[Docs] Move commonalities across blocks to a single base layout (#424)

docs/_layouts/block.njk

@@ -0,0 +1,37 @@
+{% set hasSidebar = true %}
+{% set hasOutline = true %}
+
+{% extends '../_includes/base.njk' %}
+
+{# Component header #}
+{% block beforeContent %}
+  <h1 class="title">{{ title }}</h1>
+  <div class="block-info">
+    {% set snippets = (elements or element or snippets or snippet) | dict  %}
+
+    {% for snippet, link in snippets %}
+      {% if snippet %}
+        <code class="class">
+          {%- if link -%}
+            <a href="{{ link }}">{{ snippet }}</a>
+          {%- else -%}
+            {{ snippet }}
+          {%- endif-%}
+        </code>
+      {%- endif %}
+    {% endfor %}
+
+    {% include '../_includes/status.njk' %}
+  </div>
+  {% if description %}
+  <p class="summary">
+    {{ description | inlineMarkdown | safe }}
+  </p>
+  {% endif %}
+  {% block notes %}{% endblock %}
+{% endblock %}
+
+{# Content #}
+{% block content %}
+  {{ content | safe }}
+{% endblock %}

docs/_layouts/component.njk

@@ -1,23 +1,8 @@
-{% set hasSidebar = true %}
-{% set hasOutline = true %}
+{% extends '../_layouts/block.njk' %}
 {% set component = components[page.fileSlug] %}
-{% set description = component.summary %}
-{% set status = component.status %}
-{% set since = component.since %}
-
-{% extends '../_includes/base.njk' %}
 
 {# Component header #}
-{% block beforeContent %}
-  <h1 class="title">{{ title }}</h1>
-  <div class="component-info">
-    <code class="tag">&lt;{{ component.tagName }}&gt;</code>
-
-    {% include '../_includes/status.njk' %}
-  </div>
-  <p class="summary">
-    {{ component.summary | inlineMarkdown | safe }}
-  </p>
+{% block notes %}
   {% if native %}
   <wa-callout variant="success">
     <wa-icon slot="icon" name="lightbulb" variant="regular"></wa-icon>
@@ -27,11 +12,6 @@
   {% endif %}
 {% endblock %}
 
-{# Content #}
-{% block content %}
-  {{ content | safe }}
-{% endblock %}
-
 {# Component API #}
 {% block afterContent %}
   {# Slots #}

docs/_layouts/element.njk

@@ -1,37 +1,18 @@
-{% set hasSidebar = true %}
-{% set hasOutline = true %}
-
-{% extends '../_includes/base.njk' %}
+{% extends '../_layouts/block.njk' %}
 
 {# Component header #}
-{% block beforeContent %}
-  <h1 class="title">{{ title }}</h1>
-  <div class="component-info">
-    {% for tag, url in elements %}
-      <code class="tag"><a href="{{ url }}">{{ tag }}</a></code>
-    {% endfor %}
-    {% include '../_includes/status.njk' %}
-  </div>
-  {% if description -%}
-    <p class="summary">{{ description | inlineMarkdown | safe }}</p>
-  {%- endif %}
+{% block notes %}
   {% if component %}
   <wa-callout variant="success">
     <wa-icon slot="icon" name="lightbulb" variant="regular"></wa-icon>
     Want to do more?
-    Check out the {% for name in (component | toArray) -%}
+    Check out the {% for name in (component | toList) -%}
       {{ ' and ' if loop.last and not loop.first }}<a href="/docs/components/{{ name }}"><code>&lt;wa-{{ name }}&gt;</code></a>{{ ', ' if not loop.last }}
-      {%- endfor %} component{{ 's' if (component | isArray) }}</a>!
+      {%- endfor %} component{{ 's' if (component | isList) }}</a>!
   </wa-callout>
   {% endif %}
 {% endblock %}
 
-{# Content #}
-{% block content %}
-  {{ content | safe }}
-{% endblock %}
-
-{# Component API #}
 {% block afterContent %}
   {# Slots #}
   {% if css_file %}

docs/_layouts/pattern.njk

@@ -1,4 +0,0 @@
-{% set hasSidebar = true %}
-{% set hasOutline = true %}
-
-{% extends "../_includes/base.njk" %}

docs/_layouts/utilities.njk

@@ -1,25 +0,0 @@
-{% set hasSidebar = true %}
-{% set hasOutline = true %}
-
-{% extends '../_includes/base.njk' %}
-
-{# Component header #}
-{% block beforeContent %}
-  <h1 class="title">{{ title }}</h1>
-  <div class="component-info">
-
-    {% for className in classes %}
-      <code class="class">.{{ className }}</code>
-    {% endfor %}
-    {% include '../_includes/status.njk' %}
-  </div>
-  {% if description -%}
-    <p class="summary">{{ description | inlineMarkdown | safe }}</p>
-  {%- endif %}
-
-{% endblock %}
-
-{# Content #}
-{% block content %}
-  {{ content | safe }}
-{% endblock %}

docs/_utils/filters.js

@@ -74,12 +74,30 @@ export function breadcrumbs(url, { withCurrent = false } = {}) {
   return ret;
 }
 
-export function isArray(value) {
-  return Array.isArray(value);
+export function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-export function toArray(value) {
-  return isArray(value) ? value : [value];
+export function isList(value) {
+  return Array.isArray(value) || value instanceof Set;
+}
+
+/** Get an Array or Set */
+export function toList(value) {
+  return isList(value) ? value : [value];
+}
+
+/**
+ * Convert any value to something that can be iterated over with a for key, value loop.
+ * Arrays and sets will be converted to a Map of value -> undefined
+ */
+export function dict(value) {
+  if (value instanceof Map || isObject(value)) {
+    return value;
+  }
+
+  let list = toList(value);
+  return new Map([...list].map(item => [item, undefined]));
 }
 
 export function deepValue(obj, key) {
@@ -87,11 +105,15 @@ export function deepValue(obj, key) {
   return key.reduce((subObj, property) => subObj?.[property], obj);
 }
 
-function isNumeric(value) {
+export function isNumeric(value) {
   return typeof value === 'number' || (typeof value === 'string' && !isNaN(value));
 }
 
-function isEmpty(value) {
+export function isString(value) {
+  return typeof value === 'string';
+}
+
+export function isEmpty(value) {
   return value === null || value === undefined || value === '';
 }
 

docs/assets/styles/docs.css

@@ -230,7 +230,7 @@ h1.title wa-badge {
   }
 }
 
-.component-info {
+.block-info {
   margin-block-end: var(--wa-flow-spacing);
 }
 

docs/docs/components/components.json

@@ -2,6 +2,10 @@
   "layout": "component.njk",
   "tags": ["components"],
   "eleventyComputed": {
-    "status": "{{ components[page.fileSlug].status }}"
+    "component": "{{ components[page.fileSlug] }}",
+    "description": "{{ components[page.fileSlug].summary }}",
+    "status": "{{ components[page.fileSlug].status }}",
+    "since": "{{ components[page.fileSlug].since }}",
+    "element": "<{{ components[page.fileSlug].tagName }}>"
   }
 }

docs/docs/native/button.md

@@ -4,6 +4,9 @@ description: 'Button styles apply your Web Awesome theme to native HTML buttons.
 tags: forms
 component: button
 icon: button
+snippets:
+  '<button>': https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button
+  '.wa-button': false
 ---
 
 ```html {.example}

docs/docs/patterns/patterns.json

@@ -1,5 +1,5 @@
 {
-  "layout": "pattern.njk",
+  "layout": "block.njk",
   "tags": ["patterns"],
   "noAlpha": true
 }

docs/docs/utilities/appearance.md

@@ -1,11 +1,11 @@
 ---
 title: Appearance Variants
 description: Appearance utilities apply a collection of properties to achieve certain effects, like making elements accented, outlined, filled, or plain.
-classes:
-  - wa-accent
-  - wa-outlined
-  - wa-filled
-  - wa-plain
+snippets:
+  - .wa-accent
+  - .wa-outlined
+  - .wa-filled
+  - .wa-plain
 ---
 
 Some Web Awesome components, like `<wa-button>`, allow you to change their overall style by using an `appearance` attribute:

docs/docs/utilities/color.md

@@ -2,12 +2,12 @@
 title: Color Variants
 description: Color utilities allow you to apply the brand, neutral, success, warning, and danger colors from your theme to any element.
 icon: theming/color
-classes:
-  - wa-brand
-  - wa-neutral
-  - wa-success
-  - wa-warning
-  - wa-danger
+snippets:
+  - .wa-brand
+  - .wa-neutral
+  - .wa-success
+  - .wa-warning
+  - .wa-danger
 ---
 
 Some Web Awesome components, like `<wa-button>`, allow you to change the color by using a `variant` attribute:

docs/docs/utilities/size.md

@@ -3,10 +3,10 @@ title: Size
 description: Size utilities give elements one of three preset sizes (small, medium, or large).
 icon: theming/space
 status: experimental
-classes:
-  - wa-size-s
-  - wa-size-m
-  - wa-size-l
+snippets:
+  - .wa-size-s
+  - .wa-size-m
+  - .wa-size-l
 ---
 
 Some Web Awesome components, like `<wa-button>`, allow you to change their size to one of three presets: `small`, `medium`, and `large` by using a `size` attribute:

docs/docs/utilities/utilities.json

@@ -1,4 +1,4 @@
 {
-  "layout": "utilities",
+  "layout": "block",
   "tags": ["utilities"]
 }

docs/docs/utilities/visually-hidden.md

@@ -2,9 +2,9 @@
 title: Visually Hidden
 description: The visually hidden utility makes content accessible to assistive devices without displaying it on the screen.
 icon: visually-hidden
-classes:
-  - wa-visually-hidden
-  - wa-visually-hidden-force
+snippets:
+  - .wa-visually-hidden
+  - .wa-visually-hidden-force
 ---
 
 > "there are real world situations where visually hiding content may be appropriate, while the content should remain available to assistive technologies, such as screen readers. For instance, hiding a search field's label as a common magnifying glass icon is used in its stead."