@qijenchen/design-system 0.1.0-beta.10

package/dist/components/Menu/menu-item.js

@@ -0,0 +1,209 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { cn } from "../../lib/utils.js";
+import { Checkbox } from "../Checkbox/checkbox.js";
+import { Avatar } from "../Avatar/avatar.js";
+import { ICON_SIZE, AVATAR_SIZE, itemPrefixAlignVariants, ItemContent, ROW_PADDING_BY_SIZE } from "../../patterns/element-anatomy/item-anatomy.js";
+const CHECKBOX_SIZE = { sm: "sm", md: "md", lg: "lg" };
+const menuItemVariants = cva(
+  [
+    "flex items-start gap-2 px-3 w-full",
+    "cursor-pointer select-none",
+    "transition-colors duration-150",
+    "outline-none",
+    "focus-visible:bg-neutral-hover"
+  ],
+  {
+    variants: {
+      // 消費 ROW_PADDING_BY_SIZE SSOT(item-anatomy.tsx 導出)
+      // 改一處 → 全 row primitive 自動同步(消除前 SidebarMenuButton 獨立實作 risk)
+      size: ROW_PADDING_BY_SIZE
+    },
+    defaultVariants: {
+      size: "md"
+    }
+  }
+);
+function lineClampClass(maxLines) {
+  if (maxLines === "none" || !maxLines) return "";
+  if (maxLines === 1) return "line-clamp-1";
+  if (maxLines === 2) return "line-clamp-2";
+  if (maxLines === 3) return "line-clamp-3";
+  if (maxLines === 4) return "line-clamp-4";
+  if (maxLines === 5) return "line-clamp-5";
+  if (maxLines === 6) return "line-clamp-6";
+  return "";
+}
+const MenuItem = React.forwardRef(
+  ({
+    children,
+    description,
+    startIcon: StartIcon,
+    avatar,
+    checkbox,
+    checked,
+    selected,
+    tag,
+    endContent,
+    disabled,
+    header,
+    size,
+    labelMaxLines = 1,
+    descMaxLines = 1,
+    className,
+    ...props
+  }, ref) => {
+    const sizeKey = size ?? "md";
+    const labelClampClass = lineClampClass(labelMaxLines);
+    const descClampClass = lineClampClass(descMaxLines);
+    const iconPx = ICON_SIZE[sizeKey];
+    const avatarPx = avatar ? description ? AVATAR_SIZE.block[sizeKey] : AVATAR_SIZE.inline[sizeKey] : 0;
+    const isBlockAlign = avatarPx > 24 && !!description;
+    const prefixAlign = isBlockAlign ? `block-${sizeKey}` : "inline";
+    const hasPrefix = !!StartIcon || !!avatar || checkbox;
+    if (header) {
+      return /* @__PURE__ */ jsx(
+        "div",
+        {
+          ref,
+          className: cn(
+            menuItemVariants({ size }),
+            "font-medium text-fg-muted cursor-default pointer-events-none",
+            className
+          ),
+          role: "presentation",
+          ...props,
+          children
+        }
+      );
+    }
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref,
+        role: "option",
+        "aria-selected": selected || checked === true || void 0,
+        "aria-disabled": disabled || void 0,
+        "data-selected": selected ? "" : void 0,
+        "data-disabled": disabled ? "" : void 0,
+        className: cn(
+          menuItemVariants({ size }),
+          !disabled && !selected && "hover:bg-neutral-hover",
+          !disabled && selected && "bg-neutral-selected",
+          // disabled 用 cursor-not-allowed(對齊 Button + Material/Polaris/Atlassian);
+          // pointer-events-none 會讓 cursor 失效,改用 aria-disabled + onClick guard
+          disabled && "text-fg-disabled cursor-not-allowed",
+          className
+        ),
+        onClick: disabled ? void 0 : props.onClick,
+        onKeyDown: disabled ? void 0 : props.onKeyDown,
+        ...Object.fromEntries(Object.entries(props).filter(([k]) => k !== "onClick" && k !== "onKeyDown")),
+        children: [
+          hasPrefix && /* @__PURE__ */ jsxs("div", { className: cn(itemPrefixAlignVariants({ align: prefixAlign })), children: [
+            checkbox && /* @__PURE__ */ jsx(
+              Checkbox,
+              {
+                size: CHECKBOX_SIZE[sizeKey],
+                checked: checked === true ? true : checked === "indeterminate" ? "indeterminate" : false,
+                disabled,
+                tabIndex: -1,
+                className: "pointer-events-none"
+              }
+            ),
+            StartIcon && /* @__PURE__ */ jsx(
+              StartIcon,
+              {
+                "data-prefix-type": "icon",
+                size: iconPx,
+                className: cn("shrink-0", disabled && "text-fg-disabled"),
+                "aria-hidden": true
+              }
+            ),
+            avatar && /* @__PURE__ */ jsx(
+              Avatar,
+              {
+                "data-prefix-type": "avatar",
+                src: avatar.src,
+                alt: avatar.alt,
+                color: avatar.color,
+                hoverCard: avatar.hoverCard,
+                size: avatarPx
+              }
+            )
+          ] }),
+          /* @__PURE__ */ jsx(
+            ItemContent,
+            {
+              label: children,
+              description,
+              mode: "scanning",
+              size: sizeKey === "lg" ? "lg" : "md",
+              descriptionTone: disabled ? "disabled" : "secondary",
+              labelTruncate: false,
+              labelClassName: cn(labelClampClass || "break-words", disabled && "text-fg-disabled"),
+              descriptionClassName: cn(descClampClass || "break-words")
+            }
+          ),
+          (tag || endContent) && /* @__PURE__ */ jsxs("div", { className: cn(
+            "flex items-center gap-2 shrink-0 h-[1lh] ml-auto",
+            disabled && "opacity-disabled"
+          ), children: [
+            tag,
+            endContent
+          ] })
+        ]
+      }
+    );
+  }
+);
+MenuItem.displayName = "MenuItem";
+const MenuGroup = React.forwardRef(
+  ({ children, className, ...props }, ref) => /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref,
+      role: "group",
+      className: cn("py-2 [&+&]:border-t [&+&]:border-divider", className),
+      ...props,
+      children
+    }
+  )
+);
+MenuGroup.displayName = "MenuGroup";
+const MenuFooter = React.forwardRef(
+  ({ children, className, ...props }, ref) => /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref,
+      className: cn("py-2 border-t border-divider", className),
+      ...props,
+      children
+    }
+  )
+);
+MenuFooter.displayName = "MenuFooter";
+const menuItemMeta = {
+  component: "MenuItem",
+  family: 1,
+  variants: {},
+  sizes: {
+    sm: {},
+    md: {},
+    lg: {}
+  },
+  defaultSize: "md",
+  states: ["default", "hover", "selected", "focus-visible", "disabled"],
+  tokens: {
+    bg: ["bg-neutral-hover", "bg-neutral-selected"],
+    fg: ["text-fg-muted", "text-fg-disabled"]
+  }
+};
+export {
+  MenuFooter,
+  MenuGroup,
+  MenuItem,
+  menuItemMeta,
+  menuItemVariants
+};
+//# sourceMappingURL=menu-item.js.map

