@spaceinvoices/react-ui 0.1.1

package/src/components/table/hooks/use-table-state.ts

@@ -0,0 +1,293 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { FilterState, HttpMethodFilter, HttpStatusCodeFilter, StatusFilter, TableQueryParams } from "../types";
+
+type UseTableStateProps = {
+  initialParams?: TableQueryParams;
+  defaultOrderBy?: string;
+  onChangeParams?: (params: TableQueryParams) => void;
+  /** When true, disables URL sync entirely (for embedded tables like dashboard) */
+  disableUrlSync?: boolean;
+};
+
+/**
+ * Format date to YYYY-MM-DD for API (using local timezone)
+ */
+function formatDateForAPI(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Parse YYYY-MM-DD string to local Date (avoids UTC parsing issues)
+ */
+function parseDateString(dateStr: string): Date {
+  const [year, month, day] = dateStr.split("-").map(Number);
+  return new Date(year, month - 1, day);
+}
+
+/**
+ * Parse filter state from URL-friendly params
+ */
+function parseFilterStateFromParams(params: TableQueryParams): FilterState | null {
+  const state: FilterState = {};
+
+  // Parse date filter
+  if (params.filter_date_field && (params.filter_date_from || params.filter_date_to)) {
+    state.dateFilter = {
+      field: params.filter_date_field,
+      range: {
+        from: params.filter_date_from ? parseDateString(params.filter_date_from) : undefined,
+        to: params.filter_date_to ? parseDateString(params.filter_date_to) : undefined,
+      },
+    };
+  }
+
+  // Parse status filter
+  if (params.filter_status) {
+    state.statusFilters = params.filter_status.split(",") as StatusFilter[];
+  }
+
+  // Parse HTTP method filter
+  if (params.filter_method) {
+    state.httpMethod = params.filter_method as HttpMethodFilter;
+  }
+
+  // Parse HTTP status code filter
+  if (params.filter_http_status) {
+    state.httpStatusCode = params.filter_http_status as HttpStatusCodeFilter;
+  }
+
+  return Object.keys(state).length > 0 ? state : null;
+}
+
+/**
+ * Build API query JSON from filter state
+ * Note: API only supports flat field-level queries, not AND/OR operators
+ * For multiple statuses, only the first is used (API limitation)
+ */
+export function buildQueryFromFilterState(state: FilterState | null): string | undefined {
+  if (!state) return undefined;
+
+  const query: Record<string, unknown> = {};
+
+  // Date filter
+  if (state.dateFilter?.range.from || state.dateFilter?.range.to) {
+    const field = state.dateFilter.field;
+    const range = state.dateFilter.range;
+
+    if (range.from && range.to) {
+      query[field] = { between: [formatDateForAPI(range.from), formatDateForAPI(range.to)] };
+    } else if (range.from) {
+      query[field] = { gte: formatDateForAPI(range.from) };
+    } else if (range.to) {
+      query[field] = { lte: formatDateForAPI(range.to) };
+    }
+  }
+
+  // Status filter - apply first selected status only (API doesn't support OR)
+  if (state.statusFilters?.length) {
+    const status = state.statusFilters[0]; // Use first status
+    const today = formatDateForAPI(new Date());
+
+    switch (status) {
+      case "paid":
+        query.paid_in_full = { equals: true };
+        break;
+      case "unpaid":
+        query.paid_in_full = { equals: false };
+        query.voided_at = { equals: null };
+        break;
+      case "overdue":
+        query.paid_in_full = { equals: false };
+        query.date_due = { lt: today };
+        query.voided_at = { equals: null };
+        break;
+      case "voided":
+        query.voided_at = { not: null };
+        break;
+    }
+  }
+
+  if (Object.keys(query).length === 0) return undefined;
+  return JSON.stringify(query);
+}
+
+/**
+ * Manages table state (sorting, search, pagination) with optional URL sync
+ */
+export function useTableState({
+  initialParams = {},
+  defaultOrderBy = "-id",
+  onChangeParams,
+  disableUrlSync = false,
+}: UseTableStateProps) {
+  const [params, setParams] = useState<TableQueryParams>({
+    ...initialParams,
+    order_by: initialParams.order_by ?? defaultOrderBy,
+  });
+
+  // Use ref for onChangeParams to keep it stable
+  const onChangeParamsRef = useRef(onChangeParams);
+  onChangeParamsRef.current = onChangeParams;
+
+  // Keep track of previous initialParams to detect changes
+  const prevInitialParamsRef = useRef<string>(JSON.stringify(initialParams));
+  // Flag to track if we're updating from initialParams (to avoid calling onChangeParams)
+  const isUpdatingFromInitialRef = useRef(false);
+
+  // Sync internal state when initialParams changes (e.g., when navigating to same page resets URL)
+  useEffect(() => {
+    const currentParamsStr = JSON.stringify(initialParams);
+
+    // Only update if initialParams actually changed
+    if (currentParamsStr !== prevInitialParamsRef.current) {
+      prevInitialParamsRef.current = currentParamsStr;
+      isUpdatingFromInitialRef.current = true;
+      setParams({
+        ...initialParams,
+        order_by: initialParams.order_by ?? defaultOrderBy,
+      });
+    }
+  }, [initialParams, defaultOrderBy]);
+
+  // Sync params to parent or URL when they change
+  useEffect(() => {
+    // Skip if we're updating from initialParams to avoid infinite loop
+    if (isUpdatingFromInitialRef.current) {
+      isUpdatingFromInitialRef.current = false;
+      return;
+    }
+
+    // Skip URL sync entirely when disabled (e.g., dashboard embedded tables)
+    if (disableUrlSync) {
+      return;
+    }
+
+    const changeHandler = onChangeParamsRef.current;
+
+    if (changeHandler) {
+      // Notify parent of param changes (e.g., for router navigation)
+      changeHandler(params);
+    } else {
+      // Update URL directly
+      const searchParams = new URLSearchParams();
+
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          searchParams.set(key, String(value));
+        }
+      });
+
+      const newUrl = `${window.location.pathname}${searchParams.toString() ? `?${searchParams.toString()}` : ""}`;
+      window.history.pushState({}, "", newUrl);
+    }
+  }, [params, disableUrlSync]);
+
+  /**
+   * Handle sort change
+   */
+  const handleSort = useCallback(
+    (order: string | null) => {
+      setParams((prevParams) => ({
+        ...prevParams,
+        order_by: order ?? defaultOrderBy,
+        prev_cursor: undefined,
+        next_cursor: undefined,
+      }));
+    },
+    [defaultOrderBy],
+  );
+
+  /**
+   * Handle search change
+   */
+  const handleSearch = useCallback((value: string | null) => {
+    setParams((prevParams) => ({
+      ...prevParams,
+      search: value?.trim() ?? undefined,
+      prev_cursor: undefined,
+      next_cursor: undefined,
+    }));
+  }, []);
+
+  /**
+   * Handle pagination change
+   */
+  const handlePageChange = useCallback((cursor: { prev?: string; next?: string }) => {
+    setParams((prevParams) => ({
+      ...prevParams,
+      next_cursor: cursor.next,
+      prev_cursor: cursor.next ? undefined : cursor.prev,
+    }));
+  }, []);
+
+  /**
+   * Handle filter change - stores URL-friendly params
+   */
+  const handleFilterChange = useCallback((state: FilterState | null) => {
+    setParams((prevParams) => ({
+      ...prevParams,
+      // Clear old filter params
+      filter_date_field: undefined,
+      filter_date_from: undefined,
+      filter_date_to: undefined,
+      filter_status: undefined,
+      filter_method: undefined,
+      filter_http_status: undefined,
+      // Set new filter params
+      ...(state?.dateFilter && {
+        filter_date_field: state.dateFilter.field,
+        filter_date_from: state.dateFilter.range.from ? formatDateForAPI(state.dateFilter.range.from) : undefined,
+        filter_date_to: state.dateFilter.range.to ? formatDateForAPI(state.dateFilter.range.to) : undefined,
+      }),
+      ...(state?.statusFilters?.length && {
+        filter_status: state.statusFilters.join(","),
+      }),
+      ...(state?.httpMethod && {
+        filter_method: state.httpMethod,
+      }),
+      ...(state?.httpStatusCode && {
+        filter_http_status: state.httpStatusCode,
+      }),
+      prev_cursor: undefined,
+      next_cursor: undefined,
+    }));
+  }, []);
+
+  /**
+   * Parse current filter state from URL params
+   */
+  const filterState = useMemo(() => {
+    return parseFilterStateFromParams(params);
+  }, [
+    params.filter_date_field,
+    params.filter_date_from,
+    params.filter_date_to,
+    params.filter_status,
+    params.filter_method,
+    params.filter_http_status,
+    params,
+  ]);
+
+  /**
+   * Build params for API call (includes query JSON built from filter state)
+   * Note: filter_* params are kept for tables that need them (like request logs)
+   * while query JSON is added for tables that use it (like invoices)
+   */
+  const apiParams = useMemo(() => {
+    const query = buildQueryFromFilterState(filterState);
+    return { ...params, query };
+  }, [params, filterState]);
+
+  return {
+    params,
+    apiParams,
+    filterState,
+    handleSort,
+    handleSearch,
+    handlePageChange,
+    handleFilterChange,
+  };
+}

