@dta-au/civictheme-twig 1.13.1

package/components/00-base/grid/grid.stories.scss

@@ -0,0 +1,184 @@
+//
+// CivicTheme Grid component story styles.
+//
+
+@use 'sass:math';
+
+.story-grid-outlines {
+  $_container-color: red;
+  $_fluid-container-color: purple;
+  $_row-color: orange;
+  $_template-column-color: green;
+  $_auto-column-color: blue;
+  $_placeholder-text-color: grey;
+  $_story-container-color: #25324d;
+
+  .container,
+  .container-fluid {
+    background-color: rgba($_container-color, 0.025);
+    box-shadow: 0 0 1px 1px $_container-color inset;
+
+    .row,
+    ul {
+      counter-reset: story-coloumn-counter;
+      background-color: rgba($_row-color, 0.2);
+      outline: 1px solid rgba($_row-color, 0.2);
+
+      // Column.
+      > .col,
+      > [class*='col-'],
+      > li {
+        counter-increment: story-coloumn-counter;
+        position: relative;
+
+        &::after {
+          content: counter(story-coloumn-counter) ' of ' attr(data-story-total-columns);
+          position: absolute;
+          bottom: 2px;
+          right: 0;
+          left: 0;
+          text-align: center;
+          font-size: 0.6em;
+        }
+
+        .row,
+        ul {
+          counter-reset: story-column-nested-counter;
+
+          > .col,
+          > [class*='col-'],
+          > li {
+            counter-increment: story-column-nested-counter;
+
+            &::after {
+              content: 'Nested ' counter(story-column-nested-counter) ' of ' attr(data-story-total-columns);
+              left: auto;
+              font-size: 0.4em;
+            }
+          }
+        }
+
+        @mixin _ct-story-placeholder-meta($width) {
+          position: relative;
+
+          &::before {
+            content: ct-string($width);
+            color: $_placeholder-text-color;
+            position: absolute;
+            top: 2px;
+            left: 0;
+            right: 0;
+            text-align: center;
+            font-size: 0.6em;
+            font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
+            white-space: nowrap;
+          }
+        }
+
+        // Column content.
+        .story-placeholder {
+          @include _ct-story-placeholder-meta('100%');
+        }
+
+        .story-placeholder--hugged {
+          @include _ct-story-placeholder-meta('auto');
+        }
+
+        .story-placeholder--fixed {
+          $_width: math.div(ct-breakpoint-next($ct-grid-lowest-breakpoint), 2);
+
+          @include _ct-story-placeholder-meta($_width);
+        }
+      }
+
+      // Column colors.
+      > [class*='col-'] {
+        background-color: rgba($_template-column-color, 0.1);
+        outline: 1px solid rgba($_template-column-color, 0.5);
+
+        &::after {
+          color: $_template-column-color;
+        }
+      }
+
+      > .col,
+      > li {
+        background-color: rgba($_auto-column-color, 0.1);
+        outline: 1px solid rgba($_auto-column-color, 0.5);
+
+        &::after {
+          color: $_auto-column-color;
+        }
+      }
+    }
+  }
+
+  .container-fluid {
+    background-color: rgba($_fluid-container-color, 0.025);
+    box-shadow: 0 0 1px 1px $_fluid-container-color inset;
+  }
+
+  &.grid-story-docs {
+    row-gap: 1em;
+
+    > * {
+      margin-right: 1em;
+      white-space: nowrap;
+    }
+
+    @mixin _ct-story-docs-color-square($color) {
+      &::before {
+        content: '';
+        display: inline-block;
+        height: 1em;
+        width: 1em;
+        background-color: $color;
+        margin-right: 0.5em;
+        vertical-align: top;
+      }
+    }
+
+    .grid-story-docs-color-container-contained {
+      @include _ct-story-docs-color-square($_container-color);
+    }
+
+    .grid-story-docs-color-container-fluid {
+      @include _ct-story-docs-color-square($_fluid-container-color);
+    }
+
+    .grid-story-docs-color-row {
+      @include _ct-story-docs-color-square($_row-color);
+    }
+
+    .grid-story-docs-color-template-column {
+      @include _ct-story-docs-color-square($_template-column-color);
+    }
+
+    .grid-story-docs-color-auto-column {
+      @include _ct-story-docs-color-square($_auto-column-color);
+    }
+
+    .grid-story-docs-color-placeholder {
+      @include _ct-story-docs-color-square($_placeholder-text-color);
+    }
+  }
+
+  .story-container__title,
+  .story-container__subtitle {
+    margin-top: 0;
+    margin-bottom: 0;
+    box-shadow: 0 0 1px 1px $_story-container-color inset;
+  }
+
+  .story-container__title {
+    padding-bottom: ct-spacing(2);
+    padding-top: ct-spacing(4);
+  }
+
+  .story-container__subtitle {
+    padding-top: ct-spacing(3);
+    padding-bottom: ct-spacing(2);
+  }
+}
+
+@include ct-story-docs-conditional('.story-grid-outlines');

