@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

package/dist/components/BulkActionBar/bulk-action-bar.js

@@ -0,0 +1,78 @@
+import { jsxs, jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { X } from "lucide-react";
+import { cn } from "../../lib/utils.js";
+import { Button } from "../Button/button.js";
+import { ButtonDivider } from "../Button/button-group.js";
+const BULK_ACTION_BAR_DEFAULT_LABELS = {
+  count: (n) => `已選 ${n} 項`,
+  clear: "清除選取",
+  hiddenSuffix: (hidden) => `· ${hidden} 個被 filter 隱藏`,
+  toolbarAriaLabel: "批次操作"
+};
+const BulkActionBar = React.forwardRef(
+  function BulkActionBar2({ selection, onClear, actions, hiddenByFilter, totalSelected, labels: labelsOverride, className, ...props }, ref) {
+    const labels = React.useMemo(
+      () => ({ ...BULK_ACTION_BAR_DEFAULT_LABELS, ...labelsOverride }),
+      [labelsOverride]
+    );
+    if (selection.length === 0) return null;
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref,
+        role: "toolbar",
+        "aria-label": labels.toolbarAriaLabel,
+        className: cn(
+          "flex items-center gap-2",
+          "px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]",
+          // 上分隔線:bottom toolbar canonical(Linear / Apple Mail / Notion 共識)— 視覺從上方內容收尾
+          "border-t border-divider",
+          className
+        ),
+        ...props,
+        children: [
+          onClear && /* @__PURE__ */ jsx(
+            Button,
+            {
+              variant: "text",
+              size: "md",
+              iconOnly: true,
+              dismiss: true,
+              startIcon: X,
+              "aria-label": labels.clear,
+              onClick: onClear
+            }
+          ),
+          /* @__PURE__ */ jsxs("span", { className: "text-body text-foreground tabular-nums", children: [
+            labels.count(typeof totalSelected === "number" ? totalSelected : selection.length),
+            hiddenByFilter !== void 0 && hiddenByFilter > 0 && /* @__PURE__ */ jsxs("span", { className: "text-fg-muted font-normal", children: [
+              " ",
+              labels.hiddenSuffix(hiddenByFilter)
+            ] })
+          ] }),
+          actions && /* @__PURE__ */ jsx(ButtonDivider, {}),
+          actions && /* @__PURE__ */ jsx("div", { className: "flex items-center gap-2 flex-1 min-w-0", children: actions })
+        ]
+      }
+    );
+  }
+);
+BulkActionBar.displayName = "BulkActionBar";
+const bulkActionBarMeta = {
+  component: "BulkActionBar",
+  family: null,
+  variants: {},
+  sizes: {},
+  states: ["default"],
+  tokens: {
+    fg: ["text-fg-secondary", "text-fg-muted"],
+    border: ["border-divider"]
+  }
+};
+export {
+  BULK_ACTION_BAR_DEFAULT_LABELS,
+  BulkActionBar,
+  bulkActionBarMeta
+};
+//# sourceMappingURL=bulk-action-bar.js.map

