@kennycorrea/ui 1.8.1 → 1.8.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.8.4 — 2026-10-30
+
+A `MentionTextarea` molecule.
+
+- **`MentionTextarea`**: a `Textarea` that is an ARIA combobox for inline tokens. `triggers` maps a character to a kind (`{ '$': 'ticker', '@': 'member' }`); a trigger at the start or after whitespace, up to the caret, is the token. `onQuery(kind, q)` returns `{ value, label, detail? }` options, sync or async (an answer to an older query is dropped). `onPick` defaults to replacing the token with `<trigger><value> ` and putting the caret after it.
+- The listbox sits under the field (`role="listbox"`/`option` on divs, `aria-activedescendant`, focus stays in the textarea). Arrow keys move, Enter or Tab picks, Esc closes; options pick on mousedown without blurring. Radix tokens only, so light and dark follow the theme.
+- **New UI string `suggestions`** names the listbox. `findMentionToken` is exported too. Tests in `test/MentionTextarea.test.tsx`.
+
+## 1.8.2 — 2026-10-30
+
+A live validation status on `FormField`.
+
+- **`status` and `statusMessage` on `FormField`**, for checks run as the user types, such as a username being looked up. `checking` shows a spinner and muted text; `valid` shows a check icon and text in `--color-good-ink` (jade-11, at least 4.5:1 on the panel in light and dark); `invalid` looks and behaves like `error`. The icon and the words carry the meaning, not the colour. While shown, the message replaces the hint and is linked through `aria-describedby`. `error` wins when both are set.
+- **`announce`** repeats the message in a polite `role="status"` region. The region starts empty, so nothing is announced on first render, only changes. Off by default.
+- Tests in `test/FormField-status.test.tsx`; demo in `examples/UsernameField.tsx`.
+
 ## 1.8.1 — 2026-10-30
 
 TabBar label contrast.

package/README.md

