@mihcm/ui 0.14.1 → 0.15.0

package/src/MainSidebar/helpers.ts

@@ -0,0 +1,164 @@
+import { isValidElement, type CSSProperties, type ReactNode } from 'react';
+import type { MainSidebarColorScheme, MainSidebarItem } from './types.js';
+
+/**
+ * `MainSidebarItem.badge` accepts either a primitive (string/number) — in
+ * which case the variant wraps it in a default pill — or a fully-styled
+ * ReactElement (e.g. `<Badge variant="warning">12</Badge>`), which should
+ * render as-is to avoid double backgrounds.
+ */
+export function isPrimitiveBadge(badge: ReactNode): badge is string | number {
+  return typeof badge === 'string' || typeof badge === 'number';
+}
+
+/**
+ * True when the badge should be rendered inside the variant's default pill
+ * wrapper. ReactElements bring their own styling and bypass the wrapper.
+ */
+export function shouldWrapBadge(badge: ReactNode): boolean {
+  if (badge == null || badge === false) return false;
+  if (isValidElement(badge)) return false;
+  return true;
+}
+
+export function findItem(
+  items: MainSidebarItem[],
+  key: string | undefined,
+): MainSidebarItem | undefined {
+  if (!key) return undefined;
+  for (const item of items) {
+    if (item.key === key) return item;
+    const child = findItem(item.children ?? [], key);
+    if (child) return child;
+  }
+  return undefined;
+}
+
+/** True if `target` is `item.key` itself, OR appears somewhere in `item`'s subtree. */
+export function isOnPath(item: MainSidebarItem, target: string | undefined): boolean {
+  if (!target) return false;
+  if (item.key === target) return true;
+  return (item.children ?? []).some((child) => isOnPath(child, target));
+}
+
+export function firstPanelItem(
+  items: MainSidebarItem[],
+  activeKey: string | undefined,
+) {
+  const active = findItem(items, activeKey);
+  if (active?.children?.length || active?.panel) return active;
+  return items.find((item) => item.children?.length || item.panel) ?? items[0];
+}
+
+export function opensPanel(item: MainSidebarItem) {
+  return Boolean(item.children?.length || item.panel);
+}
+
+export function defaultMatcher(item: MainSidebarItem, query: string) {
+  if (!query) return true;
+  return item.label.toLowerCase().includes(query.toLowerCase());
+}
+
+/** Filter a list non-recursively (used by per-level search). */
+export function filterLevel(
+  items: MainSidebarItem[],
+  query: string,
+  matcher: (item: MainSidebarItem, query: string) => boolean = defaultMatcher,
+) {
+  if (!query) return items;
+  return items.filter((item) => matcher(item, query));
+}
+
+export interface FlatMatch {
+  item: MainSidebarItem;
+  /** Parent labels from root → immediate parent (excludes the matched item). */
+  breadcrumbs: string[];
+}
+
+/** Recursively flatten + filter the whole tree (used by command variant). */
+export function flatMatchTree(
+  items: MainSidebarItem[],
+  query: string,
+  matcher: (item: MainSidebarItem, query: string) => boolean = defaultMatcher,
+): FlatMatch[] {
+  const out: FlatMatch[] = [];
+  const visit = (list: MainSidebarItem[], breadcrumbs: string[]) => {
+    for (const item of list) {
+      if (matcher(item, query)) {
+        out.push({ item, breadcrumbs });
+      }
+      if (item.children?.length) {
+        visit(item.children, [...breadcrumbs, item.label]);
+      }
+    }
+  };
+  visit(items, []);
+  return out;
+}
+
+/**
+ * Convert a `MainSidebarColorScheme` into a CSS-variable style payload.
+ *
+ * Strategy: override the design-system brand variables (`--color-primary`,
+ * `--color-accent`, `--color-foreground`, etc.) directly on the sidebar
+ * root. Every Tailwind class that resolves through those tokens
+ * (`bg-primary`, `text-primary-foreground`, `bg-accent`, …) gets the new
+ * colour automatically — no per-element rewrites, and the override applies
+ * to nested affordances too (tooltips, breadcrumbs, badges, expanded
+ * panel surfaces).
+ *
+ * Tokens are scoped because the inline style only applies within the
+ * sidebar root subtree, so the rest of the page keeps its brand defaults.
+ *
+ * Omitted tokens are NOT emitted, so the cascade falls through to the
+ * page-level defaults.
+ */
+export function colorSchemeToStyle(
+  scheme: MainSidebarColorScheme | undefined,
+): CSSProperties {
+  if (!scheme) return {};
+  const out: Record<string, string> = {};
+
+  /* Granular tokens win over the bg/fg shorthands. */
+  const railBg = scheme.railBg ?? scheme.bg;
+  const railFg = scheme.railFg ?? scheme.fg;
+  const panelBg = scheme.panelBg ?? scheme.bg;
+  const panelFg = scheme.panelFg ?? scheme.fg;
+
+  if (railBg) out['--color-primary'] = railBg;
+  if (railFg) out['--color-primary-foreground'] = railFg;
+  if (panelBg) out['--color-card'] = panelBg;
+  if (panelFg) out['--color-card-foreground'] = panelFg;
+
+  if (scheme.accentBg) out['--color-accent'] = scheme.accentBg;
+  if (scheme.accentFg) out['--color-accent-foreground'] = scheme.accentFg;
+  if (scheme.border) out['--color-border'] = scheme.border;
+  if (scheme.mutedFg) out['--color-muted-foreground'] = scheme.mutedFg;
+  if (scheme.ring) out['--color-ring'] = scheme.ring;
+  /*
+   * Hover overlay — exposed under a sidebar-specific variable. Components
+   * read it via `bg-[var(--mihcm-sidebar-hover-bg,…)]` with a sensible
+   * fallback so the default theme still works when `hoverBg` isn't set.
+   */
+  if (scheme.hoverBg) out['--mihcm-sidebar-hover-bg'] = scheme.hoverBg;
+  /*
+   * Tooltip surface uses --color-foreground / --color-background. These
+   * are NOT touched by panelFg/railFg overrides — keeping them at the
+   * page's brand defaults lets the rail-icon tooltip flip cleanly with
+   * dark mode. Set `tooltipBg`/`tooltipFg` only when you need a tooltip
+   * surface distinct from the page brand.
+   */
+  if (scheme.tooltipBg) out['--color-foreground'] = scheme.tooltipBg;
+  if (scheme.tooltipFg) out['--color-background'] = scheme.tooltipFg;
+  return out as CSSProperties;
+}
+
+/** Resolve the active path stack into MainSidebarItem objects (filters missing ids). */
+export function resolvePath(
+  items: MainSidebarItem[],
+  pathKeys: string[],
+): MainSidebarItem[] {
+  return pathKeys
+    .map((key) => findItem(items, key))
+    .filter((item): item is MainSidebarItem => Boolean(item));
+}

