@stapel/vocabularies-react 0.1.0

package/src/model/runtime.ts

@@ -0,0 +1,25 @@
+import { createModuleRuntime } from "@stapel/core";
+import type { CreateModuleRuntimeOptions, ModuleRuntime } from "@stapel/core";
+import { createVocabulariesApi } from "../api/vocabulariesApi.js";
+import type { VocabulariesApi } from "../api/vocabulariesApi.js";
+
+/**
+ * The wired vocabularies runtime — core's `ModuleRuntime` bound to this pair's
+ * API (slim wave §21/S2: the plumbing lives once in `@stapel/core`'s
+ * `createModuleRuntime`/`createModuleContext`; this module only binds the
+ * module-prefixed names). The returned `client` is what the host injects
+ * into core's `StapelConfigProvider` (as the default or the `"vocabularies"`
+ * module client), preserving the client-injection fork seam
+ * (frontend-standard §7.2). Auth token/refresh and the verification-403 seam
+ * are supplied by the host's auth runtime on the shared client — this pair
+ * does not re-implement them.
+ */
+export type VocabulariesRuntime = ModuleRuntime<VocabulariesApi>;
+
+export type CreateVocabulariesRuntimeOptions = CreateModuleRuntimeOptions;
+
+export function createVocabulariesRuntime(
+  options: CreateVocabulariesRuntimeOptions
+): VocabulariesRuntime {
+  return createModuleRuntime(createVocabulariesApi, options);
+}

package/src/model/useTermLabels.ts

@@ -0,0 +1,72 @@
+/**
+ * `useTermLabels` — `{code: label}` for codes a page already HOLDS.
+ *
+ * The other half of the seam. A stored answer on a listing is a list of term
+ * CODES (`["apple", "iphone-15-pro"]`); the labels are not stored with it,
+ * because a label is translated and a code is not. So a reopened draft, a
+ * filter chip, a facet row — anything showing an answer somebody already gave
+ * — has to ask for the words.
+ *
+ * Unlike a search this IS a cacheable resource: the same codes give the same
+ * labels until the vocabulary's revision moves, and several controls on one
+ * page routinely ask for the same set. So it is a TanStack query keyed through
+ * the factory, and the answer is a {@link LoadState} rather than a bare map —
+ * `{}` would say "these codes have no labels" in exactly the same words as
+ * "nobody has asked yet" and "the request failed" (core `loadState.ts`).
+ *
+ * The fallback a caller wants is almost always the CODE ITSELF, which is what
+ * {@link termLabel} does: the stored answer is the truth, and a blank control
+ * is a worse lie than a slug.
+ */
+import { useQuery } from "@tanstack/react-query";
+import { loadStateFromQuery } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import type { VocabularyClient } from "../client.js";
+import { vocabulariesQueryKeys } from "./queryKeys.js";
+
+export interface TermLabelsOptions {
+  readonly vocabulary: string;
+  readonly level: string;
+  readonly codes: readonly string[];
+}
+
+export type TermLabels = Readonly<Record<string, string>>;
+
+/**
+ * Labels for `codes`, as a load state. Disabled — and therefore `loading`,
+ * never `ready` with an empty map — while there is no client, no pointer or
+ * nothing to resolve.
+ */
+export function useTermLabels(
+  client: VocabularyClient | null,
+  options: TermLabelsOptions
+): LoadState<TermLabels> {
+  const { vocabulary, level, codes } = options;
+  const wanted = codes.filter((code) => code.length > 0);
+  const enabled =
+    client !== null && vocabulary.length > 0 && level.length > 0 && wanted.length > 0;
+  const query = useQuery({
+    queryKey: vocabulariesQueryKeys.termLabels(vocabulary, level, wanted),
+    enabled,
+    queryFn: async (): Promise<TermLabels> => {
+      // `enabled` already guarantees this, and the compiler does not know it.
+      if (client === null) return {};
+      return await client.resolve(vocabulary, level, wanted);
+    },
+  });
+  return loadStateFromQuery(query);
+}
+
+/**
+ * The one right way to READ that state for display: a resolved label, or the
+ * code itself while the answer is in flight, when the load failed, or when the
+ * server omitted the code because it does not know it.
+ *
+ * All four fall back the same way ON PURPOSE — the code is what the person's
+ * answer literally is, so showing it is never wrong, only less kind. A control
+ * that needs to distinguish them (an admin screen auditing dead codes) reads
+ * the {@link LoadState} directly.
+ */
+export function termLabel(labels: LoadState<TermLabels>, code: string): string {
+  return labels.status === "ready" ? (labels.data[code] ?? code) : code;
+}

