@liberation-data/desk 0.1.0

package/src/react/setupProgress.ts

@@ -0,0 +1,113 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+/*
+ * Where someone got to in setup, kept so that closing the tab on step four does
+ * not send them back to step one, and so that a finished setup is not shown
+ * again. The toolkit does not decide where that lives: this browser by default,
+ * or the app's own server.
+ *
+ * Keep answers to what a person would mind retyping. Never a password or a key:
+ * the default store is this browser's local storage.
+ */
+
+export interface SetupRecord<Answers> {
+  readonly index: number
+  readonly answers: Answers
+  readonly finished: boolean
+}
+
+export interface SetupStore<Answers> {
+  /** What was saved, or undefined when nothing was. May be async, for a server. */
+  load(): SetupRecord<Answers> | undefined | Promise<SetupRecord<Answers> | undefined>
+  save(record: SetupRecord<Answers>): void | Promise<void>
+  clear(): void | Promise<void>
+}
+
+/** This browser's local storage. Quietly does nothing where storage is unavailable. */
+export function localSetupStore<Answers>(key: string): SetupStore<Answers> {
+  const name = `desk.setup.${key}`
+  return {
+    load() {
+      try {
+        const raw = globalThis.localStorage?.getItem(name)
+        return raw ? (JSON.parse(raw) as SetupRecord<Answers>) : undefined
+      } catch {
+        return undefined
+      }
+    },
+    save(record) {
+      try {
+        globalThis.localStorage?.setItem(name, JSON.stringify(record))
+      } catch {
+        // Private windows and full storage: setup still works, it just is not remembered.
+      }
+    },
+    clear() {
+      try {
+        globalThis.localStorage?.removeItem(name)
+      } catch {
+        // As above.
+      }
+    },
+  }
+}
+
+export interface SetupProgress<Answers> {
+  /** False until the store has answered; show nothing, or a quiet loading state, until then. */
+  readonly loaded: boolean
+  readonly index: number
+  readonly setIndex: (index: number) => void
+  readonly answers: Answers
+  /** Merges into the answers: `answer({ rider: 'Jasper Blues' })`. */
+  readonly answer: (patch: Partial<Answers>) => void
+  readonly finished: boolean
+  readonly finish: () => void
+  /** Forgets everything: "Set up again". */
+  readonly reset: () => void
+}
+
+export interface SetupProgressOptions<Answers> {
+  /** Names what is being set up, so two setups do not share a record. */
+  readonly key: string
+  readonly initial: Answers
+  /** Default: this browser's local storage. */
+  readonly store?: SetupStore<Answers>
+}
+
+export function useSetupProgress<Answers extends object>({ key, initial, store }: SetupProgressOptions<Answers>): SetupProgress<Answers> {
+  const storeRef = useRef(store ?? localSetupStore<Answers>(key))
+  const initialRef = useRef(initial)
+  const [record, setRecord] = useState<SetupRecord<Answers>>({ index: 0, answers: initial, finished: false })
+  const [loaded, setLoaded] = useState(false)
+
+  useEffect(() => {
+    let current = true
+    void Promise.resolve(storeRef.current.load()).then(saved => {
+      if (!current) return
+      // Answers added since the record was saved take their initial values.
+      if (saved) setRecord({ ...saved, answers: { ...initialRef.current, ...saved.answers } })
+      setLoaded(true)
+    })
+    return () => {
+      current = false
+    }
+  }, [])
+
+  const update = useCallback((change: (record: SetupRecord<Answers>) => SetupRecord<Answers>) => {
+    setRecord(previous => {
+      const next = change(previous)
+      void storeRef.current.save(next)
+      return next
+    })
+  }, [])
+
+  const setIndex = useCallback((index: number) => update(r => ({ ...r, index })), [update])
+  const answer = useCallback((patch: Partial<Answers>) => update(r => ({ ...r, answers: { ...r.answers, ...patch } })), [update])
+  const finish = useCallback(() => update(r => ({ ...r, finished: true })), [update])
+  const reset = useCallback(() => {
+    void storeRef.current.clear()
+    setRecord({ index: 0, answers: initialRef.current, finished: false })
+  }, [])
+
+  return { loaded, index: record.index, setIndex, answers: record.answers, answer, finished: record.finished, finish, reset }
+}

package/src/react/shell.tsx

