@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

package/dist/components/Coachmark/coachmark.js

@@ -34,11 +34,13 @@ const Coachmark = React.forwardRef(
     ...props
   }, ref) => {
     const isSingleStep = isLastStep && !onPrev;
-    const showSkip = Boolean(onSkip) && !onPrev;
+    const showSkip = Boolean(onSkip) && !onPrev && !isSingleStep;
     const nextLabel = isSingleStep ? doneLabel : isLastStep ? "Done" : "Next";
     const hasFooterContent = Boolean(step || showSkip || onNext || onPrev);
     const stepText = step ? `${step.current} of ${step.total}` : null;
     const headerTitle = kind === "tips" || kind === "new-features" ? KIND_TITLE[kind] : kind;
+    const titleId = React.useId();
+    const dialogLabelledBy = headerTitle || title ? titleId : void 0;
     return /* @__PURE__ */ jsxs(Popover, { open, defaultOpen, onOpenChange, children: [
       /* @__PURE__ */ jsx(PopoverTrigger, { asChild: true, children }),
       /* @__PURE__ */ jsxs(
@@ -50,19 +52,21 @@ const Coachmark = React.forwardRef(
           sideOffset,
           className: cn("w-80 p-0 overflow-hidden", className),
           onOpenAutoFocus: (e) => e.preventDefault(),
+          "aria-labelledby": dialogLabelledBy,
+          "aria-label": dialogLabelledBy ? void 0 : "提示",
           ...props,
           children: [
             headerTitle && // Header title 走 `<PopoverTitle>` 共用 Popover typography canonical(text-body font-medium)。
             // **不 hideClose** — 對齊 Popover / Dialog / 所有 overlay 家族 canonical:header 必有 dismiss X
             // (user 可隨時關閉,跟 Skip / Done 是不同入口,canonical 重複不冗)
-            /* @__PURE__ */ jsx(PopoverHeader, { children: /* @__PURE__ */ jsx(PopoverTitle, { children: headerTitle }) }),
+            /* @__PURE__ */ jsx(PopoverHeader, { children: /* @__PURE__ */ jsx(PopoverTitle, { id: titleId, children: headerTitle }) }),
             image && /* @__PURE__ */ jsx(AspectRatio, { ratio: mediaRatio, className: "w-full overflow-hidden bg-muted", children: image }),
             (title || description) && // 對齊 Dialog / Popover canonical:body 左對齊(不中置)
             // Why: Coachmark 雖是 onboarding / feature discovery,但文字可讀性 > 視覺焦點;
             // 中文 / 長句中置會「每行起點不同」造成閱讀鋸齒,左對齊最穩。
             // 世界級參考:Notion / Linear / Figma onboarding tour 皆左對齊;Intercom Messenger 亦如是。
             /* @__PURE__ */ jsxs(PopoverBody, { className: "flex flex-col", children: [
-              title && /* @__PURE__ */ jsx("h3", { className: "text-body-lg font-medium text-foreground", children: title }),
+              title && /* @__PURE__ */ jsx("h3", { id: !headerTitle ? titleId : void 0, className: "text-body-lg font-medium text-foreground", children: title }),
               description && // title(body-lg 16)+ desc(body 14)→ reading-lg token(label tier 決定)
               // 對齊 Dialog / Sheet canonical;移除原 gap-1(4px)drift
               /* @__PURE__ */ jsx("p", { className: "mt-[var(--item-gap-label-desc-reading-lg)] text-body text-fg-secondary", children: description })
@@ -93,7 +97,8 @@ const coachmarkMeta = {
   // non-family composite / overlay / layout
   variants: {},
   sizes: {},
-  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  states: ["default"],
+  // 純 Popover composition — 無自有 hover / active / disabled 視覺(spec「邊界狀態」)
   tokens: {
     bg: ["bg-muted"],
     fg: ["text-fg-secondary", "text-foreground"],

package/dist/components/Coachmark/coachmark.js.map

@@ -1 +1 @@
-{"version":3,"file":"coachmark.js","sources":["../../../src/components/Coachmark/coachmark.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 { cn } from '@/lib/utils'\nimport {\n  Popover,\n  PopoverTrigger,\n  PopoverContent,\n  PopoverBody,\n  PopoverFooter,\n  PopoverHeader,\n  PopoverTitle,\n} from '@/design-system/components/Popover/popover'\nimport { Button } from '@/design-system/components/Button/button'\nimport { AspectRatio } from '@/design-system/components/AspectRatio/aspect-ratio'\nimport { OVERLAY_SIDE_OFFSET } from '@/design-system/tokens/elevation/overlay-geometry'\n\n/**\n * Coachmark — 功能介紹 / onboarding tour 的浮層卡片\n *\n * 世界級對照:Apple HIG「Coachmark」(Apple 命名原處)/ Material「Feature Discovery」/\n * Ant Design `<Tour>` / Shepherd.js / react-joyride / Intercom Product Tours。\n *\n * 本元件 = **Popover 的 composition pattern**,consume 相同 overlay-surface SSOT:\n *   - Header(可選,多步驟建議傳 `kind=\"tips\" | \"new-features\" | 自訂 title`,\n *     single-step 預設無 header 避免視覺過重)\n *   - Media 區(圖 / 截圖 / illustration,full-width 邊緣對齊,由 AspectRatio 管比例)\n *   - Body(SurfaceBody padding):title + description 左對齊\n *   - Footer(SurfaceFooter padding,但 justify-between):step 計數左 / actions 右\n *\n * ── 單 vs 多步驟 canonical(世界級行為規則) ──\n *   1. **Single step**(無 `onPrev` 且 `isLastStep`):CTA 文字 = `doneLabel ?? '知道了'`\n *      (Apple HIG / Intercom 慣例;不用 \"Next\" 因為沒有下一步)\n *   2. **Multi step 第一步**(無 `onPrev`,有 `onNext`):CTA = \"Next\",Skip 顯示\n *   3. **Multi step 中間 / 最後步**(有 `onPrev`):**Skip 不顯示**(使用者已投入進度,\n *      再給 Skip 會讓「放棄」入口與「回上一步」衝突 — Linear / Pendo / Shepherd.js\n *      同樣規則)。CTA = `isLastStep ? 'Done' : 'Next'`\n *   4. **不強制 autoFocus 任何按鈕** — Radix Popover 預設 focus 第一個 focusable\n *      (通常是 Prev 或 Skip),本元件不額外拉焦點到 Next,避免使用者以為一按 Enter\n *      就會推進(實際上可能還在讀 body)。想推進者 tab 到 Next 再 Enter。\n *\n * ── 為什麼 Body+Footer 消費 overlay-surface ──\n * 避免 padding token 漂移:Dialog / Popover / Coachmark 三者共用同一套 Header/Body/Footer\n * padding(px-loose / py-tight),改 Dialog 就三邊自動跟進。\n */\n\ninterface CoachmarkStep {\n  current: number\n  total: number\n}\n\nexport interface CoachmarkProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children' | 'title'> {\n  /** 控制顯示(controlled mode)*/\n  open?: boolean\n  /** 預設打開(uncontrolled initial state)— 2026-05-15 audit Dim 26 V1 fix per user verbatim「A:1」approval */\n  defaultOpen?: boolean\n  onOpenChange?: (open: boolean) => void\n  /** 觸發 anchor 元素。通常傳 trigger element;Coachmark 浮層會定位於此 */\n  children: React.ReactNode\n  /** 頂部 media 區(圖片 / illustration / video 等);不傳則無 media */\n  image?: React.ReactNode\n  /**\n   * Media 區域的長寬比(ratio = 寬 / 高)。預設 `16/9`(onboarding feature tour\n   * 世界級 convention — Intercom / Pendo / Shepherd.js)。其他常用:`4/3` 產品截圖 /\n   * `1/1` 方圖 / `3/4` 直式 portrait。消費獨立的 `AspectRatio` primitive 元件。\n   */\n  mediaRatio?: number\n  /**\n   * 頂部 header 類型(多步驟 tour 建議傳)。\n   * - `'tips'` → header title = \"使用技巧\"\n   * - `'new-features'` → header title = \"新功能介紹\"\n   * - `ReactNode` → 自訂 title(string / JSX)\n   * - undefined → 無 header(單步驟常用)\n   */\n  kind?: 'tips' | 'new-features' | React.ReactNode\n  /** 標題(bold) */\n  title?: React.ReactNode\n  /** 說明文字(normal weight,多行 OK) */\n  description?: React.ReactNode\n  /** 步驟計數(2 of 3);若需多步導覽 consumer 自行管理 current */\n  step?: CoachmarkStep\n  /** Skip 按鈕 callback;不傳則不顯示 Skip。多步驟中間 / 最後步自動隱藏(有 onPrev 時) */\n  onSkip?: () => void\n  /** Next 按鈕 callback;不傳則不顯示 Next */\n  onNext?: () => void\n  /** Previous 按鈕 callback(多步 tour 第 2+ 步顯示);不傳則不顯示 */\n  onPrev?: () => void\n  /**\n   * 最後一步 flag。影響 primary CTA 文字:\n   * - single step(無 onPrev 且 isLastStep):CTA = `doneLabel ?? '知道了'`\n   * - multi-step 最後步(有 onPrev 且 isLastStep):CTA = 'Done'\n   * - 其他:CTA = 'Next'\n   */\n  isLastStep?: boolean\n  /** 自訂單步驟完成 CTA 文字(預設 `'知道了'`)。僅 single-step 使用 */\n  doneLabel?: string\n  /** 浮層定位(對齊 Popover props) */\n  side?: 'top' | 'right' | 'bottom' | 'left'\n  align?: 'start' | 'center' | 'end'\n  sideOffset?: number\n  /** 外殼寬度(預設 w-80 = 320px,比一般 Popover 寬,因要放 media + 文字) */\n  className?: string\n}\n\n// i18n-allow: DS-internal kind → title 預設對照表;consumer 透過 `title` prop 直接覆寫\nconst KIND_TITLE: Record<'tips' | 'new-features', string> = {\n  tips: '使用技巧',\n  'new-features': '新功能介紹',\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst Coachmark = React.forwardRef<HTMLDivElement, CoachmarkProps>(\n  (\n    {\n      open,\n      defaultOpen,\n      onOpenChange,\n      children,\n      image,\n      mediaRatio = 16 / 9,\n      kind,\n      title,\n      description,\n      step,\n      onSkip,\n      onNext,\n      onPrev,\n      isLastStep = false,\n      doneLabel = '知道了', // i18n-allow: DS default; consumer override via doneLabel prop\n      side = 'bottom',\n      align = 'center',\n      sideOffset = OVERLAY_SIDE_OFFSET,\n      className,\n      ...props\n    },\n    ref,\n  ) => {\n    // 單/多步驟行為推導\n    const isSingleStep = isLastStep && !onPrev\n    const showSkip = Boolean(onSkip) && !onPrev   // canonical:有 onPrev → 不顯示 Skip\n    const nextLabel = isSingleStep ? doneLabel : isLastStep ? 'Done' : 'Next'\n\n    const hasFooterContent = Boolean(step || showSkip || onNext || onPrev)\n    const stepText = step ? `${step.current} of ${step.total}` : null\n\n    // Header title 解析\n    const headerTitle =\n      kind === 'tips' || kind === 'new-features'\n        ? KIND_TITLE[kind as 'tips' | 'new-features']\n        : kind\n\n    return (\n      <Popover open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>\n        <PopoverTrigger asChild>{children}</PopoverTrigger>\n        <PopoverContent\n          ref={ref}\n          side={side}\n          align={align}\n          sideOffset={sideOffset}\n          className={cn('w-80 p-0 overflow-hidden', className)}\n          // 禁止 Radix 開啟時自動 focus 第一個 focusable(預設會 focus Prev / Skip / Next),\n          // Coachmark 的 CTA 不該被 auto-focus 偷觸發(user 可能還在讀 body,按 Enter 就推進)。\n          // 想推進的 user 自己 tab 到 CTA 即可。\n          onOpenAutoFocus={(e) => e.preventDefault()}\n          {...props}\n        >\n          {headerTitle && (\n            // Header title 走 `<PopoverTitle>` 共用 Popover typography canonical(text-body font-medium)。\n            // **不 hideClose** — 對齊 Popover / Dialog / 所有 overlay 家族 canonical:header 必有 dismiss X\n            // (user 可隨時關閉,跟 Skip / Done 是不同入口,canonical 重複不冗)\n            <PopoverHeader>\n              <PopoverTitle>{headerTitle}</PopoverTitle>\n            </PopoverHeader>\n          )}\n\n          {image && (\n            <AspectRatio ratio={mediaRatio} className=\"w-full overflow-hidden bg-muted\">\n              {image}\n            </AspectRatio>\n          )}\n\n          {(title || description) && (\n            // 對齊 Dialog / Popover canonical:body 左對齊(不中置)\n            // Why: Coachmark 雖是 onboarding / feature discovery,但文字可讀性 > 視覺焦點;\n            // 中文 / 長句中置會「每行起點不同」造成閱讀鋸齒,左對齊最穩。\n            // 世界級參考:Notion / Linear / Figma onboarding tour 皆左對齊;Intercom Messenger 亦如是。\n            <PopoverBody className=\"flex flex-col\">\n              {title && (\n                <h3 className=\"text-body-lg font-medium text-foreground\">{title}</h3>\n              )}\n              {description && (\n                // title(body-lg 16)+ desc(body 14)→ reading-lg token(label tier 決定)\n                // 對齊 Dialog / Sheet canonical;移除原 gap-1(4px)drift\n                <p className=\"mt-[var(--item-gap-label-desc-reading-lg)] text-body text-fg-secondary\">{description}</p>\n              )}\n            </PopoverBody>\n          )}\n\n          {hasFooterContent && (\n            // 專屬 Coachmark canonical:footer 無上方分隔線(media + body + footer 視覺一氣呵成,\n            // 不像 Dialog 需要 header/footer 分隔強化結構)。override SurfaceFooter default border-t\n            <PopoverFooter className=\"justify-between !border-t-0\">\n              {stepText ? (\n                // step 文字走 text-body 跟 body content 字體一致\n                <span className=\"text-body text-fg-secondary tabular-nums\">\n                  {stepText}\n                </span>\n              ) : (\n                <span aria-hidden /> /* 保持 justify-between space */\n              )}\n              <div className=\"flex items-center gap-2\">\n                {onPrev && (\n                  <Button variant=\"tertiary\" size=\"sm\" onClick={onPrev}>\n                    Previous\n                  </Button>\n                )}\n                {showSkip && (\n                  <Button variant=\"tertiary\" size=\"sm\" onClick={onSkip}>\n                    Skip\n                  </Button>\n                )}\n                {onNext && (\n                  <Button variant=\"primary\" size=\"sm\" onClick={onNext}>\n                    {nextLabel}\n                  </Button>\n                )}\n              </div>\n            </PopoverFooter>\n          )}\n        </PopoverContent>\n      </Popover>\n    )\n  },\n)\nCoachmark.displayName = 'Coachmark'\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 coachmarkMeta = {\n  component: 'Coachmark',\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: ['bg-muted'],\n    fg: ['text-fg-secondary', 'text-foreground'],\n    ring: [],\n  },\n} as const\n\nexport { Coachmark }\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"coachmark.js","sources":["../../../src/components/Coachmark/coachmark.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 { cn } from '@/lib/utils'\nimport {\n  Popover,\n  PopoverTrigger,\n  PopoverContent,\n  PopoverBody,\n  PopoverFooter,\n  PopoverHeader,\n  PopoverTitle,\n} from '@/design-system/components/Popover/popover'\nimport { Button } from '@/design-system/components/Button/button'\nimport { AspectRatio } from '@/design-system/components/AspectRatio/aspect-ratio'\nimport { OVERLAY_SIDE_OFFSET } from '@/design-system/tokens/elevation/overlay-geometry'\n\n/**\n * Coachmark — 功能介紹 / onboarding tour 的浮層卡片\n *\n * 世界級對照:Apple HIG「Coachmark」(Apple 命名原處)/ Material「Feature Discovery」/\n * Ant Design `<Tour>` / Shepherd.js / react-joyride / Intercom Product Tours。\n *\n * 本元件 = **Popover 的 composition pattern**,consume 相同 overlay-surface SSOT:\n *   - Header(可選,多步驟建議傳 `kind=\"tips\" | \"new-features\" | 自訂 title`,\n *     single-step 預設無 header 避免視覺過重)\n *   - Media 區(圖 / 截圖 / illustration,full-width 邊緣對齊,由 AspectRatio 管比例)\n *   - Body(SurfaceBody padding):title + description 左對齊\n *   - Footer(SurfaceFooter padding,但 justify-between):step 計數左 / actions 右\n *\n * ── 單 vs 多步驟 canonical(世界級行為規則) ──\n *   1. **Single step**(無 `onPrev` 且 `isLastStep`):CTA 文字 = `doneLabel ?? '知道了'`\n *      (Apple HIG / Intercom 慣例;不用 \"Next\" 因為沒有下一步)\n *   2. **Multi step 第一步**(無 `onPrev`,有 `onNext`):CTA = \"Next\",Skip 顯示\n *   3. **Multi step 中間 / 最後步**(有 `onPrev`):**Skip 不顯示**(使用者已投入進度,\n *      再給 Skip 會讓「放棄」入口與「回上一步」衝突 — Linear / Pendo / Shepherd.js\n *      同樣規則)。CTA = `isLastStep ? 'Done' : 'Next'`\n *   4. **抑制開啟時的自動 focus** — `onOpenAutoFocus` preventDefault,連 Radix 預設\n *      focus 第一個 focusable 也一併抑制(焦點停在 trigger),避免使用者還在讀 body 時\n *      按 Enter 誤推進。想推進者自行 tab 到 CTA 再 Enter(對齊 spec「A11y 預設」)。\n *\n * ── 為什麼 Body+Footer 消費 overlay-surface ──\n * 避免 padding token 漂移:Dialog / Popover / Coachmark 三者共用同一套 Header/Body/Footer\n * padding(px-loose / py-tight),改 Dialog 就三邊自動跟進。\n */\n\ninterface CoachmarkStep {\n  current: number\n  total: number\n}\n\nexport interface CoachmarkProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children' | 'title'> {\n  /** 控制顯示(controlled mode)*/\n  open?: boolean\n  /** 預設打開(uncontrolled initial state)— 2026-05-15 audit Dim 26 V1 fix per user verbatim「A:1」approval */\n  defaultOpen?: boolean\n  onOpenChange?: (open: boolean) => void\n  /** 觸發 anchor 元素。通常傳 trigger element;Coachmark 浮層會定位於此 */\n  children: React.ReactNode\n  /** 頂部 media 區(圖片 / illustration / video 等);不傳則無 media */\n  image?: React.ReactNode\n  /**\n   * Media 區域的長寬比(ratio = 寬 / 高)。預設 `16/9`(onboarding feature tour\n   * 世界級 convention — Intercom / Pendo / Shepherd.js)。其他常用:`4/3` 產品截圖 /\n   * `1/1` 方圖 / `3/4` 直式 portrait。消費獨立的 `AspectRatio` primitive 元件。\n   */\n  mediaRatio?: number\n  /**\n   * 頂部 header 類型(多步驟 tour 建議傳)。\n   * - `'tips'` → header title = \"使用技巧\"\n   * - `'new-features'` → header title = \"新功能介紹\"\n   * - `ReactNode` → 自訂 title(string / JSX)\n   * - undefined → 無 header(單步驟常用)\n   */\n  kind?: 'tips' | 'new-features' | React.ReactNode\n  /** 標題(bold) */\n  title?: React.ReactNode\n  /** 說明文字(normal weight,多行 OK) */\n  description?: React.ReactNode\n  /** 步驟計數(2 of 3);若需多步導覽 consumer 自行管理 current */\n  step?: CoachmarkStep\n  /** Skip 按鈕 callback;不傳則不顯示 Skip。多步驟中間 / 最後步自動隱藏(有 onPrev 時) */\n  onSkip?: () => void\n  /** Next 按鈕 callback;不傳則不顯示 Next */\n  onNext?: () => void\n  /** Previous 按鈕 callback(多步 tour 第 2+ 步顯示);不傳則不顯示 */\n  onPrev?: () => void\n  /**\n   * 最後一步 flag。影響 primary CTA 文字:\n   * - single step(無 onPrev 且 isLastStep):CTA = `doneLabel ?? '知道了'`\n   * - multi-step 最後步(有 onPrev 且 isLastStep):CTA = 'Done'\n   * - 其他:CTA = 'Next'\n   */\n  isLastStep?: boolean\n  /** 自訂單步驟完成 CTA 文字(預設 `'知道了'`)。僅 single-step 使用 */\n  doneLabel?: string\n  /** 浮層定位(對齊 Popover props) */\n  side?: 'top' | 'right' | 'bottom' | 'left'\n  align?: 'start' | 'center' | 'end'\n  sideOffset?: number\n  /** 外殼寬度(預設 w-80 = 320px,比一般 Popover 寬,因要放 media + 文字) */\n  className?: string\n}\n\n// i18n-allow: DS-internal kind → title 預設對照表;consumer 透過 `title` prop 直接覆寫\nconst KIND_TITLE: Record<'tips' | 'new-features', string> = {\n  tips: '使用技巧',\n  'new-features': '新功能介紹',\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst Coachmark = React.forwardRef<HTMLDivElement, CoachmarkProps>(\n  (\n    {\n      open,\n      defaultOpen,\n      onOpenChange,\n      children,\n      image,\n      mediaRatio = 16 / 9,\n      kind,\n      title,\n      description,\n      step,\n      onSkip,\n      onNext,\n      onPrev,\n      isLastStep = false,\n      doneLabel = '知道了', // i18n-allow: DS default; consumer override via doneLabel prop\n      side = 'bottom',\n      align = 'center',\n      sideOffset = OVERLAY_SIDE_OFFSET,\n      className,\n      ...props\n    },\n    ref,\n  ) => {\n    // 單/多步驟行為推導\n    const isSingleStep = isLastStep && !onPrev\n    // canonical(spec.md CTA 語義表 L116):有 onPrev → 不顯示 Skip;**單步驟也不顯示 Skip**\n    // (單步「skip」與「知道了」語義重複 = 同一個關閉動作,雙關閉鍵造成困惑;對齊 Apple HIG / Intercom / Pendo 單步 tip 僅一個完成鍵)\n    const showSkip = Boolean(onSkip) && !onPrev && !isSingleStep\n    const nextLabel = isSingleStep ? doneLabel : isLastStep ? 'Done' : 'Next'\n\n    const hasFooterContent = Boolean(step || showSkip || onNext || onPrev)\n    const stepText = step ? `${step.current} of ${step.total}` : null\n\n    // Header title 解析\n    const headerTitle =\n      kind === 'tips' || kind === 'new-features'\n        ? KIND_TITLE[kind as 'tips' | 'new-features']\n        : kind\n\n    // 2026-05-31 #6:PopoverContent(role=dialog)需 accessible name。dialog aria-labelledby 接可見標題\n    // (優先 headerTitle 的 PopoverTitle,否則 body title 的 h3);皆無則 aria-label fallback。\n    const titleId = React.useId()\n    const dialogLabelledBy = (headerTitle || title) ? titleId : undefined\n\n    return (\n      <Popover open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>\n        <PopoverTrigger asChild>{children}</PopoverTrigger>\n        <PopoverContent\n          ref={ref}\n          side={side}\n          align={align}\n          sideOffset={sideOffset}\n          className={cn('w-80 p-0 overflow-hidden', className)}\n          // 禁止 Radix 開啟時自動 focus 第一個 focusable(預設會 focus Prev / Skip / Next),\n          // Coachmark 的 CTA 不該被 auto-focus 偷觸發(user 可能還在讀 body,按 Enter 就推進)。\n          // 想推進的 user 自己 tab 到 CTA 即可。\n          onOpenAutoFocus={(e) => e.preventDefault()}\n          aria-labelledby={dialogLabelledBy}\n          aria-label={dialogLabelledBy ? undefined : '提示'}\n          {...props}\n        >\n          {headerTitle && (\n            // Header title 走 `<PopoverTitle>` 共用 Popover typography canonical(text-body font-medium)。\n            // **不 hideClose** — 對齊 Popover / Dialog / 所有 overlay 家族 canonical:header 必有 dismiss X\n            // (user 可隨時關閉,跟 Skip / Done 是不同入口,canonical 重複不冗)\n            <PopoverHeader>\n              <PopoverTitle id={titleId}>{headerTitle}</PopoverTitle>\n            </PopoverHeader>\n          )}\n\n          {image && (\n            <AspectRatio ratio={mediaRatio} className=\"w-full overflow-hidden bg-muted\">\n              {image}\n            </AspectRatio>\n          )}\n\n          {(title || description) && (\n            // 對齊 Dialog / Popover canonical:body 左對齊(不中置)\n            // Why: Coachmark 雖是 onboarding / feature discovery,但文字可讀性 > 視覺焦點;\n            // 中文 / 長句中置會「每行起點不同」造成閱讀鋸齒,左對齊最穩。\n            // 世界級參考:Notion / Linear / Figma onboarding tour 皆左對齊;Intercom Messenger 亦如是。\n            <PopoverBody className=\"flex flex-col\">\n              {title && (\n                <h3 id={!headerTitle ? titleId : undefined} className=\"text-body-lg font-medium text-foreground\">{title}</h3>\n              )}\n              {description && (\n                // title(body-lg 16)+ desc(body 14)→ reading-lg token(label tier 決定)\n                // 對齊 Dialog / Sheet canonical;移除原 gap-1(4px)drift\n                <p className=\"mt-[var(--item-gap-label-desc-reading-lg)] text-body text-fg-secondary\">{description}</p>\n              )}\n            </PopoverBody>\n          )}\n\n          {hasFooterContent && (\n            // 專屬 Coachmark canonical:footer 無上方分隔線(media + body + footer 視覺一氣呵成,\n            // 不像 Dialog 需要 header/footer 分隔強化結構)。override SurfaceFooter default border-t\n            <PopoverFooter className=\"justify-between !border-t-0\">\n              {stepText ? (\n                // step 文字走 text-body 跟 body content 字體一致\n                <span className=\"text-body text-fg-secondary tabular-nums\">\n                  {stepText}\n                </span>\n              ) : (\n                <span aria-hidden /> /* 保持 justify-between space */\n              )}\n              <div className=\"flex items-center gap-2\">\n                {onPrev && (\n                  <Button variant=\"tertiary\" size=\"sm\" onClick={onPrev}>\n                    Previous\n                  </Button>\n                )}\n                {showSkip && (\n                  <Button variant=\"tertiary\" size=\"sm\" onClick={onSkip}>\n                    Skip\n                  </Button>\n                )}\n                {onNext && (\n                  <Button variant=\"primary\" size=\"sm\" onClick={onNext}>\n                    {nextLabel}\n                  </Button>\n                )}\n              </div>\n            </PopoverFooter>\n          )}\n        </PopoverContent>\n      </Popover>\n    )\n  },\n)\nCoachmark.displayName = 'Coachmark'\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 coachmarkMeta = {\n  component: 'Coachmark',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default'], // 純 Popover composition — 無自有 hover / active / disabled 視覺(spec「邊界狀態」)\n  tokens: {\n    bg: ['bg-muted'],\n    fg: ['text-fg-secondary', 'text-foreground'],\n    ring: [],\n  },\n} as const\n\nexport { Coachmark }\n"],"names":[],"mappings":"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"}

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

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

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

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

package/dist/components/Coachmark/index.js

@@ -0,0 +1,6 @@
+import { Coachmark, coachmarkMeta } from "./coachmark.js";
+export {
+  Coachmark,
+  coachmarkMeta
+};
+//# sourceMappingURL=index.js.map

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

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

package/dist/components/Combobox/combobox.d.ts

@@ -6,8 +6,8 @@ import { type SelectMenuOption } from '../../components/SelectMenu/select-menu';
  * SelectMenuOption(primitive SSOT)** — 避免重蹈先前 PeoplePicker 改壞的 wrapper schema drift。
  *
  * Why `extends SelectMenuOption`(per user 「全盤檢查避免下次又改壞或是偏移」要求):
- *   原 `interface SelectOption { value: string; label: string }` 是 weak schema,跟 Select 的
- *   `SelectOption`(同名)雙重宣告但欄位不同 → TypeScript 不抓(同名 interface 在不同 file
+ *   原 `interface ComboboxOption { value: string; label: string }` 是 weak schema,跟 Select 的
+ *   `ComboboxOption`(同名)雙重宣告但欄位不同 → TypeScript 不抓(同名 interface 在不同 file
  *   各 export,consumer import 到哪個版本看 import path)→ schema drift。
  *   PeoplePicker multi-mode 走 Combobox 路徑,dropdown menu rows lose avatar / description —
  *   user 看到「single mode 有 avatar / multi mode 沒 avatar」inconsistency。
@@ -19,7 +19,7 @@ import { type SelectMenuOption } from '../../components/SelectMenu/select-menu';
  * 對齊 Polaris ChoiceList / Material Autocomplete / Carbon Dropdown 的 wrapper-vs-primitive
  * schema-extension idiom。Hook `check_wrapper_primitive_schema_drift.sh`(M30 機械強制)。
  */
-export interface SelectOption extends SelectMenuOption {
+export interface ComboboxOption extends SelectMenuOption {
 }
 type ComboboxOverflowShape = 'circle' | 'tag';
 export interface ComboboxProps {
@@ -28,7 +28,7 @@ export interface ComboboxProps {
     variant?: FieldVariant;
     error?: boolean;
     size?: 'sm' | 'md' | 'lg';
-    options: SelectOption[];
+    options: ComboboxOption[];
     value?: string[];
     onChange?: (value: string[]) => void;
     placeholder?: string;
@@ -61,7 +61,7 @@ export interface ComboboxProps {
      * Selected tag pill 客製 render(2026-05-07 v15.5)。
      *
      * 設了 → 每個 selected tag pill 走 consumer 提供的 ReactNode(收 item={value, label}
-     * + onRemove,consumer 自己組 onDismiss);沒設 → 走預設 `<Tag>` text-only pill。
+     * + onRemove,consumer 自己組 onRemove);沒設 → 走預設 `<Tag>` text-only pill。
      *
      * 用例:PeoplePicker(multi)用此 slot 把 selected tag 換成 avatar + name pill,而非
      * 純文字 Tag。對齊 PeoplePicker = Combobox wrapper SSOT。
@@ -81,12 +81,15 @@ export interface ComboboxProps {
         label: string;
     }) => React.ReactNode;
     /**
+     * @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer hook)。
+     *
      * Optional class merged into each tag's outer measurement wrapper (2026-05-07 v15.13)。
      * Stack avatar 模式用此 hook point 達成 sibling-level overlap (`-ml-0.5`) + group selector
      * (`group/avatar`)— 既保留 Combobox 必要 measurement wrapper,又讓 dismiss/overlap 視覺生效。
      */
     tagWrapperClassName?: string;
-    /** 2026-05-16:overflow chip wrapper 套此 class(對齊 tagWrapperClassName)。Stack 模式
+    /** @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer hook)。
+     *  2026-05-16:overflow chip wrapper 套此 class(對齊 tagWrapperClassName)。Stack 模式
      *  pass `-ml-0.5 first:ml-0` 讓 chip 跟 avatar 同 overlap step,物理上 chip = 1 個 slot 不
      *  外加 24px。Default undefined = chip 不 overlap(text-tag mode 等)。*/
     overflowWrapperClassName?: string;
@@ -96,6 +99,8 @@ export interface ComboboxProps {
      * (CSS `gap` 套在 flex container 上會強制 sibling spacing,蓋過 negative margin)。
      * **Q2 known tradeoff**:0 後 useOverflowCount 仍按 wrapper.offsetWidth 累加(不含 overlap
      * 補償)→ +N 偏保守。當前接受;若需精準可 future 加 `overlapPx` 補償邏輯。
+     *
+     * @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer hook)。
      */
     tagAreaGapPx?: number;
     /**
@@ -105,10 +110,12 @@ export interface ComboboxProps {
      * paddingLeft - paddingRight` 自動 include**(`parseFloat(cs.paddingLeft)` 從 container CSS 抓)
      * → width calc 不漂移,無 side-effect。
      *
+     * @internal PeoplePicker stack wrapper 內部協議 — 目前無 active consumer(PeoplePicker 傳 undefined),保留供未來精準 padding;新 consumer 請先評估。
+     *
      * **2026-05-13 v2 deprecate path**:原 PeoplePicker pass `{8}` 假設「Combobox tagPadding=4px,4+8=12」
      * 但 `tagPadding[size]` 是 density-dependent calc `(field-height - icon-size) / 2`,只在 md size +
      * default density 才 = 4px;其他 size/density 漂 6/8px → 4+8=12 公式破。改 PeoplePicker 直接 inject
-     * `!px-3` className 到 Combobox Field wrapper(per people-picker.spec.md:94 v2),`tagAreaPaddingLeftPx`
+     * `!px-[var(--field-px)]` className 到 Combobox Field wrapper(per people-picker.spec.md:94 v2),`tagAreaPaddingLeftPx`
      * 走 undefined。Future 仍保留此 prop 給其他 consumer 精準調整 padding,但 PeoplePicker 已不再用。
      */
     tagAreaPaddingLeftPx?: number;
@@ -119,6 +126,8 @@ export interface ComboboxProps {
      */
     overflowShape?: ComboboxOverflowShape;
     /**
+     * @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer override)。
+     *
      * 2026-05-15 Bug 3 fix:override visible count via formula-based primitive(opt-in;default 走
      * DOM-based `useOverflowCount`)。PeoplePicker stack mode 用 `avatar-stack-overflow` primitive
      * deterministic formula 計算 visible count,forward 給 Combobox bypass DOM offsetWidth

package/dist/components/Combobox/combobox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["../../../src/components/Combobox/combobox.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAA;AAM3F,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,mDAAmD,CAAA;AAcrG;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAa,SAAQ,gBAAgB;CAErD;AAgLD,KAAK,qBAAqB,GAAG,QAAQ,GAAG,KAAK,CAAA;AA6I7C,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,uFAAuF;IACvF,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;IACpC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW;IACX,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;kGAE8F;IAC9F,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;gDAC4C;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,mFAAmF;IACnF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,KAAK,CAAC,SAAS,CAAA;IAC/F;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,KAAK,CAAC,SAAS,CAAA;IAC7E;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;sEAEkE;IAClE,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;;;;;OAYG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAA;IACrC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAsUD,QAAA,MAAM,QAAQ,sFAUb,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}
+{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["../../../src/components/Combobox/combobox.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAA;AAM3F,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,mDAAmD,CAAA;AAcrG;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;CAEvD;AAgLD,KAAK,qBAAqB,GAAG,QAAQ,GAAG,KAAK,CAAA;AA6I7C,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,uFAAuF;IACvF,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;IACpC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW;IACX,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;kGAE8F;IAC9F,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;gDAC4C;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,mFAAmF;IACnF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,KAAK,CAAC,SAAS,CAAA;IAC/F;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,KAAK,CAAC,SAAS,CAAA;IAC7E;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;sEAGkE;IAClE,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAA;IACrC;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAyWD,QAAA,MAAM,QAAQ,sFAab,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/Combobox/combobox.js

@@ -3,7 +3,7 @@ import * as React from "react";
 import { X, ChevronDown } from "lucide-react";
 import { cn } from "../../lib/utils.js";
 import { nakedCellRowModeAlign, fieldWrapperStyles, EMPTY_DISPLAY, fieldDisplayTextClass } from "../Field/field-wrapper.js";
-import { useFieldContext } from "../Field/field-context.js";
+import { useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldVariant, useResolvedFieldMode, useFieldContext, useResolvedFieldInvalid } from "../Field/field-context.js";
 import { Tag } from "../Tag/tag.js";
 import { ItemSuffix, ItemInlineAction, ICON_SIZE } from "../../patterns/element-anatomy/item-anatomy.js";
 import { OverflowIndicator } from "../OverflowIndicator/overflow-indicator.js";
@@ -141,7 +141,7 @@ function OverflowTagList({ containerRef, items, size, wrap, renderTag, renderHid
         tagEls.current[i] = el;
       }, className: cn("shrink-0 max-w-full", tagWrapperClassName), style: { zIndex: items.length - i }, children: renderTag(item, i) }, item.value)
     )),
-    /* @__PURE__ */ jsx("div", { ref: overflowEl, className: cn("shrink-0", overflowWrapperClassName), children: /* @__PURE__ */ jsx(OverflowIndicator, { count: overflow, shape: overflowShape, size, children: hiddenItems.map((item) => renderHiddenTag ? /* @__PURE__ */ jsx(React.Fragment, { children: renderHiddenTag(item) }, item.value) : /* @__PURE__ */ jsx(Tag, { size: "sm", onDismiss: onRemove ? () => onRemove(item.value) : void 0, children: item.label }, item.value)) }) }),
+    /* @__PURE__ */ jsx("div", { ref: overflowEl, className: cn("shrink-0", overflowWrapperClassName), children: /* @__PURE__ */ jsx(OverflowIndicator, { count: overflow, shape: overflowShape, size, children: hiddenItems.map((item) => renderHiddenTag ? /* @__PURE__ */ jsx(React.Fragment, { children: renderHiddenTag(item) }, item.value) : /* @__PURE__ */ jsx(Tag, { size: "sm", onRemove: onRemove ? () => onRemove(item.value) : void 0, children: item.label }, item.value)) }) }),
     trailing
   ] });
 }
@@ -188,6 +188,7 @@ function ReadonlyMultiSelect({
   const variant = variantProp ?? "default";
   const sz = size ?? "md";
   const iconSize = sz === "lg" ? 20 : 16;
+  const tagHeight = sz === "sm" ? 20 : 24;
   const containerRef = React.useRef(null);
   const hasTags = ((value == null ? void 0 : value.length) ?? 0) > 0;
   if (resolvedMode === "display") {
@@ -207,7 +208,7 @@ function ReadonlyMultiSelect({
       }
     );
   }
-  return /* @__PURE__ */ jsx(
+  return /* @__PURE__ */ jsxs(
     "div",
     {
       ref: containerRef,
@@ -217,27 +218,33 @@ function ReadonlyMultiSelect({
         // 2026-05-18 #6A Round 1 Step 1/4(per user 拍板「決策6選a」+ codex M31 Step 5 verdict cite combobox.tsx:451):
         // readonly/disabled path 對齊 L293 display wrapper 已 ship 的 overflow-hidden fix。
         // M10 propagation:原 overflow-visible 讓 readonly tag 越界蓋 indicator,跟 display 不對稱。
-        wrap ? "flex-wrap py-1" : "overflow-hidden",
+        // 2026-06-27 對齊 edit path(L598-617):wrap 時 items-start + chevron self-start/tagHeight 鎖第一行;
+        // paddingRight: var(--field-px) re-assert 右緣 12px(tagPadding 對稱 calc 會吃掉右緣,跟 edit 一致)。
+        wrap ? "flex-wrap items-start py-1" : "overflow-hidden",
         className
       ),
-      style: { gap: GAP, ...wrap ? { height: "auto" } : void 0 },
+      style: { gap: GAP, paddingRight: "var(--field-px)", ...wrap ? { height: "auto" } : void 0 },
       "data-field-mode": resolvedMode,
-      children: hasTags ? /* @__PURE__ */ jsx(
-        ComboboxTagStack,
-        {
-          value,
-          options,
-          tagSize: sz,
-          wrap,
-          containerRef,
-          disabled: resolvedMode === "disabled"
-        }
-      ) : /* @__PURE__ */ jsx("span", { className: "text-fg-muted", children: EMPTY_DISPLAY })
+      "aria-disabled": resolvedMode === "disabled" ? true : void 0,
+      children: [
+        hasTags ? /* @__PURE__ */ jsx(
+          ComboboxTagStack,
+          {
+            value,
+            options,
+            tagSize: sz,
+            wrap,
+            containerRef,
+            disabled: resolvedMode === "disabled"
+          }
+        ) : /* @__PURE__ */ jsx("span", { className: "text-fg-muted", children: EMPTY_DISPLAY }),
+        (variant === "naked" ? !!showDisplayEndIcon : resolvedMode === "disabled") && /* @__PURE__ */ jsx(ItemSuffix, { className: cn("pointer-events-none", wrap && "self-start"), style: wrap ? { height: tagHeight } : void 0, children: /* @__PURE__ */ jsx(ChevronDown, { size: iconSize, className: cn("shrink-0", resolvedMode === "disabled" ? "text-fg-disabled" : "text-fg-muted"), "aria-hidden": true }) })
+      ]
     }
   );
 }
 function NativeCombobox({
-  mode = "edit",
+  mode,
   variant: variantProp,
   error = false,
   size = "md",
@@ -246,21 +253,23 @@ function NativeCombobox({
   onChange,
   placeholder,
   className,
-  disabled,
+  disabled: disabledProp,
   wrap = false,
   clearable = false,
   showDisplayEndIcon = false,
   __triggerRef
 }) {
-  const fieldCtx = useFieldContext();
-  const variant = variantProp ?? (fieldCtx == null ? void 0 : fieldCtx.variant) ?? "default";
-  const resolvedMode = disabled ? "disabled" : mode;
+  const disabled = useResolvedFieldDisabled(disabledProp);
+  const variant = useResolvedFieldVariant(variantProp);
+  const resolvedMode = useResolvedFieldMode({ mode, disabled });
   const iconSize = getIconSize(size);
   const showClear = clearable && value.length > 0 && resolvedMode === "edit";
   const handleRemove = (v) => onChange == null ? void 0 : onChange(value.filter((x) => x !== v));
   const handleAdd = (v) => {
     if (!value.includes(v)) onChange == null ? void 0 : onChange([...value, v]);
   };
+  const selectRef = React.useRef(null);
+  const tagAreaRef = React.useRef(null);
   if (resolvedMode !== "edit") {
     return /* @__PURE__ */ jsx(ReadonlyMultiSelect, { mode: resolvedMode, variant, size, options, value, wrap, className, showDisplayEndIcon });
   }
@@ -269,8 +278,6 @@ function NativeCombobox({
     return { value: v, label: ((_a = options.find((o) => o.value === v)) == null ? void 0 : _a.label) ?? v };
   });
   const unselected = options.filter((o) => !value.includes(o.value));
-  const selectRef = React.useRef(null);
-  const tagAreaRef = React.useRef(null);
   const tagHeight = size === "sm" ? 20 : 24;
   const selectDropdown = unselected.length > 0 ? /* @__PURE__ */ jsxs(
     "select",
@@ -300,7 +307,7 @@ function NativeCombobox({
         error && ["border-error hover:border-error-hover", "focus-within:border-error focus-within:hover:border-error"],
         className
       ),
-      style: { paddingRight: "0.75rem", ...wrap ? { height: "auto" } : void 0 },
+      style: { paddingRight: "var(--field-px)", ...wrap ? { height: "auto" } : void 0 },
       "data-field-mode": "edit",
       "data-error": error ? "" : void 0,
       onClick: (e) => {
@@ -341,7 +348,7 @@ function NativeCombobox({
                       (_b = (_a = selectRef.current) == null ? void 0 : _a.showPicker) == null ? void 0 : _b.call(_a);
                       (_c = selectRef.current) == null ? void 0 : _c.focus();
                     },
-                    onDismiss: () => handleRemove(item.value),
+                    onRemove: () => handleRemove(item.value),
                     children: item.label
                   }
                 ),
@@ -374,7 +381,7 @@ function NativeCombobox({
   );
 }
 function CustomCombobox({
-  mode = "edit",
+  mode,
   variant: variantProp,
   error: errorProp = false,
   size = "md",
@@ -411,10 +418,10 @@ function CustomCombobox({
 }) {
   const tagAreaGap = tagAreaGapPx ?? GAP;
   const fieldCtx = useFieldContext();
-  const error = errorProp || ((fieldCtx == null ? void 0 : fieldCtx.invalid) ?? false);
-  const disabled = disabledProp ?? (fieldCtx == null ? void 0 : fieldCtx.disabled);
-  const resolvedMode = disabled ? "disabled" : mode;
-  const variant = variantProp ?? (fieldCtx == null ? void 0 : fieldCtx.variant) ?? "default";
+  const error = useResolvedFieldInvalid(errorProp);
+  const disabled = useResolvedFieldDisabled(disabledProp);
+  const resolvedMode = useResolvedFieldMode({ mode, disabled });
+  const variant = useResolvedFieldVariant(variantProp);
   const iconSize = getIconSize(size);
   const showClear = clearable && value.length > 0 && resolvedMode === "edit";
   const [open, setOpen] = React.useState(defaultOpen);
@@ -424,9 +431,6 @@ function CustomCombobox({
   React.useEffect(() => {
     if (!open) setSearch("");
   }, [open]);
-  if (resolvedMode !== "edit") {
-    return /* @__PURE__ */ jsx(ReadonlyMultiSelect, { mode: resolvedMode, variant, size, options, value, wrap, className, showDisplayEndIcon });
-  }
   const items = React.useMemo(
     () => value.map((v) => {
       var _a;
@@ -453,6 +457,9 @@ function CustomCombobox({
     })),
     [filteredOptions]
   );
+  if (resolvedMode !== "edit") {
+    return /* @__PURE__ */ jsx(ReadonlyMultiSelect, { mode: resolvedMode, variant, size, options, value, wrap, className, showDisplayEndIcon });
+  }
   const chevronEl = /* @__PURE__ */ jsx(ChevronDown, { size: iconSize, className: cn("shrink-0 text-fg-muted transition-transform", open && "rotate-180"), "aria-hidden": true });
   const trigger = /* @__PURE__ */ jsxs(
     "div",
@@ -461,6 +468,7 @@ function CustomCombobox({
       id: fieldCtx == null ? void 0 : fieldCtx.id,
       role: "combobox",
       "aria-expanded": open,
+      "aria-haspopup": "listbox",
       "aria-controls": listboxId,
       tabIndex: 0,
       "aria-label": ariaLabel,
@@ -478,9 +486,22 @@ function CustomCombobox({
         error && ["border-error hover:border-error-hover", "focus-within:border-error focus-within:hover:border-error"],
         className
       ),
-      style: { paddingRight: "0.75rem", ...wrap ? { height: "auto" } : void 0 },
+      style: { paddingRight: "var(--field-px)", ...wrap ? { height: "auto" } : void 0 },
       "data-field-mode": "edit",
       "data-error": error ? "" : void 0,
+      onKeyDown: (e) => {
+        if (e.key === "Enter" || e.key === " ") {
+          if (!open) {
+            e.preventDefault();
+            setOpen(true);
+          }
+        }
+        if (e.key === "ArrowDown" && !open) {
+          e.preventDefault();
+          setOpen(true);
+        }
+        if (e.key === "Escape") setOpen(false);
+      },
       children: [
         /* @__PURE__ */ jsx("div", { ref: tagAreaRef, className: cn("flex-1 min-w-0 flex items-center relative", nakedCellRowModeAlign, wrap ? "flex-wrap" : "overflow-hidden"), style: { gap: tagAreaGap, paddingLeft: tagAreaPaddingLeftPx }, children: value.length > 0 ? /* @__PURE__ */ jsx(
           OverflowTagList,
@@ -499,7 +520,7 @@ function CustomCombobox({
               {
                 size,
                 className: "shrink-0 relative z-10",
-                onDismiss: () => handleRemove(item.value),
+                onRemove: () => handleRemove(item.value),
                 children: item.label
               }
             ),
@@ -582,14 +603,28 @@ function CustomCombobox({
   );
 }
 const Combobox = React.forwardRef(
-  (props, ref) => {
+  ({ size: sizeProp, ...props }, ref) => {
+    const size = useResolvedFieldSize(sizeProp);
     const isMobile = useIsTouchDevice();
-    if (isMobile) return /* @__PURE__ */ jsx(NativeCombobox, { ...props, __triggerRef: ref });
-    return /* @__PURE__ */ jsx(CustomCombobox, { ...props, __triggerRef: ref });
+    if (isMobile) return /* @__PURE__ */ jsx(NativeCombobox, { ...props, size, __triggerRef: ref });
+    return /* @__PURE__ */ jsx(CustomCombobox, { ...props, size, __triggerRef: ref });
   }
 );
 Combobox.displayName = "Combobox";
+const comboboxMeta = {
+  component: "Combobox",
+  family: 4,
+  variants: {},
+  sizes: {},
+  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  tokens: {
+    bg: ["bg-disabled", "bg-transparent"],
+    fg: ["text-fg-disabled", "text-fg-muted"],
+    ring: []
+  }
+};
 export {
-  Combobox
+  Combobox,
+  comboboxMeta
 };
 //# sourceMappingURL=combobox.js.map