@chenzy-design/core 0.1.0

package/dist/floating.test.js

@@ -0,0 +1,169 @@
+import { describe, expect, it } from 'vitest';
+import { computePosition, parsePlacement, makePlacement, } from './floating.js';
+// trigger: 100x40 box centered-ish; popup 80x30; large viewport so no clamping
+const trigger = { x: 200, y: 200, width: 100, height: 40 };
+const popup = { x: 0, y: 0, width: 80, height: 30 };
+const viewport = { width: 1000, height: 800 };
+const base = { triggerRect: trigger, popupRect: popup, viewport, offset: 8 };
+describe('parsePlacement / makePlacement round-trip', () => {
+    const all = [
+        'top', 'topStart', 'topEnd',
+        'bottom', 'bottomStart', 'bottomEnd',
+        'left', 'leftStart', 'leftEnd',
+        'right', 'rightStart', 'rightEnd',
+    ];
+    it('round-trips every 12-way placement', () => {
+        for (const p of all) {
+            const { side, align } = parsePlacement(p);
+            expect(makePlacement(side, align)).toBe(p);
+        }
+    });
+});
+describe('computePosition main-axis placement', () => {
+    it('top puts popup above the trigger with offset', () => {
+        const r = computePosition({ ...base, placement: 'top' });
+        expect(r.side).toBe('top');
+        // y = trigger.y - popup.height - offset = 200 - 30 - 8 = 162
+        expect(r.y).toBe(162);
+    });
+    it('bottom puts popup below the trigger with offset', () => {
+        const r = computePosition({ ...base, placement: 'bottom' });
+        // y = trigger.y + trigger.height + offset = 200 + 40 + 8 = 248
+        expect(r.y).toBe(248);
+    });
+    it('left puts popup to the left with offset', () => {
+        const r = computePosition({ ...base, placement: 'left' });
+        // x = trigger.x - popup.width - offset = 200 - 80 - 8 = 112
+        expect(r.x).toBe(112);
+    });
+    it('right puts popup to the right with offset', () => {
+        const r = computePosition({ ...base, placement: 'right' });
+        // x = trigger.x + trigger.width + offset = 200 + 100 + 8 = 308
+        expect(r.x).toBe(308);
+    });
+});
+describe('computePosition cross-axis align', () => {
+    it('top center horizontally centers popup over trigger center', () => {
+        const r = computePosition({ ...base, placement: 'top' });
+        // triggerCenterX = 250; x = 250 - 80/2 = 210
+        expect(r.x).toBe(210);
+    });
+    it('topStart aligns popup left edge with trigger left edge', () => {
+        const r = computePosition({ ...base, placement: 'topStart' });
+        expect(r.x).toBe(trigger.x); // 200
+    });
+    it('topEnd aligns popup right edge with trigger right edge', () => {
+        const r = computePosition({ ...base, placement: 'topEnd' });
+        // triggerRight - popupWidth = 300 - 80 = 220
+        expect(r.x).toBe(220);
+    });
+    it('leftStart aligns popup top edge with trigger top edge', () => {
+        const r = computePosition({ ...base, placement: 'leftStart' });
+        expect(r.y).toBe(trigger.y); // 200
+    });
+});
+describe('computePosition autoAdjust flip', () => {
+    it('flips top -> bottom when there is no room above but room below', () => {
+        const nearTop = { x: 200, y: 10, width: 100, height: 40 };
+        const r = computePosition({
+            ...base,
+            triggerRect: nearTop,
+            placement: 'top',
+            autoAdjust: true,
+        });
+        expect(r.side).toBe('bottom');
+    });
+    it('keeps requested side when it fits even with autoAdjust', () => {
+        const r = computePosition({ ...base, placement: 'top', autoAdjust: true });
+        expect(r.side).toBe('top');
+    });
+    it('does NOT flip when autoAdjust is off, even if overflowing', () => {
+        const nearTop = { x: 200, y: 10, width: 100, height: 40 };
+        const r = computePosition({
+            ...base,
+            triggerRect: nearTop,
+            placement: 'top',
+            autoAdjust: false,
+        });
+        expect(r.side).toBe('top');
+    });
+    it('does not flip when the opposite side has even less room', () => {
+        // trigger tall, near bottom: top has 10px, bottom has ~5px → keep top? no:
+        // top space 600, bottom space tiny → requesting bottom should flip to top
+        const nearBottom = { x: 200, y: 760, width: 100, height: 30 };
+        const r = computePosition({
+            ...base,
+            triggerRect: nearBottom,
+            placement: 'bottom',
+            autoAdjust: true,
+        });
+        expect(r.side).toBe('top');
+    });
+    it('flips left -> right symmetrically', () => {
+        const nearLeft = { x: 10, y: 300, width: 60, height: 40 };
+        const r = computePosition({
+            ...base,
+            triggerRect: nearLeft,
+            placement: 'left',
+            autoAdjust: true,
+        });
+        expect(r.side).toBe('right');
+    });
+});
+describe('computePosition viewport-edge clamping (cross axis)', () => {
+    it('clamps cross-axis x so popup stays inside the viewport with padding', () => {
+        // trigger at far right; top-center would push popup off-screen right
+        const farRight = { x: 980, y: 200, width: 40, height: 40 };
+        const r = computePosition({
+            ...base,
+            triggerRect: farRight,
+            placement: 'top',
+            padding: 4,
+        });
+        // max x = viewport.width - popup.width - padding = 1000 - 80 - 4 = 916
+        expect(r.x).toBe(916);
+    });
+    it('clamps cross-axis x to padding on the left edge', () => {
+        const farLeft = { x: 0, y: 200, width: 20, height: 40 };
+        const r = computePosition({ ...base, triggerRect: farLeft, placement: 'top', padding: 4 });
+        expect(r.x).toBe(4);
+    });
+});
+describe('computePosition arrowOffset', () => {
+    it('points the arrow at the trigger center for centered placement', () => {
+        const r = computePosition({ ...base, placement: 'bottom' });
+        // popup leading x = 210, trigger center x = 250 → arrowOffset = 40
+        expect(r.arrowOffset).toBe(40);
+    });
+    it('keeps the arrow pointing at the trigger even after cross-axis clamp', () => {
+        const farRight = { x: 980, y: 200, width: 40, height: 40 };
+        const r = computePosition({ ...base, triggerRect: farRight, placement: 'top', padding: 4 });
+        // trigger center x = 1000; popup leading x clamped to 916 → 84, clamped to popup-4 = 76
+        expect(r.arrowOffset).toBe(76);
+    });
+    it('pins the arrow near the aligned edge for start alignment by default', () => {
+        const r = computePosition({ ...base, placement: 'bottomStart' });
+        // default arrowEdgeDistance 12, measured from the leading (left) edge
+        expect(r.arrowOffset).toBe(12);
+    });
+    it('pins the arrow near the aligned edge for end alignment by default', () => {
+        const r = computePosition({ ...base, placement: 'bottomEnd' });
+        // popup width 80 − edgeDistance 12 = 68
+        expect(r.arrowOffset).toBe(68);
+    });
+    it('honors a custom arrowEdgeDistance', () => {
+        const r = computePosition({ ...base, placement: 'bottomStart', arrowEdgeDistance: 20 });
+        expect(r.arrowOffset).toBe(20);
+    });
+    it('points start-aligned arrow at the trigger center when arrowPointAtCenter', () => {
+        const r = computePosition({ ...base, placement: 'bottomStart', arrowPointAtCenter: true });
+        // popup leading x = trigger.x = 200; trigger center x = 250 → 50
+        expect(r.arrowOffset).toBe(50);
+    });
+    it('points end-aligned arrow at the trigger center when arrowPointAtCenter', () => {
+        const r = computePosition({ ...base, placement: 'bottomEnd', arrowPointAtCenter: true });
+        // popup leading x = 200+100−80 = 220; trigger center x = 250 → 30
+        expect(r.arrowOffset).toBe(30);
+    });
+});
+//# sourceMappingURL=floating.test.js.map

