@dta-au/civictheme-twig 1.13.1

package/components/02-molecules/table-of-contents/table-of-contents.js

@@ -0,0 +1,152 @@
+/**
+ * CivicTheme Table of Contents component.
+ */
+
+function CivicThemeTableOfContents(el) {
+  // Check if current target is already initialised.
+  if (el.hasAttribute('data-table-of-contents-initialised')) {
+    return;
+  }
+
+  // Get options from attributes.
+  this.target = el;
+  this.position = this.target.getAttribute('data-table-of-contents-position').trim();
+  this.theme = this.target.hasAttribute('data-table-of-contents-theme') ? this.target.getAttribute('data-table-of-contents-theme').trim() : 'light';
+  this.anchorSelector = this.target.hasAttribute('data-table-of-contents-anchor-selector') ? this.target.getAttribute('data-table-of-contents-anchor-selector').trim() : 'h2';
+  this.anchorScopeSelector = this.target.hasAttribute('data-table-of-contents-anchor-scope-selector') ? this.target.getAttribute('data-table-of-contents-anchor-scope-selector').trim() : '.ct-basic-content';
+  this.title = this.target.hasAttribute('data-table-of-contents-title') ? this.target.getAttribute('data-table-of-contents-title').trim() : '';
+
+  // Normalise attribute values.
+  this.position = ['before', 'after', 'prepend', 'append'].indexOf(this.position.trim()) > 0 ? this.position : 'before';
+  this.theme = this.theme === 'dark' ? 'dark' : 'light';
+  this.anchorSelector = this.anchorSelector !== '' ? this.anchorSelector : 'h2';
+  this.anchorScopeSelector = this.anchorScopeSelector !== '' ? this.anchorScopeSelector : '.ct-basic-content';
+
+  // Initialise component.
+  this.init();
+
+  // Mark target as initialised.
+  this.target.setAttribute('data-table-of-contents-initialised', 'true');
+}
+
+CivicThemeTableOfContents.prototype.init = function () {
+  let html = '';
+
+  const links = this.findLinks(this.anchorSelector, this.anchorScopeSelector);
+
+  if (!links.length) {
+    return;
+  }
+
+  if (this.title) {
+    html += this.renderTitle(this.title);
+  }
+
+  html += this.renderLinks(links);
+
+  html = this.renderContainer(html, this.theme, this.position);
+
+  this.place(this.target, this.position, html);
+};
+
+CivicThemeTableOfContents.prototype.findLinks = function (anchorSelector, scopeSelector) {
+  const links = [];
+  const existingUrls = new Set(); // Track existing URLs.
+
+  // Find links within provided scope selector.
+  document.querySelectorAll(scopeSelector).forEach((elScope) => {
+    elScope.querySelectorAll(anchorSelector).forEach((elAnchor) => {
+      // Skip headings marked to be excluded from TOC.
+      if (elAnchor.hasAttribute('data-toc-exclude')) {
+        return;
+      }
+
+      // Respect existing ID.
+      let anchorId = elAnchor.id || null;
+      const anchorText = elAnchor.innerText;
+
+      // Ignore blank headings.
+      if (anchorText.trim() === '') {
+        return;
+      }
+
+      // Generate new ID if no existing ID.
+      if (!anchorId || anchorId.length === 0) {
+        anchorId = this.makeAnchorId(anchorText);
+        // Check if generated ID is already present on the page or links array.
+        while (elScope.querySelectorAll(`#${anchorId}`).length || existingUrls.has(`#${anchorId}`)) {
+          // Add random 3 character suffix.
+          anchorId = `${anchorId}-${Math.random().toString(36).substring(2, 5)}`;
+        }
+      }
+
+      const url = `#${anchorId}`;
+
+      // Skip adding the link if the URL already exists.
+      if (existingUrls.has(url)) {
+        return;
+      }
+
+      links.push({
+        title: anchorText,
+        url,
+      });
+
+      // Update anchor with the id. This will "fix" any anchors with duplicated
+      // IDs, which is not a valid HTML content.
+      elAnchor.id = anchorId;
+
+      // Add the URL to the set of existing URLs.
+      existingUrls.add(url);
+    });
+  });
+
+  return links;
+};
+
+CivicThemeTableOfContents.prototype.renderTitle = function (title) {
+  return `<h2 class="ct-table-of-contents__title">${title}</h2>`;
+};
+
+CivicThemeTableOfContents.prototype.renderLinks = function (links) {
+  let html = '';
+
+  html += `<ul class="ct-table-of-contents__links">`;
+  for (const i in links) {
+    html += `
+      <li class="ct-table-of-contents__link-item">
+        <a class="ct-table-of-contents__link" href="${links[i].url}">${links[i].title}</a>
+      </li>
+    `;
+  }
+  html += '</ul>';
+
+  return html;
+};
+
+CivicThemeTableOfContents.prototype.renderContainer = function (html, theme, position) {
+  return `<div class="ct-table-of-contents ct-theme-${theme} ct-table-of-contents--position-${position}">${html}</div>`;
+};
+
+CivicThemeTableOfContents.prototype.place = function (el, position, html) {
+  const positionMap = {
+    before: 'beforebegin',
+    after: 'afterend',
+    prepend: 'afterbegin',
+    append: 'beforeend',
+  };
+
+  el.insertAdjacentHTML(positionMap[position], html);
+};
+
+CivicThemeTableOfContents.prototype.makeAnchorId = function (str) {
+  return str.toLowerCase()
+    .replace(/(&\w+?;)/gim, ' ')
+    .replace(/[_.~"<>%|'!*();:@&=+$,/?%#[\]{}\n`^\\]/gim, '')
+    .replace(/(^\s+)|(\s+$)/gim, '')
+    .replace(/\s+/gm, '-');
+};
+
+document.querySelectorAll('[data-table-of-contents-position]').forEach((el) => {
+  new CivicThemeTableOfContents(el);
+});

package/components/02-molecules/table-of-contents/table-of-contents.scss

@@ -0,0 +1,115 @@
+//
+// CivicTheme Table of Contents component styles.
+//
+
+.ct-table-of-contents {
+  $root: &;
+
+  width: 100%;
+
+  @include ct-breakpoint-upto('l') {
+    margin-top: ct-spacing(3);
+  }
+
+  @include ct-breakpoint(m) {
+    width: max-content;
+    max-width: var(--ct-table-of-contents-max-width);
+    min-width: var(--ct-table-of-contents-min-width);
+  }
+
+  &--position-before,
+  &--position-prepend {
+    margin-bottom: ct-spacing(4);
+  }
+
+  &--position-after,
+  &--position-append {
+    margin-top: ct-spacing(4);
+  }
+
+  &__title {
+    @include ct-typography('heading-4');
+
+    & {
+      margin-top: 0;
+      margin-bottom: ct-spacing(3);
+    }
+  }
+
+  &__links {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+  }
+
+  &__link {
+    @include ct-typography('label-extra-small');
+
+    & {
+      display: block;
+      position: relative;
+      padding: ct-spacing() ct-spacing(2) ct-spacing() ct-spacing(2.5);
+      border: 0;
+      border-style: solid;
+      text-decoration: none;
+    }
+
+    &::before {
+      content: '';
+      display: inline-block;
+      position: absolute;
+      top: -1 * ct-particle(0.125);
+      bottom: -1 * ct-particle(0.125);
+      left: -1 * ct-particle(0.125);
+      width: ct-particle(0.5);
+    }
+
+    &:active {
+      outline: 0 !important;
+      border-radius: 0 var(--ct-table-of-contents-link-active-border-radius) var(--ct-table-of-contents-link-active-border-radius) 0;
+    }
+
+    &:focus-visible {
+      z-index: 1;
+    }
+  }
+
+  @include ct-component-theme($root) using($root, $theme) {
+    #{$root}__title {
+      @include ct-component-property($root, $theme, title, color);
+    }
+
+    #{$root}__link {
+      @include ct-component-property($root, $theme, link, color);
+      @include ct-component-property($root, $theme, link, background-color);
+
+      &::before {
+        @include ct-component-property($root, $theme, link, stripe, background-color);
+      }
+
+      &:hover,
+      &:focus-visible,
+      &:active {
+        @include ct-component-property($root, $theme, link, hover, background-color);
+        @include ct-component-property($root, $theme, link, hover, color);
+
+        &::before {
+          @include ct-component-property($root, $theme, link, hover, stripe, background-color);
+        }
+      }
+
+      &:active {
+        @include ct-component-property($root, $theme, link, hover, border-color);
+
+        border-width: ct-particle(0.125);
+        border-left-width: 0;
+        padding-top: ct-spacing(1 - 0.125);
+        padding-bottom: ct-spacing(1 - 0.125);
+      }
+
+      &:focus-visible {
+        @include ct-outline-theme($theme);
+      }
+    }
+  }
+}

