@stapel/vocabularies-react 0.1.0

package/src/default/VocabularyTermSelect.tsx

@@ -0,0 +1,147 @@
+/**
+ * `<VocabularyTermSelect/>` — one vocabulary level as a typeahead.
+ *
+ * The SAME control `@stapel/attributes-react`'s `ref_select` editor draws,
+ * shipped on its own so the places a composer is not — a facet filter, an
+ * admin form, a bulk-edit row — do not each grow their own. The two are
+ * deliberately separate components rather than one imported across the seam:
+ * the editor's props are the attributes value-editor contract (a `FeatureDef`,
+ * `siblings`, a rule-narrowed config) and this one's are a vocabulary pointer,
+ * and collapsing them would make the two L2 pairs depend on each other for a
+ * hundred lines of antd.
+ *
+ * What it owes a person, and where each part lives:
+ *
+ *  - the options ARE the answer to the current query, so `filterOption={false}`
+ *    — letting antd filter them again would hide rows the server deliberately
+ *    ranked (a prefix match first, a label matched in another language);
+ *  - typing is debounced and superseding (`useTermSearch`);
+ *  - a code the control already HOLDS is resolved to its label
+ *    (`useTermLabels`) and kept in the option list even when the current page
+ *    does not contain it — otherwise reopening a saved filter would silently
+ *    empty the control;
+ *  - no client is a LOUD state, not an empty dropdown: a control that cannot
+ *    reach its terms and looks like one that found none is how a person ends
+ *    up unable to answer a question nobody told them was broken.
+ */
+import { useMemo } from "react";
+import type { ReactElement } from "react";
+import { Alert, Select } from "antd";
+import { useT } from "@stapel/core";
+import { SkinTheme } from "@stapel/tokens-antd/skin";
+import type { VocabularyClient } from "../client.js";
+import { useTermSearch } from "../model/useTermSearch.js";
+import { useTermLabels, termLabel } from "../model/useTermLabels.js";
+import { VOCABULARIES_I18N_KEYS } from "../i18n/keys.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface VocabularyTermSelectProps extends ThemeModeProp {
+  /** The seam. `null` draws the unavailable notice — see the module header. */
+  readonly client: VocabularyClient | null;
+  readonly vocabulary: string;
+  readonly level: string;
+  /** Code of a term at the level above; narrows the list to its children. */
+  readonly parent?: string | undefined;
+  /** The codes currently chosen. Always a list, even single-select — a term
+   * value is a list on the wire. */
+  readonly value?: readonly string[] | undefined;
+  readonly onChange?: ((codes: readonly string[]) => void) | undefined;
+  /** Several terms at once (a facet filter); default is one. */
+  readonly multiple?: boolean | undefined;
+  /** Upper bound for a multiple select. */
+  readonly maxCount?: number | undefined;
+  readonly disabled?: boolean | undefined;
+  readonly id?: string | undefined;
+  readonly status?: "error" | "warning" | undefined;
+}
+
+export function VocabularyTermSelect(
+  props: VocabularyTermSelectProps
+): ReactElement {
+  const t = useT();
+  const { client, vocabulary, level, parent } = props;
+  const codes = useMemo(
+    () => (props.value ?? []).filter((code) => code.length > 0),
+    [props.value]
+  );
+
+  const { terms, loading, search, open } = useTermSearch(client, {
+    vocabulary,
+    level,
+    parent,
+  });
+  const labels = useTermLabels(client, { vocabulary, level, codes });
+
+  // A held code the current page does not contain still has to be visible and
+  // pickable, so it is prepended rather than looked up in `terms`.
+  const options = useMemo(
+    () => [
+      ...codes
+        .filter((code) => !terms.some((term) => term.code === code))
+        .map((code) => ({ value: code, label: termLabel(labels, code) })),
+      ...terms.map((term) => ({ value: term.code, label: term.label })),
+    ],
+    [codes, terms, labels]
+  );
+
+  if (client === null || vocabulary.length === 0 || level.length === 0) {
+    return (
+      <SkinTheme
+        surface="bare"
+        {...(props.mode !== undefined ? { mode: props.mode } : {})}
+      >
+        <Alert
+          type="warning"
+          showIcon
+          data-testid="vocabulary-term-select-unavailable"
+          title={t(VOCABULARIES_I18N_KEYS.termSelectUnavailableTitle)}
+          description={t(VOCABULARIES_I18N_KEYS.termSelectUnavailable)}
+        />
+      </SkinTheme>
+    );
+  }
+
+  const multiple = props.multiple === true;
+  const onChange = props.onChange;
+
+  return (
+    <SkinTheme
+      surface="bare"
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
+      <Select
+        {...(props.id !== undefined ? { id: props.id } : {})}
+        data-testid="vocabulary-term-select"
+        style={{ width: "100%" }}
+        showSearch
+        filterOption={false}
+        options={options}
+        loading={loading}
+        disabled={props.disabled === true}
+        {...(props.status !== undefined ? { status: props.status } : {})}
+        {...(multiple ? { mode: "multiple" as const } : {})}
+        {...(multiple && props.maxCount !== undefined
+          ? { maxCount: props.maxCount }
+          : {})}
+        placeholder={t(VOCABULARIES_I18N_KEYS.termSelectPlaceholder)}
+        // `null` while loading, so antd draws its own spinner instead of
+        // saying "no matches" about a question that has not been answered yet.
+        notFoundContent={loading ? null : t(VOCABULARIES_I18N_KEYS.termSelectNoMatches)}
+        value={multiple ? codes : (codes[0] ?? null)}
+        onDropdownVisibleChange={(visible: boolean) => {
+          if (visible) open();
+        }}
+        onSearch={search}
+        onChange={(next: string | readonly string[] | null) => {
+          const picked =
+            next === null || next === undefined
+              ? []
+              : Array.isArray(next)
+                ? [...(next as readonly string[])]
+                : [next as string];
+          onChange?.(picked.filter((code) => code.length > 0));
+        }}
+      />
+    </SkinTheme>
+  );
+}

