@regle/core 0.5.6 → 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, }: {
@@ -1209,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;
     };
@@ -1217,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>>;
@@ -1255,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>;
     };
@@ -1291,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[];
 } : {
@@ -1352,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]>;
@@ -1389,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
@@ -1408,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,6 +1498,18 @@ declare function createRule<TValue extends any, TParams extends any[], TReturn e
  */
 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;

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, }: {
@@ -1209,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;
     };
@@ -1217,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>>;
@@ -1255,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>;
     };
@@ -1291,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[];
 } : {
@@ -1352,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]>;
@@ -1389,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
@@ -1408,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,6 +1498,18 @@ declare function createRule<TValue extends any, TParams extends any[], TReturn e
  */
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@regle/core",
-  "version": "0.5.6",
+  "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"