@qw-ui/core 0.3.0-next.9 → 0.3.0

package/dist/back-top/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/back-top/back-top.ts"],"sourcesContent":["import { createMachine, type Machine, type Service } from \"@zag-js/core\";\nimport type { NormalizeProps, PropTypes } from \"@zag-js/types\";\nimport { resolveIconState, type IconState } from \"../icon/index.js\";\n\n/** Stable DOM parts shared by every adapter. */\nexport const BACK_TOP_PARTS = [\"root\", \"icon\", \"label\"] as const;\n/** SSR-safe input shared by all adapters. */\nexport interface QwBackTopProps {\n  /** Page-unique instance identity; adapters generate one when omitted. */\n  id?: string;\n  /** Accessible button name; defaults to 回到顶部. */\n  label?: string;\n  /** Show the visible label next to the icon; the name is always present. */\n  showLabel?: boolean;\n  /** Scroll distance in CSS pixels after which the button appears; defaults to 400. */\n  visibilityHeight?: number;\n  /** Element id of the scrolling container; omitted or missing means the document scroller. */\n  target?: string;\n  /** Called once per activation, after the scroll request is issued. */\n  onActivate?: () => void;\n}\nexport interface ResolvedBackTopState { label: string; showLabel: boolean; visibilityHeight: number; target: string | undefined }\nexport function resolveBackTopState(props: QwBackTopProps = {}): ResolvedBackTopState {\n  const height = props.visibilityHeight;\n  return { label: typeof props.label === \"string\" && props.label.trim() ? props.label : \"回到顶部\", showLabel: !!props.showLabel,\n    visibilityHeight: typeof height === \"number\" && Number.isFinite(height) && height >= 0 ? height : 400,\n    target: typeof props.target === \"string\" && props.target.trim() ? props.target : undefined };\n}\n/** Visible above the threshold; a focused button is never hidden under the user. */\nexport function isBackTopShown(state: ResolvedBackTopState, scrollTop: number, focused: boolean): boolean {\n  return focused || scrollTop >= Math.max(1, state.visibilityHeight);\n}\nexport function createBackTopProps(props: QwBackTopProps = {}): QwBackTopProps {\n  if (props.id !== undefined && (typeof props.id !== \"string\" || !props.id.trim())) throw new TypeError(\"BackTop requires a nonempty instance id when provided\");\n  return { ...props };\n}\n\nexport interface QwBackTopSchema {\n  props: QwBackTopProps;\n  context: { scrollTop: number; focused: boolean };\n  refs: { schedule: (() => void) | null };\n  state: \"ready\";\n  action: \"setScroll\" | \"setFocused\" | \"scrollToTop\" | \"remeasure\";\n  effect: \"trackScroll\";\n  event: { type: \"SCROLL.SET\"; scrollTop: number } | { type: \"FOCUS.SET\"; focused: boolean } | { type: \"ACTIVATE\" };\n}\nexport type QwBackTopMachine = Machine<QwBackTopSchema>;\nexport type QwBackTopService = Service<QwBackTopSchema>;\nconst rootId = (scope: QwBackTopService[\"scope\"]) => `back-top:${scope.id}`;\nconst live = (service: Pick<QwBackTopService, \"prop\">) => resolveBackTopState({ label: service.prop(\"label\"), showLabel: service.prop(\"showLabel\"), visibilityHeight: service.prop(\"visibilityHeight\"), target: service.prop(\"target\") });\n\n/** Platform boundary: the element id is looked up in the button's own root node. */\nfunction resolveScroller(root: HTMLElement, state: ResolvedBackTopState): { node: HTMLElement | null; events: EventTarget } {\n  const win = root.ownerDocument.defaultView!;\n  const owner = root.getRootNode() as Document | ShadowRoot;\n  const found = state.target ? owner.getElementById?.(state.target) ?? root.ownerDocument.getElementById(state.target) : null;\n  return found ? { node: found, events: found } : { node: null, events: win };\n}\nfunction readScrollTop(root: HTMLElement, node: HTMLElement | null): number {\n  if (node) return node.scrollTop;\n  const win = root.ownerDocument.defaultView;\n  return win?.scrollY ?? root.ownerDocument.documentElement.scrollTop;\n}\n\n/** Core owns listening, threshold decisions, reduced-motion scrolling and cleanup. */\nexport const backTopMachine: QwBackTopMachine = createMachine<QwBackTopSchema>({\n  props: ({ props }) => createBackTopProps(props), initialState: () => \"ready\", states: { ready: {} },\n  context: ({ bindable }) => ({ scrollTop: bindable(() => ({ defaultValue: 0 })), focused: bindable(() => ({ defaultValue: false })) }),\n  refs: () => ({ schedule: null }),\n  watch({ track, prop, action }) { track([() => prop(\"target\"), () => prop(\"visibilityHeight\")], () => action([\"remeasure\"])); },\n  on: { \"SCROLL.SET\": { actions: [\"setScroll\"] }, \"FOCUS.SET\": { actions: [\"setFocused\"] }, ACTIVATE: { actions: [\"scrollToTop\"] } },\n  effects: [\"trackScroll\"],\n  implementations: {\n    actions: {\n      setScroll(params) { if (params.event.type === \"SCROLL.SET\") params.context.set(\"scrollTop\", params.event.scrollTop); },\n      setFocused(params) { if (params.event.type === \"FOCUS.SET\") params.context.set(\"focused\", params.event.focused); },\n      remeasure(params) { params.refs.get(\"schedule\")?.(); },\n      scrollToTop({ scope, prop }) {\n        const root = scope.getById<HTMLElement>(rootId(scope)), win = root?.ownerDocument.defaultView;\n        if (root && win) {\n          const reduce = win.matchMedia?.(\"(prefers-reduced-motion: reduce)\").matches ?? false;\n          const { node } = resolveScroller(root, live({ prop }));\n          const options: ScrollToOptions = { top: 0, behavior: reduce ? \"auto\" : \"smooth\" };\n          if (node) node.scrollTo?.(options); else win.scrollTo?.(options);\n        }\n        prop(\"onActivate\")?.();\n      },\n    },\n    effects: { trackScroll({ scope, prop, send, refs, context }) {\n      const root = scope.getById<HTMLElement>(rootId(scope)), win = root?.ownerDocument.defaultView;\n      if (!root || !win) return;\n      let frame = 0, events: EventTarget | null = null, node: HTMLElement | null = null, disposed = false;\n      const run = () => {\n        frame = 0; if (disposed) return;\n        const next = resolveScroller(root, live({ prop }));\n        if (next.events !== events) { events?.removeEventListener(\"scroll\", schedule); events = next.events; node = next.node; events.addEventListener(\"scroll\", schedule, { passive: true }); }\n        const top = readScrollTop(root, node);\n        if (top !== context.get(\"scrollTop\")) send({ type: \"SCROLL.SET\", scrollTop: top });\n      };\n      function schedule() { if (!frame && !disposed) frame = win!.requestAnimationFrame(run); }\n      refs.set(\"schedule\", schedule); run();\n      return () => { disposed = true; refs.set(\"schedule\", null); if (frame) win.cancelAnimationFrame(frame); events?.removeEventListener(\"scroll\", schedule); };\n    } },\n  },\n});\n\nexport interface QwBackTopApi<T extends PropTypes = PropTypes> {\n  shown: boolean; label: string; showLabel: boolean;\n  activate(): void;\n  getRootProps(): T[\"button\"];\n  getIconProps(): T[\"element\"];\n  getIconState(): IconState;\n  getLabelProps(): T[\"element\"];\n}\n/** Framework/native event shape; only cancellation is read. */\nexport interface BackTopDomEvent { readonly defaultPrevented: boolean }\ntype BackTopCallerHandler = (event: BackTopDomEvent) => void;\n/** Caller root handlers run first; Core then activates (unless prevented) and always tracks focus. Method syntax keeps framework handlers assignable. */\nexport interface BackTopConnectOptions {\n  onClick?(event: BackTopDomEvent): void;\n  onFocus?(event: BackTopDomEvent): void;\n  onBlur?(event: BackTopDomEvent): void;\n}\nconst callAll = (handlers: unknown, event: BackTopDomEvent) => {\n  for (const handler of Array.isArray(handlers) ? handlers : [handlers]) if (typeof handler === \"function\") (handler as BackTopCallerHandler)(event);\n};\nexport function connectBackTop<T extends PropTypes>(service: QwBackTopService, normalize: NormalizeProps<T>, options: BackTopConnectOptions = {}): QwBackTopApi<T> {\n  const state = live(service), id = rootId(service.scope);\n  const shown = isBackTopShown(state, service.context.get(\"scrollTop\"), service.context.get(\"focused\"));\n  const activate = () => service.send({ type: \"ACTIVATE\" });\n  return {\n    shown, label: state.label, showLabel: state.showLabel, activate,\n    getRootProps: () => normalize.button({ \"data-scope\": \"back-top\", \"data-part\": \"root\", id, type: \"button\", hidden: !shown || undefined, \"data-state\": shown ? \"visible\" : \"hidden\",\n      \"data-show-label\": state.showLabel ? \"true\" : undefined, \"aria-label\": state.showLabel ? undefined : state.label,\n      onClick(event: BackTopDomEvent) { callAll(options.onClick, event); if (!event.defaultPrevented) activate(); },\n      onFocus(event: BackTopDomEvent) { callAll(options.onFocus, event); service.send({ type: \"FOCUS.SET\", focused: true }); },\n      onBlur(event: BackTopDomEvent) { callAll(options.onBlur, event); service.send({ type: \"FOCUS.SET\", focused: false }); } }),\n    getIconProps: () => normalize.element({ \"data-scope\": \"back-top\", \"data-part\": \"icon\", \"aria-hidden\": true }),\n    getIconState: () => resolveIconState({ id: `${id}:icon`, name: \"to-top\" }),\n    getLabelProps: () => normalize.element({ \"data-scope\": \"back-top\", \"data-part\": \"label\", hidden: !state.showLabel || undefined }),\n  };\n}\n"],"mappings":"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"}

