@turtleclub/core 0.1.0-beta.100

package/src/helpers/usePagination.ts

@@ -0,0 +1,210 @@
+"use client";
+
+import { useQueryState, parseAsInteger } from "nuqs";
+import { useMemo, useCallback } from "react";
+import type { PaginationState } from "@tanstack/react-table";
+
+export interface UsePaginationOptions {
+  /** Default page size (default: 10) */
+  defaultPageSize?: number;
+  /** Default page index (default: 0) */
+  defaultPageIndex?: number;
+  /** Query param key for page index (default: 'page') */
+  pageIndexKey?: string;
+  /** Query param key for page size (default: 'pageSize') */
+  pageSizeKey?: string;
+}
+
+export interface UsePaginationReturn {
+  /** Current pagination state for TanStack Table */
+  pagination: PaginationState;
+  /** Function to update pagination state */
+  setPagination: (updater: PaginationState | ((prev: PaginationState) => PaginationState)) => void;
+  /** Current page index (0-based) */
+  pageIndex: number;
+  /** Current page size */
+  pageSize: number;
+  /** Set page index directly */
+  setPageIndex: (pageIndex: number) => void;
+  /** Set page size directly */
+  setPageSize: (pageSize: number) => void;
+  /** Go to next page */
+  nextPage: (totalPages?: number) => void;
+  /** Go to previous page */
+  previousPage: () => void;
+  /** Go to first page */
+  firstPage: () => void;
+  /** Go to last page */
+  lastPage: (totalPages: number) => void;
+  /** Reset pagination to defaults */
+  reset: () => void;
+  /** Check if can go to next page */
+  canNextPage: (totalPages?: number) => boolean;
+  /** Check if can go to previous page */
+  canPreviousPage: boolean;
+}
+
+/**
+ * Hook for managing server-side pagination state using nuqs.
+ *
+ * This hook synchronizes pagination state with URL query parameters,
+ * making it perfect for server-side pagination where the URL should
+ * reflect the current page and page size.
+ *
+ * @example
+ * ```tsx
+ * function MyTable() {
+ *   const {
+ *     pagination,
+ *     setPagination,
+ *     pageIndex,
+ *     pageSize,
+ *     setPageIndex,
+ *     setPageSize
+ *   } = usePagination({
+ *     defaultPageSize: 20,
+ *     pageIndexKey: 'page',
+ *     pageSizeKey: 'limit'
+ *   });
+ *
+ *   // Use with TanStack Table
+ *   const table = useReactTable({
+ *     data,
+ *     columns,
+ *     manualPagination: true,
+ *     pagination,
+ *     onPaginationChange: setPagination,
+ *     pageCount: Math.ceil(totalCount / pageSize),
+ *   });
+ *
+ *   return <DataTable table={table} />;
+ * }
+ * ```
+ */
+export function usePagination(options: UsePaginationOptions = {}): UsePaginationReturn {
+  const {
+    defaultPageSize = 10,
+    defaultPageIndex = 0,
+    pageIndexKey = "page",
+    pageSizeKey = "pageSize",
+  } = options;
+
+  // Use nuqs to manage query state
+  const [rawPageIndex, setRawPageIndex] = useQueryState(
+    pageIndexKey,
+    parseAsInteger.withDefault(defaultPageIndex)
+  );
+
+  const [rawPageSize, setRawPageSize] = useQueryState(
+    pageSizeKey,
+    parseAsInteger.withDefault(defaultPageSize)
+  );
+
+  // Ensure page index is never negative
+  const pageIndex = useMemo(() => Math.max(0, rawPageIndex), [rawPageIndex]);
+
+  // Use page size directly from query state
+  const pageSize = rawPageSize;
+
+  // Create pagination state for TanStack Table
+  const pagination = useMemo<PaginationState>(
+    () => ({
+      pageIndex,
+      pageSize,
+    }),
+    [pageIndex, pageSize]
+  );
+
+  // Set pagination function that handles both object and function updates
+  const setPagination = useCallback(
+    (updater: PaginationState | ((prev: PaginationState) => PaginationState)) => {
+      const newPagination = typeof updater === "function" ? updater(pagination) : updater;
+
+      if (newPagination.pageIndex !== pageIndex) {
+        setRawPageIndex(Math.max(0, newPagination.pageIndex));
+      }
+
+      if (newPagination.pageSize !== pageSize) {
+        setRawPageSize(newPagination.pageSize);
+      }
+    },
+    [pagination, pageIndex, pageSize, setRawPageIndex, setRawPageSize]
+  );
+
+  // Individual setters
+  const setPageIndex = useCallback(
+    (newPageIndex: number) => {
+      setRawPageIndex(Math.max(0, newPageIndex));
+    },
+    [setRawPageIndex]
+  );
+
+  const setPageSize = useCallback(
+    (newPageSize: number) => {
+      setRawPageSize(newPageSize);
+      // Reset to first page when page size changes
+      setRawPageIndex(0);
+    },
+    [setRawPageSize, setRawPageIndex]
+  );
+
+  // Navigation functions
+  const nextPage = useCallback(
+    (totalPages?: number) => {
+      const nextPageIndex = pageIndex + 1;
+      if (!totalPages || nextPageIndex < totalPages) {
+        setPageIndex(nextPageIndex);
+      }
+    },
+    [pageIndex, setPageIndex]
+  );
+
+  const previousPage = useCallback(() => {
+    if (pageIndex > 0) {
+      setPageIndex(pageIndex - 1);
+    }
+  }, [pageIndex, setPageIndex]);
+
+  const firstPage = useCallback(() => {
+    setPageIndex(0);
+  }, [setPageIndex]);
+
+  const lastPage = useCallback(
+    (totalPages: number) => {
+      setPageIndex(Math.max(0, totalPages - 1));
+    },
+    [setPageIndex]
+  );
+
+  // Reset function
+  const reset = useCallback(() => {
+    setRawPageIndex(defaultPageIndex);
+    setRawPageSize(defaultPageSize);
+  }, [setRawPageIndex, setRawPageSize, defaultPageIndex, defaultPageSize]);
+
+  // Navigation state
+  const canPreviousPage = pageIndex > 0;
+  const canNextPage = useCallback(
+    (totalPages?: number) => {
+      if (!totalPages) return true; // Assume we can go next if total pages unknown
+      return pageIndex < totalPages - 1;
+    },
+    [pageIndex]
+  );
+
+  return {
+    pagination,
+    setPagination,
+    pageIndex,
+    pageSize,
+    setPageIndex,
+    setPageSize,
+    nextPage,
+    previousPage,
+    firstPage,
+    lastPage,
+    reset,
+    canNextPage,
+    canPreviousPage,
+  };
+}

