@elabs-ai/components-data 4.0.0 → 4.2.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.stories.tsx

@@ -95,7 +95,10 @@ export const ToolbarAlignment: Story = {
           <SelectItem value="staging">Staging</SelectItem>
         </SelectContent>
       </Select>
-      <DatePicker placeholder="Pick a date" />
+      {/* DatePicker's trigger fills its container by default (`w-full`, like Input), which
+          in a wrapping flex row claims a line of its own. In a toolbar it sizes to its
+          content instead — the same per-toolbar sizing Select and Input get here. */}
+      <DatePicker placeholder="Pick a date" className="w-auto" />
       <Input className="w-40" aria-label="Search services" placeholder="e.g. billing…" />
       <Button variant="outline">Reset</Button>
     </div>

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

@@ -57,7 +57,7 @@ describe("FacetFilter — trigger", () => {
 
   /**
    * #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.
+   * toolbar mixing FacetFilter with Select/Input/DatePicker (all `h-control`) 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.
@@ -67,8 +67,8 @@ describe("FacetFilter — trigger", () => {
       <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");
+    expect(trigger).toHaveClass("h-control");
+    expect(trigger).not.toHaveClass("h-control-sm");
   });
 });
 

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.test.tsx

@@ -7,6 +7,7 @@
  * `<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 { createRef, useState } from "react";
 import { describe, expect, it, vi } from "vitest";
 import { render, screen, fireEvent } from "@testing-library/react";
 import { SearchInput } from "./search-input";
@@ -29,6 +30,26 @@ describe("SearchInput — accessible name", () => {
     expect(label).not.toBeNull();
     expect(label).toHaveAttribute("for", input.getAttribute("id"));
   });
+
+  it("keeps the label wired to a consumer-supplied id instead of a stale generated one", () => {
+    render(<SearchInput value="" onValueChange={vi.fn()} id="deployment-search" />);
+    const input = screen.getByRole("textbox", { name: "Search" });
+    // The consumer's own `id` used to reach the <input> (via the trailing
+    // `...props` spread) while the <label>'s `htmlFor` kept pointing at an
+    // internally-generated id that no element actually had — breaking the
+    // label/input association `getByRole({ name })` above depends on.
+    expect(input).toHaveAttribute("id", "deployment-search");
+    expect(document.querySelector("label")).toHaveAttribute("for", "deployment-search");
+  });
+});
+
+describe("SearchInput — ref", () => {
+  it("forwards a ref to the underlying <input>", () => {
+    const ref = createRef<HTMLInputElement>();
+    render(<SearchInput ref={ref} value="" onValueChange={vi.fn()} />);
+    expect(ref.current).toBeInstanceOf(HTMLInputElement);
+    expect(ref.current).toBe(screen.getByRole("textbox", { name: "Search" }));
+  });
 });
 
 describe("SearchInput — value reporting", () => {
@@ -72,6 +93,20 @@ describe("SearchInput — clear affordance", () => {
     const svg = screen.getByRole("button", { name: "Clear search" }).querySelector("svg");
     expect(svg).toHaveAttribute("aria-hidden", "true");
   });
+
+  it("returns keyboard focus to the input after clearing (the button itself unmounts)", () => {
+    function Harness() {
+      const [value, setValue] = useState("billing");
+      return <SearchInput value={value} onValueChange={setValue} />;
+    }
+    render(<Harness />);
+    const clearButton = screen.getByRole("button", { name: "Clear search" });
+    clearButton.focus();
+    fireEvent.click(clearButton);
+    // The clear button is conditionally rendered on `value` — once it
+    // disappears, a browser drops focus to <body> unless something claims it.
+    expect(screen.getByRole("textbox", { name: "Search" })).toHaveFocus();
+  });
 });
 
 describe("SearchInput — composability", () => {

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

@@ -1,7 +1,7 @@
 "use client";
 
-import { useId, type InputHTMLAttributes } from "react";
-import { Input } from "@elabs-ai/components-ui";
+import { forwardRef, useId, useRef, type InputHTMLAttributes } from "react";
+import { Input, useLocale } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { SearchIcon } from "@elabs-ai/components-icons";
 
@@ -11,7 +11,7 @@ export interface SearchInputProps extends Omit<
 > {
   value: string;
   onValueChange: (value: string) => void;
-  /** Visually-hidden accessible label. Defaults to "Search". */
+  /** Visually-hidden accessible label. Defaults to the localized "Search" microcopy. */
   label?: string;
   containerClassName?: string;
 }
@@ -25,31 +25,56 @@ export interface SearchInputProps extends Omit<
  * `<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();
+export const SearchInput = forwardRef<HTMLInputElement, SearchInputProps>(function SearchInput(
+  {
+    value,
+    onValueChange,
+    label,
+    placeholder,
+    className,
+    containerClassName,
+    disabled,
+    id: idProp,
+    ...props
+  },
+  forwardedRef,
+) {
+  const { t } = useLocale();
+  const resolvedLabel = label ?? t("data.searchInput.label");
+  const resolvedPlaceholder = placeholder ?? t("data.searchInput.placeholder");
+  const generatedId = useId();
+  const id = idProp ?? generatedId;
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const setRefs = (node: HTMLInputElement | null) => {
+    inputRef.current = node;
+    if (typeof forwardedRef === "function") forwardedRef(node);
+    else if (forwardedRef) forwardedRef.current = node;
+  };
+
+  const handleClear = () => {
+    onValueChange("");
+    // The clear button unmounts the instant `value` becomes falsy — without
+    // this, the browser drops focus to <body> instead of leaving it
+    // somewhere the keyboard user can keep typing.
+    inputRef.current?.focus();
+  };
+
   return (
     <div className={cn("relative w-full max-w-xs", containerClassName)}>
       <label htmlFor={id} className="sr-only">
-        {label}
+        {resolvedLabel}
       </label>
       <SearchIcon
         size={16}
         className="pointer-events-none absolute start-2.5 top-1/2 -translate-y-1/2 text-muted-foreground"
       />
       <Input
+        ref={setRefs}
         id={id}
         value={value}
         onChange={(e) => onValueChange(e.target.value)}
-        placeholder={placeholder}
+        placeholder={resolvedPlaceholder}
         disabled={disabled}
         className={cn("ps-8", value && "pe-8", className)}
         {...props}
@@ -57,9 +82,9 @@ export function SearchInput({
       {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"
+          onClick={handleClear}
+          aria-label={t("data.searchInput.clear")}
+          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"
@@ -78,4 +103,4 @@ export function SearchInput({
       ) : null}
     </div>
   );
-}
+});