Add traits api docs

docs/.vuepress/config.js

@@ -88,6 +88,8 @@ module.exports = {
         ['/api/selector_manager', 'Selector Manager'],
         ['/api/selector', `${subDivider}Selector`],
         ['/api/state', `${subDivider}State`],
+        ['/api/trait_manager', 'Trait Manager'],
+        ['/api/trait', `${subDivider}Trait`],
         ['/api/css_composer', 'CSS Composer'],
         ['/api/css_rule', `${subDivider}CssRule`],
         ['/api/modal_dialog', 'Modal'],

docs/api.js

@@ -27,6 +27,7 @@ const getEventsMdFromTypes = async (filePath) => {
       .replace(/\\`/gi, '`')
       .replace(/##/gi, '')
       .replace(/\\\[/gi, '[')
+      .replace(/\]\\\(/gi, '](')
       .trim();
 
     return result
@@ -57,6 +58,8 @@ async function generateDocs () {
     ['style_manager/model/PropertyStack.ts', 'property_stack.md'],
     ['style_manager/model/Layer.ts', 'layer.md'],
     ['storage_manager/index.ts', 'storage_manager.md'],
+    ['trait_manager/index.ts', 'trait_manager.md'],
+    ['trait_manager/model/Trait.ts', 'trait.md'],
     ['device_manager/index.ts', 'device_manager.md'],
     ['device_manager/model/Device.ts', 'device.md'],
     ['selector_manager/index.ts', 'selector_manager.md'],

docs/api/block_manager.md

@@ -66,7 +66,7 @@ editor.on('block:drag', (block) => { ... });
 editor.on('block:drag:stop', (component, block) => { ... });
 ```
 
-* `block:custom` Event to use in case of [custom Block Manager UI]\(https://grapesjs.com/docs/modules/Blocks.html#customization).
+* `block:custom` Event to use in case of [custom Block Manager UI](https://grapesjs.com/docs/modules/Blocks.html#customization).
 
 ```javascript
 editor.on('block:custom', ({ container, blocks, ... }) => { ... });
@@ -191,6 +191,30 @@ Updated when the drag starts and cleared once it's done.
 
 Returns **([Block] | [undefined][6])** 
 
+## getBlocksByCategory
+
+Get blocks by category.
+
+### Parameters
+
+*   `blocks` **[Array][4]\<Block>?** 
+
+### Examples
+
+```javascript
+blockManager.getBlocksByCategory();
+// Returns an array of items of this type
+// > { category?: Category; items: Block[] }
+
+// NOTE: The item without category is the one containing blocks without category.
+
+// You can also get the same output format by passing your own array of Blocks
+const myFilteredBlocks: Block[] = [...];
+blockManager.getBlocksByCategorymyFilteredBlocks
+```
+
+Returns **[Array][4]\<BlocksByCategory>** 
+
 ## render
 
 Render blocks

docs/api/trait.md

@@ -0,0 +1,143 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## Trait
+
+
+
+### Parameters
+
+*   `prop` **TraitProperties** 
+*   `em` **EditorModel** 
+
+### Properties
+
+*   `id` **[String][1]** Trait id, eg. `my-trait-id`.
+*   `type` **[String][1]** Trait type, defines how the trait should be rendered. Possible values: `text` (default), `number`, `select`, `checkbox`, `color`, `button`
+*   `label` **[String][1]** The trait label to show for the rendered trait.
+*   `name` **[String][1]** The name of the trait used as a key for the attribute/property. By default, the name is used as attribute name or property in case `changeProp` in enabled.
+*   `default` **[String][1]** Default value to use in case the value is not defined on the component.
+*   `placeholder` **[String][1]** Placeholder to show inside the default input (if the UI type allows it).
+*   `category` **[String][1]?** Trait category.
+*   `changeProp` **[Boolean][2]** If `true`, the trait value is applied on the component property, otherwise, on component attributes.
+
+### getId
+
+Get the trait id.
+
+Returns **[String][1]** 
+
+### getType
+
+Get the trait type.
+
+Returns **[String][1]** 
+
+### getName
+
+Get the trait name.
+
+Returns **[String][1]** 
+
+### getLabel
+
+Get the trait label.
+
+#### Parameters
+
+*   `opts` **[Object][3]** Options. (optional, default `{}`)
+
+    *   `opts.locale` **[Boolean][2]** Use the locale string from i18n module. (optional, default `true`)
+
+Returns **[String][1]** 
+
+### getValue
+
+Get the trait value.
+The value is taken from component attributes by default or from properties if the trait has the `changeProp` enabled.
+
+#### Parameters
+
+*   `opts` **[Object][3]** Options. (optional, default `{}`)
+
+    *   `opts.useType` **[Boolean][2]** Get the value based on type (eg. the checkbox will always return a boolean). (optional, default `false`)
+
+Returns **any** 
+
+### setValue
+
+Update the trait value.
+The value is applied on component attributes by default or on properties if the trait has the `changeProp` enabled.
+
+#### Parameters
+
+*   `value` **any** Value of the trait.
+*   `opts` **[Object][3]** Options. (optional, default `{}`)
+
+    *   `opts.partial` **[Boolean][2]?** If `true` the update won't be considered complete (not stored in UndoManager).
+
+### getDefault
+
+Get default value.
+
+### getOptions
+
+Get trait options.
+
+Returns **[Array][4]\<TraitOption>** 
+
+### getOption
+
+Get current selected option or by id.
+
+#### Parameters
+
+*   `id` **[String][1]?** Option id.
+
+Returns **([Object][3] | null)** 
+
+### getOptionId
+
+Get the option id from the option object.
+
+#### Parameters
+
+*   `option` **[Object][3]** Option object
+
+Returns **[String][1]** Option id
+
+### getOptionLabel
+
+Get option label.
+
+#### Parameters
+
+*   `id` **([String][1] | [Object][3])** Option id or the option object
+*   `opts` **[Object][3]** Options (optional, default `{}`)
+
+    *   `opts.locale` **[Boolean][2]** Use the locale string from i18n module (optional, default `true`)
+
+Returns **[String][1]** Option label
+
+### getCategoryLabel
+
+Get category label.
+
+#### Parameters
+
+*   `opts` **[Object][3]** Options. (optional, default `{}`)
+
+    *   `opts.locale` **[Boolean][2]** Use the locale string from i18n module. (optional, default `true`)
+
+Returns **[String][1]** 
+
+### runCommand
+
+Run the trait command (used on the button trait type).
+
+[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

docs/api/trait_manager.md

@@ -0,0 +1,135 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## Traits
+
+You can customize the initial state of the module from the editor initialization, by passing the following [Configuration Object][1]
+
+```js
+const editor = grapesjs.init({
+ traitManager: {
+   // options
+ }
+})
+```
+
+Once the editor is instantiated you can use the API below and listen to the events. Before using these methods, you should get the module from the instance.
+
+```js
+// Listen to events
+editor.on('trait:value', () => { ... });
+
+// Use the Trait Manager API
+const tm = editor.Traits;
+tm.select(...)
+```
+
+## Available Events
+* `trait:value` Trait value updated.
+
+```javascript
+editor.on('trait:value', ({ trait, component, value }) => { ... });
+```
+
+* `trait:custom` Event to use in case of [custom Trait Manager UI](https://grapesjs.com/docs/modules/Traits.html#custom-trait-manager).
+
+```javascript
+editor.on('trait:custom', ({ container }) => { ... });
+```
+
+* `trait` Catch-all event for all the events mentioned above. An object containing all the available data about the triggered event is passed as an argument to the callback.
+
+```javascript
+editor.on('trait', ({ event, model, ... }) => { ... });
+```
+
+[Component]: component.html
+
+[Trait]: trait.html
+
+## getConfig
+
+Get configuration object
+
+Returns **[Object][2]** 
+
+## select
+
+Select traits from a component.
+
+### Parameters
+
+*   `component` **[Component]** 
+
+### Examples
+
+```javascript
+tm.select(someComponent);
+```
+
+## getCategories
+
+Get trait categories from the currently selected component.
+
+### Examples
+
+```javascript
+const traitCategories: Category[] = tm.getCategories();
+```
+
+Returns **[Array][3]\<Category>** 
+
+## getTraits
+
+Get traits from the currently selected component.
+
+### Examples
+
+```javascript
+const currentTraits: Trait[] = tm.getTraits();
+```
+
+Returns **[Array][3]<[Trait]>** 
+
+## getTraitsByCategory
+
+Get traits by category from the currently selected component.
+
+### Parameters
+
+*   `traits` **[Array][3]\<Trait>?** 
+
+### Examples
+
+```javascript
+tm.getTraitsByCategory();
+// Returns an array of items of this type
+// > { category?: Category; items: Trait[] }
+
+// NOTE: The item without category is the one containing traits without category.
+
+// You can also get the same output format by passing your own array of Traits
+const myFilteredTraits: Trait[] = [...];
+tm.getTraitsByCategory(myFilteredTraits);
+```
+
+Returns **[Array][3]\<TraitsByCategory>** 
+
+## addType
+
+Add new trait type.
+More about it here: [Define new Trait type][4].
+
+### Parameters
+
+*   `name` **[string][5]** Type name.
+*   `methods` **[Object][2]** Object representing the trait.
+
+[1]: https://github.com/GrapesJS/grapesjs/blob/master/src/trait_manager/config/config.ts
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+
+[4]: https://grapesjs.com/docs/modules/Traits.html#define-new-trait-type
+
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

docs/modules/Traits.md

@@ -626,8 +626,16 @@ editor.on('trait:custom', props => {
 });
 ```
 
-In the example below we'll replicate most of the default functionality by using solely the Traits API.
+In the example below we'll replicate most of the default functionality by using solely the [Traits API].
 
-TODO
+<demo-viewer value="v8cgkLfr" height="500" darkcode/>
 
-<demo-viewer value="v8cgkLfr" height="500" darkcode/>
+
+
+
+## Events
+
+For a complete list of available events, you can check it [here](/api/trait_manager.html#available-events).
+
+
+[Traits API]: </api/trait_manager.html>

src/trait_manager/config/config.ts

@@ -14,6 +14,7 @@ export interface TraitManagerConfig {
 
   /**
    * Avoid rendering the default Trait Manager UI.
+   * More about it here: [Custom Trait Manager](https://grapesjs.com/docs/modules/Traits.html#custom-trait-manager).
    * @default false
    */
   custom?: boolean;

src/trait_manager/index.ts

@@ -1,3 +1,33 @@
+/**
+ * You can customize the initial state of the module from the editor initialization, by passing the following [Configuration Object](https://github.com/GrapesJS/grapesjs/blob/master/src/trait_manager/config/config.ts)
+ * ```js
+ * const editor = grapesjs.init({
+ *  traitManager: {
+ *    // options
+ *  }
+ * })
+ * ```
+ *
+ *
+ * Once the editor is instantiated you can use the API below and listen to the events. Before using these methods, you should get the module from the instance.
+ *
+ * ```js
+ * // Listen to events
+ * editor.on('trait:value', () => { ... });
+ *
+ * // Use the Trait Manager API
+ * const tm = editor.Traits;
+ * tm.select(...)
+ * ```
+ *
+ * {REPLACE_EVENTS}
+ *
+ * [Component]: component.html
+ * [Trait]: trait.html
+ *
+ * @module Traits
+ */
+
 import { debounce } from 'underscore';
 import { Module } from '../abstract';
 import { Model } from '../common';
@@ -43,7 +73,7 @@ export default class TraitManager extends Module<TraitManagerConfigModule> {
    * Get configuration object
    * @name getConfig
    * @function
-   * @return {Object}
+   * @returns {Object}
    */
 
   /**
@@ -65,10 +95,10 @@ export default class TraitManager extends Module<TraitManagerConfigModule> {
   }
 
   /**
-   * Select traits from component.
+   * Select traits from a component.
    * @param {[Component]} component
    * @example
-   * traitManager.select(someComponent);
+   * tm.select(someComponent);
    */
   select(component?: Component) {
     const traits = component?.getTraits() || [];
@@ -76,9 +106,24 @@ export default class TraitManager extends Module<TraitManagerConfigModule> {
     this.__trgCustom();
   }
 
+  /**
+   * Get trait categories from the currently selected component.
+   * @returns {Array<Category>}
+   * @example
+   * const traitCategories: Category[] = tm.getCategories();
+   *
+   */
+  getCategories(): Category[] {
+    const cmp = this.state.get('component');
+    const categories = cmp?.traits.categories?.models || [];
+    return [...categories];
+  }
+
   /**
    * Get traits from the currently selected component.
-   * @return {Array<Trait>}
+   * @returns {Array<[Trait]>}
+   * @example
+   * const currentTraits: Trait[] = tm.getTraits();
    */
   getTraits() {
     return this.getCurrent();
@@ -87,7 +132,7 @@ export default class TraitManager extends Module<TraitManagerConfigModule> {
   /**
    * Get traits by category from the currently selected component.
    * @example
-   * traitManager.getTraitsByCategory();
+   * tm.getTraitsByCategory();
    * // Returns an array of items of this type
    * // > { category?: Category; items: Trait[] }
    *
@@ -95,36 +140,30 @@ export default class TraitManager extends Module<TraitManagerConfigModule> {
    *
    * // You can also get the same output format by passing your own array of Traits
    * const myFilteredTraits: Trait[] = [...];
-   * traitManager.getTraitsByCategory(myFilteredTraits);
+   * tm.getTraitsByCategory(myFilteredTraits);
    */
   getTraitsByCategory(traits?: Trait[]): TraitsByCategory[] {
     return getItemsByCategory<Trait>(traits || this.getTraits());
   }
 
   /**
-   *
-   * Get Traits viewer
-   * @private
+   * Add new trait type.
+   * More about it here: [Define new Trait type](https://grapesjs.com/docs/modules/Traits.html#define-new-trait-type).
+   * @param {string} name Type name.
+   * @param {Object} methods Object representing the trait.
    */
-  getTraitsViewer() {
-    return this.view;
-  }
-
-  /**
-   * Add new trait type
-   * @param {string} name Type name
-   * @param {Object} methods Object representing the trait
-   */
-  addType<T>(name: string, trait: CustomTrait<T>) {
+  addType<T>(name: string, methods: CustomTrait<T>) {
     const baseView = this.getType('text');
     //@ts-ignore
-    this.types[name] = baseView.extend(trait);
+    this.types[name] = baseView.extend(methods);
   }
 
   /**
    * Get trait type
    * @param {string} name Type name
-   * @return {Object}
+   * @returns {Object}
+   * @private
+   * const traitView = tm.getType('text');
    */
   getType(name: string) {
     return this.getTypes()[name];
@@ -133,19 +172,19 @@ export default class TraitManager extends Module<TraitManagerConfigModule> {
   /**
    * Get all trait types
    * @returns {Object}
+   * @private
    */
   getTypes() {
     return this.types;
   }
 
   /**
-   * Get trait categories from the currently selected component.
-   * @return {Array<Category>}
+   *
+   * Get Traits viewer
+   * @private
    */
-  getCategories(): Category[] {
-    const cmp = this.state.get('component');
-    const categories = cmp?.traits.categories?.models || [];
-    return [...categories];
+  getTraitsViewer() {
+    return this.view;
   }
 
   getCurrent() {

src/trait_manager/types.ts

@@ -182,7 +182,7 @@ export enum TraitsEvents {
   value = 'trait:value',
 
   /**
-   * @event `trait:custom` Event to use in case of [custom Trait Manager UI](https://grapesjs.com/docs/modules/Traits.html#customization).
+   * @event `trait:custom` Event to use in case of [custom Trait Manager UI](https://grapesjs.com/docs/modules/Traits.html#custom-trait-manager).
    * @example
    * editor.on('trait:custom', ({ container }) => { ... });
    */