package/src/components/table/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Table Component Library
+ *
+ * A comprehensive, type-safe table system with built-in:
+ * - Sorting (client and server-side)
+ * - Search/filtering
+ * - Cursor-based pagination
+ * - Loading states
+ * - Empty states
+ * - TanStack Query integration
+ */
+
+export type { DataTableProps } from "./data-table";
+// Main component
+export { DataTable } from "./data-table";
+export { FormattedDate } from "./date-cell";
+// Hooks
+export { useTableFetch } from "./hooks/use-table-fetch";
+export { useTableQuery } from "./hooks/use-table-query";
+export { useTableState } from "./hooks/use-table-state";
+// Supporting components
+export { SearchInput } from "./search-input";
+export { SortableHeader } from "./sortable-header";
+export { TableEmptyState } from "./table-empty-state";
+export { TableNoResults } from "./table-no-results";
+export { Pagination } from "./table-pagination";
+export { TableSkeleton } from "./table-skeleton";
+
+// Types
+export type {
+  Column,
+  ListTableProps,
+  TableQueryParams,
+  TableQueryResponse,
+} from "./types";

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

@@ -0,0 +1,85 @@
+import { Search, X } from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { Button } from "@/ui/components/ui/button";
+import { Input } from "@/ui/components/ui/input";
+
+type SearchInputProps = {
+  initialValue?: string;
+  onSearch: (value: string | null) => void;
+  placeholder?: string;
+  debounceMs?: number;
+};
+
+/**
+ * Search input with optional clear button and form submission
+ */
+export function SearchInput({ initialValue = "", onSearch, placeholder = "Search...", debounceMs }: SearchInputProps) {
+  const [value, setValue] = useState(initialValue);
+
+  // Use ref to keep onSearch stable in useEffect
+  const onSearchRef = useRef(onSearch);
+  onSearchRef.current = onSearch;
+
+  // Sync with external value changes
+  useEffect(() => {
+    setValue(initialValue);
+  }, [initialValue]);
+
+  // Optional debounced search
+  useEffect(() => {
+    if (debounceMs === undefined) return;
+
+    const timer = setTimeout(() => {
+      onSearchRef.current(value || null);
+    }, debounceMs);
+
+    return () => clearTimeout(timer);
+  }, [value, debounceMs]);
+
+  const handleSubmit = useCallback(
+    (e: React.FormEvent) => {
+      e.preventDefault();
+      if (debounceMs === undefined) {
+        onSearchRef.current(value || null);
+      }
+    },
+    [debounceMs, value],
+  );
+
+  const handleChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    setValue(e.target.value);
+  }, []);
+
+  const handleClear = useCallback(() => {
+    setValue("");
+    onSearchRef.current(null);
+  }, []);
+
+  return (
+    <form onSubmit={handleSubmit} className="relative inline-block" data-testid="search-form">
+      <Search className="pointer-events-none absolute top-1/2 left-2.5 z-10 h-3 w-3 -translate-y-1/2 text-muted-foreground" />
+      <Input
+        type="search"
+        role="searchbox"
+        aria-label="Search"
+        placeholder={placeholder}
+        value={value}
+        onChange={handleChange}
+        className="h-8 w-[150px] pr-8 pl-8 lg:w-[250px] [&::-webkit-search-cancel-button]:hidden [&::-webkit-search-decoration]:hidden"
+      />
+      {value && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          onClick={handleClear}
+          className="absolute top-1/2 right-1 z-10 h-6 w-6 -translate-y-1/2 p-0 hover:bg-transparent"
+          aria-label="Clear search"
+        >
+          <X className="h-3 w-3 text-muted-foreground" />
+        </Button>
+      )}
+    </form>
+  );
+}

