@marianmeres/stuic 3.181.0 → 3.183.0

package/dist/components/FieldsBuilder/_internal/ExtrasEditor.svelte

@@ -0,0 +1,174 @@
+<!--
+	INTERNAL to FieldsBuilder — not exported from the package.
+
+	The controls of one `extras` bag (`Record<string, unknown>`), one per
+	declared `FieldTypeExtraDef` (boolean / string / select). Rendered by a
+	field row for the palette entry's extras and by a column line for the
+	column type's extras — the same bag rule applies to both.
+
+	Every arm displays the ACTUAL bag value only (no `?? ex.default` fallback):
+	defaults are materialized into the bag on add / type change, but a def
+	loaded without the key must not render as if it held the default while
+	emitting nothing — the control must always match what `value` says.
+
+	"Empty means absent": `undefined` REMOVES the key, and an emptied bag
+	removes `extras` itself — "no value" must have exactly one representation
+	downstream. A consumer reading `extras.unit` to decide whether to render a
+	suffix should never have to special-case `""`, nor a `{}` that means
+	nothing.
+-->
+<script lang="ts">
+	import { twMerge } from "../../../utils/tw-merge.js";
+	import type { FieldTypeExtraDef, LocalizedText } from "../types.js";
+	import { getLocalizedText } from "../utils.js";
+
+	interface Props {
+		extras?: Record<string, unknown>;
+		/** The declarations (the palette entry's `extras`). */
+		defs: FieldTypeExtraDef[];
+		/** Display fallback chain for the declarations' labels / placeholders. */
+		displayLanguages?: string[];
+		/** Unique prefix for the control ids (label association). */
+		idPrefix: string;
+		disabled?: boolean;
+		tabindex?: number;
+		/** Rendered below the controls; also marks the string inputs invalid. */
+		error?: string;
+		class?: string;
+		/** Fired after any change to `extras`. */
+		onChange?: () => void;
+	}
+
+	let {
+		// no fallback on purpose — the parent binds a possibly-undefined bag
+		extras = $bindable(),
+		defs,
+		displayLanguages,
+		idPrefix,
+		disabled = false,
+		tabindex = 0,
+		error,
+		class: classProp,
+		onChange,
+	}: Props = $props();
+
+	const errId = $derived(`${idPrefix}-extras-err`);
+
+	function displayText(text: LocalizedText | null | undefined): string {
+		return getLocalizedText(text, displayLanguages);
+	}
+
+	function setExtra(key: string, value: unknown) {
+		const next = { ...(extras ?? {}) };
+		if (value === undefined) delete next[key];
+		else next[key] = value;
+		extras = Object.keys(next).length ? next : undefined;
+		onChange?.();
+	}
+
+	/** Display value of a string/select extra (a non-string is shown, not eaten). */
+	function extraText(key: string): string {
+		const v = extras?.[key];
+		return v == null ? "" : String(v);
+	}
+
+	// while typing, the RAW value is stored (trimming here would fight the
+	// caret: a written-back trimmed value makes a trailing space untypable) —
+	// only the emptiness test is trimmed; `onchange` normalizes on commit
+	function onStringInput(key: string, raw: string) {
+		setExtra(key, raw.trim() ? raw : undefined);
+	}
+
+	function onStringChange(key: string, raw: string) {
+		setExtra(key, raw.trim() || undefined);
+	}
+
+	const INPUT_CLS = [
+		"rounded bg-(--stuic-color-input)",
+		"border border-(--stuic-color-border)",
+		"focus:border-(--stuic-color-border-hover)",
+		"focus:outline-none focus:ring-0",
+		"focus-visible:outline-none focus-visible:ring-0",
+	].join(" ");
+</script>
+
+<div class={twMerge("fb-extras fb-field flex flex-col gap-2.5", classProp)}>
+	{#each defs as ex, exIdx (ex.key)}
+		{#if ex.type === "string" || ex.type === "select"}
+			{@const exId = `${idPrefix}-extra-${exIdx}`}
+			{@const exValue = extraText(ex.key)}
+			<div class="fb-extra">
+				<label class="fb-sub-label" for={exId}>
+					{displayText(ex.label)}
+				</label>
+				{#if ex.type === "string"}
+					<input
+						id={exId}
+						type="text"
+						class={twMerge(INPUT_CLS, "fb-extra-input w-full")}
+						value={exValue}
+						maxlength={ex.maxlength}
+						placeholder={displayText(ex.placeholder) || undefined}
+						oninput={(e) => onStringInput(ex.key, e.currentTarget.value)}
+						onchange={(e) => onStringChange(ex.key, e.currentTarget.value)}
+						{disabled}
+						{tabindex}
+						aria-invalid={!!error || undefined}
+						aria-describedby={error ? errId : undefined}
+					/>
+				{:else}
+					<select
+						id={exId}
+						class={twMerge(INPUT_CLS, "fb-extra-input w-full")}
+						value={exValue}
+						onchange={(e) => setExtra(ex.key, e.currentTarget.value || undefined)}
+						{disabled}
+						{tabindex}
+					>
+						<option value="">
+							{displayText(ex.placeholder)}
+						</option>
+						{#each ex.options as opt (opt.value)}
+							<option value={opt.value}>
+								{displayText(opt.label)}
+							</option>
+						{/each}
+						<!-- a stored value outside the declared list stays visible and
+						     round-trips (same stance as an unknown field type) -->
+						{#if exValue && !ex.options.some((o) => o.value === exValue)}
+							<option value={exValue}>{exValue}</option>
+						{/if}
+					</select>
+				{/if}
+				{#if ex.description}
+					<div class="fb-hint text-xs mt-0.5">
+						{displayText(ex.description)}
+					</div>
+				{/if}
+			</div>
+		{:else}
+			<label class="stuic-checkbox fb-extra flex items-start gap-2 cursor-pointer">
+				<input
+					type="checkbox"
+					checked={!!extras?.[ex.key]}
+					onchange={(e) => setExtra(ex.key, e.currentTarget.checked)}
+					{disabled}
+					{tabindex}
+				/>
+				<span class="text-sm">
+					{displayText(ex.label)}
+					{#if ex.description}
+						<span class="fb-hint block text-xs">
+							{displayText(ex.description)}
+						</span>
+					{/if}
+				</span>
+			</label>
+		{/if}
+	{/each}
+	{#if error}
+		<div id={errId} class="fb-error-text text-sm">
+			{error}
+		</div>
+	{/if}
+</div>

package/dist/components/FieldsBuilder/_internal/ExtrasEditor.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { FieldTypeExtraDef } from "../types.js";
+interface Props {
+    extras?: Record<string, unknown>;
+    /** The declarations (the palette entry's `extras`). */
+    defs: FieldTypeExtraDef[];
+    /** Display fallback chain for the declarations' labels / placeholders. */
+    displayLanguages?: string[];
+    /** Unique prefix for the control ids (label association). */
+    idPrefix: string;
+    disabled?: boolean;
+    tabindex?: number;
+    /** Rendered below the controls; also marks the string inputs invalid. */
+    error?: string;
+    class?: string;
+    /** Fired after any change to `extras`. */
+    onChange?: () => void;
+}
+declare const ExtrasEditor: import("svelte").Component<Props, {}, "extras">;
+type ExtrasEditor = ReturnType<typeof ExtrasEditor>;
+export default ExtrasEditor;

package/dist/components/FieldsBuilder/_internal/column-meta.d.ts

@@ -0,0 +1,27 @@
+import type { FieldColumnDef } from "../types.js";
+/**
+ * INTERNAL to FieldsBuilder — not exported from the package.
+ *
+ * Per-column editing state, index-aligned with `FieldDef.columns` and kept in
+ * lockstep by `ColumnsEditor`. It lives on the parent's `Row` (not inside the
+ * editor) on purpose: the row body — and so the editor — is unmounted while a
+ * row is collapsed, and a mount-time snapshot would freeze the key of a column
+ * added this session, and lose the stored/new distinction the veto hooks
+ * depend on, the moment the user collapsed and re-expanded the row.
+ */
+export interface ColumnMeta {
+    /** Stable render id (columns have no identity of their own). */
+    cid: string;
+    /** Key at (re)load time; `undefined` = column added this session. */
+    initialKey?: string;
+    /** Type at (re)load time (drives the warning and the veto). */
+    initialType?: string;
+    /** Key derivation from the label stops once true. Loaded columns: true. */
+    keyTouched: boolean;
+    /** The options / extras sub-block is open. */
+    expanded: boolean;
+}
+/** Meta of a column present in `value` at (re)load time. */
+export declare function loadedColumnMeta(column: FieldColumnDef): ColumnMeta;
+/** Meta of a column added in this editing session. */
+export declare function newColumnMeta(expanded?: boolean): ColumnMeta;

package/dist/components/FieldsBuilder/_internal/column-meta.js

@@ -0,0 +1,15 @@
+import { getId } from "../../../utils/get-id.js";
+/** Meta of a column present in `value` at (re)load time. */
+export function loadedColumnMeta(column) {
+    return {
+        cid: getId(),
+        initialKey: column.key || undefined,
+        initialType: column.type || undefined,
+        keyTouched: true,
+        expanded: false,
+    };
+}
+/** Meta of a column added in this editing session. */
+export function newColumnMeta(expanded = false) {
+    return { cid: getId(), keyTouched: false, expanded };
+}

package/dist/components/FieldsBuilder/i18n-sk.js

@@ -41,6 +41,19 @@ export const FIELDS_BUILDER_MESSAGES_SK = {
     option_value_hint: "Uložená strojová hodnota tejto možnosti",
     remove_option: "Odstrániť možnosť",
     removed_option: "Odstránená možnosť: {{label}}",
+    columns_label: "Stĺpce",
+    add_column: "Pridať stĺpec",
+    empty_columns_message: "Nie sú definované žiadne stĺpce",
+    untitled_column: "Nepomenovaný stĺpec",
+    column_label_placeholder: "Názov stĺpca",
+    column_key_placeholder: "kľúč",
+    column_key_hint: "Uložený strojový kľúč tohto stĺpca",
+    column_type_label: "Typ stĺpca",
+    column_settings: "Nastavenia stĺpca",
+    remove_column: "Odstrániť stĺpec",
+    removed_column: "Odstránený stĺpec: {{label}}",
+    column_type_change_warning: "Zmena typu existujúceho stĺpca nemusí sedieť s hodnotami, ktoré sú v jeho bunkách už uložené.",
+    unknown_column_type_warning: "Tento stĺpec má typ, ktorý tento editor nepozná. Zostáva nezmenený a nedá sa tu upravovať.",
     advanced_label: "Rozšírené",
     key_label: "Kľúč",
     key_hint: "Jedinečný strojový identifikátor tohto poľa. Vypĺňa sa automaticky z názvu.",
@@ -61,6 +74,10 @@ export const FIELDS_BUILDER_MESSAGES_SK = {
     err_option_value_duplicate: "Hodnoty možností musia byť jedinečné",
     err_extra_maxlength: "{{label}} — hodnota je príliš dlhá (max. {{max}} znakov)",
     err_max_fields: "Maximálny počet polí je {{max}}",
+    err_columns_required: "Pridajte aspoň jeden stĺpec",
+    err_max_columns: "Maximálny počet stĺpcov je {{max}}",
+    err_column: "Stĺpec {{position}}: {{message}}",
+    err_column_key_duplicate: "Tento kľúč už používa iný stĺpec",
 };
 /**
  * Slovak counterpart of `FIELDS_BUILDER_DEFAULT_TYPES` — the `types` palette is

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

@@ -35,6 +35,19 @@ export declare const FIELDS_BUILDER_MESSAGES_EN: {
     option_value_hint: string;
     remove_option: string;
     removed_option: string;
+    columns_label: string;
+    add_column: string;
+    empty_columns_message: string;
+    untitled_column: string;
+    column_label_placeholder: string;
+    column_key_placeholder: string;
+    column_key_hint: string;
+    column_type_label: string;
+    column_settings: string;
+    remove_column: string;
+    removed_column: string;
+    column_type_change_warning: string;
+    unknown_column_type_warning: string;
     advanced_label: string;
     key_label: string;
     key_hint: string;
@@ -55,6 +68,10 @@ export declare const FIELDS_BUILDER_MESSAGES_EN: {
     err_option_value_duplicate: string;
     err_extra_maxlength: string;
     err_max_fields: string;
+    err_columns_required: string;
+    err_max_columns: string;
+    err_column: string;
+    err_column_key_duplicate: string;
 };
 /** Every message key `FieldsBuilder` (and its internals) may look up. */
 export type FieldsBuilderMessageKey = keyof typeof FIELDS_BUILDER_MESSAGES_EN;

package/dist/components/FieldsBuilder/i18n.js

@@ -36,6 +36,19 @@ export const FIELDS_BUILDER_MESSAGES_EN = {
     option_value_hint: "Stored machine value of this choice",
     remove_option: "Remove choice",
     removed_option: "Removed choice: {{label}}",
+    columns_label: "Columns",
+    add_column: "Add column",
+    empty_columns_message: "No columns defined",
+    untitled_column: "Untitled column",
+    column_label_placeholder: "Column name",
+    column_key_placeholder: "key",
+    column_key_hint: "Stored machine key of this column",
+    column_type_label: "Column type",
+    column_settings: "Column settings",
+    remove_column: "Remove column",
+    removed_column: "Removed column: {{label}}",
+    column_type_change_warning: "Changing the type of an existing column may not fit values already stored in its cells.",
+    unknown_column_type_warning: "This column has a type this editor does not recognize. It is kept unchanged and cannot be edited here.",
     advanced_label: "Advanced",
     key_label: "Key",
     key_hint: "Unique machine identifier of this field. Filled in automatically from the label.",
@@ -56,6 +69,10 @@ export const FIELDS_BUILDER_MESSAGES_EN = {
     err_option_value_duplicate: "Choice values must be unique",
     err_extra_maxlength: "{{label}} is too long (max {{max}} characters)",
     err_max_fields: "Maximum number of fields is {{max}}",
+    err_columns_required: "Add at least one column",
+    err_max_columns: "Maximum number of columns is {{max}}",
+    err_column: "Column {{position}}: {{message}}",
+    err_column_key_duplicate: "This key is already used by another column",
 };
 /**
  * Builds the `t` prop of `FieldsBuilder` from a message catalog. Unknown or

package/dist/components/FieldsBuilder/index.css

@@ -167,6 +167,26 @@
 		border-top: 1px dashed var(--stuic-fields-builder-row-border);
 	}
 
+	/* =============================================================================
+	   COLUMNS EDITOR (`supportsColumns` types)
+	   ============================================================================= */
+
+	.stuic-fields-builder .fb-column-divider {
+		border-top: 1px dashed var(--stuic-fields-builder-row-border);
+	}
+
+	/* the per-column options / extras sub-block sits under its line, indented
+	   past the move buttons and marked by a thin left rule */
+	.stuic-fields-builder .fb-column-settings {
+		margin-left: calc(var(--spacing) * 5);
+		padding-left: calc(var(--spacing) * 2);
+		border-left: 2px solid var(--stuic-fields-builder-row-border);
+	}
+
+	.stuic-fields-builder .fb-column-settings .fb-sub-label {
+		margin-top: calc(var(--spacing) * 0.5);
+	}
+
 	/* =============================================================================
 	   PREVIEW PANE
 	   ============================================================================= */

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

@@ -1,5 +1,5 @@
 export { default as FieldsBuilder, type Props as FieldsBuilderProps, } from "./FieldsBuilder.svelte";
-export type { FieldDef, FieldLock, FieldOptionDef, FieldTypeDef, FieldTypeExtraBaseDef, FieldTypeExtraBooleanDef, FieldTypeExtraDef, FieldTypeExtraSelectDef, FieldTypeExtraStringDef, 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 type { FieldColumnDef, FieldDef, FieldLock, FieldOptionDef, FieldTypeDef, FieldTypeExtraBaseDef, FieldTypeExtraBooleanDef, FieldTypeExtraDef, FieldTypeExtraSelectDef, FieldTypeExtraStringDef, 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 FieldColumnErrors, 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/types.d.ts

@@ -12,12 +12,31 @@ export interface FieldOptionDef {
     value: string;
     label: LocalizedText;
 }
+/**
+ * One column of a field whose palette entry declares `supportsColumns` — a
+ * field in miniature: key, type, label, and the column type's options /
+ * extras. There is deliberately no per-column description, required flag or
+ * lock (each is additive later without changing the existing members).
+ */
+export interface FieldColumnDef {
+    /** Machine key. Unique within the field's columns (not across fields). */
+    key: string;
+    /** One of the entry's column palette types (`columnTypes`). */
+    type: string;
+    label: LocalizedText;
+    /** Edited for column types declaring `supportsOptions`. Kept when the type changes. */
+    options?: FieldOptionDef[];
+    /** Per column-type extras, driven by that column type's `extras`. Kept when the type changes. */
+    extras?: Record<string, unknown>;
+}
 /** What the user may NOT change on a field. Absent flag = editable. */
 export interface FieldLock {
     key?: boolean;
     type?: boolean;
     required?: boolean;
     options?: boolean;
+    /** Render the column list read-only (the counterpart of `options`). */
+    columns?: boolean;
     /** Cannot be removed from the list. */
     delete?: boolean;
     /** Cannot be dragged, and other fields cannot be moved past it. */
@@ -51,6 +70,14 @@ export interface FieldDef {
      * extras of a previous type are RETAINED when the type changes.
      */
     extras?: Record<string, unknown>;
+    /**
+     * Edited and validated only for palette entries declaring
+     * `supportsColumns`. Like `options`, RETAINED on the def when the field's
+     * type changes away (never silently drop data; switching back restores
+     * them) — consumers compiling the list should ignore `columns` on types
+     * without `supportsColumns`.
+     */
+    columns?: FieldColumnDef[];
     /** What the user may NOT change. Absent = fully editable. */
     lock?: FieldLock;
 }
@@ -112,6 +139,18 @@ export interface FieldTypeDef {
     supportsOptions?: boolean;
     /** Extra per-field controls, rendered into `FieldDef.extras[key]`. */
     extras?: FieldTypeExtraDef[];
+    /** Renders the column editor and allows `FieldDef.columns`. */
+    supportsColumns?: boolean;
+    /**
+     * The palette a column may take. Default: the component's `types` without
+     * the entries that `supportsColumns` themselves. Columns do not nest: the
+     * column editor ignores `supportsColumns` on any entry listed here. A
+     * column palette entry's `supportsOptions` / `extras` work exactly as they
+     * do per field — so leave off the extras that only make sense per field.
+     */
+    columnTypes?: FieldTypeDef[];
+    /** Most columns one field of this type may declare. */
+    maxColumns?: number;
     /** Optional live preview of a single field of this type. */
     preview?: Snippet<[FieldDef]>;
 }

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

@@ -25,12 +25,30 @@ export declare function slugifyKey(input: string, maxLength?: number): string;
  */
 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;
+/** Errors of one column of a `supportsColumns` field. */
+export interface FieldColumnErrors {
+    label?: string;
+    key?: string;
+    options?: string;
+    /** First offending extra of the column (its label is in the message). */
+    extras?: string;
+}
 export interface FieldDefRowErrors {
     label?: string;
     key?: string;
     options?: string;
+    /**
+     * The column-list summary: no columns / over `maxColumns`, else the first
+     * column-level message already prefixed with its position ("Column 2: …").
+     */
+    columns?: string;
     /** First offending extra of the row (its label is in the message). */
     extras?: string;
+    /**
+     * Index-aligned with `def.columns`; `null` = that column has no errors.
+     * Present only when at least one column has an error.
+     */
+    columnErrors?: (FieldColumnErrors | null)[];
 }
 export interface FieldDefsValidationResult {
     valid: boolean;
@@ -39,6 +57,20 @@ export interface FieldDefsValidationResult {
     /** Index-aligned with the input defs. `null` = row has no errors. */
     rowErrors: (FieldDefRowErrors | null)[];
 }
+/** The slice of a palette entry `validateFieldDefs` reads. */
+export type ValidateFieldDefsTypeDef = Pick<FieldTypeDef, "type" | "supportsOptions" | "extras" | "supportsColumns" | "columnTypes" | "maxColumns">;
+/**
+ * The palette a column of `entry` may take: its own `columnTypes`, else the
+ * component's `types` without every entry that `supportsColumns` itself
+ * (columns never nest).
+ */
+export declare function resolveColumnTypes<T extends Pick<FieldTypeDef, "supportsColumns">>(entry: Pick<FieldTypeDef, "columnTypes">, types: T[] | null | undefined): (T | FieldTypeDef)[];
+/**
+ * Materialize the `default` of every declared extra that the bag does not
+ * hold yet. Returns the same bag when nothing was seeded (so `undefined`
+ * stays `undefined` for a type without defaults).
+ */
+export declare function seedExtraDefaults(extras: Record<string, unknown> | undefined, entry: Pick<FieldTypeDef, "extras"> | undefined): Record<string, unknown> | undefined;
 export interface ValidateFieldDefsOptions {
     /**
      * The type palette. When provided, defs with a `type` not present here are
@@ -46,7 +78,7 @@ export interface ValidateFieldDefsOptions {
      * must never block the rest of the list), but their keys still count toward
      * uniqueness.
      */
-    types?: Pick<FieldTypeDef, "type" | "supportsOptions" | "extras">[];
+    types?: ValidateFieldDefsTypeDef[];
     keyPattern?: RegExp;
     keyMaxLength?: number;
     reservedKeys?: string[] | ((key: string) => boolean);
@@ -66,6 +98,9 @@ export interface ValidateFieldDefsOptions {
  * 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, string extras within `maxlength`, `maxFields` not exceeded.
+ * A `supportsColumns` type additionally needs at least one column, at most
+ * `maxColumns`, and every column (of a known column type) passes the label /
+ * key (unique within the field) / options / extras rules above.
  *
  * This is client-side convenience only — a consumer persisting the list MUST
  * re-validate server-side; this function is not a security boundary.