@erclx/canon 5.17.0 → 5.19.0

package/src/canvas/client/state.ts

@@ -1,6 +1,7 @@
 import { computed, signal } from '@preact/signals'
 import type { ElementAddress } from '@/canvas/address'
 import type { Frame, Page } from '@/canvas/content'
+import type { TokenGroup } from '@/canvas/tokens'
 
 /**
  * Everything the panels read. Type imports only from outside `client/`, since
@@ -15,6 +16,17 @@ export interface TokenSource {
   readonly source: 'toolkit' | 'installed' | 'none'
   readonly files?: readonly string[]
   readonly notice?: string
+  /** What the stylesheet defines, which the token picker and Theme tab list. */
+  readonly groups?: readonly TokenGroup[]
+}
+
+export type LeftTab = 'pages' | 'theme'
+
+/** One property change to the selected element, as the inspector posts it. */
+export interface PendingEdit {
+  readonly key: string
+  readonly index: number
+  readonly property: string
 }
 
 export interface FrameRef {
@@ -98,6 +110,26 @@ export const draggingFrame = signal<string | undefined>(undefined)
 /** Why the last write to the canvas failed, until the next one succeeds. */
 export const writeError = signal<string | undefined>(undefined)
 
+export const leftTab = signal<LeftTab>('pages')
+
+/** The edit in flight, which holds its field until the server answers. */
+export const pendingEdit = signal<PendingEdit | undefined>(undefined)
+
+/** The edit that last landed, for a moment after it does. */
+export const savedEdit = signal<PendingEdit | undefined>(undefined)
+
+const SAVED_MS = 2500
+
+/** Why the last edit wrote nothing, until the next one lands. */
+export const editRefusal = signal<string | undefined>(undefined)
+
+/**
+ * The hash an edit answered by frame key, until that frame reloads. A second
+ * edit sent before the reload is made from the file the first one wrote, not
+ * from the document still on screen.
+ */
+export const editedHashes = signal<ReadonlyMap<string, string>>(new Map())
+
 export const currentPage = computed<Page | undefined>(() => {
   const all = pages.value
   return all.find((page) => page.name === selectedPage.value) ?? all[0]
@@ -142,6 +174,17 @@ export function registerFrameDocument(key: string, doc: Document): void {
   const next = new Map(frameDocuments.value)
   next.set(key, doc)
   frameDocuments.value = next
+  if (editedHashes.value.has(key)) {
+    const hashes = new Map(editedHashes.value)
+    hashes.delete(key)
+    editedHashes.value = hashes
+  }
+}
+
+function reloadFrame(key: string): void {
+  const next = new Map(frameVersions.value)
+  next.set(key, (next.get(key) ?? 0) + 1)
+  frameVersions.value = next
 }
 
 export function toggleLayers(key: string): void {
@@ -181,10 +224,7 @@ export async function applyChange(
   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
+    reloadFrame(`${change.page}/${change.file}`)
   }
   await loadPages(fetchImpl)
 }
@@ -267,6 +307,77 @@ export async function selectElement(
   await write('/api/selection', { ...ref, element: address }, fetchImpl)
 }
 
+/** What a refused edit tells the operator, by the server's reason. */
+const EDIT_NOTICES: Readonly<Record<string, string | undefined>> = {
+  'stale-address':
+    'The frame changed before this edit arrived, so nothing was saved. It reloads with the file as it stands now. Make the edit again there.',
+  'address-mismatch':
+    'Could not save, since the browser and the file count the elements of this frame differently.',
+  'not-text-only':
+    'Could not save the text, since this element holds other elements.',
+}
+
+/**
+ * Posts one property change to the element the address names. A refusal
+ * says why and reloads the frame, so a pending value never sits over a file
+ * that moved under it.
+ */
+export async function editElement(
+  ref: FrameRef,
+  key: string,
+  address: ElementAddress,
+  property: string,
+  value: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  const hash = editedHashes.value.get(key) ?? address.hash
+  pendingEdit.value = { key, index: address.index, property }
+  try {
+    const response = await fetchImpl('/api/frames/edit', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        ...ref,
+        element: { ...address, hash },
+        property,
+        value,
+      }),
+    })
+    const body: unknown = await response.json().catch(() => undefined)
+    const record =
+      typeof body === 'object' && body !== null
+        ? (body as Record<string, unknown>)
+        : {}
+    if (!response.ok) {
+      const reason = typeof record.reason === 'string' ? record.reason : ''
+      const detail = typeof record.detail === 'string' ? record.detail : ''
+      editRefusal.value =
+        EDIT_NOTICES[reason] ??
+        (reason === 'invalid-edit'
+          ? `Could not save that value (${detail}).`
+          : `Could not save (status ${response.status}). Check canon canvas serve is still running.`)
+      reloadFrame(key)
+      await loadPages(fetchImpl)
+      return
+    }
+    editRefusal.value = undefined
+    const saved = pendingEdit.value
+    savedEdit.value = saved
+    setTimeout(() => {
+      if (savedEdit.value === saved) savedEdit.value = undefined
+    }, SAVED_MS)
+    if (typeof record.hash === 'string') {
+      const hashes = new Map(editedHashes.value)
+      hashes.set(key, record.hash)
+      editedHashes.value = hashes
+    }
+  } catch (error) {
+    editRefusal.value = `Could not save (${error instanceof Error ? error.message : 'unknown'}). Check canon canvas serve is still running.`
+  } finally {
+    pendingEdit.value = undefined
+  }
+}
+
 /**
  * Moves a frame on the surface without writing, which a drag calls on every
  * pointer move. The next reread replaces it with what the layout holds.
@@ -369,4 +480,9 @@ export function resetState(): void {
   expandedFrames.value = new Set()
   draggingFrame.value = undefined
   writeError.value = undefined
+  leftTab.value = 'pages'
+  pendingEdit.value = undefined
+  savedEdit.value = undefined
+  editRefusal.value = undefined
+  editedHashes.value = new Map()
 }

package/src/canvas/client/theme-panel.tsx

@@ -0,0 +1,55 @@
+/** @jsxImportSource preact */
+import type { JSX } from 'preact'
+import { tokens } from '@/canvas/client/state'
+import type { Token, TokenKind } from '@/canvas/tokens'
+
+const KIND_LABEL: Record<TokenKind, string> = {
+  color: 'Color',
+  spacing: 'Spacing',
+  radius: 'Radius',
+  'font-family': 'Font family',
+  'font-size': 'Font size',
+  other: 'Other',
+}
+
+/**
+ * A swatch paints the value in the chrome's document, where the frame's own
+ * custom properties are not defined, so a value still naming one shows none.
+ */
+function Swatch({ token }: { readonly token: Token }): JSX.Element | null {
+  const paint = token.resolved ?? token.value
+  if (paint.includes('var(')) return null
+  return (
+    <span class="swatch" aria-hidden="true" style={{ background: paint }} />
+  )
+}
+
+/** Read-only: the frames' tokens are edited in their stylesheet, not here. */
+export function ThemePanel(): JSX.Element {
+  const groups = tokens.value?.groups ?? []
+  return (
+    <section aria-label="Theme">
+      {groups.length === 0 ? (
+        <p class="empty">
+          No tokens resolve for this project, so there is nothing to list.{' '}
+          {tokens.value?.notice ?? ''}
+        </p>
+      ) : (
+        groups.map((group) => (
+          <div key={group.kind}>
+            <h2 class="section-label">{KIND_LABEL[group.kind]}</h2>
+            <ul class="tokens" aria-label={`${KIND_LABEL[group.kind]} tokens`}>
+              {group.tokens.map((token) => (
+                <li key={token.name} class="token" title={token.value}>
+                  {group.kind === 'color' ? <Swatch token={token} /> : null}
+                  <span class="row-label">{token.name}</span>
+                  <span class="row-meta token-value">{token.value}</span>
+                </li>
+              ))}
+            </ul>
+          </div>
+        ))
+      )}
+    </section>
+  )
+}

