@marianmeres/stuic 3.178.0 → 3.180.0

package/dist/components/ContactUsForm/ContactUsForm.svelte

@@ -60,6 +60,29 @@
 		/** Minimum message length. 0 (default) disables the check. */
 		messageMinLength?: number;
 
+		/**
+		 * Names of fields rendered **read-only**: the value is visible and still
+		 * reaches `onSubmit`, but the user cannot change it. The typical case is a
+		 * signed-in visitor whose name/email the server already knows — prefill
+		 * them through `formData` and list them here.
+		 *
+		 * Accepts the built-in names (`"name"`, `"email"`, `"phone"`, `"subject"`,
+		 * `"company"`, `"message"`) and any `extraFields` name. Unknown names are
+		 * ignored. Listing a field does NOT show it — pair with the matching
+		 * `show*` toggle.
+		 *
+		 * Read-only is not the same as `disabled`: the value keeps full contrast
+		 * and stays focusable/selectable/copyable. A read-only Subject rendered
+		 * from `subjectValues` falls back to a read-only text input, because
+		 * `<select>` has no read-only counterpart.
+		 *
+		 * Prefill whatever you lock: a read-only control is barred from *native*
+		 * constraint validation, so an empty required one is a dead end for the
+		 * user. The form still reports it (see `validateContactForm`), it just
+		 * cannot be fixed in the UI.
+		 */
+		readonlyFields?: string[];
+
 		/**
 		 * Declarative extra fields rendered as FieldInput entries.
 		 * Values bind into `formData.extra[name]`.
@@ -153,6 +176,7 @@
 		showCompany = false,
 		requireCompany = false,
 		messageMinLength = 0,
+		readonlyFields,
 		extraFields = [],
 		extraFieldsSlot,
 		useHoneypot = true,
@@ -184,12 +208,24 @@
 	let topFields = $derived(extraFields.filter((f) => f.position === "top"));
 	let bottomFields = $derived(extraFields.filter((f) => f.position !== "top"));
 
+	let readonlySet = $derived(new Set(readonlyFields ?? []));
+	function isReadonly(field: string): boolean {
+		return readonlySet.has(field);
+	}
+
 	// Subject: render a <select> when subjectValues is non-empty (which also shows
 	// the field regardless of showSubject); otherwise a free-text input gated by
 	// showSubject. The select gets a prepended blank "prompt" option so the initial
 	// empty subject isn't silently auto-selected to the first real value.
-	let subjectAsSelect = $derived((subjectValues?.length ?? 0) > 0);
-	let subjectShown = $derived(showSubject || subjectAsSelect);
+	//
+	// A read-only subject downgrades to a read-only text input — <select> has no
+	// readonly counterpart, and `disabled` would grey out the very value we mean
+	// to show. Hence `subjectShown` keys off *having* values rather than off
+	// rendering a select: sharing one flag would have made `subjectValues` +
+	// readonly hide the field outright.
+	let subjectHasValues = $derived((subjectValues?.length ?? 0) > 0);
+	let subjectAsSelect = $derived(subjectHasValues && !isReadonly("subject"));
+	let subjectShown = $derived(showSubject || subjectHasValues);
 	let subjectOptions = $derived([
 		{ label: t("contact_form.subject_select_prompt"), value: "" },
 		...(subjectValues ?? []).map((v) => ({ label: v, value: v })),
@@ -280,6 +316,21 @@
 		},
 	});
 
+	// Single source for `validateContactForm`'s options — the submit path and
+	// `readonlyMissing()` below must agree on which fields are shown/required.
+	let validationOptions = $derived({
+		showName,
+		requireName,
+		showPhone,
+		requirePhone,
+		showSubject: subjectShown,
+		requireSubject,
+		showCompany,
+		requireCompany,
+		messageMinLength,
+		extraFields,
+	});
+
 	// Merge internal + external errors; external takes precedence per field.
 	let allErrors = $derived.by(() => {
 		const map = new Map<string, string>();
@@ -289,7 +340,22 @@
 	});
 
 	function fieldError(field: string): string | undefined {
-		return allErrors.find((e) => e.field === field)?.message;
+		return allErrors.find((e) => e.field === field)?.message ?? readonlyMissing(field);
+	}
+
+	// A read-only control is barred from *native* constraint validation:
+	// `validity.valueMissing` stays false however empty it is (the spec requires
+	// the control to be "mutable"). Without this the field walk behind the
+	// exported `validate()` would green-light an empty read-only required field,
+	// and the consumer would post it. Run the form's own validator for that one
+	// field instead — same rules, same messages, no duplicated logic. The
+	// built-in submit path reaches `validateContactForm` anyway; this only
+	// closes the pre-submit / imperative window, and only for read-only fields.
+	function readonlyMissing(field: string): string | undefined {
+		if (!readonlySet.size || !isReadonly(field)) return;
+		return validateContactForm(formData, t, validationOptions).find(
+			(e) => e.field === field
+		)?.message;
 	}
 
 	function extraValue(cfg: ContactFieldConfig): string {
@@ -321,18 +387,7 @@
 	}
 
 	function handleSubmitValid() {
-		const validationErrors = validateContactForm(formData, t, {
-			showName,
-			requireName,
-			showPhone,
-			requirePhone,
-			showSubject: subjectShown,
-			requireSubject,
-			showCompany,
-			requireCompany,
-			messageMinLength,
-			extraFields,
-		});
+		const validationErrors = validateContactForm(formData, t, validationOptions);
 		internalErrors = validationErrors;
 
 		// Report-only on bot signals: we still submit when field validation passes
@@ -452,6 +507,7 @@
 			placeholder={cfg.placeholder}
 			autocomplete={cfg.autocomplete}
 			required={cfg.required}
+			readonly={isReadonly(cfg.name)}
 			name={`contact-extra-${cfg.name}`}
 			labelLeftBreakpoint={0}
 			validate={{
@@ -481,6 +537,7 @@
 			placeholder={t("contact_form.name_placeholder")}
 			autocomplete="name"
 			required={requireName}
+			readonly={isReadonly("name")}
 			name="contact-name"
 			labelLeftBreakpoint={0}
 			validate={{
@@ -501,6 +558,7 @@
 		placeholder={t("contact_form.email_placeholder")}
 		autocomplete="email"
 		required
+		readonly={isReadonly("email")}
 		name="contact-email"
 		labelLeftBreakpoint={0}
 		validate={{
@@ -521,6 +579,7 @@
 			placeholder={t("contact_form.phone_placeholder")}
 			autocomplete="tel"
 			required={requirePhone}
+			readonly={isReadonly("phone")}
 			name="contact-phone"
 			labelLeftBreakpoint={0}
 			validate={{
@@ -542,6 +601,7 @@
 			placeholder={t("contact_form.company_placeholder")}
 			autocomplete="organization"
 			required={requireCompany}
+			readonly={isReadonly("company")}
 			name="contact-company"
 			labelLeftBreakpoint={0}
 			validate={{
@@ -579,6 +639,7 @@
 				type="text"
 				placeholder={t("contact_form.subject_placeholder")}
 				required={requireSubject}
+				readonly={isReadonly("subject")}
 				name="contact-subject"
 				labelLeftBreakpoint={0}
 				validate={{
@@ -598,6 +659,7 @@
 		label={t("contact_form.message_label")}
 		placeholder={t("contact_form.message_placeholder")}
 		required
+		readonly={isReadonly("message")}
 		name="contact-message"
 		labelLeftBreakpoint={0}
 		validate={{
@@ -619,6 +681,7 @@
 			placeholder={cfg.placeholder}
 			autocomplete={cfg.autocomplete}
 			required={cfg.required}
+			readonly={isReadonly(cfg.name)}
 			name={`contact-extra-${cfg.name}`}
 			labelLeftBreakpoint={0}
 			validate={{

package/dist/components/ContactUsForm/ContactUsForm.svelte.d.ts

@@ -47,6 +47,28 @@ export interface Props extends Omit<HTMLAttributes<HTMLFormElement>, "children">
     requireCompany?: boolean;
     /** Minimum message length. 0 (default) disables the check. */
     messageMinLength?: number;
