@trackunit/react-components 1.17.22 → 1.17.24

package/index.esm.js

@@ -118,10 +118,27 @@ const isSafari = () => {
     return ua.includes("safari") && !ua.includes("chrome");
 };
 /**
- * Icons help in making the interface more intuitive by providing visual cues for various actions or elements. They're used to enhance usability, and depending on the context, they can be used alone or paired with text to increase comprehension.
+ * 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.
  *
- * All the [HeroIcons](https://heroicons.com/) as well as custom Trackunit icons are available.
+ * ### 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.
+ *
+ * @example Icons at different sizes
+ * ```tsx
+ * import { Icon } from "@trackunit/react-components";
  *
+ * const IconExamples = () => (
+ *   <div className="flex items-center gap-4">
+ *     <Icon name="MapPin" size="small" color="danger" />
+ *     <Icon name="Truck" size="medium" color="primary" />
+ *     <Icon name="Cog6Tooth" size="large" type="outline" />
+ *   </div>
+ * );
+ * ```
  * @param {IconProps} props - The props for the Icon component
  * @returns {ReactElement} Icon component
  */
@@ -245,14 +262,21 @@ const cvaTagIcon = cvaMerge(["cursor-pointer", "transition-opacity", "hover:opac
 
 const TAG_TEXT_MIN_WIDTH_PX = parseTailwindArbitraryValue(TAG_TEXT_MIN_WIDTH_CLASS);
 /**
- * The Tag component is used for labeling or categorizing items in the UI.
- * It's commonly used to indicate the status of an asset, mark a feature as Beta,
- * or display selected options in multi-select inputs.
+ * 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.
  *
- * How to choose between Tag, Badge and Highlight?
+ * ### 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](https://design.iris.trackunit.com/?path=/docs/react-components-badge--docs) to indicate notifications or counts of applied elements, such as filters.
- * - Use a [Highlight](https://design.iris.trackunit.com/?path=/docs/react-components-highlight--docs) to draw attention to values in plain text that require special attention or have crossed a threshold.
+ * - 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.
  *
  * @example Status tags with different colors
  * ```tsx
@@ -499,12 +523,37 @@ const cvaText = cvaMerge(["text-black", "m-0", "relative", "text-sm", "font-norm
 });
 
 /**
- *  The Text component is used to apply Trackunit default typography styles to text.
+ * 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.
  *
- *  ### When to use
+ * @example Text with different sizes and weights
+ * ```tsx
+ * import { Text } from "@trackunit/react-components";
  *
- *  Use Text when you want to show a text section, use Heading if you want to show a heading.
+ * const TextExamples = () => (
+ *   <div>
+ *     <Text size="large" weight="bold">Large bold text</Text>
+ *     <Text size="medium">Default body text</Text>
+ *     <Text size="small" subtle>Small subtle caption</Text>
+ *   </div>
+ * );
+ * ```
+ * @example Inline text using span
+ * ```tsx
+ * import { Text } from "@trackunit/react-components";
  *
+ * const InlineExample = () => (
+ *   <Text>
+ *     Asset status: <Text type="span" weight="bold">Active</Text>
+ *   </Text>
+ * );
+ * ```
  * @param {TextProps} props - The props for the Text component
  * @returns {ReactElement} Text component
  */
@@ -567,16 +616,37 @@ const cvaSpinnerContainer = cvaMerge(["box-border", "p-0.5", "overflow-hidden"],
 const cvaSpinnerLabel = cvaMerge(["self-center", "text-center", "text-current"]);
 
 /**
- * The spinner component provides visual feedback that data is being processed.
+ * 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.
  *
- * Spinners are used when performing actions. They notify to the user that their request is being processed. Although they do not provide details about what is occurring on the back-end, they reassure the user that their action is being processed.
+ * ### 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.
  *
- * Common actions that benefit from spinners include any create, update, or delete actions that may have a lot of data to process. It can be used in a table, after a primary or secondary button click, or even in a modal.
+ * @example Centered spinner during data load
+ * ```tsx
+ * import { Spinner } from "@trackunit/react-components";
  *
- * Use a spinner component for any action that cannot be performed instantly and will only require a short time (between 1 to 5 seconds) to process.
+ * const LoadingContent = () => (
+ *   <div className="h-64">
+ *     <Spinner centering="centered" label="Loading assets..." />
+ *   </div>
+ * );
+ * ```
+ * @example Small inline spinner
+ * ```tsx
+ * import { Spinner } from "@trackunit/react-components";
  *
- * Use when retrieving or refreshing small data amounts, such as status.
- 
+ * const InlineLoading = () => (
+ *   <div className="flex items-center gap-2">
+ *     <Spinner size="small" centering="vertically" />
+ *     <span>Saving...</span>
+ *   </div>
+ * );
+ * ```
  * @param {SpinnerProps} props - The props for the Spinner component
  * @returns {ReactElement} Spinner component
  */
@@ -862,7 +932,7 @@ const cvaIconButton = cvaMerge([], {
  * 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](?path=/docs/components-link--docs) when the desired action is to take the user to a new page.
+ * Do not use buttons as navigational elements. Instead, use `Links` when the desired action is to take the user to a new page.
  *
  * @example Basic button with click handler
  * ```tsx
@@ -1212,14 +1282,21 @@ const cvaBadge = cvaMerge([
 });
 
 /**
- * The Badge component is used to indicate notifications or counts of applied elements.
- * It's typically used to display numbers on elements like filters, tabs, or buttons.
+ * 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?
+ * How to choose between Badge and `Tag`?
  * - Use a Badge to indicate notifications or counts of applied elements.
- * - Use a [Tag](https://design.iris.trackunit.com/?path=/docs/react-components-tag--docs) for labeling statuses, categories, or selections.
+ * - Use a `Tag` for labeling statuses, categories, or selections.
  *
- * @example Badge with count and max value
+ * @example Badge with count and max — Use `count` and `max` to show a capped notification count. Values above `max` display as "9+".
  * ```tsx
  * import { Badge, Button } from "@trackunit/react-components";
  *
@@ -1229,7 +1306,7 @@ const cvaBadge = cvaMerge([
  *   </Button>
  * );
  * ```
- * @example Compact badge as status dot
+ * @example Compact status dot — Set `compact` to render a small colored dot without any count, useful for online/offline indicators.
  * ```tsx
  * import { Badge } from "@trackunit/react-components";
  *
@@ -1478,8 +1555,25 @@ const BreadcrumbContainer = ({ "data-testid": dataTestId, breadcrumbItems, }) =>
 };
 
 /**
- * The StarButton component is used for favorite actions or similar.
+ * StarButton renders a clickable star icon for toggling favorite/starred state.
+ * The star appears in the primary color when starred and neutral when unstarred.
  *
+ * ### When to use
+ * Use StarButton for favorite or bookmark actions on list items, cards, or tables.
+ *
+ * ### When not to use
+ * Do not use StarButton for primary actions — use `Button` or `IconButton`.
+ *
+ * @example Star button for favoriting an asset
+ * ```tsx
+ * import { StarButton } from "@trackunit/react-components";
+ * import { useState } from "react";
+ *
+ * const FavoriteToggle = () => {
+ *   const [starred, setStarred] = useState(false);
+ *   return <StarButton starred={starred} onClick={() => setStarred(s => !s)} />;
+ * };
+ * ```
  * @param {StarButtonProps} props - The props for the StarButton component
  * @returns {ReactElement} StarButton component
  */
@@ -1627,10 +1721,45 @@ const Card = ({ children, onClick, fullHeight = false, onMouseEnter, onMouseLeav
 Card.displayName = "Card";
 
 /**
- * The CardBody component should be used to inform the user of important information.
+ * CardBody is the main content area of a Card. It provides consistent padding and gap between child elements.
+ * Padding is applied here rather than on the Card itself to avoid insetting the scrollbar when content overflows.
+ *
+ * Use CardBody inside a Card to wrap the primary content.
+ * It works alongside CardHeader and CardFooter.
+ *
+ * ### When to use
+ * Use CardBody to wrap the main content area of a `Card`. It handles padding, gap, and flex direction so content is laid out consistently.
  *
- * @summary For applying padding and gap to a Card.
- * @description The padding must live here, and not on the Card itself, as to not inset the scrollbar in case of overflow
+ * ### When not to use
+ * Do not use CardBody outside of a `Card`. For standalone content layout, use standard flex or grid containers.
+ *
+ * @example Basic card body inside a card
+ * ```tsx
+ * import { Card, CardHeader, CardBody, Text } from "@trackunit/react-components";
+ *
+ * const AssetInfo = () => (
+ *   <Card>
+ *     <CardHeader heading="Asset Details" />
+ *     <CardBody>
+ *       <Text>Operating hours: 1,234</Text>
+ *       <Text>Status: Active</Text>
+ *     </CardBody>
+ *   </Card>
+ * );
+ * ```
+ * @example Card body with custom direction and no gap
+ * ```tsx
+ * import { Card, CardBody } from "@trackunit/react-components";
+ *
+ * const HorizontalLayout = () => (
+ *   <Card>
+ *     <CardBody direction="row" gap="none" padding="none">
+ *       <div>Left section</div>
+ *       <div>Right section</div>
+ *     </CardBody>
+ *   </Card>
+ * );
+ * ```
  * @param {CardBodyProps} props - The props for the CardBody component
  * @returns {ReactElement} CardBody component
  */
@@ -1644,10 +1773,51 @@ const CardBody = ({ children, "data-testid": dataTestId, className, direction =
 };
 
 /**
- * A simple footer intended to use with Cards and Modals.
- * Currently only intended to contain Buttons.
- * The buttons justifies to the right, but if you style a button with "margin-right: auto" it will move to the left
+ * CardFooter provides a consistent footer section for a Card, typically containing action buttons.
+ * Buttons are right-justified by default. To push a button to the left, apply `margin-right: auto` to it.
+ *
+ * Use CardFooter as the last child inside a Card, below CardBody.
+ *
+ * ### When to use
+ * Use CardFooter to add action buttons (e.g., Save, Cancel, View Details) at the bottom of a `Card` or Modal.
+ *
+ * ### When not to use
+ * Do not use CardFooter for content display. It is designed specifically for action buttons and controls.
  *
+ * @example Card with footer actions
+ * ```tsx
+ * import { Card, CardHeader, CardBody, CardFooter, Button, Text } from "@trackunit/react-components";
+ *
+ * const ConfirmationCard = () => (
+ *   <Card>
+ *     <CardHeader heading="Confirm Action" />
+ *     <CardBody>
+ *       <Text>Are you sure you want to proceed?</Text>
+ *     </CardBody>
+ *     <CardFooter>
+ *       <Button variant="secondary">Cancel</Button>
+ *       <Button variant="primary">Confirm</Button>
+ *     </CardFooter>
+ *   </Card>
+ * );
+ * ```
+ * @example Footer with left-aligned and right-aligned buttons
+ * ```tsx
+ * import { Card, CardBody, CardFooter, Button, Text } from "@trackunit/react-components";
+ *
+ * const FormCard = () => (
+ *   <Card>
+ *     <CardBody>
+ *       <Text>Form content here</Text>
+ *     </CardBody>
+ *     <CardFooter>
+ *       <Button variant="secondary-danger" className="mr-auto">Delete</Button>
+ *       <Button variant="secondary">Cancel</Button>
+ *       <Button variant="primary">Save</Button>
+ *     </CardFooter>
+ *   </Card>
+ * );
+ * ```
  * @param {CardFooterProps} props - The props for the CardFooter component
  * @returns {ReactElement} CardFooter component
  */
@@ -1691,8 +1861,29 @@ const cvaHeading = cvaMerge(["m-0", "leading-normal", "text-black"], {
 });
 
 /**
- * The Heading is used for a heading of a section (h1,h2,h3,h4).
+ * 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`.
  *
+ * @example Heading variants
+ * ```tsx
+ * import { Heading } from "@trackunit/react-components";
+ *
+ * const HeadingExamples = () => (
+ *   <div>
+ *     <Heading variant="primary">Page Title (h1)</Heading>
+ *     <Heading variant="secondary">Section Title (h2)</Heading>
+ *     <Heading variant="tertiary">Subsection (h3)</Heading>
+ *     <Heading variant="subtitle" subtle>Subtitle (h4)</Heading>
+ *   </div>
+ * );
+ * ```
  * @param {HeadingProps} props - The props for the Heading component
  * @returns {ReactElement} Heading component
  */
@@ -1712,8 +1903,49 @@ const Heading = ({ variant = "primary", inverted = false, subtle = false, classN
 };
 
 /**
- * Header for Cards.
+ * CardHeader provides a consistent header section for a Card, including a heading, optional subheading, accessories, and action buttons.
+ * It is designed to be used as the first child inside a Card, above CardBody.
+ *
+ * ### When to use
+ * Use CardHeader when a `Card` needs a title and optional actions (e.g., close button, edit button). It handles heading layout, separator lines, and action placement.
+ *
+ * ### When not to use
+ * Do not use CardHeader outside of a `Card`. For standalone section titles, use `SectionHeader` or `Heading` instead.
  *
+ * @example Card header with heading and actions
+ * ```tsx
+ * import { Card, CardHeader, CardBody, Button, Text } from "@trackunit/react-components";
+ *
+ * const AssetCard = () => (
+ *   <Card>
+ *     <CardHeader
+ *       heading="Excavator #1234"
+ *       subHeading="Last updated: 2 hours ago"
+ *       actions={<Button variant="ghost" size="small">Edit</Button>}
+ *     />
+ *     <CardBody>
+ *       <Text>Operating hours: 1,234</Text>
+ *     </CardBody>
+ *   </Card>
+ * );
+ * ```
+ * @example Card header with accessories and no separator
+ * ```tsx
+ * import { Card, CardHeader, CardBody, Badge, Text } from "@trackunit/react-components";
+ *
+ * const NotificationsCard = () => (
+ *   <Card>
+ *     <CardHeader
+ *       heading="Notifications"
+ *       accessories={<Badge count={5} color="primary" />}
+ *       hideSeparator
+ *     />
+ *     <CardBody>
+ *       <Text>Notification list here</Text>
+ *     </CardBody>
+ *   </Card>
+ * );
+ * ```
  * @param {CardHeaderProps} props - The props for the CardHeader component
  * @returns {ReactElement} CardHeader component
  */
@@ -2010,17 +2242,26 @@ const Collapsible = ({ children, expanded, id, variant, extraPadding }) => {
 };
 
 /**
- * A component that displays a visual indicator based on the completion status.
+ * CompletionStatusIndicator displays a visual icon or spinner based on a process completion status:
+ * loading (spinner), success (green check circle), or error (red X circle). Returns null if no status flag is set.
  *
- * @example
- * <CompletionStatusIndicator loading={true} />
- * <CompletionStatusIndicator error={true} />
- * <CompletionStatusIndicator success={true} />
- * @param {CompletionStatusIndicatorProps} props - The properties for the indicator.
- * @param {boolean} props.loading - Indicates if the process is in a loading state.
- * @param {boolean} props.error - Indicates if an error has occurred.
- * @param {boolean} props.warning - Indicates if the process has a warning.
- * @param {boolean} props.success - Indicates if the process was successful.
+ * ### When to use
+ * Use CompletionStatusIndicator to show inline feedback for async operations (e.g., form submissions, save actions, data syncs).
+ *
+ * ### When not to use
+ * Do not use for page-level loading — use `Spinner`.
+ * Do not use for persistent status labels — use `Tag` or `Notice`.
+ *
+ * @example Completion status for a save action
+ * ```tsx
+ * import { CompletionStatusIndicator } from "@trackunit/react-components";
+ *
+ * const SaveStatus = ({ saving, saved, failed }: { saving: boolean; saved: boolean; failed: boolean }) => (
+ *   <CompletionStatusIndicator loading={saving} success={saved} error={failed} />
+ * );
+ * ```
+ * @param {CompletionStatusIndicatorProps} props - The props for the CompletionStatusIndicator component
+ * @returns {ReactElement | null} CompletionStatusIndicator component, or null when no status flag is set
  */
 const CompletionStatusIndicator = ({ loading = false, error, success, ...rest }) => {
     if (loading) {
@@ -2129,8 +2370,34 @@ const cvaCopyableText = cvaMerge([
 });
 
 /**
- * The CopyableText component is used where the user should have easy access to copy information.
- 
+ * CopyableText displays a text value that the user can click to copy to the clipboard.
+ * It shows a brief animation on copy to provide visual feedback. The copied value can differ from the displayed text via `alternativeText`.
+ *
+ * ### When to use
+ * Use CopyableText for identifiers, serial numbers, URLs, or any value the user may want to copy (e.g., asset IDs, error codes).
+ *
+ * ### When not to use
+ * Do not use CopyableText for long paragraphs or content that doesn't need to be copied.
+ *
+ * @example Copyable serial number
+ * ```tsx
+ * import { CopyableText } from "@trackunit/react-components";
+ *
+ * const AssetSerial = () => (
+ *   <CopyableText text="SN-2024-00142" data-testid="serial-number" />
+ * );
+ * ```
+ * @example Copyable text with alternative clipboard value
+ * ```tsx
+ * import { CopyableText } from "@trackunit/react-components";
+ *
+ * const AssetLink = () => (
+ *   <CopyableText
+ *     text="Excavator #1234"
+ *     alternativeText="https://app.trackunit.com/assets/1234"
+ *   />
+ * );
+ * ```
  * @param {CopyableTextProps} props - The props for the CopyableText component
  * @returns {ReactElement} CopyableText component
  */
@@ -2158,14 +2425,35 @@ const cvaDetailsList = cvaMerge(["flex", "w-full", "min-w-0", "items-center", "t
 const cvaDetailsListItem = cvaMerge(["last:truncate"]);
 
 /**
- * Renders a one-line list of details separated by a Slash icon.
+ * DetailsList renders a one-line list of text values separated by slash icons.
+ * It is used to display compact metadata such as model, serial number, or location in a single row.
+ *
+ * ### When to use
+ * Use DetailsList to display a compact, horizontal list of metadata values (e.g., in a card subtitle or list item description).
+ *
+ * ### When not to use
+ * Do not use DetailsList for key-value pairs — use a standard layout with labels. Do not use for long text — values should be short strings.
+ *
+ * @example Displaying asset metadata
+ * ```tsx
+ * import { DetailsList } from "@trackunit/react-components";
+ *
+ * const AssetMeta = () => (
+ *   <DetailsList details={["Excavator", "CAT 320", "SN-00142"]} />
+ * );
+ * ```
+ * @example DetailsList inside a linked context
+ * ```tsx
+ * import { DetailsList } from "@trackunit/react-components";
  *
- * @param {object} props - Component props.
- * @param {string[]} props.details - Values to render.
- * @param {string} [props.className] - Optional CSS class for customization.
- * @param {boolean} [props.hasLink=false] - Whether the parent component contains a link.
- * @param [props.ref] - Ref forwarded to the root element.
- * @returns {ReactElement} The details list element.
+ * const LinkedAssetMeta = () => (
+ *   <a href="/assets/123">
+ *     <DetailsList details={["Site: Oslo", "Group: Heavy"]} hasLink />
+ *   </a>
+ * );
+ * ```
+ * @param {DetailsListProps} props - The props for the DetailsList component
+ * @returns {ReactElement} DetailsList component
  */
 const DetailsList = ({ details, className, hasLink = false, ref }) => {
     return (jsx("div", { className: cvaDetailsList({ className, hasLink }), ref: ref, children: details.map((value, index, array) => (jsxs(Fragment, { children: [jsx("span", { className: cvaDetailsListItem({ className }), children: value }), index < array.length - 1 && (jsx("div", { className: "mx-0.5 flex items-center", children: jsx(Icon, { className: "w-4 text-neutral-300", color: "neutral", name: "Slash", size: "small" }) }))] }, index))) }));
@@ -2301,13 +2589,29 @@ const cvaSkeleton = cvaMerge([
 });
 
 /**
- * Display a single placeholder line for text content before data gets loaded to reduce load-time frustration.
+ * 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`.
  *
- * Reduces height and adds vertical margins to match the visual space text occupies within its line-height.
- * Uses text-size keys (text-xs, text-sm, text-base, etc.) for height to match actual text elements.
+ * @example Skeleton label for a title and description
+ * ```tsx
+ * import { SkeletonLabel } from "@trackunit/react-components";
  *
- * For multiple text lines, use SkeletonLines component instead.
- * For shape-based elements (images, badges, buttons), use SkeletonBlock component instead.
+ * const TextSkeleton = () => (
+ *   <div className="flex flex-col gap-1">
+ *     <SkeletonLabel textSize="text-lg" width={200} />
+ *     <SkeletonLabel textSize="text-sm" width="80%" />
+ *   </div>
+ * );
+ * ```
+ * @param {SkeletonLabelProps} props - The props for the SkeletonLabel component
+ * @returns {ReactElement} SkeletonLabel component
  */
 const SkeletonLabel = memo((props) => {
     const { width = "100%", textSize = "text-base", flexibleWidth = true, className, "data-testid": dataTestId, children, ref, } = props;
@@ -2457,8 +2761,26 @@ const EmptyState = ({ description, altText, image = "SEARCH_DOCUMENT", customIma
 const cvaEmptyValue = cvaMerge(["text-neutral-400"]);
 
 /**
- *  The EmptyValue component renders a consistent "–" symbol to represent empty, null, undefined, or not applicable values in tables.
+ * 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.
+ *
+ * @example Empty value in a details row
+ * ```tsx
+ * import { EmptyValue, Text } from "@trackunit/react-components";
  *
+ * const AssetDetail = ({ value }: { value?: string }) => (
+ *   <div className="flex justify-between">
+ *     <Text weight="bold">Serial Number</Text>
+ *     {value ? <Text>{value}</Text> : <EmptyValue />}
+ *   </div>
+ * );
+ * ```
  * @param {EmptyValueProps} props - The props for the EmptyValue component
  * @returns {ReactElement} EmptyValue component
  */
@@ -2498,10 +2820,41 @@ const cvaExternalLink = cvaMerge(["underline", "decoration-[1.5px]", "underline-
 });
 
 /**
- *  Link is an interactive element that allows users to navigate between different parts of an application or to external resources. Links are used to indicate clickable text.
- 
- * @param {ExternalLinkProps} props - The props for the external link component
- * @returns {ReactElement} External Link component
+ * ExternalLink renders an anchor element for navigating to external URLs. It opens in a new tab by default with `rel="noreferrer"` for security.
+ * If no children are provided, the href URL is displayed as the link text.
+ *
+ * ### When to use
+ * Use ExternalLink for any links that navigate to external resources outside the application (e.g., documentation, support pages, vendor sites).
+ *
+ * ### When not to use
+ * Do not use ExternalLink for in-app navigation. Use `Link` from `@tanstack/react-router` for internal routes.
+ *
+ * @example Basic external link
+ * ```tsx
+ * import { ExternalLink } from "@trackunit/react-components";
+ *
+ * const SupportLink = () => (
+ *   <ExternalLink href="https://support.trackunit.com">
+ *     Visit Support Center
+ *   </ExternalLink>
+ * );
+ * ```
+ * @example Neutral colored link opening in same window
+ * ```tsx
+ * import { ExternalLink } from "@trackunit/react-components";
+ *
+ * const DocumentLink = () => (
+ *   <ExternalLink
+ *     href="https://docs.trackunit.com/api"
+ *     color="neutral"
+ *     target="_self"
+ *   >
+ *     API Documentation
+ *   </ExternalLink>
+ * );
+ * ```
+ * @param {ExternalLinkProps} props - The props for the ExternalLink component
+ * @returns {ReactElement} ExternalLink component
  */
 const ExternalLink = ({ rel = "noreferrer", target = "_blank", href, className, children = href, title = href, "data-testid": dataTestId, onClick, color = "primary", ref, }) => {
     return (jsx("a", { className: cvaExternalLink({ className, color }), "data-testid": dataTestId, href: href, onClick: onClick, ref: ref, rel: rel, target: target, title: title, children: children }));
@@ -3293,15 +3646,40 @@ const cvaHighlight = cvaMerge([
 const cvaHighlightText = cvaMerge(["truncate"]);
 
 /**
- * The Highlight component is used to draw attention to data values that may require user action, monitoring, or investigation.
- * It visually emphasizes out-of-range or critical values using color cues (e.g. danger or warning) to support quick scanning and awareness.
+ * 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`.
+ *
+ * @example Highlighting a warning value
+ * ```tsx
+ * import { Highlight, Text } from "@trackunit/react-components";
  *
- * How to choose between Highlight and Tag?
- * - Use Highlight to draw attention to values in plain text that require special attention or have crossed a threshold.
- * - Use a [Tag](https://design.iris.trackunit.com/?path=/docs/react-components-tag--docs) for labeling statuses, categories, or selections.
+ * const TemperatureDisplay = () => (
+ *   <Text>
+ *     Engine temperature: <Highlight color="warning">92°C</Highlight>
+ *   </Text>
+ * );
+ * ```
+ * @example Different highlight colors for thresholds
+ * ```tsx
+ * import { Highlight } from "@trackunit/react-components";
  *
- * @param {HighlightProps} props - The props for the highlight component
- * @returns {ReactElement} highlight component
+ * const BatteryStatus = () => (
+ *   <div className="flex gap-2">
+ *     <Highlight color="success">85%</Highlight>
+ *     <Highlight color="warning">32%</Highlight>
+ *     <Highlight color="danger">8%</Highlight>
+ *   </div>
+ * );
+ * ```
+ * @param {HighlightProps} props - The props for the Highlight component
+ * @returns {ReactElement} Highlight component
  */
 const Highlight = ({ className, "data-testid": dataTestId, children, size = "small", color = "warning", ref, }) => {
     return (jsx("div", { className: cvaHighlight({ className, size, color }), "data-testid": dataTestId, ref: ref, children: jsx("span", { className: cvaHighlightText(), children: children }) }));
@@ -3563,11 +3941,30 @@ const cvaZStackContainer = cvaMerge(["grid", "grid-cols-1", "grid-rows-1", "isol
 const cvaZStackItem = cvaMerge(["col-start-1", "col-end-1", "row-start-1", "row-end-2"]);
 
 /**
- * ZStack is a component that stacks its children on the z-axis.
- * Is a good alternative to "position: absolute" that avoids some of the unfortunate side effects of absolute positioning.
+ * 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.
  *
- * @param { ZStackProps} props - The props for the  ZStack component
- * @returns {Element}  ZStack component
+ * @example Overlaying a badge on a thumbnail
+ * ```tsx
+ * import { ZStack, Badge, Icon } from "@trackunit/react-components";
+ *
+ * const ThumbnailWithBadge = () => (
+ *   <ZStack>
+ *     <Icon name="Truck" size="large" />
+ *     <div className="self-start justify-self-end">
+ *       <Badge count={3} color="danger" />
+ *     </div>
+ *   </ZStack>
+ * );
+ * ```
+ * @param {ZStackProps} props - The props for the ZStack component
+ * @returns {ReactElement} ZStack component
  */
 const ZStack = ({ children, className, "data-testid": dataTestId, ref }) => {
     return (jsx("div", { className: cvaZStackContainer({ className }), "data-testid": dataTestId, ref: ref, children: Children.map(children, (child, index) => {
@@ -3633,16 +4030,31 @@ const OverflowIndicator = ({ className, "data-testid": dataTestId, direction, on
 };
 
 /**
- * Container for displaying components in a horizontal layout with overflow detection.
- * Provides visual indicators when content overflows and can be scrolled.
+ * 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.
  *
- * @param props - Component properties
- * @param props.children - The content to display in the horizontal scroller
- * @param props.className - Optional CSS class name for styling
- * @param props."data-testid" - Optional test ID for testing purposes
- * @param props.onScrollStateChange - Optional callback fired when scroll state changes
- * @param [props.ref] - Ref forwarded to the root element
- * @returns {ReactElement} A horizontal overflow scroller component with visual indicators
+ * ### 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.
+ *
+ * @example Horizontal scroller for KPI cards
+ * ```tsx
+ * import { HorizontalOverflowScroller, Tag } from "@trackunit/react-components";
+ *
+ * const TagRow = () => (
+ *   <HorizontalOverflowScroller>
+ *     <Tag color="success">Active</Tag>
+ *     <Tag color="warning">Idle</Tag>
+ *     <Tag color="danger">Offline</Tag>
+ *     <Tag color="info">Maintenance</Tag>
+ *     <Tag color="neutral">Archived</Tag>
+ *   </HorizontalOverflowScroller>
+ * );
+ * ```
+ * @param {HorizontalOverflowScrollerProps} props - The props for the HorizontalOverflowScroller component
+ * @returns {ReactElement} HorizontalOverflowScroller component
  */
 const HorizontalOverflowScroller = ({ className, "data-testid": dataTestId, children, onScrollStateChange, ref, }) => {
     const childrenArray = Children.toArray(children);
@@ -3886,14 +4298,16 @@ const usePopoverContext = () => {
     return context;
 };
 /**
- * The popover component.
- * - This component should wrap all the popover components.
- * - It returns a context that is used by the popover components.
- * - The context is used to share the state of the popover, such as the open state and the reference element.
+ * 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.
  *
- * To open the popover, use the `<PopoverTrigger />` component.
+ * ### When to use
+ * Use Popover for contextual information, menus, or forms that should appear near a trigger element without navigating away.
  *
- * To render the content of the popover, use the `<PopoverContent />` component.
+ * ### 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.
  *
  * @example Basic popover with trigger
  * ```tsx
@@ -3962,10 +4376,41 @@ const getDefaultPortalContainer = () => {
 };
 
 /**
- * Portals the floating element into a given container element
- * By default they're portalled into an z-index isolated div in
- * document body -> div#portal-container.
- * alongside other portalled elements.
+ * 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.
+ *
+ * @example Rendering into a specific container
+ * ```tsx
+ * import { Portal } from "@trackunit/react-components";
+ *
+ * const PortalledContent = () => (
+ *   <Portal root={document.getElementById('sidebar-container')}>
+ *     <div className="p-4">This content renders in #sidebar-container</div>
+ *   </Portal>
+ * );
+ * ```
+ * @example Default portal into document body
+ * ```tsx
+ * import { Portal } from "@trackunit/react-components";
+ *
+ * const FloatingContent = ({ isVisible }: { isVisible: boolean }) => (
+ *   isVisible ? (
+ *     <Portal>
+ *       <div className="fixed bottom-4 right-4 bg-white p-4 rounded-lg shadow-lg">
+ *         Toast notification content
+ *       </div>
+ *     </Portal>
+ *   ) : null
+ * );
+ * @param {PortalProps} props - The props for the Portal component
+ * @returns {ReactElement} Portal component
  */
 const Portal = (props) => {
     return jsx(FloatingPortal, { ...props, root: props.root ?? getDefaultPortalContainer() });
@@ -3983,11 +4428,37 @@ const cvaPopoverTitleContainer = cvaMerge(["flex", "items-center", "px-2", "py-1
 const cvaPopoverTitleText = cvaMerge(["flex-1", "text-neutral-500"]);
 
 /**
- * The PopoverContent component displays the content inside a popover overlay.
+ * PopoverContent displays the floating content inside a Popover.
+ * It renders in a portal and manages focus, positioning, and accessibility. Must be a child of a Popover.
  *
- * This component must be used within a `<Popover>` component. It renders the content
- * in a portal and manages focus, positioning, and accessibility features.
+ * The `children` prop can be a ReactNode or a render function that receives a `close` callback to programmatically dismiss the popover.
  *
+ * ### When to use
+ * Use PopoverContent inside a `Popover` to define what appears in the floating overlay.
+ *
+ * ### When not to use
+ * Do not use PopoverContent outside of a `Popover` context. It relies on `Popover`'s context for positioning and state.
+ *
+ * @example PopoverContent with close callback
+ * ```tsx
+ * import { Popover, PopoverTrigger, PopoverContent, Button, Text } from "@trackunit/react-components";
+ *
+ * const DismissablePopover = () => (
+ *   <Popover>
+ *     <PopoverTrigger>
+ *       <Button variant="secondary">Open</Button>
+ *     </PopoverTrigger>
+ *     <PopoverContent>
+ *       {(close) => (
+ *         <div className="p-4">
+ *           <Text>Popover content here</Text>
+ *           <Button onClick={close} size="small">Done</Button>
+ *         </div>
+ *       )}
+ *     </PopoverContent>
+ *   </Popover>
+ * );
+ * ```
  * @param {PopoverContentProps} props - The props for the PopoverContent component
  * @returns {ReactElement} The popover content element
  */
@@ -4004,8 +4475,34 @@ const PopoverContent = function PopoverContent({ className, "data-testid": dataT
 };
 
 /**
- * The PopoverTrigger component is used to trigger the popover.
+ * PopoverTrigger is the clickable element that opens or closes a Popover.
+ * It must be used as a direct child of a Popover component. By default, it clones the child element and attaches popover behavior.
+ * Set `renderButton` to true to wrap children in a default Button.
+ *
+ * ### When to use
+ * Use PopoverTrigger inside a `Popover` to designate which element opens the popover overlay.
+ *
+ * ### When not to use
+ * Do not use PopoverTrigger outside of a `Popover` context. It relies on `Popover`'s context for state management.
+ *
+ * @example PopoverTrigger with a custom button
+ * ```tsx
+ * import { Popover, PopoverTrigger, PopoverContent, IconButton, Icon } from "@trackunit/react-components";
  *
+ * const IconPopover = () => (
+ *   <Popover placement="bottom">
+ *     <PopoverTrigger>
+ *       <IconButton
+ *         icon={<Icon name="InformationCircle" size="small" />}
+ *         variant="ghost"
+ *       />
+ *     </PopoverTrigger>
+ *     <PopoverContent>
+ *       <div className="p-3">Helpful information</div>
+ *     </PopoverContent>
+ *   </Popover>
+ * );
+ * ```
  * @param {PopoverTriggerProps} props - The props for the PopoverTrigger component
  * @returns {ReactElement} PopoverTrigger component
  */
@@ -4462,8 +4959,29 @@ const KPI = ({ title, value, unit, className, "data-testid": dataTestId, tooltip
 };
 
 /**
- * Skeleton loading indicator that mimics the KPI component structure.
- * Uses the same layout, spacing, and visual hierarchy as KPI.
+ * KPISkeleton is a loading placeholder that mimics the layout of a KPI component.
+ * It renders skeleton lines for the title and value with randomized widths for a natural appearance.
+ *
+ * ### When to use
+ * Use KPISkeleton while `KPI` data is loading to maintain layout stability and reduce perceived load time.
+ *
+ * ### When not to use
+ * Do not use KPISkeleton for generic text loading — use `SkeletonLabel`.
+ *
+ * @example KPI skeleton in a dashboard
+ * ```tsx
+ * import { KPISkeleton } from "@trackunit/react-components";
+ *
+ * const LoadingDashboard = () => (
+ *   <div className="flex gap-4">
+ *     <KPISkeleton variant="default" />
+ *     <KPISkeleton variant="default" />
+ *     <KPISkeleton variant="small" />
+ *   </div>
+ * );
+ * ```
+ * @param {KPISkeletonProps} props - The props for the KPISkeleton component
+ * @returns {ReactElement} KPISkeleton component
  */
 const KPISkeleton = ({ variant = "default", className, "data-testid": dataTestId, style, ref, ...rest }) => {
     const isSmallVariant = variant === "small";
@@ -4492,32 +5010,34 @@ const TrendIndicators = ({ trends, "data-testid": dataTestId, className, ref, })
     return (jsx("span", { className: twMerge("flex flex-row items-center gap-1", className), "data-testid": dataTestId, ref: ref, children: trends.map((trend, index) => (jsx(TrendIndicator, { "data-testid": dataTestId ? `${dataTestId}-trend-indicator-${index}` : undefined, ...trend }, index))) }));
 };
 
-const cvaValueBar = cvaMerge([
-    "w-full",
-    "overflow-hidden",
-    "rounded",
-    "bg-neutral-100",
-    "appearance-none",
-    "[&::-webkit-progress-bar]:bg-transparent",
-    "[&::-webkit-progress-value]:bg-current",
-    "[&::-moz-progress-bar]:bg-current",
-], {
+const valueBarContainerClassName = "relative flex w-full items-center gap-2";
+const cvaValueBarText = cvaMerge(["whitespace-nowrap"], {
     variants: {
         size: {
-            extraSmall: "h-1",
-            small: "h-3",
-            large: "h-9",
+            small: "leading-xs text-xs font-medium text-neutral-600",
+            large: "absolute pl-3 text-base text-white drop-shadow-lg",
         },
     },
     defaultVariants: {
         size: "small",
     },
 });
-const cvaValueBarText = cvaMerge(["whitespace-nowrap"], {
+
+const cvaValueBar = cvaMerge([
+    "w-full",
+    "overflow-hidden",
+    "rounded",
+    "bg-neutral-100",
+    "appearance-none",
+    "[&::-webkit-progress-bar]:bg-transparent",
+    "[&::-webkit-progress-value]:bg-current",
+    "[&::-moz-progress-bar]:bg-current",
+], {
     variants: {
         size: {
-            small: "leading-xs text-xs font-medium text-neutral-600",
-            large: "absolute pl-3 text-base text-white drop-shadow-lg",
+            extraSmall: "h-1",
+            small: "h-3",
+            large: "h-9",
         },
     },
     defaultVariants: {
@@ -4593,8 +5113,44 @@ const getValueBarColorByValue = (value, min, max, levelColors) => {
 };
 
 /**
- * ValueBar component is used to display value on a colorful bar within provided range.
- 
+ * 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.
+ *
+ * @example Basic value bar with percentage
+ * ```tsx
+ * import { ValueBar } from "@trackunit/react-components";
+ *
+ * const BatteryLevel = () => (
+ *   <ValueBar value={72} min={0} max={100} unit="%" showValue />
+ * );
+ * ```
+ * @example Value bar with custom level colors
+ * ```tsx
+ * import { ValueBar } from "@trackunit/react-components";
+ *
+ * const TemperatureBar = () => (
+ *   <ValueBar
+ *     value={85}
+ *     min={0}
+ *     max={120}
+ *     unit="°C"
+ *     showValue
+ *     size="large"
+ *     levelColors={[
+ *       { min: 0, max: 0.5, color: "#22c55e" },
+ *       { min: 0.5, max: 0.75, color: "#f59e0b" },
+ *       { min: 0.75, max: 1, color: "#ef4444" },
+ *     ]}
+ *   />
+ * );
+ * ```
  * @param {ValueBarProps} props - The props for the ValueBar component
  * @returns {ReactElement} ValueBar component
  */
@@ -4602,7 +5158,7 @@ const ValueBar = ({ value, min = 0, max = 100, unit, size = "small", levelColors
     const score = getScore(value, min, max, zeroScoreAllowed);
     const barFillColor = levelColors ? getFillColor(score, levelColors) : getDefaultFillColor(score);
     const valueText = `${Number(value.toFixed(1))}${nonNullable(unit) ? unit : ""}`;
-    return (jsxs("span", { className: "relative flex items-center gap-2", "data-testid": dataTestId, ref: ref, children: [jsx("progress", { "aria-label": valueText, className: cvaValueBar({ className, size }), max: 100, style: { color: barFillColor }, value: score * 100 }), showValue && (size === "small" || size === "large") ? (jsx(Text, { className: cvaValueBarText({ size }), "data-testid": dataTestId ? `${dataTestId}-value` : undefined, children: jsx("span", { style: valueColor ? { color: valueColor } : undefined, children: valueText }) })) : null] }));
+    return (jsxs("span", { className: valueBarContainerClassName, "data-testid": dataTestId, ref: ref, children: [jsx("progress", { "aria-label": valueText, className: cvaValueBar({ className, size }), max: 100, style: { color: barFillColor }, value: score * 100 }), showValue && (size === "small" || size === "large") ? (jsx(Text, { className: cvaValueBarText({ size }), "data-testid": dataTestId ? `${dataTestId}-value` : undefined, children: jsx("span", { style: valueColor ? { color: valueColor } : undefined, children: valueText }) })) : null] }));
 };
 
 const cvaKPICard = cvaMerge([
@@ -4703,13 +5259,29 @@ const KPICard = ({ isActive = false, onClick, className, "data-testid": dataTest
 };
 
 /**
- * Display a single placeholder block for shape-based elements before data gets loaded to reduce load-time frustration.
+ * 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.
  *
- * Fills the full height for images, badges, buttons, avatars, and other shape-based elements.
- * Uses numbers or CSS length values for height.
+ * ### 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`.
+ *
+ * @example Skeleton block for an avatar and button
+ * ```tsx
+ * import { SkeletonBlock } from "@trackunit/react-components";
  *
- * For text content, use SkeletonLabel component instead.
- * For multiple text lines, use SkeletonLines component instead.
+ * const AvatarSkeleton = () => (
+ *   <div className="flex items-center gap-3">
+ *     <SkeletonBlock height={40} width={40} className="rounded-full" />
+ *     <SkeletonBlock height={32} width={120} className="rounded-md" />
+ *   </div>
+ * );
+ * ```
+ * @param {SkeletonBlockProps} props - The props for the SkeletonBlock component
+ * @returns {ReactElement} SkeletonBlock component
  */
 const SkeletonBlock = memo((props) => {
     const { width = "100%", height = 16, flexibleWidth = false, className, "data-testid": dataTestId, children, ref, } = props;
@@ -4724,8 +5296,29 @@ const SkeletonBlock = memo((props) => {
 SkeletonBlock.displayName = "SkeletonBlock";
 
 /**
- * Skeleton loading indicator that mimics the KPICard component structure.
- * Uses the same layout, spacing, and visual hierarchy as KPICard.
+ * KPICardSkeleton is a loading placeholder that mimics the layout of a KPICard.
+ * It renders skeleton lines for the KPI title/value, and optional icon, trends, value bar, and notice slots.
+ *
+ * ### When to use
+ * Use KPICardSkeleton while `KPICard` data is loading to maintain layout stability in dashboards and metric displays.
+ *
+ * ### When not to use
+ * Do not use KPICardSkeleton for generic card loading — use a `Card` with `SkeletonLabel` inside.
+ *
+ * @example KPICard skeletons in a dashboard row
+ * ```tsx
+ * import { KPICardSkeleton } from "@trackunit/react-components";
+ *
+ * const LoadingMetrics = () => (
+ *   <div className="grid grid-cols-3 gap-4">
+ *     <KPICardSkeleton hasIcon hasTrends />
+ *     <KPICardSkeleton hasIcon hasValueBar />
+ *     <KPICardSkeleton hasNotice />
+ *   </div>
+ * );
+ * ```
+ * @param {KPICardSkeletonProps} props - The props for the KPICardSkeleton component
+ * @returns {ReactElement} KPICardSkeleton component
  */
 const KPICardSkeleton = ({ hasIcon = false, hasTrends = false, hasValueBar = false, hasNotice = false, children, className, "data-testid": dataTestId, style, ref, ...rest }) => {
     return (jsx(Card, { className: cvaKPICard({ className }), "data-testid": dataTestId, ref: ref, style: style, ...rest, children: jsxs(CardBody, { className: cvaKPICardBody(), gap: "none", padding: "none", children: [jsxs("div", { className: cvaKPICardHeader(), children: [jsx(KPISkeleton, { className: "p-0", "data-testid": dataTestId ? `${dataTestId}-kpi` : undefined }), hasIcon ? (jsx(SkeletonBlock, { "data-testid": dataTestId ? `${dataTestId}-icon-loading` : undefined, height: 28, width: 28 })) : null] }), hasTrends ? (jsx(SkeletonLabel, { "data-testid": dataTestId ? `${dataTestId}-trend-indicator-loading` : undefined, textSize: "text-xs", width: "100%" })) : null, hasValueBar ? (jsx(SkeletonLabel, { "data-testid": dataTestId ? `${dataTestId}-value-bar-loading` : undefined, textSize: "text-xs", width: "100%" })) : null, hasNotice ? (jsx(SkeletonLabel, { "data-testid": dataTestId ? `${dataTestId}-notice-loading` : undefined, textSize: "text-xs", width: "100%" })) : null, children] }) }));
@@ -4805,8 +5398,30 @@ const DEFAULT_SKELETON_LIST_ITEM_PROPS = {
     hasDetails: false,
 };
 /**
- * Skeleton loading indicator that mimics the ListItem component structure.
- * Uses the same layout, spacing, and visual hierarchy as ListItem.
+ * ListItemSkeleton is a loading placeholder that mimics the layout of a ListItem.
+ * It renders skeleton lines for the title, description, meta, thumbnail, and details slots.
+ * Use it inside a List to indicate that list data is loading.
+ *
+ * ### When to use
+ * Use ListItemSkeleton as the loading state inside a `List` when data is being fetched. Configure it to match the shape of your actual ListItems.
+ *
+ * ### When not to use
+ * Do not use ListItemSkeleton for non-list loading states. Use `SkeletonBlock` or `SkeletonLabel` for generic loading placeholders.
+ *
+ * @example ListItemSkeleton matching a typical asset list item
+ * ```tsx
+ * import { ListItemSkeleton } from "@trackunit/react-components";
+ *
+ * const LoadingList = () => (
+ *   <div>
+ *     <ListItemSkeleton hasThumbnail hasDescription hasMeta={false} />
+ *     <ListItemSkeleton hasThumbnail hasDescription hasMeta={false} />
+ *     <ListItemSkeleton hasThumbnail hasDescription hasMeta={false} />
+ *   </div>
+ * );
+ * ```
+ * @param {ListItemSkeletonProps} props - The props for the ListItemSkeleton component
+ * @returns {ReactElement} ListItemSkeleton component
  */
 const ListItemSkeleton = ({ hasThumbnail = DEFAULT_SKELETON_LIST_ITEM_PROPS.hasThumbnail, thumbnailShape = "circle", hasDescription = DEFAULT_SKELETON_LIST_ITEM_PROPS.hasDescription, hasMeta = DEFAULT_SKELETON_LIST_ITEM_PROPS.hasMeta, hasDetails = DEFAULT_SKELETON_LIST_ITEM_PROPS.hasDetails, }) => {
     // Generate stable random widths once and never change them
@@ -5292,10 +5907,32 @@ const getResolvedLoadingIndicator = (loadingIndicator) => {
 };
 
 /**
- *   The ListItem is designed to present a concise set of items for quick scanning and navigation. It supports multiple content types and actions, and its flexible layout allows for customization based on the type of data being shown - assets, events, users, etc.
+ * 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.
  *
- * @param { ListItemProps} props - The props for the ListItem component
- * @returns {Element}  ListItem component
+ * ### 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`.
+ *
+ * @example ListItem with thumbnail and details
+ * ```tsx
+ * import { ListItem, Icon, Tag } from "@trackunit/react-components";
+ *
+ * const AssetListItem = () => (
+ *   <ListItem
+ *     title="Excavator CAT 320"
+ *     description="Serial: SN-2024-00142"
+ *     meta="Last seen: 2 hours ago"
+ *     thumbnail={<Icon name="Truck" size="small" />}
+ *     details={<Tag color="success" size="small">Active</Tag>}
+ *     onClick={() => console.log("Navigate to asset")}
+ *   />
+ * );
+ * ```
+ * @param {ListItemProps} props - The props for the ListItem component
+ * @returns {ReactElement} ListItem component
  */
 const ListItem = ({ className, "data-testid": dataTestId, onClick, details, title, description, meta, thumbnail, thumbnailColor = "info-600", thumbnailBackground = "info-100", ...rest }) => {
     const baseClass = cvaListItem({ className });
@@ -5399,7 +6036,28 @@ const cvaMenuListMultiSelect = cvaMerge([
 const cvaMenuListItem = cvaMerge("max-w-full");
 
 /**
- * The MenuDivider component is used to separate items in a menu list.
+ * MenuDivider renders a horizontal line to visually separate groups of items within a MenuList.
+ *
+ * ### 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 `MenuList`. For general-purpose dividers, use `Spacer` with `border`.
+ *
+ * @example Menu with grouped sections
+ * ```tsx
+ * import { MenuList, MenuItem, MenuDivider, Icon } from "@trackunit/react-components";
+ *
+ * const GroupedMenu = () => (
+ *   <MenuList>
+ *     <MenuItem id="edit" label="Edit" prefix={<Icon name="PencilSquare" size="small" />} />
+ *     <MenuItem id="duplicate" label="Duplicate" prefix={<Icon name="DocumentDuplicate" size="small" />} />
+ *     <MenuDivider />
+ *     <MenuItem id="delete" label="Delete" variant="danger" prefix={<Icon name="Trash" size="small" />} />
+ *   </MenuList>
+ * );
+ * ```
+ * @returns {ReactElement} MenuDivider component
  */
 const MenuDivider = () => {
     return jsx("div", { className: cvaMenuListDivider(), "data-testid": "menu-divider" });
@@ -5525,8 +6183,37 @@ const cvaMenuItemSuffix = cvaMerge(["text-neutral-400", "text-sm", "flex", "item
 });
 
 /**
- * The MenuItem component is used to display a menu, primarily meant to be used in a list form.
+ * MenuItem represents a single actionable item within a MenuList.
+ * It supports labels, icons (prefix/suffix), selected and focused states, and danger variants.
+ *
+ * ### When to use
+ * Use MenuItem inside a `MenuList` for individual actions (edit, delete, duplicate) or selectable options.
+ *
+ * ### When not to use
+ * Do not use MenuItem outside of a `MenuList` context. For standalone clickable items, use `Button` or `ListItem`.
  *
+ * @example MenuItem with icon prefix
+ * ```tsx
+ * import { MenuList, MenuItem, Icon } from "@trackunit/react-components";
+ *
+ * const ActionMenu = () => (
+ *   <MenuList>
+ *     <MenuItem
+ *       id="edit"
+ *       label="Edit asset"
+ *       prefix={<Icon name="PencilSquare" size="small" />}
+ *       onClick={() => console.log("Edit clicked")}
+ *     />
+ *     <MenuItem
+ *       id="delete"
+ *       label="Delete asset"
+ *       prefix={<Icon name="Trash" size="small" />}
+ *       variant="danger"
+ *       onClick={() => console.log("Delete clicked")}
+ *     />
+ *   </MenuList>
+ * );
+ * ```
  * @param {MenuItemProps} props - The props for the MenuItem component
  * @returns {ReactElement} MenuItem component
  */
@@ -5656,9 +6343,45 @@ const MenuList = ({ "data-testid": dataTestId, className, children, isMulti = fa
 const cvaMoreMenu = cvaMerge(["p-0"]);
 
 /**
- * A kebab menu component.
- * Advice: fill it with MenuList
+ * MoreMenu (kebab menu) renders a three-dot button that opens a popover with a list of actions.
+ * It is typically filled with a MenuList 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.
  *
+ * @example Action items with render prop — Pass a function as `children` to receive the `close` callback and dismiss the menu after an action.
+ * ```tsx
+ * import { MoreMenu, MenuList, MenuItem, Icon } from "@trackunit/react-components";
+ *
+ * const AssetActions = () => (
+ *   <MoreMenu>
+ *     {(close) => (
+ *       <MenuList onClick={close}>
+ *         <MenuItem id="edit" label="Edit" prefix={<Icon name="PencilSquare" size="small" />} />
+ *         <MenuItem id="delete" label="Delete" variant="danger" prefix={<Icon name="Trash" size="small" />} />
+ *       </MenuList>
+ *     )}
+ *   </MoreMenu>
+ * );
+ * ```
+ * @example Custom trigger button — Use `customButton` to replace the default kebab icon with any element, like a labeled Button.
+ * ```tsx
+ * import { MoreMenu, MenuList, MenuItem, Button } from "@trackunit/react-components";
+ *
+ * const CustomTriggerMenu = () => (
+ *   <MoreMenu customButton={<Button variant="secondary" size="small">Actions</Button>}>
+ *     {(close) => (
+ *       <MenuList onClick={close}>
+ *         <MenuItem id="export" label="Export" />
+ *         <MenuItem id="archive" label="Archive" />
+ *       </MenuList>
+ *     )}
+ *   </MoreMenu>
+ * );
+ * ```
  * @param {MoreMenuProps} props - The props for the MoreMenu component
  * @returns {ReactElement} MoreMenu component
  */
@@ -5711,12 +6434,42 @@ const cvaNoticeIcon = cvaMerge(["rounded-full", "items-center", "justify-center"
 });
 
 /**
- * Notices are non-interactive elements that communicate information that the user needs to see, without directly prompting an action button.
+ * 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.
  *
- * _**Do use** notices to communicate non-essential information that does not necessarily require action to be taken._
+ * ### When to use
+ * Use Notice to communicate non-essential, contextual information that does not require action (e.g., status notes, informational hints).
  *
- * _**Do not use** notices for essential information (use `<Alert/>` instead), or to communicate information related to the state of an asset (use `<Indicator/>` instead)._
+ * ### 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.
  *
+ * @example Notice with icon and label
+ * ```tsx
+ * import { Notice } from "@trackunit/react-components";
+ *
+ * const InfoNotice = () => (
+ *   <Notice
+ *     iconName="InformationCircle"
+ *     label="Last synced 5 minutes ago"
+ *     color="info"
+ *   />
+ * );
+ * ```
+ * @example Warning notice with tooltip
+ * ```tsx
+ * import { Notice } from "@trackunit/react-components";
+ *
+ * const WarningNotice = () => (
+ *   <Notice
+ *     iconName="ExclamationTriangle"
+ *     label="Low battery"
+ *     color="warning"
+ *     withTooltip
+ *     tooltipLabel="Battery level is below 20%"
+ *   />
+ * );
+ * ```
  * @param {NoticeProps} props - The props for the Notice component
  * @returns {ReactElement} Notice component
  */
@@ -5751,18 +6504,68 @@ const cvaPageContent = cvaMerge(["overflow-auto", "page-content", "grid", "gap-r
 });
 
 /**
- * Renders the page component. Adds padding and layout to the page.
+ * 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.
+ *
+ * @example Page with header and content
+ * ```tsx
+ * import { Page, PageContent, PageHeader } from "@trackunit/react-components";
+ *
+ * const AssetListPage = () => (
+ *   <Page layout="default">
+ *     <PageHeader
+ *       title="Assets"
+ *       accessoryType="actions"
+ *       primaryAction={{ actionText: "Add Asset", actionCallback: () => {} }}
+ *     />
+ *     <PageContent layout="default">
+ *       <p>Asset list content goes here</p>
+ *     </PageContent>
+ *   </Page>
+ * );
+ * ```
+ * @param {PageProps} props - The props for the Page component
+ * @returns {ReactElement} Page component
  */
 const Page = ({ layout, className, children, "data-testid": dataTestId, ref }) => {
     return (jsx("div", { className: cvaPage({ className, layout }), "data-testid": dataTestId ? dataTestId : "page", ref: ref, children: children }));
 };
 
 /**
- * Renders the content of a page.
- * Applies padding to content. To be used within a <Page/>
+ * PageContent is the main content area inside a Page.
+ * It applies consistent padding to the content section. Must be used within a Page component.
+ *
+ * ### When to use
+ * Use PageContent to wrap the main content of a page, below a `PageHeader`. It provides consistent padding and layout.
+ *
+ * ### When not to use
+ * Do not use PageContent outside of a `Page`. For standalone content wrappers, use `Card` or `CardBody`.
  *
- * @param {PageContentProps} props - The component props.
- * @returns {ReactNode} - The rendered component.
+ * @example PageContent inside a Page
+ * ```tsx
+ * import { Page, PageContent, PageHeader, Card, CardBody, Text } from "@trackunit/react-components";
+ *
+ * const DetailPage = () => (
+ *   <Page layout="default">
+ *     <PageHeader title="Asset Details" />
+ *     <PageContent layout="default">
+ *       <Card>
+ *         <CardBody>
+ *           <Text>Asset information goes here</Text>
+ *         </CardBody>
+ *       </Card>
+ *     </PageContent>
+ *   </Page>
+ * );
+ * ```
+ * @param {PageContentProps} props - The props for the PageContent component
+ * @returns {ReactElement} PageContent component
  */
 const PageContent = ({ className, children, "data-testid": dataTestId, layout, ref, }) => {
     return (jsx("div", { className: cvaPageContent({ className, layout }), "data-testid": dataTestId ? dataTestId : "page-content", ref: ref, children: children }));
@@ -5846,14 +6649,16 @@ cvaMerge([
 ]);
 
 /**
- * Display multiple placeholder lines before data gets loaded to reduce load-time frustration.
+ * 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.
  *
- * Supports three modes:
- * - **Uniform mode** (default): Display identical lines using `count` prop
- * - **Custom mode**: Display customized lines with per-line configuration using `variant="custom"` and `lines` prop
- * - **Preset mode**: Display common patterns using `variant="preset"` and `preset` name
+ * ### When to use
+ * Use SkeletonLines for loading placeholders of multi-line text content: paragraphs, descriptions, articles, or any text block.
  *
- * Built on top of the [SkeletonLabel](?path=/docs/components-loading-states-skeletonlabel--docs) component for text-specific margins and sizing.
+ * ### When not to use
+ * For single text lines, use `SkeletonLabel`.
+ * For shape-based elements, use `SkeletonBlock`.
  *
  * @example
  * // Uniform lines (simple mode)
@@ -6062,11 +6867,15 @@ const PageHeaderTitle = ({ title, "data-testid": dataTestId, className, ref: for
 };
 
 /**
- * The PageHeader component is used to display the header of a page.
+ * 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.
  *
- * It provides critical context by indicating the current location within the application or website.
- * PageHeader can be used to highlight the page topic, display helpful information about the page, and carry the action items related to the current page.
- * Tabs can be added to the PageHeader to allow users to navigate between different sections of the page.
+ * ### 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`.
  *
  * @example Page header with actions
  * ```tsx
@@ -6135,8 +6944,37 @@ const cvaPagination = cvaMerge(["flex", "items-center", "gap-1"]);
 const cvaPaginationText = cvaMerge("whitespace-nowrap");
 
 /**
- * Pagination Description. It could be used when you need navigation for your paging feature.
- 
+ * 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.
+ *
+ * @example Basic offset-based pagination
+ * ```tsx
+ * import { Pagination } from "@trackunit/react-components";
+ * import { useState } from "react";
+ *
+ * const PaginatedList = () => {
+ *   const [page, setPage] = useState(0);
+ *   const totalPages = 10;
+ *
+ *   return (
+ *     <Pagination
+ *       pageIndex={page}
+ *       pageCount={totalPages}
+ *       canPreviousPage={page > 0}
+ *       canNextPage={page < totalPages - 1}
+ *       previousPage={() => setPage(p => p - 1)}
+ *       nextPage={() => setPage(p => p + 1)}
+ *       getTranslatedCount={(count) => `of ${count}`}
+ *     />
+ *   );
+ * };
+ * ```
  * @param {PaginationProps} props - The props for the Pagination component
  * @returns {ReactElement} Pagination component
  */
@@ -6192,10 +7030,29 @@ const Pagination = ({ previousPage, nextPage, canPreviousPage = false, canNextPa
 
 const STROKE_WIDTH_THRESHOLD = 32;
 /**
- *  Draws an svg Polygon from a set of points.
+ * 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.
+ *
+ * @example Rendering a triangle
+ * ```tsx
+ * import { Polygon } from "@trackunit/react-components";
  *
- * @param { PolygonProps} props - The props for the  Polygon component
- * @returns {ReactElement}  Polygon component
+ * const Triangle = () => (
+ *   <Polygon
+ *     points={[[0, 100], [50, 0], [100, 100]]}
+ *     size={64}
+ *     color="black"
+ *   />
+ * );
+ * ```
+ * @param {PolygonProps} props - The props for the Polygon component
+ * @returns {ReactElement} Polygon component
  */
 const Polygon = ({ points, size, color = "black", opaque = true, className, "data-testid": dataTestId, ref, }) => {
     // Calculate the bounds of the points
@@ -6225,8 +7082,39 @@ const Polygon = ({ points, size, color = "black", opaque = true, className, "dat
 const normalize = ({ value, min, max, size }) => ((value - min) / (max - min)) * size;
 
 /**
- * The PopoverTitle component.
+ * PopoverTitle renders a styled title bar at the top of a PopoverContent panel.
+ * It displays uppercase bold text with an optional action element and divider.
+ *
+ * ### When to use
+ * Use PopoverTitle inside `PopoverContent` when the popover needs a labeled header, optionally with an action (e.g., a close button).
  *
+ * ### When not to use
+ * Do not use PopoverTitle outside of a `Popover` context. For standalone headings, use `Heading`.
+ *
+ * @example Popover with titled content
+ * ```tsx
+ * import { Popover, PopoverTrigger, PopoverContent, PopoverTitle, Button, Text } from "@trackunit/react-components";
+ *
+ * const TitledPopover = () => (
+ *   <Popover placement="bottom-start">
+ *     <PopoverTrigger>
+ *       <Button variant="secondary">Details</Button>
+ *     </PopoverTrigger>
+ *     <PopoverContent>
+ *       {(close) => (
+ *         <div className="w-64">
+ *           <PopoverTitle divider action={<Button variant="ghost" size="small" onClick={close}>Close</Button>}>
+ *             Asset Info
+ *           </PopoverTitle>
+ *           <div className="p-3">
+ *             <Text size="small">Additional information about this asset.</Text>
+ *           </div>
+ *         </div>
+ *       )}
+ *     </PopoverContent>
+ *   </Popover>
+ * );
+ * ```
  * @param {PopoverTitleProps} props - The props for the PopoverTitle component
  * @returns {ReactElement} PopoverTitle component
  */
@@ -6369,9 +7257,31 @@ const preferenceCardGrid = createGrid()
 })
     .build();
 /**
- * PreferenceCard is a flexible component for displaying add-ons or settings configuration options
- * with various states and visual treatments.
- * It is recommended to be primarily used as an input component, as it supports checkboxes, radio buttons and toggles.
+ * PreferenceCard is a flexible component for displaying add-on options or settings with an optional input control (checkbox, radio, toggle).
+ * It supports icons/images, titles with tags, descriptions, and custom child content for advanced layouts.
+ *
+ * ### When to use
+ * Use PreferenceCard for settings pages, feature toggles, or plan selection where each option needs a title, description, and an input control.
+ *
+ * ### When not to use
+ * Do not use PreferenceCard for data display — use `Card`.
+ * Do not use for simple toggle settings — use a standalone toggle switch.
+ *
+ * @example PreferenceCard with checkbox input
+ * ```tsx
+ * import { PreferenceCard } from "@trackunit/react-components";
+ *
+ * const FeatureToggle = () => (
+ *   <PreferenceCard
+ *     title="Email Notifications"
+ *     description="Receive email alerts for asset status changes"
+ *     icon={{ type: "icon", name: "EnvelopeOpen", containerClassName: "bg-primary-100" }}
+ *     input={<input type="checkbox" />}
+ *   />
+ * );
+ * ```
+ * @param {PreferenceCardProps} props - The props for the PreferenceCard component
+ * @returns {ReactNode} PreferenceCard component
  */
 const PreferenceCard = ({ title, description, icon, input, titleTag, cardTag, disabled = false, className, "data-testid": dataTestId, children, ref: forwardedRef, }) => {
     const { ref: measureRef, geometry } = useMeasure();
@@ -6421,8 +7331,29 @@ const getRandomWidth = (min, max) => {
     return Math.floor(Math.random() * (max - min + 1)) + min;
 };
 /**
- * Skeleton loading indicator that mimics the PreferenceCard component structure.
- * Uses the same grid layout, spacing, and visual hierarchy as PreferenceCard.
+ * PreferenceCardSkeleton is a loading placeholder that mimics the layout of a PreferenceCard.
+ * It renders skeleton lines for the title, description, and optional slots (icon, tags, input).
+ * Configure the boolean flags to match the shape of your actual PreferenceCards.
+ *
+ * ### When to use
+ * Use PreferenceCardSkeleton while preference/settings data is loading to maintain layout stability and reduce perceived load time.
+ *
+ * ### When not to use
+ * Do not use PreferenceCardSkeleton for generic loading — use `SkeletonBlock` or `SkeletonLabel`.
+ *
+ * @example PreferenceCard skeleton with icon and input
+ * ```tsx
+ * import { PreferenceCardSkeleton } from "@trackunit/react-components";
+ *
+ * const LoadingSettings = () => (
+ *   <div className="flex flex-col gap-3">
+ *     <PreferenceCardSkeleton hasIcon hasInput />
+ *     <PreferenceCardSkeleton hasIcon hasInput />
+ *   </div>
+ * );
+ * ```
+ * @param {PreferenceCardSkeletonProps} props - The props for the PreferenceCardSkeleton component
+ * @returns {ReactElement} PreferenceCardSkeleton component
  */
 const PreferenceCardSkeleton = ({ hasIcon = DEFAULT_SKELETON_PREFERENCE_CARD_PROPS.hasIcon, hasTitleTag = DEFAULT_SKELETON_PREFERENCE_CARD_PROPS.hasTitleTag, hasCardTag = DEFAULT_SKELETON_PREFERENCE_CARD_PROPS.hasCardTag, hasInput = DEFAULT_SKELETON_PREFERENCE_CARD_PROPS.hasInput, ref, }) => {
     const gridAreas = useGridAreas(preferenceCardGrid);
@@ -6449,11 +7380,27 @@ function useConfirmExit(confirmExit, when = true) {
     useBlocker(confirmExit, when);
 }
 /**
- * The usePrompt hook.
- 
- * @param {string} message -
- * @param {boolean} when -
- * @returns {void} void
+ * usePrompt displays a browser confirmation dialog when the user tries to navigate away from the current page.
+ * It blocks both in-app navigation (via TanStack Router's `useBlocker`) and browser-level navigation (via `beforeunload`).
+ *
+ * ### When to use
+ * Use usePrompt when the user has unsaved changes (e.g., in a form) and should be warned before navigating away.
+ *
+ * ### When not to use
+ * Do not use usePrompt for non-destructive navigation. Only use when there is genuinely unsaved state that would be lost.
+ *
+ * @example Warn user about unsaved form changes
+ * ```tsx
+ * import { usePrompt } from "@trackunit/react-components";
+ *
+ * const EditForm = ({ isDirty }: { isDirty: boolean }) => {
+ *   usePrompt("You have unsaved changes. Are you sure you want to leave?", isDirty);
+ *   return <form>...</form>;
+ * };
+ * ```
+ * @param {string} message - The confirmation message shown to the user
+ * @param {boolean} when - Whether the prompt should be active. Defaults to true.
+ * @returns {void}
  */
 const usePrompt = (message, when = true) => {
     useEffect(() => {
@@ -6476,10 +7423,28 @@ const usePrompt = (message, when = true) => {
     useConfirmExit(confirmExit, when);
 };
 /**
- * The Prompt function.
+ * Prompt is a declarative component wrapper around the `usePrompt` hook. It displays a browser confirmation dialog
+ * when the user tries to navigate away while `when` is true.
  *
- * @param {PromptProps} Props -
- * @returns {void} void
+ * ### When to use
+ * Use Prompt when you prefer a declarative approach to navigation blocking (instead of the `usePrompt` hook).
+ *
+ * ### When not to use
+ * Do not use Prompt when `when` is always false — simply omit it.
+ *
+ * @example Declarative prompt for unsaved changes
+ * ```tsx
+ * import { Prompt } from "@trackunit/react-components";
+ *
+ * const EditPage = ({ hasUnsavedChanges }: { hasUnsavedChanges: boolean }) => (
+ *   <>
+ *     <Prompt when={hasUnsavedChanges} message="Discard unsaved changes?" />
+ *     <form>...</form>
+ *   </>
+ * );
+ * ```
+ * @param {PromptProps} props - The props for the Prompt component
+ * @returns {null} Renders nothing; only activates the navigation prompt
  */
 const Prompt = ({ when, message }) => {
     usePrompt(message, when);
@@ -6505,18 +7470,25 @@ const cvaSpacer = cvaMerge([], {
 });
 
 /**
- * The Spacer component is used for adding a bit of space in the ui.
+ * 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.
  *
- * @example basic usage
+ * ### 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.
+ *
+ * @example Spacer as a divider
  * ```tsx
- * import { Spacer } from "@trackunit/react-components";
- * const MySpacer = () => {
- *   return (
- *     <div>
- *       <Spacer size="small" border data-testid="my-spacer-testid" />
- *     </div>
- *   );
- * };
+ * import { Spacer, Text } from "@trackunit/react-components";
+ *
+ * const DividedSections = () => (
+ *   <div>
+ *     <Text>Section 1 content</Text>
+ *     <Spacer size="medium" border />
+ *     <Text>Section 2 content</Text>
+ *   </div>
+ * );
  * ```
  * @param {SpacerProps} props - The props for the Spacer component
  * @returns {ReactElement} Spacer component
@@ -6526,9 +7498,29 @@ const Spacer = ({ size = "medium", border = false, "data-testid": dataTestId, cl
 };
 
 /**
- * The SectionHeader component is used on sections to set the section title.
- 
- * @param {SectionHeaderProps} props - The props for the section header component
+ * 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`.
+ *
+ * @example Section header with subtitle and addon
+ * ```tsx
+ * import { SectionHeader, Button } from "@trackunit/react-components";
+ *
+ * const AssetSection = () => (
+ *   <SectionHeader
+ *     title="Maintenance Schedule"
+ *     subtitle="Upcoming and past maintenance events"
+ *     addons={<Button variant="secondary" size="small">Add Event</Button>}
+ *   />
+ * );
+ * ```
+ * @param {SectionHeaderProps} props - The props for the SectionHeader component
  * @returns {ReactElement} SectionHeader component
  */
 const SectionHeader = ({ title, subtitle, "data-testid": dataTestId, addons, ref, }) => {
@@ -6604,12 +7596,19 @@ const useOverflowItems = ({ threshold = 1, childUniqueIdentifierAttribute = "id"
 };
 
 /**
- * The sidebar components is used to render a responsive sidebar.
- * - The sidebar will be rendered horizontally until a given breakpoint where it will be stacked vertically.
- * - The sidebar hides items that does not fit in the sidebar and show them in a more menu.
- * - **_The sidebar is just a wrapper. You are responsible for styling the children._**
+ * 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 `jest.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.
  *
- * When using this component make sure to add `setupIntersectionObserver();` to your jest.setup.ts file.
+ * ### When not to use
+ * Do not use Sidebar for primary app navigation (the main menu). For top-level navigation, use the app shell navigation.
  *
  * @example Responsive sidebar with navigation items
  * ```tsx
@@ -6715,8 +7714,35 @@ const cvaTab = cvaMerge([
 });
 
 /**
- * Wrapper for radix tab component.
- * We add a custom implementation of the asChild prop to make it easy to make the child element look like other tabs.
+ * Tab is an individual tab trigger within a TabList.
+ * Each Tab requires a unique `value` prop that corresponds to a TabContent with the same value.
+ * Supports optional icons, suffixes (e.g., badges), and rendering as a custom child element via `asChild`.
+ *
+ * ### When to use
+ * Use Tab inside a `TabList` to create clickable tab triggers. Each Tab maps to a `TabContent` panel.
+ *
+ * ### When not to use
+ * Do not use Tab outside of a `TabList`/`Tabs` context. For standalone buttons, use `Button`.
+ *
+ * @example Tab with icon and badge suffix
+ * ```tsx
+ * import { Tabs, TabList, Tab, TabContent, Badge } from "@trackunit/react-components";
+ *
+ * const TabsWithBadge = () => (
+ *   <Tabs defaultValue="alerts">
+ *     <TabList>
+ *       <Tab value="alerts" iconName="Bell" suffix={<Badge count={3} color="danger" />}>
+ *         Alerts
+ *       </Tab>
+ *       <Tab value="history" iconName="Clock">History</Tab>
+ *     </TabList>
+ *     <TabContent value="alerts">Active alerts</TabContent>
+ *     <TabContent value="history">Event history</TabContent>
+ *   </Tabs>
+ * );
+ * ```
+ * @param {TabProps} props - The props for the Tab component
+ * @returns {ReactElement} Tab component
  */
 const Tab = ({ value, isFullWidth = false, iconName = undefined, "data-testid": dataTestId, className, children, suffix, asChild = false, appendTabStylesToChildIfAsChild = true, ref, ...rest }) => {
     const renderContent = () => (jsxs(Fragment$1, { children: [iconName !== undefined ? jsx(Icon, { name: iconName, size: "small" }) : null, isValidElement(children) ? children.props.children : children, suffix] }));
@@ -6731,14 +7757,72 @@ const Tab = ({ value, isFullWidth = false, iconName = undefined, "data-testid":
 };
 
 /**
- * Wrapper for radix tab content component.
+ * TabContent is the content panel displayed when its corresponding Tab is active.
+ * Each TabContent must have a `value` prop that matches the `value` of its corresponding Tab trigger.
+ * TabContent is only rendered when its tab is selected (unless `forceMount` is set).
+ *
+ * ### When to use
+ * Use TabContent inside a `Tabs` component, one for each `Tab` trigger.
+ *
+ * ### When not to use
+ * Do not use TabContent outside of a `Tabs` context. For conditionally shown content, use standard conditional rendering.
+ *
+ * @example Tabs with styled content panels
+ * ```tsx
+ * import { Tabs, TabList, Tab, TabContent, Text } from "@trackunit/react-components";
+ *
+ * const AssetTabs = () => (
+ *   <Tabs defaultValue="overview">
+ *     <TabList>
+ *       <Tab value="overview">Overview</Tab>
+ *       <Tab value="maintenance">Maintenance</Tab>
+ *     </TabList>
+ *     <TabContent value="overview">
+ *       <Text>Asset overview information</Text>
+ *     </TabContent>
+ *     <TabContent value="maintenance">
+ *       <Text>Maintenance schedule and history</Text>
+ *     </TabContent>
+ *   </Tabs>
+ * );
+ * ```
+ * @param {TabContentProps} props - The props for the TabContent component
+ * @returns {ReactElement} TabContent component
  */
 const TabContent = ({ className, "data-testid": dataTestId, children, ref, ...rest }) => {
     return (jsx(Content, { className: cvaTabContent({ className }), "data-testid": dataTestId ? `${dataTestId}-content` : undefined, ref: ref, ...rest, children: children }));
 };
 
 /**
- * Wrapper for radix tab list component.
+ * TabList is the container for Tab triggers inside a Tabs component.
+ * It renders a horizontal row of tab triggers and handles horizontal scroll behavior when tabs overflow.
+ * By default, it auto-scrolls the active tab into view.
+ *
+ * ### When to use
+ * Use TabList as a direct child of `Tabs` to wrap the `Tab` triggers. It handles layout and scrolling.
+ *
+ * ### When not to use
+ * Do not use TabList outside of a `Tabs` context. For horizontal navigation lists, use a standard nav element.
+ *
+ * @example TabList with auto-scroll disabled
+ * ```tsx
+ * import { Tabs, TabList, Tab, TabContent } from "@trackunit/react-components";
+ *
+ * const StaticTabs = () => (
+ *   <Tabs defaultValue="first">
+ *     <TabList autoScrollToActive={false}>
+ *       <Tab value="first">First</Tab>
+ *       <Tab value="second">Second</Tab>
+ *       <Tab value="third">Third</Tab>
+ *     </TabList>
+ *     <TabContent value="first">First panel</TabContent>
+ *     <TabContent value="second">Second panel</TabContent>
+ *     <TabContent value="third">Third panel</TabContent>
+ *   </Tabs>
+ * );
+ * ```
+ * @param {TabListProps} props - The props for the TabList component
+ * @returns {ReactElement} TabList component
  */
 const TabList = ({ className, "data-testid": dataTestId, children, autoScrollToActive = true, ref, ...rest }) => {
     const listRef = useRef(null);
@@ -6785,7 +7869,18 @@ const TabList = ({ className, "data-testid": dataTestId, children, autoScrollToA
 };
 
 /**
- * Tabs are used to 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.
+ * 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.
  *
  * @example Basic tabs with content panels
  * ```tsx
@@ -6819,6 +7914,8 @@ const TabList = ({ className, "data-testid": dataTestId, children, autoScrollToA
  *   </Tabs>
  * );
  * ```
+ * @param {TabsProps} props - The props for the Tabs component
+ * @returns {ReactElement} Tabs component
  */
 const Tabs = ({ children, forceRender, className, "data-testid": dataTestId, fullWidth, ref, ...rest }) => {
     return (jsx(Root, { className: cvaTabsRoot({ className }), "data-testid": dataTestId, ref: ref, ...rest, children: children }));
@@ -6939,8 +8036,37 @@ const cvaToggleItemContent = cvaMerge([], {
 });
 
 /**
- *  Toggle Group allows users to toggle between two or more closely related options, and immediately apply that selection.
+ * 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.
+ *
+ * @example ToggleGroup for view mode switching
+ * ```tsx
+ * import { ToggleGroup } from "@trackunit/react-components";
+ * import { useState } from "react";
+ *
+ * const ViewToggle = () => {
+ *   const [selected, setSelected] = useState("list");
+ *
+ *   return (
+ *     <ToggleGroup
+ *       selected={selected}
+ *       setSelected={setSelected}
+ *       onChange={(id) => console.log("Selected:", id)}
+ *       list={[
+ *         { id: "list", title: "List", iconName: "Bars3" },
+ *         { id: "map", title: "Map", iconName: "MapPin" },
+ *       ]}
+ *     />
+ *   );
+ * };
+ * ```
  * @param {ToggleGroupProps} props - The props for the ToggleGroup component
  * @returns {ReactElement} ToggleGroup component
  */
@@ -7057,7 +8183,7 @@ const SegmentedValueBar = ({ segments, total, size = "small", showValue = false,
     const valueText = formatValue(sum, unit);
     const canShowValue = showValue && size !== "extraSmall";
     const valueTextClassName = cvaValueBarText({ size: getValueTextVariant(size, sum, segments, total) });
-    return (jsxs("span", { className: "relative flex items-center gap-2", "data-testid": dataTestId, children: [jsx("div", { "aria-label": valueText, className: cvaSegmentedValueBar({ className, size }), "data-testid": dataTestId ? `${dataTestId}-track` : undefined, children: computedSegments.map((segment, index) => {
+    return (jsxs("span", { className: valueBarContainerClassName, "data-testid": dataTestId, children: [jsx("div", { "aria-label": valueText, className: cvaSegmentedValueBar({ className, size }), "data-testid": dataTestId ? `${dataTestId}-track` : undefined, children: computedSegments.map((segment, index) => {
                     const tooltipLabel = segment.label
                         ? `${segment.label}: ${formatValue(segment.value, unit)}`
                         : formatValue(segment.value, unit);