Merge pull request #40 from oddbird/font-variant-override

Add font-variant override "show" argument
oddbird · Dec 13, 2016 · fb97de6 · fb97de6
2 parents bd45fad + e55166a
commit fb97de6
Show file tree

Hide file tree

Showing 3 changed files with 137 additions and 35 deletions.
diff --git a/README.md b/README.md
@@ -98,6 +98,14 @@ for more info.
 Releases
 --------
 
+### 0.5.1: UNRELEASED
+
+- Add optional `show` argument for font-specimen previews —
+  `@preview font-specimen; show: regular, bold, bold italic` —
+  allowing you to override what variants are displayed
+  in the specimen.
+
+
 ### 0.5.0: 2016-12-09
 
 - Add table output for `@property` annotation,

diff --git a/scss/config/_fonts.scss b/scss/config/_fonts.scss
@@ -63,7 +63,7 @@ $sans-font: (
 // Code Font
 // ---------
 /// A readable monospace font for code previews.
-/// @preview font-specimen; key: code
+/// @preview font-specimen; key: code; show: regular, bold, bold italic
 /// @group webfonts
 /// @link http://oddbird.net/accoutrement-type/sassdoc/
 ///   Accoutrement Type

diff --git a/templates/item/preview.macros.j2 b/templates/item/preview.macros.j2
@@ -1,6 +1,11 @@
 {% import 'utility.macros.j2' as utility %}
 
 
+{#
+  Show Previews
+  -------------
+  Call the requested previews with the appropriate JSON data.
+#}
 {% macro show_previews(data, name, args) %}
   {% if args %}
     {% set type = args.type %}
@@ -9,7 +14,7 @@
     {% if type == 'color-palette' %}
       {{ color_palette(data[key]) }}
     {% elif type == 'font-specimen' %}
-      {{ font_specimen(key, data[key]) }}
+      {{ font_specimen(key, data[key], args) }}
     {% elif type == 'ratios' %}
       {{ ratios(data[key], args) }}
     {% elif type == 'sizes' %}
@@ -20,6 +25,11 @@
 {% endmacro %}
 
 
+{#
+  Color Palette
+  -------------
+  Display color palettes based on JSON map output.
+#}
 {% macro color_palette(data) %}
 <div data-sassdoc="color-palette">
   {% for name, value in data %}
@@ -42,7 +52,25 @@
 {% endmacro %}
 
 
-{% macro font_specimen(name, data) %}
+{#
+  Font Specimen
+  -------------
+  Display all font-family specimens,
+  including multiple variants.
+
+  @group font-specimen
+
+  @prop {String} name -
+    Title for the font-family being displayed.
+  @prop {Dict} data -
+    All the available data on a given font,
+    derived from the Sass JSON export.
+  @prop {Dict} args -
+    Arbitrary arguments passes along
+    in the font-specimen call
+    (currently only `show` and `key` are supported).
+#}
+{% macro font_specimen(name, data, args=none) %}
   <div data-sassdoc-font="{{ name }}">
     <h3 data-sassdoc="font-type">
       {{ utility.link_if(
@@ -61,44 +89,110 @@
       {% endfor %}
     </div>
 
-    {% set weight_options = [
-      '100', '200', '300', '400', '500', '600', '700', '800', '900', 'bold'
-    ] %}
-    {% set style_options = [
-      'italic', 'oblique'
-    ] %}
-
-    {% for options, value in data %}
-      {% set options = options|split(' ') %}
-      {% set variant = options[0] %}
-      {% set file = value if (variant in weight_options or variant in style_options or variant == 'regular') else none %}
-      {% set weight = 'normal' %}
-      {% set style = 'normal' %}
-
-      {% for value in options %}
-        {% set weight = value if (value in weight_options) else weight %}
-        {% set style = value if (value in style_options) else style %}
+    {% set family = [data.name, data.stack]|join(', ') %}
+
+    {% if args.show %}
+      {% for option in args.show|split(', ') %}
+        {{ specimen_variant(
+          family=family,
+          option=option,
+          data=data
+        ) }}
+      {% endfor %}
+    {% else %}
+      {% for option, path in data %}
+        {{ specimen_variant(
+          family=family,
+          option=option,
+          path=path
+        ) }}
       {% endfor %}
+    {% endif %}
+  </div>
+{% endmacro %}
 
-      {% if file %}
-        <div data-specimen-face="{{ options }}">
-          <h4 data-specimen="face-name">
-            {% for option in options %}
-              {{ option }}
-            {% endfor %}
-            (<code>{{ file }}</code>)
-          </h4>
-          <div data-specimen="sample" style="font-family: {{ data.name }}, {{ data.stack }}; font-weight: {{ weight }}; font-style: {{ style }};">
-            <div data-specimen="aa">Aa</div>
-            <div data-specimen="lorem">{{ lorem('alpha') }}</div>
-          </div>
-        </div>
-      {% endif %}
+
+{#
+  Specimen Variant
+  ----------------
+  Display a single specimen variant.
+
+  @group font-specimen
+
+  @prop {String} family -
+    A CSS-ready value for font-family,
+    combining both the font name, and fallback font-stack.
+  @prop {String} option -
+    The name of a font variant,
+    e.g. `bold` or `italic` or `700 italic`.
+  @prop {Dict} data [none] -
+    Optional font-data for file-path lookup.
+  @prop {String} path [none] -
+    Optional file-path data,
+    if it is already attached to the option.
+#}
+{% macro specimen_variant(family, option, data=none, path=none) %}
+  {# Local variables for parsing variants in the data #}
+  {% set weight_options = [
+    '100', '200', '300', '400', '500', '600', '700', '800', '900', 'bold'
+  ] %}
+
+  {% set style_options = [
+    'italic', 'oblique'
+  ] %}
+
+  {% set other_options = [
+    'normal', 'regular'
+  ] %}
+
+  {# Initialize variants #}
+  {% set weight = 'normal' %}
+  {% set style = 'normal' %}
+
+  {# Split the option into variants, and find files where available #}
+  {% set split_option = option|split(' ') %}
+  {% set variant_check = split_option[0] %}
+  {% set is_variant = true if (variant_check in weight_options or variant_check in style_options or variant_check in other_options) else false %}
+
+  {# If we have an actual variant, display specimen #}
+  {% if is_variant %}
+    {% set path = data.option if data.option else path %}
+
+    {% for value in split_option %}
+      {% set weight = value if (value in weight_options) else weight %}
+      {% set style = value if (value in style_options) else style %}
     {% endfor %}
-  </div>
+
+    <div data-specimen-face="{{ option }}">
+      <h4 data-specimen="face-name">
+        {{ option }}
+
+        {% if path %}
+          (<code>{{ path }}</code>)
+        {% endif %}
+      </h4>
+      <div data-specimen="sample" style="font-family: {{ family }}; font-weight: {{ weight }}; font-style: {{ style }};">
+        <div data-specimen="aa">Aa</div>
+        <div data-specimen="lorem">{{ lorem('alpha') }}</div>
+      </div>
+    </div>
+  {% endif %}
 {% endmacro %}
 
 
+{#
+  Lorem
+  -----
+  Display Lorem Ipsum text for font specimens.
+
+  @group font-specimen
+
+  @prop {'title' | 'body' | 'alpha'} length -
+    They type of Lorem Ipsum to display:
+    either title-length, paragraph-length,
+    or a list of standard characters
+    (uppercase, lowercase, numbers, and punctuation).
+#}
 {% macro lorem(length) %}
   {% if length == 'title' %}
     <span data-specimen-lorem="title">