@stapel/categories-react 0.1.0

package/dist/model/queries.d.ts

@@ -0,0 +1,124 @@
+import type { UseQueryResult } from "@tanstack/react-query";
+import type { StapelApiError } from "@stapel/core";
+import type { Category, CategoryFeature, MaxRevision } from "../api/types.js";
+import type { BuildCategoryTreeOptions, CategoryIndex } from "../catalog/tree.js";
+import type { CategorySnapshot } from "../catalog/sync.js";
+import type { CatalogStore } from "./catalogStore.js";
+/**
+ * Read hooks over the categories API (frontend-standard §2). Keys are
+ * namespaced (see `categoriesQueryKeys`).
+ *
+ * NOT SESSION-GATED, and that is the documented exception rather than an
+ * omission. Sibling pairs gate every read on `useActiveSessionReady` because
+ * their endpoints need a principal; every read here is a SAFE method under
+ * `ReadOnlyOrStaff`, which anonymous callers may make. Gating them would make
+ * a storefront's catalogue wait for a login bootstrap that a visitor who will
+ * never sign in has no stake in.
+ */
+/** What `useCategoryCatalog` hands back beside the tree. */
+export interface CategoryCatalog {
+    readonly index: CategoryIndex;
+    /** The snapshot the tree was built from — cursor included, so a host can
+     * show "catalogue as of revision N" or drive its own refresh policy. */
+    readonly snapshot: CategorySnapshot;
+    /** The page budget stopped the walk. The tree is a PARTIAL catalogue: a
+     * missing branch here is not an empty branch, and a skin that can say so
+     * should. */
+    readonly truncated: boolean;
+    /** The walk started from nothing (cold cache), rather than applying a delta. */
+    readonly wasFullSync: boolean;
+}
+export interface UseCategoryCatalogOptions extends BuildCategoryTreeOptions {
+    readonly enabled?: boolean;
+    /** Rows per sync request (server default 100, max 1000). */
+    readonly pageSize?: number;
+    /** Persistence seam. Default: an app-scoped `createRepository` store. Pass
+     * `memoryCatalogStore()` to opt out of persistence entirely. */
+    readonly store?: CatalogStore;
+    /**
+     * How long the built catalogue is considered fresh. Default: five minutes.
+     *
+     * A catalogue changes when somebody edits it in the admin, not while a
+     * person browses, and every refetch is a delta request that usually returns
+     * zero rows — so the default is generous on purpose. `0` makes every mount
+     * re-ask.
+     */
+    readonly staleTime?: number;
+}
+/**
+ * The whole category tree, delta-synced and cached across page loads.
+ *
+ * This is the hook a storefront mounts once, high up: `/c/:slug` resolves its
+ * slug against it, breadcrumbs walk it, the picker in the compose form reads
+ * it, and none of them costs a request. Without it every page pulls the
+ * catalogue (spec §4.3).
+ *
+ * ── What one "load" actually does ──────────────────────────────────────────
+ *
+ *   read the stored snapshot  (app-scoped repository; may be empty)
+ *   → GET /categories/?include_deleted=false          (cold)
+ *     or GET /categories/?min_revision=<cursor>       (warm)
+ *   → follow `has_next` with the window pinned by `max_revision`
+ *   → fold rows + `revisions.deleted_ids` into the snapshot
+ *   → persist, then build the tree
+ *
+ * The load discipline is the fleet's: `loading` while the first answer is in
+ * flight (including while the repository read is), `failed` on a refusal — a
+ * failed sync never degrades to "the catalogue is empty". Because the stored
+ * snapshot is read INSIDE the query function, a warm start still reports
+ * `loading` on the very first render and then resolves in the same tick; it
+ * does not flash an empty tree.
+ *
+ * `retry: false`: a sync failure is worth reporting immediately, and the
+ * caller has `refetch`. Three silent retries only delay the sentence.
+ */
+export declare function useCategoryCatalog(options?: UseCategoryCatalogOptions): UseQueryResult<CategoryCatalog, StapelApiError>;
+/**
+ * One category's direct children, straight from the server.
+ *
+ * The synced tree already knows them; this is for the host that does not mount
+ * the catalogue — an SSR category page, a lazily expanded branch. The server
+ * filters `deleted` here and orders by `tn_priority` descending, but it does
+ * NOT filter `active`, so a public screen still has to.
+ */
+export declare function useCategoryChildren(id: number | null | undefined, options?: {
+    readonly enabled?: boolean;
+}): UseQueryResult<readonly Category[], StapelApiError>;
+/**
+ * The carousel strip for a landing page.
+ *
+ * The one endpoint the server already filters completely (`active` AND
+ * `carousel_enabled`) and already caches, sending
+ * `Cache-Control: public, max-age`. `staleTime` mirrors that: the browser's
+ * HTTP cache and the query cache should not disagree about how fresh this is.
+ */
+export declare function useCategoryCarousel(options?: {
+    readonly enabled?: boolean;
+    readonly staleTime?: number;
+}): UseQueryResult<readonly Category[], StapelApiError>;
+/**
+ * A category's resolved feature schema — own plus inherited, deduplicated by
+ * slug, in the category's own order.
+ *
+ * This is the payload `@stapel/attributes-react` draws (the compose form) and
+ * labels facets from (the search pair's `categoryFeatures` slot). It changes
+ * only when the catalogue is edited, hence the same generous `staleTime`.
+ */
+export declare function useCategoryFeatures(id: number | null | undefined, options?: {
+    readonly enabled?: boolean;
+    readonly staleTime?: number;
+}): UseQueryResult<readonly CategoryFeature[], StapelApiError>;
+/**
+ * The catalogue's current maximum revision — the cheap freshness probe.
+ *
+ * A host that wants to poll for catalogue changes without transferring rows
+ * compares this to `catalog.snapshot.cursor` and invalidates the catalogue key
+ * when it moves. Not wired into `useCategoryCatalog` on purpose: how often to
+ * ask is a deployment's decision, and a library that picked one would be
+ * polling somebody's API on their behalf.
+ */
+export declare function useCategoriesRevision(options?: {
+    readonly enabled?: boolean;
+    readonly refetchInterval?: number;
+}): UseQueryResult<MaxRevision, StapelApiError>;
+//# sourceMappingURL=queries.d.ts.map

