@qijenchen/design-system 0.1.0-beta.10

package/dist/components/ScrollArea/scroll-area.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-area.js","sources":["../../../src/components/ScrollArea/scroll-area.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 ScrollAreaPrimitive from '@radix-ui/react-scroll-area'\nimport { cn } from '@/lib/utils'\n\n/**\n * ScrollArea — 自訂樣式的捲動區(Radix ScrollArea primitive 包裝)\n *\n * 世界級對照:shadcn `ScrollArea` / Ant Design scrollable 容器的 pattern。\n *\n * ── 為什麼需要 ScrollArea ──\n * Native scrollbar 跨 OS 不一致:\n *   macOS: overlay(不吃寬度,預設隱藏,滾動時浮出)\n *   Windows / Linux: always-visible(永遠吃 ~15-17px 寬度)\n *\n * 結果:同一個 DataTable / Sheet / Dialog 內容在 macOS 看起來對齊,在 Windows\n * 右側被吃 17px 跑版(「Left pinned + Row Actions」那張圖的問題)。\n *\n * ScrollArea 用 Radix 包裝自建 overlay 捲軸 → **跨 OS 一致不吃寬度**,\n * 捲動時浮現(hover / scroll 自動顯示)。\n *\n * ── 何時用 ──\n * - DataTable 橫向捲動(水平跑版最明顯場景)\n * - Sheet / Dialog 垂直內容捲動(body 太長)\n * - Sidebar nav 長列表\n * - 任何「內容可能溢出容器」且「跨 OS 視覺必須一致」的場景\n *\n * ── 何時不用 ──\n * - 全頁捲動(瀏覽器 document scroll,保持 native 即可;ScrollArea 是 sub-region)\n * - 單行 truncate(用 text-overflow:ellipsis 就夠)\n * - 極短內容(不會捲動 → 不需 wrapper)\n */\n\nconst ScrollArea = React.forwardRef<\n  React.ElementRef<typeof ScrollAreaPrimitive.Root>,\n  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root>\n>(({ className, children, ...props }, ref) => (\n  <ScrollAreaPrimitive.Root\n    ref={ref}\n    className={cn('relative flex flex-col overflow-hidden', className)}\n    {...props}\n  >\n    {/* Viewport canonical(2026-04-23):Root 用 `flex flex-col`,Viewport 用 `flex-1 min-h-0`。\n        原 `h-full` 在 Root 為 flex item(外層 flex-1 min-h-0)時失效 — Chrome 不把\n        flex-computed 高度視為 `height: 100%` 的 definite anchor,導致 Viewport 撐成\n        content height 而非 parent height → 失去 scroll 能力。\n        改 Root 為 flex container,Viewport 成 flex item,flex algorithm 給 definite height。\n        `w-full` 保留(水平維度不受影響)。 */}\n    {/* a11y(2026-04-25 axe scrollable-region-focusable fix):Viewport 需 tabIndex=0\n        才能 keyboard focus(Safari 不自動把 scroll container 標 focusable)。focus-\n        visible:outline 用 DS focus ring,不破壞視覺。 */}\n    <ScrollAreaPrimitive.Viewport\n      tabIndex={0}\n      className=\"flex-1 min-h-0 w-full rounded-[inherit] focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-primary\"\n    >\n      {children}\n    </ScrollAreaPrimitive.Viewport>\n    <ScrollBar />\n    <ScrollAreaPrimitive.Corner />\n  </ScrollAreaPrimitive.Root>\n))\nScrollArea.displayName = 'ScrollArea'\n\nconst ScrollBar = React.forwardRef<\n  React.ElementRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>,\n  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>\n>(({ className, orientation = 'vertical', ...props }, ref) => (\n  <ScrollAreaPrimitive.ScrollAreaScrollbar\n    ref={ref}\n    orientation={orientation}\n    className={cn(\n      'flex touch-none select-none transition-colors',\n      orientation === 'vertical' && 'h-full w-2.5 border-l border-l-transparent p-[1px]',\n      orientation === 'horizontal' && 'h-2.5 flex-col border-t border-t-transparent p-[1px]',\n      className,\n    )}\n    {...props}\n  >\n    {/* Thumb 用 scrollbar-thumb / -hover semantic alias(2026-05-09 抽 SSOT,跟 DataTable fake scrollbar\n         共享 token)。Token 值仍 = `--border` / `--border-hover`(neutral-5/-6)— 世界級 SaaS\n         (Linear / Notion / Figma / macOS)scrollbar thumb 慣例「很淡、幾乎看不見,hover 略深」。\n         前身直接 `bg-border` borrowing(2026-04 ship)→ semantic alias 收斂 SSOT(避免 thumb 視覺\n         未來演化時誤動 Field/Input/Checkbox border 視覺)。對齊 shadcn ScrollArea source `bg-border`。 */}\n    <ScrollAreaPrimitive.ScrollAreaThumb\n      className={cn('relative flex-1 rounded-full bg-[var(--scrollbar-thumb)] hover:bg-[var(--scrollbar-thumb-hover)] transition-colors')}\n    />\n  </ScrollAreaPrimitive.ScrollAreaScrollbar>\n))\nScrollBar.displayName = ScrollAreaPrimitive.ScrollAreaScrollbar.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 scrollAreaMeta = {\n  component: 'ScrollArea',\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: [],\n    ring: [],\n  },\n} as const\n\nexport { ScrollArea, ScrollBar }\n"],"names":[],"mappings":";;;;AAiCA,MAAM,aAAa,MAAM,WAGvB,CAAC,EAAE,WAAW,UAAU,GAAG,SAAS,QACpC;AAAA,EAAC,oBAAoB;AAAA,EAApB;AAAA,IACC;AAAA,IACA,WAAW,GAAG,0CAA0C,SAAS;AAAA,IAChE,GAAG;AAAA,IAWJ,UAAA;AAAA,MAAA;AAAA,QAAC,oBAAoB;AAAA,QAApB;AAAA,UACC,UAAU;AAAA,UACV,WAAU;AAAA,UAET;AAAA,QAAA;AAAA,MAAA;AAAA,0BAEF,WAAA,EAAU;AAAA,MACX,oBAAC,oBAAoB,QAApB,CAAA,CAA2B;AAAA,IAAA;AAAA,EAAA;AAC9B,CACD;AACD,WAAW,cAAc;AAEzB,MAAM,YAAY,MAAM,WAGtB,CAAC,EAAE,WAAW,cAAc,YAAY,GAAG,SAAS,QACpD;AAAA,EAAC,oBAAoB;AAAA,EAApB;AAAA,IACC;AAAA,IACA;AAAA,IACA,WAAW;AAAA,MACT;AAAA,MACA,gBAAgB,cAAc;AAAA,MAC9B,gBAAgB,gBAAgB;AAAA,MAChC;AAAA,IAAA;AAAA,IAED,GAAG;AAAA,IAOJ,UAAA;AAAA,MAAC,oBAAoB;AAAA,MAApB;AAAA,QACC,WAAW,GAAG,oHAAoH;AAAA,MAAA;AAAA,IAAA;AAAA,EACpI;AACF,CACD;AACD,UAAU,cAAc,oBAAoB,oBAAoB;AAIzD,MAAM,iBAAiB;AAAA,EAC5B,WAAW;AAAA,EACX,QAAQ;AAAA;AAAA,EACR,UAAU,CAAA;AAAA,EAGV,OAAO,CAAA;AAAA,EAGP,QAAQ,CAAC,WAAW,SAAS,UAAU,iBAAiB,UAAU;AAAA,EAClE,QAAQ;AAAA,IACN,IAAI,CAAA;AAAA,IACJ,IAAI,CAAA;AAAA,IACJ,MAAM,CAAA;AAAA,EAAC;AAEX;"}

