@marianmeres/stuic 3.167.0 → 3.169.0

package/dist/components/EmptyState/README.md

@@ -0,0 +1,188 @@
+# EmptyState
+
+Icon + title + description + CTA placeholder for empty lists, tables, and search
+results. Centered, theme-aware, and non-interactive by itself — the CTA area is a
+snippet you fill with your own `Button`s or links. Pairs naturally with `DataTable`
+("no rows"), search UIs ("no results"), and first-run dashboard tiles.
+
+## Props
+
+| Prop               | Type                               | Default   | Description                                       |
+| ------------------ | ---------------------------------- | --------- | ------------------------------------------------- |
+| `icon`             | `THC`                              | -         | Icon area content (e.g. `{ html: iconSearch() }`) |
+| `title`            | `THC`                              | -         | Title headline                                    |
+| `description`      | `THC`                              | -         | Short supporting text below the title             |
+| `variant`          | `"plain" \| "outline" \| "dashed"` | `"plain"` | Container treatment (bordered box or none)        |
+| `size`             | `"sm" \| "md" \| "lg"`             | `"md"`    | Padding, icon and typography scale                |
+| `unstyled`         | `boolean`                          | `false`   | Skip all default styling                          |
+| `class`            | `string`                           | -         | Additional CSS classes (merged via twMerge)       |
+| `classIcon`        | `string`                           | -         | Class for the icon area                           |
+| `classTitle`       | `string`                           | -         | Class for the title                               |
+| `classDescription` | `string`                           | -         | Class for the description                         |
+| `classActions`     | `string`                           | -         | Class for the actions area                        |
+| `el`               | `HTMLElement`                      | -         | Element reference (bindable)                      |
+
+## Snippet Props
+
+| Snippet      | Description                                        |
+| ------------ | -------------------------------------------------- |
+| `actions`    | CTA area below the description (buttons, links)    |
+| `renderIcon` | Override the icon area (instead of the `icon` THC) |
+| `children`   | Override the entire default layout                 |
+
+## Usage
+
+### Basic
+
+```svelte
+<script lang="ts">
+	import { EmptyState, Button, iconSearch } from "@marianmeres/stuic";
+</script>
+
+<EmptyState
+	icon={{ html: iconSearch() }}
+	title="No results found"
+	description="Try adjusting your search or filters."
+/>
+```
+
+### With CTA
+
+```svelte
+<EmptyState
+	icon={{ html: iconPlus() }}
+	title="No projects yet"
+	description="Create your first project to get started."
+>
+	{#snippet actions()}
+		<Button intent="primary">New project</Button>
+		<Button variant="ghost">Learn more</Button>
+	{/snippet}
+</EmptyState>
+```
+
+### Variants
+
+```svelte
+<!-- No box (default) — for use inside an already-framed area (table body, panel) -->
+<EmptyState variant="plain" title="Nothing here" />
+
+<!-- Bordered container -->
+<EmptyState variant="outline" title="Nothing here" />
+
+<!-- Dashed container — the "drop zone / placeholder" look -->
+<EmptyState variant="dashed" title="Nothing here" />
+```
+
+### Sizes
+
+```svelte
+<EmptyState size="sm" title="No comments" />
+<EmptyState size="md" title="No comments" />
+<EmptyState size="lg" title="No comments" />
+```
+
+### With DataTable
+
+`DataTable` already renders an `EmptyState` (titled with its `no_data` message) when it
+has no rows. Its `empty` snippet replaces that one, which is where an icon, a
+description and a CTA go:
+
+```svelte
+<DataTable {columns} {data}>
+	{#snippet empty()}
+		<EmptyState
+			icon={{ html: iconFile() }}
+			title="No documents"
+			description="Documents you upload will show up here."
+		>
+			{#snippet actions()}
+				<Button intent="primary">Upload</Button>
+			{/snippet}
+		</EmptyState>
+	{/snippet}
+</DataTable>
+```
+
+Swapping the whole table out is the other option — when the empty case should not look
+like a table at all (no header row, no pager):
+
+```svelte
+{#if !rows.length}
+	<EmptyState
+		icon={{ html: iconFile() }}
+		title="No documents"
+		description="Documents you upload will show up here."
+	>
+		{#snippet actions()}
+			<Button intent="primary">Upload</Button>
+		{/snippet}
+	</EmptyState>
+{:else}
+	<DataTable {rows} ... />
+{/if}
+```
+
+### Custom Styling
+
+```svelte
+<!-- Override the entire layout -->
+<EmptyState variant="dashed">
+	<img src="/illustrations/empty.svg" alt="" class="w-40" />
+	<p>Absolutely nothing.</p>
+</EmptyState>
+
+<!-- Override component tokens inline -->
+<EmptyState
+	title="Big icon"
+	icon={{ html: iconSearch() }}
+	style="--stuic-empty-state-icon-size-md: 5rem;"
+/>
+```
+
+## Accessibility
+
+The component renders a plain `<div>` with no implicit role. When an empty state
+replaces content dynamically (e.g. search results updating), pass `role="status"`
+so screen readers announce it:
+
+```svelte
+<EmptyState role="status" title="No results found" />
+```
+
+## CSS Variables
+
+### Component Tokens
+
+| Variable                                    | Default                          | Description                            |
+| ------------------------------------------- | -------------------------------- | -------------------------------------- |
+| `--stuic-empty-state-gap`                   | `0.5rem`                         | Gap between icon/title/description     |
+| `--stuic-empty-state-icon-text`             | `--stuic-color-muted-foreground` | Icon color                             |
+| `--stuic-empty-state-icon-opacity`          | `0.8`                            | Icon opacity                           |
+| `--stuic-empty-state-icon-margin-bottom`    | `0.25rem`                        | Extra space below the icon             |
+| `--stuic-empty-state-title-font-weight`     | `--font-weight-semibold`         | Title font weight                      |
+| `--stuic-empty-state-title-text`            | `--stuic-color-foreground`       | Title color                            |
+| `--stuic-empty-state-description-text`      | `--stuic-color-muted-foreground` | Description color                      |
+| `--stuic-empty-state-description-max-width` | `45ch`                           | Description line-length cap            |
+| `--stuic-empty-state-actions-gap`           | `0.5rem`                         | Gap between CTA buttons                |
+| `--stuic-empty-state-actions-margin-top`    | `1rem`                           | Space above the CTA row                |
+| `--stuic-empty-state-bg`                    | `transparent`                    | Background                             |
+| `--stuic-empty-state-border`                | `--stuic-color-border`           | Border color (outline/dashed variants) |
+| `--stuic-empty-state-border-width`          | `--stuic-border-width`           | Border width (outline/dashed variants) |
+| `--stuic-empty-state-radius`                | `--stuic-radius-container`       | Border radius (outline/dashed)         |
+
+### Size Tokens
+
+Each size (sm, md, lg) has corresponding tokens:
+
+- `--stuic-empty-state-padding-{size}`
+- `--stuic-empty-state-icon-size-{size}` (applied to any `svg` inside the icon area)
+- `--stuic-empty-state-title-font-size-{size}`
+- `--stuic-empty-state-description-font-size-{size}`
+
+## Data Attributes
+
+The component uses data attributes for styling:
+
+- `data-variant` - `"plain" | "outline" | "dashed"`
+- `data-size` - `"sm" | "md" | "lg"`

