@elabs-ai/components-ai 4.0.0

package/src/confirmation.tsx

@@ -0,0 +1,273 @@
+"use client";
+
+import { Alert, AlertDescription, AlertTitle, StatusBadge } from "@elabs-ai/components-ui";
+import { Button } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { ToolUIPart } from "ai";
+import type { ComponentProps, ReactNode } from "react";
+import { createContext, useContext, useId, useMemo } from "react";
+
+type ToolUIPartApproval =
+  | {
+      id: string;
+      approved?: never;
+      reason?: never;
+    }
+  | {
+      id: string;
+      approved: boolean;
+      reason?: string;
+    }
+  | {
+      id: string;
+      approved: true;
+      reason?: string;
+    }
+  | {
+      id: string;
+      approved: false;
+      reason?: string;
+    }
+  | undefined;
+
+interface ConfirmationContextValue {
+  approval: ToolUIPartApproval;
+  state: ToolUIPart["state"];
+  /** Default id wired from the card's `aria-labelledby` to `ConfirmationTitle`. */
+  titleId: string;
+}
+
+const ConfirmationContext = createContext<ConfirmationContextValue | null>(null);
+
+const useConfirmation = () => {
+  const context = useContext(ConfirmationContext);
+
+  if (!context) {
+    throw new Error("Confirmation components must be used within Confirmation");
+  }
+
+  return context;
+};
+
+export type ConfirmationProps = ComponentProps<typeof Alert> & {
+  approval?: ToolUIPartApproval;
+  state: ToolUIPart["state"];
+};
+
+export const Confirmation = ({
+  className,
+  approval,
+  state,
+  variant,
+  role,
+  children,
+  ...props
+}: ConfirmationProps) => {
+  const titleId = useId();
+  const contextValue = useMemo(() => ({ approval, state, titleId }), [approval, state, titleId]);
+
+  if (!approval || state === "input-streaming" || state === "input-available") {
+    return null;
+  }
+
+  const isResolved =
+    state === "approval-responded" || state === "output-denied" || state === "output-available";
+  const isPending = state === "approval-requested";
+  const approved = isResolved ? approval.approved : undefined;
+
+  // QUIET-RAIL treatment (supersedes research-11's warning/status WASH — a
+  // deliberate design-authority decision to drop the filled "AI card" look):
+  // a neutral card ground (Alert variant="default") + ONE accent rail encoding
+  // the outcome, plus the StatusBadge (icon + label, never color alone). The
+  // rails are hue-independent enough to stay legible at high decoration / high-contrast.
+  // A caller-supplied `variant` still wins (escape hatch).
+  const railClass =
+    approved === true
+      ? "border-s-success"
+      : approved === false
+        ? "border-s-destructive"
+        : isPending
+          ? "border-s-border-strong"
+          : "border-s-border";
+
+  return (
+    <ConfirmationContext.Provider value={contextValue}>
+      <Alert
+        variant={variant ?? "default"}
+        // A pending decision containing focusable controls is a labelled
+        // region, NOT an assertive live region (research 11 §B.3): pending =
+        // role="group" + aria-labelledby; resolved keeps role="alert".
+        role={role ?? (isPending ? "group" : "alert")}
+        aria-labelledby={isPending ? titleId : undefined}
+        className={cn(
+          "flex flex-col gap-2 border-s-4 transition-colors duration-fast",
+          railClass,
+          isPending && "shadow-sm",
+          className,
+        )}
+        {...props}
+      >
+        {/* The status line is the canonical StatusBadge (#189, research 10 §B.1). */}
+        {approved === true ? (
+          <StatusBadge
+            className="animate-in fade-in-0 self-start duration-base ease-entrance"
+            status="complete"
+          >
+            Approved
+          </StatusBadge>
+        ) : null}
+        {approved === false ? (
+          <StatusBadge
+            className="animate-in fade-in-0 self-start duration-base ease-entrance"
+            status="denied"
+          >
+            Denied
+          </StatusBadge>
+        ) : null}
+        {children}
+      </Alert>
+    </ConfirmationContext.Provider>
+  );
+};
+
+export type ConfirmationTitleProps = ComponentProps<typeof AlertTitle>;
+
+/**
+ * The question zone (research 11 §B.3 APPROVE-3) — out-ranks the surrounding
+ * `text-body` and names the pending region via the card's `aria-labelledby`.
+ */
+export const ConfirmationTitle = ({ className, id, ...props }: ConfirmationTitleProps) => {
+  const { titleId } = useConfirmation();
+  return <AlertTitle id={id ?? titleId} className={cn("text-subtitle", className)} {...props} />;
+};
+
+export type ConfirmationDescriptionProps = ComponentProps<typeof AlertDescription>;
+
+/** The consequence zone — what approving will actually do (research 11 §B.3). */
+export const ConfirmationDescription = ({ className, ...props }: ConfirmationDescriptionProps) => (
+  <AlertDescription className={cn("text-body text-muted-foreground", className)} {...props} />
+);
+
+export interface ConfirmationRequestProps {
+  children?: ReactNode;
+}
+
+export const ConfirmationRequest = ({ children }: ConfirmationRequestProps) => {
+  const { state } = useConfirmation();
+
+  // Only show when approval is requested
+  if (state !== "approval-requested") {
+    return null;
+  }
+
+  return children;
+};
+
+export interface ConfirmationAcceptedProps {
+  children?: ReactNode;
+}
+
+export const ConfirmationAccepted = ({ children }: ConfirmationAcceptedProps) => {
+  const { approval, state } = useConfirmation();
+
+  // Only show when approved and in response states
+  if (
+    !approval?.approved ||
+    (state !== "approval-responded" && state !== "output-denied" && state !== "output-available")
+  ) {
+    return null;
+  }
+
+  return children;
+};
+
+export interface ConfirmationRejectedProps {
+  children?: ReactNode;
+}
+
+export const ConfirmationRejected = ({ children }: ConfirmationRejectedProps) => {
+  const { approval, state } = useConfirmation();
+
+  // Only show when rejected and in response states
+  if (
+    approval?.approved !== false ||
+    (state !== "approval-responded" && state !== "output-denied" && state !== "output-available")
+  ) {
+    return null;
+  }
+
+  return children;
+};
+
+export type ConfirmationActionsProps = ComponentProps<"div">;
+
+export const ConfirmationActions = ({ className, ...props }: ConfirmationActionsProps) => {
+  const { state } = useConfirmation();
+
+  // Only show when approval is requested
+  if (state !== "approval-requested") {
+    return null;
+  }
+
+  return (
+    <div
+      className={cn(
+        // The action band (research 11 §B.3 APPROVE-3): the divider is the SOLE
+        // cue between consequence and buttons, so `border-strong` is correct.
+        "flex w-full items-center justify-end gap-2 border-t border-border-strong pt-3",
+        className,
+      )}
+      {...props}
+    />
+  );
+};
+
+export type ConfirmationActionProps = ComponentProps<typeof Button>;
+
+export const ConfirmationAction = ({ className, ...props }: ConfirmationActionProps) => (
+  <Button className={cn("h-8 px-3 text-sm", className)} type="button" {...props} />
+);
+
+export type ConfirmationApproveProps = ConfirmationActionProps;
+
+/**
+ * The proceed action — presets the filled primary variant (research 11 §B.3
+ * APPROVE-2). Role-named so the primary path cannot drift to `outline`.
+ */
+export const ConfirmationApprove = (props: ConfirmationApproveProps) => (
+  <ConfirmationAction variant="default" {...props} />
+);
+
+export type ConfirmationDenyProps = ConfirmationActionProps;
+
+/** The decline action — presets the quiet `ghost` variant, never `outline`. */
+export const ConfirmationDeny = (props: ConfirmationDenyProps) => (
+  <ConfirmationAction variant="ghost" {...props} />
+);
+
+/*
+ * ApprovalCard — the promoted, semantically-named front door for the approval
+ * interaction (research 11 §B.3). Same components, clearer name; the
+ * `Confirmation*` exports stay for the AI-Elements-shaped API (non-breaking).
+ * New code reaches for `ApprovalCard`.
+ */
+export const ApprovalCard = Confirmation;
+export type ApprovalCardProps = ConfirmationProps;
+export const ApprovalCardTitle = ConfirmationTitle;
+export type ApprovalCardTitleProps = ConfirmationTitleProps;
+export const ApprovalCardDescription = ConfirmationDescription;
+export type ApprovalCardDescriptionProps = ConfirmationDescriptionProps;
+export const ApprovalCardRequest = ConfirmationRequest;
+export type ApprovalCardRequestProps = ConfirmationRequestProps;
+export const ApprovalCardAccepted = ConfirmationAccepted;
+export type ApprovalCardAcceptedProps = ConfirmationAcceptedProps;
+export const ApprovalCardRejected = ConfirmationRejected;
+export type ApprovalCardRejectedProps = ConfirmationRejectedProps;
+export const ApprovalCardActions = ConfirmationActions;
+export type ApprovalCardActionsProps = ConfirmationActionsProps;
+export const ApprovalCardAction = ConfirmationAction;
+export type ApprovalCardActionProps = ConfirmationActionProps;
+export const ApprovalCardApprove = ConfirmationApprove;
+export type ApprovalCardApproveProps = ConfirmationApproveProps;
+export const ApprovalCardDeny = ConfirmationDeny;
+export type ApprovalCardDenyProps = ConfirmationDenyProps;

