vanilla-framework 4.34.2 → 4.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanilla-framework",
-  "version": "4.34.2",
+  "version": "4.36.0",
   "author": {
     "email": "webteam@canonical.com",
     "name": "Canonical Webteam"
@@ -27,6 +27,9 @@
     ".": {
       "sass": "./_index.scss"
     },
+    "./scss/*": {
+      "sass": "./scss/*"
+    },
     "./js": "./templates/static/js/index.js",
     "./js/*": "./templates/static/js/*.js"
   },
@@ -67,7 +70,7 @@
   ],
   "devDependencies": {
     "@canonical/cookie-policy": "3.6.5",
-    "@canonical/latest-news": "1.6.0",
+    "@canonical/latest-news": "2.1.0",
     "@percy/cli": "1.30.7",
     "@testing-library/cypress": "10.0.3",
     "autoprefixer": "10.4.20",

package/scss/_patterns_article-block.scss

@@ -0,0 +1,120 @@
+/*
+  @classreference
+    Article block:
+      .p-article-block:
+        Container for blog article content
+      .p-article-block__item:
+        Individual content block within article block
+      .p-article-block__image:
+        An image within an article block
+      .p-article-block__title:
+        The title of the article block
+      .p-article-block__metadata:
+        Metadata container
+      .p-article-block__metadata-item:
+        Individual metadata item with middot separator between items
+*/
+
+@use 'sass:math';
+
+@mixin vf-p-article-block {
+  // same as paragraph bottom margin.
+  // To simplify the logic of adding bottom margin to items only if they have content, we will use row-gap instead of margin-bottom.
+  $article-block-row-gap: map-get($settings-text-p, sp-after) - map-get($settings-text-p, nudge);
+
+  .p-article-block {
+    display: grid;
+    // image, title, desc/excerpt, metadata
+    grid-row: span 4;
+    grid-template-rows: subgrid;
+    margin-bottom: #{$spv--small + $article-block-row-gap};
+    row-gap: $article-block-row-gap;
+
+    // the section that wraps the items already has bottom padding defined, so the last row of items must have collapsed bottom margin to avoid duplicating spacing.
+    // small screens - the last item gets collapsed bottom margin
+    @media screen and (width < $threshold-4-small-4-med-col) {
+      &:last-child {
+        margin-bottom: 0;
+      }
+    }
+
+    // medium screens - the last two items get collapsed bottom margin
+    @media screen and ($threshold-4-small-4-med-col <= width < $threshold-4-8-col) {
+      &:nth-last-child(-n + 2) {
+        margin-bottom: 0;
+      }
+    }
+
+    // large screen - all items get collapsed bottom margin
+    @media screen and (width >= $threshold-4-8-col) {
+      margin-bottom: 0;
+    }
+  }
+
+  /*
+  Article block items and their descendants by default don't get any margin or padding.
+  Article block items are always rendered (we need to keep subgrid alignment, and we don't know at request time whether the content is going to be there or not due to dynamic content).
+  So, we by default remove all margin and padding. Then, further style rules can query for presence of content and add appropriate margins and padding.
+   */
+  .p-article-block__item {
+    display: contents;
+
+    &:not(:last-child) {
+      // empty items pull their following contents up by canceling the row-gap.
+      margin-bottom: -#{$article-block-row-gap};
+    }
+
+    // Only apply article block spacing styles to contentful items
+    &:has(.p-article-block__title:not(:empty)),
+    &:has(.p-article-block__description:not(:empty)),
+    &:has(.article-author:not(:empty)),
+    &:has(.article-time:not(:empty)) {
+      display: grid;
+      font-size: #{map-get($settings-text-p, font-size)}rem;
+      line-height: map-get($settings-text-p, line-height);
+      // cancel out the row-gap cancellation if the item has contents.
+      margin-bottom: 0;
+      padding-top: map-get($settings-text-p, nudge);
+    }
+
+    // Apply all spacing at the item level.
+    & * {
+      margin-bottom: 0;
+      margin-top: 0;
+      padding-bottom: 0;
+      padding-top: 0;
+    }
+  }
+
+  .p-article-block__title {
+    font-size: #{map-get($settings-text-p, font-size)}rem;
+    line-height: map-get($settings-text-p, line-height);
+  }
+
+  /**
+    Article block images are an exception to the above - they get small bottom margin, not paragraph styling.
+   */
+  .p-article-block__item:has(.p-article-block__image) {
+    display: grid;
+    // we want $spv--small below the images - but we are also using `row-gap`. We can create this effective spacing by subtracting the desired bottom margin from the row gap.
+    margin-bottom: -#{$article-block-row-gap - $spv--small};
+  }
+
+  /*
+    Add a middot between non-empty metadata items
+    The metadata-items are wrappers around child elements that are **always** rendered, so that dynamic content has slots to populate items into.
+    We don't know at build time if there will be any content.
+    So, we use :has() to target `p-article-block__metadata-item` elements that have at least one non-empty child element, without having to target any specific child selectors here.
+    Note that this requires careful management of whitespace within the metadata items. Extra whitespace can cause elements with no children to be considered non-empty and unnecessarily render a middot.
+   */
+  .p-article-block__metadata-item:has(> *:not(:empty)) {
+    @include vf-inline-list-item;
+
+    margin-right: $sph--x-small;
+
+    & ~ &::before {
+      content: '\2022';
+      position: relative;
+    }
+  }
+}

package/scss/_patterns_blog.scss

@@ -0,0 +1,15 @@
+/*
+  @classreference
+  blog:
+    Blog:
+      .p-blog:
+        Main element of the blog pattern.
+      .p-blog__articles:
+        Container for blog articles.
+*/
+
+@mixin vf-p-blog {
+  .p-blog__articles {
+    display: contents;
+  }
+}

package/scss/_patterns_resources-block.scss

@@ -0,0 +1,21 @@
+@import 'settings';
+
+$col-25: calc($grid-8-columns / 4);
+$col-50: calc($grid-8-columns / 2);
+
+@mixin vf-p-resources-block {
+  .p-resources-block {
+    > .p-resources-block__col {
+      @media (min-width: $threshold-4-8-col) {
+        &:nth-of-type(1) {
+          @include vf-grid-8-column($col-25);
+        }
+
+        &:nth-of-type(2) {
+          grid-column-start: calc($col-25 + 1);
+          @include vf-grid-8-column($col-50);
+        }
+      }
+    }
+  }
+}

package/scss/_vanilla.scss

@@ -3,8 +3,10 @@
 // Patterns
 
 @import 'patterns_accordion';
+@import 'patterns_article-block';
 @import 'patterns_article-pagination';
 @import 'patterns_badge';
+@import 'patterns_blog';
 @import 'patterns_breadcrumbs';
 @import 'patterns_buttons';
 @import 'patterns_card';
@@ -43,6 +45,7 @@
 @import 'patterns_pricing-block';
 @import 'patterns_newsletter-signup';
 @import 'patterns_pull-quotes';
+@import 'patterns_resources-block';
 @import 'patterns_rule';
 @import 'patterns_search-and-filter';
 @import 'patterns_search-box';
@@ -102,8 +105,10 @@
   @include vf-base;
   // Patterns
   @include vf-p-accordion;
+  @include vf-p-article-block;
   @include vf-p-article-pagination;
   @include vf-p-badge;
+  @include vf-p-blog;
   @include vf-p-breadcrumbs;
   @include vf-p-buttons;
   @include vf-p-card;
@@ -143,6 +148,7 @@
   @include vf-p-pagination;
   @include vf-p-pricing-block;
   @include vf-p-pull-quotes;
+  @include vf-p-resources-block;
   @include vf-p-rule;
   @include vf-p-search-and-filter;
   @include vf-p-search-box;

package/templates/_macros/shared/vf_article_block.jinja

@@ -0,0 +1,187 @@
+{#
+  Helper macro to render the article title with optional link and attributes.
+
+  Parameters:
+    title (object): Title configuration
+      text (string): The title text
+      link_attrs (object) (optional): Link attributes. If passed, wraps the title in a link.
+      attrs (object) (optional): Additional HTML attributes
+      heading_level (integer) (optional): Heading level to use, defaults to 3. Can be 3 or 4.
+    template_mode (boolean) (optional): Whether this is being rendered in template mode
+#}
+{%- macro _article_title(title={}, template_mode=False) -%}
+  {%- set link_attrs = title.get("link_attrs", {}) -%}
+  {%- set heading_level = title.get("heading_level", 3) -%}
+  {%- if heading_level not in [3, 4] -%}
+    {%- set heading_level = 3 -%}
+  {%- endif -%}
+  {#- Assume blog module always sets a link in template mode. -#}
+  {%- set is_link = link_attrs.items() | length > 0 or template_mode -%}
+  {%- if is_link -%}
+    <a
+      class="article-link{%- if link_attrs.get("class") %} {{ link_attrs.get("class", "") }}{%- endif -%}"
+      {% for attr, value in link_attrs.items() %}
+        {% if attr != "class" %}
+          {{ attr }}="{{ value }}"
+        {% endif %}
+      {% endfor %}
+    >
+  {%- endif -%}
+  <h{{ heading_level }}
+    class="p-article-block__title article-title{%- if title.get("class") %} {{ title.get("class", "") }}{%- endif -%}"
+    {% for attr, value in title.items() %}
+      {% if attr not in ["text", "link_attrs", "class", "heading_level"] %}
+        {{ attr }}="{{ value }}"
+      {% endif %}
+    {% endfor %}>
+    {{- title.get("text", "") | trim -}}
+  </h{{ heading_level }}>
+  {%- if is_link -%}
+    </a>
+  {%- endif -%}
+{%- endmacro -%}
+
+{#
+  Helper macro to render the article description.
+
+  Parameters:
+    description (object): Description configuration
+      text (string): The description text
+      attrs (object) (optional): Additional HTML attributes
+#}
+{%- macro _article_description(description={}) -%}
+  {%- set description_attrs = description.get("attrs", {}) -%}
+  {%- set description_class = description_attrs.get("class", "") -%}
+  <p class="p-article-block__description article-excerpt{%- if description_class %} {{ description_class }}{%- endif -%}"
+    {% for attr, value in description_attrs.items() %}
+      {% if attr != "class" %}
+        {{ attr }}="{{ value }}"
+      {% endif %}
+    {% endfor %}
+  >
+    {{- description.get("text", "") | trim -}}
+  </p>
+{%- endmacro -%}
+
+{#
+  Helper macro to render the article metadata with authors and date.
+
+  Parameters:
+    authors (array): List of author objects
+      text (string): Author name
+      link_attrs (object) (optional): Link attributes for the author. If passed, wraps the author in a link.
+
+    date (object): Date configuration
+      text (string): The date text
+      attrs (object) (optional): Additional HTML attributes for the time element
+#}
+{%- macro _article_metadata(authors=[], date={}) -%}
+  {% set has_authors = authors | length > 0 %}
+  {% set has_date = date.get("text", "") | length > 0 %}
+  {%- set date_attrs = date.get("attrs", {}) -%}
+  {%- set date_text = date.get("text", "") | trim -%}
+
+  <div class="p-article-block__metadata">
+    <small class="p-article-block__metadata-item">
+      <span class="article-author">
+        {%- for author in authors -%}
+          {%- set author_text = author.get("text", "") | trim -%}
+          {%- set author_link_attrs = author.get("link_attrs", {}) -%}
+          {%- if author_link_attrs.items() | length > 0 -%}
+            <a
+              {% for attr, value in author_link_attrs.items() %}
+                {{ attr }}="{{ value }}"
+              {% endfor %}
+            >
+          {%- endif -%}
+          {{- author_text -}}
+          {%- if author_link_attrs -%}</a>{%- endif -%}
+          {%- if not loop.last -%}, {% endif -%}
+        {%- endfor -%}
+      </span>
+    </small>
+    <small class="p-article-block__metadata-item">
+      <time
+        datetime="{{ date_text }}"
+        class="article-time{%- if date_attrs.get("class") %} {{ date_attrs.get("class", "") }}{%- endif -%}"
+        {% for attr, value in date_attrs.items() %}
+          {% if attr not in ["datetime", "class"] %}
+            {{ attr }}="{{ value }}"
+          {% endif %}
+        {% endfor %}
+      >
+        {{- date_text -}}
+      </time>
+    </small>
+  </div>
+{%- endmacro -%}
+
+{#
+  Blog article block pattern - displays a single blog article with title, description and metadata.
+
+  Parameters:
+    article_config (object) (required): Article configuration
+      title (object) (required): Title configuration
+        text (string) (required): The title text
+        link_attrs (object) (optional): Link attributes for the title. If passed, wraps the title in a link.
+        attrs (object) (optional): Additional attributes for the title
+      description (object) (optional): Description configuration
+        text (string) (required): Description text
+        attrs (object) (optional): Additional attributes for description paragraph
+      metadata (object) (optional): Metadata configuration
+        authors (array) (optional): List of author objects
+          text (string) (required): Author name
+          link_attrs (object) (optional): Author link attributes. If passed, wraps the author in a link.
+        date (object) (optional): Date configuration
+          text (string) (required): Date text
+          attrs (object) (optional): Date element attributes
+      image_html (string) (optional): Image to render before the title.
+        When used with vf_blog macro, this is automatically populated with a 16:9 cover image
+        from the article's image configuration.
+
+    attrs (object) (optional): Additional attributes for the resource block
+    template_mode (boolean) (optional): Whether this is being rendered in template mode
+#}
+{%- macro vf_article_block(article_config={}, attrs={}, template_mode=False) -%}
+    {%- set title = article_config.get("title", {}) -%}
+    {%- set description = article_config.get("description", {}) -%}
+    {%- set _ = description.setdefault('attrs', {}) -%}
+    {%- set metadata = article_config.get("metadata", {}) -%}
+    {%- set image_html = article_config.get("image_html", "") | trim -%}
+    {%- set authors = metadata.get("authors", []) -%}
+    {%- set date = metadata.get("date", {}) -%}
+
+    <div class="p-article-block{%- if attrs.get("class") %} {{ attrs.get("class", "") }}{%- endif -%}"
+      {% for attr, value in attrs.items() %}
+        {% if attr != "class" %}
+          {{ attr }}="{{ value }}"
+        {% endif %}
+      {% endfor %}
+    >
+      {#-
+        Note: p-article-block relies on subgrid to align items vertically across the grid.
+        This means that we must always create 4 p-article-block__items, even if some are empty.
+        This allows the subgrid to maintain alignment, even when some blocks are missing some items.
+        Note that this means `p-article-block__item` elements should never define padding or margin, as this would cause empty items to take up space.
+      -#}
+      <div class="p-article-block__item">
+        {%- if image_html | length > 0 -%}
+          <div class="p-article-block__image">
+            {{ image_html | safe }}
+          </div>
+        {%- endif -%}
+      </div>
+
+      <div class="p-article-block__item">
+        {{ _article_title(title=title, template_mode=template_mode) }}
+      </div>
+
+      <div class="p-article-block__item">
+        {{ _article_description(description=description) }}
+      </div>
+
+      <div class="p-article-block__item">
+        {{ _article_metadata(authors=authors, date=date) }}
+      </div>
+    </div>
+{%- endmacro -%}

package/templates/_macros/shared/vf_section_top_rule.jinja

@@ -0,0 +1,29 @@
+# Helper macro to render a top rule for a section.
+# Parameters:
+#  - top_rule_variant: string, one of "default", "muted", "highlighted", "none"
+{%- macro vf_section_top_rule(top_rule_variant="default") -%}
+  {%- set top_rule_variant = top_rule_variant | trim | lower -%}
+  {%- if top_rule_variant not in ["default", "muted", "highlighted", "none"] -%}
+    {%- set top_rule_variant = "default" -%}
+  {%- endif -%}
+
+  {%- if top_rule_variant != "none" -%}
+    {%- set top_rule_classes = "p-rule" -%}
+    {%- if top_rule_variant != "default" -%}
+      {#-
+        p-rule--highlighted doesn't exist (use p-rule--highlight instead), but p-rule--muted does.
+        We keep the external API here consistent ("-ed" suffix) for simplicity but need to handle this internally.
+      -#}
+      {%- if top_rule_variant == "highlighted" -%}
+        {%- set top_rule_classes = "p-rule--highlight" -%}
+      {%- else -%}
+        {#- Other cases: just append the top_rule_variant to the p-rule class. -#}
+        {%- set top_rule_classes = top_rule_classes + "--" + top_rule_variant -%}
+      {%- endif -%}
+    {%- endif -%}
+  {%- endif -%}
+
+  {%- if top_rule_variant != "none" -%}
+    <hr class="{{- top_rule_classes -}}"/>
+  {%- endif -%}
+{%- endmacro -%}

package/templates/_macros/vf_basic-section.jinja

@@ -1,4 +1,5 @@
 {% from "_macros/shared/vf_dedent.jinja" import vf_dedent %}
+{% from "_macros/shared/vf_section_top_rule.jinja" import vf_section_top_rule %}
 {% from "_macros/vf_linked-logo-section.jinja" import vf_linked_logo_section %}
 
 # description_config
@@ -291,33 +292,6 @@
   </h2>
 {%- endmacro -%}
 
-{%- macro basic_section_top_rule(top_rule_variant="default") -%}
-  {%- set top_rule_variant = top_rule_variant | trim | lower -%}
-  {%- if top_rule_variant not in ["default", "muted", "highlighted", "none"] -%}
-    {%- set top_rule_variant = "default" -%}
-  {%- endif -%}
-
-  {%- if top_rule_variant != "none" -%}
-    {%- set top_rule_classes = "p-rule" -%}
-    {%- if top_rule_variant != "default" -%}
-      {#-
-        p-rule--highlighted doesn't exist (use p-rule--highlight instead), but p-rule--muted does.
-        We keep the external API here consistent ("-ed" suffix) for simplicity but need to handle this internally.
-      -#}
-      {%- if top_rule_variant == "highlighted" -%}
-        {%- set top_rule_classes = "p-rule--highlight" -%}
-      {%- else -%}
-        {#- Other cases: just append the top_rule_variant to the p-rule class. -#}
-        {%- set top_rule_classes = top_rule_classes + "--" + top_rule_variant -%}
-      {%- endif -%}
-    {%- endif -%}
-  {%- endif -%}
-
-  {%- if top_rule_variant != "none" -%}
-    <hr class="{{- top_rule_classes -}}"/>
-  {%- endif -%}
-{%- endmacro -%}
-
 # Params
 # title: A dictionary with "text" and optional "link_attrs" (a dictionary of link attributes for the title).
 # subtitle: A dictionary with "text" (required) and optional "heading_level" (default is 4).
@@ -358,7 +332,7 @@
 
 <section class="{{ padding_classes }}">
   <div class="grid-row--50-50{%- if not is_split_on_medium -%}-on-large{%- endif -%}">
-    {{ basic_section_top_rule(top_rule_variant) }}
+    {{ vf_section_top_rule(top_rule_variant) }}
     <div class="grid-col">
       {%- if has_label -%}
         <h3 class="p-muted-heading u-no-padding--top u-no-margin--bottom">{{- label_text -}}</h3>

package/templates/_macros/vf_blog.jinja

@@ -0,0 +1,133 @@
+{% from "_macros/shared/vf_section_top_rule.jinja" import vf_section_top_rule %}
+{% from "_macros/shared/vf_article_block.jinja" import vf_article_block %}
+
+# Params
+# - article_config: A dictionary with the article configuration.
+#   - "title": A dictionary with "text" and optional "link" (a dictionary of link attributes for the title).
+#   - "image": A dictionary with "attrs" dict containing "src", "alt", and other image attributes.
+#          The image is automatically wrapped in a 16:9 cover image container and passed to
+#          vf_article_block as before_title_html. A fallback image is used if no image
+#          is provided (can be overridden via fallback_image_url).
+#   - "description": A dictionary with "text" containing the article description.
+#   - "metadata": A dictionary with:
+#     - "authors": A list of author objects, each with "text" and optional "link" (a dictionary of link attributes)
+#     - "date": A dictionary with "text" and optional "attrs" (a dictionary of time element attributes)
+# - template_mode: Boolean indicating if the macro is being used in template mode (for dynamic loading scenarios).
+# - fallback_image_url: URL to use as a fallback image, if no image is provided for an article.
+{%- macro _blog_article(article_config={}, template_mode=False, fallback_image_url="https://assets.ubuntu.com/v1/94c82a15-blog_fallback_image.png") -%}
+  {%- set base_image_container_classes = "p-image-container--16-9 is-cover article-image" -%}
+  {%- if not template_mode -%}
+    {%- set default_image_attrs = {
+      'src': fallback_image_url,
+      'alt': 'Blog fallback image'
+      }
+    -%}
+    {%- set input_image_attrs = article_config.get('image', {}).get('attrs', {}) -%}
+    {#- Merge user attributes over the defaults -#}
+    {%- set img_attrs = default_image_attrs.copy() -%}
+    {%- set _ = img_attrs.update(input_image_attrs) -%}
+    {#- class merging -#}
+    {%- set base_image_class = 'p-image-container__image' -%}
+    {%- set input_image_class = input_image_attrs.get('class', '') -%}
+    {%- if input_image_class -%}
+      {%- set final_image_classes = base_image_class + ' ' + input_image_class -%}
+    {%- else -%}
+      {%- set final_image_classes = base_image_class -%}
+    {%- endif -%}
+    {%- set _ = img_attrs.update({'class': final_image_classes}) -%}
+    {#- Build the HTML tag -#}
+    {%- set ns = namespace(image_html="<img") -%}
+    {%- for attr, value in img_attrs.items() -%}
+      {%- set ns.image_html = ns.image_html + " " + attr + "=\"" + value + "\"" -%}
+    {%- endfor -%}
+    {%- set image_html = ns.image_html + ">" -%}
+    {%- set _ = article_config.update({'image_html': '<div class="' + base_image_container_classes + '">\n            ' + image_html + '\n          </div>'}) -%}
+  {%- else -%}
+    {#- template mode - the template JS will fill in the image slot. -#}
+    {%- set _ = article_config.update({'image_html': '<div class="' + base_image_container_classes + '"></div>'}) -%}
+  {%- endif -%}
+  {{ vf_article_block(article_config=article_config, attrs={"class": "grid-col-2 grid-col-medium-2"}, template_mode=template_mode) }}
+
+{%- endmacro -%}
+
+# Params
+# title: A dictionary with "text" and optional "link_attrs" (a dictionary of link attributes for the title).
+# articles: A list of article dictionaries, each with "title", "image", "description", and "metadata".
+# template_config:
+#   - enabled: A boolean to enable or disable the template mode.
+#   - template_container_id: A string for the id of the container to use for dynamic loading scenarios.
+#   - template_id: A string for the id of the template to use for dynamic loading scenarios.
+#   - layout: Layout to apply to the template. Options are "3-blocks" and "4-blocks".
+# padding: Type of padding to apply to the pattern - "deep", "shallow", "default" (default is "default").
+# top_rule_variant: Type of HR to render at the top of the pattern. "default" | "muted" (default is "default").
+# fallback_image_url: URL to use as a fallback image, if no image is provided for an article.
+{% macro vf_blog(
+    title={},
+    articles=[],
+    template_config={},
+    padding="default",
+    top_rule_variant="default",
+    fallback_image_url="https://assets.ubuntu.com/v1/94c82a15-blog_fallback_image.png"
+) -%}
+  {%- set padding = padding | trim -%}
+  {%- if padding not in ["deep", "shallow", "default"] -%}
+    {%- set padding = "default" -%}
+  {%- endif -%}
+
+  {%- set padding_classes = "p-section--" + padding -%}
+  {%- if padding == "default" -%}
+    {%- set padding_classes = "p-section" -%}
+  {%- endif -%}
+
+  {#- Infer layout from article count -#}
+  {%- if articles | length == 3 -%}
+    {%- set layout = "3-blocks" -%}
+  {%- elif articles | length == 4 -%}
+    {%- set layout = "4-blocks" -%}
+  {%- endif -%}
+
+  {%- set template_mode = template_config.get("enabled", False) -%}
+
+  {#- In template mode, read layout from the template config, instead of inferring it from the article count. -#}
+  {%- if template_mode -%}
+    {%- set layout = template_config.get("layout", "4-blocks") -%}
+  {%- endif -%}
+
+  {#- Default to "4-blocks" layout if an unrecognized layout is used. -#}
+  {%- if layout not in ["3-blocks", "4-blocks"] -%}
+    {%- set layout = "4-blocks" -%}
+  {%- endif -%}
+
+  <section class="{{ padding_classes }}">
+    <div class="p-blog grid-row">
+      {{- vf_section_top_rule(top_rule_variant) -}}
+      <div class="grid-col-{%- if layout == "3-blocks" -%}2{%- else -%}8{%- endif -%}">
+        <h2 class="p-muted-heading">
+          {%- if title.get("link_attrs") -%}
+            <a
+              {% for attr, value in title.get("link_attrs", {}).items() %}
+                {{ attr }}="{{ value }}"
+              {% endfor %}
+            >
+          {%- endif -%}
+          {{- title.get("text", "Blog Title") -}}
+          {%- if title.get("link_attrs") -%}
+            </a>
+          {%- endif -%}
+        </h2>
+      </div>
+      {%- if template_mode -%}
+        <div id="{{ template_config.get("template_container_id", "articles") }}" class="p-blog__articles"></div>
+        <template style="display: none;" id="{{ template_config.get("template_id", "template") }}">
+          {{ _blog_article(template_mode=True) }}
+        </template>
+      {%- else -%}
+        <div class="p-blog__articles grid-row">
+          {%- for article in articles -%}
+            {{ _blog_article(article_config=article, fallback_image_url=fallback_image_url) }}
+          {%- endfor -%}
+        </div>
+      {%- endif -%}
+    </div>
+  </section>
+{%- endmacro -%}

package/templates/_macros/vf_divided-section.jinja

@@ -3,7 +3,9 @@
 # - padding: Type of padding to apply to the pattern - "deep", "shallow", "default" (default is "default").
 # - is_split_on_medium: Boolean to indicate if the section should be split on medium screens (default is false).
 # - top_rule_variant: Type of HR to render at the top of the pattern. "default" | "muted" (default is "default").
-{% from "_macros/vf_basic-section.jinja" import basic_section_item, basic_section_title, basic_section_top_rule %}
+{% from "_macros/vf_basic-section.jinja" import basic_section_item, basic_section_title %}
+{% from "_macros/shared/vf_section_top_rule.jinja" import vf_section_top_rule %}
+
 {% macro _get_item_padding_classes(item_config={}, isLastLoopItr=False, isLastBlockItr=False) %}
   {%- set item_padding = (item_config.get("padding", "")) | trim -%}
   {%- if item_padding not in ["shallow"] -%}
@@ -32,7 +34,7 @@
     <div class="grid-row--50-50{%- if not is_split_on_medium -%}-on-large{%- endif -%}">
       {%- set description_block = blocks | selectattr("type", "equalto", "description-block") | first -%}
       {%- set divided_blocks = blocks | selectattr("type", "equalto", "divided-block") | list -%}
-      {{ basic_section_top_rule(top_rule_variant) }}
+      {{ vf_section_top_rule(top_rule_variant) }}
       <div class="grid-col">{{- basic_section_title(title) -}}</div>
       <div class="grid-col">
         {%- if description_block -%}

package/templates/_macros/vf_equal-heights.jinja

@@ -4,9 +4,9 @@
   - subtitle_text (string) (optional): The text to be displayed as the subtitle
   - subtitle_heading_level (int) (optional): The heading level for the subtitle. Can be 4 or 5. Defaults to 5.
   - highlight_images (boolean) (optional): If the images need to be highlighted, which means adding a subtle grey background. Not added by default.
-  - image_aspect_ratio_small (string) (optional): The aspect ratio for item images on small screens. Defaults to "square". Can be "square", "2-3", "3-2", "16-9", "cinematic". Defaults to "square".
-  - image_aspect_ratio_medium (string) (optional): The aspect ratio for item images on medium screens. Defaults to "square". Can be "square", "2-3", "3-2", "16-9", "cinematic". Defaults to "square".
-  - image_aspect_ratio_large (string) (optional): The aspect ratio for item images on large screens. Defaults to "2-3". Can be "square", "2-3", "3-2", "16-9", "cinematic". Defaults to "2-3".
+  - image_aspect_ratio_small (string) (optional): The aspect ratio for item images on small screens. Defaults to "square". Can be "square", "2-3", "3-2", "16-9", "cinematic" or "auto". Defaults to "square".
+  - image_aspect_ratio_medium (string) (optional): The aspect ratio for item images on medium screens. Defaults to "square". Can be "square", "2-3", "3-2", "16-9", "cinematic" or "auto". Defaults to "square".
+  - image_aspect_ratio_large (string) (optional): The aspect ratio for item images on large screens. Defaults to "2-3". Can be "square", "2-3", "3-2", "16-9", "cinematic" or "auto". Defaults to "2-3".
   - items (array) (required): An array of items, each including 'image_html', 'title_text', 'description_html', and 'cta_html'.
  -#}
 {%- macro vf_equal_heights(
@@ -69,7 +69,7 @@
               {#- Image item (required) -#}
               <div class="p-equal-height-row__item">
                 <div
-                  class="p-image-container--{{ image_aspect_ratio_small }}-on-small p-image-container--{{ image_aspect_ratio_medium }}-on-medium p-image-container--{{ image_aspect_ratio_large }}-on-large is-cover{% if highlight_images %} is-highlighted{% endif %}" >
+                  class="p-image-container {% if image_aspect_ratio_small != 'auto' %} p-image-container--{{ image_aspect_ratio_small }}-on-small{% endif %}{% if image_aspect_ratio_medium != 'auto' %} p-image-container--{{ image_aspect_ratio_medium }}-on-medium{% endif %}{% if image_aspect_ratio_large != 'auto' %} p-image-container--{{ image_aspect_ratio_large }}-on-large{% endif %} is-cover{% if highlight_images %} is-highlighted{% endif %}" >
                   {#- The consumer must pass in an img.p-image-container__image for the image to be properly formatted -#}
                   {{- image | safe -}}
                 </div>

package/templates/_macros/vf_hero.jinja

@@ -10,11 +10,13 @@
 # cta: call-to-action block below the description
 # image: slot for image content
 # signpost_image: slot for signpost (left column) image content in 25/75 layout. Required for 25/75 layout.
+# display_blank_signpost_image_space: whether to indent the content for 25/75 layout on large screens.
 {% macro vf_hero(
   title_text,
   subtitle_text='',
   layout="fallback",
-  is_split_on_medium=false
+  is_split_on_medium=false,
+  display_blank_signpost_image_space=false
 ) -%}
   {% set has_subtitle = subtitle_text|trim|length > 0 %}
   {% set description_content = caller('description') %}
@@ -24,7 +26,7 @@
   {% set image_content = caller('image') %}
   {% set has_image = image_content|trim|length > 0 %}
   {% set signpost_image_content = caller('signpost_image') %}
-  {% set has_signpost_image = signpost_image_content|trim|length > 0 %}
+  {% set has_signpost_image = signpost_image_content|trim|length > 0 or display_blank_signpost_image_space %}
 
   {#- User can pass layout as "X-Y" or "X/Y" -#}
   {% set layout = layout | trim | replace('/', '-') %}

package/templates/_macros/vf_resources.jinja

@@ -0,0 +1,364 @@
+{#
+  VF Resources Pattern Macros
+  
+  This file contains macros for rendering resources sections with various layouts
+  including text-only, image-based, and categorized displays.
+#}
+{% from "_macros/vf_basic-section.jinja" import basic_section_item, basic_section_title %}
+{% from "_macros/shared/vf_article_block.jinja" import vf_article_block %}
+{% from "_macros/shared/vf_section_top_rule.jinja" import vf_section_top_rule %}
+{#
+  Renders the pattern's title block
+  
+  @param {object} title - Title configuration object
+    {
+      "text": "Title text",
+      "link_attrs": {
+        "href": "#"
+      } // Optional: link attributes to make title clickable
+    }
+#}
+{% macro _title_block(title={}) %}
+  {%- if title -%}
+    {{- basic_section_title(title) -}}
+  {%- endif -%}
+{% endmacro %}
+{#
+  Renders the pattern's description block
+  
+  @param {object} description - Description configuration object
+    {
+      "type": "description",
+      "item": {
+        "type": "text|html",
+        "content": "Description content",
+      }
+    }
+#}
+{% macro _description_block(description={}) %}
+  {%- if description -%}
+    {{- basic_section_item(description) -}}
+  {%- endif -%}
+{% endmacro %}
+{#
+  Renders the pattern's CTA block
+  
+  @param {object} cta - CTA configuration object
+    {
+      "type": "cta-block",
+      "item": {
+        "primary": {
+          "content_html": "Primary Action",
+          "attrs": {
+            "href": "#"
+          }
+        },
+        "secondaries": [
+          {
+            "content_html": "Secondary Action",
+            "attrs": {
+              "href": "#"
+            }
+          }
+        ],
+        "link": {
+          "content_html": "Lorem ipsum dolor sit amet ›",
+          "attrs": {
+            "href": "#"
+          }
+        }
+      }
+    }
+#}
+{% macro _cta_block(cta={}) %}
+  {%- if cta -%}
+    {{- basic_section_item(cta) -}}
+  {%- endif -%}
+{% endmacro %}
+{#
+  Renders an image based on its type configuration
+  
+  @param {object} image_config - Image configuration object
+    {
+      "type": "default" | "logo", // default applies 16-9 ratio container
+      "attrs": {
+        "src": "image url",
+        "alt": "Image description",
+        "width": "100",
+        "height": "100"
+      }
+    }
+#}
+{% macro _render_image(image_config={}) %}
+  {%- if image_config -%}
+    {%- set image_type = image_config.get("type", "default") -%}
+    {%- if image_type not in ["default", "logo"] -%}
+      {%- set image_type = "default" -%}
+    {%- endif -%}
+    {%- set attrs = image_config.get("attrs", {}) -%}
+    {%- if image_type == "default" -%}
+      <div class="p-image-container--16-9 is-cover">
+        <img class="p-image-container__image {{ attrs.get('class', '') }}" alt="{{ attrs.get('alt', '') }}" {%- if attrs.get('src') %} src="{{ attrs.get('src') }}"{% endif -%} {%- if attrs.get('width') %} width="{{ attrs.get('width') }}"{% endif -%} {%- if attrs.get('height') %} height="{{ attrs.get('height') }}"{% endif -%} {%- for attr, value in attrs.items() -%} {%- if attr not in ["class", "alt", "src", "width", "height"] %} {{ attr }}="{{ value }}"{% endif -%} {%- endfor -%} />
+      </div>
+    {%- elif image_type == "logo" -%}
+      <img class="{{ attrs.get('class', '') }}" alt="{{ attrs.get('alt', '') }}" {%- if attrs.get('src') %} src="{{ attrs.get('src') }}"{% endif -%} {%- if attrs.get('width') %} width="{{ attrs.get('width') }}"{% endif -%} {%- if attrs.get('height') %} height="{{ attrs.get('height') }}"{% endif -%} {%- for attr, value in attrs.items() -%} {%- if attr not in ["class", "alt", "src", "width", "height"] %} {{ attr }}="{{ value }}"{% endif -%} {%- endfor -%} />
+    {%- endif -%}
+  {%- endif -%}
+{% endmacro %}
+{#
+  Renders a category title with proper spacing and styling
+  
+  @param {object} category - Category configuration object
+    {
+      "text": "Title text",
+      "link_attrs": {
+        "href": "#"
+      } // Optional: link attributes to make title clickable
+    }
+  @param {boolean} is_first_category - Whether this is the first category in the list
+  @param {boolean} is_first_item - Whether this is the first item in the category
+#}
+{% macro _render_category_title(category={}, is_first_category=True, is_first_item=True) %}
+  {%- if category.title -%}
+    <div class="grid-col">
+      {% if is_first_item %}<h3 class="p-text--small-caps">{{ category.title }}</h3>{% endif %}
+    </div>
+  {%- endif -%}
+{% endmacro %}
+{#
+  Renders a resource item for text-only layout
+  
+  @param {object} item - Resource item configuration
+    {
+      "title": {
+        "text": "Resource Title",
+        "link_attrs": {
+          "href": "/resource-path"
+        }
+      },
+      "description": {
+        "text": "Resource description",
+      },
+      "metadata": {
+        "authors": [
+          {
+            "text": "Resource author",
+            "link": {
+              "href": "#"
+            }
+          }
+        ],
+        "date": {
+          "text": "20th April 2024",
+          "link": {
+            "href": "#"
+          }
+        }
+      },
+      "image": {
+        "type": "default" | "logo", // default applies 16-9 ratio container
+        "attrs": {
+          "src": "Image url",
+          "alt": "Image description",
+          "width": "Image width",
+          "height": "Image height"
+        }
+      }
+    }
+  @param {boolean} is_last_item - Whether this is the last item
+  @param {boolean} is_last_category - Whether this is the last category
+#}
+{% macro _render_text_only_item(item={}, is_last_item=False, is_last_category=False) %}
+  {%- set item_title = item.get("title", {}) -%}
+  {%- set item_description = item.get("description", {}) -%}
+  {%- set item_metadata = item.get("metadata", {}) -%}
+  <div class="{% if not (is_last_category and is_last_item) and item_description %}p-section--shallow{% endif %}">
+    {{- vf_article_block({"title": item_title, "description": item_description, "metadata": item_metadata}) -}}
+  </div>
+{% endmacro %}
+{#
+  Renders a resource item for full layout (with images and/or categories)
+  
+  @param {object} item - Resource item configuration (same structure as _render_text_only_item)
+  @param {object} category - Category configuration
+  @param {boolean} render_images - Whether to render images
+  @param {boolean} render_categories - Whether to render category titles
+  @param {boolean} is_first_category - Whether this is the first category
+  @param {boolean} is_first_item - Whether this is the first item in category
+  @param {boolean} is_last_item - Whether this is the last item in category
+#}
+{% macro _render_full_layout_item(item={}, category={}, render_images=False, render_categories=True, is_first_category=True, is_first_item=True, is_last_item=False) %}
+  {%- set item_title = item.get("title", {}) -%}
+  {%- set item_description = item.get("description", {}) -%}
+  {%- set item_metadata = item.get("metadata", {}) -%}
+  {%- set image_config = item.get("image", {}) -%}
+  <div class="grid-row--25-75-on-large{% if not is_last_item %} p-section--shallow{% endif %}">
+    {%- if render_categories and render_images -%}
+      {% if not is_first_category and is_first_item %}<hr class="p-rule--muted" />{% endif %}
+      {{- _render_category_title(category, is_first_category, is_first_item) -}}
+    {%- endif -%}
+    <div class="grid-col">
+      {%- if render_categories and not render_images -%}
+        {% if not is_first_category and is_first_item %}<hr class="p-rule--muted" />{% endif %}
+      {%- endif %}
+      <div class="p-resources-block grid-row{% if render_images or render_categories %} grid-row--50-50-on-medium{% endif %}">
+        <div class="grid-col p-resources-block__col">
+          {%- if render_images -%}
+            {{- _render_image(image_config) -}}
+          {%- elif render_categories -%}
+            {{- _render_category_title(category, is_first_category, is_first_item) -}}
+          {%- endif -%}
+        </div>
+        <div class="grid-col p-resources-block__col">
+          {%- if render_categories -%}
+            {%- set x=item_title.__setitem__("heading_level",  4) -%}
+            {%- set x=item_title.__setitem__("class",  "p-heading--3") -%}
+          {%- endif -%}
+          {{- vf_article_block({"title": item_title, "description": item_description, "metadata": item_metadata}) -}}
+        </div>
+      </div>
+    </div>
+  </div>
+{% endmacro %}
+{#
+  Main VF Resources macro for rendering resource sections
+  
+  @param {object} title - Section title configuration
+    {
+      "text": "Section Title",
+      "link_attrs": {
+        "href": "#"
+      }
+    }
+  @param {array} blocks - Array of content blocks
+    [
+      {
+        "type": "description",
+        "item": {
+          "type": "text|html",
+          "content": "Description content",
+        }
+      },
+      {
+        "type": "cta-block",
+        "item": {
+          "primary": {
+            "content_html": "Primary Action",
+            "attrs": {
+              "href": "#"
+            }
+          },
+          "secondaries": [
+            {
+              "content_html": "Secondary Action",
+              "attrs": {
+                "href": "#"
+              }
+            }
+          ],
+          "link": {
+            "content_html": "Lorem ipsum dolor sit amet ›",
+            "attrs": {
+              "href": "#"
+            }
+          }
+        }
+      },
+      {
+        "type": "resources",
+        "render_images": true|false,
+        "render_categories": true|false,
+        "categories": [
+          {
+            "title": {
+              "text": "Category Name",
+              "link_attrs": {
+                "href": "#"
+              }
+            },
+            "items": [
+              {
+                "title": {
+                  "text": "Resource Title",
+                  "link_attrs": {
+                    "href": "/resource-path"
+                  }
+                },
+                "description": {
+                  "text": "Resource description",
+                },
+                "metadata": {
+                  "authors": [
+                    {
+                      "text": "Resource author",
+                      "link": {
+                        "href": "#"
+                      }
+                    }
+                  ],
+                  "date": {
+                    "text": "20th April 2024",
+                    "link": {
+                      "href": "#"
+                    }
+                  }
+                },
+                "image": {
+                  "type": "default" | "logo", // default applies 16-9 ratio container
+                  "attrs": {
+                    "src": "Image url",
+                    "alt": "Image description",
+                    "width": "Image width",
+                    "height": "Image height"
+                  }
+                }
+              }
+            ]
+          }
+        ]
+      }
+    ]
+#}
+{% macro vf_resources(title={}, blocks=[], caller=None) %}
+  {%- set description = blocks | selectattr("type", "equalto", "description") | first -%}
+  {%- set cta = blocks | selectattr("type", "equalto", "cta-block") | first -%}
+  {%- set resources = blocks | selectattr("type", "equalto", "resources") | first -%}
+  {%- set render_images = resources.get("render_images", true) -%}
+  {%- set render_categories = resources.get("render_categories", true) -%}
+  {%- set is_text_only = not (render_images or render_categories) -%}
+  <section class="p-section">
+    <div class="grid-row--50-50{% if is_text_only %}-on-large{% endif %}{% if not is_text_only %} p-section--shallow{% endif %}">
+      {{- vf_section_top_rule("default") -}}
+      <div class="grid-col">{{- _title_block(title) -}}</div>
+      <div class="grid-col">
+        {{- _description_block(description) -}}
+        {{- _cta_block(cta) -}}
+        {%- if is_text_only -%}
+          {%- for category in resources.get("categories", []) -%}
+            {%- set category_last = loop.last -%}
+            {%- for item in category.get("items", []) -%}
+              {{- _render_text_only_item(item, loop.last, category_last) -}}
+            {%- endfor -%}
+          {%- endfor -%}
+        {%- endif -%}
+      </div>
+    </div>
+    {%- if not is_text_only -%}
+      {%- for category in resources.get("categories", []) -%}
+        {%- set first_category = loop.first -%}
+        {%- set last_category = loop.last -%}
+        <div {% if not last_category %}class="p-section--shallow"{% endif %}>
+          {%- for item in category.get("items", []) -%}
+            {{- _render_full_layout_item(item,
+                        category,
+                        render_images,
+                        render_categories,
+                        first_category,
+                        loop.first,
+                        loop.last) -}}
+          {%- endfor -%}
+        </div>
+      {%- endfor -%}
+    {%- endif -%}
+  </section>
+{% endmacro %}