package/src/default/index.ts

@@ -0,0 +1,15 @@
+/**
+ * `@stapel/vocabularies-react/default` — the pair's default AntD skin (§54: a pair ships a
+ * FEATURE, not only a bag). A separate entry point, so a host that brings its
+ * own visuals never pulls `antd` or the token bridge into its bundle;
+ * importing this subpath is the opt-in.
+ *
+ * ```tsx
+ * import { VocabularyTermSelect } from "@stapel/vocabularies-react/default";
+ * // under core's <I18nProvider>; the client is a prop, not a context read:
+ * <VocabularyTermSelect client={client} vocabulary="avito-phones" level="Vendor" … />
+ * ```
+ */
+export { VocabularyTermSelect } from "./VocabularyTermSelect.js";
+export type { VocabularyTermSelectProps } from "./VocabularyTermSelect.js";
+export type { ThemeModeProp } from "./types.js";

package/src/default/types.ts

@@ -0,0 +1,11 @@
+/**
+ * The one prop every skin component in this package shares.
+ *
+ * `mode` is OPTIONAL and has no default here on purpose: the shared
+ * `SkinTheme` (`@stapel/tokens-antd/skin`) follows the host's theme when
+ * nobody overrides it, and a `mode = "light"` default in a pair is how a dark
+ * host ends up with one white rectangle in the middle of its app.
+ */
+export interface ThemeModeProp {
+  readonly mode?: "light" | "dark";
+}

package/src/flows/errors.ts

@@ -0,0 +1,16 @@
+import { toFlowError as coreToFlowError } from "@stapel/core";
+import type { FlowError } from "@stapel/core";
+
+export type { FlowError } from "@stapel/core";
+export { isErrorCode } from "@stapel/core";
+
+/**
+ * Fold any thrown value into a {@link FlowError} using this pair's own
+ * module-scoped fallback key (`vocabularies.error.unknown`, an en string in
+ * {@link vocabulariesI18nBundleEn}) so a non-`StapelApiError` fault still renders
+ * real copy rather than a raw key. The primitive lives in `@stapel/core`
+ * (frontend-core-architecture §4b); this wrapper only pins the fallback.
+ */
+export function toFlowError(error: unknown): FlowError {
+  return coreToFlowError(error, "vocabularies.error.unknown");
+}

