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

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;

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

@@ -0,0 +1,18 @@
+/**
+ * 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).
+ */
+const sidebarCardTheme = {
+    // Card chrome — surface bg, hairline border, sidebar-tuned padding (p-3 is
+    // tighter than core/Card's p-6 because the rail is narrow). `overflow-hidden`
+    // keeps any children clipped to the rounded corners.
+    baseStyle: "rounded-[var(--card-radius)] bg-[var(--color-surface)] border border-[var(--color-border)] p-3 overflow-hidden",
+    // Wrapper applied in both styled + unstyled modes. Empty by default —
+    // the slide/fade animation lives on motion.div itself, not on this layer,
+    // so no overflow trickery needed here.
+    wrapperStyle: "",
+};
+
+export { sidebarCardTheme };

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

@@ -8,7 +8,11 @@ import '../ScrollArea/smooth/SmoothScrollEngine.js';
 const SidebarContent = React__default.forwardRef(({ children, className, ...props }, ref) => {
     const { isCollapsedView } = useSidebarCollapsed();
     const density = useSidebarDensity();
-    return (jsx(ScrollArea, { ref: ref, type: "none", size: "thin", className: "flex-1 min-h-0", ...props, children: jsx("div", { className: cn("py-3 transition-[padding] duration-200 ease-[cubic-bezier(0.4,0,0.2,1)]", density === "compact" && "py-2", isCollapsedView ? "px-2" : "px-2.5", className), children: children }) }));
+    return (jsx(ScrollArea, { ref: ref, type: "none", size: "thin", className: "flex-1 min-h-0", ...props, children: jsx("div", { className: cn("py-3 transition-[padding] duration-200 ease-[cubic-bezier(0.4,0,0.2,1)]", density === "compact" && "py-2", 
+            // Collapsed px-3 (12) on a 60px rail leaves a 36px interior — every
+            // child row (NavItem, Sidebar.Search) is exactly 36px wide, matching
+            // the 36×36 hit-area target.
+            isCollapsedView ? "px-3" : "px-2.5", className), children: children }) }));
 });
 SidebarContent.displayName = "SidebarContent";
 

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

