@trackunit/react-components 1.14.5 → 1.14.11

package/src/components/KPI/KPISkeleton.d.ts

@@ -0,0 +1,14 @@
+import { ReactElement } from "react";
+import { CommonProps } from "../../common/CommonProps";
+import { Styleable } from "../../common/Styleable";
+export interface KPISkeletonProps extends CommonProps, Styleable {
+    /**
+     * The size of the KPI skeleton
+     */
+    variant?: "small" | "default" | "condensed";
+}
+/**
+ * Skeleton loading indicator that mimics the KPI component structure.
+ * Uses the same layout, spacing, and visual hierarchy as KPI.
+ */
+export declare const KPISkeleton: ({ variant, className, "data-testid": dataTestId, style, ...rest }: KPISkeletonProps) => ReactElement;

package/src/components/KPICard/KPICard.d.ts

@@ -46,4 +46,4 @@ export interface KPICardProps extends MappedOmit<KPIProps, "variant"> {
  * @param {KPICardProps} props - The props for the KPICard component
  * @returns {ReactElement} KPICard component
  */
-export declare const KPICard: ({ isActive, onClick, className, "data-testid": dataTestId, children, iconName, iconColor, loading, notice, valueBar, trends, unit, ...rest }: KPICardProps) => ReactElement;
+export declare const KPICard: ({ isActive, onClick, className, "data-testid": dataTestId, children, iconName, iconColor, notice, valueBar, trends, unit, ...rest }: KPICardProps) => ReactElement;

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

@@ -2,6 +2,8 @@ export declare const cvaKPICard: (props?: ({
     isClickable?: boolean | null | undefined;
     isActive?: boolean | null | undefined;
 } & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
+export declare const cvaKPICardBody: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;
+export declare const cvaKPICardHeader: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;
 export declare const cvaKPIIconContainer: (props?: ({
     iconColor?: "success" | "warning" | "danger" | "info" | "neutral" | null | undefined;
 } & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;

package/src/components/KPICard/KPICardSkeleton.d.ts

@@ -0,0 +1,30 @@
+import { ReactElement, ReactNode } from "react";
+import { CommonProps } from "../../common/CommonProps";
+import { Styleable } from "../../common/Styleable";
+export interface KPICardSkeletonProps extends CommonProps, Styleable {
+    /**
+     * Whether to show an icon skeleton
+     */
+    hasIcon?: boolean;
+    /**
+     * Whether to show trends skeleton
+     */
+    hasTrends?: boolean;
+    /**
+     * Whether to show value bar skeleton
+     */
+    hasValueBar?: boolean;
+    /**
+     * Whether to show notice skeleton
+     */
+    hasNotice?: boolean;
+    /**
+     * Children to be rendered (e.g., custom skeleton content)
+     */
+    children?: ReactNode;
+}
+/**
+ * Skeleton loading indicator that mimics the KPICard component structure.
+ * Uses the same layout, spacing, and visual hierarchy as KPICard.
+ */
+export declare const KPICardSkeleton: ({ hasIcon, hasTrends, hasValueBar, hasNotice, children, className, "data-testid": dataTestId, style, ...rest }: KPICardSkeletonProps) => ReactElement;

package/src/components/PageHeader/components/PageHeaderKpiMetrics.d.ts

@@ -1,7 +1,7 @@
 import { ReactElement } from "react";
 import { PageHeaderKpiMetricsType } from "../types";
 /**
- * The PageHeaderKpiMetrics component is used to render the KPI metrics in the PageHeader component.
+ * Renders KPI metrics in the PageHeader component.
  *
  * @param {object} props - The props for the PageHeaderKpiMetrics component
  * @param {Array<PageHeaderKpiMetricsType>} props.kpiMetrics - The KPI metrics to render

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

@@ -0,0 +1,28 @@
+import { fontSizeKeys } from "@trackunit/ui-design-tokens";
+export type CSSLength = `${number}px` | `${number}rem` | `${number}em` | `${number}ch` | `${number}ex` | `${number}%`;
+export type TextSizeKey = `text-${fontSizeKeys}`;
+export type SkeletonVariant = "text" | "block";
+export declare const VALID_SIZE_KEYS: ReadonlyArray<fontSizeKeys>;
+/**
+ * Extract the size key from a text size string (e.g., "text-base" → "base").
+ *
+ * @param value - The text size string to parse
+ * @returns {fontSizeKeys | null} The extracted size key or null if invalid
+ */
+export declare const extractSizeKey: (value: string) => fontSizeKeys | null;
+/**
+ * Calculate the height value based on the height prop and variant.
+ *
+ * @param height - The height value (number, CSS length, or text size key)
+ * @param variant - The skeleton variant ("text" or "block")
+ * @returns {string} The calculated CSS height value
+ */
+export declare const getHeightValue: (height: TextSizeKey | number | string, variant: SkeletonVariant) => string;
+/**
+ * Calculate the vertical margin value for text variant to align with text baseline.
+ * Formula: (line-height - cap-height) / 2, where cap-height = font-size × 0.7
+ *
+ * @param height - The height value (number, CSS length, or text size key)
+ * @returns {string} The calculated CSS margin value
+ */
+export declare const getMarginValue: (height: TextSizeKey | number | string) => string;

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

@@ -0,0 +1,48 @@
+import { StringWithAutocompleteOptions } from "@trackunit/shared-utils";
+import { ReactNode } from "react";
+import { CommonProps } from "../../../common/CommonProps";
+import { CSSLength } from "../Skeleton.helpers";
+export type SkeletonBlockProps = CommonProps & {
+    /**
+     * The height of the skeleton.
+     *
+     * - Number: treated as pixels (e.g., 24 → "24px")
+     * - CSS length: any CSS length value (e.g., "1.5rem", "2em")
+     *
+     * @default 16
+     */
+    height?: number | StringWithAutocompleteOptions<CSSLength>;
+    /**
+     * The width of the skeleton.
+     *
+     * - Number: treated as pixels (e.g., 200 → "200px")
+     * - CSS length: any CSS length value or percentage (e.g., "50%", "20rem")
+     *
+     * @default "100%"
+     */
+    width?: number | StringWithAutocompleteOptions<CSSLength>;
+    /**
+     * Whether the width can shrink to fit within its container.
+     *
+     * - `true`: Uses max-width pattern - width can shrink if container is smaller
+     * - `false`: Uses exact width - width is fixed and won't shrink
+     *
+     * @default false
+     */
+    flexibleWidth?: boolean;
+    /**
+     * Optional children to render inside the skeleton.
+     * Useful for custom skeleton layouts with specific content.
+     */
+    children?: ReactNode;
+};
+/**
+ * Display a single placeholder block for shape-based elements before data gets loaded to reduce load-time frustration.
+ *
+ * Fills the full height for images, badges, buttons, avatars, and other shape-based elements.
+ * Uses numbers or CSS length values for height.
+ *
+ * For text content, use SkeletonLabel component instead.
+ * For multiple text lines, use SkeletonLines component instead.
+ */
+export declare const SkeletonBlock: import("react").NamedExoticComponent<SkeletonBlockProps>;

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

@@ -0,0 +1,2 @@
+export { SkeletonBlock } from "./SkeletonBlock";
+export type { SkeletonBlockProps } from "./SkeletonBlock";

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

@@ -0,0 +1,51 @@
+import { StringWithAutocompleteOptions } from "@trackunit/shared-utils";
+import { ReactNode } from "react";
+import { CommonProps } from "../../../common/CommonProps";
+import { CSSLength, TextSizeKey } from "../Skeleton.helpers";
+export type SkeletonLabelProps = CommonProps & {
+    /**
+     * The text size to match, using text size keys.
+     *
+     * Text size keys: text-xs, text-sm, text-base, text-lg, text-xl, text-2xl, text-3xl, text-4xl, text-5xl, text-6xl, text-7xl, text-8xl, text-9xl
+     *
+     * Height uses font-size × 0.7 to approximate visual cap-height, while margins are calculated as (line-height - cap-height) / 2
+     * using CSS variables. For large text sizes (5xl+), margins may be negative, allowing the skeleton to extend beyond the
+     * line-height box just like actual text does.
+     *
+     * @default "text-base"
+     */
+    textSize?: TextSizeKey;
+    /**
+     * The width of the skeleton.
+     *
+     * - Number: treated as pixels (e.g., 200 → "200px")
+     * - CSS length: any CSS length value or percentage (e.g., "50%", "20rem")
+     *
+     * @default "100%"
+     */
+    width?: number | StringWithAutocompleteOptions<CSSLength>;
+    /**
+     * Whether the width can shrink to fit within its container.
+     *
+     * - `true`: Uses max-width pattern - width can shrink if container is smaller
+     * - `false`: Uses exact width - width is fixed and won't shrink
+     *
+     * @default true
+     */
+    flexibleWidth?: boolean;
+    /**
+     * Optional children to render inside the skeleton.
+     * Useful for custom skeleton layouts with specific content.
+     */
+    children?: ReactNode;
+};
+/**
+ * Display a single placeholder line for text content before data gets loaded to reduce load-time frustration.
+ *
+ * Reduces height and adds vertical margins to match the visual space text occupies within its line-height.
+ * Uses text-size keys (text-xs, text-sm, text-base, etc.) for height to match actual text elements.
+ *
+ * For multiple text lines, use SkeletonLines component instead.
+ * For shape-based elements (images, badges, buttons), use SkeletonBlock component instead.
+ */
+export declare const SkeletonLabel: import("react").NamedExoticComponent<SkeletonLabelProps>;

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

@@ -0,0 +1,2 @@
+export { SkeletonLabel } from "./SkeletonLabel";
+export type { SkeletonLabelProps } from "./SkeletonLabel";

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

@@ -1,2 +1,4 @@
-export { Skeleton } from "./Skeleton";
-export type { SkeletonProps } from "./Skeleton";
+export { SkeletonLabel } from "./SkeletonLabel";
+export type { SkeletonLabelProps } from "./SkeletonLabel";
+export { SkeletonBlock } from "./SkeletonBlock";
+export type { SkeletonBlockProps } from "./SkeletonBlock";

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

@@ -1,36 +1,153 @@
+import { StringWithAutocompleteOptions } from "@trackunit/shared-utils";
+import { fontSizeKeys } from "@trackunit/ui-design-tokens";
 import { CommonProps } from "../../common/CommonProps";
-type SizeUnit = "px" | "%" | "rem" | "em";
-type SizeValue = `${number}${SizeUnit}` | "inherit" | (string & {});
-type GapUnit = "px" | "rem" | "em";
-type GapValue = `${number}${GapUnit}` | "inherit";
-type SkeletonDimension = number | SizeValue | Array<number | SizeValue>;
-export interface SkeletonLinesProps extends CommonProps {
+type CSSLength = `${number}px` | `${number}rem` | `${number}em` | `${number}ch` | `${number}ex` | `${number}%`;
+type TextSizeKey = `text-${fontSizeKeys}`;
+/**
+ * Preset configurations for common skeleton patterns.
+ */
+export type SkeletonLinesPreset = "short-paragraph" | "paragraph" | "long-paragraph" | "title-paragraph" | "heading-text" | "article";
+/**
+ * Base configuration shared between single line config and uniform mode.
+ */
+type BaseSkeletonLineConfig = {
+    /**
+     * The text size to match, using text size keys.
+     *
+     * Text size keys: text-xs, text-sm, text-base, text-lg, text-xl, text-2xl, text-3xl, text-4xl, text-5xl, text-6xl, text-7xl, text-8xl, text-9xl
+     *
+     * @default "text-base"
+     */
+    textSize?: TextSizeKey;
+    /**
+     * The width of the line.
+     *
+     * - Number: treated as pixels (e.g., 200 → "200px")
+     * - CSS length: any CSS length value or percentage (e.g., "50%", "20rem")
+     *
+     * @default "100%"
+     */
+    width?: number | StringWithAutocompleteOptions<CSSLength>;
+    /**
+     * Whether the width can shrink to fit within its container.
+     *
+     * - `true`: Uses max-width pattern - width can shrink if container is smaller
+     * - `false`: Uses exact width - width is fixed and won't shrink
+     *
+     * @default true
+     */
+    flexibleWidth?: boolean;
+};
+/**
+ * Configuration for a single skeleton line.
+ */
+export type SkeletonLineConfig = BaseSkeletonLineConfig & {
+    /**
+     * Optional className to apply to this specific line.
+     */
+    className?: string;
+};
+/**
+ * Props for SkeletonLines in uniform mode (default).
+ *
+ * Use this for displaying multiple identical skeleton lines.
+ */
+export type UniformSkeletonLinesProps = CommonProps & BaseSkeletonLineConfig & {
     /**
-     * The number of lines to display.
+     * Visual variant: "uniform" (default)
+     *
+     * Displays uniform skeleton lines with identical configuration.
      */
-    lines?: number;
+    variant: "uniform";
     /**
-     * The height of lines. Can be a number, string, or an array of numbers/strings.
+     * Number of skeleton lines to display.
      */
-    height?: SkeletonDimension;
+    count: number;
     /**
-     * The width of each line. Can be a number, string, or an array of numbers/strings.
-     * All width values are automatically wrapped in min(width, maxWidth) to prevent overflow.
+     * Optional className to apply to each individual line.
+     *
+     * Note: The container-level `className` prop (from CommonProps) applies to the wrapping container.
      */
-    width?: SkeletonDimension;
+    lineClassName?: string;
+};
+/**
+ * Props for SkeletonLines in custom mode.
+ *
+ * Use this for displaying skeleton lines with per-line configuration (varying widths, textSize (height), etc.).
+ */
+type CustomSkeletonLinesProps = CommonProps & {
     /**
-     * Gap between skeleton lines.
+     * Visual variant: "custom"
+     *
+     * Displays custom skeleton lines with per-line configuration.
      */
-    gap?: number | GapValue;
+    variant: "custom";
     /**
-     * Maximum width percentage to constrain skeleton lines. Defaults to "100%".
-     * Used in CSS min() function: min(width, maxWidth). Examples: "80%", "120%", "50%"
+     * Array of line configurations, one for each skeleton line.
+     *
+     * Each line can have its own textSize (height), width, and flexibleWidth settings.
      */
-    maxWidth?: `${number}%`;
-}
+    lines: Array<SkeletonLineConfig>;
+};
+/**
+ * Props for SkeletonLines in preset mode.
+ *
+ * Use this for common skeleton patterns with predefined configurations.
+ */
+type PresetSkeletonLinesProps = CommonProps & {
+    /**
+     * Visual variant: "preset"
+     *
+     * Displays skeleton lines using a predefined preset configuration.
+     */
+    variant: "preset";
+    /**
+     * The preset configuration to use.
+     *
+     * Available presets:
+     * - `"short-paragraph"`: 3 lines with last line at 60% width
+     * - `"paragraph"`: 5 lines with progressive width reduction
+     * - `"long-paragraph"`: 8 lines with varied widths
+     * - `"title-paragraph"`: Large heading + 3 body lines
+     * - `"heading-text"`: Heading + 4 body lines
+     * - `"article"`: Large title + meta info + 5 paragraph lines
+     */
+    preset: SkeletonLinesPreset;
+};
+/**
+ * Props for SkeletonLines component using discriminated union for type safety.
+ *
+ * - Use default (or `variant="uniform"`) with `count` for identical lines
+ * - Use `variant="custom"` with `lines` array for per-line configuration
+ * - Use `variant="preset"` with `preset` name for common patterns
+ */
+export type SkeletonLinesProps = UniformSkeletonLinesProps | CustomSkeletonLinesProps | PresetSkeletonLinesProps;
 /**
- * Display placeholder lines before the data gets loaded to reduce load-time frustration.
- * All width values are automatically constrained using CSS min() function to prevent overflow.
+ * Display multiple placeholder lines before data gets loaded to reduce load-time frustration.
+ *
+ * Supports three modes:
+ * - **Uniform mode** (default): Display identical lines using `count` prop
+ * - **Custom mode**: Display customized lines with per-line configuration using `variant="custom"` and `lines` prop
+ * - **Preset mode**: Display common patterns using `variant="preset"` and `preset` name
+ *
+ * Built on top of the [SkeletonLabel](?path=/docs/components-loading-states-skeletonlabel--docs) component for text-specific margins and sizing.
+ *
+ * @example
+ * // Uniform lines (simple mode)
+ * <SkeletonLines count={3} textSize="text-base" variant="uniform" />
+ * @example
+ * // Custom lines (advanced mode)
+ * <SkeletonLines
+ *   variant="custom"
+ *   lines={[
+ *     { textSize: "text-lg", width: "100%" },
+ *     { textSize: "text-base", width: "95%" },
+ *     { textSize: "text-base", width: "70%" }
+ *   ]}
+ * />
+ * @example
+ * // Preset lines (quick patterns)
+ * <SkeletonLines variant="preset" preset="title-paragraph" />
  */
 export declare const SkeletonLines: import("react").NamedExoticComponent<SkeletonLinesProps>;
 export {};

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

@@ -0,0 +1,5 @@
+import { SkeletonLineConfig, SkeletonLinesPreset } from "./SkeletonLines";
+/**
+ * Preset configurations for common skeleton patterns.
+ */
+export declare const PRESET_CONFIGURATIONS: Record<SkeletonLinesPreset, Array<SkeletonLineConfig>>;

package/src/index.d.ts

@@ -32,9 +32,11 @@ export * from "./components/Indicator";
 export * from "./components/Indicator/Indicator.variants";
 export * from "./components/InteractableItem/InteractableItem.variants";
 export * from "./components/KPI/KPI";
+export * from "./components/KPI/KPISkeleton";
 export * from "./components/KPICard/components/TrendIndicator/TrendIndicator";
 export * from "./components/KPICard/components/TrendIndicators";
 export * from "./components/KPICard/KPICard";
+export * from "./components/KPICard/KPICardSkeleton";
 export * from "./components/List/List";
 export * from "./components/List/List.variants";
 export * from "./components/List/useList";

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

@@ -1,115 +0,0 @@
-import { StringWithAutocompleteOptions } from "@trackunit/shared-utils";
-import { fontSizeKeys } from "@trackunit/ui-design-tokens";
-import { ReactNode } from "react";
-import { CommonProps } from "../../common/CommonProps";
-type CSSLength = `${number}px` | `${number}rem` | `${number}em` | `${number}ch` | `${number}ex` | `${number}%`;
-type TextSizeKey = `text-${fontSizeKeys}`;
-export type SkeletonVariant = "text" | "block";
-/**
- * Props for Skeleton when using text variant.
- *
- * Reduces height and adds vertical margins to match the visual space text occupies within its line-height.
- * Must be used with text-size keys for height.
- */
-type SkeletonTextProps = {
-    /**
-     * Visual variant: "text"
-     *
-     * @default "text"
-     */
-    variant?: "text";
-    /**
-     * The height of the skeleton using text size keys.
-     *
-     * Text size keys: text-xs, text-sm, text-base, text-lg, text-xl, text-2xl, text-3xl, text-4xl, text-5xl, text-6xl, text-7xl, text-8xl, text-9xl
-     *
-     * Height uses font-size × 0.7 to approximate visual cap-height, while margins are calculated as (line-height - cap-height) / 2
-     * using CSS variables. For large text sizes (5xl+), margins may be negative, allowing the skeleton to extend beyond the
-     * line-height box just like actual text does.
-     *
-     * @default "text-base"
-     */
-    height?: TextSizeKey;
-};
-/**
- * Props for Skeleton when using block variant.
- *
- * Fills the full height (for images, badges, buttons, and other shape-based elements).
- * Must be used with numbers or CSS length values for height.
- */
-type SkeletonBlockProps = {
-    /**
-     * Visual variant: "block"
-     */
-    variant: "block";
-    /**
-     * The height of the skeleton.
-     *
-     * - Number: treated as pixels (e.g., 24 → "24px")
-     * - CSS length: any CSS length value (e.g., "1.5rem", "2em")
-     */
-    height?: number | StringWithAutocompleteOptions<CSSLength>;
-};
-/**
- * Props for Skeleton component using discriminated union for type safety.
- *
- * - Use `variant="text"` with text-size keys (text-xs, text-sm, etc.) for text placeholders
- * - Use `variant="block"` with numbers or CSS lengths for shape-based elements (images, badges, buttons, etc.)
- */
-export type SkeletonProps = CommonProps & (SkeletonTextProps | SkeletonBlockProps) & {
-    /**
-     * The width of the skeleton.
-     *
-     * - Number: treated as pixels (e.g., 200 → "200px")
-     * - CSS length: any CSS length value or percentage (e.g., "50%", "20rem")
-     *
-     * @default "100%"
-     */
-    width?: number | StringWithAutocompleteOptions<CSSLength>;
-    /**
-     * Whether the width can shrink to fit within its container.
-     *
-     * - `true`: Uses max-width pattern - width can shrink if container is smaller
-     * - `false`: Uses exact width - width is fixed and won't shrink
-     *
-     * @default true for text variant, false for block variant
-     */
-    flexibleWidth?: boolean;
-    /**
-     * Optional children to render inside the skeleton.
-     * Useful for custom skeleton layouts with specific content.
-     */
-    children?: ReactNode;
-};
-/**
- * Extract the size key from a text size string (e.g., "text-base" → "base").
- *
- * @param value - The text size string to parse
- * @returns {fontSizeKeys | null} The extracted size key or null if invalid
- */
-export declare const extractSizeKey: (value: string) => fontSizeKeys | null;
-/**
- * Calculate the height value based on the height prop and variant.
- *
- * @param height - The height value (number, CSS length, or text size key)
- * @param variant - The skeleton variant ("text" or "block")
- * @returns {string} The calculated CSS height value
- */
-export declare const getHeightValue: (height: TextSizeKey | number | string, variant: SkeletonVariant) => string;
-/**
- * Calculate the vertical margin value for text variant to align with text baseline.
- * Formula: (line-height - cap-height) / 2, where cap-height = font-size × 0.7
- *
- * @param height - The height value (number, CSS length, or text size key)
- * @returns {string} The calculated CSS margin value
- */
-export declare const getMarginValue: (height: TextSizeKey | number | string) => string;
-/**
- * Display a single placeholder line before data gets loaded to reduce load-time frustration.
- *
- * Use `variant="text"` with text-size keys for text placeholders.
- * Use `variant="block"` with numbers/CSS for images, badges, buttons, and other shape-based elements.
- * Pass children to create custom skeleton layouts.
- */
-export declare const Skeleton: import("react").NamedExoticComponent<SkeletonProps>;
-export {};