Support for maps properties

[pascalduez]

Might be useful to have a syntax to document maps, a per key/val documenting.
For instance configuration maps.

[KittyGiraudel]

We thought about that in #15.

This is too soon to implement it, but definitely not too soon to talk about it so I am willing to consider any proposal.

[KittyGiraudel]

First, let's deal with #36.

[KittyGiraudel]

I want everyone's opinion on how we should document maps. Go. :)

[pascalduez]

Following @valeriangalliat proposition on #15 , I guess in place keys commenting would be neat.
Something like @key or more explicit @property ?
@property == @key: @default-val ...

/**
 * Default settings.
 * ---
 * @type Map
 */
$settings: (
  base: (
    default: (
      /**
       * @prop {Color}
       * description
       */
      text: black,

      /**
       * @prop {Number}
       * description
       */
      size: 50px,

      /**
       * @prop {String}
       * description
       */
      selector: widget,
    ),
  ),
);

[KittyGiraudel]

Considered and rejected. I don't want comments that enforce a specific coding syntax.

[pascalduez]

I don't want comments that enforce a specific coding syntax.

You mean forcing authors to format their maps multi-lines ?

[KittyGiraudel]

You mean forcing authors to format their maps multi-lines ?

I think most authors pretty print their maps so that's no concern here. I mean that I don't want comments to be injected in the code. Comments should come before a declaration, not in the middle of it.

[pascalduez]

Comments should come before a declaration, not in the middle of it.

Yep, I understand that.

Then why not following the function/mixin way ?

/**
 * Default settings.
 * ---
 * @type Map
 * ---
 * @prop base - description
 * -- @prop default - description
 * ---- @prop {Color} text (black) - description
 * ---- @prop {Number} size (50px) - description
 * ---- @prop {String} selector (widget) - description
 */
$settings: (
  base: (
    default: (
      text: black,
      size: 50px,
      selector: widget,
    ),
  ),
);

The issue is with how to signify nesting. Does parsing spaces/white-space is reliable enough ?

[KittyGiraudel]

Then why not following the function/mixin way ?

That's the spirit.

Does parsing spaces/white-space is reliable enough ?

I'd like to avoid that.

[FWeinb]

I like @pascalduez approach but would ultimately think that this is much more clean

/**
 * Default settings.
 * ---
 * @type Map
 * ---
 * @prop base - description
 * @prop base.default - description
 * @prop {Color} base.default.text (black) - description
 * @prop {Number} base.default.size (50px) - description
 * @prop {String} base.default.selector (widget) - description
 */
$settings: (
  base: (
    default: (
      text: black,
      size: 50px,
      selector: widget,
    ),
  ),
);

This buts the whole context in every line. So if you search for a specify thing the context is always there. Without the need to know in which context the line was.

[KittyGiraudel]

I really like this. No reason not to include the type type when it's a nested map though. That being said, we could make it optional as well.

/**
 * Default settings.
 * ---
 * @type Map
 * ---
 * @prop {Map} base - description
 * @prop {Map} base.default - description
 * @prop {Color} base.default.text (black) - description
 * @prop {Number} base.default.size (50px) - description
 * @prop {String} base.default.selector (widget) - description
 */
$settings: (
  base: (
    default: (
      text: black,
      size: 50px,
      selector: widget,
    )
  )
);

[KittyGiraudel]

I am okay with this version.

[pascalduez]

Looks neat. And yes, optional type would be better.

[KittyGiraudel]

In the meantime, I suggest to those of you who want to document maps to use @pascalduez's trick: http://pascalduez.github.io/SassyIcons/docs/#variable-icons-defaults.

Tl;dr: use inline comments within the map so they get grabbed and printed as regular content.

[alademann]

+1 for using dot notation to imply nesting levels!

I actually use a custom get Sass function in my Sass project that explodes dot-notated references to deeply nested map properties... just extends atop SassyMap's map-get-deep leveraging SassyList's sl-explode function...

/**
 * Fetch a deeply nested value in a multi-level map using object dot-notation string OR a list of keys.
 *
 * @requires sassy-maps
 * @requires SassyLists
 * @requires is-map
 * @requires is-string
 * @requires is-list
 *
 * @param {map}           $map
 * @param {string | list} $keys         object dot-notation string representing the nesting order of the desired key
 * @param {string}        $delimiter    string used to identify the individual keys within the string
 *
 * @throws if any of the `$required-functions` do not exist
 * @throws if `$map` param is not a map
 * @throws if `$keys` param is not a string or a list
 *
 * @return {*} value at nesting level requested via `$keys` param
 */
@function get($map, $keys, $delimiter: '.') {
    $required-functions: is-map, is-string, is-list, sl-explode, map-get-deep;
    @each $function in $required-functions {
        @if not function-exists($function) {
            @warn "`#{$function}()` is required by `get()`.";
            @return null;
        }
    }
    @if not is-map($map) {
        @warn "`get` function expecting a map; #{type-of($map)} given.";
        @return null;
    }
    @if not is-string($keys) and not is-list($keys) {
        @warn "`get` function expecting a list or a string; #{type-of($keys)} given.";
        @return null;
    }
    // END error-checking

    @if is-list($keys) {
        //
        // its already a list, no need to explode it
        //
        @return map-get-deep($map, $keys);
    } @else {
        @if not str-index($keys, $delimiter) {
            //
            // a single key has been requested - no recursion necessary
            // (no `$delimiter` found in `$keys`)
            //
            @return map-get($map, $keys);
        } @else {
            //
            // a `$delimiter` was found in the `$keys` string
            // lets split it on the delimiter so we can pass a valid list of keys to `map-get-deep()`
            //
            $key-list: sl-explode($keys, $delimiter);

            @return map-get-deep($map, $key-list)
        }
    }
}

.btn {
  padding: get($btn-config, 'padding.base.all');
  font-size: get($btn-config, 'text.font-size.base');
  color: get($btn-config, 'text.color.base');

  &:hover,
  &:focus {
      color: get($btn-config, 'text.color.hover');
  }

  &.btn-xs {
      padding: get($btn-config, 'padding.xs.all');
      font-size: get($btn-config, 'text.font-size.xs');
  }

  // etc...
}

[KittyGiraudel]

Moving this to 1.3.

[FWeinb]

Sorry, clicked the wrong thing.

[KittyGiraudel]

Next and last for 1.3.

[KittyGiraudel]

What about this? I release 1.3, we delay this to 1.4?

[KittyGiraudel]

@pascalduez We are very close to ship this. Do you have a specific idea on how you'd like to display a map structure in the view? A table or something? I was thinking of the exact same way as parameters.

[pascalduez]

Yeah, I guess cloning the parameter presentation is the way to go for now, so we don't ends up with too many different structures.

[FWeinb]

👍

[KittyGiraudel]

Merged in develop.