# React components
> Here is a list of all the react components in the project use the story link to get the documentation for the individual component.
the md for each component is in markdown and describes when to use the component.

## Docs for each component


- [FilterBar](/ai?storyId=components-filter-bar-filterbar):
```md
FilterBar renders a horizontal bar of user-configurable filters. Each filter is defined via a `FilterBarDefinition`
record (mapping filter keys to filter definitions such as checkbox, radio, date range, or min/max), and the bar's
state is managed by the `useFilterBar` hook which returns the required `filterBarConfig` and `filterBarDefinition` props.

Filters can be grouped into categories, starred for quick access, shown directly in the bar, or hidden programmatically.
Filter state is automatically persisted to local storage.

### When to use
Use FilterBar when a page needs user-driven filtering over a data set — for example, filtering an asset list by brand, model, status, or date range.

### When not to use
Do not use FilterBar for a single search input — use `Search`.
Do not use FilterBar for sorting controls — use the `Table` component's built-in sort functionality. 
```

- [BarChart](/ai?storyId=components-charts-barchart):
```md
Create a BarChart with automatic legends and formatting. Built on top of the Chart component
with sensible defaults for displaying categorical or time-series data.

All customization props are optional and default to the component's original rendering, so
existing usages are unaffected.

### When to use
- To compare values across categories
- To show trends over time with discrete intervals
- When you need multiple series displayed side by side 
```

- [Chart](/ai?storyId=components-charts-chart):
```md
The Chart component is a wrapper component for ECharts, providing a simplified API for rendering interactive charts.
It handles loading states, event callbacks, and timezone labels out of the box.

### When to use
- When you need full control over ECharts configuration options
- For custom or complex chart types not covered by specialized components (BarChart, DonutChart)

### When not to use
- For standard bar or donut charts, use the dedicated BarChart or DonutChart components 
```

- [DonutChart](/ai?storyId=components-charts-donutchart):
```md
Create a DonutChart with interactive legends. Shows proportional data with a center total
and hover-to-highlight interactions between chart segments and legend items.

### When to use
- To show parts of a whole (percentages, distributions)
- When you have a limited number of categories (ideally 6 or fewer)
- To display summary metrics with categorical breakdowns

### When not to use
- For comparing values across many categories (use BarChart)
- For time-series data (use line or bar charts) 
```


- [Alert](/ai?storyId=components-alert):
```md
The Alert component should be used to inform the user of important information such as errors, warnings, success messages, or informational notices.

### When to use
Use alerts to communicate important information that requires user attention, such as form validation errors, action confirmations, or system status updates.

### When not to use
Do not use alerts for non-critical information or marketing messages. Use Notice component for less urgent communications. 
```

- [Badge](/ai?storyId=components-badge):
```md
Badge displays a numeric count or a small colored dot to indicate notifications or applied elements.
It is typically placed on buttons, tabs, or filters to draw attention to new or pending items.

### When to use
Use Badge to indicate a count (e.g., unread notifications, active filters) or as a compact status dot.

### When not to use
Do not use Badge for labeling statuses or categories — use `Tag` instead.
Do not use Badge for highlighting data values — use `Highlight`.

How to choose between Badge and `Tag`?
- Use a Badge to indicate notifications or counts of applied elements.
- Use a `Tag` for labeling statuses, categories, or selections. 
```

- [Breadcrumb](/ai?storyId=components-breadcrumb):
```md
The breadcrumb component shows a user's location in a website or application. Breadcrumbs are particularly useful when a large amount of content is organized in a hierarchical manner. They streamline navigation, minimize the steps required to revisit previous pages, and offer contextual insights to the users.

All items except the last are rendered as clickable links. The last item is rendered as plain text representing the current page.
The component automatically adapts to the screen size: on large screens all items are visible, on medium screens middle items collapse behind an ellipsis button, and on small screens only the current page is shown.

### When to use
Use breadcrumbs when deep navigation is available, on apps or pages where users might dive into content and could benefit from a quick way to return to higher levels. Breadcrumbs display the current screen as the final item in the list to make it clear where the user is.

### When not to use
Do not use on the first hierarchal level, such as a home page or a main page, as there is no previous step the user can get to.
Avoid using breadcrumbs to indicate forthcoming steps. For processes with sequential steps, use a wizard flow instead. 
```

- [Card](/ai?storyId=components-cards-card):
```md
The Card component is a container for UI elements that groups related content together with a visual boundary.
To get the most out of the Card, use it in combination with the CardHeader, CardBody and CardFooter.

### When to use
Use cards to group related information and actions, such as in dashboards, list items, or content previews.

### When not to use
Do not use cards for layout purposes only. Use standard containers or grid layouts instead. 
```

- [Collapse](/ai?storyId=components-collapse):
```md
The Collapse component is a container for additional information that adds context to various flows. It is used for displaying non-essential information that can be hidden away.

### When to use
- To keep content off the screen to shorten pages and reduce scrolling, while it's still only a tap away. Remember that the users might choose not to interact with the component and won't see the information within.
- To display additional details that are not essential or necessary in the main flow/page.

### When not to use

- For explanations connected to individual elements, use a tooltip instead.
- For important content that the user needs to see at a glance or a primary action to be taken on the page.
- To hide errors or information that is relevant for a user within a flow.
- To creating hierarchy levels by nesting them within each other. 
```




- [EmptyValue](/ai?storyId=components-tables-cells-emptyvalue):
```md
EmptyValue renders a consistent dash symbol ("–") to represent missing, null, undefined, or not applicable values.
It is primarily used in tables and detail lists to maintain visual consistency when data is absent.

### When to use
Use EmptyValue as a placeholder in table cells, detail lists, or any data display where values may be missing.

### When not to use
Do not use EmptyValue for empty pages or sections — use `EmptyState` instead. 
```


- [Heading](/ai?storyId=components-text-heading):
```md
Heading renders semantic heading elements (h1, h2, h3, h4) with Trackunit typography styles.
The `variant` prop maps to the semantic heading level: "primary" = h1, "secondary" = h2, "tertiary" = h3, "subtitle" = h4.

### When to use
Use Heading for page titles, section titles, and any hierarchical heading. Choose the variant based on the semantic level of the heading.

### When not to use
Do not use Heading for body text — use `Text` instead.
Do not use Heading for page-level headers with actions — use `PageHeader` or `SectionHeader`. 
```

- [Highlight](/ai?storyId=components-highlight):
```md
Highlight draws visual attention to data values that may require user action, monitoring, or investigation.
It uses color cues (e.g., danger, warning, success) to emphasize out-of-range or critical values for quick scanning.

### When to use
Use Highlight to emphasize numeric or text values inline that have crossed a threshold or need attention (e.g., temperature warnings, low battery).

### When not to use
Do not use Highlight for labeling statuses or categories — use `Tag`.
Do not use Highlight for notification counts — use `Badge`. 
```

- [HorizontalOverflowScroller](/ai?storyId=components-layouts-horizontaloverflowscroller):
```md
HorizontalOverflowScroller displays child elements in a horizontal row with automatic overflow detection.
When content overflows, it shows left/right scroll indicators with click-to-scroll functionality.

### When to use
Use HorizontalOverflowScroller to display a row of items (cards, tags, buttons) that may overflow on smaller screens, with visual cues that more content is available.

### When not to use
Do not use HorizontalOverflowScroller for tab navigation — use `TabList` which has its own scroll handling. 
```

- [Icon](/ai?storyId=components-icon):
```md
Icon renders SVG icons from the icon sprite sheets. All [HeroIcons](https://heroicons.com/) as well as custom Trackunit icons are available.
Icons support three sizes (small=16px, medium=20px, large=24px) and theme-based colors.

### When to use
Use Icon to provide visual cues for actions, statuses, or navigation. Icons can be used standalone or paired with text (e.g., inside Buttons, MenuItems, Tags).

### When not to use
Do not use Icon alone for critical actions without an accessible label. Always provide `ariaLabel` or pair with visible text. 
```

- [Indicator](/ai?storyId=components-indicator):
```md
Indicators are non-interactive elements that communicate essential aspects of the state of an asset.

Whenever an asset is presented, indicators provide the necessary information for a user to comprehend the state of the asset.

_**Do use** indicators to communicate essential aspects of the state of an asset._

_**Do not use** indicators for non-essential information, or to communicate information unrelated to the state of an asset._ 
```

- [KPI](/ai?storyId=components-kpi-kpi):
```md
The KPI component displays a key performance indicator with a title, value, and unit.
It's ideal for showing important metrics at a glance in dashboards and summary views.

### When to use
- To display important numeric metrics that users need to monitor
- In dashboard headers, cards, or page summaries
- When you need a compact way to show a labeled value with units

### When not to use
- For detailed data that requires charts or tables
- When the metric needs interactive elements (use KPICard instead) 
```

- [KPICard](/ai?storyId=components-kpi-kpicard):
```md
The KPICard component displays a key performance indicator in an interactive card format.
It extends the basic KPI with additional features like icons, trends, value bars, and notices.

### When to use
- When KPIs need to be clickable or selectable
- To show trends or progress alongside the metric value
- When you need a richer visual representation of a KPI

### When not to use
- For simple metric display without interaction (use KPI instead)
- When space is very limited 
```

- [LabeledValue](/ai?storyId=components-labeledvalue):
```md
LabeledValue displays a single piece of labeled information, pairing a descriptive label with its corresponding value.
It provides a consistent way to present metadata, properties, or key details across cards, detail views, and side
panels, making information easy to scan and compare.

### When to use
Use LabeledValue to display a labelled value in a detail panel, card, or side panel. Compose several with `LabeledValueList`.

### When not to use
Do not use LabeledValue for a slash-separated inline list of metadata — use `DetailsList` instead. Do not use for tabular data with many rows and columns — use a table. 
```

