@igstack/app-catalog-frontend-core 6.6.0 → 6.7.0

package/src/__tests__/modules/dismiss/DismissStack.test.tsx

@@ -0,0 +1,330 @@
+import '@testing-library/jest-dom/vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import { useRef, useState } from 'react'
+import {
+  DismissStackProvider,
+  useDismissable,
+} from '~/modules/dismiss/DismissStack'
+
+/**
+ * The contract every overlay in the app now depends on, so it is worth pinning
+ * precisely. Each case here corresponds to a way the old hand-rolled Escape
+ * handling got it wrong.
+ */
+
+function Layer({
+  name,
+  onDismiss,
+  enabled,
+  children,
+}: {
+  name: string
+  onDismiss: () => void
+  enabled?: boolean
+  children?: React.ReactNode
+}) {
+  const ref = useRef<HTMLDivElement>(null)
+  useDismissable(
+    ref,
+    onDismiss,
+    enabled === undefined ? undefined : { enabled },
+  )
+  return (
+    <div ref={ref} data-testid={`layer-${name}`}>
+      {name}
+      {children}
+    </div>
+  )
+}
+
+const esc = () => userEvent.keyboard('{Escape}')
+
+describe('the dismiss stack', () => {
+  it('gives Escape to the layer registered last', async () => {
+    const outer = vi.fn()
+    const inner = vi.fn()
+    render(
+      <>
+        <Layer name="outer" onDismiss={outer} />
+        <Layer name="inner" onDismiss={inner} />
+      </>,
+    )
+
+    await esc()
+
+    // The whole point: the thing opened last is the thing Escape takes away.
+    expect(inner).toHaveBeenCalledTimes(1)
+    expect(outer).not.toHaveBeenCalled()
+  })
+
+  it('dismisses one layer per keypress, never two at once', async () => {
+    // The reported bug: one Escape closed the dialog AND the card under it,
+    // landing the user on the home page instead of back on the table.
+    const outer = vi.fn()
+    const inner = vi.fn()
+    render(
+      <>
+        <Layer name="outer" onDismiss={outer} />
+        <Layer name="inner" onDismiss={inner} />
+      </>,
+    )
+
+    await esc()
+    expect(inner).toHaveBeenCalledTimes(1)
+    expect(outer).not.toHaveBeenCalled()
+  })
+
+  it('falls back to the layer below once the top one unmounts', async () => {
+    function Host() {
+      const [innerOpen, setInnerOpen] = useState(true)
+      return (
+        <>
+          <Layer name="outer" onDismiss={outer} />
+          {innerOpen && (
+            <Layer name="inner" onDismiss={() => setInnerOpen(false)} />
+          )}
+        </>
+      )
+    }
+    const outer = vi.fn()
+    render(<Host />)
+
+    await esc()
+    expect(screen.queryByTestId('layer-inner')).not.toBeInTheDocument()
+    expect(outer).not.toHaveBeenCalled()
+
+    // Escape again, and the layer underneath gets it — "previous", one step at
+    // a time, which is what makes nesting work without anyone coordinating.
+    await esc()
+    expect(outer).toHaveBeenCalledTimes(1)
+  })
+
+  it('skips a disabled layer and asks the one beneath it', async () => {
+    const outer = vi.fn()
+    const closed = vi.fn()
+    render(
+      <>
+        <Layer name="outer" onDismiss={outer} />
+        <Layer name="closed" onDismiss={closed} enabled={false} />
+      </>,
+    )
+
+    await esc()
+
+    // A registered-but-closed popover must not swallow Escape. Staying
+    // registered while disabled is what keeps stack order stable across a
+    // toggle, so this case has to work.
+    expect(closed).not.toHaveBeenCalled()
+    expect(outer).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not move a layer to the top just because it re-rendered', async () => {
+    // The subtle one. If the hook re-registered whenever the callback identity
+    // changed, the last component to RE-RENDER would win Escape instead of the
+    // last one to OPEN — so an unrelated state change elsewhere would silently
+    // redirect Escape.
+    const outer = vi.fn()
+    const inner = vi.fn()
+    function Host() {
+      const [n, setN] = useState(0)
+      return (
+        <>
+          {/* A fresh closure every render, on the BOTTOM layer. */}
+          <Layer name="outer" onDismiss={() => outer(n)} />
+          <Layer name="inner" onDismiss={() => inner(n)} />
+          <button type="button" onClick={() => setN((v) => v + 1)}>
+            bump
+          </button>
+        </>
+      )
+    }
+    render(<Host />)
+
+    await userEvent.click(screen.getByRole('button', { name: 'bump' }))
+    await esc()
+
+    expect(inner).toHaveBeenCalledTimes(1)
+    expect(outer).not.toHaveBeenCalled()
+    // And the refreshed closure is the one that ran, not the stale one from
+    // the first render.
+    expect(inner).toHaveBeenCalledWith(1)
+  })
+
+  it('leaves Escape alone when a closer handler already claimed it', async () => {
+    // An input that uses Escape for itself — cancelling an edit — is more
+    // specific than any layer containing it, so the stack honours
+    // preventDefault instead of overriding it.
+    const layer = vi.fn()
+    render(
+      <Layer name="outer" onDismiss={layer}>
+        <input
+          aria-label="field"
+          onKeyDown={(e) => {
+            if (e.key === 'Escape') e.preventDefault()
+          }}
+        />
+      </Layer>,
+    )
+
+    await userEvent.click(screen.getByLabelText('field'))
+    await esc()
+
+    expect(layer).not.toHaveBeenCalled()
+  })
+
+  it('does nothing when no layer is registered', async () => {
+    // Escape has to stay available to whatever else wants it — the search
+    // results list clears the query on Escape when no overlay is open.
+    const onKeyDown = vi.fn()
+    render(<div onKeyDown={onKeyDown}>no layers</div>)
+
+    await esc()
+
+    expect(onKeyDown).not.toHaveBeenCalled() // nothing focused inside
+  })
+
+  it('works without a provider, and scopes to one when given', async () => {
+    // The hook deliberately works unwrapped: a hook that silently did nothing
+    // outside a provider is the same class of bug this module deletes.
+    const bare = vi.fn()
+    const { unmount } = render(<Layer name="bare" onDismiss={bare} />)
+    await esc()
+    expect(bare).toHaveBeenCalledTimes(1)
+    unmount()
+
+    const scoped = vi.fn()
+    render(
+      <DismissStackProvider>
+        <Layer name="scoped" onDismiss={scoped} />
+      </DismissStackProvider>,
+    )
+    await esc()
+    expect(scoped).toHaveBeenCalledTimes(1)
+  })
+
+  it('removes its key listener once the last layer unmounts', async () => {
+    const add = vi.spyOn(document, 'addEventListener')
+    const remove = vi.spyOn(document, 'removeEventListener')
+    const onDismiss = vi.fn()
+
+    const { unmount } = render(<Layer name="only" onDismiss={onDismiss} />)
+    // Bubble phase, deliberately: a capture listener runs before every
+    // component handler, which would stop a field from keeping Escape for
+    // itself.
+    expect(add).toHaveBeenCalledWith('keydown', expect.any(Function))
+
+    unmount()
+    expect(remove).toHaveBeenCalledWith('keydown', expect.any(Function))
+
+    // And really gone: an app with nothing open has no global key handler.
+    await esc()
+    expect(onDismiss).not.toHaveBeenCalled()
+
+    add.mockRestore()
+    remove.mockRestore()
+  })
+
+  it('gives Escape to a nested layer that opens later, not its container', async () => {
+    // The regression this ordering exists for. React runs a CHILD's effects
+    // before its parent's, so an overlay nested inside another registers
+    // FIRST — and with registration-order LIFO the container looked like the
+    // newer layer. Pressing Escape in the screenshot viewer therefore closed
+    // the card underneath it and left the catalog index.
+    const closeCard = vi.fn()
+    function Host() {
+      const [viewerOpen, setViewerOpen] = useState(false)
+      return (
+        <Layer name="card" onDismiss={closeCard}>
+          {/* Mounted from the start and merely disabled, exactly as the
+              screenshot dialog is, so it registers before its container. */}
+          <Layer
+            name="viewer"
+            onDismiss={() => setViewerOpen(false)}
+            enabled={viewerOpen}
+          />
+          <button type="button" onClick={() => setViewerOpen(true)}>
+            open viewer
+          </button>
+        </Layer>
+      )
+    }
+    render(<Host />)
+
+    await userEvent.click(screen.getByRole('button', { name: 'open viewer' }))
+    await esc()
+
+    // The viewer closed; the card is still there.
+    expect(closeCard).not.toHaveBeenCalled()
+
+    // And now the card gets it.
+    await esc()
+    expect(closeCard).toHaveBeenCalledTimes(1)
+  })
+
+  it('ranks by position on screen, not by when a layer mounted', async () => {
+    // The cold-deep-link shape. The dialog's route resolves first; the card
+    // it sits over waits for the catalog and mounts LATER, while still being
+    // rendered EARLIER in the document. Ranking by mount or activation time
+    // made the card "newer", so Escape closed it first.
+    const closeCard = vi.fn()
+    const closeDialog = vi.fn()
+    function Host() {
+      const [catalogLoaded, setCatalogLoaded] = useState(false)
+      return (
+        <>
+          {catalogLoaded && <Layer name="card" onDismiss={closeCard} />}
+          <Layer name="dialog" onDismiss={closeDialog} />
+          <button type="button" onClick={() => setCatalogLoaded(true)}>
+            catalog arrives
+          </button>
+        </>
+      )
+    }
+    render(<Host />)
+    await userEvent.click(
+      screen.getByRole('button', { name: 'catalog arrives' }),
+    )
+
+    await esc()
+
+    expect(closeDialog).toHaveBeenCalledTimes(1)
+    expect(closeCard).not.toHaveBeenCalled()
+  })
+
+  it('hands focus to the layer beneath when the top one closes', async () => {
+    // Otherwise the caret falls to <body> and the next Tab walks whatever is
+    // behind every overlay.
+    function FocusableLayer({
+      name,
+      onDismiss,
+    }: {
+      name: string
+      onDismiss: () => void
+    }) {
+      const ref = useRef<HTMLDivElement>(null)
+      useDismissable(ref, onDismiss)
+      return <div ref={ref} tabIndex={-1} data-testid={`layer-${name}`} />
+    }
+    function Host() {
+      const [open, setOpen] = useState(true)
+      return (
+        <>
+          <FocusableLayer name="card" onDismiss={() => {}} />
+          {open && (
+            <FocusableLayer name="dialog" onDismiss={() => setOpen(false)} />
+          )}
+        </>
+      )
+    }
+    render(<Host />)
+    screen.getByTestId('layer-dialog').focus()
+
+    await esc()
+    // The handback is queued after the unmount, so let it run.
+    await new Promise((r) => setTimeout(r, 0))
+
+    expect(document.activeElement).toBe(screen.getByTestId('layer-card'))
+  })
+})