package/dist/model/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/model/queries.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9E,OAAO,KAAK,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD;;;;;;;;;;GAUG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B;4EACwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC;;iBAEa;IACb,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;oEACgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,yBAA8B,GACtC,cAAc,CAAC,eAAe,EAAE,cAAc,CAAC,CA8CjD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC7B,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACvC,cAAc,CAAC,SAAS,QAAQ,EAAE,EAAE,cAAc,CAAC,CAQrD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,GAAG,cAAc,CAAC,SAAS,QAAQ,EAAE,EAAE,cAAc,CAAC,CAStD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC7B,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE,cAAc,CAAC,SAAS,eAAe,EAAE,EAAE,cAAc,CAAC,CAS5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC,GAAG,cAAc,CAAC,WAAW,EAAE,cAAc,CAAC,CAW9C"}

package/dist/model/queries.js

@@ -0,0 +1,147 @@
+import { useMemo } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { buildCategoryTree } from "../catalog/tree.js";
+import { useCategoriesApi } from "./context.js";
+import { createCatalogStore } from "./catalogStore.js";
+import { syncCatalog } from "./catalogSync.js";
+import { catalogKeyOptions, categoriesQueryKeys } from "./queryKeys.js";
+const DEFAULT_CATALOG_STALE_TIME = 5 * 60 * 1000;
+/**
+ * The whole category tree, delta-synced and cached across page loads.
+ *
+ * This is the hook a storefront mounts once, high up: `/c/:slug` resolves its
+ * slug against it, breadcrumbs walk it, the picker in the compose form reads
+ * it, and none of them costs a request. Without it every page pulls the
+ * catalogue (spec §4.3).
+ *
+ * ── What one "load" actually does ──────────────────────────────────────────
+ *
+ *   read the stored snapshot  (app-scoped repository; may be empty)
+ *   → GET /categories/?include_deleted=false          (cold)
+ *     or GET /categories/?min_revision=<cursor>       (warm)
+ *   → follow `has_next` with the window pinned by `max_revision`
+ *   → fold rows + `revisions.deleted_ids` into the snapshot
+ *   → persist, then build the tree
+ *
+ * The load discipline is the fleet's: `loading` while the first answer is in
+ * flight (including while the repository read is), `failed` on a refusal — a
+ * failed sync never degrades to "the catalogue is empty". Because the stored
+ * snapshot is read INSIDE the query function, a warm start still reports
+ * `loading` on the very first render and then resolves in the same tick; it
+ * does not flash an empty tree.
+ *
+ * `retry: false`: a sync failure is worth reporting immediately, and the
+ * caller has `refetch`. Three silent retries only delay the sentence.
+ */
+export function useCategoryCatalog(options = {}) {
+    const api = useCategoriesApi();
+    const treeOptions = useMemo(() => ({
+        ...(options.includeDeleted !== undefined
+            ? { includeDeleted: options.includeDeleted }
+            : {}),
+        ...(options.includeInactive !== undefined
+            ? { includeInactive: options.includeInactive }
+            : {}),
+    }), [options.includeDeleted, options.includeInactive]);
+    const keyOptions = useMemo(() => catalogKeyOptions(treeOptions), [treeOptions]);
+    const providedStore = options.store;
+    const store = useMemo(() => providedStore ?? createCatalogStore(), [providedStore]);
+    const pageSize = options.pageSize;
+    return useQuery({
+        queryKey: categoriesQueryKeys.catalog(keyOptions),
+        queryFn: async ({ signal }) => {
+            const stored = await store.load();
+            const result = await syncCatalog(api, stored, {
+                signal,
+                ...(pageSize !== undefined ? { pageSize } : {}),
+            });
+            // A truncated walk keeps the previous cursor (`syncCatalog`), so
+            // persisting it cannot record progress that was not made.
+            await store.save(result.snapshot);
+            return {
+                index: buildCategoryTree(result.snapshot.rows, treeOptions),
+                snapshot: result.snapshot,
+                truncated: result.truncated,
+                wasFullSync: result.wasFullSync,
+            };
+        },
+        enabled: options.enabled ?? true,
+        staleTime: options.staleTime ?? DEFAULT_CATALOG_STALE_TIME,
+        retry: false,
+    });
+}
+/**
+ * One category's direct children, straight from the server.
+ *
+ * The synced tree already knows them; this is for the host that does not mount
+ * the catalogue — an SSR category page, a lazily expanded branch. The server
+ * filters `deleted` here and orders by `tn_priority` descending, but it does
+ * NOT filter `active`, so a public screen still has to.
+ */
+export function useCategoryChildren(id, options) {
+    const api = useCategoriesApi();
+    return useQuery({
+        queryKey: categoriesQueryKeys.children(id ?? -1),
+        queryFn: ({ signal }) => api.children(id, { signal }),
+        enabled: (options?.enabled ?? true) && typeof id === "number",
+        retry: false,
+    });
+}
+/**
+ * The carousel strip for a landing page.
+ *
+ * The one endpoint the server already filters completely (`active` AND
+ * `carousel_enabled`) and already caches, sending
+ * `Cache-Control: public, max-age`. `staleTime` mirrors that: the browser's
+ * HTTP cache and the query cache should not disagree about how fresh this is.
+ */
+export function useCategoryCarousel(options) {
+    const api = useCategoriesApi();
+    return useQuery({
+        queryKey: categoriesQueryKeys.carousel,
+        queryFn: ({ signal }) => api.carousel({ signal }),
+        enabled: options?.enabled ?? true,
+        staleTime: options?.staleTime ?? DEFAULT_CATALOG_STALE_TIME,
+        retry: false,
+    });
+}
+/**
+ * A category's resolved feature schema — own plus inherited, deduplicated by
+ * slug, in the category's own order.
+ *
+ * This is the payload `@stapel/attributes-react` draws (the compose form) and
+ * labels facets from (the search pair's `categoryFeatures` slot). It changes
+ * only when the catalogue is edited, hence the same generous `staleTime`.
+ */
+export function useCategoryFeatures(id, options) {
+    const api = useCategoriesApi();
+    return useQuery({
+        queryKey: categoriesQueryKeys.features(id ?? -1),
+        queryFn: ({ signal }) => api.features(id, { signal }),
+        enabled: (options?.enabled ?? true) && typeof id === "number",
+        staleTime: options?.staleTime ?? DEFAULT_CATALOG_STALE_TIME,
+        retry: false,
+    });
+}
+/**
+ * The catalogue's current maximum revision — the cheap freshness probe.
+ *
+ * A host that wants to poll for catalogue changes without transferring rows
+ * compares this to `catalog.snapshot.cursor` and invalidates the catalogue key
+ * when it moves. Not wired into `useCategoryCatalog` on purpose: how often to
+ * ask is a deployment's decision, and a library that picked one would be
+ * polling somebody's API on their behalf.
+ */
+export function useCategoriesRevision(options) {
+    const api = useCategoriesApi();
+    return useQuery({
+        queryKey: categoriesQueryKeys.revision,
+        queryFn: ({ signal }) => api.revision({ signal }),
+        enabled: options?.enabled ?? true,
+        ...(options?.refetchInterval !== undefined
+            ? { refetchInterval: options.refetchInterval }
+            : {}),
+        retry: false,
+    });
+}
+//# sourceMappingURL=queries.js.map