- [List](/ai?storyId=components-list-uselist):
```md
A performant virtualized list component with infinite scrolling support.

⚠️ **Important**: Requires a container with defined height to work properly.

**Usage Pattern**: Always use the `useList` hook in your component and spread the result into this component.
This gives you access to the virtualizer state (scroll position, isScrolling, etc.) in the parent.

Features:
- Virtualized rendering using TanStack Virtual for performance with large datasets
- Automatic infinite scroll loading when approaching the end of the list
- Optional header support (automatically managed, scrolls with content)
- Built-in pagination with relay-style cursor support
- Configurable loading indicators (skeleton, spinner, or custom)
- Scroll state detection and callbacks
- Variable-height item support via `estimateItemSize`
- Dynamic measurement for accurate positioning of variable-height items

The component automatically loads more data when:
- User scrolls to the last visible item
- Content height is insufficient to fill the container

**Headers with Different Heights**: When using a header that differs in height from list items,
provide `estimateHeaderSize` for optimal initial rendering. The list automatically measures
actual heights on mount to ensure correct positioning. 
```

- [ListItem](/ai?storyId=components-list-listitem):
```md
ListItem presents a concise row of information for quick scanning and navigation. It supports a title, description, meta text, thumbnail,
and a details slot. When `onClick` is provided, the item becomes interactive with a chevron indicator.

### When to use
Use ListItem inside a `List` to display items such as assets, events, users, or notifications with consistent layout.

### When not to use
Do not use ListItem outside of a `List` component for standalone clickable elements — use `Card` or `Button`. 
```

- [MenuContent](/ai?storyId=components-menu-menucontent):
```md
MenuContent (formerly MenuList) is a popover menu that appears above all other content on the page. It offers a
list of actions or functions that a user can access by clicking on a trigger, with full keyboard support:
roving-tabindex Up/Down navigation (wrapping), Home/End, typeahead, and — via `MenuItem`'s `submenu` prop —
nested submenu entry/exit.

Typically rendered inside a `Popover` (directly, or as `PopoverContent`'s children), in which case it reads
the popover's floating context to power its keyboard navigation. Also works standalone (e.g. inside a
`Collapse`, with no ambient `Popover`), falling back to its own local, always-open floating context.

**When to use**
- Use the MenuContent if you have limited space and need to display overflow actions in a list.
- Use the MenuContent for actions that are not essential to completing workflows.
- Don't use the MenuContent to display single or multi-select items within form components. For dropdowns within select components, use SelectDropdown (component not available yet). 
```

- [MenuDivider](/ai?storyId=components-menu-base-components-menudivider):
```md
MenuDivider renders a horizontal line to visually separate groups of items within a MenuContent.

### When to use
Use MenuDivider between groups of related `MenuItem` elements to create logical sections within a menu.

### When not to use
Do not use MenuDivider outside of a `MenuContent`. For general-purpose dividers, use `Spacer` with `border`. 
```

- [MenuItem](/ai?storyId=components-menu-base-components-menuitem):
```md
MenuItem represents a single actionable item within a MenuContent.
It supports labels, icons (prefix/suffix), selected and focused states, danger variants, and — via the
`submenu` prop — nested submenus.

### When to use
Use MenuItem inside a `MenuContent` for individual actions (edit, delete, duplicate) or selectable options.

### When not to use
Do not use MenuItem outside of a `MenuContent` context. For standalone clickable items, use `Button` or `ListItem`. 
```

- [MoreMenu](/ai?storyId=components-menu-moremenu):
```md
MoreMenu (kebab menu) renders a three-dot button that opens a popover with a list of actions.
It is typically filled with a MenuContent containing MenuItem elements.

### When to use
Use MoreMenu when you have overflow actions that don't fit in the main UI. Common for row-level actions in tables, card headers, or list items.

### When not to use
Do not use MoreMenu for primary actions that should always be visible. Use `Button` instead. 
```

- [Notice](/ai?storyId=components-notice):
```md
Notice is a non-interactive element that communicates informational messages the user should see, without prompting an action.
It displays an optional icon and text label, with optional tooltip support.

### When to use
Use Notice to communicate non-essential, contextual information that does not require action (e.g., status notes, informational hints).

### When not to use
Do not use Notice for essential information that requires user action — use `Alert` instead.
Do not use Notice for asset state indicators — use `Indicator` instead. 
```

- [Page](/ai?storyId=components-layouts-page):
```md
Page is the top-level layout container that applies consistent padding and layout to page content.
Use it in combination with PageContent and PageHeader.

### When to use
Use Page as the outermost wrapper for a page view. It provides the base layout structure (padding, spacing) for the page.

### When not to use
Do not use Page for card-level or section-level layout. Use `Card` or standard flex/grid containers instead. 
```

- [PageHeader](/ai?storyId=components-layouts-pageheader):
```md
PageHeader displays the header of a page, providing context about the current location within the application.
It supports a title, optional description tooltip, tag, action buttons, KPI metrics, and tabs for in-page navigation.

### When to use
Use PageHeader at the top of a `Page` to display the page title, description, and primary/secondary actions.

### When not to use
Do not use PageHeader for section-level headings within a page. Use `SectionHeader` instead.
Do not use for card-level headers — use `CardHeader`. 
```

- [Pagination](/ai?storyId=components-pagination):
```md
Pagination provides previous/next page navigation with an optional page counter and jump-to-page input.
It supports both offset-based pagination (with `pageIndex` and `pageCount`) and cursor-based pagination (with `cursorBase`).

### When to use
Use Pagination below a table or list when data is split across multiple pages and the user needs to navigate between them.

### When not to use
Do not use Pagination for infinite scroll patterns. Use the `useInfiniteScroll` hook instead. 
```

- [Polygon](/ai?storyId=components-polygon):
```md
Polygon renders an SVG polygon from a set of coordinate points. Points are automatically normalized to fit within the specified size.
It supports fill/stroke color options and optional opacity for overlay effects.

### When to use
Use Polygon for rendering geofence boundaries, map overlays, or any custom shape defined by coordinate points.

### When not to use
Do not use Polygon for standard UI elements — use the design system components instead. 
```


- [Popover](/ai?storyId=components-popover):
```md
Popover is a floating overlay that appears relative to a trigger element. It provides a context for
PopoverTrigger and PopoverContent children,
managing open/close state, positioning, and focus management.

### When to use
Use Popover for contextual information, menus, or forms that should appear near a trigger element without navigating away.

### When not to use
Do not use Popover for simple text hints — use `Tooltip` instead.
For full-screen overlays or blocking dialogs, use a Modal. 
```

- [Portal](/ai?storyId=components-overlays-portal):
```md
Portal renders its children into a separate DOM node, outside the normal React tree hierarchy.
By default, content is portalled into a z-index-isolated `div#portal-container` in the document body.
This is used internally by Popover, Tooltip, and other overlay components.

### When to use
Use Portal when you need to render content (modals, popovers, tooltips) outside its parent's DOM hierarchy to avoid z-index or overflow clipping issues.

### When not to use
Do not use Portal for regular content rendering. Most overlay components (`Popover`, `Tooltip`) already use Portal internally. 
```

- [SectionHeader](/ai?storyId=components-text-sectionheader):
```md
SectionHeader renders a section title with an optional subtitle and addon elements (e.g., action buttons, status indicators).
It also sets the document title via React Helmet for SEO and browser tab labeling.

### When to use
Use SectionHeader to label a distinct section within a page, below a `PageHeader`. It provides consistent heading styles and an optional subtitle.

### When not to use
Do not use SectionHeader for the main page title — use `PageHeader`.
Do not use for card-level headers — use `CardHeader`. 
```

- [Sheet](/ai?storyId=components-overlays-sheet):
```md
Container-scoped bottom sheet with adaptive snap levels and gesture support.

Use Sheet for contextual surfaces that slide up from the bottom of a
container -- action menus, detail panels, element settings, or filters.
Every Sheet renders via Portal into a required `container` element.
On small screens, consider using Sheet instead of a Popover for better
touch UX. For app-level blocking dialogs, use Modal instead (which
automatically renders as a Sheet on small screens).

When `variant="modal"`, the sheet behaves as a dialog: it renders a
dimming backdrop, sets `role="dialog"` and `aria-modal` on the panel,
and traps keyboard focus via FloatingFocusManager. Pass
`trapFocus={false}` when a parent component provides its own focus
management (e.g. Modal in sheet mode).

Snap levels are adaptive: the Sheet measures the container and creates
fewer stops in shorter containers. Consumers navigate with directional
methods (`snapUp`, `snapDown`, `expand`, `collapse`, `dock`) instead of
naming specific snap points.

The outermost wrapper sets `container-type: size` so cqh/cqw units
resolve against the container's dimensions. Open/close animations use
CSS transitions on transform; the component stays mounted during the
close animation and unmounts after the transition completes. 
```

- [Sidebar](/ai?storyId=components-sidebar):
```md
Sidebar renders a responsive horizontal/vertical navigation bar that automatically collapses overflowing items into a MoreMenu.
It is rendered horizontally until a given breakpoint, then stacks vertically.

**Important:** The Sidebar is just a layout wrapper. You are responsible for styling the children.
For the overflow functionality, use `min-w-[*]` or `flex-shrink-0` on child elements.

When testing, add `setupIntersectionObserver();` to your `vitest.setup.ts` file.

### When to use
Use Sidebar for secondary in-page navigation (e.g., switching between views within a page). Works well with `Tabs` for page-level navigation.

If you need a persistent nav column beside a content region (a page-level sidebar+content
layout, e.g. Site Home, Administration, Asset Home), use `SidebarContentLayout` instead - it
composes `Sidebar` internally and keeps its stacking breakpoint in sync with the content grid.
Use `Sidebar` directly only for a standalone collapsing nav list with no content pane (e.g.
inside a `PageHeader`'s `tabsList`, see `Tabs.stories.tsx`'s `ResponsivenessTwo`/`Three`).

