Fix sam-datepicker-v2 outside-click close and tabindex/aria-hidden restore leak

[fpigeonjr]

Description

experimental/date-range-v2/datepicker/picker.component.ts had two entangled
defects that had to be fixed together (fixing either alone regresses the
other):

1. calendarpopup never resolves, so outside-click-to-close is dead code.
   @ViewChild("calendarpopup", { static: true }) targeted an element inside
   an *ngIf="showCalendar" block. A static query resolves once, before the
   first change-detection run, while showCalendar is still false — so
   calendarpopup stayed undefined forever. handleGlobalClick guards on
   this.calendarpopup, so its whole body — including
   enablePageTabIndex(), which restores the tabindex/aria-hidden
   attributes disablePageTabIndex() strips from every focusable element on
   the page when the calendar opens — was unreachable. Opening the calendar
   and clicking away left the rest of the page permanently unfocusable and
   hidden from screen readers.

   Fix: changed the @ViewChild to non-static (the default), so it resolves
   once the *ngIf-gated element actually renders.

2. Strict target comparison treats the icon's own child as an outside
   click. handleGlobalClick compared
   this.calendarButton.nativeElement !== event.target. The calendar
   button contains a .sr-only child span; a real mouse click at the
   icon's centre lands on that child, not on #calendarButton itself, so
   strict inequality treated the button's own child as an outside click.
   This was latent while defect 1 masked it, but once calendarpopup
   resolves, the opening click immediately closes the calendar again in
   the same event — the picker becomes unopenable by mouse (keyboard Enter
   still worked, since it dispatches no click).

   Fix: changed the comparison to containment —
   !this.calendarButton.nativeElement.contains(event.target).

Also un-skipped the two picker.spec.ts specs that were blocked on this fix
(should close the calendar when clicking outside of it,
should not close the calendar when clicking the calendar button) and
replaced their stale "why this is skipped" comments with real assertions —
the second spec previously passed only vacuously, because the guard on
this.calendarpopup always early-returned.

