@trackunit/react-components 1.13.10 → 1.13.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.13.10",
+  "version": "1.13.12",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -14,10 +14,10 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.9.18",
-    "@trackunit/css-class-variance-utilities": "1.9.19",
-    "@trackunit/shared-utils": "1.11.19",
-    "@trackunit/ui-icons": "1.9.18",
+    "@trackunit/ui-design-tokens": "1.9.20",
+    "@trackunit/css-class-variance-utilities": "1.9.21",
+    "@trackunit/shared-utils": "1.11.21",
+    "@trackunit/ui-icons": "1.9.20",
     "@tanstack/react-router": "1.114.29",
     "es-toolkit": "^1.39.10",
     "@tanstack/react-virtual": "3.13.12",

package/src/components/GridAreas/GridAreas.d.ts

@@ -0,0 +1,95 @@
+import { ReactNode } from "react";
+import { GridAreasResult, SlotProps } from "./types";
+/**
+ * Props for the GridAreas component.
+ *
+ * Spread the result from useGridAreas() onto this component.
+ */
+export type GridAreasProps<TAreaName extends string> = GridAreasResult<TAreaName> & {
+    /** Additional CSS classes to apply to the grid container */
+    className?: string;
+    /** Render prop that receives the slots object */
+    children: (slots: Record<TAreaName, SlotProps>) => ReactNode;
+    /**
+     * If true, renders as the child element instead of a div.
+     * The child must accept className and ref props.
+     */
+    asChild?: boolean;
+};
+/**
+ * Component for CSS grid with dynamic grid-template-areas.
+ *
+ * Renders the style tag and container div with proper scoping.
+ * Uses a render prop pattern to provide typed slot props for children.
+ *
+ * @example Basic usage with builder pattern and hook
+ * ```tsx
+ * // Define grid config at module level (runs once)
+ * const cardGrid = createGrid()
+ *   .areas(['icon', 'info'])
+ *   .layout({ layout: [['icon', 'info']] })
+ *   .build();
+ *
+ * function MyCard() {
+ *   const gridAreas = useGridAreas(cardGrid);
+ *
+ *   return (
+ *     <GridAreas {...gridAreas} className="gap-4">
+ *       {(slots) => (
+ *         <>
+ *           <Icon {...slots.icon} />
+ *           <Info {...slots.info} />
+ *         </>
+ *       )}
+ *     </GridAreas>
+ *   );
+ * }
+ * ```
+ * @example Conditional layouts
+ * ```tsx
+ * const cardGrid = createGrid()
+ *   .areas(['icon', 'info', 'tag'])
+ *   .layout({ layout: [['info']] })
+ *   .layout({
+ *     when: ['icon', 'info'],
+ *     layout: [['icon', 'info']],
+ *     columns: ['48px', '1fr'],
+ *   })
+ *   .build();
+ *
+ * function MyCard({ showIcon }) {
+ *   const gridAreas = useGridAreas(cardGrid);
+ *
+ *   return (
+ *     <GridAreas {...gridAreas}>
+ *       {(slots) => (
+ *         <>
+ *           {showIcon && <Icon {...slots.icon} />}
+ *           <Info {...slots.info} />
+ *         </>
+ *       )}
+ *     </GridAreas>
+ *   );
+ * }
+ * ```
+ * @example Using asChild to render a custom element
+ * ```tsx
+ * function MyCard() {
+ *   const gridAreas = useGridAreas(cardGrid);
+ *
+ *   return (
+ *     <GridAreas {...gridAreas} asChild className="gap-4">
+ *       <section aria-label="Card content">
+ *         {(slots) => (
+ *           <>
+ *             <Icon {...slots.icon} />
+ *             <Info {...slots.info} />
+ *           </>
+ *         )}
+ *       </section>
+ *     </GridAreas>
+ *   );
+ * }
+ * ```
+ */
+export declare function GridAreas<TAreaName extends string>({ slots, css, containerProps, validationRef, className, children, asChild, }: GridAreasProps<TAreaName>): ReactNode;

