staffa 0.19.0 → 0.22.0

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,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",
 });
 
 /**
@@ -111,3 +156,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/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,7 +12,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;
@@ -35,31 +40,43 @@ 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: 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));
+		});
 	});
 }
 

package/src/components/textline.ts

@@ -1,6 +1,6 @@
 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";
 
 /**
  * The `<input>` types {@link textline} supports. Deliberately excludes types
@@ -22,7 +22,7 @@ export type TextlineType =
 	| "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. */
@@ -48,18 +48,23 @@ 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 function textline(opts: TextlineOptions = {}): void {
 	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/src/index.ts

@@ -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, 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";
@@ -51,7 +51,7 @@ 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";
 
 // Re-export theming and shared types for advanced use.
 export type {ContentOptions, Bindable, Slot, Attributes} from "./core.js";