@zentauri-ui/zentauri-components 1.8.1 → 1.8.2

package/src/hooks/useTableFilter/useTableFilter.ts

@@ -0,0 +1,153 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+
+import type {
+  TableFilterState,
+  UseTableFilterParams,
+  UseTableFilterResult,
+} from "./types";
+
+function normalizeFilters<TKey extends string>(
+  filters: TableFilterState<TKey> | null | undefined,
+): TableFilterState<TKey> {
+  if (!filters || typeof filters !== "object") {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(filters).filter(
+      (entry): entry is [TKey, string] =>
+        typeof entry[1] === "string" && entry[1].trim().length > 0,
+    ),
+  ) as TableFilterState<TKey>;
+}
+
+function defaultColumnValue<TData, TKey extends string>(
+  row: TData,
+  filterKey: TKey,
+): unknown {
+  if (row && typeof row === "object" && filterKey in row) {
+    return (row as Record<TKey, unknown>)[filterKey];
+  }
+  return undefined;
+}
+
+export function useTableFilter<TData, TKey extends string = string>({
+  data,
+  filters,
+  defaultFilters = {},
+  onFiltersChange,
+  getColumnValue = defaultColumnValue,
+  filterPredicate,
+}: UseTableFilterParams<TData, TKey>): UseTableFilterResult<TData, TKey> {
+  const [internalFilters, setInternalFilters] = useState<
+    TableFilterState<TKey>
+  >(() => normalizeFilters(defaultFilters));
+
+  const isControlled = filters !== undefined;
+  const currentFilters = useMemo(
+    () => normalizeFilters(isControlled ? filters : internalFilters),
+    [filters, internalFilters, isControlled],
+  );
+
+  const setFilters = useCallback(
+    (nextFilters: TableFilterState<TKey>) => {
+      const normalized = normalizeFilters(nextFilters);
+      if (!isControlled) {
+        setInternalFilters(normalized);
+      }
+      onFiltersChange?.(normalized);
+    },
+    [isControlled, onFiltersChange],
+  );
+
+  const updateFilters = useCallback(
+    (
+      updater: (
+        previousFilters: TableFilterState<TKey>,
+      ) => TableFilterState<TKey>,
+    ) => {
+      if (isControlled) {
+        const normalized = normalizeFilters(updater(currentFilters));
+        onFiltersChange?.(normalized);
+        return;
+      }
+
+      setInternalFilters((previousFilters) => {
+        const normalized = normalizeFilters(updater(previousFilters));
+        onFiltersChange?.(normalized);
+        return normalized;
+      });
+    },
+    [currentFilters, isControlled, onFiltersChange],
+  );
+
+  const setFilter = useCallback(
+    (filterKey: TKey, value: string) => {
+      updateFilters((previousFilters) => ({
+        ...previousFilters,
+        [filterKey]: value,
+      }));
+    },
+    [updateFilters],
+  );
+
+  const clearFilter = useCallback(
+    (filterKey: TKey) => {
+      updateFilters((previousFilters) => {
+        const nextFilters = { ...previousFilters };
+        delete nextFilters[filterKey];
+        return nextFilters;
+      });
+    },
+    [updateFilters],
+  );
+
+  const clearFilters = useCallback(() => {
+    setFilters({});
+  }, [setFilters]);
+
+  const activeFilters = useMemo(
+    () =>
+      (Object.entries(currentFilters) as [TKey, string][]).map(
+        ([filterKey, filterValue]) => ({
+          filterKey,
+          filterValue,
+          lowerFilterValue: filterValue.toLowerCase(),
+        }),
+      ),
+    [currentFilters],
+  );
+
+  const filteredData = useMemo(() => {
+    if (activeFilters.length === 0) {
+      return [...data];
+    }
+
+    return data.filter((row) =>
+      activeFilters.every(({ filterKey, filterValue, lowerFilterValue }) => {
+        if (filterPredicate) {
+          return filterPredicate(row, filterValue, filterKey);
+        }
+
+        const columnValue = getColumnValue(row, filterKey);
+        if (columnValue == null) {
+          return false;
+        }
+
+        return String(columnValue).toLowerCase().includes(lowerFilterValue);
+      }),
+    );
+  }, [activeFilters, data, filterPredicate, getColumnValue]);
+
+  return {
+    filters: currentFilters,
+    filteredData,
+    hasActiveFilters: activeFilters.length > 0,
+    setFilter,
+    setFilters,
+    clearFilter,
+    clearFilters,
+  };
+}