package/src/components/GridAreas/createGrid.d.ts

@@ -0,0 +1,130 @@
+import { BreakpointLayoutConfig, ContainerBreakpoint, EmptyCell, GridConfig, TrackSize } from "./types";
+/**
+ * A readonly 2D grid layout tuple for type-safe layout configuration.
+ * Each inner tuple represents a row of grid cells.
+ */
+type GridLayoutTuple<TCell extends string = string> = ReadonlyArray<ReadonlyArray<TCell>>;
+/**
+ * Extracts the row count from a layout tuple.
+ */
+type LayoutRowCount<TLayout extends GridLayoutTuple> = TLayout["length"];
+/**
+ * Extracts the column count from a layout tuple (from first row).
+ */
+type LayoutColCount<TLayout extends GridLayoutTuple> = TLayout extends readonly [
+    infer TFirstRow extends ReadonlyArray<unknown>,
+    ...ReadonlyArray<unknown>
+] ? TFirstRow["length"] : 0;
+/**
+ * Flattens a layout tuple to get all used cell values as a union type.
+ */
+type FlattenLayout<TLayout extends GridLayoutTuple> = TLayout[number][number];
+/**
+ * Finds items from TWhen that are NOT present in the layout.
+ * Returns never if all items are present, otherwise returns the missing items.
+ */
+type FindMissingWhenItems<TWhen extends ReadonlyArray<string>, TLayout extends GridLayoutTuple> = Exclude<TWhen[number], FlattenLayout<TLayout>>;
+/**
+ * Strict input type for .layout() that validates all constraints.
+ * Errors appear directly on the invalid property for clear feedback.
+ *
+ * @template TAreaName - Available area names from .areas()
+ * @template TLayout - The layout tuple being validated
+ * @template TWhen - Optional when clause (subset of TAreaName)
+ * @template TRows - Optional row track sizes
+ * @template TCols - Optional column track sizes
+ */
+type StrictLayoutInput<TAreaName extends string, TLayout extends GridLayoutTuple<TAreaName | EmptyCell>, TWhen extends ReadonlyArray<TAreaName> | undefined, TRows extends ReadonlyArray<TrackSize> | undefined, TCols extends ReadonlyArray<TrackSize> | undefined> = {
+    /**
+     * Area names that must be present for this layout to apply.
+     * Must be a subset of the areas defined in .areas().
+     */
+    when?: TWhen;
+    /**
+     * The grid layout. Each cell must be an area name or "." for empty.
+     * When `when` is provided, all `when` items must appear in the layout.
+     */
+    layout: TLayout & (TWhen extends ReadonlyArray<TAreaName> ? FindMissingWhenItems<TWhen, TLayout> extends never ? unknown : {
+        _missingFromLayout: FindMissingWhenItems<TWhen, TLayout>;
+    } : unknown);
+    /**
+     * Grid row track sizes. Length must match the number of rows in layout.
+     */
+    rows?: TRows & (TRows extends ReadonlyArray<TrackSize> ? TRows["length"] extends LayoutRowCount<TLayout> ? unknown : {
+        _rowCountError: {
+            expected: LayoutRowCount<TLayout>;
+            got: TRows["length"];
+        };
+    } : unknown);
+    /**
+     * Grid column track sizes. Length must match the number of columns in layout.
+     */
+    columns?: TCols & (TCols extends ReadonlyArray<TrackSize> ? TCols["length"] extends LayoutColCount<TLayout> ? unknown : {
+        _columnCountError: {
+            expected: LayoutColCount<TLayout>;
+            got: TCols["length"];
+        };
+    } : unknown);
+    /**
+     * Responsive breakpoint overrides.
+     */
+    breakpoints?: Partial<Record<ContainerBreakpoint, BreakpointLayoutConfig<TAreaName>>>;
+};
+/**
+ * Builder interface for adding layouts after .areas() is called.
+ * Each .layout() call is type-checked against the available areas.
+ */
+interface GridAreasBuilder<TAreaName extends string> {
+    /**
+     * Add a layout configuration. Can be chained multiple times.
+     * Layout cells are constrained to area names defined in .areas() plus ".".
+     */
+    layout<const TLayout extends GridLayoutTuple<TAreaName | EmptyCell>, const TWhen extends ReadonlyArray<TAreaName> | undefined = undefined, const TRows extends ReadonlyArray<TrackSize> | undefined = undefined, const TCols extends ReadonlyArray<TrackSize> | undefined = undefined>(config: StrictLayoutInput<TAreaName, TLayout, TWhen, TRows, TCols>): GridAreasBuilder<TAreaName>;
+    /**
+     * Finalize and return the grid configuration.
+     * Pass this to the GridAreas component.
+     */
+    build(): GridConfig<TAreaName>;
+}
+/**
+ * Initial builder interface before .areas() is called.
+ */
+interface GridAreasBuilderInit {
+    /**
+     * Define the area names for this grid.
+     * These names will be available for autocomplete in .layout() calls.
+     */
+    areas<const TAreas extends ReadonlyArray<string>>(areas: TAreas): GridAreasBuilder<TAreas[number]>;
+}
+/**
+ * Creates a type-safe grid configuration using a fluent builder pattern.
+ *
+ * The builder provides:
+ * - Full autocomplete for area names in layouts
+ * - Type errors on the correct property (columns, rows, layout)
+ * - Validation that layout cells match defined areas
+ * - Validation that all `when` items appear in the layout
+ *
+ * @example Module-level definition (recommended for static grids)
+ * ```tsx
+ * const cardGrid = createGrid()
+ *   .areas(["icon", "info", "tag"])
+ *   .layout({ layout: [["info"]] })
+ *   .layout({
+ *     when: ["icon", "info"],
+ *     layout: [["icon", "info"]],
+ *     columns: ["48px", "1fr"],
+ *   })
+ *   .build();
+ *
+ * function MyCard() {
+ *   return (
+ *     <GridAreas config={cardGrid}>
+ *       {(slots) => (<>{slots.icon}...</>)}
+ *     </GridAreas>
+ *   );
+ * }
+ * ```
+ */
+export declare function createGrid(): GridAreasBuilderInit;
+export {};

