feat(Logo section): Support block level usage

releases.yml

@@ -1,3 +1,13 @@
+- version: 4.40.0
+  features:
+    - component: Logo section
+      url: /docs/patterns/logo-section
+      status: Updated
+      notes: Added <code>scope</code> parameter. Updated <code>padding</code> and <code>top_rule_variant</code> parameters.
+    - component: Logo block
+      url: /docs/patterns/logo-block
+      status: Deprecated
+      notes: Logo block is now deprecated in favor of the [block level Logo section](/docs/patterns/logo-section#logo-section-at-a-block-level)
 - version: 4.39.0
   features:
     - component: CTA section

templates/_macros/vf_logo-section.jinja

@@ -29,20 +29,25 @@
   - title (object) (required): A dictionary with the title configuration.
     - text (string) (required): The text to be displayed as the title.
     - link_attrs (object) (optional): A dictionary of link attributes for the title.
-  - padding (string) (optional): Type of padding to apply. Options are "deep", "default". Default is "default".
+  - padding (string) (optional): Type of padding to apply. Options are "deep", "default", "none". Default is "default".
   - blocks (array<object>) (required): List of blocks to be displayed in the section. Supported block types include:
     - cta-block: Configuration for a call-to-action block.
     - logo-block: Configuration for a logo block. Must include:
       - item.logos (array): A list of logos to display.
-
+  - top_rule_variant (string) (optional): The variant of the top rule to apply. Options are "default", "none". Default is "default".
+  - scope (string) (optional): Which root element the macro renders. Allowed values: "section" or "block". 
+      "section" (default): renders a <section> as the root element (suitable when used standalone).
+      "block": renders a <div> as the root element (suitable when used inside another section).
+      If an unknown value is provided, default behavior is "section".
+
   Slots
   - description (optional): Paragraph-style content displayed below the title. Can include one or more paragraphs.
 #}
-{%- macro vf_logo_section(title, padding="regular", blocks=[], caller=None) -%}
+{%- macro vf_logo_section(title, padding="default", blocks=[], top_rule_variant="default", scope="section", caller=None) -%}
   {% set description_content = caller('description') %}
   {% set has_description = description_content|trim|length > 0 %}
   {%- set padding = padding | trim -%}
-  {%- if padding not in ["deep", "default"] -%}
+  {%- if padding not in ["deep", "default", "none"] -%}
     {%- set padding = "default" -%}
   {%- endif -%}
   {%- if padding == "default" -%}  
@@ -52,6 +57,14 @@
   {%- endif -%}
   {%- set cta_block = blocks | selectattr("type", "equalto", "cta-block") | first -%}
   {%- set logo_block = blocks | selectattr("type", "equalto", "logo-block") | first -%}
+  {%- set top_rule_variant = top_rule_variant | trim -%}
+  {%- if top_rule_variant not in ["default", "none"] -%}
+    {%- set top_rule_variant = "default" -%}
+  {%- endif -%}
+  {%- set scope = scope | trim -%}
+  {%- if scope not in ["section", "block"] -%}
+    {%- set scope = "section" -%}
+  {%- endif -%}
   {%- macro _title_block(title={}) -%}
     <h2 class="p-text--small-caps">
       {%- if "link_attrs" in title and "href" in title.get("link_attrs", {}) -%}
@@ -68,15 +81,22 @@
   {%- macro _description_block() -%}
     {% if has_description %}{{ description_content | safe }}{% endif %}
   {%- endmacro -%}
-  <section class="{{ padding_classes }}">
-    <hr class="p-rule is-fixed-width" />
+
+  {%- set rootElement = "div" if scope == "block" else "section" -%}
+
+  <{{ rootElement }}{%- if padding != 'none' %} class="{{ padding_classes }}"{% endif %}>
+    {%- if top_rule_variant == "default" -%}
+      <hr class="p-rule is-fixed-width" />
+    {%- endif -%}
+    {%- if title.get('text') or description_content | trim | length > 0 -%}
     <div class="grid-row--50-50">
       <div class="grid-col">{{- _title_block(title) -}}</div>
       <div class="grid-col">
         {{- _description_block() -}}
         {% if cta_block %}{{- basic_section_item(cta_block) -}}{% endif %}
       </div>
     </div>
+    {%- endif -%}
     {{- _logo_block(logo_block) -}}
-  </section>
+  </{{ rootElement }}>
 {%- endmacro -%}

templates/docs/examples/patterns/logo-section/block-scoped.html

@@ -0,0 +1,85 @@
+{% extends "_layouts/examples.html" %}
+{% from "_macros/vf_logo-section.jinja" import vf_logo_section %}
+{% from "_macros/vf_tiered-list.jinja" import vf_tiered_list %}
+{% block title %}Logo section / Default{% endblock %}
+{% block standalone_css %}patterns_all{% endblock %}
+{% set is_paper = true %}
+{% block content %}
+  {%- call(slot) vf_tiered_list(is_description_full_width_on_desktop=false, is_list_full_width_on_tablet=true) -%}
+    {%- if slot == 'title' -%}
+      <h2>H2 - up to two lines; ideally one.</h2>
+    {%- endif -%}
+
+    {%- if slot == 'description' -%}
+      <p>A <a href="#">private cloud</a> provides organisations with on-demand
+        compute, storage and other resources that can be accessed over the network
+        and that are reserved exclusively for them - either in their own data centre
+        or via a 3rd party.
+      </p>
+    {%- endif -%}
+
+    {%- if slot == 'list_item_title_1' -%}
+      <h3 class="p-heading--5">Rich portfolio of products</h3>
+    {%- endif -%}
+
+    {%- if slot == 'list_item_description_1' -%}
+      <p>Resell the full range of Canonical’s portfolio of private and public
+        cloud products: OpenStack, Kubernetes, IoT, support, security and
+        compliance for Ubuntu.
+      </p>
+
+    {% call(slot) vf_logo_section(
+        title={"text": ""},
+        top_rule_variant="none",
+        padding="none",
+        scope="block",
+        blocks=[
+        {
+          "type": "logo-block",
+          "item": {
+          "logos": [
+            {
+              "src": "https://assets.ubuntu.com/v1/38fdfd23-Dell-logo.png",
+              "alt": "Dell Technologies"
+            },
+            {
+              "src": "https://assets.ubuntu.com/v1/cd5f636a-hp-logo.png",
+              "alt": "Hewlett Packard"
+            },
+            {
+              "src": "https://assets.ubuntu.com/v1/f90702cd-lenovo-logo.png",
+              "alt": "Lenovo"
+            },
+            {
+              "src": "https://assets.ubuntu.com/v1/2ef3c028-amazon-web-services-logo.png",
+              "alt": "Amazon Web Services"
+            },
+            {
+              "src": "https://assets.ubuntu.com/v1/cb7ef8ac-ibm-cloud-logo.png",
+              "alt": "IBM Cloud"
+            },
+            {
+              "src": "https://assets.ubuntu.com/v1/210f44e4-microsoft-azure-new-logo.png",
+              "alt": "Microsoft Azure"
+            },
+            {
+              "src": "https://assets.ubuntu.com/v1/a554a818-google-cloud-logo.png",
+              "alt": "Google Cloud Platform"
+            },
+            {
+              "src": "https://assets.ubuntu.com/v1/b3e692f4-oracle-new-logo.png",
+              "alt": "Oracle"
+            }
+          ]
+        }
+      }
+    ]
+    ) -%}
+    {% endcall -%}
+
+      <div class="p-cta-block">
+        <a href="#">Learn more &rsaquo;</a>
+      </div>
+    {%- endif -%}
+  {% endcall -%}
+{% endblock %}

templates/docs/examples/patterns/logo-section/combined.html

@@ -21,5 +21,8 @@
     <section>
       {% include 'docs/examples/patterns/logo-section/padding-variants.html' %}
     </section>
+    <section>
+      {% include 'docs/examples/patterns/logo-section/block-scoped.html' %}
+    </section>
   {% endwith %}
 {% endblock %}

templates/docs/patterns/logo-block/index.md

@@ -7,8 +7,8 @@ context:
 {% from "docs/macros/notice.jinja" import documentation_notice %}
 
 {{- documentation_notice(
-    icon_class="p-notification--information",
-    message_text="Please use this component if you would like to simply display logos within another section, as it should be treated as a building block that can be inserted into other patterns, without needing to include a title. If you would instead like to use a designated logo section with an accompanying heading and optional description, please use the <a href='/docs/patterns/logo-section'>Logo section</a> pattern."
+    icon_class="p-notification--negative",
+    message_text="Logo block is now deprecated in favor of the new <a href='/docs/patterns/logo-section'>Logo section</a> pattern."
 ) }}
 
 The logo block can be used to showcase a group of related images, such as a group of customer or partner logos.

templates/docs/patterns/logo-section/index.md

@@ -9,11 +9,6 @@ context:
 
 {{- pattern_wip_notice() }}
 
-{{- documentation_notice(
-    icon_class="p-notification--information",
-    message_text="Please use this pattern if you would like to use a designated logo section with an accompanying heading and optional description. If you would instead like to simply display logos within another section, please use the <a href='/docs/patterns/logo-block'>Logo block component</a>, which should be treated as a building block that can be inserted into other patterns without needing to include a title."
-) }}
-
 The logo section is a pattern where the logo block serves as the main content, combined with a muted heading, optional description, and a CTA block.
 
 It is composed of the following elements:
@@ -151,6 +146,14 @@ View example of the logo section pattern without CTA block
 View example of the logo section pattern without description and CTA block
 </a></div>
 
+#### Logo section at a block level
+
+Logo section can also be used as a block within other patterns, such as [Tiered list](/docs/patterns/tiered-list)
+
+<div class="embedded-example"><a href="/docs/examples/patterns/logo-section/block-scoped" class="js-example" data-lang="jinja">
+View example of the block scoped logo section
+</a></div>
+
 ## Jinja Macro
 
 The `vf_logo_section` Jinja macro can be used to generate a logo section pattern. The API for the macro is shown
@@ -247,7 +250,8 @@ below.
         <td>
           One of:<br>
           <code>'deep'</code>,<br>
-          <code>'default'</code>
+          <code>'default'</code>,<br>
+          <code>'none'</code>
         </td>
         <td>
           <code>'default'</code>
@@ -256,6 +260,44 @@ below.
           Padding variant for the entire section
         </td>
       </tr>
+      <tr>
+        <td>
+          <code>top_rule_variant</code>
+        </td>
+        <td>
+          No
+        </td>
+        <td>
+          One of:<br>
+          <code>'default'</code>,<br>
+          <code>'none'</code>
+        </td>
+        <td>
+          <code>'default'</code>
+        </td>
+        <td>
+          Variant of <a href="/docs/patterns/rule">horizontal rule</a> to display at the top of the section."
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <code>scope</code>
+        </td>
+        <td>
+          No
+        </td>
+        <td>
+          One of:<br>
+          <code>'section'</code>,<br>
+          <code>'block'</code>
+        </td>
+        <td>
+          <code>'section'</code>
+        </td>
+        <td>
+          Which root element the macro renders. Renders <code>&lt;section&gt;</code> or <code>&lt;div&gt;</code> depending on the value.
+        </td>
+      </tr>
     </tbody>
   </table>
 </div>