@marianmeres/stuic 3.179.0 → 3.181.0

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,41 @@ 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"])`. It is the library-wide `tr()` under this
+component's name (`LocalizedText` is an alias of `MaybeLocalized`), so a label resolved in
+your own `preview` snippet and one resolved by `Nav` or `TabbedMenu` degrade identically.
 
 ## 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/types.d.ts

@@ -1,6 +1,11 @@
 import type { Snippet } from "svelte";
-/** A localized string: either one plain string, or a per-language map. */
-export type LocalizedText = string | Record<string, string>;
+import type { MaybeLocalized } from "../../utils/tr.js";
+/**
+ * A localized string: either one plain string, or a per-language map. The
+ * same shape as the library-wide `MaybeLocalized` (resolved by `tr()`); the
+ * alias is kept for this component's vocabulary.
+ */
+export type LocalizedText = MaybeLocalized;
 /** A single option of a choice-like field type (one declaring `supportsOptions`). */
 export interface FieldOptionDef {
     /** Machine value, unique within the field's options. */

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

@@ -5,10 +5,13 @@ 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. This is the library-wide `tr()` under this component's name — same
+ * resolution, same fallbacks (a JSON-encoded record is accepted too).
  */
-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 +51,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

@@ -1,21 +1,16 @@
+import { tr } from "../../utils/tr.js";
 /** 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.
+ * 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. This is the library-wide `tr()` under this component's name — same
+ * resolution, same fallbacks (a JSON-encoded record is accepted too).
  */
 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 "";
+    return tr(text, preferredLanguage);
 }
 /**
  * Derive a machine key from a human label: transliterates diacritics
@@ -75,6 +70,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 +129,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/Nav/Nav.svelte

@@ -55,8 +55,13 @@
 		/** Optional section title rendered above the groups (uppercase, non-interactive) */
 		title?: MaybeLocalized;
 
-		/** Current locale for MaybeLocalized resolution */
-		locale?: string;
+		/**
+		 * Locale for `MaybeLocalized` label resolution — one locale, or a chain
+		 * in order of preference (e.g. `[user.locale, "en"]`). A missing
+		 * translation falls back along the chain, then to the label's first
+		 * non-empty entry.
+		 */
+		locale?: string | string[];
 
 		/** Whether the sidebar is in collapsed mode (icon-only) */
 		isCollapsed?: boolean;

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

@@ -49,8 +49,13 @@ export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children" | "t
     groups: NavGroup[];
     /** Optional section title rendered above the groups (uppercase, non-interactive) */
     title?: MaybeLocalized;
-    /** Current locale for MaybeLocalized resolution */
-    locale?: string;
+    /**
+     * Locale for `MaybeLocalized` label resolution — one locale, or a chain
+     * in order of preference (e.g. `[user.locale, "en"]`). A missing
+     * translation falls back along the chain, then to the label's first
+     * non-empty entry.
+     */
+    locale?: string | string[];
     /** Whether the sidebar is in collapsed mode (icon-only) */
     isCollapsed?: boolean;
     /** Whether the sidebar is expanding (transitioning from collapsed to expanded) */

package/dist/components/Nav/README.md

@@ -8,7 +8,7 @@ A navigation component for sidebars with support for groups, nested items, expan
 | ---------------------- | --------------------------------------------------- | ------------- | --------------------------------------------------------- |
 | `groups`               | `NavGroup[]`                                        | -             | Navigation groups to render                               |
 | `title`                | `MaybeLocalized`                                    | -             | Section title above groups (uppercase, non-interactive)   |
-| `locale`               | `string`                                            | -             | Current locale for localized labels                       |
+| `locale`               | `string \| string[]`                                | -             | Locale (or preference chain) for localized labels         |
 | `isCollapsed`          | `boolean`                                           | `false`       | Collapsed mode (icon-only)                                |
 | `isExpanding`          | `boolean`                                           | `false`       | Transitioning from collapsed to expanded                  |
 | `activeId`             | `string`                                            | -             | Active item ID for highlighting                           |
@@ -329,7 +329,7 @@ Note: in icon-only sidebar mode (`isCollapsed`), the section title is visually h
 - **localStorage Persistence**: Expand/collapse state persists across page reloads
 - **Collapsed Mode**: Icon-only sidebar with tooltips
 - **Active State**: Highlight current item via `activeId` or custom callback
