@arkcit/engine-render-layer 0.3.0

package/README.md

@@ -0,0 +1,52 @@
+# @arkcit/engine-render-layer
+
+Renderer-neutral resolved tree layer.
+
+## Position In The Flow
+
+```text
+@arkcit/engine-schema
+@arkcit/engine-runtime
+@arkcit/engine-core
+        ↓
+@arkcit/engine-render-layer
+        ↓
+@arkcit/engine
+@arkcit/engine-react
+@arkcit/engine-angular
+@arkcit/engine-react-native
+        ↓
+target UI libraries
+```
+
+## What Goes In
+
+- schema shape
+- runtime access
+- core resolution rules
+
+## What Comes Out
+
+- resolved node descriptors
+- children/content descriptors
+- renderer-neutral shaping helpers
+
+## Responsibilities
+
+- define the neutral render output
+- avoid framework-specific rendering
+- provide one resolved tree shape to many adapters
+
+## Do Not Put Here
+
+- React elements
+- Angular component instances
+- native widgets
+- docs or studio presentation wrappers
+
+## Used By
+
+- `@arkcit/engine`
+- `@arkcit/engine-react`
+- `@arkcit/engine-angular`
+- `@arkcit/engine-react-native`

package/dist/bindings.d.ts

@@ -0,0 +1,16 @@
+import { UINodeLayout, UINode } from '@arkcit/engine-schema';
+import { UIRuntime } from '@arkcit/engine-runtime';
+
+declare const readRenderLayerNodeLayout: (props?: Record<string, unknown>) => UINodeLayout;
+
+declare const normalizeRenderLayerTabsProps: (props: Record<string, unknown>) => Record<string, unknown>;
+
+type UnknownRecord = Record<string, unknown>;
+declare const RENDER_BINDING_PROP_NAMES: Set<string>;
+declare const getRenderLayerBindingProps: (props: unknown) => UnknownRecord;
+
+declare const resolveRenderLayerValue: (value: unknown, runtime: UIRuntime) => unknown;
+declare const resolveRenderLayerNodeProps: (props: Record<string, unknown> | undefined, runtime: UIRuntime) => Record<string, unknown>;
+declare const bindRenderLayerNodeEvents: (events: UINode["events"], runtime: UIRuntime) => Partial<Record<keyof NonNullable<UINode["events"]>, (...args: unknown[]) => void>>;
+
+export { RENDER_BINDING_PROP_NAMES, bindRenderLayerNodeEvents, getRenderLayerBindingProps, normalizeRenderLayerTabsProps, readRenderLayerNodeLayout, resolveRenderLayerNodeProps, resolveRenderLayerValue };

package/dist/bindings.js