package/dist/badge/badge.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Badge 契约 — 原型 A（无状态），core 无 machine，
+ * 承载双栈共享的类型契约与纯函数状态解析（SSR-safe，无 DOM 依赖）。
+ * 渲染契约：`data-scope="badge"`，`data-part="root"`；
+ * `data-variant` / `data-kind` 摊平枚举。
+ *
+ * 变体 / 形态 / 部位词表以运行时常量数组为唯一事实源（类型从常量推导），__test__ 直接锁死。
+ */
+/** 视觉变体全集：solid 强提示（默认）/ subtle 弱提示。 */
+export declare const BADGE_VARIANTS: readonly ["solid", "subtle"];
+/** 形态全集：number 数字（默认）/ dot 纯红点。 */
+export declare const BADGE_KINDS: readonly ["number", "dot"];
+/** Badge 各渲染部位全集（data-part 取值）。 */
+export declare const BADGE_PARTS: readonly ["root"];
+/** 默认溢出阈值：数值超过时收敛为「99+」。 */
+export declare const DEFAULT_BADGE_MAX_COUNT = 99;
+export type BadgeVariant = (typeof BADGE_VARIANTS)[number];
+export type BadgeKind = (typeof BADGE_KINDS)[number];
+export type BadgePart = (typeof BADGE_PARTS)[number];
+/**
+ * QwBadgeProps — 双栈共享的行为契约（全字段可选）。
+ * 视觉完全由语义令牌驱动，组件不开放自定义色值入口。
+ */
+export interface QwBadgeProps {
+    /** 视觉变体，默认 solid；dot 形态强制 solid。 */
+    variant?: BadgeVariant;
+    /** 纯红点形态，默认 false；为 true 时优先于 count。 */
+    dot?: boolean;
+    /** 未读数量；≤0 / 非有限数值不渲染。 */
+    count?: number;
+    /** 溢出阈值，默认 99；非法值（≤0 或非整数）回退默认。 */
+    maxCount?: number;
+    /** 自定义无障碍播报文案，全量覆盖默认文案。 */
+    ariaLabel?: string;
+}
+/** 适配层从 locale 传入的默认播报文案。 */
+export interface BadgeAriaTexts {
+    /** 数字形态播报模板，含 {count} 占位符。 */
+    unreadAriaTemplate: string;
+    /** 纯红点形态播报文案。 */
+    dotAria: string;
+}
+/** resolveBadgeState 的解析结果，适配层据此摊平渲染。 */
+export interface ResolvedBadgeState {
+    /** 是否渲染徽标本体；false 时双栈一致返回空渲染。 */
+    visible: boolean;
+    /** 形态。 */
+    kind: BadgeKind;
+    /** 解析后的视觉变体（dot + subtle 已降级为 solid）。 */
+    variant: BadgeVariant;
+    /** 可见文本（溢出为「<阈值>+」；dot / 不可见为空串）。 */
+    label: string;
+    /** 数值是否超过阈值。 */
+    overflow: boolean;
+    /** 解析后的生效阈值。 */
+    maxCount: number;
+    /** 生效的无障碍播报文案。 */
+    ariaLabel: string;
+}
+/**
+ * 纯函数：props + 文案 → 解析结果。
+ * 规则：dot 优先于 count；dot 强制 solid；数值四舍五入；
+ * ≤0 / NaN / Infinity 不渲染；溢出渲染「<阈值>+」。
+ */
+export declare function resolveBadgeState(props: QwBadgeProps, texts: BadgeAriaTexts): ResolvedBadgeState;
+/** 根元素 prop-getter 返回的 DOM 属性集。 */
+export interface BadgeRootProps {
+    "data-scope": "badge";
+    "data-part": "root";
+    "data-variant": BadgeVariant;
+    "data-kind": BadgeKind;
+    role: "status";
+    "aria-label": string;
+}
+/** 根元素 prop-getter：摊平 data 状态属性 + role="status" + 播报文案。 */
+export declare function getBadgeRootProps(state: ResolvedBadgeState): BadgeRootProps;
+/** Passive root retained by native hosts even when no badge is visible. */
+export interface BadgeRetainedRootProps extends Omit<BadgeRootProps, "role" | "aria-label"> {
+    role?: "status";
+    "aria-label"?: string;
+    hidden?: true;
+    "aria-hidden"?: "true";
+}
+/** Keep visibility and announcement decisions in Core while retaining the DOM root. */
+export declare function getBadgeRetainedRootProps(state: ResolvedBadgeState, hidden?: boolean): BadgeRetainedRootProps;

