houseplan-card/docs/LIVE-TEXT.md

The text block — a decor label that can show an entity's state

Status: implemented (dev, unreleased). Code: src/logic.ts (liveText, liveTextValue, decorTextScale, decorTextLines — pure, unit-tested), src/houseplan-card.ts (_renderDecorLayer, _renderTextFrame, _renderDecorTextDialog, the _dt* gestures), custom_components/houseplan/validation.py (DECOR_SCHEMA, text branch). Smokes: demo/smoke_live_text.mjs, demo/smoke_decor_text.mjs; demo/smoke_decor.mjs keeps the surrounding decor contract.

The shape: {kind:'text', x, y, text, color, scale?, angle?, entity?, attr?, unit?} — plus the legacy size? that older plans still carry. Everything after color is optional, so every existing plan validates and renders unchanged and no migration runs.

1. Why a live label

The plan already answers "which lamps are on" and "how warm is the bedroom" through icons and room fills. It cannot answer the things a house says in words: water tank 68 %, garage 12 °C, watering tonight at 20:00, firewood left: 3 days. Today a user who wants that puts a device marker in "value instead of icon" mode — which gives a badge with a bare number, always tied to a device with a position, an area and a tap action. What is missing is the caption on the wall: free-standing text, in the user's own words, that happens to have a live number in it.

The competing card (ha-floorplan) covers this with text_set and it is one of its most used features; our decor text was one field away from it.

2. The live value

A decor text shape has three optional fields:

• entity — an entity id whose state is substituted; absent = today's plain static label, byte-for-byte unchanged;
• attr — an attribute name to read instead of state (battery level, current temperature of a climate, position of a cover); absent = the state;
• unit — a suffix; absent = the entity's own unit_of_measurement, so sensor.tank needs no configuration to read 68 %.

The text field keeps its present meaning and becomes the template: the placeholder {} is where the value lands. Бак {} → Бак 68 %. A template without a placeholder gets the value appended after a space, so a user who only picks an entity and types nothing sensible still sees something useful. Only the first {} is replaced — one label, one value.

{} was chosen over {{ }} deliberately: this is a substitution, not a template language. There is no expression, no condition, no arithmetic — the moment we accept {{ states('x') | round(1) }} we have signed up for the class of support load that fills the competitor's thread (138 posts of "my CSS/template does not work"). One value, one place, no syntax to get wrong.

2.1. Rendering rules

• The value is read live from hass on every render — the same source as the rest of the card, no polling and no subscriptions of its own. A new hass repaints the label; nothing is re-created.
• Unavailable / unknown / missing entity → the value renders as — (an em dash) and the dash carries no unit («— °C» is not a reading); the rest of the template stays. A label that silently disappears when a sensor dies is worse than one that says "no data": the user must see that the caption is alive and the sensor is not.
• An attribute that is not on the entity, or that is a dict, renders as the same dash. A list attribute is joined with , ; 0 and false are values, not absences.
• Home Assistant formats the value; we still write no formatting of our own. (Refined 2026-08-05 — the rule below is narrowed, not revoked.) We do not round, do not reformat and do not localise decimal separators ourselves: we hand the state object to HA's own formatter (hass.formatEntityState, and hass.formatEntityAttributeValue for an attribute) through the single wrapper hassValue() in src/logic.ts — the same call HA's more-info makes. So the label obeys the sensor's display_precision, the user's decimal separator and the state translations (on → Включено), because those are the user's HA settings and the settings are the one source of truth. What is forbidden is duplicating that logic here, not delegating it. An older HA without the formatter falls back to the raw state, byte-for-byte the pre-2026-08-05 behaviour. Imperial/metric is not our business either — the value and the unit come from HA (docs/STYLING-HOOKS.md §6).
• The unit is inherited only for the STATE. With an attr the entity's unit_of_measurement is not applied: it describes the state, and a battery_level read off a °C sensor must not come out as «73 °C». An explicit unit always wins; an empty one inherits.
• The unit appears exactly once. HA's formatter normally appends the entity's unit itself, so the inherited one is not added a second time — and where it does not append it, ours still is, so the unit never silently disappears either. The rule: strip the entity's own unit_of_measurement if it is already the tail (exact trailing match, nothing else in the string is touched), then append the unit actually wanted — the user's explicit one, or the entity's own.
• The value is clipped to LIVE_TEXT_VALUE_MAX (60) characters: a caption is a caption, and an attribute that turns out to be a 4 KB string must not become the plan's wallpaper.
• Editors and kiosk render it identically; in the decor editor the live value is shown (not the raw template), so the user sees what visitors will see while positioning it. The read-only houseplan-space-card does not render the decor layer at all — that is unchanged, and out of scope here.