package/dist/components/Menu/menu-item.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu-item.js","sources":["../../../src/components/Menu/menu-item.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 { cva, type VariantProps } from 'class-variance-authority'\nimport type { LucideIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Checkbox } from '@/design-system/components/Checkbox/checkbox'\nimport { Avatar, type AvatarData } from '@/design-system/components/Avatar/avatar'\n// Row primitive 共用常數——統一從 item-layout pattern module 引入\nimport { ICON_SIZE, AVATAR_SIZE, ItemContent, itemPrefixAlignVariants, ROW_PADDING_BY_SIZE } from '@/design-system/patterns/element-anatomy/item-anatomy'\n\n/**\n * MenuItem — 所有 menu 類元件的共用視覺佈局層\n *\n * SelectMenu、DropdownMenu、未來的 ContextMenu 等都消費這個元件。\n * 它只負責 layout（padding、gap、prefix alignment、typography），\n * 互動行為由各 menu 的 Radix primitive 外層控制。\n *\n * ── 結構 ──\n *   [checkbox?]  [startIcon? | avatar?]  [label + description?]\n *\n * ── Prefix 對齊規則（24px 閾值）──\n *   prefix ≤ 24px  → h-[1lh]，對齊第一行 label\n *   prefix > 24px  → h-[calc(1lh+var(--item-gap-label-desc)+desc_1lh)]，對齊文字區塊\n *   無 description → prefix 上限 24px\n *\n * ── Size ──\n *   sm / md / lg — 單行高度對齊 field-height token\n */\n\nconst CHECKBOX_SIZE: Record<string, 'sm' | 'md' | 'lg'> = { sm: 'sm', md: 'md', lg: 'lg' }\n\n// ── Item variants ──\nconst menuItemVariants = cva(\n  [\n    'flex items-start gap-2 px-3 w-full',\n    'cursor-pointer select-none',\n    'transition-colors duration-150',\n    'outline-none',\n    'focus-visible:bg-neutral-hover',\n  ],\n  {\n    variants: {\n      // 消費 ROW_PADDING_BY_SIZE SSOT(item-anatomy.tsx 導出)\n      // 改一處 → 全 row primitive 自動同步(消除前 SidebarMenuButton 獨立實作 risk)\n      size: ROW_PADDING_BY_SIZE,\n    },\n    defaultVariants: {\n      size: 'md',\n    },\n  }\n)\n\n// ── Prefix alignment container ──\n// 消費 `itemPrefixAlignVariants`(SSOT from patterns/element-anatomy/item-anatomy.tsx)\n// 原本 MenuItem 自管 cva 造成 drift 風險(block formula 改動需同步);改為共用 SSOT\n// 讓公式只有一份,改 item-anatomy 一處 → MenuItem 自動同步。\n\n// ── Component ──\n\nexport interface MenuItemProps\n  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>,\n    VariantProps<typeof menuItemVariants> {\n  /** Label 文字 */\n  children: React.ReactNode\n  /** 次要說明文字，顯示在 label 下方 */\n  description?: React.ReactNode\n  /** 左側 icon（LucideIcon），與 avatar 互斥 */\n  startIcon?: LucideIcon\n  /** 左側頭像資料（AvatarData），元件內部渲染 Avatar。與 startIcon 互斥 */\n  avatar?: AvatarData\n  /** 顯示 checkbox（多選模式由父層控制） */\n  checkbox?: boolean\n  /** Checkbox 選中狀態 */\n  checked?: boolean | 'indeterminate'\n  /** 單選選中（bg-neutral-selected 背景高亮，持續選中狀態） */\n  selected?: boolean\n  /** 後綴 Tag（ReactNode），靠右對齊 */\n  tag?: React.ReactNode\n  /** 後綴自訂內容（ReactNode），用於 DropdownMenu 的 badge/endIcon/shortcut 等 */\n  endContent?: React.ReactNode\n  /** 停用 */\n  disabled?: boolean\n  /** 作為群組標題（不可選，font-medium，fg-muted） */\n  header?: boolean\n  /**\n   * Label 最大行數(line-clamp 截斷,超過顯示 ellipsis)。\n   *\n   * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `1`(單行截斷,符合選單快速掃視需求)\n   * - 數字 → 截斷到該行數\n   * - `'none'` → **明確**不截斷,自然 wrap 任意行數\n   *\n   * 為什麼用 `'none'` 而不是 `undefined` 表達不截斷?React props 的 destructure default\n   * 在 `undefined` 時會接管,所以 `<MenuItem labelMaxLines={undefined}>` 等同沒傳,\n   * 會 fallback 到預設 `1`。要明確覆寫成「不截斷」,必須用一個非 undefined 的 sentinel。\n   */\n  labelMaxLines?: number | 'none'\n  /**\n   * Description 最大行數。\n   *\n   * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `1`(跟 label 對稱,維持掃視節奏)\n   * - 數字 → 截斷到該行數\n   * - `'none'` → 明確不截斷\n   *\n   * 為什麼預設 1?Menu 的設計目的是「快速掃視多個選項挑一個」,垂直空間是\n   * 寶貴的——一個過高的 item 會破壞 row rhythm,讓使用者眼睛重新校準。description\n   * 跟 label 對稱地截到 1 行,確保所有 item 高度一致(無 desc / 有 desc 兩種高度)。\n   * Consumer 若有合理理由要 2 行 description,可顯式 override。\n   */\n  descMaxLines?: number | 'none'\n}\n\n/** 把 maxLines 轉成 line-clamp class;'none' / 0 → 空字串 */\nfunction lineClampClass(maxLines: number | 'none'): string {\n  if (maxLines === 'none' || !maxLines) return ''\n  if (maxLines === 1) return 'line-clamp-1'\n  if (maxLines === 2) return 'line-clamp-2'\n  if (maxLines === 3) return 'line-clamp-3'\n  if (maxLines === 4) return 'line-clamp-4'\n  if (maxLines === 5) return 'line-clamp-5'\n  if (maxLines === 6) return 'line-clamp-6'\n  return ''\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst MenuItem = React.forwardRef<HTMLDivElement, MenuItemProps>(\n  (\n    {\n      children,\n      description,\n      startIcon: StartIcon,\n      avatar,\n      checkbox,\n      checked,\n      selected,\n      tag,\n      endContent,\n      disabled,\n      header,\n      size,\n      labelMaxLines = 1,\n      descMaxLines = 1,\n      className,\n      ...props\n    },\n    ref\n  ) => {\n    const sizeKey = size ?? 'md'\n    const labelClampClass = lineClampClass(labelMaxLines)\n    const descClampClass = lineClampClass(descMaxLines)\n    const iconPx = ICON_SIZE[sizeKey]\n\n    // ── 決定 avatar 容器尺寸 + 對齊模式 ──\n    // 有 description → 使用 block 尺寸（32/40px），block 對齊\n    // 無 description → 使用 inline 尺寸（20/24px），inline 對齊\n    const avatarPx = avatar\n      ? (description ? AVATAR_SIZE.block[sizeKey] : AVATAR_SIZE.inline[sizeKey])\n      : 0\n    const isBlockAlign = avatarPx > 24 && !!description\n\n    const prefixAlign = isBlockAlign\n      ? (`block-${sizeKey}` as const)\n      : 'inline'\n\n    const hasPrefix = !!StartIcon || !!avatar || checkbox\n\n    // ── Header variant ──\n    if (header) {\n      return (\n        <div\n          ref={ref}\n          className={cn(\n            menuItemVariants({ size }),\n            'font-medium text-fg-muted cursor-default pointer-events-none',\n            className,\n          )}\n          role=\"presentation\"\n          {...props}\n        >\n          {children}\n        </div>\n      )\n    }\n\n    return (\n      <div\n        ref={ref}\n        role=\"option\"\n        aria-selected={selected || (checked === true) || undefined}\n        aria-disabled={disabled || undefined}\n        data-selected={selected ? '' : undefined}\n        data-disabled={disabled ? '' : undefined}\n        className={cn(\n          menuItemVariants({ size }),\n          !disabled && !selected && 'hover:bg-neutral-hover',\n          !disabled && selected && 'bg-neutral-selected',\n          // disabled 用 cursor-not-allowed(對齊 Button + Material/Polaris/Atlassian);\n          // pointer-events-none 會讓 cursor 失效,改用 aria-disabled + onClick guard\n          disabled && 'text-fg-disabled cursor-not-allowed',\n          className,\n        )}\n        onClick={disabled ? undefined : props.onClick}\n        onKeyDown={disabled ? undefined : props.onKeyDown}\n        {...Object.fromEntries(Object.entries(props).filter(([k]) => k !== 'onClick' && k !== 'onKeyDown'))}\n      >\n        {/* Prefix 對齊容器 */}\n        {hasPrefix && (\n          <div className={cn(itemPrefixAlignVariants({ align: prefixAlign }))}>\n            {checkbox && (\n              <Checkbox\n                size={CHECKBOX_SIZE[sizeKey]}\n                checked={checked === true ? true : checked === 'indeterminate' ? 'indeterminate' : false}\n                disabled={disabled}\n                tabIndex={-1}\n                className=\"pointer-events-none\"\n              />\n            )}\n            {StartIcon && (\n              <StartIcon\n                data-prefix-type=\"icon\"\n                size={iconPx}\n                className={cn('shrink-0', disabled && 'text-fg-disabled')}\n                aria-hidden\n              />\n            )}\n            {avatar && (\n              <Avatar\n                data-prefix-type=\"avatar\"\n                src={avatar.src}\n                alt={avatar.alt}\n                color={avatar.color}\n                hoverCard={avatar.hoverCard}\n                size={avatarPx}\n              />\n            )}\n          </div>\n        )}\n\n        {/* Content — 消費 ItemContent primitive(SSOT)。\n            scanning mode 跟隨 size:sm/md = caption,lg = body(desc 比 label lg 16 小 1 tier)。\n            labelClampClass / descClampClass 透過 className escape hatch 傳入(MenuItem 特化 labelMaxLines / descMaxLines 語意)。 */}\n        <ItemContent\n          label={children}\n          description={description}\n          mode=\"scanning\"\n          size={sizeKey === 'lg' ? 'lg' : 'md'}\n          descriptionTone={disabled ? 'disabled' : 'secondary'}\n          labelTruncate={false}\n          labelClassName={cn(labelClampClass || 'break-words', disabled && 'text-fg-disabled')}\n          descriptionClassName={cn(descClampClass || 'break-words')}\n        />\n\n        {(tag || endContent) && (\n          <div className={cn(\n            'flex items-center gap-2 shrink-0 h-[1lh] ml-auto',\n            disabled && 'opacity-disabled',\n          )}>\n            {tag}\n            {endContent}\n          </div>\n        )}\n      </div>\n    )\n  }\n)\nMenuItem.displayName = 'MenuItem'\n\n// ── Group ──\n// MenuGroup — Menu-like group primitive(跨元件設計語言統一,SSOT 見\n// `patterns/element-anatomy/item-anatomy.spec.md`「Group auto-separation」)\n//\n// 設計語言:每個 group 上下 8px + 相鄰 group 間 border-divider + 視覺 gap 16px\n//\n// 本元件用 Pattern A:`py-2 [&+&]:border-t [&+&]:border-divider`\n// (適用外層容器無 py-2 的情境,例 Command.List——Group 自帶邊界 padding)\n//\n// **視覺必須跟 DropdownMenuGroup 等價**(見 dropdown-menu.tsx Pattern B 對照)。\n// 改動前先讀 item-anatomy.spec.md「Group auto-separation」確認視覺不漂移。\n\nexport interface MenuGroupProps extends React.HTMLAttributes<HTMLDivElement> {\n  children: React.ReactNode\n}\n\nconst MenuGroup = React.forwardRef<HTMLDivElement, MenuGroupProps>(\n  ({ children, className, ...props }, ref) => (\n    <div\n      ref={ref}\n      role=\"group\"\n      className={cn('py-2 [&+&]:border-t [&+&]:border-divider', className)}\n      {...props}\n    >\n      {children}\n    </div>\n  )\n)\nMenuGroup.displayName = 'MenuGroup'\n\n// ── Footer ──\n\nexport interface MenuFooterProps extends React.HTMLAttributes<HTMLDivElement> {\n  children: React.ReactNode\n}\n\nconst MenuFooter = React.forwardRef<HTMLDivElement, MenuFooterProps>(\n  ({ children, className, ...props }, ref) => (\n    <div\n      ref={ref}\n      className={cn('py-2 border-t border-divider', className)}\n      {...props}\n    >\n      {children}\n    </div>\n  )\n)\nMenuFooter.displayName = 'MenuFooter'\n\n// Story auto-compile metadata — Phase 1+2 migration\nexport const menuItemMeta = {\n  component: 'MenuItem',\n  family: 1,\n  variants: {},\n  sizes: {\n    sm: {},\n    md: {},\n    lg: {},\n  },\n  defaultSize: 'md',\n  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: ['bg-neutral-hover', 'bg-neutral-selected'],\n    fg: ['text-fg-muted', 'text-fg-disabled'],\n  },\n} as const\n\nexport { MenuItem, MenuGroup, MenuFooter, menuItemVariants }\n"],"names":[],"mappings":"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"}

