@liberation-data/desk 0.1.0

package/src/react/tour.tsx

@@ -0,0 +1,183 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import type { DeskEvent } from '../core/events.js'
+import type { WindowId } from '../core/types.js'
+import { Button } from './controls.js'
+import { useDesk } from './context.js'
+import { useBus } from './events.js'
+
+/*
+ * A tour drives the desk: it opens the window each step is about and points at
+ * the control it is talking about, so the person watches the real app work
+ * rather than reading about it. A step can hand over — "your turn" — and wait.
+ *
+ * The bar holds no content of its own: the steps are the app's.
+ */
+
+export interface TourStep {
+  /** Opened and made key before the step is shown. */
+  readonly window?: WindowId
+  /** What to point at: a `data-tour` name, or any CSS selector. */
+  readonly point?: string
+  readonly caption: ReactNode
+  /** Hands over: the bar offers Done and Skip instead of Next. */
+  readonly yourTurn?: boolean
+  /**
+   * The event that means the person has done it — `ride.selected`, or a topic and a test.
+   * The tour moves on by itself when it arrives, so nobody has to say Done.
+   */
+  readonly until?: string | { readonly topic: string; readonly when: (event: DeskEvent) => boolean }
+}
+
+export interface Tour {
+  readonly id: string
+  readonly name: string
+  /** What the tour shows, in a sentence: said when it is offered. */
+  readonly description?: ReactNode
+  readonly steps: readonly TourStep[]
+}
+
+export interface TourBarProps {
+  readonly tour: Tour
+  /** Called when the last step is finished. */
+  readonly onFinish?: () => void
+  /** Called when the person stops early. */
+  readonly onStop?: () => void
+  /**
+   * Ask first: the bar invites the person to take the tour, and starts only if they say so.
+   * For the first time someone reaches the desktop, where nobody should be dropped without a word.
+   */
+  readonly offer?: boolean
+  readonly className?: string
+}
+
+const POINTED = 'data-desk-tour-pointed'
+
+function point(step: TourStep | undefined): () => void {
+  if (!step?.point) return () => {}
+  const selector = step.point.startsWith('[') || step.point.includes('.') || step.point.includes('#') ? step.point : `[data-tour="${step.point}"]`
+  const element = document.querySelector<HTMLElement>(selector)
+  if (!element) return () => {}
+  element.setAttribute(POINTED, '')
+  element.scrollIntoView({ block: 'nearest', behavior: 'smooth' })
+  return () => element.removeAttribute(POINTED)
+}
+
+export function TourBar({ tour, onFinish, onStop, offer, className }: TourBarProps) {
+  const desk = useDesk()
+  const bus = useBus()
+  const [offered, setOffered] = useState(offer ?? false)
+  const [index, setIndex] = useState(0)
+  const step = offered ? undefined : tour.steps[index]
+  const total = tour.steps.length
+  const stop = useRef<() => void>(() => {})
+
+  // Enter the step: open the window it is about, then point at its control.
+  useEffect(() => {
+    if (!step) return
+    if (step.window) desk.open(step.window)
+    stop.current()
+    // A frame later: the window it just opened has to exist before it can be pointed at.
+    const frame = requestAnimationFrame(() => {
+      stop.current = point(step)
+    })
+    return () => {
+      cancelAnimationFrame(frame)
+      stop.current()
+      stop.current = () => {}
+    }
+  }, [desk, step, index])
+
+  const go = useCallback(
+    (to: number) => {
+      if (to >= total) {
+        onFinish?.()
+        return
+      }
+      setIndex(Math.max(0, to))
+    },
+    [total, onFinish],
+  )
+
+  // A step that waits for the person moves on when what it asked for happens.
+  const until = step?.until
+  useEffect(() => {
+    if (!until) return undefined
+    const topic = typeof until === 'string' ? until : until.topic
+    return bus.subscribe(topic, event => {
+      if (typeof until === 'string' || until.when(event)) go(index + 1)
+    })
+  }, [bus, until, go, index])
+
+  if (offered) {
+    return (
+      <div className={['desk-tour', className].filter(Boolean).join(' ')} role="region" aria-label={`Tour: ${tour.name}`}>
+        <div className="desk-tour-head">
+          <b>{tour.name}</b>
+          <span className="desk-tour-count">{total} steps</span>
+        </div>
+        {tour.description && <p className="desk-tour-caption">{tour.description}</p>}
+        <div className="desk-tour-actions">
+          <span className="desk-tour-spacer" />
+          <Button size="small" onClick={() => onStop?.()}>
+            Not now
+          </Button>
+          <Button size="small" intent="default" onClick={() => setOffered(false)}>
+            Show me
+          </Button>
+        </div>
+      </div>
+    )
+  }
+
+  if (!step) return null
+
+  return (
+    <div className={['desk-tour', className].filter(Boolean).join(' ')} role="region" aria-label={`Tour: ${tour.name}`}>
+      <div className="desk-tour-head">
+        <b>{tour.name}</b>
+        <span className="desk-tour-count">
+          Step {index + 1} of {total}
+        </span>
+        <Button size="small" intent="quiet" aria-label="Stop the tour" onClick={() => onStop?.()}>
+          ✕
+        </Button>
+      </div>
+      <div className="desk-tour-progress" role="presentation">
+        <i style={{ width: `${((index + 1) / total) * 100}%` }} />
+      </div>
+      <p className="desk-tour-caption" data-your-turn={step.yourTurn || undefined}>
+        {step.yourTurn && <span className="desk-tour-turn">Your turn</span>}
+        {step.caption}
+      </p>
+      <div className="desk-tour-actions">
+        <Button size="small" intent="quiet" onClick={() => setIndex(0)}>
+          Restart
+        </Button>
+        <Button size="small" intent="quiet" onClick={() => setIndex(index)}>
+          Show me again
+        </Button>
+        <span className="desk-tour-spacer" />
+        {step.yourTurn ? (
+          <>
+            <Button size="small" onClick={() => go(index + 1)}>Skip</Button>
+            {!step.until && (
+              <Button size="small" intent="default" onClick={() => go(index + 1)}>
+                Done
+              </Button>
+            )}
+          </>
+        ) : (
+          <>
+            <Button size="small" disabled={index === 0} onClick={() => go(index - 1)}>
+              ‹ Back
+            </Button>
+            <Button size="small" intent="default" onClick={() => go(index + 1)}>
+              {index === total - 1 ? 'Finish' : 'Next ›'}
+            </Button>
+          </>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/react/windowBoundary.tsx

@@ -0,0 +1,110 @@
+import { Component, createContext, lazy, Suspense, useContext } from 'react'
+import type { ComponentType, ErrorInfo, LazyExoticComponent, ReactNode } from 'react'
+import type { WindowId } from '../core/types.js'
+import { Button } from './controls.js'
+
+/*
+ * Each window loads, and fails, on its own. One window fetching its code shows a
+ * loading state in that window and nowhere else; one window throwing shows what
+ * went wrong in that window, with a way to try again, while the rest of the desk
+ * carries on.
+ */
+
+export type WindowLoading = (id: WindowId) => ReactNode
+export type WindowFailed = (id: WindowId, error: Error, reload: () => void) => ReactNode
+
+/** How many times this window has been reloaded: a lazy window loads afresh for each. */
+const AttemptContext = createContext(0)
+
+const defaultLoading: WindowLoading = () => (
+  <div className="desk-window-status" role="status">
+    Loading…
+  </div>
+)
+
+const defaultFailed: WindowFailed = (_id, error, reload) => (
+  <div className="desk-window-status" role="alert">
+    <b>This window could not open</b>
+    <span className="desk-window-status-detail">{error.message}</span>
+    <Button size="small" onClick={reload}>
+      Reload
+    </Button>
+  </div>
+)
+
+interface BoundaryProps {
+  readonly id: WindowId
+  readonly failed: WindowFailed | undefined
+  readonly children: ReactNode
+}
+
+interface BoundaryState {
+  readonly error: Error | null
+  readonly attempt: number
+}
+
+class WindowErrorBoundary extends Component<BoundaryProps, BoundaryState> {
+  override state: BoundaryState = { error: null, attempt: 0 }
+
+  static getDerivedStateFromError(error: unknown): Partial<BoundaryState> {
+    return { error: error instanceof Error ? error : new Error(String(error)) }
+  }
+
+  override componentDidCatch(error: Error, info: ErrorInfo) {
+    // Still reported: a window that cannot open is a bug somebody should hear about.
+    console.error(`desk: window "${this.props.id}" could not open`, error, info.componentStack)
+  }
+
+  private readonly reload = () => this.setState(state => ({ error: null, attempt: state.attempt + 1 }))
+
+  override render() {
+    const { error, attempt } = this.state
+    if (error) return (this.props.failed ?? defaultFailed)(this.props.id, error, this.reload)
+    // A fresh key remounts the content, so a reload really starts again.
+    return (
+      <AttemptContext.Provider value={attempt} key={attempt}>
+        {this.props.children}
+      </AttemptContext.Provider>
+    )
+  }
+}
+
+export function WindowBoundary({
+  id,
+  loading,
+  failed,
+  children,
+}: {
+  readonly id: WindowId
+  readonly loading: WindowLoading | undefined
+  readonly failed: WindowFailed | undefined
+  readonly children: ReactNode
+}) {
+  return (
+    <WindowErrorBoundary id={id} failed={failed}>
+      <Suspense fallback={(loading ?? defaultLoading)(id)}>{children}</Suspense>
+    </WindowErrorBoundary>
+  )
+}
+
+/**
+ * A window whose code loads when it is first opened.
+ *
+ *   const RoutePlanner = lazyWindow(() => import('./apps/RoutePlanner'))
+ *
+ * Unlike `React.lazy`, a load that fails is not remembered: Reload in the window
+ * tries the import again, so a dropped connection is not permanent.
+ */
+export function lazyWindow<P extends object>(load: () => Promise<{ default: ComponentType<P> }>): ComponentType<P> {
+  const byAttempt = new Map<number, LazyExoticComponent<ComponentType<P>>>()
+  function LazyWindow(props: P) {
+    const attempt = useContext(AttemptContext)
+    let Loaded = byAttempt.get(attempt)
+    if (!Loaded) {
+      Loaded = lazy(load)
+      byAttempt.set(attempt, Loaded)
+    }
+    return <Loaded {...props} />
+  }
+  return LazyWindow
+}

package/src/react/wizard.tsx

@@ -0,0 +1,150 @@
+import { useEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import { Button } from './controls.js'
+
+/*
+ * A setup assistant: one pane, one question at a time, Back and Continue where
+ * the eye already is. It owns which step is showing and whether Continue is
+ * allowed; the steps themselves are the app's.
+ *
+ * A step cannot be skipped past by clicking a dot: the dots show where you are
+ * and let you go back over what you have already answered, nothing more.
+ */
+
+export interface WizardStep {
+  readonly id: string
+  /** Named in the progress row, and announced as the step changes. */
+  readonly name: string
+  readonly title: ReactNode
+  readonly description?: ReactNode
+  readonly body?: ReactNode
+  /** Above the title. */
+  readonly glyph?: ReactNode
+  /** Continue is offered only when this is true. Default: always. */
+  readonly complete?: boolean
+  /** Replaces Continue's label on this step. */
+  readonly continueLabel?: string
+  /** A quiet way past this step: "Set up later". */
+  readonly skip?: { readonly label: string; readonly onSkip: () => void }
+  /** Nothing to do but wait: no Back, and Continue waits for `complete`. */
+  readonly working?: boolean
+  readonly onEnter?: () => void
+  /**
+   * Work Continue does before moving on: create the account, check the key, download the maps.
+   * While it runs, Continue says so and nothing can be pressed twice. Throw to stay on the step
+   * and show why, in the step; return `false` to stay without a message.
+   */
+  readonly onContinue?: () => unknown
+  /** Continue's label while `onContinue` runs. Default: "Working…". */
+  readonly busyLabel?: string
+}
+
+export interface WizardProps {
+  readonly steps: readonly WizardStep[]
+  readonly index: number
+  readonly onIndexChange: (index: number) => void
+  readonly onFinish: () => void
+  readonly label?: string
+  readonly className?: string
+}
+
+export function Wizard({ steps, index, onIndexChange, onFinish, label = 'Setup', className }: WizardProps) {
+  const step = steps[index]
+  const [direction, setDirection] = useState<'forward' | 'back'>('forward')
+  const previous = useRef(index)
+  const heading = useRef<HTMLHeadingElement>(null)
+  const entered = useRef<(() => void) | undefined>(undefined)
+  entered.current = step?.onEnter
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  // The step a running `onContinue` belongs to: if the person has gone back meanwhile, its result is stale.
+  const running = useRef<number | null>(null)
+
+  // Only when the step changes: a step whose body has a field re-renders on every
+  // keystroke, and moving focus to the heading then would eat what was being typed.
+  useEffect(() => {
+    setDirection(index >= previous.current ? 'forward' : 'back')
+    setBusy(false)
+    setError(null)
+    running.current = null
+    previous.current = index
+    entered.current?.()
+    // Focus the new step's heading, so a screen reader announces it and the
+    // keyboard starts at the top of the pane rather than back at the buttons.
+    heading.current?.focus()
+  }, [index])
+
+  if (!step) return null
+
+  const last = index === steps.length - 1
+  const canContinue = step.complete ?? true
+  const go = (to: number) => (to >= steps.length ? onFinish() : onIndexChange(Math.max(0, to)))
+
+  const next = async () => {
+    if (!step.onContinue) return go(index + 1)
+    if (running.current !== null) return
+    running.current = index
+    setBusy(true)
+    setError(null)
+    try {
+      const result = await step.onContinue()
+      if (running.current !== index) return
+      running.current = null
+      setBusy(false)
+      if (result !== false) go(index + 1)
+    } catch (failure) {
+      if (running.current !== index) return
+      running.current = null
+      setBusy(false)
+      setError(failure instanceof Error ? failure.message : String(failure))
+    }
+  }
+
+  return (
+    <section className={['desk-wizard', className].filter(Boolean).join(' ')} aria-label={label}>
+      <div className="desk-wizard-content" data-direction={direction} key={step.id}>
+        {step.glyph && <div className="desk-wizard-glyph" aria-hidden="true">{step.glyph}</div>}
+        <h1 ref={heading} tabIndex={-1} className="desk-wizard-title">{step.title}</h1>
+        {step.description && <p className="desk-wizard-description">{step.description}</p>}
+        {step.body}
+        {error && (
+          <p className="desk-wizard-error" role="alert">
+            {error}
+          </p>
+        )}
+      </div>
+      <footer className="desk-wizard-foot">
+        <ol className="desk-wizard-steps" aria-label="Progress">
+          {steps.map((other, i) => (
+            <li
+              key={other.id}
+              className="desk-wizard-dot"
+              data-state={i === index ? 'now' : i < index ? 'done' : 'ahead'}
+              aria-current={i === index ? 'step' : undefined}
+            >
+              <span className="desk-wizard-dot-name">{other.name}</span>
+            </li>
+          ))}
+        </ol>
+        <span className="desk-wizard-step-name" aria-live="polite">
+          {step.name}
+        </span>
+        <div className="desk-wizard-actions">
+          {step.skip && (
+            <Button intent="quiet" disabled={busy} onClick={step.skip.onSkip}>
+              {step.skip.label}
+            </Button>
+          )}
+          {index > 0 && !step.working && (
+            <Button disabled={busy} onClick={() => go(index - 1)}>
+              Back
+            </Button>
+          )}
+          <Button intent="default" disabled={!canContinue || busy} aria-busy={busy || undefined} onClick={() => void next()}>
+            {busy ? (step.busyLabel ?? 'Working…') : (step.continueLabel ?? (last ? 'Done' : 'Continue'))}
+          </Button>
+        </div>
+      </footer>
+    </section>
+  )
+}