@trackunit/react-components 1.14.18 → 1.14.20

package/index.esm.js

@@ -1,7 +1,7 @@
 import { jsx, jsxs, Fragment as Fragment$1 } from 'react/jsx-runtime';
 import { objectKeys, uuidv4, parseTailwindArbitraryValue, objectEntries, nonNullable, objectValues, filterByMultiple } from '@trackunit/shared-utils';
 import { useRef, useMemo, useEffect, useState, useLayoutEffect, useCallback, createElement, forwardRef, Fragment, memo, useId, useReducer, Children, isValidElement, cloneElement, createContext, useContext } from 'react';
-import { intentPalette, generalPalette, criticalityPalette, activityPalette, utilizationPalette, sitesPalette, rentalStatusPalette, themeScreenSizeAsNumber, themeContainerSize, color } from '@trackunit/ui-design-tokens';
+import { rentalStatusPalette, sitesPalette, utilizationPalette, activityPalette, criticalityPalette, generalPalette, intentPalette, themeScreenSizeAsNumber, themeContainerSize, color } from '@trackunit/ui-design-tokens';
 import { iconNames } from '@trackunit/ui-icons';
 import IconSpriteMicro from '@trackunit/ui-icons/icons-sprite-micro.svg';
 import IconSpriteMini from '@trackunit/ui-icons/icons-sprite-mini.svg';
@@ -9,11 +9,11 @@ import IconSpriteOutline from '@trackunit/ui-icons/icons-sprite-outline.svg';
 import IconSpriteSolid from '@trackunit/ui-icons/icons-sprite-solid.svg';
 import { snakeCase, titleCase } from 'string-ts';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
-import { Slottable, Slot } from '@radix-ui/react-slot';
+import { Slot, Slottable } from '@radix-ui/react-slot';
 import { Link, useBlocker } from '@tanstack/react-router';
 import { isEqual, omit } from 'es-toolkit';
 import { twMerge } from 'tailwind-merge';
-import { useFloating, autoUpdate, offset, flip, shift, size, useClick, useDismiss, useHover as useHover$1, useRole, useInteractions, FloatingPortal, useMergeRefs as useMergeRefs$1, FloatingFocusManager, arrow, useTransitionStatus, FloatingArrow } from '@floating-ui/react';
+import { useFloating, offset, flip, shift, size, autoUpdate, useClick, useDismiss, useHover as useHover$1, useRole, useInteractions, FloatingPortal, useMergeRefs as useMergeRefs$1, FloatingFocusManager, arrow, useTransitionStatus, FloatingArrow } from '@floating-ui/react';
 import { useVirtualizer } from '@tanstack/react-virtual';
 import { HelmetProvider, Helmet } from 'react-helmet-async';
 import { Trigger, Content, List as List$1, Root } from '@radix-ui/react-tabs';
