@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/diagrams/mermaid-theme.ts

@@ -0,0 +1,115 @@
+/**
+ * The one place mermaid gets told what colour anything is.
+ *
+ * Extracted from `ChatMermaidBlock` so every mermaid surface in the kit — the
+ * chat fence and the architecture diagram — resolves the same palette the same
+ * way, and a token added for one is a token added for both.
+ *
+ * THE RULE: mermaid gets `theme: "base"` — the only built-in palette that lets
+ * every `themeVariable` through — and every variable is filled from the
+ * *computed* value of a design token read off the host element. Reading off the
+ * host rather than `:root` means a livery scope (`.accent-digichat`,
+ * `.accent-digiquant`) or a nested `[data-theme]` resolves exactly the colours
+ * the surrounding section resolves.
+ *
+ * Tokens that do not resolve (tokens.css not loaded, non-browser) are omitted,
+ * so mermaid falls back to its own value for that variable rather than being
+ * handed an empty string it cannot parse.
+ */
+
+/**
+ * mermaid themeVariable -> design token. Kept explicit (rather than letting
+ * mermaid derive everything from `primaryColor`) because its derivation runs
+ * khroma lighten/darken on whatever it is given, and the canon palette is not a
+ * ramp — `--ink-mute` is the line colour in both themes, not a shade of the
+ * node fill. Diagram kinds beyond flowchart borrow these too: the sequence,
+ * state, class, ER and architecture renderers all read actor/label/note/
+ * attribute/border vars.
+ */
+export const THEME_TOKENS: ReadonlyArray<readonly [string, string]> = [
+  // canvas + type
+  ["background", "--surface"],
+  ["textColor", "--ink-soft"],
+  ["titleColor", "--ink"],
+  // nodes
+  ["primaryColor", "--surface-2"],
+  ["primaryTextColor", "--ink"],
+  ["primaryBorderColor", "--accent"],
+  ["secondaryColor", "--surface"],
+  ["secondaryTextColor", "--ink"],
+  ["secondaryBorderColor", "--hair-2"],
+  ["tertiaryColor", "--surface"],
+  ["tertiaryTextColor", "--ink-soft"],
+  ["tertiaryBorderColor", "--hair-2"],
+  ["mainBkg", "--surface-2"],
+  ["nodeBorder", "--accent"],
+  ["nodeTextColor", "--ink"],
+  // edges + clusters
+  ["lineColor", "--ink-mute"],
+  ["edgeLabelBackground", "--surface"],
+  ["clusterBkg", "--surface"],
+  ["clusterBorder", "--hair-2"],
+  // architecture (v11 architecture-beta)
+  ["archEdgeColor", "--ink-mute"],
+  ["archEdgeArrowColor", "--ink-mute"],
+  ["archGroupBorderColor", "--hair-2"],
+  // sequence
+  ["actorBkg", "--surface-2"],
+  ["actorBorder", "--accent"],
+  ["actorTextColor", "--ink"],
+  ["actorLineColor", "--ink-mute"],
+  ["signalColor", "--ink-mute"],
+  ["signalTextColor", "--ink-soft"],
+  ["activationBkgColor", "--surface-2"],
+  ["activationBorderColor", "--accent"],
+  ["sequenceNumberColor", "--surface"],
+  ["labelBoxBkgColor", "--surface-2"],
+  ["labelBoxBorderColor", "--hair-2"],
+  ["labelTextColor", "--ink"],
+  ["loopTextColor", "--ink-soft"],
+  ["noteBkgColor", "--surface"],
+  ["noteBorderColor", "--hair-2"],
+  ["noteTextColor", "--ink-soft"],
+  ["altBackground", "--surface-2"],
+  // class / ER / state
+  ["classText", "--ink"],
+  ["attributeBackgroundColorOdd", "--surface"],
+  ["attributeBackgroundColorEven", "--surface-2"],
+  // pie / quadrant chrome (categorical slice hues stay mermaid's — the canon
+  // has no categorical ramp in the token layer)
+  ["pieTitleTextColor", "--ink"],
+  ["pieSectionTextColor", "--ink"],
+  ["pieLegendTextColor", "--ink-soft"],
+  ["pieStrokeColor", "--surface"],
+  ["pieOuterStrokeColor", "--hair-2"],
+  // failure chrome — the negative-semantics token, so a bad node reads red in
+  // both themes without a literal
+  ["errorBkgColor", "--surface"],
+  ["errorTextColor", "--down"],
+];
+
+/**
+ * Stroke widths are numbers, not colours, so they cannot come from a token —
+ * they are pinned here to the kit's hairline weight so an architecture diagram
+ * draws at the same weight as every other rule on the page.
+ */
+const THEME_LITERALS: ReadonlyArray<readonly [string, string]> = [
+  ["archEdgeWidth", "1.4"],
+  ["archGroupBorderWidth", "1"],
+];
+
+/** Resolve THEME_TOKENS against `host`'s computed style. */
+export function tokenThemeVariables(host: Element): Record<string, string | boolean> {
+  const cs = window.getComputedStyle(host);
+  const vars: Record<string, string | boolean> = {};
+  for (const [key, token] of THEME_TOKENS) {
+    const value = cs.getPropertyValue(token).trim();
+    if (value) vars[key] = value;
+  }
+  for (const [key, value] of THEME_LITERALS) vars[key] = value;
+  const mono = cs.getPropertyValue("--font-mono").trim();
+  if (mono) vars.fontFamily = mono;
+  // mermaid's own lighten/darken direction for anything it still derives.
+  vars.darkMode = document.documentElement.getAttribute("data-theme") !== "light";
+  return vars;
+}