package/components/00-base/grid/grid.test.js

@@ -0,0 +1,386 @@
+import DrupalAttribute from 'drupal-attribute';
+import jestEach from 'jest-each';
+
+const each = jestEach.default;
+
+const template = 'components/00-base/grid/grid.twig';
+
+const dataProviderGrid = () => [
+  {
+    items: ['1'],
+    use_container: true,
+    description: 'with container',
+  },
+  {
+    items: ['1'],
+    use_container: false,
+    description: 'without container',
+  },
+  {
+    items: ['1', '2'],
+    use_container: true,
+    description: 'multiple items with container',
+  },
+  {
+    items: ['1', '2'],
+    use_container: true,
+    is_fluid: true,
+    description: 'multiple items with fluid container',
+  },
+  {
+    items: ['1', '2'],
+    use_container: false,
+    description: 'multiple items without container',
+  },
+  {
+    items: ['1', '2', '3'],
+    use_container: true,
+    template_column_count: 3,
+    description: 'column count with container',
+  },
+  {
+    items: ['1', '2', '3'],
+    use_container: true,
+    template_column_count: 3,
+    is_fluid: true,
+    description: 'column count with fluid container',
+  },
+  {
+    items: ['1', '2', '3'],
+    use_container: false,
+    template_column_count: 3,
+    description: 'column count without container',
+  },
+  {
+    items: ['1', '2'],
+    use_container: true,
+    row_element: 'section',
+    column_element: 'span',
+    description: 'custom elements with container',
+  },
+  {
+    items: ['1', '2'],
+    use_container: false,
+    row_element: 'section',
+    column_element: 'span',
+    description: 'custom elements without container',
+  },
+  {
+    items: ['1'],
+    use_container: true,
+    row_class: 'custom-row',
+    column_class: 'custom-col',
+    description: 'custom classes with container',
+  },
+  {
+    items: ['1'],
+    use_container: false,
+    row_class: 'custom-row',
+    column_class: 'custom-col',
+    description: 'custom classes without container',
+  },
+  {
+    items: ['1', '2'],
+    use_container: true,
+    fill_width: true,
+    description: 'fill width with container',
+  },
+  {
+    items: ['1', '2'],
+    use_container: false,
+    fill_width: true,
+    description: 'fill width without container',
+  },
+  {
+    items: ['1'],
+    use_container: true,
+    attributes: new DrupalAttribute().setAttribute('data-test', 'true'),
+    modifier_class: 'custom-modifier',
+    description: 'attributes and modifier class with container',
+  },
+  {
+    items: ['1'],
+    use_container: false,
+    attributes: new DrupalAttribute().setAttribute('data-test', 'true'),
+    modifier_class: 'custom-modifier',
+    description: 'attributes and modifier class without container',
+  },
+];
+
+describe('Grid', () => {
+  each(dataProviderGrid()).test('renders correctly %s', async (props) => {
+    await dom(template, props);
+  });
+});
+
+describe('Grid Container', () => {
+  each([
+    { use_container: true, is_fluid: false },
+    { use_container: true, is_fluid: true },
+    { use_container: false, is_fluid: false },
+    { use_container: false, is_fluid: true },
+  ]).test('renders %s', async (props) => {
+    const c = await dom(template, { items: ['1'], ...props });
+
+    if (props.use_container) {
+      if (props.is_fluid) {
+        expect(c.querySelectorAll('.container')).toHaveLength(0);
+        expect(c.querySelectorAll('.container-fluid')).toHaveLength(1);
+      } else {
+        expect(c.querySelectorAll('.container')).toHaveLength(1);
+        expect(c.querySelectorAll('.container-fluid')).toHaveLength(0);
+      }
+    } else {
+      expect(c.querySelectorAll('.container')).toHaveLength(0);
+      expect(c.querySelectorAll('.container-fluid')).toHaveLength(0);
+    }
+  });
+});
+
+describe('Grid Row Fill Width', () => {
+  each([
+    { fill_width: true },
+    { fill_width: false },
+  ]).test('renders %s', async (props) => {
+    const c = await dom(template, {
+      items: ['1'],
+      use_container: true,
+      ...props,
+    });
+
+    if (props.fill_width) {
+      expect(c.innerHTML).toContain('row--fill-width');
+    }
+  });
+});
+
+describe('Grid Attributes and Modifier Class', () => {
+  each([
+    {
+      attributes: new DrupalAttribute().setAttribute('data-test', 'true'),
+      modifier_class: 'custom-modifier',
+      use_container: true,
+    },
+    {
+      attributes: new DrupalAttribute().setAttribute('data-test', 'true'),
+      modifier_class: 'custom-modifier',
+      use_container: false,
+    },
+  ]).test('renders %s', async (props) => {
+    const c = await dom(template, {
+      items: ['1'],
+      ...props,
+    });
+
+    if (props.use_container) {
+      expect(c.querySelectorAll('.container.custom-modifier')).toHaveLength(1);
+      expect(c.querySelectorAll('.container[data-test="true"]')).toHaveLength(1);
+    } else {
+      expect(c.querySelectorAll('.container')).toHaveLength(0);
+      expect(c.querySelectorAll('.row.custom-modifier')).toHaveLength(1);
+      expect(c.querySelectorAll('.row[data-test="true"]')).toHaveLength(1);
+    }
+  });
+});
+
+describe('Grid Custom Elements', () => {
+  each([
+    {
+      row_element: 'section',
+      column_element: 'span',
+    },
+    {
+      row_element: 'div',
+      column_element: 'div',
+    },
+  ]).test('renders %s', async (props) => {
+    const c = await dom(template, {
+      items: ['1'],
+      use_container: true,
+      ...props,
+    });
+
+    const rowElement = props.row_element || 'div';
+    const columnElement = props.column_element || 'div';
+    expect(c.querySelector(rowElement)).toBeTruthy();
+    expect(c.querySelector(columnElement)).toBeTruthy();
+  });
+});
+
+describe('Grid Custom Classes', () => {
+  each([
+    {
+      template_column_count: null,
+      row_class: null,
+      column_class: null,
+      fill_width: false,
+      expectedRowClass: 'row',
+      expectedColumnClass: 'col',
+    },
+    {
+      template_column_count: null,
+      row_class: null,
+      column_class: null,
+      fill_width: true,
+      expectedRowClass: 'row row--fill-width',
+      expectedColumnClass: 'col',
+    },
+    {
+      template_column_count: 0,
+      row_class: null,
+      column_class: null,
+      fill_width: false,
+      expectedRowClass: 'row',
+      expectedColumnClass: 'col',
+    },
+    {
+      template_column_count: 0,
+      row_class: null,
+      column_class: null,
+      fill_width: true,
+      expectedRowClass: 'row row--fill-width',
+      expectedColumnClass: 'col',
+    },
+    {
+      template_column_count: 0,
+      row_class: 'custom-row',
+      column_class: 'custom-col',
+      fill_width: false,
+      expectedRowClass: 'row custom-row',
+      expectedColumnClass: 'col custom-col',
+    },
+    {
+      template_column_count: 0,
+      row_class: 'custom-row',
+      column_class: 'custom-col',
+      fill_width: true,
+      expectedRowClass: 'row row--fill-width custom-row',
+      expectedColumnClass: 'col custom-col',
+    },
+    {
+      template_column_count: 12,
+      row_class: null,
+      column_class: null,
+      fill_width: false,
+      expectedRowClass: 'row',
+      expectedColumnClass: 'col-xxs-12 col-m-1',
+    },
+    {
+      template_column_count: 12,
+      row_class: null,
+      column_class: null,
+      fill_width: true,
+      expectedRowClass: 'row row--fill-width',
+      expectedColumnClass: 'col-xxs-12 col-m-1',
+    },
+    {
+      template_column_count: 12,
+      row_class: 'custom-row',
+      column_class: null,
+      fill_width: false,
+      expectedRowClass: 'row custom-row',
+      expectedColumnClass: 'col-xxs-12 col-m-1',
+    },
+    {
+      template_column_count: 12,
+      row_class: 'custom-row',
+      column_class: null,
+      fill_width: true,
+      expectedRowClass: 'row row--fill-width custom-row',
+      expectedColumnClass: 'col-xxs-12 col-m-1',
+    },
+    {
+      template_column_count: 12,
+      row_class: 'custom-row',
+      column_class: 'custom-col',
+      fill_width: false,
+      expectedRowClass: 'row custom-row',
+      expectedColumnClass: 'col-xxs-12 col-m-1 custom-col',
+    },
+    {
+      template_column_count: 12,
+      row_class: 'custom-row',
+      column_class: 'custom-col',
+      fill_width: true,
+      expectedRowClass: 'row row--fill-width custom-row',
+      expectedColumnClass: 'col-xxs-12 col-m-1 custom-col',
+    },
+  ]).test('renders %s', async (props) => {
+    const c = await dom(template, {
+      items: ['1'],
+      use_container: true,
+      ...props,
+    });
+
+    expect(c.querySelector('div:nth-child(1)>div:nth-child(1)').outerHTML)
+      .toContain(`class="${props.expectedRowClass}"`);
+    expect(c.querySelector('div:nth-child(1)>div:nth-child(1)>div:nth-child(1)').outerHTML)
+      .toContain(`class="${props.expectedColumnClass}"`);
+  });
+});
+
+describe('Grid Template Columns (no auto breakpoint)', () => {
+  each([
+    { template_column_count: 12 },
+    { template_column_count: 6 },
+    { template_column_count: 4 },
+    { template_column_count: 3 },
+    { template_column_count: 2 },
+    { template_column_count: 1 },
+  ]).test('renders %s', async (props) => {
+    const c = await dom(template, {
+      items: ['1'],
+      column_element: 'div',
+      auto_breakpoint: false,
+      ...props,
+    });
+
+    const el = c.querySelector('.row > div');
+    if (props.template_column_count === 12) {
+      expect(el.classList.toString()).toEqual('col-xxs-12 col-m-1');
+    } else if (props.template_column_count === 6) {
+      expect(el.classList.toString()).toEqual('col-xxs-12 col-m-2');
+    } else if (props.template_column_count === 4) {
+      expect(el.classList.toString()).toEqual('col-xxs-12 col-m-3');
+    } else if (props.template_column_count === 3) {
+      expect(el.classList.toString()).toEqual('col-xxs-12 col-m-4');
+    } else if (props.template_column_count === 2) {
+      expect(el.classList.toString()).toEqual('col-xxs-12 col-m-6');
+    } else if (props.template_column_count === 1) {
+      expect(el.classList.toString()).toEqual('col-xxs-12 col-m-12');
+    }
+  });
+});
+
+describe('Grid Template Columns with Auto Breakpoint', () => {
+  each([
+    { template_column_count: 12 },
+    { template_column_count: 6 },
+    { template_column_count: 4 },
+    { template_column_count: 3 },
+    { template_column_count: 2 },
+    { template_column_count: 1 },
+  ]).test('renders %s', async (props) => {
+    const c = await dom(template, {
+      items: ['1'],
+      column_element: 'div',
+      auto_breakpoint: true,
+      ...props,
+    });
+
+    const el = c.querySelector('.row > div');
+    if (props.template_column_count === 12) {
+      expect(el.classList.toString()).toEqual('col-xxs-12 col-m-1');
+    } else if (props.template_column_count === 6) {
+      expect(el.classList.toString()).toEqual('col-xxs-12 col-m-6 col-xl-4 col-xxl-2');
+    } else if (props.template_column_count === 4) {
+      expect(el.classList.toString()).toEqual('col-xxs-12 col-m-6 col-xl-4 col-xxl-3');
+    } else if (props.template_column_count === 3) {
+      expect(el.classList.toString()).toEqual('col-xxs-12 col-m-6 col-xl-4');
+    } else if (props.template_column_count === 2) {
+      expect(el.classList.toString()).toEqual('col-xxs-12 col-m-6');
+    } else if (props.template_column_count === 1) {
+      expect(el.classList.toString()).toEqual('col-xxs-12');
+    }
+  });
+});

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