package/src/components/GridAreas/generateCss.d.ts

@@ -0,0 +1,15 @@
+import { GridConfig, SlotProps } from "./types";
+/**
+ * Creates a typed slots object from an array of area names.
+ *
+ * Each slot contains a data-slot attribute and gridArea style.
+ */
+export declare function createSlots<TAreaName extends string>(areas: ReadonlyArray<TAreaName>): Record<TAreaName, SlotProps>;
+/**
+ * Generates CSS string from a grid configuration and id.
+ *
+ * @param id - Unique identifier for CSS scoping
+ * @param config - Grid configuration from createGrid().build()
+ * @returns {string} CSS string for use in a style tag
+ */
+export declare function generateCss<TAreaName extends string>(id: string, config: GridConfig<TAreaName>): string;

package/src/components/GridAreas/types.d.ts

@@ -0,0 +1,104 @@
+import { StringWithAutocompleteOptions } from "@trackunit/shared-utils";
+import { themeContainerSize } from "@trackunit/ui-design-tokens";
+import { CSSProperties } from "react";
+/**
+ * Tailwind CSS default container query breakpoints with @ prefix.
+ *
+ * These are the standard values used by @sm, @md, @lg, etc. in Tailwind container queries.
+ * Values are sourced from themeContainerSize in @trackunit/ui-design-tokens.
+ *
+ * @see https://tailwindcss.com/docs/responsive-design#container-queries
+ */
+export declare const CONTAINER_BREAKPOINTS: { [K in keyof typeof themeContainerSize as `@${K}`]: (typeof themeContainerSize)[K]; };
+export type ContainerBreakpoint = keyof typeof CONTAINER_BREAKPOINTS;
+/**
+ * Empty cell marker for grid-template-areas.
+ *
+ * In CSS, a "." represents an empty/unnamed cell in the grid.
+ */
+export type EmptyCell = ".";
+/**
+ * A grid cell can be either an area name or an empty cell marker.
+ */
+export type GridCell<TAreaName extends string> = TAreaName | EmptyCell;
+/**
+ * A 2D grid layout where each inner array represents a row.
+ * Use "." for empty cells.
+ */
+export type GridLayout<TAreaName extends string> = Array<Array<GridCell<TAreaName>>>;
+/**
+ * Track size definition (e.g., "1fr", "min-content", "auto", "100px")
+ */
+export type TrackSize = StringWithAutocompleteOptions<"1fr" | "min-content" | "auto" | "minmax(0,1fr)">;
+/**
+ * Layout configuration with optional conditions and track sizes.
+ * This is the runtime type - compile-time validation is done by the builder.
+ */
+export type LayoutConfig<TAreaName extends string> = {
+    /** The grid layout to apply. Use "." for empty cells. */
+    layout: GridLayout<TAreaName>;
+    /** Grid row track sizes. */
+    rows?: Array<TrackSize>;
+    /** Grid column track sizes. */
+    columns?: Array<TrackSize>;
+    /** Area names that must be present for this layout to apply. */
+    when?: Array<TAreaName>;
+    /** Responsive breakpoint overrides */
+    breakpoints?: Partial<Record<ContainerBreakpoint, BreakpointLayoutConfig<TAreaName>>>;
+};
+/**
+ * Breakpoint layout override - can include different layout and/or track sizes
+ */
+export type BreakpointLayoutConfig<TAreaName extends string> = {
+    layout: GridLayout<TAreaName>;
+    rows?: Array<TrackSize>;
+    columns?: Array<TrackSize>;
+};
+/**
+ * Grid configuration output from the builder.
+ * Contains the layout structure - id is generated at render time.
+ */
+export type GridConfig<TAreaName extends string> = {
+    /** Array of area names - selectors are auto-generated as [data-slot=name] */
+    areas: ReadonlyArray<TAreaName>;
+    /** Layout configurations */
+    layouts: Array<LayoutConfig<TAreaName>>;
+};
+/**
+ * Slot props object for spreading on elements.
+ *
+ * Includes both the data-slot attribute (for CSS :has() selectors)
+ * and the style with gridArea (for grid placement).
+ */
+export type SlotProps = {
+    "data-slot": string;
+    style: {
+        gridArea: string;
+    };
+};
+/**
+ * Nested styles object for container queries and conditional selectors
+ */
+export interface NestedStyles {
+    [key: string]: CSSProperties[keyof CSSProperties] | NestedStyles | undefined;
+}
+/**
+ * CSS-in-JS compatible styles object with nested selectors
+ */
+export type GridStyles = NestedStyles;
+/**
+ * Result type from useGridAreas hook.
+ * Contains everything needed to render a GridAreas component.
+ */
+export type GridAreasResult<TAreaName extends string> = {
+    /** Props to spread on elements, keyed by area name. Includes data-slot and style.gridArea */
+    slots: Record<TAreaName, SlotProps>;
+    /** CSS string for use in a <style> tag */
+    css: string;
+    /** Data attribute to add to the container element for CSS scoping */
+    containerProps: {
+        "data-grid-id": string;
+    };
+    /** Ref callback for development-only DOM validation. Attach to the grid container element. */
+    validationRef: (element: HTMLElement | null) => void;
+};

