# Frontend Rules & Conventions

**Read this file when working on frontend tasks** (HTML, CSS, JS, locales, templates).

## CSS Custom Properties (Variables)

Defined in `server/src/wled_controller/static/css/base.css`.

**IMPORTANT:** There is NO `--accent` variable. Always use `--primary-color` for accent/brand color.

### Global (`:root`)
| Variable | Value | Usage |
|---|---|---|
| `--primary-color` | `#4CAF50` | **Accent/brand color** — borders, highlights, active states |
| `--primary-hover` | `#5cb860` | Hover state for primary elements |
| `--primary-contrast` | `#ffffff` | Text on primary background |
| `--danger-color` | `#f44336` | Destructive actions, errors |
| `--warning-color` | `#ff9800` | Warnings |
| `--info-color` | `#2196F3` | Informational highlights |

### Theme-specific (`[data-theme="dark"]` / `[data-theme="light"]`)
| Variable | Dark | Light | Usage |
|---|---|---|---|
| `--bg-color` | `#1a1a1a` | `#f5f5f5` | Page background |
| `--bg-secondary` | `#242424` | `#eee` | Secondary background |
| `--card-bg` | `#2d2d2d` | `#ffffff` | Card/panel background |
| `--text-color` | `#e0e0e0` | `#333333` | Primary text |
| `--text-secondary` | `#999` | `#666` | Secondary text |
| `--text-muted` | `#777` | `#999` | Muted/disabled text |
| `--border-color` | `#404040` | `#e0e0e0` | Borders, dividers |
| `--primary-text-color` | `#66bb6a` | `#3d8b40` | Primary-colored text |
| `--success-color` | `#28a745` | `#2e7d32` | Success indicators |
| `--shadow-color` | `rgba(0,0,0,0.3)` | `rgba(0,0,0,0.12)` | Box shadows |

## UI Conventions for Dialogs

### Hints

Every form field in a modal should have a hint. Use the `.label-row` wrapper with a `?` toggle button:

```html
<div class="form-group">
    <div class="label-row">
        <label for="my-field" data-i18n="my.label">Label:</label>
        <button type="button" class="hint-toggle" onclick="toggleHint(this)" title="?">?</button>
    </div>
    <small class="input-hint" style="display:none" data-i18n="my.label.hint">Hint text</small>
    <input type="text" id="my-field">
</div>
```

Add hint text to both `en.json` and `ru.json` locale files using a `.hint` suffix on the label key.

### Select dropdowns

Do **not** add placeholder options like `-- Select something --`. Populate the `<select>` with real options only and let the first one be selected by default.

### Empty/None option format

When a selector has an optional entity (e.g., sync clock, processing template, brightness source), the empty option must use the format `None (<description>)` where the description explains what happens when nothing is selected. Use i18n keys, never hardcoded `—` or bare `None`.

Examples:
- `None (no processing template)` — `t('common.none_no_cspt')`
- `None (no input source)` — `t('common.none_no_input')`
- `None (use own speed)` — `t('common.none_own_speed')`
- `None (full brightness)` — `t('color_strip.composite.brightness.none')`
- `None (device brightness)` — `t('targets.brightness_vs.none')`

For `EntitySelect` with `allowNone: true`, pass the same i18n string as `noneLabel`.

### Enhanced selectors (IconSelect & EntitySelect)

Plain `<select>` dropdowns should be enhanced with visual selectors depending on the data type:

- **Predefined options** (source types, effect types, palettes, waveforms, viz modes) → use `IconSelect` from `js/core/icon-select.js`. This replaces the `<select>` with a visual grid of icon+label+description cells. See `_ensureCSSTypeIconSelect()`, `_ensureEffectTypeIconSelect()`, `_ensureInterpolationIconSelect()` in `color-strips.js` for examples.

- **Entity references** (picture sources, audio sources, devices, templates, clocks) → use `EntitySelect` from `js/core/entity-palette.js`. This replaces the `<select>` with a searchable command-palette-style picker. See `_cssPictureSourceEntitySelect` in `color-strips.js` or `_lineSourceEntitySelect` in `advanced-calibration.js` for examples.

Both widgets hide the native `<select>` but keep it in the DOM with its value in sync. After programmatically changing the `<select>` value, call `.refresh()` (EntitySelect) or `.setValue(val)` (IconSelect) to update the trigger display. Call `.destroy()` when the modal closes.

**IMPORTANT:** For `IconSelect` item icons, use SVG icons from `js/core/icon-paths.js` (via `_icon(P.iconName)`) or styled `<span>` elements (e.g., `<span style="font-weight:bold">A</span>`). **Never use emoji** — they render inconsistently across platforms and themes.

### Modal dirty check (discard unsaved changes)

Every editor modal **must** have a dirty check so closing with unsaved changes shows a "Discard unsaved changes?" confirmation. Use the `Modal` base class pattern from `js/core/modal.js`:

