Fix sorting logic of RegistryFilter

- Extract value comparison and priority logic into dedicated methods.
  This enhances readability and reduces cyclomatic complexity.
- Fix sorting instability where mixed types (e.g., null vs string)
  caused inconsistent ties.
  This prevents JavaScript's unreliable `<` and `>` comparisons from
  returning a 0 for different types.
- Implement natural numeric sorting for strings.
  (e.g., "Item 2" before "Item 10").
  This ensures digits within strings are treated as numerical values
  instead of ASCII characters.
- Optimize performance with early-exit identity checks (a === b).
  This allows the loop to immediately move to the next property without
  redundant processing.
- Add documentation to clarify how the `order` property affects the
  sorting of areas and domains in views.
  This helps users understand how to prioritize their most-used items
  effectively.

Author: DigiLive

docs/options/area-options.md

@@ -64,6 +64,18 @@ strategy:
 views: []
 ```
 
+## Sorting Areas
+
+The `order` property gives you control over how your areas are arranged in a view.
+
+To make the most of this, it helps to understand how the system prioritizes your list:
+
+- Any area assigned an order value will automatically move to the front/top.<br>
+  This allows you to "pin" your most-used rooms—like the Kitchen or Living Room—so they are always the first things you
+  see.
+- If two areas share the same order value, the system will use their names to determine which one comes first.
+- Any areas without an order property will be placed after/below your prioritized list, sorted alphabetically by name.
+
 ## Undisclosed Area
 
 The strategy has a special area, named `undisclosed`.

docs/options/domain-options.md

@@ -25,6 +25,18 @@ The number of cards per row can be configured with this option.
 
 ---
 
+## Sorting Domains
+
+The `order` property gives you control over how the domains are arranged in a view.
+
+To make the most of this, it helps to understand how the system prioritizes your list:
+
+- Any domain assigned an order value will automatically move to the front/top.<br>
+  This allows you to "pin" your most-used domains—like lights or fans—so they are always the first things you
+  see.
+- If two domains share the same order value, the system will use their names to determine which one comes first.
+- Any domain without an order property will be placed after/below your prioritized list, sorted alphabetically by name.
+
 ## Setting options for all domains
 
 Use `_` as the identifier to set options for all domains.

src/Registry.ts

@@ -181,7 +181,7 @@ class Registry {
       };
     });
 
-    // Remove hidden areas if configured as so and sort them by name.
+    // Remove hidden areas if configured as so and sort them by order first, then by name.
     Registry._areas = new RegistryFilter(Registry._areas).isNotHidden().orderBy(['order', 'name'], 'asc').toList();
 
     // Sort views and domains by order first and then by title.

src/utilities/RegistryFilter.ts

@@ -5,14 +5,15 @@ import { DeviceRegistryEntry } from '../types/homeassistant/data/device_registry
 import { EntityCategory, EntityRegistryEntry } from '../types/homeassistant/data/entity_registry';
 import { RegistryEntry, StrategyConfig } from '../types/strategy/strategy-generics';
 import { logMessage, lvlWarn } from './debug';
+import { compareValues, getSortPriority } from './auxiliaries';
 
 /**
  * A class for filtering and sorting arrays of Home Assistant's registry entries.
  *
  * Supports chaining for building complex filter queries.
  *
  * @template T The specific type of RegistryEntry being filtered.
- * @template K - A property key of T.
+ * @template K A property name of the specific entry-type.
  */
 class RegistryFilter<T extends RegistryEntry, K extends keyof T = keyof T> {
   private readonly entries: T[];
@@ -329,86 +330,55 @@ class RegistryFilter<T extends RegistryEntry, K extends keyof T = keyof T> {
   }
 
   /**
-   * Sorts the entries based on the specified keys in priority order.
+   * Sorts the entries based on the specified keys in order of priority.
    *
-   * @param {Array<keyof T>} keys - Array of property keys to sort by, in order of priority.
-   * @param {'asc' | 'desc'} [direction='asc'] - Sort direction.
-   * @returns {RegistryFilter<T>} A new RegistryFilter instance with sorted entries.
-   * @template T - The type of registry entry
+   * @param {K[]} propertyNames An array of property names to sort by, in order of priority.
+   * @param {'asc' | 'desc'} [direction='asc'] The sort direction: 'asc' for ascending, 'desc' for descending.
+   *
+   * @returns {RegistryFilter<T>} A new RegistryFilter instance with the entries sorted.
+   * @remarks
+   * - Each property in `propertyNames` is used in order to break ties from the previous property.
+   * - Special values like `null`, `undefined`, `Infinity`, and `-Infinity` are handled via `getSortPriority`.
+   * - If all specified properties are equal between two entries, their order is considered equivalent (`return 0`).
    */
-  orderBy(keys: K[], direction: 'asc' | 'desc' = 'asc'): RegistryFilter<T> {
-    // Helper to get the first defined value from an entry for the given keys.
-    const getValue = (entry: T, keys: K[]): unknown => {
-      for (const key of keys) {
-        const value = entry[key];
-        if (value !== null && value !== undefined) {
-          return value;
-        }
-      }
-      return undefined;
-    };
-
-    // Assign sort priorities for special values.
-    const getSortValue = (value: unknown): [number, unknown] => {
-      switch (value) {
-        case -Infinity:
-          return [0, 0]; // First.
-        case undefined:
-        case null:
-          return [2, 0]; // In between.
-        case Infinity:
-          return [3, 0]; // Last.
-        default:
-          return [1, value]; // Normal value comparison.
-      }
-    };
+  orderBy(propertyNames: K[], direction: 'asc' | 'desc' = 'asc'): RegistryFilter<T> {
+    const sortDirection = direction === 'asc' ? 1 : -1;
 
-    // Create a new array to avoid mutating the original.
+    // Sort the entries by creating a new array to avoid mutating the original.
     const sortedEntries = [...this.entries].sort((a, b) => {
-      const sortDirection = direction === 'asc' ? 1 : -1;
+      for (const name of propertyNames) {
+        const propertyValueA = a[name];
+        const propertyValueB = b[name];
 
-      // Get the first defined value for each entry using the provided keys
-      const valueA = getValue(a, keys);
-      const valueB = getValue(b, keys);
+        // If the values are equal, continue to the next property.
+        if (propertyValueA === propertyValueB) continue;
 
-      // If values are strictly equal, they're in the same position.
-      if (valueA === valueB) {
-        return 0;
-      }
-
-      // Get sort priorities and comparable values
-      const [priorityA, comparableA] = getSortValue(valueA);
-      const [priorityB, comparableB] = getSortValue(valueB);
-
-      // First, compare by priority (handles special values).
-      if (priorityA !== priorityB) {
-        return (priorityA - priorityB) * sortDirection;
-      }
+        // Determine the sorting priority of the values.
+        const [priorityA, comparableA] = getSortPriority(propertyValueA);
+        const [priorityB, comparableB] = getSortPriority(propertyValueB);
 
-      // For same priority, compare the actual values.
-      // Handle undefined/null cases
-      if (comparableA == null) {
-        return 1;
-      }
+        // Compare priorities first.
+        if (priorityA !== priorityB) {
+          return (priorityA - priorityB) * sortDirection;
+        }
 
-      if (comparableB == null) {
-        return -1;
-      }
+        // For the same priority, compare the values themselves.
+        const result = compareValues(comparableA, comparableB, direction);
+        if (result !== 0) return result;
 
-      // String comparison.
-      if (typeof comparableA === 'string' && typeof comparableB === 'string') {
-        return comparableA.localeCompare(comparableB) * sortDirection;
+        // The values are equal.
       }
 
-      // Numeric/other comparison.
-      return (comparableA < comparableB ? -1 : 1) * sortDirection;
+      // The priorities and the values are equal.
+      return 0;
     });
 
     // Create a new filter with the sorted entries.
     const newFilter = new RegistryFilter(sortedEntries);
 
     // Copy over existing filters.
     newFilter.filters = [...this.filters];
+
     return newFilter;
   }
 

src/utilities/auxiliaries.ts

@@ -36,3 +36,75 @@ export function deepClone<T>(obj: T): T {
     return obj;
   }
 }
+
+/**
+ * Compares two values according to a sort direction.
+ *
+ * Comparison rules:
+ * 1. `null` and `undefined` are ordered first and second respectively.
+ * 2. Strings are compared using locale-aware comparison with numeric sorting.
+ * 3. Numbers and booleans are compared naturally.
+ * 4. Any other types are considered equal (i.e., do not affect sort order).
+ *
+ * Returns:
+ * - A negative number if `a` should come **before** `b` in the specified `direction`.
+ * - A positive number if `a` should come **after** `b` in the specified `direction`.
+ * - `0` if `a` and `b` are considered equal for sorting.
+ *
+ * This implementation ensures a deterministic and stable sort for `Array.prototype.sort`.
+ *
+ * @param {unknown} a The first value.
+ * @param {unknown} b The second value.
+ * @param {'asc' | 'desc'} [direction='asc'] The sort direction.
+ *
+ * @returns {number} The comparison result.
+ */
+export function compareValues(a: unknown, b: unknown, direction: 'asc' | 'desc' = 'asc'): number {
+  // Values are equal.
+  if (a === b) return 0;
+
+  const sortDirection = direction === 'asc' ? 1 : -1;
+
+  // Handle null / undefined explicitly.
+  if (a == null || b == null) {
+    return (a == null ? -1 : 1) * sortDirection;
+  }
+
+  // Strings.
+  if (typeof a === 'string' && typeof b === 'string') {
+    return a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' }) * sortDirection;
+  }
+
+  // Numbers / booleans.
+  const isNumeric = (val: unknown) => typeof val === 'number' || typeof val === 'boolean';
+
+  if (isNumeric(a) && isNumeric(b)) {
+    return (+a - +b) * sortDirection;
+  }
+
+  // All other types: treat as equal.
+  return 0;
+}
+
+/**
+ * Determines a sorting priority for a value.
+ *
+ * A helper function that prioritizes an object's property value for sorting purposes.
+ *
+ * Priority levels for the evaluated value:
+ *   0. `-Infinity` (force to top)
+ *   1. standard values (string, number, boolean).
+ *   2. `null` or `undefined` (force to bottom).
+ *   3. `+Infinity` (absolute bottom).
+ *
+ * @template V The type of the value.
+ * @param {V | number | string} value The value to evaluate.
+ * @returns {[number, V | number | string]} Tuple of [priority, comparable value].
+ */
+export function getSortPriority<V>(value: V | number | string): [number, V | number | string] {
+  if (value === -Infinity) return [0, 0];
+  if (value == null) return [2, 0];
+  if (value === Infinity) return [3, 0];
+
+  return [1, value];
+}