@feezal/feezal-element 3.0.12 → 3.0.13

package/feezal-color.js

@@ -0,0 +1,77 @@
+/**
+ * @feezal/feezal-element/feezal-color.js (E137)
+ *
+ * Cross-controller color/scaling machinery shared by the light (and later
+ * wled) behavior controllers — consolidated from the byte-identical copies
+ * that lived in material/glass/metro-light. Pure functions, unit-testable.
+ */
+
+/** Ring % → raw MQTT value. Rounds to the granularity of 1 % of the range so
+ * sub-integer ranges survive (Homematic dimmers use a 0–1 LEVEL: 49 % → 0.49)
+ * while integer ranges (0–100, 0–254) keep publishing whole numbers. */
+export function pctToRaw(pct, min, max) {
+    const value = min + (pct / 100) * (max - min);
+    const step = Math.abs(max - min) / 100;
+    if (step >= 1 || step === 0) return Math.round(value);
+    const decimals = Math.min(6, Math.ceil(-Math.log10(step)));
+    return Number(value.toFixed(decimals));
+}
+
+/** Simple warm-to-cool interpolation: 2700 K (warm) → 6500 K (cool). */
+export function kelvinToRgb(k) {
+    const t = Math.max(0, Math.min(1, (k - 2700) / 3800));
+    return [Math.round(255 - t * 60), Math.round(210 + t * 45), Math.round(90 + t * 165)];
+}
+
+export function rgbToHex(r, g, b) {
+    return '#' + [r, g, b].map(c => Math.round(Math.max(0, Math.min(255, c))).toString(16).padStart(2, '0')).join('');
+}
+
+export function rgbToHsv(r, g, b) {
+    r /= 255; g /= 255; b /= 255;
+    const max = Math.max(r, g, b), d = max - Math.min(r, g, b);
+    let h = 0;
+    if (d) {
+        if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) * 60;
+        else if (max === g) h = ((b - r) / d + 2) * 60;
+        else h = ((r - g) / d + 4) * 60;
+    }
+    return {h, s: max ? d / max : 0, v: max};
+}
+
+export function hsvToRgb(h, s, v) {
+    const i = Math.floor(h / 60) % 6;
+    const f = h / 60 - Math.floor(h / 60);
+    const p = v * (1 - s), q = v * (1 - f * s), t = v * (1 - (1 - f) * s);
+    const combos = [[v, t, p], [q, v, p], [p, v, t], [p, q, v], [t, p, v], [v, p, q]];
+    const [r, g, b] = combos[i];
+    return [Math.round(r * 255), Math.round(g * 255), Math.round(b * 255)];
+}
+
+/** "r,g,b" string / JSON array / array → [r,g,b] (null when unparseable). */
+export function parseRgb(raw) {
+    try {
+        if (typeof raw === 'string' && !raw.startsWith('[')) {
+            const parts = raw.split(',').map(Number);
+            if (parts.length >= 3 && parts.every(n => !isNaN(n))) return parts.slice(0, 3);
+        }
+        const arr = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        if (Array.isArray(arr)) return arr.slice(0, 3).map(Number);
+    } catch {}
+    return null;
+}
+
+/** CIE 1931 xy (+ optional brightness) → sRGB (zigbee2mqtt / Hue {x,y}). */
+export function xyToRgb(x, y, bri = 1) {
+    if (!y) return [255, 255, 255];
+    const Y = bri;
+    const X = (Y / y) * x;
+    const Z = (Y / y) * (1 - x - y);
+    let r =  X * 1.656492 - Y * 0.354851 - Z * 0.255038;
+    let g = -X * 0.707196 + Y * 1.655397 + Z * 0.036152;
+    let b =  X * 0.051713 - Y * 0.121364 + Z * 1.011530;
+    const gamma = c => (c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055);
+    [r, g, b] = [r, g, b].map(c => gamma(Math.max(0, c)));
+    const max = Math.max(r, g, b, 1);
+    return [r, g, b].map(c => Math.round(Math.max(0, Math.min(1, c / max)) * 255));
+}

package/feezal-hm-fault.js

