@elabs-ai/components-editor 4.0.0

package/src/markdown-outline/document-outline.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+/**
+ * DocumentOutline (#L6) — the quiet table-of-contents rail for a markdown
+ * document. Pure presentation: pass `items` from `parseMarkdownOutline` /
+ * `useMarkdownOutline`, drive `activeId` from your scroll observer, and handle
+ * `onSelect` (e.g. scroll the matching `data-sourcepos` block into view).
+ */
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { forwardRef, useMemo, type HTMLAttributes, type ReactNode } from "react";
+
+import { parseMarkdownOutline, type MarkdownOutlineItem } from "./markdown-outline";
+
+/** Memoized outline of a markdown source. */
+export function useMarkdownOutline(markdown: string): MarkdownOutlineItem[] {
+  return useMemo(() => parseMarkdownOutline(markdown), [markdown]);
+}
+
+export interface DocumentOutlineProps extends Omit<HTMLAttributes<HTMLElement>, "onSelect"> {
+  items: MarkdownOutlineItem[];
+  /** The outline item currently in view. */
+  activeId?: string;
+  onSelect?: (item: MarkdownOutlineItem) => void;
+  /**
+   * Per-entry hover affordances (pin/copy-link…), rendered at the row end.
+   * Revealed on row hover/focus; stays visible while it contains a pressed
+   * toggle (`aria-pressed="true"`).
+   */
+  itemActions?: (item: MarkdownOutlineItem) => ReactNode;
+}
+
+export const DocumentOutline = forwardRef<HTMLElement, DocumentOutlineProps>(
+  function DocumentOutline({ items, activeId, onSelect, itemActions, className, ...props }, ref) {
+    const minLevel = items.reduce<number>((min, it) => Math.min(min, it.level), 6);
+    return (
+      <nav
+        ref={ref}
+        aria-label="Document outline"
+        className={cn("text-body", className)}
+        {...props}
+      >
+        {/* TOC grammar: a structural hairline rail; each entry overlays it with a
+            2px segment — primary for the active heading, visible on hover — so
+            position-in-document reads at a glance (the accent-rail channel from
+            the separation grammar, not a generic list). */}
+        <ul className="m-0 list-none border-s border-border p-0">
+          {items.map((item) => {
+            const actions = itemActions?.(item);
+            return (
+              <li key={item.id} className={cn(actions && "group/outline-item relative")}>
+                <button
+                  type="button"
+                  aria-current={item.id === activeId ? "true" : undefined}
+                  onClick={() => onSelect?.(item)}
+                  className={cn(
+                    "-ms-px block w-full truncate border-s-2 py-1 pe-2 text-start text-caption",
+                    "transition-colors duration-fast ease-standard motion-reduce:transition-none",
+                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring",
+                    item.id === activeId
+                      ? "border-s-primary font-medium text-foreground"
+                      : "border-s-transparent text-muted-foreground hover:border-s-border-strong hover:text-foreground",
+                    actions && "pe-8",
+                  )}
+                  style={{ paddingInlineStart: `${(item.level - minLevel) * 0.875 + 0.75}rem` }}
+                >
+                  {item.text}
+                </button>
+                {actions ? (
+                  <span className="absolute end-0.5 top-1/2 -translate-y-1/2 opacity-0 transition-opacity duration-fast ease-standard focus-within:opacity-100 group-hover/outline-item:opacity-100 has-[[aria-pressed=true]]:opacity-100 motion-reduce:transition-none">
+                    {actions}
+                  </span>
+                ) : null}
+              </li>
+            );
+          })}
+        </ul>
+        {items.length === 0 ? (
+          <p className="px-2 py-1 text-caption text-muted-foreground">No headings yet.</p>
+        ) : null}
+      </nav>
+    );
+  },
+);

package/src/markdown-outline/index.ts

@@ -0,0 +1,2 @@
+export { parseMarkdownOutline, type MarkdownOutlineItem } from "./markdown-outline";
+export { DocumentOutline, useMarkdownOutline, type DocumentOutlineProps } from "./document-outline";