package/dist/model/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../../src/model/queries.ts"],"names":[],"mappings":"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"}

package/dist/model/queryKeys.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Namespaced TanStack Query keys (frontend-standard §2 — namespaced keys).
+ * Everything under the `"categories"` root so a host can invalidate the whole
+ * module or match a single read. Explicit tuple return types satisfy
+ * `--isolatedDeclarations`.
+ *
+ * THE CATALOGUE IS ONE KEY, NOT A PAGE PER REQUEST. `catalog()` is keyed on
+ * nothing but the tree options, because the pages of a sync walk are an
+ * implementation detail of producing ONE value — the snapshot. Keying pages
+ * individually would cache the intermediate states of a protocol whose whole
+ * purpose is that the intermediate states are never shown, and would leave a
+ * half-walked catalogue in the cache for the next mount to find.
+ */
+import type { BuildCategoryTreeOptions } from "../catalog/tree.js";
+/** The tree-shaping options a catalogue read is keyed on. Normalized to
+ * booleans so `undefined` and `false` cannot cache twice. */
+export interface CatalogKeyOptions {
+    readonly includeDeleted: boolean;
+    readonly includeInactive: boolean;
+}
+export declare function catalogKeyOptions(options?: BuildCategoryTreeOptions): CatalogKeyOptions;
+export declare const categoriesQueryKeys: {
+    readonly all: readonly ["categories"];
+    catalog(options: CatalogKeyOptions): readonly ["categories", "catalog", CatalogKeyOptions];
+    children(id: number): readonly ["categories", "children", number];
+    readonly carousel: readonly ["categories", "carousel"];
+    features(id: number): readonly ["categories", "features", number];
+    readonly revision: readonly ["categories", "revision"];
+};
+//# sourceMappingURL=queryKeys.d.ts.map

