Add CanvasSpot docs

docs/.vuepress/config.js

@@ -62,6 +62,7 @@ module.exports = {
         ['/api/i18n', 'I18n'],
         ['/api/canvas', 'Canvas'],
         ['/api/frame', `${subDivider}Frame`],
+        ['/api/canvas_spot', `${subDivider}CanvasSpot`],
         ['/api/assets', 'Asset Manager'],
         ['/api/asset', `${subDivider}Asset`],
         ['/api/block_manager', 'Block Manager'],

docs/api.js

@@ -68,6 +68,7 @@ async function generateDocs () {
     ['undo_manager/index.ts', 'undo_manager.md'],
     ['canvas/index.ts', 'canvas.md'],
     ['canvas/model/Frame.ts', 'frame.md'],
+    ['canvas/model/CanvasSpot.ts', 'canvas_spot.md'],
     ['i18n/index.ts', 'i18n.md'],
     ['navigator/index.ts', 'layer_manager.md'],
     ['pages/index.ts', 'pages.md'],
@@ -83,6 +84,7 @@ async function generateDocs () {
     return documentation.build([filePath], { shallow: true })
       .then(cm => documentation.formats.md(cm, /*{ markdownToc: true }*/))
       .then(async (output) => {
+        let addLogs = [];
         let result = output
           .replace(/\*\*\\\[/g, '**[')
           .replace(/\*\*\(\\\[/g, '**([')
@@ -97,11 +99,14 @@ async function generateDocs () {
         // Search for module event documentation
         if (result.indexOf(REPLACE_EVENTS) >= 0) {
           const eventsMd = await getEventsMdFromTypes(filePath);
+          if (eventsMd && result.indexOf(REPLACE_EVENTS) >= 0) {
+            addLogs.push('replaced events');
+          }
           result = eventsMd ? result.replace(REPLACE_EVENTS, `## Available Events\n${eventsMd}`) : result;
         }
 
         fs.writeFileSync(`${docRoot}/api/${file[1]}`, result);
-        log('Created', file[1]);
+        log('Created', file[1], addLogs.length ? `(${addLogs.join(', ')})` : '');
       });
   }));
 

docs/api/canvas.md

@@ -245,38 +245,6 @@ const coords = canvas.getCoords();
 
 Returns **[Object][2]** Object containing coordinates
 
-## addFrame
-
-Add new frame to the canvas
-
-### Parameters
-
-*   `props` **[Object][2]** Frame properties (optional, default `{}`)
-*   `opts`   (optional, default `{}`)
-
-### Examples
-
-```javascript
-canvas.addFrame({
-  name: 'Mobile home page',
-  x: 100, // Position in canvas
-  y: 100,
-  width: 500, // Frame dimensions
-  height: 600,
-  // device: 'DEVICE-ID',
-  components: [
-    '<h1 class="testh">Title frame</h1>',
-    '<p class="testp">Paragraph frame</p>',
-  ],
-  styles: `
-    .testh { color: red; }
-    .testp { color: blue; }
-  `,
-});
-```
-
-Returns **[Frame]** 
-
 ## getLastDragResult
 
 Get the last created Component from a drag & drop to the canvas.

docs/api/canvas_spot.md

@@ -0,0 +1,78 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## CanvasSpot
+
+
+
+Canvas spots are elements drawn on top of the canvas. They can be used to represent anything you
+might need but the most common use case of canvas spots is rendering information and managing
+components rendered in the canvas.
+Read here for more information about [Canvas Spots][1]
+
+[Component]: component.html
+
+### Properties
+
+*   `id` **[String][2]** Spot ID.
+*   `type` **[String][2]** Spot type.
+*   `component` **[Component]?** Component to which the spot will be attached.
+*   `componentView` **ComponentView?** ComponentView to which the spot will be attached.
+*   `boxRect` **[Object][3]?** Fixed box rect of the spot, eg. `{ width: 100, height: 100, x: 0, y: 0 }`.
+
+### getBoxRect
+
+Get the box rect of the spot.
+
+#### Parameters
+
+*   `opts` **[Object][3]**  (optional, default `{}`)
+
+#### Examples
+
+```javascript
+canvasSpot.getBoxRect();
+// { width: 100, height: 50, x: 0, y: 0 }
+```
+
+Returns **[Object][3]** The box rect object
+
+### getStyle
+
+Get the style object of the spot.
+
+#### Parameters
+
+*   `opts` **[Object][3]**  (optional, default `{}`)
+
+#### Examples
+
+```javascript
+canvasSpot.getStyle();
+// { width: '100px', height: '...', ... }
+```
+
+Returns **CSSStyleDeclaration** \[opts]
+
+### isType
+
+Check the spot type.
+
+#### Parameters
+
+*   `type` **[String][2]** 
+
+#### Examples
+
+```javascript
+canvasSpot.isType('select');
+```
+
+Returns **[Boolean][4]** 
+
+[1]: https://github.com/GrapesJS/grapesjs/blob/dev/docs/modules/Canvas.md#canvas-spots
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean

src/canvas/model/CanvasSpot.ts

@@ -20,17 +20,46 @@ export type CanvasSpotType = LiteralUnion<CanvasSpotBuiltInType, string>;
 
 /** @private */
 export interface CanvasSpotBase<T extends CanvasSpotType> {
+  /**
+   * Spot type, eg. `select`.
+   */
   type: T;
+  /**
+   * Spot ID.
+   */
   id: string;
+  /**
+   * Fixed box rect of the spot, eg. `{ width: 100, height: 100, x: 0, y: 0 }`.
+   */
   boxRect?: BoxRect;
+  /**
+   * Component to which the spot will be attached.
+   */
   component?: Component;
+  /**
+   * ComponentView to which the spot will be attached.
+   */
   componentView?: ComponentView;
   frame?: Frame;
 }
 
-/** @private */
 export interface CanvasSpotProps<T extends CanvasSpotType = CanvasSpotType> extends CanvasSpotBase<T> {}
 
+/**
+ * Canvas spots are elements drawn on top of the canvas. They can be used to represent anything you
+ * might need but the most common use case of canvas spots is rendering information and managing
+ * components rendered in the canvas.
+ * Read here for more information about [Canvas Spots](https://github.com/GrapesJS/grapesjs/blob/dev/docs/modules/Canvas.md#canvas-spots)
+ *
+ * [Component]: component.html
+ *
+ * @property {String} id Spot ID.
+ * @property {String} type Spot type.
+ * @property {[Component]} [component] Component to which the spot will be attached.
+ * @property {ComponentView} [componentView] ComponentView to which the spot will be attached.
+ * @property {Object} [boxRect] Fixed box rect of the spot, eg. `{ width: 100, height: 100, x: 0, y: 0 }`.
+ *
+ */
 export default class CanvasSpot<T extends CanvasSpotProps = CanvasSpotProps> extends ModuleModel<CanvasModule, T> {
   defaults() {
     return {
@@ -57,6 +86,14 @@ export default class CanvasSpot<T extends CanvasSpotProps = CanvasSpotProps> ext
     return this.componentView?.el;
   }
 
+  /**
+   * Get the box rect of the spot.
+   * @param {Object} [opts={}]
+   * @returns {Object} The box rect object
+   * @example
+   * canvasSpot.getBoxRect();
+   * // { width: 100, height: 50, x: 0, y: 0 }
+   */
   getBoxRect(opts?: GetBoxRectOptions) {
     const { el, em } = this;
     const cvView = em.Canvas.getCanvasView();
@@ -76,6 +113,14 @@ export default class CanvasSpot<T extends CanvasSpotProps = CanvasSpotProps> ext
     };
   }
 
+  /**
+   * Get the style object of the spot.
+   * @param {Object} [opts={}]
+   * @returns {CSSStyleDeclaration} [opts]
+   * @example
+   * canvasSpot.getStyle();
+   * // { width: '100px', height: '...', ... }
+   */
   getStyle(opts: { boxRect?: BoxRect } & GetBoxRectOptions = {}): Partial<CSSStyleDeclaration> {
     const { width, height, x, y } = opts.boxRect || this.getBoxRect(opts);
 
@@ -89,6 +134,13 @@ export default class CanvasSpot<T extends CanvasSpotProps = CanvasSpotProps> ext
     };
   }
 
+  /**
+   * Check the spot type.
+   * @param {String} type
+   * @returns {Boolean}
+   * @example
+   * canvasSpot.isType('select');
+   */
   isType<E extends T>(type: E['type']): this is CanvasSpot<E> {
     return this.type === type;
   }