@cerberus-design/data-grid 0.25.3

package/dist/types.d.cts

@@ -0,0 +1,198 @@
+import { PageDetails, EnforceNoProperties, PaginationRootProps } from '@cerberus-design/react';
+import { Setter, Accessor } from '@cerberus-design/signals';
+import { ReactNode } from 'react';
+import { RowSize } from './const';
+export interface GridOptions<TData> {
+    /**
+     * The full Array of data you want the grid to render.
+     */
+    data: TData[];
+    /**
+     * A list of Defined Columns created using the column helper.
+     */
+    columns: ColumnDef<TData>[];
+    /**
+     * Initial options for feature-related settings.
+     */
+    initialState?: {
+        pagination?: boolean | PaginationOptions;
+    };
+    /**
+     * Called when a user clicks on a pagination page trigger.
+     */
+    onPageChange?: (details: PageDetails) => void;
+    /**
+     * Content to display above the Data Grid and within the Grid context.
+     */
+    toolbar?: ReactNode;
+    /**
+     * Content to display below the Data Grid and within the Grid context.
+     */
+    footer?: ReactNode;
+    /**
+     * The visual spacing of cells within a row. Can be a predefined size or any
+     * valid CSS sizing value.
+     *
+     * **default**: 'md'.
+     */
+    rowSize?: RowSizeOptions;
+}
+export type ColumnDef<TData, TKey extends keyof TData = keyof TData> = {
+    id: string;
+    /**
+     * The label or custom compoent to display.
+     */
+    header: string | ((props: {
+        colId: string;
+    }) => ReactNode);
+    /**
+     * A helper to access and manage the preferred value of the cell.
+     */
+    accessor: DisplayColAccessor | AccessorAccessor<TData, TKey> | AccessorFn<TData>;
+    /**
+     * Strictly define the cell width. Expects a pixel-based number.
+     * @default 150px
+     */
+    minWidth?: number;
+    /**
+     * Strictly define the cell width. Expects a pixel-based number. If the width
+     * provided is smaller than what is required for features, the minimum width
+     * of 100px will be used instead.
+     * @default 150px
+     */
+    width?: number;
+    features?: ColumnFeatures<TData, TKey>;
+    /**
+     * The cell renderer. Provides access to the accessor value and row data. This
+     * is used to provide custom components for the cell content.
+     *
+     * If no content is provided a string will be rendered.
+     */
+    cell?: ColCell<TData>;
+};
+export type PaginationOptions = {
+    /**
+     * The total number of rows that exist. This is useful if you choose to use
+     * server-side pagination design.
+     */
+    count?: PaginationRootProps['count'];
+    /**
+     * The default page index to start on.
+     */
+    defaultPage?: PaginationRootProps['defaultPage'];
+    /**
+     * The default page size to start with. **Must be included in customRange if
+     * using any value other than 25, 50, or 100**.
+     *
+     * default: 0
+     */
+    pageSize?: PaginationRootProps['pageSize'];
+    /**
+     * A custom range of page sizes to display in the page size dropdown.
+     */
+    customRange?: number[];
+};
+export type AccessorOptions<TData, TKey extends keyof TData> = {
+    id?: string;
+    header: string | ((props: {
+        colId: string;
+    }) => ReactNode);
+    features?: ColumnFeatures<TData, TKey>;
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    cell?: ColCell<TData>;
+};
+export type DisplayOptions<TData, TKey extends keyof TData> = {
+    id: string;
+    header: string | ((props: {
+        colId: string;
+    }) => ReactNode);
+    width?: number;
+    features?: {
+        pinning?: ColumnFeatures<TData, TKey>['pinning'];
+    };
+    cell: ColCell<TData>;
+};
+export type InternalColumn<TData> = {
+    id: string;
+    pinned: Accessor<PinnedState>;
+    isFlex: Accessor<boolean>;
+    isVisible: Accessor<boolean>;
+    width: Accessor<number>;
+    pinnable: boolean;
+    sortable: boolean;
+    filterable: boolean;
+    getValue: ColumnDef<TData>['accessor'];
+    original: ColumnDef<TData>;
+    setFlex: Setter<boolean>;
+    setColWidth: Setter<number>;
+    setPinned: Setter<PinnedState>;
+};
+export type SortState = {
+    id: string;
+    desc: boolean;
+};
+export interface GridStore<TData> {
+    columns: Accessor<InternalColumn<TData>[]>;
+    rows: Accessor<TData[]>;
+    globalFilter: Accessor<string>;
+    sorting: Accessor<SortState[]>;
+    pageIndex: Accessor<number>;
+    pageSize: Accessor<number>;
+    pageRange: Accessor<number[]>;
+    pageCount: Accessor<number>;
+    currentPageRange: Accessor<{
+        start: number;
+        end: number;
+    }>;
+    isServerPaginated: Accessor<boolean>;
+    rootCssVars: Accessor<Record<string, string>>;
+    rowCount: Accessor<number>;
+    rowSize: Accessor<number>;
+    totalWidth: Accessor<number>;
+    visibleRows: Accessor<TData[]>;
+    resizeColumn: (colId: string, delta: number) => void;
+    setContainerWidth: (val: number) => void;
+    setPage: (details: PageDetails) => void;
+    setPageSize: (size: number) => void;
+    setGlobalFilter: (val: string) => void;
+    setSort: (colId: string, direction: SortDirection, multi?: boolean) => void;
+    togglePinned: (colId: string, state: PinnedState) => void;
+    toggleSort: (colId: string, multi?: boolean) => void;
+    updateData: (newData: TData[]) => void;
+}
+export type RowSizeOptions = RowSize | number;
+export type ColumnFeatures<TData, TKey extends keyof TData> = {
+    /**
+     * Allow the column to be sorted and the rules to use.
+     */
+    sort?: (boolean & EnforceNoProperties<SortOptions<TData, TKey>>) | SortOptions<TData, TKey>;
+    /**
+     * Allow the column to be filtered and the rules to use.
+     */
+    filter?: boolean | {
+        operator?: 'contains' | 'equals' | 'startsWith';
+    };
+    /**
+     * Show pinning options in the column menu
+     */
+    pinning?: (boolean & EnforceNoProperties<PinnedOptions>) | PinnedOptions;
+};
+export type PinnedOptions = {
+    defaultPosition?: PinnedState;
+};
+export type SortOptions<TData, TKey extends keyof TData> = {
+    firstSortDirection?: SortDirection;
+    comparator?: Comparator<TData[TKey]>;
+};
+export type ColCell<TData> = (props: {
+    row: TData;
+    value: any;
+}) => ReactNode;
+export type DisplayColAccessor = () => undefined;
+export type AccessorAccessor<TData, TKey extends keyof TData> = (row: TData) => TData[TKey];
+export type AccessorFn<TData> = (row: TData) => ReactNode;
+export type Comparator<TValue> = (a: TValue, b: TValue) => number;
+export type SortDirection = 'asc' | 'desc' | null;
+export type PinnedState = 'left' | 'right' | undefined | boolean;