package/src/components/table/sortable-header.tsx

@@ -0,0 +1,56 @@
+import { ArrowDown, ArrowUp, ArrowUpDown } from "lucide-react";
+
+import { Button } from "@/ui/components/ui/button";
+import { cn } from "@/ui/lib/utils";
+
+type SortableHeaderProps = {
+  children: React.ReactNode;
+  field: string;
+  currentOrder?: string;
+  align?: "left" | "center" | "right";
+  onSort?: (order: string | null) => void;
+};
+
+/**
+ * Sortable column header with visual indicators
+ * Cycles through: none -> asc -> desc -> none
+ */
+export function SortableHeader({ children, field, currentOrder, align = "left", onSort }: SortableHeaderProps) {
+  const isActive = currentOrder?.replace(/^-/, "") === field;
+  const isDesc = currentOrder?.startsWith("-");
+
+  // Determine next sort state
+  const getNextOrder = () => {
+    if (!isActive) return field; // Not active -> ascending
+    if (!isDesc) return `-${field}`; // Ascending -> descending
+    return null; // Descending -> none
+  };
+
+  const nextOrder = getNextOrder();
+
+  return (
+    <Button
+      variant="ghost"
+      size="sm"
+      onClick={() => onSort?.(nextOrder)}
+      className={cn(
+        "h-8 gap-1",
+        isActive && "font-semibold",
+        align === "left" && "-ml-3",
+        align === "right" && "-mr-3",
+      )}
+      aria-label={`Sort by ${field}${isActive ? (isDesc ? " descending" : " ascending") : ""}`}
+    >
+      {children}
+      {isActive ? (
+        isDesc ? (
+          <ArrowDown className="h-4 w-4" aria-hidden="true" />
+        ) : (
+          <ArrowUp className="h-4 w-4" aria-hidden="true" />
+        )
+      ) : (
+        <ArrowUpDown className="h-4 w-4 opacity-50" aria-hidden="true" />
+      )}
+    </Button>
+  );
+}

