staffa 0.20.0 → 0.22.1

package/skill/SKILL.md

@@ -254,6 +254,16 @@ S.iconButton({ icon: trash2, tooltip: "Delete" });   // says "Delete" on hover,
 
 A tooltip appears only where one is asked for; on an icon button, a string `tooltip` doubles as the `ariaLabel` when that is left out, so naming a glyph takes one option rather than two. A `key` is appended to whatever the tip says (`tooltip: false` keeps even that quiet), and — unlike a tooltip on a plain disabled `<button>`, which the browser gives no hover events — these show while disabled, which is where a tooltip earns its keep.
 
+`S.textline` and `S.textarea` take a `prefix` and a `suffix` slot that put content *inside* the control — a search glyph, a unit, a clear or send button. The control's text keeps clear of whatever they hold, and on a textarea they ride the bottom edge, which is where a send button belongs:
+
+```ts
+S.textline({ placeholder: "Search…", prefix: search, suffix: () => S.iconButton({ icon: x, tooltip: "Clear" }) });
+S.textarea({ placeholder: "Message…", bind: A.ref($chat, "text"),
+  suffix: () => S.iconButton({ icon: send, tooltip: "Send", click: post }) });
+```
+
+A plain glyph there lets the click through to the field it decorates; a button or a link takes it. Tell the field how tall to be (`attrs: "h:20rem"`) and the textarea fills it, insets and all — a composer that fills its panel needs nothing else.
+
 `src/index.ts` is the authoritative list of exports.
 
 ### Keyboard shortcuts
@@ -408,6 +418,15 @@ A combobox with type-ahead filtering. Supports single or multi-select (chips),
 optional free-text entry, and full keyboard control (arrows, enter, escape,
 backspace-to-remove). Implements the ARIA combobox/listbox pattern.
 
+## [matchWords](matchWords.md) · function
+
+The default type-ahead test: every whitespace-separated term of the query has
+to match the label from a word start on, and no two terms may claim the same
+word. Order doesn't matter, so "se pal" finds "Palette search" just as
+"pal se" does — but "ette" finds nothing, as you type the beginnings of
+words. A term may run past its word's end ("typescript" finds "TypeScript",
+"c++" finds "C++"), so typing a label out in full always finds it.
+
 ## [AutocompleteOptions](AutocompleteOptions.md) · interface
 
 Options for `autocomplete`.
@@ -803,6 +822,13 @@ autocomplete, ...). Every field lays out the same way — optional label,
 control, optional help/error below — which is what lets `form` align
 groups of them.
 
+## [InsetOptions](InsetOptions.md) · interface
+
+Options for a field that can carry content *inside* its control box — an
+icon against the leading edge, a button against the trailing one. Added by
+("./textline").textline and
+("./textarea").textarea.
+
 ## [ContentOptions](ContentOptions.md) · interface
 
 Options for components that wrap a single block of caller-provided content,

package/skill/TextareaOptions.md

@@ -28,13 +28,18 @@ Visible number of text rows. Defaults to `4`. Ignored when `autoGrow` is enabled
 
 ### textareaOptions.resize · member
 
-Whether the textarea may be resized by the user. Defaults to `"vertical"`. Ignored when `autoGrow` is enabled.
+Whether the textarea may be resized by the user. Defaults to `"vertical"`,
+or to `"none"` when a | suffix is given — the
+resize grip and the inset both want the bottom-right corner. Ignored when
+`autoGrow` is enabled.
 
 **Type:** `"none" | "vertical" | "horizontal" | "both"`
 
 ### textareaOptions.autoGrow · member
 
-Auto-grow the textarea to fit its content. Defaults to `true`.
+Auto-grow the textarea to fit its content. Defaults to `true`. Ignored when
+the field is told how tall to be (| attrs
+`"h:20rem"`), as that height wins over the one the text asks for.
 
 **Type:** `boolean`
 

package/skill/autocomplete.md

