feat(ui): ship contextual action primitives

This commit is contained in:
master
2026-03-08 00:02:02 +02:00
parent a295841d25
commit f709d519ec
30 changed files with 1446 additions and 392 deletions

View File

@@ -0,0 +1,55 @@
# Contextual Actions Patterns UI
## Module
Web
## Status
VERIFIED
## Description
Shipped the shared contextual placement primitives used to turn restored but narrow functionality into usable owner-shell tabs, drawers, submenu pills, and list-detail layouts instead of standalone products. Watchlist, Reachability, Operations, and Workflow Replay now share one route-state contract, one contextual header model, and one drawer or detail-shell behavior.
## Implementation Details
- **Shared feature directory**: `src/Web/StellaOps.Web/src/app/shared/ui/`
- **Primary shared primitives**:
- `context-route-state` (`src/Web/StellaOps.Web/src/app/shared/ui/context-route-state/context-route-state.ts`)
- `context-header` (`src/Web/StellaOps.Web/src/app/shared/ui/context-header/context-header.component.ts`)
- `context-drawer-host` (`src/Web/StellaOps.Web/src/app/shared/ui/context-drawer-host/context-drawer-host.component.ts`)
- `list-detail-shell` (`src/Web/StellaOps.Web/src/app/shared/ui/list-detail-shell/list-detail-shell.component.ts`)
- `overview-card-groups` (`src/Web/StellaOps.Web/src/app/shared/ui/overview-card-groups/overview-card-groups.component.ts`)
- `tabbed-nav` (`src/Web/StellaOps.Web/src/app/shared/ui/tabbed-nav/tabbed-nav.component.ts`)
- **Shared route-state keys**:
- `tab`
- `panel`
- `drawer`
- `returnTo`
- `scope`
- `view`
- **Adopted surfaces**:
- `Setup > Trust & Signing > Identity Watchlist`
- `Security > Reachability`
- `Ops > Operations`
- `Releases > Runs`
## E2E Test Plan
- **Setup**:
- [ ] Log in with a user that can access `Setup`, `Security`, `Ops`, and `Releases`.
- [ ] Ensure watchlist, reachability, operations, and release-run fixtures or seeded data exist.
- **Core verification**:
- [ ] Verify shared tab and submenu primitives render the adopted shells without bespoke route-state code.
- [ ] Verify contextual headers preserve return-to-context actions where shells deep-link into another owner flow.
- [ ] Verify route-aware drawers and detail layouts preserve URL state and close behavior.
- **Adoption verification**:
- [ ] Verify Watchlist entries use the shared list-detail and header patterns.
- [ ] Verify Reachability tabs and PoE drill-ins use the shared contextual route-state.
- [ ] Verify Operations overview groups use the shared grouped-card and submenu patterns.
- [ ] Verify Workflow Replay step-detail and evidence handoff keep shared `returnTo` and drawer semantics.
## Verification
- Run:
- `npx ng test --watch=false --include src/tests/shared/contextual-actions-patterns-ui.spec.ts --include src/tests/watchlist/identity-watchlist-management-ui.component.spec.ts --include src/tests/reachability_center/reachability-center.component.spec.ts --include src/tests/platform-ops/platform-ops-overview-page.component.spec.ts --include src/tests/workflow_visualization/run-graph-replay-page.behavior.spec.ts`
- `npx playwright test tests/e2e/watchlist-shell.spec.ts tests/e2e/reachability-witnessing.spec.ts tests/e2e/operations-consolidation.spec.ts tests/e2e/workflow-visualization-replay.spec.ts --workers=1`
- Tier 0 (source): pass
- Tier 1 (build/tests): pass
- Tier 2 (behavior): pass
- Verified on (UTC): 2026-03-07T21:56:33.4410778Z

View File

