@marianmeres/stuic 3.153.0 → 3.154.0

package/dist/components/FieldsBuilder/index.css

@@ -0,0 +1,187 @@
+/* ============================================================================
+   FIELDS BUILDER COMPONENT TOKENS
+   Override globally: :root { --stuic-fields-builder-row-border: red; }
+   Override locally:  <FieldsBuilder style="--stuic-fields-builder-chip-bg: ..." />
+   ============================================================================ */
+
+/* prettier-ignore */
+:root {
+	--stuic-fields-builder-row-border: var(--stuic-color-border);
+	--stuic-fields-builder-row-toggle-bg-hover: var(--stuic-color-muted);
+	--stuic-fields-builder-key-text: var(--stuic-color-muted-foreground);
+	--stuic-fields-builder-chip-bg: var(--stuic-color-muted);
+	--stuic-fields-builder-chip-text: var(--stuic-color-muted-foreground);
+	--stuic-fields-builder-muted-text: var(--stuic-color-muted-foreground);
+	--stuic-fields-builder-warning-text: var(--stuic-color-surface-warning-foreground);
+	--stuic-fields-builder-error-text: var(--stuic-color-destructive);
+	--stuic-fields-builder-drop-indicator-color: var(--stuic-color-primary);
+	--stuic-fields-builder-drop-indicator-height: 2px;
+	--stuic-fields-builder-row-opacity-dragging: 0.4;
+	--stuic-fields-builder-row-opacity-deleted: 0.55;
+	--stuic-fields-builder-preview-border: var(--stuic-color-border);
+}
+
+@layer components {
+	/* =============================================================================
+	   ROWS
+	   ============================================================================= */
+
+	.stuic-fields-builder .fb-row-divider {
+		border-top: 1px solid var(--stuic-fields-builder-row-border);
+	}
+
+	.stuic-fields-builder .fb-row[data-dragging] {
+		opacity: var(--stuic-fields-builder-row-opacity-dragging);
+	}
+
+	.stuic-fields-builder .fb-row[data-drop-position="before"] {
+		box-shadow: inset 0 var(--stuic-fields-builder-drop-indicator-height) 0
+			var(--stuic-fields-builder-drop-indicator-color);
+	}
+
+	.stuic-fields-builder .fb-row[data-drop-position="after"] {
+		box-shadow: inset 0 calc(-1 * var(--stuic-fields-builder-drop-indicator-height)) 0
+			var(--stuic-fields-builder-drop-indicator-color);
+	}
+
+	.stuic-fields-builder .fb-row-deleted .fb-row-header {
+		opacity: var(--stuic-fields-builder-row-opacity-deleted);
+	}
+
+	.stuic-fields-builder .fb-row-deleted .fb-row-label {
+		text-decoration: line-through;
+	}
+
+	/* =============================================================================
+	   ROW HEADER
+	   ============================================================================= */
+
+	.stuic-fields-builder .fb-row-header {
+		padding-block: calc(var(--spacing) * 1);
+	}
+
+	.stuic-fields-builder .fb-row-toggle {
+		padding: calc(var(--spacing) * 1.5) calc(var(--spacing) * 1);
+		transition: background var(--stuic-transition);
+	}
+
+	.stuic-fields-builder .fb-row-toggle:hover:not(:disabled) {
+		background: var(--stuic-fields-builder-row-toggle-bg-hover);
+	}
+
+	.stuic-fields-builder .fb-row-toggle:disabled {
+		cursor: default;
+	}
+
+	.stuic-fields-builder .fb-row-label {
+		font-weight: 500;
+	}
+
+	.stuic-fields-builder .fb-row-required {
+		opacity: 0.5;
+	}
+
+	.stuic-fields-builder .fb-key {
+		font-family: var(--font-mono);
+		font-size: var(--text-xs);
+		color: var(--stuic-fields-builder-key-text);
+	}
+
+	.stuic-fields-builder .fb-chip {
+		background: var(--stuic-fields-builder-chip-bg);
+		color: var(--stuic-fields-builder-chip-text);
+		font-size: var(--text-xs);
+		padding: calc(var(--spacing) * 0.5) calc(var(--spacing) * 1.5);
+		border-radius: var(--stuic-fields-builder-chip-radius, var(--stuic-radius));
+		white-space: nowrap;
+	}
+
+	.stuic-fields-builder .fb-chip-warning {
+		color: var(--stuic-fields-builder-warning-text);
+	}
+
+	.stuic-fields-builder .fb-chevron {
+		opacity: 0.5;
+	}
+
+	.stuic-fields-builder .fb-handle {
+		cursor: grab;
+		opacity: 0.4;
+		touch-action: none;
+	}
+
+	.stuic-fields-builder .fb-handle:hover {
+		opacity: 1;
+	}
+
+	.stuic-fields-builder .fb-handle-spacer {
+		width: 16px;
+	}
+
+	/* =============================================================================
+	   ROW BODY (expanded editor)
+	   ============================================================================= */
+
+	.stuic-fields-builder .fb-row-body {
+		display: flex;
+		flex-direction: column;
+		gap: calc(var(--spacing) * 3);
+		padding: calc(var(--spacing) * 1) calc(var(--spacing) * 2) calc(var(--spacing) * 3)
+			calc(var(--spacing) * 2);
+	}
+
+	.stuic-fields-builder .fb-sub-label {
+		display: block;
+		font-size: var(--text-xs);
+		font-weight: 500;
+		color: var(--stuic-fields-builder-muted-text);
+		margin-bottom: calc(var(--spacing) * 0.5);
+	}
+
+	.stuic-fields-builder .fb-hint {
+		color: var(--stuic-fields-builder-muted-text);
+	}
+
+	.stuic-fields-builder .fb-error-text {
+		color: var(--stuic-fields-builder-error-text);
+	}
+
+	.stuic-fields-builder .fb-warning-text {
+		color: var(--stuic-fields-builder-warning-text);
+	}
+
+	.stuic-fields-builder .fb-advanced-toggle {
+		color: var(--stuic-fields-builder-muted-text);
+		transition: color var(--stuic-transition);
+	}
+
+	.stuic-fields-builder .fb-advanced-toggle:hover {
+		color: var(--stuic-color-foreground);
+	}
+
+	/* =============================================================================
+	   OPTIONS EDITOR
+	   ============================================================================= */
+
+	.stuic-fields-builder .fb-option-divider {
+		border-top: 1px dashed var(--stuic-fields-builder-row-border);
+	}
+
+	/* =============================================================================
+	   PREVIEW PANE
+	   ============================================================================= */
+
+	.stuic-fields-builder .fb-preview-side {
+		border-left: 1px solid var(--stuic-fields-builder-preview-border);
+	}
+
+	.stuic-fields-builder .fb-preview-below {
+		border-top: 1px solid var(--stuic-fields-builder-preview-border);
+	}
+
+	.stuic-fields-builder .fb-preview-title {
+		color: var(--stuic-fields-builder-muted-text);
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+	}
+}

