@qijenchen/design-system 0.1.0-beta.4 → 0.1.0-beta.6

package/dist/components/AppShell/app-shell.js

@@ -0,0 +1,214 @@
+import { jsx, jsxs, Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { X } from "lucide-react";
+import { Sheet, SheetContent } from "../Sheet/sheet.js";
+import { Button } from "../Button/button.js";
+import { ScrollArea } from "../ScrollArea/scroll-area.js";
+import { ChromeHeader } from "../../patterns/header-canonical/chrome-header.js";
+import { useIsNarrowViewport } from "../../hooks/use-is-narrow-viewport.js";
+import { cn } from "../../lib/utils.js";
+const AppShellContext = React.createContext(null);
+function useAppShell() {
+  const ctx = React.useContext(AppShellContext);
+  if (!ctx) throw new Error("AppShellAside must be used within <AppShell>");
+  return ctx;
+}
+const XL_BREAKPOINT_PX = 1280;
+function useIsXl() {
+  const [isXl, setIsXl] = React.useState(() => {
+    if (typeof window === "undefined") return false;
+    return window.matchMedia(`(min-width: ${XL_BREAKPOINT_PX}px)`).matches;
+  });
+  React.useEffect(() => {
+    const mq = window.matchMedia(`(min-width: ${XL_BREAKPOINT_PX}px)`);
+    const handler = (e) => setIsXl(e.matches);
+    mq.addEventListener("change", handler);
+    return () => mq.removeEventListener("change", handler);
+  }, []);
+  return isXl;
+}
+const ASIDE_WIDTH_MIN = 240;
+const ASIDE_WIDTH_MAX = 640;
+const ASIDE_WIDTH_DEFAULT = 320;
+function resolveAsideWidth(width, isXl) {
+  if (typeof width === "number") {
+    return Math.max(ASIDE_WIDTH_MIN, Math.min(ASIDE_WIDTH_MAX, width));
+  }
+  if (width && typeof width === "object") {
+    const v = (isXl ? width.xl ?? width.md : width.md) ?? ASIDE_WIDTH_DEFAULT;
+    return Math.max(ASIDE_WIDTH_MIN, Math.min(ASIDE_WIDTH_MAX, v));
+  }
+  return ASIDE_WIDTH_DEFAULT;
+}
+function SkipToMain() {
+  return /* @__PURE__ */ jsx(
+    "a",
+    {
+      href: "#app-shell-main",
+      className: cn(
+        "sr-only focus:not-sr-only",
+        "focus:fixed focus:top-2 focus:left-2 focus:z-50",
+        "focus:px-3 focus:py-2 focus:rounded-md",
+        "focus:bg-surface focus:text-foreground focus:shadow-[var(--elevation-200)]",
+        "focus:outline-none focus:ring-2 focus:ring-primary"
+      ),
+      children: "Skip to main content"
+    }
+  );
+}
+const AppShell = React.forwardRef(
+  ({
+    layout = "primary-sidebar",
+    sidebar,
+    header,
+    globalHeader,
+    aside,
+    asideOpen: asideOpenProp,
+    onAsideOpenChange,
+    children,
+    className,
+    ...props
+  }, ref) => {
+    const [asideOpenInternal, setAsideOpenInternal] = React.useState(false);
+    const isControlled = asideOpenProp !== void 0;
+    const asideOpen = isControlled ? asideOpenProp : asideOpenInternal;
+    const setAsideOpen = React.useCallback(
+      (open) => {
+        if (!isControlled) setAsideOpenInternal(open);
+        onAsideOpenChange == null ? void 0 : onAsideOpenChange(open);
+      },
+      [isControlled, onAsideOpenChange]
+    );
+    const isMobile = useIsNarrowViewport();
+    React.useEffect(() => {
+      const onKey = (e) => {
+        if (e.key === "." && (e.metaKey || e.ctrlKey)) {
+          e.preventDefault();
+          setAsideOpen(!asideOpen);
+        }
+      };
+      window.addEventListener("keydown", onKey);
+      return () => window.removeEventListener("keydown", onKey);
+    }, [asideOpen, setAsideOpen]);
+    const ctxValue = React.useMemo(
+      () => ({ layout, asideOpen, setAsideOpen, isMobile }),
+      [layout, asideOpen, setAsideOpen, isMobile]
+    );
+    if (layout === "primary-header") {
+      return /* @__PURE__ */ jsx(AppShellContext.Provider, { value: ctxValue, children: /* @__PURE__ */ jsxs(
+        "div",
+        {
+          ref,
+          className: cn("flex h-svh w-full flex-col overflow-hidden bg-canvas", className),
+          ...props,
+          children: [
+            /* @__PURE__ */ jsx(SkipToMain, {}),
+            globalHeader && /* @__PURE__ */ jsx("div", { className: "flex-shrink-0", children: globalHeader }),
+            /* @__PURE__ */ jsxs("div", { className: "flex flex-1 min-h-0 w-full", children: [
+              sidebar,
+              /* @__PURE__ */ jsxs("div", { className: "flex flex-col flex-1 min-w-0 min-h-0 overflow-hidden", children: [
+                header && /* @__PURE__ */ jsx("div", { className: "flex-shrink-0", children: header }),
+                /* @__PURE__ */ jsx(
+                  "main",
+                  {
+                    id: "app-shell-main",
+                    tabIndex: -1,
+                    className: "flex-1 min-w-0 min-h-0 overflow-y-auto focus:outline-none",
+                    children
+                  }
+                )
+              ] }),
+              aside
+            ] })
+          ]
+        }
+      ) });
+    }
+    return /* @__PURE__ */ jsx(AppShellContext.Provider, { value: ctxValue, children: /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref,
+        className: cn("flex h-svh w-full overflow-hidden bg-canvas", className),
+        ...props,
+        children: [
+          /* @__PURE__ */ jsx(SkipToMain, {}),
+          sidebar,
+          /* @__PURE__ */ jsxs("div", { className: "flex flex-col flex-1 min-w-0 min-h-0 overflow-hidden", children: [
+            header && // Header 在 main column 內(main col sibling,非 main descendant)→ 跟 W3C ARIA in HTML
+            // banner rule 對照:`<header>` 在 main descendant 才不是 banner,本 ChromeHeader 是 <div>
+            // 所以本來就不會被 banner role 計算。仍包 wrap div not <header> 確保不無意觸發 banner。
+            /* @__PURE__ */ jsx("div", { className: "flex-shrink-0", children: header }),
+            /* @__PURE__ */ jsx(
+              "main",
+              {
+                id: "app-shell-main",
+                tabIndex: -1,
+                className: "flex-1 min-h-0 overflow-y-auto focus:outline-none",
+                children
+              }
+            )
+          ] }),
+          aside
+        ]
+      }
+    ) });
+  }
+);
+AppShell.displayName = "AppShell";
+const AppShellAside = React.forwardRef(
+  ({ title, width, children, className }, ref) => {
+    const { asideOpen, setAsideOpen, isMobile } = useAppShell();
+    const isXl = useIsXl();
+    const resolvedWidth = resolveAsideWidth(width, isXl);
+    const frame = /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsxs(ChromeHeader, { children: [
+        /* @__PURE__ */ jsx("h2", { className: "text-body-lg font-medium flex-1 truncate", children: title }),
+        /* @__PURE__ */ jsx(
+          Button,
+          {
+            iconOnly: true,
+            dismiss: true,
+            size: "sm",
+            startIcon: X,
+            "aria-label": "關閉",
+            onClick: () => setAsideOpen(false)
+          }
+        )
+      ] }),
+      /* @__PURE__ */ jsx(ScrollArea, { className: "flex-1 min-h-0", children })
+    ] });
+    if (isMobile) {
+      return /* @__PURE__ */ jsx(Sheet, { open: asideOpen, onOpenChange: setAsideOpen, children: /* @__PURE__ */ jsx(
+        SheetContent,
+        {
+          side: "right",
+          className: "w-[min(90vw,var(--app-shell-aside-modal-width))] flex flex-col p-0 [&>button]:hidden",
+          style: { ["--app-shell-aside-modal-width"]: `${resolvedWidth}px` },
+          children: frame
+        }
+      ) });
+    }
+    if (!asideOpen) return null;
+    return /* @__PURE__ */ jsx(
+      "aside",
+      {
+        ref,
+        "aria-label": title,
+        className: cn(
+          "flex flex-col h-full min-h-0 overflow-hidden",
+          "bg-surface border-l border-divider",
+          className
+        ),
+        style: { width: resolvedWidth },
+        children: frame
+      }
+    );
+  }
+);
+AppShellAside.displayName = "AppShellAside";
+export {
+  AppShell,
+  AppShellAside,
+  useAppShell
+};
+//# sourceMappingURL=app-shell.js.map

