@routevn/creator-model 1.12.0 → 1.12.2

package/README.md

@@ -173,6 +173,40 @@ Computed definitions may use a simple `expr` or literal `value`, or ordered
 operator grammar, result types, concrete `variables.*`/`runtime.*` paths,
 declared variable references, and an acyclic computed dependency graph.
 
+Computed definitions may also store examples. Example inputs mirror the
+evaluation context, while calculated results remain derived and are not
+persisted:
+
+```js
+{
+  computed: {
+    expr: {
+      mul: [
+        {
+          div: [
+            { var: "variables.hp" },
+            { var: "variables.maxHp" },
+          ],
+        },
+        100,
+      ],
+    },
+    examples: [
+      {
+        id: "example-low-health",
+        name: "Low health",
+        input: {
+          variables: {
+            hp: 40,
+            maxHp: 80,
+          },
+        },
+      },
+    ],
+  },
+}
+```
+
 ## File Structure
 
 ```text
@@ -294,6 +328,10 @@ Current animation update tween properties support either:
 - `keyframes`
 - `auto: { duration, easing }`
 
+Transition animation `mask` accepts one mask object or a non-empty ordered
+array. Each mask may define a non-negative safe-integer `delay` in
+milliseconds.
+
 ## Current Scope
 
 Currently implemented command types:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routevn/creator-model",
-  "version": "1.12.0",
+  "version": "1.12.2",
   "private": false,
   "type": "module",
   "license": "MIT",

package/src/model.js

@@ -1930,6 +1930,7 @@ const validateMaskDefinition = ({ mask, path, errorFactory }) => {
         "softness",
         "invert",
         "sample",
+        "delay",
         "progress",
         "progressDuration",
         "progressEasing",
@@ -2108,6 +2109,16 @@ const validateMaskDefinition = ({ mask, path, errorFactory }) => {
     );
   }
 
+  if (
+    mask.delay !== undefined &&
+    (!Number.isSafeInteger(mask.delay) || mask.delay < 0)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.delay must be a non-negative safe integer when provided`,
+    );
+  }
+
   if (mask.progress !== undefined) {
     {
       const result = validateTweenProperty({
@@ -2171,6 +2182,30 @@ const validateMaskDefinition = ({ mask, path, errorFactory }) => {
   }
 };
 
+const validateAnimationMasks = ({ mask, path, errorFactory }) => {
+  if (!Array.isArray(mask)) {
+    return validateMaskDefinition({ mask, path, errorFactory });
+  }
+
+  if (mask.length === 0) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must be a non-empty array when provided`,
+    );
+  }
+
+  for (const [index, maskDefinition] of mask.entries()) {
+    const result = validateMaskDefinition({
+      mask: maskDefinition,
+      path: `${path}[${index}]`,
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+};
+
 const validateAnimationDefinition = ({ animation, path, errorFactory }) => {
   {
     const result = validateAllowedKeys({
@@ -2276,7 +2311,7 @@ const validateAnimationDefinition = ({ animation, path, errorFactory }) => {
 
   if (animation.mask !== undefined) {
     {
-      const result = validateMaskDefinition({
+      const result = validateAnimationMasks({
         mask: animation.mask,
         path: `${path}.mask`,
         errorFactory,
@@ -3754,6 +3789,99 @@ const validateComputedResultConfig = ({
   return VALID_RESULT;
 };
 
+const validateComputedExamples = ({ examples, path, errorFactory }) => {
+  if (!Array.isArray(examples)) {
+    return invalidFromErrorFactory(errorFactory, `${path} must be an array`);
+  }
+
+  const exampleIds = new Set();
+  for (const [index, example] of examples.entries()) {
+    const examplePath = `${path}[${index}]`;
+    {
+      const result = validateAllowedKeys({
+        value: example,
+        allowedKeys: ["id", "name", "input"],
+        path: examplePath,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    if (!isNonEmptyString(example.id)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${examplePath}.id must be a non-empty string`,
+      );
+    }
+    if (exampleIds.has(example.id)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${examplePath}.id must be unique within examples`,
+      );
+    }
+    exampleIds.add(example.id);
+
+    if (Object.hasOwn(example, "name") && !isNonEmptyString(example.name)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${examplePath}.name must be a non-empty string`,
+      );
+    }
+
+    if (!Object.hasOwn(example, "input")) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${examplePath}.input is required`,
+      );
+    }
+    if (
+      !isPlainObject(example.input) ||
+      ![Object.prototype, null].includes(Object.getPrototypeOf(example.input))
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${examplePath}.input must be an object`,
+      );
+    }
+    {
+      const result = validateAllowedKeys({
+        value: example.input,
+        allowedKeys: ["variables", "runtime"],
+        path: `${examplePath}.input`,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    for (const namespace of ["variables", "runtime"]) {
+      if (!Object.hasOwn(example.input, namespace)) {
+        continue;
+      }
+      const namespacePath = `${examplePath}.input.${namespace}`;
+      if (!isPlainObject(example.input[namespace])) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${namespacePath} must be an object`,
+        );
+      }
+      const result = validateComputedDataValue({
+        value: example.input[namespace],
+        path: namespacePath,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+  }
+
+  return VALID_RESULT;
+};
+
 const validateVariableComputedConfig = ({
   computed,
   variableType,
@@ -3766,11 +3894,22 @@ const validateVariableComputedConfig = ({
     return invalidFromErrorFactory(errorFactory, `${path} must be an object`);
   }
 
+  if (Object.hasOwn(computed, "examples")) {
+    const result = validateComputedExamples({
+      examples: computed.examples,
+      path: `${path}.examples`,
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
   if (Object.hasOwn(computed, "branches")) {
     {
       const result = validateAllowedKeys({
         value: computed,
-        allowedKeys: ["branches", "default"],
+        allowedKeys: ["branches", "default", "examples"],
         path,
         errorFactory,
       });
@@ -3846,6 +3985,7 @@ const validateVariableComputedConfig = ({
     errorFactory,
     variables,
     dependencies,
+    allowedKeys: ["expr", "value", "examples"],
   });
 };
 
@@ -8119,43 +8259,41 @@ const validateAnimationMaskImageReferences = ({
   details = {},
   errorFactory = createPreconditionValidationError,
 }) => {
-  if (
-    !isPlainObject(animation) ||
-    animation.type !== "transition" ||
-    !isPlainObject(animation.mask)
-  ) {
+  if (!isPlainObject(animation) || animation.type !== "transition") {
     return VALID_RESULT;
   }
 
-  const { mask } = animation;
+  const maskDefinitions = Array.isArray(animation.mask)
+    ? animation.mask.map((mask, index) => ({
+        mask,
+        path: `${path}.mask[${index}]`,
+        fieldPrefix: `mask[${index}].`,
+      }))
+    : isPlainObject(animation.mask)
+      ? [
+          {
+            mask: animation.mask,
+            path: `${path}.mask`,
+            fieldPrefix: "",
+          },
+        ]
+      : [];
 
-  if (mask.imageId !== undefined) {
-    const result = validateImageReference({
-      state,
-      imageId: mask.imageId,
-      path: `${path}.mask.imageId`,
-      details: {
-        ...details,
-        field: "imageId",
-        imageId: mask.imageId,
-      },
-      errorFactory,
-    });
-    if (!result.valid) {
-      return result;
+  for (const maskDefinition of maskDefinitions) {
+    const { mask, path: maskPath, fieldPrefix } = maskDefinition;
+    if (!isPlainObject(mask)) {
+      continue;
     }
-  }
 
-  if (Array.isArray(mask.imageIds)) {
-    for (const [index, imageId] of mask.imageIds.entries()) {
+    if (mask.imageId !== undefined) {
       const result = validateImageReference({
         state,
-        imageId,
-        path: `${path}.mask.imageIds[${index}]`,
+        imageId: mask.imageId,
+        path: `${maskPath}.imageId`,
         details: {
           ...details,
-          field: `imageIds[${index}]`,
-          imageId,
+          field: `${fieldPrefix}imageId`,
+          imageId: mask.imageId,
         },
         errorFactory,
       });
@@ -8163,27 +8301,46 @@ const validateAnimationMaskImageReferences = ({
         return result;
       }
     }
-  }
 
-  if (Array.isArray(mask.items)) {
-    for (const [index, item] of mask.items.entries()) {
-      if (item?.imageId === undefined) {
-        continue;
+    if (Array.isArray(mask.imageIds)) {
+      for (const [index, imageId] of mask.imageIds.entries()) {
+        const result = validateImageReference({
+          state,
+          imageId,
+          path: `${maskPath}.imageIds[${index}]`,
+          details: {
+            ...details,
+            field: `${fieldPrefix}imageIds[${index}]`,
+            imageId,
+          },
+          errorFactory,
+        });
+        if (!result.valid) {
+          return result;
+        }
       }
+    }
 
-      const result = validateImageReference({
-        state,
-        imageId: item.imageId,
-        path: `${path}.mask.items[${index}].imageId`,
-        details: {
-          ...details,
-          field: `items[${index}].imageId`,
+    if (Array.isArray(mask.items)) {
+      for (const [index, item] of mask.items.entries()) {
+        if (item?.imageId === undefined) {
+          continue;
+        }
+
+        const result = validateImageReference({
+          state,
           imageId: item.imageId,
-        },
-        errorFactory,
-      });
-      if (!result.valid) {
-        return result;
+          path: `${maskPath}.items[${index}].imageId`,
+          details: {
+            ...details,
+            field: `${fieldPrefix}items[${index}].imageId`,
+            imageId: item.imageId,
+          },
+          errorFactory,
+        });
+        if (!result.valid) {
+          return result;
+        }
       }
     }
   }