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

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 { useEffect, useLayoutEffect, useMemo, useRef } 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,7 +42,20 @@ 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)
 
   /**
@@ -92,10 +112,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">
@@ -147,20 +181,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/AccessRequestSection.tsx

@@ -89,10 +89,17 @@ function RolesTable({
                 <TableCell className="font-medium whitespace-nowrap">
                   {role.displayName}
                 </TableCell>
-                {/* `adminNotes` is provisioning-only and never shown to
-                    the requester — only `description` belongs here. */}
+                {/* `adminNotes` is the provisioning detail — the directory
+                    group, the SSO app, the manual step. It reads as a note
+                    under the description because the person granting the role
+                    and the person asking for it read the same page. */}
                 <TableCell className="text-sm text-muted-foreground">
                   {role.description || '—'}
+                  {role.adminNotes && (
+                    <div className="mt-1 text-xs italic text-muted-foreground/80">
+                      Note: {role.adminNotes}
+                    </div>
+                  )}
                 </TableCell>
               </TableRow>
             ))}
@@ -228,6 +235,22 @@ const UNDOCUMENTED_WITH_CONTACT =
 const UNDOCUMENTED_WITHOUT_CONTACT =
   'Access process not documented yet, and no owner is listed for this app.'
 
+/**
+ * The entry's own `adminNotes`, served as `Resource.notes`: the provisioning
+ * route an approver follows — the pipeline to run, the group to grant. It is
+ * about the whole request rather than one role, so it gets its own block.
+ */
+function AdminNotes({ notes }: { notes: string }) {
+  return (
+    <div>
+      <h4 className="mb-2 text-sm font-medium">Admin notes</h4>
+      <div className="text-sm text-muted-foreground prose prose-sm max-w-none">
+        <MarkdownText>{notes}</MarkdownText>
+      </div>
+    </div>
+  )
+}
+
 /**
  * The frame every access state renders into, including the empty one — an
  * entry with no access data still gets the heading, because a missing box
@@ -307,6 +330,10 @@ export function AccessRequestSection({
         <p className="text-sm text-muted-foreground">
           {UNDOCUMENTED_WITHOUT_CONTACT}
         </p>
+        {/* No request route written down, but a provisioning note still is:
+            that note is then the only thing on the page that says how the
+            access gets granted, so it cannot hang off `accessRequest`. */}
+        {app.notes && <AdminNotes notes={app.notes} />}
       </AccessBox>
     )
   }
@@ -421,6 +448,10 @@ export function AccessRequestSection({
         <RolesTable roles={accessRequest.roles} />
       )}
 
+      {/* After the roles, because the groups and pipelines it names are what
+          the roles above are granted through. */}
+      {app.notes && <AdminNotes notes={app.notes} />}
+
       {/* Approvers */}
       {accessRequest.approverSlugs &&
         accessRequest.approverSlugs.length > 0 && (

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