refactor(promote-banner): improve footer interaction and visibility states

Refactor banner visibility logic to use explicit state management instead
of CSS offset calculations. Hide banner completely while footer is visible
and restore it smoothly after scrolling away.

Changes:
- Add footer-hidden state with opacity and visibility transitions
- Remove bottom-offset CSS variable in favor of ARIA attributes
- Pause rotation timer while footer-hidden to prevent unnecessary updates
- Add inert attribute and blur active element when footer overlaps
- Update tests to verify footer-hidden behavior and state persistence
- Ensure dismissed banner remains hidden regardless of footer state

Co-Authored-By: Hagicode <noreply@hagicode.com>
Signed-off-by: newbe36524 <newbe36524@qq.com>

Author: newbe36524

src/components/DocsPromoteInfoBanner.astro

@@ -139,7 +139,6 @@ const localizedText = currentLocale === 'en'
 
   .docs-promote-banner__shell {
     --docs-promote-banner-base-bottom: max(1rem, env(safe-area-inset-bottom));
-    --docs-promote-banner-bottom-offset: 0px;
     --docs-promote-banner-border: color-mix(in srgb, var(--sl-color-accent) 24%, var(--sl-color-gray-5));
     --docs-promote-banner-surface:
       linear-gradient(
@@ -163,9 +162,14 @@ const localizedText = currentLocale === 'en'
     --docs-promote-banner-count-color: color-mix(in srgb, var(--sl-color-white) 70%, var(--sl-color-gray-3));
     position: fixed;
     inset-inline: 0;
-    bottom: calc(var(--docs-promote-banner-base-bottom) + var(--docs-promote-banner-bottom-offset));
+    bottom: var(--docs-promote-banner-base-bottom);
     z-index: 40;
     pointer-events: none;
+    opacity: 1;
+    visibility: visible;
+    transition:
+      opacity 0.24s ease,
+      visibility 0s linear 0s;
   }
 
   [data-theme='light'] .docs-promote-banner__shell {
@@ -216,18 +220,33 @@ const localizedText = currentLocale === 'en'
     box-shadow: var(--docs-promote-banner-shadow);
     backdrop-filter: blur(18px);
     transition:
+      opacity 0.24s ease,
       transform 0.2s ease,
       border-color 0.2s ease,
       box-shadow 0.2s ease;
   }
 
-  .docs-promote-banner__inner:hover,
-  .docs-promote-banner__inner:focus-within {
+  .docs-promote-banner-host:not([data-state='footer-hidden']) .docs-promote-banner__inner:hover,
+  .docs-promote-banner-host:not([data-state='footer-hidden']) .docs-promote-banner__inner:focus-within {
     transform: translateY(-2px);
     border-color: color-mix(in srgb, var(--sl-color-accent-high) 32%, var(--docs-promote-banner-border));
     box-shadow: 0 28px 86px color-mix(in srgb, var(--sl-color-black) 26%, transparent);
   }
 
+  .docs-promote-banner-host[data-state='footer-hidden'] .docs-promote-banner__shell {
+    opacity: 0;
+    visibility: hidden;
+    transition:
+      opacity 0.24s ease,
+      visibility 0s linear 0.24s;
+  }
+
+  .docs-promote-banner-host[data-state='footer-hidden'] .docs-promote-banner__inner {
+    pointer-events: none;
+    opacity: 0;
+    transform: translateY(0.5rem);
+  }
+
   .docs-promote-banner__close {
     position: absolute;
     inset-block-start: 0.85rem;

src/components/__tests__/DocsPromoteInfoBanner.test.tsx

@@ -339,7 +339,7 @@ describe('DocsPromoteBannerController', () => {
     expect(root.querySelector('[data-promote-banner-controls]')).toHaveAttribute('hidden');
   });
 
-  it('keeps the banner visible on ordinary Starlight page shells and docks above the footer instead of hiding', async () => {
+  it('hides the banner while the footer is visible and restores it after scrolling away', async () => {
     const matchMedia = createMatchMedia(false);
     vi.stubGlobal('matchMedia', vi.fn(() => matchMedia));
     const { footer, root, shell } = renderBannerShell({
@@ -362,14 +362,57 @@ describe('DocsPromoteBannerController', () => {
     expect(root).not.toHaveAttribute('hidden');
     expect(root.dataset.mode).toBe('fallback');
     expect(root.dataset.state).toBe('ready');
-    expect(shell.style.getPropertyValue('--docs-promote-banner-bottom-offset')).toBe('0px');
+    expect(getActiveSlideTitle(root)).toBe('Explore the HagiCode Product Overview');
+    expect(shell.style.getPropertyValue('--docs-promote-banner-bottom-offset')).toBe('');
 
     setFooterRect(footer, 760);
     syncLayout(controller);
 
     expect(root).not.toHaveAttribute('hidden');
-    expect(root.dataset.state).toBe('docked');
-    expect(shell.style.getPropertyValue('--docs-promote-banner-bottom-offset')).toBe('140px');
+    expect(root.dataset.state).toBe('footer-hidden');
+    expect(shell).toHaveAttribute('aria-hidden', 'true');
+    expect(shell).toHaveAttribute('inert');
+    expect(shell.style.getPropertyValue('--docs-promote-banner-bottom-offset')).toBe('');
+
+    setFooterRect(footer, 1200);
+    syncLayout(controller);
+
+    expect(root).not.toHaveAttribute('hidden');
+    expect(root.dataset.state).toBe('ready');
+    expect(shell).not.toHaveAttribute('aria-hidden');
+    expect(shell).not.toHaveAttribute('inert');
+    expect(getActiveSlideTitle(root)).toBe('Explore the HagiCode Product Overview');
+  });
+
+  it('keeps the dismissed banner hidden when footer visibility changes for the same promotion set', async () => {
+    const matchMedia = createMatchMedia(false);
+    vi.stubGlobal('matchMedia', vi.fn(() => matchMedia));
+    const { footer, root } = renderBannerShell({
+      locale: 'en',
+      path: '/en/product-overview/',
+    });
+
+    const controller = new DocsPromoteBannerController(root, {
+      footer,
+      fetchImpl: createFetchMock([]) as typeof fetch,
+      refreshIntervalMs: 60_000,
+    });
+
+    await controller.connect();
+    fireEvent.click(screen.getByRole('button', { name: 'Dismiss promotion message' }));
+
+    expect(root).toHaveAttribute('hidden');
+    expect(root.dataset.state).toBe('dismissed');
+
+    setFooterRect(footer, 760);
+    syncLayout(controller);
+    expect(root).toHaveAttribute('hidden');
+    expect(root.dataset.state).toBe('dismissed');
+
+    setFooterRect(footer, 1200);
+    syncLayout(controller);
+    expect(root).toHaveAttribute('hidden');
+    expect(root.dataset.state).toBe('dismissed');
   });
 
   it('keeps fallback dismissal persisted for the same payload but allows a later remote promotion to reappear', async () => {
@@ -474,6 +517,60 @@ describe('DocsPromoteBannerController', () => {
     expect(screen.getByText('2 / 2')).toBeInTheDocument();
   });
 
+  it('pauses automatic rotation while footer-hidden and resumes after the footer leaves the viewport', async () => {
+    const matchMedia = createMatchMedia(false);
+    vi.stubGlobal('matchMedia', vi.fn(() => matchMedia));
+    const { footer, root } = renderBannerShell({
+      locale: 'en',
+      path: '/en/guides/skills/',
+    });
+
+    const controller = new DocsPromoteBannerController(root, {
+      footer,
+      fetchImpl: createFetchMock([
+        {
+          id: 'main-game',
+          titleZh: '立即添加到愿望单',
+          titleEn: 'Wishlist Now',
+          descriptionZh: '游戏将于 2026-04-29 发售，立即前往 Steam 添加愿望单。',
+          descriptionEn: 'Coming April 29, 2026. Add to your Steam wishlist now!',
+          link: 'https://store.steampowered.com/app/4625540/Hagicode/',
+          platform: 'steam',
+        },
+        {
+          id: 'builder',
+          titleZh: '体验部署生成器',
+          titleEn: 'Try the Builder',
+          descriptionZh: '使用 Docker Compose Builder 快速生成部署配置。',
+          descriptionEn: 'Generate Docker Compose deployment files with the Builder.',
+          link: 'https://builder.hagicode.com/',
+          platform: 'web',
+        },
+      ]) as typeof fetch,
+      rotationIntervalMs: 1000,
+      refreshIntervalMs: 60_000,
+    });
+
+    await controller.connect();
+
+    expect(getActiveSlideTitle(root)).toBe('Wishlist Now');
+    setFooterRect(footer, 760);
+    syncLayout(controller);
+    expect(root.dataset.state).toBe('footer-hidden');
+
+    await vi.advanceTimersByTimeAsync(2000);
+    expect(getActiveSlideTitle(root)).toBe('Wishlist Now');
+    expect(screen.getByText('1 / 2')).toBeInTheDocument();
+
+    setFooterRect(footer, 1200);
+    syncLayout(controller);
+    expect(root.dataset.state).toBe('ready');
+
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(getActiveSlideTitle(root)).toBe('Try the Builder');
+    expect(screen.getByText('2 / 2')).toBeInTheDocument();
+  });
+
   it('supports pause and resume while automatic rotation is available', async () => {
     const matchMedia = createMatchMedia(false);
     vi.stubGlobal('matchMedia', vi.fn(() => matchMedia));

src/lib/docs-promote-banner.ts

@@ -48,6 +48,8 @@ export interface DocsPromoteBannerControllerOptions extends LoadActivePromotions
   refreshIntervalMs?: number;
 }
 
+type BannerVisibilityState = 'dismissed' | 'footer-hidden' | 'hidden' | 'ready';
+
 function defaultBadgeText(locale: PromoteLocale): string {
   return locale === 'en' ? 'Promoted' : '推荐';
 }
@@ -590,10 +592,13 @@ export class DocsPromoteBannerController {
   private syncRotationTimer(): void {
     this.stopRotationTimer();
 
+    const visibilityState = this.getVisibilityState();
+
     if (
       this.promotions.length < 2 ||
       this.isPaused ||
-      this.prefersReducedMotion
+      this.prefersReducedMotion ||
+      visibilityState !== 'ready'
     ) {
       return;
     }
@@ -659,15 +664,6 @@ export class DocsPromoteBannerController {
     }
 
     this.setSpacerHeight(0);
-
-    let bottomOffset = 0;
-    if (this.footer) {
-      const footerRect = this.footer.getBoundingClientRect();
-      bottomOffset = Math.max(window.innerHeight - footerRect.top, 0);
-      bottomOffset = Math.min(bottomOffset, footerRect.height);
-    }
-
-    this.shell.style.setProperty('--docs-promote-banner-bottom-offset', `${bottomOffset}px`);
     this.syncRotationTimer();
   }
 
@@ -691,29 +687,59 @@ export class DocsPromoteBannerController {
   }
 
   private applyVisibilityState(): boolean {
-    const hasPromotions = this.promotions.length > 0;
-    const dismissed = this.isCurrentPromotionDismissed();
-    const footerVisible = this.isFooterVisible();
-    const shouldShow = hasPromotions && !dismissed;
+    const visibilityState = this.getVisibilityState();
+    const shouldShow = visibilityState === 'ready' || visibilityState === 'footer-hidden';
+    const footerHidden = visibilityState === 'footer-hidden';
 
     setElementHidden(this.root, !shouldShow);
     setElementHidden(this.shell, !shouldShow);
     setElementHidden(this.spacer, !shouldShow);
     this.root.dataset.mode = this.promotions[0]?.source ?? 'hidden';
-    this.root.dataset.state = shouldShow
-      ? (footerVisible ? 'docked' : 'ready')
-      : dismissed
-        ? 'dismissed'
-        : 'hidden';
+    this.root.dataset.state = visibilityState;
+    this.syncFooterHiddenState(footerHidden);
 
     if (!shouldShow) {
       this.setSpacerHeight(0);
-      this.shell?.style.removeProperty('--docs-promote-banner-bottom-offset');
     }
 
     return shouldShow;
   }
 
+  private syncFooterHiddenState(footerHidden: boolean): void {
+    if (!this.shell) {
+      return;
+    }
+
+    if (footerHidden) {
+      this.shell.setAttribute('aria-hidden', 'true');
+      this.shell.setAttribute('inert', '');
+
+      if (
+        document.activeElement instanceof HTMLElement &&
+        this.shell.contains(document.activeElement)
+      ) {
+        document.activeElement.blur();
+      }
+
+      return;
+    }
+
+    this.shell.removeAttribute('aria-hidden');
+    this.shell.removeAttribute('inert');
+  }
+
+  private getVisibilityState(): BannerVisibilityState {
+    if (this.promotions.length === 0) {
+      return 'hidden';
+    }
+
+    if (this.isCurrentPromotionDismissed()) {
+      return 'dismissed';
+    }
+
+    return this.isFooterVisible() ? 'footer-hidden' : 'ready';
+  }
+
   private isFooterVisible(): boolean {
     if (!this.footer) {
       return false;