74 lines
2.1 KiB
Markdown
74 lines
2.1 KiB
Markdown
# UX Contracts (non-API) — Ops-UX Constitution Rollout (055)
|
|
|
|
This feature does not introduce new public HTTP APIs. Instead it defines **internal UX contracts**: shared builders/presenters that all operation-related UI must use.
|
|
|
|
## Surfaces
|
|
|
|
### A) Toast (queued only)
|
|
|
|
**Trigger**: user clicks “Start operation” / submits a form that enqueues a job.
|
|
|
|
**Contract**
|
|
|
|
- Toast must appear immediately.
|
|
- Must **not** write a DB notification for `queued`.
|
|
- Copy (canonical) (OPS-UX Constitution v1.3.0):
|
|
- Title: `{OperationLabel} queued`
|
|
- Body: `Running in the background.`
|
|
|
|
Optional alternative body (not additive):
|
|
|
|
- `You can monitor progress in Operations.`
|
|
|
|
Forbidden in toast:
|
|
|
|
- counts/metrics
|
|
- percentages/progress
|
|
- terminal outcomes (completed/failed/partial)
|
|
- feature-specific copy
|
|
|
|
Notes:
|
|
|
|
- Toast is queued-only.
|
|
- Terminal outcomes are delivered via DB notification (initiator-only).
|
|
- Live awareness is via Progress Widget + Monitoring → Operations.
|
|
|
|
### B) Progress widget (queued/running only)
|
|
|
|
**Audience**: tenant-wide for users with Monitoring access.
|
|
|
|
**Contract**
|
|
|
|
- Only shows runs with status `queued` or `running`.
|
|
- At most 5 items.
|
|
- If more than 5, show `+N more` link to canonical Operations index.
|
|
- Each row must include a canonical `View run` action linking to Run Detail.
|
|
- Must use centralized label + status copy.
|
|
- Polling cadence must be “calm”: start fast when there are actives, then back off.
|
|
|
|
### C) Terminal DB notification
|
|
|
|
**Trigger**: transition to a terminal state.
|
|
|
|
**Audience**: initiator-only.
|
|
|
|
**Contract**
|
|
|
|
- Exactly one notification per run per initiator.
|
|
- Must not write `queued` notifications.
|
|
- Title/body/status must be derived via centralized presenter.
|
|
- Must include canonical `View run` link.
|
|
- Optional summary uses `summary_counts` with whitelist rules.
|
|
|
|
## Strings
|
|
|
|
All copy that appears in these surfaces must come from a shared source (presenter or resource strings), not ad-hoc in Blade/Livewire.
|
|
|
|
## Metrics (summary_counts)
|
|
|
|
Allowed keys:
|
|
|
|
- See spec.md (FR-012) “Canonical allowed summary keys (single source of truth)”.
|
|
|
|
Any other keys must not render.
|