@superblocksteam/util 0.0.20 → 0.0.22

package/dist/data-types.d.ts

@@ -0,0 +1,9 @@
+export declare const supportedDataTypes: readonly ["string", "number", "boolean", "any"];
+export type DataType = (typeof supportedDataTypes)[number];
+interface TypeInfo {
+    tsType: string;
+    prompt: string;
+}
+export declare const dataTypeDefinions: Record<DataType, TypeInfo>;
+export declare function isValidDataType(input: string): input is DataType;
+export {};

package/dist/data-types.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidDataType = exports.dataTypeDefinions = exports.supportedDataTypes = void 0;
+exports.supportedDataTypes = [
+    "string",
+    "number",
+    "boolean",
+    "any",
+];
+exports.dataTypeDefinions = {
+    string: {
+        tsType: "string",
+        prompt: "string",
+    },
+    number: {
+        tsType: "number",
+        prompt: "number",
+    },
+    boolean: {
+        tsType: "boolean",
+        prompt: "boolean",
+    },
+    any: {
+        tsType: "any",
+        prompt: "any (raw js expression)",
+    },
+};
+function isValidDataType(input) {
+    return Object.prototype.hasOwnProperty.call(exports.dataTypeDefinions, input);
+}
+exports.isValidDataType = isValidDataType;

package/dist/events.d.ts

@@ -0,0 +1,9 @@
+export declare enum ComponentEvent {
+    CREATE = "create",
+    INIT = "init",
+    LOGIN = "login",
+    MIGRATE = "migrate",
+    PULL = "pull",
+    REGISTER = "register",
+    UPLOAD = "upload"
+}

package/dist/events.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComponentEvent = void 0;
+var ComponentEvent;
+(function (ComponentEvent) {
+    ComponentEvent["CREATE"] = "create";
+    ComponentEvent["INIT"] = "init";
+    ComponentEvent["LOGIN"] = "login";
+    ComponentEvent["MIGRATE"] = "migrate";
+    ComponentEvent["PULL"] = "pull";
+    ComponentEvent["REGISTER"] = "register";
+    ComponentEvent["UPLOAD"] = "upload";
+})(ComponentEvent || (exports.ComponentEvent = ComponentEvent = {}));

package/dist/file-uploader.d.ts

@@ -1 +1,2 @@
+export declare const COMPONENT_EVENT_HEADER = "x-superblocks-component-event";
 export declare const getBucketeerUrlFromSuperblocksUrl: (superblocksBaseUrl: string) => string;

package/dist/file-uploader.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getBucketeerUrlFromSuperblocksUrl = void 0;
+exports.getBucketeerUrlFromSuperblocksUrl = exports.COMPONENT_EVENT_HEADER = void 0;
 const lodash_1 = require("lodash");
