From 4dac69ee6b9c6840782ed734e6d461867de797ad Mon Sep 17 00:00:00 2001 From: Artur Arseniev Date: Mon, 24 Jun 2024 12:46:30 +0400 Subject: [PATCH] Update API docs --- docs/api/block_manager.md | 6 +++ docs/api/component.md | 28 +++++++++-- docs/api/components.md | 71 +++++++++++++++++++++++++++ docs/api/trait_manager.md | 6 +++ docs/api/undo_manager.md | 18 +++++++ src/dom_components/model/Component.ts | 3 +- 6 files changed, 127 insertions(+), 5 deletions(-) diff --git a/docs/api/block_manager.md b/docs/api/block_manager.md index dec9dd95c..48b31e3a2 100644 --- a/docs/api/block_manager.md +++ b/docs/api/block_manager.md @@ -66,6 +66,12 @@ editor.on('block:drag', (block) => { ... }); editor.on('block:drag:stop', (component, block) => { ... }); ``` +* `block:category:update` Block category updated. + +```javascript +editor.on('block:category:update', ({ category, changes }) => { ... }); +``` + * `block:custom` Event to use in case of [custom Block Manager UI](https://grapesjs.com/docs/modules/Blocks.html#customization). ```javascript diff --git a/docs/api/component.md b/docs/api/component.md index 59704dab0..f335ce9b4 100644 --- a/docs/api/component.md +++ b/docs/api/component.md @@ -128,6 +128,28 @@ Get the drag mode of the component. Returns **[String][1]** Drag mode value, options: `'absolute'` | `'translate'` | `''` +## setSymbolOverride + +Set symbol override. +By setting override to `true`, none of its property changes will be propagated to relative symbols. +By setting override to specific properties, changes of those properties will be skipped from propagation. + +### Parameters + +* `value` **([Boolean][3] | [String][1] | [Array][5]<[String][1]>)** + +### Examples + +```javascript +component.setSymbolOverride(['children', 'classes']); +``` + +## getSymbolOverride + +Get symbol override value. + +Returns **([Boolean][3] | [Array][5]<[String][1]>)** + ## find Find inner components by query string. @@ -238,7 +260,7 @@ Update attributes of the component ### Parameters * `attrs` **[Object][2]** Key value attributes -* `opts` **SetOptions** (optional, default `{}`) +* `opts` **SetAttrOptions** (optional, default `{}`) * `options` **[Object][2]** Options for the model update ### Examples @@ -256,7 +278,7 @@ Add attributes to the component ### Parameters * `attrs` **[Object][2]** Key value attributes -* `opts` **SetOptions** (optional, default `{}`) +* `opts` **SetAttrOptions** (optional, default `{}`) * `options` **[Object][2]** Options for the model update ### Examples @@ -304,7 +326,7 @@ Set the style on the component ### Parameters * `prop` **[Object][2]** Key value style object (optional, default `{}`) -* `opts` **any** (optional, default `{}`) +* `opts` **UpdateStyleOptions** (optional, default `{}`) ### Examples diff --git a/docs/api/components.md b/docs/api/components.md index 1b5564288..8f86ca6c7 100644 --- a/docs/api/components.md +++ b/docs/api/components.md @@ -218,6 +218,77 @@ cmp.isComponent({}); // false Returns **[Boolean][13]** +## addSymbol + +Add a new symbol from a component. +If the passed component is not a symbol, it will be converted to an instance and will return the main symbol. +If the passed component is already an instance, a new instance will be created and returned. +If the passed component is the main symbol, a new instance will be created and returned. + +### Parameters + +* `component` **[Component]** Component from which create a symbol. + +### Examples + +```javascript +const symbol = cmp.addSymbol(editor.getSelected()); +// cmp.getSymbolInfo(symbol).isSymbol === true; +``` + +Returns **[Component]** + +## getSymbols + +Get the array of main symbols. + +### Examples + +```javascript +const symbols = cmp.getSymbols(); +// [Component, Component, ...] +// Removing the main symbol will detach all the relative instances. +symbols[0].remove(); +``` + +Returns **[Array][11]<[Component]>** + +## detachSymbol + +Detach symbol instance from the main one. +The passed symbol instance will become a regular component. + +### Parameters + +* `component` **[Component]** The component symbol to detach. + +### Examples + +```javascript +const cmpInstance = editor.getSelected(); +// cmp.getSymbolInfo(cmpInstance).isInstance === true; +cmp.detachSymbol(cmpInstance); +// cmp.getSymbolInfo(cmpInstance).isInstance === false; +``` + +## getSymbolInfo + +Get info about the symbol. + +### Parameters + +* `component` **[Component]** Component symbol from which to get the info. +* `opts` **{withChanges: [string][12]?}** (optional, default `{}`) + +### Examples + +```javascript +cmp.getSymbolInfo(editor.getSelected()); +// > { isSymbol: true, isMain: false, isInstance: true, ... } +``` + +Returns **[Object][10]** Object containing symbol info. + ## canMove Check if a component can be moved inside another one. diff --git a/docs/api/trait_manager.md b/docs/api/trait_manager.md index fd102d310..3e43f6f2d 100644 --- a/docs/api/trait_manager.md +++ b/docs/api/trait_manager.md @@ -36,6 +36,12 @@ editor.on('trait:select', ({ traits, component }) => { ... }); editor.on('trait:value', ({ trait, component, value }) => { ... }); ``` +* `trait:category:update` Trait category updated. + +```javascript +editor.on('trait:category:update', ({ category, changes }) => { ... }); +``` + * `trait:custom` Event to use in case of [custom Trait Manager UI](https://grapesjs.com/docs/modules/Traits.html#custom-trait-manager). ```javascript diff --git a/docs/api/undo_manager.md b/docs/api/undo_manager.md index e83254fea..a3d02d661 100644 --- a/docs/api/undo_manager.md +++ b/docs/api/undo_manager.md @@ -204,6 +204,22 @@ stack.each(item => ...); Returns **Collection** +## skip + +Execute the provided callback temporarily stopping tracking changes + +### Parameters + +* `clb` **[Function][17]** The callback to execute with changes tracking stopped + +### Examples + +```javascript +um.skip(() => { + // Do stuff without tracking +}); +``` + ## clear Clear the stack @@ -247,3 +263,5 @@ Returns **this** [15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object [16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean + +[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function diff --git a/src/dom_components/model/Component.ts b/src/dom_components/model/Component.ts index f86cb1435..7610e7ec0 100644 --- a/src/dom_components/model/Component.ts +++ b/src/dom_components/model/Component.ts @@ -1230,8 +1230,7 @@ export default class Component extends StyleableModel { /** * Override original clone method * @private - */ - /** @ts-ignore */ + * @ts-ignore */ clone(opt: { symbol?: boolean; symbolInv?: boolean } = {}): this { const em = this.em; const attr = { ...this.attributes };