{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "pages-app-routes",
  "title": "App routes and navigation",
  "description": "What an app's routes table and navigation table are made of: a route is an id, a matcher and a page, the first route that answers a path draws it, and a table replaces one entry or gains a page without copying the app.",
  "dependencies": [
    "@registrystack/app-runtime@~0.43.0-next.0"
  ],
  "registryDependencies": [
    "@registrystack/document-preview",
    "@registrystack/pages-change-request-form",
    "@registrystack/pages-create-record",
    "@registrystack/pages-record-attachments",
    "@registrystack/pages-register-routes",
    "@registrystack/pages-request-detail",
    "@registrystack/request-attachment-slots"
  ],
  "files": [
    {
      "path": "pages/app-routes.tsx",
      "content": "import { lazy, type ComponentType, type LazyExoticComponent, type ReactNode } from \"react\";\nimport type { AuthenticatedSession } from \"@registrystack/app-runtime\";\nimport type { DocumentSource } from \"@/blocks/documents/document-view\";\nimport type { ChangeRequestTask } from \"@/blocks/pages/change-request-form-page\";\nimport type { CreateRecordTask } from \"@/blocks/pages/create-record-page\";\nimport type { RemovalOutcome } from \"@/blocks/pages/record-attachments\";\nimport {\n  matchEntityRoute,\n  matchRegisterRoute,\n  type EntityRouteMatch,\n  type RegisterRouteMatch,\n  type RegisterRoutes,\n} from \"@/blocks/pages/register-routes\";\nimport type { RequestDecisionTask } from \"@/blocks/pages/request-detail-page\";\nimport type { UploadOutcome } from \"@/blocks/request/attachment-slots\";\n\n/** What an app binds into its pages: the task hooks and the PDF opener. */\nexport interface AppParts {\n  useCreateTask: () => CreateRecordTask;\n  useChangeTask: () => ChangeRequestTask;\n  useRequestTask: () => RequestDecisionTask;\n  useUpload: (slot: string) => UploadOutcome;\n  useRemoval: (slot: string) => RemovalOutcome;\n  openPdf?: (\n    bytes: ArrayBuffer,\n    signal: AbortSignal,\n  ) => Promise<DocumentSource>;\n}\n\n/** What a route's page may read when it is drawn. */\nexport interface RouteContext extends AppParts {\n  session: AuthenticatedSession;\n  /** True where the root is about to send the session elsewhere. */\n  redirecting: boolean;\n}\n\n/**\n * One entry of an app's routes table: the path it answers to and the page it\n * draws. `render` returns `undefined` where the path is not the route's, and\n * a node (possibly `null`) where it is. The first entry that answers wins.\n */\nexport interface AppRoute {\n  id: string;\n  render(\n    path: string,\n    routes: RegisterRoutes,\n    context: RouteContext,\n  ): ReactNode | undefined;\n}\n\n/**\n * A route from a matcher and a page: `match` returns the path's parameters,\n * or `null` where the path is not this route's.\n */\nexport function route<P>(\n  id: string,\n  match: (path: string, routes: RegisterRoutes) => P | null,\n  page: (params: P, context: RouteContext) => ReactNode,\n): AppRoute {\n  return {\n    id,\n    render(path, routes, context) {\n      const params = match(path, routes);\n      return params === null ? undefined : page(params, context);\n    },\n  };\n}\n\n/**\n * A page that loads on first use. The module keeps exporting its page by name;\n * the route table decides when it is fetched, so an app's first chunk holds the\n * shell and the table, not every page. Draw it inside a `Suspense` boundary.\n */\nexport function lazyPage<\n  K extends string,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  M extends Record<K, ComponentType<any>>,\n>(load: () => Promise<M>, name: K): LazyExoticComponent<M[K]> {\n  return lazy(async () => ({ default: (await load())[name] }));\n}\n\n/** Matches one kind of the register's own paths, with that kind's parameters. */\nexport function registerPath<K extends RegisterRouteMatch[\"kind\"]>(kind: K) {\n  return (path: string, routes: RegisterRoutes) => {\n    const match = matchRegisterRoute(routes, path);\n    return match.kind === kind\n      ? (match as Extract<RegisterRouteMatch, { kind: K }>)\n      : null;\n  };\n}\n\n/** Matches one kind of another record entity's paths, with that kind's parameters. */\nexport function entityPath<K extends EntityRouteMatch[\"kind\"]>(kind: K) {\n  return (path: string, routes: RegisterRoutes) => {\n    const match = matchEntityRoute(routes, path);\n    return match.kind === kind\n      ? (match as Extract<EntityRouteMatch, { kind: K }>)\n      : null;\n  };\n}\n\n/** Matches exactly one path. */\nexport function exactPath(...paths: string[]) {\n  return (path: string) => (paths.includes(path) ? {} : null);\n}\n\n/** The page of the first route that answers the path, or `undefined` where none does. */\nexport function renderRoute(\n  table: readonly AppRoute[],\n  path: string,\n  routes: RegisterRoutes,\n  context: RouteContext,\n): ReactNode | undefined {\n  for (const entry of table) {\n    const page = entry.render(path, routes, context);\n    if (page !== undefined) return page;\n  }\n  return undefined;\n}\n\n/**\n * The table with the entry of the same id swapped for `replacement`. An id\n * the table does not hold is an error, so a misspelt id cannot silently leave\n * the default page in place.\n */\nexport function replaceRoute(\n  table: readonly AppRoute[],\n  replacement: AppRoute,\n): AppRoute[] {\n  if (!table.some((entry) => entry.id === replacement.id))\n    throw new Error(`No route \"${replacement.id}\" to replace.`);\n  return table.map((entry) =>\n    entry.id === replacement.id ? replacement : entry,\n  );\n}\n\n/**\n * One place, or a few, in an app's navigation. `items` returns none where\n * the session has no such place.\n */\nexport interface NavEntry<Context, Item> {\n  id: string;\n  items(context: Context): Item[];\n}\n\n/**\n * An app's navigation as data: groups of entries, each group drawn between\n * dividers, in order.\n */\nexport type NavTable<Context, Item> = ReadonlyArray<\n  ReadonlyArray<NavEntry<Context, Item>>\n>;\n\n/** The groups of items a context gets from a table; a group with no items is dropped. */\nexport function navGroups<Context, Item>(\n  table: NavTable<Context, Item>,\n  context: Context,\n): Item[][] {\n  return table\n    .map((group) => group.flatMap((entry) => entry.items(context)))\n    .filter((items) => items.length > 0);\n}\n",
      "type": "registry:block",
      "target": "@components/pages/app-routes.tsx"
    }
  ],
  "type": "registry:block"
}