package/src/hooks/useTableSort/index.ts

@@ -0,0 +1,5 @@
+export {
+  type UseTableSortParams,
+  type UseTableSortResult,
+} from "./types";
+export { useTableSort } from "./useTableSort";

package/src/hooks/useTableSort/types.ts

@@ -0,0 +1,23 @@
+import type {
+  TableHeadCellProps,
+  TableSortDirection,
+  TableSortState,
+} from "../../ui/table/types";
+
+export type UseTableSortParams<TKey extends string = string> = {
+  sortKey?: TKey;
+  defaultSortKey?: TKey;
+  sortDirection?: TableSortDirection;
+  defaultSortDirection?: TableSortDirection;
+  onSortChange?: (nextSort: TableSortState<TKey>) => void;
+};
+
+export type UseTableSortResult<TKey extends string = string> =
+  TableSortState<TKey> & {
+    setSort: (nextSort: TableSortState<TKey>) => void;
+    clearSort: () => void;
+    toggleSort: (sortKey: TKey) => void;
+    getSortProps: (
+      sortKey: TKey,
+    ) => Pick<TableHeadCellProps, "sortKey" | "sortDirection" | "onSortChange">;
+  };

package/src/hooks/useTableSort/useTableSort.test.ts

@@ -0,0 +1,150 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import type { TableSortDirection } from "../../ui/table/types";
+import { useTableSort } from "./useTableSort";
+
+describe("useTableSort", () => {
+  it("should default to no active sort", () => {
+    const { result } = renderHook(() => useTableSort());
+    expect(result.current.sortKey).toBeUndefined();
+    expect(result.current.sortDirection).toBe("none");
+  });
+
+  it("should seed state from default sort params", () => {
+    const { result } = renderHook(() =>
+      useTableSort({
+        defaultSortKey: "name",
+        defaultSortDirection: "ascending",
+      }),
+    );
+    expect(result.current.sortKey).toBe("name");
+    expect(result.current.sortDirection).toBe("ascending");
+  });
+
+  it("should cycle a column through ascending, descending, and none", () => {
+    const { result } = renderHook(() => useTableSort<"name">());
+
+    act(() => {
+      result.current.toggleSort("name");
+    });
+    expect(result.current).toMatchObject({
+      sortKey: "name",
+      sortDirection: "ascending",
+    });
+
+    act(() => {
+      result.current.toggleSort("name");
+    });
+    expect(result.current).toMatchObject({
+      sortKey: "name",
+      sortDirection: "descending",
+    });
+
+    act(() => {
+      result.current.toggleSort("name");
+    });
+    expect(result.current).toMatchObject({
+      sortKey: undefined,
+      sortDirection: "none",
+    });
+  });
+
+  it("should support controlled sort state", () => {
+    const handleSortChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({
+        sortKey,
+        sortDirection,
+      }: {
+        sortKey?: string;
+        sortDirection?: TableSortDirection;
+      }) =>
+        useTableSort({
+          sortKey,
+          sortDirection,
+          onSortChange: handleSortChange,
+        }),
+      {
+        initialProps: {
+          sortKey: "createdAt" as string,
+          sortDirection: "ascending" as TableSortDirection,
+        },
+      },
+    );
+
+    act(() => {
+      result.current.toggleSort("createdAt");
+    });
+    expect(handleSortChange).toHaveBeenCalledWith({
+      sortKey: "createdAt",
+      sortDirection: "descending",
+    });
+    expect(result.current.sortDirection).toBe("ascending");
+
+    rerender({ sortKey: "createdAt", sortDirection: "descending" });
+    expect(result.current.sortDirection).toBe("descending");
+  });
+
+  it("should allow only sortKey to be controlled", () => {
+    const handleSortChange = vi.fn();
+    const { result } = renderHook(() =>
+      useTableSort({
+        sortKey: "name",
+        onSortChange: handleSortChange,
+      }),
+    );
+
+    act(() => {
+      result.current.toggleSort("name");
+    });
+
+    expect(handleSortChange).toHaveBeenCalledWith({
+      sortKey: "name",
+      sortDirection: "ascending",
+    });
+    expect(result.current.sortKey).toBe("name");
+    expect(result.current.sortDirection).toBe("ascending");
+  });
+
+  it("should allow only sortDirection to be controlled", () => {
+    const handleSortChange = vi.fn();
+    const { result } = renderHook(() =>
+      useTableSort<"name">({
+        sortDirection: "ascending",
+        onSortChange: handleSortChange,
+      }),
+    );
+
+    act(() => {
+      result.current.toggleSort("name");
+    });
+
+    expect(handleSortChange).toHaveBeenCalledWith({
+      sortKey: "name",
+      sortDirection: "ascending",
+    });
+    expect(result.current.sortKey).toBe("name");
+    expect(result.current.sortDirection).toBe("ascending");
+  });
+
+  it("should return TableHead-compatible sort props", () => {
+    const { result } = renderHook(() =>
+      useTableSort({
+        defaultSortKey: "status",
+        defaultSortDirection: "descending",
+      }),
+    );
+    const props = result.current.getSortProps("status");
+    expect(props).toMatchObject({
+      sortKey: "status",
+      sortDirection: "descending",
+    });
+
+    act(() => {
+      props.onSortChange?.({ sortKey: "status", sortDirection: "none" });
+    });
+    expect(result.current.sortKey).toBeUndefined();
+    expect(result.current.sortDirection).toBe("none");
+  });
+});

