Rule System and Creators

/**
 * Base rule interface defining structure for form fields
 * All properties are optional and provide different aspects of field configuration
 */
interface BaseRule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> {
  /** Component type identifier (input, select, etc.) */
  type?: string;
  /** Form field name for data binding */
  field?: string;
  /** Field display title/label */
  title?: string;
  /** Field value */
  value?: any;
  /** Unique identifier for field */
  key?: string;
  /** Component name reference */
  name?: string;
  
  /** Component properties object */
  props?: { [key: string]: any };
  /** HTML attributes object */
  attrs?: { [key: string]: any };
  /** DOM properties object */
  domProps?: { [key: string]: any };
  /** Event handlers object */
  on?: { [key: string]: Function | Function[] };
  /** Native event handlers */
  nativeOn?: { [key: string]: Function | Function[] };
  /** CSS classes */
  class?: any;
  /** Inline styles */
  style?: string | object[] | object;
  /** Vue directives */
  directives?: VNodeDirective[];
  /** Slot configuration */
  slot?: string;
  /** Scoped slots */
  scopedSlots?: { [key: string]: ScopedSlot | undefined };
  
  /** Hide field from display */
  hidden?: boolean;
  /** Control field display */
  display?: boolean;
  /** Enable preview mode */
  preview?: boolean;
  /** Cache component instance */
  cache?: boolean;
  /** Use native component rendering */
  native?: boolean;
  /** Ignore field in form data */
  ignore?: boolean | 'hidden';
  
  /** Model field name for v-model binding */
  modelField?: string;
  /** Model emit event name */
  modelEmit?: string;
  /** Event emit prefix */
  emitPrefix?: string;
  /** Custom component reference */
  component?: Component;
  
  /** Validation rules array */
  validate?: Object[];
  /** Child rules for nested structures */
  children?: Array<RuleChildren<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>>;
  /** Options data for select/radio components */
  options?: RuleOptions<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>;
  /** Target field for options binding */
  optionsTo?: string;
  
  /** Computed value function or expression */
  computed?: string | ((formData: FormData, api: Api<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>) => any);
  /** Value update handler */
  update?: (value: any, rule: this, api: Api<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>, arg: {
    origin: 'change' | 'init' | 'link';
    linkField?: string;
  }) => boolean | void;
  
  /** Linked field names for synchronization */
  link?: string[];
  /** Sync field names for two-way binding */
  sync?: string[];
  /** Custom emit events configuration */
  emit?: Array<string | { name: string; inject: any }>;
  /** Native emit events configuration */
  nativeEmit?: Array<string | { name: string; inject: any }>;
  
  /** Field prefix content */
  prefix?: string | VNodeRule;
  /** Field suffix content */
  suffix?: string | VNodeRule;
  /** Deep watch configuration */
  deep?: Object;
  /** Dependency injection data */
  inject?: any;
  /** Slot update handler */
  slotUpdate?: (arg: PropArg<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>) => void;
  
  /** Control rules for conditional display */
  control?: Control<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>[];
  /** Effect configuration object */
  effect?: {
    fetch?: string | FetchEffectOption | ((rule: Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>, api: Api<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>) => FetchEffectOption);
    componentValidate?: string | boolean | {
      method: string;
      trigger?: string;
      message?: string;
      [key: string]: any;
    };
    required?: boolean | string | object;
    t?: { [key: string]: string | { attr: string; params?: Object; modify?: boolean } };
    loadData?: LoadDataEffectOption | Array<LoadDataEffectOption>;
    [key: string]: any;
  };
  
  /** Lifecycle hooks */
  hook?: {
    load?: (evt: { rule: Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>, api: Api<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> }) => void;
    mounted?: (evt: { rule: Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>, api: Api<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> }) => void;
    deleted?: (evt: { rule: Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>, api: Api<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> }) => void;
    value?: (evt: { value: any, rule: Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>, api: Api<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> }) => void;
    hidden?: (evt: { value: boolean, rule: Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>, api: Api<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> }) => void;
    watch?: (evt: { key: string, oldValue: any, newValue: any, rule: Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>, api: Api<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> }) => void;
  };
}