package/src/flows/registry.ts

@@ -0,0 +1,32 @@
+/**
+ * Zero-flow registry shim (slim wave §21/S3). stapel-vocabularies annotates no
+ * `@flow_step` yet — its backend `docs/flows.json` carries no `vocabularies.*`
+ * flows, so `gen:flows` skips emission for this pair (no `flows/generated/`
+ * scaffolding). This hand-written shim preserves the pair's public
+ * flow-registry surface at its zero-flow shape.
+ *
+ * When the backend annotates flows, `pnpm gen:flows` emits
+ * `./generated/flows.gen.ts` again — replace these exports with re-exports
+ * from it (the shapes match by construction) and delete this file.
+ */
+export const VOCABULARIES_FLOWS = {} as const;
+
+/** Canonical flow ids present in flows.json (none yet — see above). */
+export type VocabulariesFlowId = keyof typeof VOCABULARIES_FLOWS;
+
+export type VocabulariesFlowSpec = (typeof VOCABULARIES_FLOWS)[VocabulariesFlowId];
+
+export interface FlowEndpoint {
+  readonly method: string;
+  readonly path: string;
+}
+
+/** All HTTP endpoints a flow touches, in step order (for the contract test / MSW). */
+export function flowEndpoints(id: VocabulariesFlowId): readonly FlowEndpoint[] {
+  // Same widened body as the generated registry's — valid for the zero-flow
+  // shape AND correct once flows exist.
+  const spec = VOCABULARIES_FLOWS[id] as
+    | { readonly steps: readonly { readonly endpoints: readonly FlowEndpoint[] }[] }
+    | undefined;
+  return spec ? spec.steps.flatMap((s) => s.endpoints) : [];
+}

package/src/headless/VocabulariesProvider.tsx

@@ -0,0 +1,20 @@
+import type { ReactElement, ReactNode } from "react";
+import { ModuleProvider } from "../model/context.js";
+import type { VocabulariesRuntime } from "../model/runtime.js";
+
+/**
+ * Provides the wired {@link VocabulariesRuntime} to every vocabularies hook and
+ * headless component below it. Bring your own visual shell — this component
+ * renders nothing of its own. (Core's `createModuleContext` provider, bound
+ * to this pair — slim wave §21/S2.)
+ *
+ * ```tsx
+ * const runtime = createVocabulariesRuntime({ baseUrl: "/vocabularies/api/v1/" });
+ * // give runtime.client to core's <StapelConfigProvider config={{ client }}>
+ * <VocabulariesProvider runtime={runtime}>{app}</VocabulariesProvider>
+ * ```
+ */
+export const VocabulariesProvider: (props: {
+  runtime: VocabulariesRuntime;
+  children: ReactNode;
+}) => ReactElement = ModuleProvider;

package/src/i18n/errorsMap.ts

@@ -0,0 +1,31 @@
+/**
+ * The pair's error map (frontend-standard §4 checklist #7, frontend-core §2.5):
+ * the generated `code → { status, params, remediation, en }` catalog plus a
+ * tiny `explain()` lookup. Backs the manifest `errors` block and gives hosts a
+ * mechanical UX branch beside `t(code, params)`. The map itself is generated
+ * from the backend registry (`pnpm gen:errors`); this file only adds the lookup
+ * helper and re-exports the public surface.
+ */
+import { VOCABULARIES_ERRORS } from "./generated/errors.gen.js";
+import type { Remediation } from "./generated/errors.gen.js";
+
+export {
+  VOCABULARIES_ERRORS,
+  VOCABULARIES_ERROR_CODES,
+  vocabulariesErrorBundleEn,
+} from "./generated/errors.gen.js";
+export type {
+  VocabulariesErrorCode,
+  VocabulariesErrorSpec,
+  Remediation,
+} from "./generated/errors.gen.js";
+
+/**
+ * Resolve a backend error code to its remediation hint, or `undefined` for a
+ * code this module doesn't know (e.g. a cross-cutting `stapel.http.*` fallback).
+ * Zero guessing at runtime — a static lookup over the generated map.
+ */
+export function explainVocabulariesError(code: string): Remediation | undefined {
+  return (VOCABULARIES_ERRORS as Record<string, { remediation: Remediation }>)[code]
+    ?.remediation;
+}

