@lincyaw/workbench 0.0.0-stage → 0.2.0-rc.0

package/src/outline.ts

@@ -0,0 +1,97 @@
+import type { IRDocument, MdastNode, TeachingDocument } from '@lincyaw/kernel'
+
+/** A section as the navigation pane lists it: in the slides each section is one slide, numbered from 1. */
+export interface OutlineItem {
+  id: string
+  title: string
+  depth: number
+  number: number
+}
+
+export function documentOutline(doc: IRDocument | TeachingDocument | undefined): OutlineItem[] {
+  if (doc && 'schemaVersion' in doc) return doc.sectionOrder.map((id, index) => ({ id, title: doc.sections[id]!.title, depth: doc.sections[id]!.level ?? 1, number: index + 1 }))
+  return (doc?.sections ?? []).map((section, i) => ({ id: section.id, title: section.title, depth: section.depth, number: i + 1 }))
+}
+
+/** A stable display snapshot lets navigation ignore changes to the document body. */
+export class DocumentOutline {
+  #identity?: string
+  #items: readonly OutlineItem[] = []
+
+  read(document: TeachingDocument | undefined, identity = document?.id): readonly OutlineItem[] {
+    const items = documentOutline(document)
+    if (identity !== this.#identity || items.length !== this.#items.length || items.some((item, index) => {
+      const previous = this.#items[index]!
+      return item.id !== previous.id || item.title !== previous.title || item.depth !== previous.depth || item.number !== previous.number
+    })) {
+      this.#identity = identity
+      this.#items = items
+    }
+    return this.#items
+  }
+}
+
+// As a word processor counts: each CJK character is a word, and so is each run of Latin letters or digits.
+const CJK = /[぀-ヿ㐀-䶿一-鿿가-힯豈-﫿]/g
+const WORD = /[A-Za-z0-9À-ɏ]+(?:['’.-][A-Za-z0-9À-ɏ]+)*/g
+
+function countText(text: string): number {
+  return (text.match(CJK)?.length ?? 0) + (text.replace(CJK, ' ').match(WORD)?.length ?? 0)
+}
+
+function countNode(node: MdastNode): number {
+  const own = (node.type === 'text' || node.type === 'inlineCode') && typeof node.value === 'string' ? countText(node.value) : 0
+  return own + (node.children ?? []).reduce((sum, child) => sum + countNode(child), 0)
+}
+
+function richTextParts(value: unknown, parts: string[] = []): string[] {
+  if (!value || typeof value !== 'object') return parts
+  if (Array.isArray(value)) { for (const child of value) richTextParts(child, parts); return parts }
+  const node = value as { type?: string, text?: string, children?: unknown[], fallback?: unknown }
+  if (node.type === 'code') return parts
+  if (node.type === 'text' && node.text) parts.push(node.text)
+  richTextParts(node.children, parts); richTextParts(node.fallback, parts)
+  return parts
+}
+
+/** Counts authored titles and rich text; code, components and separate narration are excluded. */
+export function countWords(doc: IRDocument | TeachingDocument | undefined): number {
+  if (doc && 'schemaVersion' in doc) {
+    return doc.sectionOrder.reduce((sum, id) => sum + countText(doc.sections[id]!.title), 0) + Object.values(doc.blocks).reduce((sum, block) => sum + (block.type === 'text' ? richTextParts(block.content).reduce((sum, text) => sum + countText(text), 0) : 0), 0)
+  }
+  let words = 0
+  for (const section of doc?.sections ?? []) {
+    words += countText(section.title)
+    for (const block of section.blocks) if (block.node.type === 'markdown') words += countNode(block.node.mdast)
+  }
+  return words
+}
+
+/** Display-only counts, bounded to the current document's titles and text blocks. */
+export class DocumentWordCounter {
+  #identity?: string
+  readonly #counts = new Map<string, { signature: string, words: number }>()
+
+  count(doc: TeachingDocument | undefined, identity = doc?.id): number {
+    if (identity !== this.#identity || !doc) { this.#counts.clear(); this.#identity = identity }
+    if (!doc) return 0
+    const unused = new Set(this.#counts.keys())
+    const read = (key: string, signature: string, count: () => number): number => {
+      unused.delete(key)
+      let found = this.#counts.get(key)
+      if (found?.signature !== signature) { found = { signature, words: count() }; this.#counts.set(key, found) }
+      return found.words
+    }
+    let words = 0
+    for (const id of doc.sectionOrder) {
+      const title = doc.sections[id]!.title
+      words += read(`title:${id}`, title, () => countText(title))
+    }
+    for (const block of Object.values(doc.blocks)) if (block.type === 'text') {
+      const texts = richTextParts(block.content)
+      words += read(`body:${block.id}`, JSON.stringify(texts), () => texts.reduce((sum, text) => sum + countText(text), 0))
+    }
+    for (const key of unused) this.#counts.delete(key)
+    return words
+  }
+}

package/src/panels/ChangeTrail.tsx

@@ -0,0 +1,79 @@
+import { useEffect, useRef, useState } from 'react'
+import type { CSSProperties, RefObject } from 'react'
+import type { MascotAction } from '@lincyaw/design/mascot'
+import { PmMascot } from '../components.tsx'
+import { useMascotEnabled } from '../mascot-preference.ts'
+import { useWorkbenchState } from '../context.tsx'
+import { pageId, richNodeIds } from '../document-editor/projection.ts'
+
+/** How long the kitten walks from one changed place to the next, pats it, and stays when it is done (ms). */
+const WALK_MS = 700, PAT_MS = 900, DONE_MS = 2200
+/** At most this many changed places are visited. */
+const STOPS = 6
+
+type Point = { x: number, y: number }
+type Phase = 'walk' | 'pat' | 'done' | 'gone'
+
+/**
+ * The kitten visiting a list of points in its host (each the lower left of a changed place): it walks to each, pats it,
+ * hops when it is done and leaves. A new `id` starts it again from the first point; `where(i)` is asked on every
+ * render, so the kitten follows the places as the host lays out again. Nothing shows when the kitten is turned off.
+ */
+function KittenTrail({ id, count, where }: { id: number | undefined, count: number, where(index: number): Point | undefined }) {
+  const enabled = useMascotEnabled()
+  const [step, setStep] = useState<{ id: number, stop: number, phase: Phase }>()
+  const facing = useRef<'left' | 'right'>('right'), last = useRef<Point>()
+  useEffect(() => {
+    if (id !== undefined && count > 0) setStep(current => current?.id === id ? current : { id, stop: 0, phase: 'walk' })
+  }, [id, count])
+  useEffect(() => {
+    if (!step || step.phase === 'gone') return
+    const stops = Math.min(STOPS, count)
+    const next: typeof step = step.phase === 'walk' ? { ...step, phase: 'pat' }
+      : step.phase === 'pat' ? (step.stop + 1 < stops ? { ...step, stop: step.stop + 1, phase: 'walk' } : { ...step, phase: 'done' })
+        : { ...step, phase: 'gone' }
+    const timer = setTimeout(() => setStep(next), step.phase === 'walk' ? WALK_MS : step.phase === 'pat' ? PAT_MS : DONE_MS)
+    return () => clearTimeout(timer)
+  }, [step, count])
+  if (!enabled || !step || step.phase === 'gone' || step.id !== id) return null
+  const point = where(Math.min(step.stop, count - 1))
+  if (!point) return null
+  if (last.current && Math.abs(point.x - last.current.x) > 2 && step.phase === 'walk') facing.current = point.x < last.current.x ? 'left' : 'right'
+  if (step.phase === 'walk') last.current = point
+  const action: MascotAction = step.phase === 'walk' ? 'walk' : step.phase === 'pat' ? 'write' : 'done'
+  return (
+    <div className="pmw-change-trail" data-phase={step.phase} style={{ '--pmw-trail-x': `${point.x}px`, '--pmw-trail-y': `${point.y}px` } as CSSProperties}>
+      <div className="pmw-change-trail__facing" data-facing={facing.current}><PmMascot size="small" action={action} /></div>
+    </div>
+  )
+}
+
+/** In the preview: the blocks the preview reports blinking, in the active frame's viewport. */
+export function PreviewChangeTrail({ stage, frames }: { stage: RefObject<HTMLDivElement | null>, frames: RefObject<HTMLDivElement | null> }) {
+  const trail = useWorkbenchState(state => state.changeTrail)
+  return <KittenTrail id={trail?.id} count={trail?.rects.length ?? 0} where={index => {
+    const rect = trail?.rects[index]
+    const frame = frames.current?.querySelector<HTMLIFrameElement>('iframe[data-active="true"]:not([hidden])')
+    const host = stage.current
+    if (!rect || !frame || !host) return undefined
+    const offset = frame.getBoundingClientRect(), origin = host.getBoundingClientRect()
+    return { x: offset.left - origin.left + rect.x, y: offset.top - origin.top + rect.y + rect.height }
+  }} />
+}
+
+/** In the editor: each changed block (a text block by its first paragraph), else its page's title, on the sheet. */
+export function EditorChangeTrail({ sheet }: { sheet: RefObject<HTMLDivElement | null> }) {
+  const places = useWorkbenchState(state => state.changedPlaces)
+  const content = useWorkbenchState(state => state.authoring?.content)
+  return <KittenTrail id={places?.id} count={places?.targets.length ?? 0} where={index => {
+    const target = places?.targets[index], host = sheet.current
+    if (!target || !host) return undefined
+    const block = target.block ? content?.blocks[target.block] : undefined
+    const ids = [...target.block ? [target.block] : [], ...block?.type === 'text' ? richNodeIds(block.content) : [], pageId(target.section)]
+    const element = ids.map(id => host.querySelector<HTMLElement>(`[data-id="${CSS.escape(id)}"]`)).find(Boolean)
+    if (!element) return undefined
+    const box = element.getBoundingClientRect(), origin = host.getBoundingClientRect()
+    // the kitten stands on the place's first line, at its left edge
+    return { x: box.left - origin.left, y: box.top - origin.top + Math.min(box.height, 28) }
+  }} />
+}

package/src/panels/DocumentNarrationPanel.tsx

@@ -0,0 +1,27 @@
+import { useEffect, useId } from 'react'
+import { PmEmpty, PmIconButton } from '../components.tsx'
+import { useMessages, useWorkbench, useWorkbenchState } from '../context.tsx'
+import { DocumentStepNarration } from '../document-editor/DocumentStepNarration.tsx'
+
+/** The same step-bound fields are available even when a page has no runtime block. */
+export function DocumentNarrationPanel({ onClose }: { onClose(): void }) {
+  const workbench = useWorkbench(), t = useMessages(), panelId = useId()
+  const source = useWorkbenchState(state => state.authoring)
+  const position = useWorkbenchState(state => state.position)
+  const document = source?.content
+  const sectionId = position && document?.sections[position.section] ? position.section : document?.sectionOrder[0]
+  const section = sectionId ? document?.sections[sectionId] : undefined
+  const stepId = section?.stepOrder[position && position.section === sectionId ? position.step : 0] ?? section?.stepOrder[0]
+  const pause = () => {
+    if (sectionId && stepId) workbench.pauseDocumentStep(sectionId, stepId)
+    workbench.stopAuditions()
+  }
+  useEffect(() => { pause() }, [workbench, source?.identity])
+  return <section className="pmw-pane" aria-labelledby={panelId}>
+    <header className="pmw-pane__header"><h2 id={panelId} className="pmw-pane__title">{t.documentNarration}</h2><PmIconButton small icon="close" label={t.close} onClick={onClose} /></header>
+    {section && sectionId && stepId ? <>
+      <p className="pmw-pane__footer">{section.title}</p>
+      <DocumentStepNarration sectionId={sectionId} stepId={stepId} expanded showLabel={false} panelId={`${panelId}-fields`} onPause={pause} />
+    </> : <PmEmpty icon="captions">{t.noSections}</PmEmpty>}
+  </section>
+}