@djangocfg/widget-diagram 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Reforms.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @djangocfg/widget-diagram
+
+Mermaid diagrams, both halves: typed builders that WRITE the source, and a
+full-parser renderer that DRAWS it. Supports the diagram types covered by the builders (`FlowDiagram`,
+`SequenceDiagram`, `JourneyDiagram`) plus anything else Mermaid parses (gantt,
+class, state, ER, pie, mindmap, …) via the `chart` prop. Click-to-fullscreen
+via the floating toolbar.
+
+## Install
+
+```bash
+pnpm add @djangocfg/widget-diagram @djangocfg/ui-core
+```
+
+## Which renderer
+
+`@djangocfg/widget-media/diagram` is the OTHER one, and it is not a duplicate.
+
+| | `widget-diagram` | `widget-media/diagram` |
+|---|---|---|
+| Parser | `mermaid`, ~84 MB unpacked | `beautiful-mermaid`, ~2 MB |
+| Covers | everything mermaid parses | flowchart, sequence, state, class, ER — source otherwise |
+| For | a surface whose job IS the diagram | a chat transcript, where most messages have none |
+
+Do not import both into one app.
+
+## Builders without a renderer
+
+```ts
+import { FlowDiagram } from '@djangocfg/widget-diagram/builders';
+```
+
+The `./builders` subpath holds no static edge to the parser, so a server pass,
+a test or a CLI can write diagram source without resolving a renderer.
+`src/entries.test.ts` walks the graph and holds that.
+
+## Verify
+
+```bash
+pnpm --filter @djangocfg/widget-diagram check-types test
+```
+
+```tsx
+import Mermaid from '@djangocfg/widget-diagram';
+
+<Mermaid chart={`
+flowchart LR
+  A[Client] --> B[API] --> C[(DB)]
+`} />
+```
+
+Builder API:
+
+```tsx
+import Mermaid, { FlowDiagram } from '@djangocfg/widget-diagram';
+
+const chart = new FlowDiagram({ direction: 'LR' })
+  .node('a', 'Client')
+  .node('b', 'API')
+  .edge('a', 'b')
+  .build();
+
+<Mermaid chart={chart} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `chart` | `string` | — | Mermaid source. |
+| `isCompact` | `boolean` | `false` | Tighter padding for embedded contexts. |
+| `fullscreen` | `boolean` | `true` | Click-to-fullscreen via the floating toolbar. |
+| `scrollIsolation` | `boolean` | `false` | Lock page wheel while hovering. Off by default — Mermaid SVGs don't scroll, the overlay just steals wheel events. |
+| `debounceMs` | `number` | `300` | Re-render debounce after `chart` changes. Lower for static diagrams, higher while streaming. |
+| `className` | `string` | — | — |
+
+## Notes
+
+- **~800KB bundle** — entry point is already `lazy()`-wrapped with a `Suspense` spinner, so the cost is only paid when a diagram is actually mounted.
+- Theming pulls from `useThemePalette` / `useStylePresets` / `useBoxColors` (exported alongside the builders) — Mermaid colors follow the active app theme; do not hard-code hex.
+
+---
+
+Adapted from jalcoui (MIT).

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@djangocfg/widget-diagram",
+  "version": "0.1.1",
+  "description": "Mermaid diagrams: typed builders that write the source, and a full-parser renderer that draws it",
+  "keywords": [
+    "mermaid",
+    "diagram",
+    "flowchart",
+    "sequence-diagram",
+    "builder",
+    "typescript"
+  ],
+  "author": {
+    "name": "DjangoCFG",
+    "url": "https://djangocfg.com"
+  },
+  "homepage": "https://djangocfg.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markolofsen/django-cfg.git",
+    "directory": "widgets/diagram"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.tsx",
+  "types": "./src/index.tsx",
+  "exports": {
+    ".": {
+      "types": "./src/index.tsx",
+      "default": "./src/index.tsx"
+    },
+    "./builders": {
+      "types": "./src/builders/index.ts",
+      "default": "./src/builders/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "@djangocfg/ui-core": "^2.1.542",
+    "lucide-react": "^0.545.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@djangocfg/typescript-config": "^2.1.542",
+    "@djangocfg/ui-core": "^2.1.542",
+    "@storybook/react-vite": "^10.5.0",
+    "@types/node": "^25.9.5",
+    "@types/react": "19.2.15",
+    "@types/react-dom": "19.2.3",
+    "lucide-react": "0.545.0",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "storybook": "^10.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@djangocfg/widget-kit": "^0.1.1",
+    "mermaid": "^11.16.0",
+    "react-zoom-pan-pinch": "^3.7.0"
+  }
+}

package/src/FloatingToolbar/FloatingToolbar.css

@@ -0,0 +1,5 @@
+/* Focus ring when scroll isolation is unlocked */
+.scroll-unlocked {
+  box-shadow: 0 0 0 2px var(--ring);
+  transition: box-shadow 150ms;
+}

package/src/FloatingToolbar/actions/CopyAction.tsx

@@ -0,0 +1,31 @@
+'use client';
+
+import React from 'react';
+import {
+  CopyButton,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
+
+interface CopyActionProps {
+  value: string;
+  title?: string;
+}
+
+const BUTTON_CLASS = 'h-6 w-6 rounded-sm bg-muted/80 hover:bg-muted border border-border/50 backdrop-blur-sm';
+
+export const CopyAction: React.FC<CopyActionProps> = ({ value, title = 'Copy' }) => (
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <CopyButton
+        value={value}
+        variant="ghost"
+        size="icon"
+        className={BUTTON_CLASS}
+        iconClassName="h-3 w-3"
+      />
+    </TooltipTrigger>
+    <TooltipContent side="top">{title}</TooltipContent>
+  </Tooltip>
+);

package/src/FloatingToolbar/actions/DownloadAction.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import { Download } from 'lucide-react';
+import React from 'react';
+
+import { Button, Tooltip, TooltipContent, TooltipTrigger } from '@djangocfg/ui-core/components';
+
+interface DownloadActionProps {
+  value: string;
+  filename?: string;
+  mimeType?: string;
+  title?: string;
+}
+
+const BUTTON_CLASS = 'h-6 w-6 rounded-sm bg-muted/80 hover:bg-muted border border-border/50 backdrop-blur-sm';
+
+export const DownloadAction: React.FC<DownloadActionProps> = ({
+  value,
+  filename = 'download.txt',
+  mimeType = 'text/plain',
+  title = 'Download',
+}) => {
+  const handleDownload = () => {
+    const blob = new Blob([value], { type: mimeType });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+  };
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          variant="ghost"
+          size="icon"
+          onClick={handleDownload}
+          aria-label={title}
+          className={BUTTON_CLASS}
+        >
+          <Download className="h-3 w-3" />
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent side="top">{title}</TooltipContent>
+    </Tooltip>
+  );
+};

package/src/FloatingToolbar/actions/ExpandAction.tsx

@@ -0,0 +1,33 @@
+'use client';
+
+import { ChevronDown, ChevronUp } from 'lucide-react';
+import React from 'react';
+
+import { Button, Tooltip, TooltipContent, TooltipTrigger } from '@djangocfg/ui-core/components';
+
+interface ExpandActionProps {
+  isExpanded: boolean;
+  onToggle: () => void;
+}
+
+const BUTTON_CLASS = 'h-6 w-6 rounded-sm bg-muted/80 hover:bg-muted border border-border/50 backdrop-blur-sm';
+
+export const ExpandAction: React.FC<ExpandActionProps> = ({ isExpanded, onToggle }) => {
+  const label = isExpanded ? 'Collapse All' : 'Expand All';
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          variant="ghost"
+          size="icon"
+          onClick={onToggle}
+          aria-label={label}
+          className={BUTTON_CLASS}
+        >
+          {isExpanded ? <ChevronUp className="h-3 w-3" /> : <ChevronDown className="h-3 w-3" />}
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent side="top">{label}</TooltipContent>
+    </Tooltip>
+  );
+};

package/src/FloatingToolbar/actions/FullscreenAction.tsx

@@ -0,0 +1,38 @@
+'use client';
+
+import { Maximize2, Minimize2 } from 'lucide-react';
+import React from 'react';
+
+import { Button, Tooltip, TooltipContent, TooltipTrigger } from '@djangocfg/ui-core/components';
+
+interface FullscreenActionProps {
+  isFullscreen?: boolean;
+  onToggle: () => void;
+  title?: string;
+}
+
+const BUTTON_CLASS = 'h-6 w-6 rounded-sm bg-muted/80 hover:bg-muted border border-border/50 backdrop-blur-sm';
+
+export const FullscreenAction: React.FC<FullscreenActionProps> = ({
+  isFullscreen = false,
+  onToggle,
+  title,
+}) => {
+  const label = title ?? (isFullscreen ? 'Exit fullscreen' : 'Fullscreen');
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          variant="ghost"
+          size="icon"
+          onClick={onToggle}
+          aria-label={label}
+          className={BUTTON_CLASS}
+        >
+          {isFullscreen ? <Minimize2 className="h-3 w-3" /> : <Maximize2 className="h-3 w-3" />}
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent side="top">{label}</TooltipContent>
+    </Tooltip>
+  );
+};

package/src/FloatingToolbar/actions/index.ts

@@ -0,0 +1,4 @@
+export { CopyAction } from './CopyAction';
+export { DownloadAction } from './DownloadAction';
+export { ExpandAction } from './ExpandAction';
+export { FullscreenAction } from './FullscreenAction';

package/src/FloatingToolbar/hooks/useScrollIsolation.ts

@@ -0,0 +1,62 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+
+const UNLOCKED_CLASS = 'scroll-unlocked';
+
+/**
+ * Scroll isolation — prevents the container from capturing wheel scroll
+ * until the user explicitly clicks inside it (like Google Maps).
+ *
+ * Locked (overlay visible): wheel events on container scroll the PAGE.
+ * Unlocked: normal scroll inside the container.
+ *
+ * Unlock: click anywhere inside the container.
+ * Re-lock: click outside the container.
+ *
+ * When unlocked, adds `scroll-unlocked` class to the container element
+ * so it can be styled (e.g. focus ring) via CSS.
+ */
+export function useScrollIsolation(
+  ref: React.RefObject<HTMLElement | null>,
+  enabled: boolean,
+) {
+  const [locked, setLocked] = useState(true);
+
+  const unlock = useCallback(() => setLocked(false), []);
+
+  // Re-lock when clicking outside the container
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleDocClick = (e: MouseEvent) => {
+      const el = ref.current;
+      if (!el) return;
+      if (!el.contains(e.target as Node)) {
+        setLocked(true);
+      }
+    };
+
+    document.addEventListener('click', handleDocClick, true);
+    return () => document.removeEventListener('click', handleDocClick, true);
+  }, [enabled, ref]);
+
+  // Toggle class on container to allow CSS-driven focus ring
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || !enabled) return;
+    if (locked) {
+      el.classList.remove(UNLOCKED_CLASS);
+    } else {
+      el.classList.add(UNLOCKED_CLASS);
+    }
+    return () => el.classList.remove(UNLOCKED_CLASS);
+  }, [locked, enabled, ref]);
+
+  // Reset to locked when feature toggled on
+  useEffect(() => {
+    if (enabled) setLocked(true);
+  }, [enabled]);
+
+  return { locked, unlock };
+}

package/src/FloatingToolbar/index.tsx

@@ -0,0 +1,184 @@
+'use client';
+
+import React, { useEffect, useState } from 'react';
+
+import './FloatingToolbar.css';
+import { useScrollIsolation } from './hooks/useScrollIsolation';
+
+/**
+ * Track whether the container actually overflows. Scroll isolation
+ * (and its "Click to scroll" overlay) only makes sense when there is
+ * something to scroll — a fully-visible block must stay interactive.
+ */
+function useIsScrollable(ref: React.RefObject<HTMLElement | null>): boolean {
+  const [scrollable, setScrollable] = useState(false);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+
+    const measure = () => {
+      // 1px tolerance for sub-pixel rounding.
+      setScrollable(
+        el.scrollHeight - el.clientHeight > 1 ||
+          el.scrollWidth - el.clientWidth > 1,
+      );
+    };
+
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [ref]);
+
+  return scrollable;
+}
+
+export interface FloatingToolbarProps {
+  /** Ref to the container element the toolbar anchors to */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Action buttons to render (right side) */
+  children: React.ReactNode;
+  /** Optional label shown left of the buttons (e.g. language badge) */
+  label?: React.ReactNode;
+  /** Where to anchor relative to the container (default: bottom-right) */
+  position?: 'top-right' | 'bottom-right';
+  /** Offset from the edge in px (default: 8) */
+  offset?: number;
+  /** z-index (default: 30) */
+  zIndex?: number;
+  /**
+   * Block wheel scroll inside the container until user clicks into it.
+   * Re-locks when mouse leaves. Like Google Maps scroll isolation.
+   * @default true
+   */
+  scrollIsolation?: boolean;
+  /**
+   * Hide the toolbar until the user hovers the container. ChatGPT /
+   * GitHub-style: chrome stays out of the way, appears on demand.
+   * Keyboard focus inside the container also reveals it (a11y).
+   * @default false (always visible — back-compat)
+   */
+  autoHide?: boolean;
+}
+
+/**
+ * Toolbar is anchored with `position: absolute` inside the container (PrettyCode, etc.).
+ * `position: fixed` + viewport coordinates breaks embedded layouts (e.g. chat composer overlap).
+ */
+export const FloatingToolbar: React.FC<FloatingToolbarProps> = ({
+  containerRef,
+  children,
+  label,
+  position = 'bottom-right',
+  offset = 8,
+  zIndex = 30,
+  scrollIsolation = true,
+  autoHide = false,
+}) => {
+  // Isolation only engages when the container can actually scroll —
+  // a block that fully fits never shows the "Click to scroll" overlay.
+  const isScrollable = useIsScrollable(containerRef);
+  const isolationActive = scrollIsolation && isScrollable;
+
+  const { locked, unlock } = useScrollIsolation(containerRef, isolationActive);
+  const [overlayHovered, setOverlayHovered] = useState(false);
+
+  // Track container hover + focus for ChatGPT-style auto-hide. We watch
+  // `mouseenter/leave` and `focusin/out` on the container so keyboard
+  // users still see the toolbar — `:hover` alone would hide it from
+  // them entirely.
+  const [containerActive, setContainerActive] = useState(false);
+  useEffect(() => {
+    if (!autoHide) return;
+    const el = containerRef.current;
+    if (!el) return;
+    const enter = () => setContainerActive(true);
+    const leave = () => setContainerActive(false);
+    el.addEventListener('mouseenter', enter);
+    el.addEventListener('mouseleave', leave);
+    el.addEventListener('focusin', enter);
+    el.addEventListener('focusout', leave);
+    return () => {
+      el.removeEventListener('mouseenter', enter);
+      el.removeEventListener('mouseleave', leave);
+      el.removeEventListener('focusin', enter);
+      el.removeEventListener('focusout', leave);
+    };
+  }, [autoHide, containerRef]);
+
+  const overlay =
+    isolationActive && locked ? (
+      <div
+        onClick={unlock}
+        onMouseEnter={() => setOverlayHovered(true)}
+        onMouseLeave={() => setOverlayHovered(false)}
+        style={{
+          position: 'absolute',
+          inset: 0,
+          zIndex: zIndex - 1,
+          cursor: 'pointer',
+          background: overlayHovered ? 'rgba(0,0,0,0.04)' : 'transparent',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          transition: 'background 150ms',
+        }}
+      >
+        {overlayHovered && (
+          <span
+            style={{
+              fontSize: '0.75rem',
+              padding: '0.25rem 0.625rem',
+              borderRadius: '9999px',
+              background: 'rgba(0,0,0,0.55)',
+              color: '#fff',
+              pointerEvents: 'none',
+              userSelect: 'none',
+            }}
+          >
+            Click to scroll
+          </span>
+        )}
+      </div>
+    ) : null;
+
+  const positionStyle: React.CSSProperties =
+    position === 'bottom-right'
+      ? { bottom: offset, right: offset }
+      : { top: offset, right: offset };
+
+  // Auto-hide: invisible until the container is hovered or has keyboard
+  // focus inside. Opacity transition keeps the reveal smooth instead of
+  // popping. `pointer-events: none` while hidden so the toolbar doesn't
+  // intercept clicks on whatever sits behind it.
+  const hidden = autoHide && !containerActive;
+  const toolbar = (
+    <div
+      className="flex items-center gap-1"
+      style={{
+        position: 'absolute',
+        ...positionStyle,
+        zIndex,
+        opacity: hidden ? 0 : 1,
+        pointerEvents: hidden ? 'none' : undefined,
+        transition: 'opacity 120ms ease-out',
+      }}
+    >
+      {label && (
+        <>
+          {label}
+          <div className="w-px h-4 bg-border/50 mx-0.5" />
+        </>
+      )}
+      {children}
+    </div>
+  );
+
+  return (
+    <>
+      {overlay}
+      {toolbar}
+    </>
+  );
+};