@zentauri-ui/zentauri-components 1.8.0 → 1.8.2

package/src/hooks/useTableFilter/useTableFilter.test.ts

@@ -0,0 +1,141 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { useTableFilter } from "./useTableFilter";
+
+const rows = [
+  { name: "Atlas", status: "active", seats: 12 },
+  { name: "Beacon", status: "paused", seats: 4 },
+  { name: "Comet", status: "active", seats: 8 },
+] as const;
+
+describe("useTableFilter", () => {
+  it("should return all rows when no filters are active", () => {
+    const { result } = renderHook(() => useTableFilter({ data: rows }));
+    expect(result.current.filteredData).toEqual(rows);
+    expect(result.current.hasActiveFilters).toBe(false);
+  });
+
+  it("should filter rows by a string column value", () => {
+    const { result } = renderHook(() =>
+      useTableFilter({
+        data: rows,
+        defaultFilters: { status: "active" },
+      }),
+    );
+    expect(result.current.filteredData.map((row) => row.name)).toEqual([
+      "Atlas",
+      "Comet",
+    ]);
+    expect(result.current.hasActiveFilters).toBe(true);
+  });
+
+  it("should combine multiple column filters", () => {
+    const { result } = renderHook(() =>
+      useTableFilter({
+        data: rows,
+        defaultFilters: { status: "active", name: "com" },
+      }),
+    );
+    expect(result.current.filteredData).toEqual([rows[2]]);
+  });
+
+  it("should update and clear filters in uncontrolled mode", () => {
+    const { result } = renderHook(() => useTableFilter({ data: rows }));
+
+    act(() => {
+      result.current.setFilter("name", "bea");
+    });
+    expect(result.current.filteredData).toEqual([rows[1]]);
+
+    act(() => {
+      result.current.clearFilter("name");
+    });
+    expect(result.current.filteredData).toEqual(rows);
+
+    act(() => {
+      result.current.setFilters({ status: "paused" });
+    });
+    expect(result.current.filteredData).toEqual([rows[1]]);
+
+    act(() => {
+      result.current.clearFilters();
+    });
+    expect(result.current.filteredData).toEqual(rows);
+  });
+
+  it("should preserve batched uncontrolled filter updates", () => {
+    const { result } = renderHook(() => useTableFilter({ data: rows }));
+
+    act(() => {
+      result.current.setFilter("status", "active");
+      result.current.setFilter("name", "atlas");
+    });
+
+    expect(result.current.filters).toEqual({
+      status: "active",
+      name: "atlas",
+    });
+    expect(result.current.filteredData).toEqual([rows[0]]);
+  });
+
+  it("should support controlled filters", () => {
+    const handleFiltersChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ filters }: { filters: Record<string, string> }) =>
+        useTableFilter({
+          data: rows,
+          filters,
+          onFiltersChange: handleFiltersChange,
+        }),
+      { initialProps: { filters: { status: "active" } } },
+    );
+
+    expect(result.current.filteredData.length).toBe(2);
+    act(() => {
+      result.current.setFilter("name", "atlas");
+    });
+    expect(handleFiltersChange).toHaveBeenCalledWith({
+      status: "active",
+      name: "atlas",
+    });
+    expect(result.current.filters).toEqual({ status: "active" });
+
+    rerender({ filters: { status: "active", name: "atlas" } });
+    expect(result.current.filteredData).toEqual([rows[0]]);
+  });
+
+  it("should support custom value accessors and predicates", () => {
+    const { result } = renderHook(() =>
+      useTableFilter({
+        data: rows,
+        defaultFilters: { seats: "10" },
+        getColumnValue: (row, key) => row[key],
+        filterPredicate: (row, value, key) => Number(row[key]) >= Number(value),
+      }),
+    );
+    expect(result.current.filteredData).toEqual([rows[0]]);
+  });
+
+  it("should remove blank filter values", () => {
+    const { result } = renderHook(() =>
+      useTableFilter({
+        data: rows,
+        defaultFilters: { name: "   " },
+      }),
+    );
+    expect(result.current.filters).toEqual({});
+    expect(result.current.hasActiveFilters).toBe(false);
+  });
+
+  it("should guard against null filters at runtime", () => {
+    const { result } = renderHook(() =>
+      useTableFilter({
+        data: rows,
+        filters: null as unknown as Record<string, string>,
+      }),
+    );
+    expect(result.current.filters).toEqual({});
+    expect(result.current.filteredData).toEqual(rows);
+  });
+});

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/copy-button/animated/animations.ts

