@liberation-data/desk 0.1.0

package/src/core/desk.ts

@@ -0,0 +1,229 @@
+import type {
+  CascadeOptions,
+  DeskOptions,
+  DeskState,
+  DeskWindow,
+  Frame,
+  OpenOptions,
+  Size,
+  WindowId,
+} from './types.js'
+
+export interface Desk {
+  getState(): DeskState
+  subscribe(listener: (state: DeskState) => void): () => void
+  /** Opens a window filling the desk, over the ones already open, or brings it to the front if it is open. */
+  open(id: WindowId, options?: OpenOptions): void
+  /** Opens another window of the same kind — `query#2` beside `query` — and returns its id. */
+  openInstance(type: string, options?: OpenOptions): WindowId
+  close(id: WindowId): void
+  closeAll(): void
+  focus(id: WindowId): void
+  /** Frees a window: where it last was, or at the next step of the cascade. Given a frame, puts it there. */
+  float(id: WindowId, frame?: Frame): void
+  /** Makes a window fill the desk, remembering where it was so freeing it again puts it back. */
+  fill(id: WindowId): void
+  /** Zooms: fills a free window, or frees a filled one. */
+  toggleMode(id: WindowId): void
+  /** Places windows exactly where they are given, as free windows. Arrange uses it. */
+  placeAll(frames: Readonly<Record<WindowId, Frame>>): void
+  /** Replaces the whole state, e.g. from a URL. Unknown shapes are normalised, not trusted. */
+  restore(state: DeskState): void
+  setStage(stage: () => Size): void
+}
+
+export const EMPTY: DeskState = { windows: [], stack: [] }
+
+const DEFAULT_CASCADE: CascadeOptions = {
+  maxWidth: 720,
+  maxHeight: 520,
+  margin: 16,
+  step: { x: 32, y: 28 },
+  wrap: 6,
+}
+
+const DEFAULT_STAGE: Size = { width: 1024, height: 768 }
+
+export const focusedId = (state: DeskState): WindowId | null => state.stack.at(-1) ?? null
+
+/**
+ * Two windows onto the same thing — a second query beside the first — are the
+ * same kind with different ids: `query`, then `query#2`. The part before the
+ * `#` says what to render; the whole id says which one this is.
+ */
+export const windowType = (id: WindowId): string => id.split('#')[0] ?? id
+
+export const instancesOf = (state: DeskState, type: string): readonly DeskWindow[] =>
+  state.windows.filter(w => windowType(w.id) === type)
+
+export const isOpen = (state: DeskState, id: WindowId): boolean => state.windows.some(w => w.id === id)
+
+export function cascadeFrame(floatingCount: number, stage: Size, options: CascadeOptions = DEFAULT_CASCADE): Frame {
+  const width = Math.max(0, Math.min(options.maxWidth, stage.width - options.margin * 2))
+  const height = Math.max(0, Math.min(options.maxHeight, stage.height - options.margin * 2))
+  const n = floatingCount % options.wrap
+  return {
+    x: Math.min(options.margin + n * options.step.x, Math.max(0, stage.width - width - options.margin)),
+    y: Math.min(options.margin + n * options.step.y, Math.max(0, stage.height - height - options.margin)),
+    width,
+    height,
+  }
+}
+
+/** Which cascade step a frame sits on, or -1 once it has been dragged off one. */
+export function cascadeSlot(frame: Frame, stage: Size, options: CascadeOptions = DEFAULT_CASCADE): number {
+  for (let slot = 0; slot < options.wrap; slot++) {
+    const candidate = cascadeFrame(slot, stage, options)
+    if (candidate.x === frame.x && candidate.y === frame.y) return slot
+  }
+  return -1
+}
+
+/**
+ * The next free step of the cascade. Counting floating windows is not enough: a
+ * window closed from the middle frees its step, and the count wraps — either way
+ * a new window would open exactly on top of one already there, hiding it.
+ */
+export function nextCascadeFrame(windows: readonly DeskWindow[], stage: Size, options: CascadeOptions = DEFAULT_CASCADE): Frame {
+  const taken = new Set(
+    windows.flatMap(w => (w.mode === 'floating' ? [cascadeSlot(w.frame, stage, options)] : [])),
+  )
+  for (let slot = 0; slot < options.wrap; slot++) if (!taken.has(slot)) return cascadeFrame(slot, stage, options)
+  return cascadeFrame(taken.size % options.wrap, stage, options)
+}
+
+/** Drops duplicate ids and makes the stack agree with the windows. */
+export function normalise(state: DeskState): DeskState {
+  const windows = state.windows.filter((w, i, all) => all.findIndex(o => o.id === w.id) === i)
+  const ids = new Set(windows.map(w => w.id))
+  const stacked = state.stack.filter((id, i, all) => ids.has(id) && all.indexOf(id) === i)
+  const unstacked = windows.map(w => w.id).filter(id => !stacked.includes(id))
+  return { windows, stack: [...unstacked, ...stacked] }
+}
+
+export function createDesk(options: DeskOptions = {}): Desk {
+  const cascade: CascadeOptions = { ...DEFAULT_CASCADE, ...options.cascade }
+  let stage = options.stage ?? (() => DEFAULT_STAGE)
+  let state = normalise(options.initial ?? EMPTY)
+  const listeners = new Set<(state: DeskState) => void>()
+
+  const commit = (next: DeskState) => {
+    if (next === state) return
+    state = next
+    listeners.forEach(listener => listener(state))
+  }
+
+  const toFront = (s: DeskState, id: WindowId): DeskState =>
+    s.stack.at(-1) === id ? s : { ...s, stack: [...s.stack.filter(x => x !== id), id] }
+
+  const nextFrame = (s: DeskState) => nextCascadeFrame(s.windows, stage(), cascade)
+
+  const replace = (s: DeskState, window: DeskWindow): DeskState => ({
+    ...s,
+    windows: s.windows.map(w => (w.id === window.id ? window : w)),
+  })
+
+  const find = (id: WindowId) => state.windows.find(w => w.id === id)
+
+  /** Where each window was last free, so filling it and freeing it again is not a surprise. */
+  const remembered = new Map<WindowId, Frame>()
+
+  /** A remembered frame is only worth restoring while it still lands on this screen. */
+  const fits = (frame: Frame | undefined) => {
+    if (!frame) return undefined
+    const { width, height } = stage()
+    return frame.x + 40 <= width && frame.y + 20 <= height && frame.x >= 0 && frame.y >= 0 ? frame : undefined
+  }
+
+  // Plain functions rather than methods, so `const { open } = desk` works.
+  const float = (id: WindowId, frame?: Frame) => {
+    const window = find(id)
+    if (!window) return
+    if (window.mode === 'floating' && !frame) return
+    const next = frame ?? fits(remembered.get(id)) ?? nextFrame(state)
+    if (frame) remembered.set(id, frame)
+    commit(toFront(replace(state, { id, mode: 'floating', frame: next }), id))
+  }
+
+  const fill = (id: WindowId) => {
+    const window = find(id)
+    if (!window || window.mode === 'filled') return
+    remembered.set(id, window.frame)
+    commit(toFront(replace(state, { id, mode: 'filled' }), id))
+  }
+
+  return {
+    getState: () => state,
+
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+
+    open(id, opts = {}) {
+      if (find(id)) {
+        commit(toFront(state, id))
+        return
+      }
+      const mode = opts.mode ?? (opts.frame ? 'floating' : 'filled')
+      const window: DeskWindow = mode === 'filled' ? { id, mode } : { id, mode, frame: opts.frame ?? nextFrame(state) }
+      commit({ windows: [...state.windows, window], stack: [...state.stack, id] })
+    },
+
+    openInstance(type, opts = {}) {
+      const taken = new Set(state.windows.map(w => w.id))
+      let id = type
+      for (let n = 2; taken.has(id); n++) id = `${type}#${n}`
+      this.open(id, opts)
+      return id
+    },
+
+    close(id) {
+      if (find(id)) commit({ windows: state.windows.filter(w => w.id !== id), stack: state.stack.filter(x => x !== id) })
+    },
+
+    closeAll() {
+      if (state.windows.length) commit(EMPTY)
+    },
+
+    focus(id) {
+      if (find(id)) commit(toFront(state, id))
+    },
+
+    float,
+    fill,
+
+    toggleMode(id) {
+      const window = find(id)
+      if (!window) return
+      if (window.mode === 'filled') float(id)
+      else fill(id)
+    },
+
+    placeAll(frames) {
+      const ids = Object.keys(frames)
+      if (!ids.length) return
+      ids.forEach(id => {
+        const frame = frames[id]
+        if (frame) remembered.set(id, frame)
+      })
+      commit({
+        ...state,
+        windows: state.windows.map(w => {
+          const frame = frames[w.id]
+          return frame ? { id: w.id, mode: 'floating' as const, frame } : w
+        }),
+      })
+    },
+
+    restore(next) {
+      commit(normalise(next))
+    },
+
+    setStage(next) {
+      stage = next
+    },
+  }
+}

