@kekonic/diagrams-ui 1.0.0-rc.4

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@kekonic/diagrams-ui",
+  "version": "1.0.0-rc.4",
+  "description": "Shared chrome styles, KDiagram syntax highlighting, and React embeds as thin Lit wrappers.",
+  "homepage": "https://github.com/kekonic/diagrams#readme",
+  "bugs": {
+    "url": "https://github.com/kekonic/diagrams/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kekonic/diagrams.git",
+    "directory": "packages/diagrams-ui"
+  },
+  "files": [
+    "dist",
+    "src/chrome",
+    "src/diagram"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./chrome.css": "./src/chrome/tokens.css",
+    "./live.css": "./src/diagram/live.css",
+    "./playground.css": "./src/diagram/playground.css",
+    "./playground": {
+      "types": "./dist/playground.d.mts",
+      "import": "./dist/playground.mjs"
+    },
+    "./highlight": {
+      "types": "./dist/shiki/highlight.d.mts",
+      "import": "./dist/shiki/highlight.mjs"
+    },
+    "./shiki": {
+      "types": "./dist/shiki/kdiagram.d.mts",
+      "import": "./dist/shiki/kdiagram.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lit/react": "^1.0.8",
+    "shiki": "^4.3.1",
+    "@kekonic/diagrams": "1.0.0-rc.4",
+    "@kekonic/diagrams-core": "1.0.0-rc.4",
+    "@kekonic/diagrams-element": "1.0.0-rc.4"
+  },
+  "devDependencies": {
+    "@types/node": "^26",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^5",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.2",
+    "vite-plus": "0.2.2",
+    "vitest": "^4"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test"
+  }
+}

package/src/chrome/tokens.css

