@qijenchen/design-system 0.1.0-beta.10

package/dist/components/PeoplePicker/person-display.js

@@ -0,0 +1,203 @@
+import { jsx, jsxs, Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { X } from "lucide-react";
+import { EMPTY_DISPLAY } from "../Field/field-wrapper.js";
+import { Tag } from "../Tag/tag.js";
+import { OverflowIndicator } from "../OverflowIndicator/overflow-indicator.js";
+import { Avatar } from "../Avatar/avatar.js";
+import { NameCard, NameCardDefaultActions } from "../NameCard/name-card.js";
+import { useTableIsScrolling } from "../Field/field-context.js";
+import { ItemPrefix } from "../../patterns/element-anatomy/item-anatomy.js";
+import { getAvatarStackVisibleCount, AVATAR_STACK_AVATAR_PX, AVATAR_STACK_OVERFLOW_CHIP_PX } from "./avatar-stack-overflow.js";
+function resolvePerson(value) {
+  return typeof value === "string" ? { name: value } : value;
+}
+function buildPersonNameCard(person) {
+  return /* @__PURE__ */ jsx(
+    NameCard,
+    {
+      name: person.name,
+      subtitle: person.description,
+      avatar: { src: person.avatarUrl, alt: person.name },
+      status: person.status,
+      statusMessage: person.statusMessage,
+      defaultFieldValues: {
+        id: person.id,
+        employeeNumber: person.employeeNumber
+      },
+      fields: person.fields,
+      actions: /* @__PURE__ */ jsx(NameCardDefaultActions, {}),
+      onViewMore: person.onViewProfile ?? (() => {
+      })
+    }
+  );
+}
+const AVATAR_PX = { sm: 20, md: 24, lg: 24 };
+function PersonAvatar({
+  person,
+  size = "md",
+  className = "",
+  style
+}) {
+  const isTableScrolling = useTableIsScrolling();
+  const nameCard = React.useMemo(
+    () => isTableScrolling ? void 0 : buildPersonNameCard(person),
+    [person, isTableScrolling]
+  );
+  return /* @__PURE__ */ jsx(
+    Avatar,
+    {
+      src: person.avatarUrl,
+      alt: person.name,
+      size: AVATAR_PX[size],
+      className,
+      style,
+      hoverCard: nameCard
+    }
+  );
+}
+function PersonDisplay({ value, size = "md" }) {
+  if (!value) return /* @__PURE__ */ jsx("span", { className: "text-fg-muted", children: EMPTY_DISPLAY });
+  const person = resolvePerson(value);
+  return /* @__PURE__ */ jsxs("span", { className: "flex items-start gap-2 min-w-0 w-full", children: [
+    /* @__PURE__ */ jsx(ItemPrefix, { children: /* @__PURE__ */ jsx(PersonAvatar, { person, size }) }),
+    /* @__PURE__ */ jsx("span", { className: "truncate flex-1 min-w-0", children: person.name })
+  ] });
+}
+PersonDisplay.displayName = "PersonDisplay";
+function MultiPersonDisplay({
+  value,
+  size = "md",
+  max,
+  measured = false,
+  onRemove
+}) {
+  if (!value || value.length === 0) return /* @__PURE__ */ jsx("span", { className: "text-fg-muted", children: EMPTY_DISPLAY });
+  const containerRef = React.useRef(null);
+  const [measuredCount, setMeasuredCount] = React.useState(null);
+  React.useLayoutEffect(() => {
+    if (!measured) return;
+    const el = containerRef.current;
+    if (!el) return;
+    const calc = () => {
+      const visible2 = getAvatarStackVisibleCount({
+        availablePx: el.clientWidth,
+        total: value.length,
+        avatarPx: AVATAR_STACK_AVATAR_PX[size],
+        overflowChipPx: AVATAR_STACK_OVERFLOW_CHIP_PX[size]
+      });
+      setMeasuredCount(visible2);
+    };
+    calc();
+    const ro = new ResizeObserver(calc);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [measured, size, value]);
+  const resolvedMax = measured && measuredCount !== null ? measuredCount : max ?? 3;
+  const people = value.map(resolvePerson);
+  const visible = people.slice(0, resolvedMax);
+  const hidden = people.slice(resolvedMax);
+  const overflow = hidden.length;
+  if (people.length === 1) {
+    return /* @__PURE__ */ jsx(PersonDisplay, { value: value[0], size });
+  }
+  return /* @__PURE__ */ jsx("span", { ref: containerRef, className: "inline-flex items-start min-w-0", children: /* @__PURE__ */ jsx(ItemPrefix, { className: "!justify-start", children: /* @__PURE__ */ jsxs("span", { className: "inline-flex items-center min-w-0", children: [
+    visible.map((person, i) => {
+      const handleDismiss = onRemove ? () => onRemove(value[i]) : void 0;
+      return /* @__PURE__ */ jsxs("span", { className: `relative inline-flex group/avatar ${i > 0 ? "-ml-0.5" : ""}`, style: { zIndex: visible.length - i }, children: [
+        /* @__PURE__ */ jsx(
+          PersonAvatar,
+          {
+            person,
+            size,
+            className: "ring-2 ring-[var(--surface)]"
+          }
+        ),
+        handleDismiss && /* @__PURE__ */ jsx(AvatarDismissOverlay, { onRemove: handleDismiss, label: person.name })
+      ] }, person.name + i);
+    }),
+    overflow > 0 && /* @__PURE__ */ jsx(
+      OverflowIndicator,
+      {
+        count: overflow,
+        size,
+        className: "ring-2 ring-[var(--surface)] -ml-0.5",
+        children: hidden.map((person, i) => /* @__PURE__ */ jsx(
+          Tag,
+          {
+            color: "neutral",
+            size: "sm",
+            avatar: /* @__PURE__ */ jsx(
+              Avatar,
+              {
+                src: person.avatarUrl,
+                alt: person.name,
+                size: 16,
+                hoverCard: buildPersonNameCard(person)
+              }
+            ),
+            onDismiss: onRemove ? () => onRemove(value[resolvedMax + i]) : void 0,
+            children: person.name
+          },
+          person.name + i
+        ))
+      }
+    )
+  ] }) }) });
+}
+MultiPersonDisplay.displayName = "MultiPersonDisplay";
+function AvatarDismissOverlay({ onRemove, label }) {
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      onClick: (e) => {
+        e.stopPropagation();
+        onRemove();
+      },
+      "aria-label": `移除 ${label}`,
+      className: [
+        // **Position(2026-05-07 v15.15 user-confirmed)**:asymmetric `-top-px -right-1`
+        // (top -1px / right -4px)— field padding-y(4px sm/md)緊 → top 只 -1px 安全;
+        // padding-x 12px 寬鬆 → right 凸 4px 達 badge canonical visual。對齊 ClickUp
+        // 世界級 idiom(asymmetric offset by avatar/field size constraint)。
+        "absolute -top-px -right-1 z-10",
+        "inline-flex items-center justify-center",
+        // **12×12 + 2px white ring**(SSOT match stacked avatar,Slack/Material/iOS
+        // notification badge 2px ring canonical)。改用 `[box-shadow:...]` 而非 `ring-2`
+        // 避免跟下方 `focus-visible:ring-2` 在 tailwind-merge 衝突(同 ring family
+        // override 互殺)。Box-shadow inset 0 不影響 layout,也不被 focus-visible ring
+        // 蓋掉(focus 那邊另一條 outline ring 不同 layer)。
+        "w-3 h-3 rounded-full [box-shadow:0_0_0_2px_var(--surface)]",
+        // bg-surface-strong = neutral-6-opaque / hover = neutral-7-opaque(both modes,
+        // step-7 dark 公式自動 lighter → engaged 跨 mode 對稱)
+        "bg-surface-strong text-on-emphasis hover:bg-surface-strong-hover",
+        // a11y(codex P1 fix):opacity 而非 display:none — element 在 DOM/tab-order,
+        // keyboard 可達。Hover / focus-within / focus-visible 三條件之一觸發。
+        "opacity-0 group-hover/avatar:opacity-100 group-focus-within/avatar:opacity-100 focus-visible:opacity-100",
+        "transition-opacity duration-150",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      ].join(" "),
+      children: /* @__PURE__ */ jsx(X, { size: 12, strokeWidth: 3.5, "aria-hidden": true })
+    }
+  );
+}
+function PersonAvatarTag({
+  person,
+  size = "md",
+  onRemove
+}) {
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(PersonAvatar, { person, size, className: "ring-2 ring-[var(--surface)]" }),
+    onRemove && /* @__PURE__ */ jsx(AvatarDismissOverlay, { onRemove, label: person.name })
+  ] });
+}
+PersonAvatarTag.displayName = "PersonAvatarTag";
+export {
+  MultiPersonDisplay,
+  PersonAvatarTag,
+  PersonDisplay,
+  buildPersonNameCard,
+  resolvePerson
+};
+//# sourceMappingURL=person-display.js.map

