feat(12.1-01): declared bulk actions on admin lists

- pact.HasAdminBulkActions with AdminBulkAction, its input and result
- config_list.yaml bulkActions, compiled fail-loud, needs showCheckboxes
- POST .../{controller}/bulk/{action}: ids resolved and locked through the
  list scope in one transaction; partial selection is 409
- list schema offers declared actions per principal, with confirm text
- admin SPA bulk actions menu with confirm, busy state and failure toasts
- acme.roster fixture, tracer test, OpenAPI, TS types, dist, READMEs, docs

modules/pact/README.md

@@ -14,7 +14,7 @@ Capability interfaces that compiled plugins implement to contribute routes, conf
 - HTTP contracts: the `pact.Router` group builder (implemented by surf), the `pact.Middleware` type, and named, parameterized (`name:param`) and house-envelope middleware through `pact.HasMiddleware`, `pact.HasMiddlewareFactories` and `pact.HasHouseMiddleware`.
 - Backend registration data: `pact.Permission`, `pact.NavigationItem` and `pact.SettingsItem`, exposed through `pact.HasPermissions`, `pact.HasNavigation` and `pact.HasSettings`.
 - Admin controller contracts: `pact.AdminController`, `pact.HasAdminControllers`, `pact.AdminAssets` (embedded Winter-shaped admin YAML), `pact.AdminPermissioned` and `pact.AdminRecordSource`.
-- Admin extension contracts, so a plugin extends the compiled admin SPA without a Node build: `pact.AdminClientAssets` (per-controller JS and CSS from the plugin's embedded `assets/` tree, Winter's `addJs`/`addCss`), `pact.HasAdminActions` with `pact.AdminAction`, `pact.AdminActionInput` and `pact.AdminActionResult` (named toolbar and widget actions whose routes, CSRF check, permissions and record scoping the framework owns), and `pact.AdminPartialData` (the curated view model a partial template renders).
+- Admin extension contracts, so a plugin extends the compiled admin SPA without a Node build: `pact.AdminClientAssets` (per-controller JS and CSS from the plugin's embedded `assets/` tree, Winter's `addJs`/`addCss`), `pact.HasAdminActions` with `pact.AdminAction`, `pact.AdminActionInput` and `pact.AdminActionResult` (named toolbar and widget actions whose routes, CSRF check, permissions and record scoping the framework owns), `pact.HasAdminBulkActions` with `pact.AdminBulkAction`, `pact.AdminBulkActionInput` and `pact.AdminBulkActionResult` (named actions on the rows selected in a list, which receive records the framework loaded through the list scope, never ids), and `pact.AdminPartialData` (the curated view model a partial template renders).
 - Optional admin hooks a controller or model can implement: list and form query scoping (`pact.ListExtendQuery`, `pact.FormExtendQuery`), create, update and delete hooks (`pact.FormBeforeCreate`, `pact.FormAfterUpdate`, `pact.FormBeforeDelete` and their siblings), relation hooks (`pact.RelationExtendManageQuery`, `pact.RelationExtendOptionsQuery`, `pact.RelationBeforeLink`), relation child hooks around creating, updating and deleting a related record (`pact.RelationBeforeCreate`, `pact.RelationAfterCreate`, `pact.RelationBeforeUpdate`, `pact.RelationAfterUpdate`, `pact.RelationBeforeDelete`, `pact.RelationAfterDelete`), filter scopes (`pact.FilterScope`, `pact.FilterOptions`) and dropdown options (`pact.DropdownOptionsProvider`).
 - A background job contract (`pact.Job`, `pact.JobArgs`) that does not depend on any queue library.
 - A schedule contract: `pact.HasSchedule` returns `pact.ScheduledCommand` entries (a registered command name, its arguments and a `pact.Cadence` built with `pact.Daily`, `pact.DailyAt` or `pact.Every`), the Go form of WinterCMS `registerSchedule`. It does not depend on any queue library either.
@@ -109,6 +109,10 @@ func (p *Plugin) Schedule() []pact.ScheduledCommand {
 | `pact.AdminActionInput` | What an action receives: widget field, optional record id and scoped record, and the fill snapshot. |
 | `pact.AdminActionResult` | What an action returns: a message for the toast and the fill write-back values. |
 | `pact.HasAdminActions` | Registers a controller's actions for `toolbar.buttons` and `type: widget` fields. |
+| `pact.AdminBulkAction` | One named bulk action: name, label, optional confirm text, extra permissions and the Go `Run` function. |
+| `pact.AdminBulkActionInput` | What a bulk action receives: `Records`, the selected records loaded and row-locked through the list scope. |
+| `pact.AdminBulkActionResult` | What a bulk action returns: an optional message for the toast and `Affected`, the number of records it changed. |
+| `pact.HasAdminBulkActions` | Registers a controller's bulk actions for the `bulkActions` list of `config_list.yaml`. |
 | `pact.AdminPartialData` | Supplies the view model a controller partial template renders; never the GORM model. |
 | `pact.FilterScope` | Model scopes a list filter may call, limited to an exact allow list. |
 | `pact.RelationBeforeLink` | Optional controller hook that checks or fills pivot columns before a relation link is written. |

modules/pact/capabilities.go

@@ -255,6 +255,50 @@ type HasAdminActions interface {
 	AdminActions() []AdminAction
 }
 
+// AdminBulkAction is one controller action an administrator runs on the rows
+// selected in a list (config_list.yaml bulkActions). The admin framework owns
+// the HTTP route, the CSRF check, authentication, the resolution of the posted
+// ids and the transaction; Run only carries the business logic and reads the
+// write transaction with cabana.TxFromContext. Name is an identifier unique
+// among the controller's bulk actions; create and delete are reserved, and a
+// record action may reuse a bulk action's name. Label and Confirm are phrase
+// keys or literal text: Label is the menu item, Confirm the confirmation
+// question, and an empty Confirm means the framework's default confirm text.
+// Permissions are checked in addition to the controller's
+// RequiredPermissions.
+type AdminBulkAction struct {
+	Name        string
+	Label       string
+	Confirm     string
+	Permissions []string
+	Run         func(ctx context.Context, in AdminBulkActionInput) (AdminBulkActionResult, error) `json:"-"`
+}
+
+// AdminBulkActionInput is what the framework hands an AdminBulkAction.
+// Records are pointers to the controller's model, loaded and row-locked
+// through the controller's ListExtendQuery scope and ordered by primary key.
+// A bulk action never receives ids, so an id list can never become an
+// unscoped lookup.
+type AdminBulkActionInput struct {
+	Records []any
+}
+
+// AdminBulkActionResult is a bulk action's answer. Message is a phrase key or
+// text, localized by the framework and shown as a toast; when it is empty the
+// admin shows its default text with Affected. Affected is the number of
+// records the action changed, which may be lower than the selection when the
+// action skips rows.
+type AdminBulkActionResult struct {
+	Message  string
+	Affected int
+}
+
+// HasAdminBulkActions is implemented by an admin controller that registers
+// named bulk actions for its config_list.yaml bulkActions list.
+type HasAdminBulkActions interface {
+	AdminBulkActions() []AdminBulkAction
+}
+
 // AdminPartialData supplies the view model a controller partial template
 // renders (config_list.yaml headerPartial, fields.yaml `type: partial`). name
 // is the partial name; record is the scoped record for a form partial on an