vanilla-jui 1.3.10 → 1.4.0

package/src/core/{Component.js → Component.ts}

@@ -1,24 +1,109 @@
 import { createDeepStore, flushSync } from 'vanilla-signal';
 
-import { createEventManager } from '../utilities/events.js';
+import { createEventManager } from '../utilities/events.ts';
+
+export type ComponentProps = Record<string, unknown>;
+export type ComponentState = Record<string, unknown>;
+export interface ComponentDOM {
+  root: Element | null;
+  [key: string]: unknown;
+}
+
+export interface ComponentRuntime {
+  destroyed: boolean;
+}
+
+export interface ComponentUpdateOptions {
+  force?: boolean;
+}
+
+export type ComponentLifecycleEvent =
+  | 'init'
+  | 'beforeUpdate'
+  | 'afterUpdate'
+  | 'destroy';
+export type ComponentEventName = string;
+export type ComponentListener = (...args: unknown[]) => void;
+export type ComponentListeners = Record<
+  ComponentLifecycleEvent,
+  ComponentListener[]
+> &
+  Record<string, ComponentListener[] | undefined>;
+
+export type ComponentCleanup =
+  | void
+  | (() => void)
+  | {
+      destroy: () => void;
+    };
+
+export type ComponentPluginOptions = Record<string, unknown> | undefined;
+export type ComponentPlugin<TComponent = Component> =
+  | ((
+      instance: TComponent,
+      options?: ComponentPluginOptions
+    ) => ComponentCleanup)
+  | {
+      install: (
+        instance: TComponent,
+        options?: ComponentPluginOptions
+      ) => ComponentCleanup;
+    };
+
+export interface ComponentCleanupRegistry {
+  events: ReturnType<typeof createEventManager>;
+  plugins: Map<ComponentPlugin<unknown>, ComponentCleanup>;
+  [key: string]: unknown;
+}
+
+function isPlainObject(value: unknown): value is ComponentProps {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
 
 /**
  * 轻量级组件基类，集成 vanilla-signal 响应式状态和插件系统
  * 为所有 UI 组件提供统一的状态管理、生命周期钩子和插件支持
  */
-export default class Component {
+export default class Component<
+  TProps extends ComponentProps = ComponentProps,
+  TState extends ComponentState = ComponentState,
+  TDOM extends ComponentDOM = ComponentDOM,
+> {
   /** 全局插件注册表，所有新创建的组件实例会自动安装这些插件 */
-  static globalPlugins = new Map();
+  static globalPlugins = new Map<string, ComponentPlugin<Component>>();
+
+  /** 组件属性配置对象 */
+  props: TProps;
+
+  /** DOM 引用容器，存储根元素及其他 DOM 节点引用 */
+  dom: TDOM;
+
+  /** 已安装的插件映射表 */
+  plugins: Map<ComponentPlugin<unknown>, ComponentCleanup>;
+
+  /** 资源清理管理器，包含事件监听器和插件的清理函数 */
+  cleanup: ComponentCleanupRegistry;
+
+  /** 内部事件监听器注册表，用于生命周期和自定义事件 */
+  protected _listeners: ComponentListeners;
+
+  /** 响应式状态存储，使用 vanilla-signal 的深层响应式 store */
+  state: TState | null;
+
+  /** 运行时状态标记 */
+  runtime: ComponentRuntime;
 
   /**
    * @param {Object} props - 组件初始属性配置
    */
-  constructor(props = {}) {
+  constructor(props: TProps = {} as TProps) {
     /** 组件属性配置对象 */
-    this.props = props || {};
+    this.props = (props || {}) as TProps;
 
     /** DOM 引用容器，存储根元素及其他 DOM 节点引用 */
-    this.dom = { root: null };
+    this.dom = { root: null } as TDOM;
 
     /** 已安装的插件映射表 */
     this.plugins = new Map();
@@ -35,7 +120,7 @@ export default class Component {
     };
 
     /** 响应式状态存储，使用 vanilla-signal 的深层响应式 store */
-    this.state = createDeepStore({});
+    this.state = createDeepStore({} as TState);
 
     /** 运行时状态标记 */
     this.runtime = { destroyed: false };
@@ -48,7 +133,7 @@ export default class Component {
    * 获取组件的根 DOM 元素
    * @returns {HTMLElement|null} 根 DOM 元素或 null
    */
-  get root() {
+  get root(): Element | null {
     return this.dom?.root || null;
   }
 
@@ -56,8 +141,8 @@ export default class Component {
    * 设置组件的根 DOM 元素
    * @param {HTMLElement} value - 要设置的根 DOM 元素
    */
-  set root(value) {
-    if (!this.dom) this.dom = {};
+  set root(value: Element | null) {
+    if (!this.dom) this.dom = { root: null } as TDOM;
     this.dom.root = value;
   }
 
@@ -69,13 +154,16 @@ export default class Component {
    * @param {Object} [options] - 插件配置选项
    * @returns {Component} 返回当前实例，支持链式调用
    */
-  use(plugin, options) {
+  use(
+    plugin: ComponentPlugin<this> | null | undefined,
+    options?: ComponentPluginOptions
+  ): this {
     if (!plugin) return this;
     const cleanup =
       typeof plugin === 'function'
         ? plugin(this, options)
         : plugin.install?.(this, options);
-    this.cleanup.plugins.set(plugin, cleanup);
+    this.cleanup.plugins.set(plugin as ComponentPlugin<unknown>, cleanup);
     return this;
   }
 
@@ -86,7 +174,7 @@ export default class Component {
    * @param {Function} callback - 事件回调函数
    * @returns {Component} 返回当前实例，支持链式调用
    */
-  on(event, callback) {
+  on(event: ComponentEventName, callback: ComponentListener): this {
     if (!this._listeners[event] || typeof callback !== 'function') return this;
     this._listeners[event].push(callback);
     return this;
@@ -98,7 +186,7 @@ export default class Component {
    * @param {Function} callback - 要移除的回调函数引用
    * @returns {Component} 返回当前实例，支持链式调用
    */
-  off(event, callback) {
+  off(event: ComponentEventName, callback: ComponentListener): this {
     if (!this._listeners[event]) return this;
     this._listeners[event] = this._listeners[event].filter(
       (listener) => listener !== callback
@@ -111,9 +199,9 @@ export default class Component {
    * 遍历全局插件注册表并依次安装
    * @private
    */
-  installGlobalPlugins() {
+  installGlobalPlugins(): void {
     for (const plugin of Component.globalPlugins.values()) {
-      this.use(plugin);
+      this.use(plugin as ComponentPlugin<this>);
     }
   }
 
@@ -124,7 +212,10 @@ export default class Component {
    * @param {string} name - 插件名称标识
    * @param {Function|Object} plugin - 插件函数或插件对象
    */
-  static useGlobal(name, plugin) {
+  static useGlobal(
+    name: string | null | undefined,
+    plugin: ComponentPlugin<Component> | null | undefined
+  ): void {
     if (!name || !plugin) return;
     Component.globalPlugins.set(name, plugin);
   }
@@ -135,7 +226,7 @@ export default class Component {
    * @param {...*} args - 传递给监听器的参数
    * @returns {Component} 返回当前实例，支持链式调用
    */
-  emit(event, ...args) {
+  emit(event: ComponentEventName, ...args: unknown[]): this {
     const listeners = this._listeners[event];
     if (!listeners) return this;
     for (const listener of listeners) {
@@ -155,10 +246,10 @@ export default class Component {
    * @returns {Component} 返回当前实例，支持链式调用
    * @throws {Error} 如果组件已被销毁则抛出异常
    */
-  init(props = {}) {
+  init(props: Partial<TProps> | null | undefined = {}): this {
     if (this.runtime.destroyed)
       throw new Error('Component.init: instance destroyed');
-    if (props && typeof props === 'object' && !Array.isArray(props)) {
+    if (isPlainObject(props)) {
       this.props = Object.assign({}, this.props, props);
     }
     if (typeof this.onInit === 'function') this.onInit(this.props);
@@ -175,7 +266,12 @@ export default class Component {
    * @returns {Component} 返回当前实例，支持链式调用
    * @throws {Error} 如果组件已被销毁或参数格式不正确则抛出异常
    */
-  setState(keyOrPatch = {}, value) {
+  setState(patch?: Partial<TState> | null): this;
+  setState<TKey extends keyof TState>(key: TKey, value: TState[TKey]): this;
+  setState(
+    keyOrPatch: Partial<TState> | keyof TState | null | undefined = {},
+    value?: unknown
+  ): this {
     if (this.runtime.destroyed)
       throw new Error('Component.setState: instance destroyed');
 
@@ -183,13 +279,14 @@ export default class Component {
       typeof keyOrPatch === 'string' && arguments.length > 1
         ? { [keyOrPatch]: value }
         : keyOrPatch;
-    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+    if (!isPlainObject(patch)) {
       throw new Error('Component.setState: expects a plain object patch.');
     }
 
     flushSync(() => {
       for (const [k, v] of Object.entries(patch)) {
-        this.state[k] = v;
+        if (!this.state) return;
+        this.state[k as keyof TState] = v as TState[keyof TState];
       }
     });
     return this;
@@ -205,10 +302,13 @@ export default class Component {
    * @returns {Component} 返回当前实例，支持链式调用
    * @throws {Error} 如果组件已被销毁则抛出异常
    */
-  update(propsPatch = {}, { force = false } = {}) {
+  update(
+    propsPatch: Partial<TProps> | null | undefined = {},
+    { force = false }: ComponentUpdateOptions = {}
+  ): this {
     if (this.runtime.destroyed)
       throw new Error('Component.update: instance destroyed');
-    if (propsPatch && typeof propsPatch === 'object') {
+    if (isPlainObject(propsPatch)) {
       this.props = Object.assign({}, this.props, propsPatch);
     }
     this.emit('beforeUpdate', propsPatch, { force });
@@ -223,7 +323,7 @@ export default class Component {
    * 执行 onDestroy 钩子，触发 destroy 事件，清理所有插件和资源
    * 这是组件生命周期的最后一步，销毁后实例不可再使用
    */
-  destroy() {
+  destroy(): void {
     if (this.runtime.destroyed) return;
     this.runtime = { destroyed: true };
 
@@ -242,7 +342,14 @@ export default class Component {
     }
     this.cleanup.plugins.clear();
     this.cleanup.events.clear();
-    this.dom = { root: null };
+    this.dom = { root: null } as TDOM;
     this.state = null;
   }
+
+  protected onInit?(props: TProps): void;
+  protected onUpdate?(
+    propsPatch: Partial<TProps> | null | undefined,
+    options: Required<ComponentUpdateOptions>
+  ): void;
+  protected onDestroy?(): void;
 }

package/src/css/accordion.css

@@ -9,7 +9,7 @@
     align-items: center;
     cursor: pointer;
     padding: var(--accordion-header-padding,
-        calc(var(--space) * 2) calc(var(--space) * 3));
+        var(--s2) var(--s3));
     margin: var(--accordion-header-margin, 0);
     border-bottom: var(--accordion-border);
     font-size: var(--accordion-header-font-size, var(--font-size-md));
@@ -61,7 +61,7 @@
   .j-accordion .accordion-panel .panel-content {
     margin: var(--accordion-panel-content-margin, 0);
     padding: var(--accordion-panel-content-padding,
-        0 calc(var(--space) * 3) calc(var(--space) * 2));
+        0 var(--s3) var(--s2));
     border-bottom: var(--accordion-border);
     font-size: var(--accordion-font-size, var(--font-size-md));
   }

package/src/css/animation.css

@@ -1,4 +1,5 @@
 @layer animation {
+
   /* none */
   .animate-none {
     animation: none;
@@ -21,6 +22,7 @@
   }
 
   @keyframes animate-ping {
+
     75%,
     100% {
       transform: scale(2);
@@ -45,6 +47,7 @@
   }
 
   @keyframes animate-bounce {
+
     0%,
     100% {
       transform: translateY(-25%);
@@ -97,6 +100,7 @@
   }
 
   @keyframes animate-shake {
+
     0%,
     100% {
       transform: translateX(0);
@@ -174,4 +178,30 @@
       transform: translateX(-100%);
     }
   }
-}
+
+  /* reveal */
+  [data-reveal] {
+    opacity: 0;
+    transform: translateY(12px);
+    animation: reveal 0.62s ease forwards;
+  }
+
+  [data-reveal='2'] {
+    animation-delay: 0.08s;
+  }
+
+  [data-reveal='3'] {
+    animation-delay: 0.14s;
+  }
+
+  [data-reveal='4'] {
+    animation-delay: 0.2s;
+  }
+
+  @keyframes reveal {
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+}

package/src/css/breadcrumb.css

@@ -74,7 +74,7 @@
     justify-content: center;
     gap: var(--space);
     color: var(--breadcrumb-link-color, var(--tone-text));
-    padding: var(--breadcrumb-item-padding-vertical, 0) var(--breadcrumb-item-padding-horizontal, calc(var(--space) * 2));
+    padding: var(--breadcrumb-item-padding-vertical, 0) var(--breadcrumb-item-padding-horizontal, var(--s2));
     text-decoration: none;
   }
 

package/src/css/button.css

@@ -4,7 +4,7 @@
     justify-content: center;
     align-items: center;
     flex-wrap: nowrap;
-    gap: var(--button-gap, calc(var(--space) * 1) calc(var(--space) * 1.5));
+    gap: var(--button-gap, var(--space) calc(var(--space) * 1.5));
     position: relative;
     white-space: nowrap;
     font-weight: var(--button-font-weight, var(--font-medium));
@@ -12,7 +12,7 @@
     height: var(--button-height, var(--el-height-md));
     line-height: var(--button-line-height, var(--line-height-self));
     background-color: var(--button-background, transparent);
-    padding: var(--button-padding, 0 calc(var(--space) * 3));
+    padding: var(--button-padding, 0 var(--s3));
     border-width: var(--button-border-width, 1px);
     border-style: var(--button-border-style, solid);
     border-color: var(--button-border-color, transparent);
@@ -42,13 +42,13 @@
   .j-button.is-sm {
     font-size: var(--font-size-sm);
     height: var(--button-height-sm, var(--el-height-sm));
-    padding: var(--button-padding-sm, calc(var(--space) * 1) calc(var(--space) * 2));
+    padding: var(--button-padding-sm, var(--space) var(--s2));
   }
 
   .j-button.is-lg {
     font-size: var(--font-size-lg);
     height: var(--button-height-lg, var(--el-height-lg));
-    padding: var(--button-padding-lg, calc(var(--space) * 3) calc(var(--space) * 4));
+    padding: var(--button-padding-lg, var(--s3) var(--s4));
   }
 
   /* variant */
@@ -136,7 +136,7 @@
 
   /* group */
   .j-button-group {
-    --button-padding: 0 calc(var(--space) * 2);
+    --button-padding: 0 var(--s2);
     display: flex;
     margin: 0;
   }

package/src/css/card.css

@@ -29,7 +29,7 @@
     color: var(--card-header-color, var(--ui-fg));
     font-size: var(--font-size-md);
     font-weight: var(--card-header-weight, var(--font-medium));
-    padding: var(--card-header-padding, calc(var(--space) * 3) calc(var(--space) * 4));
+    padding: var(--card-header-padding, var(--s3) var(--s4));
     margin: 0;
   }
 
@@ -43,7 +43,7 @@
     border: none;
     margin: 0;
     padding: 0;
-    padding: var(--card-header-padding, calc(var(--space) * 1) calc(var(--space) * 2));
+    padding: var(--card-header-padding, var(--space) var(--s2));
     appearance: none;
     cursor: pointer;
   }
@@ -84,7 +84,7 @@
 
   .j-card .card-content {
     background-color: var(--card-content-background);
-    padding: var(--card-content-padding, calc(var(--space) * 4));
+    padding: var(--card-content-padding, var(--s4));
     line-height: var(--line-height-paragraph);
   }
 
@@ -118,8 +118,8 @@
   .j-card.is-vertical .card-header {
     flex-direction: column;
     align-items: flex-start;
-    gap: calc(var(--space) * 2);
-    padding: var(--card-header-padding, calc(var(--space) * 4) calc(var(--space) * 4) 0);
+    gap: var(--s2);
+    padding: var(--card-header-padding, var(--s4) var(--s4) 0);
   }
 
   .j-card.is-vertical .card-header .header-title {
@@ -138,7 +138,7 @@
 
   .j-card .card-footer {
     border-top: none;
-    padding: var(--vertical-card-footer-padding, calc(var(--space) * 4));
+    padding: var(--vertical-card-footer-padding, var(--s4));
   }
 
   .j-card .card-content+.card-footer {
@@ -146,6 +146,6 @@
   }
 
   .j-card .card-footer:has(.j-button-group) {
-    padding-top: 2px;
+    padding-top: 4px;
   }
 }