@@ -1,129 +0,0 @@
# Sprint 20260307-029 - Contextual Actions And Stray Surfaces
## Topic & Scope
- Define and implement the shared FE interaction contract for functionality that should become a submenu, tab, segmented queue mode, drawer, or full detail page instead of a new top-level product.
- Build the reusable drawer, right-rail, split-view, context-header, and overview-card primitives needed by the restoration sprints.
- Adopt those primitives into the shipped restoration features so this sprint delivers working UI infrastructure, not just another contract document.
- Working directory: `src/Web/StellaOps.Web/src/app/shared`.
- Allowed coordination edits: `src/Web/StellaOps.Web/src/app/layout/`, `src/Web/StellaOps.Web/src/app/routes/`, `docs/modules/ui/contextual-actions-patterns`, `docs/modules/ui/restoration-topics/README.md`, and `docs/modules/ui/TASKS.md`.
- Expected evidence: shipped shared UI primitives in `src/Web/**`, adopted patterns in restoration features, route-state helpers, shared tests, and updated docs.
## Dependencies & Concurrency
- Depends on:
- `docs/modules/ui/contextual-actions-patterns/README.md`
- `docs/modules/ui/restoration-topics/README.md`
- `docs/modules/ui/watchlist-operations/README.md`
- `docs/modules/ui/reachability-witnessing/README.md`
- `docs/modules/ui/platform-ops-consolidation/README.md`
- `docs/modules/ui/triage-explainability-workspace/README.md`
- `docs/modules/ui/workflow-visualization-replay/README.md`
- Safe parallelism:
- the decision matrix and route-state contract should freeze before topic-specific FE implementation starts
- shared primitives can be implemented in parallel after the contract is stable
- topic sprints can adopt the primitives in parallel once interfaces are frozen
## Documentation Prerequisites
- `docs/modules/ui/contextual-actions-patterns/README.md`
- `docs/modules/ui/restoration-topics/README.md`
- `docs/modules/ui/architecture.md`
- `docs/modules/ui/architecture-rework.md`
## Delivery Tracker
### FE-CA-001 - Implement the shared route-state contract
Status: TODO
Dependency: none
Owners: FE Architect, Product Manager
Task description:
- Implement the shared route-state helpers for `tab`, `panel`, `drawer`, `returnTo`, `scope`, and `view`.
- Make the restoration topics consume one working route-state model instead of each inventing bespoke state handling.
Completion criteria:
- [ ] Shared route-state helpers exist in code.
- [ ] Restoration topics can consume one route-state contract instead of bespoke state rules.
- [ ] The placement hierarchy remains documented as the policy for using the new helpers.
### FE-CA-002 - Ship the shared contextual drawer host
Status: TODO
Dependency: FE-CA-001
Owners: Developer, FE Architect
Task description:
- Build the shared drawer host used for edit, inspect, explain, and proof flows.
- Standardize size, close behavior, route-state binding, keyboard handling, and history interactions in working code.
Completion criteria:
- [ ] Drawer host is available for adoption in the restoration features.
- [ ] Route-state open and close behavior works in code.
- [ ] Accessibility and keyboard behavior are verified for the shared host.
### FE-CA-003 - Ship split-view, right-rail, and context-header primitives
Status: TODO
Dependency: FE-CA-001
Owners: Developer, FE Architect
Task description:
- Build reusable split list/detail, right-rail, and context-header primitives for watchlist, triage, evidence, and reachability surfaces.
- Ensure responsive behavior works in the shipped components rather than remaining a note in docs.
Completion criteria:
- [ ] Split-view, right-rail, and context-header primitives exist in code.
- [ ] Panel-stack behavior is usable in the shipped primitives.
- [ ] Responsive fallback behavior works in the adopted surfaces.
### FE-CA-004 - Ship grouped overview-card and submenu primitives
Status: TODO
Dependency: FE-CA-001
Owners: Product Manager, Developer
Task description:
- Build the grouped overview-card and submenu primitives used by Operations and narrow setup/admin capabilities.
- Standardize one-card-to-one-route and one-submenu-to-one-owner patterns in working components.
Completion criteria:
- [ ] Grouped overview-card primitives exist in code.
- [ ] Submenu patterns are usable by owner shells.
- [ ] Card-to-route and submenu-to-owner behavior is consistent in the shipped implementation.
### FE-CA-005 - Adopt the shared primitives into the restoration features
Status: TODO
Dependency: FE-CA-001
Owners: FE Architect, Developer
Task description:
- Adopt the shared route-state, drawer, split-view, right-rail, context-header, and overview-card primitives into the restoration features.
- Do not count this sprint complete until the primitives are used by the first shipped feature set rather than sitting unused in `shared`.
Completion criteria:
- [ ] At least the Watchlist, Reachability, and Triage or Workflow surfaces adopt the shared primitives.
- [ ] Shared primitives replace bespoke implementations where the new restoration work lands.
- [ ] Topic-specific adoption is visible in the shipped feature code.
### FE-CA-006 - Verify, document, and enforce shared usage
Status: TODO
Dependency: FE-CA-003
Owners: QA, Documentation author
Task description:
- Add shared verification coverage for drawers, panels, tabs, split views, overview cards, and return-to-context behavior.
- Update docs so future restoration work treats these primitives as required building blocks, not optional helpers.
Completion criteria:
- [ ] Shared verification covers the adopted primitives.
- [ ] Restoration sprints reference and consume the shared primitives.
- [ ] Shared docs are updated to reflect the shipped primitive set.
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-03-07 | Sprint created to ship the shared primitives that let restored but narrow functionality become usable submenus, tabs, drawers, right rails, and detail pages instead of spawning new top-level products. | Project Manager |
## Decisions & Risks
- Decision: contextual placement is a shared FE concern and should not be reinvented per topic.
- Decision: stable route-state semantics are required for drawers, panels, and return-to-context behavior.
- Risk: individual restoration sprints may drift and invent incompatible panel patterns before the shared contract lands.
- Mitigation: freeze the shared contract first and make topic sprints depend on it.
- Risk: responsive behavior may differ across list/detail, drawer, and right-rail surfaces.
- Mitigation: require responsive fallback rules in the shared primitive contract before implementation begins.
- Delivery rule: this sprint is only complete when the shared primitives are implemented and adopted by the restoration features, not when the contract is only documented.
- Reference design note: `docs/modules/ui/contextual-actions-patterns/README.md`.
## Next Checkpoints
- 2026-03-08: confirm placement hierarchy and route-state contract.
- 2026-03-09: freeze drawer, right-rail, split-view, and context-header primitives.
- 2026-03-10: finalize adoption map and QA expectations for the restoration sprints.

