From 546bb6dfb28644b661556f376c670279c5714698 Mon Sep 17 00:00:00 2001
From: Bianca <ianoselbiancaroberta02@gmail.com>
Date: Fri, 28 Aug 2026 22:49:52 +0200
Subject: [PATCH 1/2] Merge commit '4a244e7008e15b76e1e63e846880837a7b0c43ce'

---
 src/components/dashboard-navigation.ts        |   2 +
 .../group-labels/group-label-card.tsx         | 217 ++++++++++++++++++
 .../group-labels/group-label-color-picker.tsx |  43 ++++
 .../group-labels/group-labels-page.tsx        | 167 ++++++++++++++
 .../group-labels/group-labels.constants.ts    |  81 +++++++
 .../group-labels/group-labels.functions.ts    |  48 ++++
 .../group-labels/group-labels.validation.ts   |  24 ++
 src/features/group-labels/types.ts            |  10 +
 src/routeTree.gen.ts                          |  21 ++
 src/routes/dashboard/web/group-labels.tsx     |  15 ++
 10 files changed, 628 insertions(+)
 create mode 100644 src/features/group-labels/group-label-card.tsx
 create mode 100644 src/features/group-labels/group-label-color-picker.tsx
 create mode 100644 src/features/group-labels/group-labels-page.tsx
 create mode 100644 src/features/group-labels/group-labels.constants.ts
 create mode 100644 src/features/group-labels/group-labels.functions.ts
 create mode 100644 src/features/group-labels/group-labels.validation.ts
 create mode 100644 src/features/group-labels/types.ts
 create mode 100644 src/routes/dashboard/web/group-labels.tsx

diff --git a/src/components/dashboard-navigation.ts b/src/components/dashboard-navigation.ts
index 8eb40fa..2a39a61 100644
--- a/src/components/dashboard-navigation.ts
+++ b/src/components/dashboard-navigation.ts
@@ -8,6 +8,7 @@ import {
   type LucideIcon,
   Settings,
   ShieldCheck,
+  Tags,
   Users,
   UsersRound,
 } from "lucide-react"
@@ -63,6 +64,7 @@ export const dashboardNavigation = [
       { title: "Associations", url: "/dashboard/web/associations", icon: Users },
       { title: "Guides", url: "/dashboard/web/guides", icon: BookOpen },
       { title: "FAQs", url: "/dashboard/web/faqs", icon: CircleQuestionMark },
+      { title: "Group labels", url: "/dashboard/web/group-labels", icon: Tags },
     ],
   },
 ] as const satisfies readonly DashboardNavigationCategory[]