@@ -98,7 +98,7 @@ const SidebarProvider = ({ children, defaultCollapsed = false, collapsed: contro
         toggleCollapsed,
         width: {
             expanded: width.expanded || 280,
-            collapsed: width.collapsed || 64,
+            collapsed: width.collapsed || 60,
         },
         side,
         variant,

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

@@ -8,12 +8,20 @@ import { Button } from '../Button/Button.js';
 
 const SidebarHeader = React__default.forwardRef(({ logo, showToggle = true, customToggle, children, className, ...props }, ref) => {
     const sidebarContext = useSidebarContext();
-    const { isMobile, isMobileOpen, isCollapsedView: isCollapsedDesktop } = useSidebarCollapsed();
+    const { isMobile, isMobileOpen } = useSidebarCollapsed();
     // If children are provided, use them instead of default layout
     if (children) {
         return (jsx("div", { ref: ref, className: cn("flex-shrink-0 border-b border-[var(--color-border)]", className), ...props, children: children }));
     }
-    return (jsxs("div", { ref: ref, className: cn("flex items-center flex-shrink-0 h-14 border-b border-[var(--color-border)] overflow-visible relative transition-[padding,background-color,border-color] duration-200 ease-[cubic-bezier(0.4,0,0.2,1)]", isCollapsedDesktop ? "px-4" : "px-3", className), ...props, children: [jsx("div", { className: cn("flex items-center min-w-0 flex-1"), children: logo }), isMobile && isMobileOpen && (jsx(Button, { variant: "ghost", size: "sm", className: "size-7 p-0 text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)]", onClick: () => sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.setMobileOpen(false), "aria-label": "Close navigation", children: jsx(XMarkIcon, { className: "size-4" }) })), !isMobile && showToggle && (customToggle || jsx(SidebarToggle, {}))] }));
+    return (jsxs("div", { ref: ref, className: cn("flex items-center flex-shrink-0 h-14 border-b border-[var(--color-border)] overflow-visible relative transition-[padding,background-color,border-color] duration-200 ease-[cubic-bezier(0.4,0,0.2,1)]", 
+        // Padding mirrors Sidebar.Content so the header logo sits on the
+        // same horizontal track as the NavItem rows below it. px-3 (12px)
+        // on the 60px collapsed rail leaves a 36px interior — a 32px logo
+        // (size-8) lands with 2px slack on each side; a 36px logo (size-9)
+        // fills the interior exactly. Left-pinned in both states (no
+        // `justify-*` toggle) so nothing jumps mid-animation. Same value
+        // for collapsed + expanded → no padding transition needed.
+        "px-3", className), ...props, children: [jsx("div", { className: "flex items-center min-w-0 flex-1", children: logo }), isMobile && isMobileOpen && (jsx(Button, { variant: "ghost", size: "sm", className: "size-7 p-0 text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)]", onClick: () => sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.setMobileOpen(false), "aria-label": "Close navigation", children: jsx(XMarkIcon, { className: "size-4" }) })), !isMobile && showToggle && (customToggle || jsx(SidebarToggle, {}))] }));
 });
 SidebarHeader.displayName = "SidebarHeader";
 

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

@@ -1,12 +1,47 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
+import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default from 'react';
 import { cn } from '../../../utils/cn.js';
 import { AnimatePresence, motion } from 'motion/react';
 import { useSidebarCollapsed } from './SidebarContext.js';
 
-const SidebarLogo = React__default.forwardRef(({ icon, text, className, ...props }, ref) => {
+const SidebarLogo = React__default.forwardRef(({ expanded, collapsed, expandedSrc, collapsedSrc, expandedImageClassName, collapsedImageClassName, alt = "", icon, text, className, ...props }, ref) => {
+    var _a, _b;
     const { isCollapsedView } = useSidebarCollapsed();
-    return (jsxs("div", { ref: ref, className: cn("flex items-center gap-2 overflow-hidden", className), ...props, children: [jsx("div", { className: "flex-shrink-0", children: icon }), jsx(AnimatePresence, { initial: false, children: !isCollapsedView && text && (jsx(motion.div, { className: "overflow-hidden whitespace-nowrap", initial: { opacity: 0, x: -8 }, animate: { opacity: 1, x: 0 }, exit: { opacity: 0, x: -8 }, transition: { duration: 0.15, ease: [0.4, 0, 0.2, 1] }, children: typeof text === "string" ? (jsx("span", { className: "text-base font-semibold tracking-tight text-[var(--color-text-primary)]", children: text })) : (text) }, "logo-text")) })] }));
+    // Auto-render <img> for the src convenience API. ReactNode props still win
+    // (full control); src is the easy path for plain image/SVG assets.
+    //
+    // Defaults:
+    //  - Collapsed: size-9 (36px) square, object-cover — matches the nav icon
+    //    track so the collapsed logo aligns visually with NavItem rows below.
+    //  - Expanded: h-8 w-auto object-contain — typical wordmark sizing.
+    // Override via `collapsedImageClassName` / `expandedImageClassName`
+    // (tailwind-merge resolves conflicts in favor of the user's classes).
+    const expandedNode = expanded !== null && expanded !== void 0 ? expanded : (expandedSrc ? (jsx("img", { src: expandedSrc, alt: alt, className: cn("h-8 w-auto object-contain", expandedImageClassName) })) : undefined);
+    const collapsedNode = collapsed !== null && collapsed !== void 0 ? collapsed : (collapsedSrc ? (jsx("img", { src: collapsedSrc, alt: alt, className: cn("size-9 object-cover", collapsedImageClassName) })) : undefined);
+    // New API takes precedence: if the user passed `expanded`/`collapsed`
+    // (ReactNode) OR their `*Src` shortcuts, render those (cross-faded).
+    // Otherwise fall back to the legacy icon-plus-animated-text rendering so
+    // existing consumers keep working.
+    const hasNewApi = expandedNode !== undefined || collapsedNode !== undefined;
+    if (hasNewApi) {
+        // Resolve the logo for the current state, falling all the way back to
+        // the legacy `icon` so a partial new-API usage still has something to
+        // show. Per-state fallback: collapsed → expanded → icon, and vice versa.
+        const currentLogo = isCollapsedView
+            ? (_a = collapsedNode !== null && collapsedNode !== void 0 ? collapsedNode : expandedNode) !== null && _a !== void 0 ? _a : icon
+            : (_b = expandedNode !== null && expandedNode !== void 0 ? expandedNode : collapsedNode) !== null && _b !== void 0 ? _b : icon;
+        return (jsx("div", { ref: ref, 
+            // No `overflow-hidden`: would clip wide logos in collapsed mode.
+            // Sidebar itself is `overflow-visible`.
+            className: cn("flex items-center", className), ...props, children: jsx(AnimatePresence, { mode: "wait", initial: false, children: jsx(motion.div, { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: { duration: 0.15, ease: [0.4, 0, 0.2, 1] }, className: "flex items-center", children: currentLogo }, isCollapsedView ? "collapsed" : "expanded") }) }));
+    }
+    // Legacy API: icon + animated text.
+    return (jsxs("div", { ref: ref, 
+        // No `overflow-hidden` here — that would clip the icon when the
+        // sidebar is collapsed and horizontal space is tight. The text
+        // collapse animation owns its own `overflow-hidden` on the motion.div
+        // below, which is the only place it's actually needed.
+        className: cn("flex items-center gap-2", className), ...props, children: [jsx("div", { className: "flex-shrink-0", children: icon }), jsx(AnimatePresence, { initial: false, children: !isCollapsedView && text && (jsx(motion.div, { className: "overflow-hidden whitespace-nowrap", initial: { opacity: 0, x: -8 }, animate: { opacity: 1, x: 0 }, exit: { opacity: 0, x: -8 }, transition: { duration: 0.15, ease: [0.4, 0, 0.2, 1] }, children: typeof text === "string" ? (jsx("span", { className: "text-base font-semibold tracking-tight text-[var(--color-text-primary)]", children: text })) : (text) }, "logo-text")) })] }));
 });
 SidebarLogo.displayName = "SidebarLogo";
 

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

@@ -0,0 +1,22 @@
+import React from "react";
+import { SidebarSearchProps } from "./Sidebar.types";
+/**
+ * Optional search field for the Sidebar. Emits the typed query via `onChange`
+ * (or via the controlled `value` prop) — does NOT filter the Sidebar tree itself.
+ * Consumers wire `onChange` to whatever surfaces results (popover, command palette,
+ * side panel, route, …) so the Sidebar stays visually clean.
+ *
+ * The collapse animation mirrors NavItem (single rendered structure across both
+ * states, icon always present in a fixed flex slot, the expanded content
+ * animates in/out via AnimatePresence). The field's border + surface fill fade
+ * out via a CSS transition so the collapsed rail just shows the icon — same
+ * look as the NavItem rows above it. Click the icon to expand the sidebar and
+ * focus the input. Opt out of the collapsed affordance with `hideWhenCollapsed`.
+ *
+ * Implementation note: this uses a small inline field instead of the shared
+ * `<Input>` so the icon + animated input can be siblings under one wrapper
+ * (Input's internal layout wouldn't permit the NavItem-style animation). The
+ * border/focus styling matches `formsBaseTheme.inputGroupBaseStyle` (inset
+ * box-shadow + ring) so it reads as a normal form control when expanded.
+ */
+export declare const SidebarSearch: React.ForwardRefExoticComponent<SidebarSearchProps & React.RefAttributes<HTMLInputElement>>;

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

@@ -0,0 +1,135 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import React__default, { useState, useRef, useEffect } from 'react';
+import { motion, AnimatePresence } from 'motion/react';
+import { MagnifyingGlassIcon } from '@heroicons/react/24/outline';
+import { cn } from '../../../utils/cn.js';
+import { Tooltip } from '../Tooltip/Tooltip.js';
+import '../Tooltip/Tooltip.animations.js';
+import { useSidebarContext, useSidebarCollapsed } from './SidebarContext.js';
+
+/**
+ * Optional search field for the Sidebar. Emits the typed query via `onChange`
+ * (or via the controlled `value` prop) — does NOT filter the Sidebar tree itself.
+ * Consumers wire `onChange` to whatever surfaces results (popover, command palette,
+ * side panel, route, …) so the Sidebar stays visually clean.
+ *
+ * The collapse animation mirrors NavItem (single rendered structure across both
+ * states, icon always present in a fixed flex slot, the expanded content
+ * animates in/out via AnimatePresence). The field's border + surface fill fade
+ * out via a CSS transition so the collapsed rail just shows the icon — same
+ * look as the NavItem rows above it. Click the icon to expand the sidebar and
+ * focus the input. Opt out of the collapsed affordance with `hideWhenCollapsed`.
+ *
+ * Implementation note: this uses a small inline field instead of the shared
+ * `<Input>` so the icon + animated input can be siblings under one wrapper
+ * (Input's internal layout wouldn't permit the NavItem-style animation). The
+ * border/focus styling matches `formsBaseTheme.inputGroupBaseStyle` (inset
+ * box-shadow + ring) so it reads as a normal form control when expanded.
+ */
+const SidebarSearch = React__default.forwardRef(({ value: controlledValue, defaultValue = "", onChange, placeholder = "Search…", size = "md", iconStart, collapsedLabel = "Search", hideWhenCollapsed = false, className, inputGroupClassName, ...props }, ref) => {
+    const context = useSidebarContext();
+    const { isCollapsedView } = useSidebarCollapsed();
+    const isControlled = controlledValue !== undefined;
+    const [internalValue, setInternalValue] = useState(defaultValue);
+    const value = isControlled ? controlledValue : internalValue;
+    // Compose the user's forwarded ref with our local ref so we can focus
+    // the input after the rail expands.
+    const inputRef = useRef(null);
+    const setInputRef = (el) => {
+        inputRef.current = el;
+        if (typeof ref === "function")
+            ref(el);
+        else if (ref)
+            ref.current = el;
+    };
+    // Focus the input on the frame *after* collapse→expand transitions, but only
+    // when the user triggered it from the icon click (not e.g. via Sidebar.Toggle,
+    // where stealing focus would be surprising).
+    const pendingFocusRef = useRef(false);
+    const wasCollapsedRef = useRef(isCollapsedView);
+    useEffect(() => {
+        if (wasCollapsedRef.current && !isCollapsedView && pendingFocusRef.current) {
+            const id = requestAnimationFrame(() => { var _a; return (_a = inputRef.current) === null || _a === void 0 ? void 0 : _a.focus(); });
+            pendingFocusRef.current = false;
+            wasCollapsedRef.current = isCollapsedView;
+            return () => cancelAnimationFrame(id);
+        }
+        wasCollapsedRef.current = isCollapsedView;
+    }, [isCollapsedView]);
+    const handleChange = (e) => {
+        const next = e.target.value;
+        if (!isControlled)
+            setInternalValue(next);
+        onChange === null || onChange === void 0 ? void 0 : onChange(next);
+    };
+    const handleExpand = () => {
+        if (!isCollapsedView)
+            return;
+        pendingFocusRef.current = true;
+        context === null || context === void 0 ? void 0 : context.setCollapsed(false);
+    };
+    const handleKeyDown = (e) => {
+        if (!isCollapsedView)
+            return;
+        if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            handleExpand();
+        }
+    };
+    if (isCollapsedView && hideWhenCollapsed)
+        return null;
+    // Form-field shell — same inset-shadow border + focus ring as the shared
+    // forms.theme.ts (inputGroupBaseStyle), kept in sync intentionally. CSS
+    // transitions on background + box-shadow let the field fade out cleanly
+    // as the rail collapses; AnimatePresence handles the input itself.
+    const shellExpanded = "bg-[var(--color-surface)] shadow-[inset_0_0_0_1px_var(--color-border)] " +
+        "focus-within:shadow-[inset_0_0_0_1px_var(--color-primary-600)] " +
+        "focus-within:ring-4 focus-within:ring-[var(--color-primary)]/10 " +
+        "not-focus-within:hover:shadow-[inset_0_0_0_1px_var(--color-border-secondary)] " +
+        "dark:focus-within:shadow-[inset_0_0_0_1px_var(--color-primary-500)] dark:focus-within:ring-[var(--color-primary-500)]/20";
+    // Collapsed: keep the surface fill so the icon reads as a search "button"
+    // (not a transparent row). Hover lifts to surface-hover.
+    const shellCollapsed = "bg-[var(--color-surface)] shadow-[inset_0_0_0_0_transparent] " +
+        "hover:bg-[var(--color-surface-hover)] cursor-pointer";
+    const tooltipPlacement = (context === null || context === void 0 ? void 0 : context.side) === "right" ? "left" : "right";
+    const field = (jsxs(motion.div, { role: isCollapsedView ? "button" : undefined, tabIndex: isCollapsedView ? 0 : undefined, "aria-label": isCollapsedView ? collapsedLabel : undefined, onClick: isCollapsedView ? handleExpand : undefined, onKeyDown: handleKeyDown, className: cn("relative flex items-center rounded-[var(--form-radius)]", 
+        // 36px (h-9) in BOTH states so the search row sits at the exact
+        // same height as the NavItem rows below it — same look expanded,
+        // same 36×36 square collapsed. `size` prop is currently a no-op
+        // for height; kept on the API surface for forward compatibility.
+        "h-9", 
+        // NOTE: do NOT toggle `justify-center` between states. Combined
+        // with the icon span's constant `pl-2`, the icon sits at the same
+        // field-x (8) in both states, so the *only* thing that animates
+        // on collapse/expand is the field width (via sidebar's motion
+        // width) and the input fading in/out via AnimatePresence. Adding
+        // a justify-* toggle here would snap the icon by 4px on frame 0
+        // of every transition.
+        "transition-[background-color,box-shadow] duration-200 ease-[cubic-bezier(0.4,0,0.2,1)]", "overflow-hidden", isCollapsedView ? shellCollapsed : shellExpanded, inputGroupClassName), children: [jsx("span", { className: cn("flex items-center justify-center flex-shrink-0 pl-2", "text-[var(--color-text-muted)] transition-colors duration-200"), "aria-hidden": !isCollapsedView || undefined, children: iconStart !== null && iconStart !== void 0 ? iconStart : jsx(MagnifyingGlassIcon, { className: "size-5" }) }), jsx(AnimatePresence, { initial: false, children: !isCollapsedView && (jsx(motion.div, { initial: { opacity: 0, x: -4 }, animate: { opacity: 1, x: 0 }, exit: { opacity: 0, x: -4 }, transition: {
+                        opacity: { duration: 0.15, ease: [0.4, 0, 0.2, 1] },
+                        x: { duration: 0.2, ease: [0.4, 0, 0.2, 1] },
+                    }, className: "flex-1 min-w-0 flex items-center overflow-hidden", children: jsx("input", { ref: setInputRef, type: "search", value: value, onChange: handleChange, placeholder: placeholder, "aria-label": collapsedLabel, className: cn(
+                        // Icon span pl-2 (8) + icon size-5 (20) = field-x 8-28.
+                        // Input pl-3 (12) → text starts at field-x = 28 + 12 = 40,
+                        // giving a 12px icon→text gap (matches <Input iconStart>'s
+                        // pl-3 + pl-10 = 12px convention).
+                        "w-full bg-transparent border-0 outline-none text-sm py-2 pl-3 pr-3", "text-[var(--color-text-primary)] placeholder:text-[var(--color-text-placeholder)]", "dark:placeholder:text-[var(--color-neutral-500)]") }) }, "search-input")) })] }));
+    return (
+    // Outer horizontal padding mirrors Sidebar.Content (px-3 collapsed,
+    // px-2.5 expanded) so the search row sits on the exact same horizontal
+    // track as the NavItem rows below it — both have a 36px interior on
+    // the 60px collapsed rail, producing identical 36×36 hit-areas.
+    jsx("div", { className: cn(
+        // py-1 keeps the search row in the same vertical rhythm as the
+        // NavGroup's `space-y-1` between nav rows.
+        "py-1 transition-[padding] duration-200 ease-[cubic-bezier(0.4,0,0.2,1)]", isCollapsedView ? "px-3" : "px-2.5", className), ...props, children: isCollapsedView ? (
+        // `triggerClassName="block w-full"` makes the Tooltip's wrapping div
+        // a full-width block instead of its default `inline-block` — without
+        // this, the field collapses to icon-width and sits left-aligned,
+        // leaving empty space on the right of the rail. Same fix NavItem
+        // uses for its collapsed-mode tooltip wrapper.
+        jsx(Tooltip, { content: collapsedLabel, placement: tooltipPlacement, triggerClassName: "block w-full", children: field })) : (field) }));
+});
+SidebarSearch.displayName = "SidebarSearch";
+
+export { SidebarSearch };

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

@@ -25,7 +25,7 @@ const SidebarToggle = React__default.forwardRef(({ expandIcon, collapseIcon, cla
     const positionClasses = side === "left"
         ? "absolute right-0 translate-x-1/2 top-4 z-50"
         : "absolute left-0 -translate-x-1/2 top-4 z-50";
-    return (jsx(Button, { ref: ref, iconOnly: true, variant: "ghost", className: cn("size-6 p-0 rounded-full border border-[var(--color-border)] bg-[var(--color-background)]/50 backdrop-blur-sm text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:shadow-md hover:bg-[var(--color-surface-hover)] opacity-100 transition-all duration-400", positionClasses, className), onClick: handleClick, "aria-label": collapsed ? "Expand sidebar" : "Collapse sidebar", title: collapsed ? "Expand sidebar" : "Collapse sidebar", ...buttonProps, children: jsx(motion.div, { initial: false, animate: { rotate: collapsed ? 180 : 0 }, transition: { duration: 0.2, ease: [0.4, 0, 0.2, 1] }, className: "flex items-center justify-center", children: jsx(ChevronLeftIcon, { className: "size-3", strokeWidth: 2.5 }) }) }));
+    return (jsx(Button, { ref: ref, iconOnly: true, variant: "ghost", className: cn("size-6 p-0 rounded-full border border-[var(--color-border)] bg-[var(--color-background)]/50 backdrop-blur-sm text-[var(--color-text-muted)] hover:text-[var(--color-text-secondary)] hover:shadow-md hover:bg-[var(--color-surface-hover)] opacity-100 transition-all duration-400", positionClasses, className), onClick: handleClick, "aria-label": collapsed ? "Expand sidebar" : "Collapse sidebar", title: collapsed ? "Expand sidebar" : "Collapse sidebar", ...buttonProps, children: jsx(motion.div, { initial: false, animate: { rotate: collapsed ? 180 : 0 }, transition: { duration: 0.2, ease: [0.4, 0, 0.2, 1] }, className: "flex items-center justify-center", children: jsx(ChevronLeftIcon, { className: "size-3", strokeWidth: 2.5 }) }) }));
 });
 SidebarToggle.displayName = "SidebarToggle";
 

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

@@ -19,8 +19,8 @@ const SidebarUserProfile = React__default.forwardRef(({ name, email, avatar, sta
     const { isCollapsedView } = useSidebarCollapsed();
     // Strip drag/animation DOM handlers that collide with motion's prop types
     const { onAnimationStart, onAnimationEnd, onDrag, onDragStart, onDragEnd, ...motionSafeProps } = props;
-    const avatarElement = (jsx(Avatar, { src: avatar, name: name, size: isCollapsedView ? "sm" : "md", status: status !== null && status !== void 0 ? status : "none" }));
-    const content = (jsxs(motion.div, { ref: ref, className: cn("flex w-full items-center rounded-[var(--radius-base)] cursor-pointer border border-transparent transition-[padding,gap,background-color,border-color,color,box-shadow] duration-200 ease-[cubic-bezier(0.4,0,0.2,1)] ", isCollapsedView ? "justify-center gap-0 px-1 py-2" : "gap-2 ", className), role: "button", tabIndex: 0, onClick: onClick, onKeyDown: (e) => {
+    const avatarElement = (jsx(Avatar, { src: avatar, name: name, status: status !== null && status !== void 0 ? status : "none", className: "size-9" }));
+    const content = (jsxs(motion.div, { ref: ref, className: cn("flex w-full items-center rounded-[var(--radius-base)] cursor-pointer border border-transparent transition-[padding,gap,background-color,border-color,color,box-shadow] duration-200 ease-[cubic-bezier(0.4,0,0.2,1)] ", isCollapsedView ? "justify-center gap-0 px-1" : "gap-2 ", className), role: "button", tabIndex: 0, onClick: onClick, onKeyDown: (e) => {
             if ((e.key === "Enter" || e.key === " ") && onClick) {
                 e.preventDefault();
                 e.currentTarget.click();

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

@@ -8,5 +8,7 @@ export { SidebarToggle } from "./SidebarToggle";
 export { SidebarMobileTrigger } from "./SidebarMobileTrigger";
 export { SidebarUserProfile } from "./SidebarUserProfile";
 export { SidebarLogo } from "./SidebarLogo";
+export { SidebarSearch } from "./SidebarSearch";
+export { SidebarCard } from "./SidebarCard";
 export { SidebarProvider, useSidebarContext } from "./SidebarContext";
-export type { SidebarProps, SidebarHeaderProps, SidebarContentProps, SidebarFooterProps, SidebarNavProps, SidebarNavGroupProps, SidebarToggleProps, SidebarMobileTriggerProps, SidebarUserProfileProps, SidebarUserStatus, SidebarSide, SidebarVariant, SidebarDensity, SidebarContextValue, SidebarProviderProps, SidebarTheme, SidebarThemeOverrides, SidebarLogoProps, } from "./Sidebar.types";
+export type { SidebarProps, SidebarHeaderProps, SidebarContentProps, SidebarFooterProps, SidebarNavProps, SidebarNavGroupProps, SidebarToggleProps, SidebarMobileTriggerProps, SidebarUserProfileProps, SidebarUserStatus, SidebarSide, SidebarVariant, SidebarDensity, SidebarContextValue, SidebarProviderProps, SidebarTheme, SidebarThemeOverrides, SidebarLogoProps, SidebarSearchProps, SidebarCardProps, SidebarCardTheme, SidebarCardThemeOverrides, } from "./Sidebar.types";

package/dist/components/core/Tag/Tag.js

@@ -1,4 +1,4 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { motion } from 'motion/react';
 import { XMarkIcon } from '@heroicons/react/24/outline';
@@ -18,7 +18,7 @@ import { tagVariants, tagLayoutTransition } from './Tag.animations.js';
  * <Tag startContent={<CodeIcon className="size-4" />} onRemove={() => {}}>React</Tag>
  * ```
  */
-const Tag = React__default.forwardRef(({ children, size = "md", removable = true, onRemove, avatar, startContent, disabled = false, className, theme: customTheme, ...props }, ref) => {
+const Tag = React__default.forwardRef(({ children, size = "md", removable = true, onRemove, avatar, startContent, disabled = false, animated = true, className, theme: customTheme, ...props }, ref) => {
     var _a, _b, _c;
     // Merge default theme with custom theme overrides
     const theme = {
@@ -47,14 +47,38 @@ const Tag = React__default.forwardRef(({ children, size = "md", removable = true
     // Avatar takes precedence over startContent
     const renderLeadingContent = () => {
         if (avatar) {
-            return (jsx("span", { className: cn("inline-flex items-center justify-center shrink-0 overflow-hidden rounded-full", theme.avatarSizes[size]), children: jsx(Avatar, { src: avatar.src, name: avatar.name, fallback: avatar.fallback, initialsCount: avatar.initialsCount, size: "xs", className: "!size-full border-0 rounded-full" }) }));
+            return (jsx("span", { 
+                // leading-[0] collapses the inline line-box strut: the Avatar's
+                // inner circle is inline-flex, so a non-zero line-height adds
+                // descender space below it and pins the circle to the top of a
+                // taller line box — the visible photo then renders ~1.75px high.
+                // Zeroing the line-height makes the 16px circle define the box exactly.
+                className: cn("inline-flex items-center justify-center shrink-0 overflow-hidden rounded-full leading-[0]", theme.avatarSizes[size]), children: jsx(Avatar, { src: avatar.src, name: avatar.name, fallback: avatar.fallback, initialsCount: avatar.initialsCount, size: "xs", className: "bg-[var(--color-surface-hover)] border  border-[var(--color-border)]" }) }));
         }
         if (startContent) {
-            return (jsx("span", { className: cn("inline-flex items-center justify-center shrink-0", theme.startContentSizes[size]), children: startContent }));
+            return (jsx("span", { 
+                // leading-[0]: same line-box collapse as the avatar wrapper above,
+                // so inline startContent (icons/emoji) stays vertically centered.
+                className: cn("inline-flex items-center justify-center shrink-0 leading-[0]", theme.startContentSizes[size]), children: startContent }));
         }
         return null;
     };
-    return (jsxs(motion.span, { ref: ref, className: cn(theme.baseStyle, theme.sizes[size], hasLeadingContent && "pl-0.5", showRemoveButton && "pr-0.5", disabled && theme.disabledStyle, className), layout: true, transition: tagLayoutTransition, variants: tagVariants, exit: "exit", "data-size": size, "data-disabled": disabled ? "true" : "false", "data-removable": removable ? "true" : "false", "data-has-avatar": avatar ? "true" : "false", ...props, children: [renderLeadingContent(), children, showRemoveButton && (jsx("button", { type: "button", onClick: handleRemove, className: theme.removeButtonStyle, "aria-label": `Remove ${typeof children === "string" ? children : "tag"}`, children: jsx(XMarkIcon, { className: theme.removeIconSizes[size] }) }))] }));
+    const content = (jsxs(Fragment, { children: [renderLeadingContent(), children, showRemoveButton && (jsx("button", { type: "button", onClick: handleRemove, className: theme.removeButtonStyle, "aria-label": `Remove ${typeof children === "string" ? children : "tag"}`, children: jsx(XMarkIcon, { className: theme.removeIconSizes[size] }) }))] }));
+    const sharedProps = {
+        ref,
+        className: cn(theme.baseStyle, theme.sizes[size], hasLeadingContent && "pl-1", showRemoveButton && "pr-0.5", disabled && theme.disabledStyle, className),
+        "data-size": size,
+        "data-disabled": disabled ? "true" : "false",
+        "data-removable": removable ? "true" : "false",
+        "data-has-avatar": avatar ? "true" : "false",
+        ...props,
+    };
+    // Plain span when animation is opted out (e.g. inside a contentEditable host,
+    // where Framer-Motion's layout FLIP fights the caret on every keystroke).
+    if (!animated) {
+        return jsx("span", { ...sharedProps, children: content });
+    }
+    return (jsx(motion.span, { ...sharedProps, layout: true, transition: tagLayoutTransition, variants: tagVariants, exit: "exit", children: content }));
 });
 Tag.displayName = "Tag";
 

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

@@ -1,18 +1,23 @@
 const tagTheme = {
-    baseStyle: "inline-flex items-center gap-1 font-medium rounded-full " +
-        "bg-[var(--color-background-surface)] dark:bg-[var(--color-background-secondary)] border border-[var(--color-border)] " +
+    baseStyle: "inline-flex items-center gap-1.5 font-medium rounded-full " +
+        "bg-[var(--color-surface-raised)] border border-[var(--color-border)] " +
         "text-[var(--color-text-primary)]",
     sizes: {
-        sm: "text-xs px-2.5 py-0.5",
-        md: "text-sm px-2.5 py-0.5",
+        sm: "text-xs px-2 py-0.5",
+        md: "text-sm px-2 py-0.5",
     },
+    // No left margin here: the avatar/icon's left inset is owned by the tag's
+    // `pl-1` (applied when there's leading content), not by a per-size `ml-*`.
+    // Stacking `ml-*` on top of that padding pushed the avatar too far from the
+    // left edge and produced a lopsided pill. The avatar-to-text gap is handled
+    // by the base `gap-1`, not by this margin.
     avatarSizes: {
-        sm: "size-4 ml-0.5",
-        md: "size-5 ml-1",
+        sm: "size-4",
+        md: "size-5",
     },
     startContentSizes: {
-        sm: "ml-0.5",
-        md: "ml-1",
+        sm: "",
+        md: "",
     },
     disabledStyle: "opacity-50 cursor-not-allowed",
     removeButtonStyle: "inline-flex items-center justify-center rounded-full p-1 " +