### When not to use
Do not use Sidebar for primary app navigation (the main menu). For top-level navigation, use the app shell navigation. 
```

- [SidebarContentLayout](/ai?storyId=components-sidebarcontentlayout):
```md
SidebarContentLayout is the shared page shell for any screen built from a persistent navigation
sidebar next to a main content area - the pattern behind Site Home, Administration, and Asset
Home. It keeps that pairing consistent everywhere it's used: the same breakpoint decides both
when the sidebar collapses to a tab bar and when content drops below it, so the two can never
disagree, and every page gets identical spacing without reimplementing it by hand.

The content slot renders whatever it's given untouched - a routed `Outlet`, a form, a table - and
never imposes padding on it from the outside (see `contentSpace` to opt out of this component's
own default inset, e.g. for a full-page extension iframe that needs to sit flush to the edges).

### When to use
Use as the layout directly inside a `HostPage` for any page that needs a persistent navigation
sidebar alongside routed/tabbed content (e.g. Site Home, Administration, Asset Home).

### When not to use
Do not use for pages without a persistent sidebar - use `HostPage` directly instead. 
```

- [SkeletonBlock](/ai?storyId=components-loading-states-skeletonblock):
```md
SkeletonBlock renders a single animated placeholder block for shape-based elements (images, icons, buttons, avatars)
before data is loaded. It uses exact height and width values to match the element it replaces.

### When to use
Use SkeletonBlock for loading placeholders of shape-based UI elements: images, icons, badges, buttons, avatars, thumbnails.

### When not to use
For text content, use `SkeletonLabel` which accounts for text line-height margins.
For multiple text lines, use `SkeletonLines`. 
```

- [SkeletonLabel](/ai?storyId=components-loading-states-skeletonlabel):
```md
SkeletonLabel renders a single animated placeholder line for text content. It uses text-size keys (text-xs, text-sm, text-base, etc.)
to match the visual cap-height of actual text, with appropriate vertical margins to maintain line-height alignment.

### When to use
Use SkeletonLabel as a loading placeholder for single text lines: labels, titles, descriptions, values.

### When not to use
For multiple text lines, use `SkeletonLines`.
For shape-based elements (images, icons, avatars), use `SkeletonBlock`. 
```

- [SkeletonLines](/ai?storyId=components-loading-states-skeletonlines):
```md
SkeletonLines renders multiple animated placeholder text lines before data loads.
It supports three modes: uniform (identical lines), custom (per-line config), and preset (common patterns like paragraphs or articles).
Built on top of SkeletonLabel for text-specific margins and sizing.

### When to use
Use SkeletonLines for loading placeholders of multi-line text content: paragraphs, descriptions, articles, or any text block.

### When not to use
For single text lines, use `SkeletonLabel`.
For shape-based elements, use `SkeletonBlock`. 
```

- [Spacer](/ai?storyId=components-layouts-spacer):
```md
Spacer adds vertical whitespace between elements. It can optionally render a visible border line as a divider.

### When to use
Use Spacer to add consistent vertical gaps between sections or to render a horizontal divider line.

### When not to use
Do not use Spacer for horizontal gaps — use Tailwind flex/grid gap utilities. Do not use for structural layout — use CSS grid or flex. 
```

- [Spinner](/ai?storyId=components-loading-states-spinner):
```md
Spinner provides visual feedback that data is being processed. It reassures users that their action is being handled
during short operations (1-5 seconds) such as saving, loading, or refreshing data.

### When to use
Use Spinner for short-duration loading states: button actions, table refreshes, inline data fetches, or modal content loading.

### When not to use
Do not use Spinner for long loading states where content structure is known — use `SkeletonBlock` or `SkeletonLabel` instead.
Do not use Spinner for full-page loading — use `EmptyState` with `loading` prop. 
```

- [Tabs](/ai?storyId=components-tabs):
```md
Tabs group different but related content, allowing users to navigate views without leaving the page.
They always contain at least two items and one tab is active at a time.
Tabs can be used on full page layouts or in components such as modals or tables.

Compose Tabs with TabList, Tab, and TabContent.

### When to use
Use tabs to switch between related content sections within the same context (e.g., different views of an asset, or settings categories).

### When not to use
Do not use tabs for primary navigation between unrelated pages. Use `Sidebar` or route-based navigation instead.
Avoid tabs when there is only one content panel — just show the content directly. 
```

- [Tag](/ai?storyId=components-tag):
```md
Tag is used for labeling or categorizing items in the UI. Common use cases include indicating asset status,
marking features as Beta, or displaying selected options in multi-select inputs.
Tags support dismissal (close button), icons, and multiple color variants.

### When to use
Use Tag to label statuses, categories, or user selections. It supports colors for intent (success, warning, danger) and activity states.

### When not to use
Do not use Tag for numeric counts — use `Badge`.
Do not use Tag for highlighting data values — use `Highlight`.

How to choose between Tag, `Badge` and `Highlight`?
- Use a Tag for labeling statuses, categories, or selections.
- Use a `Badge` to indicate notifications or counts of applied elements, such as filters.
- Use a `Highlight` to draw attention to values in plain text that require special attention or have crossed a threshold. 
```

- [Text](/ai?storyId=components-text-text):
```md
Text applies Trackunit default typography styles to body text. It renders as a `<p>`, `<span>`, or `<div>` element
and supports size, weight, alignment, and style variants (subtle, inverted, uppercase, etc.).

### When to use
Use Text for body content, descriptions, labels, and any non-heading text. It ensures consistent typography across the application.

### When not to use
Do not use Text for page or section headings — use `Heading` instead. 
```

- [ToggleGroup](/ai?storyId=components-buttons-togglegroup):
```md
ToggleGroup allows users to toggle between two or more closely related options and immediately apply the selection.
It renders a segmented control with a sliding background indicator. Supports text-only, icon-only, and text+icon modes.

### When to use
Use ToggleGroup when the user needs to switch between 2-5 mutually exclusive options that take effect immediately (e.g., view modes, map/list toggle, time ranges).

### When not to use
Do not use ToggleGroup for navigation — use `Tabs`.
Do not use ToggleGroup for form selections with many options — use a Select or RadioGroup. 
```

- [Tooltip](/ai?storyId=components-tooltip):
```md
Tooltips display additional information upon hover. The information included should be contextual, helpful, and nonessential while providing that extra ability to communicate and give clarity to a user.

Tooltips should be used sparingly and contain succinct, supplementary information, and they should contain read-only text. **❗️Do not include interactive elements in tooltips ** (no links, buttons, etc). Interactive elements in tooltips are inaccessible since tooltips do not receive focus.

**Do use** tooltips to expose names of icon buttons that lack visual labels, when more information is useful in helping a user understand the context, when an element needs additional explanation, or use when defining a term or inline item.

**Do not use** tooltips to include information that is necessary for the user to complete their task. Use helper text that is always visible and accessible for vital information. 
```

- [SegmentedValueBar](/ai?storyId=components-valuebar-segmentedvaluebar):
```md
SegmentedValueBar displays multiple colored segments on a bar to visualize values relative to a total.
Supports optional tooltips per segment, showing value and optionally a label. 
```

- [ValueBar](/ai?storyId=components-valuebar-valuebar):
```md
ValueBar displays a numeric value as a colored progress bar within a defined range.
The bar color changes based on the score (value relative to min/max) using either default or custom level colors.
It can optionally display the numeric value and unit alongside the bar.

### When to use
Use ValueBar to visualize a metric relative to a range (e.g., battery level, fuel percentage, utilization rate, temperature).

### When not to use
Do not use ValueBar for progress through a multi-step process. Use a stepper or progress indicator instead. 
```

- [ZStack](/ai?storyId=components-layouts-zstack):
```md
ZStack stacks its children on the z-axis (overlaying them on top of each other).
It is a CSS grid-based alternative to `position: absolute` that avoids side effects like elements being removed from the document flow.

### When to use
Use ZStack when you need to overlay elements on top of each other (e.g., an image with a badge overlay, or a scroll container with fade indicators).

### When not to use
Do not use ZStack for standard stacking/layout — use flex or grid containers instead. 
```

- [Button](/ai?storyId=components-buttons-button):
```md
Buttons are clickable elements that are used to trigger actions. They communicate calls to action to the user and allow users to interact with pages in a variety of ways. Button labels express what action will occur when the user interacts with it.

### When to use
Use buttons to communicate actions users can take and to allow users to interact with the page. Each page should have one primary button, and any remaining calls to action should be represented as lower emphasis buttons.

### When not to use
Do not use buttons as navigational elements. Instead, use `Links` when the desired action is to take the user to a new page. 
```

- [IconButton](/ai?storyId=components-buttons-iconbutton):
```md
Buttons are clickable elements that are used to trigger actions. They communicate calls to action to the user and allow users to interact with pages in a variety of ways. The Icon Button is a version of the standard Button component without the text label.

### When to use
Use icon buttons for actions that are well-understood through the icon alone, such as close, delete, or settings buttons. Always provide a `title` or `ariaLabel` prop for accessibility.

### When not to use
Do not use icon buttons when the action is not immediately clear from the icon. Use a regular Button with text instead. 
```

- [useLocalStorage](/ai?storyId=hooks-react-components-uselocalstorage):
```md
Works like useState, but persists to localStorage with Zod schema validation
and superjson serialization (supports Date, Map, Set, BigInt, etc.). 
```

- [useDebounce](/ai?storyId=hooks-react-components-usedebounce):
```md
Returns a debounced copy of `value`: it updates only after `delay` ms without further
changes. Pass whatever changes on each keystroke, tick, or prop update; this hook only
delays the value you read back — it does not own the source of truth or expose a setter.

### When to use
Use `useDebounce` to delay expensive operations triggered by rapidly changing values —
search inputs, filter fields, resize observers, or any value that changes faster than
you want to react to it.

### When not to use
- When you need to debounce a callback rather than a value — wrap the callback in a
  `setTimeout` / `useMemo` pattern instead.
- For throttling (fixed-interval updates) — debounce waits for inactivity, throttle
  fires at intervals. 
```

- [useViewportBreakpoints](/ai?storyId=hooks-react-components-useviewportbreakpoints):
```md
Returns real-time boolean flags for each design-token breakpoint based on viewport width.

