@elabs-ai/components-ai 4.0.0

package/src/artifact.stories.tsx

@@ -0,0 +1,62 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { DownloadIcon } from "lucide-react";
+import {
+  Artifact,
+  ArtifactAction,
+  ArtifactActions,
+  ArtifactClose,
+  ArtifactContent,
+  ArtifactDescription,
+  ArtifactHeader,
+  ArtifactTitle,
+} from "./artifact";
+
+const meta = {
+  title: "AI/Artifact",
+  component: Artifact,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Artifact>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <Artifact className="max-w-lg">
+      <ArtifactHeader>
+        <div>
+          <ArtifactTitle>Q3 retention cohort</ArtifactTitle>
+          <ArtifactDescription>Generated report</ArtifactDescription>
+        </div>
+        <ArtifactActions>
+          <ArtifactAction icon={DownloadIcon} tooltip="Download" />
+          <ArtifactClose />
+        </ArtifactActions>
+      </ArtifactHeader>
+      <ArtifactContent>
+        Enterprise churn fell 0.4pp to 1.8% this quarter, driven by the renewal-desk rollout.
+      </ArtifactContent>
+    </Artifact>
+  ),
+};
+
+// LOADING — the body hasn't arrived yet (loading-states.md `loading`).
+// `ArtifactContent` renders a layout-shaped skeleton while `ArtifactHeader` /
+// `ArtifactTitle` keep rendering normally, so the artifact's identity stays
+// visible while its content streams in.
+export const Loading: Story = {
+  render: () => (
+    <Artifact className="max-w-lg" loading>
+      <ArtifactHeader>
+        <div>
+          <ArtifactTitle>Q3 retention cohort</ArtifactTitle>
+          <ArtifactDescription>Generating report…</ArtifactDescription>
+        </div>
+        <ArtifactActions>
+          <ArtifactAction icon={DownloadIcon} tooltip="Download" disabled />
+          <ArtifactClose />
+        </ArtifactActions>
+      </ArtifactHeader>
+      <ArtifactContent>This content is not shown while loading.</ArtifactContent>
+    </Artifact>
+  ),
+};

package/src/artifact.test.tsx