@@ -4,6 +4,10 @@ A combobox with type-ahead filtering. Supports single or multi-select (chips),
 optional free-text entry, and full keyboard control (arrows, enter, escape,
 backspace-to-remove). Implements the ARIA combobox/listbox pattern.
 
+What you type is matched against the start of the label's words, a term at a
+time and in any order — "pal se" finds "Palette search" — see
+`matchWords`, or `AutocompleteOptions.match` to filter your own way.
+
 The suggestion list is portalled to `document.body`, so a dialog or a
 scrolling column can neither clip it nor grow a scrollbar around it. It hangs
 off whichever side of the field has the room, and follows it as things move.

package/skill/dialog.md

@@ -5,8 +5,9 @@ that fades in and out. Returns a `Promise<void>` that resolves when the dialog
 closes. Lifecycle is also tied to the parent reactive scope — when that scope
 is cleaned up the dialog disappears and the promise resolves.
 
-Multiple dialogs stack correctly: each new pair (backdrop + dialog) has a
-higher z-index, while older dialogs are pushed behind their covering backdrop.
+Multiple dialogs stack: each new pair (backdrop + dialog) gets a higher
+z-index than the one it covers, while older dialogs are pushed behind their
+covering backdrop.
 
 **Signature:** `(opts: DialogOptions) => Promise<void>`
 

package/skill/matchWords.md

@@ -0,0 +1,17 @@
+## matchWords · function
+
+The default type-ahead test: every whitespace-separated term of the query has
+to match the label from a word start on, and no two terms may claim the same
+word. Order doesn't matter, so "se pal" finds "Palette search" just as
+"pal se" does — but "ette" finds nothing, as you type the beginnings of
+words. A term may run past its word's end ("typescript" finds "TypeScript",
+"c++" finds "C++"), so typing a label out in full always finds it.
+
+Pass it to `AutocompleteOptions.match` to compose with it.
+
+**Signature:** `(label: string, query: string) => boolean`
+
+**Parameters:**
+
+- `label: string`
+- `query: string`

package/skill/textarea.md

@@ -3,6 +3,11 @@
 A multi-line text input. Shares the field chrome and styling of
 `textline`.
 
+It sizes itself to its text by default. Give the *field* a height instead
+(| attrs `"h:20rem"`, or `"h:100%"` inside a column
+that has one) and the textarea fills it, whatever else the field holds — a
+label, help text, a `prefix`/`suffix` inset.
+
 **Signature:** `(opts?: TextareaOptions) => void`
 
 **Parameters:**
@@ -14,4 +19,17 @@ A multi-line text input. Shares the field chrome and styling of
 ```ts
 const $user = A.proxy({bio: ""});
 S.textarea({ label: "Bio", bind: A.ref($user, "bio") });
+
+// A chat box: the send button sits in the bottom-right corner, inside the field.
+const $chat = A.proxy({text: ""});
+S.textarea({
+  placeholder: "Message…",
+  bind: A.ref($chat, "text"),
+  suffix: () => S.iconButton({ icon: send, tooltip: "Send", click: () => post($chat.text) }),
+});
+
+// Told how tall to be, the textarea fills the field instead of growing with
+// its text — `h:100%` in a column that has a height makes a composer that
+// fills whatever room it is given.
+S.textarea({ label: "Notes", attrs: "h:20rem", bind: A.ref($chat, "text") });
 ```

package/skill/textline.md

@@ -15,4 +15,7 @@ chrome (label, control, help/error), so it aligns cleanly inside a `form`.
 ```ts
 const $user = A.proxy({email: "test@example.com"});
 S.textline({ label: "Email", type: "email", required: true, bind: A.ref($user, "email") });
+
+// Content inside the field: a glyph against its left edge, a button against its right.
+S.textline({ placeholder: "Search…", prefix: search, suffix: () => S.iconButton({ icon: x, tooltip: "Clear" }) });
 ```

package/src/components/autocomplete.ts

