From 2503524b7a0d3fbce52ec0f27fbe5175b6a5d023 Mon Sep 17 00:00:00 2001
From: Jorge Manrubia <jorge@37signals.com>
Date: Wed, 7 May 2025 17:21:38 +0200
Subject: [PATCH] Implement help menu command to show a help menu with the
 commands

---
 app/assets/stylesheets/terminals.css          |  8 ++++
 .../controllers/terminal_controller.js        | 31 +++++++++++++-
 app/views/commands/_form.html.erb             |  2 +-
 app/views/commands/_help.html.erb             | 42 +++++++++++++++++++
 app/views/commands/_terminal.html.erb         |  1 +
 app/views/commands/index.html.erb             |  2 +
 6 files changed, 84 insertions(+), 2 deletions(-)
 create mode 100644 app/views/commands/_help.html.erb

diff --git a/app/assets/stylesheets/terminals.css b/app/assets/stylesheets/terminals.css
index 7e82d6792..1e2becfaf 100644
--- a/app/assets/stylesheets/terminals.css
+++ b/app/assets/stylesheets/terminals.css
@@ -65,6 +65,14 @@
     }
   }
 
+  .terminal__help {
+    display: none;
+
+    .terminal--showing-help & {
+      display: block;
+    }
+  }
+
   .terminal__item {
     @media (any-hover: hover) {
       &:where(:not(:active):hover),
diff --git a/app/javascript/controllers/terminal_controller.js b/app/javascript/controllers/terminal_controller.js
index a4148623c..09a2eea5a 100644
--- a/app/javascript/controllers/terminal_controller.js
+++ b/app/javascript/controllers/terminal_controller.js
@@ -3,7 +3,7 @@ import { HttpStatus } from "helpers/http_helpers"
 
 export default class extends Controller {
   static targets = [ "input", "form", "confirmation" ]
-  static classes = [ "error", "confirmation" ]
+  static classes = [ "error", "confirmation", "help" ]
 
   // Actions
 
@@ -12,6 +12,23 @@ export default class extends Controller {
   }
 
   executeCommand(event) {
+    if (this.#hasShowHelpMenuCommand) {
+      this.#showHelpMenu()
+      event.preventDefault()
+      event.stopPropagation()
+    } else {
+      this.hideHelpMenu()
+    }
+  }
+
+  hideHelpMenu() {
+    if (this.#isHelpMenuOpened && this.#hasShowHelpMenuCommand) {
+      this.#reset()
+      this.element.classList.remove(this.helpClass)
+    }
+  }
+
+  handleCommandResponse(event) {
     if (event.detail.success) {
       this.#reset()
     } else {
@@ -28,6 +45,18 @@ export default class extends Controller {
     }
   }
 
+  get #hasShowHelpMenuCommand() {
+    return this.inputTarget.value == "/help" || this.inputTarget.value == "/?"
+  }
+
+  #showHelpMenu() {
+    this.element.classList.add(this.helpClass)
+  }
+
+  get #isHelpMenuOpened() {
+    return this.element.classList.contains(this.helpClass)
+  }
+
   async #handleErrorResponse(response) {
     const status = response.status
     const message = await response.text()
diff --git a/app/views/commands/_form.html.erb b/app/views/commands/_form.html.erb
index 5a82423ad..e6fec5b76 100644
--- a/app/views/commands/_form.html.erb
+++ b/app/views/commands/_form.html.erb
@@ -4,7 +4,7 @@
       data: {
         controller: "form",
         terminal_target: "form",
-        action: "turbo:submit-end->terminal#focus keydown.meta+k@document->terminal#focus turbo:submit-end->terminal#executeCommand"
+        action: "turbo:submit-end->terminal#focus keydown.meta+k@document->terminal#focus keydown.enter->terminal#executeCommand keydown.esc->terminal#hideHelpMenu turbo:submit-end->terminal#handleCommandResponse"
       } do %>
   <label class="terminal__label txt-nowrap" for="fizzy_do">Fizzy do &gt;</label>
 
diff --git a/app/views/commands/_help.html.erb b/app/views/commands/_help.html.erb
new file mode 100644
index 000000000..597aef5d9
--- /dev/null
+++ b/app/views/commands/_help.html.erb
@@ -0,0 +1,42 @@
+<section class="terminal__help" aria-labelledby="help-menu-title">
+  <h2 id="help-menu-title">Commands</h2>
+
+  <div>
+    <h3>Navigation</h3>
+    <dl>
+      <dt><code>@username</code></dt>
+      <dd>Navigate to a user's page</dd>
+
+      <dt><code>[card id]</code></dt>
+      <dd>Go to a specific card by its id</dd>
+    </dl>
+  </div>
+
+  <div>
+    <h3>Filtering</h3>
+    <dl>
+      <dt><code>#tag_name</code></dt>
+      <dd>Filter cards by tag</dd>
+
+      <dt><code>[card id 1] [card id 2]...</code></dt>
+      <dd>Filter multiple cards by their IDs</dd>
+
+      <dt><code>search_term</code></dt>
+      <dd>Search for cards containing the term</dd>
+    </dl>
+  </div>
+
+  <div>
+    <h3>Cards</h3>
+    <dl>
+      <dt><code>/assign [username 1] [username 2]...</code></dt>
+      <dd>Assign selected cards to specified user(s)</dd>
+
+      <dt><code>/close [reason]</code></dt>
+      <dd>Close selected cards with an optional reason</dd>
+
+      <dt><code>/tag [tag name]</code></dt>
+      <dd>Add a tag to selected cards</dd>
+    </dl>
+  </div>
+</section>
diff --git a/app/views/commands/_terminal.html.erb b/app/views/commands/_terminal.html.erb
index 31395cb47..ef93d3ed6 100644
--- a/app/views/commands/_terminal.html.erb
+++ b/app/views/commands/_terminal.html.erb
@@ -2,6 +2,7 @@
       controller: "toggle-class terminal navigable-list",
       terminal_error_class: "terminal--error",
       terminal_confirmation_class: "terminal--confirmation",
+      terminal_help_class: "terminal--showing-help",
       toggle_class_toggle_class: "terminal--open",
       action: "keydown->navigable-list#navigate keydown.esc->toggle-class#remove:stop keydown.esc->terminal#focus keydown.esc->navigable-list#selectLast" } do %>
   <%= turbo_frame_tag :recent_commands, src: commands_path, refresh: "morph" %>
diff --git a/app/views/commands/index.html.erb b/app/views/commands/index.html.erb
index 49126efbe..b3369ab85 100644
--- a/app/views/commands/index.html.erb
+++ b/app/views/commands/index.html.erb
@@ -2,4 +2,6 @@
   <ul class="terminal__menu flex-column txt-align-start margin-none margin-block-end unpad" aria-label="Recent commands">
     <%= render partial: "commands/command", collection: @commands %>
   </ul>
+
+  <%= render "commands/help" %>
 <% end %>