# Table Rendering & View Modes

# Table Rendering & View Modes

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [src/lib/components/entity-list-table/EntityListTable.css](src/lib/components/entity-list-table/EntityListTable.css)
- [src/lib/components/entity-list-table/EntityListTable.svelte](src/lib/components/entity-list-table/EntityListTable.svelte)
- [src/lib/components/entity-list-table/cards/CardField.svelte](src/lib/components/entity-list-table/cards/CardField.svelte)
- [src/lib/components/entity-list-table/cards/CardGrid.svelte](src/lib/components/entity-list-table/cards/CardGrid.svelte)
- [src/lib/components/entity-list-table/cards/CardList.svelte](src/lib/components/entity-list-table/cards/CardList.svelte)
- [src/lib/components/entity-list-table/components/CardActions.svelte](src/lib/components/entity-list-table/components/CardActions.svelte)
- [src/lib/components/entity-list-table/components/CardFieldRenderer.svelte](src/lib/components/entity-list-table/components/CardFieldRenderer.svelte)
- [src/lib/components/entity-list-table/components/CardViewRenderer.svelte](src/lib/components/entity-list-table/components/CardViewRenderer.svelte)
- [src/lib/components/entity-list-table/components/EntityListTableCardView.svelte](src/lib/components/entity-list-table/components/EntityListTableCardView.svelte)
- [src/lib/components/entity-list-table/components/EntityListTableContent.svelte](src/lib/components/entity-list-table/components/EntityListTableContent.svelte)
- [src/lib/components/entity-list-table/components/EntityListTableFooter.svelte](src/lib/components/entity-list-table/components/EntityListTableFooter.svelte)
- [src/lib/components/entity-list-table/components/EntityListTableTableView.svelte](src/lib/components/entity-list-table/components/EntityListTableTableView.svelte)
- [src/lib/components/entity-list-table/components/StateRenderer.svelte](src/lib/components/entity-list-table/components/StateRenderer.svelte)
- [src/lib/components/entity-list-table/components/TableBody.svelte](src/lib/components/entity-list-table/components/TableBody.svelte)
- [src/lib/components/entity-list-table/components/TableFooter.svelte](src/lib/components/entity-list-table/components/TableFooter.svelte)
- [src/lib/components/entity-list-table/components/TableHeader.svelte](src/lib/components/entity-list-table/components/TableHeader.svelte)
- [src/lib/components/entity-list-table/components/TableRow.svelte](src/lib/components/entity-list-table/components/TableRow.svelte)
- [src/lib/components/entity-list-table/composables/useColumnOrder.svelte.ts](src/lib/components/entity-list-table/composables/useColumnOrder.svelte.ts)
- [src/lib/components/entity-list-table/composables/useRowActions.svelte.ts](src/lib/components/entity-list-table/composables/useRowActions.svelte.ts)
- [src/lib/components/entity-list-table/composables/useRowRangeSelection.svelte.ts](src/lib/components/entity-list-table/composables/useRowRangeSelection.svelte.ts)
- [src/lib/components/entity-list-table/composables/useToolbarMode.svelte.ts](src/lib/components/entity-list-table/composables/useToolbarMode.svelte.ts)
- [src/lib/components/entity-list-table/composables/useViewMode.svelte.ts](src/lib/components/entity-list-table/composables/useViewMode.svelte.ts)
- [src/lib/components/entity-list-table/context.ts](src/lib/components/entity-list-table/context.ts)
- [src/lib/components/entity-list-table/panels/PreviewPanel.svelte](src/lib/components/entity-list-table/panels/PreviewPanel.svelte)
- [src/lib/components/entity-list-table/table/TableCell.svelte](src/lib/components/entity-list-table/table/TableCell.svelte)
- [src/lib/components/entity-list-table/table/TableHeader.svelte](src/lib/components/entity-list-table/table/TableHeader.svelte)
- [src/lib/components/entity-list-table/utils.ts](src/lib/components/entity-list-table/utils.ts)
- [src/lib/components/entity-list-table/utils/cell-styling.ts](src/lib/components/entity-list-table/utils/cell-styling.ts)
- [src/lib/components/ui/table/table-body.svelte](src/lib/components/ui/table/table-body.svelte)
- [src/lib/components/ui/table/table-caption.svelte](src/lib/components/ui/table/table-caption.svelte)
- [src/lib/components/ui/table/table-cell.svelte](src/lib/components/ui/table/table-cell.svelte)
- [src/lib/components/ui/table/table-footer.svelte](src/lib/components/ui/table/table-footer.svelte)
- [src/lib/components/ui/table/table-row.svelte](src/lib/components/ui/table/table-row.svelte)
- [tsconfig.json](tsconfig.json)