@@ -284,6 +284,22 @@ Full example with 500 rows: [examples/admin/Orders.tsx](examples/admin/Orders.ts
 - **`FilterPopover`**: a "Filters (n)" button opening a popover, or a bottom sheet below `sm`.
   With `onApply` the controls are a draft. **`FilterChips`** is a ChipGroup plus clear-all.
   **`FilterBar`** lays out search, filters and actions, with active filters as removable pills.
+- **`MentionTextarea`**: a Textarea with inline tokens such as `@ana` or `$AAPL`, as an ARIA
+  combobox. Typing a trigger opens a listbox under the field; arrows move, Enter/Tab picks,
+  Esc closes, and a click picks without taking focus from the textarea.
+
+  ```tsx
+  <MentionTextarea
+    value={note}
+    onValueChange={setNote}
+    triggers={{ $: 'ticker', '@': 'member' }}
+    onQuery={(kind, q) => (kind === 'member' ? searchMembers(q) : searchTickers(q))}
+  />
+  ```
+
+  Options are `{ value, label, detail? }`, sync or async. `onPick(option, token, text)` returns
+  `{ value, caret }`; the default replaces the token with `<trigger><value> `. The listbox is
+  named by the `suggestions` UI string.
 - **`SettingsPage`**: section list beside the content from 768px; a select above it when
   narrower.
 

package/dist/molecules/FormField/FormField.d.ts

@@ -12,6 +12,19 @@ export interface FormFieldProps {
     hint?: ReactNode;
     /** The validation message. Marks the control invalid and is linked with `aria-describedby`. */
     error?: ReactNode;
+    /**
+     * A live check's state — a username looked up as it is typed. `checking` shows a spinner,
+     * `valid` a check, `invalid` the same red state as `error`. `error` wins when both are set.
+     * While shown, `statusMessage` replaces the hint.
+     */
+    status?: FormFieldStatus;
+    /** The words for `status`. The icon and these carry the meaning, never the colour alone. */
+    statusMessage?: ReactNode;
+    /**
+     * Repeat `statusMessage` in a polite live region (`role="status"`). Only changes are
+     * announced, never what was there on first render.
+     */
+    announce?: boolean;
     required?: boolean;
     /** Defaults to a generated id. */
     id?: string;
@@ -28,6 +41,7 @@ export interface FormFieldProps {
     children: ReactElement | ((control: FormFieldControlProps) => ReactNode);
     className?: string;
 }
+export type FormFieldStatus = 'checking' | 'valid' | 'invalid';
 /**
  * A label, a control, a hint and an error, wired together: the label names the control, the
  * hint and error describe it, and the error marks it invalid.
@@ -35,7 +49,7 @@ export interface FormFieldProps {
  * The error is text with an icon, never colour alone. It is not a live region: announcing each
  * field's error as it appears is noisy, and `ErrorSummary` says it once, on submit.
  */
-export declare function FormField({ label, hint, error, required, id: idProp, layout, children, className, }: FormFieldProps): import("react").JSX.Element;
+export declare function FormField({ label, hint, error, status, statusMessage, announce, required, id: idProp, layout, children, className, }: FormFieldProps): import("react").JSX.Element;
 export interface FormFieldsetProps {
     /** Names the group: "Notifications", "Plan". */
     legend: ReactNode;

package/dist/molecules/FormField/FormField.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { ExclamationTriangleIcon } from '@radix-ui/react-icons';
-import { cloneElement, isValidElement, useId } from 'react';
+import { CheckCircledIcon, ExclamationTriangleIcon } from '@radix-ui/react-icons';
+import { Spinner as ThemedSpinner } from '@radix-ui/themes';
+import { cloneElement, isValidElement, useEffect, useId, useRef, useState, } from 'react';
 import { Input } from '../../atoms/Input/Input.js';
 import { Label } from '../../atoms/Label/Label.js';
 import { Select } from '../../atoms/Select/Select.js';
@@ -14,16 +15,29 @@ const INVALID_PROP = new Set([Input, Textarea, Select, PasswordInput]);
  * The error is text with an icon, never colour alone. It is not a live region: announcing each
  * field's error as it appears is noisy, and `ErrorSummary` says it once, on submit.
  */
-export function FormField({ label, hint, error, required, id: idProp, layout = 'stacked', children, className, }) {
+export function FormField({ label, hint, error, status, statusMessage, announce, required, id: idProp, layout = 'stacked', children, className, }) {
     const auto = useId();
     const id = idProp ?? auto;
     const hintId = `${id}-hint`;
     const errorId = `${id}-error`;
-    const describedBy = [hint ? hintId : null, error ? errorId : null].filter(Boolean).join(' ');
+    const statusId = `${id}-status`;
+    // The error wins; a status with words stands in for the hint while it is shown.
+    const shownStatus = !error && status ? status : undefined;
+    const showStatus = !!shownStatus && statusMessage != null && statusMessage !== false;
+    const showHint = !!hint && !showStatus;
+    const invalid = !!error || shownStatus === 'invalid';
+    const describedBy = [
+        showHint ? hintId : null,
+        showStatus ? statusId : null,
+        error ? errorId : null,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    const announced = useAnnouncement(showStatus ? statusMessage : null, shownStatus, statusMessage);
     const control = {
         id,
         'aria-describedby': describedBy || undefined,
-        'aria-invalid': error ? true : undefined,
+        'aria-invalid': invalid ? true : undefined,
         required: required || undefined,
     };
     let rendered;
@@ -35,7 +49,7 @@ export function FormField({ label, hint, error, required, id: idProp, layout = '
         // Passing the key at all, even as undefined, would override theirs, so it is left out.
         const { 'aria-invalid': ariaInvalid, ...rest } = control;
         const props = INVALID_PROP.has(children.type)
-            ? { ...rest, invalid: !!error }
+            ? { ...rest, invalid }
             : { ...rest, ...(ariaInvalid ? { 'aria-invalid': ariaInvalid } : {}) };
         rendered = cloneElement(children, props);
     }
@@ -43,13 +57,40 @@ export function FormField({ label, hint, error, required, id: idProp, layout = '
         rendered = children;
     }
     const labelEl = (_jsx(Label, { htmlFor: id, required: required, children: label }));
-    const hintEl = hint ? (_jsx("p", { id: hintId, className: "ui-field__hint", children: hint })) : null;
-    const errorEl = error ? _jsx(FieldError, { id: errorId, children: error }) : null;
-    return (_jsx("div", { className: ['ui-field', className].filter(Boolean).join(' '), "data-layout": layout, children: layout === 'inline' ? (_jsxs(_Fragment, { children: [_jsx("span", { className: "ui-field__control", children: rendered }), _jsxs("span", { className: "ui-field__text", children: [labelEl, hintEl, errorEl] })] })) : (_jsxs(_Fragment, { children: [labelEl, hintEl, rendered, errorEl] })) }));
+    const hintEl = showHint ? (_jsx("p", { id: hintId, className: "ui-field__hint", children: hint })) : null;
+    const errorEl = error ? (_jsx(FieldError, { id: errorId, children: error })) : showStatus && shownStatus ? (_jsx(FieldStatus, { id: statusId, status: shownStatus, children: statusMessage })) : null;
+    // Always mounted while opted in, so a change is a change to an existing region.
+    const liveEl = announce ? (_jsx("span", { role: "status", className: "ui-sr-only", children: announced })) : null;
+    return (_jsx("div", { className: ['ui-field', className].filter(Boolean).join(' '), "data-layout": layout, children: layout === 'inline' ? (_jsxs(_Fragment, { children: [_jsx("span", { className: "ui-field__control", children: rendered }), _jsxs("span", { className: "ui-field__text", children: [labelEl, hintEl, errorEl] }), liveEl] })) : (_jsxs(_Fragment, { children: [labelEl, hintEl, rendered, errorEl, liveEl] })) }));
 }
 function FieldError({ id, children }) {
     return (_jsxs("p", { id: id, className: "ui-field__error", children: [_jsx(ExclamationTriangleIcon, { "aria-hidden": "true" }), _jsx("span", { children: children })] }));
 }
+function FieldStatus({ id, status, children, }) {
+    if (status === 'invalid')
+        return _jsx(FieldError, { id: id, children: children });
+    return (_jsxs("p", { id: id, className: "ui-field__status", "data-status": status, children: [status === 'checking' ? (_jsx("span", { "aria-hidden": "true", className: "ui-field__status-icon", children: _jsx(ThemedSpinner, { size: "1" }) })) : (_jsx(CheckCircledIcon, { "aria-hidden": "true" })), _jsx("span", { children: children })] }));
+}
+/**
+ * What the live region holds: empty on first render, then the message whenever the status or
+ * message changes. A region that mounts with text is announced by some screen readers and not
+ * others, so it mounts empty and only ever receives changes.
+ */
+function useAnnouncement(message, status, source) {
+    const [text, setText] = useState(null);
+    const first = useRef(true);
+    const latest = useRef(message);
+    latest.current = message;
+    // biome-ignore lint/correctness/useExhaustiveDependencies: keyed on what changed, read through the ref.
+    useEffect(() => {
+        if (first.current) {
+            first.current = false;
+            return;
+        }
+        setText(latest.current);
+    }, [status, source]);
+    return text;
+}
 /**
  * A `fieldset` for controls that answer one question together. The legend names the group;
  * hint and error describe it.

package/dist/molecules/MentionTextarea/MentionTextarea.d.ts

@@ -0,0 +1,46 @@
+import { type ReactNode } from 'react';
+import { type TextareaProps } from '../../atoms/Textarea/Textarea.js';
+export interface MentionOption {
+    value: string;
+    label: ReactNode;
+    /** Secondary text, shown muted beside the label. */
+    detail?: ReactNode;
+}
+/** The token under the caret: its trigger, the kind it maps to, the query and where it sits. */
+export interface MentionToken {
+    trigger: string;
+    kind: string;
+    query: string;
+    /** Index of the trigger character. */
+    start: number;
+    /** Index just past the token (the caret). */
+    end: number;
+}
+export interface MentionTextareaProps extends Omit<TextareaProps, 'value' | 'defaultValue' | 'onChange' | 'role'> {
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    /** Trigger character → kind, e.g. `{ '$': 'ticker', '@': 'member' }`. */
+    triggers: Record<string, string>;
+    /** The options for a token. May be async; an answer to an older query is dropped. */
+    onQuery: (kind: string, query: string) => MentionOption[] | Promise<MentionOption[]>;
+    /**
+     * Returns the new text and caret, or nothing to leave the text alone.
+     * Default: replace the token with `<trigger><value> `.
+     */
+    onPick?: (option: MentionOption, token: MentionToken, text: string) => {
+        value: string;
+        caret: number;
+    } | undefined;
+}
+/** The token ending at `caret`: a trigger at the start or after whitespace, then no whitespace. */
+export declare function findMentionToken(text: string, caret: number, triggers: Record<string, string>): MentionToken | null;
+/**
+ * A Textarea that is also an ARIA combobox for inline tokens such as `@ana` or `$AAPL`.
+ *
+ * Typing a trigger opens a listbox under the field. Arrow keys move the active option, announced
+ * through `aria-activedescendant` so focus never leaves the textarea; Enter or Tab picks it and
+ * Escape closes the list. Options are picked on mousedown with the default prevented, so the
+ * textarea keeps focus and the caret. Colours are Radix tokens, so the list follows light and dark.
+ */
+export declare const MentionTextarea: import("react").ForwardRefExoticComponent<MentionTextareaProps & import("react").RefAttributes<HTMLTextAreaElement>>;

package/dist/molecules/MentionTextarea/MentionTextarea.js

@@ -0,0 +1,158 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useRef, useState, } from 'react';
+import { Textarea } from '../../atoms/Textarea/Textarea.js';
+import { useUiStrings } from '../../strings.js';
+/** The token ending at `caret`: a trigger at the start or after whitespace, then no whitespace. */
+export function findMentionToken(text, caret, triggers) {
+    for (let i = caret - 1; i >= 0; i--) {
+        const ch = text[i];
+        if (/\s/.test(ch))
+            return null;
+        const kind = triggers[ch];
+        if (kind !== undefined && (i === 0 || /\s/.test(text[i - 1]))) {
+            return { trigger: ch, kind, query: text.slice(i + 1, caret), start: i, end: caret };
+        }
+    }
+    return null;
+}
+function defaultPick(option, token, text) {
+    const insert = `${token.trigger}${option.value} `;
+    return {
+        value: text.slice(0, token.start) + insert + text.slice(token.end),
+        caret: token.start + insert.length,
+    };
+}
+/**
+ * A Textarea that is also an ARIA combobox for inline tokens such as `@ana` or `$AAPL`.
+ *
+ * Typing a trigger opens a listbox under the field. Arrow keys move the active option, announced
+ * through `aria-activedescendant` so focus never leaves the textarea; Enter or Tab picks it and
+ * Escape closes the list. Options are picked on mousedown with the default prevented, so the
+ * textarea keeps focus and the caret. Colours are Radix tokens, so the list follows light and dark.
+ */
+export const MentionTextarea = forwardRef(function MentionTextarea({ value, defaultValue = '', onValueChange, triggers, onQuery, onPick = defaultPick, onKeyDown, onBlur, onSelect, id, ...props }, ref) {
+    const strings = useUiStrings();
+    const autoId = useId();
+    const listId = `${id ?? autoId}-listbox`;
+    const optionId = (i) => `${listId}-${i}`;
+    const area = useRef(null);
+    useImperativeHandle(ref, () => area.current);
+    const [text, setText] = useState(value ?? defaultValue);
+    const [token, setToken] = useState(null);
+    const [options, setOptions] = useState([]);
+    const [active, setActive] = useState(0);
+    const request = useRef(0);
+    const pendingCaret = useRef(null);
+    useEffect(() => {
+        if (value !== undefined)
+            setText(value);
+    }, [value]);
+    // After a pick re-renders the text, put the caret after the inserted token.
+    useEffect(() => {
+        if (pendingCaret.current === null || !area.current)
+            return;
+        area.current.setSelectionRange(pendingCaret.current, pendingCaret.current);
+        pendingCaret.current = null;
+    });
+    const close = useCallback(() => {
+        request.current++;
+        setToken(null);
+        setOptions([]);
+    }, []);
+    const detect = useCallback((nextText, caret) => {
+        const found = findMentionToken(nextText, caret, triggers);
+        if (!found) {
+            close();
+            return;
+        }
+        setToken((prev) => prev && prev.start === found.start && prev.query === found.query ? prev : found);
+        const ticket = ++request.current;
+        Promise.resolve(onQuery(found.kind, found.query)).then((result) => {
+            if (ticket !== request.current)
+                return;
+            setOptions(result);
+            setActive(0);
+        });
+    }, [triggers, onQuery, close]);
+    const commit = (next) => {
+        if (value === undefined)
+            setText(next);
+        onValueChange?.(next);
+    };
+    const pick = (option) => {
+        if (!token)
+            return;
+        const result = onPick(option, token, text);
+        close();
+        if (!result)
+            return;
+        pendingCaret.current = result.caret;
+        commit(result.value);
+    };
+    const open = token !== null && options.length > 0;
+    const handleKeyDown = (event) => {
+        if (open) {
+            if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+                event.preventDefault();
+                const step = event.key === 'ArrowDown' ? 1 : -1;
+                setActive((a) => (a + step + options.length) % options.length);
+                return;
+            }
+            if ((event.key === 'Enter' && !event.shiftKey) || event.key === 'Tab') {
+                event.preventDefault();
+                pick(options[active]);
+                return;
+            }
+            if (event.key === 'Escape') {
+                event.preventDefault();
+                event.stopPropagation();
+                close();
+                return;
+            }
+        }
+        onKeyDown?.(event);
+    };
+    return (_jsxs("div", { style: { position: 'relative' }, children: [_jsx(Textarea, { ...props, id: id, ref: area, value: text, role: "combobox", "aria-autocomplete": "list", "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": open ? listId : undefined, "aria-activedescendant": open ? optionId(active) : undefined, onChange: (event) => {
+                    const next = event.target.value;
+                    commit(next);
+                    detect(next, event.target.selectionStart ?? next.length);
+                }, onSelect: (event) => {
+                    const el = event.currentTarget;
+                    if (el.selectionStart === el.selectionEnd)
+                        detect(el.value, el.selectionStart);
+                    else
+                        close();
+                    onSelect?.(event);
+                }, onKeyDown: handleKeyDown, onBlur: (event) => {
+                    close();
+                    onBlur?.(event);
+                } }), open && (_jsx("div", { id: listId, role: "listbox", "aria-label": strings.suggestions, className: "ui-mention-listbox", style: {
+                    position: 'absolute',
+                    insetInlineStart: 0,
+                    insetInlineEnd: 0,
+                    top: '100%',
+                    marginTop: 4,
+                    zIndex: 50,
+                    maxHeight: 240,
+                    overflowY: 'auto',
+                    padding: 4,
+                    background: 'var(--color-panel-solid)',
+                    color: 'var(--gray-12)',
+                    border: '1px solid var(--gray-a6)',
+                    borderRadius: 'var(--radius-3)',
+                    boxShadow: 'var(--shadow-4)',
+                }, children: options.map((option, i) => (_jsxs("div", { id: optionId(i), role: "option", tabIndex: -1, "aria-selected": i === active, onMouseDown: (event) => {
+                        event.preventDefault();
+                        pick(option);
+                    }, onMouseMove: () => setActive(i), style: {
+                        display: 'flex',
+                        gap: 8,
+                        alignItems: 'baseline',
+                        padding: '6px 8px',
+                        minHeight: 32,
+                        borderRadius: 'var(--radius-2)',
+                        cursor: 'pointer',
+                        background: i === active ? 'var(--accent-a4)' : undefined,
+                        color: i === active ? 'var(--accent-12)' : undefined,
+                    }, children: [_jsx("span", { children: option.label }), option.detail != null && (_jsx("span", { style: { color: 'var(--gray-11)', fontSize: 'var(--font-size-1)' }, children: option.detail }))] }, option.value))) }))] }));
+});

package/dist/molecules/MentionTextarea/index.d.ts

@@ -0,0 +1 @@
+export * from './MentionTextarea.js';

package/dist/molecules/MentionTextarea/index.js

@@ -0,0 +1 @@
+export * from './MentionTextarea.js';

package/dist/molecules/index.d.ts

@@ -12,6 +12,7 @@ export * from './FormField/index.js';
 export * from './FormSection/index.js';
 export * from './KeyValueList/index.js';
 export * from './LoadingState/index.js';
+export * from './MentionTextarea/index.js';
 export * from './NavItem/index.js';
 export * from './Pagination/index.js';
 export * from './PasswordInput/index.js';

package/dist/molecules/index.js

@@ -12,6 +12,7 @@ export * from './FormField/index.js';
 export * from './FormSection/index.js';
 export * from './KeyValueList/index.js';
 export * from './LoadingState/index.js';
+export * from './MentionTextarea/index.js';
 export * from './NavItem/index.js';
 export * from './Pagination/index.js';
 export * from './PasswordInput/index.js';

package/dist/strings.d.ts

@@ -128,6 +128,8 @@ export interface UiStrings {
     viewAsChart: string;
     /** PasswordInput: the visibility toggle's name. It is a toggle (`aria-pressed`), so one name. */
     showPassword: string;
+    /** MentionTextarea: the name of the listbox of suggestions for the token at the caret. */
+    suggestions: string;
 }
 /**
  * Feeds the components their strings, once, near the root.

package/dist/strings.js

@@ -72,6 +72,7 @@ const DEFAULTS = {
     viewAsTable: 'View as table',
     viewAsChart: 'View as chart',
     showPassword: 'Show password',
+    suggestions: 'Suggestions',
 };
 const StringsContext = createContext(DEFAULTS);
 const LocaleContext = createContext(undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kennycorrea/ui",
-  "version": "1.8.1",
+  "version": "1.8.4",
   "description": "A React + TypeScript component library built on Radix Themes: atoms, a Tailwind token bridge and theming.",
   "private": false,
   "type": "module",

package/tokens.css

@@ -1274,6 +1274,10 @@
 .ui-field__hint { margin: 0; font-size: 13px; color: var(--color-ink-muted); }
 .ui-field__error { display: flex; align-items: flex-start; gap: 6px; margin: 0; font-size: 13px; font-weight: 500; color: var(--red-11); }
 .ui-field__error svg { flex: none; margin-block-start: 2px; }
+.ui-field__status { display: flex; align-items: flex-start; gap: 6px; margin: 0; font-size: 13px; color: var(--color-ink-muted); }
+.ui-field__status[data-status="valid"] { font-weight: 500; color: var(--color-good-ink); }
+.ui-field__status svg, .ui-field__status-icon { flex: none; margin-block-start: 2px; }
+.ui-field__status-icon { display: inline-flex; }
 .ui-fieldset { display: flex; flex-direction: column; gap: 8px; min-inline-size: 0; margin: 0; padding: 0; border: 0; }
 .ui-fieldset__legend { padding: 0; margin-block-end: 2px; font-size: 14px; font-weight: 500; color: var(--color-ink); }