package/dist/components/AppShell/app-shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-shell.js","sources":["../../../src/components/AppShell/app-shell.tsx"],"sourcesContent":["// @benchmark-cited: 2026-05-19 — Mantine AppShell / Ant Layout / Material 3 Drawer / Atlassian Navigation System cite in app-shell.spec.md frontmatter.\n/**\n * AppShell — web service page-level layout primitive。\n *\n * 組合 Sidebar + ChromeHeader + Aside + main 成完整 page shell。SSOT 邊界:本 pattern only\n * own slot composition + layout mode + Aside responsive mode;不 own sidebar / header /\n * sheet 視覺(各自 spec own)。\n *\n * 對齊 Mantine AppShell compound API + Ant Layout slot 模式 + Material 3 standard/modal\n * drawer canonical(per spec.md frontmatter cite)。\n *\n * Spec SSOT:`patterns/app-shell/app-shell.spec.md`\n */\n\nimport * as React from 'react'\nimport { X as XIcon } from 'lucide-react'\nimport {\n  Sheet,\n  SheetContent,\n} from '@/design-system/components/Sheet/sheet'\nimport { Button } from '@/design-system/components/Button/button'\nimport { ScrollArea } from '@/design-system/components/ScrollArea/scroll-area'\nimport { ChromeHeader } from '@/design-system/patterns/header-canonical/chrome-header'\nimport { useIsNarrowViewport } from '@/design-system/hooks/use-is-narrow-viewport'\nimport { cn } from '@/lib/utils'\n\n// ── Types ────────────────────────────────────────────────────────────────────\n\ntype AppShellLayout = 'primary-sidebar' | 'primary-header'\n\nexport interface AppShellProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** primary-sidebar (Linear/Notion 派) | primary-header (GitHub/Slack 派);預設 primary-sidebar */\n  layout?: AppShellLayout\n  /** Sidebar 元素(必傳 Sidebar primitive,per Consumer 紀律)*/\n  sidebar?: React.ReactNode\n  /**\n   * Local page header(永遠 render 在 main column 頂部,當前頁 actions / breadcrumb / page-level filter)。\n   * 兩 layout mode 都會 render 此 slot — `primary-header` mode 多了 globalHeader 在上方,\n   * **不取代** local header(per 2026-05-20 user clarification「primary-header = primary-sidebar + 一條 global header」)。\n   */\n  header?: React.ReactNode\n  /**\n   * Global header(僅 `primary-header` mode render)。橫跨整 viewport 的頂部 bar:\n   * account avatar / workspace switcher / global search / notifications。\n   * 對齊 GitHub top nav / Slack workspace bar / Gmail logo bar 慣例。\n   * `primary-sidebar` mode 傳此 prop 會被忽略。\n   */\n  globalHeader?: React.ReactNode\n  /** Aside 元素(`<AppShellAside>` sub-component);可選 */\n  aside?: React.ReactNode\n  /** Aside open state(modal mode 必須)*/\n  asideOpen?: boolean\n  onAsideOpenChange?: (open: boolean) => void\n  /** Main content;`<main>` landmark + padding=0 */\n  children: React.ReactNode\n}\n\nexport interface AppShellAsideProps {\n  /** Required:modal mode 走 Sheet → aria-labelledby 強制,per sheet.spec.md:98 */\n  title: string\n  /** Width(number 或 breakpoint-keyed object);clamp min:240 max:640 */\n  width?: number | { md?: number; xl?: number }\n  /** Children content */\n  children: React.ReactNode\n  className?: string\n}\n\n// ── Context ──────────────────────────────────────────────────────────────────\n\ninterface AppShellContextValue {\n  layout: AppShellLayout\n  asideOpen: boolean\n  setAsideOpen: (open: boolean) => void\n  isMobile: boolean\n}\n\nconst AppShellContext = React.createContext<AppShellContextValue | null>(null)\n\nfunction useAppShell(): AppShellContextValue {\n  const ctx = React.useContext(AppShellContext)\n  if (!ctx) throw new Error('AppShellAside must be used within <AppShell>')\n  return ctx\n}\n\n// Mobile breakpoint:**消費既有 `useIsNarrowViewport`**(`hooks/use-is-narrow-viewport.ts` SSOT,\n// 768px,跟 Sidebar SSOT 同源)— 不發明 local hook,per codex Layer B D2/D4 verdict 避 drift。\n\n// xl breakpoint(對齊 Tailwind v4 xl = 1280px,DS-wide consensus)\nconst XL_BREAKPOINT_PX = 1280\n\nfunction useIsXl(): boolean {\n  const [isXl, setIsXl] = React.useState<boolean>(() => {\n    if (typeof window === 'undefined') return false\n    return window.matchMedia(`(min-width: ${XL_BREAKPOINT_PX}px)`).matches\n  })\n\n  React.useEffect(() => {\n    const mq = window.matchMedia(`(min-width: ${XL_BREAKPOINT_PX}px)`)\n    const handler = (e: MediaQueryListEvent) => setIsXl(e.matches)\n    mq.addEventListener('change', handler)\n    return () => mq.removeEventListener('change', handler)\n  }, [])\n\n  return isXl\n}\n\n// ── Width resolve(consumer 自傳 + clamp 240-640)──────────────────────────────\n\nconst ASIDE_WIDTH_MIN = 240\nconst ASIDE_WIDTH_MAX = 640\nconst ASIDE_WIDTH_DEFAULT = 320\n\nfunction resolveAsideWidth(width: AppShellAsideProps['width'], isXl: boolean): number {\n  if (typeof width === 'number') {\n    return Math.max(ASIDE_WIDTH_MIN, Math.min(ASIDE_WIDTH_MAX, width))\n  }\n  if (width && typeof width === 'object') {\n    // breakpoint-keyed:xl viewport(≥1280px)用 xl,否則 md\n    const v = (isXl ? width.xl ?? width.md : width.md) ?? ASIDE_WIDTH_DEFAULT\n    return Math.max(ASIDE_WIDTH_MIN, Math.min(ASIDE_WIDTH_MAX, v))\n  }\n  return ASIDE_WIDTH_DEFAULT\n}\n\n// ── Skip-to-main link(a11y WCAG 2.4.1)───────────────────────────────────────\n\nfunction SkipToMain() {\n  return (\n    <a\n      href=\"#app-shell-main\"\n      className={cn(\n        'sr-only focus:not-sr-only',\n        'focus:fixed focus:top-2 focus:left-2 focus:z-50',\n        'focus:px-3 focus:py-2 focus:rounded-md',\n        'focus:bg-surface focus:text-foreground focus:shadow-[var(--elevation-200)]',\n        'focus:outline-none focus:ring-2 focus:ring-primary'\n      )}\n    >\n      Skip to main content\n    </a>\n  )\n}\n\n// ── AppShell root ────────────────────────────────────────────────────────────\n\nconst AppShell = React.forwardRef<HTMLDivElement, AppShellProps>(\n  (\n    {\n      layout = 'primary-sidebar',\n      sidebar,\n      header,\n      globalHeader,\n      aside,\n      asideOpen: asideOpenProp,\n      onAsideOpenChange,\n      children,\n      className,\n      ...props\n    },\n    ref\n  ) => {\n    const [asideOpenInternal, setAsideOpenInternal] = React.useState(false)\n    const isControlled = asideOpenProp !== undefined\n    const asideOpen = isControlled ? asideOpenProp : asideOpenInternal\n\n    const setAsideOpen = React.useCallback(\n      (open: boolean) => {\n        if (!isControlled) setAsideOpenInternal(open)\n        onAsideOpenChange?.(open)\n      },\n      [isControlled, onAsideOpenChange]\n    )\n\n    const isMobile = useIsNarrowViewport()\n\n    // ── Keyboard: cmd+. toggle aside ──\n    // ⌘B sidebar toggle by Sidebar SSOT(本 component 不重覆 register)\n    React.useEffect(() => {\n      const onKey = (e: KeyboardEvent) => {\n        if (e.key === '.' && (e.metaKey || e.ctrlKey)) {\n          e.preventDefault()\n          setAsideOpen(!asideOpen)\n        }\n      }\n      window.addEventListener('keydown', onKey)\n      return () => window.removeEventListener('keydown', onKey)\n    }, [asideOpen, setAsideOpen])\n\n    const ctxValue = React.useMemo<AppShellContextValue>(\n      () => ({ layout, asideOpen, setAsideOpen, isMobile }),\n      [layout, asideOpen, setAsideOpen, isMobile]\n    )\n\n    // ── Layout grid(2 mode)──\n    // primary-sidebar:\n    //   row1: [sidebar (頂天)][main col (header + main)][aside (頂天)]\n    // primary-header:\n    //   row1: [header (橫跨整 viewport, banner role)]\n    //   row2: [sidebar][main][aside]\n\n    // AppShellAside 自決 inline vs modal mode(via AppShellContext.isMobile)。\n    // AppShell 一律只 render `{aside}` 一次,AppShellAside 內部根據 isMobile 決定 render 形式。\n\n    if (layout === 'primary-header') {\n      // primary-header layout(2026-05-21 v2 — user clarification「primary-header = primary-sidebar + 一條 global header」):\n      // 結構:row1 globalHeader(全寬 global bar)/ row2 [sidebar][main col: localHeader + main][aside]\n      // - globalHeader = 跨頁 account / workspace switcher / notifications(對齊 GitHub top nav / Slack workspace bar)\n      // - header = local page header,**仍存在**(per page actions / breadcrumb,對齊 GitHub repo header / Slack channel header / Gmail email-list toolbar 2-layer 慣例)\n      // Consumer 必傳 `<Sidebar viewportInsetTop=\"var(--chrome-header-height)\">` 讓 sidebar 從 globalHeader 下方起算。\n      return (\n        <AppShellContext.Provider value={ctxValue}>\n          <div\n            ref={ref}\n            className={cn('flex h-svh w-full flex-col overflow-hidden bg-canvas', className)}\n            {...props}\n          >\n            <SkipToMain />\n            {/* Row 1:Global header(account / workspace switcher / notifications,橫跨整 viewport)*/}\n            {globalHeader && <div className=\"flex-shrink-0\">{globalHeader}</div>}\n            {/* Row 2:[sidebar][main col][aside]horizontal row */}\n            <div className=\"flex flex-1 min-h-0 w-full\">\n              {sidebar}\n              {/* Main column:local header + main content(per user model「primary-header = primary-sidebar + global header」)*/}\n              <div className=\"flex flex-col flex-1 min-w-0 min-h-0 overflow-hidden\">\n                {header && <div className=\"flex-shrink-0\">{header}</div>}\n                <main\n                  id=\"app-shell-main\"\n                  tabIndex={-1}\n                  className=\"flex-1 min-w-0 min-h-0 overflow-y-auto focus:outline-none\"\n                >\n                  {children}\n                </main>\n              </div>\n              {aside}\n            </div>\n          </div>\n        </AppShellContext.Provider>\n      )\n    }\n\n    // primary-sidebar layout\n    return (\n      <AppShellContext.Provider value={ctxValue}>\n        <div\n          ref={ref}\n          className={cn('flex h-svh w-full overflow-hidden bg-canvas', className)}\n          {...props}\n        >\n          <SkipToMain />\n          {/* Sidebar — 頂天 */}\n          {sidebar}\n          {/* Main column(header + main 垂直堆)*/}\n          <div className=\"flex flex-col flex-1 min-w-0 min-h-0 overflow-hidden\">\n            {header && (\n              // Header 在 main column 內(main col sibling,非 main descendant)→ 跟 W3C ARIA in HTML\n              // banner rule 對照:`<header>` 在 main descendant 才不是 banner,本 ChromeHeader 是 <div>\n              // 所以本來就不會被 banner role 計算。仍包 wrap div not <header> 確保不無意觸發 banner。\n              <div className=\"flex-shrink-0\">{header}</div>\n            )}\n            <main\n              id=\"app-shell-main\"\n              tabIndex={-1}\n              className=\"flex-1 min-h-0 overflow-y-auto focus:outline-none\"\n            >\n              {children}\n            </main>\n          </div>\n          {/* Aside slot — desktop inline OR mobile Sheet,內部自決 */}\n          {aside}\n        </div>\n      </AppShellContext.Provider>\n    )\n  }\n)\nAppShell.displayName = 'AppShell'\n\n// ── AppShellAside sub-component ──────────────────────────────────────────────\n\n/**\n * AppShellAside — right panel:standard inline(desktop) vs modal overlay(mobile)。\n *\n * Desktop(viewport ≥ 768px):\n *   - Render 直接放 layout grid 右側(asideOpen=true 才 mount,close hide via parent)\n *   - 不蓋 mask / background 可操作 / 佔 layout 寬\n *   - Vertical extent:primary-sidebar → 頂天立地 / primary-header → header 下方\n *\n * Mobile(viewport < 768px):\n *   - Render 走 Sheet primitive(side=\"right\",per sheet.spec.md)\n *   - Mask 蓋 / background 不可操作 / 不佔 layout 寬\n *   - title 強制(aria-labelledby per sheet.spec.md:98)\n */\nconst AppShellAside = React.forwardRef<HTMLElement, AppShellAsideProps>(\n  ({ title, width, children, className }, ref) => {\n    const { asideOpen, setAsideOpen, isMobile } = useAppShell()\n    const isXl = useIsXl()\n    const resolvedWidth = resolveAsideWidth(width, isXl)\n\n    // Shared frame:always-on header(title + close X)+ body(ScrollArea + layoutSpace 規則 1B 父層 padding)\n    // 對齊 codex Layer B 2026-05-20「container mode 可變,panel role/content 不該變」+ Notion/Figma right\n    // panel 共識(modal vs inline 結構相同,host wrapper 不同)。\n    // 2026-05-20 migrate 消費 ChromeHeader primitive(撤回自刻 + 撤回 bg-surface 疊加 — 對齊\n    // `header-canonical.spec.md`「6. Background ownership」段「Nested chrome header 透明繼承\n    // parent」:aside container 自身已 bg-surface,內 header 不該再畫 bg 避免疊加 drift)。\n    const frame = (\n      <>\n        <ChromeHeader>\n          <h2 className=\"text-body-lg font-medium flex-1 truncate\">{title}</h2>\n          <Button\n            iconOnly\n            dismiss\n            size=\"sm\"\n            startIcon={XIcon}\n            aria-label=\"關閉\"\n            onClick={() => setAsideOpen(false)}\n          />\n        </ChromeHeader>\n        <ScrollArea className=\"flex-1 min-h-0\">\n          {children}\n        </ScrollArea>\n      </>\n    )\n\n    // Modal mode(mobile)— Sheet from right\n    if (isMobile) {\n      return (\n        <Sheet open={asideOpen} onOpenChange={setAsideOpen}>\n          <SheetContent\n            side=\"right\"\n            className=\"w-[min(90vw,var(--app-shell-aside-modal-width))] flex flex-col p-0 [&>button]:hidden\"\n            style={{ ['--app-shell-aside-modal-width' as string]: `${resolvedWidth}px` }}\n          >\n            {frame}\n          </SheetContent>\n        </Sheet>\n      )\n    }\n\n    // Standard inline mode(desktop)\n    if (!asideOpen) return null\n\n    return (\n      <aside\n        ref={ref}\n        aria-label={title}\n        className={cn(\n          'flex flex-col h-full min-h-0 overflow-hidden',\n          'bg-surface border-l border-divider',\n          className\n        )}\n        style={{ width: resolvedWidth }}\n      >\n        {frame}\n      </aside>\n    )\n  }\n)\nAppShellAside.displayName = 'AppShellAside'\n\n// ── Exports ──────────────────────────────────────────────────────────────────\n\n// code-quality-allow: dead-export useAppShell — public compound API hook(consumer 可自拼 custom aside layout,\n// 對齊 Radix `useDialogContext` / MUI `useFormControl` 慣例)。內部 AppShellAside 已消費(L294),\n// audit script 抓「無 cross-file import」是 false positive(2026-05-21 D2 codify)。\nexport { AppShell, AppShellAside, useAppShell }\n"],"names":["XIcon"],"mappings":"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"}

