@mihcm/ui 0.14.1 → 0.15.0

package/src/MainSidebar/mobile.tsx

@@ -0,0 +1,117 @@
+'use client';
+
+/**
+ * MainSidebar — `mobile` rendering.
+ *
+ * On phones and tablets the full sidebar (rail or expanded) consumes too
+ * much horizontal space. This component renders a single hamburger button
+ * inline; tapping it opens the wide `ExpandedSidebar` inside a `Sheet`
+ * overlay slid in from the chosen `side`. The page area stays clear.
+ *
+ * Triggered via `<MainSidebar mobile items={…} />` — the dispatcher routes
+ * here when `mobile === true`. Sheet handles outside-tap dismissal, Esc,
+ * focus-trap, and the scrim, so this component just composes existing
+ * primitives.
+ */
+import { forwardRef, useState, type ReactNode } from 'react';
+import { cn } from '../internal/cn.js';
+import { Sheet, SheetContent } from '../Sheet.js';
+import { ExpandedSidebar } from './expanded.js';
+import type { MainSidebarProps } from './types.js';
+
+function HamburgerIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
+      aria-hidden="true"
+    >
+      <path d="M3 6h18M3 12h18M3 18h18" />
+    </svg>
+  );
+}
+
+interface MobileSidebarProps extends MainSidebarProps {
+  /** Render-prop override for the trigger — receives an `onClick` to open. */
+  trigger?: (props: { onClick: () => void; 'aria-label': string }) => ReactNode;
+  /** Class hook for the default hamburger button. Ignored when `trigger` is set. */
+  triggerClassName?: string;
+  /** Accessible label on the hamburger. Default: "Open menu". */
+  triggerLabel?: string;
+}
+
+export const MobileSidebar = forwardRef<HTMLButtonElement, MobileSidebarProps>(
+  function MobileSidebar(
+    {
+      side = 'left',
+      trigger,
+      triggerClassName,
+      triggerLabel = 'Open menu',
+      colorScheme: _colorScheme,
+      style: _style,
+      className: _className,
+      ...sidebarProps
+    },
+    ref,
+  ) {
+    void _colorScheme;
+    void _style;
+    void _className;
+    const [open, setOpen] = useState(false);
+    const sheetSide = side === 'right' ? 'right' : 'left';
+
+    return (
+      <>
+        {trigger ? (
+          trigger({ onClick: () => setOpen(true), 'aria-label': triggerLabel })
+        ) : (
+          <button
+            ref={ref}
+            type="button"
+            aria-label={triggerLabel}
+            aria-haspopup="menu"
+            aria-expanded={open}
+            onClick={() => setOpen(true)}
+            className={cn(
+              'inline-flex size-10 items-center justify-center rounded-md text-foreground',
+              'hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+              triggerClassName,
+            )}
+          >
+            <HamburgerIcon className="size-5" />
+          </button>
+        )}
+
+        <Sheet open={open} onOpenChange={setOpen}>
+          <SheetContent
+            side={sheetSide}
+            size="sm"
+            className="p-0 bg-primary border-0"
+            aria-label="Main navigation"
+          >
+            <ExpandedSidebar
+              {...sidebarProps}
+              side={sheetSide}
+              showCollapseToggle
+              onCollapse={() => setOpen(false)}
+              collapsedLabel="Close menu"
+              /*
+               * Make the sidebar fill the sheet — the Sheet's `size` prop
+               * controls the visible width, the sidebar should not impose
+               * its own width on top of that or a stripe of the sheet's
+               * card background shows through.
+               */
+              expandedWidth="100%"
+              className="h-full w-full border-0"
+            />
+          </SheetContent>
+        </Sheet>
+      </>
+    );
+  },
+);

package/src/MainSidebar/motion.ts