/**
 * Base creator class providing fluent API for rule creation
 * All methods return 'this' for method chaining
 */
class BaseCreator<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> {
  /** Internal rule data storage */
  private _data: Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>;
  
  /**
   * Create new rule creator instance
   * @param type - Component type
   * @param title - Field title or configuration object
   * @param field - Field name
   * @param value - Initial value
   * @param props - Component properties
   */
  constructor(type: string, title?: string | Object, field?: string, value?: any, props?: Object);
  
  /**
   * Set arbitrary property on rule
   * @param key - Property name
   * @param prop - Property value
   */
  setProp(key: string, prop: any): this;
  
  /**
   * Get final rule object
   * @returns Complete rule configuration
   */
  getRule(): Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>;
  
  /**
   * Clone creator instance
   * @returns New creator with copied rule data
   */
  _clone(): Creator<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>;
  
  // Chainable property setters
  /** Set field name */
  field(prop: string): this;
  /** Set field title */
  title(prop: string): this;
  /** Set field value */
  value(prop: any): this;
  /** Set unique key */
  key(key: string): this;
  /** Set component name */
  name(prop: string): this;
  /** Set component type */
  type(prop: string): this;
  
  /** Set component properties */
  props(prop: { [key: string]: any }): this;
  props(prop: string, val: any): this;
  /** Set HTML attributes */
  attrs(prop: { [key: string]: any }): this;
  attrs(prop: string, val: any): this;
  /** Set DOM properties */
  domProps(prop: { [key: string]: any }): this;
  domProps(prop: string, val: any): this;
  
  /** Set event handlers */
  on(prop: { [key: string]: Function | Function[] }): this;
  on(prop: string, val: Function | Function[]): this;
  /** Set native event handlers */
  nativeOn(prop: { [key: string]: Function | Function[] }): this;
  nativeOn(prop: string, val: Function | Function[]): this;
  
  /** Set CSS classes */
  class(prop: any): this;
  /** Set inline styles */
  style(prop: string | object[] | object): this;
  /** Set Vue directives */
  directives(prop: VNodeDirective[]): this;
  /** Set slot name */
  slot(prop: string): this;
  /** Set scoped slots */
  scopedSlots(prop: { [key: string]: ScopedSlot | undefined }): this;
  scopedSlots(prop: string, key: ScopedSlot | undefined): this;
  
  /** Set hidden state */
  hidden(prop: boolean): this;
  /** Set display state */
  display(prop: boolean): this;
  /** Set preview mode */
  preview(prop: boolean): this;
  /** Set cache mode */
  cache(prop: boolean): this;
  /** Set native rendering mode */
  native(prop: boolean): this;
  /** Set component reference */
  component(prop: Component): this;
  
  /** Set model field name */
  modelField(prop: string): this;
  /** Set model emit event */
  modelEmit(prop: string): this;
  /** Set emit prefix */
  emitPrefix(prop: string): this;
  
  /** Set validation rules */
  validate(prop: Object[]): this;
  /** Set child rules */
  children(prop: Array<RuleChildren<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>>): this;
  /** Set options data */
  options(options: RuleOptions<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>): this;
  /** Set options target field */
  optionsTo(to: string): this;
  
  /** Set computed value */
  computed(prop: string | ((formData: FormData, api: Api<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>) => any)): this;
  /** Set update handler */
  update(prop: (value: any, rule: FormRule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>, api: Api<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>) => boolean | void): this;
  
  /** Set linked fields */
  link(prop: string[]): this;
  /** Set sync fields */
  sync(prop: string[]): this;
  /** Set custom emit events */
  emit(prop: Array<string | { name: string; inject: any }>): this;
  /** Set native emit events */
  nativeEmit(emit: Array<string | { name: string; inject: any }>): this;
  
