@camstack/types 1.2.144 → 1.2.146

package/dist/device/container-primary-child.d.ts

@@ -66,11 +66,34 @@ export interface ContainerChildRef {
      */
     readonly entityId?: string;
     readonly type: string;
+    /**
+     * The child's `DeviceRole`, when the provider stamped one. Ranked BEFORE
+     * `type` — see {@link CONTAINER_CHILD_ROLE_PRIORITY}. Absent is normal and
+     * simply defers to type priority.
+     */
+    readonly role?: string;
+    /** The child's operator-facing name, used only for the namesake tiebreak. */
+    readonly name?: string;
 }
+/**
+ * Roles that say what a container IS, most→least defining. Consulted BEFORE
+ * type priority, because `DeviceType` cannot tell them apart: Home Assistant
+ * maps a door contact, a battery level, a temperature reading and a "last seen"
+ * timestamp all to `DeviceType.Sensor`. Measured on container 4127 — children
+ * `battery-sensor`, `temperature-sensor`, `datetime-sensor`, `contact-sensor`
+ * and a role-less `button` — the type list ranked `button` above `sensor` and
+ * the container stood for its "Identifica" button instead of the door contact
+ * it is named after.
+ *
+ * Only STATE-DEFINING roles belong here. A diagnostic reading (battery,
+ * temperature, humidity, signal, last-seen) is never what a container is, so
+ * they are deliberately absent and fall through to type priority.
+ */
+export declare const CONTAINER_CHILD_ROLE_PRIORITY: readonly string[];
 /**
  * The child a container stands for: the operator's pick when it still exists,
  * else the highest-priority type. `null` for a childless container — a caller
  * must decide what an empty container means for it, rather than being handed a
  * child that is not there.
  */
-export declare function resolveContainerPrimaryChild(children: readonly ContainerChildRef[], overrideEntityId: string | null | undefined): ContainerChildRef | null;
+export declare function resolveContainerPrimaryChild(children: readonly ContainerChildRef[], overrideEntityId: string | null | undefined, containerName?: string): ContainerChildRef | null;

package/dist/index.js

@@ -35551,6 +35551,46 @@ var CONTAINER_CHILD_PRIORITY = [
 	"image",
 	"sensor"
 ];
