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

package/index.cjs.js

@@ -11,8 +11,74 @@ var polyfill = require('@js-temporal/polyfill');
 var sharedUtils = require('@trackunit/shared-utils');
 
 /**
- * The ButtonCell is used to display interactive data in table columns.
+ * The `<ButtonCell>` component renders an interactive button within a table cell.
+ * Uses a ghost-neutral variant by default for subtle inline actions.
+ * Commonly used for quick actions on individual rows without opening a menu.
  *
+ * ### When to use
+ * - Provide a single quick action directly in a table cell
+ * - When the action is contextual and specific to that row's data
+ * - For inline edit, view details, or quick status change actions
+ *
+ * ### When not to use
+ * - For multiple actions per row - use `RowActions` instead
+ * - For primary page-level actions - use regular `Button` component
+ * - For navigation links - use `LinkCell` or `IdentityCell` with link prop
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { ButtonCell } from "@trackunit/react-table-base-components";
+ * import { createColumnHelper } from "@tanstack/react-table";
+ *
+ * const columnHelper = createColumnHelper<Asset>();
+ *
+ * const columns = [
+ *   columnHelper.display({
+ *     id: "action",
+ *     header: "Action",
+ *     cell: ({ row }) => (
+ *       <ButtonCell onClick={() => handleView(row.original.id)}>
+ *         View Details
+ *       </ButtonCell>
+ *     ),
+ *   }),
+ * ];
+ * ```
+ * @example With icon
+ * ```tsx
+ * import { ButtonCell } from "@trackunit/react-table-base-components";
+ *
+ * // Edit action with icon
+ * <ButtonCell
+ *   iconName="PencilSquare"
+ *   onClick={() => handleEdit(assetId)}
+ * >
+ *   Edit
+ * </ButtonCell>
+ *
+ * // Download action
+ * <ButtonCell
+ *   iconName="ArrowDownTray"
+ *   iconColor="primary"
+ *   onClick={() => handleDownload(reportId)}
+ * >
+ *   Download
+ * </ButtonCell>
+ * ```
+ * @example Different button states
+ * ```tsx
+ * import { ButtonCell } from "@trackunit/react-table-base-components";
+ *
+ * // Disabled state
+ * <ButtonCell disabled onClick={() => {}}>
+ *   Unavailable
+ * </ButtonCell>
+ *
+ * // Loading state
+ * <ButtonCell loading onClick={() => {}}>
+ *   Processing
+ * </ButtonCell>
+ * ```
  * @param {ButtonCellProps} props - The props for the ButtonCell component
  * @returns {ReactElement} ButtonCell component
  */
@@ -38,8 +104,58 @@ const cvaDateTime$1 = cssClassVarianceUtilities.cvaMerge(["slashed-zero", "text-
 const cvaDateTimeSince$1 = cssClassVarianceUtilities.cvaMerge(["slashed-zero", "text-neutral-500", "text-xs", "text-ellipsis"]);
 
 /**
- * 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
  */
@@ -87,13 +203,76 @@ const cvaIdentityCell = cssClassVarianceUtilities.cvaMerge(["grid", "items-cente
 });
 
 /**
- * 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
  */
 const IdentityCell = ({ link, className, "data-testid": dataTestId, title, details = [], thumbnail, }) => {
     const [href, setHref] = react.useState(undefined);
@@ -139,8 +318,61 @@ const IndicatorCell = ({ withBackground = false, weight = "normal", ...rest }) =
 const cvaLinkCell = cssClassVarianceUtilities.cvaMerge(["text-sm"]);
 
 /**
- * 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
  */
@@ -248,8 +480,49 @@ const NoticeCell = ({ ...rest }) => {
 const cvaNumberCell = cssClassVarianceUtilities.cvaMerge(["flex", "gap-1", "slashed-zero", "text-sm", "text-ellipsis"]);
 
 /**
- * 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.
  */
@@ -335,15 +608,114 @@ const cvaResizeHandel = cssClassVarianceUtilities.cvaMerge([
 });
 
 /**
- * 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
+ *
+ * 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";
  *
- * - If there is a single action, it displays a standalone button.
- * - If there are multiple actions, they are grouped into a dropdown menu.
+ * 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.
  */
 const RowActions = ({ actions }) => {
     const selectedActions = actions.filter(action => action.isSelected);
@@ -446,8 +818,49 @@ const cvaTableRoot = cssClassVarianceUtilities.cvaMerge(["border-spacing-0", "mi
 const cvaTagsCell = cssClassVarianceUtilities.cvaMerge(["flex", "gap-2"]);
 
 /**
- * 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
  */
@@ -504,8 +917,44 @@ const cvaTextCellTooltip = cssClassVarianceUtilities.cvaMerge(["grid"]);
 
 /**
  * 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
  */