package/dist/badge/index.d.ts

@@ -0,0 +1 @@
+export * from "./badge.js";

package/dist/badge/index.js

@@ -0,0 +1,88 @@
+//#region src/badge/badge.ts
+/**
+* Badge 契约 — 原型 A（无状态），core 无 machine，
+* 承载双栈共享的类型契约与纯函数状态解析（SSR-safe，无 DOM 依赖）。
+* 渲染契约：`data-scope="badge"`，`data-part="root"`；
+* `data-variant` / `data-kind` 摊平枚举。
+*
+* 变体 / 形态 / 部位词表以运行时常量数组为唯一事实源（类型从常量推导），__test__ 直接锁死。
+*/
+/** 视觉变体全集：solid 强提示（默认）/ subtle 弱提示。 */
+const BADGE_VARIANTS = ["solid", "subtle"];
+/** 形态全集：number 数字（默认）/ dot 纯红点。 */
+const BADGE_KINDS = ["number", "dot"];
+/** Badge 各渲染部位全集（data-part 取值）。 */
+const BADGE_PARTS = ["root"];
+/** 默认溢出阈值：数值超过时收敛为「99+」。 */
+const DEFAULT_BADGE_MAX_COUNT = 99;
+/** 非法阈值（≤0 或非整数）一律回退默认值，避免非法配置导致空渲染。 */
+function resolveMaxCount(maxCount) {
+	return typeof maxCount === "number" && Number.isInteger(maxCount) && maxCount > 0 ? maxCount : 99;
+}
+/**
+* 纯函数：props + 文案 → 解析结果。
+* 规则：dot 优先于 count；dot 强制 solid；数值四舍五入；
+* ≤0 / NaN / Infinity 不渲染；溢出渲染「<阈值>+」。
+*/
+function resolveBadgeState(props, texts) {
+	const { variant = "solid", dot = false, count, maxCount, ariaLabel } = props;
+	const safeMax = resolveMaxCount(maxCount);
+	if (dot) return {
+		visible: true,
+		kind: "dot",
+		variant: "solid",
+		label: "",
+		overflow: false,
+		maxCount: safeMax,
+		ariaLabel: ariaLabel ?? texts.dotAria
+	};
+	const normalized = typeof count === "number" && Number.isFinite(count) && count > 0 ? Math.round(count) : 0;
+	if (normalized === 0) return {
+		visible: false,
+		kind: "number",
+		variant,
+		label: "",
+		overflow: false,
+		maxCount: safeMax,
+		ariaLabel: ""
+	};
+	const overflow = normalized > safeMax;
+	const label = overflow ? `${safeMax}+` : `${normalized}`;
+	return {
+		visible: true,
+		kind: "number",
+		variant,
+		label,
+		overflow,
+		maxCount: safeMax,
+		ariaLabel: ariaLabel ?? texts.unreadAriaTemplate.replaceAll("{count}", label)
+	};
+}
+/** 根元素 prop-getter：摊平 data 状态属性 + role="status" + 播报文案。 */
+function getBadgeRootProps(state) {
+	return {
+		"data-scope": "badge",
+		"data-part": "root",
+		"data-variant": state.variant,
+		"data-kind": state.kind,
+		role: "status",
+		"aria-label": state.ariaLabel
+	};
+}
+/** Keep visibility and announcement decisions in Core while retaining the DOM root. */
+function getBadgeRetainedRootProps(state, hidden = false) {
+	const root = getBadgeRootProps(state);
+	if (!hidden && state.visible) return root;
+	const retained = {
+		...root,
+		hidden: true,
+		"aria-hidden": "true"
+	};
+	delete retained.role;
+	delete retained["aria-label"];
+	return retained;
+}
+//#endregion
+export { BADGE_KINDS, BADGE_PARTS, BADGE_VARIANTS, DEFAULT_BADGE_MAX_COUNT, getBadgeRetainedRootProps, getBadgeRootProps, resolveBadgeState };
+
+//# sourceMappingURL=index.js.map

