search_anchor_picker 0.2.3

A searchable Flutter picker with multi or single selection, nested sub-pickers, and async save callbacks that roll back on failure.

0.2.3

• Widget initialSelectedItemCache shows selected IDs missing from the loader page in a Selected section, and keeps those rows visible under a load-error message when itemsLoader fails. Search still applies only to Results. itemBuilder now receives PickerItemSource. DefaultPickerItemTile accepts title, subtitle, and relatedListItemStatus.

0.2.2

• fix analyzer warnings

0.2.1

• Shortened the pubspec description. Added example/example.dart for pub.dev. Asserts on PickerConfig bind state include messages.

0.2.0

Breaking vs 0.1.1:

• onToggle / OnToggleMode → onChange(PickerDelta). A throw restores the checkbox.
• onFinish → onClose(PickerDelta). A throw keeps the overlay open (closeSavingBuilder / closeSaveFailedBuilder). viewOnClose is overlay lifecycle.
• PickerMode.radio / radioToggle → SelectionMode.single / singleOptional.
• UnselectBehavior + isItemInUse → relatedListItemStatusOf (unselectPolicy, selectable, auxiliaryMembership). Status listenable repaints without reload. itemBuilder gets status before toggle.
• Removed canChangeSelection. Block or confirm with PickerUnselectPolicy; throw from onChange to restore a checkbox after a failed write.
• SubPickerTile no longer deselects parent IDs just because parentController is set. Opt in with SubPickerParentSelectionEffect.
• SubPickerTile.onChange is (delta, notifyParent). When onClose is also set, call notifyParent() after every successful onChange for immediate parent sync, or never in that session.
• loadItems / LoadItems → itemsLoader / ItemsLoader. viewOnChanged → onQueryChanged.
• itemsLoader is (context, query). PickerSearchMode chooses what typing does: local (default) loads once and filters the snapshot; remote reloads and trusts the page; hybrid does both. searchTermsOf is optional and unused in remote. Debounce remote itemsLoader (or the API) with Debouncer or an equivalent; the picker does not. The open picker watches search-field text (not cursor moves) and reloads remote/hybrid from that. onQueryChanged includes programmatic query changes. searchController → queryController (TextEditingController). Overlay control is on PickerConfig: open() / close(), plus isAttached / isOpen.

Also:

• Persist in onChange or onClose, not both. Close nets select/deselect against the seed at open; change does not.
• Removed unused PickerSelectionSession.acceptToggle / result(remainingOnly:). Removed the lib/raw.dart entrypoint; raw types stay under lib/src/raw/.
• Bulk header commands take the same apply path as a row toggle (one delta).
• Default copy is localized (empty, no-results, retry, in-use warning/confirm, saving, close-save failed). emptyText / noResultsText override the first two.
• DefaultPickerFieldTrigger is the field-style triggerBuilder: outlined input, optional selected chips, Add (multi) or Change (single), field tap opens, chip delete removes without opening.
• copyWith can clear nullable fields (copyWith(listenable: null)). The copy is unbound. One PickerConfig instance binds to one picker; a second attach throws.
• Parent effects apply after a successful child onClose, or after each onChange when onClose is omitted. When both are set, call notifyParent() after every successful onChange or never in that session. The parent search field shows a spinner while that write is in flight.

0.1.2 (git only)

• Added API documentation for the public libraries and query-close behavior.
• Added localized default empty/no-results messages with emptyText and noResultsText overrides for main and nested pickers.
• Localized default retry and in-use removal warning/confirmation text through the same locale resolver.

0.1.1

• Made item reloads explicit: ordinary PickerConfig replacement now rebinds without fetching, while reloadKey, listenable, and controller refresh() provide deliberate invalidation paths.

0.1.0

Breaking package identity:

• Renamed the unpublished package from generic_search_selector to search_anchor_picker; imports now use package:search_anchor_picker/search_anchor_picker.dart.

• Renamed GenericPickerActions / PickerActions to GenericPickerController / PickerController, and renamed SubPickerTile.parentActions to parentController.

• Removed the deprecated onFinishReplaceAll, minWidth, and maxHeight APIs. Use explicit onFinish deltas and viewConstraints.

• Removed the replace-all-only empty-save parameters, builder, and default widget.

• Raised the declared Flutter minimum to 3.38 and activated very_good_analysis for the package.

• Kept Riverpod isolated to the async example by moving its integration test into the example package.

• Split agent documentation into a package maintenance guide and a standalone consumer integration skill.

0.0.4

SearchAnchor parity / UI:

• Added SearchAnchor-compatible view properties and SearchViewTheme fallback.
• Added mobile full-screen and desktop anchored popup defaults.
• Added focused builders for search, results, loading, empty, error, composed view, and surface regions.
• Moved optional/default widgets under lib/src/widgets/ and added widgets.dart.
• Added viewConstraints for popup sizing.

Selection / lifecycle:

• Close persistence uses onFinish({added, removed}) explicit deltas.
• Simplified header actions: selectLoaded, clearLoaded, and their filtered variants record explicit deltas by default; syncPending(added:, removed:) is the sole pending-only synchronization escape hatch.
• Selected IDs missing from the loaded page are preserved.
• Extracted selection-session bookkeeping and expanded lifecycle coverage.
• Added loading/error/retry states, stale-load suppression, idempotent close, and safe callback failure cleanup.

Docs / example:

• Documented server-side search safety, visual builders, theme precedence, and OnToggleMode.awaitGate versus OnToggleMode.optimistic.
• Added the example web deployment workflow and online demo link.

Consumers using Git dependencies should pin a semantic version tag matching pubspec.yaml.

0.0.3

Breaking / API:

• Split close persistence into onFinish({added, removed}) (explicit row deltas) and onFinishReplaceAll(finalIds) (replace-all).
• onFinish no longer receives the full finalIds list; use onFinishReplaceAll when the backend needs the whole selection.
• Empty onFinishReplaceAll saves require an explicit empty-save confirmation (saveEmptyLabel / showSaveEmptyButton).
• Added bulk pending helpers: pendingClearLoaded, pendingClearFiltered, pendingSelectLoaded, pendingSelectFiltered (no deltas).
• Added explicit delta helpers: toggleIdAsDelta, clearLoadedAsDelta, selectLoadedAsDelta, clearFilteredAsDelta, selectFilteredAsDelta.

Behavior / docs:

• Selected IDs missing from the current itemsLoader page are preserved (server-side search safe).
• Documented OnToggleMode.awaitGate vs OnToggleMode.optimistic for async checkbox UX.
• Added agent-facing integration guidance for common consumer pitfalls.
• Example web deploy workflow + online demo link.

0.0.2

• Internal packaging bump (see git tags v13 / v14 for prior consumer pins).

0.0.1

• Initial SearchAnchor-based picker with multi/radio modes, nested SubPickerTile, and header actions.