@jmruthers/pace-core 0.6.10 → 0.6.12

package/src/components/DataTable/types/actions.ts

@@ -0,0 +1,71 @@
+/**
+ * @file DataTable action type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import React from 'react';
+import type { DataRecord } from './base';
+
+/** Boolean condition or predicate evaluated against a row */
+export type ActionCondition<TData extends DataRecord> = boolean | ((row: TData) => boolean);
+
+/**
+ * Action definition for DataTable rows.
+ * Defines custom actions that can be performed on table rows.
+ */
+export interface DataTableAction<TData extends DataRecord> {
+  /** Display label for the action */
+  label: string;
+  /** Icon component */
+  icon?: React.ComponentType<{ className?: string }>;
+  /** Action handler */
+  onClick: (row: TData) => void;
+  /** Visual variant */
+  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost';
+  /** Whether action is disabled */
+  disabled?: ActionCondition<TData>;
+  /** Whether action is hidden (for RBAC) */
+  hidden?: boolean;
+  /** Explicit visibility override */
+  visible?: ActionCondition<TData>;
+  /** Test ID for testing */
+  testId?: string;
+  /** Whether this action should only show for parent rows (hierarchical mode) */
+  showForParent?: boolean;
+  /** Whether this action should only show for child rows (hierarchical mode) */
+  showForChild?: boolean;
+  /** Icon component for parent rows (overrides icon when showForParent is true) */
+  parentIcon?: React.ComponentType<{ className?: string }>;
+  /** Icon component for child rows (overrides icon when showForChild is true) */
+  childIcon?: React.ComponentType<{ className?: string }>;
+  /** Label for parent rows (overrides label when showForParent is true) */
+  parentLabel?: string;
+  /** Label for child rows (overrides label when showForChild is true) */
+  childLabel?: string;
+  /** Whether the action should be shown while the row is in edit mode */
+  showInEditMode?: boolean;
+  /** Whether the action should be hidden while the row is in view mode */
+  hideInViewMode?: boolean;
+  /** Whether the action should explicitly render while in view mode */
+  showInViewMode?: boolean;
+}
+
+/** Actions prop for row components (MemoizedRow, etc.). */
+export type RowActionsProp<TData extends DataRecord = DataRecord> = DataTableAction<TData>[];
+
+/** Toolbar button definition */
+export interface DataTableToolbarButton {
+  /** Display label */
+  label: string;
+  /** Icon component */
+  icon?: React.ComponentType<{ className?: string }>;
+  /** Click handler */
+  onClick: () => void;
+  /** Visual variant */
+  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost';
+  /** Whether button is disabled */
+  disabled?: boolean;
+  /** Test ID for testing */
+  testId?: string;
+}

package/src/components/DataTable/types/base.ts

@@ -0,0 +1,39 @@
+/**
+ * @file DataTable base type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+// Extend TanStack Table types to include custom meta properties (must be in a loaded file)
+declare module '@tanstack/react-table' {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface ColumnMeta<TData, TValue> {
+    /** Text alignment for the column content */
+    align?: 'left' | 'right' | 'center';
+    /** Column type for styling purposes */
+    type?: 'text' | 'number' | 'date' | 'boolean' | 'custom';
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface ColumnDefBase<TData, TValue> {
+    /** Alternative accessor key used while editing */
+    editAccessorKey?: string;
+  }
+}
+
+/** Core value types that can exist in a data record */
+export type CellValue = string | number | boolean | null | undefined | Date;
+
+/**
+ * Base data record type - all DataTable data must extend this.
+ * Individual implementations should define more specific types.
+ */
+export interface DataRecord {
+  [key: string]: unknown;
+}
+
+/** Row ID type - always a string */
+export type RowId = string;
+
+/** Row identifier function type */
+export type GetRowId<TData extends DataRecord> = (row: TData, index: number) => RowId;

package/src/components/DataTable/types/columns.ts