package/dist/components/BulkActionBar/bulk-action-bar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk-action-bar.js","sources":["../../../src/components/BulkActionBar/bulk-action-bar.tsx"],"sourcesContent":["import * as React from 'react'\nimport { X } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Button } from '@/design-system/components/Button/button'\nimport { ButtonDivider } from '@/design-system/components/Button/button-group'\n\n// ── 消費的 SSOT ───────────────────────────────────────────────────────────────\n// - bulk-action-bar.spec.md(本元件 SSOT)\n// - DataTable/data-table.spec.md「L2 選取」(整合方式)\n// - button.spec.md + button-group.tsx(action variant=tertiary,size=sm,\n//   gap-2 + ButtonDivider 自帶 mx-1 = 12px 視覺距離)\n// - inline-action.spec.md「same-row consistency rule」(close X 同尺寸 sm)\n// - tokens/layoutSpace/layoutSpace.spec.md(footer 用 px-loose py-tight)\n// - patterns/overlay-surface/overlay-surface.spec.md SurfaceFooter canonical\n// - Alert(banner)用 description ReactNode 帶 inline link CTA\n\n// ── i18n labels ─────────────────────────────────────────────────────────────\n\n// code-quality-allow: dead-export — public API per spec.md(consumer i18n override hook)\nexport interface BulkActionBarLabels {\n  count: (n: number) => string\n  clear: string\n  hiddenSuffix: (hidden: number) => string\n  toolbarAriaLabel: string\n}\n\n// code-quality-allow: dead-export — public API per spec.md(consumer spread + override)\nexport const BULK_ACTION_BAR_DEFAULT_LABELS: BulkActionBarLabels = {\n  count: (n) => `已選 ${n} 項`,\n  clear: '清除選取',\n  hiddenSuffix: (hidden) => `· ${hidden} 個被 filter 隱藏`,\n  toolbarAriaLabel: '批次操作',\n}\n\n// ── Props ───────────────────────────────────────────────────────────────────\n\nexport interface BulkActionBarProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** 已選 ID,length === 0 時自動隱藏(回傳 null) */\n  selection: readonly string[]\n  /** Clear 觸發,user 點 X icon 或 Esc(consumer 在 page-level 監聽) */\n  onClear?: () => void\n  /** 批次 actions(consumer 提供 sm Button,variant=tertiary 或 tertiary+danger;不用 primary) */\n  actions?: React.ReactNode\n  /** Filter 模式:hidden 數量,顯示在 count 區 inline「{N} 已選 · {M} 個被 filter 隱藏」 */\n  hiddenByFilter?: number\n  /**\n   * 「擴選整個 dataset」狀態(2026-05-13 ship,per user 抓 Alert「已選 5370」但 BulkActionBar\n   * 仍顯「已選 50 項」regression):\n   * - undefined / null(default):count 走 `selection.length`(page-level 視覺選取)\n   * - number:count 走此數值(整個 dataset 擴選後 user 已選的真總數)\n   *\n   * Canonical pattern:consumer 把 BulkActionBar 跟「Alert info banner(提示擴選 dataset)」\n   * 一起 mount,Alert 點「點此選取全部 N 個」→ setTotalSelected(N) → BulkActionBar count 同步。\n   * 對齊 Gmail / Linear / Notion 全選 dataset hint pattern。\n   * 詳 `bulk-action-bar.spec.md`「Extend dataset pattern」段。\n   */\n  totalSelected?: number | null\n  /** i18n labels(Partial,merge with default) */\n  labels?: Partial<BulkActionBarLabels>\n}\n\n// ── Component ───────────────────────────────────────────────────────────────\n// 視覺結構(同 SurfaceFooter / DataTable toolbar canonical):\n//   px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]\n//   gap-2 between elements\n//   全 sm Buttons(same-row consistency)\n//   <ButtonDivider /> 自帶 mx-1 = 12px 視覺距離\n//\n// Hint banner(擴 dataset 提示)完全外包給 Alert 元件 — consumer 視 ref 圖\n// 黏在 BulkActionBar 上方/下方,用 Alert variant=\"info\" placement=\"fixed\"\n// description={inline link JSX}。BulkActionBar 自己不再有 hint banner slot。\n//\n// 浮起 / fixed positioning 由 consumer wrap 決定(BulkActionBar 不限定 placement)。\n\nconst BulkActionBar = React.forwardRef<HTMLDivElement, BulkActionBarProps>(\n  function BulkActionBar(\n    { selection, onClear, actions, hiddenByFilter, totalSelected, labels: labelsOverride, className, ...props },\n    ref\n  ) {\n    const labels: BulkActionBarLabels = React.useMemo(\n      () => ({ ...BULK_ACTION_BAR_DEFAULT_LABELS, ...labelsOverride }),\n      [labelsOverride]\n    )\n\n    // selection.length === 0 自動藏(對齊 spec 禁止事項 #3)\n    if (selection.length === 0) return null\n\n    return (\n      <div\n        ref={ref}\n        role=\"toolbar\"\n        aria-label={labels.toolbarAriaLabel}\n        className={cn(\n          'flex items-center gap-2',\n          'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',\n          // 上分隔線:bottom toolbar canonical(Linear / Apple Mail / Notion 共識)— 視覺從上方內容收尾\n          'border-t border-divider',\n          className\n        )}\n        {...props}\n      >\n        {/* X close — md dismiss(2026-05-04 spec update:default placement = footer variant,\n            visual weight 對齊 Dialog footer commitment buttons md;same-row consistency 維持)\n            未來若有 top-toolbar variant(覆蓋 sm-density toolbar)→ 該 variant override sm */}\n        {onClear && (\n          <Button\n            variant=\"text\"\n            size=\"md\"\n            iconOnly\n            dismiss\n            startIcon={X}\n            aria-label={labels.clear}\n            onClick={onClear}\n          />\n        )}\n\n        {/* count + filter hidden inline\n            color canonical(2026-05-04):count = primary foreground + medium weight\n            理由:count 是 state-bearing 主資訊(「你在 selection mode + N items」),非裝飾\n            World-class 共識:Linear/Notion/Carbon/Polaris 均用 primary foreground;muted 化弱化 state signal\n            hiddenByFilter suffix 維持 muted(這是次資訊,視覺層次正確) */}\n        <span className=\"text-body text-foreground tabular-nums\">\n          {/* 2026-05-13:totalSelected override 走 dataset 擴選後真總數,否則 fallback page-level selection.length */}\n          {labels.count(typeof totalSelected === 'number' ? totalSelected : selection.length)}\n          {hiddenByFilter !== undefined && hiddenByFilter > 0 && (\n            <span className=\"text-fg-muted font-normal\"> {labels.hiddenSuffix(hiddenByFilter)}</span>\n          )}\n        </span>\n\n        {/* divider */}\n        {actions && <ButtonDivider />}\n\n        {/* batch actions slot(consumer 提供 sm Buttons) */}\n        {actions && (\n          <div className=\"flex items-center gap-2 flex-1 min-w-0\">{actions}</div>\n        )}\n      </div>\n    )\n  }\n)\nBulkActionBar.displayName = 'BulkActionBar'\n\n// Story auto-compile metadata\nexport const bulkActionBarMeta = {\n  component: 'BulkActionBar',\n  family: null,\n  variants: {},\n  sizes: {},\n  states: ['default'],\n  tokens: {\n    fg: ['text-fg-secondary', 'text-fg-muted'],\n    border: ['border-divider'],\n  },\n} as const\n\nexport { BulkActionBar }\n"],"names":["BulkActionBar"],"mappings":";;;;;;AA2BO,MAAM,iCAAsD;AAAA,EACjE,OAAO,CAAC,MAAM,MAAM,CAAC;AAAA,EACrB,OAAO;AAAA,EACP,cAAc,CAAC,WAAW,KAAK,MAAM;AAAA,EACrC,kBAAkB;AACpB;AA0CA,MAAM,gBAAgB,MAAM;AAAA,EAC1B,SAASA,eACP,EAAE,WAAW,SAAS,SAAS,gBAAgB,eAAe,QAAQ,gBAAgB,WAAW,GAAG,MAAA,GACpG,KACA;AACA,UAAM,SAA8B,MAAM;AAAA,MACxC,OAAO,EAAE,GAAG,gCAAgC,GAAG;MAC/C,CAAC,cAAc;AAAA,IAAA;AAIjB,QAAI,UAAU,WAAW,EAAG,QAAO;AAEnC,WACE;AAAA,MAAC;AAAA,MAAA;AAAA,QACC;AAAA,QACA,MAAK;AAAA,QACL,cAAY,OAAO;AAAA,QACnB,WAAW;AAAA,UACT;AAAA,UACA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,QAAA;AAAA,QAED,GAAG;AAAA,QAKH,UAAA;AAAA,UAAA,WACC;AAAA,YAAC;AAAA,YAAA;AAAA,cACC,SAAQ;AAAA,cACR,MAAK;AAAA,cACL,UAAQ;AAAA,cACR,SAAO;AAAA,cACP,WAAW;AAAA,cACX,cAAY,OAAO;AAAA,cACnB,SAAS;AAAA,YAAA;AAAA,UAAA;AAAA,UASb,qBAAC,QAAA,EAAK,WAAU,0CAEb,UAAA;AAAA,YAAA,OAAO,MAAM,OAAO,kBAAkB,WAAW,gBAAgB,UAAU,MAAM;AAAA,YACjF,mBAAmB,UAAa,iBAAiB,KAChD,qBAAC,QAAA,EAAK,WAAU,6BAA4B,UAAA;AAAA,cAAA;AAAA,cAAE,OAAO,aAAa,cAAc;AAAA,YAAA,EAAA,CAAE;AAAA,UAAA,GAEtF;AAAA,UAGC,+BAAY,eAAA,EAAc;AAAA,UAG1B,WACC,oBAAC,OAAA,EAAI,WAAU,0CAA0C,UAAA,QAAA,CAAQ;AAAA,QAAA;AAAA,MAAA;AAAA,IAAA;AAAA,EAIzE;AACF;AACA,cAAc,cAAc;AAGrB,MAAM,oBAAoB;AAAA,EAC/B,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,UAAU,CAAA;AAAA,EACV,OAAO,CAAA;AAAA,EACP,QAAQ,CAAC,SAAS;AAAA,EAClB,QAAQ;AAAA,IACN,IAAI,CAAC,qBAAqB,eAAe;AAAA,IACzC,QAAQ,CAAC,gBAAgB;AAAA,EAAA;AAE7B;"}

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

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

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

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

