@liberation-data/desk 0.1.0

package/src/react/context.tsx

@@ -0,0 +1,55 @@
+import { createContext, useContext, useState, useSyncExternalStore } from 'react'
+import type { ReactNode, RefObject } from 'react'
+import { createBus } from '../core/events.js'
+import type { Bus } from '../core/events.js'
+import { createDesk } from '../core/desk.js'
+import { DragProvider } from './dragContext.js'
+import type { Desk } from '../core/desk.js'
+import type { DeskOptions, DeskState, WindowId } from '../core/types.js'
+
+const DeskContext = createContext<Desk | null>(null)
+
+/** Every desk comes with a bus; <BusProvider> only matters when one has to be shared or supplied. */
+export const BusContext = createContext<Bus | null>(null)
+
+export interface DeskProviderProps {
+  /** An existing desk, e.g. one a tour runner or router also drives. */
+  readonly desk?: Desk
+  /** Used to create a desk when none is given. Read once. */
+  readonly options?: DeskOptions
+  readonly children: ReactNode
+}
+
+export function DeskProvider({ desk, options, children }: DeskProviderProps) {
+  const [value] = useState(() => desk ?? createDesk(options))
+  const [bus] = useState(createBus)
+  return (
+    <DeskContext.Provider value={value}>
+      <BusContext.Provider value={bus}>
+        <DragProvider>{children}</DragProvider>
+      </BusContext.Provider>
+    </DeskContext.Provider>
+  )
+}
+
+export function useDesk(): Desk {
+  const desk = useContext(DeskContext)
+  if (!desk) throw new Error('useDesk must be used inside a <DeskProvider>')
+  return desk
+}
+
+export function useDeskState(): DeskState {
+  const desk = useDesk()
+  return useSyncExternalStore(desk.subscribe, desk.getState, desk.getState)
+}
+
+export interface WindowContextValue {
+  readonly id: WindowId
+  readonly element: RefObject<HTMLElement | null>
+}
+
+/** Present inside a window's content: which window this is, and its element. */
+export const WindowContext = createContext<WindowContextValue | null>(null)
+
+/** The id of the window this component is rendered in, or null outside any window. */
+export const useWindowId = (): WindowId | null => useContext(WindowContext)?.id ?? null

package/src/react/controls.tsx