Since jsdom has no layout engine to hit-test against, a synthetic
{ target } object can't reproduce defect 2 (a click landing on the icon's
child span) — only a real browser click can. Added a /datepicker gallery
route to test-app (following the /tabs convention from #665) and a new
test-app/e2e/datepicker.spec.ts Playwright spec that exercises the fix
with a real mouse click.

Motivation and Context

Closes #666

Type of Change (Select One and Apply Label)

• Bug fix (non-breaking change which fixes an issue) → Apply bugfix label
• New feature (non-breaking change which adds functionality) → Apply enhancement label
• Breaking change (fix or feature that would cause existing functionality to change) → Apply breaking label
• Documentation / configuration update → Apply maintenance label

How to Test

1. npm ci && npm ci --prefix test-app
2. npm --prefix test-app test — confirms unit specs pass, including the
   two newly-un-skipped picker.spec.ts specs
3. npm run coverage:check — confirms coverage stays at/above the floor
4. npx playwright install --with-deps chromium && npm --prefix test-app run test:e2e —
   runs test-app/e2e/datepicker.spec.ts against a real Chromium browser
5. Manual check: cd test-app && npm start, open http://localhost:4200/datepicker
   • Click the calendar icon → the calendar opens and stays open
   • Click outside the calendar → it closes
   • Tab through the page before/after opening the calendar to confirm other
     elements are disabled while it's open and restored once it closes
   • Focus the calendar icon and press Enter → the calendar opens
   • Select a day, click Cancel, and use the year nav arrows → all still work

Expected result: The calendar opens on a real mouse click and stays
open; clicking outside closes it and restores page focusability/screen-reader
visibility; all existing interactions (day select, cancel, month/year nav,
keyboard open) are unaffected.

Screenshots (if appropriate)

N/A — no visual changes; behavior-only fix in a component with no styling
changes.

Checklist

• Branch name follows convention (e.g. gh-<number>-<slug>)
• PR title starts with a verb in the imperative mood
• I have self-reviewed my own code
• format:check passes (npm run format:check)
• lint passes (npm run lint)
• build passes (cd test-app && npm run build)
• Tests pass and coverage is reported (cd test-app && npm test)
• If this change requires a documentation update, I have updated it accordingly
• If there are dependent changes, they have been merged and published in downstream modules

[Copilot]

🟡 Changes recommended

The new Playwright spec introduces a fixed waitForTimeout(250) that can slow the suite and add flakiness; prefer a deterministic next-frame wait (see comment).

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Fixes sam-datepicker-v2’s outside-click-to-close behavior and ensures tabindex/aria-hidden state is properly restored after the calendar closes, including coverage for the real-browser “click lands on icon child” scenario via Playwright.

Changes:

• Make calendarpopup a non-static @ViewChild and update outside-click logic to use containment for the calendar button.
• Un-skip and strengthen unit specs in picker.spec.ts to cover the now-reachable close behavior and the button containment branch.
• Add a /datepicker gallery route plus Playwright e2e coverage validating open/close and focusability/screen-reader restoration.

File summaries

File	Description
src/ui-kit/experimental/date-range-v2/datepicker/picker.component.ts	Fix @ViewChild resolution and outside-click containment logic; ensures tab/ARIA restoration runs when closing.
src/ui-kit/experimental/date-range-v2/datepicker/picker.spec.ts	Un-skip and update unit tests to assert outside-click close and “click on button doesn’t close”.
test-app/src/app/app.module.ts	Register /datepicker route and import the standalone datepicker gallery component.
test-app/src/app/datepicker-gallery/datepicker-gallery.component.ts	Add standalone gallery component wiring FormsModule + SamDateRangeV2Module, providing SamFormService.
test-app/src/app/datepicker-gallery/datepicker-gallery.component.html	Gallery page with sibling focusable elements to validate tabindex/aria-hidden disabling/restoration.
test-app/src/app/datepicker-gallery/datepicker-gallery.component.spec.ts	Basic creation test for the new gallery component.
test-app/e2e/datepicker.spec.ts	Playwright tests for real-click open/close behavior and tabindex/aria-hidden restore behavior.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[fpigeonjr]

Manual testing note: /datepicker renders unstyled — expected, tracked separately

Manually testing the new /datepicker gallery route surfaced two things that look like bugs but are pre-existing and out of scope for this PR. Both are now filed:

• sam-datepicker-v2 renders unstyled: .datepicker__* CSS was lost in the 2019 fork #681 — sam-datepicker-v2 renders unstyled. No calendar icon, a stray visible "Calendar" label, and a 684x2081px popup with day cells stacked vertically. The template's bespoke .datepicker__* classes are defined in no stylesheet anywhere — they were upstream angular2-material-datepicker's inline styles: block, dropped when this component was forked in 3ba95ec0 (Feb 2019, PR for adding date range component related to IAE-14621 #263). date-range-v2.component.scss has been 0 bytes since that commit, and picker.component.ts has no styleUrls. Nobody noticed for ~7 years because nothing ever rendered it: test-app couldn't render library components until Fix inactive tab content rendering on top of active tab in sam-tabs-next #665, and the sole tracked consumer doesn't use this component (it uses the stable <sam-date>, 32 occurrences).
• disablePageTabIndex() sets aria-hidden on the focused calendar button, and enablePageTabIndex() never removes it #682 — aria-hidden on the focused calendar button. disablePageTabIndex()'s *[tabindex] selector matches the datepicker's own button, so opening the calendar hides the focused trigger from assistive tech and Chrome logs Blocked aria-hidden on an element because its descendant retained focus. enablePageTabIndex() also leaves aria-hidden="false" behind instead of removing it.

Neither is caused by this PR — git diff on picker.component.ts touches only the @ViewChild decorator and the contains() comparison.

One in-scope change pushed: e2e guard now targets the .sr-only child (e4535e0)

While investigating the above I checked whether the open-click spec actually catches Defect 2, by reverting the fix to strict !==:

spec	with !== reintroduced
centre click on .fa-calendar (before)	✅ passed — not guarding the defect
explicit click on .fa-calendar .sr-only (now)	❌ failed on expect(popup).toBeVisible()

Defect 2 only reproduces when event.target is a descendant of #calendarButton, and which element a real click lands on depends on CSS the harness doesn't load. Clicking the child explicitly with { force: true } pins the assertion to the defect regardless of stylesheets — and means #681's harness styling can't silently defang it (called out in that issue's AC).

Verification

Playwright   7 passed  (datepicker x5, tabs, smoke)
Vitest       152 files / 1383 tests passed
coverage     ✓ statements 88.79 · branches 78.83 · functions 85.95 · lines 88.78 (all above floor)
format:check ✓ clean

coverage-floor.json and eslint-baseline.json untouched, per the ratchet rule in AGENTS.md.