hys-ui 0.4.0 → 0.6.0

package/dist/types/composables/animatedNumber.d.ts

@@ -0,0 +1,220 @@
+import type { StyleValue, VNodeChild } from "vue";
+import type { HysNumberAnimation, HysNumberAnimationPresets, HysNumberDigitAnimations } from "./numberAnimation";
+export type HysNumberValue = number | string;
+export type HysNumberDirection = "up" | "down" | "none";
+export type HysNumberStatus = "idle" | "delayed" | "playing" | "paused" | "stopped" | "finished";
+export type HysNumberEasing = "linear" | "ease-in" | "ease-out" | "ease-in-out" | "spring" | "bounce" | readonly [number, number, number, number] | ((progress: number) => number);
+export type HysNumberInterrupt = "retarget" | "restart" | "queue" | "snap";
+export type HysNumberTrigger = "mount" | "activate" | "update" | "manual" | "click" | "hover" | "visible";
+export type HysNumberEffect = "count" | "odometer" | "wheel" | "flip" | "slot" | "random" | "scramble" | "fade" | "scale" | "bounce" | "spring" | "slide" | "blur" | "appear" | "disappear" | "flash" | "highlight" | "gradient";
+export type HysNumberRounding = "half-up" | "half-even" | "floor" | "ceil" | "trunc";
+export type HysNumberFormat = "decimal" | "percent" | "currency" | "scientific";
+export interface HysNumberInterpolationContext {
+    from: HysNumberValue;
+    to: HysNumberValue;
+    progress: number;
+    easedProgress: number;
+    /** 内置插值计算的当前值，字符串模式保留十进制精度。 */
+    defaultValue: HysNumberValue;
+}
+export interface HysNumberAnimationOptions {
+    /** 目标值。十进制字符串可保留超出 Number 安全范围的精度。 */
+    value?: HysNumberValue;
+    /** 起始值。省略时首次直接显示目标值，后续从当前显示值过渡。 */
+    from?: HysNumberValue;
+    /** 单轮时长，单位毫秒。默认 650，非正数直接到达终点。 */
+    duration?: number;
+    /** 每次新播放的等待毫秒数，循环的后续轮次立即开始。 */
+    delay?: number;
+    /** 播放速度倍率，影响延迟与时长，默认 1。 */
+    speed?: number;
+    /** 缓动名称、四元组 [x1, y1, x2, y2] 或返回进度的函数。默认 ease-out。 */
+    easing?: HysNumberEasing;
+    /** 替换中间帧数值。接收起止值、原始进度、缓动进度和内置插值，首尾始终精确。 */
+    interpolate?: (context: HysNumberInterpolationContext) => HysNumberValue;
+    /** true 无限循环，正整数表示总轮数，默认 1。 */
+    loop?: boolean | number;
+    /** 循环轮次交替方向。 */
+    alternate?: boolean;
+    /** 更新策略。retarget 从当前帧衔接，restart 回到起点，queue 逐个播放，snap 立即显示。 */
+    interrupt?: HysNumberInterrupt;
+    /** queue 等待项上限，默认 32，范围 1–256。满时丢弃最旧的等待项。 */
+    queueLimit?: number;
+    /** retarget / restart 的最短更新时间间隔，单位毫秒。间隔内保留最新目标。 */
+    updateInterval?: number;
+    /** 最大采样帧率，范围 1–120，默认随浏览器刷新率采样。 */
+    fps?: number;
+    /** 直接显示目标值。全局动效关闭与系统减少动态效果也会立即完成。 */
+    disabled?: boolean;
+    /** 页面隐藏时冻结计时，可见时继续，默认 true。 */
+    pauseWhenHidden?: boolean;
+}
+export interface HysNumberFrame {
+    value: HysNumberValue;
+    from: HysNumberValue;
+    to: HysNumberValue;
+    progress: number;
+    easedProgress: number;
+    direction: HysNumberDirection;
+    status: HysNumberStatus;
+    iteration: number;
+}
+export interface HysNumberComposableOptions extends HysNumberAnimationOptions {
+    /** 指定是否在挂载时播放，省略时提供 from 即播放。 */
+    autoPlay?: boolean;
+    /** 监听 value 并应用更新策略，默认 true。 */
+    autoUpdate?: boolean;
+}
+export interface HysNumberTrend {
+    previous: HysNumberValue;
+    target: HysNumberValue;
+    direction: HysNumberDirection;
+    delta: string | null;
+    percent: string | null;
+    significant: boolean;
+}
+export type HysNumberEvent = "start" | "update" | "progress" | "pause" | "resume" | "end" | "cancel" | "loop";
+export interface HysNumberControls {
+    play: () => void;
+    pause: () => void;
+    resume: () => void;
+    stop: () => void;
+    restart: () => void;
+    reset: () => void;
+    reverse: () => void;
+    seek: (progress: number) => void;
+    finishAnimation: () => void;
+}
+export interface HysNumberUnitRule {
+    /** 按绝对值匹配的最小值，优先使用匹配规则中阈值最大的一项。 */
+    threshold: HysNumberValue;
+    /** 缩放除数，省略时使用 threshold。 */
+    divisor?: HysNumberValue;
+    label: string;
+}
+export interface HysNumberFormatOptions {
+    /** 小数位数的兼容属性，precision 优先。 */
+    decimals?: number;
+    /** 固定小数位数，范围 0–100。省略时普通字符串保留有效精度。 */
+    precision?: number;
+    /** 去掉末尾小数零及多余的小数点。 */
+    trimZeros?: boolean;
+    /** 整数最小位数，范围 1–21，不足时补零。 */
+    minimumIntegerDigits?: number;
+    /** 舍入规则，默认 half-up，恰好一半时远离零。 */
+    rounding?: HysNumberRounding;
+    /** 千分位符号。空字符串关闭分组，省略时由 grouping 和 locale 决定。 */
+    groupSeparator?: string;
+    /** 小数点符号。省略时使用地区格式或句点。 */
+    decimalSeparator?: string;
+    /** 是否按地区习惯分组。省略时指定 locale 才默认开启。 */
+    grouping?: boolean;
+    /** BCP 47 地区或语言标签，例如 zh-CN、de-DE、hi-IN、ar-EG。 */
+    locale?: string | string[];
+    /** decimal、percent、currency 或 scientific。默认 decimal。 */
+    numberFormat?: HysNumberFormat;
+    /** percent 的数据约定，ratio（默认）下 0.42 显示为 42%，points 下 42 显示为 42%。 */
+    percentInput?: "ratio" | "points";
+    /** ISO 4217 货币代码，例如 CNY、USD 或 EUR。默认 CNY。 */
+    currency?: string;
+    /** 替换地区格式生成的货币符号，保留符号位置。 */
+    currencySymbol?: string;
+    /** 使用 symbol、narrowSymbol 或 code 显示币种。默认 symbol。 */
+    currencyDisplay?: "symbol" | "narrowSymbol" | "code";
+    /** 自动单位。short 使用 K/M/B/T，zh 使用万/亿/万亿，也可传自定义规则数组。 */
+    compact?: "short" | "zh" | readonly HysNumberUnitRule[];
+    /** 在自动缩写单位之后附加文字。 */
+    unit?: string;
+    /** 正负号显示策略。默认 auto，仅显示负号。 */
+    signDisplay?: "auto" | "always" | "exceptZero" | "never";
+    /** 自定义正号。需设置 signDisplay="always" 或 "exceptZero"。 */
+    positiveSign?: string;
+    /** 自定义负号。 */
+    negativeSign?: string;
+}
+export interface HysAnimatedNumberContext extends HysNumberFrame {
+    displayValue: string;
+    unit: string;
+    remaining?: number;
+    trend: HysNumberTrend;
+}
+export interface HysNumberDigitContext extends HysAnimatedNumberContext {
+    digit: string;
+    index: number;
+    position: number;
+    section: "integer" | "fraction";
+    digitProgress: number;
+}
+export interface HysAnimatedNumberProps extends HysNumberAnimationOptions, HysNumberFormatOptions {
+    /** v-model 的目标值。与 value 同时传入时优先。 */
+    modelValue?: HysNumberValue;
+    /** 可组合的播放触发条件。默认 mount 和 update，manual 仅响应实例方法。 */
+    trigger?: HysNumberTrigger | readonly HysNumberTrigger[];
+    /** 自动和用户交互触发时的条件，可接收触发原因与最新目标值。 */
+    canPlay?: boolean | ((trigger: HysNumberTrigger, target: HysNumberValue) => boolean);
+    /** 进入视口触发时只播放一次，默认 true。 */
+    visibleOnce?: boolean;
+    /** 离开视口暂停并在重新进入时继续。 */
+    pauseOutside?: boolean;
+    /** 可视比例 0–1，默认 0.2。 */
+    visibilityThreshold?: number;
+    /** 数字动画效果，可传数组组合。默认 count。 */
+    effect?: HysNumberEffect | readonly HysNumberEffect[];
+    /** 统一效果入口。接受效果名、带参数的配置，或最多 8 层的配置数组，支持运行时切换。 */
+    animation?: HysNumberAnimation;
+    /** 用户预设表。预设可引用其他预设，循环引用自动跳过。 */
+    animationPresets?: HysNumberAnimationPresets;
+    /** animation 无法解析时使用的备用配置。 */
+    fallbackAnimation?: HysNumberAnimation;
+    /** 按位权覆盖效果。键为 integer:0（个位）、fraction:1（第一位小数）或 *（所有未指定数位）。 */
+    digitAnimations?: HysNumberDigitAnimations;
+    /** 全局效果强度 0–2，默认 1；0 仅保留数值变化。 */
+    motionIntensity?: number;
+    /** full 完整效果，simplified 仅计数，off 立即到达目标。遵循系统减少动效设置。 */
+    animationMotion?: "full" | "simplified" | "off";
+    /** 播放区间的差值达到 changeThreshold 时追加的效果，默认 highlight。 */
+    thresholdEffect?: HysNumberEffect | readonly HysNumberEffect[];
+    /** 滚轮与滑动方向，默认 vertical。 */
+    axis?: "vertical" | "horizontal";
+    /** 逐位启动间隔，单位毫秒。 */
+    stagger?: number;
+    /** 单位数字动效时长，单位毫秒。省略时使用剩余的播放时间。 */
+    digitDuration?: number;
+    /** high-to-low 从高位开始，low-to-high 从低位开始。 */
+    digitOrder?: "high-to-low" | "low-to-high";
+    /** 数值区域的自定义逐帧样式，可与内置效果组合。 */
+    animationStyle?: (context: HysAnimatedNumberContext) => StyleValue;
+    /** 为起点和终点文本预留宽度，并保留当前内容的自然宽度。 */
+    stableWidth?: boolean;
+    /** plain 常规数字、panel 逐位面板、display 大屏数字。默认 plain。 */
+    appearance?: "plain" | "panel" | "display";
+    /** 启用正负值的语义配色。 */
+    colorBySign?: boolean;
+    /** 按最近一次目标值增减配色，优先于 colorBySign。 */
+    colorByDirection?: boolean;
+    /** 差值绝对值达到此阈值时标记 significant 并触发 threshold 事件。 */
+    changeThreshold?: HysNumberValue;
+    /** 展示统计标题，title 插槽优先。 */
+    title?: string;
+    /** 数值前的文本，prefix 插槽优先。 */
+    prefix?: string;
+    /** 数值后的文本，suffix 插槽优先。 */
+    suffix?: string;
+    /** 应用到数值区域的 Vue 样式。 */
+    valueStyle?: StyleValue;
+    /** 接收当前值、格式文本、播放状态与趋势，可返回文字或 VNode。 */
+    formatter?: (context: HysAnimatedNumberContext) => VNodeChild;
+    /** 朗读结束值和倒计时结束值。默认静默更新。 */
+    announce?: boolean;
+    /** 启用截止时间倒计时，传 Unix 毫秒时间戳或 Date。 */
+    deadline?: number | Date;
+    /** 倒计时模板支持 D、DD、H、HH、m、mm、s、ss、SSS，字面文本使用方括号。 */
+    format?: string;
+}
+export interface HysAnimatedNumberInstance extends HysNumberControls {
+    displayValue: string;
+    remaining: number;
+    frame: HysNumberFrame;
+    trend: HysNumberTrend;
+    setValue: (target: HysNumberValue) => void;
+}