package/dist/components/PeoplePicker/person-display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"person-display.js","sources":["../../../src/components/PeoplePicker/person-display.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 { X } from 'lucide-react'\nimport { EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'\nimport { Tag } from '@/design-system/components/Tag/tag'\nimport { OverflowIndicator } from '@/design-system/components/OverflowIndicator/overflow-indicator'\nimport { Avatar } from '@/design-system/components/Avatar/avatar'\nimport { NameCard, NameCardDefaultActions } from '@/design-system/components/NameCard/name-card'\nimport { useTableIsScrolling } from '@/design-system/components/Field/field-context'\nimport { ItemPrefix } from '@/design-system/patterns/element-anatomy/item-anatomy'\nimport {\n  getAvatarStackVisibleCount,\n  AVATAR_STACK_AVATAR_PX,\n  AVATAR_STACK_OVERFLOW_CHIP_PX,\n} from './avatar-stack-overflow'\n\n// ── Types ───────────────────────────────────────────────────────────────────\n\n// PersonData 承載 NameCard 所需的完整資訊。DS 全域 person avatar 的 hoverCard NameCard 永遠\n// 顯示同一組 sections(name + subtitle + status + 4 default fields + 自訂 fields + actions + View more)\n// — 缺資料顯 placeholder,不會 collapse。對齊 avatar.spec.md「person avatar hover → NameCard」\n// DS-wide canonical(2026-05-06 v11 always-render schema 升級)。\nexport interface PersonData {\n  name: string\n  avatarUrl?: string\n  /** 角色 / 部門 / ID 等 meta 單行(NameCard subtitle) */\n  description?: string\n  /** Presence 狀態(對齊 Avatar presence canonical)。**2026-05-14 v12 update**(per user 拍板):\n   *  production 每 user 一定有 presence state,**undefined = loading transient(資料還沒讀到)**,\n   *  不是「user 沒設定」。NameCard 在 undefined 期間隱藏整 status block,**禁** render「Status not set」\n   *  placeholder 文字。 */\n  status?: 'online' | 'away' | 'busy' | 'offline'\n  /** Status 訊息(NameCard status section)。只在 status defined 時 render,缺則顯 `—` placeholder。\n   *  Status undefined 整 block skip(無 statusMessage 也跟著 skip)。 */\n  statusMessage?: React.ReactNode\n  /** **2026-05-07 v15.7 user directive**:NameCard default 只 render `id` + `employeeNumber`,\n   *  其他 description 一律 opt-in by consumer 透過 `fields` array prop。對齊\n   *  `NAMECARD_DEFAULT_FIELD_KEYS = ['id', 'employeeNumber']`。 */\n  id?: string\n  employeeNumber?: string\n  /** 自訂額外 fields(在 default fields 之後 append)。Email / Phone / Department / Location\n   *  / 任何其他 description 一律走這個 prop(opt-in,consumer 自選)。 */\n  fields?: { label: string; value: string }[]\n  /** 跳至完整 profile 頁的 handler(hover NameCard 必含,不傳時 fallback noop placeholder) */\n  onViewProfile?: () => void\n}\n\nexport type PersonValue = string | PersonData\n\nfunction resolvePerson(value: PersonValue): PersonData {\n  return typeof value === 'string' ? { name: value } : value\n}\n\n// buildPersonNameCard — DS 全域 person avatar hoverCard 的 canonical NameCard JSX 建構器。\n// SSOT for「avatar hover NameCard 一致視覺」— 任何 person avatar consumer 都走這個 helper,\n// 不可繞道直接 build NameCard。\n//\n// **2026-05-07 v15.7 user directive**:default field values 只 `id` + `employeeNumber`,\n// 對齊 NAMECARD_DEFAULT_FIELD_KEYS。其他 description(email/phone/department/location/etc)\n// consumer 想顯式透過 `person.fields` opt-in 傳入。\nfunction buildPersonNameCard(person: PersonData): React.ReactNode {\n  return (\n    <NameCard\n      name={person.name}\n      subtitle={person.description}\n      avatar={{ src: person.avatarUrl, alt: person.name }}\n      status={person.status}\n      statusMessage={person.statusMessage}\n      defaultFieldValues={{\n        id: person.id,\n        employeeNumber: person.employeeNumber,\n      }}\n      fields={person.fields}\n      actions={<NameCardDefaultActions />}\n      // onViewMore hover context 必含(avatar.spec.md canonical)。consumer 傳\n      // `onViewProfile` 則用真 handler,否則 noop placeholder(UI 仍渲染 View more\n      // footer,避免 preview 變死路)。\n      onViewMore={person.onViewProfile ?? (() => {})}\n    />\n  )\n}\n\n// ── Avatar Size ─────────────────────────────────────────────────────────────\n// 與 Tag 高度對齊:sm=20px, md/lg=24px(對齊 item-anatomy AVATAR_SIZE.inline)\n\nconst AVATAR_PX: Record<'sm' | 'md' | 'lg', number> = { sm: 20, md: 24, lg: 24 }\n\n// ── PersonAvatar ────────────────────────────────────────────────────────────\n// Consume DS `Avatar` primitive(2026-04-22 refactor,M1 SSOT consumption)+ 預設 NameCard\n// hoverCard(avatar.spec.md DS-wide「person avatar hover → NameCard」canonical)。\n//\n// 之前用 local `<img>` / `<User icon />` hand-craft 繞過 DS Avatar,違反 M1。本次 refactor:\n// - 所有 person avatar 經過 DS Avatar primitive(size 對應 uiSize family,fallback / icon / badge 集中管理)\n// - 人員資訊 → NameCard(subtitle = description,actions = NameCardDefaultActions)\n\n// 2026-05-13 (a) perf fix(per codex Layer C HoverCard subtree dominant):\n// useMemo `buildPersonNameCard` per-person stable ref。原 every render call → new JSX ref →\n// Avatar.memo bails → HoverCard subtree 重建。Stable ref → memo skip → big win on scroll。\n//\n// (c) push-up scroll-defer:當 DataTable virtualizer.isScrolling=true,**完全不 build NameCard**\n// (Avatar 收 undefined → 跳 HoverCard wrapper)。原 (c) v1 在 Avatar 層 skip wrapper 但 NameCard\n// JSX subtree 仍在此處 build → 浪費 React reconciliation work。push 到此處才真省。\nfunction PersonAvatar({\n  person,\n  size = 'md',\n  className = '',\n  style,\n}: {\n  person: PersonData\n  size?: 'sm' | 'md' | 'lg'\n  className?: string\n  style?: React.CSSProperties\n}) {\n  const isTableScrolling = useTableIsScrolling()\n  const nameCard = React.useMemo(\n    () => (isTableScrolling ? undefined : buildPersonNameCard(person)),\n    [person, isTableScrolling]\n  )\n  return (\n    <Avatar\n      src={person.avatarUrl}\n      alt={person.name}\n      size={AVATAR_PX[size]}\n      className={className}\n      style={style}\n      hoverCard={nameCard}\n    />\n  )\n}\n\n// ── Single Person Display ───────────────────────────────────────────────────\n\n// 2026-05-14 item-anatomy SSOT fix(per codex+Layer A 共識 path (a) + user 拍板「全部做完」):\n// outer 改 items-start + Avatar 外包 ItemPrefix primitive consumption。單行視覺 = items-center 等效;\n// 多行(autoRowHeight cell)避免 avatar+name center 整 row 不對齊 first-line text top。M1 消費既有\n// 對齊 TreeView / MenuItem / SelectionItem 共用 ItemPrefix wrap chevron/icon/avatar canonical。\nfunction PersonDisplay({ value, size = 'md' }: { value?: PersonValue | null; size?: 'sm' | 'md' | 'lg' }) {\n  if (!value) return <span className=\"text-fg-muted\">{EMPTY_DISPLAY}</span>\n\n  const person = resolvePerson(value)\n\n  // 2026-05-14 I1 fix(per codex addendum verdict):outer `inline-flex` → `flex w-full`\n  // 完成 truncate 寬度約束鏈。原 inline-flex content-width parent constrain 不到 name span\n  // → cell overflow-hidden 硬裁 → ellipsis dots 不可見。改 flex(block-level full width)\n  // + inner name span `flex-1 min-w-0 truncate` 真實 truncate-with-ellipsis 顯示。\n  // 對齊 GitHub Primer ActionList / Slack users_select / Atlassian UserPicker truncation canonical。\n  return (\n    <span className=\"flex items-start gap-2 min-w-0 w-full\">\n      <ItemPrefix><PersonAvatar person={person} size={size} /></ItemPrefix>\n      <span className=\"truncate flex-1 min-w-0\">{person.name}</span>\n    </span>\n  )\n}\nPersonDisplay.displayName = 'PersonDisplay'\n\n// ── Multi Person Display ────────────────────────────────────────────────────\n// 多人堆疊:avatar 重疊(-2px),不顯示人名。\n// 第一個 avatar z-index 最高(在最上面),依此類推。\n// 溢出時顯示 +N 指示器,hover 出 tooltip 列出溢出的人(avatar + 人名)。\n\nfunction MultiPersonDisplay({\n  value,\n  size = 'md',\n  max,\n  measured = false,\n  onRemove,\n}: {\n  value?: PersonValue[] | null\n  size?: 'sm' | 'md' | 'lg'\n  /** 最多顯示幾個 avatar(不含 +N),預設 3。`measured=true` 時忽略此 prop(改 container width 算)*/\n  max?: number\n  /**\n   * 2026-05-15 codex Round 5 C+ SSOT fix:`measured=true` 啟動 container-width 量測(取代 hardcode `max ?? 3`)\n   * → display + edit stack 同 algorithm(同 cell width → 同 overflow 判斷),不再 display 用固定 3 vs edit\n   * 用 useOverflowCount。對齊 field-controls.spec.md:286 「4-mode 共享 renderer」contract + user round 3\n   * verbatim「同空間兩判斷點」SSOT directive。Default false 保 backward compat(non-cell context 仍 max ?? 3)。\n   */\n  measured?: boolean\n  /** 傳入時啟用 dismiss(edit mode),callback 接收被移除的 person */\n  onRemove?: (person: PersonValue) => void\n}) {\n  if (!value || value.length === 0) return <span className=\"text-fg-muted\">{EMPTY_DISPLAY}</span>\n\n  // 2026-05-15 Bug 3 fix(Claude+Codex Step 5 比稿 consensus):消費 shared `avatar-stack-overflow`\n  // primitive。原 inline canvas-based formula 是 dual-implementation 違反 user SSOT「同 cell width 同\n  // overflow 判斷」(edit path 用 Combobox useOverflowCount DOM offsetWidth / display path 用 inline\n  // canvas)。**抽 primitive 統一**:display + edit 共用 `getAvatarStackVisibleCount` formula。\n  // SSOT in `./avatar-stack-overflow.ts`,M14 mechanical guard 防 future drift。\n  const containerRef = React.useRef<HTMLSpanElement>(null)\n  const [measuredCount, setMeasuredCount] = React.useState<number | null>(null)\n  React.useLayoutEffect(() => {\n    if (!measured) return\n    const el = containerRef.current\n    if (!el) return\n    const calc = () => {\n      const visible = getAvatarStackVisibleCount({\n        availablePx: el.clientWidth,\n        total: value.length,\n        avatarPx: AVATAR_STACK_AVATAR_PX[size],\n        overflowChipPx: AVATAR_STACK_OVERFLOW_CHIP_PX[size],\n      })\n      setMeasuredCount(visible)\n    }\n    calc()\n    const ro = new ResizeObserver(calc)\n    ro.observe(el)\n    return () => ro.disconnect()\n  }, [measured, size, value])\n\n  const resolvedMax = measured && measuredCount !== null ? measuredCount : (max ?? 3)\n  const people = value.map(resolvePerson)\n  const visible = people.slice(0, resolvedMax)\n  const hidden = people.slice(resolvedMax)\n  const overflow = hidden.length\n\n  // 單人回退到 PersonDisplay(顯示名字)\n  if (people.length === 1) {\n    return <PersonDisplay value={value[0]} size={size} />\n  }\n\n  // 2026-05-14 item-anatomy SSOT fix(per codex+Layer A 共識):outer items-start + avatar stack\n  // 鎖 first-line baseline(整 stack 是 prefix slot,h-[1lh] 對齊 first line)。\n  return (\n    <span ref={containerRef} className=\"inline-flex items-start min-w-0\">\n      <ItemPrefix className=\"!justify-start\"><span className=\"inline-flex items-center min-w-0\">\n      {visible.map((person, i) => {\n        // **2026-05-07 v15.11 Bug D 升級 SSOT**:visible avatar 也支援 inline dismiss\n        // (對齊 user directive「avatar = tag」)。Dismiss overlay 走 `AvatarDismissOverlay`\n        // 共用 SSOT(下方 export),Combobox tagRenderer / 此處 / 任何 future avatar consumer\n        // 都用同一視覺 — 紅圈 X 對齊 avatar 右上,hover/focus-visible 才顯。\n        const handleDismiss = onRemove ? () => onRemove(value![i]) : undefined\n        return (\n          <span key={person.name + i} className={`relative inline-flex group/avatar ${i > 0 ? '-ml-0.5' : ''}`} style={{ zIndex: visible.length - i }}>\n            <PersonAvatar\n              person={person}\n              size={size}\n              className=\"ring-2 ring-[var(--surface)]\"\n            />\n            {handleDismiss && <AvatarDismissOverlay onRemove={handleDismiss} label={person.name} />}\n          </span>\n        )\n      })}\n      {overflow > 0 && (\n        <OverflowIndicator\n          count={overflow}\n          size={size}\n          className=\"ring-2 ring-[var(--surface)] -ml-0.5\"\n        >\n          {hidden.map((person, i) => (\n            <Tag\n              key={person.name + i}\n              color=\"neutral\"\n              size=\"sm\"\n              // Tag.avatar 是 ReactNode(非 AvatarData object)——傳 <Avatar> 元素。\n              // Tag 內部用 `w-4 h-4 rounded-full` 容器 slot,Avatar 填滿 object-cover。\n              // **hoverCard 必帶**(avatar.spec.md DS-wide canonical:所有 person avatar 必 hover → NameCard)。\n              // 跟 PersonAvatar 共用 `buildPersonNameCard` helper 確保顯示資訊一致。\n              avatar={\n                <Avatar\n                  src={person.avatarUrl}\n                  alt={person.name}\n                  size={16}\n                  hoverCard={buildPersonNameCard(person)}\n                />\n              }\n              onDismiss={onRemove ? () => onRemove(value![resolvedMax + i]) : undefined}\n            >\n              {person.name}\n            </Tag>\n          ))}\n        </OverflowIndicator>\n      )}\n      </span></ItemPrefix>\n    </span>\n  )\n}\nMultiPersonDisplay.displayName = 'MultiPersonDisplay'\n\n// ── AvatarDismissOverlay ────────────────────────────────────────────────────\n// SSOT for「person avatar overlay dismiss」(2026-05-07 v15.12,user spec confirmed)。\n//\n// **Visual canonical**(對齊 DS new token `--surface-strong`):\n//   - **12×12 圓**(固定,不隨 field size 變)\n//   - **bg `--surface-strong`**(neutral-6),hover → `--surface-strong-hover`\n//     (light=neutral-5 / dark=neutral-7,跨 mode 對稱)\n//   - **X icon size=12 strokeWidth=3.5**(icon 跟底色一樣大,對齊 checkbox checkmark\n//     sm/md stroke 規格)\n//   - **text-on-emphasis**(白 X,確保飽和色底對比)\n//   - **位置 `absolute top-0 right-0`**(button 右上角貼齊 avatar 右上角,完全在 avatar\n//     內 — user-confirmed canonical)\n//\n// **a11y**(codex P1 fix):`opacity-0` 而非 `display:none` — element 在 DOM/tab-order,\n// keyboard tab 可達,觸控 focus-within 也顯。Hover / focus-within / focus-visible\n// 三條件之一觸發 `opacity-100`。\n//\n// **Why centralize**:Combobox tagRenderer (PeoplePicker stack mode) + MultiPersonDisplay\n// dismiss 共用 SSOT,改 1 處全 sync(M17 propagation)。\nfunction AvatarDismissOverlay({ onRemove, label }: { onRemove: () => void; label: string }) {\n  return (\n    <button\n      type=\"button\"\n      onClick={(e) => { e.stopPropagation(); onRemove() }}\n      aria-label={`移除 ${label}`}\n      className={[\n        // **Position(2026-05-07 v15.15 user-confirmed)**:asymmetric `-top-px -right-1`\n        // (top -1px / right -4px)— field padding-y(4px sm/md)緊 → top 只 -1px 安全;\n        // padding-x 12px 寬鬆 → right 凸 4px 達 badge canonical visual。對齊 ClickUp\n        // 世界級 idiom(asymmetric offset by avatar/field size constraint)。\n        'absolute -top-px -right-1 z-10',\n        'inline-flex items-center justify-center',\n        // **12×12 + 2px white ring**(SSOT match stacked avatar,Slack/Material/iOS\n        // notification badge 2px ring canonical)。改用 `[box-shadow:...]` 而非 `ring-2`\n        // 避免跟下方 `focus-visible:ring-2` 在 tailwind-merge 衝突(同 ring family\n        // override 互殺)。Box-shadow inset 0 不影響 layout,也不被 focus-visible ring\n        // 蓋掉(focus 那邊另一條 outline ring 不同 layer)。\n        'w-3 h-3 rounded-full [box-shadow:0_0_0_2px_var(--surface)]',\n        // bg-surface-strong = neutral-6-opaque / hover = neutral-7-opaque(both modes,\n        // step-7 dark 公式自動 lighter → engaged 跨 mode 對稱)\n        'bg-surface-strong text-on-emphasis hover:bg-surface-strong-hover',\n        // a11y(codex P1 fix):opacity 而非 display:none — element 在 DOM/tab-order,\n        // keyboard 可達。Hover / focus-within / focus-visible 三條件之一觸發。\n        'opacity-0 group-hover/avatar:opacity-100 group-focus-within/avatar:opacity-100 focus-visible:opacity-100',\n        'transition-opacity duration-150',\n        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',\n      ].join(' ')}\n    >\n      <X size={12} strokeWidth={3.5} aria-hidden />\n    </button>\n  )\n}\n\n// ── PersonAvatarTag(Combobox tagRenderer SSOT for stack mode)─────────────\n// PeoplePicker `multiDisplay='stack'` 模式 wraps Combobox,tagRenderer 不能用 Tag pill\n// (那是 pill mode),改 render 此元件 — Avatar overlap 視覺 + AvatarDismissOverlay。\n// 對齊 user directive「avatar = tag 概念,差別只在視覺,SSOT 一致」(2026-05-07 v15.13)。\n//\n// **架構**(v15.13 重構):本元件**不自包** `group/avatar` / `-ml-0.5` overlap wrapper,\n// 因 Combobox `tagRenderer` 結果會被內部 `<div shrink-0>` 包成 measurement wrapper\n// (useOverflowCount 必要)。把 overlap + group 拉到 Combobox 的 `tagWrapperClassName`\n// 上,sibling-level overlap + group selector 才能正確 chain → AvatarDismissOverlay 的\n// `group-hover/avatar:opacity-100` 才會通。\nfunction PersonAvatarTag({\n  person, size = 'md', onRemove,\n}: {\n  person: PersonData\n  size?: 'sm' | 'md' | 'lg'\n  onRemove?: () => void\n}) {\n  return (\n    <>\n      <PersonAvatar person={person} size={size} className=\"ring-2 ring-[var(--surface)]\" />\n      {onRemove && <AvatarDismissOverlay onRemove={onRemove} label={person.name} />}\n    </>\n  )\n}\nPersonAvatarTag.displayName = 'PersonAvatarTag'\n\nexport { PersonDisplay, MultiPersonDisplay, PersonAvatarTag, buildPersonNameCard, resolvePerson }\n"],"names":["visible"],"mappings":"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"}