package/src/MainSidebar/hover.tsx

@@ -0,0 +1,334 @@
+'use client';
+
+/**
+ * MainSidebar — `hover` variant.
+ *
+ * Rail stays in icon width permanently. Hovering an icon shows that icon's
+ * children in a floating mini-menu beside the rail. Clicking a child that
+ * itself has children drills the panel deeper — a breadcrumb at the top
+ * lets the user jump back to any ancestor in one click. Layout never
+ * reflows. Touch devices fall back to tap-toggle.
+ */
+import { forwardRef, useEffect, useMemo, useRef, useState } from 'react';
+import { AnimatePresence, motion, useReducedMotion } from 'motion/react';
+import { cn } from '../internal/cn.js';
+import { Rail } from './rail.js';
+import { MenuSearch } from './search.js';
+import { BackButton } from './back-button.js';
+import { PathBreadcrumb } from './breadcrumb.js';
+import { defaultMatcher, filterLevel, findItem, opensPanel } from './helpers.js';
+import { scaleVariants } from './motion.js';
+import type { MainSidebarItem, MainSidebarProps } from './types.js';
+
+export const HoverSidebar = forwardRef<HTMLElement, MainSidebarProps>(function HoverSidebar(
+  {
+    items,
+    activeKey,
+    onItemSelect,
+    header,
+    footer,
+    search = false,
+    searchPlaceholder,
+    onSearchChange,
+    side = 'left',
+    density = 'comfortable',
+    panelWidth = 260,
+    motionPreset = 'expressive',
+    hoverDelayMs = 120,
+    closeOnOutsideClick = true,
+    railClassName,
+    panelClassName,
+    itemClassName,
+    activeItemClassName,
+    backLabel = 'Back',
+    className,
+    ...rest
+  },
+  ref,
+) {
+  const reduceMotion = useReducedMotion();
+  const effectivePreset = reduceMotion ? 'subtle' : motionPreset;
+
+  /* `hoveredKey` = the root rail item that opened the panel.
+   * `panelPathKeys` = ancestors drilled into INSIDE the panel, starting
+   * from (but not including) hoveredKey. When empty, panel shows
+   * hoveredItem.children. When [childKey], panel shows child.children. */
+  const [hoveredKey, setHoveredKey] = useState<string | null>(null);
+  const [panelPathKeys, setPanelPathKeys] = useState<string[]>([]);
+  const [query, setQuery] = useState('');
+  const railRef = useRef<HTMLElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const hideTimer = useRef<number | undefined>(undefined);
+  const showTimer = useRef<number | undefined>(undefined);
+
+  const searchEnabled = search !== false;
+  const searchCfg = typeof search === 'object' ? search : undefined;
+  const matcher = searchCfg?.matcher ?? defaultMatcher;
+
+  const rootItem = useMemo(
+    () => (hoveredKey ? items.find((it) => it.key === hoveredKey) ?? null : null),
+    [items, hoveredKey],
+  );
+
+  /* Build the full breadcrumb path from rootItem down through the drilled
+   * panel ancestors. The deepest entry's children populate the panel. */
+  const path = useMemo<MainSidebarItem[]>(() => {
+    if (!rootItem) return [];
+    const stack: MainSidebarItem[] = [rootItem];
+    for (const key of panelPathKeys) {
+      const node = findItem(stack[stack.length - 1]?.children ?? [], key);
+      if (!node) break;
+      stack.push(node);
+    }
+    return stack;
+  }, [rootItem, panelPathKeys]);
+
+  const current = path[path.length - 1] ?? null;
+  const childList = current?.children ?? [];
+  const filtered = filterLevel(childList, query, matcher);
+
+  function cancelHide() {
+    if (hideTimer.current !== undefined) {
+      window.clearTimeout(hideTimer.current);
+      hideTimer.current = undefined;
+    }
+  }
+  function scheduleHide() {
+    cancelHide();
+    hideTimer.current = window.setTimeout(() => closePanel(), 200);
+  }
+  function cancelShow() {
+    if (showTimer.current !== undefined) {
+      window.clearTimeout(showTimer.current);
+      showTimer.current = undefined;
+    }
+  }
+  function scheduleShow(key: string) {
+    cancelShow();
+    showTimer.current = window.setTimeout(() => {
+      if (key !== hoveredKey) {
+        setHoveredKey(key);
+        setPanelPathKeys([]);
+        setQuery('');
+      }
+    }, hoverDelayMs);
+  }
+
+  function closePanel() {
+    setHoveredKey(null);
+    setPanelPathKeys([]);
+    setQuery('');
+  }
+
+  function selectRailItem(item: MainSidebarItem) {
+    if (item.disabled) return;
+    onItemSelect?.(item.key, item);
+    if (opensPanel(item)) {
+      cancelHide();
+      cancelShow();
+      if (hoveredKey === item.key) {
+        closePanel();
+        return;
+      }
+      setHoveredKey(item.key);
+      setPanelPathKeys([]);
+      setQuery('');
+    } else {
+      closePanel();
+    }
+  }
+
+  function selectPanelItem(item: MainSidebarItem) {
+    if (item.disabled) return;
+    onItemSelect?.(item.key, item);
+    if (opensPanel(item)) {
+      /* Drill deeper inside the panel. */
+      setPanelPathKeys((prev) => [...prev, item.key]);
+      setQuery('');
+    } else {
+      closePanel();
+    }
+  }
+
+  function goBack() {
+    setPanelPathKeys((prev) => prev.slice(0, -1));
+    setQuery('');
+  }
+
+  /* Esc + outside-click close panel. */
+  useEffect(() => {
+    if (!hoveredKey) return;
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') closePanel();
+    }
+    function onPointerDown(e: PointerEvent) {
+      if (!closeOnOutsideClick) return;
+      const target = e.target as Node;
+      if (panelRef.current?.contains(target) || railRef.current?.contains(target)) return;
+      closePanel();
+    }
+    document.addEventListener('keydown', onKey);
+    document.addEventListener('pointerdown', onPointerDown);
+    return () => {
+      document.removeEventListener('keydown', onKey);
+      document.removeEventListener('pointerdown', onPointerDown);
+    };
+  }, [hoveredKey, closeOnOutsideClick]);
+
+  /* Cleanup timers on unmount */
+  useEffect(() => {
+    return () => {
+      cancelHide();
+      cancelShow();
+    };
+  }, []);
+
+  return (
+    /*
+     * Per-surface mouse handlers (NOT one outer wrapper handler) — the panel
+     * is absolutely positioned outside the outer container's layout box, so
+     * an outer `onMouseLeave` fires the moment the cursor enters the gap
+     * between rail and panel, racing the panel's own `onMouseEnter` and
+     * causing a hide/show flicker.
+     *
+     * Instead each surface owns its own enter/leave:
+     *   - rail-wrapper:  enter → cancelHide,  leave → scheduleHide
+     *   - panel:         enter → cancelHide,  leave → scheduleHide
+     * The `hideTimer` is the bridge that absorbs the brief gap-traversal.
+     */
+    <div ref={ref as never} className={cn('relative h-full', className)} {...rest}>
+      <div
+        onMouseEnter={cancelHide}
+        onMouseLeave={scheduleHide}
+        onMouseMove={(e) => {
+          const target = (e.target as HTMLElement).closest('button');
+          if (!target) return;
+          const key = target.dataset.itemKey;
+          if (key && key !== hoveredKey) scheduleShow(key);
+        }}
+      >
+        <Rail
+          ref={railRef}
+          items={items.map((it) => ({ ...it }))}
+          activeKey={activeKey}
+          density={density}
+          side={side}
+          header={header}
+          footer={footer}
+          itemClassName={itemClassName}
+          activeItemClassName={activeItemClassName}
+          className={railClassName}
+          openPanelKey={hoveredKey ?? undefined}
+          onItemSelect={selectRailItem}
+        />
+      </div>
+
+      <AnimatePresence initial={false} mode="wait">
+        {current && (childList.length || current.panel) ? (
+          <motion.div
+            key={rootItem?.key ?? 'panel'}
+            ref={panelRef}
+            variants={scaleVariants(effectivePreset)}
+            initial="initial"
+            animate="animate"
+            exit="exit"
+            role="menu"
+            aria-label={current.label}
+            onMouseEnter={cancelHide}
+            onMouseLeave={scheduleHide}
+            style={{
+              width: typeof panelWidth === 'number' ? `${panelWidth}px` : panelWidth,
+              [side === 'right' ? 'right' : 'left']: density === 'compact' ? '3rem' : '3.5rem',
+            }}
+            className={cn(
+              'absolute top-2 z-10 rounded-xl border border-border bg-card text-card-foreground shadow-xl',
+              panelClassName,
+            )}
+          >
+            <div className="border-b border-border px-3 py-2.5">
+              {path.length > 1 ? (
+                <>
+                  <PathBreadcrumb
+                    path={path}
+                    onJump={(depth) => {
+                      /* breadcrumb depth indexes into `path` (root=0). The
+                       * panel stack starts from depth 1, so trim it to
+                       * keep `depth` items beyond the root. */
+                      setPanelPathKeys((prev) => prev.slice(0, depth));
+                      setQuery('');
+                    }}
+                    className="mb-1"
+                  />
+                  <BackButton onClick={goBack} label={backLabel} className="mb-1 -ml-1.5" />
+                </>
+              ) : null}
+              <div className="truncate text-base font-semibold text-card-foreground">{current.label}</div>
+              {current.description ? (
+                <p className="mt-0.5 truncate text-xs text-card-foreground/70">{current.description}</p>
+              ) : null}
+              {searchEnabled ? (
+                <div className="mt-2">
+                  <MenuSearch
+                    value={query}
+                    onValueChange={(v) => {
+                      setQuery(v);
+                      onSearchChange?.(v);
+                    }}
+                    placeholder={searchCfg?.placeholder ?? searchPlaceholder ?? `Search ${current.label}…`}
+                  
+                  tone="onBrand"
+                  />
+                </div>
+              ) : null}
+            </div>
+            <div className="max-h-[min(80vh,32rem)] overflow-y-auto p-1.5">
+              {filtered.length === 0 && query ? (
+                <div className="px-3 py-6 text-center text-xs text-card-foreground/70">
+                  {searchCfg?.noResultsLabel ?? `No items match "${query}".`}
+                </div>
+              ) : (
+                filtered.map((item) => {
+                  const hasChildren = opensPanel(item);
+                  return (
+                    <button
+                      key={item.key}
+                      type="button"
+                      onClick={() => selectPanelItem(item)}
+                      disabled={item.disabled}
+                      className={cn(
+                        'group flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm text-card-foreground transition-colors',
+                        'hover:bg-card-foreground/10 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                        'disabled:cursor-not-allowed disabled:opacity-50',
+                        item.key === activeKey && 'text-card-foreground font-semibold',
+                        itemClassName,
+                      )}
+                    >
+                      {item.icon ? (
+                        <span className="grid size-4 shrink-0 place-items-center text-card-foreground/70 [&_svg]:size-full" aria-hidden="true">
+                          {item.icon}
+                        </span>
+                      ) : null}
+                      <span className="min-w-0 flex-1 truncate">{item.label}</span>
+                      {hasChildren ? (
+                        <svg
+                          viewBox="0 0 24 24"
+                          fill="none"
+                          stroke="currentColor"
+                          strokeWidth="2"
+                          className="size-3.5 shrink-0 text-card-foreground/70"
+                          aria-hidden="true"
+                        >
+                          <path d="m9 18 6-6-6-6" strokeLinecap="round" strokeLinejoin="round" />
+                        </svg>
+                      ) : null}
+                    </button>
+                  );
+                })
+              )}
+            </div>
+          </motion.div>
+        ) : null}
+      </AnimatePresence>
+    </div>
+  );
+});

