@weft-js/warp 0.0.0-stage → 0.1.1

package/src/Choice.tsx

@@ -0,0 +1,105 @@
+import { indicator, uid } from '@weft-js/warp-core'
+import { untrack } from '@weft-js/core'
+import type { Interaction } from '@weft-js/core/interaction'
+import { Icon, type IconRef } from './Icon'
+import { use } from '@weft-js/warp-core/weft'
+import { useUi } from './use-ui'
+import './fields'
+import '@weft-js/warp-core/styles/inputs/choice.css'
+
+const sweepParts = () => <><span data-part="sweep-base" aria-hidden="true"></span><span data-part="sweep" aria-hidden="true"></span></>
+
+/**
+ * A native checkbox with role="switch" (03 §4; SIGNATURE §1c): the rail fills through the sweep as the thumb slides.
+ * The whole label is the hover target. Applies at once: never inside a form with Save (03 §8).
+ */
+export function Switch({ children, hint, size, placement = 'end', ui, ...rest }: { checked?: boolean; hint?: unknown; size?: 'sm' | 'md' | undefined; placement?: 'start' | 'end'; ui?: Interaction; children?: unknown; [attr: string]: unknown }) {
+  let host: HTMLLabelElement | undefined
+  useUi(() => ui, () => host)
+  return (
+    <label ref={n => (host = n)} data-scope="switch" data-placement={placement} data-size={size === 'sm' ? 'sm' : undefined}>
+      <input type="checkbox" role="switch" {...rest} />
+      <span data-part="track" data-sweep="">
+        <span data-part="rail-fill" aria-hidden="true"><span data-part="rail-hover"></span></span>
+        {sweepParts()}
+        <span data-part="thumb" aria-hidden="true"></span>
+      </span>
+      <span data-part="label">{children}</span>
+      {hint !== undefined && <span data-part="hint">{hint}</span>}
+    </label>
+  )
+}
+
+/** A native checkbox (03 §4): the box never fills, the check draws in; `indeterminate` is the real property. */
+export function Checkbox({ children, hint, error, indeterminate, ui, ...rest }: { checked?: boolean; indeterminate?: boolean; hint?: unknown; error?: unknown; ui?: Interaction; children?: unknown; [attr: string]: unknown }) {
+  let input: HTMLInputElement | undefined
+  let host: HTMLLabelElement | undefined
+  useUi(() => ui, () => host)
+  use((el: HTMLInputElement, on: boolean | undefined) => {
+    el.indeterminate = !!on
+    return { update: v => void (el.indeterminate = !!v), destroy() {} }
+  }, () => input, () => indeterminate)
+  return (
+    <label ref={n => (host = n)} data-scope="checkbox" data-invalid={error ? '' : undefined}>
+      <input ref={n => (input = n)} type="checkbox" aria-invalid={error ? 'true' : undefined} {...rest} />
+      <span data-part="control" data-sweep="">
+        {sweepParts()}
+        <svg viewBox="0 0 24 24" aria-hidden="true"><path data-part="check" pathLength="1" d="M5 12.5 L9.5 17 L19 7" /><path data-part="dash" pathLength="1" d="M6 12h12" /></svg>
+      </span>
+      <span data-part="label">{children}</span>
+      {(error ?? hint) !== undefined && <span data-part="hint">{error ?? hint}</span>}
+    </label>
+  )
+}
+
+/** One radio (03 §4): the native input, the sweep ring, a dot that springs in. Use RadioGroup for a set. */
+export function Radio({ children, hint, ui, ...rest }: { hint?: unknown; ui?: Interaction; children?: unknown; [attr: string]: unknown }) {
+  let host: HTMLLabelElement | undefined
+  useUi(() => ui, () => host)
+  return (
+    <label ref={n => (host = n)} data-scope="radio">
+      <input type="radio" {...rest} />
+      <span data-part="control" data-sweep="">{sweepParts()}</span>
+      <span data-part="label">{children}</span>
+      {hint !== undefined && <span data-part="hint">{hint}</span>}
+    </label>
+  )
+}
+
+/** One RadioGroup choice. */
+export type RadioOption<V extends string> = { value: V; label: unknown; hint?: unknown; disabled?: boolean | undefined }
+
+/** A radio group: native radios, so arrow keys, form values and the group name are the platform's. */
+export function RadioGroup<V extends string>({ label, value, onChange, options, name }: { label: string; value: V; onChange: (v: V) => void; options: RadioOption<V>[]; name?: string | undefined }) {
+  const group = untrack(() => name) ?? uid('radio')
+  return (
+    <div role="radiogroup" aria-label={label} style="display:grid;gap:var(--warp-space-tight)">
+      {options.map(o => <Radio key={o.value} name={group} value={o.value} hint={o.hint} checked={o.value === value} disabled={o.disabled} onChange={() => onChange(o.value)}>{o.label}</Radio>)}
+    </div>
+  )
+}
+
+/** One Segmented choice. */
+export type SegmentedOption<V extends string> = { value: V; label: unknown; icon?: IconRef | undefined; count?: unknown; disabled?: boolean | undefined }
+
+/**
+ * Segmented (03 §4, review 01 M8): native radios in a group that rests on its ink border; hovering or focusing an
+ * unselected option sweeps a ring round that option only; the selected face slides to it on the sweep curve.
+ */
+export function Segmented<V extends string>({ label, value, onChange, options, size, name }: { label: string; value: V; onChange: (v: V) => void; options: SegmentedOption<V>[]; size?: 'sm' | 'md' | undefined; name?: string | undefined }) {
+  const group = untrack(() => name) ?? uid('seg')
+  let root: HTMLDivElement | undefined
+  use(indicator, () => root, () => ({ selected: ':scope > label:has(input:checked)', at: value }))
+  return (
+    <div ref={n => (root = n)} data-scope="segmented" role="radiogroup" aria-label={label} data-size={size === 'sm' ? 'sm' : undefined}>
+      <span data-part="indicator" aria-hidden="true" data-instant=""></span>
+      {options.map(o => (
+        <label key={o.value} data-sweep="">
+          <span data-part="sweep" aria-hidden="true"></span>
+          <input type="radio" name={group} value={o.value} checked={o.value === value} disabled={o.disabled} onChange={() => onChange(o.value)} />
+          <span data-part="item">{o.icon && <Icon name={o.icon} />}{o.label}{o.count !== undefined && <span data-part="count">{o.count}</span>}</span>
+        </label>
+      ))}
+    </div>
+  )
+}