package/src/core/events.ts

@@ -0,0 +1,99 @@
+import type { WindowId } from './types.js'
+
+/*
+ * Windows talk to each other by publishing what happened, not by calling each
+ * other: Rides says a ride was chosen, and whoever cares — the map, a chat
+ * window — answers. Nobody holds a reference to anybody.
+ *
+ * Topics are dotted names. A subscriber can take a whole branch with `ride.*`,
+ * or everything with `*`.
+ */
+
+export interface DeskEvent<T = unknown> {
+  readonly topic: string
+  readonly payload: T
+  /** The window it came from, when it came from one. */
+  readonly from: WindowId | null
+  readonly at: number
+}
+
+export type EventHandler<T = unknown> = (event: DeskEvent<T>) => void
+
+export interface SubscribeOptions {
+  /**
+   * Deliver the last event on this topic straight away, if there was one. A window
+   * opened by the event that concerns it would otherwise miss it by a frame.
+   */
+  readonly replay?: boolean
+}
+
+export interface Bus {
+  publish<T>(topic: string, payload: T, options?: { readonly from?: WindowId | null }): DeskEvent<T>
+  subscribe<T>(topic: string, handler: EventHandler<T>, options?: SubscribeOptions): () => void
+  /** The last event on a topic, if one has been published. */
+  last<T>(topic: string): DeskEvent<T> | undefined
+}
+
+export function topicMatches(pattern: string, topic: string): boolean {
+  if (pattern === '*' || pattern === topic) return true
+  if (!pattern.endsWith('.*')) return false
+  const branch = pattern.slice(0, -2)
+  return topic === branch || topic.startsWith(`${branch}.`)
+}
+
+export function createBus(): Bus {
+  const subscribers = new Set<{ pattern: string; handler: EventHandler<never> }>()
+  const latest = new Map<string, DeskEvent<unknown>>()
+
+  return {
+    publish(topic, payload, options = {}) {
+      const event: DeskEvent<typeof payload> = { topic, payload, from: options.from ?? null, at: Date.now() }
+      latest.set(topic, event as DeskEvent<unknown>)
+      // Copy first: a handler may subscribe or unsubscribe while this one is being delivered.
+      for (const subscriber of [...subscribers]) {
+        if (subscribers.has(subscriber) && topicMatches(subscriber.pattern, topic)) {
+          ;(subscriber.handler as EventHandler<typeof payload>)(event)
+        }
+      }
+      return event
+    },
+
+    subscribe(topic, handler, options = {}) {
+      const subscriber = { pattern: topic, handler: handler as EventHandler<never> }
+      subscribers.add(subscriber)
+      if (options.replay) {
+        const previous = [...latest.values()]
+          .filter(event => topicMatches(topic, event.topic))
+          .sort((a, b) => a.at - b.at)
+          .at(-1)
+        if (previous) (handler as EventHandler<unknown>)(previous)
+      }
+      return () => {
+        subscribers.delete(subscriber)
+      }
+    },
+
+    last(topic) {
+      return latest.get(topic) as DeskEvent<never> | undefined
+    },
+  }
+}
+
+/* ── Typed input: text with no target, which goes to the key window ── */
+
+export const InputCommands = {
+  /** Brings up the bar. A menu item can perform this, as a shortcut does. */
+  open: 'desk.input.open',
+  /** Sent with the text. A window that takes typed input answers this. */
+  submit: 'desk.input.submit',
+  /** Asks the chain how the bar should present itself for the key window. */
+  describe: 'desk.input.describe',
+} as const
+
+/** Filled in by whichever responder answers `desk.input.describe`. */
+export interface InputDescription {
+  placeholder?: string
+  /** What the text will reach, for the bar to show: "Rides", "Chat". */
+  target?: string
+  disabled?: boolean
+}

