@trackunit/react-table-base-components 1.10.17 → 1.10.19

package/src/components/DateTimeCell/DateTimeCell.d.ts

@@ -31,8 +31,58 @@ export interface DateTimeCellProps extends CommonProps {
     locale?: string;
 }
 /**
- * DateTimeCell is used for render a date and or time in a table cell.
+ * The `<DateTimeCell>` component renders a formatted date/time in a table cell.
+ * It displays the formatted date with an optional "time since" indicator
+ * (e.g., "2 hours ago") on a second line for quick context.
  *
+ * ### When to use
+ * - Display timestamps, created/updated dates in tables
+ * - When users need to quickly understand how recent an event was
+ * - For date columns that benefit from relative time context
+ *
+ * ### When not to use
+ * - For date-only display without time - use `PlainDateCell` instead
+ * - For duration values - use `NumberCell` with appropriate units
+ * - For editable date inputs - use form components instead
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { DateTimeCell } from "@trackunit/react-table-base-components";
+ * import { createColumnHelper } from "@tanstack/react-table";
+ *
+ * const columnHelper = createColumnHelper<Event>();
+ *
+ * const columns = [
+ *   columnHelper.accessor("createdAt", {
+ *     header: "Created",
+ *     cell: ({ getValue }) => <DateTimeCell date={getValue()} />,
+ *   }),
+ * ];
+ * ```
+ * @example With timezone and format options
+ * ```tsx
+ * import { DateTimeCell } from "@trackunit/react-table-base-components";
+ *
+ * // Default format with time since
+ * <DateTimeCell date={new Date("2024-01-15T14:30:00Z")} />
+ * // Output: "Jan 15, 2024, 2:30 PM" + "3 days ago"
+ *
+ * // Without time since indicator
+ * <DateTimeCell date={new Date()} withTimeSince={false} />
+ *
+ * // With specific timezone
+ * <DateTimeCell
+ *   date={new Date()}
+ *   timeZone="America/New_York"
+ *   locale="en-US"
+ * />
+ *
+ * // Custom format
+ * <DateTimeCell
+ *   date={new Date()}
+ *   format="dateTime"
+ * />
+ * ```
  * @param {DateTimeCellProps} props - The props for the DateTimeCell component
  * @returns {ReactElement} DateTimeCell component
  */

package/src/components/IdentityCell/IdentityCell.d.ts

