diff --git a/workplans/RAIL-FAB-WP-0009-graph-explorer-ui-refinement.md b/workplans/RAIL-FAB-WP-0009-graph-explorer-ui-refinement.md index 4338018..e29cf81 100644 --- a/workplans/RAIL-FAB-WP-0009-graph-explorer-ui-refinement.md +++ b/workplans/RAIL-FAB-WP-0009-graph-explorer-ui-refinement.md @@ -39,15 +39,21 @@ Refinement should focus on: - a calmer, denser toolbar that still exposes the important controls - clearer information architecture for the graph, selection details, - orientation hints, saved views, and hidden elements + orientation hints, saved views, node visibility, and edge visibility - map-first behavior where the graph remains the dominant surface - useful empty, loading, and error states -- visual encodings that make repo/service/interface/dependency/binding layers +- visual encodings that make repo/service/interface/dependency/binding node types distinguishable without becoming noisy +- explicit node-type and edge-type controls that support multi-selection +- a filtering model that separates hiding from removing entities from layout +- contextual controls that explain which attributes and modifiers apply to + which node and edge types +- floating map navigation controls and selection anchors that do not depend on + changing node borders - better onboarding-gap and unresolved-dependency workflows - URL and browser-local saved views that are understandable to a human user - responsive behavior that remains usable on laptop and narrow screens -- keyboard, focus, contrast, and screen-reader basics +- bubble-help explanations, keyboard, focus, contrast, and screen-reader basics - explicit seams for a later repo-scoping adapter and shared engine extraction ## Extraction Guardrail @@ -81,8 +87,10 @@ Acceptance notes: overrides, saved views, copied state URLs, and reset behavior. - Capture a concise refinement backlog in repo docs or the workplan. - Identify which issues block real use and which can wait for extraction. +- Confirm where the current UI still says `Layer`, where global controls like + Review and Unresolved are ambiguous, and which terms need bubble help. -### T02 - Layout And Information Architecture +### T02 - Node And Edge Control Architecture ```task id: RAIL-FAB-WP-0009-T02 @@ -91,19 +99,27 @@ priority: high state_hub_task_id: "751a2fc5-2263-48b0-9ef2-d55e37a0735c" ``` -Refine the toolbar, side panel, detail sections, saved-view controls, legend, -hidden-summary surface, and orientation hints so the graph remains central and -the controls are easier to scan. +Refine terminology, toolbar structure, side panel placement, map controls, +saved-view controls, legend, hidden-summary surface, and orientation hints so +the graph remains central and the controls are easier to scan. Acceptance notes: +- Replace user-facing `Layer` wording with `Nodes`, `Node type`, or + `Node types`. Internal manifest fields may keep `layer` until extraction if + that avoids churn. +- Replace the single node layer selector with a multi-select node type control. +- Add a multi-select edge type control for showing and hiding relationships by + edge type. +- Move pan, zoom, fit, focus, and reset navigation controls into a floating map + menu. - Reduce visual clutter in the toolbar without hiding core workflows. - Give selection details, orientation workflows, saved views, and legend predictable places. - Make hidden/blurred overrides and active filters easy to understand. - Keep the first screen as the working map, not documentation. -### T03 - Visual Encoding And Graph Readability +### T03 - Graph Readability, Layout Semantics, And Selection Anchors ```task id: RAIL-FAB-WP-0009-T03 @@ -112,38 +128,51 @@ priority: high state_hub_task_id: "3e60397c-c833-4bd7-ba1b-b754b203dade" ``` -Improve graph readability through better layer styling, labels, edge treatment, -selection affordances, unresolved/onboarding markers, and layout defaults. +Improve graph readability through better node-type styling, labels, edge +treatment, selection affordances, unresolved/onboarding markers, layout +defaults, and repo-local layout affinity. Acceptance notes: -- Layer colors are distinguishable and not dominated by one hue family. +- Node type colors are distinguishable and not dominated by one hue family. - Node and edge labels do not overwhelm dense views. - Selected, hovered, hidden, blurred, unresolved, and registered-only states are visually distinct. +- Selection is represented by an arrow or anchor pointing to the focused entity + rather than by relying on border changes. +- A selected entity can be hidden and unhidden without losing the selection + anchor; the anchor changes only when focus changes. +- Repo-local nodes stay closer together than cross-repo relationships, while + servers and deployments bind tightly to their runtime/deployment entities and + more loosely to service repos. - Default layout gives a useful first impression with the current registry data. -### T04 - Orientation Workflow Polish +### T04 - Filter Rule Builder And Visibility Semantics ```task id: RAIL-FAB-WP-0009-T04 status: todo -priority: medium +priority: high state_hub_task_id: "1b446ac8-eeba-4de6-9a32-d7f980d70b93" ``` -Make the Fabric-specific orientation workflows easier to use for service -dependencies, interface consumers, onboarding gaps, unresolved dependencies, -and saved operational contexts. +Design and implement an optional filtering panel that can express detailed +node and edge rules without turning type-specific attributes into unexplained +global controls. Acceptance notes: -- Selecting a service shows a readable dependency/provider chain. -- Selecting an interface shows consumers and impact context. -- Registered-only repos are visible as actionable onboarding gaps. -- Saved local views have understandable names, status, and sharing behavior. +- Users can create a list of rules that target nodes or edges by type and by + supported attributes. +- Type-specific concepts such as Review and Unresolved appear only when they + apply to the selected node or edge types, either as contextual controls or + rule templates. +- Rules can apply modifiers such as show, hide, blur, highlight, or remove. +- Node and edge filtering supports two explicit result modes: hide while + preserving the current layout, or remove from layout and redraw the graph. +- The active rule list is inspectable, editable, reorderable, and resettable. -### T05 - Accessibility, Responsiveness, And Failure States +### T05 - Bubble Help, Accessibility, Responsiveness, And Failure States ```task id: RAIL-FAB-WP-0009-T05 @@ -153,10 +182,16 @@ state_hub_task_id: "67a9cbc9-ebaa-4cb1-bec9-46bf250faf41" ``` Harden the graph explorer UI for basic accessibility, responsive use, and -failure handling before it becomes a candidate shared engine. +failure handling before it becomes a candidate shared engine. Explain the +domain terms directly where users encounter them. Acceptance notes: +- Add bubble-help explanations to graph terms and controls, including Nodes, + Node types, Edge types, Layout, Review, Unresolved, Hide, Remove, Blur, + Focus, Fit, and saved views. +- Bubble help must explain what the control changes, whether it affects layout, + and why a term might not apply to every node or edge type. - Controls have useful labels, focus order, and keyboard-accessible behavior. - Text fits on narrow and desktop viewports. - Loading, empty graph, fetch failure, and missing Cytoscape states are @@ -179,7 +214,34 @@ Acceptance notes: - Identify remaining Fabric-specific assumptions in the UI shell. - Confirm which controls should be manifest-driven before extraction. +- Confirm that user-facing node and edge terminology can be supplied through + manifest labels or host-provided vocabulary without leaking Fabric internals. +- Confirm that the rule-panel data model can support repo-scoping manifests as + well as Fabric ecosystem manifests. - Update `docs/graph-explorer-operations.md` or contract docs with any refined engine boundary. - Recommend whether the next workplan should be repo-scoping adapter parity or one more Fabric-side UI hardening pass. + +### T07 - Orientation Workflow Polish + +```task +id: RAIL-FAB-WP-0009-T07 +status: todo +priority: medium +state_hub_task_id: "6cf1fb8b-9d50-4550-942a-69bc29d14eaa" +``` + +Make the Fabric-specific orientation workflows easier to use for service +dependencies, interface consumers, onboarding gaps, unresolved dependencies, +and saved operational contexts after the node, edge, and rule controls are in +place. + +Acceptance notes: + +- Selecting a service shows a readable dependency/provider chain. +- Selecting an interface shows consumers and impact context. +- Registered-only repos are visible as actionable onboarding gaps. +- Saved local views have understandable names, status, and sharing behavior. +- Orientation workflows reuse the same hide/remove, node type, edge type, and + selection anchor semantics as the rest of the map.