package/dist/badge/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/badge/badge.ts"],"sourcesContent":["/**\n * Badge 契约 — 原型 A（无状态），core 无 machine，\n * 承载双栈共享的类型契约与纯函数状态解析（SSR-safe，无 DOM 依赖）。\n * 渲染契约：`data-scope=\"badge\"`，`data-part=\"root\"`；\n * `data-variant` / `data-kind` 摊平枚举。\n *\n * 变体 / 形态 / 部位词表以运行时常量数组为唯一事实源（类型从常量推导），__test__ 直接锁死。\n */\n\n/** 视觉变体全集：solid 强提示（默认）/ subtle 弱提示。 */\nexport const BADGE_VARIANTS = [\"solid\", \"subtle\"] as const;\n\n/** 形态全集：number 数字（默认）/ dot 纯红点。 */\nexport const BADGE_KINDS = [\"number\", \"dot\"] as const;\n\n/** Badge 各渲染部位全集（data-part 取值）。 */\nexport const BADGE_PARTS = [\"root\"] as const;\n\n/** 默认溢出阈值：数值超过时收敛为「99+」。 */\nexport const DEFAULT_BADGE_MAX_COUNT = 99;\n\nexport type BadgeVariant = (typeof BADGE_VARIANTS)[number];\nexport type BadgeKind = (typeof BADGE_KINDS)[number];\nexport type BadgePart = (typeof BADGE_PARTS)[number];\n\n/**\n * QwBadgeProps — 双栈共享的行为契约（全字段可选）。\n * 视觉完全由语义令牌驱动，组件不开放自定义色值入口。\n */\nexport interface QwBadgeProps {\n  /** 视觉变体，默认 solid；dot 形态强制 solid。 */\n  variant?: BadgeVariant;\n  /** 纯红点形态，默认 false；为 true 时优先于 count。 */\n  dot?: boolean;\n  /** 未读数量；≤0 / 非有限数值不渲染。 */\n  count?: number;\n  /** 溢出阈值，默认 99；非法值（≤0 或非整数）回退默认。 */\n  maxCount?: number;\n  /** 自定义无障碍播报文案，全量覆盖默认文案。 */\n  ariaLabel?: string;\n}\n\n/** 适配层从 locale 传入的默认播报文案。 */\nexport interface BadgeAriaTexts {\n  /** 数字形态播报模板，含 {count} 占位符。 */\n  unreadAriaTemplate: string;\n  /** 纯红点形态播报文案。 */\n  dotAria: string;\n}\n\n/** resolveBadgeState 的解析结果，适配层据此摊平渲染。 */\nexport interface ResolvedBadgeState {\n  /** 是否渲染徽标本体；false 时双栈一致返回空渲染。 */\n  visible: boolean;\n  /** 形态。 */\n  kind: BadgeKind;\n  /** 解析后的视觉变体（dot + subtle 已降级为 solid）。 */\n  variant: BadgeVariant;\n  /** 可见文本（溢出为「<阈值>+」；dot / 不可见为空串）。 */\n  label: string;\n  /** 数值是否超过阈值。 */\n  overflow: boolean;\n  /** 解析后的生效阈值。 */\n  maxCount: number;\n  /** 生效的无障碍播报文案。 */\n  ariaLabel: string;\n}\n\n/** 非法阈值（≤0 或非整数）一律回退默认值，避免非法配置导致空渲染。 */\nfunction resolveMaxCount(maxCount: number | undefined): number {\n  return typeof maxCount === \"number\" && Number.isInteger(maxCount) && maxCount > 0\n    ? maxCount\n    : DEFAULT_BADGE_MAX_COUNT;\n}\n\n/**\n * 纯函数：props + 文案 → 解析结果。\n * 规则：dot 优先于 count；dot 强制 solid；数值四舍五入；\n * ≤0 / NaN / Infinity 不渲染；溢出渲染「<阈值>+」。\n */\nexport function resolveBadgeState(\n  props: QwBadgeProps,\n  texts: BadgeAriaTexts,\n): ResolvedBadgeState {\n  const { variant = \"solid\", dot = false, count, maxCount, ariaLabel } = props;\n  const safeMax = resolveMaxCount(maxCount);\n\n  if (dot) {\n    return {\n      visible: true,\n      kind: \"dot\",\n      variant: \"solid\",\n      label: \"\",\n      overflow: false,\n      maxCount: safeMax,\n      ariaLabel: ariaLabel ?? texts.dotAria,\n    };\n  }\n\n  const normalized =\n    typeof count === \"number\" && Number.isFinite(count) && count > 0\n      ? Math.round(count)\n      : 0;\n\n  if (normalized === 0) {\n    return {\n      visible: false,\n      kind: \"number\",\n      variant,\n      label: \"\",\n      overflow: false,\n      maxCount: safeMax,\n      ariaLabel: \"\",\n    };\n  }\n\n  const overflow = normalized > safeMax;\n  const label = overflow ? `${safeMax}+` : `${normalized}`;\n  return {\n    visible: true,\n    kind: \"number\",\n    variant,\n    label,\n    overflow,\n    maxCount: safeMax,\n    ariaLabel: ariaLabel ?? texts.unreadAriaTemplate.replaceAll(\"{count}\", label),\n  };\n}\n\n/** 根元素 prop-getter 返回的 DOM 属性集。 */\nexport interface BadgeRootProps {\n  \"data-scope\": \"badge\";\n  \"data-part\": \"root\";\n  \"data-variant\": BadgeVariant;\n  \"data-kind\": BadgeKind;\n  role: \"status\";\n  \"aria-label\": string;\n}\n\n/** 根元素 prop-getter：摊平 data 状态属性 + role=\"status\" + 播报文案。 */\nexport function getBadgeRootProps(state: ResolvedBadgeState): BadgeRootProps {\n  return {\n    \"data-scope\": \"badge\",\n    \"data-part\": \"root\",\n    \"data-variant\": state.variant,\n    \"data-kind\": state.kind,\n    role: \"status\",\n    \"aria-label\": state.ariaLabel,\n  };\n}\n\n/** Passive root retained by native hosts even when no badge is visible. */\nexport interface BadgeRetainedRootProps extends Omit<BadgeRootProps, \"role\" | \"aria-label\"> {\n  role?: \"status\";\n  \"aria-label\"?: string;\n  hidden?: true;\n  \"aria-hidden\"?: \"true\";\n}\n\n/** Keep visibility and announcement decisions in Core while retaining the DOM root. */\nexport function getBadgeRetainedRootProps(state: ResolvedBadgeState, hidden = false): BadgeRetainedRootProps {\n  const root = getBadgeRootProps(state);\n  if (!hidden && state.visible) return root;\n  const retained: BadgeRetainedRootProps = { ...root, hidden: true, \"aria-hidden\": \"true\" };\n  delete retained.role;\n  delete retained[\"aria-label\"];\n  return retained;\n}\n"],"mappings":";;;;;;;;;;AAUA,MAAa,iBAAiB,CAAC,SAAS,QAAQ;;AAGhD,MAAa,cAAc,CAAC,UAAU,KAAK;;AAG3C,MAAa,cAAc,CAAC,MAAM;;AAGlC,MAAa,0BAA0B;;AAkDvC,SAAS,gBAAgB,UAAsC;CAC7D,OAAO,OAAO,aAAa,YAAY,OAAO,UAAU,QAAQ,KAAK,WAAW,IAC5E,WAAA;AAEN;;;;;;AAOA,SAAgB,kBACd,OACA,OACoB;CACpB,MAAM,EAAE,UAAU,SAAS,MAAM,OAAO,OAAO,UAAU,cAAc;CACvE,MAAM,UAAU,gBAAgB,QAAQ;CAExC,IAAI,KACF,OAAO;EACL,SAAS;EACT,MAAM;EACN,SAAS;EACT,OAAO;EACP,UAAU;EACV,UAAU;EACV,WAAW,aAAa,MAAM;CAChC;CAGF,MAAM,aACJ,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,KAAK,QAAQ,IAC3D,KAAK,MAAM,KAAK,IAChB;CAEN,IAAI,eAAe,GACjB,OAAO;EACL,SAAS;EACT,MAAM;EACN;EACA,OAAO;EACP,UAAU;EACV,UAAU;EACV,WAAW;CACb;CAGF,MAAM,WAAW,aAAa;CAC9B,MAAM,QAAQ,WAAW,GAAG,QAAQ,KAAK,GAAG;CAC5C,OAAO;EACL,SAAS;EACT,MAAM;EACN;EACA;EACA;EACA,UAAU;EACV,WAAW,aAAa,MAAM,mBAAmB,WAAW,WAAW,KAAK;CAC9E;AACF;;AAaA,SAAgB,kBAAkB,OAA2C;CAC3E,OAAO;EACL,cAAc;EACd,aAAa;EACb,gBAAgB,MAAM;EACtB,aAAa,MAAM;EACnB,MAAM;EACN,cAAc,MAAM;CACtB;AACF;;AAWA,SAAgB,0BAA0B,OAA2B,SAAS,OAA+B;CAC3G,MAAM,OAAO,kBAAkB,KAAK;CACpC,IAAI,CAAC,UAAU,MAAM,SAAS,OAAO;CACrC,MAAM,WAAmC;EAAE,GAAG;EAAM,QAAQ;EAAM,eAAe;CAAO;CACxF,OAAO,SAAS;CAChB,OAAO,SAAS;CAChB,OAAO;AACT"}

package/dist/button/button.d.ts

@@ -58,6 +58,13 @@ export interface ResolvedButtonState {
     warning?: "icon-only-block-ignored";
     type: "button" | "submit" | "reset";
 }