package/src/CodeBlock.tsx

@@ -0,0 +1,65 @@
+import { CopyIcon, CheckIcon } from '@weft-js/warp-icons'
+import { highlight } from '@weft-js/warp-core'
+import './styles'
+import '@weft-js/warp-core/styles/components/button.css'
+import '@weft-js/warp-core/styles/components/copy.css'
+import '@weft-js/warp-core/styles/rich/codeblock.css'
+import '@weft-js/warp-core/styles/rich/code-tabs.css'
+
+/** Props for CodeBlock. */
+export interface CodeBlockProps {
+  /** The source to show, colour and copy. */
+  code: string
+  /** tsx by default; ts, js, json and sh are coloured too, anything else stays plain. */
+  language?: string | undefined
+  /** A file name shown in the bar above the code. */
+  filename?: string | undefined
+  /** Line numbers. */
+  lines?: boolean | undefined
+  /** Wrap long lines instead of scrolling. */
+  wrap?: boolean | undefined
+}
+
+function CopyButton({ text }: { text?: string | undefined }) {
+  return (
+    <button type="button" data-scope="button" data-emphasis="ghost" data-tone="neutral" data-size="sm" data-act="copy" data-copy="" data-copy-text={text} aria-label="Copy code">
+      <span data-part="indicator"><CopyIcon /><CheckIcon /></span>
+    </button>
+  )
+}
+
+/**
+ * Code, coloured on the server (04 CodeBlock). It has no state, so it hydrates to nothing: `copyButtons()` from
+ * `@weft-js/warp-core`, called once anywhere in the app, runs every copy button in the document.
+ */
+export function CodeBlock({ code, language = 'tsx', filename, lines, wrap }: CodeBlockProps) {
+  return (
+    <figure data-scope="codeblock" data-wrap={wrap ? '' : undefined}>
+      <div data-part="head">
+        {filename && <span data-part="file">{filename}</span>}
+        <span class="sp"></span>
+        <span data-part="lang">{language}</span>
+        <CopyButton />
+      </div>
+      <pre tabindex="0" data-lines={lines ? '' : undefined}><code
+      // oxlint-disable-next-line weft/no-html-sink -- highlight escapes the source before it wraps tokens in spans
+      innerHTML={highlight(code, language)}></code></pre>
+    </figure>
+  )
+}
+
+/** Inline code in running text. */
+export function Code({ children }: { children: unknown }) {
+  return <code data-scope="code">{children}</code>
+}
+
+/** One command to copy, with its `$` (04 Snippet). */
+export function Snippet({ code, prompt = '$' }: { code: string; prompt?: string }) {
+  return (
+    <div data-scope="snippet">
+      <span aria-hidden="true">{prompt}</span>
+      <code>{code}</code>
+      <CopyButton text={code} />
+    </div>
+  )
+}

