From ebd7f64fe3529b992157954381c690ce74a85f01 Mon Sep 17 00:00:00 2001
From: Zhihe Li <zhihe.li@hashicorp.com>
Date: Wed, 20 May 2026 18:29:40 -0400
Subject: [PATCH] =?UTF-8?q?fix:=20=F0=9F=90=9B=20Add=20missing=20code=20bl?=
 =?UTF-8?q?ock=20description=20(#3277)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix: 🐛 Add missing code block description

* feat: 🎸 Add autocomplete on empty lines
---
 addons/core/translations/resources/en-us.yaml          |  3 ++-
 ui/admin/app/components/form/role/edit-grants/index.js |  5 +++++
 ui/admin/app/components/form/role/grants/index.hbs     | 10 +++++++++-
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/addons/core/translations/resources/en-us.yaml b/addons/core/translations/resources/en-us.yaml
index 7e7bc8105..057e50ee5 100644
--- a/addons/core/translations/resources/en-us.yaml
+++ b/addons/core/translations/resources/en-us.yaml
@@ -611,6 +611,7 @@ role:
     title: Grant
     title_plural: Grants
     description: Grants are permissions which allow roles to take actions and access resources.
+    codeblock-description: Select "{editGrantsTitle}" to add or modify grants. Select "{addGrantTemplatesTitle}" to add in templates.
     actions:
       create: New Grant
   grant-templates:
@@ -725,7 +726,7 @@ role:
         invalid-field-for-type: Invalid output field "{field}" for type "{type}"
     editor:
       title: Grant Editor
-      description: Add each new grant string on a different line
+      description: Add each new grant string on a different line. Press Ctrl+Space to get suggestions.
     string-formats:
       title_plural: String formats
       syntax: Syntax
diff --git a/ui/admin/app/components/form/role/edit-grants/index.js b/ui/admin/app/components/form/role/edit-grants/index.js
index 577904350..c78b9429b 100644
--- a/ui/admin/app/components/form/role/edit-grants/index.js
+++ b/ui/admin/app/components/form/role/edit-grants/index.js
@@ -10,6 +10,7 @@ import { tracked } from '@glimmer/tracking';
 import {
   autocompletion,
   completionKeymap,
+  startCompletion,
   keymap,
   EditorView,
   linter,
@@ -180,6 +181,10 @@ export default class FormRoleEditGrantsComponent extends Component {
         if (update.docChanged) {
           this.grantStringsText = update.state.doc.toString();
         }
+        // Trigger autocomplete when we're on an empty line
+        if (line.text === '') {
+          startCompletion(update.view);
+        }
       }
     }),
     linter(this.linterSource),
diff --git a/ui/admin/app/components/form/role/grants/index.hbs b/ui/admin/app/components/form/role/grants/index.hbs
index e6520c88f..16049731a 100644
--- a/ui/admin/app/components/form/role/grants/index.hbs
+++ b/ui/admin/app/components/form/role/grants/index.hbs
@@ -5,7 +5,15 @@
 
 <Hds::Layout::Flex as |F|>
   <F.Item @basis='66%'>
-    <Hds::CodeBlock class='grant-codeblock' @value={{this.grants}} />
+    <Hds::CodeBlock class='grant-codeblock' @value={{this.grants}} as |CB|>
+      <CB.Description>{{t
+          'resources.role.grant.codeblock-description'
+          editGrantsTitle=(t 'resources.role.edit-grants.title')
+          addGrantTemplatesTitle=(t
+            'resources.role.grant-templates.actions.add-grant-templates'
+          )
+        }}</CB.Description>
+    </Hds::CodeBlock>
   </F.Item>
 </Hds::Layout::Flex>