@marimo-team/islands 0.23.17-dev1 → 0.23.17-dev13

package/src/components/editor/actions/export-dialog/state.ts

@@ -0,0 +1,339 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { atomWithStorage } from "jotai/utils";
+import { z } from "zod";
+import type { ExportAvailabilityResponse } from "@/core/network/types";
+import { adaptForLocalStorage } from "@/utils/storage/jotai";
+
+export const EXPORT_FORMATS = [
+  "html",
+  "markdown",
+  "ipynb",
+  "pdf",
+  "script",
+  "png",
+] as const;
+
+export type ExportFormat = (typeof EXPORT_FORMATS)[number];
+export type ExportSetupRequirement =
+  ExportAvailabilityResponse["formats"][number]["missingSetup"][number];
+
+export const MARKDOWN_FLAVORS = ["pymdown", "qmd", "mystmd", "mdx"] as const;
+export const IPYNB_SORT_MODES = ["topological", "top-down"] as const;
+export const PDF_PRESETS = ["document", "slides"] as const;
+export const SCRIPT_TYPES = ["source", "flat"] as const;
+
+export type MarkdownFlavor = (typeof MARKDOWN_FLAVORS)[number];
+export type ScriptType = (typeof SCRIPT_TYPES)[number];
+
+export function isExportFormat(value: unknown): value is ExportFormat {
+  return (
+    typeof value === "string" &&
+    EXPORT_FORMATS.some((format) => format === value)
+  );
+}
+
+export interface ExportOptions {
+  html: {
+    includeCode: boolean;
+  };
+  markdown: {
+    flavor: MarkdownFlavor | null;
+  };
+  ipynb: {
+    sortMode: (typeof IPYNB_SORT_MODES)[number];
+    includeOutputs: boolean;
+  };
+  pdf: {
+    preset: (typeof PDF_PRESETS)[number];
+    includeInputs: boolean;
+    includeOutputs: boolean;
+    webpdf: boolean;
+  };
+  script: {
+    type: ScriptType;
+  };
+}
+
+export const DEFAULT_EXPORT_OPTIONS: ExportOptions = {
+  html: {
+    includeCode: true,
+  },
+  markdown: {
+    flavor: null,
+  },
+  ipynb: {
+    sortMode: "topological",
+    includeOutputs: false,
+  },
+  pdf: {
+    preset: "document",
+    includeInputs: true,
+    includeOutputs: true,
+    webpdf: true,
+  },
+  script: {
+    type: "source",
+  },
+};
+
+function storedValue<Schema extends z.ZodType>(
+  schema: Schema,
+  fallback: Exclude<z.output<Schema>, undefined>,
+) {
+  return schema.default(fallback).catch(fallback);
+}
+
+function storedGroup<Shape extends z.ZodRawShape>(shape: Shape) {
+  return z.object(shape).optional().catch(undefined);
+}
+
+const storedExportOptionsSchema = z
+  .object({
+    html: storedGroup({
+      includeCode: storedValue(
+        z.boolean(),
+        DEFAULT_EXPORT_OPTIONS.html.includeCode,
+      ),
+    }),
+    markdown: storedGroup({
+      flavor: storedValue(
+        z.enum(MARKDOWN_FLAVORS).nullable(),
+        DEFAULT_EXPORT_OPTIONS.markdown.flavor,
+      ),
+    }),
+    ipynb: storedGroup({
+      sortMode: storedValue(
+        z.enum(IPYNB_SORT_MODES),
+        DEFAULT_EXPORT_OPTIONS.ipynb.sortMode,
+      ),
+      includeOutputs: storedValue(
+        z.boolean(),
+        DEFAULT_EXPORT_OPTIONS.ipynb.includeOutputs,
+      ),
+    }),
+    pdf: storedGroup({
+      preset: storedValue(
+        z.enum(PDF_PRESETS),
+        DEFAULT_EXPORT_OPTIONS.pdf.preset,
+      ),
+      includeInputs: storedValue(
+        z.boolean(),
+        DEFAULT_EXPORT_OPTIONS.pdf.includeInputs,
+      ),
+      includeOutputs: storedValue(
+        z.boolean(),
+        DEFAULT_EXPORT_OPTIONS.pdf.includeOutputs,
+      ),
+      webpdf: storedValue(z.boolean(), DEFAULT_EXPORT_OPTIONS.pdf.webpdf),
+    }),
+    script: storedGroup({
+      type: storedValue(
+        z.enum(SCRIPT_TYPES),
+        DEFAULT_EXPORT_OPTIONS.script.type,
+      ),
+    }),
+  })
+  .catch({});
+
+export type ExportOptionOverrides = {
+  [Format in keyof ExportOptions]?: Partial<ExportOptions[Format]>;
+};
+
+export function applyExportOptionOverrides(
+  options: ExportOptions,
+  overrides: ExportOptionOverrides,
+): ExportOptions {
+  const next = { ...options };
+  const mergeFormat = <Format extends keyof ExportOptions>(format: Format) => {
+    next[format] = { ...options[format], ...overrides[format] };
+  };
+  for (const format of Object.keys(overrides) as (keyof ExportOptions)[]) {
+    mergeFormat(format);
+  }
+  return next;
+}
+
+export function mergeExportOptions(saved: unknown): ExportOptions {
+  return applyExportOptionOverrides(
+    DEFAULT_EXPORT_OPTIONS,
+    storedExportOptionsSchema.parse(saved),
+  );
+}
+
+const exportOptionsStorage = adaptForLocalStorage<ExportOptions, unknown>({
+  toSerializable: (value) => value,
+  fromSerializable: mergeExportOptions,
+});
+
+export const exportOptionsAtom = atomWithStorage<ExportOptions>(
+  "marimo:export:options:v1",
+  DEFAULT_EXPORT_OPTIONS,
+  exportOptionsStorage,
+  { getOnInit: true },
+);
+
+export const lastExportFormatAtom = atomWithStorage<ExportFormat>(
+  "marimo:export:last-format:v1",
+  "html",
+  adaptForLocalStorage<ExportFormat, unknown>({
+    toSerializable: (value) => value,
+    fromSerializable: (value) => (isExportFormat(value) ? value : "html"),
+  }),
+  { getOnInit: true },
+);
+
+export type ExportBlockReason =
+  | { type: "checking-requirements" }
+  | { type: "notebook-must-be-named" }
+  | { type: "missing-packages"; packages: string[] }
+  | { type: "missing-setup"; requirements: ExportSetupRequirement[] }
+  | { type: "wasm-runtime" };
+
+export interface ExportFormatStatus {
+  available: boolean;
+  reason?: ExportBlockReason;
+  availabilityCheckFailed?: boolean;
+}
+
+interface GetExportFormatStatusOptions {
+  format: ExportFormat;
+  options: ExportOptions;
+  runtime: "server" | "wasm";
+  filename: string | null;
+  availability:
+    | { status: "pending" }
+    | { status: "error" }
+    | { status: "success"; data: ExportAvailabilityResponse | null };
+}
+
+interface ExportFormatRequirements {
+  requiresNamedNotebookOnServer: boolean;
+  requiresServerRuntime: boolean;
+  checksServerAvailability: boolean;
+}
+
+const FORMAT_REQUIREMENTS: Record<ExportFormat, ExportFormatRequirements> = {
+  html: {
+    requiresNamedNotebookOnServer: true,
+    requiresServerRuntime: false,
+    checksServerAvailability: false,
+  },
+  markdown: {
+    requiresNamedNotebookOnServer: true,
+    requiresServerRuntime: false,
+    checksServerAvailability: false,
+  },
+  ipynb: {
+    requiresNamedNotebookOnServer: true,
+    requiresServerRuntime: true,
+    checksServerAvailability: true,
+  },
+  pdf: {
+    requiresNamedNotebookOnServer: true,
+    requiresServerRuntime: true,
+    checksServerAvailability: true,
+  },
+  script: {
+    requiresNamedNotebookOnServer: false,
+    requiresServerRuntime: false,
+    checksServerAvailability: false,
+  },
+  png: {
+    requiresNamedNotebookOnServer: false,
+    requiresServerRuntime: false,
+    checksServerAvailability: false,
+  },
+};
+
+export function isBrowserPrintExport(
+  runtime: "server" | "wasm",
+  format: ExportFormat,
+): boolean {
+  return runtime === "wasm" && format === "pdf";
+}
+
+export function getExportFormatStatus({
+  format,
+  options,
+  runtime,
+  filename,
+  availability,
+}: GetExportFormatStatusOptions): ExportFormatStatus {
+  const isNotebookSource =
+    format === "script" && options.script.type === "source";
+  const requirements = isNotebookSource
+    ? {
+        ...FORMAT_REQUIREMENTS.script,
+        requiresNamedNotebookOnServer: true,
+      }
+    : FORMAT_REQUIREMENTS[format];
+
+  const usesBrowserPrint = isBrowserPrintExport(runtime, format);
+
+  if (runtime === "wasm" && requirements.requiresServerRuntime) {
+    return {
+      available: usesBrowserPrint,
+      reason: { type: "wasm-runtime" },
+    };
+  }
+
+  if (
+    runtime === "server" &&
+    requirements.requiresNamedNotebookOnServer &&
+    !filename
+  ) {
+    return {
+      available: false,
+      reason: { type: "notebook-must-be-named" },
+    };
+  }
+
+  if (runtime === "wasm" || !requirements.checksServerAvailability) {
+    return { available: true };
+  }
+
+  if (availability.status === "pending") {
+    return {
+      available: false,
+      reason: { type: "checking-requirements" },
+    };
+  }
+
+  if (availability.status === "error" || !availability.data) {
+    return { available: true, availabilityCheckFailed: true };
+  }
+
+  const serverStatus = availability.data.formats.find(
+    (candidate) => candidate.format === format,
+  );
+  if (!serverStatus) {
+    return { available: true, availabilityCheckFailed: true };
+  }
+  if (!serverStatus.dependenciesAvailable) {
+    if (serverStatus.missingPackages.length > 0) {
+      return {
+        available: false,
+        reason: {
+          type: "missing-packages",
+          packages: serverStatus.missingPackages,
+        },
+      };
+    }
+    if (serverStatus.missingSetup.length > 0) {
+      return {
+        available: false,
+        reason: {
+          type: "missing-setup",
+          requirements: serverStatus.missingSetup,
+        },
+      };
+    }
+    return {
+      available: true,
+      availabilityCheckFailed: true,
+    };
+  }
+
+  return { available: true };
+}

