@erclx/canon 5.27.0 → 5.29.0

package/src/canvas/client/surface.tsx

@@ -1,30 +1,41 @@
 /** @jsxImportSource preact */
 import type { JSX, RefObject } from 'preact'
-import { useEffect, useRef, useState } from 'preact/hooks'
+import { useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks'
 import { addressOf, documentElements, elementAt } from '@/canvas/address'
 import type { Frame } from '@/canvas/content'
+import { type SurfaceAction, surfaceAction } from '@/canvas/client/keys'
 import {
+  activeTool,
   currentPage,
   draggingFrame,
+  editingFrames,
   fitView,
   type FrameRef,
   frameDocuments,
   frameKey,
   frameTheme,
   frameVersions,
+  historyNotice,
   hoveredElement,
   moveFrameTo,
   panBy,
+  panelsHidden,
+  panelWidths,
   previewMove,
   previewResize,
+  redo,
   registerFrameDocument,
   resizeElement,
   resizeFrameTo,
   selectElement,
   selectFrame,
   selection,
+  shownTool,
+  spacePan,
   type Theme,
   toggleFrameTheme,
+  togglePanels,
+  undo,
   view,
   zoomAt,
 } from '@/canvas/client/state'
@@ -34,6 +45,7 @@ import {
   type OverlayBox,
   SelectionOverlay,
 } from '@/canvas/client/selection'
+import { ToolStrip } from '@/canvas/client/tools'
 
 /** One wheel notch or one button press. */
 const ZOOM_STEP = 1.2
@@ -82,6 +94,37 @@ function asElement(target: EventTarget | null): Element | undefined {
   return node?.nodeType === 1 ? (node as Element) : undefined
 }
 
+/**
+ * Whether a key belongs to the element it was typed in rather than to the
+ * canvas: any key in a field, and Space on a control it activates. A frame's
+ * draft can hold its own fields, and their keys arrive through the forwarding.
+ */
+function isOwnedByTarget(event: KeyboardEvent, action: SurfaceAction): boolean {
+  const target = asElement(event.target)
+  if (!target) return false
+  if ((target as HTMLElement).isContentEditable) return true
+  if (target.closest('input, textarea, select')) return true
+  return (
+    action === 'pan-hold' && target.closest('button, a[href], summary') !== null
+  )
+}
+
+/**
+ * A press read as a second click selects a word or a whole frame even while
+ * panning, so no selection may start in the shell or a frame then.
+ */
+function blockSelectionWhilePanning(event: Event): void {
+  if (shownTool.value === 'pan') event.preventDefault()
+}
+
+/** Drops any selection in the shell and in every loaded frame document. */
+function clearSelections(): void {
+  document.getSelection()?.removeAllRanges()
+  for (const doc of frameDocuments.value.values()) {
+    doc.getSelection()?.removeAllRanges()
+  }
+}
+
 /** A computed length in pixels, or the fallback for one that is not. */
 function pixels(value: string, fallback: number): number {
   const parsed = Number.parseFloat(value)
@@ -211,10 +254,12 @@ function FrameView({
   page,
   frame,
   onWheelTurn,
+  onKey,
 }: {
   readonly page: string
   readonly frame: Frame
   readonly onWheelTurn: (turn: WheelTurn) => void
+  readonly onKey: (event: KeyboardEvent) => void
 }): JSX.Element {
   const key = frameKey(page, frame)
   const version = frameVersions.value.get(key) ?? 0
@@ -227,6 +272,7 @@ function FrameView({
   /* Bumped when the frame document scrolls, so the outlines follow it. */
   const [, setScrolled] = useState(0)
   const doc = frameDocuments.value.get(key)
+  const editing = editingFrames.value.get(key)
 
   useEffect(() => {
     applyFrameTheme(iframe.current, value)
@@ -277,6 +323,16 @@ function FrameView({
       },
       { passive: false },
     )
+    /*
+     * A click inside the frame moves focus into its window, so the surface
+     * hears no key after the first pick unless the frame passes it on.
+     */
+    loaded.addEventListener('keydown', onKey)
+    loaded.addEventListener('keyup', onKey)
+    loaded.addEventListener('selectstart', blockSelectionWhilePanning)
+    loaded.defaultView?.addEventListener('blur', () => {
+      spacePan.value = undefined
+    })
   }
 
   const picked =
@@ -298,6 +354,8 @@ function FrameView({
 
   const handlePointerDown = (event: PointerEvent) => {
     if (event.button !== 0) return
+    /* A pan drag starting on the label belongs to the surface behind it. */
+    if (shownTool.value === 'pan') return
     if ((event.target as HTMLElement | null)?.closest('.frame-theme')) return
     gesture.current = {
       startX: event.clientX,
@@ -346,7 +404,7 @@ function FrameView({
    */
   const handleKeyDown = (event: KeyboardEvent) => {
     if (event.target !== event.currentTarget) return
-    if (event.key === 'Enter' || event.key === ' ') {
+    if (event.key === 'Enter') {
       event.preventDefault()
       select()
       return
@@ -368,6 +426,16 @@ function FrameView({
     void moveFrameTo(ref, frame.x + delta.x * step, frame.y + delta.y * step)
   }
 
+  /*
+   * Space held pans, so it selects on release instead, and only when no drag
+   * moved the view while it was down. This runs before the surface's own
+   * release clears the pan.
+   */
+  const handleKeyUp = (event: KeyboardEvent) => {
+    if (event.target !== event.currentTarget || event.key !== ' ') return
+    if (spacePan.value !== 'dragged') select()
+  }
+
   const frameBox = (): OverlayBox => ({
     x: frame.x,
     y: frame.y,
@@ -383,10 +451,12 @@ function FrameView({
       data-selected={isSelected ? 'true' : undefined}
       data-picked={picked ? 'true' : undefined}
       data-dragging={draggingFrame.value === frame.name ? 'true' : undefined}
+      data-editing={editing ? 'true' : undefined}
       tabIndex={0}
-      aria-label={`${frame.name}, ${frame.width} by ${frame.height}`}
+      aria-label={`${frame.name}, ${frame.width} by ${frame.height}${editing ? `, ${editing.by} editing` : ''}`}
       aria-current={isSelected ? 'true' : undefined}
       onKeyDown={handleKeyDown}
+      onKeyUp={handleKeyUp}
       style={{
         left: `${frame.x}px`,
         top: `${frame.y}px`,
@@ -407,6 +477,10 @@ function FrameView({
         <span class="frame-size">
           {frame.width} × {frame.height}
         </span>
+        {/* Rendered empty while unmarked, so a mark landing is announced. */}
+        <span class="frame-editing" aria-live="polite">
+          {editing ? `${editing.by} editing` : ''}
+        </span>
         <button
           type="button"
           class="frame-theme"
@@ -461,18 +535,35 @@ function viewportSize(viewport: RefObject<HTMLDivElement | null>): {
   return { width: rect?.width ?? 0, height: rect?.height ?? 0 }
 }
 
+/** The zoom toolbar's actions, which its keys call as well. */
+function zoomCentered(
+  viewport: RefObject<HTMLDivElement | null>,
+  factor: number,
+): void {
+  const { width, height } = viewportSize(viewport)
+  zoomAt(factor, width / 2, height / 2)
+}
+
+/** Fits the page clear of the tool strip floating over the viewport's left. */
+function fitViewport(viewport: RefObject<HTMLDivElement | null>): void {
+  const rect = viewport.current?.getBoundingClientRect()
+  const strip = viewport.current?.parentElement
+    ?.querySelector('.tools')
+    ?.getBoundingClientRect()
+  const inset = rect && strip ? Math.max(0, strip.right - rect.left) : 0
+  fitView(rect?.width ?? 0, rect?.height ?? 0, undefined, inset)
+}
+
 function Toolbar({ viewportRef }: SurfaceProps): JSX.Element {
-  const zoomCentered = (factor: number) => {
-    const { width, height } = viewportSize(viewportRef)
-    zoomAt(factor, width / 2, height / 2)
-  }
   return (
     <div class="toolbar" role="toolbar" aria-label="Zoom">
       <button
         type="button"
         class="icon-button"
         aria-label="Zoom out"
-        onClick={() => zoomCentered(1 / ZOOM_STEP)}
+        aria-keyshortcuts="-"
+        title="Zoom out (-)"
+        onClick={() => zoomCentered(viewportRef, 1 / ZOOM_STEP)}
       >
         −
       </button>
@@ -483,17 +574,18 @@ function Toolbar({ viewportRef }: SurfaceProps): JSX.Element {
         type="button"
         class="icon-button"
         aria-label="Zoom in"
-        onClick={() => zoomCentered(ZOOM_STEP)}
+        aria-keyshortcuts="+"
+        title="Zoom in (+)"
+        onClick={() => zoomCentered(viewportRef, ZOOM_STEP)}
       >
         +
       </button>
       <button
         type="button"
         class="text-button"
-        onClick={() => {
-          const { width, height } = viewportSize(viewportRef)
-          fitView(width, height)
-        }}
+        aria-keyshortcuts="Shift+1"
+        title="Fit (Shift+1)"
+        onClick={() => fitViewport(viewportRef)}
       >
         Fit
       </button>
@@ -507,10 +599,25 @@ export function Surface({ viewportRef }: SurfaceProps): JSX.Element {
 
   /* Fits a page once when it opens, never on a reload of the same page. */
   useEffect(() => {
-    const { width, height } = viewportSize(viewportRef)
-    fitView(width, height)
+    fitViewport(viewportRef)
   }, [page?.name])
 
+  /*
+   * A panel hiding, showing, or resizing moves the viewport's left edge, so
+   * the view shifts by as much the other way and the frames hold still on
+   * screen. Reading the flag subscribes this component to it.
+   */
+  const viewportLeft = useRef<number | undefined>(undefined)
+  const isHidden = panelsHidden.value
+  const leftWidth = panelWidths.value.left
+  useLayoutEffect(() => {
+    const left = viewportRef.current?.getBoundingClientRect().left
+    if (left === undefined) return
+    const before = viewportLeft.current
+    viewportLeft.current = left
+    if (before !== undefined && before !== left) panBy(before - left, 0)
+  }, [isHidden, leftWidth])
+
   const handleWheelTurn = (turn: WheelTurn) => {
     if (turn.isZoom) {
       const rect = viewportRef.current?.getBoundingClientRect()
@@ -536,9 +643,77 @@ export function Surface({ viewportRef }: SurfaceProps): JSX.Element {
     })
   }
 
+  /* A pan held when the window loses focus never hears its Space come up. */
+  useEffect(() => {
+    const endPan = () => {
+      spacePan.value = undefined
+    }
+    window.addEventListener('blur', endPan)
+    document.addEventListener('selectstart', blockSelectionWhilePanning)
+    return () => {
+      window.removeEventListener('blur', endPan)
+      document.removeEventListener('selectstart', blockSelectionWhilePanning)
+    }
+  }, [])
+
+  const runAction = (action: SurfaceAction) => {
+    switch (action) {
+      case 'tool-move':
+        activeTool.value = 'move'
+        return
+      case 'tool-pan':
+        activeTool.value = 'pan'
+        return
+      case 'zoom-in':
+        zoomCentered(viewportRef, ZOOM_STEP)
+        return
+      case 'zoom-out':
+        zoomCentered(viewportRef, 1 / ZOOM_STEP)
+        return
+      case 'zoom-fit':
+        fitViewport(viewportRef)
+        return
+      case 'pan-hold':
+        spacePan.value ??= 'held'
+        return
+      case 'pan-release':
+        spacePan.value = undefined
+        return
+      case 'undo':
+        void undo()
+        return
+      case 'redo':
+        void redo()
+        return
+      case 'panels-toggle':
+        togglePanels()
+    }
+  }
+
+  /*
+   * The surface's one key handler, which every frame document feeds too. The
+   * default is prevented only for a key press it takes, so Space stops
+   * scrolling a frame it pans and every other key keeps its own meaning. A
+   * release always ends the pan and never claims the keyup, since a button
+   * fires its Space activation there.
+   */
+  const handleKey = (event: KeyboardEvent) => {
+    const action = surfaceAction(event)
+    if (!action) return
+    if (action === 'pan-release') {
+      runAction(action)
+      return
+    }
+    if (isOwnedByTarget(event, action)) return
+    event.preventDefault()
+    runAction(action)
+  }
+
   const handlePointerDown = (event: PointerEvent) => {
     const target = event.target as HTMLElement | null
-    if (target?.closest('.frame, .toolbar')) return
+    if (shownTool.value !== 'pan' && target?.closest('.frame')) return
+    /* A selection left over would paint over every frame the pan crosses. */
+    if (shownTool.value === 'pan') clearSelections()
     drag.current = { x: event.clientX, y: event.clientY }
     viewportRef.current?.setPointerCapture?.(event.pointerId)
   }
@@ -546,22 +721,53 @@ export function Surface({ viewportRef }: SurfaceProps): JSX.Element {
   const handlePointerMove = (event: PointerEvent) => {
     const start = drag.current
     if (!start) return
-    panBy(event.clientX - start.x, event.clientY - start.y)
+    const dx = event.clientX - start.x
+    const dy = event.clientY - start.y
+    panBy(dx, dy)
     drag.current = { x: event.clientX, y: event.clientY }
+    if (spacePan.value === 'held' && (dx !== 0 || dy !== 0)) {
+      spacePan.value = 'dragged'
+    }
+  }
+
+  /*
+   * A press selects text by default, a word or a whole frame when it reads as
+   * a second click, and neither `selectstart` nor a clear at pointer down
+   * reaches that. Under a held Space, focus stays where it was so the frame
+   * still hears the release. Under the Pan tool the press takes focus itself,
+   * as the default would have, so a field it leaves commits and the next key
+   * reaches the layer.
+   */
+  const handleMouseDown = (event: MouseEvent) => {
+    if (shownTool.value !== 'pan') return
+    event.preventDefault()
+    if (!spacePan.value) {
+      const surface = (event.currentTarget as HTMLElement).closest('main')
+      surface?.focus({ preventScroll: true })
+    }
   }
 
   const handlePointerUp = () => {
+    if (drag.current && shownTool.value === 'pan') clearSelections()
     drag.current = undefined
   }
 
   const { x, y, zoom } = view.value
   return (
-    <main class="surface" aria-label="Canvas">
+    <main
+      class="surface"
+      aria-label="Canvas"
+      tabIndex={0}
+      data-tool={shownTool.value}
+      onKeyDown={handleKey}
+      onKeyUp={handleKey}
+    >
       <div
         ref={viewportRef}
         class="viewport"
         onWheel={handleWheel}
         onPointerDown={handlePointerDown}
+        onMouseDown={handleMouseDown}
         onPointerMove={handlePointerMove}
         onPointerUp={handlePointerUp}
         onPointerCancel={handlePointerUp}
@@ -580,11 +786,18 @@ export function Surface({ viewportRef }: SurfaceProps): JSX.Element {
               page={page.name}
               frame={frame}
               onWheelTurn={handleWheelTurn}
+              onKey={handleKey}
             />
           ))}
         </div>
       </div>
+      <ToolStrip />
       <Toolbar viewportRef={viewportRef} />
+      {historyNotice.value ? (
+        <p class="history-notice" role="status">
+          {historyNotice.value}
+        </p>
+      ) : null}
     </main>
   )
 }

package/src/canvas/client/tools.tsx

@@ -0,0 +1,153 @@
+/** @jsxImportSource preact */
+import type { JSX } from 'preact'
+import {
+  activeTool,
+  history,
+  panelsHidden,
+  redo,
+  shownTool,
+  type Tool,
+  togglePanels,
+  undo,
+} from '@/canvas/client/state'
+
+interface ToolButton {
+  readonly tool: Tool
+  readonly name: string
+  readonly key: string
+  readonly icon: JSX.Element
+}
+
+const TOOLS: readonly ToolButton[] = [
+  {
+    tool: 'move',
+    name: 'Move',
+    key: 'V',
+    icon: (
+      <svg viewBox="0 0 16 16" aria-hidden="true">
+        <path d="M3.5 2.5l9 4.2-3.9 1.2-1.4 3.8z" />
+      </svg>
+    ),
+  },
+  {
+    tool: 'pan',
+    name: 'Pan',
+    key: 'H',
+    icon: (
+      <svg viewBox="0 0 16 16" aria-hidden="true">
+        <path d="M5.5 8.5V4a1 1 0 0 1 2 0v3.5M7.5 7V2.8a1 1 0 0 1 2 0V7M9.5 7V3.6a1 1 0 0 1 2 0V8M11.5 7.5a1 1 0 0 1 2 0v2.2A4.8 4.8 0 0 1 8.7 14.5h-.6a4.3 4.3 0 0 1-3.2-1.4L2.6 10.6a1 1 0 0 1 1.5-1.4l1.4 1.3" />
+      </svg>
+    ),
+  },
+]
+
+interface HistoryButton {
+  readonly name: 'Undo' | 'Redo'
+  readonly shortcut: string
+  readonly keys: string
+  readonly run: () => Promise<void>
+  readonly icon: JSX.Element
+}
+
+/** The modifier the platform names for undo, Cmd on macOS and Ctrl elsewhere. */
+const MOD = /Mac|iPhone|iPad/.test(globalThis.navigator?.platform ?? '')
+  ? 'Cmd'
+  : 'Ctrl'
+
+const HISTORY_BUTTONS: readonly HistoryButton[] = [
+  {
+    name: 'Undo',
+    shortcut: `${MOD}+Z`,
+    keys: 'Control+Z Meta+Z',
+    run: () => undo(),
+    icon: (
+      <svg viewBox="0 0 16 16" aria-hidden="true">
+        <path d="M5.5 3.5L2.5 6.5l3 3M2.5 6.5h7a4 4 0 0 1 0 8H7" />
+      </svg>
+    ),
+  },
+  {
+    name: 'Redo',
+    shortcut: `${MOD}+Shift+Z`,
+    keys: 'Control+Shift+Z Meta+Shift+Z Control+Y',
+    run: () => redo(),
+    icon: (
+      <svg viewBox="0 0 16 16" aria-hidden="true">
+        <path d="M10.5 3.5l3 3-3 3M13.5 6.5h-7a4 4 0 0 0 0 8H9" />
+      </svg>
+    ),
+  },
+]
+
+/**
+ * The tool strip floating at the surface's left edge, one button a tool, then
+ * undo and redo, each disabled while the server holds nothing to step.
+ */
+export function ToolStrip(): JSX.Element {
+  const shown = shownTool.value
+  const { canUndo, canRedo } = history.value
+  return (
+    <div
+      class="tools"
+      role="toolbar"
+      aria-label="Tools"
+      aria-orientation="vertical"
+    >
+      {TOOLS.map(({ tool, name, key, icon }) => (
+        <button
+          key={tool}
+          type="button"
+          class="tool-button"
+          aria-label={`${name} (${key})`}
+          aria-keyshortcuts={key}
+          aria-pressed={shown === tool ? 'true' : 'false'}
+          title={`${name} (${key})`}
+          data-tool={tool}
+          onClick={() => {
+            activeTool.value = tool
+          }}
+        >
+          {icon}
+        </button>
+      ))}
+      <span class="tools-divider" aria-hidden="true" />
+      {HISTORY_BUTTONS.map(({ name, shortcut, keys, run, icon }) => (
+        <button
+          key={name}
+          type="button"
+          class="tool-button"
+          aria-label={`${name} (${shortcut})`}
+          aria-keyshortcuts={keys}
+          title={`${name} (${shortcut})`}
+          disabled={name === 'Undo' ? !canUndo : !canRedo}
+          onClick={() => void run()}
+        >
+          {icon}
+        </button>
+      ))}
+      <span class="tools-divider" aria-hidden="true" />
+      <PanelsButton />
+    </div>
+  )
+}
+
+/** Named by what a press does now, so the panels come back by mouse too. */
+function PanelsButton(): JSX.Element {
+  const name = panelsHidden.value ? 'Show panels' : 'Hide panels'
+  return (
+    <button
+      type="button"
+      class="tool-button"
+      aria-label={`${name} (\\)`}
+      aria-keyshortcuts="\\"
+      title={`${name} (\\)`}
+      data-panels={panelsHidden.value ? 'hidden' : 'shown'}
+      onClick={togglePanels}
+    >
+      <svg viewBox="0 0 16 16" aria-hidden="true">
+        <rect x="2" y="3" width="12" height="10" rx="1.5" />
+        {panelsHidden.value ? null : <path d="M5.5 3v10M10.5 3v10" />}
+      </svg>
+    </button>
+  )
+}

package/src/canvas/content.ts

@@ -18,7 +18,7 @@ import {
   resolveAddress,
   type SourceElement,
 } from '@/canvas/address'
-import { recordDir } from '@/record-root'
+import { recordDir } from '@/roots/record'
 
 /**
  * The content format. A page is a folder under the record root's `canvas/`, a
@@ -419,6 +419,12 @@ export interface Position {
   readonly y: number
 }
 
+/**
+ * Hears the box a write replaced, undefined when the layout held none, and the
+ * box it wrote, apart from the returned record, which the CLI prints.
+ */
+export type BoxObserver = (replaced: Box | undefined, written: Box) => void
+
 /**
  * Moves one frame and keeps its size. A frame the layout never named takes the
  * default size it was already drawn at, so the move does not resize it.
@@ -428,6 +434,7 @@ export function moveFrame(
   page: string,
   frame: string,
   to: Position,
+  observe?: BoxObserver,
 ): FrameOutcome {
   if (!isValidName(page)) {
     return refuse('invalid-name', `${page} is not a valid page name`)
@@ -460,6 +467,7 @@ export function moveFrame(
     }
 
     writeLayout(dir, new Map([...boxes, [frame, box]]))
+    observe?.(boxes.get(frame), box)
     return { ok: true, page, frame, file, box }
   })
 }
@@ -474,6 +482,7 @@ export function resizeFrame(
   page: string,
   frame: string,
   box: Box,
+  observe?: BoxObserver,
 ): FrameOutcome {
   if (!isValidName(page)) {
     return refuse('invalid-name', `${page} is not a valid page name`)
@@ -509,10 +518,66 @@ export function resizeFrame(
     }
 
     writeLayout(dir, new Map([...boxes, [frame, written]]))
+    observe?.(boxes.get(frame), written)
     return { ok: true, page, frame, file, box: written }
   })
 }
 
+function isSameBox(a: Box | undefined, b: Box | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b
+  return (
+    a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height
+  )
+}
+
+export type BoxRestore =
+  | { readonly ok: true }
+  | ContentRefused
+  | {
+      readonly ok: false
+      readonly reason: 'changed'
+      readonly detail: string
+    }
+
+/**
+ * Writes a recorded box back under the layout lock, only while the layout
+ * still holds the box the record expects, where undefined expects none.
+ * Restoring to no box drops the frame's entry, so the reader places it in the
+ * default row again.
+ */
+export function restoreBox(
+  root: string,
+  page: string,
+  frame: string,
+  expected: Box | undefined,
+  to: Box | undefined,
+): BoxRestore {
+  const dir = pagePath(root, page)
+  if (!isDirectory(dir)) return refuse('no-page', `page ${page} does not exist`)
+  if (!existsSync(join(dir, `${frame}${FRAME_EXTENSION}`))) {
+    return refuse('no-frame', `frame ${frame} does not exist on ${page}`)
+  }
+
+  return withFileLock(join(dir, LAYOUT_FILE), (): BoxRestore => {
+    const { boxes, malformed } = readLayout(dir)
+    if (malformed) {
+      return refuse('malformed-layout', `${page}/${LAYOUT_FILE} does not parse`)
+    }
+    if (!isSameBox(boxes.get(frame), expected)) {
+      return {
+        ok: false,
+        reason: 'changed',
+        detail: `${page}/${frame} moved since this change, so nothing was written`,
+      }
+    }
+    const next = new Map(boxes)
+    if (to === undefined) next.delete(frame)
+    else next.set(frame, to)
+    writeLayout(dir, next)
+    return { ok: true }
+  })
+}
+
 export interface Selection {
   readonly page: string
   readonly frame: string