@@ -26,8 +26,22 @@ export interface AutocompleteOptions extends FieldOptions {
 	bind?: Bindable<string | string[]>;
 	/** Allow selecting several values, shown as removable chips. */
 	multi?: boolean;
-	/** Allow committing free text that isn't in the options list. Defaults to `true`. */
+	/**
+	 * Allow committing free text that isn't in the options list. Defaults to
+	 * `true`, and includes no text at all: emptying a single-select field clears
+	 * its selection (`required` is what makes that an error). With
+	 * `allowCustom: false` only the options can be committed, so anything else
+	 * springs back to the current selection when the field loses focus.
+	 */
 	allowCustom?: boolean;
+	/**
+	 * The type-ahead test, run for each option against what has been typed.
+	 * Defaults to {@link matchWords}. Pass your own to filter differently — say
+	 * `(label, q) => label.toLowerCase().includes(q.toLowerCase())` for plain
+	 * substring matching, or something that also looks at an option's other
+	 * fields. Matching never reorders: options are shown as given.
+	 */
+	match?: (label: string, query: string) => boolean;
 	/** Placeholder for the text input. */
 	placeholder?: string;
 }
@@ -110,6 +124,41 @@ mountPortal(() => {
 	sizeChanged = followAnchor(p.anchor, (r) => place(el, r));
 });
 
+/**
+ * Where each word of a label begins: runs of letters or digits, split again at
+ * camelCase humps — "TypeScript" starts a word at `T` and at `S`.
+ */
+function wordStarts(label: string): number[] {
+	const starts: number[] = [];
+	for (const m of label.matchAll(/\p{N}+|\p{Lu}+(?=\p{Lu}\p{Ll})|\p{Lu}?\p{Ll}+|\p{Lu}+/gu)) starts.push(m.index);
+	return starts;
+}
+
+/**
+ * The default type-ahead test: every whitespace-separated term of the query has
+ * to match the label from a word start on, and no two terms may claim the same
+ * word. Order doesn't matter, so "se pal" finds "Palette search" just as
+ * "pal se" does — but "ette" finds nothing, as you type the beginnings of
+ * words. A term may run past its word's end ("typescript" finds "TypeScript",
+ * "c++" finds "C++"), so typing a label out in full always finds it.
+ *
+ * Pass it to {@link AutocompleteOptions.match} to compose with it.
+ */
+export function matchWords(label: string, query: string): boolean {
+	// Longest term first: it is the most constrained, so the greedy claim below
+	// doesn't let a short term take the word a long one needed.
+	const terms = query.toLowerCase().split(/\s+/).filter(Boolean).sort((a, b) => b.length - a.length);
+	if (!terms.length) return true;
+	const starts = wordStarts(label);
+	const used: boolean[] = [];
+	return terms.every((t) => {
+		const i = starts.findIndex((s, i) => !used[i] && label.slice(s, s + t.length).toLowerCase() === t);
+		if (i < 0) return false;
+		used[i] = true;
+		return true;
+	});
+}
+
 function normOption(o: AutocompleteOptionInput): AcOption {
 	return typeof o === "string" ? { value: o, label: o } : { value: o.value, label: o.label ?? o.value };
 }
