@ai-matrx/rich-content 0.2.4 → 0.2.7

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.2.7
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/rich-content/v0.2.6..npm/rich-content/v0.2.7 -- apps/shared/rich-content`).
+No source changes intended and no consumer action required.
+
+## 0.2.6
+
+The Mermaid runtime scheduling test now supplies Mermaid and ELK through the
+documented rich-content host loaders. This keeps the test aligned with the
+portable package contract: Mermaid remains a host-owned optional dependency,
+rather than a direct package dependency.
+
+### Consumer action
+
+None. Hosts must continue registering `loadMermaid` (and optionally
+`loadMermaidElk`) through `configureRichContent` when they render diagrams.
+
+## 0.2.5
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/rich-content/v0.2.4..npm/rich-content/v0.2.5 -- apps/shared/rich-content`).
+No source changes intended and no consumer action required.
+
 ## 0.2.4
 
 `display/blocks/csv/CsvBlock`: Copy goes through `@ai-matrx/kit/clipboard` `useClipboard` with toast notices (carries matrx-frontend ALC-19 `b980571731`, which landed on the app copy as the app switched to this package).
@@ -82,3 +106,4 @@ held-back streaming text; the heal tests encode 1.3.1's behavior).
 
 - matrx-frontend: call `configureRichContent` at the root (see README) and import from
   `@ai-matrx/rich-content/<domain>/<module>`.
+

package/dist/code-block/CodeBlock.d.ts

@@ -0,0 +1,44 @@
+import React from "react";
+import { type CodeBlockMenuItem } from "./CodeBlockHeader.js";
+interface CodeBlockProps {
+    code: string;
+    language: string;
+    fontSize?: number;
+    showLineNumbers?: boolean;
+    wrapLines?: boolean;
+    className?: string;
+    onCodeChange?: (newCode: string) => void;
+    inline?: boolean;
+    isStreamActive?: boolean;
+    allowEdit?: boolean;
+    customBuiltinKeys?: string[];
+    /**
+     * Optional node rendered between the language display and the right-side
+     * action row. Used by language-specialized wrappers (e.g. `JsonBlock`) to
+     * add view-mode toggles without forking this component.
+     */
+    headerLeftSlot?: React.ReactNode;
+    /**
+     * Extra items appended to the kebab menu. Use `category` on each item to
+     * place it in an existing section (View · Edit · Download · Save · AI) or
+     * introduce a new one (e.g. "Data" for tabular JSON actions).
+     */
+    extraMenuItems?: CodeBlockMenuItem[];
+    /**
+     * The code fence's info string after the language (`title="app.tsx" {1,3-5}
+     * showLineNumbers`) — see components/markdown-core/fence-meta.ts. Sets the
+     * header title, highlighted lines and line numbering.
+     */
+    meta?: string;
+    /**
+     * A deliberate source view (code editors, diff views, artifact and canvas
+     * source, a JSON card that already decided): kind JSON is shown as code.
+     * Default false — a settled json / jsonc / json5 / unlabelled block whose
+     * content is kind JSON is drawn as its kind (`KindDataGate`) and the caller
+     * is reported (Arman, 2026-09-30: a kind is never drawn as raw JSON).
+     */
+    showSource?: boolean;
+}
+export type { CodeBlockProps };
+declare const CodeBlock: React.FC<CodeBlockProps>;
+export default CodeBlock;

package/dist/code-block/CodeBlock.js

