@qw-ui/core 0.3.0-next.40 → 0.3.0-next.42

package/dist/stepper/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/stepper/stepper.ts"],"sourcesContent":["/**\n * Stepper 加减（数量步进器）的跨框架行为契约。\n *\n * Stepper 是原型 A（无状态 Core 状态机）：交互由原生 `<button>` 承担，\n * core 只负责数值归一化、边界 clamp、按钮可用性计算与 prop-getter 生成。\n */\n\n/** 尺寸全集：s = 15×15px，m = 18×18px。 */\nexport const STEPPER_SIZES = [\"s\", \"m\"] as const;\n\n/** 形态变体全集：default = 裸按钮组合，bordered = 带边框卡片形态。 */\nexport const STEPPER_VARIANTS = [\"default\", \"bordered\"] as const;\n\n/** 渲染部位全集（data-part 取值）。 */\nexport const STEPPER_PARTS = [\"root\", \"decrement\", \"value\", \"increment\"] as const;\n\nexport type StepperSize = (typeof STEPPER_SIZES)[number];\nexport type StepperVariant = (typeof STEPPER_VARIANTS)[number];\nexport type StepperPart = (typeof STEPPER_PARTS)[number];\n\n/**\n * QwStepperProps — 双栈共享的行为契约（全字段可选）。\n * `value` 未传时走非受控模式，由适配层管理内部数值。\n */\nexport interface QwStepperProps {\n  /** 受控值。未传时走非受控模式。 */\n  value?: number;\n  /** 非受控初始值，默认 `0`（若 `min > 0` 则取 `min`）。仅在 `value` 未传时生效。 */\n  defaultValue?: number;\n  /** 数值变化回调，参数为新的 value。 */\n  onChange?: (value: number) => void;\n  /** 最小值。 */\n  min?: number;\n  /** 最大值。 */\n  max?: number;\n  /** 步长，默认 1；非法值（非正数）回退到 1。 */\n  step?: number;\n  /** 禁用状态。 */\n  disabled?: boolean;\n  /** 按钮尺寸，默认 m。 */\n  size?: StepperSize;\n  /** 形态变体，默认 default；bordered 为带边框卡片形态。 */\n  variant?: StepperVariant;\n  /** 减量按钮 aria-label，默认「减少」（适配层可注入语言包取值）。 */\n  decrementLabel?: string;\n  /** 增量按钮 aria-label，默认「增加」（适配层可注入语言包取值）。 */\n  incrementLabel?: string;\n}\n\n/** 适配器唯一可消费的归一化结果。 */\nexport interface ResolvedStepperState {\n  /** 当前数值（已按 min/max clamp）。 */\n  value: number;\n  /** 最小值。 */\n  min: number | undefined;\n  /** 最大值。 */\n  max: number | undefined;\n  /** 实际生效的步长。 */\n  step: number;\n  /** 是否整体禁用。 */\n  disabled: boolean;\n  /** 按钮尺寸。 */\n  size: StepperSize;\n  /** 形态变体。 */\n  variant: StepperVariant;\n  /** 选中态：value > min 派生，仅影响 bordered 视觉。 */\n  selected: boolean;\n  /** 减量按钮是否可用。 */\n  canDecrement: boolean;\n  /** 增量按钮是否可用。 */\n  canIncrement: boolean;\n  /** 减量按钮 aria-label（per-prop > 适配层注入 > 内置「减少」）。 */\n  decrementLabel: string;\n  /** 增量按钮 aria-label（per-prop > 适配层注入 > 内置「增加」）。 */\n  incrementLabel: string;\n}\n\n/** 将数值约束在 [min, max] 范围内；边界未定义时跳过对应侧。 */\nexport function clampStepperValue(\n  value: number,\n  min: number | undefined,\n  max: number | undefined,\n): number {\n  let result = value;\n  if (typeof min === \"number\" && !Number.isNaN(min)) {\n    result = Math.max(result, min);\n  }\n  if (typeof max === \"number\" && !Number.isNaN(max)) {\n    result = Math.min(result, max);\n  }\n  return result;\n}\n\n/** 规范化 step：仅接受正数，否则回退到 1。 */\nfunction normalizeStepperStep(step: number | undefined): number {\n  return typeof step === \"number\" && step > 0 && !Number.isNaN(step) ? step : 1;\n}\n\n/** 规范化 min：未指定时按规格默认 0（不做负数默认值）。 */\nfunction normalizeStepperMin(min: number | undefined): number {\n  return typeof min === \"number\" && !Number.isNaN(min) ? min : 0;\n}\n\n/** 将公开输入归一化为唯一的跨框架状态。 */\nexport function resolveStepperState(props: QwStepperProps = {}): ResolvedStepperState {\n  const min = normalizeStepperMin(props.min);\n  const max = props.max;\n  const step = normalizeStepperStep(props.step);\n  const disabled = props.disabled ?? false;\n  const variant = props.variant ?? \"default\";\n\n  const isControlled = props.value !== undefined;\n  const rawValue = isControlled\n    ? props.value!\n    : (props.defaultValue ?? min);\n\n  const value = clampStepperValue(rawValue, min, max);\n\n  const size = props.size ?? \"m\";\n\n  const selected = value > min;\n\n  const canDecrement = !disabled && value > min;\n  const canIncrement = !disabled && (typeof max !== \"number\" || value < max);\n\n  return {\n    value,\n    min,\n    max,\n    step,\n    disabled,\n    size,\n    variant,\n    selected,\n    canDecrement,\n    canIncrement,\n    decrementLabel: props.decrementLabel ?? \"减少\",\n    incrementLabel: props.incrementLabel ?? \"增加\",\n  };\n}\n\n/** 计算减量后的目标值（已 clamp）。 */\nexport function getStepperDecrementValue(state: ResolvedStepperState): number {\n  return clampStepperValue(state.value - state.step, state.min, state.max);\n}\n\n/** 计算增量后的目标值（已 clamp）。 */\nexport function getStepperIncrementValue(state: ResolvedStepperState): number {\n  return clampStepperValue(state.value + state.step, state.min, state.max);\n}\n\n/** Core 生成、由适配器最后覆盖到根元素的属性。 */\nexport interface StepperRootProps {\n  role: \"group\";\n  \"data-scope\": \"stepper\";\n  \"data-part\": \"root\";\n  \"data-size\": StepperSize;\n  \"data-variant\": StepperVariant;\n  \"data-selected\"?: \"true\";\n  \"data-disabled\"?: \"true\";\n}\n\n/** 生成根容器属性。 */\nexport function getStepperRootProps(state: ResolvedStepperState): StepperRootProps {\n  return {\n    role: \"group\",\n    \"data-scope\": \"stepper\",\n    \"data-part\": \"root\",\n    \"data-size\": state.size,\n    \"data-variant\": state.variant,\n    ...(state.selected ? { \"data-selected\": \"true\" as const } : {}),\n    ...(state.disabled ? { \"data-disabled\": \"true\" as const } : {}),\n  };\n}\n\n/** 减量按钮属性。 */\nexport interface StepperDecrementProps {\n  type: \"button\";\n  disabled: boolean;\n  \"data-scope\": \"stepper\";\n  \"data-part\": \"decrement\";\n  \"aria-label\": string;\n  \"data-disabled\"?: \"true\";\n}\n\n/** 生成减量按钮属性。 */\nexport function getStepperDecrementProps(state: ResolvedStepperState): StepperDecrementProps {\n  const disabled = !state.canDecrement;\n  return {\n    type: \"button\",\n    disabled,\n    \"data-scope\": \"stepper\",\n    \"data-part\": \"decrement\",\n    \"aria-label\": state.decrementLabel,\n    ...(disabled ? { \"data-disabled\": \"true\" as const } : {}),\n  };\n}\n\n/** 增量按钮属性。 */\nexport interface StepperIncrementProps {\n  type: \"button\";\n  disabled: boolean;\n  \"data-scope\": \"stepper\";\n  \"data-part\": \"increment\";\n  \"aria-label\": string;\n  \"data-disabled\"?: \"true\";\n}\n\n/** 生成增量按钮属性。 */\nexport function getStepperIncrementProps(state: ResolvedStepperState): StepperIncrementProps {\n  const disabled = !state.canIncrement;\n  return {\n    type: \"button\",\n    disabled,\n    \"data-scope\": \"stepper\",\n    \"data-part\": \"increment\",\n    \"aria-label\": state.incrementLabel,\n    ...(disabled ? { \"data-disabled\": \"true\" as const } : {}),\n  };\n}\n\n/** 数值展示属性。 */\nexport interface StepperValueProps {\n  \"data-scope\": \"stepper\";\n  \"data-part\": \"value\";\n  \"aria-live\": \"polite\";\n  \"aria-atomic\": \"true\";\n}\n\n/** 生成数值展示属性。 */\nexport function getStepperValueProps(): StepperValueProps {\n  return {\n    \"data-scope\": \"stepper\",\n    \"data-part\": \"value\",\n    \"aria-live\": \"polite\",\n    \"aria-atomic\": \"true\",\n  };\n}\n"],"mappings":";;;;;;;;AAQA,MAAa,gBAAgB,CAAC,KAAK,GAAG;;AAGtC,MAAa,mBAAmB,CAAC,WAAW,UAAU;;AAGtD,MAAa,gBAAgB;CAAC;CAAQ;CAAa;CAAS;AAAW;;AAgEvE,SAAgB,kBACd,OACA,KACA,KACQ;CACR,IAAI,SAAS;CACb,IAAI,OAAO,QAAQ,YAAY,CAAC,OAAO,MAAM,GAAG,GAC9C,SAAS,KAAK,IAAI,QAAQ,GAAG;CAE/B,IAAI,OAAO,QAAQ,YAAY,CAAC,OAAO,MAAM,GAAG,GAC9C,SAAS,KAAK,IAAI,QAAQ,GAAG;CAE/B,OAAO;AACT;;AAGA,SAAS,qBAAqB,MAAkC;CAC9D,OAAO,OAAO,SAAS,YAAY,OAAO,KAAK,CAAC,OAAO,MAAM,IAAI,IAAI,OAAO;AAC9E;;AAGA,SAAS,oBAAoB,KAAiC;CAC5D,OAAO,OAAO,QAAQ,YAAY,CAAC,OAAO,MAAM,GAAG,IAAI,MAAM;AAC/D;;AAGA,SAAgB,oBAAoB,QAAwB,CAAC,GAAyB;CACpF,MAAM,MAAM,oBAAoB,MAAM,GAAG;CACzC,MAAM,MAAM,MAAM;CAClB,MAAM,OAAO,qBAAqB,MAAM,IAAI;CAC5C,MAAM,WAAW,MAAM,YAAY;CACnC,MAAM,UAAU,MAAM,WAAW;CAOjC,MAAM,QAAQ,kBALO,MAAM,UAAU,KAAA,IAEjC,MAAM,QACL,MAAM,gBAAgB,KAEe,KAAK,GAAG;CASlD,OAAO;EACL;EACA;EACA;EACA;EACA;EACA,MAbW,MAAM,QAAQ;EAczB;EACA,UAbe,QAAQ;EAcvB,cAZmB,CAAC,YAAY,QAAQ;EAaxC,cAZmB,CAAC,aAAa,OAAO,QAAQ,YAAY,QAAQ;EAapE,gBAAgB,MAAM,kBAAkB;EACxC,gBAAgB,MAAM,kBAAkB;CAC1C;AACF;;AAGA,SAAgB,yBAAyB,OAAqC;CAC5E,OAAO,kBAAkB,MAAM,QAAQ,MAAM,MAAM,MAAM,KAAK,MAAM,GAAG;AACzE;;AAGA,SAAgB,yBAAyB,OAAqC;CAC5E,OAAO,kBAAkB,MAAM,QAAQ,MAAM,MAAM,MAAM,KAAK,MAAM,GAAG;AACzE;;AAcA,SAAgB,oBAAoB,OAA+C;CACjF,OAAO;EACL,MAAM;EACN,cAAc;EACd,aAAa;EACb,aAAa,MAAM;EACnB,gBAAgB,MAAM;EACtB,GAAI,MAAM,WAAW,EAAE,iBAAiB,OAAgB,IAAI,CAAC;EAC7D,GAAI,MAAM,WAAW,EAAE,iBAAiB,OAAgB,IAAI,CAAC;CAC/D;AACF;;AAaA,SAAgB,yBAAyB,OAAoD;CAC3F,MAAM,WAAW,CAAC,MAAM;CACxB,OAAO;EACL,MAAM;EACN;EACA,cAAc;EACd,aAAa;EACb,cAAc,MAAM;EACpB,GAAI,WAAW,EAAE,iBAAiB,OAAgB,IAAI,CAAC;CACzD;AACF;;AAaA,SAAgB,yBAAyB,OAAoD;CAC3F,MAAM,WAAW,CAAC,MAAM;CACxB,OAAO;EACL,MAAM;EACN;EACA,cAAc;EACd,aAAa;EACb,cAAc,MAAM;EACpB,GAAI,WAAW,EAAE,iBAAiB,OAAgB,IAAI,CAAC;CACzD;AACF;;AAWA,SAAgB,uBAA0C;CACxD,OAAO;EACL,cAAc;EACd,aAAa;EACb,aAAa;EACb,eAAe;CACjB;AACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/stepper/stepper.ts"],"sourcesContent":["/**\n * Stepper 加减（数量步进器）的跨框架行为契约。\n *\n * 交互由原生 `<button>` 承担。数值归一化、边界、按钮可用性、非受控模型、\n * 受控判断和取消都在 Core；适配层只运输点击并重绘。\n */\n\n/** 尺寸全集：s = 15×15px，m = 18×18px。 */\nexport const STEPPER_SIZES = [\"s\", \"m\"] as const;\n\n/** 形态变体全集：default = 裸按钮组合，bordered = 带边框卡片形态。 */\nexport const STEPPER_VARIANTS = [\"default\", \"bordered\"] as const;\n\n/** 渲染部位全集（data-part 取值）。 */\nexport const STEPPER_PARTS = [\"root\", \"decrement\", \"value\", \"increment\"] as const;\n\nexport type StepperSize = (typeof STEPPER_SIZES)[number];\nexport type StepperVariant = (typeof STEPPER_VARIANTS)[number];\nexport type StepperPart = (typeof STEPPER_PARTS)[number];\n\n/**\n * QwStepperProps — 跨框架行为契约（全字段可选）。\n * `value` 未传时走非受控模式，由 `createStepperModel` 持有内部数值。\n */\nexport interface QwStepperProps {\n  /** 受控值。未传时走非受控模式。 */\n  value?: number;\n  /** 非受控初始值，默认 `0`（若 `min > 0` 则取 `min`）。仅在 `value` 未传时生效。 */\n  defaultValue?: number;\n  /** 数值变化回调，参数为新的 value。 */\n  onChange?: (value: number) => void;\n  /** 最小值。 */\n  min?: number;\n  /** 最大值。 */\n  max?: number;\n  /** 步长，默认 1；非法值（非正数）回退到 1。 */\n  step?: number;\n  /** 禁用状态。 */\n  disabled?: boolean;\n  /** 按钮尺寸，默认 m。 */\n  size?: StepperSize;\n  /** 形态变体，默认 default；bordered 为带边框卡片形态。 */\n  variant?: StepperVariant;\n  /** 减量按钮 aria-label，默认「减少」（适配层可注入语言包取值）。 */\n  decrementLabel?: string;\n  /** 增量按钮 aria-label，默认「增加」（适配层可注入语言包取值）。 */\n  incrementLabel?: string;\n}\n\n/** 适配器唯一可消费的归一化结果。 */\nexport interface ResolvedStepperState {\n  /** 当前数值（已按 min/max clamp）。 */\n  value: number;\n  /** 最小值。 */\n  min: number | undefined;\n  /** 最大值。 */\n  max: number | undefined;\n  /** 实际生效的步长。 */\n  step: number;\n  /** 是否整体禁用。 */\n  disabled: boolean;\n  /** 按钮尺寸。 */\n  size: StepperSize;\n  /** 形态变体。 */\n  variant: StepperVariant;\n  /** 选中态：value > min 派生，仅影响 bordered 视觉。 */\n  selected: boolean;\n  /** 减量按钮是否可用。 */\n  canDecrement: boolean;\n  /** 增量按钮是否可用。 */\n  canIncrement: boolean;\n  /** 减量按钮 aria-label（per-prop > 适配层注入 > 内置「减少」）。 */\n  decrementLabel: string;\n  /** 增量按钮 aria-label（per-prop > 适配层注入 > 内置「增加」）。 */\n  incrementLabel: string;\n}\n\n/** 将数值约束在 [min, max] 范围内；边界未定义时跳过对应侧。 */\nexport function clampStepperValue(\n  value: number,\n  min: number | undefined,\n  max: number | undefined,\n): number {\n  let result = value;\n  if (typeof min === \"number\" && !Number.isNaN(min)) {\n    result = Math.max(result, min);\n  }\n  if (typeof max === \"number\" && !Number.isNaN(max)) {\n    result = Math.min(result, max);\n  }\n  return result;\n}\n\n/** 规范化 step：仅接受正数，否则回退到 1。 */\nfunction normalizeStepperStep(step: number | undefined): number {\n  return typeof step === \"number\" && step > 0 && !Number.isNaN(step) ? step : 1;\n}\n\n/** 规范化 min：未指定时按规格默认 0（不做负数默认值）。 */\nfunction normalizeStepperMin(min: number | undefined): number {\n  return typeof min === \"number\" && !Number.isNaN(min) ? min : 0;\n}\n\n/** 将公开输入归一化为唯一的跨框架状态。 */\nexport function resolveStepperState(props: QwStepperProps = {}): ResolvedStepperState {\n  const min = normalizeStepperMin(props.min);\n  const max = props.max;\n  const step = normalizeStepperStep(props.step);\n  const disabled = props.disabled ?? false;\n  const variant = props.variant ?? \"default\";\n\n  const isControlled = props.value !== undefined;\n  const rawValue = isControlled\n    ? props.value!\n    : (props.defaultValue ?? min);\n\n  const value = clampStepperValue(rawValue, min, max);\n\n  const size = props.size ?? \"m\";\n\n  const selected = value > min;\n\n  const canDecrement = !disabled && value > min;\n  const canIncrement = !disabled && (typeof max !== \"number\" || value < max);\n\n  return {\n    value,\n    min,\n    max,\n    step,\n    disabled,\n    size,\n    variant,\n    selected,\n    canDecrement,\n    canIncrement,\n    decrementLabel: props.decrementLabel ?? \"减少\",\n    incrementLabel: props.incrementLabel ?? \"增加\",\n  };\n}\n\n/** 计算减量后的目标值（已 clamp）。 */\nexport function getStepperDecrementValue(state: ResolvedStepperState): number {\n  return clampStepperValue(state.value - state.step, state.min, state.max);\n}\n\n/** 计算增量后的目标值（已 clamp）。 */\nexport function getStepperIncrementValue(state: ResolvedStepperState): number {\n  return clampStepperValue(state.value + state.step, state.min, state.max);\n}\n\n/** Core 生成、由适配器最后覆盖到根元素的属性。 */\nexport interface StepperRootProps {\n  role: \"group\";\n  \"data-scope\": \"stepper\";\n  \"data-part\": \"root\";\n  \"data-size\": StepperSize;\n  \"data-variant\": StepperVariant;\n  \"data-selected\"?: \"true\";\n  \"data-disabled\"?: \"true\";\n}\n\n/** 生成根容器属性。 */\nexport function getStepperRootProps(state: ResolvedStepperState): StepperRootProps {\n  return {\n    role: \"group\",\n    \"data-scope\": \"stepper\",\n    \"data-part\": \"root\",\n    \"data-size\": state.size,\n    \"data-variant\": state.variant,\n    ...(state.selected ? { \"data-selected\": \"true\" as const } : {}),\n    ...(state.disabled ? { \"data-disabled\": \"true\" as const } : {}),\n  };\n}\n\n/** 减量按钮属性。 */\nexport interface StepperDecrementProps {\n  type: \"button\";\n  disabled: boolean;\n  \"data-scope\": \"stepper\";\n  \"data-part\": \"decrement\";\n  \"aria-label\": string;\n  \"data-disabled\"?: \"true\";\n}\n\n/** 生成减量按钮属性。 */\nexport function getStepperDecrementProps(state: ResolvedStepperState): StepperDecrementProps {\n  const disabled = !state.canDecrement;\n  return {\n    type: \"button\",\n    disabled,\n    \"data-scope\": \"stepper\",\n    \"data-part\": \"decrement\",\n    \"aria-label\": state.decrementLabel,\n    ...(disabled ? { \"data-disabled\": \"true\" as const } : {}),\n  };\n}\n\n/** 增量按钮属性。 */\nexport interface StepperIncrementProps {\n  type: \"button\";\n  disabled: boolean;\n  \"data-scope\": \"stepper\";\n  \"data-part\": \"increment\";\n  \"aria-label\": string;\n  \"data-disabled\"?: \"true\";\n}\n\n/** 生成增量按钮属性。 */\nexport function getStepperIncrementProps(state: ResolvedStepperState): StepperIncrementProps {\n  const disabled = !state.canIncrement;\n  return {\n    type: \"button\",\n    disabled,\n    \"data-scope\": \"stepper\",\n    \"data-part\": \"increment\",\n    \"aria-label\": state.incrementLabel,\n    ...(disabled ? { \"data-disabled\": \"true\" as const } : {}),\n  };\n}\n\n/** 数值展示属性。 */\nexport interface StepperValueProps {\n  \"data-scope\": \"stepper\";\n  \"data-part\": \"value\";\n  \"aria-live\": \"polite\";\n  \"aria-atomic\": \"true\";\n}\n\n/** 生成数值展示属性。 */\nexport function getStepperValueProps(): StepperValueProps {\n  return {\n    \"data-scope\": \"stepper\",\n    \"data-part\": \"value\",\n    \"aria-live\": \"polite\",\n    \"aria-atomic\": \"true\",\n  };\n}\n\n/** 一次步进方向。适配层只运输激活，不预算下一个数值。 */\nexport type StepperDirection = \"increment\" | \"decrement\";\n\n/**\n * 取消标记。Core 在微任务里读 `defaultPrevented`，宿主冒泡阶段的 preventDefault 能赶上。\n * 传入点击事件本身即可。\n */\nexport interface StepperStepNotice {\n  readonly defaultPrevented: boolean;\n}\n\n/** 受控时是调用方原值，非受控时是内部模型。 */\nexport interface StepperModelSnapshot {\n  value: number;\n}\n\nexport interface StepperModelOptions {\n  /** 未被取消的步进提交后调用，供适配层重绘。提交时读取当前属性。 */\n  onCommit?: () => void;\n  /** 非受控重连快照。仅当创建时未传 `value`，且 `value` 为 number 时覆盖初始模型。 */\n  snapshot?: { value?: unknown };\n}\n\nexport interface StepperModel {\n  /** 当前画面状态（数值已 clamp）。 */\n  readonly state: ResolvedStepperState;\n  /** 受控：调用方原值（可以未经 clamp）。非受控：内部模型。 */\n  readonly modelValue: number;\n  readonly controlled: boolean;\n  update(props: QwStepperProps): void;\n  request(direction: StepperDirection, notice: StepperStepNotice): void;\n  /** 恢复接收步进。stop 之前已经排队的请求仍然作废。 */\n  start(): void;\n  /** 作废尚未提交的步进。 */\n  stop(): void;\n  snapshot(): StepperModelSnapshot;\n}\n\nfunction seedStepperModel(props: QwStepperProps, snapshot: StepperModelOptions[\"snapshot\"]): number {\n  if (props.value === undefined && typeof snapshot?.value === \"number\") return snapshot.value;\n  if (typeof props.defaultValue === \"number\") return props.defaultValue;\n  if (typeof props.min === \"number\") return props.min;\n  return 0;\n}\n\n/**\n * 步进器的行为源。下一步在提交时按当时的模型计算：同一次任务里连续激活会依次累计，\n * 而不是共用渲染当时预算的同一个 next。取消只看提交时的 defaultPrevented、禁用和 stop。\n */\nexport function createStepperModel(props: QwStepperProps = {}, options: StepperModelOptions = {}): StepperModel {\n  let current = props;\n  let internal = seedStepperModel(props, options.snapshot);\n  let generation = 0;\n  let stopped = false;\n  const controlledNow = () => current.value !== undefined;\n  const view = (): ResolvedStepperState => resolveStepperState({\n    ...current,\n    value: controlledNow() ? current.value : internal,\n  });\n  const readModel = () => (controlledNow() ? current.value ?? internal : internal);\n\n  return {\n    get state() { return view(); },\n    get modelValue() { return readModel(); },\n    get controlled() { return controlledNow(); },\n    update(next) { current = next; },\n    request(direction, notice) {\n      if (stopped || view().disabled) return;\n      const seen = generation;\n      queueMicrotask(() => {\n        if (stopped || seen !== generation || notice.defaultPrevented) return;\n        const resolved = view();\n        if (resolved.disabled) return;\n        const next = direction === \"increment\" ? getStepperIncrementValue(resolved) : getStepperDecrementValue(resolved);\n        if (!controlledNow()) internal = next;\n        current.onChange?.(next);\n        options.onCommit?.();\n      });\n    },\n    start() { stopped = false; },\n    stop() { stopped = true; generation += 1; },\n    snapshot() { return { value: readModel() }; },\n  };\n}\n"],"mappings":"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"}

