@marianmeres/stuic 3.169.0 → 3.170.0

package/AGENTS.md

@@ -23,7 +23,7 @@
 
 ```
 src/lib/
-├── components/     # 73 component directories
+├── components/     # 74 component directories
 ├── actions/        # 15 Svelte actions (use: directives)
 ├── attachments/    # Svelte attachments ({@attach} — preferred for new DOM helpers)
 ├── utils/          # 45 utility modules
@@ -129,7 +129,7 @@ Global tokens that control cross-component visual properties. Defined in `src/li
 
 ### Domain Docs
 
-- [Components](./docs/domains/components.md) — 73 component directories, Props pattern, snippets
+- [Components](./docs/domains/components.md) — 74 component directories, Props pattern, snippets
 - [Theming](./docs/domains/theming.md) — CSS tokens, dark mode, themes
 - [CSS presets](./docs/domains/css-presets.md) — ratio-locked frame (letterbox), safe-area, scrollbar
 - [Actions](./docs/domains/actions.md) — 15 Svelte directives

package/dist/components/Input/FieldOptions.svelte

@@ -22,11 +22,9 @@
 	import type { TranslateFn } from "../../types.js";
 	import type { IntentColorKey } from "../../utils/design-tokens.js";
 	import { getId } from "../../utils/get-id.js";
-	import { isPlainObject } from "../../utils/is-plain-object.js";
 	import { maybeJsonParse } from "../../utils/maybe-json-parse.js";
 	import { waitForNextRepaint } from "../../utils/paint.js";
 	import { qsa } from "../../utils/qsa.js";
-	import { replaceMap } from "../../utils/replace-map.js";
 	import { strHash } from "../../utils/str-hash.js";
 	import { twMerge } from "../../utils/tw-merge.js";
 	import Button from "../Button/Button.svelte";
@@ -40,6 +38,7 @@
 	import FieldLikeChips, { type FieldLikeChip } from "./_internal/FieldLikeChips.svelte";
 	import ListItemButton from "../ListItemButton/ListItemButton.svelte";
 	import type { InputWrapClassProps } from "./types.js";
+	import { t_default } from "./field-options-i18n.js";
 
 	export interface Option {
 		label: string;
@@ -111,60 +110,6 @@
 		itemIdPropName?: string;
 		onChange?: (value: string) => void;
 	}
-
-	// i18n ready
-	function t_default(
-		k: string,
-		values: false | null | undefined | Record<string, string | number> = null,
-		fallback: string | boolean = "",
-		i18nSpanWrap: boolean = true
-	) {
-		const m: Record<string, string> = {
-			field_req_att: "This field requires attention. Please review and try again.",
-			cardinality_of: "of max",
-			cardinality_selected: "selected",
-			submit: "Submit",
-			select_all: "Select all",
-			clear_all: "Clear selected",
-			clear: "Clear",
-			search_placeholder: "Type to search...",
-			search_submit_placeholder: "Type to search and submit...",
-			cardinality_full: "Max selection reached",
-			select_from_list: "Please select from the list only",
-			x_close: "Clear input or close [esc]",
-			close: "Close [esc]",
-			unknown_allowed: "Select or type and submit",
-			unknown_not_allowed: "Select from the list",
-			no_results: "No results found.",
-			add_new: 'Add "{{value}}"...',
-			click_add_new: "You must add the value to continue",
-			// chips display mode
-			chips_placeholder: "Nothing selected",
-			chips_open: "Choose...",
-			chips_remove: "Remove {{value}}",
-			//
-			pick_tab: "Pick",
-			arrange_tab: "Arrange ({{value}})",
-			arrange_help: "Reorder the selected items. Use the buttons to move them.",
-			sort_az: "Sort A–Z",
-			reverse: "Reverse",
-			shuffle: "Shuffle",
-			move_up: "Move up",
-			move_down: "Move down",
-			move_to_top: "Move to top",
-			move_to_bottom: "Move to bottom",
-			remove_item: "Remove",
-			moved_up: "Moved {{value}} up",
-			moved_down: "Moved {{value}} down",
-			removed_item: "Removed {{value}}",
-			sorted_az: "Sorted A to Z",
-			reversed: "Order reversed",
-			shuffled: "Order shuffled",
-		};
-		let out = m[k] ?? fallback ?? k;
-
-		return isPlainObject(values) ? replaceMap(out, values as any) : out;
-	}
 </script>
 
 <script lang="ts">

