@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

package/dist/components/SelectionControl/selection-item.js.map

@@ -1 +1 @@
-{"version":3,"file":"selection-item.js","sources":["../../../src/components/SelectionControl/selection-item.tsx"],"sourcesContent":["/**\n * @internal — DS-internal 單元(per `packages/design-system/ds-canonical/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。\n * 不進 root barrel front-door;由 Checkbox / RadioGroup wrap 消費,end-user app 請用 wrapper 元件。\n */\nimport * as React from 'react'\nimport { cva, type VariantProps } from 'class-variance-authority'\nimport type { LucideIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Avatar, type AvatarData } from '@/design-system/components/Avatar/avatar'\nimport { ICON_SIZE, AVATAR_SIZE } from '@/design-system/patterns/element-anatomy/item-anatomy'\n\n// ── Selection Item Styles ───────────────────────────────────────────────────\n// Checkbox 和 RadioGroup 共用的 item 佈局。\n//\n// 結構(item-anatomy.spec.md 4-slot 模型):\n//   [control] [optional prefix(icon|avatar)] [content(label/desc)](3-slot,見 spec「定位」)\n//\n// padding 公式：py = (field-height - 1lh) / 2\n//   - 單行時 item 高度 = field-height（對齊同 size 的 Input）\n//   - 多行時 padding 不變（文字間距一致）\n//   - density 切換時 field-height 自動調整，padding 跟著算\n//\n// 容器設 text-body / text-body-lg 建立 1lh context（div 上正常繼承）。\n//\n// ── 為什麼 NOT 消費 ROW_PADDING_BY_SIZE(item-anatomy.tsx SSOT,2026-04-24 consolidation)──\n// menu / sidebar / tree 3 cva 統一消費 ROW_PADDING_BY_SIZE;SelectionItem 刻意不消費,\n// 因 typography 不同(mode 差異,非 drift):\n//   - ROW_PADDING_BY_SIZE:`text-body leading-compact`(scanning mode,緊湊)\n//   - SelectionItem:`text-body`(**無 leading-compact** — reading mode,Checkbox/Radio 搭配\n//     較長 label + description,需預設 1.5 leading 而非 1.3 compact)\n// py 公式本身相同 — 若 field-height token 變動,本檔需手動同步(contained,由本註解 anchor 追)。\n\n// code-quality-allow: dead-export — public API surface — consumer-exposed for future use\nexport const selectionItemStyles = cva(\n  'flex items-start gap-2',\n  {\n    variants: {\n      size: {\n        sm: 'text-body py-[calc((var(--field-height-sm)_-_1lh)_/_2)]',\n        md: 'text-body py-[calc((var(--field-height-md)_-_1lh)_/_2)]',\n        lg: 'text-body-lg py-[calc((var(--field-height-lg)_-_1lh)_/_2)]',\n      },\n    },\n    defaultVariants: {\n      size: 'md',\n    },\n  }\n)\n\ntype SizeKey = 'sm' | 'md' | 'lg'\n\n// Avatar 尺寸 + Icon 尺寸從 item-layout module 共用,不在此 re-declare(避免漂移)\n// AVATAR_SIZE / ICON_SIZE 都是 item-layout 的 canonical 常數。\n//\n// SelectionItem 跟 MenuItem 的差異:SelectionItem 有 control(checkbox/radio)。\n// block 模式時 **control 跟 prefix 一起走 block 高度**——兩者都在 text block center,\n// 維持「selection + identity」是一組的視覺語意,不會歪斜。\nconst AVATAR_PX = AVATAR_SIZE\n\n// ── Block 對齊容器 ──\n// sm/md: reading mode (body 14/1.5 + body 14/1.5) — gap token `reading`\n// lg:    reading-lg mode (body-lg 16/1.5 + body 14/1.5) — gap token `reading-lg`\n// desc 永遠 body(14) line-height;`1lh` 會 resolve 到 label 的 line-height(sm/md=21, lg=24)\nconst blockAlignClass: Record<SizeKey, string> = {\n  sm: 'h-[calc(1lh+var(--item-gap-label-desc-reading)+var(--font-body-size)*1.5)]',\n  md: 'h-[calc(1lh+var(--item-gap-label-desc-reading)+var(--font-body-size)*1.5)]',\n  lg: 'h-[calc(1lh+var(--item-gap-label-desc-reading-lg)+var(--font-body-size)*1.5)]',\n}\n\n// ── Selection Item ──────────────────────────────────────────────────────────\n// 通用 item 行：control + 可選 prefix(icon/avatar) + label + description。\n// control 永遠包在 h-[1lh] 容器內,對齊第一行 label。\n// prefix 走 24px 閾值規則,各自獨立對齊。\n\nexport interface SelectionItemProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof selectionItemStyles> {\n  /** Checkbox 或 RadioGroupItem 元素(永遠存在,永遠 inline 對齊) */\n  control: React.ReactNode\n  /** Label 文字 */\n  label: React.ReactNode\n  /** 描述文字(fg-secondary;reading mode 永遠 14px) */\n  description?: React.ReactNode\n  /**\n   * 可選的左側 icon(在 control 之後、label 之前)。LucideIcon 型別,元件內部控制尺寸\n   * (16/16/20px @ sm/md/lg)。**永遠 inline 對齊第一行 label**(icon ≤24px)。\n   * 與 `avatar` 互斥。\n   */\n  icon?: LucideIcon\n  /**\n   * 可選的左側 avatar(在 control 之後、label 之前)。`AvatarData` 資料型別,元件內部渲染 Avatar。\n   * 尺寸由 `description` 自動決定(跟 MenuItem 同 convention):\n   * - 無 desc → inline(20/24/24px),跟 control 同步在 label 第一行\n   * - 有 desc → block(32/32/40px),跟 control 同步在 text block center\n   *\n   * Block 模式時 **control(checkbox/radio)也一起走 block 高度**——兩者都在\n   * text block center,不會歪斜。與 `icon` 互斥。\n   */\n  avatar?: AvatarData\n  /** htmlFor（label 指向 control 的 id） */\n  htmlFor?: string\n  /** disabled 狀態影響 label 顏色 */\n  disabled?: boolean\n  /**\n   * Label 最大行數(line-clamp 截斷)。\n   *\n   * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `'none'`(form 欄位允許任意長度)\n   * - 數字 → 截斷到該行數\n   * - `'none'` → 明確不截斷(語意等同預設)\n   *\n   * 為什麼用 `'none'` 而不是 `undefined`?React props 的 destructure default 在\n   * `undefined` 時會接管,要明確覆寫必須用非 undefined 的 sentinel。\n   */\n  labelMaxLines?: number | 'none'\n  /**\n   * Description 最大行數。預設 `'none'`(不截)。\n   */\n  descMaxLines?: number | 'none'\n  className?: string\n}\n\n/** 把 maxLines 轉成 line-clamp class;'none' / 0 → 空字串 */\nfunction lineClampClass(maxLines: number | 'none'): string {\n  if (maxLines === 'none' || !maxLines) return ''\n  if (maxLines === 1) return 'line-clamp-1'\n  if (maxLines === 2) return 'line-clamp-2'\n  if (maxLines === 3) return 'line-clamp-3'\n  if (maxLines === 4) return 'line-clamp-4'\n  if (maxLines === 5) return 'line-clamp-5'\n  if (maxLines === 6) return 'line-clamp-6'\n  return ''\n}\n\n// ── PrefixSlot — 24px 閾值規則 ──\n// icon(永遠 ≤24px)→ inline;avatar + 無 desc → inline;avatar + 有 desc → block(centered on text block)\ntype PrefixSlotProps = {\n  icon: LucideIcon | undefined\n  avatar: AvatarData | undefined\n  sizeKey: SizeKey\n  alignClass: string\n  avatarPx: number\n  disabled: boolean | undefined\n}\nfunction PrefixSlot({ icon: Icon, avatar, sizeKey, alignClass, avatarPx, disabled }: PrefixSlotProps) {\n  if (!Icon && !avatar) return null\n  return (\n    <div className={cn(alignClass, 'flex items-center shrink-0')}>\n      {Icon && (\n        <Icon\n          size={ICON_SIZE[sizeKey]}\n          className={cn('shrink-0', disabled && 'text-fg-disabled')}\n          aria-hidden\n        />\n      )}\n      {!Icon && avatar && (\n        <Avatar src={avatar.src} alt={avatar.alt} color={avatar.color} hoverCard={avatar.hoverCard} size={avatarPx} />\n      )}\n    </div>\n  )\n}\n\n// ── ContentSlot — label + optional description ──\n// inline-style fontSize 繞 tailwind-merge 把 text-body / text-fg-secondary 誤判同組衝突的 bug\ntype ContentSlotProps = {\n  htmlFor: string | undefined\n  disabled: boolean | undefined\n  label: React.ReactNode\n  description: React.ReactNode | undefined\n  sizeKey: SizeKey\n  labelClampClass: string\n  descClampClass: string\n}\nfunction ContentSlot({ htmlFor, disabled, label, description, sizeKey, labelClampClass, descClampClass }: ContentSlotProps) {\n  return (\n    <div className=\"min-w-0 flex-1\">\n      <label\n        htmlFor={htmlFor}\n        // 2026-06-10 a11y:styled-disabled label 明告 inactive(WCAG 1.4.3 豁免可機判;對齊 FieldLabel 同修;a11y 補強不動 SSOT = AUTO 分權,user verbatim「確保所有的任務你都有做到完美做到完整」)\n        aria-disabled={disabled || undefined}\n        className={cn(\n          'cursor-pointer block break-words',\n          labelClampClass,\n          disabled ? 'text-fg-disabled cursor-not-allowed' : 'text-foreground',\n        )}\n      >\n        {label}\n      </label>\n      {description && (\n        <p\n          className={cn(\n            sizeKey === 'lg' ? 'mt-[var(--item-gap-label-desc-reading-lg)]' : 'mt-[var(--item-gap-label-desc-reading)]',\n            'break-words',\n            descClampClass,\n            disabled ? 'text-fg-disabled' : 'text-fg-secondary',\n          )}\n          style={{ fontSize: 'var(--font-body-size)' }}\n        >\n          {description}\n        </p>\n      )}\n    </div>\n  )\n}\n\nconst SelectionItem = React.forwardRef<HTMLDivElement, SelectionItemProps>(\n  (\n    {\n      control,\n      label,\n      description,\n      icon: Icon,\n      avatar,\n      htmlFor,\n      disabled,\n      size,\n      labelMaxLines = 'none',\n      descMaxLines = 'none',\n      className,\n      ...props\n    },\n    ref\n  ) => {\n    const sizeKey: SizeKey = size ?? 'md'\n    if (process.env.NODE_ENV !== 'production' && Icon && avatar) {\n      // eslint-disable-next-line no-console\n      console.warn('[SelectionItem] `icon` 和 `avatar` 互斥,只會渲染 icon。')\n    }\n    // Block 對齊:control 跟 prefix(avatar)一起走 block 高度,「selection + identity」視覺單元不歪斜\n    const useBlock = !!avatar && !Icon && !!description && AVATAR_PX.block[sizeKey] > 24\n    const avatarPx = useBlock ? AVATAR_PX.block[sizeKey] : AVATAR_PX.inline[sizeKey]\n    const alignClass = useBlock ? blockAlignClass[sizeKey] : 'h-[1lh]'\n\n    return (\n      <div ref={ref} className={cn(selectionItemStyles({ size }), className)} {...props}>\n        <div className={cn(alignClass, 'flex items-center shrink-0')}>{control}</div>\n        <PrefixSlot icon={Icon} avatar={avatar} sizeKey={sizeKey} alignClass={alignClass} avatarPx={avatarPx} disabled={disabled} />\n        <ContentSlot\n          htmlFor={htmlFor}\n          disabled={disabled}\n          label={label}\n          description={description}\n          sizeKey={sizeKey}\n          labelClampClass={lineClampClass(labelMaxLines)}\n          descClampClass={lineClampClass(descMaxLines)}\n        />\n      </div>\n    )\n  }\n)\nSelectionItem.displayName = 'SelectionItem'\n\n// Story auto-compile metadata — Phase 1+2 migration\nexport const selectionItemMeta = {\n  component: 'SelectionItem',\n  family: 2,\n  variants: {},\n  sizes: {\n    sm: {},\n    md: {},\n    lg: {},\n  },\n  defaultSize: 'md',\n  states: ['default', 'disabled'], // disabled 是唯一視覺狀態;selected / hover 屬傳入的 control(spec「為何無 ColorMatrix / StateBehavior」)\n  tokens: {\n    fg: ['text-foreground', 'text-fg-secondary', 'text-fg-disabled'],\n  },\n} as const\n\nexport { SelectionItem }\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"selection-item.js","sources":["../../../src/components/SelectionControl/selection-item.tsx"],"sourcesContent":["/**\n * @internal — DS-internal 單元(per `packages/design-system/ds-canonical/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。\n * 不進 root barrel front-door;由 Checkbox / RadioGroup wrap 消費,end-user app 請用 wrapper 元件。\n */\nimport * as React from 'react'\nimport { cva, type VariantProps } from 'class-variance-authority'\nimport type { LucideIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Avatar, type AvatarData } from '@/design-system/components/Avatar/avatar'\nimport { ICON_SIZE, AVATAR_SIZE } from '@/design-system/patterns/element-anatomy/item-anatomy'\n\n// ── Selection Item Styles ───────────────────────────────────────────────────\n// Checkbox 和 RadioGroup 共用的 item 佈局。\n//\n// 結構(item-anatomy.spec.md 4-slot 模型):\n//   [control] [optional prefix(icon|avatar)] [content(label/desc)](3-slot,見 spec「定位」)\n//\n// padding 公式：py = (field-height - 1lh) / 2\n//   - 單行時 item 高度 = field-height（對齊同 size 的 Input）\n//   - 多行時 padding 不變（文字間距一致）\n//   - density 切換時 field-height 自動調整，padding 跟著算\n//\n// 容器設 text-body / text-body-lg 建立 1lh context（div 上正常繼承）。\n//\n// ── 為什麼 NOT 消費 ROW_PADDING_BY_SIZE(item-anatomy.tsx SSOT,2026-04-24 consolidation)──\n// menu / sidebar / tree 3 cva 統一消費 ROW_PADDING_BY_SIZE;SelectionItem 刻意不消費,\n// 因 typography 不同(mode 差異,非 drift):\n//   - ROW_PADDING_BY_SIZE:`text-body leading-compact`(scanning mode,緊湊)\n//   - SelectionItem:`text-body`(**無 leading-compact** — reading mode,Checkbox/Radio 搭配\n//     較長 label + description,需預設 1.5 leading 而非 1.3 compact)\n// py 公式本身相同 — 若 field-height token 變動,本檔需手動同步(contained,由本註解 anchor 追)。\n\n// code-quality-allow: dead-export — public API surface — consumer-exposed for future use\nexport const selectionItemStyles = cva(\n  'flex items-start gap-2',\n  {\n    variants: {\n      size: {\n        sm: 'text-body py-[calc((var(--field-height-sm)_-_1lh)_/_2)]',\n        md: 'text-body py-[calc((var(--field-height-md)_-_1lh)_/_2)]',\n        lg: 'text-body-lg py-[calc((var(--field-height-lg)_-_1lh)_/_2)]',\n      },\n    },\n    defaultVariants: {\n      size: 'md',\n    },\n  }\n)\n\ntype SizeKey = 'sm' | 'md' | 'lg'\n\n// Avatar 尺寸 + Icon 尺寸從 item-layout module 共用,不在此 re-declare(避免漂移)\n// AVATAR_SIZE / ICON_SIZE 都是 item-layout 的 canonical 常數。\n//\n// SelectionItem 跟 MenuItem 的差異:SelectionItem 有 control(checkbox/radio)。\n// block 模式時 **control 跟 prefix 一起走 block 高度**——兩者都在 text block center,\n// 維持「selection + identity」是一組的視覺語意,不會歪斜。\nconst AVATAR_PX = AVATAR_SIZE\n\n// ── Block 對齊容器 ──\n// sm/md: reading mode (body 14/1.5 + body 14/1.5) — gap token `reading`\n// lg:    reading-lg mode (body-lg 16/1.5 + body 14/1.5) — gap token `reading-lg`\n// desc 永遠 body(14) line-height;`1lh` 會 resolve 到 label 的 line-height(sm/md=21, lg=24)\nconst blockAlignClass: Record<SizeKey, string> = {\n  sm: 'h-[calc(1lh+var(--item-gap-label-desc-reading)+var(--font-body-size)*1.5)]',\n  md: 'h-[calc(1lh+var(--item-gap-label-desc-reading)+var(--font-body-size)*1.5)]',\n  lg: 'h-[calc(1lh+var(--item-gap-label-desc-reading-lg)+var(--font-body-size)*1.5)]',\n}\n\n// ── Selection Item ──────────────────────────────────────────────────────────\n// 通用 item 行：control + 可選 prefix(icon/avatar) + label + description。\n// control 永遠包在 h-[1lh] 容器內,對齊第一行 label。\n// prefix 走 24px 閾值規則,各自獨立對齊。\n\nexport interface SelectionItemProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof selectionItemStyles> {\n  /** Checkbox 或 RadioGroupItem 元素(永遠存在,永遠 inline 對齊) */\n  control: React.ReactNode\n  /** Label 文字 */\n  label: React.ReactNode\n  /** 描述文字(fg-secondary;reading mode 永遠 14px) */\n  description?: React.ReactNode\n  /**\n   * 可選的左側 icon(在 control 之後、label 之前)。LucideIcon 型別,元件內部控制尺寸\n   * (16/16/20px @ sm/md/lg)。**永遠 inline 對齊第一行 label**(icon ≤24px)。\n   * 與 `avatar` 互斥。\n   */\n  icon?: LucideIcon\n  /**\n   * 可選的左側 avatar(在 control 之後、label 之前)。`AvatarData` 資料型別,元件內部渲染 Avatar。\n   * 尺寸由 `description` 自動決定(跟 MenuItem 同 convention):\n   * - 無 desc → inline(20/24/24px),跟 control 同步在 label 第一行\n   * - 有 desc → block(32/32/40px),跟 control 同步在 text block center\n   *\n   * Block 模式時 **control(checkbox/radio)也一起走 block 高度**——兩者都在\n   * text block center,不會歪斜。與 `icon` 互斥。\n   */\n  avatar?: AvatarData\n  /** htmlFor（label 指向 control 的 id） */\n  htmlFor?: string\n  /** disabled 狀態影響 label 顏色 */\n  disabled?: boolean\n  /**\n   * Label 最大行數(line-clamp 截斷)。\n   *\n   * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `'none'`(form 欄位允許任意長度)\n   * - 數字 → 截斷到該行數\n   * - `'none'` → 明確不截斷(語意等同預設)\n   *\n   * 為什麼用 `'none'` 而不是 `undefined`?React props 的 destructure default 在\n   * `undefined` 時會接管,要明確覆寫必須用非 undefined 的 sentinel。\n   */\n  labelMaxLines?: number | 'none'\n  /**\n   * Description 最大行數。預設 `'none'`(不截)。\n   */\n  descMaxLines?: number | 'none'\n  className?: string\n}\n\n/** 把 maxLines 轉成 line-clamp class;'none' / 0 → 空字串 */\nfunction lineClampClass(maxLines: number | 'none'): string {\n  if (maxLines === 'none' || !maxLines) return ''\n  if (maxLines === 1) return 'line-clamp-1'\n  if (maxLines === 2) return 'line-clamp-2'\n  if (maxLines === 3) return 'line-clamp-3'\n  if (maxLines === 4) return 'line-clamp-4'\n  if (maxLines === 5) return 'line-clamp-5'\n  if (maxLines === 6) return 'line-clamp-6'\n  return ''\n}\n\n// ── PrefixSlot — 24px 閾值規則 ──\n// icon(永遠 ≤24px)→ inline;avatar + 無 desc → inline;avatar + 有 desc → block(centered on text block)\ntype PrefixSlotProps = {\n  icon: LucideIcon | undefined\n  avatar: AvatarData | undefined\n  sizeKey: SizeKey\n  alignClass: string\n  avatarPx: number\n  disabled: boolean | undefined\n}\nfunction PrefixSlot({ icon: Icon, avatar, sizeKey, alignClass, avatarPx, disabled }: PrefixSlotProps) {\n  if (!Icon && !avatar) return null\n  return (\n    <div className={cn(alignClass, 'flex items-center shrink-0')}>\n      {Icon && (\n        <Icon\n          size={ICON_SIZE[sizeKey]}\n          className={cn('shrink-0', disabled && 'text-fg-disabled')}\n          aria-hidden\n        />\n      )}\n      {!Icon && avatar && (\n        <Avatar src={avatar.src} alt={avatar.alt} color={avatar.color} hoverCard={avatar.hoverCard} size={avatarPx} />\n      )}\n    </div>\n  )\n}\n\n// ── ContentSlot — label + optional description ──\n// inline-style fontSize 繞 tailwind-merge 把 text-body / text-fg-secondary 誤判同組衝突的 bug\ntype ContentSlotProps = {\n  htmlFor: string | undefined\n  disabled: boolean | undefined\n  label: React.ReactNode\n  description: React.ReactNode | undefined\n  sizeKey: SizeKey\n  labelClampClass: string\n  descClampClass: string\n}\nfunction ContentSlot({ htmlFor, disabled, label, description, sizeKey, labelClampClass, descClampClass }: ContentSlotProps) {\n  return (\n    <div className=\"min-w-0 flex-1\">\n      <label\n        htmlFor={htmlFor}\n        // 2026-06-10 a11y:styled-disabled label 明告 inactive(WCAG 1.4.3 豁免可機判;對齊 FieldLabel 同修;a11y 補強不動 SSOT = AUTO 分權,user verbatim「確保所有的任務你都有做到完美做到完整」)\n        aria-disabled={disabled || undefined}\n        className={cn(\n          'cursor-pointer block break-words',\n          labelClampClass,\n          disabled ? 'text-fg-disabled cursor-not-allowed' : 'text-foreground',\n        )}\n      >\n        {label}\n      </label>\n      {description && (\n        <p\n          // 2026-09-29 a11y(待辦總帳 OE21):與上方 label 同一條理由 —— 說明文字跟著降成 fg-disabled 時也要明告 inactive,\n          // 否則 axe color-contrast 把它當一般文字誤報(RadioGroup 狀態行為 / SelectionControl 前綴圖示兩則 story)\n          aria-disabled={disabled || undefined}\n          className={cn(\n            sizeKey === 'lg' ? 'mt-[var(--item-gap-label-desc-reading-lg)]' : 'mt-[var(--item-gap-label-desc-reading)]',\n            'break-words',\n            descClampClass,\n            disabled ? 'text-fg-disabled' : 'text-fg-secondary',\n          )}\n          style={{ fontSize: 'var(--font-body-size)' }}\n        >\n          {description}\n        </p>\n      )}\n    </div>\n  )\n}\n\nconst SelectionItem = React.forwardRef<HTMLDivElement, SelectionItemProps>(\n  (\n    {\n      control,\n      label,\n      description,\n      icon: Icon,\n      avatar,\n      htmlFor,\n      disabled,\n      size,\n      labelMaxLines = 'none',\n      descMaxLines = 'none',\n      className,\n      ...props\n    },\n    ref\n  ) => {\n    const sizeKey: SizeKey = size ?? 'md'\n    if (process.env.NODE_ENV !== 'production' && Icon && avatar) {\n      console.warn('[SelectionItem] `icon` 和 `avatar` 互斥,只會渲染 icon。')\n    }\n    // Block 對齊:control 跟 prefix(avatar)一起走 block 高度,「selection + identity」視覺單元不歪斜\n    const useBlock = !!avatar && !Icon && !!description && AVATAR_PX.block[sizeKey] > 24\n    const avatarPx = useBlock ? AVATAR_PX.block[sizeKey] : AVATAR_PX.inline[sizeKey]\n    const alignClass = useBlock ? blockAlignClass[sizeKey] : 'h-[1lh]'\n\n    return (\n      <div ref={ref} className={cn(selectionItemStyles({ size }), className)} {...props}>\n        <div className={cn(alignClass, 'flex items-center shrink-0')}>{control}</div>\n        <PrefixSlot icon={Icon} avatar={avatar} sizeKey={sizeKey} alignClass={alignClass} avatarPx={avatarPx} disabled={disabled} />\n        <ContentSlot\n          htmlFor={htmlFor}\n          disabled={disabled}\n          label={label}\n          description={description}\n          sizeKey={sizeKey}\n          labelClampClass={lineClampClass(labelMaxLines)}\n          descClampClass={lineClampClass(descMaxLines)}\n        />\n      </div>\n    )\n  }\n)\nSelectionItem.displayName = 'SelectionItem'\n\n// Story auto-compile metadata — Phase 1+2 migration\nexport const selectionItemMeta = {\n  component: 'SelectionItem',\n  family: 2,\n  variants: {},\n  sizes: {\n    sm: {},\n    md: {},\n    lg: {},\n  },\n  defaultSize: 'md',\n  states: ['default', 'disabled'], // disabled 是唯一視覺狀態;selected / hover 屬傳入的 control(spec「為何無 ColorMatrix / StateBehavior」)\n  tokens: {\n    fg: ['text-foreground', 'text-fg-secondary', 'text-fg-disabled'],\n  },\n} as const\n\nexport { SelectionItem }\n"],"names":[],"mappings":"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"}

package/dist/components/Sidebar/sidebar.d.ts

@@ -2,7 +2,7 @@ import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 import type { LucideIcon } from "lucide-react";
 import { TooltipContent } from "../../components/Tooltip/tooltip";
-import { type RowSize, type InlineActionConfig } from "../../patterns/element-anatomy/item-anatomy";
+import { type ItemInlineActionButtonProps, type RowSize, type InlineActionConfig } from "../../patterns/element-anatomy/item-anatomy";
 type SidebarSize = RowSize;
 type SidebarContextProps = {
     state: "expanded" | "collapsed";
@@ -106,9 +106,7 @@ declare const SidebarGroupLabel: React.ForwardRefExoticComponent<Omit<React.Clas
 } & VariantProps<(props?: ({
     size?: RowSize | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string>, "ref"> & React.RefAttributes<HTMLDivElement>>;
-declare const SidebarGroupAction: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLButtonElement> & React.ButtonHTMLAttributes<HTMLButtonElement> & {
-    asChild?: boolean;
-}, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+declare const SidebarGroupAction: React.ForwardRefExoticComponent<Omit<ItemInlineActionButtonProps, "size"> & React.RefAttributes<HTMLButtonElement>>;
 declare const SidebarMenu: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLUListElement>, HTMLUListElement>, "ref"> & React.RefAttributes<HTMLUListElement>>;
 declare const SidebarMenuItem: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.LiHTMLAttributes<HTMLLIElement>, HTMLLIElement>, "ref"> & React.RefAttributes<HTMLLIElement>>;
 declare const SidebarMenuButton: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "id"> & {
@@ -147,17 +145,17 @@ declare const SidebarMenuButton: React.ForwardRefExoticComponent<Omit<Omit<React
     /**
      * Inline actions 的顯示模式:
      * - `false`(預設):永遠顯示
-     * - `"hover"`:row hover 時才淡入(TreeView 模式)
+     * - `"hover"`:滑過這一列、或鍵盤焦點在這一列時才出現,瞬間出現、不淡入(TreeView 模式;
+     *   待辦總帳 L9,sidebar.spec.md「Inline actions」出現時機列)
      */
     actionsReveal?: false | "hover";
 } & VariantProps<(props?: ({
     size?: "sm" | "md" | "lg" | null | undefined;
     variant?: "meta" | "default" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string>, "ref"> & React.RefAttributes<HTMLButtonElement>>;
-declare const SidebarMenuAction: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLButtonElement> & React.ButtonHTMLAttributes<HTMLButtonElement> & {
-    asChild?: boolean;
+declare const SidebarMenuAction: React.ForwardRefExoticComponent<Omit<ItemInlineActionButtonProps, "size"> & {
     showOnHover?: boolean;
-}, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+} & React.RefAttributes<HTMLButtonElement>>;
 declare const SidebarMenuBadge: React.ForwardRefExoticComponent<(Omit<import("../../components/Badge/badge").BadgeDotProps & React.RefAttributes<HTMLSpanElement>, "ref"> | Omit<import("../../components/Badge/badge").BadgeCountProps & React.RefAttributes<HTMLSpanElement>, "ref">) & React.RefAttributes<HTMLSpanElement>>;
 declare const SidebarMenuSkeleton: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLDivElement> & React.HTMLAttributes<HTMLDivElement> & {
     showIcon?: boolean;
@@ -193,7 +191,7 @@ export declare const sidebarMeta: {
     readonly tokens: {
         readonly bg: readonly ["bg-neutral-hover", "bg-neutral-selected", "bg-surface", "bg-transparent"];
         readonly fg: readonly ["text-fg-muted", "text-fg-secondary", "text-foreground"];
-        readonly ring: readonly ["ring-ring"];
+        readonly ring: readonly ["focus-ring-inset"];
     };
     readonly defaultSize: "md";
 };

package/dist/components/Sidebar/sidebar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidebar.d.ts","sourceRoot":"","sources":["../../../src/components/Sidebar/sidebar.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"sidebar.d.ts","sourceRoot":"","sources":["../../../src/components/Sidebar/sidebar.tsx"],"names":[],"mappings":"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"}

package/dist/components/Sidebar/sidebar.js

@@ -15,7 +15,8 @@ import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetDescription } from "
 import { Skeleton } from "../Skeleton/skeleton.js";
 import { ChromeHeader } from "../../patterns/header-canonical/chrome-header.js";
 import { Tooltip, TooltipTrigger, TooltipContent } from "../Tooltip/tooltip.js";
-import { ItemInlineActionButton, ICON_SIZE, ItemInlineAction, getUniformPrefixSlotStyle, AVATAR_SIZE, RowSizeProvider, ROW_PADDING_BY_SIZE, ItemIcon, ItemLabel } from "../../patterns/element-anatomy/item-anatomy.js";
+import { ItemInlineActionButton, ICON_SIZE, ItemSuffix, ItemInlineAction, getUniformPrefixSlotStyle, AVATAR_SIZE, RowSizeProvider, ROW_PADDING_BY_SIZE, ItemIcon, ItemLabel } from "../../patterns/element-anatomy/item-anatomy.js";
+import { pickRovingTabStop, setRovingTabIndex, removeRovingControlsFromTabOrder, isRovingControlReachable, resolveRovingKey, isTextEntryElement, applyRovingAction } from "../../lib/roving-list-keyboard.js";
 const SIDEBAR_COOKIE_NAME = "sidebar_state";
 const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
 const SIDEBAR_KEYBOARD_SHORTCUT = "b";
@@ -383,7 +384,7 @@ const SidebarContent = React.forwardRef(({ className, children, ...props }, ref)
         className
       ),
       ...props,
-      children: /* @__PURE__ */ jsx(ScrollArea, { className: "flex-1", children: /* @__PURE__ */ jsx("div", { className: "flex flex-col", children }) })
+      children: /* @__PURE__ */ jsx(ScrollArea, { className: "flex-1", viewportTabIndex: -1, children: /* @__PURE__ */ jsx("div", { className: "flex flex-col", children }) })
     }
   );
 });
@@ -511,33 +512,132 @@ const SidebarGroupLabel = React.forwardRef(({ className, asChild = false, size:
   );
 });
 SidebarGroupLabel.displayName = "SidebarGroupLabel";
-const SidebarGroupAction = React.forwardRef(({ className, asChild = false, ...props }, ref) => {
-  const Comp = asChild ? Slot : "button";
+const SidebarGroupAction = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+  ItemInlineActionButton,
+  {
+    ref,
+    "data-sidebar": "group-action",
+    className: cn(
+      "absolute right-[var(--layout-space-loose)] top-2",
+      "group-data-[collapsible=icon]:hidden",
+      className
+    ),
+    ...props
+  }
+));
+SidebarGroupAction.displayName = "SidebarGroupAction";
+const SIDEBAR_MENU_BUTTON = '[data-sidebar="menu-button"]';
+const SIDEBAR_ROW_ACTIONS = '[data-sidebar="menu-inline-actions"] :is(button, a[href], [role="button"]), [data-sidebar="menu-action"]';
+function getSidebarMenuRows(menu) {
+  const rows = [];
+  for (const child of Array.from(menu.children)) {
+    if (child.tagName !== "LI") continue;
+    const button = child.querySelector(SIDEBAR_MENU_BUTTON);
+    if (!button) continue;
+    rows.push({ button, actions: Array.from(child.querySelectorAll(SIDEBAR_ROW_ACTIONS)) });
+  }
+  return rows;
+}
+const isFocusableSidebarTarget = (el) => !el.disabled;
+const isRenderedSidebarTarget = (el) => el.getClientRects().length > 0;
+function sidebarRowNavigability(menu, rows) {
+  const checkRendered = isRenderedSidebarTarget(menu) && rows.some((row) => isFocusableSidebarTarget(row.button) && isRenderedSidebarTarget(row.button));
+  return (button) => isFocusableSidebarTarget(button) && (!checkRendered || isRenderedSidebarTarget(button));
+}
+function syncSidebarMenuTabStops(menu, remembered) {
+  const rows = getSidebarMenuRows(menu);
+  const stop = pickRovingTabStop(rows.map((row) => row.button), {
+    remembered,
+    isCurrent: (button) => button.getAttribute("aria-current") === "page",
+    isNavigable: sidebarRowNavigability(menu, rows)
+  });
+  for (const row of rows) {
+    setRovingTabIndex(row.button, row.button === stop ? 0 : -1);
+    removeRovingControlsFromTabOrder(row.actions);
+  }
+}
+const SidebarMenu = React.forwardRef(({ className, onKeyDownCapture, onFocus, ...props }, ref) => {
+  const menuRef = React.useRef(null);
+  const rememberedRef = React.useRef(null);
+  const sidebarContext = React.useContext(SidebarContext);
+  const sidebarState = sidebarContext == null ? void 0 : sidebarContext.state;
+  const sidebarIsMobile = sidebarContext == null ? void 0 : sidebarContext.isMobile;
+  const setRefs = React.useCallback(
+    (el) => {
+      menuRef.current = el;
+      if (typeof ref === "function") ref(el);
+      else if (ref) ref.current = el;
+    },
+    [ref]
+  );
+  React.useLayoutEffect(() => {
+    if (menuRef.current) syncSidebarMenuTabStops(menuRef.current, rememberedRef.current);
+  }, [sidebarState, sidebarIsMobile]);
+  React.useEffect(() => {
+    const menu = menuRef.current;
+    if (!menu || typeof MutationObserver === "undefined") return;
+    const observer = new MutationObserver(() => syncSidebarMenuTabStops(menu, rememberedRef.current));
+    observer.observe(menu, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["disabled", "aria-current"]
+    });
+    return () => observer.disconnect();
+  }, []);
+  const handleFocus = (event) => {
+    onFocus == null ? void 0 : onFocus(event);
+    const menu = event.currentTarget;
+    const target = event.target;
+    const row = getSidebarMenuRows(menu).find(
+      (r) => r.button === target || r.actions.includes(target)
+    );
+    if (!row) return;
+    rememberedRef.current = row.button;
+    syncSidebarMenuTabStops(menu, row.button);
+  };
+  const handleKeyDownCapture = (event) => {
+    onKeyDownCapture == null ? void 0 : onKeyDownCapture(event);
+    const menu = event.currentTarget;
+    const target = event.target;
+    const rows = getSidebarMenuRows(menu);
+    const row = rows.find((r) => r.button === target || r.actions.includes(target));
+    if (!row) return;
+    const onRow = row.button === target;
+    const controls = row.actions.filter(isRovingControlReachable);
+    const action = resolveRovingKey({
+      key: event.key,
+      focus: onRow ? "item" : "control",
+      controlCount: controls.length,
+      controlIndex: onRow ? -1 : controls.indexOf(target),
+      controlIsTextEntry: !onRow && isTextEntryElement(target),
+      defaultPrevented: event.defaultPrevented,
+      metaKey: event.metaKey,
+      ctrlKey: event.ctrlKey,
+      altKey: event.altKey,
+      shiftKey: event.shiftKey
+    });
+    const isNavigable = sidebarRowNavigability(menu, rows);
+    applyRovingAction(action, {
+      event,
+      item: row.button,
+      controls,
+      items: rows.map((r) => r.button),
+      isNavigable
+    });
+  };
   return /* @__PURE__ */ jsx(
-    Comp,
+    "ul",
     {
-      ref,
-      "data-sidebar": "group-action",
-      className: cn(
-        "absolute right-[var(--layout-space-loose)] top-2 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-fg-muted hover:bg-neutral-hover hover:text-fg-secondary [&>svg]:size-4 [&>svg]:shrink-0",
-        "after:absolute after:-inset-2 after:md:hidden",
-        "group-data-[collapsible=icon]:hidden",
-        className
-      ),
+      ref: setRefs,
+      "data-sidebar": "menu",
+      className: cn("flex w-full min-w-0 flex-col", className),
+      onFocus: handleFocus,
+      onKeyDownCapture: handleKeyDownCapture,
       ...props
     }
   );
 });
-SidebarGroupAction.displayName = "SidebarGroupAction";
-const SidebarMenu = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
-  "ul",
-  {
-    ref,
-    "data-sidebar": "menu",
-    className: cn("flex w-full min-w-0 flex-col", className),
-    ...props
-  }
-));
 SidebarMenu.displayName = "SidebarMenu";
 const SidebarMenuItem = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
   "li",
