@elabs-ai/components-editor 4.0.0

package/src/markdown-iteration/iteration-builder-dialog.stories.tsx

@@ -0,0 +1,293 @@
+import { Button } from "@elabs-ai/components-ui";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { expect, userEvent, within } from "storybook/test";
+
+import { IterationBuilderDialog } from "./iteration-builder-dialog";
+import type { IterationBuilderValue } from "./iteration-builder";
+import type { EvaluateCalc } from "../calc-block";
+
+// A minimal stand-in calc engine for the story (the app brings its own): every
+// non-empty line resolves to a fixed value, enough to show a ```calc cell
+// RESOLVING into a CalcBlock inside the pivot rather than showing raw text.
+const evaluateCalc: EvaluateCalc = (source) => ({
+  results: source
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .map((_, i) => ({
+      line: i + 1,
+      tokens: [],
+      value: { kind: "number" as const, raw: 42, display: "42" },
+    })),
+});
+
+/**
+ * Room between a focused child's border box and its scroll-container ancestor's
+ * SCROLLPORT — see `packages/ui/src/components/dialog/dialog-focus-ring-clearance.stories.tsx`
+ * for the full derivation. Reused here (not imported — `@elabs-ai/components-editor`
+ * doesn't depend on `@elabs-ai/components-ui`'s story files) to confirm #425's fix
+ * reaches this dialog now that its scroll region is a real `DialogBody`.
+ */
+const room = (child: HTMLElement, box: HTMLElement) => {
+  const c = child.getBoundingClientRect();
+  const b = box.getBoundingClientRect();
+  const l = b.left + box.clientLeft;
+  const t = b.top + box.clientTop;
+  return {
+    left: c.left - l,
+    right: l + box.clientWidth - c.right,
+    top: c.top - t,
+    bottom: t + box.clientHeight - c.bottom,
+  };
+};
+
+const meta = {
+  title: "Editor/Iteration/BuilderDialog",
+  component: IterationBuilderDialog,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component:
+          "The #223 GUIDED builder (A5) — collects the DATA (value list(s) + bind name + layout) " +
+          "as well as the per-cell template, shows a LIVE populated preview, and writes a " +
+          "fully-bound `:::iterate` / `:::pivot` directive whose value lists live in its " +
+          "attributes (rendered by the built-in `evaluateEmbedded`). Wire the node-view `⋯` " +
+          "re-edit to it with `IterationBuilderProvider` for a lossless round-trip.",
+      },
+    },
+  },
+} satisfies Meta<typeof IterationBuilderDialog>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const PIVOT_SEED: IterationBuilderValue = {
+  kind: "pivot",
+  as: "item",
+  layout: "matrix",
+  values: ["Q1", "Q2", "Q3"],
+  cols: ["North", "South"],
+  template: "{{row}} · {{col}}",
+};
+
+/**
+ * Pivot: two value lists → a populated matrix in the live preview. Opening this
+ * (the `⋯` re-edit scenario, seeded via `value`) shows the matrix filling in from
+ * the embedded row/column lists with no consumer data engine.
+ */
+export const PivotBuilder: Story = {
+  args: { open: false, onOpenChange: () => {}, onSave: () => {} },
+  render: function PivotBuilderStory() {
+    const [open, setOpen] = useState(false);
+    const [saved, setSaved] = useState<string | null>(null);
+    return (
+      <div className="flex flex-col items-center gap-3">
+        <Button onClick={() => setOpen(true)}>Edit pivot…</Button>
+        {saved ? (
+          <pre className="max-w-md rounded-md bg-surface-muted p-3 text-caption">{saved}</pre>
+        ) : null}
+        <IterationBuilderDialog
+          open={open}
+          onOpenChange={setOpen}
+          value={PIVOT_SEED}
+          onSave={setSaved}
+        />
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("button", { name: /Edit pivot/i }));
+    const dialog = await within(document.body).findByRole("dialog", {}, { timeout: 12000 });
+    const d = within(dialog);
+    // Each value string renders TWICE — once as a TagInput chip in the left
+    // column, once in the live preview — so scope queries to the preview region
+    // (the confirming pattern from PivotWithCalc / WithNestedCard below).
+    const preview = within(
+      await d.findByRole("region", { name: /live preview/i }, { timeout: 8000 }),
+    );
+    // The live preview renders a populated matrix from the embedded value lists:
+    // axis headers + an interpolated cell.
+    await expect(await preview.findByText("North", {}, { timeout: 8000 })).toBeVisible();
+    await expect(preview.getByText("Q1")).toBeVisible();
+    await expect(preview.getByText("Q1 · North")).toBeVisible();
+  },
+};
+
+/**
+ * Iterate: one value list → one rendered cell per value (stacked).
+ */
+export const IterateBuilder: Story = {
+  args: { open: false, onOpenChange: () => {}, onSave: () => {} },
+  render: function IterateBuilderStory() {
+    const [open, setOpen] = useState(false);
+    const [saved, setSaved] = useState<string | null>(null);
+    return (
+      <div className="flex flex-col items-center gap-3">
+        <Button onClick={() => setOpen(true)}>Edit iteration…</Button>
+        {saved ? (
+          <pre className="max-w-md rounded-md bg-surface-muted p-3 text-caption">{saved}</pre>
+        ) : null}
+        <IterationBuilderDialog
+          open={open}
+          onOpenChange={setOpen}
+          value={{
+            kind: "iterate",
+            as: "item",
+            layout: "stacked",
+            values: ["Alice", "Bob", "Charlie"],
+            template: "{{item.name}}",
+          }}
+          onSave={setSaved}
+        />
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("button", { name: /Edit iteration/i }));
+    const dialog = await within(document.body).findByRole("dialog", {}, { timeout: 12000 });
+    // "Alice" renders TWICE — as a TagInput chip AND in the live preview — so
+    // scope to the preview region (mirrors the PivotBuilder fix above).
+    const preview = within(
+      await within(dialog).findByRole("region", { name: /live preview/i }, { timeout: 8000 }),
+    );
+    // The live preview renders one cell per embedded value.
+    await expect(await preview.findByText("Alice", {}, { timeout: 8000 })).toBeVisible();
+
+    // #425 acceptance criterion: this dialog's `Bind name` field sits directly
+    // against the (now real) `DialogBody` scrollport as its first child — the
+    // same worst case `FocusRingClearance` locks on `DialogBody` itself. Assert
+    // the fix reaches this consumer rather than assuming it from the swap alone.
+    const body = dialog.querySelector<HTMLElement>('[data-slot="dialog-body"]')!;
+    const bindNameInput = within(dialog).getByLabelText("Bind name");
+    bindNameInput.focus();
+    const r = room(bindNameInput, body);
+    expect(r.left).toBeGreaterThanOrEqual(3.5);
+    expect(r.right).toBeGreaterThanOrEqual(3.5);
+    expect(r.top).toBeGreaterThanOrEqual(3.5);
+  },
+};
+
+/**
+ * Pivot with a ```calc cell: objects inside a cell RESOLVE in the live preview
+ * (not raw text). With a calc `evaluate` wired, each cell's fence renders a real
+ * CalcBlock — the same path the saved block renders through, in matrix and
+ * stacked alike.
+ */
+export const PivotWithCalc: Story = {
+  args: { open: false, onOpenChange: () => {}, onSave: () => {} },
+  render: function PivotWithCalcStory() {
+    const [open, setOpen] = useState(false);
+    return (
+      <div className="flex flex-col items-center gap-3">
+        <Button onClick={() => setOpen(true)}>Edit pivot with calc…</Button>
+        <IterationBuilderDialog
+          open={open}
+          onOpenChange={setOpen}
+          evaluate={evaluateCalc}
+          value={{
+            kind: "pivot",
+            as: "item",
+            layout: "matrix",
+            values: ["1", "2"],
+            cols: ["1", "2"],
+            template: "```calc\nitems = {{row}} + {{col}}\ntotal = items\n```",
+          }}
+          onSave={() => {}}
+        />
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("button", { name: /Edit pivot with calc/i }));
+    const dialog = await within(document.body).findByRole("dialog", {}, { timeout: 12000 });
+    // The calc fence resolved into real CalcBlock(s) inside the matrix cells.
+    await within(dialog).findAllByTestId("calc-block", {}, { timeout: 8000 });
+  },
+};
+
+/**
+ * A nested `:::card` (with content AFTER it) inside the iteration template. The live
+ * preview renders a REAL Card per item — not truncated plain text — and keeps the
+ * trailing line, because the builder serializes the directive with a fence longer
+ * than the nested one (`outerDirectiveFence`). This is the #223 "other components
+ * inside iterations don't render" fix, shown in the dialog the author actually uses.
+ */
+export const WithNestedCard: Story = {
+  args: { open: false, onOpenChange: () => {}, onSave: () => {} },
+  render: function WithNestedCardStory() {
+    const [open, setOpen] = useState(false);
+    return (
+      <div className="flex flex-col items-center gap-3">
+        <Button onClick={() => setOpen(true)}>Edit iteration with card…</Button>
+        <IterationBuilderDialog
+          open={open}
+          onOpenChange={setOpen}
+          value={{
+            kind: "iterate",
+            as: "item",
+            layout: "stacked",
+            values: ["Ada", "Grace"],
+            template:
+              ':::card{title="{{item.name}}"}\nLead engineer for {{item.name}}\n:::\n\nNotes for {{item.name}}',
+          }}
+          onSave={() => {}}
+        />
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("button", { name: /Edit iteration with card/i }));
+    const dialog = await within(document.body).findByRole("dialog", {}, { timeout: 12000 });
+    const d = within(dialog);
+    // The nested card rendered as a real component (title + body interpolated)...
+    await expect(await d.findByText("Lead engineer for Ada", {}, { timeout: 8000 })).toBeVisible();
+    // ...and the content AFTER it survived (dropped before the fence-collision fix).
+    await expect(d.getByText("Notes for Ada")).toBeVisible();
+    await expect(d.getByText("Notes for Grace")).toBeVisible();
+  },
+};
+
+/**
+ * Bento layout: the values render as varied-size BentoGrid tiles in the live preview.
+ */
+export const BentoBuilder: Story = {
+  args: { open: false, onOpenChange: () => {}, onSave: () => {} },
+  render: function BentoBuilderStory() {
+    const [open, setOpen] = useState(false);
+    return (
+      <div className="flex flex-col items-center gap-3">
+        <Button onClick={() => setOpen(true)}>Edit bento…</Button>
+        <IterationBuilderDialog
+          open={open}
+          onOpenChange={setOpen}
+          value={{
+            kind: "iterate",
+            as: "item",
+            layout: "bento",
+            values: ["Alpha", "Beta", "Gamma", "Delta", "Epsilon"],
+            template: "**{{item.name}}**",
+          }}
+          onSave={() => {}}
+        />
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("button", { name: /Edit bento/i }));
+    const dialog = await within(document.body).findByRole("dialog", {}, { timeout: 12000 });
+    // "Alpha"/"Epsilon" render TWICE — as TagInput chips AND in the live
+    // preview's BentoGrid tiles — so scope to the preview region.
+    const preview = within(
+      await within(dialog).findByRole("region", { name: /live preview/i }, { timeout: 8000 }),
+    );
+    await expect(await preview.findByText("Alpha", {}, { timeout: 8000 })).toBeVisible();
+    await expect(preview.getByText("Epsilon")).toBeVisible();
+  },
+};

