Interactive Features

/**
 * Cell selection configuration and state
 */
interface CellSelection {
  /** Enable/disable cell selection */
  cell_selectable: boolean;
  
  /** Currently active cell coordinates */
  active_cell?: {
    row: number;
    column: number;
    row_id?: string | number;
    column_id: string;
  };
  
  /** Array of selected cells */
  selected_cells: Array<{
    row: number;
    column: number;
    row_id?: string | number;
    column_id: string;
  }>;
  
  /** Multi-selection start point */
  start_cell?: {
    row: number;
    column: number;
    row_id?: string | number;
    column_id: string;
  };
  
  /** Multi-selection end point */
  end_cell?: {
    row: number;
    column: number;
    row_id?: string | number;
    column_id: string;
  };
}

// Basic cell selection
DataTable(
  cell_selectable=True,  # Allow clicking and navigating cells
  # Selected cells accessible via selected_cells property
)

/**
 * Row selection modes and configuration
 */
interface RowSelection {
  /** Row selection mode */
  row_selectable: 'single' | 'multi' | false;
  
  /** Enable row deletion UI */
  row_deletable?: boolean;
  
  /** Selected row indices */
  selected_rows: number[];
  
  /** Selected row IDs (if data has id field) */
  selected_row_ids: Array<string | number>;
}

// Single row selection with deletion
DataTable(
  row_selectable="single",  # Radio buttons for single selection
  row_deletable=True,       # Show delete button (X) for each row
  selected_rows=[0]         # Initially select first row
)

// Multiple row selection
DataTable(
  row_selectable="multi",   # Checkboxes for multiple selection
  selected_rows=[0, 2, 3]   # Initially select multiple rows
)

/**
 * Column selection configuration
 */
interface ColumnSelection {
  /** Column selection mode */
  column_selectable: 'single' | 'multi' | false;
  
  /** Selected column IDs */
  selected_columns: string[];
}

// Column selection with header controls
DataTable(
  column_selectable="multi",           # Checkboxes in headers
  selected_columns=["name", "price"],  # Initially select specific columns
  # Derived properties show only selected columns in viewport
  # derived_viewport_selected_columns available
)

/**
 * Editing behavior configuration
 */
interface EditingConfig {
  /** Global editing capability */
  editable: boolean;
  
  /** Focus state of active cell */
  is_focused?: boolean;
  
  /** Include headers when copying */
  include_headers_on_copy_paste: boolean;
  
  /** Enable row deletion UI */
  row_deletable?: boolean;
  
  /** Merge duplicate adjacent headers */
  merge_duplicate_headers?: boolean;
}

// Enable editing with copy/paste headers
DataTable(
  editable=True,                           # Allow editing all cells
  include_headers_on_copy_paste=True,      # Include headers in clipboard ops
  row_deletable=True,                      # Show delete (X) button for each row
  merge_duplicate_headers=True,            # Merge adjacent headers with same name
  columns=[
    {"name": "Name", "id": "name", "editable": True},    # Editable column
    {"name": "ID", "id": "id", "editable": False}        # Read-only column
  ]
)

// Conditional editing based on data values
DataTable(
  columns=[
    {
      "name": "Status", 
      "id": "status", 
      "editable": True,
      "presentation": "dropdown"  # Use dropdown for editing
    },
    {
      "name": "Locked Field", 
      "id": "locked", 
      "editable": False  # Always read-only
    }
  ],
  # Column-level editable overrides table-level editable
  editable=True
)

/**
 * Filtering capabilities and configuration
 */
interface FilteringConfig {
  /** Filter processing mode */
  filter_action: 'native' | 'custom' | 'none' | {
    type: 'native' | 'custom';
    operator: 'and' | 'or';
  };
  
  /** Current filter query string */
  filter_query: string;
  
  /** Global filter options */
  filter_options?: {
    case: 'sensitive' | 'insensitive';
    placeholder_text: string;
  };
  
  /** Parsed filter query structure (read-only) */
  derived_filter_query_structure?: FilterQueryStructure | null;
}

/**
 * Structure representing parsed filter query as tree
 */
interface FilterQueryStructure {
  /** Node type */
  type: 'open-block' | 'logical-operator' | 'relational-operator' | 'unary-operator' | 'expression';
  
  /** Subtype specification */
  subType?: '()' | '&&' | '||' | '=' | '>=' | '>' | '<=' | '<' | '!=' | 'contains' | 
           '!' | 'is bool' | 'is even' | 'is nil' | 'is num' | 'is object' | 'is odd' | 'is prime' | 'is str' |
           'value' | 'field';
  