@@ -0,0 +1,64 @@
+/**
+ * Motion presets for `MainSidebar` variants.
+ *
+ * Three intensity levels. Variants pull from this single source so the
+ * design-system motion vocabulary stays consistent.
+ *
+ * Reduced motion: every variant component checks `prefers-reduced-motion`
+ * and falls back to instant cuts when the OS-level preference is set.
+ */
+import type { Transition, Variants } from 'motion/react';
+import type { MainSidebarMotionPreset } from './types.js';
+
+interface MotionConfig {
+  /** Slide distance in px on enter. */
+  distance: number;
+  /** Motion transition. */
+  transition: Transition;
+}
+
+export const MOTION_PRESETS: Record<MainSidebarMotionPreset, MotionConfig> = {
+  subtle: {
+    distance: 4,
+    transition: { duration: 0.18, ease: [0.16, 1, 0.3, 1] },
+  },
+  standard: {
+    distance: 8,
+    transition: { duration: 0.24, ease: [0.32, 0.72, 0, 1] },
+  },
+  expressive: {
+    distance: 16,
+    transition: { type: 'spring', stiffness: 320, damping: 28, mass: 0.9 },
+  },
+};
+
+export function slideVariants(
+  preset: MainSidebarMotionPreset,
+  fromSide: 'left' | 'right',
+): Variants {
+  const cfg = MOTION_PRESETS[preset];
+  const sign = fromSide === 'left' ? -1 : 1;
+  return {
+    initial: { opacity: 0, x: sign * cfg.distance },
+    animate: { opacity: 1, x: 0, transition: cfg.transition },
+    exit: { opacity: 0, x: sign * cfg.distance, transition: cfg.transition },
+  };
+}
+
+export function fadeVariants(preset: MainSidebarMotionPreset): Variants {
+  const cfg = MOTION_PRESETS[preset];
+  return {
+    initial: { opacity: 0 },
+    animate: { opacity: 1, transition: cfg.transition },
+    exit: { opacity: 0, transition: cfg.transition },
+  };
+}
+
+export function scaleVariants(preset: MainSidebarMotionPreset): Variants {
+  const cfg = MOTION_PRESETS[preset];
+  return {
+    initial: { opacity: 0, scale: 0.96, y: -4 },
+    animate: { opacity: 1, scale: 1, y: 0, transition: cfg.transition },
+    exit: { opacity: 0, scale: 0.96, y: -4, transition: cfg.transition },
+  };
+}

package/src/MainSidebar/rail.tsx

