@rettangoli/fe 0.0.13 → 1.0.0-rc1

package/src/core/contracts/componentFiles.js

@@ -0,0 +1,119 @@
+export const FORBIDDEN_VIEW_KEYS = Object.freeze([
+  "elementName",
+  "viewDataSchema",
+  "propsSchema",
+  "events",
+  "methods",
+  "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 = {};
+
+  entries.forEach((entry) => {
+    const {
+      category,
+      component,
+      fileType,
+      filePath,
+      yamlObject,
+    } = entry || {};
+
+    if (!category || !component || !fileType || !filePath) {
+      return;
+    }
+
+    if (!index[category]) {
+      index[category] = {};
+    }
+
+    if (!index[category][component]) {
+      index[category][component] = {
+        fileTypes: new Set(),
+        files: [],
+        viewFilePath: null,
+        viewYaml: null,
+      };
+    }
+
+    const componentEntry = index[category][component];
+    componentEntry.fileTypes.add(fileType);
+    componentEntry.files.push(filePath);
+
+    if (fileType === "view") {
+      componentEntry.viewFilePath = filePath;
+      componentEntry.viewYaml = yamlObject;
+    }
+  });
+
+  return index;
+};
+
+export const validateComponentContractIndex = (index = {}) => {
+  const errors = [];
+
+  Object.entries(index).forEach(([category, components]) => {
+    Object.entries(components).forEach(([component, componentEntry]) => {
+      const componentLabel = `${category}/${component}`;
+      const representativeFile = componentEntry.files[0] || componentLabel;
+
+      if (!componentEntry.fileTypes.has("schema")) {
+        errors.push({
+          code: "RTGL-CONTRACT-001",
+          message: `${componentLabel}: missing required .schema.yaml file.`,
+          filePath: representativeFile,
+        });
+      }
+
+      const { viewYaml, viewFilePath } = componentEntry;
+      if (!viewYaml || typeof viewYaml !== "object" || Array.isArray(viewYaml)) {
+        return;
+      }
+
+      FORBIDDEN_VIEW_KEYS.forEach((forbiddenKey) => {
+        if (!Object.prototype.hasOwnProperty.call(viewYaml, forbiddenKey)) {
+          return;
+        }
+        errors.push({
+          code: "RTGL-CONTRACT-002",
+          message: `${componentLabel}: '${forbiddenKey}' is not allowed in .view.yaml. Move API metadata to .schema.yaml.`,
+          filePath: viewFilePath || representativeFile,
+        });
+      });
+
+      if (hasLegacyDotPropBinding(viewYaml.template)) {
+        errors.push({
+          code: "RTGL-CONTRACT-003",
+          message: `${componentLabel}: legacy '.prop=' binding is not supported. Use ':prop=' in .view.yaml.`,
+          filePath: viewFilePath || representativeFile,
+        });
+      }
+    });
+  });
+
+  return errors;
+};
+
+export const formatContractErrors = (errors = []) => {
+  return errors.map((error) => {
+    return `${error.code} ${error.message} [${error.filePath}]`;
+  });
+};

package/src/core/runtime/componentOrchestrator.js

@@ -0,0 +1,156 @@
+import { parseView } from "../../parser.js";
+import { createTransformedHandlers, runAfterMount, runBeforeMount } from "./lifecycle.js";
+import { attachGlobalRefListeners } from "./globalListeners.js";
+import { collectRefElements } from "./refs.js";
+import {
+  createComponentRuntimeDeps,
+  cleanupEventRateLimitState,
+  syncRefIds,
+} from "./componentRuntime.js";
+import { buildOnUpdateChanges } from "./lifecycle.js";
+import { normalizeAttributeValue, toCamelCase } from "./props.js";
+
+export const createRuntimeDepsForInstance = ({ instance }) => {
+  return createComponentRuntimeDeps({
+    baseDeps: instance.deps,
+    refs: instance.refIds,
+    dispatchEvent: instance.dispatchEvent.bind(instance),
+    store: instance.store,
+    render: instance.render.bind(instance),
+  });
+};
+
+export const runConnectedComponentLifecycle = ({
+  instance,
+  parseAndRenderFn,
+  renderFn,
+  createTransformedHandlersFn = createTransformedHandlers,
+  runBeforeMountFn = runBeforeMount,
+  attachGlobalRefListenersFn = attachGlobalRefListeners,
+  runAfterMountFn = runAfterMount,
+}) => {
+  const runtimeDeps = createRuntimeDepsForInstance({ instance });
+
+  instance.transformedHandlers = createTransformedHandlersFn({
+    handlers: instance.handlers,
+    deps: runtimeDeps,
+    parseAndRenderFn,
+  });
+
+  instance._unmountCallback = runBeforeMountFn({
+    handlers: instance.handlers,
+    deps: runtimeDeps,
+  });
+
+  instance._globalListenersCleanup = attachGlobalRefListenersFn({
+    refs: instance.refs,
+    handlers: instance.transformedHandlers,
+    parseAndRenderFn,
+  });
+
+  renderFn();
+
+  runAfterMountFn({
+    handlers: instance.handlers,
+    deps: runtimeDeps,
+  });
+
+  return runtimeDeps;
+};
+
+export const runDisconnectedComponentLifecycle = ({
+  instance,
+  clearTimerFn = clearTimeout,
+}) => {
+  if (instance._unmountCallback) {
+    instance._unmountCallback();
+  }
+  if (instance._globalListenersCleanup) {
+    instance._globalListenersCleanup();
+  }
+  return cleanupEventRateLimitState({
+    transformedHandlers: instance.transformedHandlers,
+    clearTimerFn,
+  });
+};
+
+export const runAttributeChangedComponentLifecycle = ({
+  instance,
+  attributeName,
+  oldValue,
+  newValue,
+  scheduleFrameFn,
+}) => {
+  if (oldValue === newValue || !instance.render) {
+    return;
+  }
+
+  if (instance.handlers?.handleOnUpdate) {
+    const runtimeDeps = createRuntimeDepsForInstance({ instance });
+    const changes = buildOnUpdateChanges({
+      attributeName,
+      oldValue,
+      newValue,
+      deps: runtimeDeps,
+      propsSchemaKeys: instance._propsSchemaKeys,
+      toCamelCase,
+      normalizeAttributeValue,
+    });
+    instance.handlers.handleOnUpdate(runtimeDeps, changes);
+    return;
+  }
+
+  scheduleFrameFn(() => {
+    instance.render();
+  });
+};
+
+export const runRenderComponentLifecycle = ({
+  instance,
+  createComponentUpdateHookFn,
+  parseViewFn = parseView,
+  collectRefElementsFn = collectRefElements,
+  onError = (error) => {
+    console.error("Error during patching:", error);
+  },
+}) => {
+  if (!instance.patch) {
+    console.error("Patch function is not defined!");
+    return null;
+  }
+
+  if (!instance.template) {
+    console.error("Template is not defined!");
+    return null;
+  }
+
+  try {
+    const vDom = parseViewFn({
+      h: instance.h,
+      template: instance.template,
+      viewData: instance.viewData,
+      refs: instance.refs,
+      handlers: instance.transformedHandlers,
+      createComponentUpdateHook: createComponentUpdateHookFn,
+    });
+
+    if (!instance._oldVNode) {
+      instance._oldVNode = instance.patch(instance.renderTarget, vDom);
+    } else {
+      instance._oldVNode = instance.patch(instance._oldVNode, vDom);
+    }
+
+    const ids = collectRefElementsFn({
+      rootVNode: instance._oldVNode,
+      refs: instance.refs,
+    });
+    syncRefIds({
+      refIds: instance.refIds,
+      nextRefIds: ids,
+    });
+    return instance._oldVNode;
+  } catch (error) {
+    onError(error);
+    return null;
+  }
+};

package/src/core/runtime/componentRuntime.js

@@ -0,0 +1,54 @@
+import { createRuntimeDeps } from "./lifecycle.js";
+
+export const buildObservedAttributes = ({ propsSchemaKeys = [], toKebabCase }) => {
+  const observedAttrs = new Set(["key"]);
+  propsSchemaKeys.forEach((propKey) => {
+    observedAttrs.add(propKey);
+    observedAttrs.add(toKebabCase(propKey));
+  });
+  return [...observedAttrs];
+};
+
+export const createComponentRuntimeDeps = ({
+  baseDeps,
+  refs,
+  dispatchEvent,
+  store,
+  render,
+}) => {
+  return createRuntimeDeps({
+    baseDeps,
+    refs,
+    dispatchEvent,
+    store,
+    render,
+  });
+};
+
+export const syncRefIds = ({ refIds, nextRefIds = {} }) => {
+  Object.keys(refIds).forEach((key) => {
+    delete refIds[key];
+  });
+  Object.assign(refIds, nextRefIds);
+  return refIds;
+};
+
+export const cleanupEventRateLimitState = ({
+  transformedHandlers,
+  clearTimerFn = clearTimeout,
+}) => {
+  const eventRateLimitState = transformedHandlers?.__eventRateLimitState;
+  if (!(eventRateLimitState instanceof Map)) {
+    return 0;
+  }
+
+  let clearedTimers = 0;
+  eventRateLimitState.forEach((state) => {
+    if (state && state.debounceTimer) {
+      clearTimerFn(state.debounceTimer);
+      clearedTimers += 1;
+    }
+  });
+  eventRateLimitState.clear();
+  return clearedTimers;
+};

package/src/core/runtime/constants.js

@@ -0,0 +1,27 @@
+import { isObjectPayload } from "./payload.js";
+
+export const deepFreeze = (value) => {
+  if (!isObjectPayload(value) || Object.isFrozen(value)) {
+    return value;
+  }
+
+  Object.values(value).forEach((nestedValue) => {
+    deepFreeze(nestedValue);
+  });
+
+  return Object.freeze(value);
+};
+
+export const resolveConstants = ({ setupConstants, fileConstants }) => {
+  const normalizedSetupConstants = isObjectPayload(setupConstants)
+    ? setupConstants
+    : {};
+  const normalizedFileConstants = isObjectPayload(fileConstants)
+    ? fileConstants
+    : {};
+
+  return deepFreeze({
+    ...normalizedSetupConstants,
+    ...normalizedFileConstants,
+  });
+};

package/src/core/runtime/events.js

@@ -0,0 +1,191 @@
+import { validateEventConfig } from "../view/refs.js";
+
+export const getEventRateLimitState = (handlers) => {
+  if (!handlers.__eventRateLimitState) {
+    Object.defineProperty(handlers, "__eventRateLimitState", {
+      value: new Map(),
+      enumerable: false,
+      configurable: true,
+    });
+  }
+  return handlers.__eventRateLimitState;
+};
+
+export const createEventDispatchCallback = ({
+  eventConfig,
+  handlers,
+  onMissingHandler,
+  parseAndRenderFn,
+}) => {
+  const getPayload = (event) => {
+    const payloadTemplate = (
+      eventConfig.payload
+      && typeof eventConfig.payload === "object"
+      && !Array.isArray(eventConfig.payload)
+    )
+      ? eventConfig.payload
+      : {};
+    if (typeof parseAndRenderFn !== "function") {
+      return payloadTemplate;
+    }
+    return parseAndRenderFn(payloadTemplate, {
+      _event: event,
+    });
+  };
+
+  if (eventConfig.action) {
+    if (typeof handlers.handleCallStoreAction !== "function") {
+      throw new Error(
+        `[Runtime] Action listener '${eventConfig.action}' requires handlers.handleCallStoreAction.`,
+      );
+    }
+    return (event) => {
+      const payload = getPayload(event);
+      handlers.handleCallStoreAction({
+        ...payload,
+        _event: event,
+        _action: eventConfig.action,
+      });
+    };
+  }
+
+  if (eventConfig.handler && handlers[eventConfig.handler]) {
+    return (event) => {
+      const payload = getPayload(event);
+      handlers[eventConfig.handler]({
+        ...payload,
+        _event: event,
+      });
+    };
+  }
+
+  if (eventConfig.handler) {
+    onMissingHandler?.(eventConfig.handler);
+  }
+
+  return null;
+};
+
+export const createManagedEventListener = ({
+  eventConfig,
+  callback,
+  hasDebounce,
+  hasThrottle,
+  stateKey,
+  eventRateLimitState,
+  fallbackCurrentTarget = null,
+  nowFn = Date.now,
+  setTimeoutFn = setTimeout,
+  clearTimeoutFn = clearTimeout,
+}) => {
+  return (event) => {
+    const state = eventRateLimitState.get(stateKey) || {};
+    const currentTarget = event.currentTarget || fallbackCurrentTarget;
+
+    if (eventConfig.once) {
+      if (currentTarget) {
+        if (!state.onceTargets) {
+          state.onceTargets = new WeakSet();
+        }
+        if (state.onceTargets.has(currentTarget)) {
+          eventRateLimitState.set(stateKey, state);
+          return;
+        }
+        state.onceTargets.add(currentTarget);
+      } else if (state.onceTriggered) {
+        eventRateLimitState.set(stateKey, state);
+        return;
+      } else {
+        state.onceTriggered = true;
+      }
+    }
+
+    if (eventConfig.targetOnly && event.target !== event.currentTarget) {
+      eventRateLimitState.set(stateKey, state);
+      return;
+    }
+
+    if (eventConfig.preventDefault) {
+      event.preventDefault();
+    }
+    if (eventConfig.stopImmediatePropagation) {
+      event.stopImmediatePropagation();
+    } else if (eventConfig.stopPropagation) {
+      event.stopPropagation();
+    }
+
+    if (hasDebounce) {
+      if (state.debounceTimer) {
+        clearTimeoutFn(state.debounceTimer);
+      }
+      state.debounceTimer = setTimeoutFn(() => {
+        callback(event);
+        state.debounceTimer = null;
+      }, eventConfig.debounce);
+      eventRateLimitState.set(stateKey, state);
+      return;
+    }
+
+    if (hasThrottle) {
+      if (!Object.prototype.hasOwnProperty.call(state, "lastThrottleAt")) {
+        state.lastThrottleAt = undefined;
+      }
+      const now = nowFn();
+      if (state.lastThrottleAt === undefined || now - state.lastThrottleAt >= eventConfig.throttle) {
+        state.lastThrottleAt = now;
+        eventRateLimitState.set(stateKey, state);
+        callback(event);
+        return;
+      }
+      eventRateLimitState.set(stateKey, state);
+      return;
+    }
+
+    eventRateLimitState.set(stateKey, state);
+    callback(event);
+  };
+};
+
+export const createConfiguredEventListener = ({
+  eventType,
+  eventConfig,
+  refKey,
+  handlers,
+  eventRateLimitState,
+  stateKey,
+  fallbackCurrentTarget = null,
+  parseAndRenderFn,
+  onMissingHandler,
+  nowFn = Date.now,
+  setTimeoutFn = setTimeout,
+  clearTimeoutFn = clearTimeout,
+}) => {
+  const { hasDebounce, hasThrottle } = validateEventConfig({
+    eventType,
+    eventConfig,
+    refKey,
+  });
+
+  const callback = createEventDispatchCallback({
+    eventConfig,
+    handlers,
+    onMissingHandler,
+    parseAndRenderFn,
+  });
+  if (!callback) {
+    return null;
+  }
+
+  return createManagedEventListener({
+    eventConfig,
+    callback,
+    hasDebounce,
+    hasThrottle,
+    stateKey,
+    eventRateLimitState,
+    fallbackCurrentTarget,
+    nowFn,
+    setTimeoutFn,
+    clearTimeoutFn,
+  });
+};

package/src/core/runtime/globalListeners.js

@@ -0,0 +1,87 @@
+import {
+  createConfiguredEventListener,
+  getEventRateLimitState,
+} from "./events.js";
+
+const resolveGlobalTarget = ({ refKey, targets }) => {
+  if (refKey === "window") {
+    return targets.window;
+  }
+  if (refKey === "document") {
+    return targets.document;
+  }
+  return null;
+};
+
+export const attachGlobalRefListeners = ({
+  refs = {},
+  handlers = {},
+  targets = {
+    window: globalThis.window,
+    document: globalThis.document,
+  },
+  parseAndRenderFn,
+  timing = {
+    nowFn: Date.now,
+    setTimeoutFn: setTimeout,
+    clearTimeoutFn: clearTimeout,
+  },
+  warnFn = console.warn,
+}) => {
+  const cleanupCallbacks = [];
+  const stateKeys = new Set();
+  const eventRateLimitState = getEventRateLimitState(handlers);
+
+  Object.entries(refs).forEach(([refKey, refConfig]) => {
+    if (refKey !== "window" && refKey !== "document") {
+      return;
+    }
+
+    const target = resolveGlobalTarget({ refKey, targets });
+    if (!target || !refConfig?.eventListeners) {
+      return;
+    }
+
+    Object.entries(refConfig.eventListeners).forEach(([eventType, eventConfig]) => {
+      const stateKey = `${refKey}:${eventType}`;
+      stateKeys.add(stateKey);
+      const listener = createConfiguredEventListener({
+        eventType,
+        eventConfig,
+        refKey,
+        handlers,
+        eventRateLimitState,
+        stateKey,
+        fallbackCurrentTarget: target,
+        parseAndRenderFn,
+        nowFn: timing.nowFn,
+        setTimeoutFn: timing.setTimeoutFn,
+        clearTimeoutFn: timing.clearTimeoutFn,
+        onMissingHandler: (missingHandlerName) => {
+          warnFn(
+            `[Runtime] Handler '${missingHandlerName}' for global ref '${refKey}' is referenced but not found in available handlers.`,
+          );
+        },
+      });
+      if (!listener) {
+        return;
+      }
+
+      target.addEventListener(eventType, listener);
+      cleanupCallbacks.push(() => {
+        target.removeEventListener(eventType, listener);
+      });
+    });
+  });
+
+  return () => {
+    cleanupCallbacks.forEach((cleanup) => cleanup());
+    stateKeys.forEach((stateKey) => {
+      const state = eventRateLimitState.get(stateKey);
+      if (state && state.debounceTimer) {
+        timing.clearTimeoutFn(state.debounceTimer);
+      }
+      eventRateLimitState.delete(stateKey);
+    });
+  };
+};