package/dist/components/Input/README.md

@@ -538,6 +538,84 @@ Typing directly into the field (an inline combobox) is deliberately not part of
 modal remains the single place where options are searched and picked, which is what keeps the
 field usable under a soft keyboard.
 
+### i18n
+
+All built-in texts go through the `t` prop. English is the built-in default; Slovak ships
+bundled and opt-in (importing it is what pulls it into your bundle — English-only consumers
+pay nothing).
+
+```svelte
+<script>
+	import {
+		FieldOptions,
+		createFieldOptionsT,
+		FIELD_OPTIONS_MESSAGES_SK,
+	} from "@marianmeres/stuic";
+
+	const t = createFieldOptionsT(FIELD_OPTIONS_MESSAGES_SK);
+</script>
+
+<FieldOptions name="tags" bind:value {getOptions} {t} />
+```
+
+`createFieldOptionsT(messages, fallbackMessages?)` falls back to
+`FIELD_OPTIONS_MESSAGES_EN` for any key the catalog does not define, so a partial catalog is
+fine and a raw key is never rendered — pass your own object to translate into a language
+that is not bundled, or to override individual texts. This matters most with `chips`, where
+`chips_placeholder`, `chips_open` and `chips_remove` end up in the **closed field**, on the
+page, next to your own copy (a filter with nothing selected is not "nothing selected", it is
+_everything_):
+
+```ts
+// reword two strings, keep English everywhere else
+const t = createFieldOptionsT({ chips_placeholder: "Any tag", chips_open: "Edit tags" });
+
+// or: full Slovak, plus a field specific tweak
+const t = createFieldOptionsT({
+	...FIELD_OPTIONS_MESSAGES_SK,
+	chips_placeholder: "Bez štítkov",
+});
+```
+
+Placeholders are mustache-style (`{{value}}`).
+
+| Key                         | English                                                     | Used by                             |
+| --------------------------- | ----------------------------------------------------------- | ----------------------------------- |
+| `field_req_att`             | This field requires attention. Please review and try again. | Validation message                  |
+| `chips_placeholder`         | Nothing selected                                            | Empty `chips` row                   |
+| `chips_open`                | Choose...                                                   | `chips` trailing button (+ tooltip) |
+| `chips_remove`              | Remove {{value}}                                            | Each chip's × accessible name       |
+| `search_placeholder`        | Type to search...                                           | Modal search input                  |
+| `search_submit_placeholder` | Type to search and submit...                                | Modal search input (`allowUnknown`) |
+| `x_close`                   | Clear input or close [esc]                                  | Search input's × tooltip            |
+| `close`                     | Close [esc]                                                 | Modal close button tooltip          |
+| `submit`                    | Submit                                                      | Modal submit button                 |
+| `select_all`                | Select all                                                  | Modal control                       |
+| `clear_all` / `clear`       | Clear selected / Clear                                      | Modal control (multi / single)      |
+| `cardinality_of`            | of max                                                      | Selection counter                   |
+| `cardinality_selected`      | selected                                                    | Selection counter                   |
+| `cardinality_full`          | Max selection reached                                       | Notification                        |
+| `no_results`                | No results found.                                           | Empty options list                  |
+| `add_new`                   | Add "{{value}}"...                                          | `allowUnknown` add row              |
+| `click_add_new`             | You must add the value to continue                          | Notification                        |
+| `select_from_list`          | Please select from the list only                            | Notification                        |
+| `unknown_allowed`           | Select or type and submit                                   | Modal footer hint                   |
+| `unknown_not_allowed`       | Select from the list                                        | Modal footer hint                   |
+| `pick_tab` / `arrange_tab`  | Pick / Arrange ({{value}})                                  | `ordered` tab header                |
+| `arrange_help`              | Reorder the selected items. Use the buttons to move them.   | `ordered` screen hint               |
+| `sort_az`                   | Sort A–Z                                                    | `ordered` shortcut                  |
+| `reverse`                   | Reverse                                                     | `ordered` shortcut                  |
+| `shuffle`                   | Shuffle                                                     | `ordered` shortcut                  |
+| `move_up` / `move_down`     | Move up / Move down                                         | `ordered` row buttons               |
+| `move_to_top`               | Move to top                                                 | `ordered` row button                |
+| `move_to_bottom`            | Move to bottom                                              | `ordered` row button                |
+| `remove_item`               | Remove                                                      | `ordered` row button                |
+| `moved_up` / `moved_down`   | Moved {{value}} up / Moved {{value}} down                   | Screen reader announcement          |
+| `removed_item`              | Removed {{value}}                                           | Screen reader announcement          |
+| `sorted_az`                 | Sorted A to Z                                               | Screen reader announcement          |
+| `reversed`                  | Order reversed                                              | Screen reader announcement          |
+| `shuffled`                  | Order shuffled                                              | Screen reader announcement          |
+
 ### Customization Examples
 
 ```css

package/dist/components/Input/field-options-i18n-sk.d.ts

@@ -0,0 +1,21 @@
+import type { FieldOptionsMessages } from "./field-options-i18n.js";
+/**
+ * Slovak message catalog for `FieldOptions`. Opt-in — English stays the built-in
+ * default, and this module is only pulled into a bundle when it is actually imported
+ * (the component itself never references it).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import {
+ *     FieldOptions,
+ *     createFieldOptionsT,
+ *     FIELD_OPTIONS_MESSAGES_SK,
+ *   } from "@marianmeres/stuic";
+ *   const t = createFieldOptionsT(FIELD_OPTIONS_MESSAGES_SK);
+ * </script>
+ *
+ * <FieldOptions name="tags" bind:value {getOptions} {t} />
+ * ```
+ */
+export declare const FIELD_OPTIONS_MESSAGES_SK: FieldOptionsMessages;