package/dist/components/NameCard/name-card.d.ts

@@ -0,0 +1,85 @@
+import * as React from 'react';
+import { type AvatarData } from '../../components/Avatar/avatar';
+/**
+ * NameCardDefaultActions — canonical 預設 action 組合
+ *
+ * ── 為什麼需要 export ──
+ * NameCard 的 action 列在世界級 chat/contact app 是「關係型快速動作」的 canonical
+ * (Slack / iMessage / LinkedIn / Figma 皆如此):**Chat / Message + Audio call**。
+ * 跨 consumer(avatar.principles / name-card.stories / future product code)應該用
+ * 同一組預設,避免每個範例各自發明 action 組合,讓 reader 誤以為 action 會隨情境自動變。
+ *
+ * ── 使用方式(hover context 必含 onViewMore,見 name-card.spec.md 「View more」節)──
+ *   <NameCard name="..." actions={<NameCardDefaultActions />} onViewMore={...} />
+ *
+ * ── 何時要換成自訂 action ──
+ * - Single-action 情境(只要「傳訊息」)→ consumer 傳 `<Button>傳訊息</Button>`
+ * - 特定情境的 action(管理員「撤銷邀請」/ HR「離職管理」)→ consumer 自訂
+ * - 非人員關係動作(「訂購此商品」)→ 根本不應該用 NameCard
+ *
+ * Chat + Audio call 是 **default**,不是 **only**——consumer 可覆寫,但需有明確理由。
+ */
+export declare const NameCardDefaultActions: () => import("react/jsx-runtime").JSX.Element;
+type StatusType = 'online' | 'away' | 'busy' | 'offline';
+/**
+ * NameCard SSOT — 預設 field keys(v11 always-render canonical,2026-05-06)
+ *
+ * ── 為什麼 SSOT ──
+ * User explicit rule:「所有 namecard 預設顯示的資訊都是要一樣完整的」。前 v10 props
+ * 全 optional + body conditional render → consumer 漏傳 fields 視覺缺 section,每個範例
+ * 各自不一致(同 person 在 DataTable / PeoplePicker / avatar.principles 看起來不同)。
+ *
+ * v11 canonical:NameCard **always** renders 4 default sections regardless of consumer 是否
+ * 傳資料 — 缺 data → 對應 DescriptionItem 顯 `EMPTY_PLACEHOLDER`("—"),section 結構不收合。
+ * 視覺結構 SSOT 在此元件,不依賴 consumer。
+ *
+ * ── 對齊 world-class ──
+ * Slack profile card / Linear member card / Notion person card / GitHub user card / Figma user card
+ * 都是 fixed schema(role / email / location / department / department / pronouns 等),
+ * 不會因為某 user 沒填 phone 整個 phone field 不見 — 缺 = 顯 `Not set` 或留白。
+ *
+ * ── 為什麼 placeholder 不 hide ──
+ * Hide → consumer 不知道少傳 → 視覺漂移;Placeholder → 永遠看到「該欄該有」+ dev-warn 提示
+ * consumer 補資料,自動防漂移(M19 ensure-canonical 對齊)。
+ */
+export declare const NAMECARD_DEFAULT_FIELD_KEYS: readonly ["id", "employeeNumber"];
+type NameCardDefaultFieldKey = typeof NAMECARD_DEFAULT_FIELD_KEYS[number];
+export interface NameCardProps extends React.HTMLAttributes<HTMLDivElement> {
+    name: string;
+    avatar?: AvatarData;
+    subtitle?: string;
+    status?: StatusType;
+    statusMessage?: React.ReactNode;
+    actions?: React.ReactNode;
+    /**
+     * Consumer 傳的 field 資料(partial)。預設 keys 走 `NAMECARD_DEFAULT_FIELD_KEYS` —
+     * email / phone / department / location 永遠 render(缺資料顯 `—`)。Consumer 想新增
+     * 自訂 field 直接傳入(在 default 之後 append),想 override default key value 也直接傳。
+     */
+    fields?: {
+        label: string;
+        value: React.ReactNode;
+    }[];
+    /**
+     * Default field 的真實值。Object key = NAMECARD_DEFAULT_FIELD_KEYS 之一。
+     * 缺 key → render placeholder。Dev mode 會 console.warn 提醒消費者補資料。
+     */
+    defaultFieldValues?: Partial<Record<NameCardDefaultFieldKey, React.ReactNode>>;
+    onViewMore?: () => void;
+    viewMoreLabel?: string;
+}
+declare const NameCard: React.ForwardRefExoticComponent<NameCardProps & React.RefAttributes<HTMLDivElement>>;
+export declare const nameCardMeta: {
+    readonly component: "NameCard";
+    readonly family: null;
+    readonly variants: {};
+    readonly sizes: {};
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly ["bg-muted"];
+        readonly fg: readonly ["text-foreground"];
+        readonly ring: readonly [];
+    };
+};
+export { NameCard };
+//# sourceMappingURL=name-card.d.ts.map

