staffa 0.19.0 → 0.22.0

package/README.md

@@ -244,10 +244,20 @@ Buttons, icon buttons and menu items carry a `tooltip` option of their own, so m
 
 ```ts
 S.button({ content: "Publish", tooltip: "Not until the draft validates", disabled: true });
-S.iconButton({ icon: trash2, ariaLabel: "Delete" });   // says "Delete" on hover
+S.iconButton({ icon: trash2, tooltip: "Delete" });   // says "Delete" on hover, and to screen readers
 ```
 
-An icon button tips its `ariaLabel` unless given a `tooltip` of its own (`tooltip: false` for neither), a `key` is appended to whatever the tip says, 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.
+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.
 
 `src/index.ts` is the authoritative list of exports.
 

package/dist/components/autocomplete.d.ts

@@ -21,16 +21,45 @@ 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;
 }
+/**
+ * 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 declare function matchWords(label: string, query: string): boolean;
 /**
  * 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
+ * {@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.

package/dist/components/autocomplete.js

@@ -62,6 +62,42 @@ 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) {
+    const starts = [];
+    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, query) {
+    // 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 = [];
+    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) {
     return typeof o === "string" ? { value: o, label: o } : { value: o.value, label: o.label ?? o.value };
 }
@@ -70,6 +106,10 @@ function normOption(o) {
  * 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.
@@ -105,6 +145,9 @@ export function autocomplete(opts) {
         return Array.isArray(v) ? v : [v];
     };
     const labelFor = (value) => 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) => text ? getOptions().find((o) => o.label.toLowerCase() === text.toLowerCase())?.value ?? text : "";
     // Seed the input with the current single-selection's label.
     if (!opts.multi) {
         const v = opts.bind ? A.peek(opts.bind, 'value') : undefined;
@@ -116,9 +159,10 @@ export function autocomplete(opts) {
         let list = getOptions();
         if (opts.multi)
             list = list.filter((o) => !sel.has(o.value));
-        const q = $st.query.trim().toLowerCase();
+        // Cased as typed: the matcher splits on camelCase humps, and lowercases itself.
+        const q = $st.query.trim();
         if (q)
-            list = list.filter((o) => o.label.toLowerCase().includes(q));
+            list = list.filter((o) => (opts.match ?? matchWords)(o.label, q));
         return list;
     };
     const commit = (value, inputEl) => {
@@ -271,25 +315,30 @@ export function autocomplete(opts) {
         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 === "") {
@@ -303,11 +352,13 @@ export function autocomplete(opts) {
         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/dist/components/button.d.ts

@@ -3,8 +3,12 @@ import { type Slot, type Attributes } from "../core.js";
 export interface IconButtonOptions {
     /** The glyph, usually one of the `staffa/icons` draw functions. */
     icon: Slot;
-    /** What it does, for screen readers. Required: there is no visible text to read. */
-    ariaLabel: string;
+    /**
+     * What it does, for screen readers: there is no visible text to read. Required,
+     * unless the `tooltip` is a string — that names the button just as well, and is
+     * taken as the label when this is left out.
+     */
+    ariaLabel?: string;
     /**
      * Click handler. Return a promise and the glyph becomes a spinner until it
      * settles, with further clicks bouncing off — see {@link ButtonOptions.click}.
@@ -12,16 +16,17 @@ export interface IconButtonOptions {
     click?: (event: Event) => unknown;
     /**
      * A keyboard shortcut that presses this button — see {@link ButtonOptions.key}.
-     * The tooltip shows it after the button's `tooltip` (or, failing that, its
-     * `ariaLabel` — a glyph is worth naming there anyway), and the `?` overview
-     * lists it under that label too.
+     * It is shown after the button's `tooltip`, or alone in a tooltip of its own
+     * when there is none, and the `?` overview lists it under the button's label.
      */
     key?: string;
     /**
      * A tooltip, shown on hover and keyboard focus; a string renders as rich
-     * text. Defaults to the `ariaLabel`, so an icon button says what it does
-     * without being told twice — pass this only to say something longer or
-     * different, or `false` for no tooltip at all. A `key` is appended to it.
+     * text. There is none unless you ask for one — but do consider it here, as
+     * a glyph says nothing to whoever cannot guess it. A string doubles as the
+     * `ariaLabel` when that is left out, so an icon button usually needs one
+     * option, not two. A `key` is appended to the tip, behind a `·`; pass
+     * `false` to suppress even that.
      *
      * Works on a disabled button too, which is where a tooltip earns its keep:
      * it is the only room there is to say why.
@@ -62,7 +67,10 @@ export interface ButtonOptions {
     type?: "button" | "submit" | "reset";
     /** Render as a link (`<a role=button>`) pointing here instead of a `<button>`. */
     href?: string;