package/src/markdown-outline/markdown-outline.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+
+import { parseMarkdownOutline } from "./markdown-outline";
+
+const DOC = `---
+title: Plan
+---
+# Reporting migration plan
+
+Intro text.
+
+## Phase overview
+
+\`\`\`md
+# not a heading (fenced)
+\`\`\`
+
+### Discovery & *catalog*
+
+## Phase overview
+`;
+
+describe("parseMarkdownOutline", () => {
+  it("extracts headings with levels and stripped-source lines", () => {
+    const items = parseMarkdownOutline(DOC);
+    expect(items.map((i) => [i.level, i.text])).toEqual([
+      [1, "Reporting migration plan"],
+      [2, "Phase overview"],
+      [3, "Discovery & catalog"],
+      [2, "Phase overview"],
+    ]);
+    // Line 1 of the STRIPPED body is the H1 (frontmatter removed).
+    expect(items[0]!.line).toBe(1);
+  });
+
+  it("skips headings inside fenced code blocks", () => {
+    expect(parseMarkdownOutline(DOC).some((i) => i.text.includes("not a heading"))).toBe(false);
+  });
+
+  it("dedupes repeated slugs", () => {
+    const ids = parseMarkdownOutline(DOC).map((i) => i.id);
+    expect(ids).toContain("phase-overview");
+    expect(ids).toContain("phase-overview-1");
+  });
+
+  it("returns [] for heading-free documents", () => {
+    expect(parseMarkdownOutline("just text\n\nmore text")).toEqual([]);
+  });
+});

package/src/markdown-outline/markdown-outline.ts

