@dta-au/civictheme-twig 1.13.3 → 1.13.4

package/components/01-atoms/summary-list/summary-list.mdx

@@ -0,0 +1,37 @@
+{/* Generated by packages/sdc/scripts/import-dga-dl-docs.js — re-run to refresh. */}
+{/* Source: digital.gov.au design library (dga-dl /src/content). */}
+{/* Cross-link rewrites deferred to beads ui-kit-dev-space-r0f — links may be broken. */}
+
+import { Meta, Canvas } from '@storybook/addon-docs/blocks';
+import * as Stories from './summary-list.stories';
+
+<Meta of={Stories} />
+
+# Summary list
+
+A structured list of name–value pairs for displaying record summaries and metadata.
+
+<Canvas of={Stories.Default} />
+
+Use a summary list to display structured information as labelled name–value pairs. Typical uses include review and confirm screens before form submission, metadata panels on record or profile pages, and read-only summaries of collected data.
+
+The component renders as a styled `<dl>` element with `<dt>` (term) and `<dd>` (description) pairs.
+
+## When to use
+
+- data has a clear label and a corresponding value for each item
+- summarising information a user has entered before they submit a form
+- presenting metadata about a record, file, or entity – such as dates, statuses, or identifiers
+- showing read-only field data on a profile or detail page
+
+## When not to use
+
+- for content that needs running prose – use a rich text body instead
+- when the data is tabular with multiple columns of comparable items – use a [Table](/components/table/) instead
+- for navigational lists – use [Manual list](/components/manual-list/) or [Feature link list](/components/feature-link-list/) instead
+- when there are only one or two pairs – a simple paragraph is sufficient
+
+## Related components
+
+- [Table](/components/table/) – use when data has multiple comparable rows and columns.
+- [Content](/components/content/) – use for free-form body text and formatted content.

package/components/01-atoms/summary-list/summary-list.scss

@@ -0,0 +1,107 @@
+//
+// CivicTheme Summary List component styles.
+//
+
+.ct-summary-list {
+  $root: &;
+
+  margin: 0;
+  padding: 0;
+
+  #{$root}__row {
+    display: flex;
+    flex-wrap: wrap;
+    border-bottom: ct-particle(0.125) solid transparent;
+    padding: ct-spacing(2) 0;
+    gap: ct-spacing(1);
+
+    &:last-child {
+      border-bottom: none;
+    }
+
+    @include ct-breakpoint(m) {
+      flex-wrap: nowrap;
+      gap: 0;
+    }
+  }
+
+  &--no-border {
+    #{$root}__row {
+      border-bottom: none;
+      padding: ct-spacing(1) 0;
+    }
+  }
+
+  #{$root}__key {
+    @include ct-typography('label-regular');
+
+    flex: 0 0 100%;
+    margin: 0;
+
+    & > p {
+      @include ct-typography('label-regular');
+    }
+
+    @include ct-breakpoint(m) {
+      flex: 0 0 30%;
+      padding-right: ct-spacing(2);
+    }
+  }
+
+  #{$root}__value {
+    @include ct-typography('text-regular');
+
+    flex: 1;
+    margin: 0;
+    word-break: break-word;
+    overflow-wrap: anywhere;
+
+    & > p {
+      @include ct-typography('text-regular');
+    }
+
+    @include ct-breakpoint(m) {
+      flex: 1 1 auto;
+    }
+  }
+
+  #{$root}__actions {
+    margin: 0;
+    flex: 0 0 auto;
+
+    @include ct-breakpoint(m) {
+      text-align: right;
+      padding-left: ct-spacing(2);
+    }
+  }
+
+  #{$root}__action-link {
+    @include ct-typography('label-regular');
+
+    &:hover {
+      text-decoration: none;
+    }
+  }
+
+  @include ct-component-theme($root) using($root, $theme) {
+    #{$root}__row {
+      @include ct-component-property($root, $theme, row, border-color);
+    }
+
+    #{$root}__key {
+      @include ct-component-property($root, $theme, key, color);
+    }
+
+    #{$root}__value {
+      @include ct-component-property($root, $theme, value, color);
+    }
+
+    #{$root}__action-link {
+      @include ct-component-property($root, $theme, action, color);
+
+      &:hover {
+        @include ct-component-property($root, $theme, action, hover, color);
+      }
+    }
+  }
+}

package/components/01-atoms/summary-list/summary-list.stories.js

