tenantpilot/lib/types/policy-table.ts

/**
 * Policy Explorer V2 - Type Definitions
 * 
 * This file defines TypeScript interfaces for the advanced data table feature.
 * These types manage client-side table state, URL state synchronization, and localStorage persistence.
 */

import type { SortingState, VisibilityState, ColumnSizingState } from '@tanstack/react-table';

/**
 * DataTableState - Client-side ephemeral state for TanStack Table
 * 
 * Manages pagination, sorting, column visibility/sizing, row selection, and density mode.
 * This state is NOT persisted - it's derived from URL params and localStorage preferences.
 */
export interface DataTableState {
  pagination: {
    pageIndex: number;        // 0-based page index
    pageSize: 10 | 25 | 50 | 100;
  };
  sorting: SortingState;      // TanStack Table sorting state: Array<{ id: string; desc: boolean }>
  columnVisibility: VisibilityState;  // TanStack Table visibility state: { [columnId: string]: boolean }
  columnSizing: ColumnSizingState;    // TanStack Table sizing state: { [columnId: string]: number }
  rowSelection: {
    [rowId: string]: boolean;  // Selected row IDs for CSV export
  };
  density: 'compact' | 'comfortable';  // Row height mode
}

/**
 * FilterState - Synced with URL and stored in localStorage
 * 
 * Manages user-applied filters for policy types and search query.
 * These are persisted in URL query params for shareable links.
 */
export interface FilterState {
  policyTypes: string[];      // ['deviceConfiguration', 'compliancePolicy']
  searchQuery: string;         // Text search in settingName/policyName
}

/**
 * TablePreferences - Persisted in localStorage
 * 
 * Stores user-specific table preferences across sessions.
 * Includes a version field for schema migrations when adding new features.
 */
export interface TablePreferences {
  version: 1;                  // Schema version for migrations
  columnVisibility: { [columnId: string]: boolean };
  columnSizing: { [columnId: string]: number };
  columnOrder: string[];       // Ordered column IDs for reordering
  density: 'compact' | 'comfortable';
  defaultPageSize: 10 | 25 | 50 | 100;
}

/**
 * PolicySettingRow - Row data shape for the table
 * 
 * Extends the base PolicySetting type with computed fields for display.
 */
export interface PolicySettingRow {
  id: string;
  tenantId: string;
  policyName: string;
  policyType: string;
  settingName: string;
  settingValue: string;
  graphPolicyId: string;
  lastSyncedAt: Date;
  createdAt: Date;
}

/**
 * PaginationMeta - Server response metadata
 * 
 * Returned by Server Actions to provide pagination state to the client.
 */
export interface PaginationMeta {
  totalCount: number;
  pageCount: number;
  currentPage: number;
  pageSize: number;
  hasNextPage: boolean;
  hasPreviousPage: boolean;
}

/**
 * GetPolicySettingsParams - Server Action input
 * 
 * Parameters for fetching policy settings with pagination, sorting, and filtering.
 */
export interface GetPolicySettingsParams {
  page: number;                // 0-based page index
  pageSize: 10 | 25 | 50 | 100;
  sortBy?: 'settingName' | 'policyName' | 'policyType' | 'lastSyncedAt';
  sortDir?: 'asc' | 'desc';
  policyTypes?: string[];
  searchQuery?: string;
}

/**
 * GetPolicySettingsResult - Server Action output
 * 
 * Response from Server Action with data and pagination metadata.
 */
export interface GetPolicySettingsResult {
  success: boolean;
  data?: PolicySettingRow[];
  meta?: PaginationMeta;
  error?: string;
}

/**
 * ExportPolicySettingsParams - Server Action input for CSV export
 * 
 * Parameters for server-side CSV generation (max 5000 rows).
 */
export interface ExportPolicySettingsParams {
  policyTypes?: string[];
  searchQuery?: string;
  sortBy?: 'settingName' | 'policyName' | 'policyType' | 'lastSyncedAt';
  sortDir?: 'asc' | 'desc';
  maxRows?: number;            // Default: 5000
}

/**
 * ExportPolicySettingsResult - Server Action output for CSV export
 * 
 * Returns CSV content as string with suggested filename.
 */
export interface ExportPolicySettingsResult {
  success: boolean;
  csv?: string;
  filename?: string;
  rowCount?: number;
  error?: string;
}