feat: new core decorators @PropSerialize & @AttrDeserialize (#6387)

* feat: new core decorators `@PropSerialize` & `@AttrDeserialize`

* chore: prettier

* fix-up unit tests

* chore: fixup tests

* chore: some tests

* chore: let deserializers decide on if Prop has an attr

* chore: more testing

* chore: make tests great again

* chore: update build files

* chore: fix tests more

* chore: we can do stuff before first render!

* chore: revert async decl

* chore: wdio test. Better typing

* chore: more testing

* chore: prettier

---------

Co-authored-by: John Jenkins <john.jenkins@nanoporetech.com>

Author: johnjenkins

src/app-data/index.ts

@@ -60,7 +60,7 @@ export const BUILD: BuildConditionals = {
   vdomRender: true,
   vdomStyle: true,
   vdomText: true,
-  watchCallback: true,
+  propChangeCallback: true,
   taskQueue: true,
   hotModuleReplacement: false,
   isDebug: false,

src/client/client-host-ref.ts

@@ -49,6 +49,7 @@ export const registerHost = (hostElement: d.HostElement, cmpMeta: d.ComponentRun
     $hostElement$: hostElement,
     $cmpMeta$: cmpMeta,
     $instanceValues$: new Map(),
+    $serializerValues$: new Map(),
   };
   if (BUILD.isDev) {
     hostRef.$renderCount$ = 0;
@@ -61,6 +62,9 @@ export const registerHost = (hostElement: d.HostElement, cmpMeta: d.ComponentRun
     hostElement['s-p'] = [];
     hostElement['s-rc'] = [];
   }
+  if (BUILD.lazyLoad) {
+    hostRef.$fetchedCbList$ = [];
+  }
 
   const ref = hostRef;
   hostElement.__stencil__getHostRef = () => ref;

src/compiler/app-core/app-data.ts

@@ -25,7 +25,7 @@ export const getBuildFeatures = (cmps: ComponentCompilerMeta[]): BuildFeatures =
   const f: BuildFeatures = {
     allRenderFn: cmps.every((c) => c.hasRenderFn),
     formAssociated: cmps.some((c) => c.formAssociated),
-
+    deserializer: cmps.some((c) => c.hasDeserializer),
     element: cmps.some((c) => c.hasElement),
     event: cmps.some((c) => c.hasEvent),
     hasRenderFn: cmps.some((c) => c.hasRenderFn),
@@ -41,14 +41,16 @@ export const getBuildFeatures = (cmps: ComponentCompilerMeta[]): BuildFeatures =
     method: cmps.some((c) => c.hasMethod),
     mode: cmps.some((c) => c.hasMode),
     modernPropertyDecls: cmps.some((c) => c.hasModernPropertyDecls),
-    observeAttribute: cmps.some((c) => c.hasAttribute || c.hasWatchCallback),
+    observeAttribute: cmps.some((c) => c.hasAttribute || c.hasWatchCallback || c.hasDeserializer),
     prop: cmps.some((c) => c.hasProp),
     propBoolean: cmps.some((c) => c.hasPropBoolean),
+    propChangeCallback: cmps.some((c) => c.hasWatchCallback || c.hasDeserializer || c.hasSerializer),
     propNumber: cmps.some((c) => c.hasPropNumber),
     propString: cmps.some((c) => c.hasPropString),
     propMutable: cmps.some((c) => c.hasPropMutable),
-    reflect: cmps.some((c) => c.hasReflect),
+    reflect: cmps.some((c) => c.hasReflect || c.hasSerializer),
     scoped: cmps.some((c) => c.encapsulation === 'scoped'),
+    serializer: cmps.some((c) => c.hasSerializer),
     shadowDom,
     shadowDelegatesFocus: shadowDom && cmps.some((c) => c.shadowDelegatesFocus),
     slot,
@@ -68,7 +70,6 @@ export const getBuildFeatures = (cmps: ComponentCompilerMeta[]): BuildFeatures =
     vdomRender: cmps.some((c) => c.hasVdomRender),
     vdomStyle: cmps.some((c) => c.hasVdomStyle),
     vdomText: cmps.some((c) => c.hasVdomText),
-    watchCallback: cmps.some((c) => c.hasWatchCallback),
     taskQueue: true,
   };
   f.vdomAttribute = f.vdomAttribute || f.reflect;

src/compiler/transformers/component-build-conditionals.ts

@@ -21,6 +21,14 @@ export const setComponentBuildConditionals = (cmpMeta: d.ComponentCompilerMeta)
     cmpMeta.hasWatchCallback = true;
   }
 
+  if (cmpMeta.serializers.length > 0) {
+    cmpMeta.hasSerializer = true;
+  }
+
+  if (cmpMeta.deserializers.length > 0) {
+    cmpMeta.hasDeserializer = true;
+  }
+
   if (cmpMeta.methods.length > 0) {
     cmpMeta.hasMethod = true;
   }

src/compiler/transformers/component-hydrate/hydrate-component.ts

@@ -6,7 +6,7 @@ import { addLazyElementGetter } from '../component-lazy/lazy-element-getter';
 import { transformHostData } from '../host-data-transform';
 import { removeStaticMetaProperties } from '../remove-static-meta-properties';
 import { retrieveModifierLike } from '../transform-utils';
-import { addWatchers } from '../watcher-meta-transform';
+import { addReactivePropHandlers } from '../reactive-handler-meta-transform';
 import { addHydrateRuntimeCmpMeta } from './hydrate-runtime-cmp-meta';
 
 export const updateHydrateComponentClass = (
@@ -33,7 +33,9 @@ const updateHydrateHostComponentMembers = (
 
   updateLazyComponentConstructor(classMembers, classNode, moduleFile, cmp);
   addLazyElementGetter(classMembers, moduleFile, cmp);
-  addWatchers(classMembers, cmp);
+  addReactivePropHandlers(classMembers, cmp, 'watchers');
+  addReactivePropHandlers(classMembers, cmp, 'serializers');
+  addReactivePropHandlers(classMembers, cmp, 'deserializers');
   addHydrateRuntimeCmpMeta(classMembers, cmp);
   transformHostData(classMembers, moduleFile);
 

src/compiler/transformers/component-lazy/lazy-component.ts

@@ -5,7 +5,7 @@ import { addStaticStylePropertyToClass } from '../add-static-style';
 import { transformHostData } from '../host-data-transform';
 import { removeStaticMetaProperties } from '../remove-static-meta-properties';
 import { updateComponentClass } from '../update-component-class';
-import { addWatchers } from '../watcher-meta-transform';
+import { addReactivePropHandlers } from '../reactive-handler-meta-transform';
 import { updateLazyComponentConstructor } from './lazy-constructor';
 import { addLazyElementGetter } from './lazy-element-getter';
 
@@ -54,7 +54,9 @@ const updateLazyComponentMembers = (
 
   updateLazyComponentConstructor(classMembers, classNode, moduleFile, cmp);
   addLazyElementGetter(classMembers, moduleFile, cmp);
-  addWatchers(classMembers, cmp);
+  addReactivePropHandlers(classMembers, cmp, 'watchers');
+  addReactivePropHandlers(classMembers, cmp, 'serializers');
+  addReactivePropHandlers(classMembers, cmp, 'deserializers');
   transformHostData(classMembers, moduleFile);
 
   if (transformOpts.style === 'static') {

src/compiler/transformers/component-native/native-component.ts

@@ -7,7 +7,7 @@ import { transformHostData } from '../host-data-transform';
 import { removeStaticMetaProperties } from '../remove-static-meta-properties';
 import { foundSuper, updateConstructor } from '../transform-utils';
 import { updateComponentClass } from '../update-component-class';
-import { addWatchers } from '../watcher-meta-transform';
+import { addReactivePropHandlers } from '../reactive-handler-meta-transform';
 import { addNativeConnectedCallback } from './native-connected-callback';
 import { updateNativeConstructor } from './native-constructor';
 import { addNativeElementGetter } from './native-element-getter';
@@ -145,7 +145,9 @@ const updateNativeHostComponentMembers = (
   updateNativeConstructor(classMembers, moduleFile, cmp, classNode);
   addNativeConnectedCallback(classMembers, cmp);
   addNativeElementGetter(classMembers, cmp);
-  addWatchers(classMembers, cmp);
+  addReactivePropHandlers(classMembers, cmp, 'watchers');
+  addReactivePropHandlers(classMembers, cmp, 'serializers');
+  addReactivePropHandlers(classMembers, cmp, 'deserializers');
 
   if (cmp.isPlain) {
     addNativeComponentMeta(classMembers, cmp);

src/compiler/transformers/decorators-to-static/convert-decorators.ts

@@ -15,6 +15,7 @@ import { methodDecoratorsToStatic, validateMethods } from './method-decorator';
 import { propDecoratorsToStatic } from './prop-decorator';
 import { stateDecoratorsToStatic } from './state-decorator';
 import { watchDecoratorsToStatic } from './watch-decorator';
+import { serializeDecoratorsToStatic } from './serialize-decorators';
 
 /**
  * Create a {@link ts.TransformerFactory} which will handle converting any
@@ -118,6 +119,22 @@ const visitClassDeclaration = (
   // stores a reference to fields that should be watched for changes
   // parse member decorators (Prop, State, Listen, Event, Method, Element and Watch)
   if (decoratedMembers.length > 0) {
+    const serializers = serializeDecoratorsToStatic(
+      typeChecker,
+      decoratedMembers,
+      filteredMethodsAndFields,
+      importAliasMap.get('PropSerialize'),
+      'PropSerialize',
+      importAliasMap.get('Prop'),
+    );
+    const deserializers = serializeDecoratorsToStatic(
+      typeChecker,
+      decoratedMembers,
+      filteredMethodsAndFields,
+      importAliasMap.get('AttrDeserialize'),
+      'AttrDeserialize',
+      importAliasMap.get('Prop'),
+    );
     propDecoratorsToStatic(
       config,
       diagnostics,
@@ -126,6 +143,8 @@ const visitClassDeclaration = (
       program,
       filteredMethodsAndFields,
       importAliasMap.get('Prop'),
+      serializers,
+      deserializers,
     );
     stateDecoratorsToStatic(decoratedMembers, filteredMethodsAndFields, typeChecker, importAliasMap.get('State'));
     eventDecoratorsToStatic(

src/compiler/transformers/decorators-to-static/decorators-constants.ts

@@ -3,6 +3,8 @@
  */
 export const STENCIL_DECORATORS = [
   'AttachInternals',
+  'AttrDeserialize',
+  'PropSerialize',
   'Component',
   'Element',
   'Event',
@@ -27,6 +29,8 @@ export const CLASS_DECORATORS_TO_REMOVE = ['Component'] as const satisfies reado
  */
 export const MEMBER_DECORATORS_TO_REMOVE = [
   'AttachInternals',
+  'AttrDeserialize',
+  'PropSerialize',
   'Element',
   'Event',
   'Listen',
@@ -62,6 +66,8 @@ export const STATIC_GETTER_NAMES = [
   'styleUrls',
   'styles',
   'watchers',
+  'serializers',
+  'deserializers',
 ] as const;
 
 export type StencilStaticGetter = (typeof STATIC_GETTER_NAMES)[number];

src/compiler/transformers/decorators-to-static/prop-decorator.ts

@@ -28,6 +28,7 @@ import { getDecoratorParameters, isDecoratorNamed } from './decorator-utils';
  * @param program a {@link ts.Program} object
  * @param newMembers a collection that parsed `@Prop` annotated class members should be pushed to as a side effect of calling this function
  * @param decoratorName the name of the decorator to look for
+ * @param serializers a collection of serializers (from prop > attribute) used on `@Prop` annotated class members
  */
 export const propDecoratorsToStatic = (
   config: d.ValidatedConfig,
@@ -37,10 +38,24 @@ export const propDecoratorsToStatic = (
   program: ts.Program,
   newMembers: ts.ClassElement[],
   decoratorName: string,
+  serializers: d.ComponentCompilerChangeHandler[],
+  deserializers: d.ComponentCompilerChangeHandler[],
 ): void => {
   const properties = decoratedProps
     .filter((prop) => ts.isPropertyDeclaration(prop) || ts.isGetAccessor(prop))
-    .map((prop) => parsePropDecorator(config, diagnostics, typeChecker, program, prop, decoratorName, newMembers))
+    .map((prop) =>
+      parsePropDecorator(
+        config,
+        diagnostics,
+        typeChecker,
+        program,
+        prop,
+        decoratorName,
+        newMembers,
+        serializers,
+        deserializers,
+      ),
+    )
     .filter((prop): prop is ts.PropertyAssignment => prop != null);
 
   if (properties.length > 0) {
@@ -57,6 +72,8 @@ export const propDecoratorsToStatic = (
  * @param prop the TypeScript `PropertyDeclaration` to parse
  * @param decoratorName the name of the decorator to look for
  * @param newMembers a collection of parsed `@Prop` annotated class members. Used for `get()` decorated props to find a corresponding `set()`
+ * @param serializers a collection of serializers (from prop > attribute) used on `@Prop` annotated class members
+ * @param deserializers a collection of deserializers (from attribute > prop) used on `@Prop` annotated class members
  * @returns a property assignment expression to be added to the Stencil component's class
  */
 const parsePropDecorator = (
@@ -67,6 +84,8 @@ const parsePropDecorator = (
   prop: ts.PropertyDeclaration | ts.GetAccessorDeclaration,
   decoratorName: string,
   newMembers: ts.ClassElement[],
+  serializers: d.ComponentCompilerChangeHandler[],
+  deserializers: d.ComponentCompilerChangeHandler[],
 ): ts.PropertyAssignment | null => {
   const propDecorator = retrieveTsDecorators(prop)?.find(isDecoratorNamed(decoratorName));
   if (propDecorator == null) {
@@ -100,7 +119,6 @@ const parsePropDecorator = (
 
   const propMeta: d.ComponentCompilerStaticProperty = {
     type: typeStr,
-    attribute: getAttributeName(propName, propOptions),
     mutable: !!propOptions.mutable,
     complexType: getComplexType(typeChecker, prop, type, program),
     required: prop.exclamationToken !== undefined && propName !== 'mode',
@@ -113,9 +131,23 @@ const parsePropDecorator = (
     propMeta.ogPropName = ogPropName;
   }
 
-  // prop can have an attribute if type is NOT "unknown"
-  if (typeStr !== 'unknown') {
-    propMeta.reflect = getReflect(diagnostics, propDecorator, propOptions);
+  const foundSerializer = !!serializers.find((s) => s.propName === propName);
+  const foundDeserializer = !!deserializers.find((s) => s.propName === propName);
+
+  // a `@Prop` can reflect if the type is *not* `unknown` (i.e. string, number, boolean, any)
+  // or `@Prop` has a serializer (a fn that can convert a complex type to a string)
+  if (typeStr !== 'unknown' || foundSerializer) {
+    const explicitReflect = getReflect(diagnostics, propDecorator, propOptions);
+    // an explicit reflect argument always wins over inferred
+    propMeta.reflect = explicitReflect === null ? foundSerializer : explicitReflect;
+  }
+
+  // a `@Prop` is allowed to have an attribute if:
+  // - the type is *not* `unknown` (i.e. string, number, boolean, any)
+  // - the prop is reflected (because reflected props must have an attribute)
+  // - a deserializer has been provided (it doesn't make sense to have a deserializer without an attribute)
+  if (typeStr !== 'unknown' || propMeta.reflect || foundDeserializer) {
+    propMeta.attribute = getAttributeName(propName, propOptions);
   }
 
   // extract default value
@@ -179,7 +211,7 @@ const getAttributeName = (propName: string, propOptions: d.PropOptions): string
  * @param propOptions the options passed in to the `@Prop` call expression
  * @returns `true` if the prop should be reflected in the DOM, `false` otherwise
  */
-const getReflect = (diagnostics: d.Diagnostic[], propDecorator: ts.Decorator, propOptions: d.PropOptions): boolean => {
+const getReflect = (diagnostics: d.Diagnostic[], propDecorator: ts.Decorator, propOptions: d.PropOptions) => {
   if (typeof propOptions.reflect === 'boolean') {
     return propOptions.reflect;
   }
@@ -188,9 +220,9 @@ const getReflect = (diagnostics: d.Diagnostic[], propDecorator: ts.Decorator, pr
     err.header = `Rename "reflectToAttr" to "reflect"`;
     err.messageText = `@Prop option "reflectToAttr" should be renamed to "reflect".`;
     augmentDiagnosticWithNode(err, propDecorator);
-    return (propOptions as any).reflectToAttr;
+    return (propOptions as any).reflectToAttr as boolean;
   }
-  return false;
+  return null;
 };
 
 const getComplexType = (