@qijenchen/design-system 0.1.0-beta.10

package/src/components/LinkInput/link-input.tsx

@@ -0,0 +1,304 @@
+import * as React from 'react'
+import { Pencil } from 'lucide-react'
+import type { VariantProps } from 'class-variance-authority'
+import { cn } from '@/lib/utils'
+import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
+import { fieldWrapperStyles, bareInputStyles, EMPTY_DISPLAY, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
+import { useFieldContext } from '@/design-system/components/Field/field-context'
+import { ItemInlineAction } from '@/design-system/patterns/element-anatomy/item-anatomy'
+
+// ── URL Validation ──────────────────────────────────────────────────────────
+
+function isValidUrl(value: string): boolean {
+  if (!value) return true
+  try {
+    const url = new URL(value)
+    return url.protocol === 'http:' || url.protocol === 'https:'
+  } catch {
+    return false
+  }
+}
+
+function formatHostname(url: string): string {
+  try {
+    return new URL(url).hostname.replace(/^www\./, '')
+  } catch {
+    return url
+  }
+}
+
+// ── Display rendering(inline,2026-05-05 Phase B3 retire LinkInputDisplay)──
+// 取代 LinkInputDisplay sub-component:純展示 a tag,無 input chrome、無 hover affordance。
+// edit mode 內 link state(showLink branch)也共用此 helper,確保「編輯態的 link 顯示」與
+// display mode 的視覺完全一致(SSOT)。
+function renderLinkAnchor(value: string, label?: string) {
+  const displayText = label || formatHostname(value)
+  return (
+    <a
+      href={value}
+      target="_blank"
+      rel="noopener noreferrer"
+      className="block truncate min-w-0 text-primary hover:text-primary-hover hover:underline transition-colors"
+    >
+      {displayText}
+    </a>
+  )
+}
+
+// ── Component ───────────────────────────────────────────────────────────────
+
+export interface LinkInputProps
+  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'onChange'>,
+    Omit<VariantProps<typeof fieldWrapperStyles>, 'mode' | 'variant'> {
+  mode?: FieldMode
+  /**
+   * Visual chrome(2026-05-05 Phase B3)。對齊 FieldContext.variant 透傳。
+   * - `'default'`(預設)— Field wrapper 完整 chrome(form / Field 內嵌)。
+   * - `'bare'` — 透明 variant,hover/focus 才現 border(Toolbar inline edit / DataTable cell-as-input)。
+   *
+   * mode='display' 時 chrome 無視覺意義(display 完全無 wrapper);chrome 僅作用於 edit / readonly / disabled。
+   */
+  variant?: FieldVariant
+  error?: boolean
+  value?: string | null
+  onChange?: (value: string) => void
+  placeholder?: string
+  className?: string
+  disabled?: boolean
+  /** 自訂顯示文字（非編輯時） */
+  label?: string
+  /**
+   * Display 是否包 Field naked wrapper(D-path opt-in,2026-05-08)
+   * — DataTable cell display↔edit 像素級對齊用。預設 false(裸 anchor,backward compat)。
+   * 設 true 時 display 走 fieldWrapperStyles(naked variant)包覆 anchor,
+   * 與 cell edit (`<Input naked>`) 同 DOM 結構,消除 Layer-B padding mismatch。
+   * **本元件 edit 無 endIcon(UrlCell 用 plain Input edit)→ display 也無 ItemSuffix**(僅 wrapper)。
+   */
+  showDisplayEndIcon?: boolean
+}
+
+// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
+const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
+  (
+    {
+      mode: modeProp,
+      variant: variantProp,
+      error: errorProp = false,
+      size: sizeProp = 'md',
+      value,
+      onChange,
+      placeholder = 'https://',
+      className,
+      disabled: disabledProp,
+      label,
+      showDisplayEndIcon = false,
+      id: idProp,
+      'aria-describedby': ariaDescribedByProp,
+      'aria-errormessage': ariaErrorMessageProp,
+      ...props
+    },
+    ref
+  ) => {
+    const fieldCtx = useFieldContext()
+    const size = sizeProp ?? fieldCtx?.size ?? 'md'
+    const disabled = disabledProp ?? fieldCtx?.disabled
+    // mode resolution:disabled prop 一律覆蓋;否則 prop > context.mode > default 'edit'
+    const mode: FieldMode = modeProp ?? fieldCtx?.mode ?? 'edit'
+    const resolvedMode: FieldMode = disabled ? 'disabled' : mode
+    const isEditable = resolvedMode === 'edit'
+    // chrome resolution:per-prop > context > 'default'
+    const resolvedVariant: FieldVariant = variantProp ?? fieldCtx?.variant ?? 'default'
+
+    // ── mode='display' ─────────────────────────────────────────────────────
+    // 純展示:無 input chrome / 無 hover affordance / 無 Pencil edit 入口。
+    // 取代既有 LinkInputDisplay sub-component(2026-05-05 Phase B3 retire)。
+    // Default(showDisplayEndIcon=false):無 wrapper 裸 anchor — backward compat。
+    // Opt-in(showDisplayEndIcon=true,2026-05-08 D-path):Field naked wrapper 包覆 anchor,
+    // 與 cell edit (`<Input naked>`) 同 DOM 結構消除像素偏移(無 ItemSuffix,因 edit 也無 endIcon)。
+    if (resolvedMode === 'display') {
+      if (!showDisplayEndIcon) {
+        // 2026-05-14 I2 fix(spec contract (e) display typography canonical):非 D-path bare
+        // anchor / span 必套 `fieldDisplayTextClass(size)`(sm/md→text-body,lg→text-body-lg)
+        // — 對齊跨 Field family display 視覺尺寸統一。原無 font-size class → 用 browser default
+        // 字體 → 跟其他 Field display 不一致(user 抓 I2)。truncate 同需,長 URL ellipsis(I1)。
+        if (!value) return <span className={cn(fieldDisplayTextClass(size), 'text-fg-muted block truncate')}>{EMPTY_DISPLAY}</span>
+        return <span className={cn(fieldDisplayTextClass(size), 'block truncate')}>{renderLinkAnchor(value, label)}</span>
+      }
+      return (
+        <div
+          className={cn(fieldWrapperStyles({ mode: 'display', variant: resolvedVariant, size }), className)}
+          data-field-mode="display"
+        >
+          <span className="flex-1 min-w-0 truncate">
+            {value
+              ? renderLinkAnchor(value, label)
+              : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+            }
+          </span>
+        </div>
+      )
+    }
+
+    const [editing, setEditing] = React.useState(false)
+    const [localValue, setLocalValue] = React.useState(value ?? '')
+    const [localError, setLocalError] = React.useState(false)
+    const inputRef = React.useRef<HTMLInputElement | null>(null)
+
+    // Sync external value → local
+    React.useEffect(() => {
+      if (!editing) setLocalValue(value ?? '')
+    }, [value, editing])
+
+    // Merge refs
+    const setRef = React.useCallback((el: HTMLInputElement | null) => {
+      inputRef.current = el
+      if (typeof ref === 'function') ref(el)
+      else if (ref) (ref as React.MutableRefObject<HTMLInputElement | null>).current = el
+    }, [ref])
+
+    const hasValidValue = !!value && isValidUrl(value)
+    const showLink = isEditable && hasValidValue && !editing && !localError
+    const error = errorProp || localError
+
+    // 2026-05-16 audit codex Round 6:capture rAF + cancel on unmount(defensive hygiene)
+    const focusRafIdRef = React.useRef<number>(0)
+    React.useEffect(() => () => { if (focusRafIdRef.current) cancelAnimationFrame(focusRafIdRef.current) }, [])
+
+    const handleEdit = () => {
+      setEditing(true)
+      if (focusRafIdRef.current) cancelAnimationFrame(focusRafIdRef.current)
+      focusRafIdRef.current = requestAnimationFrame(() => {
+        focusRafIdRef.current = 0
+        inputRef.current?.focus()
+      })
+    }
+
+    const handleBlur = () => {
+      setEditing(false)
+      const trimmed = localValue.trim()
+      if (!trimmed) {
+        // Empty is OK — clear value
+        setLocalError(false)
+        onChange?.('')
+        return
+      }
+      if (isValidUrl(trimmed)) {
+        setLocalError(false)
+        onChange?.(trimmed)
+      } else {
+        setLocalError(true)
+      }
+    }
+
+    const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+      setLocalValue(e.target.value)
+      // Clear error on edit (blur validation)
+      if (localError) setLocalError(false)
+    }
+
+    const handleKeyDown = (e: React.KeyboardEvent) => {
+      if (e.key === 'Enter') inputRef.current?.blur()
+      if (e.key === 'Escape') {
+        setLocalValue(value ?? '')
+        setLocalError(false)
+        setEditing(false)
+      }
+    }
+
+    // readonly — 顯示藍色連結（可點擊）
+    // disabled — 顯示純文字 fg-disabled（不可點擊）
+    if (!isEditable) {
+      const displayText = value ? (label || formatHostname(value)) : null
+      return (
+        <div
+          className={cn(fieldWrapperStyles({ mode: resolvedMode, variant: resolvedVariant, size }), className)}
+          data-field-mode={resolvedMode}
+        >
+          <span className="flex-1 min-w-0 truncate">
+            {resolvedMode === 'disabled'
+              ? (displayText
+                  ? <span className="text-fg-disabled">{displayText}</span>
+                  : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>)
+              : (value
+                  ? renderLinkAnchor(value, label)
+                  : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>)
+            }
+          </span>
+        </div>
+      )
+    }
+
+    // edit — link display mode（有合法 URL 且未在編輯中）
+    if (showLink) {
+      return (
+        <div
+          className={cn(fieldWrapperStyles({ mode: 'edit', variant: resolvedVariant, size }), className)}
+          data-field-mode="edit"
+        >
+          <span className="flex-1 min-w-0">
+            {value && renderLinkAnchor(value, label)}
+          </span>
+          <ItemInlineAction
+            size={size ?? 'md'}
+            action={{ icon: Pencil, label: '編輯連結', onClick: handleEdit }} // i18n-allow: DS default inline-action label
+          />
+        </div>
+      )
+    }
+
+    // edit — text input mode（正在編輯、無值、或格式錯誤）
+    return (
+      <div
+        className={cn(
+          fieldWrapperStyles({ mode: 'edit', variant: resolvedVariant, size }),
+          error && [
+            'border-error hover:border-error-hover',
+            'focus-within:border-error focus-within:hover:border-error',
+          ],
+          className,
+        )}
+        data-field-mode="edit"
+        data-error={error ? '' : undefined}
+      >
+        <input
+          ref={setRef}
+          type="url"
+          id={idProp ?? fieldCtx?.id}
+          value={localValue}
+          onChange={handleChange}
+          onBlur={handleBlur}
+          onKeyDown={handleKeyDown}
+          placeholder={placeholder}
+          aria-invalid={(error || fieldCtx?.invalid) || undefined}
+          aria-required={fieldCtx?.required || undefined}
+          aria-describedby={ariaDescribedByProp ?? fieldCtx?.descriptionId}
+          aria-errormessage={ariaErrorMessageProp ?? ((error || fieldCtx?.invalid) ? fieldCtx?.errorId : undefined)}
+          className={bareInputStyles}
+          {...props}
+        />
+      </div>
+    )
+  }
+)
+LinkInput.displayName = 'LinkInput'
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const linkInputMeta = {
+  component: 'LinkInput',
+  family: 4,
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: [],
+    fg: ['text-fg-disabled', 'text-fg-muted', 'text-primary'],
+    ring: [],
+  },
+} as const
+
+export { LinkInput }