package/dist/model/queryKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryKeys.d.ts","sourceRoot":"","sources":["../../src/model/queryKeys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAInE;6DAC6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,iBAAiB,CAKnB;AAED,eAAO,MAAM,mBAAmB,EAAE;IAChC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IACtC,OAAO,CACL,OAAO,EAAE,iBAAiB,GACzB,SAAS,CAAC,YAAY,EAAE,SAAS,EAAE,iBAAiB,CAAC,CAAC;IACzD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,YAAY,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAClE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IACvD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,YAAY,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAClE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;CAQxD,CAAC"}

package/dist/model/queryKeys.js

@@ -0,0 +1,16 @@
+const ROOT = "categories";
+export function catalogKeyOptions(options = {}) {
+    return {
+        includeDeleted: options.includeDeleted === true,
+        includeInactive: options.includeInactive === true,
+    };
+}
+export const categoriesQueryKeys = {
+    all: [ROOT],
+    catalog: (options) => [ROOT, "catalog", options],
+    children: (id) => [ROOT, "children", id],
+    carousel: [ROOT, "carousel"],
+    features: (id) => [ROOT, "features", id],
+    revision: [ROOT, "revision"],
+};
+//# sourceMappingURL=queryKeys.js.map

package/dist/model/queryKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryKeys.js","sourceRoot":"","sources":["../../src/model/queryKeys.ts"],"names":[],"mappings":"AAeA,MAAM,IAAI,GAAG,YAAqB,CAAC;AASnC,MAAM,UAAU,iBAAiB,CAC/B,UAAoC,EAAE;IAEtC,OAAO;QACL,cAAc,EAAE,OAAO,CAAC,cAAc,KAAK,IAAI;QAC/C,eAAe,EAAE,OAAO,CAAC,eAAe,KAAK,IAAI;KAClD,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,mBAAmB,GAS5B;IACF,GAAG,EAAE,CAAC,IAAI,CAAC;IACX,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC;IAChD,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,CAAC;IACxC,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC;IAC5B,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,CAAC;IACxC,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC;CAC7B,CAAC"}