package/dist/types.d.ts

@@ -0,0 +1,198 @@
+import { PageDetails, EnforceNoProperties, PaginationRootProps } from '@cerberus-design/react';
+import { Setter, Accessor } from '@cerberus-design/signals';
+import { ReactNode } from 'react';
+import { RowSize } from './const';
+export interface GridOptions<TData> {
+    /**
+     * The full Array of data you want the grid to render.
+     */
+    data: TData[];
+    /**
+     * A list of Defined Columns created using the column helper.
+     */
+    columns: ColumnDef<TData>[];
+    /**
+     * Initial options for feature-related settings.
+     */
+    initialState?: {
+        pagination?: boolean | PaginationOptions;
+    };
+    /**
+     * Called when a user clicks on a pagination page trigger.
+     */
+    onPageChange?: (details: PageDetails) => void;
+    /**
+     * Content to display above the Data Grid and within the Grid context.
+     */
+    toolbar?: ReactNode;
+    /**
+     * Content to display below the Data Grid and within the Grid context.
+     */
+    footer?: ReactNode;
+    /**
+     * The visual spacing of cells within a row. Can be a predefined size or any
+     * valid CSS sizing value.
+     *
+     * **default**: 'md'.
+     */
+    rowSize?: RowSizeOptions;
+}
+export type ColumnDef<TData, TKey extends keyof TData = keyof TData> = {
+    id: string;
+    /**
+     * The label or custom compoent to display.
+     */
+    header: string | ((props: {
+        colId: string;
+    }) => ReactNode);
+    /**
+     * A helper to access and manage the preferred value of the cell.
+     */
+    accessor: DisplayColAccessor | AccessorAccessor<TData, TKey> | AccessorFn<TData>;
+    /**
+     * Strictly define the cell width. Expects a pixel-based number.
+     * @default 150px
+     */
+    minWidth?: number;
+    /**
+     * Strictly define the cell width. Expects a pixel-based number. If the width
+     * provided is smaller than what is required for features, the minimum width
+     * of 100px will be used instead.
+     * @default 150px
+     */
+    width?: number;
+    features?: ColumnFeatures<TData, TKey>;
+    /**
+     * The cell renderer. Provides access to the accessor value and row data. This
+     * is used to provide custom components for the cell content.
+     *
+     * If no content is provided a string will be rendered.
+     */
+    cell?: ColCell<TData>;
+};
+export type PaginationOptions = {
+    /**
+     * The total number of rows that exist. This is useful if you choose to use
+     * server-side pagination design.
+     */
+    count?: PaginationRootProps['count'];
+    /**
+     * The default page index to start on.
+     */
+    defaultPage?: PaginationRootProps['defaultPage'];
+    /**
+     * The default page size to start with. **Must be included in customRange if
+     * using any value other than 25, 50, or 100**.
+     *
+     * default: 0
+     */
+    pageSize?: PaginationRootProps['pageSize'];
+    /**
+     * A custom range of page sizes to display in the page size dropdown.
+     */
+    customRange?: number[];
+};
+export type AccessorOptions<TData, TKey extends keyof TData> = {
+    id?: string;
+    header: string | ((props: {
+        colId: string;
+    }) => ReactNode);
+    features?: ColumnFeatures<TData, TKey>;
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    cell?: ColCell<TData>;
+};
+export type DisplayOptions<TData, TKey extends keyof TData> = {
+    id: string;
+    header: string | ((props: {
+        colId: string;
+    }) => ReactNode);
+    width?: number;
+    features?: {
+        pinning?: ColumnFeatures<TData, TKey>['pinning'];
+    };
+    cell: ColCell<TData>;
+};
+export type InternalColumn<TData> = {
+    id: string;
+    pinned: Accessor<PinnedState>;
+    isFlex: Accessor<boolean>;
+    isVisible: Accessor<boolean>;
+    width: Accessor<number>;
+    pinnable: boolean;
+    sortable: boolean;
+    filterable: boolean;
+    getValue: ColumnDef<TData>['accessor'];
+    original: ColumnDef<TData>;
+    setFlex: Setter<boolean>;
+    setColWidth: Setter<number>;
+    setPinned: Setter<PinnedState>;
+};
+export type SortState = {
+    id: string;
+    desc: boolean;
+};
+export interface GridStore<TData> {
+    columns: Accessor<InternalColumn<TData>[]>;
+    rows: Accessor<TData[]>;
+    globalFilter: Accessor<string>;
+    sorting: Accessor<SortState[]>;
+    pageIndex: Accessor<number>;
+    pageSize: Accessor<number>;
+    pageRange: Accessor<number[]>;
+    pageCount: Accessor<number>;
+    currentPageRange: Accessor<{
+        start: number;
+        end: number;
+    }>;
+    isServerPaginated: Accessor<boolean>;
+    rootCssVars: Accessor<Record<string, string>>;
+    rowCount: Accessor<number>;
+    rowSize: Accessor<number>;
+    totalWidth: Accessor<number>;
+    visibleRows: Accessor<TData[]>;
+    resizeColumn: (colId: string, delta: number) => void;
+    setContainerWidth: (val: number) => void;
+    setPage: (details: PageDetails) => void;
+    setPageSize: (size: number) => void;
+    setGlobalFilter: (val: string) => void;
+    setSort: (colId: string, direction: SortDirection, multi?: boolean) => void;
+    togglePinned: (colId: string, state: PinnedState) => void;
+    toggleSort: (colId: string, multi?: boolean) => void;
+    updateData: (newData: TData[]) => void;
+}
+export type RowSizeOptions = RowSize | number;
+export type ColumnFeatures<TData, TKey extends keyof TData> = {
+    /**
+     * Allow the column to be sorted and the rules to use.
+     */
+    sort?: (boolean & EnforceNoProperties<SortOptions<TData, TKey>>) | SortOptions<TData, TKey>;
+    /**
+     * Allow the column to be filtered and the rules to use.
+     */
+    filter?: boolean | {
+        operator?: 'contains' | 'equals' | 'startsWith';
+    };
+    /**
+     * Show pinning options in the column menu
+     */
+    pinning?: (boolean & EnforceNoProperties<PinnedOptions>) | PinnedOptions;
+};
+export type PinnedOptions = {
+    defaultPosition?: PinnedState;
+};
+export type SortOptions<TData, TKey extends keyof TData> = {
+    firstSortDirection?: SortDirection;
+    comparator?: Comparator<TData[TKey]>;
+};
+export type ColCell<TData> = (props: {
+    row: TData;
+    value: any;
+}) => ReactNode;
+export type DisplayColAccessor = () => undefined;
+export type AccessorAccessor<TData, TKey extends keyof TData> = (row: TData) => TData[TKey];
+export type AccessorFn<TData> = (row: TData) => ReactNode;
+export type Comparator<TValue> = (a: TValue, b: TValue) => number;
+export type SortDirection = 'asc' | 'desc' | null;
+export type PinnedState = 'left' | 'right' | undefined | boolean;