+    /**
+     * Names of fields rendered **read-only**: the value is visible and still
+     * reaches `onSubmit`, but the user cannot change it. The typical case is a
+     * signed-in visitor whose name/email the server already knows — prefill
+     * them through `formData` and list them here.
+     *
+     * Accepts the built-in names (`"name"`, `"email"`, `"phone"`, `"subject"`,
+     * `"company"`, `"message"`) and any `extraFields` name. Unknown names are
+     * ignored. Listing a field does NOT show it — pair with the matching
+     * `show*` toggle.
+     *
+     * Read-only is not the same as `disabled`: the value keeps full contrast
+     * and stays focusable/selectable/copyable. A read-only Subject rendered
+     * from `subjectValues` falls back to a read-only text input, because
+     * `<select>` has no read-only counterpart.
+     *
+     * Prefill whatever you lock: a read-only control is barred from *native*
+     * constraint validation, so an empty required one is a dead end for the
+     * user. The form still reports it (see `validateContactForm`), it just
+     * cannot be fixed in the UI.
+     */
+    readonlyFields?: string[];
     /**
      * Declarative extra fields rendered as FieldInput entries.
      * Values bind into `formData.extra[name]`.

package/dist/components/ContactUsForm/README.md

@@ -75,6 +75,7 @@ interface ContactFieldConfig {
 | `showCompany`        | `boolean`                                                    | `false`  | Render the Company field.                                                                                           |
 | `requireCompany`     | `boolean`                                                    | `false`  | Require Company (only applies when shown).                                                                          |
 | `messageMinLength`   | `number`                                                     | `0`      | Minimum message length. `0` disables the check.                                                                     |
+| `readonlyFields`     | `string[]`                                                   | -        | Field names rendered read-only — prefilled, visible, submitted, not editable (see below).                           |
 | `extraFields`        | `ContactFieldConfig[]`                                       | `[]`     | Declarative extra fields, positioned top or bottom.                                                                 |
 | `extraFieldsSlot`    | `Snippet<[{ formData, fieldError }]>`                        | -        | Escape hatch for non-FieldInput extras (consent checkbox, captcha widget).                                          |
 | `useHoneypot`        | `boolean`                                                    | `true`   | Render the hidden honeypot trap.                                                                                    |
@@ -182,6 +183,54 @@ automatically; the bound value is still the chosen string in `formData.subject`)
 </ContactUsForm>
 ```
 
+### Prefilled, read-only fields (signed-in visitor)
+
+When the server already knows who is writing, prefill `formData` and list those
+field names in `readonlyFields`. The values stay visible, keep full contrast, are
+selectable/copyable, and still reach `onSubmit` — the user simply cannot change
+them.
+
+```svelte
+<script lang="ts">
+	import { ContactUsForm, createEmptyContactFormData } from "@marianmeres/stuic";
+
+	let { user } = $props();
+
+	let formData = $state({
+		...createEmptyContactFormData(),
+		name: user.name,
+		email: user.email,
+	});
+</script>
+
+<ContactUsForm
+	bind:formData
+	onSubmit={send}
+	showName
+	readonlyFields={["name", "email"]}
+/>
+```
+
+Notes:
+
+- `readonlyFields` does **not** show a field — pair it with the matching `show*` toggle.
+- It accepts the built-in names (`name`, `email`, `phone`, `subject`, `company`,
+  `message`) and any `extraFields` name. Unknown names are ignored.
+- Read-only is **not** `disabled`. `disabled` reads as "unavailable", greys the
+  value out and drops it from the tab order; read-only says "this is your value,
+  it just isn't yours to change here".
+- A read-only Subject falls back to a read-only **text input** even when
+  `subjectValues` is set, because `<select>` has no read-only counterpart and
+  disabling it would grey out the very value you meant to show.
+- **Prefill whatever you lock.** A read-only control is barred from _native_
+  constraint validation, so an empty required one is a dead end for the user.
+  The form still reports it (`validateContactForm` runs on submit, and
+  `validate()` covers the same ground for read-only fields), but nobody can fix
+  it from the UI.
+- Read-only is a **UI** affordance, not a security boundary: anything the browser
+  holds can be edited from devtools. Re-derive the trusted values server-side
+  from the session instead of trusting the posted ones.
+
 ### Declarative extra field
 
 ```svelte

package/dist/components/FieldsBuilder/FieldsBuilder.svelte

@@ -7,7 +7,7 @@
 	import type { TranslateFn } from "../../types.js";
 	import type { THC } from "../Thc/Thc.svelte";
 	import type { InputWrapClassProps } from "../Input/types.js";
-	import type { FieldDef, FieldTypeDef } from "./types.js";
+	import type { FieldDef, FieldTypeDef, LocalizedText } from "./types.js";
 
 	type SnippetWithId = Snippet<[{ id: string }]>;
 
@@ -46,8 +46,22 @@
 		 * strings.
 		 */
 		languages?: string[];
