npm - @qijenchen/design-system - Versions diffs - 0.1.0-beta.61 → 0.1.0-beta.63 - Mend

@qijenchen/design-system 0.1.0-beta.61 → 0.1.0-beta.63

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (507) hide show

package/dist/components/Checkbox/checkbox.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"checkbox.js","sources":["../../../src/components/Checkbox/checkbox.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 * as CheckboxPrimitive from \"@radix-ui/react-checkbox\"\nimport { Check, Minus } from \"lucide-react\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\n\nimport { cn } from \"@/lib/utils\"\nimport type { FieldMode, FieldVariant } from \"@/design-system/components/Field/field-types\"\nimport { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode } from \"@/design-system/components/Field/field-context\"\nimport { SelectionItem } from \"@/design-system/components/SelectionControl/selection-item\"\nimport { CheckboxGroupContext } from \"./checkbox-group\"\n\n// ── Variants ────────────────────────────────────────────────────────────────\n// 三種尺寸（sm/md=16px, lg=20px），對齊 icon 系統與 SelectionItem。\n\nconst checkboxVariants = cva(\n [\n 'grid place-content-center shrink-0 rounded-md',\n 'border border-border bg-surface',\n 'transition-colors duration-150',\n 'hover:border-border-hover',\n 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',\n 'data-[state=checked]:bg-primary data-[state=checked]:text-on-emphasis data-[state=checked]:border-primary',\n 'data-[state=checked]:hover:bg-primary-hover data-[state=checked]:hover:border-primary-hover',\n 'data-[state=indeterminate]:bg-primary data-[state=indeterminate]:text-on-emphasis data-[state=indeterminate]:border-primary',\n 'data-[state=indeterminate]:hover:bg-primary-hover data-[state=indeterminate]:hover:border-primary-hover',\n 'disabled:cursor-not-allowed disabled:bg-disabled disabled:border-transparent disabled:hover:border-transparent',\n 'disabled:data-[state=checked]:bg-disabled disabled:data-[state=checked]:text-fg-disabled disabled:data-[state=checked]:border-transparent',\n 'disabled:data-[state=indeterminate]:bg-disabled disabled:data-[state=indeterminate]:text-fg-disabled disabled:data-[state=indeterminate]:border-transparent',\n // readOnly：鎖定互動但維持 checked/unchecked 視覺\n 'data-[readonly=true]:pointer-events-none data-[readonly=true]:cursor-default',\n 'data-[readonly=true]:hover:border-border',\n ],\n {\n variants: {\n size: {\n sm: 'h-4 w-4',\n md: 'h-4 w-4',\n lg: 'h-5 w-5',\n },\n },\n defaultVariants: {\n size: 'md',\n },\n }\n)\n\n// ── Check Icon Size ─────────────────────────────────────────────────────────\nconst checkIconSize: Record<string, number> = { sm: 12, md: 12, lg: 16 }\n\n// ── Check Icon Stroke Weight ────────────────────────────────────────────────\n// 16px 以下 icon 視覺不夠顯眼 → 用較粗 stroke 補償。Lucide 預設 strokeWidth=2 在\n// 12px 下 render 約 1px 線寬,視覺偏細;加粗到 3.5(render ≈ 1.75px)才有足夠視覺權重。\n// 16px 用 2.5(render ≈ 1.67px)讓 checked 態的 check icon 夠顯眼。\n//\n// 為什麼不是 3 / 2:本 session 實測 3 / 2 在 storybook 上兩個 size 的 render 線寬差僅\n// 0.17px(1.5 vs 1.33),使用者肉眼看不出差異(image #64 回報)。改為 3.5 / 2.5:\n// - md 12px × 3.5 → 1.75px 線寬\n// - lg 16px × 2.5 → 1.67px 線寬\n// 兩者仍接近但 md 的線寬絕對值跟 16px 預設(1.33)有更明顯差異,視覺上「小 check 更粗」。\n//\n// 世界級對照:iOS HIG / Material 3 / Polaris 的 checkmark 在 <16px 下皆加粗 compensate。\n// 為什麼不用 Lucide absoluteStrokeWidth:那保持「絕對 px 粗細」,我們反而要「小尺寸比例更粗」。\n//\n// Check 與 Minus(indeterminate)共用此規則;Switch 的 SPECS.checkStroke 採同樣值。\n// 2026-05-18 簡化 per user 視覺證「sm/md 3.5 vs lg 2.5 看不出差別」(image #64 + 2nd round\n// 圖一 video proof)+「做完」approval:\n// - 原 {3.5, 3.5, 2.5} → effective render thickness 1.75 / 1.75 / 1.67 = 跨 size 差 0.08px(視覺看不出)\n// - 改 {3, 3, 2.5} 保留 sm/md 小尺寸 legibility insurance(per iOS HIG / Material 3 cite)\n// + lg 仍稍粗於 Lucide default 2(保留 compensation 主旨,但不過度差異化)\nconst checkStrokeWidth: Record<string, number> = { sm: 3, md: 3, lg: 2.5 }\n\n// ── Types ───────────────────────────────────────────────────────────────────\n\nexport interface CheckboxProps\n extends React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>,\n VariantProps<typeof checkboxVariants> {\n /*\n Inline label。提供時 Checkbox 自動透過 SelectionItem 包裝，\n * 套用 text-body / text-foreground / disabled 色的 codified 樣式。\n * 在 <Field> context 內時此 prop 會被忽略（由 FieldLabel 接管）。\n /\n label?: React.ReactNode\n /\n Inline description（secondary 文字）。須與 label 搭配使用。\n * 套用 text-body / text-fg-secondary 樣式。\n * 在 <Field> context 內時此 prop 會被忽略（由 FieldDescription 接管）。\n /\n description?: React.ReactNode\n /\n readonly 模式：鎖定互動但維持 checked/unchecked 視覺正確。\n * 與 disabled 的差異：readonly 不降色（可讀），disabled 降色（弱化）。\n * 用於表單 readonly 呈現、DataTable cell 非編輯態。\n /\n readOnly?: boolean\n /\n Field mode(2026-05-05 Phase B3 align):\n * edit — 一般可互動 checkbox(預設)\n * display — 純展示:渲染 ✓ / —(無互動 primitive、無 input chrome);\n * 對齊 Carbon read-only / DataTable boolean cell 場景。取代既有 BooleanDisplay。\n * readonly — 同 readOnly prop:checkbox 視覺保留 + 鎖互動 + a11y readonly signal\n * disabled — 同 disabled prop:降色 + 鎖互動\n /\n mode?: FieldMode\n /\n Visual chrome — checkbox 本體無 input wrapper variant,本 prop 對 checkbox 主體無視覺影響;\n * 為對齊 Field 4-mode + chrome 透傳契約而保留(M19 一致性)。\n /\n variant?: FieldVariant\n}\n\n// ── Component ───────────────────────────────────────────────────────────────\n\nconst Checkbox = React.forwardRef<\n React.ElementRef<typeof CheckboxPrimitive.Root>,\n CheckboxProps\n>(\n (\n {\n className,\n size,\n label,\n description,\n readOnly = false,\n disabled,\n mode,\n // chrome 對 Checkbox 主體無視覺影響(無 input wrapper)— 接收純為 prop 一致性;destructure 防 leak 到 DOM。\n variant: _chrome,\n id: idProp,\n ...props\n },\n ref\n ) => {\n const sizeKey = size ?? 'md'\n const iconPx = checkIconSize[sizeKey]\n const iconStrokeWidth = checkStrokeWidth[sizeKey]\n\n // Field context:Checkbox 單獨塞進 Field(binary toggle)時,忽略自己的 label 讓 FieldLabel 接管\n // 2026-05-31 #35:hooks(useFieldContext / useContext / useId)必在任何 conditional return 前呼叫(Rules of Hooks)。\n // 原 mode='display' early return 寫在 hooks 之上 → runtime 切 mode 會 hook count 不一致 crash;已下移至 hooks 後。\n //\n // 例外:Checkbox 是 CheckboxGroup 的 child 時(multi-select 情境),每個 checkbox\n // 的 label 是它自己的選項名,FieldLabel 只是群組名稱 — 此時 label 必須保留,\n // 不能被 Field context 吞掉。AR50 的根因就是這個 branch 之前誤把 group 內的 checkbox\n // label 全清空,導致 sheet 內 3 個 checkbox 沒 label。\n const fieldCtx = useFieldContext()\n const checkboxGroupCtx = React.useContext(CheckboxGroupContext)\n const insideField = fieldCtx?.hasFieldWrapper === true\n const insideGroup = checkboxGroupCtx?.inGroup === true\n const shouldSuppressLabel = insideField && !insideGroup\n const effectiveLabel = shouldSuppressLabel ? undefined : label\n const effectiveDescription = shouldSuppressLabel ? undefined : description\n\n // Id 連結\n //\n // ── 2026-04-21 bug fix ──\n // 原本:`idProp ?? fieldCtx?.id ?? generatedId`。\n // 在 Field 內 fieldCtx.id 存在,CheckboxGroup 所有 children 共用同一個 id →\n // 每個 checkbox 的 `<label htmlFor={sameId}>` 全指向第一個 checkbox →\n // 點任何 label 都只開關第一個 checkbox(real bug)*。\n //\n // 修法:group 內的 checkbox 強制用 generatedId(唯一),不沿用 Field id;\n // solo in Field(binary toggle)才沿用 fieldCtx.id 讓 FieldLabel htmlFor 生效。\n const generatedId = React.useId()\n const inputId = idProp ?? (insideGroup ? generatedId : (fieldCtx?.id ?? generatedId))\n\n // 2026-06-08 SSOT cascade:disabled + mode 經 resolver hook(原 raw prop → <Field disabled>/<Field mode=\"display\"> 漏 cascade)\n const resolvedDisabled = useResolvedFieldDisabled(disabled)\n const resolvedMode = useResolvedFieldMode({ mode, disabled, readOnly })\n const effectiveReadOnly = readOnly \|\| resolvedMode === 'readonly'\n\n // ── mode='display'(下移至所有 hooks 之後,per #35 Rules of Hooks)──────────\n // 純展示模式:無互動 primitive、渲染 ✓ / —(checked=true → ✓ / 其他 → —)。取代 BooleanDisplay。\n if (resolvedMode === 'display') {\n const isChecked = props.checked === true\n return isChecked\n ? <span className=\"text-foreground\">✓</span>\n : <span className=\"text-fg-muted\">—</span>\n }\n\n const rootEl = (\n <CheckboxPrimitive.Root\n id={inputId}\n ref={ref}\n disabled={resolvedDisabled}\n aria-readonly={effectiveReadOnly \|\| undefined}\n data-readonly={effectiveReadOnly \|\| undefined}\n tabIndex={effectiveReadOnly ? -1 : undefined}\n aria-describedby={fieldCtx?.descriptionId}\n className={cn(checkboxVariants({ size }), className)}\n {...props}\n >\n <CheckboxPrimitive.Indicator className=\"grid place-content-center text-current\">\n {props.checked === 'indeterminate'\n ? <Minus style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />\n : <Check style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />\n }\n </CheckboxPrimitive.Indicator>\n </CheckboxPrimitive.Root>\n )\n\n // 無 label → 只渲染 checkbox 本體\n if (effectiveLabel == null) return rootEl\n\n // 有 label → 透過 SelectionItem 包裝（control 在左、label+description 在右）\n return (\n <SelectionItem\n control={rootEl}\n label={effectiveLabel}\n description={effectiveDescription}\n htmlFor={inputId}\n disabled={resolvedDisabled}\n size={sizeKey}\n />\n )\n }\n)\nCheckbox.displayName = CheckboxPrimitive.Root.displayName\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 checkboxMeta = {\n component: 'Checkbox',\n family: null, // self-contained primitive(對齊 spec frontmatter self-contained + body L31;非 Family 4)\n variants: {\n\n },\n sizes: {\n sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },\n md: { fieldHeight: 32, iconSize: 16, typography: 'body' },\n lg: { fieldHeight: 36, iconSize: 20, typography: 'body' },\n },\n states: ['default', 'hover', 'focus-visible', 'disabled'],\n tokens: {\n bg: ['bg-disabled', 'bg-primary', 'bg-primary-hover', 'bg-surface'],\n fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],\n ring: ['ring-ring'],\n },\n defaultSize: 'md',\n} as const\n\nexport { Checkbox, checkboxVariants }\n"],"names":[],"mappings":"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"}
1	+ {"version":3,"file":"checkbox.js","sources":["../../../src/components/Checkbox/checkbox.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 * as CheckboxPrimitive from \"@radix-ui/react-checkbox\"\nimport { Check, Minus } from \"lucide-react\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\n\nimport { cn } from \"@/lib/utils\"\nimport type { FieldMode, FieldVariant } from \"@/design-system/components/Field/field-types\"\nimport { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode } from \"@/design-system/components/Field/field-context\"\nimport { SelectionItem } from \"@/design-system/components/SelectionControl/selection-item\"\nimport type { LucideIcon } from \"lucide-react\"\nimport type { AvatarData } from \"@/design-system/components/Avatar/avatar\"\nimport { CheckboxGroupContext } from \"./checkbox-group\"\n\n// ── Variants ────────────────────────────────────────────────────────────────\n// 三種尺寸（sm/md=16px, lg=20px），對齊 icon 系統與 SelectionItem。\n\nconst checkboxVariants = cva(\n [\n 'grid place-content-center shrink-0 rounded-md',\n 'border border-border bg-surface',\n 'transition-colors duration-150',\n 'hover:border-border-hover',\n 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',\n 'data-[state=checked]:bg-primary data-[state=checked]:text-on-emphasis data-[state=checked]:border-primary',\n 'data-[state=checked]:hover:bg-primary-hover data-[state=checked]:hover:border-primary-hover',\n 'data-[state=indeterminate]:bg-primary data-[state=indeterminate]:text-on-emphasis data-[state=indeterminate]:border-primary',\n 'data-[state=indeterminate]:hover:bg-primary-hover data-[state=indeterminate]:hover:border-primary-hover',\n 'disabled:cursor-not-allowed disabled:bg-disabled disabled:border-transparent disabled:hover:border-transparent',\n 'disabled:data-[state=checked]:bg-disabled disabled:data-[state=checked]:text-fg-disabled disabled:data-[state=checked]:border-transparent',\n 'disabled:data-[state=indeterminate]:bg-disabled disabled:data-[state=indeterminate]:text-fg-disabled disabled:data-[state=indeterminate]:border-transparent',\n // readOnly：鎖定互動但維持 checked/unchecked 視覺\n 'data-[readonly=true]:pointer-events-none data-[readonly=true]:cursor-default',\n 'data-[readonly=true]:hover:border-border',\n ],\n {\n variants: {\n size: {\n sm: 'h-4 w-4',\n md: 'h-4 w-4',\n lg: 'h-5 w-5',\n },\n },\n defaultVariants: {\n size: 'md',\n },\n }\n)\n\n// ── Check Icon Size ─────────────────────────────────────────────────────────\nconst checkIconSize: Record<string, number> = { sm: 12, md: 12, lg: 16 }\n\n// ── Check Icon Stroke Weight ────────────────────────────────────────────────\n// 16px 以下 icon 視覺不夠顯眼 → 用較粗 stroke 補償。Lucide 預設 strokeWidth=2 在\n// 12px 下 render 約 1px 線寬,視覺偏細;加粗到 3.5(render ≈ 1.75px)才有足夠視覺權重。\n// 16px 用 2.5(render ≈ 1.67px)讓 checked 態的 check icon 夠顯眼。\n//\n// 為什麼不是 3 / 2:本 session 實測 3 / 2 在 storybook 上兩個 size 的 render 線寬差僅\n// 0.17px(1.5 vs 1.33),使用者肉眼看不出差異(image #64 回報)。改為 3.5 / 2.5:\n// - md 12px × 3.5 → 1.75px 線寬\n// - lg 16px × 2.5 → 1.67px 線寬\n// 兩者仍接近但 md 的線寬絕對值跟 16px 預設(1.33)有更明顯差異,視覺上「小 check 更粗」。\n//\n// 世界級對照:iOS HIG / Material 3 / Polaris 的 checkmark 在 <16px 下皆加粗 compensate。\n// 為什麼不用 Lucide absoluteStrokeWidth:那保持「絕對 px 粗細」,我們反而要「小尺寸比例更粗」。\n//\n// Check 與 Minus(indeterminate)共用此規則;Switch 的 SPECS.checkStroke 採同樣值。\n// 2026-05-18 簡化 per user 視覺證「sm/md 3.5 vs lg 2.5 看不出差別」(image #64 + 2nd round\n// 圖一 video proof)+「做完」approval:\n// - 原 {3.5, 3.5, 2.5} → effective render thickness 1.75 / 1.75 / 1.67 = 跨 size 差 0.08px(視覺看不出)\n// - 改 {3, 3, 2.5} 保留 sm/md 小尺寸 legibility insurance(per iOS HIG / Material 3 cite)\n// + lg 仍稍粗於 Lucide default 2(保留 compensation 主旨,但不過度差異化)\nconst checkStrokeWidth: Record<string, number> = { sm: 3, md: 3, lg: 2.5 }\n\n// ── Types ───────────────────────────────────────────────────────────────────\n\nexport interface CheckboxProps\n extends React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>,\n VariantProps<typeof checkboxVariants> {\n /*\n Inline label。提供時 Checkbox 自動透過 SelectionItem 包裝，\n * 套用 text-body / text-foreground / disabled 色的 codified 樣式。\n * 在 <Field> context 內時此 prop 會被忽略（由 FieldLabel 接管）。\n /\n label?: React.ReactNode\n /\n Inline description（secondary 文字）。須與 label 搭配使用。\n * 套用 text-body / text-fg-secondary 樣式。\n * 在 <Field> context 內時此 prop 會被忽略（由 FieldDescription 接管）。\n /\n description?: React.ReactNode\n /* 可選左側 icon(label 前)— 2026-06-12 M30 修:轉發 SelectionItem 既有 canonical 槽(selection-item.tsx jsDoc 為 SSOT;與 avatar 互斥)/\n icon?: LucideIcon\n /* 可選左側 avatar(label 前)— 同上,SelectionItem 槽轉發 /\n avatar?: AvatarData\n /\n readonly 模式：鎖定互動但維持 checked/unchecked 視覺正確。\n * 與 disabled 的差異：readonly 不降色（可讀），disabled 降色（弱化）。\n * 用於表單 readonly 呈現、DataTable cell 非編輯態。\n /\n readOnly?: boolean\n /\n Field mode(2026-05-05 Phase B3 align):\n * edit — 一般可互動 checkbox(預設)\n * display — 純展示:渲染 ✓ / —(無互動 primitive、無 input chrome);\n * 對齊 Carbon read-only / DataTable boolean cell 場景。取代既有 BooleanDisplay。\n * readonly — 同 readOnly prop:checkbox 視覺保留 + 鎖互動 + a11y readonly signal\n * disabled — 同 disabled prop:降色 + 鎖互動\n /\n mode?: FieldMode\n /\n Visual chrome — checkbox 本體無 input wrapper variant,本 prop 對 checkbox 主體無視覺影響;\n * 為對齊 Field 4-mode + chrome 透傳契約而保留(M19 一致性)。\n /\n variant?: FieldVariant\n}\n\n// ── Component ───────────────────────────────────────────────────────────────\n\nconst Checkbox = React.forwardRef<\n React.ElementRef<typeof CheckboxPrimitive.Root>,\n CheckboxProps\n>(\n (\n {\n className,\n size,\n label,\n icon,\n avatar,\n description,\n readOnly = false,\n disabled,\n mode,\n // chrome 對 Checkbox 主體無視覺影響(無 input wrapper)— 接收純為 prop 一致性;destructure 防 leak 到 DOM。\n variant: _chrome,\n id: idProp,\n ...props\n },\n ref\n ) => {\n const sizeKey = size ?? 'md'\n const iconPx = checkIconSize[sizeKey]\n const iconStrokeWidth = checkStrokeWidth[sizeKey]\n\n // Field context:Checkbox 單獨塞進 Field(binary toggle)時,忽略自己的 label 讓 FieldLabel 接管\n // 2026-05-31 #35:hooks(useFieldContext / useContext / useId)必在任何 conditional return 前呼叫(Rules of Hooks)。\n // 原 mode='display' early return 寫在 hooks 之上 → runtime 切 mode 會 hook count 不一致 crash;已下移至 hooks 後。\n //\n // 例外:Checkbox 是 CheckboxGroup 的 child 時(multi-select 情境),每個 checkbox\n // 的 label 是它自己的選項名,FieldLabel 只是群組名稱 — 此時 label 必須保留,\n // 不能被 Field context 吞掉。AR50 的根因就是這個 branch 之前誤把 group 內的 checkbox\n // label 全清空,導致 sheet 內 3 個 checkbox 沒 label。\n const fieldCtx = useFieldContext()\n const checkboxGroupCtx = React.useContext(CheckboxGroupContext)\n const insideField = fieldCtx?.hasFieldWrapper === true\n const insideGroup = checkboxGroupCtx?.inGroup === true\n const shouldSuppressLabel = insideField && !insideGroup\n const effectiveLabel = shouldSuppressLabel ? undefined : label\n const effectiveDescription = shouldSuppressLabel ? undefined : description\n\n // Id 連結\n //\n // ── 2026-04-21 bug fix ──\n // 原本:`idProp ?? fieldCtx?.id ?? generatedId`。\n // 在 Field 內 fieldCtx.id 存在,CheckboxGroup 所有 children 共用同一個 id →\n // 每個 checkbox 的 `<label htmlFor={sameId}>` 全指向第一個 checkbox →\n // 點任何 label 都只開關第一個 checkbox(real bug)*。\n //\n // 修法:group 內的 checkbox 強制用 generatedId(唯一),不沿用 Field id;\n // solo in Field(binary toggle)才沿用 fieldCtx.id 讓 FieldLabel htmlFor 生效。\n const generatedId = React.useId()\n const inputId = idProp ?? (insideGroup ? generatedId : (fieldCtx?.id ?? generatedId))\n\n // 2026-06-08 SSOT cascade:disabled + mode 經 resolver hook(原 raw prop → <Field disabled>/<Field mode=\"display\"> 漏 cascade)\n const resolvedDisabled = useResolvedFieldDisabled(disabled)\n const resolvedMode = useResolvedFieldMode({ mode, disabled, readOnly })\n const effectiveReadOnly = readOnly \|\| resolvedMode === 'readonly'\n\n // ── mode='display'(下移至所有 hooks 之後,per #35 Rules of Hooks)──────────\n // 純展示模式:無互動 primitive、渲染 ✓ / —(checked=true → ✓ / 其他 → —)。取代 BooleanDisplay。\n if (resolvedMode === 'display') {\n const isChecked = props.checked === true\n return isChecked\n ? <span className=\"text-foreground\">✓</span>\n : <span className=\"text-fg-muted\">—</span>\n }\n\n const rootEl = (\n <CheckboxPrimitive.Root\n id={inputId}\n ref={ref}\n disabled={resolvedDisabled}\n aria-readonly={effectiveReadOnly \|\| undefined}\n data-readonly={effectiveReadOnly \|\| undefined}\n tabIndex={effectiveReadOnly ? -1 : undefined}\n aria-describedby={fieldCtx?.descriptionId}\n className={cn(checkboxVariants({ size }), className)}\n {...props}\n >\n <CheckboxPrimitive.Indicator className=\"grid place-content-center text-current\">\n {props.checked === 'indeterminate'\n ? <Minus style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />\n : <Check style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />\n }\n </CheckboxPrimitive.Indicator>\n </CheckboxPrimitive.Root>\n )\n\n // 無 label → 只渲染 checkbox 本體\n if (effectiveLabel == null) return rootEl\n\n // 有 label → 透過 SelectionItem 包裝（control 在左、label+description 在右）\n return (\n <SelectionItem\n control={rootEl}\n label={effectiveLabel}\n description={effectiveDescription}\n icon={icon}\n avatar={avatar}\n htmlFor={inputId}\n disabled={resolvedDisabled}\n size={sizeKey}\n />\n )\n }\n)\nCheckbox.displayName = CheckboxPrimitive.Root.displayName\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 checkboxMeta = {\n component: 'Checkbox',\n family: null, // self-contained primitive(對齊 spec frontmatter self-contained + body L31;非 Family 4)\n variants: {\n\n },\n sizes: {\n // 2026-06-10 修 stale meta:iconSize 對齊 checkIconSize 真值(L49 sm/md=12, lg=16;deep-audit A.1b 抓 metadata drift)\n sm: { fieldHeight: 28, iconSize: 12, typography: 'body' },\n md: { fieldHeight: 32, iconSize: 12, typography: 'body' },\n lg: { fieldHeight: 36, iconSize: 16, typography: 'body' },\n },\n states: ['default', 'hover', 'focus-visible', 'disabled'],\n tokens: {\n bg: ['bg-disabled', 'bg-primary', 'bg-primary-hover', 'bg-surface'],\n fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],\n ring: ['ring-ring'],\n },\n defaultSize: 'md',\n} as const\n\nexport { Checkbox, checkboxVariants }\n"],"names":[],"mappings":"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"}

