next-data-kit 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,652 @@
+import * as React$1 from 'react';
+import React__default, { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * react-data-kit - Database Types (Mongo)
+ *
+ * MongoDB-specific types.
+ * Consolidated into a single file for simplicity.
+ */
+/**
+ * Sort order for database queries
+ */
+type TSortOrder = 1 | -1 | 'asc' | 'desc' | 'ascending' | 'descending';
+/**
+ * ObjectId placeholder type - compatible with MongoDB ObjectId.
+ */
+type TObjectId = {
+    toString(): string;
+    toHexString(): string;
+    equals(otherId: TObjectId | string): boolean;
+};
+/**
+ * Generic document type that represents a database document with an ID.
+ */
+type TDocument<TId = unknown> = {
+    _id: TId;
+    createdAt?: Date;
+    updatedAt?: Date;
+};
+/**
+ * Mongo document base (includes common Mongo-only fields).
+ */
+type TMongoDocument = TDocument<string | TObjectId> & {
+    __v?: number;
+};
+/**
+ * Hydrated document type - represents a document with methods.
+ */
+type THydratedDocument<T, TId = unknown> = T & TDocument<TId>;
+/**
+ * Hydrated Mongo document.
+ */
+type TMongoHydratedDocument<T> = T & TMongoDocument & {
+    toObject(): T;
+    toJSON(): T;
+};
+/**
+ * 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;
+    $all?: T extends Array<infer U> ? U[] : never;
+    $elemMatch?: T extends Array<infer U> ? TMongoFilterQuery<U> : never;
+    $size?: number;
+    $regex?: string | RegExp;
+    $options?: string;
+    $type?: string | number;
+};
+/**
+ * Mongo root operators.
+ */
+type TMongoRootFilterOperators<T> = {
+    $and?: TMongoFilterQuery<T>[];
+    $or?: TMongoFilterQuery<T>[];
+    $nor?: TMongoFilterQuery<T>[];
+    $not?: TMongoFilterQuery<T>;
+    $text?: {
+        $search: string;
+        $language?: string;
+        $caseSensitive?: boolean;
+        $diacriticSensitive?: boolean;
+    };
+    $where?: string | ((this: T) => boolean);
+};
+/**
+ * Mongo filter query type.
+ */
+type TMongoFilterQuery<T> = {
+    [P in keyof T]?: T[P] | TMongoFilterOperators<T[P]>;
+} & TMongoRootFilterOperators<T>;
+/**
+ * Populate options for query builder.
+ */
+type TPopulateOptions = {
+    path: string;
+    select?: string | Record<string, 0 | 1>;
+    model?: string;
+    match?: Record<string, unknown>;
+    populate?: TPopulateOptions | TPopulateOptions[];
+};
+/**
+ * Query builder for chaining query operations.
+ */
+type TQueryBuilder<TResult, TQueryHelpers = object> = Promise<TResult> & {
+    sort(options: Record<string, TSortOrder>): TQueryBuilder<TResult, TQueryHelpers>;
+    limit(count: number): TQueryBuilder<TResult, TQueryHelpers>;
+    skip(count: number): TQueryBuilder<TResult, TQueryHelpers>;
+    select(fields: string | Record<string, 0 | 1>): TQueryBuilder<TResult, TQueryHelpers>;
+    populate(path: string | TPopulateOptions): TQueryBuilder<TResult, TQueryHelpers>;
+    lean(): TQueryBuilder<TResult, TQueryHelpers>;
+    exec(): Promise<TResult>;
+};
+/**
+ * Generic Model type.
+ */
+type TModel<TRawDocType = unknown, TQueryHelpers = object, TId = unknown, TFilter = unknown> = {
+    countDocuments(filter?: TFilter): Promise<number>;
+    find(filter?: TFilter): TQueryBuilder<TRawDocType[], TQueryHelpers>;
+    findOne(filter?: TFilter): TQueryBuilder<TRawDocType | null, TQueryHelpers>;
+    findById(id: TId): TQueryBuilder<TRawDocType | null, TQueryHelpers>;
+};
+/**
+ * Convenience alias for a Mongo-backed model.
+ */
+type TMongoModel<TRawDocType = unknown, TQueryHelpers = object> = TModel<TRawDocType, TQueryHelpers, string | TObjectId, TMongoFilterQuery<TRawDocType>>;
+/**
+ * Extract raw document type from a Model
+ */
+type TExtractDocType<M> = M extends TModel<infer TRawDocType, unknown, unknown, unknown> ? TRawDocType : never;
+/**
+ * Extract hydrated document type from a Model
+ */
+type TExtractHydratedDoc<M> = M extends TModel<infer TRawDocType, unknown, infer TId, unknown> ? THydratedDocument<TRawDocType, TId> : never;
+
+/**
+ * react-data-kit - React Data Kit Types
+ *
+ * Core types for the react-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 for automatic filtering
+ */
+type TFilterConfig = {
+    [key: string]: {
+        type: 'regex' | 'exact';
+        field?: string;
+    };
+};
+/**
+ * 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, unknown>;
+    filter?: Record<string, unknown>;
+    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;
+};
+/**
+ * Calculate pagination info from react-data-kit result
+ */
+declare const calculatePagination: (page: number, limit: number, total: number) => TPaginationInfo;
+/**
+ * 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;
+}>;
+
+/**
+ * react-data-kit - Hook Types
+ *
+ * Types for the react-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;
+    deleteItemAt: (index: number) => void;
+    itemPush: (item: R, position?: 0 | 1) => void;
+    deleteBulk: (items: R[]) => void;
+};
+/**
+ * Combined react-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;
+    };
+    actions: TDataKitActions<T, R>;
+};
+/**
+ * React Data Kit controller options
+ */
+type TDataKitControllerOptions<T = unknown, R = unknown> = {
+    initial?: {
+        page?: number;
+        limit?: number;
+        sorts?: TSortEntry[];
+        filter?: Record<string, unknown>;
+        query?: Record<string, unknown>;
+    };
+    state?: 'memory' | 'search-params';
+    filterConfig?: TFilterConfig;
+    action: (input: TDataKitInput<T>) => Promise<TDataKitResult<R>>;
+    onSuccess?: (result: TDataKitResult<R>) => void;
+    onError?: (error: Error) => void;
+    autoFetch?: boolean;
+    debounce?: number;
+};
+/**
+ * Column definition for react-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';
+};
+
+/**
+ * react-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;
+};
+
+/**
+ * react-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;
+};
+/**
+ * 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> = {
+    name: string;
+    function: (selectedItems: TItem[]) => Promise<[boolean, {
+        deselectAll?: boolean;
+        updatedItems?: TItem[];
+    } | string]>;
+};
+/**
+ * Controller for external table manipulation
+ */
+type TDataKitComponentController<TItem> = {
+    itemPush: (item: TItem, position?: 0 | 1) => void;
+    refetchData: () => void;
+    deleteBulk: (items: TItem[]) => void;
+    getSelectedItems: () => TItem[];
+    clearSelection: () => void;
+};
+/**
+ * Item with ID for selection purposes
+ */
+type TDataKitSelectableItem = {
+    id: string | number;
+};
+/**
+ * State persistence mode
+ */
+type TDataKitStateMode = 'memory' | 'search-params';
+
+/**
+ * react-data-kit - Server Action
+ *
+ * The main server-side function for handling table data fetching
+ * with pagination, filtering, and sorting.
+ */
+
+type TDataKitServerActionOptions<T, R> = {
+    input: TDataKitInput<T>;
+    adapter: TDataKitAdapter<T> | TMongoModel<T>;
+    item: (item: T) => Promise<R> | R;
+    filter?: (filterInput?: Record<string, unknown>) => TMongoFilterQuery<T>;
+    filterCustom?: TFilterCustomConfigWithFilter<T, TMongoFilterQuery<T>>;
+    defaultSort?: TSortOptions<T>;
+};
+declare const dataKitServerAction: <T, R>(props: Readonly<TDataKitServerActionOptions<T, R>>) => Promise<TDataKitResult<R>>;
+
+/**
+ * react-data-kit - Mongoose Adapter
+ *
+ * Database adapter for Mongoose/MongoDB.
+ */
+
+declare const mongooseAdapter: <M extends TMongoModel<unknown, object>, DocType = TExtractDocType<M>>(model: M, options?: Readonly<{
+    filter?: (filterInput?: Record<string, unknown>) => TMongoFilterQuery<DocType>;
+    filterCustom?: TFilterCustomConfigWithFilter<DocType, TMongoFilterQuery<DocType>>;
+    defaultSort?: TSortOptions<DocType>;
+}>) => TDataKitAdapter<DocType>;
+
+/**
+ * react-data-kit - Memory Adapter
+ *
+ * In-memory adapter for demos, tests, and local playgrounds.
+ * Implements the React Data Kit adapter contract over an array dataset.
+ */
+
+/**
+ * Creates an adapter that pages/filters/sorts an in-memory dataset.
+ */
+declare const adapterMemory: <T extends Record<string, unknown>>(dataset: ReadonlyArray<T>, options?: Readonly<{
+    /** default behavior for filter keys not present in filterConfig */
+    defaultFilterType?: "regex" | "exact";
+}>) => TDataKitAdapter<T>;
+
+/**
+ * react-data-kit - Server Utilities
+ */
+
+/**
+ * Helper to escape regex special characters in a string
+ */
+declare const escapeRegex: (str: string) => string;
+/**
+ * Create a search filter for multiple fields
+ *
+ * @example
+ * ```typescript
+ * filterCustom: {
+ *   search: createSearchFilter(['name', 'email', 'phone'])
+ * }
+ * ```
+ */
+declare const createSearchFilter: <T>(fields: (keyof T | string)[]) => (value: unknown) => TMongoFilterQuery<T>;
+
+/**
+ * react-data-kit - useDataKit Hook
+ *
+ * React hook for managing react-data-kit state and actions.
+ */
+
+declare const useDataKit: <T = unknown, R = unknown>(props: Readonly<TDataKitControllerOptions<T, R>>) => TUseDataKitReturn<T, R>;
+
+/**
+ * react-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;
+};
+
+/**
+ * react-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>;
+    filterConfig?: TFilterConfig;
+    filters?: TDataKitFilterItem[];
+    limit?: {
+        default: number;
+    };
+    className?: string;
+    autoFetch?: boolean;
+    debounce?: number;
+    refetchInterval?: number;
+    state?: TDataKitStateMode;
+    manual?: boolean;
+    children: (dataKit: TUseDataKitReturn<unknown, TExtractDataKitItemType<TAction>>) => React__default.ReactNode;
+}>) => react_jsx_runtime.JSX.Element;
+
+/**
+ * react-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 { DataKit, DefaultDataKitContext as DataKitContext, DefaultDataKitProvider as DataKitProvider, type TDataKitActions, type TDataKitAdapter, type TDataKitBulkAction, type TDataKitColumn, type TDataKitComponentColumn, type TDataKitComponentController, type TDataKitContextValue, type TDataKitControllerOptions, type TDataKitFilterItem, type TDataKitInput, type TDataKitResult, type TDataKitSelectableItem, type TDataKitServerActionOptions, type TDataKitState, type TDataKitStateMode, type TDocument, type TExtractDataKitItemType, type TExtractDocType, type TExtractHydratedDoc, type TFilterConfig, type TFilterCustomConfig, type TFilterCustomConfigWithFilter, type THydratedDocument, type TModel, type TMongoDocument, type TMongoFilterOperators, type TMongoFilterQuery, type TMongoHydratedDocument, type TMongoModel, type TMongoRootFilterOperators, type TObjectId, type TPaginationInfo, type TPopulateOptions, type TQueryBuilder, type TSelectable, type TSelectionActions, type TSelectionMode, type TSelectionState, type TSortEntry, type TSortOptions, type TSortOrder, type TUseDataKitReturn, type TUsePaginationReturn, type TUseSelectionReturn, adapterMemory, calculatePagination, createDataKitContext, createSearchFilter, dataKitServerAction, debounce, escapeRegex, formatNumber, getColumnValue, getNextSortValue, getSortValue, keyToSortEntries, mongooseAdapter, sortEntriesToKey, throttle, useDataKit, useDefaultDataKitContext as useDataKitContext, usePagination, useSelection, useSelectionWithTotal };