package/dist/types/composables/animatedNumberDigits.d.ts

@@ -0,0 +1,32 @@
+import type { HysNumberEffect } from "./animatedNumber";
+import type { NumberPresentation } from "./animatedNumberFormat";
+export declare const digitEffects: readonly HysNumberEffect[];
+type DigitSection = "integer" | "fraction";
+export declare function digitCount(parts: Intl.NumberFormatPart[]): number;
+export interface DigitToken {
+    key: string;
+    text: string;
+    type: Intl.NumberFormatPartTypes;
+    position: number;
+    section?: DigitSection;
+}
+export declare function numberTokens(parts: Intl.NumberFormatPart[], split: boolean): DigitToken[];
+export declare function createDigitTracks(start: NumberPresentation, end: NumberPresentation, glyphs: string[]): (token: DigitToken) => {
+    offset: number;
+    destination: number;
+    steps: number;
+    carry: {
+        start: number;
+        end: number;
+    } | undefined;
+    fromPresent: boolean;
+    toPresent: boolean;
+};
+export declare function digitMotion(effect: HysNumberEffect, track: ReturnType<ReturnType<typeof createDigitTracks>>, progress: number, index: number, glyphs: string[]): {
+    first: string;
+    second: string;
+    phase: number;
+    direction: number;
+    changed: boolean;
+};
+export {};

