@elabs-ai/components-data 4.0.0

package/src/data-table/index.ts

@@ -0,0 +1,7 @@
+export {
+  DataTable,
+  type DataTableProps,
+  type DataTableViewState,
+  type DataTableServerArgs,
+  type DataTableRowClickHandler,
+} from "./data-table";

package/src/facet-filter/facet-filter.stories.tsx

@@ -0,0 +1,121 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
+import {
+  Button,
+  DatePicker,
+  Input,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@elabs-ai/components-ui";
+import { FacetFilter } from "./facet-filter";
+
+const options = [
+  { label: "Healthy", value: "healthy" },
+  { label: "Degraded", value: "degraded" },
+  { label: "Down", value: "down" },
+];
+
+const meta = {
+  title: "Data/FacetFilter",
+  component: FacetFilter,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "Multi-select faceted filter rendered as a dropdown of toggles. Controlled — it emits " +
+          "the next selection and never holds its own state, so the app (or a DataTable " +
+          "`columnFilters` slice) stays the single source of truth.",
+      },
+    },
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof FacetFilter>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function Controlled({ initial = [] as string[] }) {
+  const [selected, setSelected] = useState<string[]>(initial);
+  return (
+    <FacetFilter
+      title="Status"
+      options={options}
+      selected={selected}
+      onSelectedChange={setSelected}
+    />
+  );
+}
+
+export const Default: Story = {
+  args: { title: "Status", options, selected: [], onSelectedChange: () => {} },
+  render: () => <Controlled />,
+};
+
+/** With a selection the trigger carries a count badge and the menu gains "Clear filters". */
+export const WithSelection: Story = {
+  args: { title: "Status", options, selected: ["degraded"], onSelectedChange: () => {} },
+  render: () => <Controlled initial={["degraded", "down"]} />,
+};
+
+/**
+ * #346 — the filter row a `FacetFilter` actually lives in. Its trigger used to
+ * take `Button size="sm"` (`h-8`) while every sibling control lands on `h-9`
+ * (`Select`'s default rung, `Input`'s hardcoded height, `DatePicker` and a plain
+ * `Button` via `Button`'s own default), so the row's top and bottom edges didn't
+ * line up. The trigger now inherits that same default.
+ *
+ * The play function is the acceptance test: it MEASURES every control's rendered
+ * box in a real browser (`getBoundingClientRect`) and asserts one height and one
+ * top edge across all five. A class-list assertion would only restate the source.
+ */
+export const ToolbarAlignment: Story = {
+  args: { title: "Status", options, selected: [], onSelectedChange: () => {} },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "FacetFilter beside Select, DatePicker, Input and Button — all five controls resolve " +
+          "to the same height and baseline (#346).",
+      },
+    },
+  },
+  render: () => (
+    <div data-testid="filter-row" className="flex flex-wrap items-center gap-2">
+      <Controlled initial={["degraded"]} />
+      <Select defaultValue="prod">
+        <SelectTrigger className="w-36" aria-label="Environment">
+          <SelectValue placeholder="Environment" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="prod">Production</SelectItem>
+          <SelectItem value="staging">Staging</SelectItem>
+        </SelectContent>
+      </Select>
+      <DatePicker placeholder="Pick a date" />
+      <Input className="w-40" aria-label="Search services" placeholder="e.g. billing…" />
+      <Button variant="outline">Reset</Button>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const row = canvas.getByTestId("filter-row");
+    // Direct children only: the row's five controls, in DOM order.
+    const controls = Array.from(row.children) as HTMLElement[];
+    await expect(controls).toHaveLength(5);
+
+    await waitFor(() => {
+      const boxes = controls.map((el) => el.getBoundingClientRect());
+      // A real layout pass must have happened before the comparison means anything.
+      expect(boxes[0]!.height).toBeGreaterThan(0);
+      for (const box of boxes) {
+        // Sub-pixel rounding tolerance; anything larger is a genuine mismatch
+        // (the h-8/h-9 delta this story locks was a full 4px).
+        expect(Math.abs(box.height - boxes[0]!.height)).toBeLessThan(0.5);
+        expect(Math.abs(box.top - boxes[0]!.top)).toBeLessThan(0.5);
+      }
+    });
+  },
+};

