@stapel/vocabularies-react 0.1.0

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@stapel/vocabularies-react",
+  "version": "0.1.0",
+  "description": "Reference vocabularies too large to inline into a category schema: term typeahead and code-to-label resolve behind the VocabularyClient seam, plus the antd term select.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/usestapel/stapel-react.git",
+    "directory": "packages/vocabularies-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",
+    "./llms.txt": "./llms.txt",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md",
+    "MODULE.md",
+    "CHANGELOG.md",
+    "manifest.json",
+    "llms.txt"
+  ],
+  "size-limit": [
+    {
+      "name": "index — the seam client and the hooks stay React-only: no antd",
+      "path": "dist/index.js",
+      "limit": "8 KB"
+    },
+    {
+      "name": "default — the antd term select must stay out of the main bundle",
+      "path": "dist/default/index.js",
+      "limit": "10 KB"
+    },
+    {
+      "name": "i18n/ru subpath (opt-in locale: en floor + ru UI)",
+      "path": "dist/i18n/ru.js",
+      "limit": "4 KB"
+    },
+    {
+      "name": "i18n/es subpath (opt-in locale: en floor + es UI)",
+      "path": "dist/i18n/es.js",
+      "limit": "4 KB"
+    }
+  ],
+  "peerDependencies": {
+    "@stapel/core": ">=0.20.0 <1.0.0",
+    "@stapel/tokens-antd": ">=0.8.0",
+    "@tanstack/react-query": "^5.0.0",
+    "antd": ">=5.20.0 <7",
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "@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",
+    "msw": "^2.10.2",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "size-limit": "^11.2.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4",
+    "@stapel/core": "^0.20.0",
+    "@stapel/tokens-antd": "^0.8.1",
+    "@stapel/tokens": "^0.6.0",
+    "@stapel/showcase": "^0.3.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.demo.json && tsc -p tsconfig.test.json && vitest run --exclude test/prodBundlePurity.test.ts",
+    "test:pack": "vitest run test/prodBundlePurity.test.ts",
+    "lint": "eslint .",
+    "size": "size-limit"
+  }
+}

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/vocabularies-react",
+  "version": "0.1.0",
+  "defined": [],
+  "flows": []
+}

package/src/api/extensions.ts

@@ -0,0 +1,7 @@
+/**
+ * Hand-authored API surface the codegen does not (yet) cover — browser-redirect
+ * URL builders, open-redirect guards, narrow domain type-guards, header
+ * conventions. Everything that CAN be derived from schema.json belongs in the
+ * generated operations (`api/vocabulariesApi.ts`), not here.
+ */
+export {};

package/src/api/generated/schema.ts

