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

package/src/components/Chip/chip.tsx

@@ -20,10 +20,14 @@ import {
 } from '@/design-system/patterns/horizontal-overflow/horizontal-overflow'
 
 /**
- * Chip — Material Design Filter Chip
+ * Chip — Material Design Chips(filter + assist 兩分支)
  *
- * 基於 Radix ToggleGroup，橋接設計系統 token。
- * 必須在 <ChipGroup> 內使用。
+ * filter(預設):基於 Radix ToggleGroup,多/單選 pill;必須在 <ChipGroup> 內使用。
+ * assist(2026-09-02 加,AgentPanel 附件拍板消費):M3 assist chip 分支 —— 按鈕語意、
+ * 無 toggle、無 selected 態(https://m3.material.io/components/chips/guidelines「Assist chips」);
+ * 渲染 plain button,可獨立使用(不需 ChipGroup)。兩分支視覺同款(單一 cva;
+ * assist 無 data-state 故 selected 樣式天然不生效),差異=結構分支(conditional rendering,
+ * 非 cva variant — 對齊 cva-patterns「結構 variant 用 conditional rendering」)。
  *
  * ── 內部結構（鏡射 Button）──
  *   [startIcon?] [<span px-1>label</span>] [<span gap-1>badge? + endIcon?</span>]
@@ -33,9 +37,9 @@ import {
  *   對齊 Material 3 / Atlassian / Polaris 世界級共識
  *
  * ── State ──
- *   default   bg-surface border-border text-foreground
- *   hover     border-border-hover（對齊 Input / SegmentedControl）
- *   selected  bg-primary-subtle border-primary-hover text-primary-hover
+ *   default   bg-surface border-border text-fg-secondary
+ *   hover     border-border-hover text-foreground（對齊 Input / SegmentedControl）
+ *   selected  bg-surface（不變） border-primary text-primary
  *   disabled  cursor-not-allowed text-fg-disabled
  *
  * ── 詳見 chip.spec.md ──
@@ -56,19 +60,30 @@ const chipVariants = cva(
     'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
     // hover（未選）：border 加深一階 + 文字轉深，對齊 Input / SegmentedControl hover
     'hover:border-border-hover hover:text-foreground',
-    // selected: 文字 + 邊框都用 primary-hover,底色維持 bg-surface 不變
-    //   ── pill 風格 canonical 選中規則,跟 SegmentedControl 完全一致:
-    //      primary-hover 同時染文字和線條;底色不改 (不用 primary-subtle)。
-    'data-[state=on]:border-primary-hover data-[state=on]:text-primary-hover',
+    // selected: 文字 + 邊框都用 primary base,底色維持 bg-surface 不變
+    //   ── pill 風格 canonical 選中規則,跟 SegmentedControl 完全一致(SSOT = semantic.css「選中狀態」段):
+    //      primary base 同時染文字和線條;底色不改 (不用 primary-subtle)。
+    //   2026-07-06 user 拍板:持續選中 hover 階 → base — Ant(pagination/tabs/input focus 全 base)/
+    //   Atlassian(selected = brand 同顆)/ Material 3(active tab = primary)三家實錘「瞬時弱、持續強」;
+    //   hover 階專屬瞬時態(hover/預覽),持續選中站 base。
+    'data-[state=on]:border-primary data-[state=on]:text-primary',
+    // 選中之上的 hover = 同色相升 hover 階(2026-07-06 user 拍板;Button pressed hover
+    // data-[state=on]:hover:text-primary-hover 家族 + Ant active 頁 hover = colorPrimaryHover
+    // 同派)。原本靠 CSS 平手 source-order 讓選中「碰巧」贏過未選 hover(靜止無回饋)= 脆弱,
+    // 顯式宣告一併解掉。
+    'data-[state=on]:hover:border-primary-hover data-[state=on]:hover:text-primary-hover',
     // disabled：cursor-not-allowed + 鎖 hover 不變色
     // 不用 pointer-events-none（否則 cursor-not-allowed 不會顯示）
     'disabled:cursor-not-allowed disabled:text-fg-disabled',
     'disabled:hover:border-border disabled:hover:text-fg-disabled',
+    // disabled × selected 疊加(2026-07-07 user 拍板統一;M24 state > emphasis:disabled 全滅,
+    // 選中的 primary 描邊/染字一併退場——原本只滅字不滅框 = 半滅,Checkbox checked+disabled 全滅同族)
+    'data-[state=on]:disabled:border-border data-[state=on]:disabled:text-fg-disabled',
+    'data-[state=on]:disabled:hover:border-border data-[state=on]:disabled:hover:text-fg-disabled',
   ]
 )
 
-export interface ChipProps
-  extends React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> {
+interface ChipSlotProps {
   /** 左側 icon（LucideIcon），最多一個 */
   startIcon?: LucideIcon
   /** 右側 badge（通常是計數指示器）*/
