[Embeddable] document embeddable transform registry (elastic#235673)

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
Co-authored-by: Ola Pawlus <98127445+olapawlus@users.noreply.github.com>

Author: 4 people

src/platform/plugins/shared/embeddable/common/types.ts

@@ -10,12 +10,18 @@
 import type { Reference } from '@kbn/content-management-utils';
 
 export type EmbeddableTransforms<
-  StoredState extends object = object,
-  State extends object = object
+  StoredEmbeddableState extends object = object,
+  EmbeddableState extends object = object
 > = {
-  transformOut?: (state: StoredState, references?: Reference[]) => State;
-  transformIn?: (state: State) => {
-    state: StoredState;
+  /**
+   * Converts StoredEmbeddableState and injects references into EmbeddableState
+   */
+  transformOut?: (storedState: StoredEmbeddableState, references?: Reference[]) => EmbeddableState;
+  /**
+   * Converts EmbeddableState into StoredEmbeddableState and extracts references
+   */
+  transformIn?: (state: EmbeddableState) => {
+    state: StoredEmbeddableState;
     references?: Reference[];
   };
 };

src/platform/plugins/shared/embeddable/public/types.ts

@@ -70,6 +70,11 @@ export interface EmbeddableSetup {
    */
   registerReactEmbeddableFactory: typeof registerReactEmbeddableFactory;
 
+  /**
+   * Use registerTransforms to register transforms for an embeddable type.
+   * Public transforms registry uses transformOut to convert StoredEmbeddableState from URL into EmbeddableState.
+   * transformIn is not used.
+   */
   registerTransforms: (
     type: string,
     getTransforms: () => Promise<EmbeddableTransforms<any, any> | undefined>

src/platform/plugins/shared/embeddable/server/plugin.ts

@@ -30,6 +30,14 @@ import type { EnhancementRegistryDefinition } from '../common/enhancements/types
 
 export interface EmbeddableSetup extends PersistableStateService<EmbeddableStateWithType> {
   registerEmbeddableFactory: (factory: EmbeddableRegistryDefinition) => void;
+  /**
+   * Use registerTransforms to register transforms for an embeddable type.
+   * Transforms decouple REST API state from stored state,
+   * allowing embeddables to have one shape for REST APIs and another for storage.
+   * Embeddable containers, such as dashboard, use transforms to convert EmbeddableState into StoreEmbeddableState and vice versa.
+   * On read, transformOut is used to convert StoredEmbeddableState and inject references into EmbeddableState.
+   * On write, transformIn is used to extract references and convert EmbeddableState into StoredEmbeddableState.
+   */
   registerTransforms: (type: string, transforms: EmbeddableTransforms<any, any>) => void;
   registerEnhancement: (enhancement: EnhancementRegistryDefinition) => void;
   getAllMigrations: () => MigrateFunctionsObject;