-    /** Accessible label, when the button has only an icon. */
+    /**
+     * Accessible label, when the button has only an icon. A string `tooltip` is
+     * taken as the label of such a button when this is left out.
+     */
     ariaLabel?: string;
     /**
      * A keyboard shortcut that presses this button: `"mod+s"`, `"f2"` — see
@@ -76,9 +84,10 @@ export interface ButtonOptions {
     key?: string;
     /**
      * A tooltip, shown on hover and keyboard focus. A string renders as rich
-     * text, a function draws its own markup. A `key` is appended to it, behind
-     * a `·`. Defaults to the `ariaLabel` of a button that has one (an icon-only
-     * button, that is); pass `false` for no tooltip at all.
+     * text, a function draws its own markup. There is none unless you ask for
+     * one. A `key` is appended to it, behind a `·`; pass `false` to suppress
+     * even that. On an icon-only button, a string tooltip doubles as the
+     * `ariaLabel` when that is left out.
      *
      * Works on a disabled button too, which is where a tooltip earns its keep:
      * it is the only room there is to say why.
@@ -110,7 +119,9 @@ export interface ButtonOptions {
  * import { trash2, share2 } from "staffa/icons";
  *
  * $panel.actions = () => {
- *   S.iconButton({ icon: share2, ariaLabel: "Share", click: share });
+ *   // A string `tooltip` names the button for screen readers too, so one option does.
+ *   S.iconButton({ icon: share2, tooltip: "Share", click: share });
+ *   // Named, but silent on hover: `ariaLabel` alone raises no tooltip.
  *   S.iconButton({ icon: trash2, ariaLabel: "Delete", click: del, attrs: "fg:$s-danger" });
  * };
  * ```

package/dist/components/button.js

@@ -77,22 +77,25 @@ A.insertGlobalCss({
  * import { trash2, share2 } from "staffa/icons";
  *
  * $panel.actions = () => {
- *   S.iconButton({ icon: share2, ariaLabel: "Share", click: share });
+ *   // A string `tooltip` names the button for screen readers too, so one option does.
+ *   S.iconButton({ icon: share2, tooltip: "Share", click: share });
+ *   // Named, but silent on hover: `ariaLabel` alone raises no tooltip.
  *   S.iconButton({ icon: trash2, ariaLabel: "Delete", click: del, attrs: "fg:$s-danger" });
  * };
  * ```
  */
 export function iconButton(opts) {
     const tag = opts.href != null ? "a" : "button";
-    // A glyph says nothing on its own, so the name it carries for screen readers is
-    // the tip too, unless the caller has something better (or `false`) to say.
-    const tip = opts.tooltip === false ? undefined : opts.tooltip ?? opts.ariaLabel;
+    const tip = opts.tooltip === false ? undefined : opts.tooltip;
+    // A glyph says nothing on its own, so the button needs a name — and a tooltip
+    // written as a string already is one. Said once, it serves both.
+    const label = opts.ariaLabel ?? (typeof tip === "string" ? plainText(tip) : undefined);
     A(`${tag}.s-icon-btn`, opts.attrs, () => {
         applyActionBehavior(opts, tip != null);
-        A("aria-label=", opts.ariaLabel);
+        A("aria-label=", label);
         // Before the glyph, so a tooltip the caller adds in there is the later of
         // the two and wins the hover.
-        applyTooltipAndKey(tip, opts.key, opts.ariaLabel, opts.disabled);
+        applyTooltipAndKey(opts.tooltip, opts.key, label, opts.disabled);
         drawSlot(opts.icon);
     });
 }
@@ -159,25 +162,35 @@ function applyClick(click) {
         Promise.resolve(result).then(done, (err) => { done(); throw err; });
     });
 }
+/**
+ * A rich-text string as a screen reader should hear it. Same pattern Aberdeen's
+ * `rich=` draws with, so a tooltip standing in as the accessible name says the
+ * words it shows, and not its own asterisks and brackets.
+ */
+function plainText(rich) {
+    return rich.replace(/\*\*(.+?)\*\*|\*(.+?)\*|`(.+?)`|\[(.+?)\]\((.+?)\)/g, (_m, bold, italic, code, link) => bold ?? italic ?? code ?? link);
+}
 /**
  * The tooltip and shortcut plumbing {@link button} and {@link iconButton} share:
  * show the tip, with the key appended — the only place a button can say what its
  * key is without shouting it beside the label — then bind that key and announce
- * it as `aria-keyshortcuts`.
+ * it as `aria-keyshortcuts`. A key with no tooltip to join gets a tip of its
+ * own, saying the combination and no more.
  *
- * Pressing it clicks the element rather than calling `click` directly, so a
+ * Pressing the key clicks the element rather than calling `click` directly, so a
  * `type=submit` still submits its form and an `href` still navigates. Call this
  * inside the button's own element scope, whose element it takes and whose life
- * the binding follows.
+ * the binding follows. `keyLabel` is how the `?` overview names the shortcut.
  */
