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

package/src/modules/extensions/makeSlot.tsx

@@ -0,0 +1,123 @@
+import { Suspense } from 'react'
+import { ErrorBoundary } from 'react-error-boundary'
+import type { ReactNode } from 'react'
+import { useExtensions } from './ExtensionsContext'
+import type { OpaqueRenderer } from './types'
+
+/**
+ * Reported when a plugin's render throws.
+ *
+ * Deliberately not swallowed. With a `null` fallback and no report, a crashing
+ * plugin is indistinguishable from an unregistered one — the button is simply
+ * absent, in production and in tests alike. Routing it through `console.error`
+ * is what makes `getGlobalError()` in the test kit able to assert it.
+ */
+function reportSlotError(plugin: string, slot: string, error: unknown): void {
+  console.error(`[plugin:${plugin}] slot "${slot}" failed to render`, error)
+}
+
+const call = (fn: OpaqueRenderer, props: unknown): ReactNode =>
+  (fn as (p: unknown) => ReactNode)(props)
+
+/**
+ * Invokes a plugin's handler from inside its own component.
+ *
+ * Not an inline `{call(render, props)}`: that expression is evaluated while the
+ * surrounding `Slot` renders, which is BEFORE React mounts the ErrorBoundary
+ * around it. A boundary only catches errors thrown by its descendants, so an
+ * inline call escaped the boundary entirely and took the host down with it.
+ * Putting the invocation in a child component is what moves the throw inside.
+ */
+function Contribution({
+  render,
+  props,
+}: {
+  render: OpaqueRenderer
+  props: unknown
+}): ReactNode {
+  return call(render, props)
+}
+
+/**
+ * Builds the component the core renders at one leaf slot.
+ *
+ * Every registered plugin contributing to this slot renders, in array order, so
+ * two plugins can occupy the same point. Each is isolated: one plugin throwing
+ * removes only its own node.
+ *
+ * Each contribution also gets its own `Suspense`. Without it a plugin that
+ * suspends — any `useSuspenseQuery`, any lazy import — bubbles to the nearest
+ * boundary above, which for the detail card is `AppCatalogPage`'s
+ * `<Suspense fallback={null}>`; the whole card would then vanish until the
+ * plugin's data arrived.
+ */
+export function makeSlot<TProps>(slotName: string) {
+  function Slot(props: TProps): ReactNode {
+    const plugins = useExtensions()
+
+    return plugins.map((plugin) => {
+      const render = plugin.slots?.[slotName]
+      if (!render) return null
+      return (
+        <ErrorBoundary
+          key={plugin.name}
+          fallbackRender={() => null}
+          onError={(error) => reportSlotError(plugin.name, slotName, error)}
+        >
+          <Suspense fallback={null}>
+            <Contribution render={render} props={props} />
+          </Suspense>
+        </ErrorBoundary>
+      )
+    })
+  }
+  Slot.displayName = `Slot(${slotName})`
+  return Slot
+}
+
+/**
+ * Builds the component the core renders *around* a subtree.
+ *
+ * Folded right-to-left so the FIRST plugin in the array ends up outermost, which
+ * makes nesting order readable from the array itself.
+ *
+ * Note both fallbacks differ from a leaf slot's: they are the accumulated
+ * children, never `null`. A wrapper only decorates — usually by providing
+ * context — so neither a broken one nor a suspending one may blank the core
+ * subtree it was wrapping.
+ *
+ * The `Suspense` matters as much as the boundary. Without it a wrapper that
+ * suspends bubbles to the nearest boundary above, which for the detail card is
+ * `AppCatalogPage`'s `<Suspense fallback={null}>` — so one plugin fetching
+ * something would make the entire card disappear until it resolved. Falling
+ * back to `acc` instead renders the core subtree immediately, just without the
+ * decoration, and it arrives when the plugin is ready.
+ *
+ * A consequence worth stating: while suspended, descendants see no context from
+ * this wrapper. A wrapper whose children cannot cope with that should not
+ * suspend — it should render children and fetch inside its own subtree.
+ */
+export function makeWrapper<TProps>(wrapperName: string) {
+  function Wrapper(props: TProps & { children: ReactNode }): ReactNode {
+    const plugins = useExtensions()
+    const { children, ...rest } = props
+
+    return plugins.reduceRight<ReactNode>((acc, plugin) => {
+      const render = plugin.wrappers?.[wrapperName]
+      if (!render) return acc
+      return (
+        <ErrorBoundary
+          key={plugin.name}
+          fallbackRender={() => acc}
+          onError={(error) => reportSlotError(plugin.name, wrapperName, error)}
+        >
+          <Suspense fallback={acc}>
+            <Contribution render={render} props={{ ...rest, children: acc }} />
+          </Suspense>
+        </ErrorBoundary>
+      )
+    }, children)
+  }
+  Wrapper.displayName = `SlotWrapper(${wrapperName})`
+  return Wrapper
+}

