@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.130

package/dist/components/Menu/menu-item.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @internal — DS-internal 單元(per `packages/design-system/ds-canonical/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 DropdownMenu / SelectMenu 等 menu 類 DS 元件 wrap 消費,end-user app 請用 wrapper 元件。
+ */
 import * as React from 'react';
 import { type VariantProps } from 'class-variance-authority';
 import type { LucideIcon } from 'lucide-react';
@@ -10,10 +14,22 @@ export interface MenuItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     children: React.ReactNode;
     /** 次要說明文字，顯示在 label 下方 */
     description?: React.ReactNode;
-    /** 左側 icon（LucideIcon），與 avatar 互斥 */
+    /** 左側 icon（LucideIcon），與 avatar / startContent 互斥 */
     startIcon?: LucideIcon;
-    /** 左側頭像資料（AvatarData），元件內部渲染 Avatar。與 startIcon 互斥 */
+    /** startIcon 的 className 透傳(2026-07-08 WM 戰役:status 類彩色 icon 需求;disabled 色仍勝出) */
+    startIconClassName?: string;
+    /** 左側頭像資料（AvatarData），元件內部渲染 Avatar。與 startIcon / startContent 互斥 */
     avatar?: AvatarData;
+    /**
+     * 左側自訂內容（ReactNode），與 startIcon / avatar 互斥。與 `endContent` 對稱。
+     *
+     * **佔位與排列邏輯跟 startIcon 一模一樣**(2026-07-10 WM TypeIcon 彩色徽章需求):
+     * 渲染在同一個 prefix 對齊容器(`itemPrefixAlignVariants` SSOT)內 —— gap / 對齊 /
+     * shrink 全繼承,零平行 layout 邏輯,不可能與 startIcon 漂移。Consumer 唯一責任
+     * 是節點尺寸對齊 `ICON_SIZE[size]`(sm/md=16px、lg=20px;如 `size-4` 徽章)。
+     * 典型場景:類型徽章(彩底 + glyph)、status 圓點組合等 LucideIcon 表達不了的 leading 視覺。
+     */
+    startContent?: React.ReactNode;
     /** 顯示 checkbox（多選模式由父層控制） */
     checkbox?: boolean;
     /** Checkbox 選中狀態 */
@@ -32,7 +48,7 @@ export interface MenuItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
      * Label 最大行數(line-clamp 截斷,超過顯示 ellipsis)。
      *
      * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `1`(單行截斷,符合選單快速掃視需求)
-     * - 數字 → 截斷到該行數
+     * - 數字(1-6)→ 截斷到該行數;>6 超出 line-clamp utility 支援範圍 → 不截斷(同 'none',見 lineClampClass)
      * - `'none'` → **明確**不截斷,自然 wrap 任意行數
      *
      * 為什麼用 `'none'` 而不是 `undefined` 表達不截斷?React props 的 destructure default
@@ -44,7 +60,7 @@ export interface MenuItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
      * Description 最大行數。
      *
      * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `1`(跟 label 對稱,維持掃視節奏)
-     * - 數字 → 截斷到該行數
+     * - 數字(1-6)→ 截斷到該行數;>6 超出 line-clamp utility 支援範圍 → 不截斷(同 'none',見 lineClampClass)
      * - `'none'` → 明確不截斷
      *
      * 為什麼預設 1?Menu 的設計目的是「快速掃視多個選項挑一個」,垂直空間是

package/dist/components/Menu/menu-item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"menu-item.d.ts","sourceRoot":"","sources":["../../../src/components/Menu/menu-item.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,0CAA0C,CAAA;AA0BlF,QAAA,MAAM,gBAAgB;;8EAkBrB,CAAA;AASD,MAAM,WAAW,aACf,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC,EAC5D,YAAY,CAAC,OAAO,gBAAgB,CAAC;IACvC,eAAe;IACf,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,0BAA0B;IAC1B,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,sCAAsC;IACtC,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,sDAAsD;IACtD,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,oBAAoB;IACpB,OAAO,CAAC,EAAE,OAAO,GAAG,eAAe,CAAA;IACnC,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,6BAA6B;IAC7B,GAAG,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACrB,mEAAmE;IACnE,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC5B,SAAS;IACT,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,uCAAuC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC/B;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAC/B;AAeD,QAAA,MAAM,QAAQ,sFA2Ib,CAAA;AAeD,MAAM,WAAW,cAAe,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAC1E,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAED,QAAA,MAAM,SAAS,uFAWd,CAAA;AAKD,MAAM,WAAW,eAAgB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAC3E,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAED,QAAA,MAAM,UAAU,wFAUf,CAAA;AAID,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAA"}
+{"version":3,"file":"menu-item.d.ts","sourceRoot":"","sources":["../../../src/components/Menu/menu-item.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,0CAA0C,CAAA;AAgClF,QAAA,MAAM,gBAAgB;;8EAkBrB,CAAA;AASD,MAAM,WAAW,aACf,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC,EAC5D,YAAY,CAAC,OAAO,gBAAgB,CAAC;IACvC,eAAe;IACf,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,0BAA0B;IAC1B,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,qDAAqD;IACrD,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,kFAAkF;IAClF,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qEAAqE;IACrE,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC9B,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,oBAAoB;IACpB,OAAO,CAAC,EAAE,OAAO,GAAG,eAAe,CAAA;IACnC,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,6BAA6B;IAC7B,GAAG,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACrB,mEAAmE;IACnE,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC5B,SAAS;IACT,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,uCAAuC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC/B;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAC/B;AAeD,QAAA,MAAM,QAAQ,sFAgLb,CAAA;AAeD,MAAM,WAAW,cAAe,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAC1E,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAED,QAAA,MAAM,SAAS,uFAWd,CAAA;AAKD,MAAM,WAAW,eAAgB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAC3E,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAED,QAAA,MAAM,UAAU,wFAUf,CAAA;AAID,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAA"}

package/dist/components/Menu/menu-item.js

@@ -6,6 +6,7 @@ import { Checkbox } from "../Checkbox/checkbox.js";
 import { Avatar } from "../Avatar/avatar.js";
 import { ICON_SIZE, AVATAR_SIZE, itemPrefixAlignVariants, ItemContent, ROW_PADDING_BY_SIZE } from "../../patterns/element-anatomy/item-anatomy.js";
 const CHECKBOX_SIZE = { sm: "sm", md: "md", lg: "lg" };
+const INERT_SPREAD = Number.parseInt(React.version, 10) >= 19 ? { inert: true } : { inert: "" };
 const menuItemVariants = cva(
   [
     "flex items-start gap-2 px-3 w-full",
@@ -40,7 +41,9 @@ const MenuItem = React.forwardRef(
     children,
     description,
     startIcon: StartIcon,
+    startIconClassName,
     avatar,
+    startContent,
     checkbox,
     checked,
     selected,
@@ -61,7 +64,7 @@ const MenuItem = React.forwardRef(
     const avatarPx = avatar ? description ? AVATAR_SIZE.block[sizeKey] : AVATAR_SIZE.inline[sizeKey] : 0;
     const isBlockAlign = avatarPx > 24 && !!description;
     const prefixAlign = isBlockAlign ? `block-${sizeKey}` : "inline";
-    const hasPrefix = !!StartIcon || !!avatar || checkbox;
+    const hasPrefix = !!StartIcon || !!avatar || !!startContent || checkbox;
     if (header) {
       return /* @__PURE__ */ jsx(
         "div",
@@ -78,36 +81,50 @@ const MenuItem = React.forwardRef(
         }
       );
     }
+    const isPresentation = props.role === "presentation";
     return /* @__PURE__ */ jsxs(
       "div",
       {
         ref,
-        role: "option",
-        "aria-selected": selected || checked === true || void 0,
-        "aria-disabled": disabled || void 0,
+        role: isPresentation ? "presentation" : "option",
+        "aria-selected": isPresentation ? void 0 : selected || checked === true || void 0,
+        "aria-disabled": isPresentation ? void 0 : disabled || void 0,
         "data-selected": selected ? "" : void 0,
         "data-disabled": disabled ? "" : void 0,
         className: cn(
           menuItemVariants({ size }),
           !disabled && !selected && "hover:bg-neutral-hover",
-          !disabled && selected && "bg-neutral-selected",
+          // 2026-08-11(SSOT = item-anatomy「選中 × 互動疊加」):選中列滑鼠 hover 本就不變(上行條件互斥);
+          // 補鍵盤焦點深一階 -focus(twMerge 同組蓋過 base 的 focus-visible:bg-neutral-hover)。
+          !disabled && selected && "bg-neutral-selected focus-visible:bg-neutral-selected-focus",
           // disabled 用 cursor-not-allowed(對齊 Button + Material/Polaris/Atlassian);
           // pointer-events-none 會讓 cursor 失效,改用 aria-disabled + onClick guard
           disabled && "text-fg-disabled cursor-not-allowed",
           className
         ),
+        ...Object.fromEntries(Object.entries(props).filter(([k]) => k !== "onClick" && k !== "onKeyDown")),
         onClick: disabled ? void 0 : props.onClick,
         onKeyDown: disabled ? void 0 : props.onKeyDown,
-        ...Object.fromEntries(Object.entries(props).filter(([k]) => k !== "onClick" && k !== "onKeyDown")),
         children: [
           hasPrefix && /* @__PURE__ */ jsxs("div", { className: cn(itemPrefixAlignVariants({ align: prefixAlign })), children: [
-            checkbox && /* @__PURE__ */ jsx(
+            checkbox && // 2026-07-14 a11y(axe nested-interactive):此 checkbox 是純視覺 indicator —— checked
+            // ARIA state 由外層 row 單一 owner 宣告(Radix menuitemcheckbox / cmdk option /
+            // select-all row role="checkbox",見上方「ARIA 單一 owner gate」)。Radix Checkbox 渲
+            // focusable <button role="checkbox">,巢狀在互動 row 內 = axe nested-interactive
+            // violation;tabIndex=-1 不夠(axe-core no-focusable-content 對 tabindex<0 仍回
+            // violation,僅 messageKey 換 notHidden)。aria-hidden 移出 AT tree(消 SR 內外雙重
+            // checkbox 宣告)+ inert 移除 focusability(axe focusDisabled 認 inert → clean pass)。
+            // inert:React 18/19 傳法不同(18 要空字串、19 要 boolean)→ 消費 module scope
+            // INERT_SPREAD 的 runtime 版本判定,見該處註解。
+            /* @__PURE__ */ jsx(
               Checkbox,
               {
                 size: CHECKBOX_SIZE[sizeKey],
                 checked: checked === true ? true : checked === "indeterminate" ? "indeterminate" : false,
                 disabled,
                 tabIndex: -1,
+                "aria-hidden": true,
+                ...INERT_SPREAD,
                 className: "pointer-events-none"
               }
             ),
@@ -116,7 +133,7 @@ const MenuItem = React.forwardRef(
               {
                 "data-prefix-type": "icon",
                 size: iconPx,
-                className: cn("shrink-0", disabled && "text-fg-disabled"),
+                className: cn("shrink-0", startIconClassName, disabled && "text-fg-disabled"),
                 "aria-hidden": true
               }
             ),
@@ -130,6 +147,16 @@ const MenuItem = React.forwardRef(
                 hoverCard: avatar.hoverCard,
                 size: avatarPx
               }
+            ),
+            startContent && // 自訂 leading 節點:同容器 = 佔位/排列與 startIcon 一模一樣(見 props JSDoc)。
+            // disabled 用 opacity-disabled(對齊本元件 suffix slot 對自訂 ReactNode 的同款處理)。
+            /* @__PURE__ */ jsx(
+              "span",
+              {
+                "data-prefix-type": "content",
+                className: cn("flex shrink-0 items-center", disabled && "opacity-disabled"),
+                children: startContent
+              }
             )
           ] }),
           /* @__PURE__ */ jsx(
@@ -145,7 +172,8 @@ const MenuItem = React.forwardRef(
               descriptionClassName: cn(descClampClass || "break-words")
             }
           ),
-          (tag || endContent) && /* @__PURE__ */ jsxs("div", { className: cn(
+          (tag || endContent) && // @row-slot-handcraft-allow: MenuItem 自身即 row primitive（item-anatomy Family 1 owner），此 tag/endContent 容器是 MenuItem 自有 suffix slot 實作，非外部 consumer hand-craft → 不再 wrap ItemSuffix
+          /* @__PURE__ */ jsxs("div", { className: cn(
             "flex items-center gap-2 shrink-0 h-[1lh] ml-auto",
             disabled && "opacity-disabled"
           ), children: [

package/dist/components/Menu/menu-item.js.map

@@ -1 +1 @@
-{"version":3,"file":"menu-item.js","sources":["../../../src/components/Menu/menu-item.tsx"],"sourcesContent":["// @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.\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 { Checkbox } from '@/design-system/components/Checkbox/checkbox'\nimport { Avatar, type AvatarData } from '@/design-system/components/Avatar/avatar'\n// Row primitive 共用常數——統一從 item-layout pattern module 引入\nimport { ICON_SIZE, AVATAR_SIZE, ItemContent, itemPrefixAlignVariants, ROW_PADDING_BY_SIZE } from '@/design-system/patterns/element-anatomy/item-anatomy'\n\n/**\n * MenuItem — 所有 menu 類元件的共用視覺佈局層\n *\n * SelectMenu、DropdownMenu、未來的 ContextMenu 等都消費這個元件。\n * 它只負責 layout（padding、gap、prefix alignment、typography），\n * 互動行為由各 menu 的 Radix primitive 外層控制。\n *\n * ── 結構 ──\n *   [checkbox?]  [startIcon? | avatar?]  [label + description?]\n *\n * ── Prefix 對齊規則（24px 閾值）──\n *   prefix ≤ 24px  → h-[1lh]，對齊第一行 label\n *   prefix > 24px  → h-[calc(1lh+var(--item-gap-label-desc)+desc_1lh)]，對齊文字區塊\n *   無 description → prefix 上限 24px\n *\n * ── Size ──\n *   sm / md / lg — 單行高度對齊 field-height token\n */\n\nconst CHECKBOX_SIZE: Record<string, 'sm' | 'md' | 'lg'> = { sm: 'sm', md: 'md', lg: 'lg' }\n\n// ── Item variants ──\nconst menuItemVariants = cva(\n  [\n    'flex items-start gap-2 px-3 w-full',\n    'cursor-pointer select-none',\n    'transition-colors duration-150',\n    'outline-none',\n    'focus-visible:bg-neutral-hover',\n  ],\n  {\n    variants: {\n      // 消費 ROW_PADDING_BY_SIZE SSOT(item-anatomy.tsx 導出)\n      // 改一處 → 全 row primitive 自動同步(消除前 SidebarMenuButton 獨立實作 risk)\n      size: ROW_PADDING_BY_SIZE,\n    },\n    defaultVariants: {\n      size: 'md',\n    },\n  }\n)\n\n// ── Prefix alignment container ──\n// 消費 `itemPrefixAlignVariants`(SSOT from patterns/element-anatomy/item-anatomy.tsx)\n// 原本 MenuItem 自管 cva 造成 drift 風險(block formula 改動需同步);改為共用 SSOT\n// 讓公式只有一份,改 item-anatomy 一處 → MenuItem 自動同步。\n\n// ── Component ──\n\nexport interface MenuItemProps\n  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>,\n    VariantProps<typeof menuItemVariants> {\n  /** Label 文字 */\n  children: React.ReactNode\n  /** 次要說明文字，顯示在 label 下方 */\n  description?: React.ReactNode\n  /** 左側 icon（LucideIcon），與 avatar 互斥 */\n  startIcon?: LucideIcon\n  /** 左側頭像資料（AvatarData），元件內部渲染 Avatar。與 startIcon 互斥 */\n  avatar?: AvatarData\n  /** 顯示 checkbox（多選模式由父層控制） */\n  checkbox?: boolean\n  /** Checkbox 選中狀態 */\n  checked?: boolean | 'indeterminate'\n  /** 單選選中（bg-neutral-selected 背景高亮，持續選中狀態） */\n  selected?: boolean\n  /** 後綴 Tag（ReactNode），靠右對齊 */\n  tag?: React.ReactNode\n  /** 後綴自訂內容（ReactNode），用於 DropdownMenu 的 badge/endIcon/shortcut 等 */\n  endContent?: React.ReactNode\n  /** 停用 */\n  disabled?: boolean\n  /** 作為群組標題（不可選，font-medium，fg-muted） */\n  header?: boolean\n  /**\n   * Label 最大行數(line-clamp 截斷,超過顯示 ellipsis)。\n   *\n   * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `1`(單行截斷,符合選單快速掃視需求)\n   * - 數字 → 截斷到該行數\n   * - `'none'` → **明確**不截斷,自然 wrap 任意行數\n   *\n   * 為什麼用 `'none'` 而不是 `undefined` 表達不截斷?React props 的 destructure default\n   * 在 `undefined` 時會接管,所以 `<MenuItem labelMaxLines={undefined}>` 等同沒傳,\n   * 會 fallback 到預設 `1`。要明確覆寫成「不截斷」,必須用一個非 undefined 的 sentinel。\n   */\n  labelMaxLines?: number | 'none'\n  /**\n   * Description 最大行數。\n   *\n   * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `1`(跟 label 對稱,維持掃視節奏)\n   * - 數字 → 截斷到該行數\n   * - `'none'` → 明確不截斷\n   *\n   * 為什麼預設 1?Menu 的設計目的是「快速掃視多個選項挑一個」,垂直空間是\n   * 寶貴的——一個過高的 item 會破壞 row rhythm,讓使用者眼睛重新校準。description\n   * 跟 label 對稱地截到 1 行,確保所有 item 高度一致(無 desc / 有 desc 兩種高度)。\n   * Consumer 若有合理理由要 2 行 description,可顯式 override。\n   */\n  descMaxLines?: number | 'none'\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// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst MenuItem = React.forwardRef<HTMLDivElement, MenuItemProps>(\n  (\n    {\n      children,\n      description,\n      startIcon: StartIcon,\n      avatar,\n      checkbox,\n      checked,\n      selected,\n      tag,\n      endContent,\n      disabled,\n      header,\n      size,\n      labelMaxLines = 1,\n      descMaxLines = 1,\n      className,\n      ...props\n    },\n    ref\n  ) => {\n    const sizeKey = size ?? 'md'\n    const labelClampClass = lineClampClass(labelMaxLines)\n    const descClampClass = lineClampClass(descMaxLines)\n    const iconPx = ICON_SIZE[sizeKey]\n\n    // ── 決定 avatar 容器尺寸 + 對齊模式 ──\n    // 有 description → 使用 block 尺寸（32/40px），block 對齊\n    // 無 description → 使用 inline 尺寸（20/24px），inline 對齊\n    const avatarPx = avatar\n      ? (description ? AVATAR_SIZE.block[sizeKey] : AVATAR_SIZE.inline[sizeKey])\n      : 0\n    const isBlockAlign = avatarPx > 24 && !!description\n\n    const prefixAlign = isBlockAlign\n      ? (`block-${sizeKey}` as const)\n      : 'inline'\n\n    const hasPrefix = !!StartIcon || !!avatar || checkbox\n\n    // ── Header variant ──\n    if (header) {\n      return (\n        <div\n          ref={ref}\n          className={cn(\n            menuItemVariants({ size }),\n            'font-medium text-fg-muted cursor-default pointer-events-none',\n            className,\n          )}\n          role=\"presentation\"\n          {...props}\n        >\n          {children}\n        </div>\n      )\n    }\n\n    return (\n      <div\n        ref={ref}\n        role=\"option\"\n        aria-selected={selected || (checked === true) || undefined}\n        aria-disabled={disabled || undefined}\n        data-selected={selected ? '' : undefined}\n        data-disabled={disabled ? '' : undefined}\n        className={cn(\n          menuItemVariants({ size }),\n          !disabled && !selected && 'hover:bg-neutral-hover',\n          !disabled && selected && 'bg-neutral-selected',\n          // disabled 用 cursor-not-allowed(對齊 Button + Material/Polaris/Atlassian);\n          // pointer-events-none 會讓 cursor 失效,改用 aria-disabled + onClick guard\n          disabled && 'text-fg-disabled cursor-not-allowed',\n          className,\n        )}\n        onClick={disabled ? undefined : props.onClick}\n        onKeyDown={disabled ? undefined : props.onKeyDown}\n        {...Object.fromEntries(Object.entries(props).filter(([k]) => k !== 'onClick' && k !== 'onKeyDown'))}\n      >\n        {/* Prefix 對齊容器 */}\n        {hasPrefix && (\n          <div className={cn(itemPrefixAlignVariants({ align: prefixAlign }))}>\n            {checkbox && (\n              <Checkbox\n                size={CHECKBOX_SIZE[sizeKey]}\n                checked={checked === true ? true : checked === 'indeterminate' ? 'indeterminate' : false}\n                disabled={disabled}\n                tabIndex={-1}\n                className=\"pointer-events-none\"\n              />\n            )}\n            {StartIcon && (\n              <StartIcon\n                data-prefix-type=\"icon\"\n                size={iconPx}\n                className={cn('shrink-0', disabled && 'text-fg-disabled')}\n                aria-hidden\n              />\n            )}\n            {avatar && (\n              <Avatar\n                data-prefix-type=\"avatar\"\n                src={avatar.src}\n                alt={avatar.alt}\n                color={avatar.color}\n                hoverCard={avatar.hoverCard}\n                size={avatarPx}\n              />\n            )}\n          </div>\n        )}\n\n        {/* Content — 消費 ItemContent primitive(SSOT)。\n            scanning mode 跟隨 size:sm/md = caption,lg = body(desc 比 label lg 16 小 1 tier)。\n            labelClampClass / descClampClass 透過 className escape hatch 傳入(MenuItem 特化 labelMaxLines / descMaxLines 語意)。 */}\n        <ItemContent\n          label={children}\n          description={description}\n          mode=\"scanning\"\n          size={sizeKey === 'lg' ? 'lg' : 'md'}\n          descriptionTone={disabled ? 'disabled' : 'secondary'}\n          labelTruncate={false}\n          labelClassName={cn(labelClampClass || 'break-words', disabled && 'text-fg-disabled')}\n          descriptionClassName={cn(descClampClass || 'break-words')}\n        />\n\n        {(tag || endContent) && (\n          <div className={cn(\n            'flex items-center gap-2 shrink-0 h-[1lh] ml-auto',\n            disabled && 'opacity-disabled',\n          )}>\n            {tag}\n            {endContent}\n          </div>\n        )}\n      </div>\n    )\n  }\n)\nMenuItem.displayName = 'MenuItem'\n\n// ── Group ──\n// MenuGroup — Menu-like group primitive(跨元件設計語言統一,SSOT 見\n// `patterns/element-anatomy/item-anatomy.spec.md`「Group auto-separation」)\n//\n// 設計語言:每個 group 上下 8px + 相鄰 group 間 border-divider + 視覺 gap 16px\n//\n// 本元件用 Pattern A:`py-2 [&+&]:border-t [&+&]:border-divider`\n// (適用外層容器無 py-2 的情境,例 Command.List——Group 自帶邊界 padding)\n//\n// **視覺必須跟 DropdownMenuGroup 等價**(見 dropdown-menu.tsx Pattern B 對照)。\n// 改動前先讀 item-anatomy.spec.md「Group auto-separation」確認視覺不漂移。\n\nexport interface MenuGroupProps extends React.HTMLAttributes<HTMLDivElement> {\n  children: React.ReactNode\n}\n\nconst MenuGroup = React.forwardRef<HTMLDivElement, MenuGroupProps>(\n  ({ children, className, ...props }, ref) => (\n    <div\n      ref={ref}\n      role=\"group\"\n      className={cn('py-2 [&+&]:border-t [&+&]:border-divider', className)}\n      {...props}\n    >\n      {children}\n    </div>\n  )\n)\nMenuGroup.displayName = 'MenuGroup'\n\n// ── Footer ──\n\nexport interface MenuFooterProps extends React.HTMLAttributes<HTMLDivElement> {\n  children: React.ReactNode\n}\n\nconst MenuFooter = React.forwardRef<HTMLDivElement, MenuFooterProps>(\n  ({ children, className, ...props }, ref) => (\n    <div\n      ref={ref}\n      className={cn('py-2 border-t border-divider', className)}\n      {...props}\n    >\n      {children}\n    </div>\n  )\n)\nMenuFooter.displayName = 'MenuFooter'\n\n// Story auto-compile metadata — Phase 1+2 migration\nexport const menuItemMeta = {\n  component: 'MenuItem',\n  family: 1,\n  variants: {},\n  sizes: {\n    sm: {},\n    md: {},\n    lg: {},\n  },\n  defaultSize: 'md',\n  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: ['bg-neutral-hover', 'bg-neutral-selected'],\n    fg: ['text-fg-muted', 'text-fg-disabled'],\n  },\n} as const\n\nexport { MenuItem, MenuGroup, MenuFooter, menuItemVariants }\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"menu-item.js","sources":["../../../src/components/Menu/menu-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;由 DropdownMenu / SelectMenu 等 menu 類 DS 元件 wrap 消費,end-user app 請用 wrapper 元件。\n */\n// @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.\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 { Checkbox } from '@/design-system/components/Checkbox/checkbox'\nimport { Avatar, type AvatarData } from '@/design-system/components/Avatar/avatar'\n// Row primitive 共用常數——統一從 item-layout pattern module 引入\nimport { ICON_SIZE, AVATAR_SIZE, ItemContent, itemPrefixAlignVariants, ROW_PADDING_BY_SIZE } from '@/design-system/patterns/element-anatomy/item-anatomy'\n\n/**\n * MenuItem — 所有 menu 類元件的共用視覺佈局層\n *\n * SelectMenu、DropdownMenu、未來的 ContextMenu 等都消費這個元件。\n * 它只負責 layout（padding、gap、prefix alignment、typography），\n * 互動行為由各 menu 的 Radix primitive 外層控制。\n *\n * ── 結構 ──\n *   [checkbox?]  [startIcon? | avatar?]  [label + description?]\n *\n * ── Prefix 對齊規則（24px 閾值）──\n *   prefix ≤ 24px  → h-[1lh]，對齊第一行 label\n *   prefix > 24px  → h-[calc(1lh+var(--item-gap-label-desc-scanning)+desc_1lh)](size-aware -scanning[-lg] 變體)，對齊文字區塊\n *   無 description → prefix 上限 24px\n *\n * ── Size ──\n *   sm / md / lg — 單行高度對齊 field-height token\n */\n\nconst CHECKBOX_SIZE: Record<string, 'sm' | 'md' | 'lg'> = { sm: 'sm', md: 'md', lg: 'lg' }\n\n// inert 傳法依 React 主版本(peer range >=18):React 18 視 inert 為 unknown attr——boolean true\n// 會被丟棄(non-boolean attribute warning,attr 不落 DOM),必須傳空字串;React 19 起 inert 是\n// 內建 boolean prop——空字串反觸發 runtime warning 且視為 false(a11y 靜默失效)。runtime 判定\n// 一次,兩版皆真正落 inert attr(WM patch-package 吸收 2026-07-30;WM React 19 實證空字串失效)。\nconst INERT_SPREAD = (Number.parseInt(React.version, 10) >= 19 ? { inert: true } : { inert: '' }) as object\n\n// ── Item variants ──\nconst menuItemVariants = cva(\n  [\n    'flex items-start gap-2 px-3 w-full',\n    'cursor-pointer select-none',\n    'transition-colors duration-150',\n    'outline-none',\n    'focus-visible:bg-neutral-hover',\n  ],\n  {\n    variants: {\n      // 消費 ROW_PADDING_BY_SIZE SSOT(item-anatomy.tsx 導出)\n      // 改一處 → 全 row primitive 自動同步(消除前 SidebarMenuButton 獨立實作 risk)\n      size: ROW_PADDING_BY_SIZE,\n    },\n    defaultVariants: {\n      size: 'md',\n    },\n  }\n)\n\n// ── Prefix alignment container ──\n// 消費 `itemPrefixAlignVariants`(SSOT from patterns/element-anatomy/item-anatomy.tsx)\n// 原本 MenuItem 自管 cva 造成 drift 風險(block formula 改動需同步);改為共用 SSOT\n// 讓公式只有一份,改 item-anatomy 一處 → MenuItem 自動同步。\n\n// ── Component ──\n\nexport interface MenuItemProps\n  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>,\n    VariantProps<typeof menuItemVariants> {\n  /** Label 文字 */\n  children: React.ReactNode\n  /** 次要說明文字，顯示在 label 下方 */\n  description?: React.ReactNode\n  /** 左側 icon（LucideIcon），與 avatar / startContent 互斥 */\n  startIcon?: LucideIcon\n  /** startIcon 的 className 透傳(2026-07-08 WM 戰役:status 類彩色 icon 需求;disabled 色仍勝出) */\n  startIconClassName?: string\n  /** 左側頭像資料（AvatarData），元件內部渲染 Avatar。與 startIcon / startContent 互斥 */\n  avatar?: AvatarData\n  /**\n   * 左側自訂內容（ReactNode），與 startIcon / avatar 互斥。與 `endContent` 對稱。\n   *\n   * **佔位與排列邏輯跟 startIcon 一模一樣**(2026-07-10 WM TypeIcon 彩色徽章需求):\n   * 渲染在同一個 prefix 對齊容器(`itemPrefixAlignVariants` SSOT)內 —— gap / 對齊 /\n   * shrink 全繼承,零平行 layout 邏輯,不可能與 startIcon 漂移。Consumer 唯一責任\n   * 是節點尺寸對齊 `ICON_SIZE[size]`(sm/md=16px、lg=20px;如 `size-4` 徽章)。\n   * 典型場景:類型徽章(彩底 + glyph)、status 圓點組合等 LucideIcon 表達不了的 leading 視覺。\n   */\n  startContent?: React.ReactNode\n  /** 顯示 checkbox（多選模式由父層控制） */\n  checkbox?: boolean\n  /** Checkbox 選中狀態 */\n  checked?: boolean | 'indeterminate'\n  /** 單選選中（bg-neutral-selected 背景高亮，持續選中狀態） */\n  selected?: boolean\n  /** 後綴 Tag（ReactNode），靠右對齊 */\n  tag?: React.ReactNode\n  /** 後綴自訂內容（ReactNode），用於 DropdownMenu 的 badge/endIcon/shortcut 等 */\n  endContent?: React.ReactNode\n  /** 停用 */\n  disabled?: boolean\n  /** 作為群組標題（不可選，font-medium，fg-muted） */\n  header?: boolean\n  /**\n   * Label 最大行數(line-clamp 截斷,超過顯示 ellipsis)。\n   *\n   * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `1`(單行截斷,符合選單快速掃視需求)\n   * - 數字(1-6)→ 截斷到該行數;>6 超出 line-clamp utility 支援範圍 → 不截斷(同 'none',見 lineClampClass)\n   * - `'none'` → **明確**不截斷,自然 wrap 任意行數\n   *\n   * 為什麼用 `'none'` 而不是 `undefined` 表達不截斷?React props 的 destructure default\n   * 在 `undefined` 時會接管,所以 `<MenuItem labelMaxLines={undefined}>` 等同沒傳,\n   * 會 fallback 到預設 `1`。要明確覆寫成「不截斷」,必須用一個非 undefined 的 sentinel。\n   */\n  labelMaxLines?: number | 'none'\n  /**\n   * Description 最大行數。\n   *\n   * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `1`(跟 label 對稱,維持掃視節奏)\n   * - 數字(1-6)→ 截斷到該行數;>6 超出 line-clamp utility 支援範圍 → 不截斷(同 'none',見 lineClampClass)\n   * - `'none'` → 明確不截斷\n   *\n   * 為什麼預設 1?Menu 的設計目的是「快速掃視多個選項挑一個」,垂直空間是\n   * 寶貴的——一個過高的 item 會破壞 row rhythm,讓使用者眼睛重新校準。description\n   * 跟 label 對稱地截到 1 行,確保所有 item 高度一致(無 desc / 有 desc 兩種高度)。\n   * Consumer 若有合理理由要 2 行 description,可顯式 override。\n   */\n  descMaxLines?: number | 'none'\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// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst MenuItem = React.forwardRef<HTMLDivElement, MenuItemProps>(\n  (\n    {\n      children,\n      description,\n      startIcon: StartIcon,\n      startIconClassName,\n      avatar,\n      startContent,\n      checkbox,\n      checked,\n      selected,\n      tag,\n      endContent,\n      disabled,\n      header,\n      size,\n      labelMaxLines = 1,\n      descMaxLines = 1,\n      className,\n      ...props\n    },\n    ref\n  ) => {\n    const sizeKey = size ?? 'md'\n    const labelClampClass = lineClampClass(labelMaxLines)\n    const descClampClass = lineClampClass(descMaxLines)\n    const iconPx = ICON_SIZE[sizeKey]\n\n    // ── 決定 avatar 容器尺寸 + 對齊模式 ──\n    // 有 description → 使用 block 尺寸（32/40px），block 對齊\n    // 無 description → 使用 inline 尺寸（20/24px），inline 對齊\n    const avatarPx = avatar\n      ? (description ? AVATAR_SIZE.block[sizeKey] : AVATAR_SIZE.inline[sizeKey])\n      : 0\n    const isBlockAlign = avatarPx > 24 && !!description\n\n    const prefixAlign = isBlockAlign\n      ? (`block-${sizeKey}` as const)\n      : 'inline'\n\n    const hasPrefix = !!StartIcon || !!avatar || !!startContent || checkbox\n\n    // ── Header variant ──\n    if (header) {\n      return (\n        <div\n          ref={ref}\n          className={cn(\n            menuItemVariants({ size }),\n            'font-medium text-fg-muted cursor-default pointer-events-none',\n            className,\n          )}\n          role=\"presentation\"\n          {...props}\n        >\n          {children}\n        </div>\n      )\n    }\n\n    // ── ARIA 單一 owner gate(2026-07-05)──\n    // consumer(DropdownMenu 各 item / SelectMenu option row)把 MenuItem 巢狀在 Radix / cmdk\n    // 互動節點內時傳 role=\"presentation\":外層 primitive 是唯一 ARIA owner(aria-checked /\n    // aria-disabled 由外層宣告)。presentation 節點不得掛 ARIA state(axe aria-prohibited-attr\n    // + 內外雙重宣告)→ 同步抑制 role=\"option\" 與 aria-selected / aria-disabled 預設;\n    // data-selected / data-disabled 保留(純樣式 hook,非 ARIA)。正規 listbox option 用法\n    //(不傳 role)與 select-all row(role=\"checkbox\")不受影響。\n    const isPresentation = props.role === 'presentation'\n\n    return (\n      <div\n        ref={ref}\n        role={isPresentation ? 'presentation' : 'option'}\n        aria-selected={isPresentation ? undefined : selected || (checked === true) || undefined}\n        aria-disabled={isPresentation ? undefined : disabled || undefined}\n        data-selected={selected ? '' : undefined}\n        data-disabled={disabled ? '' : undefined}\n        className={cn(\n          menuItemVariants({ size }),\n          !disabled && !selected && 'hover:bg-neutral-hover',\n          // 2026-08-11(SSOT = item-anatomy「選中 × 互動疊加」):選中列滑鼠 hover 本就不變(上行條件互斥);\n          // 補鍵盤焦點深一階 -focus(twMerge 同組蓋過 base 的 focus-visible:bg-neutral-hover)。\n          !disabled && selected && 'bg-neutral-selected focus-visible:bg-neutral-selected-focus',\n          // disabled 用 cursor-not-allowed(對齊 Button + Material/Polaris/Atlassian);\n          // pointer-events-none 會讓 cursor 失效,改用 aria-disabled + onClick guard\n          disabled && 'text-fg-disabled cursor-not-allowed',\n          className,\n        )}\n        // 2026-07-04 robustness:先 spread 其餘 props、後放 guarded handlers — 消除\n        // 「handler 置前 + 後方 runtime filter 同名 key」對屬性順序的隱性依賴,行為不變\n        {...Object.fromEntries(Object.entries(props).filter(([k]) => k !== 'onClick' && k !== 'onKeyDown'))}\n        onClick={disabled ? undefined : props.onClick}\n        onKeyDown={disabled ? undefined : props.onKeyDown}\n      >\n        {/* Prefix 對齊容器 */}\n        {hasPrefix && (\n          <div className={cn(itemPrefixAlignVariants({ align: prefixAlign }))}>\n            {checkbox && (\n              // 2026-07-14 a11y(axe nested-interactive):此 checkbox 是純視覺 indicator —— checked\n              // ARIA state 由外層 row 單一 owner 宣告(Radix menuitemcheckbox / cmdk option /\n              // select-all row role=\"checkbox\",見上方「ARIA 單一 owner gate」)。Radix Checkbox 渲\n              // focusable <button role=\"checkbox\">,巢狀在互動 row 內 = axe nested-interactive\n              // violation;tabIndex=-1 不夠(axe-core no-focusable-content 對 tabindex<0 仍回\n              // violation,僅 messageKey 換 notHidden)。aria-hidden 移出 AT tree(消 SR 內外雙重\n              // checkbox 宣告)+ inert 移除 focusability(axe focusDisabled 認 inert → clean pass)。\n              // inert:React 18/19 傳法不同(18 要空字串、19 要 boolean)→ 消費 module scope\n              // INERT_SPREAD 的 runtime 版本判定,見該處註解。\n              <Checkbox\n                size={CHECKBOX_SIZE[sizeKey]}\n                checked={checked === true ? true : checked === 'indeterminate' ? 'indeterminate' : false}\n                disabled={disabled}\n                tabIndex={-1}\n                aria-hidden\n                {...INERT_SPREAD}\n                className=\"pointer-events-none\"\n              />\n            )}\n            {StartIcon && (\n              <StartIcon\n                data-prefix-type=\"icon\"\n                size={iconPx}\n                className={cn('shrink-0', startIconClassName, disabled && 'text-fg-disabled')}\n                aria-hidden\n              />\n            )}\n            {avatar && (\n              <Avatar\n                data-prefix-type=\"avatar\"\n                src={avatar.src}\n                alt={avatar.alt}\n                color={avatar.color}\n                hoverCard={avatar.hoverCard}\n                size={avatarPx}\n              />\n            )}\n            {startContent && (\n              // 自訂 leading 節點:同容器 = 佔位/排列與 startIcon 一模一樣(見 props JSDoc)。\n              // disabled 用 opacity-disabled(對齊本元件 suffix slot 對自訂 ReactNode 的同款處理)。\n              <span\n                data-prefix-type=\"content\"\n                className={cn('flex shrink-0 items-center', disabled && 'opacity-disabled')}\n              >\n                {startContent}\n              </span>\n            )}\n          </div>\n        )}\n\n        {/* Content — 消費 ItemContent primitive(SSOT)。\n            scanning mode 跟隨 size:sm/md = caption,lg = body(desc 比 label lg 16 小 1 tier)。\n            labelClampClass / descClampClass 透過 className escape hatch 傳入(MenuItem 特化 labelMaxLines / descMaxLines 語意)。 */}\n        <ItemContent\n          label={children}\n          description={description}\n          mode=\"scanning\"\n          size={sizeKey === 'lg' ? 'lg' : 'md'}\n          descriptionTone={disabled ? 'disabled' : 'secondary'}\n          labelTruncate={false}\n          labelClassName={cn(labelClampClass || 'break-words', disabled && 'text-fg-disabled')}\n          descriptionClassName={cn(descClampClass || 'break-words')}\n        />\n\n        {(tag || endContent) && (\n          // @row-slot-handcraft-allow: MenuItem 自身即 row primitive（item-anatomy Family 1 owner），此 tag/endContent 容器是 MenuItem 自有 suffix slot 實作，非外部 consumer hand-craft → 不再 wrap ItemSuffix\n          <div className={cn(\n            'flex items-center gap-2 shrink-0 h-[1lh] ml-auto',\n            disabled && 'opacity-disabled',\n          )}>\n            {tag}\n            {endContent}\n          </div>\n        )}\n      </div>\n    )\n  }\n)\nMenuItem.displayName = 'MenuItem'\n\n// ── Group ──\n// MenuGroup — Menu-like group primitive(跨元件設計語言統一,SSOT 見\n// `patterns/element-anatomy/item-anatomy.spec.md`「Group auto-separation」)\n//\n// 設計語言:每個 group 上下 8px + 相鄰 group 間 border-divider + 視覺 gap 16px\n//\n// 本元件用 Pattern A:`py-2 [&+&]:border-t [&+&]:border-divider`\n// (適用外層容器無 py-2 的情境,例 Command.List——Group 自帶邊界 padding)\n//\n// **視覺必須跟 DropdownMenuGroup 等價**(見 dropdown-menu.tsx Pattern B 對照)。\n// 改動前先讀 item-anatomy.spec.md「Group auto-separation」確認視覺不漂移。\n\nexport interface MenuGroupProps extends React.HTMLAttributes<HTMLDivElement> {\n  children: React.ReactNode\n}\n\nconst MenuGroup = React.forwardRef<HTMLDivElement, MenuGroupProps>(\n  ({ children, className, ...props }, ref) => (\n    <div\n      ref={ref}\n      role=\"group\"\n      className={cn('py-2 [&+&]:border-t [&+&]:border-divider', className)}\n      {...props}\n    >\n      {children}\n    </div>\n  )\n)\nMenuGroup.displayName = 'MenuGroup'\n\n// ── Footer ──\n\nexport interface MenuFooterProps extends React.HTMLAttributes<HTMLDivElement> {\n  children: React.ReactNode\n}\n\nconst MenuFooter = React.forwardRef<HTMLDivElement, MenuFooterProps>(\n  ({ children, className, ...props }, ref) => (\n    <div\n      ref={ref}\n      className={cn('py-2 border-t border-divider', className)}\n      {...props}\n    >\n      {children}\n    </div>\n  )\n)\nMenuFooter.displayName = 'MenuFooter'\n\n// Story auto-compile metadata — Phase 1+2 migration\nexport const menuItemMeta = {\n  component: 'MenuItem',\n  family: 1,\n  variants: {},\n  sizes: {\n    sm: {},\n    md: {},\n    lg: {},\n  },\n  defaultSize: 'md',\n  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: ['bg-neutral-hover', 'bg-neutral-selected'],\n    fg: ['text-fg-muted', 'text-fg-disabled'],\n  },\n} as const\n\nexport { MenuItem, MenuGroup, MenuFooter, menuItemVariants }\n"],"names":[],"mappings":"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"}

package/dist/components/Notice/index.d.ts

@@ -0,0 +1,2 @@
+export * from './notice';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/Notice/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Notice/index.ts"],"names":[],"mappings":"AAIA,cAAc,UAAU,CAAA"}

package/dist/components/Notice/index.js

@@ -0,0 +1,8 @@
+import { Notice, SUBTLE_ICON_COLOR, noticeMeta, useInverseTheme } from "./notice.js";
+export {
+  Notice,
+  SUBTLE_ICON_COLOR,
+  noticeMeta,
+  useInverseTheme
+};
+//# sourceMappingURL=index.js.map

package/dist/components/Notice/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/components/Notice/notice.d.ts

@@ -1,11 +1,18 @@
+/**
+ * @internal — DS-internal 單元(per `packages/design-system/ds-canonical/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 Alert / Toast wrap 消費,end-user app 請用 wrapper 元件。
+ */
 import * as React from 'react';
 /**
  * Notice — Toast / Alert 共用的視覺佈局層
  *
- * ── Typography: md tier ──
- * title: text-body (14px) leading-compact — 有 description 時加 font-medium
- * description: text-body (14px) leading-compact + text-fg-secondary (neutral-8)
+ * ── Typography: Family 2 reading-md(2026-06-15 user 拍板,off-grid 偏移收斂)──
+ * title: text-body (14px) default leading 1.5 — 有 description 時加 font-medium
+ * description: text-body (14px) default leading 1.5 + text-fg-secondary (neutral-8)
  * 14px 配 14px — 視覺層級靠 font-weight + color 區分,不靠 font-size。
+ * **行高 = reading 預設 1.5**(非 compact):Notice 是 Family 2 reading consumer,
+ * ItemContent 預設 mode='reading' + gap token `--item-gap-label-desc-reading` 名實相符。
+ * 原 `leading-compact`(1.3)= reading-gap + scanning-行高 混搭的 off-grid 偏移,已移除。
  *
  * ── Padding（固定,不隨 density 變） ──
  * px = px-4（16px）
@@ -22,7 +29,7 @@ import * as React from 'react';
  * Rationale(Notification banner family canonical):
  * - Notice / Alert / Toast 屬 **notification banner family**(ephemeral、px-4 py-3 固定不隨 density),
  *   dismiss 是邊角小 affordance,xs 視覺不搶眼不跟 content 競爭。見 `overlay-surface.spec.md`
- *   「Chrome dismiss size canonical」三家族分類(Modal sm / Non-modal xs / Notification xs)
+ *   「Chrome dismiss size canonical」(overlay header 走 sm native + 負 margin trick;xs 只用於 notification banner family)
  * - Close 左側可加 refresh / share(action group region),皆統一 xs
  * - `dismiss` prop 自動套 variant="text" + fg-muted override
  * SSOT:patterns/element-anatomy/inline-action.spec.md「Dismiss canonical — X close only」
@@ -35,6 +42,11 @@ export interface NoticeProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     title: React.ReactNode;
     description?: React.ReactNode;
     endContent?: React.ReactNode;
+    /**
+     * 顯示關閉鈕(預設 true)。**需同時傳 `onDismiss` 才會渲染 X** — Notice 是 controlled-only
+     * (不自我移除),無 handler 的 X 是可 focus、SR 播報「關閉通知」但按下零反應的死按鈕
+     * (2026-07-05 D4;對齊 Polaris Banner `onDismiss` 存在才顯示 X / Ant Alert `closable` 預設 false)。
+     */
     dismissible?: boolean;
     onDismiss?: () => void;
     /** ARIA label for the dismiss button. Override for i18n. Default: "關閉通知" */
@@ -55,10 +67,26 @@ declare const Notice: React.ForwardRefExoticComponent<NoticeProps & React.RefAtt
 export declare function useInverseTheme(): 'dark' | 'light';
 export declare const noticeMeta: {
     readonly component: "Notice";
-    readonly family: null;
-    readonly variants: {};
+    readonly family: 2;
+    readonly variants: {
+        readonly neutral: {
+            readonly purpose: "一般訊息、系統公告;無情緒色、不掛 status icon(title-only icon-less 形態)";
+        };
+        readonly info: {
+            readonly purpose: "資訊提示(版本更新、流程說明);Info icon";
+        };
+        readonly success: {
+            readonly purpose: "操作成功確認;CircleCheck icon";
+        };
+        readonly warning: {
+            readonly purpose: "可恢復警告(未儲存變更、連線不穩);TriangleAlert icon";
+        };
+        readonly error: {
+            readonly purpose: "錯誤(操作失敗、權限不足);XCircle icon";
+        };
+    };
     readonly sizes: {};
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly states: readonly ["default"];
     readonly tokens: {
         readonly bg: readonly [];
         readonly fg: readonly ["text-error-text", "text-fg-muted", "text-fg-secondary", "text-info-text", "text-success-text", "text-warning-text"];

package/dist/components/Notice/notice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notice.d.ts","sourceRoot":"","sources":["../../../src/components/Notice/notice.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAM9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;AAUhF,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAM3D,CAAA;AAQD,MAAM,WAAW,WACf,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAC3D,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC5B,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;IACzB;;OAEG;IACH,WAAW,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,KAAK,CAAA;CAC7C;AAED,QAAA,MAAM,MAAM,oFAyDX,CAAA;AA+BD,wBAAgB,eAAe,IAAI,MAAM,GAAG,OAAO,CAGlD;AAID,eAAO,MAAM,UAAU;;;;;;;;;;;CAeb,CAAA;AAEV,OAAO,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"notice.d.ts","sourceRoot":"","sources":["../../../src/components/Notice/notice.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAO9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;AAUhF,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAM3D,CAAA;AAYD,MAAM,WAAW,WACf,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAC3D,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC5B;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;IACzB;;OAEG;IACH,WAAW,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,KAAK,CAAA;CAC7C;AAED,QAAA,MAAM,MAAM,oFAgFX,CAAA;AA+BD,wBAAgB,eAAe,IAAI,MAAM,GAAG,OAAO,CAGlD;AAMD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmBb,CAAA;AAEV,OAAO,EAAE,MAAM,EAAE,CAAA"}

package/dist/components/Notice/notice.js

@@ -3,7 +3,8 @@ import * as React from "react";
 import { XCircle, TriangleAlert, CircleCheck, Info, X } from "lucide-react";
 import { cn } from "../../lib/utils.js";
 import { Button } from "../Button/button.js";
-import { ItemPrefix, ItemContent } from "../../patterns/element-anatomy/item-anatomy.js";
+import { ButtonDivider } from "../Button/button-group.js";
+import { ItemPrefix, ICON_SIZE, ItemContent, ItemSuffix } from "../../patterns/element-anatomy/item-anatomy.js";
 const VARIANT_ICON = {
   neutral: null,
   info: Info,
@@ -20,7 +21,11 @@ const SUBTLE_ICON_COLOR = {
 };
 const NOTICE_LAYOUT = [
   "flex items-start gap-2 w-full",
-  "text-body leading-compact",
+  // 2026-06-15 user 拍板:Notice = 乾淨 Family 2 reading-md consumer。
+  // 原 `leading-compact`(1.3)是 off-grid 偏移(reading gap token + scanning 行高混搭、未文件化),
+  // 已移除 → label/desc 走 text-body reading 預設 1.5,與 ItemContent 預設 mode='reading' + gap
+  // token `--item-gap-label-desc-reading` 名實相符。詳 notice.spec.md「Typography」段。
+  "text-body",
   "px-4 py-3"
 ].join(" ");
 const Notice = React.forwardRef(
@@ -29,7 +34,9 @@ const Notice = React.forwardRef(
     title,
     description,
     endContent,
-    dismissible = true,
+    // 不 destructure-default(保留「顯式傳 true」的可辨識性給下方 dev-warn);等效預設 true 由
+    // showDismiss 的 `!== false` 承擔。
+    dismissible,
     onDismiss,
     dismissAriaLabel = "關閉通知",
     // i18n-allow: DS default; consumer override via dismissAriaLabel prop
@@ -38,6 +45,10 @@ const Notice = React.forwardRef(
     ...props
   }, ref) => {
     const StatusIcon = VARIANT_ICON[variant];
+    const showDismiss = dismissible !== false && onDismiss != null;
+    if (process.env.NODE_ENV !== "production" && dismissible === true && onDismiss == null) {
+      console.warn("[Notice] dismissible=true 但未傳 onDismiss,關閉鈕不會渲染(需同時提供 onDismiss)。");
+    }
     return /* @__PURE__ */ jsxs(
       "div",
       {
@@ -45,7 +56,7 @@ const Notice = React.forwardRef(
         className: cn(NOTICE_LAYOUT, className),
         ...props,
         children: [
-          StatusIcon && /* @__PURE__ */ jsx(ItemPrefix, { children: /* @__PURE__ */ jsx(StatusIcon, { size: 16, className: cn("shrink-0", iconClassName), "aria-hidden": true }) }),
+          StatusIcon && /* @__PURE__ */ jsx(ItemPrefix, { children: /* @__PURE__ */ jsx(StatusIcon, { size: ICON_SIZE.md, className: cn("shrink-0", iconClassName), "aria-hidden": true }) }),
           /* @__PURE__ */ jsx(
             ItemContent,
             {
@@ -54,9 +65,15 @@ const Notice = React.forwardRef(
               labelClassName: description ? "font-medium" : void 0
             }
           ),
-          (endContent || dismissible) && /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2 shrink-0 h-[1lh]", children: [
+          (endContent || showDismiss) && // 2026-06-15 user 拍板:消費 ItemSuffix primitive(原手刻 div + @row-slot-handcraft-allow
+          // 已移除)。item-anatomy.spec.md 把 Notice 的 action/dismiss 對應到 suffix slot;ItemSuffix
+          // base geometry(h-[1lh] shrink-0 ml-auto flex items-center gap-2)正是此處所需,hoverReveal
+          // 預設 false 故無 row inline-action 機制干擾。內裝 dismiss = Button iconOnly dismiss xs(banner
+          // family canonical,overlay-surface.spec.md「Chrome dismiss size canonical」)。
+          /* @__PURE__ */ jsxs(ItemSuffix, { children: [
             endContent,
-            dismissible && /* @__PURE__ */ jsx(
+            endContent != null && showDismiss && /* @__PURE__ */ jsx(ButtonDivider, {}),
+            showDismiss && /* @__PURE__ */ jsx(
               Button,
               {
                 "data-dismiss": true,
@@ -101,11 +118,18 @@ function useInverseTheme() {
 }
 const noticeMeta = {
   component: "Notice",
-  family: null,
-  // non-family composite / overlay / layout
-  variants: {},
+  family: 2,
+  // Family 2（List item layout）消費者 — 對齊 notice.spec.md frontmatter family: 2 + body「Layout Family」段
+  variants: {
+    neutral: { purpose: "一般訊息、系統公告;無情緒色、不掛 status icon(title-only icon-less 形態)" },
+    info: { purpose: "資訊提示(版本更新、流程說明);Info icon" },
+    success: { purpose: "操作成功確認;CircleCheck icon" },
+    warning: { purpose: "可恢復警告(未儲存變更、連線不穩);TriangleAlert icon" },
+    error: { purpose: "錯誤(操作失敗、權限不足);XCircle icon" }
+  },
   sizes: {},
-  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  states: ["default"],
+  // 無互動 layout primitive(spec「邊界案例」:不擁有 disabled;hover / focus 屬內嵌 dismiss Button)
   tokens: {
     bg: [],
     fg: ["text-error-text", "text-fg-muted", "text-fg-secondary", "text-info-text", "text-success-text", "text-warning-text"],

package/dist/components/Notice/notice.js.map

@@ -1 +1 @@
-{"version":3,"file":"notice.js","sources":["../../../src/components/Notice/notice.tsx"],"sourcesContent":["import * as React from 'react'\nimport { X as XIcon, Info, CircleCheck, TriangleAlert, XCircle, type LucideIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Button } from '@/design-system/components/Button/button'\nimport { ItemContent, ItemPrefix } from '@/design-system/patterns/element-anatomy/item-anatomy'\n\n/**\n * Notice — Toast / Alert 共用的視覺佈局層\n *\n * ── Typography: md tier ──\n * title: text-body (14px) leading-compact — 有 description 時加 font-medium\n * description: text-body (14px) leading-compact + text-fg-secondary (neutral-8)\n * 14px 配 14px — 視覺層級靠 font-weight + color 區分,不靠 font-size。\n *\n * ── Padding（固定,不隨 density 變） ──\n * px = px-4（16px）\n * py = py-3（12px）\n * gap = gap-2（8px）\n * Toast/Alert 是浮動通知,不是工作區域元件——density 控制表單/選單的緊湊度,\n * 通知的尺寸應該固定,不隨 density 縮放。\n *\n * ── Icon: md tier ──\n * icon size: 16px（ICON_SIZE.md）\n *\n * ── Dismiss X(chrome corner close,Cat 3 Action group region)──\n * 用 Button iconOnly dismiss **size=\"xs\"** — 非 Inline Action、非自刻 button。\n * Rationale(Notification banner family canonical):\n * - Notice / Alert / Toast 屬 **notification banner family**(ephemeral、px-4 py-3 固定不隨 density),\n *   dismiss 是邊角小 affordance,xs 視覺不搶眼不跟 content 競爭。見 `overlay-surface.spec.md`\n *   「Chrome dismiss size canonical」三家族分類(Modal sm / Non-modal xs / Notification xs)\n * - Close 左側可加 refresh / share(action group region),皆統一 xs\n * - `dismiss` prop 自動套 variant=\"text\" + fg-muted override\n * SSOT:patterns/element-anatomy/inline-action.spec.md「Dismiss canonical — X close only」\n *      + components/Alert/alert.spec.md「Chrome corner close X canonical」。\n */\n\nexport type NoticeVariant = 'neutral' | 'info' | 'success' | 'warning' | 'error'\n\nconst VARIANT_ICON: Record<NoticeVariant, LucideIcon | null> = {\n  neutral: null,\n  info: Info,\n  success: CircleCheck,\n  warning: TriangleAlert,\n  error: XCircle,\n}\n\nexport const SUBTLE_ICON_COLOR: Record<NoticeVariant, string> = {\n  neutral: 'text-fg-muted',\n  info: 'text-info-text',\n  success: 'text-success-text',\n  warning: 'text-warning-text',\n  error: 'text-error-text',\n}\n\nconst NOTICE_LAYOUT = [\n  'flex items-start gap-2 w-full',\n  'text-body leading-compact',\n  'px-4 py-3',\n].join(' ')\n\nexport interface NoticeProps\n  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {\n  variant?: NoticeVariant\n  title: React.ReactNode\n  description?: React.ReactNode\n  endContent?: React.ReactNode\n  dismissible?: boolean\n  onDismiss?: () => void\n  /** ARIA label for the dismiss button. Override for i18n. Default: \"關閉通知\" */\n  dismissAriaLabel?: string\n  iconClassName?: string\n  /**\n   * ARIA role 由 wrapping consumer 決定(Alert / Toast / 自管 host),Notice 預設不帶 role。\n   * Notice 是 layout primitive,Alert / Toast 是 live region 擁有者——避免 nested live region\n   * 造成 screen reader 重複朗讀。明文傳遞才覆寫。\n   */\n  role?: 'status' | 'alert'\n  /**\n   * 對應 role 的 aria-live 策略,wrapping consumer 決定;Notice 預設 undefined 不帶 live region。\n   */\n  'aria-live'?: 'polite' | 'assertive' | 'off'\n}\n\nconst Notice = React.forwardRef<HTMLDivElement, NoticeProps>(\n  (\n    {\n      variant = 'neutral',\n      title,\n      description,\n      endContent,\n      dismissible = true,\n      onDismiss,\n      dismissAriaLabel = '關閉通知', // i18n-allow: DS default; consumer override via dismissAriaLabel prop\n      iconClassName,\n      className,\n      ...props\n    },\n    ref,\n  ) => {\n    const StatusIcon = VARIANT_ICON[variant]\n\n    return (\n      <div\n        ref={ref}\n        className={cn(NOTICE_LAYOUT, className)}\n        {...props}\n      >\n        {StatusIcon && (\n          <ItemPrefix>\n            <StatusIcon size={16} className={cn('shrink-0', iconClassName)} aria-hidden />\n          </ItemPrefix>\n        )}\n\n        {/* Title + description 消費 ItemContent primitive(SSOT)。\n            Label 有 desc 時 font-medium(Notice idiom:title 跟 desc 對照時 title 要更重)。 */}\n        <ItemContent\n          label={title}\n          description={description}\n          labelClassName={description ? 'font-medium' : undefined}\n        />\n\n        {(endContent || dismissible) && (\n          <div className=\"flex items-center gap-2 shrink-0 h-[1lh]\">\n            {endContent}\n            {dismissible && (\n              <Button\n                data-dismiss\n                iconOnly\n                dismiss\n                size=\"xs\"\n                startIcon={XIcon}\n                aria-label={dismissAriaLabel}\n                onClick={onDismiss}\n              />\n            )}\n          </div>\n        )}\n      </div>\n    )\n  },\n)\nNotice.displayName = 'Notice'\n\n// Singleton MutationObserver + subscription fan-out(2026-04-22 D3 perf audit):\n// 先前每個 useInverseTheme consumer(Alert / Toast / Notice instance 等)各建一個 MO,\n// N 個 Notice = N 個 observers。singleton 共用一個 MO + pub/sub 讓 theme swap 只做一次 DOM read。\nlet themeObserverStarted = false\nconst themeSubscribers = new Set<() => void>()\n\nfunction getInverseTheme(): 'dark' | 'light' {\n  if (typeof document === 'undefined') return 'dark'\n  const current = document.documentElement.getAttribute('data-theme') ?? 'light'\n  return current === 'dark' ? 'light' : 'dark'\n}\n\nfunction startThemeObserver() {\n  if (themeObserverStarted || typeof document === 'undefined') return\n  themeObserverStarted = true\n  const root = document.documentElement\n  const observer = new MutationObserver(() => {\n    themeSubscribers.forEach((cb) => cb())\n  })\n  observer.observe(root, { attributes: true, attributeFilter: ['data-theme'] })\n}\n\nfunction subscribe(cb: () => void): () => void {\n  startThemeObserver()\n  themeSubscribers.add(cb)\n  return () => themeSubscribers.delete(cb)\n}\n\nexport function useInverseTheme(): 'dark' | 'light' {\n  // useSyncExternalStore canonical (React 18+):單一 external source 被 N consumers 訂閱\n  return React.useSyncExternalStore(subscribe, getInverseTheme, getInverseTheme)\n}\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const noticeMeta = {\n  component: 'Notice',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: [],\n    fg: ['text-error-text', 'text-fg-muted', 'text-fg-secondary', 'text-info-text', 'text-success-text', 'text-warning-text'],\n    ring: [],\n  },\n} as const\n\nexport { Notice }\n"],"names":["XIcon"],"mappings":";;;;;;AAsCA,MAAM,eAAyD;AAAA,EAC7D,SAAS;AAAA,EACT,MAAM;AAAA,EACN,SAAS;AAAA,EACT,SAAS;AAAA,EACT,OAAO;AACT;AAEO,MAAM,oBAAmD;AAAA,EAC9D,SAAS;AAAA,EACT,MAAM;AAAA,EACN,SAAS;AAAA,EACT,SAAS;AAAA,EACT,OAAO;AACT;AAEA,MAAM,gBAAgB;AAAA,EACpB;AAAA,EACA;AAAA,EACA;AACF,EAAE,KAAK,GAAG;AAyBV,MAAM,SAAS,MAAM;AAAA,EACnB,CACE;AAAA,IACE,UAAU;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc;AAAA,IACd;AAAA,IACA,mBAAmB;AAAA;AAAA,IACnB;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EAAA,GAEL,QACG;AACH,UAAM,aAAa,aAAa,OAAO;AAEvC,WACE;AAAA,MAAC;AAAA,MAAA;AAAA,QACC;AAAA,QACA,WAAW,GAAG,eAAe,SAAS;AAAA,QACrC,GAAG;AAAA,QAEH,UAAA;AAAA,UAAA,cACC,oBAAC,YAAA,EACC,UAAA,oBAAC,YAAA,EAAW,MAAM,IAAI,WAAW,GAAG,YAAY,aAAa,GAAG,eAAW,MAAC,GAC9E;AAAA,UAKF;AAAA,YAAC;AAAA,YAAA;AAAA,cACC,OAAO;AAAA,cACP;AAAA,cACA,gBAAgB,cAAc,gBAAgB;AAAA,YAAA;AAAA,UAAA;AAAA,WAG9C,cAAc,gBACd,qBAAC,OAAA,EAAI,WAAU,4CACZ,UAAA;AAAA,YAAA;AAAA,YACA,eACC;AAAA,cAAC;AAAA,cAAA;AAAA,gBACC,gBAAY;AAAA,gBACZ,UAAQ;AAAA,gBACR,SAAO;AAAA,gBACP,MAAK;AAAA,gBACL,WAAWA;AAAAA,gBACX,cAAY;AAAA,gBACZ,SAAS;AAAA,cAAA;AAAA,YAAA;AAAA,UACX,EAAA,CAEJ;AAAA,QAAA;AAAA,MAAA;AAAA,IAAA;AAAA,EAIR;AACF;AACA,OAAO,cAAc;AAKrB,IAAI,uBAAuB;AAC3B,MAAM,uCAAuB,IAAA;AAE7B,SAAS,kBAAoC;AAC3C,MAAI,OAAO,aAAa,YAAa,QAAO;AAC5C,QAAM,UAAU,SAAS,gBAAgB,aAAa,YAAY,KAAK;AACvE,SAAO,YAAY,SAAS,UAAU;AACxC;AAEA,SAAS,qBAAqB;AAC5B,MAAI,wBAAwB,OAAO,aAAa,YAAa;AAC7D,yBAAuB;AACvB,QAAM,OAAO,SAAS;AACtB,QAAM,WAAW,IAAI,iBAAiB,MAAM;AAC1C,qBAAiB,QAAQ,CAAC,OAAO,GAAA,CAAI;AAAA,EACvC,CAAC;AACD,WAAS,QAAQ,MAAM,EAAE,YAAY,MAAM,iBAAiB,CAAC,YAAY,GAAG;AAC9E;AAEA,SAAS,UAAU,IAA4B;AAC7C,qBAAA;AACA,mBAAiB,IAAI,EAAE;AACvB,SAAO,MAAM,iBAAiB,OAAO,EAAE;AACzC;AAEO,SAAS,kBAAoC;AAElD,SAAO,MAAM,qBAAqB,WAAW,iBAAiB,eAAe;AAC/E;AAIO,MAAM,aAAa;AAAA,EACxB,WAAW;AAAA,EACX,QAAQ;AAAA;AAAA,EACR,UAAU,CAAA;AAAA,EAGV,OAAO,CAAA;AAAA,EAGP,QAAQ,CAAC,WAAW,SAAS,UAAU,iBAAiB,UAAU;AAAA,EAClE,QAAQ;AAAA,IACN,IAAI,CAAA;AAAA,IACJ,IAAI,CAAC,mBAAmB,iBAAiB,qBAAqB,kBAAkB,qBAAqB,mBAAmB;AAAA,IACxH,MAAM,CAAA;AAAA,EAAC;AAEX;"}
+{"version":3,"file":"notice.js","sources":["../../../src/components/Notice/notice.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;由 Alert / Toast wrap 消費,end-user app 請用 wrapper 元件。\n */\nimport * as React from 'react'\nimport { X as XIcon, Info, CircleCheck, TriangleAlert, XCircle, type LucideIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Button } from '@/design-system/components/Button/button'\nimport { ButtonDivider } from '@/design-system/components/Button/button-group'\nimport { ICON_SIZE, ItemContent, ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'\n\n/**\n * Notice — Toast / Alert 共用的視覺佈局層\n *\n * ── Typography: Family 2 reading-md(2026-06-15 user 拍板,off-grid 偏移收斂)──\n * title: text-body (14px) default leading 1.5 — 有 description 時加 font-medium\n * description: text-body (14px) default leading 1.5 + text-fg-secondary (neutral-8)\n * 14px 配 14px — 視覺層級靠 font-weight + color 區分,不靠 font-size。\n * **行高 = reading 預設 1.5**(非 compact):Notice 是 Family 2 reading consumer,\n * ItemContent 預設 mode='reading' + gap token `--item-gap-label-desc-reading` 名實相符。\n * 原 `leading-compact`(1.3)= reading-gap + scanning-行高 混搭的 off-grid 偏移,已移除。\n *\n * ── Padding（固定,不隨 density 變） ──\n * px = px-4（16px）\n * py = py-3（12px）\n * gap = gap-2（8px）\n * Toast/Alert 是浮動通知,不是工作區域元件——density 控制表單/選單的緊湊度,\n * 通知的尺寸應該固定,不隨 density 縮放。\n *\n * ── Icon: md tier ──\n * icon size: 16px（ICON_SIZE.md）\n *\n * ── Dismiss X(chrome corner close,Cat 3 Action group region)──\n * 用 Button iconOnly dismiss **size=\"xs\"** — 非 Inline Action、非自刻 button。\n * Rationale(Notification banner family canonical):\n * - Notice / Alert / Toast 屬 **notification banner family**(ephemeral、px-4 py-3 固定不隨 density),\n *   dismiss 是邊角小 affordance,xs 視覺不搶眼不跟 content 競爭。見 `overlay-surface.spec.md`\n *   「Chrome dismiss size canonical」(overlay header 走 sm native + 負 margin trick;xs 只用於 notification banner family)\n * - Close 左側可加 refresh / share(action group region),皆統一 xs\n * - `dismiss` prop 自動套 variant=\"text\" + fg-muted override\n * SSOT:patterns/element-anatomy/inline-action.spec.md「Dismiss canonical — X close only」\n *      + components/Alert/alert.spec.md「Chrome corner close X canonical」。\n */\n\nexport type NoticeVariant = 'neutral' | 'info' | 'success' | 'warning' | 'error'\n\nconst VARIANT_ICON: Record<NoticeVariant, LucideIcon | null> = {\n  neutral: null,\n  info: Info,\n  success: CircleCheck,\n  warning: TriangleAlert,\n  error: XCircle,\n}\n\nexport const SUBTLE_ICON_COLOR: Record<NoticeVariant, string> = {\n  neutral: 'text-fg-muted',\n  info: 'text-info-text',\n  success: 'text-success-text',\n  warning: 'text-warning-text',\n  error: 'text-error-text',\n}\n\nconst NOTICE_LAYOUT = [\n  'flex items-start gap-2 w-full',\n  // 2026-06-15 user 拍板:Notice = 乾淨 Family 2 reading-md consumer。\n  // 原 `leading-compact`(1.3)是 off-grid 偏移(reading gap token + scanning 行高混搭、未文件化),\n  // 已移除 → label/desc 走 text-body reading 預設 1.5,與 ItemContent 預設 mode='reading' + gap\n  // token `--item-gap-label-desc-reading` 名實相符。詳 notice.spec.md「Typography」段。\n  'text-body',\n  'px-4 py-3',\n].join(' ')\n\nexport interface NoticeProps\n  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {\n  variant?: NoticeVariant\n  title: React.ReactNode\n  description?: React.ReactNode\n  endContent?: React.ReactNode\n  /**\n   * 顯示關閉鈕(預設 true)。**需同時傳 `onDismiss` 才會渲染 X** — Notice 是 controlled-only\n   * (不自我移除),無 handler 的 X 是可 focus、SR 播報「關閉通知」但按下零反應的死按鈕\n   * (2026-07-05 D4;對齊 Polaris Banner `onDismiss` 存在才顯示 X / Ant Alert `closable` 預設 false)。\n   */\n  dismissible?: boolean\n  onDismiss?: () => void\n  /** ARIA label for the dismiss button. Override for i18n. Default: \"關閉通知\" */\n  dismissAriaLabel?: string\n  iconClassName?: string\n  /**\n   * ARIA role 由 wrapping consumer 決定(Alert / Toast / 自管 host),Notice 預設不帶 role。\n   * Notice 是 layout primitive,Alert / Toast 是 live region 擁有者——避免 nested live region\n   * 造成 screen reader 重複朗讀。明文傳遞才覆寫。\n   */\n  role?: 'status' | 'alert'\n  /**\n   * 對應 role 的 aria-live 策略,wrapping consumer 決定;Notice 預設 undefined 不帶 live region。\n   */\n  'aria-live'?: 'polite' | 'assertive' | 'off'\n}\n\nconst Notice = React.forwardRef<HTMLDivElement, NoticeProps>(\n  (\n    {\n      variant = 'neutral',\n      title,\n      description,\n      endContent,\n      // 不 destructure-default(保留「顯式傳 true」的可辨識性給下方 dev-warn);等效預設 true 由\n      // showDismiss 的 `!== false` 承擔。\n      dismissible,\n      onDismiss,\n      dismissAriaLabel = '關閉通知', // i18n-allow: DS default; consumer override via dismissAriaLabel prop\n      iconClassName,\n      className,\n      ...props\n    },\n    ref,\n  ) => {\n    const StatusIcon = VARIANT_ICON[variant]\n\n    // 2026-07-05 D4:X 渲染條件 = dismissible(預設 true)**且**有傳 onDismiss — 原 `dismissible &&`\n    // 單獨判斷讓預設用法 <Alert title=\"…\"/> 渲染一顆死 X(controlled-only 不自我移除,onClick=undefined\n    // 零反應;keyboard / SR 使用者按 Enter 零回饋 = 假 affordance)。對齊 Polaris Banner(onDismiss\n    // 存在才顯示 X)/ Ant Alert(closable 預設 false)。\n    const showDismiss = dismissible !== false && onDismiss != null\n    if (process.env.NODE_ENV !== 'production' && dismissible === true && onDismiss == null) {\n      // 只在「顯式傳 dismissible={true} 卻沒接 onDismiss」的消費端矛盾時提示(預設 undefined 不吵)\n      console.warn('[Notice] dismissible=true 但未傳 onDismiss,關閉鈕不會渲染(需同時提供 onDismiss)。')\n    }\n\n    return (\n      <div\n        ref={ref}\n        className={cn(NOTICE_LAYOUT, className)}\n        {...props}\n      >\n        {StatusIcon && (\n          <ItemPrefix>\n            <StatusIcon size={ICON_SIZE.md} className={cn('shrink-0', iconClassName)} aria-hidden />\n          </ItemPrefix>\n        )}\n\n        {/* Title + description 消費 ItemContent primitive(SSOT)。\n            Label 有 desc 時 font-medium(Notice idiom:title 跟 desc 對照時 title 要更重)。 */}\n        <ItemContent\n          label={title}\n          description={description}\n          labelClassName={description ? 'font-medium' : undefined}\n        />\n\n        {(endContent || showDismiss) && (\n          // 2026-06-15 user 拍板:消費 ItemSuffix primitive(原手刻 div + @row-slot-handcraft-allow\n          // 已移除)。item-anatomy.spec.md 把 Notice 的 action/dismiss 對應到 suffix slot;ItemSuffix\n          // base geometry(h-[1lh] shrink-0 ml-auto flex items-center gap-2)正是此處所需,hoverReveal\n          // 預設 false 故無 row inline-action 機制干擾。內裝 dismiss = Button iconOnly dismiss xs(banner\n          // family canonical,overlay-surface.spec.md「Chrome dismiss size canonical」)。\n          <ItemSuffix>\n            {endContent}\n            {/* 誤觸保護分隔線由 DS 放,consumer 零自刻(同 Dialog 先例 dialog.tsx:184-193)。\n                語意 SSOT → action-bar.spec.md 第五節「誤觸保護」:關閉鈕左邊緊鄰其他操作按鈕時必加;\n                只有關閉鈕(無 endContent)時不加 —— 沒有東西需要被隔開。\n                Alert 與 Toast 共用本基座,因此兩者行為由結構保證一致(2026-08-06 codify:\n                先前只有 Alert 規範寫了分隔線、Toast 未定義,同基座同 layout 卻行為分歧)。 */}\n            {endContent != null && showDismiss && <ButtonDivider />}\n            {showDismiss && (\n              <Button\n                data-dismiss\n                iconOnly\n                dismiss\n                size=\"xs\"\n                startIcon={XIcon}\n                aria-label={dismissAriaLabel}\n                onClick={onDismiss}\n              />\n            )}\n          </ItemSuffix>\n        )}\n      </div>\n    )\n  },\n)\nNotice.displayName = 'Notice'\n\n// Singleton MutationObserver + subscription fan-out(2026-04-22 D3 perf audit):\n// 先前每個 useInverseTheme consumer(Alert / Toast / Notice instance 等)各建一個 MO,\n// N 個 Notice = N 個 observers。singleton 共用一個 MO + pub/sub 讓 theme swap 只做一次 DOM read。\nlet themeObserverStarted = false\nconst themeSubscribers = new Set<() => void>()\n\nfunction getInverseTheme(): 'dark' | 'light' {\n  if (typeof document === 'undefined') return 'dark'\n  const current = document.documentElement.getAttribute('data-theme') ?? 'light'\n  return current === 'dark' ? 'light' : 'dark'\n}\n\nfunction startThemeObserver() {\n  if (themeObserverStarted || typeof document === 'undefined') return\n  themeObserverStarted = true\n  const root = document.documentElement\n  const observer = new MutationObserver(() => {\n    themeSubscribers.forEach((cb) => cb())\n  })\n  observer.observe(root, { attributes: true, attributeFilter: ['data-theme'] })\n}\n\nfunction subscribe(cb: () => void): () => void {\n  startThemeObserver()\n  themeSubscribers.add(cb)\n  return () => themeSubscribers.delete(cb)\n}\n\nexport function useInverseTheme(): 'dark' | 'light' {\n  // useSyncExternalStore canonical (React 18+):單一 external source 被 N consumers 訂閱\n  return React.useSyncExternalStore(subscribe, getInverseTheme, getInverseTheme)\n}\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// 2026-07-16 dim 78/DA3:variants 補齊 — 對齊 notice.spec.md frontmatter 5 variants(SSOT)\n// + alertMeta `{ purpose }` idiom(Alert 是 Notice 直接 consumer,同 5-variant 語意)。\n// variant 語意 = status icon 選擇(per spec「Variant」表);色彩由消費者 data-theme 控制。\nexport const noticeMeta = {\n  component: 'Notice',\n  family: 2, // Family 2（List item layout）消費者 — 對齊 notice.spec.md frontmatter family: 2 + body「Layout Family」段\n  variants: {\n    neutral: { purpose: '一般訊息、系統公告;無情緒色、不掛 status icon(title-only icon-less 形態)' },\n    info: { purpose: '資訊提示(版本更新、流程說明);Info icon' },\n    success: { purpose: '操作成功確認;CircleCheck icon' },\n    warning: { purpose: '可恢復警告(未儲存變更、連線不穩);TriangleAlert icon' },\n    error: { purpose: '錯誤(操作失敗、權限不足);XCircle icon' },\n  },\n  sizes: {\n\n  },\n  states: ['default'], // 無互動 layout primitive(spec「邊界案例」:不擁有 disabled;hover / focus 屬內嵌 dismiss Button)\n  tokens: {\n    bg: [],\n    fg: ['text-error-text', 'text-fg-muted', 'text-fg-secondary', 'text-info-text', 'text-success-text', 'text-warning-text'],\n    ring: [],\n  },\n} as const\n\nexport { Notice }\n"],"names":["XIcon"],"mappings":"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"}

package/dist/components/NumberInput/index.d.ts

@@ -0,0 +1,2 @@
+export * from './number-input';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/NumberInput/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/NumberInput/index.ts"],"names":[],"mappings":"AAIA,cAAc,gBAAgB,CAAA"}

package/dist/components/NumberInput/index.js

@@ -0,0 +1,7 @@
+import { NumberInput, formatNumber, numberInputMeta } from "./number-input.js";
+export {
+  NumberInput,
+  formatNumber,
+  numberInputMeta
+};
+//# sourceMappingURL=index.js.map

package/dist/components/NumberInput/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/components/NumberInput/number-input.d.ts

@@ -14,15 +14,15 @@ export interface NumberFormatOptions {
     locale?: string;
 }
 declare function formatNumber(value: number | null | undefined, options?: NumberFormatOptions): string;
-export interface NumberInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'onChange' | 'type'>, Omit<VariantProps<typeof fieldWrapperStyles>, 'mode' | 'variant'>, NumberFormatOptions {
-    /** Field display mode */
+export interface NumberInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'defaultValue' | 'onChange' | 'type'>, Omit<VariantProps<typeof fieldWrapperStyles>, 'mode' | 'variant' | 'width'>, NumberFormatOptions {
+    /** Field mode */
     mode?: FieldMode;
     /**
      * Visual chrome(正交於 mode);Phase B1(2026-05-05)新增。
      * - `'default'`(預設)— 完整 Field wrapper chrome。
-     * - `'bare'` — 透明 variant,hover/focus 才 reveal(Toolbar inline / DataTable cell)。
+     * (2026-07-09 `bare` variant 退役;naked = cell-as-input substrate,@internal)
      *
-     * 透傳:在 `<Field variant="bare">` 內自動繼承 context.variant;per-prop override context。
+     * 透傳:在 `<Field variant="default">` 內自動繼承 context.variant;per-prop override context。
      */
     variant?: FieldVariant;
     /** Error 狀態（正交於 mode）。 */
@@ -46,7 +46,7 @@ export declare const numberInputMeta: {
     readonly family: 4;
     readonly variants: {};
     readonly sizes: {};
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly states: readonly ["default", "hover", "focus-visible", "disabled"];
     readonly tokens: {
         readonly bg: readonly [];
         readonly fg: readonly ["text-fg-disabled", "text-fg-muted"];

package/dist/components/NumberInput/number-input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"number-input.d.ts","sourceRoot":"","sources":["../../../src/components/NumberInput/number-input.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAA;AAC3F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uDAAuD,CAAA;AAC/F,OAAO,EAAE,kBAAkB,EAAkC,MAAM,gDAAgD,CAAA;AAMnH,MAAM,WAAW,mBAAmB;IAClC,WAAW;IACX,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oBAAoB;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,iBAAS,YAAY,CACnB,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,OAAO,GAAE,mBAAwB,GAChC,MAAM,CAOR;AAOD,MAAM,WAAW,gBACf,SAAQ,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC,EAC/F,IAAI,CAAC,YAAY,CAAC,OAAO,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,EACjE,mBAAmB;IACrB,yBAAyB;IACzB,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,0BAA0B;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS;IACT,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,WAAW;IACX,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IACzC,qDAAqD;IACrD,SAAS,CAAC,EAAE,kBAAkB,CAAA;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAKD,QAAA,MAAM,WAAW,2FA0GhB,CAAA;AAMD,eAAO,MAAM,eAAe;;;;;;;;;;;CAelB,CAAA;AAGV,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,CAAA"}
+{"version":3,"file":"number-input.d.ts","sourceRoot":"","sources":["../../../src/components/NumberInput/number-input.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAwB,MAAM,8CAA8C,CAAA;AACjH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uDAAuD,CAAA;AAC/F,OAAO,EAAE,kBAAkB,EAAmB,MAAM,gDAAgD,CAAA;AAOpG,MAAM,WAAW,mBAAmB;IAClC,WAAW;IACX,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oBAAoB;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,iBAAS,YAAY,CACnB,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,OAAO,GAAE,mBAAwB,GAChC,MAAM,CAmBR;AAOD,MAAM,WAAW,gBAIf,SAAQ,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,cAAc,GAAG,UAAU,GAAG,MAAM,CAAC,EAChH,IAAI,CAAC,YAAY,CAAC,OAAO,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,EAC3E,mBAAmB;IACrB,iBAAiB;IACjB,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,0BAA0B;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS;IACT,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,WAAW;IACX,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IACzC,qDAAqD;IACrD,SAAS,CAAC,EAAE,kBAAkB,CAAA;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAKD,QAAA,MAAM,WAAW,2FA2HhB,CAAA;AAMD,eAAO,MAAM,eAAe;;;;;;;;;;;CAgBlB,CAAA;AAGV,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,CAAA"}