@trackunit/react-components 3.1.7 → 3.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "3.1.7",
+  "version": "3.2.1",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "migrations": "./migrations.json",
@@ -14,16 +14,16 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.15.40",
-    "@trackunit/css-class-variance-utilities": "2.0.19",
-    "@trackunit/shared-utils": "1.16.54",
-    "@trackunit/ui-icons": "1.14.48",
+    "@trackunit/ui-design-tokens": "1.15.41",
+    "@trackunit/css-class-variance-utilities": "2.0.20",
+    "@trackunit/shared-utils": "1.16.55",
+    "@trackunit/ui-icons": "1.14.49",
     "es-toolkit": "^1.39.10",
     "@tanstack/react-virtual": "^3.14.3",
     "dequal": "^2.0.3",
     "fflate": "^0.8.2",
     "zod": "^3.25.76",
-    "@trackunit/i18n-library-translation": "2.5.4"
+    "@trackunit/i18n-library-translation": "2.5.5"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/components/AssetIdentity/IdentityCard.d.ts

@@ -0,0 +1,173 @@
+import { tailwindPalette, ThemeColors } from "@trackunit/ui-design-tokens";
+import { MouseEventHandler, ReactElement, ReactNode } from "react";
+import { CommonProps } from "../../common/CommonProps";
+import { Refable } from "../../common/Refable";
+import type { Styleable } from "../../common/Styleable";
+type ThemeColorShades = `${keyof (typeof tailwindPalette)[keyof typeof tailwindPalette]}`;
+export interface IdentityCardProps extends CommonProps, Styleable, Refable<HTMLDivElement> {
+    /**
+     * Asset name / primary heading. Truncates with an ellipsis when the row
+     * is narrow. Required — call-sites without a resolved name should render
+     * `IdentityCardSkeleton`, or pass a domain-appropriate fallback string.
+     */
+    title: string;
+    /**
+     * Breadcrumb segments (e.g. `["Trackunit", "Scissorlift", "GS4390"]`).
+     * Rendered via the `DetailsList` component. Call-sites should pass a
+     * pre-filtered array of strings (e.g. `segments.filter(nonNullable)`);
+     * omit the prop entirely to hide the subtitle row.
+     */
+    subtitle?: Array<string>;
+    /**
+     * Optional asset image. Rendered to the left of the title at a 14:9
+     * aspect ratio (168/108, matching `AssetPageHeader`); the image height
+     * tracks the rendered text stack. Pass an `<img>` or `<OEMModelImage>`
+     * inside.
+     *
+     * Mutually exclusive with `thumbnail` — pass `image` for the "asset
+     * photo" shape, `thumbnail` for the ListItem-style colored icon badge
+     * (typical for sites / customers / users). If both are supplied, `image`
+     * wins.
+     */
+    image?: ReactNode;
+    /**
+     * Optional icon-shaped thumbnail. Use for non-asset entities (sites, customers, users, …)
+     * to render a colored icon square.
+     *
+     * Pair with `thumbnailColor` and `thumbnailBackground` to color the icon
+     * and its badge. Mutually exclusive with `image` (which wins if both
+     * are supplied).
+     */
+    thumbnail?: ReactElement;
+    /**
+     * Foreground color of the `thumbnail` icon. Applied as
+     * `text-${thumbnailColor}` on the badge container.
+     *
+     * @default "info-600"
+     */
+    thumbnailColor?: `${ThemeColors}-${ThemeColorShades}` | `${ThemeColors}`;
+    /**
+     * Background color of the `thumbnail` badge. Applied as
+     * `bg-${thumbnailBackground}` on the badge container.
+     *
+     * @default "info-100"
+     */
+    thumbnailBackground?: `${ThemeColors}-${ThemeColorShades}` | `${ThemeColors}`;
+    /**
+     * Status indicators row (criticality, activity, rental status, …).
+     * Pass domain-specific indicator chips as a fragment. Compose from
+     * `CriticalityIndicator` / `ActivityIndicator` / `RentalIndicator`
+     * (not `RentalTag`) at the call-site — rental sits in this row as a
+     * neutral indicator so it matches the chips beside it.
+     */
+    statusIndicators?: ReactNode;
+    /**
+     * Right-side connectivity slot. Typically the last-GSM (`ChartBar`) and
+     * last-GPS (`MapPin`) chips from `AssetPageHeader` — a `Highlight` with
+     * `iconName` set to the last-seen icon (`color="clear"` when fresh,
+     * warning/danger when stale), or an "Untracked" label when the asset has
+     * no telematics device. Any `ReactNode` is accepted; wrap each chip as a
+     * single child so the slot's gap sits between chips.
+     */
+    connectivity?: ReactNode;
+    /**
+     * Optional click handler for the card as a whole. When provided the card
+     * becomes interactive (hover state, cursor pointer) and a right-side
+     * `ChevronRight` icon is rendered as a visual affordance. The card also
+     * becomes keyboard-operable: `role="button"`, `tabIndex={0}`, and Enter /
+     * Space fire the handler alongside pointer clicks.
+     */
+    onClick?: MouseEventHandler<HTMLDivElement>;
+}
+/**
+ * IdentityCard is the entity-agnostic, `Card`-wrapped identity component.
+ * It renders a slot-based identity strip (14:9 image, title + subtitle,
+ * status indicators, connectivity) inside a bordered surface —
+ * the compact list-row / drawer-row shape used to *reference* a related
+ * entity (an asset, site, customer, user, …) from inside a surface whose
+ * real focus is something else (an alert, service ticket, inspection, …).
+ *
+ * When `onClick` is supplied, the whole card becomes clickable and a
+ * `ChevronRight` icon is rendered on the right edge to signal navigation.
+ * Clickable cards are meant to route the user to the referenced entity's
+ * own surface — pair the handler with the app's navigation hook
+ * (`useNavigateInHost` from `@trackunit/react-core-hooks`) rather than
+ * treating it as an in-place action. Clickable cards are keyboard-operable
+ * out of the box: they receive `role="button"`, join the tab order, and
+ * activate on Enter / Space with a visible focus ring.
+ *
+ * The card stays presentational: it owns layout only; domain hydration
+ * (indicator wiring, translations, last-seen formatting,
+ * click targets) lives at the call-site. The API stays lean so the
+ * inline-reference shape doesn't compete with the surrounding surface's
+ * real focus.
+ *
+ * For the loading placeholder, use the paired `IdentityCardSkeleton`
+ * component — it renders the same layout with per-slot skeleton blocks.
+ *
+ * ### When to use
+ * Use `IdentityCard` when the surface you're building is really **about
+ * something else** (an alert, a service ticket, an inspection, a scheduled
+ * job) and needs to *mention* a related entity in its content, usually
+ * with a click-through to that entity's own page.
+ *
+ * ### When not to use
+ * Do not use `IdentityCard` as the header of a surface whose subject
+ * **is** the entity (an asset's side panel, an asset overview card, a
+ * page-level asset header). The card is a reference that lives *inside*
+ * someone else's content.
+ *
+ * @example Clickable asset reference inside a service ticket panel
+ * ```tsx
+ * import { IdentityCard, Highlight } from "@trackunit/react-components";
+ * import { useNavigateInHost } from "@trackunit/react-core-hooks";
+ *
+ * const ServicedAssetRow = ({ assetId }: { assetId: string }) => {
+ *   const { gotoAssetHome } = useNavigateInHost();
+ *   return (
+ *     <IdentityCard
+ *       title="Trackunit-AWP343"
+ *       subtitle={["Trackunit", "Scissorlift", "GS4390"]}
+ *       image={<OEMModelImage brandName="Trackunit" model="GS4390" />}
+ *       statusIndicators={statusChips}
+ *       connectivity={
+ *         <>
+ *           <Highlight color="clear" iconName="ChartBar" size="small">
+ *             2h
+ *           </Highlight>
+ *           <Highlight color="danger" iconName="MapPin" size="small">
+ *             2y
+ *           </Highlight>
+ *         </>
+ *       }
+ *       onClick={() => gotoAssetHome(assetId)}
+ *     />
+ *   );
+ * };
+ * ```
+ * @example Non-clickable (chevron omitted)
+ * ```tsx
+ * <IdentityCard
+ *   image={<OEMModelImage brandName="Trackunit" model="GS4390" />}
+ *   title="Trackunit-AWP343"
+ *   subtitle={["Trackunit", "Scissorlift", "GS4390"]}
+ * />
+ * ```
+ * @example Non-asset entity (site) with an icon thumbnail
+ * ```tsx
+ * import { IdentityCard, Icon } from "@trackunit/react-components";
+ *
+ * <IdentityCard
+ *   title="Riverside Job Site"
+ *   subtitle={["Riverside Street 12, Copenhagen, Denmark"]}
+ *   thumbnail={<Icon name="ConstructionCone" />}
+ *   thumbnailColor="site_construction_site-500"
+ *   thumbnailBackground="site_construction_site-100"
+ *   onClick={() => gotoSiteHome(siteId)}
+ * />
+ * ```
+ * @param {IdentityCardProps} props - The props for the IdentityCard component
+ * @returns {ReactElement} IdentityCard component
+ */
+export declare const IdentityCard: ({ title, subtitle, image, thumbnail, thumbnailColor, thumbnailBackground, statusIndicators, connectivity, onClick, className, "data-testid": dataTestId, style, ref, }: IdentityCardProps) => ReactElement;
+export {};