@@ -18,12 +18,75 @@ export interface IdentityCellProps extends CommonProps {
     };
 }
 /**
- * The IdentityCell is used for render an identity in a table cell.
+ * The `<IdentityCell>` component renders an identity or entity in a table cell,
+ * typically showing a title with optional thumbnail and supporting details.
+ * Commonly used for displaying assets, users, or other entities with rich metadata.
  *
  * When displaying asset information, always use the `type` field
  * (e.g., "excavator", "boom lift") instead of `assetType` (e.g., "machine", "attachment").
  *
- * @param {IdentityCellProps} props - The props for the LinkCell component
- * @returns {ReactElement} LinkCell component
+ * ### When to use
+ * - Display entities with name + additional identifying details (model, serial number, etc.)
+ * - When a thumbnail/avatar helps users identify the item
+ * - For the primary identifying column in asset, user, or entity tables
+ *
+ * ### When not to use
+ * - For simple text values - use `TextCell` instead
+ * - For numeric data - use `NumberCell` instead
+ * - For standalone links without identity context - use `LinkCell` instead
+ *
+ * @example Basic usage with asset data
+ * ```tsx
+ * import { IdentityCell } from "@trackunit/react-table-base-components";
+ * import { createColumnHelper } from "@tanstack/react-table";
+ *
+ * const columnHelper = createColumnHelper<Asset>();
+ *
+ * const columns = [
+ *   columnHelper.accessor("name", {
+ *     header: "Asset",
+ *     cell: ({ row }) => (
+ *       <IdentityCell
+ *         title={row.original.name}
+ *         details={[row.original.type, row.original.serialNumber]}
+ *       />
+ *     ),
+ *   }),
+ * ];
+ * ```
+ * @example With thumbnail and link
+ * ```tsx
+ * import { IdentityCell } from "@trackunit/react-table-base-components";
+ * import { AssetImage } from "@trackunit/react-components";
+ * import { useIrisRouting } from "@trackunit/react-core-contexts-and-hooks";
+ *
+ * const { createHref, goto } = useIrisRouting();
+ *
+ * <IdentityCell
+ *   title="Excavator CAT 320"
+ *   details={["Caterpillar", "SN: ABC123456"]}
+ *   thumbnail={<AssetImage assetId={assetId} size="small" />}
+ *   link={{
+ *     href: () => createHref({ page: "asset", assetId }),
+ *     goto: () => goto({ page: "asset", assetId }),
+ *     title: "View asset details",
+ *   }}
+ * />
+ * ```
+ * @example Simple identity without extras
+ * ```tsx
+ * import { IdentityCell } from "@trackunit/react-table-base-components";
+ *
+ * // Just title
+ * <IdentityCell title="John Smith" />
+ *
+ * // Title with details array
+ * <IdentityCell
+ *   title="Boom Lift JLG 600S"
+ *   details={["JLG Industries", "Serial: XYZ789"]}
+ * />
+ * ```
+ * @param {IdentityCellProps} props - The props for the IdentityCell component
+ * @returns {ReactElement} IdentityCell component
  */
 export declare const IdentityCell: ({ link, className, "data-testid": dataTestId, title, details, thumbnail, }: IdentityCellProps) => ReactElement;

package/src/components/LinkCell/LinkCell.d.ts

@@ -19,8 +19,61 @@ export interface LinkCellProps extends CommonProps, HTMLAttributes<HTMLTableSect
     link: string;
 }
 /**
- * The LinkCell is used for render a list of tags in a table cell
+ * The `<LinkCell>` component renders a clickable link in a table cell.
+ * Supports URLs, phone numbers (tel:), and email addresses (mailto:).
+ * Clicking the link opens it without triggering the table row click handler.
  *
+ * ### When to use
+ * - Display clickable URLs, emails, or phone numbers in table columns
+ * - When users need to contact someone or visit an external link from table data
+ * - For contact information columns (email, phone)
+ *
+ * ### When not to use
+ * - For internal navigation - use `IdentityCell` with link prop instead
+ * - For action buttons - use `ButtonCell` or `RowActions` instead
+ * - For non-interactive text - use `TextCell` instead
+ *
+ * @example Basic usage with different link types
+ * ```tsx
+ * import { LinkCell } from "@trackunit/react-table-base-components";
+ * import { createColumnHelper } from "@tanstack/react-table";
+ *
+ * const columnHelper = createColumnHelper<Contact>();
+ *
+ * const columns = [
+ *   columnHelper.accessor("email", {
+ *     header: "Email",
+ *     cell: ({ getValue }) => (
+ *       <LinkCell type="EMAIL" link={getValue()} />
+ *     ),
+ *   }),
+ *   columnHelper.accessor("phone", {
+ *     header: "Phone",
+ *     cell: ({ getValue }) => (
+ *       <LinkCell type="PHONE" link={getValue()} />
+ *     ),
+ *   }),
+ *   columnHelper.accessor("website", {
+ *     header: "Website",
+ *     cell: ({ getValue }) => (
+ *       <LinkCell type="LINK" link={getValue()} />
+ *     ),
+ *   }),
+ * ];
+ * ```
+ * @example Link type examples
+ * ```tsx
+ * import { LinkCell } from "@trackunit/react-table-base-components";
+ *
+ * // Email - opens mail client
+ * <LinkCell type="EMAIL" link="contact@example.com" />
+ *
+ * // Phone - opens phone dialer
+ * <LinkCell type="PHONE" link="+1-555-123-4567" />
+ *
+ * // URL - opens in browser
+ * <LinkCell type="LINK" link="https://example.com" />
+ * ```
  * @param {LinkCellProps} props - The props for the LinkCell component
  * @returns {ReactElement} LinkCell component
  */