package/dist/components/Popover/popover.d.ts

@@ -0,0 +1,50 @@
+import * as React from "react";
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+/**
+ * Popover — Radix Popover + 設計系統 token
+ *
+ * ── 視覺 ──
+ * 與 Dialog 對齊：bg-surface-raised / rounded-lg / border-border / elevation-200。
+ * density 永遠鎖 md（non-modal 輕量浮層不隨頁面 density 放大）。
+ *
+ * ── 結構 ──
+ * PopoverContent：外殼（bg / border / radius / shadow / density），無內距。
+ * PopoverHeader / PopoverBody / PopoverFooter：消費 overlay-surface pattern
+ * 共用的 SurfaceHeader / SurfaceBody / SurfaceFooter primitives(padding SSOT)。
+ *
+ * ── Header dismiss X(2026-04-20 決策) ──
+ * 所有 PopoverHeader 一律附右上 X 按鈕(對齊 Dialog 的 canonical)。Popover 雖是
+ * non-modal + click-outside-to-close,但有 header 的 Popover 通常結構化程度高
+ * (title / 多區塊),明確的「關閉」入口讓使用者更易退出。無 header 的簡單 Popover
+ * 不加 X(click-outside / Esc 即可)。
+ */
+declare const Popover: React.FC<PopoverPrimitive.PopoverProps>;
+declare const PopoverTrigger: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+declare const PopoverAnchor: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverAnchorProps & React.RefAttributes<HTMLDivElement>>;
+declare const PopoverClose: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverCloseProps & React.RefAttributes<HTMLButtonElement>>;
+declare const PopoverContent: React.ForwardRefExoticComponent<Omit<PopoverPrimitive.PopoverContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+interface PopoverHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * 隱藏右上 close X(預設 false,顯示)。
+     * Coachmark / Tour 類 composition 用 Skip / Done 自管 close,不需 X。
+     */
+    hideClose?: boolean;
+}
+declare const PopoverHeader: React.ForwardRefExoticComponent<PopoverHeaderProps & React.RefAttributes<HTMLDivElement>>;
+declare const PopoverBody: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const PopoverFooter: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const PopoverTitle: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLHeadingElement> & React.RefAttributes<HTMLHeadingElement>>;
+export declare const popoverMeta: {
+    readonly component: "Popover";
+    readonly family: null;
+    readonly variants: {};
+    readonly sizes: {};
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly ["bg-surface-raised"];
+        readonly fg: readonly ["text-foreground"];
+        readonly ring: readonly [];
+    };
+};
+export { Popover, PopoverTrigger, PopoverAnchor, PopoverContent, PopoverClose, PopoverHeader, PopoverBody, PopoverFooter, PopoverTitle, };
+//# sourceMappingURL=popover.d.ts.map

