feat(whatsapp): group-by control for the conversation list

Driver numbers are reused across services, so add a user-selectable "Group
by" pivot over the per-phone threads (computed client-side from fields the
list API already returns — driver_id, context_service_code, wa_contact_name):

- Recent (default): flat, most-recently-active first.
- Service: bucketed under the trip/service each thread is tied to.
- Driver: bucketed by driver.

Grouping is a view only — conversations stay one-per-number, so inbound
routing is unambiguous. Refactors the row into ConversationRow reused by all
views; en/es strings added. Slice 3 of #852.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GAzRnBWEgiTESmwzRNLMzu

Author: korutx

turbo-repo/apps/app/src/features/whatsapp-inbox/components/conversation-list.tsx

@@ -5,25 +5,38 @@ import type { I18nRecord } from "@/features/i18n/i18n.service.types";
 import { tr } from "@/features/i18n/tr.service";
 import type { Conversation } from "../conversation.types";
 import { conversationName, formatListTime } from "../format";
+import { groupConversations, type GroupBy } from "../grouping";
 
 interface ConversationListProps {
   readonly conversations: Conversation[];
   readonly isLoading: boolean;
   readonly selectedId: string | null;
   readonly onSelect: (id: string) => void;
+  readonly groupBy: GroupBy;
+  readonly onGroupByChange: (groupBy: GroupBy) => void;
   readonly dict: I18nRecord;
   readonly locale: string;
 }
 
+const GROUP_OPTIONS: readonly GroupBy[] = ["recent", "service", "driver"];
+const GROUP_LABEL_KEY: Record<GroupBy, string> = {
+  recent: "groupByRecent",
+  service: "groupByService",
+  driver: "groupByDriver",
+};
+
 /**
  * Left column: one row per conversation (driver name / phone, last-message preview, time, and an
- * unread badge), most-recently-active first. Mirrors the org-switcher list styling.
+ * unread badge), most-recently-active first. A "group by" control pivots the list flat, by service,
+ * or by driver — a view over the per-phone threads, computed client-side.
  */
 export default function ConversationList({
   conversations,
   isLoading,
   selectedId,
   onSelect,
+  groupBy,
+  onGroupByChange,
   dict,
   locale,
 }: ConversationListProps) {
@@ -46,70 +59,113 @@ export default function ConversationList({
     );
   }
 
+  const groups = groupConversations(conversations, groupBy, dict);
+
   return (
     <aside className={`${shell} self-start`}>
-      <div className="px-4 py-3 border-b border-gray-200 dark:border-gray-700">
+      <div className="flex items-center justify-between gap-2 px-4 py-3 border-b border-gray-200 dark:border-gray-700">
         <h2 className="text-sm font-semibold text-gray-900 dark:text-white uppercase tracking-wide">
           {tr("listTitle", dict)}
         </h2>
+        <label className="flex items-center gap-1.5 text-xs text-gray-500 dark:text-gray-400">
+          <span className="sr-only sm:not-sr-only">{tr("groupBy", dict)}</span>
+          <select
+            value={groupBy}
+            onChange={(e) => onGroupByChange(e.target.value as GroupBy)}
+            className="rounded-md border border-gray-200 dark:border-gray-600 bg-white dark:bg-gray-700 py-1 pl-2 pr-6 text-xs text-gray-700 dark:text-gray-200 cursor-pointer"
+            aria-label={tr("groupBy", dict)}
+          >
+            {GROUP_OPTIONS.map((option) => (
+              <option key={option} value={option}>
+                {tr(GROUP_LABEL_KEY[option], dict)}
+              </option>
+            ))}
+          </select>
+        </label>
       </div>
       <ul>
-        {conversations.map((conversation, idx) => {
-          const isActive = conversation.id === selectedId;
-          const isLast = idx === conversations.length - 1;
-          const hasUnread = conversation.unreadCount > 0;
-          return (
-            <li key={conversation.id}>
-              <button
-                type="button"
-                onClick={() => onSelect(conversation.id)}
-                className={`w-full text-left flex items-center gap-3 px-4 h-16 cursor-pointer transition-all duration-300 ${
-                  isActive
-                    ? "bg-blue-50/50 dark:bg-blue-900/20"
-                    : "hover:bg-gray-100 dark:hover:bg-gray-700"
-                } ${isLast ? "" : "border-b border-gray-200 dark:border-gray-700"}`}
-              >
-                <HiUserCircle
-                  className={`h-7 w-7 shrink-0 ${
-                    isActive
-                      ? "text-blue-500 dark:text-blue-400"
-                      : "text-gray-400 dark:text-gray-500"
-                  }`}
+        {groups.map((group) => (
+          <li key={group.key}>
+            {group.label !== null && (
+              <div className="px-4 py-1.5 bg-gray-50 dark:bg-gray-900/40 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400 border-b border-gray-200 dark:border-gray-700">
+                {group.label}
+              </div>
+            )}
+            <ul>
+              {group.items.map((conversation) => (
+                <ConversationRow
+                  key={conversation.id}
+                  conversation={conversation}
+                  isActive={conversation.id === selectedId}
+                  onSelect={onSelect}
+                  dict={dict}
+                  locale={locale}
                 />
-                <span className="min-w-0 flex-1">
-                  <span className="flex items-center justify-between gap-2">
-                    <span
-                      className={`block text-sm truncate ${
-                        isActive
-                          ? "font-semibold text-blue-700 dark:text-blue-300"
-                          : "font-medium text-gray-900 dark:text-white"
-                      }`}
-                    >
-                      {conversationName(conversation)}
-                    </span>
-                    <span className="shrink-0 text-xs text-gray-400 dark:text-gray-500">
-                      {formatListTime(conversation.lastMessageAt, locale)}
-                    </span>
-                  </span>
-                  <span className="flex items-center justify-between gap-2">
-                    <span className="block text-xs text-gray-500 dark:text-gray-400 truncate">
-                      {conversation.lastMessagePreview ?? ""}
-                    </span>
-                    {hasUnread && (
-                      <span
-                        className="shrink-0 inline-flex items-center justify-center min-w-5 h-5 px-1.5 rounded-full bg-green-500 text-white text-xs font-semibold"
-                        aria-label={tr("unread", dict)}
-                      >
-                        {conversation.unreadCount}
-                      </span>
-                    )}
-                  </span>
-                </span>
-              </button>
-            </li>
-          );
-        })}
+              ))}
+            </ul>
+          </li>
+        ))}
       </ul>
     </aside>
   );
 }
