@bendyline/squisq-editor-react 1.5.3 → 1.6.1

package/src/PreviewPanel.tsx

@@ -48,6 +48,7 @@ export function PreviewPanel({ basePath = '/', className, workspaceContainer }:
     activeTheme,
     activeTransformStyle,
     activeCaptionStyle,
+    activeCaptionsEnabled,
   } = usePreviewSettings();
 
   // Build the player-ready Doc whenever the parsed doc changes.
@@ -108,10 +109,15 @@ export function PreviewPanel({ basePath = '/', className, workspaceContainer }:
     );
   }
 
-  // Page mode renders directly from markdown — it doesn't depend on the
-  // parsed Doc tree or the player preview build, so let it fall through
-  // even when those aren't ready yet.
-  if (!previewDoc && activeDisplayMode !== 'page') {
+  // The public DisplayMode values predate the current labels: raw `page`
+  // is the plain Document preview, while raw `linear` is the styled Page view.
+  const isDocumentMode = activeDisplayMode === 'page';
+  const isPageMode = activeDisplayMode === 'linear';
+
+  // Document mode renders directly from markdown — it doesn't depend on the
+  // parsed Doc tree or the player preview build, so let it fall through even
+  // when those aren't ready yet.
+  if (!previewDoc && !isDocumentMode) {
     return (
       <div className={`squisq-preview-status ${className || ''}`} data-testid="preview-panel">
         <p>No content to preview. Start typing in the editor.</p>
@@ -119,8 +125,7 @@ export function PreviewPanel({ basePath = '/', className, workspaceContainer }:
     );
   }
 
-  const fillsContainer =
-    activeDisplayMode === 'linear' || activeDisplayMode === 'page' ? 'stretch' : 'center';
+  const fillsContainer = isDocumentMode || isPageMode ? 'stretch' : 'center';
 
   return (
     <div
@@ -147,7 +152,7 @@ export function PreviewPanel({ basePath = '/', className, workspaceContainer }:
           minHeight: 0,
         }}
       >
-        {activeDisplayMode === 'page' ? (
+        {isDocumentMode ? (
           <PlainHtmlPreview
             markdown={markdownSource}
             title={(doc?.frontmatter?.title as string | undefined) ?? undefined}
@@ -155,7 +160,7 @@ export function PreviewPanel({ basePath = '/', className, workspaceContainer }:
             mediaRevision={mediaRevision}
             theme={activeTheme}
           />
-        ) : activeDisplayMode === 'linear' ? (
+        ) : isPageMode ? (
           <LinearDocView
             doc={doc!}
             basePath={basePath}
@@ -164,7 +169,7 @@ export function PreviewPanel({ basePath = '/', className, workspaceContainer }:
           />
         ) : (
           <DocPlayer
-            script={previewDoc!}
+            doc={previewDoc!}
             basePath={basePath}
             showControls
             muted
@@ -172,6 +177,7 @@ export function PreviewPanel({ basePath = '/', className, workspaceContainer }:
             displayMode={activeDisplayMode}
             theme={activeTheme}
             captionStyle={activeCaptionStyle}
+            captionsEnabled={activeCaptionsEnabled}
           />
         )}
       </div>

package/src/RawEditor.tsx

@@ -12,6 +12,7 @@ import type * as monaco from 'monaco-editor';
 import { useEditorContext } from './EditorContext';
 import { getAvailableTemplates } from '@bendyline/squisq/doc';
 import { suggestIcons, resolveIcon, iconGlyph } from '@bendyline/squisq/icons';
+import { BLOCK_META_KEY_DESCRIPTORS, tokenizeAttrTokens } from '@bendyline/squisq/markdown';
 import { SQUISQ_MEDIA_MIME, parseSquisqMediaPayload } from './mediaDragMime';
 import { useMonacoLoader } from './useMonacoLoader';
 
@@ -30,7 +31,12 @@ import { useMonacoLoader } from './useMonacoLoader';
 //   resolve: { alias: [{ find: /^monaco-editor$/, replacement: './monaco-slim.ts' }] }
 //
 // Where monaco-slim.ts re-exports 'monaco-editor/esm/vs/editor/editor.api'
-// plus only the language contributions needed (e.g. markdown, javascript).
+// plus only the language contributions actually needed
+// (`basic-languages/monaco.contribution` for the broad TM grammars,
+// and any of `language/{css,html,json,typescript}/monaco.contribution`
+// for the rich language services). Skipping the language contributions
+// entirely means `defaultLanguage` becomes inert — no tokenizer
+// registered, so every file renders as plain foreground text.
 
 // Squisq Monaco themes: same syntax highlighting as vs / vs-dark, but with
 // Monaco's internal gutter (line numbers + folding margin) and overview
@@ -50,8 +56,14 @@ const SQUISQ_THEMES: Record<string, string> = {
 };
 
 export interface RawEditorProps {
-  /** Monaco editor theme (default: 'vs-dark') */
-  theme?: string;
+  /**
+   * Monaco editor theme name (default: `'vs'`). Accepts Monaco's built-in
+   * theme ids (`'vs'`, `'vs-dark'`, `'hc-black'`) — which are transparently
+   * mapped to the Squisq-tinted variants — or any custom theme registered
+   * via `monaco.editor.defineTheme`. This is the *code editor* color
+   * theme, distinct from the shell's light/dark `colorScheme`.
+   */
+  monacoTheme?: string;
   /** Show minimap (default: false) */
   minimap?: boolean;
   /** Font size in pixels (default: 14) */
@@ -74,7 +86,7 @@ export interface RawEditorProps {
  * Binds to the shared EditorContext for source synchronization.
  */
 export function RawEditor({
-  theme = 'vs',
+  monacoTheme = 'vs',
   minimap = false,
   fontSize = 14,
   wordWrap = 'on',
@@ -82,7 +94,7 @@ export function RawEditor({
   submitOnEnter,
   readOnly = false,
 }: RawEditorProps) {
-  const { markdownSource, setMarkdownSource, setMonacoEditor, language, mentionProvider } =
+  const { editorSource, setEditorSource, setMonacoEditor, language, mentionProvider, doc } =
     useEditorContext();
   const { monaco: monacoNs, ready: monacoReady } = useMonacoLoader();
   const editorRef = useRef<monaco.editor.IStandaloneCodeEditor | null>(null);
@@ -90,6 +102,7 @@ export function RawEditor({
   const completionDisposable = useRef<monaco.IDisposable | null>(null);
   const mentionCompletionDisposable = useRef<monaco.IDisposable | null>(null);
   const iconCompletionDisposable = useRef<monaco.IDisposable | null>(null);
+  const attrCompletionDisposable = useRef<monaco.IDisposable | null>(null);
   const iconGlyphDecorations = useRef<monaco.editor.IEditorDecorationsCollection | null>(null);
   const dropCleanupRef = useRef<(() => void) | null>(null);
   const keyDisposable = useRef<monaco.IDisposable | null>(null);
@@ -105,6 +118,35 @@ export function RawEditor({
     mentionProviderRef.current = mentionProvider;
   }, [mentionProvider]);
 
+  // Template completion list: built-in registry names plus any custom
+  // templates inlined in the active doc's frontmatter (`doc.customTemplates`
+  // — the same set that actually renders via `{[name]}`). Held in a ref
+  // (like mentionProvider above) so the once-registered provider always
+  // reads the latest set — custom templates created after mount must show
+  // up without re-mounting Monaco.
+  const docCustomTemplates = doc?.customTemplates;
+  const templateEntriesRef = useRef<{ name: string; detail: string }[] | null>(null);
+  if (templateEntriesRef.current === null) {
+    templateEntriesRef.current = getAvailableTemplates().map((name) => ({
+      name,
+      detail: 'Block template',
+    }));
+  }
+  useEffect(() => {
+    const builtIns = getAvailableTemplates().map((name) => ({
+      name,
+      detail: 'Block template',
+    }));
+    const seen = new Set(builtIns.map((b) => b.name));
+    const custom = (docCustomTemplates ?? [])
+      .filter((t) => !seen.has(t.name))
+      .map((t) => ({
+        name: t.name,
+        detail: t.label ? `Custom — ${t.label}` : 'Custom template',
+      }));
+    templateEntriesRef.current = [...builtIns, ...custom];
+  }, [docCustomTemplates]);
+
   const handleBeforeMount: BeforeMount = useCallback((monaco) => {
     monaco.editor.defineTheme('squisq-light', {
       base: 'vs',
@@ -143,11 +185,12 @@ export function RawEditor({
       mentionCompletionDisposable.current = null;
       iconCompletionDisposable.current?.dispose();
       iconCompletionDisposable.current = null;
+      attrCompletionDisposable.current?.dispose();
+      attrCompletionDisposable.current = null;
 
       // Register the `{[template]}` completion provider only for markdown
       // files — it's meaningless for TypeScript, JSON, Python, etc.
       if (language === 'markdown') {
-        const templates = getAvailableTemplates();
         completionDisposable.current = monaco.languages.registerCompletionItemProvider('markdown', {
           triggerCharacters: ['['],
           provideCompletionItems(model: monaco.editor.ITextModel, position: monaco.Position) {
@@ -161,6 +204,12 @@ export function RawEditor({
             const bracketIdx = textBeforeCursor.lastIndexOf('{[');
             if (bracketIdx === -1) return { suggestions: [] };
 
+            // Template names are the FIRST token after `{[`. Once a space
+            // follows the name we're in the `key=value` attribute region —
+            // the attribute provider handles that, so bail here to avoid
+            // offering template names mid-attribute.
+            if (/\s/.test(textBeforeCursor.slice(bracketIdx + 2))) return { suggestions: [] };
+
             // When Monaco's bracket auto-pair has already produced the
             // closing `]}` we just leave it in place and skip the
             // suffix — otherwise accepting `sectionHeader` on
@@ -176,13 +225,13 @@ export function RawEditor({
               position.column,
             );
 
-            const suggestions = templates.map((name) => ({
+            const suggestions = (templateEntriesRef.current ?? []).map(({ name, detail }) => ({
               label: name,
               filterText: name,
               kind: monaco.languages.CompletionItemKind.Value,
               insertText: name + suffix,
               range,
-              detail: 'Block template',
+              detail,
               sortText: name,
             }));
 
@@ -324,6 +373,110 @@ export function RawEditor({
             },
           },
         );
+
+        // `{[name key=value]}` block-meta attribute completion. Fires on
+        // heading lines once the cursor is past the template name (the
+        // first token), where attributes like `transition=` apply to the
+        // block. Two modes:
+        //   - bare token   → suggest attribute KEYS (insert `key=`)
+        //   - after `key=` → suggest that key's VALUES, when it has a
+        //     closed set (e.g. transition / transitionDirection)
+        // The descriptor list comes from core so keys and value enums stay
+        // in lockstep with what `coerceAnnotationValues` actually accepts.
+        attrCompletionDisposable.current = monaco.languages.registerCompletionItemProvider(
+          'markdown',
+          {
+            triggerCharacters: ['=', ' '],
+            provideCompletionItems(model, position) {
+              const lineContent = model.getLineContent(position.lineNumber);
+              // Block-meta attributes only mean something on a heading's
+              // template annotation — same gate as the template provider.
+              if (!/^#{1,6}\s/.test(lineContent)) return { suggestions: [] };
+
+              const textBeforeCursor = lineContent.substring(0, position.column - 1);
+              const bracketIdx = textBeforeCursor.lastIndexOf('{[');
+              if (bracketIdx === -1) return { suggestions: [] };
+
+              // Bail if a `]` already closed the annotation before the
+              // cursor — we'd be past it, not inside the attribute list.
+              const innerBefore = textBeforeCursor.slice(bracketIdx + 2);
+              if (innerBefore.includes(']')) return { suggestions: [] };
+              // The first token is the template name; attributes only begin
+              // after a whitespace separator. No space yet → still the name.
+              if (!/\s/.test(innerBefore)) return { suggestions: [] };
+
+              // Current token = run of non-whitespace ending at the cursor.
+              const lastWsMatch = innerBefore.match(/\s(\S*)$/);
+              const currentToken = lastWsMatch ? lastWsMatch[1] : '';
+              const tokenStartCol = position.column - currentToken.length;
+
+              const eqIdx = currentToken.indexOf('=');
+              if (eqIdx >= 0) {
+                // ── Value mode: `key=<partial>` ──
+                const key = currentToken.slice(0, eqIdx);
+                const descriptor = BLOCK_META_KEY_DESCRIPTORS.find((d) => d.key === key);
+                if (!descriptor?.values) return { suggestions: [] };
+                const range = new monaco.Range(
+                  position.lineNumber,
+                  tokenStartCol + eqIdx + 1, // after `=`
+                  position.lineNumber,
+                  position.column,
+                );
+                return {
+                  suggestions: descriptor.values.map((value, i) => ({
+                    label: value,
+                    filterText: value,
+                    kind: monaco.languages.CompletionItemKind.EnumMember,
+                    insertText: value,
+                    range,
+                    detail: descriptor.description,
+                    sortText: String(i).padStart(4, '0'),
+                  })),
+                };
+              }
+
+              // ── Key mode: suggest attribute names not already present ──
+              // Collect keys already set anywhere in the annotation so we
+              // don't re-offer them; keep the key under the cursor eligible
+              // so re-editing an existing `key=` still suggests it.
+              const afterBracket = lineContent.slice(bracketIdx + 2);
+              const closeIdx = afterBracket.indexOf(']}');
+              const fullInner = closeIdx === -1 ? afterBracket : afterBracket.slice(0, closeIdx);
+              const present = new Set(
+                tokenizeAttrTokens(fullInner)
+                  .map((t) => {
+                    const i = t.indexOf('=');
+                    return i > 0 ? t.slice(0, i) : null;
+                  })
+                  .filter((k): k is string => k != null),
+              );
+              present.delete(currentToken);
+
+              const range = new monaco.Range(
+                position.lineNumber,
+                tokenStartCol,
+                position.lineNumber,
+                position.column,
+              );
+              const suggestions = BLOCK_META_KEY_DESCRIPTORS.filter((d) => !present.has(d.key)).map(
+                (d, i) => ({
+                  label: d.key,
+                  filterText: d.key,
+                  kind: monaco.languages.CompletionItemKind.Property,
+                  insertText: `${d.key}=`,
+                  range,
+                  detail: d.values ? d.description : `${d.description} — ${d.valueHint}`,
+                  sortText: String(i).padStart(4, '0'),
+                  // Closed-set keys chain straight into their value list.
+                  ...(d.values
+                    ? { command: { id: 'editor.action.triggerSuggest', title: '' } }
+                    : {}),
+                }),
+              );
+              return { suggestions };
+            },
+          },
+        );
       }
 
       // Chat-composer mode: intercept Enter before Monaco inserts a newline.
@@ -401,6 +554,8 @@ export function RawEditor({
       mentionCompletionDisposable.current = null;
       iconCompletionDisposable.current?.dispose();
       iconCompletionDisposable.current = null;
+      attrCompletionDisposable.current?.dispose();
+      attrCompletionDisposable.current = null;
       iconGlyphDecorations.current?.clear();
       iconGlyphDecorations.current = null;
       dropCleanupRef.current?.();
@@ -414,24 +569,31 @@ export function RawEditor({
     (value) => {
       if (isExternalUpdate.current) return;
       if (value !== undefined) {
-        setMarkdownSource(value);
+        setEditorSource(value);
       }
     },
-    [setMarkdownSource],
+    [setEditorSource],
   );
 
-  // When external changes happen (e.g. from WYSIWYG), update Monaco
+  // When external changes happen (e.g. from WYSIWYG, or navigating to another
+  // block in block-at-a-time mode), update Monaco. In block mode `editorSource`
+  // is the active block's slice, so this swaps Monaco's content on navigation.
   useEffect(() => {
     const editor = editorRef.current;
     if (editor) {
       const currentValue = editor.getValue();
-      if (currentValue !== markdownSource) {
+      // Ignore trailing-whitespace-only differences from block-mode splice
+      // normalization — calling setValue for those resets the Monaco cursor.
+      if (
+        currentValue !== editorSource &&
+        currentValue.replace(/\s+$/, '') !== editorSource.replace(/\s+$/, '')
+      ) {
         isExternalUpdate.current = true;
-        editor.setValue(markdownSource);
+        editor.setValue(editorSource);
         isExternalUpdate.current = false;
       }
     }
-  }, [markdownSource]);
+  }, [editorSource]);
 
   // ── Inline FontAwesome glyph decorations ────────────
   // Walk the markdown source on every change, find each resolvable
@@ -482,9 +644,9 @@ export function RawEditor({
     } else {
       iconGlyphDecorations.current.set(decorations);
     }
-  }, [markdownSource, language, monacoNs]);
+  }, [editorSource, language, monacoNs]);
 
-  const effectiveTheme = SQUISQ_THEMES[theme] ?? theme;
+  const effectiveTheme = SQUISQ_THEMES[monacoTheme] ?? monacoTheme;
 
   // Wait for the lazy monaco namespace + `loader.config()` to settle
   // before mounting `<Editor>`. Without this gate, the @monaco-editor/
@@ -516,7 +678,7 @@ export function RawEditor({
     <div className={className} style={{ width: '100%', height: '100%' }} data-testid="raw-editor">
       <Editor
         defaultLanguage={language}
-        value={markdownSource}
+        value={editorSource}
         theme={effectiveTheme}
         beforeMount={handleBeforeMount}
         onMount={handleMount}

package/src/RecorderEntry.tsx

@@ -24,6 +24,7 @@
 import { useCallback } from 'react';
 import { RecorderPanel } from './recorder/RecorderPanel.js';
 import type { RecorderSaveResult } from './recorder/RecorderModal.js';
+import { insertMediaBlock } from './recorder/insertMediaBlock.js';
 import { useEditorContext } from './EditorContext';
 
 /**
@@ -98,14 +99,10 @@ export function RecorderEntry() {
         }
         const audioTag = `<audio src="${result.relativePath}" controls></audio>`;
         if (activeView === 'wysiwyg' && tiptapEditor) {
-          tiptapEditor
-            .chain()
-            .focus()
-            .insertContent({
-              type: 'audio',
-              attrs: { src: result.relativePath, controls: true },
-            })
-            .run();
+          insertMediaBlock(tiptapEditor, {
+            type: 'audio',
+            attrs: { src: result.relativePath, controls: true },
+          });
           return;
         }
         if (activeView === 'raw' && monacoEditor) {
@@ -124,14 +121,10 @@ export function RecorderEntry() {
       // aspect ratio is preserved regardless of source dimensions.
       const videoTag = `<video src="${result.relativePath}" controls width="480"></video>`;
       if (activeView === 'wysiwyg' && tiptapEditor) {
-        tiptapEditor
-          .chain()
-          .focus()
-          .insertContent({
-            type: 'video',
-            attrs: { src: result.relativePath, controls: true, width: 480 },
-          })
-          .run();
+        insertMediaBlock(tiptapEditor, {
+          type: 'video',
+          attrs: { src: result.relativePath, controls: true, width: 480 },
+        });
         return;
       }
       if (activeView === 'raw' && monacoEditor) {

package/src/TemplateAnnotation.ts

@@ -15,6 +15,7 @@
 
 import Heading from '@tiptap/extension-heading';
 import { templateLabel } from './TemplatePicker';
+import { summarizeBlockProps } from './blockProperties';
 
 /**
  * HeadingWithTemplate — drop-in replacement for Tiptap's Heading that
@@ -40,6 +41,14 @@ export const HeadingWithTemplate = Heading.extend({
           return { 'data-template-params': attributes.dataTemplateParams };
         },
       },
+      dataBlockAttrs: {
+        default: null,
+        parseHTML: (element: HTMLElement) => element.getAttribute('data-block-attrs') || null,
+        renderHTML: (attributes: Record<string, unknown>) => {
+          if (!attributes.dataBlockAttrs) return {};
+          return { 'data-block-attrs': attributes.dataBlockAttrs };
+        },
+      },
     };
   },
 
@@ -47,6 +56,12 @@ export const HeadingWithTemplate = Heading.extend({
     const level = node.attrs.level;
     const tag = `h${level}`;
     const templateName = HTMLAttributes['data-template'];
+    // Concise summary of authored block properties (transition / timing),
+    // painted on the props badge so the canvas shows what's set at a glance.
+    const propsSummary = summarizeBlockProps(
+      (HTMLAttributes['data-block-attrs'] as string | undefined) ?? null,
+      (HTMLAttributes['data-template-params'] as string | undefined) ?? null,
+    );
 
     // Render heading with a trailing badge span. The badge has no text
     // content — its label is painted via CSS `content: attr(data-template-label)`
@@ -76,6 +91,7 @@ export const HeadingWithTemplate = Heading.extend({
             'data-template-label': templateLabel(templateName),
           },
         ],
+        propsBadgeSpec(propsSummary),
       ];
     }
 
@@ -94,6 +110,34 @@ export const HeadingWithTemplate = Heading.extend({
           title: 'Choose block template',
         },
       ],
+      propsBadgeSpec(propsSummary),
     ];
   },
 });
+
+/**
+ * The block-properties chip rendered beside the template badge — the on-canvas
+ * entry point to the {@link BlockPropertiesPopover} (transition, timing, …).
+ *
+ * Like the template badge, this is an EMPTY inert span: the sliders glyph and
+ * the optional `summary` text are painted via CSS (`::before` / `::after` with
+ * `content: attr(data-props-summary)`, using the Font Awesome font the editor
+ * already loads). Keeping it childless is deliberate — `tiptapToMarkdown`
+ * serializes the rendered heading HTML, so any real child node here would risk
+ * leaking into the markdown; a `data-*` attribute is stripped with the span.
+ * Clicks are delegated in `WysiwygEditor`.
+ */
+function propsBadgeSpec(summary: string): [string, Record<string, string>] {
+  const attrs: Record<string, string> = {
+    class: 'squisq-props-badge',
+    contenteditable: 'false',
+    role: 'button',
+    tabindex: '0',
+    'aria-haspopup': 'dialog',
+    title: summary ? `Block properties — ${summary}` : 'Block properties',
+  };
+  // Only set the attribute when there's something to show, so the CSS
+  // `[data-props-summary]` selector cleanly distinguishes "has properties".
+  if (summary) attrs['data-props-summary'] = summary;
+  return ['span', attrs];
+}