@liberation-data/desk 0.1.0

package/src/react/dnd.tsx

@@ -0,0 +1,189 @@
+import { useCallback, useContext, useEffect, useId, useRef, useState } from 'react'
+import type { PointerEvent as ReactPointerEvent, ReactNode } from 'react'
+import { WINDOW_ATTRIBUTE } from '../core/commands.js'
+import { useDesk, useWindowId } from './context.js'
+import { accepted, DragContext, TARGET_ATTRIBUTE } from './dragContext.js'
+import type { Accepts, Drag } from './dragContext.js'
+
+export { DragProvider } from './dragContext.js'
+export type { Accepts, Drag } from './dragContext.js'
+
+/*
+ * Dragging something from one window to another — a ride onto the map, a
+ * document into a conversation. Built on Pointer Events rather than HTML5
+ * drag-and-drop: the same code then works for touch and pen, the preview is
+ * ours to draw, and a drag can be cancelled with Escape.
+ *
+ * What is dragged is a `type` and a `payload`. A target says which types it
+ * takes; nothing else about the two windows is shared.
+ */
+
+const useDrag = () => {
+  const context = useContext(DragContext)
+  if (!context) throw new Error('Dragging needs a <DeskProvider> (or a <DragProvider>) above it')
+  return context
+}
+
+/** What is being dragged right now, for a window that wants to show it is ready. */
+export const useDragging = (): Drag | null => useDrag().state?.drag ?? null
+
+export interface DraggableOptions<T> {
+  readonly type: string
+  readonly payload: T
+  /** What follows the pointer. Defaults to the type. */
+  readonly preview?: ReactNode
+  readonly disabled?: boolean
+}
+
+export interface DraggableResult {
+  readonly dragProps: { readonly onPointerDown: (event: ReactPointerEvent<HTMLElement>) => void; readonly 'data-desk-draggable': true }
+  readonly dragging: boolean
+}
+
+export interface DragSourceOptions {
+  readonly type: string
+  readonly disabled?: boolean
+}
+
+export interface DragSource<T> {
+  /** Props for one item in a list: `rowProps={row => source.dragProps(row, row.name)}`. */
+  readonly dragProps: (payload: T, preview?: ReactNode) => DraggableResult['dragProps']
+  readonly dragging: boolean
+}
+
+/**
+ * One source for a list of things: a hook cannot be called per row, so the row
+ * says what it is as it is picked up.
+ */
+export function useDragSource<T>({ type, disabled }: DragSourceOptions): DragSource<T> {
+  const { targets, setState } = useDrag()
+  const from = useWindowId()
+  const desk = useDesk()
+  const [dragging, setDragging] = useState(false)
+
+  const start = useCallback(
+    (payload: T, preview: ReactNode) => (event: ReactPointerEvent<HTMLElement>) => {
+      if (disabled || event.button !== 0) return
+      const startX = event.clientX
+      const startY = event.clientY
+      const handle = event.currentTarget
+      let started = false
+
+      const findTarget = (x: number, y: number) => {
+        const element = document.elementFromPoint(x, y)?.closest(`[${TARGET_ATTRIBUTE}]`)
+        const key = element?.getAttribute(TARGET_ATTRIBUTE) ?? null
+        const target = key ? targets.get(key) : undefined
+        return target && accepted(target.accepts, type) ? key : null
+      }
+
+      const onMove = (move: PointerEvent) => {
+        if (!started && Math.hypot(move.clientX - startX, move.clientY - startY) < 5) return
+        if (!started) {
+          started = true
+          setDragging(true)
+          handle.setPointerCapture?.(move.pointerId)
+        }
+        move.preventDefault()
+        setState({
+          drag: { type, payload, from },
+          x: move.clientX,
+          y: move.clientY,
+          over: findTarget(move.clientX, move.clientY),
+          preview: preview ?? type,
+        })
+      }
+
+      const finish = (drop: boolean, released?: PointerEvent) => {
+        document.removeEventListener('pointermove', onMove)
+        document.removeEventListener('pointerup', onUp)
+        document.removeEventListener('keydown', onKey)
+        if (!started) return
+        setDragging(false)
+        // Pointer capture sends the release back to where the drag began, and the browser then
+        // counts the whole gesture as a click on it. A drag is never also a click.
+        const swallow = (click: MouseEvent) => {
+          click.stopPropagation()
+          click.preventDefault()
+        }
+        globalThis.addEventListener('click', swallow, { capture: true, once: true })
+        setTimeout(() => globalThis.removeEventListener('click', swallow, { capture: true }), 0)
+        const key = drop && released ? findTarget(released.clientX, released.clientY) : null
+        const target = key ? targets.get(key) : undefined
+        setState(null)
+        if (!target) return
+        target.onDrop({ type, payload, from })
+        // The window that took it comes forward: that is where the work moved to.
+        const receiving = document.querySelector(`[${TARGET_ATTRIBUTE}="${key}"]`)?.closest(`[${WINDOW_ATTRIBUTE}]`)
+        const windowId = receiving?.getAttribute(WINDOW_ATTRIBUTE)
+        if (windowId) desk.focus(windowId)
+      }
+
+      const onUp = (up: PointerEvent) => finish(true, up)
+      const onKey = (key: KeyboardEvent) => {
+        if (key.key === 'Escape') finish(false)
+      }
+
+      document.addEventListener('pointermove', onMove)
+      document.addEventListener('pointerup', onUp)
+      document.addEventListener('keydown', onKey)
+    },
+    [disabled, type, from, setState, targets, desk],
+  )
+
+  return {
+    dragProps: useCallback((payload: T, preview?: ReactNode) => ({ onPointerDown: start(payload, preview), 'data-desk-draggable': true as const }), [start]),
+    dragging,
+  }
+}
+
+/** Makes one thing picked up and carried. Spread `dragProps` on the element. */
+export function useDraggable<T>({ type, payload, preview, disabled }: DraggableOptions<T>): DraggableResult {
+  const source = useDragSource<T>({ type, ...(disabled === undefined ? {} : { disabled }) })
+  return { dragProps: source.dragProps(payload, preview), dragging: source.dragging }
+}
+
+export interface DropTargetOptions<T> {
+  readonly accepts: Accepts
+  readonly onDrop: (drag: Drag<T>) => void
+  readonly disabled?: boolean
+}
+
+export interface DropTargetResult {
+  readonly dropProps: Record<string, string | undefined>
+  /** Something acceptable is being carried over this target right now. */
+  readonly over: boolean
+  /** Something acceptable is being carried somewhere: show where it could go. */
+  readonly ready: boolean
+}
+
+/** Makes something a place to drop. Spread `dropProps` on the element. */
+export function useDropTarget<T>({ accepts, onDrop, disabled }: DropTargetOptions<T>): DropTargetResult {
+  const { state, targets } = useDrag()
+  const id = useId()
+  const latest = useRef({ accepts, onDrop })
+  latest.current = { accepts, onDrop }
+
+  useEffect(() => {
+    if (disabled) return
+    targets.set(id, {
+      accepts: type => accepted(latest.current.accepts, type),
+      onDrop: drag => latest.current.onDrop(drag as Drag<T>),
+    })
+    return () => {
+      targets.delete(id)
+    }
+  }, [id, targets, disabled])
+
+  const ready = Boolean(state && !disabled && accepted(accepts, state.drag.type))
+  const over = ready && state?.over === id
+  return {
+    // The marks the stylesheet looks for, so a target lights up without the app wiring it.
+    dropProps: {
+      [TARGET_ATTRIBUTE]: disabled ? undefined : id,
+      ...(ready ? { 'data-ready': 'true' } : {}),
+      ...(over ? { 'data-over': 'true' } : {}),
+    },
+    over,
+    ready,
+  }
+}