package/dist/components/FieldsBuilder/index.d.ts

@@ -0,0 +1,5 @@
+export { default as FieldsBuilder, type Props as FieldsBuilderProps, } from "./FieldsBuilder.svelte";
+export type { FieldDef, FieldLock, FieldOptionDef, FieldTypeDef, FieldTypeExtraDef, LocalizedText, } from "./types.js";
+export { DEFAULT_FIELD_TYPES as FIELDS_BUILDER_DEFAULT_TYPES, DEFAULT_KEY_PATTERN as FIELDS_BUILDER_DEFAULT_KEY_PATTERN, getLocalizedText, slugifyKey, uniqueKey, validateFieldDefs, type FieldDefRowErrors, type FieldDefsValidationResult, type ValidateFieldDefsOptions, } from "./utils.js";
+export { createFieldsBuilderT, FIELDS_BUILDER_MESSAGES_EN, type FieldsBuilderMessageKey, type FieldsBuilderMessages, } from "./i18n.js";
+export { FIELDS_BUILDER_MESSAGES_SK, FIELDS_BUILDER_DEFAULT_TYPES_SK, } from "./i18n-sk.js";

package/dist/components/FieldsBuilder/index.js

@@ -0,0 +1,4 @@
+export { default as FieldsBuilder, } from "./FieldsBuilder.svelte";
+export { DEFAULT_FIELD_TYPES as FIELDS_BUILDER_DEFAULT_TYPES, DEFAULT_KEY_PATTERN as FIELDS_BUILDER_DEFAULT_KEY_PATTERN, getLocalizedText, slugifyKey, uniqueKey, validateFieldDefs, } from "./utils.js";
+export { createFieldsBuilderT, FIELDS_BUILDER_MESSAGES_EN, } from "./i18n.js";
+export { FIELDS_BUILDER_MESSAGES_SK, FIELDS_BUILDER_DEFAULT_TYPES_SK, } from "./i18n-sk.js";

