@elabs-ai/components-editor 4.0.0

package/src/markdown-editor/slash/source-slash-trigger.ts

@@ -0,0 +1,46 @@
+/**
+ * Typed-`/` trigger detection for the Monaco source pane (the conflict-free way
+ * to open the brand block menu — no keybinding, mirrors the WYSIWYG `/` trigger).
+ *
+ * Pure + Monaco-free so it unit-tests without the engine. The workspace feeds it
+ * the just-edited line + the column the `/` landed on (from a Monaco content
+ * change) and, when it's a valid trigger spot, gets back the model range of that
+ * `/` so the menu can replace it with the inserted block (or delete it on cancel).
+ *
+ * A `/` is a valid trigger only at a textblock start (column 1) or right after
+ * whitespace — so a `/` inside a word, a URL, or a path (`a/b`, `http://`) never
+ * hijacks typing, matching the WYSIWYG `triggerAllowed` rule.
+ */
+
+/** A Monaco `IRange`-shaped span (kept structural so this module imports no monaco). */
+export interface SlashTriggerRange {
+  startLineNumber: number;
+  startColumn: number;
+  endLineNumber: number;
+  endColumn: number;
+}
+
+/**
+ * Given the 1-based `line` number, the FULL line content AFTER the `/` was typed,
+ * and the 1-based `slashColumn` the `/` now occupies, return the range covering
+ * that `/` when it is a valid trigger — otherwise `null`.
+ */
+export function slashTriggerRange(
+  line: number,
+  lineContent: string,
+  slashColumn: number,
+): SlashTriggerRange | null {
+  // Sanity: the character at the reported column must actually be the `/`.
+  if (lineContent.charAt(slashColumn - 1) !== "/") return null;
+  // Allowed at the very start of the line, or immediately after whitespace.
+  if (slashColumn > 1) {
+    const before = lineContent.charAt(slashColumn - 2);
+    if (!/\s/.test(before)) return null;
+  }
+  return {
+    startLineNumber: line,
+    startColumn: slashColumn,
+    endLineNumber: line,
+    endColumn: slashColumn + 1,
+  };
+}

package/src/markdown-editor/table-view.tsx