package/dist/components/Popover/popover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popover.d.ts","sourceRoot":"","sources":["../../../src/components/Popover/popover.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,gBAAgB,MAAM,yBAAyB,CAAA;AAQ3D;;;;;;;;;;;;;;;;;GAiBG;AAEH,QAAA,MAAM,OAAO,yCAAwB,CAAA;AACrC,QAAA,MAAM,cAAc,gHAA2B,CAAA;AAC/C,QAAA,MAAM,aAAa,4GAA0B,CAAA;AAC7C,QAAA,MAAM,YAAY,8GAAyB,CAAA;AAgB3C,QAAA,MAAM,cAAc,gKAyBlB,CAAA;AAKF,UAAU,kBAAmB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IACvE;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,QAAA,MAAM,aAAa,2FAsBlB,CAAA;AAYD,QAAA,MAAM,WAAW,6GAEhB,CAAA;AAGD,QAAA,MAAM,aAAa,6GAElB,CAAA;AAcD,QAAA,MAAM,YAAY,qHAShB,CAAA;AAKF,eAAO,MAAM,WAAW;;;;;;;;;;;CAed,CAAA;AAEV,OAAO,EACL,OAAO,EACP,cAAc,EACd,aAAa,EACb,cAAc,EACd,YAAY,EACZ,aAAa,EACb,WAAW,EACX,aAAa,EACb,YAAY,GACb,CAAA"}

package/dist/components/Popover/popover.js

