#23: Refactor SASS Docs pages to be per group

src/stylesheets/helpers/_helpers-glyphs.scss

@@ -3,8 +3,8 @@
 ////
 
 /// A map of glyph name to code (character entity reference).
-/// Avoids things like content: '\201C' throughout SASS. Use the
-/// get-glyph function.
+/// Avoids things like content: '\201C' throughout SASS.
+/// Usual usage is via the `get-glyph` function.
 /// @see get-glyph
 /// @link https://css-tricks.com/snippets/html/glyphs/
 /// @prop {String} bullet [2022] Bullet (•)
@@ -32,7 +32,7 @@ $glyphs: (
 );
 
 /// Gets a glyph code, or several, (character entity reference) from the
-/// $glyphs map, matching the given $names. Usually used with the content
+/// `$glyphs` map, matching the given `$names`. Usually used with the content
 /// property for psuedo elements, to avoid use of magic character reference strings.
 /// @param {argList} $names The name(s) of the glyph(s) to get
 /// @returns {string} The character entity reference code(s) as a string, e.g. '\201C' or '\02008\029C9'

test/test-helpers.js

@@ -1,3 +1,5 @@
+/* eslint-env node, mocha */
+
 /**
  * @module  Test helpers
  * A suite of test helpers and utility methods

test/unit/eventr.spec.js

@@ -46,7 +46,7 @@ describe("Delegate events", function() {
 
 			spy.should.be.calledOnce;
 			spy.firstCall.args.length.should.equal(1);
-			spy.firstCall.args[0].handleObj.namespace.should.equal("delegateEvents")
+			spy.firstCall.args[0].handleObj.namespace.should.equal("delegateEvents");
 		});
 
 		it("bound events maintain existing namespaced", function() {
@@ -61,7 +61,7 @@ describe("Delegate events", function() {
 
 			spy.should.be.calledOnce;
 			spy.firstCall.args.length.should.equal(1);
-			spy.firstCall.args[0].handleObj.namespace.should.equal("delegateEvents.testns")
+			spy.firstCall.args[0].handleObj.namespace.should.equal("delegateEvents.testns");
 		});
 
 		it("should call callback with instance as context", function() {
@@ -118,7 +118,7 @@ describe("Delegate events", function() {
 
 			let getEventKeys = () => {
 				return Object.keys($._data(test.$el[0], "events"));
-			}
+			};
 
 			getEventKeys().length.should.equal(2);
 

web/server/controllers/sass.js

@@ -2,15 +2,56 @@
 var express = require("express"),
 	router = express.Router(),
 	fs = require("fs"),
-	path = require("path");
+	path = require("path"),
+	_ = require("lodash");
 
-router.get("/", function(req, res) {
-	res.render("sass/index");
-});
+var data = JSON.parse(fs.readFileSync(path.join(__dirname, "./../../../dist/docs/sass/sass.json"), "utf-8"));
+
+// Returns true if the given group id has at least 1 item
+let getItems =
+	(groupId) => _.filter(data.items, (i) => i.group.indexOf(groupId) > -1 );
 
+/**
+ * Documentation homepage
+ */
 router.get("/docs", function(req, res) {
-	var data = JSON.parse(fs.readFileSync(path.join(__dirname, "./../../../dist/docs/sass/sass.json"), "utf-8"));
-	res.render("sass/docs", data);
+
+	// Map group data into a useable view model
+	let pageData = {
+		groups: _(data.groups)
+			.map((val, key) => ({
+				id: key,
+				name: val,
+				types: _.mapValues(data.byGroupAndType[key], v => v.length)
+			}))
+			.filter((group) => getItems(group.id).length)
+			.value()
+	};
+
+	res.render("sass/docs", pageData);
+});
+
+/**
+ * Documentation group.
+ * Maps the SASS docs generated JSON into a useable format
+ */
+router.get("/docs/:section", function(req, res, next) {
+
+	let group = data.groups[req.params.section],
+		items = getItems(req.params.section);
+	if(group && items.length) {
+
+		let pageData = {
+			groupId: req.params.section,
+			groupName: group,
+			items: items,
+			byType: data.byGroupAndType[req.params.section]
+		};
+		res.render("sass/docs-group", pageData);
+	}
+	else {
+		next();
+	}
 });
 
 module.exports = router;