package/src/__tests__/modules/extensions/slots.test.tsx

@@ -0,0 +1,252 @@
+import '@testing-library/jest-dom/vitest'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import type { ReactNode } from 'react'
+import type { Resource } from '@igstack/app-catalog-backend-core'
+import {
+  ExtensionsContext,
+  ResourceDetailAccessActions,
+  ResourceDetailProvider,
+} from '~/modules/extensions'
+import type { AcPlugin } from '~/modules/extensions'
+
+const resource = { slug: 'tracker', displayName: 'Tracker' } as Resource
+const ctx = { resource, subResources: [], user: null }
+
+function mount(plugins: AcPlugin[] | undefined, children: ReactNode) {
+  return render(
+    <ExtensionsContext value={plugins}>{children}</ExtensionsContext>,
+  )
+}
+
+describe('leaf slot', () => {
+  it('renders nothing when no plugin is registered', () => {
+    // The open-source default. Slots are additive: with none registered the
+    // output must be indistinguishable from having no slot at all.
+    const { container } = mount(
+      undefined,
+      <ResourceDetailAccessActions {...ctx} />,
+    )
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('renders every contributor, in array order', () => {
+    const plugins: AcPlugin[] = [
+      {
+        name: 'first',
+        slots: { resourceDetailAccessActions: () => <b>one</b> },
+      },
+      {
+        name: 'second',
+        slots: { resourceDetailAccessActions: () => <b>two</b> },
+      },
+    ]
+    mount(plugins, <ResourceDetailAccessActions {...ctx} />)
+    // Both render — the case a keyed map could not express, since the second
+    // registration would have overwritten the first.
+    expect(screen.getAllByText(/one|two/).map((n) => n.textContent)).toEqual([
+      'one',
+      'two',
+    ])
+  })
+
+  it('hands the payload to the handler', () => {
+    const seen = vi.fn()
+    mount(
+      [
+        {
+          name: 'spy',
+          slots: {
+            resourceDetailAccessActions: (props) => {
+              seen(props.resource.slug)
+              return null
+            },
+          },
+        },
+      ],
+      <ResourceDetailAccessActions {...ctx} />,
+    )
+    expect(seen).toHaveBeenCalledWith('tracker')
+  })
+
+  it('contains a crashing plugin and reports it', () => {
+    // A crash must not reach the host, and must not be silent either: with a
+    // null fallback and no report it is indistinguishable from "not registered".
+    const onError = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const plugins: AcPlugin[] = [
+      {
+        name: 'boom',
+        slots: {
+          resourceDetailAccessActions: () => {
+            throw new Error('plugin exploded')
+          },
+        },
+      },
+      {
+        name: 'ok',
+        slots: { resourceDetailAccessActions: () => <b>survivor</b> },
+      },
+    ]
+    mount(plugins, <ResourceDetailAccessActions {...ctx} />)
+
+    expect(screen.getByText('survivor')).toBeInTheDocument()
+    expect(
+      onError.mock.calls.some((call) =>
+        call.some(
+          (arg) => typeof arg === 'string' && arg.includes('[plugin:boom]'),
+        ),
+      ),
+    ).toBe(true)
+    onError.mockRestore()
+  })
+})
+
+describe('wrapper slot', () => {
+  it('passes children through untouched when no plugin is registered', () => {
+    mount(
+      undefined,
+      <ResourceDetailProvider resource={resource}>
+        <b>core content</b>
+      </ResourceDetailProvider>,
+    )
+    expect(screen.getByText('core content')).toBeInTheDocument()
+  })
+
+  it('nests wrappers with the first plugin outermost', () => {
+    const plugins: AcPlugin[] = [
+      {
+        name: 'outer',
+        wrappers: {
+          resourceDetailProvider: ({ children }) => (
+            <div data-testid="outer">{children}</div>
+          ),
+        },
+      },
+      {
+        name: 'inner',
+        wrappers: {
+          resourceDetailProvider: ({ children }) => (
+            <div data-testid="inner">{children}</div>
+          ),
+        },
+      },
+    ]
+    mount(
+      plugins,
+      <ResourceDetailProvider resource={resource}>
+        <b>leaf</b>
+      </ResourceDetailProvider>,
+    )
+    // Array order reads as nesting order: first declared ends up outermost.
+    expect(
+      screen.getByTestId('outer').querySelector('[data-testid="inner"]'),
+    ).not.toBeNull()
+  })
+
+  it('keeps core content when a wrapper crashes', () => {
+    // The fallback difference that matters: a leaf disappears, but a wrapper
+    // only decorated the subtree, so the subtree must survive its failure.
+    const onError = vi.spyOn(console, 'error').mockImplementation(() => {})
+    mount(
+      [
+        {
+          name: 'broken-wrapper',
+          wrappers: {
+            resourceDetailProvider: () => {
+              throw new Error('wrapper exploded')
+            },
+          },
+        },
+      ],
+      <ResourceDetailProvider resource={resource}>
+        <b>core content</b>
+      </ResourceDetailProvider>,
+    )
+    expect(screen.getByText('core content')).toBeInTheDocument()
+    onError.mockRestore()
+  })
+})
+
+describe('a suspending contribution', () => {
+  /** Suspends once, then resolves — a stand-in for any lazy import or query. */
+  function makeSuspender(label: string) {
+    let resolved = false
+    let release!: () => void
+    const ready = new Promise<void>((r) => {
+      release = () => {
+        resolved = true
+        r()
+      }
+    })
+    // Renders its children, so the wrapper case below is a faithful wrapper
+    // rather than something that merely replaces the subtree.
+    function Suspender({ children }: { children?: ReactNode }) {
+      if (!resolved) throw ready
+      return (
+        <b>
+          {label}
+          {children}
+        </b>
+      )
+    }
+    return { Suspender, release }
+  }
+
+  it('does not blank the host while a leaf slot suspends', async () => {
+    const { Suspender, release } = makeSuspender('arrived')
+    const plugins: AcPlugin[] = [
+      {
+        name: 'slow',
+        slots: { resourceDetailAccessActions: () => <Suspender /> },
+      },
+    ]
+
+    mount(
+      plugins,
+      <div>
+        <span>host</span>
+        <ResourceDetailAccessActions {...ctx} />
+      </div>,
+    )
+
+    // Contained: the host is still there, only the plugin's region is empty.
+    expect(screen.getByText('host')).toBeInTheDocument()
+    expect(screen.queryByText('arrived')).not.toBeInTheDocument()
+
+    release()
+    expect(await screen.findByText('arrived')).toBeInTheDocument()
+    expect(screen.getByText('host')).toBeInTheDocument()
+  })
+
+  it('keeps a wrapper’s children visible while the wrapper suspends', async () => {
+    // The asymmetry that matters: a wrapper only decorates, so suspending must
+    // not take the core subtree it was wrapping off the screen. Without its own
+    // Suspense this bubbles to the detail card's `fallback={null}` and the whole
+    // card disappears until the plugin resolves.
+    const { Suspender, release } = makeSuspender('decorated')
+    const plugins: AcPlugin[] = [
+      {
+        name: 'slow-wrapper',
+        wrappers: {
+          resourceDetailProvider: ({ children }) => (
+            <Suspender>{children}</Suspender>
+          ),
+        },
+      },
+    ]
+
+    mount(
+      plugins,
+      <ResourceDetailProvider resource={resource}>
+        <span>core subtree</span>
+      </ResourceDetailProvider>,
+    )
+
+    expect(screen.getByText('core subtree')).toBeInTheDocument()
+
+    release()
+    expect(await screen.findByText('decorated')).toBeInTheDocument()
+    // Still there once the wrapper arrives — now actually wrapped by it.
+    expect(screen.getByText('core subtree')).toBeInTheDocument()
+  })
+})

package/src/__tests__/publicEntryResolves.test.ts

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const srcDir = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+/**
+ * Re-exporting from a bare directory silently strips the types for consumers.
+ *
+ * `export type { X } from './modules/foo'` emits `from './modules/foo.js'` into
+ * `dist/esm/index.d.ts`, but the build writes `dist/esm/modules/foo/index.d.ts`
+ * — so the specifier resolves to nothing. Because every consumer runs with
+ * `skipLibCheck`, the unresolved import raises no error anywhere: the types
+ * quietly degrade to `any`, and a consumer's own typecheck passes while
+ * accepting absolutely anything.
+ *
+ * Measured, not theoretical: `keyof SlotSpec` accepted an arbitrary string from
+ * a consuming app, and `PwaAutoUpdateOptions` had been shipping as `any` for
+ * however long the export had existed. Writing `./modules/foo/index` fixes it.
+ *
+ * This checks the source rather than the build output so it runs without one.
+ */
+const ENTRY_POINTS = ['index.tsx', 'internal.ts']
+
+function relativeSpecifiers(source: string): string[] {
+  return [...source.matchAll(/from\s+'(\.[^']+)'/g)]
+    .map((match) => match[1])
+    .filter((specifier): specifier is string => specifier !== undefined)
+}
+
+describe.each(ENTRY_POINTS)('public entry %s', (entry) => {
+  const source = readFileSync(resolve(srcDir, entry), 'utf8')
+
+  it('re-exports no bare directory', () => {
+    const offenders = relativeSpecifiers(source).filter((specifier) => {
+      const target = resolve(srcDir, specifier)
+      return existsSync(target) && statSync(target).isDirectory()
+    })
+
+    // Thrown rather than passed to expect() as a message: the repo's
+    // vitest/valid-expect rule allows only one argument, and a bare
+    // "expected [x] to equal []" would not explain why it matters.
+    if (offenders.length > 0) {
+      throw new Error(
+        `Bare directory re-export(s) in src/${entry}: ${offenders.join(', ')}.\n` +
+          'Emitted as "<dir>.js", which has no .d.ts, so every type behind it\n' +
+          'becomes `any` for consumers without any error. Append "/index".',
+      )
+    }
+    expect(offenders).toEqual([])
+  })
+
+  it('resolves every relative specifier to a real module', () => {
+    const unresolved = relativeSpecifiers(source).filter((specifier) => {
+      const base = resolve(srcDir, specifier.replace(/\.js$/, ''))
+      return !['', '.ts', '.tsx', '.d.ts'].some((ext) =>
+        existsSync(`${base}${ext}`),
+      )
+    })
+    expect(unresolved).toEqual([])
+  })
+})

package/src/appPropsFactory.ts

@@ -2,13 +2,33 @@ import { createBrowserHistory } from '@tanstack/react-router'
 import { createTRPCClient, httpBatchLink } from '@trpc/client'
 import { AcDb } from './userDb/AcDb'
 import type { TRPCRouter } from '@igstack/app-catalog-backend-core'
+import type { RegisteredRouter } from '@tanstack/react-router'
 import type { AppProps } from './App'
 import type { AcPlugin } from './modules/pluginCore/types'
+import type { AcRouterInitParams } from './types/types'
 import { createQueryClient } from './api/infra/createQueryClient'
-import { createAcRouter } from './util/createAcRouter'
+
+export interface AppPropsFactoryOptions {
+  /**
+   * How to build the router.
+   *
+   * Injected rather than imported, because the ROUTE TREE belongs to the
+   * deployment. A deployment that composes its own tree declares its own
+   * `declare module … Register`, and importing the core's `createAcRouter`
+   * here would put the core's competing augmentation into that program — a
+   * hard `TS2717`, and `import type` would not help: augmentations are
+   * collected when the program is built.
+   *
+   * Using the core's tree unchanged? Pass `createAcRouter` from
+   * `@igstack/app-catalog-frontend-core/router`.
+   */
+  createRouter: (init: AcRouterInitParams) => RegisteredRouter
+}
 
 // registerSW();
-export function appPropsFactory(): AppProps {
+export function appPropsFactory({
+  createRouter,
+}: AppPropsFactoryOptions): AppProps {
   const trpcClient = createTRPCClient<TRPCRouter>({
     links: [
       httpBatchLink({
@@ -22,7 +42,7 @@ export function appPropsFactory(): AppProps {
   const plugins: AcPlugin[] = [
     // Future plugins can be added here
   ]
-  const router = createAcRouter({
+  const router = createRouter({
     history: createBrowserHistory(),
     context: {
       queryClient,