package/src/components/editor/actions/export-dialog/use-export-dialog.ts

@@ -0,0 +1,372 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { useAtom } from "jotai";
+import { useEffect, useRef, useState } from "react";
+import { toast } from "@/components/ui/use-toast";
+import {
+  updateCellOutputsWithScreenshots,
+  useEnrichCellOutputs,
+} from "@/core/export/hooks";
+import { runDuringPresentMode } from "@/core/mode";
+import { useRequestClient } from "@/core/network/requests";
+import type { ExportAvailabilityResponse } from "@/core/network/types";
+import { useFilename } from "@/core/saving/filename";
+import { VirtualFileTracker } from "@/core/static/virtual-file-tracker";
+import { isWasm } from "@/core/wasm/utils";
+import { type AsyncDataResult, useAsyncData } from "@/hooks/useAsyncData";
+import {
+  ADD_PRINTING_CLASS,
+  downloadExportedFile,
+  downloadHTMLAsImage,
+  withLoadingToast,
+} from "@/utils/download";
+import { Filenames } from "@/utils/filenames";
+import { Logger } from "@/utils/Logger";
+import { Paths } from "@/utils/paths";
+import { getExportCommand } from "./export-command";
+import { exportNotebook } from "./export-notebook";
+import { FORMAT_DEFINITIONS, type UpdateExportOptions } from "./format-options";
+import {
+  EXPORT_FORMATS,
+  type ExportFormat,
+  type ExportOptions,
+  exportOptionsAtom,
+  getExportFormatStatus,
+  isBrowserPrintExport,
+  isExportFormat,
+  lastExportFormatAtom,
+} from "./state";
+
+type ExportAvailability = Parameters<
+  typeof getExportFormatStatus
+>[0]["availability"];
+
+const SCRIPT_EXPORT_COPY: Record<
+  ExportOptions["script"]["type"],
+  { actionLabel: string; progressLabel: string }
+> = {
+  source: {
+    actionLabel: "Export notebook source",
+    progressLabel: "notebook source",
+  },
+  flat: {
+    actionLabel: "Export flat script",
+    progressLabel: "flat script",
+  },
+};
+
+function getExportAvailability(
+  runtime: "server" | "wasm",
+  request: AsyncDataResult<ExportAvailabilityResponse | null>,
+): ExportAvailability {
+  if (runtime === "wasm") {
+    return { status: "success", data: null };
+  }
+
+  switch (request.status) {
+    case "pending":
+    case "loading":
+      return { status: "pending" };
+    case "error":
+      return { status: "error" };
+    case "success":
+      return { status: "success", data: request.data };
+  }
+}
+
+function getSourceFilename(
+  runtime: "server" | "wasm",
+  filename: string | null,
+): string {
+  if (runtime === "server" && filename) {
+    return Paths.basename(filename);
+  }
+  return Filenames.toPY(document.title);
+}
+
+function getFooterDescription({
+  usesBrowserPrint,
+  hasCommand,
+  format,
+  isNotebookSource,
+}: {
+  usesBrowserPrint: boolean;
+  hasCommand: boolean;
+  format: ExportFormat;
+  isNotebookSource: boolean;
+}): string | null {
+  if (usesBrowserPrint) {
+    return "Uses the browser's print settings for page size and filename.";
+  }
+  if (hasCommand) {
+    return "Uses the current session state. The copied command exports the saved notebook.";
+  }
+  if (format !== "png" && !isNotebookSource) {
+    return "Save the notebook to copy an equivalent shell command.";
+  }
+  return null;
+}
+
+function useExportDialogState(initialFormat?: ExportFormat) {
+  const filename = useFilename();
+  const [options, setOptions] = useAtom(exportOptionsAtom);
+  const [lastFormat, setLastFormat] = useAtom(lastExportFormatAtom);
+  const [format, setFormat] = useState<ExportFormat>(
+    initialFormat ?? lastFormat,
+  );
+  const runtime = isWasm() ? "wasm" : "server";
+  const requests = useRequestClient();
+
+  const availabilityRequest =
+    useAsyncData<ExportAvailabilityResponse | null>(async () => {
+      if (runtime === "wasm") {
+        return null;
+      }
+      return requests.getExportAvailability();
+    }, [runtime, requests]);
+  const availability = getExportAvailability(runtime, availabilityRequest);
+
+  const statusFor = (candidate: ExportFormat) =>
+    getExportFormatStatus({
+      format: candidate,
+      options,
+      runtime,
+      filename,
+      availability,
+    });
+  const status = statusFor(format);
+  const formats = EXPORT_FORMATS.map((candidate) => ({
+    format: candidate,
+    status: statusFor(candidate),
+  }));
+  const usesBrowserPrint = isBrowserPrintExport(runtime, format);
+  const definition = FORMAT_DEFINITIONS[format];
+  const isNotebookSource =
+    format === "script" && options.script.type === "source";
+  const { actionLabel, progressLabel } =
+    format === "script"
+      ? SCRIPT_EXPORT_COPY[options.script.type]
+      : {
+          actionLabel: definition.actionLabel,
+          progressLabel: definition.label,
+        };
+  const command = usesBrowserPrint
+    ? null
+    : getExportCommand({ format, filename, options });
+  const footerDescription = getFooterDescription({
+    usesBrowserPrint,
+    hasCommand: Boolean(command),
+    format,
+    isNotebookSource,
+  });
+
+  useEffect(() => {
+    if (initialFormat) {
+      setLastFormat(initialFormat);
+    }
+  }, [initialFormat, setLastFormat]);
+
+  const selectFormat = (value: string) => {
+    if (isExportFormat(value)) {
+      setFormat(value);
+      setLastFormat(value);
+    }
+  };
+
+  const updateOptions: UpdateExportOptions = (optionFormat, nextOptions) => {
+    setOptions((current) => {
+      const next = { ...current };
+      next[optionFormat] = {
+        ...current[optionFormat],
+        ...nextOptions,
+      };
+      return next;
+    });
+  };
+
+  return {
+    formats,
+    options,
+    selected: {
+      format,
+      status,
+      usesBrowserPrint,
+      actionLabel,
+      command,
+      footerDescription,
+    },
+    exportRequest: {
+      format,
+      options,
+      sourceFilename: getSourceFilename(runtime, filename),
+      available: status.available,
+      usesBrowserPrint,
+      progressLabel,
+    },
+    selectFormat,
+    updateOptions,
+  };
+}
+
+async function captureCurrentAppView(
+  dialogContainer: HTMLElement | null,
+): Promise<void> {
+  const app = document.getElementById("App");
+  if (!app) {
+    const message = "The current app view could not be captured.";
+    toast({
+      title: "Failed to download as PNG",
+      description: message,
+      variant: "danger",
+    });
+    throw new Error(message);
+  }
+
+  const previousVisibility = dialogContainer?.style.visibility;
+  const wasCaptureExcluded =
+    dialogContainer?.classList.contains("print:hidden");
+  const downloaded = await downloadHTMLAsImage({
+    element: app,
+    filename: document.title,
+    prepare: () => {
+      const cleanupPrinting = ADD_PRINTING_CLASS();
+      if (dialogContainer) {
+        dialogContainer.classList.add("print:hidden");
+        dialogContainer.style.visibility = "hidden";
+      }
+      return () => {
+        cleanupPrinting();
+        if (dialogContainer) {
+          if (!wasCaptureExcluded) {
+            dialogContainer.classList.remove("print:hidden");
+          }
+          dialogContainer.style.visibility = previousVisibility ?? "";
+        }
+      };
+    },
+  });
+  if (!downloaded) {
+    throw new Error("Failed to capture the current app view.");
+  }
+}
+
+function printCurrentView(onClose: () => void): void {
+  onClose();
+  requestAnimationFrame(() => {
+    setTimeout(() => {
+      window.print();
+    }, 0);
+  });
+}
+
+function useExportDialogAction({
+  format,
+  options,
+  sourceFilename,
+  available,
+  usesBrowserPrint,
+  progressLabel,
+  onClose,
+}: {
+  format: ExportFormat;
+  options: ExportOptions;
+  sourceFilename: string;
+  available: boolean;
+  usesBrowserPrint: boolean;
+  progressLabel: string;
+  onClose: () => void;
+}) {
+  const requests = useRequestClient();
+  const takeScreenshots = useEnrichCellOutputs();
+  const [isExporting, setIsExporting] = useState(false);
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const mountedRef = useRef(true);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const captureOutputs = async (
+    progress: Parameters<typeof takeScreenshots>[0]["progress"],
+  ) => {
+    await updateCellOutputsWithScreenshots({
+      takeScreenshots: () => takeScreenshots({ progress }),
+      updateCellOutputs: requests.updateCellOutputs,
+    });
+  };
+
+  const capturePNG = async () => {
+    const capture = () =>
+      captureCurrentAppView(dialogRef.current?.parentElement ?? null);
+    await runDuringPresentMode(capture);
+  };
+
+  const submit = async () => {
+    if (!available || isExporting) {
+      return;
+    }
+    if (usesBrowserPrint) {
+      printCurrentView(onClose);
+      return;
+    }
+
+    setIsExporting(true);
+    try {
+      await withLoadingToast(
+        `Exporting ${progressLabel}…`,
+        async (progress) => {
+          await exportNotebook({
+            format,
+            options,
+            requests,
+            sourceFilename,
+            htmlFiles: VirtualFileTracker.INSTANCE.filenames(),
+            captureOutputs: () => captureOutputs(progress),
+            capturePNG,
+            downloadFile: downloadExportedFile,
+          });
+        },
+      );
+      if (mountedRef.current) {
+        onClose();
+      }
+    } catch (error) {
+      // Most helpers toast actionable errors, but not all (e.g. updateCellOutputs).
+      Logger.error("Export failed", error);
+    } finally {
+      if (mountedRef.current) {
+        setIsExporting(false);
+      }
+    }
+  };
+
+  return { dialogRef, isExporting, submit };
+}
+
+export function useExportDialog({
+  initialFormat,
+  onClose,
+}: {
+  initialFormat?: ExportFormat;
+  onClose: () => void;
+}) {
+  const { exportRequest, selectFormat, ...state } =
+    useExportDialogState(initialFormat);
+  const action = useExportDialogAction({
+    ...exportRequest,
+    onClose,
+  });
+
+  return {
+    ...state,
+    ...action,
+    selectFormat: (value: string) => {
+      if (!action.isExporting) {
+        selectFormat(value);
+      }
+    },
+  };
+}