package/src/facet-filter/facet-filter.test.tsx

@@ -0,0 +1,175 @@
+/**
+ * facet-filter.test.tsx — smoke + toggle-semantics lock for the faceted filter (#59).
+ *
+ * The behaviour that matters (and that no test covered before #59) is the
+ * multi-select toggle contract: selecting emits the union, re-selecting the same
+ * option emits the difference, and "Clear filters" only exists while something
+ * is selected. It is a CONTROLLED component — it must never hold its own
+ * selection state, so every assertion here is about what it EMITS.
+ *
+ * The menu is opened with a keyboard event on purpose: it is both the real
+ * keyboard path (WCAG 2.1.1) and the one jsdom models faithfully — jsdom has no
+ * pointer-capture, so a synthetic pointerdown would prove less, not more.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { FacetFilter } from "./facet-filter";
+
+const options = [
+  { label: "Healthy", value: "healthy" },
+  { label: "Degraded", value: "degraded" },
+  { label: "Down", value: "down" },
+];
+
+/** Open the dropdown from the keyboard and return its trigger. */
+function open(name = "Status") {
+  const trigger = screen.getByRole("button", { name: new RegExp(`^${name}`) });
+  fireEvent.keyDown(trigger, { key: "Enter" });
+  return trigger;
+}
+
+describe("FacetFilter — trigger", () => {
+  it("names the trigger with the facet title", () => {
+    render(
+      <FacetFilter title="Status" options={options} selected={[]} onSelectedChange={vi.fn()} />,
+    );
+    expect(screen.getByRole("button", { name: "Status" })).toBeInTheDocument();
+  });
+
+  it("shows the selected count on the trigger once a facet is active", () => {
+    render(
+      <FacetFilter
+        title="Status"
+        options={options}
+        selected={["healthy", "down"]}
+        onSelectedChange={vi.fn()}
+      />,
+    );
+    expect(screen.getByRole("button", { name: /^Status/ })).toHaveTextContent("2");
+  });
+
+  it("shows no count badge while nothing is selected", () => {
+    render(
+      <FacetFilter title="Status" options={options} selected={[]} onSelectedChange={vi.fn()} />,
+    );
+    expect(screen.getByRole("button", { name: "Status" }).textContent).toBe("Status");
+  });
+
+  /**
+   * #346 — the trigger must take Button's DEFAULT size rung, not `sm`, so a
+   * toolbar mixing FacetFilter with Select/Input/DatePicker (all h-9) lines up.
+   * jsdom applies no Tailwind, so the class rung is what is assertable here; the
+   * MEASURED proof lives in the `ToolbarAlignment` story's play function, which
+   * compares real `getBoundingClientRect()` boxes in a browser.
+   */
+  it("renders the trigger at the shared default control height, not the sm rung", () => {
+    render(
+      <FacetFilter title="Status" options={options} selected={[]} onSelectedChange={vi.fn()} />,
+    );
+    const trigger = screen.getByRole("button", { name: "Status" });
+    expect(trigger).toHaveClass("h-9");
+    expect(trigger).not.toHaveClass("h-8");
+  });
+});
+
+describe("FacetFilter — menu contents", () => {
+  it("renders one menu item per option when opened", () => {
+    render(
+      <FacetFilter title="Status" options={options} selected={[]} onSelectedChange={vi.fn()} />,
+    );
+    open();
+    for (const opt of options) {
+      expect(screen.getByRole("menuitem", { name: opt.label })).toBeInTheDocument();
+    }
+  });
+
+  it("hides the decorative check box from assistive tech", () => {
+    render(
+      <FacetFilter
+        title="Status"
+        options={options}
+        selected={["healthy"]}
+        onSelectedChange={vi.fn()}
+      />,
+    );
+    open();
+    // The ✓ swatch is a visual affordance; the item's own name carries meaning.
+    const item = screen.getByRole("menuitem", { name: "Healthy" });
+    expect(item.querySelector("[aria-hidden='true']")).not.toBeNull();
+  });
+});
+
+describe("FacetFilter — controlled toggle semantics", () => {
+  it("adds a value to the selection when an unselected option is chosen", () => {
+    const onSelectedChange = vi.fn();
+    render(
+      <FacetFilter
+        title="Status"
+        options={options}
+        selected={["healthy"]}
+        onSelectedChange={onSelectedChange}
+      />,
+    );
+    open();
+    fireEvent.click(screen.getByRole("menuitem", { name: "Down" }));
+    expect(onSelectedChange).toHaveBeenCalledWith(["healthy", "down"]);
+  });
+
+  it("removes a value when an already-selected option is chosen again", () => {
+    const onSelectedChange = vi.fn();
+    render(
+      <FacetFilter
+        title="Status"
+        options={options}
+        selected={["healthy", "down"]}
+        onSelectedChange={onSelectedChange}
+      />,
+    );
+    open();
+    fireEvent.click(screen.getByRole("menuitem", { name: "Healthy" }));
+    expect(onSelectedChange).toHaveBeenCalledWith(["down"]);
+  });
+
+  it("does NOT manage its own selection — the trigger still reflects the prop after a toggle", () => {
+    const onSelectedChange = vi.fn();
+    render(
+      <FacetFilter
+        title="Status"
+        options={options}
+        selected={[]}
+        onSelectedChange={onSelectedChange}
+      />,
+    );
+    // Hold onto the trigger: while the menu is open Radix marks the rest of the
+    // tree aria-hidden, so a role query would no longer reach it.
+    const trigger = open();
+    fireEvent.click(screen.getByRole("menuitem", { name: "Down" }));
+    // The parent owns the state; with the prop unchanged there is still no badge.
+    expect(trigger.textContent).toBe("Status");
+  });
+});
+
+describe("FacetFilter — clear affordance", () => {
+  it("offers no Clear entry while nothing is selected", () => {
+    render(
+      <FacetFilter title="Status" options={options} selected={[]} onSelectedChange={vi.fn()} />,
+    );
+    open();
+    expect(screen.queryByRole("menuitem", { name: "Clear filters" })).toBeNull();
+  });
+
+  it("emits an empty selection from the Clear entry", () => {
+    const onSelectedChange = vi.fn();
+    render(
+      <FacetFilter
+        title="Status"
+        options={options}
+        selected={["healthy", "down"]}
+        onSelectedChange={onSelectedChange}
+      />,
+    );
+    open();
+    fireEvent.click(screen.getByRole("menuitem", { name: "Clear filters" }));
+    expect(onSelectedChange).toHaveBeenCalledWith([]);
+  });
+});

