@luanlu/mk-motion 1.0.0

package/README.md

@@ -0,0 +1,120 @@
+# MotionKit
+
+一个轻量、现代的前端动效库，同时支持 **CSS 类动画** 和 **Web Animations API**。
+
+## 特性
+
+- 🎨 **15+ 预设动画**：fade、slide、zoom、bounce、flip、shake、pulse、rotate 等
+- 🔧 **双模式**：CSS 关键帧动画 + Web Animations API
+- 🌳 **Tree-shaking**：按需引入，不打包多余代码
+- 📘 **TypeScript**：完整的类型定义
+- 📦 **零依赖**：纯原生实现
+
+## 安装
+
+```bash
+npm install mk-motion
+```
+
+## 快速开始
+
+### 方式一：CSS 类（推荐简单场景）
+
+```html
+<div class="mk-animated mk-slideInUp">Hello World</div>
+```
+
+```css
+/* 自定义时长和缓动 */
+.my-box {
+  --mk-duration: 0.8s;
+  --mk-easing: cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+```
+
+### 方式二：JavaScript API
+
+```ts
+import { fadeIn, slideInUp, Animator } from 'mk-motion'
+
+// 快捷方法
+await fadeIn(document.querySelector('.box'))
+await slideInUp('.box', { duration: 600, easing: 'ease-out' })
+
+// 链式控制
+const anim = new Animator('.box')
+await anim.animate('bounceIn', { duration: 500 })
+anim.reset()
+```
+
+### 方式三：Web Animations API
+
+```ts
+import { Animator } from 'mk-motion'
+
+const anim = new Animator('.box')
+await anim.waa(
+  [
+    { transform: 'scale(1)', opacity: 1 },
+    { transform: 'scale(1.2)', opacity: 0.8 },
+    { transform: 'scale(1)', opacity: 1 },
+  ],
+  { duration: 300, iterations: 2 }
+)
+```
+
+## 预设动画列表
+
+| 动画 | 说明 |
+|------|------|
+| `fadeIn` / `fadeOut` | 淡入 / 淡出 |
+| `slideInUp` / `slideInDown` / `slideInLeft` / `slideInRight` | 从各方向滑入 |
+| `slideOutUp` / `slideOutDown` | 向上/下滑出 |
+| `zoomIn` / `zoomOut` | 缩放进入 / 退出 |
+| `bounceIn` / `bounceOut` | 弹跳进入 / 退出 |
+| `flipInX` / `flipInY` | 3D 翻转进入 |
+| `shake` | 左右摇晃 |
+| `pulse` | 脉冲缩放 |
+| `rotateIn` | 旋转进入 |
+
+## API
+
+### `new Animator(element)`
+
+| 方法 | 说明 |
+|------|------|
+| `.animate(name, options)` | 播放 CSS 预设动画 |
+| `.waa(keyframes, options)` | 使用 WAAPI 播放自定义关键帧 |
+| `.stop()` | 停止当前动画 |
+| `.reset()` | 移除所有动效类 |
+| `.vars({ duration: '1s' })` | 设置 CSS 变量 |
+
+### `AnimationOptions`
+
+```ts
+interface AnimationOptions {
+  duration?: number      // 毫秒，默认 500
+  easing?: string        // CSS easing，默认 'ease'
+  delay?: number         // 延迟毫秒
+  iterations?: number    // 次数，Infinity 为无限循环
+  direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse'
+  fill?: 'none' | 'forwards' | 'backwards' | 'both'
+}
+```
+
+## 构建
+
+```bash
+npm install
+npm run build
+```
+
+构建产物位于 `dist/`：
+- `mk-motion.js` — ES Module
+- `mk-motion.umd.cjs` — UMD（浏览器直接引用）
+- `style.css` — 动画样式
+- `index.d.ts` — 类型声明
+
+## 许可证
+
+MIT

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

@@ -0,0 +1,10 @@
+export declare class FocusTrap {
+    private container;
+    private previousActiveElement;
+    private listeners;
+    constructor(container: HTMLElement);
+    activate(initialFocus?: HTMLElement): void;
+    deactivate(): void;
+    private getFocusableElements;
+    private handleKeyDown;
+}