web/server/views/sass/_sass-layout.njk

@@ -1,5 +1,7 @@
 {% extends "../layouts/_sidebar.njk" %}
-{% set breadcrumbs = [{ title: "SASS", href: "/sass/" }, { title: title }] %}
+{% if not breadcrumbs %}
+	{% set breadcrumbs = [{ title: "SASS", href: "/sass/" }, { title: title }] %}
+{% endif %}
 {% set title = title + " | SASS" %}
 
 {% block sidebar %}

web/server/views/sass/docs-group.njk

@@ -0,0 +1,36 @@
+{% extends "./_sass-layout.njk" %}
+{% set title = groupName %}
+{% set breadcrumbs = [{ title: "SASS", href: "/sass/" }, { title: "Documentation", href: "/sass/docs" }, { title: title }] %}
+
+{% block sidebar %}
+	{% include "sass/includes/partials/sidebar.njk" %}
+{% endblock %}
+
+{% block main %}
+
+	<h1>{{ groupName }}</h1>
+
+	{# Loop over the types #}
+	{% for type, items in byType %}
+
+		{# If items to be displayed in type #}
+		{% if items.length > 0 %}
+			<section id="{{ type }}">
+				<h2>
+					{% if type == "css" %}
+						{# Special case for CSS selectors #}
+						Selectors
+					{% else %}
+						{{ type | pluralize | capitalize }}
+					{% endif %}
+				</h2>
+
+				{# Loop over the items #}
+				{% for item in items %}
+					{% include "sass/includes/partials/item.njk" %}
+				{% endfor %}
+			</section>
+		{% endif %}
+	{% endfor %}
+
+{% endblock %}

web/server/views/sass/docs.njk

@@ -1,46 +1,42 @@
 {% extends "./_sass-layout.njk" %}
-{% set title = "SASS Documentation" %}
-
-{% block sidebar %}
-	{% include "sass/includes/partials/sidebar.njk" %}
-{% endblock %}
-
+{% set title = "Documentation" %}
 
 {% block main %}
 
 	<h1>SASS Documentation</h1>
 
-	{# Loop over the groups #}
-	{% for group_name, group in byGroupAndType %}
-		<section>
-			<h2 id="{{ group_name }}">
-				{{ groups[group_name] }}
-			</h2>
-
-			{# Loop over the types #}
-			{% for type, items in group %}
-
-				{# If items to be displayed in type #}
-				{% if items.length > 0 %}
-					<section id="{{ group_name }}-{{ type }}">
-						<h3>
-							{% if type == "css" %}
-								{# Special case for CSS selectors #}
-								Selectors
-							{% else %}
-								{{ type | pluralize | capitalize }}
-							{% endif %}
-						</h3>
-
-						{# Loop over the items #}
-						{% for item in items %}
-							{% include "sass/includes/partials/item.njk" %}
-						{% endfor %}
-					</section>
-				{% endif %}
-			{% endfor %}
-
-		</section>
-	{% endfor %}
+	<div class="grid">
+		{# Loop over the groups #}
+		{% for group in groups %}
+			<div class="grid__item one-whole tablet--one-third desktop--one-quarter">
+				<h2 class="h4">
+					<a href="/sass/docs/{{ group.id }}">
+						{{ group.name }}
+					</a>
+				</h2>
+				<p>
+					{% for type_name, count in group.types %}
+						{{ count }}
+						{% if type_name === "variable" %}
+							variables
+						{% elif type_name === "css" %}
+							selectors
+						{% elif type_name === "function" %}
+							functions
+						{% elif type_name === "mixin" %}
+							mixins
+						{% else %}
+							others
+						{% endif %}
+						{% if loop.revindex0 === 1 %}
+							&amp;
+						{% elif not loop.last %}
+							,
+						{% endif %}
+					{% endfor %}
+				</p>
+			</div>
+		{% endfor %}
+	</div>
 
 {% endblock %}

web/server/views/sass/includes/annotations/example.njk

@@ -14,6 +14,8 @@
 			<h5>Example</h5>
 		{% endif %}
 
-		{{ renderExample(example.code, example.type) }}
+		{% source "scss", example.description | striptags -%}
+			{{ example.code }}
+		{%- endsource -%}
 	{% endfor %}
 {% endif %}

web/server/views/sass/includes/annotations/name.njk

@@ -20,6 +20,10 @@
 	{% endif %}
 </h4>
 
+<small>
+	From: <a href="https://github.com/nhsevidence/NICE-Experience/tree/master/src/stylesheets/{{ item.file.path }}" rel="external" target="_blank">{{ item.file.name }}</a>
+</small>
+
 {% if item.description %}
 	{{ item.description|safe }}
 {% endif %}

web/server/views/sass/includes/annotations/preview.njk

@@ -19,7 +19,7 @@
 {# Variables #}
 {% elif item.context.type == "variable" %}
 
-	{% source "scss" -%}
+	{% source "scss", '$' + item.context.name -%}
 		${{ item.context.name|safe }}: {{ item.context.value|safe }};
 	{%- endsource %}
 
@@ -56,7 +56,7 @@
 	{% set signature = '@' + item.context.type + ' ' + item.context.name + '(' + parameters_string + ')' %}
 
 	{# Output the source, with an expanded version #}
-	{% source "scss" -%}
+	{% source "scss", item.context.type + ' ' + item.context.name + ' source' -%}
 		{{ signature }} { ... }
 	{%- expanded -%}
 		{{ signature }} { {{ item.context.code }} }

web/server/views/sass/includes/partials/item.njk

@@ -1,4 +1,4 @@
-<section id="{{ group_name }}-{{ item.context.type }}-{{ item.context.name }}">
+<section id="{{ item.context.type }}-{{ item.context.name }}">
 
 	{% include '../annotations/name.njk' %}
 

web/server/views/sass/includes/partials/sidebar.njk

@@ -1,50 +1,39 @@
 {# See https://github.com/SassDoc/sassdoc-theme-default/blob/master/views/includes/partials/sidebar.html.swig #}
 
-{# Loop over the groups #}
-{% for group_name, group in byGroupAndType %}
-
-	<h3>
-		<a href="#{{ group_name }}">
-			{{ groups[group_name] }}
-		</a>
-	</h3>
-
-	{# Loop over the types #}
-	{% for type, items in group %}
-
-		{# If items to be displayed in type #}
-		{% if items.length > 0 %}
-
-			<h4>
-				<a href="#{{ group_name }}-{{ type }}">
-					{% if type == "css" %}
-						{# Special case for CSS selectors #}
-						Selectors
-					{% else %}
-						{{ type | pluralize | capitalize }}
+{# Loop over the types #}
+{% for type, items in byType %}
+
+	{# If items to be displayed in type #}
+	{% if items.length > 0 %}
+
+		<h4>
+			<a href="#{{ type }}">
+				{% if type == "css" %}
+					{# Special case for CSS selectors #}
+					Selectors
+				{% else %}
+					{{ type | pluralize | capitalize }}
+				{% endif %}
+			</a>
+		</h4>
+
+		{# Loop over the items #}
+		{% for item in items %}
+			{% if loop.first %}<ul>{% endif %}
+
+			<li>
+				<a href="#{{ item.context.type }}-{{ item.context.name }}">
+					{% if item.context.type == "variable" %}${% endif %}{{ item.context.name }}
+					{% if item.access[0] == "private" %}
+						<small>(private)</small>
+					{% endif %}
+					{% if item.property.length > 0 %}
+						<small>(map)</small>
 					{% endif %}
 				</a>
-			</h4>
-
-			{# Loop over the items #}
-			{% for item in items %}
-				{% if loop.first %}<ul>{% endif %}
-
-				<li>
-					<a href="#{{ group_name }}-{{ item.context.type }}-{{ item.context.name }}">
-						{% if item.context.type == "variable" %}${% endif %}{{ item.context.name }}
-						{% if item.access[0] == "private" %}
-							<small>(private)</small>
-						{% endif %}
-						{% if item.property.length > 0 %}
-							<small>(map)</small>
-						{% endif %}
-					</a>
-				</li>
-
-				{% if loop.last %}</ul>{% endif %}
-			{% endfor %}
-		{% endif %}
-	{% endfor %}
+			</li>
 
+			{% if loop.last %}</ul>{% endif %}
+		{% endfor %}
+	{% endif %}
 {% endfor %}