fancy-ui-svelte 0.9.0 → 0.10.0

package/dist/fancy-ui/command-menu/README.md

@@ -0,0 +1,176 @@
+# CommandMenu
+
+A modal search palette: a single search field over a flat vocabulary of `items`, filtered as you type, with grouped results, match highlighting, and full keyboard navigation through `aria-activedescendant` — focus never leaves the field. Portals to `document.body`, traps focus, dismisses on Escape and outside click, and locks the page's own scroll while open, the same plumbing `Dialog` uses.
+
+Data-driven rather than a compound: filtering is a decision about the whole `items` array at once, so there is one component to hand a list to, not a tree of subcomponents each re-deriving the same filter.
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { CommandMenu, type CommandItem } from "fancy-ui-svelte";
+
+	let open = $state(false);
+
+	const items: CommandItem[] = [
+		{ id: "button", label: "Button", group: "Core", meta: "Actions" },
+		{ id: "icon-button", label: "Icon Button", group: "Core", meta: "Actions" },
+		{ id: "rainbow-button", label: "Rainbow Button", group: "Fancy", meta: "Buttons" },
+		{ id: "settings", label: "Settings" },
+	];
+
+	function handleSelect(item: CommandItem) {
+		console.log("navigate to", item.id);
+	}
+</script>
+
+<button onclick={() => (open = true)}>Open command menu</button>
+
+<CommandMenu bind:open {items} onSelect={handleSelect} />
+```
+
+There is no built-in trigger or global keyboard shortcut — `open` is the whole interface. Wire a `keydown` listener yourself (⌘K, Ctrl+K, whatever suits the app) and flip `open`:
+
+```svelte
+<script lang="ts">
+	function handleKeydown(event: KeyboardEvent) {
+		if (event.key === "k" && (event.metaKey || event.ctrlKey)) {
+			event.preventDefault();
+			open = !open;
+		}
+	}
+</script>
+
+<svelte:window onkeydown={handleKeydown} />
+```
+
+### Grouped items
+
+Items with the same `group` string render under one uppercase heading, in the order that group name first appears in `items`. Items with no `group` at all render first, ungrouped:
+
+```svelte
+<CommandMenu
+	{open}
+	items={[
+		{ id: "search", label: "Search everything" },
+		{ id: "new-doc", label: "New document", group: "Create" },
+		{ id: "new-folder", label: "New folder", group: "Create" },
+		{ id: "profile", label: "Go to profile", group: "Navigate" },
+	]}
+/>
+```
+
+### Matching on more than the label
+
+`keywords` extends what the default filter matches against, without ever being shown:
+
+```svelte
+<CommandMenu
+	{open}
+	items={[{ id: "billing", label: "Billing", keywords: ["invoice", "plan", "payment"] }]}
+/>
+```
+
+### A custom filter
+
+Replaces the default entirely — `keywords` is then only meaningful if your own `filter` reads it:
+
+```svelte
+<CommandMenu
+	{open}
+	{items}
+	filter={(item, query) => item.label.toLowerCase().startsWith(query.toLowerCase())}
+/>
+```
+
+## Props
+
+| Prop            | Type                                            | Default          | Description                                                                       |
+| --------------- | ----------------------------------------------- | ---------------- | --------------------------------------------------------------------------------- |
+| `open`          | `boolean`                                       | `false`          | Whether the menu is open. Bindable.                                               |
+| `onOpenChange`  | `(open: boolean) => void`                       | —                | Fires whenever `open` changes — Escape, an outside click, or committing an item.  |
+| `items`         | `CommandItem[]`                                 | —                | The full, unfiltered vocabulary. Required.                                        |
+| `query`         | `string`                                        | `""`             | The current search text. Bindable. Reset every time the menu reopens — see below. |
+| `onQueryChange` | `(query: string) => void`                       | —                | Fires whenever `query` changes.                                                   |
+| `onSelect`      | `(item: CommandItem) => void`                   | —                | Called with the committed item, after that item's own `onSelect`.                 |
+| `placeholder`   | `string`                                        | `"Search..."`    | Placeholder for the search field.                                                 |
+| `emptyMessage`  | `string`                                        | `"No results"`   | Shown in place of the list when nothing matches.                                  |
+| `label`         | `string`                                        | `"Command menu"` | Accessible name — for the dialog and for the search field. See Accessibility.     |
+| `filter`        | `(item: CommandItem, query: string) => boolean` | see below        | Overrides the default filter entirely.                                            |
+| `class`         | `string`                                        | —                | Additional CSS classes for the panel.                                             |
+| `ref`           | `HTMLDivElement \| null`                        | `null`           | Bindable reference to the panel element.                                          |
+| `icon`          | `Snippet<[CommandItem]>`                        | —                | Rendered before each row's label, given that row's item. Treated as decorative.   |
+| `empty`         | `Snippet`                                       | —                | Rendered in place of the list when nothing matches, instead of `emptyMessage`.    |
+
+`CommandItem` is:
+
+```ts
+interface CommandItem {
+	id: string;
+	label: string;
+	/** Optional right-aligned secondary text — the category column in the mockup. */
+	meta?: string;
+	/** Optional group heading this item sits under. Items with no group render first, ungrouped. */
+	group?: string;
+	/** Extra terms the default filter matches against, alongside `label`. Never shown. */
+	keywords?: string[];
+	disabled?: boolean;
+	/** Called when this item is committed, before the component's own `onSelect`. */
+	onSelect?: () => void;
+}
+```
+
+The default filter is case- and **diacritic**-insensitive: it folds both the query and `label`/`keywords` through `normalize("NFD")` plus a combining-marks strip before comparing, so `"cafe"` matches an item labelled `"Café"`.
+
+## Accessibility
+
+- `role="dialog"` with `aria-modal="true"` and `aria-label={label}` (default `"Command menu"`). Focus moves into the search field on open and returns to whatever had focus before it opened, on close — Tab is trapped inside the panel.
+- The search field is `role="combobox"` with `aria-expanded="true"` (the result list is always visible while the dialog is open, so this never toggles), `aria-controls` pointing at the list, and `aria-activedescendant` pointing at the active `role="option"` row. The list is `role="listbox"`. **Focus never leaves the field** — arrow keys, Home, End and Enter all act on the highlighted row without moving real DOM focus onto it; rows carry `tabindex="-1"` and are not reachable by Tab.
+- The search field's accessible name is the same `label` prop as the dialog's, reused rather than introducing a second, undocumented prop for it — there is no visible `<label>` element in this layout for a `<label for>` to attach to instead.
+- The matched substring inside each row's label is a real `<mark>` element (never `{@html}`) — the canonical element for "a run of text highlighted for its relevance to a search," per its HTML definition. It is deliberately **not** `aria-hidden`: hiding it would remove exactly the text it wraps from the row's accessible name, and it is real content, not decoration. A minority of screen readers additionally announce entering/leaving a `<mark>` region; that extra signal is treated as useful (it says _why_ a row matched), not suppressed.
+- **Group headings are decorative**, `role="presentation"`, not associated with their rows through `aria-labelledby` or a nested `role="group"`. This mirrors `Combobox`/`Select`'s own flat-listbox pattern in this library, and is a deliberate, documented trade-off: cross-screen-reader support for grouped options inside a flat `listbox`/`option` pattern is inconsistent, so a plain visual heading over an otherwise-flat option list is the more reliably accessible choice. Each row's own text (including `meta`) is still read in full regardless of grouping.
+- `icon` is rendered inside an `aria-hidden="true"` wrapper — it is assumed decorative. If your icon carries meaning nothing else on the row conveys, put that meaning in `label` (or `keywords`) too.
+- Result-count changes are announced through a polite, always-mounted `role="status"` live region that reports **only the count** ("3 results"), never the row contents. A nonzero count waits for the query to sit still for 300ms before announcing, not after every keystroke — announcing on every character would turn fast typing into a screen reader narrating a number many times a second. A drop to **zero** is the one exception: it announces immediately, because the empty state is already visible on screen at that instant, and a debounced zero would leave the region reporting a stale nonzero count while the list a screen reader user cannot see already reads empty. See Implementation Notes for the exact mechanism. The region clears immediately (not debounced) the instant the menu closes.
+- A disabled item (`disabled: true`) is skipped as part of a block by arrow/Home/End navigation — it can never become the active row — and a click or Enter on it does nothing. The native `disabled` attribute on its `<button>` is not trusted alone as the guard (a synthetic click can walk past it), so `commitItem` checks `item.disabled` explicitly too.
+
+## Theming
+
+| Custom property   | Read by                             | Fallback                                                                                |
+| ----------------- | ----------------------------------- | --------------------------------------------------------------------------------------- |
+| `--ft-nav-accent` | The `<mark>` highlight's text color | `var(--ft-accent, light-dark(oklch(0.5432 0.2528 300.22), oklch(0.604 0.2606 301.75)))` |
+
+`--ft-nav-accent` is declared exactly once, with the fallback above, on the **portalled panel element itself** — the same `<div>` that carries `use:portal` — and read below that declaration on the same element. `--ft-accent` itself is never redeclared here — only read through the fallback — so a value a consumer sets higher up the tree is never shadowed.
+
+That "portalled" part is not incidental, and it changes where a consumer is allowed to set `--ft-accent`. `use:portal` moves the panel to `document.body` before it ever paints, so at render time it is no longer a DOM descendant of wherever `<CommandMenu>` was written in your markup — it inherits nothing from that spot, custom properties included. A wrapper placed around the `<CommandMenu>` element itself therefore does **nothing**:
+
+```svelte
+<!-- Has no effect: the dialog is not a descendant of this div by the time it renders. -->
+<div style="--ft-accent: oklch(0.6 0.2 290)">
+	<CommandMenu {open} {items} />
+</div>
+```
+
+`--ft-accent` has to be set at or above `document.body` — typically `:root` in your global stylesheet — to reach a portalled surface:
+
+```css
+:root {
+	--ft-accent: oklch(0.6 0.2 290);
+}
+```
+
+The failure mode if you get this wrong is quiet, not loud: `color` (what `--ft-nav-accent` feeds the `<mark>` highlight through) is an inherited property, so an unresolved `var(--ft-nav-accent)` does not fall back to some default color or produce a visible error — it computes to whatever color the surrounding text already has, which is the panel's own foreground text color. The highlight looks like it vanished; nothing in the console says why. If a retint you set on a wrapper isn't reaching the palette, that wrapper is the first thing to check.
+
+Everything else — the panel (`bg-popover`/`text-popover-foreground`/`border-border`), the active row (`bg-accent`/`text-accent-foreground`), muted text (`text-muted-foreground`) — reads the app's own semantic tokens, with no component-local overrides.
+
+## Implementation Notes
+
+- **The query and active row reset on every reopen — except the very first mount.** A caller that mounts the menu already `open` with a prefilled `query` is seeding it on purpose, and that first paint is honored as-is. Every transition into `open = true` _after_ that first one resets `query` to `""` and re-activates the first row — a stale query or highlight surviving from the session before is a bug the caller has no way to work around, so it is not left as a possibility. If you need a menu that always starts pre-filtered, pass `query` as a plain (non-bound) prop rather than `bind:query` — the reopening behavior does not touch it if nothing ever writes it back.
+- **That reset effect has to run its whole body inside `untrack(...)`, and this is not optional.** Its only intended dependency is `open`. But it also calls `listbox.moveToEdge("first")`, which reads `query` transitively through the `count`/`enabled` callbacks passed to `createListbox` — Svelte's dependency tracking follows a read through any function call made during an effect's synchronous execution, not just the names written directly inside the `$effect(...)` block. Without `untrack`, that transitive read makes `query` a real dependency of this effect, and the very next line writes `query` — an effect reading and writing the same state, which Svelte throws `effect_update_depth_exceeded` for the moment anything (a keystroke) writes `query` again from outside. Reproducible in one line: render the menu open, type one character, watch it throw.
+- **The listbox's index space is display order, not `items`' own filtered order.** `computeDisplayItems` reorders the filtered items into ungrouped-first-then-grouped before anything else touches them, and that reordered array — not `items.filter(...)`'s own order — is what `optionId`, `aria-activedescendant`, and the listbox core's `count`/`enabled` all index into. Skipping this step (indexing by `items`' own order while rendering in display order) desyncs "first"/"next" from what is visually first/next the moment an ungrouped item doesn't already sit at the front of `items`.
+- **`announcedCount` starts at `null`, not `0`.** The debounce means there is a real window, right after opening or after a keystroke, where nothing has been announced yet — and the live region has to stay silent through it, not say "0 results" for up to 300ms while a non-empty list is still being counted. `resultsMessage` folds `null` to `""` before the "1 result"/"N results" branching.
+- **A drop to zero bypasses the debounce and announces synchronously; every nonzero count still waits.** The two paths are deliberately asymmetric, not an oversight: emptiness is the one state where lagging behind the visible screen actively misleads (the region would report results the list has already stopped showing), while a nonzero count is never a contradiction of what's on screen, only a preview of it, so it keeps the debounce that protects against narrating every keystroke.
+- **Highlighting locates the match in the _original_ label, not the folded one, and that translation has to be counted in the same units the string search uses.** Folding for diacritic-insensitive search (`normalize("NFD")` plus a combining-marks strip) changes string length before the marks are stripped back off, so the position a match is found at inside the folded string is not automatically a safe index into the real label. `match.ts`'s `getMatchRange` builds an explicit offset map while folding and translates the found range back through it — proven against a label like `"Café Society"`, where searching the unaccented query `"afe soc"` must highlight the real `"afé Soc"`, not an off-by-one span. The map is built **per UTF-16 code unit**, not per codepoint: an astral character (outside the Basic Multilingual Plane — an emoji, say) is a single codepoint but two code units, the same width `String.prototype.indexOf` — what actually locates the match — counts in. A map built one entry per codepoint falls one entry short of `folded` for every astral character, and a lookup past its end reads `undefined`; `getMatchRange` guards that and returns `null` rather than a range with an `undefined` bound, since `label.slice(undefined, …)` silently coerces to `slice(0, …)` and would render the whole label twice instead of throwing where the bug could be seen.
+- **Highlighting and filtering are independent, by construction.** `getMatchRange` always searches for a literal, folded substring of `label` on its own, regardless of what logic actually selected the item — so when a custom `filter` matches for an unrelated reason (a `keywords` hit, fuzzy logic), and there is no literal substring of `label` to point at, the row renders its label plain rather than fabricating a highlight the match had nothing to do with.
+- **The debounced announcement is an `$effect` plus its own cleanup, not a hand-rolled timer variable.** Every time the filtered count (or `open`) changes, the effect reschedules a 300ms timer and Svelte runs the _previous_ run's cleanup — which clears that pending timer — before the new one starts. A burst of keystrokes keeps pushing the announcement out rather than stacking several up, and whatever count is in scope when a timer finally fires uninterrupted is the one that gets announced.
+- **`row?.scrollIntoView?.(...)` is guarded on the method itself, not just the element**, because `Element.prototype.scrollIntoView` is not implemented in jsdom — calling it unconditionally would throw in every test that arrows through the list, even though real browsers implement it fine. The active row is looked up by id under the panel's own list element (`listRef.querySelector(...)`), the same pattern `Select.svelte`'s `handleActiveChange` uses.
+- **Filtering functions are called fresh, not read from the memoized `filteredItems`, everywhere a write to `query` might have just happened in the same pass** (`handleInput`, the listbox's own `count`/`enabled` callbacks, the reopen-reset effect) — reading a `$derived` in the same synchronous call that just wrote its own dependency risks seeing the pre-write value. This is the same discipline `combobox/Combobox.svelte` documents for its own `computeFilteredOptions`.

package/dist/fancy-ui/command-menu/index.d.ts

@@ -0,0 +1,2 @@
+import CommandMenu, { type CommandMenuProps, type CommandItem } from "./CommandMenu.svelte";
+export { CommandMenu, type CommandMenuProps, type CommandItem };

package/dist/fancy-ui/command-menu/index.js

@@ -0,0 +1,2 @@
+import CommandMenu, {} from "./CommandMenu.svelte";
+export { CommandMenu };

package/dist/fancy-ui/command-menu/match.d.ts

@@ -0,0 +1,19 @@
+import type { CommandItem } from "./types.js";
+/** Case- and diacritic-insensitive substring match over `label` plus `keywords`. An empty query matches everything. */
+export declare function defaultFilter(item: CommandItem, query: string): boolean;
+export interface MatchRange {
+    start: number;
+    end: number;
+}
+/**
+ * Finds the first case- and diacritic-insensitive occurrence of `query`
+ * inside `label`, returning the span **in `label`'s own original
+ * characters** — not in the folded form used to search.
+ *
+ * Returns `null` when `query` is empty or not literally present in the
+ * folded label — including when a custom `filter` matched the item for a
+ * reason unrelated to a literal substring of `label` (a keyword, a fuzzy
+ * match). Callers render the label plain in that case rather than
+ * fabricating a highlighted span the match had nothing to do with.
+ */
+export declare function getMatchRange(label: string, query: string): MatchRange | null;

package/dist/fancy-ui/command-menu/match.js

@@ -0,0 +1,124 @@
+// Pure text-matching helpers: the default filter (case- and
+// diacritic-insensitive substring match over `label` plus `keywords`) and
+// `getMatchRange`, which locates the matched span for highlighting.
+//
+// The two are independent by construction, the same relationship
+// `combobox/match.ts` draws between its own filter and `getMatchRange`:
+// highlighting always looks for a literal, folded substring of `label`
+// itself, regardless of what logic actually selected the item. A consumer
+// `filter` can match on `keywords`, fuzzy logic, anything — when none of
+// that produces a literal substring of `label`, there is nothing honest to
+// highlight, so the row renders its plain, unhighlighted label instead of a
+// span that would misrepresent why it matched.
+// Built from an escaped-codepoint string rather than a regex literal on
+// purpose — a raw combining mark sitting directly in this file's source
+// would attach itself to whatever precedes it on screen in most editors and
+// terminals, rendering unreadable.
+const COMBINING_MARKS = new RegExp("[\\u0300-\\u036f]", "g");
+/** Case- and diacritic-folded form of a string, for matching only — never rendered. */
+function fold(text) {
+    return text.normalize("NFD").replace(COMBINING_MARKS, "").toLowerCase();
+}
+/** Case- and diacritic-insensitive substring match over `label` plus `keywords`. An empty query matches everything. */
+export function defaultFilter(item, query) {
+    if (!query)
+        return true;
+    const needle = fold(query);
+    if (fold(item.label).includes(needle))
+        return true;
+    return item.keywords?.some((keyword) => fold(keyword).includes(needle)) ?? false;
+}
+/**
+ * Builds the folded (case/diacritic-stripped) form of `text` alongside a map
+ * from each **UTF-16 code unit** of that folded form back to the UTF-16
+ * offset it came from in `text`. `map` must be indexed exactly the way
+ * `String.prototype.indexOf` counts — one entry per code unit of `folded`,
+ * not one per codepoint — because `getMatchRange` below searches with
+ * `indexOf` and reads `map` at the index it returns; if the two used
+ * different units, every index past a surrogate pair would be off by one.
+ *
+ * A precomposed accented letter ("é") decomposes under NFD into a base
+ * letter plus one or more combining marks; the marks are stripped and
+ * contribute no output units, so only the base letter survives — still
+ * pointing at the original character's own offset. An astral character
+ * (outside the Basic Multilingual Plane — an emoji, say) is different:
+ * `fold()` leaves it untouched, but it is still a surrogate pair, two UTF-16
+ * code units long, in both `text` and `folded`. Pushing one `map` entry for
+ * it (one per *codepoint*, matching the `for...of` iteration below, which
+ * always yields one codepoint per pass) would silently under-count by one
+ * for every such character — `map.length` would fall behind `folded.length`,
+ * and every match found after it would read the wrong entry. The inner loop
+ * pushes `outChar.length` entries instead, one per code unit `outChar`
+ * actually contributes to `folded`, all pointing at the same source offset.
+ *
+ * This is what lets a match found in the folded string be translated back
+ * to a span of the real, accented label: folding finds the right
+ * *characters*, but it can shift *positions* (an NFD decomposition is
+ * longer than its precomposed source, before the marks are stripped back
+ * off), so a raw folded-string index is not a safe index into the original
+ * label on its own — this map is the correction.
+ */
+function foldWithMap(text) {
+    let folded = "";
+    const map = [];
+    let offset = 0;
+    // `for...of` walks by Unicode codepoint, not UTF-16 code unit, so a
+    // surrogate pair (an astral character) is one iteration, not two —
+    // `char.length` below is then 1 or 2 accordingly, which is what keeps
+    // `offset` a valid UTF-16 index into `text` for slicing later.
+    for (const char of text) {
+        const strippedChar = fold(char);
+        for (const outChar of strippedChar) {
+            folded += outChar;
+            for (let i = 0; i < outChar.length; i++) {
+                map.push(offset);
+            }
+        }
+        offset += char.length;
+    }
+    return { folded, map };
+}
+/**
+ * Finds the first case- and diacritic-insensitive occurrence of `query`
+ * inside `label`, returning the span **in `label`'s own original
+ * characters** — not in the folded form used to search.
+ *
+ * Returns `null` when `query` is empty or not literally present in the
+ * folded label — including when a custom `filter` matched the item for a
+ * reason unrelated to a literal substring of `label` (a keyword, a fuzzy
+ * match). Callers render the label plain in that case rather than
+ * fabricating a highlighted span the match had nothing to do with.
+ */
+export function getMatchRange(label, query) {
+    if (!query)
+        return null;
+    const foldedQuery = fold(query);
+    if (!foldedQuery)
+        return null;
+    const { folded, map } = foldWithMap(label);
+    const index = folded.indexOf(foldedQuery);
+    if (index === -1)
+        return null;
+    const start = map[index];
+    // `map[index]` types as `number`, not `number | undefined` — this
+    // project's tsconfig has `strict` but not `noUncheckedIndexedAccess`, so
+    // the type system does not actually back that up here. Only
+    // `foldWithMap`'s own invariant does (one map entry per UTF-16 code unit,
+    // matching `folded` exactly), and a future edit to that function could
+    // break it silently. Guarded anyway: a range with an `undefined` bound is
+    // worse than no highlight — `CommandMenu.svelte`'s
+    // `label.slice(range.start, range.end)` would see `slice(undefined, …)`,
+    // which JS silently coerces to `slice(0, …)` instead of throwing, and the
+    // row would render its entire label twice, once plain and once inside
+    // `<mark>`.
+    if (start === undefined)
+        return null;
+    // The offset one folded-character past the match's own last character —
+    // `map[that index]` is where the *next* real character starts, which is
+    // exactly the exclusive end this range needs. Past the end of `map`
+    // (the match runs to the very end of the folded string) there is no
+    // next entry to read, so the end is `label.length` instead.
+    const endFoldedIndex = index + foldedQuery.length;
+    const end = endFoldedIndex < map.length ? map[endFoldedIndex] : label.length;
+    return { start, end };
+}

package/dist/fancy-ui/command-menu/types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * One selectable row. `id` is what a row is keyed by; `label` is what a
+ * person reads and types against. `group` and `meta` are purely
+ * presentational — CommandMenu never reorders or sorts `items` itself, it
+ * only filters and buckets them by `group` for display.
+ */
+export interface CommandItem {
+    id: string;
+    label: string;
+    /** Optional right-aligned secondary text — the category column in the mockup. */
+    meta?: string;
+    /** Optional group heading this item sits under. Items with no group render first, ungrouped. */
+    group?: string;
+    /** Extra terms the default filter matches against, alongside `label`. Never shown. */
+    keywords?: string[];
+    disabled?: boolean;
+    /** Called when this item is committed — Enter on the active row, or a click. Runs before the component's own `onSelect`. */
+    onSelect?: () => void;
+}

package/dist/fancy-ui/command-menu/types.js

@@ -0,0 +1 @@
+export {};

package/dist/fancy-ui/composer/Composer.svelte

@@ -0,0 +1,241 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { AttachmentData } from "../_internals/ai-types.js";
+
+	/**
+	 * Props for Composer
+	 */
+	export interface ComposerProps {
+		/** The draft text, bindable. Cleared by a successful submit. */
+		value?: string;
+		/** Files riding along with the draft, bindable. The consumer owns uploading them. */
+		attachments?: AttachmentData[];
+		/** Blocks typing, sending, and attaching. */
+		disabled?: boolean;
+		/** A response is arriving: the send button becomes a stop button. */
+		streaming?: boolean;
+		/** Placeholder for the default input. Ignored once `children` replaces the composition. */
+		placeholder?: string;
+		/** Called with the trimmed draft and a snapshot of the attachments. */
+		onSubmit?: (payload: { text: string; attachments: AttachmentData[] }) => void;
+		/** Called when the stop button is pressed while streaming. */
+		onStop?: () => void;
+		/** Called with the files handed to `addFiles`. Upload them, then push onto `attachments`. */
+		onAttach?: (files: File[]) => void;
+		/** Replaces the default input-and-send-row composition entirely. */
+		children?: Snippet;
+		/** An overlay covering the composer — a voice panel, a drop target, a confirmation. */
+		accessory?: Snippet;
+		/** Additional CSS classes */
+		class?: string;
+		/** The form element, bindable. */
+		ref?: HTMLFormElement | null;
+	}
+</script>
+
+<script lang="ts">
+	import { setContext, tick } from "svelte";
+	import { cn } from "../../utils.js";
+	import { findTokenStart } from "./caret.js";
+	import ComposerInput from "./ComposerInput.svelte";
+	import ComposerSubmit from "./ComposerSubmit.svelte";
+	import { COMPOSER_CONTEXT_KEY, type ComposerContext } from "./types.js";
+
+	let {
+		value = $bindable(""),
+		attachments = $bindable([]),
+		disabled = false,
+		streaming = false,
+		placeholder,
+		onSubmit,
+		onStop,
+		onAttach,
+		children,
+		accessory,
+		class: className,
+		ref = $bindable(null),
+	}: ComposerProps = $props();
+
+	// Written by ComposerInput through the context, read by insertText's caret
+	// arithmetic. A composer with no input part keeps it null and falls back to
+	// appending at the end of the draft.
+	let textareaEl = $state<HTMLTextAreaElement | null>(null);
+
+	function submit() {
+		// A composer that is off or already busy sends nothing, whatever the draft
+		// says — the send button is disabled in both states, but Enter and a
+		// programmatic `submit()` reach here too.
+		if (disabled || streaming) return;
+		const text = value.trim();
+		if (text === "" && attachments.length === 0) return;
+		// With nobody listening there is nowhere for the draft to go, and clearing
+		// it would throw away text the reader has no way of getting back.
+		if (!onSubmit) return;
+		// A copy, so a consumer stashing the payload does not end up holding the
+		// live list it is about to mutate.
+		onSubmit({ text, attachments: [...attachments] });
+		// The text is ours to clear; the attachments belong to the consumer, who
+		// alone knows whether an upload is still in flight.
+		value = "";
+	}
+
+	function stop() {
+		if (!streaming) return;
+		onStop?.();
+	}
+
+	function setValue(next: string) {
+		value = next;
+	}
+
+	function insertText(text: string, replaceTriggerToken = false) {
+		// A composer that is off or already busy takes no dictation either — the
+		// textarea is readonly in both states, and a menu writing through the
+		// context would be the one way around that.
+		if (disabled || streaming) return;
+		const current = value;
+		const rawEnd = textareaEl?.selectionEnd;
+		const end = typeof rawEnd === "number" ? rawEnd : current.length;
+		const rawStart = textareaEl?.selectionStart;
+		const selectionStart = typeof rawStart === "number" ? Math.min(rawStart, end) : end;
+
+		// The menus' own definition of a token, not a second one that could drift
+		// from it: what a menu matched is exactly what a completion overwrites.
+		const trigger = replaceTriggerToken ? findTokenStart(current, end) : -1;
+		const start = trigger >= 0 ? trigger : selectionStart;
+		const trailing = current.slice(end);
+
+		// Completing a token leaves the caret ready for the next word; a plain
+		// insert splices exactly what it was handed, and nothing more.
+		const needsSpace = trigger >= 0 && !/\s$/.test(text) && !/^\s/.test(trailing);
+		const insertion = needsSpace ? `${text} ` : text;
+		const caret = start + insertion.length;
+
+		value = `${current.slice(0, start)}${insertion}${trailing}`;
+
+		const el = textareaEl;
+		if (!el) return;
+		// The caret can only be placed once the controlled value has reached the
+		// DOM, so it waits a tick. Focus comes back with it: the insertion was
+		// almost certainly triggered from a menu that stole it.
+		void tick().then(() => {
+			if (!el.isConnected) return;
+			el.focus();
+			el.setSelectionRange(caret, caret);
+		});
+	}
+
+	function addFiles(files: File[]) {
+		if (disabled || files.length === 0) return;
+		onAttach?.(files);
+	}
+
+	function removeAttachment(id: string) {
+		attachments = attachments.filter((attachment) => attachment.id !== id);
+	}
+
+	const context: ComposerContext = {
+		value: {
+			get current() {
+				return value;
+			},
+		},
+		attachments: {
+			get current() {
+				return attachments;
+			},
+		},
+		get disabled() {
+			return disabled;
+		},
+		get streaming() {
+			return streaming;
+		},
+		get stoppable() {
+			return typeof onStop === "function";
+		},
+		// Declared read-only on ComposerContext so no other part writes it; the
+		// setter exists for ComposerInput alone, which registers its element here
+		// on mount. See the note at the top of types.ts.
+		textareaRef: {
+			get current() {
+				return textareaEl;
+			},
+			set current(next: HTMLTextAreaElement | null) {
+				textareaEl = next;
+			},
+		},
+		submit,
+		stop,
+		setValue,
+		insertText,
+		addFiles,
+		removeAttachment,
+	};
+
+	setContext(COMPOSER_CONTEXT_KEY, context);
+
+	function handleSubmit(event: SubmitEvent) {
+		// Nothing here navigates: the draft leaves through onSubmit.
+		event.preventDefault();
+		submit();
+	}
+</script>
+
+<form
+	bind:this={ref}
+	class={cn("ft-composer relative flex w-full flex-col border p-2", className)}
+	class:ft-composer-disabled={disabled}
+	data-streaming={streaming ? "" : undefined}
+	onsubmit={handleSubmit}
+>
+	{#if children}
+		{@render children()}
+	{:else}
+		<ComposerInput {placeholder} />
+		<div class="mt-2 flex items-center gap-2">
+			<div class="flex-1"></div>
+			<ComposerSubmit />
+		</div>
+	{/if}
+
+	{#if accessory}
+		<div class="ft-composer-accessory absolute inset-0 z-10">
+			{@render accessory()}
+		</div>
+	{/if}
+</form>
+
+<style>
+	/*
+	 * The surface is a form, not a card: it reads as one input the whole row of
+	 * controls lives inside, which is why the focus ring belongs to the container
+	 * rather than to the textarea buried in it.
+	 */
+	.ft-composer {
+		border-radius: var(--ft-composer-radius, 0.75rem);
+		border-color: var(--ft-composer-border, color-mix(in oklab, currentColor 14%, transparent));
+		background: var(--ft-composer-bg, color-mix(in oklab, currentColor 4%, transparent));
+	}
+
+	.ft-composer:focus-within {
+		border-color: var(
+			--ft-composer-border-focus,
+			color-mix(in oklab, currentColor 32%, transparent)
+		);
+		box-shadow: 0 0 0 1px
+			var(--ft-composer-ring, color-mix(in oklab, currentColor 22%, transparent));
+	}
+
+	.ft-composer-disabled {
+		opacity: var(--ft-composer-disabled-opacity, 0.6);
+	}
+
+	@media (prefers-reduced-motion: no-preference) {
+		.ft-composer {
+			transition:
+				border-color 150ms ease,
+				box-shadow 150ms ease;
+		}
+	}
+</style>

package/dist/fancy-ui/composer/Composer.svelte.d.ts

@@ -0,0 +1,37 @@
+import type { Snippet } from "svelte";
+import type { AttachmentData } from "../_internals/ai-types.js";
+/**
+ * Props for Composer
+ */
+export interface ComposerProps {
+    /** The draft text, bindable. Cleared by a successful submit. */
+    value?: string;
+    /** Files riding along with the draft, bindable. The consumer owns uploading them. */
+    attachments?: AttachmentData[];
+    /** Blocks typing, sending, and attaching. */
+    disabled?: boolean;
+    /** A response is arriving: the send button becomes a stop button. */
+    streaming?: boolean;
+    /** Placeholder for the default input. Ignored once `children` replaces the composition. */
+    placeholder?: string;
+    /** Called with the trimmed draft and a snapshot of the attachments. */
+    onSubmit?: (payload: {
+        text: string;
+        attachments: AttachmentData[];
+    }) => void;
+    /** Called when the stop button is pressed while streaming. */
+    onStop?: () => void;
+    /** Called with the files handed to `addFiles`. Upload them, then push onto `attachments`. */
+    onAttach?: (files: File[]) => void;
+    /** Replaces the default input-and-send-row composition entirely. */
+    children?: Snippet;
+    /** An overlay covering the composer — a voice panel, a drop target, a confirmation. */
+    accessory?: Snippet;
+    /** Additional CSS classes */
+    class?: string;
+    /** The form element, bindable. */
+    ref?: HTMLFormElement | null;
+}
+declare const Composer: import("svelte").Component<ComposerProps, {}, "ref" | "value" | "attachments">;
+type Composer = ReturnType<typeof Composer>;
+export default Composer;

package/dist/fancy-ui/composer/Composer.test.d.ts

@@ -0,0 +1 @@
+export {};