@mihcm/ui 0.14.1 → 0.15.0

package/src/IconSidebar.tsx

@@ -1,448 +1,26 @@
 'use client';
 
 /**
- * MainSidebar (web variant — React DOM).
+ * IconSidebar — legacy alias.
  *
- * Figma rail: compact 46 px primary-blue icon strip with an accent selected item.
- * Expansion: controlled/uncontrolled drilldown panel that slides beside the rail.
- *
- * `IconSidebar` remains as a compatibility alias.
- *
- * Wiki: docs/components/IconSidebar.md
+ * The implementation moved to `@mihcm/ui/MainSidebar` and gained five
+ * interaction-model variants. This file remains so existing
+ * `import { IconSidebar } from '@mihcm/ui/IconSidebar'` consumers keep
+ * working without changes. New code should import from `MainSidebar`.
  */
-import { forwardRef, useMemo, useState, type HTMLAttributes, type ReactNode } from 'react';
-import { cn } from './internal/cn.js';
-
-export interface MainSidebarItem {
-  key: string;
-  icon: ReactNode;
-  label: string;
-  href?: string;
-  description?: string;
-  badge?: ReactNode;
-  disabled?: boolean;
-  children?: MainSidebarItem[];
-  panel?: ReactNode;
-}
-
-export interface MainSidebarProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect'> {
-  items: MainSidebarItem[];
-  activeKey?: string;
-  expanded?: boolean;
-  defaultExpanded?: boolean;
-  onExpandedChange?: (expanded: boolean) => void;
-  onItemSelect?: (key: string, item: MainSidebarItem) => void;
-  header?: ReactNode;
-  footer?: ReactNode;
-  panelHeader?: ReactNode;
-  panelFooter?: ReactNode;
-  railClassName?: string;
-  panelClassName?: string;
-  itemClassName?: string;
-  activeItemClassName?: string;
-  collapsedLabel?: string;
-  expandedLabel?: string;
-  backLabel?: string;
-  showLabelsWhenExpanded?: boolean;
-  side?: 'left' | 'right';
-  /** Force the bottom mobile navigation pattern for docs, tests, or mobile-only shells. */
-  mobile?: boolean;
-}
-
-export type IconSidebarItem = MainSidebarItem;
-export type IconSidebarProps = MainSidebarProps;
-
-function ChevronLeftIcon() {
-  return (
-    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden>
-      <path d="m15 18-6-6 6-6" strokeLinecap="round" strokeLinejoin="round" />
-    </svg>
-  );
-}
-
-function ChevronRightIcon() {
-  return (
-    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden>
-      <path d="m9 18 6-6-6-6" strokeLinecap="round" strokeLinejoin="round" />
-    </svg>
-  );
-}
-
-function MenuIcon() {
-  return (
-    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden>
-      <path d="M4 7h16M4 12h16M4 17h16" strokeLinecap="round" />
-    </svg>
-  );
-}
-
-function findItem(items: MainSidebarItem[], key?: string): 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;
-}
-
-function firstPanelItem(items: MainSidebarItem[], activeKey?: string) {
-  const active = findItem(items, activeKey);
-  if (active?.children?.length || active?.panel) return active;
-  return items.find((item) => item.children?.length || item.panel) ?? items[0];
-}
-
-function opensPanel(item: MainSidebarItem) {
-  return Boolean(item.children?.length || item.panel);
-}
-
-export const MainSidebar = forwardRef<HTMLElement, MainSidebarProps>(function MainSidebar(
-  {
-    className,
-    items,
-    activeKey,
-    expanded,
-    defaultExpanded = false,
-    onExpandedChange,
-    onItemSelect,
-    header,
-    footer,
-    panelHeader,
-    panelFooter,
-    railClassName,
-    panelClassName,
-    itemClassName,
-    activeItemClassName,
-    collapsedLabel = 'Expand main sidebar',
-    expandedLabel = 'Collapse main sidebar',
-    backLabel = 'Back',
-    showLabelsWhenExpanded = true,
-    side = 'left',
-    mobile = false,
-    ...props
-  },
-  ref,
-) {
-  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 = pathKeys
-      .map((key) => findItem(items, key))
-      .filter((item): item is MainSidebarItem => Boolean(item));
-    return resolved.length ? resolved : rootItem ? [rootItem] : [];
-  }, [items, pathKeys, rootItem]);
-
-  const current = path.at(-1);
-  const currentItems = current?.children ?? items;
-  const isRightSide = side === 'right';
-
-  function setExpanded(next: boolean) {
-    if (expanded === undefined) setInternalExpanded(next);
-    if (!next) setPathKeys([]);
-    onExpandedChange?.(next);
-  }
-
-  function selectRailItem(item: MainSidebarItem) {
-    if (item.disabled) return;
-    onItemSelect?.(item.key, item);
-
-    if (opensPanel(item)) {
-      setPathKeys([item.key]);
-      setExpanded(true);
-    } else {
-      setPathKeys([]);
-    }
-  }
-
-  function selectPanelItem(item: MainSidebarItem) {
-    if (item.disabled) return;
-    onItemSelect?.(item.key, item);
-
-    if (opensPanel(item)) {
-      setExpanded(true);
-      setPathKeys((previous) =>
-        previous.at(-1) === item.key ? previous : [...previous, item.key],
-      );
-    }
-  }
-
-  const panel = isExpanded ? (
-    <div
-      className={cn(
-        'min-w-0 bg-card text-card-foreground shadow-mi-card',
-        isRightSide ? 'border-l border-border' : 'border-r border-border',
-        'w-full md:w-72 md:flex-none',
-        isRightSide
-          ? 'animate-in fade-in slide-in-from-right-2 duration-300'
-          : 'animate-in fade-in slide-in-from-left-2 duration-300',
-        panelClassName,
-      )}
-    >
-      <div className="flex h-full flex-col">
-        <div className="border-b border-border px-5 py-4">
-          {panelHeader ?? (
-            <div className="flex items-center justify-between gap-3">
-              <div className="min-w-0">
-                <div className="text-sm font-semibold">{current?.label ?? 'Main Sidebar'}</div>
-                {current?.description ? (
-                  <p className="mt-1 text-xs text-muted-foreground">{current.description}</p>
-                ) : null}
-              </div>
-              <button
-                type="button"
-                aria-label={expandedLabel}
-                onClick={() => setExpanded(false)}
-                className="grid size-8 shrink-0 place-items-center rounded-md text-muted-foreground transition hover:bg-muted hover:text-foreground focus:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-              >
-                {isRightSide ? <ChevronRightIcon /> : <ChevronLeftIcon />}
-              </button>
-            </div>
-          )}
-        </div>
-
-        <div className="min-h-0 flex-1 overflow-y-auto px-3 py-4">
-          {path.length > 1 ? (
-            <button
-              type="button"
-              onClick={() => setPathKeys((previous) => previous.slice(0, -1))}
-              className="mb-3 inline-flex items-center gap-2 rounded-md px-2 py-1.5 text-xs font-medium text-muted-foreground transition hover:bg-muted hover:text-foreground focus:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-            >
-              <span className="[&_svg]:size-4">
-                <ChevronLeftIcon />
-              </span>
-              {backLabel}
-            </button>
-          ) : null}
-
-          {current?.panel ? (
-            <div className="animate-in fade-in slide-in-from-left-2 duration-200">
-              {current.panel}
-            </div>
-          ) : (
-            <div className="grid gap-1 animate-in fade-in slide-in-from-right-2 duration-200">
-              {currentItems.map((item) => {
-                const isActive = item.key === activeKey;
-                const hasChildren = opensPanel(item);
-                return (
-                  <button
-                    key={item.key}
-                    type="button"
-                    disabled={item.disabled}
-                    onClick={() => selectPanelItem(item)}
-                    className={cn(
-                      'group flex w-full items-center gap-3 rounded-md px-3 py-2.5 text-left transition',
-                      'focus:outline-none focus-visible:ring-2 focus-visible:ring-ring',
-                      item.disabled && 'cursor-not-allowed opacity-40',
-                      isActive ? 'bg-accent text-primary-foreground' : 'hover:bg-muted',
-                    )}
-                  >
-                    <span className="grid size-8 shrink-0 place-items-center rounded-md bg-muted text-foreground group-hover:bg-background [&_svg]:size-4">
-                      {item.icon}
-                    </span>
-                    <span className="min-w-0 flex-1">
-                      <span className="block truncate text-sm font-medium">{item.label}</span>
-                      {item.description ? (
-                        <span
-                          className={cn(
-                            'mt-0.5 block text-xs',
-                            isActive ? 'text-primary-foreground/80' : 'text-muted-foreground',
-                          )}
-                        >
-                          {item.description}
-                        </span>
-                      ) : null}
-                    </span>
-                    {item.badge ? <span className="shrink-0">{item.badge}</span> : null}
-                    {hasChildren ? (
-                      <span className="shrink-0 text-muted-foreground [&_svg]:size-4">
-                        <ChevronRightIcon />
-                      </span>
-                    ) : null}
-                  </button>
-                );
-              })}
-            </div>
-          )}
-        </div>
-
-        {showLabelsWhenExpanded ? (
-          <div className="border-t border-border px-5 py-4 text-xs text-muted-foreground">
-            {currentItems.length} navigation {currentItems.length === 1 ? 'item' : 'items'}
-          </div>
-        ) : null}
-        {panelFooter ? <div className="border-t border-border px-5 py-4">{panelFooter}</div> : null}
-      </div>
-    </div>
-  ) : null;
-
-  return (
-    <>
-      <nav
-        aria-label="Main Sidebar"
-        data-expanded={isExpanded ? 'true' : 'false'}
-        data-mobile={mobile ? 'true' : undefined}
-        className={cn('absolute inset-x-0 bottom-0 z-30', !mobile && 'md:hidden', className)}
-      >
-        {isExpanded ? (
-          <div className="absolute inset-x-3 bottom-full mb-3 max-h-96 overflow-hidden rounded-lg border border-border bg-card text-card-foreground shadow-mi-popover">
-            {panel}
-          </div>
-        ) : null}
-        <div
-          className={cn(
-            'flex items-stretch border-t border-primary/80 bg-primary text-primary-foreground',
-            railClassName,
-          )}
-        >
-          <div className="flex min-w-0 flex-1 overflow-x-auto">
-            {items.map((item) => {
-              const isActive = item.key === activeKey;
-              const mobileItemClassName = cn(
-                'grid min-w-18 flex-1 place-items-center gap-1 px-3 py-2 text-caption transition',
-                'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-foreground/70',
-                item.disabled && 'cursor-not-allowed opacity-40',
-                isActive ? 'bg-accent text-primary-foreground' : 'text-primary-foreground/75',
-                itemClassName,
-                isActive && activeItemClassName,
-              );
-              const mobileItemContent = (
-                <>
-                  <span className="[&_svg]:size-5">{item.icon}</span>
-                  <span className="max-w-16 truncate">{item.label}</span>
-                </>
-              );
-
-              if (item.href && !item.disabled && !item.children?.length && !item.panel) {
-                return (
-                  <a
-                    key={item.key}
-                    href={item.href}
-                    aria-label={item.label}
-                    aria-current={isActive ? 'page' : undefined}
-                    aria-disabled={item.disabled || undefined}
-                    className={mobileItemClassName}
-                  >
-                    {mobileItemContent}
-                  </a>
-                );
-              }
-
-              return (
-                <button
-                  key={item.key}
-                  type="button"
-                  disabled={item.disabled}
-                  aria-label={item.label}
-                  aria-current={isActive ? 'page' : undefined}
-                  aria-disabled={item.disabled || undefined}
-                  onClick={() => selectRailItem(item)}
-                  className={mobileItemClassName}
-                >
-                  {mobileItemContent}
-                </button>
-              );
-            })}
-          </div>
-          <button
-            type="button"
-            aria-label={isExpanded ? expandedLabel : collapsedLabel}
-            aria-expanded={isExpanded}
-            onClick={() => setExpanded(!isExpanded)}
-            className="grid min-w-16 place-items-center gap-1 border-l border-primary-foreground/15 px-3 py-2 text-caption text-primary-foreground/85 transition hover:bg-primary-foreground/10 focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-foreground/70"
-          >
-            <span className="[&_svg]:size-5">
-              <MenuIcon />
-            </span>
-            Menu
-          </button>
-        </div>
-      </nav>
-
-      <aside
-        ref={ref}
-        aria-label="Main Sidebar"
-        data-expanded={isExpanded ? 'true' : 'false'}
-        data-side={side}
-        data-mobile={mobile ? 'false' : undefined}
-        className={cn(
-          'h-full flex-shrink-0 overflow-hidden bg-primary text-primary-foreground',
-          mobile ? 'hidden' : 'hidden md:flex',
-          isRightSide && 'flex-row-reverse',
-          'transition-[width] duration-300 ease-out',
-          isExpanded ? 'w-[20.875rem]' : 'w-11.5',
-          className,
-        )}
-        {...props}
-      >
-        <div
-          className={cn(
-            'flex w-11.5 shrink-0 flex-col items-center gap-9 overflow-hidden bg-primary pb-20',
-            railClassName,
-          )}
-        >
-          {header ? <div className="flex w-full justify-center">{header}</div> : null}
-          <nav className="flex flex-col items-center" aria-label="Primary">
-            {items.map((item) => {
-              const isActive = item.key === activeKey;
-              const shared = {
-                'aria-label': item.label,
-                'aria-current': isActive ? ('page' as const) : undefined,
-                'aria-disabled': item.disabled || undefined,
-                title: item.label,
-                className: cn(
-                  'grid h-11.5 w-11.5 shrink-0 place-items-center transition-colors duration-150',
-                  'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-foreground/70',
-                  item.disabled ? 'cursor-not-allowed opacity-40' : 'cursor-pointer',
-                  isActive
-                    ? 'bg-accent text-primary-foreground opacity-100'
-                    : 'text-primary-foreground opacity-70 hover:opacity-100 focus-visible:opacity-100',
-                  itemClassName,
-                  isActive && activeItemClassName,
-                ),
-              };
-              const content = <span className="[&_svg]:size-5">{item.icon}</span>;
-
-              if (item.href && !item.disabled && !item.children?.length && !item.panel) {
-                return (
-                  <a key={item.key} href={item.href} {...shared}>
-                    {content}
-                  </a>
-                );
-              }
-
-              return (
-                <button
-                  key={item.key}
-                  type="button"
-                  disabled={item.disabled}
-                  onClick={() => selectRailItem(item)}
-                  {...shared}
-                >
-                  {content}
-                </button>
-              );
-            })}
-          </nav>
-          {footer ? <div className="mt-auto flex w-full justify-center">{footer}</div> : null}
-          <button
-            type="button"
-            aria-label={isExpanded ? expandedLabel : collapsedLabel}
-            aria-expanded={isExpanded}
-            onClick={() => setExpanded(!isExpanded)}
-            className="mb-3 grid size-8 place-items-center rounded-md text-primary-foreground/80 transition hover:bg-primary-foreground/10 hover:text-primary-foreground focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-foreground/70"
-          >
-            <MenuIcon />
-          </button>
-        </div>
-
-        {panel}
-      </aside>
-    </>
-  );
-});
 