@@ -77,29 +92,65 @@ export interface ChipProps
   endIcon?: LucideIcon
 }
 
-const Chip = React.forwardRef<
-  React.ElementRef<typeof ToggleGroupPrimitive.Item>,
-  ChipProps
->(({ className, startIcon: StartIcon, badge, endIcon: EndIcon, children, ...props }, ref) => {
-  const hasSuffix = badge != null || EndIcon !== undefined
+export interface ChipFilterProps
+  // 2026-07-14 dim-9 修:Omit 'asChild' — chip.spec.md 禁止事項明載「❌ 用 asChild——不支援」,
+  // 且內部固定渲染 {icon}{label}{suffix} 多 children 結構,asChild(Radix Slot 要求單一
+  // element child)會 runtime throw(CLAUDE.md 失敗記憶「asChild ? Slot : Native」條)。
+  // 型別層 Omit 讓誤用在編譯期失敗,對齊 spec-vs-type 一致。
+  extends Omit<React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item>, 'asChild'>,
+    ChipSlotProps {
+  /** filter(預設):Radix ToggleGroup item,必須在 ChipGroup 內。 */
+  variant?: 'filter'
+}
 
-  return (
-    <ToggleGroupPrimitive.Item
-      ref={ref}
-      className={cn(chipVariants(), className)}
-      {...props}
-    >
-      {StartIcon && <StartIcon size={16} aria-hidden />}
-      {children != null && <span className="px-1">{children}</span>}
-      {hasSuffix && (
-        <span className="inline-flex items-center gap-1">
-          {badge}
-          {EndIcon && <EndIcon size={16} aria-hidden />}
-        </span>
-      )}
-    </ToggleGroupPrimitive.Item>
-  )
-})
+export interface ChipAssistProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    ChipSlotProps {
+  /** assist:M3 assist chip — 按鈕語意、無 toggle、無 selected 態;可獨立使用。 */
+  variant: 'assist'
+}
+
+export type ChipProps = ChipFilterProps | ChipAssistProps
+
+const Chip = React.forwardRef<HTMLButtonElement, ChipProps>(
+  ({ className, startIcon: StartIcon, badge, endIcon: EndIcon, children, variant, ...props }, ref) => {
+    const hasSuffix = badge != null || EndIcon !== undefined
+    const inner = (
+      <>
+        {StartIcon && <StartIcon size={16} aria-hidden />}
+        {children != null && <span className="px-1">{children}</span>}
+        {hasSuffix && (
+          <span className="inline-flex items-center gap-1">
+            {badge}
+            {EndIcon && <EndIcon size={16} aria-hidden />}
+          </span>
+        )}
+      </>
+    )
+    // assist 分支:plain button(按鈕語意,無 toggle);selected 樣式因無 data-state 天然不生效。
+    if (variant === 'assist') {
+      return (
+        <button
+          ref={ref}
+          type="button"
+          className={cn(chipVariants(), className)}
+          {...(props as React.ButtonHTMLAttributes<HTMLButtonElement>)}
+        >
+          {inner}
+        </button>
+      )
+    }
+    return (
+      <ToggleGroupPrimitive.Item
+        ref={ref}
+        className={cn(chipVariants(), className)}
+        {...(props as React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item>)}
+      >
+        {inner}
+      </ToggleGroupPrimitive.Item>
+    )
+  },
+)
 Chip.displayName = 'Chip'
 
 // ── ChipGroup ────────────────────────────────────────────────────────────────
@@ -208,6 +259,29 @@ ScrollChipGroup.displayName = 'ScrollChipGroup'
 //
 // Fade mask 仍保留(reserveArrowWidth: 0),軟化內容硬邊。
 