1. **Subclass Modal** with `snapshotValues()` returning an object of all tracked field values:

   ```javascript
   class MyEditorModal extends Modal {
       constructor() { super('my-modal-id'); }
       snapshotValues() {
           return {
               name: document.getElementById('my-name').value,
               // ... all form fields
           };
       }
       onForceClose() {
           // Optional: cleanup (reset flags, clear state, etc.)
       }
   }
   const myModal = new MyEditorModal();
   ```

2. **Call `modal.snapshot()`** after the form is fully populated (after `modal.open()`).
3. **Close/cancel button** calls `await modal.close()` — triggers dirty check + confirmation.
4. **Save function** calls `modal.forceClose()` after successful save — skips dirty check.
5. For complex/dynamic state (filter lists, schedule rows, conditions), serialize to JSON string in `snapshotValues()`.

The base class handles: `isDirty()` comparison, confirmation dialog, backdrop click, ESC key, focus trapping, and body scroll lock.

### Card appearance

When creating or modifying entity cards (devices, targets, CSS sources, streams, audio/value sources, templates), **always reference existing cards** of the same or similar type for visual consistency. Cards should have:

- Clone (📋) and Edit (✏️) icon buttons in `.template-card-actions`
- Delete (✕) button as `.card-remove-btn`
- Property badges in `.stream-card-props` with emoji icons
- **Crosslinks**: When a card references another entity (audio source, picture source, capture template, PP template, etc.), make the property badge a clickable link using the `stream-card-link` CSS class and an `onclick` handler calling `navigateToCard(tab, subTab, sectionKey, cardAttr, cardValue)`. Only add the link when the referenced entity is found (to avoid broken navigation). Example: `<span class="stream-card-prop stream-card-link" onclick="event.stopPropagation(); navigateToCard('streams','audio','audio-multi','data-id','${id}')">🎵 Name</span>`

### Modal footer buttons

Use **icon-only** buttons (✓ / ✕) matching the device settings modal pattern, **not** text buttons:

```html
<div class="modal-footer">
    <button class="btn btn-icon btn-secondary" onclick="closeMyModal()" title="Cancel" data-i18n-title="settings.button.cancel" data-i18n-aria-label="aria.cancel">&#x2715;</button>
    <button class="btn btn-icon btn-primary" onclick="saveMyEntity()" title="Save" data-i18n-title="settings.button.save" data-i18n-aria-label="aria.save">&#x2713;</button>
</div>
```

### Slider value display

For range sliders, display the current value **inside the label** (not in a separate wrapper). This keeps the value visible next to the property name:

```html
<label for="my-slider"><span data-i18n="my.label">Speed:</span> <span id="my-slider-display">1.0</span></label>
...
<input type="range" id="my-slider" min="0" max="10" step="0.1" value="1.0"
    oninput="document.getElementById('my-slider-display').textContent = this.value">
```

Do **not** use a `range-with-value` wrapper div.

### Tutorials

The app has an interactive tutorial system (`static/js/features/tutorials.js`) with a generic engine, spotlight overlay, tooltip positioning, and keyboard navigation. Tutorials exist for:
- **Getting started** (header-level walkthrough of all tabs and controls)
- **Per-tab tutorials** (Dashboard, Targets, Sources, Profiles) triggered by `?` buttons
- **Device card tutorial** and **Calibration tutorial** (context-specific)

When adding **new tabs, sections, or major UI elements**, update the corresponding tutorial step array in `tutorials.js` and add `tour.*` i18n keys to all 3 locale files (`en.json`, `ru.json`, `zh.json`).

## Icons

**Always use SVG icons from the icon system, never text/emoji/Unicode symbols for buttons and UI controls.**

- Icon SVG paths are defined in `static/js/core/icon-paths.js` (Lucide icons, 24×24 viewBox)
- Icon constants are exported from `static/js/core/icons.js` (e.g. `ICON_START`, `ICON_TRASH`, `ICON_EDIT`)
- Use `_svg(path)` wrapper from `icons.js` to create new icon constants from paths

When you need a new icon:
1. Find the Lucide icon at https://lucide.dev
2. Copy the inner SVG elements (paths, circles, rects) into `icon-paths.js` as a new export
3. Add a corresponding `ICON_*` constant in `icons.js` using `_svg(P.myIcon)`
4. Import and use the constant in your feature module

Common icons: `ICON_START` (play), `ICON_STOP` (power), `ICON_EDIT` (pencil), `ICON_CLONE` (copy), `ICON_TRASH` (trash), `ICON_SETTINGS` (gear), `ICON_TEST` (flask), `ICON_OK` (circle-check), `ICON_WARNING` (triangle-alert), `ICON_HELP` (circle-help), `ICON_LIST_CHECKS` (list-checks), `ICON_CIRCLE_OFF` (circle-off).

For icon-only buttons, use `btn btn-icon` CSS classes. The `.icon` class inside buttons auto-sizes to 16×16.

## Localization (i18n)

