@elabs-ai/components-ai 4.0.0

package/src/jsx-preview.tsx

@@ -0,0 +1,409 @@
+"use client";
+
+import { Skeleton } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { AlertCircle } from "lucide-react";
+import type { ComponentProps, ReactNode } from "react";
+import {
+  createContext,
+  memo,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type { TProps as JsxParserProps } from "react-jsx-parser";
+import JsxParser from "react-jsx-parser";
+
+/**
+ * The readiness of the preview, derived from the input (see loading-states.md):
+ * - `idle`    — nothing requested yet (empty input, never rendered). Renders nothing.
+ * - `pending` — not-ready: `loading`, `isStreaming`, OR syntactically incomplete
+ *               input (a half-arrived tag). Builds up best-effort; the error slot
+ *               is suppressed; the skeleton shows until the first successful paint.
+ * - `ready`   — settled, parseable input is rendering.
+ * - `error`   — settled AND genuinely invalid input (the only state that surfaces
+ *               `JSXPreviewError`).
+ */
+export type JSXPreviewStatus = "idle" | "pending" | "ready" | "error";
+
+interface JSXPreviewContextValue {
+  jsx: string;
+  processedJsx: string;
+  isStreaming: boolean;
+  loading: boolean;
+  status: JSXPreviewStatus;
+  hasRendered: boolean;
+  error: Error | null;
+  setError: (error: Error | null) => void;
+  setHasRendered: (value: boolean) => void;
+  components: JsxParserProps["components"];
+  bindings: JsxParserProps["bindings"];
+  onErrorProp?: (error: Error) => void;
+}
+
+const JSXPreviewContext = createContext<JSXPreviewContextValue | null>(null);
+
+const TAG_REGEX = /<\/?([a-zA-Z][a-zA-Z0-9]*)\s*([^>]*?)(\/)?>/;
+
+export const useJSXPreview = () => {
+  const context = useContext(JSXPreviewContext);
+  if (!context) {
+    throw new Error("JSXPreview components must be used within JSXPreview");
+  }
+  return context;
+};
+
+const matchJsxTag = (code: string) => {
+  if (code.trim() === "") {
+    return null;
+  }
+
+  const match = code.match(TAG_REGEX);
+
+  if (!match || match.index === undefined) {
+    return null;
+  }
+
+  const [fullMatch = "", tagName = "", attributes = "", selfClosing] = match;
+
+  let type: "self-closing" | "closing" | "opening";
+  if (selfClosing) {
+    type = "self-closing";
+  } else if (fullMatch.startsWith("</")) {
+    type = "closing";
+  } else {
+    type = "opening";
+  }
+
+  return {
+    attributes: attributes.trim(),
+    endIndex: match.index + fullMatch.length,
+    startIndex: match.index,
+    tag: fullMatch,
+    tagName,
+    type,
+  };
+};
+
+const stripIncompleteTag = (text: string) => {
+  // Find the last '<' that isn't part of a complete tag
+  const lastOpen = text.lastIndexOf("<");
+  if (lastOpen === -1) {
+    return text;
+  }
+
+  const afterOpen = text.slice(lastOpen);
+  // If there's no closing '>' after the last '<', it's an incomplete tag
+  if (!afterOpen.includes(">")) {
+    return text.slice(0, lastOpen);
+  }
+
+  return text;
+};
+
+const completeJsxTag = (code: string) => {
+  const stack: string[] = [];
+  let result = "";
+  let currentPosition = 0;
+
+  while (currentPosition < code.length) {
+    const match = matchJsxTag(code.slice(currentPosition));
+    if (!match) {
+      // No more tags found, strip any trailing incomplete tag
+      result += stripIncompleteTag(code.slice(currentPosition));
+      break;
+    }
+    const { tagName, type, endIndex } = match;
+
+    // Include any text content before this tag
+    result += code.slice(currentPosition, currentPosition + endIndex);
+
+    if (type === "opening") {
+      stack.push(tagName);
+    } else if (type === "closing") {
+      stack.pop();
+    }
+
+    currentPosition += endIndex;
+  }
+
+  return (
+    result +
+    [...stack]
+      .reverse()
+      .map((tag) => `</${tag}>`)
+      .join("")
+  );
+};
+
+export type JSXPreviewProps = ComponentProps<"div"> & {
+  jsx: string;
+  /** Content is arriving incrementally — build up, suppress transient errors. */
+  isStreaming?: boolean;
+  /**
+   * No renderable content yet (fetch-then-show). Forces the `pending` state so
+   * `JSXPreviewSkeleton` shows until `jsx` arrives. Orthogonal to `isStreaming`.
+   */
+  loading?: boolean;
+  components?: JsxParserProps["components"];
+  bindings?: JsxParserProps["bindings"];
+  onError?: (error: Error) => void;
+};
+
+export const JSXPreview = memo(
+  ({
+    jsx,
+    isStreaming = false,
+    loading = false,
+    components,
+    bindings,
+    onError,
+    className,
+    children,
+    ...props
+  }: JSXPreviewProps) => {
+    const [prevJsx, setPrevJsx] = useState(jsx);
+    const [error, setError] = useState<Error | null>(null);
+    const [hasRendered, setHasRendered] = useState(false);
+
+    // Clear the terminal error when jsx changes (derived state pattern)
+    if (jsx !== prevJsx) {
+      setPrevJsx(jsx);
+      setError(null);
+    }
+
+    // The tag-balanced best-effort of the current input. When it differs from the
+    // raw jsx, the input ends mid-tag → it is INCOMPLETE (still streaming / being
+    // typed), not invalid. This is the timer-free "not-ready" signal.
+    const completed = useMemo(() => completeJsxTag(jsx), [jsx]);
+    const isIncomplete = jsx.trim() !== "" && completed !== jsx;
+
+    const processedJsx = useMemo(() => {
+      if (loading) return "";
+      return isStreaming || isIncomplete ? completed : jsx;
+    }, [jsx, isStreaming, loading, isIncomplete, completed]);
+
+    const status = useMemo<JSXPreviewStatus>(() => {
+      if (loading) return "pending";
+      if (jsx.trim() === "") return hasRendered ? "ready" : "idle";
+      if (isStreaming || isIncomplete) return "pending";
+      return error != null ? "error" : "ready";
+    }, [jsx, isStreaming, loading, isIncomplete, error, hasRendered]);
+
+    const contextValue = useMemo(
+      () => ({
+        bindings,
+        components,
+        error,
+        hasRendered,
+        isStreaming,
+        jsx,
+        loading,
+        onErrorProp: onError,
+        processedJsx,
+        setError,
+        setHasRendered,
+        status,
+      }),
+      [
+        bindings,
+        components,
+        error,
+        hasRendered,
+        isStreaming,
+        jsx,
+        loading,
+        onError,
+        processedJsx,
+        status,
+      ],
+    );
+
+    return (
+      <JSXPreviewContext.Provider value={contextValue}>
+        <div className={cn("relative", className)} {...props}>
+          {children}
+        </div>
+      </JSXPreviewContext.Provider>
+    );
+  },
+);
+
+JSXPreview.displayName = "JSXPreview";
+
+export type JSXPreviewContentProps = Omit<ComponentProps<"div">, "children">;
+
+export const JSXPreviewContent = memo(({ className, ...props }: JSXPreviewContentProps) => {
+  const { processedJsx, status, components, bindings, setError, setHasRendered, onErrorProp } =
+    useJSXPreview();
+  const lastGoodJsxRef = useRef("");
+  // `erroredJsx` is committed in an effect (never during render). The parser
+  // reports errors synchronously DURING its own render, so `handleError` only
+  // stashes a ref — committing state there would be a setState-in-render.
+  const [erroredJsx, setErroredJsx] = useState<string | null>(null);
+  const pendingErrorRef = useRef<{ jsx: string; error: Error } | null>(null);
+
+  // Reset the per-input error flag synchronously when the content changes.
+  const prevProcessedRef = useRef(processedJsx);
+  if (prevProcessedRef.current !== processedJsx) {
+    prevProcessedRef.current = processedJsx;
+    if (erroredJsx !== null) setErroredJsx(null);
+  }
+  const hadError = erroredJsx === processedJsx;
+
+  const handleError = useCallback(
+    (error: Error) => {
+      pendingErrorRef.current = { error, jsx: processedJsx };
+    },
+    [processedJsx],
+  );
+
+  // After commit, reconcile the parse outcome. A fresh error becomes terminal
+  // (surfaces `JSXPreviewError`) ONLY when settled — for a `pending` input it is
+  // held silently (build-up keeps going behind the last good render). A clean
+  // render records the last-good JSX and marks the first paint.
+  useEffect(() => {
+    const failed = pendingErrorRef.current?.jsx === processedJsx;
+    if (failed) {
+      const { error } = pendingErrorRef.current!;
+      pendingErrorRef.current = null;
+      if (erroredJsx !== processedJsx) setErroredJsx(processedJsx);
+      if (status !== "pending") {
+        setError(error);
+        onErrorProp?.(error);
+      }
+    } else if (erroredJsx !== processedJsx && processedJsx.trim() !== "") {
+      lastGoodJsxRef.current = processedJsx;
+      setHasRendered(true);
+    }
+  }, [processedJsx, status, erroredJsx, setError, setHasRendered, onErrorProp]);
+
+  // The error slot and the skeleton own the "error" / nothing-yet states.
+  if (status !== "ready" && status !== "pending") {
+    return null;
+  }
+
+  // While pending, a failed parse falls back to the last good render (which may
+  // be empty on first paint — the skeleton covers that).
+  const displayJsx = hadError ? lastGoodJsxRef.current : processedJsx;
+
+  return (
+    <div className={cn("jsx-preview-content", className)} {...props}>
+      <JsxParser
+        bindings={bindings}
+        components={components}
+        jsx={displayJsx}
+        onError={handleError}
+        renderInWrapper={false}
+      />
+    </div>
+  );
+});
+
+JSXPreviewContent.displayName = "JSXPreviewContent";
+
+export type JSXPreviewSkeletonProps = ComponentProps<"div">;
+
+/**
+ * The not-ready placeholder (loading-states.md §slot anatomy). Renders a
+ * layout-shaped `Skeleton` while the preview is `pending` and nothing has
+ * painted yet — so a streaming/incomplete surface BUILDS UP behind a skeleton
+ * instead of flashing the error box. Pass `children` to override the shape.
+ */
+export const JSXPreviewSkeleton = memo(
+  ({ className, children, ...props }: JSXPreviewSkeletonProps) => {
+    const { status, hasRendered } = useJSXPreview();
+
+    // Show only before the first successful paint; once content builds up, the
+    // partial render is its own affordance (no skeleton-over-content).
+    const show = !hasRendered && status === "pending";
+
+    // The live region must exist in the DOM BEFORE its text appears, or NVDA
+    // skips the announcement (ARIA22). So the wrapper is ALWAYS rendered (it
+    // collapses to `sr-only` when idle) and the label is set one tick later via
+    // an effect — guaranteeing an empty region precedes the "Loading…" text.
+    const [announce, setAnnounce] = useState(false);
+    useEffect(() => setAnnounce(show), [show]);
+
+    return (
+      <div
+        className={cn(show ? "space-y-2" : "sr-only", className)}
+        role="status"
+        aria-live="polite"
+        {...props}
+      >
+        <span className="sr-only">{announce ? "Loading preview…" : ""}</span>
+        {show
+          ? (children ?? (
+              <>
+                <Skeleton className="h-20 w-full" />
+                <div className="grid grid-cols-3 gap-2">
+                  <Skeleton className="h-16" />
+                  <Skeleton className="h-16" />
+                  <Skeleton className="h-16" />
+                </div>
+              </>
+            ))
+          : null}
+      </div>
+    );
+  },
+);
+
+JSXPreviewSkeleton.displayName = "JSXPreviewSkeleton";
+
+export type JSXPreviewErrorProps = ComponentProps<"div"> & {
+  children?: ReactNode | ((error: Error) => ReactNode);
+};
+
+const renderChildren = (
+  children: ReactNode | ((error: Error) => ReactNode),
+  error: Error,
+): ReactNode => {
+  if (typeof children === "function") {
+    return children(error);
+  }
+  return children;
+};
+
+export const JSXPreviewError = memo(({ className, children, ...props }: JSXPreviewErrorProps) => {
+  const { status, error } = useJSXPreview();
+
+  // Terminal failures only — never while loading / streaming / incomplete.
+  if (status !== "error" || !error) {
+    return null;
+  }
+
+  return (
+    <div
+      // The status wash is the separation gesture (#194, research 08 §B.1):
+      // `bg-destructive/10` + the destructive ink/icon already mark the region,
+      // and the alpha-wash survives high decoration (token-inequality escape from the
+      // drawn-not-filled rule), so the old `border border-destructive/50` was
+      // redundant on every theme — dropped. Text + icon use `text-destructive-text`
+      // (the on-surface destructive ink ramp) — raw `text-destructive` fails AA on
+      // the wash (3.86:1) and goes near-white in dark; the *-text token is
+      // AA-guaranteed and keeps the destructive cue in every theme.
+      className={cn(
+        "flex items-center gap-2 rounded-md bg-destructive/10 p-3 text-body text-destructive-text",
+        className,
+      )}
+      role="alert"
+      {...props}
+    >
+      {children ? (
+        renderChildren(children, error)
+      ) : (
+        <>
+          <AlertCircle className="size-4 shrink-0" />
+          <span>{error.message}</span>
+        </>
+      )}
+    </div>
+  );
+});
+
+JSXPreviewError.displayName = "JSXPreviewError";

package/src/markdown-view.stories.tsx

@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { MarkdownView } from "./markdown-view";
+
+const meta = {
+  title: "AI/MarkdownView",
+  component: MarkdownView,
+  tags: ["autodocs"],
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof MarkdownView>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const DOC = `# Quarterly summary
+
+Revenue grew **12.4% QoQ**. See the [variance check](https://example.com) for details.
+
+## Regional highlights
+
+- EMEA $18.4M (+14%)
+- Americas $21.2M (+8%)
+- APAC $8.6M — watch churn
+
+> Flagged by the automated variance check.
+
+Inline \`code\` stays inline; fenced blocks go through Shiki:
+
+\`\`\`sql
+SELECT region, total FROM finance.revenue;
+\`\`\`
+`;
+
+/** The full reading scale — markdown mapped onto the Prose* primitives. */
+export const Default: Story = {
+  args: { children: DOC },
+  decorators: [
+    (Story) => (
+      <div className="max-w-prose">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+/**
+ * The constrained rung for narrow embeds (research 09 §G.2): `baseHeadingLevel={2}`
+ * maps a document `#` to the title rung — never "biggest text on screen" in a rail.
+ */
+export const ConstrainedHeadings: Story = {
+  args: { children: DOC, baseHeadingLevel: 2 },
+  decorators: [
+    (Story) => (
+      <div className="max-w-80">
+        <Story />
+      </div>
+    ),
+  ],
+};

package/src/markdown-view.test.tsx

@@ -0,0 +1,36 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { MarkdownView } from "./markdown-view";
+
+afterEach(cleanup);
+
+const DOC = `# Board note
+
+A paragraph with [a link](https://example.com) and \`inline\` code.
+
+- first
+- second
+`;
+
+describe("MarkdownView (#193, research 04 §5 — document, not Shiki source)", () => {
+  it("renders markdown onto the Prose primitives (document semantics)", () => {
+    render(<MarkdownView>{DOC}</MarkdownView>);
+
+    // Headings are real headings (not mono source text).
+    expect(screen.getByRole("heading", { level: 1, name: "Board note" })).toBeInTheDocument();
+    // Links map onto ProseLink (external → safe rel + new tab).
+    const link = screen.getByRole("link", { name: "a link" });
+    expect(link).toHaveAttribute("target", "_blank");
+    expect(link).toHaveAttribute("rel", expect.stringContaining("noopener"));
+    // Lists are real lists.
+    expect(screen.getAllByRole("listitem")).toHaveLength(2);
+  });
+
+  it("caps headings at the constrained rung via baseHeadingLevel (research 09 §G.2)", () => {
+    render(<MarkdownView baseHeadingLevel={2}>{DOC}</MarkdownView>);
+    // The document `#` renders as an h2 (the `title` rung), never the
+    // reading-scale h1 — no "biggest text on screen" inside a 20rem rail.
+    expect(screen.queryByRole("heading", { level: 1 })).not.toBeInTheDocument();
+    expect(screen.getByRole("heading", { level: 2, name: "Board note" })).toBeInTheDocument();
+  });
+});

package/src/markdown-view.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+/**
+ * MarkdownView — the branded READ-ONLY markdown renderer (#193, research 04 §5).
+ *
+ * Renders a markdown *document* as a document — never as Shiki source (that
+ * was the ASSET-2 defect: `CodeBlock code={…} language="markdown"`). Built on
+ * the EXISTING `streamdown` dependency (no new heavy dep), but unlike the
+ * streaming `MessageResponse` it maps the element tree onto the promoted
+ * `Prose*` primitives from `@elabs-ai/components-ui` via a `components` map — one
+ * source-owned prose set for chat answers, the editor preview and this view.
+ *
+ * `baseHeadingLevel` is the constrained-rung seam (research 04 §5 / 09 §G.2):
+ * inside a narrow rail pass `baseHeadingLevel={2}` so a document `#` renders
+ * at the `title` rung, not the reading-scale h1 — never "biggest text on
+ * screen" inside a 20rem panel.
+ */
+import {
+  ProseBlockquote,
+  ProseHeading,
+  ProseInlineCode,
+  ProseLink,
+  ProseList,
+  ProseListItem,
+  ProseText,
+  type ProseHeadingLevel,
+} from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { useStreamdownPlugins, useStreamdownTranslations } from "./_streamdown-i18n";
+import type { ComponentProps } from "react";
+import { useMemo } from "react";
+import { Streamdown } from "streamdown";
+
+type StreamdownComponents = NonNullable<ComponentProps<typeof Streamdown>["components"]>;
+
+const MAX_HEADING_LEVEL = 6;
+
+const clampHeadingLevel = (level: number): ProseHeadingLevel =>
+  Math.min(MAX_HEADING_LEVEL, Math.max(1, level)) as ProseHeadingLevel;
+
+/**
+ * Map the markdown element tree onto the Prose* primitives. Fenced code blocks
+ * (className `language-*`) stay with the streamdown `code` plugin (Shiki);
+ * only INLINE code re-maps to `ProseInlineCode`.
+ */
+function buildProseComponents(baseHeadingLevel: ProseHeadingLevel): StreamdownComponents {
+  const heading =
+    (markdownLevel: number): StreamdownComponents["h1"] =>
+    ({ node: _node, ...props }) => (
+      <ProseHeading level={clampHeadingLevel(markdownLevel + baseHeadingLevel - 1)} {...props} />
+    );
+  return {
+    h1: heading(1),
+    h2: heading(2),
+    h3: heading(3),
+    h4: heading(4),
+    h5: heading(5),
+    h6: heading(6),
+    p: ({ node: _node, ...props }) => <ProseText {...props} />,
+    a: ({ node: _node, ...props }) => <ProseLink {...props} />,
+    // `ref` is stripped: ProseList's intersection ref type (ul & ol) is
+    // narrower than the per-element ref react-markdown passes.
+    ul: ({ node: _node, ref: _ref, ...props }) => <ProseList {...props} />,
+    ol: ({ node: _node, ref: _ref, ...props }) => <ProseList ordered {...props} />,
+    li: ({ node: _node, ...props }) => <ProseListItem {...props} />,
+    blockquote: ({ node: _node, ...props }) => <ProseBlockquote {...props} />,
+    code: ({ node: _node, className, ...props }) =>
+      /\blanguage-/.test(className ?? "") ? (
+        <code className={className} {...props} />
+      ) : (
+        <ProseInlineCode className={className} {...props} />
+      ),
+  };
+}
+
+export interface MarkdownViewProps extends Omit<
+  ComponentProps<typeof Streamdown>,
+  "components" | "plugins"
+> {
+  /**
+   * The prose level a markdown `#` maps to; deeper headings shift with it
+   * (capped at 6). Default `1` (the full reading scale). Pass `2` in narrow
+   * embeds (a context rail) so headings stay on the constrained rung.
+   */
+  baseHeadingLevel?: ProseHeadingLevel;
+}
+
+export const MarkdownView = ({
+  baseHeadingLevel = 1,
+  className,
+  children,
+  ...props
+}: MarkdownViewProps) => {
+  const components = useMemo(() => buildProseComponents(baseHeadingLevel), [baseHeadingLevel]);
+  // Streamdown's own chrome (code copy, table menus) reads the locale seam (#310).
+  // Spread AFTER so an explicit `translations` prop still wins (ADR 0017).
+  const translations = useStreamdownTranslations();
+  // Brand-token-derived `code` plugin, not the package's static github-*
+  // default (#315 follow-up) — re-derives when the active theme changes.
+  const plugins = useStreamdownPlugins();
+  return (
+    <Streamdown
+      data-slot="markdown-view"
+      className={cn("space-y-3 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0", className)}
+      components={components}
+      plugins={plugins}
+      translations={translations}
+      {...props}
+    >
+      {children}
+    </Streamdown>
+  );
+};