@stapel/attributes-react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `@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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,YAAY,EACV,aAAa,EACb,UAAU,EACV,eAAe,EACf,uBAAuB,EACvB,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAErE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,0BAA0B,EAC1B,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEnE,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,aAAa,EACb,eAAe,EACf,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE1D,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACpF,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,54 @@
+/**
+ * `@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 { featureConfig, featureName, featureType } from "./types.js";
+export { UNTYPED_FEATURE, registerValueEditor, registeredValueEditorTypes, resolveValueEditor, unregisterValueEditor, unsupportedTypeGate, unsupportedTypes, } 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 { ATTRIBUTES_ERROR_BUNDLE_EN, ATTRIBUTES_I18N_KEYS, attributesI18nBundleEn, registerAttributesI18n, } from "./i18n/keys.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAYH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAErE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,0BAA0B,EAC1B,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,aAAa,EACb,eAAe,EACf,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE1D,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGpF,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The value-editor registry — THE customer seam of this package, and the
+ * direct descendant of forms-react's field-widget registry.
+ *
+ * It keys on `config.type` (the VALUE type: `string`, `int`, `select`, …),
+ * not on `FormField.kind` (the admin config form's field kinds). That is the
+ * whole reason this package exists next to `@stapel/forms-react` rather than
+ * inside it: two different vocabularies, and L2 pairs may not import each
+ * other anyway (`stapel-react/README.md` — dependency direction is strictly
+ * downward).
+ *
+ * The type vocabulary is an OPEN registry server-side (builtins →
+ * `STAPEL_ATTRIBUTES["EXTRA_TYPES"]` → runtime `register_feature_type`), so a
+ * host that adds a type on the backend must be able to draw it on the front
+ * without forking the skin:
+ *
+ * ```tsx
+ * registerValueEditor("size_grid", SizeGridEditor); // at startup
+ * ```
+ *
+ * ── Resolution, and what happens when nothing matches ──────────────────────
+ *
+ * This module answers only the FIRST rung: an explicit registration, or
+ * `null`. The `/default` skin completes the ladder — explicit registration >
+ * skin builtin (antd) > **loud unsupported notice** — verbatim the ladder
+ * forms-react's `<StapelForm>` runs.
+ *
+ * The last rung is a notice, deliberately, and never a skipped field. A
+ * category can legally carry a type this build has no editor for; rendering
+ * 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. `unsupportedTypeGate` blocks
+ * the submit with the reason NAMED while such a feature is present — degrade
+ * loudly.
+ *
+ * The registry lives in the main entry, not in `/default`, so a host building
+ * its own renderer uses the same seam the skin does rather than a parallel
+ * one.
+ */
+import type { ComponentType } from "react";
+import type { FlowError } from "@stapel/core";
+import type { ActionAvailability } from "@stapel/core";
+import type { FeatureDef } from "./types.js";
+/**
+ * What every value editor receives. One feature, one value, one setter, one
+ * error — the editor never touches an API layer or the rest of the form.
+ */
+export interface ValueEditorProps<T = unknown> {
+    /** The feature being edited. `feature.config` carries the type's camelCase
+     * options (`maxLength`, `minSelected`, `precision`, `multiline`, …). */
+    readonly feature: FeatureDef;
+    /** The current answer, or `undefined` while unanswered. */
+    readonly value: T | undefined;
+    /** Report a new answer. Pass the type's own DTO `value` — bare for the
+     * scalar types, an array for `select`/`hierarchical_select`, an object for
+     * `hex_color` and `convertible_unit` (see `toFeaturesDto`). */
+    onChange(value: T | undefined): void;
+    /** The feature's current refusal (client mirror or server verdict), or
+     * `undefined`. */
+    readonly error?: FlowError | undefined;
+    /** True while a submit is in flight — editors should go read-only. */
+    readonly disabled?: boolean;
+    /**
+     * DOM id the editor MUST put on its primary control. The field row points
+     * its `<label for>` at this, so the label actually names the input for a
+     * screen reader (and for a click). An editor that drops it renders an
+     * unlabelled control — which antd's `Form.Item` cannot detect and will
+     * happily draw a label beside.
+     */
+    readonly id: string;
+}
+export type ValueEditor = ComponentType<ValueEditorProps>;
+/**
+ * Register (or override) the editor for a value type. Call at startup, before
+ * the first render — the registry is module-global, like the i18n bundle
+ * registration and forms-react's widget registry.
+ */
+export declare function registerValueEditor(type: string, editor: ValueEditor): void;
+/** Remove an explicit registration (the skin's builtin, if any, resolves
+ * again). */
+export declare function unregisterValueEditor(type: string): void;
+/**
+ * The EXPLICIT registration for a type, or `null`. Named for what it is: the
+ * skin calls this FIRST and only falls back to its own builtin when it
+ * returns `null`, so a host registration always wins.
+ */
+export declare function resolveValueEditor(type: string): ValueEditor | null;
+/** Every type with an explicit registration, sorted. */
+export declare function registeredValueEditorTypes(): readonly string[];
+/**
+ * The value types present in `features` that NOTHING can draw — neither an
+ * explicit registration nor the caller's builtin set.
+ *
+ * Pure and React-free on purpose: the headless half must be able to judge
+ * renderability without importing the skin, which is how forms-react's
+ * `<FormFill>` avoids pulling antd into a headless bundle. `builtinTypes` is
+ * therefore passed IN (the skin exports `BUILTIN_VALUE_EDITOR_TYPES`), not
+ * imported from here.
+ *
+ * A feature whose config declares no `type` at all counts as unsupported and
+ * is reported under `"(none)"` — an unnamed hole is still a hole, and a
+ * silently dropped mandatory attribute is the exact failure this returns
+ * data to prevent.
+ */
+export declare function unsupportedTypes(features: readonly FeatureDef[], builtinTypes: readonly string[]): readonly string[];
+/** What `unsupportedTypes` reports for a feature whose config names no type
+ * at all. Exported so a caller can tell "we cannot draw `size_grid`" from
+ * "this row has no type" without string-matching a message. */
+export declare const UNTYPED_FEATURE = "(none)";
+/**
+ * The submit gate for an unsupported type — blocked with the reason named,
+ * never a disabled button with no explanation.
+ *
+ * This package owns its own key (`attributes.submit.blocked.unsupported_type`)
+ * because it owns the fact. A pair with its own submit — listings-react's
+ * composer, say — raises its own `listings.compose.blocked.unsupported_type`
+ * from the SAME `unsupportedTypes` call and never re-derives the fact; both
+ * spellings say the same thing to the same person, and neither invents a
+ * silent third behaviour.
+ */
+export declare function unsupportedTypeGate(features: readonly FeatureDef[], builtinTypes: readonly string[]): ActionAvailability;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C;4EACwE;IACxE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;IAC9B;;mEAE+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC;IACrC;sBACkB;IAClB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IACvC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC,gBAAgB,CAAC,CAAC;AAI1D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAE3E;AAED;aACa;AACb,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAExD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAEnE;AAED,wDAAwD;AACxD,wBAAgB,0BAA0B,IAAI,SAAS,MAAM,EAAE,CAE9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,UAAU,EAAE,EAC/B,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,SAAS,MAAM,EAAE,CAYnB;AAED;;+DAE+D;AAC/D,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,UAAU,EAAE,EAC/B,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,kBAAkB,CAMpB"}

package/dist/registry.js

@@ -0,0 +1,82 @@
+import { actionAvailable, actionBlocked } from "@stapel/core";
+import { featureType } from "./types.js";
+import { ATTRIBUTES_I18N_KEYS } from "./i18n/keys.js";
+const registered = new Map();
+/**
+ * Register (or override) the editor for a value type. Call at startup, before
+ * the first render — the registry is module-global, like the i18n bundle
+ * registration and forms-react's widget registry.
+ */
+export function registerValueEditor(type, editor) {
+    registered.set(type, editor);
+}
+/** Remove an explicit registration (the skin's builtin, if any, resolves
+ * again). */
+export function unregisterValueEditor(type) {
+    registered.delete(type);
+}
+/**
+ * The EXPLICIT registration for a type, or `null`. Named for what it is: the
+ * skin calls this FIRST and only falls back to its own builtin when it
+ * returns `null`, so a host registration always wins.
+ */
+export function resolveValueEditor(type) {
+    return registered.get(type) ?? null;
+}
+/** Every type with an explicit registration, sorted. */
+export function registeredValueEditorTypes() {
+    return [...registered.keys()].sort();
+}
+/**
+ * The value types present in `features` that NOTHING can draw — neither an
+ * explicit registration nor the caller's builtin set.
+ *
+ * Pure and React-free on purpose: the headless half must be able to judge
+ * renderability without importing the skin, which is how forms-react's
+ * `<FormFill>` avoids pulling antd into a headless bundle. `builtinTypes` is
+ * therefore passed IN (the skin exports `BUILTIN_VALUE_EDITOR_TYPES`), not
+ * imported from here.
+ *
+ * A feature whose config declares no `type` at all counts as unsupported and
+ * is reported under `"(none)"` — an unnamed hole is still a hole, and a
+ * silently dropped mandatory attribute is the exact failure this returns
+ * data to prevent.
+ */
+export function unsupportedTypes(features, builtinTypes) {
+    const builtin = new Set(builtinTypes);
+    const out = new Set();
+    for (const feature of features) {
+        const type = featureType(feature);
+        if (type === undefined) {
+            out.add(UNTYPED_FEATURE);
+            continue;
+        }
+        if (resolveValueEditor(type) === null && !builtin.has(type))
+            out.add(type);
+    }
+    return [...out].sort();
+}
+/** What `unsupportedTypes` reports for a feature whose config names no type
+ * at all. Exported so a caller can tell "we cannot draw `size_grid`" from
+ * "this row has no type" without string-matching a message. */
+export const UNTYPED_FEATURE = "(none)";
+/**
+ * The submit gate for an unsupported type — blocked with the reason named,
+ * never a disabled button with no explanation.
+ *
+ * This package owns its own key (`attributes.submit.blocked.unsupported_type`)
+ * because it owns the fact. A pair with its own submit — listings-react's
+ * composer, say — raises its own `listings.compose.blocked.unsupported_type`
+ * from the SAME `unsupportedTypes` call and never re-derives the fact; both
+ * spellings say the same thing to the same person, and neither invents a
+ * silent third behaviour.
+ */
+export function unsupportedTypeGate(features, builtinTypes) {
+    const types = unsupportedTypes(features, builtinTypes);
+    if (types.length === 0)
+        return actionAvailable();
+    return actionBlocked(ATTRIBUTES_I18N_KEYS.submitBlockedUnsupportedType, {
+        types: types.join(", "),
+    });
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAyCA,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG9D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAiCtD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAuB,CAAC;AAElD;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,MAAmB;IACnE,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED;aACa;AACb,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AACtC,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,0BAA0B;IACxC,OAAO,CAAC,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAA+B,EAC/B,YAA+B;IAE/B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,GAAG,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QACD,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED;;+DAE+D;AAC/D,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAA+B,EAC/B,YAA+B;IAE/B,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IACvD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,eAAe,EAAE,CAAC;IACjD,OAAO,aAAa,CAAC,oBAAoB,CAAC,4BAA4B,EAAE;QACtE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;KACxB,CAAC,CAAC;AACL,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The wire shapes of `stapel_attributes`, as this package sees them.
+ *
+ * There is no generated `schema.ts` here and there never will be:
+ * stapel-attributes is an **L1 library with no HTTP surface at all** — no
+ * models, no views, no urls (`stapel-attributes/docs/readme.md`), so it emits
+ * no `docs/schema.json` for `pnpm gen:api` to read. Its shapes reach a browser
+ * embedded in someone ELSE's response: a category's features arrive from
+ * `GET /categories/api/v1/categories/{id}/features/`, a validation verdict
+ * from `POST /categories/{pk}/validate-dto/` and from
+ * `POST /listings/{pk}/publish/`. The owning pair generates those; this
+ * package types the payload they carry.
+ *
+ * Every field here was read off the Python it mirrors, and the mirrors are
+ * named in the doc comments so the next person can check rather than trust.
+ */
+/**
+ * A feature's type-specific configuration. `type` is the discriminator — the
+ * **value type's slug**, and the axis this whole package switches on.
+ *
+ * ── The distinction that must not be swallowed ─────────────────────────────
+ *
+ * stapel-attributes has TWO field vocabularies, and `@stapel/forms-react`
+ * works with the other one:
+ *
+ *  - `FormField.kind` (`stapel_attributes/config_form.py`) — the field kinds
+ *    of the ADMIN form that configures a type. That is what
+ *    `GET /forms/api/v1/field-kinds` enumerates and what forms-react's widget
+ *    registry keys on.
+ *  - `config["type"]` — the VALUE type: `int`, `float`, `string`, `bool`,
+ *    `hex_color`, `select`, `date`, `header`, `hierarchical_select`,
+ *    `convertible_unit`. That is what a person filling in a listing actually
+ *    edits, and it is what this package keys on.
+ *
+ * A storefront therefore needs **no catalogue endpoint**: the type arrives in
+ * the data, on every feature.
+ *
+ * `type` is optional here because the wire can omit it. The features endpoint
+ * serializes `obj.config` verbatim (`stapel-categories`
+ * `FeatureCompactSerializer.get_config`), NOT `get_config_with_defaults()`, so
+ * a config saved without its defaults arrives without them — including,
+ * for a malformed row, without a `type`. A missing type is an unsupported
+ * type, loudly, rather than a crash.
+ */
+export interface FeatureConfig {
+    readonly type?: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * One feature of a category — the browser's view of `stapel_attributes.base
+ * .FeatureDef`, as `stapel-categories`' `FeatureCompactSerializer` sends it
+ * (`fields = [id, tn_parent, name, slug, icon, comment, config, mandatory,
+ * show_as_badge, show_at_title, translate]`).
+ */
+export interface FeatureDef {
+    /** Payload key this feature's value is submitted under. */
+    readonly slug: string;
+    readonly config?: FeatureConfig;
+    readonly id?: number | string | null;
+    /** Display name or translation key. Falls back to `slug` server-side. */
+    readonly name?: string | null;
+    readonly mandatory?: boolean;
+    readonly show_at_title?: boolean;
+    readonly show_as_badge?: boolean;
+    readonly translate?: string | null;
+    readonly icon?: string | null;
+    readonly comment?: string | null;
+    readonly tn_parent?: number | string | null;
+}
+/**
+ * One submitted value: `{type, value}` plus whatever else the type's DTO
+ * carries. Exactly one builtin adds a key — `convertible_unit`, whose DTO is
+ * `{type, value, unit}` because the number has to be tagged with the unit it
+ * was typed in before the server converts to the family's base unit.
+ */
+export interface FeatureValueDto {
+    readonly type: string;
+    readonly value: unknown;
+    readonly [key: string]: unknown;
+}
+/** The `features_draft`-shaped payload: `{slug: {type, value}}`. */
+export type FeaturesDto = Readonly<Record<string, FeatureValueDto>>;
+/** `stapel_attributes.results.ValidationStatus`. */
+export type ValidationStatus = "ok" | "validation_failed";
+/**
+ * `stapel_attributes.results.ValidationErrorCode`, mirrored.
+ *
+ * Pinned against the engine's own generated corpus
+ * (`stapel-attributes/tests/golden/error_codes.json`, itself generated from
+ * the enum and asserted by both the Python and the TypeScript half of the
+ * cross-language bridge) — see `test/contract.test.ts`.
+ */
+export type 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";
+/**
+ * One row of a batch verdict — `stapel_attributes.results
+ * .FeatureValidationResult` as its DRF serializer sends it.
+ *
+ * `slug` is the routing key: it is what puts a refusal on a control. The
+ * server's `params` carry `{feature, slug}` (never `field`), so
+ * `featureErrorsBySlug` adds `field` when folding a row into a `FlowError`,
+ * which is what the fleet's `useFieldError` convention reads.
+ */
+export interface FeatureValidationResult {
+    readonly slug: string;
+    readonly status: ValidationStatus;
+    readonly id?: number | string | null;
+    readonly error?: ValidationErrorCode | null;
+    /** The constraint that was violated (a limit, a list of options). */
+    readonly ref_value?: unknown;
+    readonly message?: string | null;
+    /** `error.400.feature_*` — the key a person's sentence comes from. */
+    readonly localizable_error?: string | null;
+    readonly params?: Readonly<Record<string, unknown>> | null;
+    /** Non-blocking findings (e.g. config keys the parser dropped). Never
+     * flips `valid` — a warning is not a refusal. */
+    readonly warnings?: readonly string[] | null;
+}
+/** `stapel_attributes.results.ValidationBatchResult`. */
+export interface ValidationBatchResult {
+    readonly valid: boolean;
+    readonly results: readonly FeatureValidationResult[];
+}
+/**
+ * A feature's declared value type, or `undefined` when the config carries
+ * none. The ONE place `config.type` is read, so "which axis is this?" has a
+ * single answer in this package.
+ */
+export declare function featureType(feature: FeatureDef): string | undefined;
+/** A feature's config, never `undefined` — saves every reader a `?? {}`. */
+export declare function featureConfig(feature: FeatureDef): FeatureConfig;
+/** A feature's display name, falling back to its slug exactly as
+ * `FeatureDef.__post_init__` does server-side. */
+export declare function featureName(feature: FeatureDef): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,35 @@
+/**
+ * The wire shapes of `stapel_attributes`, as this package sees them.
+ *
+ * There is no generated `schema.ts` here and there never will be:
+ * stapel-attributes is an **L1 library with no HTTP surface at all** — no
+ * models, no views, no urls (`stapel-attributes/docs/readme.md`), so it emits
+ * no `docs/schema.json` for `pnpm gen:api` to read. Its shapes reach a browser
+ * embedded in someone ELSE's response: a category's features arrive from
+ * `GET /categories/api/v1/categories/{id}/features/`, a validation verdict
+ * from `POST /categories/{pk}/validate-dto/` and from
+ * `POST /listings/{pk}/publish/`. The owning pair generates those; this
+ * package types the payload they carry.
+ *
+ * Every field here was read off the Python it mirrors, and the mirrors are
+ * named in the doc comments so the next person can check rather than trust.
+ */
+/**
+ * A feature's declared value type, or `undefined` when the config carries
+ * none. The ONE place `config.type` is read, so "which axis is this?" has a
+ * single answer in this package.
+ */
+export function featureType(feature) {
+    const type = feature.config?.type;
+    return typeof type === "string" && type.length > 0 ? type : undefined;
+}
+/** A feature's config, never `undefined` — saves every reader a `?? {}`. */
+export function featureConfig(feature) {
+    return feature.config ?? {};
+}
+/** A feature's display name, falling back to its slug exactly as
+ * `FeatureDef.__post_init__` does server-side. */
+export function featureName(feature) {
+    return feature.name ?? feature.slug;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAmIH;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAAmB;IAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC;IAClC,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACxE,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,aAAa,CAAC,OAAmB;IAC/C,OAAO,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED;kDACkD;AAClD,MAAM,UAAU,WAAW,CAAC,OAAmB;IAC7C,OAAO,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;AACtC,CAAC"}

package/dist/validate.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The client-side validation MIRROR — instant feedback, never a verdict.
+ *
+ * "Client-side validation mirrors, server decides." Every rule here is
+ * derived from the feature's own `config` so a person sees a problem as they
+ * type instead of after a round trip; none of it is trusted. The server
+ * re-runs `stapel_attributes.validate_dto_structured` on
+ * `POST /categories/{pk}/validate-dto/` and again on
+ * `POST /listings/{pk}/publish/`, and its `ValidationBatchResult` is the one
+ * that counts. This function returns the SAME shape so a server answer can
+ * replace a mirrored one with no translation step.
+ *
+ * ── Two contract details that are easy to get subtly wrong ─────────────────
+ *
+ * 1. **`pattern` matches the WHOLE value.** The engine uses `re.fullmatch`,
+ *    and the admin JS mirrors it as `^(?:<pattern>)$`
+ *    (`stapel-attributes/MODULE.md`, "Pattern contract"). A bare
+ *    `RegExp.test` is a PREFIX match, so `^\d{4}$`-less patterns would pass
+ *    here and fail there — the mirror telling a person their input is fine
+ *    right before the server refuses it.
+ *
+ * 2. **String length is counted in Unicode CODE POINTS**, on both sides —
+ *    same source. JavaScript's `String.length` counts UTF-16 code units, so
+ *    one emoji is 2 and one astral CJK ideograph is 2. A `maxLength: 10`
+ *    field would refuse ten emoji locally and accept them server-side.
+ *
+ * ── What the mirror deliberately does NOT judge ────────────────────────────
+ *
+ * - **A value type it does not know.** An unknown `config.type` may be a
+ *   perfectly valid `EXTRA_TYPES` registration whose rules live only in
+ *   Python. The mirror runs the type-independent checks (mandatory/empty) and
+ *   leaves the rest to the server — a mirror that invented a refusal for a
+ *   type it cannot read would block a submit the backend would have accepted.
+ *   Whether such a type can be DRAWN is a separate question, answered loudly
+ *   by `unsupportedTypes`/`unsupportedTypeGate`.
+ *
+ * - **`convertible_unit` range.** `min`/`max` are expressed in the unit
+ *   family's canonical base unit and the value is converted before comparison
+ *   (`stapel_attributes.types.convertible_unit`), and the family table is
+ *   Python-side. Mirroring the comparison without the conversion would report
+ *   "too large" for a perfectly good number in the other unit system. The
+ *   number and the unit code ARE checked; the range is the server's.
+ */
+import type { FeatureDef, FeatureValidationResult, FeaturesDto, FeatureValueDto, ValidationBatchResult } from "./types.js";
+/** `stapel_attributes.types.hex_color.constants.SIMPLE_COLORS` — the closed
+ * set of colour categories a `hex_color` value must name. */
+export declare const SIMPLE_COLORS: readonly string[];
+/** Length in Unicode code points — the unit BOTH sides count in. */
+export declare function codePointLength(text: string): number;
+/**
+ * Does `pattern` match the WHOLE of `text`? `re.fullmatch`, in JavaScript.
+ *
+ * A pattern JS cannot compile (a Python-only construct) is NOT the person's
+ * problem: the mirror stands down and lets the server, which compiled it, be
+ * the one to refuse. The `u` flag is tried first because it is what makes `.`
+ * and quantifiers count code points rather than surrogate halves, and dropped
+ * when a pattern is only valid without it.
+ */
+export declare function patternFullMatch(pattern: string, text: string): boolean | undefined;
+/**
+ * "Nothing was entered" — the one shape the mandatory rule fires on, and the
+ * engine's own predicate: `raw_value is None or raw_value == '' or
+ * raw_value == []` (`validation.py`). An explicit `false` is an ANSWER for a
+ * `bool`, and `0` is an answer for an `int`, which is why this is not a
+ * falsiness check.
+ */
+export declare function isBlank(value: unknown): boolean;
+/**
+ * Validate one submitted value against its feature's config. Returns the
+ * mirrored refusal, or `undefined` when this side of the wire is satisfied.
+ *
+ * `header` is never validated: the engine regenerates a header's DAO from its
+ * config and skips it outright in the batch validator, so a header has
+ * nothing to check and must never carry a value.
+ */
+export declare function validateFeatureValue(feature: FeatureDef, dto: FeatureValueDto): FeatureValidationResult | undefined;
+/**
+ * Validate a whole answer set against a category's features — the client-side
+ * twin of `POST /categories/{pk}/validate-dto/`.
+ *
+ * Mirrors the engine's two passes and their order, because the order is what
+ * a caller sees: first every SUBMITTED entry whose slug the category allows
+ * (an unknown slug is ignored, not refused — the engine's documented
+ * behaviour), then every allowed feature that was never submitted, of which
+ * only a mandatory non-header one produces a row.
+ */
+export declare function mirrorValidate(features: readonly FeatureDef[], dto: FeaturesDto): ValidationBatchResult;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,KAAK,EACV,UAAU,EACV,uBAAuB,EACvB,WAAW,EACX,eAAe,EACf,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AAIpB;6DAC6D;AAC7D,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAmB1C,CAAC;AAaF,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAUnF;AAqBD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAK/C;AAmPD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,eAAe,GACnB,uBAAuB,GAAG,SAAS,CAsCrC;AAyBD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,SAAS,UAAU,EAAE,EAC/B,GAAG,EAAE,WAAW,GACf,qBAAqB,CA+BvB"}