uui-box: add a property to control the headline variant

.gitignore

@@ -1,6 +1,5 @@
 ## editors
 /.idea
-/.vscode
 
 ## system files
 .DS_Store

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "cSpell.words": ["combobox", "Umbraco"]
+}

packages/uui-base/lib/types/InterfaceHeading.ts

@@ -0,0 +1,10 @@
+export const InterfaceHeadingValues: Readonly<InterfaceHeading[]> = [
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+] as const;
+
+export type InterfaceHeading = '' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';

packages/uui-base/lib/types/index.ts

@@ -1,2 +1,3 @@
 export * from './InterfaceLook';
 export * from './InterfaceColor';
+export * from './InterfaceHeading';

packages/uui-box/README.md

@@ -31,3 +31,9 @@ import { UUIBoxElement } from '@umbraco-ui/uui-box';
 ```html
 <uui-box headline="Headline"> Content </uui-box>
 ```
+
+To specify a headline variant, eg. `h2` then use the `headline-variant` attribute:
+
+```html
+<uui-box headline="Headline" headline-variant="h2"> Content </uui-box>
+```

packages/uui-box/lib/uui-box.element.ts

@@ -1,7 +1,9 @@
-import { LitElement, html, css } from 'lit';
+import { LitElement, css } from 'lit';
 import { defineElement } from '@umbraco-ui/uui-base/lib/registration';
 import { property, state } from 'lit/decorators.js';
 import { UUITextStyles } from '@umbraco-ui/uui-css/lib';
