fix(model): allow system variable element bindings (#14)

Author: han4wluc

package.json

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

src/index.js

@@ -5,3 +5,9 @@ export {
   validatePayload,
   validateState,
 } from "./model.js";
+export {
+  SYSTEM_VARIABLE_GROUPS,
+  SYSTEM_VARIABLE_IDS,
+  getSystemVariableDefinitions,
+  isSystemVariableId,
+} from "./systemVariables.js";

src/model.js

@@ -15,6 +15,7 @@ import {
   isPlainObject,
   removeTreeNode,
 } from "./helpers.js";
+import { isSystemVariableId } from "./systemVariables.js";
 
 const COLLECTION_KEYS = [
   "scenes",
@@ -220,6 +221,15 @@ const invalidInvariant = (message, details = {}) =>
     details,
   });
 
+const isVariableReferenceTarget = (state, variableId) => {
+  if (isSystemVariableId(variableId)) {
+    return true;
+  }
+
+  const variable = state.variables.items[variableId];
+  return isPlainObject(variable) && variable.type !== "folder";
+};
+
 const toDomainErrorDetails = (publicError) => {
   const details = isPlainObject(publicError?.details)
     ? { ...publicError.details }
@@ -3899,8 +3909,7 @@ export const assertInvariants = ({ state }) => {
     elementId,
     targetId,
   }) => {
-    const variable = state.variables.items[targetId];
-    if (!isPlainObject(variable) || variable.type === "folder") {
+    if (!isVariableReferenceTarget(state, targetId)) {
       return invalidInvariant(
         `${ownerLabel} element variableId must reference an existing non-folder variable`,
         {
@@ -6511,8 +6520,7 @@ const validateVisualElementReferenceTargets = ({
   }
 
   if (data.variableId !== undefined) {
-    const variable = state.variables.items[data.variableId];
-    if (!isPlainObject(variable) || variable.type === "folder") {
+    if (!isVariableReferenceTarget(state, data.variableId)) {
       return invalidFromErrorFactory(
         errorFactory,
         `${ownerLabel} element variableId must reference an existing non-folder variable`,

src/systemVariables.js

@@ -0,0 +1,42 @@
+export const SYSTEM_VARIABLE_GROUPS = Object.freeze([
+  {
+    id: "routeEngine",
+    name: "Route Engine",
+    variables: Object.freeze([
+      {
+        id: "_skipUnseenText",
+        name: "Skip Unseen Text",
+        scope: "global-device",
+        type: "boolean",
+        default: false,
+        description:
+          "When enabled, skip mode can continue through lines the player has not viewed yet.",
+      },
+      {
+        id: "_dialogueTextSpeed",
+        name: "Dialogue Text Speed",
+        scope: "global-device",
+        type: "number",
+        default: 50,
+        description:
+          "Controls the default dialogue text speed stored for this device.",
+      },
+    ]),
+  },
+]);
+
+export const SYSTEM_VARIABLE_IDS = Object.freeze(
+  SYSTEM_VARIABLE_GROUPS.flatMap((group) =>
+    (group.variables || []).map((variable) => variable.id),
+  ),
+);
+
+const SYSTEM_VARIABLE_ID_SET = new Set(SYSTEM_VARIABLE_IDS);
+
+export const isSystemVariableId = (value) => {
+  return typeof value === "string" && SYSTEM_VARIABLE_ID_SET.has(value);
+};
+
+export const getSystemVariableDefinitions = () => {
+  return SYSTEM_VARIABLE_GROUPS.flatMap((group) => group.variables || []);
+};

tests/command-direct-coverage.test.js

@@ -72,7 +72,9 @@ const createCollectionState = ({
 };
 
 const withFontAndColorRefs = (state) => {
-  withFiles(state, [{ id: "file-font-ui", type: "font", mimeType: "font/ttf" }]);
+  withFiles(state, [
+    { id: "file-font-ui", type: "font", mimeType: "font/ttf" },
+  ]);
   state.fonts.items["font-ui"] = {
     id: "font-ui",
     type: "font",
@@ -1205,12 +1207,12 @@ const directCases = [
         state,
         command: {
           type: "file.create",
-        payload: {
-          fileId: "file-a",
-          data: {
-            mimeType: "image/png",
-            size: 128,
-            sha256: "file-a-sha256",
+          payload: {
+            fileId: "file-a",
+            data: {
+              mimeType: "image/png",
+              size: 128,
+              sha256: "file-a-sha256",
             },
           },
         },
@@ -1736,6 +1738,7 @@ const directCases = [
               rotation: 0,
               text: "More",
               textStyleId: "text-style-ui",
+              variableId: "_dialogueTextSpeed",
             },
           },
         },
@@ -1756,6 +1759,7 @@ const directCases = [
         rotation: 0,
         text: "More",
         textStyleId: "text-style-ui",
+        variableId: "_dialogueTextSpeed",
       });
     },
     runNegative: () => {
@@ -1803,16 +1807,16 @@ const directCases = [
             layoutId: "layout-dialogue",
             elementId: "text-a",
             data: {
-              opacity: 0.5,
+              variableId: "_dialogueTextSpeed",
             },
           },
         },
       });
 
       expect(
         result.state.layouts.items["layout-dialogue"].elements.items["text-a"]
-          .opacity,
-      ).toBe(0.5);
+          .variableId,
+      ).toBe("_dialogueTextSpeed");
     },
     runNegative: () => {
       expectValidation(() =>
@@ -1931,6 +1935,7 @@ const directCases = [
               rotation: 0,
               text: "More",
               textStyleId: "text-style-ui",
+              variableId: "_dialogueTextSpeed",
             },
           },
         },
@@ -1951,6 +1956,7 @@ const directCases = [
         rotation: 0,
         text: "More",
         textStyleId: "text-style-ui",
+        variableId: "_dialogueTextSpeed",
       });
     },
     runNegative: () => {
@@ -1998,16 +2004,16 @@ const directCases = [
             controlId: "control-default",
             elementId: "text-a",
             data: {
-              opacity: 0.5,
+              variableId: "_dialogueTextSpeed",
             },
           },
         },
       });
 
       expect(
         result.state.controls.items["control-default"].elements.items["text-a"]
-          .opacity,
-      ).toBe(0.5);
+          .variableId,
+      ).toBe("_dialogueTextSpeed");
     },
     runNegative: () => {
       expectValidation(() =>

tests/model-api.test.js

@@ -3,6 +3,8 @@ import { expect, test } from "vitest";
 import {
   SCHEMA_VERSION,
   processCommand,
+  SYSTEM_VARIABLE_GROUPS,
+  SYSTEM_VARIABLE_IDS,
   validateAgainstState,
   validatePayload,
   validateState,
@@ -25,6 +27,14 @@ test("public api exports functions only", () => {
   expect(typeof processCommand).toBe("function");
 });
 
+test("system variable ids stay aligned with the registry", () => {
+  const registryIds = SYSTEM_VARIABLE_GROUPS.flatMap((group) =>
+    (group.variables || []).map((variable) => variable.id),
+  );
+
+  expect(SYSTEM_VARIABLE_IDS).toEqual(registryIds);
+});
+
 test("validation functions return valid results instead of throwing", () => {
   expect(
     validatePayload({
@@ -561,6 +571,53 @@ test("validateState accepts layout elements with revealEffect", () => {
   });
 });
 
+test("validateState accepts layout slider variableId refs to system variables", () => {
+  const state = createEmptyTestState();
+
+  state.layouts.items["layout-ui"] = {
+    id: "layout-ui",
+    type: "layout",
+    name: "UI",
+    layoutType: "normal",
+    elements: {
+      items: {
+        "slider-1": {
+          id: "slider-1",
+          type: "slider",
+          name: "Slider",
+          x: 0,
+          y: 0,
+          width: 400,
+          height: 20,
+          anchorX: 0,
+          anchorY: 0,
+          scaleX: 1,
+          scaleY: 1,
+          rotation: 0,
+          min: 0,
+          max: 100,
+          step: 1,
+          variableId: "_dialogueTextSpeed",
+        },
+      },
+      tree: [
+        {
+          id: "slider-1",
+          children: [],
+        },
+      ],
+    },
+  };
+  state.layouts.tree.push({
+    id: "layout-ui",
+    children: [],
+  });
+
+  expect(validateState({ state })).toEqual({
+    valid: true,
+  });
+});
+
 test("validateState rejects legacy layout element style overrides", () => {
   const state = createEmptyTestState();