-		/** Defaults to `languages[0]`. Drives key derivation and display texts. */
+		/**
+		 * The canonical (authoring) language. Defaults to `languages[0]`. Drives
+		 * key derivation, the "label required" rule and which input the label/
+		 * description/option editors show collapsed. Also the display language
+		 * unless `displayLanguage` is set.
+		 */
 		defaultLanguage?: string;
+		/**
+		 * Which translation of consumer-supplied localized data is DISPLAYED —
+		 * field labels in the row list, announcements and the preview fallback;
+		 * palette labels/descriptions; extras labels/placeholders/descriptions.
+		 * Typically the current user's UI locale. Purely presentational: authoring
+		 * stays on `defaultLanguage` (see above), which is also the fallback for a
+		 * missing translation. Default: `defaultLanguage`.
+		 */
+		displayLanguage?: string;
 		languageLabels?: Record<string, string>;
 		/** Key policy. Default: lowercase snake_case starting with a letter. */
 		keyPattern?: RegExp;
@@ -165,6 +179,7 @@
 		style,
 		languages,
 		defaultLanguage,
+		displayLanguage,
 		languageLabels,
 		keyPattern,
 		keyMaxLength = DEFAULT_KEY_MAX_LENGTH,
@@ -244,6 +259,17 @@
 	let rows: Row[] = $state(fromValue(value ?? []));
 
 	const _defaultLanguage = $derived(defaultLanguage || languages?.[0]);
