@mihcm/ui 0.14.1 → 0.15.1

package/src/MainSidebar/expanded.tsx

@@ -0,0 +1,414 @@
+'use client';
+
+/**
+ * MainSidebar — shared "expanded" rendering.
+ *
+ * When `collapsed` is false, every variant routes through this component:
+ * a wide vertical sidebar showing icon + label rows, with inline accordion
+ * expansion for parent items. This is the shadcn `collapsible="icon"`
+ * expanded shape.
+ *
+ * When the user toggles the collapse button (or `collapsed` flips to true),
+ * the dispatcher swaps this out for the variant's narrow rail rendering.
+ */
+import { forwardRef, useMemo, useState, type ReactNode } from 'react';
+import { cn } from '../internal/cn.js';
+import { MenuSearch } from './search.js';
+import {
+  defaultMatcher,
+  flatMatchTree,
+  isOnPath,
+  opensPanel,
+  shouldWrapBadge,
+} from './helpers.js';
+import type {
+  MainSidebarItem,
+  MainSidebarProps,
+} from './types.js';
+
+interface ExpandedRowProps {
+  item: MainSidebarItem;
+  depth: number;
+  activeKey: string | undefined;
+  onSelect: (item: MainSidebarItem) => void;
+  expandedKeys: Set<string>;
+  toggleExpanded: (key: string) => void;
+  itemClassName: string | undefined;
+  activeItemClassName: string | undefined;
+}
+
+function ExpandedRow({
+  item,
+  depth,
+  activeKey,
+  onSelect,
+  expandedKeys,
+  toggleExpanded,
+  itemClassName,
+  activeItemClassName,
+}: ExpandedRowProps) {
+  const hasChildren = opensPanel(item);
+  const onActivePath = isOnPath(item, activeKey);
+  const isActive = item.key === activeKey;
+  const isExpanded = expandedKeys.has(item.key);
+
+  return (
+    <>
+      <button
+        type="button"
+        disabled={item.disabled}
+        aria-current={isActive ? 'page' : undefined}
+        aria-expanded={hasChildren ? isExpanded : undefined}
+        onClick={() => {
+          if (hasChildren) toggleExpanded(item.key);
+          onSelect(item);
+        }}
+        /*
+         * Password-manager browser extensions (Dashlane, 1Password, etc.)
+         * decorate form/input buttons with their own `data-*` attributes
+         * after server render but before React hydration. That trips
+         * React's hydration mismatch warning. We're not rendering an
+         * input — just a navigation button — so suppress the diff on
+         * unrelated attribute injections.
+         */
+        suppressHydrationWarning
+        className={cn(
+          'group flex w-full items-center gap-2 rounded-md py-2 pl-2.5 pr-2.5 text-left text-sm text-primary-foreground/90 transition-colors',
+          'hover:bg-primary-foreground/10 hover:text-primary-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary-foreground/60',
+          'disabled:cursor-not-allowed disabled:opacity-50',
+          /* Active or breadcrumb-on-path */
+          (isActive || onActivePath) && 'bg-accent text-accent-foreground font-medium hover:bg-accent hover:text-accent-foreground',
+          (isActive || onActivePath) && activeItemClassName,
+          itemClassName,
+        )}
+      >
+        {item.icon ? (
+          <span className="grid size-5 shrink-0 place-items-center text-inherit [&_svg]:size-full" aria-hidden="true">
+            {item.icon}
+          </span>
+        ) : null}
+        <span className="min-w-0 flex-1 truncate">{item.label}</span>
+        {item.badge != null && item.badge !== false ? (
+          shouldWrapBadge(item.badge) ? (
+            <span className="inline-flex h-5 min-w-5 items-center justify-center rounded-full bg-current/15 px-1.5 text-xs font-medium text-current">
+              {item.badge}
+            </span>
+          ) : (
+            <span className="inline-flex shrink-0 items-center">{item.badge}</span>
+          )
+        ) : null}
+        {hasChildren ? (
+          <svg
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            className={cn(
+              'size-3.5 shrink-0 transition-transform duration-200',
+              isExpanded && 'rotate-90',
+            )}
+            aria-hidden="true"
+          >
+            <path d="m9 18 6-6-6-6" strokeLinecap="round" strokeLinejoin="round" />
+          </svg>
+        ) : null}
+      </button>
+      {hasChildren && isExpanded ? (
+        /*
+         * Indent the child group with a vertical guide line. The line sits
+         * under the parent icon column (ml-[1.0625rem] aligns it to the
+         * centre of the icon); content shifts right via pl-3 so the line
+         * stays a single 1px stroke. The same wrapper is used at every
+         * depth, so arbitrary nesting (level-3+) renders with consistent,
+         * stacking guide lines.
+         */
+        <div
+          role="group"
+          aria-label={`${item.label} sub-items`}
+          className="ml-[1.0625rem] border-l border-primary-foreground/15 pl-2 py-0.5"
+        >
+          {(item.children ?? []).map((child) => (
+            <ExpandedRow
+              key={child.key}
+              item={child}
+              depth={depth + 1}
+              activeKey={activeKey}
+              onSelect={onSelect}
+              expandedKeys={expandedKeys}
+              toggleExpanded={toggleExpanded}
+              itemClassName={itemClassName}
+              activeItemClassName={activeItemClassName}
+            />
+          ))}
+        </div>
+      ) : null}
+    </>
+  );
+}
+
+interface ExpandedSearchMatchProps {
+  item: MainSidebarItem;
+  breadcrumbs: string[];
+  activeKey: string | undefined;
+  onSelect: (item: MainSidebarItem) => void;
+  itemClassName: string | undefined;
+}
+
+function ExpandedSearchMatch({ item, breadcrumbs, activeKey, onSelect, itemClassName }: ExpandedSearchMatchProps) {
+  return (
+    <button
+      type="button"
+      disabled={item.disabled}
+      onClick={() => onSelect(item)}
+      suppressHydrationWarning
+      className={cn(
+        'group flex w-full items-center gap-2 rounded-md px-2.5 py-2 text-left text-sm text-primary-foreground/90 transition-colors',
+        'hover:bg-primary-foreground/10 hover:text-primary-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary-foreground/60',
+        'disabled:cursor-not-allowed disabled:opacity-50',
+        item.key === activeKey && 'bg-accent text-accent-foreground font-medium hover:bg-accent hover:text-accent-foreground',
+        itemClassName,
+      )}
+    >
+      {item.icon ? (
+        <span className="grid size-5 shrink-0 place-items-center text-inherit [&_svg]:size-full" aria-hidden="true">
+          {item.icon}
+        </span>
+      ) : null}
+      <span className="min-w-0 flex-1">
+        <span className="block truncate">{item.label}</span>
+        {breadcrumbs.length ? (
+          <span className="block truncate text-[11px] text-current/60">
+            {breadcrumbs.join(' › ')}
+          </span>
+        ) : null}
+      </span>
+      {item.badge != null && item.badge !== false ? (
+        shouldWrapBadge(item.badge) ? (
+          <span className="inline-flex h-5 min-w-5 items-center justify-center rounded-full bg-current/15 px-1.5 text-xs font-medium text-current">
+            {item.badge}
+          </span>
+        ) : (
+          <span className="inline-flex shrink-0 items-center">{item.badge}</span>
+        )
+      ) : null}
+    </button>
+  );
+}
+
+interface ExpandedSidebarInternalProps extends MainSidebarProps {
+  onCollapse: () => void;
+}
+
+function CollapseChevron({
+  onClick,
+  label,
+  side,
+}: {
+  onClick: () => void;
+  label: string;
+  side: 'left' | 'right';
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label={label}
+      className="grid size-7 shrink-0 place-items-center rounded-md text-primary-foreground/80 transition-colors hover:bg-primary-foreground/10 hover:text-primary-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-foreground/60"
+    >
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" className="size-4" aria-hidden="true">
+        <path d={side === 'right' ? 'm9 18 6-6-6-6' : 'm15 18-6-6 6-6'} strokeLinecap="round" strokeLinejoin="round" />
+      </svg>
+    </button>
+  );
+}
+
+export const ExpandedSidebar = forwardRef<HTMLElement, ExpandedSidebarInternalProps>(function ExpandedSidebar(
+  {
+    items,
+    activeKey,
+    onItemSelect,
+    header,
+    footer,
+    search = false,
+    searchPlaceholder,
+    onSearchChange,
+    side = 'left',
+    expandedWidth = '15rem',
+    showCollapseToggle = true,
+    onCollapse,
+    itemClassName,
+    activeItemClassName,
+    className,
+    style: outerStyle,
+    collapsedLabel = 'Collapse menu',
+    /* Strip non-DOM props that come from MainSidebarProps so they don't land on <nav>. */
+    variant: _variant,
+    expanded: _expanded,
+    defaultExpanded: _defaultExpanded,
+    onExpandedChange: _onExpandedChange,
+    panelHeader: _panelHeader,
+    panelFooter: _panelFooter,
+    density: _density,
+    panelWidth: _panelWidth,
+    motionPreset: _motionPreset,
+    showLabelsWhenExpanded: _showLabelsWhenExpanded,
+    collapsible: _collapsible,
+    collapsed: _collapsed,
+    defaultCollapsed: _defaultCollapsed,
+    onCollapsedChange: _onCollapsedChange,
+    collapsedWidth: _collapsedWidth,
+    closeOnOutsideClick: _closeOnOutsideClick,
+    columnsMaxVisible: _columnsMaxVisible,
+    hoverDelayMs: _hoverDelayMs,
+    railClassName: _railClassName,
+    panelClassName: _panelClassName,
+    expandedLabel: _expandedLabel,
+    backLabel: _backLabel,
+    mobile: _mobile,
+    ...rest
+  },
+  ref,
+) {
+  void _variant;
+  void _expanded;
+  void _defaultExpanded;
+  void _onExpandedChange;
+  void _panelHeader;
+  void _panelFooter;
+  void _density;
+  void _panelWidth;
+  void _motionPreset;
+  void _showLabelsWhenExpanded;
+  void _collapsible;
+  void _collapsed;
+  void _defaultCollapsed;
+  void _onCollapsedChange;
+  void _collapsedWidth;
+  void _closeOnOutsideClick;
+  void _columnsMaxVisible;
+  void _hoverDelayMs;
+  void _railClassName;
+  void _panelClassName;
+  void _expandedLabel;
+  void _backLabel;
+  void _mobile;
+  const searchEnabled = search !== false;
+  const searchCfg = typeof search === 'object' ? search : undefined;
+  const matcher = searchCfg?.matcher ?? defaultMatcher;
+
+  const [query, setQuery] = useState('');
+  const searchActive = query.trim().length > 0;
+  const matches = useMemo(
+    () => (searchActive ? flatMatchTree(items, query, matcher) : []),
+    [items, query, matcher, searchActive],
+  );
+
+  /* Every parent starts collapsed. The user explicitly opens what they need. */
+  const [expandedKeys, setExpandedKeys] = useState<Set<string>>(() => new Set());
+
+  function toggleExpanded(key: string) {
+    setExpandedKeys((prev) => {
+      const next = new Set(prev);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  }
+
+  function onSelect(item: MainSidebarItem) {
+    if (item.disabled) return;
+    onItemSelect?.(item.key, item);
+  }
+
+  function updateQuery(next: string) {
+    setQuery(next);
+    onSearchChange?.(next);
+  }
+
+  const widthValue = typeof expandedWidth === 'number' ? `${expandedWidth}px` : expandedWidth;
+
+  return (
+    <nav
+      ref={ref}
+      aria-label="Main navigation"
+      style={{ width: widthValue, ...outerStyle }}
+      className={cn(
+        'relative flex h-full shrink-0 flex-col bg-primary text-primary-foreground',
+        side === 'right' ? 'border-l border-primary-700/40' : 'border-r border-primary-700/40',
+        className,
+      )}
+      {...rest}
+    >
+      {/*
+        When a header prop is provided, render the dedicated header band plus
+        an optional separate search row. When no header is provided, merge
+        the collapse button into the search row to avoid an empty top band.
+      */}
+      {header ? (
+        <div className="flex items-center justify-between gap-2 border-b border-primary-foreground/10 px-3 py-2.5">
+          <div className="min-w-0 flex-1">{header}</div>
+          {showCollapseToggle ? (
+            <CollapseChevron onClick={onCollapse} label={collapsedLabel} side={side} />
+          ) : null}
+        </div>
+      ) : null}
+
+      {(searchEnabled || (!header && showCollapseToggle)) ? (
+        <div className="flex items-center gap-2 border-b border-primary-foreground/10 px-3 py-2">
+          {searchEnabled ? (
+            <div className="min-w-0 flex-1">
+              <MenuSearch
+                value={query}
+                onValueChange={updateQuery}
+                placeholder={searchCfg?.placeholder ?? searchPlaceholder ?? 'Search menu…'}
+                tone="onBrand"
+              />
+            </div>
+          ) : null}
+          {!header && showCollapseToggle ? (
+            <CollapseChevron onClick={onCollapse} label={collapsedLabel} side={side} />
+          ) : null}
+        </div>
+      ) : null}
+
+      <div className="flex-1 overflow-y-auto p-2">
+        {searchActive ? (
+          matches.length === 0 ? (
+            <div className="px-4 py-8 text-center text-sm text-primary-foreground/70">
+              {searchCfg?.noResultsLabel ?? `No items match "${query}".`}
+            </div>
+          ) : (
+            matches.map((m) => (
+              <ExpandedSearchMatch
+                key={m.item.key + m.breadcrumbs.join('>')}
+                item={m.item}
+                breadcrumbs={m.breadcrumbs}
+                activeKey={activeKey}
+                onSelect={onSelect}
+                itemClassName={itemClassName}
+              />
+            ))
+          )
+        ) : (
+          items.map((item) => (
+            <ExpandedRow
+              key={item.key}
+              item={item}
+              depth={0}
+              activeKey={activeKey}
+              onSelect={onSelect}
+              expandedKeys={expandedKeys}
+              toggleExpanded={toggleExpanded}
+              itemClassName={itemClassName}
+              activeItemClassName={activeItemClassName}
+            />
+          ))
+        )}
+      </div>
+
+      {footer ? (
+        <div className="border-t border-primary-foreground/10 px-3 py-2.5">{footer}</div>
+      ) : null}
+    </nav>
+  );
+});

package/src/MainSidebar/floating.tsx

@@ -0,0 +1,268 @@
+'use client';
+
+/**
+ * MainSidebar — `floating` variant.
+ *
+ * Rail click opens an overlay panel beside the rail. The panel floats on top
+ * of the page content (does NOT push layout). Dismisses on outside click,
+ * Esc, or repeated rail-icon click.
+ */
+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, CloseButton } from './back-button.js';
+import { PathBreadcrumb } from './breadcrumb.js';
+import { defaultMatcher, filterLevel, isOnPath, opensPanel, resolvePath } from './helpers.js';
+import { slideVariants } from './motion.js';
+import type { MainSidebarItem, MainSidebarProps } from './types.js';
+
+export const FloatingSidebar = forwardRef<HTMLElement, MainSidebarProps>(function FloatingSidebar(
+  {
+    items,
+    activeKey,
+    expanded,
+    defaultExpanded = false,
+    onExpandedChange,
+    onItemSelect,
+    header,
+    footer,
+    panelHeader,
+    panelFooter,
+    search = false,
+    searchPlaceholder,
+    onSearchChange,
+    side = 'left',
+    density = 'comfortable',
+    panelWidth = 288,
+    motionPreset = 'expressive',
+    closeOnOutsideClick = true,
+    railClassName,
+    panelClassName,
+    itemClassName,
+    activeItemClassName,
+    backLabel = 'Back',
+    expandedLabel = 'Close menu',
+    className,
+    ...rest
+  },
+  ref,
+) {
+  const reduceMotion = useReducedMotion();
+  const effectivePreset = reduceMotion ? 'subtle' : motionPreset;
+
+  const [internalExpanded, setInternalExpanded] = useState(defaultExpanded);
+  const isExpanded = expanded ?? internalExpanded;
+  const [pathKeys, setPathKeys] = useState<string[]>([]);
+  const path = useMemo(() => resolvePath(items, pathKeys), [items, pathKeys]);
+  const current = path.at(-1);
+
+  const [query, setQuery] = useState('');
+  const searchEnabled = search !== false;
+  const searchCfg = typeof search === 'object' ? search : undefined;
+  const matcher = searchCfg?.matcher ?? defaultMatcher;
+  const currentItems = current?.children ?? [];
+  const filtered = filterLevel(currentItems, query, matcher);
+
+  const panelRef = useRef<HTMLDivElement>(null);
+  const railRef = useRef<HTMLElement>(null);
+
+  function resetDeepState() {
+    setPathKeys([]);
+    setQuery('');
+  }
+
+  function setExpanded(next: boolean) {
+    if (expanded === undefined) setInternalExpanded(next);
+    if (!next) resetDeepState();
+    onExpandedChange?.(next);
+  }
+
+  function closePanel() {
+    resetDeepState();
+    setExpanded(false);
+  }
+
+  function selectRailItem(item: MainSidebarItem) {
+    if (item.disabled) return;
+    onItemSelect?.(item.key, item);
+    if (opensPanel(item)) {
+      if (current?.key === item.key && isExpanded) {
+        setExpanded(false);
+        return;
+      }
+      setPathKeys([item.key]);
+      setExpanded(true);
+      setQuery('');
+    } else {
+      setExpanded(false);
+    }
+  }
+
+  function selectPanelItem(item: MainSidebarItem) {
+    if (item.disabled) return;
+    onItemSelect?.(item.key, item);
+    if (opensPanel(item)) {
+      setPathKeys((prev) => (prev.at(-1) === item.key ? prev : [...prev, item.key]));
+      setQuery('');
+    }
+  }
+
+  /* Outside-click + Escape */
+  useEffect(() => {
+    if (!isExpanded) return;
+    function onPointerDown(e: PointerEvent) {
+      if (!closeOnOutsideClick) return;
+      const target = e.target as Node;
+      if (panelRef.current?.contains(target) || railRef.current?.contains(target)) return;
+      setExpanded(false);
+    }
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') closePanel();
+    }
+    document.addEventListener('pointerdown', onPointerDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown);
+      document.removeEventListener('keydown', onKey);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isExpanded, closeOnOutsideClick]);
+
+  function updateQuery(next: string) {
+    setQuery(next);
+    onSearchChange?.(next);
+  }
+
+  function goBack() {
+    setPathKeys((prev) => prev.slice(0, -1));
+    setQuery('');
+  }
+
+  return (
+    <div
+      ref={ref as never}
+      className={cn('relative h-full', className)}
+      {...rest}
+    >
+      <Rail
+        ref={railRef}
+        items={items}
+        activeKey={activeKey}
+        density={density}
+        side={side}
+        header={header}
+        footer={footer}
+        itemClassName={itemClassName}
+        activeItemClassName={activeItemClassName}
+        className={railClassName}
+        onItemSelect={selectRailItem}
+        openPanelKey={isExpanded ? current?.key : undefined}
+      />
+
+      <AnimatePresence initial={false} mode="wait">
+        {isExpanded && current ? (
+          <motion.div
+            key={current.key + ':' + path.length}
+            ref={panelRef}
+            variants={slideVariants(effectivePreset, side === 'right' ? 'right' : 'left')}
+            initial="initial"
+            animate="animate"
+            exit="exit"
+            role="menu"
+            aria-label={current.label}
+            style={{
+              width: typeof panelWidth === 'number' ? `${panelWidth}px` : panelWidth,
+              [side === 'right' ? 'right' : 'left']: density === 'compact' ? '3rem' : '3.5rem',
+            }}
+            className={cn(
+              'absolute top-0 z-10 flex h-full flex-col rounded-xl border border-border bg-card text-card-foreground shadow-xl',
+              'm-2',
+              panelClassName,
+            )}
+          >
+            <div className="border-b border-border px-4 py-3">
+              {panelHeader ?? (
+                <div className="flex items-start justify-between gap-3">
+                  <div className="min-w-0">
+                    {path.length > 1 ? (
+                      <>
+                        <PathBreadcrumb
+                          path={path}
+                          onJump={(depth) => setPathKeys((prev) => prev.slice(0, depth + 1))}
+                          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 text-xs text-card-foreground/70">{current.description}</p>
+                    ) : null}
+                  </div>
+                  <CloseButton onClick={closePanel} label={expandedLabel} />
+                </div>
+              )}
+              {searchEnabled ? (
+                <div className="mt-3">
+                  <MenuSearch
+                    value={query}
+                    onValueChange={updateQuery}
+                    placeholder={searchCfg?.placeholder ?? searchPlaceholder ?? `Search ${current.label}…`}
+                  
+                  tone="onBrand"
+                  />
+                </div>
+              ) : null}
+            </div>
+
+            <div className="flex-1 overflow-y-auto p-2">
+              {filtered.length === 0 && query ? (
+                <div className="px-4 py-8 text-center text-sm text-card-foreground/70">
+                  {searchCfg?.noResultsLabel ?? `No items match "${query}".`}
+                </div>
+              ) : (
+                filtered.map((item) => {
+                  const onActivePath = isOnPath(item, activeKey) || pathKeys.includes(item.key);
+                  return (
+                  <button
+                    key={item.key}
+                    type="button"
+                    onClick={() => selectPanelItem(item)}
+                    disabled={item.disabled}
+                    className={cn(
+                      'group flex w-full items-center gap-2.5 rounded-md px-2.5 py-2 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',
+                      onActivePath && 'bg-accent text-accent-foreground font-medium hover:bg-accent hover:text-accent-foreground',
+                      itemClassName,
+                      onActivePath && activeItemClassName,
+                    )}
+                  >
+                    {item.icon ? (
+                      <span className="grid size-5 shrink-0 place-items-center text-card-foreground/70 group-hover:text-card-foreground [&_svg]:size-full" aria-hidden="true">
+                        {item.icon}
+                      </span>
+                    ) : null}
+                    <span className="min-w-0 flex-1 truncate">{item.label}</span>
+                    {opensPanel(item) ? (
+                      <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>
+
+            {panelFooter ? (
+              <div className="border-t border-border px-4 py-3">{panelFooter}</div>
+            ) : null}
+          </motion.div>
+        ) : null}
+      </AnimatePresence>
+    </div>
+  );
+});