package/src/connection.tsx

@@ -0,0 +1,23 @@
+import type { ConnectionLineComponent } from "@xyflow/react";
+
+const HALF = 0.5;
+
+export const Connection: ConnectionLineComponent = ({ fromX, fromY, toX, toY }) => (
+  <g>
+    <path
+      className="animated"
+      d={`M${fromX},${fromY} C ${fromX + (toX - fromX) * HALF},${fromY} ${fromX + (toX - fromX) * HALF},${toY} ${toX},${toY}`}
+      fill="none"
+      stroke="var(--color-ring)"
+      strokeWidth={1}
+    />
+    <circle
+      cx={toX}
+      cy={toY}
+      fill="var(--color-background)"
+      r={3}
+      stroke="var(--color-ring)"
+      strokeWidth={1}
+    />
+  </g>
+);

package/src/context-panel.stories.tsx

@@ -0,0 +1,137 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { AssetPreview } from "./asset-preview";
+import {
+  ContextPanel,
+  ContextPanelBody,
+  ContextPanelDetail,
+  ContextPanelHeader,
+  ContextPanelProvider,
+  ContextPanelSection,
+  ContextPanelTrigger,
+  useContextPanel,
+  type ContextAsset,
+  type ContextPanelProviderProps,
+} from "./context-panel";
+import { ProducedAssetTree } from "./file-tree";
+
+const meta = {
+  title: "AI/ContextPanel",
+  component: ContextPanel,
+  tags: ["autodocs"],
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof ContextPanel>;
+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%)
+
+> Watch APAC churn — flagged by the variance check.
+`;
+
+const ASSETS: ContextAsset[] = [
+  { id: "board-note", name: "board-note.md", type: "markdown", content: BOARD_NOTE },
+  {
+    id: "variance-query",
+    name: "variance-check.sql",
+    type: "sql",
+    content: "SELECT region, total\nFROM finance.revenue\nWHERE quarter = 'Q3';",
+  },
+  {
+    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",
+  },
+];
+
+/** Root view — the three labelled sections (research 09 §C.2). */
+function RailRoot() {
+  const { state, actions } = useContextPanel();
+  return (
+    <>
+      <ContextPanelSection label="Status">
+        <p className="text-body text-muted-foreground">Context 21% · model atlas-fast</p>
+      </ContextPanelSection>
+      <ContextPanelSection label="Produced assets">
+        <ProducedAssetTree
+          assets={ASSETS}
+          selectedId={state.selectedAsset?.id}
+          onSelect={actions.openDetail}
+        />
+      </ContextPanelSection>
+    </>
+  );
+}
+
+/** Detail view — the focused asset, drill-in target (research 04 §5). */
+function RailDetail() {
+  const { state } = useContextPanel();
+  return (
+    <ContextPanelDetail>
+      {state.selectedAsset ? (
+        <AssetPreview asset={state.selectedAsset} />
+      ) : (
+        <p className="text-body text-muted-foreground">Select an asset to preview it…</p>
+      )}
+    </ContextPanelDetail>
+  );
+}
+
+/**
+ * The provider wraps the WORKSPACE; the trigger lives in the app header and the
+ * panel is a sibling of the chat (the Sidebar / SidebarInset relationship) —
+ * ChatShell stays generic (research 09 §C.2/§C.3).
+ */
+function WorkspaceDemo(providerProps: Omit<ContextPanelProviderProps, "children">) {
+  return (
+    <ContextPanelProvider {...providerProps}>
+      <div className="flex h-[520px] w-full overflow-hidden rounded-xl border bg-background">
+        <div className="flex min-w-0 flex-1 flex-col">
+          <header className="flex h-12 shrink-0 items-center justify-between border-b px-4">
+            <span className="text-subtitle">Agentic workspace</span>
+            <ContextPanelTrigger />
+          </header>
+          <div className="flex-1 overflow-y-auto p-4">
+            <p className="max-w-prose text-body text-muted-foreground">
+              The conversation renders here. The context panel is an always-mounted sibling: the
+              header trigger collapses it (width tween, no conditional mount), and selecting a
+              produced asset drills into the detail view inside the same rail.
+            </p>
+          </div>
+        </div>
+        <ContextPanel>
+          <ContextPanelHeader title="Context" />
+          <ContextPanelBody root={<RailRoot />} detail={<RailDetail />} />
+        </ContextPanel>
+      </div>
+    </ContextPanelProvider>
+  );
+}
+
+/** Root view, expanded — toggle via the header trigger, click a row to drill in. */
+export const Default: Story = {
+  render: () => <WorkspaceDemo defaultOpen />,
+};
+
+/** Detail view — the drill-in target with the BACK control in the header. */
+export const DetailView: Story = {
+  render: () => <WorkspaceDemo defaultOpen defaultView="detail" defaultSelectedAsset={ASSETS[0]} />,
+};
+
+/** Collapsed — still mounted (data-state="collapsed"), inert, ready to tween open. */
+export const Collapsed: Story = {
+  render: () => <WorkspaceDemo defaultOpen={false} />,
+};
+
+/** Below the mobile breakpoint the same state drives a Sheet (research 09 §B.4). */
+export const Mobile: Story = {
+  globals: { viewport: { value: "mobile1", isRotated: false } },
+  render: () => <WorkspaceDemo />,
+};

package/src/context-panel.test.tsx

@@ -0,0 +1,198 @@
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  ContextPanel,
+  ContextPanelBody,
+  ContextPanelDetail,
+  ContextPanelHeader,
+  ContextPanelProvider,
+  ContextPanelSection,
+  ContextPanelTrigger,
+  useContextPanel,
+  type ContextAsset,
+  type ContextPanelProviderProps,
+} from "./context-panel";
+import { ProducedAssetTree } from "./file-tree";
+
+beforeAll(() => {
+  // jsdom has no matchMedia (useIsMobile drives the mobile Sheet fallback).
+  window.matchMedia = ((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: () => undefined,
+    removeListener: () => undefined,
+    addEventListener: () => undefined,
+    removeEventListener: () => undefined,
+    dispatchEvent: () => false,
+  })) as unknown as typeof window.matchMedia;
+});
+
+afterEach(cleanup);
+
+const ASSETS: ContextAsset[] = [
+  { id: "board-note", name: "board-note.md", type: "markdown", content: "# Note" },
+  { id: "revenue", name: "revenue.csv", type: "csv", content: "region,total\nEMEA,1" },
+];
+
+function RootSections() {
+  const { state, actions } = useContextPanel();
+  return (
+    <ContextPanelSection label="Produced assets">
+      <ProducedAssetTree
+        assets={ASSETS}
+        selectedId={state.selectedAsset?.id}
+        onSelect={actions.openDetail}
+      />
+    </ContextPanelSection>
+  );
+}
+
+function DetailHost() {
+  const { state } = useContextPanel();
+  return <div data-testid="detail-content">{state.selectedAsset?.name ?? "No asset"}</div>;
+}
+
+function Workspace(providerProps: Omit<ContextPanelProviderProps, "children"> = {}) {
+  return (
+    <ContextPanelProvider {...providerProps}>
+      <header>
+        <ContextPanelTrigger />
+      </header>
+      <ContextPanel data-testid="panel">
+        <ContextPanelHeader title="Context" />
+        <ContextPanelBody
+          root={<RootSections />}
+          detail={
+            <ContextPanelDetail>
+              <DetailHost />
+            </ContextPanelDetail>
+          }
+        />
+      </ContextPanel>
+    </ContextPanelProvider>
+  );
+}
+
+describe("ContextPanel collapse (#193, research 09 §B.2)", () => {
+  it("is always mounted and collapses via data-state, never a conditional mount", async () => {
+    const user = userEvent.setup();
+    render(<Workspace />);
+
+    const panel = screen.getByTestId("panel");
+    const trigger = screen.getByRole("button", { name: "Toggle context panel" });
+
+    expect(panel).toHaveAttribute("data-state", "expanded");
+    expect(panel).toHaveAttribute("data-side", "right");
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    expect(trigger).toHaveAttribute("aria-controls", panel.id);
+
+    await user.click(trigger);
+
+    // Still in the DOM (the whole point — width tweens need a mounted node)…
+    expect(screen.getByTestId("panel")).toBe(panel);
+    // …but collapsed and inert (research 09 §B.5).
+    expect(panel).toHaveAttribute("data-state", "collapsed");
+    expect(panel).toHaveAttribute("inert");
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("respects controlled open (mode never flips)", async () => {
+    const onOpenChange = vi.fn();
+    const user = userEvent.setup();
+    render(<Workspace open={false} onOpenChange={onOpenChange} />);
+
+    const panel = screen.getByTestId("panel");
+    expect(panel).toHaveAttribute("data-state", "collapsed");
+
+    await user.click(screen.getByRole("button", { name: "Toggle context panel" }));
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+    // Controlled: the prop still says closed.
+    expect(panel).toHaveAttribute("data-state", "collapsed");
+  });
+
+  it("throws when useContextPanel is used outside the provider", () => {
+    const Naked = () => {
+      useContextPanel();
+      return null;
+    };
+    expect(() => render(<Naked />)).toThrow(/within a ContextPanelProvider/);
+  });
+});
+
+describe("ContextPanel drill-in a11y (#193, research 09 §B.5 tab-panel swap)", () => {
+  it("moves focus to the BACK control, inerts the off-screen pane and announces", async () => {
+    const user = userEvent.setup();
+    const { container } = render(<Workspace />);
+
+    const rootPane = container.querySelector('[data-vt-pane="root"]') as HTMLElement;
+    const detailPane = container.querySelector('[data-vt-pane="detail"]') as HTMLElement;
+    expect(rootPane).not.toHaveAttribute("inert");
+    expect(detailPane).toHaveAttribute("inert");
+    expect(detailPane).toHaveAttribute("aria-hidden", "true");
+
+    await user.click(screen.getByText("board-note.md"));
+
+    // The detail pane is now the live one; the root pane is off-screen.
+    expect(detailPane).not.toHaveAttribute("inert");
+    expect(rootPane).toHaveAttribute("inert");
+    expect(rootPane).toHaveAttribute("aria-hidden", "true");
+    expect(screen.getByTestId("detail-content")).toHaveTextContent("board-note.md");
+
+    // Focus lands on the BACK control after the swap (rAF, animation-independent).
+    const back = screen.getByRole("button", { name: "Back to context" });
+    await waitFor(() => expect(back).toHaveFocus());
+
+    // The polite live region announced the target.
+    expect(container.querySelector('[aria-live="polite"]')).toHaveTextContent(
+      "Showing board-note.md",
+    );
+  });
+
+  it("returns focus to the originating row on back", async () => {
+    const user = userEvent.setup();
+    const { container } = render(<Workspace />);
+
+    const row = screen.getByText("board-note.md").closest('[role="treeitem"]') as HTMLElement;
+    await user.click(screen.getByText("board-note.md"));
+
+    const back = screen.getByRole("button", { name: "Back to context" });
+    await waitFor(() => expect(back).toHaveFocus());
+    await user.click(back);
+
+    const rootPane = container.querySelector('[data-vt-pane="root"]') as HTMLElement;
+    expect(rootPane).not.toHaveAttribute("inert");
+    await waitFor(() => expect(row).toHaveFocus());
+    expect(container.querySelector('[aria-live="polite"]')).toHaveTextContent("Back to context");
+  });
+
+  it("auto-opens a collapsed panel when drilling in (research 09 §G.1)", async () => {
+    const user = userEvent.setup();
+
+    // External drive: a row is unreachable while the panel is inert, so use a
+    // consumer control (the lifted-state story — actions work from anywhere).
+    function ExternalOpen() {
+      const { actions } = useContextPanel();
+      return (
+        <button type="button" onClick={() => actions.openDetail(ASSETS[1] as ContextAsset)}>
+          Open revenue
+        </button>
+      );
+    }
+    render(
+      <ContextPanelProvider defaultOpen={false}>
+        <ExternalOpen />
+        <ContextPanel data-testid="panel">
+          <ContextPanelHeader />
+          <ContextPanelBody root={<RootSections />} detail={<DetailHost />} />
+        </ContextPanel>
+      </ContextPanelProvider>,
+    );
+    expect(screen.getByTestId("panel")).toHaveAttribute("data-state", "collapsed");
+
+    await user.click(screen.getByRole("button", { name: "Open revenue" }));
+    expect(screen.getByTestId("panel")).toHaveAttribute("data-state", "expanded");
+    expect(screen.getByRole("button", { name: "Back to context" })).toBeInTheDocument();
+  });
+});