@erclx/canon 5.14.0 → 5.15.0

package/src/canvas/client/state.ts

@@ -0,0 +1,186 @@
+import { computed, signal } from '@preact/signals'
+import type { Frame, Page } from '@/canvas/content'
+
+/**
+ * Everything the panels read. Type imports only from outside `client/`, since
+ * this runs in the browser and a Node or Bun module would not bundle there.
+ */
+
+export type Theme = 'light' | 'dark'
+
+export interface TokenSource {
+  readonly source: 'toolkit' | 'installed' | 'none'
+  readonly files?: readonly string[]
+  readonly notice?: string
+}
+
+export interface PagesRecord {
+  readonly pages: readonly Page[]
+  readonly tokens: TokenSource
+}
+
+export interface ChangeEvent {
+  readonly page: string
+  readonly file: string
+}
+
+export interface View {
+  readonly x: number
+  readonly y: number
+  readonly zoom: number
+}
+
+export const MIN_ZOOM = 0.05
+export const MAX_ZOOM = 4
+
+export const pages = signal<readonly Page[]>([])
+export const tokens = signal<TokenSource | undefined>(undefined)
+export const isLoaded = signal(false)
+export const loadError = signal<string | undefined>(undefined)
+export const selectedPage = signal<string | undefined>(undefined)
+
+/** Undefined follows the system, which `systemTheme` reports. */
+export const themeChoice = signal<Theme | undefined>(undefined)
+export const systemTheme = signal<Theme>('dark')
+export const theme = computed<Theme>(
+  () => themeChoice.value ?? systemTheme.value,
+)
+
+/** A frame's own theme where the operator switched it, else the chrome's. */
+export const frameThemes = signal<ReadonlyMap<string, Theme>>(new Map())
+
+/** Bumped per frame on a change, so only that frame's document reloads. */
+export const frameVersions = signal<ReadonlyMap<string, number>>(new Map())
+
+export const view = signal<View>({ x: 0, y: 0, zoom: 0.5 })
+
+export const currentPage = computed<Page | undefined>(() => {
+  const all = pages.value
+  return all.find((page) => page.name === selectedPage.value) ?? all[0]
+})
+
+export function frameKey(page: string, frame: Pick<Frame, 'file'>): string {
+  return `${page}/${frame.file}`
+}
+
+export function frameTheme(key: string): Theme {
+  return frameThemes.value.get(key) ?? theme.value
+}
+
+export function toggleTheme(): void {
+  themeChoice.value = theme.value === 'dark' ? 'light' : 'dark'
+}
+
+export function toggleFrameTheme(key: string): void {
+  const next = new Map(frameThemes.value)
+  next.set(key, frameTheme(key) === 'dark' ? 'light' : 'dark')
+  frameThemes.value = next
+}
+
+export function applyRecord(record: PagesRecord): void {
+  pages.value = record.pages
+  tokens.value = record.tokens
+  loadError.value = undefined
+  isLoaded.value = true
+}
+
+export async function loadPages(
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  try {
+    const response = await fetchImpl('/api/pages')
+    if (!response.ok) throw new Error(`status ${response.status}`)
+    applyRecord((await response.json()) as PagesRecord)
+  } catch (error) {
+    loadError.value = `Could not read the canvas (${error instanceof Error ? error.message : 'unknown'}). Check canon canvas serve is still running.`
+    isLoaded.value = true
+  }
+}
+
+/**
+ * Reloads the one frame whose file changed and rereads the page list, which
+ * picks up an added frame or a moved box. The view is separate state, so
+ * neither resets pan or zoom.
+ */
+export async function applyChange(
+  change: ChangeEvent,
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  if (change.file.endsWith('.html')) {
+    const key = `${change.page}/${change.file}`
+    const next = new Map(frameVersions.value)
+    next.set(key, (next.get(key) ?? 0) + 1)
+    frameVersions.value = next
+  }
+  await loadPages(fetchImpl)
+}
+
+export function clampZoom(zoom: number): number {
+  return Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, zoom))
+}
+
+/** Zooms about a point in surface coordinates, keeping that point still. */
+export function zoomAt(factor: number, originX: number, originY: number): void {
+  const current = view.value
+  const zoom = clampZoom(current.zoom * factor)
+  const scale = zoom / current.zoom
+  view.value = {
+    zoom,
+    x: originX - (originX - current.x) * scale,
+    y: originY - (originY - current.y) * scale,
+  }
+}
+
+export function panBy(dx: number, dy: number): void {
+  const current = view.value
+  view.value = { ...current, x: current.x + dx, y: current.y + dy }
+}
+
+/** Fits every frame on the current page into a viewport of the given size. */
+export function fitView(width: number, height: number, padding = 48): void {
+  const frames = currentPage.value?.frames ?? []
+  if (frames.length === 0 || width <= 0 || height <= 0) {
+    view.value = { x: padding, y: padding, zoom: 0.5 }
+    return
+  }
+  const left = Math.min(...frames.map((frame) => frame.x))
+  const top = Math.min(...frames.map((frame) => frame.y))
+  const right = Math.max(...frames.map((frame) => frame.x + frame.width))
+  const bottom = Math.max(...frames.map((frame) => frame.y + frame.height))
+  const zoom = clampZoom(
+    Math.min(
+      (width - padding * 2) / (right - left),
+      (height - padding * 2) / (bottom - top),
+      1,
+    ),
+  )
+  view.value = {
+    zoom,
+    x: padding - left * zoom,
+    y: padding - top * zoom,
+  }
+}
+
+/** Centers one frame in a viewport of the given size at the current zoom. */
+export function focusFrame(frame: Frame, width: number, height: number): void {
+  const { zoom } = view.value
+  view.value = {
+    zoom,
+    x: width / 2 - (frame.x + frame.width / 2) * zoom,
+    y: height / 2 - (frame.y + frame.height / 2) * zoom,
+  }
+}
+
+/** Puts every signal back to its first value. Tests call it between cases. */
+export function resetState(): void {
+  pages.value = []
+  tokens.value = undefined
+  isLoaded.value = false
+  loadError.value = undefined
+  selectedPage.value = undefined
+  themeChoice.value = undefined
+  systemTheme.value = 'dark'
+  frameThemes.value = new Map()
+  frameVersions.value = new Map()
+  view.value = { x: 0, y: 0, zoom: 0.5 }
+}