package/src/markdown-iteration/iteration-builder-dialog.tsx

@@ -0,0 +1,312 @@
+"use client";
+
+/**
+ * IterationBuilderDialog (A5) — GUIDED `:::iterate` / `:::pivot` authoring.
+ *
+ * Where `IterationTemplateDialog` edits only the per-cell template, the builder
+ * also collects the DATA — the value list (iterate) or the two value lists
+ * (pivot), the bind name, and the layout — and shows a LIVE preview of the
+ * populated block as you type. On save it writes a fully-bound directive
+ * (`serializeIterationDirective`) whose value lists live in its attributes, so the
+ * block renders populated via the built-in `evaluateEmbedded` and the `⋯` re-edit
+ * can reopen it losslessly (`parseIterationDirective` / `builderValueFromParts`).
+ *
+ * Controlled (`open` / `onOpenChange`); seed via `value` (re-edit) or `kind` +
+ * `initialValues` (fresh insert, e.g. a selection split to one value per line).
+ */
+import {
+  Button,
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  Input,
+  Label,
+  TagInput,
+  ToggleGroup,
+  ToggleGroupItem,
+} from "@elabs-ai/components-ui";
+import { useEffect, useId, useMemo, useState, type ReactNode } from "react";
+
+import { type EvaluateCalc } from "../calc-block";
+import { MarkdownPreview } from "../markdown-preview";
+import { MarkdownWorkspace } from "../markdown-workspace";
+import { IterationEditContext, type IterationEditRequest } from "./edit-context";
+import { type InterpolateTemplate, type IterationLayout } from "./iteration";
+import {
+  builderValueFromParts,
+  directivePartsFromValue,
+  emptyBuilderValue,
+  evaluateEmbedded,
+  ITERATION_LAYOUTS,
+  parseIterationDirective,
+  serializeIterationDirective,
+  type IterationBuilderValue,
+} from "./iteration-builder";
+
+export interface IterationBuilderDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** Which block to author. Default `"iterate"`. Ignored when `value` is set. */
+  kind?: "iterate" | "pivot";
+  /** Seed the whole builder (the `⋯` re-edit path). */
+  value?: IterationBuilderValue;
+  /** Seed the value list of a fresh block (e.g. a selection split to lines). */
+  initialValues?: string[];
+  /** Receives the fully-bound directive markdown when the user saves. */
+  onSave: (directiveMarkdown: string) => void;
+  /**
+   * Resolve a ```calc fence to a `CalcSheet` so calc cells COMPUTE in the live
+   * preview (the same hook `MarkdownPreview` takes — the library renders, the app
+   * computes). Without it a calc cell still renders as a code block; with it, the
+   * preview matches production. Pass your app's calc engine.
+   */
+  evaluate?: EvaluateCalc;
+  /** Fill a cell template with its context. Defaults to `{{path}}` substitution. */
+  interpolate?: InterpolateTemplate;
+}
+
+export function IterationBuilderDialog({
+  open,
+  onOpenChange,
+  kind: kindProp = "iterate",
+  value,
+  initialValues,
+  onSave,
+  evaluate,
+  interpolate,
+}: IterationBuilderDialogProps) {
+  const kind = value?.kind ?? kindProp;
+  const isPivot = kind === "pivot";
+  const ids = useId();
+
+  // Working draft. Value lists are arrays (chip entry via TagInput); the per-cell
+  // template stays raw text.
+  const [asName, setAsName] = useState("item");
+  const [layout, setLayout] = useState<IterationLayout>(ITERATION_LAYOUTS[kind][0] ?? "stacked");
+  const [values, setValues] = useState<string[]>([]);
+  const [cols, setCols] = useState<string[]>([]);
+  const [template, setTemplate] = useState("");
+
+  // (Re)seed whenever the dialog opens against a new value / kind.
+  useEffect(() => {
+    if (!open) return;
+    const seed = value ?? {
+      ...emptyBuilderValue(kind),
+      values: initialValues ?? [],
+    };
+    setAsName(seed.as);
+    setLayout(seed.layout);
+    setValues(seed.values);
+    setCols(seed.cols ?? []);
+    setTemplate(seed.template);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open]);
+
+  const draft: IterationBuilderValue = useMemo(
+    () => ({
+      kind,
+      as: asName.trim() || "item",
+      layout,
+      values,
+      cols: isPivot ? cols : undefined,
+      template,
+    }),
+    [kind, asName, layout, values, cols, template, isPivot],
+  );
+
+  // Live preview — render the SERIALIZED directive through MarkdownPreview, the
+  // exact path the saved block renders through. That resolves the iteration via
+  // the built-in `evaluateEmbedded` AND each cell's objects (a ```calc fence,
+  // nested directives, formatting) — in stacked, grid and matrix alike — instead
+  // of dumping the raw cell text.
+  const previewMarkdown = useMemo(() => serializeIterationDirective(draft), [draft]);
+
+  const save = () => {
+    onSave(serializeIterationDirective(draft));
+    onOpenChange(false);
+  };
+
+  const noun = isPivot ? "pivot" : "iteration";
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="flex max-h-[88vh] w-[min(56rem,94vw)] max-w-none flex-col">
+        <DialogHeader>
+          <DialogTitle>
+            {value ? "Edit" : "Insert"} {noun}
+          </DialogTitle>
+          <DialogDescription>
+            {isPivot
+              ? "Pick the row and column values, then write the per-cell template. The matrix below fills in live."
+              : "Add the list values, then write the per-row template. The result below fills in live."}
+          </DialogDescription>
+        </DialogHeader>
+
+        <DialogBody className="grid gap-4 md:grid-cols-2">
+          {/* Left column — the DATA the block iterates over. */}
+          <div className="flex min-w-0 flex-col gap-4">
+            {!isPivot ? (
+              <div className="flex flex-col gap-1.5">
+                <Label htmlFor={`${ids}-as`}>Bind name</Label>
+                <Input
+                  id={`${ids}-as`}
+                  value={asName}
+                  spellCheck={false}
+                  autoComplete="off"
+                  placeholder="item"
+                  onChange={(e) => setAsName(e.target.value)}
+                />
+                <p className="text-meta text-muted-foreground">
+                  Use <code>{`{{${asName.trim() || "item"}.name}}`}</code> in the template.
+                </p>
+              </div>
+            ) : null}
+
+            <div className="flex flex-col gap-1.5">
+              <Label htmlFor={`${ids}-values`}>{isPivot ? "Row values" : "Values"}</Label>
+              <TagInput
+                id={`${ids}-values`}
+                value={values}
+                onValueChange={setValues}
+                delimiter={[",", "\n"]}
+                placeholder="Type a value, press Enter…"
+              />
+            </div>
+
+            {isPivot ? (
+              <div className="flex flex-col gap-1.5">
+                <Label htmlFor={`${ids}-cols`}>Column values</Label>
+                <TagInput
+                  id={`${ids}-cols`}
+                  value={cols}
+                  onValueChange={setCols}
+                  delimiter={[",", "\n"]}
+                  placeholder="Type a value, press Enter…"
+                />
+              </div>
+            ) : null}
+
+            <div className="flex flex-col gap-1.5">
+              <Label id={`${ids}-layout`}>Layout</Label>
+              <ToggleGroup
+                type="single"
+                variant="segmented"
+                value={layout}
+                onValueChange={(next) => {
+                  // Single-select: ignore the empty value Radix emits when the active
+                  // item is re-pressed, so a layout is always selected.
+                  if (next) setLayout(next as IterationLayout);
+                }}
+                aria-labelledby={`${ids}-layout`}
+                className="w-fit"
+              >
+                {ITERATION_LAYOUTS[kind].map((l) => (
+                  <ToggleGroupItem key={l} value={l} className="capitalize">
+                    {l}
+                  </ToggleGroupItem>
+                ))}
+              </ToggleGroup>
+            </div>
+          </div>
+
+          {/* Right column — the per-cell TEMPLATE + the live populated preview. */}
+          <div className="flex min-h-0 min-w-0 flex-col gap-4">
+            <div className="flex min-h-0 flex-col gap-1.5">
+              <Label>Per-{isPivot ? "cell" : "row"} template</Label>
+              <div className="h-44 min-h-0 overflow-hidden rounded-md border border-border">
+                <MarkdownWorkspace
+                  value={template}
+                  onChange={setTemplate}
+                  defaultMode="source"
+                  className="h-full"
+                  aria-label="Per-cell template"
+                />
+              </div>
+            </div>
+
+            <div className="flex min-h-0 flex-col gap-1.5">
+              <Label>Live preview</Label>
+              <div
+                role="region"
+                aria-label="Live preview"
+                className="min-h-0 flex-1 overflow-auto rounded-md border border-border bg-card p-3"
+              >
+                <MarkdownPreview
+                  evaluateIteration={evaluateEmbedded}
+                  evaluate={evaluate}
+                  interpolate={interpolate}
+                >
+                  {previewMarkdown}
+                </MarkdownPreview>
+              </div>
+            </div>
+          </div>
+        </DialogBody>
+
+        <DialogFooter>
+          <Button variant="ghost" onClick={() => onOpenChange(false)}>
+            Cancel
+          </Button>
+          <Button onClick={save}>{value ? "Save" : "Insert"}</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+/**
+ * One-liner wiring for the node-view `⋯` re-edit using the GUIDED builder (A5).
+ * Drop it above a `MarkdownEditor` / `MarkdownWorkspace` to make the `⋯` on a
+ * `:::iterate` / `:::pivot` reopen the full builder seeded with the block's DATA
+ * (value lists + bind name + layout) and template, writing both back losslessly.
+ *
+ * Prefer this over {@link IterationTemplateProvider} when the consumer authors
+ * blocks with embedded value lists (the builder flow); the template-only provider
+ * remains for the lighter "edit just the template" affordance.
+ */
+export function IterationBuilderProvider({
+  children,
+  evaluate,
+  interpolate,
+}: {
+  children: ReactNode;
+  /** Forwarded to the builder's live preview so calc cells COMPUTE on re-edit. */
+  evaluate?: EvaluateCalc;
+  /** Forwarded to the builder's live preview cell interpolation. */
+  interpolate?: InterpolateTemplate;
+}) {
+  const [request, setRequest] = useState<IterationEditRequest | null>(null);
+
+  const seed = request
+    ? builderValueFromParts(request.kind, request.attributes ?? {}, request.template)
+    : undefined;
+
+  return (
+    <IterationEditContext.Provider value={setRequest}>
+      {children}
+      <IterationBuilderDialog
+        open={request != null}
+        onOpenChange={(next) => {
+          if (!next) setRequest(null);
+        }}
+        kind={request?.kind ?? "iterate"}
+        value={seed}
+        evaluate={evaluate}
+        interpolate={interpolate}
+        onSave={(directiveMarkdown) => {
+          const parsed = parseIterationDirective(directiveMarkdown);
+          if (!parsed) return;
+          const { attributes, template } = directivePartsFromValue(parsed);
+          // Prefer the data-aware writer (rewrites attributes + body); fall back to
+          // the template-only writer for older node-views.
+          if (request?.onSaveData) request.onSaveData({ attributes, template });
+          else request?.onSave(template);
+        }}
+      />
+    </IterationEditContext.Provider>
+  );
+}