package/dist/floating.test.js.map

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

package/dist/focus-trap.d.ts

@@ -0,0 +1,24 @@
+export interface FocusTrap {
+    activate(): void;
+    deactivate(): void;
+}
+export interface FocusTrapOptions {
+    /**
+     * 是否捕获 Tab/Shift+Tab 做焦点循环。false 时仍执行进场聚焦与归还焦点，
+     * 但不拦截键盘 Tab（供 keyboard 总开关关闭键盘交互时使用）。默认 true。
+     */
+    trapTab?: boolean;
+    /**
+     * deactivate 时是否把焦点归还给激活前聚焦的元素。默认 true。
+     * 设 false 时不归还焦点（供 Popover returnFocus=false 等场景）。
+     */
+    returnFocus?: boolean;
+    /**
+     * 是否记忆 deactivate 时浮层内最后聚焦的元素，下次 activate 优先恢复到它
+     * （而非聚焦首个可聚焦元素）。默认 false。供 Popover rememberFocus 复用。
+     * 仅当被记忆的元素在重新 activate 时仍可聚焦才恢复，否则退回首个。
+     */
+    rememberFocus?: boolean;
+}
+export declare function useFocusTrap(container: HTMLElement, options?: FocusTrapOptions): FocusTrap;
+//# sourceMappingURL=focus-trap.d.ts.map

