@trackunit/react-components 1.17.21 → 1.17.23

package/src/components/KPICard/KPICardSkeleton.d.ts

@@ -25,7 +25,28 @@ export interface KPICardSkeletonProps extends CommonProps, Styleable, Refable<HT
     children?: ReactNode;
 }
 /**
- * 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
  */
 export declare const KPICardSkeleton: ({ hasIcon, hasTrends, hasValueBar, hasNotice, children, className, "data-testid": dataTestId, style, ref, ...rest }: KPICardSkeletonProps) => ReactElement;

package/src/components/ListItem/ListItem.d.ts

@@ -36,10 +36,32 @@ export interface ListItemProps extends CommonProps, ListItemVirtualizationProps,
     thumbnailBackground?: `${ThemeColors}-${ThemeColorShades}` | `${ThemeColors}`;
 }
 /**
- *   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
  */
 export declare const ListItem: ({ className, "data-testid": dataTestId, onClick, details, title, description, meta, thumbnail, thumbnailColor, thumbnailBackground, ...rest }: ListItemProps) => ReactElement;
 export {};

package/src/components/ListItem/ListItemSkeleton.d.ts

@@ -22,7 +22,29 @@ export interface ListItemSkeletonProps {
     hasDetails?: boolean;
 }
 /**
- * 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
  */
 export declare const ListItemSkeleton: ({ hasThumbnail, thumbnailShape, hasDescription, hasMeta, hasDetails, }: ListItemSkeletonProps) => ReactElement;

package/src/components/Menu/MenuDivider/MenuDivider.d.ts

@@ -1,5 +1,26 @@
 import { ReactElement } from "react";
 /**
- * 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
  */
 export declare const MenuDivider: () => ReactElement;

package/src/components/Menu/MenuItem/MenuItem.d.ts

@@ -86,8 +86,37 @@ export interface MenuItemProps extends CommonProps, Refable<HTMLDivElement> {
     fieldSize?: VariantProps<typeof cvaMenuItemStyle>["fieldSize"];
 }
 /**
- * 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
  */

package/src/components/Menu/MoreMenu/MoreMenu.d.ts

@@ -10,17 +10,71 @@ export type MenuPlacement = "above" | "below";
 type FilteredIconProps = MakePropertyOptional<MappedOmit<IconProps, "onClick">, "name">;
 type FilteredIconButtonProps = Omit<IconButtonProps, "icon" | "onClick">;
 export interface MoreMenuProps extends CommonProps, Refable<HTMLDivElement> {
+    /**
+     * Content to render inside the popover. Receives a `close` callback as a render prop, or accepts static ReactNode children.
+     */
     children: PopoverContentChildren;
+    /**
+     * Props to forward to the underlying Popover component (e.g., `placement`, `offset`).
+     */
     popoverProps?: PopoverProps;
+    /**
+     * Props to customize the kebab icon (e.g., `size`, `className`). The `name` defaults to "EllipsisHorizontal".
+     */
     iconProps?: FilteredIconProps;
+    /**
+     * Props to customize the trigger IconButton (e.g., `size`, `variant`).
+     */
     iconButtonProps?: FilteredIconButtonProps;
+    /**
+     * A custom portal ID for the popover content. Useful when rendering inside modals or other portal containers.
+     */
     customPortalId?: string;
+    /**
+     * A custom trigger element to replace the default kebab IconButton.
+     */
     customButton?: ReactNode;
 }
 /**
- * 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
  */

package/src/components/Notice/Notice.d.ts

@@ -43,12 +43,42 @@ export interface NoticeProps extends CommonProps, Refable<HTMLDivElement> {
     withTooltip?: boolean;
 }
 /**
- * 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
  */

package/src/components/Page/Page.d.ts

@@ -8,14 +8,50 @@ import { cvaPage } from "./Page.variants";
  */
 export type Layout = VariantProps<typeof cvaPage>["layout"];
 /**
- * The props for the page component.
+ * The props for the Page component.
  */
 export interface PageProps extends CommonProps, Refable<HTMLDivElement> {
+    /**
+     * The layout mode of the page. Controls how content is arranged within the page container.
+     */
     layout: Layout;
+    /**
+     * The child elements to render inside the page.
+     */
     children?: ReactNode;
+    /**
+     * An ID that can be used in tests to locate the component. Defaults to "page".
+     */
     "data-testid"?: string;
 }
 /**
- * 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
  */
 export declare const Page: ({ layout, className, children, "data-testid": dataTestId, ref }: PageProps) => ReactElement;

