@trackunit/react-components 1.13.10 → 1.13.11

package/index.cjs.js

@@ -14,8 +14,8 @@ var cssClassVarianceUtilities = require('@trackunit/css-class-variance-utilities
 var reactSlot = require('@radix-ui/react-slot');
 var reactRouter = require('@tanstack/react-router');
 var esToolkit = require('es-toolkit');
-var react$1 = require('@floating-ui/react');
 var tailwindMerge = require('tailwind-merge');
+var react$1 = require('@floating-ui/react');
 var reactVirtual = require('@tanstack/react-virtual');
 var reactHelmetAsync = require('react-helmet-async');
 var reactTabs = require('@radix-ui/react-tabs');
@@ -2049,6 +2049,755 @@ const ExternalLink = ({ rel = "noreferrer", target = "_blank", href, className,
     return (jsxRuntime.jsx("a", { className: cvaExternalLink({ className, color }), "data-testid": dataTestId, href: href, onClick: onClick, rel: rel, target: target, title: title, children: children }));
 };
 
+// =============================================================================
+// Builder Implementation
+// =============================================================================
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+function createGrid() {
+    return {
+        areas(areas) {
+            const layouts = [];
+            const builder = {
+                layout(config) {
+                    // At runtime, config properties are always valid arrays (error types only exist at compile-time)
+                    // We need to cast and copy readonly arrays to mutable arrays for storage
+                    // eslint-disable-next-line local-rules/no-typescript-assertion -- Error tuple types only exist at compile-time; runtime values are always valid arrays
+                    const runtimeConfig = config;
+                    layouts.push({
+                        layout: runtimeConfig.layout.map(row => [...row]),
+                        rows: runtimeConfig.rows ? [...runtimeConfig.rows] : undefined,
+                        columns: runtimeConfig.columns ? [...runtimeConfig.columns] : undefined,
+                        when: runtimeConfig.when ? [...runtimeConfig.when] : undefined,
+                        breakpoints: runtimeConfig.breakpoints,
+                    });
+                    return builder;
+                },
+                build() {
+                    return {
+                        areas: [...areas],
+                        layouts,
+                    };
+                },
+            };
+            return builder;
+        },
+    };
+}
+
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+function GridAreas({ slots, css, containerProps, validationRef, className, children, asChild = false, }) {
+    const Comp = asChild ? reactSlot.Slot : "div";
+    return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx("style", { children: css }), jsxRuntime.jsx(Comp, { ref: validationRef, ...containerProps, className: tailwindMerge.twMerge("@container grid", className), children: children(slots) })] }));
+}
+
+/**
+ * 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
+ */
+// eslint-disable-next-line local-rules/no-typescript-assertion
+const CONTAINER_BREAKPOINTS = Object.fromEntries(Object.entries(uiDesignTokens.themeContainerSize).map(([key, value]) => [`@${key}`, value]));
+
+/**
+ * Converts a 2D layout array to a CSS grid-template-areas string.
+ *
+ * @example
+ * layoutToGridTemplateAreas([['icon', 'tag'], ['info', 'info']])
+ * // Returns: "'icon tag' 'info info'"
+ */
+function layoutToGridTemplateAreas(layout) {
+    return layout.map(row => `'${row.join(" ")}'`).join(" ");
+}
+/**
+ * Converts an array of track sizes to a CSS grid-template-rows/columns string.
+ *
+ * @example
+ * tracksToGridTemplate(['min-content', '1fr', 'auto'])
+ * // Returns: "min-content 1fr auto"
+ */
+function tracksToGridTemplate(tracks) {
+    return tracks.join(" ");
+}
+/**
+ * Generates the selector for an area name.
+ * Uses [data-slot=name] format.
+ */
+function areaToSelector(area) {
+    return `[data-slot=${area}]`;
+}
+/**
+ * Generates a :has() selector for the given conditions.
+ *
+ * Areas in `when` must be present (direct children).
+ * All other areas from the full list are automatically treated as "must NOT be present".
+ *
+ * Uses direct child selector (>) for better performance and to avoid
+ * false positives with nested grids.
+ *
+ * @example
+ * generateHasSelector(['icon', 'tag'], ['icon', 'tag', 'info'])
+ * // Returns: "&:has(> [data-slot=icon]):has(> [data-slot=tag]):not(:has(> [data-slot=info]))"
+ */
+function generateHasSelector(when, allAreas) {
+    const hasParts = when.map(area => `:has(> ${areaToSelector(area)})`);
+    const notAreas = allAreas.filter(area => !when.includes(area));
+    const notParts = notAreas.map(area => `:not(:has(> ${areaToSelector(area)}))`);
+    return `&${[...hasParts, ...notParts].join("")}`;
+}
+/**
+ * Helper to safely get or initialize a nested styles object
+ */
+function getOrCreateNestedStyles(styles, key) {
+    const existing = styles[key];
+    if (typeof existing === "object") {
+        return existing;
+    }
+    const newObj = {};
+    styles[key] = newObj;
+    return newObj;
+}
+/**
+ * Type guard to check if a string is a valid container breakpoint
+ */
+function isContainerBreakpoint(value) {
+    return value in CONTAINER_BREAKPOINTS;
+}
+/**
+ * Creates a typed slots object from an array of area names.
+ *
+ * Each slot contains a data-slot attribute and gridArea style.
+ */
+function createSlots(areas) {
+    // eslint-disable-next-line local-rules/no-typescript-assertion -- Object.fromEntries loses key type information
+    return Object.fromEntries(areas.map(area => [area, { "data-slot": area, style: { gridArea: area } }]));
+}
+/**
+ * Converts a camelCase CSS property name to kebab-case.
+ *
+ * @example
+ * camelToKebab('gridTemplateAreas') // 'grid-template-areas'
+ */
+function camelToKebab(str) {
+    return str.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`);
+}
+/**
+ * Converts a NestedStyles object to CSS declarations string.
+ */
+function stylesToCssDeclarations(styles) {
+    const declarations = [];
+    for (const key of Object.keys(styles)) {
+        const value = styles[key];
+        // Only include non-nested properties (not starting with & or @)
+        if (!key.startsWith("&") && !key.startsWith("@") && value !== undefined && typeof value !== "object") {
+            declarations.push(`${camelToKebab(key)}: ${value};`);
+        }
+    }
+    return declarations.join(" ");
+}
+/**
+ * Recursively converts a GridStyles object to a CSS string.
+ */
+function stylesToCss(styles, parentSelector, indent = "") {
+    const lines = [];
+    // Collect base declarations for this level
+    const baseDeclarations = stylesToCssDeclarations(styles);
+    if (baseDeclarations.length > 0) {
+        lines.push(`${indent}${parentSelector} { ${baseDeclarations} }`);
+    }
+    // Process nested selectors
+    for (const key of Object.keys(styles)) {
+        const value = styles[key];
+        if (typeof value === "object") {
+            if (key.startsWith("&")) {
+                // Pseudo-selector: replace & with parent selector
+                const nestedSelector = key.replace(/^&/, parentSelector);
+                lines.push(stylesToCss(value, nestedSelector, indent));
+            }
+            else if (key.startsWith("@")) {
+                // At-rule (like @container): wrap in the at-rule
+                const nestedCss = stylesToCss(value, parentSelector, indent + "  ");
+                lines.push(`${indent}${key} {\n${nestedCss}\n${indent}}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Applies layout styles (areas, rows, columns) to a styles object.
+ *
+ * For breakpoints (isBreakpoint=true), rows/columns are always explicitly set
+ * to prevent base layout values from cascading. This makes breakpoints self-contained.
+ */
+function applyLayoutStyles({ targetStyles, layout, rows, columns, isBreakpoint = false, }) {
+    targetStyles.gridTemplateAreas = layoutToGridTemplateAreas(layout);
+    if (rows !== undefined && rows.length > 0) {
+        targetStyles.gridTemplateRows = tracksToGridTemplate(rows);
+    }
+    else if (isBreakpoint) {
+        // Breakpoints are self-contained - reset to prevent base cascade
+        targetStyles.gridTemplateRows = "none";
+    }
+    if (columns !== undefined && columns.length > 0) {
+        targetStyles.gridTemplateColumns = tracksToGridTemplate(columns);
+    }
+    else if (isBreakpoint) {
+        // Breakpoints are self-contained - reset to prevent base cascade
+        targetStyles.gridTemplateColumns = "none";
+    }
+}
+/**
+ * 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
+ */
+function generateCss(id, config) {
+    const { areas, layouts } = config;
+    // Build styles object
+    const styles = {};
+    for (const layoutDef of layouts) {
+        const { layout, rows, columns, when = [], breakpoints = {} } = layoutDef;
+        // No conditions - this is a base layout
+        if (when.length === 0) {
+            applyLayoutStyles({ targetStyles: styles, layout, rows, columns });
+            // Add breakpoint overrides for base layout
+            for (const breakpoint of Object.keys(breakpoints)) {
+                if (isContainerBreakpoint(breakpoint)) {
+                    const breakpointConfig = breakpoints[breakpoint];
+                    if (breakpointConfig !== undefined) {
+                        const containerQuery = `@container (min-width: ${CONTAINER_BREAKPOINTS[breakpoint]})`;
+                        const nestedStyles = getOrCreateNestedStyles(styles, containerQuery);
+                        applyLayoutStyles({
+                            targetStyles: nestedStyles,
+                            layout: breakpointConfig.layout,
+                            rows: breakpointConfig.rows,
+                            columns: breakpointConfig.columns,
+                            isBreakpoint: true,
+                        });
+                    }
+                }
+            }
+        }
+        else {
+            // Conditional layout - generate :has() selector
+            // Areas not in `when` are automatically treated as "must NOT be present"
+            const selector = generateHasSelector(when, areas);
+            const conditionalStyles = getOrCreateNestedStyles(styles, selector);
+            applyLayoutStyles({ targetStyles: conditionalStyles, layout, rows, columns });
+            // Add breakpoint overrides for conditional layout
+            for (const breakpoint of Object.keys(breakpoints)) {
+                if (isContainerBreakpoint(breakpoint)) {
+                    const breakpointConfig = breakpoints[breakpoint];
+                    if (breakpointConfig !== undefined) {
+                        const containerQuery = `@container (min-width: ${CONTAINER_BREAKPOINTS[breakpoint]})`;
+                        const containerStyles = getOrCreateNestedStyles(styles, containerQuery);
+                        const nestedConditional = getOrCreateNestedStyles(containerStyles, selector);
+                        applyLayoutStyles({
+                            targetStyles: nestedConditional,
+                            layout: breakpointConfig.layout,
+                            rows: breakpointConfig.rows,
+                            columns: breakpointConfig.columns,
+                            isBreakpoint: true,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // Generate CSS string with the container selector
+    const containerSelector = `[data-grid-id="${id}"]`;
+    return stylesToCss(styles, containerSelector);
+}
+
+/**
+ * Creates a normalized key from a when-clause for comparison.
+ * Sorts the array alphabetically and joins with a delimiter.
+ * Returns empty string for undefined/empty when-clauses.
+ *
+ * @param when - The when-clause array
+ * @returns {string} A normalized string key for comparison
+ */
+function normalizeWhenClause(when) {
+    if (when === undefined || when.length === 0) {
+        return "";
+    }
+    return [...when].sort().join("\0");
+}
+/**
+ * Validates a grid layout's dimensions against rows/columns arrays.
+ *
+ * @param options - Validation options
+ * @param options.layout - The 2D grid layout
+ * @param options.rows - Optional row track sizes
+ * @param options.columns - Optional column track sizes
+ * @param options.context - Context string for error messages
+ * @returns {Array<string>} Array of error messages
+ */
+function validateLayoutDimensions({ layout, rows, columns, context }) {
+    const errors = [];
+    const firstRow = layout[0];
+    if (firstRow === undefined) {
+        errors.push(`${context}: Layout has no rows.`);
+        return errors;
+    }
+    const rowCount = layout.length;
+    const firstRowLength = firstRow.length;
+    // Check rows array length
+    if (rows !== undefined && rows.length !== rowCount) {
+        errors.push(`${context}: rows array length (${rows.length}) doesn't match layout row count (${rowCount}).`);
+    }
+    // Check columns array length
+    if (columns !== undefined && columns.length !== firstRowLength) {
+        errors.push(`${context}: columns array length (${columns.length}) doesn't match layout column count (${firstRowLength}).`);
+    }
+    // Check for inconsistent column counts across rows
+    for (let i = 1; i < layout.length; i++) {
+        const row = layout[i];
+        if (row === undefined) {
+            continue;
+        }
+        if (row.length !== firstRowLength) {
+            errors.push(`${context}: Row ${i} has ${row.length} columns, but row 0 has ${firstRowLength}. All rows must have the same number of columns.`);
+        }
+    }
+    return errors;
+}
+/**
+ * Validates that all cell names in a layout are valid area names.
+ *
+ * @param options - Validation options
+ * @param options.layout - The 2D grid layout
+ * @param options.areas - Valid area names
+ * @param options.context - Context string for error messages
+ * @returns {Array<string>} Array of error messages
+ */
+function validateLayoutAreaNames({ layout, areas, context }) {
+    const errors = [];
+    const areaSet = new Set(areas);
+    for (let rowIndex = 0; rowIndex < layout.length; rowIndex++) {
+        const row = layout[rowIndex];
+        if (row === undefined) {
+            continue;
+        }
+        for (let colIndex = 0; colIndex < row.length; colIndex++) {
+            const cell = row[colIndex];
+            if (cell === undefined) {
+                continue;
+            }
+            if (cell !== "." && !areaSet.has(cell)) {
+                errors.push(`${context}: Unknown area name "${cell}" at row ${rowIndex}, column ${colIndex}. Valid areas are: ${areas.join(", ")}.`);
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Validates that all items in a 'when' array are valid area names and appear in the layout.
+ *
+ * @param options - Validation options
+ * @param options.when - Optional when-clause array
+ * @param options.layout - The 2D grid layout
+ * @param options.areas - Valid area names
+ * @param options.context - Context string for error messages
+ * @returns {Array<string>} Array of error messages
+ */
+function validateWhenClause({ when, layout, areas, context }) {
+    if (when === undefined || when.length === 0) {
+        return [];
+    }
+    const errors = [];
+    const areaSet = new Set(areas);
+    const layoutCells = new Set(layout.flat());
+    for (const item of when) {
+        if (!areaSet.has(item)) {
+            errors.push(`${context}: Unknown area "${item}" in 'when' clause. Valid areas are: ${areas.join(", ")}.`);
+        }
+        else if (!layoutCells.has(item)) {
+            errors.push(`${context}: Area "${item}" is in 'when' clause but doesn't appear in the layout. The layout will never match this condition.`);
+        }
+    }
+    return errors;
+}
+/**
+ * Validates breakpoint configurations.
+ *
+ * @param options - Validation options
+ * @param options.breakpoints - Optional breakpoint config
+ * @param options.areas - Valid area names
+ * @param options.layoutIndex - Index of the parent layout for error messages
+ * @returns {Array<string>} Array of error messages
+ */
+function validateBreakpoints({ breakpoints, areas, layoutIndex }) {
+    if (breakpoints === undefined) {
+        return [];
+    }
+    const errors = [];
+    for (const [breakpoint, config] of Object.entries(breakpoints)) {
+        const context = `Layout ${layoutIndex}, breakpoint "${breakpoint}"`;
+        errors.push(...validateLayoutDimensions({ layout: config.layout, rows: config.rows, columns: config.columns, context }));
+        errors.push(...validateLayoutAreaNames({ layout: config.layout, areas, context }));
+    }
+    return errors;
+}
+/**
+ * Validates that there are no duplicate 'when' clauses across layouts.
+ * Two when-clauses are considered duplicates if they contain the same set of areas (order doesn't matter).
+ *
+ * @param layouts - Array of layout configurations
+ * @returns {Array<string>} Array of warning messages
+ */
+function validateDuplicateWhenClauses(layouts) {
+    const warnings = [];
+    const seenWhenClauses = new Map();
+    for (let i = 0; i < layouts.length; i++) {
+        const layoutConfig = layouts[i];
+        if (layoutConfig === undefined) {
+            continue;
+        }
+        const whenKey = normalizeWhenClause(layoutConfig.when);
+        // Skip layouts without when-clauses (base layouts)
+        if (whenKey === "") {
+            continue;
+        }
+        const previousIndex = seenWhenClauses.get(whenKey);
+        if (previousIndex !== undefined) {
+            const whenDisplay = layoutConfig.when?.join(", ") ?? "";
+            warnings.push(`Layout ${i} has the same 'when' clause as Layout ${previousIndex}: [${whenDisplay}]. ` +
+                `Layout ${i} will override Layout ${previousIndex} since it appears later.`);
+        }
+        seenWhenClauses.set(whenKey, i);
+    }
+    return warnings;
+}
+/**
+ * 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
+ */
+function validateGridConfig(config) {
+    const errors = [];
+    const { areas, layouts } = config;
+    // Validate areas array
+    if (areas.length === 0) {
+        errors.push("Config has no areas defined. Use .areas([...]) to define at least one area.");
+    }
+    // Validate layouts array
+    if (layouts.length === 0) {
+        errors.push("Config has no layouts defined. Use .layout({...}) to define at least one layout.");
+    }
+    // Check for duplicate when-clauses
+    errors.push(...validateDuplicateWhenClauses(layouts));
+    // Validate each layout
+    for (let i = 0; i < layouts.length; i++) {
+        const layoutConfig = layouts[i];
+        if (layoutConfig === undefined) {
+            continue;
+        }
+        const context = `Layout ${i}`;
+        errors.push(...validateLayoutDimensions({
+            layout: layoutConfig.layout,
+            rows: layoutConfig.rows,
+            columns: layoutConfig.columns,
+            context,
+        }));
+        errors.push(...validateLayoutAreaNames({ layout: layoutConfig.layout, areas, context }));
+        errors.push(...validateWhenClause({ when: layoutConfig.when, layout: layoutConfig.layout, areas, context }));
+        errors.push(...validateBreakpoints({ breakpoints: layoutConfig.breakpoints, areas, layoutIndex: i }));
+    }
+    return errors;
+}
+
+/**
+ * Extracts the gridArea value from an element's inline style.
+ *
+ * @param element - The element to check
+ * @returns {string | null} The gridArea value or null if not set
+ */
+function getGridAreaStyle(element) {
+    if (element instanceof HTMLElement) {
+        const gridArea = element.style.gridArea;
+        return gridArea !== "" ? gridArea : null;
+    }
+    return null;
+}
+/**
+ * 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
+ */
+function validateGridSlots(container, areas) {
+    const warnings = [];
+    const areaSet = new Set(areas);
+    const unwiredChildren = [];
+    const unknownSlots = [];
+    const partialSlots = [];
+    const mismatchedSlots = [];
+    let childIndex = 0;
+    for (const child of Array.from(container.children)) {
+        const dataSlot = child.getAttribute("data-slot");
+        const gridArea = getGridAreaStyle(child);
+        const tagName = child.tagName.toLowerCase();
+        const hasDataSlot = dataSlot !== null;
+        const hasGridArea = gridArea !== null;
+        if (!hasDataSlot && !hasGridArea) {
+            // Completely missing slot props
+            unwiredChildren.push({ tagName, index: childIndex, dataSlot, gridArea });
+        }
+        else if (hasDataSlot && !hasGridArea) {
+            // Has data-slot but missing gridArea style
+            partialSlots.push({ tagName, index: childIndex, dataSlot, gridArea });
+        }
+        else if (!hasDataSlot && hasGridArea) {
+            // Has gridArea but missing data-slot
+            partialSlots.push({ tagName, index: childIndex, dataSlot, gridArea });
+        }
+        else if (hasDataSlot && hasGridArea && dataSlot !== gridArea) {
+            // Both present but values don't match
+            mismatchedSlots.push({ tagName, index: childIndex, dataSlot, gridArea });
+        }
+        else if (hasDataSlot && !areaSet.has(dataSlot)) {
+            // Valid slot props but unknown area name
+            unknownSlots.push({ tagName, index: childIndex, dataSlot, gridArea });
+        }
+        childIndex++;
+    }
+    if (unwiredChildren.length > 0) {
+        const details = unwiredChildren.map(({ tagName, index }) => `  - <${tagName}> at index ${index}`).join("\n");
+        warnings.push(`Found ${unwiredChildren.length} child element(s) without slot props:\n${details}\n` +
+            `Hint: Did you forget to spread {...slots.name} on these elements?`);
+    }
+    if (partialSlots.length > 0) {
+        const details = partialSlots
+            .map(({ tagName, index, dataSlot, gridArea }) => {
+            const has = dataSlot !== null ? `data-slot="${dataSlot}"` : `style.gridArea="${gridArea}"`;
+            const missing = dataSlot !== null ? "style.gridArea" : "data-slot";
+            return `  - <${tagName}> at index ${index} has ${has} but missing ${missing}`;
+        })
+            .join("\n");
+        warnings.push(`Found ${partialSlots.length} child element(s) with incomplete slot props:\n${details}\n` +
+            `Hint: Make sure to spread the full slot props {...slots.name} instead of setting attributes manually. And make sure the child takes a style prop.`);
+    }
+    if (mismatchedSlots.length > 0) {
+        const details = mismatchedSlots
+            .map(({ tagName, index, dataSlot, gridArea }) => `  - <${tagName}> at index ${index} has data-slot="${dataSlot}" but style.gridArea="${gridArea}"`)
+            .join("\n");
+        warnings.push(`Found ${mismatchedSlots.length} child element(s) with mismatched slot values:\n${details}\n` +
+            `Hint: The data-slot attribute and style.gridArea should have the same value. Use {...slots.name} to ensure consistency.`);
+    }
+    if (unknownSlots.length > 0) {
+        const details = unknownSlots
+            .map(({ dataSlot, tagName, index }) => `  - <${tagName}> at index ${index} has data-slot="${dataSlot}"`)
+            .join("\n");
+        warnings.push(`Found ${unknownSlots.length} child element(s) with unknown slot names:\n${details}\n` +
+            `Valid slot names are: ${areas.join(", ")}.`);
+    }
+    return warnings;
+}
+
+/**
+ * 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
+ */
+function useGridAreas(config) {
+    const id = react.useId();
+    // Ref callback for DOM validation (runs once when element mounts)
+    const validationRef = react.useCallback((element) => {
+        if (process.env.NODE_ENV !== "development" || element === null) {
+            return;
+        }
+        const warnings = validateGridSlots(element, config.areas);
+        for (const warning of warnings) {
+            // eslint-disable-next-line no-console
+            console.warn(`GridAreas: ${warning}`);
+        }
+    }, [config.areas]);
+    return react.useMemo(() => {
+        // Config validation (dev only)
+        if (process.env.NODE_ENV === "development") {
+            const errors = validateGridConfig(config);
+            for (const error of errors) {
+                // eslint-disable-next-line no-console
+                console.warn(`useGridAreas: ${error}`);
+            }
+        }
+        return {
+            slots: createSlots(config.areas),
+            css: generateCss(id, config),
+            containerProps: { "data-grid-id": id },
+            validationRef,
+        };
+    }, [id, config, validationRef]);
+}
+
 const cvaHighlight = cssClassVarianceUtilities.cvaMerge([
     "inline-flex",
     "justify-center",
@@ -3103,7 +3852,7 @@ const Indicator = ({ "data-testid": dataTestId, icon, label, color = "unknown",
  *
  * @returns tailwind class names on the basis on the provided props.
  */
-const cvaInteractableItem = cssClassVarianceUtilities.cvaMerge("", {
+const cvaInteractableItem = cssClassVarianceUtilities.cvaMerge(["transition-colors", "duration-100", "ease-in-out"], {
     variants: {
         cursor: {
             pointer: "cursor-pointer",
@@ -3410,6 +4159,124 @@ const cvaListItem$1 = cssClassVarianceUtilities.cvaMerge(["absolute", "top-0", "
     },
 });
 
+const cvaSkeleton = cssClassVarianceUtilities.cvaMerge([
+    "relative",
+    "overflow-hidden",
+    "rounded-lg",
+    // Gradient background
+    "bg-gradient-to-r",
+    "from-gray-200/80",
+    "via-gray-300/60",
+    "to-gray-200/80",
+    // Pulse animation
+    "animate-pulse",
+    // Shimmer overlay
+    "before:absolute",
+    "before:inset-0",
+    "before:bg-gradient-to-r",
+    "before:from-transparent",
+    "before:via-white/50",
+    "before:to-transparent",
+    "before:opacity-0",
+    "before:animate-pulse",
+    // Smooth transitions for accessibility
+    "transition-all",
+    "duration-300",
+    "ease-in-out",
+]);
+
+const VALID_SIZE_KEYS = [
+    "xs",
+    "sm",
+    "base",
+    "lg",
+    "xl",
+    "2xl",
+    "3xl",
+    "4xl",
+    "5xl",
+    "6xl",
+    "7xl",
+    "8xl",
+    "9xl",
+];
+/**
+ * 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
+ */
+const extractSizeKey = (value) => {
+    if (!value.startsWith("text-")) {
+        return null;
+    }
+    const sizeKey = value.replace("text-", "");
+    return VALID_SIZE_KEYS.find(key => key === sizeKey) ?? 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
+ */
+const getHeightValue = (height, variant) => {
+    if (typeof height === "number") {
+        return `${height}px`;
+    }
+    const sizeKey = extractSizeKey(height);
+    if (sizeKey) {
+        // Text variant: use font-size × 0.7 to approximate cap-height
+        // Block variant: use full line-height (for when text size keys are passed to block variant)
+        return variant === "text" ? `calc(var(--font-size-${sizeKey}) * 0.7)` : `var(--line-height-${sizeKey})`;
+    }
+    return height;
+};
+/**
+ * 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
+ */
+const getMarginValue = (height) => {
+    if (typeof height === "string") {
+        const sizeKey = extractSizeKey(height);
+        if (sizeKey) {
+            // margin = (line-height - cap-height) / 2
+            // cap-height = font-size × 0.7
+            // For large text sizes, this may be negative, which matches how actual text extends beyond its line-height box
+            return `calc((var(--line-height-${sizeKey}) - var(--font-size-${sizeKey}) * 0.7) / 2)`;
+        }
+    }
+    return "0";
+};
+/**
+ * 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.
+ */
+const Skeleton = react.memo((props) => {
+    const { width = "100%", className, "data-testid": dataTestId, children } = props;
+    const variant = props.variant ?? "text";
+    const height = props.height ?? (variant === "text" ? "text-base" : 16);
+    const flexibleWidth = props.flexibleWidth ?? variant === "text";
+    const widthValue = typeof width === "number" ? `${width}px` : width;
+    const isTextVariant = variant === "text";
+    const heightValue = getHeightValue(height, variant);
+    const marginValue = isTextVariant ? getMarginValue(height) : undefined;
+    return (jsxRuntime.jsx("div", { "aria-label": "Loading", className: cvaSkeleton({ className }), "data-testid": dataTestId, role: "status", style: {
+            width: flexibleWidth ? "100%" : widthValue,
+            maxWidth: flexibleWidth ? widthValue : undefined,
+            height: heightValue,
+            marginTop: marginValue,
+            marginBottom: marginValue,
+        }, children: children }));
+});
+Skeleton.displayName = "Skeleton";
+
 const cvaListItem = cssClassVarianceUtilities.cvaMerge(["py-3", "px-4", "min-h-14", "w-full", "flex", "justify-between", "items-center"]);
 const cvaMainInformationClass = cssClassVarianceUtilities.cvaMerge(["grid", "items-center", "text-sm", "gap-2"], {
     variants: {
@@ -3428,6 +4295,11 @@ const cvaThumbnailContainer = cssClassVarianceUtilities.cvaMerge([
     "overflow-hidden",
     "rounded-md",
 ]);
+const cvaTextContainer = cssClassVarianceUtilities.cvaMerge(["grid-rows-min-fr", "grid", "items-center", "text-sm"]);
+const cvaTitleRow = cssClassVarianceUtilities.cvaMerge(["gap-responsive-space-sm", "flex", "w-full", "min-w-0", "items-center", "text-sm"]);
+const cvaDescriptionRow = cssClassVarianceUtilities.cvaMerge(["gap-responsive-space-sm", "flex", "w-full", "min-w-0", "items-center"]);
+const cvaMetaRow = cssClassVarianceUtilities.cvaMerge(["gap-responsive-space-sm", "flex", "w-full", "min-w-0", "items-center", "pt-0.5"]);
+const cvaDetailsContainer = cssClassVarianceUtilities.cvaMerge(["flex", "items-center", "gap-0.5", "text-nowrap", "pl-2"]);
 
 /**
  * Default property values for ListItemSkeleton component.
@@ -3453,7 +4325,7 @@ const ListItemSkeleton = ({ hasThumbnail = DEFAULT_SKELETON_LIST_ITEM_PROPS.hasT
             details: getResponsiveRandomWidthPercentage({ min: 25, max: 45 }),
         };
     }, []);
-    return (jsxRuntime.jsxs("div", { className: cvaListItem({ className: "w-full" }), children: [jsxRuntime.jsxs("div", { className: cvaMainInformationClass({ hasThumbnail, className: "w-full" }), children: [hasThumbnail ? (jsxRuntime.jsx("div", { className: cvaThumbnailContainer({ className: "bg-gray-200" }), children: jsxRuntime.jsx("div", { className: tailwindMerge.twMerge("bg-gray-300", thumbnailShape === "circle" ? "rounded-full" : "rounded"), style: { width: 20, height: 20 } }) })) : null, jsxRuntime.jsxs("div", { className: "grid-rows-min-fr grid w-full items-center gap-1 text-sm", children: [jsxRuntime.jsx(SkeletonLines, { height: "0.875em", lines: 1, width: lineWidths.title }), hasDescription ? jsxRuntime.jsx(SkeletonLines, { height: "0.75em", lines: 1, width: lineWidths.description }) : null, hasMeta ? jsxRuntime.jsx(SkeletonLines, { height: "0.75em", lines: 1, width: lineWidths.meta }) : null] })] }), hasDetails ? (jsxRuntime.jsx("div", { className: "pl-2 text-sm", children: jsxRuntime.jsx(SkeletonLines, { height: "0.875em", lines: 1, width: lineWidths.details }) })) : null] }));
+    return (jsxRuntime.jsxs("div", { className: cvaListItem({ className: "w-full" }), children: [jsxRuntime.jsxs("div", { className: cvaMainInformationClass({ hasThumbnail, className: "w-full" }), children: [hasThumbnail ? (jsxRuntime.jsx("div", { className: cvaThumbnailContainer({ className: "bg-gray-200" }), children: jsxRuntime.jsx("div", { className: tailwindMerge.twMerge("bg-gray-300", thumbnailShape === "circle" ? "rounded-full" : "rounded"), style: { width: 20, height: 20 } }) })) : null, jsxRuntime.jsxs("div", { className: cvaTextContainer(), children: [jsxRuntime.jsx("div", { className: cvaTitleRow(), children: jsxRuntime.jsx(Skeleton, { height: "text-sm", width: lineWidths.title }) }), hasDescription ? (jsxRuntime.jsx("div", { className: cvaDescriptionRow(), children: jsxRuntime.jsx(Skeleton, { height: "text-xs", width: lineWidths.description }) })) : null, hasMeta ? (jsxRuntime.jsx("div", { className: cvaMetaRow(), children: jsxRuntime.jsx(Skeleton, { height: "text-xs", width: lineWidths.meta }) })) : null] })] }), hasDetails ? (jsxRuntime.jsx("div", { className: cvaDetailsContainer(), children: jsxRuntime.jsx(Skeleton, { height: "text-sm", width: lineWidths.details }) })) : null] }));
 };
 
 /**
@@ -3940,13 +4812,13 @@ const ListItem = ({ className, "data-testid": dataTestId, onClick, details, titl
     const interactableItemClass = onClick ? tailwindMerge.twMerge(baseClass, cvaInteractableItem({ cursor: "pointer" })) : baseClass;
     return (jsxRuntime.jsxs("li", { className: interactableItemClass, "data-testid": dataTestId, onClick: onClick, ...rest, children: [jsxRuntime.jsxs("div", { className: cvaMainInformationClass({ hasThumbnail: !!thumbnail }), children: [thumbnail ? (jsxRuntime.jsx("div", { className: cvaThumbnailContainer({
                             className: `text-${thumbnailColor} bg-${thumbnailBackground}`,
-                        }), children: thumbnail })) : null, jsxRuntime.jsxs("div", { className: "grid-rows-min-fr grid items-center text-sm", children: [jsxRuntime.jsx("div", { className: "gap-responsive-space-sm flex w-full min-w-0 items-center text-sm", children: typeof title === "string" ? (jsxRuntime.jsx(Text, { className: "truncate", "data-testid": dataTestId ? `${dataTestId}-title` : undefined, weight: "bold", children: title })) : (react.cloneElement(title, {
+                        }), children: thumbnail })) : null, jsxRuntime.jsxs("div", { className: cvaTextContainer(), children: [jsxRuntime.jsx("div", { className: cvaTitleRow(), children: typeof title === "string" ? (jsxRuntime.jsx(Text, { className: "truncate", "data-testid": dataTestId ? `${dataTestId}-title` : undefined, weight: "bold", children: title })) : (react.cloneElement(title, {
                                     className: tailwindMerge.twMerge(title.props.className, "neutral-900 text-sm font-medium truncate"),
                                     "data-testid": !title.props["data-testid"] && dataTestId ? `${dataTestId}-title` : undefined,
-                                })) }), description !== undefined && description !== "" ? (jsxRuntime.jsx("div", { className: "gap-responsive-space-sm flex w-full min-w-0 items-center", children: typeof description === "string" ? (jsxRuntime.jsx(Text, { className: "truncate text-xs text-neutral-500", "data-testid": dataTestId ? `${dataTestId}-description` : undefined, weight: "bold", children: description })) : (react.cloneElement(description, {
+                                })) }), description !== undefined && description !== "" ? (jsxRuntime.jsx("div", { className: cvaDescriptionRow(), children: typeof description === "string" ? (jsxRuntime.jsx(Text, { className: "truncate text-xs text-neutral-500", "data-testid": dataTestId ? `${dataTestId}-description` : undefined, weight: "bold", children: description })) : (react.cloneElement(description, {
                                     className: tailwindMerge.twMerge(description.props.className, "text-neutral-500 text-xs font-medium truncate"),
                                     "data-testid": !description.props["data-testid"] && dataTestId ? `${dataTestId}-description` : undefined,
-                                })) })) : null, meta ? (jsxRuntime.jsx("div", { className: "gap-responsive-space-sm flex w-full min-w-0 items-center pt-0.5", children: jsxRuntime.jsx(Text, { className: "truncate text-xs text-neutral-400", "data-testid": dataTestId ? `${dataTestId}-meta` : undefined, weight: "bold", children: meta }) })) : null] })] }), jsxRuntime.jsxs("div", { className: "flex items-center gap-0.5 text-nowrap pl-2", children: [details, onClick ? jsxRuntime.jsx(Icon, { color: "neutral", name: "ChevronRight", size: "medium" }) : null] })] }));
+                                })) })) : null, meta ? (jsxRuntime.jsx("div", { className: cvaMetaRow(), children: jsxRuntime.jsx(Text, { className: "truncate text-xs text-neutral-400", "data-testid": dataTestId ? `${dataTestId}-meta` : undefined, weight: "bold", children: meta }) })) : null] })] }), jsxRuntime.jsxs("div", { className: cvaDetailsContainer(), children: [details, onClick ? jsxRuntime.jsx(Icon, { color: "neutral", name: "ChevronRight", size: "medium" }) : null] })] }));
 };
 
 // Height constants (in pixels) - based on ListItem.variants.ts styling
@@ -4642,6 +5514,216 @@ const Polygon = ({ points, size, color = "black", opaque = true, className, "dat
 };
 const normalize = ({ value, min, max, size }) => ((value - min) / (max - min)) * size;
 
+const cvaPreferenceCard = cssClassVarianceUtilities.cvaMerge([
+    "rounded-lg",
+    "border",
+    "border-neutral-200",
+    "bg-white",
+    "w-full",
+    "grid",
+    "gap-y-2",
+    "@container",
+    "grid-rows-1",
+    "grid-cols-1",
+    "[&:has([data-slot=input-container])]:grid-cols-min-fr", // When the input container is present, the grid columns are set to min-fr
+    "[&:has([data-slot=input-container]_:focus-visible)]:outline-native",
+], {
+    variants: {
+        disabled: {
+            true: "",
+            false: "",
+        },
+        clickable: {
+            true: ["cursor-pointer"],
+            false: "",
+        },
+    },
+    compoundVariants: [
+        {
+            disabled: true,
+            clickable: true,
+            class: "cursor-not-allowed",
+        },
+    ],
+    defaultVariants: {
+        disabled: false,
+        clickable: false,
+    },
+});
+const cvaInputContainer = cssClassVarianceUtilities.cvaMerge(["flex", "p-4", "rounded-l-lg", "border", "border-transparent", "bg-neutral-50", "border-r-neutral-200"], {
+    variants: {
+        itemPlacement: {
+            center: "items-center",
+            start: "items-start",
+        },
+    },
+    defaultVariants: {
+        itemPlacement: "start",
+    },
+});
+const cvaContentContainer = cssClassVarianceUtilities.cvaMerge([
+    "grid",
+    "gap-x-3",
+    //* Grid template areas are applied with GridAreas component)
+], {
+    variants: {
+        itemPlacement: {
+            center: "items-center",
+            start: "items-start",
+        },
+    },
+    defaultVariants: {
+        itemPlacement: "start",
+    },
+});
+const cvaTitleCard = cssClassVarianceUtilities.cvaMerge(["min-w-0", "overflow-hidden", "text-ellipsis", "whitespace-nowrap"], {
+    variants: {
+        disabled: {
+            true: "text-neutral-400",
+            false: "text-neutral-900",
+        },
+    },
+    defaultVariants: {
+        disabled: false,
+    },
+});
+const cvaDescriptionCard = cssClassVarianceUtilities.cvaMerge([], {
+    variants: {
+        disabled: {
+            true: "text-neutral-400",
+            false: "text-neutral-600",
+        },
+    },
+    defaultVariants: {
+        disabled: false,
+    },
+});
+const cvaIconBackground = cssClassVarianceUtilities.cvaMerge(["flex", "h-8", "w-8", "items-center", "justify-center", "rounded-md", "shrink-0"], {
+    variants: {
+        disabled: {
+            true: "bg-neutral-200",
+            false: "",
+        },
+    },
+    defaultVariants: {
+        disabled: false,
+    },
+});
+const cvaContentWrapper = cssClassVarianceUtilities.cvaMerge(["grid", "gap-2", "px-4", "py-3"]);
+
+const CENTER_INPUT_HEIGHT_THRESHOLD = 92;
+/**
+ * Grid layout configuration for the PreferenceCard content area.
+ * Defined at module level for optimal performance (runs once).
+ */
+const preferenceCardGrid = createGrid()
+    .areas(["icon", "information", "cardTag"])
+    // Base: just information
+    .layout({ layout: [["information"]] })
+    // When all three: stacked on mobile, inline on @sm
+    .layout({
+    when: ["icon", "information", "cardTag"],
+    layout: [
+        ["icon", "cardTag"],
+        ["information", "information"],
+    ],
+    rows: ["min-content", "1fr"],
+    columns: ["min-content", "auto"],
+    breakpoints: {
+        "@sm": {
+            layout: [["icon", "information", "cardTag"]],
+            columns: ["min-content", "1fr", "auto"],
+        },
+    },
+})
+    // Icon and information (no cardTag)
+    .layout({
+    when: ["icon", "information"],
+    layout: [["icon", "information"]],
+    columns: ["min-content", "auto"],
+})
+    // Information and cardTag (no icon)
+    .layout({
+    when: ["cardTag", "information"],
+    layout: [["information", "cardTag"]],
+})
+    .build();
+/**
+ * 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.
+ */
+const PreferenceCard = ({ title, description, icon, input, titleTag, cardTag, disabled = false, className, "data-testid": dataTestId, children, }) => {
+    const { ref, geometry } = useMeasure();
+    const gridAreas = useGridAreas(preferenceCardGrid);
+    return (jsxRuntime.jsxs("div", { className: cvaPreferenceCard({
+            disabled,
+            className,
+        }), "data-testid": dataTestId, ref: ref, children: [input ? (jsxRuntime.jsx("label", { className: tailwindMerge.twMerge(cvaInputContainer({
+                    itemPlacement: geometry && geometry.height < CENTER_INPUT_HEIGHT_THRESHOLD ? "center" : "start",
+                }), cvaInteractableItem({
+                    disabled,
+                    selection: "auto",
+                    focus: "unfocused",
+                })), "data-slot": "input-container", children: react.cloneElement(input, disabled ? { disabled: true } : {}) })) : null, jsxRuntime.jsxs("div", { className: cvaContentWrapper(), children: [jsxRuntime.jsx(GridAreas, { ...gridAreas, className: cvaContentContainer({
+                            itemPlacement: geometry && geometry.height < CENTER_INPUT_HEIGHT_THRESHOLD ? "center" : "start",
+                        }), children: slots => (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx(IconContent, { ...slots.icon, disabled: disabled, icon: icon }), jsxRuntime.jsx(InformationContent, { ...slots.information, description: description, disabled: disabled, title: title, titleTag: titleTag }), cardTag ? (jsxRuntime.jsx("div", { ...slots.cardTag, className: "justify-self-end", children: jsxRuntime.jsx(Tag, { color: disabled ? "unknown" : cardTag.color, size: "medium", children: cardTag.title }) })) : null] })) }), Boolean(children) ? jsxRuntime.jsx("div", { "data-slot": "children", children: children }) : null] })] }));
+};
+const IconContent = ({ icon, disabled, ...rest }) => {
+    if (icon?.type === "icon") {
+        return (jsxRuntime.jsx("div", { ...rest, className: tailwindMerge.twMerge(cvaIconBackground({ disabled }), disabled ? "" : icon.containerClassName), children: jsxRuntime.jsx(Icon, { color: "white", name: icon.name, size: "small", type: "solid" }) }));
+    }
+    if (icon?.type === "image") {
+        return (jsxRuntime.jsx("div", { ...rest, className: tailwindMerge.twMerge(cvaIconBackground({ disabled }), disabled ? "" : icon.containerClassName || "bg-gray-100"), children: jsxRuntime.jsx("img", { alt: icon.alt, className: "aspect-square h-8 w-8 rounded-md border border-neutral-200 object-contain", src: icon.src }) }));
+    }
+    return null;
+};
+const InformationContent = ({ title, description, titleTag, disabled = false, className, ...rest }) => (jsxRuntime.jsxs("div", { ...rest, className: tailwindMerge.twMerge("min-w-0 flex-1", className), children: [jsxRuntime.jsx("div", { className: "grid min-w-0 grid-cols-[1fr_auto] items-center gap-2", children: jsxRuntime.jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [jsxRuntime.jsx(Text, { className: cvaTitleCard({ disabled }), "data-slot": "title", size: "medium", weight: "bold", children: title }), titleTag ? (jsxRuntime.jsx(Tag, { color: disabled ? "unknown" : titleTag.color, "data-slot": "title-tag", size: "small", children: titleTag.title })) : null] }) }), jsxRuntime.jsx(Text, { className: cvaDescriptionCard({ disabled }), "data-slot": "description", size: "small", type: "p", children: description })] }));
+
+/**
+ * Default property values for PreferenceCardSkeleton component.
+ */
+const DEFAULT_SKELETON_PREFERENCE_CARD_PROPS = {
+    hasIcon: false,
+    hasTitleTag: false,
+    hasCardTag: false,
+    hasInput: false,
+};
+/**
+ * Generates a random width in pixels within the given range.
+ *
+ * Note: Uses pixel values instead of percentages (unlike ListItemSkeleton) because
+ * PreferenceCard text elements have fixed pixel-based layouts with truncation,
+ * not percentage-based flexible widths.
+ */
+const getRandomWidth = (min, max) => {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+};
+/**
+ * Skeleton loading indicator that mimics the PreferenceCard component structure.
+ * Uses the same grid layout, spacing, and visual hierarchy as PreferenceCard.
+ */
+const PreferenceCardSkeleton = ({ hasIcon = DEFAULT_SKELETON_PREFERENCE_CARD_PROPS.hasIcon, hasTitleTag = DEFAULT_SKELETON_PREFERENCE_CARD_PROPS.hasTitleTag, hasCardTag = DEFAULT_SKELETON_PREFERENCE_CARD_PROPS.hasCardTag, hasInput = DEFAULT_SKELETON_PREFERENCE_CARD_PROPS.hasInput, }) => {
+    const gridAreas = useGridAreas(preferenceCardGrid);
+    // Generate stable random widths once and never change them
+    const lineWidths = react.useMemo(() => {
+        return {
+            title: getRandomWidth(80, 140),
+            description: getRandomWidth(160, 240),
+        };
+    }, []);
+    return (jsxRuntime.jsxs("div", { className: cvaPreferenceCard(), children: [hasInput ? (jsxRuntime.jsx("div", { className: cvaInputContainer({ itemPlacement: "center" }), children: jsxRuntime.jsx(Skeleton, { height: 20, variant: "block", width: 20 }) })) : null, jsxRuntime.jsx("div", { className: cvaContentWrapper(), children: jsxRuntime.jsx(GridAreas, { ...gridAreas, className: cvaContentContainer({ itemPlacement: "center" }), children: slots => (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [hasIcon ? (jsxRuntime.jsx("div", { ...slots.icon, children: jsxRuntime.jsx(Skeleton, { className: cvaIconBackground({ disabled: false }), height: 32, variant: "block", width: 32 }) })) : null, jsxRuntime.jsxs("div", { ...slots.information, className: "min-w-0 flex-1", children: [jsxRuntime.jsx("div", { className: "grid min-w-0 grid-cols-[1fr_auto] items-center gap-2", children: jsxRuntime.jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [jsxRuntime.jsx(Skeleton, { height: "text-sm", width: lineWidths.title }), hasTitleTag ? jsxRuntime.jsx(TagSkeleton, { size: "small" }) : null] }) }), jsxRuntime.jsx(Skeleton, { height: "text-xs", width: lineWidths.description })] }), hasCardTag ? (jsxRuntime.jsx("div", { ...slots.cardTag, className: "justify-self-end", children: jsxRuntime.jsx(TagSkeleton, { size: "medium" }) })) : null] })) }) })] }));
+};
+/**
+ * Simple tag skeleton for use within PreferenceCardSkeleton.
+ * Renders a rounded pill shape without any props.
+ */
+const TagSkeleton = ({ size }) => {
+    const width = react.useMemo(() => getRandomWidth(40, 64), []);
+    const height = size === "small" ? 18 : 24;
+    return jsxRuntime.jsx(Skeleton, { className: "rounded-full", height: height, variant: "block", width: width });
+};
+
 function useConfirmExit(confirmExit, when = true) {
     reactRouter.useBlocker(confirmExit, when);
 }
@@ -6098,10 +7180,12 @@ exports.CardHeader = CardHeader;
 exports.Collapse = Collapse;
 exports.CompletionStatusIndicator = CompletionStatusIndicator;
 exports.CopyableText = CopyableText;
+exports.DEFAULT_SKELETON_PREFERENCE_CARD_PROPS = DEFAULT_SKELETON_PREFERENCE_CARD_PROPS;
 exports.DetailsList = DetailsList;
 exports.EmptyState = EmptyState;
 exports.EmptyValue = EmptyValue;
 exports.ExternalLink = ExternalLink;
+exports.GridAreas = GridAreas;
 exports.Heading = Heading;
 exports.Highlight = Highlight;
 exports.HorizontalOverflowScroller = HorizontalOverflowScroller;
@@ -6131,10 +7215,13 @@ exports.PopoverContent = PopoverContent;
 exports.PopoverTitle = PopoverTitle;
 exports.PopoverTrigger = PopoverTrigger;
 exports.Portal = Portal;
+exports.PreferenceCard = PreferenceCard;
+exports.PreferenceCardSkeleton = PreferenceCardSkeleton;
 exports.Prompt = Prompt;
 exports.ROLE_CARD = ROLE_CARD;
 exports.SectionHeader = SectionHeader;
 exports.Sidebar = Sidebar;
+exports.Skeleton = Skeleton;
 exports.SkeletonLines = SkeletonLines;
 exports.Spacer = Spacer;
 exports.Spinner = Spinner;
@@ -6151,12 +7238,17 @@ exports.TrendIndicator = TrendIndicator;
 exports.TrendIndicators = TrendIndicators;
 exports.ValueBar = ValueBar;
 exports.ZStack = ZStack;
+exports.createGrid = createGrid;
 exports.cvaButton = cvaButton;
 exports.cvaButtonPrefixSuffix = cvaButtonPrefixSuffix;
 exports.cvaButtonSpinner = cvaButtonSpinner;
 exports.cvaButtonSpinnerContainer = cvaButtonSpinnerContainer;
 exports.cvaClickable = cvaClickable;
 exports.cvaContainerStyles = cvaContainerStyles;
+exports.cvaContentContainer = cvaContentContainer;
+exports.cvaContentWrapper = cvaContentWrapper;
+exports.cvaDescriptionCard = cvaDescriptionCard;
+exports.cvaIconBackground = cvaIconBackground;
 exports.cvaIconButton = cvaIconButton;
 exports.cvaImgStyles = cvaImgStyles;
 exports.cvaIndicator = cvaIndicator;
@@ -6164,6 +7256,7 @@ exports.cvaIndicatorIcon = cvaIndicatorIcon;
 exports.cvaIndicatorIconBackground = cvaIndicatorIconBackground;
 exports.cvaIndicatorLabel = cvaIndicatorLabel;
 exports.cvaIndicatorPing = cvaIndicatorPing;
+exports.cvaInputContainer = cvaInputContainer;
 exports.cvaInteractableItem = cvaInteractableItem;
 exports.cvaList = cvaList;
 exports.cvaListContainer = cvaListContainer;
@@ -6181,6 +7274,8 @@ exports.cvaMenuListMultiSelect = cvaMenuListMultiSelect;
 exports.cvaPageHeader = cvaPageHeader;
 exports.cvaPageHeaderContainer = cvaPageHeaderContainer;
 exports.cvaPageHeaderHeading = cvaPageHeaderHeading;
+exports.cvaPreferenceCard = cvaPreferenceCard;
+exports.cvaTitleCard = cvaTitleCard;
 exports.cvaToggleGroup = cvaToggleGroup;
 exports.cvaToggleGroupWithSlidingBackground = cvaToggleGroupWithSlidingBackground;
 exports.cvaToggleItem = cvaToggleItem;
@@ -6196,6 +7291,7 @@ exports.getValueBarColorByValue = getValueBarColorByValue;
 exports.iconColorNames = iconColorNames;
 exports.iconPalette = iconPalette;
 exports.noPagination = noPagination;
+exports.preferenceCardGrid = preferenceCardGrid;
 exports.useClickOutside = useClickOutside;
 exports.useContainerBreakpoints = useContainerBreakpoints;
 exports.useContinuousTimeout = useContinuousTimeout;
@@ -6205,6 +7301,7 @@ exports.useDebounce = useDebounce;
 exports.useDevicePixelRatio = useDevicePixelRatio;
 exports.useElevatedReducer = useElevatedReducer;
 exports.useElevatedState = useElevatedState;
+exports.useGridAreas = useGridAreas;
 exports.useHover = useHover;
 exports.useInfiniteScroll = useInfiniteScroll;
 exports.useIsFirstRender = useIsFirstRender;