@bendyline/squisq-editor-react 1.6.2 → 2.0.1

package/src/blockTagActivity.ts

@@ -0,0 +1,233 @@
+import { Extension } from '@tiptap/core';
+import { Plugin, PluginKey, type Transaction } from '@tiptap/pm/state';
+import { Decoration, DecorationSet, type EditorView as ProseMirrorView } from '@tiptap/pm/view';
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
+
+export const BLOCK_TAG_SELECTED_CLASS = 'squisq-block-tags--selected';
+export const BLOCK_TAG_HOVERED_CLASS = 'squisq-block-tags--hovered';
+
+export interface BlockTagActivityPluginState {
+  selectedPosition: number | null;
+  hoveredPosition: number | null;
+  decorations: DecorationSet;
+}
+
+interface BlockTagHoverMeta {
+  hoveredPosition: number | null;
+}
+
+export const BLOCK_TAG_ACTIVITY_KEY = new PluginKey<BlockTagActivityPluginState>(
+  'squisq-block-tag-activity',
+);
+
+function isHeadingElement(element: Element): element is HTMLElement {
+  return /^H[1-6]$/.test(element.tagName);
+}
+
+/**
+ * Returns the heading position for the block owning a document position.
+ * A block begins at a top-level heading and continues until the next heading.
+ */
+export function findOwningHeadingPosition(doc: ProseMirrorNode, position: number): number | null {
+  let offset = 0;
+  let owningPosition: number | null = null;
+
+  for (let index = 0; index < doc.childCount && offset <= position; index += 1) {
+    const node = doc.child(index);
+    if (node.type.name === 'heading') owningPosition = offset;
+    offset += node.nodeSize;
+  }
+
+  return owningPosition;
+}
+
+/** Find the preceding top-level heading for a DOM node under ProseMirror. */
+export function findOwningHeadingElement(
+  editorDom: HTMLElement,
+  target: EventTarget | null,
+): HTMLElement | null {
+  if (!(target instanceof Node)) return null;
+
+  let element =
+    target.nodeType === Node.ELEMENT_NODE
+      ? (target as HTMLElement)
+      : (target.parentElement as HTMLElement | null);
+  if (!element || element === editorDom || !editorDom.contains(element)) return null;
+
+  while (element.parentElement && element.parentElement !== editorDom) {
+    element = element.parentElement;
+  }
+  if (element.parentElement !== editorDom) return null;
+
+  let candidate: Element | null = element;
+  while (candidate && !isHeadingElement(candidate)) {
+    candidate = candidate.previousElementSibling;
+  }
+  return candidate && isHeadingElement(candidate) ? candidate : null;
+}
+
+/**
+ * Resolve blank canvas space to the heading-defined block at that vertical
+ * position. Margins between top-level nodes are not owned by either node in
+ * the DOM, so pointer events there target the ProseMirror root. Treating the
+ * root as "no block" makes active-only tags disappear while the pointer
+ * crosses ordinary paragraph/list spacing.
+ */
+export function findOwningHeadingElementAtPoint(
+  editorDom: HTMLElement,
+  target: EventTarget | null,
+  clientY: number,
+): HTMLElement | null {
+  const direct = findOwningHeadingElement(editorDom, target);
+  if (direct) return direct;
+  if (!(target instanceof Node) || !editorDom.contains(target) || !Number.isFinite(clientY)) {
+    return null;
+  }
+
+  const children = Array.from(editorDom.children);
+  const lastChild = children[children.length - 1];
+  if (!lastChild || clientY > lastChild.getBoundingClientRect().bottom) return null;
+
+  let owningHeading: HTMLElement | null = null;
+  for (const child of children) {
+    if (child.getBoundingClientRect().top > clientY) break;
+    if (isHeadingElement(child)) owningHeading = child;
+  }
+  return owningHeading;
+}
+
+function validHeadingPosition(doc: ProseMirrorNode, position: number | null): number | null {
+  if (position === null) return null;
+  return doc.nodeAt(position)?.type.name === 'heading' ? position : null;
+}
+
+function buildDecorations(
+  doc: ProseMirrorNode,
+  selectedPosition: number | null,
+  hoveredPosition: number | null,
+): DecorationSet {
+  const classesByPosition = new Map<number, string[]>();
+
+  if (selectedPosition !== null) {
+    classesByPosition.set(selectedPosition, [BLOCK_TAG_SELECTED_CLASS]);
+  }
+  if (hoveredPosition !== null) {
+    const classes = classesByPosition.get(hoveredPosition) ?? [];
+    classes.push(BLOCK_TAG_HOVERED_CLASS);
+    classesByPosition.set(hoveredPosition, classes);
+  }
+
+  const decorations: Decoration[] = [];
+  for (const [position, classes] of classesByPosition) {
+    const node = doc.nodeAt(position);
+    if (!node || node.type.name !== 'heading') continue;
+    decorations.push(
+      Decoration.node(position, position + node.nodeSize, { class: classes.join(' ') }),
+    );
+  }
+
+  return decorations.length > 0 ? DecorationSet.create(doc, decorations) : DecorationSet.empty;
+}
+
+function createPluginState(
+  doc: ProseMirrorNode,
+  selectionFrom: number,
+  hoveredPosition: number | null,
+): BlockTagActivityPluginState {
+  const selectedPosition = findOwningHeadingPosition(doc, selectionFrom);
+  const validHoveredPosition = validHeadingPosition(doc, hoveredPosition);
+  return {
+    selectedPosition,
+    hoveredPosition: validHoveredPosition,
+    decorations: buildDecorations(doc, selectedPosition, validHoveredPosition),
+  };
+}
+
+function nextHoveredPosition(
+  transaction: Transaction,
+  previousPosition: number | null,
+  doc: ProseMirrorNode,
+): number | null {
+  const meta = transaction.getMeta(BLOCK_TAG_ACTIVITY_KEY) as BlockTagHoverMeta | undefined;
+  if (meta !== undefined) return validHeadingPosition(doc, meta.hoveredPosition);
+  if (!transaction.docChanged || previousPosition === null) return previousPosition;
+
+  const mapped = transaction.mapping.mapResult(previousPosition, 1);
+  return mapped.deleted ? null : validHeadingPosition(doc, mapped.pos);
+}
+
+function headingPositionForTarget(
+  view: ProseMirrorView,
+  target: EventTarget | null,
+  clientY: number,
+): number | null {
+  const heading = findOwningHeadingElementAtPoint(view.dom, target, clientY);
+  if (!heading) return null;
+
+  try {
+    const positionInsideHeading = view.posAtDOM(heading, 0);
+    return findOwningHeadingPosition(view.state.doc, positionInsideHeading);
+  } catch {
+    return null;
+  }
+}
+
+function setHoveredPosition(view: ProseMirrorView, hoveredPosition: number | null): void {
+  const current = BLOCK_TAG_ACTIVITY_KEY.getState(view.state)?.hoveredPosition ?? null;
+  if (current === hoveredPosition) return;
+  view.dispatch(
+    view.state.tr
+      .setMeta(BLOCK_TAG_ACTIVITY_KEY, { hoveredPosition } satisfies BlockTagHoverMeta)
+      .setMeta('addToHistory', false),
+  );
+}
+
+/**
+ * ProseMirror-owned block activity decorations. Using node decorations keeps
+ * the classes stable when ProseMirror reconciles its managed heading DOM.
+ */
+export const BlockTagActivityExtension = Extension.create({
+  name: 'squisqBlockTagActivity',
+
+  addProseMirrorPlugins() {
+    return [
+      new Plugin<BlockTagActivityPluginState>({
+        key: BLOCK_TAG_ACTIVITY_KEY,
+        state: {
+          init: (_config, state) => createPluginState(state.doc, state.selection.from, null),
+          apply: (transaction, previous, _oldState, newState) =>
+            createPluginState(
+              newState.doc,
+              newState.selection.from,
+              nextHoveredPosition(transaction, previous.hoveredPosition, newState.doc),
+            ),
+        },
+        props: {
+          decorations(state) {
+            return this.getState(state)?.decorations ?? DecorationSet.empty;
+          },
+          handleDOMEvents: {
+            mouseover(view, event) {
+              setHoveredPosition(view, headingPositionForTarget(view, event.target, event.clientY));
+              return false;
+            },
+            mousemove(view, event) {
+              // `mouseover` covers real document nodes. Only track continuous
+              // movement while the root itself owns the pointer (the blank
+              // margin/gutter case), avoiding geometry reads over text.
+              if (event.target !== view.dom) return false;
+              setHoveredPosition(view, headingPositionForTarget(view, event.target, event.clientY));
+              return false;
+            },
+            mouseleave(view) {
+              setHoveredPosition(view, null);
+              return false;
+            },
+          },
+        },
+      }),
+    ];
+  },
+});
+
+export default BlockTagActivityExtension;

