@superblocksteam/util 1.0.0 → 1.0.2

package/dist/generate-component-types.js

@@ -12,7 +12,7 @@ const indent = (str, spaces) => {
 function renderInputTypeAsTS(name, type, trailingChars, indentSpaces) {
     let { tsType } = data_types_1.dataTypeDefinions[type];
     if (["number", "string"].includes(type)) {
-        tsType += "| null";
+        tsType += " | null";
     }
     return indent(`${name}: ${tsType}${trailingChars}`, indentSpaces);
 }

package/dist/identifiers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Suggest an identifier based on a label, e.g. `My Component` -> `myComponent`.
+ * @param label The label to suggest an identifier for.
+ * @param capitalizeFirst Whether to capitalize the first letter of the identifier.
+ */
+export declare function suggestIdentifier(label: string, capitalizeFirst?: boolean): string;
+export declare function isValidIdentifier(str: string): boolean;
+export declare function isReservedPropertyName(str: string): boolean;

package/dist/identifiers.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isReservedPropertyName = exports.isValidIdentifier = exports.suggestIdentifier = void 0;
+// convert a string to upper camel case, e.g. "123 & this is my component, foo-bar" -> "123ThisIsMyComponentFooBar"
+function wordsToUpperCamelCase(str) {
+    return str
+        .split(/[^A-Za-z0-9_]+/)
+        .filter(Boolean)
+        .map((word) => word[0].toUpperCase() + word.slice(1))
+        .join("");
+}
+const digits = "Zero One Two Three Four Five Six Seven Eight Nine".split(" ");
+// convert digits to words, e.g. "123" -> "OneTwoThree"
+function digitsToWords(str) {
+    return str.replace(/\d/g, (char) => { var _a; return (_a = digits[parseInt(char, 10)]) !== null && _a !== void 0 ? _a : char; });
+}
+/**
+ * Suggest an identifier based on a label, e.g. `My Component` -> `myComponent`.
+ * @param label The label to suggest an identifier for.
+ * @param capitalizeFirst Whether to capitalize the first letter of the identifier.
+ */
+function suggestIdentifier(label, capitalizeFirst = false) {
+    const upperCamelCase = wordsToUpperCamelCase(label)
+        // convert any digits at the start of the string to words as these are not valid in identifiers
+        .replace(/^\d+/, digitsToWords);
+    if (capitalizeFirst) {
+        return upperCamelCase;
+    }
+    else {
+        return upperCamelCase[0].toLowerCase() + upperCamelCase.slice(1);
+    }
+}
+exports.suggestIdentifier = suggestIdentifier;
+const IdentifierRegex = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function isValidIdentifier(str) {
+    return IdentifierRegex.test(str);
+}
+exports.isValidIdentifier = isValidIdentifier;
+const reservedPropertyNames = new Set([
+    "ENTITY_TYPE",
+    "bindingPaths",
+    "bottomRow",
+    "dynamicBindingPathList",
+    "dynamicTriggerPathList",
+    "gridColumns",
+    "gridRows",
+    "height",
+    "isLoading",
+    "isVisible",
+    "leftColumn",
+    "parentId",
+    "rightColumn",
+    "snapColumns",
+    "snapRows",
+    "top",
+    "topRow",
+    "type",
+    "widgetId",
+    "widgetLastChange",
+    "widgetName",
+    "width",
+]);
+function isReservedPropertyName(str) {
+    return (reservedPropertyNames.has(str) ||
+        // also treat any property name starting with "default_" as reserved since we use this prefix for default properties
+        str.startsWith("default_"));
+}
+exports.isReservedPropertyName = isReservedPropertyName;

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export * from "./login";
 export * from "./resource-configs";
 export * from "./data-types";
 export * from "./types";
+export * from "./identifiers";

package/dist/index.js

@@ -9,3 +9,4 @@ tslib_1.__exportStar(require("./login"), exports);
 tslib_1.__exportStar(require("./resource-configs"), exports);
 tslib_1.__exportStar(require("./data-types"), exports);
 tslib_1.__exportStar(require("./types"), exports);
+tslib_1.__exportStar(require("./identifiers"), exports);

package/dist/validation.js

@@ -4,7 +4,45 @@ exports.validateCustomComponents = void 0;
 const tslib_1 = require("tslib");
 const ajv_1 = tslib_1.__importDefault(require("ajv"));
 const better_ajv_errors_1 = tslib_1.__importDefault(require("better-ajv-errors"));
+const identifiers_1 = require("./identifiers");
 const ajv = new ajv_1.default();
+ajv.addKeyword({
+    keyword: "stringFormat",
+    compile: (schema) => {
+        let validateFunc;
+        // schema is the value assigned to stringFormat in the schema
+        if (schema === "identifier") {
+            validateFunc = (data) => {
+                if (typeof data != "string")
+                    return false;
+                if (!(0, identifiers_1.isValidIdentifier)(data)) {
+                    validateFunc.errors = [
+                        {
+                            keyword: "format",
+                            message: "must be a valid identifier starting with a-z or underscore and containing only a-z, 0-9, and underscores",
+                        },
+                    ];
+                    return false;
+                }
+                if ((0, identifiers_1.isReservedPropertyName)(data)) {
+                    validateFunc.errors = [
+                        {
+                            keyword: "format",
+                            message: "must not match a reserved property path (see https://docs.superblocks.com/applications/custom-components/faq#what-is-a-reserved-property)",
+                        },
+                    ];
+                    return false;
+                }
+                return true;
+            };
+        }
+        else {
+            throw new Error(`Unknown stringFormat: ${schema}`);
+        }
+        return validateFunc;
+    },
+    errors: true,
+});
 const componentSchema = {
     type: "object",
     properties: {
@@ -46,7 +84,7 @@ const componentSchema = {
     definitions: {
         Property: {
             properties: {
-                path: { type: "string" },
+                path: { $ref: "#/definitions/Identifier" },
                 dataType: { enum: ["number", "boolean", "string", "any"] },
                 propertiesPanelDisplay: {
                     type: "object",
@@ -84,12 +122,16 @@ const componentSchema = {
         EventHandler: {
             properties: {
                 label: { type: "string" },
-                path: { type: "string" },
+                path: { $ref: "#/definitions/Identifier" },
             },
             type: "object",
             additionalProperties: false,
             required: ["label", "path"],
         },
+        Identifier: {
+            type: "string",
+            stringFormat: "identifier",
+        },
     },
 };
 const validate = ajv.compile(componentSchema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/util",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "main": "dist/index.js",
   "homepage": "https://www.superblocks.com",
   "scripts": {
@@ -23,7 +23,7 @@
     "@types/mime-types": "^2.1.1",
     "@typescript-eslint/eslint-plugin": "^5.60.1",
     "@typescript-eslint/parser": "^5.60.1",
-    "eslint": "^8.45.0",
+    "eslint": "^8.48.0",
     "eslint-plugin-unicorn": "^47.0.0",
     "prettier": "^2.8.8",
     "typescript": "^5.1.3"

package/src/generate-component-types.ts

@@ -18,7 +18,7 @@ function renderInputTypeAsTS(
 ) {
   let { tsType } = dataTypeDefinions[type];
   if (["number", "string"].includes(type)) {
-    tsType += "| null";
+    tsType += " | null";
   }
   return indent(`${name}: ${tsType}${trailingChars}`, indentSpaces);
 }

package/src/identifiers.ts

@@ -0,0 +1,70 @@
+// convert a string to upper camel case, e.g. "123 & this is my component, foo-bar" -> "123ThisIsMyComponentFooBar"
+function wordsToUpperCamelCase(str: string) {
+  return str
+    .split(/[^A-Za-z0-9_]+/)
+    .filter(Boolean)
+    .map((word) => word[0].toUpperCase() + word.slice(1))
+    .join("");
+}
+
+const digits = "Zero One Two Three Four Five Six Seven Eight Nine".split(" ");
+
+// convert digits to words, e.g. "123" -> "OneTwoThree"
+function digitsToWords(str: string) {
+  return str.replace(/\d/g, (char) => digits[parseInt(char, 10)] ?? char);
+}
+
+/**
+ * Suggest an identifier based on a label, e.g. `My Component` -> `myComponent`.
+ * @param label The label to suggest an identifier for.
+ * @param capitalizeFirst Whether to capitalize the first letter of the identifier.
+ */
+export function suggestIdentifier(label: string, capitalizeFirst = false) {
+  const upperCamelCase = wordsToUpperCamelCase(label)
+    // convert any digits at the start of the string to words as these are not valid in identifiers
+    .replace(/^\d+/, digitsToWords);
+  if (capitalizeFirst) {
+    return upperCamelCase;
+  } else {
+    return upperCamelCase[0].toLowerCase() + upperCamelCase.slice(1);
+  }
+}
+
+const IdentifierRegex = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+export function isValidIdentifier(str: string) {
+  return IdentifierRegex.test(str);
+}
+
+const reservedPropertyNames = new Set<string>([
+  "ENTITY_TYPE",
+  "bindingPaths",
+  "bottomRow",
+  "dynamicBindingPathList",
+  "dynamicTriggerPathList",
+  "gridColumns",
+  "gridRows",
+  "height",
+  "isLoading",
+  "isVisible",
+  "leftColumn",
+  "parentId",
+  "rightColumn",
+  "snapColumns",
+  "snapRows",
+  "top",
+  "topRow",
+  "type",
+  "widgetId",
+  "widgetLastChange",
+  "widgetName",
+  "width",
+]);
+
+export function isReservedPropertyName(str: string) {
+  return (
+    reservedPropertyNames.has(str) ||
+    // also treat any property name starting with "default_" as reserved since we use this prefix for default properties
+    str.startsWith("default_")
+  );
+}

package/src/index.ts

@@ -6,3 +6,4 @@ export * from "./login";
 export * from "./resource-configs";
 export * from "./data-types";
 export * from "./types";
+export * from "./identifiers";

package/src/validation.ts

@@ -1,8 +1,48 @@
 import Ajv, { Schema } from "ajv";
+import { DataValidateFunction } from "ajv/dist/types";
 import betterAjvErrors from "better-ajv-errors";
+import { isReservedPropertyName, isValidIdentifier } from "./identifiers";
 
 const ajv = new Ajv();
 
+ajv.addKeyword({
+  keyword: "stringFormat",
+  compile: (schema: any) => {
+    let validateFunc: DataValidateFunction;
+    // schema is the value assigned to stringFormat in the schema
+    if (schema === "identifier") {
+      validateFunc = (data: any) => {
+        if (typeof data != "string") return false;
+        if (!isValidIdentifier(data)) {
+          validateFunc.errors = [
+            {
+              keyword: "format",
+              message:
+                "must be a valid identifier starting with a-z or underscore and containing only a-z, 0-9, and underscores",
+            },
+          ];
+          return false;
+        }
+        if (isReservedPropertyName(data)) {
+          validateFunc.errors = [
+            {
+              keyword: "format",
+              message:
+                "must not match a reserved property path (see https://docs.superblocks.com/applications/custom-components/faq#what-is-a-reserved-property)",
+            },
+          ];
+          return false;
+        }
+        return true;
+      };
+    } else {
+      throw new Error(`Unknown stringFormat: ${schema}`);
+    }
+    return validateFunc;
+  },
+  errors: true,
+});
+
 const componentSchema: Schema = {
   type: "object",
   properties: {
@@ -44,7 +84,7 @@ const componentSchema: Schema = {
   definitions: {
     Property: {
       properties: {
-        path: { type: "string" },
+        path: { $ref: "#/definitions/Identifier" },
         dataType: { enum: ["number", "boolean", "string", "any"] },
         propertiesPanelDisplay: {
           type: "object",
@@ -82,12 +122,16 @@ const componentSchema: Schema = {
     EventHandler: {
       properties: {
         label: { type: "string" },
-        path: { type: "string" },
+        path: { $ref: "#/definitions/Identifier" },
       },
       type: "object",
       additionalProperties: false,
       required: ["label", "path"],
     },
+    Identifier: {
+      type: "string",
+      stringFormat: "identifier",
+    },
   },
 };