@trackunit/react-components 1.17.22 → 1.17.23

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

@@ -1,19 +1,50 @@
 import { HTMLProps, ReactElement, ReactNode, Ref } from "react";
 interface PopoverTriggerProps extends HTMLProps<HTMLElement> {
     /**
-     * When enabled the trigger will be rendered as a button
-     * note that not all elements are valid children of a button
+     * The element that acts as the trigger. Typically a Button or IconButton.
+     * When `renderButton` is false (default), the child element is cloned with popover props.
+     * When `renderButton` is true, children are wrapped in a Button.
      */
     children: ReactNode;
+    /**
+     * When true, wraps children in a default Button element. Use false (default) when passing
+     * your own Button or interactive element as children.
+     */
     renderButton?: boolean;
     /**
-     * A ref for the component
+     * A ref for the component.
      */
     ref?: Ref<HTMLElement>;
 }
 /**
- * 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
  */

package/src/components/Portal/Portal.d.ts

@@ -2,9 +2,40 @@ import { FloatingPortalProps } from "@floating-ui/react";
 import { ReactElement } from "react";
 export type PortalProps = FloatingPortalProps;
 /**
- * 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
  */
 export declare const Portal: (props: FloatingPortalProps) => ReactElement;

package/src/components/PreferenceCard/PreferenceCard.d.ts

@@ -63,9 +63,31 @@ export interface PreferenceCardProps extends CommonProps, Refable<HTMLDivElement
     children?: ReactNode;
 }
 /**
- * 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
  */
 export declare const PreferenceCard: ({ title, description, icon, input, titleTag, cardTag, disabled, className, "data-testid": dataTestId, children, ref: forwardedRef, }: PreferenceCardProps) => ReactNode;
 export {};

package/src/components/PreferenceCard/PreferenceCardSkeleton.d.ts

@@ -20,7 +20,28 @@ export interface PreferenceCardSkeletonProps extends Refable<HTMLDivElement> {
     hasInput?: boolean;
 }
 /**
- * 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
  */
 export declare const PreferenceCardSkeleton: ({ hasIcon, hasTitleTag, hasCardTag, hasInput, ref, }: PreferenceCardSkeletonProps) => ReactElement;

package/src/components/Prompt/Prompt.d.ts

@@ -3,18 +3,52 @@ interface PromptProps {
     message: string;
 }
 /**
- * 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}
  */
 export declare const usePrompt: (message: string, when?: boolean) => void;
 /**
- * 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.
+ *
+ * ### 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";
  *
- * @param {PromptProps} Props -
- * @returns {void} void
+ * 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
  */
 export declare const Prompt: ({ when, message }: PromptProps) => null;
 export {};

package/src/components/SectionHeader/SectionHeader.d.ts

@@ -16,9 +16,29 @@ export interface SectionHeaderProps extends CommonProps, Refable<HTMLDivElement>
     addons?: ReactNode;
 }
 /**
- * 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
  */
 export declare const SectionHeader: ({ title, subtitle, "data-testid": dataTestId, addons, ref, }: SectionHeaderProps) => ReactElement;

package/src/components/Sidebar/Sidebar.d.ts

@@ -46,12 +46,19 @@ export interface SidebarProps extends CommonProps, Refable<HTMLDivElement> {
     menuListProps?: Omit<ComponentProps<typeof MenuList>, "children">;
 }
 /**
- * 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.
  *
- * When using this component make sure to add `setupIntersectionObserver();` to your jest.setup.ts file.
+ * **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 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

package/src/components/Skeleton/SkeletonBlock/SkeletonBlock.d.ts

@@ -38,12 +38,28 @@ export type SkeletonBlockProps = CommonProps & Refable<HTMLDivElement> & {
     children?: ReactNode;
 };
 /**
- * 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.
  *
- * For text content, use SkeletonLabel component instead.
- * For multiple text lines, use SkeletonLines component instead.
+ * ### 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";
+ *
+ * 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
  */
 export declare const SkeletonBlock: import("react").NamedExoticComponent<SkeletonBlockProps>;

package/src/components/Skeleton/SkeletonLabel/SkeletonLabel.d.ts

@@ -41,12 +41,28 @@ export type SkeletonLabelProps = CommonProps & Refable<HTMLDivElement> & {
     children?: ReactNode;
 };
 /**
- * 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.
  *
- * 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.
+ * ### When to use
+ * Use SkeletonLabel as a loading placeholder for single text lines: labels, titles, descriptions, values.
  *
- * For multiple text lines, use SkeletonLines component instead.
- * For shape-based elements (images, badges, buttons), use SkeletonBlock component instead.
+ * ### When not to use
+ * For multiple text lines, use `SkeletonLines`.
+ * For shape-based elements (images, icons, avatars), use `SkeletonBlock`.
+ *
+ * @example Skeleton label for a title and description
+ * ```tsx
+ * import { SkeletonLabel } from "@trackunit/react-components";
+ *
+ * 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
  */
 export declare const SkeletonLabel: import("react").NamedExoticComponent<SkeletonLabelProps>;

