@stapel/attributes-react 0.1.0

package/src/errors.ts

@@ -0,0 +1,127 @@
+/**
+ * The error vocabulary, mirrored — and the one step that turns a server
+ * verdict into refusals sitting on the controls that caused them.
+ *
+ * Both halves come straight from `stapel_attributes.errors`: the machine code
+ * (`ValidationErrorCode`) and the localizable key it maps to
+ * (`ERROR_CODE_TO_KEY`). Nothing here invents copy: a "too long" caught by
+ * the client mirror and a "too long" caught by the server render the SAME
+ * sentence from the SAME key, because they ARE the same key. The alternative
+ * — pair-invented wording for the local half — gives a person two sentences
+ * for one problem and makes the local one a lie the moment the backend's rule
+ * moves.
+ *
+ * The keys themselves are owned by stapel-attributes and registered with
+ * stapel-core (`register_service_errors(ATTRIBUTES_ERRORS)`), so a host that
+ * already has a pair's generated error bundle has their copy; the fallback
+ * English lives in this package's own i18n bundle for a host that does not.
+ */
+import type { FlowError } from "@stapel/core";
+import type {
+  FeatureValidationResult,
+  ValidationBatchResult,
+  ValidationErrorCode,
+} from "./types.js";
+
+/**
+ * Every `ValidationErrorCode` the engine defines, sorted.
+ *
+ * Pinned byte-for-byte against `stapel-attributes/tests/golden/
+ * error_codes.json` — the corpus the engine generates from its own enum and
+ * asserts from both Python and TypeScript. A code added upstream and not here
+ * turns `test/contract.test.ts` red.
+ */
+export const VALIDATION_ERROR_CODES: readonly ValidationErrorCode[] = [
+  "above_maximum",
+  "below_minimum",
+  "description_too_long",
+  "description_too_short",
+  "duplicate_slug",
+  "empty_options",
+  "invalid_config",
+  "invalid_format",
+  "invalid_type",
+  "mandatory_missing",
+  "min_greater_than_max",
+  "not_allowed",
+  "not_in_options",
+  "unknown_feature",
+  "unknown_feature_type",
+];
+
+/**
+ * `ValidationErrorCode` → localizable key, mirroring
+ * `stapel_attributes.errors.ERROR_CODE_TO_KEY` exactly — including the three
+ * codes that deliberately collapse onto one key (`duplicate_slug` reports as
+ * an unknown type; `min_greater_than_max` and `empty_options` are both
+ * invalid config). Collapsing them differently here would make the client
+ * claim a distinction the server does not draw.
+ */
+export const ERROR_CODE_TO_KEY: Readonly<Record<ValidationErrorCode, string>> = {
+  below_minimum: "error.400.feature_below_minimum",
+  above_maximum: "error.400.feature_above_maximum",
+  not_in_options: "error.400.feature_not_in_options",
+  invalid_type: "error.400.feature_invalid_type",
+  invalid_format: "error.400.feature_invalid_format",
+  mandatory_missing: "error.400.feature_mandatory_missing",
+  duplicate_slug: "error.400.feature_unknown_type",
+  unknown_feature_type: "error.400.feature_unknown_type",
+  not_allowed: "error.400.feature_not_allowed",
+  unknown_feature: "error.400.feature_unknown",
+  invalid_config: "error.400.feature_invalid_config",
+  min_greater_than_max: "error.400.feature_invalid_config",
+  empty_options: "error.400.feature_invalid_config",
+  description_too_short: "error.400.description_too_short",
+  description_too_long: "error.400.description_too_long",
+};
+
+/** The key a result should render from: what the server said, else the one
+ * its code maps to. The server sends `localizable_error` already — this only
+ * covers the mirror's rows and a server that ever omits it. */
+export function resultErrorKey(
+  result: FeatureValidationResult
+): string | undefined {
+  if (typeof result.localizable_error === "string" && result.localizable_error.length > 0) {
+    return result.localizable_error;
+  }
+  return result.error ? ERROR_CODE_TO_KEY[result.error] : undefined;
+}
+
+/**
+ * A batch verdict, split into per-control refusals keyed by feature slug.
+ *
+ * `params.field` is added on the way out. The engine's own params are
+ * `{feature, slug}` (`validation.py`) and the fleet's `useFieldError`
+ * convention routes on `field` — so without this a perfectly well-formed
+ * server refusal lands in a page-level banner instead of under the control
+ * whose value caused it, which is the difference between "something is wrong"
+ * and "this box is wrong".
+ *
+ * `ref_value` rides along in params too: `error.400.feature_below_minimum`
+ * interpolates the limit, and the limit is what `ref_value` carries.
+ */
+export function featureErrorsBySlug(
+  batch: ValidationBatchResult
+): Readonly<Record<string, FlowError>> {
+  const out: Record<string, FlowError> = {};
+  for (const result of batch.results) {
+    if (result.status !== "validation_failed") continue;
+    const code = resultErrorKey(result);
+    if (code === undefined) continue;
+    out[result.slug] = {
+      code,
+      params: {
+        ...(result.params ?? {}),
+        field: result.slug,
+        slug: result.slug,
+        ...(result.ref_value === undefined || result.ref_value === null
+          ? {}
+          : { ref_value: result.ref_value }),
+      },
+      status: 400,
+      message: result.message ?? undefined,
+      language: undefined,
+    };
+  }
+  return out;
+}