@@ -575,13 +675,28 @@ const sidebarMenuButtonVariants = cva(
     //   對齊 MUI MiniDrawer + shadcn canonical(width morph + overflow clip + row geometry 不變)。
     // hover 底色瞬間切換,不做過渡(user 2026-09-10 拍板「第三題改成全部瞬間」;SSOT = tokens/motion/motion.spec.md「hover 回饋不做過渡」)
     "hover:bg-neutral-hover hover:text-foreground",
+    // 巢狀 hover(2026-09-25,user 選「卡片保留、按鈕再亮一層」;SSOT = sidebar.spec.md「Inline actions」段「指標在動作鈕上時(巢狀 hover)」):
+    // 指標移到同一列的動作鈕(inlineActions 的 suffix span / SidebarMenuAction)上,列保留上一行的 hover,動作鈕再亮自己那層。
+    // 需要這兩行是因為動作鈕是列鈕的**同層兄弟**(避免 button 包 button,見下方 suffixNode 註解)—— 指標在兄弟上時列鈕不算 :hover。
+    // - `~` 只往後找:動作必須排在列鈕後面(兩個內建出口都是;SidebarMenuAction 的 peer-data 也早就要求這個順序)。
+    // - 外層包 `:where()` 把特異性壓回 (0,1,0),下方 `data-[active=true]` 選中色 (0,2,0) 照樣釘住;不包會是 (0,3,0),選中列指到動作鈕時選中色被 hover 色蓋掉(2026-09-25 Chromium 實測)。
+    // - 不掛在 li 的 `group-hover/menu-item`:li 收任意子元素,指到 li 裡的子項目時父列會誤亮(同日實測)。
+    // - `[@media(hover:hover)]` 對齊上一行 `hover:` 的媒體條件(Tailwind 4 的 hover: 只在能懸停的裝置生效),觸控裝置不留殘亮。
+    // 值與上一行 `hover:` 是同一對;改那一行必須同步改這兩行。
+    "[@media(hover:hover)]:[&:where(:has(~:is([data-sidebar=menu-inline-actions],[data-sidebar=menu-action]):hover))]:bg-neutral-hover",
+    "[@media(hover:hover)]:[&:where(:has(~:is([data-sidebar=menu-inline-actions],[data-sidebar=menu-action]):hover))]:text-foreground",
     // 鍵盤游標一律畫框、不上底色(focus-canonical 規則二,user 2026-09-09 拍板);選單鈕撐滿側欄寬度 → 內描邊。
     // 2026-09-09 之前非當前項的焦點用 hover 同色底(AI 推導,user 撤回);hover 的底色與文字色只屬於滑鼠。
     "focus-visible:focus-ring-inset",
     // 2026-05-31 M24:SidebarMenuButton 主要為 icon+label(currentColor 可改寫)→ 用 semantic
     // text-fg-disabled 對齊 MenuItem primitive(menu-item.tsx:198/221/248 + item-anatomy.tsx:374),
     // 非 opacity-disabled(opacity 保留給圖片/avatar/Switch 等無法改寫內部色者,per color.spec.md:103/118/701)。
-    "disabled:pointer-events-none disabled:text-fg-disabled",
+    // 原生 disabled 的 button 本來就不會發 click,不再 pointer-events-none:留著接指標只為了掛禁止符號
+    //(hit-area-canonical.md 滑過原則一-3「停用的用禁止符號」;2026-09-29 全站掃出:「混合內容」的「delta（已封存）」游標是箭頭,
+    // 因為 pointer-events-none 讓 cursor 由 li 決定)。上方 hover 的底色 / 字色由 disabled:hover 釘住(:disabled:hover 特異性高過 :hover)。
+    "disabled:text-fg-disabled disabled:cursor-not-allowed disabled:hover:bg-transparent disabled:hover:text-fg-disabled",
+    // aria-disabled(asChild 的 <a> 等非 button 宿主)仍靠 pointer-events-none 擋掉點擊 / 導覽 —— 那是它唯一的擋法;
+    // 代價是游標由外層決定(箭頭)。要拿掉這裡的 pointer-events-none,得先在 asChild 宿主補 click guard(另案)。
     "aria-disabled:pointer-events-none aria-disabled:text-fg-disabled",
     "data-[active=true]:bg-neutral-selected data-[active=true]:text-foreground",
     // 2026-08-11 user 拍板(SSOT = item-anatomy「選中 × 互動疊加」):滑鼠 hover 當前項釘住不變
@@ -689,6 +804,7 @@ const SidebarMenuButton = React.forwardRef(
         ref,
         "data-sidebar": "menu-button",
         "data-active": isActive,
+        "aria-current": isActive ? "page" : void 0,
         className: cn(sidebarMenuButtonVariants({ size, variant }), className),
         style: hasActions ? { paddingRight: buttonPaddingRight } : void 0,
         onClick: handleClick,
@@ -697,19 +813,22 @@ const SidebarMenuButton = React.forwardRef(
       }
     );
     const suffixNode = hasActions ? /* @__PURE__ */ jsx(
-      "span",
+      ItemSuffix,
       {
         "data-sidebar": "menu-inline-actions",
+        hoverReveal: actionsReveal === "hover",
+        hoverGroup: "menu-item",
         className: cn(
-          "absolute top-1/2 -translate-y-1/2 flex items-center gap-2",
+          "absolute top-1/2 -translate-y-1/2",
           "right-[var(--layout-space-loose)]",
           // Icon 模式隱藏(跟 SidebarMenuBadge / SidebarMenuAction 一致)
           "group-data-[collapsible=icon]:hidden",
-          // hover-reveal:滑鼠 hover 或鍵盤 focus(但不是 mouse click 的 focus)時顯示。
-          // 用 `:has(:focus-visible)` 而非 `:focus-within`——focus-within 會被
-          // mouse click 觸發,導致 click 之後 actions 永久顯示直到焦點移走;
-          // focus-visible 只在鍵盤 tab 時啟動,mouse click 不會觸發,符合使用者直覺。
-          actionsReveal === "hover" && "opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100 transition-opacity duration-150 motion-reduce:duration-0"
+          // 兩顆動作鈕之間的空隙歸列(2026-09-26,待辦總帳 N53 ①,user:「這些看起來幾乎都是bug」;修法 = R20「讓亮著的地方點得到」):
+          // 空隙在滑過時讓列亮著(sidebar.spec.md「Inline actions」段「兩顆動作鈕之間的空隙也算在內」),
+          // 點下去卻落在這個容器、列不導覽 —— 看得到亮卻點不到(hit-area-canonical.md「看到亮起來卻點不到」)。
+          // 容器本身不接指標,只有裡面可以按的東西接;空隙、以及插槽裡不能按的裝飾都穿到底下的列鈕(列鈕 paddingRight 已讓出這一段)。
+          // 指到按鈕上時容器仍是 :hover 的祖先,列的巢狀滑過(上方 cva 的 `~` 選擇器)照舊。
+          "pointer-events-none [&_:is(button,a[href],[role=button],[tabindex])]:pointer-events-auto"
         ),
         children: hasSlot ? inlineActionsSlot : inlineActions.map((action, i) => /* @__PURE__ */ jsx(ItemInlineAction, { action }, action.label + i))
       }
@@ -737,24 +856,26 @@ const SidebarMenuButton = React.forwardRef(
   }
 );
 SidebarMenuButton.displayName = "SidebarMenuButton";
-const SidebarMenuAction = React.forwardRef(({ className, asChild = false, showOnHover = false, ...props }, ref) => {
-  const Comp = asChild ? Slot : "button";
-  return /* @__PURE__ */ jsx(
-    Comp,
-    {
-      ref,
-      "data-sidebar": "menu-action",
-      className: cn(
-        "absolute right-[var(--layout-space-loose)] top-1/2 -translate-y-1/2 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-fg-muted hover:bg-neutral-hover hover:text-fg-secondary [&>svg]:size-4 [&>svg]:shrink-0",
-        "after:absolute after:-inset-2 after:md:hidden",
-        "group-data-[collapsible=icon]:hidden",
-        showOnHover && "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[state=open]:opacity-100 peer-data-[active=true]/menu-button:text-foreground md:opacity-0",
-        className
-      ),
-      ...props
-    }
-  );
-});
+const SidebarMenuAction = React.forwardRef(({ className, showOnHover = false, ...props }, ref) => /* @__PURE__ */ jsx(
+  ItemInlineActionButton,
+  {
+    ref,
+    "data-sidebar": "menu-action",
+    className: cn(
+      "absolute right-[var(--layout-space-loose)] top-1/2 -translate-y-1/2",
+      "group-data-[collapsible=icon]:hidden",
+      showOnHover && "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[state=open]:opacity-100 peer-data-[active=true]/menu-button:text-foreground md:opacity-0",
+      // 當前項旁的動作鈕:靜止已是 foreground(上一行),滑過 / 按下**釘住 foreground**,不讓 ItemInlineActionButton 的
+      // `hover:/active:text-fg-secondary` (0,2,0) 把它降回一階(2026-09-25 合成情境量測:淺 #252525→#545454、深 #FFFFFF→#E1E1E1;目前 DS 內無 showOnHover 消費者)。
+      // 依據:inline-action.spec.md「Icon 色彩」的階梯 root invariant `fg-muted → fg-secondary → foreground`,滑過只准往前一階;
+      // 這顆的靜止已站在最高一階 foreground,沒有下一階可升就留在原地,不得往回掉 ——
+      // 同列鈕「選中 × 滑過釘住」的寫法(上方 cva 的 `data-[active=true]:hover:…`)。特異性 (0,3,0) > hover:/active: 的 (0,2,0)。
+      showOnHover && "peer-data-[active=true]/menu-button:hover:text-foreground peer-data-[active=true]/menu-button:active:text-foreground",
+      className
+    ),
+    ...props
+  }
+));
 SidebarMenuAction.displayName = "SidebarMenuAction";
 const SidebarMenuBadge = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
   Badge,
@@ -844,7 +965,7 @@ const sidebarMeta = {
   tokens: {
     bg: ["bg-neutral-hover", "bg-neutral-selected", "bg-surface", "bg-transparent"],
     fg: ["text-fg-muted", "text-fg-secondary", "text-foreground"],
-    ring: ["ring-ring"]
+    ring: ["focus-ring-inset"]
   },
   defaultSize: "md"
 };