@@ -0,0 +1,264 @@
+// src/nodeLayout.ts
+var toPositiveNumber = (value) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric <= 0) return void 0;
+  return numeric;
+};
+var toColSpan = (value) => {
+  const numeric = Number(value);
+  if (!Number.isInteger(numeric) || numeric < 1 || numeric > 12) return void 0;
+  return numeric;
+};
+var toCardSection = (value) => {
+  if (value === "header" || value === "body" || value === "footer") return value;
+  return void 0;
+};
+var readRenderLayerNodeLayout = (props) => {
+  var _a, _b, _c, _d, _e, _f, _g;
+  if (!props) return {};
+  const rawLayout = props.layout && typeof props.layout === "object" && !Array.isArray(props.layout) ? props.layout : {};
+  return {
+    widthPct: toPositiveNumber((_a = rawLayout.widthPct) != null ? _a : props.__studioWidthPct),
+    heightPct: toPositiveNumber((_b = rawLayout.heightPct) != null ? _b : props.__studioHeightPct),
+    heightPx: toPositiveNumber((_c = rawLayout.heightPx) != null ? _c : props.__studioHeightPx),
+    colSpan: toColSpan((_d = rawLayout.colSpan) != null ? _d : props.__studioColSpan),
+    wrapperClassName: String(
+      (_f = (_e = rawLayout.wrapperClassName) != null ? _e : props.__studioWrapperClassName) != null ? _f : ""
+    ).trim(),
+    cardSection: toCardSection((_g = rawLayout.cardSection) != null ? _g : props.__studioCardSection),
+    wizardStep: rawLayout.wizardStep === true ? true : void 0,
+    wizardStepRole: rawLayout.wizardStepRole === "title" || rawLayout.wizardStepRole === "description" ? rawLayout.wizardStepRole : void 0,
+    wizardContent: rawLayout.wizardContent === true ? true : void 0,
+    accordionItem: rawLayout.accordionItem === true ? true : void 0,
+    formRole: rawLayout.formRole === "field" || rawLayout.formRole === "title" || rawLayout.formRole === "submit" || rawLayout.formRole === "reset" || rawLayout.formRole === "step" || rawLayout.formRole === "step-content" || rawLayout.formRole === "trigger" || rawLayout.formRole === "content" ? rawLayout.formRole : void 0,
+    tabId: typeof rawLayout.tabId === "string" || typeof rawLayout.tabId === "number" ? String(rawLayout.tabId) : void 0
+  };
+};
+
+// src/normalizeTabsProps.ts
+var normalizeRenderLayerTabsProps = (props) => {
+  var _a;
+  const rawTabs = Array.isArray(props.tabs) ? props.tabs : [];
+  const tabs = rawTabs.length ? rawTabs.map((tab, index) => {
+    var _a2, _b, _c;
+    const rawTab = tab && typeof tab === "object" && !Array.isArray(tab) ? tab : {};
+    const id = String((_a2 = rawTab.id) != null ? _a2 : `tab-${index + 1}`);
+    const title = (_c = (_b = rawTab.title) != null ? _b : rawTab.label) != null ? _c : `Tab ${index + 1}`;
+    return {
+      ...rawTab,
+      id,
+      title,
+      label: title
+    };
+  }) : [
+    {
+      id: "overview",
+      title: "Overview",
+      label: "Overview",
+      content: "Overview content"
+    }
+  ];
+  const rawDict = props.dict && typeof props.dict === "object" && !Array.isArray(props.dict) ? props.dict : {};
+  const rawUrlSync = props.urlSync && typeof props.urlSync === "object" && !Array.isArray(props.urlSync) ? props.urlSync : null;
+  const rawNavigation = (rawUrlSync == null ? void 0 : rawUrlSync.navigation) && typeof rawUrlSync.navigation === "object" && !Array.isArray(rawUrlSync.navigation) ? rawUrlSync.navigation : null;
+  const normalizedUrlSync = rawNavigation && typeof rawNavigation.getSearch === "function" && typeof rawNavigation.replaceSearch === "function" ? {
+    ...rawUrlSync,
+    navigation: rawNavigation
+  } : void 0;
+  return {
+    ...props,
+    tabs,
+    dict: {
+      ...rawDict,
+      noContentYet: typeof rawDict.noContentYet === "string" && rawDict.noContentYet.trim().length > 0 ? rawDict.noContentYet : "No content yet"
+    },
+    defaultActive: typeof props.defaultActive === "string" && props.defaultActive.trim().length > 0 ? props.defaultActive : String((_a = tabs[0].id) != null ? _a : "overview"),
+    keepMounted: typeof props.keepMounted === "boolean" ? props.keepMounted : true,
+    urlSync: normalizedUrlSync
+  };
+};
+
+// src/renderBindingProps.ts
+var RENDER_BINDING_PROP_NAMES = /* @__PURE__ */ new Set([
+  "bindingEnabled",
+  "valueBindingKey",
+  "optionsBindingKey",
+  "useBindingData",
+  "entitiesBindingKey",
+  "videoBindingKey",
+  "mapBindingKey",
+  "productBindingKey",
+  "useTranslationKeys",
+  "tagContentTranslationKey",
+  "tagContentTranslationValue",
+  "hrefTranslationKey",
+  "hrefTranslationValue",
+  "mediaSource",
+  "mediaSrc",
+  "mediaAlt",
+  "rowsBindingKey",
+  "columnsBindingKey"
+]);
+var getRenderLayerBindingProps = (props) => {
+  if (!props || typeof props !== "object" || Array.isArray(props)) {
+    return {};
+  }
+  const source = props;
+  const embedded = source.__studio && typeof source.__studio === "object" && !Array.isArray(source.__studio) ? source.__studio : {};
+  const legacy = Array.from(RENDER_BINDING_PROP_NAMES).reduce(
+    (accumulator, key) => {
+      if (source[key] !== void 0) {
+        accumulator[key] = source[key];
+      }
+      return accumulator;
+    },
+    {}
+  );
+  return Array.from(RENDER_BINDING_PROP_NAMES).reduce((accumulator, key) => {
+    if (legacy[key] !== void 0) {
+      accumulator[key] = legacy[key];
+    } else if (embedded[key] !== void 0) {
+      accumulator[key] = embedded[key];
+    }
+    return accumulator;
+  }, {});
+};
+
+// src/runtimeBindings.ts
+var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var MISSING_TRANSLATION_FALLBACK = "Lorem ipsum dolor sit amet. (fallback)";
+var MISSING_REF_FALLBACK = "Lorem ipsum dolor sit amet. (fallback)";
+var isPlainObject = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+var isReactElementLike = (value) => isPlainObject(value) && typeof value.$$typeof === "symbol" && "props" in value;
+var isTranslationValue = (value) => isPlainObject(value) && typeof value.$t === "string";
+var isRefValue = (value) => isPlainObject(value) && typeof value.$ref === "string";
+var isExprValue = (value) => isPlainObject(value) && typeof value.$expr === "string";
+var parseStructuredString = (value) => {
+  if (typeof value !== "string") return value;
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) return value;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (!isPlainObject(parsed)) return value;
+    if ((typeof parsed.$ref === "string" || typeof parsed.$t === "string") && Object.keys(parsed).length >= 1) {
+      return parsed;
+    }
+    return value;
+  } catch {
+    return value;
+  }
+};
+var resolveRenderLayerValue = (value, runtime) => {
+  const normalizedValue = parseStructuredString(value);
+  if (isTranslationValue(normalizedValue)) {
+    const fallback = typeof normalizedValue.defaultValue === "string" && normalizedValue.defaultValue.trim() ? normalizedValue.defaultValue : normalizedValue.$t;
+    if (!runtime.t) return fallback || MISSING_TRANSLATION_FALLBACK;
+    const translated = runtime.t(normalizedValue.$t, normalizedValue.values);
+    if (typeof translated !== "string") return fallback || MISSING_TRANSLATION_FALLBACK;
+    if (!translated.trim()) return fallback || MISSING_TRANSLATION_FALLBACK;
+    if (translated === normalizedValue.$t) return fallback || MISSING_TRANSLATION_FALLBACK;
+    return translated;
+  }
+  if (isRefValue(normalizedValue)) {
+    const resolved = runtime.get(normalizedValue.$ref);
+    if (resolved == null) return MISSING_REF_FALLBACK;
+    if (typeof resolved === "string" && !resolved.trim()) return MISSING_REF_FALLBACK;
+    return resolved;
+  }
+  if (isExprValue(normalizedValue)) {
+    return void 0;
+  }
+  if (Array.isArray(normalizedValue)) {
+    return normalizedValue.map((item) => resolveRenderLayerValue(item, runtime));
+  }
+  if (isReactElementLike(normalizedValue)) {
+    return normalizedValue;
+  }
+  if (isPlainObject(normalizedValue)) {
+    const next = {};
+    Object.entries(normalizedValue).forEach(([key, childValue]) => {
+      if (DANGEROUS_KEYS.has(key)) return;
+      next[key] = resolveRenderLayerValue(childValue, runtime);
+    });
+    return next;
+  }
+  return normalizedValue;
+};
+var resolveRenderLayerNodeProps = (props, runtime) => {
+  if (!props) return {};
+  const resolved = {};
+  Object.entries(props).forEach(([key, value]) => {
+    if (DANGEROUS_KEYS.has(key)) return;
+    resolved[key] = resolveRenderLayerValue(value, runtime);
+  });
+  return resolved;
+};
+var bindRenderLayerNodeEvents = (events, runtime) => {
+  if (!events) return {};
+  const handlers = {};
+  const extractDynamicPayload = (eventName, args) => {
+    var _a;
+    if (eventName !== "onChange") return void 0;
+    const firstArg = args[0];
+    if (!firstArg || typeof firstArg !== "object" || !("target" in firstArg)) {
+      return void 0;
+    }
+    const target = firstArg.target;
+    if (!target) return void 0;
+    const isCheckboxType = String((_a = target.type) != null ? _a : "").toLowerCase() === "checkbox";
+    const query = isCheckboxType ? target.checked : target.value;
+    return {
+      query,
+      value: target.value,
+      checked: target.checked
+    };
+  };
+  Object.entries(events).forEach(([eventName, action]) => {
+    if (!action) return;
+    handlers[eventName] = (...args) => {
+      const actionRef = action;
+      const dynamicPayload = extractDynamicPayload(eventName, args);
+      if (!dynamicPayload) {
+        runtime.dispatch(actionRef);
+        return;
+      }
+      if ("id" in actionRef) {
+        const basePayload = actionRef.payload && typeof actionRef.payload === "object" ? actionRef.payload : {};
+        runtime.dispatch({
+          ...actionRef,
+          payload: {
+            ...basePayload,
+            ...dynamicPayload
+          }
+        });
+        return;
+      }
+      if ("type" in actionRef) {
+        const basePayload = actionRef.payload && typeof actionRef.payload === "object" ? actionRef.payload : {};
+        runtime.dispatch({
+          ...actionRef,
+          payload: {
+            ...basePayload,
+            ...dynamicPayload
+          }
+        });
+        return;
+      }
+      runtime.dispatch(actionRef);
+    };
+  });
+  return handlers;
+};
+export {
+  RENDER_BINDING_PROP_NAMES,
+  bindRenderLayerNodeEvents,
+  getRenderLayerBindingProps,
+  normalizeRenderLayerTabsProps,
+  readRenderLayerNodeLayout,
+  resolveRenderLayerNodeProps,
+  resolveRenderLayerValue
+};

