Source: lib/kss_section.js

  1. 'use strict';
  3. const KssModifier = require('./kss_modifier'),
  4.   KssParameter = require('./kss_parameter');
  6. /**
  7.  * The `kss/lib/kss_section` module is normally accessed via the
  8.  * [`KssSection()`]{@link module:kss.KssSection} class of the `kss` module:
  9.  * ```
  10.  * const KssSection = require('kss').KssSection;
  11.  * ```
  12.  * @private
  13.  * @module kss/lib/kss_section
  14.  */
  16. /**
  17.  * A KssSection object represents a single section of a `KssStyleGuide`.
  18.  *
  19.  * A section of a style guide can be used for:
  20.  * - a category of sub-sections, since sections are hierarchical
  21.  * - a component in a design
  22.  * - a mixin (or similar concept) of a CSS preprocessor
  23.  *
  24.  * This class is normally accessed via the [`kss`]{@link module:kss} module:
  25.  * ```
  26.  * const KssSection = require('kss').KssSection;
  27.  * ```
  28.  *
  29.  * @alias module:kss.KssSection
  30.  */
  31. class KssSection {
  33.   /**
  34.    * Creates a KssSection object and stores the given data.
  35.    *
  36.    * If passed an object, it will add the properties to the section.
  37.    *
  38.    * @param {Object} [data] An object of data.
  39.    */
  40.   constructor(data) {
  41.     data = data || {};
  43.     this.meta = {
  44.       styleGuide: data.styleGuide || null,
  45.       raw: data.raw || '',
  46.       customPropertyNames: [],
  47.       depth: data.depth || 0
  48.     };
  50.     this.data = {
  51.       header: '',
  52.       description: '',
  53.       deprecated: false,
  54.       experimental: false,
  55.       reference: '',
  56.       referenceNumber: '',
  57.       referenceURI: '',
  58.       weight: 0,
  59.       markup: '',
  60.       colors: [],
  61.       source: {
  62.         filename: '',
  63.         path: '',
  64.         line: ''
  65.       },
  66.       modifiers: [],
  67.       parameters: []
  68.     };
  70.     // Loop through the given properties.
  71.     for (let name in data) {
  72.       // istanbul ignore else
  73.       if (data.hasOwnProperty(name)) {
  74.         // If the property is defined in this.data, add it via our API.
  75.         if (this.data.hasOwnProperty(name)) {
  76.           this[name](data[name]);
  78.           // If the property isn't defined in meta or data, add a custom property.
  79.         } else if (!this.meta.hasOwnProperty(name)) {
  80.           this.custom(name, data[name]);
  81.         }
  82.       }
  83.     }
  84.   }
  86.   /**
  87.    * Return the `KssSection` as a JSON object.
  88.    *
  89.    * @returns {Object} A JSON object representation of the KssSection.
  90.    */
  91.   toJSON() {
  92.     /* eslint-disable key-spacing */
  93.     let returnObject = {
  94.       header: this.header(),
  95.       description: this.description(),
  96.       deprecated: this.deprecated(),
  97.       experimental: this.experimental(),
  98.       reference: this.reference(),
  99.       referenceNumber: this.referenceNumber(),
  100.       referenceURI: this.referenceURI(),
  101.       weight: this.weight(),
  102.       colors: this.colors(),
  103.       markup: this.markup(),
  104.       source: this.source(),
  105.       // Include meta as well.
  106.       depth: this.depth()
  107.     };
  108.     /* eslint-enable key-spacing */
  110.     returnObject.modifiers = this.modifiers().map(modifier => {
  111.       return modifier.toJSON();
  112.     });
  113.     returnObject.parameters = this.parameters().map(parameter => {
  114.       return parameter.toJSON();
  115.     });
  117.     // Add custom properties to the JSON object.
  118.     for (let i = 0; i < this.meta.customPropertyNames.length; i++) {
  119.       // istanbul ignore else
  120.       if (typeof this.custom(this.meta.customPropertyNames[i]) !== 'undefined') {
  121.         returnObject[this.meta.customPropertyNames[i]] = this.custom(this.meta.customPropertyNames[i]);
  122.       }
  123.     }
  125.     return returnObject;
  126.   }
  128.   /**
  129.    * Gets or sets the `KssStyleGuide` object this `KssSection` is associated with.
  130.    *
  131.    * If the `styleGuide` value is provided, the `KssStyleGuide` for this section
  132.    * is set. Otherwise, the `KssStyleGuide` of the section is returned.
  133.    *
  134.    * @param {KssStyleGuide} [styleGuide] Optional. The `KssStyleGuide` that owns the
  135.    *   `KssSection`.
  136.    * @returns {KssStyleGuide|KssSection} If styleGuide is given, the current
  137.    *   `KssSection` object is returned to allow chaining of methods. Otherwise,
  138.    *   the `KssStyleGuide` object the section belongs to is returned.
  139.    */
  140.   styleGuide(styleGuide) {
  141.     if (typeof styleGuide === 'undefined') {
  142.       return this.meta.styleGuide;
  143.     }
  145.     this.meta.styleGuide = styleGuide;
  146.     // Tell the style guide about this section's custom property names.
  147.     this.meta.styleGuide.customPropertyNames(this.customPropertyNames());
  148.     // Allow chaining.
  149.     return this;
  150.   }
  152.   /**
  153.    * Gets or sets the header of the section, i.e. the first line in the description.
  154.    *
  155.    * If the `header` value is provided, the `header` for this section is set.
  156.    * Otherwise, the `header` of the section is returned.
  157.    *
  158.    * @param {string} [header] Optional. The header of the section.
  159.    * @returns {KssSection|string} If `header` is given, the `KssSection` object is
  160.    *   returned to allow chaining of methods. Otherwise, the header of the section
  161.    *   is returned.
  162.    */
  163.   header(header) {
  164.     if (typeof header === 'undefined') {
  165.       return this.data.header;
  166.     }
  168.     this.data.header = header;
  169.     // Allow chaining.
  170.     return this;
  171.   }
  173.   /**
  174.    * Gets or sets the description of the section.
  175.    *
  176.    * If the `description` value is provided, the `description` for this section is
  177.    * set. Otherwise, the `description` of the section is returned.
  178.    *
  179.    * @param {string} [description] Optional. The description of the section.
  180.    * @returns {KssSection|string} If `description` is given, the `KssSection`
  181.    *   object is returned to allow chaining of methods. Otherwise, the description
  182.    *   of the section is returned.
  183.    */
  184.   description(description) {
  185.     if (typeof description === 'undefined') {
  186.       return this.data.description;
  187.     }
  189.     this.data.description = description;
  190.     // Allow chaining.
  191.     return this;
  192.   }
  194.   /**
  195.    * Gets the list of custom properties of the section.
  196.    *
  197.    * Note that this method will return the actual custom properties set for this
  198.    * section, and not all of the custom properties available for the entire style
  199.    * guide. Use KssStyleGuide.customPropertyNames() for that list.
  200.    *
  201.    * @returns {string[]} An array of the section's custom property names.
  202.    */
  203.   customPropertyNames() {
  204.     return this.meta.customPropertyNames;
  205.   }
  207.   /**
  208.    * Gets or sets a custom property of the section.
  209.    *
  210.    * If the `value` is provided, the requested custom property of the section is
  211.    * set. Otherwise, the section's custom property with the name specified in the
  212.    * `name` parameter is returned.
  213.    *
  214.    * @param {string} name The name of the section's custom property.
  215.    * @param {*} [value] Optional. The value of the section's custom property.
  216.    * @returns {KssSection|*} If `value` is given, the `KssSection` object is
  217.    *   returned to allow chaining of methods. Otherwise, the section's custom
  218.    *   property, `name`, is returned.
  219.    */
  220.   custom(name, value) {
  221.     if (typeof value === 'undefined') {
  222.       /* eslint-disable no-undefined */
  223.       return this.meta.customPropertyNames.indexOf(name) === -1 ? undefined : this.data[name];
  224.     }
  226.     if (this.styleGuide()) {
  227.       this.styleGuide().customPropertyNames(name);
  228.     }
  229.     this.meta.customPropertyNames.push(name);
  230.     this.data[name] = value;
  231.     // Allow chaining.
  232.     return this;
  233.   }
  235.   /**
  236.    * Gets or sets the deprecated flag for the section.
  237.    *
  238.    * If the `deprecated` value is provided, the `deprecated` flag for this section
  239.    * is set. Otherwise, the `deprecated` flag for the section is returned.
  240.    *
  241.    * @param {boolean} [deprecated] Optional. The deprecated flag for the section.
  242.    * @returns {KssSection|boolean} If `deprecated` is given, the `KssSection`
  243.    *   object is returned to allow chaining of methods. Otherwise, the deprecated
  244.    *   flag for the section is returned.
  245.    */
  246.   deprecated(deprecated) {
  247.     if (typeof deprecated === 'undefined') {
  248.       return this.data.deprecated;
  249.     }
  251.     this.data.deprecated = !!deprecated;
  252.     // Allow chaining.
  253.     return this;
  254.   }
  256.   /**
  257.    * Gets or sets the experimental flag for the section.
  258.    *
  259.    * If the `experimental` value is provided, the `experimental` flag for this
  260.    * section is set. Otherwise, the `deprecated` flag for the section is returned.
  261.    *
  262.    * @param {boolean} [experimental] Optional. The experimental flag for the
  263.    *   section.
  264.    * @returns {KssSection|boolean} If `experimental` is given, the `KssSection`
  265.    *   object is returned to allow chaining of methods. Otherwise, the
  266.    *   experimental flag for the section is returned.
  267.    */
  268.   experimental(experimental) {
  269.     if (typeof experimental === 'undefined') {
  270.       return this.data.experimental;
  271.     }
  273.     this.data.experimental = !!experimental;
  274.     // Allow chaining.
  275.     return this;
  276.   }
  278.   /**
  279.    * Gets or sets the reference for the section.
  280.    *
  281.    * If the `reference` value is provided, the `reference` for this section is
  282.    * set. Otherwise, the `reference` for the section is returned.
  283.    *
  284.    * @param {string} [reference] Optional. The reference of the section.
  285.    * @returns {KssSection|string} If `reference` is given, the `KssSection` object
  286.    *   is returned to allow chaining of methods. Otherwise, the reference for the
  287.    *   section is returned.
  288.    */
  289.   reference(reference) {
  290.     if (typeof reference === 'undefined') {
  291.       return this.data.reference;
  292.     }
  294.     // @TODO: Tell the KssStyleGuide about the update.
  296.     reference = reference.toString();
  297.     // Normalize any " - " delimiters.
  298.     reference = reference.replace(/\s+\-\s+/g, ' - ');
  299.     // Remove trailing dot-zeros and periods.
  300.     reference = reference.replace(/\.$|(\.0){1,}$/g, '');
  302.     this.data.reference = reference;
  303.     // Allow chaining.
  304.     return this;
  305.   }
  307.   /**
  308.    * Gets or sets a numeric reference number for the section.
  309.    *
  310.    * If the `referenceNumber` value is provided, the `referenceNumber` for this
  311.    * section is set.
  312.    *
  313.    * If no parameters are given, this method returns a numeric reference number;
  314.    * if the style guide's references are already numeric (e.g. 2, 2.1.3, 3.2),
  315.    * then this method returns the same value as reference() does. Otherwise, an
  316.    * auto-incremented reference number will be returned.
  317.    *
  318.    * @param {string} [referenceNumber] Optional. The auto-incremented reference
  319.    *   number of the section.
  320.    * @returns {KssSection|string} If `referenceNumber` is given, the `KssSection`
  321.    *   object is returned to allow chaining of methods. Otherwise, the reference
  322.    *   number of the section is returned.
  323.    */
  324.   referenceNumber(referenceNumber) {
  325.     if (typeof referenceNumber === 'undefined') {
  326.       if (this.styleGuide() && this.styleGuide().hasNumericReferences()) {
  327.         return this.data.reference;
  328.       } else {
  329.         return this.data.referenceNumber;
  330.       }
  331.     }
  333.     this.data.referenceNumber = referenceNumber;
  334.     // Allow chaining.
  335.     return this;
  336.   }
  338.   /**
  339.    * Gets or sets the reference of the section, encoded as a valid URI fragment.
  340.    *
  341.    * If the `referenceURI` value is provided, the `referenceURI` for this section
  342.    * is set. Otherwise, the `referenceURI` of the section is returned.
  343.    *
  344.    * @param {string} [referenceURI] Optional. The referenceURI of the section.
  345.    * @returns {KssSection|string} If `referenceURI` is given, the `KssSection`
  346.    *   object is returned to allow chaining of methods. Otherwise, the
  347.    *   referenceURI of the section is returned.
  348.    */
  349.   referenceURI(referenceURI) {
  350.     if (typeof referenceURI === 'undefined') {
  351.       if (!this.data.referenceURI) {
  352.         this.data.referenceURI = encodeURI(
  353.           this.reference()
  354.             .replace(/ \- /g, '-')
  355.             .replace(/[^\w-]+/g, '-')
  356.             .toLowerCase()
  357.         );
  358.       }
  359.       return this.data.referenceURI;
  360.     }
  362.     this.data.referenceURI = referenceURI;
  363.     // Allow chaining.
  364.     return this;
  365.   }
  367.   /**
  368.    * Gets or sets the weight of the section.
  369.    *
  370.    * If the `weight` value is provided, the `weight` for this section is set.
  371.    * Otherwise, the `weight` of the section is returned.
  372.    *
  373.    * @param {number} [weight] Optional. The weight of the section as an integer.
  374.    * @returns {KssSection|number} If `weight` is given, the `KssSection` object
  375.    *   is returned to allow chaining of methods. Otherwise, the weight of the
  376.    *   section is returned.
  377.    */
  378.   weight(weight) {
  379.     if (typeof weight === 'undefined') {
  380.       return this.data.weight;
  381.     }
  383.     // @TODO: The weight needs to bubble-up to the KssStyleGuide weightMap.
  384.     this.data.weight = weight;
  385.     // Allow chaining.
  386.     return this;
  387.   }
  389.   /**
  390.    * Gets or sets the depth of the section.
  391.    *
  392.    * If the `depth` value is provided, the `depth` for this section is set.
  393.    * Otherwise, the `depth` of the section is returned.
  394.    *
  395.    * @param {number} [depth] Optional. The depth of the section as a positive
  396.    *   integer.
  397.    * @returns {KssSection|number} If `depth` is given, the `KssSection` object is
  398.    *   returned to allow chaining of methods. Otherwise, the depth of the section
  399.    *   is returned.
  400.    */
  401.   depth(depth) {
  402.     if (typeof depth === 'undefined') {
  403.       return this.meta.depth;
  404.     }
  406.     this.meta.depth = depth;
  407.     // Allow chaining.
  408.     return this;
  409.   }
  411.   /**
  412.    * Gets or sets the markup of the section.
  413.    *
  414.    * If the `markup` value is provided, the `markup` for this section is set.
  415.    * Otherwise, the `markup` of the section is returned.
  416.    *
  417.    * @param {string} [markup] Optional. The markup of the section.
  418.    * @returns {KssSection|string|boolean} If `markup` is given, the `KssSection` object is
  419.    *   returned to allow chaining of methods. Otherwise, the markup of the section
  420.    *   is returned, or `false` if none.
  421.    */
  422.   markup(markup) {
  423.     if (typeof markup === 'undefined') {
  424.       return this.data.markup;
  425.     }
  427.     this.data.markup = markup;
  428.     // Allow chaining.
  429.     return this;
  430.   }
  432.   /**
  433.    * Gets or sets the colors of the section.
  434.    *
  435.    * If the `colors` value is provided, the `colors` for this section is set.
  436.    * Otherwise, the `colors` of the section is returned.
  437.    *
  438.    * @param {Array} [colors] Collection of color object.
  439.    * @returns {KssSection|string|boolean} If `colors` is given, the `KssSection` object is
  440.    *   returned to allow chaining of methods. Otherwise, the colors of the section
  441.    *   is returned, or `false` if none.
  442.    */
  443.   colors(colors) {
  444.     if (typeof colors === 'undefined') {
  445.       return this.data.colors;
  446.     }
  448.     this.data.colors = colors;
  449.     // Allow chaining.
  450.     return this;
  451.   }
  453.   /**
  454.    * Gets or sets the file information of the file where the section was
  455.    * originally found.
  456.    *
  457.    * If the `source` parameter is provided, the `source` for this section is
  458.    * set. Otherwise, the `source` of the section is returned.
  459.    *
  460.    * The `source` object contains the following information:
  461.    * - filename: The name of the file.
  462.    * - path: The full path of the file.
  463.    * - line: The line number where the KSS comment is found.
  464.    *
  465.    * @param {{filename, path, line}} [source] The source file information where
  466.    *   the section was originally found.
  467.    * @returns {KssSection|{filename, path, line}} If `source` is given, the
  468.    *   `KssSection` object is returned to allow chaining of methods. Otherwise,
  469.    *   the source of the section is returned.
  470.    */
  471.   source(source) {
  472.     if (typeof source === 'undefined') {
  473.       return this.data.source;
  474.     }
  476.     if (source.filename) {
  477.       this.data.source.filename = source.filename;
  478.     }
  479.     if (source.path) {
  480.       this.data.source.path = source.path;
  481.     }
  482.     if (source.line) {
  483.       this.data.source.line = source.line;
  484.     }
  486.     // Allow chaining.
  487.     return this;
  488.   }
  490.   /**
  491.    * Gets the name of the file where the section was originally found.
  492.    *
  493.    * @returns {string} Returns the source file's path relative to the base path.
  494.    */
  495.   sourceFileName() {
  496.     return this.data.source.filename;
  497.   }
  499.   /**
  500.    * Gets the line number where the section was found in the original source file.
  501.    *
  502.    * @returns {string} Returns the source file's line number.
  503.    */
  504.   sourceLine() {
  505.     return this.data.source.line;
  506.   }
  508.   /**
  509.    * Gets or adds nested objects of the section.
  510.    *
  511.    * A common helper for `.modifiers()` and `.parameters()` methods.
  512.    *
  513.    * Different types of arguments for `properties` will yield different results:
  514.    * - `Object|Array`: If the value is an array of objects or an object, the
  515.    *   `properties` are added to this section.
  516.    * - `undefined`: Pass nothing to return all of the section's properties in an
  517.    *   array.
  518.    * - `integer`: Use a 0-based index to return the section's Nth property.
  519.    * - `string`: Use a string to return a specific modifier by name.
  520.    *
  521.    * @private
  522.    * @param {string} propertyName The name of property in `KssSection`.
  523.    * @param {Constructor} objectConstructor The constructor function for the type
  524.    *   of object the property is.
  525.    * @param {*} [properties] Optional. The properties to set for the section.
  526.    * @returns {*} If `properties` is given, the `KssSection` object is returned to
  527.    *   allow chaining of methods. Otherwise, the requested properties of the
  528.    *   section are returned.
  529.    */
  530.   _propertyHelper(propertyName, objectConstructor, properties) {
  531.     if (typeof properties === 'undefined') {
  532.       return this.data[propertyName];
  533.     }
  535.     // If we are given an object, assign the properties.
  536.     if (typeof properties === 'object') {
  537.       if (!(properties instanceof Array)) {
  538.         properties = [properties];
  539.       }
  540.       properties.forEach(property => {
  541.         let newProperty = (property instanceof objectConstructor) ? property : new objectConstructor(property);
  542.         newProperty.section(this);
  543.         this.data[propertyName].push(newProperty);
  544.       });
  545.       // Allow chaining.
  546.       return this;
  547.     }
  549.     // Otherwise, we should search for the requested property.
  550.     let query = properties,
  551.       index = parseInt(query);
  552.     if (typeof query === 'number' || typeof query === 'string' && query === (index + '')) {
  553.       return (index < this.data[propertyName].length) ? this.data[propertyName][index] : false;
  554.       // If the query can be converted to an integer, search by index instead.
  555.     } else {
  556.       // Otherwise, search for the property by name.
  557.       for (let i = 0; i < this.data[propertyName].length; i++) {
  558.         if (this.data[propertyName][i].name() === query) {
  559.           return this.data[propertyName][i];
  560.         }
  561.       }
  562.     }
  564.     // No matching property found.
  565.     return false;
  566.   }
  568.   /**
  569.    * Gets or adds modifiers of the section.
  570.    *
  571.    * Different types of arguments will yield different results:
  572.    * - `modifiers(Object|Array)`: If the value is an array of objects or an
  573.    *   object, the `modifiers` are added to this section.
  574.    * - `modifiers()`: Pass nothing to return all of the section's modifiers in an
  575.    *   array.
  576.    * - `modifiers(Integer)`: Use a 0-based index to return the section's Nth
  577.    *   modifier.
  578.    * - `modifiers(String)`: Use a string to return a specific modifier by name.
  579.    *
  580.    * @param {*} [modifiers] Optional. The modifiers of the section.
  581.    * @returns {KssSection|KssModifier|KssModifier[]|boolean} If `modifiers` is
  582.    *   given, the `KssSection` object is returned to allow chaining of methods.
  583.    *   Otherwise, the requested modifiers of the section are returned.
  584.    */
  585.   modifiers(modifiers) {
  586.     return this._propertyHelper('modifiers', KssModifier, modifiers);
  587.   }
  589.   /**
  590.    * Gets or adds parameters if the section is a CSS preprocessor function/mixin.
  591.    *
  592.    * Different types of arguments will yield different results:
  593.    *  - `parameters(Object|Array)`: If the value is an array of objects or an
  594.    *    object, the `parameters` are added to this section.
  595.    * - `parameters()`: Pass nothing to return all of the section's parameters in
  596.    *   an array.
  597.    * - `parameters(Integer)`: Use a 0-based index to return the section's Nth
  598.    *   parameter.
  599.    * - `parameters(String)`: Use a string to return a specific parameter by name.
  600.    *
  601.    * @param {*} [parameters] Optional. The parameters of the section.
  602.    * @returns {KssSection|KssParameter|KssParameter[]|boolean} If `parameters` is
  603.    *   given, the `KssSection` object is returned to allow chaining of methods.
  604.    *   Otherwise, the requested parameters of the section are returned.
  605.    */
  606.   parameters(parameters) {
  607.     return this._propertyHelper('parameters', KssParameter, parameters);
  608.   }
  609. }
  611. module.exports = KssSection;