@elabs-ai/components-data 4.0.0

package/src/search-input/search-input.test.tsx

@@ -0,0 +1,99 @@
+/**
+ * search-input.test.tsx — smoke + behaviour lock for the table search field (#59).
+ *
+ * SearchInput is one of the four filter primitives DataTable's `toolbar`
+ * render-prop drives; until #59 it was only exercised indirectly, inside
+ * data-table.stories.tsx. The load-bearing contract is: a real labelled
+ * `<input>` (no placeholder-as-label), every keystroke reported to the caller,
+ * and a named clear affordance that only exists when there is something to clear.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { SearchInput } from "./search-input";
+
+describe("SearchInput — accessible name", () => {
+  it("exposes a textbox named by the visually-hidden label (not the placeholder)", () => {
+    render(<SearchInput value="" onValueChange={vi.fn()} />);
+    expect(screen.getByRole("textbox", { name: "Search" })).toBeInTheDocument();
+  });
+
+  it("uses a custom label when supplied", () => {
+    render(<SearchInput value="" onValueChange={vi.fn()} label="Filter deployments" />);
+    expect(screen.getByRole("textbox", { name: "Filter deployments" })).toBeInTheDocument();
+  });
+
+  it("wires the <label> to the input via a generated id (clicking the label focuses it)", () => {
+    render(<SearchInput value="" onValueChange={vi.fn()} />);
+    const input = screen.getByRole("textbox", { name: "Search" });
+    const label = document.querySelector("label");
+    expect(label).not.toBeNull();
+    expect(label).toHaveAttribute("for", input.getAttribute("id"));
+  });
+});
+
+describe("SearchInput — value reporting", () => {
+  it("calls onValueChange with the typed value", () => {
+    const onValueChange = vi.fn();
+    render(<SearchInput value="" onValueChange={onValueChange} />);
+    fireEvent.change(screen.getByRole("textbox", { name: "Search" }), {
+      target: { value: "billing" },
+    });
+    expect(onValueChange).toHaveBeenCalledWith("billing");
+  });
+
+  it("is controlled — it renders the value prop, not internal state", () => {
+    const { rerender } = render(<SearchInput value="alpha" onValueChange={vi.fn()} />);
+    expect(screen.getByRole("textbox", { name: "Search" })).toHaveValue("alpha");
+    rerender(<SearchInput value="beta" onValueChange={vi.fn()} />);
+    expect(screen.getByRole("textbox", { name: "Search" })).toHaveValue("beta");
+  });
+});
+
+describe("SearchInput — clear affordance", () => {
+  it("renders no clear button while the field is empty", () => {
+    render(<SearchInput value="" onValueChange={vi.fn()} />);
+    expect(screen.queryByRole("button", { name: "Clear search" })).toBeNull();
+  });
+
+  it("renders a NAMED clear button once there is a value (icon-only control, WCAG 4.1.2)", () => {
+    render(<SearchInput value="billing" onValueChange={vi.fn()} />);
+    expect(screen.getByRole("button", { name: "Clear search" })).toBeInTheDocument();
+  });
+
+  it("clears the value through the caller's handler", () => {
+    const onValueChange = vi.fn();
+    render(<SearchInput value="billing" onValueChange={onValueChange} />);
+    fireEvent.click(screen.getByRole("button", { name: "Clear search" }));
+    expect(onValueChange).toHaveBeenCalledWith("");
+  });
+
+  it("hides its glyph from assistive tech (the button carries the name)", () => {
+    render(<SearchInput value="billing" onValueChange={vi.fn()} />);
+    const svg = screen.getByRole("button", { name: "Clear search" }).querySelector("svg");
+    expect(svg).toHaveAttribute("aria-hidden", "true");
+  });
+});
+
+describe("SearchInput — composability", () => {
+  it("spreads arbitrary input props (id/name/autocomplete) onto the field", () => {
+    render(
+      <SearchInput value="" onValueChange={vi.fn()} name="q" autoComplete="off" data-testid="f" />,
+    );
+    const input = screen.getByTestId("f");
+    expect(input).toHaveAttribute("name", "q");
+    expect(input).toHaveAttribute("autocomplete", "off");
+  });
+
+  it("merges className onto the input and containerClassName onto the wrapper", () => {
+    const { container } = render(
+      <SearchInput
+        value=""
+        onValueChange={vi.fn()}
+        className="input-extra"
+        containerClassName="wrap-extra"
+      />,
+    );
+    expect(container.firstChild).toHaveClass("wrap-extra");
+    expect(screen.getByRole("textbox", { name: "Search" })).toHaveClass("input-extra");
+  });
+});

package/src/search-input/search-input.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import { useId, type InputHTMLAttributes } from "react";
+import { Input } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { SearchIcon } from "@elabs-ai/components-icons";
+
+export interface SearchInputProps extends Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  "onChange" | "value"
+> {
+  value: string;
+  onValueChange: (value: string) => void;
+  /** Visually-hidden accessible label. Defaults to "Search". */
+  label?: string;
+  containerClassName?: string;
+}
+
+/**
+ * Search field with a leading icon and a clear button. Controlled.
+ *
+ * `disabled` (available via the extended `InputHTMLAttributes`) is how a
+ * consumer signals a pending fetch (D5 — the app owns fetch state, this
+ * control just reflects it; see loading-states.md). It is forwarded to the
+ * `<Input>` explicitly AND gates the clear button — while disabled the clear
+ * affordance is hidden so it can't mutate the filter mid-request (#269/#8).
+ */
+export function SearchInput({
+  value,
+  onValueChange,
+  label = "Search",
+  placeholder = "Search…",
+  className,
+  containerClassName,
+  disabled,
+  ...props
+}: SearchInputProps) {
+  const id = useId();
+  return (
+    <div className={cn("relative w-full max-w-xs", containerClassName)}>
+      <label htmlFor={id} className="sr-only">
+        {label}
+      </label>
+      <SearchIcon
+        size={16}
+        className="pointer-events-none absolute start-2.5 top-1/2 -translate-y-1/2 text-muted-foreground"
+      />
+      <Input
+        id={id}
+        value={value}
+        onChange={(e) => onValueChange(e.target.value)}
+        placeholder={placeholder}
+        disabled={disabled}
+        className={cn("ps-8", value && "pe-8", className)}
+        {...props}
+      />
+      {value && !disabled ? (
+        <button
+          type="button"
+          onClick={() => onValueChange("")}
+          aria-label="Clear search"
+          className="absolute end-2 top-1/2 -translate-y-1/2 rounded-sm p-0.5 text-muted-foreground transition-colors duration-fast ease-standard hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring animate-in fade-in zoom-in-95 duration-fast ease-entrance"
+        >
+          <svg
+            width="14"
+            height="14"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden="true"
+          >
+            <path d="M18 6 6 18M6 6l12 12" />
+          </svg>
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/src/templates-data-app.stories.tsx

@@ -0,0 +1,160 @@
+/**
+ * Data app template — the canonical full-screen data-app composition
+ * (app-shell + DataTable with toolbar). This story is the single source of
+ * truth: `pnpm gen:templates` derives the consumer template source
+ * (`docs/playbooks/templates/data-app.tsx`) from it.
+ * Verify across all three themes with globals=theme:<slug>.
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import {
+  Badge,
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarHeader,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarProvider,
+  SidebarTrigger,
+} from "@elabs-ai/components-ui";
+import { AppIcon } from "@elabs-ai/components-icons";
+import { ColumnPicker, DataTable, FilterBar, SearchInput, type ColumnDef } from "./index";
+
+type Status = "active" | "paused" | "error";
+
+interface DataRow {
+  id: string;
+  name: string;
+  status: Status;
+  records: number;
+  lastRun: string;
+}
+
+const statusVariant: Record<Status, "success" | "secondary" | "destructive"> = {
+  active: "success",
+  paused: "secondary",
+  error: "destructive",
+};
+
+const columns: ColumnDef<DataRow>[] = [
+  { accessorKey: "name", header: "Name" },
+  {
+    accessorKey: "status",
+    header: "Status",
+    cell: ({ row }) => (
+      <Badge variant={statusVariant[row.original.status]}>{row.original.status}</Badge>
+    ),
+  },
+  {
+    accessorKey: "records",
+    header: "Records",
+    cell: ({ row }) => (
+      <span className="tabular-nums">{row.original.records.toLocaleString()}</span>
+    ),
+  },
+  { accessorKey: "lastRun", header: "Last run" },
+];
+
+const sampleData: DataRow[] = [
+  { id: "1", name: "Customer import", status: "active", records: 14200, lastRun: "2 min ago" },
+  { id: "2", name: "Nightly sync", status: "active", records: 88541, lastRun: "6 h ago" },
+  { id: "3", name: "Legacy migration", status: "paused", records: 3010, lastRun: "3 d ago" },
+  { id: "4", name: "Partner feed", status: "error", records: 0, lastRun: "1 d ago" },
+];
+
+const nav = [
+  { id: "data", label: "Data" },
+  { id: "tables", label: "Tables" },
+  { id: "home", label: "Home" },
+  { id: "settings", label: "Settings" },
+];
+
+function DataAppTemplate({ loading = false }: { loading?: boolean }) {
+  const [active, setActive] = useState("data");
+  const [search, setSearch] = useState("");
+  return (
+    <SidebarProvider>
+      <Sidebar collapsible="offcanvas">
+        <SidebarHeader className="px-3 py-2">
+          <div className="flex items-center gap-2">
+            <AppIcon height={20} aria-hidden />
+            <span className="truncate font-semibold group-data-[collapsible=icon]:hidden">
+              Data
+            </span>
+          </div>
+        </SidebarHeader>
+        <SidebarContent>
+          <SidebarGroup>
+            <SidebarGroupContent>
+              <SidebarMenu>
+                {nav.map((n) => (
+                  <SidebarMenuItem key={n.id}>
+                    <SidebarMenuButton
+                      isActive={active === n.id}
+                      tooltip={n.label}
+                      onClick={() => setActive(n.id)}
+                    >
+                      <span>{n.label}</span>
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
+                ))}
+              </SidebarMenu>
+            </SidebarGroupContent>
+          </SidebarGroup>
+        </SidebarContent>
+      </Sidebar>
+      <SidebarInset>
+        <header className="flex h-14 items-center gap-2 border-b px-4">
+          <SidebarTrigger />
+          <h1 className="text-body font-medium capitalize">{active}</h1>
+        </header>
+        {/* NOT a second `<main>` (#386): `SidebarInset` already renders the
+            page's `<main>` landmark, so nesting one here produced three axe
+            violations at once — `landmark-main-is-top-level`,
+            `landmark-no-duplicate-main` and `landmark-unique`. The content
+            region inside the inset is a plain `<div>`. */}
+        <div className="p-6">
+          <DataTable
+            columns={columns}
+            data={loading ? [] : sampleData}
+            loading={loading}
+            enablePagination
+            // Controlled global filter — the app owns `search` and passes it down.
+            // Never mutate the filter inside `toolbar` (e.g. table.setGlobalFilter),
+            // which sets state during render and loops ("Too many re-renders").
+            globalFilter={search}
+            onGlobalFilterChange={setSearch}
+            toolbar={(table) => (
+              // The toolbar has no fetch state of its own (D5) — it just
+              // reflects the table's `loading` by disabling its controls
+              // (loading-states.md; #269).
+              <FilterBar actions={<ColumnPicker table={table} disabled={loading} />}>
+                <SearchInput value={search} onValueChange={setSearch} disabled={loading} />
+              </FilterBar>
+            )}
+          />
+        </div>
+      </SidebarInset>
+    </SidebarProvider>
+  );
+}
+
+const meta = {
+  title: "Patterns/Templates/Data App",
+  parameters: { layout: "fullscreen" },
+  tags: ["autodocs"],
+} satisfies Meta;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { render: () => <DataAppTemplate /> };
+
+// LOADING — the toolbar's controls (`ColumnPicker`, `SearchInput`) are
+// disabled while `DataTable loading` renders its skeleton rows (#269,
+// loading-states.md). The toolbar has no fetch state of its own (D5); it
+// just reflects the table's `loading` prop.
+export const Loading: Story = { render: () => <DataAppTemplate loading /> };

package/src/to-csv.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { toCsv, downloadCsv } from "./to-csv";
+
+type Row = Record<string, unknown>;
+
+describe("toCsv", () => {
+  it("produces a header row from Object.keys when columns omitted", () => {
+    const rows = [{ name: "Alice", age: 30 }];
+    const csv = toCsv(rows);
+    const lines = csv.split("\r\n").filter(Boolean);
+    expect(lines[0]).toBe("name,age");
+    expect(lines[1]).toBe("Alice,30");
+  });
+
+  it("uses custom header labels when provided", () => {
+    const rows = [{ name: "Bob", age: 25 }];
+    const csv = toCsv(rows, {
+      columns: [
+        { key: "name", header: "Full Name" },
+        { key: "age", header: "Age" },
+      ],
+    });
+    const lines = csv.split("\r\n").filter(Boolean);
+    expect(lines[0]).toBe("Full Name,Age");
+  });
+
+  it("column subset and reorder", () => {
+    const rows = [{ a: 1, b: 2, c: 3 }];
+    const csv = toCsv(rows, { columns: [{ key: "c" }, { key: "a" }] });
+    const lines = csv.split("\r\n").filter(Boolean);
+    expect(lines[0]).toBe("c,a");
+    expect(lines[1]).toBe("3,1");
+  });
+
+  it("omits header row when header:false", () => {
+    const rows = [{ x: 1 }];
+    const csv = toCsv(rows, { header: false });
+    const lines = csv.split("\r\n").filter(Boolean);
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toBe("1");
+  });
+
+  it("quotes a field containing the delimiter", () => {
+    const rows = [{ val: "hello,world" } as Row];
+    const csv = toCsv(rows);
+    expect(csv).toContain('"hello,world"');
+  });
+
+  it("escapes embedded double-quotes per RFC 4180", () => {
+    const rows = [{ val: 'say "hi"' } as Row];
+    const csv = toCsv(rows);
+    expect(csv).toContain('"say ""hi"""');
+  });
+
+  it("quotes a field containing a newline", () => {
+    const rows = [{ val: "line1\nline2" } as Row];
+    const csv = toCsv(rows);
+    expect(csv).toContain('"line1\nline2"');
+  });
+
+  it("CSV injection guard: prefixes = with single quote", () => {
+    const rows = [{ formula: "=SUM(A1:A10)" } as Row];
+    const csv = toCsv(rows);
+    expect(csv).toContain("'=SUM");
+  });
+
+  it("CSV injection guard: prefixes + with single quote", () => {
+    const rows = [{ val: "+foo" } as Row];
+    const csv = toCsv(rows);
+    expect(csv).toContain("'+foo");
+  });
+
+  it("CSV injection guard: prefixes - with single quote", () => {
+    const rows = [{ val: "-bar" } as Row];
+    const csv = toCsv(rows);
+    expect(csv).toContain("'-bar");
+  });
+
+  it("CSV injection guard: prefixes @ with single quote", () => {
+    const rows = [{ val: "@baz" } as Row];
+    const csv = toCsv(rows);
+    expect(csv).toContain("'@baz");
+  });
+
+  it("null → empty string", () => {
+    const rows = [{ val: null } as Row];
+    const csv = toCsv(rows);
+    // Split without filter so empty data lines are preserved. Lines: header, data, trailing "".
+    const lines = csv.split("\r\n");
+    expect(lines[0]).toBe("val");
+    expect(lines[1]).toBe(""); // empty cell
+  });
+
+  it("undefined → empty string", () => {
+    const rows = [{ val: undefined } as Row];
+    const csv = toCsv(rows);
+    const lines = csv.split("\r\n");
+    expect(lines[0]).toBe("val");
+    expect(lines[1]).toBe(""); // empty cell
+  });
+
+  it("custom delimiter (semicolon)", () => {
+    const rows = [{ a: 1, b: 2 }];
+    const csv = toCsv(rows, { delimiter: ";" });
+    const lines = csv.split("\r\n").filter(Boolean);
+    expect(lines[0]).toBe("a;b");
+    expect(lines[1]).toBe("1;2");
+  });
+
+  it("uses CRLF line terminators and ends with a trailing newline", () => {
+    const rows = [{ x: 1 }];
+    const csv = toCsv(rows);
+    expect(csv.endsWith("\r\n")).toBe(true);
+    // Internal lines also use CRLF
+    expect(csv.includes("\r\n")).toBe(true);
+  });
+
+  it("returns empty string for empty rows array", () => {
+    const csv = toCsv([]);
+    expect(csv).toBe("");
+  });
+});
+
+describe("downloadCsv", () => {
+  beforeEach(() => {
+    // Mock Blob and URL APIs for jsdom
+    global.URL.createObjectURL = vi.fn(() => "blob:mock");
+    global.URL.revokeObjectURL = vi.fn();
+  });
+
+  it("creates and clicks an anchor element with the correct download attribute", () => {
+    const clickSpy = vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {});
+    downloadCsv([{ name: "Alice" }], { filename: "test-export" });
+    expect(clickSpy).toHaveBeenCalled();
+    clickSpy.mockRestore();
+  });
+
+  it("is a no-op when document is undefined (SSR guard)", () => {
+    const orig = global.document;
+    // @ts-expect-error intentional SSR simulation
+    delete global.document;
+    // Should not throw
+    expect(() => downloadCsv([{ x: 1 }])).not.toThrow();
+    // Restore
+    global.document = orig;
+  });
+});