package/src/components/table/table-empty-state.tsx

@@ -0,0 +1,40 @@
+import { Sprout } from "lucide-react";
+
+import { Button } from "@/ui/components/ui/button";
+
+type TableEmptyStateProps = {
+  resource: string;
+  createNewLink?: string;
+  createNewTrigger?: React.ReactNode;
+  /** Number of rows to calculate height (default: 10) */
+  rows?: number;
+};
+
+// Approximate row height in pixels (including padding/border)
+const ROW_HEIGHT = 53;
+
+/**
+ * Empty state shown when table has no data
+ */
+export function TableEmptyState({ resource, createNewLink, createNewTrigger, rows = 10 }: TableEmptyStateProps) {
+  // Calculate height based on row count (min 200px)
+  const height = Math.max(rows * ROW_HEIGHT, 200);
+
+  return (
+    <div className="flex flex-col items-center justify-center gap-3" style={{ height }}>
+      <Sprout size={70} strokeWidth={0.35} className="text-muted-foreground" />
+      <div className="space-y-1 text-center">
+        <p className="font-light text-lg text-muted-foreground">Your {resource} list is empty</p>
+        {(createNewLink || createNewTrigger) && (
+          <p className="text-muted-foreground text-sm">Get started by creating your first {resource}</p>
+        )}
+      </div>
+      {createNewLink && (
+        <Button variant="default" size="sm" asChild>
+          <a href={createNewLink}>Create {resource}</a>
+        </Button>
+      )}
+      {createNewTrigger && !createNewLink && <div>{createNewTrigger}</div>}
+    </div>
+  );
+}

package/src/components/table/table-no-results.tsx

