@liberation-data/desk 0.1.0

package/src/react/Desktop.tsx

@@ -0,0 +1,349 @@
+import { memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react'
+import type { CSSProperties, PointerEvent as ReactPointerEvent, ReactNode } from 'react'
+import { addCommandHandler, addDeskCommands, DeskCommands, STAGE_ATTRIBUTE, WINDOW_ATTRIBUTE, windowElement } from '../core/commands.js'
+import { focusedId } from '../core/desk.js'
+import type { DeskWindow, Frame, WindowId } from '../core/types.js'
+import { arrangement } from './arrange.js'
+import { useDesk, useDeskState, WindowContext } from './context.js'
+import { WindowBoundary } from './windowBoundary.js'
+import type { WindowFailed, WindowLoading } from './windowBoundary.js'
+
+export type DeskLayout = 'desktop' | 'fullscreen'
+
+export interface DesktopProps {
+  readonly renderWindow: (id: WindowId) => ReactNode
+  readonly title: (id: WindowId) => ReactNode
+  /** Window-wide controls on the trailing side of the title bar. One or two; more belongs in a toolbar. */
+  readonly actions?: (id: WindowId) => ReactNode
+  /** Shown when no window is open. */
+  readonly empty?: ReactNode
+  /** Shown inside a window while its code loads. Default: a quiet "Loading…". */
+  readonly loading?: WindowLoading
+  /** Shown inside a window that could not open, with a way to try again. */
+  readonly failed?: WindowFailed
+  /**
+   * `auto` (the default) reads the device: a touch screen gets `fullscreen`, one
+   * window at a time; anything with a pointer gets the layered `desktop`.
+   */
+  readonly layout?: DeskLayout | 'auto'
+  readonly className?: string
+}
+
+/** Touch-first: a coarse pointer that cannot hover. A tablet with a trackpad reports otherwise. */
+const TOUCH = '(pointer: coarse) and (hover: none)'
+
+function useMediaQuery(query: string): boolean {
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      const list = globalThis.matchMedia?.(query)
+      list?.addEventListener('change', onChange)
+      return () => list?.removeEventListener('change', onChange)
+    },
+    [query],
+  )
+  return useSyncExternalStore(
+    subscribe,
+    () => globalThis.matchMedia?.(query).matches ?? false,
+    () => false,
+  )
+}
+
+const MIN_WIDTH = 240
+const MIN_HEIGHT = 160
+/** How close to the edge a dragged window has to get before it takes that half. */
+const SNAP_MARGIN = 56
+
+/** The part of the stage windows are arranged in: inside its padding, with its gap. */
+function arrangementArea(stage: HTMLElement) {
+  const style = getComputedStyle(stage)
+  const left = parseFloat(style.paddingLeft) || 0
+  const right = parseFloat(style.paddingRight) || 0
+  const top = parseFloat(style.paddingTop) || 0
+  const bottom = parseFloat(style.paddingBottom) || 0
+  const gap = parseFloat(style.columnGap) || 0
+  return { x: left, y: top, width: stage.clientWidth - left - right, height: stage.clientHeight - top - bottom, gap }
+}
+
+const halfFrame = (stage: HTMLElement, side: 'start' | 'end'): Frame => {
+  const area = arrangementArea(stage)
+  const width = (area.width - area.gap) / 2
+  return { x: side === 'start' ? area.x : area.x + width + area.gap, y: area.y, width, height: area.height }
+}
+
+export function Desktop({ renderWindow, title, actions, empty, loading, failed, layout = 'auto', className }: DesktopProps) {
+  const desk = useDesk()
+  const state = useDeskState()
+  const stage = useRef<HTMLDivElement>(null)
+  const touch = useMediaQuery(TOUCH)
+  const mode: DeskLayout = layout === 'auto' ? (touch ? 'fullscreen' : 'desktop') : layout
+
+  useLayoutEffect(() => {
+    desk.setStage(() => ({ width: stage.current?.clientWidth ?? 1024, height: stage.current?.clientHeight ?? 768 }))
+  }, [desk])
+
+  useEffect(() => (stage.current ? addDeskCommands(stage.current, desk) : undefined), [desk])
+
+  // Arrange lays every window out once, as free windows that can be moved again straight away.
+  useEffect(() => {
+    const element = stage.current
+    if (!element || mode !== 'desktop') return undefined
+    return addCommandHandler(
+      element,
+      DeskCommands.arrange,
+      () => {
+        const { windows, stack } = desk.getState()
+        const [focused, previous] = [stack.at(-1), stack.at(-2)]
+        if (windows.length === 1) {
+          if (focused) desk.fill(focused)
+          return
+        }
+        const frames = arrangement(
+          windows.map(w => w.id),
+          focused ?? null,
+          previous ?? null,
+          arrangementArea(element),
+          { minWidth: MIN_WIDTH, minHeight: MIN_HEIGHT },
+        )
+        desk.placeAll(frames)
+        // Windows that cascade come in front of the half they cascade over; the focused window stays in front of all.
+        if (previous) desk.focus(previous)
+        windows.forEach(w => w.id !== focused && w.id !== previous && desk.focus(w.id))
+        if (focused) desk.focus(focused)
+      },
+      {
+        enabled: () => {
+          const { windows } = desk.getState()
+          return windows.length > 1 || windows.some(w => w.mode === 'floating')
+        },
+      },
+    )
+  }, [desk, mode])
+
+  const focused = focusedId(state)
+
+  // Keyboard focus follows the key window, so commands and typing reach the window the person just chose.
+  // Not on first render: loading a page should not pull focus away from wherever the browser put it.
+  const previousFocus = useRef<WindowId | null | undefined>(undefined)
+  useEffect(() => {
+    const before = previousFocus.current
+    previousFocus.current = focused
+    if (before === undefined || before === focused || !focused || !stage.current) return
+    const element = windowElement(stage.current, focused)
+    if (element instanceof HTMLElement && !element.contains(document.activeElement)) element.focus({ preventScroll: true })
+  }, [focused])
+
+  return (
+    <div
+      ref={stage}
+      className={['desk-stage', className].filter(Boolean).join(' ')}
+      data-layout={mode}
+      {...{ [STAGE_ATTRIBUTE]: '' }}
+    >
+      {state.windows.length === 0 && empty}
+      {state.windows.map(window => (
+        <WindowView
+          key={window.id}
+          window={window}
+          layout={mode}
+          depth={state.stack.indexOf(window.id)}
+          focused={window.id === focused}
+          // One window at a time: the rest stay mounted, keeping their state, and simply wait offstage.
+          hidden={mode === 'fullscreen' && window.id !== focused}
+          title={title(window.id)}
+          actions={actions?.(window.id)}
+        >
+          {/* Memoised on the id and the render function: moving or focusing a window
+              re-renders its chrome, never the app's content inside it. */}
+          <WindowContent id={window.id} render={renderWindow} loading={loading} failed={failed} />
+        </WindowView>
+      ))}
+    </div>
+  )
+}
+
+interface WindowContentProps {
+  readonly id: WindowId
+  readonly render: (id: WindowId) => ReactNode
+  readonly loading: WindowLoading | undefined
+  readonly failed: WindowFailed | undefined
+}
+
+// Each window loads and fails on its own: one fetching its code, or throwing, never blanks another.
+const WindowContent = memo(function WindowContent({ id, render, loading, failed }: WindowContentProps) {
+  return (
+    <WindowBoundary id={id} loading={loading} failed={failed}>
+      {render(id)}
+    </WindowBoundary>
+  )
+})
+
+interface WindowViewProps {
+  readonly window: DeskWindow
+  readonly layout: DeskLayout
+  readonly hidden?: boolean
+  readonly depth: number
+  readonly focused: boolean
+  readonly title: ReactNode
+  readonly actions?: ReactNode
+  readonly children: ReactNode
+}
+
+/** Moving by the title bar, or resizing from the corner or from the left, right or bottom edge. */
+type Gesture = 'move' | 'resize' | 'left' | 'right' | 'bottom'
+
+/** The frame a gesture makes of `origin` after the pointer has travelled dx, dy. */
+function reshape(gesture: Gesture, origin: Frame, dx: number, dy: number): Frame {
+  switch (gesture) {
+    case 'move':
+      return { ...origin, x: origin.x + dx, y: Math.max(0, origin.y + dy) }
+    case 'resize':
+      return { ...origin, width: Math.max(MIN_WIDTH, origin.width + dx), height: Math.max(MIN_HEIGHT, origin.height + dy) }
+    case 'right':
+      return { ...origin, width: Math.max(MIN_WIDTH, origin.width + dx) }
+    case 'bottom':
+      return { ...origin, height: Math.max(MIN_HEIGHT, origin.height + dy) }
+    case 'left': {
+      // The right edge stays put, however far the left one is pulled.
+      const shift = Math.min(dx, origin.width - MIN_WIDTH)
+      return { ...origin, x: origin.x + shift, width: origin.width - shift }
+    }
+  }
+}
+
+function WindowView({ window, layout, hidden, depth, focused, title, actions, children }: WindowViewProps) {
+  const desk = useDesk()
+  // While dragging, the frame lives here and commits once on release, so a drag
+  // re-renders one window rather than notifying every subscriber per pixel.
+  const [live, setLive] = useState<Frame | null>(null)
+  const element = useRef<HTMLElement>(null)
+  const context = useMemo(() => ({ id: window.id, element }), [window.id])
+  const titleId = `desk-title-${window.id}`
+
+  const startGesture = (gesture: Gesture) => (event: ReactPointerEvent<HTMLElement>) => {
+    if (event.button !== 0 || layout === 'fullscreen') return
+    if (gesture === 'move' && (event.target as HTMLElement).closest('button')) return
+    event.preventDefault()
+    const stageBox = event.currentTarget.closest<HTMLElement>(`[${STAGE_ATTRIBUTE}]`)?.getBoundingClientRect()
+    const windowBox = event.currentTarget.closest<HTMLElement>(`[${WINDOW_ATTRIBUTE}]`)?.getBoundingClientRect()
+    // A filled window is freed exactly where it already sits, so it does not jump under the pointer.
+    const origin: Frame =
+      window.mode === 'floating'
+        ? window.frame
+        : {
+            x: (windowBox?.left ?? 0) - (stageBox?.left ?? 0),
+            y: (windowBox?.top ?? 0) - (stageBox?.top ?? 0),
+            width: windowBox?.width ?? 480,
+            height: windowBox?.height ?? 360,
+          }
+    let pulledOut = window.mode === 'floating'
+    const startX = event.clientX
+    const startY = event.clientY
+    const handle = event.currentTarget
+    handle.setPointerCapture?.(event.pointerId)
+    const stage = handle.closest<HTMLElement>(`[${STAGE_ATTRIBUTE}]`)
+    let latest = origin
+    let snap: 'start' | 'end' | null = null
+
+    // Dragging a window against an edge offers it that half of the desk.
+    const snapAt = (clientX: number) => {
+      if (gesture !== 'move' || !stage) return null
+      const box = stage.getBoundingClientRect()
+      if (clientX - box.left < SNAP_MARGIN) return 'start' as const
+      if (box.right - clientX < SNAP_MARGIN) return 'end' as const
+      return null
+    }
+
+    const onMove = (move: PointerEvent) => {
+      const dx = move.clientX - startX
+      const dy = move.clientY - startY
+      if (!pulledOut && Math.hypot(dx, dy) > 5) {
+        pulledOut = true
+        if (window.mode === 'filled') desk.float(window.id, origin)
+      }
+      latest = reshape(gesture, origin, dx, dy)
+      setLive(latest)
+      snap = snapAt(move.clientX)
+      if (stage) {
+        if (snap) stage.dataset.snap = snap
+        else delete stage.dataset.snap
+      }
+    }
+    const onUp = () => {
+      handle.removeEventListener('pointermove', onMove)
+      handle.removeEventListener('pointerup', onUp)
+      handle.removeEventListener('pointercancel', onUp)
+      setLive(null)
+      if (stage) delete stage.dataset.snap
+      // Dropped against an edge, it takes that half of the desk — and nothing else moves.
+      if (snap && stage) desk.float(window.id, halfFrame(stage, snap))
+      else if (pulledOut && latest !== origin) desk.float(window.id, latest)
+    }
+    handle.addEventListener('pointermove', onMove)
+    handle.addEventListener('pointerup', onUp)
+    handle.addEventListener('pointercancel', onUp)
+  }
+
+  // Double-clicking a title bar, or the green control, fills the desk with the window and back — as on a Mac.
+  const zoom = () => {
+    if (layout === 'desktop') desk.toggleMode(window.id)
+  }
+
+  const frame = layout === 'desktop' ? (live ?? (window.mode === 'floating' ? window.frame : null)) : null
+  const style: CSSProperties | undefined =
+    layout !== 'desktop'
+      ? undefined
+      : frame
+        ? { left: frame.x, top: frame.y, width: frame.width, height: frame.height, zIndex: 10 + depth }
+        : { zIndex: 10 + depth }
+
+  return (
+    <WindowContext.Provider value={context}>
+      <section
+        ref={element}
+        tabIndex={-1}
+        {...{ [WINDOW_ATTRIBUTE]: window.id }}
+        className="desk-window"
+        data-mode={layout === 'fullscreen' ? 'fullscreen' : live ? 'floating' : window.mode}
+        data-hidden={hidden || undefined}
+        inert={hidden || undefined}
+        data-focused={focused || undefined}
+        data-dragging={live ? true : undefined}
+        aria-labelledby={titleId}
+        style={style}
+        onPointerDownCapture={() => {
+          if (!focused) desk.focus(window.id)
+        }}
+      >
+          <header
+          className="desk-titlebar"
+          onPointerDown={startGesture('move')}
+          onDoubleClick={event => {
+            if (!(event.target as HTMLElement).closest('button')) zoom()
+          }}
+          data-draggable={layout === 'desktop' || undefined}
+        >
+          <div className="desk-controls">
+            <button type="button" className="desk-control" data-control="close" aria-label="Close" onClick={() => desk.close(window.id)} />
+            {layout === 'desktop' && (
+              <button type="button" className="desk-control" data-control="mode" aria-label="Zoom" onClick={zoom} />
+            )}
+          </div>
+          <h2 id={titleId} className="desk-title">
+            {title}
+          </h2>
+          {actions && <div className="desk-window-actions">{actions}</div>}
+        </header>
+        <div className="desk-body">{children}</div>
+        {layout === 'desktop' && (
+          <>
+            {/* No top edge: the title bar is there, and it moves the window. */}
+            <div className="desk-edge" data-edge="left" aria-hidden="true" onPointerDown={startGesture('left')} />
+            <div className="desk-edge" data-edge="right" aria-hidden="true" onPointerDown={startGesture('right')} />
+            <div className="desk-edge" data-edge="bottom" aria-hidden="true" onPointerDown={startGesture('bottom')} />
+            <div className="desk-grip" aria-hidden="true" onPointerDown={startGesture('resize')} />
+          </>
+        )}
+      </section>
+    </WindowContext.Provider>
+  )
+}

