@bendyline/squisq-editor-react 1.6.1 → 1.6.2

package/src/PreviewControls.tsx

@@ -62,6 +62,10 @@ export interface PreviewSettings {
    *  that style. The single entry point so the toggle buttons persist in one
    *  frontmatter write. */
   setCaptionMode: (mode: CaptionMode) => void;
+  /** Whether Squisq should synthesize and show its managed cover slide. */
+  activeCoverSlide: boolean;
+  /** Enable/disable the managed cover slide. */
+  setCoverSlideEnabled: (enabled: boolean) => void;
   /** User-authored themes (doc + browser library) for the picker's "Custom" group. */
   customThemes: Theme[];
   /** Open the custom-theme designer for a theme (or null to create a new one). */
@@ -171,6 +175,15 @@ function resolveFrontmatterCaptionMode(value: unknown): CaptionMode | null {
   return null;
 }
 
+function resolveFrontmatterBoolean(value: unknown): boolean | null {
+  if (typeof value === 'boolean') return value;
+  if (typeof value !== 'string') return null;
+  const v = value.trim().toLowerCase();
+  if (v === 'true' || v === 'yes' || v === 'on' || v === 'show' || v === 'visible') return true;
+  if (v === 'false' || v === 'no' || v === 'off' || v === 'hide' || v === 'hidden') return false;
+  return null;
+}
+
 // ── Provider ─────────────────────────────────────────────────────
 
 export interface PreviewSettingsProviderProps {
@@ -192,6 +205,7 @@ const FM_KEYS = {
   theme: { canonical: 'squisq-theme', legacy: 'theme' as const },
   transform: { canonical: 'squisq-transform', legacy: 'transform-style' as const },
   captions: { canonical: 'squisq-captions', legacy: 'caption-style' as const },
+  coverSlide: { canonical: 'squisq-cover-slide', legacy: 'cover-slide' as const },
 } as const;
 
 function readFrontmatterKey(
@@ -366,6 +380,26 @@ export function PreviewSettingsProvider({
     [persistFrontmatter],
   );
 
+  // Managed cover slide — generated from the document startBlock. Defaults on
+  // for existing documents; authors can persist an explicit off switch.
+  const fmCoverSlide = useMemo(
+    () =>
+      resolveFrontmatterBoolean(
+        readFrontmatterKey(frontmatter, FM_KEYS.coverSlide.canonical, FM_KEYS.coverSlide.legacy),
+      ),
+    [frontmatter],
+  );
+  const [selectedCoverSlide, setSelectedCoverSlide] = useState<boolean | null>(null);
+  useEffect(() => setSelectedCoverSlide(null), [fmCoverSlide]);
+  const activeCoverSlide = selectedCoverSlide ?? fmCoverSlide ?? true;
+  const handleSetCoverSlideEnabled = useCallback(
+    (enabled: boolean) => {
+      setSelectedCoverSlide(enabled);
+      persistFrontmatter({ [FM_KEYS.coverSlide.canonical]: enabled ? 'true' : 'false' });
+    },
+    [persistFrontmatter],
+  );
+
   // Config for the docked designer (rendered by `<ThemeDesignerDock>` in the
   // editor content row). Null when closed. setPreviewTheme is a stable setter.
   const themeDesigner = useMemo<ThemeDesignerConfig | null>(
@@ -396,6 +430,8 @@ export function PreviewSettingsProvider({
       activeCaptionStyle,
       activeCaptionsEnabled,
       setCaptionMode: handleSetCaptionMode,
+      activeCoverSlide,
+      setCoverSlideEnabled: handleSetCoverSlideEnabled,
       customThemes,
       openThemeDesigner,
       deleteCustomTheme,
@@ -410,9 +446,11 @@ export function PreviewSettingsProvider({
       activeTransformStyle,
       activeCaptionStyle,
       activeCaptionsEnabled,
+      activeCoverSlide,
       handleSetThemeId,
       handleSetTransformStyle,
       handleSetCaptionMode,
+      handleSetCoverSlideEnabled,
       customThemes,
       openThemeDesigner,
       deleteCustomTheme,
@@ -473,15 +511,28 @@ const TRANSFORM_STYLE_OPTIONS = [
 /**
  * Left-to-right priority order for the preview controls. As the toolbar
  * narrows, controls drop into the overflow menu from the END of this list
- * first (Captions, then Transform, …), so the higher-priority control (Theme)
- * stays inline the longest.
- *
- * Display mode and aspect ratio are not here — they're surfaced separately as
- * the segmented {@link PreviewModeSwitch} / {@link PreviewFormatSwitch} on the
- * left of the toolbar.
+ * first (Cover, then Captions, …). Display mode and aspect ratio stay inline
+ * the longest, but still collapse into the same menu when the toolbar is very
+ * constrained.
  */
-type ControlKey = 'theme' | 'transform' | 'captions';
-const CONTROL_KEYS: ControlKey[] = ['theme', 'transform', 'captions'];
+type ControlKey = 'mode' | 'format' | 'theme' | 'transform' | 'captions' | 'cover';
+const CONTROL_KEYS: ControlKey[] = ['mode', 'format', 'theme', 'transform', 'captions', 'cover'];
+
+const PREVIEW_POPOVER_GAP = 4;
+const PREVIEW_POPOVER_MARGIN = 8;
+const PREVIEW_POPOVER_FALLBACK_WIDTH = 220;
+
+function clampPreviewPopoverLeft(
+  triggerRect: DOMRect,
+  popoverWidth: number,
+  viewportWidth: number,
+): number {
+  const maxLeft = Math.max(
+    PREVIEW_POPOVER_MARGIN,
+    viewportWidth - popoverWidth - PREVIEW_POPOVER_MARGIN,
+  );
+  return Math.min(Math.max(PREVIEW_POPOVER_MARGIN, triggerRect.right - popoverWidth), maxLeft);
+}
 
 // ── Shared styles ────────────────────────────────────────────────
 
@@ -510,7 +561,7 @@ const selectStyle: React.CSSProperties = {
  * whole row in and out at a fixed window-width breakpoint, the controls
  * measure how many of them actually fit in the width the toolbar gives them
  * and keep that many inline, folding the rest — from the low-priority end of
- * {@link CONTROL_KEYS} — into a single settings (gear) button's popover. As
+ * {@link CONTROL_KEYS} — into a single ellipsis button's popover. As
  * the toolbar widens or narrows, controls migrate one at a time between the
  * inline row and the menu, so the available space is always well used and the
  * row never wraps onto a second line.
@@ -526,6 +577,27 @@ export function PreviewToolbarControls() {
   // inline and overflow is computed from these per-control measurements.
   const probeRef = useRef<HTMLDivElement>(null);
   const popoverRef = useRef<HTMLDivElement>(null);
+  const popoverTriggerRef = useRef<HTMLButtonElement>(null);
+  const popoverPanelRef = useRef<HTMLDivElement>(null);
+  const [popoverAnchor, setPopoverAnchor] = useState<{ top: number; left: number } | null>(null);
+
+  const updatePopoverPosition = useCallback(() => {
+    const trigger = popoverTriggerRef.current;
+    if (!trigger) return;
+    const triggerRect = trigger.getBoundingClientRect();
+    const measuredWidth =
+      popoverPanelRef.current?.getBoundingClientRect().width ?? PREVIEW_POPOVER_FALLBACK_WIDTH;
+    const popoverWidth = Math.min(measuredWidth, window.innerWidth - PREVIEW_POPOVER_MARGIN * 2);
+    setPopoverAnchor({
+      top: triggerRect.bottom + PREVIEW_POPOVER_GAP,
+      left: clampPreviewPopoverLeft(triggerRect, popoverWidth, window.innerWidth),
+    });
+  }, []);
+
+  const closePopover = useCallback(() => {
+    setPopoverOpen(false);
+    setPopoverAnchor(null);
+  }, []);
 
   // Fit detection: keep as many controls inline as fit, overflow the rest.
   useLayoutEffect(() => {
@@ -534,7 +606,7 @@ export function PreviewToolbarControls() {
     if (!root || !probe) return;
     const GAP = 6; // matches the row's flex `gap`
     const LEAD_PAD = 9; // root's left padding, eaten before any control
-    const GEAR_RESERVE = 40; // width kept for the overflow gear button (+ its gap)
+    const OVERFLOW_TRIGGER_RESERVE = 40; // width kept for the ellipsis button (+ its gap)
     const SAFETY = 2;
     const measure = () => {
       const available = root.clientWidth - LEAD_PAD;
@@ -549,8 +621,8 @@ export function PreviewToolbarControls() {
         setVisibleCount(widths.length);
         return;
       }
-      // Otherwise reserve room for the gear and fit as many as possible.
-      const budget = available - GEAR_RESERVE - GAP - SAFETY;
+      // Otherwise reserve room for the ellipsis and fit as many as possible.
+      const budget = available - OVERFLOW_TRIGGER_RESERVE - GAP - SAFETY;
       let count = 0;
       while (count < widths.length && rowWidth(count + 1) <= budget) count++;
       setVisibleCount(count);
@@ -568,13 +640,29 @@ export function PreviewToolbarControls() {
   useEffect(() => {
     if (!popoverOpen) return;
     const handler = (e: MouseEvent) => {
-      if (popoverRef.current && !popoverRef.current.contains(e.target as Node)) {
-        setPopoverOpen(false);
-      }
+      const target = e.target as Node;
+      if (popoverRef.current?.contains(target)) return;
+      if (popoverPanelRef.current?.contains(target)) return;
+      closePopover();
     };
     document.addEventListener('mousedown', handler);
     return () => document.removeEventListener('mousedown', handler);
-  }, [popoverOpen]);
+  }, [closePopover, popoverOpen]);
+
+  useLayoutEffect(() => {
+    if (!popoverOpen) return;
+    updatePopoverPosition();
+  }, [popoverOpen, updatePopoverPosition, visibleCount]);
+
+  useEffect(() => {
+    if (!popoverOpen) return;
+    window.addEventListener('resize', updatePopoverPosition);
+    window.addEventListener('scroll', updatePopoverPosition, true);
+    return () => {
+      window.removeEventListener('resize', updatePopoverPosition);
+      window.removeEventListener('scroll', updatePopoverPosition, true);
+    };
+  }, [popoverOpen, updatePopoverPosition]);
 
   // "Edit theme" pencil next to the dropdown. A custom theme opens directly in
   // the designer; a built-in seeds a NEW "Modified <name>" custom theme based
@@ -593,6 +681,26 @@ export function PreviewToolbarControls() {
   // label-over-control layout used inside the overflow popover.
   const renderControl = (key: ControlKey, compact: boolean): ReactNode => {
     switch (key) {
+      case 'mode':
+        return (
+          <div
+            key="mode"
+            className={`squisq-preview-control squisq-preview-control--seg${compact ? ' squisq-preview-control--compact' : ''}`}
+          >
+            {compact && <label style={labelStyle}>Mode:</label>}
+            <PreviewModeSwitch />
+          </div>
+        );
+      case 'format':
+        return (
+          <div
+            key="format"
+            className={`squisq-preview-control squisq-preview-control--seg${compact ? ' squisq-preview-control--compact' : ''}`}
+          >
+            {compact && <label style={labelStyle}>Format:</label>}
+            <PreviewFormatSwitch />
+          </div>
+        );
       case 'theme':
         return (
           <div
@@ -684,6 +792,23 @@ export function PreviewToolbarControls() {
           </div>
         );
       }
+      case 'cover':
+        return (
+          <div
+            key="cover"
+            className={`squisq-preview-control${compact ? ' squisq-preview-control--compact' : ''}`}
+          >
+            <label style={labelStyle}>Cover:</label>
+            <label className="squisq-preview-checkbox">
+              <input
+                type="checkbox"
+                checked={s.activeCoverSlide}
+                onChange={(e) => s.setCoverSlideEnabled(e.target.checked)}
+              />
+              <span>Cover slide</span>
+            </label>
+          </div>
+        );
     }
   };
 
@@ -691,10 +816,18 @@ export function PreviewToolbarControls() {
   const visibleKeys = CONTROL_KEYS.slice(0, visibleCount);
   const overflowKeys = CONTROL_KEYS.slice(visibleCount);
 
+  useEffect(() => {
+    if (!hasOverflow && popoverOpen) closePopover();
+  }, [closePopover, hasOverflow, popoverOpen]);
+
   // The root is a flex:1 filler so it always spans the toolbar's leftover
   // width (which is what the fit measurement reads).
   return (
-    <div className="squisq-preview-controls" ref={rootRef}>
+    <div
+      className="squisq-preview-controls"
+      data-has-overflow={hasOverflow ? 'true' : undefined}
+      ref={rootRef}
+    >
       {/* Hidden probe — every control at natural width, measured to decide the
           inline/overflow split. Absolutely positioned so it never affects
           layout. */}
@@ -702,35 +835,37 @@ export function PreviewToolbarControls() {
         {CONTROL_KEYS.map((key) => renderControl(key, false))}
       </div>
 
-      <div className="squisq-preview-controls-inline">
-        {visibleKeys.map((key) => renderControl(key, false))}
-      </div>
+      {visibleKeys.length > 0 && (
+        <div className="squisq-preview-controls-inline">
+          {visibleKeys.map((key) => renderControl(key, false))}
+        </div>
+      )}
 
       {hasOverflow && (
         <div className="squisq-preview-controls-compact" ref={popoverRef}>
           <button
+            ref={popoverTriggerRef}
             className={`squisq-toolbar-button${popoverOpen ? ' squisq-toolbar-button--active' : ''}`}
-            onClick={() => setPopoverOpen((v) => !v)}
+            onClick={() => {
+              if (popoverOpen) {
+                closePopover();
+                return;
+              }
+              updatePopoverPosition();
+              setPopoverOpen(true);
+            }}
             aria-label="More preview settings"
             title="More preview settings"
             aria-expanded={popoverOpen}
           >
-            <svg
-              width="16"
-              height="16"
-              viewBox="0 0 16 16"
-              fill="none"
-              stroke="currentColor"
-              strokeWidth="1.5"
-              strokeLinecap="round"
-              strokeLinejoin="round"
-            >
-              <circle cx="8" cy="8" r="2.5" />
-              <path d="M13.5 8a5.5 5.5 0 01-.4 1.8l1.2 1.2-1.6 1.6-1.2-1.2A5.5 5.5 0 018 13.5a5.5 5.5 0 01-3.5-1.3L3.3 13.4 1.7 11.8l1.2-1.2A5.5 5.5 0 012.5 8c0-.6.1-1.2.4-1.8L1.7 5 3.3 3.4l1.2 1.2A5.5 5.5 0 018 2.5c1.3 0 2.5.5 3.5 1.3l1.2-1.2 1.6 1.6-1.2 1.2c.3.6.4 1.2.4 1.6z" />
-            </svg>
+            <Icon icon="fa-solid fa-ellipsis" />
           </button>
-          {popoverOpen && (
-            <div className="squisq-preview-controls-popover">
+          {popoverOpen && popoverAnchor && (
+            <div
+              ref={popoverPanelRef}
+              className="squisq-preview-controls-popover"
+              style={{ top: popoverAnchor.top, left: popoverAnchor.left }}
+            >
               {overflowKeys.map((key) => renderControl(key, true))}
             </div>
           )}
@@ -741,10 +876,9 @@ export function PreviewToolbarControls() {
 }
 
 /**
- * Segmented display-mode switch (Video / Slideshow / Document / Page) rendered
- * as four connected buttons on the left of the Play toolbar — the prominent,
- * one-click counterpart to the old "Mode:" dropdown. Reads and writes the same
- * `activeDisplayMode` in preview settings.
+ * Segmented display-mode switch (Video / Slideshow / Document / Page), used
+ * inline in the Use toolbar and inside its overflow popover. Reads and writes
+ * the same `activeDisplayMode` in preview settings.
  */
 export function PreviewModeSwitch() {
   const s = usePreviewSettings();
@@ -787,10 +921,9 @@ function AspectIcon({ w, h }: { w: number; h: number }) {
 }
 
 /**
- * Segmented aspect-ratio switch (16:9 / 1:1 / 9:16 / 4:3) rendered as connected
- * icon buttons on the left of the Play toolbar, next to the mode switch — the
- * one-click counterpart to the old "Format:" dropdown. Reads and writes the
- * same `activePreset` in preview settings.
+ * Segmented aspect-ratio switch (16:9 / 1:1 / 9:16 / 4:3), used inline in the
+ * Use toolbar and inside its overflow popover. Reads and writes the same
+ * `activePreset` in preview settings.
  */
 export function PreviewFormatSwitch() {
   const s = usePreviewSettings();

package/src/PreviewPanel.tsx

@@ -49,6 +49,7 @@ export function PreviewPanel({ basePath = '/', className, workspaceContainer }:
     activeTransformStyle,
     activeCaptionStyle,
     activeCaptionsEnabled,
+    activeCoverSlide,
   } = usePreviewSettings();
 
   // Build the player-ready Doc whenever the parsed doc changes.
@@ -178,6 +179,7 @@ export function PreviewPanel({ basePath = '/', className, workspaceContainer }:
             theme={activeTheme}
             captionStyle={activeCaptionStyle}
             captionsEnabled={activeCaptionsEnabled}
+            showCoverSlide={activeCoverSlide}
           />
         )}
       </div>

package/src/TemplateAnnotation.ts

@@ -63,10 +63,10 @@ export const HeadingWithTemplate = Heading.extend({
       (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)`
-    // so the template name never becomes part of the serialized heading
-    // text (which would leak into markdown on round-trip).
+    // Render heading with a trailing badge span. The badge and its inner core
+    // have no real text content — labels/braces are painted via CSS so the
+    // template name never becomes part of serialized heading text (which
+    // would leak into markdown on round-trip).
     //
     // When no template is set we still render a subtle "empty" badge so
     // authors have a visible affordance for opening the template picker
@@ -86,10 +86,17 @@ export const HeadingWithTemplate = Heading.extend({
             role: 'button',
             tabindex: '0',
             'aria-haspopup': 'listbox',
-            title: 'Change block template',
+            title: 'Change block type',
             'data-template': templateName,
-            'data-template-label': templateLabel(templateName),
           },
+          [
+            'span',
+            {
+              class: 'squisq-template-badge-core',
+              'data-template-label': templateLabel(templateName),
+              'aria-hidden': 'true',
+            },
+          ],
         ],
         propsBadgeSpec(propsSummary),
       ];
@@ -107,8 +114,16 @@ export const HeadingWithTemplate = Heading.extend({
           role: 'button',
           tabindex: '0',
           'aria-haspopup': 'listbox',
-          title: 'Choose block template',
+          title: 'Choose block type',
         },
+        [
+          'span',
+          {
+            class: 'squisq-template-badge-core',
+            'data-template-label': 'Block',
+            'aria-hidden': 'true',
+          },
+        ],
       ],
       propsBadgeSpec(propsSummary),
     ];

package/src/TemplateContentPreview.tsx

@@ -0,0 +1,56 @@
+import { useMemo } from 'react';
+import { BlockRenderer, MediaContext } from '@bendyline/squisq-react';
+import {
+  resolveTemplateContentPreviewResult,
+  type TemplatePreviewSource,
+} from './templateContentPreviewResolver';
+
+export interface TemplateContentPreviewProps {
+  templateName: string;
+  source?: TemplatePreviewSource;
+  fallback: JSX.Element;
+}
+
+export function TemplateContentPreview({
+  templateName,
+  source,
+  fallback,
+}: TemplateContentPreviewProps) {
+  const preview = useMemo(
+    () => (source ? resolveTemplateContentPreviewResult(templateName, source) : null),
+    [templateName, source],
+  );
+
+  if (!source) return fallback;
+
+  if (!preview?.visual) {
+    if (!preview?.warning) return fallback;
+    return (
+      <div
+        className="squisq-template-gallery-content-preview squisq-template-gallery-content-preview--fallback"
+        style={{ aspectRatio: `${source.viewport.width} / ${source.viewport.height}` }}
+        aria-hidden="true"
+      >
+        <div className="squisq-template-gallery-content-preview-fallback">{fallback}</div>
+        <span className="squisq-template-gallery-content-preview-warning">{preview.warning}</span>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="squisq-template-gallery-content-preview"
+      style={{ aspectRatio: `${source.viewport.width} / ${source.viewport.height}` }}
+      aria-hidden="true"
+    >
+      <MediaContext.Provider value={source.mediaProvider ?? null}>
+        <BlockRenderer
+          block={preview.visual}
+          blockTime={0}
+          basePath={source.basePath ?? '/'}
+          viewport={source.viewport}
+        />
+      </MediaContext.Provider>
+    </div>
+  );
+}