package/src/to-csv.ts

@@ -0,0 +1,102 @@
+/**
+ * Minimal, dependency-free CSV serializer (RFC 4180).
+ *
+ * `toCsv` is pure + SSR-safe (no DOM, no deps). `downloadCsv` delegates the
+ * browser save mechanics to `@elabs-ai/components-ui`'s shared `downloadBlob` (one home for
+ * the Blob → `<a download>` dance; @elabs-ai/components-ui is already a peer dep here).
+ * ChartFrame uses its own local copy of `toCsv` in @elabs-ai/components-charts to avoid a
+ * cross-sibling dependency (charts → data is not allowed per the one-way rule).
+ */
+import { downloadBlob } from "@elabs-ai/components-ui";
+
+export type CsvColumn<TData> = { key: keyof TData & string; header?: string };
+
+export interface ToCsvOptions<TData> {
+  /** Subset/reorder of columns. Omitted → all keys from rows[0]. */
+  columns?: CsvColumn<TData>[];
+  /** Emit header row. Default true. */
+  header?: boolean;
+  /** Field delimiter. Default ",". */
+  delimiter?: string;
+}
+
+export interface DownloadCsvOptions<TData> extends ToCsvOptions<TData> {
+  /** File name without extension. Default "download". */
+  filename?: string;
+}
+
+/** RFC 4180 injection guard prefixes. */
+const INJECTION_PREFIXES = ["=", "+", "-", "@"];
+
+function stringifyValue(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}
+
+function quoteField(field: string, delimiter: string): string {
+  // CSV-injection guard: prefix with a single quote if the field starts with a
+  // formula trigger character.
+  if (INJECTION_PREFIXES.some((p) => field.startsWith(p))) {
+    field = "'" + field;
+  }
+  // RFC 4180: quote iff the field contains delimiter, double-quote, CR, or LF.
+  if (
+    field.includes(delimiter) ||
+    field.includes('"') ||
+    field.includes("\n") ||
+    field.includes("\r")
+  ) {
+    return '"' + field.replaceAll('"', '""') + '"';
+  }
+  return field;
+}
+
+/**
+ * Serialize rows to a CSV string (no DOM access — safe for SSR / jsdom).
+ */
+export function toCsv<TData extends Record<string, unknown>>(
+  rows: TData[],
+  opts?: ToCsvOptions<TData>,
+): string {
+  const delimiter = opts?.delimiter ?? ",";
+  const includeHeader = opts?.header !== false;
+
+  // Derive columns from first row when not provided.
+  const firstRow = rows[0];
+  const cols: CsvColumn<TData>[] =
+    opts?.columns ??
+    (firstRow !== undefined
+      ? (Object.keys(firstRow) as (keyof TData & string)[]).map((k) => ({ key: k }))
+      : []);
+
+  const lines: string[] = [];
+
+  if (includeHeader && cols.length > 0) {
+    const headerRow = cols.map((c) => quoteField(c.header ?? c.key, delimiter)).join(delimiter);
+    lines.push(headerRow);
+  }
+
+  for (const row of rows) {
+    const line = cols.map((c) => quoteField(stringifyValue(row[c.key]), delimiter)).join(delimiter);
+    lines.push(line);
+  }
+
+  // RFC 4180: CRLF line terminator, trailing newline.
+  return lines.join("\r\n") + (lines.length > 0 ? "\r\n" : "");
+}
+
+/**
+ * Trigger a CSV file download in the browser. No-op in SSR environments.
+ */
+export function downloadCsv<TData extends Record<string, unknown>>(
+  rows: TData[],
+  opts?: DownloadCsvOptions<TData>,
+): void {
+  if (typeof document === "undefined") return;
+
+  const csv = toCsv(rows, opts);
+  const blob = new Blob([csv], { type: "text/csv;charset=utf-8;" });
+  downloadBlob(blob, (opts?.filename ?? "download") + ".csv");
+}