docs: update package documentation

[koukibadr]

Summary by CodeRabbit

• New Features

  • Added a new release with search and filter improvements for the simple picker.
  • Expanded picker customization options and exposed selected/current values more clearly.
  • Updated documentation and examples to reflect the latest picker and callback behavior.

• Bug Fixes

  • Improved modal dismissal flow for safer closing.
  • Refined date-selection behavior and picker header layout.

• Documentation

  • Refreshed the changelog, README structure, setup steps, and usage examples.
  • Updated version references to 4.2.0.

[coderabbitai]

Warning

Review limit reached

@koukibadr, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 40 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: e761f369-1f7f-4d76-94d0-642e7aec31e2

📥 Commits

Reviewing files that changed from the base of the PR and between 2aaaac7 and da3185c.

⛔ Files ignored due to path filters (1)

• example/pubspec.lock is excluded by !**/*.lock

📒 Files selected for processing (5)

• CHANGELOG.md
• README.md
• example/lib/example_widget.dart
• lib/bottom_picker.dart
• pubspec.yaml

📝 Walkthrough

Walkthrough

This PR bumps the package version to 4.2.0, reformats CHANGELOG.md headings consistently, refreshes README documentation with typed callback signatures and new/deprecated API fields, and simplifies the example app's picker configuration and filter logic.

Changes

4.2.0 Release Update

Layer / File(s)	Summary
Version bump and changelog entries pubspec.yaml, CHANGELOG.md	Version updated to 4.2.0; CHANGELOG.md gets a new 4.2.0 entry and historical entries reformatted to consistent ### headings.
README overview and installation refresh README.md	Intro, feature list, and installation snippet updated to reference version 4.2.0.
README API documentation for typed callbacks and deprecations README.md	Documented typed generic callbacks (onChange, onSubmit, onDismiss, itemBuilder, filterPredicate), nullable DateTime? range callbacks, new buttonBuilder and pickerTextStyle, and deprecation of legacy button properties.
README usage examples and closing sections README.md	Usage examples updated for typed callbacks across item/date/year pickers; contributing and closing sections refreshed.
Example widget simplification example/lib/example_widget.dart	Removed default selectedItemIndex, simplified onChange logging, and narrowed filterPredicate to a case-insensitive name match.

Estimated code review effort: 2 (Simple) | ~12 minutes

Poem

Hop, hop, version four-point-two,
New callbacks typed, crisp and true,
Docs refreshed with tidy heads,
Old button styles put to bed,
A rabbit thumps in joyful cheer! 🐇✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title matches the docs-focused nature of the PR, but it is too generic to describe the specific documentation changes.	Use a more specific title, e.g. "docs: refresh README and changelog for v4.2.0".

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 8

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CHANGELOG.md`:
- Line 81: The changelog entry has the same misspelling in the description text,
so update the affected wording to use separator consistently instead of
seperator. Fix the typo in both occurrences within CHANGELOG.md, keeping the
existing meaning and the showTimeSeparator flag reference unchanged.
- Around line 62-63: The changelog entry contains a misspelling in the
user-facing note, so update the 4.0.0 release item in CHANGELOG.md to correct
the typo in the “seleectedIndex” text. Keep the wording otherwise unchanged and
make sure the entry reads consistently with the intended
“selectedIndex”/“selectedItemIndex” terminology used elsewhere.
- Line 1: The release date for the 4.2.0 entry appears inconsistent with the
following 4.1.1 entry, so update the CHANGELOG release dates to restore
chronological order. Check the 4.2.0 heading and the nearby 4.1.1 section, then
correct whichever date is wrong so the version history is ordered consistently.

In `@pubspec.yaml`:
- Line 4: The version bump in pubspec.yaml is not reflected in the checked-in
example lockfile, so update the example/pubspec.lock entry for bottom_picker to
match 4.2.0. Regenerate or edit the lockfile so the example dependency
resolution stays aligned with the package version update.

In `@README.md`:
- Around line 595-597: The contributors image in the README is missing an alt
attribute, so update the existing contrib.rocks img element in the contributors
section to include descriptive alt text for accessibility. Keep the link and
image source unchanged, and make sure the alt text clearly identifies it as the
contributors image in the README.
- Around line 50-53: Remove the duplicated “### Core Picker Types” subsection
heading in the README so the section appears only once and does not create
duplicate anchors or TOC entries. Update the Markdown around the Core Picker
Types heading to keep a single occurrence and leave the surrounding section
structure unchanged.
- Around line 120-123: The README installation section has a duplicated “## 📦
Installation” heading, which creates duplicate anchors and fails markdown lint.
Remove the extra repeated heading in the README so there is only one
Installation heading, keeping the section content under a single unique heading.
- Around line 364-369: The README docs for buttonBuilder describe the callback
as taking only BuildContext, but the actual BottomPicker.buttonBuilder signature
also passes the BottomPicker instance. Update the callback description to match
the real Widget Function(BottomPicker instance, BuildContext context)? API, and
make sure the surrounding text in the buttonBuilder docs consistently refers to
both parameters.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 72ff48db-1d6e-4255-b612-87e6e0ebbba1

📥 Commits

Reviewing files that changed from the base of the PR and between 31845d0 and 2aaaac7.

📒 Files selected for processing (4)

• CHANGELOG.md
• README.md
• example/lib/example_widget.dart
• pubspec.yaml