@stapel/categories-react 0.1.0

package/nav-manifest.json

@@ -0,0 +1,44 @@
+{
+  "package": "@stapel/categories-react",
+  "version": "0.1.0",
+  "entries": [
+    {
+      "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
+    },
+    {
+      "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
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@stapel/categories-react",
+  "version": "0.1.0",
+  "description": "Headless React pair for stapel-categories: a typed client, a client-assembled category tree, and the revision-delta sync the module documents. The list endpoint returns FLAT rows with treenode ancestry as comma-joined pk strings — this package parses them, builds the tree, resolves a slug to a category (the server has no slug lookup), walks breadcrumbs, and keeps the whole catalogue in an app-scoped repository refreshed by `?min_revision=` deltas instead of refetching it on every page. Category and feature names are TRANSLATION KEYS on the wire, never resolved labels, and the pair says so in its types. A category's feature schema is served typed for @stapel/attributes-react to draw and for search facets to label. Zero visual opinion in the main entry; an opt-in /default subpath ships the antd skin.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/usestapel/stapel-react.git",
+    "directory": "packages/categories-react"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./default": {
+      "types": "./dist/default/index.d.ts",
+      "default": "./dist/default/index.js"
+    },
+    "./i18n/ru": {
+      "types": "./dist/i18n/ru.d.ts",
+      "default": "./dist/i18n/ru.js"
+    },
+    "./i18n/es": {
+      "types": "./dist/i18n/es.d.ts",
+      "default": "./dist/i18n/es.js"
+    },
+    "./manifest": "./manifest.json",
+    "./manifest.json": "./manifest.json",
+    "./nav-manifest.json": "./nav-manifest.json",
+    "./llms.txt": "./llms.txt",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md",
+    "MODULE.md",
+    "CHANGELOG.md",
+    "manifest.json",
+    "nav-manifest.json",
+    "llms.txt"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && vitest run --exclude test/prodBundlePurity.test.ts",
+    "lint": "eslint .",
+    "size": "size-limit",
+    "test:pack": "vitest run test/prodBundlePurity.test.ts"
+  },
+  "size-limit": [
+    {
+      "name": "index — the headless pair (client + tree assembly + delta sync + hooks): no antd",
+      "path": "dist/index.js",
+      "limit": "9 KB"
+    },
+    {
+      "name": "default — the antd skin (catalog, category page, carousel, picker, breadcrumbs) must stay out of the main bundle",
+      "path": "dist/default/index.js",
+      "limit": "13 KB"
+    },
+    {
+      "name": "i18n/ru — the Russian bundle is opt-in, not carried by the main entry",
+      "path": "dist/i18n/ru.js",
+      "limit": "4 KB"
+    },
+    {
+      "name": "i18n/es — the Spanish bundle is opt-in, not carried by the main entry",
+      "path": "dist/i18n/es.js",
+      "limit": "3.5 KB"
+    }
+  ],
+  "peerDependencies": {
+    "@stapel/attributes-react": ">=0.1.0",
+    "@stapel/core": ">=0.15.0 <1.0.0",
+    "@stapel/tokens-antd": ">=0.5.0",
+    "@tanstack/react-query": "^5.0.0",
+    "antd": ">=5.20.0 <7",
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "@stapel/tokens-antd": {
+      "optional": true
+    },
+    "antd": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "@stapel/attributes-react": "workspace:^",
+    "@stapel/core": "workspace:^",
+    "@stapel/showcase": "workspace:^",
+    "@stapel/tokens": "workspace:^",
+    "@stapel/tokens-antd": "workspace:^",
+    "@tanstack/react-query": "^5.81.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "antd": "^6.5.0",
+    "jsdom": "^26.1.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "size-limit": "^11.2.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/analytics/generated/events.json

@@ -0,0 +1,7 @@
+{
+  "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
+  "package": "@stapel/categories-react",
+  "version": "0.1.0",
+  "defined": [],
+  "flows": []
+}

package/src/api/categoriesApi.ts

@@ -0,0 +1,179 @@
+import type { StapelClient } from "@stapel/core";
+import type {
+  Category,
+  CategoryFeature,
+  CategoryListParams,
+  CategoryPage,
+  MaxRevision,
+} from "./types.js";
+
+/**
+ * The pair's typed operation surface — one method per stapel-categories
+ * endpoint a storefront may call, bound to the injected {@link StapelClient}
+ * (the per-module override seam of frontend-standard §7.2). Paths are relative
+ * to the runtime's `baseUrl` (`/categories/api/v1/`).
+ *
+ * ── Five reads, and the eighteen operations that are NOT here ──────────────
+ *
+ * The contract has 23 paths. Every one of them is on `ReadOnlyOrStaff`, which
+ * means SAFE methods are open to anonymous callers and everything else needs
+ * `is_staff` — so the split below is not a taste call, it is the permission
+ * boundary drawn on the surface:
+ *
+ *  - **Public reads, and this pair's whole surface**: the category list (the
+ *    delta-sync source), `children`, `carousel`, `{id}/features`, and
+ *    `revision`.
+ *  - **Staff writes**: create / update / delete, `bulk_add`,
+ *    `bulk-commands`, `undelete`, `convert-type`, and the four
+ *    `feature-editor*` operations. These are the catalogue admin, which the
+ *    storefront wave leaves to Django admin (spec §4.3) — a pair that exposed
+ *    them would invite a public screen to call something only staff may.
+ *  - **`POST {id}/validate-dto/` is a WRITE in DRF's eyes**, so despite
+ *    reading like a public helper it answers 403 to a visitor. The listing
+ *    compose flow validates against the same rules with
+ *    `@stapel/attributes-react`'s client-side mirror plus the server's verdict
+ *    on publish; asking this endpoint would fail for exactly the people who
+ *    need it.
+ *  - **`GET {id}/validate-configs/`** is a catalogue-health read for an
+ *    operator, not a storefront read.
+ *  - **`GET translation-keys/`** is `IsServiceRequest` (service-to-service):
+ *    it is the extraction feed for translators, and it returns KEYS with
+ *    admin refs — never resolved labels. See `catalog/labels.ts`.
+ *  - **`GET data.json/`** requires a `?revision=` cache-buster and hands back
+ *    the whole table in one response. It is a legitimate alternative to the
+ *    paged walk, but it is a *second* sync protocol, and the module documents
+ *    the paged one. One protocol, tested, beats two, half-tested.
+ *  - The parallel `/features/` collection (list, retrieve, create, …) is the
+ *    feature tree in its own right — an admin axis. A storefront reads
+ *    features THROUGH a category, which is the only place inheritance and
+ *    order are resolved.
+ *
+ * Nothing is hidden: `manifest.json` lists the whole contract.
+ *
+ * These operations will be GENERATED from schema.json operationIds by gen-api
+ * v2 (task `core-typed-ops`); until then they are hand-authored here (the ONE
+ * legal home of path strings — `stapel/no-string-paths` §2.3 carve-out).
+ */
+export interface CategoriesApi {
+  readonly client: StapelClient;
+
+  /**
+   * One page of the revision-paginated category list — the source the whole
+   * tree is assembled from, and the only endpoint that reports deletions.
+   *
+   * Rows are ordered by `revision`, NOT by tree position: this is a sync feed,
+   * not a menu. `revisions.global_max` is the cursor to store;
+   * `revisions.deleted_ids` is the authoritative tombstone list for a delta
+   * (see `catalog/sync.ts` for why it beats scanning `deleted: true` rows).
+   */
+  list(
+    params?: CategoryListParams,
+    options?: { readonly signal?: AbortSignal }
+  ): Promise<CategoryPage>;
+
+  /**
+   * Non-deleted direct children of one category, `tn_priority` descending.
+   *
+   * Redundant with the synced tree by construction, and deliberately kept: a
+   * host that wants one branch without paying for the catalogue (an SSR
+   * category page, a lazily-expanded admin-ish picker) has an endpoint for it,
+   * and it is the one place the server does the `deleted` filtering.
+   */
+  children(
+    id: number,
+    options?: { readonly signal?: AbortSignal }
+  ): Promise<readonly Category[]>;
+
+  /**
+   * The carousel strip: `active` AND `carousel_enabled`, `tn_priority`
+   * descending, cached server-side and sent with
+   * `Cache-Control: public, max-age` — so this one is safe to call on every
+   * landing render.
+   */
+  carousel(options?: {
+    readonly signal?: AbortSignal;
+  }): Promise<readonly Category[]>;
+
+  /**
+   * A category's resolved feature schema: its own features plus every ancestor's,
+   * deduplicated by SLUG (an `inherit` override is a new row sharing the
+   * parent's slug, and the version nearest this category wins), ordered by the
+   * category's own `CategoryFeature.order` first.
+   *
+   * This is what the listing compose form draws with
+   * `@stapel/attributes-react` and what labels a search facet. `config`
+   * arrives verbatim — defaults are the reader's job, and attributes-react
+   * owns them.
+   */
+  features(
+    id: number,
+    options?: { readonly signal?: AbortSignal }
+  ): Promise<readonly CategoryFeature[]>;
+
+  /**
+   * The table's current maximum revision, without transferring any rows.
+   *
+   * The cheap freshness probe: a stored snapshot whose cursor already equals
+   * this needs no delta request at all.
+   */
+  revision(options?: {
+    readonly signal?: AbortSignal;
+  }): Promise<MaxRevision>;
+}
+
+/**
+ * The wire query object for one list request.
+ *
+ * Exported because the query KEY is built from it, so the key and the request
+ * are the same value by construction.
+ *
+ * `include_deleted` is sent ONLY when the caller asked for a value, and the
+ * server's own default is `true`. Sending it always would be harmless; leaving
+ * it out when unasked keeps the cache key of a plain read from depending on
+ * this pair's opinion about a server default.
+ */
+export function categoryListParams(
+  params: CategoryListParams = {}
+): Record<string, string | number | boolean | undefined> {
+  const query: Record<string, string | number | boolean | undefined> = {};
+  if (params.minRevision !== undefined) query["min_revision"] = params.minRevision;
+  if (params.maxRevision !== undefined) query["max_revision"] = params.maxRevision;
+  if (params.includeDeleted !== undefined) {
+    query["include_deleted"] = params.includeDeleted;
+  }
+  if (params.page !== undefined) query["page"] = params.page;
+  if (params.pageSize !== undefined) query["page_size"] = params.pageSize;
+  return query;
+}
+
+export function createCategoriesApi(client: StapelClient): CategoriesApi {
+  return {
+    client,
+
+    list: (params, options) =>
+      client.get("/categories/", {
+        query: categoryListParams(params),
+        ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+      }),
+
+    children: (id, options) =>
+      client.get(`/categories/${String(id)}/children/`, {
+        ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+      }),
+
+    carousel: (options) =>
+      client.get("/categories/carousel/", {
+        ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+      }),
+
+    features: (id, options) =>
+      client.get(`/categories/${String(id)}/features/`, {
+        ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+      }),
+
+    revision: (options) =>
+      client.get("/categories/revision/", {
+        ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+      }),
+  };
+}