Files
road-compiler/.trellis/spec/frontend/hook-guidelines.md
T

1.1 KiB

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.