View File

@@ -22,6 +22,8 @@ The Console presents operator dashboards for scans, policies, VEX evidence, runt
- Added checked-feature verification for reachability witnessing at `../../features/checked/web/reachability-witnessing-ui.md`.
- Shipped the consolidated `Ops > Operations` shell with grouped overview cards, canonical `/ops/operations/*` routes, and legacy `platform-ops` alias cutover.
- Added checked-feature verification for operations consolidation at `../../features/checked/web/operations-consolidation-ui.md`.
- Shipped the shared contextual placement primitives for tabs, submenu pills, route-aware drawers, list-detail shells, grouped overview cards, and return-to-context headers under `src/Web/StellaOps.Web/src/app/shared/ui/`.
- Added checked-feature verification for the contextual primitives and their first adopted surfaces at `../../features/checked/web/contextual-actions-patterns-ui.md`.
## Latest updates (2026-02-21)
- Runtime mock cutover completed for policy simulation history/conflict/batch flows and graph explorer data loading in `src/Web/StellaOps.Web/src/app/**`.

View File

@@ -9,7 +9,6 @@
- `docs/implplan/SPRINT_20260307_009_DOCS_ui_component_preservation_map.md`
- `docs/implplan/SPRINT_20260307_022_FE_policy_vex_release_decisioning_studio.md`
- `docs/implplan/SPRINT_20260307_023_DOCS_ui_restoration_topic_shapes.md`
- `docs/implplan/SPRINT_20260307_029_FE_contextual_actions_and_stray_surfaces.md`
- `docs/implplan/SPRINT_20260307_035_DOCS_search_first_final_correction_phases.md`
- `docs/implplan/SPRINT_20260307_036_FE_search_first_shell_consolidation.md`
- `docs/implplan/SPRINT_20260307_038_FE_live_search_supported_route_execution_matrix.md`
@@ -107,9 +106,9 @@
- [DONE] FE-WV-004 Step-detail drawer and deep-link behavior
- [DONE] FE-WV-005 Workflow-editor preview reuse boundary
- [DONE] FE-WV-006 QA, rollout, alias migration, and docs sync for workflow visualization
- [TODO] FE-CA-001 Freeze contextual placement decision matrix and route-state contract
- [TODO] FE-CA-002 Shared contextual drawer host
- [TODO] FE-CA-003 Split list-detail and right-rail primitives
- [TODO] FE-CA-004 Context header and return-to-context contract
- [TODO] FE-CA-005 Grouped overview-card and submenu patterns
- [TODO] FE-CA-006 Adoption map, QA, and docs sync for contextual action patterns
- [DONE] FE-CA-001 Freeze contextual placement decision matrix and route-state contract
- [DONE] FE-CA-002 Shared contextual drawer host
- [DONE] FE-CA-003 Split list-detail and right-rail primitives
- [DONE] FE-CA-004 Context header and return-to-context contract
- [DONE] FE-CA-005 Grouped overview-card and submenu patterns
- [DONE] FE-CA-006 Adoption map, QA, and docs sync for contextual action patterns

