feat(OnyxHeadline): support showAs property (#2587)

Relates to #2451 

Add new `showAs` property to allow defining a different visual size
instead of the semantical type.

## Checklist

- [x] The added / edited code has been documented with
[JSDoc](https://jsdoc.app/about-getting-started)
- [x] All changes are documented in the documentation app (folder
`apps/docs`)
- [x] If a new component is added, at least one [Playwright screenshot
test](https://github.com/SchwarzIT/onyx/actions/workflows/playwright-screenshots.yml)
is added
- [x] A changeset is added with `npx changeset add` if your changes
should be released as npm package (because they affect the library
usage)

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.changeset/great-walls-juggle.md

@@ -0,0 +1,5 @@
+---
+"sit-onyx": minor
+---
+
+feat(OnyxHeadline): support `showAs` property

apps/docs/src/.vitepress/components/ComponentCard.vue

@@ -33,7 +33,7 @@ const props = defineProps<ComponentCardProps>();
     :href="props.href"
     :target="props.href?.startsWith('http') ? '_blank' : '_self'"
   >
-    <OnyxHeadline is="h2">{{ props.name }}</OnyxHeadline>
+    <OnyxHeadline is="h3" visual-size="h2">{{ props.name }}</OnyxHeadline>
     <ComponentStatusBadge :status="props.status" class="card__status" />
   </component>
 </template>

apps/docs/src/.vitepress/components/OnyxTypography.vue

@@ -1,5 +1,11 @@
 <script lang="ts" setup>
-import { OnyxHeadline, OnyxLink, type HeadlineType, type TextSize } from "sit-onyx";
+import {
+  OnyxHeadline,
+  OnyxLink,
+  type HeadlineType,
+  type OnyxHeadlineProps,
+  type TextSize,
+} from "sit-onyx";
 import { computed, ref } from "vue";
 import DesignVariable from "./DesignVariable.vue";
 import DesignVariableCard from "./DesignVariableCard.vue";
@@ -67,7 +73,12 @@ const getTextSizeClass = (fontSize?: TextSize) => {
             {{ previewText }}
           </OnyxLink>
 
-          <OnyxHeadline :is="variable.htmlTag" v-else :monospace="isMonospace">
+          <OnyxHeadline
+            is="h3"
+            v-else
+            :show-as="variable.htmlTag as OnyxHeadlineProps['showAs']"
+            :monospace="isMonospace"
+          >
             {{ previewText }}
           </OnyxHeadline>
         </template>
@@ -95,6 +106,9 @@ const getTextSizeClass = (fontSize?: TextSize) => {
     padding: 0;
     border: none;
     letter-spacing: normal;
+    font-size: revert-layer;
+    line-height: revert-layer;
+    font-weight: revert-layer;
   }
 }
 

packages/sit-onyx/src/components/OnyxHeadline/OnyxHeadline.ct.tsx

@@ -16,6 +16,19 @@ test.describe("Screenshot tests", () => {
   });
 });
 
+test.describe("Screenshot tests (visual size)", () => {
+  executeMatrixScreenshotTest({
+    name: "Headline (visual sizes)",
+    columns: ["h1", "h2", "h3", "h4"],
+    rows: HEADLINE_TYPES,
+    component: (column, row) => (
+      <OnyxHeadline is={row} showAs={column}>
+        Hello World
+      </OnyxHeadline>
+    ),
+  });
+});
+
 test.describe("Screenshot tests (hash)", () => {
   executeMatrixScreenshotTest({
     name: "Headline (hash)",

packages/sit-onyx/src/components/OnyxHeadline/OnyxHeadline.vue

@@ -22,6 +22,7 @@ const { t } = injectI18n();
 const skeleton = useSkeletonContext(props);
 
 const normalizedHash = computed(() => (props.hash ? normalizeUrlHash(props.hash) : undefined));
+const showAs = computed(() => props.showAs ?? props.is);
 
 const copyLink = async (hash: string) => {
   const { origin, pathname, search } = window.location;
@@ -33,14 +34,14 @@ const copyLink = async (hash: string) => {
 <template>
   <OnyxSkeleton
     v-if="skeleton"
-    :class="['onyx-headline-skeleton', `onyx-headline-skeleton--${props.is}`]"
+    :class="['onyx-headline-skeleton', `onyx-headline-skeleton--${showAs}`]"
   />
 
   <component
     :is="props.is"
     v-else
     :id="normalizedHash"
-    :class="['onyx-component', 'onyx-headline', `onyx-headline--${props.is}`]"
+    :class="['onyx-component', 'onyx-headline', `onyx-headline--${showAs}`]"
   >
     <a
       v-if="normalizedHash"

packages/sit-onyx/src/components/OnyxHeadline/types.ts

@@ -2,10 +2,14 @@ import type { SkeletonInjected } from "../../composables/useSkeletonState";
 
 export type OnyxHeadlineProps = {
   /**
-   * Headline type. Please note that only h1-h4 are intended to be used from UX perspective.
-   * h5 and h6 will have the same styles as h4 and should only be used for semantic reasons.
+   * Semantical headline type. Should match the page hierarchy and should not skip hierarchies (e.g. h2 should be followed by h3 etc.).
    */
   is: HeadlineType;
+  /**
+   * Visual size of the headline (h1-h6). Will default to but can be different from the semantical `is` property.
+   * Please note that only h1-h4 are intended to be used from UX perspective, h5 and h6 will have the same styles as h4.
+   */
+  showAs?: Exclude<HeadlineType, "h5" | "h6">;
   /**
    * Unique headline hash/ID (without "#") that is used to show a "#" icon on hover. Makes the headline clickable and a URL that points to this headline
    * is copied to the users clipboard. Will be automatically normalized when containing non URL-safe characters.