@xyo-network/react-form-group 2.81.2

package/src/control/accessor/ControlValueAccessorBase.ts

@@ -0,0 +1,187 @@
+import { forget } from '@xylabs/forget'
+import { BaseParams } from '@xylabs/object'
+import { BaseEmitter } from '@xyo-network/module-abstract'
+
+import { ControlSerializeSettings, ControlValueAccessor, SetOptions } from './ControlValueAccessor.js'
+import { ValidControlValue } from './ValidControlValue.js'
+
+export type ControlValueAccessorBaseConfig = {
+  disableEvents?: boolean
+}
+
+export const DefaultSetOptions: SetOptions = { disableEmit: false }
+
+export type ControlValueAccessorBaseEvents<TValue = ValidControlValue> = {
+  errorChanged: { error: string }
+  touchChanged: { touched: boolean }
+  valueChanged: { value: TValue }
+}
+
+/**
+ * The base class for control value accessors interface
+ */
+export class ControlValueAccessorBase<
+    TValue = ValidControlValue,
+    TEventData extends ControlValueAccessorBaseEvents<TValue> = ControlValueAccessorBaseEvents<TValue>,
+  >
+  extends BaseEmitter<BaseParams, TEventData>
+  implements ControlValueAccessor<TValue>
+{
+  private _error: string = ''
+
+  private _previousValue = undefined as TValue
+
+  private _serializeSettings: ControlSerializeSettings = { sensitive: false, serializable: false }
+
+  private _touched: boolean = false
+
+  private _value = undefined as TValue
+
+  constructor(private config: ControlValueAccessorBaseConfig) {
+    super({})
+  }
+
+  /**
+   * The error message for the control.
+   */
+  get error() {
+    return this._error
+  }
+
+  /**
+   * The "previous value" of the input element.
+   */
+  get previousValue() {
+    return this._previousValue
+  }
+
+  /**
+   * The serialize settings of the input element.
+   */
+  get serializeSettings() {
+    return this._serializeSettings
+  }
+
+  /**
+   * The "touched" state of the input element.
+   */
+  get touched() {
+    return this._touched
+  }
+
+  /**
+   * The current value of the input element.
+   */
+  get value() {
+    return this._value
+  }
+
+  /**
+   * The registered callback function called when a change or input event occurs on the input
+   * element.
+   */
+  onChange = (_: TValue) => {}
+
+  /**
+   * Registers a function called when the control error changes.
+   */
+  onErrorChange: (error: string) => void = () => {}
+
+  /**
+   * The registered callback function called when a blur event occurs on the input element.
+   */
+  onTouched = (_isTouched: boolean) => {}
+
+  /**
+   * Registers a function called when the control value changes.
+   * @param  {(_value:ValidControlValue)=>void} fn
+   * @returns void
+   */
+  registerOnChange(fn: (_value: TValue) => void): void {
+    this.onChange = fn
+  }
+
+  /**
+   * Registers a function called when the control error changes.
+   * @param  {(error:string)=>void} fn
+   */
+  registerOnErrorChange(fn: (error: string) => void) {
+    this.onErrorChange = fn
+  }
+
+  /**
+   * Registers a function called when the control is touched.
+   * @param  {(isTouched:boolean)=>void} fn
+   * @returns void
+   */
+  registerOnTouched(fn: (isTouched: boolean) => void): void {
+    this.onTouched = fn
+  }
+
+  /**
+   * Sets the "touched" state of the input element.
+   * @param  {boolean} isTouched
+   */
+  setTouched(isTouched: boolean) {
+    if (this.touched !== isTouched) {
+      this._touched = isTouched
+      this.onTouched(isTouched)
+
+      if (this.config.disableEvents) return
+      const emit = async () => await this.emit('touchChanged', { touched: isTouched })
+      forget(emit())
+    }
+  }
+
+  /**
+   * Sets the "value" property on the input element.
+   * @param  {ValidControlValue} value
+   * @returns void
+   */
+  setValue(value: TValue, options = DefaultSetOptions): void {
+    this._previousValue = this._value
+
+    const normalizedValue = value == null ? ('' as TValue) : value
+
+    if (this.value !== normalizedValue) {
+      this._value = normalizedValue
+      this.onChange(normalizedValue)
+
+      if (this.config.disableEvents || options.disableEmit) return
+      const emit = async () => await this.emit('valueChanged', { value: normalizedValue })
+      forget(emit())
+    }
+  }
+
+  /**
+   * Set the error message for the control.
+   * @param  {string} error
+   */
+  protected setError(error: string) {
+    if (this.error !== error) {
+      this._error = error
+      this.onErrorChange(error)
+
+      if (this.config.disableEvents) return
+      const emit = async () => await this.emit('errorChanged', { error })
+      forget(emit())
+    }
+  }
+
+  /**
+   * Sets the "previous value" of the input element.
+   * @param  {ValidControlValue} value
+   * @returns void
+   */
+  protected setPreviousValue(value: TValue): void {
+    this._previousValue = value
+  }
+
+  /**
+   * Sets the serialize settings  of the input element.
+   * @param  {ControlSerializeSettings} settings
+   */
+  protected setSerializeSettings(settings: ControlSerializeSettings) {
+    this._serializeSettings = settings
+  }
+}

