@bendyline/docblocks-react 2.6.1 → 2.7.0

package/dist/chunk-OINKNX26.js

@@ -0,0 +1,574 @@
+import {
+  AI_DIAGRAM_DESCRIPTION_CHARACTERS,
+  DIAGRAM_KINDS,
+  DIAGRAM_KIND_LABELS,
+  clip,
+  documentTitle,
+  idsIn,
+  inferKind,
+  locatePassage,
+  planInsertions,
+  promptBudget,
+  realizeDiagram,
+  specSummaryForAvoid,
+  startIllustrationRun
+} from "./chunk-5OZBGIIT.js";
+import {
+  unavailableSentence,
+  useAiStatus
+} from "./chunk-K4I3NJFL.js";
+import {
+  Dialog
+} from "./chunk-56KO2LYN.js";
+
+// src/Ai/AiDiagrams.tsx
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import {
+  headingDepthForInsertion,
+  useEditorContext,
+  usePreviewSettingsOptional,
+  validateMermaidSource
+} from "@bendyline/squisq-editor-react";
+import { LinearDocView } from "@bendyline/squisq-react/page";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var LINKED_KINDS = /* @__PURE__ */ new Set(["flow", "sequence", "hierarchy"]);
+function contextWindowOf(status) {
+  return status?.kind === "ready" ? status.model?.contextWindow ?? null : null;
+}
+function DiagramPreview({ compiled }) {
+  const preview = usePreviewSettingsOptional();
+  const markdown = useMemo(() => compiled.render(2, /* @__PURE__ */ new Set()), [compiled]);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: "db-ai-diagram-preview",
+      role: "img",
+      "aria-label": `${compiled.title}. ${compiled.summary}`,
+      children: /* @__PURE__ */ jsx(
+        LinearDocView,
+        {
+          markdown,
+          showCover: false,
+          thinMargins: true,
+          theme: preview?.activeTheme
+        }
+      )
+    }
+  );
+}
+function DiagramSource({ compiled }) {
+  const markdown = useMemo(() => compiled.render(2, /* @__PURE__ */ new Set()), [compiled]);
+  return /* @__PURE__ */ jsx("pre", { className: "db-ai-diagram-source", children: markdown });
+}
+function placementNote(compiled) {
+  return compiled.placement === "sectionEnd" ? "Goes at the end of this section." : null;
+}
+function AiDiagramDialog({
+  ai,
+  documentSource,
+  capturedSelection,
+  getSelection,
+  insertBlockAfterCursor,
+  onClose
+}) {
+  const status = useAiStatus(ai);
+  const material = capturedSelection.text.trim();
+  const [description, setDescription] = useState("");
+  const [kindChoice, setKindChoice] = useState("auto");
+  const [running, setRunning] = useState(false);
+  const [outcome, setOutcome] = useState(null);
+  const [error, setError] = useState(null);
+  const [showSource, setShowSource] = useState(false);
+  const promptRef = useRef(null);
+  const controllerRef = useRef(null);
+  const requestRef = useRef(0);
+  useEffect(
+    () => () => {
+      requestRef.current += 1;
+      controllerRef.current?.abort();
+    },
+    []
+  );
+  const autoKind = inferKind(description, material);
+  const kind = kindChoice === "auto" ? autoKind : kindChoice;
+  const ready = outcome?.status === "ready" ? outcome : null;
+  const generate = useCallback(async () => {
+    const request = description.trim();
+    if (!request && !material) {
+      setError("Describe the diagram you want, or select the text to draw it from.");
+      promptRef.current?.focus();
+      return;
+    }
+    controllerRef.current?.abort();
+    const controller = new AbortController();
+    controllerRef.current = controller;
+    const requestId = ++requestRef.current;
+    const avoid = ready ? specSummaryForAvoid(ready.compiled) : void 0;
+    setRunning(true);
+    setError(null);
+    const result = await realizeDiagram({
+      ai,
+      kind,
+      material: material || request,
+      heading: "",
+      title: request ? clip(request.charAt(0).toUpperCase() + request.slice(1), 60) : "",
+      description: request || void 0,
+      avoid,
+      // With selected text, the diagram must stick to it. Without, the person
+      // asked the model to supply the content.
+      ground: material.length > 0,
+      budget: promptBudget(contextWindowOf(status)),
+      validateMermaid: validateMermaidSource,
+      signal: controller.signal
+    });
+    if (requestRef.current !== requestId) return;
+    setRunning(false);
+    if (result.status === "cancelled") return;
+    if (result.status === "failed") {
+      setError(result.message);
+      return;
+    }
+    setOutcome(result);
+  }, [ai, description, kind, material, ready, status]);
+  const stop = useCallback(() => controllerRef.current?.abort(), []);
+  const insert = useCallback(() => {
+    if (!ready) return;
+    const current = getSelection();
+    if (!current || current.view !== capturedSelection.view) {
+      setError("Return to the original editor view and try again.");
+      return;
+    }
+    const { compiled } = ready;
+    const taken = idsIn(documentSource);
+    let noDepth = false;
+    const inserted = insertBlockAfterCursor(
+      (context) => {
+        if (compiled.placement === "afterBlock") return compiled.render(2, taken);
+        const depth = headingDepthForInsertion(context, { childLevels: 1 });
+        if (depth === null) noDepth = true;
+        return depth === null ? null : compiled.render(depth, taken);
+      },
+      { placement: compiled.placement }
+    );
+    if (!inserted) {
+      setError(
+        noDepth ? "This diagram cannot go at the end of this section. Move the cursor to another section and try again." : "DocBlocks could not insert the diagram in the current editor view."
+      );
+      return;
+    }
+    onClose();
+  }, [
+    capturedSelection.view,
+    documentSource,
+    getSelection,
+    insertBlockAfterCursor,
+    onClose,
+    ready
+  ]);
+  const dialog = /* @__PURE__ */ jsxs(
+    Dialog,
+    {
+      title: "Insert diagram with AI",
+      onClose,
+      size: "wide",
+      closeOnBackdrop: !running,
+      initialFocusRef: promptRef,
+      className: "db-ai-draft-dialog db-ai-diagram-dialog",
+      footer: /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx("button", { type: "button", onClick: onClose, children: "Cancel" }),
+        running ? /* @__PURE__ */ jsx("button", { type: "button", className: "db-ai-secondary-action", onClick: stop, children: "Stop" }) : /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            className: "db-ai-secondary-action",
+            onClick: () => void generate(),
+            children: ready ? "Regenerate" : "Generate"
+          }
+        ),
+        /* @__PURE__ */ jsx("button", { type: "button", disabled: !ready || running, onClick: insert, children: "Insert" })
+      ] }),
+      children: [
+        /* @__PURE__ */ jsxs("label", { className: "db-ai-field", children: [
+          /* @__PURE__ */ jsx("span", { children: "What should the diagram show?" }),
+          /* @__PURE__ */ jsx(
+            "textarea",
+            {
+              ref: promptRef,
+              value: description,
+              maxLength: AI_DIAGRAM_DESCRIPTION_CHARACTERS,
+              rows: 3,
+              placeholder: material ? "Optional. For example: Show the approval steps as a flowchart." : "For example: How a pull request is reviewed and merged.",
+              onChange: (event) => setDescription(event.currentTarget.value)
+            }
+          )
+        ] }),
+        /* @__PURE__ */ jsxs("label", { className: "db-ai-field db-ai-field--inline", children: [
+          /* @__PURE__ */ jsx("span", { children: "Kind" }),
+          /* @__PURE__ */ jsxs(
+            "select",
+            {
+              value: kindChoice,
+              onChange: (event) => setKindChoice(event.currentTarget.value),
+              children: [
+                /* @__PURE__ */ jsxs("option", { value: "auto", children: [
+                  "Auto (",
+                  DIAGRAM_KIND_LABELS[autoKind],
+                  ")"
+                ] }),
+                DIAGRAM_KINDS.map((option) => /* @__PURE__ */ jsx("option", { value: option, children: DIAGRAM_KIND_LABELS[option] }, option))
+              ]
+            }
+          )
+        ] }),
+        material && /* @__PURE__ */ jsxs("div", { className: "db-ai-selection-preview", children: [
+          /* @__PURE__ */ jsx("span", { children: "Drawing from the selected text" }),
+          /* @__PURE__ */ jsx("blockquote", { children: clip(material, 600) })
+        ] }),
+        running && /* @__PURE__ */ jsxs("p", { className: "db-ai-progress", role: "status", children: [
+          /* @__PURE__ */ jsx("span", { className: "db-ai-spinner", "aria-hidden": "true" }),
+          " Drawing\u2026"
+        ] }),
+        ready && !running && /* @__PURE__ */ jsxs("div", { className: "db-ai-diagram-result", children: [
+          /* @__PURE__ */ jsx(DiagramPreview, { compiled: ready.compiled }),
+          ready.notes.map((note) => /* @__PURE__ */ jsx("p", { className: "db-ai-note", children: note }, note)),
+          placementNote(ready.compiled) && /* @__PURE__ */ jsx("p", { className: "db-ai-note", children: placementNote(ready.compiled) }),
+          LINKED_KINDS.has(ready.compiled.kind) && /* @__PURE__ */ jsx("p", { className: "db-ai-note", children: "Check the links between boxes before inserting." }),
+          /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              className: "db-ai-link-button",
+              "aria-expanded": showSource,
+              onClick: () => setShowSource((open) => !open),
+              children: showSource ? "Hide source" : "Show source"
+            }
+          ),
+          showSource && /* @__PURE__ */ jsx(DiagramSource, { compiled: ready.compiled })
+        ] }),
+        status && !(status.kind === "ready" && status.model) && /* @__PURE__ */ jsx("p", { className: "db-ai-note", children: unavailableSentence(status) }),
+        error && /* @__PURE__ */ jsx("p", { className: "db-ai-error", role: "alert", children: error }),
+        /* @__PURE__ */ jsx("p", { className: "db-ai-disclaimer", children: "Review AI-generated diagrams before adding them." })
+      ]
+    }
+  );
+  return typeof document === "undefined" ? dialog : createPortal(dialog, document.body);
+}
+function AiIllustratePanel({ ai, onClose }) {
+  const { markdownSource, applySourceEdits } = useEditorContext();
+  const status = useAiStatus(ai);
+  const contextWindow = contextWindowOf(status);
+  const ready = status?.kind === "ready" && status.model !== null;
+  const [phase, setPhase] = useState("idle");
+  const [progress, setProgress] = useState(null);
+  const [suggestions, setSuggestions] = useState([]);
+  const [error, setError] = useState(null);
+  const [notice, setNotice] = useState(null);
+  const [regenerating, setRegenerating] = useState(null);
+  const [sourceOpen, setSourceOpen] = useState(() => /* @__PURE__ */ new Set());
+  const [kindChoice, setKindChoice] = useState({});
+  const runRef = useRef(null);
+  const regenerateRef = useRef(null);
+  const generationRef = useRef(0);
+  const startedRef = useRef(false);
+  const update = useCallback((key, change) => {
+    setSuggestions((current) => current.map((item) => item.key === key ? change(item) : item));
+  }, []);
+  const start = useCallback(() => {
+    runRef.current?.cancel();
+    regenerateRef.current?.abort();
+    const generation = ++generationRef.current;
+    setSuggestions([]);
+    setError(null);
+    setNotice(null);
+    setProgress(null);
+    setPhase("planning");
+    runRef.current = startIllustrationRun({
+      ai,
+      source: markdownSource,
+      title: documentTitle(markdownSource),
+      budget: promptBudget(contextWindow),
+      validateMermaid: validateMermaidSource,
+      onEvent: (event) => {
+        if (generationRef.current !== generation) return;
+        switch (event.type) {
+          case "planning":
+            setPhase("planning");
+            break;
+          case "planned":
+            setSuggestions(
+              event.picks.map((pick) => ({
+                key: pick.passage.id,
+                pick,
+                state: "waiting",
+                outcome: null,
+                inserted: false,
+                dismissed: false,
+                problem: null
+              }))
+            );
+            break;
+          case "drawing":
+            setPhase("drawing");
+            setProgress({ index: event.index, total: event.total });
+            setSuggestions(
+              (current) => current.map(
+                (item, index) => index === event.index ? { ...item, state: "drawing" } : item
+              )
+            );
+            break;
+          case "suggestion":
+            update(event.pick.passage.id, (item) => ({
+              ...item,
+              state: "done",
+              outcome: event.outcome
+            }));
+            break;
+          case "error":
+            setError(event.message);
+            setPhase("error");
+            break;
+          case "done":
+            runRef.current = null;
+            setProgress(null);
+            setPhase((current) => current === "error" ? current : "done");
+            setSuggestions(
+              (current) => current.map((item) => item.state === "done" ? item : { ...item, state: "done" })
+            );
+            break;
+        }
+      }
+    });
+  }, [ai, contextWindow, markdownSource, update]);
+  const stop = useCallback(() => {
+    runRef.current?.cancel();
+    regenerateRef.current?.abort();
+  }, []);
+  useEffect(() => {
+    if (startedRef.current || !ready) return;
+    startedRef.current = true;
+    start();
+  }, [ready, start]);
+  useEffect(
+    () => () => {
+      generationRef.current += 1;
+      runRef.current?.cancel();
+      regenerateRef.current?.abort();
+      startedRef.current = false;
+    },
+    []
+  );
+  const insert = useCallback(
+    (items) => {
+      const pending = [];
+      for (const item of items) {
+        if (item.inserted || item.dismissed || item.outcome?.status !== "ready") continue;
+        pending.push({
+          key: item.key,
+          passage: item.pick.passage,
+          compiled: item.outcome.compiled
+        });
+      }
+      if (pending.length === 0) return;
+      const plan = planInsertions(markdownSource, pending);
+      const stale = new Set(plan.stale);
+      const unplaceable = new Set(plan.unplaceable);
+      if (plan.edits.length > 0 && !applySourceEdits(plan.edits, { baseSource: markdownSource })) {
+        setNotice("Switch to Write or Source view, in the Document layout, to insert diagrams.");
+        return;
+      }
+      setNotice(null);
+      setSuggestions(
+        (current) => current.map((item) => {
+          if (!pending.some((entry) => entry.key === item.key)) return item;
+          if (stale.has(item.key)) {
+            return {
+              ...item,
+              problem: "This passage changed. Regenerate the diagram or dismiss it."
+            };
+          }
+          if (unplaceable.has(item.key)) {
+            return {
+              ...item,
+              problem: "No heading level fits at the end of this section without capturing the text after it."
+            };
+          }
+          return { ...item, inserted: true, problem: null };
+        })
+      );
+    },
+    [applySourceEdits, markdownSource]
+  );
+  const regenerate = useCallback(
+    async (item) => {
+      if (runRef.current || regenerating) return;
+      const kind = kindChoice[item.key] ?? item.pick.kind;
+      const controller = new AbortController();
+      regenerateRef.current = controller;
+      const generation = generationRef.current;
+      setRegenerating(item.key);
+      update(item.key, (current) => ({ ...current, state: "drawing", problem: null }));
+      const outcome = await realizeDiagram({
+        ai,
+        kind,
+        material: item.pick.passage.plain,
+        heading: item.pick.passage.heading,
+        title: item.pick.title,
+        avoid: item.outcome?.status === "ready" && kind === item.pick.kind ? specSummaryForAvoid(item.outcome.compiled) : void 0,
+        ground: true,
+        budget: promptBudget(contextWindow),
+        validateMermaid: validateMermaidSource,
+        signal: controller.signal
+      });
+      if (generationRef.current !== generation) return;
+      setRegenerating(null);
+      regenerateRef.current = null;
+      update(
+        item.key,
+        (current) => outcome.status === "cancelled" ? { ...current, state: "done" } : { ...current, state: "done", outcome, pick: { ...current.pick, kind } }
+      );
+    },
+    [ai, contextWindow, kindChoice, regenerating, update]
+  );
+  const busy = phase === "planning" || phase === "drawing" || regenerating !== null;
+  const visible = suggestions.filter((item) => !item.dismissed);
+  const insertable = visible.filter(
+    (item) => !item.inserted && item.outcome?.status === "ready" && locatePassage(markdownSource, item.pick.passage) !== null
+  );
+  return /* @__PURE__ */ jsxs("aside", { className: "db-ai-review-panel db-ai-illustrate-panel", "aria-label": "AI illustrations", children: [
+    /* @__PURE__ */ jsxs("div", { className: "db-ai-review-header", children: [
+      /* @__PURE__ */ jsxs("div", { children: [
+        /* @__PURE__ */ jsx("h2", { children: "AI illustrations" }),
+        phase === "done" && /* @__PURE__ */ jsxs("span", { className: "db-ai-review-count", children: [
+          visible.length,
+          " ",
+          visible.length === 1 ? "suggestion" : "suggestions"
+        ] })
+      ] }),
+      /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          className: "db-ai-review-close",
+          onClick: onClose,
+          "aria-label": "Close AI illustrations",
+          children: "\xD7"
+        }
+      )
+    ] }),
+    /* @__PURE__ */ jsx("div", { className: "db-ai-review-actions", children: busy ? /* @__PURE__ */ jsx("button", { type: "button", onClick: stop, children: "Stop" }) : /* @__PURE__ */ jsx("button", { type: "button", disabled: !ready, onClick: start, children: phase === "idle" ? "Suggest diagrams" : "Suggest again" }) }),
+    !ready && status && /* @__PURE__ */ jsx("div", { className: "db-ai-review-empty", role: "status", children: unavailableSentence(status) }),
+    (phase === "planning" || phase === "drawing") && /* @__PURE__ */ jsxs("div", { className: "db-ai-review-empty", role: "status", children: [
+      /* @__PURE__ */ jsx("span", { className: "db-ai-spinner", "aria-hidden": "true" }),
+      " ",
+      phase === "planning" || !progress ? "Reading the document\u2026" : `Drawing diagram ${String(progress.index + 1)} of ${String(progress.total)}\u2026`
+    ] }),
+    phase === "error" && error && /* @__PURE__ */ jsx("div", { className: "db-ai-review-empty db-ai-error", role: "alert", children: error }),
+    notice && /* @__PURE__ */ jsx("div", { className: "db-ai-review-stale", role: "status", children: notice }),
+    phase === "done" && visible.length === 0 && /* @__PURE__ */ jsx("div", { className: "db-ai-review-empty", children: suggestions.length === 0 ? "No passage here would be clearer as a diagram." : "All suggestions have been handled." }),
+    /* @__PURE__ */ jsx("ol", { className: "db-ai-review-list", children: visible.map((item) => {
+      const outcome = item.outcome;
+      const compiled = outcome?.status === "ready" ? outcome.compiled : null;
+      const kind = item.pick.kind;
+      const passageMoved = locatePassage(markdownSource, item.pick.passage) === null;
+      return /* @__PURE__ */ jsxs("li", { className: "db-ai-review-finding db-ai-illustrate-card", children: [
+        /* @__PURE__ */ jsxs("div", { className: "db-ai-review-finding-meta", children: [
+          /* @__PURE__ */ jsx("span", { className: "db-ai-review-severity db-ai-illustrate-kind", children: DIAGRAM_KIND_LABELS[kind] }),
+          item.pick.passage.heading && /* @__PURE__ */ jsx("span", { children: clip(item.pick.passage.heading, 48) })
+        ] }),
+        /* @__PURE__ */ jsx("h3", { children: compiled?.title || item.pick.title || DIAGRAM_KIND_LABELS[kind] }),
+        item.pick.why && /* @__PURE__ */ jsx("p", { children: item.pick.why }),
+        /* @__PURE__ */ jsxs("div", { className: "db-ai-review-excerpt", children: [
+          /* @__PURE__ */ jsx("span", { children: "After" }),
+          /* @__PURE__ */ jsx("blockquote", { children: clip(item.pick.passage.plain, 180) })
+        ] }),
+        item.state === "waiting" && /* @__PURE__ */ jsx("p", { className: "db-ai-note", children: "Waiting\u2026" }),
+        item.state === "drawing" && /* @__PURE__ */ jsxs("p", { className: "db-ai-progress", role: "status", children: [
+          /* @__PURE__ */ jsx("span", { className: "db-ai-spinner", "aria-hidden": "true" }),
+          " Drawing\u2026"
+        ] }),
+        item.inserted && /* @__PURE__ */ jsx("p", { className: "db-ai-note", children: "Inserted." }),
+        item.state === "done" && compiled && !item.inserted && /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx(DiagramPreview, { compiled }),
+          placementNote(compiled) && /* @__PURE__ */ jsx("p", { className: "db-ai-note", children: placementNote(compiled) }),
+          LINKED_KINDS.has(compiled.kind) && /* @__PURE__ */ jsx("p", { className: "db-ai-note", children: "Check the links between boxes before inserting." }),
+          sourceOpen.has(item.key) && /* @__PURE__ */ jsx(DiagramSource, { compiled })
+        ] }),
+        item.state === "done" && outcome?.status === "failed" && /* @__PURE__ */ jsx("p", { className: "db-ai-error", role: "alert", children: outcome.message }),
+        passageMoved && !item.inserted && /* @__PURE__ */ jsx("p", { className: "db-ai-error", role: "alert", children: "This passage changed. Regenerate the diagram or dismiss it." }),
+        item.problem && !passageMoved && /* @__PURE__ */ jsx("p", { className: "db-ai-error", role: "alert", children: item.problem }),
+        !item.inserted && item.state === "done" && /* @__PURE__ */ jsxs("div", { className: "db-ai-review-finding-actions db-ai-illustrate-actions", children: [
+          /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              onClick: () => setSuggestions(
+                (current) => current.map(
+                  (entry) => entry.key === item.key ? { ...entry, dismissed: true } : entry
+                )
+              ),
+              children: "Dismiss"
+            }
+          ),
+          compiled && /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              "aria-expanded": sourceOpen.has(item.key),
+              onClick: () => setSourceOpen((current) => {
+                const next = new Set(current);
+                if (next.has(item.key)) next.delete(item.key);
+                else next.add(item.key);
+                return next;
+              }),
+              children: sourceOpen.has(item.key) ? "Hide source" : "Source"
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "select",
+            {
+              "aria-label": "Diagram kind",
+              value: kindChoice[item.key] ?? kind,
+              disabled: busy || passageMoved,
+              onChange: (event) => {
+                const value = event.currentTarget.value;
+                setKindChoice((current) => ({ ...current, [item.key]: value }));
+              },
+              children: DIAGRAM_KINDS.map((option) => /* @__PURE__ */ jsx("option", { value: option, children: DIAGRAM_KIND_LABELS[option] }, option))
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              disabled: busy || passageMoved,
+              onClick: () => void regenerate(item),
+              children: "Regenerate"
+            }
+          ),
+          compiled && /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              disabled: busy || passageMoved,
+              onClick: () => insert([item]),
+              children: "Insert"
+            }
+          )
+        ] })
+      ] }, item.key);
+    }) }),
+    insertable.length > 1 && !busy && /* @__PURE__ */ jsx("div", { className: "db-ai-review-actions db-ai-illustrate-footer", children: /* @__PURE__ */ jsxs("button", { type: "button", onClick: () => insert(insertable), children: [
+      "Insert all (",
+      insertable.length,
+      ")"
+    ] }) }),
+    /* @__PURE__ */ jsx("p", { className: "db-ai-review-disclaimer", children: "AI diagrams can be wrong. Check each one before inserting it." })
+  ] });
+}
+
+export {
+  DiagramPreview,
+  AiDiagramDialog,
+  AiIllustratePanel
+};