package/dist/utils.cjs

@@ -0,0 +1,59 @@
+'use client';
+'use strict';
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const _const = require('./const.cjs');
+
+function determineRowHeight(rowSize = _const.SM) {
+  const prebuiltSizes = _const.ROW_SIZES.items;
+  if (typeof rowSize === "number") {
+    return rowSize;
+  }
+  if (prebuiltSizes.includes(rowSize)) {
+    const size = _const.ROW_SIZES.results[rowSize];
+    return size;
+  }
+  console.error(
+    "Unknown row size provided to Data Grid. The rowSize prop requires a number to determine pixel-based value.",
+    rowSize
+  );
+  return 0;
+}
+function determinePageSize(options) {
+  if (!options) return 0;
+  if (typeof options === "boolean" && options === true) {
+    return _const.SM_PAGE_SIZE;
+  }
+  if (options.customRange?.length) {
+    return options.customRange[0];
+  }
+  return options.pageSize ?? _const.SM_PAGE_SIZE;
+}
+function determinePageIndex(options) {
+  if (!options) return _const.DEFAULT_PAGE_IDX;
+  if (typeof options === "boolean" && options === true) {
+    return _const.DEFAULT_PAGE_IDX;
+  }
+  return options.defaultPage ?? _const.DEFAULT_PAGE_IDX;
+}
+function determinePageRange(options) {
+  if (!options) return _const.DEFAULT_PAGE_SIZES;
+  if (typeof options === "boolean" && options === true) {
+    return _const.DEFAULT_PAGE_SIZES;
+  }
+  return options.customRange ?? _const.DEFAULT_PAGE_SIZES;
+}
+function determineInitialCount(options) {
+  if (!options) return void 0;
+  if (typeof options === "boolean" && options === true) {
+    return void 0;
+  }
+  return options?.count ?? void 0;
+}
+
+exports.determineInitialCount = determineInitialCount;
+exports.determinePageIndex = determinePageIndex;
+exports.determinePageRange = determinePageRange;
+exports.determinePageSize = determinePageSize;
+exports.determineRowHeight = determineRowHeight;

