refactor(workbench): split editor state and components
This commit is contained in:
1 parent
caa3cb843f
commit
834470cfa1
23 files changed
+1219
-878
No files matched your search
@@ -2,4 +2,8 @@
|
||||
|
||||
Use typed React function components. `App.tsx` owns session/editor composition, while reusable map and UI concerns live in named components. Prefer the shared `ui/button.tsx` primitive for commands. Do not create business UI with `querySelector` or `innerHTML`.
|
||||
|
||||
Forms use controlled inputs and submit handlers. Keep map canvas DOM owned by OpenLayers and surrounding controls owned by React.
|
||||
Components expose explicit props for values and callbacks. A form component may own presentation-local state such as a select value, but it must not import `api`, mutate `WorkbenchState` directly, or implement save/preview/undo behavior. The composition root passes commands such as `stage`, `updateSignal`, or `onAccept`.
|
||||
|
||||
The inspector is composed from independent sections. Section components must preserve existing write semantics: ordinary v1 forms stage overrides, `lane-maneuver` uses the v2 session, and signal forms update the signal draft command. Do not make a generic form abstraction that hides these boundaries.
|
||||
|
||||
Forms use controlled inputs and submit handlers. Keep map canvas DOM owned by OpenLayers and surrounding controls owned by React. Extracting a component must preserve labels, default values, event ordering, and the current accordion behavior unless a separate product task approves a change.
|
||||
@@ -140,18 +140,16 @@ match `main` exactly. Guard once at construction, not per call site.
|
||||
while `compileGeometry()` ignores `profile.interval`. A control whose drag changes
|
||||
nothing is worse than no control.
|
||||
|
||||
### V1 override selection is not direct edit
|
||||
### Lane maneuver is v2 direct edit only
|
||||
|
||||
`lane-maneuver` is a saved v1 override for a discrete lane attribute, not a spatial
|
||||
constraint. Its click selection and inspector selector are intentionally available
|
||||
without `directEdit`: they stage `{ kind: 'lane-maneuver', laneId, maneuver }` and
|
||||
wait for the existing save/recompile path. Do not route them through `EditSession`,
|
||||
the preview endpoint, or a draggable element outline.
|
||||
`lane-maneuver` is a spatial direct-edit constraint. Its selector and draggable
|
||||
outline are available only in edit mode and must be routed through `EditSession` and
|
||||
the preview endpoint. It must never be added to the ordinary v1 staged override
|
||||
array, which is reserved for road, connector, and marking style overrides.
|
||||
|
||||
The distinction is observable: the ordinary workbench may select a turn-arrow part
|
||||
or lane centerline and show this selector, while the `directEdit` flag still means
|
||||
there are no edit sources, manifest requests, handles, ghosts, previews, or control
|
||||
marking outlines.
|
||||
With edit mode off, selecting a turn-arrow part may still show read-only element
|
||||
information, but it must not create a manifest request, ghost, preview, handle, or
|
||||
staged lane-maneuver override.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,5 +1,13 @@
|
||||
# Directory Structure
|
||||
|
||||
The Vite workbench lives in `workbench/client/`. Application code is under `src/`: `components/` for UI, `map/` for OpenLayers adapters, `lib/` for API clients, `types/` for API contracts, and `ui/` for shared primitives. The Node HTTP server remains `workbench/server.js`.
|
||||
The Vite workbench lives in `workbench/client/`. Application code is under `src/`:
|
||||
|
||||
Keep OpenLayers construction and source mutation outside page components; `src/components/MapCanvas.tsx` owns lifecycle and `src/map/layers.ts` owns the layer registry.
|
||||
- `components/` contains typed React view components and form sections. Components receive domain data and commands through props; they do not own cross-page persistence.
|
||||
- `hooks/` contains one stateful editing domain per hook (`useOverrideDraft`, `useDirectEditSession`, or `useTrafficSignalDraft`). Hooks may call the API boundary through injected commands, but must not share mutable module state.
|
||||
- `edit/` contains pure direct-edit models, projections, sessions, preview arbitration and geometry-unit helpers.
|
||||
- `map/` contains OpenLayers adapters. `MapCanvas.tsx` owns map lifecycle and `map/layers.ts` owns the layer registry and source updates.
|
||||
- `lib/` is the browser HTTP boundary; `types/` owns API and workbench contracts; `ui/` contains shared primitives.
|
||||
|
||||
`App.tsx` is the composition root: it loads server state, owns selection and page-level commands, and connects editing domains to the map and inspector. It must not contain substantial form implementations or a second copy of an editing protocol.
|
||||
|
||||
Keep OpenLayers construction and source mutation outside page components. The map is constructed once per mounted canvas; React re-renders and inspector extraction must not rebuild it or reset its view.
|
||||
@@ -1,3 +1,9 @@
|
||||
# Hook Guidelines
|
||||
|
||||
Use effects for imperative OpenLayers lifecycle only. `MapCanvas.tsx` constructs one map on mount, updates sources when server state changes, and updates visibility separately. Store callback-sensitive values such as selected road and scene mode in refs so stable OpenLayers style callbacks see current values.
|
||||
|
||||
Each custom hook owns one domain and exposes a typed command surface. The three existing edit domains are distinct: ordinary v1 staged overrides, v2 direct-edit session/preview, and traffic-signal drafts. A hook must not create a second undo stack or preview path for another domain.
|
||||
|
||||
Keep `EditSession`, `PreviewRequester`, signal history, and gesture refs stable across renders. Effects may synchronize external state, but a hook must not recreate a session or requester from ordinary state changes. Callback dependencies that are consumed by a stable OpenLayers listener belong in refs.
|
||||
|
||||
Hooks should return data and callbacks; they should not render JSX. API errors are converted to the existing status/reporting command at the composition boundary unless the hook owns a self-contained async view.
|
||||
@@ -15,12 +15,12 @@ This directory contains guidelines for frontend development. Fill in each file w
|
||||
| Guide | Description | Status |
|
||||
|-------|-------------|--------|
|
||||
| [Direct Edit Client](./direct-edit-client.md) | Handle/ghost/preview layer ownership, drag projection, session and save contracts | Filled |
|
||||
| [Directory Structure](./directory-structure.md) | Module organization and file layout | To fill |
|
||||
| [Component Guidelines](./component-guidelines.md) | Component patterns, props, composition | To fill |
|
||||
| [Hook Guidelines](./hook-guidelines.md) | Custom hooks, data fetching patterns | To fill |
|
||||
| [State Management](./state-management.md) | Local state, global state, server state | To fill |
|
||||
| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | To fill |
|
||||
| [Type Safety](./type-safety.md) | Type patterns, validation | To fill |
|
||||
| [Directory Structure](./directory-structure.md) | Module organization and file layout | Filled |
|
||||
| [Component Guidelines](./component-guidelines.md) | Component patterns, props, composition | Filled |
|
||||
| [Hook Guidelines](./hook-guidelines.md) | Custom hooks, data fetching patterns | Filled |
|
||||
| [State Management](./state-management.md) | Local state, global state, server state | Filled |
|
||||
| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | Filled |
|
||||
| [Type Safety](./type-safety.md) | Type patterns, validation | Filled |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -14,6 +14,8 @@ The workbench frontend uses Prettier as the source formatting authority. Code is
|
||||
|
||||
- Do not commit dense, manually minified, or single-line JSX/TypeScript.
|
||||
- Do not hand-format around Prettier output.
|
||||
- Do not leave a page component responsible for unrelated form implementations, API calls, and multiple edit histories after a named component or hook boundary exists.
|
||||
- Do not duplicate an edit protocol while extracting it. Move ownership and update call sites in one change so there is only one active path.
|
||||
|
||||
---
|
||||
|
||||
@@ -22,6 +24,8 @@ The workbench frontend uses Prettier as the source formatting authority. Code is
|
||||
- Run `npm run format` after editing frontend files.
|
||||
- Run `npm run format:check` in the validation gate.
|
||||
- Keep React components, hooks, types, and API clients in separately formatted modules once a component becomes non-trivial.
|
||||
- Keep `App.tsx` as a composition root. New domain behavior belongs in a hook or named component with typed props.
|
||||
- Refactors must preserve API call order, DOM-visible labels/defaults, and OpenLayers map identity unless the task explicitly changes them.
|
||||
|
||||
---
|
||||
|
||||
@@ -35,3 +39,4 @@ The workbench frontend uses Prettier as the source formatting authority. Code is
|
||||
|
||||
- Formatting check passes.
|
||||
- UI behavior changes do not rebuild the OpenLayers map unless the map lifecycle explicitly requires it.
|
||||
- Verify ordinary v1 staged, v2 direct-edit, and traffic-signal draft flows independently; passing one flow does not prove the others survived extraction.
|
||||
@@ -1,3 +1,12 @@
|
||||
# State Management
|
||||
|
||||
Use component `useState` for server state, selection, staged overrides, layer visibility and UI filters. `src/lib/api.ts` is the sole browser HTTP boundary. Keep staged overrides separate from persisted `WorkbenchState.overrides`; save them before compile.
|
||||
Use component `useState` for server state, selection, layer visibility and UI filters. Domain hooks own their draft state: ordinary v1 staged overrides remain separate from persisted `WorkbenchState.overrides`; v2 constraints remain inside `EditSession`; signal drafts remain separate until the signal save step.
|
||||
|
||||
`src/lib/api.ts` is the sole browser HTTP boundary. Presentational components never call it directly. `App` coordinates the fixed save order: ordinary v1 overrides, v2 document, signal draft, then compile and replace server state.
|
||||
|
||||
Whenever App accepts a fresh server `WorkbenchState` (initial load, import, compile,
|
||||
signal generation, or an accepted junction candidate), it must also refresh the
|
||||
signal draft's saved baseline. Otherwise discard can restore an older signal geometry
|
||||
after a later rotation or move.
|
||||
|
||||
Do not duplicate the whole `WorkbenchState` in multiple hooks. Hooks may use `setState` to update their owned slice and refs for non-serializable history, but there must be one current server state and one owner for each undo/redo stack. `lane-maneuver` belongs exclusively to v2 direct edit; it must not re-enter the v1 staged array.
|
||||
@@ -1,3 +1,5 @@
|
||||
# Type Safety
|
||||
|
||||
Define browser contracts in `src/types/state.ts` from actual workbench API payloads. Use `unknown` for extensible GeoJSON properties and comparison payloads, then narrow locally. Run `npm run test:client` after TypeScript changes; avoid `any` and broad assertions.
|
||||
|
||||
Component and hook boundaries must define named prop/return types for commands and domain data. Do not pass an untyped bag of callbacks or expose mutable refs as public props. Keep API payload narrowing in `lib/` or the owning domain adapter, not in each presentational component.
|
||||
Reference in new issue
Block a user