package/src/control/accessor/FormControlStatus.ts

@@ -0,0 +1,36 @@
+/**
+ * Reports that a control is valid, meaning that no errors exist in the input value.
+ */
+export const VALID = 'VALID' as const
+
+/**
+ * Reports that a control is invalid, meaning that an error exists in the input value.
+ */
+export const INVALID = 'INVALID' as const
+
+/**
+ * Reports that a control is pending, meaning that async validation is occurring and
+ * errors are not yet available for the input value.
+ */
+export const PENDING = 'PENDING' as const
+
+/**
+ * Reports that a control is disabled, meaning that the control is exempt from ancestor
+ * calculations of validity or value.
+ */
+export const DISABLED = 'DISABLED' as const
+
+/**
+ * A control can have several different statuses. Each
+ * possible status is returned as a string literal.
+ *
+ * * **VALID**: Reports that a control is valid, meaning that no errors exist in the input
+ * value.
+ * * **INVALID**: Reports that a control is invalid, meaning that an error exists in the input
+ * value.
+ * * **PENDING**: Reports that a control is pending, meaning that async validation is
+ * occurring and errors are not yet available for the input value.
+ * * **DISABLED**: Reports that a control is
+ * disabled, meaning that the control is exempt from ancestor calculations of validity or value.
+ */
+export type FormControlStatus = typeof VALID | typeof INVALID | typeof PENDING | typeof DISABLED

package/src/control/accessor/ValidControlValue.ts

@@ -0,0 +1 @@
+export type ValidControlValue = string | undefined

package/src/control/accessor/index.ts

@@ -0,0 +1,4 @@
+export * from './ControlValueAccessor.js'
+export * from './ControlValueAccessorBase.js'
+export * from './FormControlStatus.js'
+export * from './ValidControlValue.js'

package/src/control/index.ts

@@ -0,0 +1,4 @@
+export * from './AbstractControl.js'
+export * from './accessor/index.js'
+export * from './FormControl.js'
+export * from './FormControlBase.js'

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './context/index.js'
+export * from './control/index.js'
+export * from './FormGroup.js'
+export * from './InputError.js'
+export * from './storage/index.js'

package/src/storage/ArchivistFormGroupStorage.ts

@@ -0,0 +1,21 @@
+import { ArchivistInstance } from '@xyo-network/archivist-model'
+import { Payload } from '@xyo-network/payload-model'
+
+import { FormGroupStorage } from './FormGroupStorage.js'
+
+export class ArchivistFormGroupStorage implements FormGroupStorage {
+  constructor(private archivist: ArchivistInstance) {}
+
+  async clear() {
+    await this.archivist.clear?.()
+  }
+
+  async get() {
+    const all = await this.archivist.all?.()
+    return all.at(-1)
+  }
+
+  async insert(value: Payload) {
+    await this.archivist.insert?.([value])
+  }
+}

package/src/storage/FormGroupStorage.ts

@@ -0,0 +1,8 @@
+import { Promisable } from '@xylabs/promise'
+import { Payload } from '@xyo-network/payload-model'
+
+export interface FormGroupStorage<TValue extends Payload = Payload> {
+  clear: () => Promisable<void>
+  get: () => Promisable<TValue | undefined>
+  insert: (state: TValue) => Promisable<void>
+}

package/src/storage/index.ts

@@ -0,0 +1,2 @@
+export * from './ArchivistFormGroupStorage.js'
+export * from './FormGroupStorage.js'

package/src/stories/test.stories.tsx

@@ -0,0 +1,20 @@
+/**
+ * More to come...
+ */
+
+import { Meta, StoryFn } from '@storybook/react'
+import React from 'react'
+
+// eslint-disable-next-line import/no-default-export
+export default {
+  title: 'modules/form/test',
+} as Meta
+
+const Template: StoryFn<React.FC> = (args) => {
+  return <div {...args}></div>
+}
+
+const Default = Template.bind({})
+Default.args = {}
+
+export { Default }

package/src/types/images.d.ts

@@ -0,0 +1,5 @@
+declare module '*.png'
+declare module '*.jpg'
+declare module '*.svg'
+declare module '*.gif'
+declare module '*.webp'

package/typedoc.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["src/index.ts"],
+  "tsconfig": "./tsconfig.typedoc.json"
+}