**When to use:**
- Use `useViewportBreakpoints` when you need to respond to the **full viewport width**
  — for example, toggling a mobile navigation drawer or switching a global layout shell.
- **Prefer `useContainerBreakpoints`** for component-level responsiveness, as it
  responds to the parent container's width and works correctly when a component appears
  in different layout contexts (sidebar, main content, widget).
- Pass `{ skip: true }` when you only need the initial value and don't want ongoing
  `matchMedia` listeners. 
```


- [useHasAccessTo](/ai?storyId=hooks-react-core-hooks-usehasaccessto):
```md
Hook to check if the current user has access to a navigation target.
Useful for conditionally rendering links based on user permissions.

Supports single checks, `oneOf` (any match), and `requireAll` (every match) criteria.

**When to use:**
- Use `useHasAccessTo` to conditionally show/hide navigation links or action buttons
  based on whether the user can reach the target page or entity.
- Use `useUserPermission` instead when you need a synchronous check against a
  permission string on the user object rather than a navigation-target check.
- Use the `hasAccessTo` method from `useNavigateInHost` for a one-off imperative
  check (e.g. inside an event handler) rather than a reactive/rendered result. 
```

- [useNavigateInHost](/ai?storyId=hooks-react-core-hooks-usenavigateinhost):
```md
Hook to navigate programmatically within the Trackunit Manager or between Iris Apps.

### When to use
Use `useNavigateInHost` when you need to navigate between Manager pages, entity home
pages, or Iris Apps from component logic (e.g. after a mutation, on row click, in a
redirect guard). Use the `get*Url` methods when you need an href for an `<a>` tag.
Use `hasAccessTo` before showing navigation options the user may not have access to.

### When not to use
Do not use for in-page anchor scrolling or query-param changes within the same
Iris App — use your router directly. 
```

- [useCurrentUser](/ai?storyId=hooks-react-core-hooks-usecurrentuser):
```md
Hook providing the authenticated user's profile, account, and permission data
from the CurrentUserContext.

### When to use
Use `useCurrentUser` when you need the user's identity or account context — displaying
the user's name, resolving the effective account ID, or branching logic based on
`isAssuming` or `isTrackunitUser`.

### When not to use
- If you only need a boolean check for a single permission — use `useUserPermission`.
- To gate entire routes — prefer server-side access control or `hasAccessTo` from
  `useNavigateInHost`. 
```

- [useUserPermission](/ai?storyId=hooks-react-core-hooks-useuserpermission):
```md
Hook that checks if the current user has a given permission.

### When to use
Use `useUserPermission` to conditionally show or hide UI based on a single permission —
delete buttons, admin panels, export actions, or any feature behind an access check.

### When not to use
- When you need multiple user fields (name, account, assuming state) or need to check
  several permissions at once — use `useCurrentUser`.
- To gate navigation targets — use `hasAccessTo` from `useNavigateInHost`. 
```

- [useWidgetConfig](/ai?storyId=hooks-react-core-hooks-usewidgetconfig):
```md
Manages a dashboard widget's configuration, data, title, edit mode, filters, and time range.

**When to use:**
- Use `useWidgetConfig` inside any dashboard widget to read/write its persisted
  configuration, respond to dashboard-level filter and time-range changes, and
  manage the widget's edit-mode lifecycle.
- Must be rendered inside a `WidgetConfigProvider` (provided automatically by the
  dashboard host). 
```

- [DayRangePicker](/ai?storyId=components-date---time-dayrangepicker):
```md
DayRangePicker renders an interactive calendar that allows the user to select a start and end date.
It supports disabled days, timezone-aware display, locale configuration, and an optional cancel button.
The selected range is returned via the `onRangeSelect` callback as a `DateRange` object.

### When to use
Use DayRangePicker when the user needs a visual calendar to pick a custom date range — for example,
selecting a reporting period or scheduling an event spanning multiple days.

### When not to use
Do not use DayRangePicker for quick preset ranges (e.g., "Last 7 days") — use `DayRangeSelect` which includes preset options and a calendar fallback.
Do not use it for time selection — use `TimeRangeField`. 
```

- [DayRangeSelect](/ai?storyId=components-date---time-dayrangeselect):
```md
DayRangeSelect is a popover-based date range picker with preset temporal options (e.g., "Last 7 days", "Next 30 days")
and an optional custom calendar picker. Users can search for presets by typing natural language queries like "last 3 months".
It supports configurable allowed directions, timezone handling, and max day limits.

### When to use
Use DayRangeSelect when users need to choose a date range from predefined presets or a custom calendar — for example,
filtering dashboard data by time period or selecting a reporting window.

### When not to use
Do not use DayRangeSelect for a standalone calendar without presets — use `DayRangePicker`.
Do not use it for time-only selection — use `TimeRangeField`. 
```

- [Timeline](/ai?storyId=components-timeline):
```md
The Timeline component offers a visual representation of events or milestones in chronological order, helping users easily follow the progression of activities, tasks, or data points over time. 
```

- [DateTime](/ai?storyId=components-date---time-datetime):
```md
DateTime renders a locale-aware, formatted date and/or time inside a semantic `<time>` element.
It supports absolute formatting via `TemporalFormat` presets (e.g., `DateTimeFormat.DATE`, `DateTimeFormat.DATE_LONG_TIME`)
and relative "time ago" display via the `fromNow` prop. Timezone-aware formatting is handled automatically via the user's preferred timezone.

### When to use
Use DateTime whenever you need to display a date, time, or relative timestamp in the UI — for example, "Last seen 3 hours ago" or "Feb 17, 2026".

### When not to use
Do not use DateTime for date input or selection — use `DayRangePicker` or `TimeRangeField`.
Do not use for duration formatting (e.g., "2h 30m") — use dedicated duration utilities instead. 
```

- [useDateAndTime](/ai?storyId=hooks-react-date-and-time-hooks-usedateandtime):
```md
Hook for locale- and timezone-aware date/time operations including formatting,
arithmetic, comparisons, relative time, and duration formatting.

### When to use
Use `useDateAndTime` whenever you need to format, compare, or manipulate dates in a
way that respects the user's locale and timezone.

### When not to use
- For raw UTC timestamps that never reach the UI — use plain `Date` math or
  `date-and-time-utils` directly.
- For date picker value handling — the date/time components already consume locale
  and timezone internally. 
```

- [useTimezone](/ai?storyId=hooks-react-date-and-time-hooks-usetimezone):
```md
Resolves the active timezone based on user preference, custom override, and optional asset location.