package/dist/utils.d.cts

@@ -0,0 +1,6 @@
+import { PaginationOptions, RowSizeOptions } from './types';
+export declare function determineRowHeight(rowSize?: RowSizeOptions): number;
+export declare function determinePageSize(options?: boolean | PaginationOptions): number;
+export declare function determinePageIndex(options?: boolean | PaginationOptions): number;
+export declare function determinePageRange(options?: boolean | PaginationOptions): number[];
+export declare function determineInitialCount(options?: boolean | PaginationOptions): number | undefined;

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+import { PaginationOptions, RowSizeOptions } from './types';
+export declare function determineRowHeight(rowSize?: RowSizeOptions): number;
+export declare function determinePageSize(options?: boolean | PaginationOptions): number;
+export declare function determinePageIndex(options?: boolean | PaginationOptions): number;
+export declare function determinePageRange(options?: boolean | PaginationOptions): number[];
+export declare function determineInitialCount(options?: boolean | PaginationOptions): number | undefined;

package/dist/utils.js

@@ -0,0 +1,51 @@
+'use client';
+import { SM, ROW_SIZES, DEFAULT_PAGE_IDX, SM_PAGE_SIZE, DEFAULT_PAGE_SIZES } from './const.js';
+
+function determineRowHeight(rowSize = SM) {
+  const prebuiltSizes = ROW_SIZES.items;
+  if (typeof rowSize === "number") {
+    return rowSize;
+  }
+  if (prebuiltSizes.includes(rowSize)) {
+    const size = ROW_SIZES.results[rowSize];
+    return size;
+  }
+  console.error(
+    "Unknown row size provided to Data Grid. The rowSize prop requires a number to determine pixel-based value.",
+    rowSize
+  );
+  return 0;
+}
+function determinePageSize(options) {
+  if (!options) return 0;
+  if (typeof options === "boolean" && options === true) {
+    return SM_PAGE_SIZE;
+  }
+  if (options.customRange?.length) {
+    return options.customRange[0];
+  }
+  return options.pageSize ?? SM_PAGE_SIZE;
+}
+function determinePageIndex(options) {
+  if (!options) return DEFAULT_PAGE_IDX;
+  if (typeof options === "boolean" && options === true) {
+    return DEFAULT_PAGE_IDX;
+  }
+  return options.defaultPage ?? DEFAULT_PAGE_IDX;
+}
+function determinePageRange(options) {
+  if (!options) return DEFAULT_PAGE_SIZES;
+  if (typeof options === "boolean" && options === true) {
+    return DEFAULT_PAGE_SIZES;
+  }
+  return options.customRange ?? DEFAULT_PAGE_SIZES;
+}
+function determineInitialCount(options) {
+  if (!options) return void 0;
+  if (typeof options === "boolean" && options === true) {
+    return void 0;
+  }
+  return options?.count ?? void 0;
+}
+
+export { determineInitialCount, determinePageIndex, determinePageRange, determinePageSize, determineRowHeight };