package/dist/contracts.d.ts

@@ -0,0 +1 @@
+export { ResolvedNode, ResolvedNodeBase, ResolvedNodeChildDescriptor, ResolvedNodeContentDescriptor, createResolvedNode, createResolvedNodeBase } from '@arkcit/engine-core';

package/dist/contracts.js

@@ -0,0 +1,9 @@
+// src/resolvedNode.ts
+import {
+  createResolvedNode,
+  createResolvedNodeBase
+} from "@arkcit/engine-core";
+export {
+  createResolvedNode,
+  createResolvedNodeBase
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { ResolvedNode, ResolvedNodeBase, ResolvedNodeChildDescriptor, ResolvedNodeContentDescriptor, createResolvedNode, createResolvedNodeBase } from '@arkcit/engine-core';
+export { RENDER_BINDING_PROP_NAMES, bindRenderLayerNodeEvents, getRenderLayerBindingProps, normalizeRenderLayerTabsProps, readRenderLayerNodeLayout, resolveRenderLayerNodeProps, resolveRenderLayerValue } from './bindings.js';
+export { AccordionItemDescriptor, ContentCompositionPlan, CoverContentDescriptor, ExpandablePanelContentDescriptor, FinalRenderPlan, NavigationCompositionPlan, RenderDirectivePlan, ResolvedEngineNode, TabsContentDescriptor, resolveAccordionItemDescriptors, resolveChildContentDescriptor, resolveChildDescriptors, resolveContentCompositionPlan, resolveCoverContentDescriptor, resolveExpandablePanelContentDescriptor, resolveFinalRenderPlan, resolveNavigationCompositionPlan, resolveNodeBase, resolveRenderDirectivePlan, resolveResolvedNode, resolveTabsContentDescriptors } from './resolution.js';
+import '@arkcit/engine-schema';
+import '@arkcit/engine-runtime';