@@ -0,0 +1,236 @@
+// AUTO-GENERATED by scripts/gen-api.mjs — do not edit by hand.
+// Source: the backend module's own docs/schema.json (§17-native per-module contract).
+// Regenerate: pnpm gen:api   ·   Drift gate: pnpm gen:api:check
+export interface paths {
+    "/vocabularies/api/v1/vocabularies/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List vocabularies
+         * @description Every vocabulary this deployment holds, with its levels and revision. Cacheable: the ETag covers the highest revision and the number of vocabularies.
+         *
+         *     **Permissions:** `ReadOnlyOrStaff`
+         */
+        get: operations["vocabularies_api_v1_vocabularies_list"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/vocabularies/api/v1/vocabularies/{slug}/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Retrieve a vocabulary
+         * @description ``GET vocabularies/{slug}/`` — one vocabulary.
+         *
+         *     **Permissions:** `ReadOnlyOrStaff`
+         */
+        get: operations["vocabularies_api_v1_vocabularies_retrieve"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/vocabularies/api/v1/vocabularies/{slug}/terms/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Search the terms of one level
+         * @description A page of terms at `level`, optionally the children of a `parent` term at the level above, optionally matching `q`. Prefix matches rank before the rest, then the level's own sort order and label. `has_children` is what tells a cascading control whether to ask for the next level. `total` counts the whole filtered set, before limit and offset.
+         *
+         *     **Permissions:** `ReadOnlyOrStaff`
+         */
+        get: operations["vocabularies_api_v1_vocabularies_terms_retrieve"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/vocabularies/api/v1/vocabularies/{slug}/terms/resolve/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Resolve term codes to labels
+         * @description `{code: label}` for the codes named in `codes` (comma separated, at most 200 — the rest are ignored). Unknown codes are omitted, so a caller falls back to the code, which is what a stored DAO value does when its labels are missing.
+         *
+         *     **Permissions:** `ReadOnlyOrStaff`
+         */
+        get: operations["vocabularies_api_v1_vocabularies_terms_resolve_retrieve"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        /** @description One level of a vocabulary. */
+        Level: {
+            name: string;
+            /** @description Name of the level this one hangs off; null for a root level. */
+            parent?: string | null;
+        };
+        /** @description One term of one level. */
+        Term: {
+            code: string;
+            /** @description Resolved for the request's Accept-Language when the term carries a translation, otherwise the term's own label. */
+            label: string;
+            level: string;
+            /** @description Whether this term has any child term — what tells a cascading control whether to ask for the next level. */
+            has_children: boolean;
+        };
+        /** @description One page of terms plus the size of the whole filtered set. */
+        TermPage: {
+            results: components["schemas"]["Term"][];
+            /** @description Number of terms matching level/parent/q, before limit and offset. */
+            total: number;
+        };
+        /** @description A vocabulary as the catalogue endpoints render it. */
+        Vocabulary: {
+            slug: string;
+            name: string;
+            levels: components["schemas"]["Level"][];
+            term_count: number;
+            /** @description Cache key of the whole vocabulary; also the ETag and the vocabulary.changed payload. */
+            revision: number;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    vocabularies_api_v1_vocabularies_list: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Vocabulary"][];
+                };
+            };
+        };
+    };
+    vocabularies_api_v1_vocabularies_retrieve: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                slug: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Vocabulary"];
+                };
+            };
+        };
+    };
+    vocabularies_api_v1_vocabularies_terms_retrieve: {
+        parameters: {
+            query: {
+                /** @description Level to list. Required. */
+                level: string;
+                /** @description Page size, 1..200 (default 50). */
+                limit?: number;
+                /** @description Rows to skip. */
+                offset?: number;
+                /** @description Code of a term at the parent level; restricts the page to its children. */
+                parent?: string;
+                /** @description Case-insensitive substring of the label. */
+                q?: string;
+            };
+            header?: never;
+            path: {
+                slug: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TermPage"];
+                };
+            };
+        };
+    };
+    vocabularies_api_v1_vocabularies_terms_resolve_retrieve: {
+        parameters: {
+            query: {
+                /** @description Comma-separated term codes, at most 200. */
+                codes: string;
+                /** @description Level the codes belong to. Required. */
+                level: string;
+            };
+            header?: never;
+            path: {
+                slug: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+        };
+    };
+}

package/src/api/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Wire types for the stapel-vocabularies HTTP contract — **derived from the generated
+ * OpenAPI surface** (frontend-standard §2/§3), never hand-maintained. The
+ * single source of truth is `components["schemas"]` from this pair's own
+ * package-LOCAL generated schema (`./generated/schema.js`, produced by
+ * `pnpm gen:api` from stapel-vocabularies's OWN `docs/schema.json` — the §17-native
+ * per-module contract). Alias the schemas this pair uses under local names
+ * here; do NOT write parallel response bodies.
+ */
+import type { components } from "./generated/schema.js";
+
+/** The generated schema table — the one source of truth for wire shapes. */
+export type Schemas = components["schemas"];
+
+/** A vocabulary as the catalogue endpoints render it. */
+export type Vocabulary = Schemas["Vocabulary"];
+
+/** One level of a vocabulary — `parent` names the level above, null at the root. */
+export type Level = Schemas["Level"];
+
+/** One term of one level. `has_children` is what tells a cascading control
+ * whether there is another column to ask for. */
+export type Term = Schemas["Term"];
+
+/** One page of terms plus the size of the whole filtered set (`total` counts
+ * before `limit`/`offset`, so a control can say "50 of 14 962"). */
+export type TermPage = Schemas["TermPage"];

