[WOOMOB-3561] Add collapsible Page Header behavior

[hichamboushaba]

Description

Fixes WOOMOB-3561

WooPageHeader remains one component API with two rendering modes:

• With scrollBehavior = null, it renders the existing fixed 64dp TopAppBar.
• With a WooPageHeaderScrollBehavior, it renders Material 3's MediumTopAppBar in its standard expanded, partial, and collapsed states.

The default Material 3 MediumTopAppBar collapsing behavior is deliberately preserved. Its expanded and collapsed title treatments cross-fade; the title does not continuously resize during collapse, and trailing actions remain pinned.

WooPageHeaderDefaults.exitUntilCollapsedScrollBehavior() disables snapping and exposes the nestedScrollConnection that hosts attach to their scrolling container. WooPageHeaderScrollBehavior also exposes suspending expand() for downstream programmatic expansion without exposing TopAppBarState or experimental Material types.

Material 3 remains responsible for ordinary nested scrolling, direct header drag, and decay settling. Woo only owns the active programmatic expansion and cancels it before delegating meaningful nested user input or fling boundaries. Concurrent expand() calls follow a newest-wins policy: the superseded call returns normally, the newest invocation owns the final state, and the caller's ambient coroutine is not canceled.

A deliberate non-guarantee remains for rare overlap: direct header drag or an already-running private Material 3 settle can race with programmatic expansion. Material keeps the state clamped to valid bounds, but a later interaction or expand() may be needed to correct the visual state.

Scope is limited to the design-system component, catalog/demo, documentation, and focused tests. Dashboard is intentionally not migrated and no WooCommerce/ app integration is included. The catalog now includes an interactive collapse sample, while focused unit and Robolectric coverage exercises geometry, title/semantics behavior, RTL, scrolling, direct drag/fling, programmatic expansion, and cancellation boundaries.

No release note is added because this is an internal design-system component/API change with no app integration.

Test Steps

1. Open Developer Options → Store Design System Component Catalog → Production components → Page header, then locate the interactive collapsible preview.
2. Verify the fixed Page Header remains 64dp tall.
3. Scroll the sample body through expanded, partial, and collapsed states. Verify standard M3 behavior, the Share action stays pinned, releasing at a partial state does not snap, and the title cross-fades rather than continuously resizing.
4. Drag the header directly and verify standard Material 3 drag and fling behavior.
5. If practical, check the light/dark, RTL, and large-font/long-title previews.

Images/gif

Collapse behavior:

• I have considered if this change warrants release notes and have added them to RELEASE-NOTES.txt if necessary. Use the "[Internal]" label for non-user-facing changes.

[dangermattic]

	1 Warning
⚠️	This PR is larger than 300 lines of changes. Please consider splitting it into smaller PRs for easier and faster reviews.

Generated by 🚫 Danger

[wpmobilebot]

📲 You can test the changes from this Pull Request in WooCommerce Android by scanning the QR code below to install the corresponding build.

	App Name	WooCommerce Android
	Platform	📱 Mobile
	Flavor	Jalapeno
	Build Type	Debug
	Build Number	772
	Version	25.2-rc-1
	Application ID	com.woocommerce.android.prealpha
	Commit	61170f7
	Installation URL	62h475iea17ro

Automatticians: You can use our internal self-serve MC tool to give yourself access to those builds if needed.

[claude]

AI Code Review - No issues found. The changes look good.

The WooPageHeader rewrite to Material3 TopAppBar/MediumTopAppBar is clean and well-scoped. Nice touches: the WooPageHeaderScrollBehavior wrapper hides the experimental TopAppBarScrollBehavior behind an internal delegate and exposes only the stable NestedScrollConnection, and the new scrollBehavior param is added before the trailing actions lambda so existing callers stay source-compatible. The component is only consumed inside the design-system module, so the internal layout change has no production regression risk. Test coverage is thorough — fixed vs. medium heights, partial/collapsed states, single-heading accessibility, long-title truncation before the action, and LTR/RTL logical edges.

---

_{Automatic review · claude-opus-4-8 · Workflow run}

_{How to reply to a finding}

Reply on this review (or inline at the line the finding refers to) with one of:

