Merge pull request #5744 from canonical/WD-33048

feat(Logo section): Support block level usage

Author: muhammad-ali-pk

releases.yml

@@ -1,3 +1,13 @@
+- version: 4.40.0
+  features:
+    - component: Logo section
+      url: /docs/patterns/logo-section
+      status: Updated
+      notes: Added a new <code>mode</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 <a href="/docs/patterns/logo-section#full-vs-minimal-mode">Logo section</a> pattern.
 - version: 4.39.0
   features:
     - component: CTA section

templates/_macros/vf_logo-section.jinja

@@ -29,20 +29,24 @@
   - 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".
+  - mode (string) (optional): The layout mode. Allowed values: "default" or "minimal".
+      "default": renders a <section> as the root element, and includes title, description and cta (suitable when used standalone).
+      "minimal": renders a <div> as the root element, and does not render title, description and cta (suitable when used inside another 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", mode="default", 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 +56,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 mode = mode | trim -%}
+  {%- if mode not in ["default", "minimal"] -%}
+    {%- set mode = "default" -%}
+  {%- 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 +80,27 @@
   {%- macro _description_block() -%}
     {% if has_description %}{{ description_content | safe }}{% endif %}
   {%- endmacro -%}
-  <section class="{{ padding_classes }}">
-    <hr class="p-rule is-fixed-width" />
-    <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 %}
+
+  {%- set rootElement = "div" if mode == "minimal" else "section" -%}
+
+  <{{ rootElement }}{%- if padding != 'none' %} class="{{ padding_classes }}"{% endif %}>    
+    {%- if mode == "default" -%}
+      {%- if top_rule_variant == "default" -%}
+        <hr class="p-rule is-fixed-width" />
+      {%- endif -%}
+      <div class="grid-row--50-50">
+        {%- if title and title.get('text') -%}
+          <div class="grid-col">{{- _title_block(title) -}}</div>
+        {%- endif -%}
+        {%- if has_description or cta_block -%}
+          <div class="grid-col">
+            {{- _description_block() -}}
+            {% if cta_block %}{{- basic_section_item(cta_block) -}}{% endif %}
+          </div>
+        {%- endif -%}
       </div>
-    </div>
+    {%- endif -%}
+
     {{- _logo_block(logo_block) -}}
-  </section>
+  </{{ rootElement }}>
 {%- endmacro -%}

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/minimal.html' %}
+    </section>
   {% endwith %}
 {% endblock %}

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

@@ -5,6 +5,7 @@
 {% set is_paper = true %}
 {% block content %}
 {% call(slot) vf_logo_section(
+  mode="default",
   title={
     "text": "The quick brown fox jumps over the lazy dog"
   },

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

@@ -0,0 +1,52 @@
+{% extends "_layouts/examples.html" %}
+{% from "_macros/vf_logo-section.jinja" import vf_logo_section %}
+{% block title %}Logo section / Minimal mode{% endblock %}
+{% block standalone_css %}patterns_all{% endblock %}
+{% set is_paper = true %}
+{% block content %}
+  {% call(slot) vf_logo_section(
+        mode="minimal",
+        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 -%}
+{% 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,56 @@ View example of the logo section pattern without CTA block
 View example of the logo section pattern without description and CTA block
 </a></div>
 
+#### Default vs Minimal mode
+
+Use the <code>mode</code> parameter to control how much content the pattern renders. Two modes are supported: "default" and "minimal".
+
+- default
+
+  - Renders the title with a top rule, description, CTA, and logo block.
+  - Renders the root element as a <code>&lt;section&gt;</code>
+
+- minimal
+  - Renders a compact layout that displays only the logo block.
+  - Title, description slot and CTA are not rendered (useful inside other patterns or tight page areas).
+  - Renders the root element as a <code>&lt;div&gt;</code>
+
+Usage
+
+- Add the mode property at the pattern level when invoking the macro.
+
+##### Example: default
+
+```json
+{
+  "title": {"text": "Trusted by organizations worldwide"},
+  "mode": "default",
+  "description": "<p>We power the digital services of many public sector organizations.</p>",
+  "blocks": [
+    {"type": "logo-block", "item": {"logos": [{"attrs": {"src": "logo.png", "alt": "Org"}}]}},
+    {"type": "cta-block", "item": {"link": {"content_html": "Learn more", "attrs": {"href": "/about"}}}}
+  ]
+}
+```
+
+<div class="embedded-example"><a href="/docs/examples/patterns/logo-section/default" class="js-example" data-lang="jinja">
+View example of the "default" mode Logo section
+</a></div>
+
+##### Example: minimal
+
+```json
+{
+  "title": {"text": "Trusted by organizations worldwide"},
+  "mode": "minimal",
+  "blocks": [{"type": "logo-block", "item": {"logos": [{"attrs": {"src": "logo.png", "alt": "Org"}}]}}]
+}
+```
+
+<div class="embedded-example"><a href="/docs/examples/patterns/logo-section/minimal" class="js-example" data-lang="jinja">
+View example of the "minimal" mode 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 +292,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 +302,48 @@ 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>mode</code>
+        </td>
+        <td>
+          No
+        </td>
+        <td>
+          One of:<br>
+          <code>'default'</code>,<br>
+          <code>'minimal'</code>
+        </td>
+        <td>
+          <code>'default'</code>
+        </td>
+        <td>
+          Layout for the pattern.
+          <ul>
+            <li>"default": renders a &lt;section&gt; as the root element, and renders title, description and cta (suitable when used standalone).</li>
+            <li>"minimal": renders a &lt;div&gt; as the root element, and does not render title, description and cta (suitable when used inside another section).</li>
+          </ul>
+        </td>
+      </tr>
     </tbody>
   </table>
 </div>