package/dist/stepper/stepper.d.ts

@@ -1,8 +1,8 @@
 /**
  * Stepper 加减（数量步进器）的跨框架行为契约。
  *
- * Stepper 是原型 A（无状态 Core 状态机）：交互由原生 `<button>` 承担，
- * core 只负责数值归一化、边界 clamp、按钮可用性计算与 prop-getter 生成。
+ * 交互由原生 `<button>` 承担。数值归一化、边界、按钮可用性、非受控模型、
+ * 受控判断和取消都在 Core；适配层只运输点击并重绘。
  */
 /** 尺寸全集：s = 15×15px，m = 18×18px。 */
 export declare const STEPPER_SIZES: readonly ["s", "m"];
@@ -14,8 +14,8 @@ export type StepperSize = (typeof STEPPER_SIZES)[number];
 export type StepperVariant = (typeof STEPPER_VARIANTS)[number];
 export type StepperPart = (typeof STEPPER_PARTS)[number];
 /**
- * QwStepperProps — 双栈共享的行为契约（全字段可选）。
- * `value` 未传时走非受控模式，由适配层管理内部数值。
+ * QwStepperProps — 跨框架行为契约（全字段可选）。
+ * `value` 未传时走非受控模式，由 `createStepperModel` 持有内部数值。
  */
 export interface QwStepperProps {
     /** 受控值。未传时走非受控模式。 */
@@ -119,3 +119,43 @@ export interface StepperValueProps {
 }
 /** 生成数值展示属性。 */
 export declare function getStepperValueProps(): StepperValueProps;
+/** 一次步进方向。适配层只运输激活，不预算下一个数值。 */
+export type StepperDirection = "increment" | "decrement";
+/**
+ * 取消标记。Core 在微任务里读 `defaultPrevented`，宿主冒泡阶段的 preventDefault 能赶上。
+ * 传入点击事件本身即可。
+ */
+export interface StepperStepNotice {
+    readonly defaultPrevented: boolean;
+}
+/** 受控时是调用方原值，非受控时是内部模型。 */
+export interface StepperModelSnapshot {
+    value: number;
+}
+export interface StepperModelOptions {
+    /** 未被取消的步进提交后调用，供适配层重绘。提交时读取当前属性。 */
+    onCommit?: () => void;
+    /** 非受控重连快照。仅当创建时未传 `value`，且 `value` 为 number 时覆盖初始模型。 */
+    snapshot?: {
+        value?: unknown;
+    };
+}
+export interface StepperModel {
+    /** 当前画面状态（数值已 clamp）。 */
+    readonly state: ResolvedStepperState;
+    /** 受控：调用方原值（可以未经 clamp）。非受控：内部模型。 */
+    readonly modelValue: number;
+    readonly controlled: boolean;
+    update(props: QwStepperProps): void;
+    request(direction: StepperDirection, notice: StepperStepNotice): void;
+    /** 恢复接收步进。stop 之前已经排队的请求仍然作废。 */
+    start(): void;
+    /** 作废尚未提交的步进。 */
+    stop(): void;
+    snapshot(): StepperModelSnapshot;
+}
+/**
+ * 步进器的行为源。下一步在提交时按当时的模型计算：同一次任务里连续激活会依次累计，
+ * 而不是共用渲染当时预算的同一个 next。取消只看提交时的 defaultPrevented、禁用和 stop。
+ */
+export declare function createStepperModel(props?: QwStepperProps, options?: StepperModelOptions): StepperModel;

package/dist/steps/index.d.ts

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

package/dist/steps/index.js

@@ -0,0 +1,72 @@
+//#region src/steps/steps.ts
+/** Ordered sequence contract; business navigation stays with the caller. */
+const STEP_STATUSES = [
+	"wait",
+	"process",
+	"finish",
+	"error"
+];
+const STEPS_ORIENTATIONS = ["horizontal", "vertical"];
+function resolveStepsState(props) {
+	const input = props.current ?? 0;
+	const current = Number.isFinite(input) ? Math.floor(input) : 0;
+	return {
+		current,
+		orientation: props.orientation ?? "horizontal",
+		items: props.items.map((item, index) => ({
+			...item,
+			index,
+			current: index === current,
+			status: item.status ?? (index < current ? "finish" : index === current ? "process" : "wait")
+		}))
+	};
+}
+function getStepProps(item) {
+	return {
+		"data-scope": "steps",
+		"data-part": "item",
+		"data-value": item.id,
+		"data-status": item.status,
+		...item.current ? { "aria-current": "step" } : {}
+	};
+}
+/** Native semantics are chosen in Core so all integrations render the same controls. */
+function getStepControlTag(props, item) {
+	return props.interactive ? item.href ? "a" : "button" : "span";
+}
+function getStepControlProps(props, item) {
+	return {
+		"data-scope": "steps",
+		"data-part": "control",
+		...item.current ? { "aria-current": "step" } : {},
+		...item.href ? item.disabled ? {
+			role: "link",
+			"aria-disabled": true,
+			tabIndex: -1
+		} : { href: item.href } : {
+			type: "button",
+			disabled: item.disabled ?? false
+		},
+		onClick(event) {
+			if (!props.interactive || item.disabled) {
+				event.preventDefault();
+				return;
+			}
+			props.onStepChange?.({
+				id: item.id,
+				index: item.index,
+				current: resolveStepsState(props).current
+			});
+		}
+	};
+}
+/** Optional interaction moves current semantics to the native control without changing legacy getStepProps. */
+function getStepsItemProps(props, item) {
+	const result = getStepProps(item);
+	if (props.interactive) delete result["aria-current"];
+	return result;
+}
+//#endregion
+export { STEPS_ORIENTATIONS, STEP_STATUSES, getStepControlProps, getStepControlTag, getStepProps, getStepsItemProps, resolveStepsState };
+
+//# sourceMappingURL=index.js.map

package/dist/steps/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/steps/steps.ts"],"sourcesContent":["/** Ordered sequence contract; business navigation stays with the caller. */\nexport const STEP_STATUSES = [\"wait\", \"process\", \"finish\", \"error\"] as const;\nexport const STEPS_ORIENTATIONS = [\"horizontal\", \"vertical\"] as const;\nexport type StepStatus = (typeof STEP_STATUSES)[number];\nexport type StepsOrientation = (typeof STEPS_ORIENTATIONS)[number];\nexport interface StepItem {\n  id: string;\n  title: string;\n  description?: string;\n  status?: StepStatus;\n  /** Beta: native link destination in interactive mode. */\n  href?: string;\n  disabled?: boolean;\n}\nexport interface QwStepsProps {\n  items: readonly StepItem[];\n  /** Zero-based active index; negative means not started. */\n  current?: number;\n  orientation?: StepsOrientation;\n  /** Beta: opt into native controls; current remains caller-owned. */\n  interactive?: boolean;\n  onStepChange?: (details: StepChangeDetails) => void;\n}\nexport interface ResolvedStepItem extends StepItem {\n  index: number;\n  status: StepStatus;\n  current: boolean;\n}\nexport interface ResolvedStepsState {\n  current: number;\n  orientation: StepsOrientation;\n  items: ResolvedStepItem[];\n}\nexport interface StepProps {\n  \"data-scope\": \"steps\";\n  \"data-part\": \"item\";\n  \"data-value\": string;\n  \"data-status\": StepStatus;\n  \"aria-current\"?: \"step\";\n}\nexport function resolveStepsState(props: QwStepsProps): ResolvedStepsState {\n  const input = props.current ?? 0;\n  const current = Number.isFinite(input) ? Math.floor(input) : 0;\n  return { current, orientation: props.orientation ?? \"horizontal\", items: props.items.map((item, index) => ({\n    ...item, index, current: index === current,\n    status: item.status ?? (index < current ? \"finish\" : index === current ? \"process\" : \"wait\"),\n  })) };\n}\nexport function getStepProps(item: ResolvedStepItem): StepProps {\n  return { \"data-scope\": \"steps\", \"data-part\": \"item\", \"data-value\": item.id, \"data-status\": item.status,\n    ...(item.current ? { \"aria-current\": \"step\" as const } : {}) };\n}\n\n/** An activation request; accepting or refusing it belongs to the caller. */\nexport interface StepChangeDetails { id: string; index: number; current: number }\nexport interface StepControlProps {\n  \"data-scope\": \"steps\";\n  \"data-part\": \"control\";\n  \"aria-current\"?: \"step\";\n  \"aria-disabled\"?: true;\n  disabled?: boolean;\n  href?: string;\n  role?: \"link\";\n  tabIndex?: number;\n  type?: \"button\";\n  onClick: (event: { preventDefault(): void }) => void;\n}\n/** Native semantics are chosen in Core so all integrations render the same controls. */\nexport function getStepControlTag(props: QwStepsProps, item: StepItem): \"a\" | \"button\" | \"span\" {\n  return props.interactive ? item.href ? \"a\" : \"button\" : \"span\";\n}\nexport function getStepControlProps(props: QwStepsProps, item: ResolvedStepItem): StepControlProps {\n  return {\n    \"data-scope\": \"steps\", \"data-part\": \"control\",\n    ...(item.current ? { \"aria-current\": \"step\" as const } : {}),\n    ...(item.href ? item.disabled ? { role: \"link\" as const, \"aria-disabled\": true as const, tabIndex: -1 } : { href: item.href }\n      : { type: \"button\" as const, disabled: item.disabled ?? false }),\n    onClick(event) {\n      if (!props.interactive || item.disabled) { event.preventDefault(); return; }\n      props.onStepChange?.({ id: item.id, index: item.index, current: resolveStepsState(props).current });\n    },\n  };\n}\n\n/** Optional interaction moves current semantics to the native control without changing legacy getStepProps. */\nexport function getStepsItemProps(props: QwStepsProps, item: ResolvedStepItem): StepProps {\n  const result = getStepProps(item);\n  if (props.interactive) delete result[\"aria-current\"];\n  return result;\n}\n"],"mappings":";;AACA,MAAa,gBAAgB;CAAC;CAAQ;CAAW;CAAU;AAAO;AAClE,MAAa,qBAAqB,CAAC,cAAc,UAAU;AAsC3D,SAAgB,kBAAkB,OAAyC;CACzE,MAAM,QAAQ,MAAM,WAAW;CAC/B,MAAM,UAAU,OAAO,SAAS,KAAK,IAAI,KAAK,MAAM,KAAK,IAAI;CAC7D,OAAO;EAAE;EAAS,aAAa,MAAM,eAAe;EAAc,OAAO,MAAM,MAAM,KAAK,MAAM,WAAW;GACzG,GAAG;GAAM;GAAO,SAAS,UAAU;GACnC,QAAQ,KAAK,WAAW,QAAQ,UAAU,WAAW,UAAU,UAAU,YAAY;EACvF,EAAE;CAAE;AACN;AACA,SAAgB,aAAa,MAAmC;CAC9D,OAAO;EAAE,cAAc;EAAS,aAAa;EAAQ,cAAc,KAAK;EAAI,eAAe,KAAK;EAC9F,GAAI,KAAK,UAAU,EAAE,gBAAgB,OAAgB,IAAI,CAAC;CAAG;AACjE;;AAiBA,SAAgB,kBAAkB,OAAqB,MAAyC;CAC9F,OAAO,MAAM,cAAc,KAAK,OAAO,MAAM,WAAW;AAC1D;AACA,SAAgB,oBAAoB,OAAqB,MAA0C;CACjG,OAAO;EACL,cAAc;EAAS,aAAa;EACpC,GAAI,KAAK,UAAU,EAAE,gBAAgB,OAAgB,IAAI,CAAC;EAC1D,GAAI,KAAK,OAAO,KAAK,WAAW;GAAE,MAAM;GAAiB,iBAAiB;GAAe,UAAU;EAAG,IAAI,EAAE,MAAM,KAAK,KAAK,IACxH;GAAE,MAAM;GAAmB,UAAU,KAAK,YAAY;EAAM;EAChE,QAAQ,OAAO;GACb,IAAI,CAAC,MAAM,eAAe,KAAK,UAAU;IAAE,MAAM,eAAe;IAAG;GAAQ;GAC3E,MAAM,eAAe;IAAE,IAAI,KAAK;IAAI,OAAO,KAAK;IAAO,SAAS,kBAAkB,KAAK,CAAC,CAAC;GAAQ,CAAC;EACpG;CACF;AACF;;AAGA,SAAgB,kBAAkB,OAAqB,MAAmC;CACxF,MAAM,SAAS,aAAa,IAAI;CAChC,IAAI,MAAM,aAAa,OAAO,OAAO;CACrC,OAAO;AACT"}

