GovOPlaN/govoplan-core
1
0
Fork 0
Code Issues 44 Pull Requests Actions Packages Projects Releases Wiki Activity

Guided layered UI/UX overhaul for admin and configuration surfaces #225

New Issue
Open
opened 2026-07-09 12:57:01 +02:00 by zemion · 7 comments
zemion commented 2026-07-09 12:57:01 +02:00
Owner
Copy Link

The product vision now treats guided, layered UI as a quality gate. This issue tracks the cross-system UI/UX pass needed to make GovOPlaN usable for non-technical operators while retaining full power for expert users.

Vision reference: govoplan-core/docs/GOVOPLAN_MASTER_ROADMAP.md, section User Experience Direction.

Goals:

  • Replace option dumps with guided flows and progressive disclosure.
  • Avoid raw JSON as the primary configuration UI; every setting needs fields, validation, and help.
  • Use wizards for connector setup, package import, module lifecycle changes, policy changes, and destructive operations.
  • Use discovery where possible, for example Nextcloud base URL -> discovered WebDAV endpoint.
  • Explain blocked or unavailable actions in plain language, including who can fix the problem and where.
  • Reuse shared visual patterns, placement, modal behavior, problem lists, and empty/error states.

First implementation plan:

  1. Inventory all admin/settings/configuration screens and classify them as overview, repeated administration, setup wizard, policy editor, or destructive operation.
  2. Define shared WebUI primitives for layered configuration: wizard shell, collapsible advanced section, explanatory help affordance, actionable blocker callout, review step, and problem list.
  3. Apply the pattern first to file connectors and mail servers because they already share server/credential/policy concepts.
  4. Refactor module/package install flows to a step-based operator workflow with preflight, review, daemon handoff, and rollback explanation.
  5. Refactor policy and retention editors around effective value, source/provenance, local override, and reason for disabled edits.
  6. Add a recurring UX review checklist for new admin/configuration surfaces.

Acceptance criteria:

  • New shared components exist in core WebUI and are documented through local usage patterns.
  • File connector and mail server setup use the same layered server/credential/policy workflow.
  • Disabled actions expose actionable explanations rather than silent disabled states.
  • No primary admin/configuration flow requires JSON editing.
  • At least one connector setup flow performs guided discovery and fills technical fields for review.
  • Future issues can be split by module/surface from this umbrella issue.
The product vision now treats guided, layered UI as a quality gate. This issue tracks the cross-system UI/UX pass needed to make GovOPlaN usable for non-technical operators while retaining full power for expert users. Vision reference: `govoplan-core/docs/GOVOPLAN_MASTER_ROADMAP.md`, section `User Experience Direction`. Goals: - Replace option dumps with guided flows and progressive disclosure. - Avoid raw JSON as the primary configuration UI; every setting needs fields, validation, and help. - Use wizards for connector setup, package import, module lifecycle changes, policy changes, and destructive operations. - Use discovery where possible, for example Nextcloud base URL -> discovered WebDAV endpoint. - Explain blocked or unavailable actions in plain language, including who can fix the problem and where. - Reuse shared visual patterns, placement, modal behavior, problem lists, and empty/error states. First implementation plan: 1. Inventory all admin/settings/configuration screens and classify them as overview, repeated administration, setup wizard, policy editor, or destructive operation. 2. Define shared WebUI primitives for layered configuration: wizard shell, collapsible advanced section, explanatory help affordance, actionable blocker callout, review step, and problem list. 3. Apply the pattern first to file connectors and mail servers because they already share server/credential/policy concepts. 4. Refactor module/package install flows to a step-based operator workflow with preflight, review, daemon handoff, and rollback explanation. 5. Refactor policy and retention editors around effective value, source/provenance, local override, and reason for disabled edits. 6. Add a recurring UX review checklist for new admin/configuration surfaces. Acceptance criteria: - New shared components exist in core WebUI and are documented through local usage patterns. - File connector and mail server setup use the same layered server/credential/policy workflow. - Disabled actions expose actionable explanations rather than silent disabled states. - No primary admin/configuration flow requires JSON editing. - At least one connector setup flow performs guided discovery and fills technical fields for review. - Future issues can be split by module/surface from this umbrella issue.
zemion commented 2026-07-09 13:03:16 +02:00
Author
Owner
Copy Link

