@chenzy-design/core 0.1.0

package/dist/progress.d.ts

@@ -0,0 +1,64 @@
+/**
+ * createProgress helpers — framework-agnostic progress math & a11y.
+ * Pure functions only: percent clamping, status resolution, circle/dashboard
+ * SVG geometry, and progressbar aria props. No DOM, no framework deps.
+ * See specs/components/feedback/Progress.spec.md §3.
+ */
+export type ProgressStatus = 'normal' | 'success' | 'error' | 'warning';
+export type ProgressType = 'line' | 'circle' | 'dashboard';
+export type GapPosition = 'top' | 'bottom' | 'left' | 'right';
+/** Clamp any input to an integer-friendly 0..100 (NaN/±∞ → 0/100). */
+export declare function clampPercent(percent: number): number;
+/**
+ * Resolve the effective status. When status is left at 'normal' and the bar is
+ * full, optionally promote to 'success' (successWhenFull). An explicitly set
+ * error/warning/success is always respected.
+ */
+export declare function resolveStatus(percent: number, status: ProgressStatus, successWhenFull?: boolean): ProgressStatus;
+export interface CirclePathInput {
+    /** diameter in px */
+    width: number;
+    /** stroke width in px */
+    strokeWidth: number;
+    /** percent 0..100 */
+    percent: number;
+    /** open-gap angle for dashboard (0 for full circle) */
+    gapDegree?: number;
+    gapPosition?: GapPosition;
+}
+export interface CirclePathProps {
+    radius: number;
+    /** center coordinate (width/2) */
+    center: number;
+    /** full stroke length of the track (accounting for the gap) */
+    circumference: number;
+    /** dasharray for the track */
+    trackDash: string;
+    /** dashoffset for the filled stroke (maps percent → arc length) */
+    fillDash: string;
+    /** rotation transform so the start sits at the right place */
+    rotation: number;
+}
+/**
+ * Compute SVG geometry for circle/dashboard. The visible track spans
+ * (360 - gapDegree) degrees; the fill covers `percent`% of that span.
+ */
+export declare function getCirclePathProps(input: CirclePathInput): CirclePathProps;
+export interface RootAriaInput {
+    percent: number;
+    indeterminate?: boolean;
+    label?: string;
+    valueText?: string;
+}
+export interface RootAriaProps {
+    role: 'progressbar';
+    'aria-valuemin': 0;
+    'aria-valuemax': 100;
+    'aria-valuenow'?: number;
+    'aria-valuetext'?: string;
+    'aria-label'?: string;
+    'aria-busy'?: true;
+}
+/** Build progressbar aria props; indeterminate omits valuenow + sets busy. */
+export declare function getRootAriaProps(input: RootAriaInput): RootAriaProps;
+//# sourceMappingURL=progress.d.ts.map

package/dist/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AACxE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC;AAC3D,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9D,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKpD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,cAAc,EACtB,eAAe,UAAQ,GACtB,cAAc,CAIhB;AAED,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAmBD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,CA0B1E;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,eAAe,EAAE,CAAC,CAAC;IACnB,eAAe,EAAE,GAAG,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,IAAI,CAAC;CACpB;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAcpE"}

package/dist/progress.js

