Update and add Property doc

docs/.vuepress/config.js

@@ -73,6 +73,7 @@ module.exports = {
         ['/api/page', `${subDivider}Page`],
         ['/api/style_manager', 'Style Manager'],
         ['/api/sector', `${subDivider}Sector`],
+        ['/api/property', `${subDivider}Property`],
         ['/api/storage_manager', 'Storage Manager'],
         ['/api/device_manager', 'Device Manager'],
         ['/api/device', `${subDivider}Device`],

docs/api.js

@@ -22,6 +22,7 @@ async function generateDocs () {
     ['panels/index.js', 'panels.md'],
     ['style_manager/index.js', 'style_manager.md'],
     ['style_manager/model/Sector.js', 'sector.md'],
+    ['style_manager/model/Property.js', 'property.md'],
     ['storage_manager/index.js', 'storage_manager.md'],
     ['device_manager/index.js', 'device_manager.md'],
     ['device_manager/model/Device.js', 'device.md'],

docs/api/component.md

@@ -28,10 +28,10 @@ component.get('tagName');
 *   `attributes` **[Object][2]?** Key-value object of the component's attributes, eg. `{ title: 'Hello' }` Default: `{}`
 *   `name` **[String][1]?** Name of the component. Will be used, for example, in Layers and badges
 *   `removable` **[Boolean][3]?** When `true` the component is removable from the canvas, default: `true`
-*   `draggable` **([Boolean][3] | [String][1])?** Indicates if it's possible to drag the component inside others.
+*   `draggable` **([Boolean][3] | [String][1] | [Function][4])?** Indicates if it's possible to drag the component inside others.
     You can also specify a query string to indentify elements,
     eg. `'.some-class[title=Hello], [data-gjs-type=column]'` means you can drag the component only inside elements
-    containing `some-class` class and `Hello` title, and `column` components. Default: `true`
+    containing `some-class` class and `Hello` title, and `column` components. In the case of a function, target and destination components are passed as arguments, return a Boolean to indicate if the drag is possible. Default: `true`
 *   `droppable` **([Boolean][3] | [String][1] | [Function][4])?** Indicates if it's possible to drop other components inside. You can use
     a query string as with `draggable`. In the case of a function, target and destination components are passed as arguments, return a Boolean to indicate if the drop is possible. Default: `true`
 *   `badgable` **[Boolean][3]?** Set to false if you don't want to see the badge (with the name) over the component. Default: `true`
@@ -485,9 +485,41 @@ component.parent();
 
 Returns **([Component][9] | null)** 
 
+### getTraits
+
+Get traits.
+
+#### Examples
+
+```javascript
+const traits = component.getTraits();
+console.log(traits);
+// [Trait, Trait, Trait, ...]
+```
+
+Returns **[Array][5]\<Trait>** 
+
+### setTraits
+
+Replace current collection of traits with a new one.
+
+#### Parameters
+
+*   `traits` **[Array][5]<[Object][2]>** Array of trait definitions
+
+#### Examples
+
+```javascript
+const traits = component.setTraits([{ type: 'checkbox', name: 'disabled'}, ...]);
+console.log(traits);
+// [Trait, ...]
+```
+
+Returns **[Array][5]\<Trait>** 
+
 ### getTrait
 
-Get the trait by id/name
+Get the trait by id/name.
 
 #### Parameters
 
@@ -500,11 +532,11 @@ const traitTitle = component.getTrait('title');
 traitTitle && traitTitle.set('label', 'New label');
 ```
 
-Returns **Trait** Trait model
+Returns **(Trait | null)** Trait getModelToStyle
 
 ### updateTrait
 
-Update a trait
+Update a trait.
 
 #### Parameters
 
@@ -555,11 +587,11 @@ component.removeTrait('title');
 component.removeTrait(['title', 'id']);
 ```
 
-Returns **[Array][5]** Array of removed traits
+Returns **[Array][5]\<Trait>** Array of removed traits
 
 ### addTrait
 
-Add trait/s by id/s.
+Add new trait/s.
 
 #### Parameters
 
@@ -577,7 +609,7 @@ component.addTrait({
 component.addTrait(['title', {...}, ...]);
 ```
 
-Returns **[Array][5]** Array of added traits
+Returns **[Array][5]\<Trait>** Array of added traits
 
 ### getName
 

docs/api/css_rule.md

@@ -14,7 +14,7 @@
 *   `singleAtRule` **[Boolean][4]?** This property is used only on at-rules, like 'page' or 'font-face', where the block containes only style declarations
 *   `state` **[String][3]?** State of the rule, eg: `hover`, `focused`
 *   `important` **([Boolean][4] | [Array][1]<[String][3]>)?** If true, sets `!important` on all properties. You can also pass an array to specify properties on which use important
-*   `stylable` **[Boolean][4]?** Indicates if the rule is stylable from the editor
+*   `stylable` **[Boolean][4]?** Indicates if the rule is stylable from the editor[Device]: device.html[State]: state.html[Component]: component.html
 
 ### getAtRule
 
@@ -72,6 +72,45 @@ cssRule.getDeclaration() // ".class1{color:red;}"
 
 Returns **[String][3]** 
 
+### getDevice
+
+Get the Device the rule is related to.
+
+#### Examples
+
+```javascript
+const device = rule.getDevice();
+console.log(device?.getName());
+```
+
+Returns **([Device] | null)** 
+
+### getState
+
+Get the State the rule is related to.
+
+#### Examples
+
+```javascript
+const state = rule.getState();
+console.log(state?.getLabel());
+```
+
+Returns **([State] | null)** 
+
+### getComponent
+
+Returns the related Component (valid only for component-specific rules).
+
+#### Examples
+
+```javascript
+const cmp = rule.getComponent();
+console.log(cmp?.toHTML());
+```
+
+Returns **([Component] | null)** 
+
 ### toCSS
 
 Return the CSS string of the rule

docs/api/property.md

@@ -0,0 +1,122 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## Property
+
+
+
+### Properties
+
+*   `id` **[String][1]** Property id, eg. `my-property-id`.
+*   `property` **[String][1]** Related CSS property name, eg. `text-align`.
+*   `label` **[String][1]** Label to use in UI, eg. `Text Align`.
+*   `default` **[String][1]** Defaul value of the property.
+
+### getId
+
+Get property id.
+
+Returns **[String][1]** 
+
+### getType
+
+Get the property type.
+The type of the property is defined on property creation and based on its value the proper Property class is assigned.
+The default type is `base`.
+
+Returns **[String][1]** 
+
+### getName
+
+Get name (the CSS property name).
+
+Returns **[String][1]** 
+
+### getLabel
+
+Get property label.
+
+#### Parameters
+
+*   `opts` **[Object][2]** Options (optional, default `{}`)
+
+    *   `opts.locale` **[Boolean][3]** Use the locale string from i18n module (optional, default `true`)
+
+Returns **[String][1]** 
+
+### getValue
+
+Get property value.
+
+#### Parameters
+
+*   `opts` **[Object][2]** Options (optional, default `{}`)
+
+    *   `opts.noDefault` **[Boolean][3]** Avoid returning the default value (optional, default `false`)
+
+Returns **[String][1]** 
+
+### hasValue
+
+Check if the property has value.
+
+#### Parameters
+
+*   `opts` **[Object][2]** Options (optional, default `{}`)
+
+    *   `opts.noParent` **[Boolean][3]** Ignore the value if it comes from the parent target. (optional, default `false`)
+
+Returns **[Boolean][3]** 
+
+### getStyle
+
+Get the CSS style object of the property.
+
+#### Parameters
+
+*   `opts`   (optional, default `{}`)
+
+#### Examples
+
+```javascript
+// In case the property is `color` with a value of `red`.
+console.log(property.getStyle());
+// { color: 'red' };
+```
+
+Returns **[Object][2]** 
+
+### getDefaultValue
+
+Get the default value.
+
+Returns **[string][1]** 
+
+### upValue
+
+Update the value.
+The change is also propagated to the selected targets (eg. CSS rule).
+
+#### Parameters
+
+*   `value` **[String][1]** New value
+*   `opts` **[Object][2]** Options (optional, default `{}`)
+
+    *   `opts.partial` **[Boolean][3]** If `true` the update on targets won't be considered complete (not stored in UndoManager) (optional, default `false`)
+    *   `opts.noTarget` **[Boolean][3]** If `true` the change won't be propagated to selected targets. (optional, default `false`)
+
+### clear
+
+Clear the value.
+The change is also propagated to the selected targets (eg. the css property is cleared).
+
+#### Parameters
+
+*   `opts` **[Object][2]** Options (optional, default `{}`)
+
+    *   `opts.noTarget` **[Boolean][3]** If `true` the change won't be propagated to selected targets. (optional, default `false`)
+
+[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean

docs/api/sector.md

@@ -49,6 +49,13 @@ Update Sector open state
 
 Get sector properties.
 
+#### Parameters
+
+*   `opts` **[Object][4]** Options (optional, default `{}`)
+
+    *   `opts.withValue` **[Boolean][2]** Get only properties with value (optional, default `false`)
+    *   `opts.withParentValue` **[Boolean][2]** Get only properties with parent value (optional, default `false`)
+
 Returns **[Array][3]<[Property]>** 
 
 [1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

src/style_manager/index.js

@@ -33,6 +33,7 @@
  * [Sector]: sector.html
  * [CssRule]: css_rule.html
  * [Component]: component.html
+ * [Property]: property.html
  *
  * @module StyleManager
  */

src/style_manager/model/Property.js

@@ -2,11 +2,19 @@ import { Model } from 'common';
 import { isUndefined, isString, result, keys } from 'underscore';
 import { capitalize } from 'utils/mixins';
 
+/**
+ * @typedef Property
+ * @property {String} id Property id, eg. `my-property-id`.
+ * @property {String} property Related CSS property name, eg. `text-align`.
+ * @property {String} label Label to use in UI, eg. `Text Align`.
+ * @property {String} default Defaul value of the property.
+ *
+ */
 export default class Property extends Model {
   initialize(props = {}, opts = {}) {
     this.em = opts.em;
     const id = this.get('id') || '';
-    const name = this.get('name') || '';
+    const name = this.get('name') || this.get('label') || '';
     !this.get('property') && this.set('property', (name || id).replace(/ /g, '-'));
     const prop = this.get('property');
     !this.get('id') && this.set('id', prop);
@@ -64,7 +72,9 @@ export default class Property extends Model {
   }
 
   /**
-   * Get property type.
+   * Get the property type.
+   * The type of the property is defined on property creation and based on its value the proper Property class is assigned.
+   * The default type is `base`.
    * @returns {String}
    */
   getType() {
@@ -72,7 +82,7 @@ export default class Property extends Model {
   }
 
   /**
-   * Get property name (usually is the CSS property name).
+   * Get name (the CSS property name).
    * @returns {String}
    */
   getName() {
@@ -88,12 +98,14 @@ export default class Property extends Model {
   getLabel(opts = {}) {
     const { locale = true } = opts;
     const id = this.getId();
-    const name = this.get('name');
+    const name = this.get('name') || this.get('label');
     return (locale && this.em?.t(`styleManager.properties.${id}`)) || name;
   }
 
   /**
    * Get property value.
+   * @param {Object} [opts={}] Options
+   * @param {Boolean} [opts.noDefault=false] Avoid returning the default value
    * @returns {String}
    */
   getValue(opts = {}) {
@@ -103,9 +115,9 @@ export default class Property extends Model {
   }
 
   /**
-   * Check if the property has value
+   * Check if the property has value.
    * @param {Object} [opts={}] Options
-   * @param {Boolean} [opts.noParent=false] Ignore the value if from parent target.
+   * @param {Boolean} [opts.noParent=false] Ignore the value if it comes from the parent target.
    * @returns {Boolean}
    */
   hasValue(opts = {}) {
@@ -116,25 +128,51 @@ export default class Property extends Model {
   }
 
   /**
-   * Clear value
+   * Get the CSS style object of the property.
+   * @return {Object}
+   * @example
+   * // In case the property is `color` with a value of `red`.
+   * console.log(property.getStyle());
+   * // { color: 'red' };
    */
-  clear(opts = {}) {
-    this._up(this.__getClearProps(), { ...opts, __clear: true });
+  getStyle(opts = {}) {
+    return { [this.getName()]: this.__getFullValue(opts) };
   }
 
   /**
-   * Get CSS style object of the propeprty
-   * @return {Object}
+   * Get the default value.
+   * @return {string}
    */
-  getStyle(opts = {}) {
-    return { [this.getName()]: this.__getFullValue(opts) };
+  getDefaultValue() {
+    const def = this.get('default');
+    return `${!isUndefined(def) ? def : this.get('defaults')}`;
   }
 
-  upValue(value, opts) {
+  /**
+   * Update the value.
+   * The change is also propagated to the selected targets (eg. CSS rule).
+   * @param {String} value New value
+   * @param {Object} [opts={}] Options
+   * @param {Boolean} [opts.partial=false] If `true` the update on targets won't be considered complete (not stored in UndoManager)
+   * @param {Boolean} [opts.noTarget=false] If `true` the change won't be propagated to selected targets.
+   */
+  upValue(value, opts = {}) {
+    if (opts.noTarget) opts.__up = true;
     const parsed = value === null || value === '' ? this.__getClearProps() : this.__parseValue(value, opts);
     return this._up(parsed, opts);
   }
 
+  /**
+   * Clear the value.
+   * The change is also propagated to the selected targets (eg. the css property is cleared).
+   * @param {Object} [opts={}] Options
+   * @param {Boolean} [opts.noTarget=false] If `true` the change won't be propagated to selected targets.
+   */
+  clear(opts = {}) {
+    if (opts.noTarget) opts.__up = true;
+    this._up(this.__getClearProps(), { ...opts, __clear: true });
+  }
+
   __parseValue(value, opts) {
     return this.parseValue(value, opts);
   }
@@ -174,6 +212,7 @@ export default class Property extends Model {
    * @param {any} value
    * @param {Boolen} [complete=true] Indicates if it's a final state
    * @param {Object} [opts={}] Options
+   * @private
    */
   setValueFromInput(value, complete, opts = {}) {
     this.setValue(value, complete, { ...opts, fromInput: 1 });
@@ -264,16 +303,6 @@ export default class Property extends Model {
     return res.map(i => i.trim());
   }
 
-  /**
-   * Get the default value
-   * @return {string}
-   * @private
-   */
-  getDefaultValue() {
-    const def = this.get('default');
-    return `${!isUndefined(def) ? def : this.get('defaults')}`;
-  }
-
   __getFullValue({ withDefault } = {}) {
     return !this.hasValue() && withDefault ? this.getDefaultValue() : this.getFullValue();
   }