+	const _displayLanguage = $derived(displayLanguage || _defaultLanguage);
+	// display fallback chain: preferred → canonical → first non-empty entry
+	const _displayLanguages = $derived(
+		[_displayLanguage, _defaultLanguage].filter((l): l is string => !!l)
+	);
+
+	/** Read-only rendering of consumer-supplied localized data. */
+	function displayText(text: LocalizedText | null | undefined): string {
+		return getLocalizedText(text, _displayLanguages);
+	}
+
 	const typeByName = $derived(new Map(types.map((td) => [td.type, td])));
 	const visibleRows = $derived(rows.filter((r) => !r.deleted));
 	const maxReached = $derived(!!maxFields && visibleRows.length >= maxFields);
@@ -569,7 +595,7 @@
 	}
 
 	function rowLabel(row: Row): string {
-		return getLocalizedText(row.def.label, _defaultLanguage) || String(t("untitled"));
+		return displayText(row.def.label) || String(t("untitled"));
 	}
 
 	// clear-then-set so REPEATED identical announcements (e.g. pressing "Move
@@ -597,6 +623,7 @@
 				reservedKeys,
 				maxFields,
 				defaultLanguage: _defaultLanguage,
+				displayLanguage: _displayLanguage,
 				t: tUtils,
 			}
 		)
@@ -831,7 +858,7 @@
 												{:else if entry.icon}
 													{@render entry.icon()}
 												{/if}