@@ -0,0 +1,27 @@
+import { useState } from 'react'
+import type { ReactNode } from 'react'
+import { createDesk } from '../core/desk.js'
+import type { Desk } from '../core/desk.js'
+import type { Bus } from '../core/events.js'
+import type { DeskOptions } from '../core/types.js'
+import { DeskProvider } from './context.js'
+import { BusProvider } from './events.js'
+import { ToastProvider } from './overlays.js'
+
+export interface DeskShellProps {
+  /** An existing desk. One is made from `options` when this is left out. */
+  readonly desk?: Desk
+  readonly options?: DeskOptions
+  /** Share a bus across desks, or supply your own. A desk already carries one. */
+  readonly bus?: Bus
+  /** Leave toasts out when the app does not use them. Default true. */
+  readonly toasts?: boolean
+  readonly children: ReactNode
+}
+
+/** Everything an app needs around it, in one component: the desk, its bus, and toasts. */
+export function DeskShell({ desk, options, bus, toasts = true, children }: DeskShellProps) {
+  const [made] = useState(() => desk ?? createDesk(options))
+  const inner = toasts ? <ToastProvider>{children}</ToastProvider> : children
+  return <DeskProvider desk={made}>{bus ? <BusProvider bus={bus}>{inner}</BusProvider> : inner}</DeskProvider>
+}

package/src/react/sidebar.tsx

@@ -0,0 +1,84 @@
+import { useRef } from 'react'
+import type { KeyboardEvent, ReactNode } from 'react'
+
+/*
+ * A source list: the places inside a window. It is navigation, not a menu, so
+ * the chosen item is marked `aria-current` and stays chosen.
+ */
+
+export interface SidebarItem {
+  readonly id: string
+  readonly label: string
+  readonly icon?: ReactNode
+  readonly badge?: ReactNode
+  readonly disabled?: boolean
+}
+
+export interface SidebarSection {
+  readonly id: string
+  readonly label?: string
+  readonly items: readonly SidebarItem[]
+}
+
+export interface SidebarProps {
+  readonly sections: readonly SidebarSection[]
+  readonly value: string
+  readonly onChange: (id: string) => void
+  readonly label: string
+  readonly footer?: ReactNode
+  readonly className?: string
+}
+
+export function Sidebar({ sections, value, onChange, label, footer, className }: SidebarProps) {
+  const nav = useRef<HTMLElement>(null)
+  const items = sections.flatMap(section => section.items).filter(item => !item.disabled)
+
+  const onKeyDown = (event: KeyboardEvent<HTMLElement>) => {
+    const keys = { ArrowDown: 1, ArrowUp: -1 } as const
+    const delta = keys[event.key as keyof typeof keys]
+    if (!delta && event.key !== 'Home' && event.key !== 'End') return
+    event.preventDefault()
+    const at = items.findIndex(item => item.id === value)
+    const next =
+      event.key === 'Home' ? items[0]
+      : event.key === 'End' ? items.at(-1)
+      : items[(at + (delta ?? 1) + items.length) % items.length]
+    if (!next) return
+    onChange(next.id)
+    nav.current?.querySelector<HTMLButtonElement>(`[data-item="${CSS.escape(next.id)}"]`)?.focus()
+  }
+
+  return (
+    <nav ref={nav} className={['desk-sidebar', className].filter(Boolean).join(' ')} aria-label={label} onKeyDown={onKeyDown}>
+      {sections.map(section => (
+        <div key={section.id} className="desk-sidebar-section">
+          {section.label && <p className="desk-sidebar-heading">{section.label}</p>}
+          <ul>
+            {section.items.map(item => {
+              const current = item.id === value
+              return (
+                <li key={item.id}>
+                  <button
+                    type="button"
+                    data-item={item.id}
+                    className="desk-sidebar-item"
+                    aria-current={current ? 'page' : undefined}
+                    data-current={current || undefined}
+                    disabled={item.disabled}
+                    tabIndex={current ? 0 : -1}
+                    onClick={() => onChange(item.id)}
+                  >
+                    {item.icon && <span className="desk-sidebar-icon" aria-hidden="true">{item.icon}</span>}
+                    <span className="desk-sidebar-label">{item.label}</span>
+                    {item.badge != null && <span className="desk-sidebar-badge">{item.badge}</span>}
+                  </button>
+                </li>
+              )
+            })}
+          </ul>
+        </div>
+      ))}
+      {footer && <div className="desk-sidebar-footer">{footer}</div>}
+    </nav>
+  )
+}

