@loykin/gridkit 0.0.1-beta.1

package/dist/index.d.cts

@@ -0,0 +1,266 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Row, ColumnDef, SortingState, ColumnFiltersState, Table, VisibilityState, ColumnPinningState, ColumnSizingState } from '@tanstack/react-table';
+import React$1, { ReactNode } from 'react';
+
+interface Transaction<T> {
+    add?: T[];
+    update?: Array<{
+        id: string;
+        data: Partial<T>;
+    }>;
+    remove?: string[];
+}
+interface DataStore<T> {
+    get(id: string): T | undefined;
+    /** Returns a stable array reference — same reference until the next transaction */
+    getSnapshot(): T[];
+    /** Monotonically increasing integer — increments on every transaction */
+    getVersion(): number;
+    applyTransaction(tx: Transaction<T>): void;
+    /** useSyncExternalStore compatible subscribe */
+    subscribe(listener: () => void): () => void;
+}
+declare function createDataStore<T>(getRowId: (item: T, index: number) => string): DataStore<T>;
+
+type DataGridColumnDef<T extends object> = ColumnDef<T, unknown>;
+type ColumnSizingMode = 'auto' | 'flex' | 'fixed';
+/**
+ * Table width handling strategy:
+ * - 'spacer': Each column independent px + spacer cell fills remaining space (default)
+ * - 'fill-last': Last visible column stretches to fill remaining space
+ * - 'independent': Each column independent px, no fill — right gap when columns are narrow
+ */
+type TableWidthMode = 'spacer' | 'fill-last' | 'independent';
+interface CheckboxConfig<T extends object> {
+    getRowId: (row: T) => string;
+    selectedIds: Set<string>;
+    onSelectAll: (rows: Row<T>[], checked: boolean) => void;
+    onSelectOne: (rowId: string, checked: boolean) => void;
+}
+/**
+ * Rendering props owned by DataGridTableView.
+ * DataGridBaseProps and DataGridTableViewProps both extend this
+ * so these are declared exactly once.
+ */
+/**
+ * Slot-based class injection for DataGrid elements.
+ * Each key targets a specific part of the table structure.
+ * User-supplied classes are merged after library defaults via cn(),
+ * so Tailwind classes here will take precedence over library defaults.
+ */
+interface DataGridClassNames {
+    /** Outermost wrapper div (border, rounded-md) */
+    container?: string;
+    /** Header panel div (bg-muted, overflow:hidden) */
+    header?: string;
+    /** Individual header cell div */
+    headerCell?: string;
+    /** Body row div */
+    row?: string;
+    /** Body cell div */
+    cell?: string;
+}
+interface TableViewConfig<T extends object> {
+    isLoading?: boolean;
+    emptyMessage?: string;
+    /**
+     * No data일 때 body 영역에 표시할 커스텀 UI.
+     * 제공 시 emptyMessage보다 우선 적용됨.
+     */
+    emptyContent?: ReactNode;
+    /** 테이블 헤더 표시 여부. 기본값 true. */
+    showHeader?: boolean;
+    onRowClick?: (row: T) => void;
+    rowCursor?: boolean;
+    enableColumnResizing?: boolean;
+    /** Show per-column filter row below the header (AG Grid style) */
+    enableColumnFilters?: boolean;
+    /**
+     * Controls how column filters are displayed when enableColumnFilters=true.
+     * - 'row' (default): dedicated filter row below the header
+     * - 'icon': filter icon inside each header cell that opens a popover
+     */
+    filterDisplay?: 'row' | 'icon';
+    tableHeight?: string | number | 'auto';
+    /** Show vertical dividers between columns */
+    bordered?: boolean;
+    /**
+     * Table width handling strategy:
+     * - 'spacer': Each column independent px + spacer cell fills remaining space (default)
+     * - 'fill-last': Last visible column stretches to fill remaining space
+     * - 'independent': Each column independent px, no fill — right gap when columns are narrow
+     */
+    tableWidthMode?: TableWidthMode;
+    /**
+     * Fixed row height in px. Sets both the actual CSS min-height of each row
+     * and the virtualizer's estimateSize so they stay in sync. Default: 33.
+     * Rows with meta.wrap=true can still grow beyond this height — measureElement
+     * will track the actual size for accurate virtual positioning.
+     */
+    rowHeight?: number;
+    /**
+     * Override the virtualizer's estimated row height independently of rowHeight.
+     * Only needed for variable-height rows where you want a different estimate.
+     */
+    estimateRowHeight?: number;
+    /** Rows to render outside the visible area (virtualizer overscan, default: 10) */
+    overscan?: number;
+    /** Slot-based class injection for individual table elements */
+    classNames?: DataGridClassNames;
+}
+interface DataGridBaseProps<T extends object> extends TableViewConfig<T> {
+    data?: T[];
+    /**
+     * Map-based external store for real-time / high-frequency updates.
+     * Use with useDataStore() and table.applyTransaction().
+     * Mutually exclusive with the `data` prop — set one or the other.
+     */
+    dataStore?: DataStore<T>;
+    columns: DataGridColumnDef<T>[];
+    error?: Error | null;
+    enableSorting?: boolean;
+    initialSorting?: SortingState;
+    onSortingChange?: (sorting: SortingState) => void;
+    manualSorting?: boolean;
+    columnFilters?: ColumnFiltersState;
+    globalFilter?: string;
+    onGlobalFilterChange?: (value: string) => void;
+    searchableColumns?: string[];
+    leftFilters?: (table: Table<T>) => React.ReactNode;
+    rightFilters?: (table: Table<T>) => React.ReactNode;
+    visibilityState?: VisibilityState;
+    /** Initial column pinning — { left: ['id', ...], right: ['id', ...] } */
+    initialPinning?: ColumnPinningState;
+    columnSizingMode?: ColumnSizingMode;
+    /** Enable row expansion (requires subRows in data or getSubRows) */
+    enableExpanding?: boolean;
+    /**
+     * Extract sub-rows from a row for tree display.
+     * If omitted, TanStack Table looks for a 'subRows' key on each data item.
+     */
+    getSubRows?: (originalRow: T, index: number) => T[] | undefined;
+    checkboxConfig?: CheckboxConfig<T>;
+    tableKey?: string;
+    /**
+     * Sync table state (pagination, search) to the in-memory Zustand store so it
+     * survives re-renders within the same session. Requires tableKey to be set.
+     * Note: in-memory only — does not persist across page reloads.
+     */
+    syncState?: boolean;
+    onTableReady?: (table: Table<T>) => void;
+    onColumnSizingChange?: (sizing: ColumnSizingState) => void;
+}
+interface DataGridProps<T extends object> extends DataGridBaseProps<T> {
+    enablePagination?: boolean;
+    paginationConfig?: {
+        pageSize?: number;
+        initialPageIndex?: number;
+    };
+    pageSizes?: number[];
+    /** Server-side total row count for manual pagination */
+    totalCount?: number;
+    onPageChange?: (pageIndex: number, pageSize: number) => void;
+}
+interface DataGridDragProps<T extends object> extends DataGridBaseProps<T> {
+    /** Required: stable unique id per data item — used to track row identity across reorders */
+    getRowId: (originalRow: T, index: number) => string;
+    /** Called with the full reordered data array after each drag */
+    onRowReorder: (newData: T[]) => void;
+}
+interface DataGridInfinityProps<T extends object> extends DataGridBaseProps<T> {
+    hasNextPage?: boolean;
+    isFetchingNextPage?: boolean;
+    fetchNextPage?: () => void;
+    /** IntersectionObserver rootMargin to trigger next page load */
+    rootMargin?: string;
+}
+
+interface DataGridPropsWithRef<T extends object> extends DataGridProps<T> {
+    /** Ref populated with the TanStack Table instance after first render */
+    tableRef?: React.RefObject<Table<T> | null>;
+}
+declare function DataGrid<T extends object>(props: DataGridPropsWithRef<T>): react_jsx_runtime.JSX.Element;
+
+declare function DataGridInfinity<T extends object>(props: DataGridInfinityProps<T>): react_jsx_runtime.JSX.Element;
+
+declare function DataGridDrag<T extends object>(props: DataGridDragProps<T>): react_jsx_runtime.JSX.Element;
+
+interface Props$1<T extends object> {
+    table: Table<T>;
+}
+declare function ColumnVisibilityDropdown<T extends object>({ table }: Props$1<T>): react_jsx_runtime.JSX.Element;
+
+interface Props<T extends object> {
+    table: Table<T>;
+    placeholder?: string;
+    className?: string;
+}
+declare function GlobalSearch<T extends object>({ table, placeholder, className, }: Props<T>): react_jsx_runtime.JSX.Element;
+
+interface SelectFilterProps<T extends object> {
+    table: Table<T>;
+    columnId: string;
+    label: string;
+}
+declare function SelectFilter<T extends object>({ table, columnId, label }: SelectFilterProps<T>): react_jsx_runtime.JSX.Element | null;
+interface MultiSelectFilterProps<T extends object> {
+    table: Table<T>;
+    columnId: string;
+    label: string;
+}
+declare function MultiSelectFilter<T extends object>({ table, columnId, label, }: MultiSelectFilterProps<T>): react_jsx_runtime.JSX.Element | null;
+
+interface TreeCellProps {
+    row: Row<any>;
+    /** Indent per depth level in px (default: 16) */
+    indentSize?: number;
+    children: React$1.ReactNode;
+}
+/**
+ * Wraps cell content with a depth-aware indent and expand/collapse toggle.
+ * Drop this into whichever column should act as the tree "name" column.
+ *
+ * Usage:
+ *   cell: ({ row }) => (
+ *     <TreeCell row={row} indentSize={20}>
+ *       <Icon /> <span>{row.original.name}</span>
+ *     </TreeCell>
+ *   )
+ */
+declare function TreeCell({ row, indentSize, children }: TreeCellProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Drag handle cell — place in whichever column should act as the grab handle.
+ * Reads listeners/attributes from RowDragContext set by SortableRow.
+ * Only works inside DataGridDrag.
+ *
+ * Usage:
+ *   { id: 'drag', size: 36, enableResizing: false,
+ *     cell: () => <DragHandleCell /> }
+ */
+declare function DragHandleCell(): react_jsx_runtime.JSX.Element;
+
+interface UseDataStoreOptions<T> {
+    getRowId: (item: T, index: number) => string;
+}
+/**
+ * Creates and memoizes a DataStore instance for use with <DataGrid dataStore={store} />.
+ *
+ * The store is stable for the lifetime of the component — pass a stable `getRowId`
+ * callback (e.g. defined outside render or wrapped in useCallback).
+ *
+ * @example
+ * const store = useDataStore<Pod>({ getRowId: p => p.name })
+ *
+ * useEffect(() => {
+ *   const watcher = watchPods(namespace, {
+ *     onAdded:    pod  => store.applyTransaction({ add: [pod] }),
+ *     onModified: pod  => store.applyTransaction({ update: [{ id: pod.name, data: pod }] }),
+ *     onDeleted:  name => store.applyTransaction({ remove: [name] }),
+ *   })
+ *   return () => watcher.stop()
+ * }, [namespace])
+ */
+declare function useDataStore<T>(options: UseDataStoreOptions<T>): DataStore<T>;
+
+export { type CheckboxConfig, type ColumnSizingMode, ColumnVisibilityDropdown, DataGrid, type DataGridBaseProps, type DataGridClassNames, type DataGridColumnDef, DataGridDrag, type DataGridDragProps, DataGridInfinity, type DataGridInfinityProps, type DataGridProps, type DataStore, DragHandleCell, GlobalSearch, MultiSelectFilter, SelectFilter, type TableViewConfig, type TableWidthMode, type Transaction, TreeCell, createDataStore, useDataStore };

package/dist/index.d.ts

@@ -0,0 +1,266 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Row, ColumnDef, SortingState, ColumnFiltersState, Table, VisibilityState, ColumnPinningState, ColumnSizingState } from '@tanstack/react-table';
+import React$1, { ReactNode } from 'react';
+
+interface Transaction<T> {
+    add?: T[];
+    update?: Array<{
+        id: string;
+        data: Partial<T>;
+    }>;
+    remove?: string[];
+}
+interface DataStore<T> {
+    get(id: string): T | undefined;
+    /** Returns a stable array reference — same reference until the next transaction */
+    getSnapshot(): T[];
+    /** Monotonically increasing integer — increments on every transaction */
+    getVersion(): number;
+    applyTransaction(tx: Transaction<T>): void;
+    /** useSyncExternalStore compatible subscribe */
+    subscribe(listener: () => void): () => void;
+}
+declare function createDataStore<T>(getRowId: (item: T, index: number) => string): DataStore<T>;
+
+type DataGridColumnDef<T extends object> = ColumnDef<T, unknown>;
+type ColumnSizingMode = 'auto' | 'flex' | 'fixed';
+/**
+ * Table width handling strategy:
+ * - 'spacer': Each column independent px + spacer cell fills remaining space (default)
+ * - 'fill-last': Last visible column stretches to fill remaining space
+ * - 'independent': Each column independent px, no fill — right gap when columns are narrow
+ */
+type TableWidthMode = 'spacer' | 'fill-last' | 'independent';
+interface CheckboxConfig<T extends object> {
+    getRowId: (row: T) => string;
+    selectedIds: Set<string>;
+    onSelectAll: (rows: Row<T>[], checked: boolean) => void;
+    onSelectOne: (rowId: string, checked: boolean) => void;
+}
+/**
+ * Rendering props owned by DataGridTableView.
+ * DataGridBaseProps and DataGridTableViewProps both extend this
+ * so these are declared exactly once.
+ */
+/**
+ * Slot-based class injection for DataGrid elements.
+ * Each key targets a specific part of the table structure.
+ * User-supplied classes are merged after library defaults via cn(),
+ * so Tailwind classes here will take precedence over library defaults.
+ */
+interface DataGridClassNames {
+    /** Outermost wrapper div (border, rounded-md) */
+    container?: string;
+    /** Header panel div (bg-muted, overflow:hidden) */
+    header?: string;
+    /** Individual header cell div */
+    headerCell?: string;
+    /** Body row div */
+    row?: string;
+    /** Body cell div */
+    cell?: string;
+}
+interface TableViewConfig<T extends object> {
+    isLoading?: boolean;
+    emptyMessage?: string;
+    /**
+     * No data일 때 body 영역에 표시할 커스텀 UI.
+     * 제공 시 emptyMessage보다 우선 적용됨.
+     */
+    emptyContent?: ReactNode;
+    /** 테이블 헤더 표시 여부. 기본값 true. */
+    showHeader?: boolean;
+    onRowClick?: (row: T) => void;
+    rowCursor?: boolean;
+    enableColumnResizing?: boolean;
+    /** Show per-column filter row below the header (AG Grid style) */
+    enableColumnFilters?: boolean;
+    /**
+     * Controls how column filters are displayed when enableColumnFilters=true.
+     * - 'row' (default): dedicated filter row below the header
+     * - 'icon': filter icon inside each header cell that opens a popover
+     */
+    filterDisplay?: 'row' | 'icon';
+    tableHeight?: string | number | 'auto';
+    /** Show vertical dividers between columns */
+    bordered?: boolean;
+    /**
+     * Table width handling strategy:
+     * - 'spacer': Each column independent px + spacer cell fills remaining space (default)
+     * - 'fill-last': Last visible column stretches to fill remaining space
+     * - 'independent': Each column independent px, no fill — right gap when columns are narrow
+     */
+    tableWidthMode?: TableWidthMode;
+    /**
+     * Fixed row height in px. Sets both the actual CSS min-height of each row
+     * and the virtualizer's estimateSize so they stay in sync. Default: 33.
+     * Rows with meta.wrap=true can still grow beyond this height — measureElement
+     * will track the actual size for accurate virtual positioning.
+     */
+    rowHeight?: number;
+    /**
+     * Override the virtualizer's estimated row height independently of rowHeight.
+     * Only needed for variable-height rows where you want a different estimate.
+     */
+    estimateRowHeight?: number;
+    /** Rows to render outside the visible area (virtualizer overscan, default: 10) */
+    overscan?: number;
+    /** Slot-based class injection for individual table elements */
+    classNames?: DataGridClassNames;
+}
+interface DataGridBaseProps<T extends object> extends TableViewConfig<T> {
+    data?: T[];
+    /**
+     * Map-based external store for real-time / high-frequency updates.
+     * Use with useDataStore() and table.applyTransaction().
+     * Mutually exclusive with the `data` prop — set one or the other.
+     */
+    dataStore?: DataStore<T>;
+    columns: DataGridColumnDef<T>[];
+    error?: Error | null;
+    enableSorting?: boolean;
+    initialSorting?: SortingState;
+    onSortingChange?: (sorting: SortingState) => void;
+    manualSorting?: boolean;
+    columnFilters?: ColumnFiltersState;
+    globalFilter?: string;
+    onGlobalFilterChange?: (value: string) => void;
+    searchableColumns?: string[];
+    leftFilters?: (table: Table<T>) => React.ReactNode;
+    rightFilters?: (table: Table<T>) => React.ReactNode;
+    visibilityState?: VisibilityState;
+    /** Initial column pinning — { left: ['id', ...], right: ['id', ...] } */
+    initialPinning?: ColumnPinningState;
+    columnSizingMode?: ColumnSizingMode;
+    /** Enable row expansion (requires subRows in data or getSubRows) */
+    enableExpanding?: boolean;
+    /**
+     * Extract sub-rows from a row for tree display.
+     * If omitted, TanStack Table looks for a 'subRows' key on each data item.
+     */
+    getSubRows?: (originalRow: T, index: number) => T[] | undefined;
+    checkboxConfig?: CheckboxConfig<T>;
+    tableKey?: string;
+    /**
+     * Sync table state (pagination, search) to the in-memory Zustand store so it
+     * survives re-renders within the same session. Requires tableKey to be set.
+     * Note: in-memory only — does not persist across page reloads.
+     */
+    syncState?: boolean;
+    onTableReady?: (table: Table<T>) => void;
+    onColumnSizingChange?: (sizing: ColumnSizingState) => void;
+}
+interface DataGridProps<T extends object> extends DataGridBaseProps<T> {
+    enablePagination?: boolean;
+    paginationConfig?: {
+        pageSize?: number;
+        initialPageIndex?: number;
+    };
+    pageSizes?: number[];
+    /** Server-side total row count for manual pagination */
+    totalCount?: number;
+    onPageChange?: (pageIndex: number, pageSize: number) => void;
+}
+interface DataGridDragProps<T extends object> extends DataGridBaseProps<T> {
+    /** Required: stable unique id per data item — used to track row identity across reorders */
+    getRowId: (originalRow: T, index: number) => string;
+    /** Called with the full reordered data array after each drag */
+    onRowReorder: (newData: T[]) => void;
+}
+interface DataGridInfinityProps<T extends object> extends DataGridBaseProps<T> {
+    hasNextPage?: boolean;
+    isFetchingNextPage?: boolean;
+    fetchNextPage?: () => void;
+    /** IntersectionObserver rootMargin to trigger next page load */
+    rootMargin?: string;
+}
+
+interface DataGridPropsWithRef<T extends object> extends DataGridProps<T> {
+    /** Ref populated with the TanStack Table instance after first render */
+    tableRef?: React.RefObject<Table<T> | null>;
+}
+declare function DataGrid<T extends object>(props: DataGridPropsWithRef<T>): react_jsx_runtime.JSX.Element;
+
+declare function DataGridInfinity<T extends object>(props: DataGridInfinityProps<T>): react_jsx_runtime.JSX.Element;
+
+declare function DataGridDrag<T extends object>(props: DataGridDragProps<T>): react_jsx_runtime.JSX.Element;
+
+interface Props$1<T extends object> {
+    table: Table<T>;
+}
+declare function ColumnVisibilityDropdown<T extends object>({ table }: Props$1<T>): react_jsx_runtime.JSX.Element;
+
+interface Props<T extends object> {
+    table: Table<T>;
+    placeholder?: string;
+    className?: string;
+}
+declare function GlobalSearch<T extends object>({ table, placeholder, className, }: Props<T>): react_jsx_runtime.JSX.Element;
+
+interface SelectFilterProps<T extends object> {
+    table: Table<T>;
+    columnId: string;
+    label: string;
+}
+declare function SelectFilter<T extends object>({ table, columnId, label }: SelectFilterProps<T>): react_jsx_runtime.JSX.Element | null;
+interface MultiSelectFilterProps<T extends object> {
+    table: Table<T>;
+    columnId: string;
+    label: string;
+}
+declare function MultiSelectFilter<T extends object>({ table, columnId, label, }: MultiSelectFilterProps<T>): react_jsx_runtime.JSX.Element | null;
+
+interface TreeCellProps {
+    row: Row<any>;
+    /** Indent per depth level in px (default: 16) */
+    indentSize?: number;
+    children: React$1.ReactNode;
+}
+/**
+ * Wraps cell content with a depth-aware indent and expand/collapse toggle.
+ * Drop this into whichever column should act as the tree "name" column.
+ *
+ * Usage:
+ *   cell: ({ row }) => (
+ *     <TreeCell row={row} indentSize={20}>
+ *       <Icon /> <span>{row.original.name}</span>
+ *     </TreeCell>
+ *   )
+ */
+declare function TreeCell({ row, indentSize, children }: TreeCellProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Drag handle cell — place in whichever column should act as the grab handle.
+ * Reads listeners/attributes from RowDragContext set by SortableRow.
+ * Only works inside DataGridDrag.
+ *
+ * Usage:
+ *   { id: 'drag', size: 36, enableResizing: false,
+ *     cell: () => <DragHandleCell /> }
+ */
+declare function DragHandleCell(): react_jsx_runtime.JSX.Element;
+
+interface UseDataStoreOptions<T> {
+    getRowId: (item: T, index: number) => string;
+}
+/**
+ * Creates and memoizes a DataStore instance for use with <DataGrid dataStore={store} />.
+ *
+ * The store is stable for the lifetime of the component — pass a stable `getRowId`
+ * callback (e.g. defined outside render or wrapped in useCallback).
+ *
+ * @example
+ * const store = useDataStore<Pod>({ getRowId: p => p.name })
+ *
+ * useEffect(() => {
+ *   const watcher = watchPods(namespace, {
+ *     onAdded:    pod  => store.applyTransaction({ add: [pod] }),
+ *     onModified: pod  => store.applyTransaction({ update: [{ id: pod.name, data: pod }] }),
+ *     onDeleted:  name => store.applyTransaction({ remove: [name] }),
+ *   })
+ *   return () => watcher.stop()
+ * }, [namespace])
+ */
+declare function useDataStore<T>(options: UseDataStoreOptions<T>): DataStore<T>;
+
+export { type CheckboxConfig, type ColumnSizingMode, ColumnVisibilityDropdown, DataGrid, type DataGridBaseProps, type DataGridClassNames, type DataGridColumnDef, DataGridDrag, type DataGridDragProps, DataGridInfinity, type DataGridInfinityProps, type DataGridProps, type DataStore, DragHandleCell, GlobalSearch, MultiSelectFilter, SelectFilter, type TableViewConfig, type TableWidthMode, type Transaction, TreeCell, createDataStore, useDataStore };