package/dist/components/AspectRatio/aspect-ratio.d.ts

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import * as AspectRatioPrimitive from '@radix-ui/react-aspect-ratio';
+/**
+ * AspectRatio — 固定長寬比容器(Radix AspectRatio primitive 薄包裝)
+ *
+ * 世界級對照:shadcn `AspectRatio` / Ant 無獨立元件(CSS 方案)/ Material 無
+ *
+ * ── 為什麼需要 ──
+ * CSS `aspect-ratio` 屬性雖然現代瀏覽器都支援,但 Radix primitive 提供 SSR-safe
+ * padding-bottom 方案 + consistent API,避免邊緣 bug(image 未載入時容器坍塌 /
+ * content-fit 差異)。保 safe + 一致視覺。
+ *
+ * ── 標準 ratio(DS 慣例) ──
+ * 16/9  — 寬螢幕影片、onboarding feature tour 截圖(Coachmark media 預設)
+ * 4/3   — 老電視 / 照片基本 ratio、產品 thumbnail
+ * 1/1   — Avatar / 方形貼文預覽 / icon preview
+ * 3/4   — 直式照片(人物 portrait)
+ * 21/9  — Ultra-wide banner(hero section)
+ *
+ * Consumer 傳 `ratio={n/m}` 數字計算(如 16/9 = 1.7777)。
+ *
+ * ── 常見消費者 ──
+ * Coachmark media / Carousel item image / Card thumbnail(未來)/ Chart preview
+ */
+export type AspectRatioProps = React.ComponentPropsWithoutRef<typeof AspectRatioPrimitive.Root>;
+declare const AspectRatio: React.ForwardRefExoticComponent<Omit<AspectRatioPrimitive.AspectRatioProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const aspectRatioMeta: {
+    readonly component: "AspectRatio";
+    readonly family: null;
+    readonly variants: {};
+    readonly sizes: {};
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly [];
+        readonly fg: readonly [];
+        readonly ring: readonly [];
+    };
+};
+export { AspectRatio };
+//# sourceMappingURL=aspect-ratio.d.ts.map

