@elabs-ai/components-editor 4.0.0

package/src/markdown-academic/index.ts

@@ -0,0 +1,32 @@
+/**
+ * `markdown-academic` — the opt-in academic layer for `MarkdownPreview`:
+ * footnotes, citations + bibliography, math (KaTeX), and a generated TOC. Each
+ * piece is enabled by a prop on `MarkdownPreview` (`footnotes` / `resolveCitation`
+ * / `math` / `toc`); the standalone components + types below are exported for
+ * direct composition and consumer typing.
+ *
+ * The remark transforms + tag constants are wired internally by `MarkdownPreview`
+ * and are intentionally NOT part of the public surface (drive them with the props).
+ */
+
+// Citations + bibliography.
+export {
+  Bibliography,
+  collectCitations,
+  type BibliographyProps,
+  type CitationData,
+  type CitationStyle,
+  type CiteItem,
+  type CollectedCitations,
+  type ResolveCitation,
+  type ResolvedCitation,
+} from "./citations";
+
+// Math (KaTeX) — standalone renderers for direct use.
+export { MathBlock, MathInline, type MathProps } from "./math";
+
+// Footnotes — the branded definition section (standalone).
+export { FootnoteList, type FootnoteListProps } from "./footnotes";
+
+// Table of contents.
+export { TableOfContents, type TableOfContentsProps } from "./toc";

package/src/markdown-academic/math.tsx