package/src/facet-filter/facet-filter.tsx

@@ -0,0 +1,104 @@
+import type { ButtonHTMLAttributes } from "react";
+import { forwardRef } from "react";
+import {
+  Badge,
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+export interface FacetOption {
+  label: string;
+  value: string;
+}
+
+export interface FacetFilterProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "title"> {
+  title: string;
+  options: FacetOption[];
+  /** Currently selected values (controlled). */
+  selected: string[];
+  onSelectedChange: (values: string[]) => void;
+}
+
+/**
+ * Multi-select faceted filter rendered as a dropdown of toggles.
+ *
+ * `disabled` (forwarded to the trigger `Button`) is how a consumer signals a
+ * pending fetch (D5 — the app owns fetch state, this control just reflects
+ * it; see loading-states.md).
+ *
+ * The trigger takes `Button`'s DEFAULT size (`h-9`), not `sm` (#346): a facet
+ * filter lives in a toolbar beside `Select` / `Input` / `DatePicker`, all of
+ * which land on `h-9` (Select's own default rung, Input hardcoded, DatePicker
+ * via this same Button default). An `sm` trigger was the lone `h-8` outlier in
+ * that row, so the top and bottom edges of a filter bar didn't line up.
+ */
+export const FacetFilter = forwardRef<HTMLButtonElement, FacetFilterProps>(function FacetFilter(
+  { title, options, selected, onSelectedChange, className, ...props },
+  ref,
+) {
+  const selectedSet = new Set(selected);
+  const toggle = (value: string) => {
+    const next = new Set(selectedSet);
+    if (next.has(value)) next.delete(value);
+    else next.add(value);
+    onSelectedChange([...next]);
+  };
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button ref={ref} variant="outline" className={cn("border-dashed", className)} {...props}>
+          {title}
+          {selected.length > 0 ? (
+            <Badge
+              variant="secondary"
+              className="ms-1 rounded px-1.5 animate-in fade-in zoom-in-95 duration-fast ease-entrance"
+            >
+              {selected.length}
+            </Badge>
+          ) : null}
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent className="min-w-[12rem]">
+        <DropdownMenuLabel>{title}</DropdownMenuLabel>
+        {options.map((opt) => {
+          const checked = selectedSet.has(opt.value);
+          return (
+            <DropdownMenuItem
+              key={opt.value}
+              onSelect={(e) => {
+                e.preventDefault();
+                toggle(opt.value);
+              }}
+            >
+              <span
+                aria-hidden="true"
+                className={
+                  "flex size-4 items-center justify-center rounded border transition-colors duration-fast ease-standard " +
+                  (checked ? "border-primary bg-primary text-primary-foreground" : "border-input")
+                }
+              >
+                {checked ? "✓" : ""}
+              </span>
+              {opt.label}
+            </DropdownMenuItem>
+          );
+        })}
+        {selected.length > 0 ? (
+          <>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem onSelect={() => onSelectedChange([])}>Clear filters</DropdownMenuItem>
+          </>
+        ) : null}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+});
+
+FacetFilter.displayName = "FacetFilter";

package/src/facet-filter/index.ts

@@ -0,0 +1 @@
+export { FacetFilter, type FacetFilterProps, type FacetOption } from "./facet-filter";

package/src/filter-bar/filter-bar.stories.tsx

@@ -0,0 +1,58 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Button } from "@elabs-ai/components-ui";
+import { FilterBar } from "./filter-bar";
+import { SearchInput } from "../search-input";
+import { FacetFilter } from "../facet-filter";
+
+const statusOptions = [
+  { label: "Healthy", value: "healthy" },
+  { label: "Degraded", value: "degraded" },
+  { label: "Down", value: "down" },
+];
+
+const meta = {
+  title: "Data/FilterBar",
+  component: FilterBar,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The two-cluster table toolbar: filters on the leading edge, actions on the trailing " +
+          "edge. It owns no state — compose it from `SearchInput`, `FacetFilter` and " +
+          "`ColumnPicker` and pass it to a DataTable's `toolbar` render-prop.",
+      },
+    },
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof FilterBar>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function Toolbar({ withActions = true }: { withActions?: boolean }) {
+  const [query, setQuery] = useState("");
+  const [status, setStatus] = useState<string[]>([]);
+  return (
+    <FilterBar actions={withActions ? <Button size="sm">Export CSV</Button> : undefined}>
+      <SearchInput value={query} onValueChange={setQuery} />
+      <FacetFilter
+        title="Status"
+        options={statusOptions}
+        selected={status}
+        onSelectedChange={setStatus}
+      />
+    </FilterBar>
+  );
+}
+
+export const Default: Story = {
+  args: { children: null },
+  render: () => <Toolbar />,
+};
+
+/** Without `actions` the trailing cluster is omitted entirely, not rendered empty. */
+export const FiltersOnly: Story = {
+  args: { children: null },
+  render: () => <Toolbar withActions={false} />,
+};

