@zerodep-dev/vue-tsx-pro-ui 0.0.0-stage → 0.1.0

package/dist/display/Accordion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Accordion.js","names":["_isVNode","_vtp_readonlyProp","_vtp_bindable","_vtp_childrenProp","_vtp_restProps","_vue_shallowRef","_vue_computed","_createVNode","_mergeProps","_vtp_forwardChildren"],"sources":["../../src/display/Accordion.tsx"],"sourcesContent":["/**\n * 手风琴，复合组件：Accordion（div）> AccordionItem（标题按钮 + 展开收起的内容）。WAI-ARIA 的 Accordion 模式：\n * 每个标题是 heading 里的 button（aria-expanded、aria-controls），内容是 role=\"region\"、以标题为名称；\n * 标题都在 Tab 顺序里，另外 ↑ / ↓ 在标题之间移动（到头后循环），Home / End 到第一个、最后一个。参考 Radix Accordion。\n *\n *   <Accordion _value={open} aria-label=\"常见问题\">\n *     <AccordionItem value=\"ship\" title=\"多久发货？\">付款后 48 小时内。</AccordionItem>\n *     <AccordionItem value=\"refund\" title=\"怎么退款？\">…</AccordionItem>\n *   </Accordion>\n *   <Accordion selectionMode=\"multiple\" _value={openList}>…</Accordion>\n *\n * 展开收起的动画同 Collapsible（Collapse 的 CSS 过渡）。部件见 AccordionItemProps。\n */\nimport { ChevronDown } from '@lucide/icons';\nimport { createContext, _component } from '@zerodep-dev/vue-tsx-pro-tsx';\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport { h, useId, type VNodeChild } from 'vue';\nimport { ButtonBase, type ButtonBaseProps } from '../base/ButtonBase';\nimport { Icon, type IconProps } from '../base/Icon';\nimport { selectedValues, toggleSelection, type SelectionProps } from '../utils/data/selection';\nimport { mergeAttrs, mergePartProps, type PartProps } from '../utils/props';\nimport { disclosureStyles } from '../utils/style/transitions';\nimport { fontSizeStyles, type TextSize } from '../utils/style/typography';\nimport { Collapse, type CollapseProps } from './Collapse';\n\n/** Accordion 交给 AccordionItem 的状态 */\nexport interface AccordionState {\n  /** 展开着的项 */\n  readonly expanded: readonly string[];\n  /** 标题的层级（h2–h6） */\n  readonly headingLevel: 2 | 3 | 4 | 5 | 6;\n  /** 整组不可用 */\n  readonly disabled: boolean;\n  /** 展开或收起一项（单开 / 多开的规则由组决定） */\n  toggle(value: string): void;\n}\n\n/** Accordion 的上下文：自定义的项可以 inject 它接入组 */\nexport const AccordionContext = createContext<AccordionState>('Accordion');\n\n/** 两种方式共有的属性；未声明的属性落到外层 div 上 */\ninterface AccordionBaseProps extends PartProps<'div'> {\n  /** 单开时允许把唯一展开的那项也收起，默认 true */\n  collapsible?: boolean;\n  /** 标题的层级，按所在页面的大纲选，默认 3 */\n  headingLevel?: 2 | 3 | 4 | 5 | 6;\n  /** 整组不可用 */\n  disabled?: boolean;\n  /** 字号档位；不写时继承 */\n  size?: TextSize;\n  /** AccordionItem */\n  children?: VNodeChild;\n}\n\n/** 单开（selectionMode=\"single\"，value 是展开项的值）或多开（value 是数组） */\nexport type AccordionProps = AccordionBaseProps & SelectionProps;\n\n/** Accordion 的样式：root、item、heading、trigger、chevron、chevronOpen、content */\nexport const accordionStyles = css.create({\n  root: { display: 'flex', flexDirection: 'column' },\n  item: {\n    borderBottomWidth: '_xs',\n    borderBottomStyle: 'solid',\n    borderBottomColor: '_borderMuted',\n  },\n  heading: { margin: 0, fontSize: 'inherit', fontWeight: 'inherit' },\n  // 去掉按钮默认外观、焦点环、波纹、颜色过渡由 ButtonBase 给出\n  trigger: {\n    display: 'flex',\n    alignItems: 'center',\n    justifyContent: 'space-between',\n    gap: '_md',\n    width: '_full',\n    minHeight: '_minTarget',\n    paddingBlock: '_md',\n    paddingInline: '_sm',\n    borderRadius: '_sm',\n    backgroundColor: { default: 'transparent', ':hover': '_fill' },\n    color: '_text',\n    fontWeight: '_semibold',\n    textAlign: 'start',\n  },\n  triggerDisabled: { opacity: '_disabled' },\n  chevron: { flexShrink: 0, color: '_textMuted' },\n  chevronOpen: { rotate: '180deg' },\n  content: { paddingInline: '_sm', paddingBlockEnd: '_md', color: '_text' },\n});\n\n/** 手风琴：一组可展开收起的项，单开或多开 */\nexport const Accordion = _component(\n  ({\n    selectionMode = 'single',\n    _value: value = _bindable<string | string[] | null>(null),\n    collapsible = true,\n    headingLevel = 3,\n    disabled = false,\n    size,\n    children,\n    ...rest\n  }: AccordionProps) => {\n    let root = _state.raw<HTMLElement | null>(null);\n    const expanded = _derived(selectedValues(value));\n\n    AccordionContext.provide({\n      get expanded() {\n        return expanded;\n      },\n      get headingLevel() {\n        return headingLevel;\n      },\n      get disabled() {\n        return disabled;\n      },\n      toggle(item) {\n        const next = toggleSelection(expanded, item, {\n          mode: selectionMode,\n          required: !collapsible,\n        });\n        if (next === expanded) return;\n        value = selectionMode === 'multiple' ? [...next] : (next[0] ?? null);\n      },\n    });\n\n    // ↑ / ↓ 在标题之间移动（循环），Home / End 到两端；只在焦点在标题按钮上时处理\n    function onKeydown(event: KeyboardEvent) {\n      const target = event.target as HTMLElement;\n      if (!root || !target.matches('[data-accordion-trigger]')) return;\n      const triggers = [\n        ...root.querySelectorAll<HTMLButtonElement>('[data-accordion-trigger]:not(:disabled)'),\n      ].filter((trigger) => trigger.closest('[data-accordion]') === root);\n      const index = triggers.indexOf(target as HTMLButtonElement);\n      const next = {\n        ArrowDown: triggers[(index + 1) % triggers.length],\n        ArrowUp: triggers[(index - 1 + triggers.length) % triggers.length],\n        Home: triggers[0],\n        End: triggers.at(-1),\n      }[event.key];\n      if (!next) return;\n      event.preventDefault();\n      next.focus();\n    }\n\n    return () => (\n      <div\n        {...mergeAttrs<'div'>({ sx: [accordionStyles.root, size && fontSizeStyles[size]] }, rest, {\n          ref: _toRef(root),\n          onKeydown,\n        })}\n        data-accordion=\"\"\n        data-disabled={disabled || undefined}\n      >\n        {children}\n      </div>\n    );\n  },\n);\n\n/** 未声明的属性落到每一项的外层 div 上 */\nexport interface AccordionItemProps extends PartProps<'div', 'title'> {\n  /** 这一项的值 */\n  value: string;\n  /** 标题 */\n  title: VNodeChild;\n  /** 不可用：标题按钮 disabled，不能展开收起 */\n  disabled?: boolean;\n  /** 标题（h2–h6）的部件属性 */\n  propsHeading?: PartProps<'h3'>;\n  /** 标题按钮的部件属性 */\n  propsTrigger?: Omit<Partial<ButtonBaseProps>, 'aria-expanded' | 'aria-controls'>;\n  /** 展开箭头的部件属性 */\n  propsChevron?: Partial<IconProps>;\n  /** 内容区（Collapse，role=\"region\"）的部件属性 */\n  propsContent?: Partial<CollapseProps>;\n  /** 内容 */\n  children?: VNodeChild;\n}\n\n/** 手风琴里的一项：标题按钮 + 展开收起的内容 */\nexport const AccordionItem = _component(\n  ({\n    value,\n    title,\n    disabled = false,\n    propsHeading,\n    propsTrigger,\n    propsChevron,\n    propsContent,\n    children,\n    ...rest\n  }: AccordionItemProps) => {\n    const accordion = AccordionContext.inject();\n    const id = useId();\n    const triggerId = `${id}-trigger`;\n    const contentId = `${id}-content`;\n    // Collapse 在页内搜索命中（beforematch）时会写回 open：经这个对象交给组切换\n    const model = {\n      get open() {\n        return accordion.expanded.includes(value);\n      },\n      set open(next: boolean) {\n        if (next !== model.open) accordion.toggle(value);\n      },\n    };\n\n    return () => {\n      const open = model.open;\n      const off = disabled || accordion.disabled;\n      const state = open ? 'open' : 'closed';\n      const trigger = (\n        <ButtonBase\n          {...mergePartProps<ButtonBaseProps>(\n            { sx: [accordionStyles.trigger, off && accordionStyles.triggerDisabled] },\n            propsTrigger,\n            {\n              id: triggerId,\n              disabled: off,\n              'aria-expanded': open,\n              'aria-controls': contentId,\n              onClick: () => accordion.toggle(value),\n            },\n          )}\n          data-accordion-trigger=\"\"\n          data-state={state}\n        >\n          <span>{title}</span>\n          <Icon\n            {...mergePartProps<IconProps>(\n              {\n                icon: ChevronDown,\n                sx: [\n                  accordionStyles.chevron,\n                  disclosureStyles.icon,\n                  open && accordionStyles.chevronOpen,\n                ],\n              },\n              propsChevron,\n            )}\n          />\n        </ButtonBase>\n      );\n      return (\n        <div\n          {...mergeAttrs<'div'>({ sx: accordionStyles.item }, rest)}\n          data-state={state}\n          data-disabled={off || undefined}\n        >\n          {/* 标签名随 headingLevel，用 h() 渲染 */}\n          {h(\n            `h${accordion.headingLevel}`,\n            mergeAttrs<'h3'>({ sx: accordionStyles.heading }, propsHeading),\n            [trigger],\n          )}\n          <Collapse\n            {...mergePartProps<CollapseProps>(\n              { propsContent: { sx: accordionStyles.content } },\n              propsContent,\n              { id: contentId, role: 'region', 'aria-labelledby': triggerId },\n            )}\n            _open={model.open}\n          >\n            {children}\n          </Collapse>\n        </div>\n      );\n    };\n  },\n);\n"],"mappings":"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"}

package/dist/display/AnimatedNumber.d.ts

@@ -0,0 +1,44 @@
+import * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';
+import type { VNodeChild } from 'vue';
+import { type VisuallyHiddenProps } from '../base/VisuallyHidden';
+import { type NumericFormat } from '../config/lang/format';
+import { type NumericValue } from '../utils/data/numeric';
+import { type TweenOptions } from '../utils/motion/tween';
+import { type PartProps } from '../utils/props';
+import { type Tone } from '../utils/style/typography';
+/** 未声明的属性落到外层 span 上；原生的 prefix 属性（RDFa）让给前缀内容 */
+export interface AnimatedNumberProps extends PartProps<'span', 'prefix'> {
+    /** 数值：number、bigint 或 Decimal */
+    value: NumericValue;
+    /**
+     * 格式：金额 `{ style: 'currency' }`（币种默认取语言包）、百分比 `{ style: 'percent' }`、
+     * 以万为单位 `{ scale: 10_000, maximumFractionDigits: 2 }`
+     */
+    format?: NumericFormat;
+    /** 过渡的时长档位，默认 lg */
+    duration?: TweenOptions['duration'];
+    /** 挂载时从这个值滚到 value；不给时直接显示 value */
+    from?: NumericValue;
+    /** 按正负着色：正数成功色、负数危险色（涨跌）；data-trend 写 up / down / flat */
+    trend?: boolean;
+    /** 文字色调；给了 trend 时由正负决定 */
+    tone?: Tone;
+    /** 数字前的内容（如“¥”以外的说明文字、图标） */
+    prefix?: VNodeChild;
+    /** 数字后的内容（如单位“人”） */
+    suffix?: VNodeChild;
+    /** 前缀的部件属性 */
+    propsPrefix?: PartProps<'span'>;
+    /** 后缀的部件属性 */
+    propsSuffix?: PartProps<'span'>;
+    /** 滚动中的数字（对读屏隐藏）的部件属性 */
+    propsValue?: PartProps<'span', 'aria-hidden'>;
+    /** 给读屏的终值文字的部件属性 */
+    propsLabel?: Partial<VisuallyHiddenProps>;
+}
+/** AnimatedNumber 的样式：root */
+export declare const animatedNumberStyles: Readonly<{
+    root: css.CompiledStyles;
+}>;
+/** 会滚动的数字：值变化时过渡，读屏只读终值 */
+export declare const AnimatedNumber: import("@zerodep-dev/vue-tsx-pro-tsx").TsxComponent<AnimatedNumberProps>;

package/dist/display/AnimatedNumber.js

@@ -0,0 +1,97 @@
+import { compareNumeric, numericText, toNumber } from "../utils/data/numeric.js";
+import { hasContent, mergeAttrs, mergePartProps } from "../utils/props.js";
+import { toneStyles } from "../utils/style/typography.js";
+import { VisuallyHidden } from "../base/VisuallyHidden.js";
+import { useFormat } from "../config/lang/format.js";
+import { useTween } from "../utils/motion/tween.js";
+import { createVNode, mergeProps, shallowRef } from "vue";
+import { _component, effect, readonlyProp, restProps, untrack } from "@zerodep-dev/vue-tsx-pro-tsx";
+import * as css from "@zerodep-dev/vue-tsx-pro-tsx/styles";
+//#region src/display/AnimatedNumber.tsx
+/** 未声明的属性落到外层 span 上；原生的 prefix 属性（RDFa）让给前缀内容 */
+/** AnimatedNumber 的样式：root */
+var animatedNumberStyles = css.create({ root: {
+	fontVariantNumeric: "tabular-nums",
+	whiteSpace: "nowrap"
+} });
+/** 终值的小数位数：滚动中的值按它取整，整数不会滚出一串小数 */
+function decimals(value) {
+	return Math.min(20, numericText(value).split(".")[1]?.length ?? 0);
+}
+/** 会滚动的数字：值变化时过渡，读屏只读终值 */
+var AnimatedNumber = /*#__PURE__*/ _component((_props, _ctx) => {
+	const value = readonlyProp(_props, "value");
+	const format = readonlyProp(_props, "format");
+	const duration = readonlyProp(_props, "duration", "lg");
+	const from = readonlyProp(_props, "from");
+	const trend = readonlyProp(_props, "trend", false);
+	const tone = readonlyProp(_props, "tone");
+	const prefix = readonlyProp(_props, "prefix");
+	const suffix = readonlyProp(_props, "suffix");
+	const propsPrefix = readonlyProp(_props, "propsPrefix");
+	const propsSuffix = readonlyProp(_props, "propsSuffix");
+	const propsValue = readonlyProp(_props, "propsValue");
+	const propsLabel = readonlyProp(_props, "propsLabel");
+	const rest = restProps(_props, _ctx, true);
+	const formatter = useFormat();
+	let root = null;
+	const start = untrack(() => from.value);
+	const tween = useTween(() => toNumber(value.value), {
+		duration: untrack(() => duration.value),
+		from: start == null ? void 0 : toNumber(start),
+		scope: () => root
+	});
+	const text = (number) => formatter.number(number, format.value);
+	/** 过渡中当前显示的文字 */
+	const shownText = () => {
+		if (tween.current === toNumber(value.value)) return text(value.value);
+		const places = 10 ** decimals(value.value);
+		return text(Math.round(tween.current * places) / places);
+	};
+	let valueElement = shallowRef(null);
+	effect(() => {
+		const shown = shownText();
+		if (valueElement.value) valueElement.value.textContent = shown;
+	});
+	return () => {
+		const sign = compareNumeric(value.value, 0);
+		const direction = sign > 0 ? "up" : sign < 0 ? "down" : "flat";
+		const color = trend.value ? {
+			up: "success",
+			down: "danger",
+			flat: tone.value
+		}[direction] : tone.value;
+		return createVNode("span", mergeProps(mergeAttrs({ sx: [animatedNumberStyles.root, color && toneStyles[color]] }, rest, { ref: (element) => root = element }), { "data-trend": trend.value ? direction : void 0 }), [
+			hasContent(prefix.value) && createVNode("span", mergeAttrs({}, propsPrefix.value), [prefix.value]),
+			createVNode("span", mergeAttrs({}, propsValue.value, {
+				"aria-hidden": true,
+				ref: valueElement
+			}), [untrack(() => shownText())]),
+			createVNode(VisuallyHidden, mergeProps(mergePartProps({}, propsLabel.value), { "key": "__site0" }), {
+				default: () => [text(value.value)],
+				$stable: true
+			}),
+			hasContent(suffix.value) && createVNode("span", mergeAttrs({}, propsSuffix.value), [suffix.value])
+		]);
+	};
+}, {
+	name: "AnimatedNumber",
+	props: [
+		"value",
+		"format",
+		"duration",
+		"from",
+		"trend",
+		"tone",
+		"prefix",
+		"suffix",
+		"propsPrefix",
+		"propsSuffix",
+		"propsValue",
+		"propsLabel"
+	]
+});
+//#endregion
+export { AnimatedNumber, animatedNumberStyles };
+
+//# sourceMappingURL=AnimatedNumber.js.map

package/dist/display/AnimatedNumber.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnimatedNumber.js","names":["_vtp_readonlyProp","_vtp_restProps","_vtp_untrack","_vue_shallowRef","_createVNode","_mergeProps"],"sources":["../../src/display/AnimatedNumber.tsx"],"sourcesContent":["/**\n * 会滚动的数字（span）：值变化时从旧值过渡到新值（useTween），按当前语言格式化，等宽数字不抖动。\n * 统计卡片的数值、金额、百分比、计数器。\n *\n *   <AnimatedNumber value={revenue} format={{ style: 'currency' }} />\n *   <AnimatedNumber value={0.123} format={{ style: 'percent', maximumFractionDigits: 1 }} trend prefix=\"较上周 \" />\n *\n * 读屏只读终值：滚动中的数字对读屏隐藏，旁边有一份隐藏的终值文字。需要播报变化时在外层加 aria-live。\n * 值可以是 number、bigint 或 Decimal：过渡的中间帧按浮点数算，停下时与读屏的终值按原值格式化，不丢精度。\n */\nimport { _component } from '@zerodep-dev/vue-tsx-pro-tsx';\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport type { VNodeChild } from 'vue';\nimport { VisuallyHidden, type VisuallyHiddenProps } from '../base/VisuallyHidden';\nimport { useFormat, type NumericFormat } from '../config/lang/format';\nimport { compareNumeric, numericText, toNumber, type NumericValue } from '../utils/data/numeric';\nimport { useTween, type TweenOptions } from '../utils/motion/tween';\nimport { hasContent, mergeAttrs, mergePartProps, type PartProps } from '../utils/props';\nimport { toneStyles, type Tone } from '../utils/style/typography';\n\n/** 未声明的属性落到外层 span 上；原生的 prefix 属性（RDFa）让给前缀内容 */\nexport interface AnimatedNumberProps extends PartProps<'span', 'prefix'> {\n  /** 数值：number、bigint 或 Decimal */\n  value: NumericValue;\n  /**\n   * 格式：金额 `{ style: 'currency' }`（币种默认取语言包）、百分比 `{ style: 'percent' }`、\n   * 以万为单位 `{ scale: 10_000, maximumFractionDigits: 2 }`\n   */\n  format?: NumericFormat;\n  /** 过渡的时长档位，默认 lg */\n  duration?: TweenOptions['duration'];\n  /** 挂载时从这个值滚到 value；不给时直接显示 value */\n  from?: NumericValue;\n  /** 按正负着色：正数成功色、负数危险色（涨跌）；data-trend 写 up / down / flat */\n  trend?: boolean;\n  /** 文字色调；给了 trend 时由正负决定 */\n  tone?: Tone;\n  /** 数字前的内容（如“¥”以外的说明文字、图标） */\n  prefix?: VNodeChild;\n  /** 数字后的内容（如单位“人”） */\n  suffix?: VNodeChild;\n  /** 前缀的部件属性 */\n  propsPrefix?: PartProps<'span'>;\n  /** 后缀的部件属性 */\n  propsSuffix?: PartProps<'span'>;\n  /** 滚动中的数字（对读屏隐藏）的部件属性 */\n  propsValue?: PartProps<'span', 'aria-hidden'>;\n  /** 给读屏的终值文字的部件属性 */\n  propsLabel?: Partial<VisuallyHiddenProps>;\n}\n\n/** AnimatedNumber 的样式：root */\nexport const animatedNumberStyles = css.create({\n  // 等宽数字：滚动时宽度不跳\n  root: { fontVariantNumeric: 'tabular-nums', whiteSpace: 'nowrap' },\n});\n\n/** 终值的小数位数：滚动中的值按它取整，整数不会滚出一串小数 */\nfunction decimals(value: NumericValue) {\n  return Math.min(20, numericText(value).split('.')[1]?.length ?? 0);\n}\n\n/** 会滚动的数字：值变化时过渡，读屏只读终值 */\nexport const AnimatedNumber = _component(\n  ({\n    value,\n    format,\n    duration = 'lg',\n    from,\n    trend = false,\n    tone,\n    prefix,\n    suffix,\n    propsPrefix,\n    propsSuffix,\n    propsValue,\n    propsLabel,\n    ...rest\n  }: AnimatedNumberProps) => {\n    const formatter = useFormat();\n    let root: HTMLElement | null = null;\n    // 时长按自己所在的主题范围读（子树里可能覆盖了主题）\n    const start = _untrack(from);\n    const tween = useTween(() => toNumber(value), {\n      duration: _untrack(duration),\n      from: start == null ? undefined : toNumber(start),\n      scope: () => root,\n    });\n\n    const text = (number: NumericValue) => formatter.number(number, format);\n\n    /** 过渡中当前显示的文字 */\n    const shownText = () => {\n      // 停在终值时按原值格式化：bigint、Decimal 不经过浮点数\n      if (tween.current === toNumber(value)) return text(value);\n      const places = 10 ** decimals(value);\n      return text(Math.round(tween.current * places) / places);\n    };\n    // 过渡中每帧直接改文字，不为一个数字重新渲染整个组件；渲染里只取当前值、不追踪\n    let valueElement = _state.raw<HTMLElement | null>(null);\n    _effect(() => {\n      const shown = shownText();\n      if (valueElement) valueElement.textContent = shown;\n    });\n\n    return () => {\n      const sign = compareNumeric(value, 0);\n      const direction = sign > 0 ? 'up' : sign < 0 ? 'down' : 'flat';\n      const color = trend\n        ? ({ up: 'success', down: 'danger', flat: tone } as const)[direction]\n        : tone;\n      return (\n        <span\n          {...mergeAttrs<'span'>(\n            { sx: [animatedNumberStyles.root, color && toneStyles[color]] },\n            rest,\n            { ref: (element: unknown) => (root = element as HTMLElement | null) },\n          )}\n          data-trend={trend ? direction : undefined}\n        >\n          {hasContent(prefix) && <span {...mergeAttrs<'span'>({}, propsPrefix)}>{prefix}</span>}\n          <span\n            {...mergeAttrs<'span'>({}, propsValue, {\n              'aria-hidden': true,\n              ref: _toRef(valueElement),\n            })}\n          >\n            {_untrack(shownText())}\n          </span>\n          <VisuallyHidden {...mergePartProps<VisuallyHiddenProps>({}, propsLabel)}>\n            {text(value)}\n          </VisuallyHidden>\n          {hasContent(suffix) && <span {...mergeAttrs<'span'>({}, propsSuffix)}>{suffix}</span>}\n        </span>\n      );\n    };\n  },\n);\n"],"mappings":"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"}

package/dist/display/Avatar.d.ts

@@ -0,0 +1,74 @@
+import * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';
+import { type VNodeChild } from 'vue';
+import { type PartProps } from '../utils/props';
+import { type StatusTone } from '../utils/style/tone-styles';
+import { type TextSize } from '../utils/style/typography';
+import { type Radius } from '../utils/style/styles';
+/** 后备内容（首字母、图标）的底色样式 */
+export interface AvatarVariants {
+    /** 浅色底（默认） */
+    soft: unknown;
+    /** 实底 */
+    solid: unknown;
+}
+/** 头像的外观选项；可以用 createUi / Provider 的 defaults.Avatar 统一改默认值 */
+export interface AvatarOptions {
+    /** 字号档位，头像边长是它的 2.5 倍；不写时继承 */
+    size?: TextSize;
+    /** 圆角，默认 full（圆形）；团队、组织、应用的图标常用 md（圆角方形） */
+    radius?: Radius;
+    /** 后备内容的底色样式，默认 soft */
+    variant?: keyof AvatarVariants;
+    /** 后备内容的色调（与 Button、Badge 等同一套），默认 accent */
+    tone?: StatusTone;
+}
+/** 角色与读屏可见性由组件按 name 决定 */
+export type AvatarManaged = 'role' | 'aria-hidden';
+/** 未声明的属性落到外层 span 上 */
+export interface AvatarProps extends PartProps<'span', AvatarManaged>, AvatarOptions {
+    /** 图片地址；不写或加载失败时显示后备内容 */
+    src?: string;
+    /** 名字：无障碍名称，也用来生成首字母；不写时头像是装饰性的 */
+    name?: string;
+    /** 后备内容，默认是名字的首字母，没有名字时是人像图标 */
+    fallback?: VNodeChild;
+    /** 图片的部件属性 */
+    propsImage?: PartProps<'img', 'src' | 'alt'>;
+    /** 后备内容的部件属性 */
+    propsFallback?: PartProps<'span'>;
+}
+/** 在 AvatarGroup 里：Avatar 据此叠放（AvatarGroup 提供） */
+export declare const AvatarGroupContext: import("@zerodep-dev/vue-tsx-pro-tsx").Context<{
+    readonly grouped: true;
+}>;
+/**
+ * 头像的配方：部件 root（外层）、image（图片）、fallback（后备内容）；在头像组里、图片加载中是档位。
+ * 后备内容的底色来自共用的 statusToneStyles，排在配方之前，createUi / Provider 的 styles.Avatar 能盖过它
+ */
+export declare const avatarRecipe: css.Recipe<"fallback" | "image" | "root", {
+    readonly grouped: {
+        readonly true: {
+            readonly root: {
+                readonly boxShadow: `0 0 0 ${string} ${string}`;
+                readonly marginInlineStart: {
+                    readonly default: "-0.5em";
+                    readonly ':first-child': 0;
+                };
+            };
+        };
+    };
+    readonly loading: {
+        readonly true: {
+            readonly image: {
+                readonly position: "absolute";
+                readonly opacity: 0;
+            };
+        };
+    };
+}>;
+/** 头像的部件（createUi / Provider 的 styles.Avatar 按它定制） */
+export type AvatarPart = (typeof avatarRecipe.parts)[number];
+/** 名字的首字母：中文取最后一个字（通常是名），其他语言取前两个词的首字母 */
+export declare function initials(name: string): string;
+/** 头像：图片 + 后备内容（首字母或图标） */
+export declare const Avatar: import("@zerodep-dev/vue-tsx-pro-tsx").TsxComponent<AvatarProps>;

package/dist/display/Avatar.js

@@ -0,0 +1,158 @@
+import { t } from "../config/theme/tokens.js";
+import { useDefaults } from "../config/defaults.js";
+import { mergeAttrs } from "../utils/props.js";
+import { fontSizeStyles } from "../utils/style/typography.js";
+import { radiusStyles } from "../utils/style/styles.js";
+import { useRecipe } from "../config/styles.js";
+import { Icon } from "../base/Icon.js";
+import { statusToneStyles } from "../utils/style/tone-styles.js";
+import { createVNode, mergeProps, ref, watch } from "vue";
+import { _component, createContext, readonlyProp, restProps } from "@zerodep-dev/vue-tsx-pro-tsx";
+import * as css from "@zerodep-dev/vue-tsx-pro-tsx/styles";
+import { User } from "@lucide/icons";
+//#region src/display/Avatar.tsx
+/**
+* 头像（span，role="img"）：显示图片，图片还没加载好或加载失败时显示后备内容（默认是名字的首字母）。
+* 名称写在外层（aria-label），图片本身是装饰（alt=""），读屏不会念两遍；没有 name 时整个头像是装饰性的（对读屏隐藏）。
+*
+*   <Avatar src={user.avatar} name={user.name} />
+*   <Avatar name="张三" size="lg" radius="md" />
+*   <Avatar name="李四" variant="solid" tone="success" />
+*/
+/** 后备内容（首字母、图标）的底色样式 */
+/** 头像的外观选项；可以用 createUi / Provider 的 defaults.Avatar 统一改默认值 */
+/** 角色与读屏可见性由组件按 name 决定 */
+/** 未声明的属性落到外层 span 上 */
+/** 在 AvatarGroup 里：Avatar 据此叠放（AvatarGroup 提供） */
+var AvatarGroupContext = createContext("AvatarGroup");
+/**
+* 头像的配方：部件 root（外层）、image（图片）、fallback（后备内容）；在头像组里、图片加载中是档位。
+* 后备内容的底色来自共用的 statusToneStyles，排在配方之前，createUi / Provider 的 styles.Avatar 能盖过它
+*/
+var avatarRecipe = css.recipe({
+	name: "Avatar",
+	parts: [
+		"root",
+		"image",
+		"fallback"
+	],
+	base: {
+		root: {
+			position: "relative",
+			display: "inline-flex",
+			alignItems: "center",
+			justifyContent: "center",
+			flexShrink: 0,
+			width: "2.5em",
+			height: "2.5em",
+			overflow: "hidden",
+			verticalAlign: "middle",
+			userSelect: "none"
+		},
+		image: {
+			width: "_full",
+			height: "_full",
+			objectFit: "cover"
+		},
+		fallback: {
+			fontWeight: "_medium",
+			lineHeight: 1,
+			textTransform: "uppercase"
+		}
+	},
+	variants: {
+		grouped: { true: { root: {
+			boxShadow: `0 0 0 ${t.borderWidths.sm} ${t.colors.background}`,
+			marginInlineStart: {
+				default: "-0.5em",
+				":first-child": 0
+			}
+		} } },
+		loading: { true: { image: {
+			position: "absolute",
+			opacity: 0
+		} } }
+	}
+});
+/** 头像的部件（createUi / Provider 的 styles.Avatar 按它定制） */
+/** 名字的首字母：中文取最后一个字（通常是名），其他语言取前两个词的首字母 */
+function initials(name) {
+	const trimmed = name.trim();
+	if (!trimmed) return "";
+	if (/[㐀-鿿]/.test(trimmed)) return trimmed.at(-1);
+	const words = trimmed.split(/\s+/);
+	return (words[0][0] + (words.length > 1 ? words.at(-1)[0] : "")).toUpperCase();
+}
+/** 头像：图片 + 后备内容（首字母或图标） */
+var Avatar = /*#__PURE__*/ _component((_props, _ctx) => {
+	const src = readonlyProp(_props, "src");
+	const name = readonlyProp(_props, "name");
+	const fallback = readonlyProp(_props, "fallback");
+	const size = readonlyProp(_props, "size");
+	const radius = readonlyProp(_props, "radius");
+	const variant = readonlyProp(_props, "variant");
+	const tone = readonlyProp(_props, "tone");
+	const propsImage = readonlyProp(_props, "propsImage");
+	const propsFallback = readonlyProp(_props, "propsFallback");
+	const rest = restProps(_props, _ctx, true);
+	const appearance = useDefaults("Avatar", () => ({
+		size: size.value,
+		radius: radius.value,
+		variant: variant.value,
+		tone: tone.value
+	}), {
+		radius: "full",
+		variant: "soft",
+		tone: "accent"
+	});
+	const recipe = useRecipe(avatarRecipe);
+	const group = AvatarGroupContext.inject(null);
+	let status = ref("loading");
+	watch(() => src.value, () => status.value = "loading");
+	return () => {
+		const showFallback = !src.value || status.value !== "loaded";
+		const { size: fontSize, radius: corner, variant: fill, tone: color } = appearance();
+		const s = recipe({
+			variant: fill,
+			tone: color,
+			grouped: !!group,
+			loading: status.value === "loading"
+		});
+		return createVNode("span", mergeProps(mergeAttrs({
+			...s.root,
+			sx: [
+				statusToneStyles[fill][color],
+				s.root.sx,
+				radiusStyles[corner],
+				fontSize && fontSizeStyles[fontSize]
+			]
+		}, rest, name.value ? {
+			role: "img",
+			"aria-label": name.value
+		} : { "aria-hidden": true }), { "data-state": src.value ? status.value : "fallback" }), [src.value && status.value !== "error" && createVNode("img", mergeProps({
+			"key": src.value,
+			"alt": ""
+		}, mergeAttrs(s.image, propsImage.value, {
+			src: src.value,
+			onLoad: () => status.value = "loaded",
+			onError: () => status.value = "error"
+		})), null), showFallback && createVNode("span", mergeAttrs(s.fallback, propsFallback.value, { "aria-hidden": true }), [fallback.value ?? (name.value ? initials(name.value) : createVNode(Icon, { "icon": User }, null))])]);
+	};
+}, {
+	name: "Avatar",
+	props: [
+		"src",
+		"name",
+		"fallback",
+		"size",
+		"radius",
+		"variant",
+		"tone",
+		"propsImage",
+		"propsFallback"
+	]
+});
+//#endregion
+export { Avatar, AvatarGroupContext, avatarRecipe, initials };
+
+//# sourceMappingURL=Avatar.js.map

package/dist/display/Avatar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Avatar.js","names":["_vtp_readonlyProp","_vtp_restProps","_vue_ref","_createVNode","_mergeProps"],"sources":["../../src/display/Avatar.tsx"],"sourcesContent":["/**\n * 头像（span，role=\"img\"）：显示图片，图片还没加载好或加载失败时显示后备内容（默认是名字的首字母）。\n * 名称写在外层（aria-label），图片本身是装饰（alt=\"\"），读屏不会念两遍；没有 name 时整个头像是装饰性的（对读屏隐藏）。\n *\n *   <Avatar src={user.avatar} name={user.name} />\n *   <Avatar name=\"张三\" size=\"lg\" radius=\"md\" />\n *   <Avatar name=\"李四\" variant=\"solid\" tone=\"success\" />\n */\nimport { User } from '@lucide/icons';\nimport { createContext, _component } from '@zerodep-dev/vue-tsx-pro-tsx';\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport { watch, type VNodeChild } from 'vue';\nimport { Icon } from '../base/Icon';\nimport { useDefaults } from '../config/defaults';\nimport { useRecipe } from '../config/styles';\nimport { mergeAttrs, type PartProps } from '../utils/props';\nimport { statusToneStyles, type StatusTone } from '../utils/style/tone-styles';\nimport { fontSizeStyles, type TextSize } from '../utils/style/typography';\nimport { radiusStyles, type Radius } from '../utils/style/styles';\nimport { t } from '../config/theme/tokens';\n\n/** 后备内容（首字母、图标）的底色样式 */\nexport interface AvatarVariants {\n  /** 浅色底（默认） */\n  soft: unknown;\n  /** 实底 */\n  solid: unknown;\n}\n\n/** 头像的外观选项；可以用 createUi / Provider 的 defaults.Avatar 统一改默认值 */\nexport interface AvatarOptions {\n  /** 字号档位，头像边长是它的 2.5 倍；不写时继承 */\n  size?: TextSize;\n  /** 圆角，默认 full（圆形）；团队、组织、应用的图标常用 md（圆角方形） */\n  radius?: Radius;\n  /** 后备内容的底色样式，默认 soft */\n  variant?: keyof AvatarVariants;\n  /** 后备内容的色调（与 Button、Badge 等同一套），默认 accent */\n  tone?: StatusTone;\n}\n\n/** 角色与读屏可见性由组件按 name 决定 */\nexport type AvatarManaged = 'role' | 'aria-hidden';\n\n/** 未声明的属性落到外层 span 上 */\nexport interface AvatarProps extends PartProps<'span', AvatarManaged>, AvatarOptions {\n  /** 图片地址；不写或加载失败时显示后备内容 */\n  src?: string;\n  /** 名字：无障碍名称，也用来生成首字母；不写时头像是装饰性的 */\n  name?: string;\n  /** 后备内容，默认是名字的首字母，没有名字时是人像图标 */\n  fallback?: VNodeChild;\n  /** 图片的部件属性 */\n  propsImage?: PartProps<'img', 'src' | 'alt'>;\n  /** 后备内容的部件属性 */\n  propsFallback?: PartProps<'span'>;\n}\n\n/** 在 AvatarGroup 里：Avatar 据此叠放（AvatarGroup 提供） */\nexport const AvatarGroupContext = createContext<{ readonly grouped: true }>('AvatarGroup');\n\n/**\n * 头像的配方：部件 root（外层）、image（图片）、fallback（后备内容）；在头像组里、图片加载中是档位。\n * 后备内容的底色来自共用的 statusToneStyles，排在配方之前，createUi / Provider 的 styles.Avatar 能盖过它\n */\nexport const avatarRecipe = css.recipe({\n  name: 'Avatar',\n  parts: ['root', 'image', 'fallback'],\n  base: {\n    root: {\n      position: 'relative',\n      display: 'inline-flex',\n      alignItems: 'center',\n      justifyContent: 'center',\n      flexShrink: 0,\n      width: '2.5em',\n      height: '2.5em',\n      overflow: 'hidden',\n      verticalAlign: 'middle',\n      userSelect: 'none',\n    },\n    image: { width: '_full', height: '_full', objectFit: 'cover' },\n    fallback: { fontWeight: '_medium', lineHeight: 1, textTransform: 'uppercase' },\n  },\n  variants: {\n    // 头像组里：往前叠 0.5em，一圈页面底色的描边把相邻的分开（AvatarGroup 的“+N”也用它）\n    grouped: {\n      true: {\n        root: {\n          boxShadow: `0 0 0 ${t.borderWidths.sm} ${t.colors.background}`,\n          marginInlineStart: { default: '-0.5em', ':first-child': 0 },\n        },\n      },\n    },\n    // 图片加载完之前先藏起来（仍在 DOM 里加载），后备内容垫在下面\n    loading: { true: { image: { position: 'absolute', opacity: 0 } } },\n  },\n});\n\n/** 头像的部件（createUi / Provider 的 styles.Avatar 按它定制） */\nexport type AvatarPart = (typeof avatarRecipe.parts)[number];\n\n/** 名字的首字母：中文取最后一个字（通常是名），其他语言取前两个词的首字母 */\nexport function initials(name: string): string {\n  const trimmed = name.trim();\n  if (!trimmed) return '';\n  if (/[㐀-鿿]/.test(trimmed)) return trimmed.at(-1)!;\n  const words = trimmed.split(/\\s+/);\n  return (words[0]![0]! + (words.length > 1 ? words.at(-1)![0]! : '')).toUpperCase();\n}\n\n/** 头像：图片 + 后备内容（首字母或图标） */\nexport const Avatar = _component(\n  ({\n    src,\n    name,\n    fallback,\n    size,\n    radius,\n    variant,\n    tone,\n    propsImage,\n    propsFallback,\n    ...rest\n  }: AvatarProps) => {\n    const appearance = useDefaults('Avatar', () => ({ size, radius, variant, tone }), {\n      radius: 'full',\n      variant: 'soft',\n      tone: 'accent',\n    });\n    const recipe = useRecipe(avatarRecipe);\n    const group = AvatarGroupContext.inject(null);\n    // 图片状态：loading 加载中、loaded 已显示、error 失败（显示后备内容）\n    let status = _state<'loading' | 'loaded' | 'error'>('loading');\n    watch(\n      () => src,\n      () => (status = 'loading'),\n    );\n\n    return () => {\n      const showFallback = !src || status !== 'loaded';\n      const { size: fontSize, radius: corner, variant: fill, tone: color } = appearance();\n      const s = recipe({\n        variant: fill,\n        tone: color,\n        grouped: !!group,\n        loading: status === 'loading',\n      });\n      return (\n        <span\n          {...mergeAttrs<'span'>(\n            {\n              ...s.root,\n              sx: [\n                statusToneStyles[fill][color],\n                s.root.sx,\n                radiusStyles[corner],\n                fontSize && fontSizeStyles[fontSize],\n              ],\n            },\n            rest,\n            name ? { role: 'img', 'aria-label': name } : { 'aria-hidden': true },\n          )}\n          data-state={src ? status : 'fallback'}\n        >\n          {src && status !== 'error' && (\n            <img\n              key={src}\n              alt=\"\"\n              {...mergeAttrs<'img'>(s.image, propsImage, {\n                src,\n                onLoad: () => (status = 'loaded'),\n                onError: () => (status = 'error'),\n              })}\n            />\n          )}\n          {showFallback && (\n            <span {...mergeAttrs<'span'>(s.fallback, propsFallback, { 'aria-hidden': true })}>\n              {fallback ?? (name ? initials(name) : <Icon icon={User} />)}\n            </span>\n          )}\n        </span>\n      );\n    };\n  },\n);\n"],"mappings":"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"}

package/dist/display/AvatarGroup.d.ts

@@ -0,0 +1,29 @@
+import * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';
+import type { VNodeChild } from 'vue';
+import { type PartProps } from '../utils/props';
+import { type TextSize } from '../utils/style/typography';
+/** 角色由组件管理 */
+export type AvatarGroupManaged = 'role';
+/** 未声明的属性落到 div 上；aria-label 是这组人的名称 */
+export interface AvatarGroupProps extends PartProps<'div', AvatarGroupManaged> {
+    /** 最多显示几个头像，其余折叠成“+N”；不写时全部显示 */
+    max?: number;
+    /** 总人数：列表只拿到前几个时给出，“+N”按它算 */
+    total?: number;
+    /** 字号档位，头像边长是它的 2.5 倍；不写时继承 */
+    size?: TextSize;
+    /** “+N”的部件属性 */
+    propsMore?: PartProps<'span', 'role'>;
+    /** “+N”文字的部件属性；读屏念的是 More 的 aria-label，这里对读屏隐藏 */
+    propsMoreText?: PartProps<'span', 'aria-hidden'>;
+    /** 头像（Avatar） */
+    children?: VNodeChild;
+}
+/** AvatarGroup 的样式：root、more、moreText */
+export declare const avatarGroupStyles: Readonly<{
+    more: css.CompiledStyles;
+    moreText: css.CompiledStyles;
+    root: css.CompiledStyles;
+}>;
+/** 头像组：叠放的头像，超过 max 的折叠成“+N” */
+export declare const AvatarGroup: import("@zerodep-dev/vue-tsx-pro-tsx").TsxComponent<AvatarGroupProps>;

package/dist/display/AvatarGroup.js

@@ -0,0 +1,67 @@
+import { useLang } from "../config/context.js";
+import { mergeAttrs } from "../utils/props.js";
+import { fontSizeStyles } from "../utils/style/typography.js";
+import { radiusStyles } from "../utils/style/styles.js";
+import { useRecipe } from "../config/styles.js";
+import { childNodes } from "../utils/data/text.js";
+import { AvatarGroupContext, avatarRecipe } from "./Avatar.js";
+import { createTextVNode, createVNode } from "vue";
+import { _component, childrenProp, readonlyProp, restProps } from "@zerodep-dev/vue-tsx-pro-tsx";
+import * as css from "@zerodep-dev/vue-tsx-pro-tsx/styles";
+//#region src/display/AvatarGroup.tsx
+/** 角色由组件管理 */
+/** 未声明的属性落到 div 上；aria-label 是这组人的名称 */
+/** AvatarGroup 的样式：root、more、moreText */
+var avatarGroupStyles = css.create({
+	root: {
+		display: "inline-flex",
+		alignItems: "center"
+	},
+	more: {
+		backgroundColor: "_fill",
+		color: "_text"
+	},
+	moreText: {
+		fontSize: "0.875em",
+		fontWeight: "_medium"
+	}
+});
+/** 头像组：叠放的头像，超过 max 的折叠成“+N” */
+var AvatarGroup = /*#__PURE__*/ _component((_props, _ctx) => {
+	const max = readonlyProp(_props, "max");
+	const total = readonlyProp(_props, "total");
+	const size = readonlyProp(_props, "size");
+	const propsMore = readonlyProp(_props, "propsMore");
+	const propsMoreText = readonlyProp(_props, "propsMoreText");
+	const children = childrenProp(_props);
+	const rest = restProps(_props, _ctx, false);
+	const lang = useLang();
+	AvatarGroupContext.provide({ grouped: true });
+	const avatar = useRecipe(avatarRecipe);
+	return () => {
+		const avatars = childNodes(children.value);
+		const shown = max.value != null && avatars.length > max.value ? avatars.slice(0, max.value) : avatars;
+		const hidden = (total.value ?? avatars.length) - shown.length;
+		return createVNode("div", mergeAttrs({ sx: [avatarGroupStyles.root, size.value && fontSizeStyles[size.value]] }, rest, { role: "group" }), [shown, hidden > 0 && createVNode("span", mergeAttrs({
+			sx: [
+				avatar({ grouped: true }).root.sx,
+				radiusStyles.full,
+				avatarGroupStyles.more
+			],
+			"aria-label": lang.avatarMore(hidden)
+		}, propsMore.value, { role: "img" }), [createVNode("span", mergeAttrs({ sx: avatarGroupStyles.moreText }, propsMoreText.value, { "aria-hidden": true }), [createTextVNode("+"), hidden])])]);
+	};
+}, {
+	name: "AvatarGroup",
+	props: [
+		"max",
+		"total",
+		"size",
+		"propsMore",
+		"propsMoreText"
+	]
+});
+//#endregion
+export { AvatarGroup, avatarGroupStyles };
+
+//# sourceMappingURL=AvatarGroup.js.map

package/dist/display/AvatarGroup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AvatarGroup.js","names":["_vtp_readonlyProp","_vtp_childrenProp","_vtp_restProps","_createVNode","_createTextVNode"],"sources":["../../src/display/AvatarGroup.tsx"],"sourcesContent":["/**\n * 头像组（div，role=\"group\"）：一排头像叠放，超过 max 的折叠成“+N”。协作者、参与人、点赞的人。\n *\n *   <AvatarGroup max={3} aria-label=\"协作者\">\n *     {members.map((member) => <Avatar key={member.id} name={member.name} src={member.avatar} />)}\n *   </AvatarGroup>\n *\n * 头像的大小随组的 size（或上下文字号）；组里的 Avatar 经 AvatarGroupContext 得知自己在组里，叠放并加一圈页面底色的描边。\n * “+N”读屏念“还有 N 人”（语言包的 avatarMore）；total 给了时按它算 N（列表只拿到了一部分时）。\n * 部件：Root（div）、More（+N）、MoreText（More 里的“+N”文字）。\n */\nimport { _component } from '@zerodep-dev/vue-tsx-pro-tsx';\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport type { VNodeChild } from 'vue';\nimport { useLang } from '../config/context';\nimport { useRecipe } from '../config/styles';\nimport { childNodes } from '../utils/data/text';\nimport { mergeAttrs, type PartProps } from '../utils/props';\nimport { radiusStyles } from '../utils/style/styles';\nimport { fontSizeStyles, type TextSize } from '../utils/style/typography';\nimport { AvatarGroupContext, avatarRecipe } from './Avatar';\n\n/** 角色由组件管理 */\nexport type AvatarGroupManaged = 'role';\n\n/** 未声明的属性落到 div 上；aria-label 是这组人的名称 */\nexport interface AvatarGroupProps extends PartProps<'div', AvatarGroupManaged> {\n  /** 最多显示几个头像，其余折叠成“+N”；不写时全部显示 */\n  max?: number;\n  /** 总人数：列表只拿到前几个时给出，“+N”按它算 */\n  total?: number;\n  /** 字号档位，头像边长是它的 2.5 倍；不写时继承 */\n  size?: TextSize;\n  /** “+N”的部件属性 */\n  propsMore?: PartProps<'span', 'role'>;\n  /** “+N”文字的部件属性；读屏念的是 More 的 aria-label，这里对读屏隐藏 */\n  propsMoreText?: PartProps<'span', 'aria-hidden'>;\n  /** 头像（Avatar） */\n  children?: VNodeChild;\n}\n\n/** AvatarGroup 的样式：root、more、moreText */\nexport const avatarGroupStyles = css.create({\n  root: { display: 'inline-flex', alignItems: 'center' },\n  more: { backgroundColor: '_fill', color: '_text' },\n  // 字号缩在文字上：“+N”的圆仍和头像一样大\n  moreText: { fontSize: '0.875em', fontWeight: '_medium' },\n});\n\n/** 头像组：叠放的头像，超过 max 的折叠成“+N” */\nexport const AvatarGroup = _component(\n  ({ max, total, size, propsMore, propsMoreText, children, ...rest }: AvatarGroupProps) => {\n    const lang = useLang();\n    AvatarGroupContext.provide({ grouped: true });\n    // “+N”和组里的头像一样大、一样叠放：取头像配方（带主题定制）里组内头像的外层样式\n    const avatar = useRecipe(avatarRecipe);\n    return () => {\n      const avatars = childNodes(children);\n      const shown = max != null && avatars.length > max ? avatars.slice(0, max) : avatars;\n      const hidden = (total ?? avatars.length) - shown.length;\n      return (\n        <div\n          {...mergeAttrs<'div'>(\n            { sx: [avatarGroupStyles.root, size && fontSizeStyles[size]] },\n            rest,\n            { role: 'group' },\n          )}\n        >\n          {shown}\n          {hidden > 0 && (\n            <span\n              {...mergeAttrs<'span'>(\n                {\n                  sx: [\n                    avatar({ grouped: true }).root.sx,\n                    radiusStyles.full,\n                    avatarGroupStyles.more,\n                  ],\n                  'aria-label': lang.avatarMore(hidden),\n                },\n                propsMore,\n                { role: 'img' },\n              )}\n            >\n              <span\n                {...mergeAttrs<'span'>({ sx: avatarGroupStyles.moreText }, propsMoreText, {\n                  'aria-hidden': true,\n                })}\n              >\n                +{hidden}\n              </span>\n            </span>\n          )}\n        </div>\n      );\n    };\n  },\n);\n"],"mappings":";;;;;;;;;;;;;;AA0CA,IAAa,oBAAoB,IAAI,OAAO;CAC1C,MAAM;EAAE,SAAS;EAAe,YAAY;CAAS;CACrD,MAAM;EAAE,iBAAiB;EAAS,OAAO;CAAQ;CAEjD,UAAU;EAAE,UAAU;EAAW,YAAY;CAAU;AACzD,CAAC;;AAGD,IAAa,cAAc,0BACzB,QAAA,SAAyF;CAAA,MAAA,MAAAA,aAAA,QAAA,KAAA;CAAA,MAAA,QAAAA,aAAA,QAAA,OAAA;CAAA,MAAA,OAAAA,aAAA,QAAA,MAAA;CAAA,MAAA,YAAAA,aAAA,QAAA,WAAA;CAAA,MAAA,gBAAAA,aAAA,QAAA,eAAA;CAAA,MAAA,WAAAC,aAAA,MAAA;CAAA,MAA7B,OAAIC,UAAA,QAAA,MAAA,KAAA;CAC9D,MAAM,OAAO,QAAQ;CACrB,mBAAmB,QAAQ,EAAE,SAAS,KAAK,CAAC;CAE5C,MAAM,SAAS,UAAU,YAAY;CACrC,aAAa;EACX,MAAM,UAAU,WAAU,SAAA,KAAS;EACnC,MAAM,QAAQ,IAAA,SAAO,QAAQ,QAAQ,SAAM,IAAA,QAAS,QAAQ,MAAM,GAAC,IAAA,KAAK,IAAI;EAC5E,MAAM,UAAU,MAAA,SAAS,QAAQ,UAAU,MAAM;EACjD,OAAAC,YAAA,OAEQ,WACF,EAAE,IAAI,CAAC,kBAAkB,MAAM,KAAA,SAAQ,eAAc,KAAA,MAAM,EAAE,GAC7D,MACA,EAAE,MAAM,QAAQ,CAClB,GAAC,CAEA,OACA,SAAS,KAACA,YAAA,QAEH,WACF;GACE,IAAI;IACF,OAAO,EAAE,SAAS,KAAK,CAAC,CAAC,CAAC,KAAK;IAC/B,aAAa;IACb,kBAAkB;GAAI;GAExB,cAAc,KAAK,WAAW,MAAM;EACtC,GAAC,UAAA,OAED,EAAE,MAAM,MAAM,CAChB,GAAC,CAAAA,YAAA,QAGK,WAAmB,EAAE,IAAI,kBAAkB,SAAS,GAAC,cAAA,OAAiB,EACxE,eAAe,KACjB,CAAC,GAAC,CAAAC,gBAAA,GAAA,GAEA,MAAM,CAAA,CAAA,CAAA,CAGb,CAAA;CAGP;AACF,GAAC;CAAA,MAAA;CAAA,OAAA;EAAA;EAAA;EAAA;EAAA;EAAA;CAAA;AAAA,CACH"}