diff --git a/workplans/STATE-WP-0043-dashboard-ui-experience.md b/workplans/STATE-WP-0043-dashboard-ui-experience.md new file mode 100644 index 0000000..9c51a1a --- /dev/null +++ b/workplans/STATE-WP-0043-dashboard-ui-experience.md @@ -0,0 +1,268 @@ +--- +id: STATE-WP-0043 +type: workplan +title: "Dashboard UI Experience Improvements" +domain: custodian +repo: state-hub +status: ready +owner: codex +topic_slug: custodian +created: "2026-05-19" +updated: "2026-05-19" +state_hub_workstream_id: "028f60d0-8f72-4426-9267-3e6ed69a5223" +--- + +# Dashboard UI Experience Improvements + +## Summary + +Address the active dashboard-improvement suggestions and fold them into a +coherent UI pass that makes State Hub easier to operate day to day. The focus is +not a visual redesign; it is better operational affordances: clearer repository +identity in TPSC views, safe status-editing controls for tasks and workstreams, +cleaner feedback workflow states, and more consistent reusable dashboard +patterns. + +## Current Findings + +Existing active UI feedback records: + +- `07ee477f-a800-4687-8ae9-c82a9bed095b` — TPSC GDPR Warnings / Per-Repo + Breakdown should show the repository name instead of an id, and link to the + repository in Gitea in a new tab. +- `de2d14b7-c85e-4ac1-8a12-7c69af9942fa` — Workstream / Tasks should allow + changing workstream and task statuses from the dashboard. + +Inspection notes: + +- `dashboard/src/tpsc.md` builds the Per-Repo Breakdown from snapshots and uses + `snap.repo_id` directly. It does not enrich rows from `/repos/`, so the table + cannot show names, slugs, domains, or remote URLs. +- `dashboard/src/tasks.md`, `dashboard/src/tasks/[id].md`, and + `dashboard/src/workstreams/[id].md` display status as read-only even though + `PATCH /tasks/{id}` and `PATCH /workstreams/{id}` already exist. +- Marking a task `done` through the current task PATCH endpoint can create a + heuristic token event when no token fields are supplied. UI status changes + need to make that side effect deliberate. +- `dashboard/src/ui-feedback.md` only treats `finished` and `wont_fix` as + closed, so legacy `resolved` feedback can still appear as active. +- `CUST-WP-0003` already owns the WHI KPI-card work. This workplan should not + duplicate that implementation; it should only align shared UI patterns around + it. + +## Out of Scope + +- Reworking the overall dashboard information architecture. +- Replacing Observable Framework or adding a frontend framework. +- Implementing the WHI KPI card already tracked by `CUST-WP-0003`. +- Adding authentication or authorization around dashboard mutations. + +## T01 — Triage Feedback Workflow States + +```task +id: STATE-WP-0043-T01 +status: todo +priority: high +state_hub_task_id: "2aaeb57e-26aa-438d-bfd8-4943c8b0b136" +``` + +Normalize the UI-feedback workflow so actionable and closed suggestions are +shown in the correct sections. + +Implementation notes: + +- Treat `finished`, `wont_fix`, `resolved`, and `addressed` as closed in + `dashboard/src/ui-feedback.md`, or migrate legacy records to `finished` if the + API data model prefers canonical workflow statuses. +- Keep `submitted`, `analyse`, `plan`, `implement`, `test`, and `review` as the + active workflow. +- Add notes or status transitions to the two active feedback records once this + workplan is synced into State Hub. +- Confirm the UI Feedback KPI counts match the visible Active and Closed lists. + +Done when the UI Feedback page no longer mixes resolved legacy records into the +active queue and the two live suggestions are clearly visible as planned work. + +## T02 — Improve TPSC Per-Repo Breakdown + +```task +id: STATE-WP-0043-T02 +status: todo +priority: high +state_hub_task_id: "b6fe5e8e-80f6-439f-8ddc-47e65218f041" +``` + +Make the TPSC Per-Repo Breakdown identify repositories by useful human labels +and link to the source repo when a web-safe remote URL is available. + +Implementation notes: + +- Fetch `/repos/` in `dashboard/src/tpsc.md` and build lookup maps by `id` and + `slug`. +- Resolve each snapshot row to a repo object before rendering. +- Show the repo name and slug, not the raw UUID. +- Link to `remote_url` in a new tab when it is already an HTTP(S) URL. For + non-web remotes such as `gitea-remote:coulomb/state-hub.git`, show a clear + non-linked slug unless a reliable Gitea URL transform already exists locally. +- Use `target="_blank"` with `rel="noopener noreferrer"`. +- Preserve the existing service maturity chips and latest-snapshot behavior. + +Done when the active suggestion +`07ee477f-a800-4687-8ae9-c82a9bed095b` is satisfied and unknown/missing repos +degrade gracefully. + +## T03 — Design Safe Status Editing Controls + +```task +id: STATE-WP-0043-T03 +status: todo +priority: high +state_hub_task_id: "11166491-2c7a-4007-9820-e0707e71556c" +``` + +Define and implement a shared status-editing control that can be reused by task +and workstream pages without surprising side effects. + +Implementation notes: + +- Add a small dashboard component, for example + `dashboard/src/components/status-control.js`, that renders a compact status + select or segmented action control. +- Support task statuses: `todo`, `in_progress`, `blocked`, `done`, and + `cancelled`. +- Support workstream statuses from `WORKSTREAM_STATUSES`. +- Use `apiFetch` for PATCH requests, with disabled, saving, success, and error + states. +- Prevent parent row/modal click handlers from firing when the control is used. +- For task transitions to `done`, handle the current token-event behavior + explicitly: either collect optional token metadata, show a confirmation that a + heuristic token event will be created, or add a backend-safe status-only path + before enabling one-click completion. + +Done when status editing has one reusable implementation and destructive or +side-effectful transitions are guarded. + +## T04 — Add Detail-Page Status Editing + +```task +id: STATE-WP-0043-T04 +status: todo +priority: high +state_hub_task_id: "34b29724-bd4b-416e-ab55-1d37132490dd" +``` + +Add status controls to the places where operators naturally inspect a single +task or workstream. + +Implementation notes: + +- Add a task status control to `dashboard/src/tasks/[id].md`. +- Add a workstream status control to `dashboard/src/workstreams/[id].md`. +- Add task status controls to the Tasks table inside + `dashboard/src/workstreams/[id].md`. +- Refresh or locally update displayed rows after a successful PATCH. +- Keep the raw field table for audit/debug context, but make the primary status + affordance visible in the summary area. + +Done when the active suggestion +`de2d14b7-c85e-4ac1-8a12-7c69af9942fa` works from detail pages. + +## T05 — Add List-Page Status Editing + +```task +id: STATE-WP-0043-T05 +status: todo +priority: medium +state_hub_task_id: "0562bd05-d67c-4fe2-b501-166650d7129a" +``` + +Extend safe status editing to the high-volume list views after the detail-page +path is solid. + +Implementation notes: + +- Add task status controls to `dashboard/src/tasks.md` table rows. +- Add workstream status controls to `dashboard/src/workstreams.md` table rows if + the table structure can accommodate them without crowding. +- Keep filters stable after edits. +- Do not allow row-click modal behavior to conflict with status controls. +- Show a compact error state near the edited row if a PATCH fails. + +Done when common status changes can be made from list views without navigating +away and without breaking table scanning. + +## T06 — Consolidate Reusable UI Patterns + +```task +id: STATE-WP-0043-T06 +status: todo +priority: medium +state_hub_task_id: "7b055f11-25e2-45cb-80ac-d2d175fb5a1f" +``` + +Reduce one-off inline UI code in the touched surfaces so future dashboard work +stays consistent. + +Implementation notes: + +- Reuse or extend `entity-modal.js`, `workplan-status.js`, `field-help.js`, and + `config.js` rather than adding page-local copies of status maps and API + behavior. +- Prefer shared status badges and compact action controls over repeated inline + color styles. +- Align empty, loading, offline, and save-error states across the touched pages. +- Keep the dashboard dense and operational rather than turning it into a + marketing-style layout. +- Preserve existing help overlays and the shift-click suggestion workflow. + +Done when the changed pages share status/control primitives and have visibly +consistent spacing, labels, and failure states. + +## T07 — Close the Feedback Loop + +```task +id: STATE-WP-0043-T07 +status: todo +priority: medium +state_hub_task_id: "0b182fff-c100-468c-afed-91918483638f" +``` + +Make the UI feedback workflow reflect the work after implementation. + +Implementation notes: + +- Add implementation notes to the two relevant technical-debt records. +- Move each suggestion through the workflow to `review` when the code is ready + for the original suggester. +- Move to `finished` only after verification or operator confirmation. +- Update relevant docs under `dashboard/src/docs/` if controls or behavior + changed in a way operators need to understand. + +Done when the dashboard suggestions page tells the same story as the shipped UI. + +## T08 — Verification + +```task +id: STATE-WP-0043-T08 +status: todo +priority: high +state_hub_task_id: "9d59cae4-c2a8-43e1-8a28-6344e22653b0" +``` + +Verify the UI changes against both code and running dashboard behavior. + +Implementation notes: + +- Run the dashboard build from `dashboard/`. +- Run the relevant backend tests if any API behavior changes. +- Use the local dashboard preview with the local API and exercise: + - TPSC Per-Repo Breakdown with linked and unlinked repos. + - Task status transitions, including a guarded `done` transition. + - Workstream status transitions. + - Offline/error behavior for failed PATCH requests. + - UI Feedback active/closed counts. +- Check desktop and mobile widths for table overflow, clipped text, and + overlapping controls. + +Done when the implementation is build-clean, manually verified in the browser, +and any intentional residual risks are documented.