package/dist/components/NameCard/name-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"name-card.d.ts","sourceRoot":"","sources":["../../../src/components/NameCard/name-card.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,0CAA0C,CAAA;AAMlF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sBAAsB,+CAKlC,CAAA;AAqBD,KAAK,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;AAiBxD;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,eAAO,MAAM,2BAA2B,mCAAoC,CAAA;AAC5E,KAAK,uBAAuB,GAAG,OAAO,2BAA2B,CAAC,MAAM,CAAC,CAAA;AASzE,MAAM,WAAW,aAAc,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,aAAa,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC/B,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE,EAAE,CAAA;IACpD;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAA;IAC9E,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAGD,QAAA,MAAM,QAAQ,sFAuKb,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/NameCard/name-card.js

@@ -0,0 +1,153 @@
+import { jsxs, jsx, Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { MessageCircle, ChevronDown, Phone } from "lucide-react";
+import { cn } from "../../lib/utils.js";
+import { Avatar } from "../Avatar/avatar.js";
+import { Button } from "../Button/button.js";
+import { DescriptionList, DescriptionItem } from "../DescriptionList/description-list.js";
+import { ScrollArea } from "../ScrollArea/scroll-area.js";
+import { ItemContent } from "../../patterns/element-anatomy/item-anatomy.js";
+const NameCardDefaultActions = () => /* @__PURE__ */ jsxs(Fragment, { children: [
+  /* @__PURE__ */ jsx(Button, { variant: "tertiary", size: "sm", startIcon: MessageCircle, children: "Chat" }),
+  /* @__PURE__ */ jsx(Button, { variant: "tertiary", size: "sm", startIcon: Phone, endIcon: ChevronDown, children: "Audio call" })
+] });
+const AVATAR_SIZE = 64;
+const STATUS_DOT_COLOR = {
+  online: "var(--status-online)",
+  away: "var(--status-away)",
+  busy: "var(--status-busy)",
+  offline: "var(--status-offline)"
+};
+const STATUS_LABEL = {
+  online: "Online",
+  away: "Away",
+  busy: "Busy",
+  offline: "Offline"
+};
+const NAMECARD_DEFAULT_FIELD_KEYS = ["id", "employeeNumber"];
+const DEFAULT_FIELD_LABEL = {
+  id: "ID",
+  employeeNumber: "Employee number"
+};
+const FIELD_PLACEHOLDER = "—";
+const NameCard = React.forwardRef(
+  ({
+    name,
+    avatar,
+    subtitle,
+    status,
+    statusMessage,
+    actions,
+    fields,
+    defaultFieldValues,
+    onViewMore,
+    viewMoreLabel = "View more",
+    className,
+    ...props
+  }, ref) => {
+    const allFields = React.useMemo(() => {
+      const consumerLabels = new Set((fields ?? []).map((f) => f.label));
+      const defaults = NAMECARD_DEFAULT_FIELD_KEYS.map((key) => ({
+        label: DEFAULT_FIELD_LABEL[key],
+        value: (defaultFieldValues == null ? void 0 : defaultFieldValues[key]) ?? FIELD_PLACEHOLDER
+      })).filter((d) => !consumerLabels.has(d.label));
+      return fields && fields.length > 0 ? [...defaults, ...fields] : defaults;
+    }, [defaultFieldValues, fields]);
+    if (process.env.NODE_ENV !== "production" && fields) {
+      const legacyEntry = fields.find(
+        (f) => Object.values(DEFAULT_FIELD_LABEL).includes(f.label)
+      );
+      if (legacyEntry) {
+        console.warn(
+          `[NameCard] "${name}":legacy pattern — fields[].label="${legacyEntry.label}" is a default field. Migrate to defaultFieldValues={{ id, employeeNumber }} prop to align with NAMECARD_DEFAULT_FIELD_KEYS canonical.`
+        );
+      }
+    }
+    if (process.env.NODE_ENV !== "production" && !defaultFieldValues) {
+      console.warn(
+        `[NameCard] "${name}":no defaultFieldValues passed — sections will render placeholders. Pass at least { id, employeeNumber } via defaultFieldValues prop. For other description items (email/phone/department/location etc),use \`fields\` prop array.`
+      );
+    }
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref,
+        className: cn(
+          "w-[320px] flex flex-col overflow-hidden",
+          "max-h-[var(--radix-hover-card-content-available-height,var(--radix-popover-content-available-height,100vh))]",
+          className
+        ),
+        ...props,
+        children: [
+          /* @__PURE__ */ jsxs("div", { className: "shrink-0 flex flex-col", children: [
+            /* @__PURE__ */ jsxs("div", { className: "flex items-start gap-3 px-4 py-3", children: [
+              /* @__PURE__ */ jsx(
+                Avatar,
+                {
+                  src: avatar == null ? void 0 : avatar.src,
+                  alt: (avatar == null ? void 0 : avatar.alt) ?? name,
+                  color: avatar == null ? void 0 : avatar.color,
+                  size: AVATAR_SIZE,
+                  status,
+                  className: "shrink-0"
+                }
+              ),
+              /* @__PURE__ */ jsx(
+                ItemContent,
+                {
+                  label: name,
+                  description: subtitle,
+                  mode: "reading",
+                  size: "lg",
+                  labelTruncate: false,
+                  labelClassName: "text-body-lg font-medium text-foreground",
+                  className: "justify-center",
+                  style: { minHeight: AVATAR_SIZE }
+                }
+              )
+            ] }),
+            actions && /* @__PURE__ */ jsx("div", { className: "grid grid-flow-col auto-cols-fr gap-2 px-4 pb-3 [&>*]:w-full", children: actions })
+          ] }),
+          /* @__PURE__ */ jsxs(ScrollArea, { className: "flex-1 min-h-0 border-t border-divider", children: [
+            status && /* @__PURE__ */ jsxs("div", { className: "px-4 py-3 flex flex-col gap-3", children: [
+              /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2 px-3 py-2 bg-muted rounded-md", children: [
+                /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    className: "w-2.5 h-2.5 rounded-full shrink-0",
+                    style: { backgroundColor: STATUS_DOT_COLOR[status] }
+                  }
+                ),
+                /* @__PURE__ */ jsx("span", { className: "text-body", children: STATUS_LABEL[status] })
+              ] }),
+              /* @__PURE__ */ jsx(DescriptionList, { children: /* @__PURE__ */ jsx(DescriptionItem, { label: "Status message", children: statusMessage ?? /* @__PURE__ */ jsx("span", { className: "text-fg-muted", children: FIELD_PLACEHOLDER }) }) })
+            ] }),
+            /* @__PURE__ */ jsx("div", { className: cn("px-4 py-3", status && "border-t border-divider"), children: /* @__PURE__ */ jsx(DescriptionList, { cols: 2, children: allFields.map((f) => /* @__PURE__ */ jsx(DescriptionItem, { label: f.label, children: f.value === FIELD_PLACEHOLDER ? /* @__PURE__ */ jsx("span", { className: "text-fg-muted", children: FIELD_PLACEHOLDER }) : f.value }, f.label)) }) })
+          ] }),
+          onViewMore && /* @__PURE__ */ jsx("div", { className: "shrink-0 border-t border-divider px-4 py-3", children: /* @__PURE__ */ jsx(Button, { variant: "link", size: "sm", onClick: onViewMore, className: "w-full", children: viewMoreLabel }) })
+        ]
+      }
+    );
+  }
+);
+NameCard.displayName = "NameCard";
+const nameCardMeta = {
+  component: "NameCard",
+  family: null,
+  // non-family composite / overlay / layout
+  variants: {},
+  sizes: {},
+  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  tokens: {
+    bg: ["bg-muted"],
+    fg: ["text-foreground"],
+    ring: []
+  }
+};
+export {
+  NAMECARD_DEFAULT_FIELD_KEYS,
+  NameCard,
+  NameCardDefaultActions,
+  nameCardMeta
+};
+//# sourceMappingURL=name-card.js.map