@@ -0,0 +1,125 @@
+/**
+ * @file DataTable column type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import React from 'react';
+import type { ColumnDef } from '@tanstack/react-table';
+import type { DataRecord } from './base';
+
+/** Aggregate configuration */
+export interface AggregateConfig {
+  field: string;
+  function: 'sum' | 'avg' | 'count' | 'min' | 'max';
+  label: string;
+}
+
+/**
+ * Enhanced column definition that extends TanStack's ColumnDef
+ */
+export interface DataTableColumn<TData extends DataRecord = DataRecord> extends Omit<ColumnDef<TData>, 'id' | 'accessorKey'> {
+  /** Column identifier */
+  id?: string;
+  /** Accessor key for data */
+  accessorKey?: string;
+  /** Alternative accessor key used while editing */
+  editAccessorKey?: string;
+  /** Custom header label for the column */
+  header: string;
+  /** Whether this column should be searchable in global filter */
+  searchable?: boolean;
+  /** Enable sorting */
+  sortable?: boolean;
+  /** Enable column filter (inherits from ColumnDef) */
+  enableColumnFilter?: boolean;
+  /** Enable grouping (inherits from ColumnDef) */
+  enableGrouping?: boolean;
+  /** Enable hiding (inherits from ColumnDef) */
+  enableHiding?: boolean;
+  /** Aggregate configuration for this column */
+  aggregate?: AggregateConfig;
+  /** Enable virtual scrolling for this column */
+  virtualizable?: boolean;
+  /** Custom cell renderer with memoization */
+  memoizedCell?: React.ComponentType<{ row: TData }>;
+  /** Field type for editing (text, select, date, checkbox, etc.) */
+  fieldType?: 'text' | 'select' | 'date' | 'number' | 'boolean' | 'checkbox';
+  /** Options for select fields - can be simple items or grouped with labels and separators */
+  fieldOptions?: Array<
+    | { value: string | number; label: string }
+    | { type: 'group'; label: string; items: Array<{ value: string | number; label: string }> }
+    | { type: 'separator' }
+  >;
+  /** Enable keyboard search/filtering in select dropdowns within editable columns (default: true). */
+  selectSearchable?: boolean;
+  /** Enable creating new items in select dropdowns (default: false) */
+  creatable?: boolean;
+  /** Callback to create a new item when user types non-matching text in select dropdown */
+  onCreateNew?: (inputValue: string) => Promise<string | number> | string | number;
+  /** Maximum height for select dropdown content (default: "20rem") */
+  selectMaxHeight?: string;
+  /** Custom className for select content dropdown */
+  selectContentClassName?: string;
+  /** Custom style for select content dropdown */
+  selectContentStyle?: React.CSSProperties;
+  /** Hide spinner arrows on number input fields (default: true for DataTable) */
+  hideNumberSpinners?: boolean;
+  /** Filter type for column filtering (text, select, number, date) */
+  filterType?: 'text' | 'select' | 'number' | 'date';
+  /** Options for select filters (alternative to fieldOptions) */
+  filterSelectOptions?: Array<{ value: string | number; label: string }>;
+  /** Whether this column is editable in edit mode (default: true) */
+  editable?: boolean;
+  /** Alternative CSV headers that should map to this column during import */
+  importAliases?: string[];
+
+  /** Custom renderer for parent rows */
+  renderForParent?: (row: TData) => React.ReactNode;
+  /** Custom renderer for child rows */
+  renderForChild?: (row: TData) => React.ReactNode;
+  /** Hide this column for parent rows */
+  hideForParent?: boolean;
+  /** Hide this column for child rows */
+  hideForChild?: boolean;
+
+  /**
+   * Aggregation function for grouped rows.
+   * If not provided, grouped rows will show empty/undefined for this column.
+   */
+  aggregateFn?: (rows: TData[], column: DataTableColumn<TData>) => unknown;
+  /** Optional: Custom cell renderer for aggregated values in grouped rows. */
+  aggregateCell?: (value: unknown, rows: TData[], column: DataTableColumn<TData>) => React.ReactNode;
+}
+
+/**
+ * Extended column definition used when rendering editable rows
+ */
+export interface EditableColumnDef<TData extends DataRecord = DataRecord> extends DataTableColumn<TData> {
+  /** Whether the column can be edited */
+  editable?: boolean;
+  /** Field type used to determine edit control */
+  fieldType?: 'text' | 'select' | 'date' | 'number' | 'boolean' | 'checkbox';
+  /** Options for select based editors */
+  fieldOptions?: Array<
+    | { value: string | number; label: string }
+    | { type: 'group'; label: string; items: Array<{ value: string | number; label: string }> }
+    | { type: 'separator' }
+  >;
+  selectSearchable?: boolean;
+  creatable?: boolean;
+  onCreateNew?: (inputValue: string) => Promise<string | number> | string | number;
+  hideNumberSpinners?: boolean;
+}
+
+/** Simple column interface for basic use cases */
+export interface SimpleColumn<TData extends DataRecord = DataRecord> {
+  /** Data accessor key */
+  key: keyof TData | string;
+  /** Display label */
+  label: string;
+  /** Enable sorting */
+  sortable?: boolean;
+  /** Enable filtering */
+  filterable?: boolean;
+}

