@mihcm/ui 0.14.1 → 0.15.0

package/src/MainSidebar/drilldown.tsx

@@ -0,0 +1,373 @@
+'use client';
+
+/**
+ * MainSidebar — `drilldown` variant.
+ *
+ * Default. Rail click opens a panel beside the rail; deeper levels replace
+ * the current panel; back/breadcrumb to step out. Layout reflows.
+ */
+import { forwardRef, useEffect, useMemo, useRef, useState, type ReactNode } 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, findItem, firstPanelItem, isOnPath, opensPanel, resolvePath, shouldWrapBadge } from './helpers.js';
+import { slideVariants } from './motion.js';
+import type { MainSidebarItem, MainSidebarProps } from './types.js';
+
+interface PanelRowProps {
+  item: MainSidebarItem;
+  active?: boolean;
+  onClick: () => void;
+  showChevron?: boolean;
+  className: string | undefined;
+  activeClassName: string | undefined;
+}
+
+function PanelRow({ item, active, onClick, showChevron, className, activeClassName }: PanelRowProps) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={item.disabled}
+      aria-current={active ? 'page' : undefined}
+      className={cn(
+        'group flex w-full items-center gap-2.5 rounded-md px-2.5 py-2 text-left text-sm 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',
+        active && 'bg-accent text-accent-foreground font-medium hover:bg-accent hover:text-accent-foreground',
+        active && activeClassName,
+        className,
+      )}
+    >
+      {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-card-foreground/10 px-1.5 text-xs font-medium text-card-foreground/70">
+            {item.badge}
+          </span>
+        ) : (
+          <span className="ml-auto inline-flex shrink-0 items-center">{item.badge}</span>
+        )
+      ) : null}
+      {showChevron ? (
+        <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>
+  );
+}
+
+export const DrilldownSidebar = forwardRef<HTMLElement, MainSidebarProps>(function DrilldownSidebar(
+  {
+    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 = 'Collapse menu',
+    className,
+    ...rest
+  },
+  ref,
+) {
+  const reduceMotion = useReducedMotion();
+  const effectivePreset = reduceMotion ? 'subtle' : motionPreset;
+
+  const [internalExpanded, setInternalExpanded] = useState(defaultExpanded);
+  const isExpanded = expanded ?? internalExpanded;
+
+  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 [query, setQuery] = useState('');
+  const searchEnabled = search !== false;
+  const searchCfg = typeof search === 'object' ? search : undefined;
+  const matcher = searchCfg?.matcher ?? defaultMatcher;
+  const currentItems = current?.children ?? items;
+  const filtered = filterLevel(currentItems, query, matcher);
+
+  function resetDeepState() {
+    setPathKeys([]);
+    setQuery('');
+  }
+
+  function setExpanded(next: boolean) {
+    if (expanded === undefined) setInternalExpanded(next);
+    if (!next) resetDeepState();
+    onExpandedChange?.(next);
+  }
+
+  function closePanel() {
+    resetDeepState();
+    setExpanded(false);
+  }
+
+  const panelRef = useRef<HTMLElement>(null);
+  const railRef = useRef<HTMLElement>(null);
+
+  /* Esc + outside-click close the panel. */
+  useEffect(() => {
+    if (!isExpanded) 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);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isExpanded, closeOnOutsideClick]);
+
+  /*
+   * Move focus into the panel when it opens — but skip the initial
+   * mount (covers `defaultExpanded` and SSR hydration). Otherwise the
+   * browser scrolls the page to bring the just-focused input into view,
+   * landing the user halfway down the docs page. We also pass
+   * `preventScroll: true` as a belt-and-braces guard.
+   */
+  const focusInitialisedRef = useRef(false);
+  useEffect(() => {
+    if (!isExpanded) {
+      focusInitialisedRef.current = true;
+      return;
+    }
+    if (!focusInitialisedRef.current) {
+      focusInitialisedRef.current = true;
+      return;
+    }
+    const id = window.setTimeout(() => {
+      const focusable = panelRef.current?.querySelector<HTMLElement>(
+        'input, [role="searchbox"], button:not([disabled])',
+      );
+      focusable?.focus({ preventScroll: true });
+    }, 0);
+    return () => window.clearTimeout(id);
+  }, [isExpanded]);
+
+  function selectRailItem(item: MainSidebarItem) {
+    if (item.disabled) return;
+    onItemSelect?.(item.key, item);
+    if (opensPanel(item)) {
+      /* Toggle close when clicking the rail icon for the panel that's already open. */
+      if (isExpanded && pathKeys[0] === item.key) {
+        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('');
+    }
+  }
+
+  function goBack() {
+    setPathKeys((prev) => prev.slice(0, -1));
+    setQuery('');
+  }
+
+  function updateQuery(next: string) {
+    setQuery(next);
+    onSearchChange?.(next);
+  }
+
+  const railOffset = density === 'compact' ? '3rem' : '3.5rem';
+  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.aside
+            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']: railOffset,
+            }}
+            className={cn(
+              'absolute top-0 z-10 flex h-full min-w-0 flex-col bg-card text-card-foreground shadow-xl',
+              side === 'right' ? 'border-l border-border' : 'border-r border-border',
+              panelClassName,
+            )}
+          >
+            <div className="flex h-full flex-col">
+              <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>
+
+              <PanelList
+                items={filtered}
+                allItems={currentItems}
+                query={query}
+                noResultsLabel={searchCfg?.noResultsLabel}
+                activeKey={activeKey}
+                onItemSelect={selectPanelItem}
+                itemClassName={itemClassName}
+                activeItemClassName={activeItemClassName}
+                pathKeys={pathKeys}
+              />
+
+              {panelFooter ? (
+                <div className="mt-auto border-t border-border px-4 py-3">{panelFooter}</div>
+              ) : null}
+            </div>
+          </motion.aside>
+        ) : null}
+      </AnimatePresence>
+    </div>
+  );
+});
+
+function PanelList({
+  items,
+  allItems,
+  query,
+  noResultsLabel,
+  activeKey,
+  onItemSelect,
+  itemClassName,
+  activeItemClassName,
+  pathKeys,
+}: {
+  items: MainSidebarItem[];
+  allItems: MainSidebarItem[];
+  query: string;
+  noResultsLabel?: ReactNode;
+  activeKey: string | undefined;
+  onItemSelect: (item: MainSidebarItem) => void;
+  itemClassName: string | undefined;
+  activeItemClassName: string | undefined;
+  pathKeys: string[];
+}) {
+  if (items.length === 0 && query) {
+    return (
+      <div className="px-4 py-8 text-center text-sm text-card-foreground/70">
+        {noResultsLabel ?? `No items match "${query}".`}
+      </div>
+    );
+  }
+  void allItems;
+  return (
+    <div className="flex-1 overflow-y-auto p-2">
+      {items.map((item) => {
+        const onActivePath = isOnPath(item, activeKey) || pathKeys.includes(item.key);
+        return (
+          <PanelRow
+            key={item.key}
+            item={item}
+            active={onActivePath}
+            onClick={() => onItemSelect(item)}
+            showChevron={opensPanel(item)}
+            className={itemClassName}
+            activeClassName={activeItemClassName}
+          />
+        );
+      })}
+    </div>
+  );
+}