package/components/02-molecules/table-of-contents/table-of-contents.stories.js

@@ -0,0 +1,88 @@
+/**
+ * CivicTheme Table of Contents component stories.
+ */
+
+import Component from './table-of-contents.twig';
+import BasicContent from '../basic-content/basic-content.twig';
+
+const meta = {
+  title: 'Molecules/Table Of Contents',
+  component: Component,
+  argTypes: {
+    theme: {
+      control: { type: 'radio' },
+      options: ['light', 'dark'],
+    },
+    title: {
+      control: { type: 'text' },
+    },
+    anchor_selector: {
+      control: { type: 'text' },
+    },
+    scope_selector: {
+      control: { type: 'text' },
+    },
+    position: {
+      control: { type: 'radio' },
+      options: ['before', 'after', 'prepend', 'append'],
+    },
+    modifier_class: {
+      control: { type: 'text' },
+    },
+  },
+};
+
+export default meta;
+
+export const TableOfContents = {
+  args: {
+    theme: 'light',
+    title: 'On this page',
+    links: [
+      {
+        title: 'Link 1',
+        url: '/',
+      },
+      {
+        title: 'Link 2',
+        url: '/',
+      },
+      {
+        title: 'Link 3',
+        url: '/',
+      },
+    ],
+    position: 'before',
+    modifier_class: '',
+    attributes: null,
+  },
+};
+
+export const TableOfContentsAutomatic = {
+  parameters: {
+    layout: 'centered',
+  },
+  args: {
+    theme: 'light',
+    title: 'On this page',
+    anchor_selector: 'h2',
+    scope_selector: '.ct-basic-content',
+    position: 'before',
+    content: BasicContent({ content: `
+      <h2>Heading 2 - 1</h2>
+      <p>Ex cillum irure id occaecat aliquip in cillum aute occaecat ullamco in dolore nulla et veniam sed consectetur ut excepteur eu eiusmod excepteur nulla id mollit veniam deserunt ea nostrud.</p>
+      <h3>Heading 3</h3>
+      <h4>Heading 4</h4>
+      <h5>Heading 5</h5>
+      <h6>Heading 6</h6>
+      <p>Consectetur veniam exercitation voluptate reprehenderit in esse est magna minim sunt cupidatat reprehenderit ut pariatur cillum do aute adipisicing commodo voluptate quis in tempor eu irure velit esse non dolore officia sit cupidatat officia fugiat mollit eu.</p>
+      <h2>Heading 2 - 2</h2>
+      <p>Est incididunt irure eu elit eiusmod incididunt occaecat labore aute in ad non irure sunt ad ut nostrud commodo do fugiat fugiat tempor occaecat mollit sunt in id sed commodo enim occaecat eu proident nostrud fugiat cupidatat.</p>
+      <h2>Heading 2 - 3</h2>
+      <p>Nulla sed cupidatat irure quis veniam ut in in pariatur do minim adipisicing minim exercitation magna eiusmod culpa tempor.</p>
+      <h2>&nbsp;</h2>
+    ` }),
+    modifier_class: '',
+    attributes: null,
+  },
+};

