@erclx/canon 5.26.0 → 5.28.0

package/src/canvas/client/surface.tsx

@@ -3,9 +3,12 @@ import type { JSX, RefObject } from 'preact'
 import { useEffect, 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,
@@ -16,22 +19,31 @@ import {
   moveFrameTo,
   panBy,
   previewMove,
+  previewResize,
   registerFrameDocument,
+  resizeElement,
+  resizeFrameTo,
   selectElement,
   selectFrame,
   selection,
+  shownTool,
+  spacePan,
   type Theme,
   toggleFrameTheme,
   view,
   zoomAt,
 } from '@/canvas/client/state'
+import {
+  DRAG_THRESHOLD,
+  HoverOutline,
+  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
 
-/** Screen pixels a press travels before it reads as a drag and not a click. */
-const DRAG_THRESHOLD = 3
-
 /** Surface units one arrow press moves a frame, and one with Shift held. */
 const NUDGE = 10
 const NUDGE_LARGE = 50
@@ -76,25 +88,142 @@ function asElement(target: EventTarget | null): Element | undefined {
   return node?.nodeType === 1 ? (node as Element) : undefined
 }
 
-function ElementOutline({
-  element,
-  kind,
+/**
+ * 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)
+  return value.endsWith('px') && Number.isFinite(parsed) ? parsed : fallback
+}
+
+/**
+ * The selected element's overlay. A handle drag previews the size as inline
+ * style on the element and writes it once on release, the way the inspector's
+ * scrub does. The drag measures the border box while `width` and `height` set
+ * whatever box the element sizes by, so the delta is added to the computed
+ * value rather than written as the box itself.
+ */
+function ElementSelection({
+  node,
+  doc,
+  frameRef,
+  docKey,
 }: {
-  readonly element: Element
-  readonly kind: 'hover' | 'selected'
+  readonly node: Element
+  readonly doc: Document
+  readonly frameRef: FrameRef
+  readonly docKey: string
 }): JSX.Element {
-  const rect = element.getBoundingClientRect()
+  const start = useRef<
+    | {
+        readonly width: number
+        readonly height: number
+        readonly inlineWidth: string
+        readonly inlineHeight: string
+      }
+    | undefined
+  >(undefined)
+  const style = (node as HTMLElement).style
+
+  const measure = () => {
+    const rect = node.getBoundingClientRect()
+    return { x: rect.left, y: rect.top, width: rect.width, height: rect.height }
+  }
+
+  const cssSize = (box: OverlayBox, origin: OverlayBox) => {
+    const from = start.current
+    return {
+      width: Math.round(
+        (from?.width ?? origin.width) + box.width - origin.width,
+      ),
+      height: Math.round(
+        (from?.height ?? origin.height) + box.height - origin.height,
+      ),
+    }
+  }
+
+  const handleStart = () => {
+    const computed = doc.defaultView?.getComputedStyle(node)
+    const rect = node.getBoundingClientRect()
+    start.current = {
+      width: pixels(computed?.width ?? '', rect.width),
+      height: pixels(computed?.height ?? '', rect.height),
+      inlineWidth: style.getPropertyValue('width'),
+      inlineHeight: style.getPropertyValue('height'),
+    }
+  }
+
+  const handlePreview = (box: OverlayBox, from: OverlayBox) => {
+    const size = cssSize(box, from)
+    style.setProperty('width', `${size.width}px`)
+    style.setProperty('height', `${size.height}px`)
+  }
+
+  const restore = () => {
+    const from = start.current
+    if (!from) return
+    style.setProperty('width', from.inlineWidth)
+    style.setProperty('height', from.inlineHeight)
+  }
+
+  const handleCommit = (box: OverlayBox, from: OverlayBox) => {
+    const size = cssSize(box, from)
+    const address = addressOf(doc, node)
+    const isUnchanged = box.width === from.width && box.height === from.height
+    if (!address || isUnchanged) {
+      restore()
+      return
+    }
+    void resizeElement(
+      frameRef,
+      docKey,
+      address,
+      box.width === from.width ? undefined : size.width,
+      box.height === from.height ? undefined : size.height,
+    )
+  }
+
+  const handleCancel = restore
+
   return (
-    <div
-      class="element-outline"
-      data-outline={kind}
-      aria-hidden="true"
-      style={{
-        left: `${rect.left}px`,
-        top: `${rect.top}px`,
-        width: `${rect.width}px`,
-        height: `${rect.height}px`,
-      }}
+    <SelectionOverlay
+      kind="element"
+      measure={measure}
+      hasChip
+      isMeasuredWhileDragging
+      onStart={handleStart}
+      onPreview={handlePreview}
+      onCommit={handleCommit}
+      onCancel={handleCancel}
     />
   )
 }
@@ -119,10 +248,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
@@ -135,6 +266,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)
@@ -185,6 +317,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 =
@@ -206,6 +348,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,
@@ -254,7 +398,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
@@ -263,20 +407,50 @@ function FrameView({
     const delta = ARROWS[event.key]
     if (!delta || !isSelected) return
     event.preventDefault()
+    /* The keyboard path for a handle drag: right and down grow the frame. */
+    if (event.ctrlKey || event.metaKey) {
+      void resizeFrameTo(ref, {
+        x: frame.x,
+        y: frame.y,
+        width: Math.max(1, frame.width + delta.x * step),
+        height: Math.max(1, frame.height + delta.y * step),
+      })
+      return
+    }
     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,
+    width: frame.width,
+    height: frame.height,
+  })
+
   const next = value === 'dark' ? 'light' : 'dark'
   return (
     <figure
       class="frame"
       data-frame={frame.name}
       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`,
@@ -297,6 +471,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"
@@ -318,10 +496,25 @@ function FrameView({
           onLoad={handleLoad}
         />
         {hoveredNode && hoveredNode !== selectedNode ? (
-          <ElementOutline element={hoveredNode} kind="hover" />
+          <HoverOutline element={hoveredNode} />
+        ) : null}
+        {isSelected && !picked ? (
+          <SelectionOverlay
+            kind="frame"
+            measure={frameBox}
+            offset={{ x: frame.x, y: frame.y }}
+            onPreview={(box) => previewResize(ref, box)}
+            onCommit={(box) => void resizeFrameTo(ref, box)}
+            onCancel={(origin) => previewResize(ref, origin)}
+          />
         ) : null}
-        {selectedNode ? (
-          <ElementOutline element={selectedNode} kind="selected" />
+        {doc && selectedNode ? (
+          <ElementSelection
+            node={selectedNode}
+            doc={doc}
+            frameRef={ref}
+            docKey={key}
+          />
         ) : null}
       </div>
     </figure>
@@ -336,18 +529,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>
@@ -358,17 +568,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>
@@ -382,8 +593,7 @@ 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])
 
   const handleWheelTurn = (turn: WheelTurn) => {
@@ -411,9 +621,68 @@ 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
+    }
+  }
+
+  /*
+   * 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)
   }
@@ -421,22 +690,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}
@@ -455,10 +755,12 @@ export function Surface({ viewportRef }: SurfaceProps): JSX.Element {
               page={page.name}
               frame={frame}
               onWheelTurn={handleWheelTurn}
+              onKey={handleKey}
             />
           ))}
         </div>
       </div>
+      <ToolStrip />
       <Toolbar viewportRef={viewportRef} />
     </main>
   )

package/src/canvas/client/tools.tsx

@@ -0,0 +1,64 @@
+/** @jsxImportSource preact */
+import type { JSX } from 'preact'
+import { activeTool, shownTool, type Tool } 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>
+    ),
+  },
+]
+
+/** The tool strip floating at the surface's left edge, one button a tool. */
+export function ToolStrip(): JSX.Element {
+  const shown = shownTool.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>
+      ))}
+    </div>
+  )
+}

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
@@ -129,7 +129,7 @@ function refuse(reason: ContentRefusal, detail: string): ContentRefused {
   return { ok: false, reason, detail }
 }
 
-function isValidName(name: string): boolean {
+export function isValidName(name: string): boolean {
   return NAME_PATTERN.test(name) && !name.includes('..')
 }
 
@@ -464,6 +464,55 @@ export function moveFrame(
   })
 }
 
+/**
+ * Writes one frame's whole box. A handle on the top or left edge moves the
+ * frame as it resizes it, so position and size land in one locked write rather
+ * than a move and a resize another writer could land between.
+ */
+export function resizeFrame(
+  root: string,
+  page: string,
+  frame: string,
+  box: Box,
+): FrameOutcome {
+  if (!isValidName(page)) {
+    return refuse('invalid-name', `${page} is not a valid page name`)
+  }
+  if (!isValidName(frame)) {
+    return refuse('invalid-name', `${frame} is not a valid frame name`)
+  }
+  if (!Number.isFinite(box.x) || !Number.isFinite(box.y)) {
+    return refuse('invalid-position', 'x and y must be numbers')
+  }
+  const isPositive = (value: number) => Number.isFinite(value) && value > 0
+  if (!isPositive(box.width) || !isPositive(box.height)) {
+    return refuse('invalid-size', 'width and height must be positive numbers')
+  }
+
+  const dir = pagePath(root, page)
+  if (!isDirectory(dir)) return refuse('no-page', `page ${page} does not exist`)
+  const file = `${frame}${FRAME_EXTENSION}`
+  if (!existsSync(join(dir, file))) {
+    return refuse('no-frame', `frame ${frame} does not exist on ${page}`)
+  }
+
+  return withLayoutLock(dir, () => {
+    const { boxes, malformed } = readLayout(dir)
+    if (malformed) {
+      return refuse('malformed-layout', `${page}/${LAYOUT_FILE} does not parse`)
+    }
+    const written: Box = {
+      x: box.x,
+      y: box.y,
+      width: box.width,
+      height: box.height,
+    }
+
+    writeLayout(dir, new Map([...boxes, [frame, written]]))
+    return { ok: true, page, frame, file, box: written }
+  })
+}
+
 export interface Selection {
   readonly page: string
   readonly frame: string