package/dist/components/AspectRatio/aspect-ratio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aspect-ratio.d.ts","sourceRoot":"","sources":["../../../src/components/AspectRatio/aspect-ratio.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,oBAAoB,MAAM,8BAA8B,CAAA;AAEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAAC,wBAAwB,CAAC,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAA;AAK/F,QAAA,MAAM,WAAW,iKAGoD,CAAA;AAKrE,eAAO,MAAM,eAAe;;;;;;;;;;;CAelB,CAAA;AAEV,OAAO,EAAE,WAAW,EAAE,CAAA"}

package/dist/components/AspectRatio/aspect-ratio.js

@@ -0,0 +1,23 @@
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import * as AspectRatioPrimitive from "@radix-ui/react-aspect-ratio";
+const AspectRatio = React.forwardRef((props, ref) => /* @__PURE__ */ jsx(AspectRatioPrimitive.Root, { ref, ...props }));
+AspectRatio.displayName = "AspectRatio";
+const aspectRatioMeta = {
+  component: "AspectRatio",
+  family: null,
+  // non-family composite / overlay / layout
+  variants: {},
+  sizes: {},
+  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  tokens: {
+    bg: [],
+    fg: [],
+    ring: []
+  }
+};
+export {
+  AspectRatio,
+  aspectRatioMeta
+};
+//# sourceMappingURL=aspect-ratio.js.map