package/dist/steps/steps.d.ts

@@ -0,0 +1,67 @@
+/** Ordered sequence contract; business navigation stays with the caller. */
+export declare const STEP_STATUSES: readonly ["wait", "process", "finish", "error"];
+export declare const STEPS_ORIENTATIONS: readonly ["horizontal", "vertical"];
+export type StepStatus = (typeof STEP_STATUSES)[number];
+export type StepsOrientation = (typeof STEPS_ORIENTATIONS)[number];
+export interface StepItem {
+    id: string;
+    title: string;
+    description?: string;
+    status?: StepStatus;
+    /** Beta: native link destination in interactive mode. */
+    href?: string;
+    disabled?: boolean;
+}
+export interface QwStepsProps {
+    items: readonly StepItem[];
+    /** Zero-based active index; negative means not started. */
+    current?: number;
+    orientation?: StepsOrientation;
+    /** Beta: opt into native controls; current remains caller-owned. */
+    interactive?: boolean;
+    onStepChange?: (details: StepChangeDetails) => void;
+}
+export interface ResolvedStepItem extends StepItem {
+    index: number;
+    status: StepStatus;
+    current: boolean;
+}
+export interface ResolvedStepsState {
+    current: number;
+    orientation: StepsOrientation;
+    items: ResolvedStepItem[];
+}
+export interface StepProps {
+    "data-scope": "steps";
+    "data-part": "item";
+    "data-value": string;
+    "data-status": StepStatus;
+    "aria-current"?: "step";
+}
+export declare function resolveStepsState(props: QwStepsProps): ResolvedStepsState;
+export declare function getStepProps(item: ResolvedStepItem): StepProps;
+/** An activation request; accepting or refusing it belongs to the caller. */
+export interface StepChangeDetails {
+    id: string;
+    index: number;
+    current: number;
+}
+export interface StepControlProps {
+    "data-scope": "steps";
+    "data-part": "control";
+    "aria-current"?: "step";
+    "aria-disabled"?: true;
+    disabled?: boolean;
+    href?: string;
+    role?: "link";
+    tabIndex?: number;
+    type?: "button";
+    onClick: (event: {
+        preventDefault(): void;
+    }) => void;
+}
+/** Native semantics are chosen in Core so all integrations render the same controls. */
+export declare function getStepControlTag(props: QwStepsProps, item: StepItem): "a" | "button" | "span";
+export declare function getStepControlProps(props: QwStepsProps, item: ResolvedStepItem): StepControlProps;
+/** Optional interaction moves current semantics to the native control without changing legacy getStepProps. */
+export declare function getStepsItemProps(props: QwStepsProps, item: ResolvedStepItem): StepProps;