+// ── getElementRef(Radix Slot idiom)──────────────────────────────────────────
+// 讀取 child element 既有 ref 而不觸發 React dev deprecation warning:
+// React ≤18 ref 在 element.ref;React 19 起移到 element.props.ref,錯誤側讀取會 fire warning
+// (以 getter 上的 isReactWarning 標記)。抄 Radix UI Slot 的偵測法:
+// https://github.com/radix-ui/primitives/blob/main/packages/react/slot/src/slot.tsx(getElementRef)
+// react-compose-refs 僅為 transitive dep(非 package.json 直接依賴),不直接 import — 最小 local 實作。
+function getElementRef(element: React.ReactElement): React.Ref<HTMLElement> | undefined {
+  // React <=18 dev:props.ref 掛 isReactWarning getter → 真 ref 在 element.ref
+  let getter = Object.getOwnPropertyDescriptor(element.props, 'ref')?.get
+  let mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning
+  if (mayWarn) return (element as unknown as { ref?: React.Ref<HTMLElement> }).ref
+  // React 19 dev:element.ref 掛 isReactWarning getter → 真 ref 在 props.ref
+  getter = Object.getOwnPropertyDescriptor(element, 'ref')?.get
+  mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning
+  if (mayWarn) return (element.props as { ref?: React.Ref<HTMLElement> }).ref
+  // production:兩處擇一
+  return (
+    (element.props as { ref?: React.Ref<HTMLElement> }).ref ??
+    (element as unknown as { ref?: React.Ref<HTMLElement> }).ref ??
+    undefined
+  )
+}
+
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const MenuChipGroup = React.forwardRef<
   HTMLDivElement,
@@ -284,12 +358,22 @@ const MenuChipGroup = React.forwardRef<
     [groupType, groupValue, groupOnValueChange]
   )
 