@@ -0,0 +1,22 @@
+import type { CopyButtonAnimationPresets } from "./types";
+
+export const copyButtonAnimationPresets: CopyButtonAnimationPresets = {
+  swap: {
+    initial: { opacity: 0, scale: 0.6, rotate: -45 },
+    animate: { opacity: 1, scale: 1, rotate: 0 },
+    exit: { opacity: 0, scale: 0.6, rotate: 45 },
+    transition: { type: "spring", stiffness: 520, damping: 24 },
+  },
+  pop: {
+    initial: { opacity: 0, scale: 0.4, rotate: 0 },
+    animate: { opacity: 1, scale: 1, rotate: 0 },
+    exit: { opacity: 0, scale: 0.4, rotate: 0 },
+    transition: { type: "spring", stiffness: 600, damping: 20 },
+  },
+  fade: {
+    initial: { opacity: 0, scale: 1, rotate: 0 },
+    animate: { opacity: 1, scale: 1, rotate: 0 },
+    exit: { opacity: 0, scale: 1, rotate: 0 },
+    transition: { duration: 0.16 },
+  },
+};

package/src/ui/copy-button/animated/copy-button-animated.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { AnimatePresence, motion } from "framer-motion";
+
+import { CopyButtonBase } from "../copy-button-base";
+import type { CopyButtonIconRenderer } from "../types";
+
+import { copyButtonAnimationPresets } from "./animations";
+import type { CopyButtonAnimatedProps } from "./types";
+
+export function CopyButtonAnimated({
+  animation = "swap",
+  ...props
+}: CopyButtonAnimatedProps) {
+  const preset = copyButtonAnimationPresets[animation];
+
+  const renderIcon: CopyButtonIconRenderer = ({
+    copied,
+    copyIcon,
+    copiedIcon,
+  }) => (
+    <AnimatePresence initial={false} mode="wait">
+      <motion.span
+        key={copied ? "copied" : "idle"}
+        className="inline-flex items-center justify-center"
+        initial={preset.initial}
+        animate={preset.animate}
+        exit={preset.exit}
+        transition={preset.transition}
+      >
+        {copied ? copiedIcon : copyIcon}
+      </motion.span>
+    </AnimatePresence>
+  );
+
+  return <CopyButtonBase {...props} renderIcon={renderIcon} />;
+}
+
+CopyButtonAnimated.displayName = "CopyButtonAnimated";

package/src/ui/copy-button/animated/index.ts

@@ -0,0 +1,10 @@
+"use client";
+
+export { CopyButtonAnimated } from "./copy-button-animated";
+export { copyButtonAnimationPresets } from "./animations";
+export type {
+  CopyButtonAnimatedProps,
+  CopyButtonAnimation,
+  CopyButtonAnimationPreset,
+  CopyButtonAnimationPresets,
+} from "./types";

package/src/ui/copy-button/animated/types.ts

@@ -0,0 +1,21 @@
+import type { Transition } from "framer-motion";
+
+import type { CopyButtonProps } from "../types";
+
+export type CopyButtonAnimation = "swap" | "pop" | "fade";
+
+export type CopyButtonAnimatedProps = CopyButtonProps & {
+  animation?: CopyButtonAnimation;
+};
+
+export type CopyButtonAnimationPreset = {
+  initial: { opacity: number; scale: number; rotate: number };
+  animate: { opacity: number; scale: number; rotate: number };
+  exit: { opacity: number; scale: number; rotate: number };
+  transition: Transition;
+};
+
+export type CopyButtonAnimationPresets = Record<
+  CopyButtonAnimation,
+  CopyButtonAnimationPreset
+>;