Implement Widget

Implement Widget Renderer: $widget-type

Implement the SVG template and Python context builder for $widget-type. The output of this work is two artifacts:

1. custom_components/eink_dashboard/templates/$widget-type.svg.j2
2. _build_$widget-type_context() in widgets/$widget-type.py

Before you start

1. Read the existing tests (TestRender{WidgetName} in tests/test_render_{widget_type}.py) — these define the expected behavior.
2. Read const.py for WidgetType, COLOR_* constants, PADDING, DEFAULT_CARD_STYLE, Widget, DisplayConfig, color_to_hex.
3. Read svg_render.py for the Jinja2 environment, _svg_to_png(), icon filter functions (_mdi_svg_filter, _weather_svg_filter), and _SVG_RENDERERS.
4. Read existing widget modules in widgets/ (e.g. widgets/tile.py) for the context builder pattern, and widgets/_helpers.py for shared layout helpers.
5. Read templates/_macros.svg.j2 for the three shared macros: card_container, card_row, chip.

Current SVG infrastructure (svg_render.py)

!grep -n "^def \|^_SVG_RENDERERS\|^_jinja_env\|^_TEMPLATE_DIR\|^_FONTS_DIR\|^_mdi\|^_weather" custom_components/eink_dashboard/svg_render.py

Shared layout helpers (widgets/_helpers.py)

!grep -n "^def \|^_ACTIVE" custom_components/eink_dashboard/widgets/_helpers.py

Existing widget context builders