@@ -0,0 +1,178 @@
+import {html, css} from 'lit';
+
+/**
+ * E135 — Homematic fault / sabotage decoding (shared).
+ *
+ * Two encodings, per the OpenCCU-Base research:
+ *  - **Classic BidCoS/HM**: ONE integer enum datapoint — `FAULT_REPORTING` (TRV)
+ *    or `ERROR` (Keymatic, contact). The meaning of the number is
+ *    **device-family-specific** (value 7 = valve-mount error on a TRV but
+ *    SABOTAGE on a contact), so the enum table is keyed by device type. Over
+ *    MQTT the value arrives as the integer option index; feezal owns the text.
+ *  - **HmIP**: many *named boolean* `ERROR_*` datapoints (the flag NAME is the
+ *    message), plus a dedicated `SABOTAGE` / `SABOTAGE_STICKY` boolean.
+ *
+ * The number arrives live over MQTT, so decoding is a client-side render-time
+ * concern; the recognizer only wires the topic + the device-type hint.
+ */
+
+// Classic enum tables, keyed by device type. `0` (and any unlisted value that
+// maps to no fault) means OK. `sabotage` marks the value that is a tamper event.
+export const HM_FAULT_ENUMS = {
+    'HM-CC-RT-DN': {
+        datapoint: 'FAULT_REPORTING',
+        text: {1: 'Valve tight', 2: 'Adjusting range too large', 3: 'Adjusting range too small', 4: 'Communication error', 6: 'Low battery', 7: 'Valve mounting error'},
+    },
+    'HM-Sec-Key': {
+        datapoint: 'ERROR',
+        text: {1: 'Clutch failure', 2: 'Motor aborted'},
+    },
+    'HM-Sec-SC': {
+        datapoint: 'ERROR',
+        text: {7: 'Sabotage'},
+        sabotage: 7,   // classic contacts encode sabotage as ERROR == 7
+    },
+};
+
+// HmIP named fault-flag → text. The flag name IS the actionable message.
+export const HMIP_FAULT_FLAGS = {
+    ERROR_JAMMED: 'Jammed',
+    ERROR_LOAD_TOO_LOW: 'Load too low',
+    ERROR_NO_END_STOP_LOCK: 'No end stop (lock)',
+    ERROR_NO_END_STOP_UNLOCK: 'No end stop (unlock)',
+    ERROR_OVERHEAT: 'Overheating',
+    ERROR_UNDERVOLTAGE: 'Undervoltage',
+    ERROR_COPROCESSOR: 'Coprocessor error',
+    ERROR_DEGRADED_CHAMBER: 'Smoke chamber degraded',
+    ERROR_BUS_CONFIG_MISMATCH: 'Bus config mismatch',
+    ERROR_DALI_BUS: 'DALI bus error',
+};
+
+const asNum = v => {
+    if (typeof v === 'number') return v;
+    if (typeof v === 'string' && v.trim() !== '' && !Number.isNaN(Number(v))) return Number(v);
+    return null;
+};
+const asBool = v => v === true || v === 1 || v === '1' || String(v).toLowerCase() === 'true';
+
+/**
+ * Decode a fault value to human text ('' = no fault). `deviceType` selects the
+ * classic enum table; unknown families fall back to "nonzero = fault, raw code".
+ * A bare HmIP flag name (`ERROR_JAMMED`) is decoded to its text.
+ */
+export function decodeHmFault(deviceType, value) {
+    if (value === null || value === undefined || value === '') return '';
+    // HmIP: a flag name delivered as a truthy boolean — the datapoint is the message.
+    if (typeof value === 'string' && value.startsWith('ERROR_')) return hmipFlagText(value);
+    const spec = HM_FAULT_ENUMS[deviceType];
+    const n = asNum(value);
+    if (spec) {
+        if (n === null || n === 0) return '';
+        return spec.text[n] || `Fault ${n}`;
+    }
+    // Unknown family: nonzero numeric = fault (raw code); truthy string = as-is.
+    if (n !== null) return n ? `Fault ${n}` : '';
+    return asBool(value) ? String(value) : '';
+}
+
+/** Whether a classic-enum fault value is a SABOTAGE event for this device type. */
+export function isHmSabotageValue(deviceType, value) {
+    const spec = HM_FAULT_ENUMS[deviceType];
+    const n = asNum(value);
+    return !!(spec && spec.sabotage != null && n === spec.sabotage);
+}
+
+/** HmIP flag name → text (e.g. ERROR_JAMMED → "Jammed"). */
+export function hmipFlagText(flag) {
+    return HMIP_FAULT_FLAGS[flag] || String(flag).replace(/^ERROR_/, '').replace(/_/g, ' ').toLowerCase();
+}
+
+/** Interpret a sabotage signal: classic `ERROR == 7` (encoding 'error7') or an
+ *  HmIP boolean `SABOTAGE`/`SABOTAGE_STICKY` (encoding 'bool'). Returns boolean. */
+export function isSabotageActive(value, encoding, deviceType) {
+    if (value === null || value === undefined || value === '') return false;
+    if (encoding === 'error7' || (deviceType && HM_FAULT_ENUMS[deviceType] && HM_FAULT_ENUMS[deviceType].sabotage != null)) {
+        return asNum(value) === (HM_FAULT_ENUMS[deviceType] ? HM_FAULT_ENUMS[deviceType].sabotage : 7);
+    }
+    return asBool(value);
+}
+
+/**
+ * E135 shared attribute fragment — spread into a card's `feezal.attributes` so
+ * a device's fault (`FAULT_REPORTING`/`ERROR`) and sabotage (`SABOTAGE`, or
+ * classic `ERROR == 7`) signals auto-stamp and render as badges. Presence-checked
+ * like the E124 battery contract — only stamped when the device exposes them.
+ */
+export const faultSabotageAttributes = [
+    {name: 'subscribe-error', type: 'mqttTopic', help: 'Optional device fault topic (Homematic FAULT_REPORTING / ERROR). A warning badge shows the decoded fault text.'},
+    {name: 'message-property-error', type: 'string', help: 'Property path within fault messages. Defaults to message-property.'},
+    {name: 'error-device-type', type: 'string', help: 'Homematic device type (e.g. HM-CC-RT-DN) — selects the fault-code text table. Blank = show the raw code.'},
+    {name: 'subscribe-sabotage', type: 'mqttTopic', help: 'Optional sabotage/tamper topic (HmIP SABOTAGE, or classic contacts via ERROR). Shows an alarm-grade badge.'},
+    {name: 'message-property-sabotage', type: 'string', help: 'Property path within sabotage messages. Defaults to message-property.'},
+    {name: 'sabotage-encoding', type: 'select', options: ['bool', 'error7'], default: 'bool', help: 'How sabotage is encoded: a boolean (HmIP SABOTAGE), or classic contacts where ERROR == 7 is sabotage.'},
+];
+
+/** Attribute names of the E135 fragment (for parity-set derivation). */
+export const FAULT_SABOTAGE_ATTRIBUTES = faultSabotageAttributes.map(a => a.name);
+
+/**
+ * Wire a card's fault + sabotage subscriptions off its HOST attributes and
+ * decode them. `onError(text)` receives the decoded fault text ('' = no fault);
+ * `onSabotage(active)` a boolean. Mirrors the E124 battery wiring shape.
+ */
+export function subscribeFaultSabotage(host, {onError, onSabotage} = {}) {
+    const attr = n => { const v = host.getAttribute(n); return v === null ? '' : v; };
+    const prop = (msg, specific) => host.getProperty(msg, attr(specific) || attr('message-property') || 'payload');
+    const err = attr('subscribe-error');
+    if (err && onError) {
+        host.addSubscription(err, msg => onError(decodeHmFault(attr('error-device-type'), prop(msg, 'message-property-error'))));
+    }
+    const sab = attr('subscribe-sabotage');
+    if (sab && onSabotage) {
+        host.addSubscription(sab, msg => onSabotage(isSabotageActive(prop(msg, 'message-property-sabotage'), attr('sabotage-encoding'), attr('error-device-type'))));
+    }
+}
+
+/** Signature fragment for rewire-on-edit (join into the controller's signature). */
+export function faultSabotageSignature(host) {
+    return ['subscribe-error', 'subscribe-sabotage'].map(n => host.getAttribute(n) || '').join('|');
+}
+
+// E135 badge styles — sabotage is alarm-grade (error colour, prominent); fault
+// is the warning tier. Bottom-left by default (battery owns bottom-right).
+export const feezalFaultStyles = css`
+    .feezal-sabotage-badge, .feezal-fault-badge {
+        position: absolute;
+        bottom: var(--feezal-fault-bottom, 6px);
+        left: var(--feezal-fault-left, 6px);
+        width: var(--feezal-fault-size, 18px); height: var(--feezal-fault-size, 18px);
+        pointer-events: none; z-index: 2;
+    }
+    .feezal-sabotage-badge { color: var(--error-color, #d32f2f); opacity: 1; }
+    .feezal-fault-badge { color: var(--warning-color, #f0a30a); opacity: 0.95; }
+    .feezal-sabotage-badge svg, .feezal-fault-badge svg { width: 100%; height: 100%; display: block; }
+`;
+
+/** Alarm-grade sabotage badge — a shield with an exclamation. Renders nothing when inactive. */
+export function sabotageBadge(active) {
+    return active ? html`<span class="feezal-sabotage-badge" title="Sabotage / tamper"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+        <path d="M12 2 4 5v6c0 5 3.4 8.7 8 10 4.6-1.3 8-5 8-10V5l-8-3zm-1 5h2v6h-2V7zm0 8h2v2h-2v-2z"/>
+    </svg></span>` : '';
+}
+
+/** Warning-tier fault badge — a triangle; the decoded text is the tooltip. '' = none. */
+export function faultBadge(text) {
+    return text ? html`<span class="feezal-fault-badge" title="${text}"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+        <path d="M1 21h22L12 2 1 21zm12-3h-2v-2h2v2zm0-4h-2v-4h2v4z"/>
+    </svg></span>` : '';
+}
+
+/** The device-health board's wildcard datapoint set (classic + HmIP + N31/E124). */
+export const HM_HEALTH_DATAPOINTS = {
+    fault:    ['FAULT_REPORTING', 'ERROR'],
+    sabotage: ['SABOTAGE', 'SABOTAGE_STICKY'],
+    battery:  ['LOWBAT', 'LOW_BAT'],
+    unreach:  ['UNREACH'],
+    // HmIP named fault flags (collected as their own booleans).
+    hmipFlags: Object.keys(HMIP_FAULT_FLAGS),
+};