package/src/components/GridAreas/useGridAreas.d.ts

@@ -0,0 +1,62 @@
+import { GridAreasResult, GridConfig } from "./types";
+/**
+ * React hook for creating type-safe CSS grid-template-areas with automatic :has() selector generation.
+ *
+ * Automatically generates a unique id using React's useId() hook.
+ * Returns memoized grid configuration including slots, CSS, and container props.
+ *
+ * In development mode, validates the grid configuration and logs warnings for:
+ * - Empty areas or layouts
+ * - Unknown area names in layouts or when clauses
+ * - Mismatched row/column counts
+ * - Missing when items in layouts
+ *
+ * Also returns a validationRef callback that validates DOM children when attached.
+ *
+ * @example Basic usage with builder pattern
+ * ```tsx
+ * const cardGrid = createGrid()
+ *   .areas(["icon", "info"])
+ *   .layout({ layout: [["icon", "info"]] })
+ *   .build();
+ *
+ * function MyCard() {
+ *   const gridAreas = useGridAreas(cardGrid);
+ *
+ *   return (
+ *     <GridAreas {...gridAreas}>
+ *       {(slots) => (
+ *         <>
+ *           <Icon {...slots.icon} />
+ *           <Info {...slots.info} />
+ *         </>
+ *       )}
+ *     </GridAreas>
+ *   );
+ * }
+ * ```
+ * @example Conditional layouts with row/column sizing
+ * ```tsx
+ * const cardGrid = createGrid()
+ *   .areas(["icon", "title", "description"])
+ *   .layout({ layout: [["title"]] })
+ *   .layout({
+ *     when: ["icon", "title", "description"],
+ *     layout: [
+ *       ["icon", "title"],
+ *       ["icon", "description"],
+ *     ],
+ *     rows: ["auto", "1fr"],
+ *     columns: ["48px", "1fr"],
+ *   })
+ *   .build();
+ *
+ * function Card() {
+ *   const gridAreas = useGridAreas(cardGrid);
+ *   // ...
+ * }
+ * ```
+ * @param config - Grid configuration from createGrid().build()
+ * @returns {GridAreasResult} Object with slots, css, containerProps, and validationRef to spread on GridAreas
+ */
+export declare function useGridAreas<TAreaName extends string>(config: GridConfig<TAreaName>): GridAreasResult<TAreaName>;