package/src/hooks/useTableSort/useTableSort.ts

@@ -0,0 +1,121 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+
+import type { TableSortDirection, TableSortState } from "../../ui/table/types";
+import type { UseTableSortParams, UseTableSortResult } from "./types";
+
+function nextSortDirection(
+  currentDirection: TableSortDirection,
+): TableSortDirection {
+  if (currentDirection === "ascending") {
+    return "descending";
+  }
+  if (currentDirection === "descending") {
+    return "none";
+  }
+  return "ascending";
+}
+
+function normalizeSortState<TKey extends string>(
+  nextSort: TableSortState<TKey>,
+): TableSortState<TKey> {
+  if (!nextSort.sortKey || nextSort.sortDirection === "none") {
+    return { sortKey: undefined, sortDirection: "none" };
+  }
+  return nextSort;
+}
+
+export function useTableSort<TKey extends string = string>({
+  sortKey,
+  defaultSortKey,
+  sortDirection,
+  defaultSortDirection = "none",
+  onSortChange,
+}: UseTableSortParams<TKey> = {}): UseTableSortResult<TKey> {
+  const [internalSort, setInternalSort] = useState<TableSortState<TKey>>(() =>
+    normalizeSortState({
+      sortKey: defaultSortKey,
+      sortDirection: defaultSortDirection,
+    }),
+  );
+
+  const isSortKeyControlled = sortKey !== undefined;
+  const isSortDirectionControlled = sortDirection !== undefined;
+  const currentSort = normalizeSortState({
+    sortKey: isSortKeyControlled ? sortKey : internalSort.sortKey,
+    sortDirection: isSortDirectionControlled
+      ? sortDirection
+      : internalSort.sortDirection,
+  });
+
+  const setSort = useCallback(
+    (nextSort: TableSortState<TKey>) => {
+      const normalized = normalizeSortState(nextSort);
+      if (!isSortKeyControlled || !isSortDirectionControlled) {
+        setInternalSort((previousSort) => ({
+          sortKey: isSortKeyControlled
+            ? previousSort.sortKey
+            : normalized.sortKey,
+          sortDirection: isSortDirectionControlled
+            ? previousSort.sortDirection
+            : normalized.sortDirection,
+        }));
+      }
+      onSortChange?.(normalized);
+    },
+    [isSortDirectionControlled, isSortKeyControlled, onSortChange],
+  );
+
+  const clearSort = useCallback(() => {
+    setSort({ sortKey: undefined, sortDirection: "none" });
+  }, [setSort]);
+
+  const toggleSort = useCallback(
+    (nextSortKey: TKey) => {
+      const direction =
+        currentSort.sortKey === nextSortKey
+          ? nextSortDirection(currentSort.sortDirection)
+          : "ascending";
+
+      setSort({
+        sortKey: nextSortKey,
+        sortDirection: direction,
+      });
+    },
+    [currentSort.sortDirection, currentSort.sortKey, setSort],
+  );
+
+  const getSortProps = useCallback(
+    (nextSortKey: TKey) => ({
+      sortKey: nextSortKey,
+      sortDirection:
+        currentSort.sortKey === nextSortKey
+          ? currentSort.sortDirection
+          : "none",
+      onSortChange: (nextSort: TableSortState) => {
+        setSort(nextSort as TableSortState<TKey>);
+      },
+    }),
+    [currentSort.sortDirection, currentSort.sortKey, setSort],
+  );
+
+  return useMemo(
+    () => ({
+      sortKey: currentSort.sortKey,
+      sortDirection: currentSort.sortDirection,
+      setSort,
+      clearSort,
+      toggleSort,
+      getSortProps,
+    }),
+    [
+      clearSort,
+      currentSort.sortDirection,
+      currentSort.sortKey,
+      getSortProps,
+      setSort,
+      toggleSort,
+    ],
+  );
+}

