refactor(promote): wrap banner content in inner container for click-through fix

Refactor the banner DOM structure to wrap all interactive elements in an inner
container, allowing the shell to have pointer-events:none while the inner
container re-enables pointer-events for interaction. This fixes click-through
issues where the banner was blocking interactions with page content below it.

Changes:
- Add docs-promote-banner__inner wrapper around all banner content
- Apply pointer-events:none to shell and pointer-events:auto to inner container
- Update hover and focus-within selectors to target inner container
- Add pointer-events restoration to shell for responsive breakpoints
- Update glow and sheen animations to apply to inner container
- Adjust responsive width constraints to inner container

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

Author: newbe36524

src/components/DocsPromoteInfoBanner.astro

@@ -42,52 +42,54 @@ const localizedText = currentLocale === 'en'
     hidden
     aria-label={localizedText.bannerLabel}
   >
-    <button
-      type="button"
-      class="docs-promote-banner__close"
-      data-promote-banner-close
-      aria-label={localizedText.closeLabel}
-    >
-      <span aria-hidden="true">×</span>
-    </button>
-
-    <div class="docs-promote-banner__viewport">
-      <div class="docs-promote-banner__track" data-promote-banner-track></div>
-    </div>
-
-    <div class="docs-promote-banner__controls">
-      <button
-        type="button"
-        class="docs-promote-banner__control"
-        data-promote-banner-previous
-        aria-label={localizedText.previousLabel}
-      >
-        <span aria-hidden="true">‹</span>
-      </button>
-
-      <span
-        class="docs-promote-banner__count"
-        data-promote-banner-count
-        aria-label={localizedText.countLabel}
-      ></span>
-
+    <div class="docs-promote-banner__inner">
       <button
         type="button"
-        class="docs-promote-banner__control"
-        data-promote-banner-next
-        aria-label={localizedText.nextLabel}
+        class="docs-promote-banner__close"
+        data-promote-banner-close
+        aria-label={localizedText.closeLabel}
       >
-        <span aria-hidden="true">›</span>
+        <span aria-hidden="true">×</span>
       </button>
 
-      <button
-        type="button"
-        class="docs-promote-banner__control docs-promote-banner__pause"
-        data-promote-banner-pause
-        aria-label={localizedText.pauseLabel}
-      >
-        {currentLocale === 'en' ? 'Pause' : '暂停'}
-      </button>
+      <div class="docs-promote-banner__viewport">
+        <div class="docs-promote-banner__track" data-promote-banner-track></div>
+      </div>
+
+      <div class="docs-promote-banner__controls">
+        <button
+          type="button"
+          class="docs-promote-banner__control"
+          data-promote-banner-previous
+          aria-label={localizedText.previousLabel}
+        >
+          <span aria-hidden="true">‹</span>
+        </button>
+
+        <span
+          class="docs-promote-banner__count"
+          data-promote-banner-count
+          aria-label={localizedText.countLabel}
+        ></span>
+
+        <button
+          type="button"
+          class="docs-promote-banner__control"
+          data-promote-banner-next
+          aria-label={localizedText.nextLabel}
+        >
+          <span aria-hidden="true">›</span>
+        </button>
+
+        <button
+          type="button"
+          class="docs-promote-banner__control docs-promote-banner__pause"
+          data-promote-banner-pause
+          aria-label={localizedText.pauseLabel}
+        >
+          {currentLocale === 'en' ? 'Pause' : '暂停'}
+        </button>
+      </div>
     </div>
 
     <span class="docs-promote-banner__status sr-only" data-promote-banner-status aria-live="polite">
@@ -135,6 +137,12 @@ const localizedText = currentLocale === 'en'
     inset-inline: 0;
     bottom: calc(1rem + var(--docs-promote-banner-bottom-offset));
     z-index: 40;
+    pointer-events: none;
+  }
+
+  .docs-promote-banner__inner {
+    position: relative;
+    pointer-events: auto;
     display: grid;
     grid-template-columns: minmax(0, 1fr) auto;
     align-items: center;
@@ -163,15 +171,15 @@ const localizedText = currentLocale === 'en'
     display: none !important;
   }
 
