@elabs-ai/components-data 4.0.0 → 4.1.0

package/src/data-table/index.ts

@@ -1,7 +1,17 @@
 export {
   DataTable,
+  createSelectionColumn,
   type DataTableProps,
   type DataTableViewState,
   type DataTableServerArgs,
   type DataTableRowClickHandler,
+  // #69 round-1 fix (validator B3): this named type was declared and
+  // documented as exported ("Exported (not just declared) so a consumer's
+  // own `ColumnDef` literal type-checks against a NAMED type") but was never
+  // actually re-exported through this barrel — a consumer importing it from
+  // `@elabs-ai/components-data` got `TS2305`. `ColumnMeta`'s augmented keys
+  // already reached consumers via `packages/data/src/index.ts`'s TanStack
+  // re-export; this makes the NAMED type reachable too, matching both the
+  // source comment and the CHANGELOG entry.
+  type DataTableColumnMeta,
 } from "./data-table";

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

@@ -9,6 +9,7 @@ import {
   DropdownMenuLabel,
   DropdownMenuSeparator,
   DropdownMenuTrigger,
+  useLocale,
 } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 
@@ -42,6 +43,7 @@ export const FacetFilter = forwardRef<HTMLButtonElement, FacetFilterProps>(funct
   { title, options, selected, onSelectedChange, className, ...props },
   ref,
 ) {
+  const { t } = useLocale();
   const selectedSet = new Set(selected);
   const toggle = (value: string) => {
     const next = new Set(selectedSet);
@@ -93,7 +95,9 @@ export const FacetFilter = forwardRef<HTMLButtonElement, FacetFilterProps>(funct
         {selected.length > 0 ? (
           <>
             <DropdownMenuSeparator />
-            <DropdownMenuItem onSelect={() => onSelectedChange([])}>Clear filters</DropdownMenuItem>
+            <DropdownMenuItem onSelect={() => onSelectedChange([])}>
+              {t("data.facetFilter.clearFilters")}
+            </DropdownMenuItem>
           </>
         ) : null}
       </DropdownMenuContent>

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

@@ -0,0 +1,144 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, userEvent, within } from "storybook/test";
+import { FilterChip } from "./filter-chip";
+
+const meta = {
+  title: "Data/FilterBar/FilterChip",
+  component: FilterChip,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The removable active-filter chip for `FilterBar`, with an optional secondary " +
+          'count ("excluded 1,204"), passed to the base `trailing` slot (#284) rather than ' +
+          "folded into `label` — a long label truncates on its own, the count never loses " +
+          "characters to the ellipsis. Composes `@elabs-ai/components-ui`'s `FilterChip` — the " +
+          'whole chip is a single button whose accessible name is "Remove filter: <label> · ' +
+          '<trailing>" (WCAG 2.5.3), so the count still reaches the accessible name, not only ' +
+          "the visible text.",
+      },
+    },
+  },
+  args: {
+    label: "Status: Failed",
+    onRemove: fn(),
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof FilterChip>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const chip = canvas.getByRole("button", { name: "Remove filter: Status: Failed" });
+    await userEvent.click(chip);
+    await expect(args.onRemove).toHaveBeenCalledTimes(1);
+  },
+};
+
+/** A count with a caller-supplied label — "excluded 1,204", locale-formatted. */
+export const WithCount: Story = {
+  args: { count: 1204, countLabel: "excluded" },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // Label and count are separate elements (#284) — the count is never
+    // folded into the truncatable label string.
+    await expect(canvas.getByText("Status: Failed")).toBeInTheDocument();
+    await expect(canvas.getByText("excluded 1,204")).toBeInTheDocument();
+    await expect(
+      canvas.getByRole("button", { name: "Remove filter: Status: Failed · excluded 1,204" }),
+    ).toBeInTheDocument();
+  },
+};
+
+/** A bare count with no `countLabel` — just the formatted number. */
+export const BareCount: Story = {
+  args: { count: 1204 },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("Status: Failed")).toBeInTheDocument();
+    await expect(canvas.getByText("1,204")).toBeInTheDocument();
+  },
+};
+
+/** Several chips in a run — removing one never touches its siblings. */
+function MultipleChipsDemo() {
+  const [chips, setChips] = useState([
+    { id: "status", label: "Status: Failed", count: 1204, countLabel: "excluded" },
+    { id: "region", label: "Region: EU" },
+  ]);
+  return (
+    <div className="flex flex-wrap items-center gap-1.5">
+      {chips.map((chip) => (
+        <FilterChip
+          key={chip.id}
+          label={chip.label}
+          count={chip.count}
+          countLabel={chip.countLabel}
+          onRemove={() => setChips((prev) => prev.filter((c) => c.id !== chip.id))}
+        />
+      ))}
+    </div>
+  );
+}
+
+export const MultipleChips: Story = {
+  render: () => <MultipleChipsDemo />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const statusChip = canvas.getByRole("button", {
+      name: "Remove filter: Status: Failed · excluded 1,204",
+    });
+    const regionChip = canvas.getByRole("button", { name: "Remove filter: Region: EU" });
+    await userEvent.click(statusChip);
+    await expect(statusChip).not.toBeInTheDocument();
+    await expect(regionChip).toBeInTheDocument();
+  },
+};
+
+/**
+ * A label long enough to overflow a 280px container (#284). The label
+ * truncates with an ellipsis; the count stays fully visible — CSS
+ * `text-overflow: ellipsis` can only reach the label's own span, never the
+ * count's sibling element.
+ */
+export const LongLabelWithCount: Story = {
+  args: {
+    label: "Status: Awaiting downstream reconciliation review",
+    count: 1204,
+    countLabel: "excluded",
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[280px]">
+        <Story />
+      </div>
+    ),
+  ],
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const count = await canvas.findByText("excluded 1,204");
+    await expect(count).toBeInTheDocument();
+
+    const truncating = canvasElement.querySelector('[class*="truncate"]');
+    await expect(truncating).not.toBeNull();
+    // The count must never be a descendant of the truncating label span.
+    await expect(truncating?.contains(count)).toBe(false);
+
+    await expect(
+      canvas.getByRole("button", {
+        name: "Remove filter: Status: Awaiting downstream reconciliation review · excluded 1,204",
+      }),
+    ).toBeInTheDocument();
+  },
+};
+
+export const WithCountHighDecoration: Story = {
+  name: "With count — high decoration",
+  globals: { decoration: "10" },
+  args: { count: 1204, countLabel: "excluded" },
+  play: WithCount.play,
+};

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

