@trackunit/react-components 1.17.22 → 1.17.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.17.22",
+  "version": "1.17.23",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {

package/src/components/Badge/Badge.d.ts

@@ -39,14 +39,21 @@ interface BaseBadgeProps extends CommonProps, Refable<HTMLSpanElement> {
 }
 export type BadgeProps = BaseBadgeProps;
 /**
- * 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.
  *
- * How to choose between Badge and Tag?
+ * ### When to use
+ * Use Badge to indicate a count (e.g., unread notifications, active filters) or as a compact status dot.
+ *
+ * ### When not to use
+ * Do not use Badge for labeling statuses or categories — use `Tag` instead.
+ * Do not use Badge for highlighting data values — use `Highlight`.
+ *
+ * How to choose between Badge and `Tag`?
  * - Use a Badge to indicate notifications or counts of applied elements.
- * - Use a [Tag](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";
  *
@@ -56,7 +63,7 @@ export type BadgeProps = BaseBadgeProps;
  *   </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";
  *

package/src/components/Card/CardBody.d.ts

@@ -24,10 +24,45 @@ export interface CardBodyProps extends CommonProps, Refable<HTMLDivElement> {
     id?: string;
 }
 /**
- * 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.
  *
- * @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
+ * 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.
+ *
+ * ### 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
  */

package/src/components/Card/CardFooter.d.ts

@@ -16,10 +16,51 @@ export interface CardFooterProps extends CommonProps, Refable<HTMLDivElement> {
     padding?: "none" | "default";
 }
 /**
- * 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
  */

package/src/components/Card/CardHeader.d.ts

@@ -9,7 +9,7 @@ export interface CardHeaderProps extends CommonProps, Refable<HTMLDivElement> {
     heading?: string;
     /**
      * The variant/size of the heading.
-     * Same as the `Heading` component.
+     * Same as the Heading component.
      *
      * @default "secondary"
      */
@@ -43,8 +43,49 @@ export interface CardHeaderProps extends CommonProps, Refable<HTMLDivElement> {
     padding?: "none" | "default";
 }
 /**
- * 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
  */

package/src/components/CompletionStatusIndicator/CompletionStatusIndicator.d.ts

@@ -6,16 +6,25 @@ export interface CompletionStatusIndicatorProps extends CommonProps {
     error: boolean;
 }
 /**
- * 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
  */
 export declare const CompletionStatusIndicator: ({ loading, error, success, ...rest }: CompletionStatusIndicatorProps) => ReactElement | null;

package/src/components/CopyableText/CopyableText.d.ts

@@ -14,8 +14,34 @@ export interface CopyableTextProps extends CommonProps, Refable<HTMLSpanElement>
     alternativeText?: string;
 }
 /**
- * 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
  */

package/src/components/DetailsList/DetailsList.d.ts

@@ -6,14 +6,35 @@ interface DetailsListProps extends Refable<HTMLDivElement> {
     hasLink?: boolean;
 }
 /**
- * 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.
  *
- * @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.
+ * ### 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";
+ *
+ * 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
  */
 export declare const DetailsList: ({ details, className, hasLink, ref }: DetailsListProps) => ReactElement;
 export {};

package/src/components/EmptyState/EmptyState.d.ts

@@ -13,13 +13,37 @@ type EmptyStateButtonAction = {
     };
 };
 export interface EmptyStateProps extends CommonProps, Refable<HTMLDivElement> {
+    /**
+     * Description text to display below the image. Explains the empty state and guides the user.
+     */
     description?: string;
+    /**
+     * Alt text for the custom image source. Used for accessibility when `customImageSrc` is a URL string.
+     */
     altText?: string;
+    /**
+     * Predefined illustration to display. Options: "WORKER_WITH_SIGN", "ROAD_BLOCK", "BUILDING_ERROR", "WALL_CONSTRUCTION", "PHONE_LOCK_SECURITY", "SEARCH_DOCUMENT".
+     */
     image?: EmptyStateImage;
+    /**
+     * A custom image URL string or ReactNode to replace the predefined illustration.
+     */
     customImageSrc?: string | ReactNode;
+    /**
+     * Primary action button configuration. Recommend the best next step for users to proceed.
+     */
     primaryAction?: EmptyStateButtonAction;
+    /**
+     * Secondary action button configuration. Suggest an alternative action users could consider.
+     */
     secondaryAction?: EmptyStateButtonAction;
+    /**
+     * Additional help action (e.g., a link to external documentation or support).
+     */
     additionalHelpAction?: EmptyStateButtonAction;
+    /**
+     * Whether the component is in a loading state. Shows a spinner and skeleton text instead of the illustration.
+     */
     loading?: boolean;
 }
 /**

package/src/components/EmptyValue/EmptyValue.d.ts

@@ -3,8 +3,26 @@ import { CommonProps } from "../../common/CommonProps";
 import { Refable } from "../../common/Refable";
 export type EmptyValueProps = CommonProps & Refable<HTMLDivElement>;
 /**
- *  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
  */

package/src/components/ExternalLink/ExternalLink.d.ts

@@ -29,9 +29,40 @@ export interface ExternalLinkProps extends CommonProps, Refable<HTMLAnchorElemen
     onClick?: MouseEventHandler<HTMLAnchorElement>;
 }
 /**
- *  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
  */
 export declare const ExternalLink: ({ rel, target, href, className, children, title, "data-testid": dataTestId, onClick, color, ref, }: ExternalLinkProps) => ReactElement;

package/src/components/Heading/Heading.d.ts

@@ -21,8 +21,29 @@ export interface HeadingProps extends CommonProps, Refable<HTMLHeadingElement> {
     subtle?: boolean;
 }
 /**
- * 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
  */

package/src/components/Highlight/Highlight.d.ts

@@ -21,15 +21,40 @@ export interface HighlightProps extends CommonProps {
     ref?: Ref<HTMLDivElement>;
 }
 /**
- * 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.
  *
- * 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.
+ * ### 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).
  *
- * @param {HighlightProps} props - The props for the highlight component
- * @returns {ReactElement} highlight component
+ * ### 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";
+ *
+ * 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";
+ *
+ * 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
  */
 export declare const Highlight: {
     ({ className, "data-testid": dataTestId, children, size, color, ref, }: HighlightProps): ReactElement;

package/src/components/HorizontalOverflowScroller/HorizontalOverflowScroller.d.ts

@@ -14,15 +14,30 @@ export interface HorizontalOverflowScrollerProps extends CommonProps, Styleable,
     }) => void;
 }
 /**
- * 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
  */
 export declare const HorizontalOverflowScroller: ({ className, "data-testid": dataTestId, children, onScrollStateChange, ref, }: HorizontalOverflowScrollerProps) => ReactElement;

package/src/components/Icon/Icon.d.ts

@@ -294,10 +294,27 @@ export type IconProps = DiscriminatedIconProps & CommonProps & AriaProps & Refab
     fontSize?: boolean;
 };
 /**
- * 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
  */

package/src/components/KPI/KPISkeleton.d.ts

@@ -9,7 +9,28 @@ export interface KPISkeletonProps extends CommonProps, Styleable, Refable<HTMLDi
     variant?: "small" | "default" | "condensed";
 }
 /**
- * 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
  */
 export declare const KPISkeleton: ({ variant, className, "data-testid": dataTestId, style, ref, ...rest }: KPISkeletonProps) => ReactElement;