package/dist/a11y/keyboard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Keyboard navigation helpers for accessible components.
+ */
+export interface KeyHandler {
+    key: string;
+    handler: (e: KeyboardEvent) => void;
+    preventDefault?: boolean;
+}
+/**
+ * Attach keyboard handlers to an element.
+ * Returns a cleanup function.
+ */
+export declare function onKey(el: HTMLElement, handlers: KeyHandler[]): () => void;
+/**
+ * Common ARIA key patterns.
+ */
+export declare const Keys: {
+    readonly Enter: "Enter";
+    readonly Escape: "Escape";
+    readonly Tab: "Tab";
+    readonly ArrowUp: "ArrowUp";
+    readonly ArrowDown: "ArrowDown";
+    readonly ArrowLeft: "ArrowLeft";
+    readonly ArrowRight: "ArrowRight";
+    readonly Home: "Home";
+    readonly End: "End";
+    readonly Space: " ";
+};

package/dist/components/alert/alert.d.ts

@@ -0,0 +1,18 @@
+
+export interface AlertOptions {
+    type?: 'info' | 'success' | 'warning' | 'danger';
+    title?: string;
+    description?: string;
+    closable?: boolean;
+    showIcon?: boolean;
+    onClose?: () => void;
+}
+export declare class MkAlert {
+    el: HTMLDivElement;
+    private options;
+    constructor(container: HTMLElement | string, options?: AlertOptions);
+    private buildClass;
+    close(): void;
+    destroy(): void;
+}
+export declare function createAlert(container: HTMLElement | string, options?: AlertOptions): MkAlert;

package/dist/components/avatar/avatar.d.ts

@@ -0,0 +1,31 @@
+
+export interface AvatarOptions {
+    src?: string;
+    text?: string;
+    size?: 'small' | 'default' | 'large';
+    shape?: 'circle' | 'square';
+    icon?: string;
+}
+export declare class MkAvatar {
+    el: HTMLDivElement;
+    private options;
+    constructor(container: HTMLElement | string, options?: AvatarOptions);
+    private buildClass;
+    private showFallback;
+    setSrc(src: string): void;
+    setText(text: string): void;
+    destroy(): void;
+}
+export interface AvatarGroupOptions {
+    avatars: AvatarOptions[];
+    max?: number;
+    size?: 'small' | 'default' | 'large';
+}
+export declare class MkAvatarGroup {
+    el: HTMLDivElement;
+    private options;
+    constructor(container: HTMLElement | string, options: AvatarGroupOptions);
+    destroy(): void;
+}
+export declare function createAvatar(container: HTMLElement | string, options?: AvatarOptions): MkAvatar;
+export declare function createAvatarGroup(container: HTMLElement | string, options: AvatarGroupOptions): MkAvatarGroup;

package/dist/components/breadcrumb/breadcrumb.d.ts

@@ -0,0 +1,16 @@
+
+export interface BreadcrumbItem {
+    label: string;
+    href?: string;
+    onClick?: () => void;
+}
+export interface BreadcrumbOptions {
+    items: BreadcrumbItem[];
+    separator?: string | HTMLElement;
+}
+export declare class MkBreadcrumb {
+    el: HTMLElement;
+    constructor(container: HTMLElement | string, options: BreadcrumbOptions);
+    destroy(): void;
+}
+export declare function createBreadcrumb(container: HTMLElement | string, options: BreadcrumbOptions): MkBreadcrumb;

package/dist/components/button/button.d.ts

@@ -0,0 +1,28 @@
+import { MotionOptions } from '../../motion/component-motion.ts';
+
+export interface ButtonOptions {
+    type?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'text';
+    size?: 'default' | 'small' | 'large';
+    plain?: boolean;
+    round?: boolean;
+    circle?: boolean;
+    disabled?: boolean;
+    loading?: boolean;
+    text?: string;
+    icon?: string;
+    onClick?: (e: MouseEvent) => void;
+    motion?: MotionOptions;
+}
+export declare class MkButton {
+    el: HTMLButtonElement;
+    private options;
+    private motion;
+    constructor(container: HTMLElement | string, options?: ButtonOptions);
+    private buildClass;
+    private createRipple;
+    setLoading(loading: boolean): void;
+    setDisabled(disabled: boolean): void;
+    private updateAriaDisabled;
+    destroy(): void;
+}
+export declare function createButton(container: HTMLElement | string, options?: ButtonOptions): MkButton;

package/dist/components/card/card.d.ts

@@ -0,0 +1,19 @@
+import { MotionOptions } from '../../motion/component-motion.ts';
+
+export interface CardOptions {
+    title?: string;
+    body?: string;
+    footer?: string;
+    image?: string;
+    shadow?: 'always' | 'hover' | 'never';
+    loading?: boolean;
+    motion?: MotionOptions;
+}
+export declare class MkCard {
+    el: HTMLDivElement;
+    private motion;
+    constructor(container: HTMLElement | string, options?: CardOptions);
+    setLoading(loading: boolean): void;
+    destroy(): void;
+}
+export declare function createCard(container: HTMLElement | string, options?: CardOptions): MkCard;