package/src/components/DataTable/types/export.ts

@@ -0,0 +1,32 @@
+/**
+ * @file DataTable export type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import type { DataRecord } from './base';
+import type { DataTableColumn } from './columns';
+
+/**
+ * Options provided to the onExport handler for custom export functionality
+ */
+export interface ExportOptions<TData extends DataRecord> {
+  /** Filtered table rows with getValue() method for proper accessorFn evaluation */
+  tableRows: Array<{
+    original: TData;
+    getValue: (columnId: string) => unknown;
+    id: string;
+  }>;
+  /** All column definitions passed to the DataTable */
+  allColumns: DataTableColumn<TData>[];
+  /** Currently visible columns in the table */
+  visibleColumns: DataTableColumn<TData>[];
+  /** Mapping of column IDs to TanStack table column instances (for getValue() calls) */
+  columnIdToTableColumn: Map<string, unknown>;
+  /** Raw data array (unfiltered) */
+  data: TData[];
+  /** Default filename generated from table title */
+  filename: string;
+  /** TanStack table instance for advanced operations */
+  table: unknown;
+}

package/src/components/DataTable/types/features.ts

@@ -0,0 +1,81 @@
+/**
+ * @file DataTable feature configuration type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import React from 'react';
+
+/**
+ * Unified feature configuration for DataTable
+ * All features are disabled by default and must be explicitly enabled
+ */
+export interface DataTableFeatureFlags {
+  search: boolean;
+  pagination: boolean;
+  sorting: boolean;
+  filtering: boolean;
+  import: boolean;
+  export: boolean;
+  selection: boolean;
+  creation: boolean;
+  editing: boolean;
+  deletion: boolean;
+  deleteSelected: boolean;
+  grouping: boolean;
+  columnVisibility: boolean;
+  columnReordering: boolean;
+  hierarchical: boolean;
+}
+
+/**
+ * Consumer-facing feature configuration. All properties are optional and will be
+ * merged with defaultDataTableFeatures at runtime.
+ */
+export type DataTableFeatureConfig = Partial<DataTableFeatureFlags>;
+
+/** Fully normalized feature configuration used internally by the table. */
+export type NormalizedDataTableFeatureConfig = DataTableFeatureFlags;
+
+/** Default feature configuration with every capability disabled. */
+export const defaultDataTableFeatures: NormalizedDataTableFeatureConfig = {
+  search: false,
+  pagination: false,
+  sorting: false,
+  filtering: false,
+  import: false,
+  export: false,
+  selection: false,
+  creation: false,
+  editing: false,
+  deletion: false,
+  deleteSelected: false,
+  grouping: false,
+  columnVisibility: false,
+  columnReordering: false,
+  hierarchical: false,
+};
+
+/**
+ * Normalize a potentially partial feature configuration.
+ * Downstream consumers can rely on every flag being present.
+ */
+export function normalizeDataTableFeatures(
+  features?: DataTableFeatureConfig
+): NormalizedDataTableFeatureConfig {
+  return {
+    ...defaultDataTableFeatures,
+    ...(features ?? {}),
+  };
+}
+
+/** Empty state configuration */
+export interface EmptyStateConfig {
+  title?: string;
+  description?: string;
+  icon?: React.ComponentType<{ className?: string }>;
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+}

