feat(divider): add new ion-divider component (#30270)

Issue number: internal
---------

## What is the new behavior?
- Introduces a new component, `ion-divider` which has two props,
`spacing` and `inset`.
- Adds e2e tests to both `spacing` and `inset` props

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

## Other information
- As discussed with the PO, using this new component inside an
`ion-item` is out of scope , for now.

---------

Co-authored-by: Brandy Smith <[email protected]>
Co-authored-by: Gonçalo M. <[email protected]>
Co-authored-by: Maria Hutt <[email protected]>

Author: 4 people

core/api.txt

@@ -731,6 +731,22 @@ ion-datetime-button,prop,mode,"ios" | "md",undefined,false,false
 ion-datetime-button,prop,theme,"ios" | "md" | "ionic",undefined,false,false
 ion-datetime-button,part,native
 
+ion-divider,shadow
+ion-divider,prop,inset,boolean,false,false,false
+ion-divider,prop,spacing,"large" | "medium" | "small" | "xlarge" | "xsmall" | "xxlarge" | "xxsmall" | undefined,'xxsmall',false,true
+ion-divider,css-prop,--margin-bottom,ionic
+ion-divider,css-prop,--margin-bottom,ios
+ion-divider,css-prop,--margin-bottom,md
+ion-divider,css-prop,--margin-top,ionic
+ion-divider,css-prop,--margin-top,ios
+ion-divider,css-prop,--margin-top,md
+ion-divider,css-prop,--padding-end,ionic
+ion-divider,css-prop,--padding-end,ios
+ion-divider,css-prop,--padding-end,md
+ion-divider,css-prop,--padding-start,ionic
+ion-divider,css-prop,--padding-start,ios
+ion-divider,css-prop,--padding-start,md
+
 ion-fab,shadow
 ion-fab,prop,activated,boolean,false,false,false
 ion-fab,prop,edge,boolean,false,false,false

core/src/components.d.ts

@@ -1164,6 +1164,16 @@ export namespace Components {
          */
         "theme"?: "ios" | "md" | "ionic";
     }
+    interface IonDivider {
+        /**
+          * If `true`, the divider will have horizontal margins By default, it's `false`
+         */
+        "inset": boolean;
+        /**
+          * Set to `"xxsmall"` for the smallest spacing. Set to "xsmall" for very small spacing. Set to `"small"` for small spacing. Set to "medium" for medium spacing. Set to "large" for large spacing. Set to `"xlarge"` for the largest spacing.  Defaults to `"xxsmall"`.
+         */
+        "spacing"?: 'xxsmall' | 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'xxlarge';
+    }
     interface IonFab {
         /**
           * If `true`, both the `ion-fab-button` and all `ion-fab-list` inside `ion-fab` will become active. That means `ion-fab-button` will become a `close` icon and `ion-fab-list` will become visible.
@@ -4440,6 +4450,12 @@ declare global {
         prototype: HTMLIonDatetimeButtonElement;
         new (): HTMLIonDatetimeButtonElement;
     };
+    interface HTMLIonDividerElement extends Components.IonDivider, HTMLStencilElement {
+    }
+    var HTMLIonDividerElement: {
+        prototype: HTMLIonDividerElement;
+        new (): HTMLIonDividerElement;
+    };
     interface HTMLIonFabElement extends Components.IonFab, HTMLStencilElement {
     }
     var HTMLIonFabElement: {
@@ -5399,6 +5415,7 @@ declare global {
         "ion-content": HTMLIonContentElement;
         "ion-datetime": HTMLIonDatetimeElement;
         "ion-datetime-button": HTMLIonDatetimeButtonElement;
+        "ion-divider": HTMLIonDividerElement;
         "ion-fab": HTMLIonFabElement;
         "ion-fab-button": HTMLIonFabButtonElement;
         "ion-fab-list": HTMLIonFabListElement;
@@ -6619,6 +6636,16 @@ declare namespace LocalJSX {
          */
         "theme"?: "ios" | "md" | "ionic";
     }
+    interface IonDivider {
+        /**
+          * If `true`, the divider will have horizontal margins By default, it's `false`
+         */
+        "inset"?: boolean;
+        /**
+          * Set to `"xxsmall"` for the smallest spacing. Set to "xsmall" for very small spacing. Set to `"small"` for small spacing. Set to "medium" for medium spacing. Set to "large" for large spacing. Set to `"xlarge"` for the largest spacing.  Defaults to `"xxsmall"`.
+         */
+        "spacing"?: 'xxsmall' | 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'xxlarge';
+    }
     interface IonFab {
         /**
           * If `true`, both the `ion-fab-button` and all `ion-fab-list` inside `ion-fab` will become active. That means `ion-fab-button` will become a `close` icon and `ion-fab-list` will become visible.
@@ -9532,6 +9559,7 @@ declare namespace LocalJSX {
         "ion-content": IonContent;
         "ion-datetime": IonDatetime;
         "ion-datetime-button": IonDatetimeButton;
+        "ion-divider": IonDivider;
         "ion-fab": IonFab;
         "ion-fab-button": IonFabButton;
         "ion-fab-list": IonFabList;
@@ -9634,6 +9662,7 @@ declare module "@stencil/core" {
             "ion-content": LocalJSX.IonContent & JSXBase.HTMLAttributes<HTMLIonContentElement>;
             "ion-datetime": LocalJSX.IonDatetime & JSXBase.HTMLAttributes<HTMLIonDatetimeElement>;
             "ion-datetime-button": LocalJSX.IonDatetimeButton & JSXBase.HTMLAttributes<HTMLIonDatetimeButtonElement>;
+            "ion-divider": LocalJSX.IonDivider & JSXBase.HTMLAttributes<HTMLIonDividerElement>;
             "ion-fab": LocalJSX.IonFab & JSXBase.HTMLAttributes<HTMLIonFabElement>;
             "ion-fab-button": LocalJSX.IonFabButton & JSXBase.HTMLAttributes<HTMLIonFabButtonElement>;
             "ion-fab-list": LocalJSX.IonFabList & JSXBase.HTMLAttributes<HTMLIonFabListElement>;

core/src/components/divider/divider.common.scss

@@ -0,0 +1,41 @@
+@import "../../themes/mixins";
+
+:host {
+  /**
+   * @prop --margin-top: Top margin of the divider
+   * @prop --margin-bottom: Bottom margin of the divider
+   * @prop --padding-end: Right padding if direction is left-to-right, and left padding if direction is right-to-left of the divider
+   * @prop --padding-start: Left padding if direction is left-to-right, and right padding if direction is right-to-left of the divider
+   */
+  --margin-top: 0px;
+  --margin-bottom: 0px;
+  --padding-start: 0px;
+  --padding-end: 0px;
+
+  display: block;
+
+  width: 100%;
+
+  /* stylelint-disable */
+  @include ltr() {
+    padding-right: calc(var(--padding-end) + var(--ion-safe-area-right, 0px));
+    padding-left: calc(var(--padding-start) + var(--ion-safe-area-left, 0px));
+  }
+
+  @include rtl() {
+    padding-right: calc(var(--padding-start) + var(--ion-safe-area-right, 0px));
+    padding-left: calc(var(--padding-end) + var(--ion-safe-area-left, 0px));
+  }
+  /* stylelint-enable */
+}
+
+:host hr {
+  display: block;
+
+  width: 100%;
+
+  margin-top: var(--margin-top);
+  margin-bottom: var(--margin-bottom);
+
+  border: none;
+}

core/src/components/divider/divider.ionic.scss

@@ -0,0 +1,47 @@
+@use "../../themes/ionic/ionic.globals.scss" as globals;
+@use "./divider.common.scss";
+
+:host hr {
+  border-top: globals.$ion-border-size-025 globals.$ion-border-style-solid globals.$ion-border-default;
+}
+
+// Divider Inset
+// --------------------------------------------------
+
+:host(.divider-inset) {
+  --padding-start: #{globals.$ion-space-400};
+  --padding-end: #{globals.$ion-space-400};
+}
+
+// Divider Spacing
+// --------------------------------------------------
+
+:host(.divider-spacing-xsmall) {
+  --margin-top: #{globals.$ion-space-200};
+  --margin-bottom: #{globals.$ion-space-200};
+}
+
+:host(.divider-spacing-small) {
+  --margin-top: #{globals.$ion-space-300};
+  --margin-bottom: #{globals.$ion-space-300};
+}
+
+:host(.divider-spacing-medium) {
+  --margin-top: #{globals.$ion-space-400};
+  --margin-bottom: #{globals.$ion-space-400};
+}
+
+:host(.divider-spacing-large) {
+  --margin-top: #{globals.$ion-space-600};
+  --margin-bottom: #{globals.$ion-space-600};
+}
+
+:host(.divider-spacing-xlarge) {
+  --margin-top: #{globals.$ion-space-800};
+  --margin-bottom: #{globals.$ion-space-800};
+}
+
+:host(.divider-spacing-xxlarge) {
+  --margin-top: #{globals.$ion-space-1000};
+  --margin-bottom: #{globals.$ion-space-1000};
+}

core/src/components/divider/divider.ios.scss

@@ -0,0 +1,4 @@
+@import "./divider.native.scss";
+
+// iOS Divider
+// --------------------------------------------------

core/src/components/divider/divider.md.scss

@@ -0,0 +1,4 @@
+@import "./divider.native.scss";
+
+// Material Design Divider
+// --------------------------------------------------

core/src/components/divider/divider.native.scss

@@ -0,0 +1,46 @@
+@import "./divider.common.scss";
+
+:host hr {
+  border-top: 1px solid #e0e0e0;
+}
+
+// Divider Inset
+// --------------------------------------------------
+
+:host(.divider-inset) {
+  --padding-start: 16px;
+  --padding-end: 16px;
+}
+
+// Divider Spacing
+// --------------------------------------------------
+
+:host(.divider-spacing-xsmall) {
+  --margin-top: 8px;
+  --margin-bottom: 8px;
+}
+
+:host(.divider-spacing-small) {
+  --margin-top: 12px;
+  --margin-bottom: 12px;
+}
+
+:host(.divider-spacing-medium) {
+  --margin-top: 16px;
+  --margin-bottom: 16px;
+}
+
+:host(.divider-spacing-large) {
+  --margin-top: 24px;
+  --margin-bottom: 24px;
+}
+
+:host(.divider-spacing-xlarge) {
+  --margin-top: 32px;
+  --margin-bottom: 32px;
+}
+
+:host(.divider-spacing-xxlarge) {
+  --margin-top: 40px;
+  --margin-bottom: 40px;
+}

core/src/components/divider/divider.tsx

@@ -0,0 +1,50 @@
+import { getIonTheme } from '@global/ionic-global';
+import type { ComponentInterface } from '@stencil/core';
+import { Component, Prop, Host, h } from '@stencil/core';
+
+@Component({
+  tag: 'ion-divider',
+  styleUrls: {
+    ios: 'divider.ios.scss',
+    md: 'divider.md.scss',
+    ionic: 'divider.ionic.scss',
+  },
+  shadow: true,
+})
+export class Divider implements ComponentInterface {
+  /**
+   * Set to `"xxsmall"` for the smallest spacing.
+   * Set to "xsmall" for very small spacing.
+   * Set to `"small"` for small spacing.
+   * Set to "medium" for medium spacing.
+   * Set to "large" for large spacing.
+   * Set to `"xlarge"` for the largest spacing.
+   *
+   * Defaults to `"xxsmall"`.
+   */
+  @Prop({ reflect: true }) spacing?: 'xxsmall' | 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'xxlarge' =
+    'xxsmall';
+
+  /**
+   * If `true`, the divider will have horizontal margins
+   * By default, it's `false`
+   */
+  @Prop() inset: boolean = false;
+
+  render() {
+    const { inset, spacing } = this;
+    const theme = getIonTheme(this);
+
+    return (
+      <Host
+        class={{
+          [theme]: true,
+          [`divider-spacing-${spacing}`]: spacing !== undefined,
+          [`divider-inset`]: inset,
+        }}
+      >
+        <hr />
+      </Host>
+    );
+  }
+}

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

@@ -0,0 +1,44 @@
+import { expect } from '@playwright/test';
+import { configs, test } from '@utils/test/playwright';
+
+configs({ directions: ['ltr'], modes: ['md', 'ionic-md'] }).forEach(({ config, screenshot, title }) => {
+  test.describe(title('divider: rendering'), () => {
+    test('should not have visual regressions', async ({ page }) => {
+      await page.setContent(
+        `
+          <div id="container">
+            top
+            <ion-divider></ion-divider>
+            bottom
+          </div>
+        `,
+        config
+      );
+
+      const container = page.locator('#container');
+
+      await expect(container).toHaveScreenshot(screenshot(`divider-basic-default`));
+    });
+  });
+});
+
+configs({ modes: ['md', 'ionic-md'] }).forEach(({ config, screenshot, title }) => {
+  test.describe(title('divider: inset'), () => {
+    test('should not have visual regressions when inset is enabled', async ({ page }) => {
+      await page.setContent(
+        `
+          <div id="container">
+            top
+            <ion-divider inset="true"></ion-divider>
+            bottom
+          </div>
+        `,
+        config
+      );
+
+      const container = page.locator('#container');
+
+      await expect(container).toHaveScreenshot(screenshot(`divider-basic-inset`));
+    });
+  });
+});