package/dist/types/composables/animatedNumberFormat.d.ts

@@ -0,0 +1,16 @@
+import type { HysNumberAnimationOptions, HysNumberDirection, HysNumberFormatOptions, HysNumberTrend, HysNumberValue } from "./animatedNumber";
+export declare function numberValue(value: HysNumberValue | undefined): HysNumberValue;
+export declare function bounded(value: number | undefined, fallback: number, min: number, max: number): number;
+export declare function numberDirection(from: HysNumberValue, to: HysNumberValue): HysNumberDirection;
+export declare function numberInterpolation(from: HysNumberValue, to: HysNumberValue): (progress: number) => HysNumberValue;
+export declare function createNumberInterpolator(from: HysNumberValue, to: HysNumberValue, custom: HysNumberAnimationOptions["interpolate"]): (_progress: number, easedProgress: number) => HysNumberValue;
+export declare function numberTrend(previous: HysNumberValue, target: HysNumberValue, threshold?: HysNumberValue): HysNumberTrend;
+export interface NumberPresentation {
+    text: string;
+    parts: Intl.NumberFormatPart[];
+    unit: string;
+}
+export declare function createNumberPresentation(options: HysNumberFormatOptions): {
+    format: (raw: HysNumberValue) => NumberPresentation;
+    localized: string[];
+};

package/dist/types/composables/animatedNumberTiming.d.ts

@@ -0,0 +1,21 @@
+import type { HysNumberEasing, HysNumberValue } from "./animatedNumber";
+import type { createNumberInterpolator } from "./animatedNumberFormat";
+type Tick = (now: number) => void;
+export declare function unsubscribe(tick: Tick): void;
+export declare function subscribe(tick: Tick): void;
+export declare function listenVisibility(update: () => void): void;
+export declare function unlistenVisibility(update: () => void): void;
+export declare function makeEasing(easing?: HysNumberEasing): (progress: number) => number;
+export interface Run {
+    from: HysNumberValue;
+    to: HysNumberValue;
+    interpolate: ReturnType<typeof createNumberInterpolator>;
+    easing: ReturnType<typeof makeEasing>;
+    duration: number;
+    elapsed: number;
+    iteration: number;
+    loops: number;
+    alternate: boolean;
+    started: boolean;
+}
+export {};

package/dist/types/composables/drawer.d.ts

@@ -98,5 +98,5 @@ export declare const drawerSizes: {
     readonly xl: 960;
     readonly full: "100%";
 };
