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

package/dist/patterns/element-anatomy/item-anatomy.d.ts

@@ -0,0 +1,370 @@
+import * as React from "react";
+import type { LucideIcon } from "lucide-react";
+import { type AvatarProps } from "../../components/Avatar/avatar";
+export interface InlineActionConfig {
+    icon: LucideIcon;
+    /** aria-label,同時作為 tooltip 來源 */
+    label: string;
+    /**
+     * 點擊 handler。可選接收 React 事件物件——有需要時可呼叫 `stopPropagation()` 避免
+     * 事件冒泡到父層(例如 Select 清除按鈕在 popover trigger 內,不想觸發 popover open)。
+     */
+    onClick: (e?: React.MouseEvent<HTMLButtonElement>) => void;
+}
+/**
+ * Item Layout — 共用工具與常數
+ *
+ * 這個檔案不是元件,是 `item-anatomy.spec.md` 的 code-level 實作。
+ * 所有 row primitives(`MenuItem` / `TreeItem` / `SidebarMenuButton` /
+ * `SelectionItem`)**必須 import 本 module 的 ICON_SIZE 和 helpers**,
+ * 不要各自複製常數或 wrapper className——單一 source of truth,避免不一致。
+ *
+ * 詳細規則見 `item-anatomy.spec.md`。
+ */
+/** Row primitive 的 size 變體,對齊 `--field-height-*` token family */
+export type RowSize = "sm" | "md" | "lg";
+/**
+ * Icon 尺寸(px)per row size。
+ *
+ * - sm / md: 16px(標準 row icon)
+ * - lg: 20px(對齊 text-body-lg 的視覺重量)
+ *
+ * **用法**:透過 Lucide icon 的 `size` prop 直接傳入,不要用 CSS `[&>svg]:size-*`
+ * selector——當 icon 被包在 `<ItemPrefix>` 的 `h-[1lh]` wrapper 內時,
+ * `>` 直接子選擇器會失效,Lucide icon 會 fallback 到預設 24px。
+ *
+ * ```tsx
+ * import { ICON_SIZE } from "../../patterns/element-anatomy/item-anatomy"
+ *
+ * const iconPx = ICON_SIZE[size]  // size: RowSize
+ * <MyLucideIcon size={iconPx} />
+ * ```
+ */
+export declare const ICON_SIZE: Record<RowSize, number>;
+/**
+ * Avatar 尺寸(px)per row size,分 inline / block 兩種模式。
+ *
+ * - **inline**(無 description,大宗情境)→ 對齊第一行 label,用 `h-[1lh]` 容器
+ *   sm: 20, md: 24, lg: 24
+ * - **block**(有 description,avatar 跨越 label + desc 兩行)→ 對齊文字塊中心
+ *   sm: 32, md: 32, lg: 40
+ *
+ * **用法**:所有 row primitive 的 consumer(包含 `asChild` pattern 的 Sidebar / Tree
+ * consumer)**必須**從本 module import 這個常數,**不可硬寫 `size={24}`**。
+ * 硬寫會讓 sm 變體的 avatar 尺寸錯誤、跟 ICON_SIZE 對齊規則脫鉤。
+ *
+ * ```tsx
+ * import { AVATAR_SIZE } from "../../patterns/element-anatomy/item-anatomy"
+ *
+ * const { size } = useSidebar()  // RowSize
+ * <Avatar size={AVATAR_SIZE.inline[size]} />
+ * ```
+ *
+ * Canonical 實作:`MenuItem` 的內部 `AVATAR_SIZE` 查表(即將 re-export 自此)。
+ */
+export declare const AVATAR_SIZE: {
+    readonly inline: {
+        readonly sm: 20;
+        readonly md: 24;
+        readonly lg: 24;
+    };
+    readonly block: {
+        readonly sm: 32;
+        readonly md: 32;
+        readonly lg: 40;
+    };
+};
+/**
+ * 回傳 uniform prefix slot 的 inline style(CSS variable form)。
+ *
+ * 用法:Row-primitive 頂層容器(例如 `<SidebarProvider uniformPrefix>` 的 wrapper)
+ * 把這個 style 套在 `style` prop 上(預先放在 `--mixed-prefix-slot` 候選位置,
+ * 由外層 CSS `:has()` 條件化套到 `--item-prefix-slot`),子樹內所有 `<ItemPrefix>` /
+ * `<ItemIcon>` / `<ItemAvatar>` 會自動用固定寬槽對齊。
+ *
+ * 槽寬 = `AVATAR_SIZE.inline[size]`(20/24/24 @ sm/md/lg)——以最大的 inline
+ * prefix(avatar)為基準,icon 在槽內 `justify-center`。
+ *
+ * ```tsx
+ * <ul style={getUniformPrefixSlotStyle(size)}>
+ *   <ItemIcon icon={Folder} />      ← 16px icon 在 24px 槽內置中
+ *   <ItemAvatar alt="GitHub" />     ← 24px logo 填滿槽
+ * </ul>
+ * ```
+ */
+export declare function getUniformPrefixSlotStyle(size: RowSize): React.CSSProperties;
+/**
+ * Inline action(suffix 裡的 hover-action icon button)hover 背景尺寸(px)。
+ * 規則:icon size + 2px(每邊 +1px,用 absolute positioning 溢出不影響排版)。
+ * 對齊 `item-anatomy.spec.md`「Inline Action 設計規格」節。
+ */
+export declare const INLINE_ACTION_HOVER_BG_SIZE: Record<RowSize, number>;
+/**
+ * `ROW_PADDING_BY_SIZE` — Family 1+2 row primitive 的 size → padding + typography 公式 SSOT
+ *
+ * Formula(canonical):`py = (field-height - 1lh) / 2`,對齊 1em text 到 field-height center。
+ *
+ * **消費者**:menuItemVariants / sidebarMenuButtonVariants / treeItemVariants / 未來 row primitive
+ * **Rationale**:前先 3 cva 各自寫同一公式 → drift risk(item-anatomy.spec 有明文「SidebarMenuButton
+ * 獨立實作風險」)。抽本 export 後改**一處全同步**,risk 消失(對齊 Meta-Pattern M17「SSOT 必可傳播」)。
+ *
+ * 2026-04-24 D Phase 1+2 consolidation 建立。
+ */
+export declare const ROW_PADDING_BY_SIZE: Record<RowSize, string>;
+/**
+ * `<ItemPrefix>` — Row primitive 的 prefix slot wrapper。
+ *
+ * 把 prefix(icon / avatar / checkbox / indicator)包進 `h-[1lh]` 容器,
+ * 強制對齊第一行文字中線。這是 item-layout 的底層規則(詳見 spec「Prefix 垂直對齊」)。
+ *
+ * **為什麼**:
+ * - Row primitive 的 outer flex 是 `items-start`(多行 label 時 prefix 不飄移)
+ * - 單行時 prefix 透過這個 wrapper 強制對齊第一行中線,視覺效果 = `items-center`
+ * - 不同尺寸的 prefix(icon 16、Avatar 24、Checkbox 20)都能穩定置中
+ *
+ * 用法:
+ * ```tsx
+ * <div className="flex items-start gap-2">
+ *   <ItemPrefix>
+ *     <Avatar size={24} />
+ *   </ItemPrefix>
+ *   <span className="min-w-0 flex-1 truncate">{label}</span>
+ * </div>
+ * ```
+ *
+ * asChild 的 consumer(例如 `<SidebarMenuButton asChild>`)**必須自己**用這個 wrapper
+ * 包 prefix,不能省略。
+ */
+export declare const ItemPrefix: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLSpanElement> & React.RefAttributes<HTMLSpanElement>>;
+/**
+ * `itemPrefixAlignVariants` — Prefix 對齊高度的 cva SSOT(for 複雜 prefix 結構)。
+ *
+ * ── 存在的理由 ──
+ * `<ItemPrefix>` primitive 預設單一 child(icon / avatar 任一)+ inline 對齊。
+ * 但**複雜 prefix 結構**(e.g. MenuItem 可同時含 checkbox + icon/avatar 多 child)
+ * 或**block mode**(大 prefix + description 對齊塊中心)需要自建 wrapper cva。
+ * 本 cva 把 block formula SSOT 化,讓 MenuItem 等 consumer 共用,
+ * 改值一處(token or cva)→ 所有 block-prefix consumer 同步。
+ *
+ * ── Align 變體(對齊 item-anatomy.spec.md「24px 閾值對齊規則」) ──
+ * - `"inline"`:`h-[1lh]`,小 prefix(≤ 24px)對齊 label 第一行
+ * - `"block-sm"` / `"block-md"`:大 prefix + scanning desc(sm/md menu),
+ *   高度 = label(1lh) + gap(token) + desc(caption × 1.3)
+ * - `"block-lg"`:大 prefix + scanning desc(lg menu),desc 改為 body × 1.3
+ *
+ * ── Consumer ──
+ * MenuItem(inline / block-sm / block-md / block-lg)。其他 row primitive 簡單情境
+ * 直接用 `<ItemPrefix>` 就好,不需此 cva。
+ *
+ * ── SSOT 傳播 ──
+ * gap 用 `var(--item-gap-label-desc)` token;font-size 用 token-awareness
+ * (`var(--font-caption-size)` / `var(--font-body-size)`)。改 token → 公式同步。
+ */
+export declare const itemPrefixAlignVariants: (props?: ({
+    align?: "inline" | "block-sm" | "block-md" | "block-lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * `<ItemLabel>` — Row primitive 的 label span。
+ *
+ * 預設 `min-w-0 flex-1 truncate`——單行截斷,佔滿剩餘 flex 空間。
+ * 加 `data-sidebar="menu-label"` attribute 讓 sidebar icon 模式的 CSS selector 能命中。
+ *
+ * 用法:
+ * ```tsx
+ * <ItemLabel>{label}</ItemLabel>
+ * ```
+ */
+export declare const ItemLabel: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLSpanElement> & React.RefAttributes<HTMLSpanElement>>;
+/**
+ * `<ItemContent>` — Row primitive 的 label + optional description 內容區(SSOT)。
+ *
+ * ── 存在的唯一理由 ──
+ * 封裝「flex-col + label + description + `mt-[var(--item-gap-label-desc)]` gap」結構,
+ * 避免 13+ 消費者各自 hard-code `mt-0.5`。改 token 一處,全 DS 同步。
+ *
+ * ── Consumer 偏離 canonical ──
+ * 消費端若有**確切合理理由**不用 `<ItemContent>` / 需自訂 label/desc 行為,必在
+ * 該元件 `spec.md` 明文寫下 rationale(對齊 item-anatomy canonical「偏離必明文」)。
+ * 合法偏離範例:
+ *   - MenuItem 的 `leading-compact + text-caption` scanning-mode typography
+ *     → MenuItem spec 明文 rationale + 消費 `--item-gap-label-desc` token 直接用
+ *   - SelectionItem 的 control slot 跟 block formula 綁定
+ *     → SelectionItem spec 明文 rationale
+ *
+ * ── Props ──
+ * - `label`:label 內容(ReactNode,必填)
+ * - `description`:description 內容(ReactNode,optional)
+ * - `mode`:typography tier(scanning vs reading,世界級對齊 Material `dense` / Carbon `size` / Ant `size`)
+ *   - `"reading"`(預設):繼承 parent `text-body`(14px / 1.5 leading),舒適閱讀(Family 2 / Material body-large 派)
+ *   - `"scanning"`:desc 縮為 `text-caption`(12px)+ `leading-compact`(1.3),緊湊掃視
+ *     (Family 1 Menu item / Material body-medium dense 派)
+ * - `descriptionTone`:desc 顏色語意
+ *   - `"secondary"`(預設):`text-fg-secondary`
+ *   - `"error"`:`text-error-text`
+ *   - `"muted"`:`text-fg-muted`
+ * - `descriptionWrap`:desc 多行 wrap(預設 true)/ false = truncate
+ * - `labelClassName` / `descriptionClassName`:escape hatches(明文 rationale 才用)
+ *
+ * ── World-class benchmark ──
+ * 6 家 DS(Material / Polaris / Atlassian / Apple HIG / Carbon / Ant)一致用
+ * 14/20 vs 16/24 兩擋 body 表達 scanning vs reading。API 兩派:(A)密度 prop
+ * Material `dense` / Carbon `size` / Ant `size`(本 DS 採 A 派);(B)typography
+ * token 手選 Polaris / Atlassian / Apple。
+ */
+export interface ItemContentProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    label: React.ReactNode;
+    description?: React.ReactNode;
+    /**
+     * Typography mode — **leading 行為**(跟 size 正交的另一維):
+     * - `"reading"`(預設):default leading(1.5)— Family 2 List item 舒適閱讀
+     * - `"scanning"`:`leading-compact`(1.3)+ desc 降一 tier —— Menu item / Step 掃視
+     */
+    mode?: "reading" | "scanning";
+    /**
+     * Size tier — **label 字級**(跟 mode 正交的另一維):
+     * - `"md"`(預設):label `text-body`(14)
+     * - `"lg"`:label `text-body-lg`(16)— desc 永遠比 label 小一 tier(body)
+     *
+     * 2 × 2 = 4 typography 組合,對應 4 tokens:
+     * - md + reading  → body(14/1.5) + body(14/1.5)
+     * - md + scanning → body(14/1.3) + caption(12/1.3)
+     * - lg + reading  → body-lg(16/1.5) + body(14/1.5)
+     * - lg + scanning → body-lg(16/1.3) + body(14/1.3)
+     */
+    size?: "md" | "lg";
+    descriptionTone?: "secondary" | "error" | "muted" | "disabled";
+    descriptionWrap?: boolean;
+    /**
+     * Description 多行截斷(line-clamp-N)。undefined = 不 clamp(自由 wrap)。
+     * Tailwind line-clamp utilities 支援 1-6。
+     */
+    descriptionClamp?: number;
+    /**
+     * Description `break-words`(default `false`,僅在 consumer 需要時 opt-in)。
+     * 使用情境:SelectionItem / Steps 這類 description 可能塞長英文 token 需 break。
+     */
+    descriptionBreakWords?: boolean;
+    /**
+     * Label truncate (default `true`, 對齊 row-item 大宗 idiom)。
+     * Opt-out(`false`)for card-like consumers(e.g. NameCard label 允許 wrap)。
+     * World-class 對照:Material `ListItemText primaryTypographyProps.noWrap` default true。
+     */
+    labelTruncate?: boolean;
+    labelClassName?: string;
+    descriptionClassName?: string;
+}
+export declare const ItemContent: React.ForwardRefExoticComponent<ItemContentProps & React.RefAttributes<HTMLDivElement>>;
+export declare const RowSizeProvider: React.Provider<RowSize | null>;
+/**
+ * 讀取當前 row size。在 row primitive 子樹外呼叫會回 fallback(預設 "md")。
+ * Row primitive 實作者不該呼叫這個——你們已經知道自己的 size。
+ * 這個 hook 是給 `<ItemIcon>` / `<ItemAvatar>` 和 asChild consumer 的逃生艙用。
+ */
+export declare function useRowSize(fallback?: RowSize): RowSize;
+export interface ItemIconProps extends Omit<React.SVGAttributes<SVGSVGElement>, "children"> {
+    /** Lucide icon 元件(不是 JSX element) */
+    icon: LucideIcon;
+}
+/**
+ * `<ItemIcon icon={Folder} />` — 自動查 `ICON_SIZE[rowSize]`,包在 `ItemPrefix` 內。
+ * 永遠對齊第一行 label(item-layout 的 icon 永遠 inline)。
+ */
+export declare const ItemIcon: React.ForwardRefExoticComponent<ItemIconProps & React.RefAttributes<SVGSVGElement>>;
+export interface ItemAvatarProps extends Omit<AvatarProps, "size"> {
+    /**
+     * 對齊模式(選填,預設 `"inline"`):
+     * - `"inline"`:視覺重量輕的 avatar,對齊第一行 label(20/24/24 @ sm/md/lg)
+     * - `"block"`:視覺重量重的 avatar,對齊 label + description 文字塊(32/32/40 @ sm/md/lg)
+     *
+     * 預設 inline——大宗情境(扁平 row、footer user、主清單)都用這個。
+     * 只有 avatar 是 item 主體(人物卡、顯著身份辨識)才用 block。
+     *
+     * 詳見 `item-anatomy.spec.md`「Avatar 尺寸選擇」節,含 24px 對齊模式閾值規則。
+     */
+    mode?: "inline" | "block";
+}
+/**
+ * `<ItemAvatar alt="Alan" color="blue" />` — 自動查 `AVATAR_SIZE[mode][rowSize]`,
+ * 包在 `ItemPrefix` 內。
+ *
+ * asChild consumer 的標準用法——不需知道 size,不需 import AVATAR_SIZE,
+ * 不可能硬寫錯誤尺寸。
+ */
+export declare const ItemAvatar: React.ForwardRefExoticComponent<ItemAvatarProps & React.RefAttributes<HTMLDivElement>>;
+export interface ItemInlineActionButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+    /** Lucide icon 元件 */
+    icon: LucideIcon;
+    /** 可選:額外加在 icon 上的 className(例如 rotate transition) */
+    iconClassName?: string;
+    /**
+     * Size 明確覆寫(用於 fields / Tag 等**不在 `RowSizeProvider` 樹內**的 host):
+     * 傳了就以此為準,否則從 `RowSizeContext` 讀(fallback "md")。
+     *
+     * 使用時機:
+     * - Row primitive 子樹(Sidebar / TreeView / SelectMenu / DropdownMenu)→ **不傳**,吃 context
+     * - Field / Tag(自有 size 系統,沒包 RowSizeProvider)→ **必傳** `size={hostSize}`
+     */
+    size?: RowSize;
+    /**
+     * Hover / active bg className override(chromatic host 專用,如 Tag solid variant)。
+     *
+     * 預設 `group-hover/action:bg-neutral-hover group-active/action:bg-neutral-active`。
+     * 提供後**完全取代** hover + active 雙態 className,但**不影響** rest 態(永遠 bg-transparent)
+     * 與 overlay-trigger 態(`group-data-[state=open]:bg-neutral-selected`)。
+     *
+     * Consumer 須**同時**包含 hover + active 兩態 selector,例:
+     * `'group-hover/action:bg-[var(--my-hover)] group-active/action:bg-[var(--my-active)]'`
+     *
+     * Use case:Tag solid(blue/green/red 等)需 hover bg 跟 host 色相一致(非 neutral)。
+     */
+    hoverBgClassName?: string;
+    /**
+     * 標記本 button 是 **overlay trigger**(DropdownMenu / Popover / Tooltip 透過 `asChild` 包覆)。
+     *
+     * `true` 時:Radix overlay open 期間(`data-state="open"`)button 維持 host hover 樣式
+     * — 視覺鎖,讓 user 追溯 floating panel 來源(對齊 shadcn / Radix Themes / Material)。
+     *
+     * `false` 時(default):無 data-state=open 樣式 — 適用 in-place 互動如 `Collapsible.Trigger`
+     * (展開內容接在 trigger 下方,不需追溯)、drag handle、dismiss X 等。
+     *
+     * Canonical 詳 `inline-action.spec.md`「Overlay trigger canonical」段。
+     *
+     * @default false
+     */
+    overlayTrigger?: boolean;
+}
+export declare const ItemInlineActionButton: React.ForwardRefExoticComponent<ItemInlineActionButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export interface ItemInlineActionProps {
+    action: InlineActionConfig;
+    /** Size 覆寫(見 `ItemInlineActionButtonProps.size`)——Field Controls / Tag 必傳 */
+    size?: RowSize;
+}
+export declare const ItemInlineAction: React.ForwardRefExoticComponent<ItemInlineActionProps & React.RefAttributes<HTMLButtonElement>>;
+declare const SUFFIX_HOVER_REVEAL_BY_GROUP: {
+    readonly "menu-item": "opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100 transition-opacity duration-150";
+    readonly "tree-item": "opacity-0 group-hover/tree-item:opacity-100 group-has-[:focus-visible]/tree-item:opacity-100 transition-opacity duration-150";
+    readonly row: "opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity duration-150";
+};
+export type ItemSuffixHoverGroup = keyof typeof SUFFIX_HOVER_REVEAL_BY_GROUP;
+export interface ItemSuffixProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /**
+     * Hover-reveal:預設隱藏,父層 row hover / keyboard focus-visible 時才淡入。
+     * 對齊 TreeView / SidebarMenuButton inline action 行為。預設 false(永遠顯示,如 Badge)。
+     *
+     * 用 `group-has-[:focus-visible]` 而非 `group-focus-within`——後者會被 mouse click 觸發,
+     * 導致 click 後 suffix 永久顯示直到焦點移走。focus-visible 只在鍵盤 tab 時啟動。
+     */
+    hoverReveal?: boolean;
+    /**
+     * 父層 row 的 group selector(consumer 必加 `group/<name>` 到 row wrapper)。
+     * 預設 `'menu-item'`(對齊 MenuItem / Sidebar)。其他 row primitive:
+     * `'tree-item'`(TreeView)/ `'row'`(DataTable / FileItem)。
+     *
+     * 加新 row primitive(且需 hover-reveal)時:在 `SUFFIX_HOVER_REVEAL_BY_GROUP`
+     * 加 entry,Tailwind JIT 才能 scan 到 static class。
+     */
+    hoverGroup?: ItemSuffixHoverGroup;
+}
+export declare const ItemSuffix: React.ForwardRefExoticComponent<ItemSuffixProps & React.RefAttributes<HTMLSpanElement>>;
+export {};
+//# sourceMappingURL=item-anatomy.d.ts.map