package/src/components/NumberCell/NumberCell.d.ts

@@ -19,8 +19,49 @@ export interface NumberCellProps extends CommonProps {
     "data-testid"?: string;
 }
 /**
- * The `<NumberCell>` component is used for displaying numbers with units in a table cell.
+ * The `<NumberCell>` component is used for displaying numbers with optional units in a table cell.
+ * Numbers are right-aligned by default for easy scanning and comparison in data tables.
  *
+ * ### When to use
+ * - Display numeric values like quantities, measurements, or counts
+ * - When values need to be accompanied by units (km, hours, %, etc.)
+ * - For right-aligned numeric columns in data tables
+ *
+ * ### When not to use
+ * - For non-numeric text content - use `TextCell` instead
+ * - For dates and times - use `DateTimeCell` instead
+ * - For formatted currency - consider specialized formatting
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { NumberCell } from "@trackunit/react-table-base-components";
+ * import { createColumnHelper } from "@tanstack/react-table";
+ *
+ * const columnHelper = createColumnHelper<Asset>();
+ *
+ * const columns = [
+ *   columnHelper.accessor("engineHours", {
+ *     header: "Engine Hours",
+ *     cell: ({ getValue }) => <NumberCell value={getValue()} unit="h" />,
+ *   }),
+ * ];
+ * ```
+ * @example Different unit types
+ * ```tsx
+ * import { NumberCell } from "@trackunit/react-table-base-components";
+ *
+ * // Distance
+ * <NumberCell value={1250} unit="km" />
+ *
+ * // Percentage
+ * <NumberCell value={85} unit="%" />
+ *
+ * // Temperature
+ * <NumberCell value={23.5} unit="°C" />
+ *
+ * // Without unit
+ * <NumberCell value={42} />
+ * ```
  * @param {NumberCellProps} props - The props for the NumberCell component.
  * @returns {ReactElement} A React JSX element representing the NumberCell component.
  */

package/src/components/RowActions/RowActions.d.ts