+/** 调用方的展开状态与控制目标；Core 只运输，不持有业务状态。 */
+export interface ButtonControlAria {
+    /** Caller-owned disclosure state; absence never implies false. */
+    "aria-expanded"?: string | boolean | null;
+    /** Caller-owned IDREF list; Core does not inspect or generate target ids. */
+    "aria-controls"?: string | null;
+}
 /** Core 生成、由适配器最后覆盖到根元素的属性。 */
 export interface ButtonRootProps {
     type: "button" | "submit" | "reset";
@@ -75,10 +82,16 @@ export interface ButtonRootProps {
     "data-block"?: "true";
     "data-loading"?: "true";
 }
+/** 显式调用方 ARIA 输入的运输输出；旧默认根属性契约保持不变。 */
+export interface ButtonControlRootProps extends ButtonRootProps {
+    "aria-expanded"?: string | boolean;
+    "aria-controls"?: string;
+}
 /** 将公开输入和内容通道归一化为唯一的跨框架状态。 */
 export declare function resolveButtonState(props?: QwButtonProps, presence?: ButtonContentPresence): ResolvedButtonState;
 /**
  * 将归一化结果转成 root 属性。空闲状态不写入 `aria-busy`，让调用方的合法
  * aria 属性继续透传；busy 状态则由 Core 作为安全属性覆盖。
  */
+export declare function getButtonRootProps(state: ResolvedButtonState, aria: ButtonControlAria | undefined): ButtonControlRootProps;
 export declare function getButtonRootProps(state: ResolvedButtonState): ButtonRootProps;

package/dist/button/index.js

@@ -76,15 +76,13 @@ function resolveButtonState(props = {}, presence = EMPTY_PRESENCE) {
 		type: props.type ?? "button"
 	};
 }
