@xyo-network/react-form-group 2.81.2

package/dist/node/storage/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAA;AAC9C,cAAc,uBAAuB,CAAA"}

package/dist/node/storage/index.d.mts

@@ -0,0 +1,3 @@
+export * from './ArchivistFormGroupStorage.js';
+export * from './FormGroupStorage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/node/storage/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAA;AAC9C,cAAc,uBAAuB,CAAA"}

package/dist/node/storage/index.d.ts

@@ -0,0 +1,3 @@
+export * from './ArchivistFormGroupStorage.js';
+export * from './FormGroupStorage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/node/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAA;AAC9C,cAAc,uBAAuB,CAAA"}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@xyo-network/react-form-group",
+  "author": {
+    "email": "support@xyo.network",
+    "name": "XYO Development Team",
+    "url": "https://xyo.network"
+  },
+  "bugs": {
+    "email": "support@xyo.network",
+    "url": "https://github.com/XYOracleNetwork/sdk-xyo-react-js/issues"
+  },
+  "dependencies": {
+    "@mui/icons-material": "^5.16.1",
+    "@xylabs/forget": "^3.5.9",
+    "@xylabs/object": "^3.5.9",
+    "@xylabs/promise": "^3.5.9",
+    "@xyo-network/archivist-model": "^2.110.5",
+    "@xyo-network/module-abstract": "^2.110.5",
+    "@xyo-network/module-events": "^2.110.5",
+    "@xyo-network/payload-model": "^2.110.5",
+    "@xyo-network/react-shared": "^2.81.2"
+  },
+  "peerDependencies": {
+    "@mui/material": "^5",
+    "@mui/styles": "^5",
+    "react": "^18",
+    "react-dom": "^18"
+  },
+  "devDependencies": {
+    "@storybook/react": "^7.6.20",
+    "@xylabs/ts-scripts-yarn3": "^3.12.1",
+    "@xylabs/tsconfig-react": "^3.12.1",
+    "typescript": "^5.5.3"
+  },
+  "description": "Common React library for all XYO projects that use React",
+  "docs": "dist/docs.json",
+  "exports": {
+    ".": {
+      "node": {
+        "import": {
+          "types": "./dist/node/index.d.mts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      },
+      "browser": {
+        "import": {
+          "types": "./dist/browser/index.d.mts",
+          "default": "./dist/browser/index.js"
+        },
+        "require": {
+          "types": "./dist/browser/index.d.cts",
+          "default": "./dist/browser/index.cjs"
+        }
+      },
+      "default": "./dist/browser/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/browser/index.cjs",
+  "module": "dist/browser/index.js",
+  "homepage": "https://xyo.network",
+  "keywords": [
+    "xyo",
+    "utility",
+    "typescript",
+    "react"
+  ],
+  "license": "LGPL-3.0-only",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/XYOracleNetwork/sdk-xyo-react-js.git"
+  },
+  "scripts": {
+    "lint-pkg": "npmPkgJsonLint .",
+    "license": "yarn license-checker --exclude \"MIT, ISC, Apache-2.0, BSD, BSD-2-Clause, CC-BY-4.0, Unlicense, CC-BY-3.0, CC0-1.0\""
+  },
+  "sideEffects": false,
+  "types": "dist/browser/index.d.ts",
+  "version": "2.81.2",
+  "type": "module"
+}

package/src/FormGroup.ts

@@ -0,0 +1,226 @@
+import { forget } from '@xylabs/forget'
+import { EventListener } from '@xyo-network/module-events'
+import { Payload } from '@xyo-network/payload-model'
+
+import { AbstractControl, ControlValueAccessorBaseEvents } from './control/index.js'
+import { ErrorSummary } from './InputError.js'
+import { FormGroupStorage } from './storage/index.js'
+
+export type PayloadWithTimestamp = Payload<{ timestamp?: number }>
+
+export type KeyOfString<T> = keyof T extends string ? keyof T : never
+
+type FormGroupErrors<TValue> = Record<KeyOfString<TValue>, string>
+
+export type FormGroupParams<TStorageValue extends Payload = Payload> = {
+  serialize?: boolean
+  storage?: {
+    sensitive?: FormGroupStorage<TStorageValue>
+    storage?: FormGroupStorage<TStorageValue>
+  }
+  ttlStorage?: number
+}
+
+type ValueChangeEventListener = EventListener<ControlValueAccessorBaseEvents['valueChanged']>
+
+/**
+ * Organize form controls in a group.
+ *
+ * NOTE: This is a work in progress and only supports top level controls.  Nested controls are not supported.
+ */
+export class FormGroup<
+  TValue extends PayloadWithTimestamp = PayloadWithTimestamp,
+  TStorageValue extends PayloadWithTimestamp = PayloadWithTimestamp,
+> extends AbstractControl {
+  private _controls = {} as Record<KeyOfString<TValue>, AbstractControl>
+
+  private serializeListeners: Record<string, ValueChangeEventListener> = {}
+
+  private serializedSensitiveState = {} as Record<KeyOfString<TStorageValue>, string>
+  private serializedState = {} as Record<KeyOfString<TStorageValue>, string>
+
+  constructor(private fgParams?: FormGroupParams<TStorageValue>) {
+    super()
+  }
+
+  get errorSummary() {
+    const errorSummary: ErrorSummary = {
+      errorMessage: '',
+      invalidFields: [],
+    }
+    for (const [key, value] of Object.entries(this.errors)) {
+      if (value) {
+        errorSummary.errorMessage = `${errorSummary.errorMessage}, ${value}`
+        errorSummary.invalidFields.push(key)
+      }
+    }
+
+    return errorSummary
+  }
+
+  get errors(): FormGroupErrors<TValue> {
+    const value = {} as FormGroupErrors<TValue>
+    for (const key in this._controls) {
+      const castKey = key as KeyOfString<TValue>
+      value[castKey] = this._controls[castKey].error
+    }
+    return value
+  }
+
+  get nonSensitiveStorage() {
+    return this.fgParams?.storage?.storage
+  }
+
+  get sensitiveStorage() {
+    return this.fgParams?.storage?.sensitive
+  }
+
+  override get touched() {
+    return Object.values<AbstractControl>(this._controls).some((control) => control.touched)
+  }
+
+  override get valid() {
+    return Object.values<AbstractControl>(this._controls).every((control) => control.valid)
+  }
+
+  get values(): TValue {
+    const value = {} as TValue
+    for (const key in this._controls) {
+      const castKey = key as KeyOfString<TValue>
+      value[castKey] = this._controls[castKey].rawValue as TValue[KeyOfString<TValue>]
+    }
+    return value
+  }
+
+  getControl(name: string) {
+    return this._controls[name as KeyOfString<TValue>]
+  }
+
+  async getSerializedValue(name: string, sensitive = false): Promise<string | undefined> {
+    const storage = sensitive ? this.sensitiveStorage : this.nonSensitiveStorage
+    if (storage) {
+      if (!storage) {
+        console.warn(`Cannot return value for ${name}. No storage set`)
+        return
+      }
+
+      const savedState = await storage.get()
+      if (savedState && name in savedState) {
+        const savedValue = savedState[name as keyof typeof savedState] as string
+
+        // casting to PayloadWithTimestamp to check for timestamp
+        const savedStateWithTimestamp = savedState as unknown as PayloadWithTimestamp
+        if (savedStateWithTimestamp.timestamp && this.fgParams?.ttlStorage) {
+          const expirationDate = savedStateWithTimestamp.timestamp + (this.fgParams?.ttlStorage ?? 0)
+          const now = Date.now()
+          return now > expirationDate ? undefined : savedValue
+        }
+        return savedValue
+      }
+    }
+  }
+
+  registerControl(name: string, control: AbstractControl) {
+    if (this._controls[name as KeyOfString<TValue>]) console.error(`Replacing Control with name ${name} since it already exists!`)
+    this._controls[name as KeyOfString<TValue>] = control
+    this.serializeControlValue(name, control)
+  }
+
+  resetControls() {
+    for (const key in this._controls) {
+      this.unregisterControl(key)
+    }
+  }
+
+  resetValues() {
+    for (const control of Object.values<AbstractControl>(this._controls)) {
+      control.setValue('')
+    }
+  }
+
+  unregisterControl(name: string) {
+    const control = this._controls[name as KeyOfString<TValue>]
+
+    if (control) {
+      const listener = this.serializeListeners[name]
+      control.off('valueChanged', listener)
+      delete this.serializeListeners[name]
+      delete this._controls[name as KeyOfString<TValue>]
+    }
+  }
+
+  validateFields(requiredFields?: string[] | undefined) {
+    const castRequiredFields = requiredFields as KeyOfString<TValue>[]
+    for (const key in this._controls) {
+      const castKey = key as KeyOfString<TValue>
+      if (castRequiredFields === undefined || castRequiredFields.includes(castKey)) {
+        const control = this._controls[castKey]
+        control.validate()
+      }
+    }
+  }
+
+  private serializeControlValue(name: string, control: AbstractControl) {
+    const shouldSerialize = this.fgParams?.serialize
+    const sensitiveStorage = this.sensitiveStorage
+    const storage = this.nonSensitiveStorage
+
+    if (!shouldSerialize && (storage || sensitiveStorage)) console.warn('storage medium set but serialize is not enabled')
+
+    if (shouldSerialize && control.serializeSettings.serializable) {
+      this.setStateValueFromStorage(name, control)
+
+      const listener: ValueChangeEventListener = ({ value }) => {
+        // detect if control wants to be serialized
+        if (control.serializeSettings.serializable) {
+          // detect control's preferred storage
+          const targetStorage = control.serializeSettings.sensitive ? sensitiveStorage : storage
+
+          // detect control's preferred state
+          const targetState = control.serializeSettings.sensitive ? this.serializedSensitiveState : this.serializedState
+
+          // set the value
+          targetState[name as KeyOfString<TStorageValue>] = value ?? ''
+
+          // add a timestamp
+          const payloadWithTimestamp = targetState as PayloadWithTimestamp
+          payloadWithTimestamp.timestamp = Date.now()
+
+          // serialize the value
+          this.serializeValues(targetStorage, targetState as TStorageValue)
+        }
+      }
+
+      // listen for value changes
+      control.on('valueChanged', listener)
+
+      // store the listener for later removal
+      this.serializeListeners[name] = listener
+    }
+  }
+
+  private serializeValues(storage?: FormGroupStorage<TStorageValue>, values?: TStorageValue) {
+    if (storage && values) {
+      const write = async () => await storage.insert(values)
+      const clear = async () => await storage.clear()
+
+      forget(clear())
+      forget(write())
+    }
+  }
+
+  private setStateValueFromStorage(name: string, control: AbstractControl) {
+    const read = async () => {
+      const savedValue = await this.getSerializedValue(name, control.serializeSettings.sensitive)
+
+      if (savedValue) {
+        const targetState = control.serializeSettings.sensitive ? this.serializedSensitiveState : this.serializedState
+        targetState[name as KeyOfString<TStorageValue>] = savedValue
+
+        control.setValue(savedValue, { disableEmit: true })
+      }
+    }
+
+    forget(read())
+  }
+}

package/src/InputError.ts

@@ -0,0 +1,4 @@
+export type ErrorSummary = {
+  errorMessage: string
+  invalidFields: string[]
+}

package/src/context/Context.ts

@@ -0,0 +1,5 @@
+import { createContextEx } from '@xyo-network/react-shared'
+
+import { FormGroupContextWithPayloadState } from './State.js'
+
+export const FormGroupBaseContext = createContextEx<FormGroupContextWithPayloadState>()

package/src/context/Provider.tsx

@@ -0,0 +1,25 @@
+import { Payload } from '@xyo-network/payload-model'
+import { PropsWithChildren, useMemo } from 'react'
+
+import { FormGroup, FormGroupParams } from '../FormGroup.js'
+import { FormGroupBaseContext } from './Context.js'
+
+export interface FormGroupPayloadProviderProps<TStorage extends Payload = Payload> extends PropsWithChildren {
+  params?: FormGroupParams<TStorage>
+}
+
+/**
+ * Provides a FormGroup to child components.
+ */
+export const FormGroupPayloadProvider = ({ children, params, ...props }: FormGroupPayloadProviderProps) => {
+  const formGroup = useMemo(() => {
+    const formGroup = new FormGroup<Payload, Payload>(params)
+    return formGroup
+  }, [params])
+
+  return (
+    <FormGroupBaseContext.Provider value={{ formGroup, provided: true }} {...props}>
+      {children}
+    </FormGroupBaseContext.Provider>
+  )
+}

package/src/context/State.ts

@@ -0,0 +1,8 @@
+import { Payload } from '@xyo-network/payload-model'
+import { ContextExState } from '@xyo-network/react-shared'
+
+import { FormGroup } from '../FormGroup.js'
+
+export interface FormGroupContextWithPayloadState<TValue extends Payload = Payload, TStorageValue extends Payload = Payload> extends ContextExState {
+  formGroup?: FormGroup<TValue, TStorageValue>
+}

package/src/context/index.ts

@@ -0,0 +1,4 @@
+export * from './Context.js'
+export * from './Provider.js'
+export * from './State.js'
+export * from './use.js'

package/src/context/use.tsx

@@ -0,0 +1,5 @@
+import { useContextEx } from '@xyo-network/react-shared'
+
+import { FormGroupBaseContext } from './Context.js'
+
+export const useFormGroup = (required = false) => useContextEx(FormGroupBaseContext, 'FormGroup', required)

package/src/control/AbstractControl.ts

@@ -0,0 +1,125 @@
+import { forget } from '@xylabs/forget'
+
+import {
+  ControlValueAccessorBase,
+  ControlValueAccessorBaseEvents,
+  DISABLED,
+  FormControlStatus,
+  INVALID,
+  PENDING,
+  VALID,
+  ValidControlValue,
+} from './accessor/index.js'
+
+export type AbstractControlEvents<TValue> = ControlValueAccessorBaseEvents<TValue> & {
+  statusChanged: { status: FormControlStatus }
+}
+
+/**
+ * This is the base class for `Control` classes (i.e. FormControl),
+ *
+ * It provides some of the shared behavior that all controls and groups of controls have, like
+ * running validators, calculating status, and resetting state. It also defines the properties
+ * that are shared between all sub-classes, like `value`, `valid`, and `dirty`. It shouldn't be
+ * instantiated directly.
+ *
+ * NOTE: Heavily borrowed from Angular's AbstractControl:
+ * https://github.com/angular/angular/blob/5dcdbfcba934a930468aec140a7183b034466bdf/packages/forms/src/model/abstract_model.ts
+ */
+export class AbstractControl<TValue extends ValidControlValue = ValidControlValue> extends ControlValueAccessorBase<
+  TValue,
+  AbstractControlEvents<TValue>
+> {
+  private _status: FormControlStatus | undefined = undefined
+
+  constructor() {
+    super({})
+  }
+
+  /**
+   * A control is `disabled` when its `status` is `DISABLED`.
+   *
+   * Disabled controls are exempt from validation checks and
+   * are not included in the aggregate value of their ancestor
+   * controls.
+   *
+   * @returns True if the control is disabled, false otherwise.
+   */
+  /** @deprecated - disabled functionality not implemented */
+  get disabled(): boolean {
+    return this.status === DISABLED
+  }
+
+  /**
+   * A control is `enabled` as long as its `status` is not `DISABLED`.
+   *
+   * @returns True if the control has any status other than 'DISABLED',
+   * false if the status is 'DISABLED'.
+   */
+  get enabled(): boolean {
+    return this.status !== DISABLED
+  }
+
+  /**
+   * A control is `invalid` when its `status` is `INVALID`.
+   
+   *
+   * @returns True if this control has failed one or more of its validation checks,
+   * false otherwise.
+   */
+  get invalid(): boolean {
+    return this.status === INVALID
+  }
+
+  /**
+   * A control is `pending` when its `status` is `PENDING`.
+   *
+   * @returns True if this control is in the process of conducting a validation check,
+   * false otherwise.
+   */
+  get pending(): boolean {
+    return this.status == PENDING
+  }
+
+  /**
+   * The raw value of the control.
+   */
+  get rawValue(): TValue {
+    return this.value
+  }
+
+  /**
+   * The current status of the control.
+   */
+  get status() {
+    return this._status
+  }
+
+  /**
+   * A control is `valid` when its `status` is `VALID`.
+   *
+   * @returns True if the control has passed all of its validation tests,
+   * false otherwise.
+   */
+  get valid(): boolean {
+    return this.status === VALID
+  }
+
+  setErrorAndValidity(error: string, status: FormControlStatus) {
+    this.setError(error)
+    this.setStatus(status)
+  }
+
+  setStatus(status: FormControlStatus) {
+    if (this._status === status) return
+
+    this._status = status
+
+    const emit = async () => await this.emit('statusChanged', { status })
+    forget(emit())
+  }
+
+  validate(): boolean {
+    return true
+  }
+}

package/src/control/FormControl.ts

@@ -0,0 +1,31 @@
+import { EmptyObject } from '@xylabs/object'
+
+import { AbstractControl } from './AbstractControl.js'
+
+export type CursorPosition = {
+  current: number | undefined
+  previous: number | undefined
+}
+
+export interface FormControlValidator {
+  blurError?: (value: string) => void
+  changeError?: (value: string) => void
+  // filter that supports an empty value
+  pattern?: RegExp
+  // filter that does not support an empty value
+  patternStrict?: RegExp
+  required?: boolean
+}
+
+export interface FormControlMask {
+  cursorPosition: CursorPosition
+  getCursorPosition?: () => number | undefined
+  mask?: (value: string) => string
+  onCursorChange?: (cursor: number | undefined) => void
+  unmask?: (value: string) => string
+}
+
+export interface FormControl<TProps extends EmptyObject = EmptyObject> extends FormControlValidator, FormControlMask, AbstractControl {
+  readonly name?: string
+  props: TProps
+}

package/src/control/FormControlBase.ts

@@ -0,0 +1,82 @@
+import { EmptyObject } from '@xylabs/object'
+
+import { AbstractControl } from './AbstractControl.js'
+import { SetOptions } from './accessor/index.js'
+import { CursorPosition, FormControl } from './FormControl.js'
+
+const AllowAllRegex = /^.*$/s
+
+/**
+ * A base class for form controls and their validation.
+ */
+export abstract class FormControlBase<TProps extends EmptyObject = EmptyObject> extends AbstractControl implements FormControl {
+  /**
+   * The current and previous cursor position of the input element.
+   */
+  cursorPosition: CursorPosition = { current: undefined, previous: undefined }
+  invalidMessage = 'Invalid input'
+  pattern = AllowAllRegex
+  patternStrict = AllowAllRegex
+  props = {} as TProps
+  required = false
+
+  private _name: string | undefined = undefined
+
+  constructor() {
+    super()
+  }
+
+  get name() {
+    return this._name
+  }
+
+  override get rawValue() {
+    return this.unmask && this.value ? this.unmask(this.value) : this.value
+  }
+
+  blurError?(value: string): void | undefined
+  changeError?(value: string): void
+  getCursorPosition?(): number | undefined
+  mask?(value: string): string
+  onCursorChange: (cursor: number | undefined) => void = () => {}
+
+  override setValue(value: string = '', setOptions: SetOptions) {
+    // check for pattern validation
+    if (this.unmask && this.pattern) {
+      const unmasked = this.unmask(value)
+      const match = unmasked.match(this.pattern)
+      // set the new value before checking for errors
+      super.setValue(this.mask ? this.mask(unmasked) : unmasked, setOptions)
+      if (match) {
+        // if the value matches the pattern, update the cursor position
+        if (this.getCursorPosition) {
+          const newCursor = this.getCursorPosition()
+          this.onCursorChange(newCursor)
+        }
+      } else {
+        // if no match, set the error and return to the previous value
+        this.setValue(this.previousValue, setOptions)
+        this.onCursorChange?.(this.cursorPosition.previous)
+      }
+    } else {
+      // if no mask or pattern, just set the value
+      super.setValue(value, setOptions)
+    }
+    // check for changeError validation after pattern validation
+    this.changeError?.(value)
+  }
+
+  unmask?(value: string): string
+
+  // For FormControls, validate is the same as running one of the error checking functions
+  override validate(): boolean {
+    const normalizedValue = this.value ?? ''
+    // prefer the blurError function since validation assumes the user is done typing
+    this.blurError ? this.blurError(normalizedValue) : this.changeError?.(normalizedValue)
+    return !this.error
+  }
+
+  protected setName(name: string | undefined) {
+    this._name = name
+  }
+}

package/src/control/accessor/ControlValueAccessor.ts

@@ -0,0 +1,23 @@
+import { ValidControlValue } from './ValidControlValue.js'
+
+export interface SetOptions {
+  disableEmit?: boolean
+}
+
+export interface ControlSerializeSettings {
+  sensitive?: boolean
+  serializable?: boolean
+}
+
+export interface ControlValueAccessor<T = ValidControlValue> {
+  readonly error: string
+  readonly previousValue: T
+  readonly serializeSettings: ControlSerializeSettings
+  readonly touched: boolean
+  readonly value: T
+  registerOnChange(fn: (value: T) => void): void
+  registerOnErrorChange(fn: (error: string) => void): void
+  registerOnTouched(fn: (isTouched: boolean) => void): void
+  setTouched(isTouched: boolean): void
+  setValue(fieldValue: T, options?: SetOptions): void
+}