package/components/02-molecules/table-of-contents/table-of-contents.twig

@@ -0,0 +1,63 @@
+{#
+/**
+ * @file
+ * CivicTheme Table of Contents component.
+ *
+ * Props:
+ * - theme: [string] Theme variation (light or dark).
+ * - title: [string] Link title.
+ * - position: [string] TOC position ('before', 'after', 'prepend', 'append').
+ * - anchor_selector: [string] CSS selector for headings to include in TOC (e.g. 'h2, h3').
+ * - scope_selector: [string] CSS selector for the content area to generate TOC from.
+ * - modifier_class: [string] Additional CSS classes.
+ * - attributes: [Drupal\Core\Template\Attribute] Additional HTML attributes.
+ *
+ * Slots:
+ * - links: Table of contents links.
+ * - content: Content (only displays when links are not provided).
+ *
+ * Blocks:
+ * - content_block
+ */
+#}
+
+{% if links is not empty or scope_selector is not empty %}
+  <div class="container">
+    <div class="row">
+      <div class="col-xxs-12">
+        {% if links %}
+          {% set theme_class = 'ct-theme-%s'|format(theme|default('light')) %}
+          {% set position_class = 'ct-table-of-contents--position-%s'|format(position|default('before')) %}
+          {% set modifier_class = '%s %s %s'|format(theme_class, position_class, modifier_class|default('')) %}
+
+          <div class="ct-table-of-contents {{ modifier_class }}" {% if attributes is defined and attributes is not null %}{{- attributes -}}{% endif %}>
+            {% if title %}
+              <h2 class="ct-table-of-contents__title">{{ title }}</h2>
+            {% endif %}
+            {% if links %}
+              <ul class="ct-table-of-contents__links">
+                {% for link in links %}
+                  <li class="ct-table-of-contents__link-item">
+                    <a class="ct-table-of-contents__link" href="{{ link.url }}">{{ link.title }}</a>
+                  </li>
+                {% endfor %}
+              </ul>
+            {% endif %}
+          </div>
+        {% else %}
+          <div
+            data-table-of-contents-theme="{{ theme }}"
+            data-table-of-contents-title="{{ title }}"
+            data-table-of-contents-anchor-selector="{{ anchor_selector }}"
+            data-table-of-contents-anchor-scope-selector="{{ scope_selector }}"
+            data-table-of-contents-position="{{ position }}"
+          >
+            {%- block content_block -%}
+              {{- content -}}
+            {%- endblock -%}
+          </div>
+        {% endif %}
+      </div>
+    </div>
+  </div>
+{% endif %}