  /** Value for expression nodes */
  value?: any;
  
  /** Nested block structure */
  block?: FilterQueryStructure;
  
  /** Left operand */
  left?: FilterQueryStructure;
  
  /** Right operand */
  right?: FilterQueryStructure;
}

// Native filtering with case sensitivity
DataTable(
  filter_action="native",  # Built-in filtering logic
  filter_options={
    "case": "insensitive",           # Case-insensitive matching
    "placeholder_text": "Search..."  # Custom placeholder
  },
  # User typing updates filter_query automatically
)

// Advanced filtering with logical operators
DataTable(
  filter_action={
    "type": "native",
    "operator": "and"  # All conditions must match
  }
)

// Per-column filter customization
columns = [
  {
    "name": "Product", 
    "id": "product",
    "filter_options": {
      "case": "insensitive",
      "placeholder_text": "Filter products..."
    }
  },
  {
    "name": "Price", 
    "id": "price", 
    "type": "numeric"
    # Inherits table-level filter_options
  }
]

/**
 * Sorting capabilities and state
 */
interface SortingConfig {
  /** Sort processing mode */
  sort_action: 'native' | 'custom' | 'none';
  
  /** Single or multiple column sorting */
  sort_mode: 'single' | 'multi';
  
  /** Current sort configuration */
  sort_by: Array<{
    column_id: string;
    direction: 'asc' | 'desc';
  }>;
  
  /** Values treated as null when sorting */
  sort_as_null: Array<string | number | boolean>;
}

// Multi-column sorting
DataTable(
  sort_action="native",   # Built-in sorting logic
  sort_mode="multi",      # Allow sorting by multiple columns
  sort_by=[
    {"column_id": "category", "direction": "asc"},
    {"column_id": "price", "direction": "desc"}
  ],
  sort_as_null=["", "N/A", None]  # Treat these as null
)

// Custom null handling per column
columns = [
  {
    "name": "Rating", 
    "id": "rating", 
    "type": "numeric",
    "sort_as_null": [0, -1, "Not Rated"]  # Column-specific null values
  }
]

/**
 * Pagination behavior and state
 */
interface PaginationConfig {
  /** Pagination processing mode */
  page_action: 'native' | 'custom' | 'none';
  
  /** Current page index (0-based) */
  page_current: number;
  
  /** Total number of pages */
  page_count?: number;
  
  /** Rows per page */
  page_size: number;
}

// Native pagination with custom page size
DataTable(
  page_action="native",    # Built-in pagination logic
  page_size=25,           # 25 rows per page
  page_current=0          # Start on first page
)

// Custom pagination for large datasets
DataTable(
  page_action="custom",    # Handle pagination via callbacks
  page_count=100,         # Total pages known from backend
  page_size=50,
  # Use page_current in callbacks to fetch data
)

// Focus state tracking
DataTable(
  cell_selectable=True,
  # is_focused property indicates if active_cell is focused
  # Useful for keyboard navigation and styling
)

# Comprehensive interactive table
DataTable(
  id='interactive-demo',
  data=[
    {"id": 1, "name": "Alice", "department": "Sales", "salary": 50000, "active": True},
    {"id": 2, "name": "Bob", "department": "Engineering", "salary": 75000, "active": True},
    {"id": 3, "name": "Charlie", "department": "Marketing", "salary": 55000, "active": False}
  ],
  columns=[
    {"name": "ID", "id": "id", "type": "numeric", "editable": False},
    {"name": "Name", "id": "name", "type": "text", "editable": True},
    {"name": "Department", "id": "department", "type": "text", "presentation": "dropdown"},
    {"name": "Salary", "id": "salary", "type": "numeric", "format": {"specifier": "$,.0f"}},
    {"name": "Active", "id": "active", "type": "text", "presentation": "dropdown"}
  ],
  
  # Selection capabilities
  cell_selectable=True,
  row_selectable="multi",
  column_selectable="single",
  
  # Editing capabilities
  editable=True,
  include_headers_on_copy_paste=True,
  
  # Filtering
  filter_action="native",
  filter_options={"case": "insensitive"},
  
  # Sorting
  sort_action="native",
  sort_mode="multi",
  sort_by=[{"column_id": "department", "direction": "asc"}],
  
  # Pagination
  page_action="native",
  page_size=10
)