Front End Patterns
Wavemap’s front end should keep generic UI behavior, page/domain orchestration, state ownership, transport details, and localized copy in separate layers.
Use this section when adding or changing reusable components, layout composition components, queryable pages, page workflow hooks, typeahead/search surfaces, saved views, draft state, or component label maps.
For the broader feature path, start with Feature Slice Workflow. For shared route, DTO, query, saved-view, role, and permission contracts, use API Contracts.
| Page | Use It For |
|---|---|
| Components | Reusable components, layout composition components, page/domain wrappers, workflow hooks, labels, and component/workflow testing posture. |
| State | State ownership, queryable pages, URL state, saved views, workflow draft state, and media draft boundaries. |
Core Split
Section titled “Core Split”Frontend code should separate four general work areas:
| Layer | Owns | Avoids |
|---|---|---|
| Reusable components | Interaction mechanics, accessibility behavior, layout options, generic visible chrome, and documented props. | Wavemap route constants, API calls, domain DTO mapping, page-specific translation keys. |
| Layout composition components | Page section structure, responsive arrangement, repeated page chrome, and visual grouping of prepared data. | Fetching data, owning URL state, making permission decisions, or becoming a generic primitive. |
| Page/domain wrappers | Product context, API hook usage, DTO-to-view mapping, localized labels, route state, and user-facing workflow. | Reimplementing generic popover, sheet, table, upload, carousel, pagination, or input logic. |
| Workflow hooks | Multi-step sequencing, diffing, retry posture, side effects, and UI-facing pending/error/warning state. | Rendering UI directly or hiding reusable endpoint hooks behind a giant page component. |
The goal is to make reusable components easy to use correctly while keeping page-specific behavior close to the route or domain that owns it.
For example, an artists collection page should let the page frame own URL query state, endpoint capabilities, selected
view mode, and saved-view persistence. Layout composition components can own the page sections that arrange filters,
results, tabs, sidebars, headers, and empty-state placement. Table, Pagination, gallery cards, search inputs, and
popovers should receive already-normalized data, handlers, labels, and formatters. If the flow later crosses into backend
route shape or saved-view schema, graduate that part into API Contracts instead
of rediscovering it inside the component tree.
Workflow hooks live with Components because they keep page and layout components from becoming request choreography surfaces. They also coordinate a distinct class of application state, so State calls out how workflow draft state fits beside URL, saved-view, query-cache, and media draft state.
What Does Not Belong Here
Section titled “What Does Not Belong Here”Keep these elsewhere:
- API route, DTO, permission, and query-control contract details: API Contracts.
- Backend association-row modeling: Domain Relationships.
- Collection query controls, URL state, and saved views: Query Controls And Browsing State.
- Translation sheet, backend error, email, and component-label workflows: i18n Contributor Workflows.
- Media workflow proof lanes: Media Workflow And Validation.
- Media storage, ingest, delivery, and deployed-dev boundaries: Media Storage And Delivery.
- Branch-specific implementation history and open checklists: app-local roadmaps or
apps/wavemap-docs/working-notes.
Related Pages
Section titled “Related Pages”- Feature Slice Workflow for the broader cross-app implementation path.
- Local Development Runtime for local frontend, backend, i18n, and Playwright runtime setup.
- API Contracts for shared contracts consumed by frontend pages.
- Domain Relationships for relationship surface patterns.
- Query Controls And Browsing State for queryable page patterns.
- i18n Contributor Workflows for adding reusable component label maps.
- Testing Overview for layer selection and command surfaces.