+
+function ConversationRow({
+  conversation,
+  isActive,
+  onSelect,
+  dict,
+  locale,
+}: {
+  readonly conversation: Conversation;
+  readonly isActive: boolean;
+  readonly onSelect: (id: string) => void;
+  readonly dict: I18nRecord;
+  readonly locale: string;
+}) {
+  const hasUnread = conversation.unreadCount > 0;
+  return (
+    <button
+      type="button"
+      onClick={() => onSelect(conversation.id)}
+      className={`w-full text-left flex items-center gap-3 px-4 h-16 cursor-pointer transition-all duration-300 border-b border-gray-200 dark:border-gray-700 ${
+        isActive ? "bg-blue-50/50 dark:bg-blue-900/20" : "hover:bg-gray-100 dark:hover:bg-gray-700"
+      }`}
+    >
+      <HiUserCircle
+        className={`h-7 w-7 shrink-0 ${
+          isActive ? "text-blue-500 dark:text-blue-400" : "text-gray-400 dark:text-gray-500"
+        }`}
+      />
+      <span className="min-w-0 flex-1">
+        <span className="flex items-center justify-between gap-2">
+          <span
+            className={`block text-sm truncate ${
+              isActive
+                ? "font-semibold text-blue-700 dark:text-blue-300"
+                : "font-medium text-gray-900 dark:text-white"
+            }`}
+          >
+            {conversationName(conversation)}
+          </span>
+          <span className="shrink-0 text-xs text-gray-400 dark:text-gray-500">
+            {formatListTime(conversation.lastMessageAt, locale)}
+          </span>
+        </span>
+        <span className="flex items-center justify-between gap-2">
+          <span className="block text-xs text-gray-500 dark:text-gray-400 truncate">
+            {conversation.lastMessagePreview ?? ""}
+          </span>
+          {hasUnread && (
+            <span
+              className="shrink-0 inline-flex items-center justify-center min-w-5 h-5 px-1.5 rounded-full bg-green-500 text-white text-xs font-semibold"
+              aria-label={tr("unread", dict)}
+            >
+              {conversation.unreadCount}
+            </span>
+          )}
+        </span>
+      </span>
+    </button>
+  );
+}

turbo-repo/apps/app/src/features/whatsapp-inbox/components/conversations-page-content.tsx

@@ -5,6 +5,7 @@ import { FaWhatsapp } from "react-icons/fa";
 import type { I18nRecord } from "@/features/i18n/i18n.service.types";
 import { tr } from "@/features/i18n/tr.service";
 import { useConversations } from "../use-conversations";
+import type { GroupBy } from "../grouping";
 import ConversationList from "./conversation-list";
 import MessageThread from "./message-thread";
 