!grep -rn "^def _build_" custom_components/eink_dashboard/widgets/*.py

SVG macro signatures

!grep -n "macro card_container\|macro card_row\|macro chip\|macro icon_circle" custom_components/eink_dashboard/templates/_macros.svg.j2

WidgetMetrics and _compute_metrics (in render.py)

!grep -n "^class WidgetMetrics" -A 10 custom_components/eink_dashboard/render.py

!grep -n "^def _compute_metrics" -A 12 custom_components/eink_dashboard/render.py

Icon name resolver (in render.py)

!grep -n "^def _device_class_icon" -A 6 custom_components/eink_dashboard/render.py

Current SVG renderer registry

!grep -n "_SVG_RENDERERS" -A 12 custom_components/eink_dashboard/svg_render.py

Imports

Context builders live in widgets/{type}.py and use relative imports. _compute_metrics, _device_class_icon, and _load_font live in render.py. color_to_hex, Widget, DisplayConfig, and constants live in const.py. Layout helpers live in widgets/_helpers.py.

from ..const import (
    DEFAULT_CARD_STYLE,
    DEFAULT_ROW_H,
    PADDING,
    DisplayConfig,
    Widget,
    color_to_hex,
)
from ..render import (
    _compute_metrics,
    _device_class_icon,
    _load_font,        # chip width measurement only
)
from ..svg_render import _mdi_svg_filter
from ._helpers import (
    _auto_row_height,
    _card_insets,
    _color_context,
    _fmt,
    _metrics_context,
    _widget_dim,
)

Use _fmt(state_val, config) whenever a context builder formats a numeric entity state for display. This applies locale-aware decimal and thousands separators matching the owner's HA preference. Pass the raw state string — non-numeric strings ("on", "unavailable") are returned unchanged.

_color_context() in widgets/_helpers.py returns {"hex_black": ..., "hex_white": ..., "hex_gray": ...} by calling color_to_hex() on the const.py integer constants. Spread it into the context dict with **_color_context() so templates can use {{ hex_gray }} instead of hardcoded hex literals.

Macro usage notes

• card_container uses Jinja2 {% call %} syntax. The macro passes (x_off, right_inset) back to the caller body: "border" → (m.padding, m.padding); "left_bar" → (bar_w + m.padding, 0); "none" → (0, 0). Content starts at x_off; content width = w - x_off - right_inset. Always pass display_levels from config.
• card_row expects all sizes from WidgetMetrics fields plus icon_svg (pre-built SVG string, empty string for letter fallback) and letter (single uppercase char, empty string when icon_svg is set). primary is the entity label; secondary is the state + unit. Pass lpad/rpad derived from _card_insets() to prevent double-padding when a card style already provides insets; use the same values for x1/x2 of any divider <line> between rows. Pass icon_no_circle=True when icon_style == "none" — the macro hides the circle but still renders the icon glyph.
• chip requires pre-computed w because text width depends on font metrics unavailable in Jinja2. The context builder must compute chip widths using _load_font(size).getlength(text) from PIL — the font object is used only for measurement, not for drawing.
• Icon filters generate the SVG string in Python. Call _mdi_svg_filter(name, size) in the context builder and pass the result as the icon_svg string to the template. Do NOT call filters from inside templates — pass the pre-built string via context.
• _device_class_icon(attrs, state_val, domain) returns an MDI icon name without the "mdi:" prefix, or None. Extract domain: entity_id.split(".")[0].

Implementation steps

1. Add to WidgetType enum (if new widget)

In const.py, add the new value to WidgetType. Keep alphabetical order.

2. Create the SVG template

Create custom_components/eink_dashboard/templates/$widget-type.svg.j2.

The template receives a pre-computed context dict from the Python context builder. All layout math (positions, sizes, icon SVG strings, chip widths) is computed in Python. Templates only emit SVG markup.

Widget SVGs are composited onto a white canvas using the alpha channel as a mask (render_dashboard() in render.py). Transparent pixels preserve whatever is already on the canvas (white by default), so most templates do not need a white background rect.

Add a full-viewport white background rect only when the template's rendered geometry is smaller than its SVG viewport — i.e. when content does not fill w × h. The separator is the canonical example: its bar (bar_w × bar_h) is much smaller than the widget viewport, so surrounding transparent area would let earlier widget content bleed through without the rect.

Card-style and chip-style templates omit the rect because the card chrome (via card_container) or chip flow covers the meaningful area, and any remaining transparent edge pixels are harmless (canvas is white).

Card-style template pattern (tile, waste_schedule):

{%- from "_macros.svg.j2" import card_container, card_row -%}
<svg xmlns="http://www.w3.org/2000/svg"
     width="{{ w }}" height="{{ h }}">
{%- call(x_off, r_inset) card_container(
    x=0, y=0, w=w, h=h,
    card_style=card_style,
    radius=m.radius, border=m.border,
    padding=m.padding, left_bar=m.left_bar,
    display_levels=display_levels) -%}
{%- for row in rows -%}
{{ card_row(
    x=x_off, y=row.y,
    w=w - x_off - r_inset, row_h=row_h,
    padding=m.padding, icon_dia=m.icon_dia,
    inner_gap=m.inner_gap, border=m.border,
    font_primary=m.font_primary,
    font_secondary=m.font_secondary,
    primary=row.primary,
    secondary=row.secondary,
    value=row.value,
    icon_svg=row.icon_svg,
    letter=row.letter,
    lpad=lpad, rpad=rpad) }}
{%- if not loop.last -%}
<line
  x1="{{ x_off + lpad }}"
  y1="{{ row.y + row_h }}"
  x2="{{ w - r_inset - rpad }}"
  y2="{{ row.y + row_h }}"
  stroke="{{ hex_gray }}" stroke-width="{{ m.divider }}"/>
{%- endif -%}
{%- endfor -%}
{%- endcall -%}
</svg>

Chip-style template pattern (device_battery):

{%- from "_macros.svg.j2" import chip -%}
<svg xmlns="http://www.w3.org/2000/svg"
     width="{{ w }}" height="{{ h }}">
{%- for c in chips -%}
{{ chip(
    x=c.x, y=c.y, w=c.w, h=chip_h,
    text=c.text, border=m.border,
    icon_svg=c.icon_svg,
    inverted=c.inverted) }}
{%- endfor -%}
</svg>

Simple template pattern (separator):

When rendered geometry (e.g. a bar or line) is smaller than the SVG viewport, include a full-size white rect before it so the surrounding area is not transparent:

<svg xmlns="http://www.w3.org/2000/svg"
     width="{{ w }}" height="{{ h }}">
<rect width="{{ w }}" height="{{ h }}" fill="{{ hex_white }}"/>
<!-- widget-specific SVG elements here -->
</svg>

Template coordinates are relative to origin (0, 0) — the outer composition handles absolute x/y placement on the dashboard.