package/src/components/DataTable/types/hierarchical.ts

@@ -0,0 +1,44 @@
+/**
+ * @file DataTable hierarchical type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import type { DataRecord } from './base';
+
+/** Hierarchical data row interface for parent/child relationships */
+export interface HierarchicalDataRow extends DataRecord {
+  /** Whether this row is a parent row */
+  isParent: boolean;
+  /** For child rows, references the parent row ID */
+  parentId?: string;
+  /** Unique identifier for this row */
+  id: string;
+}
+
+/** Runtime state for hierarchical expand/collapse (injected by useHierarchicalState). */
+export interface HierarchicalState {
+  isExpanded: (rowId: string) => boolean;
+  hasChildren: (rowId: string) => boolean;
+  getChildrenCount: (rowId: string) => number;
+  toggleRow: (rowId: string) => void;
+}
+
+/** Hierarchical configuration for DataTable */
+export interface HierarchicalConfig {
+  /** Enable hierarchical functionality */
+  enabled: boolean;
+  /** Default expanded state - true = all expanded, false = all collapsed, array = specific IDs */
+  defaultExpanded?: boolean | string[];
+  /** Callback when expanded state changes */
+  onExpandedChange?: (expandedIds: string[]) => void;
+  /** Visual indentation for child rows (in pixels) */
+  indentSize?: number;
+  /** Custom styling for parent rows */
+  parentRowClassName?: string;
+  /** Custom styling for child rows */
+  childRowClassName?: string;
+}
+
+/** Hierarchical config with optional runtime state (used by RowComponent). */
+export type HierarchicalConfigWithState = HierarchicalConfig & { state?: HierarchicalState };

package/src/components/DataTable/types/index.ts

@@ -0,0 +1,43 @@
+/**
+ * @file DataTable type definitions - barrel export
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ *
+ * Import base first so TanStack module augmentation is applied.
+ */
+
+import './base';
+
+export type { CellValue, DataRecord, RowId, GetRowId } from './base';
+export type { HierarchicalDataRow, HierarchicalConfig, HierarchicalState, HierarchicalConfigWithState } from './hierarchical';
+export type { PerformanceConfig, SearchIndexConfig, ChunkingConfig } from './performance';
+export type {
+  PaginationMode,
+  ServerSideParams,
+  ServerSideResponse,
+  ServerSideConfig,
+  PaginationConfig,
+  PaginationCallbacks,
+} from './pagination';
+export type {
+  AggregateConfig,
+  DataTableColumn,
+  EditableColumnDef,
+  SimpleColumn,
+} from './columns';
+export type {
+  DataTableFeatureFlags,
+  DataTableFeatureConfig,
+  NormalizedDataTableFeatureConfig,
+  EmptyStateConfig,
+} from './features';
+export { defaultDataTableFeatures, normalizeDataTableFeatures } from './features';
+export type {
+  ActionCondition,
+  DataTableAction,
+  RowActionsProp,
+  DataTableToolbarButton,
+} from './actions';
+export type { DataTableRBACConfig, DataTableRowPermissions, DataTablePermissionSlot, RBACContext } from './rbac';
+export type { ExportOptions } from './export';
+export type { DataTableProps } from './props';

package/src/components/DataTable/types/pagination.ts