package/dist/patterns/element-anatomy/item-anatomy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-anatomy.d.ts","sourceRoot":"","sources":["../../../src/patterns/element-anatomy/item-anatomy.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C,OAAO,EAAU,KAAK,WAAW,EAAE,MAAM,0CAA0C,CAAA;AAanF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,UAAU,CAAA;IAChB,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAA;CAC3D;AAED;;;;;;;;;GASG;AAIH,iEAAiE;AACjE,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAIxC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAI7C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;CAGgD,CAAA;AAExE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,OAAO,GAAG,KAAK,CAAC,aAAa,CAE5E;AAED;;;;GAIG;AAEH,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAI/D,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAIvD,CAAA;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,UAAU,+GAmBrB,CAAA;AAGF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,eAAO,MAAM,uBAAuB;;8EAqBnC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,+GAUpB,CAAA;AAGF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAC3F,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,CAAA;IAC7B;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;IAClB,eAAe,CAAC,EAAE,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,CAAA;IAC9D,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAGD,eAAO,MAAM,WAAW,yFA8EvB,CAAA;AAmBD,eAAO,MAAM,eAAe,gCAA0B,CAAA;AAEtD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,GAAE,OAAc,GAAG,OAAO,CAE5D;AAUD,MAAM,WAAW,aACf,SAAQ,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,aAAa,CAAC,EAAE,UAAU,CAAC;IAC5D,qCAAqC;IACrC,IAAI,EAAE,UAAU,CAAA;CACjB;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ,qFAiBpB,CAAA;AAGD,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC;IAChE;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;CAC1B;AAED;;;;;;GAMG;AAEH,eAAO,MAAM,UAAU,wFAWtB,CAAA;AA8BD,MAAM,WAAW,2BACf,SAAQ,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,UAAU,CAAC;IACvE,qBAAqB;IACrB,IAAI,EAAE,UAAU,CAAA;IAChB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,eAAO,MAAM,sBAAsB,uGA+CjC,CAAA;AAYF,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,kBAAkB,CAAA;IAC1B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,eAAO,MAAM,gBAAgB,iGAgB3B,CAAA;AAiBF,QAAA,MAAM,4BAA4B;;;;CAMxB,CAAA;AAEV,MAAM,MAAM,oBAAoB,GAAG,MAAM,OAAO,4BAA4B,CAAA;AAE5E,MAAM,WAAW,eAAgB,SAAQ,KAAK,CAAC,cAAc,CAAC,eAAe,CAAC;IAC5E;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,oBAAoB,CAAA;CAClC;AAED,eAAO,MAAM,UAAU,yFAYtB,CAAA"}

