@topgrid/grid-pro-master 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,393 @@
+import { ReactNode, Ref, ReactElement } from 'react';
+import { GridProps, GridHandle } from '@topgrid/grid-core';
+export { ColumnPinGrid, ColumnPinGridProps, TreeGrid, TreeGridProps } from '@topgrid/grid-core';
+import { Cell, Row, ExpandedState } from '@tanstack/react-table';
+import { StorageType } from '@topgrid/grid-core/internal/storage';
+
+/**
+ * @topgrid/grid-pro-master — Public type definitions for Master-Detail and Context Menu grids.
+ *
+ * G-001 (MOD-GRID-16): `<MasterDetailGrid>` wrapper enabling Master-Detail row
+ * expansion with `renderDetailRow` prop and controlled/uncontrolled expanded state.
+ *
+ * G-002 (MOD-GRID-16): `<ContextMenuGrid>` wrapper enabling right-click context menu
+ * with `contextMenuItems` prop and keyboard shortcut support.
+ *
+ * @see G-001-spec.md Section 4.1
+ * @see G-002-spec.md Section 4
+ */
+
+/**
+ * Master-Detail expansion options.
+ *
+ * @typeParam TData - Row data type.
+ *
+ * @example Controlled mode
+ * ```tsx
+ * <MasterDetailGrid
+ *   data={rows}
+ *   columns={columns}
+ *   renderDetailRow={(row) => <DetailPanel data={row.original} />}
+ *   masterDetail={{
+ *     expandedRowKeys: expandedKeys,
+ *     onExpandChange: setExpandedKeys,
+ *   }}
+ * />
+ * ```
+ */
+interface MasterDetailOptions<_TData> {
+    /**
+     * Controlled expanded row key array.
+     * When provided, the component is in controlled mode — expanded state is
+     * driven externally. Keys correspond to TanStack `row.id` values.
+     *
+     * When absent, internal `useState<ExpandedState>` manages state (uncontrolled).
+     */
+    expandedRowKeys?: string[];
+    /**
+     * Callback fired when expanded rows change.
+     * In controlled mode, the parent must update `expandedRowKeys` from this callback.
+     *
+     * @param expandedKeys - Array of currently expanded `row.id` strings.
+     */
+    onExpandChange?: (expandedKeys: string[]) => void;
+}
+/**
+ * Render function type for the Master-Detail detail row content.
+ *
+ * @typeParam TData - Row data type.
+ *
+ * @param row - The TanStack `Row<TData>` object for the expanded master row.
+ * @returns ReactNode to render inside the detail row cell.
+ *
+ * @example
+ * ```tsx
+ * const renderDetailRow: RenderDetailRow<User> = (row) => (
+ *   <UserDetailPanel userId={row.original.id} />
+ * );
+ * ```
+ */
+type RenderDetailRow<TData> = (row: Row<TData>) => ReactNode;
+/**
+ * Props for `<MasterDetailGrid>`.
+ *
+ * Extends `GridProps<TData>` with Master-Detail specific props.
+ *
+ * @typeParam TData - Row data type.
+ *
+ * @see MasterDetailOptions
+ * @see RenderDetailRow
+ * @see G-001-spec.md Section 4.2
+ */
+interface MasterDetailGridProps<TData> extends GridProps<TData> {
+    /**
+     * Detail row render function.
+     *
+     * When provided, each row gains an expand toggle in the first column.
+     * Clicking the toggle reveals a full-width detail row rendered by this function.
+     *
+     * When absent, the grid renders as a standard flat grid without expand toggles.
+     */
+    renderDetailRow?: RenderDetailRow<TData>;
+    /**
+     * Master-Detail expansion options (controlled/uncontrolled state).
+     *
+     * @see MasterDetailOptions
+     */
+    masterDetail?: MasterDetailOptions<TData>;
+}
+/**
+ * A single context menu item definition.
+ *
+ * @typeParam TData - Row data type.
+ *
+ * @example
+ * ```tsx
+ * const items: ContextMenuItem<User>[] = [
+ *   {
+ *     label: '수정',
+ *     shortcut: 'E',
+ *     onClick: (row, cell, event) => openEditDialog(row),
+ *   },
+ *   { separator: true, label: '', onClick: () => {} },
+ *   {
+ *     label: '삭제',
+ *     shortcut: 'Delete',
+ *     disabled: (row) => row.locked,
+ *     onClick: (row, cell, event) => deleteRow(row),
+ *   },
+ * ];
+ * ```
+ *
+ * @see G-002-spec.md Section 4.1
+ */
+interface ContextMenuItem<TData> {
+    /**
+     * Display label for the menu item.
+     * For separator items, the label is ignored — pass an empty string.
+     */
+    label: string;
+    /**
+     * Optional keyboard shortcut hint displayed on the right side of the label.
+     * When the wrapper div has focus and this key is pressed while the menu is open,
+     * the item's `onClick` is triggered (if not disabled).
+     *
+     * Value is a single key string matched against `event.key` (case-insensitive).
+     *
+     * @example `'E'` for the 'e' key, `'Delete'` for the Delete key
+     */
+    shortcut?: string;
+    /**
+     * Whether this item is disabled.
+     *
+     * - `boolean`: static disabled state.
+     * - `(row: TData) => boolean`: evaluated at render time against the target row.
+     *
+     * Disabled items are rendered but not clickable (pointer-events: none equivalent).
+     */
+    disabled?: boolean | ((row: TData) => boolean);
+    /**
+     * When `true`, renders a horizontal separator line.
+     * All other properties except `label` are ignored for separator items.
+     */
+    separator?: boolean;
+    /**
+     * Click handler for this menu item.
+     *
+     * @param row   - The `original` data of the right-clicked row.
+     * @param cell  - The TanStack `Cell<TData, unknown>` that was right-clicked.
+     * @param event - The original `MouseEvent`.
+     */
+    onClick: (row: TData, cell: Cell<TData, unknown>, event: MouseEvent) => void;
+}
+/**
+ * Props for `<ContextMenuGrid>`.
+ *
+ * Extends `GridProps<TData>` with context menu specific props.
+ *
+ * @typeParam TData - Row data type.
+ *
+ * @see ContextMenuItem
+ * @see G-002-spec.md Section 4.2
+ */
+interface ContextMenuGridProps<TData> extends GridProps<TData> {
+    /**
+     * Array of context menu items displayed on right-click.
+     *
+     * When absent (or empty), right-click falls through to the browser default.
+     * When provided, `preventDefault()` is called and the custom menu is shown.
+     *
+     * @see ContextMenuItem
+     */
+    contextMenuItems?: ContextMenuItem<TData>[];
+}
+/**
+ * Row Pinning base type definition (F-16-06).
+ *
+ * Defines `pinTop` / `pinBottom` row id arrays for future TanStack row pinning UI.
+ * **Types-only in this Goal** (D20 / AC-006) — full UI implementation is a separate
+ * follow-up Goal. Pass these values to a future `RowPinningGrid` component.
+ *
+ * @example
+ * ```tsx
+ * const pinning: RowPinningOptions = {
+ *   pinTop: ['row-0', 'row-1'],
+ *   pinBottom: ['row-99'],
+ * };
+ * ```
+ *
+ * @see G-003-spec.md Section 2.3 + D6
+ * @see MOD-GRID-16-decisions.md D20
+ */
+interface RowPinningOptions {
+    /**
+     * Row ids to pin at the top of the grid.
+     * Keys correspond to TanStack `row.id` values.
+     *
+     * @see AC-006 — UI implementation deferred to a separate Goal.
+     */
+    pinTop?: string[];
+    /**
+     * Row ids to pin at the bottom of the grid.
+     * Keys correspond to TanStack `row.id` values.
+     *
+     * @see AC-006 — UI implementation deferred to a separate Goal.
+     */
+    pinBottom?: string[];
+}
+
+/**
+ * `<MasterDetailGrid>` — Pro-tier Master-Detail row expansion.
+ *
+ * Wraps `GridProps<TData>` surface with `renderDetailRow` + `masterDetail` expansion options.
+ * Renders its own standalone `useReactTable` table — does NOT import `<Grid>` from
+ * `@topgrid/grid-core` at runtime (Option B — MIT↔Pro EULA boundary preservation, D1).
+ *
+ * Features:
+ * - `renderDetailRow` prop: render function for expanded detail row content.
+ * - Controlled mode: `masterDetail.expandedRowKeys` + `onExpandChange` callback.
+ * - Uncontrolled mode: internal `useState<ExpandedState>`.
+ * - Imperative handle: `expandAll()` / `collapseAll()` via `ref`.
+ *
+ * @see G-001-spec.md Section 4/8/11
+ * @see MOD-GRID-16-decisions.md D1/D3/D7/D8
+ */
+
+/**
+ * `<MasterDetailGrid>` Pro-tier component with Master-Detail row expansion.
+ *
+ * @typeParam TData - Row data type.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * const gridRef = useRef<GridHandle<Order>>(null);
+ *
+ * <MasterDetailGrid<Order>
+ *   ref={gridRef}
+ *   data={orders}
+ *   columns={columns}
+ *   renderDetailRow={(row) => <OrderDetail order={row.original} />}
+ * />
+ *
+ * gridRef.current?.expandAll();
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [expanded, setExpanded] = useState<string[]>([]);
+ *
+ * <MasterDetailGrid<Order>
+ *   data={orders}
+ *   columns={columns}
+ *   renderDetailRow={(row) => <OrderDetail order={row.original} />}
+ *   masterDetail={{ expandedRowKeys: expanded, onExpandChange: setExpanded }}
+ * />
+ * ```
+ */
+declare const MasterDetailGrid: <TData>(props: MasterDetailGridProps<TData> & {
+    ref?: Ref<GridHandle<TData>>;
+}) => ReactElement;
+
+/**
+ * `<ContextMenuGrid>` — Pro-tier right-click context menu grid.
+ *
+ * Wraps `GridProps<TData>` surface with `contextMenuItems` prop.
+ * Renders its own standalone `useReactTable` table — does NOT import `<Grid>`
+ * from `@topgrid/grid-core` at runtime (Option B — MIT↔Pro EULA boundary, D1).
+ *
+ * Features:
+ * - `contextMenuItems` prop: declarative right-click context menu items.
+ * - `createPortal` menu rendering into `document.body` (D4).
+ * - Keyboard shortcut support via wrapper div `onKeyDown` (D5).
+ * - `disabled` evaluation at render time (D7).
+ *
+ * @see G-002-spec.md Section 4/5/8
+ * @see MOD-GRID-16-decisions.md D9–D16
+ */
+
+/**
+ * `<ContextMenuGrid>` Pro-tier component with right-click context menu support.
+ *
+ * @typeParam TData - Row data type.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * const gridRef = useRef<GridHandle<Order>>(null);
+ *
+ * const menuItems: ContextMenuItem<Order>[] = [
+ *   { label: '수정', shortcut: 'E', onClick: (row) => openEdit(row) },
+ *   { separator: true, label: '', onClick: () => {} },
+ *   {
+ *     label: '삭제',
+ *     shortcut: 'Delete',
+ *     disabled: (row) => row.status === 'completed',
+ *     onClick: (row) => deleteOrder(row),
+ *   },
+ * ];
+ *
+ * <ContextMenuGrid<Order>
+ *   ref={gridRef}
+ *   data={orders}
+ *   columns={columns}
+ *   contextMenuItems={menuItems}
+ * />
+ * ```
+ */
+declare const ContextMenuGrid: <TData>(props: ContextMenuGridProps<TData> & {
+    ref?: Ref<GridHandle<TData>>;
+}) => ReactElement;
+
+/**
+ * `useExpandedPersistence` — Pro-tier hook that persists TanStack `ExpandedState`
+ * to Web Storage (localStorage / sessionStorage) across page refreshes.
+ *
+ * Option B — independent hook. Does NOT modify `useGridState` in `@topgrid/grid-core` (D17).
+ * External composition pattern: wire `[expanded, setExpanded]` return value into
+ * `masterDetail.expandedRowKeys` + `onExpandChange` on `<MasterDetailGrid>`.
+ *
+ * Internal SSR-guard + try/catch + JSON I/O boilerplate is now delegated to
+ * `@topgrid/grid-core/internal/storage` (ADR-007 Wave 3). External API, in-memory
+ * fallback semantics, and dev-mode warning behaviour unchanged.
+ *
+ * @see G-003-spec.md Section 2.1 + D3 (D17 in decisions.md)
+ * @see MOD-GRID-16-decisions.md D17
+ * @see MOD-GRID-REFACTOR-2026-05-17-decisions.md ADR-007
+ */
+
+/**
+ * Options for `useExpandedPersistence`.
+ *
+ * @example
+ * ```tsx
+ * const [expanded, setExpanded] = useExpandedPersistence({
+ *   storageKey: 'orders-grid-expanded',
+ *   storageType: 'localStorage',
+ * });
+ * ```
+ */
+interface UseExpandedPersistenceOptions {
+    /**
+     * Web Storage key. Use a unique key per grid instance to avoid collisions
+     * when multiple grids are mounted on the same page.
+     */
+    storageKey: string;
+    /**
+     * Which Web Storage to use.
+     * - `'localStorage'` (default): persists across browser sessions.
+     * - `'sessionStorage'`: cleared when the tab is closed (EC-07).
+     * @default 'localStorage'
+     */
+    storageType?: StorageType;
+    /**
+     * Initial `ExpandedState` used when no stored value is found or storage is unavailable.
+     * @default {}
+     */
+    initialExpanded?: ExpandedState;
+}
+/** Setter signature matching TanStack table `onExpandedChange` updater contract. */
+type ExpandedStateSetter = (updated: ExpandedState | ((prev: ExpandedState) => ExpandedState)) => void;
+/**
+ * Pro-tier hook — persists TanStack `ExpandedState` to Web Storage.
+ *
+ * @remarks
+ * Does NOT modify `useGridState` in `@topgrid/grid-core` (Option B, D17).
+ * Wire the returned `[expanded, setExpanded]` into `<MasterDetailGrid>`:
+ * ```tsx
+ * masterDetail={{
+ *   expandedRowKeys: Object.keys(expanded).filter(k => (expanded as Record<string,boolean>)[k]),
+ *   onExpandChange: (keys) => {
+ *     const next: Record<string, boolean> = {};
+ *     keys.forEach(k => { next[k] = true; });
+ *     setExpanded(next);
+ *   },
+ * }}
+ * ```
+ *
+ * @param options - Persistence options (storageKey, storageType, initialExpanded).
+ * @returns `[expanded, setExpanded]` tuple compatible with TanStack `ExpandedState`.
+ *
+ * @see G-003-spec.md Section 2.1
+ */
+declare function useExpandedPersistence(options: UseExpandedPersistenceOptions): [ExpandedState, ExpandedStateSetter];
+
+export { ContextMenuGrid, type ContextMenuGridProps, type ContextMenuItem, MasterDetailGrid, type MasterDetailGridProps, type MasterDetailOptions, type RenderDetailRow, type RowPinningOptions, type UseExpandedPersistenceOptions, useExpandedPersistence };