package/src/api/vocabulariesApi.ts

@@ -0,0 +1,17 @@
+import type { StapelClient } from "@stapel/core";
+
+/**
+ * The pair's typed operation surface. Today a thin holder over the injected
+ * {@link StapelClient}; the named, typed operations (`vocabularies.<op>()`) will
+ * be GENERATED from schema.json operationIds by gen-api v2 (task
+ * `core-typed-ops`). Until then add hand-authored operations here and put
+ * anything that can never be derived from the schema in `api/extensions.ts`,
+ * each flagged with WHY the codegen does not cover it.
+ */
+export interface VocabulariesApi {
+  readonly client: StapelClient;
+}
+
+export function createVocabulariesApi(client: StapelClient): VocabulariesApi {
+  return { client };
+}

package/src/client.ts

@@ -0,0 +1,176 @@
+/**
+ * `createVocabularyClient` — the two reads a ref feature needs, over the
+ * stapel-vocabularies wire.
+ *
+ * ── Why this is a bare `fetch` client and not the pair's StapelClient ───────
+ *
+ * A `ref_select` reaches its terms through a seam
+ * (`VocabularyClient`) that `@stapel/attributes-react` DECLARES and this
+ * package SATISFIES — structurally, without either importing the other, so two
+ * L2 pairs stay independently releasable. The seam is two async functions and
+ * nothing else: no query client, no auth runtime, no provider. Anything this
+ * function returned that needed React context could not be handed to
+ * `<VocabularyClientProvider value={…}>` at a container's composition root,
+ * which is the one call site the seam exists for.
+ *
+ * Both endpoints are public reads (`ReadOnlyOrStaff`, ETag'd on the
+ * vocabulary's revision, no session), so there is no token to carry and
+ * nothing for the auth interceptors to do. A host that DOES need headers
+ * passes its own `fetch`.
+ *
+ * The caching the seam deliberately leaves out lives in this package's hooks
+ * (`useTermLabels` is a TanStack query; `useTermSearch` supersedes in flight),
+ * not in the client — a raw client is what makes the seam testable and what
+ * lets a host wrap it.
+ */
+import { toStapelApiError } from "@stapel/core";
+import type { Term, TermPage } from "./api/types.js";
+
+/** One term of a vocabulary level, as `GET …/terms/` returns it.
+ *
+ * A structural twin of `@stapel/attributes-react`'s `VocabularyTerm` — the same
+ * three fields, `has_children` spelled the wire's way. The declaration is not
+ * shared because the two packages must not import each other; the assignment
+ * is proven by `test/clientShape.test.ts`. */
+export interface VocabularyTerm {
+  readonly code: string;
+  readonly label: string;
+  readonly has_children?: boolean;
+}
+
+/**
+ * The seam `@stapel/attributes-react` declares and this package implements.
+ *
+ * ATTRIBUTES-REACT OWNS THIS SHAPE. The copy here exists so a host can name
+ * the type without depending on the attributes pair, and
+ * `test/clientShape.test.ts` holds a third, hand-transcribed copy of the
+ * upstream declaration that the value returned below is assigned to — so a
+ * drift in either package is a red build here rather than a runtime hole in a
+ * storefront that wired the two together.
+ */
+export interface VocabularyClient {
+  /** Terms of one level, narrowed by `query` and — when the caller has a
+   * parent term — by that term's code. An empty `query` means "the first page
+   * of this level", which is what a dropdown opens on. `signal` is honoured. */
+  search(
+    vocabulary: string,
+    level: string,
+    query: string,
+    parent?: string,
+    signal?: AbortSignal
+  ): Promise<readonly VocabularyTerm[]>;
+  /** `{code: label}` for codes already stored somewhere. Unknown codes are
+   * omitted by the server, so a caller falls back to the code itself. */
+  resolve(
+    vocabulary: string,
+    level: string,
+    codes: readonly string[]
+  ): Promise<Readonly<Record<string, string>>>;
+}
+
+export interface CreateVocabularyClientOptions {
+  /** Where stapel-vocabularies is mounted, e.g. `/vocabularies/api/v1/` or an
+   * absolute origin. A missing trailing slash is added. */
+  readonly baseUrl: string;
+  /** Transport override — a host's authenticated/instrumented `fetch`.
+   * Defaults to the global one. */
+  readonly fetch?: typeof globalThis.fetch;
+  /** Page size for {@link VocabularyClient.search}; the server caps it at 200
+   * and defaults to 50. */
+  readonly limit?: number;
+}
+
+/** The page a typeahead opens on. Matches the server's own default, so the
+ * parameter is sent for explicitness rather than to change behaviour. */
+export const DEFAULT_TERM_LIMIT = 50;
+
+/** The server refuses more than this many codes per resolve, and silently
+ * ignores the tail — so the client splits instead of losing labels. */
+export const RESOLVE_BATCH = 200;
+
+function withSlash(baseUrl: string): string {
+  return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+}
+
+/**
+ * `{code: label}` out of a body typed as `Record<string, unknown>` (the
+ * contract declares `additionalProperties: {}`). Non-string values are
+ * dropped rather than stringified: a label that is not a string is a server
+ * the caller should fall back from, and `"[object Object]"` in a dropdown is
+ * worse than the code.
+ */
+function labelsOf(body: unknown): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (typeof body !== "object" || body === null) return out;
+  for (const [code, label] of Object.entries(body as Record<string, unknown>)) {
+    if (typeof label === "string") out[code] = label;
+  }
+  return out;
+}
+
+export function createVocabularyClient(
+  options: CreateVocabularyClientOptions
+): VocabularyClient {
+  const base = withSlash(options.baseUrl);
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const limit = options.limit ?? DEFAULT_TERM_LIMIT;
+
+  async function read(url: string, signal?: AbortSignal): Promise<unknown> {
+    let response: Response;
+    try {
+      response = await doFetch(url, {
+        method: "GET",
+        headers: { accept: "application/json" },
+        ...(signal !== undefined ? { signal } : {}),
+      });
+    } catch (cause) {
+      // An abort is the CALLER's decision, not a failure: rethrow it as-is so
+      // `signal.aborted` still discriminates it. Folding it into the error
+      // dialect would make a superseded keystroke look like a dead backend.
+      if (signal?.aborted === true) throw cause;
+      throw toStapelApiError(cause);
+    }
+    if (!response.ok) {
+      // One dialect at the single rethrow point (core `errors.ts`): the body is
+      // the backend's envelope, the status is the response's.
+      const body: unknown = await response.json().catch(() => undefined);
+      throw toStapelApiError(body, response.status);
+    }
+    return await response.json();
+  }
+
+  return {
+    async search(vocabulary, level, query, parent, signal) {
+      const params = new URLSearchParams();
+      params.set("level", level);
+      // OMITTED, not empty: `parent=` would ask the server for the children of
+      // a term whose code is the empty string, which is a level with nothing in
+      // it — the opposite of "the whole level", which is what no parent means.
+      if (parent !== undefined && parent.length > 0) params.set("parent", parent);
+      params.set("q", query);
+      params.set("limit", String(limit));
+      const url = `${base}vocabularies/${encodeURIComponent(vocabulary)}/terms/?${params.toString()}`;
+      const page = (await read(url, signal)) as TermPage | undefined;
+      const results: readonly Term[] = page?.results ?? [];
+      return results.map((term) => ({
+        code: term.code,
+        label: term.label,
+        has_children: term.has_children,
+      }));
+    },
+
+    async resolve(vocabulary, level, codes) {
+      const wanted = codes.filter((code) => code.length > 0);
+      if (wanted.length === 0) return {};
+      const out: Record<string, string> = {};
+      for (let at = 0; at < wanted.length; at += RESOLVE_BATCH) {
+        const params = new URLSearchParams();
+        params.set("level", level);
+        params.set("codes", wanted.slice(at, at + RESOLVE_BATCH).join(","));
+        const url = `${base}vocabularies/${encodeURIComponent(vocabulary)}/terms/resolve/?${params.toString()}`;
+        Object.assign(out, labelsOf(await read(url)));
+      }
+      return out;
+    },
+  };
+}