package/dist/components/AspectRatio/aspect-ratio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aspect-ratio.js","sources":["../../../src/components/AspectRatio/aspect-ratio.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 AspectRatioPrimitive from '@radix-ui/react-aspect-ratio'\n\n/**\n * AspectRatio — 固定長寬比容器(Radix AspectRatio primitive 薄包裝)\n *\n * 世界級對照:shadcn `AspectRatio` / Ant 無獨立元件(CSS 方案)/ Material 無\n *\n * ── 為什麼需要 ──\n * CSS `aspect-ratio` 屬性雖然現代瀏覽器都支援,但 Radix primitive 提供 SSR-safe\n * padding-bottom 方案 + consistent API,避免邊緣 bug(image 未載入時容器坍塌 /\n * content-fit 差異)。保 safe + 一致視覺。\n *\n * ── 標準 ratio(DS 慣例) ──\n * 16/9  — 寬螢幕影片、onboarding feature tour 截圖(Coachmark media 預設)\n * 4/3   — 老電視 / 照片基本 ratio、產品 thumbnail\n * 1/1   — Avatar / 方形貼文預覽 / icon preview\n * 3/4   — 直式照片(人物 portrait)\n * 21/9  — Ultra-wide banner(hero section)\n *\n * Consumer 傳 `ratio={n/m}` 數字計算(如 16/9 = 1.7777)。\n *\n * ── 常見消費者 ──\n * Coachmark media / Carousel item image / Card thumbnail(未來)/ Chart preview\n */\n\nexport type AspectRatioProps = React.ComponentPropsWithoutRef<typeof AspectRatioPrimitive.Root>\n\n// shadcn canonical:顯式 forwardRef + displayName(雖 Radix primitive 已 forwardRef,\n// 此 wrapper 確保本 DS 每個 named export 在 Inspector 顯示正確 displayName,\n// 且 props passthrough + ref 行為在 code 層面明確可見)\nconst AspectRatio = React.forwardRef<\n  React.ElementRef<typeof AspectRatioPrimitive.Root>,\n  AspectRatioProps\n>((props, ref) => <AspectRatioPrimitive.Root ref={ref} {...props} />)\nAspectRatio.displayName = 'AspectRatio'\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 aspectRatioMeta = {\n  component: 'AspectRatio',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: [],\n    fg: [],\n    ring: [],\n  },\n} as const\n\nexport { AspectRatio }\n"],"names":[],"mappings":";;;AAgCA,MAAM,cAAc,MAAM,WAGxB,CAAC,OAAO,QAAQ,oBAAC,qBAAqB,MAArB,EAA0B,KAAW,GAAG,OAAO,CAAE;AACpE,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,CAAA;AAAA,IACJ,IAAI,CAAA;AAAA,IACJ,MAAM,CAAA;AAAA,EAAC;AAEX;"}

