@marianmeres/stuic 3.168.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/README.md

@@ -43,7 +43,7 @@ npm install @marianmeres/stuic
 - **FieldRadios** - Radio button group
 - **FieldFile** - File upload input
 - **FieldAssets** - Multi-file upload with preview
-- **FieldOptions** - Modal-based multi-select picker
+- **FieldOptions** - Modal-based multi-select picker (optional inline `chips` display)
 - **FieldKeyValues** - Key-value pairs editor with JSON serialization
 - **FieldSwitch** - Toggle switch within a form
 - **Fieldset** - Group of form fields with legend

package/dist/components/Input/FieldOptions.svelte

@@ -20,12 +20,11 @@
 		type ValidationResult,
 	} from "../../actions/validate.svelte.js";
 	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";
@@ -36,8 +35,10 @@
 	import X from "../X/X.svelte";
 	import InputWrap from "./_internal/InputWrap.svelte";
 	import FieldLikeButton from "./FieldLikeButton.svelte";
+	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;
@@ -90,6 +91,18 @@
 		 * serialized to `value` on submit. No-op for single-select. Default `false`.
 		 */
 		ordered?: boolean;
+		/**
+		 * Opt-in: render the current selection as inline, individually removable chips
+		 * (`Pill`s) instead of the comma-joined text button. Picking still happens in the
+		 * modal (opened by the trailing button, or by clicking the empty part of the row);
+		 * removing a chip writes `value` immediately, without the modal. `renderValue` is
+		 * ignored in this mode (labels come from `renderOptionLabel`). Default `false`.
+		 */
+		chips?: boolean;
+		/** Classes for each chip (`chips` mode only) */
+		classChip?: string;
+		/** Pill intent of the chips (`chips` mode only) */
+		chipIntent?: IntentColorKey;
 		showIconsCheckbox?: boolean;
 		showIconsRadio?: boolean;
 		searchPlaceholder?: string;
@@ -97,56 +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",
-			//
-			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">
@@ -214,6 +177,9 @@
 		renderOptionGroup = (s: string) => `${s}`.replaceAll("_", " "),
 		allowUnknown = false,
 		ordered = false,
+		chips = false,
+		classChip,
+		chipIntent,
 		showIconsCheckbox = true,
 		showIconsRadio = false,
 		searchPlaceholder,
@@ -229,8 +195,9 @@
 		modal = modalDialog;
 	});
 
-	// Imperative API delegates to the inner FieldLikeButton trigger.
-	let triggerRef: FieldLikeButton | undefined = $state();
+	// Imperative API delegates to the inner trigger (FieldLikeButton, or FieldLikeChips in
+	// `chips` mode) — both expose the same methods.
+	let triggerRef: FieldLikeButton | FieldLikeChips | undefined = $state();
 
 	/** Trigger validation now. Renders the inline message if invalid. */
 	export function validate(): ValidationResult | undefined {
@@ -604,6 +571,38 @@
 		});
 	}
 
