@mihcm/ui 0.14.1 → 0.15.0

package/src/MainSidebar/columns.tsx

@@ -0,0 +1,350 @@
+'use client';
+
+/**
+ * MainSidebar — `columns` variant.
+ *
+ * Miller columns (Finder-style). Each drill keeps the previous column
+ * visible; horizontally scrolling stacked columns. Each column has its
+ * own per-level search.
+ */
+import { forwardRef, useEffect, useMemo, useRef, useState } from 'react';
+import { flushSync } from 'react-dom';
+import { AnimatePresence, motion, useReducedMotion } from 'motion/react';
+import { cn } from '../internal/cn.js';
+import { Rail } from './rail.js';
+import { MenuSearch } from './search.js';
+import { CloseButton } from './back-button.js';
+import { defaultMatcher, filterLevel, isOnPath, opensPanel, resolvePath } from './helpers.js';
+import { slideVariants } from './motion.js';
+import type { MainSidebarItem, MainSidebarProps } from './types.js';
+
+export const ColumnsSidebar = forwardRef<HTMLElement, MainSidebarProps>(function ColumnsSidebar(
+  {
+    items,
+    activeKey,
+    expanded,
+    defaultExpanded = false,
+    onExpandedChange,
+    onItemSelect,
+    header,
+    footer,
+    search = false,
+    searchPlaceholder,
+    onSearchChange,
+    side = 'left',
+    density = 'comfortable',
+    panelWidth = 240,
+    motionPreset = 'expressive',
+    closeOnOutsideClick = true,
+    columnsMaxVisible = 3,
+    railClassName,
+    panelClassName,
+    itemClassName,
+    activeItemClassName,
+    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 searchEnabled = search !== false;
+  const searchCfg = typeof search === 'object' ? search : undefined;
+  const matcher = searchCfg?.matcher ?? defaultMatcher;
+
+  /* One search query per column index. */
+  const [queries, setQueries] = useState<Record<number, string>>({});
+
+  /*
+   * Columns map one-to-one with the path nodes. Each column displays the
+   * CHILDREN of the corresponding path node:
+   *
+   *   path = [payroll]              → columns = [payroll.children]
+   *   path = [people, onboarding]   → columns = [people.children, onboarding.children]
+   *
+   * The rail itself surfaces the root-level items, so we don't repeat them
+   * as a column — clicking a rail icon jumps straight to its children.
+   */
+  const columns = useMemo(() => {
+    const cols: MainSidebarItem[][] = [];
+    for (const node of path) {
+      if (node.children?.length) cols.push(node.children);
+    }
+    return cols;
+  }, [path]);
+
+  /**
+   * Reset all deep state synchronously. Called from close handlers so the
+   * panel reopens with a fresh stack instead of remembering the previous
+   * drill-down path.
+   */
+  function resetDeepState() {
+    setPathKeys([]);
+    setQueries({});
+  }
+
+  function setExpanded(next: boolean) {
+    if (expanded === undefined) setInternalExpanded(next);
+    if (!next) resetDeepState();
+    onExpandedChange?.(next);
+  }
+
+  function closePanel() {
+    /*
+     * `flushSync` commits the column-stack reset BEFORE we flip
+     * `isExpanded`, so AnimatePresence captures the panel with just the
+     * root column (or none) for its slide-out exit — instead of all the
+     * deeply-drilled columns being frozen in the exit frame.
+     */
+    // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- We need the column-stack reset to commit to the DOM BEFORE the panel slide-out is captured by AnimatePresence, otherwise stale deep columns linger in the exit frame.
+    flushSync(() => {
+      resetDeepState();
+    });
+    setExpanded(false);
+  }
+
+  const panelRef = useRef<HTMLDivElement>(null);
+  const railRef = useRef<HTMLElement>(null);
+
+  /* Esc + outside-click close the panel from anywhere. */
+  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), and pass
+   * `preventScroll: true` so the browser never yanks the page scroll
+   * to the just-focused element.
+   */
+  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. Reuse `closePanel` so the deep-column reset is
+         flushed BEFORE the exit animation, otherwise the user sees stale
+         sub-columns slide out. */
+      if (isExpanded && pathKeys[0] === item.key) {
+        closePanel();
+        return;
+      }
+      setPathKeys([item.key]);
+      setExpanded(true);
+      setQueries({});
+    } else {
+      closePanel();
+    }
+  }
+
+  function selectColumnItem(colIndex: number, item: MainSidebarItem) {
+    if (item.disabled) return;
+    onItemSelect?.(item.key, item);
+    /*
+     * Column N shows path[N].children, so a click in column N adds a child
+     * AFTER path[N]. Truncate any deeper drilling and push the new key
+     * when the clicked item itself opens deeper panels.
+     */
+    const keepAncestors = path.slice(0, colIndex + 1).map((p) => p.key);
+    if (opensPanel(item)) {
+      setPathKeys([...keepAncestors, item.key]);
+    } else {
+      setPathKeys(keepAncestors);
+    }
+  }
+
+  function updateColumnQuery(colIndex: number, next: string) {
+    setQueries((prev) => ({ ...prev, [colIndex]: next }));
+    onSearchChange?.(next);
+  }
+
+  /*
+   * Column N shows path[N].children. The breadcrumb-active item in column N
+   * is the path node one step deeper (path[N + 1]), if the user drilled
+   * further. On the leaf column, fall back to the externally-controlled
+   * `activeKey` so the selected leaf stays highlighted.
+   */
+  function activeInColumn(colIndex: number) {
+    return path[colIndex + 1]?.key ?? (colIndex === path.length - 1 ? activeKey : undefined);
+  }
+
+  const widthPx = typeof panelWidth === 'number' ? `${panelWidth}px` : panelWidth;
+  const maxWidth = `calc(${columnsMaxVisible} * ${widthPx})`;
+  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 ? path[0]?.key : undefined}
+      />
+
+      <AnimatePresence initial={false} mode="wait">
+        {isExpanded ? (
+          <motion.div
+            key="cols"
+            ref={panelRef}
+            variants={slideVariants(effectivePreset, side === 'right' ? 'right' : 'left')}
+            initial="initial"
+            animate="animate"
+            exit="exit"
+            role="menu"
+            aria-label={path[0]?.label ?? 'Navigation'}
+            style={{
+              maxWidth,
+              [side === 'right' ? 'right' : 'left']: railOffset,
+            }}
+            className={cn(
+              'absolute top-0 z-10 flex h-full min-w-0 overflow-x-auto bg-card shadow-xl',
+              side === 'right' ? 'border-l border-border' : 'border-r border-border',
+              panelClassName,
+            )}
+          >
+            {columns.map((col, colIndex) => {
+              const q = queries[colIndex] ?? '';
+              const filtered = filterLevel(col, q, matcher);
+              /* Column N displays path[N]'s children, so path[N] is the parent header. */
+              const parent = path[colIndex];
+              const columnKey = parent?.key ?? `col-${colIndex}`;
+              return (
+                <div
+                  key={columnKey}
+                  style={{ width: widthPx, minWidth: widthPx }}
+                  className={cn(
+                    'flex h-full shrink-0 flex-col',
+                    colIndex < columns.length - 1 && 'border-r border-border',
+                  )}
+                >
+                  <div className="border-b border-border px-4 py-3">
+                    <div className="flex items-start justify-between gap-3">
+                      <div className="min-w-0">
+                        <div className="truncate text-base font-semibold text-card-foreground">
+                          {parent?.label ?? 'Menu'}
+                        </div>
+                        {parent?.description ? (
+                          <p className="mt-0.5 text-xs text-card-foreground/70">{parent.description}</p>
+                        ) : null}
+                      </div>
+                      {colIndex === 0 ? (
+                        <CloseButton onClick={closePanel} label={expandedLabel} />
+                      ) : null}
+                    </div>
+                    {searchEnabled ? (
+                      <div className="mt-3">
+                        <MenuSearch
+                          value={q}
+                          onValueChange={(v) => updateColumnQuery(colIndex, v)}
+                          placeholder={searchCfg?.placeholder ?? searchPlaceholder ?? `Search ${parent?.label ?? 'menu'}…`}
+                        
+                        tone="onBrand"
+                        />
+                      </div>
+                    ) : null}
+                  </div>
+                  <div className="flex-1 overflow-y-auto p-1.5">
+                    {filtered.length === 0 && q ? (
+                      <div className="px-3 py-6 text-center text-xs text-card-foreground/70">
+                        {searchCfg?.noResultsLabel ?? `No items match "${q}".`}
+                      </div>
+                    ) : (
+                      filtered.map((item) => {
+                        /* Highlight if it's the live activeKey leaf, or if it's the column-level breadcrumb, or if its subtree contains the active key. */
+                        const isOnBreadcrumb = item.key === activeInColumn(colIndex);
+                        const containsActive = isOnPath(item, activeKey);
+                        const isActive = isOnBreadcrumb || containsActive;
+                        return (
+                          <button
+                            key={item.key}
+                            type="button"
+                            onClick={() => selectColumnItem(colIndex, 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',
+                              isActive && 'bg-primary text-primary-foreground hover:bg-primary',
+                              itemClassName,
+                              isActive && activeItemClassName,
+                            )}
+                          >
+                            {item.icon ? (
+                              <span className={cn('grid size-4 shrink-0 place-items-center [&_svg]:size-full', !isActive && 'text-card-foreground/70')} 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 shrink-0" aria-hidden="true">
+                                <path d="m9 18 6-6-6-6" strokeLinecap="round" strokeLinejoin="round" />
+                              </svg>
+                            ) : null}
+                          </button>
+                        );
+                      })
+                    )}
+                  </div>
+                </div>
+              );
+            })}
+          </motion.div>
+        ) : null}
+      </AnimatePresence>
+    </div>
+  );
+});