@weft-js/warp 0.0.0-stage → 0.1.0

package/src/Field.tsx

@@ -0,0 +1,147 @@
+import { AlertIcon, SearchIcon, XIcon } from '@weft-js/warp-icons'
+import { field, formInvalid, formReset, labelChars, uid } from '@weft-js/warp-core'
+import { derived, state, untrack } from '@weft-js/core'
+import { Icon, type IconRef } from './Icon'
+import { use } from '@weft-js/warp-core/weft'
+import './fields'
+import '@weft-js/warp-core/styles/inputs/text.css'
+
+interface FieldBase {
+  /** The accessible name, drawn as the floating border label (or above, classic). Required. */
+  label: string
+  hint?: unknown
+  /** Shown instead of the hint; marks the field invalid. */
+  error?: unknown
+  /** Leading icon: it sweeps with the border. */
+  icon?: IconRef | undefined
+  /** Text or an element inside the field before the value, such as `$`. */
+  prefix?: unknown
+  /** Text or an element inside the field after the value, such as `kg`. */
+  suffix?: unknown
+  /** floating (default, or the app's `warp({ fields })`) · classic: the label above. */
+  variant?: 'floating' | 'classic' | undefined
+  /** `line`: only a bottom line under the value, no box or fill. The boxed field otherwise. */
+  appearance?: 'line' | undefined
+  size?: 'sm' | 'md' | 'lg' | undefined
+  /** A clear button (shown once there is a value). */
+  clearable?: boolean | undefined
+  /** Maximum length, shown as a counter. */
+  counter?: number | undefined
+  id?: string | undefined
+  value?: string | undefined
+  disabled?: boolean | undefined
+  /** Shows the value and lets it be selected and copied, but not changed. */
+  readonly?: boolean | undefined
+  onInput?: ((e: InputEvent & { currentTarget: HTMLInputElement & HTMLTextAreaElement }) => void) | undefined
+}
+
+/** Props for the text fields; anything else lands on the control. */
+export interface FieldProps extends FieldBase { [attr: string]: unknown }
+
+/** FieldProps for a component with its own value type: Omit on FieldProps would drop what the index signature hides. */
+export type FieldShell = Omit<FieldBase, 'value' | 'defaultValue'> & { [attr: string]: unknown }
+
+// `invalid` is a getter and `rest` the live props: the control is made once and its attributes update in place
+export type Control = (p: { id: string; readonly describedby?: string | undefined; readonly invalid: boolean; rest: Record<string, unknown> }) => unknown
+
+/**
+ * The field shell (03 §1 anatomy, verbatim order): control (sweep-base, sweep, icon, label, prefix, input, suffix,
+ * clear, end slot) then message (hint | error, counter). Everything is in the server HTML, label letters included;
+ * after mount warp-core's field() measures the label's per-letter delays and notch and wires clear, counter and focus.
+ */
+export function Field({ label, hint, error, icon, prefix, suffix, variant, appearance, size, clearable, counter, id: given, control, end, filled, attrs, group, labelled, hold, wrap, reset, ...rest }: FieldProps & { control: Control; end?: unknown; filled?: boolean; attrs?: Record<string, unknown>; group?: boolean; /** The control takes its name from `aria-labelledby`, not `for`: a press on the label must not click a button. */ labelled?: boolean; hold?: boolean; wrap?: boolean; /** Puts held state back when the field's form resets. */ reset?: () => void }) {
+  const id = untrack(() => given) ?? uid('field')
+  // the browser's message for a constraint that failed (03 §1.3): `error` wins over it
+  const missing = state<string | undefined>(undefined)
+  const problem = derived(() => error ?? missing.value)
+  const glyph = derived(() => icon)
+  // an error can arrive long after mount, so the block and what points at it follow it
+  const message = derived(() => hint !== undefined || !!problem.value || counter !== undefined)
+  const msg = derived(() => (message.value ? `${id}-msg` : undefined))
+  // keyed by position: a label repeats letters
+  const chars = derived(() => labelChars(String((label as string | number | undefined) ?? '')).map((c, at) => ({ c, at })))
+  // one omit() for every read: the compiler expands `rest` afresh at each use (the proxy reads stay live)
+  const live = untrack(() => rest)
+  let root: HTMLDivElement | undefined
+  const shell = { id, get describedby() { return msg.value }, get invalid() { return !!problem.value }, rest: live }
+  use(field, () => root, () => [live.value, label] as const)
+  use(formInvalid, () => root, () => (m: string | undefined) => (missing.value = m))
+  if (untrack(() => reset)) use(formReset, () => root, () => () => reset!())
+  return (
+    <div
+      ref={n => (root = n)}
+      data-scope="field"
+      data-variant={variant}
+      data-appearance={appearance}
+      data-size={size === 'md' ? undefined : size}
+      data-counter={counter}
+      data-invalid={problem.value ? '' : undefined}
+      data-disabled={live.disabled ? '' : undefined}
+      data-readonly={live.readonly ? '' : undefined}
+      {...attrs}
+    >
+      <div data-part="control" data-icon={typeof glyph.value === 'string' ? glyph.value : glyph.value ? '' : undefined} data-sweep="" data-filled={filled ?? live.value ? '' : undefined} data-hold={hold ? '' : undefined} data-wrap={wrap ? '' : undefined}>
+        <span data-part="sweep-base" aria-hidden="true"></span><span data-part="sweep" aria-hidden="true"></span>
+        {glyph.value && <span data-part="icon" aria-hidden="true"><span data-part="sweep-base"><Icon name={glyph.value} /></span><span data-part="sweep"><Icon name={glyph.value} /></span></span>}
+        <label data-part="label" for={group || labelled ? undefined : id} id={group || labelled ? `${id}-l` : undefined}>
+          <span data-part="label-text">{label}</span>
+          <span data-part="label-chars" aria-hidden="true">{chars.value.map(x => <span key={x.at} data-char data-c={x.c}></span>)}</span>
+        </label>
+        {prefix !== undefined && <span data-part="prefix">{prefix}</span>}
+        {group
+          ? <div data-part="body" role="group" aria-labelledby={`${id}-l`} aria-describedby={msg.value} aria-invalid={problem.value ? 'true' : undefined}>{untrack(() => control(shell))}</div>
+          : untrack(() => control(shell))}
+        {suffix !== undefined && <span data-part="suffix">{suffix}</span>}
+        {clearable && <button type="button" data-part="clear" tabindex="-1" aria-label={`Clear ${label}`}><XIcon /></button>}
+        {end}
+      </div>
+      {message.value && (
+        <div data-part="message" id={msg.value}>
+          {problem.value ? <span data-part="error" role="alert"><AlertIcon /><span>{problem.value}</span></span> : hint !== undefined && <span data-part="hint">{hint}</span>}
+          {counter !== undefined && <span data-part="counter" aria-live="off"></span>}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/** A text field. Every native input attribute passes through (type, autocomplete, inputmode, onInput…). */
+export function Input({ placeholder, ...props }: FieldProps & { placeholder?: string; type?: string }) {
+  return (
+    <Field
+      {...props}
+      control={p => (
+        // a placeholder, " " at least: the label floats on :placeholder-shown (03 §1 decision 3)
+        <input data-part="input" id={p.id} placeholder={placeholder ?? ' '} aria-describedby={p.describedby} aria-invalid={p.invalid ? 'true' : undefined} {...p.rest} />
+      )}
+    />
+  )
+}
+
+/** A search field: the search icon, type=search, a clear button (03 §3 SearchInput; suggestions come with Combobox). */
+export function Search({ placeholder, ...props }: FieldProps & { placeholder?: string }) {
+  return (
+    <Field
+      icon={SearchIcon}
+      clearable
+      {...props}
+      attrs={{ role: 'search' }}
+      control={p => (
+        <input data-part="input" id={p.id} type="search" enterkeyhint="search" autocomplete="off" placeholder={placeholder ?? ' '} aria-describedby={p.describedby} aria-invalid={p.invalid ? 'true' : undefined} {...p.rest} />
+      )}
+    />
+  )
+}
+
+/** A textarea: grows from `rows` lines (3) to 10 or `rows`, Cmd/Ctrl+Enter submits its form (03 §3). */
+export function Textarea({ placeholder, rows = 3, ...props }: FieldProps & { placeholder?: string; rows?: number }) {
+  return (
+    <Field
+      {...props}
+      control={p => (
+        // field-sizing: content ignores the rows attribute, so the height reads it from --_rows
+        <textarea data-part="input" id={p.id} rows={rows} style={`--_rows:${rows}`} enterkeyhint="enter" placeholder={placeholder ?? ' '} aria-describedby={p.describedby} aria-invalid={p.invalid ? 'true' : undefined} {...p.rest}>{untrack(() => p.rest.value)}</textarea>
+      )}
+    />
+  )
+}

package/src/Icon.tsx

@@ -0,0 +1,8 @@
+// warp's `icon` props: a name, or an icon from @weft-js/warp-icons. warp's own fixed glyphs import their icon directly.
+import './styles'
+import { AlertIcon, AlertCircleIcon, CheckCircleIcon, InfoIcon } from '@weft-js/warp-icons'
+
+/** `<svg data-icon aria-hidden focusable=false>`: decorative, never named (03 §7); `label` names it. */
+export { Icon, type IconName, type IconRef } from '@weft-js/warp-icons/icon'
+
+export const toneIcon = { info: InfoIcon, neutral: InfoIcon, accent: InfoIcon, positive: CheckCircleIcon, caution: AlertIcon, critical: AlertCircleIcon } as const

package/src/Kbd.tsx

@@ -0,0 +1,6 @@
+import './styles'
+
+/** One key (05 §6): `<Kbd>⌘</Kbd><Kbd>K</Kbd>`. */
+export function Kbd({ children }: { children: unknown }) {
+  return <kbd data-scope="kbd">{children}</kbd>
+}

package/src/KeyValueEditor.tsx

@@ -0,0 +1,114 @@
+import { XIcon } from '@weft-js/warp-icons'
+import { flush, onCleanup, state, untrack } from '@weft-js/core'
+import { formReset } from '@weft-js/warp-core'
+import { bindable, type Bindable } from './bind'
+import { Button } from './Button'
+import { Segmented } from './Choice'
+import { JsonEditor } from './CodeInput'
+import { Field, type FieldShell } from './Field'
+import { use } from '@weft-js/warp-core/weft'
+import '@weft-js/warp-core/styles/rich/body.css'
+import '@weft-js/warp-core/styles/rich/key-value.css'
+
+/** One row of a KeyValueEditor. */
+export type KeyValue = { key: string; value: string }
+
+/** Props for KeyValueEditor. */
+export type KeyValueEditorProps = FieldShell & Bindable<KeyValue[]> & {
+  keyLabel?: string
+  valueLabel?: string
+  /** A Form ⇄ JSON switch; both keep the value. */
+  json?: boolean
+}
+
+const toJson = (rows: KeyValue[]) => JSON.stringify(Object.fromEntries(rows.filter(r => r.key).map(r => [r.key, r.value])), null, 2)
+
+/**
+ * A table of `key | value | remove` rows with Add row (04 KeyValueEditor). A duplicate key is a caution, not a block.
+ * With `json`, a Form ⇄ JSON switch shows the same value as a JsonEditor. Rows keep their identity, so typing never
+ * loses focus; adding focuses the new key, removing the row before.
+ */
+export function KeyValueEditor({ value, defaultValue, onValueChange, keyLabel = 'Key', valueLabel = 'Value', json, hint, ...rest }: KeyValueEditorProps) {
+  const held = bindable<KeyValue[]>(() => value, () => defaultValue, [], () => onValueChange)
+  let serial = 0
+  const ids = state(untrack(() => held.value.map(() => ++serial)))
+  const mode = state<'form' | 'json'>('form')
+  const text = state('')
+  let body: HTMLElement | undefined
+  let timer: ReturnType<typeof setTimeout> | undefined
+  onCleanup(() => clearTimeout(timer))
+  const dup = (rows: KeyValue[], at: number) => !!rows[at]!.key && rows.findIndex(r => r.key === rows[at]!.key) !== at
+  const hasDup = () => held.value.some((_, at) => dup(held.value, at))
+  const edit = (at: number, part: 'key' | 'value', v: string) => held.set(held.value.map((r, n) => (n === at ? { ...r, [part]: v } : r)), 'keyboard')
+  const add = () => {
+    held.set([...held.value, { key: '', value: '' }], 'pointer')
+    ids.value = [...ids.value, ++serial]
+    flush()
+    body?.querySelector<HTMLElement>('tbody tr:last-child input')?.focus()
+  }
+  const remove = (at: number) => {
+    held.set(held.value.filter((_, n) => n !== at), 'pointer')
+    ids.value = ids.value.filter((_, n) => n !== at)
+    flush()
+    const left = body?.querySelectorAll<HTMLElement>('[data-part="remove"]')
+    ;(left?.[Math.min(at, (left?.length ?? 1) - 1)] ?? body?.querySelector<HTMLElement>('[data-part="add"]'))?.focus()
+  }
+  const flipMode = (m: 'form' | 'json') => {
+    if (m === 'json') text.value = toJson(held.value)
+    mode.value = m
+  }
+  const fromJson = (v: string) => {
+    text.value = v
+    clearTimeout(timer)
+    timer = setTimeout(() => {
+      try {
+        const o = JSON.parse(v)
+        if (!o || typeof o !== 'object' || Array.isArray(o)) return
+        const rows = Object.entries(o).map(([key, val]) => ({ key, value: typeof val === 'string' ? val : JSON.stringify(val) }))
+        held.set(rows, 'keyboard')
+        ids.value = rows.map(() => ++serial)
+      } catch { /* the editor shows the error; the last good value stands */ }
+    }, 250)
+  }
+  const switcher = untrack(() => json) ? <Segmented label={`${rest.label} format`} size="sm" value={mode.value} options={[{ value: 'form', label: 'Form' }, { value: 'json', label: 'JSON' }]} onChange={m => flipMode(m)} /> : undefined
+  let root: HTMLDivElement | undefined
+  use(formReset, () => root, () => () => {
+    clearTimeout(timer)
+    held.reset()
+    ids.value = held.value.map(() => ++serial)
+    text.value = toJson(held.value)
+  })
+  return (
+    <div ref={n => (root = n)} data-scope="kv">
+      {switcher}
+      {mode.value === 'json'
+        ? <JsonEditor {...rest} value={text.value} onValueChange={fromJson} />
+        : (
+          <Field
+            {...rest}
+            group
+            filled
+            hint={hasDup() ? 'That key is already here: the last one wins.' : hint}
+            attrs={{ 'data-multiline': '' }}
+            control={() => (
+              <div ref={n => (body = n)}>
+                <table>
+                  <thead><tr><th scope="col">{keyLabel}</th><th scope="col">{valueLabel}</th><th scope="col"><span data-part="sr-only">Remove</span></th></tr></thead>
+                  <tbody>
+                    {ids.value.map((rowId, at) => (
+                      <tr key={rowId}>
+                        <td><input aria-label={`${keyLabel}, row ${at + 1}`} value={held.value[at]?.key ?? ''} data-duplicate={held.value[at] && dup(held.value, at) ? '' : undefined} onInput={(e: Event) => edit(at, 'key', (e.currentTarget as HTMLInputElement).value)} /></td>
+                        <td><input aria-label={`${valueLabel}, row ${at + 1}`} value={held.value[at]?.value ?? ''} onInput={(e: Event) => edit(at, 'value', (e.currentTarget as HTMLInputElement).value)} /></td>
+                        <td><button type="button" data-part="remove" aria-label={`Remove row ${at + 1}`} onClick={() => remove(at)}><XIcon /></button></td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+                <Button emphasis="ghost" tone="neutral" size="sm" data-part="add" onClick={add}>Add row</Button>
+              </div>
+            )}
+          />
+        )}
+    </div>
+  )
+}

package/src/Layout.tsx

@@ -0,0 +1,109 @@
+// Layout primitives (02 §3, PLAN §6): each is the spec's `data-scope` box and nothing else. Relationships, not pixels:
+// `gap` is the closed Space scale, widths are named, and there is no breakpoint prop, since the boxes answer to their
+// container. `as` picks the element from the tags below; weft has no dynamic tag, so each is one compiled template.
+import { untrack } from '@weft-js/core'
+import type { Space } from '@weft-js/core/ds'
+import './styles'
+import '@weft-js/warp-core/styles/layout/tokens.css'
+import '@weft-js/warp-core/styles/layout/base.css'
+import '@weft-js/warp-core/styles/layout/stack.css'
+import '@weft-js/warp-core/styles/layout/row.css'
+import '@weft-js/warp-core/styles/layout/grid.css'
+import '@weft-js/warp-core/styles/layout/split.css'
+import '@weft-js/warp-core/styles/layout/center.css'
+import '@weft-js/warp-core/styles/layout/cover.css'
+import '@weft-js/warp-core/styles/layout/frame.css'
+import '@weft-js/warp-core/styles/layout/spacer.css'
+import '@weft-js/warp-core/styles/layout/inset.css'
+import './layout.css'
+
+type Open = { children?: unknown; [attr: string]: unknown }
+type Tag = keyof typeof TAGS
+/** A breakpoint a layout can switch at. */
+export type Step = 'tablet' | 'desktop'
+type Box = Open & { as?: Tag | undefined; gap?: Space | undefined }
+
+function Div({ children, ...rest }: Open) {
+  return <div {...rest}>{children}</div>
+}
+function Section({ children, ...rest }: Open) {
+  return <section {...rest}>{children}</section>
+}
+function Article({ children, ...rest }: Open) {
+  return <article {...rest}>{children}</article>
+}
+function Main({ children, ...rest }: Open) {
+  return <main {...rest}>{children}</main>
+}
+function Header({ children, ...rest }: Open) {
+  return <header {...rest}>{children}</header>
+}
+function Footer({ children, ...rest }: Open) {
+  return <footer {...rest}>{children}</footer>
+}
+function Nav({ children, ...rest }: Open) {
+  return <nav {...rest}>{children}</nav>
+}
+function Aside({ children, ...rest }: Open) {
+  return <aside {...rest}>{children}</aside>
+}
+function Form({ children, ...rest }: Open) {
+  return <form {...rest}>{children}</form>
+}
+function Ul({ children, ...rest }: Open) {
+  return <ul {...rest}>{children}</ul>
+}
+function Ol({ children, ...rest }: Open) {
+  return <ol {...rest}>{children}</ol>
+}
+const TAGS = { div: Div, section: Section, article: Article, main: Main, header: Header, footer: Footer, nav: Nav, aside: Aside, form: Form, ul: Ul, ol: Ol }
+
+function Element({ as, ...rest }: Box) {
+  const Tag = TAGS[untrack(() => as) ?? 'div']
+  return <Tag {...rest} />
+}
+
+/** Vertical flow; the gap is the relationship between the children. */
+export function Stack({ gap, align, divided, ...rest }: Box & { align?: 'start' | 'center' | 'end' | undefined; divided?: boolean | undefined }) {
+  return <Element data-scope="stack" data-gap={gap} data-align={align} data-divided={divided ? '' : undefined} {...rest} />
+}
+
+/** A horizontal cluster that wraps. `reflow` makes it a Stack below that step; `wrap={false}` keeps it on one line. */
+export function Row({ gap, justify, align, wrap, reflow, ...rest }: Box & { justify?: 'start' | 'between' | 'end' | 'center' | undefined; align?: 'start' | 'baseline' | undefined; wrap?: boolean | undefined; reflow?: Step | undefined }) {
+  return <Element data-scope="row" data-gap={gap} data-justify={justify === 'start' ? undefined : justify} data-align={align} data-wrap={wrap === false ? 'none' : undefined} data-reflow={reflow} {...rest} />
+}
+
+/** Intrinsic columns: as many as fit at `min`, never more than `cols`. A child with `data-span="full"` takes the row. */
+export function Grid({ gap, min, cols, ...rest }: Box & { min?: 'xs' | 'sm' | 'md' | 'lg' | undefined; cols?: 2 | 3 | 4 | 6 | undefined }) {
+  return <Element data-scope="grid" data-gap={gap} data-min={min} data-cols={cols} {...rest} />
+}
+
+/** A fixed side and a fluid main, stacked below its step. Each child is a container. */
+export function Split({ gap, side, width, at, ...rest }: Box & { side?: 'start' | 'end' | undefined; width?: 'rail' | 'nav' | 'list' | 'half' | undefined; at?: Step | undefined }) {
+  return <Element data-scope="split" data-gap={gap} data-side={side === 'start' ? undefined : side} data-width={width} data-at={at === 'tablet' ? undefined : at} {...rest} />
+}
+
+/** A measured column, centred, with page gutters when `gutter` is set. */
+export function Center({ max, gutter, intrinsic, ...rest }: Box & { max?: 'measure' | 'narrow' | 'content' | 'wide' | undefined; gutter?: boolean | undefined; intrinsic?: boolean | undefined }) {
+  return <Element data-scope="center" data-max={max === 'content' ? undefined : max} data-gutter={gutter ? '' : undefined} data-intrinsic={intrinsic ? '' : undefined} {...rest} />
+}
+
+/** Fills the screen: the child with `data-part="center"` is centred, a header and footer hug the edges (auth, error pages). */
+export function Cover({ gap, min, ...rest }: Box & { min?: 'screen' | 'fill' | undefined }) {
+  return <Element data-scope="cover" data-gap={gap} data-min={min === 'screen' ? undefined : min} {...rest} />
+}
+
+/** A fixed-ratio media box with no chrome of its own. */
+export function Frame({ ratio, ...rest }: Box & { ratio?: 'square' | '4:3' | '3:2' | '16:9' | '21:9' | '3:4' | '9:16' | undefined }) {
+  return <Element data-scope="frame" data-ratio={ratio === '16:9' ? undefined : ratio} {...rest} />
+}
+
+/** Takes the free space in a Row or Stack, so what follows sits at the far end. */
+export function Spacer(rest: Open) {
+  return <div data-scope="spacer" {...rest}></div>
+}
+
+/** A sunken, padded region. */
+export function Inset({ pad, ...rest }: Box & { pad?: 'group' | 'section' | undefined }) {
+  return <Element data-scope="inset" data-pad={pad === 'section' ? pad : undefined} {...rest} />
+}

package/src/Markdown.tsx

@@ -0,0 +1,63 @@
+import { markdownToHtml, nextIndex, uid } from '@weft-js/warp-core'
+import { derived, flush, state, untrack } from '@weft-js/core'
+import { bindable, type Bindable } from './bind'
+import { Textarea, type FieldShell } from './Field'
+import './styles'
+import '@weft-js/warp-core/styles/rich/markdown.css'
+import '@weft-js/warp-core/styles/rich/md-editor.css'
+
+/** Markdown, rendered (04 Markdown): a small, safe renderer. Raw HTML is escaped and shows as text. */
+export function Markdown({ source, linkTarget, ...rest }: { source: string; linkTarget?: '_self' | '_blank' | undefined; [attr: string]: unknown }) {
+  return <article data-scope="markdown" {...rest}
+    // oxlint-disable-next-line weft/no-html-sink -- markdownToHtml sanitizes
+    innerHTML={markdownToHtml(source, { linkTarget })}></article>
+}
+
+/** Props for MarkdownEditor. */
+export type MarkdownEditorProps = FieldShell & Bindable<string> & { rows?: number }
+
+const WRAPS: Record<string, [string, string]> = { b: ['**', '**'], i: ['_', '_'], k: ['[', '](https://)'] }
+
+/**
+ * Source and preview (04 MarkdownEditor; inputs-rich.html:2299): side by side from 640px of its own width, tabs below
+ * that. ⌘B, ⌘I and ⌘K wrap the selection, and stay undoable.
+ */
+export function MarkdownEditor({ value, defaultValue, onValueChange, rows = 12, ...rest }: MarkdownEditorProps) {
+  const id = uid('mde')
+  const held = bindable<string>(() => value, () => defaultValue, '', () => onValueChange)
+  const tab = state<'write' | 'preview'>('write')
+  const html = derived(() => markdownToHtml(held.value))
+  const onKey = (e: KeyboardEvent) => {
+    const wrap = (e.metaKey || e.ctrlKey) && WRAPS[e.key.toLowerCase()]
+    if (!wrap) return
+    e.preventDefault()
+    const a = e.currentTarget as HTMLTextAreaElement
+    const { selectionStart: from, selectionEnd: to } = a
+    const text = wrap[0] + a.value.slice(from, to) + wrap[1]
+    if (!document.execCommand?.('insertText', false, text)) a.setRangeText(text, from, to, 'end')
+    a.setSelectionRange(from + wrap[0].length, to + wrap[0].length)
+    held.set(a.value, 'keyboard')
+  }
+  const onTabKey = (e: KeyboardEvent) => {
+    const to = nextIndex(e.key, tab.value === 'write' ? 0 : 1, 2)
+    if (to < 0) return
+    e.preventDefault()
+    tab.value = to ? 'preview' : 'write'
+    flush()
+    ;(e.currentTarget as Element).querySelector<HTMLElement>('[aria-selected="true"]')?.focus()
+  }
+  const button = (name: 'write' | 'preview', text: string) => (
+    <button type="button" role="tab" id={`${id}-${name}`} aria-selected={tab.value === name ? 'true' : 'false'} aria-controls={`${id}-${name}-p`} tabindex={tab.value === name ? '0' : '-1'} onClick={() => (tab.value = name)}>{text}</button>
+  )
+  return (
+    <div data-scope="md-editor" data-tab={tab.value}>
+      <div data-part="tabs" role="tablist" aria-label={untrack(() => rest.label)} onKeyDown={onTabKey}>{button('write', 'Write')}{button('preview', 'Preview')}</div>
+      <div data-part="source" role="tabpanel" id={`${id}-write-p`} aria-labelledby={`${id}-write`}>
+        <Textarea {...rest} reset={held.reset} rows={rows} value={held.value} spellcheck={false} onInput={(e: Event) => held.set((e.currentTarget as HTMLInputElement).value, 'keyboard')} onKeyDown={onKey} />
+      </div>
+      <div data-scope="markdown" role="tabpanel" id={`${id}-preview-p`} aria-labelledby={`${id}-preview`} tabindex="0"
+      // oxlint-disable-next-line weft/no-html-sink -- the preview comes from markdownToHtml, which sanitizes
+      innerHTML={html.value}></div>
+    </div>
+  )
+}

package/src/MentionsInput.tsx

@@ -0,0 +1,150 @@
+import { caretPoint, comboPopup, findTrigger, mentionToken, parseMentions, serializeMentions, shiftMarks, uid, type MentionItem, type MentionMark } from '@weft-js/warp-core'
+import { derived, flush, onCleanup, state, untrack, watch } from '@weft-js/core'
+import { bindable, type Bindable } from './bind'
+import { Field, type FieldShell } from './Field'
+import { use } from '@weft-js/warp-core/weft'
+import '@weft-js/warp-core/styles/rich/listbox.css'
+import '@weft-js/warp-core/styles/rich/popover.css'
+import '@weft-js/warp-core/styles/rich/helpers.css'
+
+/** Props for MentionsInput. */
+export type MentionsInputProps = FieldShell & Bindable<string> & {
+  /** Trigger character → its search. Superseded calls are aborted. */
+  triggers: Record<string, (q: string, signal: AbortSignal) => Promise<MentionItem[]>>
+  rows?: number
+  name?: string | undefined
+}
+
+const initials = (s: string) => s.split(/\s+/).map(w => w[0]).join('').slice(0, 2)
+
+/**
+ * A plain textarea with trigger characters (04 MentionsInput; inputs-rich.html:2367-2401), so paste, autofill and
+ * spellcheck still work. The list opens at the caret: ↑/↓ then Enter or Tab inserts, Esc closes, and an insertion is
+ * announced. The value keeps tokens as `@[Ada Lovelace](user:ada)`; the textarea shows the name, and editing inside a
+ * name turns it back into plain text.
+ */
+export function MentionsInput({ triggers, rows = 3, value, defaultValue, onValueChange, name, hint, ...rest }: MentionsInputProps) {
+  const id = uid('men')
+  const held = bindable<string>(() => value, () => defaultValue, '', () => onValueChange)
+  const start = untrack(() => parseMentions(held.value))
+  const text = state(start.text)
+  let marks: MentionMark[] = start.marks
+  let written = held.value
+  const hits = state<MentionItem[]>([])
+  const active = state(0)
+  const open = state(false)
+  const said = state('')
+  const empty = state('')
+  let at: { trigger: string; query: string; at: number } | undefined
+  let area: HTMLTextAreaElement | undefined
+  let pop: HTMLDivElement | undefined
+  let mark: HTMLSpanElement | undefined
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let stop: AbortController | undefined
+  const cancel = () => { clearTimeout(timer); stop?.abort(); stop = undefined }
+  onCleanup(cancel)
+  use(comboPopup, () => pop, () => ({ open: open.value, anchor: mark!, onClose: () => (open.value = false) }))
+  // a value set from outside: a write of our own compares equal
+  watch(() => held.value, v => {
+    if (v === written) return
+    const next = parseMentions(v)
+    written = v
+    marks = next.marks
+    text.value = next.text
+  })
+  const publish = (reason: 'keyboard' | 'pointer') => { written = serializeMentions(area!.value, marks); held.set(written, reason) }
+  const place = () => {
+    const a = area!
+    const p = caretPoint(a, at!.at)
+    mark!.style.insetInlineStart = `${a.offsetLeft + Math.min(p.x, a.clientWidth - 220)}px`
+    mark!.style.insetBlockStart = `${a.offsetTop + p.y}px`
+  }
+  const scan = () => {
+    const a = area!
+    at = findTrigger(a.value, a.selectionStart, Object.keys(triggers), marks)
+    cancel()
+    if (!at) { open.value = false; return }
+    const found = at
+    // oxlint-disable-next-line typescript/no-misused-promises -- the body catches its own failure, and a sync wrapper would add a closure to a hot field
+    timer = setTimeout(async () => {
+      const me = (stop = new AbortController())
+      try {
+        const r = await triggers[found.trigger]!(found.query, me.signal)
+        if (me !== stop) return
+        hits.value = r
+        active.value = 0
+        empty.value = r.length ? '' : `No matches for ${found.trigger}${found.query}`
+        place()
+        open.value = true
+      } catch { if (me === stop) open.value = false }
+    }, 120)
+  }
+  const pick = (n: number, reason: 'keyboard' | 'pointer') => {
+    const a = area!, it = hits.value[n]
+    if (!it || !at) return
+    const shown = at.trigger + it.label
+    const end = a.selectionStart
+    const was = a.value
+    a.setRangeText(`${shown} `, at.at, end, 'end')
+    marks = [...shiftMarks(marks, was, a.value), { start: at.at, end: at.at + shown.length, token: mentionToken(at.trigger, it) }]
+    open.value = false
+    text.value = a.value
+    publish(reason)
+    a.focus()
+    said.value = `${it.label} inserted`
+  }
+  const onInput = () => {
+    const a = area!
+    marks = shiftMarks(marks, text.value, a.value)
+    text.value = a.value
+    publish('keyboard')
+    scan()
+  }
+  const onKey = (e: KeyboardEvent) => {
+    if (!open.value || e.isComposing) return
+    if (e.key === 'Escape') { e.preventDefault(); open.value = false; return }
+    const n = hits.value.length
+    if (!n) return
+    const by = ({ ArrowDown: 1, ArrowUp: -1 } as Record<string, number>)[e.key]
+    if (by) {
+      e.preventDefault()
+      active.value = (active.value + by + n) % n
+      flush()
+      pop?.querySelector('[data-active]')?.scrollIntoView?.({ block: 'nearest' })
+    } else if (e.key === 'Enter' || e.key === 'Tab') { e.preventDefault(); pick(active.value, 'keyboard') }
+  }
+  const person = derived(() => at?.trigger === '@')
+  return (
+    <Field
+      {...rest}
+      hint={hint}
+      attrs={{ 'data-multiline': '' }}
+      filled={text.value.length > 0}
+      reset={held.reset}
+      hold={open.value}
+      control={p => (
+        <textarea ref={n => (area = n)} {...p.rest} data-part="input" id={p.id} rows={rows} placeholder=" " aria-describedby={p.describedby} aria-invalid={p.invalid ? 'true' : undefined} aria-autocomplete="list" aria-controls={id} aria-activedescendant={open.value && hits.value.length ? `${id}-${active.value}` : undefined} value={text.value} onInput={onInput} onKeyDown={onKey} onClick={scan}>{start.text}</textarea>
+      )}
+      end={
+        <>
+          <span ref={n => (mark = n)} data-part="caret-anchor" aria-hidden="true"></span>
+          <div ref={n => (pop = n)} data-scope="popover" data-kind="combo" data-sweep="" popover="manual" role="presentation" onPointerDown={e => e.preventDefault()}>
+            <span data-part="sweep" aria-hidden="true"></span>
+            <ul data-part="listbox" role="listbox" id={id} aria-label="Suggestions">
+              {hits.value.map((it, n) => (
+                <li key={it.id} role="option" id={`${id}-${n}`} aria-selected={n === active.value ? 'true' : 'false'} data-active={n === active.value ? '' : undefined} onClick={() => pick(n, 'pointer')}>
+                  {person.value && <span class="av" aria-hidden="true">{initials(it.label)}</span>}
+                  <span>{it.label}</span>
+                  {it.meta && <span data-part="opt-meta">{it.meta}</span>}
+                </li>
+              ))}
+              {!hits.value.length && <li role="option" aria-disabled="true" aria-selected="false">{empty.value}</li>}
+            </ul>
+          </div>
+          <span data-part="sr-only" role="status">{said.value}</span>
+          {name && <input type="hidden" name={name} value={held.value} />}
+        </>
+      }
+    />
+  )
+}