anchor_kit 0.2.1

anchor_kit: ^0.2.1 copied to clipboard

Documentation hygiene — no behaviour changes.

• doc/API.md caught up with 0.2.0. AutoPlacement, SizeMiddleware and Hide shipped in 0.2.0 and were documented in the README, but the API reference still stopped at Arrow — all three now have entries with their constructor arguments and the middlewareData keys they write. The Placement section also names PlacementSide / PlacementAlign, which had never been mentioned by name despite being how you read a resolved placement (position.placement.side).
• Offset4 is documented as deprecated, with the replacement spelled out. Its deprecation message said it would be removed in v0.1.0 — a version that had already shipped — and now names 0.3.0.
• The README no longer carries version numbers. The status line restated the release and Install pinned ^0.2.0; both had to be edited every release and are exactly what went stale in sibling packages. pubspec.yaml is the version, CHANGELOG.md is the history, the pub.flutter-io.cn badge renders the current number. Install is now flutter pub add anchor_kit.
• New: test/docs_freshness_test.dart — fails the suite if the README contains a version literal, if CHANGELOG.md's newest entry doesn't match pubspec.yaml, or if a public type has no entry in doc/API.md (this is the guard that found the three undocumented middleware).
• New: test/readme_snippets_test.dart — compile-checks every Dart snippet in the README and doc/API.md against the real API, including each documented middleware constructor and the "write your own middleware" example.

Stable release of the 0.2.0 line (the 0.2.0-dev.* notes below are the full history). Headline changes since 0.1.x:

• New middleware: SizeMiddleware (available-space reporting for capped, scrollable menus), AutoPlacement (pick the side with the most room), and Hide (flag when the anchor scrolls off-screen). Shift gained main-axis / cross-axis / RTL controls.
• Fix (FloatingOverlay): overlay mutations are deferred out of the build/layout phase, so opening/updating an overlay under a LayoutBuilder (or rebuilt per-frame) no longer throws setState() called during build on Flutter 3.35+.
• Fix (AutoPlacement): preserves an earlier OffsetMiddleware gap across a re-place, and only keeps the current side when it is an allowed candidate.
• Example: a new Stress test recipe — an in-app performance harness with a live FPS / build / raster / jank readout and a computePosition micro-benchmark.
• Docs: README gained a measured Performance section; install/status point at ^0.2.0.

All public API additions are backward compatible with 0.1.x.

• Fix (FloatingOverlay): opening/updating an overlay no longer throws setState() called during build. When a FloatingOverlay is rebuilt during a layout pass — e.g. nested under a LayoutBuilder, or rebuilt every frame — its didUpdateWidget used to insert/remove/rebuild the Overlay entry synchronously, marking the already-built Overlay dirty mid-build. Overlay mutations triggered during build/layout are now deferred to just after the frame. Surfaced on Flutter 3.35+ where Overlay is stricter.

• Fix (AutoPlacement): an earlier OffsetMiddleware gap is now preserved when AutoPlacement resolves to a different side — the offset is re-projected onto the chosen side's axes instead of snapping the element back to the bare base position (it used to touch the anchor after a re-place).
• Fix (AutoPlacement): the "keep the current placement if it fits" fast-path no longer retains a side that the caller excluded from candidates; the current placement is kept only when it is actually a candidate.
• Docs: README install/status now point at ^0.2.0.

Prerelease of 0.2.0 — opt in with anchor_kit: 0.2.0-dev.1. Stable users stay on 0.1.x until 0.2.0 ships.

• New middleware:
  • SizeMiddleware — reports available space on the resolved side (data['size'] = {availableWidth, availableHeight}) so a long menu can cap its height to the viewport and scroll. New "Size" example recipe.
  • AutoPlacement — picks the side with the most room (keeps the current side if it fits, else least overflow); use instead of Flip.
  • Hide — flags data['hide'] = {referenceHidden} when the anchor scrolls off-screen.
• Shift now clamps only the main axis by default (was both axes), so it no longer detaches the floating element from its anchor. Opt into crossAxis: true; rtl: true keeps the right edge for oversized elements.
• Note: SizeMiddleware collides with dart:ui's Size, hence the Middleware suffix.

• Docs: denser, mobile-sized screenshots (430×820) so the README images read clearly instead of tall, mostly-empty frames. No code changes.

• New: FloatingOverlay gains barrierDismissible + onDismiss — a transparent tap-outside-to-close barrier for dropdowns / selects / popovers.
• Example: rebuilt into a recipe gallery — placement playground, tooltip, dropdown, select (flips up), and a popover-with-arrow card. Deep-linkable via ?demo=<id> on web. Now runs on web too.
• Docs: README overhauled with screenshots, concept explanations (offset/flip/shift/arrow) and a "Known limitations" section.
• Bundles all 0.0.2 fixes below.

• Fix: FloatingOverlay now follows the anchor when an ancestor scrolls (previously it only listened to descendant scrolls and silently failed to reposition). It also repositions on window resize/rotation and re-measures the floating child each frame so size changes stay positioned.
• Fix: Flip no longer spuriously flips a placement that already fits but touches a viewport edge; and when neither side fits it keeps the side that overflows least instead of always the original.
• Fix: Shift keeps the start edge visible when the floating element is larger than the viewport (was pinned to the far edge).
• Fix: Arrow no longer throws when the floating element is too small to honour padding — it centres the arrow instead.
• API: Offset4 renamed to OffsetMiddleware (old name kept as a deprecated alias until v0.1.0).
• Lifecycle: mounted guards on overlay open/measurement.
• Docs: added docs/SPEC.md; added FloatingOverlay widget tests (including scroll-follow) and middleware edge-case tests.

• Initial scaffold: computePosition, Placement, middleware (Offset4, Flip, Shift, Arrow), FloatingOverlay widget.