From 77ea9b3da7b69f9fda91124a0f57e96ec82e55b6 Mon Sep 17 00:00:00 2001
From: Andras Bacsai <5845193+andrasbacsai@users.noreply.github.com>
Date: Thu, 1 Oct 2026 14:47:49 +0200
Subject: [PATCH] feat(server): describe server role options in listbox
 dropdown

Add optional per-option description support to the listbox component,
rendered as muted text below the option label.

Use it on the server role selector (new server and server settings) to
explain each role, and note that GitHub Actions runners require the
"Builds only" role in helper texts and the runners empty state.
---
 resources/views/components/forms/listbox.blade.php | 14 +++++++++++---
 .../views/livewire/server/github-runners.blade.php |  2 +-
 .../views/livewire/server/new/by-ip.blade.php      |  8 ++++----
 resources/views/livewire/server/show.blade.php     |  8 ++++----
 4 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/resources/views/components/forms/listbox.blade.php b/resources/views/components/forms/listbox.blade.php
index 531a195441..639a776a75 100644
--- a/resources/views/components/forms/listbox.blade.php
+++ b/resources/views/components/forms/listbox.blade.php
@@ -4,7 +4,7 @@
     'label' => null,
     'helper' => null,
     'required' => false,
-    'options' => [], // list of ['value' => ..., 'label' => ..., 'disabled' => bool]
+    'options' => [], // list of ['value' => ..., 'label' => ..., 'description' => ?string, 'disabled' => bool]
     'placeholder' => 'Select…',
     'emptyText' => 'No options available.',
     'live' => false,
@@ -163,7 +163,11 @@
                                 <button type="button" class="listbox-option" role="option"
                                     :class="{ 'listbox-option-disabled': option.disabled }"
                                     :aria-selected="String(option.value) === String(value)" @click="choose(option)">
-                                    <span class="truncate" x-text="option.label"></span>
+                                    <span class="flex min-w-0 flex-col">
+                                        <span class="truncate" x-text="option.label"></span>
+                                        <span x-show="option.description" x-text="option.description"
+                                            class="text-xs whitespace-normal text-neutral-500 dark:text-fg-dim"></span>
+                                    </span>
                                     <svg x-show="String(option.value) === String(value)" xmlns="http://www.w3.org/2000/svg"
                                         fill="none" viewBox="0 0 24 24" stroke-width="2.5" stroke="currentColor"
                                         class="size-3.5 shrink-0">
@@ -198,7 +202,11 @@
                             <button type="button" class="listbox-option" role="option"
                                 :class="{ 'listbox-option-disabled': option.disabled }"
                                 :aria-selected="String(option.value) === String(value)" @click="choose(option)">
-                                <span class="truncate" x-text="option.label"></span>
+                                <span class="flex min-w-0 flex-col">
+                                    <span class="truncate" x-text="option.label"></span>
+                                    <span x-show="option.description" x-text="option.description"
+                                        class="text-xs whitespace-normal text-neutral-500 dark:text-fg-dim"></span>
+                                </span>
                                 <svg x-show="String(option.value) === String(value)" xmlns="http://www.w3.org/2000/svg"
                                     fill="none" viewBox="0 0 24 24" stroke-width="2.5" stroke="currentColor"
                                     class="size-3.5 shrink-0">
diff --git a/resources/views/livewire/server/github-runners.blade.php b/resources/views/livewire/server/github-runners.blade.php
index 7a35ef0e07..b91886484e 100644
--- a/resources/views/livewire/server/github-runners.blade.php
+++ b/resources/views/livewire/server/github-runners.blade.php
@@ -22,7 +22,7 @@
                         </a>
                     </x-slot:actions>
                     <x-empty size="sm" title="This server is not enabled for builds"
-                        description="GitHub Actions runners only run on servers with the Build role. Change the server role in the General settings."
+                        description="GitHub Actions runners only run on servers with the Builds only role. Change the server role in the General settings."
                         icon-name="play-circle" />
                 </x-application.settings-section>
             @elseif ($this->githubApps->isEmpty())
diff --git a/resources/views/livewire/server/new/by-ip.blade.php b/resources/views/livewire/server/new/by-ip.blade.php
index d3110316d3..772ede2ac5 100644
--- a/resources/views/livewire/server/new/by-ip.blade.php
+++ b/resources/views/livewire/server/new/by-ip.blade.php
@@ -84,11 +84,11 @@
                         <x-forms.input type="number" id="port" label="Port" required />
                     </div>
                     <x-forms.listbox id="server_role"
-                        helper="Choose whether this server runs deployments, application builds, or both."
+                        helper="Choose whether this server runs deployments, application builds, or both. GitHub Actions runners need the Builds only role."
                         label="Server role" :options="[
-                            ['value' => 'deployment', 'label' => 'Deployments only'],
-                            ['value' => 'build', 'label' => 'Builds only'],
-                            ['value' => 'both', 'label' => 'Deployments and builds'],
+                            ['value' => 'deployment', 'label' => 'Deployments only', 'description' => 'Runs your resources. Images are built on a build server.'],
+                            ['value' => 'build', 'label' => 'Builds only', 'description' => 'Builds images for other servers. Required for GitHub Actions runners.'],
+                            ['value' => 'both', 'label' => 'Deployments and builds', 'description' => 'Builds and runs your resources on this server.'],
                         ]" />
                 </x-forms.collapsible>
             </x-application.settings-section>
diff --git a/resources/views/livewire/server/show.blade.php b/resources/views/livewire/server/show.blade.php
index 8f4bdea7d5..ff159bdf1a 100644
--- a/resources/views/livewire/server/show.blade.php
+++ b/resources/views/livewire/server/show.blade.php
@@ -238,11 +238,11 @@
                             <div class="mt-4 border-t border-neutral-200 pt-4 dark:border-white/[0.08]">
                                 <x-forms.listbox canGate="update" :canResource="$server" id="serverRole"
                                     label="Server role" onChange="requestServerRoleChange"
-                                    helper="Builds can use large amounts of CPU and memory. Deployments on the same server can become slow or unreachable during a build."
+                                    helper="Builds can use large amounts of CPU and memory. Deployments on the same server can become slow or unreachable during a build. GitHub Actions runners need the Builds only role."
                                     :disabled="$isValidating" :options="[
-                                        ['value' => 'deployment', 'label' => 'Deployments only'],
-                                        ['value' => 'build', 'label' => 'Builds only'],
-                                        ['value' => 'both', 'label' => 'Deployments and builds'],
+                                        ['value' => 'deployment', 'label' => 'Deployments only', 'description' => 'Runs your resources. Images are built on a build server.'],
+                                        ['value' => 'build', 'label' => 'Builds only', 'description' => 'Builds images for other servers. Required for GitHub Actions runners.'],
+                                        ['value' => 'both', 'label' => 'Deployments and builds', 'description' => 'Builds and runs your resources on this server.'],
                                     ]" />
                             </div>
                         @endif