@stapel/vocabularies-react 0.1.0

package/src/i18n/generated/errors.json

@@ -0,0 +1,351 @@
+[
+  {
+    "code": "error.400.bad_request",
+    "status": 400,
+    "params": [],
+    "remediation": "fix_input",
+    "en": "Bad request"
+  },
+  {
+    "code": "error.400.captcha_invalid",
+    "status": 400,
+    "params": [],
+    "remediation": "retry",
+    "en": "Captcha verification failed. Please try again."
+  },
+  {
+    "code": "error.400.captcha_required",
+    "status": 400,
+    "params": [],
+    "remediation": "retry",
+    "en": "Captcha token is required."
+  },
+  {
+    "code": "error.400.expected_list",
+    "status": 400,
+    "params": [],
+    "remediation": "fix_input",
+    "en": "Expected a list of items"
+  },
+  {
+    "code": "error.400.field.blank",
+    "status": 400,
+    "params": [
+      "field"
+    ],
+    "remediation": "fix_input",
+    "en": "{field} may not be blank"
+  },
+  {
+    "code": "error.400.field.does_not_exist",
+    "status": 400,
+    "params": [
+      "field"
+    ],
+    "remediation": "fix_input",
+    "en": "{field} does not exist"
+  },
+  {
+    "code": "error.400.field.invalid",
+    "status": 400,
+    "params": [
+      "field"
+    ],
+    "remediation": "fix_input",
+    "en": "{field} is invalid"
+  },
+  {
+    "code": "error.400.field.invalid_choice",
+    "status": 400,
+    "params": [
+      "field"
+    ],
+    "remediation": "fix_input",
+    "en": "{field} is not a valid choice"
+  },
+  {
+    "code": "error.400.field.max_length",
+    "status": 400,
+    "params": [
+      "field",
+      "max_length"
+    ],
+    "remediation": "fix_input",
+    "en": "{field} must be at most {max_length} characters"
+  },
+  {
+    "code": "error.400.field.max_value",
+    "status": 400,
+    "params": [
+      "field",
+      "max_value"
+    ],
+    "remediation": "fix_input",
+    "en": "{field} must be at most {max_value}"
+  },
+  {
+    "code": "error.400.field.min_length",
+    "status": 400,
+    "params": [
+      "field",
+      "min_length"
+    ],
+    "remediation": "fix_input",
+    "en": "{field} must be at least {min_length} characters"
+  },
+  {
+    "code": "error.400.field.min_value",
+    "status": 400,
+    "params": [
+      "field",
+      "min_value"
+    ],
+    "remediation": "fix_input",
+    "en": "{field} must be at least {min_value}"
+  },
+  {
+    "code": "error.400.field.null",
+    "status": 400,
+    "params": [
+      "field"
+    ],
+    "remediation": "fix_input",
+    "en": "{field} may not be null"
+  },
+  {
+    "code": "error.400.field.required",
+    "status": 400,
+    "params": [
+      "field"
+    ],
+    "remediation": "fix_input",
+    "en": "{field} is required"
+  },
+  {
+    "code": "error.400.field.unique",
+    "status": 400,
+    "params": [
+      "field"
+    ],
+    "remediation": "fix_input",
+    "en": "{field} must be unique"
+  },
+  {
+    "code": "error.400.invalid_ad_id",
+    "status": 400,
+    "params": [],
+    "remediation": "fix_input",
+    "en": "Invalid advertisement ID"
+  },
+  {
+    "code": "error.400.validation_error",
+    "status": 400,
+    "params": [],
+    "remediation": "fix_input",
+    "en": "Validation error"
+  },
+  {
+    "code": "error.400.verification_failed",
+    "status": 400,
+    "params": [],
+    "remediation": "verify",
+    "en": "Verification failed"
+  },
+  {
+    "code": "error.400.verification_invalid_factor",
+    "status": 400,
+    "params": [],
+    "remediation": "verify",
+    "en": "This verification factor is not available"
+  },
+  {
+    "code": "error.400.vocabularies_bad_parent",
+    "status": 400,
+    "params": [
+      "parent",
+      "level"
+    ],
+    "remediation": "fix_input",
+    "en": "No term '{parent}' at the parent level of '{level}'"
+  },
+  {
+    "code": "error.401.unauthorized",
+    "status": 401,
+    "params": [],
+    "remediation": "reauthenticate",
+    "en": "Authentication required"
+  },
+  {
+    "code": "error.402.payment_required",
+    "status": 402,
+    "params": [],
+    "remediation": "retry",
+    "en": "Payment required"
+  },
+  {
+    "code": "error.403.forbidden",
+    "status": 403,
+    "params": [],
+    "remediation": "retry",
+    "en": "You do not have permission to perform this action"
+  },
+  {
+    "code": "error.403.network_blocked",
+    "status": 403,
+    "params": [],
+    "remediation": "contact_support",
+    "en": "Requests from this network are not allowed"
+  },
+  {
+    "code": "error.403.verification_enrollment_required",
+    "status": 403,
+    "params": [],
+    "remediation": "verify",
+    "en": "Verification factor enrollment required"
+  },
+  {
+    "code": "error.403.verification_required",
+    "status": 403,
+    "params": [],
+    "remediation": "verify",
+    "en": "Additional verification required"
+  },
+  {
+    "code": "error.404.ad_not_found",
+    "status": 404,
+    "params": [],
+    "remediation": "retry",
+    "en": "Listing not found"
+  },
+  {
+    "code": "error.404.not_found",
+    "status": 404,
+    "params": [],
+    "remediation": "retry",
+    "en": "Requested resource not found"
+  },
+  {
+    "code": "error.404.verification_challenge_not_found",
+    "status": 404,
+    "params": [],
+    "remediation": "verify",
+    "en": "Verification challenge not found or expired"
+  },
+  {
+    "code": "error.404.vocabularies_level_not_found",
+    "status": 404,
+    "params": [
+      "vocabulary",
+      "level"
+    ],
+    "remediation": "retry",
+    "en": "Vocabulary '{vocabulary}' has no level '{level}'"
+  },
+  {
+    "code": "error.404.vocabularies_vocabulary_not_found",
+    "status": 404,
+    "params": [],
+    "remediation": "retry",
+    "en": "Vocabulary not found"
+  },
+  {
+    "code": "error.405.method_not_allowed",
+    "status": 405,
+    "params": [],
+    "remediation": "retry",
+    "en": "Method not allowed"
+  },
+  {
+    "code": "error.406.not_acceptable",
+    "status": 406,
+    "params": [],
+    "remediation": "retry",
+    "en": "Not acceptable"
+  },
+  {
+    "code": "error.408.request_timeout",
+    "status": 408,
+    "params": [],
+    "remediation": "retry",
+    "en": "Request timeout"
+  },
+  {
+    "code": "error.409.conflict",
+    "status": 409,
+    "params": [],
+    "remediation": "fix_input",
+    "en": "Resource already exists"
+  },
+  {
+    "code": "error.410.gone",
+    "status": 410,
+    "params": [],
+    "remediation": "retry",
+    "en": "Resource has been permanently removed"
+  },
+  {
+    "code": "error.413.payload_too_large",
+    "status": 413,
+    "params": [],
+    "remediation": "retry",
+    "en": "Request body is too large"
+  },
+  {
+    "code": "error.415.unsupported_media_type",
+    "status": 415,
+    "params": [],
+    "remediation": "retry",
+    "en": "Unsupported media type"
+  },
+  {
+    "code": "error.422.unprocessable_entity",
+    "status": 422,
+    "params": [],
+    "remediation": "wait_and_retry",
+    "en": "Unprocessable entity"
+  },
+  {
+    "code": "error.423.locked",
+    "status": 423,
+    "params": [],
+    "remediation": "wait_and_retry",
+    "en": "Resource is locked"
+  },
+  {
+    "code": "error.423.verification_locked",
+    "status": 423,
+    "params": [],
+    "remediation": "wait_and_retry",
+    "en": "Too many failed attempts — verification locked"
+  },
+  {
+    "code": "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."
+  },
+  {
+    "code": "error.429.too_many_requests",
+    "status": 429,
+    "params": [],
+    "remediation": "wait_and_retry",
+    "en": "Too many requests. Please try again later."
+  },
+  {
+    "code": "error.500.internal",
+    "status": 500,
+    "params": [],
+    "remediation": "contact_support",
+    "en": "Something went wrong"
+  },
+  {
+    "code": "error.503.mandate_unavailable",
+    "status": 503,
+    "params": [],
+    "remediation": "retry",
+    "en": "Cannot verify workspace mandate right now"
+  }
+]