package/src/MainSidebar/index.tsx

@@ -0,0 +1,191 @@
+'use client';
+
+/**
+ * MainSidebar — variant dispatcher with shadcn-style collapse toggle.
+ *
+ * The sidebar has two top-level shapes (matching shadcn's `collapsible="icon"`):
+ *
+ *   - **expanded**  — wide vertical sidebar with icon + label rows and
+ *     inline accordion expansion. Shared across every variant via
+ *     `ExpandedSidebar`. This is what users see by default unless the call
+ *     site opts into `defaultCollapsed`.
+ *   - **collapsed** — the original narrow icon rail; behaviour is
+ *     variant-specific. Five interaction models live here:
+ *
+ *       - `drilldown` (default) — rail click reveals a panel; deeper levels
+ *         replace it; back via breadcrumb. Layout overlays.
+ *       - `floating`            — panel floats on top of content; dismiss on
+ *         outside-click, Esc, or repeated rail click.
+ *       - `columns`             — Finder-style Miller columns; each level keeps
+ *         the previous column visible; horizontally scrolling.
+ *       - `command`             — search-first; typing filters the whole tree
+ *         recursively; empty query falls back to drilldown.
+ *       - `hover`               — hovering an icon pops out a floating
+ *         mini-menu. Touch falls back to tap-toggle.
+ *
+ * Toggle between the two shapes via the in-built collapse button (header of
+ * the expanded sidebar) or a floating expand chip rendered next to the rail
+ * when collapsed. Both can be hidden via `showCollapseToggle={false}`.
+ *
+ * Public barrel — implementations split under `./MainSidebar/*`. Wiki:
+ * docs/components/MainSidebar.md.
+ */
+import { forwardRef, useState } from 'react';
+import { cn } from '../internal/cn.js';
+import { DrilldownSidebar } from './drilldown.js';
+import { FloatingSidebar } from './floating.js';
+import { ColumnsSidebar } from './columns.js';
+import { CommandSidebar } from './command.js';
+import { HoverSidebar } from './hover.js';
+import { ExpandedSidebar } from './expanded.js';
+import { MobileSidebar } from './mobile.js';
+import { colorSchemeToStyle } from './helpers.js';
+import type { MainSidebarProps } from './types.js';
+
+export type {
+  IconSidebarItem,
+  IconSidebarProps,
+  MainSidebarCollapsible,
+  MainSidebarColorScheme,
+  MainSidebarDensity,
+  MainSidebarItem,
+  MainSidebarMotionPreset,
+  MainSidebarProps,
+  MainSidebarSearchConfig,
+  MainSidebarSide,
+  MainSidebarVariant,
+} from './types.js';
+
+export const MainSidebar = forwardRef<HTMLElement, MainSidebarProps>(function MainSidebar(props, ref) {
+  const {
+    collapsible = 'icon',
+    collapsed,
+    defaultCollapsed = true,
+    onCollapsedChange,
+    showCollapseToggle = true,
+    side = 'left',
+    expandedLabel = 'Expand menu',
+    /*
+     * Strip sidebar-meta props that no variant destructures. If left in
+     * `...rest`, they'd be spread onto the variant's root <div> and
+     * trigger "unknown DOM attribute" warnings (e.g. `mobile`).
+     */
+    mobile,
+    showLabelsWhenExpanded: _showLabelsWhenExpanded,
+    collapsedWidth: _collapsedWidth,
+    expandedWidth: _expandedWidth,
+    collapsedLabel: _collapsedLabel,
+    colorScheme,
+    style,
+    /* Variant-specific props — strip from `variantProps` and re-inject only
+     * for the variant that actually consumes them. Otherwise the prop
+     * leaks through into a variant that doesn't destructure it and lands
+     * on its root <div>, triggering "unknown DOM attribute" warnings. */
+    columnsMaxVisible,
+    hoverDelayMs,
+    ...variantProps
+  } = props;
+  void _showLabelsWhenExpanded;
+  void _collapsedWidth;
+  void _expandedWidth;
+  void _collapsedLabel;
+
+  /* Whitelabel theme — emitted as CSS-variable overrides on the wrapper so
+   * every nested Tailwind class (`bg-primary`, `text-primary-foreground`,
+   * `bg-accent`, `border-border`, etc.) inside the sidebar subtree
+   * resolves through the consumer's brand colours. */
+  const themeStyle = { ...colorSchemeToStyle(colorScheme), ...style };
+
+  const [internalCollapsed, setInternalCollapsed] = useState(defaultCollapsed);
+  const isCollapsed = collapsed ?? internalCollapsed;
+
+  function setCollapsed(next: boolean) {
+    if (collapsed === undefined) setInternalCollapsed(next);
+    onCollapsedChange?.(next);
+  }
+
+  /* Mobile / tablet — render a hamburger trigger that opens the sidebar in
+   * a Sheet overlay instead of taking inline page width. */
+  if (mobile) {
+    return (
+      <div style={themeStyle} className="contents">
+        <MobileSidebar {...variantProps} side={side} />
+      </div>
+    );
+  }
+
+  /* Expanded shape — universal across variants. */
+  if (collapsible !== 'none' && !isCollapsed) {
+    return (
+      <ExpandedSidebar
+        ref={ref}
+        {...variantProps}
+        side={side}
+        showCollapseToggle={showCollapseToggle}
+        onCollapse={() => setCollapsed(true)}
+        style={themeStyle}
+      />
+    );
+  }
+
+  /* Collapsed shape — variant-specific. Wrap in a relative shell so the
+   * floating expand chip can sit next to the rail without disturbing the
+   * variant's own layout. The wrapper carries the theme style so the
+   * floating expand chip also inherits the brand-override variables. */
+  const variantNode = (() => {
+    switch (props.variant) {
+      case 'floating':
+        return <FloatingSidebar ref={ref} {...variantProps} side={side} />;
+      case 'columns':
+        return (
+          <ColumnsSidebar
+            ref={ref}
+            {...variantProps}
+            side={side}
+            {...(columnsMaxVisible !== undefined ? { columnsMaxVisible } : {})}
+          />
+        );
+      case 'command':
+        return <CommandSidebar ref={ref} {...variantProps} side={side} />;
+      case 'hover':
+        return (
+          <HoverSidebar
+            ref={ref}
+            {...variantProps}
+            side={side}
+            {...(hoverDelayMs !== undefined ? { hoverDelayMs } : {})}
+          />
+        );
+      case 'drilldown':
+      case undefined:
+      default:
+        return <DrilldownSidebar ref={ref} {...variantProps} side={side} />;
+    }
+  })();
+
+  if (collapsible === 'none' || !showCollapseToggle) {
+    return <div style={themeStyle} className="contents">{variantNode}</div>;
+  }
+
+  return (
+    <div className="relative flex h-full" style={themeStyle}>
+      {variantNode}
+      <button
+        type="button"
+        onClick={() => setCollapsed(false)}
+        aria-label={expandedLabel}
+        className={cn(
+          'absolute top-3 z-30 grid size-6 place-items-center rounded-full border border-border bg-card text-muted-foreground shadow-sm transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+          side === 'right' ? 'left-[-12px]' : 'right-[-12px]',
+        )}
+      >
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" className="size-3.5" aria-hidden="true">
+          <path d={side === 'right' ? 'm15 18-6-6 6-6' : 'm9 18 6-6-6-6'} strokeLinecap="round" strokeLinejoin="round" />
+        </svg>
+      </button>
+    </div>
+  );
+});
+
+/** Backward-compat: IconSidebar was the original name. */
+export { MainSidebar as IconSidebar };