dinocollab-core 2.2.1 → 2.2.3

package/dist/types/lab/data-surface/index.create.d.ts

@@ -1,16 +1,59 @@
-import { ComponentType, FC } from 'react';
-import { DataSurfaceViewMode } from './types';
-import { IViewGridConfig, IViewGridProps } from './view-grid';
+import { DataSurfaceViewMode, LoadingModeRule } from './types';
+import type { BoxProps } from '@mui/material';
+import type { ComponentType, FC, ReactNode } from 'react';
+import type { TPagination, TDataSurfaceState } from './types';
+import type { IViewGridConfig, IViewGridProps } from './view-grid';
+import type { IViewListConfig, IViewListProps } from './view-list';
+export interface IDataSurfaceSlots {
+    footer?: {
+        status?: string | ((currentStatus: string) => ReactNode);
+        range?: string | ((currentRange: string) => ReactNode);
+    };
+}
 export interface IDataSurfaceProps<T> {
     value?: T[];
-    totalValue?: number;
+    /**
+     * @deprecated No longer used. Use `viewMode` and `loadMode` props directly instead.
+     * Controlled state. When provided, DataSurface becomes fully controlled.
+     */
+    state?: TDataSurfaceState;
+    /**
+     * @deprecated No longer used. Component now uses uncontrolled mode with props.
+     * Called on any state change (viewMode, loadMode, page, pageSize).
+     */
+    onStateChange?: (state: TDataSurfaceState) => void;
     viewMode?: DataSurfaceViewMode;
+    /** Pagination metadata shared by both modes. */
+    pagination?: TPagination;
+    /** True while a page fetch is in flight (shows loading indicator). */
+    loading?: boolean;
+    /**
+     * Called when the component needs a new page of data.
+     * - pagination mode: triggered by user clicking page control
+     * - infiniteScroll mode: triggered automatically when scrolling near the bottom
+     * Supports async operations - return a Promise to indicate loading state.
+     */
+    onPageChange?: (page: number, pageSize: number) => void | Promise<void>;
+    /** Load orchestration mode. @default 'pagination' */
+    loadMode?: LoadingModeRule;
+    sx?: BoxProps['sx'];
+    slots?: IDataSurfaceSlots;
+    /** Enable row selection with checkboxes (List view only). */
+    selectable?: boolean;
+    /** Array of selected row IDs (controlled). */
+    selectedIds?: (string | number)[];
+    /** Callback when selection changes. */
+    onSelectionChange?: (selectedIds: (string | number)[]) => void;
 }
 export interface IDataSurfaceConfig<T> {
     defaultViewMode?: DataSurfaceViewMode;
+    /** Default load mode when not provided via props. @default 'pagination' */
+    defaultLoadMode?: LoadingModeRule;
+    /** Default page size. @default 20 */
+    defaultPageSize?: number;
     enableSingleViewTransition?: boolean;
-    listConfig?: any;
-    ListComponent?: ComponentType<any>;
+    listConfig?: IViewListConfig<T>;
+    ListComponent?: ComponentType<IViewListProps<T>>;
     gridConfig?: IViewGridConfig<T>;
     GridComponent?: ComponentType<IViewGridProps<T>>;
 }

package/dist/types/lab/data-surface/index.d.ts

@@ -1 +1,6 @@
 export * from './types';
+export * from './helpers';
+export * from './index.create';
+export * from './view-list.types';
+export * from './view-grid.types';
+export * from './index.dino';

package/dist/types/lab/data-surface/index.dino.d.ts

@@ -1,7 +1,29 @@
-import createDataSurface from './index.create';
+/// <reference types="react" />
+import { setViewModeToURL, getViewModeFromURL, setPaginationToURL, getPaginationFromURL } from './helpers';
 import createViewGrid from './view-grid';