package/src/components/diagrams/tour-camera.ts

@@ -0,0 +1,171 @@
+/**
+ * Scroll pose for the architecture tour camera.
+ *
+ * The walk is one 0..1 progress value. Each step owns an equal slice. The
+ * camera rests on that step's boxes through the parked midpoint (where a
+ * single wheel gesture settles), then glides to the next step's boxes so it
+ * arrives as the narration crosses the boundary.
+ */
+
+export interface CamFrame {
+  k: number;
+  x: number;
+  y: number;
+}
+
+export const CAM_IDENTITY: CamFrame = { k: 1, x: 0, y: 0 };
+
+export interface Box {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface SpotRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+const clamp01 = (n: number): number => Math.max(0, Math.min(1, n));
+
+const smooth = (n: number): number => {
+  const t = clamp01(n);
+  return t * t * (3 - 2 * t);
+};
+
+/** Active step and the 0..1 position inside it. Progress 1 stays on the last step. */
+export function walkCursor(progress: number, count: number): { index: number; frac: number } {
+  if (count <= 0) return { index: 0, frac: 0 };
+  const v = clamp01(progress) * count;
+  const index = Math.min(count - 1, Math.floor(v));
+  const frac = v - index;
+  return { index, frac: clamp01(frac) };
+}
+
+/**
+ * 0 while the reader is parked on this step's boxes, then 0→1 across the
+ * tail of the step so the camera is on the next boxes as the step index flips.
+ */
+export function glideAmount(frac: number): number {
+  return smooth((frac - 0.55) / 0.45);
+}
+
+export function lerpCam(a: CamFrame, b: CamFrame, t: number): CamFrame {
+  const u = clamp01(t);
+  return {
+    k: a.k + (b.k - a.k) * u,
+    x: a.x + (b.x - a.x) * u,
+    y: a.y + (b.y - a.y) * u,
+  };
+}
+
+export function camTransform(frame: CamFrame): string {
+  if (frame.k < 1.02 && Math.abs(frame.x) < 0.5 && Math.abs(frame.y) < 0.5) return "";
+  return `scale(${frame.k.toFixed(4)}) translate(${frame.x.toFixed(2)}px, ${frame.y.toFixed(2)}px)`;
+}
+
+/**
+ * Frame the lit boxes. Zoom is capped so a small pair of boxes cannot crop
+ * the rest of the drawing out of the stage, and a step that already fills
+ * the frame (the whole-graph opener) stays at identity.
+ */
+export function fitCamera(opts: {
+  boxes: Box[];
+  stageW: number;
+  stageH: number;
+  contentW: number;
+  contentH: number;
+  /** Fraction of the stage the target should occupy. */
+  fill?: number;
+  maxScale?: number;
+  /**
+   * Contain (default) fits the whole cluster in the stage, so a wide row
+   * never zooms. Cover zooms on the tighter axis, up to `maxScale`, so a
+   * wide short row still travels into view.
+   */
+  cover?: boolean;
+  /** Stage pixels kept clear around the lit boxes, so the glow is never cut. */
+  pad?: number;
+}): CamFrame {
+  const { boxes, stageW, stageH, contentW, contentH } = opts;
+  const fill = opts.fill ?? 0.34;
+  const maxScale = opts.maxScale ?? 1.45;
+  const pad = opts.pad ?? 24;
+  if (boxes.length === 0 || stageW <= 0 || stageH <= 0 || contentW <= 0 || contentH <= 0) {
+    return CAM_IDENTITY;
+  }
+  const minX = Math.min(...boxes.map((b) => b.x));
+  const minY = Math.min(...boxes.map((b) => b.y));
+  const maxX = Math.max(...boxes.map((b) => b.x + b.w));
+  const maxY = Math.max(...boxes.map((b) => b.y + b.h));
+  const width = Math.max(maxX - minX, 1);
+  const height = Math.max(maxY - minY, 1);
+  /* A cluster that already covers the drawing is the whole-graph beat.
+     Cover would otherwise zoom the letterboxed margin around it. */
+  if (width / contentW > 0.7 && height / contentH > 0.62) return CAM_IDENTITY;
+  const contain = Math.min(
+    Math.max(stageW - 2 * pad, 1) / width,
+    Math.max(stageH - 2 * pad, 1) / height,
+  );
+  const cover = Math.max(stageW / width, stageH / height);
+  // Cover never crops the lit boxes: it stops at the padded contain fit.
+  const zoom = opts.cover ? Math.min(fill * cover, contain) : fill * contain;
+  const k = Math.max(1, Math.min(maxScale, zoom));
+  if (k < 1.02) return CAM_IDENTITY;
+  const cx = (minX + maxX) / 2;
+  const cy = (minY + maxY) / 2;
+  const pan = (span: number, content: number, centre: number): number => {
+    const low = span / k - content;
+    if (low > 0) return low / 2;
+    return Math.min(0, Math.max(low, span / (2 * k) - centre));
+  };
+  return { k, x: pan(stageW, contentW, cx), y: pan(stageH, contentH, cy) };
+}
+
+/** Spotlight over the lit boxes. A union that already covers the drawing is the
+    whole-graph beat — no spotlight, the full graph stays lit. */
+export function unionSpot(
+  boxes: Box[],
+  contentW: number,
+  contentH: number,
+  pad = 6,
+): SpotRect | null {
+  if (boxes.length === 0 || contentW <= 0 || contentH <= 0) return null;
+  const minX = Math.min(...boxes.map((b) => b.x));
+  const minY = Math.min(...boxes.map((b) => b.y));
+  const maxX = Math.max(...boxes.map((b) => b.x + b.w));
+  const maxY = Math.max(...boxes.map((b) => b.y + b.h));
+  const width = Math.max(maxX - minX, 0);
+  const height = Math.max(maxY - minY, 0);
+  if ((width * height) / (contentW * contentH) > 0.78) return null;
+  return {
+    left: minX - pad,
+    top: minY - pad,
+    width: width + pad * 2,
+    height: height + pad * 2,
+  };
+}
+
+export function mixSpot(
+  a: SpotRect | null,
+  b: SpotRect | null,
+  t: number,
+): { rect: SpotRect; opacity: number } | null {
+  const u = clamp01(t);
+  if (!a && !b) return null;
+  if (!a && b) return { rect: b, opacity: u };
+  if (a && !b) return { rect: a, opacity: 1 - u };
+  if (!a || !b) return null;
+  return {
+    rect: {
+      left: a.left + (b.left - a.left) * u,
+      top: a.top + (b.top - a.top) * u,
+      width: a.width + (b.width - a.width) * u,
+      height: a.height + (b.height - a.height) * u,
+    },
+    opacity: 1,
+  };
+}

package/src/components/docs/CodeTabs.tsx

@@ -0,0 +1,90 @@
+"use client";
+import { useState } from "react";
+import { Button } from "../../ui";
+
+/**
+ * Docs code affordances: a hover-revealed copy button, a bare copyable code
+ * block, and a label-tabbed code switcher. Presentation-generic — samples
+ * arrive as `{ label, code }`, so language naming ("curl" vs "bash") is the
+ * caller's business. Token-backed utilities carry the look; the hover-reveal
+ * combinator for the copy button lives in styles/docs.css.
+ */
+
+export interface CodeSample {
+  /** Tab label, e.g. "curl", "Python", "TypeScript". */
+  label: string;
+  code: string;
+}
+
+/** Tiny write-only "copy / copied" clipboard button (1.2s confirmation flip). */
+function DocsCopyButton({ text, ariaLabel }: { text: string; ariaLabel: string }) {
+  const [copied, setCopied] = useState(false);
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      className="docs-code-copy h-auto cursor-pointer rounded-none border border-hair bg-surface/80 px-[0.4rem] py-[0.12rem] font-mono text-[0.7rem] font-normal text-ink-mute hover:bg-transparent hover:text-ink"
+      aria-label={ariaLabel}
+      onClick={() =>
+        navigator.clipboard?.writeText(text).then(
+          () => {
+            setCopied(true);
+            setTimeout(() => setCopied(false), 1200);
+          },
+          () => {},
+        )
+      }
+    >
+      {copied ? "copied" : "copy"}
+    </Button>
+  );
+}
+
+/** Pre-formatted code block with the hover-revealed copy affordance. */
+export function DocsCodeBlock({
+  code,
+  copyLabel = "Copy code",
+}: {
+  code: string;
+  copyLabel?: string;
+}) {
+  return (
+    <div className="doc-code relative mt-[0.5rem]">
+      <DocsCopyButton text={code} ariaLabel={copyLabel} />
+      <pre className="m-0 overflow-x-auto rounded-none border border-hair bg-ink/6 px-[0.8rem] py-[0.7rem]">
+        <code className="whitespace-pre font-mono text-[0.8rem] text-ink">{code}</code>
+      </pre>
+    </div>
+  );
+}
+
+/** Label-tabbed code block — one sample visible at a time, copyable. */
+export function CodeTabs({ samples }: { samples: CodeSample[] }) {
+  const [sel, setSel] = useState(0);
+  if (!samples.length) return null;
+  const cur = samples[Math.min(sel, samples.length - 1)];
+  return (
+    <div className="mt-[0.3rem] flex flex-col gap-[0.3rem]">
+      {samples.length > 1 && (
+        <div className="flex gap-[0.2rem]" role="tablist">
+          {samples.map((s, i) => (
+            <Button
+              key={s.label}
+              type="button"
+              role="tab"
+              aria-selected={i === sel}
+              variant="link"
+              className={`h-auto cursor-pointer rounded-none border border-transparent px-[0.6rem] py-[0.2rem] font-mono text-[0.72rem] font-normal transition-colors duration-150 ease-brand hover:no-underline ${
+                i === sel ? "bg-accent-weak text-ink" : "text-ink-mute hover:text-ink-soft"
+              }`}
+              onClick={() => setSel(i)}
+            >
+              {s.label}
+            </Button>
+          ))}
+        </div>
+      )}
+      <DocsCodeBlock code={cur.code} copyLabel={`Copy ${cur.label} example`} />
+    </div>
+  );
+}