package/feezal-movement.js

@@ -0,0 +1,185 @@
+/**
+ * E128 / E154 — movement indication for actuators that take visible time to
+ * travel: blinds/shutters (`DIRECTION` while the motor runs) and motor door
+ * locks (Keymatic `DIRECTION` while it turns).
+ *
+ * Two pieces, deliberately separate:
+ *
+ *  - `parseDirection()` — the shared value→direction reading. Homematic's
+ *    `DIRECTION` is an enum (`NONE` / `UP` / `DOWN` / `UNDEFINED`, device values
+ *    0…3, verified against OpenCCU-Base `rf_keymatic.xml`); depending on the
+ *    interface it arrives as the option NAME or as the numeric index, so both
+ *    are accepted. Any other/absent value reads as idle — an unwired movement
+ *    topic simply means "no indication", exactly like E127's WORKING.
+ *
+ *  - `MovementController` — the DISCRETE-state analog of E127's numeric
+ *    `SettlingController`, for locks. A numeric settler holds a slider at its
+ *    target until the reports catch up; a lock has no numeric scale, it has a
+ *    transitional "…ing" state that must be held between the command and the
+ *    device's confirmation, so `SettlingController` does not fit (the E154
+ *    build flagged this). The rules:
+ *      • `command(intent, expected)` — the user pressed Lock/Unlock/Open:
+ *        enter the transitional state immediately (the device reports STATE
+ *        only once it is done, and some interfaces echo the OLD state first).
+ *      • `signal(active, hint)` — the device's movement datapoint. When one is
+ *        wired it is the AUTHORITY: active extends the transitional state
+ *        (also for movement started elsewhere — a physical key turn), idle
+ *        ends it. `hint` names the intent when there was no local command.
+ *      • `report(state)` — a resolved state report. It ends the transitional
+ *        state only when NO movement signal is wired (otherwise the signal
+ *        does), and only once the expected state is reached — so an echo of
+ *        the pre-command state cannot cut the hold short.
+ *      • `timeoutMs` — the fallback that always resolves, so a lost
+ *        DIRECTION=NONE or a device that never confirms cannot leave the card
+ *        stuck "locking…" forever.
+ */
+
+import {svg} from 'lit';
+import {css, html} from './feezal-element.js';
+
+/** Homematic DIRECTION enum indices (OpenCCU-Base `rf_keymatic.xml`). */
+const DIRECTION_INDEX = {0: '', 1: 'up', 2: 'down', 3: ''};
+
+/**
+ * Read a movement-datapoint value as `'up'` / `'down'` / `''` (idle).
+ *
+ * @param {*} value                 the raw datapoint value
+ * @param {string} [upPayload]      configured payload meaning "up"
+ * @param {string} [downPayload]    configured payload meaning "down"
+ */
+export function parseDirection(value, upPayload = 'UP', downPayload = 'DOWN') {
+    if (value === null || value === undefined || value === false) return '';
+    const raw = String(value).trim();
+    if (raw === '') return '';
+    const up = String(upPayload || 'UP').trim().toUpperCase();
+    const down = String(downPayload || 'DOWN').trim().toUpperCase();
+    const upper = raw.toUpperCase();
+    if (upper === up) return 'up';
+    if (upper === down) return 'down';
+    // Numeric form: the enum index as published by interfaces that send the
+    // device value instead of the option name.
+    if (/^-?\d+(\.\d+)?$/.test(raw)) return DIRECTION_INDEX[Number(raw)] ?? '';
+    return '';
+}
+
+/** True when the value reads as movement in either direction. */
+export function isMoving(value, upPayload, downPayload) {
+    return parseDirection(value, upPayload, downPayload) !== '';
+}
+
+export class MovementController {
+    /**
+     * @param {object} opts
+     * @param {() => void} [opts.onChange]        called whenever the transitional state changes
+     * @param {number} [opts.timeoutMs=20000]     hard fallback that always resolves
+     * @param {boolean} [opts.signalWired=false]  a movement datapoint feeds signal()
+     */
+    constructor({onChange = () => {}, timeoutMs = 20000, signalWired = false} = {}) {
+        this._onChange = onChange;
+        this._timeoutMs = timeoutMs;
+        this._signalWired = signalWired;
+        this._intent = '';       // 'locking' | 'unlocking' | 'opening' | 'moving'
+        this._expected = null;   // resolved state that ends the hold (no signal wired)
+        this._timer = null;
+    }
+
+    /** True while the actuator is (believed to be) moving. */
+    get moving() { return this._intent !== ''; }
+    /** The transitional intent, '' while idle. */
+    get intent() { return this._intent; }
+
+    /** The user issued a command — hold the transitional state. */
+    command(intent, expected = null) {
+        this._set(intent, expected);
+    }
+
+    /** Movement datapoint report; `hint` names the intent for external movement. */
+    signal(active, hint = 'moving') {
+        if (active) {
+            this._set(this._intent || hint || 'moving', this._expected);
+            return;
+        }
+        this._stop();
+    }
+
+    /** Resolved state report (e.g. the lock's STATE datapoint). */
+    report(state) {
+        if (!this.moving) return;
+        // A wired movement datapoint is the authority — it ends the hold.
+        if (this._signalWired) return;
+        if (this._expected === null || state === this._expected) this._stop();
+    }
+
+    dispose() { this._clear(); }
+
+    _set(intent, expected) {
+        const changed = this._intent !== intent;
+        this._intent = intent;
+        this._expected = expected;
+        this._clear();
+        this._timer = setTimeout(() => { this._timer = null; this._stop(); }, this._timeoutMs);
+        if (changed) this._onChange();
+    }
+
+    _stop() {
+        this._clear();
+        if (this._intent === '') return;
+        this._intent = '';
+        this._expected = null;
+        this._onChange();
+    }
+
+    _clear() {
+        if (this._timer) { clearTimeout(this._timer); this._timer = null; }
+    }
+}
+
+/**
+ * Shared movement badge (E128 covers / E154 locks) — a small pulsing chevron
+ * that points the way the actuator is travelling, or a neutral pulse when the
+ * direction is unknown. Positioned top-left by default (top-right is the
+ * availability badge, bottom-right the E124 battery symbol); families move it
+ * with the `--feezal-movement-*` custom properties. Colour is `currentColor`
+ * so every family's chrome carries it without a per-family override.
+ */
+export const feezalMovementStyles = css`
+    .feezal-move-badge {
+        position: absolute;
+        top: var(--feezal-movement-top, 6px);
+        left: var(--feezal-movement-left, 6px);
+        width: var(--feezal-movement-size, 16px);
+        height: var(--feezal-movement-size, 16px);
+        color: var(--feezal-movement-color, currentColor);
+        opacity: 0.9; pointer-events: none; z-index: 2;
+    }
+    .feezal-move-badge svg { width: 100%; height: 100%; display: block; }
+    /* E154: applied to the element a family already draws (the lock disc /
+       icon) so a motor lock reads as "working" without adding chrome — the
+       badge above is for actuators whose DIRECTION is meaningful (blinds). */
+    @media (prefers-reduced-motion: no-preference) {
+        .feezal-move-badge,
+        .feezal-moving { animation: feezal-move-pulse 1.1s ease-in-out infinite; }
+    }
+    @keyframes feezal-move-pulse {
+        0%, 100% { opacity: 0.25; }
+        50%      { opacity: 1; }
+    }
+`;
+
+/**
+ * Movement badge template partial: renders nothing while idle.
+ *
+ * @param {''|'up'|'down'|'moving'|string} direction  '' = idle
+ * @param {string} [title]                            tooltip / a11y label
+ */
+export function movementBadge(direction, title = 'Moving') {
+    if (!direction) return '';
+    // `svg` (not `html`): these fragments live inside the <svg> root below, so
+    // they must be created in the SVG namespace.
+    const glyph = direction === 'up'
+        ? svg`<path d="M12 5 L20 15 H4 Z" fill="currentColor"/>`
+        : direction === 'down'
+            ? svg`<path d="M12 19 L4 9 H20 Z" fill="currentColor"/>`
+            : svg`<circle cx="12" cy="12" r="6" fill="currentColor"/>`;
+    return html`<span class="feezal-move-badge" title="${title}"><svg viewBox="0 0 24 24" aria-hidden="true">${glyph}</svg></span>`;
+}

