feat(hydrate): support object serialization for hydrated components (#6208)

* feat(hydrate): support object serialization for hydrated components

* prettier

* serialize parameters into string

* don't serialize primitives

* implement hydration part

* prettier

* add more unit tests

* prettier

* revert some unneeded changes

* better identify if value is serializable

* properly case unknown attributes

* fix tests

* reorganisation

* fix unit tests

* fix analysis tests

* e2e fixes

* prettier

* progress

* skip some tests

* prettier

* reorg

* fix test

* fix tests

* only deserialize if hydrateClientSide is set

* improve comment

* more test improvements

* prettier

* revert some tests that cause test errors

* Revert "revert some tests that cause test errors"

This reverts commit 7b108e2.

* chore: fix tests

* chore: lint

* chore: fix e2e tests

---------

Co-authored-by: John Jenkins <[email protected]>

Author: christian-bromann

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

@@ -98,6 +98,7 @@ 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',
@@ -106,11 +107,12 @@ const parsePropDecorator = (
     getter: ts.isGetAccessor(prop),
     setter: !!foundSetter,
   };
-  if (ogPropName && ogPropName !== propName) propMeta.ogPropName = ogPropName;
+  if (ogPropName && ogPropName !== propName) {
+    propMeta.ogPropName = ogPropName;
+  }
 
   // prop can have an attribute if type is NOT "unknown"
   if (typeStr !== 'unknown') {
-    propMeta.attribute = getAttributeName(propName, propOptions);
     propMeta.reflect = getReflect(diagnostics, propDecorator, propOptions);
   }
 

src/compiler/transformers/test/convert-decorators.spec.ts

@@ -28,14 +28,14 @@ describe('convert-decorators', () => {
           return {
             "val": {
               "type": "string",
+              attribute: 'val',
               "mutable": false,
               "complexType": { "original": "string", "resolved": "string", "references": {} },
               "required": false,
               "optional": false,
               "docs": { "tags": [], "text": "" },
               "getter": false, 
               "setter": false,
-              "attribute": "val",
               "reflect": false,
               "defaultValue": "\\"initial value\\""
             }

src/compiler/transformers/test/parse-props.spec.ts

@@ -213,6 +213,7 @@ describe('parse props', () => {
     `);
     expect(getStaticGetter(t.outputText, 'properties')).toEqual({
       val: {
+        attribute: 'val',
         complexType: {
           references: {},
           resolved: '{}', // TODO, needs to be string[]
@@ -231,7 +232,7 @@ describe('parse props', () => {
       },
     });
     expect(t.property?.type).toBe('unknown');
-    expect(t.property?.attribute).toBe(undefined);
+    expect(t.property?.attribute).toBe('val');
     expect(t.property?.reflect).toBe(false);
   });
 
@@ -819,19 +820,20 @@ describe('parse props', () => {
         return {
           val: {
             type: 'string',
+            attribute: 'val',
             mutable: false,
             complexType: { original: 'string', resolved: 'string', references: {} },
             required: false,
             optional: false,
             docs: { tags: [], text: '' },
             getter: false,
             setter: false,
-            attribute: 'val',
             reflect: false,
             defaultValue: \"'good'\",
           },
           val2: {
             type: 'string',
+            attribute: 'val-2',
             mutable: false,
             complexType: { original: 'string', resolved: 'string', references: {} },
             required: false,
@@ -840,7 +842,6 @@ describe('parse props', () => {
             getter: false,
             setter: false,
             ogPropName: 'dynVal',
-            attribute: 'val-2',
             reflect: false,
             defaultValue: \"'nice'\",
           },

src/hydrate/platform/proxy-host-element.ts

@@ -41,46 +41,32 @@ export function proxyHostElement(elm: d.HostElement, cstr: d.ComponentConstructo
 
     members.forEach(([memberName, [memberFlags, metaAttributeName]]) => {
       if (memberFlags & MEMBER_FLAGS.Prop) {
+        // hyphenated attribute name
         const attributeName = metaAttributeName || memberName;
-        let attrValue = elm.getAttribute(attributeName);
-
-        /**
-         * allow hydrate parameters that contain a simple object, e.g.
-         * ```ts
-         * import { renderToString } from 'component-library/hydrate';
-         * await renderToString(`<car-detail car=${JSON.stringify({ year: 1234 })}></car-detail>`);
-         * ```
-         */
-        if (
-          (attrValue?.startsWith('{') && attrValue.endsWith('}')) ||
-          (attrValue?.startsWith('[') && attrValue.endsWith(']'))
-        ) {
-          try {
-            attrValue = JSON.parse(attrValue);
-          } catch (e) {
-            /* ignore */
-          }
-        }
-
+        // attribute value
+        const attrValue = elm.getAttribute(attributeName);
+        // property value
+        const propValue = (elm as any)[memberName];
+        let attrPropVal: any;
+        // any existing getter/setter applied to class property
         const { get: origGetter, set: origSetter } =
           Object.getOwnPropertyDescriptor((cstr as any).prototype, memberName) || {};
 
-        let attrPropVal: any;
-
         if (attrValue != null) {
+          // incoming value from `an-attribute=....`. Convert from string to correct type
           attrPropVal = parsePropertyValue(attrValue, memberFlags);
         }
 
-        const ownValue = (elm as any)[memberName];
-        if (ownValue !== undefined) {
-          attrPropVal = ownValue;
-          // we've got an actual value already set on the host element
-          // let's add that to our instance values and pull it off the element
-          // so the getter/setter kicks in instead, but still getting this value
+        if (propValue !== undefined) {
+          // incoming value set on the host element (e.g `element.aProp = ...`)
+          // let's add that to our instance values and pull it off the element.
+          // This allows any applied getter/setter to kick in instead whilst still getting this value
+          attrPropVal = propValue;
           delete (elm as any)[memberName];
         }
 
         if (attrPropVal !== undefined) {
+          // value set via attribute/prop on the host element
           if (origSetter) {
             // we have an original setter, so let's set the value via that.
             origSetter.apply(elm, [attrPropVal]);

src/hydrate/runner/index.ts

@@ -1,2 +1,3 @@
 export { createWindowFromHtml } from './create-window';
 export { hydrateDocument, renderToString, serializeDocumentToString, streamToString } from './render';
+export { deserializeProperty, serializeProperty } from '@utils';

src/runtime/client-hydrate.ts

@@ -1,6 +1,7 @@
 import { BUILD } from '@app-data';
 import { plt, win } from '@platform';
-import { CMP_FLAGS } from '@utils';
+import { parsePropertyValue } from '@runtime';
+import { CMP_FLAGS, MEMBER_FLAGS } from '@utils';
 
 import type * as d from '../declarations';
 import { patchSlottedNode } from './dom-extras';
@@ -53,6 +54,24 @@ export const initializeClientHydrate = (
   const vnode: d.VNode = newVNode(tagName, null);
   vnode.$elm$ = hostElm;
 
+  /**
+   * The following forEach loop attaches properties from the element's attributes to the VNode.
+   * This is used to hydrate the VNode with the initial values of the element's attributes.
+   */
+  const members = Object.entries(hostRef.$cmpMeta$?.$members$ || {});
+  members.forEach(([memberName, [memberFlags, metaAttributeName]]) => {
+    if (!(memberFlags & MEMBER_FLAGS.Prop)) {
+      return;
+    }
+    const attributeName = metaAttributeName || memberName;
+    const attrVal = hostElm.getAttribute(attributeName);
+
+    if (attrVal !== null) {
+      const attrPropVal = parsePropertyValue(attrVal, memberFlags);
+      hostRef?.$instanceValues$?.set(memberName, attrPropVal);
+    }
+  });
+
   let scopeId: string;
   if (BUILD.scoped) {
     const cmpMeta = hostRef.$cmpMeta$;

src/runtime/parse-property-value.ts

@@ -1,5 +1,5 @@
 import { BUILD } from '@app-data';
-import { isComplexType, MEMBER_FLAGS } from '@utils';
+import { deserializeProperty, isComplexType, MEMBER_FLAGS, SERIALIZED_PREFIX } from '@utils';
 
 /**
  * Parse a new property value for a given property type.
@@ -24,32 +24,71 @@ import { isComplexType, MEMBER_FLAGS } from '@utils';
  * @param propType the type of the prop, expressed as a binary number
  * @returns the parsed/coerced value
  */
-export const parsePropertyValue = (propValue: any, propType: number): any => {
-  // ensure this value is of the correct prop type
+export const parsePropertyValue = (propValue: unknown, propType: number): any => {
+  /**
+   * Allow hydrate parameters that contain a simple object, e.g.
+   * ```ts
+   * import { renderToString } from 'component-library/hydrate';
+   * await renderToString(`<car-detail car=${JSON.stringify({ year: 1234 })}></car-detail>`);
+   * ```
+   * @deprecated
+   */
+  if (
+    (BUILD.hydrateClientSide || BUILD.hydrateServerSide) &&
+    typeof propValue === 'string' &&
+    ((propValue.startsWith('{') && propValue.endsWith('}')) || (propValue.startsWith('[') && propValue.endsWith(']')))
+  ) {
+    try {
+      propValue = JSON.parse(propValue);
+      return propValue;
+    } catch (e) {
+      /* ignore */
+    }
+  }
+
+  /**
+   * Allow hydrate parameters that contain a complex non-serialized values.
+   */
+  if (
+    (BUILD.hydrateClientSide || BUILD.hydrateServerSide) &&
+    typeof propValue === 'string' &&
+    propValue.startsWith(SERIALIZED_PREFIX)
+  ) {
+    propValue = deserializeProperty(propValue);
+    return propValue;
+  }
 
   if (propValue != null && !isComplexType(propValue)) {
+    /**
+     * ensure this value is of the correct prop type
+     */
     if (BUILD.propBoolean && propType & MEMBER_FLAGS.Boolean) {
-      // per the HTML spec, any string value means it is a boolean true value
-      // but we'll cheat here and say that the string "false" is the boolean false
+      /**
+       * per the HTML spec, any string value means it is a boolean true value
+       * but we'll cheat here and say that the string "false" is the boolean false
+       */
       return propValue === 'false' ? false : propValue === '' || !!propValue;
     }
 
+    /**
+     * force it to be a number
+     */
     if (BUILD.propNumber && propType & MEMBER_FLAGS.Number) {
-      // force it to be a number
-      return parseFloat(propValue);
+      return typeof propValue === 'string' ? parseFloat(propValue) : typeof propValue === 'number' ? propValue : NaN;
     }
 
+    /**
+     * could have been passed as a number or boolean but we still want it as a string
+     */
     if (BUILD.propString && propType & MEMBER_FLAGS.String) {
-      // could have been passed as a number or boolean
-      // but we still want it as a string
       return String(propValue);
     }
 
-    // redundant return here for better minification
     return propValue;
   }
 
-  // not sure exactly what type we want
-  // so no need to change to a different type
+  /**
+   * not sure exactly what type we want so no need to change to a different type
+   */
   return propValue;
 };

src/runtime/test/hydrate-prop.spec.tsx

@@ -63,7 +63,7 @@ describe('hydrate prop types', () => {
     });
 
     expect(serverHydrated.root).toEqualHtml(`
-      <cmp-a class="hydrated" boolean="false" clamped="11" class="hydrated" num="1" s-id="1" str="hello" accessor="1">
+      <cmp-a class="hydrated" boolean="false" clamped="11" num="1" s-id="1" str="hello" accessor="1">
         <!--r.1-->
         <!--t.1.0.0.0-->
         false-hello world world-201-101-10

src/runtime/vdom/vdom-render.ts

@@ -985,13 +985,14 @@ export const renderVdom = (hostRef: d.HostRef, renderFnResults: d.VNode | d.VNod
   const hostElm = hostRef.$hostElement$;
   const cmpMeta = hostRef.$cmpMeta$;
   const oldVNode: d.VNode = hostRef.$vnode$ || newVNode(null, null);
+  const isHostElement = isHost(renderFnResults);
 
   // if `renderFnResults` is a Host node then we can use it directly. If not,
   // we need to call `h` again to wrap the children of our component in a
   // 'dummy' Host node (well, an empty vnode) since `renderVdom` assumes
   // implicitly that the top-level vdom node is 1) an only child and 2)
   // contains attrs that need to be set on the host element.
-  const rootVnode = isHost(renderFnResults) ? renderFnResults : h(null, null, renderFnResults as any);
+  const rootVnode = isHostElement ? renderFnResults : h(null, null, renderFnResults as any);
 
   hostTagName = hostElm.tagName;
 

src/utils/constants.ts

@@ -259,3 +259,36 @@ export const enum NODE_TYPES {
   DOCUMENT_FRAGMENT_NODE = 11,
   NOTATION_NODE = 12,
 }
+
+/**
+ * Represents a primitive type.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-PrimitiveProtocolValue.
+ */
+export enum PrimitiveType {
+  Undefined = 'undefined',
+  Null = 'null',
+  String = 'string',
+  Number = 'number',
+  SpecialNumber = 'number',
+  Boolean = 'boolean',
+  BigInt = 'bigint',
+}
+
+/**
+ * Represents a non-primitive type.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-RemoteValue.
+ */
+export enum NonPrimitiveType {
+  Array = 'array',
+  Date = 'date',
+  Map = 'map',
+  Object = 'object',
+  RegularExpression = 'regexp',
+  Set = 'set',
+  Channel = 'channel',
+  Symbol = 'symbol',
+}
+
+export const TYPE_CONSTANT = 'type';
+export const VALUE_CONSTANT = 'value';
+export const SERIALIZED_PREFIX = 'serialized:';

src/utils/format-component-runtime-meta.ts

@@ -123,8 +123,16 @@ const formatFlags = (compilerProperty: d.ComponentCompilerProperty) => {
   return type;
 };
 
+/**
+ * We mainly add the alternative kebab-case attribute name because it might
+ * be used in an HTML environment (non JSX). Since we support hydration of
+ * complex types we provide a kebab-case attribute name for properties with
+ * these types.
+ */
+const kebabCaseSupportForTypes = ['string', 'unknown'];
+
 const formatAttrName = (compilerProperty: d.ComponentCompilerProperty) => {
-  if (typeof compilerProperty.attribute === 'string') {
+  if (kebabCaseSupportForTypes.includes(typeof compilerProperty.attribute)) {
     // string attr name means we should observe this attribute
     if (compilerProperty.name === compilerProperty.attribute) {
       // property name and attribute name are the exact same

src/utils/index.ts

@@ -4,6 +4,7 @@ export * from './format-component-runtime-meta';
 export * from './helpers';
 export * from './is-glob';
 export * from './is-root-path';
+export * from './local-value';
 export * from './logger/logger-rollup';
 export * from './logger/logger-typescript';
 export * from './logger/logger-utils';
@@ -12,8 +13,11 @@ export * from './output-target';
 export * from './path';
 export * from './query-nonce-meta-tag-content';
 export * from './regular-expression';
+export * from './remote-value';
 export * as result from './result';
+export * from './serialize';
 export * from './sourcemaps';
+export * from './types';
 export * from './url-paths';
 export * from './util';
 export * from './validation';