package/dist/components/FieldsBuilder/types.d.ts

@@ -0,0 +1,76 @@
+import type { Snippet } from "svelte";
+/** A localized string: either one plain string, or a per-language map. */
+export type LocalizedText = string | Record<string, string>;
+/** A single option of a choice-like field type (one declaring `supportsOptions`). */
+export interface FieldOptionDef {
+    /** Machine value, unique within the field's options. */
+    value: string;
+    label: LocalizedText;
+}
+/** What the user may NOT change on a field. Absent flag = editable. */
+export interface FieldLock {
+    key?: boolean;
+    type?: boolean;
+    required?: boolean;
+    options?: boolean;
+    /** Cannot be removed from the list. */
+    delete?: boolean;
+    /** Cannot be dragged, and other fields cannot be moved past it. */
+    reorder?: boolean;
+}
+/**
+ * One field definition — the unit of the `FieldsBuilder` value. The component
+ * emits an ordered `FieldDef[]`; what the list is compiled into (a form, a
+ * schema, a template...) is entirely the consumer's business.
+ */
+export interface FieldDef {
+    /** Machine key. Unique within the list. */
+    key: string;
+    /** One of the `types` palette entries' `type`. */
+    type: string;
+    label: LocalizedText;
+    description?: LocalizedText;
+    required?: boolean;
+    /**
+     * Edited and validated only for palette entries declaring
+     * `supportsOptions`. NOTE: when a field's type is changed away from a
+     * choice type, existing `options` are deliberately RETAINED on the def
+     * (never silently drop data; switching back restores them) — consumers
+     * compiling the list should ignore `options` on non-choice types.
+     */
+    options?: FieldOptionDef[];
+    /**
+     * Per-type extra flags, driven by the palette entry's `extras`. An open bag
+     * on purpose — the component never interprets these, it only renders a
+     * control per declared extra and round-trips the value.
+     */
+    extras?: Record<string, unknown>;
+    /** What the user may NOT change. Absent = fully editable. */
+    lock?: FieldLock;
+}
+/** An extra per-field control declared by a palette entry (v1: booleans only). */
+export interface FieldTypeExtraDef {
+    /** Stored under `FieldDef.extras[key]`. */
+    key: string;
+    label: LocalizedText;
+    description?: LocalizedText;
+    /** v1: booleans only (rendered as a checkbox). */
+    type: "boolean";
+    default?: boolean;
+}
+/** One entry of the type palette (the `types` prop). */
+export interface FieldTypeDef {
+    /** Stored in `FieldDef.type`. */
+    type: string;
+    /** Shown in the type picker. */
+    label: LocalizedText;
+    description?: LocalizedText;
+    /** Icon html string (e.g. from `@marianmeres/icons-fns`) or a snippet. */
+    icon?: string | Snippet;
+    /** Renders the option editor and allows `FieldDef.options`. */
+    supportsOptions?: boolean;
+    /** Extra per-field controls, rendered into `FieldDef.extras[key]`. */
+    extras?: FieldTypeExtraDef[];
+    /** Optional live preview of a single field of this type. */
+    preview?: Snippet<[FieldDef]>;
+}