package/feezal-sensor-types.js

@@ -0,0 +1,143 @@
+/**
+ * E132 — the generalized boolean-sensor vocabulary, defined ONCE for the
+ * three family cards (material-motion / glass-occupancy / metro-occupancy —
+ * palette name "Sensor" since E132; the tag renames wait for the alias
+ * mechanism). Water alarms, smoke alarms and motion sensors all behave the
+ * same way: one boolean state, an icon that flips, a text per state,
+ * battery-driven hardware — this module carries the per-type defaults, the
+ * shared HA `device_class` map and the E124 battery-low attribute trio, the
+ * `publishLocalAttribute` way (name/help written once, E117 precedent).
+ */
+
+// type → per-state defaults. `alarm: true` classes render their ACTIVE state
+// in the error colour — an active fire alarm is not a neutral state chip.
+export const SENSOR_TYPES = {
+    motion:       {icon: 'directions_walk',       iconClear: 'directions_walk', textActive: 'Motion',    textClear: 'Clear',    alarm: false},
+    presence:     {icon: 'person',                iconClear: 'person_outline',  textActive: 'Occupied',  textClear: 'Clear',    alarm: false},
+    radar:        {icon: 'radar',                 iconClear: 'radar',           textActive: 'Presence',  textClear: 'Clear',    alarm: false},
+    zone:         {icon: 'meeting_room',          iconClear: 'meeting_room',    textActive: 'Occupied',  textClear: 'Vacant',   alarm: false},
+    'water-leak': {icon: 'water_damage',          iconClear: 'water_drop',      textActive: 'Leak!',     textClear: 'Dry',      alarm: true},
+    smoke:        {icon: 'local_fire_department', iconClear: 'detector_smoke',  textActive: 'Smoke!',    textClear: 'Clear',    alarm: true},
+    gas:          {icon: 'warning',               iconClear: 'gas_meter',       textActive: 'Gas!',      textClear: 'Clear',    alarm: true},
+    co:           {icon: 'co2',                   iconClear: 'co2',             textActive: 'CO!',       textClear: 'Clear',    alarm: true},
+    vibration:    {icon: 'vibration',             iconClear: 'check_circle',    textActive: 'Triggered', textClear: 'OK',       alarm: false},
+    tamper:       {icon: 'lock_open',             iconClear: 'check_circle',    textActive: 'Tamper!',   textClear: 'OK',       alarm: true},
+    generic:      {icon: 'sensors',               iconClear: 'sensors_off',     textActive: 'Active',    textClear: 'Inactive', alarm: false},
+};
+
+export const SENSOR_TYPE_OPTIONS = Object.keys(SENSOR_TYPES);
+
+// ── E138: motion vs alarm SLICES of the vocabulary ──────────────────────────
+// The boolean card splits into two UX characters with different active-state
+// colour semantics: MOTION/presence (expected activity → accent colour) and
+// ALARM (exceptional → error colour). The slices are the single source of truth
+// for both the per-family element `type` option lists and the discovery
+// device_class routing. The combined SENSOR_TYPES / SENSOR_TYPE_OPTIONS /
+// SENSOR_DEVICE_CLASS_MAP above are unchanged (= slice 'all'); the current three
+// boolean cards keep the full vocabulary until the E138 rename phase.
+export const MOTION_SENSOR_TYPES = ['motion', 'presence', 'radar', 'zone'];
+export const ALARM_SENSOR_TYPES = ['water-leak', 'smoke', 'gas', 'co', 'vibration', 'tamper', 'generic'];
+
+// Active-state default colour var per slice (canonical theme vars, spec §5.1).
+// motion-slice active → --accent-color; alarm-slice active → --error-color.
+// These are DEFAULTS a view consumes (per-element --feezal-* overrides win).
+export const SENSOR_SLICE_COLOR_VARS = {motion: '--accent-color', alarm: '--error-color'};
+
+// Stamp each type entry with its slice's active colour var, derived from the
+// slice arrays so the two never drift. A view reads `sensorType(t).colorVar`.
+for (const t of MOTION_SENSOR_TYPES) if (SENSOR_TYPES[t]) SENSOR_TYPES[t].colorVar = SENSOR_SLICE_COLOR_VARS.motion;
+for (const t of ALARM_SENSOR_TYPES) if (SENSOR_TYPES[t]) SENSOR_TYPES[t].colorVar = SENSOR_SLICE_COLOR_VARS.alarm;
+
+/** The type-option list for a slice ('motion' | 'alarm' | 'all'). */
+export function sensorTypesFor(slice = 'all') {
+    if (slice === 'motion') return MOTION_SENSOR_TYPES;
+    if (slice === 'alarm') return ALARM_SENSOR_TYPES;
+    return SENSOR_TYPE_OPTIONS;
+}
+
+/** Default `type` value for a slice (motion/all → motion; alarm → generic). */
+export function sensorDefaultTypeFor(slice = 'all') {
+    return slice === 'alarm' ? 'generic' : 'motion';
+}
+
+/** The active-state colour var for a type ('all' resolves via slice membership). */
+export function sensorActiveColorVar(type) {
+    return sensorType(type).colorVar || SENSOR_SLICE_COLOR_VARS.alarm;
+}
+
+/** Resolve a type entry (unknown → generic). */
+export function sensorType(type) {
+    return SENSOR_TYPES[type] || SENSOR_TYPES.generic;
+}
+
+// HA/z2m `device_class` → feezal `type` — one map for all three cards AND
+// consistent with what the Homematic sensor recognizer emits (E131 keeps its
+// output HA-shaped: motion / moisture / smoke).
+export const SENSOR_DEVICE_CLASS_MAP = {
+    motion: 'motion',
+    occupancy: 'presence',
+    presence: 'presence',
+    moisture: 'water-leak',
+    smoke: 'smoke',
+    gas: 'gas',
+    carbon_monoxide: 'co',
+    vibration: 'vibration',
+    tamper: 'tamper',
+    _default: 'generic',
+};
+
+// E138: slice-restricted device_class → type maps. A `*-motion` element routes
+// only motion/occupancy/presence (unknown → motion); a `*-sensor` (alarm)
+// element routes only the hazard classes (unknown → generic). The combined map
+// above stays the 'all' behaviour for the current, not-yet-split cards.
+export const MOTION_DEVICE_CLASS_MAP = {
+    motion: 'motion',
+    occupancy: 'presence',
+    presence: 'presence',
+    _default: 'motion',
+};
+export const ALARM_DEVICE_CLASS_MAP = {
+    smoke: 'smoke',
+    moisture: 'water-leak',
+    gas: 'gas',
+    carbon_monoxide: 'co',
+    vibration: 'vibration',
+    tamper: 'tamper',
+    _default: 'generic',
+};
+
+/** The device_class → type map for a slice ('motion' | 'alarm' | 'all'). */
+export function sensorDeviceClassMapFor(slice = 'all') {
+    if (slice === 'motion') return MOTION_DEVICE_CLASS_MAP;
+    if (slice === 'alarm') return ALARM_DEVICE_CLASS_MAP;
+    return SENSOR_DEVICE_CLASS_MAP;
+}
+
+// ── E124: the shared low-battery attribute trio (+ threshold) ───────────────
+// Battery devices signal a weak battery as a WARNING icon, not a blackout —
+// the sensor keeps reporting its state. Auto-stamped by discovery from the
+// canonical `battery_low_normalized` record (both ecosystems).
+export const batteryLowAttributes = [
+    {name: 'subscribe-battery-low', type: 'mqttTopic', section: 'Battery',
+        help: 'Optional low-battery topic. Boolean payloads compare against payload-battery-low; a numeric payload (battery percentage) compares against battery-low-threshold. Shows a warning icon — the state keeps updating. Stamped by auto-discovery (zigbee2mqtt battery sibling / Homematic :0 LOWBAT·LOW_BAT).'},
+    {name: 'message-property-battery-low', type: 'string', default: 'payload', section: 'Battery', advanced: true,
+        help: 'Dot-notation path within the battery message. Blank = fall back to element-level message-property.'},
+    {name: 'payload-battery-low', type: 'string', default: 'true', section: 'Battery',
+        help: 'Payload meaning the battery is low (boolean payloads; true/1 coercion included).'},
+    {name: 'battery-low-threshold', type: 'number', default: 15, section: 'Battery',
+        help: 'When the subscribed value is a battery PERCENTAGE (0–100), values at or below this show the low-battery icon.'},
+];
+
+/**
+ * Interpret a battery-low payload value: numbers above 1 are treated as a
+ * battery percentage (≤ threshold ⇒ low); everything else matches the
+ * payload-battery-low compare value with the usual true/1 coercion.
+ */
+export function batteryLowFromValue(v, payloadLow = 'true', threshold = 15) {
+    const asNum = typeof v === 'number' ? v
+        : (typeof v === 'string' && v.trim() !== '' && !Number.isNaN(Number(v)) ? Number(v) : null);
+    if (asNum !== null && asNum > 1) return asNum <= Number(threshold ?? 15);
+    return v === true || v === 1 || String(v) === '1'
+        || String(v).toLowerCase() === 'true'
+        || String(v) === String(payloadLow);
+}