-  const enhancedItems = items.map((child, i) =>
-    React.cloneElement(
+  // 2026-07-05 fix(deep-audit A.1b):原 cloneElement 直接以 registerItem 覆寫 child ref,
+  // consumer 傳給 Chip 的自有 ref 在 menu layout 會被靜默取代。改 compose — 同時餵
+  // registerItem(scrollIntoView 用)與 child 原 ref(對齊 Radix compose-refs idiom)。
+  const enhancedItems = items.map((child, i) => {
+    const childRef = getElementRef(child)
+    return React.cloneElement(
       child as React.ReactElement<{ ref?: React.Ref<HTMLElement> }>,
-      { ref: registerItem(i) }
+      {
+        ref: (el: HTMLElement | null) => {
+          registerItem(i)(el)
+          if (typeof childRef === 'function') childRef(el)
+          else if (childRef) (childRef as React.MutableRefObject<HTMLElement | null>).current = el
+        },
+      }
     )
-  )
+  })
 
   return (
     <div className="flex items-center gap-2">
@@ -342,16 +426,17 @@ MenuChipGroup.displayName = 'MenuChipGroup'
 export const chipMeta = {
   component: 'Chip',
   family: 3,
-  variants: {
-
-  },
+  // 2026-07-04 audit 填 Phase 2:Chip 單一視覺無 variant 軸(variants 留空為 intentional,非漏填)
+  // 2026-09-02:filter/assist 為結構分支(行為換 plain button,視覺同款)— 非視覺 variant 軸,不入此表
+  variants: {},
   sizes: {
-
+    // 單一尺寸:h-field-sm(28/32 依 density)、icon 16、text-body、px-3(cva 真值)
+    sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'], // selected = data-[state=on](primary base,2026-07-06 拍板);cva 無 active 樣式
   tokens: {
-    bg: ['bg-primary-subtle', 'bg-surface'],
-    fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],
+    bg: ['bg-surface'],
+    fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'],
     ring: ['ring-ring'],
   },
 } as const

package/src/components/Chip/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './chip'

package/src/components/CircularProgress/circular-progress.anatomy.stories.tsx

@@ -0,0 +1,177 @@
+// @anatomy-rationale:
+//   Inspector N/A — size 為自由 number prop,互動決策點少(僅 value / size /
+//     affix),由 Overview + UsageInButton + UsageInline 三個 consumer-context
+//     story 直接示範比建 inspector 更實用。
+//   ColorMatrix N/A — arc 預設固定 text-info;consumer 傳 className="text-current"
+//     才繼承 host(如 Button loading),無 own variant × state 色彩;不會隨狀態變色
+//     (完成 / 失敗由 consumer swap 整個元件,見 spec「不設 status prop」)。
+//   SizeMatrix N/A — size 為自由 number,Button / Input 等 consumer 內部依規
+//     則程式化縮放(field iconSize),由 UsageInButton / UsageInline 涵蓋。
+//   StateBehavior N/A — 無 hover / focus / active 狀態(載入中是唯一狀態)。
+import type { Meta, StoryObj } from '@storybook/react'
+import { CircularProgress } from './circular-progress'
+import { Button } from '@/design-system/components/Button/button'
+import { Input } from '@/design-system/components/Input/input'
+import { H3, Desc, Td, Th } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+/**
+ * CircularProgress 是整個設計系統「圓形進度」的單一來源——同時支援兩種模式:
+ * 不傳 value 時是旋轉的載入動畫(indeterminate),傳了 value 時是固定弧長的
+ * 進度圈(determinate,有底圈 + 進度弧)。
+ *
+ * 這頁只放四個範例:元件總覽、在 Button 載入狀態內、行內使用、無障礙。
+ * 沒有另外做尺寸對照、顏色對照、互動狀態等示範,原因是:
+ * - 尺寸是自由數值(非 sm/md/lg 階),由 Button / Input 等容器內部依規則自動縮放,
+ *   範例裡直接示範比列舉一堆尺寸更實用。
+ * - 顏色不隨狀態變色,預設固定 text-info(傳 text-current 才繼承容器文字色),沒有需要對照的色彩組合。
+ * - 元件本身沒有 hover / focus / active 等互動狀態,唯一會變的是進度值本身。
+ */
+
+const meta: Meta = {
+  title: 'Design System/Components/CircularProgress/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>
+          SVG 雙 circle:底 track(<span className="font-mono">var(--secondary)</span>)+ 進度 arc
+          (<span className="font-mono">currentColor</span>)。indeterminate 模式 arc 固定 25%,外層
+          <span className="font-mono">animate-spin</span> 旋轉;determinate 模式 arc 長度 = value/100。
+          strokeWidth 動態 scale = <span className="font-mono">max(2, size/10)</span>。
+        </Desc>
+        <div className="flex items-center gap-6 border border-border rounded-lg p-6">
+          {/* CircularProgress 只有一種預設尺寸(24)。其他尺寸 **不**示範 —
+              consumer 在 Button / Input / Empty 等 context 內由這些元件自動依原則縮放
+              (見 spec.md「Size canonical」+ UsageInButton / UsageInline 兩個 context story)。
+              Overview 只展示 indeterminate + determinate 兩種模式。 */}
+          <CircularProgress aria-label="載入中" />
+          <CircularProgress value={60} aria-label="載入進度 60%" />
+          <span className="text-caption text-fg-muted font-mono">
+            indeterminate(不傳 value)· determinate(value=60)
+          </span>
+        </div>
+      </div>
+
+      <div>
+        <H3>Props 速查</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              {[
+                ['value', 'number (0-100)', '—', '有值 → determinate(arc 固定)/ 無值 → indeterminate(旋轉)'],
+                ['size', 'number', '24', '直徑 px,≤ 64 建議;Button / Input 內部程式化'],
+                ['label', 'string', '—', 'inline label,font-size 繼承 parent,色鎖 text-fg-muted'],
+                ['affix', "'value' | ReactNode", '—', 'Determinate 右側附加(indeterminate 忽略);「已完成」不走此 prop,由 consumer 端 swap 整個元件'],
+                ['className', 'string', '—', '常用 text-current 讓 arc 色繼承父層(Button loading)'],
+              ].map(([p, t, d, desc]) => (
+                <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+        <p className="text-footnote text-fg-muted mt-3">
+          色彩策略:固定 <span className="font-mono">text-info</span>;Button loading 傳
+          <span className="font-mono"> className="text-current" </span>讓 arc 繼承 button
+          foreground(常為白色)。不隨狀態變色——「完成 / 失敗」由 consumer 端 swap 整個元件
+          呈現(見 spec「不設 status prop」)。
+        </p>
+      </div>
+    </div>
+  ),
+}
+
+export const UsageInButton: Story = {
+  name: '在 Button 載入中 狀態內',
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div>
+        <H3>Button loading</H3>
+        <Desc>
+          Button 的 <span className="font-mono">loading</span> prop 內部渲染 CircularProgress
+          (indeterminate 模式)替代 startIcon——是最常見的 CircularProgress 消費場景。
+          color 透過 <span className="font-mono">className="text-current"</span> 繼承 Button 的 foreground。
+        </Desc>
+        <div className="flex items-center gap-3">
+          <Button variant="primary" loading>儲存中</Button>
+          <Button variant="secondary" loading>處理中</Button>
+          <Button variant="tertiary" loading>載入中</Button>
+        </div>
+      </div>
+
+      <div>
+        <H3>Icon-only loading</H3>
+        <div className="flex items-center gap-3">
+          <Button variant="tertiary" size="sm" iconOnly loading aria-label="儲存中" />
+          <Button variant="tertiary" size="md" iconOnly loading aria-label="處理中" />
+          <Button variant="tertiary" size="lg" iconOnly loading aria-label="載入中" />
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const UsageInline: Story = {
+  name: '行內使用',
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div>
+        <H3>Cell / Table row 局部 loading</H3>
+        <div className="flex items-center gap-2 border border-border rounded-md px-3 py-2 max-w-xs">
+          <CircularProgress size={16} aria-label="載入訂單資料中" />
+          <span className="text-body text-fg-muted">載入訂單資料...</span>
+        </div>
+      </div>
+
+      <div>
+        <H3>Field loading state(Input `loading` prop)</H3>
+        <Desc>
+          Input 的 <span className="font-mono">loading</span> prop 內部自動在 endAction slot 塞
+          CircularProgress,size 對齊 field iconSize(sm/md=16,lg=20)。consumer 不手刻 absolute 對齊。
+        </Desc>
+        <Input
+          startIcon={undefined}
+          loading
+          defaultValue="cq@example.com"
+          placeholder="驗證 email 中..."
+          aria-label="Email"
+          className="max-w-sm"
+        />
+      </div>
+
+      <div>
+        <H3>Determinate inline(檔案上傳 %)</H3>
+        <Desc>
+          有進度資訊時傳 <span className="font-mono">value</span>,CircularProgress 切換為
+          determinate 模式(fixed arc + track)。可搭配 <span className="font-mono">affix</span>
+          顯示百分比;完成時 consumer 端 swap 為 Check icon / 結果內容,不做 success morph
+          (見 spec「不設 status prop」)。
+        </Desc>
+        <div className="flex items-center gap-4">
+          <CircularProgress value={25} aria-label="上傳進度 25%" />
+          <CircularProgress value={60} affix="value" aria-label="上傳進度 60%" />
+          <CircularProgress value={90} affix="value" aria-label="上傳進度 90%" />
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙與鍵盤',
+  render: () => (
+    <div className="max-w-3xl text-body text-fg-secondary">
+      <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
+      <p className="whitespace-pre-line">{"本元件不可聚焦、無鍵盤互動(載入指示不接收鍵盤),但會依模式自動輸出對的 ARIA 給輔助技術:\n\n• 有 value(determinate)→ role=\"progressbar\",並帶 aria-valuenow / aria-valuemin=0 / aria-valuemax=100,螢幕報讀器會念出目前進度。\n• 無 value(indeterminate)+ 有傳 label 或 aria-label → role=\"status\",把 label 當作 aria-label 念出(例如「載入訂單資料中」)。\n• 無 value 且沒給任何 label → 標記 aria-hidden,交由外層容器(如 Button 的 aria-busy)負責語義。\n\n動畫尊重 prefers-reduced-motion:偏好減少動態的使用者不會看到停止的圈(那會像卡住),indeterminate 旋轉改放慢至 3s/圈(預設 1s)——保留「進行中」訊號、降低前庭刺激(Material 流派)。\n\n當把 CircularProgress 包進互動容器(Button / Card / Link)時,聚焦與鍵盤行為由容器決定。"}</p>
+    </div>
+  ),
+}