package/src/CodeInput.tsx

@@ -0,0 +1,130 @@
+import { codeLayer, indented, jsonProblem, type ChangeReason } from '@weft-js/warp-core'
+import { derived, onCleanup, state, untrack } from '@weft-js/core'
+import { bindable, type Bindable } from './bind'
+import { Button } from './Button'
+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/code-input.css'
+
+type CodeOwn = Bindable<string> & {
+  /** After a form's reset put the value back. */
+  onReset?: () => void
+  language?: string | undefined
+  /** Numbers each line in a gutter. Default `true`; off while `wrap` is on. */
+  lineNumbers?: boolean
+  tabSize?: 2 | 4
+  /** Soft-wraps long lines; line numbers then give way, since a number no longer means one row. */
+  wrap?: boolean
+  rows?: number
+  /** The line to mark in the gutter. */
+  errorLine?: number | undefined
+  name?: string | undefined
+}
+
+/** Props for CodeInput: the field shell, the bound text and the editor's own options. */
+export type CodeInputProps = FieldShell & CodeOwn
+
+const LEAVE = 'Tab indents · Esc then Tab leaves'
+
+/**
+ * A code field (04 CodeInput; inputs-rich.html:2223-2241): a <textarea> over a layer coloured with the CSS Custom
+ * Highlight API, so a key press builds no spans; browsers without it show the textarea's own plain text. Tab indents,
+ * Shift+Tab outdents, and Esc then Tab leaves, which the hint says. No autocorrect, spellcheck or autocapitalize.
+ */
+export function CodeInput({ value, defaultValue, onValueChange, language, lineNumbers = true, tabSize = 2, wrap, rows = 8, errorLine, name, hint, onReset, ...rest }: CodeInputProps) {
+  const held = bindable<string>(() => value, () => defaultValue, '', () => onValueChange)
+  const lines = derived(() => held.value.split('\n').map((_, n) => n + 1))
+  const numbered = derived(() => lineNumbers && !wrap)
+  let box: HTMLDivElement | undefined
+  let leaving = false
+  const set = (area: HTMLTextAreaElement) => held.set(area.value, 'keyboard')
+  const onKey = (e: KeyboardEvent) => {
+    const area = e.currentTarget as HTMLTextAreaElement
+    if (e.key === 'Escape') { leaving = true; return }
+    if (e.key !== 'Tab') { if (e.key !== 'Shift') leaving = false; return }
+    if (leaving) { leaving = false; return }
+    e.preventDefault()
+    const r = indented(area.value, area.selectionStart, area.selectionEnd, tabSize, e.shiftKey)
+    area.setSelectionRange(r.from, r.to)
+    // execCommand keeps the browser's undo history, which setRangeText throws away
+    if (!document.execCommand?.('insertText', false, r.insert)) area.setRangeText(r.insert, r.from, r.to, 'end')
+    area.setSelectionRange(r.start, r.end)
+    set(area)
+  }
+  use(codeLayer, () => box, () => ({ text: held.value, language }))
+  return (
+    <Field
+      {...rest}
+      hint={hint ?? LEAVE}
+      attrs={{ 'data-multiline': '' }}
+      filled={held.value.length > 0}
+      reset={() => { held.reset(); onReset?.() }}
+      control={p => (
+        <div data-part="body">
+          <div ref={n => (box = n)} class="code-in" data-wrap={wrap ? '' : undefined} style={`--_tab:${tabSize}`}>
+            {numbered.value && <ol data-part="lines" class="ln" aria-hidden="true">{lines.value.map(n => <li key={n} data-error={n === errorLine ? '' : undefined}>{n}</li>)}</ol>}
+            <div data-part="surface">
+              <pre data-part="layer" aria-hidden="true">{`${held.value}\n`}</pre>
+              <textarea {...p.rest} data-part="input" id={p.id} rows={rows} name={name} spellcheck={false} autocapitalize="off" autocomplete="off" wrap={wrap ? 'soft' : 'off'} aria-describedby={p.describedby} aria-invalid={p.invalid ? 'true' : undefined} value={held.value} onInput={e => set(e.currentTarget)} onKeyDown={onKey}>{untrack(() => held.value)}</textarea>
+            </div>
+          </div>
+        </div>
+      )}
+    />
+  )
+}
+
+/** Props for JsonEditor: CodeInput with the language fixed to JSON, and a schema check. */
+export type JsonEditorProps = FieldShell & Omit<CodeOwn, 'language' | 'errorLine'> & {
+  /** Checks parsed JSON; what it returns shows as the field's error. */
+  schema?: (value: unknown) => string | null | undefined
+}
+
+/**
+ * CodeInput for JSON (04 JsonEditor): parse errors, and an optional schema's, name their line in the field's error and
+ * pin the sweep; Format rewrites it with `tabSize`.
+ */
+export function JsonEditor({ value, defaultValue, onValueChange, schema, tabSize = 2, ...rest }: JsonEditorProps) {
+  const held = bindable<string>(() => value, () => defaultValue, '', () => onValueChange)
+  const checked = state(held.value)
+  let timer: ReturnType<typeof setTimeout> | undefined
+  onCleanup(() => clearTimeout(timer))
+  const change = (v: string, reason: ChangeReason) => {
+    held.set(v, reason)
+    clearTimeout(timer)
+    timer = setTimeout(() => (checked.value = v), 250)
+  }
+  const problem = derived(() => (checked.value.trim() ? jsonProblem(checked.value) : null))
+  const failed = derived(() => {
+    const p = problem.value
+    if (p) return `Invalid JSON${p.line ? ` on line ${p.line}` : ''}: ${p.message}`
+    if (!schema || !checked.value.trim()) return undefined
+    return schema(JSON.parse(checked.value)) ?? undefined
+  })
+  const summary = derived(() => {
+    if (!checked.value.trim()) return LEAVE
+    const o = JSON.parse(checked.value)
+    return `Valid JSON · ${o && typeof o === 'object' ? `${Object.keys(o).length} ${Object.keys(o).length === 1 ? 'key' : 'keys'}` : typeof o} · ${LEAVE}`
+  })
+  const format = () => {
+    if (jsonProblem(held.value)) return
+    const next = JSON.stringify(JSON.parse(held.value), null, untrack(() => tabSize))
+    held.set(next, 'pointer')
+    checked.value = next
+  }
+  return (
+    <CodeInput
+      {...(rest)}
+      tabSize={tabSize}
+      language="json"
+      value={held.value}
+      onValueChange={change}
+      onReset={() => { clearTimeout(timer); checked.value = held.value }}
+      error={failed.value}
+      hint={problem.value ? LEAVE : summary.value}
+      errorLine={problem.value?.line}
+      end={<span data-part="suffix"><Button emphasis="ghost" tone="neutral" size="sm" disabled={!!problem.value} onClick={format}>Format</Button></span>}
+    />
+  )
+}