@@ -0,0 +1,41 @@
+import { FileX } from "lucide-react";
+
+import { Button } from "@/ui/components/ui/button";
+import { TableCell, TableRow } from "@/ui/components/ui/table";
+
+type TableNoResultsProps = {
+  resource: string;
+  search?: (value: null) => void;
+  /** Number of rows to calculate height (default: 10) */
+  rows?: number;
+};
+
+// Approximate row height in pixels (including padding/border)
+const ROW_HEIGHT = 53;
+
+/**
+ * No results message shown when search returns empty
+ */
+export function TableNoResults({ resource, search, rows = 10 }: TableNoResultsProps) {
+  // Calculate height based on row count (min 150px)
+  const height = Math.max(rows * ROW_HEIGHT, 150);
+
+  return (
+    <TableRow className="hover:bg-transparent">
+      <TableCell colSpan={100} className="text-center align-middle" style={{ height }}>
+        <div className="flex flex-col items-center gap-3">
+          <FileX size={32} strokeWidth={1.5} className="text-muted-foreground" />
+          <div className="space-y-1">
+            <p className="font-medium text-muted-foreground">No {resource} found</p>
+            {search && <p className="text-muted-foreground text-sm">Try adjusting your search criteria</p>}
+          </div>
+          {search && (
+            <Button variant="link" size="sm" onClick={() => search(null)} className="underline">
+              Clear search
+            </Button>
+          )}
+        </div>
+      </TableCell>
+    </TableRow>
+  );
+}

package/src/components/table/table-pagination.tsx

@@ -0,0 +1,42 @@
+import { ChevronLeft, ChevronRight } from "lucide-react";
+
+import { Button } from "@/ui/components/ui/button";
+
+type PaginationProps = {
+  prevCursor?: string | null;
+  nextCursor?: string | null;
+  onPageChange: (cursor: { prev?: string; next?: string }) => void;
+};
+
+/**
+ * Cursor-based pagination controls
+ */
+export function Pagination({ prevCursor, nextCursor, onPageChange }: PaginationProps) {
+  const hasPrevious = Boolean(prevCursor);
+  const hasNext = Boolean(nextCursor);
+
+  return (
+    <div className="flex items-center justify-end space-x-2">
+      <Button
+        variant="outline"
+        size="sm"
+        className="h-8 w-8 cursor-pointer p-0"
+        onClick={() => onPageChange({ prev: prevCursor ?? undefined })}
+        disabled={!hasPrevious}
+        aria-label="Previous page"
+      >
+        <ChevronLeft className="h-4 w-4" />
+      </Button>
+      <Button
+        variant="outline"
+        size="sm"
+        className="h-8 w-8 cursor-pointer p-0"
+        onClick={() => onPageChange({ next: nextCursor ?? undefined })}
+        disabled={!hasNext}
+        aria-label="Next page"
+      >
+        <ChevronRight className="h-4 w-4" />
+      </Button>
+    </div>
+  );
+}

package/src/components/table/table-skeleton.tsx

@@ -0,0 +1,54 @@
+import { Skeleton } from "@/ui/components/ui/skeleton";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/ui/components/ui/table";
+
+type TableSkeletonProps = {
+  columns?: number;
+  rows?: number;
+};
+
+/**
+ * Loading skeleton for table component
+ */
+export function TableSkeleton({ columns = 5, rows = 10 }: TableSkeletonProps) {
+  return (
+    <div className="space-y-4">
+      {/* Search input skeleton */}
+      <Skeleton className="h-8 w-[250px]" />
+
+      {/* Table skeleton */}
+      <div className="rounded-lg border">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              {Array.from({ length: columns }, (_, i) => (
+                // biome-ignore lint/suspicious/noArrayIndexKey: skeleton
+                <TableHead key={`header-${i}`}>
+                  <Skeleton data-testid="skeleton-cell" className="my-2 h-4 w-[100px]" />
+                </TableHead>
+              ))}
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {Array.from({ length: rows }, (_, rowIndex) => (
+              // biome-ignore lint/suspicious/noArrayIndexKey: skeleton
+              <TableRow key={`row-${rowIndex}`}>
+                {Array.from({ length: columns }, (_, colIndex) => (
+                  // biome-ignore lint/suspicious/noArrayIndexKey: skeleton
+                  <TableCell key={`cell-${rowIndex}-${colIndex}`}>
+                    <Skeleton data-testid="skeleton-cell" className="my-2 h-4 w-[100px]" />
+                  </TableCell>
+                ))}
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
+
+      {/* Pagination skeleton */}
+      <div className="flex justify-end gap-2">
+        <Skeleton className="h-8 w-8" />
+        <Skeleton className="h-8 w-8" />
+      </div>
+    </div>
+  );
+}