package/src/react/Dock.tsx

@@ -0,0 +1,258 @@
+import { useEffect, useId, useRef, useState } from 'react'
+import type { KeyboardEvent, ReactNode } from 'react'
+import { focusedId, instancesOf, windowType } from '../core/desk.js'
+import type { DeskState, WindowId } from '../core/types.js'
+import { useDesk, useDeskState } from './context.js'
+
+export interface DockItem {
+  readonly id: string
+  readonly label: string
+  readonly icon: ReactNode
+  /** The window this item opens and reports as running. Defaults to the item's id. */
+  readonly window?: WindowId
+  /** One line under the label inside a stack. */
+  readonly description?: string
+  readonly badge?: ReactNode
+  /** Replaces the default of opening the item's window. */
+  readonly onSelect?: () => void
+  readonly disabled?: boolean
+}
+
+export interface DockStack {
+  readonly id: string
+  readonly label: string
+  readonly items: readonly DockItem[]
+  /** Defaults to the first four item icons, the way a folder previews its contents. */
+  readonly icon?: ReactNode
+}
+
+export type DockEntry =
+  | ({ readonly type: 'item' } & DockItem)
+  | ({ readonly type: 'stack' } & DockStack)
+  | { readonly type: 'separator'; readonly id: string }
+
+export const dockItem = (item: DockItem): DockEntry => ({ type: 'item', ...item })
+export const dockStack = (stack: DockStack): DockEntry => ({ type: 'stack', ...stack })
+export const dockSeparator = (id: string): DockEntry => ({ type: 'separator', id })
+
+export interface DockProps {
+  readonly entries: readonly DockEntry[]
+  readonly label?: string
+  /** `overlay` floats the dock over the bottom of its positioned parent; `inline` leaves layout to you. */
+  readonly placement?: 'overlay' | 'inline'
+  readonly className?: string
+}
+
+const windowOf = (item: DockItem) => item.window ?? item.id
+
+const statusOf = (state: DeskState, items: readonly DockItem[]) => {
+  const key = focusedId(state)
+  return {
+    // Any window of this kind counts: a second query window is still Query, running.
+    running: items.some(i => instancesOf(state, windowOf(i)).length > 0),
+    focused: items.some(i => key !== null && windowType(key) === windowOf(i)),
+  }
+}
+
+/** Moves focus among the buttons in a container with arrow keys, Home and End. */
+function roveFocus(event: KeyboardEvent<HTMLElement>, keys: { next: string[]; previous: string[] }) {
+  // Only this container's own buttons: the dock must not rove into an open stack, nor a stack back out.
+  const container = event.currentTarget
+  const buttons = [...container.querySelectorAll<HTMLButtonElement>('[data-rove]:not(:disabled)')].filter(
+    b => b.parentElement?.closest('[role="toolbar"], .desk-stack') === container,
+  )
+  const index = buttons.indexOf(document.activeElement as HTMLButtonElement)
+  if (index < 0) return
+  const target =
+    keys.next.includes(event.key) ? buttons[(index + 1) % buttons.length]
+    : keys.previous.includes(event.key) ? buttons[(index - 1 + buttons.length) % buttons.length]
+    : event.key === 'Home' ? buttons[0]
+    : event.key === 'End' ? buttons.at(-1)
+    : undefined
+  if (!target) return
+  event.preventDefault()
+  buttons.forEach(b => (b.tabIndex = b === target ? 0 : -1))
+  target.focus()
+}
+
+export function Dock({ entries, label = 'Dock', placement = 'overlay', className }: DockProps) {
+  const [openStack, setOpenStack] = useState<string | null>(null)
+  const firstFocusable = entries.find(e => e.type !== 'separator')?.id
+
+  return (
+    <div
+      role="toolbar"
+      aria-label={label}
+      aria-orientation="horizontal"
+      className={['desk-dock', className].filter(Boolean).join(' ')}
+      data-placement={placement}
+      onKeyDown={event => {
+        if ((event.target as HTMLElement).closest('.desk-stack')) return
+        roveFocus(event, { next: ['ArrowRight'], previous: ['ArrowLeft'] })
+      }}
+    >
+      {entries.map(entry => {
+        if (entry.type === 'separator') return <span key={entry.id} className="desk-dock-separator" role="separator" />
+        if (entry.type === 'item')
+          return <DockButton key={entry.id} item={entry} tabIndex={entry.id === firstFocusable ? 0 : -1} />
+        return (
+          <StackButton
+            key={entry.id}
+            stack={entry}
+            tabIndex={entry.id === firstFocusable ? 0 : -1}
+            open={openStack === entry.id}
+            setOpenStack={setOpenStack}
+          />
+        )
+      })}
+    </div>
+  )
+}
+
+function Badge({ children }: { readonly children: ReactNode }) {
+  return <span className="desk-dock-badge">{children}</span>
+}
+
+function DockButton({ item, tabIndex }: { readonly item: DockItem; readonly tabIndex: number }) {
+  const desk = useDesk()
+  const { running, focused } = statusOf(useDeskState(), [item])
+  return (
+    <button
+      type="button"
+      data-rove
+      tabIndex={tabIndex}
+      className="desk-dock-item"
+      aria-label={item.label}
+      data-running={running || undefined}
+      data-focused={focused || undefined}
+      disabled={item.disabled}
+      onClick={() => (item.onSelect ? item.onSelect() : desk.open(windowOf(item)))}
+    >
+      <span className="desk-dock-icon" aria-hidden="true">
+        {item.icon}
+      </span>
+      {item.badge != null && <Badge>{item.badge}</Badge>}
+      <span className="desk-dock-tip" aria-hidden="true">
+        {item.label}
+      </span>
+    </button>
+  )
+}
+
+interface StackButtonProps {
+  readonly stack: DockStack
+  readonly tabIndex: number
+  readonly open: boolean
+  /** The dock's own state setter: stable across renders, so effects below do not re-run. */
+  readonly setOpenStack: (id: string | null) => void
+}
+
+function StackButton({ stack, tabIndex, open, setOpenStack }: StackButtonProps) {
+  const desk = useDesk()
+  const state = useDeskState()
+  const { running, focused } = statusOf(state, stack.items)
+  const onOpenChange = (next: boolean) => setOpenStack(next ? stack.id : null)
+  const button = useRef<HTMLButtonElement>(null)
+  const panel = useRef<HTMLDivElement>(null)
+  const panelId = useId()
+
+  useEffect(() => {
+    if (!open) return
+    panel.current?.querySelector<HTMLButtonElement>('[data-rove]:not(:disabled)')?.focus()
+    const onPointerDown = (event: PointerEvent) => {
+      const target = event.target as Node
+      if (!panel.current?.contains(target) && !button.current?.contains(target)) setOpenStack(null)
+    }
+    document.addEventListener('pointerdown', onPointerDown)
+    return () => document.removeEventListener('pointerdown', onPointerDown)
+  }, [open, setOpenStack])
+
+  const close = () => {
+    onOpenChange(false)
+    button.current?.focus()
+  }
+
+  const select = (item: DockItem) => {
+    if (item.onSelect) item.onSelect()
+    else desk.open(windowOf(item))
+    onOpenChange(false)
+  }
+
+  const badges = stack.items.filter(i => i.badge != null).length
+
+  return (
+    <span className="desk-dock-slot">
+      <button
+        ref={button}
+        type="button"
+        data-rove
+        tabIndex={tabIndex}
+        className="desk-dock-item"
+        data-stack
+        aria-label={stack.label}
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        aria-controls={open ? panelId : undefined}
+        data-running={running || undefined}
+        data-focused={focused || undefined}
+        onClick={() => onOpenChange(!open)}
+      >
+        <span className="desk-dock-icon" aria-hidden="true">
+          {stack.icon ?? (
+            <span className="desk-dock-preview">
+              {stack.items.slice(0, 4).map(i => (
+                <span key={i.id}>{i.icon}</span>
+              ))}
+            </span>
+          )}
+        </span>
+        {badges > 0 && <Badge>{badges}</Badge>}
+        <span className="desk-dock-tip" aria-hidden="true">
+          {stack.label}
+        </span>
+      </button>
+      {open && (
+        <div
+          ref={panel}
+          id={panelId}
+          role="dialog"
+          aria-label={stack.label}
+          className="desk-stack"
+          onKeyDown={event => {
+            if (event.key === 'Escape') {
+              event.preventDefault()
+              close()
+              return
+            }
+            roveFocus(event, { next: ['ArrowRight', 'ArrowDown'], previous: ['ArrowLeft', 'ArrowUp'] })
+          }}
+        >
+          <p className="desk-stack-title">{stack.label}</p>
+          <div className="desk-stack-grid">
+            {stack.items.map(item => {
+              const status = statusOf(state, [item])
+              return (
+                <button
+                  key={item.id}
+                  type="button"
+                  data-rove
+                  className="desk-stack-item"
+                  data-running={status.running || undefined}
+                  disabled={item.disabled}
+                  onClick={() => select(item)}
+                >
+                  <span className="desk-dock-icon" aria-hidden="true">
+                    {item.icon}
+                    {item.badge != null && <Badge>{item.badge}</Badge>}
+                  </span>
+                  <span className="desk-stack-label">{item.label}</span>
+                  {item.description && <span className="desk-stack-description">{item.description}</span>}
+                </button>
+              )
+            })}
+          </div>
+        </div>
+      )}
+    </span>
+  )
+}