fix(core): render semantic headings for application and content headers

.changeset/semantic-header-headings.md

@@ -0,0 +1,5 @@
+---
+'@siemens/ix': patch
+---
+
+Render `ix-application-header` and `ix-content-header` titles as semantic headings to improve document structure and accessibility.

packages/core/src/components/application-header/application-header.scss

@@ -8,6 +8,7 @@
  */
 @use 'mixins/shadow-dom/component';
 @use 'mixins/break-points';
+@use 'mixins/fonts';
 
 :host {
   display: flex;
@@ -102,6 +103,10 @@
     }
 
     .application-name {
+      @include fonts.typography-body-lg;
+
+      margin: 0;
+      padding: 0;
       flex: 0 1 auto;
       min-width: 0;
       flex-shrink: 0;

packages/core/src/components/application-header/application-header.tsx

@@ -406,9 +406,7 @@ export class ApplicationHeader {
             ></slot>
           </div>
           <div class="name">
-            <ix-typography format="body-lg" class="application-name">
-              {this.name}
-            </ix-typography>
+            {this.name && <h1 class="application-name">{this.name}</h1>}
             {this.nameSuffix && this.breakpoint !== 'sm' && (
               <ix-typography format="body-xs" class="application-name-suffix">
                 {this.nameSuffix}

packages/core/src/components/application-header/test/application-header.ct.ts

@@ -11,6 +11,34 @@ import { test, viewPorts } from '@utils/test';
 import { ApplicationLayoutContext } from '../../utils/application-layout/context';
 import { ContextType } from '../../utils/context';
 
+test('accessibility', async ({ mount, makeAxeBuilder }) => {
+  await mount(
+    `<ix-application-header name="Test Application"></ix-application-header>`
+  );
+
+  const results = await makeAxeBuilder().analyze();
+  expect(results.violations).toEqual([]);
+});
+
+test('renders application name as h1', async ({ mount, page }) => {
+  await mount(
+    `<ix-application-header name="Test Application"></ix-application-header>`
+  );
+
+  const heading = page.getByRole('heading', {
+    level: 1,
+    name: 'Test Application',
+  });
+  await expect(heading).toBeVisible();
+});
+
+test('does not render h1 when name is omitted', async ({ mount, page }) => {
+  await mount(`<ix-application-header></ix-application-header>`);
+
+  const heading = page.locator('ix-application-header').locator('h1');
+  await expect(heading).toHaveCount(0);
+});
+
 test('renders', async ({ mount, page }) => {
   page.setViewportSize({
     height: 500,

packages/core/src/components/content-header/content-header.scss

@@ -7,6 +7,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+@use 'mixins/fonts';
+@use 'misc/common-variables' as vars;
+
 :host {
   display: flex;
   flex-direction: row;
@@ -26,6 +29,19 @@
       text-overflow: ellipsis;
     }
 
+    .header-title {
+      @include fonts.typography-h3;
+
+      margin: 0;
+      padding: 0;
+
+      &.secondary {
+        @include fonts.typography-h4;
+
+        padding: vars.$tiny-space 0;
+      }
+    }
+
     .headerTitleRow {
       display: flex;
 
@@ -34,10 +50,6 @@
         margin-left: 0.5rem;
       }
     }
-
-    .secondary {
-      padding: 0.25rem 0;
-    }
   }
 
   .subtitle {

packages/core/src/components/content-header/content-header.tsx

@@ -60,15 +60,17 @@ export class ContentHeader {
 
         <div class="titleGroup">
           <div class="headerTitleRow">
-            <ix-typography
-              format={this.variant === 'secondary' ? 'h4' : 'h3'}
-              class={{
-                secondary: this.variant === 'secondary',
-                titleOverflow: true,
-              }}
-            >
-              {this.headerTitle}
-            </ix-typography>
+            {this.headerTitle && (
+              <h2
+                class={{
+                  'header-title': true,
+                  secondary: this.variant === 'secondary',
+                  titleOverflow: true,
+                }}
+              >
+                {this.headerTitle}
+              </h2>
+            )}
             <div class="headerSlot">
               <slot name="header" />
             </div>

packages/core/src/components/content-header/test/content-header.ct.ts

@@ -0,0 +1,74 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Siemens AG
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { expect } from '@playwright/test';
+import { regressionTest } from '@utils/test';
+
+regressionTest('accessibility', async ({ mount, makeAxeBuilder }) => {
+  await mount(
+    `<ix-content-header header-title="Content title"></ix-content-header>`
+  );
+
+  const results = await makeAxeBuilder().analyze();
+  expect(results.violations).toEqual([]);
+});
+
+regressionTest('renders', async ({ mount, page }) => {
+  await mount(
+    `<ix-content-header header-title="Content title"></ix-content-header>`
+  );
+
+  const element = page.locator('ix-content-header');
+  await expect(element).toHaveClass(/\bhydrated\b/);
+  await expect(element).toBeVisible();
+});
+
+const variants = [
+  { variant: '', expected: 'primary', hasSecondaryClass: false },
+  {
+    variant: 'variant="secondary"',
+    expected: 'secondary',
+    hasSecondaryClass: true,
+  },
+];
+
+for (const { variant, expected, hasSecondaryClass } of variants) {
+  regressionTest(
+    `renders header title as h2 for ${expected} variant`,
+    async ({ mount, page }) => {
+      await mount(
+        `<ix-content-header ${variant} header-title="My Content Page"></ix-content-header>`
+      );
+
+      const heading = page.getByRole('heading', {
+        level: 2,
+        name: 'My Content Page',
+      });
+      await expect(heading).toBeVisible();
+
+      const titleElement = page
+        .locator('ix-content-header')
+        .locator('h2.header-title');
+      if (hasSecondaryClass) {
+        await expect(titleElement).toHaveClass(/\bsecondary\b/);
+      } else {
+        await expect(titleElement).not.toHaveClass(/\bsecondary\b/);
+      }
+    }
+  );
+}
+
+regressionTest(
+  'does not render h2 when headerTitle is omitted',
+  async ({ mount, page }) => {
+    await mount(`<ix-content-header></ix-content-header>`);
+
+    const heading = page.locator('ix-content-header').locator('h2');
+    await expect(heading).toHaveCount(0);
+  }
+);