-export declare const drawerVertical: (placement?: HysDrawerPlacement) => placement is "top" | "bottom";
+export declare const drawerVertical: (placement?: HysDrawerPlacement) => placement is "bottom" | "top";
 export declare function drawerSize(props: HysDrawerProps): string | number;

package/dist/types/composables/numberAnimation.d.ts

@@ -0,0 +1,29 @@
+import type { HysNumberEffect } from "./animatedNumber";
+import { type HysNumberAnimationEntry, type HysNumberAnimationName } from "./numberAnimationCatalog";
+export interface HysNumberAnimationConfig {
+    /** 内置名称、原有效果名称或 animationPresets 中的预设名。 */
+    name: HysNumberAnimationName | HysNumberEffect | (string & {});
+    /** 效果强度 0–2。 */
+    strength?: number;
+    /** 滚动圈数或重复次数 1–12。 */
+    cycles?: number;
+    /** 数位交错量，按总时长比例指定，范围 0–0.9。 */
+    stagger?: number;
+    /** 可复现的随机种子。 */
+    seed?: number;
+    /** 为有方向的效果选择滚动轴。 */
+    axis?: "horizontal" | "vertical";
+}
+export type HysNumberAnimationItem = HysNumberAnimationConfig["name"] | HysNumberAnimationConfig;
+export type HysNumberAnimation = HysNumberAnimationItem | readonly HysNumberAnimationItem[];
+export type HysNumberAnimationPresets = Readonly<Record<string, HysNumberAnimation>>;
+export type HysNumberDigitAnimations = Readonly<Record<string, HysNumberAnimation>>;
+export interface ResolvedNumberAnimation extends Omit<HysNumberAnimationConfig, "name"> {
+    entry?: HysNumberAnimationEntry;
+    effect?: HysNumberEffect;
+}
+export declare function resolveNumberAnimation(animation: unknown, presets?: HysNumberAnimationPresets): ResolvedNumberAnimation[];
+/** 导入可复用的动画配置，名称在实际使用时按预设表解析。 */
+export declare function parseHysNumberAnimation(json: string): readonly HysNumberAnimationConfig[];
+/** 导出动画配置。仅保存名称与可序列化参数。 */
+export declare function stringifyHysNumberAnimation(animation: HysNumberAnimation): string;

package/dist/types/composables/numberAnimationCatalog.d.ts