package/src/core/index.ts

@@ -0,0 +1,43 @@
+export {
+  createDesk,
+  cascadeFrame,
+  cascadeSlot,
+  focusedId,
+  instancesOf,
+  isOpen,
+  nextCascadeFrame,
+  normalise,
+  windowType,
+  EMPTY,
+} from './desk.js'
+export type { Desk } from './desk.js'
+export {
+  addCommandHandler,
+  addDeskCommands,
+  canPerform,
+  chainStart,
+  DeskCommands,
+  perform,
+  STAGE_ATTRIBUTE,
+  WINDOW_ATTRIBUTE,
+  windowElement,
+} from './commands.js'
+export type { ChainOptions, CommandHandler, CommandId, CommandOptions } from './commands.js'
+export { createBus, InputCommands, topicMatches } from './events.js'
+export type { Bus, DeskEvent, EventHandler, InputDescription, SubscribeOptions } from './events.js'
+export { bindShortcuts, formatShortcut, isApplePlatform, isInstalledApp, matchesShortcut, parseShortcut } from './shortcuts.js'
+export type { Keymap, Shortcut, ShortcutOptions } from './shortcuts.js'
+export { parse, serialize, syncWithLocation } from './location.js'
+export { isTitleCase, titleCase } from './titles.js'
+export type { LocationEnv, LocationOptions } from './location.js'
+export type {
+  CascadeOptions,
+  DeskOptions,
+  DeskState,
+  DeskWindow,
+  Frame,
+  OpenOptions,
+  Size,
+  WindowId,
+  WindowMode,
+} from './types.js'