package/dist/components/FieldsBuilder/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/FieldsBuilder/utils.d.ts

@@ -0,0 +1,66 @@
+import type { FieldDef, FieldTypeDef, LocalizedText } from "./types.js";
+/** Default machine-key policy: lowercase snake_case, starts with a letter, max 63 chars. */
+export declare const DEFAULT_KEY_PATTERN: RegExp;
+export declare const DEFAULT_KEY_MAX_LENGTH = 63;
+/** Minimal translate signature the pure helpers below need. */
+export type FieldsBuilderTranslate = (key: string, values?: Record<string, string | number>) => string;
+/**
+ * Read the display text of a `LocalizedText`: the string itself, the preferred
+ * language's entry, or the first non-empty entry as a fallback.
+ */
+export declare function getLocalizedText(text: LocalizedText | null | undefined, preferredLanguage?: string): string;
+/**
+ * Derive a machine key from a human label: transliterates diacritics
+ * (`Ročník` → `rocnik`), lowercases, collapses everything else to `_`. A slug
+ * not starting with a letter is prefixed with `f_` (`2024` → `f_2024`) so the
+ * result always satisfies `DEFAULT_KEY_PATTERN`.
+ */
+export declare function slugifyKey(input: string, maxLength?: number): string;
+/**
+ * Make `base` unique against `isTaken` by suffixing `_2`, `_3`, ... The base is
+ * truncated when a suffixed candidate would exceed `maxLength`.
+ */
+export declare function uniqueKey(base: string, isTaken: (key: string) => boolean, maxLength?: number): string;
+export declare function isKeyReserved(key: string, reservedKeys?: string[] | ((key: string) => boolean)): boolean;
+export interface FieldDefRowErrors {
+    label?: string;
+    key?: string;
+    options?: string;
+}
+export interface FieldDefsValidationResult {
+    valid: boolean;
+    /** First error found — the component-level summary message. Empty when valid. */
+    message: string;
+    /** Index-aligned with the input defs. `null` = row has no errors. */
+    rowErrors: (FieldDefRowErrors | null)[];
+}
+export interface ValidateFieldDefsOptions {
+    /**
+     * The type palette. When provided, defs with a `type` not present here are
+     * treated as unknown: they are NOT validated (they round-trip untouched and
+     * must never block the rest of the list), but their keys still count toward
+     * uniqueness.
+     */
+    types?: Pick<FieldTypeDef, "type" | "supportsOptions">[];
+    keyPattern?: RegExp;
+    keyMaxLength?: number;
+    reservedKeys?: string[] | ((key: string) => boolean);
+    maxFields?: number;
+    defaultLanguage?: string;
+    /** Translator for the error messages; defaults to returning the message key. */
+    t?: FieldsBuilderTranslate;
+}
+/**
+ * Validate a list of field defs: label non-empty, key present/pattern/length/
+ * unique/not-reserved, choice types have at least one option with non-empty
+ * unique values, `maxFields` not exceeded.
+ *
+ * This is client-side convenience only — a consumer persisting the list MUST
+ * re-validate server-side; this function is not a security boundary.
+ */
+export declare function validateFieldDefs(defs: FieldDef[], opts?: ValidateFieldDefsOptions): FieldDefsValidationResult;
+/**
+ * A small general-purpose palette — handy for demos and for consumers with no
+ * opinion. `types` is a required prop, so nobody gets this by accident.
+ */
+export declare const DEFAULT_FIELD_TYPES: FieldTypeDef[];

package/dist/components/FieldsBuilder/utils.js