@@ -0,0 +1,92 @@
+/**
+ * createProgress helpers — framework-agnostic progress math & a11y.
+ * Pure functions only: percent clamping, status resolution, circle/dashboard
+ * SVG geometry, and progressbar aria props. No DOM, no framework deps.
+ * See specs/components/feedback/Progress.spec.md §3.
+ */
+/** Clamp any input to an integer-friendly 0..100 (NaN/±∞ → 0/100). */
+export function clampPercent(percent) {
+    if (Number.isNaN(percent))
+        return 0;
+    if (percent < 0)
+        return 0;
+    if (percent > 100)
+        return 100;
+    return percent;
+}
+/**
+ * Resolve the effective status. When status is left at 'normal' and the bar is
+ * full, optionally promote to 'success' (successWhenFull). An explicitly set
+ * error/warning/success is always respected.
+ */
+export function resolveStatus(percent, status, successWhenFull = false) {
+    if (status !== 'normal')
+        return status;
+    if (successWhenFull && clampPercent(percent) >= 100)
+        return 'success';
+    return 'normal';
+}
+/** rotation (deg) that places the gap/start according to gapPosition */
+function startRotation(gapPosition, gapDegree) {
+    // base: a full circle starts at 3 o'clock; rotate -90 to start at top.
+    switch (gapPosition) {
+        case 'top':
+            return -90 + gapDegree / 2;
+        case 'bottom':
+            return 90 + gapDegree / 2;
+        case 'left':
+            return 180 + gapDegree / 2;
+        case 'right':
+            return 0 + gapDegree / 2;
+        default:
+            return 90 + gapDegree / 2;
+    }
+}
+/**
+ * Compute SVG geometry for circle/dashboard. The visible track spans
+ * (360 - gapDegree) degrees; the fill covers `percent`% of that span.
+ */
+export function getCirclePathProps(input) {
+    const { width, strokeWidth, gapDegree = 0, gapPosition = 'bottom' } = input;
+    const percent = clampPercent(input.percent);
+    const center = width / 2;
+    const radius = center - strokeWidth / 2;
+    const perimeter = 2 * Math.PI * radius;
+    // visible portion of the perimeter (full perimeter minus the gap)
+    const visibleRatio = (360 - gapDegree) / 360;
+    const visibleLen = perimeter * visibleRatio;
+    const gapLen = perimeter - visibleLen;
+    // track: draw visibleLen, then leave gapLen empty
+    const trackDash = `${visibleLen} ${gapLen}`;
+    // fill: draw percent% of the visible length, rest is offset
+    const fillLen = (visibleLen * percent) / 100;
+    const fillDash = `${fillLen} ${perimeter - fillLen}`;
+    return {
+        radius,
+        center,
+        circumference: perimeter,
+        trackDash,
+        fillDash,
+        rotation: startRotation(gapPosition, gapDegree),
+    };
+}
+/** Build progressbar aria props; indeterminate omits valuenow + sets busy. */
+export function getRootAriaProps(input) {
+    const props = {
+        role: 'progressbar',
+        'aria-valuemin': 0,
+        'aria-valuemax': 100,
+    };
+    if (input.indeterminate) {
+        props['aria-busy'] = true;
+    }
+    else {
+        props['aria-valuenow'] = clampPercent(input.percent);
+        if (input.valueText)
+            props['aria-valuetext'] = input.valueText;
+    }
+    if (input.label)
+        props['aria-label'] = input.label;
+    return props;
+}
+//# sourceMappingURL=progress.js.map

package/dist/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"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"}

package/dist/progress.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=progress.test.d.ts.map

package/dist/progress.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.test.d.ts","sourceRoot":"","sources":["../src/progress.test.ts"],"names":[],"mappings":""}

package/dist/progress.test.js

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { clampPercent, resolveStatus, getCirclePathProps, getRootAriaProps, } from './progress.js';
+describe('clampPercent', () => {
+    it('clamps to 0..100 and handles NaN', () => {
+        expect(clampPercent(50)).toBe(50);
+        expect(clampPercent(-10)).toBe(0);
+        expect(clampPercent(120)).toBe(100);
+        expect(clampPercent(Number.NaN)).toBe(0);
+        expect(clampPercent(0)).toBe(0);
+        expect(clampPercent(100)).toBe(100);
+    });
+});
+describe('resolveStatus', () => {
+    it('respects an explicit status', () => {
+        expect(resolveStatus(100, 'error')).toBe('error');
+        expect(resolveStatus(50, 'warning')).toBe('warning');
+    });
+    it('promotes to success when full and successWhenFull', () => {
+        expect(resolveStatus(100, 'normal', true)).toBe('success');
+        expect(resolveStatus(99, 'normal', true)).toBe('normal');
+        expect(resolveStatus(100, 'normal', false)).toBe('normal');
+    });
+});
+describe('getCirclePathProps', () => {
+    it('computes radius/perimeter for a full circle', () => {
+        const p = getCirclePathProps({ width: 120, strokeWidth: 8, percent: 0 });
+        expect(p.center).toBe(60);
+        expect(p.radius).toBe(56); // 60 - 8/2
+        expect(p.circumference).toBeCloseTo(2 * Math.PI * 56, 5);
+    });
+    it('fill length is proportional to percent (full circle)', () => {
+        const r = 56;
+        const perim = 2 * Math.PI * r;
+        const p = getCirclePathProps({ width: 120, strokeWidth: 8, percent: 50 });
+        const fillLen = Number(p.fillDash.split(' ')[0]);
+        expect(fillLen).toBeCloseTo(perim * 0.5, 4);
+    });
+    it('dashboard gap reduces the visible track length', () => {
+        const r = 56;
+        const perim = 2 * Math.PI * r;
+        const p = getCirclePathProps({
+            width: 120,
+            strokeWidth: 8,
+            percent: 100,
+            gapDegree: 90,
+        });
+        // visible track = 270/360 of perimeter
+        const trackLen = Number(p.trackDash.split(' ')[0]);
+        expect(trackLen).toBeCloseTo(perim * (270 / 360), 4);
+        // 100% fill covers the full visible track
+        const fillLen = Number(p.fillDash.split(' ')[0]);
+        expect(fillLen).toBeCloseTo(trackLen, 4);
+    });
+    it('rotation differs by gapPosition', () => {
+        const top = getCirclePathProps({ width: 100, strokeWidth: 6, percent: 0, gapDegree: 60, gapPosition: 'top' });
+        const bottom = getCirclePathProps({ width: 100, strokeWidth: 6, percent: 0, gapDegree: 60, gapPosition: 'bottom' });
+        expect(top.rotation).not.toBe(bottom.rotation);
+    });
+});
+describe('getRootAriaProps', () => {
+    it('emits valuenow for determinate progress', () => {
+        const a = getRootAriaProps({ percent: 42, label: '上传进度', valueText: '42% 完成' });
+        expect(a.role).toBe('progressbar');
+        expect(a['aria-valuenow']).toBe(42);
+        expect(a['aria-valuemin']).toBe(0);
+        expect(a['aria-valuemax']).toBe(100);
+        expect(a['aria-valuetext']).toBe('42% 完成');
+        expect(a['aria-label']).toBe('上传进度');
+    });
+    it('omits valuenow and sets busy when indeterminate', () => {
+        const a = getRootAriaProps({ percent: 50, indeterminate: true });
+        expect(a['aria-valuenow']).toBeUndefined();
+        expect(a['aria-busy']).toBe(true);
+    });
+    it('clamps valuenow', () => {
+        expect(getRootAriaProps({ percent: 150 })['aria-valuenow']).toBe(100);
+    });
+});
+//# sourceMappingURL=progress.test.js.map