@@ -119,6 +168,10 @@ function normOption(o: AutocompleteOptionInput): AcOption {
  * optional free-text entry, and full keyboard control (arrows, enter, escape,
  * backspace-to-remove). Implements the ARIA combobox/listbox pattern.
  *
+ * What you type is matched against the start of the label's words, a term at a
+ * time and in any order — "pal se" finds "Palette search" — see
+ * {@link matchWords}, or {@link AutocompleteOptions.match} to filter your own way.
+ *
  * The suggestion list is portalled to `document.body`, so a dialog or a
  * scrolling column can neither clip it nor grow a scrollbar around it. It hangs
  * off whichever side of the field has the room, and follows it as things move.
@@ -154,6 +207,10 @@ export function autocomplete(opts: AutocompleteOptions): void {
 		return Array.isArray(v) ? v : [v];
 	};
 	const labelFor = (value: string): string => getOptions().find((o) => o.value === value)?.label ?? value;
+	// What committing free text means: the option the text names, or the text itself.
+	// Typing a label out in full is picking that option, not inventing a value.
+	const valueForText = (text: string): string =>
+		text ? getOptions().find((o) => o.label.toLowerCase() === text.toLowerCase())?.value ?? text : "";
 
 	// Seed the input with the current single-selection's label.
 	if (!opts.multi) {
@@ -165,8 +222,9 @@ export function autocomplete(opts: AutocompleteOptions): void {
 		const sel = new Set(selectedValues());
 		let list = getOptions();
 		if (opts.multi) list = list.filter((o) => !sel.has(o.value));
-		const q = $st.query.trim().toLowerCase();
-		if (q) list = list.filter((o) => o.label.toLowerCase().includes(q));
+		// Cased as typed: the matcher splits on camelCase humps, and lowercases itself.
+		const q = $st.query.trim();
+		if (q) list = list.filter((o) => (opts.match ?? matchWords)(o.label, q));
 		return list;
 	};
 
@@ -316,21 +374,27 @@ export function autocomplete(opts: AutocompleteOptions): void {
 		} else if (e.key === "Enter") {
 			// Always prevent default to avoid accidental form submission.
 			e.preventDefault();
-			const chosen = list[$st.active];
+			const q = $st.query.trim();
+			// Only a row of a list that is up: with it hidden there is no highlight to
+			// be seen, so Enter takes what has been typed instead.
+			const chosen = $st.open ? list[$st.active] : undefined;
 			if (chosen) {
 				commit(chosen.value, inputEl);
-			} else if (opts.allowCustom !== false && $st.query.trim()) {
-				commit($st.query.trim(), inputEl);
+			} else if (opts.allowCustom !== false && (q || !opts.multi)) {
+				// No text is a commit too, in single mode: it clears the selection.
+				// (In multi mode there is nothing to clear, and no chip to make.)
+				commit(valueForText(q), inputEl);
 			} else if ($st.open) {
+				// Nothing to commit (the options are all there is, and none match).
 				$st.open = false;
 			}
 		} else if (e.key === "Escape") {
-			// Only consume Escape while the list is showing: it dismisses the innermost
-			// layer, so a surrounding dialog closes on the next press, not this one.
+			// Escape hides the list and leaves what was typed standing — it dismisses
+			// a layer, it doesn't undo an edit. Only consumed while the list is up, so
+			// a surrounding dialog closes on the next press, not this one.
 			if ($st.open) {
 				e.preventDefault();
 				$st.open = false;
-				if (!opts.multi) $st.query = labelFor(selectedValues()[0] ?? "");
 			}
 		} else if (e.key === "Backspace" && opts.multi && $st.query === "") {
 			const sel = selectedValues();
@@ -342,10 +406,12 @@ export function autocomplete(opts: AutocompleteOptions): void {
 		$st.open = false;
 		if (opts.multi) {
 			$st.query = "";
-		} else if (opts.allowCustom !== false && $st.query.trim()) {
-			commit($st.query.trim());
+		} else if (opts.allowCustom !== false) {
+			// Free text stands as typed — nothing at all included, which is how a
+			// single selection is cleared. (`required` is what makes empty an error.)
+			commit(valueForText($st.query.trim()));
 		} else {
-			// Revert to the committed selection's label.
+			// Only the options exist, so anything else reverts to the selected one.
 			$st.query = labelFor(selectedValues()[0] ?? "");
 		}
 	}

package/src/components/dialog.ts

@@ -51,6 +51,9 @@ export interface DialogOptions {
 	onClose?: () => void;
 }
 
+/** The layer the bottom dialog's backdrop is painted on; each dialog adds two. */
+const BASE_Z = 200;
+
 A.insertGlobalCss({
 	".s-backdrop": {
 		"&": "position:fixed inset:0 z-index:200 display:block background: rgba(0,0,0,0.55); transition: opacity 0.4s ease-in-out;",
@@ -80,6 +83,8 @@ A.insertGlobalCss({
 const dialogs = A.proxy({} as Record<string,{resolve: (value: void | PromiseLike<void>) => void, opts: DialogOptions}>);
 let dialogCount = 0;
 
+// `Object.keys` orders integer-like keys numerically, so the last one is the
+// newest dialog — the one on top.
 const topDialogId = A.derive(() => {
 	const keys = Object.keys(dialogs);
 	if (keys.length) return keys[keys.length-1];
@@ -91,6 +96,9 @@ export function isDialogOpen(): boolean {
 }
 
 mountPortal(() => {
+	// Sorted numerically: the keys are numbers, and left to `onEach`'s default
+	// string ordering "10" would sort before "2", putting the tenth dialog
+	// before (hence behind) a still-open second one.
 	A.onEach(dialogs, ({resolve, opts}, dialogId) => {
 		const close = () => { delete dialogs[dialogId]; };
 
@@ -109,9 +117,9 @@ mountPortal(() => {
 
 		// Backdrop - hide when not the top dialog
 		const overlaid = A.derive(() => topDialogId.value != dialogId);
-		A("div.s-backdrop create=hidden destroy=hidden .hidden=", overlaid, "click=", () => {
+		const backdropEl = A("div.s-backdrop create=hidden destroy=hidden .hidden=", overlaid, "click=", () => {
 			if (opts.allowCancel !== false) close();
-		});
+		}) as HTMLElement;
 
 		// Derived from the dialog's own key rather than a second counter: there is
 		// exactly one of these per dialog, for as long as the dialog exists.
@@ -164,10 +172,28 @@ mountPortal(() => {
 			});
 		}) as HTMLElement;
 
+		// Stacking is stated, not left to the order the elements happen to sit in
+		// the DOM: a dialog sits a layer above its own backdrop, and that pair a
+		// layer above the dialog it covers. (A closing dialog has left the stack
+		// already; it keeps the layer it had while it fades out.)
+		let depth = 0;
+		A(() => {
+			const index = Object.keys(dialogs).indexOf(dialogId);
+			if (index >= 0) depth = index;
+			backdropEl.style.zIndex = `${BASE_Z + 2*depth}`;
+			dialogEl.style.zIndex = `${BASE_Z + 2*depth + 1}`;
+		});
+
 		// Once laid out, move focus into the dialog so it's keyboard-ready and focus
 		// doesn't linger on whatever opened it.
-		requestAnimationFrame(() => { if (document.body.contains(dialogEl)) focusFirst(dialogEl); });
-	});
+		requestAnimationFrame(() => {
+			// Only the top dialog claims focus: one opened *under* another (the
+			// covering dialog opened straight after it) must not pull focus into
+			// fields the user can't see.
+			if (A.peek(() => topDialogId.value) !== dialogId) return;
+			if (document.body.contains(dialogEl)) focusFirst(dialogEl);
+		});
+	}, (_value, dialogId) => +dialogId);
 })
 
 /**
@@ -192,8 +218,9 @@ function trapTab(dialogEl: HTMLElement, event: KeyboardEvent): void {
  * closes. Lifecycle is also tied to the parent reactive scope — when that scope
  * is cleaned up the dialog disappears and the promise resolves.
  *
- * Multiple dialogs stack correctly: each new pair (backdrop + dialog) has a
- * higher z-index, while older dialogs are pushed behind their covering backdrop.
+ * Multiple dialogs stack: each new pair (backdrop + dialog) gets a higher
+ * z-index than the one it covers, while older dialogs are pushed behind their
+ * covering backdrop.
  *
  * @example
  * ```ts

package/src/components/field.ts

@@ -31,6 +31,28 @@ export interface FieldOptions {
 	inputAttrs?: Attributes;
 }
 
+/**
+ * Options for a field that can carry content *inside* its control box — an
+ * icon against the leading edge, a button against the trailing one. Added by
+ * {@link import("./textline").textline} and
+ * {@link import("./textarea").textarea}.
+ */
+export interface InsetOptions {
+	/**
+	 * Content drawn inside the control, against its leading edge — typically a
+	 * unit, a currency sign or a search glyph. The control's text is indented to
+	 * keep clear of it, however wide it turns out to be.
+	 */
+	prefix?: Slot;
+	/**
+	 * Content drawn inside the control, against its trailing edge: a *send*
+	 * button on a chat box, a clear or reveal button, a character count. Sits
+	 * against the bottom on a (growing) textarea, and vertically centred on a
+	 * single-line input.
+	 */
+	suffix?: Slot;
+}
+
 A.insertGlobalCss({
 	".s-field": {
 		"&": "display:flex flex-direction:column gap:$1",
@@ -47,6 +69,34 @@ A.insertGlobalCss({
 		"&:focus-visible": "border-color:$s-accent box-shadow: 0 0 0 3px $s-focus; outline:none",
 "&[aria-invalid=true]": "border-color:$s-danger",
 	},
+	// Insets sit *over* the control rather than beside it, so the control keeps its
+	// own border, focus ring and full width; only its text padding gets out of the
+	// way, by however much each inset measures (see `drawInsets`).
+	".s-inset": {
+		// `display:contents` until an inset is actually there: the wrapper then has
+		// no box of its own, leaving the control the direct flex/grid child of the
+		// field that it was before insets existed — so a caller stretching the field
+		// (`attrs: "h:100%"` with `inputAttrs: "flex:1"`) still reaches the control.
+		"&": "display:contents --s-inset-start:0px --s-inset-end:0px",
+		"&:has(> .s-inset_start), &:has(> .s-inset_end)": "position:relative display:grid",
+		"> .s-input": "padding-inline-start: calc(0.7em + var(--s-inset-start)); padding-inline-end: calc(0.7em + var(--s-inset-end));",
+		"> .s-inset_start, > .s-inset_end": "position:absolute top:0 bottom:0 display:flex align-items:center gap:$1 fg:$s-muted",
+		"> .s-inset_start": "left:0.35em",
+		"> .s-inset_end": "right:0.35em",
+		// On a textarea the insets ride the bottom edge, so a growing box keeps its
+		// send button where the caret is rather than floating it mid-paragraph.
+		"&.s-inset-bottom > .s-inset_start, &.s-inset-bottom > .s-inset_end": "top:auto padding-bottom:0.35em",
+		"> .s-inset_start > svg, > .s-inset_end > svg": "width:1.15em height:1.15em",
+		// A number input's spinner wants the very corner a trailing inset is in, and
+		// it is the inset that was asked for. (Firefox's is `appearance`-controlled.)
+		"&:has(> .s-inset_end) > input[type=number]": "appearance:textfield",
+		"&:has(> .s-inset_end) > input[type=number]::-webkit-inner-spin-button": "appearance:none margin:0",
+	},
+	// A plain glyph or a counter shouldn't eat the click that focuses the field;
+	// anything the user can actually operate does.
+	".s-inset_start, .s-inset_end": "pointer-events:none",
+	".s-inset_start :where(button, a, input, select, textarea, label, [tabindex])": "pointer-events:auto",
+	".s-inset_end :where(button, a, input, select, textarea, label, [tabindex])": "pointer-events:auto",
 });
 
 /**
@@ -111,3 +161,45 @@ export function applyControlAttrs(
 	A(() => A("aria-invalid=", isInvalid() ? "true" : "false"));
 	if (bind) A("bind=", bind);
 }
+
+/**
+ * Wrap a control in the {@link InsetOptions} box: the control as drawn by
+ * `drawControl`, plus the `prefix`/`suffix` slots laid over its leading and
+ * trailing edges.
+ *
+ * Each inset is measured (it may hold anything) and its width published to the
+ * wrapper as a CSS variable, from which the control takes its text padding — so
+ * the text never runs under the inset, whatever is in it. Each slot gets its own
+ * reactive scope, so appearing, changing or going away never touches the control
+ * element (which would lose focus and selection).
+ *
+ * @param opts The inset slots.
+ * @param bottom Align the insets with the control's bottom edge instead of
+ *   centring them — what a growing textarea wants.
+ * @param drawControl Draws the control element itself, marked `s-input`.
+ */
+export function drawInsets(opts: InsetOptions, bottom: boolean, drawControl: () => void): void {
+	A("div.s-inset", () => {
+		if (bottom) A(".s-inset-bottom");
+		drawControl();
+		drawInset(() => opts.prefix, "s-inset_start", "--s-inset-start");
+		drawInset(() => opts.suffix, "s-inset_end", "--s-inset-end");
+	});
+}
+
+function drawInset(get: () => Slot | undefined, cls: string, cssVar: string): void {
+	A(() => {
+		const slot = get();
+		if (slot == null) return;
+		// `.small` sizes the buttons inside (as a buttonGroup does), so something
+		// inset into a field can never stretch the field.
+		const box = A(`div.${cls}.small`, () => drawSlot(slot)) as HTMLElement;
+		const wrap = box.parentElement;
+		const ro = new ResizeObserver(() => wrap?.style.setProperty(cssVar, `${box.offsetWidth}px`));
+		ro.observe(box);
+		A.clean(() => {
+			ro.disconnect();
+			wrap?.style.setProperty(cssVar, "0px");
+		});
+	});
+}

package/src/components/form.ts

@@ -30,6 +30,11 @@ A.insertGlobalCss({
 		"&": "display:flex flex-direction:column gap:$3",
 		"&.grid": "display:grid grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)); gap:$3",
 		"&.grid > .s-wide, &.grid > footer": "grid-column: 1 / -1;",
+		// Fields hug their content rather than being stretched to the tallest in
+		// their row. Invisible either way — a field has no fill of its own — but it
+		// keeps "this field has a height" meaning "the caller asked for one", which
+		// is what a textarea reads to decide whether to fill it.
+		"&.grid > .s-field": "align-self: start",
 		"> footer": "display:flex align-items:center justify-content:flex-end gap:$2 flex-wrap:wrap margin-top:$1",
 	},
 });

package/src/components/textarea.ts

@@ -1,9 +1,9 @@
 import A from "aberdeen";
 import type { Bindable } from "../core.js";
-import { type FieldOptions, applyControlAttrs, drawField } from "./field.js";
+import { type FieldOptions, type InsetOptions, applyControlAttrs, drawField, drawInsets } from "./field.js";
 
 /** Options for {@link textarea}. */
-export interface TextareaOptions extends FieldOptions {
+export interface TextareaOptions extends FieldOptions, InsetOptions {
 	/** Placeholder text. */
 	placeholder?: string;
 	/** Two-way binding target. */
@@ -12,9 +12,18 @@ export interface TextareaOptions extends FieldOptions {
 	value?: string;
 	/** Visible number of text rows. Defaults to `4`. Ignored when `autoGrow` is enabled. */
 	rows?: number;
-	/** Whether the textarea may be resized by the user. Defaults to `"vertical"`. Ignored when `autoGrow` is enabled. */
+	/**
+	 * Whether the textarea may be resized by the user. Defaults to `"vertical"`,
+	 * or to `"none"` when a {@link InsetOptions.suffix | suffix} is given — the
+	 * resize grip and the inset both want the bottom-right corner. Ignored when
+	 * `autoGrow` is enabled.
+	 */
 	resize?: "none" | "vertical" | "horizontal" | "both";
-	/** Auto-grow the textarea to fit its content. Defaults to `true`. */
+	/**
+	 * Auto-grow the textarea to fit its content. Defaults to `true`. Ignored when
+	 * the field is told how tall to be ({@link FieldOptions.attrs | attrs}
+	 * `"h:20rem"`), as that height wins over the one the text asks for.
+	 */
 	autoGrow?: boolean;
 	/** Fired on every `input` event. */
 	input?: (event: Event) => void;
@@ -23,6 +32,14 @@ export interface TextareaOptions extends FieldOptions {
 }
 
 A.insertGlobalCss({
+	// `flex-basis:100%` with nothing to stop it shrinking means "take the field's
+	// height, then give back whatever the label and help need" — so a field told
+	// how tall to be (`attrs: "h:8rem"`) hands that height to the textarea, while a
+	// field left to size itself (every ordinary one) has no definite height for the
+	// basis to resolve against and the textarea is content-sized exactly as before.
+	// The same rule rides the inset box below, which stands in for the control once
+	// a prefix/suffix gives it one.
+	"textarea.s-input, .s-inset.s-inset-bottom": "flex: 0 1 100%; min-height:0",
 	"textarea.s-input": "resize:vertical min-height:3em line-height:1.45",
 	"textarea.s-input.s-autoGrow": "resize:none min-height:2.5em overflow-y:hidden",
 });
@@ -31,35 +48,57 @@ A.insertGlobalCss({
  * A multi-line text input. Shares the field chrome and styling of
  * {@link textline}.
  *
+ * It sizes itself to its text by default. Give the *field* a height instead
+ * ({@link FieldOptions.attrs | attrs} `"h:20rem"`, or `"h:100%"` inside a column
+ * that has one) and the textarea fills it, whatever else the field holds — a
+ * label, help text, a `prefix`/`suffix` inset.
+ *
  * @example
  * ```ts
  * const $user = A.proxy({bio: ""});
  * S.textarea({ label: "Bio", bind: A.ref($user, "bio") });
+ *
+ * // A chat box: the send button sits in the bottom-right corner, inside the field.
+ * const $chat = A.proxy({text: ""});
+ * S.textarea({
+ *   placeholder: "Message…",
+ *   bind: A.ref($chat, "text"),
+ *   suffix: () => S.iconButton({ icon: send, tooltip: "Send", click: () => post($chat.text) }),
+ * });
+ *
+ * // Told how tall to be, the textarea fills the field instead of growing with
+ * // its text — `h:100%` in a column that has a height makes a composer that
+ * // fills whatever room it is given.
+ * S.textarea({ label: "Notes", attrs: "h:20rem", bind: A.ref($chat, "text") });
  * ```
  */
 export function textarea(opts: TextareaOptions = {}): void {
 	const grow = opts.autoGrow !== false;
 
 	drawField(opts, (id, isInvalid) => {
-		const el = A("textarea.s-input", opts.inputAttrs, () => {
-			if (grow) {
-				A(".s-autoGrow");
-				A("input=", (e: Event) => {
-					fitToContent(e.currentTarget as HTMLTextAreaElement);
-					if (opts.input) opts.input(e);
-				});
-			} else {
-				A("rows=", opts.rows ?? 4);
-				A("resize:", opts.resize ?? "vertical");
-				if (opts.input) A("input=", opts.input);
-			}
-			if (opts.placeholder != null) A("placeholder=", opts.placeholder);
-			if (opts.value != null && !opts.bind) A("value=", opts.value);
-			if (opts.change) A("change=", opts.change);
-			applyControlAttrs(opts, id, isInvalid, opts.bind);
-		}) as HTMLTextAreaElement;
+		// Insets ride the bottom edge here: on a growing box that keeps a send
+		// button beside the caret rather than floating it mid-paragraph.
+		drawInsets(opts, true, () => {
+			const el = A("textarea.s-input", opts.inputAttrs, () => {
+				if (grow) {
+					A(".s-autoGrow");
+					A("input=", (e: Event) => {
+						fitToContent(e.currentTarget as HTMLTextAreaElement);
+						if (opts.input) opts.input(e);
+					});
+				} else {
+					A("rows=", opts.rows ?? 4);
+					A("resize:", opts.resize ?? (opts.suffix ? "none" : "vertical"));
+					if (opts.input) A("input=", opts.input);
+				}
+				if (opts.placeholder != null) A("placeholder=", opts.placeholder);
+				if (opts.value != null && !opts.bind) A("value=", opts.value);
+				if (opts.change) A("change=", opts.change);
+				applyControlAttrs(opts, id, isInvalid, opts.bind);
+			}) as HTMLTextAreaElement;
 
-		if (grow) requestAnimationFrame(() => fitToContent(el));
+			if (grow) requestAnimationFrame(() => fitToContent(el));
+		});
 	});
 }