package/src/components/docs/CopyCommand.tsx

@@ -0,0 +1,151 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { cn } from "../../lib/utils";
+import type { CodeSample } from "./CodeTabs";
+
+/**
+ * The install command, as the primary action. OpenCode-informed: a label tab
+ * strip sits on a hairline, and the command beneath it *is* the copy button —
+ * no separate "copy" chrome floating beside it. A click blurs the command and
+ * shows "copied" for a few seconds, then the command returns. The command is
+ * split into a muted `protocol` prefix and a medium-weight ink payload; there
+ * is no syntax colour. The inline form is the shared `copy-cmd` button the
+ * hero clone and the module compose line both use.
+ */
+export interface CopyCommandSample extends CodeSample {
+  /** Leading token rendered muted, e.g. `docker compose` or `git clone`. */
+  protocol?: string;
+}
+
+export interface CopyCommandProps {
+  samples: CopyCommandSample[];
+  /** Accessible name for the tab strip. */
+  ariaLabel?: string;
+  className?: string;
+  /**
+   * Single-command form: no tab strip, no copy affordance — the whole code box
+   * *is* the button ("click the box and it copies"). For a hero where the
+   * command is a one-liner and the tabs would be noise. `samples[0]` is shown;
+   * the rest are ignored.
+   */
+  inline?: boolean;
+}
+
+/** How long the command stays blurred with the copied note. */
+const COPIED_MS = 2500;
+
+async function writeClipboard(text: string): Promise<boolean> {
+  const clipboard = typeof navigator === "undefined" ? undefined : navigator.clipboard;
+  if (clipboard?.writeText) {
+    try {
+      await clipboard.writeText(text);
+      return true;
+    } catch {
+      /* fall through */
+    }
+  }
+  try {
+    const el = document.createElement("textarea");
+    el.value = text;
+    el.setAttribute("readonly", "");
+    el.style.position = "fixed";
+    el.style.top = "-9999px";
+    document.body.appendChild(el);
+    el.select();
+    const ok = document.execCommand("copy");
+    document.body.removeChild(el);
+    return ok;
+  } catch {
+    return false;
+  }
+}
+
+function splitCommand(sample: CopyCommandSample): [string, string] {
+  const { code, protocol } = sample;
+  if (!protocol || !code.startsWith(protocol)) return ["", code];
+  return [protocol, code.slice(protocol.length)];
+}
+
+export function CopyCommand({ samples, ariaLabel = "Install command", className, inline = false }: CopyCommandProps) {
+  const [selected, setSelected] = useState(0);
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  const current = samples[Math.min(selected, samples.length - 1)];
+  if (!current) return null;
+
+  const [protocol, payload] = splitCommand(current);
+
+  function copy() {
+    void writeClipboard(current.code).then((ok) => {
+      if (!ok) return;
+      setCopied(true);
+      if (timer.current) clearTimeout(timer.current);
+      timer.current = setTimeout(() => setCopied(false), COPIED_MS);
+    });
+  }
+
+  return (
+    <div className={cn(inline ? "w-fit max-w-full" : "w-full max-w-[var(--measure-prose)]", className)}>
+      {inline ? null : (
+        <div
+          role="tablist"
+          aria-label={ariaLabel}
+          className="flex flex-wrap items-end gap-[1.4rem] border-b border-hair"
+        >
+        {samples.map((sample, index) => (
+          <button
+            key={sample.label}
+            type="button"
+            role="tab"
+            aria-selected={index === selected}
+            onClick={() => setSelected(index)}
+            className={cn(
+              "cursor-pointer border-b-2 border-transparent bg-transparent pb-[0.55rem] font-mono text-[0.8rem] tracking-[0.02em] transition-colors duration-150 ease-brand",
+              index === selected ? "border-b-ink text-ink" : "text-ink-mute hover:text-ink-soft",
+            )}
+          >
+            {sample.label}
+          </button>
+        ))}
+        </div>
+      )}
+      <button
+        type="button"
+        data-copied={copied ? "true" : "false"}
+        onClick={copy}
+        aria-label={`Copy ${inline ? "command" : `${current.label} command`}`}
+        className={cn(
+          "copy-cmd group relative flex cursor-pointer items-center gap-[1rem] px-[1rem] py-[0.85rem] text-left font-mono text-[0.85rem] leading-[1.5] text-ink hover:bg-surface-2",
+          inline
+            ? "w-auto max-w-full border border-hair bg-transparent"
+            : "w-full border-x border-b border-t-0 border-hair bg-surface",
+        )}
+      >
+        <span
+          className={cn(
+            "min-w-0 truncate whitespace-nowrap transition-[filter,opacity] duration-200 group-data-[copied=true]:blur-[3px] group-data-[copied=true]:opacity-40",
+            inline ? "" : "flex-1",
+          )}
+        >
+          {protocol ? <span className="text-ink-mute">{protocol}</span> : null}
+          <span className="font-medium">{payload}</span>
+        </span>
+        <span
+          aria-hidden="true"
+          className="pointer-events-none absolute inset-0 hidden items-center justify-center font-medium text-ink group-data-[copied=true]:flex"
+        >
+          copied
+        </span>
+      </button>
+    </div>
+  );
+}