@@ -0,0 +1,449 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useClipboard } from "@ai-matrx/kit/clipboard";
+import { useRef, useState, useEffect } from "react";
+import { KindDataGate } from "../host/app-bindings.js";
+import {
+  isKindJsonText,
+  valueCarriesKind
+} from "@ai-matrx/content-ir/surfaces";
+import { extractErrorMessage } from "../utils/lifted/errors.js";
+import { cn } from "@ai-matrx/design-system";
+import SmallCodeEditor from "./SmallCodeEditor.js";
+import CodeBlockHeader from "./CodeBlockHeader.js";
+import { useThemeMode } from "../host/app-bindings.js";
+import StickyButtons from "./StickyButtons.js";
+import { useIsMobile } from "@ai-matrx/kit/media-query";
+import { hostHtmlPageService, useHostUser } from "../host/app-bindings.js";
+import { isCompleteHtmlDocument } from "../utils/lifted/html-document.js";
+import { codeLanguageToExtension } from "../utils/lifted/code-language-extension.js";
+import { Globe, Loader2 } from "lucide-react";
+import { useCanvas } from "../host/app-bindings.js";
+import { toast } from "../host/toast.js";
+import { ShikiCodeView } from "./highlight/ShikiCodeView.js";
+import { parseFenceMeta } from "@ai-matrx/content-ir/source";
+import { agentForPromptKey } from "../utils/lifted/code-editor-agents.js";
+import { useOpenSmartCodeEditorWindow } from "../host/app-bindings.js";
+import {
+  normalizeViewLanguage,
+  mapLanguageForMonaco,
+  getMonacoFileExtension
+} from "../utils/lifted/languages.js";
+const JSON_LANGUAGES = /* @__PURE__ */ new Set(["", "json", "jsonc", "json5"]);
+function settledKindValue(props) {
+  if (props.showSource || props.isStreamActive || props.inline) return void 0;
+  if (!JSON_LANGUAGES.has((props.language ?? "").trim().toLowerCase())) return void 0;
+  if (!isKindJsonText(props.code)) return void 0;
+  try {
+    const value = JSON.parse(props.code);
+    return valueCarriesKind(value) ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+const CodeBlock = (props) => {
+  const kindValue = settledKindValue(props);
+  const quoted = !JSON_LANGUAGES.has((props.language ?? "").trim().toLowerCase()) || props.showSource === true && !props.isStreamActive;
+  return /* @__PURE__ */ jsx(KindDataGate, { component: "CodeBlock", data: kindValue, children: quoted ? /* @__PURE__ */ jsx("div", { "data-kind-source": "explicit", className: "contents", children: /* @__PURE__ */ jsx(CodeBlockBody, { ...props }) }) : /* @__PURE__ */ jsx(CodeBlockBody, { ...props }) });
+};
+const CodeBlockBody = ({
+  code: initialCode,
+  language: rawLanguage = "text",
+  fontSize = 12,
+  showLineNumbers = false,
+  wrapLines = true,
+  className,
+  onCodeChange,
+  inline = false,
+  isStreamActive = false,
+  allowEdit = true,
+  customBuiltinKeys = [],
+  headerLeftSlot,
+  extraMenuItems,
+  meta
+}) => {
+  const { copyText } = useClipboard({
+    notify: (message, kind) => kind === "error" ? toast.error(message) : toast.success(message)
+  });
+  const fence = parseFenceMeta(meta);
+  const viewLanguage = normalizeViewLanguage(rawLanguage);
+  const monacoLanguage = mapLanguageForMonaco(rawLanguage);
+  const monacoFileExtension = getMonacoFileExtension(rawLanguage);
+  const [editedCode, setEditedCode] = useState(null);
+  const [previousInitialCode, setPreviousInitialCode] = useState(initialCode);
+  if (previousInitialCode !== initialCode) {
+    setPreviousInitialCode(initialCode);
+    setEditedCode(initialCode);
+  }
+  const [isCopied, setIsCopied] = useState(false);
+  const [isFullScreen, setIsFullScreen] = useState(false);
+  const [isCollapsed, setIsCollapsed] = useState(false);
+  const [isEditing, setIsEditing] = useState(false);
+  const requestedLineNumbers = showLineNumbers || fence.showLineNumbers === true;
+  const [lineNumbers, setLineNumbers] = useState(requestedLineNumbers);
+  const [previousRequestedLineNumbers, setPreviousRequestedLineNumbers] = useState(requestedLineNumbers);
+  if (previousRequestedLineNumbers !== requestedLineNumbers) {
+    setPreviousRequestedLineNumbers(requestedLineNumbers);
+    setLineNumbers(requestedLineNumbers);
+  }
+  const [showWrapLines, setShowWrapLines] = useState(wrapLines);
+  const [minimapEnabled, setMinimapEnabled] = useState(false);
+  const [isTopInView, setIsTopInView] = useState(false);
+  const [isBottomInView, setIsBottomInView] = useState(false);
+  const [isCreatingPage, setIsCreatingPage] = useState(false);
+  const [formatTrigger, setFormatTrigger] = useState(0);
+  const openSmartCodeEditorWindow = useOpenSmartCodeEditorWindow();
+  const bottomRef = useRef(null);
+  const topRef = useRef(null);
+  const containerRef = useRef(null);
+  const editorRef = useRef(null);
+  const showStickyButtons = isBottomInView && !isTopInView && !isEditing;
+  const mode = useThemeMode();
+  const isMobile = useIsMobile();
+  const user = useHostUser();
+  const { open: openCanvas } = useCanvas();
+  const code = editedCode ?? initialCode;
+  const isCompleteHTMLDocument = (htmlCode) => viewLanguage === "html" && isCompleteHtmlDocument(htmlCode);
+  const handleViewHTML = async () => {
+    if (!user?.id) {
+      toast.error("You must be logged in to view HTML pages");
+      return;
+    }
+    setIsCreatingPage(true);
+    try {
+      const result = await hostHtmlPageService().createPage(
+        code,
+        "HTML Preview",
+        "Generated from code block",
+        user.id
+      );
+      openCanvas({
+        type: "iframe",
+        data: result.url,
+        metadata: {
+          title: "HTML Preview",
+          htmlPageId: result.pageId
+        }
+      });
+    } catch (error) {
+      console.error("Failed to create HTML page:", error);
+      toast.error(`Failed to create HTML page: ${extractErrorMessage(error)}`);
+    } finally {
+      setIsCreatingPage(false);
+    }
+  };
+  useEffect(() => {
+    const observerOptions = {
+      root: null,
+      rootMargin: "0px",
+      threshold: 0
+    };
+    const topObserver = new IntersectionObserver(
+      ([entry]) => setIsTopInView(entry.isIntersecting),
+      observerOptions
+    );
+    const bottomObserver = new IntersectionObserver(
+      ([entry]) => setIsBottomInView(entry.isIntersecting),
+      observerOptions
+    );
+    if (topRef.current) topObserver.observe(topRef.current);
+    if (bottomRef.current) bottomObserver.observe(bottomRef.current);
+    return () => {
+      if (topRef.current) topObserver.unobserve(topRef.current);
+      if (bottomRef.current) bottomObserver.unobserve(bottomRef.current);
+      topObserver.disconnect();
+      bottomObserver.disconnect();
+    };
+  }, [isFullScreen]);
+  useEffect(() => {
+    if (isFullScreen) {
+      document.body.style.overflow = "hidden";
+    } else {
+      document.body.style.overflow = "auto";
+    }
+    return () => {
+      document.body.style.overflow = "auto";
+    };
+  }, [isFullScreen]);
+  const handleCopy = async (e, withLineNumbers = false) => {
+    e.stopPropagation();
+    let textToCopy = code;
+    if (withLineNumbers) {
+      const lines = code.split("\n");
+      const firstLine = fence.startLine ?? 1;
+      const width = String(firstLine + lines.length - 1).length;
+      const paddedLines = lines.map((line, index) => {
+        const lineNumber = (firstLine + index).toString().padStart(width, " ");
+        return `${lineNumber} | ${line}`;
+      });
+      textToCopy = paddedLines.join("\n");
+    }
+    await copyText(textToCopy);
+    setIsCopied(true);
+    setTimeout(() => setIsCopied(false), 2e3);
+  };
+  const handleDownload = (e) => {
+    e.stopPropagation();
+    const blob = new Blob([code], { type: "text/plain" });
+    const url = window.URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    const titleFile = fence.title && /^[\w./-]+\.\w+$/.test(fence.title) ? fence.title.split("/").pop() : void 0;
+    const ext = codeLanguageToExtension(rawLanguage || "txt");
+    a.download = titleFile ?? `code${ext}`;
+    a.click();
+    window.URL.revokeObjectURL(url);
+  };
+  const toggleLineNumbers = (e) => {
+    e.stopPropagation();
+    setLineNumbers((prev) => !prev);
+  };
+  const toggleWrapLines = (e) => {
+    e.stopPropagation();
+    setShowWrapLines((prev) => !prev);
+  };
+  const toggleFullScreen = (e) => {
+    e.stopPropagation();
+    if (isFullScreen) {
+      document.body.style.overflow = "auto";
+      setTimeout(() => {
+        setIsFullScreen(false);
+        setIsCollapsed(false);
+      }, 150);
+    } else {
+      document.body.style.overflow = "hidden";
+      setIsFullScreen(true);
+      if (isCollapsed) setIsCollapsed(false);
+    }
+  };
+  const toggleCollapse = (e) => {
+    if (e) e.stopPropagation();
+    if (isEditing) return;
+    setIsCollapsed((prev) => !prev);
+    if (isFullScreen) setIsFullScreen(false);
+  };
+  const toggleEdit = (e) => {
+    e.stopPropagation();
+    setIsEditing(!isEditing);
+    if (!isEditing) {
+      setIsCollapsed(false);
+    }
+  };
+  const handleCodeChange = (newCode) => {
+    if (newCode) {
+      setEditedCode(newCode);
+      onCodeChange?.(newCode);
+    }
+  };
+  const handleFormat = (e) => {
+    e.stopPropagation();
+    if (!isEditing) return;
+    setFormatTrigger((prev) => prev + 1);
+  };
+  const handleReset = (e) => {
+    e.stopPropagation();
+    if (!isEditing) return;
+    setEditedCode(initialCode);
+    onCodeChange?.(initialCode);
+  };
+  const toggleMinimap = (e) => {
+    e.stopPropagation();
+    setMinimapEnabled((prev) => !prev);
+  };
+  const handleOpenAIModal = (config) => {
+    const agent = agentForPromptKey(config.mandateKey);
+    openSmartCodeEditorWindow({
+      agents: [agent],
+      defaultPickerMandateKey: agent.mandateKey,
+      initialCode: editedCode ?? initialCode ?? "",
+      language: monacoLanguage,
+      title: config.title,
+      onCodeChange: (event) => {
+        setEditedCode(event.code);
+        onCodeChange?.(event.code);
+      }
+    });
+  };
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    isFullScreen && /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "fixed inset-0 z-[9998] bg-black/50 backdrop-blur-sm",
+        onClick: (e) => {
+          e.stopPropagation();
+          document.body.style.overflow = "auto";
+          setTimeout(() => {
+            setIsFullScreen(false);
+            setIsCollapsed(false);
+          }, 150);
+        }
+      }
+    ),
+    /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref: containerRef,
+        className: cn(
+          "w-full my-4 rounded-t-xl rounded-b-lg border border-neutral-200 dark:border-neutral-700",
+          // `overflow-clip` (NOT `overflow-hidden`) so this box still clips to
+          // its rounded corners without becoming a scroll container — an
+          // overflow-hidden ancestor would trap StickyButtons' `position:
+          // sticky` and disable it (D153).
+          !isFullScreen && "overflow-clip",
+          isFullScreen && "fixed w-[95vw] h-[90dvh] z-[9999] bg-textured flex flex-col shadow-2xl rounded-xl overflow-hidden",
+          className
+        ),
+        style: isFullScreen ? {
+          top: "50%",
+          left: "50%",
+          transform: "translate(-50%, -50%)"
+        } : void 0,
+        children: [
+          /* @__PURE__ */ jsx(
+            CodeBlockHeader,
+            {
+              language: rawLanguage,
+              title: fence.title,
+              linesCount: code.split("\n").length,
+              isEditing,
+              isFullScreen,
+              isCollapsed,
+              code,
+              handleCopy,
+              handleDownload,
+              toggleEdit,
+              toggleFullScreen,
+              toggleCollapse,
+              toggleLineNumbers,
+              toggleWrapLines,
+              isCopied,
+              isMobile,
+              isCompleteHTML: isCompleteHTMLDocument(code),
+              handleViewHTML,
+              isCreatingPage,
+              showWrapLines,
+              handleFormat,
+              handleReset,
+              minimapEnabled,
+              toggleMinimap,
+              showLineNumbers: lineNumbers,
+              onAIEdit: handleOpenAIModal,
+              allowEdit,
+              customBuiltinKeys,
+              headerLeftSlot,
+              extraMenuItems
+            }
+          ),
+          showStickyButtons && /* @__PURE__ */ jsx(
+            StickyButtons,
+            {
+              linesCount: code.split("\n").length,
+              isCollapsed,
+              isCopied,
+              handleCopy,
+              toggleCollapse
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: cn("relative", isFullScreen && "flex-1 overflow-hidden"),
+              children: isEditing ? /* @__PURE__ */ jsx("div", { className: "w-full", children: /* @__PURE__ */ jsx(
+                SmallCodeEditor,
+                {
+                  language: monacoLanguage,
+                  fileExtension: monacoFileExtension,
+                  initialCode: code,
+                  onChange: handleCodeChange,
+                  mode,
+                  height: isFullScreen ? "calc(100dvh - 15rem)" : `${Math.max(400, code.split("\n").length * 20 + 100)}px`,
+                  showCopyButton: false,
+                  showFormatButton: false,
+                  showResetButton: false,
+                  showWordWrapToggle: false,
+                  showMinimapToggle: false,
+                  formatTrigger,
+                  controlledWordWrap: showWrapLines ? "on" : "off",
+                  controlledMinimap: minimapEnabled
+                }
+              ) }) : (
+                // Code View
+                /* @__PURE__ */ jsxs("div", { className: cn("relative", isFullScreen && "h-full"), children: [
+                  /* @__PURE__ */ jsx("div", { ref: topRef, style: { height: "1px" } }),
+                  /* @__PURE__ */ jsxs(
+                    "div",
+                    {
+                      ref: bottomRef,
+                      className: cn(
+                        "transition-all duration-300 ease-in-out relative",
+                        isCollapsed ? "max-h-[150px]" : "max-h-none",
+                        isFullScreen ? "h-full overflow-auto" : "overflow-hidden",
+                        showWrapLines && "overflow-x-hidden"
+                      ),
+                      children: [
+                        /* @__PURE__ */ jsx(
+                          ShikiCodeView,
+                          {
+                            code,
+                            language: rawLanguage,
+                            mode: mode === "dark" ? "dark" : "light",
+                            showLineNumbers: lineNumbers,
+                            startLine: fence.startLine,
+                            wrapLines: showWrapLines,
+                            fontSize,
+                            highlightLines: fence.highlightLines
+                          }
+                        ),
+                        isCompleteHTMLDocument(code) && !isCollapsed && /* @__PURE__ */ jsx(
+                          "button",
+                          {
+                            onClick: handleViewHTML,
+                            disabled: isCreatingPage,
+                            className: cn(
+                              "absolute bottom-4 right-4 z-20",
+                              "flex items-center gap-2 px-4 py-2 rounded-full",
+                              "bg-purple-600 hover:bg-purple-700 dark:bg-purple-700 dark:hover:bg-purple-600",
+                              "text-white text-sm font-medium",
+                              "shadow-lg hover:shadow-xl",
+                              "transition-all duration-200 ease-in-out",
+                              "transform hover:scale-105",
+                              isCreatingPage && "opacity-50 cursor-not-allowed"
+                            ),
+                            title: "Open HTML Preview in Canvas",
+                            children: isCreatingPage ? /* @__PURE__ */ jsxs(Fragment, { children: [
+                              /* @__PURE__ */ jsx(Loader2, { className: "w-4 h-4 animate-spin" }),
+                              /* @__PURE__ */ jsx("span", { children: "Creating..." })
+                            ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+                              /* @__PURE__ */ jsx(Globe, { className: "w-4 h-4" }),
+                              /* @__PURE__ */ jsx("span", { children: "Preview" })
+                            ] })
+                          }
+                        )
+                      ]
+                    }
+                  ),
+                  isCollapsed && /* @__PURE__ */ jsx(
+                    "div",
+                    {
+                      className: "absolute bottom-0 left-0 right-0 h-24 bg-gradient-to-t from-background to-transparent opacity-80 cursor-pointer",
+                      onClick: toggleCollapse,
+                      children: /* @__PURE__ */ jsxs("div", { className: "absolute bottom-2 left-1/2 transform -translate-x-1/2 text-muted-foreground text-sm", children: [
+                        "Click to expand ",
+                        code.split("\n").length - 3,
+                        " more lines"
+                      ] })
+                    }
+                  )
+                ] })
+              )
+            }
+          )
+        ]
+      }
+    )
+  ] });
+};
+var CodeBlock_default = CodeBlock;
+export {
+  CodeBlock_default as default
+};