</details>



The `EntityListTable` system provides a flexible, high-performance grid for displaying and interacting with entity data. It supports three distinct view modes—Table, Card Grid, and Card List—and utilizes a composable architecture to manage complex states like sticky columns, row selection, and the preview panel.

## Overview of Rendering Architecture

The rendering logic is split into several layers to separate state management from UI presentation. `EntityListTable.svelte` acts as the orchestrator, while `EntityListTableContent` determines which view mode component to mount.

### Rendering Component Hierarchy

Title: EntityListTable Rendering Hierarchy
```mermaid
graph TD
    Root["EntityListTable.svelte"] --> Content["EntityListTableContent.svelte"]
    Content -->|"viewMode === 'table'"| TableView["EntityListTableTableView.svelte"]
    Content -->|"viewMode === 'cards' | 'cards_grid' | 'cards_list'"| CardView["EntityListTableCardView.svelte"]
    
    TableView --> THeader["EntityListTableHeaderRow.svelte"]
    TableView --> TBody["TableBody.svelte"]
    TBody --> TRow["TableRow.svelte"]
    TRow --> CellRen["CellRenderer.svelte"]
    CellRen --> TCell["TableCell.svelte"]
    
    CardView --> CardRen["CardViewRenderer.svelte"]
    CardRen --> CardList["CardList.svelte"]
    CardRen --> CardGrid["CardGrid.svelte"]
    CardList & CardGrid --> CardItem["CardItem.svelte"]
    CardItem --> CField["CardField.svelte"]
    CField --> TCell
```
**Sources:** 
- [src/lib/components/entity-list-table/EntityListTable.svelte:42-42]()
- [src/lib/components/entity-list-table/components/EntityListTableContent.svelte:1-30]()
- [src/lib/components/entity-list-table/components/TableBody.svelte:189-225]()
- [src/lib/components/entity-list-table/cards/CardField.svelte:77-82]()

## View Modes

The system supports multiple `ViewMode` types defined in the `useViewMode` composable.

| Mode | Identifier | Description |
| :--- | :--- | :--- |
| **Table** | `table` | Standard spreadsheet-like grid with sticky headers and columns. |
| **Card Grid** | `cards` / `cards_grid` | Responsive grid of cards, ideal for visual or summary data. |
| **Card List** | `cards_list` | Vertical stack of wide cards, useful for mobile or detail-heavy lists. |

### View Mode Selection
The `useViewMode` composable manages the active mode and persists it if configured. In `EntityListTableCardView.svelte`, the `CardViewRenderer` handles the specific layout logic for both grid and list card formats.

**Sources:**
- [src/lib/components/entity-list-table/composables/useViewMode.svelte.ts:1-20]()
- [src/lib/components/entity-list-table/components/CardViewRenderer.svelte:126-126]()

## Table View Implementation

The Table View uses standard HTML `<table>` elements wrapped in Shadcn-Svelte components. It is optimized for large datasets and complex interactions.

### TableBody & TableRow
`TableBody.svelte` iterates over `viewRows` and renders `TableRow.svelte` for each record. It also handles empty states, loading indicators, and error watermarks.
- **Row Selection:** Managed via `useRowRangeSelection` which allows shift-click and drag-to-select behavior [src/lib/components/entity-list-table/composables/useRowRangeSelection.svelte.ts:31-61]().
- **Double Click:** Triggers the preview panel for the specific row [src/lib/components/entity-list-table/components/TableRow.svelte:126-126]().