@@ -0,0 +1,364 @@
+import { forwardRef, useEffect, useId, useRef } from 'react'
+import type { ButtonHTMLAttributes, InputHTMLAttributes, KeyboardEvent, ReactNode } from 'react'
+
+/*
+ * Controls carry their own behaviour and accessibility; their look comes only
+ * from tokens. They take few style props on purpose — consistency comes from
+ * not being able to deviate. See HIG.md §6.
+ */
+
+export type ButtonIntent = 'normal' | 'default' | 'quiet' | 'destructive'
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** `default` is the one action a view leads with, and the one Return performs. One per view. */
+  readonly intent?: ButtonIntent
+  readonly size?: 'regular' | 'small'
+  /** Before the label. Decorative: an icon-only button still needs `aria-label`. */
+  readonly icon?: ReactNode
+}
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  { intent = 'normal', size = 'regular', icon, children, type = 'button', className, ...rest },
+  ref,
+) {
+  return (
+    <button
+      ref={ref}
+      type={type}
+      className={['desk-button', className].filter(Boolean).join(' ')}
+      data-intent={intent}
+      data-size={size}
+      data-icon-only={!children || undefined}
+      {...rest}
+    >
+      {icon && <span className="desk-button-icon" aria-hidden="true">{icon}</span>}
+      {children}
+    </button>
+  )
+})
+
+export interface SegmentedOption<T extends string> {
+  readonly value: T
+  readonly label: string
+  readonly icon?: ReactNode
+  readonly disabled?: boolean
+}
+
+export interface SegmentedControlProps<T extends string> {
+  /** Two to five options, all worth seeing at once. More than that wants a pop-up menu. */
+  readonly options: readonly SegmentedOption<T>[]
+  readonly value: T
+  readonly onChange: (value: T) => void
+  /** The accessible name for the group, e.g. "Filter rides by bike". */
+  readonly label: string
+  readonly size?: 'regular' | 'small'
+  readonly disabled?: boolean
+}
+
+export function SegmentedControl<T extends string>({ options, value, onChange, label, size = 'regular', disabled }: SegmentedControlProps<T>) {
+  const group = useRef<HTMLDivElement>(null)
+
+  const move = (event: KeyboardEvent<HTMLDivElement>) => {
+    const keys = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 } as const
+    const delta = keys[event.key as keyof typeof keys]
+    const usable = options.filter(o => !o.disabled)
+    if (!delta || !usable.length) return
+    event.preventDefault()
+    const at = usable.findIndex(o => o.value === value)
+    const next = usable[(at + delta + usable.length) % usable.length]
+    if (!next) return
+    onChange(next.value)
+    // Selection follows focus here, as it does in a segmented control on any platform.
+    group.current?.querySelector<HTMLButtonElement>(`[data-value="${CSS.escape(next.value)}"]`)?.focus()
+  }
+
+  return (
+    <div ref={group} role="radiogroup" aria-label={label} className="desk-segmented" data-size={size} onKeyDown={move}>
+      {options.map(option => {
+        const selected = option.value === value
+        return (
+          <button
+            key={option.value}
+            type="button"
+            role="radio"
+            aria-checked={selected}
+            data-value={option.value}
+            className="desk-segment"
+            tabIndex={selected ? 0 : -1}
+            disabled={disabled || option.disabled}
+            onClick={() => onChange(option.value)}
+          >
+            {option.icon && <span className="desk-segment-icon" aria-hidden="true">{option.icon}</span>}
+            {option.label}
+          </button>
+        )
+      })}
+    </div>
+  )
+}
+
+export interface ToggleProps {
+  readonly checked: boolean
+  readonly onChange: (checked: boolean) => void
+  /** Shown beside the switch. Use `label` alone, or `aria-label` when the context already names it. */
+  readonly label?: ReactNode
+  readonly description?: ReactNode
+  readonly disabled?: boolean
+  readonly 'aria-label'?: string
+}
+
+/** For a setting that takes effect immediately. One that waits for Save is a checkbox. */
+export function Toggle({ checked, onChange, label, description, disabled, 'aria-label': ariaLabel }: ToggleProps) {
+  const id = useId()
+  const descriptionId = description ? `${id}-description` : undefined
+  const control = (
+    <button
+      type="button"
+      role="switch"
+      id={id}
+      aria-checked={checked}
+      aria-label={ariaLabel}
+      aria-describedby={descriptionId}
+      className="desk-toggle"
+      disabled={disabled}
+      onClick={() => onChange(!checked)}
+    >
+      <span className="desk-toggle-knob" aria-hidden="true" />
+    </button>
+  )
+  if (!label && !description) return control
+  return (
+    <div className="desk-toggle-row">
+      <span className="desk-toggle-text">
+        {label && <label htmlFor={id} className="desk-label">{label}</label>}
+        {description && <span id={descriptionId} className="desk-help">{description}</span>}
+      </span>
+      {control}
+    </div>
+  )
+}
+
+export interface CheckboxProps {
+  readonly checked: boolean
+  /** Some of the things this stands for are checked, and some are not. */
+  readonly indeterminate?: boolean
+  readonly onChange: (checked: boolean) => void
+  readonly label?: ReactNode
+  readonly description?: ReactNode
+  readonly disabled?: boolean
+  readonly 'aria-label'?: string
+}
+
+/** For a setting that waits for Save. One that applies at once is a Toggle. */
+export function Checkbox({ checked, indeterminate, onChange, label, description, disabled, 'aria-label': ariaLabel }: CheckboxProps) {
+  const id = useId()
+  const descriptionId = description ? `${id}-description` : undefined
+  const box = useRef<HTMLInputElement>(null)
+  // Indeterminate is a property, not an attribute: it cannot be set in markup.
+  useEffect(() => {
+    if (box.current) box.current.indeterminate = indeterminate ?? false
+  }, [indeterminate])
+
+  const input = (
+    <input
+      ref={box}
+      id={id}
+      type="checkbox"
+      className="desk-checkbox"
+      checked={checked}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      aria-describedby={descriptionId}
+      onChange={event => onChange(event.target.checked)}
+    />
+  )
+  if (!label && !description) return input
+  return (
+    <div className="desk-check-row">
+      {input}
+      <span className="desk-check-text">
+        {label && <label htmlFor={id} className="desk-check-label">{label}</label>}
+        {description && <span id={descriptionId} className="desk-help">{description}</span>}
+      </span>
+    </div>
+  )
+}
+
+export interface RadioOption<T extends string> {
+  readonly value: T
+  readonly label: string
+  readonly description?: string
+  readonly disabled?: boolean
+}
+
+export interface RadioGroupProps<T extends string> {
+  readonly options: readonly RadioOption<T>[]
+  readonly value: T | null
+  readonly onChange: (value: T) => void
+  readonly label: string
+  readonly labelHidden?: boolean
+  readonly disabled?: boolean
+}
+
+/** Mutually exclusive choices that each need a line of explanation. */
+export function RadioGroup<T extends string>({ options, value, onChange, label, labelHidden, disabled }: RadioGroupProps<T>) {
+  const name = useId()
+  return (
+    <fieldset className="desk-radiogroup" disabled={disabled}>
+      <legend className="desk-label" data-hidden={labelHidden || undefined}>{label}</legend>
+      {options.map(option => {
+        const id = `${name}-${option.value}`
+        return (
+          <div className="desk-check-row" key={option.value}>
+            <input
+              id={id}
+              type="radio"
+              name={name}
+              className="desk-radio"
+              value={option.value}
+              checked={option.value === value}
+              disabled={option.disabled}
+              aria-describedby={option.description ? `${id}-description` : undefined}
+              onChange={() => onChange(option.value)}
+            />
+            <span className="desk-check-text">
+              <label htmlFor={id} className="desk-check-label">{option.label}</label>
+              {option.description && <span id={`${id}-description`} className="desk-help">{option.description}</span>}
+            </span>
+          </div>
+        )
+      })}
+    </fieldset>
+  )
+}
+
+export interface ChoiceOption<T extends string> {
+  readonly value: T
+  readonly label: string
+  readonly description?: ReactNode
+  /** Decorative, beside the label. */
+  readonly icon?: ReactNode
+  /** A short aside after the label: a size, "needs a key". */
+  readonly tag?: ReactNode
+  readonly disabled?: boolean
+}
+
+export interface ChoiceGroupProps<T extends string> {
+  readonly options: readonly ChoiceOption<T>[]
+  readonly value: T | null
+  readonly onChange: (value: T) => void
+  readonly label: string
+  readonly labelHidden?: boolean
+}
+
+/**
+ * The few choices a setup step turns on, as cards: bigger than a radio, smaller than a page.
+ * Native radios underneath, so the group is one tab stop and the arrow keys move the choice.
+ */
+export function ChoiceGroup<T extends string>({ options, value, onChange, label, labelHidden }: ChoiceGroupProps<T>) {
+  const name = useId()
+  return (
+    <fieldset className="desk-choices">
+      <legend className="desk-label" data-hidden={labelHidden || undefined}>{label}</legend>
+      {options.map(option => {
+        const id = `${name}-${option.value}`
+        const chosen = option.value === value
+        return (
+          <label key={option.value} htmlFor={id} className="desk-choice" data-chosen={chosen || undefined} data-disabled={option.disabled || undefined}>
+            <input
+              id={id}
+              type="radio"
+              name={name}
+              className="desk-choice-input"
+              value={option.value}
+              checked={chosen}
+              disabled={option.disabled}
+              aria-describedby={option.description ? `${id}-description` : undefined}
+              onChange={() => onChange(option.value)}
+            />
+            <span className="desk-choice-mark" aria-hidden="true" />
+            {option.icon && <span className="desk-choice-icon" aria-hidden="true">{option.icon}</span>}
+            <span className="desk-choice-text">
+              <span className="desk-choice-label">{option.label}{option.tag && <span className="desk-choice-tag">{option.tag}</span>}</span>
+              {option.description && <span id={`${id}-description`} className="desk-help">{option.description}</span>}
+            </span>
+          </label>
+        )
+      })}
+    </fieldset>
+  )
+}
+
+export interface SliderProps {
+  readonly value: number
+  readonly onChange: (value: number) => void
+  readonly label: string
+  readonly min?: number
+  readonly max?: number
+  readonly step?: number
+  readonly disabled?: boolean
+  /** How the value reads to a person: `v => \`${v} psi\``. Shown beside the label and announced. */
+  readonly format?: (value: number) => string
+}
+
+export function Slider({ value, onChange, label, min = 0, max = 100, step = 1, disabled, format }: SliderProps) {
+  const id = useId()
+  const shown = format ? format(value) : String(value)
+  return (
+    <div className="desk-slider">
+      <div className="desk-slider-head">
+        <label htmlFor={id} className="desk-label">{label}</label>
+        <output htmlFor={id} className="desk-slider-value">{shown}</output>
+      </div>
+      <input
+        id={id}
+        type="range"
+        className="desk-slider-track"
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        disabled={disabled}
+        aria-valuetext={format ? shown : undefined}
+        onChange={event => onChange(Number(event.target.value))}
+      />
+    </div>
+  )
+}
+
+export interface TextFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'className' | 'id'> {
+  /** Every field has a label. A placeholder is an example, never the label. */
+  readonly label: string
+  /** Keep the label for assistive technology, hide it on screen — for a search field in a toolbar. */
+  readonly labelHidden?: boolean
+  readonly help?: ReactNode
+  /** What went wrong and how to fix it. Its presence marks the field invalid. */
+  readonly error?: ReactNode
+}
+
+export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(function TextField(
+  { label, labelHidden, help, error, type = 'text', ...rest },
+  ref,
+) {
+  const id = useId()
+  const helpId = help ? `${id}-help` : undefined
+  const errorId = error ? `${id}-error` : undefined
+  return (
+    <div className="desk-field" data-invalid={error ? true : undefined}>
+      <label htmlFor={id} className="desk-label" data-hidden={labelHidden || undefined}>
+        {label}
+      </label>
+      <input
+        ref={ref}
+        id={id}
+        type={type}
+        className="desk-input"
+        aria-invalid={error ? true : undefined}
+        aria-describedby={[errorId, helpId].filter(Boolean).join(' ') || undefined}
+        {...rest}
+      />
+      {error && <span id={errorId} className="desk-error">{error}</span>}
+      {help && !error && <span id={helpId} className="desk-help">{help}</span>}
+    </div>
+  )
+})

