@rowakit/table 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,389 @@
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Core type definitions for RowaKit Table
+ *
+ * These types define the contracts for:
+ * - Server-side data fetching (Fetcher)
+ * - Column definitions (ColumnDef)
+ * - Row actions (ActionDef)
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Query parameters passed to the fetcher function.
+ *
+ * All pagination, sorting, and filtering state is passed through this query.
+ */
+interface FetcherQuery {
+    /** Current page number (1-based) */
+    page: number;
+    /** Number of items per page */
+    pageSize: number;
+    /** Optional sorting configuration */
+    sort?: {
+        /** Field name to sort by */
+        field: string;
+        /** Sort direction */
+        direction: 'asc' | 'desc';
+    };
+    /** Optional filters (key-value pairs) */
+    filters?: Record<string, unknown>;
+}
+/**
+ * Result returned from the fetcher function.
+ */
+interface FetcherResult<T> {
+    /** Array of data items for the current page */
+    items: T[];
+    /** Total number of items across all pages */
+    total: number;
+}
+/**
+ * Server-side data fetcher function.
+ *
+ * This is the primary contract for loading table data. The fetcher receives
+ * pagination, sorting, and filter state, and returns a page of results.
+ *
+ * @example
+ * ```ts
+ * const fetchUsers: Fetcher<User> = async (query) => {
+ *   const response = await fetch(`/api/users?${new URLSearchParams({
+ *     page: query.page.toString(),
+ *     pageSize: query.pageSize.toString(),
+ *     sort: query.sort ? `${query.sort.field}:${query.sort.direction}` : '',
+ *   })}`);
+ *   return response.json();
+ * };
+ * ```
+ */
+type Fetcher<T> = (query: FetcherQuery) => Promise<FetcherResult<T>>;
+/**
+ * Union of supported column kinds.
+ *
+ * These represent the built-in column types that can be created
+ * via the `col.*` helper factory.
+ */
+type ColumnKind = 'text' | 'date' | 'boolean' | 'actions' | 'custom';
+/**
+ * Base column definition properties shared across all column types.
+ */
+interface BaseColumnDef<T> {
+    /** Unique identifier for this column */
+    id: string;
+    /** Column kind (text, date, boolean, actions, custom) */
+    kind: ColumnKind;
+    /** Optional header label (defaults to id if not provided) */
+    header?: string;
+    /** Whether this column can be sorted (default: false) */
+    sortable?: boolean;
+    /** Optional field name to extract from row data (for sortable columns) */
+    field?: keyof T & string;
+}
+/**
+ * Text column definition.
+ */
+interface TextColumnDef<T> extends BaseColumnDef<T> {
+    kind: 'text';
+    field: keyof T & string;
+    format?: (value: unknown) => string;
+}
+/**
+ * Date column definition.
+ */
+interface DateColumnDef<T> extends BaseColumnDef<T> {
+    kind: 'date';
+    field: keyof T & string;
+    format?: (value: Date | string | number) => string;
+}
+/**
+ * Boolean column definition.
+ */
+interface BooleanColumnDef<T> extends BaseColumnDef<T> {
+    kind: 'boolean';
+    field: keyof T & string;
+    format?: (value: boolean) => string;
+}
+/**
+ * Actions column definition.
+ */
+interface ActionsColumnDef<T> extends BaseColumnDef<T> {
+    kind: 'actions';
+    actions: ActionDef<T>[];
+}
+/**
+ * Custom column definition with render function.
+ *
+ * This is the escape hatch for any column that doesn't fit
+ * the built-in types.
+ */
+interface CustomColumnDef<T> extends BaseColumnDef<T> {
+    kind: 'custom';
+    field?: keyof T & string;
+    render: (row: T) => ReactNode;
+}
+/**
+ * Union type for all column definitions.
+ */
+type ColumnDef<T> = TextColumnDef<T> | DateColumnDef<T> | BooleanColumnDef<T> | ActionsColumnDef<T> | CustomColumnDef<T>;
+/**
+ * Row action definition.
+ *
+ * Actions appear in the actions column and can be clicked to perform
+ * operations on individual rows.
+ */
+interface ActionDef<T> {
+    /** Unique identifier for this action */
+    id: string;
+    /** Label displayed to the user */
+    label: string;
+    /** Optional icon identifier or component */
+    icon?: string | ReactNode;
+    /** Whether to show confirmation dialog before executing (default: false) */
+    confirm?: boolean;
+    /** Callback invoked when action is clicked (after confirmation if required) */
+    onClick: (row: T) => void | Promise<void>;
+    /** Optional loading state during async operations */
+    loading?: boolean;
+    /** Optional disabled state */
+    disabled?: boolean | ((row: T) => boolean);
+}
+
+/**
+ * Column helper factory functions
+ *
+ * These helpers provide a clean, type-safe API for defining table columns.
+ * They reduce boilerplate and enforce conventions while maintaining flexibility
+ * through the `col.custom` escape hatch.
+ *
+ * @packageDocumentation
+ */
+
+interface TextOptions {
+    /** Optional custom header label */
+    header?: string;
+    /** Enable sorting for this column */
+    sortable?: boolean;
+    /** Optional formatter function */
+    format?: (value: unknown) => string;
+}
+interface DateOptions {
+    /** Optional custom header label */
+    header?: string;
+    /** Enable sorting for this column */
+    sortable?: boolean;
+    /** Optional date formatter function */
+    format?: (value: Date | string | number) => string;
+}
+interface BooleanOptions {
+    /** Optional custom header label */
+    header?: string;
+    /** Enable sorting for this column */
+    sortable?: boolean;
+    /** Optional boolean formatter function */
+    format?: (value: boolean) => string;
+}
+/**
+ * Create a text column definition.
+ *
+ * @example
+ * ```ts
+ * col.text('name')
+ * col.text('email', { header: 'Email Address', sortable: true })
+ * col.text('status', { format: (val) => val.toUpperCase() })
+ * ```
+ */
+declare function text<T>(field: keyof T & string, options?: TextOptions): TextColumnDef<T>;
+/**
+ * Create a date column definition.
+ *
+ * @example
+ * ```ts
+ * col.date('createdAt')
+ * col.date('updatedAt', { header: 'Last Modified', sortable: true })
+ * col.date('birthday', {
+ *   format: (date) => new Date(date).toLocaleDateString()
+ * })
+ * ```
+ */
+declare function date<T>(field: keyof T & string, options?: DateOptions): DateColumnDef<T>;
+/**
+ * Create a boolean column definition.
+ *
+ * @example
+ * ```ts
+ * col.boolean('active')
+ * col.boolean('isPublished', { header: 'Published', sortable: true })
+ * col.boolean('enabled', {
+ *   format: (val) => val ? 'Yes' : 'No'
+ * })
+ * ```
+ */
+declare function boolean<T>(field: keyof T & string, options?: BooleanOptions): BooleanColumnDef<T>;
+/**
+ * Create an actions column definition.
+ *
+ * The actions column displays a set of actions (buttons/links) that can be
+ * performed on each row.
+ *
+ * @example
+ * ```ts
+ * col.actions([
+ *   { id: 'edit', label: 'Edit', onClick: (row) => editUser(row) },
+ *   { id: 'delete', label: 'Delete', confirm: true, onClick: (row) => deleteUser(row) }
+ * ])
+ * ```
+ */
+declare function actions<T>(actions: ActionDef<T>[]): ActionsColumnDef<T>;
+/**
+ * Create a custom column definition with full rendering control.
+ *
+ * This is the escape hatch for any column that doesn't fit the standard types.
+ * Use this for badges, avatars, complex formatting, or any custom UI.
+ *
+ * @example
+ * ```ts
+ * col.custom({
+ *   id: 'avatar',
+ *   header: 'User',
+ *   render: (row) => <img src={row.avatar} alt={row.name} />
+ * })
+ *
+ * col.custom({
+ *   id: 'price',
+ *   field: 'price',
+ *   render: (row) => <Money amount={row.price} currency={row.currency} />
+ * })
+ *
+ * col.custom({
+ *   id: 'status',
+ *   render: (row) => (
+ *     <Badge color={row.status === 'active' ? 'green' : 'gray'}>
+ *       {row.status}
+ *     </Badge>
+ *   )
+ * })
+ * ```
+ */
+declare function custom<T>(options: {
+    /** Unique column identifier */
+    id: string;
+    /** Optional custom header label */
+    header?: string;
+    /** Optional field name for sorting/filtering */
+    field?: keyof T & string;
+    /** Render function for cell content */
+    render: (row: T) => ReactNode;
+}): CustomColumnDef<T>;
+/**
+ * Column helper factory object.
+ *
+ * Provides convenient helper functions for creating column definitions.
+ *
+ * @example
+ * ```tsx
+ * import { col } from '@rowakit/table';
+ *
+ * const columns = [
+ *   col.text('name', { sortable: true }),
+ *   col.date('createdAt'),
+ *   col.boolean('active'),
+ *   col.actions([
+ *     { id: 'edit', label: 'Edit', onClick: (row) => {} }
+ *   ]),
+ *   col.custom({ id: 'badge', render: (row) => <Badge>{row.status}</Badge> })
+ * ];
+ * ```
+ */
+declare const col: {
+    readonly text: typeof text;
+    readonly date: typeof date;
+    readonly boolean: typeof boolean;
+    readonly actions: typeof actions;
+    readonly custom: typeof custom;
+};
+
+interface SmartTableProps<T> {
+    /** Server-side data fetcher function */
+    fetcher: Fetcher<T>;
+    /** Array of column definitions */
+    columns: ColumnDef<T>[];
+    /** Available page size options (default: [10, 20, 50]) */
+    pageSizeOptions?: number[];
+    /** Initial page size (default: 20) */
+    defaultPageSize?: number;
+    /** Function or field name to extract row key (default: uses 'id' field) */
+    rowKey?: keyof T | ((row: T) => string | number);
+    /** Optional CSS class name for the table container */
+    className?: string;
+}
+/**
+ * RowaKitTable - Server-side table component for internal/business apps.
+ *
+ * This component renders a table with headers and body based on column definitions.
+ * It handles all column types (text, date, boolean, actions, custom) and provides
+ * a clean API for defining table structure.
+ *
+ * Features:
+ * - Automatic data fetching on mount and query changes
+ * - Loading, error, and empty states
+ * - Stale request handling
+ * - Retry on error
+ *
+ * @example
+ * ```tsx
+ * import { RowaKitTable, col } from '@rowakit/table';
+ *
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ *   createdAt: Date;
+ *   active: boolean;
+ * }
+ *
+ * const fetchUsers: Fetcher<User> = async (query) => {
+ *   const response = await fetch(`/api/users?page=${query.page}&pageSize=${query.pageSize}`);
+ *   return response.json();
+ * };
+ *
+ * function UsersTable() {
+ *   return (
+ *     <RowaKitTable
+ *       fetcher={fetchUsers}
+ *       columns={[
+ *         col.text('name', { header: 'Name', sortable: true }),
+ *         col.text('email', { header: 'Email' }),
+ *         col.date('createdAt', { header: 'Created' }),
+ *         col.boolean('active', { header: 'Active' }),
+ *         col.actions([
+ *           { id: 'edit', label: 'Edit', onClick: (user) => editUser(user) },
+ *           { id: 'delete', label: 'Delete', confirm: true, onClick: (user) => deleteUser(user) }
+ *         ])
+ *       ]}
+ *       defaultPageSize={20}
+ *       rowKey="id"
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function RowaKitTable<T>({ fetcher, columns, defaultPageSize, pageSizeOptions, rowKey, className, }: SmartTableProps<T>): react_jsx_runtime.JSX.Element;
+/**
+ * @deprecated Use RowaKitTable instead. SmartTable is kept as an alias for backward compatibility.
+ */
+declare const SmartTable: typeof RowaKitTable;
+
+/**
+ * @rowakit/table
+ *
+ * Opinionated, server-side-first table component for internal/business apps.
+ *
+ * @packageDocumentation
+ */
+
+declare const VERSION = "0.1.0";
+
+export { type ActionDef, type ActionsColumnDef, type BaseColumnDef, type BooleanColumnDef, type ColumnDef, type ColumnKind, type CustomColumnDef, type DateColumnDef, type Fetcher, type FetcherQuery, type FetcherResult, RowaKitTable, SmartTable, type SmartTableProps, type TextColumnDef, VERSION, col };