package/dist/focus-trap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-trap.d.ts","sourceRoot":"","sources":["../src/focus-trap.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,SAAS;IACxB,QAAQ,IAAI,IAAI,CAAC;IACjB,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,YAAY,CAC1B,SAAS,EAAE,WAAW,EACtB,OAAO,GAAE,gBAAqB,GAC7B,SAAS,CA0DX"}

package/dist/focus-trap.js

@@ -0,0 +1,64 @@
+/**
+ * useFocusTrap — trap Tab focus within a container, restore on release.
+ * Used by overlays (Modal/Drawer/Dropdown). See specs/00-foundation/a11y.spec.md.
+ */
+const FOCUSABLE = 'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
+export function useFocusTrap(container, options = {}) {
+    const { trapTab = true, returnFocus = true, rememberFocus = false } = options;
+    let previouslyFocused = null;
+    // rememberFocus：deactivate 时记下浮层内最后聚焦的元素，下次 activate 恢复。
+    let lastInnerFocused = null;
+    function getFocusable() {
+        return Array.from(container.querySelectorAll(FOCUSABLE)).filter((el) => el.offsetParent !== null || el === document.activeElement);
+    }
+    function onKeydown(e) {
+        if (e.key !== 'Tab')
+            return;
+        const items = getFocusable();
+        if (items.length === 0) {
+            e.preventDefault();
+            return;
+        }
+        const first = items[0];
+        const last = items[items.length - 1];
+        const active = document.activeElement;
+        if (e.shiftKey && active === first) {
+            e.preventDefault();
+            last.focus();
+        }
+        else if (!e.shiftKey && active === last) {
+            e.preventDefault();
+            first.focus();
+        }
+    }
+    return {
+        activate() {
+            previouslyFocused = document.activeElement;
+            if (trapTab)
+                container.addEventListener('keydown', onKeydown);
+            // rememberFocus：若记忆的元素仍在容器内且可聚焦，恢复到它；否则聚焦首个。
+            if (rememberFocus &&
+                lastInnerFocused &&
+                container.contains(lastInnerFocused) &&
+                lastInnerFocused.offsetParent !== null) {
+                lastInnerFocused.focus();
+            }
+            else {
+                getFocusable()[0]?.focus();
+            }
+        },
+        deactivate() {
+            if (trapTab)
+                container.removeEventListener('keydown', onKeydown);
+            // rememberFocus：归还焦点前记下浮层内当前焦点，供下次 activate 恢复。
+            if (rememberFocus) {
+                const active = document.activeElement;
+                lastInnerFocused = active && container.contains(active) ? active : null;
+            }
+            if (returnFocus)
+                previouslyFocused?.focus();
+            previouslyFocused = null;
+        },
+    };
+}
+//# sourceMappingURL=focus-trap.js.map

