feat!: API refactor

[pawicao]

Summary

This PR refactors the library to the new context-first v1 API, simplifies the public surface, and updates the examples/docs to match it.

The main goal is to replace the old prop-passing header flow with a cleaner model built around:

• HeaderMotion.Header
• HeaderMotion.Header.Dynamic
• HeaderMotion.Bridge
• HeaderMotion.NavigationBridge
• useMotionProgress()

It also adds header panning, improves custom-scrollable ergonomics, and rewrites the docs/migration guide around the actual current API.

What changed

New header API

• HeaderMotion.Header is now the actual header container primitive
• HeaderMotion.Header.Dynamic marks the collapsible/measured dynamic section
• total header measurement is wired internally by HeaderMotion.Header
• dynamic measurement is wired internally by HeaderMotion.Header.Dynamic
• asChild support was added for both Header and Header.Dynamic

Navigation bridging

• added HeaderMotion.Bridge
• added HeaderMotion.NavigationBridge
• added useHeaderMotionBridge()
• navigation headers now use explicit bridge + re-provide flow instead of the old render-prop HeaderMotion.Header

Motion hooks / context

• useMotionProgress() was narrowed to the real animation surface:
  • progress
  • progressThreshold
• bridge-only internals moved behind useHeaderMotionBridge()
• context/types were reshaped accordingly

Header panning

• header panning is now supported directly on HeaderMotion.Header
• added pannable
• added panDecayConfig
• pan momentum logic was extracted into internal HeaderPanBoundary

Scrollable integration

• kept HeaderMotion.ScrollView, HeaderMotion.FlatList, HeaderMotion.ScrollManager, and createHeaderMotionScrollable()
• improved positioning / offset APIs around:
  • headerOffsetStrategy
  • ensureScrollableContentMinHeight
• custom-scrollable docs now push createHeaderMotionScrollable() as the preferred path, with managers as fallback for more complex cases

File / naming cleanup

• split exported components into their own files:
  • Bridge.tsx
  • NavigationBridge.tsx
  • Header.tsx
  • HeaderDynamic.tsx
• removed old HeaderBase.tsx
• renamed internal/exported component identifiers to match file names
• cleaned up redundant re-exports and simplified compound component composition in src/index.ts

Breaking changes

• HeaderMotion.Header is no longer a render-prop bridge
• AnimatedHeaderBase was removed from the public API
• HeaderBase was removed from the public API
• WithCollapsibleHeaderProps was removed
• WithCollapsiblePagedHeaderProps was removed
• useMotionProgress() no longer returns measurement callbacks
• runtime progressThreshold usage now needs to treat it as a SharedValue
• old navigation-header integration patterns must migrate to Bridge + NavigationBridge

Examples and docs

• migrated the example app to the new API
• removed the obsolete new-api example
• added a dedicated asChild example
• updated all navigation-header examples to show the real public API directly
• rewrote README.md
• rewrote MIGRATION-v1.md
• expanded JSDoc across the public surface

[pawicao]

todo: check the export shape