diff --git a/src/features/group-labels/group-label-card.tsx b/src/features/group-labels/group-label-card.tsx
new file mode 100644
index 0000000..be96694
--- /dev/null
+++ b/src/features/group-labels/group-label-card.tsx
@@ -0,0 +1,217 @@
+import { CircleDashed, LoaderCircle, Pencil, Save, Trash2, X } from "lucide-react"
+import { useState } from "react"
+
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogMedia,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog"
+import { Badge } from "@/components/ui/badge"
+import { Button } from "@/components/ui/button"
+import { Card, CardAction, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
+import { Input } from "@/components/ui/input"
+import { Textarea } from "@/components/ui/textarea"
+import { cn } from "@/lib/utils"
+
+import { GroupLabelColorPicker } from "./group-label-color-picker"
+import { GROUP_LABEL_DESCRIPTION_MAX, GROUP_LABEL_MAX, getGroupLabelColor } from "./group-labels.constants"
+import type { GroupLabel, GroupLabelFormValues } from "./types"
+
+type GroupLabelCardProps = {
+  groupLabel: GroupLabel
+  draft: boolean
+  initialEditActive: boolean
+  onCancelDraft: () => void
+  onDelete: () => Promise<boolean>
+  onSave: (values: GroupLabelFormValues) => Promise<boolean>
+}
+
+export function GroupLabelCard({
+  groupLabel,
+  draft,
+  initialEditActive,
+  onCancelDraft,
+  onDelete,
+  onSave,
+}: GroupLabelCardProps) {
+  const [label, setLabel] = useState(groupLabel.label)
+  const [editing, setEditing] = useState(initialEditActive)
+  const [color, setColor] = useState(groupLabel.color)
+  const [description, setDescription] = useState(groupLabel.description)
+  const [saving, setSaving] = useState(false)
+  const [deleting, setDeleting] = useState(false)
+  const [deleteOpen, setDeleteOpen] = useState(false)
+  const canSave = Boolean(label.trim())
+
+  function resetFields() {
+    setLabel(groupLabel.label)
+    setColor(groupLabel.color)
+    setDescription(groupLabel.description)
+  }
+
+  function cancelEdit() {
+    if (draft) {
+      onCancelDraft()
+      return
+    }
+    resetFields()
+    setEditing(false)
+  }
+
+  async function save() {
+    if (saving || !canSave) return
+    setSaving(true)
+    try {
+      const saved = await onSave({ label: label.trim(), color, description: description.trim() })
+      if (saved) setEditing(false)
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  async function remove() {
+    setDeleting(true)
+    try {
+      if (await onDelete()) setDeleteOpen(false)
+    } finally {
+      setDeleting(false)
+    }
+  }
+
+  const swatch = getGroupLabelColor(groupLabel.color)
+
+  return (
+    <>
+      <Card
+        className={cn("h-full", draft && "border-dashed border-primary/60 bg-primary/[0.035] ring-1 ring-primary/10")}
+      >
+        <CardHeader
+          className={cn(
+            "grid-cols-[1fr_auto] gap-x-4",
+            editing && "border-b pb-(--card-spacing)",
+            draft && "border-primary/15"
+          )}
+        >
+          <CardTitle className="flex min-w-0 items-start gap-3 text-lg">
+            {editing ? (
+              <div className="min-w-0 flex-1 space-y-2">
+                {draft && (
+                  <Badge variant="outline" className="border-primary/30 bg-primary/10 text-primary">
+                    <CircleDashed data-icon="inline-start" /> Unsaved draft
+                  </Badge>
+                )}
+                <div className="flex items-center gap-2">
+                  <GroupLabelColorPicker value={color} onChange={setColor} />
+                  <Input
+                    aria-label="Label"
+                    value={label}
+                    onChange={(event) => setLabel(event.target.value)}
+                    className="bg-background text-base font-medium"
+                    maxLength={GROUP_LABEL_MAX}
+                    required
+                    autoFocus={draft}
+                  />
+                </div>
+              </div>
+            ) : (
+              <Badge className={cn("h-auto py-1 text-sm", swatch.badge)}>{groupLabel.label}</Badge>
+            )}
+          </CardTitle>
+          <CardAction className="flex items-center gap-1.5">
+            {editing ? (
+              <>
+                <Button
+                  type="button"
+                  size="icon-sm"
+                  disabled={saving || !canSave}
+                  onClick={() => void save()}
+                  aria-label={`Save ${label}`}
+                >
+                  {saving ? <LoaderCircle className="animate-spin-slow" /> : <Save />}
+                </Button>
+                <Button
+                  type="button"
+                  variant="outline"
+                  size="icon-sm"
+                  disabled={saving}
+                  onClick={cancelEdit}
+                  aria-label="Cancel editing"
+                >
+                  <X />
+                </Button>
+              </>
+            ) : (
+              <>
+                <Button
+                  type="button"
+                  variant="outline"
+                  size="icon-sm"
+                  aria-label={`Edit ${groupLabel.label}`}
+                  onClick={() => {
+                    resetFields()
+                    setEditing(true)
+                  }}
+                >
+                  <Pencil />
+                </Button>
+                <Button
+                  type="button"
+                  variant="destructive"
+                  size="icon-sm"
+                  aria-label={`Delete ${groupLabel.label}`}
+                  onClick={() => setDeleteOpen(true)}
+                >
+                  <Trash2 />
+                </Button>
+              </>
+            )}
+          </CardAction>
+        </CardHeader>
+        <CardContent className="flex flex-1 flex-col gap-4">
+          {editing ? (
+            <Textarea
+              aria-label="Description"
+              value={description}
+              onChange={(event) => setDescription(event.target.value)}
+              className="min-h-24 bg-background"
+              maxLength={GROUP_LABEL_DESCRIPTION_MAX}
+              placeholder="What kind of groups does this label apply to?"
+            />
+          ) : (
+            <p className="text-sm leading-6 text-foreground/85">
+              {groupLabel.description || <span className="text-muted-foreground italic">No description</span>}
+            </p>
+          )}
+        </CardContent>
+      </Card>
+
+      <AlertDialog open={deleteOpen} onOpenChange={(open) => !deleting && setDeleteOpen(open)}>
+        <AlertDialogContent size="sm">
+          <AlertDialogHeader>
+            <AlertDialogMedia className="bg-destructive/10 text-destructive dark:bg-destructive/20">
+              <Trash2 />
+            </AlertDialogMedia>
+            <AlertDialogTitle>Delete label</AlertDialogTitle>
+            <AlertDialogDescription>
+              Are you sure you want to delete <strong>{groupLabel.label}</strong>? This action cannot be undone.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={deleting} onClick={() => setDeleteOpen(false)}>
+              Cancel
+            </AlertDialogCancel>
+            <AlertDialogAction variant="destructive" disabled={deleting} onClick={() => void remove()}>
+              {deleting && <LoaderCircle data-icon="inline-start" className="animate-spin-slow" />} Delete
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </>
+  )
+}
diff --git a/src/features/group-labels/group-label-color-picker.tsx b/src/features/group-labels/group-label-color-picker.tsx
new file mode 100644
index 0000000..9896897
--- /dev/null
+++ b/src/features/group-labels/group-label-color-picker.tsx
@@ -0,0 +1,43 @@
+import { Select, SelectContent, SelectGroup, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"
+import { cn } from "@/lib/utils"
+
+import { GROUP_LABEL_COLORS, type GroupLabelColorName, isGroupLabelColorName } from "./group-labels.constants"
+
+export function GroupLabelColorPicker({
+  value,
+  onChange,
+}: {
+  value: GroupLabelColorName
+  onChange: (color: GroupLabelColorName) => void
+}) {
+  return (
+    <Select
+      value={value}
+      onValueChange={(val) => {
+        if (val && isGroupLabelColorName(val)) onChange(val)
+      }}
+    >
+      <SelectTrigger aria-label="Label color" className="w-auto shrink-0 px-2">
+        <SelectValue>
+          <span
+            className={cn("size-3.5 rounded-full", GROUP_LABEL_COLORS.find((color) => color.name === value)?.dot)}
+          />
+        </SelectValue>
+      </SelectTrigger>
+      <SelectContent className="w-auto p-2" align="start">
+        <SelectGroup className="grid grid-cols-5 gap-1 p-1">
+          {GROUP_LABEL_COLORS.map((color) => (
+            <SelectItem
+              key={color.name}
+              value={color.name}
+              title={color.label}
+              className="flex size-8 items-center justify-center rounded-md p-0 pr-0 cursor-pointer hover:bg-accent focus:bg-accent data-selected:bg-accent data-selected:ring-2 data-selected:ring-primary/60 [&>span:last-child]:hidden"
+            >
+              <span className={cn("size-4 rounded-full", color.dot)} />
+            </SelectItem>
+          ))}
+        </SelectGroup>
+      </SelectContent>
+    </Select>
+  )
+}
diff --git a/src/features/group-labels/group-labels-page.tsx b/src/features/group-labels/group-labels-page.tsx
new file mode 100644
index 0000000..2fb9175
--- /dev/null
+++ b/src/features/group-labels/group-labels-page.tsx
@@ -0,0 +1,167 @@
+import { useRouter } from "@tanstack/react-router"
+import { useServerFn } from "@tanstack/react-start"
+import { Plus, Tags } from "lucide-react"
+import { useEffect, useMemo, useRef, useState } from "react"
+import { toast } from "sonner"
+
+import { DataToolbar } from "@/components/data-toolbar"
+import { EmptyState } from "@/components/empty-state"
+import { Button } from "@/components/ui/button"
+import { errorHasCode } from "@/lib/errors"
+
+import { GroupLabelCard } from "./group-label-card"
+import { DEFAULT_GROUP_LABEL_COLOR } from "./group-labels.constants"
+import { createGroupLabel, deleteGroupLabel, editGroupLabel } from "./group-labels.functions"
+import { groupLabelSaveErrorMessage } from "./group-labels.validation"
+import type { GroupLabel, GroupLabelFormValues } from "./types"
+
+export function GroupLabelsPage({ loadedGroupLabels }: { loadedGroupLabels: GroupLabel[] }) {
+  const router = useRouter()
+  const createGroupLabelFn = useServerFn(createGroupLabel)
+  const editGroupLabelFn = useServerFn(editGroupLabel)
+  const deleteGroupLabelFn = useServerFn(deleteGroupLabel)
+  const [groupLabels, setGroupLabels] = useState(loadedGroupLabels)
+  const [query, setQuery] = useState("")
+  const [draftGroupLabelIds, setDraftGroupLabelIds] = useState<Set<number>>(new Set())
+  const draftGroupLabelIdsRef = useRef(draftGroupLabelIds)
+
+  useEffect(() => {
+    setGroupLabels((current) => {
+      const drafts = current.filter((groupLabel) => draftGroupLabelIdsRef.current.has(groupLabel.id))
+      return drafts.length ? [...drafts, ...loadedGroupLabels] : loadedGroupLabels
+    })
+  }, [loadedGroupLabels])
+
+  const filteredGroupLabels = useMemo(() => {
+    const normalized = query.trim().toLocaleLowerCase()
+    if (!normalized) return groupLabels
+    return groupLabels.filter(
+      (groupLabel) =>
+        draftGroupLabelIds.has(groupLabel.id) ||
+        [groupLabel.label, groupLabel.description].some((value) => value.toLocaleLowerCase().includes(normalized))
+    )
+  }, [groupLabels, draftGroupLabelIds, query])
+
+  async function refresh() {
+    try {
+      await router.invalidate({ sync: true })
+    } catch (error) {
+      console.error(error)
+      toast.warning("Your change was saved, but the label list could not be refreshed.")
+    }
+  }
+
+  function removeDraftGroupLabelId(id: number) {
+    const nextDraftIds = new Set(draftGroupLabelIdsRef.current)
+    nextDraftIds.delete(id)
+    draftGroupLabelIdsRef.current = nextDraftIds
+    setDraftGroupLabelIds(nextDraftIds)
+  }
+
+  function addGroupLabel() {
+    const draft: GroupLabel = {
+      id: -Date.now(),
+      label: "New label",
+      color: DEFAULT_GROUP_LABEL_COLOR,
+      description: "",
+    }
+    setGroupLabels((current) => [draft, ...current])
+    const nextDraftIds = new Set(draftGroupLabelIdsRef.current).add(draft.id)
+    draftGroupLabelIdsRef.current = nextDraftIds
+    setDraftGroupLabelIds(nextDraftIds)
+  }
+
+  function cancelDraft(id: number) {
+    setGroupLabels((current) => current.filter((groupLabel) => groupLabel.id !== id))
+    removeDraftGroupLabelId(id)
+  }
+
+  async function saveGroupLabel(id: number, values: GroupLabelFormValues) {
+    const draft = draftGroupLabelIdsRef.current.has(id)
+    try {
+      const saved = draft
+        ? await createGroupLabelFn({ data: values })
+        : await editGroupLabelFn({ data: { id, ...values } })
+      setGroupLabels((current) => current.map((groupLabel) => (groupLabel.id === id ? saved : groupLabel)))
+      if (draft) removeDraftGroupLabelId(id)
+      toast.success(`Label ${draft ? "created" : "updated"}`)
+      void refresh()
+      return true
+    } catch (cause) {
+      console.error(cause)
+      toast.error(groupLabelSaveErrorMessage(cause))
+      return false
+    }
+  }
+
+  async function removeGroupLabel(id: number) {
+    if (draftGroupLabelIdsRef.current.has(id)) {
+      cancelDraft(id)
+      return true
+    }
+
+    try {
+      await deleteGroupLabelFn({ data: { id } })
+      setGroupLabels((current) => current.filter((groupLabel) => groupLabel.id !== id))
+      toast.success("Label deleted")
+      void refresh()
+      return true
+    } catch (cause) {
+      console.error(cause)
+      if (errorHasCode(cause, "NOT_FOUND")) {
+        setGroupLabels((current) => current.filter((groupLabel) => groupLabel.id !== id))
+        toast.success("Label deleted")
+        void refresh()
+        return true
+      }
+      toast.error("The label could not be deleted. Check your permissions and try again.")
+      return false
+    }
+  }
+
+  return (
+    <div className="animate-appear">
+      <DataToolbar
+        eyebrow="Web"
+        title="Group labels"
+        description="Manage the colored labels used to categorize groups on the PoliNetwork website."
+        count={filteredGroupLabels.length}
+        total={groupLabels.length}
+        searchPlaceholder="Search labels…"
+        onSearch={setQuery}
+        action={
+          <Button onClick={addGroupLabel}>
+            <Plus data-icon="inline-start" /> Add label
+          </Button>
+        }
+      />
+
+      {filteredGroupLabels.length ? (
+        <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-3">
+          {filteredGroupLabels.map((groupLabel) => (
+            <GroupLabelCard
+              key={groupLabel.id}
+              groupLabel={groupLabel}
+              draft={draftGroupLabelIds.has(groupLabel.id)}
+              initialEditActive={draftGroupLabelIds.has(groupLabel.id)}
+              onCancelDraft={() => cancelDraft(groupLabel.id)}
+              onDelete={() => removeGroupLabel(groupLabel.id)}
+              onSave={(values) => saveGroupLabel(groupLabel.id, values)}
+            />
+          ))}
+        </div>
+      ) : (
+        <EmptyState
+          icon={Tags}
+          title={groupLabels.length ? "No label matches this search" : "No group labels yet"}
+          text={
+            groupLabels.length
+              ? "Try a different label or description."
+              : "Add the first label used to categorize groups."
+          }
+          action={!groupLabels.length ? <Button onClick={addGroupLabel}>Add first label</Button> : undefined}
+        />
+      )}
+    </div>
+  )
+}
diff --git a/src/features/group-labels/group-labels.constants.ts b/src/features/group-labels/group-labels.constants.ts
new file mode 100644
index 0000000..0474dcf
--- /dev/null
+++ b/src/features/group-labels/group-labels.constants.ts
@@ -0,0 +1,81 @@
+export const GROUP_LABEL_MAX = 60
+export const GROUP_LABEL_DESCRIPTION_MAX = 500
+
+export const GROUP_LABEL_COLORS = [
+  {
+    name: "gray",
+    label: "Gray",
+    dot: "bg-slate-500",
+    badge: "bg-slate-500/10 text-slate-700 dark:bg-slate-400/15 dark:text-slate-300",
+  },
+  {
+    name: "red",
+    label: "Red",
+    dot: "bg-red-500",
+    badge: "bg-red-500/10 text-red-700 dark:bg-red-400/15 dark:text-red-300",
+  },
+  {
+    name: "orange",
+    label: "Orange",
+    dot: "bg-orange-500",
+    badge: "bg-orange-500/10 text-orange-700 dark:bg-orange-400/15 dark:text-orange-300",
+  },
+  {
+    name: "amber",
+    label: "Amber",
+    dot: "bg-amber-500",
+    badge: "bg-amber-500/10 text-amber-700 dark:bg-amber-400/15 dark:text-amber-300",
+  },
+  {
+    name: "green",
+    label: "Green",
+    dot: "bg-green-500",
+    badge: "bg-green-500/10 text-green-700 dark:bg-green-400/15 dark:text-green-300",
+  },
+  {
+    name: "teal",
+    label: "Teal",
+    dot: "bg-teal-500",
+    badge: "bg-teal-500/10 text-teal-700 dark:bg-teal-400/15 dark:text-teal-300",
+  },
+  {
+    name: "blue",
+    label: "Blue",
+    dot: "bg-blue-500",
+    badge: "bg-blue-500/10 text-blue-700 dark:bg-blue-400/15 dark:text-blue-300",
+  },
+  {
+    name: "indigo",
+    label: "Indigo",
+    dot: "bg-indigo-500",
+    badge: "bg-indigo-500/10 text-indigo-700 dark:bg-indigo-400/15 dark:text-indigo-300",
+  },
+  {
+    name: "purple",
+    label: "Purple",
+    dot: "bg-purple-500",
+    badge: "bg-purple-500/10 text-purple-700 dark:bg-purple-400/15 dark:text-purple-300",
+  },
+  {
+    name: "pink",
+    label: "Pink",
+    dot: "bg-pink-500",
+    badge: "bg-pink-500/10 text-pink-700 dark:bg-pink-400/15 dark:text-pink-300",
+  },
+] as const
+
+export type GroupLabelColorName = (typeof GROUP_LABEL_COLORS)[number]["name"]
+
+export const GROUP_LABEL_COLOR_NAMES =
+  // SAFETY: GROUP_LABEL_COLORS is a non-empty literal array, so mapping its names always yields at least one element.
+  GROUP_LABEL_COLORS.map((color) => color.name) as [GroupLabelColorName, ...GroupLabelColorName[]]
+
+export const DEFAULT_GROUP_LABEL_COLOR: GroupLabelColorName = "blue"
+
+export function isGroupLabelColorName(value: string): value is GroupLabelColorName {
+  return GROUP_LABEL_COLORS.some((color) => color.name === value)
+}
+
+export function getGroupLabelColor(name: GroupLabelColorName) {
+  return GROUP_LABEL_COLORS.find((color) => color.name === name) ?? GROUP_LABEL_COLORS[0]
+}
diff --git a/src/features/group-labels/group-labels.functions.ts b/src/features/group-labels/group-labels.functions.ts
new file mode 100644
index 0000000..57cd56b
--- /dev/null
+++ b/src/features/group-labels/group-labels.functions.ts
@@ -0,0 +1,48 @@
+import { createServerFn } from "@tanstack/react-start"
+
+import { adminMiddleware, writeAdminMiddleware } from "@/server/auth.middleware"
+
+import { createGroupLabelInput, editGroupLabelInput, groupLabelIdInput } from "./group-labels.validation"
+import type { GroupLabel } from "./types"
+
+// TODO: replace this seed data once `@polinetwork/backend` exposes a real `web.groupLabels` router.
+// Swap these handlers for `context.backend.web.groupLabels.*` calls (same shape as associations.functions.ts).
+let groupLabels: GroupLabel[] = [
+  { id: 1, label: "Affitti", color: "blue", description: "Room and apartment rental listings." },
+  { id: 2, label: "Mercatino", color: "green", description: "Buying and selling books and course materials." },
+  { id: 3, label: "Eventi", color: "purple", description: "Student-organized events and evenings out." },
+  { id: 4, label: "Hobby", color: "orange", description: "Groups for hobbies and free time." },
+]
+let nextGroupLabelId = groupLabels.length + 1
+
+export const listGroupLabels = createServerFn()
+  .middleware([adminMiddleware])
+  .handler(() => groupLabels)
+
+export const createGroupLabel = createServerFn({ method: "POST" })
+  .middleware([writeAdminMiddleware])
+  .validator(createGroupLabelInput)
+  .handler(({ data }) => {
+    const groupLabel: GroupLabel = { id: nextGroupLabelId++, ...data }
+    groupLabels = [...groupLabels, groupLabel]
+    return groupLabel
+  })
+
+export const editGroupLabel = createServerFn({ method: "POST" })
+  .middleware([writeAdminMiddleware])
+  .validator(editGroupLabelInput)
+  .handler(({ data }) => {
+    if (!groupLabels.some((groupLabel) => groupLabel.id === data.id)) throw new Error("NOT_FOUND")
+    const updated: GroupLabel = { id: data.id, label: data.label, color: data.color, description: data.description }
+    groupLabels = groupLabels.map((groupLabel) => (groupLabel.id === data.id ? updated : groupLabel))
+    return updated
+  })
+
+export const deleteGroupLabel = createServerFn({ method: "POST" })
+  .middleware([writeAdminMiddleware])
+  .validator(groupLabelIdInput)
+  .handler(({ data }) => {
+    if (!groupLabels.some((groupLabel) => groupLabel.id === data.id)) throw new Error("NOT_FOUND")
+    groupLabels = groupLabels.filter((groupLabel) => groupLabel.id !== data.id)
+    return { error: null }
+  })
diff --git a/src/features/group-labels/group-labels.validation.ts b/src/features/group-labels/group-labels.validation.ts
new file mode 100644
index 0000000..ec6990d
--- /dev/null
+++ b/src/features/group-labels/group-labels.validation.ts
@@ -0,0 +1,24 @@
+import { z } from "zod"
+
+import { errorHasCode } from "@/lib/errors"
+
+import { GROUP_LABEL_COLOR_NAMES, GROUP_LABEL_DESCRIPTION_MAX, GROUP_LABEL_MAX } from "./group-labels.constants"
+
+const groupLabelFieldsInput = z.object({
+  label: z.string().trim().min(1).max(GROUP_LABEL_MAX),
+  color: z.enum(GROUP_LABEL_COLOR_NAMES),
+  description: z.string().trim().max(GROUP_LABEL_DESCRIPTION_MAX),
+})
+
+export const createGroupLabelInput = groupLabelFieldsInput
+export const editGroupLabelInput = groupLabelFieldsInput.extend({ id: z.number().int().positive() })
+export const groupLabelIdInput = z.object({ id: z.number().int().positive() })
+
+export function groupLabelSaveErrorMessage(cause: unknown) {
+  if (errorHasCode(cause, "NOT_FOUND")) return "This label no longer exists."
+  if (errorHasCode(cause, "INVALID_LABEL")) return `Enter a label no longer than ${GROUP_LABEL_MAX} characters.`
+  if (errorHasCode(cause, "INVALID_DESCRIPTION")) {
+    return `Enter a description no longer than ${GROUP_LABEL_DESCRIPTION_MAX} characters.`
+  }
+  return "The label could not be saved. Check your permissions and try again."
+}
diff --git a/src/features/group-labels/types.ts b/src/features/group-labels/types.ts
new file mode 100644
index 0000000..5dc81a9
--- /dev/null
+++ b/src/features/group-labels/types.ts
@@ -0,0 +1,10 @@
+import type { GroupLabelColorName } from "./group-labels.constants"
+
+export type GroupLabel = {
+  id: number
+  label: string
+  color: GroupLabelColorName
+  description: string
+}
+
+export type GroupLabelFormValues = Pick<GroupLabel, "label" | "color" | "description">
diff --git a/src/routeTree.gen.ts b/src/routeTree.gen.ts
index 510c331..3e36c08 100644
--- a/src/routeTree.gen.ts
+++ b/src/routeTree.gen.ts
@@ -18,6 +18,7 @@ import { Route as OnboardingLinkRouteImport } from './routes/onboarding/link'
 import { Route as DashboardAccountRouteImport } from './routes/dashboard/account'
 import { Route as DashboardWebProjectsRouteImport } from './routes/dashboard/web/projects'
 import { Route as DashboardWebGuidesRouteImport } from './routes/dashboard/web/guides'
+import { Route as DashboardWebGroupLabelsRouteImport } from './routes/dashboard/web/group-labels'
 import { Route as DashboardWebFaqsRouteImport } from './routes/dashboard/web/faqs'
 import { Route as DashboardWebAssociationsRouteImport } from './routes/dashboard/web/associations'
 import { Route as DashboardTelegramGroupsRouteImport } from './routes/dashboard/telegram/groups'
@@ -73,6 +74,11 @@ const DashboardWebGuidesRoute = DashboardWebGuidesRouteImport.update({
   path: '/web/guides',
   getParentRoute: () => DashboardRoute,
 } as any)
+const DashboardWebGroupLabelsRoute = DashboardWebGroupLabelsRouteImport.update({
+  id: '/web/group-labels',
+  path: '/web/group-labels',
+  getParentRoute: () => DashboardRoute,
+} as any)
 const DashboardWebFaqsRoute = DashboardWebFaqsRouteImport.update({
   id: '/web/faqs',
   path: '/web/faqs',
@@ -137,6 +143,7 @@ export interface FileRoutesByFullPath {
   '/dashboard/telegram/groups': typeof DashboardTelegramGroupsRoute
   '/dashboard/web/associations': typeof DashboardWebAssociationsRoute
   '/dashboard/web/faqs': typeof DashboardWebFaqsRoute
+  '/dashboard/web/group-labels': typeof DashboardWebGroupLabelsRoute
   '/dashboard/web/guides': typeof DashboardWebGuidesRoute
   '/dashboard/web/projects': typeof DashboardWebProjectsRoute
   '/dashboard/telegram/users/$userId': typeof DashboardTelegramUsersUserIdRoute
@@ -156,6 +163,7 @@ export interface FileRoutesByTo {
   '/dashboard/telegram/groups': typeof DashboardTelegramGroupsRoute
   '/dashboard/web/associations': typeof DashboardWebAssociationsRoute
   '/dashboard/web/faqs': typeof DashboardWebFaqsRoute
+  '/dashboard/web/group-labels': typeof DashboardWebGroupLabelsRoute
   '/dashboard/web/guides': typeof DashboardWebGuidesRoute
   '/dashboard/web/projects': typeof DashboardWebProjectsRoute
   '/dashboard/telegram/users/$userId': typeof DashboardTelegramUsersUserIdRoute
@@ -177,6 +185,7 @@ export interface FileRoutesById {
   '/dashboard/telegram/groups': typeof DashboardTelegramGroupsRoute
   '/dashboard/web/associations': typeof DashboardWebAssociationsRoute
   '/dashboard/web/faqs': typeof DashboardWebFaqsRoute
+  '/dashboard/web/group-labels': typeof DashboardWebGroupLabelsRoute
   '/dashboard/web/guides': typeof DashboardWebGuidesRoute
   '/dashboard/web/projects': typeof DashboardWebProjectsRoute
   '/dashboard/telegram/users/$userId': typeof DashboardTelegramUsersUserIdRoute
@@ -199,6 +208,7 @@ export interface FileRouteTypes {
     | '/dashboard/telegram/groups'
     | '/dashboard/web/associations'
     | '/dashboard/web/faqs'
+    | '/dashboard/web/group-labels'
     | '/dashboard/web/guides'
     | '/dashboard/web/projects'
     | '/dashboard/telegram/users/$userId'
@@ -218,6 +228,7 @@ export interface FileRouteTypes {
     | '/dashboard/telegram/groups'
     | '/dashboard/web/associations'
     | '/dashboard/web/faqs'
+    | '/dashboard/web/group-labels'
     | '/dashboard/web/guides'
     | '/dashboard/web/projects'
     | '/dashboard/telegram/users/$userId'
@@ -238,6 +249,7 @@ export interface FileRouteTypes {
     | '/dashboard/telegram/groups'
     | '/dashboard/web/associations'
     | '/dashboard/web/faqs'
+    | '/dashboard/web/group-labels'
     | '/dashboard/web/guides'
     | '/dashboard/web/projects'
     | '/dashboard/telegram/users/$userId'
@@ -318,6 +330,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof DashboardWebGuidesRouteImport
       parentRoute: typeof DashboardRoute
     }
+    '/dashboard/web/group-labels': {
+      id: '/dashboard/web/group-labels'
+      path: '/web/group-labels'
+      fullPath: '/dashboard/web/group-labels'
+      preLoaderRoute: typeof DashboardWebGroupLabelsRouteImport
+      parentRoute: typeof DashboardRoute
+    }
     '/dashboard/web/faqs': {
       id: '/dashboard/web/faqs'
       path: '/web/faqs'
@@ -393,6 +412,7 @@ interface DashboardRouteChildren {
   DashboardTelegramGroupsRoute: typeof DashboardTelegramGroupsRoute
   DashboardWebAssociationsRoute: typeof DashboardWebAssociationsRoute
   DashboardWebFaqsRoute: typeof DashboardWebFaqsRoute
+  DashboardWebGroupLabelsRoute: typeof DashboardWebGroupLabelsRoute
   DashboardWebGuidesRoute: typeof DashboardWebGuidesRoute
   DashboardWebProjectsRoute: typeof DashboardWebProjectsRoute
   DashboardTelegramUsersUserIdRoute: typeof DashboardTelegramUsersUserIdRoute
@@ -408,6 +428,7 @@ const DashboardRouteChildren: DashboardRouteChildren = {
   DashboardTelegramGroupsRoute: DashboardTelegramGroupsRoute,
   DashboardWebAssociationsRoute: DashboardWebAssociationsRoute,
   DashboardWebFaqsRoute: DashboardWebFaqsRoute,
+  DashboardWebGroupLabelsRoute: DashboardWebGroupLabelsRoute,
   DashboardWebGuidesRoute: DashboardWebGuidesRoute,
   DashboardWebProjectsRoute: DashboardWebProjectsRoute,
   DashboardTelegramUsersUserIdRoute: DashboardTelegramUsersUserIdRoute,
diff --git a/src/routes/dashboard/web/group-labels.tsx b/src/routes/dashboard/web/group-labels.tsx
new file mode 100644
index 0000000..a5c8cbf
--- /dev/null
+++ b/src/routes/dashboard/web/group-labels.tsx
@@ -0,0 +1,15 @@
+import { createFileRoute } from "@tanstack/react-router"
+
+import { DataPageSkeleton } from "@/components/loading-skeleton"
+import { GroupLabelsPage } from "@/features/group-labels/group-labels-page"
+import { listGroupLabels } from "@/features/group-labels/group-labels.functions"
+
+export const Route = createFileRoute("/dashboard/web/group-labels")({
+  loader: () => listGroupLabels(),
+  pendingComponent: () => <DataPageSkeleton columns={3} />,
+  component: GroupLabelsRoute,
+})
+
+function GroupLabelsRoute() {
+  return <GroupLabelsPage loadedGroupLabels={Route.useLoaderData()} />
+}

From e34e4a2156e19cf3141ce418706c5e6b788e691e Mon Sep 17 00:00:00 2001
From: Bianca <ianoselbiancaroberta02@gmail.com>
Date: Sat, 29 Aug 2026 00:33:25 +0200
Subject: [PATCH 2/2] feat(group-labels): enhance group label functionality and
 UI

- Increased maximum length for group labels from 60 to 128 characters.
- Updated group label colors to use hex values instead of names.
- Introduced functions to validate hex color formats and check label equality.
- Refactored group label creation, editing, and deletion to use backend API calls.
- Added a new LabelDot component for displaying label colors.
- Implemented a GroupLabelsDialog for managing group labels in the Telegram groups page.
- Enhanced the TelegramGroupsPage to support filtering by labels and display label badges.
- Updated validation logic for group labels to ensure proper error handling.
- Added new API functions to fetch group labels and their relations.
---
 src/components/ui/combobox.tsx                |  81 ++++-
 .../group-labels/group-label-card.tsx         |  32 +-
 .../group-labels/group-label-color-picker.tsx |  27 +-
 .../group-labels/group-labels-page.tsx        | 134 ++++---
 .../group-labels/group-labels.constants.ts    |  60 ++--
 .../group-labels/group-labels.functions.ts    |  47 ++-
 .../group-labels/group-labels.validation.ts   |  25 +-
 src/features/group-labels/label-dot.tsx       |   8 +
 src/features/group-labels/types.ts            |  11 +-
 src/features/telegram/group-labels-dialog.tsx | 150 ++++++++
 src/features/telegram/groups-page.tsx         | 332 ++++++++++++++++--
 src/features/telegram/groups.functions.ts     |  20 ++
 src/lib/api/types.ts                          |   2 +
 src/routes/dashboard/telegram/groups.tsx      |  21 +-
 14 files changed, 746 insertions(+), 204 deletions(-)
 create mode 100644 src/features/group-labels/label-dot.tsx
 create mode 100644 src/features/telegram/group-labels-dialog.tsx

diff --git a/src/components/ui/combobox.tsx b/src/components/ui/combobox.tsx
index 0c0ca19..d6cdc12 100644
--- a/src/components/ui/combobox.tsx
+++ b/src/components/ui/combobox.tsx
@@ -109,4 +109,83 @@ function ComboboxEmpty({ className, ...props }: ComboboxPrimitive.Empty.Props) {
   )
 }
 
-export { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxList }
+const ComboboxValue = ComboboxPrimitive.Value
+
+function ComboboxChipsGroup({ className, ...props }: ComboboxPrimitive.InputGroup.Props) {
+  return (
+    <ComboboxPrimitive.InputGroup
+      data-slot="combobox-chips-group"
+      className={cn(
+        "flex min-h-8 w-full flex-wrap items-center gap-1 rounded-lg border border-input bg-transparent px-1.5 py-1 transition-colors outline-none focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50 has-disabled:bg-input/50 has-disabled:opacity-50 dark:bg-input/30",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ComboboxChips({ className, ...props }: ComboboxPrimitive.Chips.Props) {
+  return (
+    <ComboboxPrimitive.Chips
+      data-slot="combobox-chips"
+      className={cn("flex w-full flex-wrap items-center gap-1", className)}
+      {...props}
+    />
+  )
+}
+
+function ComboboxChip({ className, ...props }: ComboboxPrimitive.Chip.Props) {
+  return (
+    <ComboboxPrimitive.Chip
+      data-slot="combobox-chip"
+      className={cn(
+        "group/combobox-chip flex h-6 shrink-0 cursor-default items-center gap-1 rounded-md bg-accent py-0 pr-1 pl-2 text-xs font-medium text-accent-foreground outline-hidden data-highlighted:bg-primary data-highlighted:text-primary-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ComboboxChipRemove({ className, ...props }: ComboboxPrimitive.ChipRemove.Props) {
+  return (
+    <ComboboxPrimitive.ChipRemove
+      data-slot="combobox-chip-remove"
+      className={cn(
+        "flex size-4 shrink-0 items-center justify-center rounded-sm text-inherit hover:bg-foreground/10 group-data-highlighted/combobox-chip:hover:bg-primary-foreground/20",
+        className
+      )}
+      {...props}
+    >
+      <XIcon className="pointer-events-none size-3" />
+    </ComboboxPrimitive.ChipRemove>
+  )
+}
+
+function ComboboxChipsInput({ className, ...props }: ComboboxPrimitive.Input.Props) {
+  return (
+    <ComboboxPrimitive.Input
+      data-slot="combobox-chips-input"
+      className={cn(
+        "h-6 min-w-16 flex-1 border-0 bg-transparent p-0 text-sm text-foreground outline-none placeholder:text-muted-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Combobox,
+  ComboboxChip,
+  ComboboxChips,
+  ComboboxChipRemove,
+  ComboboxChipsGroup,
+  ComboboxChipsInput,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxValue,
+}
diff --git a/src/features/group-labels/group-label-card.tsx b/src/features/group-labels/group-label-card.tsx
index be96694..1111db9 100644
--- a/src/features/group-labels/group-label-card.tsx
+++ b/src/features/group-labels/group-label-card.tsx
@@ -43,7 +43,7 @@ export function GroupLabelCard({
   const [label, setLabel] = useState(groupLabel.label)
   const [editing, setEditing] = useState(initialEditActive)
   const [color, setColor] = useState(groupLabel.color)
-  const [description, setDescription] = useState(groupLabel.description)
+  const [description, setDescription] = useState(groupLabel.description ?? "")
   const [saving, setSaving] = useState(false)
   const [deleting, setDeleting] = useState(false)
   const [deleteOpen, setDeleteOpen] = useState(false)
@@ -52,7 +52,7 @@ export function GroupLabelCard({
   function resetFields() {
     setLabel(groupLabel.label)
     setColor(groupLabel.color)
-    setDescription(groupLabel.description)
+    setDescription(groupLabel.description ?? "")
   }
 
   function cancelEdit() {
@@ -108,19 +108,27 @@ export function GroupLabelCard({
                 )}
                 <div className="flex items-center gap-2">
                   <GroupLabelColorPicker value={color} onChange={setColor} />
-                  <Input
-                    aria-label="Label"
-                    value={label}
-                    onChange={(event) => setLabel(event.target.value)}
-                    className="bg-background text-base font-medium"
-                    maxLength={GROUP_LABEL_MAX}
-                    required
-                    autoFocus={draft}
-                  />
+                  {draft ? (
+                    <Input
+                      aria-label="Label"
+                      value={label}
+                      onChange={(event) => setLabel(event.target.value)}
+                      className="bg-background text-base font-medium"
+                      maxLength={GROUP_LABEL_MAX}
+                      required
+                      autoFocus
+                    />
+                  ) : (
+                    <span className="text-base font-medium" title="The label name can't be changed after creation.">
+                      {label}
+                    </span>
+                  )}
                 </div>
               </div>
             ) : (
-              <Badge className={cn("h-auto py-1 text-sm", swatch.badge)}>{groupLabel.label}</Badge>
+              <Badge className={cn("h-auto py-1 text-sm", swatch.badgeClassName)} style={swatch.badgeStyle}>
+                {groupLabel.label}
+              </Badge>
             )}
           </CardTitle>
           <CardAction className="flex items-center gap-1.5">
diff --git a/src/features/group-labels/group-label-color-picker.tsx b/src/features/group-labels/group-label-color-picker.tsx
index 9896897..756a453 100644
--- a/src/features/group-labels/group-label-color-picker.tsx
+++ b/src/features/group-labels/group-label-color-picker.tsx
@@ -1,26 +1,19 @@
 import { Select, SelectContent, SelectGroup, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"
 import { cn } from "@/lib/utils"
 
-import { GROUP_LABEL_COLORS, type GroupLabelColorName, isGroupLabelColorName } from "./group-labels.constants"
+import { getGroupLabelColor, GROUP_LABEL_COLORS } from "./group-labels.constants"
+
+export function GroupLabelColorPicker({ value, onChange }: { value: string; onChange: (color: string) => void }) {
+  const swatch = getGroupLabelColor(value)
 
-export function GroupLabelColorPicker({
-  value,
-  onChange,
-}: {
-  value: GroupLabelColorName
-  onChange: (color: GroupLabelColorName) => void
-}) {
   return (
-    <Select
-      value={value}
-      onValueChange={(val) => {
-        if (val && isGroupLabelColorName(val)) onChange(val)
-      }}
-    >
+    <Select value={value} onValueChange={(val) => val && onChange(val)}>
       <SelectTrigger aria-label="Label color" className="w-auto shrink-0 px-2">
         <SelectValue>
           <span
-            className={cn("size-3.5 rounded-full", GROUP_LABEL_COLORS.find((color) => color.name === value)?.dot)}
+            className={cn("size-3.5 rounded-full", swatch.dotClassName)}
+            style={swatch.dotStyle}
+            title={swatch.label}
           />
         </SelectValue>
       </SelectTrigger>
@@ -28,8 +21,8 @@ export function GroupLabelColorPicker({
         <SelectGroup className="grid grid-cols-5 gap-1 p-1">
           {GROUP_LABEL_COLORS.map((color) => (
             <SelectItem
-              key={color.name}
-              value={color.name}
+              key={color.hex}
+              value={color.hex}
               title={color.label}
               className="flex size-8 items-center justify-center rounded-md p-0 pr-0 cursor-pointer hover:bg-accent focus:bg-accent data-selected:bg-accent data-selected:ring-2 data-selected:ring-primary/60 [&>span:last-child]:hidden"
             >
diff --git a/src/features/group-labels/group-labels-page.tsx b/src/features/group-labels/group-labels-page.tsx
index 2fb9175..fab5e70 100644
--- a/src/features/group-labels/group-labels-page.tsx
+++ b/src/features/group-labels/group-labels-page.tsx
@@ -1,13 +1,12 @@
 import { useRouter } from "@tanstack/react-router"
 import { useServerFn } from "@tanstack/react-start"
 import { Plus, Tags } from "lucide-react"
-import { useEffect, useMemo, useRef, useState } from "react"
+import { useEffect, useMemo, useState } from "react"
 import { toast } from "sonner"
 
 import { DataToolbar } from "@/components/data-toolbar"
 import { EmptyState } from "@/components/empty-state"
 import { Button } from "@/components/ui/button"
-import { errorHasCode } from "@/lib/errors"
 
 import { GroupLabelCard } from "./group-label-card"
 import { DEFAULT_GROUP_LABEL_COLOR } from "./group-labels.constants"
@@ -15,32 +14,39 @@ import { createGroupLabel, deleteGroupLabel, editGroupLabel } from "./group-labe
 import { groupLabelSaveErrorMessage } from "./group-labels.validation"
 import type { GroupLabel, GroupLabelFormValues } from "./types"
 
+type GroupLabelRow = { key: string; groupLabel: GroupLabel; draft: boolean }
+
+function toRows(groupLabels: GroupLabel[]): GroupLabelRow[] {
+  return groupLabels.map((groupLabel) => ({ key: groupLabel.label, groupLabel, draft: false }))
+}
+
 export function GroupLabelsPage({ loadedGroupLabels }: { loadedGroupLabels: GroupLabel[] }) {
   const router = useRouter()
   const createGroupLabelFn = useServerFn(createGroupLabel)
   const editGroupLabelFn = useServerFn(editGroupLabel)
   const deleteGroupLabelFn = useServerFn(deleteGroupLabel)
-  const [groupLabels, setGroupLabels] = useState(loadedGroupLabels)
+  const [rows, setRows] = useState<GroupLabelRow[]>(() => toRows(loadedGroupLabels))
   const [query, setQuery] = useState("")
-  const [draftGroupLabelIds, setDraftGroupLabelIds] = useState<Set<number>>(new Set())
-  const draftGroupLabelIdsRef = useRef(draftGroupLabelIds)
 
   useEffect(() => {
-    setGroupLabels((current) => {
-      const drafts = current.filter((groupLabel) => draftGroupLabelIdsRef.current.has(groupLabel.id))
-      return drafts.length ? [...drafts, ...loadedGroupLabels] : loadedGroupLabels
+    setRows((current) => {
+      const drafts = current.filter((row) => row.draft)
+      const real = toRows(loadedGroupLabels)
+      return drafts.length ? [...drafts, ...real] : real
     })
   }, [loadedGroupLabels])
 
-  const filteredGroupLabels = useMemo(() => {
+  const filteredRows = useMemo(() => {
     const normalized = query.trim().toLocaleLowerCase()
-    if (!normalized) return groupLabels
-    return groupLabels.filter(
-      (groupLabel) =>
-        draftGroupLabelIds.has(groupLabel.id) ||
-        [groupLabel.label, groupLabel.description].some((value) => value.toLocaleLowerCase().includes(normalized))
+    if (!normalized) return rows
+    return rows.filter(
+      (row) =>
+        row.draft ||
+        [row.groupLabel.label, row.groupLabel.description ?? ""].some((value) =>
+          value.toLocaleLowerCase().includes(normalized)
+        )
     )
-  }, [groupLabels, draftGroupLabelIds, query])
+  }, [rows, query])
 
   async function refresh() {
     try {
@@ -51,40 +57,40 @@ export function GroupLabelsPage({ loadedGroupLabels }: { loadedGroupLabels: Grou
     }
   }
 
-  function removeDraftGroupLabelId(id: number) {
-    const nextDraftIds = new Set(draftGroupLabelIdsRef.current)
-    nextDraftIds.delete(id)
-    draftGroupLabelIdsRef.current = nextDraftIds
-    setDraftGroupLabelIds(nextDraftIds)
-  }
-
   function addGroupLabel() {
-    const draft: GroupLabel = {
-      id: -Date.now(),
-      label: "New label",
-      color: DEFAULT_GROUP_LABEL_COLOR,
-      description: "",
+    const draft: GroupLabelRow = {
+      key: `draft-${crypto.randomUUID()}`,
+      draft: true,
+      groupLabel: {
+        label: "",
+        color: DEFAULT_GROUP_LABEL_COLOR,
+        description: "",
+        createdBy: 0,
+        updatedBy: null,
+        createdAt: new Date(),
+        updatedAt: null,
+      },
     }
-    setGroupLabels((current) => [draft, ...current])
-    const nextDraftIds = new Set(draftGroupLabelIdsRef.current).add(draft.id)
-    draftGroupLabelIdsRef.current = nextDraftIds
-    setDraftGroupLabelIds(nextDraftIds)
+    setRows((current) => [draft, ...current])
   }
 
-  function cancelDraft(id: number) {
-    setGroupLabels((current) => current.filter((groupLabel) => groupLabel.id !== id))
-    removeDraftGroupLabelId(id)
+  function cancelDraft(key: string) {
+    setRows((current) => current.filter((row) => row.key !== key))
   }
 
-  async function saveGroupLabel(id: number, values: GroupLabelFormValues) {
-    const draft = draftGroupLabelIdsRef.current.has(id)
+  async function saveGroupLabel(row: GroupLabelRow, values: GroupLabelFormValues) {
     try {
-      const saved = draft
+      const saved = row.draft
         ? await createGroupLabelFn({ data: values })
-        : await editGroupLabelFn({ data: { id, ...values } })
-      setGroupLabels((current) => current.map((groupLabel) => (groupLabel.id === id ? saved : groupLabel)))
-      if (draft) removeDraftGroupLabelId(id)
-      toast.success(`Label ${draft ? "created" : "updated"}`)
+        : await editGroupLabelFn({
+            data: { label: row.groupLabel.label, color: values.color, description: values.description },
+          })
+      setRows((current) =>
+        current.map((current_) =>
+          current_.key === row.key ? { key: saved.label, groupLabel: saved, draft: false } : current_
+        )
+      )
+      toast.success(`Label ${row.draft ? "created" : "updated"}`)
       void refresh()
       return true
     } catch (cause) {
@@ -94,26 +100,20 @@ export function GroupLabelsPage({ loadedGroupLabels }: { loadedGroupLabels: Grou
     }
   }
 
-  async function removeGroupLabel(id: number) {
-    if (draftGroupLabelIdsRef.current.has(id)) {
-      cancelDraft(id)
+  async function removeGroupLabel(row: GroupLabelRow) {
+    if (row.draft) {
+      cancelDraft(row.key)
       return true
     }
 
     try {
-      await deleteGroupLabelFn({ data: { id } })
-      setGroupLabels((current) => current.filter((groupLabel) => groupLabel.id !== id))
+      await deleteGroupLabelFn({ data: { label: row.groupLabel.label } })
+      setRows((current) => current.filter((current_) => current_.key !== row.key))
       toast.success("Label deleted")
       void refresh()
       return true
     } catch (cause) {
       console.error(cause)
-      if (errorHasCode(cause, "NOT_FOUND")) {
-        setGroupLabels((current) => current.filter((groupLabel) => groupLabel.id !== id))
-        toast.success("Label deleted")
-        void refresh()
-        return true
-      }
       toast.error("The label could not be deleted. Check your permissions and try again.")
       return false
     }
@@ -125,8 +125,8 @@ export function GroupLabelsPage({ loadedGroupLabels }: { loadedGroupLabels: Grou
         eyebrow="Web"
         title="Group labels"
         description="Manage the colored labels used to categorize groups on the PoliNetwork website."
-        count={filteredGroupLabels.length}
-        total={groupLabels.length}
+        count={filteredRows.length}
+        total={rows.length}
         searchPlaceholder="Search labels…"
         onSearch={setQuery}
         action={
@@ -136,30 +136,28 @@ export function GroupLabelsPage({ loadedGroupLabels }: { loadedGroupLabels: Grou
         }
       />
 
-      {filteredGroupLabels.length ? (
+      {filteredRows.length ? (
         <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-3">
-          {filteredGroupLabels.map((groupLabel) => (
+          {filteredRows.map((row) => (
             <GroupLabelCard
-              key={groupLabel.id}
-              groupLabel={groupLabel}
-              draft={draftGroupLabelIds.has(groupLabel.id)}
-              initialEditActive={draftGroupLabelIds.has(groupLabel.id)}
-              onCancelDraft={() => cancelDraft(groupLabel.id)}
-              onDelete={() => removeGroupLabel(groupLabel.id)}
-              onSave={(values) => saveGroupLabel(groupLabel.id, values)}
+              key={row.key}
+              groupLabel={row.groupLabel}
+              draft={row.draft}
+              initialEditActive={row.draft}
+              onCancelDraft={() => cancelDraft(row.key)}
+              onDelete={() => removeGroupLabel(row)}
+              onSave={(values) => saveGroupLabel(row, values)}
             />
           ))}
         </div>
       ) : (
         <EmptyState
           icon={Tags}
-          title={groupLabels.length ? "No label matches this search" : "No group labels yet"}
+          title={rows.length ? "No label matches this search" : "No group labels yet"}
           text={
-            groupLabels.length
-              ? "Try a different label or description."
-              : "Add the first label used to categorize groups."
+            rows.length ? "Try a different label or description." : "Add the first label used to categorize groups."
           }
-          action={!groupLabels.length ? <Button onClick={addGroupLabel}>Add first label</Button> : undefined}
+          action={!rows.length ? <Button onClick={addGroupLabel}>Add first label</Button> : undefined}
         />
       )}
     </div>
diff --git a/src/features/group-labels/group-labels.constants.ts b/src/features/group-labels/group-labels.constants.ts
index 0474dcf..6602f0d 100644
--- a/src/features/group-labels/group-labels.constants.ts
+++ b/src/features/group-labels/group-labels.constants.ts
@@ -1,81 +1,101 @@
-export const GROUP_LABEL_MAX = 60
+import type { CSSProperties } from "react"
+
+export const GROUP_LABEL_MAX = 128
 export const GROUP_LABEL_DESCRIPTION_MAX = 500
 
 export const GROUP_LABEL_COLORS = [
   {
-    name: "gray",
+    hex: "#64748b",
     label: "Gray",
     dot: "bg-slate-500",
     badge: "bg-slate-500/10 text-slate-700 dark:bg-slate-400/15 dark:text-slate-300",
   },
   {
-    name: "red",
+    hex: "#ef4444",
     label: "Red",
     dot: "bg-red-500",
     badge: "bg-red-500/10 text-red-700 dark:bg-red-400/15 dark:text-red-300",
   },
   {
-    name: "orange",
+    hex: "#f97316",
     label: "Orange",
     dot: "bg-orange-500",
     badge: "bg-orange-500/10 text-orange-700 dark:bg-orange-400/15 dark:text-orange-300",
   },
   {
-    name: "amber",
+    hex: "#f59e0b",
     label: "Amber",
     dot: "bg-amber-500",
     badge: "bg-amber-500/10 text-amber-700 dark:bg-amber-400/15 dark:text-amber-300",
   },
   {
-    name: "green",
+    hex: "#22c55e",
     label: "Green",
     dot: "bg-green-500",
     badge: "bg-green-500/10 text-green-700 dark:bg-green-400/15 dark:text-green-300",
   },
   {
-    name: "teal",
+    hex: "#14b8a6",
     label: "Teal",
     dot: "bg-teal-500",
     badge: "bg-teal-500/10 text-teal-700 dark:bg-teal-400/15 dark:text-teal-300",
   },
   {
-    name: "blue",
+    hex: "#3b82f6",
     label: "Blue",
     dot: "bg-blue-500",
     badge: "bg-blue-500/10 text-blue-700 dark:bg-blue-400/15 dark:text-blue-300",
   },
   {
-    name: "indigo",
+    hex: "#6366f1",
     label: "Indigo",
     dot: "bg-indigo-500",
     badge: "bg-indigo-500/10 text-indigo-700 dark:bg-indigo-400/15 dark:text-indigo-300",
   },
   {
-    name: "purple",
+    hex: "#a855f7",
     label: "Purple",
     dot: "bg-purple-500",
     badge: "bg-purple-500/10 text-purple-700 dark:bg-purple-400/15 dark:text-purple-300",
   },
   {
-    name: "pink",
+    hex: "#ec4899",
     label: "Pink",
     dot: "bg-pink-500",
     badge: "bg-pink-500/10 text-pink-700 dark:bg-pink-400/15 dark:text-pink-300",
   },
 ] as const
 
-export type GroupLabelColorName = (typeof GROUP_LABEL_COLORS)[number]["name"]
+export const DEFAULT_GROUP_LABEL_COLOR: string = GROUP_LABEL_COLORS[6].hex // Blue
 
-export const GROUP_LABEL_COLOR_NAMES =
-  // SAFETY: GROUP_LABEL_COLORS is a non-empty literal array, so mapping its names always yields at least one element.
-  GROUP_LABEL_COLORS.map((color) => color.name) as [GroupLabelColorName, ...GroupLabelColorName[]]
+export function isGroupLabelHexColor(value: string): boolean {
+  return /^#[0-9A-Fa-f]{6}$/.test(value)
+}
 
-export const DEFAULT_GROUP_LABEL_COLOR: GroupLabelColorName = "blue"
+export function isSameGroupLabel(a: { label: string }, b: { label: string }): boolean {
+  return a.label === b.label
+}
 
-export function isGroupLabelColorName(value: string): value is GroupLabelColorName {
-  return GROUP_LABEL_COLORS.some((color) => color.name === value)
+type GroupLabelSwatch = {
+  hex: string
+  label: string
+  dotClassName: string
+  dotStyle?: CSSProperties
+  badgeClassName: string
+  badgeStyle?: CSSProperties
 }
 
-export function getGroupLabelColor(name: GroupLabelColorName) {
-  return GROUP_LABEL_COLORS.find((color) => color.name === name) ?? GROUP_LABEL_COLORS[0]
+/** Falls back to an outline swatch styled with the raw hex, for colors set outside this curated palette. */
+export function getGroupLabelColor(hex: string): GroupLabelSwatch {
+  const match = GROUP_LABEL_COLORS.find((color) => color.hex.toLowerCase() === hex.toLowerCase())
+  if (match) return { hex: match.hex, label: match.label, dotClassName: match.dot, badgeClassName: match.badge }
+
+  return {
+    hex,
+    label: "Custom",
+    dotClassName: "",
+    dotStyle: { backgroundColor: hex },
+    badgeClassName: "border bg-transparent",
+    badgeStyle: { borderColor: hex, color: hex },
+  }
 }
diff --git a/src/features/group-labels/group-labels.functions.ts b/src/features/group-labels/group-labels.functions.ts
index 57cd56b..2026d92 100644
--- a/src/features/group-labels/group-labels.functions.ts
+++ b/src/features/group-labels/group-labels.functions.ts
@@ -2,47 +2,44 @@ import { createServerFn } from "@tanstack/react-start"
 
 import { adminMiddleware, writeAdminMiddleware } from "@/server/auth.middleware"
 
-import { createGroupLabelInput, editGroupLabelInput, groupLabelIdInput } from "./group-labels.validation"
-import type { GroupLabel } from "./types"
-
-// TODO: replace this seed data once `@polinetwork/backend` exposes a real `web.groupLabels` router.
-// Swap these handlers for `context.backend.web.groupLabels.*` calls (same shape as associations.functions.ts).
-let groupLabels: GroupLabel[] = [
-  { id: 1, label: "Affitti", color: "blue", description: "Room and apartment rental listings." },
-  { id: 2, label: "Mercatino", color: "green", description: "Buying and selling books and course materials." },
-  { id: 3, label: "Eventi", color: "purple", description: "Student-organized events and evenings out." },
-  { id: 4, label: "Hobby", color: "orange", description: "Groups for hobbies and free time." },
-]
-let nextGroupLabelId = groupLabels.length + 1
+import { createGroupLabelInput, editGroupLabelInput, groupLabelIdentifierInput } from "./group-labels.validation"
 
 export const listGroupLabels = createServerFn()
   .middleware([adminMiddleware])
-  .handler(() => groupLabels)
+  .handler(({ context }) => context.backend.tg.groupLabels.getAll.query())
 
 export const createGroupLabel = createServerFn({ method: "POST" })
   .middleware([writeAdminMiddleware])
   .validator(createGroupLabelInput)
-  .handler(({ data }) => {
-    const groupLabel: GroupLabel = { id: nextGroupLabelId++, ...data }
-    groupLabels = [...groupLabels, groupLabel]
-    return groupLabel
+  .handler(async ({ data, context }) => {
+    const [created] = await context.backend.tg.groupLabels.create.mutate({
+      label: data.label,
+      description: data.description,
+      color: data.color,
+      createdBy: context.telegramId,
+    })
+    if (!created) throw new Error("The label could not be created.")
+    return created
   })
 
 export const editGroupLabel = createServerFn({ method: "POST" })
   .middleware([writeAdminMiddleware])
   .validator(editGroupLabelInput)
-  .handler(({ data }) => {
-    if (!groupLabels.some((groupLabel) => groupLabel.id === data.id)) throw new Error("NOT_FOUND")
-    const updated: GroupLabel = { id: data.id, label: data.label, color: data.color, description: data.description }
-    groupLabels = groupLabels.map((groupLabel) => (groupLabel.id === data.id ? updated : groupLabel))
+  .handler(async ({ data, context }) => {
+    const [updated] = await context.backend.tg.groupLabels.modify.mutate({
+      label: data.label,
+      description: data.description,
+      color: data.color,
+      updatedBy: context.telegramId,
+    })
+    if (!updated) throw new Error("NOT_FOUND")
     return updated
   })
 
 export const deleteGroupLabel = createServerFn({ method: "POST" })
   .middleware([writeAdminMiddleware])
-  .validator(groupLabelIdInput)
-  .handler(({ data }) => {
-    if (!groupLabels.some((groupLabel) => groupLabel.id === data.id)) throw new Error("NOT_FOUND")
-    groupLabels = groupLabels.filter((groupLabel) => groupLabel.id !== data.id)
+  .validator(groupLabelIdentifierInput)
+  .handler(async ({ data, context }) => {
+    await context.backend.tg.groupLabels.delete.mutate({ label: data.label })
     return { error: null }
   })
diff --git a/src/features/group-labels/group-labels.validation.ts b/src/features/group-labels/group-labels.validation.ts
index ec6990d..48e5796 100644
--- a/src/features/group-labels/group-labels.validation.ts
+++ b/src/features/group-labels/group-labels.validation.ts
@@ -1,24 +1,23 @@
 import { z } from "zod"
 
-import { errorHasCode } from "@/lib/errors"
+import { errorHasZodField, errorMessage } from "@/lib/errors"
 
-import { GROUP_LABEL_COLOR_NAMES, GROUP_LABEL_DESCRIPTION_MAX, GROUP_LABEL_MAX } from "./group-labels.constants"
+import { GROUP_LABEL_DESCRIPTION_MAX, GROUP_LABEL_MAX } from "./group-labels.constants"
 
-const groupLabelFieldsInput = z.object({
-  label: z.string().trim().min(1).max(GROUP_LABEL_MAX),
-  color: z.enum(GROUP_LABEL_COLOR_NAMES),
-  description: z.string().trim().max(GROUP_LABEL_DESCRIPTION_MAX),
-})
+const label = z.string().trim().min(1).max(GROUP_LABEL_MAX)
+const color = z.string().regex(/^#[0-9A-Fa-f]{6}$/)
+const description = z.string().trim().max(GROUP_LABEL_DESCRIPTION_MAX)
 
-export const createGroupLabelInput = groupLabelFieldsInput
-export const editGroupLabelInput = groupLabelFieldsInput.extend({ id: z.number().int().positive() })
-export const groupLabelIdInput = z.object({ id: z.number().int().positive() })
+export const createGroupLabelInput = z.object({ label, color, description })
+export const editGroupLabelInput = z.object({ label, color, description })
+export const groupLabelIdentifierInput = z.object({ label })
 
 export function groupLabelSaveErrorMessage(cause: unknown) {
-  if (errorHasCode(cause, "NOT_FOUND")) return "This label no longer exists."
-  if (errorHasCode(cause, "INVALID_LABEL")) return `Enter a label no longer than ${GROUP_LABEL_MAX} characters.`
-  if (errorHasCode(cause, "INVALID_DESCRIPTION")) {
+  if (errorHasZodField(cause, "label")) return `Enter a label between 1 and ${GROUP_LABEL_MAX} characters.`
+  if (errorHasZodField(cause, "color")) return "Choose a valid color."
+  if (errorHasZodField(cause, "description")) {
     return `Enter a description no longer than ${GROUP_LABEL_DESCRIPTION_MAX} characters.`
   }
+  if (/duplicate|unique/i.test(errorMessage(cause, ""))) return "A label with this name already exists."
   return "The label could not be saved. Check your permissions and try again."
 }
diff --git a/src/features/group-labels/label-dot.tsx b/src/features/group-labels/label-dot.tsx
new file mode 100644
index 0000000..6a085c6
--- /dev/null
+++ b/src/features/group-labels/label-dot.tsx
@@ -0,0 +1,8 @@
+import { cn } from "@/lib/utils"
+
+import { getGroupLabelColor } from "./group-labels.constants"
+
+export function LabelDot({ color, className }: { color: string; className?: string }) {
+  const swatch = getGroupLabelColor(color)
+  return <span className={cn("size-2 shrink-0 rounded-full", swatch.dotClassName, className)} style={swatch.dotStyle} />
+}
diff --git a/src/features/group-labels/types.ts b/src/features/group-labels/types.ts
index 5dc81a9..2922db6 100644
--- a/src/features/group-labels/types.ts
+++ b/src/features/group-labels/types.ts
@@ -1,10 +1,9 @@
-import type { GroupLabelColorName } from "./group-labels.constants"
+import type { TgGroupLabel } from "@/lib/api/types"
 
-export type GroupLabel = {
-  id: number
+export type GroupLabel = TgGroupLabel
+
+export type GroupLabelFormValues = {
   label: string
-  color: GroupLabelColorName
+  color: string
   description: string
 }
-
-export type GroupLabelFormValues = Pick<GroupLabel, "label" | "color" | "description">
diff --git a/src/features/telegram/group-labels-dialog.tsx b/src/features/telegram/group-labels-dialog.tsx
new file mode 100644
index 0000000..0a6933d
--- /dev/null
+++ b/src/features/telegram/group-labels-dialog.tsx
@@ -0,0 +1,150 @@
+import { useServerFn } from "@tanstack/react-start"
+import { LoaderCircle } from "lucide-react"
+import { useEffect, useState } from "react"
+import { toast } from "sonner"
+
+import { Button } from "@/components/ui/button"
+import {
+  Combobox,
+  ComboboxChip,
+  ComboboxChipRemove,
+  ComboboxChips,
+  ComboboxChipsGroup,
+  ComboboxChipsInput,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxValue,
+} from "@/components/ui/combobox"
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog"
+import { isSameGroupLabel } from "@/features/group-labels/group-labels.constants"
+import { LabelDot } from "@/features/group-labels/label-dot"
+import { tagTelegramGroup, untagTelegramGroup } from "@/features/telegram/groups.functions"
+import type { TgGroup, TgGroupLabel } from "@/lib/api/types"
+import { errorMessage } from "@/lib/errors"
+
+export function GroupLabelsDialog({
+  group,
+  allLabels,
+  currentLabels,
+  onClose,
+  onSaved,
+}: {
+  group: TgGroup | null
+  allLabels: TgGroupLabel[]
+  currentLabels: TgGroupLabel[]
+  onClose: () => void
+  onSaved: () => Promise<void>
+}) {
+  const tagTelegramGroupFn = useServerFn(tagTelegramGroup)
+  const untagTelegramGroupFn = useServerFn(untagTelegramGroup)
+  const [selected, setSelected] = useState<TgGroupLabel[]>(currentLabels)
+  const [pending, setPending] = useState(false)
+  const [error, setError] = useState("")
+  const open = group !== null
+
+  // Resets the working selection only when a different group is opened, not on every relations refresh
+  // (currentLabels is intentionally excluded: it gets a new array identity on every parent render).
+  useEffect(() => {
+    if (group) {
+      setSelected(currentLabels)
+      setError("")
+    }
+  }, [group])
+
+  const added = selected.filter((label) => !currentLabels.some((current) => isSameGroupLabel(current, label)))
+  const removed = currentLabels.filter((label) => !selected.some((next) => isSameGroupLabel(next, label)))
+  const dirty = added.length > 0 || removed.length > 0
+
+  async function save() {
+    if (!group || !dirty || pending) return
+    setPending(true)
+    setError("")
+    try {
+      await Promise.all([
+        ...added.map((label) => tagTelegramGroupFn({ data: { groupId: group.telegramId, label: label.label } })),
+        ...removed.map((label) => untagTelegramGroupFn({ data: { groupId: group.telegramId, label: label.label } })),
+      ])
+      toast.success(`Labels updated for ${group.title}.`)
+      onClose()
+      await onSaved()
+    } catch (cause) {
+      console.error(cause)
+      setError(errorMessage(cause, "The group labels could not be updated. Check your permissions and try again."))
+    } finally {
+      setPending(false)
+    }
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={(nextOpen) => !pending && !nextOpen && onClose()}>
+      <DialogContent className="max-w-lg">
+        <DialogHeader>
+          <DialogTitle>Edit labels</DialogTitle>
+          <DialogDescription>{group ? `Choose the labels that apply to ${group.title}.` : null}</DialogDescription>
+        </DialogHeader>
+        <div>
+          <p className="mb-1.5 text-xs font-medium text-muted-foreground">Labels</p>
+          {allLabels.length ? (
+            <Combobox
+              items={allLabels}
+              multiple
+              value={selected}
+              onValueChange={setSelected}
+              itemToStringLabel={(label) => label.label}
+              isItemEqualToValue={isSameGroupLabel}
+            >
+              <ComboboxChipsGroup>
+                <ComboboxChips>
+                  <ComboboxValue>
+                    {(value: TgGroupLabel[]) =>
+                      value.map((label) => (
+                        <ComboboxChip key={label.label}>
+                          <LabelDot color={label.color} />
+                          {label.label}
+                          <ComboboxChipRemove aria-label={`Remove ${label.label}`} />
+                        </ComboboxChip>
+                      ))
+                    }
+                  </ComboboxValue>
+                  <ComboboxChipsInput placeholder={selected.length ? "" : "Search labels…"} />
+                </ComboboxChips>
+              </ComboboxChipsGroup>
+              <ComboboxContent>
+                <ComboboxEmpty>No matching labels</ComboboxEmpty>
+                <ComboboxList>
+                  {(label: TgGroupLabel) => (
+                    <ComboboxItem key={label.label} value={label} className="gap-2">
+                      <LabelDot color={label.color} />
+                      {label.label}
+                    </ComboboxItem>
+                  )}
+                </ComboboxList>
+              </ComboboxContent>
+            </Combobox>
+          ) : (
+            <p className="text-sm text-muted-foreground">No labels have been created yet.</p>
+          )}
+        </div>
+        {error && <p className="text-sm text-destructive">{error}</p>}
+        <DialogFooter>
+          <Button type="button" variant="outline" disabled={pending} onClick={onClose}>
+            Cancel
+          </Button>
+          <Button type="button" disabled={pending || !dirty} onClick={() => void save()}>
+            {pending && <LoaderCircle data-icon="inline-start" className="animate-spin-slow" />}
+            Save labels
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
diff --git a/src/features/telegram/groups-page.tsx b/src/features/telegram/groups-page.tsx
index d5b3d51..5c05a07 100644
--- a/src/features/telegram/groups-page.tsx
+++ b/src/features/telegram/groups-page.tsx
@@ -10,6 +10,7 @@ import {
   EyeOff,
   LoaderCircle,
   MessageCircleMore,
+  Tag,
 } from "lucide-react"
 import { useMemo, useState } from "react"
 import { toast } from "sonner"
@@ -20,28 +21,81 @@ import { Pagination } from "@/components/pagination"
 import { Alert, AlertDescription } from "@/components/ui/alert"
 import { Badge } from "@/components/ui/badge"
 import { Button } from "@/components/ui/button"
+import {
+  Combobox,
+  ComboboxChip,
+  ComboboxChipRemove,
+  ComboboxChips,
+  ComboboxChipsGroup,
+  ComboboxChipsInput,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxValue,
+} from "@/components/ui/combobox"
+import {
+  Popover,
+  PopoverContent,
+  PopoverDescription,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@/components/ui/popover"
 import { DataTableHead, Table, TableBody, TableCell, TableHeader, TableRow, TableSurface } from "@/components/ui/table"
+import { getGroupLabelColor, isSameGroupLabel } from "@/features/group-labels/group-labels.constants"
+import { LabelDot } from "@/features/group-labels/label-dot"
+import { GroupLabelsDialog } from "@/features/telegram/group-labels-dialog"
 import { setGroupVisibility } from "@/features/telegram/groups.functions"
 import { LeaveGroupDialog } from "@/features/telegram/leave-group-dialog"
-import type { TgGroup } from "@/lib/api/types"
+import type { TgGroup, TgGroupLabel, TgGroupLabelRelation } from "@/lib/api/types"
 import { createAppColumnHelper, type dashboardFeatures, useAppTable } from "@/lib/table"
 import { cn } from "@/lib/utils"
 
 const groupColumnHelper = createAppColumnHelper<TgGroup>()
 
-export function TelegramGroupsPage({ loadedGroups }: { loadedGroups: TgGroup[] }) {
+type GroupsFilter = { text: string; requiredLabels: TgGroupLabel[]; excludedLabels: TgGroupLabel[] }
+const DEFAULT_GROUPS_FILTER: GroupsFilter = { text: "", requiredLabels: [], excludedLabels: [] }
+
+export function TelegramGroupsPage({
+  loadedGroups,
+  loadedGroupLabels,
+  loadedGroupLabelRelations,
+}: {
+  loadedGroups: TgGroup[]
+  loadedGroupLabels: TgGroupLabel[]
+  loadedGroupLabelRelations: TgGroupLabelRelation[]
+}) {
   const router = useRouter()
   const setGroupVisibilityFn = useServerFn(setGroupVisibility)
   const [visibilityOverrides, setVisibilityOverrides] = useState<Record<number, boolean>>({})
   const [updatingId, setUpdatingId] = useState<number | null>(null)
   const [mutationError, setMutationError] = useState("")
   const [refreshError, setRefreshError] = useState("")
+  const [editingGroup, setEditingGroup] = useState<TgGroup | null>(null)
 
   const groups = loadedGroups.map((group) => ({
     ...group,
     hide: visibilityOverrides[group.telegramId] ?? group.hide,
   }))
 
+  const groupLabelsByName = useMemo(
+    () => new Map(loadedGroupLabels.map((label) => [label.label, label])),
+    [loadedGroupLabels]
+  )
+
+  const labelsByGroupId = useMemo(() => {
+    const map = new Map<number, TgGroupLabel[]>()
+    for (const relation of loadedGroupLabelRelations) {
+      const label = groupLabelsByName.get(relation.label)
+      if (!label) continue
+      const existing = map.get(relation.groupId)
+      if (existing) existing.push(label)
+      else map.set(relation.groupId, [label])
+    }
+    return map
+  }, [loadedGroupLabelRelations, groupLabelsByName])
+
   async function toggleVisibility(group: TgGroup) {
     if (updatingId !== null) return
     const hide = !group.hide
@@ -123,6 +177,30 @@ export function TelegramGroupsPage({ loadedGroups }: { loadedGroups: TgGroup[] }
             <span className="text-xs italic text-muted-foreground">Not set</span>
           ),
       }),
+      groupColumnHelper.display({
+        id: "labels",
+        header: "Labels",
+        cell: ({ row }) => {
+          const labels = labelsByGroupId.get(row.original.telegramId)
+          if (!labels?.length) return <span className="text-xs italic text-muted-foreground">No labels</span>
+          return (
+            <div className="flex flex-wrap gap-1">
+              {labels.map((label) => {
+                const swatch = getGroupLabelColor(label.color)
+                return (
+                  <Badge
+                    key={label.label}
+                    className={cn("text-[10px]", swatch.badgeClassName)}
+                    style={swatch.badgeStyle}
+                  >
+                    {label.label}
+                  </Badge>
+                )
+              })}
+            </div>
+          )
+        },
+      }),
       groupColumnHelper.display({
         id: "visibility",
         header: "Visibility",
@@ -131,22 +209,24 @@ export function TelegramGroupsPage({ loadedGroups }: { loadedGroups: TgGroup[] }
           const pending = updatingId === group.telegramId
           const visible = !group.hide
           return (
-            <Button
-              variant="outline"
-              size="sm"
-              className={cn(
-                "gap-1 text-xs",
-                visible ? "border-primary/30 bg-accent text-primary" : "text-muted-foreground"
-              )}
-              disabled={pending}
-              aria-busy={pending}
-              aria-pressed={visible}
-              aria-label={`${group.title} is ${visible ? "visible" : "hidden"}. Change visibility`}
-              onClick={() => void toggleVisibility(group)}
-            >
-              {pending ? <LoaderCircle className="animate-spin-slow" /> : visible ? <Eye /> : <EyeOff />}
-              {visible ? "Visible" : "Hidden"}
-            </Button>
+            <div onClick={(event) => event.stopPropagation()}>
+              <Button
+                variant="outline"
+                size="sm"
+                className={cn(
+                  "gap-1 text-xs",
+                  visible ? "border-primary/30 bg-accent text-primary" : "text-muted-foreground"
+                )}
+                disabled={pending}
+                aria-busy={pending}
+                aria-pressed={visible}
+                aria-label={`${group.title} is ${visible ? "visible" : "hidden"}. Change visibility`}
+                onClick={() => void toggleVisibility(group)}
+              >
+                {pending ? <LoaderCircle className="animate-spin-slow" /> : visible ? <Eye /> : <EyeOff />}
+                {visible ? "Visible" : "Hidden"}
+              </Button>
+            </div>
           )
         },
       }),
@@ -161,6 +241,7 @@ export function TelegramGroupsPage({ loadedGroups }: { loadedGroups: TgGroup[] }
               href={link}
               target="_blank"
               rel="noreferrer"
+              onClick={(event) => event.stopPropagation()}
             >
               <ExternalLink className="size-3" />
               Open invite link
@@ -173,26 +254,54 @@ export function TelegramGroupsPage({ loadedGroups }: { loadedGroups: TgGroup[] }
       groupColumnHelper.display({
         id: "leave",
         header: "",
-        cell: ({ row }) => <LeaveGroupDialog chatId={row.original.telegramId} title={row.original.title} />,
+        cell: ({ row }) => (
+          <div onClick={(event) => event.stopPropagation()}>
+            <LeaveGroupDialog chatId={row.original.telegramId} title={row.original.title} />
+          </div>
+        ),
       }),
     ])
-  }, [updatingId])
+  }, [updatingId, labelsByGroupId])
+
   const table = useAppTable({
     key: "telegram-groups",
     columns,
     data: groups,
-    initialState: { sorting: [{ id: "title", desc: false }], pagination: { pageIndex: 0, pageSize: 20 } },
-    globalFilterFn: (row, _columnId, value) => {
+    initialState: {
+      sorting: [{ id: "title", desc: false }],
+      pagination: { pageIndex: 0, pageSize: 20 },
+      globalFilter: DEFAULT_GROUPS_FILTER,
+    },
+    globalFilterFn: (row, _columnId, value: GroupsFilter | undefined) => {
+      const filter = value ?? DEFAULT_GROUPS_FILTER
       const group = row.original
-      const query = String(value ?? "")
-        .trim()
-        .toLocaleLowerCase()
-        .replace(/^@/, "")
-      return !query || [group.title, group.tag].filter(Boolean).join(" ").toLocaleLowerCase().includes(query)
+      const query = filter.text.trim().toLocaleLowerCase().replace(/^@/, "")
+      const matchesText =
+        !query || [group.title, group.tag].filter(Boolean).join(" ").toLocaleLowerCase().includes(query)
+      if (!matchesText) return false
+
+      const groupLabels = labelsByGroupId.get(group.telegramId) ?? []
+      const matchesRequired = filter.requiredLabels.every((label) => groupLabels.some((gl) => gl.label === label.label))
+      const matchesExcluded = filter.excludedLabels.every(
+        (label) => !groupLabels.some((gl) => gl.label === label.label)
+      )
+      return matchesRequired && matchesExcluded
     },
   })
+  // SAFETY: globalFilter is only ever set via initialState or updateFilter below, both of which always produce a GroupsFilter.
+  const filter: GroupsFilter = (table.state.globalFilter as GroupsFilter | undefined) ?? DEFAULT_GROUPS_FILTER
   const filteredCount = table.getFilteredRowModel().rows.length
-  const hasSearch = Boolean(String(table.state.globalFilter ?? "").trim())
+  const hasSearch = Boolean(filter.text.trim())
+  const activeLabelFilterCount = filter.requiredLabels.length + filter.excludedLabels.length
+  const hasFilters = hasSearch || activeLabelFilterCount > 0
+
+  function updateFilter(patch: Partial<GroupsFilter>) {
+    table.setGlobalFilter((previous: GroupsFilter | undefined) => ({
+      ...(previous ?? DEFAULT_GROUPS_FILTER),
+      ...patch,
+    }))
+    table.setPageIndex(0)
+  }
 
   return (
     <div className="animate-appear">
@@ -203,11 +312,134 @@ export function TelegramGroupsPage({ loadedGroups }: { loadedGroups: TgGroup[] }
         count={filteredCount}
         total={groups.length}
         searchPlaceholder="Search by group name or tag…"
-        onSearch={(value) => {
-          table.setGlobalFilter(value)
-          table.setPageIndex(0)
-        }}
-      />
+        onSearch={(value) => updateFilter({ text: value })}
+      >
+        <Popover>
+          <PopoverTrigger
+            render={
+              <Button variant="outline" size="sm" className="gap-1.5">
+                <Tag className="size-4" />
+                Labels
+                {activeLabelFilterCount > 0 && (
+                  <Badge variant="secondary" className="h-4 min-w-4 justify-center rounded-full px-1 text-[10px]">
+                    {activeLabelFilterCount}
+                  </Badge>
+                )}
+              </Button>
+            }
+          />
+          <PopoverContent align="start" className="w-80">
+            <PopoverHeader>
+              <PopoverTitle>Filter by label</PopoverTitle>
+              <PopoverDescription>Show groups that must, or must not, have specific labels.</PopoverDescription>
+            </PopoverHeader>
+            {loadedGroupLabels.length ? (
+              <>
+                <div>
+                  <p className="mb-1.5 text-xs font-medium text-muted-foreground">Must have</p>
+                  <Combobox
+                    items={loadedGroupLabels.filter(
+                      (label) => !filter.excludedLabels.some((excluded) => isSameGroupLabel(excluded, label))
+                    )}
+                    multiple
+                    value={filter.requiredLabels}
+                    onValueChange={(labels) => updateFilter({ requiredLabels: labels })}
+                    itemToStringLabel={(label) => label.label}
+                    isItemEqualToValue={isSameGroupLabel}
+                  >
+                    <ComboboxChipsGroup>
+                      <ComboboxChips>
+                        <ComboboxValue>
+                          {(value: TgGroupLabel[]) =>
+                            value.map((label) => (
+                              <ComboboxChip key={label.label}>
+                                <LabelDot color={label.color} />
+                                {label.label}
+                                <ComboboxChipRemove aria-label={`Remove ${label.label}`} />
+                              </ComboboxChip>
+                            ))
+                          }
+                        </ComboboxValue>
+                        <ComboboxChipsInput
+                          aria-label="Required labels"
+                          placeholder={filter.requiredLabels.length ? "" : "Search labels…"}
+                        />
+                      </ComboboxChips>
+                    </ComboboxChipsGroup>
+                    <ComboboxContent>
+                      <ComboboxEmpty>No matching labels</ComboboxEmpty>
+                      <ComboboxList>
+                        {(label: TgGroupLabel) => (
+                          <ComboboxItem key={label.label} value={label} className="gap-2">
+                            <LabelDot color={label.color} />
+                            {label.label}
+                          </ComboboxItem>
+                        )}
+                      </ComboboxList>
+                    </ComboboxContent>
+                  </Combobox>
+                </div>
+                <div>
+                  <p className="mb-1.5 text-xs font-medium text-muted-foreground">Must not have</p>
+                  <Combobox
+                    items={loadedGroupLabels.filter(
+                      (label) => !filter.requiredLabels.some((required) => isSameGroupLabel(required, label))
+                    )}
+                    multiple
+                    value={filter.excludedLabels}
+                    onValueChange={(labels) => updateFilter({ excludedLabels: labels })}
+                    itemToStringLabel={(label) => label.label}
+                    isItemEqualToValue={isSameGroupLabel}
+                  >
+                    <ComboboxChipsGroup>
+                      <ComboboxChips>
+                        <ComboboxValue>
+                          {(value: TgGroupLabel[]) =>
+                            value.map((label) => (
+                              <ComboboxChip key={label.label}>
+                                <LabelDot color={label.color} />
+                                {label.label}
+                                <ComboboxChipRemove aria-label={`Remove ${label.label}`} />
+                              </ComboboxChip>
+                            ))
+                          }
+                        </ComboboxValue>
+                        <ComboboxChipsInput
+                          aria-label="Excluded labels"
+                          placeholder={filter.excludedLabels.length ? "" : "Search labels…"}
+                        />
+                      </ComboboxChips>
+                    </ComboboxChipsGroup>
+                    <ComboboxContent>
+                      <ComboboxEmpty>No matching labels</ComboboxEmpty>
+                      <ComboboxList>
+                        {(label: TgGroupLabel) => (
+                          <ComboboxItem key={label.label} value={label} className="gap-2">
+                            <LabelDot color={label.color} />
+                            {label.label}
+                          </ComboboxItem>
+                        )}
+                      </ComboboxList>
+                    </ComboboxContent>
+                  </Combobox>
+                </div>
+                {activeLabelFilterCount > 0 && (
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    className="self-start text-muted-foreground"
+                    onClick={() => updateFilter({ requiredLabels: [], excludedLabels: [] })}
+                  >
+                    Clear label filters
+                  </Button>
+                )}
+              </>
+            ) : (
+              <p className="text-sm text-muted-foreground">No labels have been created yet.</p>
+            )}
+          </PopoverContent>
+        </Popover>
+      </DataToolbar>
       {mutationError && (
         <Alert variant="destructive" className="mb-4">
           <AlertDescription>{mutationError}</AlertDescription>
@@ -244,7 +476,19 @@ export function TelegramGroupsPage({ loadedGroups }: { loadedGroups: TgGroup[] }
               </TableHeader>
               <TableBody>
                 {table.getRowModel().rows.map((row) => (
-                  <TableRow key={row.id}>
+                  <TableRow
+                    key={row.id}
+                    className="cursor-pointer outline-none focus-visible:bg-muted/70 focus-visible:ring-3 focus-visible:ring-inset focus-visible:ring-ring/25"
+                    tabIndex={0}
+                    aria-label={`Edit labels for ${row.original.title}`}
+                    onClick={() => setEditingGroup(row.original)}
+                    onKeyDown={(event) => {
+                      if (event.key === "Enter" || event.key === " ") {
+                        event.preventDefault()
+                        setEditingGroup(row.original)
+                      }
+                    }}
+                  >
                     {row.getAllCells().map((cell) => (
                       <TableCell key={cell.id} className="px-4 py-3.5 text-sm">
                         <table.FlexRender cell={cell} />
@@ -267,12 +511,24 @@ export function TelegramGroupsPage({ loadedGroups }: { loadedGroups: TgGroup[] }
       ) : (
         <EmptyState
           icon={MessageCircleMore}
-          title={hasSearch ? "No groups match this search" : "No Telegram groups yet"}
-          text={
-            hasSearch ? "Clear the search or try a different group name or tag." : "No Telegram groups were returned."
-          }
+          title={hasFilters ? "No groups match this search" : "No Telegram groups yet"}
+          text={hasFilters ? "Clear the search or filters and try again." : "No Telegram groups were returned."}
         />
       )}
+      <GroupLabelsDialog
+        group={editingGroup}
+        allLabels={loadedGroupLabels}
+        currentLabels={editingGroup ? (labelsByGroupId.get(editingGroup.telegramId) ?? []) : []}
+        onClose={() => setEditingGroup(null)}
+        onSaved={async () => {
+          try {
+            await router.invalidate({ sync: true })
+          } catch (error) {
+            console.error(error)
+            toast.warning("The labels were saved, but the group list could not be refreshed.")
+          }
+        }}
+      />
     </div>
   )
 }
diff --git a/src/features/telegram/groups.functions.ts b/src/features/telegram/groups.functions.ts
index c32a6b6..79046a0 100644
--- a/src/features/telegram/groups.functions.ts
+++ b/src/features/telegram/groups.functions.ts
@@ -7,6 +7,14 @@ export const getTelegramGroups = createServerFn()
   .middleware([adminMiddleware])
   .handler(({ context }) => context.backend.tg.groups.getAll.query())
 
+export const getGroupLabels = createServerFn()
+  .middleware([adminMiddleware])
+  .handler(({ context }) => context.backend.tg.groupLabels.getAll.query())
+
+export const getGroupLabelRelations = createServerFn()
+  .middleware([adminMiddleware])
+  .handler(({ context }) => context.backend.tg.groupLabels.getAllRelations.query())
+
 export const setGroupVisibility = createServerFn({ method: "POST" })
   .middleware([writeAdminMiddleware])
   .validator(z.object({ telegramId: z.number().int(), hide: z.boolean() }))
@@ -22,3 +30,15 @@ export const leaveTelegramGroup = createServerFn({ method: "POST" })
   .handler(({ data, context }) =>
     context.backend.tg.groups.leaveChat.mutate({ chatId: data.chatId, performerId: context.telegramId })
   )
+
+const groupLabelTagInput = z.object({ groupId: z.number().int(), label: z.string().min(1).max(128) })
+
+export const tagTelegramGroup = createServerFn({ method: "POST" })
+  .middleware([writeAdminMiddleware])
+  .validator(groupLabelTagInput)
+  .handler(({ data, context }) => context.backend.tg.groupLabels.tagGroup.mutate(data))
+
+export const untagTelegramGroup = createServerFn({ method: "POST" })
+  .middleware([writeAdminMiddleware])
+  .validator(groupLabelTagInput)
+  .handler(({ data, context }) => context.backend.tg.groupLabels.untagGroup.mutate(data))
diff --git a/src/lib/api/types.ts b/src/lib/api/types.ts
index 5769fc2..0af7a75 100644
--- a/src/lib/api/types.ts
+++ b/src/lib/api/types.ts
@@ -8,6 +8,8 @@ export type ApiError = inferRouterError<AppRouter>
 export type TgUser = NonNullable<ApiOutput["tg"]["users"]["get"]["user"]>
 export type TgGrant = NonNullable<ApiOutput["tg"]["grants"]["checkUser"]["grant"]>
 export type TgGroup = ApiOutput["tg"]["groups"]["getAll"][number]
+export type TgGroupLabel = ApiOutput["tg"]["groupLabels"]["getAll"][number]
+export type TgGroupLabelRelation = ApiOutput["tg"]["groupLabels"]["getAllRelations"][number]
 export type TgUserRole = NonNullable<ApiInput["tg"]["permissions"]["addRole"]["role"]>
 
 export type AzureMember = ApiOutput["azure"]["members"]["getAll"][number]
diff --git a/src/routes/dashboard/telegram/groups.tsx b/src/routes/dashboard/telegram/groups.tsx
index 4a70823..4831004 100644
--- a/src/routes/dashboard/telegram/groups.tsx
+++ b/src/routes/dashboard/telegram/groups.tsx
@@ -2,15 +2,28 @@ import { createFileRoute } from "@tanstack/react-router"
 
 import { DataPageSkeleton } from "@/components/loading-skeleton"
 import { TelegramGroupsPage } from "@/features/telegram/groups-page"
-import { getTelegramGroups } from "@/features/telegram/groups.functions"
+import { getGroupLabelRelations, getGroupLabels, getTelegramGroups } from "@/features/telegram/groups.functions"
 
 export const Route = createFileRoute("/dashboard/telegram/groups")({
-  loader: () => getTelegramGroups(),
+  loader: async () => {
+    const [groups, groupLabels, groupLabelRelations] = await Promise.all([
+      getTelegramGroups(),
+      getGroupLabels(),
+      getGroupLabelRelations(),
+    ])
+    return { groups, groupLabels, groupLabelRelations }
+  },
   pendingComponent: () => <DataPageSkeleton columns={5} />,
   component: TelegramGroupsRoute,
 })
 
 function TelegramGroupsRoute() {
-  const groups = Route.useLoaderData()
-  return <TelegramGroupsPage loadedGroups={groups} />
+  const { groups, groupLabels, groupLabelRelations } = Route.useLoaderData()
+  return (
+    <TelegramGroupsPage
+      loadedGroups={groups}
+      loadedGroupLabels={groupLabels}
+      loadedGroupLabelRelations={groupLabelRelations}
+    />
+  )
 }