@dta-au/civictheme-twig 1.13.5 → 1.14.0

package/components/00-base/about-civictheme/about-civictheme.stories.js

@@ -4,6 +4,7 @@ import Constants from '../../../dist/constants.json';
 const meta = {
   title: 'About CivicTheme',
   component: Component,
+  tags: ['!autodocs'],
   argTypes: {
     logos: {
       table: {

package/components/00-base/collapsible/collapsible.stories.js

@@ -3,6 +3,7 @@ import Component from './collapsible.stories.twig';
 const meta = {
   title: 'Base/Utilities/Collapsible',
   component: Component,
+  tags: ['!autodocs'],
 };
 
 export default meta;

package/components/00-base/elevation/elevation.stories.js

@@ -3,6 +3,7 @@ import Component from './elevation.stories.twig';
 const meta = {
   title: 'Base/Elevation',
   component: Component,
+  tags: ['!autodocs'],
 };
 
 export default meta;

package/components/00-base/layout/__snapshots__/layout.test.js.snap

@@ -9,9 +9,8 @@ exports[`Layout Component hides sidebars when specified - contained 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-sidebar-left ct-layout--no-sidebar-right ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right"
-    role="main"
   >
     
               
@@ -36,7 +35,7 @@ exports[`Layout Component hides sidebars when specified - contained 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -51,9 +50,8 @@ exports[`Layout Component hides sidebars when specified 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-sidebar-left ct-layout--no-sidebar-right ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right"
-    role="main"
   >
     
               
@@ -78,7 +76,7 @@ exports[`Layout Component hides sidebars when specified 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -93,9 +91,8 @@ exports[`Layout Component only main - contained 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right"
-    role="main"
   >
     
               
@@ -120,7 +117,7 @@ exports[`Layout Component only main - contained 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -135,9 +132,8 @@ exports[`Layout Component only main - not contained 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right"
-    role="main"
   >
     
               
@@ -162,7 +158,7 @@ exports[`Layout Component only main - not contained 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -177,9 +173,8 @@ exports[`Layout Component renders with all sidebars and content sections 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-vertical-spacing--top"
-    role="main"
   >
     
           Top content    
@@ -232,7 +227,7 @@ exports[`Layout Component renders with all sidebars and content sections 1`] = `
     
 
           Bottom content      
-  </main>
+  </div>
   
 
 </div>
@@ -247,10 +242,9 @@ exports[`Layout Component renders with custom attributes and classes 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right  custom-modifier"
     data-test="true"
-    role="main"
   >
     
               
@@ -275,7 +269,7 @@ exports[`Layout Component renders with custom attributes and classes 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -290,9 +284,8 @@ exports[`Layout Component renders with default values 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right"
-    role="main"
   >
     
               
@@ -317,7 +310,7 @@ exports[`Layout Component renders with default values 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -332,9 +325,8 @@ exports[`Layout Component renders with sidebar bottom left 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left ct-layout--no-top-right  ct-layout--no-bottom-right ct-vertical-spacing--top"
-    role="main"
   >
     
               
@@ -366,7 +358,7 @@ exports[`Layout Component renders with sidebar bottom left 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -381,9 +373,8 @@ exports[`Layout Component renders with sidebar bottom right 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left  ct-vertical-spacing--top"
-    role="main"
   >
     
               
@@ -415,7 +406,7 @@ exports[`Layout Component renders with sidebar bottom right 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -430,9 +421,8 @@ exports[`Layout Component renders with sidebar top left 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right ct-vertical-spacing--top"
-    role="main"
   >
     
               
@@ -464,7 +454,7 @@ exports[`Layout Component renders with sidebar top left 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -479,9 +469,8 @@ exports[`Layout Component renders with sidebar top right 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left  ct-layout--no-bottom-left ct-layout--no-bottom-right ct-vertical-spacing--top"
-    role="main"
   >
     
               
@@ -513,7 +502,7 @@ exports[`Layout Component renders with sidebar top right 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>

package/components/00-base/layout/layout.twig

@@ -57,7 +57,7 @@
 {% set modifier_class = modifier_class|trim %}
 
 {% if content %}
-  <main class="ct-layout {{ modifier_class -}}" role="main" {% if attributes is defined and attributes is not null %}{{- attributes -}}{% endif %}>
+  <div class="ct-layout {{ modifier_class -}}" {% if attributes is defined and attributes is not null %}{{- attributes -}}{% endif %}>
     {% block content_top_block %}
       {% if content_top is not empty %}
         {{- content_top -}}
@@ -111,5 +111,5 @@
         {{- content_bottom -}}
       {% endif %}
     {% endblock %}
-  </main>
+  </div>
 {% endif %}

package/components/00-base/responsive/responsive.stories.js

@@ -3,6 +3,7 @@ import Component from './responsive.stories.twig';
 const meta = {
   title: 'Base/Utilities/Responsive',
   component: Component,
+  tags: ['!autodocs'],
 };
 
 export default meta;

package/components/00-base/scrollspy/scrollspy.stories.js

@@ -3,6 +3,7 @@ import Component from './scrollspy.stories.twig';
 const meta = {
   title: 'Base/Utilities/Scrollspy',
   component: Component,
+  tags: ['!autodocs'],
 };
 
 export default meta;

package/components/00-base/spacing/spacing.stories.js

@@ -3,6 +3,7 @@ import Component from './spacing.stories.twig';
 const meta = {
   title: 'Base/Spacing',
   component: Component,
+  tags: ['!autodocs'],
 };
 
 export default meta;

package/components/00-base/typography/typography.stories.js

@@ -3,6 +3,7 @@ import Component from './typography.stories.twig';
 const meta = {
   title: 'Base/Typography',
   component: Component,
+  tags: ['!autodocs'],
 };
 
 export default meta;

package/components/00-base/welcome/welcome.stories.js

@@ -4,6 +4,7 @@ import Constants from '../../../dist/constants.json';
 const meta = {
   title: 'Welcome',
   component: Component,
+  tags: ['!autodocs'],
   argTypes: {
     logos: {
       table: {

package/components/01-atoms/iframe/iframe.mdx

@@ -0,0 +1,56 @@
+{/* Editorial guidance ported from the digital.gov.au design library (dga-dl /src/content). */}
+{/* Internal /patterns and /templates links demoted to plain text – they do not resolve in Storybook. */}
+
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as Stories from './iframe.stories';
+
+<Meta of={Stories} />
+
+# iFrame
+
+A callout draws attention to important or interesting information.
+
+<Canvas of={Stories.Iframe} />
+
+<Controls of={Stories.Iframe} />
+
+<div style="box-sizing: border-box;
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    border-width: 0;
+    border-left-width: 1px;
+    border-right-width: 1px;
+    border-top-width: 1px;
+    border-bottom-width: 1px;
+    border-color: var(--ct-color-light-border-light);
+    border-style: solid;
+    border-radius: 4px;">
+<Canvas of={Stories.Iframe} />
+</div>
+
+
+Use callout to draw a user's attention to important snippets of static information.
+
+## Do
+
+- use sparingly as they are intrusive
+- use to help users quickly scan to find essential information in a long text page
+- use to reiterate important content
+- use to format content not included in the main text such as support and contact details, checklists, definitions and 'Did you know?' content.
+
+## Don't
+- use for primary content, as it may be missed
+- use for quotes in long-form content - use a **Quote** instead
+- make them the focus of content; they are a supporting tool
+- use for errors and alerts – use an alert or message instead
+- embed form inputs in Callouts
+- use in conditionally revealed checkbox or radio groups
+- mix colour palettes.
+
+## Related components
+- Global alert – Global alerts display prominent service or system wide messages at the top of the screen.
+- Message – A message is a colour-coded, non-disruptive notification that provides Success, Error, Warning or Information messages within a page at relevant times during the user journey. They should not be confused with Callouts.
+
+## Related patterns
+- Messaging – Messaging conveys contextual information to the user, provides information in relation to a service or interaction, and provides feedback in response to their actions or the current system status.

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

@@ -1,8 +1,7 @@
-{/* 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. */}
+{/* Editorial guidance ported from the digital.gov.au design library (dga-dl /src/content). */}
+{/* Internal /patterns and /templates links demoted to plain text – they do not resolve in Storybook. */}
 
-import { Meta, Canvas } from '@storybook/addon-docs/blocks';
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
 import * as Stories from './summary-list.stories';
 
 <Meta of={Stories} />
@@ -13,6 +12,8 @@ A structured list of name–value pairs for displaying record summaries and meta
 
 <Canvas of={Stories.Default} />
 
+<Controls 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.
@@ -27,11 +28,11 @@ The component renders as a styled `<dl>` element with `<dt>` (term) and `<dd>` (
 ## 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 the data is tabular with multiple columns of comparable items – use a **Table** instead
+- for navigational lists – use **Manual list** or **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.
+- **Table** – use when data has multiple comparable rows and columns.
+- **Content** – use for free-form body text and formatted content.

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

@@ -23,6 +23,12 @@
       flex-wrap: nowrap;
       gap: 0;
     }
+
+    // The display:flex above outranks the UA [hidden] rule, so a row the
+    // filterable-table behaviour hides would otherwise stay visible.
+    &[hidden] {
+      display: none;
+    }
   }
 
   &--no-border {

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

@@ -19,6 +19,9 @@ const meta = {
     no_border: {
       control: { type: 'boolean' },
     },
+    id: {
+      control: { type: 'text' },
+    },
     items: {
       control: { type: 'object' },
     },
@@ -87,3 +90,37 @@ export const WithActions = {
     ],
   },
 };
+
+// Rows carry id + per-row filter_values, the contract the filterable-table
+// behaviour (target_type: list) reads via data-filter-col-N. Glossary example
+// (term -> definition) — the canonical <dl> use case; Category is a filter
+// dimension not shown in the row. See the "Filterable Definition List" story
+// under Content/Tables/Filterable table for the controls wired up. The <dl>
+// alone is fully usable without JS.
+export const Filterable = {
+  name: 'With filter attributes',
+  args: {
+    theme: 'light',
+    no_border: false,
+    modifier_class: '',
+    attributes: null,
+    id: 'digital-glossary',
+    items: [
+      {
+        key: 'Accessibility',
+        value: 'Designing services so everyone, including people with disability, can use them.',
+        filter_values: ['Accessibility', 'Inclusion'],
+      },
+      {
+        key: 'Design system',
+        value: 'A library of reusable components and standards for building consistent services.',
+        filter_values: ['Design system', 'Design'],
+      },
+      {
+        key: 'Open data',
+        value: 'Data published in a reusable, openly licensed, machine-readable format.',
+        filter_values: ['Open data', 'Data'],
+      },
+    ],
+  },
+};

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

@@ -6,12 +6,16 @@
  * Props:
  * - theme: [string]
  * - no_border: [boolean]
+ * - id: [string] Optional id on the <dl>, e.g. so a filterable-table control set can target it.
  * - items: [array] :
  *   Each item contains:
  *   - key: [string]
  *   - value: [string]
  *   - action_url: [string]
  *   - action_text: [string]
+ *   - filter_values: [array] Optional per-column filterable values (order matches the filterable-table columns). When set, the row carries data-filter-row plus data-filter-col-N attributes.
+ *     Each item contains:
+ *     - items [string]
  * - modifier_class: [string]
  * - attributes: [Drupal\Core\Template\Attribute] Additional HTML attributes.
  */
@@ -26,11 +30,15 @@
   <dl
     class="ct-summary-list {{ modifier_class|trim }}"
     data-component-name="ct-summary-list"
+    {%- if id is not empty %} id="{{ id }}"{% endif %}
     {%- 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">
+        <div
+          class="ct-summary-list__row"
+          {%- if item.filter_values is not empty %} data-filter-row{% for filter_value in item.filter_values %} data-filter-col-{{ loop.index0 }}="{{ filter_value }}"{% endfor %}{% endif %}
+        >
           <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 %}

package/components/01-atoms/table/table.mdx

@@ -0,0 +1,65 @@
+{/* Editorial guidance ported from the digital.gov.au design library (dga-dl /src/content). */}
+{/* Internal /patterns and /templates links demoted to plain text – they do not resolve in Storybook. */}
+
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as Stories from './table.stories';
+
+<Meta of={Stories} />
+
+# Table
+
+A structured display of data in rows and columns.
+
+<Canvas of={Stories.Table} />
+
+<Controls of={Stories.Table} />
+
+Use tables to present data that users need to scan, compare, or look up. Tables work well when information has a clear row-and-column structure and relationships between cells matter.
+
+## When to use
+
+- data has a meaningful row-and-column structure
+- users need to compare values across rows or columns
+- the data cannot be adequately expressed as a list or prose
+
+## When not to use
+
+- for layout purposes – tables are for data, not for arranging page elements
+- when the data has only one column – a list is more appropriate
+- when all rows contain the same value in most columns – reconsider the data structure
+
+## Variants
+
+### Standard
+
+A basic table with column headers, an optional caption, and optional zebra striping for readability.
+
+### Sortable
+
+Column headers become interactive sort controls. Clicking a header sorts that column ascending; clicking again sorts descending. Only one column sorts at a time. Sort direction is indicated with an icon.
+
+### Filterable
+
+Connects to the search-filters pattern. Three filter configurations apply depending on the number of filters:
+
+- **Small (1–2 filters):** filters appear inline above the table; no applied filter tags are needed.
+- **Medium (3–6 filters):** primary filters appear inline; remaining filters appear in an accordion triggered by 'Show filters'; applied filters are shown as dismissible tags.
+- **Large (6+ filters):** primary filters appear inline; remaining filters appear in a drawer triggered by 'Show filters'; the drawer has Apply, Clear, Close, and Cancel actions; applied filters are shown as dismissible tags.
+
+### Wide tables
+
+When table content overflows its container, a custom horizontal scrollbar renders at the bottom of the table. The scrollbar sticks to the bottom of the viewport when the bottom of the table is off-screen, so users can scroll horizontally from any row.
+
+### Spanning cells
+
+Cells can span multiple columns (`colSpan`) or rows (`rowSpan`) to represent data with genuinely hierarchical relationships. Use spanning cells only when the data relationship is inherently multi-dimensional. Do not use them to create visual layout effects.
+
+## Related components
+
+- **Filter sidebar** – use when filters should be persistently visible in a sidebar alongside the table.
+- **Summary list** – use for structured name–value pairs rather than rows-and-columns data.
+
+## Related patterns
+
+- Search filters – use to connect filter controls to a filterable table.
+- Pagination – use to limit the number of rows displayed at once in large datasets.

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

@@ -8,19 +8,16 @@
  * 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.
+ * In the twig package, CSS is bundled globally via civictheme.storybook.css,
+ * so no per-component CSS imports are needed — only the behaviour JS.
+ *
+ * @sync-ignore
+ * This file intentionally drifts from the SDC source: the SDC version imports
+ * per-component .css files so sdc-plugin can discover them; the twig Storybook
+ * build has no such files and resolves them globally.
  */
 
-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',

package/components/01-atoms/tag/tag.mdx

@@ -0,0 +1,51 @@
+{/* Editorial guidance ported from the digital.gov.au design library (dga-dl /src/content). */}
+{/* Internal /patterns and /templates links demoted to plain text – they do not resolve in Storybook. */}
+
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as Stories from './tag.stories';
+
+<Meta of={Stories} />
+
+# Tag
+
+A short label that signals status, audience, document type, or another classification axis.
+
+<Canvas of={Stories.Tag} />
+
+<Controls of={Stories.Tag} />
+
+A tag is a short label – usually one to three words – that classifies a page along an axis other than its title. Tags appear most often in page banners, where they signal status ('Mandatory', 'Draft'), audience or scope ('Whole-of-government'), document type ('Plan', 'Communique', 'Case study'), or a temporal horizon ('2025–2027').
+
+Tags carry information that travels with screenshots and search-result snippets. A reader who sees only the banner of a rule page should still know whether the rule is mandatory.
+
+## When to use
+
+Use a tag in a page banner when:
+
+- the page is a rule and its mandatory status needs to be visible
+- the page is one of a numbered set and its position in a second classification axis matters (for example, a statement's lifecycle stage)
+- the page is a published artefact whose document type is not obvious from the title (a case study, a communique, a plan)
+- the page is dated or versioned and that information is part of the page's identity
+
+A single page may carry one tag or a tag-list of two to four. More than four tags in a banner is a sign that the page's identity is unclear and the tags are doing the work the title should do.
+
+## When not to use
+
+Do not use a tag for:
+
+- topical taxonomy ('AI', 'investment') – that belongs in the site's content tagging system, not the page banner
+- the section the page lives in – breadcrumb covers that
+- a call to action – that belongs in a **callout** or **next step**
+
+Section landing pages do not typically carry banner tags – they are navigation surfaces, not classified artefacts.
+
+## Tag-list
+
+A tag-list is a horizontal group of two or more tags shown together. Use a tag-list when a page sits at the intersection of two or more classification axes – for example, a statement that is both 'Mandatory' and 'Lifecycle: Design'.
+
+Order the tags in the list from most general to most specific: status before audience before topic before date.
+
+## Related components
+
+- **Callout** – for the page's most important sentence; not a substitute for a tag.
+- **Banner** – the page header that hosts tags.