@flikk/ui 1.0.0-beta.26 → 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-sunken)]/10 border border-[var(--color-border)]/60 p-[var(--segmented-padding)] shadow-inner dark:bg-[var(--color-surface-sunken)]",
+    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/Sidebar/Sidebar.d.ts

@@ -11,4 +11,6 @@ export declare const Sidebar: React.ForwardRefExoticComponent<SidebarProps & Rea
     MobileTrigger: React.ForwardRefExoticComponent<import("./Sidebar.types").SidebarMobileTriggerProps & React.RefAttributes<HTMLButtonElement>>;
     UserProfile: React.ForwardRefExoticComponent<import("./Sidebar.types").SidebarUserProfileProps & React.RefAttributes<HTMLDivElement>>;
     Logo: React.ForwardRefExoticComponent<import("./Sidebar.types").SidebarLogoProps & React.RefAttributes<HTMLDivElement>>;
+    Search: React.ForwardRefExoticComponent<import("./Sidebar.types").SidebarSearchProps & React.RefAttributes<HTMLInputElement>>;
+    Card: React.ForwardRefExoticComponent<import("./Sidebar.types").SidebarCardProps & React.RefAttributes<HTMLDivElement>>;
 };

package/dist/components/core/Sidebar/Sidebar.js

@@ -14,21 +14,27 @@ import { SidebarToggle } from './SidebarToggle.js';
 import { SidebarMobileTrigger } from './SidebarMobileTrigger.js';
 import { SidebarUserProfile } from './SidebarUserProfile.js';
 import { SidebarLogo } from './SidebarLogo.js';
+import { SidebarSearch } from './SidebarSearch.js';
+import { SidebarCard } from './SidebarCard.js';
 