@@ -0,0 +1,58 @@
+/** Built-in effects, grouped as presented in the documentation. */
+declare const categories: readonly [{
+    readonly id: "rolling";
+    readonly label: "机械滚动与计数动画";
+    readonly entries: readonly [readonly ["drum-roll", "数字滚筒动画", "Drum Roll"], readonly ["gear-counter", "数字齿轮滚动", "Gear Counter"], readonly ["conveyor-counter", "数字传送带动画", "Conveyor Counter"], readonly ["waterfall-counter", "数字瀑布滚动", "Waterfall Counter"], readonly ["spiral-roll", "数字螺旋滚动", "Spiral Roll"], readonly ["inertia-roll", "数字惯性滚动", "Inertia Roll"], readonly ["accelerating-roll", "数字加速滚动", "Accelerating Roll"], readonly ["decelerating-roll", "数字减速滚动", "Decelerating Roll"], readonly ["overshoot-roll", "数字回弹滚动", "Overshoot Roll"], readonly ["damped-roll", "数字阻尼滚动", "Damped Roll"], readonly ["multi-cycle-roll", "数字多圈滚动", "Multi-Cycle Roll"], readonly ["segmented-roll", "数字分段滚动", "Segmented Roll"], readonly ["step-counter", "数字阶梯计数", "Step Counter"], readonly ["jump-counter", "数字跳跃计数", "Jump Counter"], readonly ["differential-roll", "数字差速滚动", "Differential Roll"], readonly ["synchronized-roll", "数字同步滚轮", "Synchronized Roll"], readonly ["asynchronous-roll", "数字异步滚轮", "Asynchronous Roll"], readonly ["sequential-stop", "数字逐位停靠", "Sequential Stop"], readonly ["mechanical-snap", "数字机械卡位", "Mechanical Snap"], readonly ["mileage-tick", "数字里程跳表", "Mileage Tick"]];
+}, {
+    readonly id: "spatial";
+    readonly label: "3D 立体与翻转动画";
+    readonly entries: readonly [readonly ["cube-rotate", "3D 数字立方体旋转", "Cube Rotate"], readonly ["cylinder-rotate", "3D 数字圆柱旋转", "Cylinder Rotate"], readonly ["sphere-rotate", "3D 数字球面旋转", "Sphere Rotate"], readonly ["3d-wheel", "3D 数字轮盘", "3D Wheel"], readonly ["vertical-fold", "数字上下折叠", "Vertical Fold"], readonly ["horizontal-fold", "数字左右折叠", "Horizontal Fold"], readonly ["card-flip", "数字卡片翻页", "Card Flip"], readonly ["calendar-flip", "数字日历翻页", "Calendar Flip"], readonly ["split-flap-clock", "复古翻页时钟", "Split-Flap Clock"], readonly ["blinds-flip", "数字百叶窗翻转", "Blinds Flip"], readonly ["3d-pop-out", "数字立体弹出", "3D Pop Out"], readonly ["3d-retract", "数字立体缩回", "3D Retract"], readonly ["perspective-rotate", "数字透视旋转", "Perspective Rotate"], readonly ["depth-transition", "数字空间穿梭", "Depth Transition"], readonly ["axis-flip", "数字轴向翻转", "Axis Flip"], readonly ["polyhedron-transition", "数字多面体切换", "Polyhedron Transition"], readonly ["3d-floating", "数字立体悬浮", "3D Floating"], readonly ["3d-tilt", "数字立体倾斜", "3D Tilt"], readonly ["3d-compression", "数字立体挤压", "3D Compression"], readonly ["3d-unfold", "数字立体展开", "3D Unfold"]];
+}, {
+    readonly id: "morph";
+    readonly label: "数字形态变换动画";
+    readonly entries: readonly [readonly ["number-morph", "数字形状渐变", "Number Morph"], readonly ["path-morphing", "数字路径变形", "Path Morphing"], readonly ["outline-morph", "数字轮廓变形", "Outline Morph"], readonly ["stroke-rebuild", "数字笔画重组", "Stroke Rebuild"], readonly ["skeleton-morph", "数字骨架变换", "Skeleton Morph"], readonly ["liquid-morph", "数字液态变形", "Liquid Morph"], readonly ["clay-morph", "数字橡皮泥变形", "Clay Morph"], readonly ["melting-number", "数字融化变形", "Melting Number"], readonly ["stretch-morph", "数字拉伸变形", "Stretch Morph"], readonly ["squash-morph", "数字压缩变形", "Squash Morph"], readonly ["twist-morph", "数字扭曲变形", "Twist Morph"], readonly ["rotate-morph", "数字旋转变形", "Rotate Morph"], readonly ["fragment-morph", "数字碎片重组", "Fragment Morph"], readonly ["geometric-morph", "数字几何重构", "Geometric Morph"], readonly ["polyline-morph", "数字折线变形", "Polyline Morph"], readonly ["curve-morph", "数字曲线变形", "Curve Morph"], readonly ["smooth-morph", "数字平滑形变", "Smooth Morph"], readonly ["split-and-merge", "数字分裂与合并", "Split & Merge"], readonly ["character-blend", "数字字符融合", "Character Blend"], readonly ["contour-flow", "数字轮廓流动", "Contour Flow"]];
+}, {
+    readonly id: "reveal";
+    readonly label: "数字揭示与排版动画";
+    readonly entries: readonly [readonly ["digit-reveal", "数字逐字揭示", "Digit Reveal"], readonly ["mask-reveal", "数字遮罩揭示", "Mask Reveal"], readonly ["wipe-reveal", "数字擦除揭示", "Wipe Reveal"], readonly ["scan-reveal", "数字扫描揭示", "Scan Reveal"], readonly ["clip-reveal", "数字裁剪揭示", "Clip Reveal"], readonly ["center-reveal", "数字中心向外展开", "Center Reveal"], readonly ["edge-converge", "数字两侧向中心收拢", "Edge Converge"], readonly ["rise-reveal", "数字从底部升起", "Rise Reveal"], readonly ["drop-reveal", "数字从顶部降落", "Drop Reveal"], readonly ["shutter-reveal", "数字百叶窗揭示", "Shutter Reveal"], readonly ["number-typewriter", "数字打字机效果", "Number Typewriter"], readonly ["handwriting-number", "数字手写绘制", "Handwriting Number"], readonly ["stroke-draw", "数字路径描绘", "Stroke Draw"], readonly ["outline-fill", "数字轮廓填充", "Outline Fill"], readonly ["progressive-fill", "数字渐进填充", "Progressive Fill"], readonly ["wave-fill", "数字波浪填充", "Wave Fill"], readonly ["shine-sweep", "数字遮罩扫光", "Shine Sweep"], readonly ["light-reveal", "数字光束揭示", "Light Reveal"], readonly ["slice-assemble", "数字切片拼接", "Slice Assemble"], readonly ["staggered-reveal", "数字交错揭示", "Staggered Reveal"]];
+}, {
+    readonly id: "physics";
+    readonly label: "弹性与物理运动动画";
+    readonly entries: readonly [readonly ["gravity-drop", "数字重力下落", "Gravity Drop"], readonly ["free-fall", "数字自由落体", "Free Fall"], readonly ["ground-bounce", "数字落地反弹", "Ground Bounce"], readonly ["spring-stretch", "数字弹簧伸缩", "Spring Stretch"], readonly ["rubber-band", "数字橡胶回弹", "Rubber Band"], readonly ["jelly", "数字果冻抖动", "Jelly"], readonly ["squash-and-stretch", "数字弹性挤压", "Squash & Stretch"], readonly ["pendulum", "数字钟摆摆动", "Pendulum"], readonly ["swing", "数字左右摇摆", "Swing"], readonly ["inertia-slide", "数字惯性滑动", "Inertia Slide"], readonly ["magnetic-snap", "数字磁吸定位", "Magnetic Snap"], readonly ["wave-motion", "数字波浪起伏", "Wave Motion"], readonly ["pulse", "数字连续脉冲", "Pulse"], readonly ["breathing", "数字呼吸动画", "Breathing"], readonly ["heartbeat", "数字心跳动画", "Heartbeat"], readonly ["rhythmic-vibration", "数字节奏振动", "Rhythmic Vibration"], readonly ["impact", "数字冲击反馈", "Impact"], readonly ["catapult", "数字弹射入场", "Catapult"], readonly ["spin-pop", "数字旋转弹入", "Spin Pop"], readonly ["elastic-return", "数字弹性归位", "Elastic Return"]];
+}, {
+    readonly id: "particles";
+    readonly label: "粒子、碎片与流体动画";
+    readonly entries: readonly [readonly ["particle-assemble", "数字粒子聚合", "Particle Assemble"], readonly ["particle-dissolve", "数字粒子消散", "Particle Dissolve"], readonly ["particle-rebuild", "数字粒子重组", "Particle Rebuild"], readonly ["pixel-assemble", "数字像素聚合", "Pixel Assemble"], readonly ["pixel-dissolve", "数字像素溶解", "Pixel Dissolve"], readonly ["mosaic-transition", "数字马赛克切换", "Mosaic Transition"], readonly ["fragment-scatter", "数字碎片飞散", "Fragment Scatter"], readonly ["fragment-assemble", "数字碎片拼接", "Fragment Assemble"], readonly ["sand-assemble", "数字沙粒聚合", "Sand Assemble"], readonly ["sand-fall", "数字沙粒坠落", "Sand Fall"], readonly ["smoke-reveal", "数字烟雾显现", "Smoke Reveal"], readonly ["water-ripple", "数字水波扩散", "Water Ripple"], readonly ["liquid-gather", "数字液滴汇聚", "Liquid Gather"], readonly ["liquid-flow", "数字液体流动", "Liquid Flow"], readonly ["ink-spread", "数字墨水扩散", "Ink Spread"], readonly ["ink-rebuild", "数字墨水重组", "Ink Rebuild"], readonly ["light-particle-gather", "数字光点汇聚", "Light Particle Gather"], readonly ["firefly-gather", "数字萤火虫聚合", "Firefly Gather"], readonly ["star-scatter", "数字星光散射", "Star Scatter"], readonly ["particle-burst", "数字粒子爆发", "Particle Burst"]];
+}, {
+    readonly id: "digital";
+    readonly label: "科技感与赛博数字动画";
+    readonly entries: readonly [readonly ["seven-segment-display", "LED 七段数码管", "Seven-Segment Display"], readonly ["sixteen-segment-display", "LED 十六段数码管", "Sixteen-Segment Display"], readonly ["dot-matrix-number", "LED 点阵数字", "Dot Matrix Number"], readonly ["lcd-number", "LCD 液晶数字", "LCD Number"], readonly ["neon-number", "霓虹灯数字", "Neon Number"], readonly ["holographic-number", "全息投影数字", "Holographic Number"], readonly ["matrix-decode", "数字矩阵解码", "Matrix Decode"], readonly ["binary-decode", "数字二进制解码", "Binary Decode"], readonly ["hex-decode", "数字十六进制解码", "Hex Decode"], readonly ["character-scramble", "数字字符扰动", "Character Scramble"], readonly ["glitch", "数字故障闪烁", "Glitch"], readonly ["signal-interference", "数字信号干扰", "Signal Interference"], readonly ["rgb-split", "数字 RGB 色差", "RGB Split"], readonly ["scanline", "数字扫描线", "Scanline"], readonly ["crt-effect", "数字 CRT 复古显示", "CRT Effect"], readonly ["electronic-pulse", "数字电子脉冲", "Electronic Pulse"], readonly ["electric-flow", "数字电流流动", "Electric Flow"], readonly ["energy-charging", "数字能量充能", "Energy Charging"], readonly ["energy-discharge", "数字能量释放", "Energy Discharge"], readonly ["radar-scan", "数字雷达扫描", "Radar Scan"], readonly ["raster-transition", "数字光栅切换", "Raster Transition"], readonly ["pixel-scan", "数字像素扫描", "Pixel Scan"], readonly ["data-stream", "数字数据流切换", "Data Stream"], readonly ["code-rain", "数字代码雨", "Code Rain"], readonly ["terminal-print", "数字终端打印", "Terminal Print"], readonly ["terminal-cursor", "数字终端光标闪烁", "Terminal Cursor"], readonly ["hud-counter", "数字 HUD 仪表显示", "HUD Counter"], readonly ["halo-pulse", "数字光环脉冲", "Halo Pulse"], readonly ["laser-outline", "数字激光描边", "Laser Outline"], readonly ["grid-rebuild", "数字科技网格重组", "Grid Rebuild"]];
+}, {
+    readonly id: "data";
+    readonly label: "金融、统计与数据可视化动画";
+    readonly entries: readonly [readonly ["amount-rise", "金额逐位增长动画"], readonly ["amount-fall", "金额逐位下降动画"], readonly ["fractional-roll", "金额小数位独立滚动"], readonly ["currency-switch", "货币符号切换动画"], readonly ["sign-flip", "正负号翻转动画"], readonly ["grouping-reflow", "数字千分位动态重排"], readonly ["carry-highlight", "数值进位强调动画"], readonly ["borrow-highlight", "数值退位强调动画"], readonly ["trend-up", "数值增长箭头联动"], readonly ["trend-down", "数值下降箭头联动"], readonly ["delta-expand", "数字差值展开动画"], readonly ["percent-change", "数字百分比变化动画"], readonly ["gain-highlight", "数字增幅强调动画"], readonly ["threshold-cross", "数字阈值突破动画"], readonly ["goal-reached", "数字目标达成动画"], readonly ["goal-exceeded", "数字目标超额动画"], readonly ["progress-fill", "数字进度填充动画"], readonly ["ring-progress", "数字环形进度联动"], readonly ["gauge-needle", "数字仪表盘指针联动"], readonly ["trend-line", "数字趋势曲线联动"], readonly ["chart-growth", "数字图表同步增长"], readonly ["ranking-swap", "数字排行榜名次切换"], readonly ["rank-rise", "数字名次跃升动画"], readonly ["rank-fall", "数字名次下降动画"], readonly ["kpi-refresh", "KPI 数值刷新动画"], readonly ["kpi-alert", "KPI 数值异常警示动画"], readonly ["kpi-peak", "KPI 数值峰值强调动画"], readonly ["kpi-trough", "KPI 数值低谷强调动画"], readonly ["live-trade", "实时交易金额跳动动画"], readonly ["live-orders", "实时订单数量增长动画"]];
+}, {
+    readonly id: "sequence";
+    readonly label: "数字组合与编排动画";
+    readonly entries: readonly [readonly ["sequential-start", "多数字依次启动", "Sequential Start"], readonly ["wave-start", "多数字波浪启动", "Wave Start"], readonly ["staircase-start", "多数字阶梯启动", "Staircase Start"], readonly ["center-out", "多数字中心扩散", "Center Out"], readonly ["outside-in", "多数字两侧汇聚", "Outside In"], readonly ["random-start", "多数字随机启动", "Random Start"], readonly ["synchronized-stop", "多数字同步定格", "Synchronized Stop"], readonly ["staggered-stop", "多数字错峰定格", "Staggered Stop"], readonly ["alternating-roll", "多数字交替滚动", "Alternating Roll"], readonly ["relay-roll", "多数字接力滚动", "Relay Roll"], readonly ["chain-transition", "多数字链式变化", "Chain Transition"], readonly ["rhythm-sync", "多数字节奏同步", "Rhythm Sync"], readonly ["cascade", "多数字级联变化", "Cascade"], readonly ["mirror-transition", "多数字镜像变化", "Mirror Transition"], readonly ["grouped-transition", "多数字分组变化", "Grouped Transition"], readonly ["matrix-sequence", "多数字矩阵编排", "Matrix Sequence"], readonly ["path-sequence", "多数字路径编排", "Path Sequence"], readonly ["random-rearrange", "多数字随机重排", "Random Rearrange"], readonly ["row-reveal", "多数字逐行揭示", "Row Reveal"], readonly ["column-reveal", "多数字逐列揭示", "Column Reveal"]];
+}, {
+    readonly id: "special";
+    readonly label: "特殊展示与创意动画";
+    readonly entries: readonly [readonly ["flip-clock", "数字时钟翻页动画"], readonly ["rolling-stopwatch", "数字秒表滚动动画"], readonly ["lottery-draw", "数字彩票摇号动画"], readonly ["raffle-roll", "数字抽奖滚动动画"], readonly ["countdown-sprint", "数字倒计时冲刺动画"], readonly ["milestone", "数字里程碑达成动画"], readonly ["achievement", "数字成就解锁动画"], readonly ["coin-drop", "数字金币掉落动画"], readonly ["coin-stack", "数字金币堆叠动画"], readonly ["reward-burst", "数字奖励爆发动画"], readonly ["fireworks", "数字烟花庆祝动画"], readonly ["confetti", "数字彩带庆祝动画"], readonly ["medal-pop", "数字奖牌弹出动画"], readonly ["badge-light", "数字徽章点亮动画"], readonly ["energy-meter", "数字能量槽充满动画"], readonly ["thermometer", "数字温度计升降动画"], readonly ["battery", "数字电量充放动画"], readonly ["speedometer", "数字速度表加减速动画"], readonly ["water-level", "数字水位上涨下降动画"], readonly ["scale-ticks", "数字刻度尺动态变化动画"]];
+}];
+type Category = (typeof categories)[number];
+export type HysNumberAnimationCategory = Category["id"];
+export type HysNumberAnimationName = Category["entries"][number][0];
+export interface HysNumberAnimationEntry {
+    name: HysNumberAnimationName;
+    label: string;
+    english?: string;
+    category: HysNumberAnimationCategory;
+    variant: number;
+}
+export declare const hysNumberAnimationCategories: {
+    id: "data" | "rolling" | "spatial" | "morph" | "reveal" | "physics" | "particles" | "digital" | "sequence" | "special";
+    label: "机械滚动与计数动画" | "3D 立体与翻转动画" | "数字形态变换动画" | "数字揭示与排版动画" | "弹性与物理运动动画" | "粒子、碎片与流体动画" | "科技感与赛博数字动画" | "金融、统计与数据可视化动画" | "数字组合与编排动画" | "特殊展示与创意动画";
+}[];
+export declare const hysNumberAnimationCatalog: readonly HysNumberAnimationEntry[];
+export {};