package/src/modules/extensions/types.ts

@@ -0,0 +1,51 @@
+import type { ReactNode } from 'react'
+
+/**
+ * The signed-in visitor as a plugin sees them.
+ *
+ * Structural on purpose. Core's own `User` (see `modules/auth/AuthContext.tsx`)
+ * is not exported, and a plugin has no business depending on core's auth
+ * internals: it needs an identity and an admin flag, nothing more. Widening this
+ * is a deliberate API decision, not a convenience.
+ */
+export interface PluginUser {
+  email?: string | null
+  isAdmin: boolean
+}
+
+/**
+ * A renderer whose props are deliberately unknowable.
+ *
+ * This exists only to break a type cycle: the context has to hold plugins, a
+ * plugin's slot map is keyed by the composed `SlotSpec`, and `SlotSpec` is
+ * composed from the feature files that call `slotFactory` — which would need the
+ * context back. `never` in parameter position accepts every function regardless
+ * of what it takes (parameters are contravariant under `strictFunctionTypes`), so
+ * the registration stays assignable while the PUBLIC types in `index.ts` remain
+ * exact. `makeSlot` re-narrows before calling.
+ */
+export type OpaqueRenderer = (props: never) => ReactNode
+
+/**
+ * What the context stores. Consumers never build this by hand — they build an
+ * `AcPlugin` (see `index.ts`), which is assignable to it.
+ */
+export interface PluginRegistration {
+  name: string
+  slots?: Record<string, OpaqueRenderer | undefined>
+  wrappers?: Record<string, OpaqueRenderer | undefined>
+}
+
+/**
+ * Compile error naming any slot id two features both claim.
+ *
+ * `SlotSpec` is an intersection of the per-feature specs, and an intersection
+ * accepts anything: two features declaring one id would silently intersect their
+ * payloads into `A & B` — a slot nothing can satisfy. `extends` would error, but
+ * only with a generic "incompatibly declared" message. This puts the offending
+ * id in the error text.
+ */
+export type AssertDisjoint<TLeft, TRight> =
+  Extract<keyof TLeft, keyof TRight> extends never
+    ? true
+    : { DUPLICATE_SLOT_ID: Extract<keyof TLeft, keyof TRight> }

package/src/modules/gallery/Gallery.tsx

@@ -3,6 +3,7 @@ import useEmblaCarousel from 'embla-carousel-react'
 import { ChevronLeft, ChevronRight, ImageOff, X } from 'lucide-react'
 import { clamp } from 'radashi'
 import { useHotkeys } from 'react-hotkeys-hook'
+import { useDismissable } from '~/modules/dismiss/DismissStack'
 
 import { Button } from '~/ui/button'
 import { Spinner } from '~/ui/spinner'
@@ -129,23 +130,17 @@ export function Gallery({
     },
     [scrollNext, images.length],
   )
