@marianmeres/stuic 3.180.0 → 3.181.0

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)
 

package/docs/domains/components.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-79 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
+80 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
 
 ## Component Categories
 
@@ -35,6 +35,7 @@
 | Slider               | Fancy range input (fill + optional thumb)                                                       |
 | RangeSlider          | Dual-thumb Slider: `start` ≤ `end` on one track, no crossing, `minRange`, two hidden inputs     |
 | Rating               | Star rating: radiogroup input (half steps, hover preview, form + validate) or read-only display |
+| ColorPicker          | Swatch palette (radiogroup) + native picker & hex field; any CSS color, form + validate         |
 | TwCheck              | Styled checkbox/radio                                                                           |
 | DropdownMenu         | Popover menu                                                                                    |
 | ContextMenu          | Right-click / long-press menu at the cursor (the DropdownMenu engine + trigger semantics)       |
@@ -882,6 +883,62 @@ Prefix: `--stuic-card-*`
 
 ---
 
+## ColorPicker
+
+A swatch palette plus a custom-color escape hatch. The palette is a `role="radiogroup"` of swatch buttons (roving tabindex, wrapping Left/Right, Up/Down by one _rendered_ row — measured from the layout, so it survives wrapping — Home/End, Delete/Backspace to clear, an optional crossed-out "no color" swatch); the custom row is the native `<input type="color">` next to a hex text field. A hidden input carries `name`/value with the `validate` action and `required` enforced (hidden inputs skip native constraint validation).
+
+`columns` caps swatches per row rather than forcing a grid — a phone too narrow for N wraps to fewer instead of scrolling the page sideways.
+
+Swatch values are **never parsed** — they go to CSS as `--stuic-color-picker-swatch-color`, so a palette may hold hex, `oklch(...)`, `transparent`, or `var(--stuic-color-primary)` (`COLOR_PICKER_PALETTE_THEME` does exactly that, and the stored value keeps following the theme). Selection is a ring drawn _outside_ the swatch, which reads on any color without luminance math. Mobile needs no special path: the native input opens the platform picker, so there is no popover to fight the on-screen keyboard; swatches grow to ~44px on a coarse pointer and the hex field carries the iOS zoom guard.
+
+### Exports
+
+| Export                       | Kind      | Description                                  |
+| ---------------------------- | --------- | -------------------------------------------- |
+| `ColorPicker`                | component | Main component                               |
+| `ColorPickerProps`           | type      | Props type                                   |
+| `ColorPickerCustom`          | type      | `"both" \| "native" \| "text" \| false`      |
+| `ColorPickerSwatch`          | type      | `string \| ColorPickerSwatchObject`          |
+| `ColorPickerSwatchObject`    | type      | `{ value, label? }`                          |
+| `COLOR_PICKER_PALETTE`       | constant  | Default palette (12 hues + white/grey/black) |
+| `COLOR_PICKER_PALETTE_THEME` | constant  | Opt-in design-token palette                  |
+| `createColorPickerT`         | function  | Builds the `t` prop from a (partial) catalog |
+| `COLOR_PICKER_MESSAGES_EN`   | constant  | Built-in English catalog (also the fallback) |
+| `COLOR_PICKER_MESSAGES_SK`   | constant  | Bundled Slovak catalog (opt-in)              |
+| `ColorPickerMessageKey`      | type      | Message key union                            |
+| `ColorPickerMessages`        | type      | One locale's catalog                         |
+
+### Key Props
+
+| Prop                                                  | Type                                    | Default                | Description                                                                                                                                    |
+| ----------------------------------------------------- | --------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`                                               | `string`                                | `""`                   | Bindable; any CSS color string, stored verbatim. `""` = no color                                                                               |
+| `palette`                                             | `ColorPickerSwatch[]`                   | `COLOR_PICKER_PALETTE` | Color strings or `{ value, label }` objects; `[]` renders no palette                                                                           |
+| `columns`                                             | `number`                                | —                      | Cap of N swatches per row (a narrower container wraps to fewer). Unset = as many as fit                                                        |
+| `custom`                                              | `"both" \| "native" \| "text" \| false` | `"both"`               | Which custom-color controls render under the palette                                                                                           |
+| `allowClear`                                          | `boolean`                               | `true`                 | Clear swatch + Delete/Backspace + an emptied hex field                                                                                         |
+| `name`, `required`, `validate`, `setValidationResult` |                                         |                        | Form integration — same contract as the `Field*` components; imperative `validate()` / `clearValidation()` / `getValidation()` via `bind:this` |
+| `onchange`                                            | `(value: string) => void`               | —                      | User **commits** only (see below)                                                                                                              |
+| `t`                                                   | `TranslateFn`                           | English                | Group label, swatch names, "no color", custom-color labels, required message                                                                   |
+
+Class slots: `class`, `classSwatch`.
+
+### Preview vs commit
+
+`value` updates live while the native OS picker is dragged and while a valid color is typed into the hex field (so `bind:value` previews); `onchange` — and the hidden input's `change`, which is what re-runs validation — fires only on a commit: a swatch click, an arrow onto a _different_ swatch (a radio does not re-fire for the checked one), the native picker's `change`, or Enter/blur in the hex field. An unparseable hex field commits nothing and snaps back.
+
+The hex field normalizes hex in any spelling (`#0f0`, `3b82f6`) to lowercase `#rrggbb`; anything else `CSS.supports("color", …)` accepts is kept verbatim. Because a focused field must own its own DOM value, it is written explicitly rather than driven by a reactive `value=` — Svelte skips a write when the expression matches what it last wrote, which is exactly the snap-back case.
+
+### CSS Tokens
+
+Prefix: `--stuic-color-picker-*`
+
+`gap`, `custom-gap`, `swatch-size`, `swatch-size-touch`, `swatch-border`, `swatch-scale-hover`, `swatch-ring-width`, `swatch-ring-gap`, `swatch-ring-color`, `swatch-ring-gap-color`, `ring-width`, `ring-color`, `clear-color`, `clear-bg`, `text-width`, `text-bg`, `text-border`, `text-color`, `text-placeholder`, `text-font-family`, `text-font-size`, `text-font-size-touch-min`, `opacity-disabled`
+
+Radius and border width use the shared-token fallback pattern (`swatch-radius` / `text-radius` / `*-border-width` → `--stuic-radius` / `--stuic-border-width`).
+
+---
+
 ## ContextMenu
 
 Right-click / long-press triggered menu positioned at the pointer. Wraps content into a context target area: `contextmenu` (right-click), long-press (touch/pen, via the `longPress` attachment), or Shift+F10 / the menu key open the menu anchored at the interaction point (an invisible 0×0 fixed anchor the underlying DropdownMenu positions against). The menu panel **is** a `DropdownMenu` — item model, keyboard navigation, search, overflow handling, and theming (`--stuic-dropdown-menu-*`) all come from there.

package/package.json

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