package/src/components/SkeletonLines/SkeletonLines.d.ts

@@ -122,14 +122,16 @@ type PresetSkeletonLinesProps = CommonProps & Refable<HTMLDivElement> & {
  */
 export type SkeletonLinesProps = UniformSkeletonLinesProps | CustomSkeletonLinesProps | PresetSkeletonLinesProps;
 /**
- * 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)

package/src/components/Spacer/Spacer.d.ts

@@ -14,18 +14,25 @@ export interface SpacerProps extends CommonProps, Refable<HTMLDivElement> {
     border?: boolean;
 }
 /**
- * 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.
  *
- * @example basic usage
+ * ### When to use
+ * Use Spacer to add consistent vertical gaps between sections or to render a horizontal divider line.
+ *
+ * ### When not to use
+ * Do not use Spacer for horizontal gaps — use Tailwind flex/grid gap utilities. Do not use for structural layout — use CSS grid or flex.
+ *
+ * @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

package/src/components/Spinner/Spinner.d.ts

@@ -28,16 +28,37 @@ export interface SpinnerProps extends CommonProps, Refable<HTMLDivElement> {
     label?: string;
 }
 /**
- * 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.
  *
- * 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 to use
+ * Use Spinner for short-duration loading states: button actions, table refreshes, inline data fetches, or modal content loading.
  *
- * 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.
+ * ### 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.
  *
- * 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.
+ * @example Centered spinner during data load
+ * ```tsx
+ * import { Spinner } from "@trackunit/react-components";
  *
- * Use when retrieving or refreshing small data amounts, such as status.
- 
+ * const LoadingContent = () => (
+ *   <div className="h-64">
+ *     <Spinner centering="centered" label="Loading assets..." />
+ *   </div>
+ * );
+ * ```
+ * @example Small inline spinner
+ * ```tsx
+ * import { Spinner } from "@trackunit/react-components";
+ *
+ * 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
  */

package/src/components/Tabs/Tab.d.ts

@@ -41,7 +41,34 @@ export interface TabProps extends TabsTriggerProps, Refable<HTMLButtonElement> {
     appendTabStylesToChildIfAsChild?: boolean;
 }
 /**
- * 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
  */
 export declare const Tab: ({ value, isFullWidth, iconName, "data-testid": dataTestId, className, children, suffix, asChild, appendTabStylesToChildIfAsChild, ref, ...rest }: TabProps) => ReactElement;

package/src/components/Tabs/TabContent.d.ts

@@ -3,13 +3,58 @@ import { IconName } from "@trackunit/ui-icons";
 import { ReactElement, ReactNode } from "react";
 import { Refable } from "../../common/Refable";
 export interface TabContentProps extends TabsContentProps, Refable<HTMLDivElement> {
+    /**
+     * A custom class name to be attached to the content wrapper element.
+     */
     className?: string;
+    /**
+     * An ID that can be used in tests to locate the component. A "-content" suffix is appended automatically.
+     */
     "data-testid"?: string;
+    /**
+     * The content to render when this tab panel is active.
+     */
     children?: ReactNode;
+    /**
+     * An optional suffix element, typically a badge or icon, displayed alongside the tab content.
+     */
     suffix?: ReactNode;
+    /**
+     * The name of an icon to associate with this tab content panel.
+     */
     iconName?: IconName;
 }
 /**
- * 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
  */
 export declare const TabContent: ({ className, "data-testid": dataTestId, children, ref, ...rest }: TabContentProps) => ReactElement;

package/src/components/Tabs/TabList.d.ts

@@ -23,6 +23,34 @@ export interface TabListProps extends TabsListProps, Refable<HTMLDivElement> {
     autoScrollToActive?: boolean;
 }
 /**
- * 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
  */
 export declare const TabList: ({ className, "data-testid": dataTestId, children, autoScrollToActive, ref, ...rest }: TabListProps) => ReactElement;

package/src/components/Tabs/Tabs.d.ts

@@ -24,7 +24,18 @@ export interface TabsProps extends TabsRootProps, Refable<HTMLDivElement> {
     "data-testid"?: string;
 }
 /**
- * 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
@@ -58,5 +69,7 @@ export interface TabsProps extends TabsRootProps, Refable<HTMLDivElement> {
  *   </Tabs>
  * );
  * ```
+ * @param {TabsProps} props - The props for the Tabs component
+ * @returns {ReactElement} Tabs component
  */
 export declare const Tabs: ({ children, forceRender, className, "data-testid": dataTestId, fullWidth, ref, ...rest }: TabsProps) => ReactElement;