package/dist/components/NameCard/name-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"name-card.js","sources":["../../../src/components/NameCard/name-card.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 { MessageCircle, Phone, ChevronDown } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Avatar, type AvatarData } from '@/design-system/components/Avatar/avatar'\nimport { Button } from '@/design-system/components/Button/button'\nimport { DescriptionList, DescriptionItem } from '@/design-system/components/DescriptionList/description-list'\nimport { ScrollArea } from '@/design-system/components/ScrollArea/scroll-area'\nimport { ItemContent } from '@/design-system/patterns/element-anatomy/item-anatomy'\n\n/**\n * NameCardDefaultActions — canonical 預設 action 組合\n *\n * ── 為什麼需要 export ──\n * NameCard 的 action 列在世界級 chat/contact app 是「關係型快速動作」的 canonical\n * (Slack / iMessage / LinkedIn / Figma 皆如此):**Chat / Message + Audio call**。\n * 跨 consumer(avatar.principles / name-card.stories / future product code)應該用\n * 同一組預設,避免每個範例各自發明 action 組合,讓 reader 誤以為 action 會隨情境自動變。\n *\n * ── 使用方式(hover context 必含 onViewMore,見 name-card.spec.md 「View more」節)──\n *   <NameCard name=\"...\" actions={<NameCardDefaultActions />} onViewMore={...} />\n *\n * ── 何時要換成自訂 action ──\n * - Single-action 情境(只要「傳訊息」)→ consumer 傳 `<Button>傳訊息</Button>`\n * - 特定情境的 action(管理員「撤銷邀請」/ HR「離職管理」)→ consumer 自訂\n * - 非人員關係動作(「訂購此商品」)→ 根本不應該用 NameCard\n *\n * Chat + Audio call 是 **default**,不是 **only**——consumer 可覆寫,但需有明確理由。\n */\nexport const NameCardDefaultActions = () => (\n  <>\n    <Button variant=\"tertiary\" size=\"sm\" startIcon={MessageCircle}>Chat</Button>\n    <Button variant=\"tertiary\" size=\"sm\" startIcon={Phone} endIcon={ChevronDown}>Audio call</Button>\n  </>\n)\n\n/**\n * NameCard — 人員 HoverCard 的內容元件\n *\n * ── Status 對齊 Avatar presence canonical(2026-04-20) ──\n * status type = `online | away | busy | offline`,跟 Avatar 的 presence prop 對齊\n * (世界級 Slack / Teams / Discord term);dot 色走 `--status-*` semantic token\n * (獨立於 success/error/warning,避免語義衝突)。\n *\n * ── Avatar 對齊 ──\n * 跟 FileItem rich 統一:右側 text column 用 justify-center + minHeight=avatar。\n * 短文字置中於 avatar,長文字(多行名字)自然撐高。\n *\n * ── Info fields ──\n * Status message / ID / Employee number 等唯讀屬性全部用 DescriptionList 家族\n * 承載(不手刻 dt/dd),canonical 由 DS primitive own。\n */\n\nconst AVATAR_SIZE = 64\n\ntype StatusType = 'online' | 'away' | 'busy' | 'offline'\n\n// Presence semantic tokens(見 color/semantic.css)——跟 Avatar status dot 共用\nconst STATUS_DOT_COLOR: Record<StatusType, string> = {\n  online: 'var(--status-online)',\n  away: 'var(--status-away)',\n  busy: 'var(--status-busy)',\n  offline: 'var(--status-offline)',\n}\n\nconst STATUS_LABEL: Record<StatusType, string> = {\n  online: 'Online',\n  away: 'Away',\n  busy: 'Busy',\n  offline: 'Offline',\n}\n\n/**\n * NameCard SSOT — 預設 field keys(v11 always-render canonical,2026-05-06)\n *\n * ── 為什麼 SSOT ──\n * User explicit rule:「所有 namecard 預設顯示的資訊都是要一樣完整的」。前 v10 props\n * 全 optional + body conditional render → consumer 漏傳 fields 視覺缺 section,每個範例\n * 各自不一致(同 person 在 DataTable / PeoplePicker / avatar.principles 看起來不同)。\n *\n * v11 canonical:NameCard **always** renders 4 default sections regardless of consumer 是否\n * 傳資料 — 缺 data → 對應 DescriptionItem 顯 `EMPTY_PLACEHOLDER`(\"—\"),section 結構不收合。\n * 視覺結構 SSOT 在此元件,不依賴 consumer。\n *\n * ── 對齊 world-class ──\n * Slack profile card / Linear member card / Notion person card / GitHub user card / Figma user card\n * 都是 fixed schema(role / email / location / department / department / pronouns 等),\n * 不會因為某 user 沒填 phone 整個 phone field 不見 — 缺 = 顯 `Not set` 或留白。\n *\n * ── 為什麼 placeholder 不 hide ──\n * Hide → consumer 不知道少傳 → 視覺漂移;Placeholder → 永遠看到「該欄該有」+ dev-warn 提示\n * consumer 補資料,自動防漂移(M19 ensure-canonical 對齊)。\n */\n// **2026-05-07 v15.7 user directive**:default render 只 `id` + `employeeNumber` 兩個。\n// Email / Phone / Department / Location 等其他 description 一律 opt-in by consumer 透過\n// `fields` array prop。對齊 user 明確「應該確保所有都只有這兩個,因為我並沒有要求你要選其他的」。\nexport const NAMECARD_DEFAULT_FIELD_KEYS = ['id', 'employeeNumber'] as const\ntype NameCardDefaultFieldKey = typeof NAMECARD_DEFAULT_FIELD_KEYS[number]\n\nconst DEFAULT_FIELD_LABEL: Record<NameCardDefaultFieldKey, string> = {\n  id: 'ID',\n  employeeNumber: 'Employee number',\n}\n\nconst FIELD_PLACEHOLDER = '—'\n\nexport interface NameCardProps extends React.HTMLAttributes<HTMLDivElement> {\n  name: string\n  avatar?: AvatarData\n  subtitle?: string\n  status?: StatusType\n  statusMessage?: React.ReactNode\n  actions?: React.ReactNode\n  /**\n   * Consumer 傳的 field 資料(partial)。預設 keys 走 `NAMECARD_DEFAULT_FIELD_KEYS` —\n   * email / phone / department / location 永遠 render(缺資料顯 `—`)。Consumer 想新增\n   * 自訂 field 直接傳入(在 default 之後 append),想 override default key value 也直接傳。\n   */\n  fields?: { label: string; value: React.ReactNode }[]\n  /**\n   * Default field 的真實值。Object key = NAMECARD_DEFAULT_FIELD_KEYS 之一。\n   * 缺 key → render placeholder。Dev mode 會 console.warn 提醒消費者補資料。\n   */\n  defaultFieldValues?: Partial<Record<NameCardDefaultFieldKey, React.ReactNode>>\n  onViewMore?: () => void\n  viewMoreLabel?: string\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst NameCard = React.forwardRef<HTMLDivElement, NameCardProps>(\n  (\n    {\n      name,\n      avatar,\n      subtitle,\n      status,\n      statusMessage,\n      actions,\n      fields,\n      defaultFieldValues,\n      onViewMore,\n      viewMoreLabel = 'View more',\n      className,\n      ...props\n    },\n    ref,\n  ) => {\n    // v11 always-render canonical:default fields 永遠 render(缺資料顯 placeholder),\n    // consumer 自訂 fields 在 default 之後 append。Status section 也永遠 render(無 status\n    // 顯「Status not set」placeholder),統一視覺結構。\n    //\n    // **Dedup canonical(2026-05-07 v15.8 fix Bug E)**:consumer 的 `fields` array 若含\n    // label 撞 default(eg. 「ID」「Employee number」),consumer 值 win — defaults 那一行\n    // 跳過(否則 same label 連 render 兩次,如 default placeholder `—` + consumer 真值)。\n    // 這是遷移期 forgiving 行為:DEV warn 提示應改用 `defaultFieldValues`,但 production\n    // 不破壞既有 consumer。對齊 React `key` 唯一性 + Linear / Slack profile card 一 label\n    // 一 row idiom。\n    const allFields = React.useMemo(() => {\n      const consumerLabels = new Set((fields ?? []).map((f) => f.label))\n      const defaults = NAMECARD_DEFAULT_FIELD_KEYS\n        .map((key) => ({\n          label: DEFAULT_FIELD_LABEL[key],\n          value: defaultFieldValues?.[key] ?? FIELD_PLACEHOLDER,\n        }))\n        .filter((d) => !consumerLabels.has(d.label))\n      return fields && fields.length > 0 ? [...defaults, ...fields] : defaults\n    }, [defaultFieldValues, fields])\n\n    // Dev warn:consumer 透過 `fields` 傳 default key label(legacy pattern)→ 應改 `defaultFieldValues`\n    if (process.env.NODE_ENV !== 'production' && fields) {\n      const legacyEntry = fields.find((f) =>\n        Object.values(DEFAULT_FIELD_LABEL).includes(f.label as string),\n      )\n      if (legacyEntry) {\n        // eslint-disable-next-line no-console\n        console.warn(\n          `[NameCard] \"${name}\":legacy pattern — fields[].label=\"${legacyEntry.label}\" ` +\n          `is a default field. Migrate to defaultFieldValues={{ id, employeeNumber }} prop ` +\n          `to align with NAMECARD_DEFAULT_FIELD_KEYS canonical.`,\n        )\n      }\n    }\n\n    // Dev mode warn:consumer 沒傳 default field 任何 key → 提示補完(避免漂移成 placeholder-only)\n    if (process.env.NODE_ENV !== 'production' && !defaultFieldValues) {\n      // eslint-disable-next-line no-console\n      console.warn(\n        `[NameCard] \"${name}\":no defaultFieldValues passed — sections will render placeholders. ` +\n        `Pass at least { id, employeeNumber } via defaultFieldValues prop. ` +\n        `For other description items (email/phone/department/location etc),use \\`fields\\` prop array.`,\n      )\n    }\n\n    // Layout canonical(2026-04-23):Header + Actions 固定上,Body(status + fields)可捲動,\n    // View more 固定下。**NameCard 自己約束高度**,不依賴 consumer HoverCardContent 設 flex:\n    //   - `max-h-[var(--radix-hover-card-content-available-height,...)]`:HoverCard / Popover\n    //     context 自動繼承 Radix viewport-aware 變數;standalone 落到 100vh fallback\n    //   - 內部 `flex flex-col + overflow-hidden`:Header(shrink-0)+ Body(flex-1 min-h-0 ScrollArea)\n    //     + Footer(shrink-0)三層 chrome\n    // 世界級對照:Slack / Linear / GitHub / Notion hover-profile popover 皆此 chrome pattern。\n    return (\n      <div\n        ref={ref}\n        className={cn(\n          'w-[320px] flex flex-col overflow-hidden',\n          'max-h-[var(--radix-hover-card-content-available-height,var(--radix-popover-content-available-height,100vh))]',\n          className,\n        )}\n        {...props}\n      >\n        {/* ── HEADER(固定): profile + actions ── */}\n        <div className=\"shrink-0 flex flex-col\">\n          <div className=\"flex items-start gap-3 px-4 py-3\">\n            <Avatar\n              src={avatar?.src}\n              alt={avatar?.alt ?? name}\n              color={avatar?.color}\n              size={AVATAR_SIZE}\n              status={status}\n              className=\"shrink-0\"\n            />\n            {/* NameCard typography:label body-lg(16/1.5) + desc body(14/1.5) = reading mode + size=\"lg\"。\n                labelClassName escape hatch 加 font-medium(card context 語意)+ labelTruncate=false 允許 wrap。 */}\n            <ItemContent\n              label={name}\n              description={subtitle}\n              mode=\"reading\"\n              size=\"lg\"\n              labelTruncate={false}\n              labelClassName=\"text-body-lg font-medium text-foreground\"\n              className=\"justify-center\"\n              style={{ minHeight: AVATAR_SIZE }}\n            />\n          </div>\n\n          {/* Action buttons — 均分空間 + 填滿格子(canonical):多個 action 等寬瓜分容器,\n              單一 action 也撐滿容器。`grid grid-flow-col auto-cols-fr` + `[&>*]:w-full`。\n              世界級對照:iOS contact card / macOS contact / LinkedIn profile card 的 action row。 */}\n          {actions && (\n            <div className=\"grid grid-flow-col auto-cols-fr gap-2 px-4 pb-3 [&>*]:w-full\">\n              {actions}\n            </div>\n          )}\n        </div>\n\n        {/* ── BODY(可捲動,v12 status-conditional 2026-05-14):status + fields ──\n            **v12 rule**(per user 拍板「不應該顯示『狀態沒有被設定』,production 每 user 一定有\n            presence state,undefined 頂多是 loading transient 還沒讀到」):status undefined →\n            隱藏整 status badge + status message block(loading 期間 skip),禁 render「Status not\n            set」這種 placeholder(語義錯,user presence 不會「沒設定」)。**NameCard-specific 不外推\n            至 DS 其他元件**(FileItem / DescriptionList / DataTable cell 各自 placeholder 邏輯\n            unrelated)。Fields section 仍 always-render(info schema 性質)。 */}\n        <ScrollArea className=\"flex-1 min-h-0 border-t border-divider\">\n          {/* Status section:`status` defined 才 render(v12 conditional canonical) */}\n          {status && (\n            <div className=\"px-4 py-3 flex flex-col gap-3\">\n              <div className=\"flex items-center gap-2 px-3 py-2 bg-muted rounded-md\">\n                <span\n                  className=\"w-2.5 h-2.5 rounded-full shrink-0\"\n                  style={{ backgroundColor: STATUS_DOT_COLOR[status] }}\n                />\n                <span className=\"text-body\">{STATUS_LABEL[status]}</span>\n              </div>\n              {/* Status message — 只在 status defined 才 render(語意配對:status badge + status\n                  message 是一組;沒 status 就沒 status message)。缺 statusMessage 顯 placeholder。 */}\n              <DescriptionList>\n                <DescriptionItem label=\"Status message\">\n                  {statusMessage ?? <span className=\"text-fg-muted\">{FIELD_PLACEHOLDER}</span>}\n                </DescriptionItem>\n              </DescriptionList>\n            </div>\n          )}\n\n          {/* Fields section:status defined 才有 border-t separator;無 status section 時去除 border-t(因 ScrollArea 起點已有上方 border-t,不重疊) */}\n          <div className={cn('px-4 py-3', status && 'border-t border-divider')}>\n            <DescriptionList cols={2}>\n              {allFields.map((f) => (\n                <DescriptionItem key={f.label} label={f.label}>\n                  {f.value === FIELD_PLACEHOLDER\n                    ? <span className=\"text-fg-muted\">{FIELD_PLACEHOLDER}</span>\n                    : f.value}\n                </DescriptionItem>\n              ))}\n            </DescriptionList>\n          </div>\n        </ScrollArea>\n\n        {/* ── FOOTER(固定): View more,py-3 canonical(12px,比一般 link 按鈕多呼吸) ── */}\n        {onViewMore && (\n          <div className=\"shrink-0 border-t border-divider px-4 py-3\">\n            <Button variant=\"link\" size=\"sm\" onClick={onViewMore} className=\"w-full\">{viewMoreLabel}</Button>\n          </div>\n        )}\n      </div>\n    )\n  },\n)\nNameCard.displayName = 'NameCard'\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 nameCardMeta = {\n  component: 'NameCard',\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-foreground'],\n    ring: [],\n  },\n} as const\n\nexport { NameCard }\n"],"names":[],"mappings":"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"}