@@ -0,0 +1,163 @@
+"use client";
+
+/**
+ * Math via `remark-math` + KaTeX (`$inline$`, and `$$block$$` on its own lines).
+ *
+ * `remark-math` parses `$…$` / `$$…$$` into `inlineMath` / `math` mdast nodes,
+ * which have NO mdast→hast handler (they'd otherwise degrade to literal text). So
+ * `remarkBrandMath` rewrites them into our own `brand-math` / `brand-math-inline`
+ * elements carrying the raw TeX, and the React renderers turn that into KaTeX.
+ *
+ * SECURITY: the TeX is untrusted input, so KaTeX runs with `trust: false` (blocks
+ * `\href`/`\url`/class injection), a bounded `maxExpand` (caps macro expansion —
+ * the `\def`-bomb DoS guard), and `throwOnError: false` (a bad expression renders
+ * a contained error, never crashes the page). a11y: `output: "htmlAndMathml"`
+ * emits MathML (read by assistive tech) alongside the visual HTML.
+ */
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import katex from "katex";
+import { useMemo, type HTMLAttributes } from "react";
+import { visit } from "unist-util-visit";
+
+/** Block math element (`$$…$$`). */
+export const MATH_BLOCK_TAG = "brand-math";
+/** Inline math element (`$…$`). */
+export const MATH_INLINE_TAG = "brand-math-inline";
+/** hast property carrying the raw TeX (rendered as `data-tex`). */
+export const MATH_PROP = "dataTex";
+const MATH_ATTR = "data-tex";
+
+/** Cap macro expansion — bounds `\def`-style expansion against untrusted input. */
+const MAX_EXPAND = 1000;
+
+interface MdNode {
+  type: string;
+  value?: string;
+  children?: MdNode[];
+  data?: { hName?: string; hProperties?: Record<string, unknown> };
+}
+
+/**
+ * Rewrite `inlineMath` / `math` (from remark-math) into branded elements carrying
+ * the raw TeX. Runs AFTER `remarkMath` in the plugin array.
+ */
+export function remarkBrandMath() {
+  return (tree: unknown) => {
+    visit(tree as never, (node: MdNode, index: number | undefined, parent: MdNode | undefined) => {
+      if (node.type !== "inlineMath" && node.type !== "math") return;
+      if (!parent?.children || index == null) return;
+      const display = node.type === "math";
+      const tex = typeof node.value === "string" ? node.value : "";
+      parent.children[index] = {
+        type: display ? "brandMathBlock" : "brandMathInline",
+        data: {
+          hName: display ? MATH_BLOCK_TAG : MATH_INLINE_TAG,
+          hProperties: { [MATH_PROP]: tex },
+        },
+      };
+    });
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* React renderers                                                      */
+/* ------------------------------------------------------------------ */
+
+type TagProps = { node?: unknown; children?: React.ReactNode } & Record<string, unknown>;
+
+function readTex(rest: TagProps): string {
+  return (rest[MATH_ATTR] as string | undefined) ?? (rest[MATH_PROP] as string | undefined) ?? "";
+}
+
+/** Render TeX to a KaTeX HTML string (safe options); never throws. */
+function renderKatex(tex: string, displayMode: boolean): { html: string; error: boolean } {
+  try {
+    return {
+      html: katex.renderToString(tex, {
+        displayMode,
+        throwOnError: false,
+        errorColor: "var(--destructive)",
+        trust: false,
+        maxExpand: MAX_EXPAND,
+        strict: "ignore",
+        output: "htmlAndMathml",
+      }),
+      error: false,
+    };
+  } catch {
+    return { html: "", error: true };
+  }
+}
+
+export interface MathProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+  /** Raw TeX source. */
+  tex: string;
+}
+
+/** Inline math (`$…$`) → KaTeX, in the text flow. */
+export function MathInline({ tex, className, ...props }: MathProps) {
+  const { html, error } = useMemo(() => renderKatex(tex, false), [tex]);
+  if (error) {
+    return (
+      <code
+        className={cn("text-destructive-text", className)}
+        aria-label={`Math (could not render): ${tex}`}
+        title="Could not render math"
+        {...props}
+      >
+        {tex}
+      </code>
+    );
+  }
+  return (
+    <span
+      role="math"
+      // The raw TeX is a universally-readable fallback name for AT that does not
+      // process the embedded MathML; MathML-capable AT reads the MathML instead.
+      aria-label={tex}
+      className={cn("inline-block align-middle", className)}
+      // KaTeX output is generated with trust:false + bounded maxExpand (safe).
+      dangerouslySetInnerHTML={{ __html: html }}
+      {...props}
+    />
+  );
+}
+
+/** Block math (`$$…$$`) → centered display KaTeX. */
+export function MathBlock({ tex, className, ...props }: MathProps) {
+  const { html, error } = useMemo(() => renderKatex(tex, true), [tex]);
+  if (error) {
+    return (
+      <pre
+        className={cn(
+          "overflow-x-auto rounded-md bg-surface-muted p-3 text-destructive-text",
+          className,
+        )}
+        aria-label={`Math (could not render): ${tex}`}
+        title="Could not render math"
+        {...props}
+      >
+        <code>{tex}</code>
+      </pre>
+    );
+  }
+  return (
+    <div
+      role="math"
+      aria-label={tex}
+      className={cn("my-3 overflow-x-auto text-center", className)}
+      dangerouslySetInnerHTML={{ __html: html }}
+      {...props}
+    />
+  );
+}
+
+/** Components-map renderer for the inline math element. */
+export function MathInlineTag({ node: _n, children: _c, ...rest }: TagProps) {
+  return <MathInline tex={readTex(rest)} />;
+}
+
+/** Components-map renderer for the block math element. */
+export function MathBlockTag({ node: _n, children: _c, ...rest }: TagProps) {
+  return <MathBlock tex={readTex(rest)} />;
+}

package/src/markdown-academic/toc.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+/**
+ * Generated table of contents — an in-flow `::toc` block.
+ *
+ * Reuses `parseMarkdownOutline` (the same heading extractor `DocumentOutline`
+ * uses — no second parser) for slugs + levels, and renders a quiet nav list of
+ * same-page anchor links. `MarkdownPreview` provides the outline through
+ * `TocProvider`; it also stamps the matching `id` on each rendered heading
+ * (`useHeadingId`) so the links resolve.
+ */
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { createContext, forwardRef, useContext, type HTMLAttributes } from "react";
+
+import type { MarkdownOutlineItem } from "../markdown-outline";
+
+// Per-depth indent on the standard spacing scale (statically scannable so Tailwind
+// keeps the classes). Index = heading depth relative to the shallowest in view.
+const INDENT = ["ps-0", "ps-3", "ps-6", "ps-9", "ps-12", "ps-12"] as const;
+
+interface TocState {
+  items: MarkdownOutlineItem[];
+  /** Heading slug keyed by 1-based start line (frontmatter-stripped coords). */
+  idByLine: Map<number, string>;
+}
+
+const TocContext = createContext<TocState | null>(null);
+
+export interface TocProviderProps {
+  items: MarkdownOutlineItem[];
+  children: React.ReactNode;
+}
+
+export function TocProvider({ items, children }: TocProviderProps) {
+  const idByLine = new Map<number, string>();
+  for (const it of items) idByLine.set(it.line, it.id);
+  return <TocContext.Provider value={{ items, idByLine }}>{children}</TocContext.Provider>;
+}
+
+/** The heading `id` for a 1-based source line, or `undefined`. */
+export function useHeadingId(line: number | undefined): string | undefined {
+  const ctx = useContext(TocContext);
+  if (line == null || !ctx) return undefined;
+  return ctx.idByLine.get(line);
+}
+
+export interface TableOfContentsProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+  /** Heading outline; defaults to the outline collected by `MarkdownPreview`. */
+  items?: MarkdownOutlineItem[];
+  /** Section heading label. Default `"Contents"`. */
+  title?: string;
+  /** Deepest heading level to include (1–6). Default 3. */
+  maxLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+}
+
+/**
+ * Quiet generated TOC. Standalone with an explicit `items` array, or fed from the
+ * preview context inside a `::toc` block. Indentation tracks heading depth; no
+ * fill or border — the indent + links are the only gestures.
+ */
+export const TableOfContents = forwardRef<HTMLElement, TableOfContentsProps>(
+  function TableOfContents({ items, title = "Contents", maxLevel = 3, className, ...props }, ref) {
+    const ctx = useContext(TocContext);
+    const source = items ?? ctx?.items ?? [];
+    const list = source.filter((it) => it.level <= maxLevel);
+    if (list.length === 0) return null;
+
+    const minLevel = Math.min(...list.map((it) => it.level));
+
+    return (
+      <nav ref={ref} aria-label={title} className={cn("my-4 text-meta", className)} {...props}>
+        <p className="mb-2 font-medium text-muted-foreground">{title}</p>
+        <ol className="space-y-1">
+          {list.map((it) => (
+            <li key={it.id} className={INDENT[Math.min(it.level - minLevel, INDENT.length - 1)]}>
+              <a
+                href={`#${it.id}`}
+                className="text-muted-foreground underline hover:text-foreground hover:underline focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              >
+                {it.text}
+              </a>
+            </li>
+          ))}
+        </ol>
+      </nav>
+    );
+  },
+);