package/src/model/useTermSearch.ts

@@ -0,0 +1,118 @@
+/**
+ * `useTermSearch` — a typeahead over ONE vocabulary level.
+ *
+ * The level is the wrong size to hold (529 phone vendors is fine, 14 962
+ * models is not), so the options ARE the answer to the current query and the
+ * hook's whole job is to make sure the answer on screen belongs to the query
+ * on screen:
+ *
+ *  - a keystroke DEBOUNCES (250 ms by default) — one request per pause, not
+ *    per character;
+ *  - a new request ABORTS the one before it, and a resolved-but-superseded
+ *    answer is dropped, because the network does not promise order;
+ *  - opening is not typing: the first page is fetched immediately (a spinner
+ *    that starts a quarter second after the click reads as a dead control),
+ *    ONCE per (vocabulary, level, parent) — antd reports the dropdown as
+ *    opening on every keystroke, so a naive `open()` is a request storm nobody
+ *    can see in a screenshot;
+ *  - a parent CHANGE empties the list: what is listed are the previous
+ *    parent's children and must not stay pickable.
+ *
+ * The client is a PARAMETER, not a context read: this hook is one half of the
+ * seam `@stapel/attributes-react` declares, and a host wires the client at its
+ * composition root. Passing `null` is a supported state (the control draws its
+ * unavailable notice) rather than a crash.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { VocabularyClient, VocabularyTerm } from "../client.js";
+
+/** The pause after the last keystroke before a query goes to the server. Long
+ * enough that typing a word is one request, short enough that it still feels
+ * like the control answered. Mirrors the ref editors in attributes-react. */
+export const TERM_SEARCH_DEBOUNCE_MS = 250;
+
+export interface TermSearchOptions {
+  readonly vocabulary: string;
+  readonly level: string;
+  /** Code of a term at the level above; narrows the page to its children.
+   * `undefined` means the whole level. */
+  readonly parent?: string | undefined;
+  readonly debounceMs?: number;
+}
+
+export interface TermSearchState {
+  readonly terms: readonly VocabularyTerm[];
+  readonly loading: boolean;
+  /** A person typed. Debounced and superseding. */
+  search: (query: string) => void;
+  /** A dropdown opened. Fetches the first page immediately, once per
+   * (vocabulary, level, parent). */
+  open: () => void;
+}
+
+export function useTermSearch(
+  client: VocabularyClient | null,
+  options: TermSearchOptions
+): TermSearchState {
+  const { vocabulary, level, parent, debounceMs = TERM_SEARCH_DEBOUNCE_MS } = options;
+  const [terms, setTerms] = useState<readonly VocabularyTerm[]>([]);
+  const [loading, setLoading] = useState(false);
+  const inFlight = useRef<AbortController | undefined>(undefined);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const asked = useRef(false);
+
+  const run = useCallback(
+    (query: string): void => {
+      if (client === null || vocabulary.length === 0 || level.length === 0) return;
+      inFlight.current?.abort();
+      const controller = new AbortController();
+      inFlight.current = controller;
+      setLoading(true);
+      client
+        .search(vocabulary, level, query, parent, controller.signal)
+        .then((found) => {
+          if (controller.signal.aborted) return;
+          setTerms(found);
+          setLoading(false);
+        })
+        .catch(() => {
+          // A superseded request is not a failure and must not clear the list
+          // the CURRENT request is about to fill.
+          if (controller.signal.aborted) return;
+          setTerms([]);
+          setLoading(false);
+        });
+    },
+    [client, vocabulary, level, parent]
+  );
+
+  useEffect(() => {
+    asked.current = false;
+    setTerms([]);
+  }, [client, vocabulary, level, parent]);
+
+  useEffect(
+    () => () => {
+      if (timer.current !== undefined) clearTimeout(timer.current);
+      inFlight.current?.abort();
+    },
+    []
+  );
+
+  const search = useCallback(
+    (query: string): void => {
+      asked.current = true;
+      if (timer.current !== undefined) clearTimeout(timer.current);
+      timer.current = setTimeout(() => run(query), debounceMs);
+    },
+    [run, debounceMs]
+  );
+
+  const open = useCallback((): void => {
+    if (asked.current) return;
+    asked.current = true;
+    run("");
+  }, [run]);
+
+  return { terms, loading, search, open };
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "_comment": "Self-contained on purpose: standalone-buildable per frontend-standard §7. Mirrors the root tsconfig.base.json settings.",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "isolatedModules": true,
+    "isolatedDeclarations": true,
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}