Decision ledger added and synced to the wiki:

  • Repository: govoplan-core/docs/UI_UX_DECISION_LEDGER.md
  • Wiki page: Repo-docs-UI-UX-DECISION-LEDGER

The ledger records binding UX decisions UX-001 through UX-009, the impact index, and the review checklist. The immediate product decisions to confirm before implementation are DUE-001 through DUE-006:

  1. Standard two-zone admin/configuration shell.
  2. Standard wizard step model.
  3. Explanation placement rules.
  4. Advanced-options contract.
  5. Structured blocker language contract.
  6. First migration surface: file connectors, then mail servers.

Implementation should not create new one-off admin/configuration patterns unless this ledger is revised first.

Decision ledger added and synced to the wiki: - Repository: `govoplan-core/docs/UI_UX_DECISION_LEDGER.md` - Wiki page: `Repo-docs-UI-UX-DECISION-LEDGER` The ledger records binding UX decisions `UX-001` through `UX-009`, the impact index, and the review checklist. The immediate product decisions to confirm before implementation are `DUE-001` through `DUE-006`: 1. Standard two-zone admin/configuration shell. 2. Standard wizard step model. 3. Explanation placement rules. 4. Advanced-options contract. 5. Structured blocker language contract. 6. First migration surface: file connectors, then mail servers. Implementation should not create new one-off admin/configuration patterns unless this ledger is revised first.
zemion commented 2026-07-09 13:05:34 +02:00
Author
Owner
Copy Link

Product decision recorded: DUE-001 through DUE-006 are green-lit and now marked accepted in govoplan-core/docs/UI_UX_DECISION_LEDGER.md.

Implementation may proceed with:

  1. UX inventory of admin/settings/configuration surfaces.
  2. Core WebUI primitives for the shared guided configuration pattern.
  3. File connector guided setup as the first converted surface.
  4. Mail server setup using the same pattern.

Future admin/configuration work should treat the accepted DUE decisions plus UX-001 through UX-009 as binding unless the ledger is explicitly revised first.

Product decision recorded: DUE-001 through DUE-006 are green-lit and now marked accepted in `govoplan-core/docs/UI_UX_DECISION_LEDGER.md`. Implementation may proceed with: 1. UX inventory of admin/settings/configuration surfaces. 2. Core WebUI primitives for the shared guided configuration pattern. 3. File connector guided setup as the first converted surface. 4. Mail server setup using the same pattern. Future admin/configuration work should treat the accepted DUE decisions plus UX-001 through UX-009 as binding unless the ledger is explicitly revised first.
zemion commented 2026-07-09 13:17:03 +02:00
Author
Owner
Copy Link

Implementation update, 2026-07-09:

  • Phase-0 inventory baseline added to govoplan-core/docs/UI_UX_DECISION_LEDGER.md and synced to wiki page Repo-docs-UI-UX-DECISION-LEDGER.
  • Core WebUI now has reusable guided-configuration primitives: GuidedConfigDialog, AdvancedOptionsPanel, ActionBlockerHint, and GuidedReviewList.
  • First file-connector UI slice is implemented in govoplan-files/webui/src/features/files/FileConnectorSettingsPanel.tsx: connection and credential create/edit flows now use wizard steps, review summaries, structured blocker hints, and collapsed advanced metadata/protocol/env fields.
  • Existing file connector API behavior is unchanged; this is a UX layering slice around the current profile/credential save paths.

Verification:

  • npm run build in govoplan-core/webui passed.
  • npm run audit:i18n-structural in govoplan-core/webui passed.
  • git diff --check passed for touched tracked core files; files module check has no tracked diff because the panel file is currently untracked in that repo state.

Remaining work on this issue:

  • Add real provider discovery/test inside the connector wizard, especially Nextcloud base URL to WebDAV endpoint.
  • Layer the central connector policy card using the same effective-policy/edit-modal pattern.
  • Migrate mail server settings to the same guided server/credential/policy structure.
  • Continue inventory conversion for module/package operations, retention/privacy, API keys, and user settings.