### Cell Rendering Pipeline
Cells are rendered through a multi-stage process to allow for custom snippets or standard formatting.
1. **CellRenderer.svelte:** A wrapper that checks if a custom `cell` snippet was provided via props [src/lib/components/entity-list-table/components/CellRenderer.svelte:1-20]().
2. **TableCell.svelte:** The default renderer. It handles:
    - **Booleans:** Renders `CircleCheck` or `CircleX` icons [src/lib/components/entity-list-table/table/TableCell.svelte:38-59]().
    - **Badges:** Maps values to colors using `badgeClassesFromToken` [src/lib/components/entity-list-table/table/TableCell.svelte:60-68]().
    - **Datetimes:** Formats dates based on the active IANA timezone mode (Browser vs Record) [src/lib/components/entity-list-table/table/TableCell.svelte:69-87]().
    - **Audit Fields:** Uses `getAuditFieldValue` for standard text display [src/lib/components/entity-list-table/table/TableCell.svelte:89-89]().

**Sources:**
- [src/lib/components/entity-list-table/components/TableBody.svelte:114-187]()
- [src/lib/components/entity-list-table/table/TableCell.svelte:36-90]()

## Card View Implementation

The Card View provides a non-tabular representation of data, utilizing `CardList` or `CardGrid`.

### CardField & CardFieldRenderer
Similar to `TableCell`, `CardField` is the atomic unit of the card view.
- It displays the column label [src/lib/components/entity-list-table/cards/CardField.svelte:55-55]().
- It handles "Empty" states by showing a `Ban` icon with a tooltip if the field contains no data [src/lib/components/entity-list-table/cards/CardField.svelte:57-73]().
- It delegates actual value rendering back to `TableCell` to ensure consistency between table and card modes [src/lib/components/entity-list-table/cards/CardField.svelte:77-82]().

**Sources:**
- [src/lib/components/entity-list-table/cards/CardList.svelte:81-149]()
- [src/lib/components/entity-list-table/cards/CardField.svelte:49-85]()

## Sticky Columns & Layout

The table supports sticky columns (usually for selection checkboxes and primary identifiers) and sticky headers.

### Implementation Detail
- **Sticky Offsets:** Calculated dynamically by the `useStickyColumns` composable.
- **CSS Classes:** Applied via `stickyCellClassWithCompute`. It adds `sticky z-30` and calculates the `left` CSS property based on the cumulative width of preceding sticky columns [src/lib/components/entity-list-table/utils/cell-styling.ts:1-50]().
- **Visual Feedback:** When scrolling, sticky cells apply specific border and shadow styles defined in `EntityListTable.css` to maintain separation from the scrolling content.

Title: Sticky Column Calculation Flow
```mermaid
sequenceDiagram
    participant U as useStickyColumns
    participant T as TableRow
    participant C as CSS/DOM
    
    T->>U: registerRef(columnKey, element)
    U->>U: Calculate cumulative widths
    U->>T: Return stickyLeftOffsets[columnKey]
    T->>C: Apply style="left: Xpx"
```

**Sources:**
- [src/lib/components/entity-list-table/components/TableRow.svelte:150-164]()
- [src/lib/components/entity-list-table/utils/cell-styling.ts:108-125]()
- [src/lib/components/entity-list-table/EntityListTable.css:1-100]()

## Row Actions & Preview

Each row (or card) can trigger actions or open a preview panel.

### useRowActions
This composable provides handlers for common entity operations:
- `handleEditRow`: Navigates to the edit form.
- `handleDeleteRow` / `handleRestoreRow`: Opens confirmation dialogs for soft-deletion [src/lib/components/entity-list-table/composables/useRowActions.svelte.ts:101-111]().
- `handleDuplicateRow`: Initiates the duplication flow [src/lib/components/entity-list-table/composables/useRowActions.svelte.ts:113-122]().

### PreviewPanel
Opened via `handlePreviewRow`, the `PreviewPanel` is a side-sheet that allows:
- **Quick Navigation:** Stepping through the list using "Next" and "Previous" buttons [src/lib/components/entity-list-table/panels/PreviewPanel.svelte:136-160]().
- **Mode Toggle:** Switching between a read-only view and an "Edit Mode" (if the entity supports it) [src/lib/components/entity-list-table/panels/PreviewPanel.svelte:163-178]().
- **Action Access:** Accessing the full row action menu (Delete, Duplicate, Version History) from within the preview [src/lib/components/entity-list-table/panels/PreviewPanel.svelte:181-200]().

**Sources:**
- [src/lib/components/entity-list-table/composables/useRowActions.svelte.ts:56-122]()
- [src/lib/components/entity-list-table/panels/PreviewPanel.svelte:63-120]()

---