@redsift/ds-mcp-server 12.3.1-muiv6-alpha.2

package/data/docs/llms.txt

@@ -0,0 +1,234 @@
+# Red Sift Design System
+
+> A React component library for Red Sift applications built with TypeScript and styled-components.
+
+## Overview
+
+The Red Sift Design System provides reusable UI components including forms, navigation, charts, tables, and data visualization components.
+
+- **Framework:** React 18 with TypeScript
+- **Styling:** styled-components 6.x
+- **Documentation:** https://design-system.redsift.io
+
+## Packages
+
+- **@redsift/design-system** (60 components): Core UI components (buttons, forms, navigation, layout)
+- **@redsift/popovers** (28 components): Popover, tooltip, dialog, and toast components
+- **@redsift/pickers** (21 components): Selection components (combobox, menu button, select)
+- **@redsift/charts** (32 components): D3.js-based chart components (bar, line, pie, scatter)
+- **@redsift/table** (8 components): DataGrid components built on MUI X Data Grid
+- **@redsift/dashboard** (16 components): Dashboard components with crossfilter integration
+- **@redsift/products** (7 components): Product-specific component implementations
+
+## Components
+
+### design-system
+
+- **ActiveDescendantListbox** (19 props)
+- **Alert** (7 props): Alert displays a short, important message that attracts the user's attention
+- **AppBar** (6 props): AppBar is the top navigation bar of the application. It displays the page title
+- **AppContainer** (5 props): The AppContainer component.
+- **AppContent** (11 props): AppContent is the main content area of a Red Sift application. It automatically
+- **AppSidePanel** (8 props): AppSidePanel is the collapsible side navigation panel of a Red Sift application.
+- **Badge** (5 props): Badge displays a small status indicator or count. Badges have two variants:
+- **BaseBreadcrumbs** (2 props): Breadcrumbs display a list of links to parent pages in hierarchical order,
+- **BaseGrid** (11 props): Grid provides a CSS Grid container for two-dimensional layouts with rows
+- **BaseSkeleton** (2 props): Skeleton displays a placeholder animation while content is loading.
+- **BreadcrumbItem** (4 props): BreadcrumbItem represents a single link in a Breadcrumbs navigation.
+- **Breadcrumbs** (2 props)
+- **Button** (12 props): The Button is a semantic button that looks like a button.
+- **ButtonGroup** (3 props): ButtonGroup combines multiple related buttons into a single visual unit.
+- **ButtonLink** (11 props): ButtonLink is a semantic link (`<a>`) styled to look like a button.
+- **Card** (5 props)
+- **CardActions** (10 props): CardActions is a container for action buttons at the bottom of a Card.
+- **CardBody** (10 props): CardBody is the main content area of a Card. It can contain any content.
+- **CardHeader** (6 props): CardHeader displays the title and optional subtitle of a Card.
+- **Checkbox** (15 props): Checkbox allows users to select one or more items from a set, or to mark an
+- **CheckboxGroup** (11 props): CheckboxGroup manages a group of related Checkbox components. It handles
+- **ConditionalWrapper** (3 props): ConditionalWrapper conditionally wraps children in a wrapper component.
+- **DetailedCard** (10 props)
+- **DetailedCardCollapsibleSectionItems** (2 props): The DetailedCardCollapsibleSectionItems Section component.
+- **DetailedCardHeader** (3 props): The DetailedCardHeader component.
+- **DetailedCardSection** (6 props): The DetailedCardSection component.
+- **DetailedCardSectionItem** (9 props): The DetailedCardSectionItems component.
+- **Flexbox** (19 props): Flexbox provides a CSS Flexbox container with convenient props for common
+- **FocusWithinGroup** (0 props): The FocusWithinGroup component.
+- **Grid** (22 props)
+- **GridItem** (9 props): GridItem is a child of Grid that can span multiple columns or rows.
+- **Heading** (9 props): Heading renders semantic HTML heading elements (h1-h6) with consistent styling.
+- **Icon** (8 props): Icon displays SVG icons from the Material Design Icons library or custom paths.
+- **IconButton** (9 props): IconButton is a button containing only an icon, without text.
+- **IconButtonLink** (13 props): IconButtonLink is a semantic link (`<a>`) styled to look like an icon button.
+- **Item** (22 props): The Item component.
+- **Link** (8 props): Link is a semantic link (`<a>`) styled as a text link. Use for internal
+- **LinkButton** (10 props): LinkButton is a semantic button (`<button>`) styled to look like a text link.
+- **Listbox** (20 props): Listbox displays a list of selectable options. Supports single or multiple
+- **Number** (33 props): Number formats and displays numeric values with locale-aware formatting.
+- **NumberField** (35 props): NumberField allows users to enter and adjust numeric values with increment
+- **Pill** (8 props): Pill displays a small piece of information as a colored label. Commonly used
+- **ProgressBar** (11 props): ProgressBar displays the progress of a task or operation as a horizontal bar.
+- **Radio** (14 props): Radio allows users to select exactly one option from a set. Typically used
+- **RadioGroup** (11 props): RadioGroup manages a group of Radio components, ensuring only one can be
+- **RenderedListboxItem** (1 props)
+- **RovingTabindexListbox** (19 props)
+- **Shield** (7 props): The Shield component.
+- **SideNavigationMenu** (14 props): SideNavigationMenu provides hierarchical navigation within the AppSidePanel.
+- **SideNavigationMenuBar** (8 props): The SideNavigationMenuBar component.
+- **SideNavigationMenuItem** (13 props): The SideNavigationMenuItem component.
+- **Skeleton** (2 props)
+- **SkeletonCircle** (2 props): The SkeletonCircle component.
+- **SkeletonText** (5 props): The SkeletonText component.
+- **Spinner** (6 props): Spinner displays a loading indicator for async operations.
+- **Switch** (14 props): Switch is a toggle control for binary options (on/off, enabled/disabled).
+- **SwitchGroup** (11 props): SwitchGroup manages a group of related Switch components. Provides a shared
+- **Text** (11 props): Text renders text content with consistent styling. By default renders a
+- **TextArea** (23 props): TextArea allows users to enter multi-line text. Supports auto-growing height,
+- **TextField** (26 props): TextField allows users to enter single-line text input. Supports validation,
+
+### popovers
+
+- **BaseDialog** (10 props): Dialog displays modal content that requires user attention or interaction.
+- **BaseDialogContent** (1 props): The DialogContent component.
+- **BasePopover** (15 props): Popover displays contextual content anchored to a trigger element.
+- **BaseToggletip** (17 props): Toggletip displays supplementary content toggled by click/tap.
+- **BaseTooltip** (11 props): Tooltip displays brief informational text on hover or focus.
+- **Button** (12 props)
+- **ButtonLink** (11 props)
+- **Dialog** (10 props)
+- **DialogContent** (1 props)
+- **DialogContentActions** (11 props): The DialogContentActions component.
+- **DialogContentBody** (11 props): The DialogContentBody component.
+- **DialogContentHeader** (7 props): The DialogContentHeader component.
+- **DialogTrigger** (0 props): The DialogTrigger component.
+- **IconButton** (9 props)
+- **IconButtonLink** (13 props)
+- **Link** (8 props)
+- **LinkButton** (10 props)
+- **Popover** (15 props)
+- **PopoverContent** (11 props): The PopoverContent component.
+- **PopoverTrigger** (0 props): The PopoverTrigger component.
+- **Toast** (4 props): Toast displays non-blocking feedback messages. Use with ToastContainer
+- **ToastContainer** (10 props): ToastContainer provides the root element for toast notifications.
+- **Toggletip** (17 props)
+- **ToggletipContent** (11 props): The ToggletipContent component.
+- **ToggletipTrigger** (0 props): The ToggletipTrigger component.
+- **Tooltip** (11 props)
+- **TooltipContent** (11 props): The TooltipContent component.
+- **TooltipTrigger** (0 props): The TooltipTrigger component.
+
+### pickers
+
+- **BaseCombobox** (31 props): Combobox combines a text input with a filterable dropdown list.
+- **BaseComboboxContent** (12 props): The ComboboxContent component.
+- **BaseMenuButton** (22 props): MenuButton displays a button that opens a menu of actions.
+- **BaseMenuButtonContent** (11 props): The MenuButtonContent component.
+- **BaseSelect** (24 props): Select allows users to choose a single option from a dropdown list.
+- **Combobox** (31 props)
+- **ComboboxContent** (12 props)
+- **ComboboxContentFooter** (10 props): The ComboboxContentFooter component.
+- **ComboboxContentHeader** (10 props): The ComboboxContentHeader component.
+- **ComboboxContentListbox** (13 props): The ComboboxContentListbox component.
+- **ComboboxTrigger** (6 props): The ComboboxTrigger component.
+- **Item** (22 props): The Item component.
+- **MenuButton** (22 props)
+- **MenuButtonContent** (11 props)
+- **MenuButtonContentFooter** (10 props): The MenuButtonContentFooter component.
+- **MenuButtonContentHeader** (10 props): The MenuButtonContentHeader component.
+- **MenuButtonContentMenu** (12 props): The MenuButtonContentMenu component.
+- **MenuButtonTrigger** (1 props): The MenuButtonTrigger component.
+- **Select** (24 props)
+- **SelectContent** (11 props): The SelectContent component.
+- **SelectTrigger** (2 props): The SelectTrigger component.
+
+### charts
+
+- **Arc** (19 props)
+- **Arcs** (10 props)
+- **Axis** (28 props)
+- **Bar** (26 props)
+- **BarChart** (54 props)
+- **BarChartBars** (1 props)
+- **BarChartGroupedTooltip** (0 props)
+- **BarChartOverlay** (3 props)
+- **BarChartSection** (9 props)
+- **BaseBarChart** (54 props): BarChart visualizes categorical data with rectangular bars.
+- **ChartContainerTitle** (26 props)
+- **DataPoint** (17 props)
+- **Dot** (20 props)
+- **EmptyBarChart** (54 props)
+- **EmptyLineChart** (44 props)
+- **EmptyPieChart** (50 props)
+- **EmptyScatterPlot** (49 props)
+- **Legend** (18 props)
+- **LegendItem** (13 props)
+- **Line** (6 props)
+- **LineChart** (44 props): LineChart displays trends over time or continuous data.
+- **LoadingBarChart** (54 props)
+- **LoadingLineChart** (44 props)
+- **LoadingPieChart** (50 props)
+- **LoadingScatterPlot** (49 props)
+- **PieChart** (50 props): PieChart displays proportional data as slices of a circle.
+- **RenderedLinearBarChart** (51 props)
+- **RenderedLineChart** (44 props)
+- **RenderedOrdinalBarChart** (54 props)
+- **RenderedPieChart** (50 props)
+- **RenderedScatterPlot** (49 props)
+- **ScatterPlot** (49 props): ScatterPlot displays relationships between two numeric variables.
+
+### table
+
+- **ControlledPagination** (0 props)
+- **DataGrid** (9 props): DataGrid displays tabular data with sorting, filtering, pagination, and row selection.
+- **GridToolbarFilterSemanticField** (7 props): The GridToolbarFilterSemanticField component.
+- **ServerSideControlledPagination** (0 props)
+- **StatefulDataGrid** (12 props): StatefulDataGrid extends DataGrid with automatic state persistence to localStorage.
+- **TextCell** (6 props): The Cell component.
+- **Toolbar** (15 props): ------
+- **ToolbarWrapper** (0 props)
+
+### dashboard
+
+- **ChartEmptyState** (4 props)
+- **Dashboard** (2 props): Dashboard provides a context for connected, filterable visualizations.
+- **DataCard** (2 props)
+- **DataCardBody** (10 props): DataCardBody is the main content area of a DataCard 。
+- **DataCardHeader** (3 props): DataCardHeader displays an icon and title that floats on top of
+- **DataCardListbox** (20 props): DataCardListbox is a styled Listbox for use inside a DataCard.
+- **DataRow** (9 props): DataRow displays a formatted number alongside a legend label.
+- **DrilldownItem** (7 props): DrilldownItem displays a numeric value with a legend label and an optional
+- **FilterableBarChart** (8 props)
+- **FilterableDataGrid** (8 props)
+- **FilterablePieChart** (8 props)
+- **FilterableScatterPlot** (8 props)
+- **PdfDocument** (6 props)
+- **PdfExportButton** (19 props)
+- **TimeSeriesBarChart** (17 props)
+- **WithFilters** (8 props)
+
+### products
+
+- **Dialog** (10 props): RadarDialog displays Radar AI interactions in a branded modal dialog.
+- **Dialog** (9 props)
+- **MenuButton** (22 props): The RadarMenuButton component.
+- **MenuButton** (21 props): The RadarSimpleMenuButton component.
+- **PulsedRadarImage** (0 props)
+- **RadarButton** (12 props): RadarButton is a pre-styled button for Radar AI features.
+- **RadarItem** (22 props): The RadarItem component.
+
+## Links
+
+- [Full Documentation](llms-full.txt): Complete component documentation with all props
+- [Components JSON](components.json): Machine-readable component data
+- [Patterns JSON](patterns.json): Machine-readable composition pattern data
+- [Storybook](https://design-system.redsift.io/storybook): Interactive component examples
+
+## Composition Patterns
+
+Proven component groupings for common UI scenarios, extracted from production applications.
+
+| Pattern | Components | Packages |
+|---------|-----------|----------|
+| Datagrid Page | DataGrid, TextCell, StatefulDataGrid, Pill, Button, Flexbox, Text, Badge | @redsift/table, @redsift/design-system, @mui/x-data-grid-pro |
+| Server Datagrid Page | DataGrid, TextCell, Pill, Button, Flexbox, Text, Badge, Icon, IconButtonLink | @redsift/table, @redsift/design-system, @mui/x-data-grid-pro |
+
+For detailed pattern documentation with demos, visit: https://design-system.redsift.io/patterns/

package/data/docs/patterns-catalog.md

@@ -0,0 +1,359 @@
+# Composition Patterns
+
+Page-level UI patterns observed across Red Sift product applications (OnDMARC, Brand Trust, Certificates).
+Each pattern documents which Design System components to combine and how to lay them out to build a complete page.
+These patterns serve as implementation specs — they give LLMs and developers everything needed to build a page from scratch.
+
+---
+
+## Datagrid Page
+
+**When to use:**
+
+- You need a filterable, sortable, paginated table of records
+- The full dataset can be loaded upfront (typically under ~1,000 rows)
+- All filtering, sorting, and pagination can happen client-side in the browser
+- You want built-in column visibility, density, export, and quick search with zero backend work
+- You need optional bulk selection with contextual action buttons
+
+**When NOT to use:**
+
+- The dataset has thousands or millions of rows — use **Server Datagrid Page** instead
+- Sorting or filtering logic must live on the backend — use **Server Datagrid Page** instead
+
+**Anatomy:**
+
+1. Toolbar — Flexbox wrapping GridToolbarContainer with filter, columns, density, export, quick search controls
+2. DataGrid — the table itself, configured with autoHeight, pagination, checkboxSelection, and GridColDef[] columns
+3. Bulk Action Bar — Flexbox row shown when selectionModel.length > 0, with Pill (count) and action Buttons
+
+**Key imports:** `DataGrid`, `TextCell`, `StatefulDataGrid` from `@redsift/table`; `GridColDef`, `GridFilterModel`, `GridRowSelectionModel` from `@mui/x-data-grid-pro`; `Pill`, `Button`, `Flexbox` from `@redsift/design-system`
+**Components:** DataGrid, TextCell, StatefulDataGrid (from @redsift/table), Flexbox, Button, Pill, Text, Badge, Icon, IconButton, IconButtonLink (from @redsift/design-system)
+**Layout:** DataGrid with `autoHeight`, `pagination`, `pageSize`, built-in Toolbar (Columns | Filters | Density | Export | Search via `componentsProps.toolbar.showQuickFilter`). Columns use `GridColDef[]` with `type: 'rsString'` / `'rsNumber'` / `'rsSingleSelect'`, `renderCell` returning `TextCell`, `Pill`, `Badge`. Optional bulk actions bar above grid shown when `selectionModel.length > 0`.
+
+**Features:**
+
+| Feature               | Required | Description                                                                                         |
+| --------------------- | -------- | --------------------------------------------------------------------------------------------------- |
+| Column definitions    | Yes      | GridColDef[] with custom types: rsString, rsNumber, rsSingleSelect, rsMultipleSelect, boolean, date |
+| Toolbar               | Yes      | Built-in toolbar with filter, columns, density, export, and quick search controls                   |
+| Pagination            | Yes      | Client-side pagination with configurable page size                                                  |
+| Sorting               | Yes      | Client-side column sorting                                                                          |
+| Filtering             | Yes      | Client-side column filtering                                                                        |
+| Custom cell renderers | Yes      | renderCell returning TextCell, Pill, Icon, IconButtonLink                                           |
+| Checkbox selection    | No       | checkboxSelection + rowSelectionModel + onRowSelectionModelChange                                   |
+| Bulk action bar       | No       | Contextual buttons shown when rows are selected                                                     |
+| Actions column        | No       | Column with IconButtonLink for row-level navigation                                                 |
+| Quick search          | No       | GridToolbarQuickFilter for text search across all columns                                           |
+
+**Data Contract:**
+
+```tsx
+type Row = {
+  id: string;
+  label: string;
+  active: boolean;
+  status: 'active' | 'warning' | 'critical' | 'expired';
+  category: string;
+  score: number;
+  expiry: string;
+  tags: string[];
+};
+```
+
+**Implementation Checklist:**
+
+1. Define your row type — Create a TypeScript type Row. Every row must have a unique id field.
+2. Define column definitions — Create a GridColDef[] array with RS custom column types. Add renderCell for rich content.
+3. Create the toolbar — Build a CustomToolbar using GridToolbarContainer.
+4. Set up state — Add useState<GridSelectionModel>([]) for checkbox selection.
+5. Render the DataGrid — Pass rows, columns, autoHeight, pagination, pageSize, rowsPerPageOptions, checkboxSelection.
+6. Add bulk action bar — Conditionally render when selectionModel.length > 0.
+7. Handle edge cases — Add loading, empty, and error states.
+8. Verify — Test pagination breakpoints, filter operators, column visibility, density, and export.
+
+**Variants:** Loading State, Empty State, Error State
+**Related:** Server Datagrid Page — use when data is too large or filtering must be server-side
+**Demo:** [Datagrid Page](/patterns/datagrid-page)
+
+---
+
+## Server Datagrid Page
+
+**When to use:**
+
+- The dataset has thousands or millions of records that cannot be loaded into the browser
+- Filtering, sorting, or pagination logic must live on the backend (ElasticSearch, SQL, API)
+- You need the server to return the total matching count alongside the current page of results
+- Filter changes should be debounced to avoid excessive requests during rapid typing
+
+**When NOT to use:**
+
+- The dataset is small enough to load entirely (under ~1,000 rows) — use **Datagrid Page** instead
+- All data is available upfront and filtering can happen in the browser — use **Datagrid Page** instead
+
+**Anatomy:**
+
+1. Toolbar — Flexbox wrapping GridToolbarContainer with filter, columns, density, export, quick search controls
+2. DataGrid — the table configured with paginationMode='server', sortingMode='server', filterMode='server', loading, and rowCount
+3. Bulk Action Bar — Flexbox row shown when selectionModel.length > 0, with Pill (count) and action Buttons
+
+**Key imports:** `DataGrid`, `TextCell` from `@redsift/table`; `GridColDef`, `GridFilterModel`, `GridSortModel`, `GridSelectionModel` from `@mui/x-data-grid-pro`; `Pill`, `Button`, `Flexbox`, `Icon`, `IconButtonLink` from `@redsift/design-system`
+**Components:** DataGrid, TextCell (from @redsift/table), Flexbox, Button, Pill, Text, Badge, Icon, IconButton, IconButtonLink (from @redsift/design-system)
+**Layout:** DataGrid with `autoHeight`, `paginationMode="server"`, `sortingMode="server"`, `filterMode="server"`, `rowCount`, `loading`, built-in Toolbar (Columns | Filters | Density | Export | Search). Same column types as Datagrid Page.
+
+**Features:**
+
+| Feature                  | Required | Description                                                              |
+| ------------------------ | -------- | ------------------------------------------------------------------------ |
+| Server-side pagination   | Yes      | paginationMode='server' with controlled page, pageSize, rowCount         |
+| Server-side sorting      | Yes      | sortingMode='server' with controlled sortModel + onSortModelChange       |
+| Server-side filtering    | Yes      | filterMode='server' with controlled filterModel + onFilterModelChange    |
+| Loading overlay          | Yes      | loading prop set to true during fetches                                  |
+| Row count                | Yes      | rowCount prop set to total matching records from server response         |
+| Debounced filter changes | Yes      | 300ms debounce on onFilterModelChange                                    |
+| Column definitions       | Yes      | GridColDef[] with custom types                                           |
+| Toolbar                  | Yes      | Built-in toolbar with filter, columns, density, export, and quick search |
+| Custom cell renderers    | Yes      | renderCell returning TextCell, Pill, Icon, IconButtonLink                |
+| Checkbox selection       | No       | checkboxSelection + rowSelectionModel                                    |
+| Bulk action bar          | No       | Contextual buttons shown when rows are selected                          |
+| Quick search             | No       | GridToolbarQuickFilter with server-side text search                      |
+
+**State Hooks:**
+
+| Hook            | Type                                  | Initial       | Description                                |
+| --------------- | ------------------------------------- | ------------- | ------------------------------------------ |
+| rows            | Row[]                                 | []            | Rows returned from server for current page |
+| totalRows       | number                                | 0             | Total matching records                     |
+| loading         | boolean                               | true          | Whether a fetch is in progress             |
+| page            | number                                | 0             | 0-based current page index                 |
+| pageSize        | number                                | 10            | Rows per page                              |
+| sortModel       | GridSortModel                         | []            | Current sort configuration                 |
+| filterModel     | GridFilterModel                       | { items: [] } | Current filter configuration               |
+| selectionModel  | GridSelectionModel                    | []            | Checked rows                               |
+| quickFilterText | string                                | ''            | Quick search text                          |
+| debounceRef     | useRef<ReturnType<typeof setTimeout>> | undefined     | Debounce timer ref                         |
+
+**Data Contract:**
+
+```tsx
+type Row = {
+  id: string;
+  label: string;
+  active: boolean;
+  status: 'active' | 'warning' | 'critical' | 'expired';
+  category: string;
+  score: number;
+  expiry: string;
+  tags: string[];
+};
+
+type FetchParams = {
+  page: number;
+  pageSize: number;
+  sortModel: GridSortModel;
+  filterModel: GridFilterModel;
+  quickFilterText: string;
+};
+
+type FetchResult = {
+  rows: Row[];
+  totalRows: number;
+};
+```
+
+**Implementation Checklist:**
+
+1. Define your row type. Every row must have a unique id field.
+2. Create your fetch function — implement async FetchParams → FetchResult. If using React Query, wrap in useQuery.
+3. Define column definitions with RS custom column types. Add renderCell for rich content.
+4. Create the toolbar using GridToolbarContainer.
+5. Set up all state hooks: rows, totalRows, loading, page, pageSize, sortModel, filterModel, selectionModel, quickFilterText, debounce ref.
+6. Wire the fetch effect — useEffect triggers on page, pageSize, sortModel, filterModel, quickFilterText changes.
+7. Configure the DataGrid with paginationMode='server', sortingMode='server', filterMode='server', loading, rowCount.
+8. Debounce filter changes — 300ms setTimeout in onFilterModelChange. Reset to page 0 on filter change.
+9. Add bulk action bar — conditionally render when selectionModel.length > 0.
+10. Handle edge cases — loading, empty (custom NoRowsOverlay), and error states.
+11. Verify — Test page navigation, sort toggling, filter operators, debounce, loading overlay, empty results, error recovery.
+
+**Key props:** `paginationMode="server"` + `page` + `pageSize` + `onPageChange` + `onPageSizeChange` + `rowCount` for pagination. `sortingMode="server"` + `sortModel` + `onSortModelChange` for sorting. `filterMode="server"` + `filterModel` + `onFilterModelChange` for filtering. `loading` for the built-in loading overlay during fetches. Filter changes should be debounced (~300ms) to avoid excessive requests.
+**Mock server pattern:** A self-contained `fakeFetch` function simulates a 400ms network round-trip. It receives `{ page, pageSize, sortModel, filterModel }`, applies filtering (string, number, date, single-select, multi-select, boolean operators), sorting, and pagination server-side, then returns `{ rows, totalRows }`.
+**Variants:** Loading State, Empty State, Error State
+**Related:** Datagrid Page — use when all data can be loaded upfront and filtering/sorting can happen client-side
+**Demo:** [Server Datagrid Page](/patterns/server-datagrid-page)
+
+---
+
+## Drilldown Datagrid Page
+
+**When to use:**
+
+- You want summary KPI cards above a filterable table
+- Clicking a card value should add a filter to the datagrid as a convenience shortcut
+- DataCard counts should always show totals from the full dataset, regardless of active filters
+- The dataset is small enough to load entirely (under ~1,000 rows)
+
+**When NOT to use:**
+
+- DataCard counts should recalculate when filters change — use **Cross-filtered Datagrid Page** instead
+- No summary cards are needed — use **Datagrid Page** instead
+- The dataset is too large to load entirely — combine with **Server Datagrid Page** patterns
+
+**Anatomy:**
+
+1. DataCard Row — Flexbox with 1-N DataCards, each containing DataCard.Header and DataCard.Listbox or DataCard.Body with DrilldownItem children
+2. Toolbar — Flexbox wrapping GridToolbarContainer with filter, columns, density, export, quick search controls
+3. DataGrid — the table with controlled filterModel + onFilterModelChange
+4. Bulk Action Bar — Flexbox row shown when selectionModel.length > 0, with Pill (count) and action Buttons
+
+**Key imports:** `DataGrid`, `TextCell` from `@redsift/table`; `DataCard`, `DrilldownItem` from `@redsift/dashboard`; `GridColDef`, `GridFilterModel` from `@mui/x-data-grid-pro`; `Pill`, `Button`, `Flexbox`, `Icon` from `@redsift/design-system`
+**Components:** DataGrid, TextCell (from @redsift/table), DataCard, DataCard.Header, DataCard.Body, DataCard.Listbox, DrilldownItem (from @redsift/dashboard), Flexbox, Button, Pill, Text, Icon, IconButtonLink (from @redsift/design-system)
+**Layout:** Flexbox column: DataCard row (Flexbox gap=12px flexWrap=wrap with 1-N DataCards), then DataGrid with autoHeight, pagination, controlled filterModel + onFilterModelChange. Optional bulk actions bar.
+
+**Features:**
+
+| Feature                   | Required | Description                                                                      |
+| ------------------------- | -------- | -------------------------------------------------------------------------------- |
+| DataCard aggregation      | Yes      | DataCard components showing aggregate counts per field from the full dataset     |
+| DrilldownItem filter push | Yes      | Clicking a DrilldownItem adds an isAnyOf filter to the DataGrid filterModel      |
+| Listbox multi-select      | Yes      | DataCard.Listbox with selectionMode=multiple and controlled values               |
+| is/isNot clearing         | Yes      | When filter panel has is/isNot for a card's field, the DataCard selection clears |
+| Column definitions        | Yes      | GridColDef[] with custom types                                                   |
+| Toolbar                   | Yes      | Built-in toolbar with filter, columns, density, export, and quick search         |
+| Custom cell renderers     | Yes      | renderCell returning TextCell, Pill, Icon, IconButtonLink                        |
+| Boolean toggle            | No       | DataCard.Body with DrilldownItem onClick for boolean fields                      |
+| Checkbox selection        | No       | checkboxSelection + rowSelectionModel                                            |
+| Bulk action bar           | No       | Contextual buttons shown when rows are selected                                  |
+
+**Filter helpers:**
+
+- `getSelectedFromFilterModel(filterModel, fieldName)` — reads isAnyOf values, returns [] for is/isNot operators
+- `updateFilterModel(filterModel, fieldName, values)` — always writes isAnyOf, removes when empty. Never preserves incompatible operators.
+- `updateBooleanFilter(filterModel, fieldName, value)` — uses 'is' operator with 'true'/'false' for boolean fields
+
+**Data Contract:**
+
+```tsx
+type Row = {
+  id: string;
+  label: string;
+  active: boolean;
+  status: 'active' | 'warning' | 'critical' | 'expired' | 'revoked';
+  category: 'primary' | 'secondary' | 'tertiary';
+  score: number;
+  expiry: string;
+  tags: string[];
+};
+
+type AggregateCounts = {
+  status: Record<string, number>;
+  category: Record<string, number>;
+  activeCount: number;
+  inactiveCount: number;
+};
+```
+
+**Implementation Checklist:**
+
+1. Define your row type — every row must have a unique id field.
+2. Compute aggregate counts — useAggregateCounts(allRows) counts from the full dataset.
+3. Build DataCards with DataCard.Header, DataCard.Listbox (multi-select) or DataCard.Body (boolean toggle) containing DrilldownItem children.
+4. Write filter helpers — getSelectedFromFilterModel and updateFilterModel.
+5. Wire DataCard handlers — onChange to updateFilterModel, onClick to updateBooleanFilter.
+6. Render the DataGrid with controlled filterModel and onFilterModelChange.
+7. Handle edge cases — loading, empty, and error states for both DataCards and DataGrid.
+
+**Variants:** Loading State, Empty State, Error State
+**Related:** Cross-filtered Datagrid Page — use when DataCard counts should recalculate as filters change; Datagrid Page — use when no summary cards are needed; Server Datagrid Page — use when data is too large
+**Demo:** [Drilldown Datagrid Page](/patterns/drilldown-datagrid-page)
+
+---
+
+## Cross-filtered Datagrid Page
+
+**When to use:**
+
+- You want dashboard-style KPI cards that stay in sync with the table below
+- DataCard counts should recalculate as filters change — reflecting the current filter context
+- Clicking a card value should add a filter to the datagrid (bidirectional)
+- Changing the filter panel should update the card selection
+- The dataset is small enough to load entirely (under ~1,000 rows)
+
+**When NOT to use:**
+
+- DataCard counts should always show full-dataset totals — use **Drilldown Datagrid Page** instead
+- No summary cards are needed — use **Datagrid Page** instead
+- The dataset is too large to load entirely — combine with **Server Datagrid Page** patterns
+
+**Anatomy:**
+
+1. DataCard Row — Flexbox with 1-N DataCards. Counts are cross-filtered: each card excludes its own field from the filter calculation
+2. Toolbar — Flexbox wrapping GridToolbarContainer with filter, columns, density, export, quick search controls
+3. DataGrid — the table with controlled filterModel + onFilterModelChange. Rows are pre-filtered client-side
+4. Bulk Action Bar — Flexbox row shown when selectionModel.length > 0, with Pill (count) and action Buttons
+
+**Key imports:** `DataGrid`, `TextCell` from `@redsift/table`; `DataCard`, `DrilldownItem` from `@redsift/dashboard`; `GridColDef`, `GridFilterModel` from `@mui/x-data-grid-pro`; `Pill`, `Button`, `Flexbox`, `Icon` from `@redsift/design-system`
+**Components:** DataGrid, TextCell (from @redsift/table), DataCard, DataCard.Header, DataCard.Body, DataCard.Listbox, DrilldownItem (from @redsift/dashboard), Flexbox, Button, Pill, Text, Icon, IconButtonLink (from @redsift/design-system)
+**Layout:** Flexbox column: DataCard row (cross-filtered counts), then DataGrid with autoHeight, pagination, controlled filterModel + onFilterModelChange. Rows are pre-filtered client-side via applyFilters. Optional bulk actions bar.
+
+**Features:**
+
+| Feature                    | Required | Description                                                                      |
+| -------------------------- | -------- | -------------------------------------------------------------------------------- |
+| Cross-filtered aggregation | Yes      | DataCard counts recompute from rows filtered by all fields except the card's own |
+| Two-way filter sync        | Yes      | DataCard selections derive from filterModel; DataCard clicks update filterModel  |
+| DrilldownItem filter push  | Yes      | Clicking a DrilldownItem adds an isAnyOf filter to the DataGrid filterModel      |
+| Listbox multi-select       | Yes      | DataCard.Listbox with selectionMode=multiple and controlled values               |
+| is/isNot clearing          | Yes      | When filter panel has is/isNot for a card's field, the DataCard selection clears |
+| Client-side row filtering  | Yes      | applyFilters function filters the full row set by the current filterModel        |
+| Column definitions         | Yes      | GridColDef[] with custom types                                                   |
+| Toolbar                    | Yes      | Built-in toolbar with filter, columns, density, export, and quick search         |
+| Custom cell renderers      | Yes      | renderCell returning TextCell, Pill, Icon, IconButtonLink                        |
+| Boolean toggle             | No       | DataCard.Body with DrilldownItem onClick for boolean fields                      |
+| Checkbox selection         | No       | checkboxSelection + rowSelectionModel                                            |
+| Bulk action bar            | No       | Contextual buttons shown when rows are selected                                  |
+
+**Cross-filtering logic:**
+
+- `applyFilters(rows, filterModel, excludeField?)` — filters rows. When `excludeField` is provided, skips filters for that field.
+- Each DataCard computes its counts via `computeCounts(applyFilters(allRows, filterModel, cardField))` — so the Status card excludes status filters, etc.
+- DataGrid rows use `applyFilters(allRows, filterModel)` without exclusion — all filters applied.
+- Same `getSelectedFromFilterModel` / `updateFilterModel` / `updateBooleanFilter` helpers as Drilldown Datagrid Page.
+
+**Data Contract:**
+
+```tsx
+type Row = {
+  id: string;
+  label: string;
+  active: boolean;
+  status: 'active' | 'warning' | 'critical' | 'expired' | 'revoked';
+  category: 'primary' | 'secondary' | 'tertiary';
+  score: number;
+  expiry: string;
+  tags: string[];
+};
+
+type AggregateCounts = {
+  status: Record<string, number>;
+  category: Record<string, number>;
+  activeCount: number;
+  inactiveCount: number;
+};
+```
+
+**Implementation Checklist:**
+
+1. Define your row type — every row must have a unique id field.
+2. Write the applyFilters function — supports isAnyOf, is, isNot. Accepts optional excludeField parameter.
+3. Write computeCounts — accepts a row array, returns aggregate counts per field value.
+4. Write filter helpers — getSelectedFromFilterModel and updateFilterModel.
+5. Compute cross-filtered counts — for each DataCard, call computeCounts(applyFilters(allRows, filterModel, cardField)).
+6. Compute filtered rows for DataGrid — applyFilters(allRows, filterModel) without excluding any field.
+7. Build DataCards with controlled values derived from filterModel.
+8. Render the DataGrid with rows={filteredRows}, controlled filterModel and onFilterModelChange.
+9. Handle edge cases — loading, empty, and error states.
+
+**Variants:** Loading State, Empty State, Error State
+**Related:** Drilldown Datagrid Page — use when DataCard counts should always show full-dataset totals; Datagrid Page — use when no summary cards are needed; Server Datagrid Page — use when data is too large
+**Demo:** [Cross-filtered Datagrid Page](/patterns/crossfiltered-datagrid-page)