@@ -0,0 +1,85 @@
+/**
+ * @file DataTable pagination type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import type { SortingState, ColumnFiltersState, GroupingState } from '@tanstack/react-table';
+import type { DataRecord } from './base';
+
+/** Pagination mode determines how data is handled */
+export type PaginationMode = 'client' | 'server' | 'hybrid';
+
+/** Parameters sent to server for data fetching */
+export interface ServerSideParams {
+  /** Current page index */
+  pageIndex: number;
+  /** Page size */
+  pageSize: number;
+  /** Sorting configuration */
+  sorting: SortingState;
+  /** Column filters */
+  columnFilters: ColumnFiltersState;
+  /** Global filter/search term */
+  globalFilter: string;
+  /** Grouping configuration */
+  grouping: GroupingState;
+}
+
+/** Response from server for data fetching */
+export interface ServerSideResponse<TData extends DataRecord> {
+  /** Array of data records */
+  data: TData[];
+  /** Total number of records (for pagination) */
+  totalCount: number;
+  /** Current page index */
+  pageIndex: number;
+  /** Page size */
+  pageSize: number;
+  /** Total number of pages */
+  pageCount: number;
+  /** Whether there are more pages */
+  hasNextPage: boolean;
+  /** Whether there are previous pages */
+  hasPreviousPage: boolean;
+}
+
+/** Server-side data fetching configuration */
+export interface ServerSideConfig<TData extends DataRecord> {
+  /** Function to fetch data from server */
+  fetchData: (params: ServerSideParams) => Promise<ServerSideResponse<TData>>;
+  /** Enable server-side sorting */
+  enableServerSorting?: boolean;
+  /** Enable server-side filtering */
+  enableServerFiltering?: boolean;
+  /** Enable server-side search */
+  enableServerSearch?: boolean;
+  /** Enable server-side pagination */
+  enableServerPagination?: boolean;
+  /** Debounce delay for server requests */
+  debounceMs?: number;
+  /** Cache duration for server responses */
+  cacheMs?: number;
+}
+
+/** Unified pagination configuration for consistent behavior across modes */
+export interface PaginationConfig {
+  /** Pagination mode */
+  mode: PaginationMode;
+  /** Available page size options */
+  pageSizeOptions?: number[];
+  /** Initial page size */
+  initialPageSize?: number;
+  /** Show enhanced pagination controls (jump to page, etc.) */
+  enhanced?: boolean;
+  /** Show performance mode indicator */
+  showPerformanceInfo?: boolean;
+}
+
+/** Pagination callbacks for server-side and hybrid modes */
+export interface PaginationCallbacks {
+  /** Called when page index changes */
+  onPageChange?: (pageIndex: number) => void;
+  /** Called when page size changes */
+  onPageSizeChange?: (pageSize: number) => void;
+}

package/src/components/DataTable/types/performance.ts

@@ -0,0 +1,47 @@
+/**
+ * @file DataTable performance type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+/** Performance configuration for large datasets */
+export interface PerformanceConfig {
+  /** Enable virtual scrolling */
+  virtualScrolling?: boolean;
+  /** Virtual scrolling overscan count */
+  overscan?: number;
+  /** Enable memoization of cell renderers */
+  memoizeCells?: boolean;
+  /** Enable debounced search */
+  debounceSearch?: number;
+  /** Enable data chunking for memory management */
+  enableChunking?: boolean;
+  /** Chunk size for data processing */
+  chunkSize?: number;
+  /** Enable Web Workers for heavy operations */
+  enableWebWorkers?: boolean;
+  /** Threshold for switching to server-side mode */
+  serverSideThreshold?: number;
+}
+
+/** Search index configuration for performance */
+export interface SearchIndexConfig {
+  /** Fields to index for search */
+  indexedFields: string[];
+  /** Enable fuzzy search */
+  fuzzySearch?: boolean;
+  /** Fuzzy search threshold */
+  fuzzyThreshold?: number;
+  /** Enable search highlighting */
+  enableHighlighting?: boolean;
+}
+
+/** Data chunking configuration */
+export interface ChunkingConfig {
+  /** Size of each data chunk */
+  chunkSize: number;
+  /** Number of chunks to keep in memory */
+  maxChunksInMemory: number;
+  /** Enable progressive loading */
+  progressiveLoading?: boolean;
+}

package/src/components/DataTable/types/props.ts