package/src/components/AssetIdentity/IdentityCard.variants.d.ts

@@ -0,0 +1,120 @@
+export declare const cvaCardContentRow: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
+export declare const cvaCardMain: import("cva").CVAComponent<Omit<{
+    base: string[];
+    variants: {
+        singleLine: {
+            true: string;
+            false: string;
+        };
+    };
+    defaultVariants: {
+        singleLine: false;
+    };
+}, "defaultVariants"> & {
+    variants: {
+        singleLine: {
+            true: string;
+            false: string;
+        };
+    };
+    defaultVariants: Omit<{}, "singleLine"> & {
+        singleLine: false;
+    };
+}, {
+    singleLine: {
+        true: string;
+        false: string;
+    };
+}>;
+export declare const cvaCardImage: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
+export declare const cvaCardThumbnail: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
+export declare const cvaCardTextStack: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
+export declare const cvaCardIdentityGroup: import("cva").CVAComponent<Omit<{
+    base: string[];
+    variants: {
+        singleLine: {
+            true: string[];
+            false: string;
+        };
+    };
+    defaultVariants: {
+        singleLine: false;
+    };
+}, "defaultVariants"> & {
+    variants: {
+        singleLine: {
+            true: string[];
+            false: string;
+        };
+    };
+    defaultVariants: Omit<{}, "singleLine"> & {
+        singleLine: false;
+    };
+}, {
+    singleLine: {
+        true: string[];
+        false: string;
+    };
+}>;
+export declare const cvaCardTitleRow: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
+export declare const cvaCardTitleCluster: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
+export declare const cvaCardTitle: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
+export declare const cvaCardStatusRow: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
+export declare const cvaCardStatusSkeletonRow: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
+export declare const cvaCardConnectivity: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
+export declare const cvaCardChevron: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;