Implementation update, 2026-07-09: - Phase-0 inventory baseline added to `govoplan-core/docs/UI_UX_DECISION_LEDGER.md` and synced to wiki page `Repo-docs-UI-UX-DECISION-LEDGER`. - Core WebUI now has reusable guided-configuration primitives: `GuidedConfigDialog`, `AdvancedOptionsPanel`, `ActionBlockerHint`, and `GuidedReviewList`. - First file-connector UI slice is implemented in `govoplan-files/webui/src/features/files/FileConnectorSettingsPanel.tsx`: connection and credential create/edit flows now use wizard steps, review summaries, structured blocker hints, and collapsed advanced metadata/protocol/env fields. - Existing file connector API behavior is unchanged; this is a UX layering slice around the current profile/credential save paths. Verification: - `npm run build` in `govoplan-core/webui` passed. - `npm run audit:i18n-structural` in `govoplan-core/webui` passed. - `git diff --check` passed for touched tracked core files; files module check has no tracked diff because the panel file is currently untracked in that repo state. Remaining work on this issue: - Add real provider discovery/test inside the connector wizard, especially Nextcloud base URL to WebDAV endpoint. - Layer the central connector policy card using the same effective-policy/edit-modal pattern. - Migrate mail server settings to the same guided server/credential/policy structure. - Continue inventory conversion for module/package operations, retention/privacy, API keys, and user settings.
zemion commented 2026-07-09 13:31:52 +02:00
Author
Owner
Copy Link

Design correction, 2026-07-09:

The default file connector create/edit interaction has been changed from a stepper wizard to an adaptive full-state dialog.

Rationale recorded in govoplan-core/docs/UI_UX_DECISION_LEDGER.md as DUE-007:

  • Ordinary create/edit should show the full editable state in one consistent form.
  • The form adapts immediately when provider, credential mode, or policy mode changes, showing only relevant fields.
  • Editing an existing object must look like the state created earlier, not force the user through a linear setup path.
  • Wizard shells remain available for assisted setup, first-run guidance, import/discovery-heavy workflows, and operational preflight.

Implementation update:

  • govoplan-files/webui/src/features/files/FileConnectorSettingsPanel.tsx now uses adaptive dialogs for file connections and credentials.
  • GuidedConfigDialog remains exported in core for later assisted setup flows.
  • Core modal CSS was adjusted so the wizard shell fills its modal body and scrolls only inside the content pane.

Verification:

  • npm run build in govoplan-core/webui passed.
  • npm run audit:i18n-structural in govoplan-core/webui passed.
  • Targeted whitespace/diff checks passed.
Design correction, 2026-07-09: The default file connector create/edit interaction has been changed from a stepper wizard to an adaptive full-state dialog. Rationale recorded in `govoplan-core/docs/UI_UX_DECISION_LEDGER.md` as DUE-007: - Ordinary create/edit should show the full editable state in one consistent form. - The form adapts immediately when provider, credential mode, or policy mode changes, showing only relevant fields. - Editing an existing object must look like the state created earlier, not force the user through a linear setup path. - Wizard shells remain available for assisted setup, first-run guidance, import/discovery-heavy workflows, and operational preflight. Implementation update: - `govoplan-files/webui/src/features/files/FileConnectorSettingsPanel.tsx` now uses adaptive dialogs for file connections and credentials. - `GuidedConfigDialog` remains exported in core for later assisted setup flows. - Core modal CSS was adjusted so the wizard shell fills its modal body and scrolls only inside the content pane. Verification: - `npm run build` in `govoplan-core/webui` passed. - `npm run audit:i18n-structural` in `govoplan-core/webui` passed. - Targeted whitespace/diff checks passed.
zemion commented 2026-07-09 15:18:08 +02:00
Author
Owner
Copy Link