@@ -0,0 +1,153 @@
+/** Default machine-key policy: lowercase snake_case, starts with a letter, max 63 chars. */
+export const DEFAULT_KEY_PATTERN = /^[a-z][a-z0-9_]{0,62}$/;
+export const DEFAULT_KEY_MAX_LENGTH = 63;
+/**
+ * Read the display text of a `LocalizedText`: the string itself, the preferred
+ * language's entry, or the first non-empty entry as a fallback.
+ */
+export function getLocalizedText(text, preferredLanguage) {
+    if (text == null)
+        return "";
+    if (typeof text === "string")
+        return text;
+    if (preferredLanguage && text[preferredLanguage])
+        return text[preferredLanguage];
+    for (const v of Object.values(text))
+        if (v)
+            return v;
+    return "";
+}
+/**
+ * Derive a machine key from a human label: transliterates diacritics
+ * (`Ročník` → `rocnik`), lowercases, collapses everything else to `_`. A slug
+ * not starting with a letter is prefixed with `f_` (`2024` → `f_2024`) so the
+ * result always satisfies `DEFAULT_KEY_PATTERN`.
+ */
+export function slugifyKey(input, maxLength = DEFAULT_KEY_MAX_LENGTH) {
+    let s = (input ?? "")
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (s && !/^[a-z]/.test(s))
+        s = `f_${s}`;
+    if (maxLength > 0 && s.length > maxLength) {
+        s = s.slice(0, maxLength).replace(/_+$/, "");
+    }
+    return s;
+}
+/**
+ * Make `base` unique against `isTaken` by suffixing `_2`, `_3`, ... The base is
+ * truncated when a suffixed candidate would exceed `maxLength`.
+ */
+export function uniqueKey(base, isTaken, maxLength = DEFAULT_KEY_MAX_LENGTH) {
+    if (!base || !isTaken(base))
+        return base;
+    for (let i = 2; i < 1_000; i++) {
+        const suffix = `_${i}`;
+        let candidate = base + suffix;
+        if (maxLength > 0 && candidate.length > maxLength) {
+            candidate = base.slice(0, maxLength - suffix.length).replace(/_+$/, "") + suffix;
+        }
+        if (!isTaken(candidate))
+            return candidate;
+    }
+    return base;
+}
+export function isKeyReserved(key, reservedKeys) {
+    if (!reservedKeys)
+        return false;
+    return typeof reservedKeys === "function"
+        ? !!reservedKeys(key)
+        : reservedKeys.includes(key);
+}
+/**
+ * Validate a list of field defs: label non-empty, key present/pattern/length/
+ * unique/not-reserved, choice types have at least one option with non-empty
+ * unique values, `maxFields` not exceeded.
+ *
+ * This is client-side convenience only — a consumer persisting the list MUST
+ * re-validate server-side; this function is not a security boundary.
+ */
+export function validateFieldDefs(defs, opts = {}) {
+    const t = opts.t ?? ((k) => k);
+    const keyPattern = opts.keyPattern ?? DEFAULT_KEY_PATTERN;
+    const keyMaxLength = opts.keyMaxLength ?? DEFAULT_KEY_MAX_LENGTH;
+    const typeMap = opts.types ? new Map(opts.types.map((td) => [td.type, td])) : null;
+    const rowErrors = defs.map(() => null);
+    const put = (i, field, msg) => {
+        rowErrors[i] ??= {};
+        rowErrors[i][field] ??= msg;
+    };
+    // keys of ALL defs (incl. unknown types) occupy the key space
+    const keyCounts = new Map();
+    for (const d of defs) {
+        const k = (d.key ?? "").trim();
+        if (k)
+            keyCounts.set(k, (keyCounts.get(k) ?? 0) + 1);
+    }
+    defs.forEach((d, i) => {
+        // unknown type: keep as-is, do not block (see the doc comment above)
+        if (typeMap && !typeMap.has(d.type))
+            return;
+        if (!getLocalizedText(d.label, opts.defaultLanguage).trim()) {
+            put(i, "label", t("err_label_required"));
+        }
+        // presence is checked trimmed, but pattern/length run on the RAW key —
+        // a whitespace-padded key must fail here, not at the consumer's gate
+        const k = d.key ?? "";
+        if (!k.trim()) {
+            put(i, "key", t("err_key_required"));
+        }
+        else {
+            if (k.length > keyMaxLength) {
+                put(i, "key", t("err_key_maxlength", { max: keyMaxLength }));
+            }
+            else if (!keyPattern.test(k)) {
+                put(i, "key", t("err_key_pattern"));
+            }
+            if ((keyCounts.get(k.trim()) ?? 0) > 1)
+                put(i, "key", t("err_key_duplicate"));
+            if (isKeyReserved(k, opts.reservedKeys))
+                put(i, "key", t("err_key_reserved"));
+        }
+        if (typeMap?.get(d.type)?.supportsOptions) {
+            const options = d.options ?? [];
+            const values = options.map((o) => (o.value ?? "").trim());
+            if (!options.length) {
+                put(i, "options", t("err_options_required"));
+            }
+            else if (values.some((v) => !v)) {
+                put(i, "options", t("err_option_value_required"));
+            }
+            else if (new Set(values).size !== values.length) {
+                put(i, "options", t("err_option_value_duplicate"));
+            }
+        }
+    });
+    let message = rowErrors.find(Boolean)
+        ? Object.values(rowErrors.find(Boolean))[0]
+        : "";
+    if (!message && opts.maxFields && defs.length > opts.maxFields) {
+        message = t("err_max_fields", { max: opts.maxFields });
+    }
+    return { valid: !message, message, rowErrors };
+}
+/**
+ * A small general-purpose palette — handy for demos and for consumers with no
+ * opinion. `types` is a required prop, so nobody gets this by accident.
+ */
+export const DEFAULT_FIELD_TYPES = [
+    { type: "text", label: "Text", description: "A single line of text" },
+    { type: "longtext", label: "Long text", description: "Multiple lines of text" },
+    { type: "number", label: "Number", description: "A numeric value" },
+    { type: "checkbox", label: "Yes / no", description: "A single on/off checkbox" },
+    {
+        type: "select",
+        label: "Choice",
+        description: "Pick one from a list of choices",
+        supportsOptions: true,
+    },
+    { type: "date", label: "Date", description: "A calendar date" },
+];