@@ -0,0 +1,89 @@
+/**
+ * CivicTheme Summary List component stories.
+ */
+
+import Component from './summary-list.twig';
+
+const meta = {
+  title: 'Content/Summary list',
+  component: Component,
+  tags: ['digitalgovau'],
+  parameters: {
+    layout: 'padded',
+  },
+  argTypes: {
+    theme: {
+      control: { type: 'radio' },
+      options: ['light', 'dark'],
+    },
+    no_border: {
+      control: { type: 'boolean' },
+    },
+    items: {
+      control: { type: 'object' },
+    },
+    modifier_class: {
+      control: { type: 'text' },
+    },
+  },
+};
+
+export default meta;
+
+const defaultItems = [
+  { key: 'Full name', value: 'Jane Citizen' },
+  { key: 'Date of birth', value: '1 January 1980' },
+  { key: 'Contact email', value: 'jane.citizen@example.gov.au' },
+  { key: 'Address', value: '123 Example Street, Canberra ACT 2600' },
+];
+
+export const Default = {
+  name: 'Light theme',
+  args: {
+    theme: 'light',
+    items: defaultItems,
+    no_border: false,
+    modifier_class: '',
+    attributes: null,
+  },
+};
+
+export const DarkTheme = {
+  name: 'Dark theme',
+  globals: {
+    backgrounds: { value: 'dark' },
+  },
+  args: {
+    theme: 'dark',
+    items: defaultItems.slice(0, 3),
+    no_border: false,
+    modifier_class: '',
+    attributes: null,
+  },
+};
+
+export const NoBorder = {
+  name: 'No border',
+  args: {
+    theme: 'light',
+    items: defaultItems.slice(0, 3),
+    no_border: true,
+    modifier_class: '',
+    attributes: null,
+  },
+};
+
+export const WithActions = {
+  name: 'With actions',
+  args: {
+    theme: 'light',
+    no_border: false,
+    modifier_class: '',
+    attributes: null,
+    items: [
+      { key: 'Full name', value: 'Jane Citizen', action_url: '#', action_text: 'Change' },
+      { key: 'Date of birth', value: '1 January 1980', action_url: '#', action_text: 'Change' },
+      { key: 'Contact email', value: 'jane.citizen@example.gov.au', action_url: '#', action_text: 'Change' },
+    ],
+  },
+};

package/components/01-atoms/summary-list/summary-list.twig