package/src/canvas/client/surface.tsx

@@ -0,0 +1,213 @@
+/** @jsxImportSource preact */
+import type { JSX, RefObject } from 'preact'
+import { useEffect, useRef } from 'preact/hooks'
+import type { Frame } from '@/canvas/content'
+import {
+  currentPage,
+  fitView,
+  frameKey,
+  frameTheme,
+  frameVersions,
+  panBy,
+  type Theme,
+  toggleFrameTheme,
+  view,
+  zoomAt,
+} from '@/canvas/client/state'
+
+/** One wheel notch or one button press. */
+const ZOOM_STEP = 1.2
+
+export interface SurfaceProps {
+  readonly viewportRef: RefObject<HTMLDivElement | null>
+}
+
+export function frameSrc(page: string, frame: Frame, version: number): string {
+  const path = `/frames/${encodeURIComponent(page)}/${encodeURIComponent(frame.file)}`
+  return version === 0 ? path : `${path}?v=${version}`
+}
+
+/**
+ * Sets the frame document's theme the way the token stylesheet reads it. The
+ * frame shares the shell's origin, so its document is reachable once loaded.
+ */
+function applyFrameTheme(iframe: HTMLIFrameElement | null, value: Theme): void {
+  const root = iframe?.contentDocument?.documentElement
+  if (!root) return
+  root.dataset.theme = value
+  root.style.colorScheme = value
+}
+
+function FrameView({
+  page,
+  frame,
+}: {
+  readonly page: string
+  readonly frame: Frame
+}): JSX.Element {
+  const key = frameKey(page, frame)
+  const version = frameVersions.value.get(key) ?? 0
+  const value = frameTheme(key)
+  const iframe = useRef<HTMLIFrameElement>(null)
+
+  useEffect(() => {
+    applyFrameTheme(iframe.current, value)
+  }, [value])
+
+  const next = value === 'dark' ? 'light' : 'dark'
+  return (
+    <figure
+      class="frame"
+      data-frame={frame.name}
+      style={{
+        left: `${frame.x}px`,
+        top: `${frame.y}px`,
+        width: `${frame.width}px`,
+      }}
+    >
+      <figcaption class="frame-label">
+        <span class="frame-name" title={frame.name}>
+          {frame.name}
+        </span>
+        <span class="frame-size">
+          {frame.width} × {frame.height}
+        </span>
+        <button
+          type="button"
+          class="frame-theme"
+          aria-label={`Show ${frame.name} in ${next} theme`}
+          title={`Show in ${next} theme`}
+          onClick={() => toggleFrameTheme(key)}
+        >
+          {value === 'dark' ? 'Dark' : 'Light'}
+        </button>
+      </figcaption>
+      <iframe
+        ref={iframe}
+        title={frame.name}
+        src={frameSrc(page, frame, version)}
+        width={frame.width}
+        height={frame.height}
+        style={{ height: `${frame.height}px` }}
+        onLoad={() => applyFrameTheme(iframe.current, frameTheme(key))}
+      />
+    </figure>
+  )
+}
+
+function viewportSize(viewport: RefObject<HTMLDivElement | null>): {
+  width: number
+  height: number
+} {
+  const rect = viewport.current?.getBoundingClientRect()
+  return { width: rect?.width ?? 0, height: rect?.height ?? 0 }
+}
+
+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)}
+      >
+        −
+      </button>
+      <output class="zoom" aria-live="polite">
+        {Math.round(view.value.zoom * 100)}%
+      </output>
+      <button
+        type="button"
+        class="icon-button"
+        aria-label="Zoom in"
+        onClick={() => zoomCentered(ZOOM_STEP)}
+      >
+        +
+      </button>
+      <button
+        type="button"
+        class="text-button"
+        onClick={() => {
+          const { width, height } = viewportSize(viewportRef)
+          fitView(width, height)
+        }}
+      >
+        Fit
+      </button>
+    </div>
+  )
+}
+
+export function Surface({ viewportRef }: SurfaceProps): JSX.Element {
+  const page = currentPage.value
+  const drag = useRef<{ x: number; y: number } | undefined>(undefined)
+
+  /* Fits a page once when it opens, never on a reload of the same page. */
+  useEffect(() => {
+    const { width, height } = viewportSize(viewportRef)
+    fitView(width, height)
+  }, [page?.name])
+
+  const handleWheel = (event: WheelEvent) => {
+    event.preventDefault()
+    if (event.ctrlKey || event.metaKey) {
+      const rect = viewportRef.current?.getBoundingClientRect()
+      const factor = event.deltaY < 0 ? ZOOM_STEP : 1 / ZOOM_STEP
+      zoomAt(
+        factor,
+        event.clientX - (rect?.left ?? 0),
+        event.clientY - (rect?.top ?? 0),
+      )
+      return
+    }
+    panBy(-event.deltaX, -event.deltaY)
+  }
+
+  const handlePointerDown = (event: PointerEvent) => {
+    const target = event.target as HTMLElement | null
+    if (target?.closest('.frame, .toolbar')) return
+    drag.current = { x: event.clientX, y: event.clientY }
+    viewportRef.current?.setPointerCapture?.(event.pointerId)
+  }
+
+  const handlePointerMove = (event: PointerEvent) => {
+    const start = drag.current
+    if (!start) return
+    panBy(event.clientX - start.x, event.clientY - start.y)
+    drag.current = { x: event.clientX, y: event.clientY }
+  }
+
+  const handlePointerUp = () => {
+    drag.current = undefined
+  }
+
+  const { x, y, zoom } = view.value
+  return (
+    <main class="surface" aria-label="Canvas">
+      <div
+        ref={viewportRef}
+        class="viewport"
+        onWheel={handleWheel}
+        onPointerDown={handlePointerDown}
+        onPointerMove={handlePointerMove}
+        onPointerUp={handlePointerUp}
+        onPointerCancel={handlePointerUp}
+      >
+        <div
+          class="plane"
+          style={{ transform: `translate(${x}px, ${y}px) scale(${zoom})` }}
+        >
+          {page?.frames.map((frame) => (
+            <FrameView key={frame.name} page={page.name} frame={frame} />
+          ))}
+        </div>
+      </div>
+      <Toolbar viewportRef={viewportRef} />
+    </main>
+  )
+}