diff --git a/README.md b/README.md index 919faa1..8d0635d 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,7 @@ planetsField.parent; // ⮕ universeField ``` -Fields returned by the [`Field.at`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.FieldBase.html#at) +Fields returned by the [`Field.at`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.BareField.html#at) method have a stable identity. This means that you can invoke `at` with the same key multiple times and the same field instance is returned: @@ -186,14 +186,14 @@ const unsubscribe = planetsField.on('change:value', event => { // ⮕ () => void ``` -The [`Field.on`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.FieldBase.html#on) method +The [`Field.on`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.BareField.html#on) method associates the event subscriber with an event type. All events that are dispatched onto fields have the share [`Event`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.Event.html). Without plugins, fields can dispatch events with -[`change:value`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.FieldBase.html#on.on-2) type. This +[`change:value`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.BareField.html#on.on-2) type. This event is dispatched when the field value is changed via -[`Field.setValue`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.FieldBase.html#setValue). +[`Field.setValue`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.BareField.html#setValue). Plugins may dispatch their own events. Here's an example of the [`change:errors`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.ErrorsPlugin.html#on.on-1) event @@ -234,7 +234,7 @@ planetsField.on('*', event => { # Transient updates -When you call [`Field.setValue`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.FieldBase.html#setValue) +When you call [`Field.setValue`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.BareField.html#setValue) on a field then subscribers of its ancestors and its updated child fields are triggered. To manually control the update propagation to fields ancestors, you can use transient updates. @@ -261,7 +261,7 @@ avatarField.at('eyeColor').isTransient; ``` To propagate the transient value contained by the child field to its parent, use the -[`Field.propagate`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.FieldBase.html#propagate) +[`Field.propagate`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.BareField.html#propagate) method: ```ts @@ -271,7 +271,7 @@ avatarField.value; // ⮕ { eyeColor: 'green' } ``` -[`Field.setTransientValue`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.FieldBase.html#setTransientValue) +[`Field.setTransientValue`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.BareField.html#setTransientValue) can be called multiple times, but only the most recent update is propagated to the parent field after the `propagate` call. @@ -308,12 +308,12 @@ planetsField.at(1).value; updates field values. - When the child field is accessed via - [`Field.at`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.FieldBase.html#at) method for the + [`Field.at`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.BareField.html#at) method for the first time, its value is read from the value of the parent field using the [`ValueAccessor.get`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.Accessor.html#get) method. - When a field value is updated via - [`Field.setValue`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.FieldBase.html#setValue), then + [`Field.setValue`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.BareField.html#setValue), then the parent field value is updated with the value returned from the [`ValueAccessor.set`](https://smikhalevski.github.io/roqueform/interfaces/roqueform.Accessor.html#set) method. If the updated field has child fields, their values are updated with values returned from the diff --git a/packages/doubter-plugin/src/main/doubterPlugin.ts b/packages/doubter-plugin/src/main/doubterPlugin.ts index 3ea288c..357f81e 100644 --- a/packages/doubter-plugin/src/main/doubterPlugin.ts +++ b/packages/doubter-plugin/src/main/doubterPlugin.ts @@ -13,7 +13,7 @@ import { export interface DoubterShapePlugin { /** - * The shape that Doubter uses to validate {@link FieldBase.value the field value}, or `null` if there's no + * The shape that Doubter uses to validate {@link BareField.value the field value}, or `null` if there's no * shape for this field. */ valueShape: Shape | null; diff --git a/packages/reset-plugin/src/main/resetPlugin.ts b/packages/reset-plugin/src/main/resetPlugin.ts index 30701dd..eb19ba8 100644 --- a/packages/reset-plugin/src/main/resetPlugin.ts +++ b/packages/reset-plugin/src/main/resetPlugin.ts @@ -1,3 +1,4 @@ +import isDeepEqual from 'fast-deep-equal'; import { dispatchEvents, Event, @@ -9,7 +10,6 @@ import { Unsubscribe, ValueOf, } from 'roqueform'; -import isDeepEqual from 'fast-deep-equal'; /** * The plugin added to fields by the {@link resetPlugin}. @@ -33,15 +33,15 @@ export interface ResetPlugin { reset(): void; /** - * Returns all fields that have {@link roqueform!FieldBase.value a value} that is different from - * {@link roqueform!FieldBase.initialValue an initial value}. + * Returns all fields that have {@link roqueform!BareField.value a value} that is different from + * {@link roqueform!BareField.initialValue an initial value}. * * @see {@link isDirty} */ getDirtyFields(): Field>[]; /** - * Subscribes to changes of {@link roqueform!FieldBase.initialValue the initial value}. + * Subscribes to changes of {@link roqueform!BareField.initialValue the initial value}. * * @param eventType The type of the event. * @param subscriber The subscriber that would be triggered. diff --git a/packages/roqueform/src/main/index.ts b/packages/roqueform/src/main/index.ts index 1ac0205..383b598 100644 --- a/packages/roqueform/src/main/index.ts +++ b/packages/roqueform/src/main/index.ts @@ -16,13 +16,13 @@ export { validationPlugin } from './validationPlugin'; export type { ClearErrorsOptions, ErrorsPlugin } from './errorsPlugin'; export type { Validator, Validation, ValidationPlugin } from './validationPlugin'; export type { - Field, + BareField, Event, + Field, + PluginInjector, + PluginOf, Subscriber, Unsubscribe, - PluginOf, - ValueOf, - FieldBase, - PluginInjector, ValueAccessor, + ValueOf, } from './types'; diff --git a/packages/roqueform/src/main/types.ts b/packages/roqueform/src/main/types.ts index b05f19f..3d156fd 100644 --- a/packages/roqueform/src/main/types.ts +++ b/packages/roqueform/src/main/types.ts @@ -5,15 +5,15 @@ * @template Value The field value. * @template Plugin The plugin injected into the field. */ -export type Field = FieldBase> & PreferUnknown; +export type Field = BareField> & PreferUnknown; /** - * The field controller provides the core field functionality. + * The bare field provides the core field functionality. * * @template Value The field value. * @template Plugin The plugin injected into the field. */ -export interface FieldBase { +export interface BareField { /** * Holds the plugin type for inference. * @@ -175,8 +175,7 @@ export type Unsubscribe = () => void; /** * Infers plugins that were injected into a field * - * Use `PluginOf` in plugin interfaces to infer all plugin interfaces that were intersected with the field - * controller. + * Use `PluginOf` in plugin interfaces to infer all plugin interfaces that were intersected with the bare field. * * @template T The field to infer plugin of. */ diff --git a/packages/roqueform/src/main/utils.ts b/packages/roqueform/src/main/utils.ts index 42a0711..51b980c 100644 --- a/packages/roqueform/src/main/utils.ts +++ b/packages/roqueform/src/main/utils.ts @@ -1,4 +1,4 @@ -import type { Event, FieldBase } from './types'; +import type { BareField, Event } from './types'; /** * [SameValueZero](https://262.ecma-international.org/7.0/#sec-samevaluezero) comparison operation. @@ -46,7 +46,7 @@ export function dispatchEvents(events: readonly Event[]): void { continue; } - for (let ancestor: FieldBase | null = event.targetField; ancestor !== null; ancestor = ancestor.parentField) { + for (let ancestor: BareField | null = event.targetField; ancestor !== null; ancestor = ancestor.parentField) { const subscribers1 = ancestor.subscribers[event.type]; const subscribers2 = ancestor.subscribers['*']; diff --git a/packages/zod-plugin/src/main/zodPlugin.ts b/packages/zod-plugin/src/main/zodPlugin.ts index 090112c..dc205eb 100644 --- a/packages/zod-plugin/src/main/zodPlugin.ts +++ b/packages/zod-plugin/src/main/zodPlugin.ts @@ -1,9 +1,9 @@ import { + BareField, composePlugins, errorsPlugin, ErrorsPlugin, Field, - FieldBase, PluginInjector, Validation, validationPlugin, @@ -99,7 +99,7 @@ function getValue(field: Field): unknown { return value; } -function getPath(field: FieldBase): any[] { +function getPath(field: BareField): any[] { const path = []; while (field.parentField !== null) {