@@ -254,6 +254,33 @@ const TAG_TEXT_MIN_WIDTH_PX = parseTailwindArbitraryValue(TAG_TEXT_MIN_WIDTH_CLA
  * - 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.
  *
+ * @example Status tags with different colors
+ * ```tsx
+ * import { Tag } from "@trackunit/react-components";
+ *
+ * const AssetStatus = () => (
+ *   <div className="flex gap-2">
+ *     <Tag color="success">Active</Tag>
+ *     <Tag color="warning">Idle</Tag>
+ *     <Tag color="danger">Offline</Tag>
+ *     <Tag color="info">Beta</Tag>
+ *   </div>
+ * );
+ * ```
+ * @example Dismissible tag for selections
+ * ```tsx
+ * import { Tag, Icon } from "@trackunit/react-components";
+ *
+ * const SelectedFilter = ({ label, onRemove }: { label: string; onRemove: () => void }) => (
+ *   <Tag
+ *     color="primary"
+ *     icon={<Icon name="Funnel" size="small" />}
+ *     onClose={onRemove}
+ *   >
+ *     {label}
+ *   </Tag>
+ * );
+ * ```
  * @param {TagProps} props - The props for the Tag component.
  * @returns {ReactElement} The rendered Tag component.
  */
@@ -771,8 +798,39 @@ 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](https://www.notion.so/Links-49638788b6c042698b40b94a318361f1?pvs=21) when the desired action is to take the user to a new page.
+ * 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.
+ *
+ * @example Basic button with click handler
+ * ```tsx
+ * import { Button } from "@trackunit/react-components";
+ *
+ * const MyComponent = () => {
+ *   return (
+ *     <Button onClick={() => console.log('clicked')}>
+ *       Click me
+ *     </Button>
+ *   );
+ * };
+ * ```
+ * @example Button variants and sizes
+ * ```tsx
+ * import { Button, Icon } from "@trackunit/react-components";
  *
+ * const ButtonExamples = () => {
+ *   return (
+ *     <div className="flex gap-2">
+ *       <Button variant="primary">Primary</Button>
+ *       <Button variant="secondary">Secondary</Button>
+ *       <Button variant="ghost">Ghost</Button>
+ *       <Button variant="primary-danger">Danger</Button>
+ *       <Button size="small">Small</Button>
+ *       <Button prefix={<Icon name="Plus" size="small" />}>With Icon</Button>
+ *       <Button loading>Loading</Button>
+ *       <Button disabled>Disabled</Button>
+ *     </div>
+ *   );
+ * };
+ * ```
  * @param {ButtonProps} props - The props for the Button component
  * @returns {ReactElement} Button component
  */
@@ -800,6 +858,45 @@ Button.displayName = "Button";
 
 /**
  * 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` 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.
+ *
+ * @example Basic icon button
+ * ```tsx
+ * import { IconButton, Icon } from "@trackunit/react-components";
+ *
+ * const MyComponent = () => {
+ *   return (
+ *     <IconButton
+ *       icon={<Icon name="Trash" />}
+ *       onClick={() => console.log('delete')}
+ *       title="Delete item"
+ *     />
+ *   );
+ * };
+ * ```
+ * @example Icon button variants
+ * ```tsx
+ * import { IconButton, Icon } from "@trackunit/react-components";
+ *
+ * const IconButtonExamples = () => {
+ *   return (
+ *     <div className="flex gap-2">
+ *       <IconButton icon={<Icon name="Plus" />} variant="primary" title="Add" />
+ *       <IconButton icon={<Icon name="Cog" />} variant="secondary" title="Settings" />
+ *       <IconButton icon={<Icon name="XMark" />} variant="ghost" title="Close" />
+ *       <IconButton icon={<Icon name="Trash" />} variant="primary-danger" title="Delete" />
+ *       <IconButton icon={<Icon name="Plus" />} size="small" title="Small add" />
+ *     </div>
+ *   );
+ * };
+ * ```
+ * @param {IconButtonProps} props - The props for the IconButton component
+ * @returns {ReactElement} IconButton component
  */
 const IconButton = ({ icon, size = "medium", square = true, loading = false, disabled = false, className, ref, ...rest }) => {
     return (jsx(Button, { className: cvaIconButton({ size: size, className }), disabled: disabled || loading, loading: loading, prefix: !loading ? icon : undefined, ref: ref, size: size, square: square, ...rest }));
@@ -901,8 +998,66 @@ const cvaAlertIconContainer = cvaMerge(["shrink-0", "grid", "w-min", "flex"], {
 });
 
 /**
- * The Alert component should be used to inform the user of important information.
+ * 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.
  *
+ * @example Basic alert variants
+ * ```tsx
+ * import { Alert } from "@trackunit/react-components";
+ *
+ * const AlertExamples = () => {
+ *   return (
+ *     <div className="flex flex-col gap-4">
+ *       <Alert color="info" title="Information">
+ *         Your session will expire in 5 minutes.
+ *       </Alert>
+ *       <Alert color="success" title="Success">
+ *         Asset successfully updated.
+ *       </Alert>
+ *       <Alert color="warning" title="Warning">
+ *         Low battery detected on 3 assets.
+ *       </Alert>
+ *       <Alert color="danger" title="Error">
+ *         Failed to save changes. Please try again.
+ *       </Alert>
+ *     </div>
+ *   );
+ * };
+ * ```
+ * @example Alert with actions and close button
+ * ```tsx
+ * import { Alert } from "@trackunit/react-components";
+ * import { useState } from "react";
+ *
+ * const DismissibleAlert = () => {
+ *   const [visible, setVisible] = useState(true);
+ *
+ *   if (!visible) return null;
+ *
+ *   return (
+ *     <Alert
+ *       color="warning"
+ *       title="Unsaved Changes"
+ *       onClose={() => setVisible(false)}
+ *       primaryAction={{
+ *         label: "Save Now",
+ *         onClick: () => console.log("Saving..."),
+ *       }}
+ *       secondaryAction={{
+ *         label: "Discard",
+ *         onClick: () => setVisible(false),
+ *       }}
+ *     >
+ *       You have unsaved changes that will be lost if you leave this page.
+ *     </Alert>
+ *   );
+ * };
+ * ```
  * @param {AlertProps} props - The props for the Alert component
  * @returns {ReactElement} Alert component
  */
@@ -1004,6 +1159,27 @@ const cvaBadge = cvaMerge([
  * - 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.
  *
+ * @example Badge with count and max value
+ * ```tsx
+ * import { Badge, Button } from "@trackunit/react-components";
+ *
+ * const NotificationButton = () => (
+ *   <Button variant="secondary">
+ *     Notifications <Badge count={15} max={9} color="danger" />
+ *   </Button>
+ * );
+ * ```
+ * @example Compact badge as status dot
+ * ```tsx
+ * import { Badge } from "@trackunit/react-components";
+ *
+ * const OnlineStatus = () => (
+ *   <div className="flex items-center gap-2">
+ *     <Badge compact color="primary" />
+ *     <span>Online</span>
+ *   </div>
+ * );
+ * ```
  * @param {BadgeProps} props - The props for the Badge component
  * @returns {ReactElement} Badge component
  */
@@ -1195,6 +1371,26 @@ const useBreadcrumbItemsToRender = (breadcrumbItems) => {
  * 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.
  *
+ * @example Basic breadcrumb navigation
+ * ```tsx
+ * import { Breadcrumb } from "@trackunit/react-components";
+ * import { useNavigate } from "@tanstack/react-router";
+ *
+ * const AssetDetailBreadcrumb = () => {
+ *   const navigate = useNavigate();
+ *
+ *   return (
+ *     <Breadcrumb
+ *       breadcrumbItems={[
+ *         { label: "Fleet", to: "/fleet" },
+ *         { label: "Assets", to: "/fleet/assets" },
+ *         { label: "Excavator 001", to: "/fleet/assets/123" },
+ *       ]}
+ *       back={() => navigate({ to: "/fleet/assets" })}
+ *     />
+ *   );
+ * };
+ * ```
  * @param {BreadcrumbProps} props - The props for the Breadcrumb component
  * @returns {ReactElement} Breadcrumb component
  */
@@ -1306,9 +1502,49 @@ const cvaCardBodyContainer = cvaMerge(["flex", "flex-grow", "overflow-auto"], {
 
 const ROLE_CARD = "region";
 /**
- * The Card component is a container for UI elements, and is the main component of the modal.
+ * 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.
+ *
+ * @example Basic card
+ * ```tsx
+ * import { Card, CardHeader, CardBody } from "@trackunit/react-components";
+ *
+ * const MyComponent = () => {
+ *   return (
+ *     <Card>
+ *       <CardHeader title="Asset Details" />
+ *       <CardBody>
+ *         <p>This card contains information about the asset.</p>
+ *       </CardBody>
+ *     </Card>
+ *   );
+ * };
+ * ```
+ * @example Clickable card with full content
+ * ```tsx
+ * import { Card, CardHeader, CardBody, CardFooter, Button } from "@trackunit/react-components";
+ *
+ * const AssetCard = () => {
+ *   return (
+ *     <Card onClick={() => console.log("Card clicked")}>
+ *       <CardHeader title="Excavator #1234" subtitle="Last updated: 2 hours ago" />
+ *       <CardBody>
+ *         <p>Operating hours: 1,234</p>
+ *         <p>Status: Active</p>
+ *       </CardBody>
+ *       <CardFooter>
+ *         <Button variant="secondary" size="small">View Details</Button>
+ *       </CardFooter>
+ *     </Card>
+ *   );
+ * };
+ * ```
  * @param {CardProps} props - The props for the Card component
  * @returns {ReactElement} Card component
  */
@@ -1642,7 +1878,7 @@ const cvaChevronIcon = cvaMerge(["transition-transform"], {
  * 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 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
@@ -1652,6 +1888,35 @@ const cvaChevronIcon = cvaMerge(["transition-transform"], {
  * - To hide errors or information that is relevant for a user within a flow.
  * - To creating hierarchy levels by nesting them within each other.
  *
+ * @example Basic collapse section
+ * ```tsx
+ * import { Collapse, Text } from "@trackunit/react-components";
+ *
+ * const AdditionalDetails = () => (
+ *   <Collapse id="details" label="Additional Details">
+ *     <Text>
+ *       This content is hidden by default and can be expanded by clicking the header.
+ *       Use this for supplementary information that isn't critical to the main flow.
+ *     </Text>
+ *   </Collapse>
+ * );
+ * ```
+ * @example Collapse with header addon and initial expanded state
+ * ```tsx
+ * import { Collapse, Badge } from "@trackunit/react-components";
+ *
+ * const NotificationsSection = () => (
+ *   <Collapse
+ *     id="notifications"
+ *     label="Notifications"
+ *     initialExpanded={true}
+ *     headerAddon={<Badge count={5} color="primary" />}
+ *     onToggle={(e, expanded) => console.log("Expanded:", expanded)}
+ *   >
+ *     <div>Notification list content here</div>
+ *   </Collapse>
+ * );
+ * ```
  * @param {CollapseProps} props - The props for the Collapse component
  * @returns {ReactElement} Collapse component
  */
@@ -2014,13 +2279,52 @@ WorkerWithSignSVG.displayName = "WorkerWithSignSVG";
 
 /**
  *
- * Empty states serve as placeholders when there's no content to display in either a table or card. They guide users out of the empty state towards actionable steps, highlighting ways to progress. It’s recommended to suggest simple actions that can help the users move out of the empty states towards the content that fits their goals.
+ * Empty states serve as placeholders when there's no content to display in either a table or card. They guide users out of the empty state towards actionable steps, highlighting ways to progress. It's recommended to suggest simple actions that can help the users move out of the empty states towards the content that fits their goals.
  * ## **When to Use**
  * - When user actions yield no results (e.g., empty search results or unfilled data).
  * - To offer guidance on navigating out of the empty state.
  * - In cases of errors (e.g., failed content loading, unexpected errors).
  * - For guidance purposes (e.g., onboarding, adjusting filters, exploring alternative approaches).
  * - In celebratory instances (e.g., no new notifications, services up to date).
+ *
+ * @example Empty state with actions for no search results
+ * ```tsx
+ * import { EmptyState } from "@trackunit/react-components";
+ *
+ * const NoSearchResults = () => (
+ *   <EmptyState
+ *     image="SEARCH_DOCUMENT"
+ *     description="No assets match your search criteria"
+ *     primaryAction={{
+ *       title: "Clear filters",
+ *       onClick: () => console.log("Clear filters"),
+ *     }}
+ *     secondaryAction={{
+ *       title: "Add new asset",
+ *       onClick: () => console.log("Add asset"),
+ *     }}
+ *   />
+ * );
+ * ```
+ * @example Empty state for error with help link
+ * ```tsx
+ * import { EmptyState } from "@trackunit/react-components";
+ *
+ * const ErrorState = () => (
+ *   <EmptyState
+ *     image="BUILDING_ERROR"
+ *     description="Something went wrong while loading your data"
+ *     primaryAction={{
+ *       title: "Try again",
+ *       onClick: () => window.location.reload(),
+ *     }}
+ *     additionalHelpAction={{
+ *       title: "Contact support",
+ *       to: { pathname: "https://support.trackunit.com", target: "_blank" },
+ *     }}
+ *   />
+ * );
+ * ```
  */
 const EmptyState = ({ description, altText, image = "SEARCH_DOCUMENT", customImageSrc, loading = false, "data-testid": dataTestId, className, primaryAction, secondaryAction, additionalHelpAction, }) => {
     const ImageSource = useMemo(() => {
@@ -3541,6 +3845,45 @@ const usePopoverContext = () => {
  *
  * To render the content of the popover, use the `<PopoverContent />` component.
  *
+ * @example Basic popover with trigger
+ * ```tsx
+ * import { Popover, PopoverTrigger, PopoverContent, Button, Text } from "@trackunit/react-components";
+ *
+ * const InfoPopover = () => (
+ *   <Popover placement="bottom-start">
+ *     <PopoverTrigger>
+ *       <Button variant="secondary">Show Info</Button>
+ *     </PopoverTrigger>
+ *     <PopoverContent>
+ *       <div className="p-4 max-w-xs">
+ *         <Text weight="bold">Asset Information</Text>
+ *         <Text size="small">Additional details about this asset appear here.</Text>
+ *       </div>
+ *     </PopoverContent>
+ *   </Popover>
+ * );
+ * ```
+ * @example Controlled popover with render prop
+ * ```tsx
+ * import { Popover, PopoverTrigger, PopoverContent, Button } from "@trackunit/react-components";
+ *
+ * const ControlledPopover = () => (
+ *   <Popover placement="right">
+ *     {({ isOpen, setIsOpen }) => (
+ *       <>
+ *         <PopoverTrigger>
+ *           <Button onClick={() => setIsOpen(!isOpen)}>
+ *             {isOpen ? "Close" : "Open"} Menu
+ *           </Button>
+ *         </PopoverTrigger>
+ *         <PopoverContent>
+ *           <div className="p-4">Popover content</div>
+ *         </PopoverContent>
+ *       </>
+ *     )}
+ *   </Popover>
+ * );
+ * ```
  * @param {PopoverProps} props The props for the popover
  * @returns {ReactElement} A Popover Context Provider containing the children
  */
@@ -3712,6 +4055,35 @@ const FloatingArrowContainer = ({ arrowRef, mode = "dark", }) => {
  *
  * **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.
  *
+ * @example Tooltip on an icon button
+ * ```tsx
+ * import { Tooltip, IconButton, Icon } from "@trackunit/react-components";
+ *
+ * const SettingsButton = () => (
+ *   <Tooltip label="Open settings" placement="bottom">
+ *     <IconButton
+ *       icon={<Icon name="Cog6Tooth" size="small" />}
+ *       variant="ghost-neutral"
+ *       onClick={() => console.log("Settings clicked")}
+ *     />
+ *   </Tooltip>
+ * );
+ * ```
+ * @example Standalone tooltip icon for explanations
+ * ```tsx
+ * import { Tooltip } from "@trackunit/react-components";
+ *
+ * const FieldWithHelp = () => (
+ *   <div className="flex items-center gap-2">
+ *     <span>Utilization Rate</span>
+ *     <Tooltip
+ *       label="The percentage of time the asset was actively in use during the selected period"
+ *       placement="right"
+ *       mode="light"
+ *     />
+ *   </div>
+ * );
+ * ```
  * @param {TooltipProps} props - The props for the Tooltip component
  * @returns {ReactElement} Tooltip component
  */
@@ -3877,7 +4249,32 @@ const cvaIndicatorIconBackground = cvaMerge(["rounded-full", "items-center", "ju
  * _**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._
- 
+ *
+ * @example Asset status indicator with icon
+ * ```tsx
+ * import { Indicator, Icon } from "@trackunit/react-components";
+ *
+ * const AssetStatusIndicator = () => (
+ *   <Indicator
+ *     icon={<Icon name="Bolt" size="small" />}
+ *     color="success"
+ *     label="Running"
+ *   />
+ * );
+ * ```
+ * @example Pinging indicator for alerts
+ * ```tsx
+ * import { Indicator, Icon } from "@trackunit/react-components";
+ *
+ * const AlertIndicator = () => (
+ *   <Indicator
+ *     icon={<Icon name="ExclamationTriangle" size="small" />}
+ *     color="danger"
+ *     label="Critical Alert"
+ *     ping={true}
+ *   />
+ * );
+ * ```
  * @param {IndicatorProps} props - The props for the Indicator component
  * @returns {ReactElement} Indicator component
  */
@@ -3974,8 +4371,43 @@ const cvaKPITrendPercentage = cvaMerge([""], {
 });
 
 /**
- * The KPI component is used to display KPIs.
+ * 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)
+ *
+ * @example Basic KPI display
+ * ```tsx
+ * import { KPI } from "@trackunit/react-components";
+ *
+ * const FleetUtilization = () => (
+ *   <KPI
+ *     title="Fleet Utilization"
+ *     value={87}
+ *     unit="%"
+ *     tooltipLabel="Average utilization across all assets"
+ *   />
+ * );
+ * ```
+ * @example KPI variants
+ * ```tsx
+ * import { KPI } from "@trackunit/react-components";
  *
+ * const MetricsRow = () => (
+ *   <div className="flex gap-4">
+ *     <KPI title="Total Assets" value={156} unit="units" variant="default" />
+ *     <KPI title="Active" value={142} unit="" variant="small" />
+ *     <KPI title="Idle Time" value="2.5" unit="hrs" variant="condensed" />
+ *   </div>
+ * );
+ * ```
  * @param {KPIProps} props - The props for the KPI component
  * @returns {ReactElement} KPI component
  */
@@ -4332,8 +4764,54 @@ const cvaKPIIconContainer = cvaMerge(["flex", "items-center", "justify-center",
 });
 
 /**
- * The KPICard component is used to display KPIs.
+ * 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
  *
+ * @example KPI card with trend indicator
+ * ```tsx
+ * import { KPICard } from "@trackunit/react-components";
+ *
+ * const UtilizationCard = () => (
+ *   <KPICard
+ *     title="Utilization"
+ *     value={87}
+ *     unit="%"
+ *     iconName="ChartBar"
+ *     iconColor="success"
+ *     trends={[
+ *       { value: 5, direction: "up", label: "vs last week" },
+ *     ]}
+ *     onClick={() => console.log("Navigate to details")}
+ *   />
+ * );
+ * ```
+ * @example KPI card with value bar and notice
+ * ```tsx
+ * import { KPICard } from "@trackunit/react-components";
+ *
+ * const StorageCard = () => (
+ *   <KPICard
+ *     title="Storage Used"
+ *     value={75}
+ *     unit="GB"
+ *     valueBar={{ value: 75, max: 100 }}
+ *     notice={{
+ *       label: "25 GB remaining",
+ *       iconName: "InformationCircle",
+ *       iconColor: "info",
+ *     }}
+ *   />
+ * );
+ * ```
  * @param {KPICardProps} props - The props for the KPICard component
  * @returns {ReactElement} KPICard component
  */
@@ -4425,7 +4903,6 @@ const cvaDetailsContainer = cvaMerge(["flex", "items-center", "gap-0.5", "text-n
  */
 const DEFAULT_SKELETON_LIST_ITEM_PROPS = {
     hasThumbnail: true,
-    thumbnailShape: "circle",
     hasDescription: true,
     hasMeta: false,
     hasDetails: false,
@@ -5191,8 +5668,53 @@ const MenuItem = ({ className, "data-testid": dataTestId, label, children, selec
  * **When to use**
  * - Use the MenuList if you have limited space and need to display overflow actions in a list.
  * - Use the MenuList for actions that are not essential to completing workflows.
- * - Don’t use the MenuList to display single or multi-select items within form components. For dropdowns within select components, use SelectDropdown (component not available yet).
+ * - Don't use the MenuList to display single or multi-select items within form components. For dropdowns within select components, use SelectDropdown (component not available yet).
+ *
+ * @example MenuList with action items
+ * ```tsx
+ * import { MenuList, MenuItem, MoreMenu, Icon } from "@trackunit/react-components";
+ *
+ * const ActionsMenu = () => (
+ *   <MoreMenu>
+ *     {(close) => (
+ *       <MenuList onClick={close}>
+ *         <MenuItem id="edit" prefix={<Icon name="PencilSquare" size="small" />}>
+ *           Edit
+ *         </MenuItem>
+ *         <MenuItem id="duplicate" prefix={<Icon name="DocumentDuplicate" size="small" />}>
+ *           Duplicate
+ *         </MenuItem>
+ *         <MenuItem id="delete" prefix={<Icon name="Trash" size="small" />} destructive>
+ *           Delete
+ *         </MenuItem>
+ *       </MenuList>
+ *     )}
+ *   </MoreMenu>
+ * );
+ * ```
+ * @example Multi-select MenuList
+ * ```tsx
+ * import { MenuList, MenuItem, MoreMenu } from "@trackunit/react-components";
+ * import { useState } from "react";
+ *
+ * const FilterMenu = () => {
+ *   const [selected, setSelected] = useState<string[]>(["active"]);
  *
+ *   return (
+ *     <MoreMenu label="Filter by status">
+ *       <MenuList
+ *         isMulti
+ *         selectedItems={selected}
+ *         onSelectionChange={setSelected}
+ *       >
+ *         <MenuItem id="active">Active</MenuItem>
+ *         <MenuItem id="idle">Idle</MenuItem>
+ *         <MenuItem id="offline">Offline</MenuItem>
+ *       </MenuList>
+ *     </MoreMenu>
+ *   );
+ * };
+ * ```
  * @param {MenuListProps} props - The props for the MenuList component
  * @returns {ReactElement} MenuList component
  */
@@ -5519,6 +6041,45 @@ const PageHeaderTitle = ({ title, "data-testid": dataTestId, className, }) => {
  * 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.
  *
+ * @example Page header with actions
+ * ```tsx
+ * import { PageHeader } from "@trackunit/react-components";
+ *
+ * const AssetPage = () => (
+ *   <PageHeader
+ *     title="Asset Management"
+ *     description="Manage and monitor your fleet assets"
+ *     accessoryType="actions"
+ *     primaryAction={{
+ *       actionText: "Add Asset",
+ *       actionCallback: () => console.log("Add asset"),
+ *       prefixIconName: "Plus",
+ *       variant: "primary",
+ *     }}
+ *     secondaryActions={[
+ *       { actionText: "Export", actionCallback: () => {}, variant: "secondary" },
+ *     ]}
+ *   />
+ * );
+ * ```
+ * @example Page header with KPI metrics
+ * ```tsx
+ * import { PageHeader } from "@trackunit/react-components";
+ *
+ * const DashboardHeader = () => (
+ *   <PageHeader
+ *     title="Fleet Overview"
+ *     tagLabel="Live"
+ *     tagColor="success"
+ *     accessoryType="kpi-metrics"
+ *     kpiMetrics={[
+ *       { header: "Total Assets", value: 156, unit: "" },
+ *       { header: "Active", value: 142, unit: "assets" },
+ *       { header: "Utilization", value: 87, unit: "%" },
+ *     ]}
+ *   />
+ * );
+ * ```
  * @param {PageHeaderProps} props - The props for the PageHeader component
  * @returns {ReactElement} PageHeader component
  */
@@ -6012,6 +6573,27 @@ const useOverflowItems = ({ threshold = 1, childUniqueIdentifierAttribute = "id"
  *
  * When using this component make sure to add `setupIntersectionObserver();` to your jest.setup.ts file.
  *
+ * @example Responsive sidebar with navigation items
+ * ```tsx
+ * import { Sidebar, Button } from "@trackunit/react-components";
+ *
+ * const NavigationSidebar = () => (
+ *   <Sidebar breakpoint="lg">
+ *     <Button id="overview" variant="ghost-neutral" className="min-w-[100px]">
+ *       Overview
+ *     </Button>
+ *     <Button id="assets" variant="ghost-neutral" className="min-w-[100px]">
+ *       Assets
+ *     </Button>
+ *     <Button id="reports" variant="ghost-neutral" className="min-w-[100px]">
+ *       Reports
+ *     </Button>
+ *     <Button id="settings" variant="ghost-neutral" className="min-w-[100px]">
+ *       Settings
+ *     </Button>
+ *   </Sidebar>
+ * );
+ * ```
  * @param {SidebarProps} props - The props for the Sidebar component
  * @returns {ReactElement} Sidebar component
  */
@@ -6165,6 +6747,39 @@ 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.
+ *
+ * @example Basic tabs with content panels
+ * ```tsx
+ * import { Tabs, TabList, Tab, TabContent } from "@trackunit/react-components";
+ *
+ * const MyTabs = () => (
+ *   <Tabs defaultValue="tab1">
+ *     <TabList>
+ *       <Tab value="tab1">Overview</Tab>
+ *       <Tab value="tab2">Details</Tab>
+ *       <Tab value="tab3">Settings</Tab>
+ *     </TabList>
+ *     <TabContent value="tab1">Overview content goes here</TabContent>
+ *     <TabContent value="tab2">Details content goes here</TabContent>
+ *     <TabContent value="tab3">Settings content goes here</TabContent>
+ *   </Tabs>
+ * );
+ * ```
+ * @example Full width tabs with icons
+ * ```tsx
+ * import { Tabs, TabList, Tab, TabContent } from "@trackunit/react-components";
+ *
+ * const FullWidthTabs = () => (
+ *   <Tabs defaultValue="assets" fullWidth>
+ *     <TabList>
+ *       <Tab value="assets" iconName="Truck" isFullWidth>Assets</Tab>
+ *       <Tab value="sites" iconName="MapPin" isFullWidth>Sites</Tab>
+ *     </TabList>
+ *     <TabContent value="assets">Asset list</TabContent>
+ *     <TabContent value="sites">Site list</TabContent>
+ *   </Tabs>
+ * );
+ * ```
  */
 const Tabs = ({ children, forceRender, className, "data-testid": dataTestId, fullWidth, ...rest }) => {
     return (jsx(Root, { className: cvaTabsRoot({ className }), "data-testid": dataTestId, ...rest, children: children }));