@weft-js/warp 0.0.0-stage → 0.1.1

package/src/collab/Composer.tsx

@@ -0,0 +1,173 @@
+import { AtIcon, CheckIcon, PaperclipIcon, SendIcon, SmileIcon, XIcon } from '@weft-js/warp-icons'
+import { announce, insertMention, mentionQuery, nextIndex, uid, type Peer } from '@weft-js/warp-core'
+import { derived, state, untrack, type State } from '@weft-js/core'
+import { Button } from '../Button'
+import { PeerAvatar, SWEEP } from './peer'
+import '../styles'
+import '@weft-js/warp-core/styles/components/button.css'
+import '@weft-js/warp-core/styles/app/tokens.css'
+import '@weft-js/warp-core/styles/app/base.css'
+import '@weft-js/warp-core/styles/app/composer.css'
+import '@weft-js/warp-core/styles/app/suggest.css'
+import '@weft-js/warp-core/styles/app/typing.css'
+
+const HINT = 'Enter sends, Shift+Enter adds a line'
+
+/** The message being quoted in a reply. */
+export interface QuoteDraftValue { ref: string; author: string; time: string; text: string }
+/** A file attached to a draft. */
+export interface ComposerFile { id: string; name: string }
+/** Someone an `@` can name. */
+export type Mentionable = Peer & { status?: string | undefined }
+/** What the composer sends. */
+export interface ComposerSend { text: string; quote?: QuoteDraftValue }
+
+/** Props for Composer. */
+export interface ComposerProps {
+  /** The textarea's name: "Message #calendar-engine". */
+  label: string
+  placeholder?: string
+  onSend: (m: ComposerSend) => void
+  /** The quote being drafted (§5.5), for a Thread to fill. */
+  quote?: State<QuoteDraftValue | null>
+  mentions?: Mentionable[]
+  files?: ComposerFile[]
+  onRemoveFile?: (f: ComposerFile) => void
+  onAttach?: () => void
+  /** The emoji slot: open a picker, then call `insert` with what was picked. */
+  onEmoji?: (insert: (text: string) => void) => void
+  onTyping?: () => void
+  /** Hide the keyboard hint (phone). */
+  compact?: boolean | undefined
+  /** Reaches the textarea, for focus. */
+  input?: (el: HTMLTextAreaElement) => void
+}
+
+/**
+ * The composer (07 §5.1, §5.5): QuoteDraft, textarea, attach and emoji slots, @mention suggest listbox, Send. Enter
+ * sends, Shift+Enter adds a line. A quote alone never sends: the hint says why. Escape closes the list, then the quote.
+ */
+export function Composer({ label, placeholder, onSend, quote, mentions, files, onRemoveFile, onAttach, onEmoji, onTyping, compact, input: giveInput }: ComposerProps) {
+  const id = uid('composer')
+  const hint = state<string | null>(null)
+  const query = state<string | null>(null)
+  const active = state(0)
+  const hasPeople = derived(() => (mentions ?? []).length > 0)
+  const canAttach = derived(() => onAttach !== undefined)
+  const canEmoji = derived(() => onEmoji !== undefined)
+  const shown = derived(() => {
+    const q = query.value?.toLowerCase()
+    return q === undefined ? [] : (mentions ?? []).filter(p => p.name.toLowerCase().includes(q)).slice(0, 8)
+  })
+  const open = derived(() => query.value !== null && shown.value.length > 0)
+  const draft = derived(() => quote?.value ?? null)
+  let ta: HTMLTextAreaElement | undefined
+
+  const removeQuote = () => {
+    if (quote) quote.value = null
+    hint.value = null
+  }
+  const closeList = () => { query.value = null; active.value = 0 }
+  const scan = () => {
+    const q = ta ? mentionQuery(ta.value, ta.selectionStart) : null
+    query.value = q && hasPeople.value ? q.query : null
+    active.value = 0
+  }
+  const pick = (p: Mentionable) => {
+    const next = insertMention(ta!.value, ta!.selectionStart, p.name.split(/\s+/)[0]!)
+    ta!.value = next.value
+    ta!.setSelectionRange(next.caret, next.caret)
+    closeList()
+    ta!.focus()
+  }
+  const send = () => {
+    const text = ta!.value.trim()
+    const q = draft.value
+    if (!text) {
+      if (!q) return
+      hint.value = 'Add a reply to the quote'
+      announce(ta!.ownerDocument, 'Add a reply to the quote', true)
+      return ta!.focus()
+    }
+    ta!.value = ''
+    closeList()
+    removeQuote()
+    onSend(q ? { text, quote: q } : { text })
+  }
+  const key = (e: KeyboardEvent) => {
+    if (open.value) {
+      const to = nextIndex(e.key, active.value, shown.value.length, { orientation: 'vertical' })
+      if (to >= 0 && e.key !== 'Home' && e.key !== 'End') { e.preventDefault(); active.value = to; return }
+      if (e.key === 'Escape') { e.preventDefault(); return closeList() }
+      if (e.key === 'Enter' || e.key === 'Tab') { e.preventDefault(); return pick(shown.value[active.value]!) }
+    }
+    if (e.key === 'Escape' && draft.value) { e.preventDefault(); removeQuote(); return announce(ta!.ownerDocument, 'Quote removed') }
+    if (e.key === 'Enter' && !e.shiftKey && !e.isComposing) { e.preventDefault(); send() }
+  }
+  const insert = (text: string) => {
+    ta!.setRangeText(text, ta!.selectionStart, ta!.selectionEnd, 'end')
+    ta!.focus()
+  }
+  return (
+    <div data-scope="composer" data-sweep="">
+      <SWEEP />
+      {(files ?? []).length > 0 && (
+        <div data-part="files">
+          {(files ?? []).map(f => (
+            <span key={f.id} data-part="file" data-arrive="">
+              <CheckIcon /><span>{f.name}</span>
+              <Button emphasis="ghost" tone="neutral" size="sm" icon={XIcon} label={`Remove ${f.name}`} onClick={() => onRemoveFile?.(f)} />
+            </span>
+          ))}
+        </div>
+      )}
+      {draft.value && (
+        <div data-part="quote-draft" role="group" aria-label={`Quoting ${draft.value.author}`} data-arrive="">
+          <span data-part="quote-by">{draft.value.author} · {draft.value.time}</span>
+          <span data-part="quote-text">{draft.value.text}</span>
+          <Button emphasis="ghost" tone="neutral" size="sm" icon={XIcon} label="Remove quote" onClick={() => { removeQuote(); ta!.focus(); announce(ta!.ownerDocument, 'Quote removed') }} />
+        </div>
+      )}
+      <label data-part="sr-only" for={id}>{label}</label>
+      <textarea
+        ref={n => { ta = n; if (n) untrack(() => giveInput)?.(n) }}
+        id={id}
+        rows={1}
+        placeholder={placeholder ?? label}
+        aria-describedby={`${id}-h`}
+        aria-autocomplete={hasPeople.value ? 'list' : undefined}
+        aria-controls={open.value ? `${id}-l` : undefined}
+        aria-activedescendant={open.value ? `${id}-o${active.value}` : undefined}
+        onKeyDown={key}
+        onInput={() => { hint.value = null; scan(); onTyping?.() }}
+        onBlur={closeList}
+      ></textarea>
+      <div data-part="row">
+        {canAttach.value && <Button emphasis="ghost" tone="neutral" size="sm" label="Attach" data-icon-only="" onClick={() => onAttach?.()}><PaperclipIcon /></Button>}
+        {canEmoji.value && <Button emphasis="ghost" tone="neutral" size="sm" label="Emoji" data-icon-only="" onClick={() => onEmoji?.(insert)}><SmileIcon /></Button>}
+        {hasPeople.value && <Button emphasis="ghost" tone="neutral" size="sm" label="Mention someone" data-icon-only="" onClick={() => { insert(`${ta!.value && !/\s$/.test(ta!.value) ? ' ' : ''}@`); scan() }}><AtIcon /></Button>}
+        <span data-part="spacer"></span>
+        <span data-part="hint" id={`${id}-h`} data-state={hint.value ? 'error' : undefined}>{hint.value ?? (compact ? '' : HINT)}</span>
+        <button type="button" data-scope="button" data-part="send" data-icon-only="" aria-label="Send" onClick={send}><SendIcon /></button>
+      </div>
+      {open.value && (
+        <div data-scope="suggest" role="listbox" id={`${id}-l`} aria-label="Mention">
+          {shown.value.map(p => (
+            <div key={p.id} role="option" id={`${id}-o${shown.value.findIndex(x => x.id === p.id)}`} aria-selected={shown.value[active.value]?.id === p.id ? 'true' : 'false'} onMouseDown={(e: MouseEvent) => { e.preventDefault(); pick(p) }}>
+              <PeerAvatar peer={p} size="sm" /><span>{p.name}</span><small>{p.status}</small>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/** "Mei is typing…" with three dots (07 §5.1): real data, so it may animate; it holds still under reduced motion. */
+export function TypingIndicator({ text }: { text: string }) {
+  return (
+    <div data-scope="typing" aria-live="polite">
+      {text ? <><span data-part="dots" aria-hidden="true"><i></i><i></i><i></i></span><span>{text}</span></> : ' '}
+    </div>
+  )
+}

package/src/collab/ConversationList.tsx

@@ -0,0 +1,73 @@
+import { PinIcon } from '@weft-js/warp-icons'
+import { peerColor, roving, type Peer } from '@weft-js/warp-core'
+import { Box, derived, state, untrack, type State } from '@weft-js/core'
+import { Badge } from '../Badge'
+import { Avatar } from '../parts'
+import { use } from '@weft-js/warp-core/weft'
+import { tint } from './peer'
+import '../styles'
+import '@weft-js/warp-core/styles/app/tokens.css'
+import '@weft-js/warp-core/styles/app/conversations.css'
+
+/** One conversation in the list. */
+export type ChatConversation = Peer & {
+  /** Last message. */
+  preview: string
+  time: string
+  unread?: number
+  muted?: boolean
+  pinned?: boolean
+  /** A channel draws "#"; a person draws initials. */
+  channel?: boolean
+  online?: boolean
+  href?: string
+}
+
+/**
+ * The conversation list (07 §5.1, §5.4): a listbox with `aria-selected` on the open channel. One tab stop, ↑/↓ and
+ * Home/End rove, Enter or a press opens. `value` is a box or a plain id.
+ */
+export function ConversationList({ label = 'Conversations', title, actions, items, value, onSelect }: { label?: string | undefined; title?: unknown; actions?: unknown; items: ChatConversation[]; value?: State<string> | string; onSelect?: (c: ChatConversation) => void }) {
+  const own = state(untrack(() => (value instanceof Box ? '' : value ?? '')))
+  const current = derived(() => (value instanceof Box ? value.value : value ?? own.value))
+  const heading = derived(() => title)
+  const tools = derived(() => actions)
+  let box: HTMLDivElement | undefined
+  use(roving, () => box, () => ({ items: '[role="option"]', orientation: 'vertical' as const }))
+  const pick = (e: Event, c: ChatConversation) => {
+    if (!c.href) e.preventDefault()
+    if (value instanceof Box) value.value = c.id
+    else own.value = c.id
+    onSelect?.(c)
+  }
+  const stop = derived(() => (items.some(c => c.id === current.value) ? current.value : items[0]?.id))
+  return (
+    <nav data-scope="conversations" aria-label={label}>
+      {(heading.value !== undefined || tools.value !== undefined) && <div style="display:flex;justify-content:space-between;align-items:center;padding:8px 8px 6px">{heading.value}{tools.value}</div>}
+      <div ref={n => (box = n)} role="listbox" aria-label={label} style="display:contents">
+        {items.map(c => (
+          <a
+            key={c.id}
+            href={c.href ?? '#'}
+            role="option"
+            aria-selected={current.value === c.id ? 'true' : 'false'}
+            aria-current={current.value === c.id ? 'page' : undefined}
+            tabindex={stop.value === c.id ? 0 : -1}
+            data-unread={c.unread ? '' : undefined}
+            data-muted={c.muted ? '' : undefined}
+            onClick={(e: MouseEvent) => pick(e, c)}
+            onKeyDown={(e: KeyboardEvent) => { if (e.key === ' ') { e.preventDefault(); pick(e, c) } }}
+          >
+            <Avatar name={c.channel ? '#' : c.name} size="sm" status={c.online ? 'positive' : undefined} style={tint(peerColor(c))} />
+            <b>{c.name}</b>
+            <small>{c.preview}</small>
+            <span data-part="side">
+              <span>{c.time}</span>
+              {c.unread ? <Badge emphasis="solid" count srText={`${c.unread} unread`}>{c.unread}</Badge> : c.pinned ? <PinIcon /> : null}
+            </span>
+          </a>
+        ))}
+      </div>
+    </nav>
+  )
+}

package/src/collab/Cursors.tsx

@@ -0,0 +1,35 @@
+import { cursorsLayer, firstName, peerColor, type CursorPeer, type Peer } from '@weft-js/warp-core'
+import { derived } from '@weft-js/core'
+import { use } from '@weft-js/warp-core/weft'
+import { read, type Live } from './peer'
+import '../styles'
+import '@weft-js/warp-core/styles/app/tokens.css'
+import '@weft-js/warp-core/styles/app/base.css'
+import '@weft-js/warp-core/styles/app/cursors.css'
+import '@weft-js/warp-core/styles/app/cursor.css'
+
+/**
+ * Peer cursors (07 §6.1): arrow and name chip in the peer's colour, anchored to `[data-anchor]` elements in the
+ * positioned parent. Glide 120 ms, fade after `idle` ms, an edge chevron when the anchor is off-screen. aria-hidden.
+ */
+export function Cursors({ peers, anchor, idle = 5000 }: { peers: Live<CursorPeer[]>; anchor?: string | undefined; idle?: number }) {
+  const list = derived(() => read(peers))
+  let layer: HTMLDivElement | undefined
+  use(cursorsLayer, () => layer, () => ({ peers: list.value, anchor, idle }))
+  return (
+    <div ref={n => (layer = n)} data-scope="cursors" aria-hidden="true">
+      {list.value.map(p => (
+        <div key={p.id} data-scope="cursor" data-presence-color={peerColor(p)} data-peer={p.id} style="--_x:0px;--_y:0px">
+          <svg viewBox="0 0 16 16"><path d="M1 1l5.5 13 2-5.5L14 6.5z" /></svg>
+          <span><b>{firstName(p.name)}</b></span>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+/** A peer's selected text (07 §6.1): a tint in their colour and a caret on the focus end. Decorative. */
+export const PeerMark = ({ peer, children }: { peer: Peer; children?: unknown }) => <mark data-peer-text="" data-presence-color={peerColor(peer)}>{children}</mark>
+
+/** A peer's selection on an object: an outline with their name flag. */
+export const PeerSelection = ({ peer, children }: { peer: Peer; children?: unknown }) => <span data-peer-selection={firstName(peer.name)} data-presence-color={peerColor(peer)}>{children}</span>

package/src/collab/DataIntegrity.tsx

@@ -0,0 +1,45 @@
+import { uid, type IntegrityStats } from '@weft-js/warp-core'
+import { derived } from '@weft-js/core'
+import { Button } from '../Button'
+import { LiveStatus, type LiveState } from '../parts'
+import { read, type Live } from './peer'
+import '../styles'
+import '@weft-js/warp-core/styles/app/tokens.css'
+import '@weft-js/warp-core/styles/app/integrity.css'
+
+/** One event of a replication trace. */
+export interface IntegrityEvent { id: string; seq: number; kind: string; route: string; note?: string; lag: number }
+
+/**
+ * The dev-tools panel on a channel (07 §6.4): Sent, Received, Duplicate (caution), Out of order (critical), Lag p95, a
+ * recent-events log, and inject and reset controls for testing a client's dedupe. `integrityCounter` keeps the counts.
+ */
+export function DataIntegrity({ channel, stats, events, live, onInjectDuplicate, onInjectReorder, onReset }: { channel: string; stats: Live<IntegrityStats>; events: Live<IntegrityEvent[]>; live?: LiveState | undefined; onInjectDuplicate?: () => void; onInjectReorder?: () => void; onReset?: () => void }) {
+  const id = uid('integrity')
+  const s = derived(() => read(stats))
+  const log = derived(() => read(events))
+  const hasLive = derived(() => live !== undefined)
+  return (
+    <section data-scope="integrity" aria-labelledby={id}>
+      <div style="display:flex;flex-wrap:wrap;justify-content:space-between;align-items:center;gap:8px">
+        <h3 id={id}>Data integrity · channel “{channel}”</h3>
+        {hasLive.value && <LiveStatus state={live!} />}
+      </div>
+      <dl>
+        <div><dt>Sent</dt><dd data-numeric="">{s.value.sent}</dd></div>
+        <div><dt>Received</dt><dd data-numeric="">{s.value.received}</dd></div>
+        <div><dt>Duplicate</dt><dd data-numeric="" data-tone={s.value.duplicate ? 'caution' : undefined}>{s.value.duplicate}</dd></div>
+        <div><dt>Out of order</dt><dd data-numeric="" data-tone={s.value.outOfOrder ? 'critical' : undefined}>{s.value.outOfOrder}</dd></div>
+        <div><dt>Lag p95</dt><dd data-numeric="">{s.value.lagP95} ms</dd></div>
+      </dl>
+      <ol aria-label="Recent events" tabindex="0">
+        {log.value.map(e => <li key={e.id}><b>#{e.seq}</b><span>{e.kind}</span><span>{e.route}{e.note ? ` · ${e.note}` : ''}</span><span>{e.lag} ms</span></li>)}
+      </ol>
+      <div>
+        <Button emphasis="outline" tone="neutral" size="sm" onClick={() => onInjectDuplicate?.()}>Inject a duplicate</Button>{' '}
+        <Button emphasis="outline" tone="neutral" size="sm" onClick={() => onInjectReorder?.()}>Inject a reorder</Button>{' '}
+        <Button emphasis="ghost" tone="neutral" size="sm" onClick={() => onReset?.()}>Reset counts</Button>
+      </div>
+    </section>
+  )
+}

package/src/collab/Kanban.tsx

@@ -0,0 +1,185 @@
+import { MoreIcon } from '@weft-js/warp-icons'
+import { announce, edges, findCard, isSheet, kanban, menu, moveCard, moveLine, uid, type BoardCard, type BoardColumn } from '@weft-js/warp-core'
+import { Box, derived, flush, state, untrack, watch, type State } from '@weft-js/core'
+import { Button } from '../Button'
+import { Drawer } from '../Drawer'
+import { Input } from '../Field'
+import { use } from '@weft-js/warp-core/weft'
+import { VirtualList, type VirtualControl } from '../VirtualList'
+import { SWEEP } from './peer'
+import '../styles'
+import '@weft-js/warp-core/styles/data/base.css'
+import '@weft-js/warp-core/styles/data/kanban.css'
+import '@weft-js/warp-core/styles/app/kanban.css'
+import '@weft-js/warp-core/styles/layout/edges.css'
+
+
+/** A card on the board, with what warp draws on it. */
+export type KanbanCardData = BoardCard & { label?: string | undefined; color?: number | undefined; assignee?: string | undefined; /** Footer text: a due date, a count. */ meta?: string | undefined }
+/** A board column of warp cards. */
+export type KanbanColumn = BoardColumn<KanbanCardData>
+
+type Ctx = {
+  board: () => KanbanColumn[]
+  move: (id: string, col: number, index: number) => void
+  sheet: (c: KanbanCardData) => void
+  coarse: (el: Element) => boolean
+  focus: (id: string) => void
+  hint: string
+  drift?: (index: number, predicted: number, actual: number) => void
+  window: (column: string, c: VirtualControl) => void
+  adds: () => boolean
+  add: (column: string, title: string) => void
+}
+
+const hasFooter = (c: KanbanCardData) => c.label !== undefined || c.assignee !== undefined || c.meta !== undefined
+
+function Card({ card, ctx }: { card: KanbanCardData; ctx: Ctx }) {
+  const open = state(false)
+  let btn: HTMLButtonElement | undefined
+  let panel: HTMLDivElement | undefined
+  let el: HTMLDivElement | undefined
+  use(menu, () => panel, () => ({ open: open.value, trigger: () => btn, onClose: () => (open.value = false) }))
+  watch(() => open.value, on => { const row = el?.parentElement; if (row) row.style.zIndex = on ? '5' : '' }) // a row is its own stacking context, so the menu's has to rise
+  const to = (col: number, index: number) => {
+    const id = card.id
+    open.value = false
+    ctx.move(id, col, index)
+    ctx.focus(id)
+  }
+  const at = () => findCard(ctx.board(), card.id)
+  return (
+    <div ref={n => (el = n)} data-part="card" data-virtual="" data-focus="" data-sweep="" tabindex="0" draggable="true" data-id={card.id} aria-label={card.title} aria-describedby={ctx.hint}>
+      <SWEEP />
+      <h4 data-measure="">{card.title}</h4>
+      {hasFooter(card) && (
+        <footer>
+          {card.meta}
+          {card.label !== undefined && <span data-part="label-chip" style={`--_dc:var(--warp-color-data-${card.color ?? 1})`}><i></i>{card.label}</span>}
+          {card.assignee !== undefined && <span data-scope="avatar" data-size="sm" aria-hidden="true">{card.assignee}</span>}
+        </footer>
+      )}
+      <button ref={n => (btn = n)} type="button" data-part="move" aria-haspopup="true" aria-expanded={open.value ? 'true' : 'false'} aria-label={`Move ${card.title}`} onClick={(e: MouseEvent) => { if (ctx.coarse(e.currentTarget as Element)) ctx.sheet(card); else open.value = !open.value }}><MoreIcon /></button>
+      <div ref={n => (panel = n)} data-part="menu" hidden={!open.value} role="menu" aria-label="Move to">
+        {open.value && ctx.board().map(c => <button key={c.id} type="button" role="menuitem" tabindex="-1" aria-disabled={at()?.col === ctx.board().indexOf(c) ? 'true' : undefined} onClick={() => { const n = ctx.board().indexOf(c); if (at()?.col !== n) to(n, c.cards.length) }}>Move to {c.title}</button>)}
+        {open.value && <button type="button" role="menuitem" tabindex="-1" onClick={() => { const a = at()!; to(a.col, a.index - 1) }}>Move up</button>}
+        {open.value && <button type="button" role="menuitem" tabindex="-1" onClick={() => { const a = at()!; to(a.col, a.index + 1) }}>Move down</button>}
+      </div>
+    </div>
+  )
+}
+
+function QuickAdd({ column, onAdd }: { column: KanbanColumn; onAdd: (title: string) => void }) {
+  const adding = state(false)
+  const add = (e: Event) => {
+    e.preventDefault()
+    const el = (e.currentTarget as HTMLFormElement).querySelector('input')!
+    if (el.value.trim()) onAdd(el.value.trim())
+    el.value = ''
+  }
+  return (
+    <>
+      {adding.value
+        ? <form onSubmit={add} onKeyDown={(e: KeyboardEvent) => { if (e.key === 'Escape') adding.value = false }}><Input label={`Add a card to ${column.title}`} size="sm" autofocus /></form>
+        : <Button emphasis="ghost" tone="neutral" size="sm" onClick={() => (adding.value = true)}>Add card</Button>}
+    </>
+  )
+}
+
+function Column({ col, ctx, hint }: { col: () => KanbanColumn; ctx: Ctx; hint: string }) {
+  const id = untrack(() => col().id)
+  return (
+    <section data-part="column" aria-labelledby={`${hint}-${id}`} data-over-limit={col().limit !== undefined && col().cards.length > col().limit! ? '' : undefined}>
+      <header data-part="column-head">
+        {col().color !== undefined && <i style={`--_dc:var(--warp-color-data-${col().color})`}></i>}
+        <h3 id={`${hint}-${id}`} style="margin-inline-end:auto">{col().title}</h3>
+        <em data-part="count">{col().cards.length}{col().limit !== undefined ? ` / ${col().limit}` : ''}</em>
+      </header>
+      <VirtualList
+        part="cards"
+        tag="ol"
+        role="list"
+        inner
+        label={col().title}
+        items={col().cards}
+        rowKey={c => c.id}
+        text={c => c.title}
+        variant={c => (hasFooter(c) ? 'footer' : 'plain')}
+        estimate={72}
+        gap={8}
+        onDrift={ctx.drift}
+        control={c => ctx.window(id, c)}
+      >{card => { const c = derived(card); return <Card card={c.value} ctx={ctx} /> }}</VirtualList>
+      {ctx.adds() && <QuickAdd column={col()} onAdd={t => ctx.add(id, t)} />}
+    </section>
+  )
+}
+
+/**
+ * The board (07 §6.2, 06 §10). Columns are `section > ol`, each a window, so one with 10,000 cards costs what one with
+ * 20 does, with count and WIP limit, caution when over. Three move paths: HTML drag with a placeholder; keyboard
+ * (Alt + arrows, or Space, arrows, Space); the Move button, a menu at a fine pointer and a Sheet on a phone. Each move is
+ * announced. `columns` is a box, or a list the board follows and `onMove` reports to. `height` defaults to 560px.
+ */
+export function Kanban({ columns, onMove, onAdd, onDrift, height, label = 'Board' }: { columns: State<KanbanColumn[]> | KanbanColumn[]; onMove?: (id: string, column: string, index: number) => void; onAdd?: (column: string, title: string) => void; onDrift?: ((index: number, predicted: number, actual: number) => void) | undefined; height?: string; label?: string | undefined }) {
+  const hint = uid('kanban')
+  const own = state(untrack(() => (columns instanceof Box ? [] : columns)))
+  const board = derived<KanbanColumn[]>(() => (columns instanceof Box ? columns.value : own.value))
+  watch(() => columns, c => { if (!(c instanceof Box)) own.value = c })
+  const adds = derived(() => onAdd !== undefined)
+  const moving = state<KanbanCardData | null>(null)
+  const sheetOpen = state(false)
+  const windows = new Map<string, VirtualControl>()
+  let host: HTMLDivElement | undefined
+  const focus = (id: string) => {
+    const at = findCard(board.value, id)
+    if (at) queueMicrotask(() => windows.get(board.value[at.col]!.id)?.focus(id)) // focus follows the card
+  }
+  const move = (id: string, col: number, index: number) => {
+    const next = moveCard(board.value, id, col, index)
+    if (columns instanceof Box) columns.value = next
+    else own.value = next
+    flush()
+    const at = findCard(next, id)!
+    announce(host!.ownerDocument, moveLine(next, id))
+    onMove?.(id, next[at.col]!.id, at.index)
+  }
+  use(kanban, () => host, () => ({ columns: () => untrack(() => board.value), onMove: move, focus }))
+  use(edges, () => host) // a column cut at the stage's edge gets a shadow there, as a wide table's does
+  const ctx: Ctx = {
+    board: () => board.value,
+    move,
+    focus,
+    hint,
+    coarse: el => isSheet(el) || !!el.ownerDocument.defaultView?.matchMedia?.('(pointer: coarse)').matches,
+    sheet: c => { moving.value = c; sheetOpen.value = true },
+    drift: (i, p, a) => onDrift?.(i, p, a),
+    window: (column, c) => windows.set(column, c),
+    adds: () => adds.value,
+    add: (column, title) => onAdd?.(column, title),
+  }
+  const sheetTo = (col: number, index: number) => {
+    const id = moving.value!.id
+    sheetOpen.value = false
+    move(id, col, index)
+    focus(id)
+  }
+  const place = derived(() => (moving.value ? findCard(board.value, moving.value.id) : null))
+  return (
+    <>
+      <div data-scope="edges">
+        <div ref={n => (host = n)} data-scope="kanban" role="group" aria-label={label} style={`block-size:${height ?? '560px'}`}>
+          {board.value.map(c => <Column key={c.id} col={() => board.value.find(x => x.id === c.id) ?? c} ctx={ctx} hint={hint} />)}
+        </div>
+      </div>
+      <p data-part="sr-only" id={hint}>Alt plus arrow keys move this card. Space picks it up. The move button lists every destination.</p>
+      <Drawer open={sheetOpen} title={`Move ${moving.value?.title ?? ''}`} side="bottom">
+        <div style="display:grid;gap:4px">
+          {board.value.map(c => <Button key={c.id} emphasis="ghost" tone="neutral" full disabled={place.value !== null && board.value[place.value.col]?.id === c.id} onClick={() => sheetTo(board.value.indexOf(c), c.cards.length)}>Move to {c.title}</Button>)}
+          <Button emphasis="ghost" tone="neutral" full onClick={() => sheetTo(place.value!.col, place.value!.index - 1)}>Move up</Button>
+          <Button emphasis="ghost" tone="neutral" full onClick={() => sheetTo(place.value!.col, place.value!.index + 1)}>Move down</Button>
+        </div>
+      </Drawer>
+    </>
+  )
+}

package/src/collab/Lock.tsx

@@ -0,0 +1,23 @@
+import { firstName, peerColor, uid, type Peer } from '@weft-js/warp-core'
+import { Input } from '../Field'
+import { PeerAvatar } from './peer'
+import '../styles'
+import '@weft-js/warp-core/styles/app/tokens.css'
+import '@weft-js/warp-core/styles/app/base.css'
+import '@weft-js/warp-core/styles/app/lock.css'
+
+/** The chip on a field another peer holds (07 §6.1): "Kofi is editing". */
+export function LockIndicator({ peer, ...rest }: { peer: Peer; [attr: string]: unknown }) {
+  return <span data-scope="lock" data-presence-color={peerColor(peer)} {...rest}><PeerAvatar peer={peer} />{firstName(peer.name)} is editing</span>
+}
+
+/** A text field held by a peer: `readonly`, not disabled, so it stays readable and focusable; the chip describes it. */
+export function LockedField({ peer, ...field }: { peer: Peer | null; label: string; value?: string; [attr: string]: unknown }) {
+  const id = uid('lock')
+  return (
+    <div data-locked-by={peer?.id}>
+      <Input {...field} readonly={peer !== null} aria-describedby={peer ? id : undefined} />
+      {peer && <LockIndicator peer={peer} id={id} />}
+    </div>
+  )
+}

package/src/collab/PresenceStack.tsx

@@ -0,0 +1,67 @@
+import { announce, burst, firstName, followViewport, peerColor, popover, presenceDelta, uid, type Peer } from '@weft-js/warp-core'
+import { derived, onCleanup, onMount, state, untrack, watch } from '@weft-js/core'
+import { use } from '@weft-js/warp-core/weft'
+import { PeerAvatar, read, type Live } from './peer'
+import '../styles'
+import '@weft-js/warp-core/styles/components/popover.css'
+import '@weft-js/warp-core/styles/app/tokens.css'
+import '@weft-js/warp-core/styles/app/base.css'
+import '@weft-js/warp-core/styles/app/avatar-stack.css'
+import '@weft-js/warp-core/styles/app/follow-flag.css'
+
+/**
+ * Who is here (07 §6.1): avatars with a ring in each peer's colour, `+n` overflow opening the list, joins and leaves
+ * announced as one summary. With `onFollow` each avatar is a toggle: `following` is the peer's id.
+ */
+export function PresenceStack({ peers, max = 4, following, onFollow, label = 'People here' }: { peers: Live<Peer[]>; max?: number | undefined; following?: string | null | undefined; onFollow?: (p: Peer | null) => void; label?: string | undefined }) {
+  const id = uid('presence')
+  const list = derived(() => read(peers))
+  const front = derived(() => list.value.slice(0, max))
+  const rest = derived(() => list.value.slice(max))
+  const open = state(false)
+  const canFollow = derived(() => onFollow !== undefined)
+  let more: HTMLButtonElement | undefined
+  let panel: HTMLDivElement | undefined
+  use(popover, () => panel, () => ({ open: open.value, trigger: more!, onClose: () => (open.value = false) }))
+  onMount(() => {
+    const told = burst<string>(lines => announce(panel!.ownerDocument, lines.join('. ')))
+    let was = untrack(() => list.value)
+    onCleanup(told.cancel)
+    watch(() => list.value, now => {
+      const line = presenceDelta(was, now)
+      was = now
+      if (line) told.push(line)
+    })
+  })
+  return (
+    <span data-scope="avatar-stack" role="group" aria-label={label}>
+      {front.value.map(p => (canFollow.value
+        ? <button key={p.id} type="button" data-hit="" aria-pressed={following === p.id ? 'true' : 'false'} style="all:unset;cursor:pointer;border-radius:99px" onClick={() => onFollow!(following === p.id ? null : p)}><span data-part="sr-only">Follow {p.name}</span><PeerAvatar peer={p} size="sm" ring /></button>
+        : <PeerAvatar key={p.id} peer={p} size="sm" ring />))}
+      {rest.value.length > 0 && <button ref={n => (more = n)} type="button" data-part="more" aria-haspopup="dialog" aria-expanded={open.value ? 'true' : 'false'} aria-controls={id} aria-label={`${rest.value.length} more people`} style="border:0;margin-inline-start:0;cursor:pointer" onClick={() => (open.value = !open.value)}>+{rest.value.length}</button>}
+      <div ref={n => (panel = n)} data-scope="popover" data-part="content" role="dialog" popover="manual" id={id} aria-label={label}>
+        <ul>{list.value.map(p => <li key={p.id}>{p.name}</li>)}</ul>
+      </div>
+    </span>
+  )
+}
+
+/**
+ * Following (07 §6.1): wraps the surface that rides the peer's viewport. The frame and the flag take their colour; any
+ * scroll of the user's, or Esc, stops. `top` is the peer's viewport top, 0–1.
+ */
+export function Following({ peer, top, onStop, children, ...rest }: { peer: Peer | null; top?: number | undefined; onStop: () => void; children?: unknown; [attr: string]: unknown }) {
+  let el: HTMLDivElement | undefined
+  const on = derived(() => peer !== null)
+  onMount(() => watch(() => peer, (p, was) => {
+    if (p) announce(el!.ownerDocument, `Following ${p.name}`)
+    else if (was) announce(el!.ownerDocument, 'Stopped following')
+  }))
+  use(followViewport, () => el, () => ({ on: on.value, top, onStop }))
+  return (
+    <div ref={n => (el = n)} data-following={on.value ? '' : undefined} data-presence-color={peer ? peerColor(peer) : undefined} style="position:relative" {...rest}>
+      {peer && <span data-scope="follow-flag" data-presence-color={peerColor(peer)}>Following {firstName(peer.name)} · Esc to stop</span>}
+      {children}
+    </div>
+  )
+}