-// Matches the 200ms / cubic-bezier(0.4,0,0.2,1) timing used by Tailwind's
-// `duration-200` transitions on the content + footer, so width, padding and
-// icon animations stay in sync.
+// Subtle spring on the sidebar's width animation. Stiffness/damping picked so
+// the effective duration sits in the same ~200ms window as the internal CSS
+// transitions on padding/gap (Tailwind `duration-200`), but with a soft
+// organic settle instead of a linear cubic-bezier. Damping ratio ≈ 0.9 — a
+// hair under critical so there's a barely-perceptible easing-into-final
+// rather than an overshoot/bounce.
 const SIDEBAR_TRANSITION = {
-    type: "tween",
-    duration: 0.2,
-    ease: [0.4, 0, 0.2, 1],
+    type: "spring",
+    stiffness: 320,
+    damping: 34,
+    mass: 1,
 };
 const SidebarDesktop = React__default.forwardRef(({ side = "left", variant = "sidebar", density, width, children, className, theme: customTheme = {}, ...props }, ref) => {
     var _a, _b, _c, _d;
     const context = useSidebarContext();
     const collapsed = (_a = context === null || context === void 0 ? void 0 : context.collapsed) !== null && _a !== void 0 ? _a : false;
     const expandedWidth = (width === null || width === void 0 ? void 0 : width.expanded) || ((_b = context === null || context === void 0 ? void 0 : context.width) === null || _b === void 0 ? void 0 : _b.expanded) || 280;
-    const collapsedWidth = (width === null || width === void 0 ? void 0 : width.collapsed) || ((_c = context === null || context === void 0 ? void 0 : context.width) === null || _c === void 0 ? void 0 : _c.collapsed) || 64;
+    const collapsedWidth = (width === null || width === void 0 ? void 0 : width.collapsed) || ((_c = context === null || context === void 0 ? void 0 : context.width) === null || _c === void 0 ? void 0 : _c.collapsed) || 60;
     const theme = useMemo(() => ({
         ...sidebarTheme,
         ...customTheme,
@@ -104,6 +110,8 @@ const Sidebar = Object.assign(SidebarRoot, {
     MobileTrigger: SidebarMobileTrigger,
     UserProfile: SidebarUserProfile,
     Logo: SidebarLogo,
+    Search: SidebarSearch,
+    Card: SidebarCard,
 });
 
 export { Sidebar };

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

@@ -72,7 +72,7 @@ export interface SidebarProps extends React.HTMLAttributes<HTMLDivElement> {
     /**
      * Children components
      */
-    children: ReactNode;
+    children?: ReactNode;
     /**
      * Custom theme overrides
      */
@@ -176,11 +176,99 @@ export interface SidebarUserProfileProps extends React.HTMLAttributes<HTMLDivEle
     children?: ReactNode;
 }
 export interface SidebarLogoProps extends HTMLAttributes<HTMLDivElement> {
-    /** Always-visible icon/mark (shown in both expanded and collapsed states) */
-    icon: ReactNode;
-    /** Text shown only when expanded — animates in/out automatically */
+    /**
+     * Logo shown when the sidebar is **expanded**. Accepts any node — an `<img>`,
+     * an inline `<svg>`, or composed JSX (e.g. a mark + wordmark). Preferred
+     * over the legacy `icon` + `text` API.
+     */
+    expanded?: ReactNode;
+    /**
+     * Logo shown when the sidebar is **collapsed**. Typically a square mark
+     * (image, SVG, or JSX). If omitted, falls back to `expanded`, then to the
+     * legacy `icon` prop.
+     */
+    collapsed?: ReactNode;
+    /**
+     * Convenience: image URL for the expanded logo. Rendered as an `<img>` with
+     * sensible defaults (`h-8 w-auto object-contain`). Use `expandedImageClassName`
+     * to override sizing / object-fit. Ignored when `expanded` (ReactNode) is set.
+     */
+    expandedSrc?: string;
+    /**
+     * Convenience: image URL for the collapsed logo. Rendered as an `<img>` in a
+     * 36×36 (`size-9`) slot — matching the nav icon track — with `object-cover`
+     * by default. Use `collapsedImageClassName` to switch to `object-contain`,
+     * adjust border-radius, etc. Ignored when `collapsed` (ReactNode) is set.
+     */
+    collapsedSrc?: string;
+    /** ClassName forwarded to the auto-rendered `<img>` for `expandedSrc`. */
+    expandedImageClassName?: string;
+    /** ClassName forwarded to the auto-rendered `<img>` for `collapsedSrc`. */
+    collapsedImageClassName?: string;
+    /** Alt text for any auto-rendered `<img>` (both `expandedSrc` and `collapsedSrc`). */
+    alt?: string;
+    /**
+     * Legacy: always-visible icon/mark. Shown in both states; the `text` prop
+     * fades in alongside it when expanded. Use `expanded` / `collapsed` instead
+     * for full control (especially for image/SVG logos that differ per state).
+     */
+    icon?: ReactNode;
+    /**
+     * Legacy: text rendered to the right of `icon` when expanded — animates
+     * in/out on collapse. Use `expanded` instead for full control.
+     */
     text?: ReactNode;
 }
+export interface SidebarSearchProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+    /** Controlled value */
+    value?: string;
+    /** Uncontrolled initial value */
+    defaultValue?: string;
+    /**
+     * Fires on every keystroke. Consumers wire this to render results wherever
+     * they like (popover, command palette, side panel). The Sidebar tree itself
+     * is NOT filtered.
+     */
+    onChange?: (value: string) => void;
+    /** @default "Search…" */
+    placeholder?: string;
+    /** @default 'sm' */
+    size?: "sm" | "md";
+    /** Override the leading icon (defaults to MagnifyingGlassIcon). */
+    iconStart?: ReactNode;
+    /** Tooltip + aria-label for the collapsed-mode icon button. @default "Search" */
+    collapsedLabel?: string;
+    /** Hide the collapsed-mode icon button entirely. @default false */
+    hideWhenCollapsed?: boolean;
+    /** Forwarded to the underlying Input's group wrapper — use for background
+     * overrides on custom sidebar surfaces (e.g. `bg-transparent`). */
+    inputGroupClassName?: string;
+}
+export interface SidebarCardTheme {
+    /** Outer wrapper applied in both styled and unstyled modes — must carry
+     * `overflow-hidden` so the height collapse animation clips children. */
+    wrapperStyle: string;
+    /** Default container chrome (rounded / surface bg / border / padding).
+     * Skipped when the consumer sets `unstyled`. */
+    baseStyle: string;
+}
+export interface SidebarCardThemeOverrides {
+    wrapperStyle?: string;
+    baseStyle?: string;
+}
+export interface SidebarCardProps extends HTMLAttributes<HTMLDivElement> {
+    children: ReactNode;
+    className?: string;
+    /**
+     * Drop the default container styling (rounded / bg / border / padding)
+     * so consumers can put an edge-to-edge image, a custom panel, or any
+     * non-card-shaped content inside without fighting the default chrome.
+     * The disappear-on-collapse animation is unchanged.
+     * @default false
+     */
+    unstyled?: boolean;
+    theme?: SidebarCardThemeOverrides;
+}
 export interface SidebarProviderProps {
     children: React.ReactNode;
     defaultCollapsed?: boolean;

package/dist/components/core/Sidebar/SidebarCard.d.ts

@@ -0,0 +1,25 @@
+import React from "react";
+import { SidebarCardProps } from "./Sidebar.types";
+/**
+ * A collapse-aware container for arbitrary sidebar content — promo CTAs,
+ * storage meters, tip-of-the-day, banner images, anything. Renders its
+ * children when the sidebar is expanded and **disappears entirely** when
+ * the sidebar collapses (smooth height + opacity exit via AnimatePresence).
+ *
+ * Composition is open: drop in raw text, an `<img>`, a `<Button>`,
+ * `<Progress>`, or any custom JSX. There are intentionally no sub-parts
+ * (`Sidebar.Card.Header`/`.Body`/…) because the whole card vanishes
+ * together — granular slots add ceremony with no payoff.
+ *
+ * @example
+ * <Sidebar.Card>
+ *   <p className="text-sm">Upgrade for unlimited projects.</p>
+ *   <Button size="sm" className="mt-2 w-full">Upgrade</Button>
+ * </Sidebar.Card>
+ *
+ * @example Edge-to-edge image (no default container chrome):
+ * <Sidebar.Card unstyled>
+ *   <img src="/promo.jpg" alt="" className="w-full rounded-[var(--card-radius)]" />
+ * </Sidebar.Card>
+ */
+export declare const SidebarCard: React.ForwardRefExoticComponent<SidebarCardProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/core/Sidebar/SidebarCard.js

@@ -0,0 +1,68 @@
+import { jsx } from 'react/jsx-runtime';
+import React__default, { useMemo, useState, useEffect } from 'react';
+import { AnimatePresence, motion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+import { sidebarCardTheme } from './SidebarCard.theme.js';
+import { useSidebarCollapsed } from './SidebarContext.js';
+
+// Sidebar.Card mount is sequenced relative to the sidebar's collapse/expand
+// animation. On collapse → the card exits immediately (popLayout + slide/fade
+// in parallel with the rail narrowing). On expand → the card mount is delayed
+// until the sidebar's spring has settled, so the card lays out at its FINAL
+// expanded width on first render and the text never reflows mid-animation.
+// 260ms ≈ the spring's 99% settle time (stiffness 320, damping 34) — see
+// Sidebar.tsx's SIDEBAR_TRANSITION comment for the underlying math.
+const MOUNT_DELAY_MS = 260;
+/**
+ * A collapse-aware container for arbitrary sidebar content — promo CTAs,
+ * storage meters, tip-of-the-day, banner images, anything. Renders its
+ * children when the sidebar is expanded and **disappears entirely** when
+ * the sidebar collapses (smooth height + opacity exit via AnimatePresence).
+ *
+ * Composition is open: drop in raw text, an `<img>`, a `<Button>`,
+ * `<Progress>`, or any custom JSX. There are intentionally no sub-parts
+ * (`Sidebar.Card.Header`/`.Body`/…) because the whole card vanishes
+ * together — granular slots add ceremony with no payoff.
+ *
+ * @example
+ * <Sidebar.Card>
+ *   <p className="text-sm">Upgrade for unlimited projects.</p>
+ *   <Button size="sm" className="mt-2 w-full">Upgrade</Button>
+ * </Sidebar.Card>
+ *
+ * @example Edge-to-edge image (no default container chrome):
+ * <Sidebar.Card unstyled>
+ *   <img src="/promo.jpg" alt="" className="w-full rounded-[var(--card-radius)]" />
+ * </Sidebar.Card>
+ */
+const SidebarCard = React__default.forwardRef(({ children, className, unstyled = false, theme: customTheme, ...props }, ref) => {
+    const { isCollapsedView } = useSidebarCollapsed();
+    const theme = useMemo(() => ({ ...sidebarCardTheme, ...customTheme }), [customTheme]);
+    // Card is visible when expanded. Hide immediately on collapse (so the
+    // AnimatePresence exit + popLayout reflow happens in parallel with the
+    // rail narrowing). On expand, wait for the sidebar spring to settle
+    // before mounting — see `MOUNT_DELAY_MS` rationale.
+    const [shouldShow, setShouldShow] = useState(!isCollapsedView);
+    useEffect(() => {
+        if (isCollapsedView) {
+            setShouldShow(false);
+            return;
+        }
+        const id = setTimeout(() => setShouldShow(true), MOUNT_DELAY_MS);
+        return () => clearTimeout(id);
+    }, [isCollapsedView]);
+    // Strip drag/animation DOM handlers that collide with motion's prop types
+    // (same pattern the other Sidebar pieces use, e.g. Sidebar.tsx:54-61).
+    const { onAnimationStart, onAnimationEnd, onDrag, onDragStart, onDragEnd, ...motionSafeProps } = props;
+    return (
+    // `mode="popLayout"` removes the exiting card from the layout flow
+    // immediately so siblings (footer, nav rows below) snap into their new
+    // positions without waiting on the card's exit animation.
+    jsx(AnimatePresence, { initial: false, mode: "popLayout", children: shouldShow && (jsx(motion.div, { ref: ref, initial: { opacity: 0, x: -16 }, animate: { opacity: 1, x: 0 }, exit: { opacity: 0, x: -16 }, transition: { duration: 0.2, ease: [0.4, 0, 0.2, 1] }, className: cn(theme.wrapperStyle, 
+            // Default card chrome (rounded / bg / border / p-3) unless the
+            // consumer opts out. className wins per shadcn rules.
+            !unstyled && theme.baseStyle, className), ...motionSafeProps, children: children }, "sidebar-card")) }));
+});
+SidebarCard.displayName = "SidebarCard";
+
+export { SidebarCard };

package/dist/components/core/Sidebar/SidebarCard.theme.d.ts

@@ -0,0 +1,8 @@
+import { SidebarCardTheme } from "./Sidebar.types";
+/**
+ * Default theme for `<Sidebar.Card>`. Small surface — the component itself
+ * only renders a single styled wrapper that disappears on collapse, so the
+ * theme just holds the default outer chrome. Set `unstyled` on the card to
+ * skip it entirely (e.g. for full-bleed images).
+ */
+export declare const sidebarCardTheme: SidebarCardTheme;