package/src/core/location.ts

@@ -0,0 +1,127 @@
+import { cascadeFrame, focusedId, normalise } from './desk.js'
+import type { Desk } from './desk.js'
+import type { DeskState, DeskWindow, Size, WindowId } from './types.js'
+
+/*
+ * The URL carries which windows are open, which are free, and which has focus —
+ * never frames. A shared link should open the same things, not reproduce
+ * someone else's window positions on a different screen.
+ *
+ *   #w=notes,clock~,inspector&f=clock
+ *
+ * `~` marks a free window; the others fill the desk. `f` names the focused window.
+ */
+
+const FLOAT = '~'
+
+const warned = new Set<string>()
+/** Said once per message: a warning on every parse would be noise, not help. */
+const warnOnce = (message: string) => {
+  if (warned.has(message)) return
+  warned.add(message)
+  console.warn(message)
+}
+
+export interface LocationOptions {
+  /** Hash parameter that holds the windows. Default `w`. */
+  readonly key?: string
+  /** Hash parameter that holds the focused window. Default `f`. */
+  readonly focusKey?: string
+  /** Ids the app can render. Anything else in a URL is dropped. */
+  readonly isKnown?: (id: WindowId) => boolean
+}
+
+export function serialize(state: DeskState, options: LocationOptions = {}): URLSearchParams {
+  const params = new URLSearchParams()
+  if (!state.windows.length) return params
+  params.set(
+    options.key ?? 'w',
+    state.windows.map(w => `${encodeURIComponent(w.id)}${w.mode === 'floating' ? FLOAT : ''}`).join(','),
+  )
+  const focused = focusedId(state)
+  if (focused) params.set(options.focusKey ?? 'f', focused)
+  return params
+}
+
+export function parse(params: URLSearchParams, stage: Size, options: LocationOptions = {}): DeskState {
+  const known =
+    options.isKnown ??
+    (id => {
+      // Without `isKnown` a stale or hand-edited link opens ids the app cannot render.
+      warnOnce(`desk: no isKnown given, so "${id}" from a URL is taken on trust. Pass isKnown to drop unknown windows.`)
+      return true
+    })
+  const raw = params.get(options.key ?? 'w')
+  if (!raw) return { windows: [], stack: [] }
+
+  const entries = raw
+    .split(',')
+    .filter(Boolean)
+    .map(token => {
+      const floating = token.endsWith(FLOAT)
+      return { id: decodeURIComponent(floating ? token.slice(0, -1) : token), floating }
+    })
+    .filter(e => e.id && known(e.id))
+
+  const windows = entries.map(
+    (e, i): DeskWindow =>
+      e.floating
+        ? { id: e.id, mode: 'floating', frame: cascadeFrame(entries.slice(0, i).filter(x => x.floating).length, stage) }
+        : { id: e.id, mode: 'filled' },
+  )
+  const focus = params.get(options.focusKey ?? 'f')
+  const ids = windows.map(w => w.id)
+  const stack = focus && ids.includes(focus) ? [...ids.filter(id => id !== focus), focus] : ids
+  return normalise({ windows, stack })
+}
+
+export interface LocationEnv {
+  readonly location: { hash: string }
+  readonly history: { pushState(data: unknown, unused: string, url: string): void; replaceState(data: unknown, unused: string, url: string): void }
+  addEventListener(type: 'popstate', listener: () => void): void
+  removeEventListener(type: 'popstate', listener: () => void): void
+}
+
+const openSet = (state: DeskState) => state.windows.map(w => w.id).join('|')
+
+/**
+ * Keeps the desk and the URL hash in step. Opening or closing a window pushes a
+ * history entry, so Back closes it; focus and mode changes replace the entry.
+ * Other hash parameters are left alone, so the app can keep using the hash too.
+ */
+export function syncWithLocation(desk: Desk, stage: () => Size, options: LocationOptions = {}, env?: LocationEnv): () => void {
+  const target = env ?? (globalThis as unknown as LocationEnv)
+  const keys = [options.key ?? 'w', options.focusKey ?? 'f']
+  const read = () => new URLSearchParams(target.location.hash.replace(/^#/, ''))
+
+  const fromUrl = () => desk.restore(parse(read(), stage(), options))
+
+  const toUrl = (state: DeskState, previous: DeskState) => {
+    const params = read()
+    keys.forEach(k => params.delete(k))
+    serialize(state, options).forEach((value, key) => params.set(key, value))
+    const url = `#${params.toString().replace(/%2C/g, ',').replace(/%7E/g, FLOAT)}`
+    if (url === target.location.hash || (url === '#' && !target.location.hash)) return
+    if (openSet(state) !== openSet(previous)) target.history.pushState(null, '', url)
+    else target.history.replaceState(null, '', url)
+  }
+
+  // A URL that names windows wins. One that names none adopts whatever the app opened.
+  if (read().has(keys[0] as string)) fromUrl()
+  else if (desk.getState().windows.length) toUrl(desk.getState(), desk.getState())
+  let previous = desk.getState()
+  const unsubscribe = desk.subscribe(state => {
+    toUrl(state, previous)
+    previous = state
+  })
+  const onPop = () => {
+    fromUrl()
+    previous = desk.getState()
+  }
+  target.addEventListener('popstate', onPop)
+
+  return () => {
+    unsubscribe()
+    target.removeEventListener('popstate', onPop)
+  }
+}

package/src/core/shortcuts.ts

@@ -0,0 +1,119 @@
+import { perform } from './commands.js'
+import type { CommandId } from './commands.js'
+import type { Desk } from './desk.js'
+
+/*
+ * Shortcuts are written once, platform-neutrally — `mod+shift+z` — and mean ⌘ on
+ * Apple devices and Ctrl elsewhere. A shortcut performs a command through the
+ * responder chain; if nothing handles it, the browser's default is left alone,
+ * so ⌘C still copies when no window has claimed Copy.
+ */
+
+export type Keymap = Readonly<Record<string, CommandId>>
+
+export interface Shortcut {
+  readonly key: string
+  readonly mod: boolean
+  readonly shift: boolean
+  readonly alt: boolean
+  readonly ctrl: boolean
+}
+
+const NAMES: Readonly<Record<string, string>> = { esc: 'escape', return: 'enter', comma: ',', space: ' ', backquote: '`' }
+
+export function parseShortcut(text: string): Shortcut {
+  const parts = text.toLowerCase().split('+')
+  const key = parts.pop() ?? ''
+  return {
+    key: NAMES[key] ?? key,
+    mod: parts.includes('mod'),
+    shift: parts.includes('shift'),
+    alt: parts.includes('alt') || parts.includes('option'),
+    ctrl: parts.includes('ctrl'),
+  }
+}
+
+/**
+ * Whether the app is running installed, rather than in a browser tab. Only then
+ * may it take shortcuts the browser normally owns, such as ⌘W (HIG.md §5).
+ */
+export const isInstalledApp = (): boolean =>
+  typeof matchMedia === 'function' && (matchMedia('(display-mode: standalone)').matches || matchMedia('(display-mode: window-controls-overlay)').matches)
+
+export const isApplePlatform = (): boolean =>
+  typeof navigator !== 'undefined' && /mac|iphone|ipad|ipod/i.test(navigator.platform || navigator.userAgent)
+
+interface KeyLike {
+  readonly key: string
+  readonly code?: string
+  readonly metaKey: boolean
+  readonly ctrlKey: boolean
+  readonly shiftKey: boolean
+  readonly altKey: boolean
+}
+
+const CODES: Readonly<Record<string, string>> = {
+  BracketLeft: '[', BracketRight: ']', Backquote: '`', Comma: ',', Period: '.', Slash: '/', Semicolon: ';', Quote: "'", Minus: '-', Equal: '=', Backslash: '\\', Space: ' ',
+}
+
+/** The unmodified key a physical key stands for: ⌥ on a Mac turns `]` into `‘`, but the code is still BracketRight. */
+const keyFromCode = (code: string | undefined) =>
+  !code ? undefined
+  : code.startsWith('Key') ? code.slice(3).toLowerCase()
+  : code.startsWith('Digit') ? code.slice(5)
+  : CODES[code]
+
+export function matchesShortcut(event: KeyLike, shortcut: Shortcut, apple = isApplePlatform()): boolean {
+  const wantMeta = apple && shortcut.mod
+  const wantCtrl = shortcut.ctrl || (!apple && shortcut.mod)
+  return (
+    (event.key.toLowerCase() === shortcut.key || keyFromCode(event.code) === shortcut.key) &&
+    event.metaKey === wantMeta &&
+    event.ctrlKey === wantCtrl &&
+    event.shiftKey === shortcut.shift &&
+    event.altKey === shortcut.alt
+  )
+}
+
+const GLYPHS: Readonly<Record<string, string>> = {
+  escape: 'Esc', enter: '↩', ',': ',', ' ': 'Space', arrowup: '↑', arrowdown: '↓', arrowleft: '←', arrowright: '→', backspace: '⌫', '`': '`',
+}
+
+/** How a menu shows a shortcut: `⇧⌘Z` on Apple devices, `Ctrl+Shift+Z` elsewhere. */
+export function formatShortcut(text: string, apple = isApplePlatform()): string {
+  const s = parseShortcut(text)
+  const key = GLYPHS[s.key] ?? s.key.toUpperCase()
+  if (apple) return `${s.ctrl ? '⌃' : ''}${s.alt ? '⌥' : ''}${s.shift ? '⇧' : ''}${s.mod ? '⌘' : ''}${key}`
+  return [s.ctrl || s.mod ? 'Ctrl' : '', s.alt ? 'Alt' : '', s.shift ? 'Shift' : '', key].filter(Boolean).join('+')
+}
+
+const isEditable = (target: EventTarget | null) =>
+  target instanceof Element && (target.closest('input, textarea, select, [contenteditable=""], [contenteditable="true"]') !== null)
+
+export interface ShortcutOptions {
+  readonly target?: EventTarget
+  readonly apple?: boolean
+}
+
+/** Performs commands from keyboard shortcuts. Returns a function that stops listening. */
+export function bindShortcuts(desk: Desk | null, keymap: Keymap | (() => Keymap), options: ShortcutOptions = {}): () => void {
+  const target = options.target ?? globalThis
+  const bind = (map: Keymap) => Object.entries(map).map(([text, command]) => ({ shortcut: parseShortcut(text), command }))
+  // A keymap given as a function is read at each key press, for menus whose items change.
+  const fixed = typeof keymap === 'function' ? null : bind(keymap)
+
+  const onKeyDown = (event: Event) => {
+    const key = event as KeyboardEvent
+    if (key.defaultPrevented || key.isComposing) return
+    const bindings = fixed ?? bind((keymap as () => Keymap)())
+    const binding = bindings.find(b => matchesShortcut(key, b.shortcut, options.apple))
+    if (!binding) return
+    // A bare key belongs to whatever is being typed into; a modified one can still be a command.
+    const plain = !binding.shortcut.mod && !binding.shortcut.ctrl && !binding.shortcut.alt
+    if (plain && isEditable(key.target)) return
+    if (perform(desk, binding.command)) key.preventDefault()
+  }
+
+  target.addEventListener('keydown', onKeyDown)
+  return () => target.removeEventListener('keydown', onKeyDown)
+}

package/src/core/titles.ts

@@ -0,0 +1,28 @@
+/*
+ * App and window names are names, so they are written in title case: Ride Card,
+ * Parts & Wear, Service History. It is not applied for you, because a window showing one
+ * document takes that document's own name, as written. Use `titleCase` where a name
+ * is defined, and `isTitleCase` in a test over the names an app defines.
+ */
+
+/** Short words that stay lower case inside a title: articles, conjunctions, short prepositions. */
+const MINOR = new Set(['a', 'an', 'and', 'as', 'at', 'but', 'by', 'for', 'in', 'nor', 'of', 'on', 'or', 'per', 'so', 'the', 'to', 'up', 'via', 'vs', 'yet'])
+
+// A word someone has already cased on purpose — iPhone, API, macOS — is left alone.
+const deliberate = (word: string) => /[A-Z]/.test(word.slice(1))
+
+const capital = (word: string) => word.charAt(0).toUpperCase() + word.slice(1)
+
+export function titleCase(text: string): string {
+  const words = text.trim().split(/\s+/)
+  return words
+    .map((word, i) => {
+      if (deliberate(word)) return word
+      const edge = i === 0 || i === words.length - 1
+      if (!edge && MINOR.has(word.toLowerCase())) return word.toLowerCase()
+      return word.split('-').map(capital).join('-')
+    })
+    .join(' ')
+}
+
+export const isTitleCase = (text: string): boolean => titleCase(text) === text.trim()