package/dist/components/collapse/collapse.d.ts

@@ -0,0 +1,23 @@
+
+export interface CollapseItem {
+    title: string;
+    content: string | HTMLElement;
+    disabled?: boolean;
+}
+export interface CollapsePanelOptions {
+    items: CollapseItem[];
+    accordion?: boolean;
+    activeKeys?: number[];
+}
+export declare class MkCollapse {
+    el: HTMLDivElement;
+    private options;
+    private activeKeys;
+    private itemEls;
+    constructor(container: HTMLElement | string, options: CollapsePanelOptions);
+    private toggle;
+    private updateItemState;
+    setActiveKeys(keys: number[]): void;
+    destroy(): void;
+}
+export declare function createCollapse(container: HTMLElement | string, options: CollapsePanelOptions): MkCollapse;

package/dist/components/dialog/dialog.d.ts

@@ -0,0 +1,27 @@
+
+export interface DialogOptions {
+    title?: string;
+    content?: string | HTMLElement;
+    showClose?: boolean;
+    showCancel?: boolean;
+    center?: boolean;
+    cancelText?: string;
+    confirmText?: string;
+    onConfirm?: () => void;
+    onCancel?: () => void;
+    onClose?: () => void;
+}
+export declare class MkDialog {
+    private overlay;
+    private dialog;
+    private options;
+    private focusTrap;
+    private escapeCleanup;
+    private confirmBtn;
+    private titleId;
+    constructor(options?: DialogOptions);
+    open(): void;
+    close(): void;
+    destroy(): void;
+}
+export declare function createDialog(options?: DialogOptions): MkDialog;

package/dist/components/drawer/drawer.d.ts

@@ -0,0 +1,21 @@
+
+export interface DrawerOptions {
+    title?: string;
+    content?: string | HTMLElement;
+    direction?: 'right' | 'left' | 'top' | 'bottom';
+    size?: number;
+    showClose?: boolean;
+    onClose?: () => void;
+}
+export declare class MkDrawer {
+    private overlay;
+    private drawer;
+    private options;
+    private focusTrap;
+    private escapeCleanup;
+    constructor(options?: DrawerOptions);
+    open(): void;
+    close(): void;
+    destroy(): void;
+}
+export declare function createDrawer(options?: DrawerOptions): MkDrawer;

package/dist/components/empty/empty.d.ts

@@ -0,0 +1,14 @@
+
+export interface EmptyOptions {
+    description?: string;
+    image?: string | 'default';
+    imageStyle?: Partial<CSSStyleDeclaration>;
+}
+export declare class MkEmpty {
+    el: HTMLDivElement;
+    private options;
+    constructor(container: HTMLElement | string, options?: EmptyOptions);
+    setDescription(text: string): void;
+    destroy(): void;
+}
+export declare function createEmpty(container: HTMLElement | string, options?: EmptyOptions): MkEmpty;

package/dist/components/form/checkbox.d.ts

@@ -0,0 +1,27 @@
+
+export interface CheckboxOptions {
+    label?: string;
+    checked?: boolean;
+    disabled?: boolean;
+    onChange?: (checked: boolean) => void;
+}
+export declare class MkCheckbox {
+    el: HTMLLabelElement;
+    private options;
+    private _checked;
+    private _cleanupKey?;
+    constructor(container: HTMLElement | string, options?: CheckboxOptions);
+    get checked(): boolean;
+    set checked(v: boolean);
+    toggle(): void;
+    destroy(): void;
+}
+export declare function createCheckbox(container: HTMLElement | string, options?: CheckboxOptions): MkCheckbox;
+export declare class MkCheckboxGroup {
+    el: HTMLDivElement;
+    private checkboxes;
+    constructor(container: HTMLElement | string);
+    add(options: CheckboxOptions): MkCheckbox;
+    getValues(): boolean[];
+    destroy(): void;
+}

package/dist/components/form/radio.d.ts

