@womp/kookie-ui 0.3.22

package/src/components/sidebar.tsx

@@ -0,0 +1,880 @@
+'use client';
+
+import * as React from 'react';
+import classNames from 'classnames';
+import { Slot } from './slot.js';
+import * as Accordion from '@radix-ui/react-accordion';
+import * as DropdownMenu from './dropdown-menu.js';
+import * as Popover from './popover.js';
+
+import { sidebarPropDefs } from './sidebar.props.js';
+import { useThemeContext } from './theme.js';
+// import { IconButton } from './icon-button.js';
+import { ScrollArea } from './scroll-area.js';
+import { Separator } from './separator.js';
+import { ThickChevronRightIcon } from './icons.js';
+import { extractProps } from '../helpers/extract-props.js';
+import { Kbd } from './kbd.js';
+import { Badge } from './badge.js';
+
+import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-props.js';
+import type { GetPropDefTypes } from '../props/prop-def.js';
+import type { BadgeProps } from './badge.js';
+
+// Badge configuration type for sidebar menu buttons
+type BadgeConfig = {
+  content: React.ReactNode;
+  variant?: BadgeProps['variant'];
+  size?: BadgeProps['size'];
+  color?: BadgeProps['color'];
+  highContrast?: BadgeProps['highContrast'];
+  radius?: BadgeProps['radius'];
+};
+
+// Internal presentational context (not exported) for size/menu variant
+type SidebarVisualContextValue = {
+  size: '1' | '2' | '3';
+  menuVariant: 'solid' | 'soft';
+  presentation?: 'thin' | 'expanded';
+  color?: string;
+};
+const SidebarVisualContext = React.createContext<SidebarVisualContextValue | null>(null);
+function useSidebarVisual() {
+  return React.useContext(SidebarVisualContext);
+}
+
+// Sidebar is now independent of Shell - no integration needed
+
+// Main Sidebar component
+type SidebarOwnProps = GetPropDefTypes<typeof sidebarPropDefs>;
+interface SidebarProps extends ComponentPropsWithout<'div', RemovedProps>, SidebarOwnProps {
+  /**
+   * Presentational mode independent of Shell.
+   * 'thin' renders a rail-style sidebar, 'expanded' renders a panel-style sidebar.
+   * If both `presentation` and `layout` are provided, `presentation` takes precedence.
+   */
+  presentation?: 'thin' | 'expanded';
+}
+
+const Sidebar = React.forwardRef<HTMLDivElement, SidebarProps>((props, forwardedRef) => {
+  const themeContext = useThemeContext();
+
+  const {
+    size = sidebarPropDefs.size.default,
+    variant = sidebarPropDefs.variant.default,
+    menuVariant = sidebarPropDefs.menuVariant.default,
+    layout = sidebarPropDefs.layout.default,
+    presentation,
+    // type = sidebarPropDefs.type.default,
+    // side = sidebarPropDefs.side.default,
+    // collapsible = sidebarPropDefs.collapsible.default,
+    panelBackground,
+    color,
+    highContrast = sidebarPropDefs.highContrast.default,
+  } = props;
+
+  const { className, children, ...rootProps } = extractProps(props, sidebarPropDefs);
+  // Remove internal-only props from DOM
+  const { asChild: _, panelBackground: __, presentation: ___, ...safeRootProps } = rootProps;
+  const resolvedColor = color || themeContext.accentColor;
+
+  // Resolve layout (default to 'panel'). `presentation` takes precedence over `layout`.
+  const resolvedLayout = presentation === 'thin' ? 'rail' : presentation === 'expanded' ? 'panel' : layout || 'panel';
+
+  // Update context with current props - we'll pass the resolved values
+  const resolvedSize = typeof size === 'object' ? size.initial || '2' : size;
+  const visualContextValue = React.useMemo(
+    () => ({ size: resolvedSize, menuVariant, presentation, color: resolvedColor }),
+    [resolvedSize, menuVariant, presentation, resolvedColor],
+  );
+  return (
+    <div {...safeRootProps} ref={forwardedRef} data-accent-color={resolvedColor} className={classNames('rt-SidebarRoot', className)}>
+      <SidebarVisualContext.Provider value={visualContextValue}>
+        <div
+          className={classNames('rt-SidebarContainer', `rt-variant-${variant}`, `rt-r-size-${resolvedSize}`, `rt-menu-variant-${menuVariant}`, resolvedLayout && `rt-layout-${resolvedLayout}`)}
+          data-accent-color={resolvedColor}
+          data-high-contrast={highContrast || undefined}
+          data-panel-background={panelBackground}
+          data-presentation={presentation}
+          data-layout={resolvedLayout}
+        >
+          {children}
+        </div>
+      </SidebarVisualContext.Provider>
+    </div>
+  );
+});
+Sidebar.displayName = 'Sidebar.Root';
+
+// Sidebar content area
+interface SidebarContentProps extends React.ComponentPropsWithoutRef<'div'> {
+  id?: string;
+  role?: 'navigation' | 'none';
+  'aria-label'?: string;
+}
+
+const SidebarContent = React.forwardRef<HTMLDivElement, SidebarContentProps>(
+  ({ className, children, role = 'navigation', 'aria-label': ariaLabel = 'Main navigation', id, ...props }, forwardedRef) => {
+    const visual = useSidebarVisual();
+    const size = visual?.size ?? '2';
+    const menuVariant = visual?.menuVariant ?? 'soft';
+
+    return (
+      <ScrollArea type="hover">
+        <div
+          {...props}
+          ref={forwardedRef}
+          id={id}
+          role={role}
+          aria-label={ariaLabel}
+          className={classNames('rt-BaseMenuContent', 'rt-SidebarContent', `rt-r-size-${size}`, `rt-menu-variant-${menuVariant}`, className)}
+        >
+          <div className="rt-BaseMenuViewport">{children}</div>
+        </div>
+      </ScrollArea>
+    );
+  },
+);
+SidebarContent.displayName = 'Sidebar.Content';
+
+// Sidebar header
+interface SidebarHeaderProps extends React.ComponentPropsWithoutRef<'div'> {
+  /**
+   * Whether to use the default flex container layout.
+   * @default true
+   */
+  asContainer?: boolean;
+}
+
+const SidebarHeader = React.forwardRef<HTMLDivElement, SidebarHeaderProps>(({ className, asContainer = true, ...props }, forwardedRef) => {
+  const visual = useSidebarVisual();
+  const size = visual?.size ?? '2';
+  const menuVariant = visual?.menuVariant ?? 'soft';
+
+  return (
+    <div
+      {...props}
+      ref={forwardedRef}
+      className={classNames(
+        'rt-SidebarHeader',
+        `rt-r-size-${size}`,
+        `rt-menu-variant-${menuVariant}`,
+        {
+          'rt-SidebarHeader--container': asContainer,
+        },
+        className,
+      )}
+    />
+  );
+});
+SidebarHeader.displayName = 'Sidebar.Header';
+
+// Sidebar footer
+interface SidebarFooterProps extends React.ComponentPropsWithoutRef<'div'> {
+  /**
+   * Whether to use the default flex container layout.
+   * @default true
+   */
+  asContainer?: boolean;
+}
+
+const SidebarFooter = React.forwardRef<HTMLDivElement, SidebarFooterProps>(({ className, asContainer = true, ...props }, forwardedRef) => {
+  const visual = useSidebarVisual();
+  const size = visual?.size ?? '2';
+  const menuVariant = visual?.menuVariant ?? 'soft';
+
+  return (
+    <div
+      {...props}
+      ref={forwardedRef}
+      className={classNames(
+        'rt-SidebarFooter',
+        `rt-r-size-${size}`,
+        `rt-menu-variant-${menuVariant}`,
+        {
+          'rt-SidebarFooter--container': asContainer,
+        },
+        className,
+      )}
+    />
+  );
+});
+SidebarFooter.displayName = 'Sidebar.Footer';
+
+// Sidebar trigger button
+// removed Trigger in presentational-only Sidebar
+
+// Removed SidebarInset - not needed
+
+// Sidebar separator
+interface SidebarSeparatorProps extends ComponentPropsWithout<typeof Separator, RemovedProps> {}
+
+const SidebarSeparator = React.forwardRef<React.ComponentRef<typeof Separator>, SidebarSeparatorProps>(({ className, ...props }, forwardedRef) => (
+  <Separator {...props} ref={forwardedRef} className={classNames('rt-SidebarSeparator', className)} />
+));
+SidebarSeparator.displayName = 'Sidebar.Separator';
+
+// Menu components - reusing dropdown menu structure
+interface SidebarMenuProps extends React.ComponentPropsWithoutRef<'ul'> {}
+
+const SidebarMenu = React.forwardRef<HTMLUListElement, SidebarMenuProps>(({ className, ...props }, forwardedRef) => (
+  <ul {...props} ref={forwardedRef} role="menu" className={classNames('rt-SidebarMenu', className)} />
+));
+SidebarMenu.displayName = 'Sidebar.Menu';
+
+interface SidebarMenuItemProps extends React.ComponentPropsWithoutRef<'li'> {}
+
+const SidebarMenuItem = React.forwardRef<HTMLLIElement, SidebarMenuItemProps>(({ className, ...props }, forwardedRef) => (
+  <li {...props} ref={forwardedRef} className={classNames('rt-SidebarMenuItem', className)} />
+));
+SidebarMenuItem.displayName = 'Sidebar.MenuItem';
+
+interface SidebarMenuButtonProps extends React.ComponentPropsWithoutRef<'button'> {
+  asChild?: boolean;
+  isActive?: boolean;
+  shortcut?: React.ReactNode;
+  badge?: string | BadgeConfig;
+}
+
+// Extracted to module scope to avoid re-creation on every render
+function separateIconsAndLabels(node: React.ReactNode): { icons: React.ReactNode[]; labels: React.ReactNode[] } {
+  const icons: React.ReactNode[] = [];
+  const labels: React.ReactNode[] = [];
+
+  React.Children.forEach(node, (child) => {
+    if (typeof child === 'string' || typeof child === 'number') {
+      labels.push(<span key={labels.length} className="rt-SidebarMenuLabel">{child}</span>);
+    } else if (React.isValidElement(child)) {
+      const el = child as React.ReactElement<any>;
+      if (el.type === 'svg' || (el.props && el.props.icon) || (typeof el.type === 'function' && ((el.type as any).displayName?.includes('Icon') || (el.type as any).name?.includes('Icon')))) {
+        icons.push(child);
+      } else {
+        labels.push(child);
+      }
+    } else if (child) {
+      labels.push(child);
+    }
+  });
+
+  return { icons, labels };
+}
+
+function wrapTextNodes(node: React.ReactNode): React.ReactNode {
+  if (typeof node === 'string' || typeof node === 'number') {
+    return <span className="rt-SidebarMenuLabel">{node}</span>;
+  }
+  if (Array.isArray(node)) {
+    return node.map((child, index) => <React.Fragment key={index}>{wrapTextNodes(child)}</React.Fragment>);
+  }
+  if (React.isValidElement(node)) {
+    const el = node as React.ReactElement<any>;
+    const className: string = (el.props && (el.props as any).className) || '';
+    const isAlreadyLabel = typeof el.type === 'string' && className.split(' ').includes('rt-SidebarMenuLabel');
+    if (isAlreadyLabel) return el;
+    const newChildren = wrapTextNodes((el.props as any)?.children);
+    return React.cloneElement(el, { ...(el.props as any) }, newChildren);
+  }
+  return node;
+}
+
+const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenuButtonProps>(
+  ({ asChild = false, isActive = false, shortcut, badge, className, children, onKeyDown, ...props }, forwardedRef) => {
+    const visual = useSidebarVisual();
+    const sidebarSize = visual?.size ?? '2';
+    const isThinMode = visual?.presentation === 'thin';
+
+    const Comp = asChild ? Slot : 'button';
+
+    const { onClick } = props;
+    const handleKeyDown = React.useCallback(
+      (event: React.KeyboardEvent<HTMLButtonElement>) => {
+        switch (event.key) {
+          case 'Enter':
+          case ' ':
+            event.preventDefault();
+            if (onClick) onClick(event as any);
+            break;
+          case 'ArrowDown': {
+            event.preventDefault();
+            // Focus next menu item
+            const nextItem = (event.currentTarget as HTMLElement).nextElementSibling?.querySelector('[role="menuitem"]') as HTMLElement;
+            if (nextItem) nextItem.focus();
+            break;
+          }
+          case 'ArrowUp': {
+            event.preventDefault();
+            // Focus previous menu item
+            const prevItem = (event.currentTarget as HTMLElement).previousElementSibling?.querySelector('[role="menuitem"]') as HTMLElement;
+            if (prevItem) prevItem.focus();
+            break;
+          }
+        }
+        onKeyDown?.(event);
+      },
+      [onClick, onKeyDown],
+    );
+
+    // Memoize child processing to avoid re-traversal on every render
+    const processedChildren = React.useMemo(() => wrapTextNodes(children), [children]);
+
+    // For thin mode, separate icons into a wrapper for targeted background styling
+    const { icons, labels } = React.useMemo(
+      () => isThinMode ? separateIconsAndLabels(children) : { icons: [] as React.ReactNode[], labels: [] as React.ReactNode[] },
+      [isThinMode, children],
+    );
+
+    // When rendering asChild, Slot expects a single child element. We still want to
+    // append optional badge/shortcut inside that element so they render with Link.
+    const slottedChildren = React.useMemo(() => {
+      if (!asChild) return null;
+      try {
+        const onlyChild = React.Children.only(processedChildren as React.ReactElement<any>) as React.ReactElement<any>;
+        const originalInnerChildren = (onlyChild.props as any)?.children;
+        const enhancedInnerChildren = (
+          <>
+            {originalInnerChildren}
+            {badge && (
+              <div className="rt-SidebarMenuBadge">
+                {typeof badge === 'string' ? (
+                  <Badge size={sidebarSize} variant="soft">
+                    {badge}
+                  </Badge>
+                ) : (
+                  <Badge size={badge.size || sidebarSize} variant={badge.variant || 'soft'} color={badge.color} highContrast={badge.highContrast} radius={badge.radius}>
+                    {badge.content}
+                  </Badge>
+                )}
+              </div>
+            )}
+            {shortcut && (
+              <div className="rt-BaseMenuShortcut rt-SidebarMenuShortcut">
+                <Kbd size={sidebarSize}>{shortcut}</Kbd>
+              </div>
+            )}
+          </>
+        );
+        return React.cloneElement(onlyChild, { ...(onlyChild.props as any) }, enhancedInnerChildren);
+      } catch {
+        // Fallback: if multiple children were passed incorrectly, just return processedChildren
+        return processedChildren as React.ReactNode;
+      }
+    }, [asChild, processedChildren, badge, shortcut, sidebarSize]);
+
+    return (
+      <Comp
+        {...props}
+        ref={forwardedRef}
+        role="menuitem"
+        aria-current={isActive ? 'page' : undefined}
+        className={classNames('rt-reset', 'rt-BaseMenuItem', 'rt-SidebarMenuButton', className)}
+        data-active={isActive || undefined}
+        onKeyDown={handleKeyDown}
+      >
+        {asChild ? (
+          slottedChildren
+        ) : isThinMode && icons.length > 0 ? (
+          <>
+            <span className="rt-SidebarMenuIconWrapper">{icons}</span>
+            {labels.map((label, index) => (
+              <React.Fragment key={index}>
+                {typeof label === 'string' || typeof label === 'number' ? (
+                  <span className="rt-SidebarMenuLabel">{label}</span>
+                ) : (
+                  label
+                )}
+              </React.Fragment>
+            ))}
+          </>
+        ) : (
+          <>
+            {processedChildren}
+            {badge && (
+              <div className="rt-SidebarMenuBadge">
+                {typeof badge === 'string' ? (
+                  <Badge size={sidebarSize} variant="soft">
+                    {badge}
+                  </Badge>
+                ) : (
+                  <Badge size={badge.size || sidebarSize} variant={badge.variant || 'soft'} color={badge.color} highContrast={badge.highContrast} radius={badge.radius}>
+                    {badge.content}
+                  </Badge>
+                )}
+              </div>
+            )}
+            {shortcut && (
+              <div className="rt-BaseMenuShortcut rt-SidebarMenuShortcut">
+                <Kbd size={sidebarSize}>{shortcut}</Kbd>
+              </div>
+            )}
+          </>
+        )}
+      </Comp>
+    );
+  },
+);
+SidebarMenuButton.displayName = 'Sidebar.MenuButton';
+
+// Sub-menu components: Accordion in expanded, Dropdown in thin
+const SidebarSubMenuModeContext = React.createContext<'accordion' | 'dropdown'>('accordion');
+interface SidebarMenuSubProps extends React.ComponentPropsWithoutRef<'div'> {
+  defaultOpen?: boolean;
+}
+
+const SidebarMenuSub = React.forwardRef<HTMLDivElement, SidebarMenuSubProps>(({ defaultOpen = false, children, ...props }, forwardedRef) => {
+  const visual = useSidebarVisual();
+  const mode: 'accordion' | 'dropdown' = visual?.presentation === 'thin' ? 'dropdown' : 'accordion';
+
+  if (mode === 'dropdown') {
+    return (
+      <div {...props} ref={forwardedRef}>
+        <DropdownMenu.Root>
+          <SidebarSubMenuModeContext.Provider value="dropdown">{children}</SidebarSubMenuModeContext.Provider>
+        </DropdownMenu.Root>
+      </div>
+    );
+  }
+
+  return (
+    <div {...props} ref={forwardedRef}>
+      <SidebarSubMenuModeContext.Provider value="accordion">
+        <Accordion.Root type="single" collapsible defaultValue={defaultOpen ? 'item' : undefined}>
+          <Accordion.Item value="item">{children}</Accordion.Item>
+        </Accordion.Root>
+      </SidebarSubMenuModeContext.Provider>
+    </div>
+  );
+});
+SidebarMenuSub.displayName = 'Sidebar.MenuSub';
+
+interface SidebarMenuSubTriggerProps extends React.ComponentPropsWithoutRef<typeof Accordion.Trigger> {
+  asChild?: boolean;
+}
+
+const SidebarMenuSubTrigger = React.forwardRef<React.ElementRef<typeof Accordion.Trigger>, SidebarMenuSubTriggerProps>(
+  ({ asChild = false, className, children, ...props }, forwardedRef) => {
+    const mode = React.useContext(SidebarSubMenuModeContext);
+
+    if (mode === 'dropdown') {
+      return (
+        <DropdownMenu.Trigger>
+          <button
+            {...(props as any)}
+            ref={forwardedRef as any}
+            type="button"
+            role="menuitem"
+            aria-haspopup="menu"
+            className={classNames('rt-reset', 'rt-BaseMenuItem', 'rt-SidebarMenuButton', 'rt-SidebarMenuSubTrigger', className)}
+          >
+            {children}
+          </button>
+        </DropdownMenu.Trigger>
+      );
+    }
+
+    return (
+      <Accordion.Header asChild>
+        <div>
+          <Accordion.Trigger
+            {...props}
+            ref={forwardedRef}
+            asChild={asChild}
+            role="menuitem"
+            aria-haspopup="true"
+            className={classNames('rt-reset', 'rt-BaseMenuItem', 'rt-SidebarMenuButton', 'rt-SidebarMenuSubTrigger', className)}
+          >
+            {asChild ? (
+              children
+            ) : (
+              <>
+                {children}
+                <ThickChevronRightIcon className={classNames('rt-BaseMenuSubTriggerIcon', 'rt-SidebarMenuSubTriggerIcon')} />
+              </>
+            )}
+          </Accordion.Trigger>
+        </div>
+      </Accordion.Header>
+    );
+  },
+);
+SidebarMenuSubTrigger.displayName = 'Sidebar.MenuSubTrigger';
+
+interface SidebarMenuSubContentProps extends React.ComponentPropsWithoutRef<typeof Accordion.Content> {}
+
+const SidebarMenuSubContent = React.forwardRef<React.ElementRef<typeof Accordion.Content>, SidebarMenuSubContentProps>(({ className, children, ...props }, forwardedRef) => {
+  const visual = useSidebarVisual();
+  const mode = React.useContext(SidebarSubMenuModeContext);
+
+  if (mode === 'dropdown') {
+    const unwrapMenuButton = (node: React.ReactNode): React.ReactNode => {
+      if (Array.isArray(node)) {
+        return node.map((n, i) => <React.Fragment key={i}>{unwrapMenuButton(n)}</React.Fragment>);
+      }
+      if (React.isValidElement(node)) {
+        const typeDisplay = (node.type as any)?.displayName;
+        if (typeDisplay === 'Sidebar.MenuButton') {
+          return (node.props as any)?.children;
+        }
+        const child = (node.props as any)?.children;
+        if (child !== undefined) {
+          return React.cloneElement(node as any, { ...(node.props as any), children: unwrapMenuButton(child) });
+        }
+      }
+      return node;
+    };
+
+    const normalized = React.Children.map(children as React.ReactNode, (child, index) => {
+      if (React.isValidElement(child) && (child.type as any)?.displayName === 'Sidebar.MenuItem') {
+        const itemChildren = (child.props as any)?.children;
+        const content = unwrapMenuButton(itemChildren);
+        return (
+          <DropdownMenu.Item key={index} asChild>
+            {content as any}
+          </DropdownMenu.Item>
+        );
+      }
+      // Fallback: wrap raw nodes too for consistent menu styling
+      return (
+        <DropdownMenu.Item key={index} asChild>
+          {unwrapMenuButton(child) as any}
+        </DropdownMenu.Item>
+      );
+    });
+
+    // DropdownMenu only supports sizes 1 and 2, so map size 3 to 2
+    const dropdownSize = visual?.size === '3' ? '2' : visual?.size;
+    return (
+      <DropdownMenu.Content size={dropdownSize} variant={visual?.menuVariant} className={classNames(className)}>
+        <DropdownMenu.Group>{normalized}</DropdownMenu.Group>
+      </DropdownMenu.Content>
+    );
+  }
+
+  return (
+    <Accordion.Content {...props} ref={forwardedRef} className={classNames('rt-SidebarMenuSubContent', className)}>
+      <div className="rt-SidebarMenuSubList">{children}</div>
+    </Accordion.Content>
+  );
+});
+SidebarMenuSubContent.displayName = 'Sidebar.MenuSubContent';
+
+// Group components
+interface SidebarGroupProps extends React.ComponentPropsWithoutRef<'div'> {}
+
+const SidebarGroup = React.forwardRef<HTMLDivElement, SidebarGroupProps>(({ className, ...props }, forwardedRef) => (
+  <div {...props} ref={forwardedRef} className={classNames('rt-BaseMenuGroup', 'rt-SidebarGroup', className)} />
+));
+SidebarGroup.displayName = 'Sidebar.Group';
+
+interface SidebarGroupLabelProps extends React.ComponentPropsWithoutRef<'div'> {
+  asChild?: boolean;
+}
+
+const SidebarGroupLabel = React.forwardRef<HTMLDivElement, SidebarGroupLabelProps>(({ asChild = false, className, ...props }, forwardedRef) => {
+  const Comp = asChild ? Slot : 'div';
+
+  return <Comp {...props} ref={forwardedRef} role="group" className={classNames('rt-BaseMenuLabel', 'rt-SidebarGroupLabel', className)} />;
+});
+SidebarGroupLabel.displayName = 'Sidebar.GroupLabel';
+
+interface SidebarGroupContentProps extends React.ComponentPropsWithoutRef<'div'> {}
+
+const SidebarGroupContent = React.forwardRef<HTMLDivElement, SidebarGroupContentProps>(({ className, ...props }, forwardedRef) => (
+  <div {...props} ref={forwardedRef} className={classNames('rt-SidebarGroupContent', className)} />
+));
+SidebarGroupContent.displayName = 'Sidebar.GroupContent';
+
+// Search component: inline input in expanded, popover trigger in thin
+interface SidebarSearchProps extends React.ComponentPropsWithoutRef<'div'> {
+  value: string;
+  onValueChange: (value: string) => void;
+  placeholder?: string;
+  children?: React.ReactNode;
+}
+
+const SearchIcon = ({ className }: { className?: string }) => (
+  <svg className={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+    <circle cx="11" cy="11" r="8" />
+    <line x1="21" y1="21" x2="16.65" y2="16.65" />
+  </svg>
+);
+
+const ClearIcon = ({ className }: { className?: string }) => (
+  <svg className={className} width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+    <line x1="18" y1="6" x2="6" y2="18" />
+    <line x1="6" y1="6" x2="18" y2="18" />
+  </svg>
+);
+
+const SidebarSearch = React.forwardRef<HTMLDivElement, SidebarSearchProps>(
+  ({ value, onValueChange, placeholder = 'Search...', children, className, ...props }, forwardedRef) => {
+    const visual = useSidebarVisual();
+    const isThin = visual?.presentation === 'thin';
+    const inputRef = React.useRef<HTMLInputElement>(null);
+    const popoverRef = React.useRef<HTMLDivElement>(null);
+    const searchId = React.useId();
+    const resultsId = `${searchId}-results`;
+
+    // Stable refs for values used in callbacks — avoids recreating handlers on every keystroke
+    const valueRef = React.useRef(value);
+    valueRef.current = value;
+    const onValueChangeRef = React.useRef(onValueChange);
+    onValueChangeRef.current = onValueChange;
+
+    // Derive a clean aria-label from placeholder (strip trailing dots/ellipsis)
+    const searchLabel = placeholder.replace(/\.+$/, '');
+
+    const handleKeyDown = React.useCallback(
+      (e: React.KeyboardEvent<HTMLInputElement>) => {
+        if (e.key === 'Escape' && valueRef.current) {
+          e.preventDefault();
+          e.stopPropagation();
+          onValueChangeRef.current('');
+          inputRef.current?.focus();
+        }
+      },
+      [],
+    );
+
+    // Arrow key navigation within the popover (input ↔ results)
+    const handlePopoverKeyDown = React.useCallback(
+      (e: React.KeyboardEvent<HTMLDivElement>) => {
+        const container = popoverRef.current;
+        if (!container) return;
+
+        const resultsGroup = container.querySelector('[role="group"]');
+        if (!resultsGroup) return;
+
+        const items = Array.from(
+          resultsGroup.querySelectorAll<HTMLElement>('a, button'),
+        );
+        if (items.length === 0) return;
+
+        const active = document.activeElement as HTMLElement;
+        const isOnInput = active === inputRef.current;
+        const currentIndex = items.indexOf(active);
+
+        // Typing while a result is focused → redirect focus to input
+        if (
+          e.key.length === 1 &&
+          !e.ctrlKey &&
+          !e.metaKey &&
+          !e.altKey &&
+          !isOnInput &&
+          currentIndex !== -1
+        ) {
+          inputRef.current?.focus();
+          return;
+        }
+
+        switch (e.key) {
+          case 'ArrowDown': {
+            e.preventDefault();
+            if (isOnInput || currentIndex === -1) {
+              items[0]?.focus();
+            } else if (currentIndex < items.length - 1) {
+              items[currentIndex + 1]?.focus();
+            }
+            break;
+          }
+          case 'ArrowUp': {
+            e.preventDefault();
+            if (currentIndex <= 0) {
+              inputRef.current?.focus();
+            } else {
+              items[currentIndex - 1]?.focus();
+            }
+            break;
+          }
+          case 'Home': {
+            // Only intercept when focused on a result, not the input (where Home moves cursor)
+            if (!isOnInput) {
+              e.preventDefault();
+              items[0]?.focus();
+            }
+            break;
+          }
+          case 'End': {
+            if (!isOnInput) {
+              e.preventDefault();
+              items[items.length - 1]?.focus();
+            }
+            break;
+          }
+        }
+      },
+      [],
+    );
+
+    if (isThin) {
+      return (
+        <div {...props} ref={forwardedRef} className={classNames('rt-SidebarSearch', 'rt-SidebarSearch--thin', className)}>
+          <Popover.Root>
+            <Popover.Trigger>
+              <button
+                type="button"
+                className={classNames('rt-reset', 'rt-BaseMenuItem', 'rt-SidebarMenuButton', 'rt-SidebarSearchTrigger')}
+                aria-label={searchLabel}
+              >
+                <span className="rt-SidebarMenuIconWrapper">
+                  <SearchIcon />
+                </span>
+                <span className="rt-SidebarMenuLabel">Search</span>
+              </button>
+            </Popover.Trigger>
+            <Popover.Content side="right" align="start" size="2" width="280px" aria-label={searchLabel}>
+              {/* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- keyDown manages arrow-key navigation between input and results, which is accessibility-enhancing */}
+              <div
+                ref={popoverRef}
+                className="rt-SidebarSearchPopover"
+                role="search"
+                onKeyDown={handlePopoverKeyDown}
+              >
+                <div className="rt-SidebarSearchInputWrapper">
+                  <SearchIcon className="rt-SidebarSearchIcon" />
+                  <input
+                    ref={inputRef}
+                    type="search"
+                    className="rt-SidebarSearchInput"
+                    value={value}
+                    onChange={(e) => onValueChange(e.target.value)}
+                    onKeyDown={handleKeyDown}
+                    placeholder={placeholder}
+                    aria-label={searchLabel}
+                    aria-controls={children ? resultsId : undefined}
+                    // eslint-disable-next-line jsx-a11y/no-autofocus -- intentional: popover opens on user action, focusing the input is expected UX
+                    autoFocus
+                  />
+                  {value && (
+                    <button
+                      type="button"
+                      className="rt-reset rt-SidebarSearchClear"
+                      onClick={() => {
+                        onValueChange('');
+                        inputRef.current?.focus();
+                      }}
+                      aria-label="Clear search"
+                    >
+                      <ClearIcon />
+                    </button>
+                  )}
+                </div>
+                {children && (
+                  <div id={resultsId} role="group" aria-label="Search results">
+                    {children}
+                  </div>
+                )}
+              </div>
+            </Popover.Content>
+          </Popover.Root>
+        </div>
+      );
+    }
+
+    // Expanded mode: inline input
+    return (
+      <div {...props} ref={forwardedRef} className={classNames('rt-SidebarSearch', 'rt-SidebarSearch--expanded', className)} role="search">
+        <div className="rt-SidebarSearchInputWrapper">
+          <SearchIcon className="rt-SidebarSearchIcon" />
+          <input
+            ref={inputRef}
+            type="search"
+            className="rt-SidebarSearchInput"
+            value={value}
+            onChange={(e) => onValueChange(e.target.value)}
+            onKeyDown={handleKeyDown}
+            placeholder={placeholder}
+            aria-label={searchLabel}
+          />
+          {value && (
+            <button
+              type="button"
+              className="rt-reset rt-SidebarSearchClear"
+              onClick={() => {
+                onValueChange('');
+                inputRef.current?.focus();
+              }}
+              aria-label="Clear search"
+            >
+              <ClearIcon />
+            </button>
+          )}
+        </div>
+      </div>
+    );
+  },
+);
+SidebarSearch.displayName = 'Sidebar.Search';
+
+// Export all components following shadcn's pattern
+export {
+  Sidebar as Root,
+  SidebarContent as Content,
+  SidebarHeader as Header,
+  SidebarFooter as Footer,
+  SidebarSeparator as Separator,
+  SidebarMenu as Menu,
+  SidebarMenuItem as MenuItem,
+  SidebarMenuButton as MenuButton,
+  SidebarMenuSub as MenuSub,
+  SidebarMenuSubTrigger as MenuSubTrigger,
+  SidebarMenuSubContent as MenuSubContent,
+  SidebarGroup as Group,
+  SidebarGroupLabel as GroupLabel,
+  SidebarGroupContent as GroupContent,
+  SidebarSearch as Search,
+};
+
+/**
+ * Enhanced Sidebar Header and Footer Usage Examples:
+ *
+ * 1. Simple default container (backwards compatible):
+ * <Sidebar.Header>
+ *   <Logo />
+ *   <span>App Name</span>
+ * </Sidebar.Header>
+ *
+ * 2. Custom flex layout:
+ * <Sidebar.Header className="rt-justify-between rt-gap-3">
+ *   <Logo />
+ *   <Sidebar.MenuButton>
+ *     <SettingsIcon />
+ *   </Sidebar.MenuButton>
+ * </Sidebar.Header>
+ *
+ * 3. Column layout for multiple rows:
+ * <Sidebar.Header className="rt-flex-col rt-gap-2" asContainer={false}>
+ *   <div className="rt-flex rt-items-center rt-gap-2">
+ *     <Logo />
+ *     <span>App Name</span>
+ *   </div>
+ *   <Sidebar.MenuButton>
+ *     <UserAvatar />
+ *     <span>John Doe</span>
+ *   </Sidebar.MenuButton>
+ * </Sidebar.Header>
+ *
+ * 4. Interactive footer with menu button:
+ * <Sidebar.Footer>
+ *   <Sidebar.MenuButton>
+ *     <UserIcon />
+ *     <span>Settings</span>
+ *     <ChevronUpIcon />
+ *   </Sidebar.MenuButton>
+ * </Sidebar.Footer>
+ *
+ * 5. Custom footer layout:
+ * <Sidebar.Footer className="rt-justify-between">
+ *   <span>v1.0.0</span>
+ *   <Sidebar.MenuButton>
+ *     <HelpIcon />
+ *   </Sidebar.MenuButton>
+ * </Sidebar.Footer>
+ *
+ * Available utility classes:
+ * - Layout: rt-flex-row, rt-flex-col
+ * - Alignment: rt-items-center, rt-items-start, rt-items-end
+ * - Justification: rt-justify-between, rt-justify-center, rt-justify-start, rt-justify-end
+ * - Gap: rt-gap-1, rt-gap-2, rt-gap-3, rt-gap-4
+ */
+
+export type { SidebarProps as RootProps, SidebarContentProps as ContentProps, SidebarHeaderProps as HeaderProps, SidebarFooterProps as FooterProps, BadgeConfig };