@@ -0,0 +1,249 @@
+"use client";
+
+/**
+ * Table control overlay for the Milkdown WYSIWYG editor.
+ *
+ * Mechanism: a **contextual toolbar** rendered as a ProseMirror plugin view
+ * (via `@prosemirror-adapter/react`'s `usePluginViewFactory`). When the
+ * selection is inside a GFM table, a token-styled button bar appears at the
+ * bottom of the editor's wrapper offering add/remove row and column ops.
+ *
+ * Design choice — why NOT a `$view` node-view:
+ *   A content-replacing `$view` for the GFM table conflicts with gfm's
+ *   `columnResizingPlugin` and `tableEditingPlugin` decorations (both rewrite
+ *   the DOM directly), breaking cell selection highlighting and column handles.
+ *   The contextual toolbar avoids all decoration conflicts while delivering the
+ *   full feature surface (add/remove row+col, Tab nav, lossless round-trip,
+ *   token look, keyboard a11y). GFM's `tableKeymap` already binds Tab →
+ *   NextCell and Shift+Tab → PrevCell so no extra keymap plugin is needed.
+ *
+ * Focus safety:
+ *   Plugin views mount OUTSIDE `contentEditable` (ProseMirror appends them to
+ *   the editor wrapper). Buttons use `onMouseDown={preventDefault}` so clicks
+ *   never steal focus from the editing surface.
+ *
+ * Command wiring:
+ *   All ops call the existing gfm commands (addRowAfterCommand, etc.) via
+ *   `commandsCtx.call()`. The GFM schema + serializer are never replaced, so
+ *   GFM round-trip fidelity is structurally guaranteed.
+ */
+
+import type { CmdKey } from "@milkdown/kit/core";
+import type { Ctx, MilkdownPlugin } from "@milkdown/kit/ctx";
+import { commandsCtx } from "@milkdown/kit/core";
+import {
+  addColAfterCommand,
+  addColBeforeCommand,
+  addRowAfterCommand,
+  addRowBeforeCommand,
+  deleteSelectedCellsCommand,
+} from "@milkdown/kit/preset/gfm";
+import { Plugin, PluginKey } from "@milkdown/kit/prose/state";
+import type { EditorView } from "@milkdown/kit/prose/view";
+import { $prose } from "@milkdown/kit/utils";
+import { isInTable } from "@milkdown/kit/prose/tables";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { usePluginViewContext } from "@prosemirror-adapter/react";
+import type { usePluginViewFactory } from "@prosemirror-adapter/react";
+
+// ---------------------------------------------------------------------------
+// Ctx bridge
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-instance Ctx registry. The `$prose` plugin's `view(editorView)` records
+ * THIS editor's live Milkdown `Ctx` keyed by its ProseMirror view; the React
+ * toolbar reads it back via the view it gets from `usePluginViewContext`. Keyed
+ * by the view (NOT a module singleton) so multiple `MarkdownEditor`s on one page
+ * — a Storybook autodocs page, a split workspace — each dispatch to the correct
+ * instance. Entries are released with their view (WeakMap GC).
+ */
+const ctxByView = new WeakMap<EditorView, Ctx>();
+
+/** Call a gfm command key on the editor that owns `view`. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function dispatchCommand(view: EditorView, key: CmdKey<any>): void {
+  const ctx = ctxByView.get(view);
+  if (!ctx) return;
+  try {
+    ctx.get(commandsCtx).call(key);
+  } catch {
+    // Editor may be mid-destroy; swallow gracefully.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Plugin key
+// ---------------------------------------------------------------------------
+
+const tableControlsKey = new PluginKey<boolean>("brand-table-controls");
+
+// ---------------------------------------------------------------------------
+// Toolbar React component
+// ---------------------------------------------------------------------------
+
+interface ToolbarButtonProps {
+  onClick: () => void;
+  ariaLabel: string;
+  title: string;
+  children: React.ReactNode;
+  variant?: "default" | "destructive";
+}
+
+function ToolbarButton({
+  onClick,
+  ariaLabel,
+  title,
+  children,
+  variant = "default",
+}: ToolbarButtonProps) {
+  return (
+    <button
+      type="button"
+      aria-label={ariaLabel}
+      title={title}
+      // Keep focus in the editor — a mousedown without preventDefault would
+      // blur the ProseMirror view before the click fires.
+      onMouseDown={(e) => e.preventDefault()}
+      onClick={onClick}
+      className={cn(
+        "inline-flex h-7 items-center gap-1 rounded px-2 text-caption font-medium",
+        "border border-border-strong",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        "transition-colors duration-fast ease-standard motion-reduce:transition-none",
+        variant === "destructive"
+          ? "bg-background text-destructive hover:bg-destructive/10"
+          : "bg-background text-foreground hover:bg-surface-muted",
+      )}
+    >
+      {children}
+    </button>
+  );
+}
+
+/** Thin visual separator between button groups. */
+function ToolbarDivider() {
+  return <span aria-hidden="true" className="mx-0.5 h-4 w-px bg-border-strong" />;
+}
+
+/**
+ * The table controls toolbar.
+ *
+ * Rendered as a ProseMirror plugin view: ProseMirror mounts it into the
+ * editor's wrapper DOM (`view.dom.parentElement`) and calls `update()` on
+ * every state change — `usePluginViewContext` re-renders the React tree.
+ * Hidden when the cursor is not inside a table.
+ */
+function TableControlsView() {
+  const { view } = usePluginViewContext();
+  const inTable = isInTable(view.state);
+  const run = (key: Parameters<typeof dispatchCommand>[1]) => () => dispatchCommand(view, key);
+
+  if (!inTable) return null;
+
+  return (
+    <div
+      role="toolbar"
+      aria-label="Table controls"
+      className={cn(
+        "flex flex-wrap items-center gap-1 px-2 py-1.5",
+        "border-t border-border-strong bg-surface-muted",
+      )}
+    >
+      {/* Row group */}
+      <span className="mr-1 select-none text-caption text-muted-foreground">Row</span>
+      <ToolbarButton
+        ariaLabel="Add row above"
+        title="Add row above"
+        onClick={run(addRowBeforeCommand.key)}
+      >
+        ↑+
+      </ToolbarButton>
+      <ToolbarButton
+        ariaLabel="Add row below"
+        title="Add row below"
+        onClick={run(addRowAfterCommand.key)}
+      >
+        ↓+
+      </ToolbarButton>
+      <ToolbarButton
+        ariaLabel="Delete row"
+        title="Delete row"
+        variant="destructive"
+        onClick={run(deleteSelectedCellsCommand.key)}
+      >
+        ×row
+      </ToolbarButton>
+
+      <ToolbarDivider />
+
+      {/* Column group */}
+      <span className="mr-1 select-none text-caption text-muted-foreground">Col</span>
+      <ToolbarButton
+        ariaLabel="Add column left"
+        title="Add column left"
+        onClick={run(addColBeforeCommand.key)}
+      >
+        ←+
+      </ToolbarButton>
+      <ToolbarButton
+        ariaLabel="Add column right"
+        title="Add column right"
+        onClick={run(addColAfterCommand.key)}
+      >
+        →+
+      </ToolbarButton>
+      <ToolbarButton
+        ariaLabel="Delete column"
+        title="Delete column"
+        variant="destructive"
+        onClick={run(deleteSelectedCellsCommand.key)}
+      >
+        ×col
+      </ToolbarButton>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Exported factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the Milkdown plugin array for table controls.
+ *
+ * Call with `usePluginViewFactory()` from inside `<ProsemirrorAdapterProvider>`,
+ * then `.use(tableViewPlugins(pluginViewFactory))` on the editor chain.
+ *
+ * The signature matches the `directiveViewPlugins` convention: factory
+ * captured from the React adapter hook, plugin array returned for `.use()`.
+ */
+export function tableViewPlugins(
+  pluginViewFactory: ReturnType<typeof usePluginViewFactory>,
+): MilkdownPlugin[] {
+  return [
+    $prose((ctx) => {
+      // Build the ProseMirror PluginViewSpec from the adapter factory. This
+      // returns a `view(editorView) => PluginView` that ProseMirror calls to
+      // mount/update/destroy the React tree.
+      const makePluginView = pluginViewFactory({ component: TableControlsView });
+
+      return new Plugin({
+        key: tableControlsKey,
+        state: {
+          // Track whether the cursor is in a table (bool) as plugin state so
+          // ProseMirror knows when to trigger an `update()` on the plugin view.
+          init: (_cfg, state) => isInTable(state),
+          apply: (_tr, _prev, _old, state) => isInTable(state),
+        },
+        // Bind THIS editor's Ctx to THIS editor's view, so the toolbar's
+        // commands dispatch to the right instance when several editors share
+        // this module (autodocs page, split workspace).
+        view: (editorView) => {
+          ctxByView.set(editorView, ctx);
+          return makePluginView(editorView);
+        },
+      });
+    }) as unknown as MilkdownPlugin,
+  ];
+}

package/src/markdown-iteration/directive.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+/**
+ * The `:::iterate` / `:::pivot` directive bridge — turns a directive context
+ * (attributes + the captured raw body template) into an `IterationSpec`, and
+ * renders an `IterationBlock` with a recursion guard so a self-referential
+ * template can't loop forever (the transclusion depth-cap precedent).
+ */
+import { createContext, useContext, type ReactNode } from "react";
+
+import {
+  IterationBlock,
+  type EvaluateIteration,
+  type InterpolateTemplate,
+  type IterationLayout,
+  type IterationSpec,
+} from "./iteration";
+
+/** Max nesting depth for `:::iterate` inside an iterated cell. */
+export const MAX_ITERATION_DEPTH = 3;
+
+/** Current iteration nesting depth; 0 = top-level document. */
+const IterationDepthContext = createContext(0);
+
+const DEFAULT_LAYOUT: Record<"iterate" | "pivot", IterationLayout> = {
+  iterate: "stacked",
+  pivot: "matrix",
+};
+
+const LAYOUTS = new Set<IterationLayout>(["stacked", "grid", "matrix", "bento"]);
+
+/** Build an `IterationSpec` from a directive's name + attributes + raw body. */
+export function specFromDirective(
+  name: "iterate" | "pivot",
+  attributes: Record<string, string>,
+  rawBody: string | undefined,
+): IterationSpec {
+  const kind = name;
+  const layoutAttr = attributes.layout as IterationLayout | undefined;
+  const layout = layoutAttr && LAYOUTS.has(layoutAttr) ? layoutAttr : DEFAULT_LAYOUT[kind];
+  const columns = attributes.columns ? Number(attributes.columns) || undefined : undefined;
+  return {
+    kind,
+    layout,
+    template: rawBody ?? "",
+    as: attributes.as?.trim() || "item",
+    source: attributes.source,
+    rows: attributes.rows,
+    cols: attributes.cols,
+    columns,
+    attributes,
+  };
+}
+
+export interface IterationDirectiveProps {
+  spec: IterationSpec;
+  evaluate: EvaluateIteration;
+  interpolate?: InterpolateTemplate;
+  /** Render one cell's resolved markdown → node (a nested `MarkdownPreview`). */
+  renderCell: (markdown: string) => ReactNode;
+}
+
+/**
+ * Renders an `IterationBlock` one nesting level deeper, refusing to recurse past
+ * {@link MAX_ITERATION_DEPTH}. Cells (which mount nested `MarkdownPreview`s) read
+ * the incremented depth, so a nested `:::iterate` is bounded.
+ */
+export function IterationDirective({
+  spec,
+  evaluate,
+  interpolate,
+  renderCell,
+}: IterationDirectiveProps) {
+  const depth = useContext(IterationDepthContext);
+  if (depth >= MAX_ITERATION_DEPTH) {
+    return (
+      <div className="my-4 text-meta text-muted-foreground italic" data-iteration-too-deep="">
+        Iteration nested too deep — skipped.
+      </div>
+    );
+  }
+  return (
+    <IterationDepthContext.Provider value={depth + 1}>
+      <IterationBlock
+        spec={spec}
+        evaluate={evaluate}
+        interpolate={interpolate}
+        render={renderCell}
+      />
+    </IterationDepthContext.Provider>
+  );
+}

package/src/markdown-iteration/edit-context.ts

@@ -0,0 +1,56 @@
+"use client";
+
+/**
+ * The seam between an iteration node-view's `⋯` "Edit template…" affordance and
+ * the {@link IterationTemplateDialog} that fulfils it.
+ *
+ * Decoupled ON PURPOSE: the node-view (inside `MarkdownEditor`) must NOT import the
+ * dialog (which embeds a whole `MarkdownWorkspace` — a heavy, cyclic dependency).
+ * Instead the node-view emits an edit REQUEST through this context; the consumer
+ * (above the editor) renders the dialog and writes the result back via `onSave`.
+ * When no handler is provided, the `⋯` button is hidden and the template stays
+ * editable inline. This keeps `@elabs-ai/components-editor` a presentation layer — the app owns
+ * how/where the modal mounts.
+ */
+import { createContext } from "react";
+
+export interface IterationEditRequest {
+  /** Which directive asked to be edited. */
+  kind: "iterate" | "pivot";
+  /** The current template markdown (the node body, serialized). */
+  template: string;
+  /** Apply the edited template back to the node. */
+  onSave: (template: string) => void;
+  /**
+   * The directive's current attributes (value lists, bind name, layout) — present
+   * when the node-view supports GUIDED re-editing (A5). The
+   * `IterationBuilderProvider` reads these to reopen the builder with its data;
+   * the template-only `IterationTemplateProvider` ignores them.
+   */
+  attributes?: Record<string, string>;
+  /**
+   * Write back BOTH the attributes and the template (the guided builder path). When
+   * present it is preferred over {@link onSave} (which only rewrites the body).
+   */
+  onSaveData?: (next: { attributes: Record<string, string>; template: string }) => void;
+  /**
+   * Directly rewrite the node's attributes (e.g. the node-menu's "Change layout" /
+   * "Transpose" actions) without touching the template body. Additive (#223) —
+   * present alongside {@link onSave}/{@link onSaveData} for back-compat; a
+   * consumer-side surface (a future dialog action) can reach the same write the
+   * node-view's own menu uses.
+   */
+  onSetAttributes?: (attributes: Record<string, string>) => void;
+  /**
+   * Replace the ENTIRE directive node with plain markdown — e.g. the node-menu's
+   * "Convert to static" action (the evaluated, populated result). After this the
+   * node stops being a `:::iterate`/`:::pivot` directive. Additive (#223).
+   */
+  onReplaceWithMarkdown?: (markdown: string) => void;
+}
+
+/** A consumer handler that opens the template editor for a request. */
+export type IterationEditHandler = (request: IterationEditRequest) => void;
+
+/** Provide a handler to enable the node-view `⋯` re-edit affordance. */
+export const IterationEditContext = createContext<IterationEditHandler | null>(null);

package/src/markdown-iteration/index.ts

@@ -0,0 +1,24 @@
+/**
+ * `markdown-iteration` — the `:::iterate` / `:::pivot` repeater for
+ * `MarkdownPreview`. Enabled by the `evaluateIteration` prop (the calc/citation
+ * precedent — *the library renders, the app computes*); the standalone
+ * `IterationBlock` + the public contract types are exported for direct use.
+ */
+export {
+  IterationBlock,
+  defaultInterpolate,
+  type EvaluateIteration,
+  type InterpolateTemplate,
+  type IterationBlockProps,
+  type IterationCell,
+  type IterationData,
+  type IterationLayout,
+  type IterationSpec,
+} from "./iteration";
+
+export {
+  IterationDirective,
+  specFromDirective,
+  MAX_ITERATION_DEPTH,
+  type IterationDirectiveProps,
+} from "./directive";

package/src/markdown-iteration/iteration-block.test.tsx

@@ -0,0 +1,138 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { IterationBlock, type IterationData, type IterationSpec } from "./iteration";
+
+afterEach(cleanup);
+
+// A plain cell renderer (NOT a nested MarkdownPreview) keeps these tests
+// deterministic + light — they exercise layout + interpolation, not markdown.
+const plainRender = (md: string) => <span data-cell="">{md}</span>;
+
+const spec = (over: Partial<IterationSpec> = {}): IterationSpec => ({
+  kind: "iterate",
+  layout: "stacked",
+  template: "{{name}}",
+  as: "item",
+  attributes: {},
+  ...over,
+});
+
+describe("IterationBlock", () => {
+  it("stacked: renders one interpolated cell per item, in order", () => {
+    const data: IterationData = {
+      cells: [{ context: { name: "Ada" } }, { context: { name: "Bo" } }],
+    };
+    render(<IterationBlock spec={spec()} evaluate={() => data} render={plainRender} />);
+    const cells = screen.getAllByText(/Ada|Bo/);
+    expect(cells.map((c) => c.textContent)).toEqual(["Ada", "Bo"]);
+  });
+
+  it("grid: lays cells into a table with the given column headers", () => {
+    const data: IterationData = {
+      columns: ["A", "B"],
+      cells: [{ context: { n: 1 } }, { context: { n: 2 } }, { context: { n: 3 } }],
+    };
+    render(
+      <IterationBlock
+        spec={spec({ layout: "grid", template: "{{n}}" })}
+        evaluate={() => data}
+        render={plainRender}
+      />,
+    );
+    expect(screen.getByRole("columnheader", { name: "A" })).toBeInTheDocument();
+    // 3 cells + 2 columns → 2 rows (row-major).
+    expect(screen.getAllByRole("row")).toHaveLength(3); // header + 2 body rows
+  });
+
+  it("bento: renders one BentoGrid tile (bg-card surface) per cell", () => {
+    const data: IterationData = {
+      cells: [{ context: { n: 1 } }, { context: { n: 2 } }, { context: { n: 3 } }],
+    };
+    const { container } = render(
+      <IterationBlock
+        spec={spec({ layout: "bento", template: "{{n}}" })}
+        evaluate={() => data}
+        render={plainRender}
+      />,
+    );
+    expect(container.querySelector('[data-iteration-layout="bento"]')).toBeInTheDocument();
+    // Each tile composes Card (bg-card) → 3 cells = 3 tiles.
+    expect(container.querySelectorAll(".bg-card")).toHaveLength(3);
+    expect(screen.getByText("1")).toBeInTheDocument();
+  });
+
+  it("matrix: builds a pivot table with row + column headers and cells at intersections", () => {
+    const data: IterationData = {
+      rowHeaders: ["Q1", "Q2"],
+      colHeaders: ["EU", "US"],
+      cells: ["Q1", "Q2"].flatMap((r) =>
+        ["EU", "US"].map((c) => ({ row: r, col: c, context: { v: `${r}/${c}` } })),
+      ),
+    };
+    render(
+      <IterationBlock
+        spec={spec({ kind: "pivot", layout: "matrix", template: "{{v}}" })}
+        evaluate={() => data}
+        render={plainRender}
+      />,
+    );
+    expect(screen.getByRole("columnheader", { name: "EU" })).toBeInTheDocument();
+    expect(screen.getByRole("rowheader", { name: "Q1" })).toBeInTheDocument();
+    expect(screen.getByText("Q1/US")).toBeInTheDocument();
+  });
+
+  it("matrix without both axes falls back to a grid (no crash)", () => {
+    const data: IterationData = { cells: [{ context: { v: "x" } }] };
+    render(
+      <IterationBlock
+        spec={spec({ kind: "pivot", layout: "matrix", template: "{{v}}" })}
+        evaluate={() => data}
+        render={plainRender}
+      />,
+    );
+    expect(screen.getByText("x")).toBeInTheDocument();
+  });
+
+  it("renders a quiet empty state when there is no data", () => {
+    render(<IterationBlock spec={spec()} evaluate={() => null} render={plainRender} />);
+    expect(screen.getByRole("group", { name: "Iteration" })).toHaveTextContent(
+      /Nothing to iterate/i,
+    );
+  });
+
+  it("degrades a throwing evaluate to the empty state (never crashes)", () => {
+    const evaluate = vi.fn(() => {
+      throw new Error("boom");
+    });
+    render(<IterationBlock spec={spec()} evaluate={evaluate} render={plainRender} />);
+    expect(screen.getByRole("group", { name: "Iteration" })).toBeInTheDocument();
+  });
+
+  it("uses a cell's pre-rendered markdown, skipping interpolate", () => {
+    const interpolate = vi.fn(() => "INTERPOLATED");
+    const data: IterationData = { cells: [{ context: {}, markdown: "PRERENDERED" }] };
+    render(
+      <IterationBlock
+        spec={spec()}
+        evaluate={() => data}
+        interpolate={interpolate}
+        render={plainRender}
+      />,
+    );
+    expect(screen.getByText("PRERENDERED")).toBeInTheDocument();
+    expect(interpolate).not.toHaveBeenCalled();
+  });
+
+  it("exposes the loop variable + fields to the template scope", () => {
+    const data: IterationData = { cells: [{ context: { name: "Ada" } }] };
+    render(
+      <IterationBlock
+        spec={spec({ as: "p", template: "{{p.name}}={{name}}" })}
+        evaluate={() => data}
+        render={plainRender}
+      />,
+    );
+    expect(screen.getByText("Ada=Ada")).toBeInTheDocument();
+  });
+});