package/dist/components/Input/field-options-i18n-sk.js

@@ -0,0 +1,61 @@
+/**
+ * Slovak message catalog for `FieldOptions`. Opt-in — English stays the built-in
+ * default, and this module is only pulled into a bundle when it is actually imported
+ * (the component itself never references it).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import {
+ *     FieldOptions,
+ *     createFieldOptionsT,
+ *     FIELD_OPTIONS_MESSAGES_SK,
+ *   } from "@marianmeres/stuic";
+ *   const t = createFieldOptionsT(FIELD_OPTIONS_MESSAGES_SK);
+ * </script>
+ *
+ * <FieldOptions name="tags" bind:value {getOptions} {t} />
+ * ```
+ */
+export const FIELD_OPTIONS_MESSAGES_SK = {
+    field_req_att: "Toto pole vyžaduje pozornosť. Skontrolujte ho a skúste to znova.",
+    cardinality_of: "z max.",
+    cardinality_selected: "vybraných",
+    submit: "Potvrdiť",
+    select_all: "Vybrať všetko",
+    clear_all: "Zrušiť výber",
+    clear: "Zrušiť výber",
+    search_placeholder: "Píšte pre vyhľadávanie...",
+    search_submit_placeholder: "Píšte pre vyhľadanie a potvrdenie...",
+    cardinality_full: "Dosiahnutý maximálny počet výberov",
+    select_from_list: "Vyberte, prosím, iba zo zoznamu",
+    x_close: "Vymazať vstup alebo zavrieť [esc]",
+    close: "Zavrieť [esc]",
+    unknown_allowed: "Vyberte alebo napíšte a potvrďte",
+    unknown_not_allowed: "Vyberte zo zoznamu",
+    no_results: "Nenašli sa žiadne výsledky.",
+    add_new: 'Pridať "{{value}}"...',
+    click_add_new: "Ak chcete pokračovať, musíte hodnotu pridať",
+    // chips display mode
+    chips_placeholder: "Nič nie je vybrané",
+    chips_open: "Vybrať...",
+    chips_remove: "Odstrániť {{value}}",
+    //
+    pick_tab: "Výber",
+    arrange_tab: "Poradie ({{value}})",
+    arrange_help: "Zmeňte poradie vybraných položiek. Na presun použite tlačidlá.",
+    sort_az: "Zoradiť A–Z",
+    reverse: "Obrátiť",
+    shuffle: "Zamiešať",
+    move_up: "Posunúť vyššie",
+    move_down: "Posunúť nižšie",
+    move_to_top: "Presunúť na začiatok",
+    move_to_bottom: "Presunúť na koniec",
+    remove_item: "Odstrániť",
+    moved_up: "Posunuté vyššie: {{value}}",
+    moved_down: "Posunuté nižšie: {{value}}",
+    removed_item: "Odstránené: {{value}}",
+    sorted_az: "Zoradené od A po Z",
+    reversed: "Poradie obrátené",
+    shuffled: "Poradie zamiešané",
+};