@@ -0,0 +1,137 @@
+'use client';
+
+/**
+ * Shared rail — the fixed icon strip on the side. Used by all five variants.
+ */
+import { forwardRef, type ReactNode } from 'react';
+import { cn } from '../internal/cn.js';
+import { Tooltip } from '../Tooltip.js';
+import { isOnPath, shouldWrapBadge } from './helpers.js';
+import type {
+  MainSidebarDensity,
+  MainSidebarItem,
+  MainSidebarSide,
+} from './types.js';
+
+const RAIL_WIDTH = {
+  compact: 'w-12',
+  comfortable: 'w-[3.5rem]',
+} as const;
+
+const RAIL_BUTTON = {
+  compact: 'h-12 w-full',
+  comfortable: 'h-14 w-full',
+} as const;
+
+interface RailProps {
+  items: MainSidebarItem[];
+  activeKey: string | undefined;
+  density?: MainSidebarDensity;
+  side?: MainSidebarSide;
+  header?: ReactNode;
+  footer?: ReactNode;
+  itemClassName: string | undefined;
+  activeItemClassName: string | undefined;
+  className: string | undefined;
+  onItemSelect: (item: MainSidebarItem) => void;
+  /** Item key whose panel is currently visible (for aria-expanded). */
+  openPanelKey: string | undefined;
+  /** Used for the toggle button aria-label. */
+  ariaLabel?: string;
+}
+
+export const Rail = forwardRef<HTMLElement, RailProps>(function Rail(
+  {
+    items,
+    activeKey,
+    density = 'comfortable',
+    side = 'left',
+    header,
+    footer,
+    itemClassName,
+    activeItemClassName,
+    className,
+    onItemSelect,
+    openPanelKey,
+    ariaLabel = 'Main navigation',
+  },
+  ref,
+) {
+  const railWidth = RAIL_WIDTH[density];
+  const buttonSize = RAIL_BUTTON[density];
+
+  return (
+    <nav
+      ref={ref}
+      aria-label={ariaLabel}
+      className={cn(
+        'relative z-20 flex h-full shrink-0 flex-col items-stretch bg-primary text-primary-foreground',
+        railWidth,
+        side === 'right' ? 'border-l border-primary-700/40' : 'border-r border-primary-700/40',
+        className,
+      )}
+    >
+      {header ? <div className="flex w-full items-center justify-center">{header}</div> : null}
+      <div className="flex w-full flex-col items-stretch">
+        {items.map((item) => {
+          /* Highlight the rail icon when the active leaf is anywhere in this item's subtree. */
+          const isActive = isOnPath(item, activeKey);
+          const isOpen = openPanelKey === item.key;
+          const tooltipSide = side === 'right' ? 'left' : 'right';
+          return (
+            <Tooltip
+              key={item.key}
+              content={item.label}
+              side={tooltipSide}
+              delayMs={80}
+              className="flex w-full"
+            >
+              <button
+                type="button"
+                data-item-key={item.key}
+                disabled={item.disabled}
+                aria-current={isActive ? 'page' : undefined}
+                aria-expanded={isOpen}
+                aria-haspopup={item.children?.length || item.panel ? 'menu' : undefined}
+                aria-label={item.label}
+                onClick={() => onItemSelect(item)}
+                className={cn(
+                  'relative grid place-items-center transition-colors outline-none',
+                  'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary-foreground/60',
+                  buttonSize,
+                  'text-primary-foreground/85 hover:bg-primary-foreground/10 hover:text-primary-foreground',
+                  'disabled:cursor-not-allowed disabled:opacity-40',
+                  isActive && 'bg-accent text-accent-foreground hover:bg-accent',
+                  isActive && activeItemClassName,
+                  itemClassName,
+                )}
+              >
+                <span className="grid size-[18px] place-items-center [&_svg]:size-full" aria-hidden="true">
+                  {item.icon}
+                </span>
+                <span className="sr-only">{item.label}</span>
+                {item.badge != null && item.badge !== false ? (
+                  shouldWrapBadge(item.badge) ? (
+                    <span
+                      aria-hidden="true"
+                      className="pointer-events-none absolute right-1 top-1 grid h-4 min-w-4 place-items-center rounded-full bg-destructive px-1 text-[10px] font-semibold text-destructive-foreground"
+                    >
+                      {item.badge}
+                    </span>
+                  ) : (
+                    <span aria-hidden="true" className="pointer-events-none absolute right-1 top-1">
+                      {item.badge}
+                    </span>
+                  )
+                ) : null}
+              </button>
+            </Tooltip>
+          );
+        })}
+      </div>
+      {footer ? (
+        <div className="mt-auto flex w-full items-center justify-center">{footer}</div>
+      ) : null}
+    </nav>
+  );
+});

package/src/MainSidebar/search.tsx