package/src/markdown-editor/completions/completions-menu.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+/**
+ * CompletionMenu — the token-styled listbox the WYSIWYG completions widget
+ * renders at the caret (`completions-widget.tsx`). Deliberately simpler than
+ * `../slash/slash-menu.tsx`'s `SlashMenu`: `EditorCompletionItem` carries only
+ * `label`/`detail`/`insertText` (no groups/icons), so there is nothing to group.
+ * Same visual grammar (bg-popover, accent selection) for consistency with the
+ * slash popup and Monaco's own themed suggest widget.
+ */
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { forwardRef, type HTMLAttributes } from "react";
+
+import type { EditorCompletionItem } from "../../lib/editor-completions";
+
+export interface CompletionMenuProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+  /** The candidates to show (already resolved by the provider(s)). */
+  items: EditorCompletionItem[];
+  /** Index of the highlighted candidate. */
+  activeIndex: number;
+  /** Called when a candidate is chosen (click or the plugin's Enter/Tab). */
+  onSelect: (index: number) => void;
+  /** DOM id prefix so each option id is stable + unique. */
+  idPrefix?: string;
+  /** Shown while no candidates have resolved yet (or none matched). */
+  emptyLabel?: string;
+}
+
+/** Build the stable DOM id for an option element. */
+export function completionOptionId(idPrefix: string, index: number): string {
+  return `${idPrefix}-${index}`;
+}
+
+export const CompletionMenu = forwardRef<HTMLDivElement, CompletionMenuProps>(
+  function CompletionMenu(
+    {
+      items,
+      activeIndex,
+      onSelect,
+      idPrefix = "brand-completions",
+      emptyLabel = "No suggestions",
+      className,
+      ...props
+    },
+    ref,
+  ) {
+    return (
+      <div
+        ref={ref}
+        role="listbox"
+        aria-label="Suggestions"
+        className={cn(
+          "max-h-[min(280px,50vh)] w-64 overflow-y-auto overflow-x-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-ring-md",
+          className,
+        )}
+        {...props}
+      >
+        {items.length === 0 ? (
+          <div className="px-2 py-3 text-center text-caption text-muted-foreground">
+            {emptyLabel}
+          </div>
+        ) : (
+          items.map((item, index) => {
+            const selected = index === activeIndex;
+            return (
+              <div
+                key={`${item.label}-${String(index)}`}
+                id={completionOptionId(idPrefix, index)}
+                role="option"
+                aria-selected={selected}
+                data-selected={selected ? "true" : undefined}
+                // The editor keeps focus — select on mousedown (before the editor
+                // would steal focus back), mirroring `slash-menu.tsx`.
+                onMouseDown={(e) => {
+                  e.preventDefault();
+                  onSelect(index);
+                }}
+                className={cn(
+                  "flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-body outline-none transition-colors duration-fast",
+                  "data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground",
+                )}
+              >
+                <span className="flex min-w-0 flex-col">
+                  <span className="truncate">{item.label}</span>
+                  {item.detail ? (
+                    <span className="truncate text-meta text-muted-foreground">{item.detail}</span>
+                  ) : null}
+                </span>
+              </div>
+            );
+          })
+        )}
+      </div>
+    );
+  },
+);