Maintains bulk selection across paginated or virtualized lists with explicit select-all semantics, exclusion tracking, action confirmation, and recovery when the underlying dataset changes.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
Support bulk actions on paginated datasets with an explicit selection model: per-row selection, select-all on page, and select-all matching current query. Cross-page state tracks selected ids or query snapshot plus exclusions so users understand what will be affected before confirming destructive operations.
Scope
- Selection states and transitions in
selection-model.yaml. - Banner UX showing selection count and mode.
- Query snapshot hashing when select-all matching is used.
- Bulk action payload shape and destructive confirmation requirements.
Outside this block
- Row-level authorization rules on the server.
- Virtualization performance tuning.
- Export/download of full datasets.
Contract
- Selection state survives page navigation within the profile persistence scope until cleared or expired.
- Select-all matching is reachable from none or partial state and stores a deterministic query_snapshot_hash using documented normalization.
- In all-matching mode, submission sends the query snapshot hash and excluded ids; the client does not expand the selection into a potentially stale full id list.
- A destructive bulk action requires confirmation that names the action and displays the selected count represented by the submitted payload.
- Partial server failures report per-id results and retain failed ids in selection for retry.
- Session persistence expiry clears selection and informs the user.
- Clearing selection resets to none state and removes persistence entries.
Implementation guidance
- Implement the state machine from
selection-model.yamlas a single module shared by table views. - Compute query snapshot hash from normalized filter, sort, and search parameters.
- Show persistent banner whenever selected_count is greater than zero.
- Pair destructive bulk actions with the destructive-action interaction block where adopted so confirmation copy matches action severity.
- Expose selection mode in analytics events to diagnose mistaken bulk operations after release.
Failure handling and safeguards
- If total count is unknown, disable select-all matching or require explicit fetch of count before enabling.
- If bulk action partially fails server-side, show per-item results without clearing selection silently.
- On session expiry, drop persisted selection and inform the user.
Verification and operations
- Test cross-page navigation, select-all matching, exclusions, and query-change invalidation.
- Monitor bulk action error rates and mistaken selection incidents.
- Audit that confirmation dialogs match submitted payload counts.
The executable-looking examples in this package are fixtures and acceptance contracts. Validate package structure before adoption; then implement and execute the scenarios in the target repository.
Adoption assumptions
- Page size, persistence TTL, and action names in
example.yamlare profile choices for an admin user table, not universal defaults. - Server must support query-scoped bulk operations when all_matching mode is enabled.
References
- No external normative source is required; this package defines a selection state contract.