fix(back-button): add and document custom properties

removes use of `--ion-color-*` variables references #14808 documents custom properties references #14850 uses `—background` vars to prevent overriding the color css references #14853
ionic-team · Sep 24, 2018 · b3aebb8 · b3aebb8
1 parent f9caace
commit b3aebb8
Show file tree

Hide file tree

Showing 6 changed files with 291 additions and 71 deletions.
diff --git a/core/src/components/back-button/back-button.ios.scss b/core/src/components/back-button/back-button.ios.scss
@@ -5,39 +5,32 @@
 // --------------------------------------------------
 
 :host {
-  --ion-color-base: #{$back-button-ios-color};
+  --color: #{$back-button-ios-color};
+  --margin-top: 0;
+  --margin-end: 0;
+  --margin-bottom: 0;
+  --margin-start: 0;
+  --padding-top: 0;
+  --padding-end: 0;
+  --padding-bottom: 0;
+  --padding-start: 0;
+  --min-height: 32px;
+  --icon-padding-top: 0;
+  --icon-padding-end: 0;
+  --icon-padding-bottom: 0;
+  --icon-padding-start: 0;
+  --icon-margin-top: 0;
+  --icon-margin-end: -5px;
+  --icon-margin-bottom: 0;
+  --icon-margin-start: -4px;
+  --icon-font-size: 1.85em;
+
+  font-size: 17px;
 }
 
 .back-button-native {
-  @include padding(0);
-  @include margin(0);
-
-  min-height: 32px;
-
   transform: translateZ(0);
 
-  border: 0;
-
-  background-color: transparent;
-
-  font-size: 17px;
-
-  line-height: 1;
-
   overflow: visible;
   z-index: $back-button-ios-button-z-index;
-
-  &.activated {
-    opacity: .4;
-  }
-}
-
-ion-icon {
-  @include padding(0);
-  @include margin(0, -5px, 0, -4px);
-
-  display: inherit;
-
-  font-size: 1.85em;
-  pointer-events: none;
 }
diff --git a/core/src/components/back-button/back-button.md.scss b/core/src/components/back-button/back-button.md.scss
@@ -5,42 +5,38 @@
 // --------------------------------------------------
 
 :host {
-  --ion-color-base: currentColor;
-}
-
-.back-button-native {
-  @include margin(1px, 6px, 0, 0);
-  @include padding(0, 5px);
-
-  min-width: 44px;
-  height: 32px;
-
-  border: 0;
-
-  background-color: transparent;
+  --color: #{$back-button-md-color};
+  --margin-top: 1px;
+  --margin-end: 6px;
+  --margin-bottom: 0;
+  --margin-start: 0;
+  --padding-top: 0;
+  --padding-end: 5px;
+  --padding-bottom: 0;
+  --padding-start: 5px;
+  --height: 32px;
+  --min-width: 44px;
+  --icon-padding-end: .3em;
+  --icon-padding-start: .3em;
+  --icon-margin-top: 0;
+  --icon-margin-end: 6px;
+  --icon-margin-bottom: 0;
+  --icon-margin-start: 6px;
+  --icon-font-size: 24px;
+  --icon-font-weight: normal;
 
   font-size: 14px;
   font-weight: 500;
 
   text-transform: uppercase;
+}
 
+.back-button-native {
   box-shadow: none;
-
-  &.activated {
-    opacity: .4;
-  }
 }
 
 ion-icon {
-  @include padding-horizontal(null, .3em);
-  @include margin(0);
-  @include margin(0, 6px);
-
-  font-size: 24px;
-  font-weight: normal;
-
   line-height: .67;
 
   text-align: start;
-  pointer-events: none;
 }