@@ -0,0 +1,112 @@
+/**
+ * artifact.test.tsx — smoke + naming lock for the generated-artifact frame (#59).
+ *
+ * `Artifact` is the panel a generated document/preview lands in. Every control
+ * in its header is ICON-ONLY, so the assertions that matter are accessible
+ * names: `ArtifactClose` must always announce "Close", and `ArtifactAction`
+ * must fall back to its tooltip text when no explicit label is given — an
+ * unnamed icon button is a WCAG 4.1.2 failure and is invisible in review.
+ *
+ * The frame's `border` is also locked here: it reads redundant on a light theme
+ * (the recess + shadow already lift it) but at high decoration/decoration the
+ * shadow is zeroed and the border becomes the SOLE structural cue — the
+ * canonical "redundant-on-light, sole-cue-under-decoration" KEEP (#194).
+ */
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { SaveIcon } from "lucide-react";
+import {
+  Artifact,
+  ArtifactAction,
+  ArtifactActions,
+  ArtifactClose,
+  ArtifactContent,
+  ArtifactDescription,
+  ArtifactHeader,
+  ArtifactTitle,
+} from "./artifact";
+
+describe("Artifact — frame", () => {
+  it("renders header, title, description and content together", () => {
+    render(
+      <Artifact>
+        <ArtifactHeader>
+          <ArtifactTitle>Q3 forecast</ArtifactTitle>
+          <ArtifactDescription>Generated from the pipeline export</ArtifactDescription>
+        </ArtifactHeader>
+        <ArtifactContent>body</ArtifactContent>
+      </Artifact>,
+    );
+    expect(screen.getByText("Q3 forecast")).toBeInTheDocument();
+    expect(screen.getByText("Generated from the pipeline export")).toBeInTheDocument();
+    expect(screen.getByText("body")).toBeInTheDocument();
+  });
+
+  it("keeps its border (#194 — the sole structural cue once decoration zeroes the shadow)", () => {
+    const { container } = render(<Artifact>x</Artifact>);
+    expect(container.firstChild).toHaveClass("border");
+  });
+
+  it("merges a caller className without dropping the frame", () => {
+    const { container } = render(<Artifact className="extra">x</Artifact>);
+    expect(container.firstChild).toHaveClass("extra");
+    expect(container.firstChild).toHaveClass("rounded-lg");
+  });
+
+  it("spreads arbitrary props onto the root (id/aria-*)", () => {
+    const { container } = render(
+      <Artifact id="a1" aria-label="Forecast artifact">
+        x
+      </Artifact>,
+    );
+    expect(container.firstChild).toHaveAttribute("id", "a1");
+    expect(screen.getByLabelText("Forecast artifact")).toBeInTheDocument();
+  });
+});
+
+describe("ArtifactClose — icon-only naming", () => {
+  it('always announces "Close" even though it renders only a glyph', () => {
+    render(<ArtifactClose />);
+    expect(screen.getByRole("button", { name: "Close" })).toBeInTheDocument();
+  });
+
+  it("calls onClick", () => {
+    const onClick = vi.fn();
+    render(<ArtifactClose onClick={onClick} />);
+    fireEvent.click(screen.getByRole("button", { name: "Close" }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('is type="button" so it cannot submit a surrounding form', () => {
+    render(<ArtifactClose />);
+    expect(screen.getByRole("button", { name: "Close" })).toHaveAttribute("type", "button");
+  });
+});
+
+describe("ArtifactAction — icon-only naming", () => {
+  it("takes its accessible name from label", () => {
+    render(<ArtifactAction icon={SaveIcon} label="Save to workspace" />);
+    expect(screen.getByRole("button", { name: "Save to workspace" })).toBeInTheDocument();
+  });
+
+  it("falls back to the tooltip text when no label is given (never an unnamed button)", () => {
+    render(<ArtifactAction icon={SaveIcon} tooltip="Save" />);
+    expect(screen.getByRole("button", { name: "Save" })).toBeInTheDocument();
+  });
+
+  it("renders inside a tooltip trigger without losing the name", () => {
+    render(
+      <ArtifactActions>
+        <ArtifactAction icon={SaveIcon} tooltip="Save" label="Save to workspace" />
+      </ArtifactActions>,
+    );
+    expect(screen.getByRole("button", { name: "Save to workspace" })).toBeInTheDocument();
+  });
+
+  it("calls onClick", () => {
+    const onClick = vi.fn();
+    render(<ArtifactAction icon={SaveIcon} label="Save" onClick={onClick} />);
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});

package/src/artifact.tsx

@@ -0,0 +1,167 @@
+"use client";
+
+import { Button, Skeleton, useLocale } from "@elabs-ai/components-ui";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { LucideIcon } from "lucide-react";
+import { XIcon } from "lucide-react";
+import type { ComponentProps, HTMLAttributes } from "react";
+import { createContext, use, useMemo } from "react";
+
+/**
+ * Shared `loading` state (composition-patterns — lifted into the provider):
+ * `Artifact` is the ONLY place that knows whether the body has arrived;
+ * `ArtifactContent` reads the interface and renders its skeleton, while
+ * `ArtifactHeader`/`ArtifactTitle` (ordinary children of `Artifact`) keep
+ * rendering normally, untouched by the not-ready state.
+ */
+const ArtifactContext = createContext<{ loading: boolean }>({ loading: false });
+
+export type ArtifactProps = HTMLAttributes<HTMLDivElement> & {
+  /**
+   * The artifact body has not arrived yet (loading-states.md loading signal).
+   * ArtifactContent renders a layout-shaped skeleton instead of its
+   * children; ArtifactHeader/ArtifactTitle keep rendering as passed.
+   * @default false
+   */
+  loading?: boolean;
+};
+
+export const Artifact = ({ className, loading = false, children, ...props }: ArtifactProps) => {
+  const contextValue = useMemo(() => ({ loading }), [loading]);
+
+  return (
+    <ArtifactContext.Provider value={contextValue}>
+      <div
+        // KEEP this border (#194, research 08 §G.5): it is redundant on light
+        // (the #187 page-ground recess + shadow already lift the frame), but under
+        // high decoration the shadow is zeroed and the border becomes the
+        // SOLE structural cue — the canonical "redundant-on-light, sole-cue-under-
+        // decoration" KEEP example. Do not drop it in a border-noise pass.
+        className={cn(
+          "flex flex-col overflow-hidden rounded-lg border bg-background shadow-sm",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    </ArtifactContext.Provider>
+  );
+};
+
+export type ArtifactHeaderProps = HTMLAttributes<HTMLDivElement>;
+
+export const ArtifactHeader = ({ className, ...props }: ArtifactHeaderProps) => (
+  <div
+    className={cn("flex items-center justify-between border-b bg-muted/50 px-4 py-3", className)}
+    {...props}
+  />
+);
+
+export type ArtifactCloseProps = ComponentProps<typeof Button>;
+
+export const ArtifactClose = ({
+  className,
+  children,
+  size = "sm",
+  variant = "ghost",
+  ...props
+}: ArtifactCloseProps) => (
+  <Button
+    className={cn("size-8 p-0 text-muted-foreground hover:text-foreground", className)}
+    size={size}
+    type="button"
+    variant={variant}
+    {...props}
+  >
+    {children ?? <XIcon className="size-4" />}
+    <span className="sr-only">Close</span>
+  </Button>
+);
+
+export type ArtifactTitleProps = HTMLAttributes<HTMLParagraphElement>;
+
+export const ArtifactTitle = ({ className, ...props }: ArtifactTitleProps) => (
+  <p className={cn("font-medium text-foreground text-sm", className)} {...props} />
+);
+
+export type ArtifactDescriptionProps = HTMLAttributes<HTMLParagraphElement>;
+
+export const ArtifactDescription = ({ className, ...props }: ArtifactDescriptionProps) => (
+  <p className={cn("text-muted-foreground text-sm", className)} {...props} />
+);
+
+export type ArtifactActionsProps = HTMLAttributes<HTMLDivElement>;
+
+export const ArtifactActions = ({ className, ...props }: ArtifactActionsProps) => (
+  <div className={cn("flex items-center gap-1", className)} {...props} />
+);
+
+export type ArtifactActionProps = ComponentProps<typeof Button> & {
+  tooltip?: string;
+  label?: string;
+  icon?: LucideIcon;
+};
+
+export const ArtifactAction = ({
+  tooltip,
+  label,
+  icon: Icon,
+  children,
+  className,
+  size = "sm",
+  variant = "ghost",
+  ...props
+}: ArtifactActionProps) => {
+  const button = (
+    <Button
+      className={cn("size-8 p-0 text-muted-foreground hover:text-foreground", className)}
+      size={size}
+      type="button"
+      variant={variant}
+      {...props}
+    >
+      {Icon ? <Icon className="size-4" /> : children}
+      <span className="sr-only">{label || tooltip}</span>
+    </Button>
+  );
+
+  if (tooltip) {
+    return (
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger asChild>{button}</TooltipTrigger>
+          <TooltipContent>
+            <p>{tooltip}</p>
+          </TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    );
+  }
+
+  return button;
+};
+
+export type ArtifactContentProps = HTMLAttributes<HTMLDivElement>;
+
+export const ArtifactContent = ({ className, children, ...props }: ArtifactContentProps) => {
+  const { loading } = use(ArtifactContext);
+  const { t } = useLocale();
+
+  return (
+    <div className={cn("flex-1 overflow-auto p-4", className)} {...props}>
+      {loading ? (
+        <div className="space-y-2" role="status" aria-live="polite">
+          <span className="sr-only">{t("loading")}</span>
+          <Skeleton className="h-4 w-3/4" />
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-5/6" />
+          <Skeleton className="h-4 w-1/2" />
+        </div>
+      ) : (
+        children
+      )}
+    </div>
+  );
+};

package/src/asset-preview.stories.tsx

@@ -0,0 +1,100 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { AssetPreview } from "./asset-preview";
+
+const meta = {
+  title: "AI/AssetPreview",
+  component: AssetPreview,
+  tags: ["autodocs"],
+  parameters: { layout: "padded" },
+  decorators: [
+    (Story) => (
+      // The real host is the 20rem context rail — preview at that width.
+      <div className="max-w-80">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof AssetPreview>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const BOARD_NOTE = `# Board note — Q3
+
+Revenue grew **12.4% QoQ**, led by EMEA.
+
+## Highlights
+
+- EMEA $18.4M (+14%)
+- Americas $21.2M (+8%)
+`;
+
+/** Markdown renders as a DOCUMENT via MarkdownView (the ASSET-2 fix) — toggle Raw for source. */
+export const Markdown: Story = {
+  args: {
+    asset: { id: "board-note", name: "board-note.md", type: "markdown", content: BOARD_NOTE },
+  },
+};
+
+/** Code/SQL renders via CodeBlock (Shiki), soft-wrapped for the narrow rail. */
+export const Sql: Story = {
+  args: {
+    asset: {
+      id: "variance-query",
+      name: "variance-check.sql",
+      type: "sql",
+      content: "SELECT region, total\nFROM finance.revenue\nWHERE quarter = 'Q3';",
+    },
+  },
+};
+
+/** CSV renders as a small table with a row-count summary. */
+export const Csv: Story = {
+  args: {
+    asset: {
+      id: "revenue",
+      name: "revenue.csv",
+      type: "csv",
+      content: "region,q2,q3\nEMEA,16.1,18.4\nAmericas,19.6,21.2\nAPAC,7.2,8.6",
+    },
+  },
+};
+
+/** Raw mode as the initial state. */
+export const RawByDefault: Story = {
+  args: {
+    asset: { id: "board-note", name: "board-note.md", type: "markdown", content: BOARD_NOTE },
+    defaultMode: "raw",
+  },
+};
+
+/**
+ * A format this package cannot parse, drawn by an injected renderer.
+ *
+ * `renderPreview` is how a PDF, a spreadsheet or a video reaches the rail:
+ * `@elabs-ai/components-viewer` is a layer PEER of this package, so
+ * neither may import the other (ADR 0024 §6) and the consuming app owns the
+ * edge — `renderPreview={(asset) => asset.source ? <FileViewer source={asset.source} /> : null}`.
+ * The stand-in below keeps this story free of that import.
+ *
+ * A renderer that returns `null` declines, so every built-in format above is
+ * untouched by an injection that only knows PDFs.
+ */
+export const InjectedRenderer: Story = {
+  args: {
+    asset: {
+      id: "audit-report",
+      name: "audit-report.pdf",
+      // The type union stays closed: a PDF arrives as a `source`, it does not
+      // add a case here.
+      type: "code",
+      mediaType: "application/pdf",
+      source: { kind: "url", url: "/audit-report.pdf", name: "audit-report.pdf" },
+    },
+    renderPreview: (asset) =>
+      asset.source ? (
+        <div className="bg-surface-muted text-body text-muted-foreground rounded-md p-4">
+          Rendered by the injected viewer: {asset.name}
+        </div>
+      ) : null,
+  },
+};

package/src/asset-preview.test.tsx

@@ -0,0 +1,126 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it } from "vitest";
+import { AssetPreview } from "./asset-preview";
+import { ContextPanelProvider, type ContextAsset } from "./context-panel";
+
+afterEach(cleanup);
+
+const MARKDOWN_ASSET: ContextAsset = {
+  id: "board-note",
+  name: "board-note.md",
+  type: "markdown",
+  content: "# Quarterly summary\n\nRevenue grew.",
+};
+
+const CSV_ASSET: ContextAsset = {
+  id: "revenue",
+  name: "revenue.csv",
+  type: "csv",
+  content: "region,total\nEMEA,16.1\nAmericas,19.6",
+};
+
+describe("AssetPreview (#193, research 04 §5 ASSET-4)", () => {
+  it("renders markdown as a document (the ASSET-2 fix), with a Preview/Raw toggle", async () => {
+    const user = userEvent.setup();
+    render(<AssetPreview asset={MARKDOWN_ASSET} />);
+
+    // Artifact chrome: the asset name headline.
+    expect(screen.getByText("board-note.md")).toBeInTheDocument();
+    // Preview = a real heading, not Shiki source.
+    expect(screen.getByRole("heading", { name: "Quarterly summary" })).toBeInTheDocument();
+    // Constrained rung: never an h1 inside the rail (research 09 §G.2).
+    expect(screen.queryByRole("heading", { level: 1 })).not.toBeInTheDocument();
+
+    // Raw shows the markdown source instead.
+    await user.click(screen.getByRole("button", { name: "Raw" }));
+    expect(screen.queryByRole("heading", { name: "Quarterly summary" })).not.toBeInTheDocument();
+    expect(screen.getByText(/# Quarterly summary/)).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Raw" })).toHaveAttribute("aria-pressed", "true");
+  });
+
+  it("renders csv as a small table with a row-count summary", () => {
+    render(<AssetPreview asset={CSV_ASSET} />);
+    expect(screen.getByRole("table")).toBeInTheDocument();
+    expect(screen.getByText("EMEA")).toBeInTheDocument();
+    expect(screen.getByText("2 rows")).toBeInTheDocument();
+  });
+
+  it("renders an empty state for missing content, never broken UI", () => {
+    render(<AssetPreview asset={{ id: "x", name: "empty.md", type: "markdown" }} />);
+    expect(screen.getByText("No preview available…")).toBeInTheDocument();
+    // No Raw toggle without raw source.
+    expect(screen.queryByRole("button", { name: "Raw" })).not.toBeInTheDocument();
+  });
+});
+
+/**
+ * The seam that lets a format this package cannot parse (a PDF, a spreadsheet,
+ * a video) show up in the rail without `@elabs-ai/components-ai`
+ * importing `@elabs-ai/components-viewer` — they are layer peers
+ * (ADR 0024 §6). The injection stands in for `FileViewer` here.
+ */
+describe("AssetPreview — renderPreview injection", () => {
+  const PDF_ASSET: ContextAsset = {
+    id: "report",
+    name: "report.pdf",
+    // The union stays closed: a PDF arrives as `code` + a `source`, it does not
+    // grow a `ContextAssetType` case.
+    type: "code",
+    mediaType: "application/pdf",
+    source: { kind: "url", url: "https://example.com/report.pdf", name: "report.pdf" },
+  };
+
+  it("draws a format the built-in switch cannot, instead of 'No preview available…'", () => {
+    render(
+      <AssetPreview
+        asset={PDF_ASSET}
+        renderPreview={(asset) => (asset.source ? <p>viewer: {asset.name}</p> : null)}
+      />,
+    );
+    expect(screen.getByText("viewer: report.pdf")).toBeInTheDocument();
+    expect(screen.queryByText("No preview available…")).not.toBeInTheDocument();
+  });
+
+  it("is additive — a renderer that declines leaves every built-in format alone", () => {
+    // The whole point of the `null` return: an injection that only knows PDFs
+    // must not take markdown away from `MarkdownView`.
+    render(
+      <AssetPreview
+        asset={MARKDOWN_ASSET}
+        renderPreview={(asset) => (asset.mediaType === "application/pdf" ? <p>viewer</p> : null)}
+      />,
+    );
+    expect(screen.getByRole("heading", { name: "Quarterly summary" })).toBeInTheDocument();
+    expect(screen.queryByText("viewer")).not.toBeInTheDocument();
+  });
+
+  it("takes an injection from the surrounding provider, so a rail is taught once", () => {
+    render(
+      <ContextPanelProvider renderPreview={(asset) => <p>rail: {asset.name}</p>}>
+        <AssetPreview asset={PDF_ASSET} />
+      </ContextPanelProvider>,
+    );
+    expect(screen.getByText("rail: report.pdf")).toBeInTheDocument();
+  });
+
+  it("lets an explicit prop win over the provider's renderer", () => {
+    render(
+      <ContextPanelProvider renderPreview={() => <p>rail</p>}>
+        <AssetPreview asset={PDF_ASSET} renderPreview={() => <p>this one</p>} />
+      </ContextPanelProvider>,
+    );
+    expect(screen.getByText("this one")).toBeInTheDocument();
+    expect(screen.queryByText("rail")).not.toBeInTheDocument();
+  });
+
+  it("never intercepts Raw — Raw means 'show me the source'", async () => {
+    const user = userEvent.setup();
+    render(<AssetPreview asset={MARKDOWN_ASSET} renderPreview={() => <p>injected preview</p>} />);
+    expect(screen.getByText("injected preview")).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "Raw" }));
+    expect(screen.queryByText("injected preview")).not.toBeInTheDocument();
+    expect(screen.getByText(/# Quarterly summary/)).toBeInTheDocument();
+  });
+});