@regle/core 0.5.5 → 0.5.7

package/README.md

@@ -11,7 +11,7 @@ It's heavily inspired by Vuelidate.
 
 ## 📚 Documentation
 
-[![Documentation](https://raw.githubusercontent.com/victorgarciaesgi/regle/refs/heads/main/.github/images/redirectDoc.svg)](https://regle.vercel.app/)
+[![Documentation](https://raw.githubusercontent.com/victorgarciaesgi/regle/refs/heads/main/.github/images/redirectDoc.svg)](https://reglejs.dev/)
 
 ## 🎮 Play with it
 

package/dist/regle-core.d.cts

@@ -423,12 +423,38 @@ type IsPropertyOutputRequired<TState, TRule extends RegleFormPropertyType<any, a
 type SafeFieldProperty<TState, TRule extends RegleFormPropertyType<any, any> | undefined = never> = TRule extends RegleRuleDecl<any, any> ? unknown extends TRule['required'] ? Maybe<TState> : TRule['required'] extends undefined ? never : TRule['required'] extends RegleRuleDefinition<any, infer Params, any, any, any> ? Params extends never[] ? Maybe<TState> : Maybe<TState> : Maybe<TState> : Maybe<TState>;
 
 type useRegleFn<TCustomRules extends Partial<AllRulesDeclarations>, TShortcuts extends RegleShortcutDefinition<any> = never> = <TState extends Record<string, any>, TRules extends ReglePartialRuleTree<Unwrap<TState>, Partial<AllRulesDeclarations> & TCustomRules> & TValid, TValidationGroups extends Record<string, RegleValidationGroupEntry[]>, TValid = isDeepExact<NoInferLegacy<TRules>, ReglePartialRuleTree<Unwrap<TState>, Partial<AllRulesDeclarations> & TCustomRules>> extends true ? {} : MismatchInfo<NoInferLegacy<TRules>, ReglePartialRuleTree<Unwrap<TState>, Partial<AllRulesDeclarations> & TCustomRules>>>(state: MaybeRef<TState> | DeepReactiveState<TState>, rulesFactory: MaybeRefOrGetter<TRules>, options?: Partial<DeepMaybeRef<RegleBehaviourOptions>> & LocalRegleBehaviourOptions<Unwrap<TState>, TRules, TValidationGroups>) => Regle<Unwrap<TState>, TRules, TValidationGroups, TShortcuts>;
+/**
+ * useRegle serves as the foundation for validation logic.
+ *
+ * It accepts the following inputs:
+ *
+ * @param state - This can be a plain object, a ref, a reactive object, or a structure containing nested refs.
+ * @param rules - These should align with the structure of your state.
+ * @param modifiers - Customize computed beahviour
+ *
+ * ```ts
+ * import { useRegle } from '@regle/core';
+   import { required } from '@regle/rules';
+
+   const { r$ } = useRegle({ email: '' }, {
+     email: { required }
+   })
+ * ```
+ * Docs: {@link https://reglejs.dev/core-concepts/}
+ */
 declare const useRegle: useRegleFn<Partial<AllRulesDeclarations>, RegleShortcutDefinition<any>>;
 
 interface inferRulesFn<TCustomRules extends Partial<AllRulesDeclarations>> {
     <TState extends Record<string, any>, TRules extends ReglePartialRuleTree<Unwrap<TState>, Partial<AllRulesDeclarations> & TCustomRules> & TValid, TValid = isDeepExact<NoInferLegacy<TRules>, ReglePartialRuleTree<Unwrap<TState>, Partial<AllRulesDeclarations> & TCustomRules>> extends true ? {} : never>(state: MaybeRef<TState> | DeepReactiveState<TState> | undefined, rulesFactory: TRules): NoInferLegacy<TRules>;
     <TState extends PrimitiveTypes, TRules extends RegleRuleDecl>(state: MaybeRef<TState>, rulesFactory: TRules): NoInferLegacy<TRules>;
 }
+/**
+ * Rule type helper to provide autocomplete and typecheck to your form rules or part of your form rules
+ * It will just return the rules without any processing.
+ *
+ * @param state - The state reference
+ * @param rules - Your rule tree
+ */
 declare const inferRules: inferRulesFn<Partial<AllRulesDeclarations>>;
 
 declare function useRootStorage({ initialState, options, scopeRules, state, customRules, shortcuts, }: {
@@ -897,7 +923,6 @@ type MismatchInfo<Actual, Expected> = And<[Extends<PrintType<Actual>, '...'>, No
     [K in UsefulKeys<Actual> | UsefulKeys<Expected>]: MismatchInfo<K extends keyof Actual ? Actual[K] : never, K extends keyof Expected ? Expected[K] : never>;
 } : StrictEqualUsingBranding<Actual, Expected> extends true ? Actual : `[Regle error] The parent property does not match the form schema`;
 
-type ParamDecl<T = any> = MaybeRef<Maybe<T>> | (() => Maybe<T>);
 type CreateFn<T extends any[]> = (...args: T) => any;
 /**
  * Transform normal parameters tuple declaration to a rich tuple declaration
@@ -905,10 +930,10 @@ type CreateFn<T extends any[]> = (...args: T) => any;
  * [foo: string, bar?: number] => [foo: MaybeRef<string> | (() => string), bar?: MaybeRef<number | undefined> | (() => number) | undefined]
  */
 type RegleUniversalParams<T extends any[] = [], F = CreateFn<T>> = [T] extends [[]] ? [] : Parameters<F extends (...args: infer Args) => any ? (...args: {
-    [K in keyof Args]: ParamDecl<Args[K]>;
+    [K in keyof Args]: MaybeRefOrGetter<Maybe<Args[K]>>;
 }) => any : never>;
-type UnwrapRegleUniversalParams<T extends ParamDecl[] = [], F = CreateFn<T>> = [T] extends [[]] ? [] : Parameters<F extends (...args: infer Args) => any ? (...args: {
-    [K in keyof Args]: Args[K] extends ParamDecl<infer U> ? U : Args[K];
+type UnwrapRegleUniversalParams<T extends MaybeRefOrGetter[] = [], F = CreateFn<T>> = [T] extends [[]] ? [] : Parameters<F extends (...args: infer Args) => any ? (...args: {
+    [K in keyof Args]: Args[K] extends MaybeRefOrGetter<Maybe<infer U>> ? U : Args[K];
 }) => any : never>;
 
 /**
@@ -1210,6 +1235,9 @@ type $InternalRegleResult = {
  * @public
  */
 type RegleRoot<TState extends Record<string, any> = Record<string, any>, TRules extends ReglePartialRuleTree<TState> = Record<string, any>, TValidationGroups extends Record<string, RegleValidationGroupEntry[]> = never, TShortcuts extends RegleShortcutDefinition = {}> = RegleStatus<TState, TRules, TShortcuts> & ([TValidationGroups] extends [never] ? {} : {
+    /**
+     * Collection of validation groups used declared with the `validationGroups` modifier
+     */
     $groups: {
         readonly [TKey in keyof TValidationGroups]: RegleValidationGroupOutput;
     };
@@ -1218,12 +1246,17 @@ type RegleRoot<TState extends Record<string, any> = Record<string, any>, TRules
  * @public
  */
 type RegleStatus<TState extends Record<string, any> | undefined = Record<string, any>, TRules extends ReglePartialRuleTree<NonNullable<TState>> = Record<string, any>, TShortcuts extends RegleShortcutDefinition = {}> = RegleCommonStatus<TState> & {
+    /** Represents all the children of your object. You can access any nested child at any depth to get the relevant data you need for your form. */
     readonly $fields: {
         readonly [TKey in keyof TState]: InferRegleStatusType<NonNullable<TRules[TKey]>, NonNullable<TState>, TKey, TShortcuts>;
     } & {
         readonly [TKey in keyof TState as TRules[TKey] extends NonNullable<TRules[TKey]> ? TKey : never]-?: InferRegleStatusType<NonNullable<TRules[TKey]>, NonNullable<TState>, TKey, TShortcuts>;
     };
+    /** Collection of all the error messages, collected for all children properties and nested forms.
+     *
+     * Only contains errors from properties where $dirty equals true. */
     readonly $errors: RegleErrorTree<TState>;
+    /** Collection of all the error messages, collected for all children properties. */
     readonly $silentErrors: RegleErrorTree<TState>;
     $extractDirtyFields: (filterNullishValues?: boolean) => PartialDeep<TState>;
     $validate: () => Promise<RegleResult<TState, TRules>>;
@@ -1256,14 +1289,23 @@ type $InternalRegleStatusType = $InternalRegleCollectionStatus | $InternalRegleS
  * @public
  */
 type RegleFieldStatus<TState extends any = any, TRules extends RegleFormPropertyType<any, Partial<AllRulesDeclarations>> = Record<string, any>, TShortcuts extends RegleShortcutDefinition = never> = Omit<RegleCommonStatus<TState>, '$value'> & {
+    /** A reference to the original validated model. It can be used to bind your form with v-model.*/
     $value: Maybe<UnwrapNestedRefs<TState>>;
+    /** $value variant that will not "touch" the field and update the value silently, running only the rules, so you can easily swap values without impacting user interaction. */
     $silentValue: Maybe<UnwrapNestedRefs<TState>>;
+    /** Collection of all the error messages, collected for all children properties and nested forms.
+     *
+     * Only contains errors from properties where $dirty equals true. */
     readonly $errors: string[];
+    /** Collection of all the error messages, collected for all children properties and nested forms.  */
     readonly $silentErrors: string[];
     readonly $externalErrors: string[];
     readonly $tooltips: string[];
+    /** Will return a copy of your state with only the fields that are dirty. By default it will filter out nullish values or objects, but you can override it with the first parameter $extractDirtyFields(false). */
     $extractDirtyFields: (filterNullishValues?: boolean) => Maybe<TState>;
+    /** Sets all properties as dirty, triggering all rules. It returns a promise that will either resolve to false or a type safe copy of your form state. Values that had the required rule will be transformed into a non-nullable value (type only). */
     $validate: () => Promise<RegleResult<TState, TRules>>;
+    /** This is reactive tree containing all the declared rules of your field. To know more about the rule properties check the rules properties section */
     readonly $rules: {
         readonly [TRuleKey in keyof Omit<TRules, '$each' | keyof FieldRegleBehaviourOptions>]: RegleRuleStatus<TState, TRules[TRuleKey] extends RegleRuleDefinition<any, infer TParams, any> ? TParams : [], TRules[TRuleKey] extends RegleRuleDefinition<any, any, any, infer TMetadata> ? TMetadata : TRules[TRuleKey] extends InlineRuleDeclaration<any, any[], infer TMetadata> ? TMetadata extends Promise<infer P> ? P : TMetadata : any>;
     };
@@ -1292,35 +1334,58 @@ interface RegleCommonStatus<TValue = any> {
     readonly $invalid: boolean;
     readonly $dirty: boolean;
     readonly $anyDirty: boolean;
+    /** Indicates if any async rule for the field is currently running. Always false for synchronous rules. */
     readonly $pending: boolean;
+    /** Convenience flag to easily decide if a message should be displayed. Equivalent to $dirty && !$pending && $invalid. */
     readonly $error: boolean;
+    /** Indicates whether the field is ready for submission. Equivalent to !$invalid && !$pending. */
     readonly $ready: boolean;
+    /** Return the current key name of the field. */
     readonly $name: string;
+    /** Id used to track collections items */
     $id?: string;
+    /** A reference to the original validated model. It can be used to bind your form with v-model.*/
     $value: UnwrapNestedRefs<TValue>;
+    /** $value variant that will not "touch" the field and update the value silently, running only the rules, so you can easily swap values without impacting user interaction. */
     $silentValue: UnwrapNestedRefs<TValue>;
+    /** Marks the field and all nested properties as $dirty. */
     $touch(runCommit?: boolean, withConditions?: boolean): void;
+    /** Resets the $dirty state on all nested properties of a form. */
     $reset(): void;
+    /** Will reset both your validation state and your form state to their initial values. */
     $resetAll: () => void;
+    /** Clears the $externalResults state back to an empty object. */
+    $clearExternalErrors(): void;
+    /** @interal */
     $unwatch(): void;
+    /** @interal */
     $watch(): void;
-    $clearExternalErrors(): void;
 }
 /**
  * @public
  */
 type RegleRuleStatus<TValue = any, TParams extends any[] = any[], TMetadata extends RegleRuleMetadataDefinition = any> = {
+    /** The name of the rule type. */
     readonly $type: string;
+    /** Returns the computed error message or messages for the current rule. */
     readonly $message: string | string[];
     readonly $tooltip: string | string[];
+    /** Indicates whether or not the rule is enabled (for rules like requiredIf) */
     readonly $active: boolean;
+    /** Indicates the state of validation for this validator. */
     readonly $valid: boolean;
+    /** If the rule is async, indicates if it's currently pending. Always false if it's synchronous. */
     readonly $pending: boolean;
+    /** Returns the current path of the rule (used internally for tracking) */
     readonly $path: string;
+    /** Contains the metadata returned by the validator function. */
     readonly $metadata: TMetadata;
-    $validator: ((value: Maybe<TValue>, ...args: [TParams] extends [never[]] ? [] : [unknown[]] extends [TParams] ? any[] : TParams) => RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>) & ((value: TValue, ...args: [TParams] extends [never[]] ? [] : [unknown[]] extends [TParams] ? any[] : TParams) => RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>);
+    /** Run the rule validator and compute its properties like $message and $active */
     $validate(): Promise<boolean>;
+    /** Reset the $valid, $metadata and $pending states */
     $reset(): void;
+    /** Returns the original rule validator function. */
+    $validator: ((value: Maybe<TValue>, ...args: [TParams] extends [never[]] ? [] : [unknown[]] extends [TParams] ? any[] : TParams) => RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>) & ((value: TValue, ...args: [TParams] extends [never[]] ? [] : [unknown[]] extends [TParams] ? any[] : TParams) => RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>);
 } & ([TParams] extends [never[]] ? {} : [unknown[]] extends [TParams] ? {
     readonly $params?: any[];
 } : {
@@ -1353,13 +1418,23 @@ interface $InternalRegleRuleStatus {
  * @public
  */
 type RegleCollectionStatus<TState extends any[] = any[], TRules extends ReglePartialRuleTree<ArrayElement<TState>> = Record<string, any>, TFieldRule extends RegleCollectionRuleDecl<any, any> = never, TShortcuts extends RegleShortcutDefinition = {}> = Omit<RegleCommonStatus<TState>, '$value'> & {
+    /** A reference to the original validated model. It can be used to bind your form with v-model.*/
     $value: Maybe<TState>;
+    /** $value variant that will not "touch" the field and update the value silently, running only the rules, so you can easily swap values without impacting user interaction. */
     $silentValue: Maybe<TState>;
+    /** Collection of status of every item in your collection. Each item will be a field you can access, or map on it to display your elements. */
     readonly $each: Array<InferRegleStatusType<NonNullable<TRules>, NonNullable<TState>, number, TShortcuts>>;
+    /** Represents the status of the collection itself. You can have validation rules on the array like minLength, this field represents the isolated status of the collection. */
     readonly $field: RegleFieldStatus<TState, TFieldRule, TShortcuts>;
+    /** Collection of all the error messages, collected for all children properties and nested forms.
+     *
+     * Only contains errors from properties where $dirty equals true. */
     readonly $errors: RegleCollectionErrors<TState>;
+    /** Collection of all the error messages, collected for all children properties and nested forms.  */
     readonly $silentErrors: RegleCollectionErrors<TState>;
+    /** Will return a copy of your state with only the fields that are dirty. By default it will filter out nullish values or objects, but you can override it with the first parameter $extractDirtyFields(false). */
     $extractDirtyFields: (filterNullishValues?: boolean) => PartialDeep<TState>;
+    /** Sets all properties as dirty, triggering all rules. It returns a promise that will either resolve to false or a type safe copy of your form state. Values that had the required rule will be transformed into a non-nullable value (type only). */
     $validate: () => Promise<RegleResult<TState, TRules>>;
 } & ([TShortcuts['collections']] extends [never] ? {} : {
     [K in keyof TShortcuts['collections']]: ReturnType<NonNullable<TShortcuts['collections']>[K]>;
@@ -1382,7 +1457,6 @@ interface $InternalRegleCollectionStatus extends Omit<$InternalRegleStatus, '$fi
 }
 
 /**
- * @description
  * Create a typed custom rule that can be used like default rules.
  * It can also be declared in the global options
  *
@@ -1391,6 +1465,7 @@ interface $InternalRegleCollectionStatus extends Omit<$InternalRegleStatus, '$fi
  * @typeParam TValue - The input value the rule should receive
  * @typeParam TParams - Tuple declaration of the rule parameters (if any)
  *
+ *
  * @param definition - The rule processors object
  *
  * @returns A rule definition that can be callable depending on params presence
@@ -1402,7 +1477,7 @@ interface $InternalRegleCollectionStatus extends Omit<$InternalRegleStatus, '$fi
  * import {isFilled} from '@regle/rules';
  *
  * export const isFoo = createRule({
- *   validator(value: string) {
+ *   validator(value: Maybe<string>) {
  *       if (isFilled(value)) {
  *           return value === 'foo';
  *       }
@@ -1410,7 +1485,10 @@ interface $InternalRegleCollectionStatus extends Omit<$InternalRegleStatus, '$fi
  *   },
  *   message: "The value should be 'foo'"
  * })
+ *
  * ```
+ *
+ * Docs: {@link https://reglejs.dev/core-concepts/rules/reusable-rules}
  */
 declare function createRule<TValue extends any, TParams extends any[], TReturn extends RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>, TMetadata extends RegleRuleMetadataDefinition = TReturn extends Promise<infer M> ? M : TReturn, TAsync extends boolean = TReturn extends Promise<any> ? true : false>(definition: RegleRuleInit<TValue, TParams, TReturn, TMetadata, TAsync>): InferRegleRule<TValue, TParams, TAsync, TMetadata>;
 
@@ -1418,8 +1496,20 @@ declare function createRule<TValue extends any, TParams extends any[], TReturn e
  * Returns a clean list of parameters
  * Removing Ref and executing function to return the unwraped value
  */
-declare function unwrapRuleParameters<TParams extends any[]>(params: ParamDecl[]): TParams;
+declare function unwrapRuleParameters<TParams extends any[]>(params: MaybeRefOrGetter[]): TParams;
 
+/**
+ * Define a global regle configuration, where you can:
+ * - Customize buil-in rules messages
+ * - Add your custom rules
+ * - Define global modifiers
+ * - Define shortcuts
+ *
+ * It will return:
+ *
+ * - a `useRegle` composable that can typecheck your custom rules
+ * - an `inferRules` helper that can typecheck your custom rules
+ */
 declare function defineRegleConfig<TShortcuts extends RegleShortcutDefinition<TCustomRules>, TCustomRules extends Partial<AllRulesDeclarations> = EmptyObject>({ rules, modifiers, shortcuts, }: {
     rules?: () => TCustomRules;
     modifiers?: RegleBehaviourOptions;
@@ -1429,4 +1519,4 @@ declare function defineRegleConfig<TShortcuts extends RegleShortcutDefinition<TC
     inferRules: inferRulesFn<TCustomRules>;
 };
 
-export { type $InternalRegleStatus, type AllRulesDeclarations, type DeepMaybeRef, type FormRuleDeclaration, type InferRegleRoot, type InferRegleRule, type InferRegleRules, type InferRegleShortcuts, type InferRegleStatusType, type InlineRuleDeclaration, InternalRuleType, type LocalRegleBehaviourOptions, type Maybe, type NoInferLegacy, type ParamDecl, type PrimitiveTypes, type Regle, type RegleBehaviourOptions, type RegleCollectionErrors, type RegleCollectionRuleDecl, type RegleCollectionRuleDefinition, type RegleCollectionStatus, type RegleCommonStatus, type RegleComputedRules, type RegleEnforceCustomRequiredRules, type RegleEnforceRequiredRules, type RegleErrorTree, type RegleExternalCollectionErrors, type RegleExternalErrorTree, type RegleFieldStatus, type RegleFormPropertyType, type RegleInternalRuleDefs, type ReglePartialRuleTree, type RegleResult, type RegleRoot, type RegleRuleCore, type RegleRuleDecl, type RegleRuleDefinition, type RegleRuleDefinitionProcessor, type RegleRuleDefinitionWithMetadataProcessor, type RegleRuleInit, type RegleRuleMetadataConsumer, type RegleRuleMetadataDefinition, type RegleRuleMetadataExtended, type RegleRuleRaw, type RegleRuleStatus, type RegleRuleTypeReturn, type RegleRuleWithParamsDefinition, type RegleShortcutDefinition, type RegleStatus, type RegleUniversalParams, type RegleValidationErrors, type RegleValidationGroupEntry, type RegleValidationGroupOutput, type RegleRuleTree as RegleValidationTree, type ResolvedRegleBehaviourOptions, type Unwrap, type UnwrapRegleUniversalParams, type UnwrapRuleWithParams, createRule, defineRegleConfig, inferRules, unwrapRuleParameters, useRegle, useRootStorage };
+export { type $InternalRegleStatus, type AllRulesDeclarations, type DeepMaybeRef, type FormRuleDeclaration, type InferRegleRoot, type InferRegleRule, type InferRegleRules, type InferRegleShortcuts, type InferRegleStatusType, type InlineRuleDeclaration, InternalRuleType, type LocalRegleBehaviourOptions, type Maybe, type NoInferLegacy, type PrimitiveTypes, type Regle, type RegleBehaviourOptions, type RegleCollectionErrors, type RegleCollectionRuleDecl, type RegleCollectionRuleDefinition, type RegleCollectionStatus, type RegleCommonStatus, type RegleComputedRules, type RegleEnforceCustomRequiredRules, type RegleEnforceRequiredRules, type RegleErrorTree, type RegleExternalCollectionErrors, type RegleExternalErrorTree, type RegleFieldStatus, type RegleFormPropertyType, type RegleInternalRuleDefs, type ReglePartialRuleTree, type RegleResult, type RegleRoot, type RegleRuleCore, type RegleRuleDecl, type RegleRuleDefinition, type RegleRuleDefinitionProcessor, type RegleRuleDefinitionWithMetadataProcessor, type RegleRuleInit, type RegleRuleMetadataConsumer, type RegleRuleMetadataDefinition, type RegleRuleMetadataExtended, type RegleRuleRaw, type RegleRuleStatus, type RegleRuleTypeReturn, type RegleRuleWithParamsDefinition, type RegleShortcutDefinition, type RegleStatus, type RegleUniversalParams, type RegleValidationErrors, type RegleValidationGroupEntry, type RegleValidationGroupOutput, type RegleRuleTree as RegleValidationTree, type ResolvedRegleBehaviourOptions, type Unwrap, type UnwrapRegleUniversalParams, type UnwrapRuleWithParams, createRule, defineRegleConfig, inferRules, unwrapRuleParameters, useRegle, useRootStorage };

package/dist/regle-core.d.ts

@@ -423,12 +423,38 @@ type IsPropertyOutputRequired<TState, TRule extends RegleFormPropertyType<any, a
 type SafeFieldProperty<TState, TRule extends RegleFormPropertyType<any, any> | undefined = never> = TRule extends RegleRuleDecl<any, any> ? unknown extends TRule['required'] ? Maybe<TState> : TRule['required'] extends undefined ? never : TRule['required'] extends RegleRuleDefinition<any, infer Params, any, any, any> ? Params extends never[] ? Maybe<TState> : Maybe<TState> : Maybe<TState> : Maybe<TState>;
 
 type useRegleFn<TCustomRules extends Partial<AllRulesDeclarations>, TShortcuts extends RegleShortcutDefinition<any> = never> = <TState extends Record<string, any>, TRules extends ReglePartialRuleTree<Unwrap<TState>, Partial<AllRulesDeclarations> & TCustomRules> & TValid, TValidationGroups extends Record<string, RegleValidationGroupEntry[]>, TValid = isDeepExact<NoInferLegacy<TRules>, ReglePartialRuleTree<Unwrap<TState>, Partial<AllRulesDeclarations> & TCustomRules>> extends true ? {} : MismatchInfo<NoInferLegacy<TRules>, ReglePartialRuleTree<Unwrap<TState>, Partial<AllRulesDeclarations> & TCustomRules>>>(state: MaybeRef<TState> | DeepReactiveState<TState>, rulesFactory: MaybeRefOrGetter<TRules>, options?: Partial<DeepMaybeRef<RegleBehaviourOptions>> & LocalRegleBehaviourOptions<Unwrap<TState>, TRules, TValidationGroups>) => Regle<Unwrap<TState>, TRules, TValidationGroups, TShortcuts>;
+/**
+ * useRegle serves as the foundation for validation logic.
+ *
+ * It accepts the following inputs:
+ *
+ * @param state - This can be a plain object, a ref, a reactive object, or a structure containing nested refs.
+ * @param rules - These should align with the structure of your state.
+ * @param modifiers - Customize computed beahviour
+ *
+ * ```ts
+ * import { useRegle } from '@regle/core';
+   import { required } from '@regle/rules';
+
+   const { r$ } = useRegle({ email: '' }, {
+     email: { required }
+   })
+ * ```
+ * Docs: {@link https://reglejs.dev/core-concepts/}
+ */
 declare const useRegle: useRegleFn<Partial<AllRulesDeclarations>, RegleShortcutDefinition<any>>;
 
 interface inferRulesFn<TCustomRules extends Partial<AllRulesDeclarations>> {
     <TState extends Record<string, any>, TRules extends ReglePartialRuleTree<Unwrap<TState>, Partial<AllRulesDeclarations> & TCustomRules> & TValid, TValid = isDeepExact<NoInferLegacy<TRules>, ReglePartialRuleTree<Unwrap<TState>, Partial<AllRulesDeclarations> & TCustomRules>> extends true ? {} : never>(state: MaybeRef<TState> | DeepReactiveState<TState> | undefined, rulesFactory: TRules): NoInferLegacy<TRules>;
     <TState extends PrimitiveTypes, TRules extends RegleRuleDecl>(state: MaybeRef<TState>, rulesFactory: TRules): NoInferLegacy<TRules>;
 }
+/**
+ * Rule type helper to provide autocomplete and typecheck to your form rules or part of your form rules
+ * It will just return the rules without any processing.
+ *
+ * @param state - The state reference
+ * @param rules - Your rule tree
+ */
 declare const inferRules: inferRulesFn<Partial<AllRulesDeclarations>>;
 
 declare function useRootStorage({ initialState, options, scopeRules, state, customRules, shortcuts, }: {
@@ -897,7 +923,6 @@ type MismatchInfo<Actual, Expected> = And<[Extends<PrintType<Actual>, '...'>, No
     [K in UsefulKeys<Actual> | UsefulKeys<Expected>]: MismatchInfo<K extends keyof Actual ? Actual[K] : never, K extends keyof Expected ? Expected[K] : never>;
 } : StrictEqualUsingBranding<Actual, Expected> extends true ? Actual : `[Regle error] The parent property does not match the form schema`;
 
-type ParamDecl<T = any> = MaybeRef<Maybe<T>> | (() => Maybe<T>);
 type CreateFn<T extends any[]> = (...args: T) => any;
 /**
  * Transform normal parameters tuple declaration to a rich tuple declaration
@@ -905,10 +930,10 @@ type CreateFn<T extends any[]> = (...args: T) => any;
  * [foo: string, bar?: number] => [foo: MaybeRef<string> | (() => string), bar?: MaybeRef<number | undefined> | (() => number) | undefined]
  */
 type RegleUniversalParams<T extends any[] = [], F = CreateFn<T>> = [T] extends [[]] ? [] : Parameters<F extends (...args: infer Args) => any ? (...args: {
-    [K in keyof Args]: ParamDecl<Args[K]>;
+    [K in keyof Args]: MaybeRefOrGetter<Maybe<Args[K]>>;
 }) => any : never>;
-type UnwrapRegleUniversalParams<T extends ParamDecl[] = [], F = CreateFn<T>> = [T] extends [[]] ? [] : Parameters<F extends (...args: infer Args) => any ? (...args: {
-    [K in keyof Args]: Args[K] extends ParamDecl<infer U> ? U : Args[K];
+type UnwrapRegleUniversalParams<T extends MaybeRefOrGetter[] = [], F = CreateFn<T>> = [T] extends [[]] ? [] : Parameters<F extends (...args: infer Args) => any ? (...args: {
+    [K in keyof Args]: Args[K] extends MaybeRefOrGetter<Maybe<infer U>> ? U : Args[K];
 }) => any : never>;
 
 /**
@@ -1210,6 +1235,9 @@ type $InternalRegleResult = {
  * @public
  */
 type RegleRoot<TState extends Record<string, any> = Record<string, any>, TRules extends ReglePartialRuleTree<TState> = Record<string, any>, TValidationGroups extends Record<string, RegleValidationGroupEntry[]> = never, TShortcuts extends RegleShortcutDefinition = {}> = RegleStatus<TState, TRules, TShortcuts> & ([TValidationGroups] extends [never] ? {} : {
+    /**
+     * Collection of validation groups used declared with the `validationGroups` modifier
+     */
     $groups: {
         readonly [TKey in keyof TValidationGroups]: RegleValidationGroupOutput;
     };
@@ -1218,12 +1246,17 @@ type RegleRoot<TState extends Record<string, any> = Record<string, any>, TRules
  * @public
  */
 type RegleStatus<TState extends Record<string, any> | undefined = Record<string, any>, TRules extends ReglePartialRuleTree<NonNullable<TState>> = Record<string, any>, TShortcuts extends RegleShortcutDefinition = {}> = RegleCommonStatus<TState> & {
+    /** Represents all the children of your object. You can access any nested child at any depth to get the relevant data you need for your form. */
     readonly $fields: {
         readonly [TKey in keyof TState]: InferRegleStatusType<NonNullable<TRules[TKey]>, NonNullable<TState>, TKey, TShortcuts>;
     } & {
         readonly [TKey in keyof TState as TRules[TKey] extends NonNullable<TRules[TKey]> ? TKey : never]-?: InferRegleStatusType<NonNullable<TRules[TKey]>, NonNullable<TState>, TKey, TShortcuts>;
     };
+    /** Collection of all the error messages, collected for all children properties and nested forms.
+     *
+     * Only contains errors from properties where $dirty equals true. */
     readonly $errors: RegleErrorTree<TState>;
+    /** Collection of all the error messages, collected for all children properties. */
     readonly $silentErrors: RegleErrorTree<TState>;
     $extractDirtyFields: (filterNullishValues?: boolean) => PartialDeep<TState>;
     $validate: () => Promise<RegleResult<TState, TRules>>;
@@ -1256,14 +1289,23 @@ type $InternalRegleStatusType = $InternalRegleCollectionStatus | $InternalRegleS
  * @public
  */
 type RegleFieldStatus<TState extends any = any, TRules extends RegleFormPropertyType<any, Partial<AllRulesDeclarations>> = Record<string, any>, TShortcuts extends RegleShortcutDefinition = never> = Omit<RegleCommonStatus<TState>, '$value'> & {
+    /** A reference to the original validated model. It can be used to bind your form with v-model.*/
     $value: Maybe<UnwrapNestedRefs<TState>>;
+    /** $value variant that will not "touch" the field and update the value silently, running only the rules, so you can easily swap values without impacting user interaction. */
     $silentValue: Maybe<UnwrapNestedRefs<TState>>;
+    /** Collection of all the error messages, collected for all children properties and nested forms.
+     *
+     * Only contains errors from properties where $dirty equals true. */
     readonly $errors: string[];
+    /** Collection of all the error messages, collected for all children properties and nested forms.  */
     readonly $silentErrors: string[];
     readonly $externalErrors: string[];
     readonly $tooltips: string[];
+    /** Will return a copy of your state with only the fields that are dirty. By default it will filter out nullish values or objects, but you can override it with the first parameter $extractDirtyFields(false). */
     $extractDirtyFields: (filterNullishValues?: boolean) => Maybe<TState>;
+    /** Sets all properties as dirty, triggering all rules. It returns a promise that will either resolve to false or a type safe copy of your form state. Values that had the required rule will be transformed into a non-nullable value (type only). */
     $validate: () => Promise<RegleResult<TState, TRules>>;
+    /** This is reactive tree containing all the declared rules of your field. To know more about the rule properties check the rules properties section */
     readonly $rules: {
         readonly [TRuleKey in keyof Omit<TRules, '$each' | keyof FieldRegleBehaviourOptions>]: RegleRuleStatus<TState, TRules[TRuleKey] extends RegleRuleDefinition<any, infer TParams, any> ? TParams : [], TRules[TRuleKey] extends RegleRuleDefinition<any, any, any, infer TMetadata> ? TMetadata : TRules[TRuleKey] extends InlineRuleDeclaration<any, any[], infer TMetadata> ? TMetadata extends Promise<infer P> ? P : TMetadata : any>;
     };
@@ -1292,35 +1334,58 @@ interface RegleCommonStatus<TValue = any> {
     readonly $invalid: boolean;
     readonly $dirty: boolean;
     readonly $anyDirty: boolean;
+    /** Indicates if any async rule for the field is currently running. Always false for synchronous rules. */
     readonly $pending: boolean;
+    /** Convenience flag to easily decide if a message should be displayed. Equivalent to $dirty && !$pending && $invalid. */
     readonly $error: boolean;
+    /** Indicates whether the field is ready for submission. Equivalent to !$invalid && !$pending. */
     readonly $ready: boolean;
+    /** Return the current key name of the field. */
     readonly $name: string;
+    /** Id used to track collections items */
     $id?: string;
+    /** A reference to the original validated model. It can be used to bind your form with v-model.*/
     $value: UnwrapNestedRefs<TValue>;
+    /** $value variant that will not "touch" the field and update the value silently, running only the rules, so you can easily swap values without impacting user interaction. */
     $silentValue: UnwrapNestedRefs<TValue>;
+    /** Marks the field and all nested properties as $dirty. */
     $touch(runCommit?: boolean, withConditions?: boolean): void;
+    /** Resets the $dirty state on all nested properties of a form. */
     $reset(): void;
+    /** Will reset both your validation state and your form state to their initial values. */
     $resetAll: () => void;
+    /** Clears the $externalResults state back to an empty object. */
+    $clearExternalErrors(): void;
+    /** @interal */
     $unwatch(): void;
+    /** @interal */
     $watch(): void;
-    $clearExternalErrors(): void;
 }
 /**
  * @public
  */
 type RegleRuleStatus<TValue = any, TParams extends any[] = any[], TMetadata extends RegleRuleMetadataDefinition = any> = {
+    /** The name of the rule type. */
     readonly $type: string;
+    /** Returns the computed error message or messages for the current rule. */
     readonly $message: string | string[];
     readonly $tooltip: string | string[];
+    /** Indicates whether or not the rule is enabled (for rules like requiredIf) */
     readonly $active: boolean;
+    /** Indicates the state of validation for this validator. */
     readonly $valid: boolean;
+    /** If the rule is async, indicates if it's currently pending. Always false if it's synchronous. */
     readonly $pending: boolean;
+    /** Returns the current path of the rule (used internally for tracking) */
     readonly $path: string;
+    /** Contains the metadata returned by the validator function. */
     readonly $metadata: TMetadata;
-    $validator: ((value: Maybe<TValue>, ...args: [TParams] extends [never[]] ? [] : [unknown[]] extends [TParams] ? any[] : TParams) => RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>) & ((value: TValue, ...args: [TParams] extends [never[]] ? [] : [unknown[]] extends [TParams] ? any[] : TParams) => RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>);
+    /** Run the rule validator and compute its properties like $message and $active */
     $validate(): Promise<boolean>;
+    /** Reset the $valid, $metadata and $pending states */
     $reset(): void;
+    /** Returns the original rule validator function. */
+    $validator: ((value: Maybe<TValue>, ...args: [TParams] extends [never[]] ? [] : [unknown[]] extends [TParams] ? any[] : TParams) => RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>) & ((value: TValue, ...args: [TParams] extends [never[]] ? [] : [unknown[]] extends [TParams] ? any[] : TParams) => RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>);
 } & ([TParams] extends [never[]] ? {} : [unknown[]] extends [TParams] ? {
     readonly $params?: any[];
 } : {
@@ -1353,13 +1418,23 @@ interface $InternalRegleRuleStatus {
  * @public
  */
 type RegleCollectionStatus<TState extends any[] = any[], TRules extends ReglePartialRuleTree<ArrayElement<TState>> = Record<string, any>, TFieldRule extends RegleCollectionRuleDecl<any, any> = never, TShortcuts extends RegleShortcutDefinition = {}> = Omit<RegleCommonStatus<TState>, '$value'> & {
+    /** A reference to the original validated model. It can be used to bind your form with v-model.*/
     $value: Maybe<TState>;
+    /** $value variant that will not "touch" the field and update the value silently, running only the rules, so you can easily swap values without impacting user interaction. */
     $silentValue: Maybe<TState>;
+    /** Collection of status of every item in your collection. Each item will be a field you can access, or map on it to display your elements. */
     readonly $each: Array<InferRegleStatusType<NonNullable<TRules>, NonNullable<TState>, number, TShortcuts>>;
+    /** Represents the status of the collection itself. You can have validation rules on the array like minLength, this field represents the isolated status of the collection. */
     readonly $field: RegleFieldStatus<TState, TFieldRule, TShortcuts>;
+    /** Collection of all the error messages, collected for all children properties and nested forms.
+     *
+     * Only contains errors from properties where $dirty equals true. */
     readonly $errors: RegleCollectionErrors<TState>;
+    /** Collection of all the error messages, collected for all children properties and nested forms.  */
     readonly $silentErrors: RegleCollectionErrors<TState>;
+    /** Will return a copy of your state with only the fields that are dirty. By default it will filter out nullish values or objects, but you can override it with the first parameter $extractDirtyFields(false). */
     $extractDirtyFields: (filterNullishValues?: boolean) => PartialDeep<TState>;
+    /** Sets all properties as dirty, triggering all rules. It returns a promise that will either resolve to false or a type safe copy of your form state. Values that had the required rule will be transformed into a non-nullable value (type only). */
     $validate: () => Promise<RegleResult<TState, TRules>>;
 } & ([TShortcuts['collections']] extends [never] ? {} : {
     [K in keyof TShortcuts['collections']]: ReturnType<NonNullable<TShortcuts['collections']>[K]>;
@@ -1382,7 +1457,6 @@ interface $InternalRegleCollectionStatus extends Omit<$InternalRegleStatus, '$fi
 }
 
 /**
- * @description
  * Create a typed custom rule that can be used like default rules.
  * It can also be declared in the global options
  *
@@ -1391,6 +1465,7 @@ interface $InternalRegleCollectionStatus extends Omit<$InternalRegleStatus, '$fi
  * @typeParam TValue - The input value the rule should receive
  * @typeParam TParams - Tuple declaration of the rule parameters (if any)
  *
+ *
  * @param definition - The rule processors object
  *
  * @returns A rule definition that can be callable depending on params presence
@@ -1402,7 +1477,7 @@ interface $InternalRegleCollectionStatus extends Omit<$InternalRegleStatus, '$fi
  * import {isFilled} from '@regle/rules';
  *
  * export const isFoo = createRule({
- *   validator(value: string) {
+ *   validator(value: Maybe<string>) {
  *       if (isFilled(value)) {
  *           return value === 'foo';
  *       }
@@ -1410,7 +1485,10 @@ interface $InternalRegleCollectionStatus extends Omit<$InternalRegleStatus, '$fi
  *   },
  *   message: "The value should be 'foo'"
  * })
+ *
  * ```
+ *
+ * Docs: {@link https://reglejs.dev/core-concepts/rules/reusable-rules}
  */
 declare function createRule<TValue extends any, TParams extends any[], TReturn extends RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>, TMetadata extends RegleRuleMetadataDefinition = TReturn extends Promise<infer M> ? M : TReturn, TAsync extends boolean = TReturn extends Promise<any> ? true : false>(definition: RegleRuleInit<TValue, TParams, TReturn, TMetadata, TAsync>): InferRegleRule<TValue, TParams, TAsync, TMetadata>;
 
@@ -1418,8 +1496,20 @@ declare function createRule<TValue extends any, TParams extends any[], TReturn e
  * Returns a clean list of parameters
  * Removing Ref and executing function to return the unwraped value
  */
-declare function unwrapRuleParameters<TParams extends any[]>(params: ParamDecl[]): TParams;
+declare function unwrapRuleParameters<TParams extends any[]>(params: MaybeRefOrGetter[]): TParams;
 
+/**
+ * Define a global regle configuration, where you can:
+ * - Customize buil-in rules messages
+ * - Add your custom rules
+ * - Define global modifiers
+ * - Define shortcuts
+ *
+ * It will return:
+ *
+ * - a `useRegle` composable that can typecheck your custom rules
+ * - an `inferRules` helper that can typecheck your custom rules
+ */
 declare function defineRegleConfig<TShortcuts extends RegleShortcutDefinition<TCustomRules>, TCustomRules extends Partial<AllRulesDeclarations> = EmptyObject>({ rules, modifiers, shortcuts, }: {
     rules?: () => TCustomRules;
     modifiers?: RegleBehaviourOptions;
@@ -1429,4 +1519,4 @@ declare function defineRegleConfig<TShortcuts extends RegleShortcutDefinition<TC
     inferRules: inferRulesFn<TCustomRules>;
 };
 
-export { type $InternalRegleStatus, type AllRulesDeclarations, type DeepMaybeRef, type FormRuleDeclaration, type InferRegleRoot, type InferRegleRule, type InferRegleRules, type InferRegleShortcuts, type InferRegleStatusType, type InlineRuleDeclaration, InternalRuleType, type LocalRegleBehaviourOptions, type Maybe, type NoInferLegacy, type ParamDecl, type PrimitiveTypes, type Regle, type RegleBehaviourOptions, type RegleCollectionErrors, type RegleCollectionRuleDecl, type RegleCollectionRuleDefinition, type RegleCollectionStatus, type RegleCommonStatus, type RegleComputedRules, type RegleEnforceCustomRequiredRules, type RegleEnforceRequiredRules, type RegleErrorTree, type RegleExternalCollectionErrors, type RegleExternalErrorTree, type RegleFieldStatus, type RegleFormPropertyType, type RegleInternalRuleDefs, type ReglePartialRuleTree, type RegleResult, type RegleRoot, type RegleRuleCore, type RegleRuleDecl, type RegleRuleDefinition, type RegleRuleDefinitionProcessor, type RegleRuleDefinitionWithMetadataProcessor, type RegleRuleInit, type RegleRuleMetadataConsumer, type RegleRuleMetadataDefinition, type RegleRuleMetadataExtended, type RegleRuleRaw, type RegleRuleStatus, type RegleRuleTypeReturn, type RegleRuleWithParamsDefinition, type RegleShortcutDefinition, type RegleStatus, type RegleUniversalParams, type RegleValidationErrors, type RegleValidationGroupEntry, type RegleValidationGroupOutput, type RegleRuleTree as RegleValidationTree, type ResolvedRegleBehaviourOptions, type Unwrap, type UnwrapRegleUniversalParams, type UnwrapRuleWithParams, createRule, defineRegleConfig, inferRules, unwrapRuleParameters, useRegle, useRootStorage };
+export { type $InternalRegleStatus, type AllRulesDeclarations, type DeepMaybeRef, type FormRuleDeclaration, type InferRegleRoot, type InferRegleRule, type InferRegleRules, type InferRegleShortcuts, type InferRegleStatusType, type InlineRuleDeclaration, InternalRuleType, type LocalRegleBehaviourOptions, type Maybe, type NoInferLegacy, type PrimitiveTypes, type Regle, type RegleBehaviourOptions, type RegleCollectionErrors, type RegleCollectionRuleDecl, type RegleCollectionRuleDefinition, type RegleCollectionStatus, type RegleCommonStatus, type RegleComputedRules, type RegleEnforceCustomRequiredRules, type RegleEnforceRequiredRules, type RegleErrorTree, type RegleExternalCollectionErrors, type RegleExternalErrorTree, type RegleFieldStatus, type RegleFormPropertyType, type RegleInternalRuleDefs, type ReglePartialRuleTree, type RegleResult, type RegleRoot, type RegleRuleCore, type RegleRuleDecl, type RegleRuleDefinition, type RegleRuleDefinitionProcessor, type RegleRuleDefinitionWithMetadataProcessor, type RegleRuleInit, type RegleRuleMetadataConsumer, type RegleRuleMetadataDefinition, type RegleRuleMetadataExtended, type RegleRuleRaw, type RegleRuleStatus, type RegleRuleTypeReturn, type RegleRuleWithParamsDefinition, type RegleShortcutDefinition, type RegleStatus, type RegleUniversalParams, type RegleValidationErrors, type RegleValidationGroupEntry, type RegleValidationGroupOutput, type RegleRuleTree as RegleValidationTree, type ResolvedRegleBehaviourOptions, type Unwrap, type UnwrapRegleUniversalParams, type UnwrapRuleWithParams, createRule, defineRegleConfig, inferRules, unwrapRuleParameters, useRegle, useRootStorage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@regle/core",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Typescript-first model-based form validation library for Vue 3",
   "peerDependencies": {
     "vue": "^3.3.0"
@@ -62,7 +62,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "homepage": "https://regle.vercel.app/",
+  "homepage": "https://reglejs.dev/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/victorgarciaesgi/regle.git"