Publish ITWorx Pulse source

docs/engineering/FRONTEND_STANDARDS.md

@@ -0,0 +1,92 @@
+# Frontend standards
+
+## Architecture
+
+Recommended modules:
+
+```text
+app-shell
+auth
+routing
+i18n
+design-system
+dashboards
+widgets
+metrics
+inventory
+alerts
+incidents
+events
+settings
+operations
+```
+
+Feature modules own routes, queries, views and tests. Shared UI remains domain-neutral.
+
+## State
+
+- URL state for shareable filters/time range when appropriate.
+- Server state via TanStack Query or measured equivalent.
+- Editor draft state isolated from saved dashboard state.
+- WebSocket subscriptions managed by one client/service.
+- Chart samples in bounded local stores/ring buffers.
+- Avoid duplicating server state across stores.
+
+## Dashboard editor
+
+- Save complete version atomically.
+- Use explicit edit session/draft.
+- Detect optimistic concurrency conflict.
+- Undo/redo operates on normalized editor commands or bounded snapshots.
+- Breakpoint layouts validated before save.
+- Keyboard move/resize and screen-reader labels.
+- Prevent accidental drag from chart interactions.
+
+## Charts
+
+- Lazy-load heavy chart implementations.
+- Initialize history once per query.
+- Append live data efficiently.
+- Cap points/series.
+- Dispose observers/listeners/instances.
+- Pause offscreen/background work.
+- Provide textual summary/table alternative.
+- Use consistent units, timestamps, legend and tooltip behavior.
+- Status thresholds do not overwrite data meaning.
+
+## Tables/lists
+
+- Cursor/server pagination for large datasets.
+- Virtualization for large rendered collections.
+- Stable row keys.
+- Accessible sorting/filtering labels.
+- Preserve filter state sensibly.
+- Loading and empty states are distinct.
+
+## Error handling
+
+- Route-level boundary.
+- Component/query errors show safe, actionable messages.
+- Correlation ID exposed for diagnostics.
+- Retry only when safe and bounded.
+- Authentication expiry has a clean flow.
+- Partial datasource failure does not blank the entire app.
+
+## Styling
+
+- Use design tokens; no scattered literal colors/spacing.
+- Consistent card padding and grid gaps.
+- Limited elevation.
+- Status colors only for status.
+- Respect reduced motion.
+- Avoid oversized decorative headers that reduce information space.
+- Desktop and mobile screenshots/visual regression for key routes.
+
+## Testing
+
+- Unit tests for formatting/transforms/editor reducers.
+- Component tests for states and accessibility.
+- Playwright for user journeys.
+- Axe or equivalent on all core routes and viewports.
+- Real browser verification for drag/resize, WebSocket reconnect and wallboard.
+- Leak/soak instrumentation for chart/subscription lifecycle.