package/dist/components/Input/field-options-i18n.d.ts

@@ -0,0 +1,82 @@
+import type { TranslateFn } from "../../types.js";
+/**
+ * The built-in (English) message catalog of `FieldOptions`. Also the fallback of every
+ * other bundled locale, so a locale missing a key still renders text.
+ *
+ * Placeholders are mustache-style (`{{value}}`).
+ */
+export declare const FIELD_OPTIONS_MESSAGES_EN: {
+    field_req_att: string;
+    cardinality_of: string;
+    cardinality_selected: string;
+    submit: string;
+    select_all: string;
+    clear_all: string;
+    clear: string;
+    search_placeholder: string;
+    search_submit_placeholder: string;
+    cardinality_full: string;
+    select_from_list: string;
+    x_close: string;
+    close: string;
+    unknown_allowed: string;
+    unknown_not_allowed: string;
+    no_results: string;
+    add_new: string;
+    click_add_new: string;
+    chips_placeholder: string;
+    chips_open: string;
+    chips_remove: string;
+    pick_tab: string;
+    arrange_tab: string;
+    arrange_help: string;
+    sort_az: string;
+    reverse: string;
+    shuffle: string;
+    move_up: string;
+    move_down: string;
+    move_to_top: string;
+    move_to_bottom: string;
+    remove_item: string;
+    moved_up: string;
+    moved_down: string;
+    removed_item: string;
+    sorted_az: string;
+    reversed: string;
+    shuffled: string;
+};
+/** Every message key `FieldOptions` may look up. */
+export type FieldOptionsMessageKey = keyof typeof FIELD_OPTIONS_MESSAGES_EN;
+/** A (possibly partial) catalog for one locale. */
+export type FieldOptionsMessages = Record<FieldOptionsMessageKey, string>;
+/**
+ * Builds the `t` prop of `FieldOptions` from a message catalog. Unknown or untranslated
+ * keys fall back to `fallbackMessages` (English by default), so a catalog may safely be
+ * partial and never renders a raw key.
+ *
+ * Handy with the `chips` display mode, where a few of the texts (`chips_placeholder`,
+ * `chips_open`, `chips_remove`) end up in the closed field, on the page, next to your own
+ * copy — reworded per field, without restating the whole catalog.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import {
+ *     FieldOptions,
+ *     createFieldOptionsT,
+ *     FIELD_OPTIONS_MESSAGES_SK,
+ *   } from "@marianmeres/stuic";
+ *
+ *   // full locale, plus a field specific tweak
+ *   const t = createFieldOptionsT({
+ *     ...FIELD_OPTIONS_MESSAGES_SK,
+ *     chips_placeholder: "Bez štítkov",
+ *   });
+ * </script>
+ *
+ * <FieldOptions chips name="tags" bind:value {getOptions} {t} />
+ * ```
+ */
+export declare function createFieldOptionsT(messages: Partial<FieldOptionsMessages> | Record<string, string>, fallbackMessages?: Partial<FieldOptionsMessages> | Record<string, string>): TranslateFn;
+/** The component's built-in English `t`. */
+export declare const t_default: TranslateFn;

package/dist/components/Input/field-options-i18n.js