View File

@@ -54,7 +54,7 @@ The order is by confidence that the capability should exist in the final Stella
- `Security / Reachability` with evidence-side drill-down links
- Notes:
- Detailed UX dossier: `docs/modules/ui/reachability-witnessing/README.md`
- Implementation sprint: `docs/implplan/SPRINT_20260307_025_FE_reachability_witnessing_merge.md`
- Implementation sprint: `docs-archived/implplan/SPRINT_20260307_025_FE_reachability_witnessing_merge.md`
### 4. Platform Ops Consolidation
- Type: `merge`
@@ -67,7 +67,7 @@ The order is by confidence that the capability should exist in the final Stella
- `Ops > Operations`
- Notes:
- Detailed UX dossier: `docs/modules/ui/platform-ops-consolidation/README.md`
- Implementation sprint: `docs/implplan/SPRINT_20260307_026_FE_platform_ops_consolidation.md`
- Implementation sprint: `docs-archived/implplan/SPRINT_20260307_026_FE_platform_ops_consolidation.md`
### 5. Triage Explainability Workbench
- Type: `merge`
@@ -80,7 +80,7 @@ The order is by confidence that the capability should exist in the final Stella
- `/triage/artifacts` and `/triage/audit-bundles`
- Notes:
- Detailed UX dossier: `docs/modules/ui/triage-explainability-workspace/README.md`
- Implementation sprint: `docs/implplan/SPRINT_20260307_027_FE_triage_explainability_workspace.md`
- Implementation sprint: `docs-archived/implplan/SPRINT_20260307_027_FE_triage_explainability_workspace.md`
### 6. Workflow Visualization And Replay UX
- Type: `merge`
@@ -290,4 +290,4 @@ These branches probably contain valuable pieces, but the right home needs one mo
8. After that, tackle the big surfacing debt bucket: audit, offline, scanner, quota, topology, trust, unknowns.
Detailed topic-shape notes for items 2 through 6 now live under `docs/modules/ui/restoration-topics/`.
The shared placement contract for stray actions, drawers, tabs, and detail pages is captured in `docs/modules/ui/contextual-actions-patterns/README.md` and implementation sprint `docs/implplan/SPRINT_20260307_029_FE_contextual_actions_and_stray_surfaces.md`.
The shared placement contract for stray actions, drawers, tabs, and detail pages is captured in `docs/modules/ui/contextual-actions-patterns/README.md`, shipped implementation sprint `docs-archived/implplan/SPRINT_20260307_029_FE_contextual_actions_and_stray_surfaces.md`, and verification note `docs/features/checked/web/contextual-actions-patterns-ui.md`.