package/dist/virtualizer.client.cjs

@@ -0,0 +1,56 @@
+'use client';
+'use strict';
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const signals = require('@cerberus-design/signals');
+const react = require('react');
+
+function useVirtualizer(store, viewportRef) {
+  const isServerPaginated = signals.useRead(store.isServerPaginated);
+  const rows = signals.useRead(store.visibleRows);
+  const rowHeight = signals.useRead(store.rowSize);
+  const [scrollTop, setScrollTop] = signals.useSignal(0);
+  const [containerHeight, setContainerHeight] = signals.useSignal(0);
+  react.useEffect(() => {
+    let rafId;
+    const el = viewportRef.current;
+    if (!el) return;
+    const onScroll = () => {
+      if (rafId) cancelAnimationFrame(rafId);
+      rafId = requestAnimationFrame(() => {
+        setScrollTop(el.scrollTop);
+      });
+    };
+    el.addEventListener("scroll", onScroll, { passive: true });
+    const observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        setContainerHeight(entry.contentRect.height);
+      }
+    });
+    observer.observe(el);
+    return () => {
+      el.removeEventListener("scroll", onScroll);
+      if (rafId) cancelAnimationFrame(rafId);
+      observer.disconnect();
+    };
+  }, [viewportRef, setScrollTop, setContainerHeight]);
+  return react.useMemo(() => {
+    if (isServerPaginated) {
+      return { virtualRows: [], totalHeight: 0, rowHeight };
+    }
+    const totalHeight = rows.length * rowHeight;
+    const buffer = 5;
+    const visibleCount = Math.ceil((containerHeight || 600) / rowHeight);
+    const start = Math.max(0, Math.floor(scrollTop / rowHeight) - buffer);
+    const end = Math.min(rows.length, start + visibleCount + buffer * 2);
+    const virtualRows = rows.slice(start, end).map((row, index) => ({
+      data: row,
+      index: start + index,
+      offsetY: (start + index) * rowHeight
+    }));
+    return { virtualRows, totalHeight, rowHeight };
+  }, [isServerPaginated, rows, rowHeight, scrollTop, containerHeight]);
+}
+
+exports.useVirtualizer = useVirtualizer;