@@ -0,0 +1,137 @@
+/**
+ * filter-chip.test.tsx — smoke + count-in-accessible-name lock (#221).
+ *
+ * `FilterChip` composes `@elabs-ai/components-ui`'s FilterChip; the contract worth
+ * locking here is specific to the count feature this wrapper adds: the
+ * formatted count reaches the VISIBLE text and the chip's ACCESSIBLE NAME
+ * (WCAG 2.5.3), and removing one chip never touches its siblings.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { FilterChip } from "./filter-chip";
+
+describe("FilterChip", () => {
+  it("renders the bare label with no count", () => {
+    render(<FilterChip label="Status: Failed" onRemove={vi.fn()} />);
+    expect(
+      screen.getByRole("button", { name: "Remove filter: Status: Failed" }),
+    ).toBeInTheDocument();
+    expect(screen.getByText("Status: Failed")).toBeInTheDocument();
+  });
+
+  it("renders 'excluded 1,204' (locale-formatted) alongside the label", () => {
+    render(
+      <FilterChip label="Status: Failed" count={1204} countLabel="excluded" onRemove={vi.fn()} />,
+    );
+    expect(screen.getByText("Status: Failed")).toBeInTheDocument();
+    expect(screen.getByText("excluded 1,204")).toBeInTheDocument();
+  });
+
+  it("folds the count into the chip's ACCESSIBLE NAME, not only its visible text", () => {
+    render(
+      <FilterChip label="Status: Failed" count={1204} countLabel="excluded" onRemove={vi.fn()} />,
+    );
+    expect(
+      screen.getByRole("button", { name: "Remove filter: Status: Failed · excluded 1,204" }),
+    ).toBeInTheDocument();
+  });
+
+  it("renders a bare formatted count with no countLabel", () => {
+    render(<FilterChip label="Status: Failed" count={1204} onRemove={vi.fn()} />);
+    expect(screen.getByText("Status: Failed")).toBeInTheDocument();
+    expect(screen.getByText("1,204")).toBeInTheDocument();
+  });
+
+  it("fires onRemove for the clicked chip only, leaving sibling chips untouched", async () => {
+    const user = userEvent.setup();
+    const removeFirst = vi.fn();
+    const removeSecond = vi.fn();
+    render(
+      <>
+        <FilterChip label="Status: Failed" onRemove={removeFirst} />
+        <FilterChip label="Region: EU" onRemove={removeSecond} />
+      </>,
+    );
+    await user.click(screen.getByRole("button", { name: "Remove filter: Status: Failed" }));
+    expect(removeFirst).toHaveBeenCalledTimes(1);
+    expect(removeSecond).not.toHaveBeenCalled();
+  });
+
+  it("merges a caller className onto the root", () => {
+    render(<FilterChip label="Status: Failed" onRemove={vi.fn()} className="extra" />);
+    expect(screen.getByRole("button")).toHaveClass("extra");
+  });
+
+  it("keeps the count in a non-shrinking element so truncation can only reach the label", () => {
+    const { container } = render(
+      <FilterChip
+        label="Status: Awaiting downstream reconciliation review"
+        count={1204}
+        countLabel="excluded"
+        onRemove={vi.fn()}
+      />,
+    );
+    const truncating = container.querySelector('[class*="truncate"]');
+    expect(truncating).not.toBeNull();
+    expect(truncating).toHaveTextContent("Status: Awaiting downstream reconciliation review");
+    expect(truncating?.textContent).toBe("Status: Awaiting downstream reconciliation review");
+
+    // The count lives in its own, sibling element — never inside the truncating one.
+    const count = screen.getByText("excluded 1,204");
+    expect(count).not.toBe(truncating);
+    expect(truncating?.contains(count)).toBe(false);
+  });
+
+  // Runtime lock (PR #408 review round 2): `Omit<BaseFilterChipProps, "trailing">`
+  // only stops a `trailing` prop written as an object LITERAL — TypeScript's
+  // excess-property check does not apply to a spread of an already-declared
+  // variable, so a typed caller can still get `trailing` into `props` this
+  // way and have it win at render. This must hold at runtime regardless of
+  // what the type system caught.
+  it("keeps the derived count even when a caller spreads a `trailing` override through a variable", () => {
+    const hijack = { trailing: "hijacked" } as { trailing: string };
+    render(
+      <FilterChip
+        label="Status: Failed"
+        count={1204}
+        countLabel="excluded"
+        onRemove={vi.fn()}
+        {...hijack}
+      />,
+    );
+    expect(screen.getByText("excluded 1,204")).toBeInTheDocument();
+    expect(screen.queryByText("hijacked")).not.toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: "Remove filter: Status: Failed · excluded 1,204" }),
+    ).toBeInTheDocument();
+  });
+
+  // Type-level lock, same shape as ContextRail's `children` omission
+  // (context-rail.test.tsx #15): `FilterChipProps` is re-derived from the
+  // base package's `BaseFilterChipProps` and must omit `trailing` alongside
+  // `label`. The wrapper computes its OWN `trailing` from `count`/
+  // `countLabel` and strips any caller-supplied `trailing` from `props` at
+  // RUNTIME before forwarding to the base component, so a caller-supplied
+  // `trailing` — whether it type-checks as an object literal (it doesn't,
+  // thanks to this Omit) or slips through a spread of an already-declared
+  // variable (it does; see the runtime lock above) — can never win at
+  // render. Fails to typecheck the moment `trailing` is dropped from the
+  // `Omit`.
+  it("(type-level) does not accept a `trailing` prop", () => {
+    function typeOnly() {
+      return (
+        <FilterChip
+          label="Status: Failed"
+          count={1204}
+          // @ts-expect-error — `trailing` is omitted from `FilterChipProps`;
+          // the wrapper derives its own `trailing` from `count`/`countLabel`
+          // and must not let a caller override it.
+          trailing="hijacked"
+          onRemove={vi.fn()}
+        />
+      );
+    }
+    expect(typeof typeOnly).toBe("function");
+  });
+});

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

@@ -0,0 +1,92 @@
+"use client";
+
+/**
+ * filter-chip.tsx — `@elabs-ai/components-data`'s removable filter chip, with an optional
+ * secondary count ("excluded 1,204") for `ProcessFilterBar` (RM-056, #221).
+ *
+ * Deliberately a thin COMPOSING wrapper around `@elabs-ai/components-ui`'s `FilterChip`
+ * (`view-toolbar.tsx`, #331) rather than a second implementation — the dedupe
+ * audit found the real, accessible, whole-chip-as-button `FilterChip` already
+ * lives there (WCAG 2.5.8 target size, WCAG 2.5.3 "Remove filter: <label>"
+ * accessible name). Building a second one in `packages/data` would duplicate
+ * that work; this wrapper reuses it and passes `count`/`countLabel` through
+ * the base component's `trailing` slot (#284) — a second, non-shrinking text
+ * element, distinct from the truncatable `label` — so the count reaches the
+ * chip's ACCESSIBLE NAME (screen readers hear "Remove filter: Status: Failed
+ * · excluded 1,204") AND survives truncation in the visible chip, instead of
+ * being folded into the one string CSS `truncate` can clip from the tail.
+ */
+import { forwardRef } from "react";
+import {
+  FilterChip as BaseFilterChip,
+  type FilterChipProps as BaseFilterChipProps,
+  useLocale,
+} from "@elabs-ai/components-ui";
+
+// `trailing` is omitted alongside `label`: this wrapper derives its OWN
+// `trailing` from `count`/`countLabel`. The `Omit` blocks `trailing` written
+// as an object LITERAL, but TypeScript's excess-property check does not
+// apply to a spread of an already-declared variable — `const extra = {
+// trailing: "x" }; <FilterChip {...extra} />` still type-checks, and the
+// value would land in `props` regardless of JSX attribute order (PR #408
+// review round 2). So the `Omit` is necessary but not sufficient: below,
+// `trailing` is also stripped from `props` at RUNTIME before it reaches the
+// base component, so a caller-supplied `trailing` — literal or
+// spread-smuggled — can never win at render, the same advertised-but-inert
+// failure mode #382/#284-round-1 already closed elsewhere in the repo
+// (`ContextRail`'s `children` omission).
+export interface FilterChipProps extends Omit<BaseFilterChipProps, "label" | "trailing"> {
+  /**
+   * Label-in-value text — `"Status: Failed"`, never `"Status = failed"` and
+   * never a bare `"Failed"`. Same contract as the base `FilterChip`.
+   */
+  label: string;
+  /**
+   * How many records this active filter excluded (or matched) — rendered as a
+   * secondary, locale-formatted segment alongside `label`. Omit for a bare
+   * chip with no count.
+   */
+  count?: number;
+  /**
+   * The word placed before the formatted count, e.g. `"excluded"` →
+   * `"excluded 1,204"`. Omitted by default: a bare `count` renders as just the
+   * formatted number.
+   */
+  countLabel?: string;
+}
+
+/**
+ * A removable active-filter chip with an optional secondary count.
+ *
+ * `onRemove` stays REQUIRED (inherited from the base `FilterChip`, diverging
+ * from this item's spec draft) — the whole chip IS the remove control, so a
+ * chip with no removal affordance is a plain `Badge`, not this component.
+ */
+export const FilterChip = forwardRef<HTMLButtonElement, FilterChipProps>(function FilterChip(
+  { label, count, countLabel, ...props },
+  ref,
+) {
+  const { formatNumber } = useLocale();
+  const countText =
+    count === undefined
+      ? undefined
+      : countLabel
+        ? `${countLabel} ${formatNumber(count)}`
+        : formatNumber(count);
+
+  // Runtime guard (belt and braces alongside the `Omit` above): a caller can
+  // still smuggle `trailing` into `props` through a spread of an
+  // already-declared variable, which the type system cannot catch. Strip it
+  // here so the derived count wins regardless of prop order.
+  const { trailing: _ignoredTrailing, ...restProps } = props as Omit<BaseFilterChipProps, "label">;
+
+  return (
+    <BaseFilterChip
+      ref={ref}
+      data-slot="filter-chip"
+      label={label}
+      {...restProps}
+      trailing={countText}
+    />
+  );
+});