package/dist/model/runtime.d.ts

@@ -0,0 +1,31 @@
+import type { CreateModuleRuntimeOptions, ModuleRuntime } from "@stapel/core";
+import type { CategoriesApi } from "../api/categoriesApi.js";
+/**
+ * The wired categories runtime — core's `ModuleRuntime` bound to this pair's
+ * API (slim wave §21/S2). The returned `client` is what the host injects into
+ * core's `StapelConfigProvider` (as the default or the `"categories"` module
+ * client), preserving the client-injection fork seam (frontend-standard §7.2).
+ *
+ * ANONYMOUS BY DESIGN. Every endpoint this pair calls is a SAFE method under
+ * `ReadOnlyOrStaff`, i.e. open to a caller with no session at all:
+ *
+ * ```tsx
+ * const runtime = createCategoriesRuntime({ baseUrl: "/categories/api/v1/" });
+ * <CategoriesProvider runtime={runtime}>…</CategoriesProvider>
+ * ```
+ *
+ * No session, no workspace id, no auth client — which is what lets a
+ * catalogue render for a visitor who will never sign in, and why the read
+ * hooks here are deliberately not gated on `useActiveSessionReady`.
+ *
+ * The catalogue snapshot is stored in an **app-scoped** repository
+ * (`createRepository(..., { scope: "app" })`, `model/catalogStore.ts`): a
+ * category tree is a deployment's public content, identical for every visitor,
+ * so it is neither encrypted with the per-session key nor wiped at logout.
+ * Wiping it would mean re-downloading the whole catalogue every time somebody
+ * signs out.
+ */
+export type CategoriesRuntime = ModuleRuntime<CategoriesApi>;
+export type CreateCategoriesRuntimeOptions = CreateModuleRuntimeOptions;
+export declare function createCategoriesRuntime(options: CreateCategoriesRuntimeOptions): CategoriesRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/model/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/model/runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,0BAA0B,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;AAE7D,MAAM,MAAM,8BAA8B,GAAG,0BAA0B,CAAC;AAExE,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,8BAA8B,GACtC,iBAAiB,CAEnB"}

package/dist/model/runtime.js

@@ -0,0 +1,6 @@
+import { createModuleRuntime } from "@stapel/core";
+import { createCategoriesApi } from "../api/categoriesApi.js";
+export function createCategoriesRuntime(options) {
+    return createModuleRuntime((client) => createCategoriesApi(client), options);
+}
+//# sourceMappingURL=runtime.js.map

package/dist/model/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/model/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAgC9D,MAAM,UAAU,uBAAuB,CACrC,OAAuC;IAEvC,OAAO,mBAAmB,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;AAC/E,CAAC"}

package/dist/nav/manifest.d.ts