package/src/components/AssetIdentity/IdentityCardSkeleton.d.ts

@@ -0,0 +1,95 @@
+import { ReactElement } from "react";
+import { CommonProps } from "../../common/CommonProps";
+import { Refable } from "../../common/Refable";
+import type { Styleable } from "../../common/Styleable";
+export interface IdentityCardSkeletonProps extends CommonProps, Styleable, Refable<HTMLDivElement> {
+    /**
+     * When true, renders an image slot with a size-matched skeleton block. The
+     * slot's height tracks the rendered text stack at a 14:9 aspect ratio
+     * (168/108, matching `AssetPageHeader`) — same measurement approach as
+     * the loaded `IdentityCard` so the skeleton → loaded transition doesn't
+     * jump.
+     *
+     * Mutually exclusive with `hasThumbnail` — `hasImage` wins if both
+     * are true (mirrors the loaded card's slot precedence).
+     *
+     * @default false
+     */
+    hasImage?: boolean;
+    /**
+     * When true, renders a 44×44 rounded-md skeleton badge in the thumbnail
+     * slot — the loading counterpart to the loaded card's `thumbnail` prop.
+     * Use for non-asset entities (sites, customers, users, …).
+     *
+     * Mutually exclusive with `hasImage` — `hasImage` wins if both are true.
+     *
+     * @default false
+     */
+    hasThumbnail?: boolean;
+    /**
+     * When true, renders a subtitle skeleton line under the title. Kept on by
+     * default so `<IdentityCardSkeleton />` with no props renders the
+     * canonical compact identity card shape (title + subtitle).
+     *
+     * @default true
+     */
+    hasSubtitle?: boolean;
+    /**
+     * When true, renders a status-row skeleton (two chip placeholders) under
+     * the identity group.
+     *
+     * @default false
+     */
+    hasStatusIndicators?: boolean;
+    /**
+     * When true, renders a right-side connectivity skeleton on the title row.
+     *
+     * @default false
+     */
+    hasConnectivity?: boolean;
+    /**
+     * When true, renders the same right-side `ChevronRight` as a clickable
+     * `IdentityCard` — the icon is known up front, so it is not skeletoned.
+     * Keeps the skeleton → loaded transition from jumping.
+     *
+     * @default false
+     */
+    hasChevron?: boolean;
+}
+/**
+ * IdentityCardSkeleton is the loading placeholder paired with
+ * `IdentityCard`. It renders per-slot skeleton blocks (title +
+ * optional subtitle / status indicators / image / thumbnail / connectivity)
+ * inside the same `Card` shell so the skeleton → loaded
+ * transition is visually stable. When `hasChevron` is on, the real
+ * `ChevronRight` is shown — that icon does not depend on loaded data.
+ *
+ * The slot toggles (`hasImage`, `hasThumbnail`, `hasSubtitle`,
+ * `hasStatusIndicators`, `hasConnectivity`, `hasChevron`) are the skeleton
+ * counterparts to the loaded `IdentityCard`'s slot props / `onClick` —
+ * flip on the slots you'll render once the data resolves.
+ *
+ * ### When to use
+ * Use `IdentityCardSkeleton` in place of `IdentityCard` while
+ * the referenced entity's data is being fetched.
+ *
+ * ### When not to use
+ * Do not use for generic text loading — use `SkeletonLabel` /
+ * `SkeletonBlock` directly. Do not use to represent partial data (some
+ * fields loaded, others not); render `IdentityCard` with the fields
+ * you have and omit the rest.
+ *
+ * @example Compact card (title + subtitle)
+ * ```tsx
+ * import { IdentityCardSkeleton } from "@trackunit/react-components";
+ *
+ * const Loading = () => <IdentityCardSkeleton />;
+ * ```
+ * @example Clickable card with image + status + connectivity
+ * ```tsx
+ * <IdentityCardSkeleton hasImage hasStatusIndicators hasConnectivity hasChevron />
+ * ```
+ * @param {IdentityCardSkeletonProps} props - The props for the IdentityCardSkeleton component
+ * @returns {ReactElement} IdentityCardSkeleton component
+ */
+export declare const IdentityCardSkeleton: ({ hasImage, hasThumbnail, hasSubtitle, hasStatusIndicators, hasConnectivity, hasChevron, className, "data-testid": dataTestId, style, ref, }: IdentityCardSkeletonProps) => ReactElement;