package/src/i18n/es.ts

@@ -0,0 +1,49 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { vocabulariesErrorBundleEs } from "./generated/errors.es.gen.js";
+import { vocabulariesI18nBundleEn } from "./keys.js";
+
+export { vocabulariesErrorBundleEs } from "./generated/errors.es.gen.js";
+
+/**
+ * Spanish bundle for vocabularies-react — shipped as the
+ * `@stapel/vocabularies-react/i18n/es` subpath (i18n-shipping.md §2) so the locale is
+ * opt-in: a host that never registers it never carries these strings (the main
+ * entry does not import this module).
+ *
+ * TWO SOURCES, ON PURPOSE — see the ru bundle's header: the generated
+ * `vocabulariesErrorBundleEs` covers the codes stapel-core owns, and the 3
+ * stapel-vocabularies owns are authored below until upstream ships a
+ * `translations/errors.es.json`.
+ */
+export const vocabulariesI18nBundleEs: I18nDictionary = {
+  // Backend error codes — generated es texts for every key core owns.
+  ...vocabulariesErrorBundleEs,
+
+  // Backend error codes stapel-vocabularies owns — authored here (see above).
+  "error.400.vocabularies_bad_parent":
+    "No hay ningún término «{parent}» en el nivel superior de «{level}»",
+  "error.404.vocabularies_level_not_found":
+    "El vocabulario «{vocabulary}» no tiene el nivel «{level}»",
+  "error.404.vocabularies_vocabulary_not_found": "Vocabulario no encontrado",
+
+  // vocabularies-react UI
+  "vocabularies.error.unknown": "Algo salió mal. Inténtalo de nuevo.",
+  "vocabularies.termSelect.placeholder": "Escribe para buscar…",
+  "vocabularies.termSelect.noMatches": "Ningún término coincide.",
+  "vocabularies.termSelect.unavailable.title": "No se puede cargar esta lista",
+  "vocabularies.termSelect.unavailable":
+    "Los valores de este campo vienen de un servicio de vocabularios que no está configurado aquí, así que no hay nada que elegir. Nadie puede responder a esta pregunta hasta que se conecte — avísanos, por favor.",
+};
+
+/**
+ * Register the Spanish bundle. The en bundle goes UNDER it
+ * (merge-priority convention): a key this locale has not translated yet
+ * degrades to ENGLISH, never to a raw key.
+ */
+export function registerVocabulariesI18nEs(
+  engine: I18nEngine,
+  locale = "es"
+): void {
+  engine.registerBundle(locale, vocabulariesI18nBundleEn);
+  engine.registerBundle(locale, vocabulariesI18nBundleEs);
+}

package/src/i18n/generated/errors.es.gen.ts