package/dist/sticky/index.d.ts

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

package/dist/sticky/index.js

@@ -0,0 +1,145 @@
+import { createMachine } from "@zag-js/core";
+//#region src/sticky/sticky.ts
+/** Edge of the scrollport the element sticks to. */
+const STICKY_POSITIONS = ["top", "bottom"];
+/** Stable DOM parts shared by every adapter. */
+const STICKY_PARTS = ["root"];
+function resolveStickyState(props = {}) {
+	return {
+		offset: typeof props.offset === "number" && Number.isFinite(props.offset) && props.offset > 0 ? props.offset : 0,
+		position: STICKY_POSITIONS.includes(props.position) ? props.position : "top",
+		scrollContainer: typeof props.scrollContainer === "string" && props.scrollContainer.trim() ? props.scrollContainer : void 0
+	};
+}
+/**
+* A native sticky box that has scrolled is stuck exactly when it sits on its offset line;
+* an unstuck box moves with the content, so the coincidence tolerance is sub-pixel.
+*/
+function computeStickyStuck(state, m) {
+	return state.position === "top" ? m.scrolledBefore > 0 && Math.abs(m.rootStart - (m.portStart + state.offset)) < 1 : m.scrolledAfter > 0 && Math.abs(m.rootEnd - (m.portEnd - state.offset)) < 1;
+}
+function createStickyProps(props = {}) {
+	if (props.id !== void 0 && (typeof props.id !== "string" || !props.id.trim())) throw new TypeError("Sticky requires a nonempty instance id when provided");
+	return { ...props };
+}
+const rootId = (scope) => `sticky:${scope.id}`;
+const live = (service) => resolveStickyState({
+	offset: service.prop("offset"),
+	position: service.prop("position"),
+	scrollContainer: service.prop("scrollContainer")
+});
+/** Platform boundary: resolve the scrollport and measure. Only called from the client effect. */
+function measure(root, state) {
+	const win = root.ownerDocument.defaultView;
+	const port = state.scrollContainer ? root.parentElement?.closest(state.scrollContainer) ?? null : null;
+	const rect = root.getBoundingClientRect();
+	if (port) {
+		const box = port.getBoundingClientRect();
+		return computeStickyStuck(state, {
+			rootStart: rect.top,
+			rootEnd: rect.bottom,
+			portStart: box.top + port.clientTop,
+			portEnd: box.top + port.clientTop + port.clientHeight,
+			scrolledBefore: port.scrollTop,
+			scrolledAfter: port.scrollHeight - port.clientHeight - port.scrollTop
+		});
+	}
+	const doc = root.ownerDocument.documentElement, y = win?.scrollY ?? doc.scrollTop, height = win?.innerHeight ?? doc.clientHeight;
+	return computeStickyStuck(state, {
+		rootStart: rect.top,
+		rootEnd: rect.bottom,
+		portStart: 0,
+		portEnd: height,
+		scrolledBefore: y,
+		scrolledAfter: doc.scrollHeight - height - y
+	});
+}
+/** Core owns listening, rAF throttling, transition-only notification and cleanup. */
+const stickyMachine = createMachine({
+	props: ({ props }) => createStickyProps(props),
+	initialState: () => "ready",
+	states: { ready: {} },
+	context: ({ bindable, prop }) => ({ stuck: bindable(() => ({
+		defaultValue: false,
+		onChange(stuck) {
+			prop("onStuckChange")?.({ stuck });
+		}
+	})) }),
+	refs: () => ({ schedule: null }),
+	watch({ track, prop, action }) {
+		track([
+			() => prop("offset"),
+			() => prop("position"),
+			() => prop("scrollContainer")
+		], () => action(["remeasure"]));
+	},
+	on: { "STUCK.SET": { actions: ["setStuck"] } },
+	effects: ["trackStuck"],
+	implementations: {
+		actions: {
+			setStuck(params) {
+				if (params.event.type === "STUCK.SET") params.context.set("stuck", params.event.stuck);
+			},
+			remeasure(params) {
+				params.refs.get("schedule")?.();
+			}
+		},
+		effects: { trackStuck({ scope, prop, send, context, refs }) {
+			const root = scope.getById(rootId(scope)), win = root?.ownerDocument.defaultView;
+			if (!root || !win) return;
+			let frame = 0, port = null, disposed = false;
+			const attach = () => {
+				const state = live({ prop });
+				const next = state.scrollContainer ? root.parentElement?.closest(state.scrollContainer) ?? win : win;
+				if (next === port) return;
+				port?.removeEventListener("scroll", schedule);
+				port = next;
+				port.addEventListener("scroll", schedule, { passive: true });
+			};
+			const run = () => {
+				frame = 0;
+				if (disposed || !root.isConnected) return;
+				attach();
+				const stuck = measure(root, live({ prop }));
+				if (stuck !== context.get("stuck")) send({
+					type: "STUCK.SET",
+					stuck
+				});
+			};
+			function schedule() {
+				if (!frame && !disposed) frame = win.requestAnimationFrame(run);
+			}
+			attach();
+			win.addEventListener("resize", schedule, { passive: true });
+			schedule();
+			refs.set("schedule", schedule);
+			return () => {
+				disposed = true;
+				refs.set("schedule", null);
+				if (frame) win.cancelAnimationFrame(frame);
+				port?.removeEventListener("scroll", schedule);
+				win.removeEventListener("resize", schedule);
+			};
+		} }
+	}
+});
+function connectSticky(service, normalize) {
+	const state = live(service), stuck = service.context.get("stuck");
+	return {
+		stuck,
+		position: state.position,
+		offset: state.offset,
+		getRootProps: () => normalize.element({
+			"data-scope": "sticky",
+			"data-part": "root",
+			id: rootId(service.scope),
+			"data-position": state.position,
+			"data-stuck": stuck ? "true" : void 0,
+			style: { "--qw-sticky-offset": `${state.offset}px` }
+		})
+	};
+}
+//#endregion
+export { STICKY_PARTS, STICKY_POSITIONS, computeStickyStuck, connectSticky, createStickyProps, resolveStickyState, stickyMachine };
+
+//# sourceMappingURL=index.js.map

