@superblocksteam/util 0.0.22 → 1.0.0

package/dist/component-configs.js

@@ -15,7 +15,8 @@ const compileTypeScript = (inputFilePath, outputDir) => {
         try {
             const tscPath = require.resolve("typescript/bin/tsc");
             if (tscPath) {
-                (0, child_process_1.execFile)(tscPath, [
+                (0, child_process_1.execFile)("node", [
+                    tscPath,
                     node_path_1.default.resolve(inputFilePath),
                     "--outDir",
                     outputDir,
@@ -59,9 +60,13 @@ async function getFolderPaths() {
             withFileTypes: true,
         });
         // filter out any non-directory items
-        const directories = folderPaths.filter((dirent) => dirent.isDirectory());
+        const directories = folderPaths.filter((dirent) => dirent.isDirectory() ||
+            (dirent.isSymbolicLink() &&
+                fs
+                    .statSync(node_path_1.default.join(constants_1.CUSTOM_COMPONENTS_PATH, dirent.name))
+                    .isDirectory()));
         // map each directory to its path
-        const folderPathsArray = directories.map((dirent) => node_path_1.default.resolve(`${constants_1.CUSTOM_COMPONENTS_PATH}/${dirent.name}`));
+        const folderPathsArray = directories.map((dirent) => node_path_1.default.join(constants_1.CUSTOM_COMPONENTS_PATH, dirent.name));
         return folderPathsArray;
     }
     catch {
@@ -72,9 +77,10 @@ async function getComponentConfigs(generateTypesFiles) {
     const folderPaths = await getFolderPaths();
     let hasError = false;
     const promiseConfigFiles = folderPaths.map(async (ccpath) => {
+        const absPath = node_path_1.default.resolve(ccpath);
         try {
-            const config = await fs.readJSON(`${ccpath}/config.json`);
-            console.log(`Found component in ${ccpath}`);
+            const config = await fs.readJSON(`${absPath}/config.json`);
+            console.log(`Found component in ${absPath}`);
             return { ccpath, config };
         }
         catch (e) {
@@ -91,6 +97,7 @@ async function getComponentConfigs(generateTypesFiles) {
             const outputDirectory = node_path_1.default.resolve(`${node_os_1.default.tmpdir()}/superblocks/${ccpath}/config.timestamp-${Date.now()}-${Math.random()
                 .toString(16)
                 .slice(2)}`);
+            await fs.ensureDir(outputDirectory);
             await compileTypeScript(fileName, outputDirectory);
             console.log(`Typescript compiled to ${ccpath}`);
             const config = (await Promise.resolve(`${outputDirectory + "/config.js"}`).then(s => tslib_1.__importStar(require(s)))).default;

package/dist/constants.d.ts

@@ -7,3 +7,7 @@ export declare const ERROR_FILE_ACCESS = "FileAccessError";
 export declare class FileAccessError extends Error {
     constructor(message: string);
 }
+export declare const ERROR_FILE_NOT_FOUND = "FileNotFoundError";
+export declare class NotFoundError extends Error {
+    constructor(message: string);
+}

package/dist/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FileAccessError = exports.ERROR_FILE_ACCESS = exports.CUSTOM_COMPONENTS_PATH = exports.ROOT_CONFIG_RELATIVE_PATH = exports.RESOURCE_CONFIG_PATH = exports.TOKEN_CONFIG_PATH = exports.SUPERBLOCKS_HOME_FOLDER_NAME = void 0;
+exports.NotFoundError = exports.ERROR_FILE_NOT_FOUND = exports.FileAccessError = exports.ERROR_FILE_ACCESS = exports.CUSTOM_COMPONENTS_PATH = exports.ROOT_CONFIG_RELATIVE_PATH = exports.RESOURCE_CONFIG_PATH = exports.TOKEN_CONFIG_PATH = exports.SUPERBLOCKS_HOME_FOLDER_NAME = void 0;
 exports.SUPERBLOCKS_HOME_FOLDER_NAME = ".superblocks";
 exports.TOKEN_CONFIG_PATH = ".superblocks/auth.json";
 exports.RESOURCE_CONFIG_PATH = ".superblocks/superblocks.json";
@@ -27,3 +27,11 @@ class FileAccessError extends Error {
     }
 }
 exports.FileAccessError = FileAccessError;
+exports.ERROR_FILE_NOT_FOUND = "FileNotFoundError";
+class NotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = exports.ERROR_FILE_NOT_FOUND;
+    }
+}
+exports.NotFoundError = NotFoundError;

package/dist/generate-component-types.js

@@ -10,31 +10,37 @@ const indent = (str, spaces) => {
         .join("\n");
 };
 function renderInputTypeAsTS(name, type, trailingChars, indentSpaces) {
-    return indent(`${name}: ${data_types_1.dataTypeDefinions[type].tsType}${trailingChars}`, indentSpaces);
+    let { tsType } = data_types_1.dataTypeDefinions[type];
+    if (["number", "string"].includes(type)) {
+        tsType += "| null";
+    }
+    return indent(`${name}: ${tsType}${trailingChars}`, indentSpaces);
 }
 function generateComponentTypesFile(config) {
     var _a, _b;
     const properties = (_a = config.properties) !== null && _a !== void 0 ? _a : [];
     const eventHandlers = (_b = config.events) !== null && _b !== void 0 ? _b : [];
-    return `// WARNING: This file is automatically generated and managed by Superblocks CLI and should not be edited manually.
+    return `// GENERATED CODE -- DO NOT EDIT!
+//
+// This file is automatically generated by the Superblocks CLI
 // Use the \`superblocks components watch\` command to regenerate this file from its source in config.ts
 
 // All properties of your component are defined here.
 // These are the properties which are surfaced in the Superblocks properties panel
 // and can be referenced throughout your Superblocks Application
-export interface Props {
+export type Props = {
 ${properties
         .map((v) => renderInputTypeAsTS(v.path, v.dataType, ";", 2) + "\n")
-        .join("")}}
+        .join("")}};
 
-export interface EventTriggers {
+export type EventTriggers = {
   // Call the subsequent function(s) to trigger event(s) in Superblocks from your component.
   // These events can be wired up to event handlers in your Superblocks App
 ${eventHandlers.length === 0
         ? "  // Note: no event handlers defined\n"
         : eventHandlers
             .map((v) => indent(v.path, 2) + ": () => void;" + "\n")
-            .join("")}}
+            .join("")}};
 `;
 }
 exports.generateComponentTypesFile = generateComponentTypesFile;

package/dist/resource-configs.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getSuperblocksResourceConfigIfExists = exports.getSuperblocksBackendConfigJson = exports.getSuperblocksApplicationConfigJson = exports.getSuperblocksMonorepoConfigJson = void 0;
 const tslib_1 = require("tslib");
+const path_1 = tslib_1.__importDefault(require("path"));
 const fs = tslib_1.__importStar(require("fs-extra"));
 const constants_1 = require("./constants");
 /**
@@ -9,27 +10,32 @@ const constants_1 = require("./constants");
  * @param checkParentDir Whether to recursively check the parent directory for a Superblocks config file
  */
 async function getSuperblocksMonorepoConfigJson(checkParentDir = false, pathPrefix = "") {
+    const absolutePath = path_1.default.resolve(pathPrefix);
+    let hasReachedFilesystemRoot = false;
+    try {
+        hasReachedFilesystemRoot = path_1.default.parse(absolutePath).root == absolutePath;
+    }
+    catch {
+        throw new Error("Could not parse path " + absolutePath);
+    }
     let superblocksConfig;
-    if (pathPrefix && !fs.existsSync(pathPrefix)) {
+    if ((pathPrefix && !fs.existsSync(absolutePath)) ||
+        hasReachedFilesystemRoot) {
         throw new Error("No Superblocks config file found in current directory hierarchy " +
             pathPrefix);
     }
+    const attemptedPath = path_1.default.join(absolutePath, constants_1.RESOURCE_CONFIG_PATH);
     try {
-        superblocksConfig = await fs.readJSON(pathPrefix + constants_1.RESOURCE_CONFIG_PATH);
+        superblocksConfig = await fs.readJSON(attemptedPath);
         if (superblocksConfig.configType !== "ROOT") {
             throw new Error("Not the root Superblocks config file");
         }
-        return [
-            superblocksConfig,
-            pathPrefix + constants_1.RESOURCE_CONFIG_PATH,
-        ];
+        return [superblocksConfig, attemptedPath];
     }
     catch {
         if (!checkParentDir) {
             // no superblocks config file found
-            throw new Error("No Superblocks config file found in current directory " +
-                pathPrefix +
-                constants_1.RESOURCE_CONFIG_PATH);
+            throw new Error("No Superblocks config file found in current directory " + attemptedPath);
         }
         return getSuperblocksMonorepoConfigJson(true, "../" + pathPrefix);
     }

package/dist/types.d.ts

@@ -1,11 +1,13 @@
 /// <reference types="node" />
 import { type UUID } from "node:crypto";
 import { type DataType } from "./data-types";
-interface PropertiesPanelDisplay {
+interface PropertiesPanelDisplay<T extends DataType> {
     /**
      * Determines what form item type is shown in the Superblocks properties panel.
+     *
+     * Only booleans are allowed to use the "switch" control
      */
-    controlType: "text" | "js-expr" | "switch";
+    controlType: T extends "boolean" ? "text" | "js-expr" | "switch" : "text" | "js-expr";
     /**
      * Determines form item label in the Superblocks properties panel.
      */
@@ -18,18 +20,39 @@ interface PropertiesPanelDisplay {
     /**
      * This shows up in the popover as a user types into the properties panel.
      * This is a documentation field that helps users understand what type of data is accepted
-     * by this property.
+     * by this property. You should give a specific example, not a generic type
+     *
+     * @example {
+     *   label: "My Label",
+     *   value: "myValue"
+     * }
      */
     exampleData?: string;
+    /**
+     * This shows up in the popover as a user types into the properties panel.
+     * This is a documentation field that helps users understand what type of data is accepted
+     * by this property. Typescript notation is recommended.
+     *
+     * @example "Array<{ label: string; value: string; }>"
+     */
+    expectedType?: string;
+    /**
+     * The default value should match the dataType of the property.
+     *
+     * When dataType is "any", you must provide a string default value.
+     * Your string will be interpreted based on the controlType, so if you have controlType "js-expr",
+     * you should provide a string that is a valid javascript expression including quotations marks.
+     */
+    defaultValue?: T extends "number" ? number : T extends "boolean" ? boolean : string;
 }
-export interface Property {
+export interface PropertyForData<T extends DataType> {
     path: string;
-    dataType: DataType;
+    dataType: T;
     /**
      * The presence of this object determines whether or not this property
      * shows up in the Superblocks properties panel.
      **/
-    propertiesPanelDisplay?: PropertiesPanelDisplay;
+    propertiesPanelDisplay?: PropertiesPanelDisplay<T>;
     /**
      * A description of this property. This is used in the Superblocks properties panel
      * as well as in the custom component's autocomplete.
@@ -48,6 +71,7 @@ export interface Property {
      **/
     isExternallySettable?: boolean;
 }
+export type Property = PropertyForData<"string"> | PropertyForData<"number"> | PropertyForData<"boolean"> | PropertyForData<"any">;
 export interface ComponentConfig {
     id: UUID;
     /**
@@ -62,7 +86,7 @@ export interface ComponentConfig {
      * @example "components/myComponent/component.tsx"
      */
     componentPath: string;
-    properties: Property[];
+    properties: Array<PropertyForData<"string"> | PropertyForData<"number"> | PropertyForData<"boolean"> | PropertyForData<"any">>;
     /**
      * @example [{
      *  label: "On Click",
@@ -73,5 +97,9 @@ export interface ComponentConfig {
         label: string;
         path: string;
     }>;
+    gridDimensions?: {
+        initialColumns: number;
+        initialRows: number;
+    };
 }
 export {};

package/dist/validation.js

@@ -24,6 +24,15 @@ const componentSchema = {
                 $ref: "#/definitions/EventHandler",
             },
         },
+        gridDimensions: {
+            type: "object",
+            properties: {
+                initialColumns: { type: "number" },
+                initialRows: { type: "number" },
+            },
+            additionalProperties: false,
+            required: ["initialColumns", "initialRows"],
+        },
     },
     required: [
         "id",
@@ -44,9 +53,22 @@ const componentSchema = {
                     properties: {
                         label: { type: "string" },
                         controlType: { enum: ["text", "js-expr", "switch"] },
-                        defaultValue: { type: "string" },
+                        defaultValue: {
+                            oneOf: [
+                                {
+                                    type: "string",
+                                },
+                                {
+                                    type: "boolean",
+                                },
+                                {
+                                    type: "number",
+                                },
+                            ],
+                        },
                         placeholder: { type: "string" },
                         exampleData: { type: "string" },
+                        expectedType: { type: "string" },
                     },
                     required: ["controlType", "label"],
                     additionalProperties: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/util",
-  "version": "0.0.22",
+  "version": "1.0.0",
   "main": "dist/index.js",
   "homepage": "https://www.superblocks.com",
   "scripts": {
@@ -9,7 +9,8 @@
     "clean": "npm run clean:build && rm -rf node_modules",
     "clean:build": "tsc --build --clean && rm -rf dist tsconfig.tsbuildinfo",
     "lint": "eslint . --ext .ts --config .eslintrc.json",
-    "lint:fix": "eslint . --ext .ts --config .eslintrc.json --fix"
+    "lint:fix": "eslint . --ext .ts --config .eslintrc.json --fix",
+    "typecheck": "tsc --noEmit"
   },
   "license": "Superblocks Community Software License",
   "description": "",

package/src/component-configs.ts

@@ -13,8 +13,9 @@ const compileTypeScript = (inputFilePath: string, outputDir: string) => {
       const tscPath = require.resolve("typescript/bin/tsc");
       if (tscPath) {
         execFile(
-          tscPath,
+          "node",
           [
+            tscPath,
             path.resolve(inputFilePath),
             "--outDir",
             outputDir,
@@ -64,10 +65,17 @@ async function getFolderPaths() {
       withFileTypes: true,
     });
     // filter out any non-directory items
-    const directories = folderPaths.filter((dirent) => dirent.isDirectory());
+    const directories = folderPaths.filter(
+      (dirent) =>
+        dirent.isDirectory() ||
+        (dirent.isSymbolicLink() &&
+          fs
+            .statSync(path.join(CUSTOM_COMPONENTS_PATH, dirent.name))
+            .isDirectory())
+    );
     // map each directory to its path
     const folderPathsArray = directories.map((dirent) =>
-      path.resolve(`${CUSTOM_COMPONENTS_PATH}/${dirent.name}`)
+      path.join(CUSTOM_COMPONENTS_PATH, dirent.name)
     );
     return folderPathsArray;
   } catch {
@@ -86,9 +94,10 @@ export async function getComponentConfigs(
   const folderPaths = await getFolderPaths();
   let hasError = false;
   const promiseConfigFiles = folderPaths.map(async (ccpath) => {
+    const absPath = path.resolve(ccpath);
     try {
-      const config = await fs.readJSON(`${ccpath}/config.json`);
-      console.log(`Found component in ${ccpath}`);
+      const config = await fs.readJSON(`${absPath}/config.json`);
+      console.log(`Found component in ${absPath}`);
       return { ccpath, config };
     } catch (e: any) {
       // Noop because there is a fallback
@@ -107,6 +116,7 @@ export async function getComponentConfigs(
           .toString(16)
           .slice(2)}`
       );
+      await fs.ensureDir(outputDirectory);
       await compileTypeScript(fileName, outputDirectory);
       console.log(`Typescript compiled to ${ccpath}`);
       const config = (await import(outputDirectory + "/config.js")).default;

package/src/constants.ts

@@ -26,3 +26,11 @@ export class FileAccessError extends Error {
     this.name = ERROR_FILE_ACCESS;
   }
 }
+
+export const ERROR_FILE_NOT_FOUND = "FileNotFoundError";
+export class NotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = ERROR_FILE_NOT_FOUND;
+  }
+}

package/src/generate-component-types.ts

@@ -16,27 +16,30 @@ function renderInputTypeAsTS(
   trailingChars: string,
   indentSpaces: number
 ) {
-  return indent(
-    `${name}: ${dataTypeDefinions[type].tsType}${trailingChars}`,
-    indentSpaces
-  );
+  let { tsType } = dataTypeDefinions[type];
+  if (["number", "string"].includes(type)) {
+    tsType += "| null";
+  }
+  return indent(`${name}: ${tsType}${trailingChars}`, indentSpaces);
 }
 
 export function generateComponentTypesFile(config: ComponentConfig) {
   const properties = config.properties ?? [];
   const eventHandlers = config.events ?? [];
-  return `// WARNING: This file is automatically generated and managed by Superblocks CLI and should not be edited manually.
+  return `// GENERATED CODE -- DO NOT EDIT!
+//
+// This file is automatically generated by the Superblocks CLI
 // Use the \`superblocks components watch\` command to regenerate this file from its source in config.ts
 
 // All properties of your component are defined here.
 // These are the properties which are surfaced in the Superblocks properties panel
 // and can be referenced throughout your Superblocks Application
-export interface Props {
+export type Props = {
 ${properties
   .map((v) => renderInputTypeAsTS(v.path, v.dataType, ";", 2) + "\n")
-  .join("")}}
+  .join("")}};
 
-export interface EventTriggers {
+export type EventTriggers = {
   // Call the subsequent function(s) to trigger event(s) in Superblocks from your component.
   // These events can be wired up to event handlers in your Superblocks App
 ${
@@ -45,6 +48,6 @@ ${
     : eventHandlers
         .map((v: any) => indent(v.path, 2) + ": () => void;" + "\n")
         .join("")
-}}
+}};
 `;
 }

package/src/resource-configs.ts

@@ -1,3 +1,4 @@
+import path from "path";
 import * as fs from "fs-extra";
 import { RESOURCE_CONFIG_PATH } from "./constants";
 
@@ -45,30 +46,38 @@ export async function getSuperblocksMonorepoConfigJson(
   checkParentDir = false,
   pathPrefix = ""
 ): Promise<[SuperblocksMonorepoConfig, string]> {
+  const absolutePath = path.resolve(pathPrefix);
+
+  let hasReachedFilesystemRoot = false;
+  try {
+    hasReachedFilesystemRoot = path.parse(absolutePath).root == absolutePath;
+  } catch {
+    throw new Error("Could not parse path " + absolutePath);
+  }
+
   let superblocksConfig;
-  if (pathPrefix && !fs.existsSync(pathPrefix)) {
+  if (
+    (pathPrefix && !fs.existsSync(absolutePath)) ||
+    hasReachedFilesystemRoot
+  ) {
     throw new Error(
       "No Superblocks config file found in current directory hierarchy " +
         pathPrefix
     );
   }
 
+  const attemptedPath = path.join(absolutePath, RESOURCE_CONFIG_PATH);
   try {
-    superblocksConfig = await fs.readJSON(pathPrefix + RESOURCE_CONFIG_PATH);
+    superblocksConfig = await fs.readJSON(attemptedPath);
     if (superblocksConfig.configType !== "ROOT") {
       throw new Error("Not the root Superblocks config file");
     }
-    return [
-      superblocksConfig as SuperblocksMonorepoConfig,
-      pathPrefix + RESOURCE_CONFIG_PATH,
-    ];
+    return [superblocksConfig as SuperblocksMonorepoConfig, attemptedPath];
   } catch {
     if (!checkParentDir) {
       // no superblocks config file found
       throw new Error(
-        "No Superblocks config file found in current directory " +
-          pathPrefix +
-          RESOURCE_CONFIG_PATH
+        "No Superblocks config file found in current directory " + attemptedPath
       );
     }
     return getSuperblocksMonorepoConfigJson(true, "../" + pathPrefix);

package/src/types.ts

@@ -1,11 +1,15 @@
 import { type UUID } from "node:crypto";
 import { type DataType } from "./data-types";
 
-interface PropertiesPanelDisplay {
+interface PropertiesPanelDisplay<T extends DataType> {
   /**
    * Determines what form item type is shown in the Superblocks properties panel.
+   *
+   * Only booleans are allowed to use the "switch" control
    */
-  controlType: "text" | "js-expr" | "switch";
+  controlType: T extends "boolean"
+    ? "text" | "js-expr" | "switch"
+    : "text" | "js-expr";
 
   /**
    * Determines form item label in the Superblocks properties panel.
@@ -21,20 +25,47 @@ interface PropertiesPanelDisplay {
   /**
    * This shows up in the popover as a user types into the properties panel.
    * This is a documentation field that helps users understand what type of data is accepted
-   * by this property.
+   * by this property. You should give a specific example, not a generic type
+   *
+   * @example {
+   *   label: "My Label",
+   *   value: "myValue"
+   * }
    */
   exampleData?: string;
+
+  /**
+   * This shows up in the popover as a user types into the properties panel.
+   * This is a documentation field that helps users understand what type of data is accepted
+   * by this property. Typescript notation is recommended.
+   *
+   * @example "Array<{ label: string; value: string; }>"
+   */
+  expectedType?: string;
+
+  /**
+   * The default value should match the dataType of the property.
+   *
+   * When dataType is "any", you must provide a string default value.
+   * Your string will be interpreted based on the controlType, so if you have controlType "js-expr",
+   * you should provide a string that is a valid javascript expression including quotations marks.
+   */
+  defaultValue?: T extends "number"
+    ? number
+    : T extends "boolean"
+    ? boolean
+    : string;
 }
 
-export interface Property {
+export interface PropertyForData<T extends DataType> {
   path: string;
-  dataType: DataType;
+  dataType: T;
 
   /**
    * The presence of this object determines whether or not this property
    * shows up in the Superblocks properties panel.
    **/
-  propertiesPanelDisplay?: PropertiesPanelDisplay;
+  propertiesPanelDisplay?: PropertiesPanelDisplay<T>;
 
   /**
    * A description of this property. This is used in the Superblocks properties panel
@@ -57,6 +88,12 @@ export interface Property {
   isExternallySettable?: boolean;
 }
 
+export type Property =
+  | PropertyForData<"string">
+  | PropertyForData<"number">
+  | PropertyForData<"boolean">
+  | PropertyForData<"any">;
+
 export interface ComponentConfig {
   id: UUID;
 
@@ -75,7 +112,15 @@ export interface ComponentConfig {
    */
   componentPath: string;
 
-  properties: Property[];
+  properties: Array<
+    // Note to devs: The reason we are duplicating the Property type above is that it produces a better
+    // error message. The user will see 'is not assignable to type PropertyForData<"string"> | PropertyForData<"number">'
+    // instead of seeing "is not assignable to type Property"
+    | PropertyForData<"string">
+    | PropertyForData<"number">
+    | PropertyForData<"boolean">
+    | PropertyForData<"any">
+  >;
 
   /**
    * @example [{
@@ -87,4 +132,9 @@ export interface ComponentConfig {
     label: string;
     path: string;
   }>;
+
+  gridDimensions?: {
+    initialColumns: number;
+    initialRows: number;
+  };
 }

package/src/validation.ts

@@ -22,6 +22,15 @@ const componentSchema: Schema = {
         $ref: "#/definitions/EventHandler",
       },
     },
+    gridDimensions: {
+      type: "object",
+      properties: {
+        initialColumns: { type: "number" },
+        initialRows: { type: "number" },
+      },
+      additionalProperties: false,
+      required: ["initialColumns", "initialRows"],
+    },
   },
   required: [
     "id",
@@ -42,9 +51,22 @@ const componentSchema: Schema = {
           properties: {
             label: { type: "string" },
             controlType: { enum: ["text", "js-expr", "switch"] },
-            defaultValue: { type: "string" },
+            defaultValue: {
+              oneOf: [
+                {
+                  type: "string",
+                },
+                {
+                  type: "boolean",
+                },
+                {
+                  type: "number",
+                },
+              ],
+            },
             placeholder: { type: "string" },
             exampleData: { type: "string" },
+            expectedType: { type: "string" },
           },
           required: ["controlType", "label"],
           additionalProperties: false,