package/dist/index.css

@@ -80,6 +80,7 @@ In practice:
 @import "./components/DismissibleMessage/index.css";
 @import "./components/DropdownMenu/index.css";
 @import "./components/EmailVerifyForm/index.css";
+@import "./components/FieldsBuilder/index.css";
 @import "./components/Float/index.css";
 @import "./components/H/index.css";
 @import "./components/Header/index.css";

package/dist/index.d.ts

@@ -45,6 +45,7 @@ export * from "./components/DismissibleMessage/index.js";
 export * from "./components/Drawer/index.js";
 export * from "./components/DropdownMenu/index.js";
 export * from "./components/EmailVerifyForm/index.js";
+export * from "./components/FieldsBuilder/index.js";
 export * from "./components/Float/index.js";
 export * from "./components/H/index.js";
 export * from "./components/Header/index.js";

package/dist/index.js

@@ -51,6 +51,7 @@ export * from "./components/DismissibleMessage/index.js";
 export * from "./components/Drawer/index.js";
 export * from "./components/DropdownMenu/index.js";
 export * from "./components/EmailVerifyForm/index.js";
+export * from "./components/FieldsBuilder/index.js";
 export * from "./components/Float/index.js";
 export * from "./components/H/index.js";
 export * from "./components/Header/index.js";

package/docs/domains/components.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-63 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
+64 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
 
 ## Component Categories
 
@@ -62,6 +62,7 @@
 | CronInput                                     | Cron expression editor with presets and validation                          |
 | Fieldset                                      | Field grouping with legend                                                  |
 | FieldKeyValues                                | Key-value pair editor                                                       |
+| FieldsBuilder                                 | Field-definition list editor ("what properties does a thing have?")         |
 | FieldAssets                                   | File/asset management                                                       |
 | LoginForm, LoginFormModal                     | Standalone login form with optional modal variant                           |
 | RegisterForm                                  | Standalone registration form with declarative extra fields                  |
@@ -509,6 +510,65 @@ Exported from Input: `FieldObject`, `FieldObjectProps`.
 
 ---
 