package/src/components/Page/PageContent.d.ts

@@ -8,18 +8,47 @@ import { cvaPageContent } from "./Page.variants";
  */
 export type PageContentLayout = VariantProps<typeof cvaPageContent>["layout"];
 /**
- * The props for the page content component.
+ * The props for the PageContent component.
  */
 interface PageContentProps extends CommonProps, Refable<HTMLDivElement> {
+    /**
+     * The layout mode for the page content area. Controls content arrangement and spacing.
+     */
     layout: PageContentLayout;
+    /**
+     * The child elements to render inside the page content area.
+     */
     children?: ReactNode;
 }
 /**
- * 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.
  *
- * @param {PageContentProps} props - The component props.
- * @returns {ReactNode} - The rendered 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`.
+ *
+ * @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
  */
 export declare const PageContent: ({ className, children, "data-testid": dataTestId, layout, ref, }: PageContentProps) => ReactElement;
 export {};

package/src/components/PageHeader/PageHeader.d.ts

@@ -1,11 +1,15 @@
 import { ReactElement } from "react";
 import { PageHeaderProps } from "./types";
 /**
- * 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

package/src/components/Pagination/Pagination.d.ts

@@ -55,8 +55,37 @@ export interface PaginationProps extends Refable<HTMLDivElement> {
     cursorBase?: boolean;
 }
 /**
- * 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
  */

package/src/components/Polygon/Polygon.d.ts

@@ -3,16 +3,51 @@ import { CommonProps } from "../../common/CommonProps";
 import { Refable } from "../../common/Refable";
 type Point = [number, number];
 export interface PolygonProps extends CommonProps, Refable<SVGSVGElement> {
+    /**
+     * Array of [x, y] coordinate pairs defining the polygon's vertices. Points are normalized to fit within the given size.
+     */
     points: Array<Point>;
+    /**
+     * The pixel dimensions (width and height) of the SVG viewport.
+     */
     size: number;
+    /**
+     * Fill and stroke color of the polygon.
+     *
+     * @default "black"
+     */
     color?: "white" | "black";
+    /**
+     * Whether the fill should be semi-transparent (20% opacity) and the stroke slightly transparent (80% opacity).
+     *
+     * @default true
+     */
     opaque?: boolean;
 }
 /**
- *  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.
  *
- * @param { PolygonProps} props - The props for the  Polygon component
- * @returns {ReactElement}  Polygon component
+ * ### 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";
+ *
+ * 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
  */
 export declare const Polygon: ({ points, size, color, opaque, className, "data-testid": dataTestId, ref, }: PolygonProps) => ReactElement;
 export {};

package/src/components/Popover/Popover.d.ts

@@ -14,14 +14,16 @@ type ModalCallback = {
     placement: PopoverPlacement;
 };
 /**
- * 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

package/src/components/Popover/PopoverContent.d.ts

@@ -37,11 +37,37 @@ export interface PopoverContentProps extends Omit<HTMLProps<HTMLDivElement>, "ch
     ref?: Ref<HTMLDivElement>;
 }
 /**
- * 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
  */

package/src/components/Popover/PopoverTitle.d.ts

@@ -2,19 +2,53 @@ import { ReactElement, ReactNode } from "react";
 import { CommonProps } from "../../common/CommonProps";
 import { Refable } from "../../common/Refable";
 export interface PopoverTitleProps extends CommonProps, Refable<HTMLDivElement> {
+    /**
+     * An optional action element (e.g., a close button or link) rendered to the right of the title.
+     */
     action?: ReactNode;
     /**
      * Whether there should be a divider between the title and the content.
      */
     divider?: boolean;
     /**
-     * The child nodes.
+     * The title text or elements to display.
      */
     children?: ReactNode;
 }
 /**
- * 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
  */