@@ -0,0 +1,113 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+import { X } from "lucide-react";
+import { cn } from "../../lib/utils.js";
+import { SurfaceBody, SurfaceFooter, SurfaceHeader } from "../../patterns/overlay-surface/overlay-surface.js";
+import { Button } from "../Button/button.js";
+import { OVERLAY_COLLISION_PADDING, OVERLAY_SIDE_OFFSET } from "../../tokens/elevation/overlay-geometry.js";
+const Popover = PopoverPrimitive.Root;
+const PopoverTrigger = PopoverPrimitive.Trigger;
+const PopoverAnchor = PopoverPrimitive.Anchor;
+const PopoverClose = PopoverPrimitive.Close;
+const handlePopoverOpenAutoFocus = (e) => {
+  e.preventDefault();
+  const content = e.currentTarget;
+  const firstBodyTarget = content.querySelector(
+    "[data-popover-body] input:not([disabled]),[data-popover-body] textarea:not([disabled]),[data-popover-body] select:not([disabled]),[data-popover-body] button:not([disabled]):not([data-dismiss]),input:not([disabled]),textarea:not([disabled]),button:not([disabled]):not([data-dismiss])"
+  );
+  const firstFooterButton = content.querySelector(
+    "[data-popover-footer] button:not([disabled]):not([data-dismiss])"
+  );
+  (firstBodyTarget ?? firstFooterButton ?? content).focus({ preventScroll: true });
+};
+const PopoverContent = React.forwardRef(({ className, align = "center", sideOffset = OVERLAY_SIDE_OFFSET, collisionPadding = OVERLAY_COLLISION_PADDING, onOpenAutoFocus, ...props }, ref) => /* @__PURE__ */ jsx(PopoverPrimitive.Portal, { children: /* @__PURE__ */ jsx(
+  PopoverPrimitive.Content,
+  {
+    ref,
+    align,
+    sideOffset,
+    collisionPadding,
+    "data-density": "md",
+    onOpenAutoFocus: onOpenAutoFocus ?? handlePopoverOpenAutoFocus,
+    className: cn(
+      "z-50 w-72 rounded-lg border border-border bg-surface-raised text-foreground shadow-[var(--elevation-200)] outline-none",
+      // 2026-05-04 viewport-aware max-h SSOT(從 NameCard 升 DS-wide):header/footer 永遠 in-viewport,body 壓縮 scroll
+      // 2026-05-05 audit dim 35 補:加 `min-h-0` 完成 M25 chain invariant(flex item default min-h: auto 阻 shrink)
+      "max-h-[var(--radix-popover-content-available-height,100vh)] flex flex-col overflow-hidden min-h-0",
+      "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 motion-reduce:animate-none",
+      "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+      "origin-[var(--radix-popover-content-transform-origin)]",
+      className
+    ),
+    ...props
+  }
+) }));
+PopoverContent.displayName = PopoverPrimitive.Content.displayName;
+const PopoverHeader = React.forwardRef(
+  ({ className, children, hideClose = false, ...props }, ref) => (
+    // Popover lightweight chrome canonical(2026-05-04 重思 v2):
+    //   覆寫 `--chrome-slot-h: 1.25rem` (20px) → unbounded button 佔位縮成 20,**匹配 PopoverTitle
+    //   text-body line-height (14×1.5≈21,floor 20)**。Header 維持 padding-based 自然撐開:
+    //   max(21 title, 20 slot) + py-tight(12*2) = 45 → 自然比 Dialog/Sheet 48 輕一級。
+    //   Q10 穩定:title-only / title+close 都 = title + py 主導,slot 不 dominate。
+    //   無 min-h / 無 py override — 修正前一版過度設計。
+    /* @__PURE__ */ jsxs(
+      SurfaceHeader,
+      {
+        ref,
+        className: cn("justify-between [--chrome-slot-h:1.25rem]", className),
+        ...props,
+        children: [
+          /* @__PURE__ */ jsx("div", { className: "flex-1 min-w-0", children }),
+          !hideClose && // Dismiss X = native sm,SurfaceHeader 負 my trick 讓 layout 佔位 24 → 匹配 inner 24
+          /* @__PURE__ */ jsx(PopoverPrimitive.Close, { asChild: true, children: /* @__PURE__ */ jsx(Button, { "data-dismiss": true, iconOnly: true, dismiss: true, size: "sm", startIcon: X, "aria-label": "關閉" }) })
+        ]
+      }
+    )
+  )
+);
+PopoverHeader.displayName = "PopoverHeader";
+const PopoverBody = React.forwardRef(
+  ({ ...props }, ref) => /* @__PURE__ */ jsx(SurfaceBody, { ref, "data-popover-body": true, ...props })
+);
+PopoverBody.displayName = "PopoverBody";
+const PopoverFooter = React.forwardRef(
+  ({ ...props }, ref) => /* @__PURE__ */ jsx(SurfaceFooter, { ref, "data-popover-footer": true, ...props })
+);
+PopoverFooter.displayName = "PopoverFooter";
+const PopoverTitle = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+  "h2",
+  {
+    ref,
+    className: cn("text-body font-medium truncate", className),
+    ...props
+  }
+));
+PopoverTitle.displayName = "PopoverTitle";
+const popoverMeta = {
+  component: "Popover",
+  family: null,
+  // non-family composite / overlay / layout
+  variants: {},
+  sizes: {},
+  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  tokens: {
+    bg: ["bg-surface-raised"],
+    fg: ["text-foreground"],
+    ring: []
+  }
+};
+export {
+  Popover,
+  PopoverAnchor,
+  PopoverBody,
+  PopoverClose,
+  PopoverContent,
+  PopoverFooter,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverTrigger,
+  popoverMeta
+};
+//# sourceMappingURL=popover.js.map