package/dist/types/composables/numberAnimationSequence.d.ts

@@ -0,0 +1,13 @@
+export interface HysNumberSequenceStep {
+    index: number;
+    delay: number;
+    duration: number;
+    reverse: boolean;
+}
+/** 将多实例编排转换为每个实例的顺序、延迟、时长和播放方向。 */
+export declare function createHysNumberSequence(name: string, count: number, options?: {
+    duration?: number;
+    interval?: number;
+    columns?: number;
+    seed?: number;
+}): HysNumberSequenceStep[];

package/dist/types/composables/popupReferenceBinding.d.ts

@@ -0,0 +1,9 @@
+type ReferenceListeners = {
+    [Name in keyof HTMLElementEventMap]?: (event: HTMLElementEventMap[Name]) => void;
+};
+export declare function createPopupReferenceBinding(kind: "tooltip" | "popover", id: string, events: ReferenceListeners): {
+    attach: (node: HTMLElement | undefined, open: boolean) => void;
+    detach: () => void;
+    syncAria: (open: boolean) => void;
+};
+export {};

package/dist/types/composables/textInput.d.ts

@@ -1,4 +1,4 @@
-import type { Component, InputHTMLAttributes, TextareaHTMLAttributes } from "vue";
+import type { Component, InputHTMLAttributes, StyleValue, TextareaHTMLAttributes } from "vue";
 export interface HysInputFormatInfo {
     userTyping: boolean;
     input: string;
@@ -9,8 +9,20 @@ export interface HysInputCountInfo {
     maxLength?: number;
 }
 export type HysInputCountStrategy = boolean | ((value: string) => number);
+export type HysInputSize = "sm" | "md" | "lg" | "small" | "middle" | "default" | "large";
+export interface HysInputModelModifiers {
+    lazy?: boolean;
+    trim?: boolean;
+    number?: boolean;
+}
+export interface HysTextareaStyle {
+    height?: string;
+    overflowY?: "auto" | "hidden";
+}
 export interface HysInputProps {
     modelValue?: string | number | null;
+    /** Vue v-model 修饰符。lazy 延后写入模型，trim 去首尾空白，number 由 Vue 转换数值。 */
+    modelModifiers?: HysInputModelModifiers;
     defaultValue?: string | number | null;
     placeholder?: string;
     type?: string;
@@ -21,6 +33,12 @@ export interface HysInputProps {
     error?: string;
     status?: "error" | "warning" | "success";
     clearable?: boolean;
+    /** 清空开关别名，clearable 显式设置时优先。 */
+    allowClear?: boolean;
+    /** 输入框外侧的附加文字，prepend 插槽优先。 */
+    addonBefore?: string;
+    /** 输入框外侧的附加文字，append 插槽优先。 */
+    addonAfter?: string;
     clearIcon?: Component;
     prefixIcon?: Component;
     suffixIcon?: Component;
@@ -42,7 +60,7 @@ export interface HysInputProps {
     allowInput?: (value: string) => boolean;
     autocomplete?: string;
     name?: string;
-    size?: "sm" | "md" | "lg";
+    size?: HysInputSize;
     rows?: number;
     autosize?: boolean | {
         minRows?: number;
@@ -50,27 +68,44 @@ export interface HysInputProps {
     };
     resize?: "none" | "both" | "horizontal" | "vertical";
     inputProps?: InputHTMLAttributes | TextareaHTMLAttributes;
+    /** 应用到原生输入元素的样式。自动高度启用时由组件管理 height 和 overflowY。 */
+    inputStyle?: StyleValue;
+    /** 原生 inputmode，用于提示移动端键盘布局。 */
+    inputmode?: InputHTMLAttributes["inputmode"];
+    /** 原生控件的 Tab 顺序。 */
+    tabindex?: string | number;
+    /** 关联的原生 form 元素 ID，可提交在表单外的输入。 */
+    form?: string;
+    /** 是否由组件交互触发表单的 change、blur 校验，默认 true。 */
+    validateEvent?: boolean;
     autofocus?: boolean;
     selectOnFocus?: boolean;
     bordered?: boolean;
     round?: boolean;
 }
 export interface HysInputInstance {
+    element: HTMLInputElement | HTMLTextAreaElement | undefined;
     input: HTMLInputElement | HTMLTextAreaElement | undefined;
     textarea: HTMLTextAreaElement | undefined;
     isComposing: boolean;
+    passwordVisible: boolean;
+    textareaStyle: HysTextareaStyle;
     focus: (options?: FocusOptions) => void;
     blur: () => void;
     select: () => void;
     clear: () => void;
     resize: () => Promise<void>;
+    resizeTextarea: () => Promise<void>;
     setSelectionRange: (start: number, end: number, direction?: "forward" | "backward" | "none") => void;
     scrollTo: (options: ScrollToOptions) => void;
 }
-export type HysTextareaProps = Omit<HysInputProps, 'type' | 'showPassword' | 'showPasswordOn' | 'passwordVisible' | 'defaultPasswordVisible'>;
-export interface HysTextareaInstance extends Omit<HysInputInstance, 'input'> {
+export type HysTextareaProps = Omit<HysInputProps, "type" | "showPassword" | "showPasswordOn" | "passwordVisible" | "defaultPasswordVisible">;
+export interface HysTextareaInstance extends Omit<HysInputInstance, "input" | "element" | "passwordVisible"> {
     input: HTMLTextAreaElement | undefined;
+    element: HTMLTextAreaElement | undefined;
 }
+export declare function textInputSize(size?: HysInputSize): "sm" | "md" | "lg" | undefined;
+export declare function modelText(value: string, modifiers?: HysInputModelModifiers): string;
 export declare function textCount(value: string, strategy?: HysInputCountStrategy): number;
 export declare function textLimit(value: string, max: number | undefined, strategy?: HysInputCountStrategy): string;
 export declare function textLengthLimit(value?: string | number): number | undefined;

package/dist/types/composables/toastEscape.d.ts

@@ -1 +1 @@
-export declare function registerToastEscape(close: () => void): () => void;
+export declare function registerToastEscape(close: (event: KeyboardEvent) => void, element: () => HTMLElement | undefined): (() => void) | undefined;