homebridge-generac 0.1.0-beta.1

package/homebridge-ui/public/js/main.js

@@ -0,0 +1,288 @@
+import { callServer, setSaveEnabled, toastError } from './api.js';
+import { BANNER, INTRO, SHELL } from './copy.js';
+import { clear, el } from './dom.js';
+import { renderFooter } from './footer.js';
+import { exportConfig, PLATFORM, readConfig } from './model.js';
+import { renderAccount } from './sections/account.js';
+import { renderGenerators } from './sections/generators.js';
+import { renderSettings } from './sections/settings.js';
+import { validate } from './validate.js';
+/**
+ * The settings page (SPEC section 11): reads the platform block with `getPluginConfig`, pushes every change with
+ * `updatePluginConfig`, leaves saving to the Homebridge UI's Save button (disabled while validation finds errors),
+ * and asks the plugin's UI server for /status every 15 seconds while the page is open.
+ */
+export const STATUS_POLL_MS = 15 * 1000;
+const SECTIONS = [
+    { key: 'account', title: INTRO.accountHeading, help: INTRO.accountHelp, render: renderAccount },
+    { key: 'generators', title: INTRO.generatorsHeading, help: INTRO.generatorsHelp, render: renderGenerators },
+    { key: 'settings', title: INTRO.settingsHeading, help: '', render: renderSettings },
+];
+const CONTROLS = ':scope > .form-control, :scope > .input-group > .form-control, :scope > .form-check-input';
+/** True on phones and tablets: the page then gives every button a 44px touch target. */
+export function isTouchDevice() {
+    try {
+        return (window.matchMedia && window.matchMedia('(pointer: coarse)').matches) || navigator.maxTouchPoints > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export class Page {
+    constructor(config, root) {
+        this.config = config;
+        this.root = root;
+        this.status = null;
+        this.ui = { flow: null, disconnectOpen: false, resetOpen: false, rename: null, checkingSince: null };
+        this.containers = new Map();
+        this.touched = new Set();
+        /** The messages currently shown inline, by path. A focused field only ever loses its message, never gains one. */
+        this.shown = new Map();
+        this.otherBlocks = [];
+        this.exerciseTimeSettled = config.exerciseTime.trim().length > 0;
+        root.appendChild(el('img', {
+            class: 'ns-banner', src: BANNER.file, alt: `${BANNER.title}: ${BANNER.tagline}`, width: '1280', height: '320',
+        }));
+        root.appendChild(el('p', { class: 'lead-copy' }, INTRO.one));
+        root.appendChild(el('p', { class: 'lead-copy' }, INTRO.two));
+        root.appendChild(el('p', { class: 'form-text gn-affiliation' }, INTRO.affiliation));
+        for (const section of SECTIONS) {
+            const container = el('div', { class: 'section-body' });
+            this.containers.set(section.key, container);
+            root.appendChild(el('section', { class: 'ns-section', id: `section-${section.key}` }, el('h2', { class: 'h5' }, section.title), section.help ? el('p', { class: 'section-copy' }, section.help) : null, container));
+        }
+        root.appendChild(el('p', { class: 'lead-copy mt-3' }, INTRO.closing));
+        this.footer = renderFooter();
+        root.appendChild(this.footer.el);
+        // Validation on blur: leaving a control touches its field; typing alone does not. Typing does clear a message
+        // the moment the field is fixed, so nothing under the field moves when it is left (a button below it would
+        // otherwise shift between mousedown and mouseup).
+        root.addEventListener('focusout', (event) => {
+            if (event.target instanceof HTMLElement && event.target.matches('input, select, textarea')) {
+                const path = event.target.closest('[data-path]')?.dataset.path;
+                if (path) {
+                    if (path === 'exerciseTime') {
+                        this.exerciseTimeSettled = true;
+                    }
+                    this.touch(path);
+                }
+            }
+        });
+        root.addEventListener('input', (event) => {
+            if (event.target instanceof HTMLElement && event.target.matches('input, select, textarea')) {
+                this.markIssues(validate(this.config));
+            }
+        });
+    }
+    setOtherBlocks(blocks) {
+        this.otherBlocks = blocks;
+    }
+    renderAll() {
+        for (const section of SECTIONS) {
+            this.rerender(section.key);
+        }
+        this.revalidate();
+    }
+    rerender(section) {
+        const container = this.containers.get(section);
+        if (!container) {
+            return;
+        }
+        const open = [...container.querySelectorAll('details')].map((d) => d.open);
+        clear(container);
+        SECTIONS.find((s) => s.key === section)?.render(this, container);
+        [...container.querySelectorAll('details')].forEach((d, i) => {
+            d.open = open[i] ?? d.open;
+        });
+        this.markIssues(validate(this.config));
+    }
+    changed() {
+        this.revalidate();
+        this.push();
+    }
+    replaceConfig(config) {
+        this.config = config;
+        this.touched.clear();
+        this.exerciseTimeSettled = true;
+        this.renderAll();
+        this.push();
+    }
+    touch(path) {
+        this.touched.add(path);
+        this.markIssues(validate(this.config));
+    }
+    untouch(path) {
+        this.touched.delete(path);
+    }
+    issues() {
+        return validate(this.config);
+    }
+    /**
+     * Asks the server for /status and redraws the account card from the answer (unless the Connect flow is in
+     * progress) and the generator cards (unless a Rename editor is open).
+     */
+    async refreshStatus() {
+        var _a;
+        const status = await callServer('/status');
+        if (!status || !status.account) {
+            return;
+        }
+        this.status = status;
+        this.footer.setVersion(status.version);
+        this.prefillExerciseTime();
+        if (status.account.state === 'checking') {
+            (_a = this.ui).checkingSince ?? (_a.checkingSince = Date.now());
+        }
+        else {
+            this.ui.checkingSince = null;
+        }
+        if (!this.ui.flow) {
+            this.rerender('account');
+        }
+        if (!this.ui.rename) {
+            this.rerender('generators');
+        }
+    }
+    /** The Exercise time setting is prefilled from Mobile Link once (SPEC section 11.3 E) and pushed, so Save keeps it. */
+    prefillExerciseTime() {
+        if (this.exerciseTimeSettled || !this.status) {
+            return;
+        }
+        const fromApi = this.status.generators.map((g) => g.exerciseTimeFromApi).find((t) => typeof t === 'string' && t.length > 0);
+        if (!fromApi) {
+            return;
+        }
+        this.exerciseTimeSettled = true;
+        this.config.exerciseTime = fromApi;
+        const settings = this.containers.get('settings');
+        if (settings && !settings.contains(document.activeElement)) {
+            this.rerender('settings');
+        }
+        this.changed();
+    }
+    startPolling() {
+        void this.refreshStatus();
+        this.pollTimer = window.setInterval(() => void this.refreshStatus(), STATUS_POLL_MS);
+        window.addEventListener('pagehide', () => {
+            if (this.pollTimer !== undefined) {
+                window.clearInterval(this.pollTimer);
+                this.pollTimer = undefined;
+            }
+        });
+    }
+    revalidate() {
+        const issues = validate(this.config);
+        this.markIssues(issues);
+        setSaveEnabled(issues.length === 0);
+    }
+    push() {
+        if (this.pushTimer !== undefined) {
+            window.clearTimeout(this.pushTimer);
+        }
+        this.pushTimer = window.setTimeout(() => {
+            this.pushTimer = undefined;
+            window.homebridge.updatePluginConfig([exportConfig(this.config), ...this.otherBlocks]).catch((err) => {
+                toastError(`${SHELL.updateFailed} ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }, 150);
+    }
+    /**
+     * Draws the inline state of every field: the issue on a touched field as a message under it, nothing otherwise.
+     * The field that has focus never gains a message; one it already shows is kept until the issue is gone.
+     */
+    markIssues(issues) {
+        const active = document.activeElement instanceof HTMLElement ? document.activeElement.closest('[data-path]') : null;
+        const activePath = active?.dataset.path;
+        const byPath = new Map();
+        for (const issue of issues) {
+            if (!byPath.has(issue.path)) {
+                byPath.set(issue.path, issue);
+            }
+        }
+        const shown = new Map();
+        for (const node of this.root.querySelectorAll('[data-path]')) {
+            const path = node.dataset.path ?? '';
+            if (path.startsWith('connect.') || path.startsWith('generators[')) {
+                // The Connect flow and the Rename editor validate their own required fields.
+                this.markRequired(node, path, path === activePath);
+                continue;
+            }
+            const issue = byPath.get(path);
+            let message = issue && this.touched.has(path) ? issue.message : undefined;
+            if (path === activePath && message !== undefined) {
+                message = this.shown.get(path);
+            }
+            if (message !== undefined) {
+                shown.set(path, message);
+            }
+            const feedback = node.querySelector(':scope > .invalid-feedback');
+            node.classList.toggle('has-issue', message !== undefined);
+            if (feedback) {
+                feedback.textContent = message ?? '';
+            }
+            for (const control of node.querySelectorAll(CONTROLS)) {
+                control.classList.toggle('is-invalid', message !== undefined);
+            }
+            if (message !== undefined) {
+                // An issue on a field under the collapsed disclosure would otherwise be invisible.
+                for (let details = node.closest('details'); details; details = details.parentElement?.closest('details') ?? null) {
+                    details.open = true;
+                }
+            }
+        }
+        this.shown = shown;
+    }
+    /** "{Label} is required." for the Connect fields once touched (SPEC section 11.2); a focused field only loses it. */
+    markRequired(node, path, focused) {
+        if (!path.startsWith('connect.') || !this.touched.has(path)) {
+            return;
+        }
+        const control = node.querySelector(CONTROLS);
+        const label = node.querySelector('label')?.firstChild?.textContent?.trim() ?? '';
+        const missing = !!control && control.value.trim() === '' && (!focused || node.classList.contains('has-issue'));
+        node.classList.toggle('has-issue', missing);
+        control?.classList.toggle('is-invalid', missing);
+        const feedback = node.querySelector(':scope > .invalid-feedback');
+        if (feedback) {
+            feedback.textContent = missing ? `${label} is required.` : '';
+        }
+    }
+}
+async function start() {
+    const root = document.getElementById('app');
+    if (!root) {
+        return;
+    }
+    if (isTouchDevice()) {
+        document.body.classList.add('ns-touch');
+    }
+    const hb = window.homebridge;
+    hb.showSpinner();
+    try {
+        const blocks = await hb.getPluginConfig();
+        const index = blocks.findIndex((block) => block && typeof block === 'object' && block.platform === PLATFORM);
+        const raw = index >= 0 ? blocks[index] : undefined;
+        const page = new Page(readConfig(raw), root);
+        page.setOtherBlocks(blocks.filter((_, i) => i !== index));
+        page.renderAll();
+        if (index < 0) {
+            // A fresh install: the block exists once Save is clicked.
+            page.changed();
+        }
+        page.startPolling();
+    }
+    catch (err) {
+        root.appendChild(el('div', { class: 'alert alert-danger' }, `${SHELL.loadFailed} ${err instanceof Error ? err.message : String(err)}`));
+    }
+    finally {
+        hb.hideSpinner();
+    }
+}
+if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => {
+        start().catch(() => undefined);
+    });
+}
+else {
+    start().catch(() => undefined);
+}

package/homebridge-ui/public/js/mark.js

@@ -0,0 +1,34 @@
+import { el } from './dom.js';
+/**
+ * The Generac for Homebridge mark (assets/generac-mark.svg without its metadata), drawn inline so the footer
+ * loads no file. It uses `currentColor`, so it takes the surrounding text colour and follows the host's theme.
+ */
+const PATHS = [
+    ['rect', { x: '30', y: '34', width: '132', height: '90', rx: '12' }],
+    ['path', { d: 'M56 62H94M56 79H94M56 96H94', 'stroke-linecap': 'round' }],
+    ['rect', { x: '112', y: '64', width: '30', height: '30', rx: '6' }],
+    ['path', { d: 'M66 124V148M126 124V148', 'stroke-linecap': 'round' }],
+    ['path', { d: 'M18 154H174', 'stroke-linecap': 'round' }],
+];
+/** The mark at `size` CSS pixels, decorative (`aria-hidden`), in the surrounding text colour. */
+export function renderMark(size) {
+    const ns = 'http://www.w3.org/2000/svg';
+    const svg = document.createElementNS(ns, 'svg');
+    svg.setAttribute('viewBox', '0 0 192 192');
+    svg.setAttribute('width', String(size));
+    svg.setAttribute('height', String(size));
+    svg.setAttribute('aria-hidden', 'true');
+    svg.setAttribute('focusable', 'false');
+    svg.classList.add('ns-mark-svg');
+    for (const [tag, attrs] of PATHS) {
+        const node = document.createElementNS(ns, tag);
+        for (const [k, v] of Object.entries(attrs)) {
+            node.setAttribute(k, v);
+        }
+        node.setAttribute('fill', 'none');
+        node.setAttribute('stroke', 'currentColor');
+        node.setAttribute('stroke-width', '12');
+        svg.appendChild(node);
+    }
+    return el('span', { class: 'ns-mark' }, svg).firstElementChild;
+}

package/homebridge-ui/public/js/model.js

@@ -0,0 +1,120 @@
+/**
+ * The platform block as the page edits it (SPEC section 9). `readConfig` accepts whatever config.json holds and
+ * fills in the defaults; `exportConfig` writes the block back, keeping keys the page does not know (the host's
+ * `_bridge` settings, `credentialsPath`) exactly as loaded.
+ */
+export const PLATFORM = 'Generac';
+export const DEFAULTS = {
+    name: 'Generac',
+    pollIdleMinutes: 10,
+    pollIdleMinutesMin: 2,
+    pollActiveSeconds: 90,
+    pollActiveSecondsMin: 60,
+    batteryLowVoltage: 12.0,
+    faultOnStopped: true,
+    faultOnDisconnected: false,
+    attentionSensor: false,
+    exerciseSensor: true,
+    exerciseHoldMinutes: 5,
+    exerciseHoldMinutesMin: 1,
+    debug: false,
+};
+const KNOWN = new Set([
+    'platform', 'name', 'pollIdleMinutes', 'pollActiveSeconds', 'batteryLowVoltage', 'faultOnStopped', 'faultOnDisconnected',
+    'attentionSensor', 'exerciseSensor', 'exerciseTime', 'exerciseHoldMinutes', 'debug', 'generators',
+]);
+function num(value, fallback) {
+    const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() !== '' ? Number(value) : Number.NaN;
+    return Number.isFinite(n) ? n : fallback;
+}
+function bool(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+export function emptyConfig() {
+    return {
+        name: DEFAULTS.name,
+        pollIdleMinutes: DEFAULTS.pollIdleMinutes,
+        pollActiveSeconds: DEFAULTS.pollActiveSeconds,
+        batteryLowVoltage: DEFAULTS.batteryLowVoltage,
+        faultOnStopped: DEFAULTS.faultOnStopped,
+        faultOnDisconnected: DEFAULTS.faultOnDisconnected,
+        attentionSensor: DEFAULTS.attentionSensor,
+        exerciseSensor: DEFAULTS.exerciseSensor,
+        exerciseTime: '',
+        exerciseHoldMinutes: DEFAULTS.exerciseHoldMinutes,
+        debug: DEFAULTS.debug,
+        generators: [],
+        extra: {},
+    };
+}
+export function readConfig(raw) {
+    const c = emptyConfig();
+    if (!raw || typeof raw !== 'object') {
+        return c;
+    }
+    const r = raw;
+    c.name = typeof r.name === 'string' && r.name.trim() ? r.name : DEFAULTS.name;
+    c.pollIdleMinutes = num(r.pollIdleMinutes, DEFAULTS.pollIdleMinutes);
+    c.pollActiveSeconds = num(r.pollActiveSeconds, DEFAULTS.pollActiveSeconds);
+    c.batteryLowVoltage = num(r.batteryLowVoltage, DEFAULTS.batteryLowVoltage);
+    c.faultOnStopped = bool(r.faultOnStopped, DEFAULTS.faultOnStopped);
+    c.faultOnDisconnected = bool(r.faultOnDisconnected, DEFAULTS.faultOnDisconnected);
+    c.attentionSensor = bool(r.attentionSensor, DEFAULTS.attentionSensor);
+    c.exerciseSensor = bool(r.exerciseSensor, DEFAULTS.exerciseSensor);
+    c.exerciseTime = typeof r.exerciseTime === 'string' ? r.exerciseTime.trim() : '';
+    c.exerciseHoldMinutes = num(r.exerciseHoldMinutes, DEFAULTS.exerciseHoldMinutes);
+    c.debug = bool(r.debug, DEFAULTS.debug);
+    if (Array.isArray(r.generators)) {
+        for (const g of r.generators) {
+            if (g && typeof g === 'object') {
+                const id = num(g.apparatusId, Number.NaN);
+                const name = g.name;
+                if (Number.isFinite(id) && typeof name === 'string' && name.trim()) {
+                    c.generators.push({ apparatusId: id, name: name.trim() });
+                }
+            }
+        }
+    }
+    for (const [key, value] of Object.entries(r)) {
+        if (!KNOWN.has(key)) {
+            c.extra[key] = value;
+        }
+    }
+    return c;
+}
+/** The block for `updatePluginConfig`. Optional keys at their default are written all the same, so the file reads as the page shows. */
+export function exportConfig(c) {
+    const block = {
+        ...c.extra,
+        platform: PLATFORM,
+        name: c.name,
+        pollIdleMinutes: c.pollIdleMinutes,
+        pollActiveSeconds: c.pollActiveSeconds,
+        batteryLowVoltage: c.batteryLowVoltage,
+        faultOnStopped: c.faultOnStopped,
+        faultOnDisconnected: c.faultOnDisconnected,
+        attentionSensor: c.attentionSensor,
+        exerciseSensor: c.exerciseSensor,
+        exerciseHoldMinutes: c.exerciseHoldMinutes,
+        debug: c.debug,
+    };
+    if (c.exerciseTime.trim()) {
+        block.exerciseTime = c.exerciseTime.trim();
+    }
+    if (c.generators.length > 0) {
+        block.generators = c.generators.map((g) => ({ apparatusId: g.apparatusId, name: g.name }));
+    }
+    return block;
+}
+/** The display name override for a generator, or undefined. */
+export function overrideFor(c, apparatusId) {
+    return c.generators.find((g) => g.apparatusId === apparatusId)?.name;
+}
+/** Sets or clears a generator's display name override: a name equal to the Mobile Link name needs no override. */
+export function setOverride(c, apparatusId, name, mobileLinkName) {
+    const trimmed = name.trim();
+    c.generators = c.generators.filter((g) => g.apparatusId !== apparatusId);
+    if (trimmed && trimmed !== mobileLinkName) {
+        c.generators.push({ apparatusId, name: trimmed });
+    }
+}