package/dist/components/Popover/popover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"popover.js","sources":["../../../src/components/Popover/popover.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 PopoverPrimitive from \"@radix-ui/react-popover\"\nimport { X as XIcon } from \"lucide-react\"\n\nimport { cn } from \"@/lib/utils\"\nimport { SurfaceHeader, SurfaceBody, SurfaceFooter } from \"@/design-system/patterns/overlay-surface/overlay-surface\"\nimport { Button } from \"@/design-system/components/Button/button\"\nimport { OVERLAY_SIDE_OFFSET, OVERLAY_COLLISION_PADDING } from \"@/design-system/tokens/elevation/overlay-geometry\"\n\n/**\n * Popover — Radix Popover + 設計系統 token\n *\n * ── 視覺 ──\n * 與 Dialog 對齊：bg-surface-raised / rounded-lg / border-border / elevation-200。\n * density 永遠鎖 md（non-modal 輕量浮層不隨頁面 density 放大）。\n *\n * ── 結構 ──\n * PopoverContent：外殼（bg / border / radius / shadow / density），無內距。\n * PopoverHeader / PopoverBody / PopoverFooter：消費 overlay-surface pattern\n * 共用的 SurfaceHeader / SurfaceBody / SurfaceFooter primitives(padding SSOT)。\n *\n * ── Header dismiss X(2026-04-20 決策) ──\n * 所有 PopoverHeader 一律附右上 X 按鈕(對齊 Dialog 的 canonical)。Popover 雖是\n * non-modal + click-outside-to-close,但有 header 的 Popover 通常結構化程度高\n * (title / 多區塊),明確的「關閉」入口讓使用者更易退出。無 header 的簡單 Popover\n * 不加 X(click-outside / Esc 即可)。\n */\n\nconst Popover = PopoverPrimitive.Root\nconst PopoverTrigger = PopoverPrimitive.Trigger\nconst PopoverAnchor = PopoverPrimitive.Anchor\nconst PopoverClose = PopoverPrimitive.Close\n\n// AutoFocus canonical(對齊 Dialog / Sheet / Material / Polaris)—\n// 開啟時 focus 落在 body 第一個有意義互動元素,避免 focus 到 close X 觸發 tooltip leak\nconst handlePopoverOpenAutoFocus = (e: Event) => {\n  e.preventDefault()\n  const content = e.currentTarget as HTMLElement\n  const firstBodyTarget = content.querySelector<HTMLElement>(\n    '[data-popover-body] input:not([disabled]),[data-popover-body] textarea:not([disabled]),[data-popover-body] select:not([disabled]),[data-popover-body] button:not([disabled]):not([data-dismiss]),input:not([disabled]),textarea:not([disabled]),button:not([disabled]):not([data-dismiss])'\n  )\n  const firstFooterButton = content.querySelector<HTMLElement>(\n    '[data-popover-footer] button:not([disabled]):not([data-dismiss])'\n  )\n  ;(firstBodyTarget ?? firstFooterButton ?? content).focus({ preventScroll: true })\n}\n\nconst PopoverContent = React.forwardRef<\n  React.ElementRef<typeof PopoverPrimitive.Content>,\n  React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>\n>(({ className, align = \"center\", sideOffset = OVERLAY_SIDE_OFFSET, collisionPadding = OVERLAY_COLLISION_PADDING, onOpenAutoFocus, ...props }, ref) => (\n  <PopoverPrimitive.Portal>\n    <PopoverPrimitive.Content\n      ref={ref}\n      align={align}\n      sideOffset={sideOffset}\n      collisionPadding={collisionPadding}\n      data-density=\"md\"\n      onOpenAutoFocus={onOpenAutoFocus ?? handlePopoverOpenAutoFocus}\n      className={cn(\n        \"z-50 w-72 rounded-lg border border-border bg-surface-raised text-foreground shadow-[var(--elevation-200)] outline-none\",\n        // 2026-05-04 viewport-aware max-h SSOT(從 NameCard 升 DS-wide):header/footer 永遠 in-viewport,body 壓縮 scroll\n        // 2026-05-05 audit dim 35 補:加 `min-h-0` 完成 M25 chain invariant(flex item default min-h: auto 阻 shrink)\n        \"max-h-[var(--radix-popover-content-available-height,100vh)] flex flex-col overflow-hidden min-h-0\",\n        \"data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 motion-reduce:animate-none\",\n        \"data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2\",\n        \"origin-[var(--radix-popover-content-transform-origin)]\",\n        className\n      )}\n      {...props}\n    />\n  </PopoverPrimitive.Portal>\n))\nPopoverContent.displayName = PopoverPrimitive.Content.displayName\n\n// PopoverHeader: SurfaceHeader + Close X(對齊 Dialog 的 canonical,見 docblock)\n// justify-between 讓 children 與 Close 分左右。\ninterface PopoverHeaderProps extends React.HTMLAttributes<HTMLDivElement> {\n  /**\n   * 隱藏右上 close X(預設 false,顯示)。\n   * Coachmark / Tour 類 composition 用 Skip / Done 自管 close,不需 X。\n   */\n  hideClose?: boolean\n}\n\nconst PopoverHeader = React.forwardRef<HTMLDivElement, PopoverHeaderProps>(\n  ({ className, children, hideClose = false, ...props }, ref) => (\n    // Popover lightweight chrome canonical(2026-05-04 重思 v2):\n    //   覆寫 `--chrome-slot-h: 1.25rem` (20px) → unbounded button 佔位縮成 20,**匹配 PopoverTitle\n    //   text-body line-height (14×1.5≈21,floor 20)**。Header 維持 padding-based 自然撐開:\n    //   max(21 title, 20 slot) + py-tight(12*2) = 45 → 自然比 Dialog/Sheet 48 輕一級。\n    //   Q10 穩定:title-only / title+close 都 = title + py 主導,slot 不 dominate。\n    //   無 min-h / 無 py override — 修正前一版過度設計。\n    <SurfaceHeader\n      ref={ref}\n      className={cn(\"justify-between [--chrome-slot-h:1.25rem]\", className)}\n      {...props}\n    >\n      <div className=\"flex-1 min-w-0\">{children}</div>\n      {!hideClose && (\n        // Dismiss X = native sm,SurfaceHeader 負 my trick 讓 layout 佔位 24 → 匹配 inner 24\n        <PopoverPrimitive.Close asChild>\n          <Button data-dismiss iconOnly dismiss size=\"sm\" startIcon={XIcon} aria-label=\"關閉\" />\n        </PopoverPrimitive.Close>\n      )}\n    </SurfaceHeader>\n  ),\n)\nPopoverHeader.displayName = \"PopoverHeader\"\n\n// PopoverBody / PopoverFooter: wrap SurfaceBody / SurfaceFooter with data-popover-*\n// attributes so handlePopoverOpenAutoFocus 可正確定位 body 內第一個 interactive 元素\n//\n// ── List-as-region 場景(menu / Cmd+K / nav)──\n// 不再提供 `flush` variant(2026-05-01 移除,對齊 DialogBody / SheetBody canonical)。\n// consumer 用 SurfaceBody className override 撤掉 chrome padding + 自管 list outer wrapper:\n// `<PopoverBody className=\"!px-0 !py-0\"><div className=\"py-2\">{items}</div></PopoverBody>`\n// 或乾脆不用 PopoverBody,直接 PopoverContent > 自管 list 結構(naked popover)。\n// 詳 DialogBody comment + `tokens/layoutSpace/layoutSpace.spec.md`「List-as-region in overlay body」\nconst PopoverBody = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(\n  ({ ...props }, ref) => <SurfaceBody ref={ref} data-popover-body {...props} />,\n)\nPopoverBody.displayName = \"PopoverBody\"\n\nconst PopoverFooter = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(\n  ({ ...props }, ref) => <SurfaceFooter ref={ref} data-popover-footer {...props} />\n)\nPopoverFooter.displayName = \"PopoverFooter\"\n\n// PopoverTitle(2026-04-22 v4 non-modal canonical):`text-body font-medium`(14px)\n// Rationale:Popover / Coachmark 屬 **non-modal 輕量浮層**,跟 density 鎖 md 同源的視覺語言 —\n// chrome 全體輕量:\n//   - density 鎖 md(不隨 page 放大)\n//   - dismiss X 透過 v5 unbounded trick layout 佔位 24\n//   - **title `text-body`(14px)跟 Dialog / Sheet modal 的 body-lg(16px)形成重量級 vs 輕量級視覺區分**\n// 世界級對照:Figma / Notion / Linear / Material 的 popover / filter panel / inline settings\n// 的 header title 多半比 modal dialog title 小一級(16→14 或同比),視覺宣告「此浮層可忽略」\n//\n// Coachmark 同樣消費 PopoverTitle 作 header 小標籤(如 \"新功能介紹\" / \"Tip 1 of 3\"),\n// CoachmarkBody 的主 title 另走 text-body-lg(見 coachmark.tsx L178)。\nconst PopoverTitle = React.forwardRef<\n  HTMLHeadingElement,\n  React.HTMLAttributes<HTMLHeadingElement>\n>(({ className, ...props }, ref) => (\n  <h2\n    ref={ref}\n    className={cn(\"text-body font-medium truncate\", className)}\n    {...props}\n  />\n))\nPopoverTitle.displayName = \"PopoverTitle\"\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 popoverMeta = {\n  component: 'Popover',\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-surface-raised'],\n    fg: ['text-foreground'],\n    ring: [],\n  },\n} as const\n\nexport {\n  Popover,\n  PopoverTrigger,\n  PopoverAnchor,\n  PopoverContent,\n  PopoverClose,\n  PopoverHeader,\n  PopoverBody,\n  PopoverFooter,\n  PopoverTitle,\n}\n"],"names":["XIcon"],"mappings":";;;;;;;;AA6BA,MAAM,UAAU,iBAAiB;AACjC,MAAM,iBAAiB,iBAAiB;AACxC,MAAM,gBAAgB,iBAAiB;AACvC,MAAM,eAAe,iBAAiB;AAItC,MAAM,6BAA6B,CAAC,MAAa;AAC/C,IAAE,eAAA;AACF,QAAM,UAAU,EAAE;AAClB,QAAM,kBAAkB,QAAQ;AAAA,IAC9B;AAAA,EAAA;AAEF,QAAM,oBAAoB,QAAQ;AAAA,IAChC;AAAA,EAAA;AAED,GAAC,mBAAmB,qBAAqB,SAAS,MAAM,EAAE,eAAe,MAAM;AAClF;AAEA,MAAM,iBAAiB,MAAM,WAG3B,CAAC,EAAE,WAAW,QAAQ,UAAU,aAAa,qBAAqB,mBAAmB,2BAA2B,iBAAiB,GAAG,MAAA,GAAS,QAC7I,oBAAC,iBAAiB,QAAjB,EACC,UAAA;AAAA,EAAC,iBAAiB;AAAA,EAAjB;AAAA,IACC;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,gBAAa;AAAA,IACb,iBAAiB,mBAAmB;AAAA,IACpC,WAAW;AAAA,MACT;AAAA;AAAA;AAAA,MAGA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,IAED,GAAG;AAAA,EAAA;AACN,GACF,CACD;AACD,eAAe,cAAc,iBAAiB,QAAQ;AAYtD,MAAM,gBAAgB,MAAM;AAAA,EAC1B,CAAC,EAAE,WAAW,UAAU,YAAY,OAAO,GAAG,SAAS;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOrD;AAAA,MAAC;AAAA,MAAA;AAAA,QACC;AAAA,QACA,WAAW,GAAG,6CAA6C,SAAS;AAAA,QACnE,GAAG;AAAA,QAEJ,UAAA;AAAA,UAAA,oBAAC,OAAA,EAAI,WAAU,kBAAkB,SAAA,CAAS;AAAA,UACzC,CAAC;AAAA,UAEA,oBAAC,iBAAiB,OAAjB,EAAuB,SAAO,MAC7B,UAAA,oBAAC,UAAO,gBAAY,MAAC,UAAQ,MAAC,SAAO,MAAC,MAAK,MAAK,WAAWA,GAAO,cAAW,MAAK,EAAA,CACpF;AAAA,QAAA;AAAA,MAAA;AAAA,IAAA;AAAA;AAIR;AACA,cAAc,cAAc;AAW5B,MAAM,cAAc,MAAM;AAAA,EACxB,CAAC,EAAE,GAAG,SAAS,QAAQ,oBAAC,aAAA,EAAY,KAAU,qBAAiB,MAAE,GAAG,MAAA,CAAO;AAC7E;AACA,YAAY,cAAc;AAE1B,MAAM,gBAAgB,MAAM;AAAA,EAC1B,CAAC,EAAE,GAAG,SAAS,QAAQ,oBAAC,eAAA,EAAc,KAAU,uBAAmB,MAAE,GAAG,MAAA,CAAO;AACjF;AACA,cAAc,cAAc;AAa5B,MAAM,eAAe,MAAM,WAGzB,CAAC,EAAE,WAAW,GAAG,MAAA,GAAS,QAC1B;AAAA,EAAC;AAAA,EAAA;AAAA,IACC;AAAA,IACA,WAAW,GAAG,kCAAkC,SAAS;AAAA,IACxD,GAAG;AAAA,EAAA;AACN,CACD;AACD,aAAa,cAAc;AAIpB,MAAM,cAAc;AAAA,EACzB,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,CAAC,mBAAmB;AAAA,IACxB,IAAI,CAAC,iBAAiB;AAAA,IACtB,MAAM,CAAA;AAAA,EAAC;AAEX;"}