package/dist/components/SegmentedControl/segmented-control.d.ts

@@ -0,0 +1,102 @@
+import * as React from 'react';
+import * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group';
+import type { LucideIcon } from 'lucide-react';
+/**
+ * SegmentedControl — 互斥多選一的 value 選擇器
+ *
+ * 基於 Radix ToggleGroup（寫死 type="single"），橋接設計系統 token。
+ * 內部 item 結構鏡射 Button，但兩者型別獨立。
+ *
+ * ── 定位 ──
+ *   切 value（不是切 view）。塞得進 Field，Tabs 不行。
+ *   切 view → Tabs；單一 on/off → Button pressed；>5 個選項 → Select。
+ *
+ * ── Size（對齊 field-height / Button 系列）──
+ *   xs   h-field-xs（24 固定）
+ *   sm   h-field-sm（28/32）
+ *   md   h-field-md（32/36）★ 預設（跟 Button / Input / 所有 field-height 系列一致）
+ *   lg   h-field-lg（36/40）
+ *
+ * ── fullWidth ──
+ *   false  ★ 預設，item 寬度由內容決定（hug content）
+ *   true   SegmentedControl 撐滿父容器寬度，所有 item 等分
+ *
+ * ── Item 結構 ──
+ *   [startIcon?] [<span px-1>label</span>] [<span gap-1>suffix?</span>]
+ *   suffix 目前只支援 badge；endIcon 為保留 slot、未開放
+ *
+ * ── iconOnly（group-level）──
+ *   整組同時 icon-only 或全帶 label，不可混搭。
+ */
+type SegmentedControlSize = 'xs' | 'sm' | 'md' | 'lg';
+declare const segmentedControlVariants: (props?: ({
+    fullWidth?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface SegmentedControlProps extends Omit<React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root>, 'type' | 'defaultValue' | 'value' | 'onValueChange'> {
+    size?: SegmentedControlSize;
+    /** 撐滿父容器寬度，所有 item 等分。預設 false（hug content） */
+    fullWidth?: boolean;
+    iconOnly?: boolean;
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+}
+declare const SegmentedControl: React.ForwardRefExoticComponent<SegmentedControlProps & React.RefAttributes<HTMLDivElement>>;
+declare const itemVariants: (props?: ({
+    size?: "sm" | "md" | "lg" | "xs" | null | undefined;
+    fullWidth?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface SegmentedControlItemProps extends React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> {
+    /** 左側 icon（LucideIcon）。group iconOnly = true 時必填。 */
+    startIcon?: LucideIcon;
+    /** 右側 suffix badge（通常是計數指示器）。group iconOnly = true 時會被忽略。 */
+    badge?: React.ReactNode;
+    /**
+     * 無障礙名稱。帶 label 時可選（label 已傳達語意），
+     * 但 group iconOnly = true 時必填——同時驅動 screen reader 和自動 tooltip。
+     */
+    'aria-label'?: string;
+    children?: React.ReactNode;
+}
+declare const SegmentedControlItem: React.ForwardRefExoticComponent<SegmentedControlItemProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const segmentedControlMeta: {
+    readonly component: "SegmentedControl";
+    readonly family: null;
+    readonly variants: {};
+    readonly sizes: {
+        readonly xs: {
+            readonly fieldHeight: 24;
+            readonly typography: "caption";
+            readonly iconSize: 14;
+            readonly purpose: "row-embedded inline action / DataTable inline filter";
+        };
+        readonly sm: {
+            readonly fieldHeight: 28;
+            readonly typography: "body";
+            readonly iconSize: 16;
+            readonly purpose: "compact chrome bar / dense toolbar";
+        };
+        readonly md: {
+            readonly fieldHeight: 32;
+            readonly typography: "body";
+            readonly iconSize: 16;
+            readonly purpose: "預設 — form field 對齊";
+        };
+        readonly lg: {
+            readonly fieldHeight: 36;
+            readonly typography: "body-lg";
+            readonly iconSize: 20;
+            readonly purpose: "touch / prominent CTA";
+        };
+    };
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly ["bg-surface"];
+        readonly fg: readonly ["text-fg-disabled", "text-fg-secondary", "text-foreground"];
+        readonly ring: readonly ["ring-ring"];
+    };
+    readonly defaultSize: "md";
+};
+export { SegmentedControl, SegmentedControlItem, segmentedControlVariants, itemVariants as segmentedControlItemVariants };
+export type { SegmentedControlSize };
+//# sourceMappingURL=segmented-control.d.ts.map

package/dist/components/SegmentedControl/segmented-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segmented-control.d.ts","sourceRoot":"","sources":["../../../src/components/SegmentedControl/segmented-control.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,oBAAoB,MAAM,8BAA8B,CAAA;AAEpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAM9C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,KAAK,oBAAoB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAiBrD,QAAA,MAAM,wBAAwB;;8EAa7B,CAAA;AAED,MAAM,WAAW,qBACf,SAAQ,IAAI,CACR,KAAK,CAAC,wBAAwB,CAAC,OAAO,oBAAoB,CAAC,IAAI,CAAC,EAChE,MAAM,GAAG,cAAc,GAAG,OAAO,GAAG,eAAe,CACpD;IACH,IAAI,CAAC,EAAE,oBAAoB,CAAA;IAC3B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC;AAED,QAAA,MAAM,gBAAgB,8FAqDrB,CAAA;AAmBD,QAAA,MAAM,YAAY;;;8EA0CjB,CAAA;AAMD,MAAM,WAAW,yBACf,SAAQ,KAAK,CAAC,wBAAwB,CAAC,OAAO,oBAAoB,CAAC,IAAI,CAAC;IACxE,qDAAqD;IACrD,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED,QAAA,MAAM,oBAAoB,qGA2DxB,CAAA;AAMF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiBvB,CAAA;AAEV,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,YAAY,IAAI,4BAA4B,EAAE,CAAA;AACzH,YAAY,EAAE,oBAAoB,EAAE,CAAA"}

package/dist/components/SegmentedControl/segmented-control.js

@@ -0,0 +1,171 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group";
+import { cva } from "class-variance-authority";
+import { cn } from "../../lib/utils.js";
+import { useFieldContext } from "../Field/field-context.js";
+import { Tooltip, TooltipTrigger, TooltipContent } from "../Tooltip/tooltip.js";
+import { ICON_SIZE } from "../../patterns/element-anatomy/item-anatomy.js";
+const SegmentedControlContext = React.createContext({
+  size: "md",
+  fullWidth: false,
+  iconOnly: false,
+  disabled: false
+});
+const segmentedControlVariants = cva(
+  "flex items-stretch rounded-md",
+  {
+    variants: {
+      fullWidth: {
+        true: "w-full",
+        false: "w-fit"
+      }
+    },
+    defaultVariants: {
+      fullWidth: false
+    }
+  }
+);
+const SegmentedControl = React.forwardRef(
+  ({
+    className,
+    size: sizeProp,
+    fullWidth = false,
+    iconOnly = false,
+    disabled = false,
+    children,
+    value,
+    defaultValue,
+    onValueChange,
+    ...props
+  }, ref) => {
+    var _a;
+    const fieldCtx = (_a = useFieldContext) == null ? void 0 : _a();
+    const resolvedSize = sizeProp ?? (fieldCtx == null ? void 0 : fieldCtx.size) ?? "md";
+    const resolvedDisabled = disabled || !!(fieldCtx == null ? void 0 : fieldCtx.disabled);
+    const ctxValue = React.useMemo(
+      () => ({ size: resolvedSize, fullWidth, iconOnly, disabled: resolvedDisabled }),
+      [resolvedSize, fullWidth, iconOnly, resolvedDisabled]
+    );
+    return /* @__PURE__ */ jsx(SegmentedControlContext.Provider, { value: ctxValue, children: /* @__PURE__ */ jsx(
+      ToggleGroupPrimitive.Root,
+      {
+        ref,
+        type: "single",
+        value,
+        defaultValue,
+        onValueChange: (v) => {
+          if (v) onValueChange == null ? void 0 : onValueChange(v);
+        },
+        disabled: resolvedDisabled,
+        className: cn(segmentedControlVariants({ fullWidth }), className),
+        ...props,
+        children
+      }
+    ) });
+  }
+);
+SegmentedControl.displayName = "SegmentedControl";
+const ICON_ONLY_BASE = "aspect-square p-0 min-w-0 gap-0";
+const itemVariants = cva(
+  [
+    "relative inline-flex items-center justify-center",
+    "whitespace-nowrap font-medium",
+    "border border-border bg-surface text-fg-secondary",
+    "transition-colors duration-150",
+    "cursor-pointer select-none",
+    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:z-20",
+    // disabled：cursor-not-allowed + 鎖住 hover 色（不用 pointer-events-none，否則 cursor 無法變）
+    // button[disabled] 本身擋 click，不需靠 pointer-events: none
+    "disabled:cursor-not-allowed disabled:text-fg-disabled",
+    "disabled:hover:text-fg-disabled disabled:hover:border-border",
+    // hover（未選）：border 加深一階 + 文字轉深，對齊 Input / Chip hover
+    "hover:text-foreground hover:border-border-hover hover:z-[5]",
+    // selected: 文字 + 邊框都用 primary-hover,底色維持 bg-surface 不變 (跟 Chip 一致)
+    //   ── 這是 pill 風格元件 (Chip / SegmentedControl) 的 canonical 選中規則:
+    //      primary-hover 同時染文字和線條;底色不改 (不用 primary-subtle)。
+    //      Tabs 是 underline 風格,規則不同 (文字 foreground + 底線 primary-hover)。
+    //   z-10 讓 border 浮在相鄰 item 之上
+    "data-[state=on]:text-primary-hover data-[state=on]:border-primary-hover data-[state=on]:z-10",
+    // item 連體：除第一個外，-ml-px 讓相鄰 border 重疊
+    "first:rounded-l-md last:rounded-r-md",
+    "[&:not(:first-child)]:-ml-px"
+  ],
+  {
+    variants: {
+      size: {
+        xs: "h-field-xs px-2 text-caption leading-compact gap-0",
+        sm: "h-field-sm px-3 text-body leading-compact gap-1",
+        md: "h-field-md px-3 text-body leading-compact gap-1",
+        lg: "h-field-lg px-3 text-body-lg leading-compact gap-1"
+      },
+      fullWidth: {
+        true: "flex-1 min-w-0",
+        false: ""
+      }
+    },
+    defaultVariants: {
+      size: "md",
+      fullWidth: false
+    }
+  }
+);
+const SegmentedControlItem = React.forwardRef(({ className, startIcon: StartIcon, badge, children, "aria-label": ariaLabel, ...restProps }, ref) => {
+  const { size, fullWidth, iconOnly: groupIconOnly } = React.useContext(SegmentedControlContext);
+  const iconSize = ICON_SIZE[size];
+  const hasSuffix = badge != null;
+  const effectiveIconOnly = groupIconOnly;
+  const itemEl = /* @__PURE__ */ jsxs(
+    ToggleGroupPrimitive.Item,
+    {
+      ref,
+      className: cn(
+        itemVariants({ size, fullWidth }),
+        effectiveIconOnly && ICON_ONLY_BASE,
+        className
+      ),
+      "aria-label": ariaLabel,
+      ...restProps,
+      children: [
+        StartIcon && /* @__PURE__ */ jsx(StartIcon, { size: iconSize, "aria-hidden": true }),
+        !effectiveIconOnly && children != null && /* @__PURE__ */ jsx("span", { className: "px-1", children }),
+        hasSuffix && !effectiveIconOnly && /* @__PURE__ */ jsx("span", { className: "inline-flex items-center gap-1", children: badge })
+      ]
+    }
+  );
+  if (effectiveIconOnly && typeof ariaLabel === "string") {
+    return /* @__PURE__ */ jsxs(Tooltip, { children: [
+      /* @__PURE__ */ jsx(TooltipTrigger, { asChild: true, children: itemEl }),
+      /* @__PURE__ */ jsx(TooltipContent, { children: ariaLabel })
+    ] });
+  }
+  return itemEl;
+});
+SegmentedControlItem.displayName = "SegmentedControlItem";
+const segmentedControlMeta = {
+  component: "SegmentedControl",
+  family: null,
+  // non-family composite / overlay / layout
+  variants: {},
+  sizes: {
+    xs: { fieldHeight: 24, typography: "caption", iconSize: 14, purpose: "row-embedded inline action / DataTable inline filter" },
+    sm: { fieldHeight: 28, typography: "body", iconSize: 16, purpose: "compact chrome bar / dense toolbar" },
+    md: { fieldHeight: 32, typography: "body", iconSize: 16, purpose: "預設 — form field 對齊" },
+    lg: { fieldHeight: 36, typography: "body-lg", iconSize: 20, purpose: "touch / prominent CTA" }
+  },
+  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  tokens: {
+    bg: ["bg-surface"],
+    fg: ["text-fg-disabled", "text-fg-secondary", "text-foreground"],
+    ring: ["ring-ring"]
+  },
+  defaultSize: "md"
+};
+export {
+  SegmentedControl,
+  SegmentedControlItem,
+  itemVariants as segmentedControlItemVariants,
+  segmentedControlMeta,
+  segmentedControlVariants
+};
+//# sourceMappingURL=segmented-control.js.map

package/dist/components/SegmentedControl/segmented-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"segmented-control.js","sources":["../../../src/components/SegmentedControl/segmented-control.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 { useFieldContext } from '@/design-system/components/Field/field-context'\nimport { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'\nimport { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'\n\n/**\n * SegmentedControl — 互斥多選一的 value 選擇器\n *\n * 基於 Radix ToggleGroup（寫死 type=\"single\"），橋接設計系統 token。\n * 內部 item 結構鏡射 Button，但兩者型別獨立。\n *\n * ── 定位 ──\n *   切 value（不是切 view）。塞得進 Field，Tabs 不行。\n *   切 view → Tabs；單一 on/off → Button pressed；>5 個選項 → Select。\n *\n * ── Size（對齊 field-height / Button 系列）──\n *   xs   h-field-xs（24 固定）\n *   sm   h-field-sm（28/32）\n *   md   h-field-md（32/36）★ 預設（跟 Button / Input / 所有 field-height 系列一致）\n *   lg   h-field-lg（36/40）\n *\n * ── fullWidth ──\n *   false  ★ 預設，item 寬度由內容決定（hug content）\n *   true   SegmentedControl 撐滿父容器寬度，所有 item 等分\n *\n * ── Item 結構 ──\n *   [startIcon?] [<span px-1>label</span>] [<span gap-1>suffix?</span>]\n *   suffix 目前只支援 badge；endIcon 為保留 slot、未開放\n *\n * ── iconOnly（group-level）──\n *   整組同時 icon-only 或全帶 label，不可混搭。\n */\n\ntype SegmentedControlSize = 'xs' | 'sm' | 'md' | 'lg'\n\ninterface SegmentedControlContextValue {\n  size: SegmentedControlSize\n  fullWidth: boolean\n  iconOnly: boolean\n  disabled: boolean\n}\n\nconst SegmentedControlContext = React.createContext<SegmentedControlContextValue>({\n  size: 'md',\n  fullWidth: false,\n  iconOnly: false,\n  disabled: false,\n})\n\n// ── Root ──\nconst segmentedControlVariants = cva(\n  'flex items-stretch rounded-md',\n  {\n    variants: {\n      fullWidth: {\n        true: 'w-full',\n        false: 'w-fit',\n      },\n    },\n    defaultVariants: {\n      fullWidth: false,\n    },\n  }\n)\n\nexport interface SegmentedControlProps\n  extends Omit<\n      React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root>,\n      'type' | 'defaultValue' | 'value' | 'onValueChange'\n    > {\n  size?: SegmentedControlSize\n  /** 撐滿父容器寬度，所有 item 等分。預設 false（hug content） */\n  fullWidth?: boolean\n  iconOnly?: boolean\n  value?: string\n  defaultValue?: string\n  onValueChange?: (value: string) => void\n}\n\nconst SegmentedControl = React.forwardRef<\n  React.ElementRef<typeof ToggleGroupPrimitive.Root>,\n  SegmentedControlProps\n>(\n  (\n    {\n      className,\n      size: sizeProp,\n      fullWidth = false,\n      iconOnly = false,\n      disabled = false,\n      children,\n      value,\n      defaultValue,\n      onValueChange,\n      ...props\n    },\n    ref\n  ) => {\n    // Field 內自動讀 size，跟 Button 同機制\n    const fieldCtx = useFieldContext?.()\n    const resolvedSize: SegmentedControlSize =\n      sizeProp ?? (fieldCtx?.size as SegmentedControlSize) ?? 'md'\n    const resolvedDisabled = disabled || !!fieldCtx?.disabled\n\n    // Memoize provider value(2026-04-22 D3 perf audit):避免每次父 render 重建 4-field object\n    // 讓 children SegmentedControlItem 不必要 re-render\n    const ctxValue = React.useMemo(\n      () => ({ size: resolvedSize, fullWidth, iconOnly, disabled: resolvedDisabled }),\n      [resolvedSize, fullWidth, iconOnly, resolvedDisabled],\n    )\n\n    return (\n      <SegmentedControlContext.Provider value={ctxValue}>\n        <ToggleGroupPrimitive.Root\n          ref={ref}\n          type=\"single\"\n          value={value}\n          defaultValue={defaultValue}\n          onValueChange={(v) => {\n            // Radix 的 single ToggleGroup 允許 deselect（返回空字串）\n            // SegmentedControl 是 radio 語意，不允許空值——忽略 deselect\n            if (v) onValueChange?.(v)\n          }}\n          disabled={resolvedDisabled}\n          className={cn(segmentedControlVariants({ fullWidth }), className)}\n          {...props}\n        >\n          {children}\n        </ToggleGroupPrimitive.Root>\n      </SegmentedControlContext.Provider>\n    )\n  }\n)\nSegmentedControl.displayName = 'SegmentedControl'\n\n// ── Item ──\n\n/**\n * Icon-only base — Polaris/Atlassian idiom:`aspect-square + p-0 + flex-center`。\n * 0 magic-number、0 公式、0 border-deduction;flex centering(已在 itemVariants base)\n * 自動將 SVG 視覺置中,任何 size / icon 都自然正方形。\n *\n * 對齊 `Button.tsx` 的 `ICON_ONLY_BASE`(2026-04-25 從 padding-formula 派改 padding-free)。\n * Rule-of-3:目前 2 處 consumer(Button + SegmentedControl),尚未抽 utility/token;\n * 第 3 個 host 加入時抽到 `packages/design-system/src/utils/`。\n *\n * 舊公式 `(field-height - icon)/2` 沒扣 border 2px,造成 SegmentedControl item 從\n * 設計 spec「自然正方形」漂移為 34×32 長方形(2026-04-25 audit 發現)。\n */\nconst ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'\n\nconst itemVariants = cva(\n  [\n    'relative inline-flex items-center justify-center',\n    'whitespace-nowrap font-medium',\n    'border border-border bg-surface text-fg-secondary',\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 focus-visible:z-20',\n    // disabled：cursor-not-allowed + 鎖住 hover 色（不用 pointer-events-none，否則 cursor 無法變）\n    // button[disabled] 本身擋 click，不需靠 pointer-events: none\n    'disabled:cursor-not-allowed disabled:text-fg-disabled',\n    'disabled:hover:text-fg-disabled disabled:hover:border-border',\n    // hover（未選）：border 加深一階 + 文字轉深，對齊 Input / Chip hover\n    'hover:text-foreground hover:border-border-hover hover:z-[5]',\n    // selected: 文字 + 邊框都用 primary-hover,底色維持 bg-surface 不變 (跟 Chip 一致)\n    //   ── 這是 pill 風格元件 (Chip / SegmentedControl) 的 canonical 選中規則:\n    //      primary-hover 同時染文字和線條;底色不改 (不用 primary-subtle)。\n    //      Tabs 是 underline 風格,規則不同 (文字 foreground + 底線 primary-hover)。\n    //   z-10 讓 border 浮在相鄰 item 之上\n    'data-[state=on]:text-primary-hover data-[state=on]:border-primary-hover data-[state=on]:z-10',\n    // item 連體：除第一個外，-ml-px 讓相鄰 border 重疊\n    'first:rounded-l-md last:rounded-r-md',\n    '[&:not(:first-child)]:-ml-px',\n  ],\n  {\n    variants: {\n      size: {\n        xs: 'h-field-xs px-2 text-caption leading-compact gap-0',\n        sm: 'h-field-sm px-3 text-body leading-compact gap-1',\n        md: 'h-field-md px-3 text-body leading-compact gap-1',\n        lg: 'h-field-lg px-3 text-body-lg leading-compact gap-1',\n      },\n      fullWidth: {\n        true: 'flex-1 min-w-0',\n        false: '',\n      },\n    },\n    defaultVariants: {\n      size: 'md',\n      fullWidth: false,\n    },\n  }\n)\n\n// iconOnly 是 group-level 決策（由 <SegmentedControl iconOnly> 控制），\n// 不是 per-item 決策，所以 Item 型別不用 discriminated union 強制 iconOnly。\n// 但當 group iconOnly = true 時，每個 item 必須提供 startIcon + aria-label——\n// 這是語意契約，在 render 階段檢查並在 dev mode 發出警告（TS 層做不到這層檢查）。\nexport interface SegmentedControlItemProps\n  extends React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> {\n  /** 左側 icon（LucideIcon）。group iconOnly = true 時必填。 */\n  startIcon?: LucideIcon\n  /** 右側 suffix badge（通常是計數指示器）。group iconOnly = true 時會被忽略。 */\n  badge?: React.ReactNode\n  /**\n   * 無障礙名稱。帶 label 時可選（label 已傳達語意），\n   * 但 group iconOnly = true 時必填——同時驅動 screen reader 和自動 tooltip。\n   */\n  'aria-label'?: string\n  children?: React.ReactNode\n}\n\nconst SegmentedControlItem = React.forwardRef<\n  React.ElementRef<typeof ToggleGroupPrimitive.Item>,\n  SegmentedControlItemProps\n>(({ className, startIcon: StartIcon, badge, children, 'aria-label': ariaLabel, ...restProps }, ref) => {\n  const { size, fullWidth, iconOnly: groupIconOnly } = React.useContext(SegmentedControlContext)\n  // 2026-05-18 改 per user 拍板「沒機械化導致偏移」+「做完」approval(對齊 Button xs / uiSize Icon Tier):\n  // 原 xs=14 跟 Button xs=16 不一致,xs/sm/md 統一 16 對齊 uiSize.spec.md(xs/sm/md→16, lg→20)。\n  // 2026-05-18 改 import ICON_SIZE SSOT(per user『做完』approval,消除 M17 違反 7+ 重複 ternary)\n  const iconSize = ICON_SIZE[size as 'sm' | 'md' | 'lg']\n  const hasSuffix = badge != null\n\n  // Dev-mode 語意契約檢查：group iconOnly = true 時，item 必須有 startIcon + aria-label\n  if (import.meta.env?.DEV && groupIconOnly) {\n    if (!StartIcon) {\n      console.warn(\n        '[SegmentedControl] iconOnly 群組內的 item 必須提供 startIcon。'\n      )\n    }\n    if (!ariaLabel) {\n      console.warn(\n        '[SegmentedControl] iconOnly 群組內的 item 必須提供 aria-label（作為無障礙名稱與自動 tooltip 來源）。'\n      )\n    }\n  }\n\n  const effectiveIconOnly = groupIconOnly\n\n  const itemEl = (\n    <ToggleGroupPrimitive.Item\n      ref={ref}\n      className={cn(\n        itemVariants({ size, fullWidth }),\n        effectiveIconOnly && ICON_ONLY_BASE,\n        className,\n      )}\n      aria-label={ariaLabel}\n      {...restProps}\n    >\n      {StartIcon && <StartIcon size={iconSize} aria-hidden />}\n      {!effectiveIconOnly && children != null && <span className=\"px-1\">{children}</span>}\n      {/* suffix wrapper：即使目前只有 badge，wrapper 從第一天就存在，\n          未來若開放 endIcon，直接加入此 span 內 gap-1 自動生效 */}\n      {hasSuffix && !effectiveIconOnly && (\n        <span className=\"inline-flex items-center gap-1\">{badge}</span>\n      )}\n    </ToggleGroupPrimitive.Item>\n  )\n\n  // icon-only 自動包 Tooltip（與 Button icon-only 一致）\n  if (effectiveIconOnly && typeof ariaLabel === 'string') {\n    return (\n      <Tooltip>\n        <TooltipTrigger asChild>{itemEl}</TooltipTrigger>\n        <TooltipContent>{ariaLabel}</TooltipContent>\n      </Tooltip>\n    )\n  }\n\n  return itemEl\n})\nSegmentedControlItem.displayName = 'SegmentedControlItem'\n\n// Story auto-compile metadata — Phase 2 fill(2026-05-15)\n// Sizes 真實 cva keys = xs/sm/md/lg(itemVariants.size),映射 field-height-* token tier\n// SegmentedControl 無語意 variant(選中 vs 未選 是 state 不是 variant)— 與 Button.variant 刻意不同(spec「與 Button 的血緣」段)\nexport const segmentedControlMeta = {\n  component: 'SegmentedControl',\n  family: null, // non-family composite / overlay / layout\n  variants: {},\n  sizes: {\n    xs: { fieldHeight: 24, typography: 'caption', iconSize: 14, purpose: 'row-embedded inline action / DataTable inline filter' },\n    sm: { fieldHeight: 28, typography: 'body', iconSize: 16, purpose: 'compact chrome bar / dense toolbar' },\n    md: { fieldHeight: 32, typography: 'body', iconSize: 16, purpose: '預設 — form field 對齊' },\n    lg: { fieldHeight: 36, typography: 'body-lg', iconSize: 20, purpose: 'touch / prominent CTA' },\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  defaultSize: 'md',\n} as const\n\nexport { SegmentedControl, SegmentedControlItem, segmentedControlVariants, itemVariants as segmentedControlItemVariants }\nexport type { SegmentedControlSize }\n"],"names":[],"mappings":"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"}

package/dist/components/Select/select.d.ts

@@ -0,0 +1,102 @@
+import * as React from 'react';
+import type { LucideIcon } from 'lucide-react';
+import type { FieldMode, FieldVariant } from '../../components/Field/field-types';
+import { type SelectMenuOption } from '../../components/SelectMenu/select-menu';
+/**
+ * Select 用的 option schema(2026-05-10 Issue 4 + post-prune unify):**explicit extends
+ * SelectMenuOption(primitive SSOT)** — 任何 SelectMenuOption 加 field 都自動繼承,不會 drift。
+ *
+ * Why `extends SelectMenuOption`(per user 「全盤檢查避免下次又改壞或是偏移」要求):
+ *   - **schema SSOT 機械強制**:TypeScript inheritance 跟著 primitive 走,wrapper consumer 永遠
+ *     拿得到 primitive 所有 surface field
+ *   - **Hook lint**(M30 `check_wrapper_primitive_schema_drift.sh`):grep `interface .*Option`
+ *     未 `extends` SelectMenuOption / 同名重複 declare 直接 BLOCK
+ *
+ * Wrapper-only field(`tagVariant`)— Select 獨有 `display='tag'` 用,SelectMenu primitive 不該知道
+ * 此 wrapper-only concern,所以 wrapper 層 extend 加上,不污染 primitive。
+ *
+ * 對齊 Polaris ChoiceList / Material Autocomplete / Carbon Dropdown 的 wrapper-vs-primitive
+ * schema-extension idiom。
+ */
+export interface SelectOption extends SelectMenuOption {
+    /** Tag 模式的顏色。只在 display='tag' 時生效,對應 Tag 的 variant。Wrapper-only。 */
+    tagVariant?: string;
+}
+/** 分組設定 — 對齊 SelectMenuGroupConfig SSOT */
+export interface SelectGroupConfig {
+    key: string;
+    label: string;
+}
+export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, 'size' | 'value' | 'defaultValue' | 'onChange'> {
+    mode?: FieldMode;
+    /** Field chrome variant. Default = context.variant ?? 'default'. Per-prop override. */
+    variant?: FieldVariant;
+    error?: boolean;
+    size?: 'sm' | 'md' | 'lg';
+    options: SelectOption[];
+    /** 分組顯示(對齊 SelectMenu groups SSOT)。option.group 對應 groups[].key */
+    groups?: SelectGroupConfig[];
+    /** Controlled value(consumer 自管 state)。傳 `value` + `onChange` 表示 controlled mode。 */
+    value?: string | null;
+    /** Uncontrolled 初始值(2026-05-21 D3 audit add per user verbatim「決策三照妳建議」+「都給我做到好」)。
+     *  不傳 `value` 時 Select 自管 internal state,以 `defaultValue` 為初始值,選變更時 fire `onChange`
+     *  callback 通知 consumer(但 state 仍歸 Select)。對齊 Radix Select(`defaultValue`)+ shadcn Input
+     *  (`defaultValue`)+ React `<input>` dual-mode canonical。
+     *  互斥規則:同時傳 `value` + `defaultValue` 走 controlled(value 勝),`defaultValue` 僅 first-mount 用。 */
+    defaultValue?: string | null;
+    onChange?: (value: string) => void;
+    placeholder?: string;
+    clearable?: boolean;
+    display?: 'plain' | 'tag';
+    startIcon?: LucideIcon;
+    /** 啟用搜尋（desktop 時 field 變 input，打字即篩選） */
+    searchable?: boolean;
+    /** Loading state(2026-05-15 audit B fix per user verbatim「dropdown 隨時可開,讀取在 panel 中間 CircularProgress」)。
+     *  Forward 給 SelectMenu primitive SSOT;dropdown 開啟時取代 options 顯 CircularProgress + loadingText。
+     *  Trigger 不變(chevron 保留 user 隨時可點開)。對齊 Field family loading SSOT + Empty 元件 `<Empty icon={CircularProgress}/>` compose。*/
+    loading?: boolean;
+    /** Menu list 最小列數(空狀態 / 選項少時的視覺一致 reserve)。預設 3 — 選項 < 3 時顯式縮(如 And/Or 兩選項) */
+    minRows?: number;
+    /** Initial open state(uncontrolled)。對齊 Radix Popover defaultOpen canonical;DataTable cell-as-input
+     *  click → 1 step open menu(Airtable / Notion canonical),consumer pass `defaultOpen` 達成。
+     *  Note:Native Select(mobile)無 popover 概念,此 prop 僅 Custom path 生效。 */
+    defaultOpen?: boolean;
+    /** open state 變更 callback(對齊 Radix Popover onOpenChange canonical)。
+     *  DataTable cell-as-input 用:open=false 時 cell 自動 exit edit mode(避免 dismiss 後卡住)。 */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Display mode 顯 picker intrinsic end icon(2026-05-08 D path Phase 1)。
+     * 預設 false:`mode="display"` 純展示 bare span(向後相容)。
+     * `variant="naked" && mode="display"` 場景(DataTable cell)opt-in 設 true → wrap 進
+     * Field naked-display + 渲 ChevronDown ItemSuffix。**只 display mode 生效**;readonly /
+     * disabled / edit 已有 Field wrapper + suffix(不受此 prop 影響)。
+     * Authority:`data-table.spec.md:204` + `inline-action.spec.md:157`「Field family endAction(自動繼承)」。
+     * @default false
+     */
+    showDisplayEndIcon?: boolean;
+    /**
+     * Trigger 內「已選項目」客製 render(2026-05-07 v15.5)。
+     *
+     * 設了 → trigger 不走純文字 / Tag 預設 path,改用 consumer 提供的 ReactNode(收 selectedOpt)。
+     * Searchable+open 仍走 input(搜尋優先)。Empty value(no selection)仍走 placeholder。
+     *
+     * 用例:PeoplePicker 用此 slot 把 single 選中的 person render 成 PersonDisplay
+     * (avatar + name)而非純文字 label。對齊 PeoplePicker = Select wrapper SSOT。
+     */
+    selectedItemRenderer?: (selectedOpt: SelectOption) => React.ReactNode;
+}
+declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLDivElement | HTMLSelectElement>>;
+export declare const selectMeta: {
+    readonly component: "Select";
+    readonly family: 4;
+    readonly variants: {};
+    readonly sizes: {};
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly [];
+        readonly fg: readonly ["text-fg-disabled", "text-fg-muted"];
+        readonly ring: readonly [];
+    };
+};
+export { Select };
+//# sourceMappingURL=select.d.ts.map

package/dist/components/Select/select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../src/components/Select/select.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE9C,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAA;AAK3F,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,mDAAmD,CAAA;AAcrG;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IACpD,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACd;AAID,MAAM,WAAW,WACf,SAAQ,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,cAAc,GAAG,UAAU,CAAC;IAC3G,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,uFAAuF;IACvF,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,mEAAmE;IACnE,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC5B,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB;;;;kGAI8F;IAC9F,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,GAAG,KAAK,CAAA;IACzB,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;+HAE2H;IAC3H,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;0EAEsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;yFACqF;IACrF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,CAAC,WAAW,EAAE,YAAY,KAAK,KAAK,CAAC,SAAS,CAAA;CACtE;AA+fD,QAAA,MAAM,MAAM,wGAUX,CAAA;AAKD,eAAO,MAAM,UAAU;;;;;;;;;;;CAeb,CAAA;AAEV,OAAO,EAAE,MAAM,EAAE,CAAA"}