package/feezal-settling.js

@@ -0,0 +1,170 @@
+/**
+ * E127 — SettlingController: suppression logic for ramping actuators.
+ *
+ * Homematic dimmers (and blinds, E128) ramp towards a commanded LEVEL and
+ * report every intermediate value on the way — a slider that follows those
+ * reports jumps around right after the user set it. This controller decides
+ * which incoming reports may reach the display:
+ *
+ *  - command(target): the element just published a set value → hold the
+ *    display at the target. Intermediate reports are swallowed until the
+ *    reported value reaches the target, a settled signal arrives, or the
+ *    settle timeout reconciles to the last reported value (interrupted
+ *    ramps, device clamping, sentinel targets like Homematic's 1.005
+ *    OLD_LEVEL restore that the device never echoes verbatim).
+ *  - working(active): the device's WORKING datapoint. `true` enters/extends
+ *    suppression (covers ramps started elsewhere); `false` ends it and
+ *    applies the last report as the settled value.
+ *  - live(value): a report from the state topic. Applied directly when idle;
+ *    swallowed while holding/ramping. When a WORKING topic is wired, idle
+ *    reports are buffered for `reportDelayMs` first — interfaces cannot
+ *    guarantee WORKING=true precedes the first intermediate report (it
+ *    arrives ≤ ~100 ms after), so a WORKING=true within the buffer cancels
+ *    the pending jumpy update.
+ *  - settled(value): a report from a settled-values-only topic (RedMatic's
+ *    LEVEL_NOTWORKING). Always applied, ends any hold.
+ *
+ * The controller is value-scale-agnostic (raw device values in, raw values
+ * out through the apply callback) and family-agnostic — lights use it for
+ * brightness, covers (E128) for position.
+ */
+
+const TARGET_EPSILON = 1e-3;
+
+export class SettlingController {
+    /**
+     * @param {object} opts
+     * @param {(value: number) => void} opts.apply   applies a raw report to the element state
+     * @param {number} [opts.timeoutMs=5000]         hold/ramp reconcile timeout
+     * @param {number} [opts.reportDelayMs=100]      idle-report buffer while a WORKING topic is wired (0 = off)
+     * @param {boolean} [opts.workingWired=false]    a WORKING topic feeds working()
+     * @param {boolean} [opts.settledWired=false]    a settled topic feeds settled() — live() then never drives apply
+     */
+    constructor({apply, timeoutMs = 5000, reportDelayMs = 100, workingWired = false, settledWired = false}) {
+        this._apply = apply;
+        this._timeoutMs = timeoutMs;
+        this._reportDelayMs = reportDelayMs;
+        this._workingWired = workingWired;
+        this._settledWired = settledWired;
+
+        this._holding = false;      // own command in flight
+        this._target = null;
+        this._ramping = false;      // externally initiated ramp (WORKING=true seen)
+        this._lastLive = null;      // most recent live report (raw)
+        this._timeout = null;
+        this._pending = null;       // {value, timer} — buffered idle report
+    }
+
+    /** The element just published `target` (raw device scale). */
+    command(target) {
+        this._cancelPending();
+        this._holding = true;
+        this._ramping = false;
+        this._target = Number(target);
+        this._startTimeout();
+    }
+
+    /** Report from the live state topic (raw device scale). */
+    live(value) {
+        this._lastLive = value;
+        if (this._settledWired) return;                 // slider follows the settled topic only
+        if (this._holding) {
+            if (Math.abs(value - this._target) <= TARGET_EPSILON) this._settle(value);
+            return;                                     // swallow intermediate ramp values
+        }
+        if (this._ramping) return;                      // swallow external ramp values
+        if (this._workingWired && this._reportDelayMs > 0) {
+            // Buffer so a trailing WORKING=true can cancel the jumpy update.
+            // The timer runs from the FIRST buffered report; later reports
+            // only update the pending value (a ramp without WORKING must not
+            // starve the display forever).
+            if (this._pending) {
+                this._pending.value = value;
+            } else {
+                this._pending = {
+                    value,
+                    timer: setTimeout(() => {
+                        const v = this._pending.value;
+                        this._pending = null;
+                        this._apply(v);
+                    }, this._reportDelayMs),
+                };
+            }
+            return;
+        }
+        this._apply(value);
+    }
+
+    /** WORKING datapoint report. */
+    working(active) {
+        // B60: when a settled-values topic (RedMatic LEVEL_NOTWORKING) is wired it
+        // is the SOLE authority — the control follows command()/settled() only, so
+        // WORKING is redundant AND harmful here. RedMatic delivers WORKING=false a
+        // moment BEFORE the settled value, and `_lastLive` at that instant is a
+        // mid-ramp (often near-old) reading; acting on the WORKING=false edge would
+        // snap the slider to that stale value and then correct when the settled
+        // value lands — the reported two-step jump. Ignore WORKING entirely in
+        // settled mode. (WORKING-only devices, with no settled topic, are
+        // unaffected and still rely on it below.)
+        if (this._settledWired) return;
+        if (active) {
+            this._cancelPending();
+            if (!this._holding && !this._ramping) {
+                this._ramping = true;
+                this._startTimeout();                   // safety: a lost WORKING=false must not freeze the display
+            }
+            return;
+        }
+        if (this._holding || this._ramping) this._settle(this._lastLive);
+    }
+
+    /** Report from the settled-values topic (LEVEL_NOTWORKING). */
+    settled(value) {
+        this._settle(value);
+    }
+
+    /**
+     * Abandon any hold/ramp WITHOUT applying a value — E128: the user pressed
+     * STOP, so the actuator halts somewhere between the old value and the
+     * target and the target is no longer meaningful. The next report must
+     * reach the display immediately instead of being swallowed until the
+     * timeout. (`settled()` would additionally apply a stale mid-travel value.)
+     */
+    cancel() {
+        this._holding = false;
+        this._ramping = false;
+        this._target = null;
+        this._clearTimeout();
+        this._cancelPending();
+    }
+
+    dispose() {
+        this._clearTimeout();
+        this._cancelPending();
+    }
+
+    _settle(value) {
+        this._holding = false;
+        this._ramping = false;
+        this._target = null;
+        this._clearTimeout();
+        this._cancelPending();
+        if (value !== null && value !== undefined && !Number.isNaN(Number(value))) this._apply(Number(value));
+    }
+
+    _startTimeout() {
+        this._clearTimeout();
+        this._timeout = setTimeout(() => {
+            this._timeout = null;
+            this._settle(this._lastLive);
+        }, this._timeoutMs);
+    }
+
+    _clearTimeout() {
+        if (this._timeout) { clearTimeout(this._timeout); this._timeout = null; }
+    }
+
+    _cancelPending() {
+        if (this._pending) { clearTimeout(this._pending.timer); this._pending = null; }
+    }
+}

package/package.json

@@ -14,9 +14,14 @@
     "feezal": {},
     "files": [
         "feezal-element.js",
+        "feezal-color.js",
         "feezal-conditions.js",
         "feezal-friendly-name.js",
+        "feezal-hm-fault.js",
+        "feezal-movement.js",
         "feezal-polymer-element.js",
+        "feezal-sensor-types.js",
+        "feezal-settling.js",
         "feezal-topic-input.js",
         "LICENSE"
     ],
@@ -36,5 +41,5 @@
         "url": "git+https://github.com/feezal/feezal.git",
         "directory": "www/packages/@feezal/feezal-element"
     },
-    "version": "3.0.12"
+    "version": "3.0.13"
 }