Build single level files

[ffoodd]

Having a single file for each level may be very useful for some users, in order to display only errors for example.

Should not be complicated.

[GaetanBt]

This or the ability to choose which level you want to see by checking something in a control box. This would certainly require some Javascript but I think it could be amazing and more simple/fast to use.

[KittyGiraudel]

This would certainly require some Javascript

[GaetanBt]

Great 👍

[ffoodd]

Yup, I'd love to do this without requiring Javascript, but any solution would be great :)

Please note that this is note the most important issue at this moment, but will be in a few weeks ;)

[GaetanBt]

You can do it with radio buttons or checkboxes and CSS pseudo-classes but it would require adding HTML. Do you think of any other way to do it @hugogiraudel ?

[KittyGiraudel]

Na. The Sass Way™.

[ffoodd]

You already can do it pretty easily but it requires a few actions. I was thinking about simply add some files, like "a11y-en_errors.scss" that would compile when running Sass. Easy, but needs to duplicate files.

I'm quite sure Hugo has his own way in mind already :D

[KittyGiraudel]

Okay, so I have an idea to make it work with nothing more than a Sass configuration mixin, exactly the same as we did for the language.

The idea

I went with the following idea, inspired by PHP/Apache logs: error > warning > obsolete > advice. This means that:

• if you set advice, you want to see everything;
• if you set obsolete, you want to see everything but advice;
• if you set warning, you want to see warning and error;
• if you set error, you want to see only error.

You would define which level you want in the main file, aside with the language:

@charset "UTF-8";

@import "utils/all";
@include set-locale("fr");
@include set-minimum-level("advice"); // Display everything
@import "base/base";
@import "themes/all";

Building the set-minimum-level mixin

This mixin is almost a copy of the set-locale mixin. You give it a level, it makes sure it's valid, and it defines a global variable holding this level. Easy peasy.

/// Defines the minimum level used by `a11y.css`.
/// Either:
/// * `error` for errors only;
/// * `warning` for errors and warnings;
/// * `obsolete` for everything but advices;
/// * `advice` for everything.
/// @access public
/// @param {String} $level
/// @output Nothing
/// @example scss - Defines the minimum level to `error`.
///  @include set-minimum-level("error");
/// @throw Throws an error if `$level` is not either `error`, `warning`, `obsolete` or `advice`.
@mixin set-minimum-level($level) {
  $level: to-lower-case($level);
  $levels: map-keys($themes);

  @if not index($levels, $level) {
    @error "Level `#{$level}` is not supported. "
         + "Please choose one of `#{$levels}`.";
  }

  $minimum-level: $level !global;
}

Outputing only when needed

Now, we need to find a way to make sure rules are only output when the log level is sufficient. For this, we need a simple is-level-enough($level) function which returns a boolean.

/// Test whether `$level` is high enough to be displayed.
/// @access private
/// @param {String} $level
/// @return {Boolean}
@function is-level-enough($level) {
  $levels: map-keys($themes);

  @return index($levels, $level) <= index($levels, $minimum-level);
}

Then, we only have to use it in the relevant mixins:

/// Defines an error
/// @access public
/// @param {String} $key - Key used to fetch message in `$messages` map
/// @param {Bool} $self-closing (false) - Whether or not to use message on self or next node
/// @requires {mixin} item
/// @example scss - Define an error
/// .selector {
///   @include error("no-src");
/// }
@mixin error($key, $self-closing: false) {
  @if is-level-enough("error") {
    @include item("error", $key, $self-closing);
  }
}


/// Defines a warning
/// @access public
/// @param {String} $key - Key used to fetch message in `$messages` map
/// @param {Bool} $self-closing (false) - Whether or not to use message on self or next node
/// @requires {mixin} item
/// @example scss - Define an warning
/// .selector {
///   @include warning("abbr");
/// }
@mixin warning($key, $self-closing: false) {
  @if is-level-enough("warning") {
    @include item("warning", $key, $self-closing);
  }
}


/// Defines an obsolete thing
/// @access public
/// @param {String} $key - Key used to fetch message in `$messages` map
/// @param {Bool} $self-closing (false) - Whether or not to use message on self or next node
/// @requires {mixin} item
/// @example scss - Define an obsolete
/// .selector {
///   @include obsolete("any");
/// }
@mixin obsolete($key, $self-closing: false) {
  @if is-level-enough("obsolete") {
    @include item("obsolete", $key, $self-closing);
  }
}

/// Defines an advice
/// @access public
/// @param {String} $key - Key used to fetch message in `$messages` map
/// @param {Bool} $self-closing (false) - Whether or not to use message on self or next node
/// @requires {mixin} item
/// @example scss - Define an advice
/// .selector {
///   @include advice("nav");
/// }
@mixin advice($key, $self-closing: false) {
  @if is-level-enough("advice") {
    @include item("advice", $key, $self-closing);
  }
}

Tests

@include set-minimum-level("advice");
set-minimum-level:advice {
  display-advices:  is-level-enough("advice");
  display-obsolete: is-level-enough("obsolete");
  display-warnings: is-level-enough("warning");
  display-errors:   is-level-enough("error");
}

@include set-minimum-level("obsolete");
set-minimum-level:obsolete {
  display-advices:  is-level-enough("advice");
  display-obsolete: is-level-enough("obsolete");
  display-warnings: is-level-enough("warning");
  display-errors:   is-level-enough("error");
}

@include set-minimum-level("warning");
set-minimum-level:warning {
  display-advices:  is-level-enough("advice");
  display-obsolete: is-level-enough("obsolete");
  display-warnings: is-level-enough("warning");
  display-errors:   is-level-enough("error");
}

@include set-minimum-level("error");
set-minimum-level:error {
  display-advices:  is-level-enough("advice");
  display-obsolete: is-level-enough("obsolete");
  display-warnings: is-level-enough("warning");
  display-errors:   is-level-enough("error");
}

Results:

set-minimum-level:advice {
  display-advices: true;
  display-obsolete: true;
  display-warnings: true;
  display-errors: true;
}

set-minimum-level:obsolete {
  display-advices: false;
  display-obsolete: true;
  display-warnings: true;
  display-errors: true;
}

set-minimum-level:warning {
  display-advices: false;
  display-obsolete: false;
  display-warnings: true;
  display-errors: true;
}

set-minimum-level:error {
  display-advices: false;
  display-obsolete: false;
  display-warnings: false;
  display-errors: true;
}

End of story. If you guys are okay, I'll submit a PR. PoC here: http://sassmeister.com/gist/55bdf15ffaa0f073a61f.

[ffoodd]

This is perfect, it will only require to set the right level and job's done :)

I'd love a PR for this !

[GaetanBt]

Mind blowing, nice job :)

[KittyGiraudel]

Done in #70. Please review, test and document before merging.

[ffoodd]

PR merged, only waiting for the SassDoc to close this issue :)

Thanks !