  /** Set field prefix */
  prefix(prop: string | VNodeRule): this;
  /** Set field suffix */
  suffix(prop: string | VNodeRule): this;
  /** Set deep watch configuration */
  deep(deep: Object): this;
  /** Set injection data */
  inject(prop: any): this;
  /** Set slot update handler */
  slotUpdate(arg: PropArg<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>): this;
  
  /** Set control rules */
  control(prop: Control<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>[]): this;
  /** Set effect configuration */
  effect(prop: Object): this;
}

/**
 * Create a custom rule creator with predefined configuration
 * @param name - Creator name/type
 * @param init - Initial configuration object or setup function
 * @returns Creator helper function
 */
function creatorFactory(name: string, init?: Object | ((m: Creator<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>) => Creator<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>)): CreatorHelper<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>;

/**
 * Creator helper function signature
 * @param title - Field title or configuration object
 * @param field - Field name
 * @param value - Initial value
 * @param props - Component properties
 * @returns Configured creator instance
 */
interface CreatorHelper<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> {
  (title?: string | Object, field?: string, value?: any, props?: Object): Creator<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>;
}

/**
 * Creator factory interface for advanced creator creation
 */
interface CreatorFactory<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> {
  (name: string, init: Object | ((m: Creator<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>) => Creator<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>)): CreatorHelper<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>;
}

// Create custom input creator
const inputCreator = creatorFactory("input", {
  props: {
    placeholder: "Enter value..."
  }
});

// Use custom creator
const usernameRule = inputCreator("Username", "username", "", {
  required: true
});

// Create creator with setup function
const emailCreator = creatorFactory("input", (creator) => {
  return creator
    .props({ type: "email" })
    .validate([
      { type: "email", message: "Invalid email format" }
    ]);
});

/**
 * Deep copy a single rule
 * @param rule - Rule to copy
 * @param mode - Copy mode configuration
 * @returns Copied rule
 */
function copyRule(rule: Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>, mode?: boolean): Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>;

/**
 * Deep copy array of rules
 * @param rules - Rules to copy
 * @param mode - Copy mode configuration
 * @returns Copied rules array
 */
function copyRules(rules: Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>[], mode?: boolean): Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>[];

/**
 * Merge properties into existing rule
 * @param rule - Target rule to merge into
 * @param merge - Properties to merge
 * @returns Modified rule
 */
function mergeRule(rule: Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>, merge: Object): Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>;

/**
 * Parse JSON string to form rules
 * @param json - JSON string containing rules
 * @returns Parsed rules array
 */
function parseJson(json: string): FormRule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>[];

/**
 * Convert rules to JSON string
 * @param rules - Rules to serialize
 * @param space - JSON formatting space parameter
 * @returns JSON string representation
 */
function toJson(rules: FormRule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>[], space?: string | number): string;

/** Union type for form rules - can be rule object or creator instance */
type FormRule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> = 
  Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> | 
  Creator<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>;

/** Rule type with custom attributes */
type Rule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> = 
  BaseRule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> & RuleAttrs;

/** Creator type with custom attributes */
type Creator<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> = 
  BaseCreator<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> & CreatorAttrs;

/** Children rule type - can be string, rule, or function */
type RuleChildren<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> = 
  string | 
  FormRule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> | 
  RuleChildrenFn<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>;

/** Function type for dynamic children */
type RuleChildrenFn<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> = (
  data: loadParams<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>
) => FormRule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>[] | Promise<FormRule<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>[]>;

/** Options type - can be array or function */
type RuleOptions<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> = 
  Array<any> | 
  RuleOptionsFn<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>;

/** Function type for dynamic options */
type RuleOptionsFn<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs> = (
  data: loadParams<OptionAttrs, CreatorAttrs, RuleAttrs, ApiAttrs>
) => Array<any> | Promise<Array<any>>;