@@ -0,0 +1,32 @@
+
+export interface RadioOptions {
+    label?: string;
+    value: string | number;
+    checked?: boolean;
+    disabled?: boolean;
+    onChange?: (value: string | number) => void;
+}
+export declare class MkRadio {
+    el: HTMLLabelElement;
+    private options;
+    private _checked;
+    constructor(container: HTMLElement | string, options: RadioOptions);
+    setChecked(checked: boolean): void;
+    getValue(): string | number;
+    destroy(): void;
+}
+export declare class MkRadioGroup {
+    el: HTMLDivElement;
+    private radios;
+    private _value;
+    private _cleanupKey?;
+    constructor(container: HTMLElement | string, options?: {
+        value?: string | number;
+        onChange?: (value: string | number) => void;
+    });
+    add(radioOptions: Omit<RadioOptions, 'onChange'>): MkRadio;
+    setValue(value: string | number): void;
+    getValue(): string | number | undefined;
+    private focusRadio;
+    destroy(): void;
+}

package/dist/components/form/select.d.ts

@@ -0,0 +1,32 @@
+
+export interface SelectOption {
+    label: string;
+    value: string | number;
+    disabled?: boolean;
+}
+export interface SelectOptions {
+    placeholder?: string;
+    options: SelectOption[];
+    value?: string | number;
+    onChange?: (value: string | number) => void;
+}
+export declare class MkSelect {
+    el: HTMLDivElement;
+    private trigger;
+    private dropdown;
+    private options;
+    private _value;
+    private isOpen;
+    private _cleanupKey?;
+    constructor(container: HTMLElement | string, options: SelectOptions);
+    private updateLabel;
+    get value(): string | number | undefined;
+    setValue(v: string | number): void;
+    private renderOptions;
+    private toggle;
+    open(): void;
+    close(): void;
+    private moveSelection;
+    destroy(): void;
+}
+export declare function createSelect(container: HTMLElement | string, options: SelectOptions): MkSelect;

package/dist/components/form/slider.d.ts

@@ -0,0 +1,31 @@
+
+export interface SliderOptions {
+    min?: number;
+    max?: number;
+    step?: number;
+    value?: number;
+    showValue?: boolean;
+    onChange?: (value: number) => void;
+}
+export declare class MkSlider {
+    el: HTMLDivElement;
+    private track;
+    private fill;
+    private thumb;
+    private valueEl?;
+    private options;
+    private _value;
+    private dragging;
+    private _cleanupKey?;
+    constructor(container: HTMLElement | string, options?: SliderOptions);
+    private onStart;
+    private onMove;
+    private onEnd;
+    private updateFromPosition;
+    get value(): number;
+    set value(v: number);
+    private updateUI;
+    private updateAria;
+    private adjustValue;
+    destroy(): void;
+}

package/dist/components/input/input.d.ts

@@ -0,0 +1,31 @@
+import { MotionOptions } from '../../motion/component-motion.ts';
+
+export interface InputOptions {
+    placeholder?: string;
+    type?: string;
+    value?: string;
+    disabled?: boolean;
+    clearable?: boolean;
+    showPassword?: boolean;
+    validate?: (value: string) => string | null;
+    onInput?: (value: string) => void;
+    onEnter?: (value: string) => void;
+    motion?: MotionOptions;
+}
+export declare class MkInput {
+    el: HTMLDivElement;
+    input: HTMLInputElement;
+    private options;
+    private errorMsg;
+    private motion;
+    constructor(container: HTMLElement | string, options?: InputOptions);
+    get value(): string;
+    set value(v: string);
+    validate(): boolean;
+    showError(msg: string): void;
+    showSuccess(): void;
+    clearError(): void;
+    focus(): void;
+    destroy(): void;
+}
+export declare function createInput(container: HTMLElement | string, options?: InputOptions): MkInput;

package/dist/components/layout/divider.d.ts

@@ -0,0 +1,12 @@
+
+export interface DividerOptions {
+    text?: string;
+    direction?: 'horizontal' | 'vertical';
+    dashed?: boolean;
+}
+export declare class MkDivider {
+    el: HTMLDivElement;
+    constructor(container: HTMLElement | string, options?: DividerOptions);
+    destroy(): void;
+}
+export declare function createDivider(container: HTMLElement | string, options?: DividerOptions): MkDivider;

package/dist/components/layout/row.d.ts

@@ -0,0 +1,14 @@
+
+export interface RowOptions {
+    gutter?: number;
+    justify?: 'start' | 'center' | 'end' | 'space-between' | 'space-around';
+    align?: 'top' | 'middle' | 'bottom';
+    wrap?: boolean;
+}
+export declare class MkRow {
+    el: HTMLDivElement;
+    constructor(container: HTMLElement | string, options?: RowOptions);
+    addCol(span: number | 'flex', content?: string | HTMLElement, className?: string): HTMLDivElement;
+    destroy(): void;
+}
+export declare function createRow(container: HTMLElement | string, options?: RowOptions): MkRow;