+import createDataSurface from './index.create';
 export declare class DinoDataSurFace {
     createDataSurface: typeof createDataSurface;
     createViewGrid: typeof createViewGrid;
+    ButtonSwitch: import("react").FC<{
+        value?: "grid" | "list" | undefined;
+        onChange?: ((value: "grid" | "list") => void) | undefined;
+        size?: "sm" | "md" | undefined;
+        className?: string | undefined;
+        onlyIcon?: boolean | undefined;
+        reverse?: boolean | undefined;
+    }>;
+    createButtonSwitch: () => import("react").FC<{
+        value?: "grid" | "list" | undefined;
+        onChange?: ((value: "grid" | "list") => void) | undefined;
+        size?: "sm" | "md" | undefined;
+        className?: string | undefined;
+        onlyIcon?: boolean | undefined;
+        reverse?: boolean | undefined;
+    }>;
+    setViewModeToURL: typeof setViewModeToURL;
+    getViewModeFromURL: typeof getViewModeFromURL;
+    setPaginationToURL: typeof setPaginationToURL;
+    getPaginationFromURL: typeof getPaginationFromURL;
 }
 export declare const dinoDataSurface: DinoDataSurFace;

package/dist/types/lab/data-surface/types.d.ts

@@ -1,5 +1,32 @@
-import { RenderStrategyRule } from "./view-grid.types";
 export type TGetterId<T> = (item: T, index: number) => string | number;
+export type TPagination = {
+    page?: number;
+    pageSize?: number;
+    hasNext?: boolean;
+    hasPrev?: boolean;
+    total?: number;
+};
+/**
+ * Virtualized rendering configuration.
+ * Used by both grid and list views for windowing optimization.
+ */
+export type TVirtualizedConfig = {
+    scrollTop: number;
+    viewportHeight: number;
+    /** Number of extra rows/columns rendered outside the viewport as a buffer. Defaults to `4` (grid) / `6` (table). */
+    overscan?: number;
+    gap?: number;
+};
+/**
+ * Controls how the list is rendered into the DOM.
+ * - `normal`      — all rows are mounted (suitable for small datasets)
+ * - `virtualized` — only visible rows are mounted (optimized for large datasets)
+ */
+export declare const RenderStrategyRule: {
+    readonly normal: "normal";
+    readonly virtualized: "virtualized";
+};
+export type RenderStrategyRule = keyof typeof RenderStrategyRule;
 /**
  * Controls how the list is displayed.
  * - `list` — items are displayed in a single column
@@ -15,13 +42,13 @@ export type DataSurfaceViewMode = keyof typeof DataSurfaceViewMode;
  * - `pagination`    — loading indicator is shown when the user clicks on the pagination controls
  * - `infiniteScroll` — loading indicator is shown when the user scrolls to the end of the list
  */