package/src/helpers/useSorting.ts

@@ -0,0 +1,185 @@
+"use client";
+
+import { useQueryState, parseAsString } from "nuqs";
+import { useMemo, useCallback } from "react";
+import type { SortingState } from "@tanstack/react-table";
+
+export interface UseSortingOptions {
+  /** Default sort column (default: undefined - no sorting) */
+  defaultSortBy?: string;
+  /** Default sort order (default: 'asc') */
+  defaultSortOrder?: "asc" | "desc";
+  /** Query param key for sort column (default: 'sortBy') */
+  sortByKey?: string;
+  /** Query param key for sort order (default: 'sortOrder') */
+  sortOrderKey?: string;
+}
+
+export interface UseSortingReturn {
+  /** Current sorting state for TanStack Table */
+  sorting: SortingState;
+  /** Function to update sorting state */
+  setSorting: (updater: SortingState | ((prev: SortingState) => SortingState)) => void;
+  /** Current sort column (undefined if no sorting) */
+  sortBy: string | undefined;
+  /** Current sort order */
+  sortOrder: "asc" | "desc";
+  /** Set sort column and order directly */
+  setSort: (column: string, order?: "asc" | "desc") => void;
+  /** Clear all sorting */
+  clearSort: () => void;
+  /** Toggle sort order for a column */
+  toggleSort: (column: string) => void;
+  /** Check if a column is currently sorted */
+  isSorted: (column: string) => boolean;
+  /** Get sort order for a column */
+  getSortOrder: (column: string) => "asc" | "desc" | undefined;
+}
+
+/**
+ * Hook for managing server-side sorting state using nuqs.
+ *
+ * This hook synchronizes sorting state with URL query parameters,
+ * making it perfect for server-side sorting where the URL should
+ * reflect the current sort state.
+ *
+ * @example
+ * ```tsx
+ * function MyTable() {
+ *   const {
+ *     sorting,
+ *     setSorting,
+ *     sortBy,
+ *     sortOrder,
+ *     setSort,
+ *     toggleSort
+ *   } = useSorting({
+ *     defaultSortBy: 'name',
+ *     defaultSortOrder: 'asc'
+ *   });
+ *
+ *   // Use with TanStack Table
+ *   const table = useReactTable({
+ *     data,
+ *     columns,
+ *     manualSorting: true,
+ *     sorting,
+ *     onSortingChange: setSorting,
+ *   });
+ *
+ *   return <DataTable table={table} />;
+ * }
+ * ```
+ */
+export function useSorting(options: UseSortingOptions = {}): UseSortingReturn {
+  const {
+    defaultSortBy,
+    defaultSortOrder = "asc",
+    sortByKey = "sortBy",
+    sortOrderKey = "sortOrder",
+  } = options;
+
+  // Use nuqs to manage query state
+  const [sortBy, setSortBy] = useQueryState(
+    sortByKey,
+    parseAsString.withDefault(defaultSortBy || "")
+  );
+
+  const [sortOrder, setSortOrder] = useQueryState(
+    sortOrderKey,
+    parseAsString.withDefault(defaultSortOrder)
+  );
+
+  // Ensure sort order is valid
+  const validSortOrder = useMemo(() => {
+    return sortOrder === "desc" ? "desc" : "asc";
+  }, [sortOrder]);
+
+  // Create sorting state for TanStack Table
+  const sorting = useMemo<SortingState>(() => {
+    if (!sortBy || sortBy.trim() === "") {
+      return [];
+    }
+    return [
+      {
+        id: sortBy,
+        desc: validSortOrder === "desc",
+      },
+    ];
+  }, [sortBy, validSortOrder]);
+
+  // Set sorting function that handles both object and function updates
+  const setSorting = useCallback(
+    (updater: SortingState | ((prev: SortingState) => SortingState)) => {
+      const newSorting = typeof updater === "function" ? updater(sorting) : updater;
+
+      if (newSorting.length === 0) {
+        // Clear sorting
+        setSortBy("");
+      } else {
+        // Set first sort (TanStack Table typically only has one sort at a time)
+        const firstSort = newSorting[0];
+        setSortBy(firstSort.id);
+        setSortOrder(firstSort.desc ? "desc" : "asc");
+      }
+    },
+    [sorting, setSortBy, setSortOrder]
+  );
+
+  // Set sort column and order directly
+  const setSort = useCallback(
+    (column: string, order: "asc" | "desc" = "asc") => {
+      setSortBy(column);
+      setSortOrder(order);
+    },
+    [setSortBy, setSortOrder]
+  );
+
+  // Clear all sorting
+  const clearSort = useCallback(() => {
+    setSortBy(null);
+  }, [setSortBy]);
+
+  // Toggle sort order for a column
+  const toggleSort = useCallback(
+    (column: string) => {
+      if (sortBy === column) {
+        // Same column, toggle order
+        setSortOrder(validSortOrder === "asc" ? "desc" : "asc");
+      } else {
+        // Different column, set new column with asc
+        setSortBy(column);
+        setSortOrder("asc");
+      }
+    },
+    [sortBy, validSortOrder, setSortBy, setSortOrder]
+  );
+
+  // Check if a column is currently sorted
+  const isSorted = useCallback(
+    (column: string) => {
+      return sortBy === column;
+    },
+    [sortBy]
+  );
+
+  // Get sort order for a column
+  const getSortOrder = useCallback(
+    (column: string) => {
+      return sortBy === column ? validSortOrder : undefined;
+    },
+    [sortBy, validSortOrder]
+  );
+
+  return {
+    sorting,
+    setSorting,
+    sortBy: sortBy || undefined,
+    sortOrder: validSortOrder,
+    setSort,
+    clearSort,
+    toggleSort,
+    isSorted,
+    getSortOrder,
+  };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./filters";
+export * from "./wrappers";
+export * from "./helpers";
+export * from "./selectors";

package/src/selectors/ChainSelector.tsx

@@ -0,0 +1,72 @@
+"use client";
+
+import { useMemo } from "react";
+import { Combobox } from "@turtleclub/ui";
+import { useSupportedChains } from "@turtleclub/hooks";
+
+interface ChainSelectorProps {
+  /** Selected chain ID */
+  value: string;
+  /** Callback when selection changes */
+  onValueChange: (value: string) => void;
+  /** Placeholder text */
+  placeholder?: string;
+  /** Whether the selector is disabled */
+  disabled?: boolean;
+  /** Custom className */
+  className?: string;
+  /** Whether to close on select */
+  closeOnSelect?: boolean;
+  /** Whether to show search */
+  searchable?: boolean;
+}
+
+export function ChainSelector({
+  value,
+  onValueChange,
+  placeholder = "Select chain",
+  disabled = false,
+  className,
+  closeOnSelect = true,
+  searchable = true,
+}: ChainSelectorProps) {
+  const { chains, isLoading } = useSupportedChains({
+    page: 1,
+    limit: 100, // High limit to fetch all chains
+  });
+
+  const chainOptions = useMemo(() => {
+    if (!chains || chains.length === 0) return [];
+
+    const filteredChains = chains.filter((chain) => chain.status === "active");
+
+    return filteredChains.map((chain) => ({
+      label: chain.name,
+      value: chain?.id ?? "",
+      icon: chain.logoUrl
+        ? () => (
+            <img
+              src={chain.logoUrl}
+              alt={chain.name}
+              width={16}
+              height={16}
+              className="size-4 rounded-full"
+            />
+          )
+        : undefined,
+    }));
+  }, [chains]);
+
+  return (
+    <Combobox
+      searchable={searchable}
+      options={chainOptions}
+      value={value}
+      onValueChange={onValueChange}
+      disabled={disabled || isLoading}
+      placeholder={isLoading ? "Loading chains..." : placeholder}
+      closeOnSelect={closeOnSelect}
+      className={className}
+    />
+  );
+}

package/src/selectors/ChainsSelector.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import { useMemo } from "react";
+import { MultiSelect } from "@turtleclub/ui";
+import { useSupportedChains } from "@turtleclub/hooks";
+
+interface ChainSelectorProps {
+  /** Selected chain IDs */
+  value: string[];
+  /** Callback when selection changes */
+  onValueChange: (values: string[]) => void;
+  /** Placeholder text */
+  placeholder?: string;
+  /** Whether the selector is disabled */
+  disabled?: boolean;
+  /** Custom className */
+  className?: string;
+  /** Maximum count to show in trigger */
+  maxCount?: number;
+  /** Whether to close on select */
+  closeOnSelect?: boolean;
+  /** Whether to show search */
+  searchable?: boolean;
+}
+
+export function ChainsSelector({
+  value,
+  onValueChange,
+  placeholder = "Select chains",
+  disabled = false,
+  className,
+  maxCount = 1,
+  closeOnSelect = true,
+  searchable = true,
+}: ChainSelectorProps) {
+  const { chains, isLoading } = useSupportedChains({
+    page: 1,
+    limit: 100, // High limit to fetch all chains
+  });
+
+  const chainOptions = useMemo(() => {
+    if (!chains || chains.length === 0) return [];
+
+    const filteredChains = chains.filter((chain) => chain.status === "active");
+
+    return filteredChains.map((chain) => ({
+      label: chain.name,
+      value: chain?.id ?? "",
+      icon: chain.logoUrl
+        ? () => (
+            <img
+              src={chain.logoUrl}
+              alt={chain.name}
+              width={16}
+              height={16}
+              className="size-4 rounded-full"
+            />
+          )
+        : undefined,
+    }));
+  }, [chains]);
+
+  return (
+    <MultiSelect
+      searchable={searchable}
+      options={chainOptions}
+      value={value}
+      onValueChange={onValueChange}
+      disabled={disabled || isLoading}
+      placeholder={isLoading ? "Loading chains..." : placeholder}
+      closeOnSelect={closeOnSelect}
+      maxCount={maxCount}
+      className={className}
+    />
+  );
+}

package/src/selectors/OpportunitiesSelector.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+import { useMemo } from "react";
+import { MultiSelect } from "@turtleclub/ui";
+import { useOpportunities } from "@turtleclub/hooks";
+
+interface OpportunitySelectorProps {
+  /** Selected opportunity IDs */
+  value: string[];
+  /** Callback when selection changes */
+  onValueChange: (values: string[]) => void;
+  /** Placeholder text */
+  placeholder?: string;
+  /** Whether the selector is disabled */
+  disabled?: boolean;
+  /** Custom className */
+  className?: string;
+  /** Maximum count to show in trigger */
+  maxCount?: number;
+  /** Whether to close on select */
+  closeOnSelect?: boolean;
+  /** Whether to show search */
+  searchable?: boolean;
+}
+
+export function OpportunitiesSelector({
+  value,
+  onValueChange,
+  placeholder = "Select opportunities",
+  disabled = false,
+  className,
+  maxCount = 1,
+  closeOnSelect = true,
+  searchable = true,
+}: OpportunitySelectorProps) {
+  const { data: opportunitiesData, isLoading } = useOpportunities();
+
+  const opportunities = useMemo(
+    () => opportunitiesData?.opportunities ?? [],
+    [opportunitiesData?.opportunities]
+  );
+
+  const opportunityOptions = useMemo(() => {
+    if (!opportunities || opportunities.length === 0) return [];
+
+    const filteredOpportunities = opportunities.filter((opp) => opp.status === "active");
+
+    return filteredOpportunities.map((opportunity) => ({
+      label: opportunity.name || opportunity.shortName,
+      value: opportunity.id!,
+      description: opportunity.shortName !== opportunity.name ? opportunity.shortName : undefined,
+      icon: opportunity.depositTokens?.[0]?.logoUrl
+        ? () => (
+            <img
+              src={opportunity.depositTokens[0].logoUrl}
+              alt={opportunity.name}
+              width={16}
+              height={16}
+              className="size-4 rounded-full"
+            />
+          )
+        : undefined,
+    }));
+  }, [opportunities]);
+
+  return (
+    <MultiSelect
+      searchable={searchable}
+      options={opportunityOptions}
+      value={value}
+      onValueChange={onValueChange}
+      disabled={disabled || isLoading}
+      placeholder={isLoading ? "Loading opportunities..." : placeholder}
+      closeOnSelect={closeOnSelect}
+      maxCount={maxCount}
+      className={className}
+    />
+  );
+}

package/src/selectors/OpportunitySelector.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+import { useMemo } from "react";
+import { Combobox } from "@turtleclub/ui";
+import { useOpportunities } from "@turtleclub/hooks";
+
+interface OpportunitySelectorProps {
+  /** Selected opportunity ID */
+  value: string;
+  /** Callback when selection changes */
+  onValueChange: (value: string) => void;
+  /** Placeholder text */
+  placeholder?: string;
+  /** Whether the selector is disabled */
+  disabled?: boolean;
+  /** Custom className */
+  className?: string;
+  /** Whether to close on select */
+  closeOnSelect?: boolean;
+  /** Whether to show search */
+  searchable?: boolean;
+}
+
+export function OpportunitySelector({
+  value,
+  onValueChange,
+  placeholder = "Select opportunity",
+  disabled = false,
+  className,
+  closeOnSelect = true,
+  searchable = true,
+}: OpportunitySelectorProps) {
+  const { data: opportunitiesData, isLoading } = useOpportunities();
+
+  const opportunities = useMemo(
+    () => opportunitiesData?.opportunities ?? [],
+    [opportunitiesData?.opportunities]
+  );
+
+  const opportunityOptions = useMemo(() => {
+    if (!opportunities || opportunities.length === 0) return [];
+
+    const filteredOpportunities = opportunities.filter((opp) => opp.status === "active");
+
+    return filteredOpportunities.map((opportunity) => ({
+      label: opportunity.name || opportunity.shortName,
+      value: opportunity.id!,
+      description: opportunity.shortName !== opportunity.name ? opportunity.shortName : undefined,
+      icon: opportunity.depositTokens?.[0]?.logoUrl
+        ? () => (
+            <img
+              src={opportunity.depositTokens[0].logoUrl}
+              alt={opportunity.name}
+              width={16}
+              height={16}
+              className="size-4 rounded-full"
+            />
+          )
+        : undefined,
+    }));
+  }, [opportunities]);
+
+  return (
+    <Combobox
+      searchable={searchable}
+      options={opportunityOptions}
+      value={value}
+      onValueChange={onValueChange}
+      disabled={disabled || isLoading}
+      placeholder={isLoading ? "Loading opportunities..." : placeholder}
+      closeOnSelect={closeOnSelect}
+      className={className}
+    />
+  );
+}