-function applyTooltipAndKey(tip, key, label, disabled) {
-    if (tip != null || key) {
+function applyTooltipAndKey(tooltip, key, keyLabel, disabled) {
+    // `false` is a vow of silence: not even a key raises a tip on this one.
+    if (tooltip !== false && (tooltip != null || key)) {
         addTooltip({
             tip: () => {
-                drawSlot(tip);
+                drawSlot(tooltip);
                 // A draw function, not a string: a key like `*` is markup to rich text.
                 if (key)
-                    A("#", tip == null ? formatKey(key) : ` · ${formatKey(key)}`);
+                    A("#", tooltip == null ? formatKey(key) : ` · ${formatKey(key)}`);
             },
         });
     }
@@ -187,7 +200,7 @@ function applyTooltipAndKey(tip, key, label, disabled) {
     if (key && !disabled) {
         const el = A();
         A("aria-keyshortcuts=", formatKey(key, true));
-        bindKey(key, label, () => el.click());
+        bindKey(key, keyLabel, () => el.click());
     }
 }
 /**
@@ -219,18 +232,19 @@ function applyTooltipAndKey(tip, key, label, disabled) {
 export function button(opts = {}) {
     const o = typeof opts === "string" || typeof opts === "function" ? { content: opts } : opts;
     const tag = o.href != null ? "a" : "button";
-    // An `ariaLabel` means an icon-only button, whose name is worth showing to the
-    // sighted too; anything else says nothing until asked.
-    const tip = o.tooltip === false ? undefined : o.tooltip ?? o.ariaLabel;
+    const tip = o.tooltip === false ? undefined : o.tooltip;
+    // Only a button without visible text needs naming, and a string tooltip is a
+    // name: on one that has text, an aria-label would *hide* that text from AT.
+    const label = o.ariaLabel ?? (o.content == null && typeof tip === "string" ? plainText(tip) : undefined);
     // A bare `.s-s` is a filled `.primary` surface (see theme.ts), so no role
     // detection here: `attrs` just names another role or variant.
     A(`${tag}.s-btn.s-s.shadow`, o.attrs, () => {
         applyActionBehavior(o, tip != null);
-        if (o.ariaLabel)
-            A("aria-label=", o.ariaLabel);
+        if (label)
+            A("aria-label=", label);
         // Before the content, so a tooltip the caller adds in there is the later of
         // the two and wins the hover.
-        applyTooltipAndKey(tip, o.key, typeof o.content === "string" ? o.content : o.ariaLabel, o.disabled);
+        applyTooltipAndKey(o.tooltip, o.key, typeof o.content === "string" ? o.content : label, o.disabled);
         drawSlot(o.icon);
         drawSlot(o.content);
     });

package/dist/components/dialog.d.ts

@@ -52,8 +52,9 @@ export declare function isDialogOpen(): boolean;
  * 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/dist/components/dialog.js

@@ -4,6 +4,8 @@ import { button } from "./button.js";
 import { buttonGroup } from "./buttonGroup.js";
 import { textline } from "./textline.js";
 import { bindKey, claimKeyboard, keyboardOwner } from "../keys.js";
+/** 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;",
@@ -28,6 +30,8 @@ A.insertGlobalCss({
 });
 const dialogs = A.proxy({});
 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)
@@ -38,6 +42,9 @@ export function isDialogOpen() {
     return topDialogId.value != null;
 }
 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]; };
         A.clean(() => {
@@ -54,7 +61,7 @@ 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();
         });
@@ -105,11 +112,30 @@ mountPortal(() => {
                 }
             });
         });
+        // 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);
 });
 /**
  * Keep Tab inside a modal dialog: from its last focusable element Tab wraps
@@ -134,8 +160,9 @@ function trapTab(dialogEl, event) {
  * 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/dist/components/field.d.ts

@@ -28,6 +28,27 @@ export interface FieldOptions {
     /** Aberdeen attr/style string applied to the control (input) element itself. */
     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;
+}
 /**
  * Render the standard field chrome (label + control + help/error) around a
  * caller-supplied control.
@@ -47,3 +68,20 @@ export declare function drawField(opts: FieldOptions, drawControl: (id: string,
  * each get their own scope so the control element is never recreated.
  */
 export declare function applyControlAttrs(opts: FieldOptions, id: string, isInvalid: () => boolean, bind?: Bindable<unknown>): void;
+/**
+ * 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 declare function drawInsets(opts: InsetOptions, bottom: boolean, drawControl: () => void): void;

package/dist/components/field.js

@@ -16,6 +16,29 @@ 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": {
+        "&": "position:relative display:grid --s-inset-start:0px --s-inset-end:0px",
+        "> .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",
 });
 /**
  * Render the standard field chrome (label + control + help/error) around a
@@ -74,3 +97,45 @@ export function applyControlAttrs(opts, id, isInvalid, bind) {
     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, bottom, drawControl) {
+    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, cls, cssVar) {
+    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));
+        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/dist/components/textarea.d.ts

@@ -1,7 +1,7 @@
 import type { Bindable } from "../core.js";
-import { type FieldOptions } from "./field.js";
+import { type FieldOptions, type InsetOptions } 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. */
@@ -10,7 +10,12 @@ 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`. */
     autoGrow?: boolean;
@@ -27,6 +32,14 @@ export interface TextareaOptions extends FieldOptions {
  * ```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) }),
+ * });
  * ```
  */
 export declare function textarea(opts?: TextareaOptions): void;