package/dist/sticky/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/sticky/sticky.ts"],"sourcesContent":["import { createMachine, type Machine, type Service } from \"@zag-js/core\";\nimport type { NormalizeProps, PropTypes } from \"@zag-js/types\";\n\n/** Edge of the scrollport the element sticks to. */\nexport const STICKY_POSITIONS = [\"top\", \"bottom\"] as const;\n/** Stable DOM parts shared by every adapter. */\nexport const STICKY_PARTS = [\"root\"] as const;\nexport type StickyPosition = (typeof STICKY_POSITIONS)[number];\nexport interface StickyStuckChangeDetails { stuck: boolean }\n/** SSR-safe input shared by all adapters. Positioning is native `position: sticky`. */\nexport interface QwStickyProps {\n  /** Page-unique instance identity; adapters generate one when omitted. */\n  id?: string;\n  /** Distance in CSS pixels from the chosen scrollport edge; nonfinite/negative is 0. */\n  offset?: number;\n  position?: StickyPosition;\n  /** CSS selector of the scrolling ancestor, matched with `closest()`; omitted means the viewport. */\n  scrollContainer?: string;\n  /** Called only when the measured stuck state changes. */\n  onStuckChange?: (details: StickyStuckChangeDetails) => void;\n}\nexport interface ResolvedStickyState { offset: number; position: StickyPosition; scrollContainer: string | undefined }\nexport function resolveStickyState(props: QwStickyProps = {}): ResolvedStickyState {\n  const offset = typeof props.offset === \"number\" && Number.isFinite(props.offset) && props.offset > 0 ? props.offset : 0;\n  return { offset, position: STICKY_POSITIONS.includes(props.position!) ? props.position! : \"top\",\n    scrollContainer: typeof props.scrollContainer === \"string\" && props.scrollContainer.trim() ? props.scrollContainer : undefined };\n}\n/** Geometry snapshot read by the platform effect. `before`/`after` are remaining scroll distances. */\nexport interface StickyMeasurement {\n  rootStart: number; rootEnd: number; portStart: number; portEnd: number; scrolledBefore: number; scrolledAfter: number;\n}\n/**\n * A native sticky box that has scrolled is stuck exactly when it sits on its offset line;\n * an unstuck box moves with the content, so the coincidence tolerance is sub-pixel.\n */\nexport function computeStickyStuck(state: ResolvedStickyState, m: StickyMeasurement): boolean {\n  return state.position === \"top\"\n    ? m.scrolledBefore > 0 && Math.abs(m.rootStart - (m.portStart + state.offset)) < 1\n    : m.scrolledAfter > 0 && Math.abs(m.rootEnd - (m.portEnd - state.offset)) < 1;\n}\nexport function createStickyProps(props: QwStickyProps = {}): QwStickyProps {\n  if (props.id !== undefined && (typeof props.id !== \"string\" || !props.id.trim())) throw new TypeError(\"Sticky requires a nonempty instance id when provided\");\n  return { ...props };\n}\n\nexport interface QwStickySchema {\n  props: QwStickyProps;\n  context: { stuck: boolean };\n  refs: { schedule: (() => void) | null };\n  state: \"ready\";\n  action: \"setStuck\" | \"remeasure\";\n  effect: \"trackStuck\";\n  event: { type: \"STUCK.SET\"; stuck: boolean };\n}\nexport type QwStickyMachine = Machine<QwStickySchema>;\nexport type QwStickyService = Service<QwStickySchema>;\nconst rootId = (scope: QwStickyService[\"scope\"]) => `sticky:${scope.id}`;\nconst live = (service: Pick<QwStickyService, \"prop\">) => resolveStickyState({ offset: service.prop(\"offset\"), position: service.prop(\"position\"), scrollContainer: service.prop(\"scrollContainer\") });\n\n/** Platform boundary: resolve the scrollport and measure. Only called from the client effect. */\nfunction measure(root: HTMLElement, state: ResolvedStickyState): boolean {\n  const win = root.ownerDocument.defaultView;\n  const port = state.scrollContainer ? root.parentElement?.closest<HTMLElement>(state.scrollContainer) ?? null : null;\n  const rect = root.getBoundingClientRect();\n  if (port) {\n    const box = port.getBoundingClientRect();\n    return computeStickyStuck(state, { rootStart: rect.top, rootEnd: rect.bottom, portStart: box.top + port.clientTop, portEnd: box.top + port.clientTop + port.clientHeight,\n      scrolledBefore: port.scrollTop, scrolledAfter: port.scrollHeight - port.clientHeight - port.scrollTop });\n  }\n  const doc = root.ownerDocument.documentElement, y = win?.scrollY ?? doc.scrollTop, height = win?.innerHeight ?? doc.clientHeight;\n  return computeStickyStuck(state, { rootStart: rect.top, rootEnd: rect.bottom, portStart: 0, portEnd: height, scrolledBefore: y, scrolledAfter: doc.scrollHeight - height - y });\n}\n\n/** Core owns listening, rAF throttling, transition-only notification and cleanup. */\nexport const stickyMachine: QwStickyMachine = createMachine<QwStickySchema>({\n  props: ({ props }) => createStickyProps(props), initialState: () => \"ready\", states: { ready: {} },\n  context: ({ bindable, prop }) => ({\n    stuck: bindable(() => ({ defaultValue: false, onChange(stuck) { prop(\"onStuckChange\")?.({ stuck }); } })),\n  }),\n  refs: () => ({ schedule: null }),\n  watch({ track, prop, action }) { track([() => prop(\"offset\"), () => prop(\"position\"), () => prop(\"scrollContainer\")], () => action([\"remeasure\"])); },\n  on: { \"STUCK.SET\": { actions: [\"setStuck\"] } },\n  effects: [\"trackStuck\"],\n  implementations: {\n    actions: {\n      setStuck(params) { if (params.event.type === \"STUCK.SET\") params.context.set(\"stuck\", params.event.stuck); },\n      remeasure(params) { params.refs.get(\"schedule\")?.(); },\n    },\n    effects: { trackStuck({ scope, prop, send, context, refs }) {\n      const root = scope.getById<HTMLElement>(rootId(scope)), win = root?.ownerDocument.defaultView;\n      if (!root || !win) return;\n      let frame = 0, port: EventTarget | null = null, disposed = false;\n      const attach = () => {\n        const state = live({ prop });\n        const next: EventTarget = state.scrollContainer ? root.parentElement?.closest(state.scrollContainer) ?? win : win;\n        if (next === port) return;\n        port?.removeEventListener(\"scroll\", schedule); port = next; port.addEventListener(\"scroll\", schedule, { passive: true });\n      };\n      const run = () => { frame = 0; if (disposed || !root.isConnected) return; attach(); const stuck = measure(root, live({ prop })); if (stuck !== context.get(\"stuck\")) send({ type: \"STUCK.SET\", stuck }); };\n      function schedule() { if (!frame && !disposed) frame = win!.requestAnimationFrame(run); }\n      attach(); win.addEventListener(\"resize\", schedule, { passive: true }); schedule();\n      refs.set(\"schedule\", schedule);\n      return () => { disposed = true; refs.set(\"schedule\", null); if (frame) win.cancelAnimationFrame(frame); port?.removeEventListener(\"scroll\", schedule); win.removeEventListener(\"resize\", schedule); };\n    } },\n  },\n});\n\nexport interface QwStickyApi<T extends PropTypes = PropTypes> {\n  stuck: boolean; position: StickyPosition; offset: number;\n  getRootProps(): T[\"element\"];\n}\nexport function connectSticky<T extends PropTypes>(service: QwStickyService, normalize: NormalizeProps<T>): QwStickyApi<T> {\n  const state = live(service), stuck = service.context.get(\"stuck\");\n  return { stuck, position: state.position, offset: state.offset,\n    getRootProps: () => normalize.element({ \"data-scope\": \"sticky\", \"data-part\": \"root\", id: rootId(service.scope), \"data-position\": state.position, \"data-stuck\": stuck ? \"true\" : undefined,\n      style: { \"--qw-sticky-offset\": `${state.offset}px` } }) };\n}\n"],"mappings":"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"}

