feat: hierarchical sticky rows for expandable Table rows (AWSUI-59346)

[ernst-dev]

Description

[WIP / v0] First-cut implementation of hierarchical sticky rows for expandable (tree) Tables — SIM AWSUI-59346.

When enabled, expanded ancestor (parent) rows stay stuck to the top of the table while the user scrolls through their descendant rows — like sticky section headers that reflect the current position in the hierarchy. Each expanded level stacks directly below the sticky header as you scroll deeper.

This is an opt-in, additive enhancement built on top of the existing expandableRows + stickyHeader machinery and the browser's native position: sticky. No existing behavior changes when the flag is off.

What's implemented (v0 — done)

• New opt-in prop TableProps.ExpandableRows.stickyAncestorRows?: boolean (with JSDoc). Effective only together with stickyHeader.
• src/table/sticky-ancestor-rows/index.ts:
  • getStickyAncestorRowOffset() — pure helper computing each level's inset-block-start offset (header offset + (level-1) * rowHeight), with input normalization/clamping.
  • useStickyAncestorRows() — hook that measures the header height (reusing the existing thead ref + useResizeObserver) and returns per-row class + inline offset/z-index props. Deeper levels get a lower z-index so shallower ancestors win overlaps.
• internal.tsx wiring: expanded data rows receive the sticky class + inline offset. Leaf/collapsed rows and the disabled case are untouched.
• SCSS .sticky-ancestor-row (guarded by @supports (position: sticky)), cells get a background so scrolled content doesn't bleed through.
• Dev page: pages/table/hierarchical-sticky-rows.page.tsx (4-level deep tree, toggle to enable/disable).
• Unit tests: src/table/__tests__/sticky-ancestor-rows.test.tsx (8 tests — pure-helper math + render assertions that the class is applied only to expanded parents and only when enabled).
• Public API added → documenter snapshot updated.

Remaining work (NOT in this WIP)

• Precise row-height measurement: v0 uses a fixed DEFAULT_STICKY_ANCESTOR_ROW_HEIGHT (40px) estimate; wrapped content / custom vertical alignment can cause slight overlap. Needs per-row/level measurement.
• position: sticky on <tr> has cross-browser quirks; likely move stickiness to the <td> cells (as sticky-columns does) for robustness.
• Interaction with sticky columns, progressive loading / skeleton rows, grouped/multi-row headers, and selection column offsets not yet validated.
• Accessibility: keyboard scroll/focus behavior with pinned ancestors; verify no focus traps and correct reading order.
• Integration + visual regression tests, and RTL verification.
• Design review / docs (Usage guidelines) — ticket is currently "Design only"; API surface is provisional and may change.
• Consider exposing rowHeight / offset config, and behavior when stickyHeader is false.

Related links, issue #, if available: SIM AWSUI-59346 (Cloudscape feature request: "Hierarchical sticky rows for expandable table rows")

Note: the SIM ticket matches this task description exactly (no ticket mismatch).

How has this been tested?

• eslint — clean on all changed/new files.
• quick-build — success.
• Full build (production) — success (documenter/component-definitions regenerated).
• Unit tests — new suite (8 tests) green; existing table.test.tsx + expandable-rows.test.tsx (48 tests) green; documenter snapshot suite (97 tests) green.
• Manual: dev page table/hierarchical-sticky-rows with a 4-level tree and an enable/disable toggle. Automated cross-browser/visual testing is deferred (see remaining work).

Review checklist

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

Correctness

• Changes include appropriate documentation updates. — JSDoc added; customer-facing usage docs deferred (WIP).
• Changes are backward-compatible if not indicated. — Yes, fully opt-in/additive.
• Changes do not include unsupported browser features. — position: sticky guarded by @supports; cross-browser hardening is follow-up.
• Changes were manually tested for accessibility. — Not yet; tracked in remaining work.

Security

• If the code handles URLs. — N/A.

Testing

• Changes are covered with new/existing unit tests? — Yes.
• 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

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.61%. Comparing base (f97729a) to head (44282a5).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4819   +/-   ##
=======================================
  Coverage   97.61%   97.61%           
=======================================
  Files         952      953    +1     
  Lines       30816    30840   +24     
  Branches    11318    11325    +7     
=======================================
+ Hits        30081    30105   +24     
  Misses        688      688           
  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.