@@ -0,0 +1,90 @@
+import { isPlainObject } from "../../utils/is-plain-object.js";
+import { replaceMap } from "../../utils/replace-map.js";
+/**
+ * The built-in (English) message catalog of `FieldOptions`. Also the fallback of every
+ * other bundled locale, so a locale missing a key still renders text.
+ *
+ * Placeholders are mustache-style (`{{value}}`).
+ */
+export const FIELD_OPTIONS_MESSAGES_EN = {
+    field_req_att: "This field requires attention. Please review and try again.",
+    cardinality_of: "of max",
+    cardinality_selected: "selected",
+    submit: "Submit",
+    select_all: "Select all",
+    clear_all: "Clear selected",
+    clear: "Clear",
+    search_placeholder: "Type to search...",
+    search_submit_placeholder: "Type to search and submit...",
+    cardinality_full: "Max selection reached",
+    select_from_list: "Please select from the list only",
+    x_close: "Clear input or close [esc]",
+    close: "Close [esc]",
+    unknown_allowed: "Select or type and submit",
+    unknown_not_allowed: "Select from the list",
+    no_results: "No results found.",
+    add_new: 'Add "{{value}}"...',
+    click_add_new: "You must add the value to continue",
+    // chips display mode
+    chips_placeholder: "Nothing selected",
+    chips_open: "Choose...",
+    chips_remove: "Remove {{value}}",
+    //
+    pick_tab: "Pick",
+    arrange_tab: "Arrange ({{value}})",
+    arrange_help: "Reorder the selected items. Use the buttons to move them.",
+    sort_az: "Sort A–Z",
+    reverse: "Reverse",
+    shuffle: "Shuffle",
+    move_up: "Move up",
+    move_down: "Move down",
+    move_to_top: "Move to top",
+    move_to_bottom: "Move to bottom",
+    remove_item: "Remove",
+    moved_up: "Moved {{value}} up",
+    moved_down: "Moved {{value}} down",
+    removed_item: "Removed {{value}}",
+    sorted_az: "Sorted A to Z",
+    reversed: "Order reversed",
+    shuffled: "Order shuffled",
+};
+/**
+ * Builds the `t` prop of `FieldOptions` from a message catalog. Unknown or untranslated
+ * keys fall back to `fallbackMessages` (English by default), so a catalog may safely be
+ * partial and never renders a raw key.
+ *
+ * Handy with the `chips` display mode, where a few of the texts (`chips_placeholder`,
+ * `chips_open`, `chips_remove`) end up in the closed field, on the page, next to your own
+ * copy — reworded per field, without restating the whole catalog.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import {
+ *     FieldOptions,
+ *     createFieldOptionsT,
+ *     FIELD_OPTIONS_MESSAGES_SK,
+ *   } from "@marianmeres/stuic";
+ *
+ *   // full locale, plus a field specific tweak
+ *   const t = createFieldOptionsT({
+ *     ...FIELD_OPTIONS_MESSAGES_SK,
+ *     chips_placeholder: "Bez štítkov",
+ *   });
+ * </script>
+ *
+ * <FieldOptions chips name="tags" bind:value {getOptions} {t} />
+ * ```
+ */
+export function createFieldOptionsT(messages, fallbackMessages = FIELD_OPTIONS_MESSAGES_EN) {
+    return (k, values = null, fallback = "") => {
+        const out = messages[k] ??
+            fallbackMessages[k] ??
+            (typeof fallback === "string" ? fallback : k);
+        return isPlainObject(values)
+            ? replaceMap(out, values)
+            : out;
+    };
+}
+/** The component's built-in English `t`. */
+export const t_default = createFieldOptionsT(FIELD_OPTIONS_MESSAGES_EN);

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

@@ -8,6 +8,8 @@ export { default as FieldInput, type Props as FieldInputProps, } from "./FieldIn
 export { default as FieldMoney, type Props as FieldMoneyProps, } from "./FieldMoney.svelte";
 export { default as FieldLikeButton, type Props as FieldLikeButtonProps, } from "./FieldLikeButton.svelte";
 export { default as FieldOptions, type Props as FieldOptionsProps, type Option as FieldOption, } from "./FieldOptions.svelte";
+export { createFieldOptionsT, FIELD_OPTIONS_MESSAGES_EN, type FieldOptionsMessageKey, type FieldOptionsMessages, } from "./field-options-i18n.js";
+export { FIELD_OPTIONS_MESSAGES_SK } from "./field-options-i18n-sk.js";
 export { default as FieldRadios, type Props as FieldRadiosProps, } from "./FieldRadios.svelte";
 export { default as FieldSelect, type Props as FieldSelectProps, } from "./FieldSelect.svelte";
 export { default as Fieldset, type Props as FieldsetProps } from "./Fieldset.svelte";

package/dist/components/Input/index.js

@@ -8,6 +8,8 @@ export { default as FieldInput, } from "./FieldInput.svelte";
 export { default as FieldMoney, } from "./FieldMoney.svelte";
 export { default as FieldLikeButton, } from "./FieldLikeButton.svelte";
 export { default as FieldOptions, } from "./FieldOptions.svelte";
+export { createFieldOptionsT, FIELD_OPTIONS_MESSAGES_EN, } from "./field-options-i18n.js";
+export { FIELD_OPTIONS_MESSAGES_SK } from "./field-options-i18n-sk.js";
 export { default as FieldRadios, } from "./FieldRadios.svelte";
 export { default as FieldSelect, } from "./FieldSelect.svelte";
 export { default as Fieldset } from "./Fieldset.svelte";