@@ -0,0 +1,31 @@
+/**
+ * This pair's contribution to the scripted-fullstack nav contract
+ * (`@stapel/core`'s `NavEntry`/`PackageNavManifest`). `scripts/gen-nav-
+ * manifest.mjs` reads `navEntries` below, stamps `package`/`version` from THIS
+ * package's own `package.json`, and emits
+ * `packages/categories-react/nav-manifest.json` plus this package's slice of
+ * the root aggregate.
+ *
+ * ── Why `/` is NOT claimed here ────────────────────────────────────────────
+ *
+ * The spec's route table (§5.1) gives `/` to "categories + search": a carousel
+ * of categories above a feed of the newest listings. That screen is COMPOSED
+ * of two pairs, and a composed route belongs to the container that composes it
+ * (§6.2 — wiring adds, generation emits). A pair claiming `/` would be one
+ * package deciding the landing page of every host that installs it, and the
+ * second pair would have nowhere to put its half.
+ *
+ * So the catalogue's own root is `/c` — the whole tree as a browsable page,
+ * which is a real single-pair screen — and `/c/:slug` is the category page.
+ * The container's landing mounts `<CategoryCarousel>` (or the skin's
+ * `CategoryCarouselStrip`) itself, which is one line and no manifest entry.
+ *
+ * Both entries declare `surface: "public"` EXPLICITLY. The derivation
+ * `requiresAuth ? "member" : "public"` lands on the same answer today; the
+ * explicit declaration is what a public container can rely on if an entry ever
+ * gains an auth requirement for an unrelated reason (`core/src/nav.ts`,
+ * `navEntrySurface`; the trap is §1.3 — `audience: undefined` does not filter).
+ */
+import type { NavEntry } from "@stapel/core";
+export declare const navEntries: readonly NavEntry[];
+//# sourceMappingURL=manifest.d.ts.map

package/dist/nav/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/nav/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAmCzC,CAAC"}

package/dist/nav/manifest.js

@@ -0,0 +1,37 @@
+export const navEntries = [
+    {
+        // The catalogue root: the tree, browsable, with the carousel above it.
+        // This one IS a menu item — "Catalogue" is the browse bar's anchor, which
+        // is why it is the single entry in this pair with
+        // `menuVisibleDefault: true`.
+        id: "categories.catalog",
+        labelKey: "categories.catalog.title",
+        icon: "AppstoreOutlined",
+        route: { path: "/c" },
+        component: { export: "CatalogPage", subpath: "default" },
+        placement: { level: "top" },
+        menuVisibleDefault: true,
+        requiresAuth: false,
+        surface: "public",
+        order: 5,
+    },
+    {
+        // `/c/:slug`, not `/c/:id`. `Category.slug` is `unique=True` on the model,
+        // but the SERVER cannot look a category up by it — `lookup_field` is never
+        // overridden and the list endpoint has no slug filter — so the resolution
+        // happens client-side against the synced tree (spec §4.3). A
+        // parameterized route is a navigation TARGET, not a menu item: the same
+        // treatment `auth.login` and `search.results` get.
+        id: "categories.category",
+        labelKey: "categories.category.title",
+        icon: "FolderOpenOutlined",
+        route: { path: "/c/:slug" },
+        component: { export: "CategoryPage", subpath: "default" },
+        placement: { level: "top" },
+        menuVisibleDefault: false,
+        requiresAuth: false,
+        surface: "public",
+        order: 6,
+    },
+];
+//# sourceMappingURL=manifest.js.map

package/dist/nav/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/nav/manifest.ts"],"names":[],"mappings":"AA8BA,MAAM,CAAC,MAAM,UAAU,GAAwB;IAC7C;QACE,uEAAuE;QACvE,0EAA0E;QAC1E,kDAAkD;QAClD,8BAA8B;QAC9B,EAAE,EAAE,oBAAoB;QACxB,QAAQ,EAAE,0BAA0B;QACpC,IAAI,EAAE,kBAAkB;QACxB,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;QACrB,SAAS,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE;QACxD,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;QAC3B,kBAAkB,EAAE,IAAI;QACxB,YAAY,EAAE,KAAK;QACnB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,CAAC;KACT;IACD;QACE,2EAA2E;QAC3E,2EAA2E;QAC3E,0EAA0E;QAC1E,6DAA6D;QAC7D,wEAAwE;QACxE,mDAAmD;QACnD,EAAE,EAAE,qBAAqB;QACzB,QAAQ,EAAE,2BAA2B;QACrC,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE;QAC3B,SAAS,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE;QACzD,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;QAC3B,kBAAkB,EAAE,KAAK;QACzB,YAAY,EAAE,KAAK;QACnB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,CAAC;KACT;CACF,CAAC"}