package/dist/focus-trap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-trap.js","sourceRoot":"","sources":["../src/focus-trap.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,SAAS,GACb,sIAAsI,CAAC;AA0BzI,MAAM,UAAU,YAAY,CAC1B,SAAsB,EACtB,UAA4B,EAAE;IAE9B,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,WAAW,GAAG,IAAI,EAAE,aAAa,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IAC9E,IAAI,iBAAiB,GAAuB,IAAI,CAAC;IACjD,yDAAyD;IACzD,IAAI,gBAAgB,GAAuB,IAAI,CAAC;IAEhD,SAAS,YAAY;QACnB,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAc,SAAS,CAAC,CAAC,CAAC,MAAM,CAC1E,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,KAAK,IAAI,IAAI,EAAE,KAAK,QAAQ,CAAC,aAAa,CAClE,CAAC;IACJ,CAAC;IAED,SAAS,SAAS,CAAC,CAAgB;QACjC,IAAI,CAAC,CAAC,GAAG,KAAK,KAAK;YAAE,OAAO;QAC5B,MAAM,KAAK,GAAG,YAAY,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,CAAC,CAAC,cAAc,EAAE,CAAC;YACnB,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QACxB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;QACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC;QACtC,IAAI,CAAC,CAAC,QAAQ,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;YACnC,CAAC,CAAC,cAAc,EAAE,CAAC;YACnB,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC;aAAM,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YAC1C,CAAC,CAAC,cAAc,EAAE,CAAC;YACnB,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IAED,OAAO;QACL,QAAQ;YACN,iBAAiB,GAAG,QAAQ,CAAC,aAAmC,CAAC;YACjE,IAAI,OAAO;gBAAE,SAAS,CAAC,gBAAgB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YAC9D,6CAA6C;YAC7C,IACE,aAAa;gBACb,gBAAgB;gBAChB,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC;gBACpC,gBAAgB,CAAC,YAAY,KAAK,IAAI,EACtC,CAAC;gBACD,gBAAgB,CAAC,KAAK,EAAE,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACN,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;YAC7B,CAAC;QACH,CAAC;QACD,UAAU;YACR,IAAI,OAAO;gBAAE,SAAS,CAAC,mBAAmB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YACjE,gDAAgD;YAChD,IAAI,aAAa,EAAE,CAAC;gBAClB,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAmC,CAAC;gBAC5D,gBAAgB,GAAG,MAAM,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;YAC1E,CAAC;YACD,IAAI,WAAW;gBAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;YAC5C,iBAAiB,GAAG,IAAI,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/form.d.ts

