@rettangoli/fe 1.0.4 → 1.1.1

package/README.md

@@ -195,7 +195,7 @@ Use this workflow:
 Docker image:
 
 ```bash
-IMAGE="han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.10"
+IMAGE="han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.12"
 ```
 
 Dashboard suite:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rettangoli/fe",
-  "version": "1.0.4",
+  "version": "1.1.1",
   "description": "Frontend framework for building reactive web components",
   "type": "module",
   "main": "./src/index.js",

package/src/cli/frontendEntrySource.js

@@ -113,6 +113,10 @@ export const generateFrontendEntrySource = ({
     } else if (YAML_FILE_TYPES.has(fileType)) {
       const yamlObject = readYamlObject(filePath);
 
+      if (fileType === "view" || fileType === "schema") {
+        componentContractEntry.yamlObject = structuredClone(yamlObject);
+      }
+
       if (fileType === "view") {
         try {
           yamlObject.template = parseTemplate(yamlObject.template);
@@ -127,10 +131,6 @@ export const generateFrontendEntrySource = ({
         validateConstantsRoot({ filePath, yamlObject, errorPrefix });
       }
 
-      if (fileType === "view" || fileType === "schema") {
-        componentContractEntry.yamlObject = yamlObject;
-      }
-
       declarationLines.push(
         `const ${declarationName} = ${JSON.stringify(yamlObject)};`,
       );

package/src/core/contracts/componentFiles.js

@@ -1,3 +1,5 @@
+import { findUnsupportedTemplatePropertyBindingSyntax } from "../view/templatePropertyBindings.js";
+
 export const FORBIDDEN_VIEW_KEYS = Object.freeze([
   "elementName",
   "viewDataSchema",
@@ -7,24 +9,6 @@ export const FORBIDDEN_VIEW_KEYS = Object.freeze([
   "attrsSchema",
 ]);
 
-const LEGACY_PROP_BINDING_REGEX = /(^|\s)\.[A-Za-z_][A-Za-z0-9_-]*\s*=/;
-
-const hasLegacyDotPropBinding = (node) => {
-  if (Array.isArray(node)) {
-    return node.some((item) => hasLegacyDotPropBinding(item));
-  }
-  if (!node || typeof node !== "object") {
-    return false;
-  }
-
-  return Object.entries(node).some(([key, value]) => {
-    if (LEGACY_PROP_BINDING_REGEX.test(key)) {
-      return true;
-    }
-    return hasLegacyDotPropBinding(value);
-  });
-};
-
 export const buildComponentContractIndex = (entries = []) => {
   const index = {};
 
@@ -99,10 +83,10 @@ export const validateComponentContractIndex = (index = {}) => {
         });
       });
 
-      if (hasLegacyDotPropBinding(viewYaml.template)) {
+      if (findUnsupportedTemplatePropertyBindingSyntax(viewYaml.template)) {
         errors.push({
           code: "RTGL-CONTRACT-003",
-          message: `${componentLabel}: legacy '.prop=' binding is not supported. Use ':prop=' in .view.yaml.`,
+          message: `${componentLabel}: legacy property binding syntax is not supported. Use ':prop=\${value}' in .view.yaml.`,
           filePath: viewFilePath || representativeFile,
         });
       }

package/src/core/runtime/componentOrchestrator.js

@@ -7,7 +7,7 @@ import {
   cleanupEventRateLimitState,
   syncRefIds,
 } from "./componentRuntime.js";
-import { buildOnUpdateChanges } from "./lifecycle.js";
+import { buildOnPropUpdateChanges, buildOnUpdateChanges } from "./lifecycle.js";
 import { normalizeAttributeValue, toCamelCase } from "./props.js";
 
 export const createRuntimeDepsForInstance = ({ instance }) => {
@@ -112,6 +112,39 @@ export const runAttributeChangedComponentLifecycle = ({
   });
 };
 
+export const runPropChangedComponentLifecycle = ({
+  instance,
+  propName,
+  oldValue,
+  newValue,
+  scheduleFrameFn,
+}) => {
+  if (oldValue === newValue || !instance.render) {
+    return;
+  }
+
+  if (instance.isConnected === false || !instance.renderTarget) {
+    return;
+  }
+
+  if (instance.handlers?.handleOnUpdate) {
+    const runtimeDeps = createRuntimeDepsForInstance({ instance });
+    const changes = buildOnPropUpdateChanges({
+      propName,
+      oldValue,
+      newValue,
+      deps: runtimeDeps,
+      propsSchemaKeys: instance._propsSchemaKeys,
+    });
+    instance.handlers.handleOnUpdate(runtimeDeps, changes);
+    return;
+  }
+
+  scheduleFrameFn(() => {
+    instance.render();
+  });
+};
+
 export const runRenderComponentLifecycle = ({
   instance,
   createComponentUpdateHookFn,

package/src/core/runtime/lifecycle.js

@@ -122,3 +122,42 @@ export const buildOnUpdateChanges = ({
     newProps,
   };
 };
+
+export const buildOnPropUpdateChanges = ({
+  propName,
+  oldValue,
+  newValue,
+  deps,
+  propsSchemaKeys,
+}) => {
+  const newProps = {};
+
+  propsSchemaKeys.forEach((propKey) => {
+    const propValue = deps.props[propKey];
+    if (propValue !== undefined) {
+      newProps[propKey] = propValue;
+    }
+  });
+
+  const oldProps = {
+    ...newProps,
+  };
+
+  if (oldValue === undefined) {
+    delete oldProps[propName];
+  } else {
+    oldProps[propName] = oldValue;
+  }
+
+  if (newValue === undefined) {
+    delete newProps[propName];
+  } else {
+    newProps[propName] = newValue;
+  }
+
+  return {
+    changedProp: propName,
+    oldProps,
+    newProps,
+  };
+};

package/src/core/runtime/props.js

@@ -28,6 +28,81 @@ export const readPropFallbackFromAttributes = (source, propName) => {
   return undefined;
 };
 
+const REACTIVE_PROP_VALUES = Symbol("rtglReactivePropValues");
+
+const ensureReactivePropValues = (source) => {
+  if (!Object.prototype.hasOwnProperty.call(source, REACTIVE_PROP_VALUES)) {
+    Object.defineProperty(source, REACTIVE_PROP_VALUES, {
+      value: Object.create(null),
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+  }
+
+  return source[REACTIVE_PROP_VALUES];
+};
+
+export const installReactiveProps = ({
+  source,
+  allowedKeys = [],
+  onPropChange,
+}) => {
+  const reactiveValues = ensureReactivePropValues(source);
+
+  allowedKeys.forEach((propName) => {
+    if (typeof propName !== "string" || propName.length === 0) {
+      return;
+    }
+
+    const presetValue = Object.prototype.hasOwnProperty.call(source, propName)
+      ? source[propName]
+      : undefined;
+    const hadPresetValue = Object.prototype.hasOwnProperty.call(source, propName);
+
+    if (hadPresetValue) {
+      delete source[propName];
+    }
+
+    Object.defineProperty(source, propName, {
+      configurable: true,
+      enumerable: true,
+      get() {
+        if (Object.prototype.hasOwnProperty.call(reactiveValues, propName)) {
+          return reactiveValues[propName];
+        }
+
+        return readPropFallbackFromAttributes(source, propName);
+      },
+      set(value) {
+        const oldValue = Object.prototype.hasOwnProperty.call(reactiveValues, propName)
+          ? reactiveValues[propName]
+          : readPropFallbackFromAttributes(source, propName);
+
+        if (value === undefined) {
+          delete reactiveValues[propName];
+        } else {
+          reactiveValues[propName] = value;
+        }
+
+        if (oldValue === value) {
+          return;
+        }
+
+        onPropChange?.({
+          propName,
+          oldValue,
+          newValue: value,
+        });
+      },
+    });
+
+    if (hadPresetValue) {
+      reactiveValues[propName] = presetValue;
+    }
+  });
+};
+
 export const createPropsProxy = (source, allowedKeys) => {
   const allowed = new Set(allowedKeys);
   return new Proxy(

package/src/core/view/bindings.js

@@ -149,7 +149,7 @@ export const parseNodeBindings = ({
     }
     if (Object.prototype.hasOwnProperty.call(props, normalizedPropName)) {
       throw new Error(
-        `[Parser] Duplicate prop binding '${normalizedPropName}' on '${tagName}'. Use only one of 'name=value' or ':name=value'.`,
+        `[Parser] Duplicate prop binding '${normalizedPropName}' on '${tagName}'. Use only one of 'name=value' or ':name=\${expr}'.`,
       );
     }
     props[normalizedPropName] = propValue;

package/src/core/view/templatePropertyBindings.js

@@ -0,0 +1,276 @@
+import { parse as parseTemplate } from "jempl";
+import { NodeType } from "jempl/src/parse/constants.js";
+
+const ATTR_ASSIGNMENT_REGEX = /(\S+?)=(?:\"([^\"]*)\"|\'([^\']*)\'|([^\s]*))/g;
+const LOOP_DIRECTIVE_REGEX = /^\$for\s+([A-Za-z_][A-Za-z0-9_]*)(?:\s*,\s*([A-Za-z_][A-Za-z0-9_]*))?\s+in\s+.+$/;
+const INTERPOLATION_ONLY_REGEX = /^\$\{([^{}]+)\}$/;
+const SIMPLE_PATH_REGEX = /^[A-Za-z_][A-Za-z0-9_]*(?:(?:\.[A-Za-z_][A-Za-z0-9_]*)|\[(?:\d+|"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')\])*$/;
+
+const normalizedTemplateCache = new WeakSet();
+
+const extendScopeVars = (scopeVars, itemVar, indexVar) => {
+  const nextScopeVars = new Set(scopeVars);
+  if (itemVar) {
+    nextScopeVars.add(itemVar);
+  }
+  if (indexVar) {
+    nextScopeVars.add(indexVar);
+  }
+  return nextScopeVars;
+};
+
+const getLoopScopeVarsFromRawKey = (key, scopeVars) => {
+  if (typeof key !== "string") {
+    return scopeVars;
+  }
+
+  const loopMatch = key.match(LOOP_DIRECTIVE_REGEX);
+  if (!loopMatch) {
+    return scopeVars;
+  }
+
+  return extendScopeVars(scopeVars, loopMatch[1], loopMatch[2]);
+};
+
+const getPropertyBindingViolationForKey = (key) => {
+  if (typeof key !== "string" || (!key.includes(":") && !key.includes("."))) {
+    return null;
+  }
+
+  ATTR_ASSIGNMENT_REGEX.lastIndex = 0;
+  let match;
+  while ((match = ATTR_ASSIGNMENT_REGEX.exec(key)) !== null) {
+    const rawBindingName = match[1];
+    if (rawBindingName.startsWith(".")) {
+      return {
+        bindingName: rawBindingName,
+        rawValue: match[2] ?? match[3] ?? match[4] ?? "",
+        key,
+      };
+    }
+
+    if (!rawBindingName.startsWith(":")) {
+      continue;
+    }
+
+    const isQuoted = match[2] !== undefined || match[3] !== undefined;
+    const rawValue = match[2] ?? match[3] ?? match[4] ?? "";
+    if (isQuoted || !INTERPOLATION_ONLY_REGEX.test(rawValue)) {
+      return {
+        bindingName: rawBindingName,
+        rawValue,
+        key,
+      };
+    }
+  }
+
+  return null;
+};
+
+const walkRawTemplateForViolation = (node, scopeVars = new Set()) => {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      const violation = walkRawTemplateForViolation(item, scopeVars);
+      if (violation) {
+        return violation;
+      }
+    }
+    return null;
+  }
+
+  if (!node || typeof node !== "object") {
+    return null;
+  }
+
+  for (const [key, value] of Object.entries(node)) {
+    const violation = getPropertyBindingViolationForKey(key);
+    if (violation) {
+      return violation;
+    }
+
+    const nextScopeVars = getLoopScopeVarsFromRawKey(key, scopeVars);
+    const nestedViolation = walkRawTemplateForViolation(value, nextScopeVars);
+    if (nestedViolation) {
+      return nestedViolation;
+    }
+  }
+
+  return null;
+};
+
+const walkAstTemplateForViolation = (node, scopeVars = new Set()) => {
+  if (!node || typeof node !== "object") {
+    return null;
+  }
+
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      const violation = walkAstTemplateForViolation(item, scopeVars);
+      if (violation) {
+        return violation;
+      }
+    }
+    return null;
+  }
+
+  if (node.type === NodeType.LOOP) {
+    const nextScopeVars = extendScopeVars(scopeVars, node.itemVar, node.indexVar);
+    return walkAstTemplateForViolation(node.body, nextScopeVars);
+  }
+
+  if (node.type === NodeType.ARRAY && Array.isArray(node.items)) {
+    return walkAstTemplateForViolation(node.items, scopeVars);
+  }
+
+  if (node.type === NodeType.OBJECT && Array.isArray(node.properties)) {
+    for (const property of node.properties) {
+      const violation = getPropertyBindingViolationForKey(property.key);
+      if (violation) {
+        return violation;
+      }
+      const nestedViolation = walkAstTemplateForViolation(property.value, scopeVars);
+      if (nestedViolation) {
+        return nestedViolation;
+      }
+    }
+    return null;
+  }
+
+  for (const value of Object.values(node)) {
+    const violation = walkAstTemplateForViolation(value, scopeVars);
+    if (violation) {
+      return violation;
+    }
+  }
+
+  return null;
+};
+
+const deriveParsedKey = (key) => {
+  const parsed = parseTemplate([{ [key]: "" }]);
+  const property = parsed?.items?.[0]?.properties?.[0];
+  return property?.parsedKey;
+};
+
+const getInterpolationExpression = (rawValue) => {
+  const match = rawValue.match(INTERPOLATION_ONLY_REGEX);
+  return match ? match[1].trim() : null;
+};
+
+const getBaseIdentifier = (expression) => {
+  const match = expression.match(/^([A-Za-z_][A-Za-z0-9_]*)/);
+  return match ? match[1] : null;
+};
+
+const normalizePropertyBindingsInKey = (key, scopeVars) => {
+  let changed = false;
+
+  const normalizedKey = key.replace(
+    ATTR_ASSIGNMENT_REGEX,
+    (fullMatch, rawBindingName, doubleQuotedValue, singleQuotedValue, bareValue) => {
+      if (!rawBindingName.startsWith(":")) {
+        return fullMatch;
+      }
+
+      const rawValue = doubleQuotedValue ?? singleQuotedValue ?? bareValue ?? "";
+      const expression = getInterpolationExpression(rawValue);
+      if (!expression || !SIMPLE_PATH_REGEX.test(expression)) {
+        return fullMatch;
+      }
+
+      const baseIdentifier = getBaseIdentifier(expression);
+      if (!baseIdentifier) {
+        return fullMatch;
+      }
+
+      const internalValue = scopeVars.has(baseIdentifier)
+        ? `#{${expression}}`
+        : expression;
+
+      if (internalValue === rawValue) {
+        return fullMatch;
+      }
+
+      changed = true;
+      return `${rawBindingName}=${internalValue}`;
+    },
+  );
+
+  return changed ? normalizedKey : key;
+};
+
+const normalizeAstTemplate = (node, scopeVars = new Set()) => {
+  if (!node || typeof node !== "object") {
+    return;
+  }
+
+  if (Array.isArray(node)) {
+    node.forEach((item) => normalizeAstTemplate(item, scopeVars));
+    return;
+  }
+
+  if (node.type === NodeType.LOOP) {
+    const nextScopeVars = extendScopeVars(scopeVars, node.itemVar, node.indexVar);
+    normalizeAstTemplate(node.body, nextScopeVars);
+    return;
+  }
+
+  if (node.type === NodeType.ARRAY && Array.isArray(node.items)) {
+    node.items.forEach((item) => normalizeAstTemplate(item, scopeVars));
+    return;
+  }
+
+  if (node.type === NodeType.OBJECT && Array.isArray(node.properties)) {
+    node.properties.forEach((property) => {
+      const normalizedKey = normalizePropertyBindingsInKey(property.key, scopeVars);
+      if (normalizedKey !== property.key) {
+        property.key = normalizedKey;
+        const parsedKey = deriveParsedKey(normalizedKey);
+        if (parsedKey) {
+          property.parsedKey = parsedKey;
+        } else {
+          delete property.parsedKey;
+        }
+      }
+
+      normalizeAstTemplate(property.value, scopeVars);
+    });
+    return;
+  }
+
+  Object.values(node).forEach((value) => {
+    normalizeAstTemplate(value, scopeVars);
+  });
+};
+
+export const findUnsupportedTemplatePropertyBindingSyntax = (template) => {
+  if (!template) {
+    return null;
+  }
+
+  if (template.type && typeof template.type === "number") {
+    return walkAstTemplateForViolation(template);
+  }
+
+  return walkRawTemplateForViolation(template);
+};
+
+export const ensureNormalizedTemplatePropertyBindings = (template) => {
+  if (!template || typeof template !== "object") {
+    return;
+  }
+
+  if (normalizedTemplateCache.has(template)) {
+    return;
+  }
+
+  const violation = findUnsupportedTemplatePropertyBindingSyntax(template);
+  if (violation) {
+    throw new Error(
+      `Property-form bindings must use ':prop=\${value}' syntax. Found '${violation.bindingName}=${violation.rawValue}' in '${violation.key}'.`,
+    );
+  }
+
+  normalizeAstTemplate(template);
+  normalizedTemplateCache.add(template);
+};

package/src/parser.js

@@ -2,6 +2,7 @@ import { parseAndRender as jemplParseAndRender, render as jemplRender } from "je
 
 import { flattenArrays } from "./utils/flattenArrays.js";
 import { parseNodeBindings } from './core/view/bindings.js';
+import { ensureNormalizedTemplatePropertyBindings } from "./core/view/templatePropertyBindings.js";
 import {
   createRefMatchers,
   resolveBestRefMatcher,
@@ -20,6 +21,7 @@ export const parseView = ({
   handlers,
   createComponentUpdateHook,
 }) => {
+  ensureNormalizedTemplatePropertyBindings(template);
   const result = jemplRender(template, viewData, {});
 
   // Flatten the array carefully to maintain structure

package/src/web/createWebComponentClass.js

@@ -7,9 +7,10 @@ import {
   runAttributeChangedComponentLifecycle,
   runConnectedComponentLifecycle,
   runDisconnectedComponentLifecycle,
+  runPropChangedComponentLifecycle,
   runRenderComponentLifecycle,
 } from "../core/runtime/componentOrchestrator.js";
-import { createPropsProxy, toKebabCase } from "../core/runtime/props.js";
+import { createPropsProxy, installReactiveProps, toKebabCase } from "../core/runtime/props.js";
 import {
   buildObservedAttributes,
 } from "../core/runtime/componentRuntime.js";
@@ -120,6 +121,19 @@ export const createWebComponentClass = ({
         fileConstants: constants,
       });
       this.propsSchema = propsSchema;
+      installReactiveProps({
+        source: this,
+        allowedKeys: propsSchemaKeys,
+        onPropChange: ({ propName, oldValue, newValue }) => {
+          runPropChangedComponentLifecycle({
+            instance: this,
+            propName,
+            oldValue,
+            newValue,
+            scheduleFrameFn: scheduleFrame,
+          });
+        },
+      });
       this.props = propsSchema
         ? createPropsProxy(this, propsSchemaKeys)
         : {};