@@ -1,27 +1,138 @@
 import { MenuItemVariant } from "@trackunit/react-components";
 import { IconName } from "@trackunit/ui-icons";
 export type Action = {
+    /** The display text for the action button or menu item */
     label: string;
+    /** Visual variant of the action, use "danger" for destructive actions */
     variant?: MenuItemVariant;
+    /** Callback function triggered when the action is clicked */
     onClick: () => void;
+    /** Optional icon to display alongside the action label */
     iconName?: IconName;
+    /** When true, the action is shown as an icon button outside the dropdown menu */
     isSelected?: boolean;
+    /** When true, the action is visually disabled and cannot be clicked */
     disabled?: boolean;
+    /** When true, shows a spinner instead of the icon to indicate processing */
     loading?: boolean;
+    /** Controls visibility of the action. Defaults to true if not specified */
     isVisible?: boolean | null;
 };
 export interface RowActionsProps {
+    /**
+     * Array of actions to display. Single actions render as a button,
+     * multiple actions render as a dropdown menu with selected actions as icon buttons.
+     */
     actions: Array<Action>;
 }
 /**
- * RowActions component displays actions as individual buttons or a dropdown menu
- * based on the number of actions provided.
+ * The `<RowActions>` component displays contextual actions for a table row.
+ * Automatically adapts its rendering based on the number of actions:
+ * - Single action: renders as a standalone button
+ * - Multiple actions: renders selected actions as icon buttons + overflow menu
  *
- * - If there is a single action, it displays a standalone button.
- * - If there are multiple actions, they are grouped into a dropdown menu.
+ * Actions can be marked as `isSelected` to display them as quick-access icon buttons
+ * outside the dropdown menu. Danger actions are automatically separated with a divider.
  *
+ * ### When to use
+ * - Provide row-level actions like Edit, Delete, Download, etc.
+ * - When rows need multiple contextual actions
+ * - For consistent action patterns across data tables
+ *
+ * ### When not to use
+ * - For bulk actions on selected rows - use `ActionSheet` instead
+ * - For a single simple action - consider `ButtonCell` for simpler UI
+ * - For navigation - use `IdentityCell` with link prop
+ *
+ * @example Basic usage with multiple actions
+ * ```tsx
+ * import { RowActions } from "@trackunit/react-table-base-components";
+ * import { createColumnHelper } from "@tanstack/react-table";
+ *
+ * const columnHelper = createColumnHelper<Asset>();
+ *
+ * const columns = [
+ *   columnHelper.display({
+ *     id: "actions",
+ *     header: "",
+ *     cell: ({ row }) => (
+ *       <RowActions
+ *         actions={[
+ *           {
+ *             label: "Edit",
+ *             iconName: "PencilSquare",
+ *             onClick: () => handleEdit(row.original.id),
+ *           },
+ *           {
+ *             label: "Download",
+ *             iconName: "ArrowDownTray",
+ *             onClick: () => handleDownload(row.original.id),
+ *           },
+ *           {
+ *             label: "Delete",
+ *             iconName: "Trash",
+ *             variant: "danger",
+ *             onClick: () => handleDelete(row.original.id),
+ *           },
+ *         ]}
+ *       />
+ *     ),
+ *   }),
+ * ];
+ * ```
+ * @example With selected (pinned) actions
+ * ```tsx
+ * import { RowActions } from "@trackunit/react-table-base-components";
+ *
+ * <RowActions
+ *   actions={[
+ *     {
+ *       label: "Edit",
+ *       iconName: "PencilSquare",
+ *       isSelected: true, // Shows as icon button outside menu
+ *       onClick: () => handleEdit(id),
+ *     },
+ *     {
+ *       label: "Duplicate",
+ *       iconName: "DocumentDuplicate",
+ *       onClick: () => handleDuplicate(id),
+ *     },
+ *     {
+ *       label: "Delete",
+ *       iconName: "Trash",
+ *       variant: "danger",
+ *       onClick: () => handleDelete(id),
+ *     },
+ *   ]}
+ * />
+ * ```
+ * @example With loading and disabled states
+ * ```tsx
+ * import { RowActions } from "@trackunit/react-table-base-components";
+ *
+ * <RowActions
+ *   actions={[
+ *     {
+ *       label: "Processing...",
+ *       iconName: "ArrowPath",
+ *       loading: true,
+ *       onClick: () => {},
+ *     },
+ *     {
+ *       label: "Unavailable",
+ *       iconName: "NoSymbol",
+ *       disabled: true,
+ *       onClick: () => {},
+ *     },
+ *     {
+ *       label: "Hidden Action",
+ *       isVisible: false, // Will not be rendered
+ *       onClick: () => {},
+ *     },
+ *   ]}
+ * />
+ * ```
  * @param {RowActionsProps} props - The properties for the component.
- * @param {Action[]} props.actions - A list of actions to display, including their labels, icons, and handlers.
- * @returns {Element} A React component rendering the actions.
+ * @returns {ReactElement} A React component rendering the row actions.
  */
 export declare const RowActions: ({ actions }: RowActionsProps) => false | import("react/jsx-runtime").JSX.Element | null | undefined;

package/src/components/TagsCell/TagsCell.d.ts