package/dist/components/BulkActionBar/index.js

@@ -0,0 +1,7 @@
+import { BULK_ACTION_BAR_DEFAULT_LABELS, BulkActionBar, bulkActionBarMeta } from "./bulk-action-bar.js";
+export {
+  BULK_ACTION_BAR_DEFAULT_LABELS,
+  BulkActionBar,
+  bulkActionBarMeta
+};
+//# sourceMappingURL=index.js.map

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

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

package/dist/components/Button/button-group.d.ts

@@ -0,0 +1,49 @@
+import * as React from 'react';
+/**
+ * ButtonGroup — 按鈕群組容器
+ *
+ * 負責群組內的間距（gap 8px）與對齊方式。
+ * 垂直排列時透過 ButtonGroupContext 讓所有直接子 Button 自動套用 fullWidth，
+ * 無需 cloneElement — 符合 shadcn 的 Context 慣例。
+ *
+ * @example
+ * // 水平排列（預設）
+ * <ButtonGroup>
+ *   <Button variant="primary">確認</Button>
+ *   <Button variant="tertiary">取消</Button>
+ * </ButtonGroup>
+ *
+ * // 靠右對齊（primary 放右側）
+ * <ButtonGroup align="end">
+ *   <Button variant="tertiary">取消</Button>
+ *   <Button variant="primary">確認</Button>
+ * </ButtonGroup>
+ *
+ * // 垂直排列（fullWidth 自動套用）
+ * <ButtonGroup direction="vertical">
+ *   <Button variant="primary">確認</Button>
+ *   <Button variant="tertiary">取消</Button>
+ * </ButtonGroup>
+ */
+interface ButtonGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** 排列方向，預設 horizontal */
+    direction?: 'horizontal' | 'vertical';
+    /** 水平對齊，預設 start */
+    align?: 'start' | 'center' | 'end';
+}
+declare const ButtonGroup: React.ForwardRefExoticComponent<ButtonGroupProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * ButtonDivider — 按鈕群組內的分隔線
+ *
+ * 自身左右各 4px，與相鄰按鈕形成 8px（gap）+ 4px（自身）= 12px 的視覺距離。
+ *
+ * @example
+ * <ButtonGroup>
+ *   <Button variant="text" size="sm" iconOnly startIcon={Settings} aria-label="設定" />
+ *   <ButtonDivider />
+ *   <Button variant="primary" danger size="sm" iconOnly startIcon={Trash2} aria-label="刪除" />
+ * </ButtonGroup>
+ */
+declare const ButtonDivider: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+export { ButtonGroup, ButtonDivider };
+//# sourceMappingURL=button-group.d.ts.map