package/dist/components/Chip/chip.d.ts CHANGED Viewed

@@ -43,10 +43,10 @@ export declare const chipMeta: {
     readonly family: 3;
     readonly variants: {};
     readonly sizes: {};
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly states: readonly ["default", "hover", "selected", "focus-visible", "disabled"];
     readonly tokens: {
         readonly bg: readonly ["bg-surface"];
-        readonly fg: readonly ["text-fg-disabled", "text-fg-secondary", "text-foreground"];
+        readonly fg: readonly ["text-fg-disabled", "text-fg-secondary", "text-foreground", "text-primary-hover"];
         readonly ring: readonly ["ring-ring"];
     };
 };

package/dist/components/Chip/chip.js CHANGED Viewed

@@ -208,10 +208,11 @@ const chipMeta = {
   family: 3,
   variants: {},
   sizes: {},
-  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  states: ["default", "hover", "selected", "focus-visible", "disabled"],
+  // selected = data-[state=on](primary-hover);cva 無 active 樣式
   tokens: {
     bg: ["bg-surface"],
-    fg: ["text-fg-disabled", "text-fg-secondary", "text-foreground"],
+    fg: ["text-fg-disabled", "text-fg-secondary", "text-foreground", "text-primary-hover"],
     ring: ["ring-ring"]
   }
 };