package/dist/patterns/element-anatomy/item-anatomy.js

@@ -0,0 +1,272 @@
+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 { Avatar } from "../../components/Avatar/avatar.js";
+import { Tooltip, TooltipTrigger, TooltipContent } from "../../components/Tooltip/tooltip.js";
+const ICON_SIZE = {
+  sm: 16,
+  md: 16,
+  lg: 20
+};
+const AVATAR_SIZE = {
+  inline: { sm: 20, md: 24, lg: 24 },
+  block: { sm: 32, md: 32, lg: 40 }
+};
+function getUniformPrefixSlotStyle(size) {
+  return { "--item-prefix-slot": `${AVATAR_SIZE.inline[size]}px` };
+}
+const INLINE_ACTION_HOVER_BG_SIZE = {
+  sm: 18,
+  md: 18,
+  lg: 22
+};
+const ROW_PADDING_BY_SIZE = {
+  sm: "text-body leading-compact py-[calc((var(--field-height-sm)-1lh)/2)]",
+  md: "text-body leading-compact py-[calc((var(--field-height-md)-1lh)/2)]",
+  lg: "text-body-lg leading-compact py-[calc((var(--field-height-lg)-1lh)/2)]"
+};
+const ItemPrefix = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+  "span",
+  {
+    ref,
+    className: cn(
+      "h-[1lh] shrink-0 flex items-center",
+      // Uniform prefix slot:讀取 `--item-prefix-slot` CSS variable,
+      // fallback `auto`(= 預設行為,不佔額外寬度、不 center)。
+      // Row-primitive 頂層容器(例如 `<SidebarProvider uniformPrefix>` 的 wrapper)
+      // 若設定這個 var,小尺寸 prefix(icon 16px)會在固定寬槽(24px @ md)內置中,
+      // 與大尺寸 prefix(app logo 24px)對齊,達成 label 齊左。
+      // 詳見 item-anatomy.spec.md「Uniform prefix slot」節。
+      "min-w-[var(--item-prefix-slot,auto)] justify-center",
+      className
+    ),
+    ...props
+  }
+));
+ItemPrefix.displayName = "ItemPrefix";
+const itemPrefixAlignVariants = cva(
+  "flex items-center gap-2 shrink-0",
+  {
+    variants: {
+      align: {
+        inline: "h-[1lh]",
+        // sm/md desc = text-caption (12px × 1.3 = 15.6px)
+        // block-sm / block-md:scanning mode(body + caption 組合)→ 用 scanning mode 專屬 gap token
+        "block-sm": "h-[calc(1lh+var(--item-gap-label-desc-scanning)+var(--font-caption-size)*1.3)]",
+        "block-md": "h-[calc(1lh+var(--item-gap-label-desc-scanning)+var(--font-caption-size)*1.3)]",
+        // block-lg:scanning-lg mode(body-lg + body compact 組合)→ 用 scanning-lg mode 專屬 gap token
+        "block-lg": "h-[calc(1lh+var(--item-gap-label-desc-scanning-lg)+var(--font-body-size)*1.3)]"
+      }
+    },
+    defaultVariants: {
+      align: "inline"
+    }
+  }
+);
+const ItemLabel = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+  "span",
+  {
+    ref,
+    "data-sidebar": "menu-label",
+    className: cn("min-w-0 flex-1 truncate", className),
+    ...props
+  }
+));
+ItemLabel.displayName = "ItemLabel";
+const ItemContent = React.forwardRef(
+  ({
+    label,
+    description,
+    mode = "reading",
+    size = "md",
+    descriptionTone = "secondary",
+    descriptionWrap = true,
+    descriptionClamp,
+    descriptionBreakWords = false,
+    labelTruncate = true,
+    labelClassName,
+    descriptionClassName,
+    className,
+    ...props
+  }, ref) => {
+    const toneClass = {
+      secondary: "text-fg-secondary",
+      error: "text-error-text",
+      muted: "text-fg-muted",
+      disabled: "text-fg-disabled"
+    }[descriptionTone];
+    const isLg = size === "lg";
+    const modeClass = mode === "scanning" ? isLg ? "text-[length:var(--font-body-size)] leading-compact" : "text-[length:var(--font-caption-size)] leading-compact" : isLg ? "text-[length:var(--font-body-size)]" : "";
+    const clampClass = descriptionClamp ? `line-clamp-${descriptionClamp}` : "";
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref,
+        className: cn("flex flex-col min-w-0 flex-1", className),
+        ...props,
+        children: [
+          /* @__PURE__ */ jsx("span", { className: cn(labelTruncate && "truncate", labelClassName), children: label }),
+          description && /* @__PURE__ */ jsx(
+            "span",
+            {
+              className: cn(
+                // Typography-mode-aware gap token(2026-04-23):
+                // (mode, size)2 維正交 → 4 token 對應 4 typography 組合
+                mode === "scanning" ? isLg ? "mt-[var(--item-gap-label-desc-scanning-lg)]" : "mt-[var(--item-gap-label-desc-scanning)]" : isLg ? "mt-[var(--item-gap-label-desc-reading-lg)]" : "mt-[var(--item-gap-label-desc-reading)]",
+                modeClass,
+                toneClass,
+                clampClass,
+                descriptionBreakWords && "break-words",
+                !descriptionWrap && "truncate",
+                descriptionClassName
+              ),
+              children: description
+            }
+          )
+        ]
+      }
+    );
+  }
+);
+ItemContent.displayName = "ItemContent";
+const RowSizeContext = React.createContext(null);
+const RowSizeProvider = RowSizeContext.Provider;
+function useRowSize(fallback = "md") {
+  return React.useContext(RowSizeContext) ?? fallback;
+}
+const ItemIcon = React.forwardRef(
+  ({ icon: Icon, className, ...props }, ref) => {
+    const size = useRowSize();
+    return (
+      // data-prefix-type="icon" 讓 row-primitive 容器的 `:has()` selector 能偵測類型,
+      // 用於 `<SidebarProvider uniformPrefix>` opt-in 後的混用 auto-detection
+      /* @__PURE__ */ jsx(ItemPrefix, { "data-prefix-type": "icon", children: /* @__PURE__ */ jsx(
+        Icon,
+        {
+          ref,
+          size: ICON_SIZE[size],
+          className: cn("shrink-0", className),
+          "aria-hidden": true,
+          ...props
+        }
+      ) })
+    );
+  }
+);
+ItemIcon.displayName = "ItemIcon";
+const ItemAvatar = React.forwardRef(
+  ({ mode = "inline", ...props }, ref) => {
+    const size = useRowSize();
+    return (
+      // data-prefix-type="avatar" 讓 row-primitive 容器的 `:has()` selector 能偵測類型,
+      // 用於 `<SidebarProvider uniformPrefix>` opt-in 後的混用 auto-detection
+      /* @__PURE__ */ jsx(ItemPrefix, { "data-prefix-type": "avatar", children: /* @__PURE__ */ jsx(Avatar, { ref, size: AVATAR_SIZE[mode][size], ...props }) })
+    );
+  }
+);
+ItemAvatar.displayName = "ItemAvatar";
+const ItemInlineActionButton = React.forwardRef(({ icon: Icon, className, iconClassName, style, type = "button", size: sizeProp, hoverBgClassName, overlayTrigger = false, ...rest }, ref) => {
+  const contextSize = useRowSize();
+  const size = sizeProp ?? contextSize;
+  const iconPx = ICON_SIZE[size];
+  const hoverBgPx = INLINE_ACTION_HOVER_BG_SIZE[size];
+  return /* @__PURE__ */ jsxs(
+    "button",
+    {
+      ref,
+      type,
+      className: cn(
+        "group/action relative grid place-content-center shrink-0 cursor-pointer",
+        "text-fg-muted hover:text-foreground active:text-foreground transition-colors",
+        // Overlay trigger active state — 只在 consumer 顯式宣告 overlayTrigger=true 時生效
+        // (canonical 2026-05-05:Collapsible / drag / dismiss 等 in-place 互動 ≠ overlay,
+        // 不應 leak 視覺 lock。詳 inline-action.spec.md「Overlay trigger canonical」)
+        overlayTrigger && "data-[state=open]:text-foreground",
+        "focus-visible:outline-2 focus-visible:outline-ring",
+        className
+      ),
+      style: { width: iconPx, height: iconPx, ...style },
+      ...rest,
+      children: [
+        /* @__PURE__ */ jsx(
+          "span",
+          {
+            "aria-hidden": true,
+            className: cn(
+              "absolute pointer-events-none",
+              "rounded-md",
+              "bg-transparent",
+              hoverBgClassName ?? "group-hover/action:bg-neutral-hover group-active/action:bg-neutral-active",
+              // Overlay 開啟 = 維持 host hover bg(只在 overlayTrigger=true 時生效)
+              overlayTrigger && "group-data-[state=open]/action:bg-neutral-hover",
+              "transition-colors"
+            ),
+            style: {
+              width: hoverBgPx,
+              height: hoverBgPx,
+              top: "50%",
+              left: "50%",
+              transform: "translate(-50%, -50%)"
+            }
+          }
+        ),
+        /* @__PURE__ */ jsx(Icon, { size: iconPx, className: cn("relative", iconClassName), "aria-hidden": true })
+      ]
+    }
+  );
+});
+ItemInlineActionButton.displayName = "ItemInlineActionButton";
+const ItemInlineAction = React.forwardRef(({ action, size }, ref) => /* @__PURE__ */ jsxs(Tooltip, { children: [
+  /* @__PURE__ */ jsx(TooltipTrigger, { asChild: true, children: /* @__PURE__ */ jsx(
+    ItemInlineActionButton,
+    {
+      ref,
+      icon: action.icon,
+      "aria-label": action.label,
+      onClick: action.onClick,
+      size
+    }
+  ) }),
+  /* @__PURE__ */ jsx(TooltipContent, { children: action.label })
+] }));
+ItemInlineAction.displayName = "ItemInlineAction";
+const SUFFIX_HOVER_REVEAL_BY_GROUP = {
+  "menu-item": "opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100 transition-opacity duration-150",
+  "tree-item": "opacity-0 group-hover/tree-item:opacity-100 group-has-[:focus-visible]/tree-item:opacity-100 transition-opacity duration-150",
+  row: "opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity duration-150"
+};
+const ItemSuffix = React.forwardRef(
+  ({ className, hoverReveal = false, hoverGroup = "menu-item", ...props }, ref) => /* @__PURE__ */ jsx(
+    "span",
+    {
+      ref,
+      className: cn(
+        "h-[1lh] shrink-0 ml-auto flex items-center gap-2",
+        hoverReveal && SUFFIX_HOVER_REVEAL_BY_GROUP[hoverGroup],
+        className
+      ),
+      ...props
+    }
+  )
+);
+ItemSuffix.displayName = "ItemSuffix";
+export {
+  AVATAR_SIZE,
+  ICON_SIZE,
+  INLINE_ACTION_HOVER_BG_SIZE,
+  ItemAvatar,
+  ItemContent,
+  ItemIcon,
+  ItemInlineAction,
+  ItemInlineActionButton,
+  ItemLabel,
+  ItemPrefix,
+  ItemSuffix,
+  ROW_PADDING_BY_SIZE,
+  RowSizeProvider,
+  getUniformPrefixSlotStyle,
+  itemPrefixAlignVariants,
+  useRowSize
+};
+//# sourceMappingURL=item-anatomy.js.map