@liberation-data/desk 0.1.0

package/src/react/overlays.tsx

@@ -0,0 +1,254 @@
+import { createContext, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import type { ReactElement, ReactNode, RefObject } from 'react'
+import { createPortal } from 'react-dom'
+import { windowElement } from '../core/commands.js'
+import { Button } from './controls.js'
+import { useWindowId } from './context.js'
+import { useFocusTrap, useLayer } from './layers.js'
+
+/*
+ * Interruption, least to most (HIG.md §7): a popover belongs to one control, a
+ * sheet to one window, an alert to the whole app, and a toast interrupts nothing.
+ *
+ * Escape always dismisses the topmost layer, so overlays share one stack rather
+ * than each listening for their own key.
+ */
+
+/* ── Popover: a small task tied to one control ── */
+
+export interface PopoverTriggerProps {
+  readonly ref: RefObject<HTMLButtonElement | null>
+  readonly 'aria-haspopup': 'dialog'
+  readonly 'aria-expanded': boolean
+  readonly onClick: () => void
+}
+
+export interface PopoverProps {
+  readonly open: boolean
+  readonly onOpenChange: (open: boolean) => void
+  /** The accessible name of the popover. */
+  readonly label: string
+  /** Renders the control the popover hangs from; spread the props it is given. */
+  readonly trigger: (props: PopoverTriggerProps) => ReactElement
+  readonly placement?: 'below' | 'above'
+  readonly align?: 'start' | 'end'
+  readonly children: ReactNode
+}
+
+export function Popover({ open, onOpenChange, label, trigger, placement = 'below', align = 'start', children }: PopoverProps) {
+  const id = useId()
+  const button = useRef<HTMLButtonElement>(null)
+  const panel = useRef<HTMLDivElement>(null)
+  useLayer(id, open, () => onOpenChange(false))
+  useFocusTrap(panel, open)
+
+  useEffect(() => {
+    if (!open) return
+    const onPointerDown = (event: PointerEvent) => {
+      const target = event.target as Node
+      if (!panel.current?.contains(target) && !button.current?.contains(target)) onOpenChange(false)
+    }
+    document.addEventListener('pointerdown', onPointerDown, true)
+    return () => document.removeEventListener('pointerdown', onPointerDown, true)
+  }, [open, onOpenChange])
+
+  return (
+    <span className="desk-popover-anchor">
+      {trigger({ ref: button, 'aria-haspopup': 'dialog', 'aria-expanded': open, onClick: () => onOpenChange(!open) })}
+      {open && (
+        <div ref={panel} role="dialog" aria-label={label} className="desk-popover" data-placement={placement} data-align={align}>
+          {children}
+        </div>
+      )}
+    </span>
+  )
+}
+
+/* ── Sheet: a task that belongs to one window, and blocks only that window ── */
+
+export interface SheetProps {
+  readonly open: boolean
+  readonly onDismiss: () => void
+  readonly title: string
+  readonly description?: ReactNode
+  /** Buttons, trailing-aligned. Cancel before the default button. */
+  readonly actions?: ReactNode
+  readonly children?: ReactNode
+}
+
+export function Sheet({ open, onDismiss, title, description, actions, children }: SheetProps) {
+  const id = useId()
+  const panel = useRef<HTMLDivElement>(null)
+  const windowId = useWindowId()
+  // A sheet blocks its own window and nothing else, so it lives inside that window. It is
+  // found in the document rather than through a ref: a window's ref is attached after the
+  // effects of the content it holds have already run.
+  const [host, setHost] = useState<HTMLElement | null>(null)
+  useLayoutEffect(() => {
+    if (!open) {
+      setHost(null)
+      return
+    }
+    const element = windowId ? windowElement(document, windowId) : null
+    setHost(element instanceof HTMLElement ? element : document.body)
+  }, [open, windowId])
+  useLayer(id, open, onDismiss)
+  useFocusTrap(panel, open && host !== null)
+  if (!open || !host) return null
+
+  return createPortal(
+    <div className="desk-sheet-scrim">
+      <div ref={panel} role="dialog" aria-modal="true" aria-labelledby={`${id}-title`} className="desk-sheet">
+        <h2 id={`${id}-title`} className="desk-sheet-title">{title}</h2>
+        {description && <p className="desk-sheet-description">{description}</p>}
+        {children}
+        {actions && <div className="desk-sheet-actions">{actions}</div>}
+      </div>
+    </div>,
+    host,
+  )
+}
+
+/* ── Alert: the app cannot continue until this is decided. Rare. ── */
+
+export interface AlertProps {
+  readonly open: boolean
+  readonly title: string
+  readonly message?: ReactNode
+  /** The action the alert is asking about. */
+  readonly confirmLabel: string
+  readonly onConfirm: () => void
+  readonly onCancel: () => void
+  readonly cancelLabel?: string
+  /** Use for anything that cannot be undone. */
+  readonly destructive?: boolean
+}
+
+export function Alert({ open, title, message, confirmLabel, onConfirm, onCancel, cancelLabel = 'Cancel', destructive }: AlertProps) {
+  const id = useId()
+  const panel = useRef<HTMLDivElement>(null)
+  useLayer(id, open, onCancel)
+  useFocusTrap(panel, open)
+  if (!open) return null
+
+  return createPortal(
+    <div className="desk-alert-scrim">
+      <div
+        ref={panel}
+        role="alertdialog"
+        aria-modal="true"
+        aria-labelledby={`${id}-title`}
+        aria-describedby={message ? `${id}-message` : undefined}
+        className="desk-alert"
+      >
+        <h2 id={`${id}-title`} className="desk-alert-title">{title}</h2>
+        {message && <p id={`${id}-message`} className="desk-alert-message">{message}</p>}
+        <div className="desk-alert-actions">
+          <Button onClick={onCancel}>{cancelLabel}</Button>
+          <Button intent={destructive ? 'destructive' : 'default'} onClick={onConfirm}>{confirmLabel}</Button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  )
+}
+
+/* ── Toast: a background action finished; it interrupts nothing ── */
+
+export interface Toast {
+  readonly id: string
+  readonly message: ReactNode
+  readonly tone?: 'neutral' | 'ok' | 'bad'
+  /** Usually Undo. Dismisses the toast when chosen. */
+  readonly action?: { readonly label: string; readonly onSelect: () => void }
+  /** Milliseconds. 0 keeps it until dismissed. Default 6000. */
+  readonly duration?: number
+}
+
+export type ToastInput = Omit<Toast, 'id'> & { readonly id?: string }
+
+interface ToastApi {
+  show: (toast: ToastInput) => string
+  dismiss: (id: string) => void
+}
+
+const ToastContext = createContext<ToastApi | null>(null)
+
+export function ToastProvider({ children }: { readonly children: ReactNode }) {
+  const [toasts, setToasts] = useState<readonly Toast[]>([])
+  const counter = useRef(0)
+
+  const dismiss = useCallback((id: string) => setToasts(list => list.filter(t => t.id !== id)), [])
+  const show = useCallback((toast: ToastInput) => {
+    const id = toast.id ?? `toast-${(counter.current += 1)}`
+    setToasts(list => [...list.filter(t => t.id !== id), { ...toast, id }])
+    return id
+  }, [])
+  const api = useMemo(() => ({ show, dismiss }), [show, dismiss])
+
+  return (
+    <ToastContext.Provider value={api}>
+      {children}
+      <ToastStack toasts={toasts} onDismiss={dismiss} />
+    </ToastContext.Provider>
+  )
+}
+
+export function useToast(): ToastApi {
+  const api = useContext(ToastContext)
+  if (!api) throw new Error('useToast must be used inside a <ToastProvider>')
+  return api
+}
+
+function ToastStack({ toasts, onDismiss }: { readonly toasts: readonly Toast[]; readonly onDismiss: (id: string) => void }) {
+  if (!toasts.length) return null
+  return createPortal(
+    <div className="desk-toasts">
+      {toasts.map(toast => (
+        <ToastView key={toast.id} toast={toast} onDismiss={() => onDismiss(toast.id)} />
+      ))}
+    </div>,
+    document.body,
+  )
+}
+
+function ToastView({ toast, onDismiss }: { readonly toast: Toast; readonly onDismiss: () => void }) {
+  const [paused, setPaused] = useState(false)
+  const duration = toast.duration ?? 6000
+
+  useEffect(() => {
+    if (!duration || paused) return
+    const timer = setTimeout(onDismiss, duration)
+    return () => clearTimeout(timer)
+  }, [duration, paused, onDismiss])
+
+  return (
+    <div
+      className="desk-toast"
+      data-tone={toast.tone ?? 'neutral'}
+      role={toast.tone === 'bad' ? 'alert' : 'status'}
+      // Reading it, or reaching for Undo, should not start the clock against you.
+      onPointerEnter={() => setPaused(true)}
+      onPointerLeave={() => setPaused(false)}
+      onFocusCapture={() => setPaused(true)}
+      onBlurCapture={() => setPaused(false)}
+    >
+      <span className="desk-toast-message">{toast.message}</span>
+      {toast.action && (
+        <Button
+          size="small"
+          intent="quiet"
+          onClick={() => {
+            toast.action?.onSelect()
+            onDismiss()
+          }}
+        >
+          {toast.action.label}
+        </Button>
+      )}
+      <Button size="small" intent="quiet" aria-label="Dismiss" onClick={onDismiss}>
+        ✕
+      </Button>
+    </div>
+  )
+}

package/src/react/popup.tsx

@@ -0,0 +1,176 @@
+import { useEffect, useId, useRef, useState } from 'react'
+import type { KeyboardEvent, ReactNode } from 'react'
+
+/*
+ * A pop-up button: what a segmented control becomes once there are too many
+ * options to show at once, or the options need explaining. It is a form control,
+ * not a menu — so, unlike a menu, it takes focus while it is open.
+ */
+
+export interface PopUpOption<T extends string> {
+  readonly value: T
+  readonly label: string
+  readonly description?: string
+  readonly icon?: ReactNode
+  readonly disabled?: boolean
+}
+
+export interface PopUpButtonProps<T extends string> {
+  readonly value: T | null
+  readonly onChange: (value: T) => void
+  readonly options: readonly PopUpOption<T>[]
+  readonly label: string
+  /** Hides the label on screen but keeps it for assistive technology. */
+  readonly labelHidden?: boolean
+  readonly placeholder?: string
+  readonly disabled?: boolean
+  readonly size?: 'regular' | 'small'
+}
+
+export function PopUpButton<T extends string>({
+  value,
+  onChange,
+  options,
+  label,
+  labelHidden,
+  placeholder = 'Choose…',
+  disabled,
+  size = 'regular',
+}: PopUpButtonProps<T>) {
+  const id = useId()
+  const [open, setOpen] = useState(false)
+  const [active, setActive] = useState(0)
+  const button = useRef<HTMLButtonElement>(null)
+  const list = useRef<HTMLUListElement>(null)
+  const typed = useRef({ text: '', at: 0 })
+
+  const selectable = options.filter(o => !o.disabled)
+  const selected = options.find(o => o.value === value) ?? null
+
+  const show = (from: 'first' | 'selected' = 'selected') => {
+    const start = from === 'selected' && selected ? options.indexOf(selected) : options.findIndex(o => !o.disabled)
+    setActive(Math.max(0, start))
+    setOpen(true)
+  }
+
+  const close = (returnFocus = true) => {
+    setOpen(false)
+    if (returnFocus) button.current?.focus()
+  }
+
+  const choose = (index: number) => {
+    const option = options[index]
+    if (!option || option.disabled) return
+    onChange(option.value)
+    close()
+  }
+
+  useEffect(() => {
+    if (!open) return
+    list.current?.focus()
+    const onPointerDown = (event: PointerEvent) => {
+      const target = event.target as Node
+      if (!list.current?.contains(target) && !button.current?.contains(target)) setOpen(false)
+    }
+    document.addEventListener('pointerdown', onPointerDown, true)
+    return () => document.removeEventListener('pointerdown', onPointerDown, true)
+  }, [open])
+
+  const step = (from: number, delta: 1 | -1) => {
+    for (let i = 1; i <= options.length; i++) {
+      const index = (from + delta * i + options.length * 2) % options.length
+      if (!options[index]?.disabled) return index
+    }
+    return from
+  }
+
+  const onListKeyDown = (event: KeyboardEvent<HTMLUListElement>) => {
+    switch (event.key) {
+      case 'ArrowDown': setActive(step(active, 1)); break
+      case 'ArrowUp': setActive(step(active, -1)); break
+      case 'Home': setActive(step(-1, 1)); break
+      case 'End': setActive(step(options.length, -1)); break
+      case 'Enter':
+      case ' ': choose(active); break
+      case 'Escape':
+      case 'Tab': close(); break
+      default: {
+        if (event.key.length !== 1 || event.metaKey || event.ctrlKey || event.altKey) return
+        // Typeahead: letters typed close together look for a word, a single letter cycles.
+        const now = Date.now()
+        typed.current = { text: now - typed.current.at < 800 ? typed.current.text + event.key : event.key, at: now }
+        const search = typed.current.text.toLowerCase()
+        const found = selectable.find(o => o.label.toLowerCase().startsWith(search))
+        if (found) setActive(options.indexOf(found))
+        break
+      }
+    }
+    event.preventDefault()
+  }
+
+  const onButtonKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp' || event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault()
+      show(event.key === 'ArrowDown' ? 'selected' : 'selected')
+    }
+  }
+
+  return (
+    <div className="desk-field" data-popup>
+      <span id={`${id}-label`} className="desk-label" data-hidden={labelHidden || undefined}>
+        {label}
+      </span>
+      <div className="desk-popup-anchor">
+        <button
+          ref={button}
+          type="button"
+          className="desk-popup-button"
+          data-size={size}
+          aria-haspopup="listbox"
+          aria-expanded={open}
+          aria-labelledby={`${id}-label ${id}-value`}
+          disabled={disabled}
+          onKeyDown={onButtonKeyDown}
+          onClick={() => (open ? close(false) : show())}
+        >
+          {selected?.icon && <span className="desk-popup-icon" aria-hidden="true">{selected.icon}</span>}
+          <span id={`${id}-value`} className="desk-popup-value" data-placeholder={!selected || undefined}>
+            {selected?.label ?? placeholder}
+          </span>
+          <span className="desk-popup-chevron" aria-hidden="true">⌄</span>
+        </button>
+        {open && (
+          <ul
+            ref={list}
+            role="listbox"
+            tabIndex={-1}
+            aria-labelledby={`${id}-label`}
+            aria-activedescendant={options[active] ? `${id}-option-${active}` : undefined}
+            className="desk-popup-list"
+            onKeyDown={onListKeyDown}
+          >
+            {options.map((option, index) => (
+              <li
+                key={option.value}
+                id={`${id}-option-${index}`}
+                role="option"
+                aria-selected={option.value === value}
+                aria-disabled={option.disabled || undefined}
+                className="desk-popup-option"
+                data-active={index === active || undefined}
+                onPointerMove={() => !option.disabled && setActive(index)}
+                onClick={() => choose(index)}
+              >
+                <span className="desk-popup-check" aria-hidden="true">{option.value === value ? '✓' : ''}</span>
+                <span className="desk-popup-text">
+                  <span>{option.label}</span>
+                  {option.description && <span className="desk-help">{option.description}</span>}
+                </span>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/react/search.tsx

@@ -0,0 +1,177 @@
+import { useEffect, useId, useMemo, useRef, useState } from 'react'
+import type { KeyboardEvent, ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import type { Desk } from '../core/desk.js'
+import type { WindowId } from '../core/types.js'
+import { useCommand, useShortcuts } from './commands.js'
+import { useDesk } from './context.js'
+import { useFocusTrap, useLayer } from './layers.js'
+
+/*
+ * One place to search everything the app knows. The app says what the results
+ * are; the palette handles typing, keyboard, grouping and choosing.
+ */
+
+export interface SearchResult {
+  readonly id: string
+  readonly title: string
+  readonly subtitle?: string
+  /** Groups the results under a heading, in the order the groups first appear. */
+  readonly group?: string
+  readonly icon?: ReactNode
+  /** A short word for what this is: `window`, `ride`, `command`. */
+  readonly kind?: string
+  readonly onSelect: () => void
+}
+
+/** The open windows as results, for an app to mix into its own. */
+export function windowResults(desk: Desk, title: (id: WindowId) => string, group = 'Windows'): SearchResult[] {
+  return desk.getState().windows.map(w => ({
+    id: `window:${w.id}`,
+    title: title(w.id),
+    group,
+    kind: 'window',
+    onSelect: () => desk.focus(w.id),
+  }))
+}
+
+export const SearchCommand = 'desk.search'
+
+export interface SearchPaletteProps {
+  readonly open: boolean
+  readonly onOpenChange: (open: boolean) => void
+  /** Called as the person types. May be async; a slower answer never overtakes a newer one. */
+  readonly search: (query: string) => readonly SearchResult[] | Promise<readonly SearchResult[]>
+  readonly placeholder?: string
+  readonly label?: string
+  /** Shown before anything is typed. */
+  readonly hint?: ReactNode
+  /** Shown when a query matches nothing. */
+  readonly empty?: (query: string) => ReactNode
+  /** Also opens the palette. Default `mod+k`; pass `null` to bind nothing. */
+  readonly shortcut?: string | null
+}
+
+export function SearchPalette({
+  open,
+  onOpenChange,
+  search,
+  placeholder = 'Search',
+  label = 'Search',
+  hint,
+  empty,
+  shortcut = 'mod+k',
+}: SearchPaletteProps) {
+  const desk = useDesk()
+  const id = useId()
+  const panel = useRef<HTMLDivElement>(null)
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState<readonly SearchResult[]>([])
+  const [active, setActive] = useState(0)
+
+  useLayer(id, open, () => onOpenChange(false))
+  useFocusTrap(panel, open)
+  useCommand(SearchCommand, () => onOpenChange(true), { at: 'app' })
+  // Memoised: bindShortcuts re-registers whenever the keymap object changes identity.
+  useShortcuts(useMemo(() => (shortcut ? { [shortcut]: SearchCommand } : {}), [shortcut]))
+
+  useEffect(() => {
+    if (!open) setQuery('')
+  }, [open])
+
+  useEffect(() => {
+    if (!open) return
+    let current = true
+    Promise.resolve(search(query)).then(found => {
+      // A slow search for an old query must not replace the answer to a newer one.
+      if (!current) return
+      setResults(found)
+      setActive(0)
+    })
+    return () => {
+      current = false
+    }
+  }, [open, query, search])
+
+  if (!open) return null
+
+  const choose = (result: SearchResult | undefined) => {
+    if (!result) return
+    onOpenChange(false)
+    result.onSelect()
+  }
+
+  const onKeyDown = (event: KeyboardEvent<HTMLElement>) => {
+    const move = (to: number) => {
+      event.preventDefault()
+      setActive(Math.max(0, Math.min(to, results.length - 1)))
+    }
+    switch (event.key) {
+      case 'ArrowDown': return move(active + 1)
+      case 'ArrowUp': return move(active - 1)
+      case 'Home': return move(0)
+      case 'End': return move(results.length - 1)
+      case 'Enter': {
+        event.preventDefault()
+        return choose(results[active])
+      }
+      default:
+    }
+  }
+
+  const listId = `${id}-results`
+  let group: string | undefined
+  return createPortal(
+    <div className="desk-search-scrim" onPointerDown={event => event.target === event.currentTarget && onOpenChange(false)}>
+      <div ref={panel} role="dialog" aria-label={label} className="desk-search" onKeyDown={onKeyDown}>
+        <div className="desk-search-bar">
+          <input
+            className="desk-search-field"
+            role="combobox"
+            aria-label={label}
+            aria-expanded
+            aria-controls={listId}
+            aria-activedescendant={results[active] ? `${id}-${active}` : undefined}
+            aria-autocomplete="list"
+            placeholder={placeholder}
+            value={query}
+            onChange={event => setQuery(event.target.value)}
+          />
+        </div>
+        {results.length > 0 && (
+          <ul id={listId} role="listbox" aria-label={label} className="desk-search-results">
+            {results.map((result, index) => {
+              const heading = result.group && result.group !== group ? result.group : null
+              group = result.group
+              return (
+                <li key={result.id} className="desk-search-row-wrap">
+                  {heading && <p className="desk-search-group">{heading}</p>}
+                  <div
+                    id={`${id}-${index}`}
+                    role="option"
+                    aria-selected={index === active}
+                    className="desk-search-row"
+                    data-active={index === active || undefined}
+                    onPointerMove={() => setActive(index)}
+                    onClick={() => choose(result)}
+                  >
+                    {result.icon && <span className="desk-search-icon" aria-hidden="true">{result.icon}</span>}
+                    <span className="desk-search-text">
+                      <span className="desk-search-title">{result.title}</span>
+                      {result.subtitle && <span className="desk-search-subtitle">{result.subtitle}</span>}
+                    </span>
+                    {result.kind && <span className="desk-search-kind">{result.kind}</span>}
+                  </div>
+                </li>
+              )
+            })}
+          </ul>
+        )}
+        {results.length === 0 && (
+          <p className="desk-search-empty">{query.trim() ? (empty?.(query) ?? `Nothing matches “${query}”.`) : hint}</p>
+        )}
+      </div>
+    </div>,
+    document.body,
+  )
+}