package/src/buildDocumentPreviewMarkdown.ts

@@ -0,0 +1,168 @@
+/**
+ * Build the text-first Document-mode projection for a transformed Doc.
+ *
+ * Transform-generated blocks are programmatic template inputs: unlike blocks
+ * parsed from Markdown, they do not carry `sourceHeading` / `contents` nodes.
+ * `docToMarkdown()` intentionally omits such blocks because its primary job is
+ * lossless authoring round-trips. For a summarized preview we instead give the
+ * generated blocks a temporary, readable authoring shape before serializing.
+ */
+
+import { docToMarkdown } from '@bendyline/squisq/doc';
+import { stringifyMarkdown } from '@bendyline/squisq/markdown';
+import type { MarkdownHeading, MarkdownParagraph } from '@bendyline/squisq/markdown';
+import type { Block, Doc } from '@bendyline/squisq/schemas';
+
+function textParagraph(value: string): MarkdownParagraph {
+  return { type: 'paragraph', children: [{ type: 'text', value }] };
+}
+
+function textHeading(value: string, depth: 1 | 2 = 2): MarkdownHeading {
+  return { type: 'heading', depth, children: [{ type: 'text', value }] };
+}
+
+function stringValue(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function stringList(record: Record<string, unknown>, key: string): string[] {
+  const value = record[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === 'string' && !!item.trim());
+}
+
+interface ReadableBlockContent {
+  title?: string;
+  body: string[];
+}
+
+/** Extract the reader-facing copy carried by a programmatic template block. */
+function readableTemplateContent(block: Block): ReadableBlockContent {
+  const value = block as unknown as Record<string, unknown>;
+  const template = stringValue(value, 'template');
+  const explicitTitle = stringValue(value, 'title');
+
+  switch (template) {
+    case 'statHighlight':
+      return {
+        title: stringValue(value, 'stat') ?? explicitTitle,
+        body: [stringValue(value, 'description')].filter(Boolean) as string[],
+      };
+    case 'factCard':
+      return {
+        title: stringValue(value, 'fact') ?? explicitTitle,
+        body: [stringValue(value, 'explanation')].filter(Boolean) as string[],
+      };
+    case 'quote':
+      return {
+        title: stringValue(value, 'quote') ?? explicitTitle,
+        body: [stringValue(value, 'attribution')].filter(Boolean) as string[],
+      };
+    case 'fullBleedQuote':
+    case 'pullQuote':
+      return {
+        title: stringValue(value, 'text') ?? stringValue(value, 'quote') ?? explicitTitle,
+        body: [stringValue(value, 'attribution')].filter(Boolean) as string[],
+      };
+    case 'dateEvent':
+      return {
+        title: stringValue(value, 'date') ?? explicitTitle,
+        body: [stringValue(value, 'description')].filter(Boolean) as string[],
+      };
+    case 'definitionCard':
+      return {
+        title: stringValue(value, 'term') ?? explicitTitle,
+        body: [stringValue(value, 'definition'), stringValue(value, 'origin')].filter(
+          Boolean,
+        ) as string[],
+      };
+    case 'twoColumn':
+      return {
+        title: stringValue(value, 'header') ?? explicitTitle ?? 'Comparison',
+        body: [stringValue(value, 'left'), stringValue(value, 'right')].filter(Boolean) as string[],
+      };
+    case 'list':
+      return {
+        title: explicitTitle ?? 'Highlights',
+        body: stringList(value, 'items'),
+      };
+    case 'imageWithCaption':
+      return {
+        title: stringValue(value, 'caption') ?? stringValue(value, 'imageAlt') ?? explicitTitle,
+        body: [],
+      };
+    default:
+      return {
+        title: explicitTitle,
+        body: [
+          stringValue(value, 'body'),
+          stringValue(value, 'description'),
+          stringValue(value, 'text'),
+        ].filter(Boolean) as string[],
+      };
+  }
+}
+
+function hasAuthoredShape(block: Block): boolean {
+  return !!(
+    block.sourceHeading ||
+    block.standaloneAnnotation ||
+    (block.contents && block.contents.length > 0)
+  );
+}
+
+function makeReadableBlock(block: Block): Block {
+  const children = block.children?.map(makeReadableBlock);
+  if (hasAuthoredShape(block)) {
+    return children === block.children ? block : { ...block, children };
+  }
+
+  const readable = readableTemplateContent(block);
+  return {
+    ...block,
+    // Document mode is intentionally text-first. Removing the template from
+    // this temporary projection prevents docToMarkdown from re-adding a
+    // presentation annotation to the synthesized heading.
+    template: undefined,
+    sourceHeading: readable.title ? textHeading(readable.title) : undefined,
+    contents: readable.body.map(textParagraph),
+    children,
+  };
+}
+
+function documentTitle(doc: Doc): string | undefined {
+  if (doc.startBlock?.title?.trim()) return doc.startBlock.title.trim();
+  const title = doc.frontmatter?.title;
+  return typeof title === 'string' && title.trim() ? title.trim() : undefined;
+}
+
+function hasLevelOneHeading(blocks: Block[]): boolean {
+  return blocks.some(
+    (block) =>
+      block.sourceHeading?.depth === 1 ||
+      (block.children ? hasLevelOneHeading(block.children) : false),
+  );
+}
+
+/** Serialize a transformed Doc into readable Markdown for Document mode. */
+export function buildDocumentPreviewMarkdown(doc: Doc): string {
+  const blocks = doc.blocks.map(makeReadableBlock);
+  const title = documentTitle(doc);
+  const titledBlocks =
+    title && !hasLevelOneHeading(blocks)
+      ? [
+          {
+            id: 'transform-document-title',
+            startTime: 0,
+            duration: 0,
+            audioSegment: 0,
+            sourceHeading: textHeading(title, 1),
+            contents: [],
+          } satisfies Block,
+          ...blocks,
+        ]
+      : blocks;
+
+  return stringifyMarkdown(docToMarkdown({ ...doc, blocks: titledBlocks }));
+}

package/src/buildPreviewDoc.ts

@@ -11,7 +11,7 @@
  * 4. Synthesize a dummy audio segment for timer-based playback
  */
 
-import { flattenRenderableBlocks, hasTemplate } from '@bendyline/squisq/doc';
+import { deriveTemplateInputs, 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';
@@ -158,7 +158,12 @@ function getTemplateDefaults(
 
   switch (templateName) {
     case 'statHighlight':
-      return { stat: headingText, description: body || headingText };
+      return (
+        deriveTemplateInputs(templateName, headingText, block.contents) ?? {
+          stat: headingText,
+          description: body || headingText,
+        }
+      );
     case 'quote':
     case 'fullBleedQuote':
     case 'pullQuote':
@@ -381,18 +386,20 @@ export function buildPreviewDoc(doc: Doc): Doc {
     t += slide.duration as number;
   }
 
+  const audio =
+    doc.audio?.segments?.length > 0
+      ? doc.audio
+      : {
+          segments: t > 0 ? [{ src: '', name: 'preview', duration: t, startTime: 0 }] : [],
+        };
+
   return {
-    articleId: doc.articleId,
+    // Preserve document-wide capabilities (custom themes, persistent layers,
+    // scheduled media, frontmatter, captions, and future schema fields).
+    // Preview preparation should replace only the slide/timing projection.
+    ...doc,
     duration: t,
     blocks: slides as unknown as Block[],
-    audio: {
-      segments: t > 0 ? [{ src: '', name: 'preview', duration: t, startTime: 0 }] : [],
-    },
-    ...(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 } : {}),
+    audio,
   };
 }

package/src/codeContext/types.ts

@@ -56,7 +56,7 @@ export interface CodeContext {
   /** Line-anchored sections. Array order is preserved for equal lines. */
   sections?: CodeContextSection[];
   /**
-   * Extra URI schemes section links may use (e.g. `['gezel-nav']`).
+   * Extra URI schemes section links may use (e.g. `['workspace-nav']`).
    * http/https/mailto/tel are always allowed; executable schemes
    * (javascript:, data:) are never allowed regardless.
    */

package/src/customTemplates/CustomLayoutManager.tsx

@@ -47,7 +47,7 @@ type Selection =
 
 export function CustomLayoutManager({ onClose }: CustomLayoutManagerProps) {
   const { docTemplates, onDocTemplatesChange } = useDocCustomTemplates();
-  const { mediaProvider } = useEditorContext();
+  const { mediaProvider, colorScheme } = useEditorContext();
 
   // Close on Escape, mirroring the other editor dialogs.
   useEffect(() => {
@@ -60,7 +60,8 @@ export function CustomLayoutManager({ onClose }: CustomLayoutManagerProps) {
 
   return createPortal(
     <div
-      className="squisq-layout-manager-overlay"
+      className="squisq-editor-shell squisq-layout-manager-overlay"
+      data-theme={colorScheme}
       role="dialog"
       aria-modal="true"
       aria-label="Custom layouts"

package/src/customTemplates/CustomTemplateContext.tsx

@@ -34,6 +34,7 @@ import {
   listLibraryTemplates,
   saveLibraryTemplate as saveLibraryTemplateRaw,
   deleteLibraryTemplate as deleteLibraryTemplateRaw,
+  LIBRARY_STORAGE_KEY,
 } from './library';
 
 export interface CustomTemplateContextValue {
@@ -99,6 +100,11 @@ export function CustomTemplateProvider({
   // re-reads, which is enough for the single-tab common case.
   useEffect(() => {
     setLibraryTemplates(listLibraryTemplates());
+    const onStorage = (event: StorageEvent) => {
+      if (event.key === LIBRARY_STORAGE_KEY) setLibraryTemplates(listLibraryTemplates());
+    };
+    window.addEventListener('storage', onStorage);
+    return () => window.removeEventListener('storage', onStorage);
   }, []);
 
   const upsertDocTemplate = useCallback(

package/src/customTemplates/TemplateDesigner.tsx

@@ -77,6 +77,8 @@ interface TemplateDesignerProps {
    * preview. Omit to disable media in the bin.
    */
   mediaProvider?: MediaProvider | null;
+  /** Editor chrome scheme, copied onto the portal root for theme inheritance. */
+  colorScheme?: 'light' | 'dark';
 }
 
 const DESIGN_CANVAS = { width: 1920, height: 1080 };
@@ -112,6 +114,7 @@ export function TemplateDesigner({
   embedded = false,
   primarySaveLabel = 'Save to this doc',
   mediaProvider = null,
+  colorScheme = 'light',
 }: TemplateDesignerProps) {
   const [name, setName] = useState(initial?.name ?? '');
   const [label, setLabel] = useState(initial?.label ?? '');
@@ -147,9 +150,8 @@ export function TemplateDesigner({
   );
 
   // Build the toolset once. Each bin entry — placeholder token or shape —
-  // gets a click-to-place tool; SelectTool is the singleton from
-  // scene/tools/SelectTool.ts. Tools are factories so each has its own
-  // state-free closure.
+  // gets a click-to-place tool. Gesture state is supplied by each Scene,
+  // so the reusable tool definitions remain instance-safe.
   const tools: SceneTool[] = useMemo(
     () => [
       SelectTool,
@@ -414,7 +416,8 @@ export function TemplateDesigner({
   // Standalone: full-screen modal over a click-to-dismiss backdrop.
   return createPortal(
     <div
-      className="squisq-template-designer-overlay"
+      className="squisq-editor-shell squisq-template-designer-overlay"
+      data-theme={colorScheme}
       role="dialog"
       aria-modal="true"
       aria-label="Custom layout designer"

package/src/customTemplates/__tests__/library.test.ts

@@ -85,4 +85,12 @@ describe('library', () => {
     saveLibraryTemplate(defn('a'));
     expect(listLibraryTemplates().map((t) => t.name)).toEqual(['a']);
   });
+
+  it('filters structurally invalid array entries instead of crashing sort', () => {
+    window.localStorage.setItem(
+      LIBRARY_STORAGE_KEY,
+      JSON.stringify({ version: 1, templates: [null, {}, defn('valid')] }),
+    );
+    expect(listLibraryTemplates().map((template) => template.name)).toEqual(['valid']);
+  });
 });

package/src/customTemplates/__tests__/useMemoryLayerAdapter.test.ts

@@ -34,6 +34,19 @@ describe('applyCommand', () => {
     expect(after[0].position.height).toBe(80);
   });
 
+  it('resizeLayer applies an optional north/west origin atomically', () => {
+    const before: Layer[] = [rect('a', 10, 20, 100, 50)];
+    const after = applyCommand(before, {
+      kind: 'resizeLayer',
+      id: 'a',
+      x: 0,
+      y: 5,
+      width: 110,
+      height: 65,
+    });
+    expect(after[0].position).toMatchObject({ x: 0, y: 5, width: 110, height: 65 });
+  });
+
   it('addLayer appends', () => {
     const before: Layer[] = [rect('a', 0, 0)];
     const newLayer = rect('b', 100, 100);