Implemented the next connector UI/workflow slice: shared connection tree now fills card bodies through LoadingFrame and keeps columns aligned with child indentation; file credential creation is only available from a parent connection row and uses UserRoundKey after bumping lucide-react to 1.23.0; required-field blockers now use field highlighting plus disabled-save hover feedback; WebDAV/Nextcloud endpoint discovery route and inline connection-dialog feedback were added; app rail navigation now goes through the unsaved-change guard. Updated the UI/UX decision ledger and synced the wiki with the discovery-feedback and compact blocker rules.

Implemented the next connector UI/workflow slice: shared connection tree now fills card bodies through LoadingFrame and keeps columns aligned with child indentation; file credential creation is only available from a parent connection row and uses UserRoundKey after bumping lucide-react to 1.23.0; required-field blockers now use field highlighting plus disabled-save hover feedback; WebDAV/Nextcloud endpoint discovery route and inline connection-dialog feedback were added; app rail navigation now goes through the unsaved-change guard. Updated the UI/UX decision ledger and synced the wiki with the discovery-feedback and compact blocker rules.
zemion commented 2026-07-09 15:40:57 +02:00
Author
Owner
Copy Link

Follow-up connector UI fixes: stabilized ConnectionTree action column so rows/header align; kept credential indentation inside the first column only; made the add-credential UserRoundKey action primary-colored; added a credential login test button in the secret section using a strict discovery probe; changed the local Nextcloud placeholder from /files/govoplan/ to /files/admin/ after confirming the Docker service returns 404 for govoplan and 207 for admin/webdav. Build and i18n audit pass; connector smoke passes for WebDAV and Nextcloud, SMB skipped unless smbprotocol is installed.

Follow-up connector UI fixes: stabilized ConnectionTree action column so rows/header align; kept credential indentation inside the first column only; made the add-credential UserRoundKey action primary-colored; added a credential login test button in the secret section using a strict discovery probe; changed the local Nextcloud placeholder from /files/govoplan/ to /files/admin/ after confirming the Docker service returns 404 for govoplan and 207 for admin/webdav. Build and i18n audit pass; connector smoke passes for WebDAV and Nextcloud, SMB skipped unless smbprotocol is installed.
zemion commented 2026-07-20 14:43:15 +02:00
Author
Owner
Copy Link

This is now the admin/configuration child of the product-wide interface pattern-language program add-ideas/govoplan#11. Its primitives and migrations should follow that shared taxonomy; Campaign #74 is the first full-domain pilot.