@@ -0,0 +1,99 @@
+'use client';
+
+/**
+ * Shared MenuSearch input used by all variants. Token-styled, accessible,
+ * with a clear affordance.
+ */
+import { forwardRef, type ChangeEventHandler } from 'react';
+import { cn } from '../internal/cn.js';
+
+interface MenuSearchProps {
+  value: string;
+  onValueChange: (next: string) => void;
+  placeholder?: string;
+  className?: string;
+  /** Auto-focus on mount — useful for command variant. */
+  autoFocus?: boolean;
+  /** Aria label for the input. Defaults to the placeholder. */
+  ariaLabel?: string;
+  /**
+   * Visual tone. `light` (default) renders the input on neutral panel
+   * backgrounds. `onBrand` renders a semi-transparent input legible on the
+   * brand-primary sidebar surface.
+   */
+  tone?: 'light' | 'onBrand';
+}
+
+export const MenuSearch = forwardRef<HTMLInputElement, MenuSearchProps>(function MenuSearch(
+  { value, onValueChange, placeholder = 'Search menu…', className, autoFocus, ariaLabel, tone = 'light' },
+  ref,
+) {
+  const onChange: ChangeEventHandler<HTMLInputElement> = (e) => onValueChange(e.target.value);
+  const onBrand = tone === 'onBrand';
+
+  return (
+    <div className={cn('relative flex w-full items-center', className)}>
+      <SearchIcon
+        className={cn(
+          'pointer-events-none absolute left-2.5 size-4',
+          /*
+           * `onBrand` uses card-foreground tokens. Both the rail (bg-primary)
+           * and any drill panel (bg-card) have their *-foreground tokens
+           * overridden to the same scheme.fg via `colorScheme`, so the
+           * search adapts cleanly on every themed surface AND on the
+           * default-brand panel (where card-foreground is the page dark
+           * foreground over a white card → readable).
+           */
+          onBrand ? 'text-card-foreground/60' : 'text-muted-foreground',
+        )}
+      />
+      <input
+        ref={ref}
+        type="search"
+        value={value}
+        onChange={onChange}
+        placeholder={placeholder}
+        aria-label={ariaLabel ?? placeholder}
+        autoFocus={autoFocus}
+        className={cn(
+          'h-9 w-full rounded-md pl-8 pr-8 text-sm',
+          onBrand
+            ? 'border border-card-foreground/20 bg-card-foreground/10 text-card-foreground placeholder:text-card-foreground/60 focus:outline-none focus:border-card-foreground/40 focus:ring-2 focus:ring-card-foreground/20'
+            : 'border border-border bg-background text-foreground shadow-mi-input placeholder:text-muted-foreground focus:outline-none focus:border-primary focus:ring-2 focus:ring-ring/30',
+        )}
+      />
+      {value ? (
+        <button
+          type="button"
+          onClick={() => onValueChange('')}
+          aria-label="Clear search"
+          className={cn(
+            'absolute right-1 grid size-7 place-items-center rounded focus-visible:outline-none focus-visible:ring-2',
+            onBrand
+              ? 'text-card-foreground/60 hover:bg-card-foreground/10 hover:text-card-foreground focus-visible:ring-card-foreground/40'
+              : 'text-muted-foreground hover:bg-muted hover:text-foreground focus-visible:ring-ring',
+          )}
+        >
+          <ClearIcon className="size-3.5" />
+        </button>
+      ) : null}
+    </div>
+  );
+});
+
+function SearchIcon({ className }: { className?: string }) {
+  return (
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" className={className} aria-hidden="true">
+      <circle cx="11" cy="11" r="7" />
+      <path d="m20 20-3.5-3.5" strokeLinecap="round" />
+    </svg>
+  );
+}
+
+function ClearIcon({ className }: { className?: string }) {
+  return (
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" className={className} aria-hidden="true">
+      <path d="M6 6l12 12M18 6 6 18" strokeLinecap="round" />
+    </svg>
+  );
+}

package/src/MainSidebar/types.ts