View File

@@ -115,6 +115,36 @@ Use stable, predictable query params and child routes instead of ad hoc local st
- row or bulk actions that preserve page context
- confirmation only for destructive or privilege-sensitive actions
## Shipped Implementation
The shared contract is now implemented under `src/Web/StellaOps.Web/src/app/shared/ui/` and should be treated as the default building block set for restoration work.
### Shipped primitives
- `context-route-state`
- central helpers for `tab`, `panel`, `drawer`, `returnTo`, `scope`, and `view`
- includes `readContextRouteState`, `readContextRouteParam`, `buildContextRouteParams`, and `buildContextReturnTo`
- `context-header`
- stable subject header with chips, context note, and return-to-context action
- `context-drawer-host`
- overlay or rail presentation with shared close behavior, escape handling, and testable route-state integration
- `list-detail-shell`
- responsive split list/detail layout for owner shells with one dominant list workflow
- `overview-card-groups`
- grouped overview cards with one-card-to-one-route behavior
- `tabbed-nav`
- now supports both classic tabs and owner-shell submenu pills, plus route command arrays and shared query params
### First adopted surfaces
- Watchlist uses the shared route-state, contextual header, tabs, and list-detail shell.
- Reachability uses the shared route-state, contextual header, and tabs.
- Operations uses the shared submenu and grouped overview-card patterns.
- Workflow Replay uses the shared route-state, contextual header, tabs, and drawer host.
### Delivery rule
- New restoration work should adopt these primitives before introducing new feature-local panel or route-state helpers.
- Context-preserving deep links should use `returnTo` instead of bespoke navigation metadata.
- Owner shells should prefer submenu pills, tabs, list-detail layouts, or drawers before creating another top-level route tree.
## Topic Mapping
### Watchlist
@@ -153,3 +183,4 @@ Use stable, predictable query params and child routes instead of ad hoc local st
- `docs/ui-analysis/05_ROUTE_SUMMARY_AND_OBSERVATIONS.md`
- `docs/modules/ui/architecture.md`
- `docs/modules/ui/architecture-rework.md`
- `docs/features/checked/web/contextual-actions-patterns-ui.md`

View File

@@ -13,7 +13,6 @@ Provide a living plan for UI deliverables, dependencies, and evidence.
- `SPRINT_20260307_009_DOCS_ui_component_preservation_map.md` - per-component preservation dossiers for unused and weakly surfaced console UI components.
- `SPRINT_20260307_022_FE_policy_vex_release_decisioning_studio.md` - canonical Decisioning Studio shell to unify policy, simulation, VEX decisioning, and release-context gate explanation.
- `SPRINT_20260307_023_DOCS_ui_restoration_topic_shapes.md` - documentation prerequisite for shell/menu/tab placements; not a product-delivery sprint by itself.
- `SPRINT_20260307_029_FE_contextual_actions_and_stray_surfaces.md` - ship the shared tabs, drawers, right rails, split views, and contextual detail primitives adopted by the restoration features.
## Latest evidence
- `docs/modules/ui/component-preservation-map/README.md` - root index for the first-pass preservation map.
@@ -27,6 +26,7 @@ Provide a living plan for UI deliverables, dependencies, and evidence.
- `docs/features/checked/web/operations-consolidation-ui.md` - shipped verification note for the canonical Operations shell, overview grouping, and legacy alias cutover.
- `docs/features/checked/web/triage-explainability-workspace-ui.md` - shipped verification note for the canonical triage artifact workspace, explainability rail, audit bundles, and security alias cutover.
- `docs/features/checked/web/workflow-visualization-replay-ui.md` - shipped verification note for the canonical run-detail graph, timeline, replay, evidence tabs, and workflow-editor preview reuse boundary.
- `docs/features/checked/web/contextual-actions-patterns-ui.md` - shipped verification note for the shared contextual route-state, headers, drawers, list-detail shells, grouped overview cards, and first adopted restoration surfaces.
- `docs/modules/ui/reachability-witnessing/README.md` - detailed witness and proof UX dossier plus cross-shell deep-link contract.
- `docs/modules/ui/platform-ops-consolidation/README.md` - detailed Operations overview taxonomy and legacy absorption plan.
- `docs/modules/ui/triage-explainability-workspace/README.md` - detailed artifact workspace and audit-bundle UX dossier.