package/dist/components/Chip/chip.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"chip.js","sources":["../../../src/components/Chip/chip.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 * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group'\nimport { cva } from 'class-variance-authority'\nimport type { LucideIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport {\n DropdownMenu,\n DropdownMenuTrigger,\n DropdownMenuContent,\n DropdownMenuCheckboxItem,\n} from '@/design-system/components/DropdownMenu/dropdown-menu'\nimport {\n useScrollEdges,\n useScrollByPage,\n buildFadeMask,\n ARROW_BUTTON_WIDTH,\n OverflowScrollArrow,\n OverflowMenuTriggerButton,\n} from '@/design-system/patterns/horizontal-overflow/horizontal-overflow'\n\n/*\n Chip — Material Design Filter Chip\n \n 基於 Radix ToggleGroup，橋接設計系統 token。\n * 必須在 <ChipGroup> 內使用。\n \n ── 內部結構（鏡射 Button）──\n * [startIcon?] [<span px-1>label</span>] [<span gap-1>badge? + endIcon?</span>]\n \n ── Size ──\n * 單一 size = h-field-sm（28/32 density-aware）\n * 對齊 Material 3 / Atlassian / Polaris 世界級共識\n \n ── State ──\n * default bg-surface border-border text-fg-secondary\n * hover border-border-hover text-foreground（對齊 Input / SegmentedControl）\n * selected bg-surface（不變） border-primary-hover text-primary-hover\n * disabled cursor-not-allowed text-fg-disabled\n \n ── 詳見 chip.spec.md ──\n /\n\n// ── Chip item ────────────────────────────────────────────────────────────────\n\nconst chipVariants = cva(\n [\n 'inline-flex items-center justify-center',\n 'h-field-sm px-3 gap-1',\n 'rounded-full border border-border',\n // 預設文字: text-fg-secondary (neutral-8) — 對齊 SegmentedControl / Tabs 未選狀態\n 'bg-surface text-fg-secondary',\n 'text-body leading-compact font-medium whitespace-nowrap',\n 'transition-colors duration-150',\n 'cursor-pointer select-none',\n 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',\n // hover（未選）：border 加深一階 + 文字轉深，對齊 Input / SegmentedControl hover\n 'hover:border-border-hover hover:text-foreground',\n // selected: 文字 + 邊框都用 primary-hover,底色維持 bg-surface 不變\n // ── pill 風格 canonical 選中規則,跟 SegmentedControl 完全一致:\n // primary-hover 同時染文字和線條;底色不改 (不用 primary-subtle)。\n 'data-[state=on]:border-primary-hover data-[state=on]:text-primary-hover',\n // disabled：cursor-not-allowed + 鎖 hover 不變色\n // 不用 pointer-events-none（否則 cursor-not-allowed 不會顯示）\n 'disabled:cursor-not-allowed disabled:text-fg-disabled',\n 'disabled:hover:border-border disabled:hover:text-fg-disabled',\n ]\n)\n\nexport interface ChipProps\n extends React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> {\n /* 左側 icon（LucideIcon），最多一個 /\n startIcon?: LucideIcon\n /* 右側 badge（通常是計數指示器）/\n badge?: React.ReactNode\n /* 右側 icon（少見，通常是 ChevronDown 指示可展開）/\n endIcon?: LucideIcon\n}\n\nconst Chip = React.forwardRef<\n React.ElementRef<typeof ToggleGroupPrimitive.Item>,\n ChipProps\n>(({ className, startIcon: StartIcon, badge, endIcon: EndIcon, children, ...props }, ref) => {\n const hasSuffix = badge != null \|\| EndIcon !== undefined\n\n return (\n <ToggleGroupPrimitive.Item\n ref={ref}\n className={cn(chipVariants(), className)}\n {...props}\n >\n {StartIcon && <StartIcon size={16} aria-hidden />}\n {children != null && <span className=\"px-1\">{children}</span>}\n {hasSuffix && (\n <span className=\"inline-flex items-center gap-1\">\n {badge}\n {EndIcon && <EndIcon size={16} aria-hidden />}\n </span>\n )}\n </ToggleGroupPrimitive.Item>\n )\n})\nChip.displayName = 'Chip'\n\n// ── ChipGroup ────────────────────────────────────────────────────────────────\n\nexport type ChipGroupLayout = 'wrap' \| 'scroll' \| 'menu'\n\nexport type ChipGroupProps = React.ComponentPropsWithoutRef<\n typeof ToggleGroupPrimitive.Root\n> & {\n /* Overflow 處理模式。預設 `wrap`（塞不下換行）。詳見 chip.spec.md */\n layout?: ChipGroupLayout\n}\n\nconst ChipGroup = React.forwardRef<HTMLDivElement, ChipGroupProps>(\n ({ layout = 'wrap', className, children, ...props }, ref) => {\n if (layout === 'scroll') {\n return (\n <ScrollChipGroup ref={ref} className={className} {...props}>\n {children}\n </ScrollChipGroup>\n )\n }\n if (layout === 'menu') {\n return (\n <MenuChipGroup ref={ref} className={className} {...props}>\n {children}\n </MenuChipGroup>\n )\n }\n // wrap（預設）\n return (\n <ToggleGroupPrimitive.Root\n ref={ref}\n className={cn('flex flex-wrap gap-2', className)}\n {...props}\n >\n {children}\n </ToggleGroupPrimitive.Root>\n )\n }\n)\nChipGroup.displayName = 'ChipGroup'\n\n// ── Scroll / Menu modes ──\n// Fade mask / arrows / menu trigger 全部從 horizontal-overflow pattern module 取用。\n// 詳見 `patterns/horizontal-overflow/horizontal-overflow.spec.md`。\n//\n// Canonical 規則:所有 overflow affordance 一律是 Button text sm iconOnly,\n// 不論在 Chip / Tab / Step / SegmentedControl。Chip menu trigger 曾經用\n// chip-shape 圓形 button,已改回 text button 對齊 mental model。\n\n// ── ScrollChipGroup ──────────────────────────────────────────────────────────\n\nconst ScrollChipGroup = React.forwardRef<\n HTMLDivElement,\n React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root>\n>(({ className, children, ...props }, ref) => {\n const { scrollRef, atStart, atEnd, canScroll } = useScrollEdges<HTMLDivElement>()\n const scrollByPage = useScrollByPage(scrollRef)\n const maskImage = buildFadeMask({\n canScroll,\n atStart,\n atEnd,\n reserveArrowWidth: ARROW_BUTTON_WIDTH,\n })\n\n return (\n <div className=\"relative\">\n <div\n ref={scrollRef}\n className=\"overflow-x-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden\"\n style={{ maskImage, WebkitMaskImage: maskImage }}\n >\n <ToggleGroupPrimitive.Root\n ref={ref}\n className={cn('flex flex-nowrap gap-2 w-fit', className)}\n {...props}\n >\n {children}\n </ToggleGroupPrimitive.Root>\n </div>\n {!atStart && canScroll && (\n <OverflowScrollArrow direction=\"left\" onClick={() => scrollByPage('left')} />\n )}\n {!atEnd && canScroll && (\n <OverflowScrollArrow direction=\"right\" onClick={() => scrollByPage('right')} />\n )}\n </div>\n )\n})\nScrollChipGroup.displayName = 'ScrollChipGroup'\n\n// ── MenuChipGroup ────────────────────────────────────────────────────────────\n// Show-all navigator pattern (Chrome tab dropdown / VS Code editor tabs):\n// - Menu 永遠顯示全部 chips,每個都用 DropdownMenuCheckboxItem + checked 反映 selection\n// - 點 menu item = toggle selection + scrollIntoView,把該 chip 捲到中央\n// - 不用動態 overflow 計算,menu 內容穩定\n//\n// Menu trigger 使用 canonical `<OverflowMenuTriggerButton>`(= Button text sm iconOnly\n// + ChevronDown),跟 Tabs menu trigger 完全同一套——overflow affordance 屬於工具層,\n// 不該用 chip 自己的視覺語言(圓形 outlined)去渲染,否則 mental model 錯誤(使用者\n// 會誤以為是第 N+1 個可選 chip)。\n//\n// 過去 Chip menu trigger 曾用 `chipVariants() + aspect-square + p-0` 做成圓形 pill,\n// 已按 `horizontal-overflow.spec.md` 的 canonical 規則改回 text button。\n//\n// Fade mask 仍保留(reserveArrowWidth: 0),軟化內容硬邊。\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst MenuChipGroup = React.forwardRef<\n HTMLDivElement,\n React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root>\n>(({ className, children, ...props }, ref) => {\n const { scrollRef, atStart, atEnd, canScroll } = useScrollEdges<HTMLDivElement>()\n\n // Local ref map — 追蹤每個 chip 的 DOM 元素供 scrollIntoView 使用。\n // 不用 useOverflowIndices 因為 menu 永遠顯示全部, 不需要動態 overflow 計算。\n // code-quality-allow: long-function — helper fn 結構緊密,拆 sub-fn 會跨 fn 傳 state 反而複雜\n const itemRefs = React.useRef<Map<number, HTMLElement>>(new Map())\n // 2026-05-16 audit codex Round 6:capture rAF + cancel on unmount(defensive hygiene)\n const scrollRafIdRef = React.useRef<number>(0)\n React.useEffect(() => () => { if (scrollRafIdRef.current) cancelAnimationFrame(scrollRafIdRef.current) }, [])\n const registerItem = React.useCallback(\n (index: number) => (el: HTMLElement \| null) => {\n if (el) itemRefs.current.set(index, el)\n else itemRefs.current.delete(index)\n },\n []\n )\n\n const menuMaskImage = buildFadeMask({ canScroll, atStart, atEnd, reserveArrowWidth: 0 })\n\n const items = React.useMemo(\n () => React.Children.toArray(children).filter(React.isValidElement) as React.ReactElement[],\n [children]\n )\n\n const groupType = (props as { type?: 'single' \| 'multiple' }).type ?? 'single'\n const groupValue = (props as { value?: string \| string[] }).value\n const groupOnValueChange = (\n props as { onValueChange?: (value: string \| string[]) => void }\n ).onValueChange\n\n // code-quality-allow: long-function — helper fn 結構緊密,拆 sub-fn 會跨 fn 傳 state 反而複雜\n const isSelected = React.useCallback(\n (chipValue: string): boolean => {\n if (groupType === 'multiple') {\n return Array.isArray(groupValue) && groupValue.includes(chipValue)\n }\n return groupValue === chipValue\n },\n [groupType, groupValue]\n )\n\n // code-quality-allow: long-function — multi / single / none selection mode each has 事務性 branch,拆 fn 會跨 fn 傳 chipValue/index/groupOnValueChange state 反而難讀\n const toggleFromMenu = React.useCallback(\n (chipValue: string, index: number) => {\n if (!groupOnValueChange) {\n if (import.meta.env?.DEV) {\n console.warn(\n '[ChipGroup] layout=\"menu\" 需要 controlled 使用（請傳 value + onValueChange），否則 menu items 無法同步主 chip 選擇狀態。'\n )\n }\n return\n }\n if (groupType === 'multiple') {\n const current = (Array.isArray(groupValue) ? groupValue : []) as string[]\n const next = current.includes(chipValue)\n ? current.filter((v) => v !== chipValue)\n : [...current, chipValue]\n ;(groupOnValueChange as (v: string[]) => void)(next)\n } else {\n ;(groupOnValueChange as (v: string) => void)(chipValue)\n }\n // scrollIntoView: 讓剛選中的 chip 出現在視圖中央\n if (scrollRafIdRef.current) cancelAnimationFrame(scrollRafIdRef.current)\n scrollRafIdRef.current = requestAnimationFrame(() => {\n scrollRafIdRef.current = 0\n itemRefs.current.get(index)?.scrollIntoView({ behavior: 'smooth', inline: 'center', block: 'nearest' })\n })\n },\n [groupType, groupValue, groupOnValueChange]\n )\n\n const enhancedItems = items.map((child, i) =>\n React.cloneElement(\n child as React.ReactElement<{ ref?: React.Ref<HTMLElement> }>,\n { ref: registerItem(i) }\n )\n )\n\n return (\n <div className=\"flex items-center gap-2\">\n <div\n ref={scrollRef}\n className=\"flex-1 min-w-0 overflow-x-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden\"\n style={{ maskImage: menuMaskImage, WebkitMaskImage: menuMaskImage }}\n >\n <ToggleGroupPrimitive.Root\n ref={ref}\n className={cn('flex flex-nowrap gap-2 w-fit', className)}\n {...props}\n >\n {enhancedItems}\n </ToggleGroupPrimitive.Root>\n </div>\n {canScroll && (\n <DropdownMenu>\n <DropdownMenuTrigger asChild>\n <OverflowMenuTriggerButton\n aria-label={`選項選單(共 ${items.length} 個)`}\n />\n </DropdownMenuTrigger>\n <DropdownMenuContent align=\"end\">\n {items.map((chip, index) => {\n const chipProps = chip.props as { value?: string; children?: React.ReactNode; disabled?: boolean }\n const chipValue = chipProps.value\n if (typeof chipValue !== 'string') return null\n return (\n <DropdownMenuCheckboxItem\n key={chipValue}\n checked={isSelected(chipValue)}\n disabled={chipProps.disabled}\n onCheckedChange={() => toggleFromMenu(chipValue, index)}\n >\n {chipProps.children}\n </DropdownMenuCheckboxItem>\n )\n })}\n </DropdownMenuContent>\n </DropdownMenu>\n )}\n </div>\n )\n})\nMenuChipGroup.displayName = 'MenuChipGroup'\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 chipMeta = {\n component: 'Chip',\n family: 3,\n variants: {\n\n },\n sizes: {\n\n },\n states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],\n tokens: {\n bg: ['bg-surface'],\n fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],\n ring: ['ring-ring'],\n },\n} as const\n\nexport { Chip, ChipGroup, chipVariants }\n"],"names":[],"mappings":"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"}
1	+ {"version":3,"file":"chip.js","sources":["../../../src/components/Chip/chip.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 * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group'\nimport { cva } from 'class-variance-authority'\nimport type { LucideIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport {\n DropdownMenu,\n DropdownMenuTrigger,\n DropdownMenuContent,\n DropdownMenuCheckboxItem,\n} from '@/design-system/components/DropdownMenu/dropdown-menu'\nimport {\n useScrollEdges,\n useScrollByPage,\n buildFadeMask,\n ARROW_BUTTON_WIDTH,\n OverflowScrollArrow,\n OverflowMenuTriggerButton,\n} from '@/design-system/patterns/horizontal-overflow/horizontal-overflow'\n\n/*\n Chip — Material Design Filter Chip\n \n 基於 Radix ToggleGroup，橋接設計系統 token。\n * 必須在 <ChipGroup> 內使用。\n \n ── 內部結構（鏡射 Button）──\n * [startIcon?] [<span px-1>label</span>] [<span gap-1>badge? + endIcon?</span>]\n \n ── Size ──\n * 單一 size = h-field-sm（28/32 density-aware）\n * 對齊 Material 3 / Atlassian / Polaris 世界級共識\n \n ── State ──\n * default bg-surface border-border text-fg-secondary\n * hover border-border-hover text-foreground（對齊 Input / SegmentedControl）\n * selected bg-surface（不變） border-primary-hover text-primary-hover\n * disabled cursor-not-allowed text-fg-disabled\n \n ── 詳見 chip.spec.md ──\n /\n\n// ── Chip item ────────────────────────────────────────────────────────────────\n\nconst chipVariants = cva(\n [\n 'inline-flex items-center justify-center',\n 'h-field-sm px-3 gap-1',\n 'rounded-full border border-border',\n // 預設文字: text-fg-secondary (neutral-8) — 對齊 SegmentedControl / Tabs 未選狀態\n 'bg-surface text-fg-secondary',\n 'text-body leading-compact font-medium whitespace-nowrap',\n 'transition-colors duration-150',\n 'cursor-pointer select-none',\n 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',\n // hover（未選）：border 加深一階 + 文字轉深，對齊 Input / SegmentedControl hover\n 'hover:border-border-hover hover:text-foreground',\n // selected: 文字 + 邊框都用 primary-hover,底色維持 bg-surface 不變\n // ── pill 風格 canonical 選中規則,跟 SegmentedControl 完全一致:\n // primary-hover 同時染文字和線條;底色不改 (不用 primary-subtle)。\n 'data-[state=on]:border-primary-hover data-[state=on]:text-primary-hover',\n // disabled：cursor-not-allowed + 鎖 hover 不變色\n // 不用 pointer-events-none（否則 cursor-not-allowed 不會顯示）\n 'disabled:cursor-not-allowed disabled:text-fg-disabled',\n 'disabled:hover:border-border disabled:hover:text-fg-disabled',\n ]\n)\n\nexport interface ChipProps\n extends React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> {\n /* 左側 icon（LucideIcon），最多一個 /\n startIcon?: LucideIcon\n /* 右側 badge（通常是計數指示器）/\n badge?: React.ReactNode\n /* 右側 icon（少見，通常是 ChevronDown 指示可展開）/\n endIcon?: LucideIcon\n}\n\nconst Chip = React.forwardRef<\n React.ElementRef<typeof ToggleGroupPrimitive.Item>,\n ChipProps\n>(({ className, startIcon: StartIcon, badge, endIcon: EndIcon, children, ...props }, ref) => {\n const hasSuffix = badge != null \|\| EndIcon !== undefined\n\n return (\n <ToggleGroupPrimitive.Item\n ref={ref}\n className={cn(chipVariants(), className)}\n {...props}\n >\n {StartIcon && <StartIcon size={16} aria-hidden />}\n {children != null && <span className=\"px-1\">{children}</span>}\n {hasSuffix && (\n <span className=\"inline-flex items-center gap-1\">\n {badge}\n {EndIcon && <EndIcon size={16} aria-hidden />}\n </span>\n )}\n </ToggleGroupPrimitive.Item>\n )\n})\nChip.displayName = 'Chip'\n\n// ── ChipGroup ────────────────────────────────────────────────────────────────\n\nexport type ChipGroupLayout = 'wrap' \| 'scroll' \| 'menu'\n\nexport type ChipGroupProps = React.ComponentPropsWithoutRef<\n typeof ToggleGroupPrimitive.Root\n> & {\n /* Overflow 處理模式。預設 `wrap`（塞不下換行）。詳見 chip.spec.md */\n layout?: ChipGroupLayout\n}\n\nconst ChipGroup = React.forwardRef<HTMLDivElement, ChipGroupProps>(\n ({ layout = 'wrap', className, children, ...props }, ref) => {\n if (layout === 'scroll') {\n return (\n <ScrollChipGroup ref={ref} className={className} {...props}>\n {children}\n </ScrollChipGroup>\n )\n }\n if (layout === 'menu') {\n return (\n <MenuChipGroup ref={ref} className={className} {...props}>\n {children}\n </MenuChipGroup>\n )\n }\n // wrap（預設）\n return (\n <ToggleGroupPrimitive.Root\n ref={ref}\n className={cn('flex flex-wrap gap-2', className)}\n {...props}\n >\n {children}\n </ToggleGroupPrimitive.Root>\n )\n }\n)\nChipGroup.displayName = 'ChipGroup'\n\n// ── Scroll / Menu modes ──\n// Fade mask / arrows / menu trigger 全部從 horizontal-overflow pattern module 取用。\n// 詳見 `patterns/horizontal-overflow/horizontal-overflow.spec.md`。\n//\n// Canonical 規則:所有 overflow affordance 一律是 Button text sm iconOnly,\n// 不論在 Chip / Tab / Step / SegmentedControl。Chip menu trigger 曾經用\n// chip-shape 圓形 button,已改回 text button 對齊 mental model。\n\n// ── ScrollChipGroup ──────────────────────────────────────────────────────────\n\nconst ScrollChipGroup = React.forwardRef<\n HTMLDivElement,\n React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root>\n>(({ className, children, ...props }, ref) => {\n const { scrollRef, atStart, atEnd, canScroll } = useScrollEdges<HTMLDivElement>()\n const scrollByPage = useScrollByPage(scrollRef)\n const maskImage = buildFadeMask({\n canScroll,\n atStart,\n atEnd,\n reserveArrowWidth: ARROW_BUTTON_WIDTH,\n })\n\n return (\n <div className=\"relative\">\n <div\n ref={scrollRef}\n className=\"overflow-x-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden\"\n style={{ maskImage, WebkitMaskImage: maskImage }}\n >\n <ToggleGroupPrimitive.Root\n ref={ref}\n className={cn('flex flex-nowrap gap-2 w-fit', className)}\n {...props}\n >\n {children}\n </ToggleGroupPrimitive.Root>\n </div>\n {!atStart && canScroll && (\n <OverflowScrollArrow direction=\"left\" onClick={() => scrollByPage('left')} />\n )}\n {!atEnd && canScroll && (\n <OverflowScrollArrow direction=\"right\" onClick={() => scrollByPage('right')} />\n )}\n </div>\n )\n})\nScrollChipGroup.displayName = 'ScrollChipGroup'\n\n// ── MenuChipGroup ────────────────────────────────────────────────────────────\n// Show-all navigator pattern (Chrome tab dropdown / VS Code editor tabs):\n// - Menu 永遠顯示全部 chips,每個都用 DropdownMenuCheckboxItem + checked 反映 selection\n// - 點 menu item = toggle selection + scrollIntoView,把該 chip 捲到中央\n// - 不用動態 overflow 計算,menu 內容穩定\n//\n// Menu trigger 使用 canonical `<OverflowMenuTriggerButton>`(= Button text sm iconOnly\n// + ChevronDown),跟 Tabs menu trigger 完全同一套——overflow affordance 屬於工具層,\n// 不該用 chip 自己的視覺語言(圓形 outlined)去渲染,否則 mental model 錯誤(使用者\n// 會誤以為是第 N+1 個可選 chip)。\n//\n// 過去 Chip menu trigger 曾用 `chipVariants() + aspect-square + p-0` 做成圓形 pill,\n// 已按 `horizontal-overflow.spec.md` 的 canonical 規則改回 text button。\n//\n// Fade mask 仍保留(reserveArrowWidth: 0),軟化內容硬邊。\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst MenuChipGroup = React.forwardRef<\n HTMLDivElement,\n React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root>\n>(({ className, children, ...props }, ref) => {\n const { scrollRef, atStart, atEnd, canScroll } = useScrollEdges<HTMLDivElement>()\n\n // Local ref map — 追蹤每個 chip 的 DOM 元素供 scrollIntoView 使用。\n // 不用 useOverflowIndices 因為 menu 永遠顯示全部, 不需要動態 overflow 計算。\n // code-quality-allow: long-function — helper fn 結構緊密,拆 sub-fn 會跨 fn 傳 state 反而複雜\n const itemRefs = React.useRef<Map<number, HTMLElement>>(new Map())\n // 2026-05-16 audit codex Round 6:capture rAF + cancel on unmount(defensive hygiene)\n const scrollRafIdRef = React.useRef<number>(0)\n React.useEffect(() => () => { if (scrollRafIdRef.current) cancelAnimationFrame(scrollRafIdRef.current) }, [])\n const registerItem = React.useCallback(\n (index: number) => (el: HTMLElement \| null) => {\n if (el) itemRefs.current.set(index, el)\n else itemRefs.current.delete(index)\n },\n []\n )\n\n const menuMaskImage = buildFadeMask({ canScroll, atStart, atEnd, reserveArrowWidth: 0 })\n\n const items = React.useMemo(\n () => React.Children.toArray(children).filter(React.isValidElement) as React.ReactElement[],\n [children]\n )\n\n const groupType = (props as { type?: 'single' \| 'multiple' }).type ?? 'single'\n const groupValue = (props as { value?: string \| string[] }).value\n const groupOnValueChange = (\n props as { onValueChange?: (value: string \| string[]) => void }\n ).onValueChange\n\n // code-quality-allow: long-function — helper fn 結構緊密,拆 sub-fn 會跨 fn 傳 state 反而複雜\n const isSelected = React.useCallback(\n (chipValue: string): boolean => {\n if (groupType === 'multiple') {\n return Array.isArray(groupValue) && groupValue.includes(chipValue)\n }\n return groupValue === chipValue\n },\n [groupType, groupValue]\n )\n\n // code-quality-allow: long-function — multi / single / none selection mode each has 事務性 branch,拆 fn 會跨 fn 傳 chipValue/index/groupOnValueChange state 反而難讀\n const toggleFromMenu = React.useCallback(\n (chipValue: string, index: number) => {\n if (!groupOnValueChange) {\n if (import.meta.env?.DEV) {\n console.warn(\n '[ChipGroup] layout=\"menu\" 需要 controlled 使用（請傳 value + onValueChange），否則 menu items 無法同步主 chip 選擇狀態。'\n )\n }\n return\n }\n if (groupType === 'multiple') {\n const current = (Array.isArray(groupValue) ? groupValue : []) as string[]\n const next = current.includes(chipValue)\n ? current.filter((v) => v !== chipValue)\n : [...current, chipValue]\n ;(groupOnValueChange as (v: string[]) => void)(next)\n } else {\n ;(groupOnValueChange as (v: string) => void)(chipValue)\n }\n // scrollIntoView: 讓剛選中的 chip 出現在視圖中央\n if (scrollRafIdRef.current) cancelAnimationFrame(scrollRafIdRef.current)\n scrollRafIdRef.current = requestAnimationFrame(() => {\n scrollRafIdRef.current = 0\n itemRefs.current.get(index)?.scrollIntoView({ behavior: 'smooth', inline: 'center', block: 'nearest' })\n })\n },\n [groupType, groupValue, groupOnValueChange]\n )\n\n const enhancedItems = items.map((child, i) =>\n React.cloneElement(\n child as React.ReactElement<{ ref?: React.Ref<HTMLElement> }>,\n { ref: registerItem(i) }\n )\n )\n\n return (\n <div className=\"flex items-center gap-2\">\n <div\n ref={scrollRef}\n className=\"flex-1 min-w-0 overflow-x-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden\"\n style={{ maskImage: menuMaskImage, WebkitMaskImage: menuMaskImage }}\n >\n <ToggleGroupPrimitive.Root\n ref={ref}\n className={cn('flex flex-nowrap gap-2 w-fit', className)}\n {...props}\n >\n {enhancedItems}\n </ToggleGroupPrimitive.Root>\n </div>\n {canScroll && (\n <DropdownMenu>\n <DropdownMenuTrigger asChild>\n <OverflowMenuTriggerButton\n aria-label={`選項選單(共 ${items.length} 個)`}\n />\n </DropdownMenuTrigger>\n <DropdownMenuContent align=\"end\">\n {items.map((chip, index) => {\n const chipProps = chip.props as { value?: string; children?: React.ReactNode; disabled?: boolean }\n const chipValue = chipProps.value\n if (typeof chipValue !== 'string') return null\n return (\n <DropdownMenuCheckboxItem\n key={chipValue}\n checked={isSelected(chipValue)}\n disabled={chipProps.disabled}\n onCheckedChange={() => toggleFromMenu(chipValue, index)}\n >\n {chipProps.children}\n </DropdownMenuCheckboxItem>\n )\n })}\n </DropdownMenuContent>\n </DropdownMenu>\n )}\n </div>\n )\n})\nMenuChipGroup.displayName = 'MenuChipGroup'\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 chipMeta = {\n component: 'Chip',\n family: 3,\n variants: {\n\n },\n sizes: {\n\n },\n states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'], // selected = data-[state=on](primary-hover);cva 無 active 樣式\n tokens: {\n bg: ['bg-surface'],\n fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary-hover'],\n ring: ['ring-ring'],\n },\n} as const\n\nexport { Chip, ChipGroup, chipVariants }\n"],"names":[],"mappings":"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"}

