Add display: pill — zone icon + initials marker (#213)

Opt-in entity display mode. When a person/device_tracker is inside a HA zone,
render the marker as a stadium pill with the zone icon + the entity's initials;
fall back to the normal initials marker otherwise.

Fixes the overlap decision vs #196 by keeping pill as a dedicated display mode.

Author: uofm-matt

README.md

@@ -99,7 +99,7 @@ Either the name of the `entity` or:
 | name                   | Default                               | note                                                                                          |
 |------------------------|---------------------------------------|-----------------------------------------------------------------------------------------------|
 | `entity`               |                                       | The entity id                                                                                 |
-| `display`              | `marker`                              | `icon`, `state`, `attribute` or `marker`. <br/>`marker` will display the picture if available. <br/>`icon` will display the icon if available, otherwise a label composed of first letters of the entity's name |
+| `display`              | `marker`                              | `icon`, `state`, `attribute`, `marker` or `pill`. <br/>`marker` will display the picture if available. <br/>`icon` will display the icon if available, otherwise a label composed of first letters of the entity's name. <br/>`pill` shows the entity's **current zone icon + its initials** together when it is inside a Home Assistant zone, and the normal initials marker otherwise. See [Place pill](#place-pill-display-pill). |
 | `picture`              |                                       | Set a custom picture to use on the marker.                                                    |
 | `icon`                 |                                       | Set a custom icon to use if `display` is set to `icon`. e.g. `mdi:cake`                           |
 | `label`                |                                       | Set a custom text label to display on the marker (overrides auto-generated initials). Works with picture overlays.                |
@@ -124,9 +124,96 @@ Either the name of the `entity` or:
 | `z_index_offset`       | 1                                     | z-index value that determines what is displayed on top when markers overlap. (Setting a gap of at least 20 between the values assigned to each entity is recommended.) |
 | `use_base_entity_only` | false                                 | When set to `true`, the tracking will use only the base entity without including any associated device trackers. This is useful for scenarios where you want to track the base entity directly and ignore any associated trackers. |
 | `position_update_threshold` | 10                               | Distance threshold in meters. Marker position only updates if the entity has moved more than this distance. Prevents unnecessary map updates from GPS drift. Useful for clustered markers. |
+| `pill_callout_min_zoom` | 15                              | Only for `display: pill`. Map zoom at/above which the pill is drawn as an offset callout (up-left of the point, with a thin leader line to a dot on the exact location). Below this zoom the pill simply centres on the point with no leader, so it isn't obtrusive when the whole region is in view. |
 | `circle`               |                                       | Display a circle around the marker. <br/>More details [Circle options](#circle-options) |
 | `geojson`              |                                       | Display GeoJSON data from an entity attribute. <br/>More details [GeoJSON options](#geojson-options) |
 
+### Place pill (`display: pill`)
+
+A `pill` marker answers "who is where" in a single glance. When a tracked entity
+is inside a Home Assistant zone, its marker is drawn as a small stadium ("pill")
+holding two circles: the **zone's icon** on the left and the entity's **initials**
+on the right — for example a church icon next to `ML`, or a home icon next to
+`MG`. When the entity is not in any zone it falls back to the normal initials
+marker. It is opt-in per entity and changes nothing for entities that don't set
+`display: pill`.
+
+#### Why
+
+With the stock marker you can see *that* someone is on the map, but to learn
+*which named place* they're at you have to recognise the spot or click through.
+And when a person sits on top of their home/zone, you either get two overlapping
+markers or a cluster bubble showing a count. The pill folds identity and place
+into one marker — "Mom is at the church" is readable without interaction — using
+data Home Assistant already has (zones + the entity's state).
+
+#### How it resolves the person and the place
+
+There is no extra configuration linking a person to a place; it is derived live:
+
+1. **The entity is the person.** You list a `person.*` or `device_tracker.*` on
+   the map as usual. The card already places it at its GPS position and derives
+   its **initials** from the entity's `friendly_name` (first letter of each word,
+   e.g. `Mom Location` → `ML`). `label:` still overrides the initials if set.
+2. **Zones are the named places.** Each HA `zone.*` has a `friendly_name`, an
+   `icon`, a latitude/longitude and a radius. These already exist whenever you
+   create a zone (Settings → Areas & Zones).
+3. **Home Assistant links them via state.** When a `device_tracker`/`person` is
+   inside a zone, HA sets that entity's **state to the zone's name** (the Home
+   zone reports `home`). This is the join between person and place, maintained by
+   HA core — the card doesn't compute geometry.
+4. **The card reads it back.** For a `pill` entity it takes the entity's raw
+   state, finds the `zone.*` whose `friendly_name` matches it (case-insensitive;
+   `home` → the Home zone), and uses that zone's `icon` for the left circle. If
+   the state is `not_home`/`away`/unknown — or matches no zone — there is no
+   place, so the normal initials marker is shown instead.
+5. **Tooltip.** Hovering shows `<person> is at <place>`, e.g. *Mom is at
+   Extended Family*. The person name is the entity's `friendly_name` with a
+   trailing `Location`/`Tracker`/`Device`/`Phone`/`GPS` stripped, so
+   `Mom Location` reads as `Mom`. (This uses a Leaflet tooltip, which opens
+   immediately, rather than the browser's delayed native `title`.)
+
+The marker is rebuilt automatically when the entity enters or leaves a zone, so
+the pill appears, swaps icon, or collapses to initials as the person moves.
+
+#### Zoom-aware callout
+
+At/above `pill_callout_min_zoom` (default `15`) the pill is offset up-and-left of
+the exact position and connected by a thin **leader line** to a small dot on the
+real location, so the pill doesn't cover what's underneath. Below that zoom — when
+the whole town or region is in view and a leader line would just be clutter — the
+pill simply centres on the point with no leader. Set `pill_callout_min_zoom` lower
+to engage the callout sooner, or very high to effectively disable it.
+
+#### Appearance
+
+The pill reuses the entity's existing `color` (the same per-entity colour the
+normal marker uses, or whatever you set with `color:`) for the outline, icon,
+initials and leader, and `size` for each circle. Dark mode is honoured.
+
+#### Requirements
+
+- The places must be real HA **zones** with an `icon` and a `friendly_name`
+  (icons like `mdi:home`, `mdi:church`, `mdi:account-group`).
+- The entity must report its zone in its **state** — GPS `device_tracker`s and
+  `person`s do this automatically; the Home zone reports `home`.
+
+#### Example
+
+```yaml
+type: custom:map-card
+entities:
+  - entity: device_tracker.mom_location
+    display: pill
+  - entity: person.matt
+    display: pill
+    pill_callout_min_zoom: 14   # show the offset callout a bit sooner
+```
+
+With `device_tracker.mom_location` in the *Extended Family* zone this renders a
+pill of `mdi:account-group` + `ML`, tooltip "Mom is at Extended Family"; when she
+leaves it becomes a plain `ML` marker.
+
 ### History options
 
 If `history_date_selection:true`, any entities that do not define their own `history_start` and `history_end` configuration will be automatically linked to this. Please ensure a card of `type: energy-date-selection`  exists on the page before enabling this.

src/components/MapCardEntityMarker.js

@@ -10,6 +10,8 @@ export default class MapCardEntityMarker extends LitElement {
       'tooltip': {type: String, attribute: 'tooltip'},
       'picture': {type: String, attribute: 'picture'},
       'icon': {type: String, attribute: 'icon'},
+      'placeIcon': {type: String, attribute: 'place-icon'},
+      'callout': {type: String, attribute: 'callout'},
       'color': {type: String, attribute: 'color'},
       'size': {type: Number},
       'tapAction': {type: Object, attribute: 'tap-action'},
@@ -18,12 +20,56 @@ export default class MapCardEntityMarker extends LitElement {
   }
 
   render() {
+    // When the entity is inside a named place, render a horizontal "pill":
+    // a stadium outline holding two circles - the zone icon (left) and the
+    // entity's initials (right). Otherwise fall back to the normal marker.
+    if (this.placeIcon) {
+      // Pill: zone icon (left) + initials (right). Geometry must match
+      // Entity.createMapMarker. When `callout` is on (zoomed in) the pill sits
+      // up-left of the point with a thin leader line down-right to a dot on the
+      // exact location; otherwise it just centers on the point (no leader).
+      const s = this.size;
+      const pillW = 2 * s + 14;
+      const pillH = s + 8;
+      const pill = html`
+        <div class="place-pill" style="border-color: ${this.color}; width: ${pillW}px; height: ${pillH}px;">
+          <div class="pill-badge" style="border-color: ${this.color}; width: ${s}px; height: ${s}px;">
+            <ha-icon icon="${this.placeIcon}" style="--icon-primary-color: ${this.color}; --mdc-icon-size: ${s - 14}px;"></ha-icon>
+          </div>
+          <div class="pill-badge pill-initials" style="border-color: ${this.color}; color: ${this.color}; width: ${s}px; height: ${s}px; font-size: ${Math.round(s * 0.5)}px;">
+            ${this.title}
+          </div>
+        </div>`;
+      if (this.callout !== "true") {
+        return html`
+          <div class="place-pill-wrap ${this.extraCssClasses ? this.extraCssClasses : ""}"
+               style="width: ${pillW}px; height: ${pillH}px;"
+               @click=${this._badgeTap}>
+            ${pill}
+          </div>`;
+      }
+      const off = Math.round(s * 0.7);
+      const boxW = pillW + off;
+      const boxH = pillH + off;
+      const dotX = boxW - 2, dotY = boxH - 2;
+      return html`
+        <div class="place-pill-wrap ${this.extraCssClasses ? this.extraCssClasses : ""}"
+             style="width: ${boxW}px; height: ${boxH}px;"
+             @click=${this._badgeTap}>
+          <svg class="pill-leader" width="${boxW}" height="${boxH}">
+            <line x1="${pillW - 2}" y1="${pillH - 2}" x2="${dotX}" y2="${dotY}"
+                  stroke="${this.color}" stroke-width="1.5"></line>
+            <circle cx="${dotX}" cy="${dotY}" r="2.5" fill="${this.color}"></circle>
+          </svg>
+          ${pill}
+        </div>
+      `;
+    }
     return html`
         <div
           class="marker ${this.picture ? "picture" : ""}  ${this.extraCssClasses ? this.extraCssClasses : ""}"
           style="border-color: ${this.color}; height: ${this.size}px; width: ${this.size}px;"
           @click=${this._badgeTap}
-          title="${this.tooltip}"
           >
           ${this._inner()}
         </div>
@@ -123,6 +169,53 @@ export default class MapCardEntityMarker extends LitElement {
       .suffix {
         margin-left: var(--ha-marker-suffix-margin, 2px);
       }
+      .place-pill-wrap {
+        position: relative;
+      }
+      .pill-leader {
+        position: absolute;
+        left: 0;
+        top: 0;
+        overflow: visible;
+        pointer-events: none;
+      }
+      .place-pill {
+        position: absolute;
+        left: 0;
+        top: 0;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        gap: 2px;
+        box-sizing: border-box;
+        padding: 3px 5px;
+        border-radius: 999px;
+        border: 1px solid var(--ha-marker-color, var(--primary-color));
+        background-color: var(--card-background-color);
+        font-size: var(--ha-marker-font-size, 1.5em);
+        white-space: nowrap;
+      }
+      .place-pill .pill-badge {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        box-sizing: border-box;
+        border-radius: 50%;
+        border: 1px solid var(--ha-marker-color, var(--primary-color));
+        background-color: var(--card-background-color);
+        color: var(--primary-text-color);
+        flex: 0 0 auto;
+      }
+      .place-pill .pill-initials {
+        font-weight: 700;
+        text-align: center;
+        line-height: 1;
+      }
+      .place-pill.dark,
+      .place-pill.dark .pill-badge {
+        color: #ffffff;
+        background: #1c1c1c;
+      }
     `;
   }
 }

src/configs/EntityConfig.js

@@ -67,6 +67,11 @@ export default class EntityConfig {
   useBaseEntityOnly;
   /** @type {number} */
   positionUpdateThreshold;
+  /**
+   * @type {number} Min map zoom at which a `display: pill` marker shows the
+   * offset callout + leader line; below it the pill centers on the point.
+   */
+  pillCalloutMinZoom;
 
   /** @type {CircleConfig} */
   circleConfig;
@@ -132,6 +137,7 @@ export default class EntityConfig {
 
     this.useBaseEntityOnly = config.use_base_entity_only ?? false;
     this.positionUpdateThreshold = config.position_update_threshold ?? 10;
+    this.pillCalloutMinZoom = config.pill_callout_min_zoom ?? 15;
 
     this.circleConfig = new CircleConfig(config.circle, this.color);
     this.geoJsonConfig = new GeoJsonConfig(config.geojson, this.color);

src/configs/EntityConfig.test.js

@@ -8,6 +8,18 @@ describe("EntityConfig", () => {
     historyEnd: null
   };
 
+  describe("pillCalloutMinZoom", () => {
+    it("defaults to 15", () => {
+      const entityConfig = new EntityConfig({ entity: "device_tracker.mom" }, defaults);
+      expect(entityConfig.pillCalloutMinZoom).toBe(15);
+    });
+
+    it("can be overridden via pill_callout_min_zoom", () => {
+      const entityConfig = new EntityConfig({ entity: "device_tracker.mom", pill_callout_min_zoom: 12 }, defaults);
+      expect(entityConfig.pillCalloutMinZoom).toBe(12);
+    });
+  });
+
   describe("_generateRandomColor", () => {
     it("should generate a random color", () => {
       const entityConfig = new EntityConfig("sensor.random_entity", defaults);