# Coding Conventions

## Source Language

Use JavaScript for the new client.

Rules:

- Backend response validation lives in `src/api/schemas`.
- UI-facing normalized models are produced by mapper functions.
- Avoid passing raw backend envelopes deep into UI components.
- If a response shape is uncertain, validate it at the API/module boundary and
  return `invalid_response` on mismatch.

## File Naming

- Vue components: `PascalCase.vue`.
- Stores: `useXStore` exported from `stores/x.js`.
- Composables: `useThing.js`.
- API modules: lowercase domain names, e.g. `devices.js`.
- Runtime schemas: domain names, e.g. `devices.js`, `areas.js`.

## Component Rules

- Keep route components thin.
- Put reusable domain UI in `features/{domain}/components`.
- Put generic reusable UI in `components`.
- Do not pass raw backend DTO-like objects directly into deep UI components unless
  the component is API-specific by design.
- Use props/events for reusable components.
- Use stores for screen-level data and cross-component state.

## Store Rules

- Stores own fetch/mutation orchestration.
- Stores call API modules.
- Stores expose loading/error states.
- Stores should not know about toasts or router navigation.
- Components or page-level actions decide how to show feedback.

## API Rules

- All API methods return normalized `{ ok, data?, error?, meta }` results.
- API modules do not show UI feedback.
- API modules do not mutate stores directly.
- API mappers should be pure functions.
- Request cancellation should use `AbortController`.

## Error Handling

Use this UI policy:

- Route-level fetch failure: show route error state with retry.
- Per-row device status failure: show row-level error/offline state.
- Mutation failure: keep the modal/page open and show toast plus inline field
  errors when available.
- Validation failure: show field-level errors before submitting.

Do not:

- Treat component render errors as network errors.
- Hide backend `msg` when present.
- Swallow failed mutations silently.

## Formatting And Style

- Use tabs or spaces consistently after scaffold decision.
- Keep components small enough that template, script, and styles are easy to scan.
- Prefer explicit names over abbreviations.
- Avoid direct DOM manipulation except for integration boundaries.
- Avoid global singletons unless they are intentional app-level services.

## Icons

Current client uses Phosphor Icons.

New client options:

- Continue using Phosphor if `gnexus-ui-kit` supports it or does not provide an
  icon system.
- Prefer UI-kit icon primitives if they exist.

Do not mix several icon systems in the same screen.

## Dates And Formatting

Centralize formatting in `src/utils/format.js` and `src/utils/dates.js`.

Required helpers:

- `formatDate`
- `formatDateTime`
- `formatTimeAgo`
- `formatDeviceConnectionStatus`
- `formatScriptState`

## CSS And Styling

- Prefer UI-kit tokens/classes.
- Put app-specific layout styles in `src/styles`.
- Avoid copying old SCSS wholesale.
- If old styles are needed temporarily, isolate them under a legacy namespace.
- Do not override UI-kit internals with brittle selectors.
- Keep UI-kit compatibility wrappers thin enough that design updates from
  `gnexus-ui-kit` are visible without rewriting feature components.

## Accessibility Baseline

- Buttons must use real `<button>` elements.
- Modals must trap focus or rely on UI-kit dialog behavior.
- Inputs must have labels.
- Loading states must not remove context.
- Danger actions require confirmation.