package/src/ui/divider/divider.test.tsx

@@ -0,0 +1,55 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { Divider } from "./divider";
+
+const DIVIDER_SLOT = '[data-slot="divider"]';
+
+function getDividerRoot(container: HTMLElement = document.body) {
+  const elements = container.querySelectorAll(DIVIDER_SLOT);
+  expect(elements.length).toBe(1);
+  return elements[0] as HTMLElement;
+}
+
+describe("Divider", () => {
+  it("should expose a stable displayName", () => {
+    expect(Divider.displayName).toBe("Divider");
+  });
+
+  it("should render a horizontal separator by default", () => {
+    render(<Divider />);
+    const root = screen.getByRole("separator");
+    expect(root).toHaveAttribute("data-slot", "divider");
+    expect(root).toHaveAttribute("aria-orientation", "horizontal");
+  });
+
+  it("should render a vertical separator when requested", () => {
+    render(<Divider orientation="vertical" />);
+    expect(screen.getByRole("separator")).toHaveAttribute(
+      "aria-orientation",
+      "vertical",
+    );
+  });
+
+  it("should render label content between two divider lines", () => {
+    render(<Divider label="Or continue with" />);
+    expect(screen.getByText("Or continue with")).toHaveAttribute(
+      "data-slot",
+      "divider-label",
+    );
+    expect(document.querySelectorAll("[aria-hidden]").length).toBe(2);
+  });
+
+  it("should apply appearance token classes", () => {
+    render(<Divider appearance="emerald" />);
+    expect(getDividerRoot().className).toMatch(/--zui-divider-emerald-fg/);
+  });
+
+  it("should forward refs to the separator element", () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<Divider ref={ref} />);
+    expect(ref.current).toBeInstanceOf(HTMLElement);
+    expect(ref.current?.getAttribute("data-slot")).toBe("divider");
+  });
+});

package/src/ui/empty-state/empty-state.test.tsx

