@weft-js/warp 0.0.0-stage → 0.1.1

package/src/SideNav.tsx

@@ -0,0 +1,147 @@
+import { RightIcon, XIcon } from '@weft-js/warp-icons'
+import { navIndicator, readCollapsed, readFolds, sideNav, uid, writeCollapsed, writeFolds, type Folds } from '@weft-js/warp-core'
+import { derived, onMount, state, untrack, watch } from '@weft-js/core'
+import { use } from '@weft-js/warp-core/weft'
+import './styles'
+import '@weft-js/warp-core/styles/components/button.css' // the close button, without a bar
+import '@weft-js/warp-core/styles/layout/navlist.css'
+import '@weft-js/warp-core/styles/layout/sidenav.css'
+
+/** One page in a SideNav section. */
+export interface SideNavLink {
+  href: string
+  label: string
+}
+
+/** A titled run of pages. `pinned` keeps it open, with a plain heading instead of a fold. */
+export interface SideNavSection {
+  title: string
+  items: SideNavLink[]
+  pinned?: boolean | undefined
+}
+
+/** Props for SideNav. */
+export interface SideNavProps {
+  /** Names the navigation landmark, and titles the panel when it is laid over the page. */
+  label: string
+  sections: SideNavSection[]
+  /** The current page's href: its link is marked, its section starts open, and the panel scrolls to it. */
+  current?: string | undefined
+  /** A filter box at the top, for a long list. A string is its placeholder. */
+  filter?: boolean | string | undefined
+  /** The localStorage key for what a viewer folded, and `<key>:collapsed` for the docked panel's fold; `false` keeps
+   * nothing. Default `warp:sidenav:<label>`. */
+  remember?: string | false | undefined
+  /** A collapse bar at the panel's edge: on a phone it is all that shows until pressed, and it opens the panel over the
+   * page; docked, it folds the sidebar to its own width. Default true. `false` leaves the panel to an outside button. */
+  collapsible?: boolean | undefined
+  /** The panel's id. Any button with `aria-controls` naming it also opens the panel on a phone. */
+  id?: string | undefined
+  /** Links shown above the sections only while the panel is laid over the page, such as a site's top links. */
+  lead?: SideNavLink[] | undefined
+}
+
+/**
+ * A docs sidebar: one left panel whose sections fold, with a collapse bar at its edge. The section holding the current
+ * page starts open, the rest closed, and a viewer's own choices are remembered. From 900px the panel is docked: sticky,
+ * scrolling on its own, and its bar folds it to a slim strip and back, remembered too. Below that only the bar shows, a
+ * slim strip down the left edge; pressing it brings the panel over the page, full height, with focus kept inside, and
+ * the bar, Escape, the backdrop or a link closing it. Links are plain anchors, so a router that handles `<a>` clicks
+ * navigates as usual.
+ */
+export function SideNav(props: SideNavProps) {
+  const id = untrack(() => props.id) ?? uid('sidenav')
+  const chosen = state<Folds>({})
+  const query = state('')
+  const open = state(false)
+  const collapsible = untrack(() => props.collapsible) !== false
+  const collapsed = state(false)
+  let root: HTMLElement | undefined
+  let list: HTMLElement | undefined
+
+  const key = () => (props.remember === false ? undefined : props.remember ?? `warp:sidenav:${props.label}`)
+  const holds = (s: SideNavSection) => s.items.some(i => i.href === props.current)
+  const words = derived(() => query.value.trim().toLowerCase())
+  const shown = derived(() => props.sections
+    .map((section, n) => ({ section, n, items: words.value ? section.items.filter(i => i.label.toLowerCase().includes(words.value)) : section.items }))
+    .filter(x => x.items.length > 0))
+  const unfolded = (s: SideNavSection) => words.value !== '' || !!s.pinned || (chosen.value[s.title] ?? holds(s))
+  const toggle = (s: SideNavSection) => {
+    chosen.value = { ...chosen.value, [s.title]: !unfolded(s) }
+    const k = key()
+    if (k) writeFolds(k, chosen.value)
+  }
+  // Arriving on a page opens its section, whatever was remembered, so the current link is never folded away.
+  const reveal = () => {
+    const s = props.sections.find(holds)
+    if (s && chosen.value[s.title] === false) chosen.value = { ...chosen.value, [s.title]: true }
+  }
+  const fold = (v: boolean) => {
+    collapsed.value = v
+    const k = key()
+    if (k) writeCollapsed(`${k}:collapsed`, v)
+  }
+  onMount(() => {
+    const k = key()
+    if (k) chosen.value = readFolds(k)
+    if (k && collapsible) collapsed.value = readCollapsed(`${k}:collapsed`)
+    reveal()
+  })
+  watch(() => props.current, () => { reveal(); open.value = false })
+  use(sideNav, () => root, () => ({ current: props.current, open: open.value, onOpenChange: (v: boolean) => (open.value = v), collapsed: collapsed.value, onCollapsedChange: fold }))
+  // warp's sliding bar, as Nav and the on-page rail have it: it follows the pointer and keyboard, and slides to a new page.
+  use(navIndicator, () => list, () => ({ axis: 'y' as const }))
+
+  const filterText = () => (typeof props.filter === 'string' ? props.filter : `Filter ${props.label.toLowerCase()}`)
+  return (
+    <div ref={n => (root = n)} data-scope="sidenav" data-open={open.value ? '' : undefined} data-collapsible={collapsible ? '' : undefined} data-collapsed={collapsible && collapsed.value ? '' : undefined}>
+      <div data-part="backdrop" aria-hidden="true"></div>
+      <div data-part="panel" id={id} tabindex="-1">
+        <div data-part="head">
+          <p data-part="title" id={`${id}-t`}>{props.label}</p>
+          {!collapsible && <button type="button" data-scope="button" data-emphasis="ghost" data-tone="neutral" data-icon-only="" data-size="sm" aria-label="Close" data-part="close"><XIcon /></button>}
+        </div>
+        <div data-part="scroll">
+          {props.lead && props.lead.length > 0 && (
+            <div data-part="lead" data-scope="navlist">
+              <ul>
+                {props.lead.map(i => <li key={i.href}><a data-part="item" href={i.href} aria-current={props.current?.startsWith(i.href) ? 'true' : undefined}>{i.label}</a></li>)}
+              </ul>
+            </div>
+          )}
+          {props.filter && (
+            <input type="search" data-part="filter" placeholder={filterText()} aria-label={filterText()} value={query.value} onInput={(e: Event) => (query.value = (e.currentTarget as HTMLInputElement).value)} />
+          )}
+          <nav ref={n => (list = n)} data-scope="navlist" data-bar="" aria-label={props.label}>
+            <ul data-part="sections">
+              {shown.value.map(x => (
+                <li key={x.section.title} data-current={holds(x.section) ? '' : undefined}>
+                  {x.section.pinned
+                    ? <p data-part="group-label">{x.section.title}</p>
+                    : (
+                      <button type="button" data-part="item" data-fold="" aria-expanded={unfolded(x.section) ? 'true' : 'false'} aria-controls={`${id}-${x.n}`} onClick={() => toggle(x.section)}>
+                        <span data-part="fold-label">{x.section.title}</span>
+                        <span data-part="chevron" aria-hidden="true"><RightIcon /></span>
+                      </button>
+                    )}
+                  <ul id={`${id}-${x.n}`} hidden={!unfolded(x.section)}>
+                    {x.items.map(i => <li key={i.href}><a data-part="item" href={i.href} aria-current={i.href === props.current ? 'page' : undefined}>{i.label}</a></li>)}
+                  </ul>
+                </li>
+              ))}
+            </ul>
+            <span data-part="indicator" aria-hidden="true"></span>
+          </nav>
+          {words.value !== '' && shown.value.length === 0 && <p data-part="empty">No pages match “{query.value.trim()}”.</p>}
+        </div>
+        {/* Last, as Shell's toggle is at its nav's foot. Its name is the label; aria-expanded, kept by sideNav, says the rest. */}
+        {collapsible && (
+          <button type="button" data-part="bar" aria-controls={id} aria-expanded="false">
+            <RightIcon />
+            <span data-part="bar-label">{props.label}</span>
+          </button>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/SignaturePad.tsx

@@ -0,0 +1,120 @@
+import { UndoIcon, XIcon } from '@weft-js/warp-icons'
+import { paintStrokes, signatureSvg, strokeWidth, uid, type Stroke } from '@weft-js/warp-core'
+import { derived, flush, state, untrack } from '@weft-js/core'
+import { Button } from './Button'
+import { Field, type FieldShell } from './Field'
+import { bindable, type Bindable } from './Picker'
+import { use } from '@weft-js/warp-core/weft'
+import '@weft-js/warp-core/styles/rich/signature.css'
+
+/** A signature, drawn or typed, with the SVG to show it. */
+export type SignatureValue = { method: 'drawn' | 'typed'; strokes?: Stroke[]; text?: string | undefined; svg: string }
+/** Props for SignaturePad. */
+export type SignaturePadProps = FieldShell & Bindable<SignatureValue | null>
+
+/**
+ * SignaturePad (04 §4): a canvas redrawn from its stored points on resize and theme change, with Undo and Clear. Typing
+ * the name is the mandatory alternative (WCAG 2.1.1, 2.5.1), so keyboard and switch users can sign.
+ */
+export function SignaturePad({ value, defaultValue, onValueChange, label, hint, ...rest }: SignaturePadProps) {
+  const id = uid('sig')
+  const v = bindable<SignatureValue | null>(() => value, () => defaultValue, null, () => onValueChange)
+  const start = untrack(() => v.value)
+  const strokes = state<Stroke[]>(start?.strokes ?? [])
+  const typed = state(start?.text ?? '')
+  const method = state<'draw' | 'type'>(start?.method === 'typed' ? 'type' : 'draw')
+  const count = derived(() => strokes.value.length)
+  const has = derived(() => (method.value === 'draw' ? count.value > 0 : typed.value.trim().length > 0))
+  const name = derived(() => (method.value === 'type' ? 'Typed signature' : count.value ? `Signature, ${count.value} stroke${count.value === 1 ? '' : 's'}` : 'Signature, empty'))
+  const status = derived(() => (!has.value ? 'Empty' : method.value === 'type' ? 'Typed' : `${count.value} stroke${count.value === 1 ? '' : 's'} · drawn`))
+  let pad: HTMLDivElement | undefined
+  let canvas: HTMLCanvasElement | undefined
+  let box: HTMLInputElement | undefined
+  let cur: Stroke | null = null
+  let last = { x: 0, y: 0, t: 0, w: 2.6 }
+  const draw = () => {
+    const ctx = canvas?.getContext?.('2d')
+    if (!ctx) return
+    const dpr = devicePixelRatio || 1, r = pad!.getBoundingClientRect()
+    if (canvas!.width !== Math.round(r.width * dpr) || canvas!.height !== Math.round(r.height * dpr)) { canvas!.width = Math.max(1, Math.round(r.width * dpr)); canvas!.height = Math.max(1, Math.round(r.height * dpr)) }
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0)
+    ctx.strokeStyle = ctx.fillStyle = getComputedStyle(pad!).color
+    paintStrokes(ctx, strokes.value, r.width, r.height)
+  }
+  const emit = () => {
+    if (!has.value) return v.set(null, 'programmatic')
+    if (method.value === 'draw') v.set({ method: 'drawn', strokes: strokes.value, svg: signatureSvg(strokes.value) }, 'pointer')
+    else { const text = typed.value.trim(); v.set({ method: 'typed', text, svg: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 200"><text x="24" y="130" font-size="64" font-style="italic" fill="currentColor">${text.replace(/[&<>]/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c]!)}</text></svg>` }, 'keyboard') }
+  }
+  const down = (e: PointerEvent) => {
+    if (method.value !== 'draw') return
+    canvas!.setPointerCapture?.(e.pointerId)
+    const r = canvas!.getBoundingClientRect()
+    cur = [[(e.clientX - r.left) / r.width, (e.clientY - r.top) / r.height, e.pointerType === 'pen' && e.pressure ? 1 + e.pressure * 3 : 2.6]]
+    strokes.value = [...strokes.value, cur]
+    last = { x: e.clientX, y: e.clientY, t: e.timeStamp, w: 2.6 }
+    draw()
+  }
+  const move = (e: PointerEvent) => {
+    if (!cur) return
+    const r = canvas!.getBoundingClientRect()
+    for (const ev of e.getCoalescedEvents?.().length ? e.getCoalescedEvents() : [e]) {
+      const speed = Math.hypot(ev.clientX - last.x, ev.clientY - last.y) / Math.max(1, ev.timeStamp - last.t)
+      const w = strokeWidth(last.w, speed, ev.pointerType === 'pen' ? ev.pressure : undefined)
+      cur.push([(ev.clientX - r.left) / r.width, (ev.clientY - r.top) / r.height, w])
+      last = { x: ev.clientX, y: ev.clientY, t: ev.timeStamp, w }
+    }
+    draw()
+  }
+  const up = () => { if (cur) { cur = null; strokes.value = [...strokes.value]; emit() } }
+  const undo = () => { strokes.value = strokes.value.slice(0, -1); flush(); draw(); emit() }
+  const clear = () => { if (method.value === 'draw') strokes.value = []; else typed.value = ''; flush(); draw(); emit() }
+  const pick = (m: 'draw' | 'type') => { method.value = m; flush(); if (m === 'type') box?.focus(); else draw(); emit() }
+  use((el: HTMLDivElement) => {
+    const size = typeof ResizeObserver === 'undefined' ? undefined : new ResizeObserver(draw)
+    size?.observe(el)
+    const theme = new MutationObserver(() => requestAnimationFrame(draw))
+    theme.observe(el.ownerDocument.documentElement, { attributes: true, attributeFilter: ['data-theme', 'data-expression'] })
+    return { update() {}, destroy() { size?.disconnect(); theme.disconnect() } }
+  }, () => pad)
+  return (
+    <div data-scope="signature" class="stack">
+      <div class="row" style="justify-content:flex-end">
+        <div class="seg" role="radiogroup" aria-label="Signing method">
+          <label><input type="radio" name={`${id}-m`} checked={method.value === 'draw'} onChange={() => pick('draw')} /><i>Draw</i></label>
+          <label><input type="radio" name={`${id}-m`} checked={method.value === 'type'} onChange={() => pick('type')} /><i>Type</i></label>
+        </div>
+      </div>
+      <Field
+        {...rest}
+        group
+        label={label}
+        hint={hint ?? 'Draw with a finger, a pen or a mouse, or switch to Type.'}
+        filled={has.value}
+        reset={() => {
+          v.reset()
+          strokes.value = start?.strokes ?? []
+          typed.value = start?.text ?? ''
+          method.value = start?.method === 'typed' ? 'type' : 'draw'
+          flush()
+          draw()
+        }}
+        control={() => (
+          <div ref={n => (pad = n)} data-part="pad">
+            <canvas ref={n => (canvas = n)} role="img" aria-label={name.value} style={method.value === 'type' ? 'visibility:hidden' : undefined} onPointerDown={down} onPointerMove={move} onPointerUp={up} onPointerCancel={up}></canvas>
+            <span data-part="empty"></span>
+            <span data-part="baseline" aria-hidden="true">×</span>
+            <input ref={n => (box = n)} data-part="typed" hidden={method.value !== 'type'} aria-label="Type your full name" placeholder="Type your full name" autocomplete="name" value={typed.value} onInput={e => { typed.value = (e.currentTarget).value; emit() }} />
+          </div>
+        )}
+      />
+      <div class="row" style="justify-content:space-between">
+        <span class="muted" aria-live="polite">{status.value}</span>
+        <span class="row">
+          {method.value === 'draw' && <Button emphasis="ghost" size="sm" icon={UndoIcon} disabled={!count.value} onClick={undo}>Undo</Button>}
+          <Button emphasis="ghost" size="sm" icon={XIcon} disabled={!has.value} onClick={clear}>Clear</Button>
+        </span>
+      </div>
+    </div>
+  )
+}

package/src/Skeleton.tsx

@@ -0,0 +1,14 @@
+import { untrack } from '@weft-js/core'
+import './styles'
+import '@weft-js/warp-core/styles/components/skeleton.css'
+
+/**
+ * A skeleton (05 §5): the shimmer is the sweep, left to right; still under reduced motion. `lines` stacks text
+ * lines (the last one shorter).
+ */
+export function Skeleton({ shape = 'text', lines = 1, width, height }: { shape?: 'text' | 'circle' | 'block' | undefined; lines?: number | undefined; width?: string | undefined; height?: string | undefined }) {
+  const size = (last: boolean) => [width ? `inline-size:${width}` : last && lines > 1 ? 'inline-size:60%' : '', height ? `block-size:${height}` : ''].filter(Boolean).join(';') || undefined
+  if (untrack(() => lines) <= 1) return <span data-scope="skeleton" data-shape={shape === 'text' ? undefined : shape} style={size(false)}></span>
+  return <>{Array.from({ length: lines }, (_, i) => <span data-scope="skeleton" data-shape={shape === 'text' ? undefined : shape} style={size(i === lines - 1)}></span>)}</>
+}
+

package/src/Slider.tsx

@@ -0,0 +1,42 @@
+import { slider as action, uid } from '@weft-js/warp-core'
+import { derived } from '@weft-js/core'
+import { use } from '@weft-js/warp-core/weft'
+import './fields'
+import '@weft-js/warp-core/styles/inputs/range.css'
+
+/** Props for Slider. */
+export interface SliderProps<V extends number | [number, number] = number | [number, number]> {
+  label: string
+  /** One number, or two for a range. */
+  value: V
+  onChange: (value: V) => void
+  min?: number | undefined
+  max?: number | undefined
+  step?: number | undefined
+  format?: ((v: number) => string) | undefined
+  /** A range's thumbs, for screen readers: "Minimum price", "Maximum price". */
+  names?: [string, string] | undefined
+  disabled?: boolean | undefined
+  /** Posts with a form: the number, or one entry per thumb. */
+  name?: string | undefined
+}
+
+/** A slider (03 §5): role=slider thumbs on warp's rail, keyboard per APG, a pointer anywhere on the track. */
+export function Slider<V extends number | [number, number]>({ label, value, onChange, min = 0, max = 100, step = 1, format = String, names, disabled, name }: SliderProps<V>) {
+  const id = uid('slider')
+  const values = derived<number[]>(() => (typeof value === 'number' ? [value] : value))
+  let el: HTMLDivElement | undefined
+  use(action, () => el, () => ({ values: values.value, min, max, step, format, names, disabled, onChange: (v: number[]) => onChange((v.length === 1 ? v[0] : v) as V) }))
+  return (
+    <div style="display:grid;gap:6px">
+      <div data-scope="range-head"><span id={`${id}-l`}>{label}</span><output>{values.value.map(format).join(' – ')}</output></div>
+      <div ref={n => (el = n)} data-scope="slider" data-disabled={disabled ? '' : undefined}>
+        <div data-part="track" data-on=""><div data-part="range"></div></div>
+        {values.value.map((v, i) => (
+          <div key={i} data-part="thumb" role="slider" tabindex={disabled ? '-1' : '0'} aria-labelledby={`${id}-l`} aria-valuemin={min} aria-valuemax={max} aria-valuenow={v} aria-disabled={disabled ? 'true' : undefined}></div>
+        ))}
+      </div>
+      {name && values.value.map((v, i) => <input key={i} type="hidden" name={name} value={v} />)}
+    </div>
+  )
+}

package/src/Spinner.tsx

@@ -0,0 +1,7 @@
+import './styles'
+import '@weft-js/warp-core/styles/components/spinner.css'
+
+/** A spinner: one arc, 0.8s; a pulse under reduced motion. `label` names it (role="status"); without one it is decorative. */
+export function Spinner({ label, size }: { label?: string | undefined; size?: 'sm' | 'md' | 'lg' | undefined }) {
+  return <span data-scope="spinner" data-size={size === 'md' ? undefined : size} role={label ? 'status' : undefined} aria-label={label} aria-hidden={label ? undefined : 'true'}></span>
+}