package/src/format.ts

@@ -0,0 +1,210 @@
+/**
+ * DISPLAY — the read-only half of every value type.
+ *
+ * A storefront renders an attribute far more often than it edits one: a card
+ * shows badges, a detail page shows the whole spec table, a title carries the
+ * `show_at_title` values. Formatting therefore lives HERE, in the main entry,
+ * React-free and antd-free, so a card can format a value without pulling a
+ * skin into its bundle. `<FeatureBadges>`/`<FeatureValueList>` in `/default`
+ * are renderers over this function, not a second implementation of it.
+ *
+ * It mirrors each type's `format_value(config, dao)` (`stapel_attributes
+ * .types.*.type`), with the one honest difference the browser forces:
+ * `date` formats with the VIEWER's locale and time zone, where the engine
+ * formats with the server's — the same instant, written the way the person
+ * reading it writes dates.
+ *
+ * Unsupported types do not vanish. `formatFeatureValue` returns `undefined`
+ * for a type it cannot read, and the caller says so; a silent empty cell
+ * where a spec line belongs is the display twin of a dropped mandatory field.
+ */
+import type { FeatureDef, FeatureValueDto } from "./types.js";
+import { featureConfig, featureType } from "./types.js";
+import { isBlank } from "./validate.js";
+
+/** The types this module can render, sorted — the display half of the
+ * builtin set, and asserted equal to the editor half in `contract.test.ts`
+ * (a type you can fill in but cannot read back is a half-shipped type). */
+export const FORMATTABLE_TYPES: readonly string[] = [
+  "bool",
+  "convertible_unit",
+  "date",
+  "float",
+  "header",
+  "hex_color",
+  "hierarchical_select",
+  "int",
+  "select",
+  "string",
+];
+
+/** Copy the formatter needs from the host's translator — one function, so a
+ * caller outside React (a meta-tag builder, a title composer) can pass a
+ * plain lookup instead of standing up a provider. */
+export interface FormatOptions {
+  /** Resolve an option label / boolean caption. Option labels are translation
+   * keys when the config says `translatable_options` (the default). */
+  readonly t?: (key: string) => string;
+  /** BCP-47 tag for `date`. Defaults to the runtime's own locale. */
+  readonly locale?: string;
+}
+
+function str(value: unknown): string {
+  return typeof value === "string" ? value : value === null || value === undefined ? "" : String(value);
+}
+
+function translate(options: FormatOptions | undefined, key: string): string {
+  const t = options?.t;
+  if (t === undefined) return key;
+  const resolved = t(key);
+  // A translator that does not know a key conventionally returns the key —
+  // which is still the most informative thing available, so it stands.
+  return resolved.length > 0 ? resolved : key;
+}
+
+/** `{value → label}` for an options-bearing config, in either option shape. */
+function labelOf(
+  config: Readonly<Record<string, unknown>>,
+  value: unknown,
+  options: FormatOptions | undefined
+): string {
+  const raw = config["options"];
+  if (Array.isArray(raw)) {
+    for (const option of raw) {
+      if (option !== null && typeof option === "object") {
+        const entry = option as { value?: unknown; label?: unknown };
+        if (entry.value === value && typeof entry.label === "string" && entry.label.length > 0) {
+          return config["translatable_options"] === false
+            ? entry.label
+            : translate(options, entry.label);
+        }
+      }
+    }
+  }
+  return str(value);
+}
+
+function formatNumber(
+  config: Readonly<Record<string, unknown>>,
+  value: unknown,
+  defaultPrecision: number
+): string | undefined {
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(parsed)) return undefined;
+  const precision = config["precision"];
+  const digits = typeof precision === "number" && precision >= 0 ? precision : defaultPrecision;
+  const body = digits > 0 ? parsed.toFixed(digits) : String(Math.trunc(parsed));
+  const prefix = str(config["prefix"]);
+  const postfix = str(config["postfix"]);
+  return `${prefix}${body}${postfix ? ` ${postfix}` : ""}`;
+}
+
+/** `precision` → the `Intl` fields the engine's own `strftime` would show. */
+function formatTimestamp(
+  seconds: number,
+  precision: string,
+  locale: string | undefined
+): string {
+  const date = new Date(seconds * 1000);
+  switch (precision) {
+    case "year":
+      return new Intl.DateTimeFormat(locale, { year: "numeric" }).format(date);
+    case "month":
+      return new Intl.DateTimeFormat(locale, { year: "numeric", month: "long" }).format(date);
+    case "datetime":
+      return new Intl.DateTimeFormat(locale, {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+      }).format(date);
+    default:
+      return new Intl.DateTimeFormat(locale, {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+      }).format(date);
+  }
+}
+
+/**
+ * A submitted value, as a person reads it — or `undefined` when there is
+ * nothing to show (blank) or nothing this build can read (an unknown type).
+ * The two cases are distinguished by {@link isBlank}, so a caller can say
+ * "not specified" for one and name the type for the other.
+ */
+export function formatFeatureValue(
+  feature: FeatureDef,
+  dto: FeatureValueDto | undefined,
+  options?: FormatOptions
+): string | undefined {
+  const type = featureType(feature);
+  if (type === "header" || dto === undefined || isBlank(dto.value)) return undefined;
+  const config = featureConfig(feature);
+  const value = dto.value;
+
+  switch (type) {
+    case "string":
+      return `${str(config["prefix"])}${str(value)}${
+        str(config["postfix"]) ? ` ${str(config["postfix"])}` : ""
+      }`;
+    case "int":
+      return formatNumber(config, value, 0);
+    case "float":
+      return formatNumber(config, value, 2);
+    case "bool": {
+      const on = value === true || value === 1 || value === "true";
+      const label = str(config[on ? "trueLabel" : "falseLabel"]);
+      if (label.length > 0) return translate(options, label);
+      return on ? "✓" : "—";
+    }
+    case "select": {
+      const items = Array.isArray(value) ? value : [value];
+      return items.map((item) => labelOf(config, item, options)).join(", ");
+    }
+    case "hierarchical_select": {
+      const path = Array.isArray(value) ? value : [value];
+      return path.map((step) => str(step)).join(" / ");
+    }
+    case "date": {
+      const seconds =
+        typeof value === "number"
+          ? Math.trunc(value)
+          : typeof value === "string" && /^-?\d+$/.test(value.trim())
+            ? Number.parseInt(value.trim(), 10)
+            : undefined;
+      if (seconds === undefined) return undefined;
+      return formatTimestamp(seconds, str(config["precision"]) || "date", options?.locale);
+    }
+    case "hex_color": {
+      if (value === null || typeof value !== "object") return undefined;
+      const entry = value as { hex?: unknown; simple?: unknown; label?: unknown };
+      if (typeof entry.label === "string" && entry.label.length > 0) {
+        return translate(options, entry.label);
+      }
+      return str(entry.simple) || str(entry.hex) || undefined;
+    }
+    case "convertible_unit": {
+      const parsed = typeof value === "number" ? value : Number(value);
+      if (!Number.isFinite(parsed)) return undefined;
+      const digits = typeof config["precision"] === "number" ? config["precision"] : 2;
+      const unit = str(dto["unit"]) || str(config["unit_m"]) || str(config["unit_i"]);
+      const body = `${str(config["prefix"])}${parsed.toFixed(digits)}`;
+      return unit ? `${body} ${unit}` : body;
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** The `#RRGGBB` a `hex_color` value carries, when it carries one — the swatch
+ * a display skin paints beside the label. */
+export function hexColorSwatch(dto: FeatureValueDto | undefined): string | undefined {
+  const value = dto?.value;
+  if (value === null || value === undefined || typeof value !== "object") return undefined;
+  const hex = (value as { hex?: unknown }).hex;
+  return typeof hex === "string" && /^#(?:[0-9a-fA-F]{3}){1,2}$/.test(hex.trim())
+    ? hex.trim()
+    : undefined;
+}

package/src/i18n/es.ts

@@ -0,0 +1,41 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+
+/**
+ * Spanish bundle — the `@stapel/attributes-react/i18n/es` subpath, opt-in
+ * (i18n-shipping.md §2), same shape and same provenance caveat as `./ru`:
+ * stapel-attributes ships English only, so this copy is pair-authored and
+ * unreviewed, and deliberately worded to match forms-react's copy of the same
+ * twelve engine keys.
+ */
+export const attributesI18nBundleEs: I18nDictionary = {
+  "error.400.feature_below_minimum": "El valor es inferior al mínimo de {feature}",
+  "error.400.feature_above_maximum": "El valor supera el máximo de {feature}",
+  "error.400.feature_not_in_options": "El valor no está entre las opciones de {feature}",
+  "error.400.feature_invalid_type": "Tipo de valor no válido para {feature}",
+  "error.400.feature_invalid_format": "Formato no válido para {feature}",
+  "error.400.feature_mandatory_missing": "{feature} es obligatorio",
+  "error.400.feature_unknown_type": "Tipo de característica desconocido para {feature}",
+  "error.400.feature_not_allowed": "{feature} no se admite aquí",
+  "error.400.feature_unknown": "Característica desconocida {feature}",
+  "error.400.feature_invalid_config": "Configuración no válida de {feature}",
+  "error.400.description_too_short": "La descripción debe tener al menos {min_length} caracteres",
+  "error.400.description_too_long": "La descripción debe tener como máximo {max_length} caracteres",
+
+  "attributes.unsupported_type":
+    "Esta versión no incluye un editor para el tipo de atributo «{type}», así que no se puede rellenar aquí.",
+  "attributes.submit.blocked.unsupported_type":
+    "Algunos atributos no se pueden rellenar en esta página: {types}",
+  "attributes.untyped_feature": "Este atributo no declara ningún tipo y no se puede editar.",
+  "attributes.value.not_set": "Sin especificar",
+  "attributes.value.unreadable": "Esta versión no muestra valores de tipo «{type}»",
+  "attributes.bool.yes": "Sí",
+  "attributes.bool.no": "No",
+  "attributes.select.placeholder": "Elegir",
+  "attributes.required": "Obligatorio",
+};
+
+/** Register the `es` bundle. Call AFTER `registerAttributesI18n` so it
+ * overrides the English floor. */
+export function registerAttributesI18nEs(engine: I18nEngine, locale = "es"): void {
+  engine.registerBundle(locale, attributesI18nBundleEs);
+}

package/src/i18n/keys.ts

@@ -0,0 +1,89 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+
+/**
+ * `@stapel/attributes-react`'s own translation KEYS (frontend-standard §4.2):
+ * nothing in this package renders a literal string — a host resolves these
+ * through core's i18n engine (`useT`).
+ *
+ * Two families live here, and only two:
+ *
+ *  - `attributes.*` — this package's OWN chrome: the unsupported-type notice,
+ *    the blocked-submit reason, the empty/optional captions, the control
+ *    placeholders.
+ *  - `error.400.feature_*` / `error.400.description_*` — the engine's own
+ *    error catalogue (`stapel_attributes.errors.ATTRIBUTES_ERRORS`, registered
+ *    with stapel-core), carried here as an English floor so a host that has
+ *    not installed a pair whose `gen:errors` bundle includes them still shows
+ *    a sentence rather than a key. A host that HAS one registers it after
+ *    this bundle and the generated copy wins.
+ *
+ * ── What is NOT a key here ─────────────────────────────────────────────────
+ *
+ * A feature's `name` and its options' `label`s are admin-authored content
+ * carried in the category's own data, not keys of this package. When
+ * `config.translatable_options` is set (the default) those labels ARE
+ * translation keys — but they belong to the deployment's catalogue, not to
+ * this bundle, which is why the formatter takes a `t` and never a table.
+ */
+export const ATTRIBUTES_I18N_KEYS = {
+  /** The loud last rung of the resolution ladder. */
+  unsupportedType: "attributes.unsupported_type",
+  /** Why the submit is off while an undrawable feature is on screen. */
+  submitBlockedUnsupportedType: "attributes.submit.blocked.unsupported_type",
+  /** A feature whose config declares no type at all. */
+  untypedFeature: "attributes.untyped_feature",
+  /** Display side: the value is absent. Never rendered as an empty cell. */
+  valueNotSet: "attributes.value.not_set",
+  /** Display side: the type has no formatter in this build. */
+  valueUnreadable: "attributes.value.unreadable",
+  boolYes: "attributes.bool.yes",
+  boolNo: "attributes.bool.no",
+  selectPlaceholder: "attributes.select.placeholder",
+  required: "attributes.required",
+} as const;
+
+export type AttributesI18nKey =
+  (typeof ATTRIBUTES_I18N_KEYS)[keyof typeof ATTRIBUTES_I18N_KEYS];
+
+/**
+ * The engine's error catalogue, English — a verbatim mirror of
+ * `stapel_attributes.errors.ATTRIBUTES_ERRORS`, including its
+ * `{feature}`/`{min_length}`/`{max_length}` placeholders. Same key, same
+ * sentence, whichever side of the wire noticed the problem.
+ */
+export const ATTRIBUTES_ERROR_BUNDLE_EN: I18nDictionary = {
+  "error.400.feature_below_minimum": "Value is below minimum for {feature}",
+  "error.400.feature_above_maximum": "Value is above maximum for {feature}",
+  "error.400.feature_not_in_options": "Value is not in allowed options for {feature}",
+  "error.400.feature_invalid_type": "Invalid type for {feature}",
+  "error.400.feature_invalid_format": "Invalid format for {feature}",
+  "error.400.feature_mandatory_missing": "Mandatory feature {feature} is required",
+  "error.400.feature_unknown_type": "Unknown feature type for {feature}",
+  "error.400.feature_not_allowed": "Feature {feature} is not allowed here",
+  "error.400.feature_unknown": "Unknown feature {feature}",
+  "error.400.feature_invalid_config": "Invalid config for {feature}",
+  "error.400.description_too_short": "Description must be at least {min_length} characters",
+  "error.400.description_too_long": "Description must be at most {max_length} characters",
+};
+
+export const attributesI18nBundleEn: I18nDictionary = {
+  ...ATTRIBUTES_ERROR_BUNDLE_EN,
+  "attributes.unsupported_type":
+    "This build has no editor for the “{type}” attribute type, so it cannot be filled in here.",
+  "attributes.submit.blocked.unsupported_type":
+    "Some attributes cannot be filled in on this page: {types}",
+  "attributes.untyped_feature": "This attribute declares no type and cannot be edited.",
+  "attributes.value.not_set": "Not specified",
+  "attributes.value.unreadable": "Cannot display a “{type}” value in this build",
+  "attributes.bool.yes": "Yes",
+  "attributes.bool.no": "No",
+  "attributes.select.placeholder": "Choose",
+  "attributes.required": "Required",
+};
+
+/** Register the package's `en` floor into a core i18n engine (call once at
+ * startup, before any locale override — the convention every
+ * `@stapel/*-react` package follows). */
+export function registerAttributesI18n(engine: I18nEngine, locale = "en"): void {
+  engine.registerBundle(locale, attributesI18nBundleEn);
+}

package/src/i18n/ru.ts

@@ -0,0 +1,48 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+
+/**
+ * Russian bundle — the `@stapel/attributes-react/i18n/ru` subpath, opt-in
+ * (i18n-shipping.md §2): the main entry does not import this module, so a
+ * host that does not register it never carries these strings (gated by
+ * size-limit).
+ *
+ * PROVENANCE, stated rather than implied: stapel-attributes ships English
+ * only (no `translations/` directory — which is why `gen:errors` runs with
+ * `ERRORS_LOCALE_EXEMPT_OWNERS=stapel_attributes` for forms-react), so the
+ * error copy below is pair-authored, not upstream, and unreviewed. Same grade
+ * as forms-react's copy of the same twelve keys, and deliberately the same
+ * WORDING — two pairs must not give one refusal two sentences.
+ */
+export const attributesI18nBundleRu: I18nDictionary = {
+  "error.400.feature_below_minimum": "Значение меньше минимального для «{feature}»",
+  "error.400.feature_above_maximum": "Значение больше максимального для «{feature}»",
+  "error.400.feature_not_in_options":
+    "Значение отсутствует среди допустимых вариантов для «{feature}»",
+  "error.400.feature_invalid_type": "Неверный тип значения для «{feature}»",
+  "error.400.feature_invalid_format": "Неверный формат значения для «{feature}»",
+  "error.400.feature_mandatory_missing": "Поле «{feature}» обязательно для заполнения",
+  "error.400.feature_unknown_type": "Неизвестный тип поля «{feature}»",
+  "error.400.feature_not_allowed": "Поле «{feature}» здесь недопустимо",
+  "error.400.feature_unknown": "Неизвестное поле «{feature}»",
+  "error.400.feature_invalid_config": "Неверная конфигурация поля «{feature}»",
+  "error.400.description_too_short": "Описание должно содержать не менее {min_length} символов",
+  "error.400.description_too_long": "Описание должно содержать не более {max_length} символов",
+
+  "attributes.unsupported_type":
+    "В этой сборке нет редактора для типа характеристики «{type}», заполнить её здесь нельзя.",
+  "attributes.submit.blocked.unsupported_type":
+    "Часть характеристик нельзя заполнить на этой странице: {types}",
+  "attributes.untyped_feature": "У характеристики не указан тип, редактировать её нельзя.",
+  "attributes.value.not_set": "Не указано",
+  "attributes.value.unreadable": "Значение типа «{type}» в этой сборке не отображается",
+  "attributes.bool.yes": "Да",
+  "attributes.bool.no": "Нет",
+  "attributes.select.placeholder": "Выберите",
+  "attributes.required": "Обязательно",
+};
+
+/** Register the `ru` bundle. Call AFTER `registerAttributesI18n` so it
+ * overrides the English floor. */
+export function registerAttributesI18nRu(engine: I18nEngine, locale = "ru"): void {
+  engine.registerBundle(locale, attributesI18nBundleRu);
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+/**
+ * `@stapel/attributes-react` — the React value layer for `stapel-attributes`'
+ * dynamic feature types.
+ *
+ * ── What this package is, and what it deliberately is not ──────────────────
+ *
+ * It is an **L0 package, not a pair**, modelled on `@stapel/image`: no client,
+ * no queries, no `docs/schema.json`. Its backend counterpart is an L1 library
+ * with no HTTP surface whatsoever (`stapel-attributes/docs/readme.md`) — there
+ * is no `/attributes/api/v1/` to pair with. Feature definitions and validation
+ * verdicts reach a browser inside the responses of the modules that OWN them
+ * (categories, listings), and those pairs depend on this one to draw and check
+ * what they carry.
+ *
+ * It switches on **`config.type`** — the value type (`string`, `int`,
+ * `select`, `date`, `hex_color`, `hierarchical_select`, `convertible_unit`,
+ * `bool`, `float`, `header`). That is a DIFFERENT axis from the one
+ * `@stapel/forms-react` works on, which is `FormField.kind`: the field kinds
+ * of the admin form that CONFIGURES a type. Same upstream library, two
+ * vocabularies, and the storefront needs this one. A consequence worth
+ * stating because it removes an upstream ask: a storefront needs **no
+ * catalogue endpoint** for these types — the type arrives in the data, on
+ * every feature.
+ *
+ * ── The three-rung ladder, verbatim from forms-react ───────────────────────
+ *
+ *   explicit `registerValueEditor(type, …)`  ← a host's, always wins
+ *   → the skin's `BUILTIN_VALUE_EDITORS`     ← `/default`, ten types
+ *   → `<UnsupportedValueEditor/>`            ← loud, never a skipped field
+ *
+ * and, while an undrawable feature is on screen, `unsupportedTypeGate` blocks
+ * the submit with the reason NAMED. A category can legally carry a type this
+ * build has no editor for; drawing nothing would silently drop a feature that
+ * may be MANDATORY, and the person would submit a listing they could not
+ * complete and be told, by the server, that an attribute they never saw is
+ * missing.
+ *
+ * ── Layout ─────────────────────────────────────────────────────────────────
+ *
+ *   `.`          registry + mirror + DTO helpers + display formatting.
+ *                React types only; no antd, no react-router, no fetch.
+ *   `./default`  the antd skin: ten builtin editors, `<FeatureFields>`,
+ *                `<FeatureBadges>`, `<FeatureValueList>`.
+ *   `./i18n/ru`  opt-in locale bundles.
+ *   `./i18n/es`
+ */
+
+export type {
+  FeatureConfig,
+  FeatureDef,
+  FeatureValueDto,
+  FeatureValidationResult,
+  FeaturesDto,
+  ValidationBatchResult,
+  ValidationErrorCode,
+  ValidationStatus,
+} from "./types.js";
+export { featureConfig, featureName, featureType } from "./types.js";
+
+export {
+  UNTYPED_FEATURE,
+  registerValueEditor,
+  registeredValueEditorTypes,
+  resolveValueEditor,
+  unregisterValueEditor,
+  unsupportedTypeGate,
+  unsupportedTypes,
+} from "./registry.js";
+export type { ValueEditor, ValueEditorProps } from "./registry.js";
+
+export {
+  ERROR_CODE_TO_KEY,
+  VALIDATION_ERROR_CODES,
+  featureErrorsBySlug,
+  resultErrorKey,
+} from "./errors.js";
+
+export {
+  SIMPLE_COLORS,
+  codePointLength,
+  isBlank,
+  mirrorValidate,
+  patternFullMatch,
+  validateFeatureValue,
+} from "./validate.js";
+
+export { fromFeaturesDto, toFeaturesDto } from "./dto.js";
+
+export { FORMATTABLE_TYPES, formatFeatureValue, hexColorSwatch } from "./format.js";
+export type { FormatOptions } from "./format.js";
+
+export {
+  ATTRIBUTES_ERROR_BUNDLE_EN,
+  ATTRIBUTES_I18N_KEYS,
+  attributesI18nBundleEn,
+  registerAttributesI18n,
+} from "./i18n/keys.js";
+export type { AttributesI18nKey } from "./i18n/keys.js";