-  .docs-promote-banner__shell::before,
-  .docs-promote-banner__shell::after {
+  .docs-promote-banner__inner::before,
+  .docs-promote-banner__inner::after {
     content: '';
     position: absolute;
     pointer-events: none;
     z-index: 0;
   }
 
-  .docs-promote-banner__shell::before {
+  .docs-promote-banner__inner::before {
     inset-block-start: -8rem;
     inset-inline-start: -4rem;
     width: 20rem;
@@ -187,7 +195,7 @@ const localizedText = currentLocale === 'en'
     animation: docs-promote-banner-glow 11s ease-in-out infinite alternate;
   }
 
-  .docs-promote-banner__shell::after {
+  .docs-promote-banner__inner::after {
     inset: -24% auto -24% 42%;
     width: 42%;
     background: linear-gradient(
@@ -202,8 +210,8 @@ const localizedText = currentLocale === 'en'
     animation: docs-promote-banner-sheen 9s linear infinite;
   }
 
-  .docs-promote-banner__shell:hover,
-  .docs-promote-banner__shell:focus-within {
+  .docs-promote-banner__inner:hover,
+  .docs-promote-banner__inner:focus-within {
     transform: translateY(-2px);
     border-color: color-mix(in srgb, var(--sl-color-accent-high) 34%, var(--sl-color-white) 10%);
     box-shadow:
@@ -371,8 +379,8 @@ const localizedText = currentLocale === 'en'
     transform: translateY(-1px);
   }
 
-  .docs-promote-banner__shell:hover .docs-promote-banner__cta,
-  .docs-promote-banner__shell:focus-within .docs-promote-banner__cta {
+  .docs-promote-banner__inner:hover .docs-promote-banner__cta,
+  .docs-promote-banner__inner:focus-within .docs-promote-banner__cta {
     transform: translateX(2px);
   }
 
@@ -428,6 +436,10 @@ const localizedText = currentLocale === 'en'
 
   @media (max-width: 960px) {
     .docs-promote-banner__shell {
+      width: 100%;
+    }
+
+    .docs-promote-banner__inner {
       width: min(100vw - 1rem, 44rem);
       grid-template-columns: 1fr;
       gap: 0.75rem;
@@ -457,8 +469,12 @@ const localizedText = currentLocale === 'en'
 
   @media (max-width: 640px) {
     .docs-promote-banner__shell {
-      width: calc(100vw - 0.75rem);
       bottom: calc(0.5rem + var(--docs-promote-banner-bottom-offset));
+      width: 100%;
+    }
+
+    .docs-promote-banner__inner {
+      width: calc(100vw - 0.75rem);
       padding: 1rem 3.45rem 0.85rem 0.85rem;
       border-radius: 1rem;
     }
@@ -498,8 +514,8 @@ const localizedText = currentLocale === 'en'
 
     .docs-promote-banner__slide::before,
     .docs-promote-banner__slide::after,
-    .docs-promote-banner__shell::before,
-    .docs-promote-banner__shell::after {
+    .docs-promote-banner__inner::before,
+    .docs-promote-banner__inner::after {
       animation: none;
     }
   }

src/components/__tests__/DocsPromoteInfoBanner.test.tsx

@@ -54,6 +54,8 @@ function createMatchMedia(matches = false): MatchMediaResult {
 function createFetchMock(promotions: Array<{
   id: string;
   on?: boolean;
+  startTime?: string;
+  endTime?: string;
   titleZh: string;
   titleEn: string;
   descriptionZh: string;
@@ -78,12 +80,14 @@ function createFetchMock(promotions: Array<{
     }
 
     if (url.endsWith('/promote.json')) {
-      return new Response(JSON.stringify({
-        promotes: promotions.map((promotion) => ({
-          id: promotion.id,
-          on: promotion.on ?? true,
-        })),
-      }), { status: 200, headers: jsonHeaders });
+        return new Response(JSON.stringify({
+          promotes: promotions.map((promotion) => ({
+            id: promotion.id,
+            on: promotion.on ?? true,
+            startTime: promotion.startTime,
+            endTime: promotion.endTime,
+          })),
+        }), { status: 200, headers: jsonHeaders });
     }
 
     if (url.endsWith('/promote_content.json')) {
@@ -109,15 +113,17 @@ function renderBannerShell(locale = 'en') {
       <docs-promote-banner data-locale="${locale}" hidden>
         <div data-promote-banner-spacer></div>
         <section data-promote-banner-shell hidden>
-          <button type="button" data-promote-banner-close aria-label="${closeLabel}">×</button>
-          <div>
-            <div data-promote-banner-track></div>
-          </div>
-          <div>
-            <button type="button" data-promote-banner-previous aria-label="Show previous promotion">‹</button>
-            <span data-promote-banner-count></span>
-            <button type="button" data-promote-banner-next aria-label="Show next promotion">›</button>
-            <button type="button" data-promote-banner-pause aria-label="Pause automatic rotation">Pause</button>
+          <div class="docs-promote-banner__inner">
+            <button type="button" data-promote-banner-close aria-label="${closeLabel}">×</button>
+            <div>
+              <div data-promote-banner-track></div>
+            </div>
+            <div>
+              <button type="button" data-promote-banner-previous aria-label="Show previous promotion">‹</button>
+              <span data-promote-banner-count></span>
+              <button type="button" data-promote-banner-next aria-label="Show next promotion">›</button>
+              <button type="button" data-promote-banner-pause aria-label="Pause automatic rotation">Pause</button>
+            </div>
           </div>
           <span data-promote-banner-status aria-live="polite"></span>
         </section>
@@ -211,6 +217,7 @@ describe('DocsPromoteBannerController', () => {
 
   beforeEach(() => {
     vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-04-28T23:59:59+08:00'));
     Object.defineProperty(window, 'innerHeight', {
       configurable: true,
       value: 900,
@@ -247,6 +254,118 @@ describe('DocsPromoteBannerController', () => {
     expect(spacer.style.height).toBe('0px');
   });
 
+  it('keeps pre-start promotions hidden until a refresh crosses the start time', async () => {
+    const matchMedia = createMatchMedia(false);
+    vi.stubGlobal('matchMedia', vi.fn(() => matchMedia));
+    const { footer, root, shell } = renderBannerShell('en');
+
+    const controller = new DocsPromoteBannerController(root, {
+      footer,
+      fetchImpl: createFetchMock([
+        {
+          id: 'future',
+          startTime: '2026-04-29T00:00:00+08:00',
+          titleZh: '即将上线',
+          titleEn: 'Starts Soon',
+          descriptionZh: '预热中',
+          descriptionEn: 'Warming up',
+          link: 'https://example.invalid/future',
+          platform: 'steam',
+        },
+      ]) as typeof fetch,
+      refreshIntervalMs: 1000,
+    });
+
+    await controller.connect();
+
+    expect(root).toHaveAttribute('hidden');
+    expect(shell).toHaveAttribute('hidden');
+
+    vi.setSystemTime(new Date('2026-04-29T00:00:00+08:00'));
+    await (controller as unknown as { reloadPromotions: ({ forceRefresh }: { forceRefresh: boolean }) => Promise<void> })
+      .reloadPromotions({ forceRefresh: true });
+    (controller as unknown as { syncLayout: () => void }).syncLayout();
+
+    expect(root).not.toHaveAttribute('hidden');
+    expect(getActiveSlideTitle(root)).toBe('Starts Soon');
+  });
+
+  it('removes an expired promotion after refresh and hides the banner when no active entry remains', async () => {
+    const matchMedia = createMatchMedia(false);
+    vi.stubGlobal('matchMedia', vi.fn(() => matchMedia));
+    const { footer, root, shell } = renderBannerShell('en');
+
+    const controller = new DocsPromoteBannerController(root, {
+      footer,
+      fetchImpl: createFetchMock([
+        {
+          id: 'expires-now',
+          endTime: '2026-04-29T00:00:00+08:00',
+          titleZh: '即将结束',
+          titleEn: 'Ends Soon',
+          descriptionZh: '最后一刻',
+          descriptionEn: 'Last chance',
+          link: 'https://example.invalid/ends',
+          platform: 'steam',
+        },
+      ]) as typeof fetch,
+      refreshIntervalMs: 1000,
+    });
+
+    await controller.connect();
+
+    expect(root).not.toHaveAttribute('hidden');
+
+    vi.setSystemTime(new Date('2026-04-29T00:00:00+08:00'));
+    await vi.advanceTimersByTimeAsync(1000);
+
+    expect(root).toHaveAttribute('hidden');
+    expect(shell).toHaveAttribute('hidden');
+    expect(root.dataset.state).toBe('hidden');
+  });
+
+  it('swaps promotions at the exact boundary on refresh', async () => {
+    const matchMedia = createMatchMedia(false);
+    vi.stubGlobal('matchMedia', vi.fn(() => matchMedia));
+    const { footer, root } = renderBannerShell('en');
+
+    const controller = new DocsPromoteBannerController(root, {
+      footer,
+      fetchImpl: createFetchMock([
+        {
+          id: 'main-game-2026-04-29',
+          endTime: '2026-04-29T00:00:00+08:00',
+          titleZh: '愿望单',
+          titleEn: 'Wishlist Now',
+          descriptionZh: '旧推广',
+          descriptionEn: 'Old promotion',
+          link: 'https://example.invalid/wishlist',
+          platform: 'steam',
+        },
+        {
+          id: 'main-game-steam-ea-2026-04-29',
+          startTime: '2026-04-29T00:00:00+08:00',
+          titleZh: '抢先体验',
+          titleEn: 'Early Access Is Live',
+          descriptionZh: '新推广',
+          descriptionEn: 'New promotion',
+          link: 'https://example.invalid/ea',
+          platform: 'steam',
+        },
+      ]) as typeof fetch,
+      refreshIntervalMs: 1000,
+    });
+
+    await controller.connect();
+
+    expect(getActiveSlideTitle(root)).toBe('Wishlist Now');
+
+    vi.setSystemTime(new Date('2026-04-29T00:00:00+08:00'));
+    await vi.advanceTimersByTimeAsync(1000);
+
+    expect(getActiveSlideTitle(root)).toBe('Early Access Is Live');
+  });
+
   it('keeps the entire banner hidden when promotion fetch fails', async () => {
     const matchMedia = createMatchMedia(false);
     vi.stubGlobal('matchMedia', vi.fn(() => matchMedia));