package/src/components/Menu/menu-item.tsx

@@ -0,0 +1,334 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import * as React from 'react'
+import { cva, type VariantProps } from 'class-variance-authority'
+import type { LucideIcon } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+import { Avatar, type AvatarData } from '@/design-system/components/Avatar/avatar'
+// Row primitive 共用常數——統一從 item-layout pattern module 引入
+import { ICON_SIZE, AVATAR_SIZE, ItemContent, itemPrefixAlignVariants, ROW_PADDING_BY_SIZE } from '@/design-system/patterns/element-anatomy/item-anatomy'
+
+/**
+ * MenuItem — 所有 menu 類元件的共用視覺佈局層
+ *
+ * SelectMenu、DropdownMenu、未來的 ContextMenu 等都消費這個元件。
+ * 它只負責 layout（padding、gap、prefix alignment、typography），
+ * 互動行為由各 menu 的 Radix primitive 外層控制。
+ *
+ * ── 結構 ──
+ *   [checkbox?]  [startIcon? | avatar?]  [label + description?]
+ *
+ * ── Prefix 對齊規則（24px 閾值）──
+ *   prefix ≤ 24px  → h-[1lh]，對齊第一行 label
+ *   prefix > 24px  → h-[calc(1lh+var(--item-gap-label-desc)+desc_1lh)]，對齊文字區塊
+ *   無 description → prefix 上限 24px
+ *
+ * ── Size ──
+ *   sm / md / lg — 單行高度對齊 field-height token
+ */
+
+const CHECKBOX_SIZE: Record<string, 'sm' | 'md' | 'lg'> = { sm: 'sm', md: 'md', lg: 'lg' }
+
+// ── Item variants ──
+const menuItemVariants = cva(
+  [
+    'flex items-start gap-2 px-3 w-full',
+    'cursor-pointer select-none',
+    'transition-colors duration-150',
+    'outline-none',
+    'focus-visible:bg-neutral-hover',
+  ],
+  {
+    variants: {
+      // 消費 ROW_PADDING_BY_SIZE SSOT(item-anatomy.tsx 導出)
+      // 改一處 → 全 row primitive 自動同步(消除前 SidebarMenuButton 獨立實作 risk)
+      size: ROW_PADDING_BY_SIZE,
+    },
+    defaultVariants: {
+      size: 'md',
+    },
+  }
+)
+
+// ── Prefix alignment container ──
+// 消費 `itemPrefixAlignVariants`(SSOT from patterns/element-anatomy/item-anatomy.tsx)
+// 原本 MenuItem 自管 cva 造成 drift 風險(block formula 改動需同步);改為共用 SSOT
+// 讓公式只有一份,改 item-anatomy 一處 → MenuItem 自動同步。
+
+// ── Component ──
+
+export interface MenuItemProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>,
+    VariantProps<typeof menuItemVariants> {
+  /** Label 文字 */
+  children: React.ReactNode
+  /** 次要說明文字，顯示在 label 下方 */
+  description?: React.ReactNode
+  /** 左側 icon（LucideIcon），與 avatar 互斥 */
+  startIcon?: LucideIcon
+  /** 左側頭像資料（AvatarData），元件內部渲染 Avatar。與 startIcon 互斥 */
+  avatar?: AvatarData
+  /** 顯示 checkbox（多選模式由父層控制） */
+  checkbox?: boolean
+  /** Checkbox 選中狀態 */
+  checked?: boolean | 'indeterminate'
+  /** 單選選中（bg-neutral-selected 背景高亮，持續選中狀態） */
+  selected?: boolean
+  /** 後綴 Tag（ReactNode），靠右對齊 */
+  tag?: React.ReactNode
+  /** 後綴自訂內容（ReactNode），用於 DropdownMenu 的 badge/endIcon/shortcut 等 */
+  endContent?: React.ReactNode
+  /** 停用 */
+  disabled?: boolean
+  /** 作為群組標題（不可選，font-medium，fg-muted） */
+  header?: boolean
+  /**
+   * Label 最大行數(line-clamp 截斷,超過顯示 ellipsis)。
+   *
+   * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `1`(單行截斷,符合選單快速掃視需求)
+   * - 數字 → 截斷到該行數
+   * - `'none'` → **明確**不截斷,自然 wrap 任意行數
+   *
+   * 為什麼用 `'none'` 而不是 `undefined` 表達不截斷?React props 的 destructure default
+   * 在 `undefined` 時會接管,所以 `<MenuItem labelMaxLines={undefined}>` 等同沒傳,
+   * 會 fallback 到預設 `1`。要明確覆寫成「不截斷」,必須用一個非 undefined 的 sentinel。
+   */
+  labelMaxLines?: number | 'none'
+  /**
+   * Description 最大行數。
+   *
+   * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `1`(跟 label 對稱,維持掃視節奏)
+   * - 數字 → 截斷到該行數
+   * - `'none'` → 明確不截斷
+   *
+   * 為什麼預設 1?Menu 的設計目的是「快速掃視多個選項挑一個」,垂直空間是
+   * 寶貴的——一個過高的 item 會破壞 row rhythm,讓使用者眼睛重新校準。description
+   * 跟 label 對稱地截到 1 行,確保所有 item 高度一致(無 desc / 有 desc 兩種高度)。
+   * Consumer 若有合理理由要 2 行 description,可顯式 override。
+   */
+  descMaxLines?: number | 'none'
+}
+
+/** 把 maxLines 轉成 line-clamp class;'none' / 0 → 空字串 */
+function lineClampClass(maxLines: number | 'none'): string {
+  if (maxLines === 'none' || !maxLines) return ''
+  if (maxLines === 1) return 'line-clamp-1'
+  if (maxLines === 2) return 'line-clamp-2'
+  if (maxLines === 3) return 'line-clamp-3'
+  if (maxLines === 4) return 'line-clamp-4'
+  if (maxLines === 5) return 'line-clamp-5'
+  if (maxLines === 6) return 'line-clamp-6'
+  return ''
+}
+
+// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
+const MenuItem = React.forwardRef<HTMLDivElement, MenuItemProps>(
+  (
+    {
+      children,
+      description,
+      startIcon: StartIcon,
+      avatar,
+      checkbox,
+      checked,
+      selected,
+      tag,
+      endContent,
+      disabled,
+      header,
+      size,
+      labelMaxLines = 1,
+      descMaxLines = 1,
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    const sizeKey = size ?? 'md'
+    const labelClampClass = lineClampClass(labelMaxLines)
+    const descClampClass = lineClampClass(descMaxLines)
+    const iconPx = ICON_SIZE[sizeKey]
+
+    // ── 決定 avatar 容器尺寸 + 對齊模式 ──
+    // 有 description → 使用 block 尺寸（32/40px），block 對齊
+    // 無 description → 使用 inline 尺寸（20/24px），inline 對齊
+    const avatarPx = avatar
+      ? (description ? AVATAR_SIZE.block[sizeKey] : AVATAR_SIZE.inline[sizeKey])
+      : 0
+    const isBlockAlign = avatarPx > 24 && !!description
+
+    const prefixAlign = isBlockAlign
+      ? (`block-${sizeKey}` as const)
+      : 'inline'
+
+    const hasPrefix = !!StartIcon || !!avatar || checkbox
+
+    // ── Header variant ──
+    if (header) {
+      return (
+        <div
+          ref={ref}
+          className={cn(
+            menuItemVariants({ size }),
+            'font-medium text-fg-muted cursor-default pointer-events-none',
+            className,
+          )}
+          role="presentation"
+          {...props}
+        >
+          {children}
+        </div>
+      )
+    }
+
+    return (
+      <div
+        ref={ref}
+        role="option"
+        aria-selected={selected || (checked === true) || undefined}
+        aria-disabled={disabled || undefined}
+        data-selected={selected ? '' : undefined}
+        data-disabled={disabled ? '' : undefined}
+        className={cn(
+          menuItemVariants({ size }),
+          !disabled && !selected && 'hover:bg-neutral-hover',
+          !disabled && selected && 'bg-neutral-selected',
+          // disabled 用 cursor-not-allowed(對齊 Button + Material/Polaris/Atlassian);
+          // pointer-events-none 會讓 cursor 失效,改用 aria-disabled + onClick guard
+          disabled && 'text-fg-disabled cursor-not-allowed',
+          className,
+        )}
+        onClick={disabled ? undefined : props.onClick}
+        onKeyDown={disabled ? undefined : props.onKeyDown}
+        {...Object.fromEntries(Object.entries(props).filter(([k]) => k !== 'onClick' && k !== 'onKeyDown'))}
+      >
+        {/* Prefix 對齊容器 */}
+        {hasPrefix && (
+          <div className={cn(itemPrefixAlignVariants({ align: prefixAlign }))}>
+            {checkbox && (
+              <Checkbox
+                size={CHECKBOX_SIZE[sizeKey]}
+                checked={checked === true ? true : checked === 'indeterminate' ? 'indeterminate' : false}
+                disabled={disabled}
+                tabIndex={-1}
+                className="pointer-events-none"
+              />
+            )}
+            {StartIcon && (
+              <StartIcon
+                data-prefix-type="icon"
+                size={iconPx}
+                className={cn('shrink-0', disabled && 'text-fg-disabled')}
+                aria-hidden
+              />
+            )}
+            {avatar && (
+              <Avatar
+                data-prefix-type="avatar"
+                src={avatar.src}
+                alt={avatar.alt}
+                color={avatar.color}
+                hoverCard={avatar.hoverCard}
+                size={avatarPx}
+              />
+            )}
+          </div>
+        )}
+
+        {/* Content — 消費 ItemContent primitive(SSOT)。
+            scanning mode 跟隨 size:sm/md = caption,lg = body(desc 比 label lg 16 小 1 tier)。
+            labelClampClass / descClampClass 透過 className escape hatch 傳入(MenuItem 特化 labelMaxLines / descMaxLines 語意)。 */}
+        <ItemContent
+          label={children}
+          description={description}
+          mode="scanning"
+          size={sizeKey === 'lg' ? 'lg' : 'md'}
+          descriptionTone={disabled ? 'disabled' : 'secondary'}
+          labelTruncate={false}
+          labelClassName={cn(labelClampClass || 'break-words', disabled && 'text-fg-disabled')}
+          descriptionClassName={cn(descClampClass || 'break-words')}
+        />
+
+        {(tag || endContent) && (
+          <div className={cn(
+            'flex items-center gap-2 shrink-0 h-[1lh] ml-auto',
+            disabled && 'opacity-disabled',
+          )}>
+            {tag}
+            {endContent}
+          </div>
+        )}
+      </div>
+    )
+  }
+)
+MenuItem.displayName = 'MenuItem'
+
+// ── Group ──
+// MenuGroup — Menu-like group primitive(跨元件設計語言統一,SSOT 見
+// `patterns/element-anatomy/item-anatomy.spec.md`「Group auto-separation」)
+//
+// 設計語言:每個 group 上下 8px + 相鄰 group 間 border-divider + 視覺 gap 16px
+//
+// 本元件用 Pattern A:`py-2 [&+&]:border-t [&+&]:border-divider`
+// (適用外層容器無 py-2 的情境,例 Command.List——Group 自帶邊界 padding)
+//
+// **視覺必須跟 DropdownMenuGroup 等價**(見 dropdown-menu.tsx Pattern B 對照)。
+// 改動前先讀 item-anatomy.spec.md「Group auto-separation」確認視覺不漂移。
+
+export interface MenuGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode
+}
+
+const MenuGroup = React.forwardRef<HTMLDivElement, MenuGroupProps>(
+  ({ children, className, ...props }, ref) => (
+    <div
+      ref={ref}
+      role="group"
+      className={cn('py-2 [&+&]:border-t [&+&]:border-divider', className)}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+)
+MenuGroup.displayName = 'MenuGroup'
+
+// ── Footer ──
+
+export interface MenuFooterProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode
+}
+
+const MenuFooter = React.forwardRef<HTMLDivElement, MenuFooterProps>(
+  ({ children, className, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn('py-2 border-t border-divider', className)}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+)
+MenuFooter.displayName = 'MenuFooter'
+
+// Story auto-compile metadata — Phase 1+2 migration
+export const menuItemMeta = {
+  component: 'MenuItem',
+  family: 1,
+  variants: {},
+  sizes: {
+    sm: {},
+    md: {},
+    lg: {},
+  },
+  defaultSize: 'md',
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-neutral-hover', 'bg-neutral-selected'],
+    fg: ['text-fg-muted', 'text-fg-disabled'],
+  },
+} as const
+
+export { MenuItem, MenuGroup, MenuFooter, menuItemVariants }