feat(header): add new divider property (#29675)

Issue number: internal

---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->

- Add new divider property on header's Ionic theme
- Added new divider test.
- Added TODO for support on ios/ md in future.

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

<!--
  If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
  2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md#footer
for more information.
-->


## Other information

<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->

[Header divider
sample](https://ionic-framework-a13vvxiyy-ionic1.vercel.app/src/components/header/test/divider?ionic:theme=ionic)

---------

Co-authored-by: ionitron <hi@ionicframework.com>
Co-authored-by: Giuliana Silva <108938618+OS-giulianasilva@users.noreply.github.com>

core/api.txt

@@ -829,6 +829,7 @@ ion-grid,css-prop,--ion-grid-width-xs
 
 ion-header,none
 ion-header,prop,collapse,"condense" | "fade" | undefined,undefined,false,false
+ion-header,prop,divider,boolean,false,false,false
 ion-header,prop,mode,"ios" | "md",undefined,false,false
 ion-header,prop,theme,"ios" | "md" | "ionic",undefined,false,false
 ion-header,prop,translucent,boolean,false,false,false

core/src/components.d.ts

@@ -1286,6 +1286,10 @@ export namespace Components {
           * Describes the scroll effect that will be applied to the header. Only applies when the theme is `"ios"`.  Typically used for [Collapsible Large Titles](https://ionicframework.com/docs/api/title#collapsible-large-titles)
          */
         "collapse"?: 'condense' | 'fade';
+        /**
+          * If `true`, the header will have a line at the bottom. TODO(ROU-10855): add support for this prop on ios/md themes
+         */
+        "divider": boolean;
         /**
           * The mode determines the platform behaviors of the component.
          */
@@ -6574,6 +6578,10 @@ declare namespace LocalJSX {
           * Describes the scroll effect that will be applied to the header. Only applies when the theme is `"ios"`.  Typically used for [Collapsible Large Titles](https://ionicframework.com/docs/api/title#collapsible-large-titles)
          */
         "collapse"?: 'condense' | 'fade';
+        /**
+          * If `true`, the header will have a line at the bottom. TODO(ROU-10855): add support for this prop on ios/md themes
+         */
+        "divider"?: boolean;
         /**
           * The mode determines the platform behaviors of the component.
          */

core/src/components/header/header.ionic.scss

@@ -6,5 +6,9 @@
 
 ion-header {
   box-shadow: #{globals.$ionic-elevation-200};
-  z-index: 10;
+  z-index: 10; // TODO(ROU-10853): replace this value with a layer token.
+
+  &.header-divider {
+    border-bottom: globals.$ionic-border-size-025 globals.$ionic-border-style-solid globals.$ionic-color-neutral-300;
+  }
 }

core/src/components/header/header.tsx

@@ -46,6 +46,12 @@ export class Header implements ComponentInterface {
    */
   @Prop() collapse?: 'condense' | 'fade';
 
+  /**
+   * If `true`, the header will have a line at the bottom.
+   * TODO(ROU-10855): add support for this prop on ios/md themes
+   */
+  @Prop() divider = false;
+
   /**
    * If `true`, the header will be translucent.
    * Only applies when the theme is `"ios"` and the device supports
@@ -207,7 +213,7 @@ export class Header implements ComponentInterface {
   }
 
   render() {
-    const { translucent, inheritedAttributes } = this;
+    const { translucent, inheritedAttributes, divider } = this;
     const theme = getIonTheme(this);
     const collapse = this.collapse || 'none';
 
@@ -226,6 +232,7 @@ export class Header implements ComponentInterface {
           [`header-translucent`]: this.translucent,
           [`header-collapse-${collapse}`]: true,
           [`header-translucent-${theme}`]: this.translucent,
+          ['header-divider']: divider,
         }}
         {...inheritedAttributes}
       >

core/src/components/header/test/divider/header.e2e.ts

@@ -0,0 +1,31 @@
+import { expect } from '@playwright/test';
+import { configs, test } from '@utils/test/playwright';
+
+configs({ modes: ['ionic-md'], directions: ['ltr'] }).forEach(({ title, screenshot, config }) => {
+  test.describe(title('header: divider'), () => {
+    test('should not have visual regressions with divider header', async ({ page }) => {
+      await page.setContent(
+        `
+        <style>
+          .container {
+            padding: 10px;
+          }
+        </style>
+      
+        <div class="container">
+          <ion-header divider="true">
+            <ion-toolbar>
+              <ion-title>Header - Divider</ion-title>
+            </ion-toolbar>
+          </ion-header>
+        </div>
+      `,
+        config
+      );
+
+      const container = page.locator('.container');
+
+      await expect(container).toHaveScreenshot(screenshot(`ionic-header-divider`));
+    });
+  });
+});

packages/angular/src/directives/proxies.ts

@@ -824,14 +824,14 @@ export declare interface IonGrid extends Components.IonGrid {}
 
 
 @ProxyCmp({
-  inputs: ['collapse', 'mode', 'theme', 'translucent']
+  inputs: ['collapse', 'divider', 'mode', 'theme', 'translucent']
 })
 @Component({
   selector: 'ion-header',
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: '<ng-content></ng-content>',
   // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
-  inputs: ['collapse', 'mode', 'theme', 'translucent'],
+  inputs: ['collapse', 'divider', 'mode', 'theme', 'translucent'],
 })
 export class IonHeader {
   protected el: HTMLElement;

packages/angular/standalone/src/directives/proxies.ts

@@ -860,14 +860,14 @@ export declare interface IonGrid extends Components.IonGrid {}
 
 @ProxyCmp({
   defineCustomElementFn: defineIonHeader,
-  inputs: ['collapse', 'mode', 'theme', 'translucent']
+  inputs: ['collapse', 'divider', 'mode', 'theme', 'translucent']
 })
 @Component({
   selector: 'ion-header',
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: '<ng-content></ng-content>',
   // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
-  inputs: ['collapse', 'mode', 'theme', 'translucent'],
+  inputs: ['collapse', 'divider', 'mode', 'theme', 'translucent'],
   standalone: true
 })
 export class IonHeader {

packages/vue/src/proxies.ts

@@ -379,6 +379,7 @@ export const IonGrid = /*@__PURE__*/ defineContainer<JSX.IonGrid>('ion-grid', de
 
 export const IonHeader = /*@__PURE__*/ defineContainer<JSX.IonHeader>('ion-header', defineIonHeader, [
   'collapse',
+  'divider',
   'translucent'
 ]);