diff --git a/core/src/components/back-button/back-button.scss b/core/src/components/back-button/back-button.scss
@@ -4,10 +4,56 @@
 // --------------------------------------------------
 
 :host {
+ /**
+   * @prop --background: Background of the button
+   *
+   * @prop --color: Text color of the button
+   *
+   * @prop --width: Width of the button
+   * @prop --height: Height of the button
+   *
+   * @prop --min-width: Minimum width of the button
+   * @prop --min-height: Minimum height of the button
+   *
+   * @prop --transition: Transition of the button
+   *
+   * @prop --border-radius: Border radius of the button
+   *
+   * @prop --ripple-color: Color of the button ripple effect
+   *
+   * @prop --opacity: Opacity of the button
+   *
+   * @prop --margin-top: Margin top of the button
+   * @prop --margin-end: Margin end of the button
+   * @prop --margin-bottom: Margin bottom of the button
+   * @prop --margin-start: Margin start of the button
+   *
+   * @prop --padding-top: Padding top of the button
+   * @prop --padding-end: Padding end of the button
+   * @prop --padding-bottom: Padding bottom of the button
+   * @prop --padding-start: Padding start of the button
+   *
+   * @prop --icon-margin-top: Margin top of the button icon
+   * @prop --icon-margin-end: Margin end of the button icon
+   * @prop --icon-margin-bottom: Margin bottom of the button icon
+   * @prop --icon-margin-start: Margin start of the button icon
+   *
+   * @prop --icon-padding-top: Padding top of the button icon
+   * @prop --icon-padding-end: Padding end of the button icon
+   * @prop --icon-padding-bottom: Padding bottom of the button icon
+   * @prop --icon-padding-start: Padding start of the button icon
+   *
+   * @prop --icon-font-size: Font size of the button icon
+   * @prop --icon-font-weight: Font weight of the button icon
+   */
+  --background: transparent;
+  --ripple-color: currentColor;
+  --transition: background-color, opacity 100ms linear;
+  --opacity: 1;
+
   display: none;
 
-  color: #{current-color(base)};
-  pointer-events: all;
+  font-family: $font-family-base;
 
   text-align: center;
   text-decoration: none;
@@ -20,27 +66,61 @@
   font-kerning: none;
 }
 
+
+// Back Button with Color
+// --------------------------------------------------
+
+:host(.ion-color) .back-button-native {
+  color: current-color(base);
+}
+
+
+// Back Button States
+// --------------------------------------------------
+
+:host(.activated) .back-button-native {
+  opacity: .4;
+}
+
 :host-context(.can-go-back > ion-header),
 :host(.show-back-button) {
   display: block;
 }
 
+
+// Native Back Button
+// --------------------------------------------------
+
 .back-button-native {
-  @include text-inherit();
+  @include border-radius(var(--border-radius));
   @include font-smoothing();
+  @include margin(var(--margin-top), var(--margin-end), var(--margin-bottom), var(--margin-start));
+  @include padding(var(--padding-top), var(--padding-end), var(--padding-bottom), var(--padding-start));
+  @include text-inherit();
 
   display: block;
   position: relative;
 
-  transition: background-color, opacity 100ms linear;
+  width: var(--width);
+  min-width: var(--min-width);
+
+  height: var(--height);
+  min-height: var(--min-height);
+
+  transition: var(--transition);
 
   border: 0;
 
   outline: none;
 
+  background: var(--background);
+  color: var(--color);
+
   line-height: 1;
 
   cursor: pointer;
+
+  opacity: var(--opacity);
   user-select: none;
   z-index: 0;
   appearance: none;
@@ -58,8 +138,18 @@
   height: 100%;
 }
 
