vanilla-jui 1.4.5 → 1.4.7

package/src/utilities/types.ts

@@ -0,0 +1,420 @@
+import { isPlainObject } from './object.ts';
+
+type LooseRecord = Record<string, unknown>;
+type ValueTypeName = string;
+type TypeRule = ValueTypeName | readonly ValueTypeName[];
+
+export function isNilValue(value: unknown): value is null | undefined {
+  return value == null;
+}
+
+export function isDomNodeValue(value: unknown): value is Node {
+  return typeof Node !== 'undefined' && value instanceof Node;
+}
+
+export function isDomElementValue(value: unknown): value is Element {
+  return typeof Element !== 'undefined' && value instanceof Element;
+}
+
+export function isHtmlElementValue(value: unknown): value is HTMLElement {
+  return typeof HTMLElement !== 'undefined' && value instanceof HTMLElement;
+}
+
+export function isRenderablePrimitive(
+  value: unknown
+): value is string | number | boolean {
+  return (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  );
+}
+
+export function isRenderableValue(value: unknown): boolean {
+  return (
+    isNilValue(value) ||
+    isRenderablePrimitive(value) ||
+    typeof value === 'function' ||
+    Array.isArray(value) ||
+    isDomNodeValue(value)
+  );
+}
+
+export const getType = (val: unknown): string => {
+  if (val === null) return 'null';
+  if (Array.isArray(val)) return 'array';
+  if (isHtmlElementValue(val)) return 'HTMLElement';
+  if (isDomNodeValue(val)) return 'Node';
+  return typeof val;
+};
+
+export type ValidateCondition =
+  | ((value: unknown) => boolean)
+  | {
+      test: (value: unknown) => boolean;
+      message?: string;
+    };
+
+export interface NormalizeContext<TInput extends LooseRecord = LooseRecord> {
+  key: string;
+  input: TInput;
+  options: LooseRecord;
+  schema: ResolveSchema<TInput>;
+}
+
+export interface ParamRule<TInput extends LooseRecord = LooseRecord> {
+  type?: TypeRule;
+  types?: TypeRule;
+  required?: boolean;
+  enum?: readonly unknown[];
+  nonEmpty?: boolean;
+  minLength?: number;
+  maxLength?: number;
+  finite?: boolean;
+  integer?: boolean;
+  min?: number;
+  max?: number;
+  greaterThan?: number;
+  lessThan?: number;
+  plain?: boolean;
+  items?: ParamRuleInput;
+  shape?: ResolveSchema;
+  conditions?: ValidateCondition | readonly ValidateCondition[];
+  validate?: (value: unknown) => boolean;
+  message?: string;
+  normalize?: (value: unknown, context: NormalizeContext<TInput>) => unknown;
+  default?: unknown;
+  factory?: boolean;
+  [key: string]: unknown;
+}
+
+export type ParamRuleInput<TInput extends LooseRecord = LooseRecord> =
+  | TypeRule
+  | ParamRule<TInput>;
+
+export type ResolveSchema<TInput extends LooseRecord = LooseRecord> = Record<
+  string,
+  ParamRuleInput<TInput>
+>;
+
+export type ResolvedProps<TSchema extends object> = LooseRecord & {
+  [Key in keyof TSchema]: unknown;
+};
+
+function cloneDefault<T>(value: T): T {
+  if (Array.isArray(value)) return value.slice() as T;
+  if (isPlainObject(value)) return { ...(value as LooseRecord) } as T;
+  return value;
+}
+
+function normalizeRule<TInput extends LooseRecord = LooseRecord>(
+  rule: ParamRuleInput<TInput> = {}
+): ParamRule<TInput> {
+  if (typeof rule === 'string' || Array.isArray(rule)) return { type: rule };
+  if (!rule || typeof rule !== 'object') return {};
+  return rule as ParamRule<TInput>;
+}
+
+function throwValidateError(name: string, message: string): never {
+  throw new Error(`Validator: ${name} ${message}`);
+}
+
+function stringifyExpected(value: unknown): string {
+  return typeof value === 'string' ? value : String(value);
+}
+
+function describeLengthValue(value: unknown): string {
+  return typeof value === 'string' ? 'string' : 'array';
+}
+
+function validateLengthRule<TInput extends LooseRecord = LooseRecord>(
+  name: string,
+  value: unknown,
+  rule: ParamRule<TInput>
+): void {
+  if (isNilValue(value)) return;
+  if (typeof value !== 'string' && !Array.isArray(value)) return;
+
+  const label = describeLengthValue(value);
+  if (rule.nonEmpty && value.length === 0) {
+    throwValidateError(name, `expects a non-empty ${label}.`);
+  }
+  if (typeof rule.minLength === 'number' && value.length < rule.minLength) {
+    throwValidateError(
+      name,
+      `expects ${label} length to be at least ${rule.minLength}.`
+    );
+  }
+  if (typeof rule.maxLength === 'number' && value.length > rule.maxLength) {
+    throwValidateError(
+      name,
+      `expects ${label} length to be at most ${rule.maxLength}.`
+    );
+  }
+}
+
+function validateNumberRule<TInput extends LooseRecord = LooseRecord>(
+  name: string,
+  value: unknown,
+  rule: ParamRule<TInput>
+): void {
+  if (isNilValue(value) || typeof value !== 'number') return;
+  if (rule.finite && !Number.isFinite(value)) {
+    throwValidateError(name, 'expects a finite number.');
+  }
+  if (rule.integer && !Number.isInteger(value)) {
+    throwValidateError(name, 'expects an integer.');
+  }
+  if (typeof rule.min === 'number' && value < rule.min) {
+    throwValidateError(
+      name,
+      `expects a number greater than or equal to ${rule.min}.`
+    );
+  }
+  if (typeof rule.max === 'number' && value > rule.max) {
+    throwValidateError(
+      name,
+      `expects a number less than or equal to ${rule.max}.`
+    );
+  }
+  if (typeof rule.greaterThan === 'number' && value <= rule.greaterThan) {
+    throwValidateError(
+      name,
+      `expects a number greater than ${rule.greaterThan}.`
+    );
+  }
+  if (typeof rule.lessThan === 'number' && value >= rule.lessThan) {
+    throwValidateError(name, `expects a number less than ${rule.lessThan}.`);
+  }
+}
+
+function validatePlainRule<TInput extends LooseRecord = LooseRecord>(
+  name: string,
+  value: unknown,
+  rule: ParamRule<TInput>
+): void {
+  if (!rule.plain || isNilValue(value)) return;
+  if (!isPlainObject(value)) {
+    throwValidateError(name, 'expects an object.');
+  }
+}
+
+function validateItemsRule<TInput extends LooseRecord = LooseRecord>(
+  name: string,
+  value: unknown,
+  rule: ParamRule<TInput>
+): void {
+  if (!rule.items || isNilValue(value)) return;
+  if (!Array.isArray(value)) {
+    throwValidateError(name, 'expects array.');
+  }
+  value.forEach((item, index) => {
+    validateParam(String(index), item, rule.items, name);
+  });
+}
+
+function validateShapeRule<TInput extends LooseRecord = LooseRecord>(
+  name: string,
+  value: unknown,
+  rule: ParamRule<TInput>
+): void {
+  if (!rule.shape || isNilValue(value)) return;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throwValidateError(name, 'expects object.');
+  }
+  const source = value as LooseRecord;
+  for (const [key, childRule] of Object.entries(rule.shape)) {
+    validateParam(key, source[key], childRule, name);
+  }
+}
+
+function matchesValueType(value: unknown, type: string): boolean {
+  if (type === 'renderable') return isRenderableValue(value);
+  if (type === 'Node') return isDomNodeValue(value);
+  if (type === 'Element') return isDomElementValue(value);
+  if (type === 'HTMLElement') return isHtmlElementValue(value);
+  if (type === 'plainObject') return isPlainObject(value);
+  return getType(value) === type;
+}
+
+function getActualType(value: unknown): string {
+  return isPlainObject(value) ? 'object' : getType(value);
+}
+
+function runValidateConditions(
+  name: string,
+  value: unknown,
+  conditions: ValidateCondition | readonly ValidateCondition[] = []
+): void {
+  const list = Array.isArray(conditions)
+    ? conditions
+    : conditions
+      ? [conditions]
+      : [];
+  for (const c of list) {
+    let testFn: (val: unknown) => boolean;
+    let message: string;
+
+    if (typeof c === 'function') {
+      testFn = c;
+      message = 'does not satisfy the required condition.';
+    } else if (c && typeof c.test === 'function') {
+      testFn = c.test;
+      message = c.message || 'condition failed.';
+    } else {
+      throw new Error(
+        'Validator: Condition must be a function or { test, message }.'
+      );
+    }
+
+    if (!testFn(value)) {
+      throwValidateError(name, message);
+    }
+  }
+}
+
+function formatValidateName(namespace: string, name: string): string {
+  return namespace ? `${namespace}.${name}` : name;
+}
+
+export function validateParam<TInput extends LooseRecord = LooseRecord>(
+  name: string,
+  value: unknown,
+  rule: ParamRuleInput<TInput> = {},
+  namespace = ''
+): unknown {
+  const config = normalizeRule(rule);
+  const label = formatValidateName(namespace, name);
+  const expectedTypes = Object.hasOwn(config, 'types')
+    ? config.types
+    : config.type;
+
+  if (config.required && isNilValue(value)) {
+    throwValidateError(label, 'is required.');
+  }
+
+  if (expectedTypes !== undefined) {
+    const types = Array.isArray(expectedTypes)
+      ? expectedTypes
+      : [expectedTypes];
+    const actualType = getActualType(value);
+    const typeMatch = types.some((t) => matchesValueType(value, t));
+    if (!typeMatch) {
+      const allowed = types.join(', ');
+      throwValidateError(label, `expects ${allowed}, but got ${actualType}.`);
+    }
+  }
+
+  if (Array.isArray(config.enum) && !config.enum.includes(value)) {
+    throwValidateError(
+      label,
+      `expects one of ${config.enum.map(stringifyExpected).join(', ')}.`
+    );
+  }
+
+  validateLengthRule(label, value, config);
+  validateNumberRule(label, value, config);
+  validatePlainRule(label, value, config);
+  validateItemsRule(label, value, config);
+  validateShapeRule(label, value, config);
+  runValidateConditions(label, value, config.conditions);
+
+  if (typeof config.validate === 'function') {
+    const valid = config.validate(value);
+    if (!valid) {
+      throwValidateError(
+        label,
+        config.message || 'does not satisfy the required condition.'
+      );
+    }
+  }
+
+  return value;
+}
+
+export function resolveProps<
+  TInput extends LooseRecord,
+  TSchema extends ResolveSchema<TInput>,
+>(
+  input: TInput | null | undefined = {} as TInput,
+  schema: TSchema = {} as TSchema,
+  namespace = 'Options'
+): TInput & ResolvedProps<TSchema> {
+  const source = input == null ? {} : input;
+  if (typeof source !== 'object' || Array.isArray(source)) {
+    throw new Error(`${namespace} expects object.`);
+  }
+
+  const sourceRecord = source as TInput;
+  const resolved: LooseRecord = { ...sourceRecord };
+  const entries = Object.entries(schema || {}) as Array<
+    [string, ParamRuleInput<TInput>]
+  >;
+
+  for (const [key, rawRule] of entries) {
+    const rule = normalizeRule<TInput>(rawRule);
+    resolved[key] = Object.hasOwn(sourceRecord, key)
+      ? sourceRecord[key]
+      : resolveDefault(rule);
+  }
+
+  for (const [key, rawRule] of entries) {
+    const rule = normalizeRule<TInput>(rawRule);
+    if (typeof rule.normalize === 'function') {
+      resolved[key] = rule.normalize(resolved[key], {
+        key,
+        input: sourceRecord,
+        options: resolved,
+        schema,
+      });
+    }
+  }
+
+  for (const [key, rule] of entries) {
+    validateParam(key, resolved[key], rule, namespace);
+  }
+
+  return resolved as TInput & ResolvedProps<TSchema>;
+}
+
+interface DefaultRule {
+  default?: unknown;
+  factory?: boolean;
+}
+
+function resolveDefault(rule: DefaultRule): unknown {
+  if (!Object.hasOwn(rule, 'default')) return undefined;
+  const defaultValue = rule.default;
+  const value =
+    rule.factory && typeof defaultValue === 'function'
+      ? defaultValue()
+      : defaultValue;
+  return cloneDefault(value);
+}
+
+/**
+ * 判断是否为普通可构造函数（排除箭头函数和类）。
+ * @param fn - 需要判断的值
+ * @returns 如果是普通函数则返回 true，否则返回 false
+ * @deprecated 未使用过，暂时注释掉。待需要使用时，再重新恢复。
+ */
+// export const isFunction = (fn: unknown): fn is (...args: never[]) => unknown => {
+//   return (
+//     typeof fn === "function" &&
+//     Object.hasOwn(fn, "prototype") &&
+//     fn.prototype !== null &&
+//     typeof fn.prototype === "object" &&
+//     Object.hasOwn(fn.prototype, "constructor") &&
+//     fn.prototype.constructor === fn
+//   );
+// };
+
+/**
+ * 判断是否为类（使用 class 语法定义）。
+ * @param fn - 需要判断的值
+ * @returns 如果是类则返回 true，否则返回 false
+ * @deprecated 未使用过，暂时注释掉。待需要使用时，再重新恢复。
+ */
+// export const isClass = (fn: unknown): fn is abstract new (...args: never[]) => unknown => {
+//   return typeof fn === "function" && /^class\s/.test(Function.prototype.toString.call(fn));
+// };