@@ -0,0 +1,47 @@
+{#
+/**
+ * @file
+ * CivicTheme Summary List component.
+ *
+ * Props:
+ * - theme: [string]
+ * - no_border: [boolean]
+ * - items: [array] :
+ *   Each item contains:
+ *   - key: [string]
+ *   - value: [string]
+ *   - action_url: [string]
+ *   - action_text: [string]
+ * - modifier_class: [string]
+ * - attributes: [Drupal\Core\Template\Attribute] Additional HTML attributes.
+ */
+#}
+
+{% set theme = theme in ['light', 'dark'] ? theme : 'light' %}
+{% set theme_class = 'ct-theme-%s'|format(theme) %}
+{% set no_border_class = no_border ? 'ct-summary-list--no-border' : '' %}
+{% set modifier_class = '%s %s %s'|format(theme_class, no_border_class, modifier_class|default('')) %}
+
+{% if items is not empty %}
+  <dl
+    class="ct-summary-list {{ modifier_class|trim }}"
+    data-component-name="ct-summary-list"
+    {%- if attributes is defined and attributes is not null %} {{- attributes -}}{% endif %}
+  >
+    {% for item in items %}
+      {% if item.key is not empty and item.value is not empty %}
+        <div class="ct-summary-list__row">
+          <dt class="ct-summary-list__key">{{ item.key }}</dt>
+          <dd class="ct-summary-list__value">{{ item.value }}</dd>
+          {% if item.action_url is not empty %}
+            <dd class="ct-summary-list__actions">
+              <a href="{{ item.action_url }}" class="ct-summary-list__action-link">
+                {{- item.action_text|default('Change') -}}
+              </a>
+            </dd>
+          {% endif %}
+        </div>
+      {% endif %}
+    {% endfor %}
+  </dl>
+{% endif %}

package/components/01-atoms/table-sort/table-sort.js

@@ -0,0 +1,199 @@
+/**
+ * @file
+ * Table Sort — framework-agnostic progressive enhancement.
+ *
+ * Finds all tables with the class `ct-table--sortable` and progressively
+ * enhances them with MOJ-style sortable column header buttons.
+ *
+ * Usage: apply the class `ct-table--sortable` to any <table> element. The
+ * behavior attaches automatically via DOMContentLoaded (static/Storybook) or
+ * Drupal.behaviors (Drupal). Stories call window.DgaTableSort.initAll().
+ *
+ * Pre-sorted columns: add aria-sort="ascending|descending" directly to the
+ * <th>, or add the class `ct-sort--asc` / `ct-sort--desc`.
+ *
+ * Custom sort values: add data-sort-value="..." to any <td> to override what
+ * value is used for sorting (e.g. a numeric timestamp for a date cell).
+ */
+
+/* global Drupal */
+
+(function () {
+  'use strict';
+
+  // SVG arrow icons — MOJ Design System pattern.
+  // focusable="false" + aria-hidden="true" hides icons from assistive tech.
+  // fill="currentColor" ensures visibility in Windows High Contrast Mode.
+  const SVG_UP = '<svg width="22" height="22" focusable="false" aria-hidden="true" role="img" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M6.5625 15.5L11 6.63125L15.4375 15.5H6.5625Z" fill="currentColor"/></svg>';
+  const SVG_DOWN = '<svg width="22" height="22" focusable="false" aria-hidden="true" role="img" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M15.4375 7L11 15.8687L6.5625 7L15.4375 7Z" fill="currentColor"/></svg>';
+  const SVG_UPDOWN = '<svg width="22" height="22" focusable="false" aria-hidden="true" role="img" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M8.1875 9.5L10.9609 3.95703L13.7344 9.5H8.1875Z" fill="currentColor"/><path d="M13.7344 12.0781L10.9609 17.6211L8.1875 12.0781H13.7344Z" fill="currentColor"/></svg>';
+
+  // ---------------------------------------------------------------------------
+  // Helpers.
+  // ---------------------------------------------------------------------------
+
+  function getCellValue(cell) {
+    if (!cell) return '';
+    const raw = cell.getAttribute('data-sort-value') || cell.textContent.trim();
+    const num = Number(raw);
+    return Number.isFinite(num) ? num : raw;
+  }
+
+  function updateIcons(headings) {
+    headings.forEach((th) => {
+      const btn = th.querySelector('.ct-sort-btn');
+      if (!btn) return;
+
+      const existing = btn.querySelector('svg');
+      if (existing) existing.remove();
+
+      const dir = th.getAttribute('aria-sort');
+      btn.insertAdjacentHTML('beforeend',
+        dir === 'ascending' ? SVG_UP :
+        dir === 'descending' ? SVG_DOWN :
+        SVG_UPDOWN
+      );
+    });
+  }
+
+  function sortRows(tbody, colIndex, direction) {
+    const rows = Array.from(tbody.querySelectorAll('tr'));
+    const ascending = direction === 'ascending';
+
+    rows.sort((a, b) => {
+      const aCell = a.querySelectorAll('td, th')[colIndex];
+      const bCell = b.querySelectorAll('td, th')[colIndex];
+      const aVal = getCellValue(aCell);
+      const bVal = getCellValue(bCell);
+
+      if (typeof aVal === 'number' && typeof bVal === 'number') {
+        return ascending ? aVal - bVal : bVal - aVal;
+      }
+      return ascending
+        ? String(aVal).localeCompare(String(bVal))
+        : String(bVal).localeCompare(String(aVal));
+    });
+
+    rows.forEach((row) => tbody.appendChild(row));
+  }
+
+  function initialiseSortedColumn(headings, tbody) {
+    headings.forEach((th) => {
+      const dir = th.getAttribute('aria-sort');
+      if (dir !== 'ascending' && dir !== 'descending') return;
+      const btn = th.querySelector('.ct-sort-btn');
+      if (!btn) return;
+      sortRows(tbody, parseInt(btn.getAttribute('data-index'), 10), dir);
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Core enhancement — no Drupal dependency.
+  // ---------------------------------------------------------------------------
+
+  function initTable(table) {
+    // Idempotency guard — replaces once().
+    if (table.dataset.tableSortInit) return;
+    table.dataset.tableSortInit = 'true';
+
+    const thead = table.querySelector('thead');
+    const tbody = table.querySelector('tbody');
+
+    if (!thead || !tbody) return;
+
+    const headings = Array.from(thead.querySelectorAll('th'));
+
+    // Resolve initial aria-sort state for every heading.
+    // Priority: existing aria-sort attribute > ct-sort--* class > 'none'.
+    headings.forEach((th) => {
+      const preset = th.getAttribute('aria-sort')
+        || (th.classList.contains('ct-sort--asc') ? 'ascending'
+        : th.classList.contains('ct-sort--desc') ? 'descending'
+        : 'none');
+      th.setAttribute('aria-sort', preset);
+    });
+
+    // Inject a sort button into every heading.
+    headings.forEach((th, index) => {
+      if (th.querySelector('.ct-sort-btn')) return;
+
+      const label = th.textContent.trim();
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = 'ct-sort-btn';
+      btn.setAttribute('data-index', String(index));
+      btn.textContent = label;
+
+      th.textContent = '';
+      th.appendChild(btn);
+    });
+
+    updateIcons(headings);
+    initialiseSortedColumn(headings, tbody);
+
+    // aria-live region so screen readers announce sort changes.
+    const status = document.createElement('div');
+    status.setAttribute('aria-atomic', 'true');
+    status.setAttribute('aria-live', 'polite');
+    status.setAttribute('role', 'status');
+    status.className = 'ct-visually-hidden';
+    table.insertAdjacentElement('afterend', status);
+
+    // Abort any previous listener — prevents accumulation when the idempotency
+    // guard is cleared on HMR reuse.
+    if (table.sortAbort) table.sortAbort.abort();
+    const controller = new AbortController();
+    table.sortAbort = controller;
+
+    // Single delegated listener on thead — avoids per-button listeners.
+    thead.addEventListener('click', (event) => {
+      const btn = event.target.closest('.ct-sort-btn');
+      if (!btn) return;
+
+      const th = btn.parentElement;
+      const current = th.getAttribute('aria-sort');
+      const newDir = (current === 'none' || current === 'descending') ? 'ascending' : 'descending';
+      const colIndex = parseInt(btn.getAttribute('data-index'), 10);
+
+      headings.forEach((h) => h.setAttribute('aria-sort', 'none'));
+      th.setAttribute('aria-sort', newDir);
+
+      updateIcons(headings);
+      sortRows(tbody, colIndex, newDir);
+
+      status.textContent = `Sort by ${btn.textContent.trim()} (${newDir})`;
+    }, { signal: controller.signal });
+  }
+
+  /**
+   * Initialise all sortable tables within a given context element.
+   *
+   * @param {Element|Document} [context=document]
+   */
+  function initAll(context) {
+    (context || document).querySelectorAll('.ct-table--sortable').forEach(initTable);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Integration.
+  // ---------------------------------------------------------------------------
+
+  // Expose globally for Storybook play() and static pages.
+  window.DgaTableSort = { initAll };
+
+  // Drupal: register as a behavior for AJAX-safe re-attachment.
+  if (typeof Drupal !== 'undefined') {
+    Drupal.behaviors.dgaTableSort = {
+      attach(context) {
+        initAll(context);
+      },
+    };
+  } else {
+    // Non-Drupal: init elements in the DOM now, then watch for future
+    // insertions via MutationObserver (covers static pages and Storybook).
+    initAll();
+    new MutationObserver(() => initAll())
+      .observe(document.body || document.documentElement, { childList: true, subtree: true });
+  }
+
+})();

package/components/01-atoms/table-sort/table-sort.scss

@@ -0,0 +1,65 @@
+// Sort button styles. Applied when the DgaTableSort behavior enhances a `.ct-table--sortable` table.
+// Buttons are injected into <th> cells by JS — styles are global-scoped since
+// we're enhancing existing CivicTheme tables, not a component-owned element.
+
+.ct-basic-content table,
+.table-container table,
+.ct-table {
+  th {
+    &:has(> .ct-sort-btn) {
+      padding: ct-spacing(1.5) ct-spacing(3);
+    }
+  }
+}
+
+.ct-sort-btn {
+  display: flex;
+  align-items: center;
+  gap: ct-spacing(1);
+  width: 100%;
+  padding: ct-spacing(1) 0;
+  background: none;
+  border: none;
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: inherit;
+  color: inherit;
+  text-align: left;
+  cursor: pointer;
+  white-space: nowrap;
+
+  &:focus-visible {
+    @include ct-outline();
+    @include ct-outline-border();
+  }
+
+  // SVG sort indicator — injected by JS, sized to scale with text.
+  svg {
+    flex-shrink: 0;
+    margin-left: auto;
+
+    // Dim the up/down icon when the column is unsorted.
+    [aria-sort='none'] & {
+      opacity: 0.4;
+    }
+  }
+}
+
+// .ct-sort-btn is injected as a child of <th> and is never the themed root,
+// so ct-component-theme() (which targets &.ct-theme-*) cannot be used here.
+// The parent selector is the correct pattern for descendant-only theming.
+.ct-theme-dark .ct-sort-btn:focus-visible {
+  @include ct-outline(true);
+}
+
+// Screen-reader-only utility for the aria-live status region.
+.ct-visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: 0;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+}

package/components/01-atoms/table-sort/table-sort.stories.js

@@ -0,0 +1,142 @@
+/**
+ * CivicTheme Table Sort atom stories.
+ *
+ * Table Sort is a pure CSS/JS enhancement — there is no Twig template.
+ * Apply the class `ct-table--sortable` to any <table> element to enable
+ * MOJ-style sortable column header buttons.
+ *
+ * Pre-sorted columns: add aria-sort="ascending|descending" to a <th>.
+ * Custom sort values: add data-sort-value="..." to a <td>.
+ *
+ * CSS and JS are imported explicitly here because the sdc-plugin auto-discovers
+ * assets via Twig imports — this component has no Twig template, so they must
+ * be declared manually.
+ */
+
+import './table-sort.css';
+import './table-sort.js';
+// table.js sets data-title attrs on tbody cells so mobile pseudo-element labels
+// render; table.css carries the matching `content: attr(data-title)` rule. The
+// sdc-plugin only auto-loads sibling assets via Twig imports — this atom has no
+// Twig template, so the table assets must be pulled in explicitly.
+import '../table/table.js';
+import '../table/table.css';
+
+const meta = {
+  title: 'Content/Tables/Table sort',
+  tags: ['digitalgovau'],
+  parameters: {
+    layout: 'padded',
+  },
+};
+
+export default meta;
+
+function teardownTableSort(canvasElement) {
+  canvasElement.querySelectorAll('.ct-table--sortable').forEach((el) => {
+    if (!el.dataset.tableSortInit) return;
+    const next = el.nextElementSibling;
+    if (next?.getAttribute('role') === 'status') next.remove();
+    delete el.dataset.tableSortInit;
+  });
+}
+
+export const TableSort = {
+  play: async ({ canvasElement }) => {
+    teardownTableSort(canvasElement);
+    window.DgaTableSort.initAll(canvasElement);
+  },
+  render: () => `
+    <div class="container">
+      <div class="row">
+        <div class="col-xxs-12">
+
+    <table class="ct-table ct-table--sortable ct-theme-light">
+      <thead>
+        <tr>
+          <th>Entity</th>
+          <th>Portfolio</th>
+          <th aria-sort="ascending">Year</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>Australian Taxation Office</td>
+          <td>Treasury</td>
+          <td data-sort-value="2024">2024</td>
+        </tr>
+        <tr>
+          <td>Department of Finance</td>
+          <td>Finance</td>
+          <td data-sort-value="2023">2023</td>
+        </tr>
+        <tr>
+          <td>Services Australia</td>
+          <td>Finance</td>
+          <td data-sort-value="2025">2025</td>
+        </tr>
+        <tr>
+          <td>Australian Federal Police</td>
+          <td>Attorney General's</td>
+          <td data-sort-value="2022">2022</td>
+        </tr>
+        <tr>
+          <td>Digital Transformation Agency</td>
+          <td>Finance</td>
+          <td data-sort-value="2024">2024</td>
+        </tr>
+      </tbody>
+    </table>
+    </div></div></div>
+  `,
+};
+
+export const TableSortWithPreSortedColumn = {
+  name: 'Pre-sorted Column (descending)',
+  play: async ({ canvasElement }) => {
+    teardownTableSort(canvasElement);
+    window.DgaTableSort.initAll(canvasElement);
+  },
+  render: () => `
+    <div class="container">
+      <div class="row">
+        <div class="col-xxs-12">
+    <table class="ct-table ct-table--sortable ct-theme-light">
+      <thead>
+        <tr>
+          <th aria-sort="descending">Entity</th>
+          <th>Portfolio</th>
+          <th>Year</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>Australian Taxation Office</td>
+          <td>Treasury</td>
+          <td data-sort-value="2024">2024</td>
+        </tr>
+        <tr>
+          <td>Department of Finance</td>
+          <td>Finance</td>
+          <td data-sort-value="2023">2023</td>
+        </tr>
+        <tr>
+          <td>Services Australia</td>
+          <td>Finance</td>
+          <td data-sort-value="2025">2025</td>
+        </tr>
+        <tr>
+          <td>Australian Federal Police</td>
+          <td>Attorney General's</td>
+          <td data-sort-value="2022">2022</td>
+        </tr>
+        <tr>
+          <td>Digital Transformation Agency</td>
+          <td>Finance</td>
+          <td data-sort-value="2024">2024</td>
+        </tr>
+      </tbody>
+    </table>
+  </div></div></div>
+  `,
+};