-.back-button-text {
-  display: flex;
 
-  align-items: center;
+// Back Button Icon
+// --------------------------------------------------
+
+ion-icon {
+  @include padding(var(--icon-padding-top), var(--icon-padding-end), var(--icon-padding-bottom), var(--icon-padding-start));
+  @include margin(var(--icon-margin-top), var(--icon-margin-end), var(--icon-margin-bottom), var(--icon-margin-start));
+
+  display: inherit;
+
+  font-size: var(--icon-font-size);
+  font-weight: var(--icon-font-weight);
+
+  pointer-events: none;
 }
diff --git a/core/src/components/back-button/back-button.tsx b/core/src/components/back-button/back-button.tsx
@@ -39,12 +39,12 @@ export class BackButton implements ComponentInterface {
   /**
    * The icon name to use for the back button.
    */
-  @Prop() icon?: string;
+  @Prop() icon?: string | null;
 
   /**
    * The text to display in the back button.
    */
-  @Prop() text?: string;
+  @Prop() text?: string | null;
 
   async onClick(ev: Event) {
     const nav = this.el.closest('ion-nav');
@@ -60,18 +60,19 @@ export class BackButton implements ComponentInterface {
     const showBackButton = this.defaultHref !== undefined;
 
     return {
+      'ion-activatable': true,
       class: {
         ...createColorClasses(this.color),
         'button': true,
         'show-back-button': showBackButton
-      },
-      'ion-activatable': true,
+      }
     };
   }
 
   render() {
-    const backButtonIcon = this.icon || this.config.get('backButtonIcon', 'arrow-back');
-    const backButtonText = this.text !== undefined ? this.text : this.config.get('backButtonText', 'Back');
+    const defaultBackButtonText = this.mode === 'ios' ? 'Back' : null;
+    const backButtonIcon = this.icon != null ? this.icon : this.config.get('backButtonIcon', 'arrow-back');
+    const backButtonText = this.text != null ? this.text : this.config.get('backButtonText', defaultBackButtonText);
 
     return (
       <button
@@ -80,9 +81,9 @@ export class BackButton implements ComponentInterface {
         onClick={ev => this.onClick(ev)}
       >
         <span class="back-button-inner">
-          {backButtonIcon && <ion-icon icon={backButtonIcon} lazy={false}/>}
-          {this.mode === 'ios' && backButtonText && <span class="button-text">{backButtonText}</span>}
-          {this.mode === 'md' && <ion-ripple-effect />}
+          {backButtonIcon && <ion-icon icon={backButtonIcon} lazy={false}></ion-icon>}
+          {backButtonText && <span class="back-button-text">{backButtonText}</span>}
+          {this.mode === 'md' && <ion-ripple-effect></ion-ripple-effect>}
         </span>
       </button>
     );

diff --git a/core/src/components/back-button/readme.md b/core/src/components/back-button/readme.md
@@ -19,6 +19,40 @@ To change what is displayed in the back button, use the `text` and `icon` proper
 | `text`        | `text`         | The text to display in the back button.                                                                                                                                                                                                                                | `string` |
 
 
+## CSS Custom Properties
+
+| Name                    | Description                       |
+| ----------------------- | --------------------------------- |
+| `--background`          | Background of the button          |
+| `--border-radius`       | Border radius of the button       |
+| `--color`               | Text color of the button          |
+| `--height`              | Height of the button              |
+| `--icon-font-size`      | Font size of the button icon      |
+| `--icon-font-weight`    | Font weight of the button icon    |
+| `--icon-margin-bottom`  | Margin bottom of the button icon  |
+| `--icon-margin-end`     | Margin end of the button icon     |
+| `--icon-margin-start`   | Margin start of the button icon   |
+| `--icon-margin-top`     | Margin top of the button icon     |
+| `--icon-padding-bottom` | Padding bottom of the button icon |
+| `--icon-padding-end`    | Padding end of the button icon    |
+| `--icon-padding-start`  | Padding start of the button icon  |
+| `--icon-padding-top`    | Padding top of the button icon    |
+| `--margin-bottom`       | Margin bottom of the button       |
+| `--margin-end`          | Margin end of the button          |
+| `--margin-start`        | Margin start of the button        |
+| `--margin-top`          | Margin top of the button          |
+| `--min-height`          | Minimum height of the button      |
+| `--min-width`           | Minimum width of the button       |
+| `--opacity`             | Opacity of the button             |
+| `--padding-bottom`      | Padding bottom of the button      |
+| `--padding-end`         | Padding end of the button         |
+| `--padding-start`       | Padding start of the button       |
+| `--padding-top`         | Padding top of the button         |
+| `--ripple-color`        | Color of the button ripple effect |
+| `--transition`          | Transition of the button          |
+| `--width`               | Width of the button               |
+
+
 ----------------------------------------------
 
 *Built with [StencilJS](https://stenciljs.com/)*