package/src/react/conversation.tsx

@@ -0,0 +1,208 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import type { KeyboardEvent, ReactNode } from 'react'
+import { Button } from './controls.js'
+
+/*
+ * A conversation: the thread, and the box you type into. Presentational only —
+ * it holds no transport and knows nothing about who is answering. Messages come
+ * in as props; sending, streaming and retrying are the app's to do.
+ */
+
+export interface Message {
+  readonly id: string
+  /** Matches `me` on the thread for your own messages. Anything else is somebody else. */
+  readonly from: string
+  /** Shown above the first message of a run. Falls back to `from`. */
+  readonly authorName?: string
+  readonly body: ReactNode
+  readonly at?: Date | string
+  /** `sending` dims it, `failed` offers Retry. */
+  readonly state?: 'sending' | 'sent' | 'failed'
+}
+
+export interface ThreadProps {
+  readonly messages: readonly Message[]
+  /** Which `from` is you. Default `me`. */
+  readonly me?: string
+  /** Shown while the other side is composing: `true` for dots, or your own node. */
+  readonly typing?: boolean | ReactNode
+  readonly onRetry?: (id: string) => void
+  readonly empty?: ReactNode
+  readonly label?: string
+  readonly className?: string
+}
+
+const time = (at: Date | string | undefined) =>
+  at === undefined ? null
+  : typeof at === 'string' ? at
+  : at.toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' })
+
+export function Thread({ messages, me = 'me', typing, onRetry, empty, label = 'Conversation', className }: ThreadProps) {
+  const scroller = useRef<HTMLDivElement>(null)
+  const atBottom = useRef(true)
+  const [missed, setMissed] = useState(0)
+
+  const toBottom = useCallback((behavior: ScrollBehavior = 'auto') => {
+    const element = scroller.current
+    if (!element) return
+    element.scrollTo({ top: element.scrollHeight, behavior })
+    atBottom.current = true
+    setMissed(0)
+  }, [])
+
+  // Follow the conversation only while the reader is at the end of it: scrolling
+  // back to read something must not be yanked away by the next message.
+  useLayoutEffect(() => {
+    if (atBottom.current) toBottom()
+    else setMissed(n => n + 1)
+  }, [messages.length, toBottom])
+
+  useEffect(() => {
+    toBottom()
+  }, [toBottom])
+
+  const onScroll = () => {
+    const element = scroller.current
+    if (!element) return
+    atBottom.current = element.scrollHeight - element.scrollTop - element.clientHeight < 32
+    if (atBottom.current) setMissed(0)
+  }
+
+  let previous: string | null = null
+  return (
+    <div className={['desk-thread', className].filter(Boolean).join(' ')}>
+      <div ref={scroller} className="desk-thread-scroll" role="log" aria-label={label} aria-live="polite" onScroll={onScroll}>
+        {messages.length === 0 && !typing && empty}
+        {messages.map(message => {
+          const mine = message.from === me
+          const runStart = message.from !== previous
+          previous = message.from
+          const stamp = time(message.at)
+          return (
+            <article
+              key={message.id}
+              className="desk-message"
+              data-mine={mine || undefined}
+              data-state={message.state ?? 'sent'}
+              data-run-start={runStart || undefined}
+            >
+              {runStart && !mine && <span className="desk-message-author">{message.authorName ?? message.from}</span>}
+              <div className="desk-bubble">{message.body}</div>
+              <span className="desk-message-foot">
+                {stamp && <time>{stamp}</time>}
+                {message.state === 'sending' && <span>Sending…</span>}
+                {message.state === 'failed' && (
+                  <>
+                    <span className="desk-message-failed">Not sent</span>
+                    {onRetry && (
+                      <Button size="small" intent="quiet" onClick={() => onRetry(message.id)}>
+                        Retry
+                      </Button>
+                    )}
+                  </>
+                )}
+              </span>
+            </article>
+          )
+        })}
+        {typing && (
+          <div className="desk-typing" aria-label="Typing">
+            {typing === true ? (
+              <span className="desk-typing-dots" aria-hidden="true">
+                <i />
+                <i />
+                <i />
+              </span>
+            ) : (
+              typing
+            )}
+          </div>
+        )}
+      </div>
+      {missed > 0 && (
+        <Button className="desk-thread-jump" size="small" onClick={() => toBottom('smooth')}>
+          {missed === 1 ? '1 new message' : `${missed} new messages`} ↓
+        </Button>
+      )}
+    </div>
+  )
+}
+
+export interface ComposerProps {
+  readonly value: string
+  readonly onChange: (value: string) => void
+  /** Called on Enter or Send, with the trimmed text. Clearing the box is yours to do. */
+  readonly onSubmit: (value: string) => void
+  readonly placeholder?: string
+  readonly label?: string
+  readonly disabled?: boolean
+  /** An answer is arriving: Send becomes Stop when `onStop` is given. */
+  readonly busy?: boolean
+  readonly onStop?: () => void
+  /** Beside the send button — attachments, a model picker. */
+  readonly accessory?: ReactNode
+  readonly maxRows?: number
+}
+
+export function Composer({
+  value,
+  onChange,
+  onSubmit,
+  placeholder = 'Say something…',
+  label = 'Message',
+  disabled,
+  busy,
+  onStop,
+  accessory,
+  maxRows = 8,
+}: ComposerProps) {
+  const field = useRef<HTMLTextAreaElement>(null)
+
+  // Grow with the text, up to maxRows, then scroll.
+  useLayoutEffect(() => {
+    const element = field.current
+    if (!element) return
+    element.style.height = 'auto'
+    const line = parseFloat(getComputedStyle(element).lineHeight || '20') || 20
+    element.style.height = `${Math.min(element.scrollHeight, line * maxRows)}px`
+  }, [value, maxRows])
+
+  const submit = () => {
+    const text = value.trim()
+    if (!text || disabled) return
+    onSubmit(text)
+  }
+
+  const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
+    // Enter sends; Shift+Enter is a new line. IME composition must never send.
+    if (event.key !== 'Enter' || event.shiftKey || event.nativeEvent.isComposing) return
+    event.preventDefault()
+    submit()
+  }
+
+  return (
+    <div className="desk-composer" data-disabled={disabled || undefined}>
+      <textarea
+        ref={field}
+        className="desk-composer-field"
+        aria-label={label}
+        rows={1}
+        value={value}
+        placeholder={placeholder}
+        disabled={disabled}
+        onChange={event => onChange(event.target.value)}
+        onKeyDown={onKeyDown}
+      />
+      {accessory}
+      {busy && onStop ? (
+        <Button aria-label="Stop" onClick={onStop}>
+          Stop
+        </Button>
+      ) : (
+        <Button intent="default" aria-label="Send" disabled={disabled || !value.trim()} onClick={submit}>
+          Send
+        </Button>
+      )}
+    </div>
+  )
+}