package/dist/components/Avatar/avatar.d.ts

@@ -0,0 +1,85 @@
+import * as React from 'react';
+import type { LucideIcon } from 'lucide-react';
+/**
+ * Avatar — 頭像元件
+ *
+ * 三種內容模式（按優先順序）：
+ *   1. src → 圖片
+ *   2. icon → icon 在底色圓/方形內
+ *   3. alt → 取首字作文字 fallback
+ *   4. 都沒有 → 預設 User icon
+ *
+ * ── 尺寸 ──
+ *   size 接受任意 px 值，icon 自動 = round_even(size × 0.6)
+ *   文字 fallback 字體 = size × 0.5
+ *
+ * ── 形狀 ──
+ *   circle（預設）→ rounded-full，用於人物
+ *   square → rounded-md (4px)，用於實體（專案、組織、App）
+ */
+type ColorKey = 'neutral' | 'blue' | 'red' | 'green' | 'yellow' | 'turquoise' | 'purple' | 'magenta' | 'indigo';
+export interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** 尺寸：number (px) 或 'fill'（填滿父容器，由父層決定大小）。預設 32 */
+    size?: number | 'fill';
+    /** 形狀：circle（人物）或 square（實體），預設 circle */
+    shape?: 'circle' | 'square';
+    /** 圖片 URL */
+    src?: string;
+    /** 替代文字（圖片失敗時取首字作 fallback） */
+    alt?: string;
+    /** Icon 模式（LucideIcon） */
+    icon?: LucideIcon;
+    /** Icon / text fallback 的背景色，預設 neutral */
+    color?: ColorKey;
+    /** 深底白字模式（step-6 背景 + 白色前景，warning 例外），預設 false */
+    solid?: boolean;
+    /**
+     * 在線狀態指示器(presence),顯示在 avatar **右下角**。
+     * 世界級對照:Slack / Teams / Discord — `online` 是最廣泛被理解的術語。
+     * 位置語義:右下 = "此人的 presence"(使用者聚焦於「這個人是誰 + 現在 在不在」)。
+     */
+    status?: 'online' | 'away' | 'busy' | 'offline';
+    /**
+     * 未讀 / 通知計數 badge,顯示在 avatar **右上角**。
+     * 世界級對照:chat app(iMessage / Slack thread / LINE / WhatsApp)一律右上角。
+     * 位置語義:右上 = "關於此對話的新事件數量"(使用者聚焦於「有多少未處理」);
+     * 與右下的 presence 共存不衝突(不同角、不同語義)。
+     * `> 99` 自動顯示 "99+"(交給內部 Badge 的 `max` 行為)。
+     */
+    badgeCount?: number;
+    /**
+     * 傳入 HoverCard 內容（如 NameCard），hover avatar 時自動顯示。
+     * 只有人員 avatar 需要傳；實體 avatar（專案、組織）不傳。
+     */
+    hoverCard?: React.ReactNode;
+}
+export interface AvatarData {
+    /** 圖片 URL */
+    src?: string;
+    /** 替代文字（圖片失敗時取首字作 fallback） */
+    alt: string;
+    /** Icon / text fallback 的背景色，預設 neutral */
+    color?: ColorKey;
+    /**
+     * Person avatar hover NameCard(DS-wide canonical,person avatar 預設必有,見 avatar.spec.md)。
+     * Entity avatar(專案 / 組織 logo)不帶 → consumer 不傳 hoverCard 即豁免。
+     * 所有消費 AvatarData 的 primitive(MenuItem / DropdownMenu / SelectMenu / SelectionItem / NameCard)
+     * 需 forward 此 prop 到內部 <Avatar hoverCard={avatar.hoverCard} />。
+     */
+    hoverCard?: React.ReactNode;
+}
+export declare const avatarMeta: {
+    readonly component: "Avatar";
+    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 ["--foreground", "--on-emphasis"];
+        readonly ring: readonly ["ring-ring"];
+    };
+};
+declare const Avatar: React.MemoExoticComponent<React.ForwardRefExoticComponent<AvatarProps & React.RefAttributes<HTMLDivElement>>>;
+export { Avatar };
+//# sourceMappingURL=avatar.d.ts.map