package/src/canvas/content.ts

@@ -12,7 +12,7 @@ import {
   unlinkSync,
   writeFileSync,
 } from 'node:fs'
-import { join } from 'node:path'
+import { basename, join } from 'node:path'
 import {
   type ElementAddress,
   resolveAddress,
@@ -200,7 +200,18 @@ function sleep(ms: number): void {
  * found it.
  */
 function withLayoutLock(dir: string, run: () => FrameOutcome): FrameOutcome {
-  const lock = join(dir, `${LAYOUT_FILE}${LOCK_SUFFIX}`)
+  return withFileLock(join(dir, LAYOUT_FILE), run)
+}
+
+/**
+ * The same lock over any one file under the canvas folder, which a frame
+ * writer takes so its hash check and its write cannot straddle another's.
+ */
+export function withFileLock<T>(
+  target: string,
+  run: () => T,
+): T | ContentRefused {
+  const lock = `${target}${LOCK_SUFFIX}`
   const deadline = Date.now() + LOCK_WAIT_MS
   for (;;) {
     try {
@@ -214,7 +225,7 @@ function withLayoutLock(dir: string, run: () => FrameOutcome): FrameOutcome {
         continue
       }
       if (Date.now() >= deadline) {
-        return refuse('busy', `${LAYOUT_FILE} is being written, try again`)
+        return refuse('busy', `${basename(target)} is being written, try again`)
       }
       sleep(LOCK_POLL_MS)
     }

package/src/canvas/edit.ts

@@ -0,0 +1,360 @@
+import { readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  countElements,
+  type ElementAddress,
+  isRawText,
+  resolveAddress,
+  sourceElements,
+} from '@/canvas/address'
+import {
+  type ContentRefusal,
+  canvasDir,
+  contentHash,
+  readPage,
+  readSelection,
+  TEMP_SUFFIX,
+  withFileLock,
+  writeSelection,
+} from '@/canvas/content'
+
+/**
+ * The basic set an operator edits by hand. Each is a CSS property written into
+ * the element's inline style, except `text`, which replaces its text.
+ */
+export const STYLE_PROPERTIES = [
+  'color',
+  'background-color',
+  'font-size',
+  'font-weight',
+  'width',
+  'height',
+  'padding',
+  'gap',
+  'flex-direction',
+] as const
+
+export type StyleProperty = (typeof STYLE_PROPERTIES)[number]
+
+export type EditProperty = StyleProperty | 'text'
+
+export interface EditChange {
+  readonly property: string
+  /** Empty drops a style property, and sets an element's text to nothing. */
+  readonly value: string
+}
+
+export type EditRefusal = ContentRefusal | 'invalid-edit' | 'not-text-only'
+
+export interface EditRefused {
+  readonly ok: false
+  readonly reason: EditRefusal
+  readonly detail: string
+}
+
+export type AppliedEdit = { readonly ok: true; readonly html: string }
+
+export type FrameEdit =
+  | {
+      readonly ok: true
+      readonly page: string
+      readonly frame: string
+      readonly file: string
+      /** The file's hash after the edit, which the next edit is made from. */
+      readonly hash: string
+    }
+  | EditRefused
+
+const MAX_VALUE_LENGTH = 200
+
+/** Anything that would end the declaration and start another. */
+const DECLARATION_BREAK = /[;{}<>\n\r]/
+
+const BOM = ''
+
+function refuse(reason: EditRefusal, detail: string): EditRefused {
+  return { ok: false, reason, detail }
+}
+
+function isStyleProperty(property: string): property is StyleProperty {
+  return (STYLE_PROPERTIES as readonly string[]).includes(property)
+}
+
+export function isEditProperty(property: string): property is EditProperty {
+  return property === 'text' || isStyleProperty(property)
+}
+
+function checkChange(change: EditChange): EditRefused | undefined {
+  if (!isEditProperty(change.property)) {
+    return refuse(
+      'invalid-edit',
+      `${change.property} is not editable here. Edit one of text, ${STYLE_PROPERTIES.join(', ')}`,
+    )
+  }
+  if (change.value.length > MAX_VALUE_LENGTH) {
+    return refuse(
+      'invalid-edit',
+      `the value runs past ${MAX_VALUE_LENGTH} characters`,
+    )
+  }
+  if (change.property !== 'text' && DECLARATION_BREAK.test(change.value)) {
+    return refuse(
+      'invalid-edit',
+      `${change.property} takes one value, with no ; { } < > or line break`,
+    )
+  }
+  return undefined
+}
+
+/**
+ * Splits a style attribute at each semicolon outside parentheses and quotes,
+ * keeping every segment's own spacing so an untouched one is written back as
+ * it was.
+ */
+function declarations(style: string): string[] {
+  const segments: string[] = []
+  let depth = 0
+  let quote: string | undefined
+  let start = 0
+  for (let at = 0; at < style.length; at += 1) {
+    const char = style[at]
+    if (quote) {
+      if (char === quote) quote = undefined
+    } else if (char === '"' || char === "'") quote = char
+    else if (char === '(') depth += 1
+    else if (char === ')') depth = Math.max(0, depth - 1)
+    else if (char === ';' && depth === 0) {
+      segments.push(style.slice(start, at))
+      start = at + 1
+    }
+  }
+  segments.push(style.slice(start))
+  return segments
+}
+
+function propertyOf(segment: string): string {
+  return segment.split(':', 1)[0]?.trim().toLowerCase() ?? ''
+}
+
+/**
+ * Sets one property in a style attribute, or drops it on an empty value. The
+ * first declaration of it is replaced in place and any later one dropped, so
+ * nothing further in the attribute overrides the edit. Undefined means no
+ * style is left.
+ */
+export function setDeclaration(
+  style: string,
+  property: StyleProperty,
+  value: string,
+): string | undefined {
+  const segments = declarations(style)
+  const matches = segments.filter((segment) => propertyOf(segment) === property)
+  const declaration = `${property}: ${value.trim()}`
+
+  let next: string[]
+  if (value.trim() === '') {
+    next = segments.filter((segment) => propertyOf(segment) !== property)
+  } else if (matches.length > 0) {
+    let isReplaced = false
+    next = segments.flatMap((segment) => {
+      if (propertyOf(segment) !== property) return [segment]
+      if (isReplaced) return []
+      isReplaced = true
+      const lead = segment.match(/^\s*/)?.[0] ?? ''
+      return [`${lead}${declaration}`]
+    })
+  } else {
+    const kept = style.replace(/[\s;]*$/, '')
+    return kept === '' ? declaration : `${kept}; ${declaration}`
+  }
+
+  if (next.every((segment) => segment.trim() === '')) return undefined
+  return next.join(';').replace(/^[\s;]+/, '')
+}
+
+/**
+ * Whether the element at an index holds text alone, so replacing its text
+ * flattens no nested markup. An element closed only by implication stays open
+ * to the end and reads as holding everything after it, which refuses.
+ */
+function holdsTextAlone(html: string, index: number): boolean {
+  let isOpen = false
+  let hasChild = false
+  countElements(new HTMLRewriter(), (_element, at) => {
+    if (isOpen) hasChild = true
+    if (at !== index) return undefined
+    isOpen = true
+    return () => {
+      isOpen = false
+    }
+  }).transform(html)
+  return !hasChild
+}
+
+/**
+ * Applies one change to the element the address names and leaves every other
+ * byte of the file as it was. The address is checked against the file first,
+ * the same way a pick is.
+ */
+export function applyEdit(
+  source: string,
+  address: ElementAddress,
+  change: EditChange,
+): AppliedEdit | EditRefused {
+  const invalid = checkChange(change)
+  if (invalid) return invalid
+
+  /* The rewriter drops a leading byte order mark, so it is put back after. */
+  const bom = source.startsWith(BOM) ? BOM : ''
+  const html = source.slice(bom.length)
+
+  const check = resolveAddress(html, address)
+  if (!check.ok) return refuse(check.reason, check.detail)
+
+  const { property, value } = change
+  if (property === 'text') {
+    if (isRawText(address.tag) || !holdsTextAlone(html, address.index)) {
+      return refuse(
+        'not-text-only',
+        `<${address.tag}> holds other elements or raw content, so its text is not edited as one string`,
+      )
+    }
+  }
+
+  let voidRefused = false
+  const rewritten = countElements(new HTMLRewriter(), (element, at) => {
+    if (at !== address.index) return undefined
+    if (property === 'text') {
+      if (!element.canHaveContent || element.selfClosing) {
+        voidRefused = true
+        return undefined
+      }
+      element.setInnerContent(value, { html: false })
+      return undefined
+    }
+    if (!isStyleProperty(property)) return undefined
+    const style = setDeclaration(
+      element.getAttribute('style') ?? '',
+      property,
+      value,
+    )
+    if (style === undefined) element.removeAttribute('style')
+    else element.setAttribute('style', style)
+    return undefined
+  }).transform(html)
+
+  if (voidRefused) {
+    return refuse('not-text-only', `<${address.tag}> cannot hold text`)
+  }
+  return { ok: true, html: `${bom}${rewritten}` }
+}
+
+/**
+ * Edits one element of a frame file under the file's lock. An address carrying
+ * a hash the file no longer has is refused rather than applied at an index the
+ * change may have shifted. A selection that was fresh before the edit is
+ * restamped after it, since the edit moves no element.
+ */
+export function editFrame(
+  root: string,
+  page: string,
+  frame: string,
+  address: ElementAddress,
+  change: EditChange,
+): FrameEdit {
+  const invalid = checkChange(change)
+  if (invalid) return invalid
+
+  const onPage = readPage(root, page)
+  if (!onPage) return refuse('no-page', `page ${page} does not exist`)
+  const found = onPage.frames.find((candidate) => candidate.name === frame)
+  if (!found) {
+    return refuse('no-frame', `frame ${frame} does not exist on ${page}`)
+  }
+
+  const path = join(canvasDir(root), page, found.file)
+  return withFileLock(path, (): FrameEdit => {
+    const bytes = readFileSync(path)
+    if (address.hash !== undefined && address.hash !== contentHash(bytes)) {
+      return refuse(
+        'stale-address',
+        `${page}/${frame} changed after this edit was made, so nothing was written`,
+      )
+    }
+    const before = readSelection(root)
+    const isSelectionFresh =
+      before?.page === page &&
+      before.frame === frame &&
+      before.element !== undefined &&
+      !before.element.stale
+
+    const applied = applyEdit(bytes.toString('utf8'), address, change)
+    if (!applied.ok) return applied
+
+    const temp = `${path}.${process.pid}${TEMP_SUFFIX}`
+    writeFileSync(temp, applied.html)
+    renameSync(temp, path)
+
+    if (isSelectionFresh && before.element) {
+      writeSelection(root, {
+        page,
+        frame,
+        element: {
+          index: before.element.index,
+          tag: before.element.tag,
+          count: sourceElements(applied.html).length,
+        },
+      })
+    }
+    return {
+      ok: true,
+      page,
+      frame,
+      file: found.file,
+      hash: contentHash(applied.html),
+    }
+  })
+}
+
+/**
+ * Edits the element at an index of the file as it stands, for a caller that
+ * holds no served frame to take an address from. The address it builds
+ * carries the hash it read, so a write landing between the read and the lock
+ * still refuses.
+ */
+export function editFrameAtIndex(
+  root: string,
+  page: string,
+  frame: string,
+  index: number,
+  change: EditChange,
+): FrameEdit {
+  const onPage = readPage(root, page)
+  if (!onPage) return refuse('no-page', `page ${page} does not exist`)
+  const found = onPage.frames.find((candidate) => candidate.name === frame)
+  if (!found) {
+    return refuse('no-frame', `frame ${frame} does not exist on ${page}`)
+  }
+
+  const bytes = readFileSync(join(canvasDir(root), page, found.file))
+  const elements = sourceElements(bytes.toString('utf8'))
+  const element = Number.isInteger(index) ? elements[index] : undefined
+  if (!element) {
+    return refuse(
+      'invalid-address',
+      `${page}/${frame} holds elements 0 to ${elements.length - 1}, so ${index} names none`,
+    )
+  }
+  return editFrame(
+    root,
+    page,
+    frame,
+    {
+      index,
+      tag: element.tag,
+      count: elements.length,
+      hash: contentHash(bytes),
+    },
+    change,
+  )
+}