-												{getLocalizedText(entry.label, _defaultLanguage)}
+												{displayText(entry.label)}
 											</span>
 										{/if}
 										{#if (showLabelError || showKeyError || showOptionsError || showExtrasError) && !row.deleted}
@@ -994,7 +1021,7 @@
 													>
 														{#each types as td (td.type)}
 															<option value={td.type}>
-																{getLocalizedText(td.label, _defaultLanguage)}
+																{displayText(td.label)}
 															</option>
 														{/each}
 													</select>
@@ -1016,7 +1043,7 @@
 												</div>
 												{#if entry.description}
 													<div class="fb-hint text-xs mt-0.5">
-														{getLocalizedText(entry.description, _defaultLanguage)}
+														{displayText(entry.description)}
 													</div>
 												{/if}
 												{#if typeChanged(row)}
@@ -1043,6 +1070,7 @@
 														bind:options={row.def.options}
 														{languages}
 														defaultLanguage={_defaultLanguage}
+														displayLanguage={_displayLanguage}
 														{languageLabels}
 														{disabled}
 														locked={!!row.def.lock?.options}
@@ -1077,7 +1105,7 @@
 															{@const exValue = extraText(row, ex.key)}
 															<div class="fb-extra">
 																<label class="fb-sub-label" for={exId}>
-																	{getLocalizedText(ex.label, _defaultLanguage)}
+																	{displayText(ex.label)}
 																</label>
 																{#if ex.type === "string"}
 																	<input
@@ -1086,10 +1114,7 @@
 																		class={twMerge(INPUT_CLS, "fb-extra-input w-full")}
 																		value={exValue}
 																		maxlength={ex.maxlength}
-																		placeholder={getLocalizedText(
-																			ex.placeholder,
-																			_defaultLanguage
-																		) || undefined}
+																		placeholder={displayText(ex.placeholder) || undefined}
 																		oninput={(e) =>
 																			onExtraStringInput(
 																				row,
@@ -1124,11 +1149,11 @@
 																		{tabindex}
 																	>
 																		<option value="">
-																			{getLocalizedText(ex.placeholder, _defaultLanguage)}
+																			{displayText(ex.placeholder)}
 																		</option>
 																		{#each ex.options as opt (opt.value)}
 																			<option value={opt.value}>
-																				{getLocalizedText(opt.label, _defaultLanguage)}
+																				{displayText(opt.label)}
 																			</option>
 																		{/each}
 																		<!-- a stored value outside the declared list stays
@@ -1141,7 +1166,7 @@
 																{/if}
 																{#if ex.description}
 																	<div class="fb-hint text-xs mt-0.5">
-																		{getLocalizedText(ex.description, _defaultLanguage)}
+																		{displayText(ex.description)}
 																	</div>
 																{/if}
 															</div>
@@ -1158,10 +1183,10 @@
 																	{tabindex}
 																/>
 																<span class="text-sm">
-																	{getLocalizedText(ex.label, _defaultLanguage)}
+																	{displayText(ex.label)}
 																	{#if ex.description}
 																		<span class="fb-hint block text-xs">
-																			{getLocalizedText(ex.description, _defaultLanguage)}
+																			{displayText(ex.description)}
 																		</span>
 																	{/if}
 																</span>
@@ -1291,14 +1316,14 @@
 								{:else}
 									<div class="fb-preview-fallback flex items-center gap-1.5 text-sm">
 										<span>
-											{getLocalizedText(f.label, _defaultLanguage) || t("untitled")}
+											{displayText(f.label) || t("untitled")}
 										</span>
 										{#if f.required}
 											<span class="fb-row-required" aria-hidden="true">*</span>
 										{/if}
 										{#if pentry}
 											<span class="fb-chip">
-												{getLocalizedText(pentry.label, _defaultLanguage)}
+												{displayText(pentry.label)}
 											</span>
 										{/if}
 									</div>

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

@@ -42,8 +42,22 @@ export interface Props extends InputWrapClassProps, Record<string, any> {
      * strings.
      */
     languages?: string[];
-    /** Defaults to `languages[0]`. Drives key derivation and display texts. */
+    /**
+     * The canonical (authoring) language. Defaults to `languages[0]`. Drives
+     * key derivation, the "label required" rule and which input the label/
+     * description/option editors show collapsed. Also the display language
+     * unless `displayLanguage` is set.
+     */
     defaultLanguage?: string;
+    /**
+     * Which translation of consumer-supplied localized data is DISPLAYED —
+     * field labels in the row list, announcements and the preview fallback;
+     * palette labels/descriptions; extras labels/placeholders/descriptions.
+     * Typically the current user's UI locale. Purely presentational: authoring
+     * stays on `defaultLanguage` (see above), which is also the fallback for a
+     * missing translation. Default: `defaultLanguage`.
+     */
+    displayLanguage?: string;
     languageLabels?: Record<string, string>;
     /** Key policy. Default: lowercase snake_case starting with a letter. */
     keyPattern?: RegExp;

package/dist/components/FieldsBuilder/README.md

@@ -187,35 +187,36 @@ not block validation. It is never silently dropped.
 
 ## Props
 
-| Prop                                                          | Type                                                 | Default        | Description                                            |
-| ------------------------------------------------------------- | ---------------------------------------------------- | -------------- | ------------------------------------------------------ |
-| `value`                                                       | `FieldDef[]`                                         | required       | Bindable ordered field list                            |
-| `name`                                                        | `string`                                             | required       | Hidden-input name (form participation)                 |
-| `types`                                                       | `FieldTypeDef[]`                                     | required       | The type palette                                       |
-| `label`                                                       | `Snippet \| THC`                                     | —              | Field label                                            |
-| `description`                                                 | `Snippet \| THC`                                     | —              | Help text below                                        |
-| `languages`                                                   | `string[]`                                           | —              | Enables multi-language label/description/option labels |
-| `defaultLanguage`                                             | `string`                                             | `languages[0]` | Drives key derivation and display texts                |
-| `languageLabels`                                              | `Record<string, string>`                             | —              | Display names for language codes                       |
-| `keyPattern`                                                  | `RegExp`                                             | snake_case     | Key validation pattern                                 |
-| `keyMaxLength`                                                | `number`                                             | `63`           | Key length limit                                       |
-| `reservedKeys`                                                | `string[] \| (key) => boolean`                       | —              | Keys the user may not use                              |
-| `keysImmutable`                                               | `boolean`                                            | `true`         | Freeze keys loaded from `value`                        |
-| `deriveKeyFromLabel`                                          | `boolean \| (label) => string`                       | `true`         | Live key derivation (custom slugifier allowed)         |
-| `maxFields`                                                   | `number`                                             | —              | Disables adding beyond the limit                       |
-| `deleteMode`                                                  | `"mark" \| "immediate"`                              | `"mark"`       | Delete UX (see above)                                  |
-| `onBeforeDelete`                                              | `(field) => void \| false \| Promise<void \| false>` | —              | Delete veto hook                                       |
-| `onBeforeTypeChange`                                          | `(field, newType) => void \| false \| Promise<...>`  | —              | Type-change veto hook (pre-existing fields)            |
-| `onChange`                                                    | `(value: FieldDef[]) => void`                        | —              | Fired after every change                               |
-| `preview`                                                     | `Snippet<[{ fields: FieldDef[] }]>`                  | —              | Preview pane content (see below)                       |
-| `previewBreakpoint`                                           | `number`                                             | `768`          | Component width for side-by-side preview; `0` = below  |
-| `required`                                                    | `boolean`                                            | `false`        | At least one field required                            |
-| `validate`                                                    | `boolean \| ValidateOptions`                         | `true`         | Validate-action options                                |
-| `renderSize`                                                  | `"sm" \| "md" \| "lg"`                               | `"sm"`         | InputWrap size                                         |
-| `addLabel`, `emptyMessage`                                    | `string`                                             | —              | Text overrides                                         |
-| `classRow`, `classRowHeader`, `classRowBody`, `classPreview`  | `string`                                             | —              | Class hooks                                            |
-| `t`                                                           | `TranslateFn`                                        | built-in (en)  | i18n override for all texts (see below)                |
-| `disabled`, `id`, `tabindex`, `style`, `labelLeft*`, `class*` |                                                      |                | Standard `Field*`/InputWrap pass-throughs              |
+| Prop                                                          | Type                                                 | Default           | Description                                                                     |
+| ------------------------------------------------------------- | ---------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------- |
+| `value`                                                       | `FieldDef[]`                                         | required          | Bindable ordered field list                                                     |
+| `name`                                                        | `string`                                             | required          | Hidden-input name (form participation)                                          |
+| `types`                                                       | `FieldTypeDef[]`                                     | required          | The type palette                                                                |
+| `label`                                                       | `Snippet \| THC`                                     | —                 | Field label                                                                     |
+| `description`                                                 | `Snippet \| THC`                                     | —                 | Help text below                                                                 |
+| `languages`                                                   | `string[]`                                           | —                 | Enables multi-language label/description/option labels                          |
+| `defaultLanguage`                                             | `string`                                             | `languages[0]`    | Canonical language: key derivation, required-label rule, editors' primary input |
+| `displayLanguage`                                             | `string`                                             | `defaultLanguage` | Translation shown in read-only spots (row list, palette, extras); see i18n      |
+| `languageLabels`                                              | `Record<string, string>`                             | —                 | Display names for language codes                                                |
+| `keyPattern`                                                  | `RegExp`                                             | snake_case        | Key validation pattern                                                          |
+| `keyMaxLength`                                                | `number`                                             | `63`              | Key length limit                                                                |
+| `reservedKeys`                                                | `string[] \| (key) => boolean`                       | —                 | Keys the user may not use                                                       |
+| `keysImmutable`                                               | `boolean`                                            | `true`            | Freeze keys loaded from `value`                                                 |
+| `deriveKeyFromLabel`                                          | `boolean \| (label) => string`                       | `true`            | Live key derivation (custom slugifier allowed)                                  |
+| `maxFields`                                                   | `number`                                             | —                 | Disables adding beyond the limit                                                |
+| `deleteMode`                                                  | `"mark" \| "immediate"`                              | `"mark"`          | Delete UX (see above)                                                           |
+| `onBeforeDelete`                                              | `(field) => void \| false \| Promise<void \| false>` | —                 | Delete veto hook                                                                |
+| `onBeforeTypeChange`                                          | `(field, newType) => void \| false \| Promise<...>`  | —                 | Type-change veto hook (pre-existing fields)                                     |
+| `onChange`                                                    | `(value: FieldDef[]) => void`                        | —                 | Fired after every change                                                        |
+| `preview`                                                     | `Snippet<[{ fields: FieldDef[] }]>`                  | —                 | Preview pane content (see below)                                                |
+| `previewBreakpoint`                                           | `number`                                             | `768`             | Component width for side-by-side preview; `0` = below                           |
+| `required`                                                    | `boolean`                                            | `false`           | At least one field required                                                     |
+| `validate`                                                    | `boolean \| ValidateOptions`                         | `true`            | Validate-action options                                                         |
+| `renderSize`                                                  | `"sm" \| "md" \| "lg"`                               | `"sm"`            | InputWrap size                                                                  |
+| `addLabel`, `emptyMessage`                                    | `string`                                             | —                 | Text overrides                                                                  |
+| `classRow`, `classRowHeader`, `classRowBody`, `classPreview`  | `string`                                             | —                 | Class hooks                                                                     |
+| `t`                                                           | `TranslateFn`                                        | built-in (en)     | i18n override for all texts (see below)                                         |
+| `disabled`, `id`, `tabindex`, `style`, `labelLeft*`, `class*` |                                                      |                   | Standard `Field*`/InputWrap pass-throughs                                       |
 
 Imperative API (via `bind:this`), same as every `Field*`:
 `validate()`, `clearValidation()`, `getValidation()`, `focus()`, `scrollIntoView()`.
@@ -281,7 +282,39 @@ messages alone would leave the type select in English. `FIELDS_BUILDER_DEFAULT_T
 is the Slovak twin of `FIELDS_BUILDER_DEFAULT_TYPES` (identical `type` values — the
 stored defs are unaffected by which one you pass). A palette entry's `label` /
 `description` also accept a per-language map (`{ en: "Text", sk: "Text" }`), resolved
-against `defaultLanguage`.
+against `displayLanguage`.
+
+### Display language vs. default language
+
+With `languages` set, two languages play different roles:
+
+- **`defaultLanguage`** (default `languages[0]`) is the _canonical_ one: the key is
+  derived from its label, the "label required" rule checks its entry, and the
+  label/description/option editors open on it (the other translations sit behind the
+  toggle).
+- **`displayLanguage`** (default `defaultLanguage`) is what the component _shows_
+  wherever it renders localized data read-only: the collapsed row titles and the
+  reorder/delete announcements, the type chips and the type picker, the palette
+  descriptions, extras labels/placeholders/descriptions, the built-in preview fallback,
+  and the extra's name in `err_extra_maxlength`. A missing translation falls back to
+  `defaultLanguage`, then to the first non-empty entry.
+
+So a Slovak user of a schema whose canonical language is English gets a Slovak list and
+Slovak chrome (`t`), and still edits the canonical English label first:
+
+```svelte
+<FieldsBuilder
+	bind:value
+	name="fields"
+	types={FIELDS_BUILDER_DEFAULT_TYPES_SK}
+	languages={["en", "sk"]}
+	displayLanguage={user.locale}
+	t={createFieldsBuilderT(FIELDS_BUILDER_MESSAGES_SK)}
+/>
+```
+
+`getLocalizedText(text, preferred)` — exported — accepts the same fallback chain as an
+array: `getLocalizedText(label, ["sk", "en"])`.
 
 ## Accessibility
 

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

@@ -37,7 +37,10 @@
 	interface Props {
 		options?: FieldOptionDef[];
 		languages?: string[];
+		/** Canonical language: value derivation and the editors' collapsed input. */
 		defaultLanguage?: string;
+		/** Language the announcements read option labels in. Default: `defaultLanguage`. */
+		displayLanguage?: string;
 		languageLabels?: Record<string, string>;
 		disabled?: boolean;
 		/** `lock.options` — render the list read-only. */
@@ -52,6 +55,7 @@
 		options = $bindable(),
 		languages,
 		defaultLanguage,
+		displayLanguage,
 		languageLabels,
 		disabled = false,
 		locked = false,
@@ -61,6 +65,11 @@
 	}: Props = $props();
 
 	const _defaultLanguage = $derived(defaultLanguage || languages?.[0]);
+	const _displayLanguages = $derived(
+		[displayLanguage || _defaultLanguage, _defaultLanguage].filter(
+			(l): l is string => !!l
+		)
+	);
 
 	interface OptionMeta {
 		/** Stable render id (options themselves have no identity). */
@@ -92,7 +101,7 @@
 	) {
 		liveAnnouncement = "";
 		const msg = String(
-			t(key, { label: getLocalizedText(option.label, _defaultLanguage), ...values })
+			t(key, { label: getLocalizedText(option.label, _displayLanguages), ...values })
 		);
 		tick().then(() => (liveAnnouncement = msg));
 	}

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

@@ -3,7 +3,10 @@ import type { FieldOptionDef } from "../types.js";
 interface Props {
     options?: FieldOptionDef[];
     languages?: string[];
+    /** Canonical language: value derivation and the editors' collapsed input. */
     defaultLanguage?: string;
+    /** Language the announcements read option labels in. Default: `defaultLanguage`. */
+    displayLanguage?: string;
     languageLabels?: Record<string, string>;
     disabled?: boolean;
     /** `lock.options` — render the list read-only. */

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

@@ -5,10 +5,12 @@ 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.
+ * Read the display text of a `LocalizedText`: the string itself, the entry of
+ * the first preferred language (a single one, or a fallback chain in order of
+ * preference) that is non-empty, or the first non-empty entry as a last
+ * resort.
  */
-export declare function getLocalizedText(text: LocalizedText | null | undefined, preferredLanguage?: string): string;
+export declare function getLocalizedText(text: LocalizedText | null | undefined, preferredLanguage?: string | string[]): string;
 /**
  * Derive a machine key from a human label: transliterates diacritics
  * (`Ročník` → `rocnik`), lowercases, collapses everything else to `_`. A slug
@@ -48,7 +50,14 @@ export interface ValidateFieldDefsOptions {
     keyMaxLength?: number;
     reservedKeys?: string[] | ((key: string) => boolean);
     maxFields?: number;
+    /** The canonical language: the "label required" rule reads this entry. */
     defaultLanguage?: string;
+    /**
+     * Language the texts interpolated into messages (an extra's `label`) are
+     * read in, falling back to `defaultLanguage`. The rules themselves are not
+     * affected. Default: `defaultLanguage`.
+     */
+    displayLanguage?: string;
     /** Translator for the error messages; defaults to returning the message key. */
     t?: FieldsBuilderTranslate;
 }

package/dist/components/FieldsBuilder/utils.js

@@ -2,16 +2,22 @@
 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.
+ * Read the display text of a `LocalizedText`: the string itself, the entry of
+ * the first preferred language (a single one, or a fallback chain in order of
+ * preference) that is non-empty, or the first non-empty entry as a last
+ * resort.
  */
 export function getLocalizedText(text, preferredLanguage) {
     if (text == null)
         return "";
     if (typeof text === "string")
         return text;
-    if (preferredLanguage && text[preferredLanguage])
-        return text[preferredLanguage];
+    const preferred = typeof preferredLanguage === "string"
+        ? [preferredLanguage]
+        : (preferredLanguage ?? []);
+    for (const lang of preferred)
+        if (lang && text[lang])
+            return text[lang];
     for (const v of Object.values(text))
         if (v)
             return v;
@@ -75,6 +81,7 @@ export function validateFieldDefs(defs, opts = {}) {
     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 displayLanguages = [opts.displayLanguage, opts.defaultLanguage].filter((l) => !!l);
     const rowErrors = defs.map(() => null);
     const put = (i, field, msg) => {
         rowErrors[i] ??= {};
@@ -133,7 +140,7 @@ export function validateFieldDefs(defs, opts = {}) {
             const v = d.extras?.[ex.key];
             if (typeof v === "string" && v.length > ex.maxlength) {
                 put(i, "extras", t("err_extra_maxlength", {
-                    label: getLocalizedText(ex.label, opts.defaultLanguage),
+                    label: getLocalizedText(ex.label, displayLanguages),
                     max: ex.maxlength,
                 }));
             }

package/dist/components/Input/README.md

@@ -314,6 +314,25 @@ Override globally in `:root` or locally via `style` prop:
 | `--stuic-input-text`         | `--stuic-color-foreground`       | Text color            |
 | `--stuic-input-placeholder`  | `--stuic-color-muted-foreground` | Placeholder color     |
 
+### Readonly Tokens
+
+Any `Field*` control that reaches the DOM with a `readonly` attribute (via the
+`readonly` prop passthrough) gets a muted wrapper — a "shown, but not yours to
+change" treatment. Deliberately **not** the `disabled` treatment: `disabled`
+fades the whole wrap to `opacity: 0.5` and leaves the tab order, while readonly
+keeps full text contrast and stays focusable, selectable and copyable. Applies
+to `<input>` and `<textarea>` only — `<select>` has no readonly counterpart.
+
+| Variable                        | Default                                                                  | Description                      |
+| ------------------------------- | ------------------------------------------------------------------------ | -------------------------------- |
+| `--stuic-input-bg-readonly`     | `--stuic-color-input` mixed 10% toward `--stuic-color-muted-foreground`  | Wrapper background when readonly |
+| `--stuic-input-border-readonly` | `--stuic-input-border` mixed 15% toward `--stuic-color-muted-foreground` | Wrapper border when readonly     |
+
+Both are _mixed off_ the editable values rather than pointing at
+`--stuic-color-muted`: in several themes (stone, for one) `muted` and `input`
+sit ~2% apart, which is no visual cue at all. Mixing toward the muted
+_foreground_ also reverses direction on its own in dark themes.
+
 ### Size Tokens
 
 Each size (sm, md, lg) has corresponding tokens:

package/dist/components/Input/index.css

@@ -24,6 +24,15 @@
 	--stuic-input-text: var(--stuic-color-foreground);
 	--stuic-input-placeholder: color-mix(in oklab, var(--stuic-color-muted-foreground) 75%, transparent);
 
+	/* Readonly: a value shown but not editable. Deliberately NOT the disabled
+	   treatment (opacity 0.5) — the text must stay fully legible. Mixed off the
+	   input bg rather than set to --stuic-color-muted: in several themes (stone,
+	   the demo default) muted and input sit ~2% apart, which is no cue at all.
+	   Mixing toward the muted *foreground* also flips direction on its own in
+	   dark themes, so the field reads as "settled" either way. */
+	--stuic-input-bg-readonly: color-mix(in oklab, var(--stuic-color-muted-foreground) 10%, var(--stuic-color-input));
+	--stuic-input-border-readonly: color-mix(in oklab, var(--stuic-color-muted-foreground) 15%, var(--stuic-input-border));
+
 	/* Size: sm */
 	--stuic-input-padding-x-sm: calc(var(--spacing) * 2.5);
 	--stuic-input-padding-y-sm: calc(var(--spacing) * 2);
@@ -254,6 +263,22 @@
 		cursor: not-allowed;
 	}
 
+	/* Readonly state — "this value is known, you just can't change it".
+	   Scoped to the wrap that directly contains the control (not the whole
+	   .stuic-input) so a nested readonly control can't mute an editable parent.
+	   Unlike disabled it keeps full text contrast and the focus ring: a readonly
+	   control is still focusable, and hiding that would cost keyboard users. */
+	.stuic-input .input-wrap:has(input[readonly]),
+	.stuic-input .input-wrap:has(textarea[readonly]) {
+		background: var(--stuic-input-bg-readonly);
+		border-color: var(--stuic-input-border-readonly);
+	}
+
+	.stuic-input input[readonly],
+	.stuic-input textarea[readonly] {
+		cursor: default;
+	}
+
 	/* Transparent wrapper utility - for components like Switch that don't need wrapper styling */
 	.stuic-input .input-wrap.input-wrap-transparent,
 	.stuic-input.invalid .input-wrap.input-wrap-transparent,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.178.0",
+	"version": "3.180.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",
@@ -177,7 +177,7 @@
 		"tailwindcss": "^4.3.3",
 		"tsx": "^4.23.13",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.69.0",
+		"typescript-eslint": "^8.70.0",
 		"vite": "^7.3.6",
 		"vitest": "^4.1.11",
 		"vitest-browser-svelte": "^2.2.1"