-export const IconSidebar = MainSidebar;
+export {
+  IconSidebar,
+  MainSidebar,
+  type IconSidebarItem,
+  type IconSidebarProps,
+  type MainSidebarCollapsible,
+  type MainSidebarColorScheme,
+  type MainSidebarDensity,
+  type MainSidebarItem,
+  type MainSidebarMotionPreset,
+  type MainSidebarProps,
+  type MainSidebarSearchConfig,
+  type MainSidebarSide,
+  type MainSidebarVariant,
+} from './MainSidebar/index.js';

package/src/MainSidebar/back-button.tsx

@@ -0,0 +1,58 @@
+'use client';
+
+/**
+ * Shared back / chevron button. Used by drilldown + columns + floating
+ * panel headers.
+ */
+import { cn } from '../internal/cn.js';
+
+interface BackButtonProps {
+  onClick: () => void;
+  label: string;
+  className?: string;
+}
+
+export function BackButton({ onClick, label, className }: BackButtonProps) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={cn(
+        'inline-flex items-center gap-1 rounded-md px-1.5 py-1 text-xs font-medium text-card-foreground/70 transition-colors',
+        'hover:bg-card-foreground/10 hover:text-card-foreground',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-card-foreground/40',
+        className,
+      )}
+    >
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" className="size-3.5" aria-hidden="true">
+        <path d="m15 18-6-6 6-6" strokeLinecap="round" strokeLinejoin="round" />
+      </svg>
+      {label}
+    </button>
+  );
+}
+
+interface CloseButtonProps {
+  onClick: () => void;
+  label: string;
+  className?: string;
+}
+
+export function CloseButton({ onClick, label, className }: CloseButtonProps) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label={label}
+      className={cn(
+        'grid size-8 shrink-0 place-items-center rounded-md text-card-foreground/70 transition hover:bg-card-foreground/10 hover:text-card-foreground',
+        'focus:outline-none focus-visible:ring-2 focus-visible:ring-card-foreground/40',
+        className,
+      )}
+    >
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" className="size-4" aria-hidden="true">
+        <path d="M6 6l12 12M18 6 6 18" strokeLinecap="round" />
+      </svg>
+    </button>
+  );
+}