+## FieldsBuilder
+
+Composite form control for authoring an ordered list of field definitions — the end
+user (typically non-technical) answers "what properties does a thing have?": add a
+field, name it, pick its type, mark it required, reorder, delete. The bindable `value`
+is a plain `FieldDef[]`; the type palette is a required prop (`types`), never a
+built-in union. Emits a field list, NOT JSON Schema — compiling (and re-validating)
+the list is the consumer's job, server-side. Own directory: `components/FieldsBuilder/`
+(composes `InputWrap`, exports the validate quintet).
+
+### Exports
+
+| Export                                                             | Kind      | Description                                                 |
+| ------------------------------------------------------------------ | --------- | ----------------------------------------------------------- |
+| `FieldsBuilder`                                                    | component | Main component                                              |
+| `FieldsBuilderProps`                                               | type      | Props type                                                  |
+| `FieldDef`                                                         | type      | One field definition (the value unit)                       |
+| `FieldLock`                                                        | type      | Per-field edit locks                                        |
+| `FieldOptionDef`                                                   | type      | Choice-type option `{ value, label }`                       |
+| `FieldTypeDef`                                                     | type      | Palette entry                                               |
+| `FieldTypeExtraDef`                                                | type      | Palette-declared boolean extra                              |
+| `LocalizedText`                                                    | type      | `string \| Record<language, string>`                        |
+| `FIELDS_BUILDER_DEFAULT_TYPES`                                     | constant  | Starter palette (text/longtext/number/checkbox/select/date) |
+| `FIELDS_BUILDER_DEFAULT_KEY_PATTERN`                               | constant  | `/^[a-z][a-z0-9_]{0,62}$/`                                  |
+| `getLocalizedText`, `slugifyKey`, `uniqueKey`, `validateFieldDefs` | functions | Pure helpers (node-testable)                                |
+
+### Key Props
+
+| Prop                 | Type                                           | Default  | Description                                      |
+| -------------------- | ---------------------------------------------- | -------- | ------------------------------------------------ |
+| `value`              | `FieldDef[]`                                   | required | Bindable ordered field list                      |
+| `name`               | `string`                                       | required | Hidden-input name                                |
+| `types`              | `FieldTypeDef[]`                               | required | The type palette                                 |
+| `languages`          | `string[]`                                     | —        | Multi-language labels/descriptions/options       |
+| `keysImmutable`      | `boolean`                                      | `true`   | Freeze keys loaded from `value`                  |
+| `deriveKeyFromLabel` | `boolean \| (label) => string`                 | `true`   | Live slug derivation (diacritics transliterated) |
+| `reservedKeys`       | `string[] \| (key) => boolean`                 | —        | Forbidden keys (derivation auto-avoids them)     |
+| `deleteMode`         | `"mark" \| "immediate"`                        | `"mark"` | Mark+undo vs outright removal                    |
+| `onBeforeDelete`     | `(field) => void \| false \| Promise`          | —        | Delete veto (Tree `onMove`-style)                |
+| `onBeforeTypeChange` | `(field, newType) => void \| false \| Promise` | —        | Type-change veto for pre-existing fields         |
+| `preview`            | `Snippet<[{ fields }]>`                        | —        | Live preview pane (side-by-side when wide)       |
+| `maxFields`          | `number`                                       | —        | Add-limit                                        |
+
+Features: collapsed rows (label + key + type chip) expanding to the full editor;
+drag reorder + Move up/down buttons with aria-live announcements; `lock.*` per-field
+locks (label/description always editable); unknown-type rows render degraded
+read-only and round-trip untouched; per-row inline validation with
+focus-first-offender `validate()`.
+
+### CSS Tokens
+
+Prefix: `--stuic-fields-builder-*`
+
+`row-border`, `row-toggle-bg-hover`, `key-text`, `chip-bg`, `chip-text`, `chip-radius`,
+`muted-text`, `warning-text`, `error-text`, `drop-indicator-color`,
+`drop-indicator-height`, `row-opacity-dragging`, `row-opacity-deleted`, `preview-border`
+
+---
+
 ## Checkout Components
 
 14 exported sub-components organized as atomic building blocks + composite step pages.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.153.0",
+	"version": "3.154.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",