package/src/react/dragContext.tsx

@@ -0,0 +1,60 @@
+import { createContext, useMemo, useState } from 'react'
+import type { ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+
+/*
+ * The state behind dragging, kept apart from the hooks that use it: a desk
+ * provides this, and the hooks reach for the desk — so this file must not.
+ */
+
+export interface Drag<T = unknown> {
+  readonly type: string
+  readonly payload: T
+  /** The window it was picked up in, when it was picked up in one. */
+  readonly from: string | null
+}
+
+export type Accepts = string | readonly string[] | ((type: string) => boolean)
+
+export const accepted = (accepts: Accepts, type: string) =>
+  typeof accepts === 'function' ? accepts(type) : typeof accepts === 'string' ? accepts === type : accepts.includes(type)
+
+export interface Target {
+  readonly accepts: Accepts
+  readonly onDrop: (drag: Drag) => void
+}
+
+export interface DragState {
+  readonly drag: Drag
+  readonly x: number
+  readonly y: number
+  readonly over: string | null
+  readonly preview: ReactNode
+}
+
+export interface DragContextValue {
+  readonly state: DragState | null
+  readonly targets: Map<string, Target>
+  readonly setState: (state: DragState | null) => void
+}
+
+export const DragContext = createContext<DragContextValue | null>(null)
+
+export const TARGET_ATTRIBUTE = 'data-desk-drop'
+
+/** Holds what is being carried. A desk provides one; this is for sharing or nesting. */
+export function DragProvider({ children }: { readonly children: ReactNode }) {
+  const [state, setState] = useState<DragState | null>(null)
+  const [targets] = useState(() => new Map<string, Target>())
+  const value = useMemo(() => ({ state, targets, setState }), [state, targets])
+  return (
+    <DragContext.Provider value={value}>
+      {children}
+      {state && (
+        <div className="desk-drag-preview" style={{ left: state.x, top: state.y }} aria-hidden="true">
+          {state.preview}
+        </div>
+      )}
+    </DragContext.Provider>
+  )
+}

package/src/react/events.tsx

@@ -0,0 +1,149 @@
+import { useCallback, useContext, useEffect, useId, useMemo, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import { perform } from '../core/commands.js'
+import { createBus, InputCommands } from '../core/events.js'
+import type { Bus, DeskEvent, EventHandler, InputDescription, SubscribeOptions } from '../core/events.js'
+import type { WindowId } from '../core/types.js'
+import { useCommand, useShortcuts } from './commands.js'
+import { Composer } from './conversation.js'
+import { useFocusTrap, useLayer } from './layers.js'
+import { BusContext, useDesk, useDeskState, useWindowId } from './context.js'
+
+/** Supplies a bus of your own, or shares one across several desks. A desk already has one. */
+export function BusProvider({ bus, children }: { readonly bus?: Bus; readonly children: ReactNode }) {
+  const [value] = useState(() => bus ?? createBus())
+  return <BusContext.Provider value={value}>{children}</BusContext.Provider>
+}
+
+export function useBus(): Bus {
+  const bus = useContext(BusContext)
+  if (!bus) throw new Error('useBus must be used inside a <DeskProvider> or <BusProvider>')
+  return bus
+}
+
+/** Publishes an event, stamped with the window it came from. */
+export function usePublish(): <T>(topic: string, payload: T) => DeskEvent<T> {
+  const bus = useBus()
+  const from = useWindowId()
+  return useCallback((topic, payload) => bus.publish(topic, payload, { from }), [bus, from])
+}
+
+/** Answers events on a topic (`ride.selected`, `ride.*`, `*`) while mounted. */
+export function useDeskEvent<T = unknown>(topic: string, handler: EventHandler<T>, options: SubscribeOptions = {}): void {
+  const bus = useBus()
+  const latest = useRef(handler)
+  latest.current = handler
+  const { replay } = options
+  useEffect(() => bus.subscribe<T>(topic, event => latest.current(event), { replay: replay ?? false }), [bus, topic, replay])
+}
+
+export interface WindowInputOptions {
+  readonly placeholder?: string
+  /** What the bar says the text will reach. Defaults to the window's id. */
+  readonly target?: string
+  readonly disabled?: boolean
+}
+
+/**
+ * Takes the text typed into the desk's input bar while this window is key.
+ * A window that registers nothing lets the bar's own fallback have it.
+ */
+export function useWindowInput(handler: (text: string) => void, options: WindowInputOptions = {}): void {
+  const windowId = useWindowId()
+  const { placeholder, target, disabled } = options
+  useCommand<string>(InputCommands.submit, handler, { enabled: !disabled })
+  // The bar asks the chain how to present itself; the answer is written into the object it sends.
+  useCommand<InputDescription>(InputCommands.describe, description => {
+    if (placeholder) description.placeholder = placeholder
+    const named = target ?? windowId
+    if (named) description.target = named
+    description.disabled = disabled ?? false
+  })
+}
+
+export interface InputBarProps {
+  /** Used when no window takes the text. */
+  readonly onSubmit: (text: string) => void
+  readonly fallbackPlaceholder?: string
+  readonly fallbackTarget?: string
+  readonly label?: string
+  /**
+   * `summoned` (the default) stays out of the way until called for, then opens
+   * over the middle of the screen. `inline` is always there, wherever you put it.
+   */
+  readonly mode?: 'summoned' | 'inline'
+  /** Summons the bar. Default `mod+j`; `null` binds nothing (a menu item may own the key). */
+  readonly shortcut?: string | null
+  readonly className?: string
+}
+
+/** One place to type, which reaches whichever window you are working in. */
+export function InputBar({
+  onSubmit,
+  fallbackPlaceholder = 'Type here…',
+  fallbackTarget,
+  label = 'Type here',
+  mode = 'summoned',
+  shortcut = 'mod+j',
+  className,
+}: InputBarProps) {
+  const desk = useDesk()
+  const state = useDeskState()
+  const [value, setValue] = useState('')
+  const [open, setOpen] = useState(mode === 'inline')
+  const [description, setDescription] = useState<InputDescription>({})
+  const panel = useRef<HTMLDivElement>(null)
+  const id = useId()
+
+  const summoned = mode === 'summoned'
+  useCommand(InputCommands.open, () => setOpen(true), { at: 'app' })
+  useShortcuts(useMemo(() => (shortcut && summoned ? { [shortcut]: InputCommands.open } : {}), [shortcut, summoned]))
+  useLayer(id, summoned && open, () => setOpen(false))
+  useFocusTrap(panel, summoned && open)
+
+  // Re-ask whenever the key window changes, or the bar is summoned: it belongs to whoever is in front.
+  const key: WindowId | null = state.stack.at(-1) ?? null
+  useEffect(() => {
+    if (!open) return
+    const answer: InputDescription = {}
+    perform(desk, InputCommands.describe, answer)
+    setDescription(answer)
+  }, [desk, key, open, id])
+
+  if (!open) return null
+
+  const submit = (text: string) => {
+    if (!perform(desk, InputCommands.submit, text)) onSubmit(text)
+    setValue('')
+    if (summoned) setOpen(false)
+  }
+
+  const target = description.target ?? fallbackTarget
+  const bar = (
+    <div ref={panel} className={['desk-inputbar', className].filter(Boolean).join(' ')} data-mode={mode}>
+      <Composer
+        value={value}
+        onChange={setValue}
+        onSubmit={submit}
+        label={label}
+        placeholder={description.placeholder ?? fallbackPlaceholder}
+        maxRows={4}
+        {...(description.disabled ? { disabled: true } : {})}
+      />
+      {target && (
+        <span className="desk-inputbar-target" aria-live="polite">
+          goes to <b>{target}</b>
+        </span>
+      )}
+    </div>
+  )
+
+  if (!summoned) return bar
+  return createPortal(
+    <div className="desk-inputbar-scrim" onPointerDown={event => event.target === event.currentTarget && setOpen(false)}>
+      {bar}
+    </div>,
+    document.body,
+  )
+}

package/src/react/index.ts

@@ -0,0 +1,64 @@
+export { APP_BRIDGE_SCRIPT, AppFrame, withAppBridge } from './appFrame.js'
+export type { AppFrameProps } from './appFrame.js'
+export { DragProvider, useDraggable, useDragging, useDragSource, useDropTarget } from './dnd.js'
+export type {
+  Accepts,
+  Drag,
+  DraggableOptions,
+  DraggableResult,
+  DragSource,
+  DragSourceOptions,
+  DropTargetOptions,
+  DropTargetResult,
+} from './dnd.js'
+export { DeskShell } from './shell.js'
+export type { DeskShellProps } from './shell.js'
+export { DeskProvider, useDesk, useDeskState, useWindowId } from './context.js'
+export type { DeskProviderProps } from './context.js'
+export { useCanPerform, useCommand, usePerform, useShortcuts } from './commands.js'
+export type { UseCommandOptions } from './commands.js'
+export { Desktop } from './Desktop.js'
+export type { DeskLayout, DesktopProps } from './Desktop.js'
+export { lazyWindow } from './windowBoundary.js'
+export type { WindowFailed, WindowLoading } from './windowBoundary.js'
+export { Button, Checkbox, ChoiceGroup, RadioGroup, SegmentedControl, Slider, TextField, Toggle } from './controls.js'
+export type {
+  ButtonIntent,
+  ButtonProps,
+  CheckboxProps,
+  ChoiceGroupProps,
+  ChoiceOption,
+  RadioGroupProps,
+  RadioOption,
+  SegmentedControlProps,
+  SegmentedOption,
+  SliderProps,
+  TextFieldProps,
+  ToggleProps,
+} from './controls.js'
+export { Checklist, useTasks } from './tasks.js'
+export { localSetupStore, useSetupProgress } from './setupProgress.js'
+export type { SetupProgress, SetupProgressOptions, SetupRecord, SetupStore } from './setupProgress.js'
+export type { ChecklistProps, Task, TaskProgress, Tasks, TaskState } from './tasks.js'
+export { PopUpButton } from './popup.js'
+export type { PopUpButtonProps, PopUpOption } from './popup.js'
+export { Table } from './table.js'
+export type { Column, Sort, TableProps } from './table.js'
+export { Sidebar } from './sidebar.js'
+export type { SidebarItem, SidebarProps, SidebarSection } from './sidebar.js'
+export { Wizard } from './wizard.js'
+export type { WizardProps, WizardStep } from './wizard.js'
+export { TourBar } from './tour.js'
+export type { Tour, TourBarProps, TourStep } from './tour.js'
+export { SearchCommand, SearchPalette, windowResults } from './search.js'
+export type { SearchPaletteProps, SearchResult } from './search.js'
+export { BusProvider, InputBar, useBus, useDeskEvent, usePublish, useWindowInput } from './events.js'
+export type { InputBarProps, WindowInputOptions } from './events.js'
+export { Composer, Thread } from './conversation.js'
+export type { ComposerProps, Message, ThreadProps } from './conversation.js'
+export { Alert, Popover, Sheet, ToastProvider, useToast } from './overlays.js'
+export type { AlertProps, PopoverProps, PopoverTriggerProps, SheetProps, Toast, ToastInput } from './overlays.js'
+export { MenuBar, menuAction, menuCommand, menuHeader, menuSeparator, windowMenuItems } from './MenuBar.js'
+export type { Menu, MenuBarProps, MenuItem } from './MenuBar.js'
+export { Dock, dockItem, dockSeparator, dockStack } from './Dock.js'
+export type { DockEntry, DockItem, DockProps, DockStack } from './Dock.js'

package/src/react/layers.ts

@@ -0,0 +1,66 @@
+import { useEffect, useRef } from 'react'
+import type { RefObject } from 'react'
+
+/*
+ * What every overlay needs: a shared stack so Escape dismisses the topmost one
+ * rather than all of them, and a focus trap that gives focus back on the way out.
+ */
+
+const layers: string[] = []
+const isTopLayer = (id: string) => layers.at(-1) === id
+
+export function useLayer(id: string, open: boolean, onEscape: () => void) {
+  useEffect(() => {
+    if (!open) return
+    layers.push(id)
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape' || !isTopLayer(id)) return
+      event.preventDefault()
+      event.stopPropagation()
+      onEscape()
+    }
+    document.addEventListener('keydown', onKeyDown, true)
+    return () => {
+      const at = layers.lastIndexOf(id)
+      if (at >= 0) layers.splice(at, 1)
+      document.removeEventListener('keydown', onKeyDown, true)
+    }
+  })
+}
+
+const TABBABLE =
+  'a[href], button:not(:disabled), input:not(:disabled), select:not(:disabled), textarea:not(:disabled), [tabindex]:not([tabindex="-1"])'
+
+const tabbable = (root: HTMLElement) => [...root.querySelectorAll<HTMLElement>(TABBABLE)].filter(el => !el.closest('[inert]'))
+
+/** Holds keyboard focus inside `panel` while open, and gives it back on close. */
+export function useFocusTrap(panel: RefObject<HTMLElement | null>, open: boolean) {
+  const returnTo = useRef<HTMLElement | null>(null)
+  useEffect(() => {
+    if (!open) return
+    returnTo.current = document.activeElement instanceof HTMLElement ? document.activeElement : null
+    const first = panel.current && (tabbable(panel.current)[0] ?? panel.current)
+    first?.focus({ preventScroll: true })
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Tab' || !panel.current) return
+      const stops = tabbable(panel.current)
+      if (!stops.length) return
+      const [first, last] = [stops[0] as HTMLElement, stops.at(-1) as HTMLElement]
+      const active = document.activeElement
+      if (event.shiftKey && (active === first || !panel.current.contains(active))) {
+        event.preventDefault()
+        last.focus()
+      } else if (!event.shiftKey && active === last) {
+        event.preventDefault()
+        first.focus()
+      }
+    }
+    document.addEventListener('keydown', onKeyDown, true)
+    return () => {
+      document.removeEventListener('keydown', onKeyDown, true)
+      if (returnTo.current?.isConnected) returnTo.current.focus({ preventScroll: true })
+    }
+  }, [open, panel])
+}
+