feat(tab-bar): add hideOnScroll for ionic theme (#31085)

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. -->

This pull request introduces a new feature to the `ion-tab-bar`
component that allows it to automatically hide when the user scrolls
down and reappear when scrolling up.

## What is the current behavior?
- Missing `hide-on-scroll` feature

## What is the new behavior?
- New Hide-on-Scroll Feature for Tab Bar

## What was done?
*Component Logic & API:*
- Added a new `hideOnScroll` property to `ion-tab-bar`, enabling
automatic hide/show behavior based on scroll direction when the theme is
`"ionic"` and `expand` is `"compact"`. The scroll listener is attached
to the nearest `ion-content` for scroll detection.
(`core/src/components/tab-bar/tab-bar.tsx`, `core/api.txt`)
[[1]](diffhunk://#diff-4524448d8146967e9d7ca6409b76b56db889c6bc42c7d4c911d8b3f1a80d5dbaR67-R73)
[[2]](diffhunk://#diff-4524448d8146967e9d7ca6409b76b56db889c6bc42c7d4c911d8b3f1a80d5dbaR125-R126)
[[3]](diffhunk://#diff-4524448d8146967e9d7ca6409b76b56db889c6bc42c7d4c911d8b3f1a80d5dbaR169-R226)
[[4]](diffhunk://#diff-4524448d8146967e9d7ca6409b76b56db889c6bc42c7d4c911d8b3f1a80d5dbaL172-R246)
[[5]](diffhunk://#diff-4524448d8146967e9d7ca6409b76b56db889c6bc42c7d4c911d8b3f1a80d5dbaR259-R260)
[[6]](diffhunk://#diff-5e21becb925e949068c3cbefae90d040401eaf39874bfd1336d93a3cd8d64809R2403)

*Styling:*
- Updated SCSS to handle the hide/show animation and positioning for the
tab bar when `hideOnScroll` is enabled, including transitions and
transforms for both bottom and top slots.
(`core/src/components/tab-bar/tab-bar.ionic.scss`)
[[1]](diffhunk://#diff-fe63470b419227d79e943ff7370a337e9f273fbcd76d1d420916292e13126db7R73-R81)
[[2]](diffhunk://#diff-fe63470b419227d79e943ff7370a337e9f273fbcd76d1d420916292e13126db7R93-R111)

*Framework Integrations:*
- Updated Angular proxies to support the new `hideOnScroll` input,
ensuring compatibility with Angular apps.
(`packages/angular/src/directives/proxies.ts`,
`packages/angular/standalone/src/directives/proxies.ts`)
[[1]](diffhunk://#diff-1fd76195dbb521bd6fc15558ddb677c06cd4a94d7541ecdea25409b875ea71daL2373-R2380)
[[2]](diffhunk://#diff-23bd4dda0490183f78acea6eb747bfab3091a16ce2e1d4710f4c194669597628L2116-R2123)

*Testing & Documentation:*
- Added a new test page demonstrating the hide-on-scroll behavior, along
with usage requirements and visual confirmation.
(`core/src/components/tab-bar/test/hide-on-scroll/index.html`)

## 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

- This prop will only affect Ionic theme;
- `ion-tab-bar` expand property must be set to compact;
- It should be used inside an `ion-footer`;

---------

Co-authored-by: ionitron <hi@ionicframework.com>

Author: joselrio

core/api.txt

@@ -2402,6 +2402,7 @@ ion-tab,method,setActive,setActive() => Promise<void>
 ion-tab-bar,shadow
 ion-tab-bar,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string & Record<never, never> | undefined,undefined,false,true
 ion-tab-bar,prop,expand,"compact" | "full",'full',false,false
+ion-tab-bar,prop,hideOnScroll,boolean,false,false,false
 ion-tab-bar,prop,mode,"ios" | "md",undefined,false,false
 ion-tab-bar,prop,selectedTab,string | undefined,undefined,false,false
 ion-tab-bar,prop,shape,"rectangular" | "round" | "soft" | undefined,undefined,false,false

core/package-lock.json

@@ -68,7 +68,7 @@
     "fs-extra": "^9.0.1",
     "jest": "^29.7.0",
     "jest-cli": "^29.7.0",
-    "outsystems-design-tokens": "^1.3.7",
+    "outsystems-design-tokens": "^1.3.8",
     "playwright-core": "^1.58.2",
     "prettier": "^2.8.8",
     "rollup": "^2.26.4",

core/package.json

@@ -3980,6 +3980,11 @@ export namespace Components {
           * @default 'full'
          */
         "expand": 'compact' | 'full';
+        /**
+          * If `true`, the tab bar will be hidden when the user scrolls down and shown when the user scrolls up. Only applies when the theme is `"ionic"` and `expand` is `"compact"`.
+          * @default false
+         */
+        "hideOnScroll": boolean;
         /**
           * The mode determines the platform behaviors of the component.
          */
@@ -10077,6 +10082,11 @@ declare namespace LocalJSX {
           * @default 'full'
          */
         "expand"?: 'compact' | 'full';
+        /**
+          * If `true`, the tab bar will be hidden when the user scrolls down and shown when the user scrolls up. Only applies when the theme is `"ionic"` and `expand` is `"compact"`.
+          * @default false
+         */
+        "hideOnScroll"?: boolean;
         /**
           * The mode determines the platform behaviors of the component.
          */
@@ -11320,6 +11330,7 @@ declare namespace LocalJSX {
     interface IonTabBarAttributes {
         "color": Color;
         "selectedTab": string;
+        "hideOnScroll": boolean;
         "translucent": boolean;
         "expand": 'compact' | 'full';
         "shape": 'soft' | 'round' | 'rectangular';

core/src/components.d.ts

@@ -1,4 +1,5 @@
 @use "../../themes/ionic/ionic.globals.scss" as globals;
+@use "../../themes/mixins" as mixins;
 @use "./tab-bar.common";
 
 :host {
@@ -67,13 +68,16 @@
 /* Compact */
 :host(.tab-bar-compact) {
   @include globals.padding(globals.$ion-space-100, globals.$ion-space-400);
+  @include mixins.position-horizontal(50%, null);
 
   position: absolute;
 
   align-self: center;
 
   width: fit-content;
 
+  transform: translateX(calc(-50%));
+
   contain: content;
 }
 
@@ -85,6 +89,23 @@
   bottom: calc(globals.$ion-space-400 + var(--ion-safe-area-bottom, 0));
 }
 
+// Tab Bar Hide on Scroll
+// --------------------------------------------------
+
+:host(.tab-bar-hide-on-scroll) {
+  transition: transform globals.$ion-transition-time-200 globals.$ion-transition-curve-spring;
+}
+
+:host(.tab-bar-scroll-hidden) {
+  transform: translateY(calc(100% + var(--ion-safe-area-bottom, 0) + globals.$ion-space-1000)) translateX(calc(-50%));
+
+  transition: transform globals.$ion-transition-time-350 globals.$ion-transition-curve-base;
+}
+
+:host([slot="top"].tab-bar-scroll-hidden) {
+  transform: translateY(-100%) translateX(calc(-50%));
+}
+
 // Tab Bar Translucent
 // --------------------------------------------------
 

core/src/components/tab-bar/tab-bar.ionic.scss

@@ -1,5 +1,6 @@
 import type { ComponentInterface, EventEmitter } from '@stencil/core';
-import { Component, Element, Event, Host, Prop, State, Watch, h } from '@stencil/core';
+import { Component, Element, Event, Host, Prop, State, Watch, h, readTask, writeTask } from '@stencil/core';
+import { findIonContent, getScrollElement } from '@utils/content';
 import type { KeyboardController } from '@utils/keyboard/keyboard-controller';
 import { createKeyboardController } from '@utils/keyboard/keyboard-controller';
 import { createColorClasses } from '@utils/theme';
@@ -26,11 +27,17 @@ export class TabBar implements ComponentInterface {
   private keyboardCtrl: KeyboardController | null = null;
   private keyboardCtrlPromise: Promise<KeyboardController> | null = null;
   private didLoad = false;
+  private scrollEl?: HTMLElement;
+  private contentScrollCallback?: () => void;
+  private lastScrollTop = 0;
+  private scrollDirectionChangeTop = 0;
 
   @Element() el!: HTMLElement;
 
   @State() keyboardVisible = false;
 
+  @State() scrollHidden = false;
+
   /**
    * The color to use from your application's color palette.
    * Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`.
@@ -57,6 +64,13 @@ export class TabBar implements ComponentInterface {
     }
   }
 
+  /**
+   * If `true`, the tab bar will be hidden when the user scrolls down
+   * and shown when the user scrolls up.
+   * Only applies when the theme is `"ionic"` and `expand` is `"compact"`.
+   */
+  @Prop() hideOnScroll = false;
+
   /**
    * If `true`, the tab bar will be translucent.
    * Only applies when the theme is `"ios"` and the device supports
@@ -108,6 +122,8 @@ export class TabBar implements ComponentInterface {
         tab: this.selectedTab,
       });
     }
+
+    this.setupHideOnScroll();
   }
 
   async connectedCallback() {
@@ -150,6 +166,80 @@ export class TabBar implements ComponentInterface {
       this.keyboardCtrl.destroy();
       this.keyboardCtrl = null;
     }
+
+    this.destroyHideOnScroll();
+  }
+
+  private setupHideOnScroll() {
+    const theme = getIonTheme(this);
+    if (theme !== 'ionic' || !this.hideOnScroll || this.expand !== 'compact') {
+      return;
+    }
+
+    const footerEl = this.el.closest('ion-footer');
+    const pageEl = footerEl?.closest('ion-page, .ion-page') ?? this.el.closest('ion-page, .ion-page');
+    const contentEl = pageEl ? findIonContent(pageEl) : null;
+
+    if (!contentEl) {
+      return;
+    }
+
+    this.initScrollListener(contentEl);
+  }
+
+  private async initScrollListener(contentEl: HTMLElement) {
+    const scrollEl = (this.scrollEl = await getScrollElement(contentEl));
+
+    this.contentScrollCallback = () => {
+      readTask(() => {
+        const scrollTop = scrollEl.scrollTop;
+        const shouldHide = this.checkScrollStatus(scrollTop);
+
+        if (shouldHide !== this.scrollHidden) {
+          writeTask(() => {
+            this.scrollHidden = shouldHide;
+          });
+        }
+
+        this.lastScrollTop = scrollTop;
+      });
+    };
+
+    scrollEl.addEventListener('scroll', this.contentScrollCallback, { passive: true });
+  }
+
+  private destroyHideOnScroll() {
+    if (this.scrollEl && this.contentScrollCallback) {
+      this.scrollEl.removeEventListener('scroll', this.contentScrollCallback);
+      this.contentScrollCallback = undefined;
+    }
+  }
+
+  private checkScrollStatus(scrollTop: number): boolean {
+    // Always visible within the first 80px of scroll
+    const visibleZone = 80;
+    // Hides after 60px of continuous downward scrolling only, when scrolling up threashold should be 0px
+    const scrollThresholdHide = 60;
+
+    if (scrollTop <= visibleZone) {
+      return false;
+    }
+
+    const isScrollingDown = scrollTop > this.lastScrollTop;
+    const wasScrollingDown = this.lastScrollTop > this.scrollDirectionChangeTop;
+
+    if (isScrollingDown !== wasScrollingDown) {
+      this.scrollDirectionChangeTop = this.lastScrollTop;
+    }
+
+    const delta = Math.abs(scrollTop - this.scrollDirectionChangeTop);
+    const threshold = isScrollingDown ? scrollThresholdHide : 0;
+
+    if (delta < threshold) {
+      return this.scrollHidden;
+    }
+
+    return isScrollingDown;
   }
 
   private getShape(): string | undefined {
@@ -169,7 +259,7 @@ export class TabBar implements ComponentInterface {
   }
 
   render() {
-    const { color, translucent, keyboardVisible, expand } = this;
+    const { color, translucent, keyboardVisible, scrollHidden, expand, hideOnScroll } = this;
     const theme = getIonTheme(this);
     const shape = this.getShape();
     const shouldHide = keyboardVisible && this.el.getAttribute('slot') !== 'top';
@@ -182,6 +272,8 @@ export class TabBar implements ComponentInterface {
           [theme]: true,
           'tab-bar-translucent': translucent,
           'tab-bar-hidden': shouldHide,
+          'tab-bar-hide-on-scroll': hideOnScroll,
+          'tab-bar-scroll-hidden': scrollHidden,
           [`tab-bar-${expand}`]: true,
           [`tab-bar-${shape}`]: shape !== undefined,
         })}

core/src/components/tab-bar/tab-bar.tsx

@@ -52,7 +52,7 @@ configs({ directions: ['ltr'], modes: ['ionic-md'] }).forEach(({ title, screensh
             .container {
               padding: 20px 10px;
               /* Size is needed because tab bar compact has position absolute and will not capture correctly. */
-              width: 225px;
+              width: 100%;
               height: 96px;
             }
           </style>