package/src/MainSidebar/breadcrumb.tsx

@@ -0,0 +1,53 @@
+'use client';
+
+/**
+ * Path breadcrumb shared by drilldown / floating / columns / command / hover.
+ *
+ * Renders the drilled-into ancestors as clickable text crumbs so the user can
+ * jump back to any level in one click. Used in the panel header when the
+ * `path` is deeper than the root.
+ *
+ *   <PathBreadcrumb path={[people, onboarding]} onJump={(idx) => ...} />
+ *   ⇒  People › Onboarding
+ *
+ * `path` is the full ancestor list (including the current leaf). The leaf
+ * itself renders as the panel title, so the breadcrumb stops at
+ * `path.length - 1`.
+ */
+import { cn } from '../internal/cn.js';
+import type { MainSidebarItem } from './types.js';
+
+interface PathBreadcrumbProps {
+  path: MainSidebarItem[];
+  /** Click handler — receives the depth index to jump to. */
+  onJump: (depth: number) => void;
+  className?: string;
+}
+
+export function PathBreadcrumb({ path, onJump, className }: PathBreadcrumbProps) {
+  if (path.length <= 1) return null;
+  const ancestors = path.slice(0, -1);
+  return (
+    <nav
+      aria-label="Breadcrumb"
+      className={cn('flex flex-wrap items-center gap-1 text-xs text-card-foreground/70', className)}
+    >
+      <ol className="flex flex-wrap items-center gap-1">
+        {ancestors.map((node, idx) => (
+          <li key={node.key} className="flex items-center gap-1">
+            <button
+              type="button"
+              onClick={() => onJump(idx)}
+              className="rounded px-1 py-0.5 text-xs font-medium text-card-foreground/70 transition-colors hover:bg-card-foreground/10 hover:text-card-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-card-foreground/40"
+            >
+              {node.label}
+            </button>
+            <span aria-hidden="true" className="text-card-foreground/50">
+              ›
+            </span>
+          </li>
+        ))}
+      </ol>
+    </nav>
+  );
+}