@liberation-data/desk 0.3.0 → 0.6.0

package/src/css/tokens.css

@@ -0,0 +1,89 @@
+/*
+ * desk — the stage and its windows. Every value reads a --desk-* token, so an
+ * app restyles the desk by redefining tokens, never by overriding selectors.
+ */
+:root {
+  --desk-ground: #eef0f4;
+  --desk-surface: #ffffff;
+  --desk-titlebar: #f6f7f9;
+  --desk-ink: #1b1f27;
+  --desk-muted: #667085;
+  --desk-rule: #dde1e8;
+  --desk-accent: #5b57f5;
+  --desk-close: #ef6b63;
+  --desk-mode: #34c47a;
+  --desk-info: #34c47a;
+  --desk-radius: 12px;
+  --desk-gap: 12px;
+  --desk-padding: 12px;
+  --desk-shadow: 0 1px 2px rgb(16 24 40 / 6%), 0 12px 32px rgb(16 24 40 / 10%);
+  --desk-shadow-floating: 0 2px 4px rgb(16 24 40 / 8%), 0 24px 60px rgb(16 24 40 / 22%);
+  --desk-font: system-ui, -apple-system, "Segoe UI", sans-serif;
+  --desk-font-mono: ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, monospace;
+
+  /* The spacing scale (HIG.md §2). Nothing between these values. */
+  --desk-space-1: 4px;
+  --desk-space-2: 8px;
+  --desk-space-3: 12px;
+  --desk-space-4: 16px;
+  --desk-space-5: 24px;
+  --desk-space-6: 32px;
+  --desk-space-7: 48px;
+
+  /* State, kept apart from the accent. */
+  --desk-ok: #2f9e68;
+  --desk-warn: #b7791f;
+  --desk-bad: #c6483f;
+
+  --desk-control-height: 28px;
+  --desk-control-height-small: 22px;
+  --desk-control-radius: 7px;
+  --desk-field-bg: #ffffff;
+  --desk-on-accent: #ffffff;
+  --desk-ease: cubic-bezier(.32, .72, 0, 1);
+  --desk-dock-size: 48px;
+  --desk-dock-glass: rgb(255 255 255 / 72%);
+  --desk-dock-icon: linear-gradient(160deg, #ffffff, #eceff5);
+  --desk-badge: #ef4444;
+  --desk-badge-ink: #ffffff;
+  /* Room the stage leaves at the bottom for an overlay dock. */
+  --desk-inset-bottom: 0px;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --desk-ground: #07090f;
+    --desk-surface: #101828;
+    --desk-titlebar: #0b111d;
+    --desk-ink: #e6e6e6;
+    --desk-muted: #99a1af;
+    --desk-rule: #1e2939;
+    --desk-shadow: 0 12px 32px rgb(0 0 0 / 45%);
+    --desk-shadow-floating: 0 30px 80px rgb(0 0 0 / 70%);
+    --desk-dock-glass: rgb(11 18 32 / 62%);
+    --desk-dock-icon: linear-gradient(160deg, #1a2338, #0e1526);
+    --desk-ok: #3ecf8e;
+    --desk-info: #3ecf8e;
+    --desk-warn: #fbbf24;
+    --desk-bad: #f87171;
+    --desk-field-bg: rgb(0 0 0 / 35%);
+  }
+}
+
+:root[data-theme="dark"] {
+  --desk-ground: #07090f;
+  --desk-surface: #101828;
+  --desk-titlebar: #0b111d;
+  --desk-ink: #e6e6e6;
+  --desk-muted: #99a1af;
+  --desk-rule: #1e2939;
+  --desk-shadow: 0 12px 32px rgb(0 0 0 / 45%);
+  --desk-shadow-floating: 0 30px 80px rgb(0 0 0 / 70%);
+  --desk-dock-glass: rgb(11 18 32 / 62%);
+  --desk-dock-icon: linear-gradient(160deg, #1a2338, #0e1526);
+  --desk-ok: #3ecf8e;
+  --desk-info: #3ecf8e;
+  --desk-warn: #fbbf24;
+  --desk-bad: #f87171;
+  --desk-field-bg: rgb(0 0 0 / 35%);
+}

package/src/css/windows.css

@@ -0,0 +1,320 @@
+.desk-stage {
+  position: relative;
+  box-sizing: border-box;
+  height: 100%;
+  min-height: 0;
+  padding: var(--desk-padding);
+  padding-bottom: calc(var(--desk-padding) + var(--desk-inset-bottom));
+  display: grid;
+  grid-template: minmax(0, 1fr) / minmax(0, 1fr);
+  gap: var(--desk-gap);
+  overflow: hidden;
+  background: var(--desk-ground);
+  color: var(--desk-ink);
+  font-family: var(--desk-font);
+}
+
+.desk-window {
+  /* Filled windows fill the stage inside its padding, layered in the order they were used. */
+  position: absolute;
+  top: var(--desk-padding);
+  right: var(--desk-padding);
+  bottom: calc(var(--desk-padding) + var(--desk-inset-bottom));
+  left: var(--desk-padding);
+  box-sizing: border-box;
+  min-width: 0;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  background: var(--desk-surface);
+  border: 1px solid var(--desk-rule);
+  border-radius: var(--desk-radius);
+  box-shadow: var(--desk-shadow);
+  overflow: hidden;
+  transition: border-color .15s var(--desk-ease), box-shadow .15s var(--desk-ease);
+}
+
+.desk-window:focus {
+  /* The key window is already marked by its border; a ring on the whole window would be noise. */
+  outline: none;
+}
+
+.desk-window[data-focused] {
+  border-color: color-mix(in srgb, var(--desk-accent) 45%, var(--desk-rule));
+}
+
+.desk-window[data-hidden] {
+  display: none;
+}
+
+/* One window at a time: it fills the stage, and the zoom control is not offered. */
+.desk-stage[data-layout="fullscreen"] .desk-window {
+  position: static;
+  inset: auto;
+  grid-area: 1 / 1;
+}
+
+.desk-window[data-mode="floating"] {
+  right: auto;
+  bottom: auto;
+  box-shadow: var(--desk-shadow-floating);
+}
+
+.desk-window[data-dragging] {
+  transition: none;
+  user-select: none;
+}
+
+.desk-titlebar {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 12px;
+  background: var(--desk-titlebar);
+  border-bottom: 1px solid var(--desk-rule);
+  user-select: none;
+}
+
+.desk-titlebar[data-draggable] {
+  cursor: grab;
+  touch-action: none;
+}
+
+.desk-window[data-dragging] .desk-titlebar {
+  cursor: grabbing;
+}
+
+.desk-controls {
+  display: flex;
+  gap: 7px;
+}
+
+.desk-control {
+  width: 12px;
+  height: 12px;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  cursor: pointer;
+  background: var(--desk-rule);
+}
+
+.desk-window[data-focused] .desk-control[data-control="close"],
+.desk-control[data-control="close"]:hover {
+  background: var(--desk-close);
+}
+
+.desk-window[data-focused] .desk-control[data-control="mode"],
+.desk-control[data-control="mode"]:hover {
+  background: var(--desk-mode);
+}
+
+.desk-control:focus-visible {
+  outline: 2px solid var(--desk-accent);
+  outline-offset: 2px;
+}
+
+.desk-title {
+  margin: 0;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.desk-window:not([data-focused]) .desk-title {
+  color: var(--desk-muted);
+}
+
+.desk-window-note {
+  margin: 0 0 0 auto;
+  min-width: 0;
+  /* The title is what the window IS; the note is what it is looking at. In a narrow window the note
+     gives up its room first, and is cut before the title is. */
+  flex: 0 999 auto;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 11.5px;
+  color: var(--desk-muted);
+}
+
+/* The note gives up the spare room; the (i) keeps its place at the end of the bar. */
+.desk-window-note + .desk-window-info {
+  margin-left: var(--desk-space-2);
+}
+
+.desk-window-info {
+  margin-left: auto;
+}
+
+.desk-window-note ~ .desk-window-info {
+  margin-left: var(--desk-space-2);
+}
+
+.desk-window-info + .desk-window-actions,
+.desk-window-note + .desk-window-actions {
+  margin-left: var(--desk-space-1);
+}
+
+.desk-window-actions {
+  margin-left: auto;
+  display: flex;
+  align-items: center;
+  gap: var(--desk-space-1);
+}
+
+.desk-body {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}
+
+.desk-window-status {
+  box-sizing: border-box;
+  height: 100%;
+  min-height: 120px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--desk-space-2);
+  padding: var(--desk-space-4);
+  text-align: center;
+  color: var(--desk-muted);
+  font-size: 13px;
+}
+
+.desk-window-status b {
+  color: var(--desk-ink);
+  font-weight: 600;
+}
+
+.desk-window-status-detail {
+  max-width: 40ch;
+  font-size: 12px;
+}
+
+/* Edges a window resizes from. Inside the window, so nothing clips them. */
+.desk-edge {
+  position: absolute;
+  touch-action: none;
+}
+
+.desk-edge[data-edge="left"],
+.desk-edge[data-edge="right"] {
+  top: 0;
+  bottom: 0;
+  width: 5px;
+  cursor: ew-resize;
+}
+
+.desk-edge[data-edge="left"] {
+  left: 0;
+}
+
+.desk-edge[data-edge="right"] {
+  right: 0;
+}
+
+.desk-edge[data-edge="bottom"] {
+  left: 0;
+  right: 0;
+  bottom: 0;
+  height: 5px;
+  cursor: ns-resize;
+}
+
+.desk-grip {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  width: 16px;
+  height: 16px;
+  cursor: nwse-resize;
+  touch-action: none;
+}
+
+/* Where a dragged window would land if it were dropped now. */
+.desk-stage[data-snap]::after {
+  content: "";
+  position: absolute;
+  top: var(--desk-padding);
+  bottom: calc(var(--desk-padding) + var(--desk-inset-bottom));
+  width: calc(50% - var(--desk-padding) - var(--desk-gap) / 2);
+  border: 2px solid var(--desk-accent);
+  border-radius: var(--desk-radius);
+  background: color-mix(in srgb, var(--desk-accent) 14%, transparent);
+  pointer-events: none;
+  z-index: 5;
+}
+
+.desk-stage[data-snap="start"]::after {
+  left: var(--desk-padding);
+}
+
+.desk-stage[data-snap="end"]::after {
+  right: var(--desk-padding);
+}
+
+/* ── The inside of a window: controls that stay, content that scrolls ── */
+
+.desk-pane {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+}
+
+.desk-pane-header,
+.desk-pane-footer {
+  flex: none;
+}
+
+/* The only part that scrolls, so the toolbar never leaves with the content. */
+.desk-pane-body {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}
+
+.desk-pane-body:focus-visible {
+  outline: 2px solid var(--desk-accent);
+  outline-offset: -2px;
+}
+
+/* A window whose whole content is a pane does not scroll itself: the pane's middle does. */
+.desk-body:has(> .desk-pane) {
+  overflow: hidden;
+}
+
+.desk-toolbar {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: var(--desk-space-2);
+  /* One centre line for everything in the row, whatever each control's own height is. */
+  min-height: calc(var(--desk-control-height) + var(--desk-space-2) * 2);
+  padding: var(--desk-space-2) var(--desk-space-3);
+  border-bottom: 1px solid var(--desk-rule);
+}
+
+.desk-toolbar > *,
+.desk-toolbar-trailing > * {
+  flex: none;
+}
+
+.desk-toolbar .desk-grow {
+  flex: 1 1 140px;
+  min-width: 0;
+}
+
+.desk-toolbar-trailing {
+  margin-left: auto;
+  display: flex;
+  align-items: center;
+  gap: var(--desk-space-2);
+}

package/src/react/Desktop.tsx

@@ -2,8 +2,10 @@ import { memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useStat
 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 { Desk } from '../core/desk.js'
 import type { DeskWindow, Frame, WindowId } from '../core/types.js'
 import { arrangement } from './arrange.js'
+import { InfoTip } from './infoTip.js'
 import { useDesk, useDeskState, WindowContext } from './context.js'
 import { WindowBoundary } from './windowBoundary.js'
 import type { WindowFailed, WindowLoading } from './windowBoundary.js'
@@ -19,6 +21,12 @@ export interface DesktopProps {
    * gives way to the actions and disappears before the title does when the window is narrow.
    */
   readonly note?: (id: WindowId) => ReactNode
+  /**
+   * What this window is, behind an (i) at the end of its title bar — the same place in every window,
+   * so a person who wonders what they are looking at always knows where to ask. Explanation only: a
+   * warning, or anything that changes what someone is about to do, belongs in the window itself.
+   */
+  readonly info?: (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. */
@@ -76,7 +84,7 @@ const halfFrame = (stage: HTMLElement, side: 'start' | 'end'): Frame => {
   return { x: side === 'start' ? area.x : area.x + width + area.gap, y: area.y, width, height: area.height }
 }
 
-export function Desktop({ renderWindow, title, note, actions, empty, loading, failed, layout = 'auto', className }: DesktopProps) {
+export function Desktop({ renderWindow, title, note, info, actions, empty, loading, failed, layout = 'auto', className }: DesktopProps) {
   const desk = useDesk()
   const state = useDeskState()
   const stage = useRef<HTMLDivElement>(null)
@@ -87,6 +95,51 @@ export function Desktop({ renderWindow, title, note, actions, empty, loading, fa
     desk.setStage(() => ({ width: stage.current?.clientWidth ?? 1024, height: stage.current?.clientHeight ?? 768 }))
   }, [desk])
 
+  /*
+   * The desk changing size is not a layout decision, but it can undo one: unplug an external
+   * display and the windows you spread across it are past the edge of the laptop screen, where
+   * nothing can drag them back. They are brought in; plug the display back in and they go out
+   * again exactly as they were.
+   *
+   * Filled windows need none of this — they are whatever size the desk is — so a desk of only
+   * filled windows never commits anything here.
+   */
+  useEffect(() => {
+    const element = stage.current
+    if (!element || mode !== 'desktop') return undefined
+    let frame = 0
+    // Once per paint: dragging the browser window's edge fires this continuously.
+    const refit = () => {
+      cancelAnimationFrame(frame)
+      frame = requestAnimationFrame(() => {
+        const fit = desk.fitToStage()
+        /*
+         * One window that no longer fits is brought in and made smaller, and that is enough. Two or
+         * more means the layout itself is gone: each was clamped on its own, so windows that sat
+         * side by side now sit on top of each other, and the desk is left looking like one window.
+         * At that point it is laid out the way Arrange would — which is a layout for THIS screen,
+         * while the frames from the big one are remembered and come back with it.
+         */
+        if (fit.squeezed.length > 1) arrangeNow(desk, element)
+      })
+    }
+    // The stage can change size without the window doing so — a sidebar opening beside it — so the
+    // element is watched where that can be watched, and the window is the fallback where it cannot.
+    if (typeof ResizeObserver === 'undefined') {
+      addEventListener('resize', refit)
+      return () => {
+        cancelAnimationFrame(frame)
+        removeEventListener('resize', refit)
+      }
+    }
+    const observer = new ResizeObserver(refit)
+    observer.observe(element)
+    return () => {
+      cancelAnimationFrame(frame)
+      observer.disconnect()
+    }
+  }, [desk, mode])
+
   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.
@@ -96,26 +149,7 @@ export function Desktop({ renderWindow, title, note, actions, empty, loading, fa
     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)
-      },
+      () => arrangeNow(desk, element),
       {
         enabled: () => {
           const { windows } = desk.getState()
@@ -157,6 +191,7 @@ export function Desktop({ renderWindow, title, note, actions, empty, loading, fa
           hidden={mode === 'fullscreen' && window.id !== focused}
           title={title(window.id)}
           note={note?.(window.id)}
+          info={info?.(window.id)}
           actions={actions?.(window.id)}
         >
           {/* Memoised on the id and the render function: moving or focusing a window
@@ -192,11 +227,34 @@ interface WindowViewProps {
   readonly focused: boolean
   readonly title: ReactNode
   readonly note?: ReactNode
+  readonly info?: 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. */
+/** Lays every open window out at once: what Window → Arrange does, and what a shrunken desk needs. */
+function arrangeNow(desk: Desk, element: HTMLElement) {
+  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)
+}
+
 type Gesture = 'move' | 'resize' | 'left' | 'right' | 'bottom'
 
 /** The frame a gesture makes of `origin` after the pointer has travelled dx, dy. */
@@ -218,7 +276,7 @@ function reshape(gesture: Gesture, origin: Frame, dx: number, dy: number): Frame
   }
 }
 
-function WindowView({ window, layout, hidden, depth, focused, title, note, actions, children }: WindowViewProps) {
+function WindowView({ window, layout, hidden, depth, focused, title, note, info, 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.
@@ -340,6 +398,15 @@ function WindowView({ window, layout, hidden, depth, focused, title, note, actio
             {title}
           </h2>
           {note != null && note !== false && <p className="desk-window-note">{note}</p>}
+          {info != null && info !== false && (
+            <InfoTip
+              className="desk-window-info"
+              label={typeof title === 'string' ? `About ${title}` : 'About this window'}
+              align="end"
+            >
+              {info}
+            </InfoTip>
+          )}
           {actions && <div className="desk-window-actions">{actions}</div>}
         </header>
         <div className="desk-body">{children}</div>