package/dist/components/Button/button-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"button-group.d.ts","sourceRoot":"","sources":["../../../src/components/Button/button-group.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAI9B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,UAAU,gBAAiB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IACrE,yBAAyB;IACzB,SAAS,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;IACrC,oBAAoB;IACpB,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAA;CACnC;AAMD,QAAA,MAAM,WAAW,yFAsBhB,CAAA;AAGD;;;;;;;;;;;GAWG;AACH,QAAA,MAAM,aAAa,6GAcjB,CAAA;AAGF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,CAAA"}

package/dist/components/Button/button-group.js

@@ -0,0 +1,46 @@
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../../lib/utils.js";
+import { ButtonGroupContext } from "./button.js";
+const BUTTON_GROUP_CTX_VERTICAL = { fullWidth: true };
+const BUTTON_GROUP_CTX_HORIZONTAL = { fullWidth: false };
+const ButtonGroup = React.forwardRef(
+  ({ direction = "horizontal", align = "start", className, children, ...props }, ref) => {
+    const isVertical = direction === "vertical";
+    return /* @__PURE__ */ jsx(ButtonGroupContext.Provider, { value: isVertical ? BUTTON_GROUP_CTX_VERTICAL : BUTTON_GROUP_CTX_HORIZONTAL, children: /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref,
+        className: cn(
+          "flex gap-2",
+          isVertical ? "flex-col items-stretch" : "flex-row items-center flex-wrap",
+          !isVertical && align === "center" && "justify-center",
+          !isVertical && align === "end" && "justify-end",
+          className
+        ),
+        ...props,
+        children
+      }
+    ) });
+  }
+);
+ButtonGroup.displayName = "ButtonGroup";
+const ButtonDivider = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+  "div",
+  {
+    ref,
+    role: "separator",
+    className: cn(
+      "self-stretch w-px mx-1 my-1",
+      "bg-divider",
+      className
+    ),
+    ...props
+  }
+));
+ButtonDivider.displayName = "ButtonDivider";
+export {
+  ButtonDivider,
+  ButtonGroup
+};
+//# sourceMappingURL=button-group.js.map