@@ -0,0 +1,109 @@
+/**
+ * KDiagram chrome — shared by Studio and other product hosts.
+ * Sharp shell, purple brand accent. Diagram colors use --kd-* separately.
+ *
+ * Brand hue is OKLCH 288 — between indigo (277) and Tailwind violet (293). Past
+ * ~300 the hue runs into purple → fuchsia (322) → pink (354), so raising chroma
+ * there turns the brand pink instead of deepening it. At 288 more chroma reads
+ * as richer violet.
+ */
+
+:root,
+:root[data-theme="dark"],
+[data-theme="dark"] {
+  --bg: oklch(16% 0.012 288);
+  --bg-elevated: oklch(20% 0.014 288);
+  --bg-panel: oklch(18.5% 0.013 288);
+  --bg-input: oklch(13% 0.01 288);
+  --border: oklch(30% 0.02 288);
+  --border-soft: oklch(24% 0.014 288);
+  --text: oklch(93% 0.008 288);
+  --text-muted: oklch(68% 0.02 288);
+  --text-faint: oklch(48% 0.016 288);
+  --accent: oklch(72% 0.14 288);
+  --accent-soft: oklch(72% 0.14 288 / 0.18);
+  /* Dark-mode accent is light, so text on it must be dark. */
+  --accent-contrast: oklch(16% 0.012 288);
+  --danger: oklch(68% 0.14 25);
+  --warn: oklch(78% 0.12 85);
+  --ok: oklch(68% 0.12 155);
+  --focus: oklch(72% 0.14 288 / 0.55);
+  --shadow: 0 12px 40px oklch(0% 0 0 / 0.45);
+  color-scheme: dark;
+}
+
+:root[data-theme="light"],
+[data-theme="light"] {
+  --bg: oklch(97.5% 0.008 288);
+  --bg-elevated: oklch(100% 0.004 288);
+  --bg-panel: oklch(95.5% 0.012 288);
+  --bg-input: oklch(100% 0.004 288);
+  --border: oklch(82% 0.02 288);
+  --border-soft: oklch(88% 0.014 288);
+  --text: oklch(22% 0.03 288);
+  --text-muted: oklch(42% 0.025 288);
+  --text-faint: oklch(58% 0.02 288);
+  --accent: oklch(48% 0.21 288);
+  --accent-soft: oklch(48% 0.21 288 / 0.12);
+  /* Light-mode accent is dark, so text on it must be near-white. */
+  --accent-contrast: oklch(98% 0.01 288);
+  --danger: oklch(52% 0.16 25);
+  --warn: oklch(58% 0.14 75);
+  --ok: oklch(48% 0.12 155);
+  --focus: oklch(48% 0.21 288 / 0.45);
+  --shadow: 0 12px 40px oklch(30% 0.04 288 / 0.12);
+  color-scheme: light;
+}
+
+:root {
+  /*
+   * Filled brand surfaces (primary buttons). Theme-independent on purpose: the
+   * per-theme --accent flips light/dark for legible link text, which makes it a
+   * poor button fill — a pale lavender button washes out and can only carry a
+   * legible label in one mode. One deeper violet works on both page backgrounds
+   * and always takes a near-white label.
+   * Label 5.8:1 at rest, 7.8:1 on hover; button edge 3.1:1 on dark, 5.8:1 on light.
+   */
+  --accent-strong: oklch(52% 0.24 288);
+  --accent-strong-hover: oklch(45% 0.22 288);
+  --on-accent-strong: oklch(98% 0.01 288);
+  --radius: 0;
+  --font-ui: "IBM Plex Sans", "Segoe UI", system-ui, sans-serif;
+  --font-mono: "IBM Plex Mono", "JetBrains Mono", "Fira Code", ui-monospace, monospace;
+  --toolbar-h: 52px;
+  --drawer-w: 300px;
+  --content-max: 72rem;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+button,
+select,
+textarea,
+input {
+  color: inherit;
+  font: inherit;
+}
+
+button {
+  cursor: pointer;
+}
+
+:focus {
+  outline: none;
+}
+
+:focus-visible {
+  outline: 1px solid color-mix(in oklch, var(--accent) 55%, var(--border));
+  outline-offset: 0;
+}
+
+button:focus-visible,
+select:focus-visible,
+input:focus-visible,
+textarea:focus-visible {
+  outline: none;
+  box-shadow: inset 0 0 0 1px color-mix(in oklch, var(--accent) 55%, var(--border));
+}

package/src/diagram/KDiagramLive.tsx

@@ -0,0 +1,59 @@
+import * as React from "react";
+import { createComponent } from "@lit/react";
+import { KDiagramElement, K_DIAGRAM_TAG } from "@kekonic/diagrams-element";
+import type { InteractiveRenderOptions, RenderResult, ThemeMode } from "@kekonic/diagrams";
+
+export type KDiagramLiveProps = {
+  source: string;
+  /** Diagram theme. `"auto"` follows the host page (`html[data-theme]`). */
+  theme?: ThemeMode | "auto";
+  className?: string;
+  /** Remove the host border and panel background. Controls remain independently configurable. */
+  frameless?: boolean;
+  /** Sun/moon control that dogfoods theme swaps. */
+  showThemeToggle?: boolean;
+  /** Zoom / fit / fullscreen controls. */
+  showViewControls?: boolean;
+  /** Compact render stats badge (floating). Off by default for a clean embed. */
+  showStats?: boolean;
+  /** Animation play/scrub chrome when an animation exists. Default on. */
+  showAnimationControls?: boolean;
+  /** Start playing when the diagram mounts. */
+  autoplay?: boolean;
+  /** Loop the active animation. */
+  animationLoop?: boolean;
+  /** Preferred animation name or id (authored blocks). */
+  animation?: string;
+  height?: number | string;
+  options?: Omit<InteractiveRenderOptions, "theme">;
+  /** Fired after mount / source / theme renders complete. */
+  onKDiagramRender?: (event: CustomEvent<RenderResult>) => void;
+};
+
+/** Lit + React prop inference drifts when the element surface grows; keep React props explicit. */
+const KDiagramReact = createComponent({
+  react: React,
+  tagName: K_DIAGRAM_TAG,
+  elementClass: KDiagramElement,
+  events: {
+    onKDiagramRender: "kdiagram-render",
+  },
+}) as unknown as React.ForwardRefExoticComponent<
+  KDiagramLiveProps & React.RefAttributes<KDiagramElement>
+>;
+
+/**
+ * React thin wrapper around Lit `<k-diagram>`.
+ * Same interactive host as HTML embeds — pan/zoom, theme, live `source` updates.
+ */
+export const KDiagramLive = React.forwardRef<KDiagramElement, KDiagramLiveProps>(
+  function KDiagramLive({ className, ...props }, ref) {
+    return (
+      <KDiagramReact
+        ref={ref}
+        className={["kd-live", className].filter(Boolean).join(" ")}
+        {...props}
+      />
+    );
+  },
+);

package/src/diagram/KDiagramPlayground.tsx

@@ -0,0 +1,288 @@
+import {
+  lazy,
+  Suspense,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type CSSProperties,
+  type UIEvent,
+} from "react";
+import type { ThemeMode } from "@kekonic/diagrams";
+import type { KDiagramLiveProps } from "./KDiagramLive.tsx";
+
+const KDiagramLive = lazy(async () => {
+  const mod = await import("./KDiagramLive.tsx");
+  return { default: mod.KDiagramLive };
+});
+
+/** Kick off Shiki as soon as this island module evaluates (still lazy vs the page). */
+const highlightModule = import("../shiki/highlight.ts");
+
+export type KDiagramPlaygroundProps = {
+  /** Initial KDiagram source (also the Reset target). */
+  source: string;
+  theme?: ThemeMode | "auto";
+  className?: string;
+  /** Remove the live diagram's host border and panel background. */
+  frameless?: boolean;
+  /** Source pane + diagram side-by-side, stacked, or gallery (diagram-first). */
+  layout?: "split" | "stacked" | "gallery";
+  /** Debounce before `controller.update` (ms). */
+  debounceMs?: number;
+  editable?: boolean;
+  showThemeToggle?: boolean;
+  showViewControls?: boolean;
+  showStats?: boolean;
+  showAnimationControls?: boolean;
+  autoplay?: boolean;
+  animationLoop?: boolean;
+  animation?: string;
+  /**
+   * Playground root height — both panes stretch to fill.
+   * Diagram viewport flexes inside; no separate short editor box.
+   */
+  height?: number | string;
+  /**
+   * Minimum height for the source editor region when the root is not stretched
+   * (e.g. stacked layout without an explicit `height`).
+   */
+  editorHeight?: number | string;
+  options?: KDiagramLiveProps["options"];
+};
+
+function escapeHtml(text: string): string {
+  return text
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+function cssSize(value: number | string): string {
+  return typeof value === "number" ? `${value}px` : value;
+}
+
+function copyTextFallback(text: string): boolean {
+  const input = document.createElement("textarea");
+  input.value = text;
+  input.setAttribute("readonly", "");
+  input.style.position = "fixed";
+  input.style.opacity = "0";
+  document.body.append(input);
+  input.select();
+  const copied = document.execCommand("copy");
+  input.remove();
+  return copied;
+}
+
+/**
+ * Docs dogfood embed: editable KDiagram source (Shiki) + live diagram (`KDiagramLive`).
+ * Shiki and the render path load lazily on mount / first highlight.
+ */
+export function KDiagramPlayground({
+  source,
+  theme = "auto",
+  className,
+  frameless = false,
+  layout = "split",
+  debounceMs = 280,
+  editable = true,
+  showThemeToggle = true,
+  showViewControls = true,
+  showStats = false,
+  showAnimationControls = true,
+  autoplay = false,
+  animationLoop = false,
+  animation,
+  height = 360,
+  editorHeight = 280,
+  options,
+}: KDiagramPlaygroundProps) {
+  const [draft, setDraft] = useState(source);
+  const [liveSource, setLiveSource] = useState(source);
+  const [highlightHtml, setHighlightHtml] = useState<string | null>(null);
+  const [dirty, setDirty] = useState(false);
+  const [actionStatus, setActionStatus] = useState("");
+  const highlightRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+  const labelId = useId();
+  const sourceGen = useRef(0);
+
+  useEffect(() => {
+    setDraft(source);
+    setLiveSource(source);
+    setDirty(false);
+  }, [source]);
+
+  useEffect(() => {
+    if (draft === liveSource) return;
+    const t = window.setTimeout(() => setLiveSource(draft), debounceMs);
+    return () => window.clearTimeout(t);
+  }, [draft, liveSource, debounceMs]);
+
+  useEffect(() => {
+    let cancelled = false;
+    const gen = ++sourceGen.current;
+    // Plain text first; upgrade once the module-level Shiki import resolves.
+    setHighlightHtml(`<pre><code>${escapeHtml(draft)}</code></pre>`);
+    void (async () => {
+      try {
+        const { highlightKDiagram } = await highlightModule;
+        const html = await highlightKDiagram(draft);
+        if (!cancelled && gen === sourceGen.current) setHighlightHtml(html);
+      } catch {
+        // Keep plain text if Shiki cannot load in this host.
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [draft]);
+
+  const syncScroll = (event: UIEvent<HTMLTextAreaElement>) => {
+    const pre = highlightRef.current;
+    if (!pre) return;
+    pre.scrollTop = event.currentTarget.scrollTop;
+    pre.scrollLeft = event.currentTarget.scrollLeft;
+  };
+
+  const reset = () => {
+    setDraft(source);
+    setLiveSource(source);
+    setDirty(false);
+    inputRef.current?.focus();
+  };
+
+  const copySource = async () => {
+    let copied = false;
+    try {
+      if (navigator.clipboard?.writeText) {
+        await navigator.clipboard.writeText(draft);
+        copied = true;
+      } else {
+        copied = copyTextFallback(draft);
+      }
+    } catch {
+      copied = copyTextFallback(draft);
+    }
+    setActionStatus(copied ? "Copied source" : "Could not copy source");
+    window.setTimeout(() => setActionStatus(""), 1_500);
+  };
+
+  const downloadSvg = async () => {
+    const { KDiagram } = await import("@kekonic/diagrams");
+    const resolvedTheme =
+      theme === "auto"
+        ? document.documentElement.dataset.theme === "light"
+          ? "light"
+          : "dark"
+        : theme;
+    const result = await KDiagram.renderToSvg(draft, {
+      ...options,
+      theme: resolvedTheme,
+      snapshotTheme: true,
+    });
+    if (!result.ok || !result.svg) {
+      setActionStatus("Fix diagram errors before downloading");
+      return;
+    }
+    const url = URL.createObjectURL(new Blob([result.svg], { type: "image/svg+xml" }));
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = "diagram.svg";
+    document.body.append(link);
+    link.click();
+    link.remove();
+    window.setTimeout(() => URL.revokeObjectURL(url), 1_000);
+    setActionStatus("Downloaded SVG");
+    window.setTimeout(() => setActionStatus(""), 1_500);
+  };
+
+  const rootStyle = {
+    height: cssSize(height),
+    "--kd-play-editor-min": cssSize(editorHeight),
+  } as CSSProperties;
+
+  const hint = editable ? "Edit source — diagram updates live" : "Source + live diagram";
+
+  return (
+    <div
+      className={["kd-play", className].filter(Boolean).join(" ")}
+      style={rootStyle}
+      title={hint}
+      aria-labelledby={labelId}
+    >
+      <span id={labelId} className="kd-play__sr-only">
+        {hint}
+      </span>
+      <div className="kd-play__body" data-layout={layout}>
+        <div className="kd-play__source">
+          <div className="kd-play__pane-bar">
+            <span className="kd-play__label">Source</span>
+            <div className="kd-play__actions">
+              <button type="button" className="kd-play__btn" onClick={() => void copySource()}>
+                Copy source
+              </button>
+              <button type="button" className="kd-play__btn" onClick={() => void downloadSvg()}>
+                Download SVG
+              </button>
+              {editable ? (
+                <button type="button" className="kd-play__btn" disabled={!dirty} onClick={reset}>
+                  Reset
+                </button>
+              ) : null}
+            </div>
+            <span className="kd-play__sr-only" role="status" aria-live="polite">
+              {actionStatus}
+            </span>
+          </div>
+          <div className="kd-play__editor">
+            <div
+              ref={highlightRef}
+              className="kd-play__highlight"
+              aria-hidden
+              dangerouslySetInnerHTML={{
+                __html: highlightHtml ?? `<pre><code>${escapeHtml(draft)}</code></pre>`,
+              }}
+            />
+            {editable ? (
+              <textarea
+                ref={inputRef}
+                className="kd-play__input"
+                value={draft}
+                spellCheck={false}
+                autoCapitalize="off"
+                autoCorrect="off"
+                aria-label="KDiagram source"
+                onScroll={syncScroll}
+                onChange={(event) => {
+                  setDraft(event.target.value);
+                  setDirty(event.target.value !== source);
+                }}
+              />
+            ) : null}
+          </div>
+        </div>
+        <div className="kd-play__diagram">
+          <Suspense fallback={<div className="kd-play__fallback">Loading diagram…</div>}>
+            <KDiagramLive
+              source={liveSource}
+              theme={theme}
+              height="100%"
+              frameless={frameless}
+              showThemeToggle={showThemeToggle}
+              showViewControls={showViewControls}
+              showStats={showStats}
+              showAnimationControls={showAnimationControls}
+              autoplay={autoplay}
+              animationLoop={animationLoop}
+              animation={animation}
+              options={options}
+            />
+          </Suspense>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/diagram/live.css

@@ -0,0 +1,13 @@
+/*
+  Host layout for React embeds of `<k-diagram>`.
+  Chrome (tools, viewport, errors) lives in the Lit shadow root — do not restyle
+  `.kd-live__*` internals here; those class names no longer exist in light DOM.
+*/
+
+.kd-live,
+k-diagram.kd-live {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  box-sizing: border-box;
+}