@stapel/categories-react 0.1.0

package/src/headless/CategoryPicker.tsx

@@ -0,0 +1,173 @@
+import { useMemo, useState } from "react";
+import type { ReactNode } from "react";
+import { loadStateFromQuery, mapLoad } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import {
+  categoryBreadcrumbs,
+  flattenCategoryNodes,
+} from "../catalog/tree.js";
+import type { CategoryNode } from "../catalog/tree.js";
+import { categoryLabel, renderCategoryLabel } from "../catalog/labels.js";
+import type { CategoryLabel } from "../catalog/labels.js";
+import { useCategoryCatalog } from "../model/queries.js";
+import type { UseCategoryCatalogOptions } from "../model/queries.js";
+
+/** One selectable option in the picker. */
+export interface CategoryOption {
+  readonly node: CategoryNode;
+  readonly label: CategoryLabel;
+  /** Root → this node, for a skin that shows the full path in the option. */
+  readonly path: readonly CategoryLabel[];
+  /** `true` when this node has no children — usually the only kind a listing
+   * may be filed under. See `leavesOnly`. */
+  readonly isLeaf: boolean;
+}
+
+export interface CategoryPickerBag {
+  /**
+   * The options at the current drill level, or the search matches while a
+   * query is typed. `empty` is a real answer here — a leaf category has no
+   * children, and a search can match nothing.
+   */
+  readonly state: LoadState<readonly CategoryOption[]>;
+  /** Where the drill-down currently is: root → open node. */
+  readonly path: readonly CategoryNode[];
+  /** The selected node, or `null`. */
+  readonly selected: CategoryNode | null;
+  /** Blocked when nothing is selected, or when the selection is not a leaf
+   * and `leavesOnly` is on. Carries the REASON — a disabled control that does
+   * not say why is the thing `ActionAvailability` exists to prevent. */
+  readonly submitBlockedReason: CategoryPickerBlockedReason | null;
+  readonly query: string;
+  setQuery(value: string): void;
+  /** Descend into a node. A leaf selects instead of descending. */
+  open(node: CategoryNode): void;
+  /** Back up one level. */
+  up(): void;
+  select(node: CategoryNode | null): void;
+  refetch(): void;
+}
+
+/** Why the picker will not hand a value back yet. */
+export type CategoryPickerBlockedReason = "nothing_selected" | "not_a_leaf";
+
+export interface CategoryPickerProps extends UseCategoryCatalogOptions {
+  /** Controlled selection. */
+  value?: number | null;
+  onChange?: (id: number | null, node: CategoryNode | null) => void;
+  /**
+   * Only leaf categories are a valid answer. Default `true`: a listing filed
+   * under "Electronics" instead of "Electronics › Phones › Used" inherits the
+   * wrong feature set, and the compose form then asks the wrong questions.
+   */
+  leavesOnly?: boolean;
+  /** Resolve a translation key to a caption, so SEARCH matches what the
+   * person can read. Without it, search matches the key. */
+  translate?: (key: string) => string;
+  children: (bag: CategoryPickerBag) => ReactNode;
+}
+
+/**
+ * The category chooser of the compose form, headless.
+ *
+ * Two modes over the SAME synced tree: drill-down (roots → children → …) and
+ * a flat search. The search matches the RENDERED caption when a `translate` is
+ * supplied and the raw key otherwise, which is the only honest behaviour for a
+ * catalogue whose names are translation keys (`catalog/labels.ts`): a person
+ * typing "phones" is typing what they see, not `category.phones`.
+ *
+ * Nothing here requests anything — the catalogue is already in memory.
+ */
+export function CategoryPicker(props: CategoryPickerProps): ReactNode {
+  const {
+    value,
+    onChange,
+    leavesOnly,
+    translate,
+    children,
+    ...catalogOptions
+  } = props;
+  const requireLeaf = leavesOnly ?? true;
+
+  const query = useCategoryCatalog(catalogOptions);
+  const catalog = loadStateFromQuery(query);
+  const index = catalog.status === "ready" ? catalog.data.index : null;
+
+  const [openId, setOpenId] = useState<number | null>(null);
+  const [text, setText] = useState("");
+
+  const selected =
+    index !== null && value !== null && value !== undefined
+      ? (index.byId.get(value) ?? null)
+      : null;
+
+  const toOption = useMemo(
+    () =>
+      (node: CategoryNode): CategoryOption => ({
+        node,
+        label: categoryLabel(node.category),
+        path: (index === null ? [] : categoryBreadcrumbs(index, node.id)).map(
+          (crumb) => categoryLabel(crumb.category)
+        ),
+        isLeaf: node.children.length === 0,
+      }),
+    [index]
+  );
+
+  const options = useMemo<readonly CategoryOption[]>(() => {
+    if (index === null) return [];
+    const needle = text.trim().toLocaleLowerCase();
+    if (needle !== "") {
+      const caption = (node: CategoryNode): string => {
+        const label = categoryLabel(node.category);
+        return translate === undefined
+          ? label.value
+          : renderCategoryLabel(label, translate);
+      };
+      return flattenCategoryNodes(index.roots)
+        .filter(
+          (node) =>
+            caption(node).toLocaleLowerCase().includes(needle) ||
+            node.category.slug.toLocaleLowerCase().includes(needle)
+        )
+        .filter((node) => !requireLeaf || node.children.length === 0)
+        .map(toOption);
+    }
+    const level =
+      openId === null ? index.roots : (index.byId.get(openId)?.children ?? []);
+    return level.map(toOption);
+  }, [index, text, openId, requireLeaf, translate, toOption]);
+
+  const blocked: CategoryPickerBlockedReason | null =
+    selected === null
+      ? "nothing_selected"
+      : requireLeaf && selected.children.length > 0
+        ? "not_a_leaf"
+        : null;
+
+  return children({
+    state: mapLoad(catalog, () => options),
+    path: index === null ? [] : categoryBreadcrumbs(index, openId),
+    selected,
+    submitBlockedReason: blocked,
+    query: text,
+    setQuery: setText,
+    open: (node) => {
+      if (node.children.length === 0) {
+        onChange?.(node.id, node);
+        return;
+      }
+      setOpenId(node.id);
+    },
+    up: () => {
+      if (index === null || openId === null) return;
+      setOpenId(index.byId.get(openId)?.category.tn_parent ?? null);
+    },
+    select: (node) => {
+      onChange?.(node?.id ?? null, node);
+    },
+    refetch: () => {
+      void query.refetch();
+    },
+  });
+}