package/src/Combobox.tsx

@@ -0,0 +1,113 @@
+import { comboPopup, uid } from '@weft-js/warp-core'
+import { derived, flush, onCleanup, state, untrack } from '@weft-js/core'
+import { Field, type FieldProps } from './Field'
+import { Icon, type IconRef } from './Icon'
+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'
+
+export type ComboRow = { main: string; sub?: string | undefined; meta?: string | undefined; icon?: IconRef | undefined }
+
+export type ComboFieldProps<T> = FieldProps & {
+  /** The app's search. Superseded calls are aborted. */
+  find: (q: string, signal: AbortSignal) => Promise<T[]>
+  row: (hit: T) => ComboRow
+  onPick: (hit: T) => unknown
+  /** The text changed: by typing, or cleared by a second Esc. */
+  onText?: (text: string) => void
+  /** The search failed or took longer than `timeout` ms. */
+  onFail?: () => void
+  text: () => string
+  minChars?: number
+  timeout?: number
+  /** Announced in the hint while there is no search running. */
+  status?: () => string | undefined
+}
+
+/**
+ * A text field with a list popup (04 §3, APG Combobox, list autocomplete with automatic selection): focus stays in the
+ * input. Typing `minChars` opens the list with the first result active, ↓/↑ wrap, Enter picks, Esc closes and keeps the
+ * text, a second Esc clears it, ↓ on a closed combobox searches again. Requests are debounced 120ms and aborted when
+ * superseded. Shared by PlaceLookupInput and AddressField's line 1.
+ */
+export function ComboField<T>({ find, row, onPick, onText, onFail, text, minChars = 2, timeout, status, hint, ...rest }: ComboFieldProps<T>) {
+  const id = uid('combo')
+  const hits = state<T[]>([])
+  const active = state(0)
+  const open = state(false)
+  const busy = state(false)
+  const rows = derived(() => hits.value.map((hit, at) => ({ at, r: untrack(() => row)(hit) })))
+  let input: HTMLInputElement | undefined
+  let pop: HTMLDivElement | undefined
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let stop: AbortController | undefined
+  const cancel = () => { clearTimeout(timer); stop?.abort(); stop = undefined; busy.value = false }
+  onCleanup(cancel)
+  use(comboPopup, () => pop, () => ({ open: open.value, anchor: (input?.closest('[data-part="control"]') ?? input) as HTMLElement, onClose: () => (open.value = false) }))
+  const run = (q: string) => {
+    cancel()
+    if (q.trim().length < minChars) { open.value = false; hits.value = []; return }
+    // 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())
+      busy.value = true
+      const late = timeout ? setTimeout(() => me.abort(), timeout) : undefined
+      try {
+        const r = await find(q.trim(), me.signal)
+        if (me !== stop) return
+        hits.value = r
+        active.value = 0
+        open.value = r.length > 0
+      } catch {
+        if (me === stop || me.signal.aborted) { open.value = false; onFail?.() }
+      } finally {
+        clearTimeout(late)
+        if (me === stop) busy.value = false
+      }
+    }, 120)
+  }
+  const pick = (at: number) => { open.value = false; onPick(hits.value[at]!) }
+  const onKey = (e: KeyboardEvent) => {
+    const el = e.currentTarget as HTMLInputElement
+    if (e.key === 'Escape') {
+      if (e.defaultPrevented) return // an overlay took it: this popup, or the dialog around a closed one
+      e.preventDefault()
+      if (el.value) { cancel(); onText?.('') }
+    } else if (e.key === 'ArrowDown' && !open.value) { e.preventDefault(); run(el.value) }
+    else if (open.value && hits.value.length) {
+      const d = ({ ArrowDown: 1, ArrowUp: -1 } as Record<string, number>)[e.key]
+      if (d) {
+        e.preventDefault()
+        active.value = (active.value + d + hits.value.length) % hits.value.length
+        flush()
+        pop?.querySelector('[data-active]')?.scrollIntoView?.({ block: 'nearest' })
+      } else if (e.key === 'Enter') { e.preventDefault(); pick(active.value) }
+    }
+  }
+  const shownHint = derived(() => (busy.value ? 'Searching…' : status?.() ?? hint))
+  return (
+    <Field
+      {...rest}
+      hint={shownHint.value}
+      filled={text().length > 0}
+      hold={open.value}
+      control={p => (
+        <input ref={n => (input = n)} {...p.rest} data-part="input" id={p.id} placeholder=" " role="combobox" aria-autocomplete="list" aria-expanded={open.value ? 'true' : 'false'} aria-controls={id} aria-activedescendant={open.value && hits.value.length ? `${id}-${active.value}` : undefined} aria-busy={busy.value ? 'true' : undefined} aria-describedby={p.describedby} aria-invalid={p.invalid ? 'true' : undefined} autocomplete={p.rest.autocomplete ?? 'off'} value={text()} onInput={e => { const v = (e.currentTarget).value; onText?.(v); run(v) }} onKeyDown={onKey} />
+      )}
+      end={
+        <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={rest.label}>
+            {rows.value.map(({ at, r }) => (
+              <li key={`${at}:${r.main}`} role="option" id={`${id}-${at}`} aria-selected={at === active.value ? 'true' : 'false'} data-active={at === active.value ? '' : undefined} onClick={() => pick(at)}>
+                {r.icon && <Icon name={r.icon} />}
+                <span>{r.main}{r.sub && <small> {r.sub}</small>}</span>
+                {r.meta && <span data-part="opt-meta">{r.meta}</span>}
+              </li>
+            ))}
+          </ul>
+        </div>
+      }
+    />
+  )
+}