-  // Intercept Escape in fullscreen — must stopPropagation before Radix Dialog sees it
-  useEffect(() => {
-    if (!isFullscreen) return
-
-    const handleEscape = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') {
-        e.stopPropagation()
-        e.preventDefault()
-        setFullscreen(false)
-      }
-    }
-
-    document.addEventListener('keydown', handleEscape, true)
-    return () => {
-      document.removeEventListener('keydown', handleEscape, true)
-    }
-  }, [isFullscreen, setFullscreen])
+  // Escape leaves fullscreen rather than closing the gallery.
+  //
+  // This used to be a capture-phase document listener whose whole purpose was
+  // to beat Radix to the event, with the dialog above separately cancelling
+  // Radix's close by reading this component's fullscreen state through a ref.
+  // The stack makes that unnecessary: the fullscreen view is rendered after
+  // the dialog that contains it, so it is simply the top layer while it is on.
+  const fullscreenRef = useRef<HTMLDivElement>(null)
+  useDismissable(fullscreenRef, () => setFullscreen(false), {
+    enabled: isFullscreen,
+  })
 
   // Mouse wheel navigation with debouncing
   useEffect(() => {
@@ -209,6 +204,7 @@ export function Gallery({
     const imageState = imageStates[currentIndex]
     return (
       <div
+        ref={fullscreenRef}
         className="fixed inset-0 z-50 bg-background"
         role="dialog"
         aria-label="Fullscreen view"

package/src/routeTree.gen.ts

@@ -11,10 +11,10 @@
 import { Route as rootRouteImport } from './routes/__root'
 import { Route as LayoutRouteImport } from './routes/_layout'
 import { Route as LayoutIndexRouteImport } from './routes/_layout/index'
-import { Route as AuthCallbackRouteImport } from './routes/auth.callback'
-import { Route as LayoutServiceDesksRouteImport } from './routes/_layout/service-desks'
-import { Route as LayoutMcpRouteImport } from './routes/_layout/mcp'
 import { Route as LayoutLoginRouteImport } from './routes/_layout/login'
+import { Route as LayoutMcpRouteImport } from './routes/_layout/mcp'
+import { Route as LayoutServiceDesksRouteImport } from './routes/_layout/service-desks'
+import { Route as AuthCallbackRouteImport } from './routes/auth.callback'
 import { Route as LayoutAppSlugRouteImport } from './routes/_layout/app.$slug'
 import { Route as LayoutCatalogAppsIndexRouteImport } from './routes/_layout/catalog.apps.index'
 import { Route as LayoutAppSlugSubSubSlugRouteImport } from './routes/_layout/app.$slug_.sub.$subSlug'
@@ -28,14 +28,9 @@ const LayoutIndexRoute = LayoutIndexRouteImport.update({
   path: '/',
   getParentRoute: () => LayoutRoute,
 } as any)
-const AuthCallbackRoute = AuthCallbackRouteImport.update({
-  id: '/auth/callback',
-  path: '/auth/callback',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const LayoutServiceDesksRoute = LayoutServiceDesksRouteImport.update({
-  id: '/service-desks',
-  path: '/service-desks',
+const LayoutLoginRoute = LayoutLoginRouteImport.update({
+  id: '/login',
+  path: '/login',
   getParentRoute: () => LayoutRoute,
 } as any)
 const LayoutMcpRoute = LayoutMcpRouteImport.update({
@@ -43,11 +38,16 @@ const LayoutMcpRoute = LayoutMcpRouteImport.update({
   path: '/mcp',
   getParentRoute: () => LayoutRoute,
 } as any)
-const LayoutLoginRoute = LayoutLoginRouteImport.update({
-  id: '/login',
-  path: '/login',
+const LayoutServiceDesksRoute = LayoutServiceDesksRouteImport.update({
+  id: '/service-desks',
+  path: '/service-desks',
   getParentRoute: () => LayoutRoute,
 } as any)
+const AuthCallbackRoute = AuthCallbackRouteImport.update({
+  id: '/auth/callback',
+  path: '/auth/callback',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const LayoutAppSlugRoute = LayoutAppSlugRouteImport.update({
   id: '/app/$slug',
   path: '/app/$slug',
@@ -151,18 +151,11 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof LayoutIndexRouteImport
       parentRoute: typeof LayoutRoute
     }
-    '/auth/callback': {
-      id: '/auth/callback'
-      path: '/auth/callback'
-      fullPath: '/auth/callback'
-      preLoaderRoute: typeof AuthCallbackRouteImport
-      parentRoute: typeof rootRouteImport
-    }
-    '/_layout/service-desks': {
-      id: '/_layout/service-desks'
-      path: '/service-desks'
-      fullPath: '/service-desks'
-      preLoaderRoute: typeof LayoutServiceDesksRouteImport
+    '/_layout/login': {
+      id: '/_layout/login'
+      path: '/login'
+      fullPath: '/login'
+      preLoaderRoute: typeof LayoutLoginRouteImport
       parentRoute: typeof LayoutRoute
     }
     '/_layout/mcp': {
@@ -172,13 +165,20 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof LayoutMcpRouteImport
       parentRoute: typeof LayoutRoute
     }
-    '/_layout/login': {
-      id: '/_layout/login'
-      path: '/login'
-      fullPath: '/login'
-      preLoaderRoute: typeof LayoutLoginRouteImport
+    '/_layout/service-desks': {
+      id: '/_layout/service-desks'
+      path: '/service-desks'
+      fullPath: '/service-desks'
+      preLoaderRoute: typeof LayoutServiceDesksRouteImport
       parentRoute: typeof LayoutRoute
     }
+    '/auth/callback': {
+      id: '/auth/callback'
+      path: '/auth/callback'
+      fullPath: '/auth/callback'
+      preLoaderRoute: typeof AuthCallbackRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/_layout/app/$slug': {
       id: '/_layout/app/$slug'
       path: '/app/$slug'

package/src/router.ts

@@ -0,0 +1,23 @@
+/**
+ * The core's own router, on a subpath of its own — a deliberate quarantine.
+ *
+ * `createAcRouter` carries `declare module '@tanstack/react-router'` for both
+ * `Register` and (via `routeTree.gen.ts`) `FileRoutesByPath`. TypeScript
+ * collects module augmentations when it builds the PROGRAM, and `import type`
+ * still resolves the specifier — so there is no way to reference anything from
+ * that file without admitting its augmentations. Even `await import()` does it;
+ * type elision is emit-only.
+ *
+ * Two declarations of `Register.router` in one program is a hard `TS2717`, and
+ * two of `FileRoutesByPath` collapses `createFileRoute` to `path?: never`. So a
+ * deployment that composes its own route tree — core routes plus its own, and
+ * therefore its own augmentation — must never end up with this file in its
+ * program. Keeping it off the main entry's import graph is what makes that
+ * possible, and this subpath is the only published door to it.
+ *
+ * Import it if you use the core's route tree unchanged: that is the example app
+ * and the core's own test suites, each a single-`Register` program. Do NOT
+ * import it from a deployment that declares its own.
+ */
+export { createAcRouter } from './util/createAcRouter'
+export type { AcRouterInitParams } from './types/types'

package/src/routes/_layout.tsx

@@ -10,6 +10,36 @@ import { Route as AppDetailRoute } from './_layout/app.$slug'
 import { Route as SubResourceDetailRoute } from './_layout/app.$slug_.sub.$subSlug'
 import { Route as CatalogIndexRoute } from './_layout/index'
 
+/**
+ * The opt-in a deployment's own route sets to get the catalog layout:
+ *
+ *   createFileRoute('/_layout/app/$slug_/whatever')({
+ *     staticData: { acCatalogLayout: true },
+ *     component: MyRoute,
+ *   })
+ *
+ * Narrowed rather than asserted: `staticData` is a loose bag that a consumer
+ * fills, so an unexpected shape must read as "not opted in" instead of
+ * throwing inside a router-state selector.
+ */
+function wantsCatalogLayout(staticData: unknown): boolean {
+  return (
+    typeof staticData === 'object' &&
+    staticData !== null &&
+    'acCatalogLayout' in staticData &&
+    staticData.acCatalogLayout === true
+  )
+}
+
+function hasSlug(params: unknown): params is { slug: string } {
+  return (
+    typeof params === 'object' &&
+    params !== null &&
+    'slug' in params &&
+    typeof params.slug === 'string'
+  )
+}
+
 export const Route = createFileRoute('/_layout')({
   component: LayoutComponent,
 })
@@ -35,12 +65,32 @@ function LayoutComponent() {
       const params = (detailMatch ?? subMatch)?.params as
         | { slug?: string; subSlug?: string }
         | undefined
+      // A deployment composing its own route tree can put a route inside this
+      // layout, and it will not be one of the ids above — so without an opt-in
+      // it silently renders outside AppCatalogLayout with no providers, and
+      // the first hook that needs the catalog throws. `staticData` is the
+      // opt-in: the route declares that it wants the catalog layout, and the
+      // core needs to know nothing about it.
+      const optedIn = s.matches.some(
+        (m) => wantsCatalogLayout(m.staticData) === true,
+      )
+      // The slug from whichever match carries one, so a deployment's own route
+      // under /app/$slug/... opens the card it belongs to rather than dropping
+      // the user on the catalog index.
+      const slugMatch = [...s.matches].reverse().find((m) => hasSlug(m.params))
+      // One narrowing is enough: the predicate on `find` already guarantees the
+      // match it returned carries a string slug.
+      const consumerSlug = hasSlug(slugMatch?.params)
+        ? slugMatch.params.slug
+        : undefined
+
       return {
         isCatalogRoute:
           detailMatch !== undefined ||
           subMatch !== undefined ||
+          optedIn ||
           s.matches.some((m) => m.routeId === CatalogIndexRoute.id),
-        selectedSlug: params?.slug,
+        selectedSlug: params?.slug ?? consumerSlug,
         selectedSubSlug: params?.subSlug,
       }
     },

package/src/ui/components/error/DefaultErrorComponent.tsx

@@ -97,7 +97,27 @@ export function Treatment({ error, reset }: ErrorComponentProps) {
   )
 }
 
+/**
+ * What a thrown value can be relied on to have.
+ *
+ * `ErrorComponentProps.error` is `unknown`, and rightly so — `throw` accepts
+ * any value, so a route can be handed a string or a plain object. Narrowing
+ * here rather than asserting `Error` means a non-Error throw renders a useful
+ * message instead of "Cannot read properties of undefined".
+ */
+function describeThrown(error: unknown): {
+  message: string
+  stack: string | undefined
+} {
+  if (error instanceof Error) {
+    return { message: error.message, stack: error.stack }
+  }
+  return { message: String(error), stack: undefined }
+}
+
 export function DefaultErrorComponent({ error, reset }: ErrorComponentProps) {
+  const { message, stack } = describeThrown(error)
+
   return (
     <BaseErrorPage>
       <Empty role="alert">
@@ -107,7 +127,7 @@ export function DefaultErrorComponent({ error, reset }: ErrorComponentProps) {
           </EmptyMedia>
           <EmptyTitle>Ooops!</EmptyTitle>
           <EmptyDescription>
-            Error inside app-catalog occured: {<i>{error.message}</i>}
+            Error inside app-catalog occured: {<i>{message}</i>}
           </EmptyDescription>
         </EmptyHeader>
         <EmptyContent>
@@ -118,9 +138,7 @@ export function DefaultErrorComponent({ error, reset }: ErrorComponentProps) {
               'mt-8 text-center max-w-[90vw] max-h-[80vh] overflow-auto'
             }
           >
-            <pre className={'text-left mt-8 text-sm'}>
-              {<i>{error.stack}</i>}
-            </pre>
+            <pre className={'text-left mt-8 text-sm'}>{<i>{stack}</i>}</pre>
           </div>
         </EmptyContent>
       </Empty>

package/src/ui/dialog.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react'
 import * as DialogPrimitive from '@radix-ui/react-dialog'
+import { useDismissStack } from '~/modules/dismiss/DismissStack'
 import { XIcon } from 'lucide-react'
 
 import { cn } from '~/lib/utils'
@@ -48,15 +49,40 @@ function DialogContent({
   className,
   children,
   showCloseButton = true,
+  onEscapeKeyDown,
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Content> & {
   showCloseButton?: boolean
 }) {
+  const stack = useDismissStack()
+
+  /**
+   * Bridges Radix's Escape handling into the dismiss stack.
+   *
+   * Radix listens for Escape with `capture: true`, so it runs before the
+   * stack's own document listener and before every component handler. Left
+   * alone, a Radix dialog therefore closes itself even when something else is
+   * on top of it — which is the bug this whole module exists to fix, just
+   * from the other direction.
+   *
+   * So: ask the stack first. If it had a layer to dismiss, that layer was the
+   * topmost one and Radix must stand down, which `preventDefault` tells it.
+   * If the stack was empty, nothing registered an opinion and Radix closing
+   * this dialog is exactly right — which keeps every existing dialog working
+   * whether or not anyone has wired it into the stack.
+   */
+  const handleEscapeKeyDown = (event: KeyboardEvent) => {
+    onEscapeKeyDown?.(event)
+    if (event.defaultPrevented) return
+    if (stack.dismissTop()) event.preventDefault()
+  }
+
   return (
     <DialogPortal data-slot="dialog-portal">
       <DialogOverlay />
       <DialogPrimitive.Content
         data-slot="dialog-content"
+        onEscapeKeyDown={handleEscapeKeyDown}
         className={cn(
           'bg-background data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border p-6 shadow-lg duration-200 sm:max-w-lg',
           className,

package/src/ui/table.tsx

@@ -2,15 +2,58 @@ import * as React from 'react'
 
 import { cn } from '~/lib/utils'
 
-function Table({ className, ...props }: React.ComponentProps<'table'>) {
+interface TableProps extends React.ComponentProps<'table'> {
+  /**
+   * Keep the header visible while the body scrolls.
+   *
+   * The scroll has to be on the container BELOW, not on an ancestor, and that is
+   * the whole difficulty: this container sets `overflow-x: auto`, which per spec
+   * makes `overflow-y: visible` compute to `auto` as well. So it is already a
+   * scrollport on both axes, and `position: sticky` on the header resolves
+   * against it rather than against whatever ancestor has the height limit.
+   * Putting the height limit anywhere above leaves the header pinned to an
+   * element that never scrolls vertically — it scrolls away exactly as if
+   * nothing had been set.
+   *
+   * Pass the max height as `className` (e.g. `max-h-[400px]`); it lands on this
+   * container, which then both clips and scrolls.
+   */
+  stickyHeader?: boolean
+  /**
+   * The scrolling container, for a caller that virtualizes the body: the
+   * scrollport is this element, not the `<table>`, so a ref on the table
+   * would measure the wrong thing.
+   */
+  containerRef?: React.Ref<HTMLDivElement>
+}
+
+function Table({
+  className,
+  stickyHeader,
+  containerRef,
+  ...props
+}: TableProps) {
   return (
     <div
+      ref={containerRef}
       data-slot="table-container"
-      className="relative w-full overflow-x-auto"
+      className={cn(
+        'relative w-full overflow-x-auto',
+        stickyHeader && 'overflow-y-auto',
+        stickyHeader && className,
+      )}
     >
       <table
         data-slot="table"
-        className={cn('w-full caption-bottom text-sm', className)}
+        className={cn(
+          'w-full caption-bottom text-sm',
+          // The header's own bottom border does not render reliably once the
+          // row is sticky, so the separating line comes from an inset shadow on
+          // the cells instead. Opaque background, or rows show through it.
+          stickyHeader &&
+            '[&>thead]:sticky [&>thead]:top-0 [&>thead]:z-10 [&>thead>tr]:border-b-0 [&>thead_th]:bg-background [&>thead_th]:shadow-[inset_0_-1px_0_var(--border)]',
+          !stickyHeader && className,
+        )}
         {...props}
       />
     </div>