@@ -0,0 +1,64 @@
+// AUTO-GENERATED by scripts/gen-errors.mjs — do not edit by hand.
+// Source: stapel-auth canonical errors.json (backend codegen artifact).
+// Regenerate: pnpm gen:errors   ·   Drift gate: pnpm gen:errors:check
+// Locale source: backend translations/errors.es.json (locale catalog
+// beside the canonical errors.json — i18n-shipping.md §1).
+import type { VocabulariesErrorCode } from "./errors.gen.js";
+
+/**
+ * `es` texts for the backend error codes this catalog carries.
+ *
+ * PARTIAL, and deliberately typed to say so: 3 key(s) owned by
+ * stapel_vocabularies are absent, because that owner ships no locale catalog
+ * (ERRORS_LOCALE_EXEMPT_OWNERS). English for them still comes from the registry
+ * artifact via the en bundle; the pair layers its own authored `es`
+ * strings over this one until upstream ships translations. `Partial` is what
+ * makes the gap visible to TypeScript instead of a silent English fallback.
+ *
+ * Import from the pair's `./i18n/es` subpath, NOT the main entry, so
+ * the locale stays out of hosts that don't ship it.
+ */
+export const vocabulariesErrorBundleEs: Partial<Record<VocabulariesErrorCode, string>> = {
+  "error.400.bad_request": "Solicitud incorrecta",
+  "error.400.captcha_invalid": "La verificación del captcha ha fallado. Inténtalo de nuevo.",
+  "error.400.captcha_required": "Se requiere el token del captcha.",
+  "error.400.expected_list": "Se esperaba una lista de elementos",
+  "error.400.field.blank": "{field} no puede estar vacío",
+  "error.400.field.does_not_exist": "{field} no existe",
+  "error.400.field.invalid": "{field} no es válido",
+  "error.400.field.invalid_choice": "{field} no es una opción válida",
+  "error.400.field.max_length": "{field} debe tener como máximo {max_length} caracteres",
+  "error.400.field.max_value": "{field} debe ser como máximo {max_value}",
+  "error.400.field.min_length": "{field} debe tener al menos {min_length} caracteres",
+  "error.400.field.min_value": "{field} debe ser como mínimo {min_value}",
+  "error.400.field.null": "{field} no puede ser nulo",
+  "error.400.field.required": "{field} es obligatorio",
+  "error.400.field.unique": "{field} debe ser único",
+  "error.400.invalid_ad_id": "ID de anuncio no válido",
+  "error.400.validation_error": "Error de validación",
+  "error.400.verification_failed": "La verificación ha fallado",
+  "error.400.verification_invalid_factor": "Este factor de verificación no está disponible",
+  "error.401.unauthorized": "Se requiere autenticación",
+  "error.402.payment_required": "Se requiere pago",
+  "error.403.forbidden": "No tienes permiso para realizar esta acción",
+  "error.403.network_blocked": "No se permiten solicitudes desde esta red.",
+  "error.403.verification_enrollment_required": "Es necesario registrar un factor de verificación.",
+  "error.403.verification_required": "Se requiere verificación adicional",
+  "error.404.ad_not_found": "Anuncio no encontrado",
+  "error.404.not_found": "Recurso solicitado no encontrado",
+  "error.404.verification_challenge_not_found": "Desafío de verificación no encontrado o caducado",
+  "error.405.method_not_allowed": "Método no permitido",
+  "error.406.not_acceptable": "No aceptable",
+  "error.408.request_timeout": "Tiempo de espera de la solicitud agotado",
+  "error.409.conflict": "El recurso ya existe",
+  "error.410.gone": "El recurso se ha eliminado permanentemente",
+  "error.413.payload_too_large": "El cuerpo de la solicitud es demasiado grande",
+  "error.415.unsupported_media_type": "Tipo de contenido no compatible",
+  "error.422.unprocessable_entity": "Entidad no procesable",
+  "error.423.locked": "El recurso está bloqueado",
+  "error.423.verification_locked": "Demasiados intentos fallidos — verificación bloqueada",
+  "error.429.rate_limit": "Demasiados intentos. Inténtalo de nuevo en {retry_after_minutes} minutos.",
+  "error.429.too_many_requests": "Demasiadas solicitudes. Inténtalo de nuevo más tarde.",
+  "error.500.internal": "Algo salió mal",
+  "error.503.mandate_unavailable": "No se puede verificar el mandato del espacio de trabajo",
+};

package/src/i18n/generated/errors.gen.ts

