## Overview

Displays a list of search results.

The Table Widget is a next-generation table implementation that presents search results in a tabular format with modern web component architecture. It serves as both a primary data display component and a powerful data producer for connected widgets, supporting advanced features like multi-column sorting, dynamic filtering, and customizable column configurations.

**Status**: Preferred table widget for new implementations. Marked `@Beta` in the platform API (the interface may still evolve), but it does **not** require a runtime feature flag.

## Key Capabilities

- **Search-based data display**: Executes configured searches and displays results in a table format
- **Multi-producer architecture**: Acts as a data source for other widgets through three producer interfaces
  - Search results provider (ISearchProducer)
  - Single entity selection (ISingleEntitySelectionProducer)
  - Multi-entity selection (IMultiEntitySelectionProducer)
- **Advanced table features**: Multi-level sorting, column customization, filtering, and pinned columns
- **Connected widget support**: Establishes master-detail relationships with other widgets

## Use Cases

### Primary Data Display
**When to use**: Display search results in a structured, sortable table format

**Example scenarios**:
- All projects in a workspace with status and owner columns
- Team members with their roles, departments, and contact information
- Task lists with status, assignee, and due dates

**Why this widget**:
- Clean tabular organization of data
- Native sorting and filtering capabilities
- User-configurable column visibility and order

### Master Table in Master-Detail Pattern
**When to use**: One table drives the content of detail widgets on the same page

**Example scenario**: Project list table connected to:
- Project details widget (shows selected project attributes)
- Project team widget (shows team members of selected project)
- Project timeline widget (shows schedule of selected project)

**Why this widget**:
- Implements producer interfaces for single and multi-entity selection
- Emits selection events that connected widgets consume
- Enables coordinated page layouts with dynamic detail views

### Connected Table (Detail Table)
**When to use**: Table content depends on selection from another widget

**Example scenarios**:
- Task table showing tasks for a project selected in a project dropdown
- Team member table filtered by department selected in a department selector
- Issue table scoped to the component selected in a component list

**Why this widget**:
- Connects to selection producers via `CONNECTED_WIDGET_ID` configuration
- Automatically refreshes when connected widget selection changes
- Provides context-filtered views based on parent selections

### Search Result Provider
**When to use**: Provide search results to visualization widgets (charts, metrics)

**Example scenario**: Table showing filtered issues connected to:
- Pie chart showing issue distribution by status
- Bar chart showing issues by priority
- Number widget showing total count

**Why this widget**:
- Implements ISearchProducer interface for sharing search results
- Allows multiple widgets to visualize the same dataset
- Handles permissions and execution mode properly for consumers

### Multi-Column Sorted Lists
**When to use**: Complex sorting requirements with multiple sort criteria

**Example scenarios**:
- Employee list sorted by department (primary), then seniority (secondary), then name (tertiary)
- Product catalog sorted by category, then price, then rating

**Why this widget**:
- Supports `MULTI_SORT_COLUMNS` configuration for multi-level sorting
- Maintains sort order across refreshes
- Users can configure sorting priorities

### Filtered Data Views
**When to use**: Pre-configured filters need to be applied to displayed data

**Example scenarios**:
- "My Open Tasks" table with pre-filtered view showing user's assigned tasks
- "High Priority Issues" table showing only urgent items
- "This Month's Activities" with date range filter

**Why this widget**:
- Supports `FILTERS` configuration for pre-configured filtering
- Combines search definition with filter criteria
- Users can add additional filters on top of pre-configured ones

## Design Considerations

### When to Use This Widget

Use the Table Widget when:
- You need a modern, feature-rich table implementation
- You're building new pages requiring table functionality
- You need master-detail patterns with connected widgets
- You want to provide search results to multiple visualization widgets

### Prerequisites and Dependencies

**Required**:
- Valid search definition in configuration
- Widget must be embedded in a page

**Optional**:
- Connected widgets for producer/consumer patterns
- Column and filter configurations for customized views
- Multi-sort configuration for complex sorting

### Beta Status Considerations

The widget is marked with `@Beta` annotation, indicating:
- API may undergo changes in future releases
- Consider migration planning if replacing legacy table widgets

## Common Patterns

### Pattern 1: Standalone Table
Simple table displaying search results with optional customization:
- Configure search query
- Define visible columns
- Optionally add pre-configured filters
- Enable/disable "Create New" button
- Pin first column for horizontal scrolling

### Pattern 2: Master Table with Details
Table driving multiple detail widgets:
- Master table produces single entity selection
- Multiple detail widgets connect to the master table
- Each detail widget shows different aspects of selected entity
- Selection in master table updates all connected details

### Pattern 3: Table with Analytics
Table providing data to visualization widgets:
- Table widget executes search and produces results
- Multiple chart widgets connect to the table
- Each chart visualizes a different aspect of the data
- Metric widgets show aggregated statistics

### Pattern 4: Hierarchical Tables
Parent-child table relationship:
- Parent table (e.g., Departments) produces single selection
- Child table (e.g., Employees) connects to parent table
- Child table search is filtered by parent selection
- Changing parent selection updates child table content

## Comparison with Other Table Widgets

### vs. Embedded Search as Table (EMBEDDED_SEARCH_AS_TABLE) — This widget is preferred

**Table Widget advantages**:
- Modern web component architecture (vs. legacy AngularJS)
- Cleaner producer interface implementation
- Better separation of concerns in state management

**When to use Table Widget**:
- New implementations on modern infrastructure
- For new pages requiring table functionality

**When to use Embedded Search as Table**:
- Legacy pages still on AngularJS
- Existing implementations that don't need migration

The Table Widget is the preferred choice for new implementations. Embedded Search as Table is the legacy version — use it only for maintaining existing implementations.

## Related Widgets

- **Embedded Search as Table** (`cf.cplace.platform.embeddedSearchAsTable`): Legacy table widget, production-stable alternative
- **Single Attribute Widget**: Common detail widget for displaying attributes of selected entity
- **Attributes Group Widget**: Shows multiple attributes of connected entity selection
- **Chart widgets** (Pie, Bar, Line): Visualize data from table search results
- **Number of Results Widget**: Shows count metrics from table search results