package/dist/components/layout/space.d.ts

@@ -0,0 +1,13 @@
+
+export interface SpaceOptions {
+    direction?: 'horizontal' | 'vertical';
+    size?: 'small' | 'default' | 'large';
+    wrap?: boolean;
+}
+export declare class MkSpace {
+    el: HTMLDivElement;
+    constructor(container: HTMLElement | string, options?: SpaceOptions);
+    add(content: string | HTMLElement): void;
+    destroy(): void;
+}
+export declare function createSpace(container: HTMLElement | string, options?: SpaceOptions): MkSpace;

package/dist/components/loading/loading.d.ts

@@ -0,0 +1,8 @@
+
+export interface LoadingOptions {
+    text?: string;
+    fullscreen?: boolean;
+    target?: HTMLElement | string;
+}
+export declare function showLoading(options?: LoadingOptions): () => void;
+export declare function showFullscreenLoading(text?: string): () => void;

package/dist/components/menu/menu.d.ts

@@ -0,0 +1,30 @@
+
+export interface MenuItem {
+    index: string;
+    label: string;
+    icon?: string;
+    disabled?: boolean;
+    children?: MenuItem[];
+}
+export interface MenuOptions {
+    mode?: 'vertical' | 'horizontal';
+    items: MenuItem[];
+    defaultActive?: string;
+    defaultOpeneds?: string[];
+    collapse?: boolean;
+    onSelect?: (index: string) => void;
+    onOpen?: (index: string) => void;
+    onClose?: (index: string) => void;
+}
+export declare class MkMenu {
+    el: HTMLElement;
+    private options;
+    private openeds;
+    private activeIndex;
+    constructor(container: HTMLElement | string, options: MenuOptions);
+    private render;
+    private renderItem;
+    private setupKeyboard;
+    destroy(): void;
+}
+export declare function createMenu(container: HTMLElement | string, options: MenuOptions): MkMenu;

package/dist/components/message/message.d.ts

@@ -0,0 +1,10 @@
+
+export interface MessageOptions {
+    type?: 'success' | 'warning' | 'error' | 'info';
+    duration?: number;
+    closable?: boolean;
+}
+export declare function message(msg: string, options?: MessageOptions): () => void;
+export declare function messageSuccess(msg: string, options?: Omit<MessageOptions, 'type'>): () => void;
+export declare function messageError(msg: string, options?: Omit<MessageOptions, 'type'>): () => void;
+export declare function messageWarning(msg: string, options?: Omit<MessageOptions, 'type'>): () => void;

package/dist/components/popover/popover.d.ts

@@ -0,0 +1,31 @@
+
+export interface PopoverOptions {
+    content?: string | HTMLElement;
+    title?: string;
+    placement?: 'top' | 'bottom' | 'left' | 'right';
+    trigger?: 'click' | 'hover';
+    width?: number;
+    offset?: number;
+}
+export declare class MkPopover {
+    el: HTMLDivElement;
+    private options;
+    private popoverEl;
+    private arrowEl;
+    private contentEl;
+    private showTimer;
+    private hideTimer;
+    private isVisible;
+    private cleanupFns;
+    private focusTrap;
+    private escapeCleanup;
+    constructor(target: HTMLElement, options?: PopoverOptions);
+    private buildPopover;
+    private position;
+    show(): void;
+    hide(): void;
+    toggle(): void;
+    setContent(content: string | HTMLElement): void;
+    destroy(): void;
+}
+export declare function createPopover(target: HTMLElement, options?: PopoverOptions): MkPopover;

package/dist/components/progress/progress.d.ts

@@ -0,0 +1,25 @@
+
+export interface ProgressOptions {
+    type?: 'line' | 'circle' | 'dashboard';
+    percent?: number;
+    strokeWidth?: number;
+    color?: string;
+    status?: 'success' | 'exception' | 'active';
+    showInfo?: boolean;
+}
+export declare class MkProgress {
+    el: HTMLDivElement;
+    private options;
+    private barEl;
+    private textEl;
+    private circleSvg;
+    private circleTrack;
+    private circlePath;
+    constructor(container: HTMLElement | string, options?: ProgressOptions);
+    private buildClass;
+    private renderLine;
+    private renderCircleOrDashboard;
+    setPercent(percent: number): void;
+    destroy(): void;
+}
+export declare function createProgress(container: HTMLElement | string, options?: ProgressOptions): MkProgress;