-- **Localization**: Labels support `MaybeLocalized` type
+- **Localization**: Labels support `MaybeLocalized`, resolved via `tr()` against `locale` (a single locale or a preference chain); a missing translation falls back to the label's first non-empty entry, never to `[object Object]`
 - **Touch-Friendly**: Auto-detect or manually enable larger touch targets
 - **ARIA Compliant**: Proper roles and aria-expanded attributes
 - **Reduced Motion**: Respects user's reduced motion preference

package/dist/components/TabbedMenu/README.md

@@ -22,19 +22,20 @@ A horizontal tab navigation component built on semantic `ul/li` markup with ARIA
 
 ## Props
 
-| Prop                  | Type                             | Default     | Description                        |
-| --------------------- | -------------------------------- | ----------- | ---------------------------------- |
-| `items`               | `TabbedMenuItem[]`               | required    | Array of tab items                 |
-| `value`               | `string \| number`               | `undefined` | Active tab id (bindable)           |
-| `disabled`            | `boolean`                        | `false`     | Disable all tabs                   |
-| `onSelect`            | `(item: TabbedMenuItem) => void` | `undefined` | Callback when tab is selected      |
-| `class`               | `string`                         | `undefined` | Class for the `ul` wrapper         |
-| `classItem`           | `string`                         | `undefined` | Class for each `li` element        |
-| `classButton`         | `string`                         | `undefined` | Class for tab buttons              |
-| `classButtonActive`   | `string`                         | `undefined` | Additional class for active tab    |
-| `classButtonDisabled` | `string`                         | `undefined` | Additional class for disabled tabs |
-| `unstyled`            | `boolean`                        | `false`     | Skip default styling               |
-| `el`                  | `HTMLUListElement`               | `undefined` | Element reference (bindable)       |
+| Prop                  | Type                             | Default     | Description                                   |
+| --------------------- | -------------------------------- | ----------- | --------------------------------------------- |
+| `items`               | `TabbedMenuItem[]`               | required    | Array of tab items                            |
+| `value`               | `string \| number`               | `undefined` | Active tab id (bindable)                      |
+| `disabled`            | `boolean`                        | `false`     | Disable all tabs                              |
+| `onSelect`            | `(item: TabbedMenuItem) => void` | `undefined` | Callback when tab is selected                 |
+| `locale`              | `string \| string[]`             | `undefined` | Locale (or chain) for `MaybeLocalized` labels |
+| `class`               | `string`                         | `undefined` | Class for the `ul` wrapper                    |
+| `classItem`           | `string`                         | `undefined` | Class for each `li` element                   |
+| `classButton`         | `string`                         | `undefined` | Class for tab buttons                         |
+| `classButtonActive`   | `string`                         | `undefined` | Additional class for active tab               |
+| `classButtonDisabled` | `string`                         | `undefined` | Additional class for disabled tabs            |
+| `unstyled`            | `boolean`                        | `false`     | Skip default styling                          |
+| `el`                  | `HTMLUListElement`               | `undefined` | Element reference (bindable)                  |
 
 ## TabbedMenuItem Interface
 

package/dist/components/TabbedMenu/TabbedMenu.svelte

@@ -21,8 +21,13 @@
 		disabled?: boolean;
 		onSelect?: (item: TabbedMenuItem) => void;
 		orientation?: "horizontal" | "vertical";
-		/** Current locale for MaybeLocalized resolution */
-		locale?: string;
+		/**
+		 * Locale for `MaybeLocalized` label resolution — one locale, or a chain
+		 * in order of preference (e.g. `[user.locale, "en"]`). A missing
+		 * translation falls back along the chain, then to the label's first
+		 * non-empty entry.
+		 */
+		locale?: string | string[];
 		//
 		class?: string;
 		classItem?: string;

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

@@ -16,8 +16,13 @@ export interface Props extends Omit<HTMLAttributes<HTMLUListElement>, "children"
     disabled?: boolean;
     onSelect?: (item: TabbedMenuItem) => void;
     orientation?: "horizontal" | "vertical";
-    /** Current locale for MaybeLocalized resolution */
-    locale?: string;
+    /**
+     * Locale for `MaybeLocalized` label resolution — one locale, or a chain
+     * in order of preference (e.g. `[user.locale, "en"]`). A missing
+     * translation falls back along the chain, then to the label's first
+     * non-empty entry.
+     */
+    locale?: string | string[];
     class?: string;
     classItem?: string;
     classButton?: string;

package/dist/index.css

@@ -86,6 +86,7 @@ In practice:
 @import "./components/RegisterForm/index.css";
 @import "./components/LoginOrRegisterForm/index.css";
 @import "./components/Checkout/index.css";