package/llms.txt

@@ -0,0 +1,125 @@
+# @stapel/categories-react 0.1.0
+
+Headless React flow pair for stapel-categories (contract >=0.6 <0.7) — business + state, zero visual opinion.
+Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
+verification-403 interception, i18n engine, analytics facade, TanStack Query layer.
+
+## The one right way (do this, the rest is a review/lint smell)
+- No raw fetch/axios. The client is injected via <CategoriesProvider>/StapelConfigProvider;
+  every hook and flow already carries auth, refresh, and the error envelope.
+- Render errors, never try/catch them: a flow's state carries FlowError{code,params};
+  render `t(code, params)` and branch on `explainCategoriesError(code)` remediation.
+- Server state = the use* hooks (query layer); keys come only from categoriesQueryKeys.
+- User strings = i18n keys (registerCategoriesI18n); never string literals.
+- Sign-in UI = a headless flow component; copy it (shadcn-style) to restyle.
+
+## Layers
+api (typed client) · model (hooks, session) · flows (machines) · headless · i18n
+
+## Documented flows (flows.json — canonical id, steps, endpoints)
+
+## Operations (typed; use the named op, never a path string)
+Request/response schema names are in manifest.json + the generated types.
+Paths are relative to `/categories/api/v1/`.
+- categories_api_v1_categories_bulk_add_create: POST /categories/bulk_add/
+- categories_api_v1_categories_bulk_commands_create: POST /categories/bulk-commands/
+- categories_api_v1_categories_carousel_list: GET /categories/carousel/
+- categories_api_v1_categories_children_list: GET /categories/{id}/children/
+- categories_api_v1_categories_create: POST /categories/
+- categories_api_v1_categories_data.json_retrieve: GET /categories/data.json/
+- categories_api_v1_categories_deleted_children_list: GET /categories/{id}/deleted-children/
+- categories_api_v1_categories_destroy: DELETE /categories/{id}/
+- categories_api_v1_categories_feature_editor_apply_create: POST /categories/{id}/feature-editor/apply/
+- categories_api_v1_categories_feature_editor_draft_create: POST /categories/{id}/feature-editor/draft/
+- categories_api_v1_categories_feature_editor_retrieve: GET /categories/{id}/feature-editor/
+- categories_api_v1_categories_features_list: GET /categories/{id}/features/
+- categories_api_v1_categories_list: GET /categories/
+- categories_api_v1_categories_partial_update: PATCH /categories/{id}/
+- categories_api_v1_categories_retrieve: GET /categories/{id}/
+- categories_api_v1_categories_revision_retrieve: GET /categories/revision/
+- categories_api_v1_categories_undelete_create: POST /categories/{id}/undelete/
+- categories_api_v1_categories_update: PUT /categories/{id}/
+- categories_api_v1_categories_validate_configs_retrieve: GET /categories/{id}/validate-configs/
+- categories_api_v1_categories_validate_dto_create: POST /categories/{id}/validate-dto/
+- categories_api_v1_features_bulk_add_create: POST /features/bulk_add/
+- categories_api_v1_features_convert_type_create: POST /features/{id}/convert-type/
+- categories_api_v1_features_create: POST /features/
+- categories_api_v1_features_data.json_retrieve: GET /features/data.json/
+- categories_api_v1_features_destroy: DELETE /features/{id}/
+- categories_api_v1_features_list: GET /features/
+- categories_api_v1_features_partial_update: PATCH /features/{id}/
+- categories_api_v1_features_retrieve: GET /features/{id}/
+- categories_api_v1_features_revision_retrieve: GET /features/revision/
+- categories_api_v1_features_update: PUT /features/{id}/
+- collect_translation_keys: GET /categories/translation-keys/
+
+## Query hooks (server state; keys come only from the key factory)
+- useCategoriesRevision (query) → revision
+- useCategoryCarousel (query) → carousel
+- useCategoryCatalog (query) → —
+- useCategoryChildren (query) → children
+- useCategoryFeatures (query) → features
+
+## Errors (render t(code, params); UX from remediation)
+62 keys (full catalog: manifest.json §errors). By remediation: fix_input 36 · retry 13 · verify 5 · wait_and_retry 5 · contact_support 2 · reauthenticate 1.
+Param-bearing keys (interpolation slots matter):
+- error.400.categories_duplicate_slug [400] → fix_input {slug}
+- error.400.categories_feature_editor_invalid [400] → fix_input {reason}
+- error.400.description_too_long [400] → fix_input {max_length}
+- error.400.description_too_short [400] → fix_input {min_length}
+- error.400.feature_above_maximum [400] → fix_input {feature}
+- error.400.feature_below_minimum [400] → fix_input {feature}
+- error.400.feature_invalid_config [400] → fix_input {feature}
+- error.400.feature_invalid_format [400] → fix_input {feature}
+- error.400.feature_invalid_type [400] → fix_input {feature}
+- error.400.feature_mandatory_missing [400] → fix_input {feature}
+- error.400.feature_not_allowed [400] → fix_input {feature}
+- error.400.feature_not_in_options [400] → fix_input {feature}
+- error.400.feature_unknown [400] → fix_input {feature}
+- error.400.feature_unknown_type [400] → fix_input {feature}
+- error.400.field.blank [400] → fix_input {field}
+- error.400.field.does_not_exist [400] → fix_input {field}
+- error.400.field.invalid [400] → fix_input {field}
+- error.400.field.invalid_choice [400] → fix_input {field}
+- error.400.field.max_length [400] → fix_input {field,max_length}
+- error.400.field.max_value [400] → fix_input {field,max_value}
+- error.400.field.min_length [400] → fix_input {field,min_length}
+- error.400.field.min_value [400] → fix_input {field,min_value}
+- error.400.field.null [400] → fix_input {field}
+- error.400.field.required [400] → fix_input {field}
+- error.400.field.unique [400] → fix_input {field}
+- error.409.categories_feature_editor_conflict [409] → fix_input {expected,actual}
+- error.429.rate_limit [429] → wait_and_retry {retry_after_minutes}
+
+## Analytics events (typed; defineEvent → events.json, drift-gated)
+- (no app defineEvent() in this pair — its analytic events are the
+  auto-instrumented flow funnels below)
+
+## Flow funnels (auto-instrumented: flow.<id>.<step> {phase})
+
+```tsx
+// Typed event + tracked() click (the one right way; §3.1).
+const planSelected = defineEvent({
+  name: "pricing.plan.selected",
+  description: "User picked a plan",
+  props: { plan: prop.oneOf(["free", "pro", "team"], "Plan code") },
+});
+const { tracked } = useTracked();
+<Button onClick={tracked(planSelected, { plan }, startCheckout)} />
+// A click that STEPS a flow machine is already instrumented — mark it
+// data-analytics="flow" instead; tracked() on top double-counts (§3.2).
+```
+
+## Demos (defineDemo → manifest.demos; compiled, linted, rendered examples)
+- categories.carousel → <CategoryCarousel> [default]  demo/CategoryCarousel.demo.tsx
+- categories.features → <CategoryFeatures> [default]  demo/CategoryFeatures.demo.tsx
+- categories.picker → <CategoryPicker> [default]  demo/CategoryPicker.demo.tsx
+- categories.tree → <CategoryTree> [roots|one category]  demo/CategoryTree.demo.tsx
+Each source file is the canonical usage snippet (open the default variant).
+
+## Snippets
+```tsx
+// Error rendering + remediation branch (one pattern for every pair).
+const r = explainCategoriesError(err.code); // 'wait_and_retry' | 'verify' | ...
+return <Alert action={r}>{t(err.code, err.params)}</Alert>;
+```