@builder.io/sdk 1.1.26 → 1.1.27-2

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@builder.io/sdk",
-    "version": "1.1.25",
+    "version": "1.1.27-1",
     "unpkg": "./dist/index.browser.js",
     "main": "./dist/index.cjs.js",
     "module": "./dist/index.esm.js",
@@ -13,6 +13,9 @@
     "scripts": {
         "_unlink": "npm unlink *",
         "_install": "npm install",
+        "docs": "npm run docs:generate && npm run docs:cleanup",
+        "docs:generate": "typedoc",
+        "docs:cleanup": "node scripts/cleanup-generated-docs",
         "build": "npm run tsc && rollup -c",
         "watch": "rollup -cw",
         "start": "npm run watch",
@@ -41,6 +44,8 @@
         "@types/virtual-dom": "^2.0.27",
         "esbuild": "0.14.14",
         "esbuild-runner": "2.2.1",
+        "glob": "^7.2.3",
+        "glob-promise": "^4.2.2",
         "jest": "27.4.7",
         "rollup": "^0.58.2",
         "rollup-plugin-alias": "^1.4.0",
@@ -53,7 +58,9 @@
         "rollup-plugin-typescript": "^0.8.1",
         "rollup-plugin-typescript2": "^0.13.0",
         "rollup-plugin-uglify": "^3.0.0",
-        "typescript": "^3.8.3"
+        "typedoc": "^0.22.15",
+        "typedoc-plugin-markdown": "^3.12.1",
+        "typescript": "^4.6.4"
     },
     "dependencies": {
         "hash-sum": "^2.0.0",

package/dist/src/builder.class.d.ts

@@ -48,30 +48,75 @@ export interface UserAttributes {
      * URL path of the current user.
      */
     urlPath?: string;
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @hidden
+     */
     queryString?: string | ParamsMap;
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @hidden
+     */
     device?: 'mobile' | 'tablet' | 'desktop';
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @hidden
+     */
     location?: any;
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @hidden
+     */
     userAgent?: string;
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @hidden
+     */
     referrer?: string;
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @hidden
+     */
     entryMedium?: string;
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @hidden
+     */
     language?: string;
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @hidden
+     */
     browser?: string;
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @hidden
+     */
     cookie?: string;
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @hidden
+     */
     newVisitor?: boolean;
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @hidden
+     */
     operatingSystem?: string;
 }
 export interface GetContentOptions {
+    /**
+     * User attribute key value pairs to be used for targeting
+     * https://www.builder.io/c/docs/custom-targeting-attributes
+     *
+     * e.g.
+     * ```js
+     * userAttributes: {
+     *   urlPath: '/',
+     *   returnVisitor: true,
+     * }
+     * ```
+     */
     userAttributes?: UserAttributes;
     /**
      * Alias for userAttributes.urlPath except it can handle a full URL (optionally with host,
@@ -114,10 +159,13 @@ export interface GetContentOptions {
     /**
      * Mongodb style query of your data. E.g.:
      *
-     * ```
-     * &query.data.id=abc123
-     * &query.data.myCustomField=someValue
-     * &query.data.someNumber.$ne=20
+     * ```js
+     * query: {
+     *  id: 'abc123',
+     *  data: {
+     *    myCustomField: { $gt: 20 },
+     *  }
+     * }
      * ```
      *
      * See more info on MongoDB's query operators and format.
@@ -172,6 +220,7 @@ export interface GetContentOptions {
     /**
      * @package
      * @deprecated
+     * @hidden
      */
     alias?: string;
     fields?: string;
@@ -191,7 +240,10 @@ export interface GetContentOptions {
      * Affects HTML generation for specific targets.
      */
     format?: 'amp' | 'email' | 'html' | 'react' | 'solid';
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @hidden
+     */
     noWrap?: true;
     /**
      * @package
@@ -243,22 +295,60 @@ interface Map<K, V> {
     values(): IterableIterator<V>;
     [Symbol.iterator](): IterableIterator<[K, V]>;
 }
+/**
+ * This is the interface for inputs in `Builder.registerComponent`
+ *
+ * ```js
+ * Builder.registerComponent(MyComponent, {
+ *   inputs: [{ name: 'title', type: 'text' }] // <- Input[]
+ * })
+ * ```
+ *
+ * Learn more about registering custom components [here](https://www.builder.io/c/docs/custom-react-components)
+ */
 export interface Input {
+    /** This is the name of the component prop this input represents */
     name: string;
+    /** A friendlier name to show in the UI if the component prop name is not ideal for end users */
     friendlyName?: string;
+    /** @hidden @deprecated */
     description?: string;
+    /** A default value to use */
     defaultValue?: any;
+    /**
+     * The type of input to use, such as 'text'
+     *
+     * See all available inputs [here](https://www.builder.io/c/docs/custom-react-components#input-types)
+     * and you can create your own custom input types and associated editor UIs with [plugins](https://www.builder.io/c/docs/extending/plugins)
+     */
     type: string;
+    /** Is this input mandatory or not */
     required?: boolean;
+    /** @hidden */
     autoFocus?: boolean;
     subFields?: Input[];
+    /**
+     * Additional text to render in the UI to give guidance on how to use this
+     *
+     * @example
+     * ```js
+     * helperText: 'Be sure to use a proper URL, starting with "https://"'
+     * 111
+     */
     helperText?: string;
+    /** @hidden */
     allowedFileTypes?: string[];
+    /** @hidden */
     imageHeight?: number;
+    /** @hidden */
     imageWidth?: number;
+    /** @hidden */
     mediaHeight?: number;
+    /** @hidden */
     mediaWidth?: number;
+    /** @hidden */
     hideFromUI?: boolean;
+    /** @hidden */
     modelId?: string;
     /**
      * Number field type validation maximum accepted input
@@ -285,9 +375,13 @@ export interface Input {
      * to bubble up important inputs for locked groups, like text and images
      */
     bubble?: boolean;
+    /** @hidden */
     options?: {
         [key: string]: any;
     };
+    /**
+     * For "text" input type, specifying an enum will show a dropdown of options instead
+     */
     enum?: string[] | {
         label: string;
         value: any;
@@ -305,31 +399,82 @@ export interface Input {
          */
         message: string;
     };
+    /**
+     * Set this to `true` to put this under the "show more" section of
+     * the options editor. Useful for things that are more advanced
+     * or more rarely used and don't need to be too prominent
+     */
     advanced?: boolean;
+    /** @hidden */
     onChange?: Function | string;
+    /** @hidden */
     code?: boolean;
+    /** @hidden */
     richText?: boolean;
+    /** @hidden */
     showIf?: ((options: Map<string, any>) => boolean) | string;
+    /** @hidden */
     copyOnAdd?: boolean;
 }
+/**
+ * This is the interface for the options for `Builder.registerComponent`
+ *
+ * ```js
+ * Builder.registerComponent(YourComponent, {
+ *  // <- Component options
+ * })
+ * ```
+ *
+ * Learn more about registering custom components [here](https://www.builder.io/c/docs/custom-react-components)
+ */
 export interface Component {
     /**
      * Name your component something unique, e.g. 'MyButton'. You can override built-in components
      * by registering a component with the same name, e.g. 'Text', to replace the built-in text component
      */
     name: string;
+    /** @hidden @deprecated */
     description?: string;
     /**
      * Link to a documentation page for this component
      */
     docsLink?: string;
+    /**
+     * Link to an image to be used as an icon for this component in Builder's editor
+     *
+     * @example
+     * ```js
+     * image: 'https://some-cdn.com/my-icon-for-this-component.png'
+     * ```
+     */
     image?: string;
     /**
-     * Input schema for your component for users to fill in the options
+     * Link to a screenshot shown when user hovers over the component in Builder's editor
+     * use https://builder.io/upload to upload your screeshot, for easier resizing by Builder.
+     */
+    screenshot?: string;
+    /**
+     * Input schema for your component for users to fill in the options via a UI
+     * that translate to this components props
      */
     inputs?: Input[];
+    /** @hidden @deprecated */
     class?: any;
+    /** @hidden @deprecated */
     type?: 'angular' | 'webcomponent' | 'react' | 'vue';
+    /**
+     * Default styles to apply when droppged into the Builder.io editor
+     *
+     * @example
+     * ```js
+     * defaultStyles: {
+     *   // large (default) breakpoint
+     *   large: {
+     *     backgroundColor: 'black'
+     *   },
+     * }
+     * ```
+     */
     defaultStyles?: {
         [key: string]: string;
     };
@@ -339,6 +484,7 @@ export interface Component {
      * github.com/BuilderIO/builder/blob/master/examples/react-design-system/src/components/HeroWithChildren/HeroWithChildren.builder.js#L5
      */
     canHaveChildren?: boolean;
+    /** @hidden */
     fragment?: boolean;
     /**
      * Do not wrap a component in a dom element. Be sure to use {...props.attributes} with this option
@@ -349,7 +495,11 @@ export interface Component {
      * Default children
      */
     defaultChildren?: BuilderElement[];
+    /**
+     * Default options to merge in when creating this block
+     */
     defaults?: Partial<BuilderElement>;
+    /** @hidden @deprecated */
     hooks?: {
         [key: string]: string | Function;
     };
@@ -357,7 +507,9 @@ export interface Component {
      * Hide your component in editor, useful for gradually deprecating components
      */
     hideFromInsertMenu?: boolean;
+    /** Custom tag name (for custom webcomponents only) */
     tag?: string;
+    /** @hidden @deprecated */
     static?: boolean;
     /**
      * Passing a list of model names will restrict using the component to only the models listed here, otherwise it'll be available for all models
@@ -403,7 +555,7 @@ export interface Component {
          */
         query?: any;
     };
-    /** not yet implemented */
+    /** @hidden @deprecated */
     friendlyName?: string;
     /**
      * Use to restrict access to your component based on a the current user permissions
@@ -421,6 +573,29 @@ export interface InsertMenuItem {
     icon?: string;
     item: DeepPartial<BuilderElement>;
 }
+/**
+ * Use this to register custom sections in the Insert menu, for instance
+ * to make new sections to organize your custom components
+ *
+ * ![Example of what a custom section looks like](https://cdn.builder.io/api/v1/image/assets%2F7f7bbcf72a1a4d72bac5daa359e7befd%2Fe5f2792e9c0f44ed89a9dcb77b945858)
+ *
+ * @example
+ * ```js
+ * Builder.register('insertMenu', {
+ *   name: 'Our components',
+ *   items: [
+ *     { name: 'Hero' },
+ *     { name: 'Double Columns' },
+ *     { name: 'Triple Columns' },
+ *     { name: 'Dynamic Columns' },
+ *   ],
+ * })
+ * ```
+ *
+ * You can make as many custom sections as you like
+ *
+ * See a complete usage example [here](https://github.com/builderio/builder/blob/main/examples/react-design-system/src/builder-settings.js)
+ */
 export interface InsertMenuConfig {
     name: string;
     priority?: number;
@@ -439,6 +614,10 @@ export interface Action {
 export declare class Builder {
     protected request?: IncomingMessage | undefined;
     protected response?: ServerResponse | undefined;
+    /**
+     * @hidden
+     * @deprecated. This is buggy, and always behind by a version.
+     */
     static VERSION: string;
     static components: Component[];
     static singletonInstance: Builder;
@@ -485,6 +664,12 @@ export declare class Builder {
     static previewingModel: string | false | null;
     static settings: Settings;
     static settingsChange: BehaviorSubject<any, any>;
+    /**
+     * @deprecated
+     * @hidden
+     *
+     * Use Builder.register('editor.settings', {}) instead.
+     */
     static set(settings: Settings): void;
     static import(packageName: string): any;
     static isEditing: boolean;