@trackunit/react-table-base-components 1.13.25 → 1.13.27

package/index.cjs.js

@@ -89,9 +89,21 @@ const ButtonCell = ({ children, className, "data-testid": dataTestId, iconColor
 const cvaCheckboxCell = cssClassVarianceUtilities.cvaMerge([""]);
 
 /**
- * CheckboxCell is used for render a checkbox in a table cell-
- * The checkbox is not editable.
+ * CheckboxCell renders a read-only checkbox inside a table cell. The checkbox reflects a boolean value
+ * but cannot be toggled by the user — it is purely for display purposes.
  *
+ * ### When to use
+ * Use CheckboxCell to display a boolean field (e.g., active/inactive, enabled/disabled) as a visual checkbox in a table column.
+ *
+ * ### When not to use
+ * Do not use CheckboxCell for row selection — use `useTableSelection` which provides an interactive selection column.
+ *
+ * @example Boolean status in a table column
+ * ```tsx
+ * import { CheckboxCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = ({ row }) => <CheckboxCell checked={row.original.isActive} />;
+ * ```
  * @param {CheckboxCellProps} props - The props for the CheckboxCell component
  * @returns {ReactElement} CheckboxCell component
  */
@@ -181,8 +193,27 @@ const TimeSince = ({ date, timeZone, locale }) => {
 const cvaHighlightCell = cssClassVarianceUtilities.cvaMerge(["flex", "gap-2"]);
 
 /**
- * The HighlightCell is used for rendering a list of highlights in a table cell
+ * HighlightCell renders one or more colored highlight badges inside a table cell. Each highlight
+ * can be a simple string (displayed with the default warning color) or an object with a custom color.
+ * It is used to draw attention to out-of-range or notable values in a table row.
  *
+ * ### When to use
+ * Use HighlightCell to display threshold warnings, status flags, or tagged values inside a table column.
+ *
+ * ### When not to use
+ * Do not use HighlightCell for general status indicators — use `IndicatorCell`.
+ *
+ * @example Highlight cell with warning values
+ * ```tsx
+ * import { HighlightCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = ({ row }) => (
+ *   <HighlightCell highlights={[
+ *     { color: "danger", children: "High Temp" },
+ *     { color: "warning", children: "Low Battery" },
+ *   ]} />
+ * );
+ * ```
  * @param {HighlightCellProps} props - The props for the HighlightCell component
  * @returns {ReactElement} HighlightCell component
  */
@@ -296,20 +327,56 @@ const IdentityCell = ({ link, className, "data-testid": dataTestId, ref, title,
 };
 
 /**
- * The `<ImageCell>` component is used for displaying images in a table cell.
+ * ImageCell renders a thumbnail image inside a table cell with configurable width, height, and alt text.
+ * It is used to display asset photos, user avatars, or product images alongside other table data.
+ *
+ * ### When to use
+ * Use ImageCell when a table column needs to display a thumbnail or image preview.
+ *
+ * ### When not to use
+ * Do not use ImageCell for icons or status indicators — use `IndicatorCell`.
  *
- * @param {ImageCellProps} props - The props for the Image component.
- * @returns {ReactElement} The Image component.
+ * @example Asset image in a table column
+ * ```tsx
+ * import { ImageCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = ({ row }) => (
+ *   <ImageCell imageUrl={row.original.imageUrl} alt={row.original.name} width={60} height={60} />
+ * );
+ * ```
+ * @param {ImageCellProps} props - The props for the ImageCell component
+ * @returns {ReactElement} ImageCell component
  */
 const ImageCell = ({ imageUrl, alt = "", width = 100, height = 100, "data-testid": dataTestId, ref, ...rest }) => {
     return jsxRuntime.jsx("img", { alt: alt, "data-testid": dataTestId, height: height, ref: ref, src: imageUrl, width: width, ...rest });
 };
 
 /**
- * The IndicatorCell is used for render an indicator in a table cell
+ * IndicatorCell renders a colored icon indicator with an optional text label inside a table cell.
+ * It wraps the Indicator component and supports background highlighting, a pinging animation for urgency,
+ * and hiding the label to show it on hover instead.
  *
- * @param {IndicatorCellProps} props - The props for the LinkCell component
- * @returns {ReactElement} LinkCell component
+ * ### When to use
+ * Use IndicatorCell to display status indicators in a table — for example, online/offline status, health state, or connectivity.
+ *
+ * ### When not to use
+ * Do not use IndicatorCell for text-based status labels — use `TextCell` or `NoticeCell`.
+ *
+ * @example Status indicator in a table column
+ * ```tsx
+ * import { IndicatorCell } from "@trackunit/react-table-base-components";
+ * import { Icon } from "@trackunit/react-components";
+ *
+ * const cell = ({ row }) => (
+ *   <IndicatorCell
+ *     icon={<Icon name="CheckCircle" size="small" />}
+ *     color="success"
+ *     label="Online"
+ *   />
+ * );
+ * ```
+ * @param {IndicatorCellProps} props - The props for the IndicatorCell component
+ * @returns {ReactElement} IndicatorCell component
  */
 const IndicatorCell = ({ withBackground = false, weight = "normal", ref, ...rest }) => {
     return jsxRuntime.jsx(reactComponents.Indicator, { ref: ref, weight: weight, withBackground: withBackground, ...rest });
@@ -390,8 +457,24 @@ const cvaMainRowText = cssClassVarianceUtilities.cvaMerge(["overflow-hidden", "t
 const cvaSecondaryRowText = cssClassVarianceUtilities.cvaMerge(["overflow-hidden", "text-ellipsis", "text-neutral-500", "text-xs"]);
 
 /**
- * The MultiRowTableCell component helps to display two rows inside a table cell.
+ * MultiRowTableCell renders two stacked rows inside a single table cell — a primary `main` row
+ * and a secondary row below it. String values are automatically styled with appropriate text sizes.
+ *
+ * ### When to use
+ * Use MultiRowTableCell when a table cell needs to display a primary value with secondary metadata below —
+ * for example, an asset name with its serial number, or a user name with their email.
+ *
+ * ### When not to use
+ * Do not use MultiRowTableCell for single-line text — use `TextCell`.
  *
+ * @example Name with description in a table cell
+ * ```tsx
+ * import { MultiRowTableCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = ({ row }) => (
+ *   <MultiRowTableCell main={row.original.name} secondary={row.original.serialNumber} />
+ * );
+ * ```
  * @param {MultiRowTableCellProps} props - The props for the MultiRowTableCell component
  * @returns {ReactElement} MultiRowTableCell component
  */
@@ -468,8 +551,22 @@ const MultiValueTextCell = ({ content, count, countTooltip, icon, iconTooltip, "
 };
 
 /**
- * The NoticeCell is used for rendering a Notice in a table cell
+ * NoticeCell renders a Notice component inside a table cell, displaying an inline colored message
+ * (info, warning, success, danger). It accepts the same props as Notice.
+ *
+ * ### When to use
+ * Use NoticeCell to display contextual messages or status banners within a table row —
+ * for example, a warning about an expired certificate or an info notice about a pending update.
+ *
+ * ### When not to use
+ * Do not use NoticeCell for simple colored text — use `HighlightCell`.
  *
+ * @example Warning notice in a table cell
+ * ```tsx
+ * import { NoticeCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = () => <NoticeCell color="warning">Certificate expires soon</NoticeCell>;
+ * ```
  * @param {NoticeCellProps} props - The props for the NoticeCell component
  * @returns {ReactElement} NoticeCell component
  */
@@ -535,8 +632,26 @@ const cvaDateTime = cssClassVarianceUtilities.cvaMerge(["slashed-zero", "text-sm
 const cvaDateTimeSince = cssClassVarianceUtilities.cvaMerge(["slashed-zero", "text-neutral-500", "text-xs", "text-ellipsis"]);
 
 /**
- * PlainDateCell is used for render a date and or time in a table cell.
+ * PlainDateCell renders a `Temporal.PlainDate` inside a table cell as a formatted date string.
+ * By default it also shows the number of days since the date on a second line (e.g., "15 days ago").
+ * Returns `null` when no date is provided.
+ *
+ * ### When to use
+ * Use PlainDateCell for date columns in tables where you work with `Temporal.PlainDate` values —
+ * for example, "Last Service Date" or "Created On" columns.
+ *
+ * ### When not to use
+ * Do not use PlainDateCell for `Date` objects or ISO strings — use the `DateTime` component instead.
  *
+ * @example Date column with days-since indicator
+ * ```tsx
+ * import { PlainDateCell } from "@trackunit/react-table-base-components";
+ * import { Temporal } from "@js-temporal/polyfill";
+ *
+ * const cell = ({ row }) => (
+ *   <PlainDateCell date={Temporal.PlainDate.from(row.original.lastServiceDate)} />
+ * );
+ * ```
  * @param {PlainDateCellProps} props - The props for the PlainDateCell component
  * @returns {ReactElement} PlainDateCell component
  */
@@ -754,18 +869,32 @@ const IconWithLoader = ({ action, size }) => {
 };
 
 /**
- * The SortIndicator is used in the table header to indicate the current sort order of the column.
- * This is a visual only component and does not handle the sorting logic.
+ * SortIndicator renders ascending/descending arrow indicators in a table column header.
+ * It is a visual-only component — it does not handle sorting logic. Set `sortingState` to
+ * `"asc"`, `"desc"`, or `false` (hidden).
  *
- * In most cases, we recommend using the Table Component which already handles sorting indication.
- * However, if you need to construct a custom table, the Table Base Components can be utilized.
+ * In most cases, use the Table component which handles sort indication automatically.
+ * Use SortIndicator directly only when building custom table headers with the Table Base Components.
  *
- * @param {object} props - Props for the sorting indicator.
- * @param {boolean} [props.sortingState=false] - Indicates the sorting state (ascending/descending).
- * @param {string} [props."data-testid"] - A data-testid attribute for testing purposes.
- * @param {string} [props.className] - Additional CSS classes to apply to the sorting indicator.
- * @param {import('react').Ref<HTMLDivElement>} [props.ref] - Ref forwarded to the root DOM element.
- * @returns {ReactElement} A React element representing the sorting indicator.
+ * ### When to use
+ * Use SortIndicator in custom table header cells that need to show the current sort direction.
+ *
+ * ### When not to use
+ * Do not use SortIndicator when using the `Table` component — sorting indicators are built in.
+ *
+ * @example Sort indicator in a custom header
+ * ```tsx
+ * import { SortIndicator } from "@trackunit/react-table-base-components";
+ *
+ * const CustomHeader = ({ sortDirection }: { sortDirection: "asc" | "desc" | false }) => (
+ *   <div className="flex items-center gap-1">
+ *     <span>Column Name</span>
+ *     <SortIndicator sortingState={sortDirection} />
+ *   </div>
+ * );
+ * ```
+ * @param {SortIndicatorProps} props - The props for the SortIndicator component
+ * @returns {ReactElement} SortIndicator component
  */
 const SortIndicator = ({ sortingState = false, "data-testid": dataTestId, className, ref, ...rest }) => {
     return (jsxRuntime.jsx("div", { className: cvaSortIndicator({ sortingState, className }), "data-testid": dataTestId, ref: ref, role: "separator", ...rest }));

package/index.esm.js

@@ -87,9 +87,21 @@ const ButtonCell = ({ children, className, "data-testid": dataTestId, iconColor
 const cvaCheckboxCell = cvaMerge([""]);
 
 /**
- * CheckboxCell is used for render a checkbox in a table cell-
- * The checkbox is not editable.
+ * CheckboxCell renders a read-only checkbox inside a table cell. The checkbox reflects a boolean value
+ * but cannot be toggled by the user — it is purely for display purposes.
  *
+ * ### When to use
+ * Use CheckboxCell to display a boolean field (e.g., active/inactive, enabled/disabled) as a visual checkbox in a table column.
+ *
+ * ### When not to use
+ * Do not use CheckboxCell for row selection — use `useTableSelection` which provides an interactive selection column.
+ *
+ * @example Boolean status in a table column
+ * ```tsx
+ * import { CheckboxCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = ({ row }) => <CheckboxCell checked={row.original.isActive} />;
+ * ```
  * @param {CheckboxCellProps} props - The props for the CheckboxCell component
  * @returns {ReactElement} CheckboxCell component
  */
@@ -179,8 +191,27 @@ const TimeSince = ({ date, timeZone, locale }) => {
 const cvaHighlightCell = cvaMerge(["flex", "gap-2"]);
 
 /**
- * The HighlightCell is used for rendering a list of highlights in a table cell
+ * HighlightCell renders one or more colored highlight badges inside a table cell. Each highlight
+ * can be a simple string (displayed with the default warning color) or an object with a custom color.
+ * It is used to draw attention to out-of-range or notable values in a table row.
  *
+ * ### When to use
+ * Use HighlightCell to display threshold warnings, status flags, or tagged values inside a table column.
+ *
+ * ### When not to use
+ * Do not use HighlightCell for general status indicators — use `IndicatorCell`.
+ *
+ * @example Highlight cell with warning values
+ * ```tsx
+ * import { HighlightCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = ({ row }) => (
+ *   <HighlightCell highlights={[
+ *     { color: "danger", children: "High Temp" },
+ *     { color: "warning", children: "Low Battery" },
+ *   ]} />
+ * );
+ * ```
  * @param {HighlightCellProps} props - The props for the HighlightCell component
  * @returns {ReactElement} HighlightCell component
  */
@@ -294,20 +325,56 @@ const IdentityCell = ({ link, className, "data-testid": dataTestId, ref, title,
 };
 
 /**
- * The `<ImageCell>` component is used for displaying images in a table cell.
+ * ImageCell renders a thumbnail image inside a table cell with configurable width, height, and alt text.
+ * It is used to display asset photos, user avatars, or product images alongside other table data.
+ *
+ * ### When to use
+ * Use ImageCell when a table column needs to display a thumbnail or image preview.
+ *
+ * ### When not to use
+ * Do not use ImageCell for icons or status indicators — use `IndicatorCell`.
  *
- * @param {ImageCellProps} props - The props for the Image component.
- * @returns {ReactElement} The Image component.
+ * @example Asset image in a table column
+ * ```tsx
+ * import { ImageCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = ({ row }) => (
+ *   <ImageCell imageUrl={row.original.imageUrl} alt={row.original.name} width={60} height={60} />
+ * );
+ * ```
+ * @param {ImageCellProps} props - The props for the ImageCell component
+ * @returns {ReactElement} ImageCell component
  */
 const ImageCell = ({ imageUrl, alt = "", width = 100, height = 100, "data-testid": dataTestId, ref, ...rest }) => {
     return jsx("img", { alt: alt, "data-testid": dataTestId, height: height, ref: ref, src: imageUrl, width: width, ...rest });
 };
 
 /**
- * The IndicatorCell is used for render an indicator in a table cell
+ * IndicatorCell renders a colored icon indicator with an optional text label inside a table cell.
+ * It wraps the Indicator component and supports background highlighting, a pinging animation for urgency,
+ * and hiding the label to show it on hover instead.
  *
- * @param {IndicatorCellProps} props - The props for the LinkCell component
- * @returns {ReactElement} LinkCell component
+ * ### When to use
+ * Use IndicatorCell to display status indicators in a table — for example, online/offline status, health state, or connectivity.
+ *
+ * ### When not to use
+ * Do not use IndicatorCell for text-based status labels — use `TextCell` or `NoticeCell`.
+ *
+ * @example Status indicator in a table column
+ * ```tsx
+ * import { IndicatorCell } from "@trackunit/react-table-base-components";
+ * import { Icon } from "@trackunit/react-components";
+ *
+ * const cell = ({ row }) => (
+ *   <IndicatorCell
+ *     icon={<Icon name="CheckCircle" size="small" />}
+ *     color="success"
+ *     label="Online"
+ *   />
+ * );
+ * ```
+ * @param {IndicatorCellProps} props - The props for the IndicatorCell component
+ * @returns {ReactElement} IndicatorCell component
  */
 const IndicatorCell = ({ withBackground = false, weight = "normal", ref, ...rest }) => {
     return jsx(Indicator, { ref: ref, weight: weight, withBackground: withBackground, ...rest });
@@ -388,8 +455,24 @@ const cvaMainRowText = cvaMerge(["overflow-hidden", "text-ellipsis", "text-sm"])
 const cvaSecondaryRowText = cvaMerge(["overflow-hidden", "text-ellipsis", "text-neutral-500", "text-xs"]);
 
 /**
- * The MultiRowTableCell component helps to display two rows inside a table cell.
+ * MultiRowTableCell renders two stacked rows inside a single table cell — a primary `main` row
+ * and a secondary row below it. String values are automatically styled with appropriate text sizes.
+ *
+ * ### When to use
+ * Use MultiRowTableCell when a table cell needs to display a primary value with secondary metadata below —
+ * for example, an asset name with its serial number, or a user name with their email.
+ *
+ * ### When not to use
+ * Do not use MultiRowTableCell for single-line text — use `TextCell`.
  *
+ * @example Name with description in a table cell
+ * ```tsx
+ * import { MultiRowTableCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = ({ row }) => (
+ *   <MultiRowTableCell main={row.original.name} secondary={row.original.serialNumber} />
+ * );
+ * ```
  * @param {MultiRowTableCellProps} props - The props for the MultiRowTableCell component
  * @returns {ReactElement} MultiRowTableCell component
  */
@@ -466,8 +549,22 @@ const MultiValueTextCell = ({ content, count, countTooltip, icon, iconTooltip, "
 };
 
 /**
- * The NoticeCell is used for rendering a Notice in a table cell
+ * NoticeCell renders a Notice component inside a table cell, displaying an inline colored message
+ * (info, warning, success, danger). It accepts the same props as Notice.
+ *
+ * ### When to use
+ * Use NoticeCell to display contextual messages or status banners within a table row —
+ * for example, a warning about an expired certificate or an info notice about a pending update.
+ *
+ * ### When not to use
+ * Do not use NoticeCell for simple colored text — use `HighlightCell`.
  *
+ * @example Warning notice in a table cell
+ * ```tsx
+ * import { NoticeCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = () => <NoticeCell color="warning">Certificate expires soon</NoticeCell>;
+ * ```
  * @param {NoticeCellProps} props - The props for the NoticeCell component
  * @returns {ReactElement} NoticeCell component
  */
@@ -533,8 +630,26 @@ const cvaDateTime = cvaMerge(["slashed-zero", "text-sm", "text-ellipsis"]);
 const cvaDateTimeSince = cvaMerge(["slashed-zero", "text-neutral-500", "text-xs", "text-ellipsis"]);
 
 /**
- * PlainDateCell is used for render a date and or time in a table cell.
+ * PlainDateCell renders a `Temporal.PlainDate` inside a table cell as a formatted date string.
+ * By default it also shows the number of days since the date on a second line (e.g., "15 days ago").
+ * Returns `null` when no date is provided.
+ *
+ * ### When to use
+ * Use PlainDateCell for date columns in tables where you work with `Temporal.PlainDate` values —
+ * for example, "Last Service Date" or "Created On" columns.
+ *
+ * ### When not to use
+ * Do not use PlainDateCell for `Date` objects or ISO strings — use the `DateTime` component instead.
  *
+ * @example Date column with days-since indicator
+ * ```tsx
+ * import { PlainDateCell } from "@trackunit/react-table-base-components";
+ * import { Temporal } from "@js-temporal/polyfill";
+ *
+ * const cell = ({ row }) => (
+ *   <PlainDateCell date={Temporal.PlainDate.from(row.original.lastServiceDate)} />
+ * );
+ * ```
  * @param {PlainDateCellProps} props - The props for the PlainDateCell component
  * @returns {ReactElement} PlainDateCell component
  */
@@ -752,18 +867,32 @@ const IconWithLoader = ({ action, size }) => {
 };
 
 /**
- * The SortIndicator is used in the table header to indicate the current sort order of the column.
- * This is a visual only component and does not handle the sorting logic.
+ * SortIndicator renders ascending/descending arrow indicators in a table column header.
+ * It is a visual-only component — it does not handle sorting logic. Set `sortingState` to
+ * `"asc"`, `"desc"`, or `false` (hidden).
  *
- * In most cases, we recommend using the Table Component which already handles sorting indication.
- * However, if you need to construct a custom table, the Table Base Components can be utilized.
+ * In most cases, use the Table component which handles sort indication automatically.
+ * Use SortIndicator directly only when building custom table headers with the Table Base Components.
  *
- * @param {object} props - Props for the sorting indicator.
- * @param {boolean} [props.sortingState=false] - Indicates the sorting state (ascending/descending).
- * @param {string} [props."data-testid"] - A data-testid attribute for testing purposes.
- * @param {string} [props.className] - Additional CSS classes to apply to the sorting indicator.
- * @param {import('react').Ref<HTMLDivElement>} [props.ref] - Ref forwarded to the root DOM element.
- * @returns {ReactElement} A React element representing the sorting indicator.
+ * ### When to use
+ * Use SortIndicator in custom table header cells that need to show the current sort direction.
+ *
+ * ### When not to use
+ * Do not use SortIndicator when using the `Table` component — sorting indicators are built in.
+ *
+ * @example Sort indicator in a custom header
+ * ```tsx
+ * import { SortIndicator } from "@trackunit/react-table-base-components";
+ *
+ * const CustomHeader = ({ sortDirection }: { sortDirection: "asc" | "desc" | false }) => (
+ *   <div className="flex items-center gap-1">
+ *     <span>Column Name</span>
+ *     <SortIndicator sortingState={sortDirection} />
+ *   </div>
+ * );
+ * ```
+ * @param {SortIndicatorProps} props - The props for the SortIndicator component
+ * @returns {ReactElement} SortIndicator component
  */
 const SortIndicator = ({ sortingState = false, "data-testid": dataTestId, className, ref, ...rest }) => {
     return (jsx("div", { className: cvaSortIndicator({ sortingState, className }), "data-testid": dataTestId, ref: ref, role: "separator", ...rest }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-table-base-components",
-  "version": "1.13.25",
+  "version": "1.13.27",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -8,9 +8,9 @@
   },
   "dependencies": {
     "react": "19.0.0",
-    "@trackunit/react-components": "1.17.22",
+    "@trackunit/react-components": "1.17.24",
     "@trackunit/ui-icons": "1.11.42",
-    "@trackunit/react-form-components": "1.14.25",
+    "@trackunit/react-form-components": "1.14.27",
     "@trackunit/css-class-variance-utilities": "1.11.43",
     "@trackunit/date-and-time-utils": "1.11.44",
     "@trackunit/shared-utils": "1.13.43",

package/src/components/CheckboxCell/CheckboxCell.d.ts

@@ -3,9 +3,21 @@ export interface CheckboxCellProps extends CommonProps {
     checked: boolean;
 }
 /**
- * CheckboxCell is used for render a checkbox in a table cell-
- * The checkbox is not editable.
+ * CheckboxCell renders a read-only checkbox inside a table cell. The checkbox reflects a boolean value
+ * but cannot be toggled by the user — it is purely for display purposes.
  *
+ * ### When to use
+ * Use CheckboxCell to display a boolean field (e.g., active/inactive, enabled/disabled) as a visual checkbox in a table column.
+ *
+ * ### When not to use
+ * Do not use CheckboxCell for row selection — use `useTableSelection` which provides an interactive selection column.
+ *
+ * @example Boolean status in a table column
+ * ```tsx
+ * import { CheckboxCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = ({ row }) => <CheckboxCell checked={row.original.isActive} />;
+ * ```
  * @param {CheckboxCellProps} props - The props for the CheckboxCell component
  * @returns {ReactElement} CheckboxCell component
  */

package/src/components/HighlightCell/HighlightCell.d.ts

@@ -19,8 +19,27 @@ export interface HighlightCellProps extends CommonProps, HTMLAttributes<HTMLTabl
     }>;
 }
 /**
- * The HighlightCell is used for rendering a list of highlights in a table cell
+ * HighlightCell renders one or more colored highlight badges inside a table cell. Each highlight
+ * can be a simple string (displayed with the default warning color) or an object with a custom color.
+ * It is used to draw attention to out-of-range or notable values in a table row.
  *
+ * ### When to use
+ * Use HighlightCell to display threshold warnings, status flags, or tagged values inside a table column.
+ *
+ * ### When not to use
+ * Do not use HighlightCell for general status indicators — use `IndicatorCell`.
+ *
+ * @example Highlight cell with warning values
+ * ```tsx
+ * import { HighlightCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = ({ row }) => (
+ *   <HighlightCell highlights={[
+ *     { color: "danger", children: "High Temp" },
+ *     { color: "warning", children: "Low Battery" },
+ *   ]} />
+ * );
+ * ```
  * @param {HighlightCellProps} props - The props for the HighlightCell component
  * @returns {ReactElement} HighlightCell component
  */

package/src/components/ImageCell/ImageCell.d.ts

@@ -22,9 +22,24 @@ export interface ImageCellProps extends CommonProps, Refable<HTMLImageElement> {
     "data-testid"?: string;
 }
 /**
- * The `<ImageCell>` component is used for displaying images in a table cell.
+ * ImageCell renders a thumbnail image inside a table cell with configurable width, height, and alt text.
+ * It is used to display asset photos, user avatars, or product images alongside other table data.
  *
- * @param {ImageCellProps} props - The props for the Image component.
- * @returns {ReactElement} The Image component.
+ * ### When to use
+ * Use ImageCell when a table column needs to display a thumbnail or image preview.
+ *
+ * ### When not to use
+ * Do not use ImageCell for icons or status indicators — use `IndicatorCell`.
+ *
+ * @example Asset image in a table column
+ * ```tsx
+ * import { ImageCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = ({ row }) => (
+ *   <ImageCell imageUrl={row.original.imageUrl} alt={row.original.name} width={60} height={60} />
+ * );
+ * ```
+ * @param {ImageCellProps} props - The props for the ImageCell component
+ * @returns {ReactElement} ImageCell component
  */
 export declare const ImageCell: ({ imageUrl, alt, width, height, "data-testid": dataTestId, ref, ...rest }: ImageCellProps) => import("react/jsx-runtime").JSX.Element;

package/src/components/IndicatorCell/IndicatorCell.d.ts

@@ -31,9 +31,30 @@ export interface IndicatorCellProps extends IndicatorProps, HTMLAttributes<HTMLT
     weight?: "normal" | "medium";
 }
 /**
- * The IndicatorCell is used for render an indicator in a table cell
+ * IndicatorCell renders a colored icon indicator with an optional text label inside a table cell.
+ * It wraps the Indicator component and supports background highlighting, a pinging animation for urgency,
+ * and hiding the label to show it on hover instead.
  *
- * @param {IndicatorCellProps} props - The props for the LinkCell component
- * @returns {ReactElement} LinkCell component
+ * ### When to use
+ * Use IndicatorCell to display status indicators in a table — for example, online/offline status, health state, or connectivity.
+ *
+ * ### When not to use
+ * Do not use IndicatorCell for text-based status labels — use `TextCell` or `NoticeCell`.
+ *
+ * @example Status indicator in a table column
+ * ```tsx
+ * import { IndicatorCell } from "@trackunit/react-table-base-components";
+ * import { Icon } from "@trackunit/react-components";
+ *
+ * const cell = ({ row }) => (
+ *   <IndicatorCell
+ *     icon={<Icon name="CheckCircle" size="small" />}
+ *     color="success"
+ *     label="Online"
+ *   />
+ * );
+ * ```
+ * @param {IndicatorCellProps} props - The props for the IndicatorCell component
+ * @returns {ReactElement} IndicatorCell component
  */
 export declare const IndicatorCell: ({ withBackground, weight, ref, ...rest }: IndicatorCellProps) => import("react/jsx-runtime").JSX.Element;

package/src/components/MultiRowTableCell/MultiRowTableCell.d.ts

@@ -11,8 +11,24 @@ export interface MultiRowTableCellProps extends CommonProps {
     secondary: ReactNode;
 }
 /**
- * The MultiRowTableCell component helps to display two rows inside a table cell.
+ * MultiRowTableCell renders two stacked rows inside a single table cell — a primary `main` row
+ * and a secondary row below it. String values are automatically styled with appropriate text sizes.
  *
+ * ### When to use
+ * Use MultiRowTableCell when a table cell needs to display a primary value with secondary metadata below —
+ * for example, an asset name with its serial number, or a user name with their email.
+ *
+ * ### When not to use
+ * Do not use MultiRowTableCell for single-line text — use `TextCell`.
+ *
+ * @example Name with description in a table cell
+ * ```tsx
+ * import { MultiRowTableCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = ({ row }) => (
+ *   <MultiRowTableCell main={row.original.name} secondary={row.original.serialNumber} />
+ * );
+ * ```
  * @param {MultiRowTableCellProps} props - The props for the MultiRowTableCell component
  * @returns {ReactElement} MultiRowTableCell component
  */

package/src/components/NoticeCell/NoticeCell.d.ts

@@ -1,8 +1,22 @@
 import { NoticeProps } from "@trackunit/react-components";
 export type NoticeCellProps = NoticeProps;
 /**
- * The NoticeCell is used for rendering a Notice in a table cell
+ * NoticeCell renders a Notice component inside a table cell, displaying an inline colored message
+ * (info, warning, success, danger). It accepts the same props as Notice.
  *
+ * ### When to use
+ * Use NoticeCell to display contextual messages or status banners within a table row —
+ * for example, a warning about an expired certificate or an info notice about a pending update.
+ *
+ * ### When not to use
+ * Do not use NoticeCell for simple colored text — use `HighlightCell`.
+ *
+ * @example Warning notice in a table cell
+ * ```tsx
+ * import { NoticeCell } from "@trackunit/react-table-base-components";
+ *
+ * const cell = () => <NoticeCell color="warning">Certificate expires soon</NoticeCell>;
+ * ```
  * @param {NoticeCellProps} props - The props for the NoticeCell component
  * @returns {ReactElement} NoticeCell component
  */

package/src/components/PlainDateCell/PlainDateCell.d.ts

@@ -20,8 +20,26 @@ export interface PlainDateCellProps extends CommonProps, Refable<HTMLDivElement>
     locale?: string;
 }
 /**
- * PlainDateCell is used for render a date and or time in a table cell.
+ * PlainDateCell renders a `Temporal.PlainDate` inside a table cell as a formatted date string.
+ * By default it also shows the number of days since the date on a second line (e.g., "15 days ago").
+ * Returns `null` when no date is provided.
  *
+ * ### When to use
+ * Use PlainDateCell for date columns in tables where you work with `Temporal.PlainDate` values —
+ * for example, "Last Service Date" or "Created On" columns.
+ *
+ * ### When not to use
+ * Do not use PlainDateCell for `Date` objects or ISO strings — use the `DateTime` component instead.
+ *
+ * @example Date column with days-since indicator
+ * ```tsx
+ * import { PlainDateCell } from "@trackunit/react-table-base-components";
+ * import { Temporal } from "@js-temporal/polyfill";
+ *
+ * const cell = ({ row }) => (
+ *   <PlainDateCell date={Temporal.PlainDate.from(row.original.lastServiceDate)} />
+ * );
+ * ```
  * @param {PlainDateCellProps} props - The props for the PlainDateCell component
  * @returns {ReactElement} PlainDateCell component
  */

package/src/components/SortIndicator.d.ts

@@ -15,17 +15,31 @@ export interface SortIndicatorProps extends CommonProps, HTMLAttributes<HTMLSpan
     sortingState?: false | "asc" | "desc";
 }
 /**
- * The SortIndicator is used in the table header to indicate the current sort order of the column.
- * This is a visual only component and does not handle the sorting logic.
+ * SortIndicator renders ascending/descending arrow indicators in a table column header.
+ * It is a visual-only component — it does not handle sorting logic. Set `sortingState` to
+ * `"asc"`, `"desc"`, or `false` (hidden).
  *
- * In most cases, we recommend using the Table Component which already handles sorting indication.
- * However, if you need to construct a custom table, the Table Base Components can be utilized.
+ * In most cases, use the Table component which handles sort indication automatically.
+ * Use SortIndicator directly only when building custom table headers with the Table Base Components.
  *
- * @param {object} props - Props for the sorting indicator.
- * @param {boolean} [props.sortingState=false] - Indicates the sorting state (ascending/descending).
- * @param {string} [props."data-testid"] - A data-testid attribute for testing purposes.
- * @param {string} [props.className] - Additional CSS classes to apply to the sorting indicator.
- * @param {import('react').Ref<HTMLDivElement>} [props.ref] - Ref forwarded to the root DOM element.
- * @returns {ReactElement} A React element representing the sorting indicator.
+ * ### When to use
+ * Use SortIndicator in custom table header cells that need to show the current sort direction.
+ *
+ * ### When not to use
+ * Do not use SortIndicator when using the `Table` component — sorting indicators are built in.
+ *
+ * @example Sort indicator in a custom header
+ * ```tsx
+ * import { SortIndicator } from "@trackunit/react-table-base-components";
+ *
+ * const CustomHeader = ({ sortDirection }: { sortDirection: "asc" | "desc" | false }) => (
+ *   <div className="flex items-center gap-1">
+ *     <span>Column Name</span>
+ *     <SortIndicator sortingState={sortDirection} />
+ *   </div>
+ * );
+ * ```
+ * @param {SortIndicatorProps} props - The props for the SortIndicator component
+ * @returns {ReactElement} SortIndicator component
  */
 export declare const SortIndicator: ({ sortingState, "data-testid": dataTestId, className, ref, ...rest }: SortIndicatorProps) => ReactElement;