package/dist/components/ProgressBar/progress-bar.d.ts

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import * as ProgressPrimitive from '@radix-ui/react-progress';
+export interface ProgressBarProps extends Omit<React.ComponentProps<typeof ProgressPrimitive.Root>, 'value'> {
+    /** 當前進度 0-100 */
+    value: number;
+    /** 狀態色(lifecycle,非 emphasis 階) */
+    status?: 'inProgress' | 'success' | 'error';
+    /** 右側附加 */
+    affix?: 'value' | 'status-icon' | React.ReactNode;
+    /**
+     * Track 高度(px)override。**預設 4**(對齊 Material / Carbon / Ant canonical)。
+     *
+     * **非公開 size 階**——這不是給 consumer 自由選擇粗細的 API,而是給**內部另一個
+     * DS 元件(FileItem)在極密集 row layout 下壓低到 2px** 的逃生艙。Consumer 端
+     * 一律走預設 4px。未來若新 primitive(例如 health-bar 型 hero progress)需要
+     * 較高的 track,再評估是否擴公開 API。
+     *
+     * 世界級對照:Ant `<Progress>` 有 `strokeWidth` 原生 prop;本 DS 只暴露給內部
+     * 元件使用,不在 public API 宣傳,避免 consumer 重新陷入「選哪個 size」的判斷負擔。
+     */
+    height?: number;
+}
+declare const ProgressBar: React.ForwardRefExoticComponent<Omit<ProgressBarProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const progressBarMeta: {
+    readonly component: "ProgressBar";
+    readonly family: null;
+    readonly variants: {};
+    readonly sizes: {};
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly ["bg-error", "bg-primary", "bg-secondary", "bg-success"];
+        readonly fg: readonly ["text-foreground"];
+        readonly ring: readonly [];
+    };
+};
+export { ProgressBar };
+//# sourceMappingURL=progress-bar.d.ts.map

package/dist/components/ProgressBar/progress-bar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-bar.d.ts","sourceRoot":"","sources":["../../../src/components/ProgressBar/progress-bar.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,iBAAiB,MAAM,0BAA0B,CAAA;AAoD7D,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,iBAAiB,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAC1G,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,kCAAkC;IAClC,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAAA;IAC3C,WAAW;IACX,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa,GAAG,KAAK,CAAC,SAAS,CAAA;IACjD;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,QAAA,MAAM,WAAW,sGA2DhB,CAAA;AAKD,eAAO,MAAM,eAAe;;;;;;;;;;;CAelB,CAAA;AAEV,OAAO,EAAE,WAAW,EAAE,CAAA"}

package/dist/components/ProgressBar/progress-bar.js

@@ -0,0 +1,86 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import * as ProgressPrimitive from "@radix-ui/react-progress";
+import { XCircle, CircleCheck } from "lucide-react";
+import { cn } from "../../lib/utils.js";
+const DEFAULT_TRACK_H = 4;
+const STATUS_FILL = {
+  inProgress: "bg-primary",
+  success: "bg-success",
+  error: "bg-error"
+};
+const STATUS_ICON = {
+  success: { Icon: CircleCheck, className: "text-success" },
+  error: { Icon: XCircle, className: "text-error" }
+};
+const ProgressBar = React.forwardRef(
+  ({
+    value,
+    status = "inProgress",
+    affix,
+    height,
+    className,
+    ...props
+  }, ref) => {
+    const clampedValue = Math.max(0, Math.min(100, value));
+    const fillColor = STATUS_FILL[status];
+    const trackH = height ?? DEFAULT_TRACK_H;
+    let affixNode = null;
+    if (affix === "value") {
+      affixNode = /* @__PURE__ */ jsxs("span", { className: "text-caption text-foreground tabular-nums shrink-0", children: [
+        Math.round(clampedValue),
+        "%"
+      ] });
+    } else if (affix === "status-icon") {
+      const s = status !== "inProgress" ? STATUS_ICON[status] : null;
+      if (s) affixNode = /* @__PURE__ */ jsx(s.Icon, { size: 16, className: cn("shrink-0", s.className), "aria-hidden": true });
+    } else if (React.isValidElement(affix) || typeof affix === "string" || typeof affix === "number") {
+      affixNode = affix;
+    }
+    const bar = /* @__PURE__ */ jsx(
+      ProgressPrimitive.Root,
+      {
+        ref,
+        value: clampedValue,
+        max: 100,
+        className: cn(
+          "relative overflow-hidden rounded-full bg-secondary w-full",
+          className
+        ),
+        style: { height: trackH },
+        ...props,
+        children: /* @__PURE__ */ jsx(
+          ProgressPrimitive.Indicator,
+          {
+            className: cn("h-full rounded-full transition-all duration-300", fillColor),
+            style: { width: `${clampedValue}%` }
+          }
+        )
+      }
+    );
+    if (!affixNode) return bar;
+    return /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2 w-full", children: [
+      /* @__PURE__ */ jsx("div", { className: "flex-1 min-w-0", children: bar }),
+      affixNode
+    ] });
+  }
+);
+ProgressBar.displayName = "ProgressBar";
+const progressBarMeta = {
+  component: "ProgressBar",
+  family: null,
+  // non-family composite / overlay / layout
+  variants: {},
+  sizes: {},
+  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  tokens: {
+    bg: ["bg-error", "bg-primary", "bg-secondary", "bg-success"],
+    fg: ["text-foreground"],
+    ring: []
+  }
+};
+export {
+  ProgressBar,
+  progressBarMeta
+};
+//# sourceMappingURL=progress-bar.js.map