**Every user-facing string must be localized.** Never use hardcoded English strings in `showToast()`, `error.textContent`, modal messages, or any other UI-visible text. Always use `t('key')` from `../core/i18n.js` and add the corresponding key to **all three** locale files (`en.json`, `ru.json`, `zh.json`).

- In JS modules: `import { t } from '../core/i18n.js';` then `showToast(t('my.key'), 'error')`
- In inline `<script>` blocks (where `t()` may not be available yet): use `window.t ? t('key') : 'fallback'`
- In HTML templates: use `data-i18n="key"` for text content, `data-i18n-title="key"` for title attributes, `data-i18n-aria-label="key"` for aria-labels
- Keys follow dotted namespace convention: `feature.context.description` (e.g. `device.error.brightness`, `calibration.saved`)

### Dynamic content and language changes

When a feature module generates HTML with baked-in `t()` calls (e.g., toolbar button titles, legend text), that content won't update when the user switches language. To handle this, listen for the `languageChanged` event and re-render:

```javascript
document.addEventListener('languageChanged', () => {
    if (_initialized) _reRender();
});
```

Static HTML using `data-i18n` attributes is handled automatically by the i18n system. Only dynamically generated HTML needs this pattern.

## Bundling & Development Workflow

The frontend uses **esbuild** to bundle all JS modules and CSS files into single files for production.

### Files

- **Entry points:** `static/js/app.js` (JS), `static/css/all.css` (CSS imports all individual sheets)
- **Output:** `static/dist/app.bundle.js` and `static/dist/app.bundle.css` (minified + source maps)
- **Config:** `server/esbuild.mjs`
- **HTML:** `templates/index.html` references the bundles, not individual source files

### Commands (from `server/` directory)

| Command | Description |
|---|---|
| `npm run build` | One-shot bundle + minify (~30ms) |
| `npm run watch` | Watch mode — auto-rebuilds on any JS/CSS file save |

### Development workflow

1. Run `npm run watch` in a terminal (stays running)
2. Edit source files in `static/js/` or `static/css/` as usual
3. esbuild rebuilds the bundle automatically (~30ms)
4. Refresh the browser to see changes

### Dependencies

All JS/CSS dependencies are bundled — **no CDN or external requests** at runtime:

- **Chart.js** — imported in `perf-charts.js`, exposed as `window.Chart` for `targets.js` and `dashboard.js`
- **ELK.js** — imported in `graph-layout.js` for graph auto-layout
- **Fonts** — DM Sans (400-700) and Orbitron (700) woff2 files in `static/fonts/`, declared in `css/fonts.css`

When adding a new JS dependency: `npm install <pkg>` in `server/`, then `import` it in the relevant source file. esbuild bundles it automatically.

### Notes

- The `dist/` directory is gitignored — bundles are build artifacts, run `npm run build` after clone
- Source maps are generated so browser DevTools show original source files
- The server sets `Cache-Control: no-cache` on static JS/CSS/JSON to prevent stale browser caches during development
- GZip compression middleware reduces transfer sizes by ~75%
- **Do not edit files in `static/dist/`** — they are overwritten by the build

## Chrome Browser Tools

See [`contexts/chrome-tools.md`](chrome-tools.md) for Chrome MCP tool usage, browser tricks (hard reload, zoom, console), and verification workflow.

## Duration & Numeric Formatting

### Uptime / duration values

Use `formatUptime(seconds)` from `core/ui.js`. Outputs `{s}s`, `{m}m {s}s`, or `{h}h {m}m` via i18n keys `time.seconds`, `time.minutes_seconds`, `time.hours_minutes`.

### Large numbers

Use `formatCompact(n)` from `core/ui.js`. Outputs `1.2K`, `3.5M` etc. Set `element.title` to the exact value for hover detail.

### Preventing layout shift

Numeric/duration values that update frequently (FPS, uptime, frame counts) **must** use fixed-width styling to prevent layout reflow:

- `font-family: var(--font-mono, monospace)` — equal-width characters
- `font-variant-numeric: tabular-nums` — equal-width digits in proportional fonts
- Fixed `width` or `min-width` on the value container
- `text-align: right` to anchor the growing edge

Reference: `.dashboard-metric-value` in `dashboard.css` uses `font-family: var(--font-mono)`, `font-weight: 600`, `min-width: 48px`.

### FPS sparkline charts

Use `createFpsSparkline(canvasId, actualHistory, currentHistory, fpsTarget)` from `core/chart-utils.js`. Wrap the canvas in `.target-fps-sparkline` (36px height, `position: relative`, `overflow: hidden`). Show the value in `.target-fps-label` with `.metric-value` and `.target-fps-avg`.

## Visual Graph Editor

See [`contexts/graph-editor.md`](graph-editor.md) for full graph editor architecture and conventions.

**IMPORTANT:** When adding or modifying entity types, subtypes, or connection fields, the graph editor files **must** be updated in sync. The graph maintains its own maps of entity colors, labels, icons, connection rules, and cache references. See the "Keeping the graph in sync with entity types" section in `graph-editor.md` for the complete checklist.