3. The block: size, rotation, lines

The old size: 's'|'m'|'l' selector is gone from the dialog. A caption's size is not one of three opinions; it is whatever fits the place it is put in.

• scale — a font multiplier against the base 20 px, written by dragging a corner of the selected block (select tool). Bounded 0.15…20 in the card and in the backend.
• angle — degrees, written by the handle above the block. The step is 5°, the same step a device icon rotates in; Shift drags past it, as past every other snap in this card (docs/CANVAS.md §9.4). Rotating back to zero removes the field, so a straight label stores nothing.
• No migration for size. A stored size is read as the multiplier it used to render at — s = 0.7 (14 px), m = 1 (20 px), l = 1.5 (30 px) — so an old label comes back at exactly its old size. An explicit scale wins, and the first corner drag replaces size with the scale it meant: a shape never states its size twice. size stays in DECOR_SCHEMA (still bounded to the three known values) precisely because old plans keep sending it.
• Line breaks are the user's own. The dialog's field is a textarea; a newline is stored and rendered as a newline (one <tspan> per line, line height 1.2 em). The label never wraps by itself — a caption that reflows on every state change is a caption that jumps around the plan. A 300-character line stays one line.
• Multi-line blocks are centred, horizontally (the decor layer's text-anchor: middle, which single-line labels already used) and vertically: the anchor x/y sits in the middle of the block, so adding a second line grows the label in both directions instead of pushing the first one up.
• Both gestures pivot on the anchor (x/y), not on a box corner, so a label never walks away from the point it was placed at, and a rotated block still scales along the same axis (a distance from the anchor is invariant under its own rotation). The frame chrome — dashed outline, four corner handles, one rotate handle on a stem — reuses the backdrop frame's mechanics and sizes: chrome that never takes a pointer, handles that always do, with a hit radius of 1.8 % of the visible view so they stay finger-sized at any zoom (docs/BACKDROP.md §2). What you see is a quarter of that (owner, 2026-08-05: «уменьшить в 4 раза») — a bead, not a button, so the frame stops covering the words it frames. The two are different elements: an invisible .dthandle circle at the full radius owns the gesture, a .dtknob circle at hr / 4 owns the paint and takes no pointer. The clickable area is therefore unchanged; only the ink shrank. Same split the wall-resize handles use (docs/RESIZE.md).
• The frame is measured from the rendered glyphs (getBBox), so it appears one frame after the text and follows every edit of it.

4. Tools: what a click does

Decor shapes are inert under a drawing tool — a new line must be able to start exactly on the end of an old one (owner, 2026-08-04). The text tool has one exception, asked for by the owner on the same day:

Text tool, press on…	What happens
an existing label	its editor opens (the same form, prefilled)
empty canvas	a new label is created there
a non-text shape (line, rect, ellipse)	a new label is created there; the shape stays inert

Under the select tool a label is selected and dragged as before, a double click opens its editor, and the corner/rotate handles appear.

5. The dialog

Under the text field:

• a textarea (line breaks are content now), saved with the button or Ctrl/⌘+Enter — plain Enter is a new line;
• a hint that mentions {} only when an entity is chosen — an unlinked label must not be burdened with syntax it does not need;
• an entity picker with a datalist of all entities — the same control style the vacuum source and the weather field use;
• an attribute field, shown only once an entity is chosen, with a datalist of that entity's actual attribute names — the user should not have to know that a climate keeps current_temperature;
• a unit field whose placeholder is the entity's own unit, so leaving it empty is the obvious right answer (the placeholder disappears once an attribute is chosen, because an attribute does not inherit it);
• a live preview of the resulting label, rendered through the same liveText the plan uses: one substitution, one truth.

Clearing the entity clears the attribute and the unit with it — a save never leaves orphan fields in the config.

6. Backend

DECOR_SCHEMA, text branch: entity optional, None or an entity id (^[a-z0-9_]+\.[a-z0-9_]+$, ≤ 255); attr optional, None or a flat name ≤ 64; unit optional, None or ≤ 16 characters; scale optional, finite, 0.15…20; angle optional, finite, -360…360; text ≤ 200 characters, newlines included. Everything optional, so every existing plan validates unchanged. Tests: tests_backend/test_validation.py (test_decor_text_live_fields, test_decor_text_block_scale_and_angle).

7. What this is not

• Not a second device marker. No tap action, no icon, no state class, no participation in room aggregation (LQI, climate averages) — it is a caption, not a device. A user who wants an interactive thing puts a marker.
• Not a template engine (see §2).
• Not a multi-entity widget. One label, one value. Two values are two labels; that stays honest and costs the user one drag.
• Not an auto-layout. No wrapping, no shrink-to-fit: the size is set with the corners and the lines with the Enter key.