package/src/{components → validation}/validator.ts

@@ -1,29 +1,25 @@
 import { jsx } from 'vanilla-signal';
 
+import { type DOMReference, all, resolveElement } from '../utilities/dom.ts';
+import { type IEventManager, createEventManager } from '../utilities/events.ts';
 import {
   type ResolveSchema,
   resolveProps,
   validateParam,
-} from '../utilities/core.ts';
-import { type DOMReference, all, resolveElement } from '../utilities/dom.ts';
-import { type IEventManager, createEventManager } from '../utilities/events.ts';
+} from '../utilities/types.ts';
 
 type ValidatorElement =
   | HTMLInputElement
   | HTMLSelectElement
   | HTMLTextAreaElement;
-type ValidatorRuleName = keyof ValidatorRule | string;
-type ValidatorMessageMap = Record<
-  string,
-  Partial<Record<ValidatorRuleName, string>>
->;
+type ValidatorMessageMap = Record<string, Partial<Record<string, string>>>;
 type ValidatorCustomResult = boolean | string;
 type ValidatorCustomRule = (
   element: ValidatorElement,
-  validator: Validator
+  validator: ValidatorInstance
 ) => ValidatorCustomResult;
 
-export interface ValidatorRule extends Record<string, unknown> {
+interface ValidatorRule extends Record<string, unknown> {
   required?: boolean;
   minLength?: number;
   maxLength?: number;
@@ -45,16 +41,20 @@ export interface ValidatorRule extends Record<string, unknown> {
   validate?: ValidatorCustomRule;
 }
 
-export interface ValidatorOptions extends Record<string, unknown> {
+interface ValidatorProps extends Record<string, unknown> {
   rules?: Record<string, ValidatorRule>;
   messages?: ValidatorMessageMap;
-  onSubmit?: ((validator: Validator) => void) | null;
+  onSubmit?: ((validator: ValidatorInstance) => void) | null;
 }
 
-interface ResolvedValidatorOptions extends Record<string, unknown> {
+interface ResolvedValidatorProps extends Record<string, unknown> {
   rules: Record<string, ValidatorRule>;
   messages: ValidatorMessageMap;
-  onSubmit: ((validator: Validator) => void) | null;
+  onSubmit: ((validator: ValidatorInstance) => void) | null;
+}
+
+interface ValidatorDOM {
+  root: HTMLFormElement | null;
 }
 
 interface ValidatorRuntime {
@@ -71,22 +71,27 @@ interface ResetOptions {
   native?: boolean;
 }
 
-const VALIDATOR_OPTIONS_SCHEMA = {
+interface ValidatorInstance {
+  dom: ValidatorDOM;
+  props: ResolvedValidatorProps | null;
+  runtime: ValidatorRuntime;
+  validate(): boolean;
+  reset(options?: ResetOptions): void;
+  destroy(): void;
+}
+
+const VALIDATOR_PROPS_SCHEMA = {
   rules: { default: {}, type: 'object' },
   messages: { default: {}, type: 'object' },
   onSubmit: { default: null, types: ['function', 'null'] },
-} satisfies ResolveSchema<ValidatorOptions>;
+} satisfies ResolveSchema<ValidatorProps>;
 
-function normalizeOptions(input: ValidatorOptions): ResolvedValidatorOptions {
-  const options = resolveProps(
-    input,
-    VALIDATOR_OPTIONS_SCHEMA,
-    'Validator.options'
-  );
+function normalizeProps(input: ValidatorProps): ResolvedValidatorProps {
+  const props = resolveProps(input, VALIDATOR_PROPS_SCHEMA, 'Validator.props');
   return {
-    rules: options.rules as Record<string, ValidatorRule>,
-    messages: options.messages as ValidatorMessageMap,
-    onSubmit: options.onSubmit as ResolvedValidatorOptions['onSubmit'],
+    rules: props.rules as Record<string, ValidatorRule>,
+    messages: props.messages as ValidatorMessageMap,
+    onSubmit: props.onSubmit as ResolvedValidatorProps['onSubmit'],
   };
 }
 
@@ -146,19 +151,21 @@ function hasFiles(element: HTMLInputElement): element is HTMLInputElement & {
  *
  * 支持绑定表单 submit/reset 事件，也可以手动调用 validate/reset。
  */
-export class Validator {
-  root: HTMLFormElement | null;
-  options: ResolvedValidatorOptions | null;
+class Validator implements ValidatorInstance {
+  dom: ValidatorDOM;
+  props: ResolvedValidatorProps | null;
   runtime: ValidatorRuntime;
   cleanup: ValidatorCleanup | null;
 
   constructor(
     element: DOMReference,
-    options: ValidatorOptions = {},
+    props: ValidatorProps = {},
     bindEvents = false
   ) {
-    this.options = normalizeOptions(options);
-    this.root = this.resolveRoot(element);
+    this.props = normalizeProps(props);
+    this.dom = {
+      root: this.resolveRoot(element),
+    };
     this.runtime = createRuntime();
     this.cleanup = {
       events: createEventManager(),
@@ -185,13 +192,14 @@ export class Validator {
 
   private bindEvents(): void {
     this.unbindEvents();
-    if (!this.root || !this.cleanup) return;
+    const { root } = this.dom;
+    if (!root || !this.cleanup) return;
 
-    this.cleanup.events.on('submit', this.root, 'submit', (event) => {
+    this.cleanup.events.on('submit', root, 'submit', (event) => {
       event.preventDefault();
       this.validate();
     });
-    this.cleanup.events.on('reset', this.root, 'reset', () => {
+    this.cleanup.events.on('reset', root, 'reset', () => {
       this.reset({ native: false });
     });
   }
@@ -204,28 +212,29 @@ export class Validator {
    * 执行表单校验。
    */
   validate(): boolean {
-    if (!this.root || !this.options) return false;
+    const { root } = this.dom;
+    if (!root || !this.props) return false;
 
     this.runtime.valid = true;
     this.runtime.message = '';
 
-    for (const element of Array.from(this.root.elements)) {
+    for (const element of Array.from(root.elements)) {
       if (!isValidatorElement(element) || !element.name) continue;
-      if (!this.options.rules[element.name]) continue;
+      if (!this.props.rules[element.name]) continue;
 
       this.runtime.valid = this.validateRule(element, element.name);
       if (!this.runtime.valid) break;
     }
 
-    if (this.runtime.valid && this.options.onSubmit) {
-      this.options.onSubmit(this);
+    if (this.runtime.valid && this.props.onSubmit) {
+      this.props.onSubmit(this);
     }
     return this.runtime.valid;
   }
 
   private validateRule(element: ValidatorElement, name: string): boolean {
-    if (!this.options) return false;
-    const rules = this.options.rules[name];
+    if (!this.props) return false;
+    const rules = this.props.rules[name];
     if (!rules) return true;
 
     if (this.hasNativeValidationRule(element)) {
@@ -358,9 +367,10 @@ export class Validator {
     element: ValidatorElement,
     targetName: unknown
   ): boolean {
-    if (!this.root || typeof targetName !== 'string') return true;
+    const { root } = this.dom;
+    if (!root || typeof targetName !== 'string') return true;
     const targetElement = toValidatorElement(
-      this.root.elements.namedItem(targetName)
+      root.elements.namedItem(targetName)
     );
     if (!targetElement) {
       throw new Error(`Validator: target element "${targetName}" not found.`);
@@ -509,7 +519,7 @@ export class Validator {
       element.classList.add('is-invalid');
     }
 
-    const error = customMessage || this.options?.messages[name]?.[rule] || '';
+    const error = customMessage || this.props?.messages[name]?.[rule] || '';
     if (!error) return;
 
     this.runtime.message = error;
@@ -552,16 +562,17 @@ export class Validator {
    * 重置表单与校验状态。
    */
   reset({ native = true }: ResetOptions = {}): void {
-    if (!this.root) return;
-    if (native) this.root.reset();
+    const { root } = this.dom;
+    if (!root) return;
+    if (native) root.reset();
 
-    for (const element of Array.from(this.root.elements)) {
+    for (const element of Array.from(root.elements)) {
       if (!isValidatorElement(element)) continue;
       element.classList.remove('is-valid');
       element.classList.remove('is-invalid');
     }
 
-    for (const help of all<HTMLElement>('[data-validator-help]', this.root)) {
+    for (const help of all<HTMLElement>('[data-validator-help]', root)) {
       help.remove();
     }
 
@@ -578,8 +589,8 @@ export class Validator {
 
     this.unbindEvents();
     this.reset({ native: false });
-    this.root = null;
-    this.options = null;
+    this.dom.root = null;
+    this.props = null;
     this.runtime.valid = false;
     this.runtime.message = '';
     this.cleanup?.events.clear();
@@ -589,8 +600,8 @@ export class Validator {
 
 export function createValidator(
   element: DOMReference,
-  options: ValidatorOptions = {},
+  props: ValidatorProps = {},
   bindEvents = false
-): Validator {
-  return new Validator(element, options, bindEvents);
+): ValidatorInstance {
+  return new Validator(element, props, bindEvents);
 }