@flikk/ui 1.0.0-beta.27 → 1.0.0-beta.29

package/dist/components/core/ScrollArea/ScrollArea.js

@@ -25,7 +25,7 @@ import { useSmoothScroll } from './smooth/useSmoothScroll.js';
  * </ScrollArea>
  * ```
  */
-const ScrollArea = React__default.forwardRef(({ children, type = 'hover', size = 'default', orientation = 'vertical', snap, snapAlign = 'start', smooth = false, smoothConfig, onScrollProgress, onPerformanceUpdate, className, theme, ...props }, ref) => {
+const ScrollArea = React__default.forwardRef(({ children, type = 'hover', size = 'default', orientation = 'vertical', dragToScroll = false, snap, snapAlign = 'start', smooth = true, smoothConfig, onScrollProgress, onPerformanceUpdate, className, theme, ...props }, ref) => {
     // Internal ref for the scrollable element
     const internalRef = useRef(null);
     // Determine scroll orientation for smooth scroll
@@ -58,14 +58,244 @@ const ScrollArea = React__default.forwardRef(({ children, type = 'hover', size =
         const extendedRef = element;
         // Add smooth scroll methods if smooth is enabled
         if (smooth && smoothAPI) {
-            extendedRef.smoothScrollTo = smoothAPI.scrollTo;
+            extendedRef.smoothScrollTo = (position, options) => {
+                if (inertiaFrameIdRef.current !== null) {
+                    cancelAnimationFrame(inertiaFrameIdRef.current);
+                    inertiaFrameIdRef.current = null;
+                }
+                smoothAPI.scrollTo(position, options);
+            };
             extendedRef.getScrollVelocity = smoothAPI.getVelocity;
             extendedRef.pauseSmoothScroll = smoothAPI.stop;
             extendedRef.resumeSmoothScroll = smoothAPI.start;
             extendedRef.refreshSnapPoints = smoothAPI.refreshSnapPoints;
         }
+        extendedRef.setPosition = (position) => {
+            if (inertiaFrameIdRef.current !== null) {
+                cancelAnimationFrame(inertiaFrameIdRef.current);
+                inertiaFrameIdRef.current = null;
+            }
+            if (smooth && smoothAPI) {
+                smoothAPI.setPosition(position);
+            }
+            else {
+                const max = orientation === 'horizontal'
+                    ? element.scrollWidth - element.clientWidth
+                    : element.scrollHeight - element.clientHeight;
+                const clamped = Math.max(0, Math.min(max, position));
+                if (orientation === 'horizontal') {
+                    element.scrollLeft = clamped;
+                }
+                else {
+                    element.scrollTop = clamped;
+                }
+            }
+        };
         return extendedRef;
-    }, [smooth, smoothAPI]);
+    }, [smooth, smoothAPI, orientation]);
+    // Drag-to-scroll (mouse panning) with inertia.
+    const dragRef = useRef(null);
+    const suppressClickRef = useRef(false);
+    const [isDragging, setIsDragging] = useState(false);
+    const inertiaFrameIdRef = useRef(null);
+    // Cancel inertia animation on unmount
+    useEffect(() => {
+        return () => {
+            if (inertiaFrameIdRef.current !== null) {
+                cancelAnimationFrame(inertiaFrameIdRef.current);
+            }
+        };
+    }, []);
+    const startDragInertia = (vx, vy) => {
+        if (inertiaFrameIdRef.current !== null) {
+            cancelAnimationFrame(inertiaFrameIdRef.current);
+        }
+        let lastTime = performance.now();
+        const el = internalRef.current;
+        if (!el)
+            return;
+        const tick = (now) => {
+            const dt = now - lastTime;
+            lastTime = now;
+            // Prevent frame skip issues when tab is backgrounded
+            if (dt > 100) {
+                inertiaFrameIdRef.current = requestAnimationFrame(tick);
+                return;
+            }
+            // Apply friction decay (0.95 per 16.67ms frame)
+            const friction = 0.95;
+            const timeFactor = dt / 16.67;
+            const currentFriction = Math.pow(friction, timeFactor);
+            let activeVx = vx;
+            let activeVy = vy;
+            if (orientation === 'vertical') {
+                activeVx = 0;
+            }
+            else if (orientation === 'horizontal') {
+                activeVy = 0;
+            }
+            const deltaX = activeVx * dt;
+            const deltaY = activeVy * dt;
+            const nextLeft = el.scrollLeft + deltaX;
+            const nextTop = el.scrollTop + deltaY;
+            // Apply positions
+            if (smooth && smoothAPI) {
+                if (smoothOrientation === 'horizontal') {
+                    smoothAPI.setPosition(nextLeft);
+                    if (orientation === 'both') {
+                        el.scrollTop = nextTop;
+                    }
+                }
+                else {
+                    smoothAPI.setPosition(nextTop);
+                    if (orientation === 'both') {
+                        el.scrollLeft = nextLeft;
+                    }
+                }
+            }
+            else {
+                if (orientation !== 'vertical')
+                    el.scrollLeft = nextLeft;
+                if (orientation !== 'horizontal')
+                    el.scrollTop = nextTop;
+            }
+            // Decay velocity
+            vx *= currentFriction;
+            vy *= currentFriction;
+            // If we hit scroll boundaries, stop inertia on that axis
+            const maxScrollLeft = el.scrollWidth - el.clientWidth;
+            const maxScrollTop = el.scrollHeight - el.clientHeight;
+            if (el.scrollLeft <= 0 || el.scrollLeft >= maxScrollLeft)
+                vx = 0;
+            if (el.scrollTop <= 0 || el.scrollTop >= maxScrollTop)
+                vy = 0;
+            const currentSpeed = Math.sqrt(vx * vx + vy * vy);
+            if (currentSpeed > 0.05) {
+                inertiaFrameIdRef.current = requestAnimationFrame(tick);
+            }
+            else {
+                inertiaFrameIdRef.current = null;
+            }
+        };
+        inertiaFrameIdRef.current = requestAnimationFrame(tick);
+    };
+    const onDragPointerDown = (e) => {
+        if (e.pointerType !== 'mouse' || e.button !== 0)
+            return;
+        // Stop any running inertia animation on fresh interaction
+        if (inertiaFrameIdRef.current !== null) {
+            cancelAnimationFrame(inertiaFrameIdRef.current);
+            inertiaFrameIdRef.current = null;
+        }
+        suppressClickRef.current = false;
+        if (e.target.closest('input, textarea, select, [contenteditable="true"]'))
+            return;
+        const el = internalRef.current;
+        if (!el)
+            return;
+        dragRef.current = {
+            startX: e.clientX,
+            startY: e.clientY,
+            scrollLeft: el.scrollLeft,
+            scrollTop: el.scrollTop,
+            dragging: false,
+            pointerId: e.pointerId,
+            history: [{ time: performance.now(), x: e.clientX, y: e.clientY }]
+        };
+    };
+    const onDragPointerMove = (e) => {
+        const drag = dragRef.current;
+        const el = internalRef.current;
+        if (!drag || !el)
+            return;
+        const now = performance.now();
+        drag.history.push({ time: now, x: e.clientX, y: e.clientY });
+        // Keep only the last 100ms of history for velocity calculation
+        while (drag.history.length > 0 && now - drag.history[0].time > 100) {
+            drag.history.shift();
+        }
+        const dx = e.clientX - drag.startX;
+        const dy = e.clientY - drag.startY;
+        if (!drag.dragging) {
+            if (Math.abs(dx) < 4 && Math.abs(dy) < 4)
+                return;
+            drag.dragging = true;
+            setIsDragging(true);
+            el.setPointerCapture(drag.pointerId);
+        }
+        const targetLeft = drag.scrollLeft - dx;
+        const targetTop = drag.scrollTop - dy;
+        if (smooth && smoothAPI) {
+            if (smoothOrientation === 'horizontal') {
+                smoothAPI.setPosition(targetLeft);
+                if (orientation === 'both') {
+                    el.scrollTop = targetTop;
+                }
+            }
+            else {
+                smoothAPI.setPosition(targetTop);
+                if (orientation === 'both') {
+                    el.scrollLeft = targetLeft;
+                }
+            }
+        }
+        else {
+            if (orientation !== 'vertical')
+                el.scrollLeft = targetLeft;
+            if (orientation !== 'horizontal')
+                el.scrollTop = targetTop;
+        }
+    };
+    const onDragPointerEnd = (e) => {
+        var _a;
+        const drag = dragRef.current;
+        if (!drag)
+            return;
+        if (drag.dragging) {
+            suppressClickRef.current = e.type === 'pointerup';
+            setIsDragging(false);
+            const el = internalRef.current;
+            if (el) {
+                (_a = el.releasePointerCapture) === null || _a === void 0 ? void 0 : _a.call(el, drag.pointerId);
+                // Calculate release velocity
+                const now = performance.now();
+                const recentHistory = drag.history.filter(h => now - h.time < 100);
+                if (recentHistory.length >= 2) {
+                    const first = recentHistory[0];
+                    const last = recentHistory[recentHistory.length - 1];
+                    const dt = last.time - first.time;
+                    if (dt > 10) {
+                        const vx = (last.x - first.x) / dt;
+                        const vy = (last.y - first.y) / dt;
+                        const speed = Math.sqrt(vx * vx + vy * vy);
+                        // Only trigger inertia if speed is high enough AND smooth scrolling is enabled
+                        if (speed > 0.15 && smooth) {
+                            startDragInertia(-vx, -vy);
+                        }
+                    }
+                }
+            }
+        }
+        dragRef.current = null;
+    };
+    const onDragClickCapture = (e) => {
+        if (!suppressClickRef.current)
+            return;
+        suppressClickRef.current = false;
+        e.preventDefault();
+        e.stopPropagation();
+    };
+    const dragHandlers = dragToScroll
+        ? {
+            onPointerDown: onDragPointerDown,
+            onPointerMove: onDragPointerMove,
+            onPointerUp: onDragPointerEnd,
+            onPointerCancel: onDragPointerEnd,
+            onClickCapture: onDragClickCapture,
+            // Native HTML5 drag (images, links) hijacks the gesture mid-pan
+            onDragStart: (e) => e.preventDefault(),
+        }
+        : undefined;
     // Scroll-detection state for type='scroll' (overlay scrollbar)
     const [isScrolling, setIsScrolling] = useState(false);
     const scrollTimerRef = useRef(undefined);
@@ -181,7 +411,15 @@ const ScrollArea = React__default.forwardRef(({ children, type = 'hover', size =
                 ].join(' ');
         }
     }, [type]);
-    return (jsx("div", { ref: internalRef, className: cn(resolvedTheme.baseStyle, overflowClasses, snapClasses, scrollbarBase, scrollbarVisibility, className), "data-orientation": orientation, "data-type": type, "data-smooth": smooth, "data-scrolling": isScrolling || undefined, ...props, children: children }));
+    const onWheel = (e) => {
+        var _a;
+        if (inertiaFrameIdRef.current !== null) {
+            cancelAnimationFrame(inertiaFrameIdRef.current);
+            inertiaFrameIdRef.current = null;
+        }
+        (_a = props.onWheel) === null || _a === void 0 ? void 0 : _a.call(props, e);
+    };
+    return (jsx("div", { ref: internalRef, className: cn(resolvedTheme.baseStyle, overflowClasses, snapClasses, scrollbarBase, scrollbarVisibility, dragToScroll && 'cursor-grab', isDragging && 'cursor-grabbing select-none', className), "data-orientation": orientation, "data-type": type, "data-smooth": smooth, "data-scrolling": isScrolling || undefined, "data-dragging": isDragging || undefined, ...props, ...dragHandlers, onWheel: onWheel, children: children }));
 });
 ScrollArea.displayName = 'ScrollArea';
 

package/dist/components/core/ScrollArea/ScrollArea.types.d.ts

@@ -43,6 +43,8 @@ export interface ScrollAreaRef extends HTMLDivElement {
     pauseSmoothScroll?: () => void;
     /** Resume smooth scrolling */
     resumeSmoothScroll?: () => void;
+    /** Set scroll position immediately without animation */
+    setPosition?: (position: number) => void;
     /** Refresh snap points */
     refreshSnapPoints?: () => void;
 }
@@ -89,9 +91,18 @@ export interface ScrollAreaProps extends HTMLAttributes<HTMLDivElement> {
      */
     snapAlign?: 'start' | 'center' | 'end';
     /**
-     * Enable smooth momentum-based scrolling
+     * Enable mouse drag-to-scroll panning (grab the content and drag, like touch).
+     * Mouse-only — touch input already pans natively. A real drag needs ~4px of
+     * movement first, so plain clicks on content (cards, buttons) still work; the
+     * click that would follow a completed drag is suppressed. Drags never start
+     * from text fields, so selection inside inputs/textareas is unaffected.
      * @default false
      */
+    dragToScroll?: boolean;
+    /**
+     * Enable smooth momentum-based scrolling
+     * @default true
+     */
     smooth?: boolean;
     /**
      * Configuration for smooth scrolling

package/dist/components/core/ScrollArea/smooth/SmoothScrollEngine.d.ts

@@ -98,6 +98,10 @@ export declare class SmoothScrollEngine {
      * Scroll to element
      */
     scrollToElement(element: HTMLElement, options?: ScrollToOptions): void;
+    /**
+     * Set scroll position immediately without animation, updating internal state
+     */
+    setPosition(position: number): void;
     /**
      * Get current velocity
      */

package/dist/components/core/ScrollArea/smooth/SmoothScrollEngine.js

@@ -447,6 +447,29 @@ class SmoothScrollEngine {
         }
         this.scrollTo(position, options);
     }
+    /**
+     * Set scroll position immediately without animation, updating internal state
+     */
+    setPosition(position) {
+        const max = getMaxScroll(this.element, this.orientation);
+        const clamped = clampScroll(position, 0, max);
+        this.state.current = clamped;
+        this.state.target = clamped;
+        this.previousPosition = clamped;
+        this.state.velocity.current = 0;
+        this.state.velocity.previous = 0;
+        // Sync to DOM
+        if (this.orientation === 'horizontal') {
+            this.element.scrollLeft = clamped;
+        }
+        else {
+            this.element.scrollTop = clamped;
+        }
+        // Stop any ongoing programmatic scroll or snapping
+        this.state.isSnapping = false;
+        this.state.targetSnapPoint = null;
+        this.animationOnComplete = null;
+    }
     /**
      * Get current velocity
      */

package/dist/components/core/ScrollArea/smooth/useSmoothScroll.js

@@ -106,6 +106,10 @@ function useSmoothScroll(elementRef, config = {}, orientation = 'vertical') {
                 var _a;
                 (_a = engineRef.current) === null || _a === void 0 ? void 0 : _a.updateConfig(newConfig);
             },
+            setPosition: (position) => {
+                var _a;
+                (_a = engineRef.current) === null || _a === void 0 ? void 0 : _a.setPosition(position);
+            },
             refreshSnapPoints: () => {
                 var _a;
                 (_a = engineRef.current) === null || _a === void 0 ? void 0 : _a.refreshSnapPoints();

package/dist/components/core/ScrollArea/smooth/useSmoothScroll.types.d.ts

@@ -39,6 +39,11 @@ export interface SmoothScrollAPI {
      * @param config - Partial configuration to update
      */
     update: (config: SmoothScrollConfigUpdate) => void;
+    /**
+     * Set scroll position immediately without animation, updating internal state
+     * @param position - Target scroll position in pixels
+     */
+    setPosition: (position: number) => void;
     /**
      * Refresh snap points (call when DOM changes)
      */

package/dist/components/core/Segmented/Segmented.theme.js

@@ -3,7 +3,7 @@
  */
 const segmentedTheme = {
     // Base styles for the segmented container
-    baseStyle: "relative flex rounded-[var(--segmented-radius)] bg-[var(--color-surface)] border border-[var(--color-border)]/60 p-[var(--segmented-padding)] shadow-inner",
+    baseStyle: "relative flex rounded-[var(--segmented-radius)] bg-neutral-100 dark:bg-neutral-900 border border-[var(--color-border)] p-[var(--segmented-padding)] shadow-inner-real-md",
     // Size variants using CSS variables
     sizes: {
         sm: "min-h-[var(--segmented-min-h-sm)]",
@@ -15,7 +15,7 @@ const segmentedTheme = {
     // Disabled style
     disabledStyle: "opacity-50 cursor-not-allowed pointer-events-none",
     // Sliding background style with CSS variables
-    slidingBackgroundStyle: "absolute top-[0px] left-[0px] rounded-[var(--segmented-inner-radius)] transition-transform duration-200 ease-out pointer-events-none z-0 bg-white dark:bg-[var(--color-surface-raised)] shadow-real-lg",
+    slidingBackgroundStyle: "absolute top-[0px] left-[0px] rounded-[var(--segmented-inner-radius)] transition-transform duration-200 ease-out pointer-events-none z-0 bg-[var(--color-surface)] shadow-real-md dark:bg-neutral-800",
 };
 /**
  * Default theme for the SegmentedItem component

package/dist/components/core/Tooltip/Tooltip.theme.js

@@ -1,6 +1,6 @@
 const tooltipTheme = {
     // Base style for the tooltip - using fixed positioning for portal rendering
-    baseStyle: "fixed z-[99] rounded-[var(--tooltip-radius)] py-1 px-2 text-xs text-[var(--color-text-primary)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 pointer-events-none bg-[var(--color-surface-overlay)]/90 backdrop-blur-md outline outline-[var(--color-border)] shadow-lg",
+    baseStyle: "fixed z-[99] rounded-[var(--tooltip-radius)] py-1 px-2 text-xs text-[var(--color-text-primary)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 pointer-events-none bg-[var(--color-surface-overlay)]/80 backdrop-blur-lg outline outline-[var(--color-border)] shadow-lg",
 };
 
 export { tooltipTheme };

package/dist/components/core/index.d.ts

@@ -10,6 +10,7 @@ export * from "./ButtonGroup";
 export * from "./Calendar";
 export * from "./Card";
 export * from "./CardStack";
+export * from "./HeroCard";
 export * from "./Carousel";
 export * from "./CommandPalette";
 export * from "./Separator";

package/dist/components/core/index.js

@@ -17,6 +17,8 @@ export { calendarAnimations } from './Calendar/Calendar.animations.js';
 export { CalendarMini } from './Calendar/CalendarMini/CalendarMini.js';
 export { Card } from './Card/Card.js';
 export { CardStack } from './CardStack/CardStack.js';
+export { HERO_CARD_DEFAULT_IMAGE, HeroCard } from './HeroCard/HeroCard.js';
+export { heroCardTheme } from './HeroCard/HeroCard.theme.js';
 export { Carousel } from './Carousel/Carousel.js';
 export { CarouselBody } from './Carousel/CarouselBody.js';
 export { CommandPalette } from './CommandPalette/CommandPalette.js';

package/dist/components/data-display/DescriptionList/DescriptionList.js

@@ -17,19 +17,35 @@ function useDescriptionListContext() {
 // ──────────────────────────────────────────────
 // DescriptionList (container)
 // ──────────────────────────────────────────────
-const DescriptionListRoot = React__default.forwardRef(({ className, variant = "horizontal", theme: customTheme, children, ...props }, ref) => {
-    const theme = useMemo(() => ({ ...descriptionListTheme, ...customTheme }), [customTheme]);
-    const contextValue = useMemo(() => ({ variant, theme }), [variant, theme]);
-    return (jsx(DescriptionListContext.Provider, { value: contextValue, children: jsx("dl", { ref: ref, className: cn(theme.baseStyle, className), ...props, children: children }) }));
+const DescriptionListRoot = React__default.forwardRef(({ className, variant = "horizontal", padding = "flush", items, theme: customTheme, children, ...props }, ref) => {
+    const theme = useMemo(() => ({
+        ...descriptionListTheme,
+        ...customTheme,
+        paddingStyles: { ...descriptionListTheme.paddingStyles, ...customTheme === null || customTheme === void 0 ? void 0 : customTheme.paddingStyles },
+    }), [customTheme]);
+    const contextValue = useMemo(() => ({ variant, padding, theme }), [variant, padding, theme]);
+    if (process.env.NODE_ENV !== "production" &&
+        items &&
+        React__default.Children.count(children) > 0) {
+        console.warn("[DescriptionList]: both `items` and children were provided — `items` takes precedence and children are ignored.");
+    }
+    // Data-driven path maps to the same compound primitive as composition.
+    const content = items
+        ? items.map((item, i) => {
+            var _a;
+            return (jsx(DescriptionListItem, { label: item.label, value: item.value, className: item.className }, (_a = item.key) !== null && _a !== void 0 ? _a : i));
+        })
+        : children;
+    return (jsx(DescriptionListContext.Provider, { value: contextValue, children: jsx("dl", { ref: ref, className: cn(theme.baseStyle, className), ...props, children: content }) }));
 });
 DescriptionListRoot.displayName = "DescriptionList";
 // ──────────────────────────────────────────────
 // DescriptionList.Item
 // ──────────────────────────────────────────────
-const DescriptionListItem = React__default.forwardRef(({ term, detail, className, ...props }, ref) => {
-    const { variant, theme } = useDescriptionListContext();
+const DescriptionListItem = React__default.forwardRef(({ label, value, className, ...props }, ref) => {
+    const { variant, padding, theme } = useDescriptionListContext();
     const isHorizontal = variant === "horizontal";
-    return (jsxs("div", { ref: ref, className: cn(theme.itemStyle, isHorizontal && "sm:grid sm:grid-cols-3 sm:gap-4 sm:px-0", className), ...props, children: [jsx("dt", { className: theme.termStyle, children: term }), jsx("dd", { className: cn(theme.detailStyle, isHorizontal && "sm:col-span-2 sm:mt-0"), children: detail })] }));
+    return (jsxs("div", { ref: ref, className: cn(theme.itemStyle, isHorizontal && "sm:grid sm:grid-cols-3 sm:gap-4 sm:px-0", theme.paddingStyles[padding], className), ...props, children: [jsx("dt", { className: theme.labelStyle, children: label }), jsx("dd", { className: cn(theme.valueStyle, isHorizontal && "sm:col-span-2 sm:mt-0"), children: value })] }));
 });
 DescriptionListItem.displayName = "DescriptionList.Item";
 // ──────────────────────────────────────────────

package/dist/components/data-display/DescriptionList/DescriptionList.theme.js

@@ -1,8 +1,15 @@
 const descriptionListTheme = {
     baseStyle: "divide-y divide-[var(--color-border)] min-w-0",
-    itemStyle: "px-4 py-3",
-    termStyle: "text-sm/6 font-medium text-[var(--color-text-primary)]",
-    detailStyle: "mt-1 text-sm/6 text-[var(--color-text-secondary)]",
+    itemStyle: "py-2.5",
+    // Edge-padding modes (mirrors Table's `flush`): `flush` (default) zeroes the item
+    // side padding so values sit flush with the container edges (e.g. inside a Card);
+    // `default` adds horizontal padding for standalone use.
+    paddingStyles: {
+        default: "px-4",
+        flush: "px-0",
+    },
+    labelStyle: "text-sm font-medium text-[var(--color-text-primary)]",
+    valueStyle: "text-sm mt-0.5 text-[var(--color-text-secondary)]",
 };
 
 export { descriptionListTheme };

package/dist/components/data-display/DescriptionList/DescriptionList.types.d.ts

@@ -1,34 +1,73 @@
 import React from "react";
 export type DescriptionListVariant = "horizontal" | "vertical";
+/**
+ * Edge padding behavior for list items (mirrors Table's `padding`).
+ * - `default`: items get horizontal side padding.
+ * - `flush`: items have zero side padding so labels/values align flush with the
+ *   container edges (e.g. inside a padded Card).
+ */
+export type DescriptionListPadding = "default" | "flush";
 export interface DescriptionListTheme {
     /** Base styles for the <dl> container */
     baseStyle: string;
     /** Styles for each item wrapper */
     itemStyle: string;
-    /** Styles for the term (<dt>) */
-    termStyle: string;
-    /** Styles for the detail (<dd>) */
-    detailStyle: string;
+    /** Edge-padding mode classes applied to each item */
+    paddingStyles: Record<DescriptionListPadding, string>;
+    /** Styles for the label (<dt>) */
+    labelStyle: string;
+    /** Styles for the value (<dd>) */
+    valueStyle: string;
 }
 export interface DescriptionListThemeOverrides {
     baseStyle?: string;
     itemStyle?: string;
-    termStyle?: string;
-    detailStyle?: string;
+    paddingStyles?: Partial<Record<DescriptionListPadding, string>>;
+    labelStyle?: string;
+    valueStyle?: string;
 }
 export interface DescriptionListContextValue {
     variant: DescriptionListVariant;
+    padding: DescriptionListPadding;
     theme: DescriptionListTheme;
 }
 export interface DescriptionListProps extends React.HTMLAttributes<HTMLDListElement> {
     /** Layout variant: "horizontal" (default) or "vertical" */
     variant?: DescriptionListVariant;
+    /**
+     * Edge padding behavior. `flush` (default) removes the item side padding so
+     * labels/values align flush with the container edges (e.g. inside a padded
+     * Card); `default` adds horizontal padding for standalone use.
+     */
+    padding?: DescriptionListPadding;
+    /**
+     * Data-driven items. When provided, the list renders from this array and any
+     * `children` are ignored (dev-warns). Omit it to use the compound API.
+     * Fully serializable — ideal for generative UI.
+     */
+    items?: DescriptionListItemData[];
     /** Custom theme overrides */
     theme?: DescriptionListThemeOverrides;
+    /** `DescriptionList.Item` children (compound API). Optional when `items` is used. */
+    children?: React.ReactNode;
+}
+/**
+ * A single key/value entry for the data-driven (`items`) API. Maps internally
+ * to `DescriptionList.Item`.
+ */
+export interface DescriptionListItemData {
+    /** The label (rendered as the <dt> term) */
+    label: React.ReactNode;
+    /** The value (rendered as the <dd> description) */
+    value: React.ReactNode;
+    /** Optional className forwarded to the item wrapper */
+    className?: string;
+    /** Stable React key (falls back to the array index) */
+    key?: string | number;
 }
 export interface DescriptionListItemProps extends React.HTMLAttributes<HTMLDivElement> {
-    /** The term / label */
-    term: React.ReactNode;
-    /** The detail / value */
-    detail: React.ReactNode;
+    /** The label (rendered as the <dt> term) */
+    label: React.ReactNode;
+    /** The value (rendered as the <dd> description) */
+    value: React.ReactNode;
 }

package/dist/components/data-display/DescriptionList/index.d.ts

@@ -1,2 +1,2 @@
 export { DescriptionList } from "./DescriptionList";
-export type { DescriptionListVariant, DescriptionListProps, DescriptionListItemProps, DescriptionListThemeOverrides, } from "./DescriptionList.types";
+export type { DescriptionListVariant, DescriptionListPadding, DescriptionListProps, DescriptionListItemProps, DescriptionListItemData, DescriptionListThemeOverrides, } from "./DescriptionList.types";

package/dist/components/data-display/Feed/Feed.js

@@ -1,4 +1,4 @@
-import { jsx, jsxs } from 'react/jsx-runtime';
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 import React__default, { createContext, useMemo, useState, useCallback, useContext } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
 import { ChevronUpDownIcon } from '@heroicons/react/16/solid';
@@ -19,10 +19,33 @@ const useFeedContext = () => {
 // ---------------------------------------------------------------------------
 // Feed (root)
 // ---------------------------------------------------------------------------
-const FeedRoot = React__default.forwardRef(({ children, className, theme: themeOverrides, ...props }, ref) => {
+/** Render one data-driven item to the compound `Feed.Item` primitive. */
+const renderItemData = (item, index) => {
+    var _a;
+    return (jsx(FeedItem, { icon: item.icon, timestamp: item.timestamp, indicatorClassName: item.indicatorClassName, className: item.className, children: item.content }, (_a = item.key) !== null && _a !== void 0 ? _a : index));
+};
+const FeedRoot = React__default.forwardRef(({ children, items, collapseAfter, className, theme: themeOverrides, ...props }, ref) => {
     const theme = useMemo(() => ({ ...feedTheme, ...themeOverrides }), [themeOverrides]);
     const contextValue = useMemo(() => ({ theme }), [theme]);
-    return (jsx(FeedContext.Provider, { value: contextValue, children: jsx("div", { ref: ref, className: cn(theme.baseStyle, className), ...props, children: jsx("ul", { role: "list", className: theme.listStyle, children: children }) }) }));
+    if (process.env.NODE_ENV !== "production" &&
+        items &&
+        React__default.Children.count(children) > 0) {
+        console.warn("[Feed]: both `items` and children were provided — `items` takes precedence and children are ignored.");
+    }
+    // Data-driven path maps to the same compound primitives as composition.
+    // With `collapseAfter`, overflow items are tucked into a Feed.Collapse.
+    let content = children;
+    if (items) {
+        if (collapseAfter != null && items.length > collapseAfter) {
+            const visible = items.slice(0, collapseAfter);
+            const hidden = items.slice(collapseAfter);
+            content = (jsxs(Fragment, { children: [visible.map(renderItemData), jsx(FeedCollapse, { children: hidden.map(renderItemData) })] }));
+        }
+        else {
+            content = items.map(renderItemData);
+        }
+    }
+    return (jsx(FeedContext.Provider, { value: contextValue, children: jsx("div", { ref: ref, className: cn(theme.baseStyle, className), ...props, children: jsx("ul", { role: "list", className: theme.listStyle, children: content }) }) }));
 });
 FeedRoot.displayName = "Feed";
 // ---------------------------------------------------------------------------
@@ -87,7 +110,7 @@ const FeedCollapse = ({ label = "Show {count} more", icon, defaultExpanded = fal
     if (shouldReduceMotion) {
         return (jsxs("li", { className: cn(theme.collapseStyle, className), children: [expanded && (jsx("span", { "aria-hidden": "true", className: "absolute left-5 -translate-x-1/2 top-0 h-full w-0.5 bg-[var(--color-border)]/60" })), !expanded ? (jsxs("div", { className: "relative", style: { height: COLLAPSED_HEIGHT }, children: [jsx("svg", { "aria-hidden": "true", className: theme.collapseSvgStyle, style: { left: "calc(1.25rem - 1px)" }, width: SVG_WIDTH, height: COLLAPSED_HEIGHT, fill: "none", children: jsx("path", { d: CURVE_PATH, stroke: "var(--color-border)", strokeOpacity: "0.6", strokeWidth: STROKE_WIDTH }) }), jsxs("button", { type: "button", className: "absolute top-1/2 -translate-y-1/2 flex items-center gap-2.5 cursor-pointer bg-transparent border-none p-0", style: {
                                 left: `calc(1.25rem - 1px + ${CURVE_APEX_X + 12}px)`,
-                            }, onClick: handleToggle, "aria-expanded": false, children: [jsx("div", { className: "flex size-5 shrink-0 items-center justify-center rounded-full bg-[var(--color-surface)] ", children: collapseIcon }), jsx("span", { className: theme.collapseButtonStyle, children: resolvedLabel })] })] })) : (jsxs("div", { children: [clonedChildren, jsx("div", { className: "relative pb-8", children: jsxs("div", { className: theme.itemContentStyle, children: [jsx("div", { className: "flex size-8 ml-1 shrink-0 items-center justify-center rounded-full bg-[var(--color-background-secondary)] ring-2 ring-[var(--color-background)]/50", children: collapseIcon }), jsx("div", { className: theme.contentStyle, children: jsx("button", { type: "button", className: theme.collapseButtonStyle, onClick: handleToggle, "aria-expanded": true, children: "Show less" }) })] }) })] }))] }));
+                            }, onClick: handleToggle, "aria-expanded": false, children: [jsx("div", { className: "flex size-5 shrink-0 items-center justify-center rounded-full bg-[var(--color-surface)] ", children: collapseIcon }), jsx("span", { className: theme.collapseButtonStyle, children: resolvedLabel })] })] })) : (jsxs("div", { children: [clonedChildren, jsx("div", { className: "relative pb-8", children: jsxs("div", { className: theme.itemContentStyle, children: [jsx("div", { className: "flex size-8 ml-1 shrink-0 items-center justify-center rounded-full bg-[var(--color-surface)] ring-2 ring-[var(--color-background)]/50", children: collapseIcon }), jsx("div", { className: theme.contentStyle, children: jsx("button", { type: "button", className: theme.collapseButtonStyle, onClick: handleToggle, "aria-expanded": true, children: "Show less" }) })] }) })] }))] }));
     }
     /* ---- Full multi-stage animation ---- */
     return (jsxs("li", { className: cn(theme.collapseStyle, className), children: [jsx(motion.span, { "aria-hidden": "true", className: "absolute left-5 -translate-x-1/2 top-0 h-full w-0.5 bg-[var(--color-border)]/60", animate: { opacity: expanded ? 1 : 0 }, transition: { duration: 0.2 } }), jsx(motion.div, { animate: {
@@ -109,7 +132,7 @@ const FeedCollapse = ({ label = "Show {count} more", icon, defaultExpanded = fal
                         }, transition: {
                             duration: 0.25,
                             delay: expanded ? STAGGER_BASE_DELAY + count * STAGGER_IN : 0,
-                        }, children: jsx("div", { className: "relative pb-8", children: jsxs("div", { className: theme.itemContentStyle, children: [jsx("div", { className: "flex size-8 ml-1 shrink-0 items-center justify-center rounded-full bg-[var(--color-background-secondary)] ring-2 ring-[var(--color-background)]/50", children: collapseIcon }), jsx("div", { className: theme.contentStyle, children: jsx("button", { type: "button", className: theme.collapseButtonStyle, onClick: handleToggle, "aria-expanded": true, children: "Show less" }) })] }) }) })] })] }));
+                        }, children: jsx("div", { className: "relative pb-8", children: jsxs("div", { className: theme.itemContentStyle, children: [jsx("div", { className: "flex size-8 ml-1 shrink-0 items-center justify-center rounded-full bg-[var(--color-surface)] ring-2 ring-[var(--color-background)]/50", children: collapseIcon }), jsx("div", { className: theme.contentStyle, children: jsx("button", { type: "button", className: theme.collapseButtonStyle, onClick: handleToggle, "aria-expanded": true, children: "Show less" }) })] }) }) })] })] }));
 };
 FeedCollapse.displayName = "Feed.Collapse";
 // ---------------------------------------------------------------------------

package/dist/components/data-display/Feed/Feed.theme.js

@@ -6,7 +6,7 @@ const feedTheme = {
     itemContentStyle: "relative flex items-start space-x-4",
     connectorStyle: "feed-connector absolute top-5 left-5 -translate-x-1/2 h-full w-0.5 bg-[var(--color-border)]",
     // Indicators
-    indicatorStyle: "relative flex size-8 ml-1 shrink-0 items-center justify-center bg-[var(--color-background-secondary)] rounded-full ring-2 ring-[var(--color-background)]/50",
+    indicatorStyle: "relative flex size-8 ml-1 shrink-0 items-center justify-center bg-[var(--color-surface)] rounded-full ring-2 ring-[var(--color-background)]/50",
     dotIndicatorStyle: "relative flex size-10 items-center justify-center",
     // Content
     contentStyle: "min-w-0 flex-1 pt-1",