@@ -21,6 +22,7 @@ interface ConversationsPageContentProps {
 export default function ConversationsPageContent({ dict, locale }: ConversationsPageContentProps) {
   const { conversations, isLoading, error, refresh } = useConversations();
   const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [groupBy, setGroupBy] = useState<GroupBy>("recent");
 
   const selected = conversations.find((c) => c.id === selectedId) ?? null;
 
@@ -48,6 +50,8 @@ export default function ConversationsPageContent({ dict, locale }: Conversations
           isLoading={isLoading}
           selectedId={selectedId}
           onSelect={setSelectedId}
+          groupBy={groupBy}
+          onGroupByChange={setGroupBy}
           dict={dict}
           locale={locale}
         />

turbo-repo/apps/app/src/features/whatsapp-inbox/grouping.ts

@@ -0,0 +1,63 @@
+import type { I18nRecord } from "@/features/i18n/i18n.service.types";
+import { tr } from "@/features/i18n/tr.service";
+import type { Conversation } from "./conversation.types";
+
+/**
+ * How the conversation list is pivoted. Driver phone numbers are reused across services over time,
+ * so the same thread can be viewed flat (most recent first), bucketed by the trip/service it's
+ * currently tied to, or bucketed by driver. Grouping is a VIEW over the per-phone threads — we never
+ * fork a conversation per trip, so an inbound reply always lands on one place.
+ */
+export type GroupBy = "recent" | "service" | "driver";
+
+export interface ConversationGroup {
+  readonly key: string;
+  /** Section header text; {@code null} renders a flat list with no header (the "recent" view). */
+  readonly label: string | null;
+  readonly items: Conversation[];
+}
+
+/** Most-recently-active first; missing timestamps sort last. ISO strings compare chronologically. */
+function byRecent(a: Conversation | undefined, b: Conversation | undefined): number {
+  return (b?.lastMessageAt ?? "").localeCompare(a?.lastMessageAt ?? "");
+}
+
+export function groupConversations(
+  conversations: Conversation[],
+  groupBy: GroupBy,
+  dict: I18nRecord,
+): ConversationGroup[] {
+  const sorted = [...conversations].sort(byRecent);
+
+  if (groupBy === "recent") {
+    return [{ key: "all", label: null, items: sorted }];
+  }
+
+  const keyOf = (c: Conversation): string =>
+    groupBy === "service"
+      ? (c.contextServiceCode ?? "")
+      : (c.driverId ?? c.waContactName ?? c.phoneE164);
+
+  const buckets = new Map<string, Conversation[]>();
+  for (const conversation of sorted) {
+    const key = keyOf(conversation);
+    const bucket = buckets.get(key);
+    if (bucket) {
+      bucket.push(conversation);
+    } else {
+      buckets.set(key, [conversation]);
+    }
+  }
+
+  const groups: ConversationGroup[] = [];
+  for (const [key, items] of buckets) {
+    const label =
+      groupBy === "service"
+        ? key || tr("noService", dict)
+        : (items[0]?.waContactName ?? items[0]?.phoneE164 ?? tr("noDriver", dict));
+    groups.push({ key: key || "__none__", label, items });
+  }
+
+  // Order groups by their most-recent conversation (items are already recency-sorted).
+  return groups.sort((g1, g2) => byRecent(g1.items[0], g2.items[0]));
+}

turbo-repo/apps/app/src/lang/en.json

@@ -4002,6 +4002,12 @@
     "title": "WhatsApp Conversations",
     "description": "Driver replies and message delivery status for your organization.",
     "listTitle": "Conversations",
+    "groupBy": "Group by",
+    "groupByRecent": "Recent",
+    "groupByService": "Service",
+    "groupByDriver": "Driver",
+    "noService": "No service",
+    "noDriver": "Unknown driver",
     "loading": "Loading conversations…",
     "empty": "No conversations yet.",
     "noSelection": "Select a conversation to view the thread.",

turbo-repo/apps/app/src/lang/es.json

@@ -4002,6 +4002,12 @@
     "title": "Conversaciones de WhatsApp",
     "description": "Respuestas de conductores y estado de entrega de los mensajes de tu organización.",
     "listTitle": "Conversaciones",
+    "groupBy": "Agrupar por",
+    "groupByRecent": "Recientes",
+    "groupByService": "Servicio",
+    "groupByDriver": "Conductor",
+    "noService": "Sin servicio",
+    "noDriver": "Conductor desconocido",
     "loading": "Cargando conversaciones…",
     "empty": "Aún no hay conversaciones.",
     "noSelection": "Selecciona una conversación para ver los mensajes.",