@ionic/core 8.8.16-dev.11784841344.1aa1a41c → 8.8.16-dev.11784914346.10d0804c

package/dist/collection/components/header/header.ios.css

@@ -9,6 +9,159 @@ ion-header ion-toolbar:first-of-type {
   padding-top: var(--ion-safe-area-top, 0);
 }
 
+.header-collapse-fade ion-toolbar {
+  --opacity-scale: inherit;
+}
+
+/**
+ * Override styles applied during the page transition to prevent
+ * header flickering.
+ */
+.header-collapse-fade.header-transitioning ion-toolbar {
+  --background: transparent;
+  --border-style: none;
+}
+
+.header-collapse-condense {
+  z-index: 9;
+}
+
+.header-collapse-condense ion-toolbar {
+  position: sticky;
+  top: 0;
+}
+
+.header-collapse-condense ion-toolbar:first-of-type {
+  /**
+   * The toolbar that contains the collapsible
+   * large title should not have safe area padding applied.
+   */
+  padding-top: 0px;
+  z-index: 1;
+}
+
+/**
+ * Large title toolbar should just use the content background
+ * since it needs to blend in with the header above it.
+ */
+.header-collapse-condense ion-toolbar {
+  z-index: 0;
+}
+
+.header-collapse-condense ion-toolbar:last-of-type {
+  --border-width: 0px;
+}
+
+.header-collapse-condense ion-toolbar ion-searchbar {
+  padding-top: 0px;
+  padding-bottom: 13px;
+}
+
+.header-collapse-main {
+  --opacity-scale: 1;
+}
+
+.header-collapse-main ion-toolbar {
+  --opacity-scale: inherit;
+}
+
+.header-collapse-main ion-toolbar.in-toolbar ion-title,
+.header-collapse-main ion-toolbar.in-toolbar ion-buttons {
+  transition: all 0.2s ease-in-out;
+}
+
+/**
+ * Large title toolbar should just use the content background
+ * since it needs to blend in with the header above it.
+ */
+.header-collapse-condense ion-toolbar,
+.header-collapse-condense-inactive.header-transitioning:not(.header-collapse-condense) ion-toolbar {
+  --background: var(--ion-background-color, #fff);
+}
+
+/**
+ * Override styles applied during the page transition to prevent
+ * header flickering.
+ */
+.header-collapse-condense-inactive.header-transitioning:not(.header-collapse-condense) ion-toolbar {
+  --border-style: none;
+  --opacity-scale: 1;
+}
+
+.header-collapse-condense-inactive:not(.header-collapse-condense) ion-toolbar.in-toolbar ion-title,
+.header-collapse-condense-inactive:not(.header-collapse-condense) ion-toolbar.in-toolbar ion-buttons.buttons-collapse {
+  opacity: 0;
+  pointer-events: none;
+}
+
+/**
+ * There is a bug in Safari where changing
+ * the opacity of an element in a scrollable container
+ * while rubber-banding causes the scroll position
+ * to jump to the top
+ */
+.header-collapse-condense-inactive.header-collapse-condense ion-toolbar.in-toolbar ion-title,
+.header-collapse-condense-inactive.header-collapse-condense ion-toolbar.in-toolbar ion-buttons.buttons-collapse {
+  visibility: hidden;
+}
+
+/**
+ * The main header is only hidden once the collapsible large
+ * title is configured. As a result, if the main header loads
+ * before the collapsible large title is configured then the
+ * main header will be visible briefly before being hidden
+ * by the collapsible large title.
+ *
+ * The following selector ensures that any main header
+ * on a page with a collapsible large title is hidden
+ * before the collapsible large title is configured.
+ * Once the collapsible large title is configured the main
+ * header will have the ".header-collapse-main" class, and
+ * this selector will no longer apply.
+ *
+ * The :has(...) part of the selector ensures a couple things:
+ * 1. This will only apply within a page view since the content
+ * must be a subsequent-sibling of the header (~ ion-content).
+ * 2. This will only apply when that content has an active condense
+ *    header (the .header-collapse-condense class).
+ *
+ * We use opacity: 0 to avoid a layout shift.
+ * We use the class (not the attribute) because the class is only
+ * added when the condense effect is valid (large title present).
+ * The attribute alone is not sufficient since it would match even
+ * when the effect is guarded (e.g. no large title).
+ */
+ion-header:not(.header-collapse-main):has(~ ion-content ion-header.header-collapse-condense) {
+  opacity: 0;
+}
+
+/**
+ * The deprecated collapse="condense" prop is iOS-only.
+ * On non-iOS themes, the condense header should be hidden since
+ * the JS won't activate it. Uses a class instead of an attribute
+ * selector because collapse is not a reflected prop, and framework
+ * proxies (Angular/Vue) bind it as a property.
+ */
+.header-collapse-condense-hidden {
+  display: none;
+}
+
+ion-header.header-scroll-effect-hide {
+  transition: transform 300ms cubic-bezier(0, 0, 0.2, 1), opacity 300ms cubic-bezier(0, 0, 0.2, 1);
+}
+
+ion-header.header-scroll-effect-hide.header-scroll-hidden {
+  transform: translateY(-100%);
+  transition: transform 200ms cubic-bezier(0.4, 0, 1, 1), opacity 300ms cubic-bezier(0.4, 0, 1, 1);
+  opacity: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  ion-header.header-scroll-effect-hide,
+  ion-header.header-scroll-effect-hide.header-scroll-hidden {
+    transition: none;
+  }
+}
 /**
  * Convert a pixels given value into rem
  * 
@@ -163,129 +316,6 @@ ion-header {
   --border-width: 0;
 }
 
-.header-collapse-fade ion-toolbar {
-  --opacity-scale: inherit;
-}
-
-/**
- * Override styles applied during the page transition to prevent
- * header flickering.
- */
-.header-collapse-fade.header-transitioning ion-toolbar {
-  --background: transparent;
-  --border-style: none;
-}
-
-.header-collapse-condense {
-  z-index: 9;
-}
-
-.header-collapse-condense ion-toolbar {
-  position: sticky;
-  top: 0;
-}
-
-.header-collapse-condense ion-toolbar:first-of-type {
-  /**
-   * The toolbar that contains the collapsible
-   * large title should not have safe area padding applied.
-   */
-  padding-top: 0px;
-  z-index: 1;
-}
-
-/**
- * Large title toolbar should just use the content background
- * since it needs to blend in with the header above it.
- */
-.header-collapse-condense ion-toolbar {
-  z-index: 0;
-}
-
 .header-collapse-condense ion-toolbar:last-of-type {
   --border-width: 0px;
-}
-
-.header-collapse-condense ion-toolbar ion-searchbar {
-  padding-top: 0px;
-  padding-bottom: 13px;
-}
-
-.header-collapse-main {
-  --opacity-scale: 1;
-}
-
-.header-collapse-main ion-toolbar {
-  --opacity-scale: inherit;
-}
-
-.header-collapse-main ion-toolbar.in-toolbar ion-title,
-.header-collapse-main ion-toolbar.in-toolbar ion-buttons {
-  transition: all 0.2s ease-in-out;
-}
-
-/**
- * Large title toolbar should just use the content background
- * since it needs to blend in with the header above it.
- */
-.header-collapse-condense ion-toolbar,
-.header-collapse-condense-inactive.header-transitioning:not(.header-collapse-condense) ion-toolbar {
-  --background: var(--ion-background-color, #fff);
-}
-
-/**
- * Override styles applied during the page transition to prevent
- * header flickering.
- */
-.header-collapse-condense-inactive.header-transitioning:not(.header-collapse-condense) ion-toolbar {
-  --border-style: none;
-  --opacity-scale: 1;
-}
-
-.header-collapse-condense-inactive:not(.header-collapse-condense) ion-toolbar.in-toolbar ion-title,
-.header-collapse-condense-inactive:not(.header-collapse-condense) ion-toolbar.in-toolbar ion-buttons.buttons-collapse {
-  opacity: 0;
-  pointer-events: none;
-}
-
-/**
- * There is a bug in Safari where changing
- * the opacity of an element in a scrollable container
- * while rubber-banding causes the scroll position
- * to jump to the top
- */
-.header-collapse-condense-inactive.header-collapse-condense ion-toolbar.in-toolbar ion-title,
-.header-collapse-condense-inactive.header-collapse-condense ion-toolbar.in-toolbar ion-buttons.buttons-collapse {
-  visibility: hidden;
-}
-
-/**
- * The main header is only hidden once the collapsible large
- * title is configured. As a result, if the main header loads
- * before the collapsible large title is configured then the
- * main header will be visible briefly before being hidden
- * by the collapsible large title.
- *
- * The following selector ensures that any main header
- * on a page with a collapsible large title is hidden
- * before the collapsible large title is configured.
- * Once the collapsible large title is configured the main
- * header will have the ".header-collapse-main" class, and
- * this selector will no longer apply.
- *
- * The :has(...) part of the selector ensures a couple things:
- * 1. This will only apply within a page view since the content
- * must be a subsequent-sibling of the header (~ ion-content).
- * 2. This will only apply when that content has a collapse header (ion-header[collapse="condense"])
- *
- * We use opacity: 0 to avoid a layout shift.
- * We target both the attribute and the class in the event that the attribute
- * is not reflected on the host in some frameworks.
- *
- * Both headers should be scoped to iOS mode otherwise an MD app that uses an
- * iOS header may cause other MD headers to be unexpectedly hidden.
- */
-ion-header.header-ios:not(.header-collapse-main):has(~ ion-content ion-header.header-ios[collapse=condense],
-~ ion-content ion-header.header-ios.header-collapse-condense) {
-  opacity: 0;
 }

package/dist/collection/components/header/header.js

@@ -4,6 +4,8 @@
 import { Host, h, writeTask } from "@stencil/core";
 import { findIonContent, getScrollElement, printIonContentErrorMsg } from "../../utils/content/index";
 import { inheritAriaAttributes } from "../../utils/helpers";
+import { printIonWarning } from "../../utils/logging/index";
+import { createScrollHideController } from "../../utils/scroll-hide-controller";
 import { hostContext } from "../../utils/theme";
 import { config } from "../../global/config";
 import { getIonTheme } from "../../global/ionic-global";
@@ -15,6 +17,9 @@ import { cloneElement, createHeaderIndex, handleContentScroll, handleHeaderFade,
 export class Header {
     constructor() {
         this.inheritedAttributes = {};
+        this.scrollHideCtrlPromise = null;
+        this.hasWarnedCollapse = false;
+        this.fadeCondenseSetupId = 0;
         /**
          * If `true`, the header will have a line at the bottom.
          * TODO(ROU-10855): add support for this prop on ios/md themes
@@ -29,8 +34,29 @@ export class Header {
          * attribute needs to be set on the content.
          */
         this.translucent = false;
+        this.setupScrollEffectHide = async (contentEl) => {
+            const setupPromise = createScrollHideController(contentEl, {
+                el: this.el,
+                cssVar: '--internal-header-hide-height',
+                hiddenClass: 'header-scroll-hidden',
+                contentPartnerClass: 'content-header-hide-scroll-partner',
+                contentHiddenClass: 'content-header-hide-scroll-hidden',
+            });
+            this.scrollHideCtrlPromise = setupPromise;
+            const controller = await setupPromise;
+            if (this.scrollHideCtrlPromise === setupPromise) {
+                this.scrollHideCtrlPromise = null;
+                controller.init();
+                this.scrollHideCtrl = controller;
+            }
+        };
         this.setupFadeHeader = async (contentEl, condenseHeader) => {
-            const scrollEl = (this.scrollEl = await getScrollElement(contentEl));
+            const setupId = ++this.fadeCondenseSetupId;
+            const scrollEl = await getScrollElement(contentEl);
+            if (this.fadeCondenseSetupId !== setupId) {
+                return;
+            }
+            this.scrollEl = scrollEl;
             /**
              * Handle fading of toolbars on scroll
              */
@@ -54,38 +80,63 @@ export class Header {
         this.destroyCollapsibleHeader();
     }
     async checkCollapsibleHeader() {
-        const theme = getIonTheme(this);
-        if (theme !== 'ios') {
+        const { scrollEffect, collapse } = this;
+        if (collapse !== undefined && scrollEffect === undefined && !this.hasWarnedCollapse) {
+            this.hasWarnedCollapse = true;
+            printIonWarning(`[ion-header] - The \`collapse\` property is deprecated. Use \`scrollEffect\` instead.\nExample: <ion-header scroll-effect="${collapse}">`, this.el);
+        }
+        const effect = scrollEffect !== null && scrollEffect !== void 0 ? scrollEffect : collapse;
+        // Skip teardown/rebuild if the effect hasn't changed.
+        // This prevents re-renders from destroying the scroll controller
+        // and resetting isHidden.
+        if (effect === this.activeEffect) {
             return;
         }
-        const { collapse } = this;
-        const hasCondense = collapse === 'condense';
-        const hasFade = collapse === 'fade';
+        const hasHide = effect === 'hide';
+        const hasCondense = effect === 'condense';
+        const hasFade = effect === 'fade';
         this.destroyCollapsibleHeader();
         const appRootSelector = config.get('appRootSelector', 'ion-app');
-        if (hasCondense) {
-            const pageEl = this.el.closest(`${appRootSelector},ion-page,.ion-page,page-inner`);
-            const contentEl = pageEl ? findIonContent(pageEl) : null;
+        const pageEl = this.el.closest(`${appRootSelector}, ion-page, .ion-page, page-inner`);
+        const contentEl = pageEl ? findIonContent(pageEl) : null;
+        if (hasHide && contentEl) {
+            this.activeEffect = effect;
+            await this.setupScrollEffectHide(contentEl);
+            return;
+        }
+        // condense/fade via the deprecated `collapse` prop are iOS-only.
+        // condense/fade via the new `scrollEffect` prop work in all themes.
+        const isModeRestricted = scrollEffect === undefined && getIonTheme(this) !== 'ios';
+        if (hasCondense && !isModeRestricted) {
             // Cloned elements are always needed in iOS transition
             writeTask(() => {
                 const title = cloneElement('ion-title');
                 title.size = 'large';
                 cloneElement('ion-back-button');
             });
-            await this.setupCondenseHeader(contentEl, pageEl);
+            const didSetup = await this.setupCondenseHeader(contentEl, pageEl);
+            if (didSetup) {
+                this.activeEffect = effect;
+            }
         }
-        else if (hasFade) {
-            const pageEl = this.el.closest(`${appRootSelector},ion-page,.ion-page,page-inner`);
-            const contentEl = pageEl ? findIonContent(pageEl) : null;
+        else if (hasFade && !isModeRestricted) {
             if (!contentEl) {
                 printIonContentErrorMsg(this.el);
                 return;
             }
-            const condenseHeader = contentEl.querySelector('ion-header[collapse="condense"]');
+            const condenseHeader = contentEl.querySelector('ion-header[collapse="condense"],ion-header[scroll-effect="condense"]');
+            this.activeEffect = effect;
             await this.setupFadeHeader(contentEl, condenseHeader);
         }
     }
     destroyCollapsibleHeader() {
+        this.activeEffect = undefined;
+        this.fadeCondenseSetupId++;
+        this.scrollHideCtrlPromise = null;
+        if (this.scrollHideCtrl) {
+            this.scrollHideCtrl.destroy();
+            this.scrollHideCtrl = undefined;
+        }
         if (this.intersectionObserver) {
             this.intersectionObserver.disconnect();
             this.intersectionObserver = undefined;
@@ -102,21 +153,40 @@ export class Header {
     async setupCondenseHeader(contentEl, pageEl) {
         if (!contentEl || !pageEl) {
             printIonContentErrorMsg(this.el);
-            return;
+            return false;
         }
         if (typeof IntersectionObserver === 'undefined') {
-            return;
+            return false;
+        }
+        const setupId = ++this.fadeCondenseSetupId;
+        const scrollEl = await getScrollElement(contentEl);
+        if (this.fadeCondenseSetupId !== setupId) {
+            return false;
+        }
+        this.scrollEl = scrollEl;
+        /**
+         * The condense effect requires an ion-title with size="large"
+         * in the condense header. Without it, there is nothing to
+         * collapse into the main header toolbar.
+         */
+        const hasLargeTitle = this.el.querySelector('ion-title[size="large"]') !== null;
+        if (!hasLargeTitle) {
+            printIonWarning('[ion-header] - The condense scroll effect requires an <ion-title size="large"> in the condense header.', this.el);
+            return false;
         }
-        this.scrollEl = await getScrollElement(contentEl);
         const headers = pageEl.querySelectorAll('ion-header');
-        this.collapsibleMainHeader = Array.from(headers).find((header) => header.collapse !== 'condense');
+        this.collapsibleMainHeader = Array.from(headers).find((header) => {
+            var _a;
+            const effect = (_a = header.scrollEffect) !== null && _a !== void 0 ? _a : header.collapse;
+            return effect !== 'condense';
+        });
         if (!this.collapsibleMainHeader) {
-            return;
+            return false;
         }
         const mainHeaderIndex = createHeaderIndex(this.collapsibleMainHeader);
         const scrollHeaderIndex = createHeaderIndex(this.el);
         if (!mainHeaderIndex || !scrollHeaderIndex) {
-            return;
+            return false;
         }
         setHeaderActive(mainHeaderIndex, false);
         setToolbarBackgroundOpacity(mainHeaderIndex.el, 0);
@@ -148,23 +218,35 @@ export class Header {
                 this.collapsibleMainHeader.classList.add('header-collapse-main');
             }
         });
+        return true;
     }
     render() {
-        const { translucent, inheritedAttributes, divider } = this;
+        const { translucent, inheritedAttributes, divider, scrollEffect, collapse } = this;
         const theme = getIonTheme(this);
-        const collapse = this.collapse || 'none';
-        const isCondensed = collapse === 'condense';
+        const effect = scrollEffect !== null && scrollEffect !== void 0 ? scrollEffect : collapse;
+        // condense/fade via the deprecated `collapse` prop are iOS-only.
+        const isModeRestricted = scrollEffect === undefined && theme !== 'ios';
+        const hasHide = effect === 'hide';
+        const hasCondense = effect === 'condense' && !isModeRestricted && this.el.querySelector('ion-title[size="large"]') !== null;
+        const hasFade = effect === 'fade' && !isModeRestricted;
+        // The condense header should be hidden when
+        // - deprecated collapse prop is used on non-iOS (mode restricted), or
+        // - scrollEffect="condense" is set but no ion-title[size="large"] is present
+        const isHiddenCondense = effect === 'condense' && !hasCondense;
         // banner role must be at top level, so remove role if inside a menu
-        const roleType = getRoleType(hostContext('ion-menu', this.el), isCondensed, theme);
-        return (h(Host, Object.assign({ key: '3395dedfd5165ba6e9f3ad1a25f0bb5b3678704a', role: roleType, class: {
+        const roleType = isHiddenCondense ? 'none' : getRoleType(hostContext('ion-menu', this.el));
+        return (h(Host, Object.assign({ key: '09f60ca014bb7b3a85d3c0a94e7989d5dbc43f46', role: roleType, class: {
                 [theme]: true,
                 // Used internally for styling
                 [`header-${theme}`]: true,
                 [`header-translucent`]: this.translucent,
-                [`header-collapse-${collapse}`]: true,
+                ['header-collapse-condense']: hasCondense,
+                ['header-collapse-condense-hidden']: isHiddenCondense,
+                ['header-collapse-fade']: hasFade,
                 [`header-translucent-${theme}`]: this.translucent,
                 ['header-divider']: divider,
-            } }, inheritedAttributes), theme !== 'md' && translucent && h("div", { key: 'cafeb88b6e73d64b264514ea46590fd3477b3052', class: "header-background" }), h("slot", { key: 'ad681aaf866d7e7a5e5e731c0b5d6f5cc9fe94d2' })));
+                'header-scroll-effect-hide': hasHide,
+            } }, inheritedAttributes), theme !== 'md' && translucent && h("div", { key: 'fd5ff245ae0166e5e1d50936cacc98c90625db48', class: "header-background" }), h("slot", { key: '1baa31af87b9eb6406a21073ec65afa191dfbb3d' })));
     }
     static get is() { return "ion-header"; }
     static get originalStyleUrls() {
@@ -183,6 +265,32 @@ export class Header {
     }
     static get properties() {
         return {
+            "scrollEffect": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "HeaderScrollEffect",
+                    "resolved": "\"condense\" | \"fade\" | \"hide\" | undefined",
+                    "references": {
+                        "HeaderScrollEffect": {
+                            "location": "import",
+                            "path": "./header-interface",
+                            "id": "src/components/header/header-interface.ts::HeaderScrollEffect",
+                            "referenceLocation": "HeaderScrollEffect"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Describes the scroll effect that will be applied to the header.\n`\"hide\"` slides the header out of view when scrolling down and back in\nwhen scrolling up.\n`\"condense\"` collapses the large title into the main toolbar on scroll.\n`\"fade\"` fades the toolbar background on scroll."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "scroll-effect"
+            },
             "collapse": {
                 "type": "string",
                 "mutable": false,
@@ -194,7 +302,10 @@ export class Header {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `scrollEffect` instead."
+                        }],
                     "text": "Describes the scroll effect that will be applied to the header.\nOnly applies when the theme is `\"ios\"`.\n\nTypically used for [Collapsible Large Titles](https://ionicframework.com/docs/api/title#collapsible-large-titles)"
                 },
                 "getter": false,