package/dist/components/EmptyState/index.css

@@ -0,0 +1,154 @@
+/* ============================================================================
+   EMPTY STATE COMPONENT TOKENS
+   Override globally: :root { --stuic-empty-state-icon-size-md: 4rem; }
+   Override locally:  <EmptyState style="--stuic-empty-state-gap: 1rem;">
+   ============================================================================ */
+
+/* prettier-ignore */
+:root {
+	--stuic-empty-state-gap: 0.5rem;
+
+	/* Size: sm */
+	--stuic-empty-state-padding-sm: 1.5rem;
+	--stuic-empty-state-icon-size-sm: 2rem;
+	--stuic-empty-state-title-font-size-sm: var(--text-base);
+	--stuic-empty-state-description-font-size-sm: var(--text-xs);
+
+	/* Size: md */
+	--stuic-empty-state-padding-md: 3rem;
+	--stuic-empty-state-icon-size-md: 2.5rem;
+	--stuic-empty-state-title-font-size-md: var(--text-lg);
+	--stuic-empty-state-description-font-size-md: var(--text-sm);
+
+	/* Size: lg */
+	--stuic-empty-state-padding-lg: 4rem;
+	--stuic-empty-state-icon-size-lg: 3rem;
+	--stuic-empty-state-title-font-size-lg: var(--text-xl);
+	--stuic-empty-state-description-font-size-lg: var(--text-base);
+
+	/* Icon */
+	--stuic-empty-state-icon-text: var(--stuic-color-muted-foreground);
+	--stuic-empty-state-icon-opacity: 0.8;
+	--stuic-empty-state-icon-margin-bottom: 0.25rem;
+
+	/* Typography */
+	--stuic-empty-state-title-font-weight: var(--font-weight-semibold);
+	--stuic-empty-state-title-text: var(--stuic-color-foreground);
+	--stuic-empty-state-description-text: var(--stuic-color-muted-foreground);
+	--stuic-empty-state-description-max-width: 45ch;
+
+	/* Actions */
+	--stuic-empty-state-actions-gap: 0.5rem;
+	--stuic-empty-state-actions-margin-top: 1rem;
+
+	/* Outline/dashed variants */
+	--stuic-empty-state-bg: transparent;
+	--stuic-empty-state-border: var(--stuic-color-border);
+}
+
+@layer components {
+	/* ============================================================================
+	   BASE STYLES
+	   ============================================================================ */
+
+	.stuic-empty-state {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		justify-content: center;
+		text-align: center;
+		width: 100%;
+		gap: var(--stuic-empty-state-gap);
+		background: var(--stuic-empty-state-bg);
+	}
+
+	/* ============================================================================
+	   SIZE VARIANTS
+	   Each size sets the scale via internal CSS vars consumed by the child areas.
+	   ============================================================================ */
+
+	.stuic-empty-state[data-size="sm"] {
+		padding: var(--stuic-empty-state-padding-sm);
+		--_icon-size: var(--stuic-empty-state-icon-size-sm);
+		--_title-font-size: var(--stuic-empty-state-title-font-size-sm);
+		--_description-font-size: var(--stuic-empty-state-description-font-size-sm);
+	}
+
+	.stuic-empty-state[data-size="md"] {
+		padding: var(--stuic-empty-state-padding-md);
+		--_icon-size: var(--stuic-empty-state-icon-size-md);
+		--_title-font-size: var(--stuic-empty-state-title-font-size-md);
+		--_description-font-size: var(--stuic-empty-state-description-font-size-md);
+	}
+
+	.stuic-empty-state[data-size="lg"] {
+		padding: var(--stuic-empty-state-padding-lg);
+		--_icon-size: var(--stuic-empty-state-icon-size-lg);
+		--_title-font-size: var(--stuic-empty-state-title-font-size-lg);
+		--_description-font-size: var(--stuic-empty-state-description-font-size-lg);
+	}
+
+	/* ============================================================================
+	   CONTAINER VARIANTS
+	   plain (default): no box. outline/dashed: bordered container.
+	   ============================================================================ */
+
+	.stuic-empty-state[data-variant="outline"],
+	.stuic-empty-state[data-variant="dashed"] {
+		border: var(--stuic-empty-state-border-width, var(--stuic-border-width)) solid
+			var(--stuic-empty-state-border);
+		border-radius: var(--stuic-empty-state-radius, var(--stuic-radius-container));
+	}
+
+	.stuic-empty-state[data-variant="dashed"] {
+		border-style: dashed;
+	}
+
+	/* ============================================================================
+	   ICON AREA
+	   ============================================================================ */
+
+	.stuic-empty-state-icon {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		color: var(--stuic-empty-state-icon-text);
+		opacity: var(--stuic-empty-state-icon-opacity);
+		margin-bottom: var(--stuic-empty-state-icon-margin-bottom);
+	}
+
+	/* Normalize any passed svg icon to the size preset (like DismissibleMessage) */
+	.stuic-empty-state-icon svg {
+		width: var(--_icon-size);
+		height: var(--_icon-size);
+	}
+
+	/* ============================================================================
+	   TITLE + DESCRIPTION
+	   ============================================================================ */
+
+	.stuic-empty-state-title {
+		font-size: var(--_title-font-size);
+		font-weight: var(--stuic-empty-state-title-font-weight);
+		color: var(--stuic-empty-state-title-text);
+	}
+
+	.stuic-empty-state-description {
+		font-size: var(--_description-font-size);
+		color: var(--stuic-empty-state-description-text);
+		max-width: var(--stuic-empty-state-description-max-width);
+	}
+
+	/* ============================================================================
+	   ACTIONS (CTA)
+	   ============================================================================ */
+
+	.stuic-empty-state-actions {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		justify-content: center;
+		gap: var(--stuic-empty-state-actions-gap);
+		margin-top: var(--stuic-empty-state-actions-margin-top);
+	}
+}

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

@@ -0,0 +1 @@
+export { default as EmptyState, type Props as EmptyStateProps, type EmptyStateVariant, type EmptyStateSize, } from "./EmptyState.svelte";

package/dist/components/EmptyState/index.js

@@ -0,0 +1 @@
+export { default as EmptyState, } from "./EmptyState.svelte";

package/dist/components/Input/FieldOptions.svelte

@@ -20,6 +20,7 @@
 		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";
@@ -36,6 +37,7 @@
 	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";
 
@@ -90,6 +92,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;
@@ -124,6 +138,10 @@
 			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}})",
@@ -214,6 +232,9 @@
 		renderOptionGroup = (s: string) => `${s}`.replaceAll("_", " "),
 		allowUnknown = false,
 		ordered = false,
+		chips = false,
+		classChip,
+		chipIntent,
 		showIconsCheckbox = true,
 		showIconsRadio = false,
 		searchPlaceholder,
@@ -229,8 +250,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 +626,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 +766,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,35 @@ 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.
+
 ### Customization Examples
 
 ```css