package/src/react/table.tsx

@@ -0,0 +1,176 @@
+import { useRef } from 'react'
+import type { KeyboardEvent, ReactNode } from 'react'
+
+/*
+ * A table of rows people read, sort and choose from. It renders what it is
+ * given: no paging, no fetching, no opinion about where the rows came from.
+ */
+
+export interface Column<Row> {
+  readonly key: string
+  readonly header: ReactNode
+  /** Defaults to `row[key]` when the key names a field. */
+  readonly render?: (row: Row) => ReactNode
+  readonly align?: 'start' | 'end'
+  /** Figures line up and sort as numbers when this is set. */
+  readonly numeric?: boolean
+  readonly sortable?: boolean
+  readonly width?: string
+}
+
+export interface Sort {
+  readonly key: string
+  readonly direction: 'ascending' | 'descending'
+}
+
+export interface TableProps<Row> {
+  readonly rows: readonly Row[]
+  readonly columns: readonly Column<Row>[]
+  readonly rowId: (row: Row) => string
+  /** The accessible name, e.g. "Rides". */
+  readonly label: string
+  /** One id, or several when `selection` is `multiple`. */
+  readonly selected?: string | readonly string[] | null
+  /** Default `single`. `multiple` adds ⌘/Ctrl to add one and Shift for a run. */
+  readonly selection?: 'single' | 'multiple'
+  readonly onSelect?: (id: string, row: Row) => void
+  /** Called instead of `onSelect` when `selection` is `multiple`. */
+  readonly onSelectionChange?: (ids: string[]) => void
+  /** Enter, or a double click. */
+  readonly onActivate?: (id: string, row: Row) => void
+  readonly sort?: Sort | null
+  readonly onSortChange?: (sort: Sort) => void
+  readonly empty?: ReactNode
+  /** Extra props for each row — how a row becomes draggable. */
+  readonly rowProps?: (row: Row) => Record<string, unknown>
+}
+
+const cell = <Row,>(row: Row, column: Column<Row>): ReactNode =>
+  column.render ? column.render(row) : ((row as Record<string, unknown>)[column.key] as ReactNode)
+
+export function Table<Row>({
+  rows,
+  columns,
+  rowId,
+  label,
+  selected,
+  selection = 'single',
+  onSelect,
+  onSelectionChange,
+  onActivate,
+  sort,
+  onSortChange,
+  empty,
+  rowProps,
+}: TableProps<Row>) {
+  const body = useRef<HTMLTableSectionElement>(null)
+  const anchor = useRef<number>(0)
+  const chosen = selected == null ? [] : Array.isArray(selected) ? selected : [selected as string]
+  const isChosen = (id: string) => chosen.includes(id)
+
+  const choose = (index: number, modifiers: { readonly add?: boolean; readonly range?: boolean } = {}) => {
+    const row = rows[index]
+    if (!row) return
+    const id = rowId(row)
+    if (selection === 'multiple' && onSelectionChange) {
+      if (modifiers.range) {
+        const [from, to] = [Math.min(anchor.current, index), Math.max(anchor.current, index)]
+        onSelectionChange(rows.slice(from, to + 1).map(rowId))
+      } else if (modifiers.add) {
+        anchor.current = index
+        onSelectionChange(isChosen(id) ? chosen.filter(x => x !== id) : [...chosen, id])
+      } else {
+        anchor.current = index
+        onSelectionChange([id])
+      }
+      return
+    }
+    anchor.current = index
+    onSelect?.(id, row)
+  }
+
+  const focusRow = (index: number, modifiers: { readonly range?: boolean } = {}) => {
+    const clamped = Math.max(0, Math.min(index, rows.length - 1))
+    if (!rows[clamped]) return
+    choose(clamped, modifiers)
+    body.current?.querySelectorAll<HTMLElement>('tr')[clamped]?.focus()
+  }
+
+  const onKeyDown = (event: KeyboardEvent<HTMLTableSectionElement>) => {
+    const index = [...(body.current?.querySelectorAll('tr') ?? [])].indexOf(document.activeElement as HTMLTableRowElement)
+    if (index < 0) return
+    const row = rows[index]
+    switch (event.key) {
+      case 'ArrowDown': focusRow(index + 1, { range: event.shiftKey }); break
+      case 'ArrowUp': focusRow(index - 1, { range: event.shiftKey }); break
+      case 'Home': focusRow(0, { range: event.shiftKey }); break
+      case 'End': focusRow(rows.length - 1, { range: event.shiftKey }); break
+      case ' ': if (selection === 'multiple') choose(index, { add: true }); break
+      case 'Enter': if (row) onActivate?.(rowId(row), row); break
+      default: return
+    }
+    event.preventDefault()
+  }
+
+  const toggleSort = (column: Column<Row>) => {
+    if (!column.sortable || !onSortChange) return
+    const direction = sort?.key === column.key && sort.direction === 'ascending' ? 'descending' : 'ascending'
+    onSortChange({ key: column.key, direction })
+  }
+
+  if (!rows.length && empty) return <div className="desk-table-empty">{empty}</div>
+
+  return (
+    <div className="desk-table-wrap">
+      <table className="desk-table" aria-label={label} aria-multiselectable={selection === 'multiple' || undefined}>
+        <thead>
+          <tr>
+            {columns.map(column => (
+              <th
+                key={column.key}
+                scope="col"
+                style={column.width ? { width: column.width } : undefined}
+                data-align={column.align ?? (column.numeric ? 'end' : 'start')}
+                aria-sort={sort?.key === column.key ? sort.direction : column.sortable ? 'none' : undefined}
+              >
+                {column.sortable && onSortChange ? (
+                  <button type="button" className="desk-table-sort" onClick={() => toggleSort(column)}>
+                    {column.header}
+                    <span aria-hidden="true">{sort?.key === column.key ? (sort.direction === 'ascending' ? '↑' : '↓') : ''}</span>
+                  </button>
+                ) : (
+                  column.header
+                )}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody ref={body} onKeyDown={onKeyDown}>
+          {rows.map((row, index) => {
+            const id = rowId(row)
+            const isSelected = isChosen(id)
+            const selectable = Boolean(onSelect || onSelectionChange)
+            return (
+              <tr
+                key={id}
+                // One tab stop for the whole table; arrow keys move within it.
+                tabIndex={isSelected || (!chosen.length && index === 0) ? 0 : -1}
+                aria-selected={selectable ? isSelected : undefined}
+                data-selected={isSelected || undefined}
+                onClick={event => choose(index, { add: event.metaKey || event.ctrlKey, range: event.shiftKey })}
+                onDoubleClick={() => onActivate?.(id, row)}
+                {...rowProps?.(row)}
+              >
+                {columns.map(column => (
+                  <td key={column.key} data-align={column.align ?? (column.numeric ? 'end' : 'start')} data-numeric={column.numeric || undefined}>
+                    {cell(row, column)}
+                  </td>
+                ))}
+              </tr>
+            )
+          })}
+        </tbody>
+      </table>
+    </div>
+  )
+}

package/src/react/tasks.tsx

@@ -0,0 +1,176 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import { Button } from './controls.js'
+
+/*
+ * The jobs a setup does while the person watches: save the profile, import the
+ * rides, store the key. They run in order, each says how it is getting on,
+ * and one that fails stops the rest and says why — with a retry that picks up
+ * where it stopped, not from the top.
+ */
+
+export type TaskState = 'waiting' | 'working' | 'done' | 'failed'
+
+export interface Task {
+  readonly id: string
+  readonly name: ReactNode
+  /** The line under the name, until the task reports its own. */
+  readonly detail?: ReactNode
+  /** The work. `report` replaces the line under the name while it runs: "12 of 24". Throw to fail. */
+  readonly run: (report: (detail: ReactNode) => void) => unknown
+}
+
+export interface TaskProgress {
+  readonly id: string
+  readonly name: ReactNode
+  readonly state: TaskState
+  readonly detail?: ReactNode
+  /** Why it failed, for a person. */
+  readonly error?: string
+}
+
+export interface Tasks {
+  readonly items: readonly TaskProgress[]
+  readonly running: boolean
+  readonly done: boolean
+  readonly failed: boolean
+  /** Runs every task not yet done, in order. After a failure, this is the retry. */
+  readonly start: () => void
+  /** Forgets what ran and runs everything again: for a setup step entered a second time. */
+  readonly restart: () => void
+}
+
+interface Status {
+  readonly state: TaskState
+  readonly reported?: ReactNode
+  readonly error?: string
+}
+
+export function useTasks(tasks: readonly Task[]): Tasks {
+  // The latest tasks, so a task's `run` sees the answers given since the step was drawn.
+  const latest = useRef(tasks)
+  latest.current = tasks
+  const [status, setStatus] = useState<Readonly<Record<string, Status>>>({})
+  const statusNow = useRef(status)
+  statusNow.current = status
+  // A run that has been superseded — by a restart, or by leaving — stops touching state.
+  const generation = useRef(0)
+  const [running, setRunning] = useState(false)
+
+  useEffect(
+    () => () => {
+      generation.current += 1
+    },
+    [],
+  )
+
+  const run = useCallback(async (from: Readonly<Record<string, Status>>) => {
+    const mine = ++generation.current
+    const set = (id: string, next: Status) => {
+      if (generation.current !== mine) return
+      statusNow.current = { ...statusNow.current, [id]: next }
+      setStatus(statusNow.current)
+    }
+    setRunning(true)
+    for (const task of latest.current) {
+      if (from[task.id]?.state === 'done') continue
+      set(task.id, { state: 'working' })
+      try {
+        await task.run(detail => set(task.id, { state: 'working', reported: detail }))
+        set(task.id, { state: 'done', reported: statusNow.current[task.id]?.reported })
+      } catch (failure) {
+        set(task.id, { state: 'failed', error: failure instanceof Error ? failure.message : String(failure) })
+        break
+      }
+      if (generation.current !== mine) return
+    }
+    if (generation.current === mine) setRunning(false)
+  }, [])
+
+  const start = useCallback(() => {
+    if (running) return
+    void run(statusNow.current)
+  }, [run, running])
+
+  const restart = useCallback(() => {
+    statusNow.current = {}
+    setStatus({})
+    void run({})
+  }, [run])
+
+  const items = tasks.map((task): TaskProgress => {
+    const s = status[task.id]
+    const detail = s?.reported ?? task.detail
+    return {
+      id: task.id,
+      name: task.name,
+      state: s?.state ?? 'waiting',
+      ...(detail === undefined ? {} : { detail }),
+      ...(s?.error === undefined ? {} : { error: s.error }),
+    }
+  })
+
+  return {
+    items,
+    running,
+    done: items.length > 0 && items.every(item => item.state === 'done'),
+    failed: items.some(item => item.state === 'failed'),
+    start,
+    restart,
+  }
+}
+
+export interface ChecklistProps {
+  readonly items: readonly TaskProgress[]
+  /** Offered beside a failed task. */
+  readonly onRetry?: () => void
+  /** A bar above the list, filling as tasks finish. Default true. */
+  readonly progress?: boolean
+  readonly label?: string
+  readonly className?: string
+}
+
+/** Tasks as a person watches them: waiting, working, done, or failed with the reason. */
+export function Checklist({ items, onRetry, progress = true, label = 'Progress', className }: ChecklistProps) {
+  const done = items.filter(item => item.state === 'done').length
+  return (
+    <div className={['desk-checklist', className].filter(Boolean).join(' ')}>
+      {progress && (
+        <div
+          className="desk-progress"
+          role="progressbar"
+          aria-label={label}
+          aria-valuemin={0}
+          aria-valuemax={items.length}
+          aria-valuenow={done}
+        >
+          <i style={{ width: `${items.length ? (done / items.length) * 100 : 0}%` }} />
+        </div>
+      )}
+      <ul className="desk-tasks" aria-label={label}>
+        {items.map(item => (
+          <li key={item.id} className="desk-task" data-state={item.state}>
+            <span className="desk-task-mark" aria-hidden="true">
+              {item.state === 'done' ? '✓' : item.state === 'failed' ? '!' : ''}
+            </span>
+            <span className="desk-task-text">
+              <span className="desk-task-name">{item.name}</span>
+              {item.state === 'failed' ? (
+                <span className="desk-task-error" role="alert">
+                  {item.error}
+                </span>
+              ) : (
+                item.detail !== undefined && <span className="desk-task-detail">{item.detail}</span>
+              )}
+            </span>
+            {item.state === 'failed' && onRetry && (
+              <Button size="small" onClick={onRetry}>
+                Try again
+              </Button>
+            )}
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}