+@import "./components/ColorPicker/index.css";
 @import "./components/CommandMenu/index.css";
 /* NOTE: CommentInput/index.css is deliberately NOT imported here — same reason as
    MarkdownEditor's. It is a subpath-export component and imports its own CSS

package/dist/index.d.ts

@@ -39,6 +39,7 @@ export * from "./components/Carousel/index.js";
 export * from "./components/Checkout/index.js";
 export * from "./components/Circle/index.js";
 export * from "./components/Collapsible/index.js";
+export * from "./components/ColorPicker/index.js";
 export * from "./components/ColorScheme/index.js";
 export * from "./components/CommandMenu/index.js";
 export * from "./components/ContactUsForm/index.js";

package/dist/index.js

@@ -40,6 +40,7 @@ export * from "./components/Carousel/index.js";
 export * from "./components/Checkout/index.js";
 export * from "./components/Circle/index.js";
 export * from "./components/Collapsible/index.js";
+export * from "./components/ColorPicker/index.js";
 export * from "./components/ColorScheme/index.js";
 export * from "./components/CommandMenu/index.js";
 // NOTE: CommentInput is deliberately NOT exported here. It embeds MarkdownEditor,

package/dist/utils/tr.d.ts

@@ -1,25 +1,37 @@
 /**
- * A value that may be a plain string or a locale-keyed object of translations.
+ * A value that may be a plain string or a locale-keyed object of translations
+ * (`{ en: "Hello", sk: "Ahoj" }`).
  */
 export type MaybeLocalized = string | Record<string, string>;
 /**
- * Performs a locale-based translation lookup on a value.
+ * Resolves a `MaybeLocalized` value to the text to display.
  *
- * If the value is a plain string, returns it directly. If it's an object with
- * locale keys (e.g., `{ en: "Hello", sk: "Ahoj" }`), returns the value for the
- * given locale.
+ * A plain string is returned as-is. A locale-keyed record (or a JSON string
+ * encoding one — how string-valued inputs such as `FieldInputLocalized` carry
+ * it) is resolved in this order:
  *
- * @param val - A plain string or locale-keyed object (can also be a JSON string of the object)
- * @param locale - The locale key to look up (e.g., "en", "sk")
- * @param fallback - Fallback value if locale key not found
- * @returns The translated string
+ * 1. the first entry of `locale` (one locale, or a preference chain in order)
+ *    that is non-empty — an empty entry counts as missing,
+ * 2. `fallback`, when one is given,
+ * 3. the first non-empty entry of the record,
+ * 4. `""`.
+ *
+ * So a record never renders as `[object Object]`, and a missing translation
+ * degrades to another language rather than to nothing. `null`/`undefined`
+ * yield `fallback ?? ""`.
+ *
+ * @param val - A plain string, a locale-keyed record, or a JSON string of one
+ * @param locale - The locale to look up, or a chain of locales in order of preference
+ * @param fallback - Text to use when none of `locale` has a non-empty entry
  *
  * @example
  * ```ts
- * tr('Hello', 'sk');                            // 'Hello' (plain string returned as-is)
- * tr({ en: 'Hello', sk: 'Ahoj' }, 'sk');        // 'Ahoj'
- * tr({ en: 'Hello' }, 'sk', 'fallback');        // 'fallback'
- * tr('{"en":"Hello","sk":"Ahoj"}', 'sk');       // 'Ahoj' (JSON string parsed)
+ * tr("Hello", "sk");                             // "Hello" (plain string returned as-is)
+ * tr({ en: "Hello", sk: "Ahoj" }, "sk");         // "Ahoj"
+ * tr({ en: "Hello", sk: "Ahoj" }, ["cs", "sk"]); // "Ahoj" (chain, in order)
+ * tr({ en: "Hello" }, "sk");                     // "Hello" (first non-empty entry)
+ * tr({ en: "Hello" }, "sk", "—");                // "—" (explicit fallback wins)
+ * tr('{"en":"Hello","sk":"Ahoj"}', "sk");        // "Ahoj" (JSON string parsed)
  * ```
  */
-export declare function tr(val: MaybeLocalized | undefined | null, locale?: string, fallback?: string): string;
+export declare function tr(val: MaybeLocalized | undefined | null, locale?: string | string[], fallback?: string): string;

package/dist/utils/tr.js