+	// --- chips (inline display of the selection) ---
+
+	// straight from `value`, in value order — so with `ordered` the arranged order is what
+	// the user sees; labels go through the same renderer as the modal's options
+	let chipItems: FieldLikeChip[] = $derived.by(() => {
+		if (!chips) return [];
+		const parsed = maybeJsonParse(value || "[]");
+		if (!Array.isArray(parsed)) return [];
+		return parsed
+			.filter((item) => item != null)
+			.map((item: Item, i: number) => {
+				const label = _renderOptionLabel(item);
+				return {
+					// index-suffixed so a (malformed) duplicate id can't break the keyed each
+					key: `${item[itemIdPropName] ?? ""}__${i}`,
+					label,
+					removeLabel: t("chips_remove", { value: label }),
+				};
+			});
+	});
+
+	// removing a chip is an immediate, modal-less edit of `value` + the same change
+	// notification the modal submit does (so validation re-runs)
+	function removeChip(_chip: FieldLikeChip, index: number) {
+		const parsed = maybeJsonParse(value || "[]");
+		if (!Array.isArray(parsed)) return;
+		const items = parsed.filter((item) => item != null);
+		value = JSON.stringify(items.filter((_, i) => i !== index));
+		_dispatch_change_to_owner();
+		onChange?.(value);
+	}
+
 	// "outer" submit - will set the outer bound value (always string) and close modal...
 	// further process is left on the consumer
 	function submit() {
@@ -712,6 +711,42 @@
 <div>
 	{#if trigger}
 		{@render trigger({ value, modal: modalDialog })}
+	{:else if chips}
+		<FieldLikeChips
+			bind:this={triggerRef}
+			bind:value
+			bind:input={parentHiddenInputEl}
+			chips={chipItems}
+			{name}
+			class={classProp}
+			{label}
+			{description}
+			{labelLeft}
+			{labelAfter}
+			{below}
+			{labelLeftWidth}
+			{labelLeftBreakpoint}
+			{classLabel}
+			{classLabelBox}
+			{classInputBox}
+			{classInputBoxWrap}
+			{classInputBoxWrapInvalid}
+			{classDescBox}
+			{classDescBoxToggle}
+			{classBelowBox}
+			{classValidationBox}
+			{style}
+			validate={wrappedValidate}
+			{required}
+			{disabled}
+			{tabindex}
+			{classChip}
+			{chipIntent}
+			placeholder={t("chips_placeholder")}
+			openLabel={t("chips_open")}
+			onOpen={() => modalDialog?.open()}
+			onRemove={removeChip}
+		/>
 	{:else}
 		<FieldLikeButton
 			bind:this={triggerRef}

package/dist/components/Input/FieldOptions.svelte.d.ts

@@ -2,6 +2,7 @@ import { type Item } from "@marianmeres/item-collection";
 import { type Snippet } from "svelte";
 import { type ValidateOptions, type ValidationResult } from "../../actions/validate.svelte.js";
 import type { TranslateFn } from "../../types.js";
+import type { IntentColorKey } from "../../utils/design-tokens.js";
 import { ModalDialog } from "../ModalDialog/index.js";
 import { NotificationsStack } from "../Notifications/index.js";
 import type { THC } from "../Thc/Thc.svelte";
@@ -62,6 +63,18 @@ export interface Props extends InputWrapClassProps, Record<string, any> {
      * serialized to `value` on submit. No-op for single-select. Default `false`.
      */
     ordered?: boolean;
+    /**
+     * Opt-in: render the current selection as inline, individually removable chips
+     * (`Pill`s) instead of the comma-joined text button. Picking still happens in the
+     * modal (opened by the trailing button, or by clicking the empty part of the row);
+     * removing a chip writes `value` immediately, without the modal. `renderValue` is
+     * ignored in this mode (labels come from `renderOptionLabel`). Default `false`.
+     */
+    chips?: boolean;
+    /** Classes for each chip (`chips` mode only) */
+    classChip?: string;
+    /** Pill intent of the chips (`chips` mode only) */
+    chipIntent?: IntentColorKey;
     showIconsCheckbox?: boolean;
     showIconsRadio?: boolean;
     searchPlaceholder?: string;

package/dist/components/Input/README.md

@@ -408,48 +408,54 @@ Components use data attributes for CSS styling:
 
 ## FieldOptions
 
-A modal-based multi-select/single-select component with search functionality, typeahead support, and option grouping.
+A modal-based multi-select/single-select component with search functionality, typeahead support, and option grouping. The closed field can show the selection as inline removable chips (`chips`).
 
 ### Props
 
-| Prop                | Type                                                       | Default    | Description                                                                         |
-| ------------------- | ---------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------- |
-| `value`             | `string`                                                   | `"[]"`     | JSON array of selected items (bindable)                                             |
-| `name`              | `string`                                                   | -          | Form field name                                                                     |
-| `getOptions`        | `(q: string, current: Item[]) => Promise<{found: Item[]}>` | -          | Async function to fetch options                                                     |
-| `cardinality`       | `number`                                                   | `Infinity` | Max selections (-1 for unlimited)                                                   |
-| `allowUnknown`      | `boolean`                                                  | `false`    | Allow typing custom values                                                          |
-| `ordered`           | `boolean`                                                  | `false`    | Opt-in: add an "Arrange" screen to manually order the selection (multi-select only) |
-| `renderOptionLabel` | `(item: Item) => string`                                   | -          | Custom option label renderer                                                        |
-| `renderOptionGroup` | `(s: string) => string`                                    | -          | Custom optgroup label renderer                                                      |
-| `renderValue`       | `(stringifiedItems: string) => string`                     | -          | Custom value display renderer                                                       |
-| `showIconsCheckbox` | `boolean`                                                  | `true`     | Show checkbox icons in multi-select                                                 |
-| `showIconsRadio`    | `boolean`                                                  | `false`    | Show radio icons in single-select                                                   |
-| `searchPlaceholder` | `string`                                                   | -          | Custom search placeholder                                                           |
-| `itemIdPropName`    | `string`                                                   | `"id"`     | Property name for item ID                                                           |
-| `notifications`     | `NotificationsStack`                                       | -          | Notification handler for errors                                                     |
+| Prop                | Type                                                       | Default    | Description                                                                              |
+| ------------------- | ---------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------- |
+| `value`             | `string`                                                   | `"[]"`     | JSON array of selected items (bindable)                                                  |
+| `name`              | `string`                                                   | -          | Form field name                                                                          |
+| `getOptions`        | `(q: string, current: Item[]) => Promise<{found: Item[]}>` | -          | Async function to fetch options                                                          |
+| `cardinality`       | `number`                                                   | `Infinity` | Max selections (-1 for unlimited)                                                        |
+| `allowUnknown`      | `boolean`                                                  | `false`    | Allow typing custom values                                                               |
+| `ordered`           | `boolean`                                                  | `false`    | Opt-in: add an "Arrange" screen to manually order the selection (multi-select only)      |
+| `chips`             | `boolean`                                                  | `false`    | Opt-in: show the selection as inline removable chips; picking still happens in the modal |
+| `classChip`         | `string`                                                   | -          | Classes for each chip (`chips` mode)                                                     |
+| `chipIntent`        | `IntentColorKey`                                           | -          | Pill intent of the chips (`chips` mode)                                                  |
+| `renderOptionLabel` | `(item: Item) => string`                                   | -          | Custom option label renderer                                                             |
+| `renderOptionGroup` | `(s: string) => string`                                    | -          | Custom optgroup label renderer                                                           |
+| `renderValue`       | `(stringifiedItems: string) => string`                     | -          | Custom value display renderer                                                            |
+| `showIconsCheckbox` | `boolean`                                                  | `true`     | Show checkbox icons in multi-select                                                      |
+| `showIconsRadio`    | `boolean`                                                  | `false`    | Show radio icons in single-select                                                        |
+| `searchPlaceholder` | `string`                                                   | -          | Custom search placeholder                                                                |
+| `itemIdPropName`    | `string`                                                   | `"id"`     | Property name for item ID                                                                |
+| `notifications`     | `NotificationsStack`                                       | -          | Notification handler for errors                                                          |
 
 ### Class Props
 
-| Prop                | Target                       |
-| ------------------- | ---------------------------- |
-| `classOption`       | Option item (ListItemButton) |
-| `classOptionActive` | Active/selected option       |
-| `classOptgroup`     | Option group label           |
-| `classModalField`   | Modal field wrapper          |
+| Prop                | Target                           |
+| ------------------- | -------------------------------- |
+| `classOption`       | Option item (ListItemButton)     |
+| `classOptionActive` | Active/selected option           |
+| `classOptgroup`     | Option group label               |
+| `classModalField`   | Modal field wrapper              |
+| `classChip`         | Each chip (Pill) in `chips` mode |
 
 ### CSS Variables
 
 #### Component Tokens
 
-| Variable                                   | Default                          | Description                     |
-| ------------------------------------------ | -------------------------------- | ------------------------------- |
-| `--stuic-field-options-divider`            | `--stuic-color-border`           | Divider/separator color         |
-| `--stuic-field-options-control-text`       | `--stuic-color-muted-foreground` | Control button text color       |
-| `--stuic-field-options-control-text-hover` | `--stuic-color-foreground`       | Control button hover text color |
-| `--stuic-field-options-control-ring`       | `--stuic-color-ring`             | Control button focus ring       |
-| `--stuic-field-options-muted-text`         | `--stuic-color-muted-foreground` | Muted/secondary text color      |
-| `--stuic-field-options-optgroup-text`      | `--stuic-color-muted-foreground` | Option group label color        |
+| Variable                                       | Default                          | Description                               |
+| ---------------------------------------------- | -------------------------------- | ----------------------------------------- |
+| `--stuic-field-options-divider`                | `--stuic-color-border`           | Divider/separator color                   |
+| `--stuic-field-options-control-text`           | `--stuic-color-muted-foreground` | Control button text color                 |
+| `--stuic-field-options-control-text-hover`     | `--stuic-color-foreground`       | Control button hover text color           |
+| `--stuic-field-options-control-ring`           | `--stuic-color-ring`             | Control button focus ring                 |
+| `--stuic-field-options-muted-text`             | `--stuic-color-muted-foreground` | Muted/secondary text color                |
+| `--stuic-field-options-optgroup-text`          | `--stuic-color-muted-foreground` | Option group label color                  |
+| `--stuic-field-options-chips-gap`              | `0.25rem`                        | Gap between chips (`chips` mode)          |
+| `--stuic-field-options-chips-placeholder-text` | `--stuic-input-placeholder`      | Placeholder color of an empty `chips` row |
 
 ### Usage
 
@@ -503,6 +509,113 @@ on submit (and round-trips on reopen). Single-select fields ignore the prop.
 > default contract, so the Arrange list can render selected items even when they aren't in
 > the current search results.
 
+### Chips display (`chips`)
+
+By default the closed field is a button showing the selection as comma-joined text. Opt in
+with `chips` to show it as inline, individually removable `Pill` chips instead — the tags form
+factor. Picking still happens in the same modal: open it with the trailing button, or by
+clicking the empty part of the row. Each chip's × removes that item immediately (writes
+`value`, fires `onChange`, re-runs validation) without opening the modal, and keyboard focus
+stays in the field. Chips render in `value` order, so with `ordered` they mirror the arranged
+order. `renderValue` is ignored in this mode; labels come from `renderOptionLabel`.
+
+```svelte
+<FieldOptions
+	label="Tags"
+	name="tags"
+	bind:value
+	{getOptions}
+	cardinality={-1}
+	allowUnknown
+	chips
+	chipIntent="primary"
+/>
+```
+
+Each chip's × is a full-height 24px square (the Pill's own touch-target floor,
+`--stuic-pill-dismiss-min-size`), so no extra hit-area padding is needed on touch devices.
+Typing directly into the field (an inline combobox) is deliberately not part of this mode — the
+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