package/src/components/AssetIdentity/useIdentityImageSize.d.ts

@@ -0,0 +1,32 @@
+import { type RefCallback } from "react";
+export declare const IDENTITY_MIN_IMAGE_HEIGHT_PX = 44;
+export declare const IDENTITY_IMAGE_ASPECT_RATIO: number;
+export type IdentityImageSize = {
+    readonly height: number;
+    readonly width: number;
+};
+export type IdentityImageSizeResult = {
+    readonly imageSize: IdentityImageSize | null;
+    readonly textStackRef: RefCallback<HTMLDivElement>;
+};
+/**
+ * Measures the rendered text-stack height and returns matching image
+ * dimensions at a 14:9 (168/108) aspect ratio, clamped to the identity
+ * minimum so title-only identities keep a reasonable image footprint. Kept
+ * as a shared hook so the loaded `IdentityCard` and its `IdentityCardSkeleton`
+ * cannot drift out of sync — the skeleton → loaded transition would jump
+ * if the two measurements diverged.
+ *
+ * Measured in `useLayoutEffect` so the image slot is sized before the
+ * browser paints. `useMeasure` is the usual choice here, but it observes
+ * in `useEffect` (after paint), which would flash the unsized
+ * `aspect-[14/9]` fallback for a frame.
+ *
+ * Attach `textStackRef` to the text-stack container; subsequent layout
+ * changes (title text, subtitle wrap, status row toggling on/off)
+ * re-measure automatically.
+ *
+ * @param enabled - When false, the hook is inert (no measurement). Use this
+ *   to gate on `showImage` / `hasImage`.
+ */
+export declare const useIdentityImageSize: (enabled: boolean) => IdentityImageSizeResult;