package/src/filter-bar/filter-bar.test.tsx

@@ -0,0 +1,60 @@
+/**
+ * filter-bar.test.tsx — smoke + layout-contract lock for the table toolbar (#59).
+ *
+ * FilterBar is deliberately thin: it is the two-cluster toolbar grammar (filters
+ * on the leading edge, actions on the trailing edge) that every data screen
+ * repeats. The contract worth locking is that both clusters exist, that the
+ * actions cluster is OMITTED (not rendered empty) when there are no actions —
+ * an empty flex box would still eat the `gap` — and that it composes.
+ */
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { FilterBar } from "./filter-bar";
+
+describe("FilterBar", () => {
+  it("renders its filter children", () => {
+    render(
+      <FilterBar>
+        <button type="button">Status</button>
+      </FilterBar>,
+    );
+    expect(screen.getByRole("button", { name: "Status" })).toBeInTheDocument();
+  });
+
+  it("renders the actions cluster when actions are supplied", () => {
+    render(
+      <FilterBar actions={<button type="button">Export</button>}>
+        <button type="button">Status</button>
+      </FilterBar>,
+    );
+    expect(screen.getByRole("button", { name: "Export" })).toBeInTheDocument();
+  });
+
+  it("keeps filters and actions in SEPARATE clusters (leading vs trailing)", () => {
+    const { container } = render(
+      <FilterBar actions={<button type="button">Export</button>}>
+        <button type="button">Status</button>
+      </FilterBar>,
+    );
+    const clusters = container.firstElementChild?.children;
+    expect(clusters).toHaveLength(2);
+    expect(clusters?.[0]).toHaveTextContent("Status");
+    expect(clusters?.[1]).toHaveTextContent("Export");
+  });
+
+  it("omits the actions cluster entirely when there are no actions", () => {
+    const { container } = render(
+      <FilterBar>
+        <button type="button">Status</button>
+      </FilterBar>,
+    );
+    // One child only — an empty second flex row would still consume the gap.
+    expect(container.firstElementChild?.children).toHaveLength(1);
+  });
+
+  it("merges a caller className onto the root without dropping the layout classes", () => {
+    const { container } = render(<FilterBar className="extra">x</FilterBar>);
+    expect(container.firstChild).toHaveClass("extra");
+    expect(container.firstChild).toHaveClass("flex");
+  });
+});