This is now the admin/configuration child of the product-wide interface pattern-language program add-ideas/govoplan#11. Its primitives and migrations should follow that shared taxonomy; Campaign #74 is the first full-domain pilot.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/api
HTTP API contracts, routers, schemas, or API smoke behavior.
area/auth
Authentication, sessions, access bootstrap, or login behavior.
area/db
Database sessions, models, transactions, or persistence primitives.
area/devex
Local developer workflow, scripts, tests, tooling, or release helpers.
area/docs
Durable documentation and project guidance.
area/governance
Governance policy, audit, privacy, retention, or compliance behavior.
area/marketing
Public website, product messaging, publication copy, or legal page content.
area/migrations
Alembic migrations, schema bootstrap, or persistence evolution.
area/module-system
Module discovery, manifests, capabilities, routing, or optional integrations.
area/rbac
Permissions, roles, delegation, or authorization policy.
area/release
Versioning, release locks, tags, packaging, or dependency pins.
area/security
Security posture, static analysis, supply-chain hardening, or vulnerability remediation.
area/tenancy
Tenant boundaries, provisioning, or tenant-scoped data behavior.
area/webui
Shared WebUI shell, frontend components, routing, or frontend tests.
audit/complexity
Complexity finding from Radon, Xenon, or equivalent maintainability scans.
audit/duplication
Duplicated-code finding from jscpd or equivalent similarity scans.
audit/false-positive
Audit finding reviewed as a narrow false positive or acceptable risk.
audit/needs-design
Audit finding that needs an architectural or product decision before implementation.
audit/quick-fix
Audit finding that appears narrow and directly fixable.
audit/structural
Audit finding that needs design, refactoring, or behavior review.
codex/needs-human
Needs an explicit human decision before Codex should implement.
codex/ready
Suitable for Codex to pick up with the existing issue context.
module/access
GovOPlaN access, identity, authentication, RBAC, and administration behavior.
module/addresses
GovOPlaN Addresses module behavior or integration.
module/admin
GovOPlaN Admin module behavior or integration.
module/appointments
GovOPlaN Appointments module behavior or integration.
module/audit
GovOPlaN Audit module behavior or integration.
module/calendar
GovOPlaN Calendar module behavior or integration.
module/campaign
GovOPlaN campaign module behavior or integration.
module/cases
GovOPlaN Cases module behavior or integration.
module/connectors
GovOPlaN Connectors module behavior or integration.
module/core
GovOPlaN core runner, shared primitives, shell, or extension points.
module/dataflow
GovOPlaN Dataflow module behavior or integration.
module/datasources
GovOPlaN governed datasource contracts, catalogs, and integrations.
module/dist-lists
GovOPlaN Distribution Lists module behavior or integration.
module/dms
GovOPlaN Dms module behavior or integration.
module/erp
GovOPlaN Erp module behavior or integration.
module/evaluation
GovOPlaN Evaluation module behavior or integration.
module/files
GovOPlaN files module behavior or integration.
module/fit-connect
GovOPlaN Fit Connect module behavior or integration.
module/forms
GovOPlaN Forms module behavior or integration.
module/identity
GovOPlaN Identity module behavior or integration.
module/identity-trust
GovOPlaN Identity Trust module behavior or integration.
module/idm
GovOPlaN Idm module behavior or integration.
module/ledger
GovOPlaN Ledger module behavior or integration.
module/mail
GovOPlaN mail module behavior or integration.
module/notifications
GovOPlaN Notifications module behavior or integration.
module/ops
GovOPlaN Ops module behavior or integration.
module/organizations
GovOPlaN Organizations module behavior or integration.
module/payments
GovOPlaN Payments module behavior or integration.
module/permits
GovOPlaN Permits module behavior or integration.
module/policy
GovOPlaN Policy module behavior or integration.
module/poll
GovOPlaN Poll module behavior or integration.
module/portal
GovOPlaN Portal module behavior or integration.
module/postbox
GovOPlaN Postbox module behavior or integration.
module/reporting
GovOPlaN Reporting module behavior or integration.
module/risk-compliance
GovOPlaN Risk Compliance module behavior or integration.
module/scheduling
GovOPlaN Scheduling module behavior or integration.
module/search
GovOPlaN Search module behavior or integration.
module/tasks
GovOPlaN Tasks module behavior or integration.
module/templates
GovOPlaN Templates module behavior or integration.
module/tenancy
GovOPlaN Tenancy module behavior or integration.
module/views
GovOPlaN governed task views, interface projections, and workflow view integration.
module/workflow
GovOPlaN Workflow module behavior or integration.
module/xoev
GovOPlaN Xoev module behavior or integration.
module/xrechnung
GovOPlaN Xrechnung module behavior or integration.
module/xta-osci
GovOPlaN Xta Osci module behavior or integration.
priority
p0
Immediate stop-the-line priority.
priority
p1
High priority for the next focused work window.
priority
p2
Normal planned priority.
priority
p3
Low priority or opportunistic cleanup.
source/backlog-import
Imported from markdown backlog, roadmap, plan, or TODO files.
source/security-audit
Created from a structured security or code-quality audit report.
source/todo-scan
Imported from inline TODO/FIXME/HACK markers by the Gitea TODO importer.
status
blocked
Cannot progress without a decision, dependency, credential, or external change.
status
in-progress
Currently being worked.
status
needs-info
Needs clarifying input before implementation can proceed safely.
status
ready
Ready for implementation.
status
triage
Needs review, ownership, priority, or acceptance criteria.
type
bug
A reproducible defect, regression, or incorrect behavior.
type
debt
Cleanup, refactoring, risk reduction, or deferred engineering work.
type
docs
Documentation, process, or developer workflow work.
type
feature
New user-visible behavior or platform capability.
type
task
Implementation, maintenance, migration, or operational work.
type
user-story
End-to-end user journey or real-world process story used to steer product slices.
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
zemion
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: GovOPlaN/govoplan-core#225
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?