Merge master (#1706 participants-picker ordering) into card/1710

src/Http/Controllers/TicketController.php

@@ -5,6 +5,7 @@ namespace Dashboard\Ticketing\Http\Controllers;
 use App\Models\Setting;
 use App\Models\User;
 use App\Support\PersonChip;
+use App\Support\PersonNames;
 use Dashboard\Ticketing\Models\PriorityLevel;
 use Dashboard\Ticketing\Models\Ticket;
 use Dashboard\Ticketing\Models\TicketAttachment;
@@ -1134,11 +1135,23 @@ class TicketController extends Controller
      *    operator-precedence hole the same shape opened on [central-inventory]
      *    #1594.
      *
-     * `orderBy('name')` is new and is the only visible difference: the old query
+     * AN ORDER AT ALL is new, and it is `PersonNames::orderUsers()` rather than
-     * had no order at all, so ten rows arrived in whatever order the storage
+     * `orderBy('name')`. The old query had no order, so ten rows arrived in
-     * engine happened to return them and the same two letters could list the
+     * whatever sequence the storage engine happened to return them and the same
-     * same people differently twice running. The reference search orders by
+     * two letters could list the same people differently twice running. But the
-     * name, and "a consistent shape" is what this card is for.
+     * column that makes an order CONSISTENT is not automatically the one that
+     * makes it READABLE: `users.name` is the cached "First Last" ("Andrew Fast")
+     * and these rows are chips, which read "Last, First" ("Fast, Andrew"). A
+     * list labelled one way and collated the other is what an operator calls
+     * unsorted — "Toews, Fast, Ivanov, Mwangi, Bergman" is perfectly ordered by
+     * a string the row no longer shows. `PersonNames::orderUsers()` is the
+     * platform's one answer to that (#524), it is what the reference search
+     * (`admin.settings.users.search`) and the sibling conversions use, and it
+     * honours the operator's `name_format` rather than assuming surname-first.
+     *
+     * It also decides WHICH TEN come back, not merely their sequence, so this is
+     * not cosmetic: on a common surname the limit falls on a different set of
+     * people under the two collations.
      */
     public function searchUsers(Request $request, Ticket $ticket)
     {
@@ -1163,7 +1176,7 @@ class TicketController extends Controller
                       ->orWhere('email', 'like', "%{$q}%");
             })
                 ->whereNotIn('id', $excludeIds)
-                ->orderBy('name')
+                ->tap(fn ($query) => PersonNames::orderUsers($query))
                 ->limit(10)
                 ->get(PersonChip::columns())
         ));