package/dist/components/Button/button-group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"button-group.js","sources":["../../../src/components/Button/button-group.tsx"],"sourcesContent":["import * as React from 'react'\nimport { cn } from '@/lib/utils'\nimport { ButtonGroupContext } from './button'\n\n/**\n * ButtonGroup — 按鈕群組容器\n *\n * 負責群組內的間距（gap 8px）與對齊方式。\n * 垂直排列時透過 ButtonGroupContext 讓所有直接子 Button 自動套用 fullWidth，\n * 無需 cloneElement — 符合 shadcn 的 Context 慣例。\n *\n * @example\n * // 水平排列（預設）\n * <ButtonGroup>\n *   <Button variant=\"primary\">確認</Button>\n *   <Button variant=\"tertiary\">取消</Button>\n * </ButtonGroup>\n *\n * // 靠右對齊（primary 放右側）\n * <ButtonGroup align=\"end\">\n *   <Button variant=\"tertiary\">取消</Button>\n *   <Button variant=\"primary\">確認</Button>\n * </ButtonGroup>\n *\n * // 垂直排列（fullWidth 自動套用）\n * <ButtonGroup direction=\"vertical\">\n *   <Button variant=\"primary\">確認</Button>\n *   <Button variant=\"tertiary\">取消</Button>\n * </ButtonGroup>\n */\ninterface ButtonGroupProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** 排列方向，預設 horizontal */\n  direction?: 'horizontal' | 'vertical'\n  /** 水平對齊，預設 start */\n  align?: 'start' | 'center' | 'end'\n}\n\n// Module-level 常數(2026-04-22 D3 perf audit):provider value 為 2 狀態 boolean,hoist 避免 render 重建\nconst BUTTON_GROUP_CTX_VERTICAL = { fullWidth: true } as const\nconst BUTTON_GROUP_CTX_HORIZONTAL = { fullWidth: false } as const\n\nconst ButtonGroup = React.forwardRef<HTMLDivElement, ButtonGroupProps>(\n  ({ direction = 'horizontal', align = 'start', className, children, ...props }, ref) => {\n    const isVertical = direction === 'vertical'\n\n    return (\n      <ButtonGroupContext.Provider value={isVertical ? BUTTON_GROUP_CTX_VERTICAL : BUTTON_GROUP_CTX_HORIZONTAL}>\n        <div\n          ref={ref}\n          className={cn(\n            'flex gap-2',\n            isVertical ? 'flex-col items-stretch' : 'flex-row items-center flex-wrap',\n            !isVertical && align === 'center' && 'justify-center',\n            !isVertical && align === 'end'    && 'justify-end',\n            className,\n          )}\n          {...props}\n        >\n          {children}\n        </div>\n      </ButtonGroupContext.Provider>\n    )\n  }\n)\nButtonGroup.displayName = 'ButtonGroup'\n\n/**\n * ButtonDivider — 按鈕群組內的分隔線\n *\n * 自身左右各 4px，與相鄰按鈕形成 8px（gap）+ 4px（自身）= 12px 的視覺距離。\n *\n * @example\n * <ButtonGroup>\n *   <Button variant=\"text\" size=\"sm\" iconOnly startIcon={Settings} aria-label=\"設定\" />\n *   <ButtonDivider />\n *   <Button variant=\"primary\" danger size=\"sm\" iconOnly startIcon={Trash2} aria-label=\"刪除\" />\n * </ButtonGroup>\n */\nconst ButtonDivider = React.forwardRef<\n  HTMLDivElement,\n  React.HTMLAttributes<HTMLDivElement>\n>(({ className, ...props }, ref) => (\n  <div\n    ref={ref}\n    role=\"separator\"\n    className={cn(\n      'self-stretch w-px mx-1 my-1',\n      'bg-divider',\n      className,\n    )}\n    {...props}\n  />\n))\nButtonDivider.displayName = 'ButtonDivider'\n\nexport { ButtonGroup, ButtonDivider }\n"],"names":[],"mappings":";;;;AAsCA,MAAM,4BAA4B,EAAE,WAAW,KAAA;AAC/C,MAAM,8BAA8B,EAAE,WAAW,MAAA;AAEjD,MAAM,cAAc,MAAM;AAAA,EACxB,CAAC,EAAE,YAAY,cAAc,QAAQ,SAAS,WAAW,UAAU,GAAG,MAAA,GAAS,QAAQ;AACrF,UAAM,aAAa,cAAc;AAEjC,+BACG,mBAAmB,UAAnB,EAA4B,OAAO,aAAa,4BAA4B,6BAC3E,UAAA;AAAA,MAAC;AAAA,MAAA;AAAA,QACC;AAAA,QACA,WAAW;AAAA,UACT;AAAA,UACA,aAAa,2BAA2B;AAAA,UACxC,CAAC,cAAc,UAAU,YAAY;AAAA,UACrC,CAAC,cAAc,UAAU,SAAY;AAAA,UACrC;AAAA,QAAA;AAAA,QAED,GAAG;AAAA,QAEH;AAAA,MAAA;AAAA,IAAA,GAEL;AAAA,EAEJ;AACF;AACA,YAAY,cAAc;AAc1B,MAAM,gBAAgB,MAAM,WAG1B,CAAC,EAAE,WAAW,GAAG,MAAA,GAAS,QAC1B;AAAA,EAAC;AAAA,EAAA;AAAA,IACC;AAAA,IACA,MAAK;AAAA,IACL,WAAW;AAAA,MACT;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,IAED,GAAG;AAAA,EAAA;AACN,CACD;AACD,cAAc,cAAc;"}