package/dist/virtualizer.client.d.cts

@@ -0,0 +1,11 @@
+import { RefObject } from 'react';
+import { GridStore } from './types';
+export declare function useVirtualizer(store: GridStore<unknown>, viewportRef: RefObject<HTMLDivElement | null>): {
+    virtualRows: {
+        data: unknown;
+        index: number;
+        offsetY: number;
+    }[];
+    totalHeight: number;
+    rowHeight: number;
+};

package/dist/virtualizer.client.d.ts

@@ -0,0 +1,11 @@
+import { RefObject } from 'react';
+import { GridStore } from './types';
+export declare function useVirtualizer(store: GridStore<unknown>, viewportRef: RefObject<HTMLDivElement | null>): {
+    virtualRows: {
+        data: unknown;
+        index: number;
+        offsetY: number;
+    }[];
+    totalHeight: number;
+    rowHeight: number;
+};

package/dist/virtualizer.client.js

@@ -0,0 +1,52 @@
+'use client';
+import { useRead, useSignal } from '@cerberus-design/signals';
+import { useEffect, useMemo } from 'react';
+
+function useVirtualizer(store, viewportRef) {
+  const isServerPaginated = useRead(store.isServerPaginated);
+  const rows = useRead(store.visibleRows);
+  const rowHeight = useRead(store.rowSize);
+  const [scrollTop, setScrollTop] = useSignal(0);
+  const [containerHeight, setContainerHeight] = useSignal(0);
+  useEffect(() => {
+    let rafId;
+    const el = viewportRef.current;
+    if (!el) return;
+    const onScroll = () => {
+      if (rafId) cancelAnimationFrame(rafId);
+      rafId = requestAnimationFrame(() => {
+        setScrollTop(el.scrollTop);
+      });
+    };
+    el.addEventListener("scroll", onScroll, { passive: true });
+    const observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        setContainerHeight(entry.contentRect.height);
+      }
+    });
+    observer.observe(el);
+    return () => {
+      el.removeEventListener("scroll", onScroll);
+      if (rafId) cancelAnimationFrame(rafId);
+      observer.disconnect();
+    };
+  }, [viewportRef, setScrollTop, setContainerHeight]);
+  return useMemo(() => {
+    if (isServerPaginated) {
+      return { virtualRows: [], totalHeight: 0, rowHeight };
+    }
+    const totalHeight = rows.length * rowHeight;
+    const buffer = 5;
+    const visibleCount = Math.ceil((containerHeight || 600) / rowHeight);
+    const start = Math.max(0, Math.floor(scrollTop / rowHeight) - buffer);
+    const end = Math.min(rows.length, start + visibleCount + buffer * 2);
+    const virtualRows = rows.slice(start, end).map((row, index) => ({
+      data: row,
+      index: start + index,
+      offsetY: (start + index) * rowHeight
+    }));
+    return { virtualRows, totalHeight, rowHeight };
+  }, [isServerPaginated, rows, rowHeight, scrollTop, containerHeight]);
+}
+
+export { useVirtualizer };