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

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,

package/src/index.tsx

@@ -1,4 +1,8 @@
 export { appPropsFactory } from './appPropsFactory.js'
+export type { AppPropsFactoryOptions } from './appPropsFactory.js'
+// What a deployment's own router factory is handed. Safe on this entry: it
+// names no route tree, so it carries no `declare module` with it.
+export type { AcRouterContext, AcRouterInitParams } from './types/types'
 export { App } from './App'
 export type { AppProps } from './App'
 export type { AreaIcon, AreasSettings, UiSettings } from './types/uiSettings'
@@ -6,5 +10,31 @@ export {
   DAY_TO_DAY_AREA_KEY,
   DAY_TO_DAY_TAG,
 } from './modules/appCatalog/utils/areaGrouping'
-export { PwaAutoUpdateProvider, usePwaAutoUpdate } from './modules/pwa'
-export type { PwaAutoUpdateOptions, PwaUpdateHandle } from './modules/pwa'
+export { PwaAutoUpdateProvider, usePwaAutoUpdate } from './modules/pwa/index'
+export type { PwaAutoUpdateOptions, PwaUpdateHandle } from './modules/pwa/index'
+
+// ── Plugins ───────────────────────────────────────────────────────────────────
+// A deployment registers these via <App extensions={[...]} />. `Resource` is
+// re-exported because the slot payloads name it: without that, a consumer would
+// have to depend on backend-core directly just to type a handler.
+export type {
+  AcPlugin,
+  PluginSlots,
+  PluginWrappers,
+  PluginUser,
+  SlotSpec,
+  WrapperSpec,
+} from './modules/extensions/index'
+export type { Resource } from '@igstack/app-catalog-backend-core'
+// For a deployment that owns its own routes: resolving its own path params
+// against the catalog. Narrow on purpose — see the hook's own comment.
+export { useCatalogResources } from './modules/appCatalog/context/AppCatalogContext'
+
+/**
+ * Escape handling, for a deployment's own overlays.
+ *
+ * Call `useDismissable(close)` in any overlay and Escape dismisses whatever
+ * opened last, across core and deployment layers alike. Nothing needs to know
+ * what else is on screen.
+ */
+export { useDismissable, useDismissStack } from './modules/dismiss/DismissStack'

package/src/internal.ts

@@ -5,11 +5,17 @@
  *
  * No stability guarantees: this moves in lockstep with
  * `@igstack/app-catalog-test-kit`, which is its only intended consumer.
+ *
+ * Must stay free of `createAcRouter`. The test kit runs inside a DEPLOYMENT's
+ * test program, which declares its own `Register` augmentation for its own
+ * route tree — and re-exporting `createAcRouter` here would drag the core's
+ * competing augmentation in with it, which is a hard `TS2717`. The router
+ * factory is injected instead; see `setRouterFactory` in the test kit. The
+ * core's own router is published separately, at `/router`.
  */
 export { App } from './App'
 export type { AppProps } from './App'
 export { AcDb, dbCacheDbKeys } from './userDb/AcDb'
-export { createAcRouter } from './util/createAcRouter'
 export {
   SEARCH_STORAGE_KEY,
   clearSessionState,

package/src/modules/appCatalog/context/AppCatalogContext.tsx

@@ -83,3 +83,24 @@ export function useAppCatalogContext(): AppCatalogContextIface {
   }
   return context
 }
+
+/**
+ * The catalog, for a deployment that owns its own routes.
+ *
+ * A deployment composing its own route tree has to resolve its own path params
+ * against the catalog — `/app/$slug/…/$account` means nothing until `$account`
+ * is matched to a resource. It needs the resources to do that, and the loading
+ * flag to tell "still fetching" from "no such resource", which is the
+ * difference between a spinner and a redirect.
+ *
+ * Deliberately narrower than `useAppCatalogContext`: persons, groups, tags and
+ * approval methods are the core's own rendering concerns, and publishing them
+ * would make every one of them part of the supported surface.
+ */
+export function useCatalogResources(): {
+  resources: Resource[]
+  isLoading: boolean
+} {
+  const { resources, isLoadingApps } = useAppCatalogContext()
+  return { resources, isLoading: isLoadingApps }
+}

package/src/modules/appCatalog/ui/catalog/AppCatalogGrid.tsx

@@ -1,6 +1,14 @@
 import type { Resource } from '@igstack/app-catalog-backend-core'
 import { ArrowUpRight, Search, X } from 'lucide-react'