package/src/headless/CategoryTree.tsx

@@ -0,0 +1,115 @@
+import type { ReactNode } from "react";
+import { loadStateFromQuery, mapLoad } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import { categoryBreadcrumbs, resolveCategorySlug } from "../catalog/tree.js";
+import type { CategoryIndex, CategoryNode } from "../catalog/tree.js";
+import { useCategoryCatalog } from "../model/queries.js";
+import type {
+  CategoryCatalog,
+  UseCategoryCatalogOptions,
+} from "../model/queries.js";
+
+/** The bag `<CategoryTree>` hands its render prop. */
+export interface CategoryTreeBag {
+  /**
+   * The nodes to render at this level. `empty` means the catalogue really has
+   * no categories here — reachable only from a sync that succeeded, which is
+   * the whole reason it is a separate arm from `failed`.
+   */
+  readonly state: LoadState<readonly CategoryNode[]>;
+  /** The full built catalogue, for a skin that wants more than one level. */
+  readonly catalog: LoadState<CategoryCatalog>;
+  /** The node `slug`/`categoryId` selected, once the catalogue has loaded. */
+  readonly current: CategoryNode | null;
+  /** Root → current, inclusive. `[]` when nothing is selected. */
+  readonly breadcrumbs: readonly CategoryNode[];
+  /**
+   * A slug that is not in the loaded catalogue. `true` only once the
+   * catalogue is `ready` — before that the honest answer is "we do not know
+   * yet", and a skin that renders "category not found" during a sync is
+   * showing a 404 for a page that exists.
+   */
+  readonly unknownSlug: boolean;
+  /**
+   * The page budget stopped the sync walk: this tree is INCOMPLETE. Distinct
+   * from `empty` in the same way `failed` is — a branch missing here was not
+   * read, not absent.
+   */
+  readonly truncated: boolean;
+  readonly isFetching: boolean;
+  refetch(): void;
+}
+
+export interface CategoryTreeProps extends UseCategoryCatalogOptions {
+  /** Render the children of this category instead of the roots. */
+  parentId?: number | null;
+  /** Select a category by slug — the `/c/:slug` route's job. Resolved against
+   * the synced tree because the server has no slug lookup. */
+  slug?: string;
+  /** Select a category by id. Ignored when `slug` is given. */
+  categoryId?: number | null;
+  children: (bag: CategoryTreeBag) => ReactNode;
+}
+
+function levelOf(
+  index: CategoryIndex,
+  parentId: number | null | undefined,
+  current: CategoryNode | null
+): readonly CategoryNode[] {
+  if (parentId !== null && parentId !== undefined) {
+    return index.byId.get(parentId)?.children ?? [];
+  }
+  // With a category selected and no explicit parent, "the level" is that
+  // category's own sub-categories — which is what a category page shows. A
+  // LEAF category has none, and that empty is a true empty: the skin below it
+  // renders listings, not a menu.
+  if (current !== null) return current.children;
+  return index.roots;
+}
+
+/**
+ * Headless category navigation over the delta-synced catalogue.
+ *
+ * One hook mounted anywhere in the tree serves every level: the roots on the
+ * catalogue page, one category's children on `/c/:slug`, the breadcrumb above
+ * either. Nothing here issues a request per level — the tree is already in
+ * memory (see `useCategoryCatalog`), which is precisely the property the spec
+ * asked for in §4.3.
+ */
+export function CategoryTree(props: CategoryTreeProps): ReactNode {
+  const {
+    parentId,
+    slug,
+    categoryId,
+    children,
+    ...catalogOptions
+  } = props;
+  const query = useCategoryCatalog(catalogOptions);
+  const catalog = loadStateFromQuery(query);
+  const index = catalog.status === "ready" ? catalog.data.index : null;
+
+  let current: CategoryNode | null = null;
+  if (index !== null) {
+    if (slug !== undefined) current = resolveCategorySlug(index, slug) ?? null;
+    else if (categoryId !== null && categoryId !== undefined) {
+      current = index.byId.get(categoryId) ?? null;
+    }
+  }
+
+  return children({
+    state: mapLoad(catalog, (data) =>
+      levelOf(data.index, parentId, current)
+    ),
+    catalog,
+    current,
+    breadcrumbs:
+      index === null ? [] : categoryBreadcrumbs(index, current?.id),
+    unknownSlug:
+      catalog.status === "ready" && slug !== undefined && current === null,
+    truncated: catalog.status === "ready" && catalog.data.truncated,
+    isFetching: query.isFetching,
+    refetch: () => {
+      void query.refetch();
+    },
+  });
+}

