feat: initial values & getters for field/editor API (#1444)

# Initial values

When passing a callback to the following methods at the very start of the app, it was called with `undefined` instead of its initial value
- `sdk.field.onIsDisabledChanged`
- `sdk.field.onSchemaErrorsChanged`
- `sdk.editor.onLocaleSettingsChanged`
- `sdk.editor.onShowDisabledFieldsChanged`

This is now fixed and the callback is immediately invoked with the correct value.

# Getters

The following methods are added
- `sdk.field.getIsDisabled()`
- `sdk.field.getSchemaErrors()`
- `sdk.editor.getLocaleSettings()`
- `sdk.editor.getShowHiddenFields()`

# Deprecation

`sdk.editor.onShowDisabledFieldsChanged` is now deprecated and replaced by `sdk.editor.onShowHiddenFieldsChanged`

Author: andipaetzold

lib/api.ts

@@ -99,9 +99,9 @@ function makeWindowAPI(channel: Channel, _data: any, currentGlobal: typeof globa
 }
 
 function makeEditorAPI(channel: Channel, data: any) {
-  const { editorInterface } = data
+  const { editorInterface, editor } = data
   return {
-    editor: createEditor(channel, editorInterface),
+    editor: createEditor(channel, editorInterface, editor),
   }
 }
 

lib/channel.ts

@@ -56,7 +56,7 @@ export class Channel {
 
   addHandler<T extends unknown[]>(method: string, handler: (...args: T) => void) {
     if (!(method in this._messageHandlers)) {
-      this._messageHandlers[method] = new Signal<T>()
+      this._messageHandlers[method] = new Signal()
     }
     return this._messageHandlers[method].attach(handler)
   }

lib/editor.ts

@@ -1,31 +1,43 @@
 import { EditorInterface, EditorLocaleSettings, SharedEditorSDK } from './types'
 import { Channel } from './channel'
 import { MemoizedSignal } from './signal'
+import { ConnectMessage } from './types/api.types'
 
 export default function createEditor(
   channel: Channel,
-  editorInterface: EditorInterface
+  editorInterface: EditorInterface,
+  editorData: Exclude<ConnectMessage['editor'], undefined>
 ): SharedEditorSDK['editor'] {
-  // @ts-expect-error Missing default value
-  const _localeSettingsSygnal = new MemoizedSignal<[EditorLocaleSettings]>([undefined])
-  // @ts-expect-error Missing default value
-  const _showDisabledFieldsSygnal = new MemoizedSignal<[boolean]>([undefined])
+  const localeSettingsSignal = new MemoizedSignal<[EditorLocaleSettings]>(editorData.localeSettings)
+  const showHiddenFieldsSignal = new MemoizedSignal<[boolean]>(editorData.showHiddenFields)
 
   channel.addHandler('localeSettingsChanged', (settings: EditorLocaleSettings) => {
-    _localeSettingsSygnal.dispatch(settings)
+    localeSettingsSignal.dispatch(settings)
   })
 
-  channel.addHandler('showDisabledFieldsChanged', (showDisabledFields: boolean) => {
-    _showDisabledFieldsSygnal.dispatch(showDisabledFields)
+  channel.addHandler('showHiddenFieldsChanged', (showHiddenFields: boolean) => {
+    showHiddenFieldsSignal.dispatch(showHiddenFields)
   })
 
   return {
     editorInterface,
-    onLocaleSettingsChanged: (handler: (localeSettings: EditorLocaleSettings) => void) => {
-      return _localeSettingsSygnal.attach(handler)
+    getLocaleSettings(): EditorLocaleSettings {
+      return localeSettingsSignal.getMemoizedArgs()[0]
     },
-    onShowDisabledFieldsChanged: (handler: (showDisabledFields: boolean) => void) => {
-      return _showDisabledFieldsSygnal.attach(handler)
+    onLocaleSettingsChanged: (handler) => {
+      return localeSettingsSignal.attach(handler)
+    },
+    /**
+     * @deprecated
+     */
+    onShowDisabledFieldsChanged: (handler) => {
+      return showHiddenFieldsSignal.attach(handler)
+    },
+    getShowHiddenFields(): boolean {
+      return showHiddenFieldsSignal.getMemoizedArgs()[0]
+    },
+    onShowHiddenFieldsChanged: (handler) => {
+      return showHiddenFieldsSignal.attach(handler)
     },
   }
 }

lib/entry.ts

@@ -1,6 +1,6 @@
 import { Channel } from './channel'
 import { MemoizedSignal } from './signal'
-import { EntryAPI, EntryFieldInfo, EntrySys, Metadata, TaskAPI } from './types'
+import { EntryAPI, EntryFieldAPI, EntryFieldInfo, EntrySys, Metadata, TaskAPI } from './types'
 
 const taskMethods: Array<keyof TaskAPI> = [
   'getTask',
@@ -14,7 +14,7 @@ export default function createEntry(
   channel: Channel,
   entryData: any,
   fieldInfo: EntryFieldInfo[],
-  createEntryField: Function
+  createEntryField: (info: EntryFieldInfo) => EntryFieldAPI
 ): EntryAPI {
   let sys = entryData.sys
   const sysChanged = new MemoizedSignal<[EntrySys]>(sys)

lib/field-locale.ts

@@ -1,6 +1,6 @@
 import { Channel } from './channel'
 import { MemoizedSignal } from './signal'
-import { FieldAPI, FieldInfo, Items } from './types'
+import { FieldAPI, FieldInfo, Items, SerializedJSONValue } from './types'
 import { ValidationError } from './types/validation-error'
 
 export default class FieldLocale implements FieldAPI {
@@ -15,7 +15,7 @@ export default class FieldLocale implements FieldAPI {
   private _valueSignal: MemoizedSignal<[any]>
   private _isDisabledSignal: MemoizedSignal<[boolean]>
   private _schemaErrorsChangedSignal: MemoizedSignal<[ValidationError[]]>
-  private _channel: any
+  private _channel: Channel
 
   constructor(channel: Channel, info: FieldInfo) {
     this.id = info.id
@@ -27,10 +27,8 @@ export default class FieldLocale implements FieldAPI {
 
     this._value = info.value
     this._valueSignal = new MemoizedSignal(this._value)
-    // @ts-expect-error Missing default value
-    this._isDisabledSignal = new MemoizedSignal<[boolean]>(undefined)
-    // @ts-expect-error Missing default value
-    this._schemaErrorsChangedSignal = new MemoizedSignal<[ValidationError[]]>(undefined)
+    this._isDisabledSignal = new MemoizedSignal<[boolean]>(info.isDisabled)
+    this._schemaErrorsChangedSignal = new MemoizedSignal<[ValidationError[]]>(info.schemaErrors)
     this._channel = channel
 
     channel.addHandler('valueChanged', (id: string, locale: string, value: any) => {
@@ -63,15 +61,20 @@ export default class FieldLocale implements FieldAPI {
     return this._value
   }
 
-  setValue(value: any) {
+  async setValue(value: any) {
     this._value = value
     this._valueSignal.dispatch(value)
-    return this._channel.call('setValue', this.id, this.locale, value)
+    return await this._channel.call<SerializedJSONValue | undefined>(
+      'setValue',
+      this.id,
+      this.locale,
+      value
+    )
   }
 
-  removeValue() {
+  async removeValue() {
     this._value = undefined
-    return this._channel.call('removeValue', this.id, this.locale)
+    await this._channel.call('removeValue', this.id, this.locale)
   }
 
   setInvalid(isInvalid: boolean) {
@@ -82,10 +85,18 @@ export default class FieldLocale implements FieldAPI {
     return this._valueSignal.attach(handler)
   }
 
+  getIsDisabled(): boolean {
+    return this._isDisabledSignal.getMemoizedArgs()[0]
+  }
+
   onIsDisabledChanged(handler: (isDisabled: boolean) => any) {
     return this._isDisabledSignal.attach(handler)
   }
 
+  getSchemaErrors(): ValidationError[] {
+    return this._schemaErrorsChangedSignal.getMemoizedArgs()[0]
+  }
+
   onSchemaErrorsChanged(handler: (errors: ValidationError[]) => void) {
     return this._schemaErrorsChangedSignal.attach(handler)
   }

lib/field.ts

@@ -32,6 +32,8 @@ export default class Field implements EntryFieldAPI {
           items: info.items,
           locale,
           value: info.values[locale],
+          isDisabled: info.isDisabled[locale],
+          schemaErrors: info.schemaErrors[locale],
         })
 
         return { ...acc, [locale]: fieldLocale }
@@ -46,12 +48,12 @@ export default class Field implements EntryFieldAPI {
     return this._getFieldLocale(locale).getValue()
   }
 
-  setValue(value: any, locale?: string) {
-    return this._getFieldLocale(locale).setValue(value)
+  async setValue(value: any, locale?: string) {
+    return await this._getFieldLocale(locale).setValue(value)
   }
 
-  removeValue(locale?: string) {
-    return this.setValue(undefined, locale)
+  async removeValue(locale?: string) {
+    await this.setValue(undefined, locale)
   }
 
   onValueChanged(locale: string | ((value: any) => void), handler?: (value: any) => void) {

lib/signal.ts

@@ -50,4 +50,8 @@ export class MemoizedSignal<T extends unknown[]> extends Signal<T> {
     listener(...this._memoizedArgs)
     return detachListener
   }
+
+  getMemoizedArgs(): T {
+    return this._memoizedArgs
+  }
 }

lib/types/api.types.ts

@@ -125,14 +125,56 @@ export interface EditorLocaleSettings {
 export interface SharedEditorSDK {
   editor: {
     editorInterface: EditorInterface
+
+    /**
+     * Returns the current locale settings
+     *
+     * The locale setting can change. To always work with the latest settings, use `onLocaleSettingsChanged`.
+     */
+    getLocaleSettings(): EditorLocaleSettings
+
+    /**
+     * Subscribes to changes of the editor's locale settings
+     *
+     * @param callback Function that is called every time the locale settings change. Called immidiately with the current setting.
+     * @returns Function to unsubscribe. `callback` won't be called anymore.
+     */
     onLocaleSettingsChanged: (
       callback: (localeSettings: EditorLocaleSettings) => void
     ) => () => void
-    onShowDisabledFieldsChanged: (callback: (showDisabledFields: boolean) => any) => () => void
+
+    /**
+     * Subscribes to changes of whether or not disabled fields are displayed
+     *
+     * @param callback Function that is called every time the setting whether or not disabled fields are displayed changes. Called immediately with the current state.
+     * @returns Function to unsubscribe. `callback` won't be called anymore.
+     * @deprecated Use {@link onShowHiddenFieldsChanged} instead
+     */
+    onShowDisabledFieldsChanged: (callback: (showDisabledFields: boolean) => void) => () => void
+
+    /**
+     * Returns whether or not hidden fields are displayed
+     *
+     * This setting can change. To always work with the latest settings, use `onShowHiddenFieldsChanged`.
+     */
+    getShowHiddenFields(): boolean
+
+    /**
+     * Subscribes to changes of whether or not hidden fields are displayed
+     *
+     * @param callback Function that is called every time the setting whether or not hidden fields are displayed changes. Called immediately with the current state.
+     * @returns Function to unsubscribe. `callback` won't be called anymore.
+     */
+    onShowHiddenFieldsChanged: (callback: (showHiddenFields: boolean) => void) => () => void
   }
-  /** Allows to read and update the value of any field of the current entry and to get the entry's metadata */
+
+  /**
+   * Allows to read and update the value of any field of the current entry and to get the entry's metadata
+   */
   entry: EntryAPI
-  /** Information about the content type of the entry. */
+  /**
+   * Information about the content type of the entry.
+   */
   contentType: ContentTypeAPI
 }
 
@@ -274,6 +316,10 @@ export interface ConnectMessage {
   ids: IdsAPI
   contentType: ContentTypeAPI
   editorInterface?: EditorInterface
+  editor?: {
+    localeSettings: EditorLocaleSettings
+    showHiddenFields: boolean
+  }
   entry: {
     sys: EntrySys
     metadata?: Metadata

lib/types/field-locale.types.ts

@@ -29,12 +29,34 @@ export interface FieldAPI {
    *  the returned function can be called to remove the handler function
    **/
   onValueChanged: (callback: (value: any) => void) => () => void
-  /** Calls the callback when the disabled status of the field changes.
-   *  the returned function can be called to remove the handler function
-   **/
+
+  /**
+   * Returns whether the current field is disabled
+   *
+   * The disabled state can change. To always work with the latest state, use `onIsDisabledChanged`.
+   */
+  getIsDisabled(): boolean
+
+  /**
+   * Subscribes to changes to this field's disabled state
+   *
+   * @param callback Function that is called every time this field's disabled state changes. Called immidiately with the current state.
+   * @returns Function to unsubscribe. `callback` won't be called anymore.
+   */
   onIsDisabledChanged: (callback: (isDisabled: boolean) => void) => () => void
-  /** Calls the callback immediately with the current validation errors and whenever the field is re-validated.
-   *  the returned function can be called to remove the handler function
-   **/
+
+  /**
+   * Returns the field's validation errors
+   *
+   * The schema errors can change. To always work with the latest errors, use `onSchemaErrorsChanged`.
+   */
+  getSchemaErrors(): ValidationError[]
+
+  /**
+   * Subscribes to schema errors
+   *
+   * @param callback Function that is called every time the schema errors change. Called immediately with the current errors.
+   * @returns Function to unsubscribe. `callback` won't be called anymore.
+   */
   onSchemaErrorsChanged: (callback: (errors: ValidationError[]) => void) => () => void
 }

lib/types/field.types.ts

@@ -1,6 +1,7 @@
 import { Items, SerializedJSONValue } from './utils'
 import { FieldAPI } from './field-locale.types'
 import { ContentTypeFieldValidation } from './entities'
+import { ValidationError } from './validation-error'
 
 export interface FieldInfo {
   id: string
@@ -10,6 +11,8 @@ export interface FieldInfo {
   validations: ContentTypeFieldValidation[]
   items?: Items
   value: any
+  isDisabled: boolean
+  schemaErrors: ValidationError[]
 }
 
 export interface EntryFieldInfo {
@@ -20,6 +23,8 @@ export interface EntryFieldInfo {
   validations: ContentTypeFieldValidation[]
   items?: Items
   values: { [locale: string]: any }
+  isDisabled: { [locale: string]: boolean }
+  schemaErrors: { [locale: string]: ValidationError[] }
 }
 
 export interface EntryFieldAPI {