package/dist/components/ProgressBar/progress-bar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-bar.js","sources":["../../../src/components/ProgressBar/progress-bar.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 ProgressPrimitive from '@radix-ui/react-progress'\nimport { CircleCheck, XCircle } from 'lucide-react'\nimport { cn } from '@/lib/utils'\n\n/**\n * ProgressBar — 水平進度條(determinate)\n *\n * 世界級對照:Material `LinearProgress` / Ant `Progress` / Polaris `ProgressBar` /\n * shadcn `Progress`(皆為 Radix Progress primitive 的包裝)。本 DS 命名為\n * `ProgressBar`(linear)以和 `CircularProgress`(circular)做清楚區分。\n *\n * ── 與 CircularProgress 的分界 ──\n * CircularProgress = circular 兩態(indeterminate 旋轉 / determinate arc),inline 小空間\n * ProgressBar      = linear determinate(0-100% 已知量化),頁面級大區塊 / 表單 wizard / quota\n * 兩者視覺與語意都不同,consumer 依「形狀(linear / circular)+ 是否量化」擇一。\n *\n * ── 與 FileItem 的分界(2026-04-20 user 決策) ──\n * **檔案上傳 UI 走 `FileItem`,不直接消費 ProgressBar**。FileItem 是檔案上傳情境的\n * canonical consumer-facing primitive(檔名 / icon / 進度 / status / actions 一條龍);\n * FileItem 內部可能消費 ProgressBar(engineering 實作細節),consumer 不用也不該自己\n * 組合 raw ProgressBar + 檔名 + action 來做上傳列表。世界級對照:Ant Design 的 `Upload`\n * vs `Progress`(Upload.List 內部用 Progress,consumer 不直接用 Progress 做上傳 UI)。\n *\n * ── 3 狀態,單一 size ──\n * status: inProgress(進行中藍) / success(完成綠) / error(失敗紅)\n *   ^ 命名理由:`status` 是 lifecycle(在途 / 終態),不是視覺 emphasis 階。前身\n *   `primary` 會撞 Button `variant=\"primary\"`(emphasis 最高階),改用世界級\n *   lifecycle 慣例(Polaris `inProgress` / Ant Progress `active`)。\n *\n * **單一高度 4px**(2026-04-20 user 決策):對齊 Material 3 / Carbon / Ant 慣例\n * (固定 4dp/px 不給 size 選項)。4px 是 linear progress 的業界 canonical;若需\n * 視覺強調改用 CircularProgress + label 或改做 full-width hero 版型,不靠 size\n * 階梯撐。移除前的 sm(2)/ md(4)/ lg(6)刻度差太小,無實質視覺區分。\n *\n * ── affix(右側附加) ──\n * `affix=\"value\"` → 顯示 `{value}%` 文字\n * `affix=\"status-icon\"` → 顯示狀態 icon(success ✓ / error ✗;inProgress 時無 icon)\n * `affix={<custom />}` → consumer 客製\n * 不傳 → 純 bar\n */\n\nconst DEFAULT_TRACK_H = 4 // 預設 4px(見 docblock「單一高度」)\nconst STATUS_FILL = {\n  inProgress: 'bg-primary',\n  success: 'bg-success',\n  error: 'bg-error',\n} as const\nconst STATUS_ICON = {\n  success: { Icon: CircleCheck, className: 'text-success' },\n  error:   { Icon: XCircle,     className: 'text-error' },\n} as const\n\nexport interface ProgressBarProps extends Omit<React.ComponentProps<typeof ProgressPrimitive.Root>, 'value'> {\n  /** 當前進度 0-100 */\n  value: number\n  /** 狀態色(lifecycle,非 emphasis 階) */\n  status?: 'inProgress' | 'success' | 'error'\n  /** 右側附加 */\n  affix?: 'value' | 'status-icon' | React.ReactNode\n  /**\n   * Track 高度(px)override。**預設 4**(對齊 Material / Carbon / Ant canonical)。\n   *\n   * **非公開 size 階**——這不是給 consumer 自由選擇粗細的 API,而是給**內部另一個\n   * DS 元件(FileItem)在極密集 row layout 下壓低到 2px** 的逃生艙。Consumer 端\n   * 一律走預設 4px。未來若新 primitive(例如 health-bar 型 hero progress)需要\n   * 較高的 track,再評估是否擴公開 API。\n   *\n   * 世界級對照:Ant `<Progress>` 有 `strokeWidth` 原生 prop;本 DS 只暴露給內部\n   * 元件使用,不在 public API 宣傳,避免 consumer 重新陷入「選哪個 size」的判斷負擔。\n   */\n  height?: number\n}\n\nconst ProgressBar = React.forwardRef<HTMLDivElement, ProgressBarProps>(\n  (\n    {\n      value,\n      status = 'inProgress',\n      affix,\n      height,\n      className,\n      ...props\n    },\n    ref,\n  ) => {\n    const clampedValue = Math.max(0, Math.min(100, value))\n    const fillColor = STATUS_FILL[status]\n    const trackH = height ?? DEFAULT_TRACK_H\n\n    // Affix 渲染\n    let affixNode: React.ReactNode = null\n    if (affix === 'value') {\n      affixNode = (\n        <span className=\"text-caption text-foreground tabular-nums shrink-0\">\n          {Math.round(clampedValue)}%\n        </span>\n      )\n    } else if (affix === 'status-icon') {\n      const s = status !== 'inProgress' ? STATUS_ICON[status] : null\n      if (s) affixNode = <s.Icon size={16} className={cn('shrink-0', s.className)} aria-hidden />\n    } else if (React.isValidElement(affix) || typeof affix === 'string' || typeof affix === 'number') {\n      affixNode = affix\n    }\n\n    const bar = (\n      <ProgressPrimitive.Root\n        ref={ref}\n        value={clampedValue}\n        max={100}\n        className={cn(\n          'relative overflow-hidden rounded-full bg-secondary w-full',\n          className,\n        )}\n        style={{ height: trackH }}\n        {...props}\n      >\n        <ProgressPrimitive.Indicator\n          className={cn('h-full rounded-full transition-all duration-300', fillColor)}\n          style={{ width: `${clampedValue}%` }}\n        />\n      </ProgressPrimitive.Root>\n    )\n\n    if (!affixNode) return bar\n\n    return (\n      <div className=\"flex items-center gap-2 w-full\">\n        <div className=\"flex-1 min-w-0\">{bar}</div>\n        {affixNode}\n      </div>\n    )\n  },\n)\nProgressBar.displayName = 'ProgressBar'\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 progressBarMeta = {\n  component: 'ProgressBar',\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-error', 'bg-primary', 'bg-secondary', 'bg-success'],\n    fg: ['text-foreground'],\n    ring: [],\n  },\n} as const\n\nexport { ProgressBar }\n"],"names":[],"mappings":";;;;;AA2CA,MAAM,kBAAkB;AACxB,MAAM,cAAc;AAAA,EAClB,YAAY;AAAA,EACZ,SAAS;AAAA,EACT,OAAO;AACT;AACA,MAAM,cAAc;AAAA,EAClB,SAAS,EAAE,MAAM,aAAa,WAAW,eAAA;AAAA,EACzC,OAAS,EAAE,MAAM,SAAa,WAAW,aAAA;AAC3C;AAuBA,MAAM,cAAc,MAAM;AAAA,EACxB,CACE;AAAA,IACE;AAAA,IACA,SAAS;AAAA,IACT;AAAA,IACA;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EAAA,GAEL,QACG;AACH,UAAM,eAAe,KAAK,IAAI,GAAG,KAAK,IAAI,KAAK,KAAK,CAAC;AACrD,UAAM,YAAY,YAAY,MAAM;AACpC,UAAM,SAAS,UAAU;AAGzB,QAAI,YAA6B;AACjC,QAAI,UAAU,SAAS;AACrB,kBACE,qBAAC,QAAA,EAAK,WAAU,sDACb,UAAA;AAAA,QAAA,KAAK,MAAM,YAAY;AAAA,QAAE;AAAA,MAAA,GAC5B;AAAA,IAEJ,WAAW,UAAU,eAAe;AAClC,YAAM,IAAI,WAAW,eAAe,YAAY,MAAM,IAAI;AAC1D,UAAI,EAAG,aAAY,oBAAC,EAAE,MAAF,EAAO,MAAM,IAAI,WAAW,GAAG,YAAY,EAAE,SAAS,GAAG,eAAW,MAAC;AAAA,IAC3F,WAAW,MAAM,eAAe,KAAK,KAAK,OAAO,UAAU,YAAY,OAAO,UAAU,UAAU;AAChG,kBAAY;AAAA,IACd;AAEA,UAAM,MACJ;AAAA,MAAC,kBAAkB;AAAA,MAAlB;AAAA,QACC;AAAA,QACA,OAAO;AAAA,QACP,KAAK;AAAA,QACL,WAAW;AAAA,UACT;AAAA,UACA;AAAA,QAAA;AAAA,QAEF,OAAO,EAAE,QAAQ,OAAA;AAAA,QAChB,GAAG;AAAA,QAEJ,UAAA;AAAA,UAAC,kBAAkB;AAAA,UAAlB;AAAA,YACC,WAAW,GAAG,mDAAmD,SAAS;AAAA,YAC1E,OAAO,EAAE,OAAO,GAAG,YAAY,IAAA;AAAA,UAAI;AAAA,QAAA;AAAA,MACrC;AAAA,IAAA;AAIJ,QAAI,CAAC,UAAW,QAAO;AAEvB,WACE,qBAAC,OAAA,EAAI,WAAU,kCACb,UAAA;AAAA,MAAA,oBAAC,OAAA,EAAI,WAAU,kBAAkB,UAAA,KAAI;AAAA,MACpC;AAAA,IAAA,GACH;AAAA,EAEJ;AACF;AACA,YAAY,cAAc;AAInB,MAAM,kBAAkB;AAAA,EAC7B,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,CAAC,YAAY,cAAc,gBAAgB,YAAY;AAAA,IAC3D,IAAI,CAAC,iBAAiB;AAAA,IACtB,MAAM,CAAA;AAAA,EAAC;AAEX;"}