@@ -0,0 +1,208 @@
+/**
+ * Shared types for `MainSidebar` and its five variants.
+ */
+import type { HTMLAttributes, ReactNode } from 'react';
+
+export interface MainSidebarItem {
+  key: string;
+  icon?: ReactNode;
+  label: string;
+  href?: string;
+  description?: string;
+  badge?: ReactNode;
+  disabled?: boolean;
+  children?: MainSidebarItem[];
+  /** Override the auto-rendered child list with a custom panel. */
+  panel?: ReactNode;
+}
+
+export type MainSidebarVariant =
+  | 'drilldown'
+  | 'floating'
+  | 'columns'
+  | 'command'
+  | 'hover';
+
+export type MainSidebarSide = 'left' | 'right';
+
+export type MainSidebarDensity = 'compact' | 'comfortable';
+
+export type MainSidebarCollapsible = 'icon' | 'none';
+
+export type MainSidebarMotionPreset = 'subtle' | 'standard' | 'expressive';
+
+/**
+ * Per-instance colour overrides. Each token is optional and applies via a
+ * scoped CSS-variable override on the sidebar root, so the rest of the
+ * page is unaffected. Omitted tokens fall back to the design-system brand
+ * defaults. Structure mirrors shadcn's sidebar token taxonomy
+ * (`--sidebar-background`, `--sidebar-accent`, etc.).
+ *
+ * ### Quick-set shorthands
+ *
+ * | Token | Default | Sets |
+ * |---|---|---|
+ * | `bg` | `var(--color-primary)` | Both `railBg` AND `panelBg` |
+ * | `fg` | `var(--color-primary-foreground)` | Both `railFg` AND `panelFg` |
+ *
+ * ### Granular tokens (override individual surfaces)
+ *
+ * | Token | Default | Applies to |
+ * |---|---|---|
+ * | `railBg` | `var(--color-primary)` | Icon rail + wide expanded sidebar background |
+ * | `railFg` | `var(--color-primary-foreground)` | Icon rail + expanded text and icons |
+ * | `panelBg` | `var(--color-card)` | Drill/floating/columns/command/hover panel surface |
+ * | `panelFg` | `var(--color-card-foreground)` | Panel titles, item text, icons |
+ * | `accentBg` | `var(--color-accent)` | Active item background (rail + panel + expanded) |
+ * | `accentFg` | `var(--color-accent-foreground)` | Active item text |
+ * | `border` | `var(--color-border)` | All internal dividers + outer rail border |
+ * | `mutedFg` | `text-card-foreground/70` | Descriptions, breadcrumb crumbs, icon hints |
+ * | `hoverBg` | `card-foreground/10` | Hover overlay on every interactive row |
+ * | `ring` | `var(--color-ring)` | Focus ring on every interactive row |
+ * | `tooltipBg` | `var(--color-foreground)` | Rail-icon hover tooltip surface |
+ * | `tooltipFg` | `var(--color-background)` | Rail-icon hover tooltip text |
+ *
+ * Example — fully bespoke whitelabel:
+ *
+ * ```tsx
+ * <MainSidebar
+ *   colorScheme={{
+ *     railBg: '#0a2540', railFg: '#ffffff',
+ *     panelBg: '#11304b', panelFg: '#ffffff',
+ *     accentBg: '#ff5a1f', accentFg: '#ffffff',
+ *     mutedFg: 'rgb(255 255 255 / 0.6)',
+ *     hoverBg: 'rgb(255 255 255 / 0.08)',
+ *     border: 'rgb(255 255 255 / 0.16)',
+ *     ring: '#ff5a1f',
+ *     tooltipBg: '#ffffff', tooltipFg: '#0a2540',
+ *   }}
+ * />
+ * ```
+ */
+export interface MainSidebarColorScheme {
+  /* Shorthands (set both rail + panel at once) */
+  bg?: string;
+  fg?: string;
+
+  /* Per-surface */
+  railBg?: string;
+  railFg?: string;
+  panelBg?: string;
+  panelFg?: string;
+
+  /* Accent (active state) */
+  accentBg?: string;
+  accentFg?: string;
+
+  /* Lines + dividers */
+  border?: string;
+
+  /* Muted text + hover overlay */
+  mutedFg?: string;
+  hoverBg?: string;
+
+  /* Focus ring */
+  ring?: string;
+
+  /* Tooltip surface (rail-icon hover) */
+  tooltipBg?: string;
+  tooltipFg?: string;
+}
+
+export interface MainSidebarSearchConfig {
+  placeholder?: string;
+  /** Custom predicate; defaults to case-insensitive `item.label` match. */
+  matcher?: (item: MainSidebarItem, query: string) => boolean;
+  /** Shown when nothing matches. Default: "No menu items match {query}". */
+  noResultsLabel?: ReactNode;
+}
+
+export interface MainSidebarProps
+  extends Omit<HTMLAttributes<HTMLElement>, 'onSelect'> {
+  items: MainSidebarItem[];
+
+  /** Interaction model. Defaults to `drilldown` (backward-compatible). */
+  variant?: MainSidebarVariant;
+
+  /* Selection + controlled expansion */
+  activeKey?: string;
+  expanded?: boolean;
+  defaultExpanded?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+  onItemSelect?: (key: string, item: MainSidebarItem) => void;
+
+  /* Slots */
+  header?: ReactNode;
+  footer?: ReactNode;
+  panelHeader?: ReactNode;
+  panelFooter?: ReactNode;
+
+  /* Search */
+  search?: boolean | MainSidebarSearchConfig;
+  searchPlaceholder?: string;
+  onSearchChange?: (query: string) => void;
+
+  /* Visual */
+  side?: MainSidebarSide;
+  density?: MainSidebarDensity;
+  panelWidth?: number | string;
+  motionPreset?: MainSidebarMotionPreset;
+  showLabelsWhenExpanded?: boolean;
+
+  /* Collapse / expand — shadcn-style icon ↔ full toggle */
+  collapsible?: MainSidebarCollapsible;
+  collapsed?: boolean;
+  defaultCollapsed?: boolean;
+  onCollapsedChange?: (collapsed: boolean) => void;
+  collapsedWidth?: number | string;
+  expandedWidth?: number | string;
+  showCollapseToggle?: boolean;
+
+  /* Variant-specific */
+  /** Dismiss the panel when a pointer-down lands outside the rail + panel. Default true (all overlay variants). */
+  closeOnOutsideClick?: boolean;
+  /** Columns: how many columns can be visible at once before horizontal scroll. */
+  columnsMaxVisible?: number;
+  /** Hover: open delay in milliseconds. Default 120. */
+  hoverDelayMs?: number;
+
+  /* className overrides */
+  railClassName?: string;
+  panelClassName?: string;
+  itemClassName?: string;
+  activeItemClassName?: string;
+
+  /**
+   * Whitelabel colour scheme. Any subset of these tokens overrides the
+   * sidebar's surface, accent, border and tooltip colours per-instance —
+   * the values are emitted as CSS variables on the sidebar root so they
+   * cascade through every nested affordance (rail, expanded surface,
+   * tooltips, badges, breadcrumbs).
+   *
+   *   <MainSidebar
+   *     colorScheme={{
+   *       bg: '#0a2540',
+   *       fg: '#ffffff',
+   *       accentBg: '#ff5a1f',
+   *       accentFg: '#ffffff',
+   *       border: 'rgb(255 255 255 / 0.12)',
+   *     }}
+   *   />
+   *
+   * Any token may be omitted; omitted tokens fall back to the design
+   * system's brand defaults (primary / accent / border).
+   */
+  colorScheme?: MainSidebarColorScheme;
+
+  /* Labels for a11y */
+  collapsedLabel?: string;
+  expandedLabel?: string;
+  backLabel?: string;
+
+  /** Force the mobile bottom-sheet layout for previews/tests. */
+  mobile?: boolean;
+}
+
+/** Backward-compat aliases — IconSidebar was the original name. */
+export type IconSidebarItem = MainSidebarItem;
+export type IconSidebarProps = MainSidebarProps;

