@developer_tribe/react-builder 1.1.0 → 1.2.1

package/src/utils/analyseNode.ts

@@ -1,77 +1,94 @@
 import { Node, NodeData, NodeDefaultAttribute } from '../types/Node';
+import { generateRandomKeyForNode } from './generateRandomKeyForNode';
+import { analyseNodeByPatterns } from './analyseNodeByPatterns';
+import { analyseNodeStructural } from './analyseNodeStructural';
+import { isNodeArray, isNodeNullOrUndefined, isNodeString } from './nodeGuards';
+import { normalizeNodeForValidation } from './__special_exceptions';
 
-export function isNodeNullOrUndefined<T = NodeDefaultAttribute>(
-  node: Node<T>,
-): boolean {
-  return node === null || node === undefined;
-}
-export function isNodeString<T = NodeDefaultAttribute>(node: Node<T>): boolean {
-  return typeof node === 'string';
-}
-export function isNodeArray<T = NodeDefaultAttribute>(node: Node<T>): boolean {
-  return node instanceof Array;
-}
-export function isEmptyObject<T = NodeDefaultAttribute>(
-  node: Node<T>,
-): boolean {
-  return Object.keys(node as Object).length === 0;
+export {
+  isEmptyObject,
+  isNodeArray,
+  isNodeNullOrUndefined,
+  isNodeString,
+} from './nodeGuards';
+
+function assignMissingKeys(
+  node: Node<NodeDefaultAttribute>,
+  usedKeys: Set<string>,
+): Node<NodeDefaultAttribute> {
+  if (isNodeNullOrUndefined(node) || isNodeString(node)) {
+    return node;
+  }
+
+  if (isNodeArray(node)) {
+    const nodeArray = node as unknown as Node<NodeDefaultAttribute>[];
+    return nodeArray.map((child) =>
+      assignMissingKeys(child, usedKeys),
+    ) as unknown as Node<NodeDefaultAttribute>;
+  }
+
+  const recordData = node as NodeData<NodeDefaultAttribute>;
+
+  let key = recordData.key;
+  if (key && usedKeys.has(key)) {
+    // Repair duplicate keys by generating a new unique key.
+    key = undefined;
+  }
+
+  if (!key) {
+    do {
+      key = generateRandomKeyForNode(recordData.type);
+    } while (usedKeys.has(key));
+  }
+  usedKeys.add(key);
+
+  const children = recordData.children
+    ? (assignMissingKeys(
+        recordData.children as Node<NodeDefaultAttribute>,
+        usedKeys,
+      ) as Node<NodeDefaultAttribute>)
+    : recordData.children;
+
+  return {
+    ...recordData,
+    key,
+    children,
+  };
 }
 
 export function analyseNode(node: Node<NodeDefaultAttribute>): {
   valid: boolean;
   message?: string;
 } {
-  if (isNodeNullOrUndefined(node)) {
-    return {
-      valid: true,
-      message: 'null or undefined is valid',
-    };
-  }
+  const structural = analyseNodeStructural(node);
+  if (!structural.valid) return structural;
 
-  if (isNodeString(node)) {
-    return {
-      valid: true,
-      message: 'string is valid',
-    };
+  const patternRes = analyseNodeByPatterns(node);
+  if (!patternRes.valid) {
+    const prefix = patternRes.path ? `${patternRes.path}: ` : '';
+    return { valid: false, message: `${prefix}${patternRes.message ?? ''}` };
   }
 
-  if (isNodeArray(node)) {
-    const nodeArray = node as unknown as Node[];
-    for (const value of nodeArray) {
-      const { valid, message } = analyseNode(value);
-      if (!valid) {
-        return {
-          valid: false,
-          message: message,
-        };
-      }
-    }
-    return {
-      // array is valid
-      valid: true,
-      message: 'Array is valid',
-    };
+  return { valid: true, message: 'Node is valid (structure + patterns)' };
+}
+
+export function analyseAndProccess(
+  node: Node<NodeDefaultAttribute>,
+): Node<NodeDefaultAttribute> | null {
+  if (isNodeNullOrUndefined(node)) {
+    return null;
   }
-  const recordData = node as NodeData;
-  if (isEmptyObject(recordData)) {
-    return {
-      valid: true,
-      message: 'empty object is valid',
-    };
-  } else {
-    if (recordData.children) {
-      const { valid, message } = analyseNode(recordData.children);
-      if (!valid) {
-        return {
-          valid: false,
-          message: message,
-        };
-      }
-    }
 
-    return {
-      valid: true,
-      message: 'everthing is valid',
-    };
+  // Normalize persisted JSON "select option" objects into primitives before
+  // validation (e.g. { label, value } -> value). This commonly appears in
+  // attributes like events[].navigate_to.
+  const normalized = normalizeNodeForValidation(node);
+
+  const { valid, message } = analyseNode(normalized);
+  if (!valid) {
+    throw new Error(message ?? 'Node is not valid');
   }
+
+  const usedKeys = new Set<string>();
+  return assignMissingKeys(normalized, usedKeys);
 }

package/src/utils/analyseNodeByPatterns.ts

@@ -0,0 +1,481 @@
+import type { Node, NodeData, NodeDefaultAttribute } from '../types/Node';
+import {
+  getArrayItemType,
+  getAttributeSchema,
+  getPatternByType,
+  getTypeSchema,
+  isPrimitiveType,
+  normalizeComponentType,
+} from './patterns';
+import { FONT_WEIGHT_OPTIONS, normalizeFontWeight } from './fontWeight';
+import {
+  isEmptyObject,
+  isNodeArray,
+  isNodeNullOrUndefined,
+  isNodeString,
+} from './nodeGuards';
+
+export type AnalyseResultWithPath = {
+  valid: boolean;
+  message?: string;
+  path?: string;
+};
+
+type AttributeTypeSpec = string | string[];
+type AttributeSchema = Record<string, AttributeTypeSpec>;
+
+type PatternLike = {
+  pattern: {
+    type: string;
+    children: unknown;
+    attributes?: AttributeSchema;
+  };
+};
+
+function ok(): AnalyseResultWithPath {
+  return { valid: true };
+}
+
+function fail(message: string, path?: string): AnalyseResultWithPath {
+  return { valid: false, message, path };
+}
+
+function joinPath(base: string, next: string): string {
+  if (!base) return next;
+  if (!next) return base;
+  // next may already include brackets (e.g. [0])
+  return next.startsWith('[') ? `${base}${next}` : `${base}.${next}`;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isNodeDataLike(
+  value: unknown,
+): value is NodeData<NodeDefaultAttribute> {
+  if (!isPlainObject(value)) return false;
+  const maybeType = (value as Record<string, unknown>).type;
+  // `children` is optional in persisted JSON; treat missing as `undefined`.
+  // The structural validator handles overall shape; the pattern validator should
+  // focus on types/attributes/children rules, not require the key to exist.
+  return typeof maybeType === 'string';
+}
+
+function normalizeTypeOrFallback(type: string): string {
+  return normalizeComponentType(type) ?? type;
+}
+
+function getChildrenSpecTokens(pattern: PatternLike): string[] {
+  const raw = pattern?.pattern?.children;
+  if (typeof raw === 'string') return [raw];
+  if (Array.isArray(raw)) return raw.filter((x) => typeof x === 'string');
+  return [];
+}
+
+function splitChildrenSpec(tokens: string[]): {
+  baseKinds: Set<'never' | 'string' | 'node'>;
+  allowedComponentTypes: Set<string>;
+} {
+  const baseKinds = new Set<'never' | 'string' | 'node'>();
+  const allowedComponentTypes = new Set<string>();
+  for (const t of tokens) {
+    // NOTE: pattern.children no longer uses the 'array' token.
+    // 'node' means "a node OR an array of nodes".
+    if (t === 'never' || t === 'string' || t === 'node') {
+      baseKinds.add(t);
+    } else if (t === 'array') {
+      // Backwards-compat: treat 'array' as 'node'
+      baseKinds.add('node');
+    } else if (typeof t === 'string' && t) {
+      allowedComponentTypes.add(normalizeTypeOrFallback(t));
+    }
+  }
+  return { baseKinds, allowedComponentTypes };
+}
+
+function validateChildrenNeverRule(
+  children: Node<NodeDefaultAttribute>,
+  baseKinds: Set<'never' | 'string' | 'node'>,
+  path: string,
+): AnalyseResultWithPath {
+  if (!baseKinds.has('never')) return ok();
+  if (isNodeNullOrUndefined(children) || isEmptyObject(children)) return ok();
+  return fail(`Children not allowed (pattern.children = "never")`, path);
+}
+
+function validateChildrenKindRule(
+  children: Node<NodeDefaultAttribute>,
+  baseKinds: Set<'never' | 'string' | 'node'>,
+  allowedComponentTypes: Set<string>,
+  path: string,
+): AnalyseResultWithPath {
+  if (isNodeNullOrUndefined(children) || isEmptyObject(children)) return ok();
+
+  // Component-type specs allow either a single node or an array of nodes.
+  if (allowedComponentTypes.size > 0) {
+    if (isNodeArray(children)) return ok();
+    if (isNodeDataLike(children)) return ok();
+    return fail(
+      `Children must be a node or array of nodes (allowed: ${Array.from(
+        allowedComponentTypes,
+      ).join(', ')})`,
+      path,
+    );
+  }
+
+  if (isNodeString(children)) {
+    return baseKinds.has('string')
+      ? ok()
+      : fail(`Children must not be a string`, path);
+  }
+  if (isNodeArray(children)) {
+    // 'node' allows both a single node and an array of nodes
+    return baseKinds.has('node')
+      ? ok()
+      : fail(`Children must not be an array`, path);
+  }
+  if (isNodeDataLike(children)) {
+    return baseKinds.has('node')
+      ? ok()
+      : fail(`Children must not be a node`, path);
+  }
+
+  // Unknown object shape
+  return fail(`Children has invalid shape`, path);
+}
+
+function validateChildrenAllowedComponentTypesRule(
+  children: Node<NodeDefaultAttribute>,
+  allowedComponentTypes: Set<string>,
+  path: string,
+): AnalyseResultWithPath {
+  if (allowedComponentTypes.size === 0) return ok();
+  if (isNodeNullOrUndefined(children) || isEmptyObject(children)) return ok();
+
+  const allowed = Array.from(allowedComponentTypes);
+
+  const validateChildType = (child: unknown, childPath: string) => {
+    if (!isNodeDataLike(child)) {
+      return fail(`Child must be an object node`, childPath);
+    }
+    const actual = normalizeTypeOrFallback(child.type);
+    if (!allowedComponentTypes.has(actual)) {
+      return fail(
+        `Child type "${child.type}" is not allowed here (allowed: ${allowed.join(
+          ', ',
+        )})`,
+        joinPath(childPath, 'type'),
+      );
+    }
+    return ok();
+  };
+
+  if (isNodeArray(children)) {
+    const arr = children as unknown[];
+    for (let i = 0; i < arr.length; i++) {
+      const res = validateChildType(arr[i], `${path}[${i}]`);
+      if (!res.valid) return res;
+    }
+    return ok();
+  }
+
+  return validateChildType(children, path);
+}
+
+function validateChildrenByPattern(
+  nodeData: NodeData<NodeDefaultAttribute>,
+  pattern: PatternLike,
+  path: string,
+): AnalyseResultWithPath {
+  const tokens = getChildrenSpecTokens(pattern);
+  const { baseKinds, allowedComponentTypes } = splitChildrenSpec(tokens);
+
+  const neverRes = validateChildrenNeverRule(
+    nodeData.children,
+    baseKinds,
+    path,
+  );
+  if (!neverRes.valid) return neverRes;
+
+  const kindRes = validateChildrenKindRule(
+    nodeData.children,
+    baseKinds,
+    allowedComponentTypes,
+    path,
+  );
+  if (!kindRes.valid) return kindRes;
+
+  return validateChildrenAllowedComponentTypesRule(
+    nodeData.children,
+    allowedComponentTypes,
+    path,
+  );
+}
+
+function validatePrimitiveValue(
+  value: unknown,
+  primitiveType: string,
+  path: string,
+): AnalyseResultWithPath {
+  switch (primitiveType) {
+    case 'string':
+      return typeof value === 'string' ? ok() : fail(`Expected string`, path);
+    case 'number':
+      return typeof value === 'number' ? ok() : fail(`Expected number`, path);
+    case 'boolean':
+      return typeof value === 'boolean' ? ok() : fail(`Expected boolean`, path);
+    case 'color':
+      return typeof value === 'string'
+        ? ok()
+        : fail(`Expected color (string)`, path);
+    case 'size':
+      // Sizes can be numbers or strings like "16@fs" / "100%" / "20px"
+      return typeof value === 'number' || typeof value === 'string'
+        ? ok()
+        : fail(`Expected size (string or number)`, path);
+    case 'fontWeight': {
+      const normalized = normalizeFontWeight(value);
+      if (normalized) return ok();
+      return fail(
+        `Expected fontWeight (${FONT_WEIGHT_OPTIONS.join(', ')})`,
+        path,
+      );
+    }
+    case 'iconType':
+      return typeof value === 'string'
+        ? ok()
+        : fail(`Expected iconType (string)`, path);
+    default:
+      return fail(`Unknown primitive type "${primitiveType}"`, path);
+  }
+}
+
+function validateEnumValue(
+  value: unknown,
+  options: string[],
+  path: string,
+): AnalyseResultWithPath {
+  if (typeof value === 'string') {
+    return options.includes(value)
+      ? ok()
+      : fail(`Expected one of: ${options.join(', ')}`, path);
+  }
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      const v = value[i];
+      if (typeof v !== 'string' || !options.includes(v)) {
+        return fail(
+          `Expected an array of: ${options.join(', ')}`,
+          `${path}[${i}]`,
+        );
+      }
+    }
+    return ok();
+  }
+  return fail(`Expected a string or string[] enum value`, path);
+}
+
+function validateCustomObjectValue(
+  componentType: string,
+  value: unknown,
+  typeName: string,
+  path: string,
+): AnalyseResultWithPath {
+  const schema = getTypeSchema(componentType, typeName);
+  if (!schema) {
+    return fail(`Unknown custom type "${typeName}"`, path);
+  }
+  if (!isPlainObject(value)) {
+    return fail(`Expected object for type "${typeName}"`, path);
+  }
+
+  for (const [fieldName, fieldSpec] of Object.entries(schema)) {
+    if (!(fieldName in value)) continue;
+    const fieldValue = (value as Record<string, unknown>)[fieldName];
+    const fieldPath = joinPath(path, fieldName);
+    const res = validateAttributeValue(
+      componentType,
+      fieldValue,
+      fieldSpec,
+      fieldPath,
+    );
+    if (!res.valid) return res;
+  }
+
+  return ok();
+}
+
+function validateAttributeValue(
+  componentType: string,
+  value: unknown,
+  spec: AttributeTypeSpec,
+  path: string,
+): AnalyseResultWithPath {
+  // Pattern validation does not enforce requiredness (it only validates types for
+  // keys that exist). Treat null/undefined as "unset" so persisted JSON can use
+  // null to clear fields (e.g. events[].navigate_to = null).
+  if (value == null) return ok();
+
+  if (Array.isArray(spec)) {
+    return validateEnumValue(value, spec, path);
+  }
+
+  const arrayItemType = getArrayItemType(spec);
+  if (arrayItemType) {
+    if (!Array.isArray(value)) {
+      return fail(`Expected array for type "${spec}"`, path);
+    }
+    for (let i = 0; i < value.length; i++) {
+      const item = value[i];
+      const itemPath = `${path}[${i}]`;
+      const res = validateAttributeValue(
+        componentType,
+        item,
+        arrayItemType,
+        itemPath,
+      );
+      if (!res.valid) return res;
+    }
+    return ok();
+  }
+
+  if (isPrimitiveType(spec)) {
+    return validatePrimitiveValue(value, spec, path);
+  }
+
+  return validateCustomObjectValue(componentType, value, spec, path);
+}
+
+function validateAttributesByPattern(
+  nodeData: NodeData<NodeDefaultAttribute>,
+  pattern: PatternLike,
+  path: string,
+): AnalyseResultWithPath {
+  const attrs = nodeData.attributes;
+  if (attrs == null) return ok();
+  if (!isPlainObject(attrs)) return fail(`attributes must be an object`, path);
+
+  const schema: AttributeSchema = (getAttributeSchema(pattern.pattern.type) ??
+    pattern.pattern.attributes ??
+    {}) as AttributeSchema;
+
+  // Validate nested `attributes.style` as an object; validate any style keys that also exist in schema.
+  const maybeStyle = (attrs as Record<string, unknown>).style;
+  if (maybeStyle != null) {
+    if (!isPlainObject(maybeStyle)) {
+      return fail(`style must be an object`, joinPath(path, 'style'));
+    }
+    for (const [styleKey, styleValue] of Object.entries(
+      maybeStyle as Record<string, unknown>,
+    )) {
+      const spec = schema?.[styleKey];
+      if (!spec) continue; // allow unknown style keys (free-form CSSProperties)
+      const res = validateAttributeValue(
+        pattern.pattern.type,
+        styleValue,
+        spec,
+        joinPath(joinPath(path, 'style'), styleKey),
+      );
+      if (!res.valid) return res;
+    }
+  }
+
+  for (const [attrName, attrValue] of Object.entries(attrs)) {
+    if (attrName === 'style') continue;
+    const attrSpec = schema?.[attrName];
+    if (!attrSpec) {
+      return fail(`Unknown attribute "${attrName}"`, joinPath(path, attrName));
+    }
+    const res = validateAttributeValue(
+      pattern.pattern.type,
+      attrValue,
+      attrSpec,
+      joinPath(path, attrName),
+    );
+    if (!res.valid) return res;
+  }
+
+  return ok();
+}
+
+function validateNodeDataByPatterns(
+  nodeData: NodeData<NodeDefaultAttribute>,
+  path: string,
+): AnalyseResultWithPath {
+  const normalizedType = normalizeTypeOrFallback(nodeData.type);
+  const pattern = getPatternByType(normalizedType) as unknown as
+    | PatternLike
+    | undefined;
+  if (!pattern) {
+    return fail(
+      `Unknown component type "${nodeData.type}"`,
+      joinPath(path, 'type'),
+    );
+  }
+
+  const attrRes = validateAttributesByPattern(
+    { ...nodeData, type: normalizedType },
+    pattern,
+    joinPath(path, 'attributes'),
+  );
+  if (!attrRes.valid) return attrRes;
+
+  const childrenRes = validateChildrenByPattern(
+    { ...nodeData, type: normalizedType },
+    pattern,
+    joinPath(path, 'children'),
+  );
+  if (!childrenRes.valid) return childrenRes;
+
+  return ok();
+}
+
+function validateAnyNodeByPatterns(
+  node: Node<NodeDefaultAttribute>,
+  path: string,
+): AnalyseResultWithPath {
+  if (
+    isNodeNullOrUndefined(node) ||
+    isNodeString(node) ||
+    isEmptyObject(node)
+  ) {
+    return ok();
+  }
+
+  if (isNodeArray(node)) {
+    const arr = node as unknown as Node<NodeDefaultAttribute>[];
+    for (let i = 0; i < arr.length; i++) {
+      const res = validateAnyNodeByPatterns(arr[i], `${path}[${i}]`);
+      if (!res.valid) return res;
+    }
+    return ok();
+  }
+
+  if (!isNodeDataLike(node)) {
+    return fail(`Invalid node shape`, path);
+  }
+
+  const selfRes = validateNodeDataByPatterns(node, path);
+  if (!selfRes.valid) return selfRes;
+
+  return validateAnyNodeByPatterns(
+    node.children as Node<NodeDefaultAttribute>,
+    joinPath(path, 'children'),
+  );
+}
+
+/**
+ * Validates a Node tree against the generated component patterns:
+ * - Enforces `pattern.children` including "never"
+ * - Validates `attributes` against `pattern.attributes` (+ custom `types`)
+ *
+ * Notes:
+ * - Null/undefined children are considered "no children" and are allowed even
+ *   when patterns expect some kind of children.
+ */
+export function analyseNodeByPatterns(
+  node: Node<NodeDefaultAttribute>,
+): AnalyseResultWithPath {
+  return validateAnyNodeByPatterns(node, 'root');
+}

package/src/utils/analyseNodeStructural.ts

@@ -0,0 +1,52 @@
+import type { Node, NodeData, NodeDefaultAttribute } from '../types/Node';
+import {
+  isEmptyObject,
+  isNodeArray,
+  isNodeNullOrUndefined,
+  isNodeString,
+} from './nodeGuards';
+
+export type AnalyseResult = {
+  valid: boolean;
+  message?: string;
+};
+
+/**
+ * Structural validation only:
+ * - Ensures the input is a valid Node union recursively (null/string/array/object)
+ * - Does NOT validate against component patterns.
+ */
+export function analyseNodeStructural(
+  node: Node<NodeDefaultAttribute>,
+): AnalyseResult {
+  if (isNodeNullOrUndefined(node)) {
+    return { valid: true, message: 'null or undefined is valid' };
+  }
+
+  if (isNodeString(node)) {
+    return { valid: true, message: 'string is valid' };
+  }
+
+  if (isNodeArray(node)) {
+    const nodeArray = node as unknown as Node[];
+    for (const value of nodeArray) {
+      const res = analyseNodeStructural(value as Node<NodeDefaultAttribute>);
+      if (!res.valid) return res;
+    }
+    return { valid: true, message: 'Array is valid' };
+  }
+
+  const recordData = node as NodeData;
+  if (isEmptyObject(recordData)) {
+    return { valid: true, message: 'empty object is valid' };
+  }
+
+  if (recordData.children) {
+    const res = analyseNodeStructural(
+      recordData.children as Node<NodeDefaultAttribute>,
+    );
+    if (!res.valid) return res;
+  }
+
+  return { valid: true, message: 'everything is structurally valid' };
+}