@@ -0,0 +1,60 @@
+/**
+ * Markdown outline extraction (#L6) — the pure half of `DocumentOutline`.
+ *
+ * `parseMarkdownOutline` walks ATX headings (`#` … `######`) outside fenced
+ * code blocks and returns the document outline. Line numbers are 1-based and
+ * relative to the frontmatter-STRIPPED body — the same coordinate space as the
+ * `data-sourcepos` attributes `MarkdownPreview` stamps on rendered blocks, so
+ * outline → block lookup is a direct equality on the start line.
+ */
+import { parseFrontmatter } from "../lib/markdown/frontmatter";
+import { plainText, slugifyHeading, uniqueSlug } from "../lib/markdown/slugify";
+
+export interface MarkdownOutlineItem {
+  /** Stable slug (GitHub-style, deduped with `-n` suffixes). */
+  id: string;
+  /** Plain heading text (inline markdown stripped). */
+  text: string;
+  /** Heading level 1–6. */
+  level: 1 | 2 | 3 | 4 | 5 | 6;
+  /** 1-based line in the frontmatter-stripped source (matches `data-sourcepos`). */
+  line: number;
+}
+
+const HEADING_RE = /^(#{1,6})\s+(.*?)\s*#*\s*$/;
+const FENCE_RE = /^(```|~~~)/;
+
+export function parseMarkdownOutline(markdown: string): MarkdownOutlineItem[] {
+  let body = markdown;
+  try {
+    body = parseFrontmatter(markdown).content;
+  } catch {
+    // Transient-invalid frontmatter while typing — outline the raw source.
+  }
+  const lines = body.split("\n");
+  const items: MarkdownOutlineItem[] = [];
+  const used = new Map<string, number>();
+  let inFence = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (FENCE_RE.test(line.trimStart())) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const match = HEADING_RE.exec(line);
+    if (!match) continue;
+    const text = plainText(match[2] ?? "");
+    if (!text) continue;
+    const base = slugifyHeading(text);
+    const id = uniqueSlug(base, used);
+    items.push({
+      id,
+      text,
+      level: match[1]!.length as MarkdownOutlineItem["level"],
+      line: i + 1,
+    });
+  }
+  return items;
+}

package/src/markdown-preview/code-fence.tsx

@@ -0,0 +1,193 @@
+"use client";
+
+/**
+ * CodeFence — the highlighted non-mermaid code fence inside MarkdownPreview.
+ *
+ * Highlighting rides on the SAME engine the rest of the workspace already
+ * ships (`@streamdown/code`, Streamdown's shiki plugin — cached highlighters,
+ * sync-after-first-tokenize), but the theme is a shiki **CSS-variables theme**:
+ * every token color resolves to a `var(--md-code-*)` reference that this
+ * component maps onto the semantic tokens below. One theme, correct in every
+ * `data-theme` (light, dark, …) — no per-theme shiki theme, no raw
+ * colors, and a runtime theme switch recolors already-tokenized code for free.
+ *
+ * Until shiki finishes loading (or for a fence with no language tag) the raw
+ * fence text renders as before — highlighting is a progressive enhancement.
+ */
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { code as codeHighlighter } from "@streamdown/code";
+import {
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type HTMLAttributes,
+  type ReactNode,
+} from "react";
+import type { BundledLanguage, ThemedToken, TokensResult } from "shiki";
+import { createCssVariablesTheme } from "shiki";
+
+import { CopyButton } from "../copy-button";
+
+/** Extract the fence language from react-markdown's `language-*` className. */
+export function fenceLanguage(className?: string): string | undefined {
+  return /\blanguage-([\w+#.-]+)\b/.exec(className ?? "")?.[1];
+}
+
+/**
+ * One shiki theme for BOTH slots (the plugin API is [light, dark]): colors are
+ * pure CSS-variable references, so the active `data-theme` decides the actual
+ * values — both slots resolve identically by construction.
+ */
+const cssVariablesTheme = createCssVariablesTheme({
+  name: "brand-tokens",
+  variablePrefix: "--md-code-",
+  fontStyle: true,
+});
+const SHIKI_THEMES: [typeof cssVariablesTheme, typeof cssVariablesTheme] = [
+  cssVariablesTheme,
+  cssVariablesTheme,
+];
+
+/**
+ * The `--md-code-*` seams mapped onto semantic tokens (scoped to the fence, so
+ * nothing leaks into `themes.css`). Chart tokens carry the categorical hues —
+ * they are the only themed accent ramp guaranteed to exist in every theme.
+ */
+const SHIKI_TOKEN_VARS = cn(
+  "[--md-code-foreground:var(--foreground)]",
+  "[--md-code-background:transparent]",
+  "[--md-code-token-comment:var(--muted-foreground)]",
+  "[--md-code-token-constant:var(--chart-1)]",
+  "[--md-code-token-function:var(--chart-3)]",
+  "[--md-code-token-keyword:var(--chart-4)]",
+  "[--md-code-token-link:var(--primary)]",
+  "[--md-code-token-parameter:var(--chart-5)]",
+  "[--md-code-token-punctuation:var(--muted-foreground)]",
+  "[--md-code-token-string-expression:var(--chart-2)]",
+  "[--md-code-token-string:var(--chart-2)]",
+);
+
+// Shiki encodes font style as bitflags: 1 = italic, 2 = bold, 4 = underline.
+const hasFontFlag = (fontStyle: number | undefined, flag: number) =>
+  ((fontStyle ?? 0) & flag) === flag;
+
+function tokenStyle(token: ThemedToken): CSSProperties {
+  return {
+    // htmlStyle.color carries the theme var; token.color is the fallback path.
+    color: (token.htmlStyle as Record<string, string> | undefined)?.color ?? token.color,
+    fontStyle: hasFontFlag(token.fontStyle, 1) ? "italic" : undefined,
+    fontWeight: hasFontFlag(token.fontStyle, 2) ? "bold" : undefined,
+    textDecoration: hasFontFlag(token.fontStyle, 4) ? "underline" : undefined,
+  };
+}
+
+/**
+ * Tokenize via the shared plugin. Returns `null` until the highlighter is
+ * ready (first render of a language) — cached fences resolve synchronously.
+ */
+function useHighlightedTokens(codeText: string, language: string | undefined) {
+  const [result, setResult] = useState<TokensResult | null>(null);
+  const keyRef = useRef({ codeText, language });
+
+  // Invalidate stale tokens synchronously during render (no flash of the
+  // previous fence's tokens when the source changes).
+  if (keyRef.current.codeText !== codeText || keyRef.current.language !== language) {
+    keyRef.current = { codeText, language };
+    setResult(null);
+  }
+
+  useEffect(() => {
+    if (!language) return undefined; // no language tag — keep the plain text
+    let cancelled = false;
+    const sync = codeHighlighter.highlight(
+      // Unknown languages fall back to "text" inside the plugin.
+      { code: codeText, language: language as BundledLanguage, themes: SHIKI_THEMES },
+      (r) => {
+        if (!cancelled) setResult(r);
+      },
+    );
+    if (sync && !cancelled) setResult(sync);
+    return () => {
+      cancelled = true;
+    };
+  }, [codeText, language]);
+
+  return result;
+}
+
+export interface CodeFenceProps extends HTMLAttributes<HTMLElement> {
+  /** Raw fence text (trailing newline already stripped). */
+  codeText: string;
+  /** The fence's language tag (` ```ts `), if any. */
+  language?: string;
+  /** This fence contains the active in-document search hit. */
+  searchActive?: boolean;
+  /** Fallback content (the un-highlighted fence) while shiki loads. */
+  children?: ReactNode;
+}
+
+export function CodeFence({
+  codeText,
+  language,
+  searchActive,
+  className,
+  children,
+  ...props
+}: CodeFenceProps) {
+  const tokens = useHighlightedTokens(codeText, language)?.tokens ?? null;
+
+  return (
+    <div
+      data-code-fence={language ?? ""}
+      className={cn("group/code-fence relative my-3", className)}
+      {...props}
+    >
+      <pre
+        data-search-active={searchActive ? "" : undefined}
+        className={cn(
+          "!my-0 overflow-x-auto rounded-md p-3 font-mono text-code",
+          SHIKI_TOKEN_VARS,
+          searchActive ? "bg-primary/10" : "bg-surface-muted",
+        )}
+      >
+        {tokens ? (
+          <code>
+            {tokens.map((line, lineIdx) => (
+              // Lines are positionally stable for a given source string (the
+              // whole list is rebuilt when `codeText` changes).
+              <span key={`line-${lineIdx}`} className="block">
+                {line.length === 0
+                  ? "\n"
+                  : line.map((token, tokenIdx) => (
+                      <span key={`token-${lineIdx}-${tokenIdx}`} style={tokenStyle(token)}>
+                        {token.content}
+                      </span>
+                    ))}
+              </span>
+            ))}
+          </code>
+        ) : (
+          children
+        )}
+      </pre>
+
+      <div className="absolute end-2 top-2 flex items-center gap-1">
+        <CopyButton
+          value={codeText}
+          label={false}
+          size="icon-sm"
+          className="opacity-0 transition-opacity duration-fast ease-standard focus-visible:opacity-100 group-hover/code-fence:opacity-100 motion-reduce:transition-none"
+        />
+        {language ? (
+          <span
+            aria-hidden="true"
+            className="pointer-events-none select-none rounded-sm bg-surface-muted px-1.5 py-0.5 font-mono text-meta text-muted-foreground"
+          >
+            {language}
+          </span>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/markdown-preview/index.ts

@@ -0,0 +1,8 @@
+export {
+  MarkdownPreview,
+  type MarkdownPreviewProps,
+  type MarkdownHeadingInfo,
+  type MarkdownUrlKind,
+  type MarkdownAnnotation,
+  type MarkdownAnnotationKind,
+} from "./markdown-preview";

package/src/markdown-preview/markdown-preview-academic.stories.tsx

@@ -0,0 +1,203 @@
+// KaTeX styling — consumers must import this once at their app entry. The story
+// imports it so the `Math` stories render correctly in Storybook.
+import "katex/dist/katex.min.css";
+
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+
+import { MarkdownPreview } from "./markdown-preview";
+import type { CitationData } from "../markdown-academic/citations";
+
+const meta = {
+  title: "Editor/MarkdownPreview/Academic",
+  component: MarkdownPreview,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The opt-in **academic layer** for `MarkdownPreview`: branded footnotes " +
+          "(`footnotes`), `$…$` / `$$…$$` math via KaTeX (`math`), Pandoc / Better-BibTeX " +
+          "citations + a generated bibliography (`resolveCitation`), and a generated `::toc` " +
+          "(`toc`). The BibTeX/CSL database, the math engine, and CSL formatting stay in the " +
+          "app — the library renders. Math requires the consumer to load KaTeX CSS once " +
+          '(`import "katex/dist/katex.min.css"`).',
+      },
+    },
+  },
+} satisfies Meta<typeof MarkdownPreview>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/* ------------------------------------------------------------------ */
+/* A small in-app citation database (would be BibTeX/CSL in real apps). */
+/* ------------------------------------------------------------------ */
+const CITES: Record<string, CitationData> = {
+  knuth1984: {
+    author: "Knuth",
+    year: 1984,
+    title: "Literate Programming",
+    container: "The Computer Journal",
+    doi: "10.1093/comjnl/27.2.97",
+  },
+  dijkstra1968: {
+    author: "Dijkstra",
+    year: 1968,
+    title: "Go To Statement Considered Harmful",
+    container: "Communications of the ACM",
+    url: "https://dl.acm.org/doi/10.1145/362929.362947",
+  },
+  turing1936: {
+    author: "Turing",
+    year: 1936,
+    title: "On Computable Numbers",
+    container: "Proc. London Math. Soc.",
+  },
+};
+const resolveCitation = (key: string): CitationData | null => CITES[key] ?? null;
+
+export const Footnotes: Story = {
+  args: {
+    footnotes: true,
+    children: `# Field notes
+
+The estate ran on nine legacy dashboards.[^scope] Consolidation cut that to one.[^win]
+
+Both numbers were verified against the warehouse before sign-off.[^scope]
+
+[^scope]: Counted from the migration manifest — see the [scope sheet](https://example.com/scope).
+[^win]: Post-launch audit, 2026-Q1.`,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(
+      await canvas.findByRole("region", { name: "Footnotes" }, { timeout: 8000 }),
+    ).toBeVisible();
+  },
+};
+
+export const Math: Story = {
+  args: {
+    math: true,
+    children: `# Cost model
+
+The unit cost is $c = \\frac{f + v\\,n}{n}$, fixed cost $f$ amortized over $n$ runs.
+
+Total spend over the window:
+
+$$
+S = \\sum_{i=1}^{N} c_i n_i = f N + v \\sum_{i=1}^{N} n_i
+$$
+
+So the marginal cost approaches $v$ as $n \\to \\infty$.`,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByRole("heading", { name: "Cost model" }, { timeout: 8000 });
+    await expect(canvasElement.querySelectorAll('[role="math"]').length).toBeGreaterThan(0);
+  },
+};
+
+export const CitationsNumeric: Story = {
+  name: "Citations — numeric + bibliography",
+  args: {
+    resolveCitation,
+    children: `# Related work
+
+Literate programming [@knuth1984] reframed source as exposition, building on the
+structured-programming turn [@dijkstra1968]. The theoretical floor was set decades
+earlier [@turing1936, p. 230]. See also [@knuth1984; @dijkstra1968].
+
+::bibliography`,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(
+      await canvas.findByRole("region", { name: "References" }, { timeout: 8000 }),
+    ).toBeVisible();
+  },
+};
+
+export const CitationsAuthorYear: Story = {
+  name: "Citations — author-year",
+  args: {
+    resolveCitation,
+    citationStyle: "author-year",
+    children: `Knuth's literate programming [@knuth1984] inverts the usual order — see also
+the earlier argument [-@dijkstra1968] for structure.
+
+::references`,
+  },
+};
+
+export const TableOfContents: Story = {
+  name: "Generated TOC",
+  args: {
+    toc: true,
+    children: `::toc
+
+# Architecture
+
+Overview prose.
+
+## Data layer
+
+How storage works.
+
+## Service layer
+
+How services compose.
+
+# Operations
+
+### Monitoring
+
+Dashboards and alerts.`,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const nav = await canvas.findByRole("navigation", { name: "Contents" }, { timeout: 8000 });
+    await expect(within(nav).getAllByRole("link").length).toBeGreaterThan(1);
+  },
+};
+
+/**
+ * Everything together — the shape of a short research note: a TOC, inline math,
+ * a footnote, citations, and a generated bibliography in one document.
+ */
+export const AcademicPaper: Story = {
+  args: {
+    footnotes: true,
+    math: true,
+    toc: true,
+    resolveCitation,
+    children: `::toc
+
+# Amortizing fixed cost
+
+We model per-run cost as $c = \\frac{f + v n}{n}$, following the structured-cost
+argument [@dijkstra1968].[^model] As $n \\to \\infty$, $c \\to v$.
+
+$$
+S = f N + v \\sum_{i=1}^{N} n_i
+$$
+
+## Prior art
+
+Literate exposition of such models traces to Knuth [@knuth1984].
+
+::bibliography
+
+[^model]: Fixed cost $f$ is treated as constant across the window.`,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(
+      await canvas.findByRole("navigation", { name: "Contents" }, { timeout: 8000 }),
+    ).toBeVisible();
+    await expect(canvas.getByRole("region", { name: "References" })).toBeVisible();
+    await expect(canvas.getByRole("region", { name: "Footnotes" })).toBeVisible();
+  },
+};