@@ -15,8 +15,49 @@ export interface TagsCellProps extends CommonProps, HTMLAttributes<HTMLTableSect
     tags: Array<string> | Array<TagProps>;
 }
 /**
- * The TagsCell is used for render a list of tags in a table cell
+ * The `<TagsCell>` component renders a list of tags in a table cell.
+ * Useful for displaying categories, labels, or status indicators in a compact format.
  *
+ * ### When to use
+ * - Display multiple tags, categories, or labels for an entity
+ * - Show groupings, classifications, or metadata as visual tags
+ * - When items have multiple attributes that should be shown together
+ *
+ * ### When not to use
+ * - For a single status indicator - use `Tag` component directly or `IndicatorCell`
+ * - For text content - use `TextCell` instead
+ * - For interactive chip selection - use form components instead
+ *
+ * @example Basic usage with string array
+ * ```tsx
+ * import { TagsCell } from "@trackunit/react-table-base-components";
+ * import { createColumnHelper } from "@tanstack/react-table";
+ *
+ * const columnHelper = createColumnHelper<Asset>();
+ *
+ * const columns = [
+ *   columnHelper.accessor("tags", {
+ *     header: "Tags",
+ *     cell: ({ getValue }) => <TagsCell tags={getValue()} />,
+ *   }),
+ * ];
+ * ```
+ * @example With custom tag props
+ * ```tsx
+ * import { TagsCell } from "@trackunit/react-table-base-components";
+ *
+ * // Simple string tags
+ * <TagsCell tags={["Active", "Premium", "Verified"]} />
+ *
+ * // Tags with custom styling using TagProps
+ * <TagsCell
+ *   tags={[
+ *     { children: "Active", color: "success" },
+ *     { children: "Warning", color: "warning" },
+ *     { children: "Inactive", color: "neutral" },
+ *   ]}
+ * />
+ * ```
  * @param {TagsCellProps} props - The props for the TagsCell component
  * @returns {ReactElement} TagsCell component
  */

package/src/components/TextCell/TextCell.d.ts

@@ -1,12 +1,53 @@
 import { CommonProps } from "@trackunit/react-components";
 import { ReactElement } from "react";
 export interface TextCellProps extends CommonProps {
+    /**
+     * The text or React element to display in the cell.
+     * When text overflows the cell width, it will be truncated with an ellipsis
+     * and a tooltip will appear on hover showing the full content.
+     */
     content?: string | ReactElement;
 }
 /**
  * The `<TextCell>` component is used for displaying text in a table cell.
- * The text is not editable and will be truncated if the cell is too narrow.
+ * The text is not editable and will be truncated with an ellipsis if the cell is too narrow.
+ * When truncated, a tooltip automatically appears on hover showing the full content.
  *
+ * ### When to use
+ * - Display simple text values in table columns (names, descriptions, statuses)
+ * - When text content might be longer than the column width
+ * - For read-only text display in data grids
+ *
+ * ### When not to use
+ * - For numeric values - use `NumberCell` instead
+ * - For dates and times - use `DateTimeCell` instead
+ * - For clickable links - use `LinkCell` or `ButtonCell` instead
+ * - For multi-line content - consider `IdentityCell` with details
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { TextCell } from "@trackunit/react-table-base-components";
+ * import { createColumnHelper } from "@tanstack/react-table";
+ *
+ * const columnHelper = createColumnHelper<Asset>();
+ *
+ * const columns = [
+ *   columnHelper.accessor("name", {
+ *     header: "Name",
+ *     cell: ({ getValue }) => <TextCell content={getValue()} />,
+ *   }),
+ * ];
+ * ```
+ * @example With custom content
+ * ```tsx
+ * import { TextCell } from "@trackunit/react-table-base-components";
+ *
+ * // Text content - will show tooltip if truncated
+ * <TextCell content="This is a long description that might get truncated" />
+ *
+ * // ReactElement content
+ * <TextCell content={<span className="font-bold">Bold text</span>} />
+ * ```
  * @param {TextCellProps} props - The props for the TextCell component
  * @returns {ReactElement} TextCell component
  */