@weft-js/warp 0.0.0-stage → 0.1.0

package/src/flow/Tour.tsx

@@ -0,0 +1,108 @@
+import { announce, coachSpot, tourSpot, uid } from '@weft-js/warp-core'
+import { derived, state, untrack, watch, type State } from '@weft-js/core'
+import { Button } from '../Button'
+import { bindable } from '../Picker'
+import { use } from '@weft-js/warp-core/weft'
+import '../styles'
+import '@weft-js/warp-core/styles/flows/tokens.css'
+import '@weft-js/warp-core/styles/flows/base.css'
+import '@weft-js/warp-core/styles/components/tour.css'
+import '@weft-js/warp-core/styles/flows/tour.css'
+
+/** One stop of a tour. */
+export interface TourStep {
+  /** A CSS selector: `[data-tour=new]`. */
+  target: string
+  title: unknown
+  body: unknown
+  /** The target stays pressable ("Try it: click New"). */
+  interactive?: boolean | undefined
+}
+
+/** Props for Tour. */
+export interface TourProps {
+  id?: string
+  steps: TourStep[]
+  open?: State<boolean> | boolean
+  /** Ran to the end. */
+  onDone?: () => void
+  /** Skip or Escape. */
+  onSkip?: () => void
+  onStepChange?: ((index: number) => void) | undefined
+}
+
+function Running({ steps, onEnd, onStepChange }: { steps: TourStep[]; onEnd: (done: boolean) => void; onStepChange?: ((i: number) => void) | undefined }) {
+  const id = uid('tour')
+  const list = untrack(() => steps)
+  const at = state(0)
+  const way = state(1)
+  const step = derived(() => list[at.value])
+  const many = list.length > 1
+  const go = (i: number, dir = 1) => {
+    way.value = dir
+    if (i < 0) return
+    if (i >= list.length) return onEnd(true)
+    at.value = i
+    onStepChange?.(i)
+  }
+  watch(() => at.value, i => { if (typeof document === 'object') announce(document, `${many ? `Step ${i + 1} of ${list.length}. ` : ''}${typeof list[i]!.title === 'string' ? list[i]!.title : ''}`) })
+  let root: HTMLDivElement | undefined
+  use(tourSpot, () => root, () => ({
+    target: step.value!.target, step: at.value, interactive: step.value!.interactive,
+    onNext: () => go(at.value + 1), onPrev: () => go(at.value - 1, -1), onClose: () => onEnd(false),
+    onMissing: () => (way.value < 0 && at.value === 0 ? onEnd(false) : go(at.value + way.value, way.value)),
+    onBlocked: () => onEnd(false),
+  }))
+  return (
+    <div ref={n => (root = n)} data-scope="tour">
+      <div data-part="spotlight" data-sweep="" data-hold=""><span data-part="sweep-base" aria-hidden="true"></span><span data-part="sweep" aria-hidden="true"></span></div>
+      <div data-part="card" role="dialog" aria-modal="false" aria-labelledby={`${id}-t`} aria-describedby={`${id}-d`}>
+        <span data-part="step-count">{many ? `Step ${at.value + 1} of ${list.length}` : 'Tip'}</span>
+        <h4 id={`${id}-t`} tabindex="-1" aria-level="2">{step.value!.title}</h4>
+        <p id={`${id}-d`}>{step.value!.body}</p>
+        <footer>
+          <span data-part="pips" aria-hidden="true">{many && list.map((s, i) => <i key={s.target} data-on={i === at.value ? '' : undefined}></i>)}</span>
+          <Button emphasis="ghost" tone="neutral" size="sm" onClick={() => onEnd(false)}>Skip tour</Button>
+          {at.value > 0 && <Button emphasis="ghost" tone="neutral" size="sm" onClick={() => go(at.value - 1, -1)}>Back</Button>}
+          <Button size="sm" onClick={() => go(at.value + 1)}>{at.value === list.length - 1 ? 'Done' : 'Next'}</Button>
+        </footer>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * The product tour (09 §3.2): a spotlight cut by the scrim, a ring that draws on arrival, a card beside the target
+ * (docked on a phone). A missing target skips its step; it starts only on request and never over another overlay; Esc
+ * ends it and focus returns to where it began.
+ */
+export function Tour({ steps, open, onDone, onSkip, onStepChange }: TourProps) {
+  const on = bindable<boolean>(() => open, () => false, false)
+  const end = (done: boolean) => {
+    on.set(false)
+    ;(done ? onDone : onSkip)?.()
+  }
+  return <>{on.value && <Running steps={steps} onEnd={end} onStepChange={onStepChange} />}</>
+}
+
+/** A coachmark (09 §3.2): one tip with no scrim: a beacon on the target, the card on a press. Persisting the dismissal is the app's (`onDismiss`). */
+export function Coachmark({ target, title, body, onDismiss }: { target: string; title: unknown; body: unknown; onDismiss?: () => void }) {
+  const id = uid('coach')
+  const open = state(false)
+  const gone = state(false)
+  let root: HTMLDivElement | undefined
+  use(coachSpot, () => root, () => ({ target, open: open.value, onClose: () => (open.value = false) }))
+  return (
+    <div ref={n => (root = n)} data-scope="tour" hidden={gone.value || undefined}>
+      <button type="button" data-scope="button" data-emphasis="ghost" data-tone="neutral" data-size="sm" data-icon-only="" data-beacon="" aria-label="Show tip" aria-expanded={open.value ? 'true' : 'false'} onClick={() => (open.value = !open.value)}><span data-part="beacon" aria-hidden="true"></span></button>
+      {open.value && (
+        <div data-part="card" role="dialog" aria-modal="false" aria-labelledby={`${id}-t`}>
+          <span data-part="step-count">Tip</span>
+          <h4 id={`${id}-t`} tabindex="-1" aria-level="2">{title}</h4>
+          <p>{body}</p>
+          <footer><span data-part="pips"></span><Button size="sm" onClick={() => { open.value = false; gone.value = true; onDismiss?.() }}>Got it</Button></footer>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/flow/index.ts

@@ -0,0 +1,17 @@
+// The flow pack: see docs/design/warp. One file per component family; each imports only its own CSS.
+export { Flow, type FlowProps, type FlowStep } from './Flow'
+export { AuthScreen } from './AuthScreen'
+export { SignIn, type SignInProps, type SignInValues } from './SignIn'
+export { SignUp, PasswordMeter, type SignUpProps, type SignUpValues } from './SignUp'
+export { OtpField, OtpStep, type OtpFieldProps, type OtpStepProps, type OtpValues } from './Otp'
+export { MagicLinkSent, ResetPassword, InviteAccept, AuthDone, type ResetPasswordProps, type ResetValues } from './AuthSteps'
+export { ReauthDialog, type ReauthProps } from './ReauthDialog'
+export { PasskeyButton, SsoButtons, type SsoProvider } from './Sso'
+export { MfaSetup, type MfaSetupProps } from './MfaSetup'
+export { SignGate, SignGateBadge, type SignGateProps, type SignStatus } from './SignGate'
+export { Checklist, type ChecklistProps, type ChecklistItem } from './Checklist'
+export { Tour, Coachmark, type TourProps, type TourStep } from './Tour'
+export { SystemPage, type SystemPageProps, type AccessRequest, type SwitchAccount } from './SystemPage'
+export { ConnBanner, RateLimited, type ConnBannerProps, type RateLimitedProps } from './ConnBanner'
+export { ShortcutsOverlay } from './ShortcutsOverlay'
+export { useCooldown, type FlowForm, type FormLike } from './kit'

package/src/flow/kit.tsx

@@ -0,0 +1,170 @@
+// What the flow screens share (09 §1): the title, mark and rail parts, the step's form frame and its error surfaces.
+// Internal, except what the barrel names.
+import { announce, mapFlowError, secondsClock, type FlowError, type FlowErrorOptions } from '@weft-js/warp-core'
+import { derived, flush, onCleanup, onMount, state, untrack, watch } from '@weft-js/core'
+import { Alert } from '../Alert'
+import { Button, type ButtonProps } from '../Button'
+import { Banner } from '../parts'
+import { toast } from '../Toast'
+import '../styles'
+import '@weft-js/warp-core/styles/flows/tokens.css'
+import '@weft-js/warp-core/styles/flows/base.css'
+import '@weft-js/warp-core/styles/flows/meter.css' // the result mark
+import '@weft-js/warp-core/styles/layout/stack.css'
+
+export type Heading = 'h1' | 'h2' | 'h3'
+
+/** A step's title: focus lands here on arrival (09 §1.1). */
+export function Title({ as, id, children }: { as?: Heading | undefined; id?: string; children?: unknown }) {
+  const level = derived(() => as ?? 'h1')
+  return (
+    <>
+      {level.value === 'h3' ? <h3 data-part="title" data-part-title="" tabindex="-1" id={id}>{children}</h3>
+        : level.value === 'h2' ? <h2 data-part="title" data-part-title="" tabindex="-1" id={id}>{children}</h2>
+        : <h1 data-part="title" data-part-title="" tabindex="-1" id={id}>{children}</h1>}
+    </>
+  )
+}
+
+/** The result mark; `draw` strokes a check in. */
+export function Mark({ tone, draw, children }: { tone?: 'positive' | 'caution' | 'critical' | undefined; draw?: boolean; children?: unknown }) {
+  return <span data-part="mark" data-tone={tone}>{draw ? <svg viewBox="0 0 24 24" aria-hidden="true"><path pathLength="1" data-draw="" d="m5 12.5 4.5 4.5L19 7.5" /></svg> : children}</span>
+}
+
+/** The flows rail: `value` in percent. */
+export function Rail({ value, on = true, ...rest }: { value: number; on?: boolean; [attr: string]: unknown }) {
+  return <span data-part="rail" data-on={on ? '' : undefined} style={`--v:${value}%`} {...rest}><span data-part="rail-fill"></span></span>
+}
+
+/**
+ * Seconds counting down to zero while `seconds()` holds a number; a new number restarts it. Nothing runs on the server
+ * or before mount, so the first paint is the full count.
+ */
+export function useCooldown(seconds: () => number | undefined, onDone?: () => void) {
+  const left = state(untrack(seconds) ?? 0)
+  let stop: (() => void) | undefined
+  const start = (n: number | undefined) => {
+    stop?.()
+    stop = undefined
+    left.value = n ?? 0
+    if (n) stop = secondsClock(n, s => (left.value = s), onDone)
+  }
+  onMount(() => {
+    // a fresh object each run: a restart with the same seconds still restarts
+    watch(() => ({ n: seconds() }), v => start(v.n))
+    onCleanup(() => stop?.())
+  })
+  return left
+}
+
+/** What `<Form of={mutation}>` gives its children; a step reads it, so warp never imports the server's Form. */
+export interface FormLike {
+  readonly pending: { readonly value: boolean }
+  readonly errors: { readonly value: Record<string, string> }
+  readonly message: { readonly value: string | undefined }
+  value?(name: string): unknown
+}
+
+/** How a screen is driven: inside `<Form of>` (pass `form`), or on its own with `onSubmit` and `errors`. */
+export interface FlowForm<V> {
+  /** The `<Form of={mutation}>` render argument: the screen then renders no <form> of its own. */
+  form?: FormLike
+  /** Called with the form's values once its own checks pass. */
+  onSubmit?: (values: V, e: SubmitEvent) => void
+  /** Messages by field name. */
+  errors?: Record<string, string> | undefined
+  /** The failure: anything `mapFlowError` takes (a `FnError`, a typed error, a string). */
+  error?: unknown
+  /** Options for `mapFlowError`: copy by code, and `online`. */
+  errorOptions?: FlowErrorOptions | undefined
+  pending?: boolean | undefined
+  /** The Retry on a network failure's toast. */
+  onRetry?: (() => void) | undefined
+  /** The title's level (default h1: an auth step is the page). */
+  heading?: Heading
+}
+
+/** One step's form state: errors from all three sources, the mapped failure and its cooldown, its surfaces' side effects. */
+export function useStepForm<V>(p: FlowForm<V>, check?: (values: Record<string, string>) => Record<string, string | undefined>) {
+  const own = state<Record<string, string>>({})
+  const failure = derived(() => {
+    const e = p.form ? p.form.message.value : p.error
+    return e ? mapFlowError(e, untrack(() => p.errorOptions)) : undefined
+  })
+  const errors = derived<Record<string, string>>(() => ({ ...own.value, ...failure.value?.fields, ...(p.form ? p.form.errors.value : p.errors) }))
+  const pending = derived(() => !!(p.form ? p.form.pending.value : p.pending))
+  const cooling = useCooldown(() => failure.value?.retryAfter, () => announce(document, 'You can try again now.'))
+  let root: HTMLElement | undefined
+  const focusInvalid = (say?: string) => {
+    flush()
+    root?.querySelector<HTMLElement>('[aria-invalid="true"]')?.focus()
+    if (say) announce(document, say)
+  }
+  onMount(() => {
+    watch(() => failure.value, (m: FlowError | undefined) => {
+      if (!m) return
+      if (m.surface === 'field') focusInvalid(m.summary)
+      if (m.surface === 'alert') { flush(); root?.querySelector<HTMLElement>('[data-part="formerr"]')?.focus() }
+      if (m.surface === 'rate-limit') announce(document, `${m.title} Try again in ${m.retryAfter}s.`)
+      if (m.surface === 'toast') toast.show({ title: m.title, description: m.description, tone: 'critical', action: p.onRetry && { label: 'Retry', onClick: () => p.onRetry!() } })
+    })
+    let sent = 0
+    watch(() => Object.keys(p.form ? p.form.errors.value : (p.errors ?? {})).length, n => {
+      if (n && n !== sent) focusInvalid()
+      sent = n
+    })
+  })
+  const submit = (e: SubmitEvent) => {
+    e.preventDefault()
+    const f = e.currentTarget as HTMLFormElement
+    const values = Object.fromEntries(new FormData(f)) as Record<string, string>
+    const bad = Object.fromEntries(Object.entries(check?.(values) ?? {}).filter(([, m]) => m)) as Record<string, string>
+    own.value = bad
+    const n = Object.keys(bad).length
+    if (n) return focusInvalid(n > 1 ? `${n} fields need attention` : undefined)
+    p.onSubmit?.(values as V, e)
+  }
+  return {
+    errors, failure, pending, cooling, submit,
+    /** Set one field's message from the client (format on blur), or clear it. */
+    flag(name: string, message: string | undefined) {
+      const { [name]: _, ...rest } = own.value
+      own.value = message ? { ...rest, [name]: message } : rest
+    },
+    bind(n: HTMLElement) { root = n },
+  }
+}
+export type StepForm = ReturnType<typeof useStepForm>
+
+/** The step's frame: a <form> of its own, or a plain stack inside `<Form of>`. */
+export function StepFrame({ ctl, embedded, labelledby, children }: { ctl: StepForm; embedded: boolean; labelledby?: string; children?: unknown }) {
+  const plain = derived(() => embedded)
+  return (
+    <>
+      {plain.value
+        ? <div ref={n => ctl.bind(n)} data-scope="stack" role="group" aria-labelledby={labelledby}>{children}</div>
+        : <form ref={n => ctl.bind(n)} data-scope="stack" novalidate aria-labelledby={labelledby} onSubmit={ctl.submit}>{children}</form>}
+    </>
+  )
+}
+
+/** The failure at the top of the step (09 §1.3): the Alert takes focus; a rate limit counts down; offline is a Banner. */
+export function FormError({ ctl, actions }: { ctl: StepForm; actions?: unknown }) {
+  const m = derived(() => ctl.failure.value)
+  return (
+    <div data-part="formerr" tabindex="-1">
+      {m.value?.surface === 'alert' && <Alert tone="critical" live title={m.value.title} actions={actions}>{m.value.description}</Alert>}
+      {m.value?.surface === 'rate-limit' && <Alert tone="caution" title={m.value.title}>{ctl.cooling.value > 0 ? `Try again in ${ctl.cooling.value}s.` : 'You can try again now.'}</Alert>}
+      {m.value?.surface === 'banner' && <Banner tone="caution" live={m.value.live}><b>{m.value.title}</b> {m.value.description}</Banner>}
+    </div>
+  )
+}
+
+/** The one solid: keeps its label while pending; a rate limit disables it and says why. */
+export function Submit({ ctl, disabled, children, ...rest }: { ctl: StepForm; disabled?: boolean | undefined; children?: unknown } & ButtonProps) {
+  const wait = derived(() => ctl.cooling.value)
+  return <Button type="submit" size="lg" full loading={ctl.pending.value} disabled={disabled || wait.value > 0} {...rest}>{wait.value > 0 ? `Try again in ${wait.value}s` : children}</Button>
+}
+
+/** A text button in a step's row. */
+export const TextLink = ({ children, ...rest }: ButtonProps) => <Button emphasis="link" data-hit="text" {...rest}>{children}</Button>

package/src/index.ts

@@ -0,0 +1,74 @@
+// @weft-js/warp: the weft binding of warp. Each component renders the spec's specimen markup with weft's compiled
+// templates and attaches warp-core's behaviour; each imports only its own CSS (warp-core/styles, split per component).
+export { Stack, Row, Grid, Split, Center, Cover, Frame, Spacer, Inset, type Step } from './Layout'
+export { Heading, Text, Link } from './Type'
+export { Button, type ButtonProps, type Tone, type Emphasis } from './Button'
+export { Toggle, type ToggleProps } from './Toggle'
+export { Field, Input, Search, Textarea, type FieldProps } from './Field'
+export { NumberField, type NumberFieldProps } from './NumberField'
+export { CompactSelect, Select, type Option, type OptionGroup } from './Select'
+export { Switch, Checkbox, Radio, RadioGroup, Segmented, type SegmentedOption, type RadioOption } from './Choice'
+export { Slider, type SliderProps } from './Slider'
+export { Accordion, type AccordionItem, type AccordionProps } from './Accordion'
+export { Ticker, type TickerProps } from './Ticker'
+export { Menu, type MenuEntry as MenuItem, type MenuProps } from './Menu'
+export { Chip } from './Chip'
+export { Tabs, type TabOption } from './Tabs'
+export { Nav } from './Nav'
+export { Card } from './Card'
+export { Badge } from './Badge'
+export { Tag } from './Tag'
+export { Kbd } from './Kbd'
+export { Alert } from './Alert'
+export { Progress } from './Progress'
+export { Spinner } from './Spinner'
+export { Skeleton } from './Skeleton'
+export { Shape } from './Shape'
+export { Tooltip } from './Tooltip'
+export { Popover } from './Popover'
+export { Modal } from './Modal'
+export { Drawer } from './Drawer'
+export { Toaster, toast } from './Toast'
+export { Table, type Column, type TableProps, type TableSort, type TableStatus, type ListPage } from './Table'
+export { DataGrid, PivotTable, type DataGridProps, type GridColumn, type GridView, type GridTree, type GridPaste, type PivotMeasure } from './DataGrid'
+export { PaginationBar, LoadMore, type PaginationBarProps } from './Pagination'
+export { CommandPalette, type Command, type CommandMode, type CommandSource, type CommandPaletteProps } from './CommandPalette'
+export { MentionsInput, type MentionsInputProps } from './MentionsInput'
+export { CodeBlock, Code, Snippet, type CodeBlockProps } from './CodeBlock'
+export { CodeInput, JsonEditor, type CodeInputProps, type JsonEditorProps } from './CodeInput'
+export { KeyValueEditor, type KeyValue, type KeyValueEditorProps } from './KeyValueEditor'
+export { RichTextEditor, type RichTextEditorProps, type SlashCommand } from './RichTextEditor'
+export { Markdown, MarkdownEditor, type MarkdownEditorProps } from './Markdown'
+export { Shell, type ShellProps, type NavItem, type NavGroup, type NavIcon, type Crumb, type MenuEntry, type Workspace } from './Shell'
+/** A docs sidebar: one left panel whose sections fold and remember; docked from 900px, opened over the page on phones. */
+export { SideNav, type SideNavProps, type SideNavSection, type SideNavLink } from './SideNav'
+export { Icon, type IconName, type IconRef } from './Icon'
+export { Chart, type ChartFrame } from './Chart'
+export { LineChart, BarChart, ComboChart, DonutChart, RadialChart, FunnelChart, ScatterChart, BubbleChart, Histogram, HeatGrid, RadarChart, Treemap, Sunburst, SankeyChart, CandlestickChart, BoxPlot, WaterfallChart, StreamChart, BrushChart, TileMap, GaugeChart, Sparkline } from './Charts'
+export { type Bindable, type Openable } from './Picker'
+export { InlineCalendar } from './Calendar'
+export { DateField, DateRangeField, compareRange, type DateFieldProps, type DateRangeFieldProps } from './DateField'
+export { TimeField, DateTimeField, type TimeFieldProps, type DateTimeFieldProps } from './TimeField'
+export { MonthPicker, WeekPicker, PeriodPicker, type MonthPickerProps, type WeekPickerProps, type PeriodPickerProps } from './MonthPicker'
+export { TimeZoneSelect, CountrySelect, LanguageSelect, CurrencySelect, PhoneField, type TimeZoneSelectProps, type PhoneFieldProps } from './RichSelect'
+export { DurationField, type DurationFieldProps } from './DurationField'
+export { RecurrenceField, type RecurrenceFieldProps } from './RecurrenceField'
+export { PlaceLookupInput, AddressField, type Place, type PlaceBias, type PlaceLookupInputProps, type AddressFieldProps, type AddressProvider } from './PlaceField'
+export { PaymentCardInput, CardNumberText, type PaymentCardInputProps, type ProviderField, type ProviderAppearance, type CardNumberTextProps } from './PaymentCard'
+export { SignaturePad, type SignaturePadProps, type SignatureValue } from './SignaturePad'
+export { Canvas, CanvasStage, StageSelect, type CanvasProps, type CanvasStageProps, type StageOption, type StageSelectProps, type Frame as CanvasFrame, type Press, type Scene, type Scroll, type StageLayout, type StagePainter, type StagePiece, type Word } from './Canvas'
+export { Dither, DitherField, DitherGlyph, DitherStage, LEVEL, PAINTERS, type DitherProps, type DitherFieldProps, type DitherGlyphProps, type DitherStageProps, type Algorithm, type Brush, type DitherPainter, type DitherPiece, type FieldFn, type FieldName, type Gradient, type MaskSource, type Pattern, type PointerMode, type Ramp, type Skin } from './Dither'
+export * from './agent/index'
+export * from './schedule/index'
+export * from './live/index'
+export * from './collab/index'
+export { Thread, Kanban } from './collab/index' // the one chat and the one board: both are windows (VirtualList)
+export * from './flow/index'
+export * from './admin/index'
+export { VirtualList, type VirtualListProps, type VirtualControl } from './VirtualList'
+export { Feed, type FeedProps, type FeedItem } from './Feed'
+export { ScrollGrid, type ScrollGridProps, type GridColumn as ScrollGridColumn } from './ScrollGrid'
+export type { Address, MentionItem } from '@weft-js/warp-core'
+export type { Peer, CursorPeer, IntegrityStats, ChatMessage, MessageReaction } from '@weft-js/warp-core'
+export type { IsoDate, IsoTime, IsoDateTime, IsoMonth, IsoWeek, IsoDuration, IsoZoned, TimeZoneId, DateRange, ChangeReason } from '@weft-js/warp-core'
+export { sweep, setDial, getDial } from '@weft-js/warp-core'

package/src/layout.css

@@ -0,0 +1,4 @@
+/* 02 §3 lists `page` in the Space scale; the spec's layout CSS stops at `section`. */
+@layer warp.layout {
+:where([data-gap="page"]) { --_gap: var(--warp-space-page); }
+}

package/src/links.css

@@ -0,0 +1,4 @@
+/* A bare `<a>` is never the browser's blue: warp's link ink and hairline underline (05 §4), in warp.base so every component's own link and app CSS win. */
+@layer warp.base {
+:where(a:any-link) { color: var(--warp-color-accent-text); text-decoration-thickness: var(--warp-border-hairline); text-underline-offset: 0.22em; }
+}

package/src/live/ActivityFeed.tsx

@@ -0,0 +1,49 @@
+import { arrivals, groupByDay, uid } from '@weft-js/warp-core'
+import { derived } from '@weft-js/core'
+import { Avatar, type LiveState } from '../parts'
+import { use } from '@weft-js/warp-core/weft'
+import { avatarTint, G, val } from './shared'
+import '../styles'
+import '@weft-js/warp-core/styles/app/base.css'
+import '@weft-js/warp-core/styles/app/activity.css'
+import '@weft-js/warp-core/styles/app/activity-feed.css'
+import '@weft-js/warp-core/styles/app/sync.css'
+
+/** One line of the activity feed. */
+export interface ActivityItem { id: string; actor: string; verb: string; object?: string; detail?: string; time: string; datetime?: string; day?: string }
+
+/**
+ * Activity feed (07 §4.2): actor, verb, object, time, grouped per day on a hairline spine, the quiet sibling of the inbox
+ * row. The header shows a "Live" check while `live` is live; new ids arrive.
+ */
+export function ActivityFeed({ items, live, title = 'Activity', level = 3 }: { items: ActivityItem[] | { value: ActivityItem[] } | (() => ActivityItem[]); live?: LiveState | { value: LiveState } | (() => LiveState) | undefined; title?: string; /** The title's heading level: one below the heading the feed sits under. */ level?: 2 | 3 | 4 | 5 | 6 }) {
+  const id = uid('activity')
+  const data = derived(() => (val<ActivityItem[]>(items) ?? []))
+  const days = derived(() => groupByDay(data.value))
+  const many = derived(() => days.value.length > 1 || data.value.some(n => n.day))
+  const on = derived(() => val<LiveState | undefined>(live) === 'live')
+  let root: HTMLElement | undefined
+  use(arrivals, () => root, () => ({ items: '[data-scope="activity"] > li', ids: data.value.map(n => n.id) }))
+  return (
+    <section ref={n => (root = n)} data-scope="activity-feed" aria-labelledby={`${id}-t`}>
+      <header>
+        <h3 id={`${id}-t`} aria-level={level === 3 ? undefined : level}>{title}</h3>
+        {on.value && <span data-scope="sync" data-state="saved"><G name="check" /> Live</span>}
+      </header>
+      {days.value.map(g => (
+        <div key={g.day}>
+          {many.value && <span data-part="eyebrow">{g.day}</span>}
+          <ol data-scope="activity">
+            {g.rows.map(n => (
+              <li key={n.id} data-id={n.id}>
+                <Avatar name={n.actor} size="sm" style={avatarTint(n.actor)} />
+                <span><b>{n.actor}</b> {n.verb}{n.object ? ' ' : ''}{n.object && <b>{n.object}</b>}{n.detail ? ` ${n.detail}` : ''}</span>
+                <time datetime={n.datetime}>{n.time}</time>
+              </li>
+            ))}
+          </ol>
+        </div>
+      ))}
+    </section>
+  )
+}

package/src/live/Bell.tsx

@@ -0,0 +1,62 @@
+import { bellCount, bellLabel, bump, popover, uid, type Align, type Side } from '@weft-js/warp-core'
+import { derived, onMount, state, untrack, watch, type State } from '@weft-js/core'
+import { Button } from '../Button'
+import { Badge } from '../Badge'
+import { use } from '@weft-js/warp-core/weft'
+import { G, val } from './shared'
+import '../styles'
+import '@weft-js/warp-core/styles/components/popover.css'
+import '@weft-js/warp-core/styles/app/bell.css'
+import '@weft-js/warp-core/styles/app/badge.css'
+
+/** Props for Bell. */
+export interface BellProps {
+  /** Unread count: a number, a State or a getter. */
+  count?: number | { value: number } | (() => number | undefined)
+  onOpen?: () => void
+  /** The panel, usually `open => <Inbox variant="popover" open={open.value} … />`, shown in a Popover from the bell. */
+  inbox?: (open: State<boolean>) => unknown
+  /** On a phone the inbox is a page, not a popover (07 §4.3): below 600px the bell calls this instead of opening. */
+  route?: () => void
+  side?: Side | undefined
+  align?: Align
+}
+
+/** Bell (07 §4.1): icon button and count badge, which bumps once per batch; its name says the count (§4.5). */
+export function Bell({ count, onOpen, inbox, route, side = 'bottom', align = 'end' }: BellProps) {
+  const id = uid('bell')
+  const n = derived(() => Number(val<unknown>(count) ?? 0))
+  const open = state(false)
+  const panel = untrack(() => inbox)
+  let button: HTMLButtonElement | undefined
+  let box: HTMLDivElement | undefined
+  let badge: HTMLElement | undefined
+  use(popover, () => box, () => ({ open: open.value, trigger: button!, side, align, onClose: () => (open.value = false) }))
+  onMount(() => watch(() => n.value, (v, prev) => { if (prev !== undefined && v > prev && badge) bump(badge) }))
+  const press = () => {
+    const toPage = route && button!.ownerDocument.defaultView!.matchMedia?.('(max-width: 599.98px)').matches
+    onOpen?.()
+    if (toPage) route()
+    else if (panel) open.value = !open.value
+  }
+  return (
+    <span data-scope="bell">
+      <Button
+        emphasis="ghost"
+        tone="neutral"
+        data-icon-only=""
+        ref={(el: HTMLButtonElement) => (button = el)}
+        id={`${id}-b`}
+        aria-label={bellLabel(n.value)}
+        aria-haspopup={panel ? 'dialog' : undefined}
+        aria-expanded={panel ? (open.value ? 'true' : 'false') : undefined}
+        aria-controls={panel ? id : undefined}
+        onClick={press}
+      >
+        <G name="bell" />
+      </Button>
+      <Badge emphasis="solid" count ref={(el: HTMLElement) => (badge = el)} hidden={n.value === 0} aria-hidden="true">{bellCount(n.value)}</Badge>
+      {panel && <div ref={el => (box = el)} data-scope="popover" data-part="content" role="dialog" popover="manual" id={id} aria-label="Notifications">{panel(open)}</div>}
+    </span>
+  )
+}

package/src/live/Connection.tsx

@@ -0,0 +1,49 @@
+import { announce, connectionAnnouncement, liveState, type LiveState } from '@weft-js/warp-core'
+import { derived, onCleanup, onMount, state, untrack, watch } from '@weft-js/core'
+import { Banner, LiveStatus } from '../parts'
+import { Button } from '../Button'
+import { val } from './shared'
+
+const TEXT: Record<LiveState, string> = { connecting: 'Connecting…', live: 'Live', reconnecting: 'Reconnecting…', offline: 'Offline' }
+
+type Status = string | undefined | { value: string } | (() => string | undefined)
+
+/**
+ * The one pill (07 §0, §4.4): `state` is `.live`, `stream().status` or `channel.status`, mapped to the four states. It
+ * announces each change once; `queued` is the count in "Back online. 4 updates."
+ */
+export function ConnectionPill({ state: status, label = 'Connection', queued = 0 }: { state: Status; label?: string | undefined; queued?: number }) {
+  const now = derived(() => liveState(val<string | undefined>(status)))
+  const words = derived(() => TEXT[now.value])
+  let root: HTMLSpanElement | undefined
+  onMount(() => watch(() => now.value, (next, prev) => {
+    const say = connectionAnnouncement(prev, next, untrack(() => queued))
+    if (say && root) announce(root.ownerDocument, say.text, say.assertive)
+  }))
+  return <span ref={n => (root = n)}><LiveStatus state={now.value} label={label}>{words.value}</LiveStatus></span>
+}
+
+/**
+ * The trouble banner (07 §4.4): nothing while live or connecting, after `delay` ms of reconnecting (data stays, edits
+ * queue), at once when offline, with Retry. Quiet for assistive tech: the pill does the announcing.
+ */
+export function ConnectionBanner({ state: status, delay = 3000, onRetry, offline = "You're offline. Showing what was saved; new notifications will arrive when you reconnect.", reconnecting = 'Reconnecting… changes you make are queued.' }: { state: Status; delay?: number; onRetry?: (() => void) | undefined; offline?: unknown; reconnecting?: unknown }) {
+  const now = derived(() => liveState(val<string | undefined>(status)))
+  const late = state(false)
+  const retry = untrack(() => onRetry)
+  onMount(() => {
+    let t: ReturnType<typeof setTimeout> | undefined
+    watch(() => now.value, next => {
+      clearTimeout(t)
+      if (next !== 'reconnecting') { late.value = false; return }
+      t = setTimeout(() => (late.value = true), untrack(() => delay))
+    })
+    onCleanup(() => clearTimeout(t))
+  })
+  return (
+    <>
+      {now.value === 'offline' && <Banner tone="critical" actions={retry ? () => <Button emphasis="outline" tone="neutral" size="sm" onClick={retry}>Retry now</Button> : undefined}>{offline}</Banner>}
+      {now.value === 'reconnecting' && late.value && <Banner tone="caution">{reconnecting}</Banner>}
+    </>
+  )
+}