package/dist/components/Notice/notice.d.ts

@@ -0,0 +1,69 @@
+import * as React from 'react';
+/**
+ * Notice — Toast / Alert 共用的視覺佈局層
+ *
+ * ── Typography: md tier ──
+ * title: text-body (14px) leading-compact — 有 description 時加 font-medium
+ * description: text-body (14px) leading-compact + text-fg-secondary (neutral-8)
+ * 14px 配 14px — 視覺層級靠 font-weight + color 區分,不靠 font-size。
+ *
+ * ── Padding（固定,不隨 density 變） ──
+ * px = px-4（16px）
+ * py = py-3（12px）
+ * gap = gap-2（8px）
+ * Toast/Alert 是浮動通知,不是工作區域元件——density 控制表單/選單的緊湊度,
+ * 通知的尺寸應該固定,不隨 density 縮放。
+ *
+ * ── Icon: md tier ──
+ * icon size: 16px（ICON_SIZE.md）
+ *
+ * ── Dismiss X(chrome corner close,Cat 3 Action group region)──
+ * 用 Button iconOnly dismiss **size="xs"** — 非 Inline Action、非自刻 button。
+ * Rationale(Notification banner family canonical):
+ * - Notice / Alert / Toast 屬 **notification banner family**(ephemeral、px-4 py-3 固定不隨 density),
+ *   dismiss 是邊角小 affordance,xs 視覺不搶眼不跟 content 競爭。見 `overlay-surface.spec.md`
+ *   「Chrome dismiss size canonical」三家族分類(Modal sm / Non-modal xs / Notification xs)
+ * - Close 左側可加 refresh / share(action group region),皆統一 xs
+ * - `dismiss` prop 自動套 variant="text" + fg-muted override
+ * SSOT:patterns/element-anatomy/inline-action.spec.md「Dismiss canonical — X close only」
+ *      + components/Alert/alert.spec.md「Chrome corner close X canonical」。
+ */
+export type NoticeVariant = 'neutral' | 'info' | 'success' | 'warning' | 'error';
+export declare const SUBTLE_ICON_COLOR: Record<NoticeVariant, string>;
+export interface NoticeProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+    variant?: NoticeVariant;
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    endContent?: React.ReactNode;
+    dismissible?: boolean;
+    onDismiss?: () => void;
+    /** ARIA label for the dismiss button. Override for i18n. Default: "關閉通知" */
+    dismissAriaLabel?: string;
+    iconClassName?: string;
+    /**
+     * ARIA role 由 wrapping consumer 決定(Alert / Toast / 自管 host),Notice 預設不帶 role。
+     * Notice 是 layout primitive,Alert / Toast 是 live region 擁有者——避免 nested live region
+     * 造成 screen reader 重複朗讀。明文傳遞才覆寫。
+     */
+    role?: 'status' | 'alert';
+    /**
+     * 對應 role 的 aria-live 策略,wrapping consumer 決定;Notice 預設 undefined 不帶 live region。
+     */
+    'aria-live'?: 'polite' | 'assertive' | 'off';
+}
+declare const Notice: React.ForwardRefExoticComponent<NoticeProps & React.RefAttributes<HTMLDivElement>>;
+export declare function useInverseTheme(): 'dark' | 'light';
+export declare const noticeMeta: {
+    readonly component: "Notice";
+    readonly family: null;
+    readonly variants: {};
+    readonly sizes: {};
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly [];
+        readonly fg: readonly ["text-error-text", "text-fg-muted", "text-fg-secondary", "text-info-text", "text-success-text", "text-warning-text"];
+        readonly ring: readonly [];
+    };
+};
+export { Notice };
+//# sourceMappingURL=notice.d.ts.map

package/dist/components/Notice/notice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notice.d.ts","sourceRoot":"","sources":["../../../src/components/Notice/notice.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAM9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;AAUhF,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAM3D,CAAA;AAQD,MAAM,WAAW,WACf,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAC3D,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC5B,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;IACzB;;OAEG;IACH,WAAW,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,KAAK,CAAA;CAC7C;AAED,QAAA,MAAM,MAAM,oFAyDX,CAAA;AA+BD,wBAAgB,eAAe,IAAI,MAAM,GAAG,OAAO,CAGlD;AAID,eAAO,MAAM,UAAU;;;;;;;;;;;CAeb,CAAA;AAEV,OAAO,EAAE,MAAM,EAAE,CAAA"}