package/dist/code-block/CodeBlockHeader.d.ts

@@ -0,0 +1,63 @@
+import type { MandateKey } from "@ai-matrx/agents/mandates";
+import React from "react";
+import { type MenuItem } from "../host/app-bindings.js";
+type AIModalConfig = {
+    /** The editing job (mandate key) — the DB decides which agent runs it. */
+    mandateKey: MandateKey;
+    title: string;
+};
+/**
+ * Items that wrappers (e.g. `JsonBlock`) can append to the unified kebab menu.
+ * Use `category` to slot the item into one of the existing buckets — common
+ * choices: `"Data"`, `"Download"`, `"Save"`, `"AI"`, `"View"`. Any new category
+ * appears as its own section in the menu in the order it was first declared.
+ */
+export type CodeBlockMenuItem = MenuItem;
+interface CodeBlockHeaderProps {
+    language: string;
+    /** Filename or caption from the fence (`title="app.tsx"`, ```ts:app.tsx). */
+    title?: string;
+    linesCount: number;
+    isEditing: boolean;
+    isFullScreen: boolean;
+    isCollapsed: boolean;
+    code: string;
+    handleCopy: (e: React.MouseEvent, withLineNumbers?: boolean) => void;
+    handleDownload: (e: React.MouseEvent) => void;
+    toggleEdit?: (e: React.MouseEvent) => void;
+    toggleFullScreen?: (e: React.MouseEvent) => void;
+    toggleCollapse?: (e?: React.MouseEvent) => void;
+    toggleLineNumbers?: (e: React.MouseEvent) => void;
+    toggleWrapLines?: (e: React.MouseEvent) => void;
+    isCopied: boolean;
+    isMobile: boolean;
+    isCompleteHTML?: boolean;
+    handleViewHTML?: () => void;
+    isCreatingPage?: boolean;
+    showWrapLines?: boolean;
+    handleFormat?: (e: React.MouseEvent) => void;
+    handleReset?: (e: React.MouseEvent) => void;
+    minimapEnabled?: boolean;
+    toggleMinimap?: (e: React.MouseEvent) => void;
+    showLineNumbers?: boolean;
+    onAIEdit?: (config: AIModalConfig) => void;
+    hideLanguageDisplay?: boolean;
+    allowEdit?: boolean;
+    customBuiltinKeys?: string[];
+    /** Rendered after the language display. Used by wrappers to inject
+     *  view-mode toggles (e.g. JsonBlock's Code/Tree/Table/Path switcher). */
+    headerLeftSlot?: React.ReactNode;
+    /**
+     * Extra items appended to the kebab menu. Use `category` to control
+     * grouping inside the menu (the four section buckets the header already
+     * declares are: View · Edit · Download · Save · AI). New categories
+     * (e.g. "Data" from JsonBlock) appear as their own section.
+     */
+    extraMenuItems?: CodeBlockMenuItem[];
+}
+export declare const CodeBlockHeader: React.FC<CodeBlockHeaderProps>;
+export declare const EditButton: ({ isEditing, toggleEdit, }: {
+    isEditing: boolean;
+    toggleEdit?: (e: React.MouseEvent) => void;
+}) => React.JSX.Element | null;
+export default CodeBlockHeader;