-import { use, useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  use,
+  useCallback,
+  useDeferredValue,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
 import { cn } from '~/lib/utils'
 import { useAppClickHistory } from '../../hooks/useAppClickHistory'
 import { markdownToPlainText } from '../../utils/markdownToPlainText'
@@ -697,7 +705,29 @@ export function AppCatalogGrid({
   // on the areas most people need. Within an area, alpha (from browse).
   const browseGroups = useMemo(() => groupByArea(browse), [browse])
 
-  const isSearching = searchValue.trim() !== ''
+  /**
+   * The query the RESULTS are computed from; the input stays on `searchValue`.
+   *
+   * Searching rebuilds the ranked result set from scratch on every keystroke —
+   * `searchResources` rebuilds its parent index, scores every resource across
+   * 15 tiers and sorts — and the first keystroke additionally unmounts the
+   * whole discovery spine while the last one remounts it. Doing that between
+   * the keypress and the caret moving is what made typing stutter. Deferring
+   * hands React permission to render the typed character first and the list
+   * after, abandoning a superseded pass instead of finishing one per
+   * character.
+   *
+   * `isSearching` is derived from the DEFERRED value on purpose. Driving the
+   * results/spine swap from the live value instead tears the frame: the spine
+   * unmounts immediately while the results are still a render behind, so the
+   * page blanks for a frame on the first keystroke. Everything the user sees
+   * for a given query — the swap, the rows and the highlight marks — comes off
+   * one value, so they can never disagree.
+   */
+  const deferredSearch = useDeferredValue(searchValue)
+  const isSearching = deferredSearch.trim() !== ''
+  // True while the list is a render behind the box, used only to dim it.
+  const isSearchPending = searchValue !== deferredSearch
   const searchRef = useRef<HTMLInputElement>(null)
 
   // ⌘K / Ctrl+K focuses the hero search box from anywhere on the page.
@@ -764,16 +794,26 @@ export function AppCatalogGrid({
           search box. The discovery spine below is what gets replaced — the
           shell, hero and search box stay put, so typing never shifts layout. */}
       {isSearching && (
-        <SearchResultsList
-          apps={allResources ?? apps}
-          searchValue={searchValue}
-          onAppClick={onAppClick}
-          onSubClick={onSubClick}
-          onLaunch={onLaunch}
-          onClear={() => onSearchChange('')}
-          keyboardEnabled={!detailOpen}
-          selectedSubSlug={selectedSubSlug}
-        />
+        <div
+          className={`transition-opacity ${
+            isSearchPending ? 'opacity-60' : ''
+          }`}
+          aria-busy={isSearchPending || undefined}
+        >
+          <SearchResultsList
+            apps={allResources ?? apps}
+            // Deferred, not live: `Highlight` inside marks the matched text, and
+            // feeding it a newer query than the rows were built from highlights
+            // substrings the rows do not contain.
+            searchValue={deferredSearch}
+            onAppClick={onAppClick}
+            onSubClick={onSubClick}
+            onLaunch={onLaunch}
+            onClear={() => onSearchChange('')}
+            keyboardEnabled={!detailOpen}
+            selectedSubSlug={selectedSubSlug}
+          />
+        </div>
       )}
 
       {/* Discovery spine: only shown when not searching */}

package/src/modules/appCatalog/ui/catalog/AppDetailPanel.tsx

@@ -1,7 +1,14 @@
 import type { Resource } from '@igstack/app-catalog-backend-core'
-import { X } from 'lucide-react'
-import { useEffect, useLayoutEffect, useRef } from 'react'
+import { Maximize2, Minimize2, X } from 'lucide-react'
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
 import { useAppCatalogContext } from '../../context/AppCatalogContext'
+import {
+  ResourceDetailAccessActions,
+  ResourceDetailProvider,
+} from '~/modules/extensions'
+import { useOptionalUser } from '~/modules/auth'
+import { useDismissStack, useDismissable } from '~/modules/dismiss/DismissStack'
+import { getChildResources } from '../../utils/resolveHelpers'
 import { SubResourceDetailPanel } from '../components/SubResourceDetailPanel'
 import { AppDetails } from '../detail/AppDetails'
 
@@ -35,8 +42,24 @@ export function AppDetailPanel({
   /** Clears `?sub=` and returns to the parent's detail. */
   onBackToParent?: () => void
 }) {
-  const { approvalMethods } = useAppCatalogContext()
+  const { approvalMethods, resources: allResources } = useAppCatalogContext()
+  const user = useOptionalUser()
+
+  // The sub-resource branch has no band of its own, so its slot payload is
+  // assembled here, where the catalog context already is, and handed down.
+  const subResourceActionsCtx = useMemo(
+    () => ({
+      resource: subResource ?? app,
+      parent: subResource ? app : undefined,
+      subResources: getChildResources(allResources, app.slug),
+      user: user ? { email: user.email, isAdmin: user.isAdmin ?? false } : null,
+    }),
+    [subResource, app, allResources, user],
+  )
   const dialogRef = useRef<HTMLDivElement>(null)
+  // Not persisted: every open starts at the normal width. The toggle is for the
+  // one card being read, and the default stays readable for the next one.
+  const [isWide, setIsWide] = useState(false)
 
   /**
    * Centre the card ONCE when it opens, then hold that position.
@@ -92,10 +115,24 @@ export function AppDetailPanel({
   // caret would land on <body> — where the next Tab walks the catalog grid
   // behind the scrim, since the card has no focus trap.
   const shownSlug = subResource?.slug ?? app.slug
+  const stack = useDismissStack()
   useEffect(() => {
     const dialog = dialogRef.current
-    if (dialog && !dialog.contains(document.activeElement)) dialog.focus()
-  }, [shownSlug])
+    if (!dialog || dialog.contains(document.activeElement)) return
+    // Only while the card is on top. A layer opened OVER it — a deployment's
+    // dialog on a nested route — owns the caret, and on a cold deep link that
+    // layer mounts before the card does, so without this check the card took
+    // focus back off the dialog's first field the moment the catalog arrived.
+    const top = stack.topElement()
+    if (top && top !== dialog) return
+    dialog.focus()
+  }, [shownSlug, stack])
+
+  // Escape closes the card. Registered here rather than in AppDetails because
+  // this is the layer's element, and because the sub-resource view renders a
+  // different body in place of AppDetails — which left that view with no
+  // Escape at all while the registration lived in the body.
+  useDismissable(dialogRef, onClose)
 
   return (
     <div className="fixed inset-0 z-50 flex items-start justify-center overflow-y-auto p-4 sm:p-6 md:p-10">
@@ -122,16 +159,33 @@ export function AppDetailPanel({
         // `overflow-hidden` belongs on the rounded box: the scrolling child
         // below carries the band's tint to its own square corners and paints
         // them over this radius, so the card's top corners read as cut off.
-        className="relative w-full max-w-[min(1120px,94vw)] overflow-hidden rounded-[var(--radius)] border border-border bg-background shadow-2xl animate-in fade-in zoom-in-95 duration-200 outline-none"
+        // Widening drops the cap only. The pinned top margin is left alone, so
+        // the card's top edge stays put and restoring gives back the same layout.
+        className={`relative w-full ${isWide ? 'max-w-none' : 'max-w-[min(1120px,94vw)]'} overflow-hidden rounded-[var(--radius)] border border-border bg-background shadow-2xl animate-in fade-in zoom-in-95 duration-200 outline-none`}
       >
-        <button
-          type="button"
-          aria-label="Close"
-          onClick={onClose}
-          className="absolute top-3 right-3 z-10 rounded-full p-1.5 text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
-        >
-          <X className="size-4" />
-        </button>
+        <div className="absolute top-3 right-3 z-10 flex gap-1">
+          <button
+            type="button"
+            aria-label={isWide ? 'Restore width' : 'Widen card'}
+            title={isWide ? 'Restore width' : 'Widen card'}
+            onClick={() => setIsWide((wide) => !wide)}
+            className="rounded-full p-1.5 text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
+          >
+            {isWide ? (
+              <Minimize2 className="size-4" />
+            ) : (
+              <Maximize2 className="size-4" />
+            )}
+          </button>
+          <button
+            type="button"
+            aria-label="Close"
+            onClick={onClose}
+            className="rounded-full p-1.5 text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
+          >
+            <X className="size-4" />
+          </button>
+        </div>
         {/* Keyed by the resource on screen, so the body remounts when the card
             navigates from one app to another ("View replacement", an access
             prerequisite's parent) instead of updating in place. Everything
@@ -147,20 +201,27 @@ export function AppDetailPanel({
           key={shownSlug}
           className="max-h-[85vh] overflow-y-auto px-6 py-5 sm:px-8 sm:py-7"
         >
-          {subResource ? (
-            <SubResourceDetailPanel
-              subResource={subResource}
-              parent={app}
-              approvalMethods={approvalMethods}
-              onBack={onBackToParent ?? onClose}
-            />
-          ) : (
-            <AppDetails
-              app={app}
-              onAppClick={onAppClick}
-              onClosePanel={onClose}
-            />
-          )}
+          {/* Inside the key, so anything a plugin provides here is scoped to
+              the resource on screen and is discarded when the card navigates.
+              Renders its children untouched when no plugin contributes. */}
+          <ResourceDetailProvider
+            resource={subResource ?? app}
+            parent={subResource ? app : undefined}
+          >
+            {subResource ? (
+              <SubResourceDetailPanel
+                subResource={subResource}
+                parent={app}
+                approvalMethods={approvalMethods}
+                onBack={onBackToParent ?? onClose}
+                actions={
+                  <ResourceDetailAccessActions {...subResourceActionsCtx} />
+                }
+              />
+            ) : (
+              <AppDetails app={app} onAppClick={onAppClick} />
+            )}
+          </ResourceDetailProvider>
         </div>
       </div>
     </div>

package/src/modules/appCatalog/ui/components/ScreenshotGallery.tsx

@@ -1,4 +1,5 @@
 import { useMemo, useRef } from 'react'
+import { useDismissable } from '~/modules/dismiss/DismissStack'
 
 import type { Resource } from '@igstack/app-catalog-backend-core'
 
@@ -24,8 +25,15 @@ export function ScreenshotGallery({
   onOpenChange,
   title,
 }: ScreenshotGalleryProps) {
-  // Track whether Gallery is in fullscreen — if so, block Radix from closing on Escape
-  const isFullscreenRef = useRef(false)
+  /**
+   * The dialog is dismissable through the stack, not through Radix.
+   *
+   * It no longer needs to know whether the gallery inside it is fullscreen:
+   * fullscreen registers above this layer while it is on, so Escape reaches it
+   * first and this dialog only hears Escape once fullscreen is off.
+   */
+  const contentRef = useRef<HTMLDivElement>(null)
+  useDismissable(contentRef, () => onOpenChange(false), { enabled: open })
 
   // Transform screenshot IDs to URLs. Capped at 2000px — plenty for on-screen
   // viewing (incl. fullscreen zoom) while avoiding multi-MB original downloads
@@ -47,33 +55,17 @@ export function ScreenshotGallery({
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent
+        ref={contentRef}
         aria-describedby={undefined}
         className="h-[85vh] w-full max-w-[calc(100vw-2rem)] sm:max-w-[calc(100vw-3rem)] md:max-w-[calc(100vw-4rem)] p-0 overflow-hidden"
         showCloseButton={true}
-        onEscapeKeyDown={(e) => {
-          // Stop propagation so the Esc event doesn't reach outer document listeners
-          // (e.g. SearchResultsList's raw keydown handler, which would clear search).
-          e.stopPropagation()
-          // If Gallery is in fullscreen, its capture listener already handled Escape.
-          // Prevent Radix from also closing the dialog on the same event.
-          if (isFullscreenRef.current) {
-            e.preventDefault()
-          }
-        }}
       >
         <VisuallyHidden>
           <DialogTitle>
             {title || `${app.abbreviation || app.displayName} screenshots`}
           </DialogTitle>
         </VisuallyHidden>
-        <Gallery
-          images={images}
-          initialIndex={initialIndex}
-          title={title}
-          onFullscreenChange={(fs) => {
-            isFullscreenRef.current = fs
-          }}
-        />
+        <Gallery images={images} initialIndex={initialIndex} title={title} />
       </DialogContent>
     </Dialog>
   )

package/src/modules/appCatalog/ui/components/SubResourceDetailPanel.tsx

@@ -2,6 +2,7 @@ import type {
   AppApprovalMethod,
   Resource,
 } from '@igstack/app-catalog-backend-core'
+import type { ReactNode } from 'react'
 import { ArrowLeft, ExternalLink } from 'lucide-react'
 import { Button } from '~/ui/button'
 import { Badge } from '~/ui/badge'
@@ -13,6 +14,16 @@ interface SubResourceDetailPanelProps {
   parent: Resource
   approvalMethods: AppApprovalMethod[]
   onBack: () => void
+  /**
+   * Plugin actions for this sub-resource, rendered under the title.
+   *
+   * Passed in rather than rendered here on purpose. The slot's payload needs the
+   * catalog context and the signed-in user, and calling those hooks in this
+   * component would break the tests that render it bare — the same failure mode
+   * a `useTRPC()` call has in `AppCatalogGrid`. Optional, so those tests keep
+   * passing untouched.
+   */
+  actions?: ReactNode
 }
 
 function StepBadge({ step }: { step: number }) {
@@ -28,6 +39,7 @@ export function SubResourceDetailPanel({
   parent,
   approvalMethods,
   onBack,
+  actions,
 }: SubResourceDetailPanelProps) {
   // Mirrors AccessRequestSection's fallback: a sub-resource usually documents
   // access through top-level `approverSlugs`/`accessComments`, not through an
@@ -102,6 +114,13 @@ export function SubResourceDetailPanel({
         )}
       </div>
 
+      {/* ABOVE the gate below on purpose: an account with no approver, owner
+          or access comments renders no access region at all, and that is
+          exactly the case where an approver most needs the action. */}
+      {actions ? (
+        <div className="mt-4 flex items-center gap-2">{actions}</div>
+      ) : null}
+
       {/* Two-step access section */}
       {hasAnyAccess && (
         // The whole two-step region carries the anchor: the step labels naming