vanilla-jui 1.4.5 → 1.4.6

package/src/components/toc.ts

@@ -4,14 +4,12 @@ import Component, {
   type ComponentDOM,
   type ComponentRuntime,
 } from '../core/Component.ts';
-import {
-  type ResolveSchema,
-  randomId,
-  resolveProps,
-} from '../utilities/core.ts';
+import { joinClasses } from '../utilities/class-name.ts';
 import { type DOMReference, all, requireContainer } from '../utilities/dom.ts';
+import { randomId } from '../utilities/id.ts';
+import { type ResolveSchema, resolveProps } from '../utilities/types.ts';
 
-export interface TocClassNames {
+interface TocClassNames {
   toc: string;
   list: string;
   link: string;
@@ -19,36 +17,38 @@ export interface TocClassNames {
   levelPrefix: string;
 }
 
-export type TocClassNameConfig = Partial<TocClassNames>;
+type TocClassNameConfig = Partial<TocClassNames>;
 
-export interface TocItem {
+interface TocItem {
   id: string;
   text: string;
   level: number;
   element: HTMLHeadingElement;
 }
 
-export interface TocCurrent {
+interface TocCurrent {
   index: number;
   item: TocItem | null;
 }
 
-export interface TocProps extends Record<string, unknown> {
-  container?: DOMReference;
+interface TocProps extends Record<string, unknown> {
   target?: DOMReference;
   headings?: string;
   offset?: number;
   className?: TocClassNameConfig;
-  onUpdate?: ((item: TocItem | null, index: number, toc: Toc) => void) | null;
+  onChange?:
+    | ((item: TocItem | null, index: number, toc: TocInstance) => void)
+    | null;
 }
 
 interface ResolvedTocProps extends Record<string, unknown> {
-  container: DOMReference;
   target: DOMReference;
   headings: string;
   offset: number;
   className: TocClassNames;
-  onUpdate: ((item: TocItem | null, index: number, toc: Toc) => void) | null;
+  onChange:
+    | ((item: TocItem | null, index: number, toc: TocInstance) => void)
+    | null;
 }
 
 interface TocState extends Record<string, unknown> {
@@ -58,7 +58,6 @@ interface TocState extends Record<string, unknown> {
 
 interface TocDOM extends ComponentDOM {
   root: HTMLElement | null;
-  container: Element | null;
   target: Element | null;
   list: HTMLElement | null;
   headings: HTMLHeadingElement[];
@@ -75,6 +74,13 @@ interface TocScrollOptions {
   updateHash?: boolean;
 }
 
+type TocInstance = Component<ResolvedTocProps, TocState, TocDOM> & {
+  runtime: TocRuntime;
+  build(): TocInstance;
+  refresh(): TocInstance;
+  activate(index: number): TocInstance;
+};
+
 const DEFAULT_CLASS_NAMES: TocClassNames = {
   toc: 'j-toc',
   list: 'toc-list',
@@ -84,14 +90,12 @@ const DEFAULT_CLASS_NAMES: TocClassNames = {
 };
 
 const TOC_PROPS_SCHEMA = {
-  container: { default: null },
   target: { default: '.j-content' },
   headings: { default: 'h2, h3', type: 'string' },
   offset: {
     default: 80,
     type: 'number',
-    validate: (value) => typeof value === 'number' && value >= 0,
-    message: 'expects a positive number or 0.',
+    min: 0,
   },
   className: {
     default: DEFAULT_CLASS_NAMES,
@@ -101,7 +105,7 @@ const TOC_PROPS_SCHEMA = {
       ...(value && typeof value === 'object' ? value : {}),
     }),
   },
-  onUpdate: { default: null, types: ['function', 'null'] },
+  onChange: { default: null, types: ['function', 'null'] },
 } satisfies ResolveSchema<TocProps>;
 
 const ACTIVE_OFFSET_TOLERANCE = 1;
@@ -109,12 +113,11 @@ const ACTIVE_OFFSET_TOLERANCE = 1;
 function normalizeProps(input: TocProps): ResolvedTocProps {
   const props = resolveProps(input, TOC_PROPS_SCHEMA, 'Toc.props');
   return {
-    container: props.container as DOMReference,
     target: props.target as DOMReference,
     headings: props.headings as string,
     offset: props.offset as number,
     className: props.className as TocClassNames,
-    onUpdate: props.onUpdate as ResolvedTocProps['onUpdate'],
+    onChange: props.onChange as ResolvedTocProps['onChange'],
   };
 }
 
@@ -138,18 +141,17 @@ function normalizeHeading(element: HTMLHeadingElement, index: number): TocItem {
  *
  * 扫描内容区域内的标题，生成锚点列表，并随页面滚动更新 active 状态。
  */
-export class Toc extends Component<ResolvedTocProps, TocState, TocDOM> {
+class Toc extends Component<ResolvedTocProps, TocState, TocDOM> {
   declare runtime: TocRuntime;
 
   /**
    * 创建 Toc 实例。
    * @param {object} [input={}] Toc 配置。
    */
-  constructor(input: TocProps = {}) {
-    const props = normalizeProps(input);
-    super(props);
+  constructor(props: TocProps = {}) {
+    const settings = normalizeProps(props);
+    super(settings);
 
-    this.dom.container = null;
     this.dom.target = null;
     this.dom.list = null;
     this.dom.headings = [];
@@ -177,21 +179,16 @@ export class Toc extends Component<ResolvedTocProps, TocState, TocDOM> {
     if (this.runtime.built) return this;
 
     this.init(this.props);
-    this.dom.container = requireContainer(
-      this.props.container,
-      'Toc.container'
-    );
     this.dom.target = requireContainer(this.props.target, 'Toc.target');
-    const root = document.createElement('nav');
-    root.className = this.props.className.toc;
-    root.dataset.toc = 'root';
-    this.root = root;
-    this.dom.list = document.createElement('div');
-    this.dom.list.className = this.props.className.list;
-    this.dom.list.dataset.tocList = 'root';
-    root.appendChild(this.dom.list);
-    this.dom.container.innerHTML = '';
-    this.dom.container.appendChild(root);
+    this.dom.list = jsx('div', {
+      className: this.props.className.list,
+      'data-toc-list': 'root',
+    }) as HTMLElement;
+    this.dom.root = jsx('nav', {
+      className: this.props.className.toc,
+      'data-toc': 'root',
+      children: this.dom.list,
+    }) as HTMLElement;
 
     this.runtime.built = true;
     this.refresh();
@@ -259,7 +256,7 @@ export class Toc extends Component<ResolvedTocProps, TocState, TocDOM> {
       `${this.props.className.levelPrefix}${item.level}`,
     ];
     if (active) classes.push(this.props.className.active);
-    return classes.filter(Boolean).join(' ');
+    return joinClasses(...classes);
   }
 
   private buildLink(item: TocItem, index: number): HTMLAnchorElement {
@@ -302,8 +299,8 @@ export class Toc extends Component<ResolvedTocProps, TocState, TocDOM> {
       link.className = this.linkClassName(items[i], active);
     });
 
-    if (typeof this.props.onUpdate === 'function') {
-      this.props.onUpdate(current, index, this);
+    if (typeof this.props.onChange === 'function') {
+      this.props.onChange(current, index, this);
     }
   }
 
@@ -368,11 +365,10 @@ export class Toc extends Component<ResolvedTocProps, TocState, TocDOM> {
    */
   protected onDestroy(): void {
     this.cleanup.events.clear();
-    if (this.dom.container) this.dom.container.innerHTML = '';
+    this.dom.root?.remove();
 
     this.runtime.built = false;
     this.runtime.ticking = false;
-    this.dom.container = null;
     this.dom.target = null;
     this.dom.list = null;
     this.dom.headings = [];
@@ -380,6 +376,6 @@ export class Toc extends Component<ResolvedTocProps, TocState, TocDOM> {
   }
 }
 
-export function createToc(props: TocProps = {}): Toc {
+export function createToc(props: TocProps = {}): TocInstance {
   return new Toc(props);
 }

package/src/core/Component.ts

@@ -1,6 +1,7 @@
 import { createDeepStore, flushSync } from 'vanilla-signal';
 
 import { createEventManager } from '../utilities/events.ts';
+import { isPlainObject } from '../utilities/object.ts';
 
 export type ComponentProps = Record<string, unknown>;
 export type ComponentState = Record<string, unknown>;
@@ -13,14 +14,16 @@ export interface ComponentRuntime {
   destroyed: boolean;
 }
 
-export interface ComponentUpdateOptions {
+export type ComponentCache = unknown;
+
+export interface ComponentReCreateOptions {
   force?: boolean;
 }
 
 export type ComponentLifecycleEvent =
   | 'init'
-  | 'beforeUpdate'
-  | 'afterUpdate'
+  | 'beforeReCreate'
+  | 'afterReCreate'
   | 'destroy';
 export type ComponentEventName = string;
 export type ComponentListener = (...args: unknown[]) => void;
@@ -56,12 +59,6 @@ export interface ComponentCleanupRegistry {
   [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 组件提供统一的状态管理、生命周期钩子和插件支持
@@ -70,6 +67,7 @@ export default class Component<
   TProps extends ComponentProps = ComponentProps,
   TState extends ComponentState = ComponentState,
   TDOM extends ComponentDOM = ComponentDOM,
+  TCache = ComponentCache,
 > {
   /** 全局插件注册表，所有新创建的组件实例会自动安装这些插件 */
   static globalPlugins = new Map<string, ComponentPlugin<Component>>();
@@ -80,6 +78,9 @@ export default class Component<
   /** DOM 引用容器，存储根元素及其他 DOM 节点引用 */
   dom: TDOM;
 
+  /** 实例缓存容器，存储组件运行时派生数据 */
+  cache: TCache;
+
   /** 已安装的插件映射表 */
   plugins: Map<ComponentPlugin<unknown>, ComponentCleanup>;
 
@@ -105,6 +106,9 @@ export default class Component<
     /** DOM 引用容器，存储根元素及其他 DOM 节点引用 */
     this.dom = { root: null } as TDOM;
 
+    /** 实例缓存容器，存储组件运行时派生数据 */
+    this.cache = {} as TCache;
+
     /** 已安装的插件映射表 */
     this.plugins = new Map();
 
@@ -114,8 +118,8 @@ export default class Component<
     /** 内部事件监听器注册表，用于生命周期和自定义事件 */
     this._listeners = {
       init: [], // 初始化完成事件
-      beforeUpdate: [], // 更新前事件
-      afterUpdate: [], // 更新后事件
+      beforeReCreate: [], // 重新实例化前事件
+      afterReCreate: [], // 重新实例化后事件
       destroy: [], // 销毁事件
     };
 
@@ -129,23 +133,6 @@ export default class Component<
     this.installGlobalPlugins();
   }
 
-  /**
-   * 获取组件的根 DOM 元素
-   * @returns {HTMLElement|null} 根 DOM 元素或 null
-   */
-  get root(): Element | null {
-    return this.dom?.root || null;
-  }
-
-  /**
-   * 设置组件的根 DOM 元素
-   * @param {HTMLElement} value - 要设置的根 DOM 元素
-   */
-  set root(value: Element | null) {
-    if (!this.dom) this.dom = { root: null } as TDOM;
-    this.dom.root = value;
-  }
-
   /**
    * 安装实例插件
    * 插件可以是函数形式 plugin(instance, options) 或对象形式 { install(instance, options) }
@@ -169,7 +156,7 @@ export default class Component<
 
   /**
    * 注册事件监听器
-   * 用于监听组件生命周期事件（init、beforeUpdate、afterUpdate、destroy）或自定义事件
+   * 用于监听组件生命周期事件（init、beforeReCreate、afterReCreate、destroy）或自定义事件
    * @param {string} event - 事件名称
    * @param {Function} callback - 事件回调函数
    * @returns {Component} 返回当前实例，支持链式调用
@@ -283,39 +270,57 @@ export default class Component<
       throw new Error('Component.setState: expects a plain object patch.');
     }
 
+    const normalizedPatch = this.normalizeStatePatch(patch as Partial<TState>);
+    if (!isPlainObject(normalizedPatch)) {
+      throw new Error('Component.setState: expects a plain object patch.');
+    }
+    this.validateStatePatch(normalizedPatch);
+
     flushSync(() => {
-      for (const [k, v] of Object.entries(patch)) {
+      for (const [k, v] of Object.entries(normalizedPatch)) {
         if (!this.state) return;
         this.state[k as keyof TState] = v as TState[keyof TState];
       }
     });
+    this.afterSetState(normalizedPatch);
     return this;
   }
 
   /**
-   * 更新组件属性和触发更新生命周期
-   * 合并新的属性配置，触发 beforeUpdate 和 afterUpdate 事件
-   * 子类可以重写 onUpdate 方法实现自定义更新逻辑
+   * 根据新的 props 重新创建组件实例并触发生命周期
+   * 合并新的属性配置，触发 beforeReCreate 和 afterReCreate 事件
+   * 子类可以重写 onReCreate 方法实现自定义重建前逻辑
    * @param {Object} [propsPatch={}] - 要合并的属性补丁对象
    * @param {Object} [options] - 更新选项
    * @param {boolean} [options.force=false] - 是否强制更新（由子类处理）
-   * @returns {Component} 返回当前实例，支持链式调用
+   * @returns {Component} 返回新创建的实例
    * @throws {Error} 如果组件已被销毁则抛出异常
    */
-  update(
+  reCreate(
     propsPatch: Partial<TProps> | null | undefined = {},
-    { force = false }: ComponentUpdateOptions = {}
+    { force = false }: ComponentReCreateOptions = {}
   ): this {
     if (this.runtime.destroyed)
-      throw new Error('Component.update: instance destroyed');
-    if (isPlainObject(propsPatch)) {
-      this.props = Object.assign({}, this.props, propsPatch);
-    }
-    this.emit('beforeUpdate', propsPatch, { force });
-    if (typeof this.onUpdate === 'function')
-      this.onUpdate(propsPatch, { force });
-    this.emit('afterUpdate', propsPatch, { force });
-    return this;
+      throw new Error('Component.reCreate: instance destroyed');
+
+    if (!isPlainObject(propsPatch)) return this;
+
+    const nextProps = Object.assign({}, this.props, propsPatch);
+    this.emit('beforeReCreate', propsPatch, { force });
+    if (typeof this.onReCreate === 'function')
+      this.onReCreate(propsPatch, { force });
+
+    const nextInstance = this.createInstance(nextProps);
+    this.destroy();
+    nextInstance.emit('afterReCreate', propsPatch, { force });
+    return nextInstance;
+  }
+
+  protected createInstance(props: TProps): this {
+    const ComponentConstructor = this.constructor as new (
+      props: TProps
+    ) => this;
+    return new ComponentConstructor(props);
   }
 
   /**
@@ -343,13 +348,30 @@ export default class Component<
     this.cleanup.plugins.clear();
     this.cleanup.events.clear();
     this.dom = { root: null } as TDOM;
+    this.cache = {} as TCache;
     this.state = null;
   }
 
   protected onInit?(props: TProps): void;
-  protected onUpdate?(
+  protected onReCreate?(
     propsPatch: Partial<TProps> | null | undefined,
-    options: Required<ComponentUpdateOptions>
+    options: Required<ComponentReCreateOptions>
   ): void;
+  protected normalizeStatePatch(patch: Partial<TState>): Partial<TState> {
+    return patch;
+  }
+  protected validateStatePatch(patch: Partial<TState>): void {
+    if (!this.state) return;
+    for (const key of Object.keys(patch)) {
+      const stateKey = String(key);
+      const exists = Object.hasOwn(this.state as object, stateKey);
+      if (!exists) {
+        throw new Error(
+          `Component.setState: "${stateKey}" is not a supported state key.`
+        );
+      }
+    }
+  }
+  protected afterSetState(_patch: Partial<TState>): void {}
   protected onDestroy?(): void;
 }

package/src/css/accordion.css

@@ -21,7 +21,7 @@
     display: none;
   }
 
-  .j-accordion .accordion-panel[aria-hidden="false"] {
+  .j-accordion .accordion-panel[aria-hidden='false'] {
     display: block;
   }
-}
+}

package/src/css/animation.css

@@ -1,5 +1,4 @@
 @layer animation {
-
   /* none */
   .animate-none {
     animation: none;
@@ -22,7 +21,6 @@
   }
 
   @keyframes animate-ping {
-
     75%,
     100% {
       transform: scale(2);
@@ -47,7 +45,6 @@
   }
 
   @keyframes animate-bounce {
-
     0%,
     100% {
       transform: translateY(-25%);
@@ -100,7 +97,6 @@
   }
 
   @keyframes animate-shake {
-
     0%,
     100% {
       transform: translateX(0);
@@ -204,4 +200,4 @@
       transform: translateY(0);
     }
   }
-}
+}

package/src/css/avatar.css

@@ -33,4 +33,4 @@
     align-items: center;
     flex-wrap: nowrap;
   }
-}
+}

package/src/css/badge.css

@@ -15,4 +15,4 @@
     background-color: var(--badge-bg);
     box-shadow: var(--badge-box-shadow);
   }
-}
+}

package/src/css/breadcrumb.css

@@ -1,5 +1,4 @@
 @layer components {
-
   .j-breadcrumb {
     font-size: var(--breadcrumb-font-size);
     color: var(--breadcrumb-fg);
@@ -12,8 +11,8 @@
     height: var(--breadcrumb-icon-size);
   }
 
-  .j-breadcrumb>ol,
-  .j-breadcrumb>ul {
+  .j-breadcrumb > ol,
+  .j-breadcrumb > ul {
     display: flex;
     flex-wrap: wrap;
     justify-content: flex-start;
@@ -22,8 +21,8 @@
     padding: 0;
   }
 
-  .j-breadcrumb>ol li,
-  .j-breadcrumb>ul li {
+  .j-breadcrumb > ol li,
+  .j-breadcrumb > ul li {
     display: flex;
     align-items: center;
     justify-content: center;
@@ -33,20 +32,20 @@
     padding-inline-start: 0;
   }
 
-  .j-breadcrumb li+li::before {
+  .j-breadcrumb li + li::before {
     color: var(--breadcrumb-divider-fg);
     content: '/';
   }
 
-  .j-breadcrumb.is-dot li+li::before {
+  .j-breadcrumb.is-dot li + li::before {
     content: '•';
   }
 
-  .j-breadcrumb.is-arrow li+li::before {
+  .j-breadcrumb.is-arrow li + li::before {
     content: '>';
   }
 
-  .j-breadcrumb.is-dash li+li::before {
+  .j-breadcrumb.is-dash li + li::before {
     content: '–';
   }
 
@@ -80,4 +79,4 @@
   .j-breadcrumb.is-right ol {
     justify-content: flex-end;
   }
-}
+}

package/src/css/button.css

@@ -92,4 +92,4 @@
   .j-button-group.is-vertical .j-button:last-child {
     border-bottom-left-radius: var(--radius-md);
   }
-}
+}

package/src/css/card.css

@@ -141,11 +141,11 @@
     padding: var(--vertical-card-footer-padding, var(--s4));
   }
 
-  .j-card .card-content+.card-footer {
+  .j-card .card-content + .card-footer {
     padding-top: 0;
   }
 
   .j-card .card-footer:has(.j-button-group) {
     padding-top: 4px;
   }
-}
+}