@bendyline/squisq-editor-react 1.5.3 → 1.6.1

package/src/blockRange.ts

@@ -0,0 +1,132 @@
+/**
+ * blockRange
+ *
+ * Source-text-range slicing for the block-at-a-time editing view. Splits a
+ * full markdown document into ordered, contiguous slices — one per
+ * heading-defined block plus an optional leading preamble — so a single
+ * block can be shown in isolation and edits spliced back into the parent.
+ *
+ * A block runs from its heading line through the character just before the
+ * next heading at ANY depth (or EOF). Sub-headings therefore start their own
+ * slices — they are NOT folded into their parent — which matches the
+ * "don't see child blocks" requirement and the `slicePastHeading` boundary
+ * in `blockSlice.ts`. Ranges are half-open `[startOffset, endOffset)` and
+ * line-aligned, so trailing blank lines stay with the current block and
+ * `spliceBlock(src, range, getBlockSlices(src)[i].text) === src` for every i.
+ *
+ * These are pure functions over a markdown string — no React, no editor
+ * coupling — so any host can reuse them.
+ */
+
+import { parseMarkdown } from '@bendyline/squisq/markdown';
+import type { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { frontmatterEndOffset } from './frontmatter';
+
+/** Half-open character range into the full source: `[startOffset, endOffset)`. */
+export interface BlockRange {
+  startOffset: number;
+  endOffset: number;
+}
+
+/** One block's source text plus the range it occupies in the full document. */
+export interface BlockSlice {
+  text: string;
+  range: BlockRange;
+}
+
+/** Map every line start to its character offset (`lineStarts[line - 1]`). */
+function computeLineStarts(source: string): number[] {
+  const starts = [0];
+  for (let i = 0; i < source.length; i++) {
+    if (source[i] === '\n') starts.push(i + 1);
+  }
+  return starts;
+}
+
+function makeSlice(source: string, startOffset: number, endOffset: number): BlockSlice {
+  return { text: source.slice(startOffset, endOffset), range: { startOffset, endOffset } };
+}
+
+/**
+ * Split `fullSource` into ordered block slices.
+ *
+ * - With no headings, the entire post-frontmatter body is a single slice
+ *   (so an empty or heading-less document still shows one editable card).
+ * - With headings, a leading preamble slice is included only when the text
+ *   before the first heading has non-whitespace content. Each heading then
+ *   yields one slice spanning up to the next heading (any depth) or EOF.
+ *
+ * Frontmatter is never part of any slice — slices start at the body offset.
+ */
+export function getBlockSlices(fullSource: string): BlockSlice[] {
+  const bodyStart = frontmatterEndOffset(fullSource);
+
+  let doc: MarkdownDocument;
+  try {
+    doc = parseMarkdown(fullSource);
+  } catch {
+    // Unparseable mid-edit — treat the whole body as one slice rather than
+    // dropping the user into an empty card.
+    return [makeSlice(fullSource, bodyStart, fullSource.length)];
+  }
+
+  const lineStarts = computeLineStarts(fullSource);
+  const headingOffsets: number[] = [];
+  for (const node of doc.children) {
+    if (node.type !== 'heading') continue;
+    const line = node.position?.start.line;
+    if (typeof line !== 'number') continue;
+    const off = lineStarts[line - 1];
+    if (typeof off === 'number') headingOffsets.push(off);
+  }
+
+  if (headingOffsets.length === 0) {
+    return [makeSlice(fullSource, bodyStart, fullSource.length)];
+  }
+
+  const slices: BlockSlice[] = [];
+  const firstHeading = headingOffsets[0];
+  if (fullSource.slice(bodyStart, firstHeading).trim().length > 0) {
+    slices.push(makeSlice(fullSource, bodyStart, firstHeading));
+  }
+  for (let i = 0; i < headingOffsets.length; i++) {
+    const start = headingOffsets[i];
+    const end = i + 1 < headingOffsets.length ? headingOffsets[i + 1] : fullSource.length;
+    slices.push(makeSlice(fullSource, start, end));
+  }
+  return slices;
+}
+
+/** Replace the text in `range` with `newText`, returning the new full source. */
+export function spliceBlock(fullSource: string, range: BlockRange, newText: string): string {
+  return fullSource.slice(0, range.startOffset) + newText + fullSource.slice(range.endOffset);
+}
+
+/** Character offset of the start of 1-based `line` (clamps past EOF). */
+export function lineToOffset(source: string, line: number): number {
+  const starts = computeLineStarts(source);
+  return starts[Math.max(0, line - 1)] ?? source.length;
+}
+
+/** 1-based line number containing `offset`. */
+export function offsetToLine(source: string, offset: number): number {
+  const starts = computeLineStarts(source);
+  let lo = 0;
+  let hi = starts.length - 1;
+  let ans = 0;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    if (starts[mid] <= offset) {
+      ans = mid;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return ans + 1;
+}
+
+/** Index of the slice whose range contains `offset`, or -1. */
+export function sliceIndexAtOffset(slices: BlockSlice[], offset: number): number {
+  return slices.findIndex((s) => offset >= s.range.startOffset && offset < s.range.endOffset);
+}

package/src/buildPreviewDoc.ts

@@ -11,19 +11,40 @@
  * 4. Synthesize a dummy audio segment for timer-based playback
  */
 
-import { flattenBlocks, hasTemplate } from '@bendyline/squisq/doc';
-import { extractPlainText } from '@bendyline/squisq/markdown';
+import { flattenRenderableBlocks, hasTemplate } from '@bendyline/squisq/doc';
+import { extractPlainText, KNOWN_BLOCK_META_KEYS } from '@bendyline/squisq/markdown';
 import { getChildren } from '@bendyline/squisq/markdown';
+import { iconMarker } from '@bendyline/squisq/icon-marker';
+import type { IconFamily } from '@bendyline/squisq/icons';
 import type { Block, Doc } from '@bendyline/squisq/schemas';
 import type { MarkdownBlockNode, MarkdownList, MarkdownNode } from '@bendyline/squisq/markdown';
 
 // ── Helpers ────────────────────────────────────────────────────────
 
+/**
+ * Like `extractPlainText`, but preserves inline icons as encoded markers so
+ * template text can render them as glyphs downstream (see `iconMarker` and
+ * `TextLayer`). Mirrors `extractPlainText`'s value/child/list handling; the
+ * only addition is the `inlineIcon` interception.
+ */
+function extractRichText(node: MarkdownNode): string {
+  if (node.type === 'inlineIcon') {
+    const icon = node as unknown as { family: IconFamily; name: string };
+    return iconMarker(icon.family, icon.name);
+  }
+  if ('value' in node && typeof (node as { value?: unknown }).value === 'string') {
+    return (node as { value: string }).value;
+  }
+  const children = getChildren(node);
+  const separator = node.type === 'list' || node.type === 'listItem' ? '\n' : '';
+  return children.map(extractRichText).join(separator);
+}
+
 function extractBodyText(contents: MarkdownBlockNode[] | undefined): string {
   if (!contents || contents.length === 0) return '';
   const parts: string[] = [];
   for (const node of contents) {
-    parts.push(extractPlainText(node));
+    parts.push(extractRichText(node));
   }
   return parts.join('\n').trim();
 }
@@ -174,13 +195,23 @@ function getTemplateDefaults(
   }
 }
 
-function blockToSlide(block: Block, index: number): Record<string, unknown> {
+function blockToSlide(
+  block: Block,
+  index: number,
+  knownTemplates?: ReadonlySet<string>,
+): Record<string, unknown> {
   const headingText = block.sourceHeading
     ? extractPlainText(block.sourceHeading)
     : block.title || block.id || `Slide ${index + 1}`;
 
   const requestedTemplate = block.template || 'sectionHeader';
-  const template = hasTemplate(requestedTemplate) ? requestedTemplate : 'sectionHeader';
+  // A template is recognized if it's a built-in OR a user-defined
+  // template carried in the doc's `customTemplates` set. Without this,
+  // an annotated `{[hero]}` heading would silently fall back to
+  // `sectionHeader` because `hasTemplate` only knows built-ins.
+  const isCustomTemplate = knownTemplates?.has(requestedTemplate) ?? false;
+  const recognized = hasTemplate(requestedTemplate) || isCustomTemplate;
+  const template = recognized ? requestedTemplate : 'sectionHeader';
   const defaults = getTemplateDefaults(template, headingText, block);
 
   const {
@@ -196,6 +227,7 @@ function blockToSlide(block: Block, index: number): Record<string, unknown> {
     contents: _co,
     sourceHeading: _sh,
     templateOverrides: _to,
+    templateData: _td,
     ...extraFields
   } = block as unknown as Record<string, unknown>;
 
@@ -204,14 +236,59 @@ function blockToSlide(block: Block, index: number): Record<string, unknown> {
     template,
     duration: block.duration,
     audioSegment: 0,
-    transition: index > 0 ? { type: 'fade', duration: 0.5 } : undefined,
+    // Respect the block's authored transition (set via the toolbar / on-canvas
+    // properties palette → `{…}` block attrs). Only fall back to a default fade
+    // for blocks past the first when the author hasn't chosen one; the first
+    // block has no previous slide to transition in from.
+    transition: block.transition ?? (index > 0 ? { type: 'fade', duration: 0.5 } : undefined),
     title: headingText,
+    // Custom templates need access to the source block's body content
+    // + children so their token resolver (`{content}`, `{children}`,
+    // `{image:N}`) substitutes against the user's prose, not just the
+    // heading. Built-in templates don't read these fields and risk
+    // surprising overlap with their typed inputs, so we only attach
+    // them when the slide actually maps to a custom template.
+    ...(isCustomTemplate && block.contents ? { contents: block.contents } : {}),
+    ...(isCustomTemplate && block.children ? { children: block.children } : {}),
     ...defaults,
     ...extraFields,
-    ...block.templateOverrides,
+    // Structured body data (```json data fences, GFM tables for dataTable)
+    // carries typed values; `{[…]}` string overrides win last so an explicit
+    // annotation param can still pin any field.
+    //
+    // Block-meta keys (transition, startTime, duration, …) are the exception:
+    // they were already coerced to typed block fields above (e.g.
+    // `block.transition` → `{ type, duration, direction }`). Their raw string
+    // form also rides along in `templateData`/`templateOverrides` because the
+    // author wrote them inside `{[…]}`; left un-stripped, that string would
+    // spread back over the typed value here and clobber it — turning
+    // `transition=vortex` into the string `"vortex"`, which the player can't
+    // animate. Omit them from the content spreads so the typed fields win.
+    ...omitBlockMeta(block.templateData),
+    ...omitBlockMeta(block.templateOverrides),
   };
 }
 
+/** Keys coerced to typed block fields; must not be re-applied as raw strings. */
+const BLOCK_META_KEYS: ReadonlySet<string> = new Set(Object.keys(KNOWN_BLOCK_META_KEYS));
+
+/** Copy of a template-param record with block-meta keys removed. */
+function omitBlockMeta(
+  data: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (!data) return data;
+  let hit = false;
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(data)) {
+    if (BLOCK_META_KEYS.has(key)) {
+      hit = true;
+      continue;
+    }
+    out[key] = data[key];
+  }
+  return hit ? out : data;
+}
+
 const IMAGE_MOTIONS: Array<'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight'> = [
   'zoomIn',
   'zoomOut',
@@ -229,9 +306,18 @@ const IMAGE_MOTIONS: Array<'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight'> = [
  * audio segment.
  */
 export function buildPreviewDoc(doc: Doc): Doc {
-  const flat = flattenBlocks(doc.blocks);
+  // Container templates (`diagram`, `drawing`) render their children as
+  // nodes/shapes, so those children must not also become preview slides.
+  const flat = flattenRenderableBlocks(doc.blocks);
   const allImages = collectAllDocImages(doc.blocks);
   const usedImageSrcs = new Set<string>();
+  // Names of user-defined templates carried by the doc — passed into
+  // `blockToSlide` so heading annotations like `{[hero]}` aren't
+  // silently downgraded to `sectionHeader` when the template doesn't
+  // exist in the built-in registry.
+  const knownTemplates = doc.customTemplates
+    ? new Set(doc.customTemplates.map((d) => d.name))
+    : undefined;
 
   const slides: Record<string, unknown>[] = [];
   let motionIndex = 0;
@@ -239,7 +325,7 @@ export function buildPreviewDoc(doc: Doc): Doc {
   for (let i = 0; i < flat.length; i++) {
     const block = flat[i];
     const blockImages = extractBlockImages(block.contents);
-    const slide = blockToSlide(block, i);
+    const slide = blockToSlide(block, i, knownTemplates);
 
     if (blockImages.length > 0 && slide.template === 'sectionHeader') {
       const img = blockImages[0];
@@ -305,5 +391,8 @@ export function buildPreviewDoc(doc: Doc): Doc {
     ...(doc.captions ? { captions: doc.captions } : {}),
     ...(doc.startBlock ? { startBlock: doc.startBlock } : {}),
     ...(doc.themeId ? { themeId: doc.themeId } : {}),
+    // Custom templates ride along so `useDocPlayback` can merge them
+    // onto the registry before expanding slides.
+    ...(doc.customTemplates ? { customTemplates: doc.customTemplates } : {}),
   };
 }

package/src/codeContext/CodeContextSectionView.tsx

@@ -0,0 +1,124 @@
+import { parseMarkdown } from '@bendyline/squisq/markdown';
+import { MarkdownRenderer } from '@bendyline/squisq-react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import type { CodeContext, CodeContextSection } from './types';
+
+/**
+ * One context section rendered inside a Monaco view zone: a single-line
+ * disclosure strip, plus the full markdown body while expanded. The body is
+ * rendered lazily — a file with 100 collapsed sections parses 100 one-liners,
+ * nothing more.
+ */
+export interface CodeContextSectionViewProps {
+  section: Omit<CodeContextSection, 'line'>;
+  expanded: boolean;
+  onToggle: (id: string) => void;
+  linkSchemes?: readonly string[] | undefined;
+  onLinkClick?: CodeContext['onLinkClick'] | undefined;
+  /** Native `#L<n>` handling: reveal that line in the editor. */
+  onRevealLine: (line: number) => void;
+  /** Reports the rendered content height so the zone can be resized to fit. */
+  onMeasure: (id: string, px: number) => void;
+}
+
+export function CodeContextSectionView({
+  section,
+  expanded,
+  onToggle,
+  linkSchemes,
+  onLinkClick,
+  onRevealLine,
+  onMeasure,
+}: CodeContextSectionViewProps) {
+  const rootRef = useRef<HTMLDivElement | null>(null);
+
+  const stripNodes = useMemo(
+    () => parseMarkdown(section.summaryMarkdown).children,
+    [section.summaryMarkdown],
+  );
+  const bodyNodes = useMemo(
+    () => (expanded && section.markdown ? parseMarkdown(section.markdown).children : null),
+    [expanded, section.markdown],
+  );
+
+  // Height feedback loop: report the content's real height whenever it
+  // changes. Monaco display:none's offscreen zones and ResizeObserver reports
+  // 0×0 for those — ignore zeros so scrolled-away zones keep their height.
+  useEffect(() => {
+    const el = rootRef.current;
+    if (!el || typeof ResizeObserver === 'undefined') return;
+    const report = () => {
+      const h = el.offsetHeight;
+      if (h > 0) onMeasure(section.id, h);
+    };
+    report();
+    const ro = new ResizeObserver(report);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [section.id, onMeasure]);
+
+  // Delegated link interception. `#L<n>` reveals natively; everything else
+  // goes to the host callback (returning false opts back into default
+  // navigation).
+  const handleClick = useCallback(
+    (e: React.MouseEvent) => {
+      const anchor = (e.target as HTMLElement).closest?.('a');
+      if (!anchor) return;
+      const href = anchor.getAttribute('href') ?? '';
+      const lineMatch = /^#L(\d+)$/.exec(href);
+      if (lineMatch) {
+        e.preventDefault();
+        e.stopPropagation();
+        onRevealLine(Number(lineMatch[1]));
+        return;
+      }
+      if (onLinkClick) {
+        const handled = onLinkClick(href, { sectionId: section.id });
+        if (handled !== false) {
+          e.preventDefault();
+          e.stopPropagation();
+        }
+      }
+    },
+    [onLinkClick, onRevealLine, section.id],
+  );
+
+  // Keep Monaco's container-level mousedown handler from hijacking clicks
+  // and text selection inside the section.
+  const stopMouseDown = useCallback((e: React.MouseEvent) => {
+    e.stopPropagation();
+  }, []);
+
+  return (
+    // Click handler is delegated anchor interception only; keyboard users
+    // reach links natively and the strip itself is a real <button>.
+    <div
+      ref={rootRef}
+      className={`squisq-ccx-section${expanded ? ' squisq-ccx-section--expanded' : ''}`}
+      onClick={handleClick}
+      onMouseDown={stopMouseDown}
+    >
+      <button
+        type="button"
+        className="squisq-ccx-strip"
+        aria-expanded={expanded}
+        onClick={() => onToggle(section.id)}
+      >
+        <span className="squisq-ccx-chevron" aria-hidden="true">
+          {expanded ? '▾' : '▸'}
+        </span>
+        <span className="squisq-ccx-strip-text">
+          <MarkdownRenderer nodes={stripNodes} {...(linkSchemes ? { linkSchemes } : {})} />
+        </span>
+      </button>
+      {expanded &&
+        (bodyNodes ? (
+          <div className="squisq-ccx-body">
+            <MarkdownRenderer nodes={bodyNodes} {...(linkSchemes ? { linkSchemes } : {})} />
+          </div>
+        ) : (
+          <div className="squisq-ccx-body squisq-ccx-body--loading">Loading…</div>
+        ))}
+    </div>
+  );
+}

package/src/codeContext/CodeContextZoneManager.ts

@@ -0,0 +1,149 @@
+import type { editor as MonacoEditorNs } from 'monaco-editor';
+import { type ZoneSpec, diffContextSections } from './diffContextSections';
+
+type MonacoEditor = MonacoEditorNs.IStandaloneCodeEditor;
+
+/**
+ * Owns the Monaco view zones behind the code-context sections. React-free —
+ * the React layer portals content into the zone dom nodes it hands out and
+ * feeds measured heights back via {@link setHeight}.
+ *
+ * Zone mechanics this leans on (monaco 0.50):
+ * - `changeViewZones` batches adds/removes/layouts into one whitespace
+ *   re-layout.
+ * - `layoutZone(id)` re-reads the zone delegate, so mutating our own
+ *   delegate's `afterLineNumber`/`heightInPx` then calling layoutZone both
+ *   moves and resizes without remove/re-add churn (expanded DOM survives).
+ * - Zone dom nodes live in `.view-zones` (absolutely positioned, offscreen
+ *   ones display:none'd by Monaco). They sit BELOW `.view-lines` in hit-test
+ *   order, so the stylesheet raises `.squisq-ccx-zone` with a z-index and
+ *   `pointer-events: auto` to make section content clickable.
+ * - Model swaps invalidate zone ids; the owner listens to onDidChangeModel
+ *   and rebuilds.
+ */
+export class CodeContextZoneManager {
+  private readonly editor: MonacoEditor;
+  private entries = new Map<
+    string,
+    {
+      zoneId: string;
+      delegate: MonacoEditorNs.IViewZone;
+      domNode: HTMLDivElement;
+      spec: ZoneSpec;
+    }
+  >();
+  private listeners = new Set<() => void>();
+  private modelListener: { dispose(): void } | null = null;
+  private disposed = false;
+
+  /** Initial height estimate for a strip; the ResizeObserver corrects it. */
+  static readonly INITIAL_HEIGHT_PX = 28;
+
+  constructor(editor: MonacoEditor) {
+    this.editor = editor;
+    // A model swap (file change / external reset) invalidates every zone id.
+    // Drop our bookkeeping; the next sync() recreates zones against the new
+    // model.
+    this.modelListener = editor.onDidChangeModel(() => {
+      this.entries.clear();
+      this.emit();
+    });
+  }
+
+  /** Reconcile the live zones against `specs` in one changeViewZones batch. */
+  sync(specs: ZoneSpec[]): void {
+    if (this.disposed) return;
+    const prev = [...this.entries.values()].map((e) => e.spec);
+    const { add, remove, move } = diffContextSections(prev, specs);
+    if (add.length === 0 && remove.length === 0 && move.length === 0) return;
+
+    this.editor.changeViewZones((accessor) => {
+      for (const id of remove) {
+        const entry = this.entries.get(id);
+        if (!entry) continue;
+        accessor.removeZone(entry.zoneId);
+        this.entries.delete(id);
+      }
+      for (const spec of move) {
+        const entry = this.entries.get(spec.id);
+        if (!entry) continue;
+        entry.spec = spec;
+        entry.delegate.afterLineNumber = Math.max(spec.line - 1, 0);
+        setOrdinal(entry.delegate, spec.ordinal);
+        accessor.layoutZone(entry.zoneId);
+      }
+      for (const spec of add) {
+        const domNode = document.createElement('div');
+        domNode.className = 'squisq-ccx-zone';
+        domNode.dataset.sectionId = spec.id;
+        const delegate: MonacoEditorNs.IViewZone = {
+          afterLineNumber: Math.max(spec.line - 1, 0),
+          heightInPx: CodeContextZoneManager.INITIAL_HEIGHT_PX,
+          domNode,
+          suppressMouseDown: true,
+        };
+        setOrdinal(delegate, spec.ordinal);
+        const zoneId = accessor.addZone(delegate);
+        this.entries.set(spec.id, { zoneId, delegate, domNode, spec });
+      }
+    });
+    this.emit();
+  }
+
+  /** Measured-content feedback: resize the zone to fit its rendered DOM. */
+  setHeight(id: string, px: number): void {
+    if (this.disposed) return;
+    const entry = this.entries.get(id);
+    if (!entry) return;
+    const height = Math.max(Math.ceil(px), 1);
+    if (Math.abs((entry.delegate.heightInPx ?? 0) - height) < 1) return;
+    entry.delegate.heightInPx = height;
+    this.editor.changeViewZones((accessor) => {
+      accessor.layoutZone(entry.zoneId);
+    });
+  }
+
+  getDomNode(id: string): HTMLDivElement | undefined {
+    return this.entries.get(id)?.domNode;
+  }
+
+  liveIds(): string[] {
+    return [...this.entries.keys()];
+  }
+
+  /** Fires after sync/model-change so the React layer rebuilds its portals. */
+  onDidChangeZones(cb: () => void): () => void {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.modelListener?.dispose();
+    this.modelListener = null;
+    if (this.entries.size > 0) {
+      try {
+        this.editor.changeViewZones((accessor) => {
+          for (const entry of this.entries.values()) accessor.removeZone(entry.zoneId);
+        });
+      } catch {
+        // Editor already disposed — its zones died with it.
+      }
+    }
+    this.entries.clear();
+    this.listeners.clear();
+  }
+
+  private emit(): void {
+    for (const cb of [...this.listeners]) cb();
+  }
+}
+
+/**
+ * `ordinal` orders zones sharing an afterLineNumber (monaco 0.50 supports it
+ * but the public IViewZone typing lags behind) — hence the structural write.
+ */
+function setOrdinal(zone: MonacoEditorNs.IViewZone, ordinal: number): void {
+  (zone as MonacoEditorNs.IViewZone & { ordinal?: number }).ordinal = ordinal;
+}