@@ -0,0 +1,88 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { EmptyState } from "./empty-state";
+import {
+  EmptyStateAction,
+  EmptyStateDescription,
+  EmptyStateIcon,
+  EmptyStateTitle,
+} from "./empty-state-base";
+
+const EMPTY_STATE_SLOT = '[data-slot="empty-state"]';
+
+function getEmptyStateRoot(container: HTMLElement = document.body) {
+  const elements = container.querySelectorAll(EMPTY_STATE_SLOT);
+  expect(elements.length).toBe(1);
+  return elements[0] as HTMLElement;
+}
+
+describe("EmptyState", () => {
+  it("should set displayName on compound parts", () => {
+    expect(EmptyState.displayName).toBe("EmptyState");
+    expect(EmptyStateIcon.displayName).toBe("EmptyStateIcon");
+    expect(EmptyStateTitle.displayName).toBe("EmptyStateTitle");
+    expect(EmptyStateDescription.displayName).toBe("EmptyStateDescription");
+    expect(EmptyStateAction.displayName).toBe("EmptyStateAction");
+  });
+
+  it("should stamp data-slot on the root section", () => {
+    render(<EmptyState>Nothing here</EmptyState>);
+    const root = getEmptyStateRoot();
+    expect(root.tagName).toBe("SECTION");
+    expect(root).toHaveAttribute("data-slot", "empty-state");
+  });
+
+  it("should render title, description, icon, and action slots", () => {
+    render(
+      <EmptyState>
+        <EmptyStateIcon>!</EmptyStateIcon>
+        <EmptyStateTitle>No results</EmptyStateTitle>
+        <EmptyStateDescription>Try another filter.</EmptyStateDescription>
+        <EmptyStateAction>
+          <button type="button">Reset</button>
+        </EmptyStateAction>
+      </EmptyState>,
+    );
+
+    expect(
+      screen.getByRole("heading", { level: 2, name: "No results" }),
+    ).toHaveAttribute("data-slot", "empty-state-title");
+    expect(screen.getByText("Try another filter.")).toHaveAttribute(
+      "data-slot",
+      "empty-state-description",
+    );
+    expect(screen.getByText("!")).toHaveAttribute(
+      "data-slot",
+      "empty-state-icon",
+    );
+    expect(screen.getByRole("button", { name: "Reset" })).toBeVisible();
+  });
+
+  it("should apply live region state when requested", () => {
+    render(<EmptyState liveRegion="assertive">Updated</EmptyState>);
+    expect(getEmptyStateRoot()).toHaveAttribute("aria-live", "assertive");
+  });
+
+  it("should apply size classes to nested text slots through context", () => {
+    render(
+      <EmptyState size="lg">
+        <EmptyStateTitle>Large title</EmptyStateTitle>
+        <EmptyStateDescription>Large description</EmptyStateDescription>
+      </EmptyState>,
+    );
+
+    expect(screen.getByText("Large title").className).toMatch(/text-xl/);
+    expect(screen.getByText("Large description").className).toMatch(
+      /text-base/,
+    );
+  });
+
+  it("should forward refs to the root element", () => {
+    const ref = createRef<HTMLElement>();
+    render(<EmptyState ref={ref}>Empty</EmptyState>);
+    expect(ref.current).toBeInstanceOf(HTMLElement);
+    expect(ref.current?.getAttribute("data-slot")).toBe("empty-state");
+  });
+});

package/src/ui/marquee/marquee.test.tsx

@@ -1,9 +1,13 @@
-import { render, screen } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { Marquee } from "./marquee";
 
 describe("Marquee", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   it("exposes a display name", () => {
     expect(Marquee.displayName).toBe("Marquee");
   });
@@ -17,13 +21,14 @@ describe("Marquee", () => {
 
     expect(document.querySelector('[data-slot="marquee"]')).toBeTruthy();
     expect(document.querySelector('[data-slot="marquee-track"]')).toBeTruthy();
-    expect(screen.getAllByText("Acme")).toHaveLength(2);
-
     const groups = document.querySelectorAll(
       '[data-slot="marquee-item-group"]',
     );
+    expect(groups).toHaveLength(2);
+    expect(groups[0]?.textContent).toContain("Acme");
     expect(groups[1]).toHaveAttribute("aria-hidden", "true");
     expect(groups[1]).toHaveAttribute("inert");
+    expect(groups[1]?.textContent).toContain("Acme");
   });
 
   it("applies horizontal metadata by default", () => {
@@ -84,6 +89,42 @@ describe("Marquee", () => {
     });
   });
 
+  it("hides filler copies from assistive technology", async () => {
+    vi.spyOn(HTMLElement.prototype, "offsetWidth", "get").mockImplementation(
+      function (this: HTMLElement) {
+        return this.getAttribute("data-slot") === "marquee" ? 300 : 0;
+      },
+    );
+    vi.spyOn(HTMLElement.prototype, "scrollWidth", "get").mockImplementation(
+      function (this: HTMLElement) {
+        return this.getAttribute("data-slot") === "marquee-measure" ? 100 : 0;
+      },
+    );
+
+    render(
+      <Marquee>
+        <button type="button">Focusable item</button>
+      </Marquee>,
+    );
+
+    const firstGroup = document.querySelector(
+      '[data-slot="marquee-item-group"]',
+    );
+
+    await waitFor(() => {
+      expect(firstGroup?.textContent).toBe(
+        "Focusable itemFocusable itemFocusable item",
+      );
+    });
+
+    expect(
+      screen.getAllByRole("button", { name: "Focusable item" }),
+    ).toHaveLength(1);
+    expect(
+      firstGroup?.querySelectorAll('[aria-hidden="true"][inert]'),
+    ).toHaveLength(2);
+  });
+
   it("accepts string gap values", () => {
     render(
       <Marquee gap="2rem" data-testid="marquee">