diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 2113b1182..466ae6df5 100644 --- a/docs/.vuepress/config.js +++ b/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'], diff --git a/docs/api.js b/docs/api.js index 32af3a3bc..b02855461 100644 --- a/docs/api.js +++ b/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(', ')})` : ''); }); })); diff --git a/docs/api/canvas.md b/docs/api/canvas.md index af16875b5..dab3e1956 100644 --- a/docs/api/canvas.md +++ b/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: [ - '

Title frame

', - '

Paragraph frame

', - ], - styles: ` - .testh { color: red; } - .testp { color: blue; } - `, -}); -``` - -Returns **[Frame]** - ## getLastDragResult Get the last created Component from a drag & drop to the canvas. diff --git a/docs/api/canvas_spot.md b/docs/api/canvas_spot.md new file mode 100644 index 000000000..9c7349e22 --- /dev/null +++ b/docs/api/canvas_spot.md @@ -0,0 +1,78 @@ + + +## 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 diff --git a/src/canvas/model/CanvasSpot.ts b/src/canvas/model/CanvasSpot.ts index 45a877ef0..2009a40ef 100644 --- a/src/canvas/model/CanvasSpot.ts +++ b/src/canvas/model/CanvasSpot.ts @@ -20,17 +20,46 @@ export type CanvasSpotType = LiteralUnion; /** @private */ export interface CanvasSpotBase { + /** + * 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 extends CanvasSpotBase {} +/** + * 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 extends ModuleModel { defaults() { return { @@ -57,6 +86,14 @@ export default class CanvasSpot 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 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 { const { width, height, x, y } = opts.boxRect || this.getBoxRect(opts); @@ -89,6 +134,13 @@ export default class CanvasSpot ext }; } + /** + * Check the spot type. + * @param {String} type + * @returns {Boolean} + * @example + * canvasSpot.isType('select'); + */ isType(type: E['type']): this is CanvasSpot { return this.type === type; }