package/dist/components/Button/button.d.ts

@@ -0,0 +1,203 @@
+import * as React from 'react';
+import { type VariantProps } from 'class-variance-authority';
+import type { LucideIcon } from 'lucide-react';
+/**
+ * Button — shadcn 風格，橋接設計系統 token
+ *
+ * ── Variants ──
+ *   primary    主要操作，藍底白字
+ *   secondary  次要品牌操作，藍框藍字；正面 vs 負面並存時用於正面那個
+ *   tertiary   一般輔助操作，灰框灰字，hover 轉藍（最常用的非主要按鈕）
+ *   text       無底色無邊框，hover 顯示灰底（工具列、密集 UI）
+ *   link       外觀像連結的按鈕（本質仍是 button）
+ *
+ * ── danger prop ──
+ *   danger     套用在任何 variant 上，將顏色改為危險色（紅色）
+ *
+ *   <Button variant="primary" danger>永久刪除</Button>        → 紅底白字（立即不可逆）
+ *   <Button variant="secondary" danger>移至垃圾桶</Button>    → 紅框紅字（點下去還可反悔）
+ *
+ * ── pressed prop（toggle）──
+ *   pressed    Toggle 按下狀態（持續 on/off），寫入 aria-pressed + data-state
+ *   僅 secondary / tertiary / text 三個 variant 支援 toggle 視覺：
+ *     - secondary + pressed → primary-subtle 底、primary 字、透明邊框
+ *     - tertiary  + pressed → primary-subtle 底、primary 字、透明邊框（同 secondary 按下視覺）
+ *     - text      + pressed → neutral-selected 底，hover 反向變淺，:active 深一階
+ *   primary / link 傳入 pressed 無視覺效果（語意不符）
+ *
+ * ── Sizes（預設 md）──
+ *   xs   h-field-xs（24px 固定），不隨 density 縮放
+ *   sm   h-field-sm，md=28px / lg=32px
+ *   md   h-field-md，md=32px / lg=36px  ← 預設（跟 Field/Input 對齊）
+ *   lg   h-field-lg，md=36px / lg=40px
+ *   icon-only 不是獨立尺寸 — 加 iconOnly prop 讓任何尺寸變正方形
+ *
+ * ── 內部結構 ──
+ *   [startIcon?]  [label]  [badge? + endIcon?]
+ *
+ * ── 用法範例 ──
+ *   <Button startIcon={Plus}>新增</Button>
+ *   <Button variant="tertiary">取消</Button>
+ *   <Button variant="primary" danger>永久刪除</Button>
+ *   <Button variant="text" pressed={isPinned} startIcon={Pin} aria-label="釘選" iconOnly />
+ *   <Button badge={<Badge count={3} />} endIcon={ChevronDown}>通知</Button>
+ *   <Button size="sm" iconOnly startIcon={Plus} aria-label="新增" />
+ *   <Button iconOnly startIcon={Bell} aria-label="通知 (3 則)"
+ *           overlayBadge={<Badge count={3} />} />  ← badge 自動貼 icon 右上角
+ *
+ * ── asChild ──
+ *   <Button asChild><Link to="/home">回首頁</Link></Button>
+ */
+declare const buttonVariants: (props?: ({
+    variant?: "text" | "link" | "primary" | "secondary" | "tertiary" | null | undefined;
+    danger?: boolean | null | undefined;
+    pressedTone?: "emphasis" | "neutral" | null | undefined;
+    size?: "sm" | "md" | "lg" | "xs" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+interface ButtonGroupContextValue {
+    fullWidth?: boolean;
+}
+declare const ButtonGroupContext: React.Context<ButtonGroupContextValue>;
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, Omit<VariantProps<typeof buttonVariants>, 'variant' | 'danger'> {
+    /**
+     * 將樣式套用至子元件（e.g. React Router Link）。
+     *
+     * ⚠️ **icon-only + asChild 警告**:當 `iconOnly={true}` 且 `asChild={true}` 時,內建
+     * Tooltip wrapper 不啟動(Radix Slot 不接受多 child)。consumer 必須**自管 child 的 `aria-label`**
+     * 給 screen reader,並視需要自行包 `<Tooltip>`(對齊 Polaris / Radix asChild idiom)。
+     * Button 不會主動補 tooltip — 否則會破壞 Slot 單 child 規則。
+     */
+    asChild?: boolean;
+    /**
+     * 按鈕視覺強調等級。
+     * `destructive` / `ghost` 為 shadcn 內部 compat，請勿在應用程式碼中直接使用。
+     */
+    variant?: 'primary' | 'secondary' | 'tertiary' | 'text' | 'link' | (string & {});
+    /** 套用危險色（紅色）。可與任何 variant 組合使用。 */
+    danger?: boolean;
+    /**
+     * Toggle 按下狀態（持續 on/off）。設定時 Button 變為 toggle：
+     * - 自動寫入 `aria-pressed` + `data-state="on" | "off"`
+     * - 樣式由 variant × `pressedTone` 的 compoundVariants 套用
+     * - 僅 secondary / tertiary / text 有 toggle 視覺；primary / link 傳入無效果
+     *
+     * 不傳此 prop 時 Button 就是一般按鈕，不帶 aria-pressed。
+     */
+    pressed?: boolean;
+    /**
+     * Pressed 視覺色調(2026-05-21 v12 加):
+     * - `'emphasis'`(預設)→ 淡藍底 / primary 字(對齊 Figma toolbar / Linear toolbar /
+     *   Material ToggleButton 共識 — toolbar functional toggle / 篩選啟用 / 面板開關)
+     * - `'neutral'` → 灰底 / foreground 字(對齊 Linear / Notion / VS Code Activity Bar
+     *   共識 — sidebar/contextual nav row pressed)
+     *
+     * 僅在 `pressed` 啟用且 variant ∈ {secondary, tertiary, text} 時生效。
+     * 跨 toggle context 維持單一 prop API,consumer 視語意選 tone 不另開 variant。
+     */
+    pressedTone?: 'emphasis' | 'neutral';
+    /** 左側 icon（LucideIcon），最多一個，loading 時自動替換為 spinner */
+    startIcon?: LucideIcon;
+    /** 右側 badge（ReactNode），通常傳入計數指示器 */
+    badge?: React.ReactNode;
+    /**
+     * Overlay badge(iconOnly 專用)。接收 `<Badge>` 元素,Button 內部**自動定位在 startIcon 右上角**——
+     * badge 中心對齊 icon 的 top-right corner(Material BadgedBox / iOS App icon canonical),不是按鈕邊緣。
+     * 解決手刻 `relative + absolute -top-1 -right-1` 讓 badge 飄在按鈕 chrome 右上的問題。
+     *
+     * 世界級對照:Material BadgedBox、iOS App Icon、Ant Badge wrap icon,badge 相對於**視覺重心**(icon)。
+     * 只在 `iconOnly=true` 時生效;非 iconOnly 時應該用 inline `badge` prop 放 suffix 位置。
+     */
+    overlayBadge?: React.ReactNode;
+    /** 右側 icon（LucideIcon），放在 badge 右邊，通常用於 ChevronDown 等方向指示 */
+    endIcon?: LucideIcon;
+    /** Icon-only 模式：移除 padding，變為正方形（必須同時設定 aria-label） */
+    iconOnly?: boolean;
+    /**
+     * Dismiss 視覺類(X close only canonical)。專用於 **X(close)icon 的 dismiss 語意** —
+     * 「關閉 surface / 忽略訊息」。**不適用 Trash / Delete / Clear / Remove 等 destructive / clear 操作**。
+     *
+     * 自動套用:
+     * - `variant="text"`(強制 override 其他 variant)
+     * - `iconOnly=true`(強制)
+     * - Icon 色 override:`fg-muted` → hover `foreground`(跟 Inline Action dismiss 視覺一致)
+     *
+     * 典型 case:Dialog / Sheet / Popover / Alert / Toast / Coachmark 的 **chrome corner close X**
+     * (action group region — corner 可多 action,close 左側加 Separator + refresh / share 等)。
+     *
+     * 非 dismiss(**不套此 prop**):
+     * - Trash / Delete → destructive action,Button 用一般 variant 或 Inline Action(按 row size 判)
+     * - Clear → 欄位清空,用 Inline Action
+     * - Remove → collection 移除,用一般 Button / Inline Action
+     *
+     * 詳見 button.spec.md「Dismiss 視覺類」段 + patterns/element-anatomy/item-anatomy.spec.md
+     * 「Dismiss canonical — X close only」段。
+     */
+    dismiss?: boolean;
+    /** 載入中狀態：startIcon 替換為 spinner，自動 disabled；badge / endIcon 維持顯示以避免 layout shift */
+    loading?: boolean;
+    /** 撐滿父容器寬度 */
+    fullWidth?: boolean;
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * componentMeta — Story Auto-Compile 系統消費的結構化 canonical
+ * (見 .claude/planning/story-auto-compile.md Phase 1)
+ *
+ * compile-stories.mjs 讀本 export + spec.md frontmatter 產出
+ * anatomy.stories.tsx 的 variant/size/state/token 矩陣 canonical section。
+ *
+ * Keys 必跟 buttonVariants cva + spec frontmatter 對齊(compile-time 驗證)。
+ */
+export declare const buttonMeta: {
+    readonly component: "Button";
+    readonly family: 3;
+    readonly variants: {
+        readonly primary: {
+            readonly purpose: "主要 action / CTA";
+        };
+        readonly secondary: {
+            readonly purpose: "次要 action(陪襯 primary)";
+        };
+        readonly tertiary: {
+            readonly purpose: "第三級 action(tool-like)";
+        };
+        readonly text: {
+            readonly purpose: "文字樣式 action(low emphasis / toolbar)";
+        };
+        readonly link: {
+            readonly purpose: "內文連結(inline reading)";
+        };
+    };
+    readonly sizes: {
+        readonly xs: {
+            readonly fieldHeight: 24;
+            readonly iconSize: 16;
+            readonly typography: "body";
+        };
+        readonly sm: {
+            readonly fieldHeight: 28;
+            readonly iconSize: 16;
+            readonly typography: "body";
+        };
+        readonly md: {
+            readonly fieldHeight: 32;
+            readonly iconSize: 16;
+            readonly typography: "body";
+        };
+        readonly lg: {
+            readonly fieldHeight: 40;
+            readonly iconSize: 20;
+            readonly typography: "body-lg";
+        };
+    };
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly ["--primary", "--primary-hover", "--primary-active", "--bg-disabled"];
+        readonly fg: readonly ["--on-emphasis", "--fg-disabled"];
+        readonly ring: readonly ["--ring"];
+    };
+    readonly defaultVariant: "primary";
+    readonly defaultSize: "md";
+};
+export { Button, buttonVariants, ButtonGroupContext };
+//# sourceMappingURL=button.d.ts.map

package/dist/components/Button/button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"button.d.ts","sourceRoot":"","sources":["../../../src/components/Button/button.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAK9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,QAAA,MAAM,cAAc;;;;;8EAgKnB,CAAA;AAKD,UAAU,uBAAuB;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AACD,QAAA,MAAM,kBAAkB,wCAAmD,CAAA;AAI3E,MAAM,WAAW,WACf,SAAQ,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EACnD,IAAI,CAAC,YAAY,CAAC,OAAO,cAAc,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACjE;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;IAChF,mCAAmC;IACnC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,UAAU,GAAG,SAAS,CAAA;IACpC,sDAAsD;IACtD,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,oCAAoC;IACpC,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC9B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,UAAU,CAAA;IACpB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,mFAAmF;IACnF,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,cAAc;IACd,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAwBD,QAAA,MAAM,MAAM,uFAqKX,CAAA;AAGD;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwBb,CAAA;AAEV,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAA"}