-export declare const DataSurfaceLoadingType: {
+export declare const LoadingModeRule: {
     readonly pagination: "pagination";
     readonly infiniteScroll: "infiniteScroll";
 };
-export type DataSurfaceLoadingType = keyof typeof DataSurfaceLoadingType;
+export type LoadingModeRule = keyof typeof LoadingModeRule;
 export type TDataSurfaceState = {
     viewMode?: DataSurfaceViewMode;
-    loadingType?: DataSurfaceLoadingType;
+    loadMode?: LoadingModeRule;
     renderStrategy?: RenderStrategyRule;
 };

package/dist/types/lab/data-surface/ui.units.d.ts

@@ -0,0 +1,34 @@
+import type { FC, ReactNode } from 'react';
+import type { BoxProps } from '@mui/material';
+export declare const PanelLoading: FC<BoxProps>;
+export declare const PanelError: FC<{
+    error: string;
+}>;
+export declare const PanelNoData: FC;
+export declare const PanelWaiting: FC;
+export declare const PanelMissingConfig: FC;
+export declare const PanelLoadMore: FC;
+export interface IPanelInfiniteScrollFooterSlots {
+    statusText?: string | ((currentStatus: string) => ReactNode);
+    rangeText?: string | ((currentRange: string) => ReactNode);
+}
+export interface IPanelInfiniteScrollFooterProps {
+    loading?: boolean;
+    hasNext?: boolean;
+    currentCount: number;
+    total?: number;
+    slots?: IPanelInfiniteScrollFooterSlots;
+}
+export declare const PanelInfiniteScrollFooter: FC<IPanelInfiniteScrollFooterProps>;
+export interface IPanelPaginationFooterProps {
+    page: number;
+    pageSize: number;
+    total?: number;
+    hasNext?: boolean;
+    hasPrev?: boolean;
+    loading?: boolean;
+    onPrevPage?: () => void;
+    onNextPage?: () => void;
+    onPageJump?: (page: number) => void;
+}
+export declare const PanelPaginationFooter: FC<IPanelPaginationFooterProps>;

package/dist/types/lab/data-surface/view-grid.d.ts

@@ -1,14 +1,6 @@
-import { ComponentType, FC } from 'react';
-import { TGetterId } from './types';
-import { RenderStrategyRule } from './view-grid.types';
+import type { ComponentType, FC } from 'react';
+import type { TGetterId, LoadingModeRule, TPagination, TVirtualizedConfig, RenderStrategyRule } from './types';
 import type { IViewGridItemProps, TGridSizes } from './view-grid.types';
-export type TVirtualizedConfig = {
-    scrollTop: number;
-    viewportHeight: number;
-    /** Number of extra rows/columns rendered outside the viewport as a buffer. Defaults to `4` (grid) / `6` (table). */
-    overscan?: number;
-    gap?: number;
-};
 export interface IViewGridBase<T> {
     gap?: number;
     sizes?: TGridSizes;
@@ -22,6 +14,8 @@ export interface IViewGridBase<T> {
     renderStrategy?: RenderStrategyRule;
     Component?: ComponentType<IViewGridItemProps<T>>;
     virtualizedConfig?: TVirtualizedConfig;
+    /** Called when user scrolls near the bottom of the list. Use this to trigger pagination or infinity load. */
+    onNearEnd?: () => void;
 }
 export interface IViewGridConfig<T> extends IViewGridBase<T> {
     getterId: TGetterId<T>;
@@ -29,7 +23,15 @@ export interface IViewGridConfig<T> extends IViewGridBase<T> {
 export interface IViewGridProps<T> extends IViewGridBase<T> {
     value: T[];
 }
+export interface IViewGridLoadingProps<T> extends IViewGridBase<T> {
+    value: T[];
+    loadMode: LoadingModeRule;
+    loading?: boolean;
+    pagination?: TPagination;
+    onPageChange?: (page: number, pageSize: number) => void | Promise<void>;
+}
 export declare function createViewGrid<T>(config: IViewGridConfig<T>): FC<IViewGridProps<T>>;
+export declare function createViewGridLoading<T>(GridComponent: ComponentType<IViewGridProps<T>>): FC<IViewGridLoadingProps<T>>;
 export default createViewGrid;
 export declare const viewGridClasses: {
     root: string;

package/dist/types/lab/data-surface/view-grid.types.d.ts

@@ -1,15 +1,5 @@
 export type TGridSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 export type TGridSizes = Partial<Record<TGridSize, number>>;
-/**
- * Controls how the list is rendered into the DOM.
- * - `normal`      — all rows are mounted (suitable for small datasets)
- * - `virtualized` — only visible rows are mounted (optimized for large datasets)
- */
-export declare const RenderStrategyRule: {
-    readonly normal: "normal";
-    readonly virtualized: "virtualized";
-};
-export type RenderStrategyRule = keyof typeof RenderStrategyRule;
 /**
  * Props received by the custom render function for each card in Grid view.
  * @template T - The shape of a single data row object.

package/dist/types/lab/data-surface/view-grid.units.d.ts

@@ -1,8 +1,8 @@
-import { IViewGridItemProps, TGridSizes } from './view-grid.types';
-import { FC } from 'react';
+import type { FC } from 'react';
+import type { IViewGridItemProps, TGridSizes } from './view-grid.types';
 export declare const DEFAULT_GRID_GAP_PX = 8;
 export declare const getMaxGridGap: (...gap: (number | undefined)[]) => number;
-export declare const DEFAULT_GRID_ITEM_MAX_HEIGHT = 200;
+export declare const DEFAULT_GRID_ITEM_MAX_HEIGHT = 120;
 export declare const getMaxGridItemHeight: (...height: (number | undefined)[]) => number;
 export declare const DEFAULT_GRID_ITEM_SIZES: TGridSizes;
 export declare const getGridItemSizes: (sizes?: TGridSizes) => TGridSizes;

package/dist/types/lab/data-surface/view-list.d.ts

@@ -0,0 +1,52 @@
+import { ListDensity } from './view-list.types';
+import type { ComponentType, FC } from 'react';
+import type { TListColumns } from './view-list.types';
+import type { TGetterId, LoadingModeRule, TPagination, TVirtualizedConfig, RenderStrategyRule } from './types';
+export interface IViewListBase<T> {
+    columns?: TListColumns<T>;
+    density?: ListDensity;
+    /**
+     * Controls how the list is rendered into the DOM.
+     * - `normal`      — all rows are mounted (suitable for small datasets)
+     * - `virtualized` — only visible rows are mounted (optimized for large datasets)
+     * @default 'normal'
+     */
+    renderStrategy?: RenderStrategyRule;
+    virtualizedConfig?: TVirtualizedConfig;
+    /** Called when user scrolls near the bottom of the list. Use this to trigger pagination or infinity load. */
+    onNearEnd?: () => void;
+    /** Enable row selection with checkboxes. */
+    selectable?: boolean;
+    /** Array of selected row IDs (controlled). */
+    selectedIds?: (string | number)[];
+    /** Callback when selection changes. */
+    onSelectionChange?: (selectedIds: (string | number)[]) => void;
+}
+export interface IViewListConfig<T> extends IViewListBase<T> {
+    getterId: TGetterId<T>;
+}
+export interface IViewListProps<T> extends IViewListBase<T> {
+    value: T[];
+}
+export interface IViewListLoadingProps<T> extends IViewListBase<T> {
+    value: T[];
+    loadMode: LoadingModeRule;
+    loading?: boolean;
+    pagination?: TPagination;
+    onPageChange?: (page: number, pageSize: number) => void | Promise<void>;
+}
+export declare function createViewList<T>(config: IViewListConfig<T>): FC<IViewListProps<T>>;
+export declare function createViewListLoading<T>(ListComponent: ComponentType<IViewListProps<T>>): FC<IViewListLoadingProps<T>>;
+export default createViewList;
+export declare const viewListClasses: {
+    root: string;
+    virtualized: string;
+    scrollContainer: string;
+    table: string;
+    tableHeader: string;
+    tableHeaderCell: string;
+    tableBodyCell: string;
+    tableSpacerRow: string;
+    tableSpacerCell: string;
+    tableCellContent: string;
+};

package/dist/types/lab/data-surface/view-list.types.d.ts

@@ -0,0 +1,64 @@
+import type { ReactNode } from 'react';
+/**
+ * Props received by the custom render function for each row in List view.
+ * @template T - The shape of a single data row object.
+ */
+export interface IViewListItemProps<T> {
+    /** The data object for this list row. */
+    value: T;
+    /** Zero-based position of this item in the data array. */
+    index: number;
+    /** Whether this row is currently selected. */
+    selected?: boolean;
+}
+/** Horizontal alignment for list cell content. */
+export type TListAlign = 'left' | 'right' | 'center';
+/**
+ * Context passed to a column's render callback.
+ * @template T - The shape of a single data row object.
+ */
+export interface IListCellParams<T> {
+    /** Resolved cell value (after valueGetter if provided). */
+    value: any;
+    /** The full row object. */
+    row: T;
+    /** Zero-based row index. */
+    index: number;
+    /** The column field key this cell belongs to. */
+    field: keyof T;
+}
+/**
+ * Definition of a single column in List view.
+ * @template T - The shape of a single data row object.
+ */
+export interface TListColumn<T> {
+    /** Key of the row object this column maps to. */
+    field: keyof T;
+    /** Column header label shown in the header. */
+    label?: string;
+    /** Explicit column width. Accepts px number or CSS string (e.g. '120px', '20%'). */
+    width?: number | string;
+    /** Minimum column width in pixels. */
+    minWidth?: number;
+    /** Maximum column width in pixels. */
+    maxWidth?: number;
+    /** Flex grow ratio used when no explicit width is set. */
+    flex?: number;
+    /** Horizontal alignment of the cell content. */
+    align?: TListAlign;
+    /** Custom cell render function - receives CellParams, returns ReactNode. */
+    renderCell?: (params: IListCellParams<T>) => ReactNode;
+    /** Derives a value from the row before it is passed to the render step. */
+    valueGetter?: (row: T, index: number) => any;
+}
+export type TListColumns<T> = Partial<Record<keyof T, Omit<TListColumn<T>, 'field'>>>;
+/**
+ * Row density preset for List view.
+ * Controls the row height and cell padding.
+ */
+export declare const ListDensity: {
+    readonly compact: "compact";
+    readonly standard: "standard";
+    readonly comfortable: "comfortable";
+};
+export type ListDensity = keyof typeof ListDensity;

package/dist/types/lab/data-surface/view-list.units.d.ts

@@ -0,0 +1,23 @@
+import { ListDensity } from './view-list.types';
+import type { TGetterId } from './types';
+export declare const LIST_HEADER_HEIGHT = 48;
+export declare const LIST_ROW_HEIGHT_BY_DENSITY: Record<ListDensity, number>;
+export declare const LIST_CELL_PADDING_BY_DENSITY: Record<ListDensity, string>;
+/**
+ * Custom hook to manage list row selection logic.
+ * Handles select all, individual row selection, and indeterminate state.
+ *
+ * @param value - The array of data items
+ * @param getterId - Function to extract unique ID from each row
+ * @param selectable - Whether selection is enabled
+ * @param selectedIds - Controlled array of selected row IDs
+ * @param onSelectionChange - Callback when selection changes
+ * @returns Selection state and handlers
+ */
+export declare function useListSelection<T>(value: T[], getterId: TGetterId<T>, selectable: boolean, selectedIds?: (string | number)[], onSelectionChange?: (selectedIds: (string | number)[]) => void): {
+    selectedIds: (string | number)[];
+    isAllSelected: boolean;
+    isSomeSelected: boolean;
+    handleToggleAll: () => void;
+    handleToggleRow: (rowId: string | number) => void;
+};

package/dist/types/lab/data-surface/view-switch-transition.units.d.ts

@@ -1,4 +1,4 @@
-import { CSSProperties, FC, ReactElement } from 'react';
+import type { CSSProperties, FC, ReactElement } from 'react';
 export declare const viewSwitchTransitionClasses: {
     root: string;
     viewWrapper: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dinocollab-core",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "Dinocollab core - libraries for building collaborative applications with React 18",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -32,6 +32,9 @@
       "filter-bar": [
         "./dist/types/filter-bar/index.d.ts"
       ],
+      "lab/data-surface": [
+        "./dist/types/lab/data-surface/index.d.ts"
+      ],
       "data-view": [
         "./dist/types/data-view/index.d.ts"
       ],
@@ -81,6 +84,10 @@
       "import": "./dist/filter-bar/index.js",
       "types": "./dist/types/filter-bar/index.d.ts"
     },
+    "./lab/data-surface": {
+      "import": "./dist/lab/data-surface/index.js",
+      "types": "./dist/types/lab/data-surface/index.d.ts"
+    },
     "./data-view": {
       "import": "./dist/data-view/index.js",
       "types": "./dist/types/data-view/index.d.ts"

package/dist/types/lab/data-viewer/index.d.ts

@@ -1 +0,0 @@
-export {};