package/src/filter-bar/index.ts

@@ -1 +1,2 @@
 export { FilterBar, type FilterBarProps } from "./filter-bar";
+export { FilterChip, type FilterChipProps } from "./filter-chip";

package/src/index.ts

@@ -12,7 +12,16 @@ 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";
+export type {
+  ColumnDef,
+  ColumnMeta,
+  ColumnPinningState,
+  ColumnSizingState,
+  RowSelectionState,
+  Table,
+  Row,
+  CellContext,
+} from "@tanstack/react-table";
 
 // CSV helpers — pure, dependency-free serializer + browser download trigger.
 export * from "./to-csv";

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

@@ -10,6 +10,9 @@ const meta = {
     docs: {
       description: {
         component:
+          "The SEARCH field, with a leading icon and a clear button; a plain text field is " +
+          "`Core/Input` — see " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). " +
           "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.",

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

@@ -59,7 +59,7 @@ export function SearchInput({
           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"
+          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-ring animate-in fade-in zoom-in-95 duration-fast ease-entrance"
         >
           <svg
             width="14"

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

@@ -3,7 +3,7 @@
  * (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>.
+ * Verify across every theme with globals=theme:<slug>.
  */
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { useState } from "react";
@@ -52,9 +52,11 @@ const columns: ColumnDef<DataRow>[] = [
   {
     accessorKey: "records",
     header: "Records",
-    cell: ({ row }) => (
-      <span className="tabular-nums">{row.original.records.toLocaleString()}</span>
-    ),
+    // #69: `meta.numeric` is the seam — DataTable applies `tabular-nums` +
+    // end-alignment on both `<th>` and `<td>`, so the exemplar no longer
+    // hand-rolls a wrapper span for it.
+    meta: { numeric: true },
+    cell: ({ row }) => row.original.records.toLocaleString(),
   },
   { accessorKey: "lastRun", header: "Last run" },
 ];