+/**
+* Roles that say what a container IS, most→least defining. Consulted BEFORE
+* type priority, because `DeviceType` cannot tell them apart: Home Assistant
+* maps a door contact, a battery level, a temperature reading and a "last seen"
+* timestamp all to `DeviceType.Sensor`. Measured on container 4127 — children
+* `battery-sensor`, `temperature-sensor`, `datetime-sensor`, `contact-sensor`
+* and a role-less `button` — the type list ranked `button` above `sensor` and
+* the container stood for its "Identifica" button instead of the door contact
+* it is named after.
+*
+* Only STATE-DEFINING roles belong here. A diagnostic reading (battery,
+* temperature, humidity, signal, last-seen) is never what a container is, so
+* they are deliberately absent and fall through to type priority.
+*/
+var CONTAINER_CHILD_ROLE_PRIORITY = [
+	"contact-sensor",
+	"motion-sensor",
+	"occupancy-sensor",
+	"smoke-sensor",
+	"co-sensor",
+	"gas-sensor",
+	"leak-sensor",
+	"vibration-sensor",
+	"tamper-sensor",
+	"sound-sensor"
+];
+/**
+* NOT in the list, deliberately: `binary-sensor` and `binary-helper`. They are
+* GENERIC — they say "this reports a boolean", not what the container is — and
+* ranking them above type priority is a live regression, not a hypothetical:
+* container 1837 holds a real `lock` (features `['lock-open']`) alongside a
+* child named "Actuator" whose only role is `binary-sensor`, and the generic
+* role beat the lock. A role earns a place here by naming a SUBJECT (a contact,
+* a leak, smoke), never by naming a datatype.
+*/
+function roleRank(role) {
+	if (role === void 0) return CONTAINER_CHILD_ROLE_PRIORITY.length;
+	const i = CONTAINER_CHILD_ROLE_PRIORITY.indexOf(role);
+	return i === -1 ? CONTAINER_CHILD_ROLE_PRIORITY.length : i;
+}
 function rank(type) {
 	const i = CONTAINER_CHILD_PRIORITY.indexOf(type);
 	return i === -1 ? CONTAINER_CHILD_PRIORITY.length : i;
@@ -35561,12 +35601,13 @@ function rank(type) {
 * must decide what an empty container means for it, rather than being handed a
 * child that is not there.
 */
-function resolveContainerPrimaryChild(children, overrideEntityId) {
+function resolveContainerPrimaryChild(children, overrideEntityId, containerName) {
 	if (overrideEntityId !== void 0 && overrideEntityId !== null) {
 		const picked = children.find((c) => c.stableId === overrideEntityId) ?? children.find((c) => c.entityId !== void 0 && c.entityId === overrideEntityId);
 		if (picked !== void 0) return picked;
 	}
-	return [...children].toSorted((a, b) => rank(a.type) - rank(b.type))[0] ?? null;
+	const namesake = (c) => containerName !== void 0 && containerName.length > 0 && c.name !== void 0 && c.name.toLowerCase() === containerName.toLowerCase() ? 0 : 1;
+	return [...children].toSorted((a, b) => roleRank(a.role) - roleRank(b.role) || namesake(a) - namesake(b) || rank(a.type) - rank(b.type))[0] ?? null;
 }
 //#endregion
 //#region src/device/accessory.ts

package/dist/index.mjs

@@ -35543,6 +35543,46 @@ var CONTAINER_CHILD_PRIORITY = [
 	"image",
 	"sensor"
 ];
+/**
+* Roles that say what a container IS, most→least defining. Consulted BEFORE
+* type priority, because `DeviceType` cannot tell them apart: Home Assistant
+* maps a door contact, a battery level, a temperature reading and a "last seen"
+* timestamp all to `DeviceType.Sensor`. Measured on container 4127 — children
+* `battery-sensor`, `temperature-sensor`, `datetime-sensor`, `contact-sensor`
+* and a role-less `button` — the type list ranked `button` above `sensor` and
+* the container stood for its "Identifica" button instead of the door contact
+* it is named after.
+*
+* Only STATE-DEFINING roles belong here. A diagnostic reading (battery,
+* temperature, humidity, signal, last-seen) is never what a container is, so
+* they are deliberately absent and fall through to type priority.
+*/
+var CONTAINER_CHILD_ROLE_PRIORITY = [
+	"contact-sensor",
+	"motion-sensor",
+	"occupancy-sensor",
+	"smoke-sensor",
+	"co-sensor",
+	"gas-sensor",
+	"leak-sensor",
+	"vibration-sensor",
+	"tamper-sensor",
+	"sound-sensor"
+];
+/**
+* NOT in the list, deliberately: `binary-sensor` and `binary-helper`. They are
+* GENERIC — they say "this reports a boolean", not what the container is — and
+* ranking them above type priority is a live regression, not a hypothetical:
+* container 1837 holds a real `lock` (features `['lock-open']`) alongside a
+* child named "Actuator" whose only role is `binary-sensor`, and the generic
+* role beat the lock. A role earns a place here by naming a SUBJECT (a contact,
+* a leak, smoke), never by naming a datatype.
+*/
+function roleRank(role) {
+	if (role === void 0) return CONTAINER_CHILD_ROLE_PRIORITY.length;
+	const i = CONTAINER_CHILD_ROLE_PRIORITY.indexOf(role);
+	return i === -1 ? CONTAINER_CHILD_ROLE_PRIORITY.length : i;
+}
 function rank(type) {
 	const i = CONTAINER_CHILD_PRIORITY.indexOf(type);
 	return i === -1 ? CONTAINER_CHILD_PRIORITY.length : i;
@@ -35553,12 +35593,13 @@ function rank(type) {
 * must decide what an empty container means for it, rather than being handed a
 * child that is not there.
 */
-function resolveContainerPrimaryChild(children, overrideEntityId) {
+function resolveContainerPrimaryChild(children, overrideEntityId, containerName) {
 	if (overrideEntityId !== void 0 && overrideEntityId !== null) {
 		const picked = children.find((c) => c.stableId === overrideEntityId) ?? children.find((c) => c.entityId !== void 0 && c.entityId === overrideEntityId);
 		if (picked !== void 0) return picked;
 	}
-	return [...children].toSorted((a, b) => rank(a.type) - rank(b.type))[0] ?? null;
+	const namesake = (c) => containerName !== void 0 && containerName.length > 0 && c.name !== void 0 && c.name.toLowerCase() === containerName.toLowerCase() ? 0 : 1;
+	return [...children].toSorted((a, b) => roleRank(a.role) - roleRank(b.role) || namesake(a) - namesake(b) || rank(a.type) - rank(b.type))[0] ?? null;
 }
 //#endregion
 //#region src/device/accessory.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.144",
+  "version": "1.2.146",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",