package/dist/sticky/sticky.d.ts

@@ -0,0 +1,70 @@
+import { type Machine, type Service } from "@zag-js/core";
+import type { NormalizeProps, PropTypes } from "@zag-js/types";
+/** Edge of the scrollport the element sticks to. */
+export declare const STICKY_POSITIONS: readonly ["top", "bottom"];
+/** Stable DOM parts shared by every adapter. */
+export declare const STICKY_PARTS: readonly ["root"];
+export type StickyPosition = (typeof STICKY_POSITIONS)[number];
+export interface StickyStuckChangeDetails {
+    stuck: boolean;
+}
+/** SSR-safe input shared by all adapters. Positioning is native `position: sticky`. */
+export interface QwStickyProps {
+    /** Page-unique instance identity; adapters generate one when omitted. */
+    id?: string;
+    /** Distance in CSS pixels from the chosen scrollport edge; nonfinite/negative is 0. */
+    offset?: number;
+    position?: StickyPosition;
+    /** CSS selector of the scrolling ancestor, matched with `closest()`; omitted means the viewport. */
+    scrollContainer?: string;
+    /** Called only when the measured stuck state changes. */
+    onStuckChange?: (details: StickyStuckChangeDetails) => void;
+}
+export interface ResolvedStickyState {
+    offset: number;
+    position: StickyPosition;
+    scrollContainer: string | undefined;
+}
+export declare function resolveStickyState(props?: QwStickyProps): ResolvedStickyState;
+/** Geometry snapshot read by the platform effect. `before`/`after` are remaining scroll distances. */
+export interface StickyMeasurement {
+    rootStart: number;
+    rootEnd: number;
+    portStart: number;
+    portEnd: number;
+    scrolledBefore: number;
+    scrolledAfter: number;
+}
+/**
+ * A native sticky box that has scrolled is stuck exactly when it sits on its offset line;
+ * an unstuck box moves with the content, so the coincidence tolerance is sub-pixel.
+ */
+export declare function computeStickyStuck(state: ResolvedStickyState, m: StickyMeasurement): boolean;
+export declare function createStickyProps(props?: QwStickyProps): QwStickyProps;
+export interface QwStickySchema {
+    props: QwStickyProps;
+    context: {
+        stuck: boolean;
+    };
+    refs: {
+        schedule: (() => void) | null;
+    };
+    state: "ready";
+    action: "setStuck" | "remeasure";
+    effect: "trackStuck";
+    event: {
+        type: "STUCK.SET";
+        stuck: boolean;
+    };
+}
+export type QwStickyMachine = Machine<QwStickySchema>;
+export type QwStickyService = Service<QwStickySchema>;
+/** Core owns listening, rAF throttling, transition-only notification and cleanup. */
+export declare const stickyMachine: QwStickyMachine;
+export interface QwStickyApi<T extends PropTypes = PropTypes> {
+    stuck: boolean;
+    position: StickyPosition;
+    offset: number;
+    getRootProps(): T["element"];
+}
+export declare function connectSticky<T extends PropTypes>(service: QwStickyService, normalize: NormalizeProps<T>): QwStickyApi<T>;

package/dist/swipe-action/index.d.ts

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