@@ -1,30 +1,54 @@
+import { isPlainObject } from "./is-plain-object.js";
 import { maybeJsonParse } from "./maybe-json-parse.js";
 /**
- * Performs a locale-based translation lookup on a value.
+ * Resolves a `MaybeLocalized` value to the text to display.
  *
- * If the value is a plain string, returns it directly. If it's an object with
- * locale keys (e.g., `{ en: "Hello", sk: "Ahoj" }`), returns the value for the
- * given locale.
+ * A plain string is returned as-is. A locale-keyed record (or a JSON string
+ * encoding one — how string-valued inputs such as `FieldInputLocalized` carry
+ * it) is resolved in this order:
  *
- * @param val - A plain string or locale-keyed object (can also be a JSON string of the object)
- * @param locale - The locale key to look up (e.g., "en", "sk")
- * @param fallback - Fallback value if locale key not found
- * @returns The translated string
+ * 1. the first entry of `locale` (one locale, or a preference chain in order)
+ *    that is non-empty — an empty entry counts as missing,
+ * 2. `fallback`, when one is given,
+ * 3. the first non-empty entry of the record,
+ * 4. `""`.
+ *
+ * So a record never renders as `[object Object]`, and a missing translation
+ * degrades to another language rather than to nothing. `null`/`undefined`
+ * yield `fallback ?? ""`.
+ *
+ * @param val - A plain string, a locale-keyed record, or a JSON string of one
+ * @param locale - The locale to look up, or a chain of locales in order of preference
+ * @param fallback - Text to use when none of `locale` has a non-empty entry
  *
  * @example
  * ```ts
- * tr('Hello', 'sk');                            // 'Hello' (plain string returned as-is)
- * tr({ en: 'Hello', sk: 'Ahoj' }, 'sk');        // 'Ahoj'
- * tr({ en: 'Hello' }, 'sk', 'fallback');        // 'fallback'
- * tr('{"en":"Hello","sk":"Ahoj"}', 'sk');       // 'Ahoj' (JSON string parsed)
+ * tr("Hello", "sk");                             // "Hello" (plain string returned as-is)
+ * tr({ en: "Hello", sk: "Ahoj" }, "sk");         // "Ahoj"
+ * tr({ en: "Hello", sk: "Ahoj" }, ["cs", "sk"]); // "Ahoj" (chain, in order)
+ * tr({ en: "Hello" }, "sk");                     // "Hello" (first non-empty entry)
+ * tr({ en: "Hello" }, "sk", "—");                // "—" (explicit fallback wins)
+ * tr('{"en":"Hello","sk":"Ahoj"}', "sk");        // "Ahoj" (JSON string parsed)
  * ```
  */
 export function tr(val, locale, fallback) {
-    if (!locale)
-        return `${val ?? fallback ?? ""}`;
-    val = maybeJsonParse(val);
-    // if string - no translation support
-    if (typeof val === "string")
-        return val;
-    return `${val?.[locale] ?? fallback ?? val ?? ""}`;
+    if (val == null)
+        return fallback ?? "";
+    // only a plain object is a record; a string that parses to anything else
+    // ("2024", "null", "[1,2]") is just that string
+    const parsed = maybeJsonParse(val);
+    if (!isPlainObject(parsed))
+        return String(val);
+    const rec = parsed;
+    const chain = typeof locale === "string" ? [locale] : (locale ?? []);
+    for (const l of chain) {
+        if (l && Object.hasOwn(rec, l) && rec[l])
+            return String(rec[l]);
+    }
+    if (fallback !== undefined)
+        return fallback;
+    for (const v of Object.values(rec))
+        if (v)
+            return String(v);
+    return "";
 }

package/docs/_archive/maybe-todo.md

@@ -83,8 +83,15 @@ Checked first, to avoid false positives:
     feedback (icon + intent swap, localized label/name, sr live announcement),
     `onCopied` / `onError` callbacks; the write is the reusable `copyToClipboard()`
     util (async Clipboard API + `execCommand` fallback) in `utils/`.
-13. **ColorPicker** — beyond native `type="color"`: swatch palette + custom input.
-    Given stuic's theming/design-tokens focus, a swatch picker would be on-brand.
+13. ~~**ColorPicker**~~ — ✅ shipped (see `src/lib/components/ColorPicker/`): a
+    `role="radiogroup"` swatch palette (roving tabindex, wrapping arrows, optional
+    "no color" swatch, `columns` grid) plus a custom row of the native
+    `<input type="color">` and a hex field; hidden input + `validate` with `required`,
+    `t` texts with Slovak bundled. Swatch values are never parsed — any CSS color
+    string, so `COLOR_PICKER_PALETTE_THEME` can hold `var(--stuic-color-*)` tokens and
+    the picked value keeps following the theme. Mobile needed no special path: the
+    native input opens the platform picker, so there is no popover to fight the
+    on-screen keyboard.
 
 ## Deliberately out of scope (or close enough to covered)