staffa 0.20.0 → 0.22.0

package/README.md

@@ -249,6 +249,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.
+
 `src/index.ts` is the authoritative list of exports.
 
 ### Keyboard shortcuts

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/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;

package/dist/components/textarea.js

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { applyControlAttrs, drawField } from "./field.js";
+import { applyControlAttrs, drawField, drawInsets } from "./field.js";
 A.insertGlobalCss({
     "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",
@@ -12,36 +12,48 @@ A.insertGlobalCss({
  * ```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 function textarea(opts = {}) {
     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) => {
-                    fitToContent(e.currentTarget);
+        // 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) => {
+                        fitToContent(e.currentTarget);
+                        if (opts.input)
+                            opts.input(e);
+                    });
+                }
+                else {
+                    A("rows=", opts.rows ?? 4);
+                    A("resize:", opts.resize ?? (opts.suffix ? "none" : "vertical"));
                     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);
+                        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);
+            });
+            if (grow)
+                requestAnimationFrame(() => fitToContent(el));
         });
-        if (grow)
-            requestAnimationFrame(() => fitToContent(el));
     });
 }
 function fitToContent(el) {

package/dist/components/textline.d.ts

@@ -1,5 +1,5 @@
 import type { Bindable } from "../core.js";
-import { type FieldOptions } from "./field.js";
+import { type FieldOptions, type InsetOptions } from "./field.js";
 /**
  * The `<input>` types {@link textline} supports. Deliberately excludes types
  * that need their own widget (`checkbox`, `radio`, `color`, `range`, `file`,
@@ -7,7 +7,7 @@ import { type FieldOptions } from "./field.js";
  */
 export type TextlineType = "text" | "password" | "email" | "number" | "tel" | "url" | "search" | "date" | "time" | "datetime-local" | "month" | "week";
 /** Options for {@link textline}. */
-export interface TextlineOptions extends FieldOptions {
+export interface TextlineOptions extends FieldOptions, InsetOptions {
     /** Input type. Defaults to `"text"`. */
     type?: TextlineType;
     /** Placeholder text. */
@@ -32,6 +32,9 @@ export interface TextlineOptions extends FieldOptions {
  * ```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" }) });
  * ```
  */
 export declare function textline(opts?: TextlineOptions): void;

package/dist/components/textline.js

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { applyControlAttrs, drawField } from "./field.js";
+import { applyControlAttrs, drawField, drawInsets } from "./field.js";
 /**
  * A single-line text input — text, passwords, numbers, email, dates and the other
  * line-oriented `<input>` types. Renders inside the standard {@link drawField}
@@ -9,23 +9,28 @@ import { applyControlAttrs, drawField } from "./field.js";
  * ```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" }) });
  * ```
  */
 export function textline(opts = {}) {
     drawField(opts, (id, isInvalid) => {
-        A("input.s-input", opts.inputAttrs, () => {
-            A("type=", opts.type ?? "text");
-            if (opts.placeholder != null)
-                A("placeholder=", opts.placeholder);
-            if (opts.autocomplete != null)
-                A("autocomplete=", opts.autocomplete);
-            if (opts.value != null && !opts.bind)
-                A("value=", opts.value);
-            if (opts.input)
-                A("input=", opts.input);
-            if (opts.change)
-                A("change=", opts.change);
-            applyControlAttrs(opts, id, isInvalid, opts.bind);
+        drawInsets(opts, false, () => {
+            A("input.s-input", opts.inputAttrs, () => {
+                A("type=", opts.type ?? "text");
+                if (opts.placeholder != null)
+                    A("placeholder=", opts.placeholder);
+                if (opts.autocomplete != null)
+                    A("autocomplete=", opts.autocomplete);
+                if (opts.value != null && !opts.bind)
+                    A("value=", opts.value);
+                if (opts.input)
+                    A("input=", opts.input);
+                if (opts.change)
+                    A("change=", opts.change);
+                applyControlAttrs(opts, id, isInvalid, opts.bind);
+            });
         });
     });
 }

package/dist/index.d.ts

@@ -32,7 +32,7 @@
 export { setDarkMode, getDarkMode } from "./theme.js";
 export { formatKey, bindKey } from "./keys.js";
 export { showKeyHelp, setKeyHelp } from "./components/keyhelp.js";
-export { autocomplete, type AutocompleteOptions, type AutocompleteOptionInput } from "./components/autocomplete.js";
+export { autocomplete, matchWords, type AutocompleteOptions, type AutocompleteOptionInput } from "./components/autocomplete.js";
 export { box, type BoxOptions } from "./components/box.js";
 export { button, iconButton, type ButtonOptions, type IconButtonOptions } from "./components/button.js";
 export { buttonChooser, type ButtonChooserOptions } from "./components/buttonChooser.js";
@@ -49,5 +49,5 @@ export { textarea, type TextareaOptions } from "./components/textarea.js";
 export { textline, type TextlineOptions, type TextlineType } from "./components/textline.js";
 export { toast, type ToastOptions } from "./components/toast.js";
 export { addTooltip, type TooltipOptions } from "./components/tooltip.js";
-export type { FieldOptions } from "./components/field.js";
+export type { FieldOptions, InsetOptions } from "./components/field.js";
 export type { ContentOptions, Bindable, Slot, Attributes } from "./core.js";

package/dist/index.js

@@ -34,7 +34,7 @@
 export { setDarkMode, getDarkMode } from "./theme.js";
 export { formatKey, bindKey } from "./keys.js";
 export { showKeyHelp, setKeyHelp } from "./components/keyhelp.js";
-export { autocomplete } from "./components/autocomplete.js";
+export { autocomplete, matchWords } from "./components/autocomplete.js";
 export { box } from "./components/box.js";
 export { button, iconButton } from "./components/button.js";
 export { buttonChooser } from "./components/buttonChooser.js";