@bendyline/docblocks-react 1.1.1 → 2.0.0

package/src/Export/ExportToolbarControls.tsx

@@ -7,15 +7,21 @@
  * Must be rendered inside <EditorProvider> so useEditorContext() works.
  */
 
-import { useState, useCallback, useEffect, useRef, useMemo } from 'react';
+import {
+  lazy,
+  Suspense,
+  useState,
+  useCallback,
+  useEffect,
+  useRef,
+  useMemo,
+  type ComponentType,
+} from 'react';
 import { useEditorContext } from '@bendyline/squisq-editor-react';
 import { getThemeSummaries } from '@bendyline/squisq/schemas';
-import { getTransformStyleSummaries } from '@bendyline/squisq/transform';
 import { parseMarkdown } from '@bendyline/squisq/markdown';
-import { markdownToDoc } from '@bendyline/squisq/doc';
-import { VideoExportModal } from '@bendyline/squisq-video-react';
-import { PLAYER_BUNDLE } from '@bendyline/squisq-react/standalone-source';
 import type { ContentContainer } from '@bendyline/squisq/storage';
+import type { VideoExportModalProps } from '@bendyline/squisq-video-react';
 import type { ExportOptions } from './export-options.js';
 import {
   DEFAULT_OPTIONS,
@@ -23,18 +29,80 @@ import {
   loadLastExportOptions,
   saveExportOptions,
 } from './export-options.js';
-import { ExportDialog } from './ExportDialog.js';
-import { runExport } from './run-export.js';
+import type { ExportBlobSaver } from './run-export.js';
+import { loadTransformStyleSummaries, type ExportSummaryOption } from './transform-summaries.js';
+
+const ExportDialog = lazy(() =>
+  import('./ExportDialog.js').then((module) => ({ default: module.ExportDialog })),
+);
+
+let runExportModulePromise: Promise<typeof import('./run-export.js')> | null = null;
+
+function loadRunExportModule(): Promise<typeof import('./run-export.js')> {
+  runExportModulePromise ??= import('./run-export.js');
+  return runExportModulePromise;
+}
 
 export interface ExportToolbarControlsProps {
   /** Currently selected file path — used to derive the download filename. */
   selectedFile: string | null;
   /** Media container for resolving images during export. */
   mediaContainer?: ContentContainer | null;
+  /** Override the default browser download behavior for host-provided save flows. */
+  saveBlob?: ExportBlobSaver;
+  /** Optional host adapter for displaying, picking, and saving to a native target path. */
+  destinationAdapter?: ExportDestinationAdapter;
+  /** Render the trigger as a direct Export button instead of the overflow menu. */
+  trigger?: 'menu' | 'button';
+  /** Whether to show video export in the overflow menu. */
+  showVideoExport?: boolean;
+}
+
+/** Host-specific operations behind the shared export destination control. */
+export interface ExportDestinationTarget {
+  grantId: string | null;
+  displayPath: string;
+}
+
+export interface ExportDestinationAdapter {
+  resolveTarget: (filename: string) => Promise<ExportDestinationTarget>;
+  pickTarget: (
+    filename: string,
+    currentTarget?: ExportDestinationTarget | null,
+  ) => Promise<ExportDestinationTarget | null>;
+  saveBlob: (
+    blob: Blob,
+    filename: string,
+    target?: ExportDestinationTarget | null,
+  ) => Promise<ExportDestinationTarget | null>;
+  hint?: string;
+}
+
+type ParsedMarkdown = ReturnType<typeof parseMarkdown>;
+
+interface VideoExportModules {
+  Modal: ComponentType<VideoExportModalProps>;
+  markdownToDoc: (doc: ParsedMarkdown) => VideoExportModalProps['doc'];
+  playerScript: string;
+}
+
+let videoExportModulesPromise: Promise<VideoExportModules> | null = null;
+
+function loadVideoExportModules(): Promise<VideoExportModules> {
+  videoExportModulesPromise ??= Promise.all([
+    import('@bendyline/squisq/doc'),
+    import('@bendyline/squisq-video-react'),
+    import('@bendyline/squisq-react/standalone-source'),
+  ]).then(([docModule, videoModule, playerModule]) => ({
+    Modal: videoModule.VideoExportModal,
+    markdownToDoc: docModule.markdownToDoc,
+    playerScript: playerModule.PLAYER_BUNDLE,
+  }));
+  return videoExportModulesPromise;
 }
 
 /** Build the quick-export label from saved options. */
-function quickLabel(opts: ExportOptions): string {
+function quickLabel(opts: ExportOptions, transformSummaries: ExportSummaryOption[]): string {
   const baseExt = FORMAT_EXTENSIONS[opts.format].toUpperCase().replace('.', '');
   // Recursive HTML always emits a ZIP (multi-doc tree), regardless of
   // the saved `htmlBundle` value. Applies to both plain and rendered
@@ -58,7 +126,7 @@ function quickLabel(opts: ExportOptions): string {
     if (theme) parts.push(theme.name);
   }
   if (opts.format === 'pptx' && opts.transformStyle) {
-    const transform = getTransformStyleSummaries().find((t) => t.id === opts.transformStyle);
+    const transform = transformSummaries.find((t) => t.id === opts.transformStyle);
     if (transform) parts.push(transform.name);
   }
 
@@ -71,12 +139,23 @@ function quickLabel(opts: ExportOptions): string {
 export function ExportToolbarControls({
   selectedFile,
   mediaContainer,
+  saveBlob,
+  destinationAdapter,
+  trigger = 'menu',
+  showVideoExport = true,
 }: ExportToolbarControlsProps) {
   const { markdownSource, markdownDoc } = useEditorContext();
   const [menuOpen, setMenuOpen] = useState(false);
   const [dialogOpen, setDialogOpen] = useState(false);
   const [videoModalOpen, setVideoModalOpen] = useState(false);
+  const [videoLoading, setVideoLoading] = useState(false);
+  const [videoLoadError, setVideoLoadError] = useState<string | null>(null);
+  const [videoModules, setVideoModules] = useState<VideoExportModules | null>(null);
+  const [videoDoc, setVideoDoc] = useState<VideoExportModalProps['doc'] | null>(null);
+  const [transformSummaries, setTransformSummaries] = useState<ExportSummaryOption[]>([]);
   const [exporting, setExporting] = useState(false);
+  const [destinationTarget, setDestinationTarget] = useState<ExportDestinationTarget | null>(null);
+  const destinationRequestRef = useRef(0);
   const menuRef = useRef<HTMLDivElement>(null);
 
   const lastOptions = loadLastExportOptions();
@@ -108,13 +187,6 @@ export function ExportToolbarControls({
     return docThemeId ? { ...base, themeId: docThemeId } : base;
   }, [lastOptions, docThemeId]);
 
-  /** Build a Doc from the current markdown for video export. */
-  const doc = useMemo(() => {
-    if (!videoModalOpen) return null;
-    const mdDoc = parseMarkdown(markdownSource);
-    return markdownToDoc(mdDoc);
-  }, [videoModalOpen, markdownSource]);
-
   // Close menu on outside click
   useEffect(() => {
     if (!menuOpen) return;
@@ -127,39 +199,150 @@ export function ExportToolbarControls({
     return () => document.removeEventListener('pointerdown', onPointerDown);
   }, [menuOpen]);
 
+  useEffect(() => {
+    if (
+      !menuOpen ||
+      lastOptions?.format !== 'pptx' ||
+      !lastOptions.transformStyle ||
+      transformSummaries.length > 0
+    ) {
+      return;
+    }
+
+    let cancelled = false;
+    loadTransformStyleSummaries()
+      .then((nextSummaries) => {
+        if (!cancelled) setTransformSummaries(nextSummaries);
+      })
+      .catch(() => {
+        if (!cancelled) setTransformSummaries([]);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [lastOptions?.format, lastOptions?.transformStyle, menuOpen, transformSummaries.length]);
+
   const handleToggleMenu = useCallback(() => {
     setMenuOpen((prev) => !prev);
   }, []);
 
+  const refreshDestination = useCallback(
+    async (options: ExportOptions) => {
+      if (!destinationAdapter) return;
+
+      const requestId = destinationRequestRef.current + 1;
+      destinationRequestRef.current = requestId;
+
+      try {
+        const { buildExportFilename } = await loadRunExportModule();
+        const filename = buildExportFilename(selectedFile, options);
+        const target = await destinationAdapter.resolveTarget(filename);
+        if (destinationRequestRef.current === requestId) setDestinationTarget(target);
+      } catch {
+        if (destinationRequestRef.current === requestId) setDestinationTarget(null);
+      }
+    },
+    [destinationAdapter, selectedFile],
+  );
+
   const handleOpenDialog = useCallback(() => {
     setMenuOpen(false);
     setDialogOpen(true);
-  }, []);
+    void refreshDestination(dialogInitial);
+  }, [dialogInitial, refreshDestination]);
 
   const handleCloseDialog = useCallback(() => {
     setDialogOpen(false);
   }, []);
 
-  const handleOpenVideoModal = useCallback(() => {
+  const handleOpenVideoModal = useCallback(async () => {
     setMenuOpen(false);
     setVideoModalOpen(true);
-  }, []);
+    setVideoLoading(true);
+    setVideoLoadError(null);
+
+    try {
+      const modules = videoModules ?? (await loadVideoExportModules());
+      setVideoModules(modules);
+      setVideoDoc(modules.markdownToDoc(parseMarkdown(markdownSource)));
+    } catch {
+      setVideoLoadError('Video export could not be loaded.');
+    } finally {
+      setVideoLoading(false);
+    }
+  }, [markdownSource, videoModules]);
 
   const handleCloseVideoModal = useCallback(() => {
     setVideoModalOpen(false);
+    setVideoDoc(null);
+    setVideoLoadError(null);
   }, []);
 
+  const handleOptionsChange = useCallback(
+    (options: ExportOptions) => {
+      void refreshDestination(options);
+    },
+    [refreshDestination],
+  );
+
+  const handlePickDestination = useCallback(
+    async (options: ExportOptions) => {
+      if (!destinationAdapter) return;
+      try {
+        const { buildExportFilename } = await loadRunExportModule();
+        const filename = buildExportFilename(selectedFile, options);
+        const pickedTarget = await destinationAdapter.pickTarget(filename, destinationTarget);
+        if (pickedTarget === null) return;
+        setDestinationTarget(pickedTarget);
+      } catch {
+        // Native hosts surface picker failures through their own UI channel.
+      }
+    },
+    [destinationAdapter, destinationTarget, selectedFile],
+  );
+
+  const saveToDestination = useCallback(
+    async (blob: Blob, filename: string, target: ExportDestinationTarget | null) => {
+      if (!destinationAdapter) return;
+      const savedTarget = await destinationAdapter.saveBlob(blob, filename, target);
+      if (savedTarget) setDestinationTarget(savedTarget);
+    },
+    [destinationAdapter],
+  );
+
+  const handleDestinationSaveBlob = useCallback(
+    async (blob: Blob, filename: string) => {
+      await saveToDestination(blob, filename, destinationTarget);
+    },
+    [destinationTarget, saveToDestination],
+  );
+
   const handleExport = useCallback(
     async (opts: ExportOptions) => {
       setExporting(true);
       try {
-        await runExport(markdownSource, selectedFile, opts, mediaContainer);
+        const { runExport } = await loadRunExportModule();
+        await runExport(
+          markdownSource,
+          selectedFile,
+          opts,
+          mediaContainer,
+          destinationAdapter ? handleDestinationSaveBlob : saveBlob,
+        );
       } finally {
         setExporting(false);
         setDialogOpen(false);
       }
     },
-    [markdownSource, selectedFile, mediaContainer],
+    [
+      markdownSource,
+      selectedFile,
+      mediaContainer,
+      destinationAdapter,
+      handleDestinationSaveBlob,
+      saveBlob,
+    ],
   );
 
   const handleQuickExport = useCallback(async () => {
@@ -168,58 +351,161 @@ export function ExportToolbarControls({
     setExporting(true);
     try {
       saveExportOptions(lastOptions);
-      await runExport(markdownSource, selectedFile, lastOptions, mediaContainer);
+      const { runExport } = await loadRunExportModule();
+      let quickTarget: ExportDestinationTarget | null = null;
+      if (destinationAdapter) {
+        const { buildExportFilename } = await loadRunExportModule();
+        quickTarget = await destinationAdapter.resolveTarget(
+          buildExportFilename(selectedFile, lastOptions),
+        );
+      }
+      await runExport(
+        markdownSource,
+        selectedFile,
+        lastOptions,
+        mediaContainer,
+        destinationAdapter
+          ? async (blob, filename) => saveToDestination(blob, filename, quickTarget)
+          : saveBlob,
+      );
     } finally {
       setExporting(false);
     }
-  }, [lastOptions, markdownSource, selectedFile, mediaContainer]);
+  }, [
+    destinationAdapter,
+    lastOptions,
+    markdownSource,
+    mediaContainer,
+    saveBlob,
+    saveToDestination,
+    selectedFile,
+  ]);
+
+  const LoadedVideoExportModal = videoModules?.Modal;
 
   return (
     <>
-      <div className="db-toolbar-menu" ref={menuRef}>
+      {trigger === 'button' ? (
         <button
-          className="db-toolbar-menu-trigger"
-          onClick={handleToggleMenu}
-          aria-label="More actions"
-          title="More actions"
+          type="button"
+          className="squisq-toolbar-button db-toolbar-export-trigger"
+          onClick={handleOpenDialog}
+          disabled={exporting}
+          aria-label="Export document"
+          data-tooltip={exporting ? 'Exporting...' : 'Export document'}
         >
-          &middot;&middot;&middot;
+          <ExportGlyph />
         </button>
+      ) : (
+        <div className="db-toolbar-menu" ref={menuRef}>
+          <button
+            className="db-toolbar-menu-trigger"
+            onClick={handleToggleMenu}
+            aria-label="More actions"
+            title="More actions"
+          >
+            &middot;&middot;&middot;
+          </button>
 
-        {menuOpen && (
-          <div className="db-toolbar-menu-dropdown">
-            {lastOptions && (
-              <button
-                className="db-toolbar-menu-item"
-                onClick={handleQuickExport}
-                disabled={exporting}
-              >
-                {quickLabel(lastOptions)}
+          {menuOpen && (
+            <div className="db-toolbar-menu-dropdown">
+              {lastOptions && (
+                <button
+                  className="db-toolbar-menu-item"
+                  onClick={handleQuickExport}
+                  disabled={exporting}
+                >
+                  {quickLabel(lastOptions, transformSummaries)}
+                </button>
+              )}
+              <button className="db-toolbar-menu-item" onClick={handleOpenDialog}>
+                Export...
               </button>
-            )}
-            <button className="db-toolbar-menu-item" onClick={handleOpenDialog}>
-              Export...
-            </button>
-            <div className="db-toolbar-menu-divider" />
-            <button className="db-toolbar-menu-item" onClick={handleOpenVideoModal}>
-              Export Video...
-            </button>
-          </div>
-        )}
-      </div>
+              {showVideoExport && (
+                <>
+                  <div className="db-toolbar-menu-divider" />
+                  <button className="db-toolbar-menu-item" onClick={handleOpenVideoModal}>
+                    Export Video...
+                  </button>
+                </>
+              )}
+            </div>
+          )}
+        </div>
+      )}
 
       {dialogOpen && (
-        <ExportDialog
-          initial={dialogInitial}
-          exporting={exporting}
-          onExport={handleExport}
-          onClose={handleCloseDialog}
-        />
+        <Suspense fallback={null}>
+          <ExportDialog
+            initial={dialogInitial}
+            exporting={exporting}
+            destination={
+              destinationAdapter
+                ? {
+                    value: destinationTarget?.displayPath ?? '',
+                    onPick: handlePickDestination,
+                    hint: destinationAdapter.hint,
+                  }
+                : undefined
+            }
+            onExport={handleExport}
+            onOptionsChange={destinationAdapter ? handleOptionsChange : undefined}
+            onClose={handleCloseDialog}
+          />
+        </Suspense>
       )}
 
-      {videoModalOpen && doc && (
-        <VideoExportModal doc={doc} playerScript={PLAYER_BUNDLE} onClose={handleCloseVideoModal} />
+      {videoModalOpen && (videoLoading || videoLoadError) && (
+        <div className="db-dialog-overlay">
+          <div className="db-dialog">
+            <div className="db-dialog-header">
+              <h2 className="db-dialog-title">Export Video</h2>
+              <button
+                className="db-dialog-close"
+                onClick={handleCloseVideoModal}
+                aria-label="Close"
+              >
+                &times;
+              </button>
+            </div>
+            <div className="db-dialog-body">
+              <p className="db-export-hint">{videoLoadError ?? 'Loading...'}</p>
+            </div>
+          </div>
+        </div>
       )}
+
+      {videoModalOpen &&
+        videoModules &&
+        LoadedVideoExportModal &&
+        videoDoc &&
+        !videoLoading &&
+        !videoLoadError && (
+          <LoadedVideoExportModal
+            doc={videoDoc}
+            playerScript={videoModules.playerScript}
+            onClose={handleCloseVideoModal}
+          />
+        )}
     </>
   );
 }
+
+function ExportGlyph() {
+  return (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M4.5 1.75h4.25L12 5v7.25a1.5 1.5 0 0 1-1.5 1.5h-6A1.5 1.5 0 0 1 3 12.25v-9a1.5 1.5 0 0 1 1.5-1.5z" />
+      <path d="M8.75 1.75V5h3.25" />
+      <path d="M6 8.75h4.5" />
+      <path d="M8.75 7 10.5 8.75 8.75 10.5" />
+    </svg>
+  );
+}

package/src/Export/export-destination.ts

@@ -0,0 +1,30 @@
+/** Keep a user-edited target name while switching the selected export format. */
+export function updateExportTargetExtension(targetPath: string, suggestedFilename: string): string {
+  const nextExtension = extensionOf(suggestedFilename);
+  if (!nextExtension) return targetPath;
+  if (!targetPath.trim()) return suggestedFilename;
+
+  const suffixIndex = firstSuffixIndex(targetPath);
+  const pathPart = suffixIndex === -1 ? targetPath : targetPath.slice(0, suffixIndex);
+  const suffix = suffixIndex === -1 ? '' : targetPath.slice(suffixIndex);
+  const separatorIndex = Math.max(pathPart.lastIndexOf('/'), pathPart.lastIndexOf('\\'));
+  const dotIndex = pathPart.lastIndexOf('.');
+  const stem = dotIndex > separatorIndex ? pathPart.slice(0, dotIndex) : pathPart;
+  return `${stem}${nextExtension}${suffix}`;
+}
+
+function extensionOf(value: string): string {
+  const suffixIndex = firstSuffixIndex(value);
+  const pathPart = suffixIndex === -1 ? value : value.slice(0, suffixIndex);
+  const separatorIndex = Math.max(pathPart.lastIndexOf('/'), pathPart.lastIndexOf('\\'));
+  const dotIndex = pathPart.lastIndexOf('.');
+  return dotIndex > separatorIndex ? pathPart.slice(dotIndex) : '';
+}
+
+function firstSuffixIndex(value: string): number {
+  const query = value.indexOf('?');
+  const fragment = value.indexOf('#');
+  if (query === -1) return fragment;
+  if (fragment === -1) return query;
+  return Math.min(query, fragment);
+}

package/src/Export/index.ts

@@ -1,5 +1,19 @@
-export { ExportToolbarControls } from './ExportToolbarControls.js';
-export type { ExportToolbarControlsProps } from './ExportToolbarControls.js';
+export { ExportToolbarControls } from './DeferredExportToolbarControls.js';
+export type {
+  ExportDestinationAdapter,
+  ExportDestinationTarget,
+  ExportToolbarControlsProps,
+} from './DeferredExportToolbarControls.js';
 export { ExportDialog } from './ExportDialog.js';
-export type { ExportDialogProps } from './ExportDialog.js';
-export type { ExportFormat, ExportOptions } from './export-options.js';
+export type { ExportDestinationControl, ExportDialogProps } from './ExportDialog.js';
+export {
+  DEFAULT_OPTIONS,
+  FORMAT_EXTENSIONS,
+  FORMAT_LABELS,
+  loadLastExportOptions,
+  saveExportOptions,
+} from './export-options.js';
+export type { ExportFormat, ExportOptions, HtmlBundle, HtmlStyle } from './export-options.js';
+export { buildExportFilename, runExport } from './run-export.js';
+export { updateExportTargetExtension } from './export-destination.js';
+export type { ExportBlobSaver } from './run-export.js';

package/src/Export/public-api.ts

@@ -0,0 +1,17 @@
+/**
+ * Narrow public export pipeline for hosts that provide their own editor shell.
+ * Keep toolbar/video controls out of this entry so consumers such as the VS
+ * Code webview do not eagerly transform the video worker graph.
+ */
+export { ExportDialog } from './ExportDialog.js';
+export type { ExportDestinationControl, ExportDialogProps } from './ExportDialog.js';
+export {
+  DEFAULT_OPTIONS,
+  FORMAT_EXTENSIONS,
+  FORMAT_LABELS,
+  loadLastExportOptions,
+  saveExportOptions,
+} from './export-options.js';
+export type { ExportFormat, ExportOptions, HtmlBundle, HtmlStyle } from './export-options.js';
+export { buildExportFilename, runExport } from './run-export.js';
+export type { ExportBlobSaver } from './run-export.js';