@@ -0,0 +1,187 @@
+// AUTO-GENERATED by scripts/gen-errors.mjs — do not edit by hand.
+// Source: stapel-auth canonical errors.json (backend codegen artifact).
+// Regenerate: pnpm gen:errors   ·   Drift gate: pnpm gen:errors:check
+
+/**
+ * Remediation vocabulary (frontend-core-architecture §2.5). Declared by the
+ * backend on the error registry and consumed verbatim from its `errors.json`
+ * artifact. A host maps it to UX — retryable → "try again"; `wait_and_retry` →
+ * timer from `params.retry_after_minutes`; `verify` → the step-up seam;
+ * `fix_input` → highlight the offending field.
+ */
+export type Remediation =
+  | "retry"
+  | "wait_and_retry"
+  | "reauthenticate"
+  | "verify"
+  | "fix_input"
+  | "contact_support"
+  | "bug";
+
+export interface VocabulariesErrorSpec {
+  /** HTTP status the backend raises this key with. */
+  readonly status: number;
+  /** `{param}` interpolation slots present in the message. */
+  readonly params: readonly string[];
+  /** Remediation hint declared by the backend (see {@link Remediation}). */
+  readonly remediation: Remediation;
+  /** English fallback (source: stapel-auth errors.json). */
+  readonly en: string;
+}
+
+/**
+ * The VOCABULARIES_ERRORS map — every `error.*` key stapel-auth can raise, keyed by its
+ * canonical code. The single source of truth behind the en fallback bundle, the
+ * remediation lookup, and the manifest `errors` block.
+ */
+export const VOCABULARIES_ERRORS = {
+  "error.400.bad_request": { status: 400, params: [], remediation: "fix_input", en: "Bad request" },
+  "error.400.captcha_invalid": { status: 400, params: [], remediation: "retry", en: "Captcha verification failed. Please try again." },
+  "error.400.captcha_required": { status: 400, params: [], remediation: "retry", en: "Captcha token is required." },
+  "error.400.expected_list": { status: 400, params: [], remediation: "fix_input", en: "Expected a list of items" },
+  "error.400.field.blank": { status: 400, params: ["field"], remediation: "fix_input", en: "{field} may not be blank" },
+  "error.400.field.does_not_exist": { status: 400, params: ["field"], remediation: "fix_input", en: "{field} does not exist" },
+  "error.400.field.invalid": { status: 400, params: ["field"], remediation: "fix_input", en: "{field} is invalid" },
+  "error.400.field.invalid_choice": { status: 400, params: ["field"], remediation: "fix_input", en: "{field} is not a valid choice" },
+  "error.400.field.max_length": { status: 400, params: ["field","max_length"], remediation: "fix_input", en: "{field} must be at most {max_length} characters" },
+  "error.400.field.max_value": { status: 400, params: ["field","max_value"], remediation: "fix_input", en: "{field} must be at most {max_value}" },
+  "error.400.field.min_length": { status: 400, params: ["field","min_length"], remediation: "fix_input", en: "{field} must be at least {min_length} characters" },
+  "error.400.field.min_value": { status: 400, params: ["field","min_value"], remediation: "fix_input", en: "{field} must be at least {min_value}" },
+  "error.400.field.null": { status: 400, params: ["field"], remediation: "fix_input", en: "{field} may not be null" },
+  "error.400.field.required": { status: 400, params: ["field"], remediation: "fix_input", en: "{field} is required" },
+  "error.400.field.unique": { status: 400, params: ["field"], remediation: "fix_input", en: "{field} must be unique" },
+  "error.400.invalid_ad_id": { status: 400, params: [], remediation: "fix_input", en: "Invalid advertisement ID" },
+  "error.400.validation_error": { status: 400, params: [], remediation: "fix_input", en: "Validation error" },
+  "error.400.verification_failed": { status: 400, params: [], remediation: "verify", en: "Verification failed" },
+  "error.400.verification_invalid_factor": { status: 400, params: [], remediation: "verify", en: "This verification factor is not available" },
+  "error.400.vocabularies_bad_parent": { status: 400, params: ["parent","level"], remediation: "fix_input", en: "No term '{parent}' at the parent level of '{level}'" },
+  "error.401.unauthorized": { status: 401, params: [], remediation: "reauthenticate", en: "Authentication required" },
+  "error.402.payment_required": { status: 402, params: [], remediation: "retry", en: "Payment required" },
+  "error.403.forbidden": { status: 403, params: [], remediation: "retry", en: "You do not have permission to perform this action" },
+  "error.403.network_blocked": { status: 403, params: [], remediation: "contact_support", en: "Requests from this network are not allowed" },
+  "error.403.verification_enrollment_required": { status: 403, params: [], remediation: "verify", en: "Verification factor enrollment required" },
+  "error.403.verification_required": { status: 403, params: [], remediation: "verify", en: "Additional verification required" },
+  "error.404.ad_not_found": { status: 404, params: [], remediation: "retry", en: "Listing not found" },
+  "error.404.not_found": { status: 404, params: [], remediation: "retry", en: "Requested resource not found" },
+  "error.404.verification_challenge_not_found": { status: 404, params: [], remediation: "verify", en: "Verification challenge not found or expired" },
+  "error.404.vocabularies_level_not_found": { status: 404, params: ["vocabulary","level"], remediation: "retry", en: "Vocabulary '{vocabulary}' has no level '{level}'" },
+  "error.404.vocabularies_vocabulary_not_found": { status: 404, params: [], remediation: "retry", en: "Vocabulary not found" },
+  "error.405.method_not_allowed": { status: 405, params: [], remediation: "retry", en: "Method not allowed" },
+  "error.406.not_acceptable": { status: 406, params: [], remediation: "retry", en: "Not acceptable" },
+  "error.408.request_timeout": { status: 408, params: [], remediation: "retry", en: "Request timeout" },
+  "error.409.conflict": { status: 409, params: [], remediation: "fix_input", en: "Resource already exists" },
+  "error.410.gone": { status: 410, params: [], remediation: "retry", en: "Resource has been permanently removed" },
+  "error.413.payload_too_large": { status: 413, params: [], remediation: "retry", en: "Request body is too large" },
+  "error.415.unsupported_media_type": { status: 415, params: [], remediation: "retry", en: "Unsupported media type" },
+  "error.422.unprocessable_entity": { status: 422, params: [], remediation: "wait_and_retry", en: "Unprocessable entity" },
+  "error.423.locked": { status: 423, params: [], remediation: "wait_and_retry", en: "Resource is locked" },
+  "error.423.verification_locked": { status: 423, params: [], remediation: "wait_and_retry", en: "Too many failed attempts — verification locked" },
+  "error.429.rate_limit": { status: 429, params: ["retry_after_minutes"], remediation: "wait_and_retry", en: "Too many attempts. Try again in {retry_after_minutes} minutes." },
+  "error.429.too_many_requests": { status: 429, params: [], remediation: "wait_and_retry", en: "Too many requests. Please try again later." },
+  "error.500.internal": { status: 500, params: [], remediation: "contact_support", en: "Something went wrong" },
+  "error.503.mandate_unavailable": { status: 503, params: [], remediation: "retry", en: "Cannot verify workspace mandate right now" },
+} as const;
+
+export type VocabulariesErrorCode = keyof typeof VOCABULARIES_ERRORS;
+
+/** Every backend error code this module can surface, sorted. */
+export const VOCABULARIES_ERROR_CODES: readonly VocabulariesErrorCode[] = [
+  "error.400.bad_request",
+  "error.400.captcha_invalid",
+  "error.400.captcha_required",
+  "error.400.expected_list",
+  "error.400.field.blank",
+  "error.400.field.does_not_exist",
+  "error.400.field.invalid",
+  "error.400.field.invalid_choice",
+  "error.400.field.max_length",
+  "error.400.field.max_value",
+  "error.400.field.min_length",
+  "error.400.field.min_value",
+  "error.400.field.null",
+  "error.400.field.required",
+  "error.400.field.unique",
+  "error.400.invalid_ad_id",
+  "error.400.validation_error",
+  "error.400.verification_failed",
+  "error.400.verification_invalid_factor",
+  "error.400.vocabularies_bad_parent",
+  "error.401.unauthorized",
+  "error.402.payment_required",
+  "error.403.forbidden",
+  "error.403.network_blocked",
+  "error.403.verification_enrollment_required",
+  "error.403.verification_required",
+  "error.404.ad_not_found",
+  "error.404.not_found",
+  "error.404.verification_challenge_not_found",
+  "error.404.vocabularies_level_not_found",
+  "error.404.vocabularies_vocabulary_not_found",
+  "error.405.method_not_allowed",
+  "error.406.not_acceptable",
+  "error.408.request_timeout",
+  "error.409.conflict",
+  "error.410.gone",
+  "error.413.payload_too_large",
+  "error.415.unsupported_media_type",
+  "error.422.unprocessable_entity",
+  "error.423.locked",
+  "error.423.verification_locked",
+  "error.429.rate_limit",
+  "error.429.too_many_requests",
+  "error.500.internal",
+  "error.503.mandate_unavailable",
+];
+
+/**
+ * English fallback bundle — one string per backend key, so a `StapelApiError.code`
+ * never renders as a raw key. Merged UNDER the hand-polished UI copy in
+ * {@link authI18nBundleEn} (polish wins; this guarantees coverage).
+ */
+export const vocabulariesErrorBundleEn: Record<VocabulariesErrorCode, string> = {
+  "error.400.bad_request": "Bad request",
+  "error.400.captcha_invalid": "Captcha verification failed. Please try again.",
+  "error.400.captcha_required": "Captcha token is required.",
+  "error.400.expected_list": "Expected a list of items",
+  "error.400.field.blank": "{field} may not be blank",
+  "error.400.field.does_not_exist": "{field} does not exist",
+  "error.400.field.invalid": "{field} is invalid",
+  "error.400.field.invalid_choice": "{field} is not a valid choice",
+  "error.400.field.max_length": "{field} must be at most {max_length} characters",
+  "error.400.field.max_value": "{field} must be at most {max_value}",
+  "error.400.field.min_length": "{field} must be at least {min_length} characters",
+  "error.400.field.min_value": "{field} must be at least {min_value}",
+  "error.400.field.null": "{field} may not be null",
+  "error.400.field.required": "{field} is required",
+  "error.400.field.unique": "{field} must be unique",
+  "error.400.invalid_ad_id": "Invalid advertisement ID",
+  "error.400.validation_error": "Validation error",
+  "error.400.verification_failed": "Verification failed",
+  "error.400.verification_invalid_factor": "This verification factor is not available",
+  "error.400.vocabularies_bad_parent": "No term '{parent}' at the parent level of '{level}'",
+  "error.401.unauthorized": "Authentication required",
+  "error.402.payment_required": "Payment required",
+  "error.403.forbidden": "You do not have permission to perform this action",
+  "error.403.network_blocked": "Requests from this network are not allowed",
+  "error.403.verification_enrollment_required": "Verification factor enrollment required",
+  "error.403.verification_required": "Additional verification required",
+  "error.404.ad_not_found": "Listing not found",
+  "error.404.not_found": "Requested resource not found",
+  "error.404.verification_challenge_not_found": "Verification challenge not found or expired",
+  "error.404.vocabularies_level_not_found": "Vocabulary '{vocabulary}' has no level '{level}'",
+  "error.404.vocabularies_vocabulary_not_found": "Vocabulary not found",
+  "error.405.method_not_allowed": "Method not allowed",
+  "error.406.not_acceptable": "Not acceptable",
+  "error.408.request_timeout": "Request timeout",
+  "error.409.conflict": "Resource already exists",
+  "error.410.gone": "Resource has been permanently removed",
+  "error.413.payload_too_large": "Request body is too large",
+  "error.415.unsupported_media_type": "Unsupported media type",
+  "error.422.unprocessable_entity": "Unprocessable entity",
+  "error.423.locked": "Resource is locked",
+  "error.423.verification_locked": "Too many failed attempts — verification locked",
+  "error.429.rate_limit": "Too many attempts. Try again in {retry_after_minutes} minutes.",
+  "error.429.too_many_requests": "Too many requests. Please try again later.",
+  "error.500.internal": "Something went wrong",
+  "error.503.mandate_unavailable": "Cannot verify workspace mandate right now",
+};