View File

@@ -28,11 +28,11 @@ It answers four questions for each topic:
## Implementation Sprint Set
- `docs-archived/implplan/SPRINT_20260307_024_FE_identity_watchlist_shell.md` - shipped watchlist restoration
- `docs/implplan/SPRINT_20260307_025_FE_reachability_witnessing_merge.md`
- `docs/implplan/SPRINT_20260307_026_FE_platform_ops_consolidation.md`
- `docs/implplan/SPRINT_20260307_027_FE_triage_explainability_workspace.md`
- `docs-archived/implplan/SPRINT_20260307_025_FE_reachability_witnessing_merge.md` - shipped reachability witnessing restoration
- `docs-archived/implplan/SPRINT_20260307_026_FE_platform_ops_consolidation.md` - shipped platform ops consolidation
- `docs-archived/implplan/SPRINT_20260307_027_FE_triage_explainability_workspace.md` - shipped triage explainability restoration
- `docs-archived/implplan/SPRINT_20260307_028_FE_workflow_visualization_replay.md` - shipped workflow visualization and replay restoration
- `docs/implplan/SPRINT_20260307_029_FE_contextual_actions_and_stray_surfaces.md`
- `docs-archived/implplan/SPRINT_20260307_029_FE_contextual_actions_and_stray_surfaces.md` - shipped shared contextual primitives
## Placement Matrix

View File

@@ -93,7 +93,7 @@ One overview page plus grouped subroutes is enough.
## Detailed UX And Sprint
- Detailed UX dossier: `../platform-ops-consolidation/README.md`
- Implementation sprint: `../../../implplan/SPRINT_20260307_026_FE_platform_ops_consolidation.md`
- Implementation sprint: `../../../docs-archived/implplan/SPRINT_20260307_026_FE_platform_ops_consolidation.md`
## Corroborating Inputs

View File

@@ -97,7 +97,7 @@ These should deep-link into the same reachability surfaces:
## Detailed UX And Sprint
- Detailed UX dossier: `../reachability-witnessing/README.md`
- Implementation sprint: `../../../implplan/SPRINT_20260307_025_FE_reachability_witnessing_merge.md`
- Implementation sprint: `../../../docs-archived/implplan/SPRINT_20260307_025_FE_reachability_witnessing_merge.md`
## Corroborating Inputs

View File

@@ -108,7 +108,7 @@ These should be secondary tabs or a right-rail stack, not standalone routes.
## Detailed UX And Sprint
- Detailed UX dossier: `../triage-explainability-workspace/README.md`
- Implementation sprint: `../../../implplan/SPRINT_20260307_027_FE_triage_explainability_workspace.md`
- Implementation sprint: `../../../docs-archived/implplan/SPRINT_20260307_027_FE_triage_explainability_workspace.md`
## Corroborating Inputs