package/dist/components/CircularProgress/circular-progress.d.ts CHANGED Viewed

@@ -28,7 +28,7 @@ export declare const circularProgressMeta: {
     readonly family: null;
     readonly variants: {};
     readonly sizes: {};
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly states: readonly ["default"];
     readonly tokens: {
         readonly bg: readonly [];
         readonly fg: readonly ["text-fg-muted", "text-foreground", "text-info"];

package/dist/components/CircularProgress/circular-progress.js CHANGED Viewed

@@ -104,7 +104,8 @@ const circularProgressMeta = {
   // non-family composite / overlay / layout
   variants: {},
   sizes: {},
-  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  states: ["default"],
+  // 無 hover / focus / active(spec);disabled 屬 consumer host(spec「邊界案例」)
   tokens: {
     bg: [],
     fg: ["text-fg-muted", "text-foreground", "text-info"],

package/dist/components/CircularProgress/circular-progress.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"circular-progress.js","sources":["../../../src/components/CircularProgress/circular-progress.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'\n\n/*\n CircularProgress — 圓形進度指示(determinate + indeterminate 雙模式)\n \n 世界級對照:Material `CircularProgress` / Chakra `CircularProgress` — 同元件管\n * determinate(有 `value`)+ indeterminate(無 `value`)兩態。本 DS 採此流派作為\n * circular progress 的 SSOT,`Spinner` 名稱廢除(遷至本元件)。\n \n ── 姊妹元件 ──\n * `ProgressBar` = linear determinate(大區塊、頁面級、表單步驟、上傳 bar)\n * `CircularProgress` = circular 兩態(本元件,inline 小空間 / Button loading / Field loading)\n \n ── API ──\n * value: undefined → indeterminate(旋轉 partial arc,Spinner 樣式)\n * number 0-100 → determinate(固定 arc + track)\n * size: 自由 px(預設 24,≤ 64 建議)— 跟 Avatar / Lucide icon 同策略\n * label: 可選 inline label,font-size inherit parent,color text-fg-muted\n * affix: (determinate only)'value' \| ReactNode\n \n ── 視覺 ──\n * SVG 雙圓:底 track(`var(--secondary)`)+ 進度 arc(`text-info`,status 進度色,不隨狀態變色)。\n * stroke-linecap round,rotate -90deg。\n * Indeterminate mode:arc 固定 25%,外層 `animate-spin` 旋轉,視覺同 Spinner。\n \n ── 不設 status prop(決策 2026-04-20)──\n * 世界級沒有「success / error CircularProgress」的穩態呈現——完成 / 失敗的語義應由\n * consumer 在業務邏輯上替換 CircularProgress 為實際內容(status icon + label、\n * 成功的結果、錯誤訊息等),而非讓 CircularProgress 變色 + 加 check icon。這種「綠底\n * 空心 circle + check icon 並排」是 DS 典型 over-designing 的 anti-pattern(參考:\n * Material / Chakra / Ant / Polaris 全部沒有此 variant)。\n \n Consumer 端範例:\n * {uploading ? <CircularProgress /> : done ? <Check /> : error ? <AlertCircle /> : null}\n \n ── A11y ──\n * 有 value → role=\"progressbar\" + aria-valuenow/min/max\n * 無 value → role=\"status\"(loading 語義) + aria-label(如傳)或 aria-hidden(否則)\n /\n\n// Indeterminate mode 的 arc 比例(Material 流派:25%-30% 視覺最平衡)\nconst INDETERMINATE_ARC_RATIO = 0.25\n\nexport interface CircularProgressProps extends React.HTMLAttributes<HTMLSpanElement> {\n /\n 進度 0-100。\n * - undefined → indeterminate(旋轉 partial arc,Spinner 樣式)\n * - number → determinate(固定 arc + track)\n /\n value?: number\n /* 直徑(px)。預設 24,建議 ≤ 64。 /\n size?: number\n /\n 視覺 label(inline 顯示於右側)。\n * - font-size 繼承 parent(不設 text-size class,CSS inherit)\n * - color 鎖 `text-fg-muted`(neutral-7)\n * - 塞在元件內時預設不用(e.g. Button loading);全頁 / Empty overlay 可用\n /\n label?: string\n /\n 右側 affix(determinate only;indeterminate 忽略)。\n * - `'value'` → `{value}%` 文字\n * - ReactNode → 客製(若需顯示「已完成」,consumer 端整個 swap 為 Check icon,不走此 prop)\n /\n affix?: 'value' \| React.ReactNode\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst CircularProgress = React.forwardRef<HTMLSpanElement, CircularProgressProps>(\n (\n {\n value,\n size = 24,\n label,\n affix,\n className,\n 'aria-label': ariaLabel,\n ...props\n },\n ref,\n ) => {\n const isDeterminate = typeof value === 'number'\n const clampedValue = isDeterminate ? Math.max(0, Math.min(100, value)) : 0\n const strokeWidth = Math.max(2, Math.round(size / 10))\n const radius = (size - strokeWidth) / 2\n const circumference = 2 Math.PI * radius\n const dashOffset = isDeterminate\n ? circumference * (1 - clampedValue / 100)\n : circumference * (1 - INDETERMINATE_ARC_RATIO)\n\n const hasLabel = typeof label === 'string' && label.length > 0\n const hasAriaLabel = typeof ariaLabel === 'string' && ariaLabel.length > 0\n const shouldAnnounce = hasAriaLabel \|\| hasLabel\n\n // Affix(determinate only)\n let affixNode: React.ReactNode = null\n if (isDeterminate) {\n if (affix === 'value') {\n affixNode = (\n <span className=\"text-caption text-foreground tabular-nums shrink-0\">\n {Math.round(clampedValue)}%\n </span>\n )\n } else if (\n React.isValidElement(affix) \|\|\n typeof affix === 'string' \|\|\n typeof affix === 'number'\n ) {\n affixNode = affix\n }\n }\n\n const a11yRole = isDeterminate ? 'progressbar' : shouldAnnounce ? 'status' : undefined\n const a11yLabel = hasAriaLabel ? ariaLabel : hasLabel ? label : undefined\n const a11yValueAttrs = isDeterminate\n ? {\n 'aria-valuenow': Math.round(clampedValue),\n 'aria-valuemin': 0,\n 'aria-valuemax': 100,\n }\n : {}\n\n const graphic = (\n <span\n ref={ref}\n role={a11yRole}\n aria-label={a11yLabel}\n aria-hidden={!a11yRole ? true : undefined}\n {...a11yValueAttrs}\n className={cn(\n // align-middle:inline context 內讓 SVG 對齊 adjacent text 的 x-height 中線\n //(不加會按 baseline 對齊,在 inline-flex cell 裡視覺下沉 1-2px 看起來歪)\n 'inline-flex shrink-0 align-middle text-info',\n // motion-reduce:Material 流派 — prefers-reduced-motion 時不停止旋轉(loading 仍需可見回饋),\n // 而是放慢到 3s/cycle(預設 1s),保留資訊不刺激前庭。\n !isDeterminate && 'animate-spin motion-reduce:[animation-duration:3s]',\n className,\n )}\n style={{ width: size, height: size }}\n {...props}\n >\n <svg viewBox={`0 0 ${size} ${size}`} width={size} height={size} aria-hidden>\n <circle\n cx={size / 2}\n cy={size / 2}\n r={radius}\n fill=\"none\"\n stroke=\"var(--secondary)\"\n strokeWidth={strokeWidth}\n />\n <circle\n cx={size / 2}\n cy={size / 2}\n r={radius}\n fill=\"none\"\n stroke=\"currentColor\"\n strokeWidth={strokeWidth}\n strokeDasharray={circumference}\n strokeDashoffset={dashOffset}\n strokeLinecap=\"round\"\n transform={`rotate(-90 ${size / 2} ${size / 2})`}\n className={isDeterminate ? 'transition-[stroke-dashoffset] duration-300' : undefined}\n />\n </svg>\n </span>\n )\n\n // 單純 graphic(無 label / affix)\n if (!hasLabel && !affixNode) return graphic\n\n return (\n <span className={cn('inline-flex items-center', (hasLabel \|\| affixNode) && 'gap-2')}>\n {graphic}\n {hasLabel && <span className=\"text-fg-muted\">{label}</span>}\n {affixNode}\n </span>\n )\n },\n)\nCircularProgress.displayName = 'CircularProgress'\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 circularProgressMeta = {\n component: 'CircularProgress',\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-fg-muted', 'text-foreground', 'text-info'],\n ring: [],\n },\n} as const\n\nexport { CircularProgress }\n"],"names":[],"mappings":"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~~WAAW,~~SAAS~~,UAAU,iBAAiB,UAAU~~;AAAA,~~EAClE~~,QAAQ;AAAA,IACN,IAAI,CAAA;AAAA,IACJ,IAAI,CAAC,iBAAiB,mBAAmB,WAAW;AAAA,IACpD,MAAM,CAAA;AAAA,EAAC;AAEX;"}
1	+ {"version":3,"file":"circular-progress.js","sources":["../../../src/components/CircularProgress/circular-progress.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'\n\n/*\n CircularProgress — 圓形進度指示(determinate + indeterminate 雙模式)\n \n 世界級對照:Material `CircularProgress` / Chakra `CircularProgress` — 同元件管\n * determinate(有 `value`)+ indeterminate(無 `value`)兩態。本 DS 採此流派作為\n * circular progress 的 SSOT,`Spinner` 名稱廢除(遷至本元件)。\n \n ── 姊妹元件 ──\n * `ProgressBar` = linear determinate(大區塊、頁面級、表單步驟、上傳 bar)\n * `CircularProgress` = circular 兩態(本元件,inline 小空間 / Button loading / Field loading)\n \n ── API ──\n * value: undefined → indeterminate(旋轉 partial arc,Spinner 樣式)\n * number 0-100 → determinate(固定 arc + track)\n * size: 自由 px(預設 24,≤ 64 建議)— 跟 Avatar / Lucide icon 同策略\n * label: 可選 inline label,font-size inherit parent,color text-fg-muted\n * affix: (determinate only)'value' \| ReactNode\n \n ── 視覺 ──\n * SVG 雙圓:底 track(`var(--secondary)`)+ 進度 arc(`text-info`,status 進度色,不隨狀態變色)。\n * stroke-linecap round,rotate -90deg。\n * Indeterminate mode:arc 固定 25%,外層 `animate-spin` 旋轉,視覺同 Spinner。\n \n ── 不設 status prop(決策 2026-04-20)──\n * 世界級沒有「success / error CircularProgress」的穩態呈現——完成 / 失敗的語義應由\n * consumer 在業務邏輯上替換 CircularProgress 為實際內容(status icon + label、\n * 成功的結果、錯誤訊息等),而非讓 CircularProgress 變色 + 加 check icon。這種「綠底\n * 空心 circle + check icon 並排」是 DS 典型 over-designing 的 anti-pattern(參考:\n * Material / Chakra / Ant / Polaris 全部沒有此 variant)。\n \n Consumer 端範例:\n * {uploading ? <CircularProgress /> : done ? <Check /> : error ? <AlertCircle /> : null}\n \n ── A11y ──\n * 有 value → role=\"progressbar\" + aria-valuenow/min/max\n * 無 value → role=\"status\"(loading 語義) + aria-label(如傳)或 aria-hidden(否則)\n /\n\n// Indeterminate mode 的 arc 比例(Material 流派:25%-30% 視覺最平衡)\nconst INDETERMINATE_ARC_RATIO = 0.25\n\nexport interface CircularProgressProps extends React.HTMLAttributes<HTMLSpanElement> {\n /\n 進度 0-100。\n * - undefined → indeterminate(旋轉 partial arc,Spinner 樣式)\n * - number → determinate(固定 arc + track)\n /\n value?: number\n /* 直徑(px)。預設 24,建議 ≤ 64。 /\n size?: number\n /\n 視覺 label(inline 顯示於右側)。\n * - font-size 繼承 parent(不設 text-size class,CSS inherit)\n * - color 鎖 `text-fg-muted`(neutral-7)\n * - 塞在元件內時預設不用(e.g. Button loading);全頁 / Empty overlay 可用\n /\n label?: string\n /\n 右側 affix(determinate only;indeterminate 忽略)。\n * - `'value'` → `{value}%` 文字\n * - ReactNode → 客製(若需顯示「已完成」,consumer 端整個 swap 為 Check icon,不走此 prop)\n /\n affix?: 'value' \| React.ReactNode\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst CircularProgress = React.forwardRef<HTMLSpanElement, CircularProgressProps>(\n (\n {\n value,\n size = 24,\n label,\n affix,\n className,\n 'aria-label': ariaLabel,\n ...props\n },\n ref,\n ) => {\n const isDeterminate = typeof value === 'number'\n const clampedValue = isDeterminate ? Math.max(0, Math.min(100, value)) : 0\n const strokeWidth = Math.max(2, Math.round(size / 10))\n const radius = (size - strokeWidth) / 2\n const circumference = 2 Math.PI * radius\n const dashOffset = isDeterminate\n ? circumference * (1 - clampedValue / 100)\n : circumference * (1 - INDETERMINATE_ARC_RATIO)\n\n const hasLabel = typeof label === 'string' && label.length > 0\n const hasAriaLabel = typeof ariaLabel === 'string' && ariaLabel.length > 0\n const shouldAnnounce = hasAriaLabel \|\| hasLabel\n\n // Affix(determinate only)\n let affixNode: React.ReactNode = null\n if (isDeterminate) {\n if (affix === 'value') {\n affixNode = (\n <span className=\"text-caption text-foreground tabular-nums shrink-0\">\n {Math.round(clampedValue)}%\n </span>\n )\n } else if (\n React.isValidElement(affix) \|\|\n typeof affix === 'string' \|\|\n typeof affix === 'number'\n ) {\n affixNode = affix\n }\n }\n\n const a11yRole = isDeterminate ? 'progressbar' : shouldAnnounce ? 'status' : undefined\n const a11yLabel = hasAriaLabel ? ariaLabel : hasLabel ? label : undefined\n const a11yValueAttrs = isDeterminate\n ? {\n 'aria-valuenow': Math.round(clampedValue),\n 'aria-valuemin': 0,\n 'aria-valuemax': 100,\n }\n : {}\n\n const graphic = (\n <span\n ref={ref}\n role={a11yRole}\n aria-label={a11yLabel}\n aria-hidden={!a11yRole ? true : undefined}\n {...a11yValueAttrs}\n className={cn(\n // align-middle:inline context 內讓 SVG 對齊 adjacent text 的 x-height 中線\n //(不加會按 baseline 對齊,在 inline-flex cell 裡視覺下沉 1-2px 看起來歪)\n 'inline-flex shrink-0 align-middle text-info',\n // motion-reduce:Material 流派 — prefers-reduced-motion 時不停止旋轉(loading 仍需可見回饋),\n // 而是放慢到 3s/cycle(預設 1s),保留資訊不刺激前庭。\n !isDeterminate && 'animate-spin motion-reduce:[animation-duration:3s]',\n className,\n )}\n style={{ width: size, height: size }}\n {...props}\n >\n <svg viewBox={`0 0 ${size} ${size}`} width={size} height={size} aria-hidden>\n <circle\n cx={size / 2}\n cy={size / 2}\n r={radius}\n fill=\"none\"\n stroke=\"var(--secondary)\"\n strokeWidth={strokeWidth}\n />\n <circle\n cx={size / 2}\n cy={size / 2}\n r={radius}\n fill=\"none\"\n stroke=\"currentColor\"\n strokeWidth={strokeWidth}\n strokeDasharray={circumference}\n strokeDashoffset={dashOffset}\n strokeLinecap=\"round\"\n transform={`rotate(-90 ${size / 2} ${size / 2})`}\n className={isDeterminate ? 'transition-[stroke-dashoffset] duration-300' : undefined}\n />\n </svg>\n </span>\n )\n\n // 單純 graphic(無 label / affix)\n if (!hasLabel && !affixNode) return graphic\n\n return (\n <span className={cn('inline-flex items-center', (hasLabel \|\| affixNode) && 'gap-2')}>\n {graphic}\n {hasLabel && <span className=\"text-fg-muted\">{label}</span>}\n {affixNode}\n </span>\n )\n },\n)\nCircularProgress.displayName = 'CircularProgress'\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 circularProgressMeta = {\n component: 'CircularProgress',\n family: null, // non-family composite / overlay / layout\n variants: {\n\n },\n sizes: {\n\n },\n states: ['default'], // 無 hover / focus / active(spec);disabled 屬 consumer host(spec「邊界案例」)\n tokens: {\n bg: [],\n fg: ['text-fg-muted', 'text-foreground', 'text-info'],\n ring: [],\n },\n} as const\n\nexport { CircularProgress }\n"],"names":[],"mappings":"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"}

package/dist/components/Coachmark/coachmark.d.ts CHANGED Viewed

@@ -19,9 +19,9 @@ import * as React from 'react';
  *   3. **Multi step 中間 / 最後步**(有 `onPrev`):**Skip 不顯示**(使用者已投入進度,
  *      再給 Skip 會讓「放棄」入口與「回上一步」衝突 — Linear / Pendo / Shepherd.js
  *      同樣規則)。CTA = `isLastStep ? 'Done' : 'Next'`
- *   4. **不強制 autoFocus 任何按鈕** — Radix Popover 預設 focus 第一個 focusable
- *      (通常是 Prev 或 Skip),本元件不額外拉焦點到 Next,避免使用者以為一按 Enter
- *      就會推進(實際上可能還在讀 body)。想推進者 tab 到 Next 再 Enter。
+ *   4. **抑制開啟時的自動 focus** — `onOpenAutoFocus` preventDefault,連 Radix 預設
+ *      focus 第一個 focusable 也一併抑制(焦點停在 trigger),避免使用者還在讀 body 時
+ *      按 Enter 誤推進。想推進者自行 tab 到 CTA 再 Enter(對齊 spec「A11y 預設」)。
  *
  * ── 為什麼 Body+Footer 消費 overlay-surface ──
  * 避免 padding token 漂移:Dialog / Popover / Coachmark 三者共用同一套 Header/Body/Footer
@@ -89,7 +89,7 @@ export declare const coachmarkMeta: {
     readonly family: null;
     readonly variants: {};
     readonly sizes: {};
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly states: readonly ["default"];
     readonly tokens: {
         readonly bg: readonly ["bg-muted"];
         readonly fg: readonly ["text-fg-secondary", "text-foreground"];

package/dist/components/Coachmark/coachmark.js CHANGED Viewed

@@ -97,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 CHANGED Viewed

	@@ -1 +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 // 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', '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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"}
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. 抑制開啟時的自動 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/Combobox/combobox.d.ts.map CHANGED Viewed

	@@ -1 +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,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;~~AAqVD~~,QAAA,MAAM,QAAQ,sFAab,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}
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,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;AA8VD,QAAA,MAAM,QAAQ,sFAab,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/Combobox/combobox.js CHANGED Viewed

@@ -207,7 +207,7 @@ function ReadonlyMultiSelect({
       }
     );
   }
-  return /* @__PURE__ */ jsx(
+  return /* @__PURE__ */ jsxs(
     "div",
     {
       ref: containerRef,
@@ -222,17 +222,21 @@ function ReadonlyMultiSelect({
       ),
       style: { gap: GAP, ...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 : true) && /* @__PURE__ */ jsx(ItemSuffix, { className: "pointer-events-none", children: /* @__PURE__ */ jsx(ChevronDown, { size: iconSize, className: cn("shrink-0", resolvedMode === "disabled" ? "text-fg-disabled" : "text-fg-muted"), "aria-hidden": true }) })
+      ]
     }
   );
 }
@@ -484,7 +488,7 @@ function CustomCombobox({
       "data-error": error ? "" : void 0,
       onKeyDown: (e) => {
         if (e.key === "Enter" || e.key === " ") {
-          if (!searchable) {
+          if (!open) {
             e.preventDefault();
             setOpen(true);
           }