@@ -0,0 +1,96 @@
+{#
+/**
+ * @file
+ * CivicTheme Grid component.
+ *
+ * Props:
+ * - items: [array] Column items.
+ *   Each item contains:
+ *   - items [string,object]
+ * - row_element: [string] Row element.
+ * - row_class: [string] Optional row class override (defaults to 'row').
+ * - row_attributes: [Drupal\Core\Template\Attribute] Additional row attributes.
+ * - column_element: [string] Column element.
+ * - column_class: [string] Optional column class override (defaults to 'col' if template_column_count is 0).
+ * - column_attributes: [Drupal\Core\Template\Attribute] Additional column attributes.
+ * - use_container: [boolean] Whether to use container or not.
+ * - is_fluid: [boolean] Whether the grid is fluid or not (applies only if use_container is true).
+ * - template_column_count: [number] Row columns count (0 for auto columns). If 0 - the auto columns will be used where column width will be calculated automatically.
+ * - auto_breakpoint: [boolean] Switch between columns (starting at template_column_count) as the screen reduces.
+ * - fill_width: [boolean] Stretch "hanging" items to row full width.
+ * - modifier_class: [string] Additional CSS classes.
+ * - attributes: [Drupal\Core\Template\Attribute] Additional HTML attributes.
+ */
+#}
+
+{% set use_container = use_container is defined ? use_container : true %}
+{% set is_fluid = is_fluid is defined ? is_fluid : false %}
+{% set fill_width = fill_width is defined ? fill_width : false %}
+{% set row_element = row_element|default('div') %}
+{% set column_element = column_element|default('div') %}
+{% set template_column_count = template_column_count|default(0) %}
+{% set row_class = row_class|default('') %}
+{% set modifier_class = modifier_class|default('') %}
+
+{% if template_column_count > 0 %}
+  {% set column_class = column_class|default('') %}
+  {% set template_column_count = template_column_count in [1, 2, 3, 4, 6, 12] ? template_column_count : 12 %}
+  {% if auto_breakpoint and template_column_count <= 6 %}
+    {% set breakpoints = {1: 'xxs', 2: 'm', 3: 'xl', 4: 'xxl', 6: 'xxl'} %}
+    {% set column_class = [] %}
+    {% for i in range(1, template_column_count) %}
+      {% if i != 5 and not (template_column_count == 6 and i == 4) %}
+        {% set bp = breakpoints[i] %}
+        {% if bp %}
+          {% set col = 12 // i %}
+          {% set column_class = column_class|merge(['col-%s-%s'|format(bp, col)]) %}
+        {% endif %}
+      {% endif %}
+    {% endfor %}
+    {% set column_class = column_class|join(' ') %}
+  {% else %}
+    {% set column_class = 'col-xxs-12 col-m-%s %s'|format(12 // template_column_count, column_class)|trim %}
+  {% endif %}
+{% else %}
+  {% set template_column_count = items|length %}
+  {% set column_class = ('col ' ~ column_class|default(''))|trim %}
+{% endif %}
+
+{% set row_classes = ['row'] %}
+{% if fill_width %}
+  {% set row_classes = row_classes|merge(['row--fill-width']) %}
+{% endif %}
+{% set row_classes = row_classes|merge([row_class]) %}
+
+{% set container_class = '' %}
+{% if use_container %}
+  {% set container_class = ((is_fluid ? 'container-fluid' : 'container') ~ ' ' ~ modifier_class)|trim %}
+{% else %}
+  {# Propagate modifier class to row class if container is not used. #}
+  {% if modifier_class is not empty %}
+    {% set row_classes = row_classes|merge([modifier_class]) %}
+  {% endif %}
+  {% set attributes = attributes is defined and attributes is not null ? attributes : create_attribute({}) %}
+  {% set row_attributes = row_attributes is defined and row_attributes is not null ? row_attributes : create_attribute({}) %}
+  {% set row_attributes = row_attributes.merge(attributes) %}
+{% endif %}
+
+{% set row_class_string = row_classes|join(' ')|trim %}
+
+{% if items is not empty %}
+  {% if use_container %}
+  <div class="{{ container_class }}" {% if attributes is defined and attributes is not null %}{{- attributes -}}{% endif %} aria-live="polite">
+  {% endif %}
+    <{{ row_element }} class="{{ row_class_string }}" {% if row_attributes is defined and row_attributes is not null %}{{ row_attributes }}{% endif %}>
+      {% for item in items %}
+        {% if item is not empty %}
+          <{{ column_element }} class="{{ column_class }}" {% if column_attributes is defined and column_attributes is not null %}{{ column_attributes }}{% endif %}>
+            {{ item }}
+          </{{ column_element }}>
+        {% endif %}
+      {% endfor %}
+    </{{ row_element }}>
+  {% if use_container %}
+  </div>
+  {% endif %}
+{% endif %}