package/src/filter-bar/filter-bar.tsx

@@ -0,0 +1,20 @@
+import { type ReactNode } from "react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+export interface FilterBarProps {
+  /** Left cluster: search + facet filters. */
+  children: ReactNode;
+  /** Right cluster: column picker, export, primary actions. */
+  actions?: ReactNode;
+  className?: string;
+}
+
+/** Horizontal toolbar that groups table filters and actions. */
+export function FilterBar({ children, actions, className }: FilterBarProps) {
+  return (
+    <div className={cn("flex flex-wrap items-center justify-between gap-2", className)}>
+      <div className="flex flex-wrap items-center gap-2">{children}</div>
+      {actions ? <div className="flex items-center gap-2">{actions}</div> : null}
+    </div>
+  );
+}

package/src/filter-bar/index.ts

@@ -0,0 +1 @@
+export { FilterBar, type FilterBarProps } from "./filter-bar";

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @elabs-ai/components-data — data-dense UI built on TanStack Table.
+ *
+ * DataTable owns the table instance and exposes it through a toolbar
+ * render-prop so SearchInput, FacetFilter and ColumnPicker can drive it.
+ */
+// DataTable + DataTableViewState + DataTableServerArgs (WP-05 #62 new types)
+export * from "./data-table";
+export * from "./search-input";
+export * from "./filter-bar";
+export * from "./facet-filter";
+export * from "./column-picker";
+
+// Re-export the most common TanStack types so consumers don't need a direct dep.
+export type { ColumnDef, ColumnPinningState, Table, Row, CellContext } from "@tanstack/react-table";
+
+// CSV helpers — pure, dependency-free serializer + browser download trigger.
+export * from "./to-csv";

package/src/search-input/index.ts

@@ -0,0 +1 @@
+export { SearchInput, type SearchInputProps } from "./search-input";

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

@@ -0,0 +1,45 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { SearchInput } from "./search-input";
+
+const meta = {
+  title: "Data/SearchInput",
+  component: SearchInput,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "Controlled search field with a leading icon and a clear button. Pair it with " +
+          "`FilterBar` and drive a DataTable's global filter from the `toolbar` render-prop. " +
+          "The label is visually hidden but real — the placeholder is never the accessible name.",
+      },
+    },
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof SearchInput>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Uncontrolled-looking wrapper so the stories are actually typeable. */
+function Controlled({ initial = "", label }: { initial?: string; label?: string }) {
+  const [value, setValue] = useState(initial);
+  return <SearchInput value={value} onValueChange={setValue} label={label} />;
+}
+
+export const Default: Story = {
+  args: { value: "", onValueChange: () => {} },
+  render: () => <Controlled />,
+};
+
+/** With a value the clear button appears, named "Clear search" for AT. */
+export const WithValue: Story = {
+  args: { value: "billing", onValueChange: () => {} },
+  render: () => <Controlled initial="billing" />,
+};
+
+/** The visually-hidden label is overridable when "Search" is too vague. */
+export const CustomLabel: Story = {
+  args: { value: "", onValueChange: () => {} },
+  render: () => <Controlled label="Filter deployments" />,
+};