package/dist/progress.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.test.js","sourceRoot":"","sources":["../src/progress.test.ts"],"names":[],"mappings":"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"}

package/dist/resize-observer.d.ts

@@ -0,0 +1,133 @@
+/**
+ * createResizeObserver — framework-agnostic wrapper over native ResizeObserver.
+ * Normalizes entries to a stable shape and degrades silently when unsupported
+ * (SSR / old browsers). The svelte layer owns the element refs and lifecycle.
+ * See specs/components/other/ResizeObserver.spec.md §3.
+ *
+ * 进阶子集：
+ *   - throttle / debounce 节流去抖（命令式定时器 + cleanup，红线 #3）
+ *   - 多目标（observe/unobserve 多个元素，回调按 target 路由）
+ *   - 单例 observer 池 getGlobalResizeObserver()（多元素复用 1 个原生 observer）
+ *   - window.resize 降级（fallbackToWindow：原生不可用或显式开启时近似监听）
+ *   - onResizeStart / onResizeEnd：连续变化首帧 / 静默结束（纯状态机 + 命令式静默计时器）
+ */
+export type ResizeBox = 'content-box' | 'border-box' | 'device-pixel-content-box';
+/** 节流/去抖调度策略。'none' = 原生即时（默认，向后兼容）。 */
+export type ResizeSchedule = {
+    strategy: 'none';
+} | {
+    strategy: 'throttle';
+    wait: number;
+} | {
+    strategy: 'debounce';
+    wait: number;
+};
+/** normalized size payload — consumers never call getBoundingClientRect */
+export interface CDResizeEntry {
+    target: Element;
+    width: number;
+    height: number;
+    box: ResizeBox;
+}
+export interface ResizeObserverOptions {
+    box?: ResizeBox;
+    onResize: (entry: CDResizeEntry) => void;
+    /**
+     * 节流间隔(ms)，leading+trailing，0 即原生即时回调。与 debounce 互斥
+     * （同时 >0 时 debounce 优先）。
+     */
+    throttle?: number;
+    /** 防抖等待(ms)，trailing-only，0 关闭。与 throttle 互斥（优先于 throttle）。 */
+    debounce?: number;
+    /**
+     * 一段连续尺寸变化的首帧触发（不在 resizing 态时收到首个 resize）。
+     * 用于"调整中"态（如显示尺寸 badge）。
+     */
+    onResizeStart?: ((entry: CDResizeEntry) => void) | undefined;
+    /**
+     * 连续变化结束后（静默 resizeEndDelay 无新 resize）触发，payload 为最后一帧。
+     * 用于"调整完成"提交。
+     */
+    onResizeEnd?: ((entry: CDResizeEntry) => void) | undefined;
+    /**
+     * onResizeEnd 静默判定窗口(ms)，0 表示沿用 schedule wait（无则默认 RESIZE_END_DELAY）。
+     * 仅当传了 onResizeStart / onResizeEnd 时生效。
+     */
+    resizeEndDelay?: number;
+    /**
+     * 原生 ResizeObserver 不可用（SSR/老环境）或显式开启时，降级监听 window.resize，
+     * 在每次 window resize 用 getBoundingClientRect 重新测量已注册目标并上报（精度较低）。
+     * 默认 false：不支持环境静默降级（不监听、不抛错）。
+     */
+    fallbackToWindow?: boolean;
+}
+export interface ResizeObserverApi {
+    readonly supported: boolean;
+    observe(el: Element): void;
+    unobserve(el: Element): void;
+    disconnect(): void;
+}
+/** true when the native ResizeObserver is available (client only). */
+export declare function isResizeObserverSupported(): boolean;
+/**
+ * Normalize a native ResizeObserverEntry into CDResizeEntry. Prefers
+ * borderBoxSize / contentBoxSize (avoids forced reflow) and falls back to
+ * contentRect for older implementations.
+ */
+export declare function normalizeEntry(entry: ResizeObserverEntry, box: ResizeBox): CDResizeEntry;
+/**
+ * 归一化节流/去抖配置为单一 schedule。纯函数、不依赖时钟（红线 #2 友好）。
+ * debounce 优先于 throttle（spec：二者互斥，同时 >0 时 debounce 优先）。
+ */
+export declare function resolveSchedule(opts: {
+    throttle?: number;
+    debounce?: number;
+}): ResizeSchedule;
+/**
+ * advanceResizePhase — start/end 状态机的纯函数核心（红线 #2，不依赖时钟/计时器）。
+ * 给定"当前是否处于 resizing 态"与一个新到达的 resize 事件，返回新状态及应派发的
+ * 边界事件标记。计时器（决定何时进入 'end'）由命令式调用方持有，本函数只描述跃迁：
+ *   - 不在 resizing 态收到 resize → start，进入 resizing 态。
+ *   - 已在 resizing 态收到 resize → 无边界事件（仅续期，态不变）。
+ * 'end' 的跃迁见 endResizePhase（由静默计时器触发）。
+ */
+export declare function advanceResizePhase(resizing: boolean): {
+    resizing: boolean;
+    emitStart: boolean;
+};
+/**
+ * endResizePhase — 静默计时器到点时的纯跃迁：若处于 resizing 态则结束并标记派发 end。
+ * 非 resizing 态（无在途变化）则不派发，幂等。
+ */
+export declare function endResizePhase(resizing: boolean): {
+    resizing: boolean;
+    emitEnd: boolean;
+};
+/**
+ * createScheduler — 命令式定时器调度器。包裹一个回调，按 schedule 节流/去抖。
+ * - none: 即时透传（零开销，向后兼容）。
+ * - throttle: leading+trailing，窗口内丢弃中间帧，trailing 补发最后一帧。
+ * - debounce: trailing-only，静默 wait 后才发最后一帧。
+ * 返回 { run, flush, cancel }；cancel 必须在 cleanup 调用以清定时器（红线 #3）。
+ *
+ * 注意：run 接受一个无参 commit 闭包（最新值在调用方闭包里持有），
+ * 调度器只负责"何时"调用，不持有业务数据。
+ */
+export declare function createScheduler(schedule: ResizeSchedule): {
+    run: (commit: () => void) => void;
+    flush: () => void;
+    cancel: () => void;
+};
+export declare function createResizeObserver(options: ResizeObserverOptions): ResizeObserverApi;
+type PoolListener = (entry: CDResizeEntry) => void;
+/**
+ * getGlobalResizeObserver — 取得指定 box 的进程内单例池。
+ * 返回 { supported, subscribe }；subscribe 返回取消订阅函数（必须在 cleanup 调用）。
+ * 节流/去抖请在订阅方包裹 createScheduler，池本身只做即时路由分发。
+ */
+export declare function getGlobalResizeObserver(box?: ResizeBox): {
+    readonly supported: boolean;
+    subscribe(el: Element, listener: PoolListener): () => void;
+};
+export {};
+//# sourceMappingURL=resize-observer.d.ts.map

package/dist/resize-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resize-observer.d.ts","sourceRoot":"","sources":["../src/resize-observer.ts"],"names":[],"mappings":"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"}