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

feat: consolidate shared UI and harden browser authority for release

Browse Source
This commit is contained in:
zemion
2026-09-08 01:35:05 +02:00
parent ac40774785
commit b75ca34295
143 changed files with 8664 additions and 752 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API_CLIENT_CACHE_CONTRACT.md
+35
View File
@@ -0,0 +1,35 @@
# Shared API client cache and authority boundaries
All optional WebUI modules use the Core API client. Its bounded in-memory caches
are an optimization, never an authorization mechanism. The backend must check
the current principal, tenant, and permissions even for conditional GETs.
- Identical simultaneous safe requests can share one network request. Requests
with caller-owned cancellation are independent.
- Responses allowing reuse have at most a 750 ms recent-response window.
`no-store` and `Vary: *` responses are not retained. `no-cache` and zero-age
responses require a server check; permitted ETags retain conditional GET
support without bypassing authorization. This follows the relevant
[HTTP cache-control semantics](https://www.rfc-editor.org/rfc/rfc9111.html#section-5.2.2).
- Explicit `cache: "no-store"`, `"reload"`, or `"no-cache"` reads bypass older
response data and supersede older requests for that resource. Reload is not a
mutation. Owning read helpers must pass these options through pagination.
- Writes invalidate caches before execution and again on settlement, including
failures whose server outcome may be uncertain. Reads started before or
during the write cannot seed reusable data after it finishes.
- The shell calls `clearApiReadCache()` before explicit auth updates and when
refreshing authoritative session data. API-settings changes, clearing the
token, authentication expiry, and changes to the paired session/CSRF cookie
also invalidate both stored and in-flight reuse. Cookie observation also
covers sign-in/out in another tab; it does not read the HttpOnly session token.
- Interactive sign-in and sign-out clear a previously saved automation key.
Explicit key-based connection settings still select the key's identity;
profile-only updates preserve settings identity to avoid reload loops.
- Expired responses from superseded reads or downloads do not trigger a login
prompt in a newer session.
- Every completion (including 304) must still own its cache slot and generation
before storing anything. An old caller may receive its own result, so feature
components must continue guarding displayed state against obsolete requests.
Regression coverage: `npm run test:api-client-cache` uses the real client and
isolated network fixtures. No live API or account data is involved.
docs/DATAGRID_SIZING_CONTRACT.md
+68 -3
View File
@@ -1,8 +1,14 @@
# DataGrid Sizing Contract
Auto-height grids reserve no empty vertical scrollbar gutter. The table fills
its card to the right edge; an actual constrained vertical scrollbar still
occupies its normal space. `Card bodyLayout="table"` provides an explicit
zero-inset surface, including with loading wrappers and padded notices. The
Organizations/IDM browser fixtures assert row geometry, not just outer shells.
`DataGrid` turns every declared track into a deterministic pixel layout after
its container has a measurable width. The same contract is used on initial
layout, container resize, persisted-layout restore, and pointer resize.
layout, container resize, persisted-layout restore, and pointer/keyboard resize.
## Column Declarations
@@ -17,6 +23,54 @@ layout, container resize, persisted-layout restore, and pointer resize.
- `maxWidth` bounds direct user growth and free/constrained compensation. In a
cover layout it is a preferred maximum: passive tracks may exceed it when
that is necessary to keep the table flush with its container.
- `columnType: "actions"` marks a custom action/control column. Canonical
`TableActionGroup` content is recognized automatically, even in existing
column declarations. Use `sticky: "end"` for the normal row-action surface.
## Action Visibility and Constrained Containers
Action tracks reserve the width of actual buttons, disabled-action wrappers,
reserved empty-state slots, gaps, and cell padding. A historic `width: 72`
preference therefore cannot clip a four-button action group. Ordinary data text
does not participate in this content measurement; long field values do not
silently widen all tracks. Changes to the rendered action set are remeasured.
`TableActionButton` remains a compact 36 px control, including the Add action
in an empty grid. Never stretch it with a last-column `.btn { width: 100% }`
rule. Its shared maximum width and fixed flex basis protect against broad
consumer button rules, which can otherwise feed stretched widths back into
action-track measurement and consume the data area.
When the full group needs more than half the scroll viewport, its measured
minimum is capped at half the viewport and the group wraps. Explicit hard
minima remain authoritative. Custom action groups should use wrapping-capable
flex layouts and semantic groups, preferably composing `TableActionGroup`.
The grid's physical width matches its pixel tracks, including horizontal
overflow, so right-sticky actions remain inside the correct scroll bounds.
If explicitly wide or persisted sticky tracks would obscure the readable data
area, horizontal stickiness is released until space returns. No columns or
actions are hidden: the labelled scroll region is focusable and supports native
keyboard scrolling. Vertical header stickiness remains available.
## Resizing Controls
Drag a resize handle with a mouse, pen, or touch pointer. Pointer capture keeps
the drag active when it leaves the handle. Escape or pointer cancellation
restores the layout before that drag; releasing the pointer commits it. Losing
window focus ends a drag without leaving the table stuck in resizing mode.
Each handle is a focusable vertical separator exposing its current and allowed
widths. Left/Right changes its width by 10 px; Shift+Left/Right uses 40 px. Enter
or a double-click resets that column's explicit override to the declared sizing
rules. Other columns retain their preferences, so cover/compensation constraints
still apply. These operations only change personal browser layout, never rows.
Deutsch: Spalten lassen sich mit Maus, Stift oder Touch ziehen. Escape verwirft
den laufenden Ziehvorgang. Am fokussierten Trenner ändern Links/Rechts die Breite
um 10 px, mit Umschalt um 40 px. Eingabe oder Doppelklick setzt die persönliche
Breite dieser Spalte zurück. Schmale Aktionenspalten umbrechen ihre Schaltflächen;
breite Tabellen bleiben horizontal scrollbar.
## Layout Modes
@@ -39,7 +93,7 @@ the column remains stopped until the pointer crosses the same boundary again.
Only the pixel layout resulting from an explicit user resize is persisted,
together with the container width at which the user selected it.
Persisted widths are keyed by a signature containing column IDs, declared
widths and bounds, resize affordances, sticky placement, initial fit, and resize
widths and bounds, sort/filter/resize affordances, column type, sticky placement, initial fit, and resize
behavior. A changed signature discards the old override and recomputes the
declared layout.
@@ -51,7 +105,10 @@ contracts, persisted tracks may shrink toward their hard minima. The layout
retains only the amount of horizontal overflow deliberately created by the
user; an exact-cover layout therefore remains exact-cover at narrower widths.
Legacy snapshots from the former hard-pixel persistence contract are discarded
once and recomputed from the declared column layout.
once and recomputed from the declared column layout. The current `v3` signature
also discards old snapshots that predate action and header-control minima;
sort/filter preferences remain intact. Measured action widths are not included
in the signature, so changing rows does not erase user sizing intent.
## Regression Matrix
@@ -72,3 +129,11 @@ once and recomputed from the declared column layout.
`webui/tests/data-grid-actions.test.tsx` also verifies the rendered fixed-cover
shape and guards against reintroducing a synthetic buffer cell.
`webui/conformance/tests/data-grid-layout.spec.ts` exercises the real rendered
grid with deliberately undersized action preferences, constrained containers,
horizontal scrolling, changing/empty action sets, keyboard and pointer resizing,
Escape cancellation, remount persistence, responsive contraction and restoration,
free/content mode, and constrained compensation. Run with
`npm run test:conformance -- data-grid-layout.spec.ts`; its isolated test server
is stopped automatically afterwards.
docs/DEPLOYMENT_OPERATOR_GUIDE.md
+34
View File
@@ -74,6 +74,19 @@ Operator rule: take a database backup before applying migrations or destructive
module retirement. For non-SQLite databases, configure deployment-specific
backup/restore hooks for the module installer.
#### Ownership-history upgrade repair
Core revision `c58a2d7e9f10` repairs existing ownership-transfer tables that
predate the `decisions` column. Such installations can otherwise return HTTP
500 from `/api/v1/ownership/transfers`, including Campaign Settings. Apply the
normal forward migrations after taking a backup; do not stamp a revision or
recreate the table. The repair is available on both migration tracks, adds only
the missing non-null JSON column, and initializes old rows with an empty list.
It preserves owners, approvals, transfer states, revisions, timestamps, and any
existing decision history. Historical decisions are not reconstructed or
invented. Downgrading this repair retains the additive column and its evidence.
Verify that ownership-transfer listing and Campaign Settings load after upgrade.
### PostgreSQL Production Target
PostgreSQL is the primary development and production target. SQLite remains
@@ -408,6 +421,27 @@ To stop PostgreSQL and Redis when the launcher exits:
GOVOPLAN_STOP_PROFILE_DEPENDENCIES_ON_EXIT=1 tools/launch/launch-production-like-dev.sh
```
## Development WebUI Dependency Caches
The application and browser-conformance harness share installed JavaScript
packages but must not share Vite's optimized-dependency cache. The application
uses `webui/node_modules/.vite/govoplan-app`; the conformance harness uses
`webui/node_modules/.vite/govoplan-conformance`. Keep these explicit sibling
directories when adding development or test configurations. Setting a different
Vite `root` alone does not isolate this cache.
A shared cache can make otherwise healthy Workflow, Dataflow or deferred editors
show “The resource could not be loaded.” The browser then reports an asset such
as `@xyflow_react.js` with HTTP 504 `Outdated Optimize Dep`, while the corresponding
API still returns HTTP 200. This is not a missing workflow permission or a reason
to rerun a pipeline. Preserve unsaved work, let the existing development server
reload the corrected configuration (or restart that WebUI server), then reload
the browser. Do not clear application data, change grants or restart delivery
workers to repair a frontend dependency cache.
Run `npm run test:vite-cache-isolation` in `govoplan-core/webui` to verify the real
resolved Vite configurations without starting servers or overwriting caches.
## Module Install/Uninstall Operations
Use Admin > System > Modules for planning. The running API server validates and
docs/INTERFACE_PATTERN_MIGRATION.md
+38 -1
View File
@@ -17,7 +17,7 @@ domain modules own their compositions.
| Full-canvas workspace | Navigation/content and list/detail canvases that own pane geometry and scrolling | Navigation and split variants, primary-pane width, pane-owned or contained scrolling, responsive stacking or navigation collapse, pane labels, and contextual-help identity are centralized without encoding domain navigation | `WorkspaceLayout.tsx`, `workspace-layout.test.tsx`, Core Settings, Access administration, Docs, Organizations, Campaign, Templates, Approvals, and `check-shared-webui-layouts.py`; the raw-workspace exception baseline is empty |
| Full-height module frame | Outer module landmark and viewport/container sizing | `WorkspaceFrame` centralizes surface, overflow, box sizing, accessible naming, help identity, and application-viewport height so modules do not copy the `100vh - shell` frame | `WorkspaceFrame.tsx`, `layout-primitives.test.tsx`, Dataflow, Workflow, Datasources, Distribution Lists, Notifications, Tasks, Scheduling, Forms, Portal, Projects, Records, and Reporting |
| Responsive action toolbar | Domain-neutral action and filter grouping for pages, workspaces, editors, and overlays | Density, surface, grouping, flexible space, accessible naming, toolbar help identity, and responsive wrapping are centralized while modules retain action wording, authority, and consequence | `ActionToolbar.tsx`, `layout-primitives.test.tsx`, WYSIWYG, Calendar, Files, Forms, Templates, and the product-wide primitive check |
| Semantic page and pane action bars | Overview, collection, detail, editor, and workspace intent declared independently from frame geometry; full-canvas panes add workspace/collection/detail/editor scope | Core renders leading Reload from a guarded descriptor; editor persistence owns clean, dirty, invalid, saving, failed, and conflict feedback plus guarded Discard and far-right Save; destructive actions occupy an explicit named boundary; read-only surfaces do not invent Save | `PageActionBar.tsx`, `WorkspaceActionBar.tsx`, `PAGE_LAYOUT_USAGE_GUIDELINES.md`, component and browser conformance, every headed page and full-canvas workspace, and the discovery-based `check-shared-webui-layouts.py` |
| Semantic page and pane action bars | Overview, collection, detail, editor, and workspace intent declared independently from frame geometry; full-canvas panes add workspace/collection/detail/editor scope | Core renders guarded Reload in the right-aligned group immediately before Create/primary actions; editor persistence owns clean, dirty, invalid, saving, failed, and conflict feedback plus guarded Discard and far-right Save; destructive actions occupy an explicit named boundary; read-only surfaces do not invent Save | `PageActionBar.tsx`, `WorkspaceActionBar.tsx`, `PAGE_LAYOUT_USAGE_GUIDELINES.md`, component and browser conformance, every headed page and full-canvas workspace, and the discovery-based `check-shared-webui-layouts.py` |
| Catalogue and state composition | Search/filter bars, selectable navigation lists, count badges, and empty/blocked/error panels | Width, surface, wrap, selection geometry, title/description truncation, numeric emphasis, state sizing, tone and action placement are centralized; modules retain query behavior, object state and consequences | `FilterBar.tsx`, `SelectionList.tsx`, `CountBadge.tsx`, `StatePanel.tsx`, `layout-primitives.test.tsx`, and list/detail modules across Cases, Committee, Dataflow, Forms, Notifications, Portal, Postbox, Projects, Records, Reporting, Tasks, Templates, and Workflow |
| Content and form grids | Equal-column content, field, and native-form geometry | Explicit 1–4 columns, standard gaps, item spans, alignment, and named narrow/workspace/standard/wide collapse points replace generic and module-prefixed copies; unequal domain tracks remain local | `ContentGrid.tsx`, `layout-primitives.test.tsx`, Core dashboard/settings/mail, Calendar dialogs, Forms editor, Datasources, Postbox, Campaign, administration surfaces, and the product-wide primitive check |
| Content sections | Repeated editor/detail section surfaces | Border, surface, compact/default density, stacked flow and block rhythm are centralized without encoding section contents | `ContentSection.tsx`, `layout-primitives.test.tsx`, Datasources, Distribution Lists, Templates, Dataflow, and Workflow |
@@ -27,9 +27,46 @@ domain modules own their compositions.
| Dialog anatomy | Shared outer dialog plus composable body and footer regions | Size and administration variants, body padding, descriptions, notices, fixed action wrapping, native form flow, and section grouping are centralized; focus trapping and stack lifecycle remain unchanged | `Dialog.tsx`, `DialogAnatomy.tsx`, `dialog-focus.test.tsx`, `layout-primitives.test.tsx`, Addresses, Calendar, Records, Datasources, Distribution Lists, Files, and Templates |
| Definition-editor visuals | Reusable graph palette, canvas chrome, node icon/port geometry, empty overlay and floating activity state | Core owns visual and responsive anatomy while node/edge types, validation, execution, provenance and workflow semantics remain in Dataflow or Workflow | `DefinitionPalette.tsx`, `DefinitionNodeIcon.tsx`, `FloatingStatus.tsx`, shared definition styles, Dataflow and Workflow structure/build checks |
| Shared configuration primitives | Cross-module component contract | Dialog focus, blocker structure, disabled-action focus, route/page/field/action F1 help, unsaved changes, confirmation, loading, alerts, problem lists, and policy provenance are centralized | Core component tests, `CONTEXTUAL_HELP_CONTRACT.md`, and module-permutation build |
| Measured operation feedback | `LoadingFrame` over existing content | Use `indicator="none"` with native measured progress for long-running operations; `progress={null}` means unknown, never a synthetic percentage. Keep dialog content inert and close controls disabled until success or error. Existing consumers retain their loading indicator. | Files archive inspection/extraction, layout primitive tests, managed-archive browser conformance |
## Boundary
Side-rail customization uses the shared `NavigationPreferenceEditor` for system,
tenant, personal, and View layouts. Modules and labelled separators share one
ordered list, with pointer drag-and-drop, keyboard reordering, and explicit
add/remove actions. Consumers retain persistence and dirty-state ownership;
mounting the editor does not create a draft change. See
`NAVIGATION_LAYOUT_CONTRACT.md` for inheritance, locked items, optional-module
preservation, and collapsed-rail grouping.
Action columns use `TableActionGroup` or declare `columnType: "actions"` when
their composition differs. DataGrid owns measured action minima, initial column
allocation, persistent resizing, and local horizontal scrolling; consumers must
not compensate with clipped overflow or copied fixed widths. See
`DATAGRID_SIZING_CONTRACT.md`. Dialog forms use `DialogForm` and `FormGrid` inside
the shared size-bounded dialog. Do not add a content minimum wider than the
panel's padded interior. Genuinely wide content, such as a table, owns its own
local scroller instead of making the entire dialog scroll horizontally.
In `FormGrid` and `FormLayout`, direct `FormField` and `ToggleSwitch` items
align their controls at the row's lower edge. A single control inside a
`GridItem` follows the same rule. Labels may wrap without shifting adjacent
switches up into the label row. Do not add per-module top margins or empty
labels; single-column layouts must not retain a phantom label spacer.
Credential editors resolve public reference labels when opened. A failed
save displays its error inside the dialog and keeps the entered draft for an
explicit retry. While a write is pending, repeated submission, edits, and
dialog dismissal are disabled; no configured secret is read back from storage.
The shared rich-text editor emits content changes only for actual document
edits. Mounting, read-only changes, loading a saved value, and switching between
visual and source inspection must preserve the controlled HTML without marking
the owning page dirty. This is especially important for legacy Campaign HTML:
merely visiting Template must not normalize it or require a save on leaving.
The WYSIWYG lifecycle browser conformance covers both visual and legacy-source
initial content, as well as genuine typing.
Files and Mail are the first two external consumers of the layered
server/credential/policy pattern. Their own repositories retain provider
discovery, transport behavior, authorization, and migration evidence. Remaining
docs/MODULE_ARCHITECTURE.md
+10
View File
@@ -1635,6 +1635,16 @@ Unsigned/unhashed remote bundles are skipped. This keeps remote loading a
controlled deployment option rather than a replacement for release package
builds.
A failed local WebUI package import receives one automatic retry after 250 ms.
Descriptor validation still fails closed; it is not bypassed by the retry.
If an enabled local module still cannot load, the signed-in shell warns that its
screens and integrations may be unavailable and identifies the module. This is
a loading failure, not an uninstall. Save other drafts before manually reloading
the page; there is no automatic page reload or persistent retry loop. A verified
remote fallback that successfully loads clears that module's warning. Packages
absent from the optional build graph remain absent, and effective View filtering
continues to control which loaded UI capabilities are exposed.
## Maintenance Mode
Maintenance mode is the required operating state for package install/uninstall
docs/NAVIGATION_LAYOUT_CONTRACT.md
+64
View File
@@ -0,0 +1,64 @@
# Shared navigation layout contract
Core owns `NavigationPreferenceEditor`, ordered layout resolution, and rail
rendering. Admin, Tenancy, personal Settings and Views reuse this editor. They
own loading, authorization, Save, Reload and dirty-state guards; the editor
emits a draft only after a real edit. A drag onto the same position, keyboard
pickup/drop without movement, and opening inherited settings do not save or
create an override.
## Stored document and precedence
The version-1 navigation document retains `order`, `hidden` and `locked` and
adds optional `separators`, each containing a stable `separator:`-prefixed ID
and an optional plain-text label of at most 120 characters. Separator IDs and
module navigation IDs occupy the same `order` list. Separators are presentation
metadata and never become routes, modules, permissions or authorized surfaces.
Omitting `separators` or using null preserves inherited grouping. An explicit
empty array removes grouping. Resetting the entire navigation document to null
removes that scope's override. Existing order-only documents remain readable;
the editor materializes group markers into a draft only when edited. Unknown
optional-module order IDs remain stored when currently visible items move, so
uninstalling or temporarily disabling a module does not destroy its preference.
User order and visibility take precedence over tenant and system preferences.
System and tenant visibility locks accumulate; lower scopes cannot hide those
destinations, but may move them. Views may supply a navigation presentation
inside the already authorized and View-filtered destination set. An explicit
personal order/layout or visibility preference takes precedence over that
presentation, not over authorization or the View's surface restrictions.
Views cannot introduce locks. When multiple modules contribute one product
entry, it inherits the earliest effective rail position/section and all
authorized contributors' locks; this does not change operational route
selection. An owner alias in View layout refers to that composed entry.
## Interaction and reuse
Drag the handle to move either a module or separator before/after another row.
The handle also supports Space to pick up, arrow keys to move, Enter to drop,
and Escape to restore the pre-drag draft. Up/down buttons offer the same moves.
Add module restores an available hidden entry; Remove only hides navigation,
never uninstalls a module or deletes records. Add separator inserts a new
optional group label. Remove separator changes grouping only.
Expanded rails display group labels without divider lines. Collapsed rails
replace these labels with horizontal group dividers; empty groups are not
rendered. Both modes use the same resolved order.
The editor receives product-area metadata to show inherited grouping and uses
container-responsive rows rather than a fixed dialog/page width. Its English
and German labels load with the editor, not the initial shell bundle.
Give the ordered list a full-span `GridItem` when a settings page contains
multiple cards; do not squeeze the entire editor into an otherwise half-empty
two-column settings grid. Central spacing tokens provide real row padding and
separation at both wide and narrow sizes, covered by computed-style assertions.
## Verification
Core navigation unit tests and HTTP settings/profile tests cover persistence,
separator inheritance, explicit flat layouts, reset and locks. Module-capability
tests cover View aliases, composed destinations and personal precedence. The
browser conformance suite tests all four editor scopes, pointer/keyboard moves,
no-op cleanliness, unavailable-module preservation, collapsed dividers and a
German narrow read-only layout. Use the same shared component for future
navigation-definition surfaces rather than implementing another sortable list.
docs/PAGE_LAYOUT_USAGE_GUIDELINES.md
+55 -5
View File
@@ -69,11 +69,61 @@ page or pane action bar.
| Page kind | Leading group | Trailing group |
| --- | --- | --- |
| Overview | Reload when refreshable, then context | Help, then ordinary primary actions |
| Collection | Reload when refreshable, then collection context such as export | Help, then Create at the far right |
| Detail | Reload when refreshable, then object context | Help, ordinary primary actions, then a separated destructive group |
| Editor | Reload only when refresh is a distinct safe operation, then context | Dirty state, Help, ordinary primary actions, separated destructive actions, Discard, then Save at the far right |
| Workspace | Reload when the coordinated projection can become stale, then task context | Help, ordinary primary actions, then a separated destructive group |
| Overview | Context | Help, Reload when refreshable, then ordinary primary actions |
| Collection | Collection context such as export | Help, Reload when refreshable, then Create at the far right |
| Detail | Object context | Help, Reload when refreshable, ordinary primary actions, then a separated destructive group |
| Editor | Context | Dirty state, Help, Reload if distinctly safe, ordinary primary actions, separated destructive actions, Discard, then Save at the far right |
| Workspace | Task context | Help, Reload when refreshable, ordinary primary actions, then a separated destructive group |
Reload and Create belong to the same right-aligned group, in that order. A
collection-wide toolbar stays above its workspace, not inside the left tree or
conditionally inside an editor. Changing selection or opening an editor must
not remove it. Permission-blocked creation remains visible with an explanation.
On narrow screens the trailing group wraps while retaining right alignment and
the same DOM/keyboard order.
Use `Card bodyLayout="table"` for table surfaces, including tables wrapped by
`LoadingFrame`. This removes body padding explicitly, without relying on the
number of children or negative margins. Place any meaningful explanation or
warning in a padded `ContentSection`; do not add a redundant tagline to every
table. Use `ContentGrid` for sibling cards so spacing does not depend on fragments.
Use `MultiSelectFilter` for standalone list facets. It and DataGrid share the
same checkbox body and Select all / Deselect all behavior. `null` means no
restriction, `[]` means no matches, and multiple values mean OR within a facet.
Apply remote filters before server pagination/limits and discard stale reads.
Do not replace this with rows of toggles or implement a second checkbox menu.
The dropdown's body portal escapes clipped containers. Inside Core dialogs it
joins the existing dialog stack: Tab/Shift+Tab stay in the filter, Space toggles
the focused checkbox, and Escape closes only the filter and restores its
trigger. Long option labels wrap without widening the popup.
Keep facet definitions, URL serialization and request cancellation in one owning
module adapter when the same search appears on a page and in an overlay. Do not
translate an explicit empty selection into an unrestricted backend query. Keep
legacy API meanings at the adapter boundary; retain scope and unrelated URL
parameters when clearing filters. A query, context, account or tenant change
invalidates both initial and cursor requests, including results still visible
during a debounce interval.
Explorer workspaces keep collection commands in a persistent header. Files
uses Reload, Create folder, then primary Upload; frequent selected-item actions
stay near the list. Group less-common selection and connection operations in
labelled domain dialogs using `Dialog`, `FormSection` and shared action bars,
with an explicit destructive section. Do not move an overloaded toolbar into
another ungrouped row. Mail's read-only workspace has one Reload for its current
profile, folder, index and preview; narrower refreshes belong in Mailbox tools.
Do not invent a New or Save button on a workspace that owns neither workflow.
Reload must not become import, synchronization, delivery or another mutation.
Explicit Reload reads must bypass short-lived client response reuse (for
example, pass `cache: "no-store"` through the owning read API), including each
page of a refreshed listing. Routine navigation may retain normal deduplication.
Conformance must observe a fresh request, not just an enabled Reload button.
Tree icons/disclosure controls expand and collapse; labels select. A module's
`ExplorerTree.onOpen` must not toggle expansion. Use occurrence-specific node
IDs when the same semantic record appears in multiple branches; selection and
ancestor expansion must follow the clicked occurrence, not every copy.
Reload means re-fetch or re-evaluate the current surface. A page declaring
`refreshable` must provide it, and a non-refreshable page must not use Reload as
docs/THEMING.md
+6
View File
@@ -54,3 +54,9 @@ but their surrounding controls must still use the shared tokens.
custom-override validation/application, and representative
Campaign, Calendar, Files, and Mail token consumption. The check runs before a
production WebUI build.
Runtime validation and token application live in the dependency-free
`webui/src/components/appearanceOverrides.ts`; both the shell and the shared
editor use it. The shell must not import the editor to apply an existing theme:
settings controls load with their route, while valid saved colors apply
synchronously and invalid documents still fail closed before any token is set.
docs/UI_UX_DECISION_LEDGER.md
+1 -1
View File
@@ -57,7 +57,7 @@ contestability, responsibility, and traceability at the point of action.
| UX-031 | Public controls and extension contributions use stable, module-namespaced interface identities. Shared controls expose `interfaceId` and `helpTopicId`; generated source anchors are inventory evidence, not a substitute for an explicit ID when documentation, policy, or automation refers to the control. | Accepted | Core and module WebUIs |
| UX-032 | `F1` resolves help from the focused field or action, then its dialog/section/page and registered route. Focused contexts retain the page fallback; Docs applies audience and permission filtering and falls back to visible module documentation. | Accepted | Core shell, Docs, and all module WebUIs |
| UX-033 | Global search is the left-most titlebar command, immediately before language selection. Its icon, `F3`, and `Ctrl`/`Cmd`+`K` all open the same permission-aware search overlay; the titlebar does not reserve a persistent query field. | Accepted | Core shell and Search WebUI |
| UX-034 | Every headed `PageLayout` declares one of `overview`, `collection`, `detail`, `editor`, or `workspace` independently from its standalone/workspace/embedded geometry. Its actions use the matching semantic `PageActionBar`: a refreshable page must provide Reload in the leading slot; collections keep Create far right; read-only pages do not invent Save. | Accepted | Core and all module WebUIs |
| UX-034 | Every headed `PageLayout` declares one of `overview`, `collection`, `detail`, `editor`, or `workspace` independently from its standalone/workspace/embedded geometry. Its actions use the matching semantic `PageActionBar`: refreshable pages provide Reload in the right-aligned trailing group immediately before Create/primary actions; collections keep Create far right; read-only pages do not invent Save. The trailing placement supersedes the earlier leading-Reload rule (2026-09-07, Core #295). | Accepted | Core and all module WebUIs |
| UX-035 | Editor action bars expose clean, dirty, and saving state; always retain Discard immediately before the far-right Save; centrally disable both while clean or saving; and participate in the unsaved-change navigation guard. Danger actions occupy the explicit separated destructive group after ordinary actions and before editor persistence. | Accepted | Core and all module WebUIs |
## Confirmed Implementation Decisions
docs/WEBUI_BUNDLE_BUDGETS.md
+15
View File
@@ -59,6 +59,14 @@ The first budgeted full-product build reported:
## Verification
Development startup explicitly prebundles the Excel reader's browser/universal
entrypoints and the lazy rich-text editor's Tiptap dependencies. These are
Core-installed vendor dependencies, not eager optional-module imports. This
avoids first-time Campaign/Template navigation triggering a second dependency
optimization and page reload. Module descriptors and pages remain lazy, and
production bundle budgets remain unchanged. The Core interface-pattern check
verifies this include list and keeps optional GovOPlaN modules excluded.
```bash
cd /mnt/DATA/git/govoplan-core/webui
npm run build
@@ -69,3 +77,10 @@ npm run test:module-permutations
The build gate also catches accidental eager imports: a page pulled into the
entry closure consumes the initial budget, while an oversized page or module
descriptor consumes the asynchronous chunk budget.
The startup shell imports appearance validation/application from the pure
`appearanceOverrides.ts` runtime. Settings-only color controls, JSON import/export,
and previews remain in `AppearanceOverridesEditor.tsx` behind the existing lazy
Settings route. Importing a runtime helper from a module that also owns editor
components can accidentally pull the entire editor into the startup chunk.
Public helper exports remain compatible; theme application is still synchronous.
docs/migration-release-baselines.json
+497
View File
@@ -2271,6 +2271,503 @@
"release": "0.1.18",
"squash_policy": "reviewed-manual",
"track": "release"
},
{
"heads": [
{
"owner": "govoplan-notifications",
"revision": "6e2f91ab4c70"
},
{
"owner": "govoplan-poll",
"revision": "6e7f8a9b0c1d"
},
{
"owner": "govoplan-dashboard",
"revision": "7b9d2f4a6c8e"
},
{
"owner": "govoplan-tasks",
"revision": "7c4d9a2e1f30"
},
{
"owner": "govoplan-records",
"revision": "8a6c4e2f1b3d"
},
{
"owner": "govoplan-voting",
"revision": "8b9c0d1e2f3a"
},
{
"owner": "govoplan-tickets",
"revision": "8d1f4b7a2c5e"
},
{
"owner": "govoplan-workflow-engine",
"revision": "8d5a2f7c1b4e"
},
{
"owner": "govoplan-quick-access",
"revision": "9a4e6c2d8f10"
},
{
"owner": "govoplan-helpdesk",
"revision": "9e2a5c8f1b4d"
},
{
"owner": "govoplan-files",
"revision": "a2b3c4d5e6f8"
},
{
"owner": "govoplan-files",
"revision": "a2b3c4d5e6f9"
},
{
"owner": "govoplan-dataflow",
"revision": "a3d7f1c5e9b2"
},
{
"owner": "govoplan-templates",
"revision": "a3f7c9d2e1b4"
},
{
"owner": "govoplan-mail",
"revision": "a4c5d6e7f809"
},
{
"owner": "govoplan-organizations",
"revision": "a61e4d9c72b8"
},
{
"owner": "govoplan-wiki",
"revision": "a7c2e9f4b1d6"
},
{
"owner": "govoplan-cases",
"revision": "a7c4e2f9b1d6"
},
{
"owner": "govoplan-mandates",
"revision": "a8b1c2d3e4f5"
},
{
"owner": "govoplan-approvals",
"revision": "a91c4e72b5d8"
},
{
"owner": "govoplan-policy",
"revision": "a9c4e7b2d5f8"
},
{
"owner": "govoplan-search",
"revision": "b2c3d4e5f607"
},
{
"owner": "govoplan-tenancy",
"revision": "b3d8e1f4a6c2"
},
{
"owner": "govoplan-risk-compliance",
"revision": "b9c0d1e2f3a4"
},
{
"owner": "govoplan-services",
"revision": "b9c2d3e4f5a6"
},
{
"owner": "govoplan-audit",
"revision": "b9e2f5a8c3d6"
},
{
"owner": "govoplan-parties",
"revision": "c0d3e4f5a6b7"
},
{
"owner": "govoplan-connectors",
"revision": "c0f1a2b3c4d5"
},
{
"owner": "govoplan-idm",
"revision": "c2d3e4f5a6b7"
},
{
"owner": "govoplan-identity-trust",
"revision": "c3f5a7b9d1e2"
},
{
"owner": "govoplan-projects",
"revision": "c4a1e8f2d6b9"
},
{
"owner": "govoplan-core",
"revision": "c58a2d7e9f10"
},
{
"owner": "govoplan-views",
"revision": "c6f2a9d4e7b1"
},
{
"owner": "govoplan-reporting",
"revision": "c8d5e2f6a9b3"
},
{
"owner": "govoplan-datasources",
"revision": "d1a7c3e9f5b2"
},
{
"owner": "govoplan-decisions",
"revision": "d1e4f5a6b7c8"
},
{
"owner": "govoplan-calendar",
"revision": "d24e5f607182"
},
{
"owner": "govoplan-docs",
"revision": "d3e7a1c5f9b2"
},
{
"owner": "govoplan-forms-runtime",
"revision": "d6a8b0c2e4f6"
},
{
"owner": "govoplan-addresses",
"revision": "d6e8f9a0b1c2"
},
{
"owner": "govoplan-scheduling",
"revision": "d7a4c1e8f205"
},
{
"owner": "govoplan-postbox",
"revision": "d8b4f1a6c9e2"
},
{
"owner": "govoplan-committee",
"revision": "d8b9f0a1c2e3"
},
{
"owner": "govoplan-access",
"revision": "d8f1b4e7a0c3"
},
{
"owner": "govoplan-encryption",
"revision": "e5b7c9d1f3a4"
},
{
"owner": "govoplan-payments",
"revision": "e7b9c1d3f5a7"
},
{
"owner": "govoplan-dist-lists",
"revision": "e7c3a9d1b5f2"
},
{
"owner": "govoplan-campaign",
"revision": "f3c7a9d2e6b1"
}
],
"owner_heads": [
{
"owner": "govoplan-access",
"revisions": [
"d8f1b4e7a0c3"
]
},
{
"owner": "govoplan-addresses",
"revisions": [
"d6e8f9a0b1c2"
]
},
{
"owner": "govoplan-approvals",
"revisions": [
"a91c4e72b5d8"
]
},
{
"owner": "govoplan-audit",
"revisions": [
"b9e2f5a8c3d6"
]
},
{
"owner": "govoplan-calendar",
"revisions": [
"d24e5f607182"
]
},
{
"owner": "govoplan-campaign",
"revisions": [
"f3c7a9d2e6b1"
]
},
{
"owner": "govoplan-cases",
"revisions": [
"a7c4e2f9b1d6"
]
},
{
"owner": "govoplan-committee",
"revisions": [
"d8b9f0a1c2e3"
]
},
{
"owner": "govoplan-connectors",
"revisions": [
"c0f1a2b3c4d5"
]
},
{
"owner": "govoplan-core",
"revisions": [
"c58a2d7e9f10"
]
},
{
"owner": "govoplan-dashboard",
"revisions": [
"7b9d2f4a6c8e"
]
},
{
"owner": "govoplan-dataflow",
"revisions": [
"a3d7f1c5e9b2"
]
},
{
"owner": "govoplan-datasources",
"revisions": [
"d1a7c3e9f5b2"
]
},
{
"owner": "govoplan-decisions",
"revisions": [
"d1e4f5a6b7c8"
]
},
{
"owner": "govoplan-dist-lists",
"revisions": [
"e7c3a9d1b5f2"
]
},
{
"owner": "govoplan-docs",
"revisions": [
"d3e7a1c5f9b2"
]
},
{
"owner": "govoplan-encryption",
"revisions": [
"e5b7c9d1f3a4"
]
},
{
"owner": "govoplan-files",
"revisions": [
"a2b3c4d5e6f8",
"a2b3c4d5e6f9"
]
},
{
"owner": "govoplan-forms",
"revisions": [
"e1f2a3b4c5d6"
]
},
{
"owner": "govoplan-forms-runtime",
"revisions": [
"d6a8b0c2e4f6"
]
},
{
"owner": "govoplan-helpdesk",
"revisions": [
"9e2a5c8f1b4d"
]
},
{
"owner": "govoplan-identity",
"revisions": [
"5c6d7e8f9a10"
]
},
{
"owner": "govoplan-identity-trust",
"revisions": [
"c3f5a7b9d1e2"
]
},
{
"owner": "govoplan-idm",
"revisions": [
"c2d3e4f5a6b7"
]
},
{
"owner": "govoplan-mail",
"revisions": [
"a4c5d6e7f809"
]
},
{
"owner": "govoplan-mandates",
"revisions": [
"a8b1c2d3e4f5"
]
},
{
"owner": "govoplan-notifications",
"revisions": [
"6e2f91ab4c70"
]
},
{
"owner": "govoplan-organizations",
"revisions": [
"a61e4d9c72b8"
]
},
{
"owner": "govoplan-parties",
"revisions": [
"c0d3e4f5a6b7"
]
},
{
"owner": "govoplan-payments",
"revisions": [
"e7b9c1d3f5a7"
]
},
{
"owner": "govoplan-policy",
"revisions": [
"a9c4e7b2d5f8"
]
},
{
"owner": "govoplan-poll",
"revisions": [
"6e7f8a9b0c1d"
]
},
{
"owner": "govoplan-postbox",
"revisions": [
"d8b4f1a6c9e2"
]
},
{
"owner": "govoplan-projects",
"revisions": [
"c4a1e8f2d6b9"
]
},
{
"owner": "govoplan-quick-access",
"revisions": [
"9a4e6c2d8f10"
]
},
{
"owner": "govoplan-records",
"revisions": [
"8a6c4e2f1b3d"
]
},
{
"owner": "govoplan-reporting",
"revisions": [
"c8d5e2f6a9b3"
]
},
{
"owner": "govoplan-risk-compliance",
"revisions": [
"b9c0d1e2f3a4"
]
},
{
"owner": "govoplan-scheduling",
"revisions": [
"d7a4c1e8f205"
]
},
{
"owner": "govoplan-search",
"revisions": [
"b2c3d4e5f607"
]
},
{
"owner": "govoplan-services",
"revisions": [
"b9c2d3e4f5a6"
]
},
{
"owner": "govoplan-tasks",
"revisions": [
"7c4d9a2e1f30"
]
},
{
"owner": "govoplan-templates",
"revisions": [
"a3f7c9d2e1b4"
]
},
{
"owner": "govoplan-tenancy",
"revisions": [
"b3d8e1f4a6c2"
]
},
{
"owner": "govoplan-tickets",
"revisions": [
"8d1f4b7a2c5e"
]
},
{
"owner": "govoplan-views",
"revisions": [
"c6f2a9d4e7b1"
]
},
{
"owner": "govoplan-voting",
"revisions": [
"8b9c0d1e2f3a"
]
},
{
"owner": "govoplan-wiki",
"revisions": [
"a7c2e9f4b1d6"
]
},
{
"owner": "govoplan-workflow-engine",
"revisions": [
"8d5a2f7c1b4e"
]
}
],
"recorded_at": "2026-09-07T23:29:20Z",
"release": "0.1.45",
"squash_policy": "reviewed-manual",
"track": "release"
}
],
"version": 1