package/src/i18n/errorsMap.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 { CATEGORIES_ERRORS } from "./generated/errors.gen.js";
+import type { Remediation } from "./generated/errors.gen.js";
+
+export {
+  CATEGORIES_ERRORS,
+  CATEGORIES_ERROR_CODES,
+  categoriesErrorBundleEn,
+} from "./generated/errors.gen.js";
+export type {
+  CategoriesErrorCode,
+  CategoriesErrorSpec,
+  Remediation,
+} from "./generated/errors.gen.js";
+
+/**
+ * The optimistic-concurrency refusal of the feature editor, named because it
+ * is the one 409 in the registry and it means something specific: somebody
+ * else changed this category's schema while you were editing it, and
+ * `params.expected` / `params.actual` say which revisions.
+ *
+ * Not raised by anything on this pair's surface (the feature editor is a staff
+ * screen — see `api/categoriesApi.ts`), and exported anyway because the
+ * catalogue admin a host builds on top of this client WILL meet it, and a
+ * constant beats a string retyped at each call site.
+ */
+export const CATEGORIES_FEATURE_EDITOR_CONFLICT =
+  "error.409.categories_feature_editor_conflict";
+
+/**
+ * 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 explainCategoriesError(code: string): Remediation | undefined {
+  return (CATEGORIES_ERRORS as Record<string, { remediation: Remediation }>)[
+    code
+  ]?.remediation;
+}

package/src/i18n/es.ts

@@ -0,0 +1,92 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { categoriesErrorBundleEs } from "./generated/errors.es.gen.js";
+
+export { categoriesErrorBundleEs } from "./generated/errors.es.gen.js";
+
+/**
+ * Spanish bundle for categories-react — the
+ * `@stapel/categories-react/i18n/es` subpath (i18n-shipping.md §2), opt-in
+ * exactly like `ru`.
+ *
+ * Same composition and the same three-way split by owner as `./ru`: the 42
+ * cross-cutting `stapel_core` codes are generated from core's catalogue, the 8
+ * `stapel_categories` codes are pair-authored here until upstream ships a
+ * `translations/` directory, and the 12 `stapel_attributes` codes stay with
+ * `@stapel/attributes-react`, which owns them.
+ *
+ * `es` carries the full UI copy, not just the refusals: the catalogue is the
+ * first thing a visitor sees, and a half-translated menu above a translated
+ * search is worse than either.
+ *
+ * PROVENANCE: unreviewed, seed-grade, like every other authored catalogue in
+ * this wave.
+ */
+export const categoriesI18nBundleEs: I18nDictionary = {
+  ...categoriesErrorBundleEs,
+
+  // ── the 8 stapel_categories-owned codes, pair-authored ───────────────────
+  "error.400.categories_config_required": "Se requiere un objeto config.",
+  "error.400.categories_database_error":
+    "Error de base de datos al aplicar los cambios.",
+  "error.400.categories_duplicate_slug":
+    "Ya existe una característica con el slug «{slug}».",
+  "error.400.categories_expected_list": "Se esperaba una lista de objetos.",
+  "error.400.categories_feature_editor_invalid":
+    "Solicitud del editor de características no válida: {reason}",
+  "error.400.categories_invalid_conversion":
+    "Conversión de tipo no válida (solo se admite select ↔ string).",
+  "error.400.categories_not_deleted": "La categoría no está eliminada.",
+  "error.409.categories_feature_editor_conflict":
+    "Otro editor modificó la categoría (se esperaba la revisión {expected}, ahora {actual}); recarga y vuelve a intentarlo.",
+
+  "categories.error.unknown": "Algo salió mal con el catálogo.",
+
+  "categories.catalog.title": "Catálogo",
+  "categories.catalog.loading": "Cargando el catálogo…",
+  "categories.catalog.load_failed": "No pudimos cargar el catálogo.",
+  "categories.catalog.empty": "Este catálogo todavía no tiene categorías.",
+  "categories.catalog.retry": "Reintentar",
+  "categories.catalog.truncated":
+    "Solo se cargó parte del catálogo. Una categoría que falte aquí aún no se ha leído: no se ha eliminado.",
+  "categories.catalog.refreshing": "Comprobando cambios en el catálogo…",
+  "categories.catalog.as_of": "Catálogo a la revisión {revision}",
+
+  "categories.category.title": "Categoría",
+  "categories.category.unknown_slug": "No hay ninguna categoría en esta dirección.",
+  "categories.category.subcategories": "Subcategorías",
+  "categories.category.no_subcategories": "Esta categoría no tiene subcategorías.",
+  "categories.category.open": "Abrir",
+
+  "categories.breadcrumbs.root": "Todas las categorías",
+  "categories.breadcrumbs.label": "Estás aquí",
+
+  "categories.carousel.title": "Explorar por categoría",
+  "categories.carousel.loading": "Cargando categorías…",
+  "categories.carousel.load_failed": "No pudimos cargar las categorías.",
+  "categories.carousel.empty": "Ahora mismo no hay categorías destacadas.",
+
+  "categories.picker.title": "Categoría",
+  "categories.picker.search": "Buscar categorías",
+  "categories.picker.loading": "Cargando categorías…",
+  "categories.picker.load_failed": "No pudimos cargar las categorías.",
+  "categories.picker.no_matches": "Ninguna categoría coincide.",
+  "categories.picker.up": "Subir un nivel",
+  "categories.picker.selected": "Seleccionada: {category}",
+  "categories.picker.blocked.nothing_selected": "Elige primero una categoría.",
+  "categories.picker.blocked.not_a_leaf":
+    "Elige una categoría más concreta: esta tiene subcategorías, y de ellas dependen los datos que se piden.",
+
+  "categories.features.title": "Datos de esta categoría",
+  "categories.features.loading": "Cargando los datos…",
+  "categories.features.load_failed": "No pudimos cargar los datos.",
+  "categories.features.empty": "Esta categoría no pide datos adicionales.",
+  "categories.features.mandatory": "Obligatorio",
+  "categories.features.type": "{type}",
+  "categories.features.untyped": "Este dato no tiene tipo y no se puede mostrar.",
+};
+
+/** Register the `es` bundle. Call AFTER `registerCategoriesI18n` so it
+ * overrides the English floor. */
+export function registerCategoriesI18nEs(engine: I18nEngine, locale = "es"): void {
+  engine.registerBundle(locale, categoriesI18nBundleEs);
+}

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 { CategoriesErrorCode } from "./errors.gen.js";
+
+/**
+ * `es` texts for the backend error codes this catalog carries.
+ *
+ * PARTIAL, and deliberately typed to say so: 20 key(s) owned by
+ * stapel_attributes, stapel_categories 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 categoriesErrorBundleEs: Partial<Record<CategoriesErrorCode, 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",
+};