package/src/MainSidebar.tsx

@@ -1,10 +1,21 @@
 'use client';
 
+/**
+ * Public barrel for `@mihcm/ui/MainSidebar`. The implementation is split
+ * across `./MainSidebar/*` so each variant stays under the 400-line rule
+ * (CLAUDE.md §6).
+ */
+
 export {
-  MainSidebar,
   IconSidebar,
-  type MainSidebarItem,
-  type MainSidebarProps,
+  MainSidebar,
   type IconSidebarItem,
   type IconSidebarProps,
-} from './IconSidebar.js';
+  type MainSidebarDensity,
+  type MainSidebarItem,
+  type MainSidebarMotionPreset,
+  type MainSidebarProps,
+  type MainSidebarSearchConfig,
+  type MainSidebarSide,
+  type MainSidebarVariant,
+} from './MainSidebar/index.js';

package/src/NavigationMenu.tsx

@@ -99,7 +99,7 @@ export const NavigationMenuTrigger = forwardRef<
         stroke="currentColor"
         strokeWidth={2}
         className="relative top-px ml-1 h-3 w-3 transition-transform duration-200 group-data-[state=open]:rotate-180"
-        aria-hidden
+        aria-hidden="true"
       >
         <path strokeLinecap="round" strokeLinejoin="round" d="M4 6l4 4 4-4" />
       </svg>