Returns `current` (browser or custom override), `preferred` (resolved per user settings
and optional asset), and `assetTimeZone` (fetched from the asset's GPS location).

The asset timezone is resolved by the nearest `AssetTimezoneProvider` in the component tree.
Use `AssetTimezoneProvider` on asset-detail pages to enable machine-timezone resolution.

**When to use:**
- Use `useTimezone` whenever you need to display or calculate dates in the correct
  timezone — especially on asset-detail pages where the machine's timezone may differ
  from the user's browser timezone.
- Pair with `useDateAndTime` to format dates in the resolved `preferred` timezone.
- Do **not** rely on `Intl.DateTimeFormat().resolvedOptions().timeZone` directly —
  this hook respects the user's preference setting (browser, machine, or custom). 
```

- [Drawer](/ai?storyId=components-overlays-drawer):
```md
Drawers slide in from the left or right edge of the viewport as either a modal
dialog or a docked inspector panel.

### When to use
- For secondary content that doesn't need to be always visible
- For inspector panels or item detail views that slide in from the side
- When you need to preserve context of the underlying page

### When not to use
- For critical actions requiring user confirmation (use Modal instead)
- For simple tooltips or small contextual information (use Popover)
- To show a table selection and bulk actions (use ActionSheet instead)

### API
`Drawer` is a presentation component. Call `useDrawer()` to own the drawer's
open state, dismiss handling, and (optional) `onBeforeClose` guard, then spread
its return value onto `<Drawer>`. 
```

- [DrawerHeader](/ai?storyId=components-overlays-drawerheader):
```md
Standard drawer toolbar header. Compose it as a child of `<Drawer />`:

```tsx
const drawer = useDrawer({ position: "right" });

<Drawer {...drawer}>
  <DrawerHeader menuContent={…} onClickBack={goBack} onClickClose={drawer.close} />
  {\/* body *\/}
</Drawer>
```

Wire the X button to `useDrawer`'s `close` so it shares the same dismiss pipeline
(Escape, outside-press, `onBeforeClose` guard) as the rest of the drawer.

Button labels come from this library's translation namespace and cannot be overridden — the
affordances are universal ("Close", "Back", "Forward", "More actions"). 
```

- [Filter](/ai?storyId=components-filter-bar-base-components-filter):
```md
The Filter component is the base component used in the manager to filter data.

- This component in generic and does not have any connection to the data.
- The base props extends button props, and any button props such as prefix and suffix can be used.
- Color and size has special default values in this component, but can be overridden if needed.

To add items to the popover list use the children prop, this is where you build all the filter items and connected logic. 
```

- [FilterBody](/ai?storyId=components-filter-bar-base-components-filterbody):
```md
The FilterBody component is used to display the title of the filter and a reset button.
IT is intended for use in the Filter component.
The reset button will be enabled if the showReset prop is set to true. 
```

- [FilterFooter](/ai?storyId=components-filter-bar-base-components-filterfooter):
```md
The FilterFooter component is a container component for filter footer content.
It provides a flexible layout with right-aligned content for filter components. 
```

- [FilterHeader](/ai?storyId=components-filter-bar-base-components-filterheader):
```md
The FilterHeader component is used to display the title of the filter and a reset button.
IT is intended for use in the Filter component.
The reset button will only be enabled if the showReset prop is set to true. 
```

- [CheckBoxFilterItem](/ai?storyId=components-filter-bar-base-components-checkboxfilteritem):
```md
The CheckBoxFilterItem component is the base component used in the manager to FilterItem data.
This component in generic and does not have any connection to the data. 
```

- [RadioFilterItem](/ai?storyId=components-filter-bar-base-components-radiofilteritem):
```md
The RadioFilterItem component is the base component used in the manager to FilterItem data.
This component in generic and does not have any connection to the data. 
```

- [Checkbox](/ai?storyId=components-checkbox):
```md
Checkboxes are used when there are multiple items to select in a list. Users can select zero, one, or any number of items.

Checkboxes are used for multiple choices, not for mutually exclusive choices. Each checkbox works independently from other checkboxes in the list, therefore checking an additional box does not affect any other selections.

### When to use
Use checkboxes to allow selection in a form, for filtering, terms and conditions to indicate agreement, and bulk actions in lists or tables.

### When not to use
Do not use checkboxes if the user can only select one option from a list. Use RadioGroup instead. 
```

- [CheckboxField](/ai?storyId=components-inputs-checkboxfield):
```md
CheckboxField is a form-ready checkbox that wraps a `Checkbox` inside a `FormGroup`.
It provides a labeled checkbox with support for tooltips, help text, validation, and form group styling.

### When to use
Use CheckboxField for boolean inputs inside forms — for example, "I agree to terms" or toggling a feature on/off.

### When not to use
Do not use CheckboxField for multi-select lists — use checkbox filters or a select component.
For a standalone checkbox without form group wrapping, use `Checkbox` directly. 
```

- [ColorField](/ai?storyId=components-inputs-colorfield):
```md
The `<ColorField>` component is used to select and enter colors.
It provides both a color picker and a text input for hex color codes,
with validation ensuring valid hex format (#RRGGBB).

### When to use
- Color selection in theming or customization forms
- Brand color configuration
- Any input requiring a valid hex color value

### When not to use
- When you need a full color palette with named colors
- When opacity/alpha channel is required (only supports 6-digit hex) 
```

- [DateField](/ai?storyId=components-inputs-datefield):
```md
The date field component is used for entering date values with a calendar picker (same UI as DayPicker).

### When to use
Use DateField for selecting calendar dates such as birthdates, deadlines, or scheduling.

### When not to use
Do not use DateField for non-serialized dates or free-form date text input. Use TextField instead. 
```

- [DropZone](/ai?storyId=components-upload-dropzone):
```md
The `<DropZone>` component provides a drag-and-drop area for file uploads.
Users can either drag files onto the zone or click to browse the file system.

### When to use
- Drag-and-drop file upload experience
- Batch file uploads
- When visual feedback during drag is important

### When not to use
- Simple single file uploads - use `UploadField` instead
- When form field styling (label, help text) is needed - use `UploadField` 
```

- [EmailField](/ai?storyId=components-inputs-emailfield):
```md
The `<EmailField>` component is used to enter and validate email addresses.
It automatically validates the format on blur and displays appropriate error messages.

### When to use
- Collecting user email addresses in forms
- Contact forms that require email validation
- Any input that must be a valid email format

### When not to use
- For general text input - use `TextField` instead
- For URLs - use `UrlField` instead
- For phone numbers - use `PhoneField` instead 
```


- [Label](/ai?storyId=components-text-label):
```md
Label renders a styled `<label>` element for form input fields.
This component is typically **not used directly** — it is rendered internally by `FormGroup` and
all Field components (e.g., `TextField`, `CheckboxField`, `TimeRangeField`). Use it only when
building a custom form group layout that cannot use `FormGroup`.

### When to use
Use Label only when constructing a custom form field wrapper that cannot use `FormGroup`.

### When not to use
Do not use Label directly for standard form fields — use the appropriate Field component (e.g., `TextField`, `CheckboxField`) which includes Label automatically. 
```

- [MultiSelectField](/ai?storyId=components-select-multiselectfield):
```md
The `<MultiSelectField>` component allows selecting multiple options from a dropdown list.
It wraps the select input with FormGroup for consistent form styling including label,
help text, and validation.

### When to use
- Selecting multiple items from a predefined list (tags, categories, permissions)
- When users need to see and manage all selected items
- Filtering by multiple criteria

### When not to use
- Single selection - use `SelectField` instead
- Very long lists - consider a searchable/async variant
- Binary choices - use `Checkbox` or `ToggleSwitchOption` instead 
```

- [NumberField](/ai?storyId=components-inputs-numberfield):
```md
The number field component is used for entering numeric values and includes controls for incrementally increasing or decreasing the value.

### When to use
Use NumberField when the controls to incrementally increase or decrease makes the task easier for the user, such as quantity selectors or numeric settings.

### When not to use
Do not use NumberField for non-serialized numbers or IDs. Use TextField instead. 
```

- [OptionCard](/ai?storyId=components-cards-optioncard):
```md
A card version of a radio button that includes an icon, headings and a description. 
```

- [PasswordField](/ai?storyId=components-inputs-passwordfield):
```md
The `<PasswordField>` component is used to enter passwords or other confidential information.
Characters are masked as they are typed, with an option to toggle visibility.

### When to use
- Password input for login or registration forms
- Entering sensitive data that should be obfuscated (API keys, secrets)
- Any confidential text input

### When not to use
- Confirming user actions like deletion - use a Checkbox instead
- Non-sensitive text input - use `TextField` instead
- PIN codes - consider a specialized PIN input 
```

- [PhoneField](/ai?storyId=components-inputs-phonefield):
```md
The `<PhoneField>` component is used to enter and validate phone numbers.
It includes built-in validation for phone number format and displays appropriate error messages.

### When to use
- Collecting phone numbers in contact forms
- User profile phone number fields
- Any input requiring phone number validation

### When not to use
- General text input - use `TextField` instead
- International phone with country selector - consider specialized international phone component 
```

- [PhoneFieldWithController](/ai?storyId=components-inputs-phonefieldwithcontroller):
```md
PhoneFieldWithController wraps `PhoneField` with a `react-hook-form` `Controller`,
connecting the phone number input to form state management. It handles value synchronization,
validation integration, and default value assignment automatically.

### When to use
Use PhoneFieldWithController when you have a phone number field inside a `react-hook-form` managed form.

### When not to use
Do not use PhoneFieldWithController outside of `react-hook-form` — use `PhoneField` directly. 
```


- [Schedule](/ai?storyId=components-date---time-schedule):
```md
Schedule renders a weekly time-range editor where each row represents a day with an active toggle,
an optional all-day checkbox, and a start/end time range. It is used for defining recurring schedules
such as operating hours, service windows, or geofence active periods.

### When to use
Use Schedule when users need to configure per-day time ranges — for example, setting working hours for each day of the week.

### When not to use
Do not use Schedule for a single time range — use `TimeRangeField`.
Do not use it for date range selection — use `DayRangePicker`. 
```

- [Search](/ai?storyId=components-search):
```md
Search renders a styled search input with a magnifying glass icon, an optional loading spinner,
and a clear button that appears when a value is present. It supports visual variants such as
widening on focus and hiding the border when not focused.

### When to use
Use Search for filtering or querying data sets — for example, a search box above a table or list to narrow down results.

### When not to use
Do not use Search for multi-filter scenarios — use `FilterBar`.
Do not use it as a general text input — use `TextField`. 
```

- [SelectField](/ai?storyId=components-select-selectfield):
```md
SelectField is a dropdown select component wrapped in the FormGroup component for selecting a single option from a list.

### When to use
Use SelectField when users need to choose one option from a predefined list of 4 or more items.

### When not to use
Do not use SelectField for fewer than 4 options. Use RadioGroup instead for better usability with small option sets. 
```

- [TextAreaField](/ai?storyId=components-inputs-textareafield):
```md
The `<TextAreaField>` component is used for multi-line text input.
Use when you need to allow users to enter a large amount of text, such as comments or descriptions.

### When to use
- Longer text inputs like comments, descriptions, or notes
- When the expected input is more than one line
- For free-form text that benefits from a larger input area

### When not to use
- Single-line inputs - use `TextField` instead
- Structured data like email or phone - use specialized field components
- Rich text editing - consider a rich text editor component 
```

- [TextField](/ai?storyId=components-inputs-textfield):
```md
Text fields enable the user to interact with and input content and data. This component can be used for long and short form entries. Allow the size of the text input box to reflect the length of the content you expect the user to enter.

### When to use
Use text fields for short-form text input such as names, emails, or search queries.

### When not to use
Do not use text fields for multi-line text input. Use TextAreaField instead. 
```

- [TimeRange](/ai?storyId=components-date---time-timerange):
```md
TimeRange renders a pair of native `<input type="time">` fields for selecting a start and end time.
It provides a controlled time range with `onChange` callback and supports custom separators, disabled state, and validation styling.

### When to use
Use TimeRange for bare time range inputs inside custom layouts or composed components (e.g., inside Schedule rows).

### When not to use
Do not use TimeRange directly in forms that need a label, help text, or validation — use `TimeRangeField` instead. 
```

- [TimeRangeField](/ai?storyId=components-date---time-timerangefield):
```md
TimeRangeField is a form-ready time range input that wraps a `TimeRange` selector inside a `FormGroup`.
It provides a labeled pair of start/end time inputs with support for tooltips, help text, and validation error messages.

### When to use
Use TimeRangeField when you need a labeled time range input inside a form — for example, selecting working hours, shift times, or scheduling windows.

### When not to use
Do not use TimeRangeField for date ranges — use `DayRangePicker`.
Do not use it outside a form context where you only need a bare time range input — use `TimeRange` directly instead. 
```

- [ToggleSwitch](/ai?storyId=components-toggle-toggleswitch):
```md
The `<ToggleSwitch>` is a low-level checkbox input wrapper with `role="switch"`.
It renders just the switch control without label or description.

**Not intended for standalone use** - use `ToggleSwitchOption` instead for forms.
This component is for building custom toggle implementations or wrapping in other components.

### When to use
- Building custom toggle components with different layouts
- Integrating a toggle into a component that provides its own label (e.g., menu items)
- Creating specialized switch controls

### When not to use
- Standard forms - use `ToggleSwitchOption` instead (includes label/description)
- Multiple selections - use `Checkbox` components instead 
```

- [ToggleSwitchOption](/ai?storyId=components-toggle-toggleswitchoption):
```md
The `<ToggleSwitchOption>` component is used for binary on/off settings in forms.
It combines a toggle switch with a label and optional description for complete form integration.

### When to use
- Enable/disable feature toggles in settings
- Binary choices where the action takes effect immediately
- Preferences that represent on/off states

### When not to use
- Multiple selections from a list - use `Checkbox` components instead
- Mutually exclusive options - use `RadioGroup` instead
- Actions requiring confirmation - use buttons with confirmation dialog 
```

- [UploadField](/ai?storyId=components-upload-uploadfield):
```md
The `<UploadField>` component enables users to upload files through a form field.
It wraps the UploadInput with FormGroup for consistent form styling including label,
help text, and error handling.

### When to use
- Single file upload in forms (documents, images)
- When you need form field styling (label, validation messages)
- File attachments in form submissions

### When not to use
- Drag and drop file uploads - use `DropZone` instead
- Multiple file uploads with preview - consider specialized upload component
- Large file uploads requiring progress indication 
```

- [UploadInput](/ai?storyId=components-upload-uploadinput):
```md
UploadInput renders a file upload input with a styled button label. It wraps `BaseInput` with `type="file"`
and supports restricting file types, enabling multi-file selection, and disabling interaction.

**Note:** If you need a label, help text, or validation wrapping, use `UploadField` instead.

### When to use
Use UploadInput for bare file upload inputs inside custom layouts or composed form components.

### When not to use
Do not use UploadInput in standard forms — use `UploadField` which adds `FormGroup` wrapping with label and validation. 
```

- [UrlField](/ai?storyId=components-inputs-urlfield):
```md
The `<UrlField>` component is used to enter and validate URLs/web addresses.
It automatically validates the format on blur and displays appropriate error messages.

### When to use
- Collecting website URLs in forms
- Social media profile links
- Any input requiring valid URL format

### When not to use
- General text input - use `TextField` instead
- Email addresses - use `EmailField` instead
- Internal application links - use standard link/routing 
```

- [FormWizard](/ai?storyId=components-wizard-formwizard):
```md
The `<FormWizard>` component renders multi-step forms with a sidebar navigation.
Use the `useFormWizard` hook to generate the props for this component.

The wizard uses Zod schemas for validation, where each schema property represents a step.
Each step receives its own form instance for registering inputs, enabling per-step and
full-form validation.

**Note:** In production, the schema should be returned from a hook to allow translations
for error messages.

### When to use
- Complex forms that benefit from being split into logical steps
- Onboarding flows or setup wizards
- Forms where later steps depend on earlier input

### When not to use
- Simple forms with few fields - use regular form components
- Forms that should show all fields at once 
```

- [useLazyQuery](/ai?storyId=hooks-react-graphql-hooks-uselazyquery):
```md
A wrapper around Apollo Client's useLazyQuery that provides stable data by default.

This hook prevents UI flickering during refetches by returning the previous data
when new data is loading, unless stableData is set to false.

### When to use
Use `useLazyQuery` when the query should fire on a user action (button click, form
submit, or after a precondition is met), not on mount.

### When not to use
- When data should load immediately on render — use `useQuery`.
- For Relay-style cursor-paginated lists — use `usePaginationQuery`. 
```

- [usePaginationQuery](/ai?storyId=hooks-react-graphql-hooks-usepaginationquery):
```md
`usePaginationQuery` fetches data from a GraphQL query with Relay-style cursor pagination.
It manages page accumulation, loading state, and provides `pagination` controls (including `fetchNext`)
compatible with the Table component's `pagination` prop.

The `updateQuery` callback merges newly fetched pages into the accumulated dataset. Use
`unionEdgesByNodeKey` to deduplicate and merge edges across pages.

### When to use
Use usePaginationQuery for any paginated GraphQL list — for example, loading an asset list
or event log with infinite scroll via the Table component.

### When not to use
Do not use usePaginationQuery for single-entity queries without pagination — use `useQuery` from this library directly. 
```

- [useQuery](/ai?storyId=hooks-react-graphql-hooks-usequery):
```md
A wrapper around Apollo Client's useQuery that provides stable data by default.

This hook prevents UI flickering during refetches by returning the previous data
when new data is loading, unless stableData is set to false.

### When to use
Use `useQuery` for any GraphQL query that should execute on mount and render data.

### When not to use
- When the query should fire on a user action — use `useLazyQuery`.
- For Relay-style cursor-paginated lists — use `usePaginationQuery`. 
```


- [useMapAnnotation](/ai?storyId=components-map-usemapannotation):
```md
Registers a map annotation to be rendered in the Controls overlay.

Pass a descriptor to register, or `null` to unregister.
Automatically cleans up on unmount.

Same-id rerenders are stable: passing an inline descriptor with identical
content (id, label, priority, etc.) will not cause unregister/register churn,
avoiding reordering and enter/exit animation retriggers. 
```

- [ClusterMarker](/ai?storyId=components-map-layers-markers-clustermarker):
```md
 
```

- [useControls](/ai?storyId=components-map-usecontrols):
```md
Merges per-area `prepend`/`append` modifier lists into a base `ControlsConfig`.

Memoizes internally — stable references are returned when neither `base` nor
`areas` has changed. Modifiers are applied via `defineControlStack`, which
filters `undefined` entries and rejects duplicate control ids.

When `areas` is omitted the `base` reference is returned as-is. 
```

- [useMap](/ai?storyId=components-map-usemap):
```md
useMap hook - the main entry point for using the map

Returns a tuple of [Map, api] where Map is the component to render
and api contains map status, actions, event subscriptions, containerRef, and
controls configuration. `api.state` is MapStatus only: use it for readiness,
initialization failure, appearance, and tile size.

Camera state (center, zoom, bounds, isIdle) is exposed through
`useCameraState(api)` so components opt in to high-frequency viewport updates.

All action functions and the Map component reference are stable across re-renders. 
```

- [useMapKeyboardNavigation](/ai?storyId=components-map-usemapkeyboardnavigation):
```md
Opt-in keyboard navigation hook for map components.
Provides consistent keyboard shortcuts:
- Arrow keys: Pan the map in all directions
- `=` key: Zoom in
- `-` key: Zoom out

**Usage:**
```tsx
import { useMap, useMapKeyboardNavigation } from "@trackunit/react-map";
import { googleMapsAdapter } from "@trackunit/react-map-adapter-google";

const [Map, api] = useMap(googleMapsAdapter({ apiKey }));
useMapKeyboardNavigation(api);
``` 
```

- [useImageOverlay](/ai?storyId=components-map-layers-useimageoverlay):
```md
`useImageOverlay` -- creates an image overlay layer handle.

Renders a georeferenced image on the map within the given bounds. 
```

- [useRoute](/ai?storyId=components-map-layers-useroute):
```md
`useRoute` -- creates a route layer handle from an array of waypoints.

Converts the waypoints to a GeoJSON LineString internally.
Routes need at least 2 waypoints to be rendered. 
```

- [useLayers](/ai?storyId=components-map-layers-uselayers):
```md
`useLayers` -- aggregates layer handles and manages shared interaction state.

This is the central hook that ties all layers together:
- Shared hover/select interaction via a reducer (cross-layer, single entity at a time)
- Combined bounds across all layers (lazy, cached)
- Loading/ready coordination
- Aggregated controls 
```

- [useMarkers](/ai?storyId=components-map-layers-markers-usemarkers):
```md
`useMarkers` -- creates a marker layer handle from arbitrary data.

Generic over:
- `TItem`: the data item type (inferred from `data`)
- `TCluster`: the cluster data type (inferred from `cluster.data` for server-side,
  defaults to `ClusterInfo` for client-side or no clustering) 
```

- [ShapeAnnotationLabel](/ai?storyId=components-map-layers-shapes-shapeannotationlabel):
```md
Annotation-mode shape label shown in the `AnnotationStack` when
the viewport is fully inside a shape and no edge is visible.

Composes `ShapeLabelPill` with a `ShapeIcon` preview on the left
to preserve the site's visual identity (color + geometry type icon)
in the annotation chrome bar. When `onClick` is provided, a wrapping
`<button>` handles interaction; pass `fitFeatureBounds` here to
zoom-to-fit on click.

Intended for use inside a `MapAnnotationDescriptor` with
`type: "custom"` — see `useFleetSiteAnnotation` for the canonical usage. 
```

- [ShapeIcon](/ai?storyId=components-map-layers-shapes-shapeicon):
```md
Renders a miniature SVG preview of a GeoJSON geometry.

For multi-geometries (MultiPolygon, MultiLineString, etc.), shows
a "multi" badge in the top-right corner. The badge is absolutely
positioned so it does not inflate the icon's layout dimensions. 
```

- [ShapeEdgeLabel](/ai?storyId=components-map-layers-shapes-shapeedgelabel):
```md
 
```


- [useShapes](/ai?storyId=components-map-layers-shapes-useshapes):
```md
`useShapes` -- creates a shape layer handle from a GeoJSON FeatureCollection.

Input is pure GeoJSON. The hook does not transform geometry -- it computes
bounds and wraps the data in a layer handle. 
```

- [MapMarker](/ai?storyId=components-map-layers-markers-mapmarker):
```md
 
```

- [Panel](/ai?storyId=components-map-usepanel):
```md
Renders a marker info panel positioned next to its anchor with Floating UI.

Middleware chain: `offset(8) → flip() → shift(8) → hide`

Animation state is driven by the `data-panel` attribute:
  ""         — element is in DOM (for Floating UI to measure) but hidden via
               CSS `visibility: hidden` so the pre-commit translate(0,0)
               position is never visible.
  "open"     — appears instantly once placement is committed (no enter
               animation — see docs/adr/0027-instant-panel-first-paint.md).
  "closing"  — fades out during the EXIT_DURATION_MS window before unmount. 
```

- [Modal](/ai?storyId=components-overlays-modal):
```md
Modal presents critical information or requests user input in an overlay dialog that interrupts the current workflow.
It renders inside a Portal with a backdrop overlay, focus trapping, and proper accessibility roles.
Modals must always be used together with the `useModal` hook, which manages open/close state and Floating UI integration.

When the container width is below the "sm" breakpoint (480px), the Modal
automatically renders as a bottom Sheet with gesture support.

Compose the modal body with `ModalHeader`, `ModalBody`, and `ModalFooter` for consistent structure.

### When to use
Use Modal for confirmations, forms, or critical information that requires user attention before proceeding.

### When not to use
Do not use Modal for non-blocking notifications — use `Notice` or `Alert`.
Do not use Modal for simple tooltips or contextual info — use `Popover`. 
```

- [ModalBody](/ai?storyId=components-overlays-modalbody):
```md
Modal body container.

Renders children inside a scrollable flex container. Use this component to wrap
the main content of a modal, which automatically handles overflow scrolling. 
```

- [ModalFooter](/ai?storyId=components-overlays-modalfooter):
```md
Modal footer with action buttons.

Provides a consistent footer layout with cancel, secondary, and primary action buttons.
Supports loading states and automatic button disabling during async operations. 
```

- [ModalHeader](/ai?storyId=components-overlays-modalheader):
```md
Modal header section.
Displays a main heading, optional subheading, and a close button.

Use inside a Modal component to provide consistent header styling with a title, subtitle, and close button. 
```

- [ActionSheet](/ai?storyId=components-tables-actionsheet):
```md
The `<ActionSheet>` component appears as a floating bar when one or more items
are selected from a table, providing bulk actions for the selection.

It primarily accommodates 1-3 main actions that represent the most crucial and
frequently accessed functions on the specific page. If the page supports more
than 3 actions, the ones that are performed less often can be placed in a
contextual menu, represented by the 'three dots' icon via `moreActions`.

### When to use
- Provide bulk operations when users select multiple table rows
- For batch actions like delete, export, assign, or status changes
- When actions need to operate on a collection of selected items

### When not to use
- For single row actions - use `RowActions` instead
- For page-level actions not tied to selection - use regular buttons
- When the table doesn't support multi-selection 
```

- [SelectAllBanner](/ai?storyId=components-tables-selectallbanner):
```md
A generic banner displayed inside a table's `subHeaderActions` slot when all
rows on the current page are selected. It offers the user two actions:

1. **Select all** across every page (when `areAllSelected` is `false`).
2. **Clear selection** (when `areAllSelected` is `true`).

Domain-specific data-fetching and state management are left to the consumer
via the `onClickSelectAll` / `onClickClearSelection` callbacks.

### When to use

- The table is **paginated** and users need to select items beyond the
  visible page (e.g. bulk assign, bulk delete).
- The full set of matching IDs is fetched lazily via a separate lightweight
  query when the user explicitly clicks "Select all".
- The table supports **filters** and the selection should respect the
  currently applied filter set. Use the `selectAllLabel` prop to communicate
  that only matching items will be selected (e.g. "Select all matching assets
  in Service Plans").

### When **not** to use

- The table loads **all data at once** (no pagination). In that case the
  built-in header checkbox from `useTableSelection` already selects every
  row — there is nothing extra to select.
- The dataset is small enough that all rows fit on a single page.
- Selection is limited to a single row (e.g. a details panel use-case). 
```

- [Table](/ai?storyId=components-tables-table):
```md
Table displays large data sets with virtual scrolling, column sorting, filtering, resizing, drag-and-drop column reordering,
and row selection. It extends `@tanstack/react-table` and uses `useTable` to create the table instance.
Infinite scroll pagination is handled via `RelayPagination` from `usePaginationQuery`.

For the full TanStack Table API, see [TanStack Table docs](https://tanstack.com/table/v8/docs/guide/introduction).

### When to use
Use Table for displaying structured data with sorting, pagination, or row actions — for example, asset lists, event logs, or user management views.

### When not to use
Do not use Table for simple key-value displays — use a layout with `Text` components.
Do not use Table for small card-based lists — use `List`. 
```

- [useTablePersistence](/ai?storyId=hooks-react-table-usetablepersistence):
```md
Persists and restores table column state (order, sizing, visibility, sorting, pinning, expanded) using
the URL **hash fragment** and localStorage.

Storage scope:
- URL hash (shareable): `columnOrder`, `columnVisibility`, `sorting`, `columnPinning`, `columnSizing`.
- localStorage: everything above plus `expanded`.

The hash slot is used instead of search params because some deployments
route through AWS WAF, whose `SizeRestrictions_QUERYSTRING` managed rule
caps the query string at ~5000 bytes — easily breached by wide tables.
The fragment is client-only and bypasses that cap entirely (subject to a
64 KiB soft limit enforced by `useHashParamSync`).

Legacy compatibility: shared links that still use `?<persistenceKey>Tp=`
search params from before the hash migration are decoded on first load
and the search param is stripped via a `replace` navigation so old
bookmarks and forwarded URLs continue to restore state without polluting
browser history.

On mount, state is loaded from the hash (or legacy search param as a
one-shot fallback) and merged with localStorage so fields omitted from
the URL, such as `expanded`, still survive reloads. Changes are
debounced (300 ms) and synced to both the hash and localStorage.

`onTableStateChange` takes a *partial* state and merges it into whatever
was reported earlier in the session, so a consumer can report a single
slice (e.g. only `expanded`) without the omitted fields falling back to
their mount-time values. A field reported empty is dropped from the stored
state, and once every field is empty the entry is removed altogether. 
```

- [useTable](/ai?storyId=hooks-react-table-usetable):
```md
Hook for managing and controlling a table's state and behavior.

Wraps `@tanstack/react-table` with built-in state management for column visibility,
ordering, sorting, sizing, and pinning. Reads `meta.hiddenByDefault` and `meta.pinned`
from column definitions so the table is correctly configured from a single source of truth.

**When to use:**
- Use `useTable` whenever you render a `<Table>` component — it is the standard way to
  initialise and manage table state in this codebase.
- Use `useTableSelection` on top of `useTable` when you need row selection checkboxes.
- Do **not** call `useReactTable` directly — `useTable` adds required column-state
  orchestration that the raw hook does not provide.

Row expansion is managed like the column state: it starts from `initialState.expanded`, and
expand/collapse changes are reported to `onTableStateChange` so they can be persisted — unless
the consumer passes `state.expanded`, in which case it owns what is worth storing.

`onTableStateChange` is called with the field that changed, not the whole state, so anything
storing it has to merge each report into what it already holds. `useTablePersistence` does. 
```

- [useTableSelection](/ai?storyId=hooks-react-table-usetableselection):
```md
`useTableSelection` provides row selection state management for the Table component.
It returns a selection checkbox column definition, row selection state, and props to spread onto `useTable`.

### When to use
Use useTableSelection when your Table needs checkbox-based row selection — for example, bulk actions on selected assets.

### When not to use
Do not use useTableSelection if your table does not need row selection. For single-row actions, use `onRowClick` on the Table instead. 
```


- [ButtonCell](/ai?storyId=components-tables-cells-buttoncell):
```md
The `<ButtonCell>` component renders an interactive button within a table cell.
Uses a ghost-neutral variant by default for subtle inline actions.
Commonly used for quick actions on individual rows without opening a menu.

### When to use
- Provide a single quick action directly in a table cell
- When the action is contextual and specific to that row's data
- For inline edit, view details, or quick status change actions

### When not to use
- For multiple actions per row - use `RowActions` instead
- For primary page-level actions - use regular `Button` component
- For navigation links - use `LinkCell` or `IdentityCell` with link prop 
```

- [CheckboxCell](/ai?storyId=components-tables-cells-checkboxcell):
```md
CheckboxCell renders a read-only checkbox inside a table cell. The checkbox reflects a boolean value
but cannot be toggled by the user — it is purely for display purposes.

### When to use
Use CheckboxCell to display a boolean field (e.g., active/inactive, enabled/disabled) as a visual checkbox in a table column.

### When not to use
Do not use CheckboxCell for row selection — use `useTableSelection` which provides an interactive selection column. 
```

- [CopyableCell](/ai?storyId=components-tables-cells-copyablecell):
```md
CopyableCell renders a table cell with click-to-copy functionality.
Supports single-line and multi-line layouts.

### When to use
Use CopyableCell inside table column definitions when a cell value (ID, name, reference) should be copyable.

### When not to use
For standalone copyable text outside of tables, use `CopyableText` from `@trackunit/react-components`. 
```

- [DateTimeCell](/ai?storyId=components-tables-cells-datetimecell):
```md
The `<DateTimeCell>` component renders a formatted date/time in a table cell.
It displays the formatted date with an optional "time since" indicator
(e.g., "2 hours ago") on a second line for quick context.

### When to use
- Display timestamps, created/updated dates in tables
- When users need to quickly understand how recent an event was
- For date columns that benefit from relative time context

### When not to use
- For date-only display without time - use `PlainDateCell` instead
- For duration values - use `NumberCell` with appropriate units
- For editable date inputs - use form components instead 
```

- [HighlightCell](/ai?storyId=components-tables-cells-highlightcell):
```md
HighlightCell renders one or more colored highlight badges inside a table cell. Each highlight
can be a simple string (displayed with the default warning color) or an object with a custom color.
It is used to draw attention to out-of-range or notable values in a table row.

### When to use
Use HighlightCell to display threshold warnings, status flags, or tagged values inside a table column.

### When not to use
Do not use HighlightCell for general status indicators — use `IndicatorCell`. 
```

- [IdentityCell](/ai?storyId=components-tables-cells-identitycell):
```md
The `<IdentityCell>` component renders an identity or entity in a table cell,
typically showing a title with optional thumbnail and supporting details.
Commonly used for displaying assets, users, or other entities with rich metadata.

When displaying asset information, always use the `type` field
(e.g., "excavator", "boom lift") instead of `assetType` (e.g., "machine", "attachment").

### When to use
- Display entities with name + additional identifying details (model, serial number, etc.)
- When a thumbnail/avatar helps users identify the item
- For the primary identifying column in asset, user, or entity tables

### When not to use
- For simple text values - use `TextCell` instead
- For numeric data - use `NumberCell` instead
- For standalone links without identity context - use `LinkCell` instead 
```

- [ImageCell](/ai?storyId=components-tables-cells-imagecell):
```md
ImageCell renders a thumbnail image inside a table cell with configurable width, height, and alt text.
It is used to display asset photos, user avatars, or product images alongside other table data.

### When to use
Use ImageCell when a table column needs to display a thumbnail or image preview.

### When not to use
Do not use ImageCell for icons or status indicators — use `IndicatorCell`. 
```

- [IndicatorCell](/ai?storyId=components-tables-cells-indicatorcell):
```md
IndicatorCell renders a colored icon indicator with an optional text label inside a table cell.
It wraps the Indicator component and supports background highlighting, a pinging animation for urgency,
and hiding the label to show it on hover instead.

### When to use
Use IndicatorCell to display status indicators in a table — for example, online/offline status, health state, or connectivity.

### When not to use
Do not use IndicatorCell for text-based status labels — use `TextCell` or `NoticeCell`. 
```

- [LinkCell](/ai?storyId=components-tables-cells-linkcell):
```md
The `<LinkCell>` component renders a clickable link in a table cell.
Supports URLs, phone numbers (tel:), and email addresses (mailto:).
Clicking the link opens it without triggering the table row click handler.

### When to use
- Display clickable URLs, emails, or phone numbers in table columns
- When users need to contact someone or visit an external link from table data
- For contact information columns (email, phone)

### When not to use
- For internal navigation - use `IdentityCell` with link prop instead
- For action buttons - use `ButtonCell` or `RowActions` instead
- For non-interactive text - use `TextCell` instead 
```

- [MultiRowTableCell](/ai?storyId=components-tables-cells-multirowtablecell):
```md
MultiRowTableCell renders two stacked rows inside a single table cell — a primary `main` row
and a secondary row below it. String values are automatically styled with appropriate text sizes.

### When to use
Use MultiRowTableCell when a table cell needs to display a primary value with secondary metadata below —
for example, an asset name with its serial number, or a user name with their email.

### When not to use
Do not use MultiRowTableCell for single-line text — use `TextCell`. 
```

- [MultiValueTextCell](/ai?storyId=components-tables-cells-multivaluetextcell):
```md
The `<MultiValueTextCell>` component is used for displaying the text values with multiple values in a table cell. First element is displayed as a text, the rest of the values are displayed as a number. Icon can be passed as an optional prop.
The text content is not editable and will be truncated if the cell is too narrow. 
```

- [NoticeCell](/ai?storyId=components-tables-cells-noticecell):
```md
NoticeCell renders a Notice component inside a table cell, displaying an inline colored message
(info, warning, success, danger). It accepts the same props as Notice.

### When to use
Use NoticeCell to display contextual messages or status banners within a table row —
for example, a warning about an expired certificate or an info notice about a pending update.

### When not to use
Do not use NoticeCell for simple colored text — use `HighlightCell`. 
```

- [NumberCell](/ai?storyId=components-tables-cells-numbercell):
```md
The `<NumberCell>` component is used for displaying numbers with optional units in a table cell.
Numbers are right-aligned by default for easy scanning and comparison in data tables.

### When to use
- Display numeric values like quantities, measurements, or counts
- When values need to be accompanied by units (km, hours, %, etc.)
- For right-aligned numeric columns in data tables

### When not to use
- For non-numeric text content - use `TextCell` instead
- For dates and times - use `DateTimeCell` instead
- For formatted currency - consider specialized formatting 
```

- [PlainDateCell](/ai?storyId=components-tables-cells-plaindatecell):
```md
PlainDateCell renders a `Temporal.PlainDate` inside a table cell as a formatted date string.
By default it also shows the number of days since the date on a second line (e.g., "15 days ago").
Returns `null` when no date is provided.

### When to use
Use PlainDateCell for date columns in tables where you work with `Temporal.PlainDate` values —
for example, "Last Service Date" or "Created On" columns.

### When not to use
Do not use PlainDateCell for `Date` objects or ISO strings — use the `DateTime` component instead. 
```

- [RowActions](/ai?storyId=components-tables-cells-rowactions):
```md
The `<RowActions>` component displays contextual actions for a table row.
Automatically adapts its rendering based on the number of actions:
- Single action: renders as a standalone button
- Multiple actions: renders selected actions as icon buttons + overflow menu

Actions can be marked as `isSelected` to display them as quick-access icon buttons
outside the dropdown menu. Danger actions are automatically separated with a divider.

### When to use
- Provide row-level actions like Edit, Delete, Download, etc.
- When rows need multiple contextual actions
- For consistent action patterns across data tables

### When not to use
- For bulk actions on selected rows - use `ActionSheet` instead
- For a single simple action - consider `ButtonCell` for simpler UI
- For navigation - use `IdentityCell` with link prop 
```

- [SortIndicator](/ai?storyId=components-tables-base-components-sortindicator):
```md
SortIndicator renders ascending/descending arrow indicators in a table column header.
It is a visual-only component — it does not handle sorting logic. Set `sortingState` to
`"asc"`, `"desc"`, or `false` (hidden).

In most cases, use the Table component which handles sort indication automatically.
Use SortIndicator directly only when building custom table headers with the Table Base Components.

### When to use
Use SortIndicator in custom table header cells that need to show the current sort direction.

### When not to use
Do not use SortIndicator when using the `Table` component — sorting indicators are built in. 
```

- [TagsCell](/ai?storyId=components-tables-cells-tagscell):
```md
The `<TagsCell>` component renders a list of tags in a table cell.
Useful for displaying categories, labels, or status indicators in a compact format.

### When to use
- Display multiple tags, categories, or labels for an entity
- Show groupings, classifications, or metadata as visual tags
- When items have multiple attributes that should be shown together

### When not to use
- For a single status indicator - use `Tag` component directly or `IndicatorCell`
- For text content - use `TextCell` instead
- For interactive chip selection - use form components instead 
```

- [TextCell](/ai?storyId=components-tables-cells-textcell):
```md
The `<TextCell>` component is used for displaying text in a table cell.
The text is not editable and will be truncated with an ellipsis if the cell is too narrow.
When truncated, a tooltip automatically appears on hover showing the full content.

### When to use
- Display simple text values in table columns (names, descriptions, statuses)
- When text content might be longer than the column width
- For read-only text display in data grids

### When not to use
- For numeric values - use `NumberCell` instead
- For dates and times - use `DateTimeCell` instead
- For clickable links - use `LinkCell` or `ButtonCell` instead
- For multi-line content - consider `IdentityCell` with details 
```

- [WidgetError](/ai?storyId=components-widgets-empty-states-widgeterror):
```md
WidgetError displays a centered error empty state inside a widget. It shows an error illustration
and a message describing what went wrong. If no custom `description` is provided, a default
localized error message is shown.

### When to use
Use WidgetError inside a widget when data fetching or processing fails and the widget cannot render its normal content.

### When not to use
Do not use WidgetError for page-level errors — use a page-level error boundary or `Notice`.
Do not use it when the widget simply has no data — use `WidgetNoData` instead. 
```

- [WidgetMissingConfiguration](/ai?storyId=components-widgets-empty-states-widgetmissingconfiguration):
```md
WidgetMissingConfiguration displays a centered empty state inside a widget when it has not yet been configured.
It shows an illustration, a localized description, and a "Configure" button that opens the widget's edit mode
via `WidgetConfigRuntime.openEditMode()`. This component takes no props — all text is localized automatically.

### When to use
Use WidgetMissingConfiguration when a configurable widget is rendered for the first time and requires
user setup before it can display data (e.g., selecting a data source or configuring thresholds).

### When not to use
Do not use WidgetMissingConfiguration when the widget has been configured but has no data — use `WidgetNoData`.
Do not use it for error states — use `WidgetError`. 
```

- [WidgetNoData](/ai?storyId=components-widgets-empty-states-widgetnodata):
```md
WidgetNoData displays a centered empty state inside a widget when there is no data to show.
It renders an illustration and a description message. The `type` prop controls the illustration tone:
`"Good"` indicates a positive empty state (e.g., no alerts), while `"Neutral"` indicates a neutral absence of data.

### When to use
Use WidgetNoData when a widget's data source returns an empty result set and you want to communicate that clearly.

### When not to use
Do not use WidgetNoData for error states — use `WidgetError`.
Do not use it when the widget requires configuration — use `WidgetMissingConfiguration`. 
```

- [WidgetContent](/ai?storyId=components-widgets-widgetcontent):
```md
WidgetContent is the layout foundation for all widget body content. It provides CSS Grid-based
layout structures, responsive padding, spacing between child elements, and optional centering.
The padding intentionally lives on this component (not on the Widget wrapper) so that overflow
scrollbars are not inset.

### Layout options
- `"none"` — basic stacking with no grid structure
- `"top-fill"` — fixed-height header (first child) with remaining space filled by content
- `"fill-bottom"` — content fills available space with a fixed-height footer at the bottom
- `"top-fill-bottom"` — fixed header, flexible middle, and fixed footer

### When to use
Use WidgetContent as the direct child of a widget `Card` to structure its body — for example, a `KPI` at the top with a chart filling the rest.

### When not to use
Do not use WidgetContent outside a widget context. For general page layout, use `Page` and `PageContent`. 
```

- [WidgetKPI](/ai?storyId=components-widgets-widgetkpi):
```md
The KPI Widget is a compact and flexible component designed to surface key metrics in a clear, impactful way. It provides at-a-glance insights through bold values, concise labels, and optional contextual elements such as trend indicators or time zones. Its goal is to drive user attention toward meaningful data that prompts action. 
```