• @claude addressed - I made the change. Bot verifies against the next diff before marking resolved.
• @claude rejected: <reason> - Will not fix; reason gets quoted on the next review.
• @claude not-applicable - Finding does not apply (wrong file, already covered elsewhere, etc.).

The bot honours these on the next review pass.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 15.65217% with 194 lines in your changes missing coverage. Please review.
✅ Project coverage is 41.12%. Comparing base (c797d14) to head (61170f7).
⚠️ Report is 71 commits behind head on trunk.

Files with missing lines	Patch %	Lines
...ui/compose/designsystem/component/WooPageHeader.kt	0.00%	129 Missing ⚠️
...ignsystem/component/WooPageHeaderScrollBehavior.kt	50.70%	27 Missing and 8 partials ⚠️
.../preview/WooDesignSystemComponentCatalogPreview.kt	0.00%	30 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk   #16257      +/-   ##
============================================
- Coverage     41.15%   41.12%   -0.04%     
- Complexity    13498    13503       +5     
============================================
  Files          2503     2504       +1     
  Lines        146462   146658     +196     
  Branches      21761    21817      +56     
============================================
+ Hits          60275    60311      +36     
- Misses        80089    80241     +152     
- Partials       6098     6106       +8     

☔ 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.

[hichamboushaba]

@claude review

[claude]

AI Code Review - Follow-up

The previous review raised no issues, so there is nothing to reconcile.

• Previous review readiness: not flagged (design-system component, no production consumers) — still resolved

New issues: 0

I re-reviewed the full current diff. The concurrency design in WooPageHeaderScrollBehavior.expand() holds up: the LAZY child job + writeIfActiveOwner ownership check correctly rejects stale writes when a newer expansion supersedes an older one, superseded callers return normally (individually cancelling a child does not propagate to the caller's coroutineScope), and the WooPageHeaderNestedScrollConnection cancels the active expansion before delegating meaningful user input and both fling boundaries. All of this is precisely exercised by the two test files. WooPageHeader remains consumed only inside the design-system module (component + catalog preview), so the API change carries no production regression risk, and the new implementation dependencies (compose-animation, coroutines-core) match the new code. Looks good.

---

_{Automatic review (follow-up) · claude-opus-4-8 · Workflow run}

_{How to reply to a finding}

Reply on this review (or inline at the line the finding refers to) with one of:

• @claude addressed - I made the change. Bot verifies against the next diff before marking resolved.
• @claude rejected: <reason> - Will not fix; reason gets quoted on the next review.
• @claude not-applicable - Finding does not apply (wrong file, already covered elsewhere, etc.).

The bot honours these on the next review pass.

[claude]

AI Code Review - Follow-up

The previous review raised no code issues, so there is nothing to reconcile beyond the readiness note.

• Previous review readiness: not flagged (design-system component with no production consumers; exercised via catalog previews and unit tests) — still resolved

New issues: 0

The HEAD commit is unchanged from the previous follow-up, so there are no new changes to review. The WooPageHeaderScrollBehavior.expand() concurrency design remains sound: the LAZY child job plus the writeIfActiveOwner ownership guard rejects stale writes when a newer expansion supersedes an older one, superseded callers return normally, and WooPageHeaderNestedScrollConnection cancels the active expansion before delegating meaningful user input and both fling boundaries — all covered by the two test files. WooPageHeader is still consumed only inside the design-system module, so the API change carries no production regression risk, and the added implementation dependencies (compose-animation, coroutines-core) match the new code. Looks good.

---

_{Automatic review (follow-up) · claude-opus-4-8 · Workflow run}

_{How to reply to a finding}

Reply on this review (or inline at the line the finding refers to) with one of:

• @claude addressed - I made the change. Bot verifies against the next diff before marking resolved.
• @claude rejected: <reason> - Will not fix; reason gets quoted on the next review.
• @claude not-applicable - Finding does not apply (wrong file, already covered elsewhere, etc.).

The bot honours these on the next review pass.

[hichamboushaba]

@irfano I see you self-assigned the review of #16248, can you please instead review this PR first? Since it's the base branch for all other PRs.

Thanks 🙏

[hichamboushaba]

Note: Wagner approved the collapsing animation of the title, and that it should match the default M3.

[irfano]

I left some minor feedback, but I'm approving. 👍🏻