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

package/src/App.tsx

@@ -5,17 +5,44 @@ import type { QueryClient } from '@tanstack/react-query'
 import type { TRPCRouter } from '@igstack/app-catalog-backend-core'
 import type { TRPCClient } from '@trpc/client'
 import type { AcDb } from './userDb/AcDb'
-import type { createAcRouter } from './util/createAcRouter'
+import type { RegisteredRouter } from '@tanstack/react-router'
 import { TRPCProvider } from './api/infra/trpc'
 import type { UiSettings } from './types/uiSettings'
 import { UiSettingsContext } from './context/UiSettingsContext'
+import { ExtensionsContext } from './modules/extensions'
+import type { AcPlugin } from './modules/extensions'
 
 export interface AppProps {
-  router: ReturnType<typeof createAcRouter>
+  /**
+   * `RegisteredRouter`, not `ReturnType<typeof createAcRouter>`.
+   *
+   * That was a type-only import, and a type-only import still pulls the
+   * referenced file's `declare module` into the program — so naming
+   * `createAcRouter` here put the core's `Register` augmentation into every
+   * consumer, and a deployment composing its own route tree could not declare
+   * its own without `TS2717`.
+   *
+   * This widens nothing: `RegisteredRouter` resolves per program against
+   * whatever `Register` that program declared, so the core's own program gets
+   * the core's router and a deployment gets its own, each exactly typed. A
+   * router built from a different route tree is still rejected here.
+   *
+   * The one blind spot, guarded by a type test on the consumer side: with NO
+   * `Register` anywhere in a program this silently degrades to `AnyRouter`.
+   */
+  router: RegisteredRouter
   queryClient: QueryClient
   trpcClient: TRPCClient<TRPCRouter>
   db: AcDb
   uiSettings?: UiSettings
+  /**
+   * Deployment-specific UI, rendered at the slots the core declares. Optional:
+   * with none registered every slot renders nothing and the UI is identical to
+   * one with no slots at all.
+   *
+   * Must be a module-level constant — see `AcPlugin`.
+   */
+  extensions?: readonly AcPlugin[]
 }
 
 export function App({
@@ -24,13 +51,17 @@ export function App({
   trpcClient,
   db,
   uiSettings,
+  extensions,
 }: AppProps) {
   return (
     <QueryClientProvider client={queryClient}>
       <TRPCProvider queryClient={queryClient} trpcClient={trpcClient}>
         <DbProvider db={db}>
           <UiSettingsContext value={uiSettings}>
-            <RouterProvider router={router} />
+            {/* Above the router, so a slot anywhere in the tree can read it. */}
+            <ExtensionsContext value={extensions}>
+              <RouterProvider router={router} />
+            </ExtensionsContext>
           </UiSettingsContext>
         </DbProvider>
       </TRPCProvider>

package/src/__tests__/modules/appCatalog/ui/catalog/AppDetailPanel.appSwitch.test.tsx

@@ -32,7 +32,10 @@ vi.mock('~/modules/appCatalog/ui/context/AppCatalogFiltersContext', () => ({
     actions: {},
   })),
 }))
-vi.mock('~/modules/auth', () => ({ useUser: vi.fn(() => null) }))
+vi.mock('~/modules/auth', () => ({
+  useUser: vi.fn(() => null),
+  useOptionalUser: vi.fn(() => null),
+}))
 vi.mock('~/modules/appCatalog/ui/detail/FeedbackSection', () => ({
   FeedbackSection: () => <div />,
 }))

package/src/__tests__/modules/appCatalog/ui/catalog/AppDetailPanel.focus.test.tsx

@@ -17,7 +17,7 @@ vi.mock('~/modules/appCatalog/ui/components/SubResourceDetailPanel', () => ({
   SubResourceDetailPanel: () => null,
 }))
 vi.mock('~/modules/appCatalog/context/AppCatalogContext', () => ({
-  useAppCatalogContext: vi.fn(() => ({ approvalMethods: [] })),
+  useAppCatalogContext: vi.fn(() => ({ approvalMethods: [], resources: [] })),
 }))
 
 const { AppDetailPanel } =

package/src/__tests__/modules/appCatalog/ui/catalog/AppDetailPanel.widen.test.tsx

@@ -0,0 +1,53 @@
+import type { Resource } from '@igstack/app-catalog-backend-core'
+import { fireEvent, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import '@testing-library/jest-dom/vitest'
+
+vi.mock('~/modules/appCatalog/ui/detail/AppDetails', () => ({
+  AppDetails: () => <p>body</p>,
+}))
+vi.mock('~/modules/appCatalog/ui/components/SubResourceDetailPanel', () => ({
+  SubResourceDetailPanel: () => null,
+}))
+vi.mock('~/modules/appCatalog/context/AppCatalogContext', () => ({
+  useAppCatalogContext: vi.fn(() => ({ approvalMethods: [], resources: [] })),
+}))
+
+const { AppDetailPanel } =
+  await import('~/modules/appCatalog/ui/catalog/AppDetailPanel')
+
+const app = { slug: 'tracker', displayName: 'Tracker' } as Resource
+
+describe('AppDetailPanel — widen button', () => {
+  // jsdom has no layout, so the measured width is checked on the live site;
+  // here only the toggle and its cap.
+  it('toggles the card between its capped width and the full width', async () => {
+    const user = userEvent.setup()
+    render(<AppDetailPanel app={app} onClose={vi.fn()} />)
+    const dialog = screen.getByRole('dialog')
+    expect(dialog).not.toHaveClass('max-w-none')
+
+    await user.click(screen.getByRole('button', { name: 'Widen card' }))
+    expect(dialog).toHaveClass('max-w-none')
+
+    await user.click(screen.getByRole('button', { name: 'Restore width' }))
+    expect(dialog).not.toHaveClass('max-w-none')
+    expect(screen.getByRole('button', { name: 'Widen card' })).toBeVisible()
+  })
+
+  it('works from the keyboard and leaves Escape closing the card', async () => {
+    const user = userEvent.setup()
+    const onClose = vi.fn()
+    render(<AppDetailPanel app={app} onClose={onClose} />)
+
+    screen.getByRole('button', { name: 'Widen card' }).focus()
+    await user.keyboard('{Enter}')
+    expect(screen.getByRole('dialog')).toHaveClass('max-w-none')
+
+    fireEvent.keyDown(screen.getByRole('button', { name: 'Restore width' }), {
+      key: 'Escape',
+    })
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+})

package/src/__tests__/modules/appCatalog/ui/components/SubResourcesSection.adminColumn.test.tsx

@@ -0,0 +1,115 @@
+import '@testing-library/jest-dom/vitest'
+import { render, screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import type { Resource } from '@igstack/app-catalog-backend-core'
+import { ExtensionsContext } from '~/modules/extensions'
+import type { AcPlugin } from '~/modules/extensions'
+import { SubResourcesSection } from '~/modules/appCatalog/ui/components/SubResourcesSection'
+
+vi.mock('@tanstack/react-router', () => ({
+  Link: ({ children }: { children: React.ReactNode }) => (
+    <a href="#">{children}</a>
+  ),
+  useNavigate: () => vi.fn(),
+  useSearch: () => ({}),
+}))
+
+vi.mock('~/modules/appCatalog/ui/components/PersonBadge', () => ({
+  PersonBadge: () => null,
+  PersonOrGroupBadge: () => null,
+}))
+
+const parent = { slug: 'cloud', displayName: 'Cloud' } as Resource
+const children = [
+  { slug: 'acct-a', displayName: 'account-a' },
+  { slug: 'acct-b', displayName: 'account-b' },
+] as Resource[]
+
+function mount(plugins?: AcPlugin[]) {
+  return render(
+    <ExtensionsContext value={plugins}>
+      <SubResourcesSection
+        subResources={children}
+        parentSlug={parent.slug}
+        parent={parent}
+      />
+    </ExtensionsContext>,
+  )
+}
+
+const rowActionsPlugin: AcPlugin = {
+  name: 'admin-actions',
+  slots: {
+    resourceSubResourceRowActions: ({ resource }) => (
+      <button type="button">Provision {resource.displayName}</button>
+    ),
+  },
+}
+
+/**
+ * The column is layout, so unlike an ordinary slot it cannot be "rendered empty"
+ * — a header with no cells under it reads as a broken table, and the
+ * open-source build registers no plugins at all. These two tests are the parity
+ * invariant: nothing registered has to look exactly like no slot existing.
+ */
+describe('the sub-resources Admin column', () => {
+  it('is absent entirely when no plugin fills the row slot', () => {
+    mount(undefined)
+
+    expect(
+      screen.queryByRole('columnheader', { name: 'Admin' }),
+    ).not.toBeInTheDocument()
+    // Five columns, the same as before the slot existed.
+    expect(screen.getAllByRole('columnheader')).toHaveLength(5)
+  })
+
+  it('appears, with one cell per row, once a plugin fills it', () => {
+    mount([rowActionsPlugin])
+
+    expect(
+      screen.getByRole('columnheader', { name: 'Admin' }),
+    ).toBeInTheDocument()
+    expect(screen.getAllByRole('columnheader')).toHaveLength(6)
+
+    // Called once PER ROW and handed that row — the opposite shape to the
+    // header slot, which is called once with the whole list.
+    expect(
+      screen.getByRole('button', { name: 'Provision account-a' }),
+    ).toBeInTheDocument()
+    expect(
+      screen.getByRole('button', { name: 'Provision account-b' }),
+    ).toBeInTheDocument()
+  })
+
+  it('keeps the empty-state row spanning the full width', async () => {
+    // A colSpan that does not match the column count leaves a stray cell and a
+    // visibly broken border, and it only shows up when a filter matches nothing.
+    //
+    // Typed, not seeded via `initialSearch`: that prop is deliberately ignored
+    // unless it matches a child, so passing a non-matching term there shows
+    // every row and the empty state never appears.
+    const { container } = mount([rowActionsPlugin])
+    await userEvent.type(
+      screen.getByPlaceholderText(/Search resources/i),
+      'nothing-matches-this',
+    )
+
+    const empty = within(container).getByText(/No resources match your filters/)
+    expect(empty).toHaveAttribute('colspan', '6')
+  })
+
+  it('skips the column when the parent is not known', () => {
+    // The slot's payload promises a parent. Without one there is nothing to
+    // decide against, so the column is left out rather than passed a hole.
+    render(
+      <ExtensionsContext value={[rowActionsPlugin]}>
+        <SubResourcesSection subResources={children} parentSlug={parent.slug} />
+      </ExtensionsContext>,
+    )
+
+    expect(
+      screen.queryByRole('columnheader', { name: 'Admin' }),
+    ).not.toBeInTheDocument()
+  })
+})

package/src/__tests__/modules/appCatalog/ui/components/SubResourcesSection.rowMemo.test.tsx

@@ -0,0 +1,120 @@
+import '@testing-library/jest-dom/vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Resource } from '@igstack/app-catalog-backend-core'
+import { ExtensionsContext } from '~/modules/extensions'
+import type { AcPlugin } from '~/modules/extensions'
+import { SubResourcesSection } from '~/modules/appCatalog/ui/components/SubResourcesSection'
+
+vi.mock('@tanstack/react-router', () => ({
+  Link: ({ children }: { children: React.ReactNode }) => (
+    <a href="#">{children}</a>
+  ),
+  useNavigate: () => vi.fn(),
+  useSearch: () => ({}),
+}))
+
+vi.mock('~/modules/appCatalog/ui/components/PersonBadge', () => ({
+  PersonBadge: () => null,
+  PersonOrGroupBadge: () => null,
+}))
+
+const parent = { slug: 'cloud', displayName: 'Cloud' } as Resource
+const children = [
+  { slug: 'acct-a', displayName: 'alpha-account' },
+  { slug: 'acct-b', displayName: 'alpha-backup' },
+  { slug: 'acct-c', displayName: 'zeta-account' },
+] as Resource[]
+
+/**
+ * Renders per row, counted through the public plugin API.
+ *
+ * The row-actions slot is invoked once per row render, so its call count IS the
+ * row's render count — no internal instrumentation and nothing to keep in sync
+ * with the component's structure.
+ */
+let renders: Record<string, number> = {}
+
+const countingPlugin: AcPlugin = {
+  name: 'render-counter',
+  slots: {
+    resourceSubResourceRowActions: ({ resource }) => {
+      renders[resource.slug] = (renders[resource.slug] ?? 0) + 1
+      return <span>cell</span>
+    },
+  },
+}
+
+function mount() {
+  return render(
+    <ExtensionsContext value={[countingPlugin]}>
+      <SubResourcesSection
+        subResources={children}
+        parentSlug={parent.slug}
+        parent={parent}
+      />
+    </ExtensionsContext>,
+  )
+}
+
+const filterBox = () => screen.getByPlaceholderText(/Search resources/i)
+
+/**
+ * The rows are memoized, and on a large table that is a correctness-adjacent
+ * property rather than a nicety: measured on the 667-account catalog entry, a
+ * filter keystroke that changed no visible row cost ~400ms and wrote 9
+ * attributes, because every row's tree was rebuilt and diffed. Memoizing the
+ * row took the same keystroke to ~33ms.
+ *
+ * These tests pin the two things that make it work, both easy to undo by
+ * accident: props must stay referentially stable across a filter change, and
+ * the highlight must arrive as a boolean rather than as the slug (which would
+ * change a prop on EVERY row whenever the highlight moved).
+ */
+describe('sub-resource rows are memoized', () => {
+  beforeEach(() => {
+    renders = {}
+  })
+
+  it('renders each row once on mount', () => {
+    mount()
+
+    // The baseline the next test depends on. Without it, "no re-render" could
+    // pass simply because nothing ever rendered.
+    expect(renders).toEqual({ 'acct-a': 1, 'acct-b': 1, 'acct-c': 1 })
+  })
+
+  it('does not re-render a row when filtering leaves it on screen', async () => {
+    mount()
+    expect(renders['acct-a']).toBe(1)
+
+    // 'alpha' keeps rows a and b and drops c. The two survivors are the same
+    // objects from the same array, so their props are unchanged and memo should
+    // skip them entirely.
+    await userEvent.type(filterBox(), 'alpha')
+
+    expect(screen.getByText('alpha-account')).toBeInTheDocument()
+    expect(screen.getByText('alpha-backup')).toBeInTheDocument()
+    expect(screen.queryByText('zeta-account')).not.toBeInTheDocument()
+
+    // Five keystrokes, five re-renders of the section. The surviving rows must
+    // not have re-rendered even once.
+    expect(renders['acct-a']).toBe(1)
+    expect(renders['acct-b']).toBe(1)
+  })
+
+  it('re-renders a row that comes back after the filter is cleared', async () => {
+    mount()
+    await userEvent.type(filterBox(), 'alpha')
+    expect(renders['acct-c']).toBe(1)
+
+    await userEvent.clear(filterBox())
+
+    expect(screen.getByText('zeta-account')).toBeInTheDocument()
+    // Unmounted while filtered out, so it genuinely mounts again. This is the
+    // positive control: memo must not be so sticky that a row that should
+    // reappear does not.
+    expect(renders['acct-c']).toBe(2)
+  })
+})

package/src/__tests__/modules/appCatalog/ui/detail/AppDetails.background.test.tsx

@@ -49,14 +49,14 @@ const app = {
 // visit. That is what these assert now.
 describe('AppDetails — Background', () => {
   it('opens on the description, not on the history', () => {
-    render(<AppDetails app={app} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={app} />)
 
     expect(screen.getByRole('heading', { name: 'Description' })).toBeVisible()
     expect(screen.queryByRole('heading', { name: 'Background' })).toBeNull()
   })
 
   it('renders the history under Documentation', async () => {
-    render(<AppDetails app={app} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={app} />)
 
     fireEvent.click(screen.getByRole('tab', { name: /documentation/i }))
 
@@ -71,9 +71,7 @@ describe('AppDetails — Background', () => {
   // panel either way — a test that cannot fail is worse than no test.
   it('leaves no empty section when the entry has no history recorded', () => {
     const { background: _omitted, ...withoutBackground } = app
-    render(
-      <AppDetails app={withoutBackground as Resource} onClosePanel={vi.fn()} />,
-    )
+    render(<AppDetails app={withoutBackground as Resource} />)
 
     fireEvent.click(screen.getByRole('tab', { name: /documentation/i }))
 

package/src/__tests__/modules/appCatalog/ui/detail/AppDetails.doorAndTabs.test.tsx

@@ -67,7 +67,7 @@ beforeEach(() => {
 // address" — and a surface that looks pressable but is not would be worse.
 describe('the door', () => {
   it('is a link to the app when there is an address', () => {
-    render(<AppDetails app={withUrl} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={withUrl} />)
 
     const door = screen.getByRole('link', { name: /^Open Thing in a new tab/ })
     expect(door).toHaveAttribute('href', 'https://thing.example.com/portal')
@@ -79,7 +79,7 @@ describe('the door', () => {
   })
 
   it('says so plainly when the entry has no address, and offers nothing to press', () => {
-    render(<AppDetails app={withoutUrl} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={withoutUrl} />)
 
     expect(screen.getByText('No URL for this app.')).toBeVisible()
     expect(screen.queryByRole('link', { name: /in a new tab/ })).toBeNull()
@@ -90,7 +90,7 @@ describe('the tab strip', () => {
   // The reason the active tab lives in the url at all: a card is linkable
   // mid-conversation, and a maintainer's reply on the notes tab is addressable.
   it('writes the selected tab to the url', () => {
-    render(<AppDetails app={withUrl} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={withUrl} />)
 
     fireEvent.click(screen.getByRole('tab', { name: /^access/i }))
 
@@ -108,7 +108,7 @@ describe('the tab strip', () => {
    * NOT the default belongs in the url.
    */
   it('keeps the default tab out of the url', () => {
-    render(<AppDetails app={withUrl} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={withUrl} />)
 
     // Go somewhere else, then come back to the first tab.
     fireEvent.click(screen.getByRole('tab', { name: /^access/i }))
@@ -128,7 +128,7 @@ describe('the tab strip', () => {
 
   it('opens on the tab named in the url', () => {
     search.tab = 'documentation'
-    render(<AppDetails app={withUrl} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={withUrl} />)
 
     expect(screen.getByRole('tab', { name: 'Documentation' })).toHaveAttribute(
       'aria-selected',
@@ -140,7 +140,7 @@ describe('the tab strip', () => {
   // keep resolving rather than dropping the reader on the first tab.
   it('still honours a retired tab id from an older link', () => {
     search.tab = 'metadata'
-    render(<AppDetails app={withUrl} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={withUrl} />)
 
     expect(screen.getByRole('tab', { name: 'Documentation' })).toHaveAttribute(
       'aria-selected',
@@ -152,7 +152,7 @@ describe('the tab strip', () => {
   // rendering a card with no panel at all.
   it('falls back to the first tab when the url names one this entry lacks', () => {
     search.tab = 'resources'
-    render(<AppDetails app={withUrl} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={withUrl} />)
 
     expect(screen.queryByRole('tab', { name: /resources/i })).toBeNull()
     expect(screen.getByRole('tab', { name: 'Overview' })).toHaveAttribute(
@@ -164,7 +164,7 @@ describe('the tab strip', () => {
 
   // Per the tablist pattern: one stop in the tab order, arrows move within.
   it('moves between tabs with the arrow keys', () => {
-    render(<AppDetails app={withUrl} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={withUrl} />)
 
     const overview = screen.getByRole('tab', { name: 'Overview' })
     expect(overview).toHaveAttribute('tabindex', '0')
@@ -180,7 +180,7 @@ describe('the tab strip', () => {
   })
 
   it('wraps from the first tab to the last', () => {
-    render(<AppDetails app={withUrl} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={withUrl} />)
 
     fireEvent.keyDown(screen.getByRole('tab', { name: 'Overview' }), {
       key: 'ArrowLeft',

package/src/__tests__/modules/appCatalog/ui/detail/AppDetails.escape.test.tsx

@@ -1,5 +1,6 @@
 import type { Resource } from '@igstack/app-catalog-backend-core'
 import { fireEvent, render, screen } from '@testing-library/react'
+import { useRef } from 'react'
 import { describe, expect, it, vi } from 'vitest'
 import '@testing-library/jest-dom/vitest'
 
@@ -33,6 +34,24 @@ vi.mock('~/modules/appCatalog/ui/detail/FeedbackSection', () => ({
 }))
 
 const { AppDetails } = await import('~/modules/appCatalog/ui/detail/AppDetails')
+const { useDismissable } = await import('~/modules/dismiss/DismissStack')
+
+/** Stands in for the card: the layer AppDetails is rendered inside. */
+function CardLayer({
+  onClose,
+  children,
+}: {
+  onClose: () => void
+  children: React.ReactNode
+}) {
+  const ref = useRef<HTMLDivElement>(null)
+  useDismissable(ref, onClose)
+  return (
+    <div ref={ref} role="dialog" aria-label="card">
+      {children}
+    </div>
+  )
+}
 
 const app = {
   id: 'tracker',
@@ -51,17 +70,24 @@ const app = {
 // The card takes focus on open so Esc closes it. The Quick Jump field takes that
 // focus instead — so Esc has to keep working from inside the field, or the
 // feature costs the keyboard its way out.
+//
+// Escape itself belongs to the card's layer, not to AppDetails. What this pins
+// is that the field does not CLAIM it: a field that called preventDefault on
+// Escape would keep it from the layer, and the card would stop closing.
 describe('AppDetails — Esc from the quick jump field', () => {
-  it('closes the panel', () => {
-    const onClosePanel = vi.fn()
-    render(<AppDetails app={app} onClosePanel={onClosePanel} />)
+  it('reaches the layer the details are rendered in', () => {
+    const onClose = vi.fn()
+    render(
+      <CardLayer onClose={onClose}>
+        <AppDetails app={app} />
+      </CardLayer>,
+    )
 
-    // `code` as well as `key`: the hotkey library matches on the physical code.
     fireEvent.keyDown(screen.getByLabelText('case id'), {
       key: 'Escape',
       code: 'Escape',
     })
 
-    expect(onClosePanel).toHaveBeenCalled()
+    expect(onClose).toHaveBeenCalledTimes(1)
   })
 })

package/src/__tests__/modules/appCatalog/ui/detail/AppDetails.sectionOrder.test.tsx

@@ -55,7 +55,7 @@ const app = {
 // that would have silently regressed if this test had simply been deleted.
 describe('AppDetails — section order', () => {
   it('opens on the description, with the access instructions not yet mounted', () => {
-    render(<AppDetails app={app} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={app} />)
 
     expect(screen.getByRole('heading', { name: 'Description' })).toBeVisible()
     expect(
@@ -64,7 +64,7 @@ describe('AppDetails — section order', () => {
   })
 
   it('reaches the access instructions from its own tab', () => {
-    render(<AppDetails app={app} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={app} />)
 
     fireEvent.click(screen.getByRole('tab', { name: /^access/i }))
 
@@ -76,7 +76,7 @@ describe('AppDetails — section order', () => {
   // approval method registered there is nothing to name, and claiming a route
   // we cannot describe is the failure the label exists to prevent.
   it('names the access route in the tab', () => {
-    render(<AppDetails app={app} onClosePanel={vi.fn()} />)
+    render(<AppDetails app={app} />)
 
     expect(
       screen.getByRole('tab', { name: /access — not documented/i }),