package/src/components/Indicator/Indicator.d.ts

@@ -1,8 +1,8 @@
 import { ActivityColors, CriticalityColors, GeneralColors, IntentColors, RentalStatusColors, SitesColors, UtilizationColors } from "@trackunit/ui-design-tokens";
-import { ReactElement } from "react";
+import { ReactElement, ReactNode } from "react";
 import { CommonProps } from "../../common/CommonProps";
-import type { Styleable } from "../../common/Styleable";
 import { Refable } from "../../common/Refable";
+import type { Styleable } from "../../common/Styleable";
 export interface IndicatorProps extends CommonProps, Styleable, Refable<HTMLDivElement> {
     /**
      * The icon to be rendered inside the indicator component
@@ -21,9 +21,9 @@ export interface IndicatorProps extends CommonProps, Styleable, Refable<HTMLDivE
      */
     weight?: "normal" | "medium";
     /**
-     * A text label to be displayed next to the indicator
+     * Content displayed next to the indicator. String labels are capitalized; custom content retains its own casing.
      */
-    label?: string;
+    label?: ReactNode;
     /**
      * A boolean parameter to display or hide icon background, default value is true
      */

package/src/components/Indicator/Indicator.variants.d.ts

@@ -11,8 +11,11 @@ export declare const cvaIndicatorIcon: import("cva").CVAComponent<Omit<{
     defaultVariants: Omit<{}, never>;
 }, unknown>;
 export declare const cvaIndicatorLabel: import("cva").CVAComponent<Omit<{
-    base: string[];
     variants: {
+        content: {
+            text: string;
+            custom: null;
+        };
         size: {
             small: string;
             medium: string;
@@ -27,12 +30,17 @@ export declare const cvaIndicatorLabel: import("cva").CVAComponent<Omit<{
         };
     };
     defaultVariants: {
+        content: "text";
         size: "medium";
         weight: "medium";
         background: "visible";
     };
 }, "defaultVariants"> & {
     variants: {
+        content: {
+            text: string;
+            custom: null;
+        };
         size: {
             small: string;
             medium: string;
@@ -46,12 +54,17 @@ export declare const cvaIndicatorLabel: import("cva").CVAComponent<Omit<{
             hidden: string;
         };
     };
-    defaultVariants: Omit<{}, "size" | "weight" | "background"> & {
+    defaultVariants: Omit<{}, "content" | "size" | "weight" | "background"> & {
+        content: "text";
         size: "medium";
         weight: "medium";
         background: "visible";
     };
 }, {
+    content: {
+        text: string;
+        custom: null;
+    };
     size: {
         small: string;
         medium: string;

package/src/index.d.ts

@@ -7,6 +7,8 @@ export * from "./common/Size";
 export * from "./common/StorybookProps";
 export type { Styleable } from "./common/Styleable";
 export * from "./components/Alert/Alert";
+export * from "./components/AssetIdentity/IdentityCard";
+export * from "./components/AssetIdentity/IdentityCardSkeleton";
 export * from "./components/Badge/Badge";
 export * from "./components/Breadcrumb/Breadcrumb";
 export * from "./components/buttons/Button/Button";