+import type { InterfaceHeading } from '@umbraco-ui/uui-base/lib';
+import { StaticValue, html, literal, unsafeStatic } from 'lit/static-html.js';
 
 /**
  *  A box for grouping elements
@@ -46,6 +48,25 @@ export class UUIBoxElement extends LitElement {
   @property({ type: String })
   headline: string | null = null;
 
+  /**
+   * Changes the headline variant for accessibility for this box.
+   * Notice this does not change the visual representation of the headline. (Umbraco does only recommend displaying a h5 sizes headline in the UUI-BOX)
+   * @type {"h1" | "h2" | "h3" | "h4" | "h5" | "h6"}
+   * @attr
+   * @default "h5"
+   */
+  @property({ attribute: 'headline-variant' })
+  set headlineVariant(value: InterfaceHeading) {
+    if (!value) {
+      this._headlineVariantTag = literal`h5`;
+    } else {
+      this._headlineVariantTag = unsafeStatic(value);
+    }
+  }
+
+  @state()
+  private _headlineVariantTag: StaticValue = literal`h5`;
+
   @state()
   private _headlineSlotHasContent = false;
   private _headlineSlotChanged = (e: Event) => {
@@ -67,24 +88,31 @@ export class UUIBoxElement extends LitElement {
    * @method
    */
   protected renderHeader() {
+    /* eslint-disable lit/no-invalid-html, lit/binding-positions */
     return html`<div
       id="header"
       class="uui-text"
-      style=${this._headerSlotHasContent ||
-      this._headlineSlotHasContent ||
-      this.headline !== null
-        ? ''
-        : 'display: none'}>
-      <h5
-        id="headline"
-        style=${this._headlineSlotHasContent || this.headline !== null
+      style=${
+        this._headerSlotHasContent ||
+        this._headlineSlotHasContent ||
+        this.headline !== null
           ? ''
-          : 'display: none'}>
+          : 'display: none'
+      }>
+      <${this._headlineVariantTag}
+        id="headline"
+        class="uui-h5"
+        style=${
+          this._headlineSlotHasContent || this.headline !== null
+            ? ''
+            : 'display: none'
+        }>
         ${this.headline}
         <slot name="headline" @slotchange=${this._headlineSlotChanged}></slot>
-      </h5>
+      </${this._headlineVariantTag}>
       <slot name="header" @slotchange=${this._headerSlotChanged}></slot>
     </div>`;
+    /* eslint-enable lit/no-invalid-html, lit/binding-positions */
   }
 
   render() {

packages/uui-box/lib/uui-box.story.ts

@@ -1,28 +1,54 @@
 import '.';
 
-import { Story } from '@storybook/web-components';
+import { Meta, Story } from '@storybook/web-components';
 import { html } from 'lit';
+import type { UUIBoxElement } from './uui-box.element';
+
 import readme from '../README.md?raw';
 
 export default {
   title: 'Layout/Box',
   component: 'uui-box',
   id: 'uui-box',
+  args: {
+    headline: 'Headline',
+    headlineVariant: 'h5',
+  },
+  argTypes: {
+    headlineVariant: {
+      control: {
+        type: 'select',
+      },
+      options: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+    },
+  },
   parameters: {
     readme: {
       markdown: readme,
     },
   },
-};
+} as Meta<UUIBoxElement>;
 
-const Template: Story = () => html`
-  <uui-box headline="Headline">
-    Some content of this box, appended in the default slot.
-  </uui-box>
-`;
+const Template: Story = props => {
+  return html`
+    <uui-box
+      .headline=${props.headline}
+      .headlineVariant=${props.headlineVariant}>
+      <p>Some content of this box, appended in the default slot.</p>
+      <p>The headline is currently rendered as a ${props.headlineVariant}.</p>
+    </uui-box>
+  `;
+};
 
 export const AAAOverview = Template.bind({});
 AAAOverview.storyName = 'Overview';
+AAAOverview.parameters = {
+  docs: {
+    source: {
+      type: 'dynamic',
+    },
+  },
+};
 
 export const Slots: Story = () => html`
   <uui-box>
@@ -33,3 +59,16 @@ export const Slots: Story = () => html`
     <uui-button look="placeholder">Default slot</uui-button>
   </uui-box>
 `;
+
+export const WithHeadlineVariant = Template.bind({});
+WithHeadlineVariant.args = { headline: 'H1 Headline', headerVariant: 'h1' };
+WithHeadlineVariant.parameters = {
+  docs: {
+    source: {
+      code: `
+<uui-box headline="H1 Headline" headline-variant="h1">
+  The headline is rendered as a H1.
+</uui-box>`,
+    },
+  },
+};

packages/uui-box/lib/uui-box.test.ts

@@ -1,6 +1,7 @@
 import { expect, fixture, html } from '@open-wc/testing';
 
 import { UUIBoxElement } from './uui-box.element';
+import { InterfaceHeadingValues } from '@umbraco-ui/uui-base/lib/types';
 
 describe('UUIBox', () => {
   let element: UUIBoxElement;
@@ -15,13 +16,23 @@ describe('UUIBox', () => {
   });
 
   it('passes the a11y audit', async () => {
-    await expect(element).shadowDom.to.be.accessible();
+    for (const headlineVariant of InterfaceHeadingValues) {
+      element = await fixture(html` <uui-box
+        headline="headline"
+        .headlineVariant="${headlineVariant}">
+        Main
+      </uui-box>`);
+      await expect(element).shadowDom.to.be.accessible();
+    }
   });
 
   describe('properties', () => {
     it('has a headline property', () => {
       expect(element).to.have.property('headline');
     });
+    it('has a headlineVariant property', () => {
+      expect(element).to.have.property('headlineVariant');
+    });
   });
 
   describe('css custom properties', () => {
@@ -57,6 +68,20 @@ describe('UUIBox', () => {
       const slot = element.shadowRoot!.querySelector('slot[name=header]')!;
       expect(slot).to.exist;
     });
+
+    it('renders specified headline tag when headlineVariant is set', async () => {
+      element = await fixture(
+        html` <uui-box headline="headline" headline-variant="h2">Main</uui-box>`
+      );
+
+      // it should exist and it should be the only one
+      expect(element.shadowRoot!.querySelectorAll('h2')).to.have.lengthOf(1);
+
+      // and it should change when headlineVariant changes
+      element.headlineVariant = 'h3';
+      await element.updateComplete;
+      expect(element.shadowRoot!.querySelectorAll('h3')).to.have.lengthOf(1);
+    });
   });
 
   describe('UUIBox', () => {

typings.d.ts

@@ -1,6 +1,6 @@
 declare module '*.css';
 
-declare module '*.md?raw' {
+declare module '*?raw' {
   const content: string;
   export default content;
 }