+exports.COMPONENT_EVENT_HEADER = "x-superblocks-component-event";
 // retrieves bucketeer base URL given the superblocks server base URL
 const getBucketeerUrlFromSuperblocksUrl = (superblocksBaseUrl) => {
     // if superblocks base URL is an EE, return bucketeer's dev URL

package/dist/generate-component-types.d.ts

@@ -1 +1,2 @@
-export declare function generateComponentTypesFile(config: any): string;
+import { ComponentConfig } from "./types";
+export declare function generateComponentTypesFile(config: ComponentConfig): string;

package/dist/generate-component-types.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateComponentTypesFile = void 0;
-const input_types_1 = require("./input-types");
+const data_types_1 = require("./data-types");
 const indent = (str, spaces) => {
     const spacesString = " ".repeat(spaces);
     return str
@@ -10,21 +10,21 @@ const indent = (str, spaces) => {
         .join("\n");
 };
 function renderInputTypeAsTS(name, type, trailingChars, indentSpaces) {
-    return indent(`${name}: ${input_types_1.inputTypeDefinions[type].tsType}${trailingChars}`, indentSpaces);
+    return indent(`${name}: ${data_types_1.dataTypeDefinions[type].tsType}${trailingChars}`, indentSpaces);
 }
 function generateComponentTypesFile(config) {
     var _a, _b;
-    const statefulProperties = (_a = config.statefulProperties) !== null && _a !== void 0 ? _a : [];
-    const eventHandlers = (_b = config.eventHandlers) !== null && _b !== void 0 ? _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.
 // Use the \`superblocks components watch\` command to regenerate this file from its source in config.ts
 
-// All stateful properties of your component are defined here.
+// 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 {
-${statefulProperties
-        .map((v) => renderInputTypeAsTS(v.path, v.inputType, ";", 2) + "\n")
+${properties
+        .map((v) => renderInputTypeAsTS(v.path, v.dataType, ";", 2) + "\n")
         .join("")}}
 
 export interface EventTriggers {

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export * from "./constants";
 export * from "./component-configs";
+export * from "./events";
 export * from "./file-uploader";
 export * from "./login";
 export * from "./resource-configs";
-export * from "./input-types";
+export * from "./data-types";
 export * from "./types";

package/dist/index.js

@@ -3,8 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./constants"), exports);
 tslib_1.__exportStar(require("./component-configs"), exports);
+tslib_1.__exportStar(require("./events"), exports);
 tslib_1.__exportStar(require("./file-uploader"), exports);
 tslib_1.__exportStar(require("./login"), exports);
 tslib_1.__exportStar(require("./resource-configs"), exports);
-tslib_1.__exportStar(require("./input-types"), exports);
+tslib_1.__exportStar(require("./data-types"), exports);
 tslib_1.__exportStar(require("./types"), exports);

package/dist/resource-configs.d.ts

@@ -28,7 +28,6 @@ export type SuperblocksConfig = SuperblocksMonorepoConfig | SuperblocksApplicati
  * @param checkParentDir Whether to recursively check the parent directory for a Superblocks config file
  */
 export declare function getSuperblocksMonorepoConfigJson(checkParentDir?: boolean, pathPrefix?: string): Promise<[SuperblocksMonorepoConfig, string]>;
-export declare function updatedMonorepoConfig(version: string): Promise<void>;
 export declare function getSuperblocksApplicationConfigJson(): Promise<SuperblocksApplicationConfig>;
 export declare function getSuperblocksBackendConfigJson(): Promise<SuperblocksBackendConfig>;
 export declare function getSuperblocksResourceConfigIfExists(): Promise<SuperblocksResourceConfig | undefined>;

package/dist/resource-configs.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSuperblocksResourceConfigIfExists = exports.getSuperblocksBackendConfigJson = exports.getSuperblocksApplicationConfigJson = exports.updatedMonorepoConfig = exports.getSuperblocksMonorepoConfigJson = void 0;
+exports.getSuperblocksResourceConfigIfExists = exports.getSuperblocksBackendConfigJson = exports.getSuperblocksApplicationConfigJson = exports.getSuperblocksMonorepoConfigJson = void 0;
 const tslib_1 = require("tslib");
 const fs = tslib_1.__importStar(require("fs-extra"));
 const constants_1 = require("./constants");
@@ -35,21 +35,6 @@ async function getSuperblocksMonorepoConfigJson(checkParentDir = false, pathPref
     }
 }
 exports.getSuperblocksMonorepoConfigJson = getSuperblocksMonorepoConfigJson;
-async function updatedMonorepoConfig(version) {
-    try {
-        const [previousConfig, configPath] = await getSuperblocksMonorepoConfigJson(true);
-        if (previousConfig.metadata.cliVersion !== version) {
-            const newConfig = JSON.parse(JSON.stringify(previousConfig));
-            newConfig.metadata.cliVersion = version;
-            // update superblocks.json file
-            await fs.writeFile(configPath, JSON.stringify(updatedMonorepoConfig, null, 2));
-        }
-    }
-    catch {
-        // This might fail for a brand-new project folder, which is deliberately ignored
-    }
-}
-exports.updatedMonorepoConfig = updatedMonorepoConfig;
 async function getSuperblocksApplicationConfigJson() {
     let superblocksConfig;
     try {

package/dist/types.d.ts

@@ -1,26 +1,77 @@
 /// <reference types="node" />
 import { type UUID } from "node:crypto";
-import { type InputType } from "./input-types";
-export interface StatefulProperty {
+import { type DataType } from "./data-types";
+interface PropertiesPanelDisplay {
+    /**
+     * Determines what form item type is shown in the Superblocks properties panel.
+     */
+    controlType: "text" | "js-expr" | "switch";
+    /**
+     * Determines form item label in the Superblocks properties panel.
+     */
     label: string;
-    path: string;
-    inputType: InputType;
+    /**
+     * Placeholder text appears as gray text in the properties panel. This only applies
+     * to text-like inputs.
+     */
     placeholder?: 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.
+     */
+    exampleData?: string;
+}
+export interface Property {
+    path: string;
+    dataType: DataType;
+    /**
+     * The presence of this object determines whether or not this property
+     * shows up in the Superblocks properties panel.
+     **/
+    propertiesPanelDisplay?: PropertiesPanelDisplay;
+    /**
+     * A description of this property. This is used in the Superblocks properties panel
+     * as well as in the custom component's autocomplete.
+     **/
+    description?: string;
+    /**
+     * By default, all your properties are readable from anywhere in Superblocks using dot notation
+     * (e.g. `myComponent.myProperty`). If you want to hide a property from the outside world,
+     * set this to false
+     * @default true
+     */
+    isExternallyReadable?: boolean;
+    /**
+     * By default, all properties can have be used with Set Component Property and Reset Component to Default.
+     * @default true
+     **/
+    isExternallySettable?: boolean;
 }
 export interface ComponentConfig {
     id: UUID;
+    /**
+     * @example: "myComponent"
+     */
     name: string;
+    /**
+     * @example "My Component"
+     */
     displayName: string;
+    /**
+     * @example "components/myComponent/component.tsx"
+     */
     componentPath: string;
-    statefulProperties: StatefulProperty[];
+    properties: Property[];
     /**
-     * Example: [{
+     * @example [{
      *  label: "On Click",
      *  path: "onClick",
      * }]
      */
-    eventHandlers: Array<{
+    events: Array<{
         label: string;
         path: string;
     }>;
 }
+export {};

package/dist/validation.js

@@ -12,13 +12,13 @@ const componentSchema = {
         name: { type: "string" },
         displayName: { type: "string" },
         componentPath: { type: "string" },
-        statefulProperties: {
+        properties: {
             type: "array",
             items: {
-                $ref: "#/definitions/StatefulProperty",
+                $ref: "#/definitions/Property",
             },
         },
-        eventHandlers: {
+        events: {
             type: "array",
             items: {
                 $ref: "#/definitions/EventHandler",
@@ -30,21 +30,34 @@ const componentSchema = {
         "name",
         "displayName",
         "componentPath",
-        "statefulProperties",
-        "eventHandlers",
+        "properties",
+        "events",
     ],
     additionalProperties: false,
     definitions: {
-        StatefulProperty: {
+        Property: {
             properties: {
-                label: { type: "string" },
                 path: { type: "string" },
-                inputType: { enum: ["text", "number", "boolean", "js"] },
-                placeholder: { type: "string" },
+                dataType: { enum: ["number", "boolean", "string", "any"] },
+                propertiesPanelDisplay: {
+                    type: "object",
+                    properties: {
+                        label: { type: "string" },
+                        controlType: { enum: ["text", "js-expr", "switch"] },
+                        defaultValue: { type: "string" },
+                        placeholder: { type: "string" },
+                        exampleData: { type: "string" },
+                    },
+                    required: ["controlType", "label"],
+                    additionalProperties: false,
+                },
+                description: { type: "string" },
+                isExternallySettable: { type: "boolean" },
+                isExternallyReadable: { type: "boolean" },
             },
             type: "object",
             additionalProperties: false,
-            required: ["label", "path", "inputType"],
+            required: ["path", "dataType"],
         },
         EventHandler: {
             properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/util",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "main": "dist/index.js",
   "homepage": "https://www.superblocks.com",
   "scripts": {

package/src/data-types.ts

@@ -0,0 +1,39 @@
+export const supportedDataTypes = [
+  "string",
+  "number",
+  "boolean",
+  "any",
+] as const;
+
+export type DataType = (typeof supportedDataTypes)[number];
+
+interface TypeInfo {
+  tsType: string;
+  prompt: string;
+}
+
+export const dataTypeDefinions: Record<DataType, TypeInfo> = {
+  string: {
+    tsType: "string",
+    prompt: "string",
+  },
+  number: {
+    tsType: "number",
+    prompt: "number",
+  },
+  boolean: {
+    tsType: "boolean",
+    prompt: "boolean",
+  },
+  any: {
+    tsType: "any",
+    prompt: "any (raw js expression)",
+  },
+};
+
+export function isValidDataType(input: string): input is DataType {
+  return Object.prototype.hasOwnProperty.call(
+    dataTypeDefinions,
+    input as DataType
+  );
+}

package/src/events.ts

@@ -0,0 +1,9 @@
+export enum ComponentEvent {
+  CREATE = "create",
+  INIT = "init",
+  LOGIN = "login",
+  MIGRATE = "migrate",
+  PULL = "pull",
+  REGISTER = "register",
+  UPLOAD = "upload",
+}

package/src/file-uploader.ts

@@ -1,5 +1,7 @@
 import { isEmpty } from "lodash";
 
+export const COMPONENT_EVENT_HEADER = "x-superblocks-component-event";
+
 // retrieves bucketeer base URL given the superblocks server base URL
 export const getBucketeerUrlFromSuperblocksUrl = (
   superblocksBaseUrl: string

package/src/generate-component-types.ts

@@ -1,4 +1,5 @@
-import { inputTypeDefinions, type InputType } from "./input-types";
+import { dataTypeDefinions, type DataType } from "./data-types";
+import { ComponentConfig } from "./types";
 
 const indent = (str: string, spaces: number) => {
   const spacesString = " ".repeat(spaces);
@@ -11,28 +12,28 @@ const indent = (str: string, spaces: number) => {
 
 function renderInputTypeAsTS(
   name: string,
-  type: InputType,
+  type: DataType,
   trailingChars: string,
   indentSpaces: number
 ) {
   return indent(
-    `${name}: ${inputTypeDefinions[type].tsType}${trailingChars}`,
+    `${name}: ${dataTypeDefinions[type].tsType}${trailingChars}`,
     indentSpaces
   );
 }
 
-export function generateComponentTypesFile(config: any) {
-  const statefulProperties = config.statefulProperties ?? [];
-  const eventHandlers = config.eventHandlers ?? [];
+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.
 // Use the \`superblocks components watch\` command to regenerate this file from its source in config.ts
 
-// All stateful properties of your component are defined here.
+// 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 {
-${statefulProperties
-  .map((v: any) => renderInputTypeAsTS(v.path, v.inputType, ";", 2) + "\n")
+${properties
+  .map((v) => renderInputTypeAsTS(v.path, v.dataType, ";", 2) + "\n")
   .join("")}}
 
 export interface EventTriggers {

package/src/index.ts

@@ -1,7 +1,8 @@
 export * from "./constants";
 export * from "./component-configs";
+export * from "./events";
 export * from "./file-uploader";
 export * from "./login";
 export * from "./resource-configs";
-export * from "./input-types";
+export * from "./data-types";
 export * from "./types";

package/src/resource-configs.ts

@@ -75,25 +75,6 @@ export async function getSuperblocksMonorepoConfigJson(
   }
 }
 
-export async function updatedMonorepoConfig(version: string) {
-  try {
-    const [previousConfig, configPath] = await getSuperblocksMonorepoConfigJson(
-      true
-    );
-    if (previousConfig.metadata.cliVersion !== version) {
-      const newConfig = JSON.parse(JSON.stringify(previousConfig));
-      newConfig.metadata.cliVersion = version;
-      // update superblocks.json file
-      await fs.writeFile(
-        configPath,
-        JSON.stringify(updatedMonorepoConfig, null, 2)
-      );
-    }
-  } catch {
-    // This might fail for a brand-new project folder, which is deliberately ignored
-  }
-}
-
 export async function getSuperblocksApplicationConfigJson(): Promise<SuperblocksApplicationConfig> {
   let superblocksConfig;
   try {

package/src/types.ts

@@ -1,34 +1,89 @@
 import { type UUID } from "node:crypto";
-import { type InputType } from "./input-types";
+import { type DataType } from "./data-types";
 
-export interface StatefulProperty {
+interface PropertiesPanelDisplay {
+  /**
+   * Determines what form item type is shown in the Superblocks properties panel.
+   */
+  controlType: "text" | "js-expr" | "switch";
+
+  /**
+   * Determines form item label in the Superblocks properties panel.
+   */
   label: string;
-  path: string;
-  inputType: InputType;
+
+  /**
+   * Placeholder text appears as gray text in the properties panel. This only applies
+   * to text-like inputs.
+   */
   placeholder?: 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.
+   */
+  exampleData?: string;
+}
+
+export interface Property {
+  path: string;
+  dataType: DataType;
+
+  /**
+   * The presence of this object determines whether or not this property
+   * shows up in the Superblocks properties panel.
+   **/
+  propertiesPanelDisplay?: PropertiesPanelDisplay;
+
+  /**
+   * A description of this property. This is used in the Superblocks properties panel
+   * as well as in the custom component's autocomplete.
+   **/
+  description?: string;
+
+  /**
+   * By default, all your properties are readable from anywhere in Superblocks using dot notation
+   * (e.g. `myComponent.myProperty`). If you want to hide a property from the outside world,
+   * set this to false
+   * @default true
+   */
+  isExternallyReadable?: boolean;
+
+  /**
+   * By default, all properties can have be used with Set Component Property and Reset Component to Default.
+   * @default true
+   **/
+  isExternallySettable?: boolean;
 }
 
 export interface ComponentConfig {
   id: UUID;
 
-  // Example: "myComponent"
+  /**
+   * @example: "myComponent"
+   */
   name: string;
 
-  // Example: "My Component"
+  /**
+   * @example "My Component"
+   */
   displayName: string;
 
-  // Example: "components/myComponent/component.tsx"
+  /**
+   * @example "components/myComponent/component.tsx"
+   */
   componentPath: string;
 
-  statefulProperties: StatefulProperty[];
+  properties: Property[];
 
   /**
-   * Example: [{
+   * @example [{
    *  label: "On Click",
    *  path: "onClick",
    * }]
    */
-  eventHandlers: Array<{
+  events: Array<{
     label: string;
     path: string;
   }>;

package/src/validation.ts

@@ -10,13 +10,13 @@ const componentSchema: Schema = {
     name: { type: "string" },
     displayName: { type: "string" },
     componentPath: { type: "string" },
-    statefulProperties: {
+    properties: {
       type: "array",
       items: {
-        $ref: "#/definitions/StatefulProperty",
+        $ref: "#/definitions/Property",
       },
     },
-    eventHandlers: {
+    events: {
       type: "array",
       items: {
         $ref: "#/definitions/EventHandler",
@@ -28,21 +28,34 @@ const componentSchema: Schema = {
     "name",
     "displayName",
     "componentPath",
-    "statefulProperties",
-    "eventHandlers",
+    "properties",
+    "events",
   ],
   additionalProperties: false,
   definitions: {
-    StatefulProperty: {
+    Property: {
       properties: {
-        label: { type: "string" },
         path: { type: "string" },
-        inputType: { enum: ["text", "number", "boolean", "js"] },
-        placeholder: { type: "string" },
+        dataType: { enum: ["number", "boolean", "string", "any"] },
+        propertiesPanelDisplay: {
+          type: "object",
+          properties: {
+            label: { type: "string" },
+            controlType: { enum: ["text", "js-expr", "switch"] },
+            defaultValue: { type: "string" },
+            placeholder: { type: "string" },
+            exampleData: { type: "string" },
+          },
+          required: ["controlType", "label"],
+          additionalProperties: false,
+        },
+        description: { type: "string" },
+        isExternallySettable: { type: "boolean" },
+        isExternallyReadable: { type: "boolean" },
       },
       type: "object",
       additionalProperties: false,
-      required: ["label", "path", "inputType"],
+      required: ["path", "dataType"],
     },
     EventHandler: {
       properties: {

package/dist/input-types.d.ts

@@ -1,9 +0,0 @@
-export declare const supportedInputTypes: readonly ["text", "number", "boolean", "js"];
-export type InputType = (typeof supportedInputTypes)[number];
-interface TypeInfo {
-    tsType: string;
-    prompt: string;
-}
-export declare const inputTypeDefinions: Record<InputType, TypeInfo>;
-export declare function isValidInputType(input: string): input is InputType;
-export {};

package/dist/input-types.js

@@ -1,26 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isValidInputType = exports.inputTypeDefinions = exports.supportedInputTypes = void 0;
-exports.supportedInputTypes = ["text", "number", "boolean", "js"];
-exports.inputTypeDefinions = {
-    text: {
-        tsType: "string",
-        prompt: "text",
-    },
-    number: {
-        tsType: "number",
-        prompt: "number",
-    },
-    boolean: {
-        tsType: "boolean",
-        prompt: "boolean",
-    },
-    js: {
-        tsType: "any",
-        prompt: "any (raw js expression)",
-    },
-};
-function isValidInputType(input) {
-    return Object.prototype.hasOwnProperty.call(exports.inputTypeDefinions, input);
-}
-exports.isValidInputType = isValidInputType;

package/src/input-types.ts

@@ -1,34 +0,0 @@
-export const supportedInputTypes = ["text", "number", "boolean", "js"] as const;
-
-export type InputType = (typeof supportedInputTypes)[number];
-
-interface TypeInfo {
-  tsType: string;
-  prompt: string;
-}
-
-export const inputTypeDefinions: Record<InputType, TypeInfo> = {
-  text: {
-    tsType: "string",
-    prompt: "text",
-  },
-  number: {
-    tsType: "number",
-    prompt: "number",
-  },
-  boolean: {
-    tsType: "boolean",
-    prompt: "boolean",
-  },
-  js: {
-    tsType: "any",
-    prompt: "any (raw js expression)",
-  },
-};
-
-export function isValidInputType(input: string): input is InputType {
-  return Object.prototype.hasOwnProperty.call(
-    inputTypeDefinions,
-    input as InputType
-  );
-}