-/**
-* 将归一化结果转成 root 属性。空闲状态不写入 `aria-busy`，让调用方的合法
-* aria 属性继续透传；busy 状态则由 Core 作为安全属性覆盖。
-*/
-function getButtonRootProps(state) {
+function getButtonRootProps(state, aria = {}) {
 	return {
 		type: state.type,
 		disabled: state.effectiveDisabled,
 		...state.loading ? { "aria-busy": true } : {},
+		...aria["aria-expanded"] != null ? { "aria-expanded": aria["aria-expanded"] } : {},
+		...aria["aria-controls"] != null ? { "aria-controls": aria["aria-controls"] } : {},
 		"data-scope": "button",
 		"data-part": "root",
 		"data-variant": state.variant,

package/dist/button/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/button/button.ts"],"sourcesContent":["/**\n * Button 的跨框架行为契约。\n *\n * Button 是无状态的 Prototype A：这里仅归一化公开 props 与内容通道，React/Vue\n * 适配器不得复制 icon-only、disabled 或 block 的组合规则。\n */\n\nexport const BUTTON_VARIANTS = [\"solid\", \"soft\", \"outline\", \"ghost\", \"link\"] as const;\nexport const BUTTON_TONES = [\"brand\", \"neutral\", \"danger\"] as const;\nexport const BUTTON_SIZES = [\"mini\", \"xs\", \"s\", \"normal\", \"m\", \"l\"] as const;\nexport const BUTTON_SHAPES = [\"default\", \"square\", \"round\"] as const;\nexport const BUTTON_ICON_POSITIONS = [\"start\", \"end\"] as const;\nexport const BUTTON_PARTS = [\"root\", \"content\", \"icon\", \"label\", \"spinner\"] as const;\n\nexport type ButtonVariant = (typeof BUTTON_VARIANTS)[number];\nexport type ButtonTone = (typeof BUTTON_TONES)[number];\nexport type ButtonSize = (typeof BUTTON_SIZES)[number];\nexport type ButtonShape = (typeof BUTTON_SHAPES)[number];\nexport type ButtonIconPosition = (typeof BUTTON_ICON_POSITIONS)[number];\nexport type ButtonPart = (typeof BUTTON_PARTS)[number];\n\n/** 双栈共享的标量 props；框架特有的内容通道不进入 Core。 */\nexport interface QwButtonProps {\n  /** 视觉层级，默认 `solid`。 */\n  variant?: ButtonVariant;\n  /** 语气，默认 `brand`。 */\n  tone?: ButtonTone;\n  /** 尺寸，默认 `normal`。 */\n  size?: ButtonSize;\n  /** 外形，默认 `default`。 */\n  shape?: ButtonShape;\n  /** 图标与默认内容同时存在时的视觉位置，默认 `start`。 */\n  iconPosition?: ButtonIconPosition;\n  /** 有默认内容时撑满容器可用宽度。 */\n  block?: boolean;\n  /** 忙碌时保持内容、显示 spinner 并禁用原生 button。 */\n  loading?: boolean;\n  /** 原生禁用状态。 */\n  disabled?: boolean;\n  /** 原生 button 类型，默认 `button`。 */\n  type?: \"button\" | \"submit\" | \"reset\";\n}\n\n/** 由各框架的内容通道存在性计算；不检查 DOM 或 VNode 内容。 */\nexport interface ButtonContentPresence {\n  hasIcon: boolean;\n  hasContent: boolean;\n}\n\n/** 适配器唯一可消费的归一化结果。 */\nexport interface ResolvedButtonState {\n  variant: ButtonVariant;\n  tone: ButtonTone;\n  size: ButtonSize;\n  shape: ButtonShape;\n  iconPosition: ButtonIconPosition;\n  hasIcon: boolean;\n  hasContent: boolean;\n  iconOnly: boolean;\n  loading: boolean;\n  effectiveDisabled: boolean;\n  effectiveBlock: boolean;\n  warning?: \"icon-only-block-ignored\";\n  type: \"button\" | \"submit\" | \"reset\";\n}\n\n/** Core 生成、由适配器最后覆盖到根元素的属性。 */\nexport interface ButtonRootProps {\n  type: \"button\" | \"submit\" | \"reset\";\n  disabled: boolean;\n  \"aria-busy\"?: true;\n  \"data-scope\": \"button\";\n  \"data-part\": \"root\";\n  \"data-variant\": ButtonVariant;\n  \"data-tone\": ButtonTone;\n  \"data-size\": ButtonSize;\n  \"data-shape\": ButtonShape;\n  \"data-icon-position\": ButtonIconPosition;\n  \"data-has-icon\"?: \"true\";\n  \"data-icon-only\"?: \"true\";\n  \"data-block\"?: \"true\";\n  \"data-loading\"?: \"true\";\n}\n\nconst EMPTY_PRESENCE: ButtonContentPresence = { hasIcon: false, hasContent: false };\nconst BUILD_MODE = (import.meta as ImportMeta & { env?: { MODE?: string } }).env?.MODE;\n\n/**\n * 诊断只属于明确的开发环境。Vite 会在浏览器构建中提供 `import.meta.env.MODE`；\n * 未注入 process/env 的已发布浏览器产物默认静默，避免生产控制台噪音。\n */\nfunction isDevelopmentBuild(): boolean {\n  if (BUILD_MODE != null) return BUILD_MODE !== \"production\";\n\n  const nodeEnv = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env?.NODE_ENV;\n  return nodeEnv === \"development\" || nodeEnv === \"test\";\n}\n\n/** 将公开输入和内容通道归一化为唯一的跨框架状态。 */\nexport function resolveButtonState(\n  props: QwButtonProps = {},\n  presence: ButtonContentPresence = EMPTY_PRESENCE,\n): ResolvedButtonState {\n  const hasIcon = presence.hasIcon;\n  const hasContent = presence.hasContent;\n  const iconOnly = hasIcon && !hasContent;\n  const loading = props.loading ?? false;\n  const effectiveDisabled = (props.disabled ?? false) || loading;\n  const effectiveBlock = (props.block ?? false) && !iconOnly;\n\n  return {\n    variant: props.variant ?? \"solid\",\n    tone: props.tone ?? \"brand\",\n    size: props.size ?? \"normal\",\n    shape: props.shape ?? \"default\",\n    iconPosition: props.iconPosition ?? \"start\",\n    hasIcon,\n    hasContent,\n    iconOnly,\n    loading,\n    effectiveDisabled,\n    effectiveBlock,\n    ...(iconOnly && props.block && isDevelopmentBuild()\n      ? { warning: \"icon-only-block-ignored\" as const }\n      : {}),\n    type: props.type ?? \"button\",\n  };\n}\n\n/**\n * 将归一化结果转成 root 属性。空闲状态不写入 `aria-busy`，让调用方的合法\n * aria 属性继续透传；busy 状态则由 Core 作为安全属性覆盖。\n */\nexport function getButtonRootProps(state: ResolvedButtonState): ButtonRootProps {\n  return {\n    type: state.type,\n    disabled: state.effectiveDisabled,\n    ...(state.loading ? { \"aria-busy\": true as const } : {}),\n    \"data-scope\": \"button\",\n    \"data-part\": \"root\",\n    \"data-variant\": state.variant,\n    \"data-tone\": state.tone,\n    \"data-size\": state.size,\n    \"data-shape\": state.shape,\n    \"data-icon-position\": state.iconPosition,\n    ...(state.hasIcon ? { \"data-has-icon\": \"true\" as const } : {}),\n    ...(state.iconOnly ? { \"data-icon-only\": \"true\" as const } : {}),\n    ...(state.effectiveBlock ? { \"data-block\": \"true\" as const } : {}),\n    ...(state.loading ? { \"data-loading\": \"true\" as const } : {}),\n  };\n}\n"],"mappings":";;;;;;;AAOA,MAAa,kBAAkB;CAAC;CAAS;CAAQ;CAAW;CAAS;AAAM;AAC3E,MAAa,eAAe;CAAC;CAAS;CAAW;AAAQ;AACzD,MAAa,eAAe;CAAC;CAAQ;CAAM;CAAK;CAAU;CAAK;AAAG;AAClE,MAAa,gBAAgB;CAAC;CAAW;CAAU;AAAO;AAC1D,MAAa,wBAAwB,CAAC,SAAS,KAAK;AACpD,MAAa,eAAe;CAAC;CAAQ;CAAW;CAAQ;CAAS;AAAS;AAwE1E,MAAM,iBAAwC;CAAE,SAAS;CAAO,YAAY;AAAM;AAClF,MAAM,aAAc,OAAO,KAAkD,KAAK;;;;;AAMlF,SAAS,qBAA8B;CACrC,IAAI,cAAc,MAAM,OAAO,eAAe;CAE9C,MAAM,UAAW,WAA6D,SAAS,KAAK;CAC5F,OAAO,YAAY,iBAAiB,YAAY;AAClD;;AAGA,SAAgB,mBACd,QAAuB,CAAC,GACxB,WAAkC,gBACb;CACrB,MAAM,UAAU,SAAS;CACzB,MAAM,aAAa,SAAS;CAC5B,MAAM,WAAW,WAAW,CAAC;CAC7B,MAAM,UAAU,MAAM,WAAW;CACjC,MAAM,qBAAqB,MAAM,YAAY,UAAU;CACvD,MAAM,kBAAkB,MAAM,SAAS,UAAU,CAAC;CAElD,OAAO;EACL,SAAS,MAAM,WAAW;EAC1B,MAAM,MAAM,QAAQ;EACpB,MAAM,MAAM,QAAQ;EACpB,OAAO,MAAM,SAAS;EACtB,cAAc,MAAM,gBAAgB;EACpC;EACA;EACA;EACA;EACA;EACA;EACA,GAAI,YAAY,MAAM,SAAS,mBAAmB,IAC9C,EAAE,SAAS,0BAAmC,IAC9C,CAAC;EACL,MAAM,MAAM,QAAQ;CACtB;AACF;;;;;AAMA,SAAgB,mBAAmB,OAA6C;CAC9E,OAAO;EACL,MAAM,MAAM;EACZ,UAAU,MAAM;EAChB,GAAI,MAAM,UAAU,EAAE,aAAa,KAAc,IAAI,CAAC;EACtD,cAAc;EACd,aAAa;EACb,gBAAgB,MAAM;EACtB,aAAa,MAAM;EACnB,aAAa,MAAM;EACnB,cAAc,MAAM;EACpB,sBAAsB,MAAM;EAC5B,GAAI,MAAM,UAAU,EAAE,iBAAiB,OAAgB,IAAI,CAAC;EAC5D,GAAI,MAAM,WAAW,EAAE,kBAAkB,OAAgB,IAAI,CAAC;EAC9D,GAAI,MAAM,iBAAiB,EAAE,cAAc,OAAgB,IAAI,CAAC;EAChE,GAAI,MAAM,UAAU,EAAE,gBAAgB,OAAgB,IAAI,CAAC;CAC7D;AACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/button/button.ts"],"sourcesContent":["/**\n * Button 的跨框架行为契约。\n *\n * Button 是无状态的 Prototype A：这里仅归一化公开 props 与内容通道，React/Vue\n * 适配器不得复制 icon-only、disabled 或 block 的组合规则。\n */\n\nexport const BUTTON_VARIANTS = [\"solid\", \"soft\", \"outline\", \"ghost\", \"link\"] as const;\nexport const BUTTON_TONES = [\"brand\", \"neutral\", \"danger\"] as const;\nexport const BUTTON_SIZES = [\"mini\", \"xs\", \"s\", \"normal\", \"m\", \"l\"] as const;\nexport const BUTTON_SHAPES = [\"default\", \"square\", \"round\"] as const;\nexport const BUTTON_ICON_POSITIONS = [\"start\", \"end\"] as const;\nexport const BUTTON_PARTS = [\"root\", \"content\", \"icon\", \"label\", \"spinner\"] as const;\n\nexport type ButtonVariant = (typeof BUTTON_VARIANTS)[number];\nexport type ButtonTone = (typeof BUTTON_TONES)[number];\nexport type ButtonSize = (typeof BUTTON_SIZES)[number];\nexport type ButtonShape = (typeof BUTTON_SHAPES)[number];\nexport type ButtonIconPosition = (typeof BUTTON_ICON_POSITIONS)[number];\nexport type ButtonPart = (typeof BUTTON_PARTS)[number];\n\n/** 双栈共享的标量 props；框架特有的内容通道不进入 Core。 */\nexport interface QwButtonProps {\n  /** 视觉层级，默认 `solid`。 */\n  variant?: ButtonVariant;\n  /** 语气，默认 `brand`。 */\n  tone?: ButtonTone;\n  /** 尺寸，默认 `normal`。 */\n  size?: ButtonSize;\n  /** 外形，默认 `default`。 */\n  shape?: ButtonShape;\n  /** 图标与默认内容同时存在时的视觉位置，默认 `start`。 */\n  iconPosition?: ButtonIconPosition;\n  /** 有默认内容时撑满容器可用宽度。 */\n  block?: boolean;\n  /** 忙碌时保持内容、显示 spinner 并禁用原生 button。 */\n  loading?: boolean;\n  /** 原生禁用状态。 */\n  disabled?: boolean;\n  /** 原生 button 类型，默认 `button`。 */\n  type?: \"button\" | \"submit\" | \"reset\";\n}\n\n/** 由各框架的内容通道存在性计算；不检查 DOM 或 VNode 内容。 */\nexport interface ButtonContentPresence {\n  hasIcon: boolean;\n  hasContent: boolean;\n}\n\n/** 适配器唯一可消费的归一化结果。 */\nexport interface ResolvedButtonState {\n  variant: ButtonVariant;\n  tone: ButtonTone;\n  size: ButtonSize;\n  shape: ButtonShape;\n  iconPosition: ButtonIconPosition;\n  hasIcon: boolean;\n  hasContent: boolean;\n  iconOnly: boolean;\n  loading: boolean;\n  effectiveDisabled: boolean;\n  effectiveBlock: boolean;\n  warning?: \"icon-only-block-ignored\";\n  type: \"button\" | \"submit\" | \"reset\";\n}\n\n/** 调用方的展开状态与控制目标；Core 只运输，不持有业务状态。 */\nexport interface ButtonControlAria {\n  /** Caller-owned disclosure state; absence never implies false. */\n  \"aria-expanded\"?: string | boolean | null;\n  /** Caller-owned IDREF list; Core does not inspect or generate target ids. */\n  \"aria-controls\"?: string | null;\n}\n\n/** Core 生成、由适配器最后覆盖到根元素的属性。 */\nexport interface ButtonRootProps {\n  type: \"button\" | \"submit\" | \"reset\";\n  disabled: boolean;\n  \"aria-busy\"?: true;\n  \"data-scope\": \"button\";\n  \"data-part\": \"root\";\n  \"data-variant\": ButtonVariant;\n  \"data-tone\": ButtonTone;\n  \"data-size\": ButtonSize;\n  \"data-shape\": ButtonShape;\n  \"data-icon-position\": ButtonIconPosition;\n  \"data-has-icon\"?: \"true\";\n  \"data-icon-only\"?: \"true\";\n  \"data-block\"?: \"true\";\n  \"data-loading\"?: \"true\";\n}\n\n/** 显式调用方 ARIA 输入的运输输出；旧默认根属性契约保持不变。 */\nexport interface ButtonControlRootProps extends ButtonRootProps {\n  \"aria-expanded\"?: string | boolean;\n  \"aria-controls\"?: string;\n}\n\nconst EMPTY_PRESENCE: ButtonContentPresence = { hasIcon: false, hasContent: false };\nconst BUILD_MODE = (import.meta as ImportMeta & { env?: { MODE?: string } }).env?.MODE;\n\n/**\n * 诊断只属于明确的开发环境。Vite 会在浏览器构建中提供 `import.meta.env.MODE`；\n * 未注入 process/env 的已发布浏览器产物默认静默，避免生产控制台噪音。\n */\nfunction isDevelopmentBuild(): boolean {\n  if (BUILD_MODE != null) return BUILD_MODE !== \"production\";\n\n  const nodeEnv = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env?.NODE_ENV;\n  return nodeEnv === \"development\" || nodeEnv === \"test\";\n}\n\n/** 将公开输入和内容通道归一化为唯一的跨框架状态。 */\nexport function resolveButtonState(\n  props: QwButtonProps = {},\n  presence: ButtonContentPresence = EMPTY_PRESENCE,\n): ResolvedButtonState {\n  const hasIcon = presence.hasIcon;\n  const hasContent = presence.hasContent;\n  const iconOnly = hasIcon && !hasContent;\n  const loading = props.loading ?? false;\n  const effectiveDisabled = (props.disabled ?? false) || loading;\n  const effectiveBlock = (props.block ?? false) && !iconOnly;\n\n  return {\n    variant: props.variant ?? \"solid\",\n    tone: props.tone ?? \"brand\",\n    size: props.size ?? \"normal\",\n    shape: props.shape ?? \"default\",\n    iconPosition: props.iconPosition ?? \"start\",\n    hasIcon,\n    hasContent,\n    iconOnly,\n    loading,\n    effectiveDisabled,\n    effectiveBlock,\n    ...(iconOnly && props.block && isDevelopmentBuild()\n      ? { warning: \"icon-only-block-ignored\" as const }\n      : {}),\n    type: props.type ?? \"button\",\n  };\n}\n\n/**\n * 将归一化结果转成 root 属性。空闲状态不写入 `aria-busy`，让调用方的合法\n * aria 属性继续透传；busy 状态则由 Core 作为安全属性覆盖。\n */\nexport function getButtonRootProps(state: ResolvedButtonState, aria: ButtonControlAria | undefined): ButtonControlRootProps;\nexport function getButtonRootProps(state: ResolvedButtonState): ButtonRootProps;\nexport function getButtonRootProps(state: ResolvedButtonState, aria: ButtonControlAria = {}): ButtonControlRootProps {\n  return {\n    type: state.type,\n    disabled: state.effectiveDisabled,\n    ...(state.loading ? { \"aria-busy\": true as const } : {}),\n    ...(aria[\"aria-expanded\"] != null ? { \"aria-expanded\": aria[\"aria-expanded\"] } : {}),\n    ...(aria[\"aria-controls\"] != null ? { \"aria-controls\": aria[\"aria-controls\"] } : {}),\n    \"data-scope\": \"button\",\n    \"data-part\": \"root\",\n    \"data-variant\": state.variant,\n    \"data-tone\": state.tone,\n    \"data-size\": state.size,\n    \"data-shape\": state.shape,\n    \"data-icon-position\": state.iconPosition,\n    ...(state.hasIcon ? { \"data-has-icon\": \"true\" as const } : {}),\n    ...(state.iconOnly ? { \"data-icon-only\": \"true\" as const } : {}),\n    ...(state.effectiveBlock ? { \"data-block\": \"true\" as const } : {}),\n    ...(state.loading ? { \"data-loading\": \"true\" as const } : {}),\n  };\n}\n"],"mappings":";;;;;;;AAOA,MAAa,kBAAkB;CAAC;CAAS;CAAQ;CAAW;CAAS;AAAM;AAC3E,MAAa,eAAe;CAAC;CAAS;CAAW;AAAQ;AACzD,MAAa,eAAe;CAAC;CAAQ;CAAM;CAAK;CAAU;CAAK;AAAG;AAClE,MAAa,gBAAgB;CAAC;CAAW;CAAU;AAAO;AAC1D,MAAa,wBAAwB,CAAC,SAAS,KAAK;AACpD,MAAa,eAAe;CAAC;CAAQ;CAAW;CAAQ;CAAS;AAAS;AAsF1E,MAAM,iBAAwC;CAAE,SAAS;CAAO,YAAY;AAAM;AAClF,MAAM,aAAc,OAAO,KAAkD,KAAK;;;;;AAMlF,SAAS,qBAA8B;CACrC,IAAI,cAAc,MAAM,OAAO,eAAe;CAE9C,MAAM,UAAW,WAA6D,SAAS,KAAK;CAC5F,OAAO,YAAY,iBAAiB,YAAY;AAClD;;AAGA,SAAgB,mBACd,QAAuB,CAAC,GACxB,WAAkC,gBACb;CACrB,MAAM,UAAU,SAAS;CACzB,MAAM,aAAa,SAAS;CAC5B,MAAM,WAAW,WAAW,CAAC;CAC7B,MAAM,UAAU,MAAM,WAAW;CACjC,MAAM,qBAAqB,MAAM,YAAY,UAAU;CACvD,MAAM,kBAAkB,MAAM,SAAS,UAAU,CAAC;CAElD,OAAO;EACL,SAAS,MAAM,WAAW;EAC1B,MAAM,MAAM,QAAQ;EACpB,MAAM,MAAM,QAAQ;EACpB,OAAO,MAAM,SAAS;EACtB,cAAc,MAAM,gBAAgB;EACpC;EACA;EACA;EACA;EACA;EACA;EACA,GAAI,YAAY,MAAM,SAAS,mBAAmB,IAC9C,EAAE,SAAS,0BAAmC,IAC9C,CAAC;EACL,MAAM,MAAM,QAAQ;CACtB;AACF;AAQA,SAAgB,mBAAmB,OAA4B,OAA0B,CAAC,GAA2B;CACnH,OAAO;EACL,MAAM,MAAM;EACZ,UAAU,MAAM;EAChB,GAAI,MAAM,UAAU,EAAE,aAAa,KAAc,IAAI,CAAC;EACtD,GAAI,KAAK,oBAAoB,OAAO,EAAE,iBAAiB,KAAK,iBAAiB,IAAI,CAAC;EAClF,GAAI,KAAK,oBAAoB,OAAO,EAAE,iBAAiB,KAAK,iBAAiB,IAAI,CAAC;EAClF,cAAc;EACd,aAAa;EACb,gBAAgB,MAAM;EACtB,aAAa,MAAM;EACnB,aAAa,MAAM;EACnB,cAAc,MAAM;EACpB,sBAAsB,MAAM;EAC5B,GAAI,MAAM,UAAU,EAAE,iBAAiB,OAAgB,IAAI,CAAC;EAC5D,GAAI,MAAM,WAAW,EAAE,kBAAkB,OAAgB,IAAI,CAAC;EAC9D,GAAI,MAAM,iBAAiB,EAAE,cAAc,OAAgB,IAAI,CAAC;EAChE,GAAI,MAAM,UAAU,EAAE,gBAAgB,OAAgB,IAAI,CAAC;CAC7D;AACF"}

package/dist/calendar/calendar.d.ts

@@ -0,0 +1,100 @@
+import { type Machine, type Service } from "@zag-js/core";
+import type { NormalizeProps, PropTypes } from "@zag-js/types";
+export declare const CALENDAR_PARTS: readonly ["root", "header", "previous-trigger", "heading", "next-trigger", "grid", "row", "column-header", "cell", "day"];
+export type CalendarSelectionMode = "single" | "multiple" | "range";
+export interface CalendarDate {
+    year: number;
+    month: number;
+    day: number;
+}
+export interface CalendarRange {
+    start: CalendarDate | null;
+    end: CalendarDate | null;
+}
+export type CalendarValue = CalendarDate | CalendarDate[] | CalendarRange | null;
+export interface CalendarValueChangeDetails {
+    value: CalendarValue;
+}
+export interface QwCalendarProps {
+    id?: string;
+    label?: string;
+    locale?: string;
+    dir?: "ltr" | "rtl";
+    mode?: CalendarSelectionMode;
+    value?: CalendarValue;
+    defaultValue?: CalendarValue;
+    min?: CalendarDate;
+    max?: CalendarDate;
+    disabledDates?: readonly CalendarDate[];
+    weekStartsOn?: number;
+    today?: CalendarDate;
+    onValueChange?: (details: CalendarValueChangeDetails) => void;
+}
+export declare function isValidCalendarDate(value: unknown): value is CalendarDate;
+export declare function daysInMonth(year: number, month: number): number;
+export declare function toDateKey(date: CalendarDate): string;
+export declare function compareCalendarDates(a: CalendarDate, b: CalendarDate): number;
+export declare function addCalendarDays(date: CalendarDate, amount: number): CalendarDate;
+export declare function addCalendarMonths(date: CalendarDate, amount: number): CalendarDate;
+export declare function normalizeCalendarValue(value: CalendarValue | undefined, mode: CalendarSelectionMode): CalendarValue;
+export declare function isCalendarDateDisabled(date: CalendarDate, props: Pick<QwCalendarProps, "min" | "max" | "disabledDates">): boolean;
+export interface CalendarDay {
+    date: CalendarDate;
+    key: string;
+    label: string;
+    day: number;
+    outside: boolean;
+    disabled: boolean;
+    selected: boolean;
+    inRange: boolean;
+    today: boolean;
+    focused: boolean;
+}
+export declare function getCalendarMonthDays(view: CalendarDate, props: QwCalendarProps, value: CalendarValue, focused: CalendarDate): CalendarDay[];
+export declare function selectCalendarDate(value: CalendarValue, date: CalendarDate, mode: CalendarSelectionMode): CalendarValue;
+export declare function createCalendarProps(props: QwCalendarProps): QwCalendarProps;
+export interface QwCalendarSchema {
+    props: QwCalendarProps;
+    context: {
+        value: CalendarValue;
+        view: CalendarDate;
+        focused: CalendarDate;
+    };
+    state: "idle";
+    action: "select" | "focus" | "navigate" | "today";
+    event: {
+        type: "SELECT";
+        date: CalendarDate;
+    } | {
+        type: "FOCUS";
+        date: CalendarDate;
+    } | {
+        type: "NAVIGATE";
+        months: number;
+    } | {
+        type: "TODAY";
+    };
+}
+export type QwCalendarMachine = Machine<QwCalendarSchema>;
+export type QwCalendarService = Service<QwCalendarSchema>;
+export declare const calendarMachine: QwCalendarMachine;
+export interface QwCalendarApi<T extends PropTypes = PropTypes> {
+    label: string;
+    heading: string;
+    weekdays: string[];
+    weeks: CalendarDay[][];
+    value: CalendarValue;
+    focusDate(date: CalendarDate): void;
+    selectDate(date: CalendarDate): void;
+    getRootProps(): T["element"];
+    getHeaderProps(): T["element"];
+    getPreviousTriggerProps(): T["button"];
+    getHeadingProps(): T["element"];
+    getNextTriggerProps(): T["button"];
+    getGridProps(): T["element"];
+    getRowProps(): T["element"];
+    getColumnHeaderProps(index: number): T["element"];
+    getCellProps(day: CalendarDay): T["element"];
+    getDayProps(day: CalendarDay): T["button"];
+}
+export declare function connectCalendar<T extends PropTypes>(service: QwCalendarService, normalize: NormalizeProps<T>): QwCalendarApi<T>;

package/dist/calendar/index.d.ts

@@ -0,0 +1 @@
+export * from "./calendar.js";

package/dist/calendar/index.js

@@ -0,0 +1,2 @@
+import { a as compareCalendarDates, c as daysInMonth, d as isValidCalendarDate, f as normalizeCalendarValue, i as calendarMachine, l as getCalendarMonthDays, m as toDateKey, n as addCalendarDays, o as connectCalendar, p as selectCalendarDate, r as addCalendarMonths, s as createCalendarProps, t as CALENDAR_PARTS, u as isCalendarDateDisabled } from "../calendar-CmpK3stz.js";
+export { CALENDAR_PARTS, addCalendarDays, addCalendarMonths, calendarMachine, compareCalendarDates, connectCalendar, createCalendarProps, daysInMonth, getCalendarMonthDays, isCalendarDateDisabled, isValidCalendarDate, normalizeCalendarValue, selectCalendarDate, toDateKey };