feat: add Master/Detail pattern (v0) [WIP]

[ernst-dev]

Description

[WIP] First-cut (v0) of the Master/Detail layout pattern. Opening as a draft to
gather early feedback on the approach — this is a foundation, not a finished feature.

The Master/Detail pattern places a list/master pane (e.g. a Table) alongside a detail
pane that reflects the selected item; selecting an item updates the detail view, and the
layout collapses to a single column on narrow widths.

This v0 is delivered as a documented composition + a small internal layout helper,
rather than a new public component, because the pattern is fundamentally a composition of
existing primitives (AppLayout, Table/Cards, KeyValuePairs, …). The only reusable,
non-trivial piece — the two-column layout plus responsive collapse — is owned by the helper.

Everything here is additive and opt-in, and lives under src/internal so it carries
no public API surface (no documenter definitions, i18n messages, or test-utils wrappers).

What's included (done in v0)

• src/internal/components/master-detail-layout/ — experimental internal helper:
  • MasterDetailLayout composes existing layout primitives; owns the two-column grid and
    the responsive collapse to a single column (via useContainerQuery).
  • Narrow layout shows a single pane: the detail pane when an item is selected (with an
    optional "back to list" control), otherwise the master pane.
  • Exported pure helper resolveMasterDetailView(...) for the pane-visibility branching.
  • styles.scss (+ test-classes) and a README.md documenting the pattern & API.
• pages/master-detail/simple.page.tsx — dev/demo page: a Table (single-select) master
  → KeyValuePairs detail, inside AppLayout + ContentLayout, with an empty state.
• Unit tests: 8 tests covering the pure view resolver (all branches) + rendering
  (wide layout, empty-state placeholder, no back-control in wide layout).

Remaining work (out of scope for v0 — follow-ups)

• Keyboard focus management when switching panes on narrow widths.
• URL / deep-link syncing of the selected item.
• A SplitPanel/drawer-based detail variant in addition to the inline detail pane.
• Configurable column ratio / minimum widths.
• Decision on graduating to a public API (then: interfaces, i18n, test-utils, documenter,
  API docs) — or keeping it as a documented composition/recipe.
• __integ__ integration tests and visual-regression coverage.
• Broader examples (Cards master, bulk actions, filtering/pagination in the master pane).

⚠️ Ticket mismatch note: The referenced SIM AWSUI-55031 does not describe a
Master/Detail pattern — it resolves to an unrelated "Aperture Form Submission" customer
feedback record (a "Yes" on the Side navigation testing docs tab, 2024-08-09). This PR
was implemented against the provided task description for the Master/Detail pattern; the
ticket reference should be corrected/re-linked.

Related links, issue #, if available: n/a (see ticket-mismatch note above)

How has this been tested?

• npx eslint on the new files — clean (auto-formatted with prettier).
• npx stylelint on the new SCSS — clean.
• npm run quick-build — success.
• Unit tests (jest.unit.config.js) — 8/8 passing.
• npm run build (full: pages, themeable, docs, size-limit, test-definitions) — success
  (only pre-existing entrypoint asset-size warnings, unrelated to this change).
• Manual: npm start → open the "master-detail/simple" dev page; select rows to update
  the detail pane; resize the window to observe the single-column collapse.

Review checklist

The following items are to be evaluated by the author(s) and the reviewer(s).

Correctness

• Changes include appropriate documentation updates. — README + dev page added.
• Changes are backward-compatible if not indicated. — Yes; additive, internal-only, no public API.
• Changes do not include unsupported browser features. — Uses existing primitives + useContainerQuery.
• Changes were manually tested for accessibility. — Regions labelled; full a11y pass is a follow-up.

Security

• If the code handles URLs: all URLs are validated through checkSafeUrl. — N/A, no URL handling.

Testing

• Changes are covered with new/existing unit tests? — Yes (8 new unit tests).
• Changes are covered with new/existing integration tests? — Not yet (follow-up).

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[codecov]

Codecov Report

❌ Patch coverage is 91.66667% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.61%. Comparing base (f97729a) to head (5a1fceb).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...internal/components/master-detail-layout/index.tsx	91.66%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4825      +/-   ##
==========================================
- Coverage   97.61%   97.61%   -0.01%     
==========================================
  Files         952      953       +1     
  Lines       30816    30840      +24     
  Branches    11318    11333      +15     
==========================================
+ Hits        30081    30103      +22     
- Misses        688      690       +2     
  Partials       47       47              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.