package/dist/components/Avatar/avatar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatar.d.ts","sourceRoot":"","sources":["../../../src/components/Avatar/avatar.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAO9C;;;;;;;;;;;;;;;;GAgBG;AAMH,KAAK,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAA;AA2E/G,MAAM,WAAW,WAAY,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IACvE,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC3B,aAAa;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,+BAA+B;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,0BAA0B;IAC1B,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,mDAAmD;IACnD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IAC/C;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC5B;AA4LD,MAAM,WAAW,UAAU;IACzB,aAAa;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,2CAA2C;IAC3C,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC5B;AAID,eAAO,MAAM,UAAU;;;;;;;;;;;CAeb,CAAA;AAGV,QAAA,MAAM,MAAM,+GAA0B,CAAA;AAEtC,OAAO,EAAE,MAAM,EAAE,CAAA"}

package/dist/components/Avatar/avatar.js

@@ -0,0 +1,195 @@
+import { jsxs, jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { User } from "lucide-react";
+import { cn } from "../../lib/utils.js";
+import { HoverCard, HoverCardTrigger, HoverCardContent } from "../HoverCard/hover-card.js";
+import { HOVER_DELAY_CLOSE_MS, HOVER_DELAY_RICH_MS } from "../../tokens/motion/motion.js";
+import { Badge } from "../Badge/badge.js";
+import { useTableIsScrolling, useFieldContext } from "../Field/field-context.js";
+const COLOR_MAP = {
+  subtle: {
+    neutral: { bg: "var(--muted)", text: "var(--foreground)" },
+    blue: { bg: "var(--color-blue-1)", text: "var(--color-blue-7)" },
+    red: { bg: "var(--color-deep-orange-1)", text: "var(--color-deep-orange-7)" },
+    green: { bg: "var(--color-green-1)", text: "var(--color-green-7)" },
+    yellow: { bg: "var(--color-yellow-1)", text: "var(--color-yellow-7)" },
+    turquoise: { bg: "var(--color-turquoise-1)", text: "var(--color-turquoise-7)" },
+    purple: { bg: "var(--color-purple-1)", text: "var(--color-purple-7)" },
+    magenta: { bg: "var(--color-magenta-1)", text: "var(--color-magenta-7)" },
+    indigo: { bg: "var(--color-indigo-1)", text: "var(--color-indigo-7)" }
+  },
+  solid: {
+    neutral: { bg: "var(--color-neutral-9)", text: "var(--inverse-fg)" },
+    blue: { bg: "var(--color-blue-6)", text: "var(--on-emphasis)" },
+    red: { bg: "var(--color-deep-orange-6)", text: "var(--on-emphasis)" },
+    green: { bg: "var(--color-green-6)", text: "var(--on-emphasis)" },
+    yellow: { bg: "var(--color-yellow-6)", text: "var(--warning-foreground)" },
+    turquoise: { bg: "var(--color-turquoise-6)", text: "var(--on-emphasis)" },
+    purple: { bg: "var(--color-purple-6)", text: "var(--on-emphasis)" },
+    magenta: { bg: "var(--color-magenta-6)", text: "var(--on-emphasis)" },
+    indigo: { bg: "var(--color-indigo-6)", text: "var(--on-emphasis)" }
+  }
+};
+function getIconSize(avatarSize) {
+  return Math.round(avatarSize * 0.6 / 2) * 2;
+}
+function getInitial(text) {
+  return text.trim().charAt(0).toUpperCase();
+}
+const STATUS_DOT_COLOR = {
+  online: "var(--status-online)",
+  away: "var(--status-away)",
+  busy: "var(--status-busy)",
+  offline: "var(--status-offline)"
+};
+function useDocumentTheme() {
+  const [theme, setTheme] = React.useState(
+    () => typeof document !== "undefined" ? document.documentElement.getAttribute("data-theme") : null
+  );
+  React.useEffect(() => {
+    if (typeof document === "undefined") return;
+    const root = document.documentElement;
+    const update = () => setTheme(root.getAttribute("data-theme"));
+    update();
+    const obs = new MutationObserver(update);
+    obs.observe(root, { attributes: true, attributeFilter: ["data-theme"] });
+    return () => obs.disconnect();
+  }, []);
+  return theme;
+}
+const AvatarInner = React.forwardRef(
+  ({ size = 32, shape = "circle", src, alt, icon: Icon, color = "neutral", solid = false, status, badgeCount, hoverCard, className, style, ...props }, ref) => {
+    var _a;
+    const [imgError, setImgError] = React.useState(false);
+    const documentTheme = useDocumentTheme();
+    const isTableScrolling = useTableIsScrolling();
+    const fieldCtx = useFieldContext();
+    const isDisabledInField = (fieldCtx == null ? void 0 : fieldCtx.mode) === "disabled" && (fieldCtx == null ? void 0 : fieldCtx.hasFieldWrapper) === true;
+    const isFill = size === "fill";
+    const numSize = isFill ? 32 : size;
+    const iconPx = getIconSize(numSize);
+    const fontSizePx = Math.round(numSize * 0.5);
+    const variantKey = solid ? "solid" : "subtle";
+    const colors = ((_a = COLOR_MAP[variantKey]) == null ? void 0 : _a[color]) ?? COLOR_MAP.subtle.neutral;
+    const radius = shape === "circle" ? "9999px" : "4px";
+    const showImage = src && !imgError;
+    const showIcon = !showImage && (Icon || !alt);
+    const showText = !showImage && !showIcon && alt;
+    const FallbackIcon = Icon ?? User;
+    const dotSize = isFill ? 10 : Math.max(8, Math.min(16, Math.round(numSize * 0.28)));
+    const dotBorder = dotSize >= 12 ? 3 : 2;
+    const avatarEl = /* @__PURE__ */ jsxs(
+      "div",
+      {
+        className: cn(
+          "inline-flex items-center justify-center shrink-0 overflow-hidden select-none",
+          isFill && "w-full h-full",
+          // 2026-05-13 R3.5 self-dim:Avatar 在 disabled Field wrapper context 內自 dim
+          // (取代 field-wrapper.tsx default/bare/naked disabled blanket opacity-disabled 逃生艙)
+          isDisabledInField && "opacity-disabled"
+        ),
+        style: {
+          ...isFill ? { containerType: "inline-size" } : { width: numSize, height: numSize },
+          borderRadius: radius,
+          backgroundColor: showImage ? void 0 : colors.bg,
+          color: showImage ? void 0 : colors.text
+        },
+        "data-avatar-size": isFill ? "fill" : numSize,
+        children: [
+          showImage && /* @__PURE__ */ jsx(
+            "img",
+            {
+              src,
+              alt: alt ?? "",
+              className: "w-full h-full object-cover",
+              onError: () => setImgError(true)
+            }
+          ),
+          showIcon && (isFill ? /* @__PURE__ */ jsx(FallbackIcon, { className: "w-[60%] h-[60%]", "aria-hidden": true }) : /* @__PURE__ */ jsx(FallbackIcon, { size: iconPx, "aria-hidden": true })),
+          showText && /* @__PURE__ */ jsx(
+            "span",
+            {
+              className: "font-medium leading-none",
+              style: { fontSize: isFill ? "50cqi" : fontSizePx },
+              "aria-hidden": true,
+              children: getInitial(alt)
+            }
+          )
+        ]
+      }
+    );
+    const hasOverlay = status || typeof badgeCount === "number";
+    const focusableProps = hoverCard ? {
+      tabIndex: 0,
+      role: "button",
+      "aria-haspopup": "dialog",
+      "aria-label": alt ?? "View profile"
+    } : {};
+    const focusableClass = hoverCard ? "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 rounded-full" : "";
+    const baseEl = !hasOverlay ? /* @__PURE__ */ jsx("div", { ref, className: cn("inline-flex shrink-0", focusableClass, className), style, ...focusableProps, ...props, children: avatarEl }) : /* @__PURE__ */ jsxs("div", { ref, className: cn("relative inline-flex shrink-0", focusableClass, className), style, ...focusableProps, ...props, children: [
+      avatarEl,
+      status && /* @__PURE__ */ jsx(
+        "span",
+        {
+          className: "absolute block rounded-full",
+          style: {
+            width: dotSize,
+            height: dotSize,
+            bottom: 0,
+            right: 0,
+            backgroundColor: STATUS_DOT_COLOR[status],
+            boxShadow: `0 0 0 ${dotBorder}px var(--surface-raised, var(--canvas))`
+          },
+          "aria-hidden": true
+        }
+      ),
+      typeof badgeCount === "number" && badgeCount > 0 && /* @__PURE__ */ jsx(
+        Badge,
+        {
+          variant: "critical",
+          count: badgeCount,
+          max: 99,
+          className: "absolute -top-1 -right-1",
+          style: {
+            boxShadow: `0 0 0 2px var(--surface-raised, var(--canvas))`
+          },
+          "aria-label": `${badgeCount} unread`
+        }
+      )
+    ] });
+    if (!hoverCard || isTableScrolling) return baseEl;
+    return /* @__PURE__ */ jsxs(HoverCard, { openDelay: HOVER_DELAY_RICH_MS, closeDelay: HOVER_DELAY_CLOSE_MS, children: [
+      /* @__PURE__ */ jsx(HoverCardTrigger, { asChild: true, children: baseEl }),
+      /* @__PURE__ */ jsx(
+        HoverCardContent,
+        {
+          "data-theme": documentTheme ?? void 0,
+          className: "bg-surface-raised rounded-lg border border-border overflow-hidden",
+          style: { boxShadow: "var(--elevation-200)" },
+          children: hoverCard
+        }
+      )
+    ] });
+  }
+);
+AvatarInner.displayName = "AvatarInner";
+const avatarMeta = {
+  component: "Avatar",
+  family: null,
+  // non-family composite / overlay / layout
+  variants: {},
+  sizes: {},
+  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  tokens: {
+    bg: ["bg-surface-raised"],
+    fg: ["--foreground", "--on-emphasis"],
+    ring: ["ring-ring"]
+  }
+};
+AvatarInner.displayName = "Avatar";
+const Avatar = React.memo(AvatarInner);
+export {
+  Avatar,
+  avatarMeta
+};
+//# sourceMappingURL=avatar.js.map