next-data-kit 9.2.0 → 9.3.0

package/dist/index-CzDzNX62.d.ts

@@ -0,0 +1,558 @@
+import * as React$1 from 'react';
+import React__default, { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * next-data-kit - Database Types (Mongo)
+ *
+ * MongoDB-specific types for filters and queries.
+ */
+/**
+ * Sort order for database queries
+ */
+type TSortOrder = 1 | -1 | 'asc' | 'desc' | 'ascending' | 'descending';
+/**
+ * Filter operators for individual fields (Mongo subset)
+ */
+type TMongoFilterOperators<T> = {
+    $eq?: T;
+    $ne?: T;
+    $gt?: T;
+    $gte?: T;
+    $lt?: T;
+    $lte?: T;
+    $in?: T[];
+    $nin?: T[];
+    $exists?: boolean;
+    $regex?: string | RegExp;
+    $options?: string;
+};
+/**
+ * Mongo root operators.
+ */
+type TMongoRootFilterOperators<T> = {
+    $and?: TMongoFilterQuery<T>[];
+    $or?: TMongoFilterQuery<T>[];
+    $nor?: TMongoFilterQuery<T>[];
+};
+/**
+ * Mongo filter query type.
+ */
+type TMongoFilterQuery<T> = {
+    [P in keyof T]?: T[P] | TMongoFilterOperators<T[P]>;
+} & TMongoRootFilterOperators<T>;
+/**
+ * Minimal Mongoose Model interface for the adapter.
+ */
+type TMongoModel<T = unknown> = {
+    countDocuments(filter?: TMongoFilterQuery<T>): Promise<number>;
+    find(filter?: TMongoFilterQuery<T>, projection?: unknown, options?: unknown): TMongoQuery<T>;
+};
+/**
+ * Mongoose Query interface.
+ */
+type TMongoQuery<T> = {
+    sort(sort: Record<string, TSortOrder>): TMongoQuery<T>;
+    limit(limit: number): TMongoQuery<T>;
+    skip(skip: number): TMongoQuery<T>;
+    then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+};
+
+/**
+ * next-data-kit - React Data Kit Types
+ *
+ * Core types for the next-data-kit server action and components.
+ */
+
+/**
+ * Sort options type that references keys from the item type
+ */
+type TSortOptions<T> = {
+    [K in keyof T]?: TSortOrder;
+};
+/**
+ * Sort entry for array-based sorting
+ */
+type TSortEntry = {
+    path: string;
+    value: 1 | -1;
+};
+/**
+ * Filter configuration item
+ */
+type TFilterConfiguration = {
+    type: 'REGEX' | 'EXACT';
+    field?: string;
+};
+/**
+ * Filter configuration for automatic filtering
+ */
+type TFilterConfig = {
+    [key: string]: TFilterConfiguration;
+};
+/**
+ * Custom filter configuration
+ * Allows defining custom filter functions for specific filter keys
+ */
+type TFilterCustomConfig<T = unknown> = {
+    [id: string]: (data: unknown) => TMongoFilterQuery<T>;
+};
+/**
+ * Variant of TFilterCustomConfig that allows customizing the returned filter shape.
+ * Useful for Mongo (operator-based) vs. other ORMs (where clauses) in the future.
+ */
+type TFilterCustomConfigWithFilter<TDoc = unknown, TFilter = TMongoFilterQuery<TDoc>> = {
+    [id: string]: (data: unknown) => TFilter;
+};
+/**
+ * React Data Kit server action input
+ */
+type TDataKitInput<T = unknown> = {
+    action?: 'FETCH';
+    page?: number;
+    limit?: number;
+    sort?: TSortOptions<T>;
+    sorts?: TSortEntry[];
+    query?: Record<string, string | number | boolean>;
+    filter?: Record<string, string | number | boolean | null>;
+    filterConfig?: TFilterConfig;
+    filterCustom?: TFilterCustomConfig<T>;
+};
+/**
+ * React Data Kit server action result
+ */
+type TDataKitResult<R> = {
+    type: 'ITEMS';
+    items: R[];
+    documentTotal: number;
+};
+/**
+ * Pagination info for client-side use
+ */
+type TPaginationInfo = {
+    currentPage: number;
+    totalPages: number;
+    totalItems: number;
+    itemsPerPage: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+};
+/**
+ * React Data Kit Adapter Interface
+ * Defines the contract for a database adapter.
+ */
+type TDataKitAdapter<T> = (params: Readonly<{
+    filter: Record<string, unknown>;
+    sorts: TSortEntry[];
+    limit: number;
+    page: number;
+    skip: number;
+    input: TDataKitInput<T>;
+}>) => Promise<{
+    items: T[];
+    total: number;
+}>;
+
+/**
+ * next-data-kit - Hook Types
+ *
+ * Types for the next-data-kit hooks and state management.
+ */
+
+/**
+ * React Data Kit controller state
+ */
+type TDataKitState<T = unknown> = {
+    page: number;
+    limit: number;
+    sorts: TSortEntry[];
+    filter: Record<string, unknown>;
+    filterConfig?: TFilterConfig;
+    query?: Record<string, unknown>;
+    isLoading: boolean;
+    error: Error | null;
+    items: T[];
+    total: number;
+};
+/**
+ * React Data Kit controller actions
+ */
+type TDataKitActions<T = unknown, R = unknown> = {
+    setPage: (page: number) => void;
+    setLimit: (limit: number) => void;
+    setSort: (path: string, value: 1 | -1 | null, append?: boolean) => void;
+    setSorts: (sorts: TSortEntry[]) => void;
+    setFilter: (key: string, value: unknown) => void;
+    setFilters: (filters: Record<string, unknown>) => void;
+    clearFilters: () => void;
+    setQuery: (key: string, value: unknown) => void;
+    refresh: () => Promise<void>;
+    reset: () => void;
+    getInput: () => TDataKitInput<T>;
+    setItems: (items: R[]) => void;
+    setItemAt: (index: number, item: R) => void;
+    itemUpdate: (props: {
+        index: number;
+        data: Partial<R>;
+    } | {
+        id: string | number;
+        data: Partial<R>;
+    }) => void;
+    deleteItemAt: (index: number) => void;
+    itemDelete: (props: {
+        index: number;
+    } | {
+        id: string | number;
+    }) => void;
+    itemPush: (item: R, position?: 0 | 1) => void;
+    deleteBulk: (items: R[]) => void;
+};
+/**
+ * Combined next-data-kit controller return type
+ */
+type TUseDataKitReturn<T = unknown, R = unknown> = {
+    page: number;
+    limit: number;
+    sorts: TSortEntry[];
+    filter: Record<string, unknown>;
+    filterConfig?: TFilterConfig;
+    query?: Record<string, unknown>;
+    items: R[];
+    total: number;
+    state: {
+        isLoading: boolean;
+        error: Error | null;
+        hasNextPage: boolean;
+    };
+    actions: TDataKitActions<T, R>;
+};
+/**
+ * Options for the useDataKit hook
+ */
+type TUseDataKitOptions<T = unknown, R = unknown> = {
+    initial?: {
+        page?: number;
+        limit?: number;
+        sorts?: TSortEntry[];
+        filter?: Record<string, unknown>;
+        query?: Record<string, unknown>;
+    };
+    memory?: 'memory' | 'search-params';
+    filters?: {
+        id: string;
+        configuration?: TFilterConfiguration;
+    }[];
+    action: (input: TDataKitInput<T>) => Promise<TDataKitResult<R>>;
+    onSuccess?: (result: TDataKitResult<R>) => void;
+    onError?: (error: Error) => void;
+    autoFetch?: boolean;
+    debounce?: number;
+};
+/**
+ * Column definition for next-data-kit (headless)
+ */
+type TDataKitColumn<T = unknown> = {
+    id: string;
+    header: string;
+    accessor: keyof T | ((item: T) => unknown);
+    sortable?: boolean;
+    sortPath?: string;
+    filterable?: boolean;
+    filterKey?: string;
+    width?: string | number;
+    minWidth?: string | number;
+    maxWidth?: string | number;
+    align?: 'left' | 'center' | 'right';
+    cell?: (value: unknown, item: T, index: number) => React.ReactNode;
+    headerCell?: (column: TDataKitColumn<T>) => React.ReactNode;
+    hidden?: boolean;
+    sticky?: 'left' | 'right';
+};
+
+/**
+ * next-data-kit - Selectable Types
+ *
+ * Types for selectable/multi-select functionality in tables.
+ */
+/**
+ * Selection state for a table
+ */
+type TSelectionState<T = string> = {
+    selectedIds: Set<T>;
+    isAllSelected: boolean;
+    isIndeterminate: boolean;
+};
+/**
+ * Selection actions for a table
+ */
+type TSelectionActions<T = string> = {
+    select: (id: T) => void;
+    deselect: (id: T) => void;
+    toggle: (id: T) => void;
+    selectAll: (ids: T[]) => void;
+    deselectAll: () => void;
+    toggleAll: (ids: T[]) => void;
+    isSelected: (id: T) => boolean;
+    getSelectedArray: () => T[];
+};
+/**
+ * Combined selection hook return type
+ */
+type TUseSelectionReturn<T = string> = TSelectionState<T> & TSelectionActions<T>;
+/**
+ * Selection mode for tables
+ */
+type TSelectionMode = 'single' | 'multiple' | 'none';
+/**
+ * Selectable item type
+ */
+type TSelectable = {
+    id: string;
+    selected?: boolean;
+    disabled?: boolean;
+};
+
+/**
+ * next-data-kit - Component Types
+ *
+ * Types for the React Data Kit component and related UI elements.
+ */
+
+/**
+ * Extract the item type from a TDataKitResult
+ */
+type TExtractDataKitItemFromResult<R> = R extends TDataKitResult<infer I> ? I : R extends {
+    items: (infer I)[];
+} ? I : R extends [true, infer Ok] ? (Ok extends {
+    items: (infer I)[];
+} ? I : never) : never;
+/**
+ * Extract the item type from an action function's return type
+ */
+type TExtractDataKitItemType<T> = T extends (input: TDataKitInput<unknown>) => infer R ? TExtractDataKitItemFromResult<Awaited<R>> : never;
+/**
+ * Column definition for React Data Kit component
+ */
+type TDataKitComponentColumn<TItem, TRowState = unknown> = {
+    head: React.ReactNode;
+    body: (props: Readonly<{
+        item: TItem;
+        index: number;
+        state: TRowState;
+        setState: React.Dispatch<React.SetStateAction<TRowState>>;
+        setItem: (item: TItem) => void;
+        deleteItem: () => void;
+    }>) => React.ReactNode;
+    sortable?: {
+        path: string;
+        default: 1 | -1 | 0;
+    };
+};
+/**
+ * Base filter item properties
+ */
+type TDataKitFilterItemBase = {
+    id: string;
+    label: string;
+    placeholder?: string;
+    configuration?: TFilterConfiguration;
+};
+/**
+ * Text filter item
+ */
+type TDataKitFilterItemText = TDataKitFilterItemBase & {
+    type: 'TEXT';
+    defaultValue?: string;
+};
+/**
+ * Select filter item - dataset is required
+ */
+type TDataKitFilterItemSelect = TDataKitFilterItemBase & {
+    type: 'SELECT';
+    dataset: {
+        id: string;
+        name: string;
+        label: string;
+    }[];
+    defaultValue?: string;
+};
+/**
+ * Boolean filter item
+ */
+type TDataKitFilterItemBoolean = TDataKitFilterItemBase & {
+    type: 'BOOLEAN';
+    defaultValue?: boolean;
+};
+/**
+ * Filter item configuration - discriminated union for type safety
+ */
+type TDataKitFilterItem = TDataKitFilterItemText | TDataKitFilterItemSelect | TDataKitFilterItemBoolean;
+/**
+ * Bulk action definition for selectable tables
+ */
+type TDataKitBulkAction<TItem> = {
+    type: 'SEPARATOR';
+} | {
+    type?: 'MENU';
+    name: string;
+    icon?: React.ReactNode;
+    function: (selectedItems: TItem[]) => Promise<[boolean, {
+        deselectAll?: boolean;
+        updatedItems?: TItem[];
+    } | string]>;
+};
+/**
+ * Controller ref for external DataKitTable manipulation
+ */
+type TDataKitController<TItem> = {
+    itemPush: (item: TItem, position?: 0 | 1) => void;
+    itemUpdate: (props: {
+        index: number;
+        data: Partial<TItem>;
+    } | {
+        id: string | number;
+        data: Partial<TItem>;
+    }) => void;
+    itemDelete: (props: {
+        index: number;
+    } | {
+        id: string | number;
+    }) => void;
+    refetchData: () => void;
+    deleteBulk: (items: TItem[]) => void;
+    getSelectedItems: () => TItem[];
+    clearSelection: () => void;
+};
+/**
+ * Item with ID for selection purposes
+ */
+type TDataKitSelectableItem = {
+    id: string | number;
+};
+/**
+ * Memory persistence mode
+ */
+type TDataKitMemoryMode = 'memory' | 'search-params';
+/**
+ * DataKit Component Ref Type
+ * Exposes the internal state and actions of the DataKit component.
+ */
+type TDataKitRef<T = unknown, R = unknown> = TUseDataKitReturn<T, R>;
+
+/**
+ * next-data-kit - useDataKit Hook
+ *
+ * React hook for managing next-data-kit state and actions.
+ */
+
+declare const useDataKit: <T = unknown, R = unknown>(props: Readonly<TUseDataKitOptions<T, R>>) => TUseDataKitReturn<T, R>;
+
+/**
+ * next-data-kit - useSelection Hook
+ *
+ * React hook for managing table row selection.
+ */
+
+declare const useSelection: <T = string>(initialSelected?: T[]) => TUseSelectionReturn<T>;
+declare const useSelectionWithTotal: <T = string>(totalItems: T[], initialSelected?: T[]) => Omit<TUseSelectionReturn<T>, "toggleAll"> & {
+    isAllSelected: boolean;
+    isIndeterminate: boolean;
+    toggleAll: () => void;
+};
+
+/**
+ * next-data-kit - usePagination Hook
+ *
+ * React hook for calculating pagination state.
+ */
+
+type TUsePaginationReturn = TPaginationInfo & {
+    pages: (number | 'ellipsis')[];
+    firstPage: number;
+    lastPage: number;
+};
+declare const usePagination: (props: Readonly<{
+    page: number;
+    limit: number;
+    total: number;
+    siblingCount?: number;
+}>) => TUsePaginationReturn;
+
+type TDataKitContextValue<T = unknown, R = unknown> = TUseDataKitReturn<T, R>;
+declare const createDataKitContext: <T = unknown, R = unknown>() => {
+    DataKitProvider: (props: Readonly<{
+        value: TDataKitContextValue<T, R>;
+        children: ReactNode;
+    }>) => react_jsx_runtime.JSX.Element;
+    useDataKitContext: () => TDataKitContextValue<T, R>;
+    Context: React$1.Context<TDataKitContextValue<T, R> | null>;
+};
+declare const DefaultDataKitProvider: (props: Readonly<{
+    value: TDataKitContextValue<unknown, unknown>;
+    children: ReactNode;
+}>) => react_jsx_runtime.JSX.Element;
+declare const useDefaultDataKitContext: () => TDataKitContextValue<unknown, unknown>;
+declare const DefaultDataKitContext: React$1.Context<TDataKitContextValue<unknown, unknown> | null>;
+
+declare const DataKit: <TAction extends (input: TDataKitInput<unknown>) => Promise<TDataKitResult<TDataKitSelectableItem>>>(props: Readonly<{
+    action: TAction;
+    query?: Record<string, unknown>;
+    filters?: TDataKitFilterItem[];
+    limit?: {
+        default: number;
+    };
+    defaultSort?: {
+        path: string;
+        value: 1 | -1;
+    }[];
+    className?: string;
+    autoFetch?: boolean;
+    debounce?: number;
+    refetchInterval?: number;
+    memory?: TDataKitMemoryMode;
+    manual?: boolean;
+    pagination?: "SIMPLE" | "NUMBER";
+    children: (dataKit: TUseDataKitReturn<unknown, TExtractDataKitItemType<TAction>>) => React__default.ReactNode;
+    ref?: React__default.Ref<TDataKitRef<unknown, TExtractDataKitItemType<TAction>>>;
+}>) => React__default.ReactElement;
+
+/**
+ * next-data-kit - Utility Functions
+ *
+ * Helper utilities for client-side operations.
+ */
+
+/**
+ * Get the value from an item using a column accessor
+ */
+declare const getColumnValue: <T>(item: T, column: TDataKitColumn<T>) => unknown;
+/**
+ * Get the sort value for a column
+ */
+declare const getSortValue: (sorts: TSortEntry[], path: string) => 1 | -1 | null;
+/**
+ * Get the next sort value in the cycle: null -> 1 -> -1 -> null
+ */
+declare const getNextSortValue: (current: 1 | -1 | null) => 1 | -1 | null;
+/**
+ * Format a number with commas
+ */
+declare const formatNumber: (num: number) => string;
+/**
+ * Debounce a function
+ */
+declare const debounce: <T extends (...args: unknown[]) => unknown>(fn: T, delay: number) => ((...args: Parameters<T>) => void);
+/**
+ * Throttle a function
+ */
+declare const throttle: <T extends (...args: unknown[]) => unknown>(fn: T, limit: number) => ((...args: Parameters<T>) => void);
+/**
+ * Create a stable object key from sort entries
+ */
+declare const sortEntriesToKey: (sorts: TSortEntry[]) => string;
+/**
+ * Parse a sort key back to sort entries
+ */
+declare const keyToSortEntries: (key: string) => TSortEntry[];
+
+export { type TSortOrder as A, type TMongoFilterOperators as B, type TMongoRootFilterOperators as C, DefaultDataKitProvider as D, type TSortEntry as E, type TFilterConfig as F, type TFilterCustomConfig as G, type TDataKitState as H, type TDataKitActions as I, type TUseDataKitReturn as J, type TDataKitColumn as K, type TSelectionState as L, type TSelectionActions as M, type TUseSelectionReturn as N, type TSelectionMode as O, type TSelectable as P, type TExtractDataKitItemType as Q, type TDataKitComponentColumn as R, type TDataKitFilterItem as S, type TDataKitInput as T, type TDataKitBulkAction as U, type TDataKitController as V, type TDataKitSelectableItem as W, type TDataKitMemoryMode as X, type TDataKitRef as Y, type TMongoFilterQuery as a, type TFilterCustomConfigWithFilter as b, type TSortOptions as c, type TDataKitAdapter as d, type TDataKitResult as e, type TMongoModel as f, type TPaginationInfo as g, useSelection as h, useSelectionWithTotal as i, usePagination as j, createDataKitContext as k, useDefaultDataKitContext as l, DefaultDataKitContext as m, DataKit as n, getColumnValue as o, getSortValue as p, getNextSortValue as q, formatNumber as r, debounce as s, throttle as t, useDataKit as u, sortEntriesToKey as v, keyToSortEntries as w, type TUseDataKitOptions as x, type TUsePaginationReturn as y, type TDataKitContextValue as z };