Data Management

/**
 * Core data properties for table configuration
 */
interface DataTableProps {
  /** The contents of the table as array of objects */
  data: Array<Record<string, string | number | boolean>>;
  
  /** Column definitions with comprehensive configuration */
  columns: ColumnDefinition[];
  
  /** Previous state of data (read-only) */
  data_previous?: Array<Record<string, any>>;
  
  /** Unix timestamp when data was last edited */
  data_timestamp?: number;
}

/**
 * Column definition with all configuration options
 */
interface ColumnDefinition {
  /** Column identifier (required) */
  id: string;
  
  /** Display name (required, can be array for multi-header) */
  name: string | string[];
  
  /** Data type for validation and formatting */
  type?: 'any' | 'numeric' | 'text' | 'datetime';
  
  /** How to present the data */
  presentation?: 'input' | 'dropdown' | 'markdown';
  
  /** Column-level editability override */
  editable?: boolean;
  
  /** Column-specific filter options */
  filter_options?: FilterOptions;
  
  /** Formatting configuration */
  format?: FormatConfiguration;
  
  /** Validation and coercion behavior */
  on_change?: ChangeHandling;
  
  /** Values treated as null when sorting */
  sort_as_null?: Array<string | number | boolean>;
  
  /** Input validation rules */
  validation?: ValidationRules;
}

// Numeric column with validation
{
  "name": "Price", 
  "id": "price", 
  "type": "numeric",
  "validation": {
    "allow_null": false
  },
  "on_change": {
    "action": "coerce",
    "failure": "reject"
  }
}

// Text column with markdown support
{
  "name": "Description", 
  "id": "desc", 
  "type": "text",
  "presentation": "markdown"
}

// Datetime column with 2-digit year support
{
  "name": "Date", 
  "id": "date", 
  "type": "datetime",
  "validation": {
    "allow_YY": true
  }
}

/**
 * Column action configuration for interactive behavior
 */
interface ColumnActions {
  /** User can select the column */
  selectable?: boolean | 'first' | 'last' | boolean[];
  
  /** User can clear column data */
  clearable?: boolean | 'first' | 'last' | boolean[];
  
  /** User can delete the column */
  deletable?: boolean | 'first' | 'last' | boolean[];
  
  /** User can hide the column */
  hideable?: boolean | 'first' | 'last' | boolean[];
  
  /** User can rename the column */
  renamable?: boolean | 'first' | 'last' | boolean[];
}

// Example: Column with selective actions
{
  "name": "Revenue", 
  "id": "revenue", 
  "type": "numeric",
  "clearable": true,
  "hideable": true,
  "deletable": false,  // Prevent accidental deletion
  "selectable": "last"  // Show selector only on last header row
}

// Multi-level headers
columns = [
  {
    "name": ["Sales", "Q1"], 
    "id": "q1_sales", 
    "type": "numeric"
  },
  {
    "name": ["Sales", "Q2"], 
    "id": "q2_sales", 
    "type": "numeric"
  },
  {
    "name": ["Marketing", "Budget"], 
    "id": "marketing_budget", 
    "type": "numeric"
  }
]

// Control header merging
DataTable(
  columns=columns,
  merge_duplicate_headers=True  # Merge duplicate adjacent headers
)

/**
 * Configuration for user-initiated data modifications
 */
interface ChangeHandling {
  /** How to process data changes */
  action: 'coerce' | 'none' | 'validate';
  
  /** What to do if action fails */
  failure: 'accept' | 'default' | 'reject';
}

/**
 * Validation rules for data input
 */
interface ValidationRules {
  /** Allow null/undefined values */
  allow_null?: boolean;
  
  /** Default value when validation fails */
  default?: any;
  
  /** For datetime: allow 2-digit years */
  allow_YY?: boolean;
}

// Strict numeric validation
{
  "name": "Quantity", 
  "id": "qty", 
  "type": "numeric",
  "on_change": {
    "action": "validate",  // Strict validation
    "failure": "reject"    // Keep original value if invalid
  },
  "validation": {
    "allow_null": false,
    "default": 0
  }
}

// Lenient text processing with coercion
{
  "name": "Category", 
  "id": "category", 
  "type": "text",
  "on_change": {
    "action": "coerce",    // Try to convert to text
    "failure": "default"   // Use default if conversion fails
  },
  "validation": {
    "allow_null": true,
    "default": "Uncategorized"
  }
}

/**
 * Read-only properties providing current data state information
 */
interface DerivedDataState {
  /** Current page data after filtering/sorting */
  derived_viewport_data: Array<Record<string, any>>;
  
  /** Row indices for current page */
  derived_viewport_indices: number[];
  
  /** Row IDs for current page */
  derived_viewport_row_ids: Array<string | number>;
  
  /** All filtered/sorted data across pages */
  derived_virtual_data: Array<Record<string, any>>;
  
  /** All filtered/sorted row indices */
  derived_virtual_indices: number[];
  
  /** All filtered/sorted row IDs */
  derived_virtual_row_ids: Array<string | number>;
}

DataTable(
  columns=[
    {"name": "Name", "id": "name"},
    {"name": "Internal ID", "id": "internal_id", "hideable": True},
    {"name": "Status", "id": "status"}
  ],
  hidden_columns=["internal_id"],  # Initially hide internal ID column
  # User can show/hide via column actions
)

DataTable(
  id='complex-table',
  data=[
    {
      "id": 1,
      "product": "Widget A",
      "price": 29.99,
      "stock": 150,
      "category": "electronics",
      "last_updated": "2023-01-15 10:30:00",
      "active": True,
      "rating": 4.5
    }
  ],
  columns=[
    {
      "name": "Product ID", 
      "id": "id", 
      "type": "numeric",
      "editable": False  # Read-only ID
    },
    {
      "name": "Product Name", 
      "id": "product", 
      "type": "text",
      "editable": True,
      "validation": {"allow_null": False}
    },
    {
      "name": "Price ($)", 
      "id": "price", 
      "type": "numeric",
      "format": {"specifier": "$,.2f"},
      "on_change": {"action": "coerce", "failure": "reject"}
    },
    {
      "name": "Stock Level", 
      "id": "stock", 
      "type": "numeric",
      "validation": {"allow_null": False, "default": 0}
    },
    {
      "name": "Category", 
      "id": "category", 
      "type": "text",
      "presentation": "dropdown"
    },
    {
      "name": "Last Updated", 
      "id": "last_updated", 
      "type": "datetime",
      "editable": False
    },
    {
      "name": "Active", 
      "id": "active", 
      "type": "text",
      "presentation": "dropdown"
    },
    {
      "name": "Rating", 
      "id": "rating", 
      "type": "numeric",
      "format": {"specifier": ".1f"}
    }
  ],
  editable=True
)