@@ -0,0 +1,131 @@
+export type FormValues = Record<string, unknown>;
+/** Validation message: a string, an i18n-key descriptor, or false/undefined for "no error". */
+export type ValidateResult = string | undefined;
+export interface Rule {
+    required?: boolean;
+    /** numeric / string-length / value-range checks */
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    type?: 'email' | 'url' | 'number';
+    /** sync or async custom validator; return an error message or undefined */
+    validator?: (value: unknown, values: FormValues) => ValidateResult | Promise<ValidateResult>;
+    /** override message for the built-in rule on this entry */
+    message?: string;
+    /**
+     * when true, a failure of THIS rule produces a non-blocking warning instead of
+     * an error: it surfaces a (yellow) hint but never fails `submit`. Mirrors AntD.
+     */
+    warningOnly?: boolean;
+}
+/**
+ * When validation should run. Spec §2 L26 / §4 L65. A single trigger or a list.
+ * `mount` runs once at registration; `change`/`blur` run on the matching event;
+ * `submit` only runs during submit(). The render layer reads `getFieldTrigger`
+ * to decide which DOM events to wire — core stays framework-free.
+ */
+export type ValidateTrigger = 'change' | 'blur' | 'submit' | 'mount';
+export interface FieldConfig {
+    rules?: Rule[];
+    initialValue?: unknown;
+    /** label used for interpolating default messages */
+    label?: string;
+    /**
+     * names of other fields this field's validation depends on. When any listed
+     * field's value changes (validate-on-change), this field is re-validated too —
+     * e.g. a "confirm password" field depends on ["password"].
+     */
+    dependencies?: string[];
+    /**
+     * field-level override of the form's `validateTrigger` (spec §4 L84). When
+     * omitted the field inherits the form default.
+     */
+    trigger?: ValidateTrigger | ValidateTrigger[];
+    /**
+     * pure transform applied to the field's value when collecting values for
+     * `getFieldsValue`/`submit` (spec §4.2 L88). Does NOT mutate state — the live
+     * `values` keep the raw value; only the collected payload is transformed.
+     */
+    transform?: (value: unknown, values: FormValues) => unknown;
+}
+export type FieldErrors = Record<string, string | undefined>;
+export interface FormState {
+    values: FormValues;
+    errors: FieldErrors;
+    /** non-blocking warnings (from `warningOnly` rules); never affect submit validity */
+    warnings: FieldErrors;
+    touched: Record<string, boolean>;
+    validating: Record<string, boolean>;
+    submitting: boolean;
+    submitCount: number;
+}
+/** message resolver: built-in messages are emitted as keyed descriptors so the
+ *  render layer can localize. We pass label/params so the layer can interpolate. */
+export interface MessageDescriptor {
+    key: string;
+    params?: Record<string, string | number>;
+    /** explicit override text (skips i18n) */
+    text?: string;
+}
+export interface FormOptions {
+    initialValues?: FormValues;
+    /** resolve a MessageDescriptor to a display string (i18n). Defaults to key. */
+    resolveMessage?: (d: MessageDescriptor) => string;
+    /**
+     * default validation trigger(s) for every field (spec §4 L65). Fields may
+     * override via `FieldConfig.trigger`. Defaults to `['blur','change']`.
+     */
+    validateTrigger?: ValidateTrigger | ValidateTrigger[];
+    /**
+     * stop running a field's rules at the first blocking error (spec §4 L68).
+     * Default `false`: every rule runs (so warnings keep accumulating and a later
+     * blocking rule can still win); the first blocking error is the surfaced one.
+     */
+    stopValidateWithError?: boolean;
+    /**
+     * keep empty-value field keys when collecting values for submit (spec §4 L70).
+     * Default `false`: keys whose value is `undefined`/`null`/`''` are dropped
+     * from the collected `values` payload.
+     */
+    allowEmpty?: boolean;
+}
+export interface FormApi {
+    getState(): FormState;
+    subscribe(listener: (state: FormState) => void): () => void;
+    registerField(name: string, config?: FieldConfig): () => void;
+    /**
+     * resolved validation triggers for a field: its own `trigger` override, else
+     * the form default. Always a normalized array (spec §4 L65/L84). The render
+     * layer uses this to decide which DOM events to wire.
+     */
+    getFieldTrigger(name: string): ValidateTrigger[];
+    getFieldValue(name: string): unknown;
+    setFieldValue(name: string, value: unknown, opts?: {
+        validate?: boolean;
+    }): void;
+    setFieldsValue(values: FormValues): void;
+    setFieldTouched(name: string, touched?: boolean): void;
+    getFieldError(name: string): string | undefined;
+    /** the field's non-blocking warning (from a `warningOnly` rule), if any */
+    getFieldWarning(name: string): string | undefined;
+    /** validate one field; resolves to its (blocking) error (or undefined) */
+    validateField(name: string): Promise<string | undefined>;
+    /** validate all (or given) fields; resolves to true when valid */
+    validate(names?: string[]): Promise<boolean>;
+    resetFields(): void;
+    /**
+     * collected values honoring `allowEmpty` (spec §4 L70): with `allowEmpty:false`
+     * keys whose value is empty (`undefined`/`null`/`''`) are dropped.
+     */
+    getFieldsValue(): FormValues;
+    /** run validation then resolve { valid, values, errors } */
+    submit(): Promise<{
+        valid: boolean;
+        values: FormValues;
+        errors: FieldErrors;
+    }>;
+}
+export declare function createForm(options?: FormOptions): FormApi;
+//# sourceMappingURL=form.d.ts.map

package/dist/form.d.ts.map

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