@mihcm/ui 0.14.1 → 0.15.1

package/src/MainSidebar/command.tsx

@@ -0,0 +1,404 @@
+'use client';
+
+/**
+ * MainSidebar — `command` variant.
+ *
+ * Two modes in one panel:
+ *
+ *   - **Drilldown** when the search input is empty — rows with chevrons for
+ *     items that have children; click to drill, back via chevron.
+ *   - **Flat search** when the user types — recursive tree filter with
+ *     breadcrumb paths on each match. Arrow keys + Enter pick by keyboard.
+ *
+ * The panel overlays the page rather than pushing layout.
+ */
+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, flatMatchTree, firstPanelItem, isOnPath, opensPanel, resolvePath, shouldWrapBadge } from './helpers.js';
+import { slideVariants } from './motion.js';
+import type { MainSidebarItem, MainSidebarProps } from './types.js';
+
+export const CommandSidebar = forwardRef<HTMLElement, MainSidebarProps>(function CommandSidebar(
+  {
+    items,
+    activeKey,
+    expanded,
+    defaultExpanded = false,
+    onExpandedChange,
+    onItemSelect,
+    header,
+    footer,
+    panelHeader,
+    panelFooter,
+    search = true,
+    searchPlaceholder,
+    onSearchChange,
+    side = 'left',
+    density = 'comfortable',
+    panelWidth = 360,
+    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 [query, setQuery] = useState('');
+  const [focusIndex, setFocusIndex] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const panelRef = useRef<HTMLElement>(null);
+  const railRef = useRef<HTMLElement>(null);
+
+  const searchCfg = typeof search === 'object' ? search : undefined;
+  const matcher = searchCfg?.matcher ?? defaultMatcher;
+
+  /* Drilldown state (active when query is empty). */
+  const rootItem = useMemo(() => firstPanelItem(items, activeKey), [activeKey, items]);
+  const [pathKeys, setPathKeys] = useState<string[]>([]);
+  const path = useMemo(() => {
+    const resolved = resolvePath(items, pathKeys);
+    return resolved.length ? resolved : rootItem ? [rootItem] : [];
+  }, [items, pathKeys, rootItem]);
+  const current = path.at(-1);
+  const drilldownItems = current?.children ?? items;
+
+  const searchActive = query.trim().length > 0;
+  const matches = useMemo(
+    () => (searchActive ? flatMatchTree(items, query, matcher) : []),
+    [items, query, matcher, searchActive],
+  );
+
+  const railOffset = density === 'compact' ? '3rem' : '3.5rem';
+
+  /*
+   * Skip auto-focus on initial mount so a `defaultExpanded` command
+   * sidebar doesn't yank the page scroll to its search input on page
+   * load. Pass `preventScroll: true` as belt-and-braces.
+   */
+  const focusInitialisedRef = useRef(false);
+  useEffect(() => {
+    if (!isExpanded) {
+      focusInitialisedRef.current = true;
+      return undefined;
+    }
+    setFocusIndex(0);
+    if (!focusInitialisedRef.current) {
+      focusInitialisedRef.current = true;
+      return undefined;
+    }
+    const id = window.setTimeout(() => inputRef.current?.focus({ preventScroll: true }), 0);
+    return () => window.clearTimeout(id);
+  }, [isExpanded]);
+
+  useEffect(() => {
+    setFocusIndex(0);
+  }, [query]);
+
+  function resetDeepState() {
+    setQuery('');
+    setPathKeys([]);
+  }
+
+  function setExpanded(next: boolean) {
+    if (expanded === undefined) setInternalExpanded(next);
+    if (!next) resetDeepState();
+    onExpandedChange?.(next);
+  }
+
+  function closePanel() {
+    resetDeepState();
+    setExpanded(false);
+  }
+
+  /* Outside-click closes the panel. */
+  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;
+      closePanel();
+    }
+    document.addEventListener('pointerdown', onPointerDown);
+    return () => document.removeEventListener('pointerdown', onPointerDown);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isExpanded, closeOnOutsideClick]);
+
+  function selectRailItem(item: MainSidebarItem) {
+    if (item.disabled) return;
+    onItemSelect?.(item.key, item);
+    if (opensPanel(item)) {
+      if (isExpanded && pathKeys[0] === item.key && !searchActive) {
+        setExpanded(false);
+        return;
+      }
+      setPathKeys([item.key]);
+      setQuery('');
+      setExpanded(true);
+    } else {
+      setExpanded(false);
+    }
+  }
+
+  function selectDrilldownItem(item: MainSidebarItem) {
+    if (item.disabled) return;
+    onItemSelect?.(item.key, item);
+    if (opensPanel(item)) {
+      setPathKeys((prev) => (prev.at(-1) === item.key ? prev : [...prev, item.key]));
+    }
+  }
+
+  function findStackTo(target: string, list: MainSidebarItem[] = items, acc: string[] = []): string[] | null {
+    for (const it of list) {
+      if (it.key === target) return [...acc, it.key];
+      if (it.children) {
+        const found = findStackTo(target, it.children, [...acc, it.key]);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  function pickMatch(idx: number) {
+    const m = matches[idx];
+    if (!m || m.item.disabled) return;
+    onItemSelect?.(m.item.key, m.item);
+    if (opensPanel(m.item)) {
+      const stack = findStackTo(m.item.key) ?? [m.item.key];
+      setPathKeys(stack);
+      setQuery('');
+    } else {
+      setExpanded(false);
+    }
+  }
+
+  function goBack() {
+    setPathKeys((prev) => prev.slice(0, -1));
+  }
+
+  function onKey(e: React.KeyboardEvent<HTMLDivElement>) {
+    if (!searchActive) {
+      if (e.key === 'Escape') closePanel();
+      return;
+    }
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setFocusIndex((i) => Math.min(matches.length - 1, i + 1));
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setFocusIndex((i) => Math.max(0, i - 1));
+    } else if (e.key === 'Enter') {
+      e.preventDefault();
+      pickMatch(focusIndex);
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      if (query) setQuery('');
+      else closePanel();
+    }
+  }
+
+  function updateQuery(next: string) {
+    setQuery(next);
+    onSearchChange?.(next);
+  }
+
+  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 ? (
+          <motion.aside
+            key="command"
+            ref={panelRef}
+            variants={slideVariants(effectivePreset, side === 'right' ? 'right' : 'left')}
+            initial="initial"
+            animate="animate"
+            exit="exit"
+            style={{
+              width: typeof panelWidth === 'number' ? `${panelWidth}px` : panelWidth,
+              [side === 'right' ? 'right' : 'left']: railOffset,
+            }}
+            className={cn(
+              'absolute top-0 z-10 flex h-full min-w-0 flex-col bg-card shadow-xl',
+              side === 'right' ? 'border-l border-border' : 'border-r border-border',
+              panelClassName,
+            )}
+            onKeyDown={onKey}
+          >
+            <div className="border-b border-border px-4 py-3">
+              {panelHeader ?? (
+                <div className="flex items-start justify-between gap-3 pb-3">
+                  <div className="min-w-0">
+                    {!searchActive && 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">
+                      {searchActive ? 'Quick navigation' : current?.label ?? 'Menu'}
+                    </div>
+                    {!searchActive && current?.description ? (
+                      <p className="mt-0.5 truncate text-xs text-card-foreground/70">{current.description}</p>
+                    ) : null}
+                  </div>
+                  <CloseButton onClick={closePanel} label={expandedLabel} />
+                </div>
+              )}
+              <MenuSearch
+                ref={inputRef}
+                value={query}
+                onValueChange={updateQuery}
+                placeholder={searchCfg?.placeholder ?? searchPlaceholder ?? 'Search all menus…'}
+              
+              tone="onBrand"
+              />
+              {searchActive ? (
+                <div className="mt-2 flex items-center justify-between text-[11px] text-card-foreground/70">
+                  <span>{matches.length} {matches.length === 1 ? 'match' : 'matches'}</span>
+                  <span className="inline-flex items-center gap-1">
+                    <kbd className="rounded border border-border bg-card-foreground/10 px-1.5 py-0.5 text-[10px] font-mono">↑↓</kbd>
+                    <kbd className="rounded border border-border bg-card-foreground/10 px-1.5 py-0.5 text-[10px] font-mono">↵</kbd>
+                  </span>
+                </div>
+              ) : null}
+            </div>
+
+            {searchActive ? (
+              <div role="listbox" aria-label="Menu search results" className="flex-1 overflow-y-auto p-2">
+                {matches.length === 0 ? (
+                  <div className="px-4 py-8 text-center text-sm text-card-foreground/70">
+                    {searchCfg?.noResultsLabel ?? `No items match "${query}".`}
+                  </div>
+                ) : (
+                  matches.map((m, idx) => (
+                    <div
+                      key={m.item.key + idx}
+                      role="option"
+                      aria-selected={idx === focusIndex}
+                      onMouseEnter={() => setFocusIndex(idx)}
+                      onClick={() => pickMatch(idx)}
+                      className={cn(
+                        'group flex cursor-pointer items-center gap-3 rounded-md px-2.5 py-2 text-sm text-card-foreground transition-colors',
+                        idx === focusIndex && 'bg-card-foreground/10',
+                        m.item.disabled && 'cursor-not-allowed opacity-50',
+                        itemClassName,
+                        m.item.key === activeKey && 'text-card-foreground font-semibold',
+                        m.item.key === activeKey && activeItemClassName,
+                      )}
+                    >
+                      {m.item.icon ? (
+                        <span className="grid size-5 shrink-0 place-items-center text-card-foreground/70 [&_svg]:size-full" aria-hidden="true">
+                          {m.item.icon}
+                        </span>
+                      ) : null}
+                      <div className="min-w-0 flex-1">
+                        <div className="truncate font-medium">{m.item.label}</div>
+                        {m.breadcrumbs.length ? (
+                          <div className="truncate text-[11px] text-card-foreground/70">
+                            {m.breadcrumbs.join(' › ')}
+                          </div>
+                        ) : null}
+                      </div>
+                      {m.item.badge != null && m.item.badge !== false ? (
+                        shouldWrapBadge(m.item.badge) ? (
+                          <span className="ml-auto 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">
+                            {m.item.badge}
+                          </span>
+                        ) : (
+                          <span className="ml-auto inline-flex shrink-0 items-center">{m.item.badge}</span>
+                        )
+                      ) : null}
+                    </div>
+                  ))
+                )}
+              </div>
+            ) : (
+              <div className="flex-1 overflow-y-auto p-2">
+                {filterLevel(drilldownItems, '').map((item) => {
+                  const onActivePath = isOnPath(item, activeKey) || pathKeys.includes(item.key);
+                  return (
+                  <button
+                    key={item.key}
+                    type="button"
+                    onClick={() => selectDrilldownItem(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>
+                    {item.badge != null && item.badge !== false ? (
+                      shouldWrapBadge(item.badge) ? (
+                        <span className="ml-auto 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="ml-auto inline-flex shrink-0 items-center">{item.badge}</span>
+                      )
+                    ) : null}
+                    {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.aside>
+        ) : null}
+      </AnimatePresence>
+    </div>
+  );
+});