package/src/components/GridAreas/validateGridConfig.d.ts

@@ -0,0 +1,9 @@
+import { GridConfig } from "./types";
+/**
+ * Validates a grid configuration and returns an array of error messages.
+ * Returns an empty array if the configuration is valid.
+ *
+ * @param config - The grid configuration to validate
+ * @returns {Array<string>} Array of error message strings
+ */
+export declare function validateGridConfig<TAreaName extends string>(config: GridConfig<TAreaName>): Array<string>;

package/src/components/GridAreas/validateGridSlots.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Validates that all direct children of a grid container have proper slot props.
+ * Checks for both data-slot attribute and gridArea style, and validates they match.
+ *
+ * @param container - The grid container element
+ * @param areas - Array of valid area names
+ * @returns {Array<string>} Array of warning message strings
+ */
+export declare function validateGridSlots(container: HTMLElement, areas: ReadonlyArray<string>): Array<string>;

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

@@ -3,3 +3,8 @@ export declare const cvaMainInformationClass: (props?: ({
     hasThumbnail?: boolean | null | undefined;
 } & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
 export declare const cvaThumbnailContainer: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;
+export declare const cvaTextContainer: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;
+export declare const cvaTitleRow: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;
+export declare const cvaDescriptionRow: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;
+export declare const cvaMetaRow: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;
+export declare const cvaDetailsContainer: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;

package/src/components/PreferenceCard/PreferenceCard.d.ts

@@ -0,0 +1,70 @@
+import { VariantProps } from "@trackunit/css-class-variance-utilities";
+import { MappedOmit } from "@trackunit/shared-utils";
+import { IconName } from "@trackunit/ui-icons";
+import { ReactElement, ReactNode } from "react";
+import { CommonProps } from "../../common/CommonProps";
+import { TagProps } from "../Tag";
+import { cvaPreferenceCard } from "./PreferenceCard.variants";
+/**
+ * Grid layout configuration for the PreferenceCard content area.
+ * Defined at module level for optimal performance (runs once).
+ */
+export declare const preferenceCardGrid: import("../..").GridConfig<"icon" | "information" | "cardTag">;
+type IconDetails = {
+    type: "icon";
+    name: IconName;
+    containerClassName: string;
+};
+type ImageDetails = {
+    type: "image";
+    src: string;
+    alt: string;
+    containerClassName?: string;
+};
+export interface PreferenceCardProps extends CommonProps, MappedOmit<VariantProps<typeof cvaPreferenceCard>, "className"> {
+    /**
+     * The title of the preference card
+     */
+    title: string;
+    /**
+     * The description text for the preference card
+     */
+    description: string;
+    /**
+     * The icon or image to display in the card
+     */
+    icon?: IconDetails | ImageDetails;
+    /**
+     * Input component to display in the card (e.g., Checkbox, RadioItem, ToggleSwitch)
+     */
+    input?: ReactElement<HTMLInputElement>;
+    /**
+     * Tag displayed inline next to the title - if provided, shows the tag component
+     */
+    titleTag?: {
+        title: string;
+        color: TagProps["color"];
+    };
+    /**
+     * Tag displayed at the right end of the card - if provided, shows the tag component
+     */
+    cardTag?: {
+        title: string;
+        color: TagProps["color"];
+    };
+    /**
+     * Whether the card is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Extra content to display at the bottom of the card
+     */
+    children?: ReactNode;
+}
+/**
+ * PreferenceCard is a flexible component for displaying add-ons or settings configuration options
+ * with various states and visual treatments.
+ * It is recommended to be primarily used as an input component, as it supports checkboxes, radio buttons and toggles.
+ */
+export declare const PreferenceCard: ({ title, description, icon, input, titleTag, cardTag, disabled, className, "data-testid": dataTestId, children, }: PreferenceCardProps) => ReactNode;
+export {};

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

@@ -0,0 +1,25 @@
+/**
+ * Keeps the data-slot attribute name usage in sync with the tailwind has() selector
+ * by having them both satisfy the same template literal type containing the data-slot attribute name.
+ */
+export type StringContainingDataInputContainerAttr = `${string}input-container${string}`;
+export declare const cvaPreferenceCard: (props?: ({
+    disabled?: boolean | null | undefined;
+    clickable?: boolean | null | undefined;
+} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
+export declare const cvaInputContainer: (props?: ({
+    itemPlacement?: "center" | "start" | null | undefined;
+} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
+export declare const cvaContentContainer: (props?: ({
+    itemPlacement?: "center" | "start" | null | undefined;
+} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
+export declare const cvaTitleCard: (props?: ({
+    disabled?: boolean | null | undefined;
+} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
+export declare const cvaDescriptionCard: (props?: ({
+    disabled?: boolean | null | undefined;
+} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
+export declare const cvaIconBackground: (props?: ({
+    disabled?: boolean | null | undefined;
+} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
+export declare const cvaContentWrapper: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;

package/src/components/PreferenceCard/PreferenceCardSkeleton.d.ts

@@ -0,0 +1,25 @@
+import { ReactElement } from "react";
+/**
+ * Default property values for PreferenceCardSkeleton component.
+ */
+export declare const DEFAULT_SKELETON_PREFERENCE_CARD_PROPS: {
+    readonly hasIcon: false;
+    readonly hasTitleTag: false;
+    readonly hasCardTag: false;
+    readonly hasInput: false;
+};
+export interface PreferenceCardSkeletonProps {
+    /** Whether to show an icon skeleton */
+    hasIcon?: boolean;
+    /** Whether to show a title tag skeleton (inline with title) */
+    hasTitleTag?: boolean;
+    /** Whether to show a card tag skeleton (right-aligned tag) */
+    hasCardTag?: boolean;
+    /** Whether to show an input skeleton */
+    hasInput?: boolean;
+}
+/**
+ * Skeleton loading indicator that mimics the PreferenceCard component structure.
+ * Uses the same grid layout, spacing, and visual hierarchy as PreferenceCard.
+ */
+export declare const PreferenceCardSkeleton: ({ hasIcon, hasTitleTag, hasCardTag, hasInput, }: PreferenceCardSkeletonProps) => ReactElement;