@@ -0,0 +1,62 @@
+/**
+ * @file DataTable props type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import type { DataRecord, GetRowId } from './base';
+import type { HierarchicalConfig } from './hierarchical';
+import type { PerformanceConfig, SearchIndexConfig, ChunkingConfig } from './performance';
+import type { PaginationMode, ServerSideConfig } from './pagination';
+import type { DataTableColumn, SimpleColumn, AggregateConfig } from './columns';
+import type { DataTableFeatureConfig, EmptyStateConfig } from './features';
+import type { DataTableRBACConfig } from './rbac';
+import type { ExportOptions } from './export';
+import type { ImportModalConfig } from '../ui/modals/ImportModal';
+import type { ImportHandlerResult } from '../ui/modals/importModalPersistence';
+
+/**
+ * Enhanced DataTable props with unified feature configuration and MANDATORY RBAC
+ */
+export interface DataTableProps<TData extends DataRecord> {
+  /** Array of data to display */
+  data: TData[];
+  /** Column definitions - supports both DataTableColumn and SimpleColumn formats */
+  columns: (DataTableColumn<TData> | SimpleColumn<TData>)[];
+  /** RBAC configuration - REQUIRED for all DataTables */
+  rbac: DataTableRBACConfig;
+
+  title?: string;
+  description?: string;
+  variant?: 'default' | 'compact' | 'spacious';
+  className?: string;
+  features?: DataTableFeatureConfig;
+  hierarchical?: HierarchicalConfig;
+  performance?: PerformanceConfig;
+  serverSide?: ServerSideConfig<TData>;
+  paginationMode?: PaginationMode;
+  chunking?: ChunkingConfig;
+  searchIndex?: SearchIndexConfig;
+  initialPageSize?: number;
+
+  defaultGrouping?: string[];
+  defaultSorting?: Array<{ id: string; desc: boolean }>;
+  initialColumnVisibility?: Record<string, boolean>;
+
+  onEditRow?: (row: TData, data: Partial<TData>) => void;
+  onDeleteRow?: (row: TData) => void;
+  onCreateRow?: (data: Partial<TData>) => void;
+  onImport?: (data: TData[]) => ImportHandlerResult;
+  onExport?: (options: ExportOptions<TData>) => void | Promise<void>;
+  onRowSelectionChange?: (selection: Record<string, boolean>) => void;
+  selection?: Record<string, boolean>;
+  onDeleteSelected?: (selectedRows: Record<string, boolean>) => void;
+
+  getRowId?: GetRowId<TData>;
+  isLoading?: boolean;
+  emptyState?: EmptyStateConfig;
+  aggregates?: AggregateConfig[];
+  importModalConfig?: ImportModalConfig;
+  /** Called when the import modal is closed (e.g. to refetch table data). */
+  onImportModalClose?: () => void;
+}

package/src/components/DataTable/types/rbac.ts

@@ -0,0 +1,45 @@
+/**
+ * @file DataTable RBAC type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+/** Single permission slot (can + loading) used by row-level permission checks. */
+export interface DataTablePermissionSlot {
+  can: boolean;
+  isLoading: boolean;
+}
+
+/** Row-level permissions passed to RowComponent for action visibility. */
+export interface DataTableRowPermissions {
+  canRead: DataTablePermissionSlot;
+  canCreate: DataTablePermissionSlot;
+  canUpdate: DataTablePermissionSlot;
+  canDelete: DataTablePermissionSlot;
+  canExport: DataTablePermissionSlot;
+  canImport: DataTablePermissionSlot;
+}
+
+/**
+ * RBAC configuration for DataTable - MANDATORY for all DataTables
+ */
+export interface DataTableRBACConfig {
+  /** Page name for page-based permissions - will be resolved to page ID */
+  pageName?: string;
+  /** Page ID for page-based permissions - used directly if provided */
+  pageId?: string;
+}
+
+/** RBAC context passed to server-side requests */
+export interface RBACContext {
+  /** User ID for permission checking */
+  userId: string;
+  /** Organisation ID for scope isolation */
+  organisationId: string;
+  /** Event ID for event-based apps */
+  eventId?: string;
+  /** App ID for app-specific permissions */
+  appId?: string;
+  /** Page ID for granular permissions */
+  pageId: string;
+}