package/src/i18n/generated/errors.ru.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.ru.json (locale catalog
+// beside the canonical errors.json — i18n-shipping.md §1).
+import type { VocabulariesErrorCode } from "./errors.gen.js";
+
+/**
+ * `ru` 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 `ru`
+ * 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/ru` subpath, NOT the main entry, so
+ * the locale stays out of hosts that don't ship it.
+ */
+export const vocabulariesErrorBundleRu: Partial<Record<VocabulariesErrorCode, string>> = {
+  "error.400.bad_request": "Некорректный запрос",
+  "error.400.captcha_invalid": "Проверка капчи не пройдена. Пожалуйста, попробуйте ещё раз.",
+  "error.400.captcha_required": "Требуется токен капчи.",
+  "error.400.expected_list": "Ожидался список элементов",
+  "error.400.field.blank": "Поле «{field}» не может быть пустым",
+  "error.400.field.does_not_exist": "«{field}» не существует",
+  "error.400.field.invalid": "Поле «{field}» содержит недопустимое значение",
+  "error.400.field.invalid_choice": "Недопустимый вариант для поля «{field}»",
+  "error.400.field.max_length": "Поле «{field}» должно содержать не более {max_length} символов",
+  "error.400.field.max_value": "Значение поля «{field}» должно быть не больше {max_value}",
+  "error.400.field.min_length": "Поле «{field}» должно содержать не менее {min_length} символов",
+  "error.400.field.min_value": "Значение поля «{field}» должно быть не меньше {min_value}",
+  "error.400.field.null": "Поле «{field}» не может быть null",
+  "error.400.field.required": "Поле «{field}» обязательно",
+  "error.400.field.unique": "Значение поля «{field}» должно быть уникальным",
+  "error.400.invalid_ad_id": "Недопустимый идентификатор объявления",
+  "error.400.validation_error": "Ошибка валидации",
+  "error.400.verification_failed": "Проверка не пройдена",
+  "error.400.verification_invalid_factor": "Этот способ подтверждения недоступен",
+  "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.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": "Слишком много попыток. Повторите попытку через {retry_after_minutes} мин.",
+  "error.429.too_many_requests": "Слишком много запросов. Пожалуйста, повторите попытку позже.",
+  "error.500.internal": "Что-то пошло не так",
+  "error.503.mandate_unavailable": "Не удалось проверить доступ к рабочему пространству",
+};

package/src/i18n/keys.ts

@@ -0,0 +1,53 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { vocabulariesErrorBundleEn } from "./generated/errors.gen.js";
+
+/**
+ * vocabularies-react's own translation KEYS (frontend-standard §4.2): headless
+ * components never render literal strings — hosts resolve these via core's i18n
+ * engine (`useT`). Backend error codes flow through the SAME contour: a
+ * `StapelApiError.code` is already a key, so the default bundle below ships
+ * English fallbacks for both the backend error codes (generated) and the
+ * pair's own UI keys. Point core's `loadLocale` at stapel-translate to override
+ * per locale. UI keys live under the `vocabularies.` namespace.
+ */
+export const VOCABULARIES_I18N_KEYS = {
+  unknownError: "vocabularies.error.unknown",
+  termSelectPlaceholder: "vocabularies.termSelect.placeholder",
+  termSelectNoMatches: "vocabularies.termSelect.noMatches",
+  termSelectUnavailableTitle: "vocabularies.termSelect.unavailable.title",
+  termSelectUnavailable: "vocabularies.termSelect.unavailable",
+} as const;
+
+export type VocabulariesI18nKey =
+  (typeof VOCABULARIES_I18N_KEYS)[keyof typeof VOCABULARIES_I18N_KEYS];
+
+/**
+ * English fallback bundle for vocabularies-react UI keys + backend error codes.
+ * The generated `vocabulariesErrorBundleEn` (from stapel-vocabularies's error registry,
+ * `pnpm gen:errors`) is spread FIRST so every backend `error.*` key has a
+ * fallback — a `StapelApiError.code` never renders as a raw key. Hand-polished
+ * copy below then OVERRIDES the generated English for the keys users see most.
+ */
+export const vocabulariesI18nBundleEn: I18nDictionary = {
+  // Backend error codes — generated en fallbacks (coverage by construction).
+  ...vocabulariesErrorBundleEn,
+
+  // vocabularies-react UI
+  "vocabularies.error.unknown": "Something went wrong. Please try again.",
+
+  // the default skin's own copy (see i18n/ru.ts, i18n/es.ts)
+  "vocabularies.termSelect.placeholder": "Start typing to search…",
+  "vocabularies.termSelect.noMatches": "No term matches that.",
+  "vocabularies.termSelect.unavailable.title": "This list cannot be loaded",
+  "vocabularies.termSelect.unavailable":
+    "The terms for this field come from a vocabulary service that is not configured here, so there is nothing to choose from. Nobody can answer this question until it is wired up — please report it.",
+};
+
+/**
+ * Register vocabularies-react's key bundle into a core i18n engine (call once at
+ * startup). A later `loadLocale` from stapel-translate can layer localized
+ * overrides on top.
+ */
+export function registerVocabulariesI18n(engine: I18nEngine, locale = "en"): void {
+  engine.registerBundle(locale, vocabulariesI18nBundleEn);
+}

package/src/i18n/ru.ts

@@ -0,0 +1,54 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { vocabulariesErrorBundleRu } from "./generated/errors.ru.gen.js";
+import { vocabulariesI18nBundleEn } from "./keys.js";
+
+export { vocabulariesErrorBundleRu } from "./generated/errors.ru.gen.js";
+
+/**
+ * Russian bundle for vocabularies-react — shipped as the
+ * `@stapel/vocabularies-react/i18n/ru` 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. The generated `vocabulariesErrorBundleRu` covers the
+ * 42 cross-cutting codes stapel-core owns and localizes. The 3 codes
+ * stapel-vocabularies owns are NOT in it and cannot be: the module ships no
+ * `translations/` directory at all, so the generator emits a `Partial` bundle
+ * and says so in its own header (`ERRORS_LOCALE_EXEMPT_OWNERS`, the
+ * stapel-geo / stapel-reviews precedent). They are authored below, beside the
+ * UI copy. When upstream ships `translations/errors.ru.json`, those three
+ * lines are deleted and the generated bundle covers them — the keys and the
+ * texts do not move.
+ */
+export const vocabulariesI18nBundleRu: I18nDictionary = {
+  // Backend error codes — generated ru texts for every key core owns.
+  ...vocabulariesErrorBundleRu,
+
+  // Backend error codes stapel-vocabularies owns — authored here (see above).
+  "error.400.vocabularies_bad_parent":
+    "На родительском уровне «{level}» нет термина «{parent}»",
+  "error.404.vocabularies_level_not_found":
+    "В справочнике «{vocabulary}» нет уровня «{level}»",
+  "error.404.vocabularies_vocabulary_not_found": "Справочник не найден",
+
+  // vocabularies-react UI
+  "vocabularies.error.unknown": "Что-то пошло не так. Попробуйте ещё раз.",
+  "vocabularies.termSelect.placeholder": "Начните вводить для поиска…",
+  "vocabularies.termSelect.noMatches": "Ничего не найдено.",
+  "vocabularies.termSelect.unavailable.title": "Список не удалось загрузить",
+  "vocabularies.termSelect.unavailable":
+    "Значения для этого поля берутся из справочника, который здесь не подключён, и выбирать не из чего. Ответить на этот вопрос невозможно — сообщите, пожалуйста, об этом.",
+};
+
+/**
+ * Register the Russian 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 registerVocabulariesI18nRu(
+  engine: I18nEngine,
+  locale = "ru"
+): void {
+  engine.registerBundle(locale, vocabulariesI18nBundleEn);
+  engine.registerBundle(locale, vocabulariesI18nBundleRu);
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+/**
+ * `@stapel/vocabularies-react` — the headless React flow pair for stapel-vocabularies
+ * (frontend-standard §2). Business + state only, zero visual opinion. Built on
+ * `@stapel/core`'s StapelClient (verification-403 interception, token refresh,
+ * i18n, analytics, query layer).
+ *
+ * Scaffolded by `stapel-new-react-lib`. Layers: api → model → flows → headless
+ * → i18n. Generated surfaces (flows registry, error map, manifest, llms.txt)
+ * are produced by the monorepo `gen:*` drivers and stand under drift gates.
+ */
+
+// ── api ──────────────────────────────────────────────────────────────────────
+export { createVocabulariesApi } from "./api/vocabulariesApi.js";
+export type { VocabulariesApi } from "./api/vocabulariesApi.js";
+export type { Schemas, Vocabulary, Level, Term, TermPage } from "./api/types.js";
+
+// ── the seam (attributes-v2 §3.4) ────────────────────────────────────────────
+// `createVocabularyClient` returns the two functions
+// `@stapel/attributes-react` declares as `VocabularyClient` and hands to
+// `<VocabularyClientProvider>`. The shape is satisfied STRUCTURALLY: neither
+// package imports the other (test/clientShape.test.ts is the proof), so the
+// two L2 pairs stay independently releasable.
+export {
+  createVocabularyClient,
+  DEFAULT_TERM_LIMIT,
+  RESOLVE_BATCH,
+} from "./client.js";
+export type {
+  VocabularyClient,
+  VocabularyTerm,
+  CreateVocabularyClientOptions,
+} from "./client.js";
+
+// ── flows ────────────────────────────────────────────────────────────────────
+// The flow-machine primitive lives in `@stapel/core` (one reviewed copy for
+// every pair — frontend-core-architecture §4b). Re-exported for ergonomics.
+export { createFlowMachine, useFlow, isErrorCode } from "@stapel/core";
+export type {
+  FlowMachine,
+  FlowMachineOptions,
+  FlowStateBase,
+  FlowError,
+} from "@stapel/core";
+export { toFlowError } from "./flows/errors.js";
+export { VOCABULARIES_FLOWS, flowEndpoints } from "./flows/registry.js";
+export type {
+  VocabulariesFlowId,
+  VocabulariesFlowSpec,
+  FlowEndpoint,
+} from "./flows/registry.js";
+
+// ── model (runtime wiring, query keys, context) ──────────────────────────────
+export { createVocabulariesRuntime } from "./model/runtime.js";
+export type {
+  VocabulariesRuntime,
+  CreateVocabulariesRuntimeOptions,
+} from "./model/runtime.js";
+export {
+  VocabulariesRuntimeContext,
+  useVocabulariesRuntime,
+  useVocabulariesApi,
+  useVocabulariesAnalytics,
+} from "./model/context.js";
+export { vocabulariesQueryKeys } from "./model/queryKeys.js";
+export { useTermSearch, TERM_SEARCH_DEBOUNCE_MS } from "./model/useTermSearch.js";
+export type { TermSearchOptions, TermSearchState } from "./model/useTermSearch.js";
+export { useTermLabels, termLabel } from "./model/useTermLabels.js";
+export type { TermLabels, TermLabelsOptions } from "./model/useTermLabels.js";
+
+// ── headless (renderless components) ─────────────────────────────────────────
+export { VocabulariesProvider } from "./headless/VocabulariesProvider.js";
+
+// ── i18n ─────────────────────────────────────────────────────────────────────
+export {
+  VOCABULARIES_I18N_KEYS,
+  vocabulariesI18nBundleEn,
+  registerVocabulariesI18n,
+} from "./i18n/keys.js";
+export type { VocabulariesI18nKey } from "./i18n/keys.js";
+
+// ── errors map (code → status/params/remediation/en; generated) ──────────────
+export {
+  VOCABULARIES_ERRORS,
+  VOCABULARIES_ERROR_CODES,
+  vocabulariesErrorBundleEn,
+  explainVocabulariesError,
+} from "./i18n/errorsMap.js";
+export type {
+  VocabulariesErrorCode,
+  VocabulariesErrorSpec,
+  Remediation,
+} from "./i18n/errorsMap.js";

package/src/model/context.tsx

@@ -0,0 +1,28 @@
+import type { Context } from "react";
+import { createModuleContext } from "@stapel/core";
+import type { Analytics, ModuleContextKit } from "@stapel/core";
+import type { VocabulariesApi } from "../api/vocabulariesApi.js";
+import type { VocabulariesRuntime } from "./runtime.js";
+
+/**
+ * The wired VocabulariesRuntime shared through React context by
+ * `<VocabulariesProvider>`. Hooks in `model/` and `headless/` read the singletons
+ * from here. One reviewed copy of this plumbing lives in `@stapel/core`
+ * (`createModuleContext`, slim wave §21/S2); this module binds it under the
+ * pair's public names.
+ */
+const kit: ModuleContextKit<VocabulariesRuntime> =
+  createModuleContext<VocabulariesRuntime>("Vocabularies");
+
+export const VocabulariesRuntimeContext: Context<VocabulariesRuntime | null> =
+  kit.RuntimeContext;
+
+export const useVocabulariesRuntime: () => VocabulariesRuntime = kit.useRuntime;
+
+export const useVocabulariesApi: () => VocabulariesApi = kit.useApi;
+
+export const useVocabulariesAnalytics: () => Analytics | null = kit.useAnalytics;
+
+/** @internal Re-exported as `<VocabulariesProvider>` from `headless/`. */
+export const ModuleProvider: ModuleContextKit<VocabulariesRuntime>["Provider"] =
+  kit.Provider;

package/src/model/queryKeys.ts

@@ -0,0 +1,35 @@
+/**
+ * Namespaced TanStack Query keys (frontend-standard §2 — "keys are namespaced").
+ * Everything under the `"vocabularies"` root so a host can invalidate the whole
+ * module or match a single resource. Explicit tuple return types satisfy
+ * `--isolatedDeclarations`.
+ *
+ * Only ONE read is keyed here, and that is not an oversight: a term SEARCH is
+ * not a cacheable resource — it is superseded per keystroke and its answer is
+ * scoped to a dropdown that is about to close — so `useTermSearch` owns its own
+ * in-flight state and never enters the cache. `useTermLabels` is the opposite:
+ * a stable `{code: label}` for codes a page already holds, worth caching across
+ * every control that shows the same term, which is why it is a query.
+ */
+const ROOT = "vocabularies" as const;
+
+export const vocabulariesQueryKeys: {
+  readonly all: readonly ["vocabularies"];
+  termLabels: (
+    vocabulary: string,
+    level: string,
+    codes: readonly string[]
+  ) => readonly ["vocabularies", "termLabels", string, string, string];
+} = {
+  all: [ROOT],
+  // The codes are sorted and joined into ONE key segment: two controls asking
+  // for the same set in a different order are the same read, and an array
+  // segment would make them two cache entries and two round trips.
+  termLabels: (vocabulary, level, codes) => [
+    ROOT,
+    "termLabels",
+    vocabulary,
+    level,
+    [...codes].sort().join(","),
+  ],
+};