Review

src/components/automation/ha-automation-row.ts

@@ -187,7 +187,6 @@ export class HaAutomationRow extends LitElement {
       flex: 1;
       min-width: 0;
       overflow-wrap: anywhere;
-      margin: 0 var(--ha-space-3);
     }
     ::slotted([slot="header"]) {
       overflow-wrap: anywhere;

src/components/ha-settings-row.ts

@@ -30,6 +30,7 @@ export class HaSettingsRow extends LitElement {
         <slot name="prefix"></slot>
         <div
           class="body"
+          part="heading"
           ?two-line=${!this.threeLine && hasDescription}
           ?three-line=${this.threeLine}
         >

src/components/ha-textarea.ts

@@ -1,12 +1,13 @@
 import "@home-assistant/webawesome/dist/components/textarea/textarea";
 import type WaTextarea from "@home-assistant/webawesome/dist/components/textarea/textarea";
 import { HasSlotController } from "@home-assistant/webawesome/dist/internal/slot";
+import type { PropertyValues } from "lit";
 import { LitElement, css, html, nothing } from "lit";
 import { customElement, property, query } from "lit/decorators";
 import { classMap } from "lit/directives/class-map";
 import { ifDefined } from "lit/directives/if-defined";
-import { WaInputMixin, waInputStyles } from "./input/wa-input-mixin";
 import { stopPropagation } from "../common/dom/stop_propagation";
+import { WaInputMixin, waInputStyles } from "./input/wa-input-mixin";
 
 /**
  * Home Assistant textarea component
@@ -84,6 +85,20 @@ export class HaTextArea extends WaInputMixin(LitElement) {
     this.removeEventListener("keydown", stopPropagation);
   }
 
+  protected override async firstUpdated(
+    changedProperties: PropertyValues<this>
+  ): Promise<void> {
+    super.firstUpdated(changedProperties);
+    if (this.autofocus) {
+      await this._textarea?.updateComplete;
+      this._textarea?.focus();
+    }
+  }
+
+  public override focus(options?: FocusOptions): void {
+    this._textarea?.focus(options);
+  }
+
   protected render() {
     const hasLabelSlot = this.label
       ? false

src/data/automation.ts

@@ -95,6 +95,7 @@ export interface TriggerList {
 
 export interface BaseTrigger {
   alias?: string;
+  comment?: string;
   /** @deprecated Use `trigger` instead */
   platform?: string;
   trigger: string;
@@ -240,6 +241,7 @@ export type Trigger = LegacyTrigger | TriggerList | PlatformTrigger;
 interface BaseCondition {
   condition: string;
   alias?: string;
+  comment?: string;
   enabled?: boolean;
   options?: Record<string, unknown>;
 }
@@ -607,6 +609,7 @@ export interface AutomationClipboard {
 export interface BaseSidebarConfig {
   delete: () => void;
   close: (focus?: boolean) => void;
+  editComment: () => void;
 }
 
 export interface TriggerSidebarConfig extends BaseSidebarConfig {
@@ -668,6 +671,7 @@ export interface OptionSidebarConfig extends BaseSidebarConfig {
   rename: () => void;
   duplicate: () => void;
   defaultOption?: boolean;
+  comment?: string;
 }
 
 export interface ScriptFieldSidebarConfig extends BaseSidebarConfig {

src/data/device/device_automation.ts

@@ -12,6 +12,7 @@ import {
 
 export interface DeviceAutomation {
   alias?: string;
+  comment?: string;
   device_id: string;
   domain: string;
   entity_id?: string;

src/data/script.ts

@@ -36,6 +36,7 @@ export const isMaxMode = arrayLiteralIncludes(MODES_MAX);
 
 export const baseActionStruct = object({
   alias: optional(string()),
+  comment: optional(string()),
   continue_on_error: optional(boolean()),
   enabled: optional(boolean()),
 });
@@ -105,6 +106,7 @@ export interface Field {
 
 interface BaseAction {
   alias?: string;
+  comment?: string;
   continue_on_error?: boolean;
   enabled?: boolean;
 }
@@ -195,6 +197,7 @@ export interface ForEachRepeat extends BaseRepeat {
 
 export interface Option {
   alias?: string;
+  comment?: string;
   conditions: string | Condition[];
   sequence: Action | Action[];
 }

src/dialogs/generic/dialog-box.ts

@@ -9,6 +9,7 @@ import "../../components/ha-dialog";
 import "../../components/ha-dialog-footer";
 import "../../components/ha-dialog-header";
 import "../../components/ha-svg-icon";
+import "../../components/ha-textarea";
 import "../../components/input/ha-input";
 import type { HaInput } from "../../components/input/ha-input";
 import type { HomeAssistant } from "../../types";
@@ -28,7 +29,7 @@ class DialogBox extends LitElement {
 
   @state() private _validInput = true;
 
-  @query("ha-input") private _textField?: HaInput;
+  @query("ha-input, ha-textarea") private _textField?: HaInput;
 
   private _closePromise?: Promise<void>;
 
@@ -109,7 +110,7 @@ class DialogBox extends LitElement {
         </ha-dialog-header>
         <div id="dialog-box-description">
           ${this._params.text ? html` <p>${this._params.text}</p> ` : ""}
-          ${this._params.prompt
+          ${this._params.prompt && !this._params.multiline
             ? html`
                 <ha-input
                   autofocus
@@ -131,7 +132,19 @@ class DialogBox extends LitElement {
                     : nothing}
                 </ha-input>
               `
-            : nothing}
+            : this._params.prompt && this._params.multiline
+              ? html`
+                  <ha-textarea
+                    resize="auto"
+                    autofocus
+                    .value=${this._params.defaultValue}
+                    .placeholder=${this._params.placeholder}
+                    .label=${this._params.inputLabel}
+                    .disabled=${this._loading}
+                    @input=${this._validateInput}
+                  ></ha-textarea>
+                `
+              : nothing}
         </div>
         <ha-dialog-footer slot="footer">
           ${confirmPrompt

src/dialogs/generic/show-dialog-box.ts

@@ -33,6 +33,7 @@ export interface PromptDialogParams extends BaseDialogBoxParams {
   inputMin?: number | string;
   inputMax?: number | string;
   action?: (value?: string) => Promise<void>;
+  multiline?: boolean;
 }
 
 export interface DialogBoxParams

src/panels/config/automation/action/ha-automation-action-editor.ts

@@ -107,6 +107,7 @@ export default class HaAutomationActionEditor extends LitElement {
     ev.stopPropagation();
     const value = {
       ...(this.action.alias ? { alias: this.action.alias } : {}),
+      ...(this.action.comment ? { comment: this.action.comment } : {}),
       ...ev.detail.value,
     };
     fireEvent(this, "value-changed", { value });

src/panels/config/automation/action/ha-automation-action-row.ts

@@ -7,6 +7,8 @@ import {
   mdiArrowUp,
   mdiCheckboxBlankOutline,
   mdiCheckboxOutline,
+  mdiCommentEditOutline,
+  mdiCommentTextOutline,
   mdiContentCopy,
   mdiContentCut,
   mdiContentPaste,
@@ -294,6 +296,13 @@ export default class HaAutomationActionRow extends LitElement {
             ?.target
         : undefined;
 
+    const trimmedComment = this.action.comment?.trim() || "";
+    const commentTooltipText = !trimmedComment
+      ? ""
+      : trimmedComment.length > 250
+        ? `${trimmedComment.substring(0, 250)}...`
+        : trimmedComment;
+
     return html`
       ${type === "service" && "action" in this.action && this.action.action
         ? html`
@@ -329,6 +338,21 @@ export default class HaAutomationActionRow extends LitElement {
               serviceTargetSpec
             )
           : nothing}
+        ${commentTooltipText
+          ? html`
+              <ha-svg-icon
+                id="comment-icon"
+                .path=${mdiCommentTextOutline}
+                .label=${this.hass.localize(
+                  "ui.panel.config.automation.editor.comment.label"
+                )}
+                class="comment-indicator"
+              ></ha-svg-icon
+              ><ha-tooltip for="comment-icon"
+                ><p>${commentTooltipText}</p></ha-tooltip
+              >
+            `
+          : nothing}
         ${type !== "condition" &&
         (this.action as NonConditionAction).continue_on_error === true
           ? html`<ha-svg-icon
@@ -384,6 +408,14 @@ export default class HaAutomationActionRow extends LitElement {
             )
           )}
         </ha-dropdown-item>
+        <ha-dropdown-item value="edit_comment">
+          <ha-svg-icon slot="icon" .path=${mdiCommentEditOutline}></ha-svg-icon>
+          ${this._renderOverflowLabel(
+            this.hass.localize(
+              `ui.panel.config.automation.editor.comment.${this.action.comment ? "edit" : "add"}`
+            )
+          )}
+        </ha-dropdown-item>
         <wa-divider></wa-divider>
         <ha-dropdown-item value="duplicate" .disabled=${this.disabled}>
           <ha-svg-icon
@@ -910,6 +942,38 @@ export default class HaAutomationActionRow extends LitElement {
     }
   };
 
+  private _editCommentAction = async (): Promise<void> => {
+    const comment = await showPromptDialog(this, {
+      title: this.hass.localize(
+        `ui.panel.config.automation.editor.comment.${this.action.comment ? "edit" : "add"}`
+      ),
+      inputLabel: this.hass.localize(
+        "ui.panel.config.automation.editor.comment.label"
+      ),
+      inputType: "string",
+      defaultValue: this.action.comment,
+      confirmText: this.hass.localize("ui.common.submit"),
+      multiline: true,
+    });
+    if (comment !== null) {
+      const value = { ...this.action };
+      if (comment === "") {
+        delete value.comment;
+      } else {
+        value.comment = comment;
+      }
+      fireEvent(this, "value-changed", {
+        value,
+      });
+
+      if (this._selected && this.optionsInSidebar) {
+        this.openSidebar(value); // refresh sidebar
+      } else if (this._yamlMode) {
+        this._actionEditor?.yamlEditor?.setValue(value);
+      }
+    }
+  };
+
   private _duplicateAction = () => {
     fireEvent(this, "duplicate");
   };
@@ -1026,6 +1090,7 @@ export default class HaAutomationActionRow extends LitElement {
       rename: () => {
         this._renameAction();
       },
+      editComment: this._editCommentAction,
       toggleYamlMode: () => {
         this._toggleYamlMode();
         this.openSidebar();
@@ -1121,6 +1186,9 @@ export default class HaAutomationActionRow extends LitElement {
       case "rename":
         this._renameAction();
         break;
+      case "edit_comment":
+        this._editCommentAction();
+        break;
       case "duplicate":
         this._duplicateAction();
         break;

src/panels/config/automation/action/types/ha-automation-action-device_id.ts

@@ -186,6 +186,10 @@ export class HaDeviceAction extends LitElement {
   }
 
   static styles = css`
+    :host {
+      display: block;
+      margin-bottom: var(--ha-space-3);
+    }
     ha-device-picker {
       display: block;
       margin-bottom: 24px;

src/panels/config/automation/condition/ha-automation-condition-editor.ts

@@ -123,6 +123,7 @@ export default class HaAutomationConditionEditor extends LitElement {
     ev.stopPropagation();
     const value = {
       ...(this.condition.alias ? { alias: this.condition.alias } : {}),
+      ...(this.condition.comment ? { comment: this.condition.comment } : {}),
       ...ev.detail.value,
     };
     fireEvent(this, "value-changed", { value });

src/panels/config/automation/condition/ha-automation-condition-row.ts

@@ -4,6 +4,8 @@ import {
   mdiAppleKeyboardCommand,
   mdiArrowDown,
   mdiArrowUp,
+  mdiCommentEditOutline,
+  mdiCommentTextOutline,
   mdiContentCopy,
   mdiContentCut,
   mdiContentPaste,
@@ -200,6 +202,13 @@ export default class HaAutomationConditionRow extends LitElement {
     const conditionTargetSpec =
       this.conditionDescriptions[this.condition.condition]?.target;
 
+    const trimmedComment = this.condition.comment?.trim() || "";
+    const commentTooltipText = !trimmedComment
+      ? ""
+      : trimmedComment.length > 250
+        ? `${trimmedComment.substring(0, 250)}...`
+        : trimmedComment;
+
     return html`
       <ha-condition-icon
         slot="leading-icon"
@@ -217,6 +226,21 @@ export default class HaAutomationConditionRow extends LitElement {
               conditionTargetSpec
             )
           : nothing}
+        ${this.condition.comment?.trim()
+          ? html`
+              <ha-svg-icon
+                id="comment-icon"
+                .path=${mdiCommentTextOutline}
+                .label=${this.hass.localize(
+                  "ui.panel.config.automation.editor.comment.label"
+                )}
+                class="comment-indicator"
+              ></ha-svg-icon>
+              <ha-tooltip for="comment-icon"
+                ><p>${commentTooltipText}</p></ha-tooltip
+              >
+            `
+          : nothing}
       </h3>
       <ha-automation-row-event-chip
         .show=${this._testing}
@@ -264,6 +288,14 @@ export default class HaAutomationConditionRow extends LitElement {
             )
           )}
         </ha-dropdown-item>
+        <ha-dropdown-item value="edit_comment">
+          <ha-svg-icon slot="icon" .path=${mdiCommentEditOutline}></ha-svg-icon>
+          ${this._renderOverflowLabel(
+            this.hass.localize(
+              `ui.panel.config.automation.editor.comment.${this.condition.comment ? "edit" : "add"}`
+            )
+          )}
+        </ha-dropdown-item>
 
         <wa-divider></wa-divider>
 
@@ -813,6 +845,38 @@ export default class HaAutomationConditionRow extends LitElement {
     }
   };
 
+  private _editCommentCondition = async (): Promise<void> => {
+    const comment = await showPromptDialog(this, {
+      title: this.hass.localize(
+        `ui.panel.config.automation.editor.comment.${this.condition.comment ? "edit" : "add"}`
+      ),
+      inputLabel: this.hass.localize(
+        "ui.panel.config.automation.editor.comment.label"
+      ),
+      inputType: "string",
+      defaultValue: this.condition.comment,
+      confirmText: this.hass.localize("ui.common.submit"),
+      multiline: true,
+    });
+    if (comment !== null) {
+      const value = { ...this.condition };
+      if (comment === "") {
+        delete value.comment;
+      } else {
+        value.comment = comment;
+      }
+      fireEvent(this, "value-changed", {
+        value,
+      });
+
+      if (this._selected && this.optionsInSidebar) {
+        this.openSidebar(value); // refresh sidebar
+      } else if (this._yamlMode) {
+        this.conditionEditor?.yamlEditor?.setValue(value);
+      }
+    }
+  };
+
   private _duplicateCondition = () => {
     fireEvent(this, "duplicate");
   };
@@ -954,6 +1018,7 @@ export default class HaAutomationConditionRow extends LitElement {
       rename: () => {
         this._renameCondition();
       },
+      editComment: this._editCommentCondition,
       toggleYamlMode: () => {
         this._toggleYamlMode();
         this.openSidebar();
@@ -1025,6 +1090,9 @@ export default class HaAutomationConditionRow extends LitElement {
       case "rename":
         this._renameCondition();
         break;
+      case "edit_comment":
+        this._editCommentCondition();
+        break;
       case "duplicate":
         this._duplicateCondition();
         break;

src/panels/config/automation/condition/types/ha-automation-condition-device.ts

@@ -188,6 +188,10 @@ export class HaDeviceCondition extends LitElement {
   }
 
   static styles = css`
+    :host {
+      display: block;
+      margin-bottom: var(--ha-space-3);
+    }
     ha-device-picker {
       display: block;
       margin-bottom: 24px;

src/panels/config/automation/condition/types/ha-automation-condition-numeric_state.ts

@@ -1,5 +1,5 @@
 import type { PropertyValues } from "lit";
-import { html, LitElement } from "lit";
+import { css, html, LitElement } from "lit";
 import { customElement, property, state } from "lit/decorators";
 import memoizeOne from "memoize-one";
 import {
@@ -22,6 +22,7 @@ import type { HomeAssistant } from "../../../../../types";
 
 const numericStateConditionStruct = object({
   alias: optional(string()),
+  comment: optional(string()),
   condition: literal("numeric_state"),
   entity_id: optional(string()),
   attribute: optional(string()),
@@ -255,6 +256,13 @@ export default class HaNumericStateCondition extends LitElement {
         );
     }
   };
+
+  static styles = css`
+    :host {
+      display: block;
+      margin-bottom: var(--ha-space-3);
+    }
+  `;
 }
 
 declare global {

src/panels/config/automation/condition/types/ha-automation-condition-state.ts

@@ -1,7 +1,8 @@
 import type { PropertyValues } from "lit";
-import { html, LitElement } from "lit";
+import { css, html, LitElement } from "lit";
 import { customElement, property } from "lit/decorators";
 import {
+  array,
   assert,
   boolean,
   literal,
@@ -10,10 +11,9 @@ import {
   optional,
   string,
   union,
-  array,
 } from "superstruct";
-import { createDurationData } from "../../../../../common/datetime/create_duration_data";
 import { ensureArray } from "../../../../../common/array/ensure-array";
+import { createDurationData } from "../../../../../common/datetime/create_duration_data";
 import { fireEvent } from "../../../../../common/dom/fire_event";
 import "../../../../../components/ha-form/ha-form";
 import type { SchemaUnion } from "../../../../../components/ha-form/types";
@@ -25,6 +25,7 @@ import type { ConditionElement } from "../ha-automation-condition-row";
 
 const stateConditionStruct = object({
   alias: optional(string()),
+  comment: optional(string()),
   condition: literal("state"),
   entity_id: optional(string()),
   attribute: optional(string()),
@@ -142,6 +143,13 @@ export class HaStateCondition extends LitElement implements ConditionElement {
         );
     }
   };
+
+  static styles = css`
+    :host {
+      display: block;
+      margin-bottom: var(--ha-space-3);
+    }
+  `;
 }
 
 declare global {

src/panels/config/automation/ha-automation-comment.ts

@@ -0,0 +1,80 @@
+import "@home-assistant/webawesome/dist/components/divider/divider";
+import { consume, type ContextType } from "@lit/context";
+import { css, html, LitElement } from "lit";
+import { customElement, property, state } from "lit/decorators";
+import { fireEvent } from "../../../common/dom/fire_event";
+import "../../../components/ha-button";
+import "../../../components/ha-settings-row";
+import { internationalizationContext } from "../../../data/context";
+
+@customElement("ha-automation-comment")
+export class HaAutomationComment extends LitElement {
+  @property() public comment!: string;
+
+  @state()
+  @consume({ context: internationalizationContext, subscribe: true })
+  private _i18n!: ContextType<typeof internationalizationContext>;
+
+  protected render() {
+    return html`
+      <ha-settings-row narrow>
+        <div class="heading" slot="heading">
+          <span class="title" id="comment-label">
+            ${this._i18n.localize(
+              "ui.panel.config.automation.editor.comment.label"
+            )}
+          </span>
+          <ha-button
+            @click=${this._handleClick}
+            size="small"
+            appearance="plain"
+          >
+            ${this._i18n.localize("ui.common.edit")}
+          </ha-button>
+        </div>
+        <p aria-labelledby="comment-label">${this.comment}</p>
+      </ha-settings-row>
+    `;
+  }
+
+  private _handleClick() {
+    fireEvent(this, "edit-comment");
+  }
+
+  static styles = css`
+    ha-settings-row {
+      margin-inline: calc(-1 * var(--ha-space-4));
+    }
+    ha-settings-row::part(heading) {
+      padding-inline-end: 0;
+      overflow: visible;
+    }
+    .heading {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    }
+    p {
+      margin: var(--ha-space-2) 0 0;
+      border: var(--ha-border-width-sm) solid
+        var(--ha-color-border-neutral-quiet);
+      padding: var(--ha-space-1) var(--ha-space-3);
+      border-radius: var(--ha-border-radius-lg);
+      background-color: var(--ha-color-fill-neutral-quiet-resting);
+      white-space: pre;
+    }
+    ha-button {
+      margin-inline-end: calc(-1 * var(--ha-space-3));
+    }
+  `;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ha-automation-comment": HaAutomationComment;
+  }
+
+  interface HASSDomEvents {
+    "edit-comment": undefined;
+  }
+}

src/panels/config/automation/option/ha-automation-option-row.ts

@@ -3,6 +3,8 @@ import {
   mdiAppleKeyboardCommand,
   mdiArrowDown,
   mdiArrowUp,
+  mdiCommentEditOutline,
+  mdiCommentTextOutline,
   mdiDelete,
   mdiDotsVertical,
   mdiPlusCircleMultipleOutline,
@@ -37,11 +39,11 @@ import type { Action, Option } from "../../../../data/script";
 import { showPromptDialog } from "../../../../dialogs/generic/show-dialog-box";
 import type { HomeAssistant } from "../../../../types";
 import { isMac } from "../../../../util/is_mac";
-import { showEditorToast } from "../editor-toast";
 import "../action/ha-automation-action";
 import type HaAutomationAction from "../action/ha-automation-action";
 import "../condition/ha-automation-condition";
 import type HaAutomationCondition from "../condition/ha-automation-condition";
+import { showEditorToast } from "../editor-toast";
 import {
   editorStyles,
   indentStyle,
@@ -138,8 +140,14 @@ export default class HaAutomationOptionRow extends LitElement {
       </div>
     `;
   }
-
   private _renderRow() {
+    const trimmedComment = this.option?.comment?.trim() || "";
+    const commentTooltipText = !trimmedComment
+      ? ""
+      : trimmedComment.length > 250
+        ? `${trimmedComment.substring(0, 250)}...`
+        : trimmedComment;
+
     return html`
       <h3 slot="header">
         ${this.option
@@ -150,6 +158,21 @@ export default class HaAutomationOptionRow extends LitElement {
           : this.hass.localize(
               "ui.panel.config.automation.editor.actions.type.choose.default"
             )}
+        ${this.option?.comment?.trim()
+          ? html`
+              <ha-svg-icon
+                id="comment-icon"
+                .path=${mdiCommentTextOutline}
+                .label=${this.hass.localize(
+                  "ui.panel.config.automation.editor.comment.label"
+                )}
+                class="comment-indicator"
+              ></ha-svg-icon>
+              <ha-tooltip for="comment-icon"
+                ><p>${commentTooltipText}</p></ha-tooltip
+              >
+            `
+          : nothing}
       </h3>
 
       <slot name="icons" slot="icons"></slot>
@@ -177,6 +200,17 @@ export default class HaAutomationOptionRow extends LitElement {
                   )
                 )}
               </ha-dropdown-item>
+              <ha-dropdown-item value="edit_comment">
+                <ha-svg-icon
+                  slot="icon"
+                  .path=${mdiCommentEditOutline}
+                ></ha-svg-icon>
+                ${this._renderOverflowLabel(
+                  this.hass.localize(
+                    `ui.panel.config.automation.editor.comment.${this.option?.comment ? "edit" : "add"}`
+                  )
+                )}
+              </ha-dropdown-item>
 
               <ha-dropdown-item value="duplicate" .disabled=${this.disabled}>
                 <ha-svg-icon
@@ -361,6 +395,9 @@ export default class HaAutomationOptionRow extends LitElement {
       case "rename":
         this._renameOption();
         break;
+      case "edit_comment":
+        this._editCommentOption();
+        break;
       case "delete":
         this._removeOption();
         break;
@@ -424,6 +461,39 @@ export default class HaAutomationOptionRow extends LitElement {
     }
   };
 
+  private _editCommentOption = async (): Promise<void> => {
+    if (!this.option) {
+      return;
+    }
+    const comment = await showPromptDialog(this, {
+      title: this.hass.localize(
+        `ui.panel.config.automation.editor.comment.${this.option.comment ? "edit" : "add"}`
+      ),
+      inputLabel: this.hass.localize(
+        "ui.panel.config.automation.editor.comment.label"
+      ),
+      inputType: "string",
+      defaultValue: this.option.comment,
+      confirmText: this.hass.localize("ui.common.submit"),
+      multiline: true,
+    });
+    if (comment !== null) {
+      const value: Option = { ...this.option };
+      if (comment === "") {
+        delete value.comment;
+      } else {
+        value.comment = comment;
+      }
+      fireEvent(this, "value-changed", {
+        value,
+      });
+
+      if (this._selected) {
+        this.openSidebar(value); // refresh sidebar
+      }
+    }
+  };
+
   private _conditionChanged(ev: CustomEvent) {
     ev.stopPropagation();
     const conditions = ev.detail.value as Condition[];
@@ -455,7 +525,8 @@ export default class HaAutomationOptionRow extends LitElement {
     this.openSidebar();
   }
 
-  public openSidebar(): void {
+  public openSidebar(option?: Option): void {
+    const sidebarOption = option ?? this.option;
     fireEvent(this, "open-sidebar", {
       close: (focus?: boolean) => {
         this._selected = false;
@@ -467,9 +538,11 @@ export default class HaAutomationOptionRow extends LitElement {
       rename: () => {
         this._renameOption();
       },
+      editComment: this._editCommentOption,
       delete: this._removeOption,
       duplicate: this._duplicateOption,
       defaultOption: !!this.defaultActions,
+      comment: sidebarOption?.comment,
     } satisfies OptionSidebarConfig);
     this._selected = true;
     this._collapsed = false;

src/panels/config/automation/sidebar/ha-automation-sidebar-action.ts

@@ -3,6 +3,7 @@ import {
   mdiAppleKeyboardCommand,
   mdiCheckboxBlankOutline,
   mdiCheckboxOutline,
+  mdiCommentEditOutline,
   mdiContentCopy,
   mdiContentCut,
   mdiContentPaste,
@@ -26,8 +27,8 @@ import type { HaDropdownSelectEvent } from "../../../../components/ha-dropdown";
 import "../../../../components/ha-dropdown-item";
 import { ACTION_BUILDING_BLOCKS } from "../../../../data/action";
 import type { ActionSidebarConfig } from "../../../../data/automation";
-import { domainToName } from "../../../../data/integration";
 import type { DomainManifestLookup } from "../../../../data/integration";
+import { domainToName } from "../../../../data/integration";
 import type {
   NonConditionAction,
   RepeatAction,
@@ -38,6 +39,7 @@ import { isMac } from "../../../../util/is_mac";
 import type HaAutomationConditionEditor from "../action/ha-automation-action-editor";
 import { getAutomationActionType } from "../action/ha-automation-action-row";
 import { getRepeatType } from "../action/types/ha-automation-action-repeat";
+import "../ha-automation-comment";
 import { overflowStyles, sidebarEditorStyles } from "../styles";
 import "./ha-automation-sidebar-card";
 
@@ -175,6 +177,15 @@ export default class HaAutomationSidebarAction extends LitElement {
           <span class="shortcut-placeholder ${isMac ? "mac" : ""}"></span>
         </div>
       </ha-dropdown-item>
+      <ha-dropdown-item slot="menu-items" value="edit_comment">
+        <ha-svg-icon slot="icon" .path=${mdiCommentEditOutline}></ha-svg-icon>
+        <div class="overflow-label">
+          ${this.hass.localize(
+            `ui.panel.config.automation.editor.comment.${this.config.config.action.comment ? "edit" : "add"}`
+          )}
+          <span class="shortcut-placeholder ${isMac ? "mac" : ""}"></span>
+        </div>
+      </ha-dropdown-item>
 
       <wa-divider slot="menu-items"></wa-divider>
       <ha-dropdown-item
@@ -377,6 +388,12 @@ export default class HaAutomationSidebarAction extends LitElement {
               @ui-mode-not-available=${this._handleUiModeNotAvailable}
             ></ha-automation-action-editor>`
           )}
+      ${this.config.config.action.comment?.trim() && !this.yamlMode
+        ? html`<ha-automation-comment
+            @edit-comment=${this.config.editComment}
+            .comment=${this.config.config.action.comment}
+          ></ha-automation-comment>`
+        : nothing}
     </ha-automation-sidebar-card>`;
   }
 
@@ -425,6 +442,9 @@ export default class HaAutomationSidebarAction extends LitElement {
       case "rename":
         this.config.rename();
         break;
+      case "edit_comment":
+        this.config.editComment();
+        break;
       case "run":
         this.config.run();
         break;

src/panels/config/automation/sidebar/ha-automation-sidebar-condition.ts

@@ -1,6 +1,7 @@
 import "@home-assistant/webawesome/dist/components/divider/divider";
 import {
   mdiAppleKeyboardCommand,
+  mdiCommentEditOutline,
   mdiContentCopy,
   mdiContentCut,
   mdiContentPaste,
@@ -34,6 +35,7 @@ import type { HomeAssistant } from "../../../../types";
 import { isMac } from "../../../../util/is_mac";
 import "../condition/ha-automation-condition-editor";
 import type HaAutomationConditionEditor from "../condition/ha-automation-condition-editor";
+import "../ha-automation-comment";
 import { overflowStyles, sidebarEditorStyles } from "../styles";
 import "./ha-automation-sidebar-card";
 
@@ -149,6 +151,19 @@ export default class HaAutomationSidebarCondition extends LitElement {
           <span class="shortcut-placeholder ${isMac ? "mac" : ""}"></span>
         </div>
       </ha-dropdown-item>
+      <ha-dropdown-item
+        slot="menu-items"
+        value="edit_comment"
+        .disabled=${this.disabled}
+      >
+        <ha-svg-icon slot="icon" .path=${mdiCommentEditOutline}></ha-svg-icon>
+        <div class="overflow-label">
+          ${this.hass.localize(
+            `ui.panel.config.automation.editor.comment.${this.config.config.comment ? "edit" : "add"}`
+          )}
+          <span class="shortcut-placeholder ${isMac ? "mac" : ""}"></span>
+        </div>
+      </ha-dropdown-item>
 
       <wa-divider slot="menu-items"></wa-divider>
 
@@ -332,6 +347,12 @@ export default class HaAutomationSidebarCondition extends LitElement {
               sidebar
             ></ha-automation-condition-editor>`
           )}
+      ${this.config.config.comment?.trim() && !this.yamlMode
+        ? html`<ha-automation-comment
+            @edit-comment=${this.config.editComment}
+            .comment=${this.config.config.comment}
+          ></ha-automation-comment>`
+        : nothing}
       <div class="testing-wrapper">
         <div
           class="testing ${classMap({
@@ -396,6 +417,9 @@ export default class HaAutomationSidebarCondition extends LitElement {
       case "rename":
         this.config.rename();
         break;
+      case "edit_comment":
+        this.config.editComment();
+        break;
       case "test":
         this.config.test();
         break;

src/panels/config/automation/sidebar/ha-automation-sidebar-option.ts

@@ -1,6 +1,7 @@
 import "@home-assistant/webawesome/dist/components/divider/divider";
 import {
   mdiAppleKeyboardCommand,
+  mdiCommentEditOutline,
   mdiDelete,
   mdiPlusCircleMultipleOutline,
   mdiRenameBox,
@@ -14,6 +15,7 @@ import type { OptionSidebarConfig } from "../../../../data/automation";
 import type { HomeAssistant } from "../../../../types";
 import { isMac } from "../../../../util/is_mac";
 import type HaAutomationConditionEditor from "../action/ha-automation-action-editor";
+import "../ha-automation-comment";
 import { overflowStyles, sidebarEditorStyles } from "../styles";
 import "./ha-automation-sidebar-card";
 import type { HaDropdownSelectEvent } from "../../../../components/ha-dropdown";
@@ -72,6 +74,22 @@ export default class HaAutomationSidebarOption extends LitElement {
                 <span class="shortcut-placeholder ${isMac ? "mac" : ""}"></span>
               </div>
             </ha-dropdown-item>
+            <ha-dropdown-item
+              slot="menu-items"
+              value="edit_comment"
+              .disabled=${!!disabled}
+            >
+              <ha-svg-icon
+                slot="icon"
+                .path=${mdiCommentEditOutline}
+              ></ha-svg-icon>
+              <div class="overflow-label">
+                ${this.hass.localize(
+                  `ui.panel.config.automation.editor.comment.${this.config.comment ? "edit" : "add"}`
+                )}
+                <span class="shortcut-placeholder ${isMac ? "mac" : ""}"></span>
+              </div>
+            </ha-dropdown-item>
 
             <ha-dropdown-item
               slot="menu-items"
@@ -126,6 +144,12 @@ export default class HaAutomationSidebarOption extends LitElement {
           `}
 
       <div class="description">${description}</div>
+      ${!this.config.defaultOption && this.config.comment?.trim()
+        ? html`<ha-automation-comment
+            @edit-comment=${this.config.editComment}
+            .comment=${this.config.comment}
+          ></ha-automation-comment>`
+        : nothing}
     </ha-automation-sidebar-card>`;
   }
 
@@ -140,6 +164,9 @@ export default class HaAutomationSidebarOption extends LitElement {
       case "rename":
         this.config.rename();
         break;
+      case "edit_comment":
+        this.config.editComment();
+        break;
       case "duplicate":
         this.config.duplicate();
         break;

src/panels/config/automation/sidebar/ha-automation-sidebar-script-field.ts

@@ -1,18 +1,24 @@
-import { mdiAppleKeyboardCommand, mdiDelete, mdiPlaylistEdit } from "@mdi/js";
+import {
+  mdiAppleKeyboardCommand,
+  mdiCommentEditOutline,
+  mdiDelete,
+  mdiPlaylistEdit,
+} from "@mdi/js";
 import type { PropertyValues } from "lit";
 import { html, LitElement, nothing } from "lit";
 import { customElement, property, query, state } from "lit/decorators";
 import { keyed } from "lit/directives/keyed";
 import { fireEvent } from "../../../../common/dom/fire_event";
+import type { HaDropdownSelectEvent } from "../../../../components/ha-dropdown";
 import "../../../../components/ha-dropdown-item";
 import type { ScriptFieldSidebarConfig } from "../../../../data/automation";
 import type { HomeAssistant } from "../../../../types";
 import { isMac } from "../../../../util/is_mac";
 import "../../script/ha-script-field-editor";
 import type HaAutomationConditionEditor from "../action/ha-automation-action-editor";
+import "../ha-automation-comment";
 import { overflowStyles, sidebarEditorStyles } from "../styles";
 import "./ha-automation-sidebar-card";
-import type { HaDropdownSelectEvent } from "../../../../components/ha-dropdown";
 
 @customElement("ha-automation-sidebar-script-field")
 export default class HaAutomationSidebarScriptField extends LitElement {
@@ -62,6 +68,15 @@ export default class HaAutomationSidebarScriptField extends LitElement {
       @wa-select=${this._handleDropdownSelect}
     >
       <span slot="title">${title}</span>
+      <ha-dropdown-item slot="menu-items" value="edit_comment">
+        <ha-svg-icon slot="icon" .path=${mdiCommentEditOutline}></ha-svg-icon>
+        <div class="overflow-label">
+          ${this.hass.localize(
+            `ui.panel.config.automation.editor.comment.${this.config.config.field.description ? "edit" : "add"}`
+          )}
+          <span class="shortcut-placeholder ${isMac ? "mac" : ""}"></span>
+        </div>
+      </ha-dropdown-item>
       <ha-dropdown-item
         slot="menu-items"
         value="toggle_yaml_mode"
@@ -121,6 +136,12 @@ export default class HaAutomationSidebarScriptField extends LitElement {
           @yaml-changed=${this._yamlChangedSidebar}
         ></ha-script-field-editor>`
       )}
+      ${this.config.config.field.description?.trim() && !this.yamlMode
+        ? html`<ha-automation-comment
+            @edit-comment=${this.config.editComment}
+            .comment=${this.config.config.field.description}
+          ></ha-automation-comment>`
+        : nothing}
     </ha-automation-sidebar-card>`;
   }
 
@@ -168,6 +189,9 @@ export default class HaAutomationSidebarScriptField extends LitElement {
       case "toggle_yaml_mode":
         this._toggleYamlMode();
         break;
+      case "edit_comment":
+        this.config.editComment();
+        break;
       case "delete":
         this.config.delete();
         break;

src/panels/config/automation/sidebar/ha-automation-sidebar-trigger.ts

@@ -1,6 +1,7 @@
 import "@home-assistant/webawesome/dist/components/divider/divider";
 import {
   mdiAppleKeyboardCommand,
+  mdiCommentEditOutline,
   mdiContentCopy,
   mdiContentCut,
   mdiContentPaste,
@@ -18,9 +19,12 @@ import { customElement, property, query, state } from "lit/decorators";
 import { keyed } from "lit/directives/keyed";
 import { fireEvent } from "../../../../common/dom/fire_event";
 import { handleStructError } from "../../../../common/structs/handle-errors";
+import type { HaDropdownSelectEvent } from "../../../../components/ha-dropdown";
 import "../../../../components/ha-dropdown-item";
 import type {
   LegacyTrigger,
+  Trigger,
+  TriggerList,
   TriggerSidebarConfig,
 } from "../../../../data/automation";
 import {
@@ -30,11 +34,11 @@ import {
 } from "../../../../data/trigger";
 import type { HomeAssistant } from "../../../../types";
 import { isMac } from "../../../../util/is_mac";
+import "../ha-automation-comment";
 import { overflowStyles, sidebarEditorStyles } from "../styles";
 import "../trigger/ha-automation-trigger-editor";
 import type HaAutomationTriggerEditor from "../trigger/ha-automation-trigger-editor";
 import "./ha-automation-sidebar-card";
-import type { HaDropdownSelectEvent } from "../../../../components/ha-dropdown";
 
 @customElement("ha-automation-sidebar-trigger")
 export default class HaAutomationSidebarTrigger extends LitElement {
@@ -125,7 +129,24 @@ export default class HaAutomationSidebarTrigger extends LitElement {
             <span class="shortcut-placeholder ${isMac ? "mac" : ""}"></span>
           </div>
         </ha-dropdown-item>
-
+        ${type !== "list"
+          ? html`<ha-dropdown-item
+              slot="menu-items"
+              value="edit_comment"
+              .disabled=${this.disabled}
+            >
+              <ha-svg-icon
+                slot="icon"
+                .path=${mdiCommentEditOutline}
+              ></ha-svg-icon>
+              <div class="overflow-label">
+                ${this.hass.localize(
+                  `ui.panel.config.automation.editor.comment.${(this.config.config as Exclude<Trigger, TriggerList>).comment ? "edit" : "add"}`
+                )}
+                <span class="shortcut-placeholder ${isMac ? "mac" : ""}"></span>
+              </div>
+            </ha-dropdown-item>`
+          : nothing}
         ${!this.yamlMode &&
         !("id" in this.config.config) &&
         !this._requestShowId
@@ -321,6 +342,14 @@ export default class HaAutomationSidebarTrigger extends LitElement {
             sidebar
           ></ha-automation-trigger-editor>`
         )}
+        ${!isTriggerList(this.config.config) &&
+        this.config.config.comment?.trim() &&
+        !this.yamlMode
+          ? html`<ha-automation-comment
+              @edit-comment=${this.config.editComment}
+              .comment=${this.config.config.comment}
+            ></ha-automation-comment>`
+          : nothing}
       </ha-automation-sidebar-card>
     `;
   }
@@ -372,6 +401,9 @@ export default class HaAutomationSidebarTrigger extends LitElement {
       case "rename":
         this.config.rename();
         break;
+      case "edit_comment":
+        this.config.editComment();
+        break;
       case "show_id":
         this._showTriggerId();
         break;

src/panels/config/automation/structs.ts

@@ -4,6 +4,7 @@ export const baseTriggerStruct = object({
   trigger: string(),
   id: optional(string()),
   enabled: optional(boolean()),
+  comment: optional(string()),
 });
 
 export const forDictStruct = object({

src/panels/config/automation/styles.ts

@@ -52,6 +52,18 @@ export const rowStyles = css`
   ha-automation-row-event-chip.event-chip {
     position: absolute;
   }
+
+  .comment-indicator {
+    color: var(--ha-color-on-neutral-normal);
+  }
+  .comment-indicator + ha-tooltip::part(body) {
+    cursor: default;
+    max-width: 300px;
+  }
+  .comment-indicator + ha-tooltip p {
+    white-space: pre;
+    margin: 0;
+  }
 `;
 
 export const editorStyles = css`

src/panels/config/automation/trigger/ha-automation-trigger-editor.ts

@@ -141,6 +141,7 @@ export default class HaAutomationTriggerEditor extends LitElement {
     ev.stopPropagation();
     const value = {
       ...(this.trigger.alias ? { alias: this.trigger.alias } : {}),
+      ...(this.trigger.comment ? { comment: this.trigger.comment } : {}),
       ...ev.detail.value,
     };
     fireEvent(this, "value-changed", { value });

src/panels/config/automation/trigger/ha-automation-trigger-row.ts

@@ -4,6 +4,8 @@ import {
   mdiAppleKeyboardCommand,
   mdiArrowDown,
   mdiArrowUp,
+  mdiCommentEditOutline,
+  mdiCommentTextOutline,
   mdiContentCopy,
   mdiContentCut,
   mdiContentPaste,
@@ -221,6 +223,16 @@ export default class HaAutomationTriggerRow extends LitElement {
             ?.target
         : undefined;
 
+    const trimmedComment =
+      (type !== "list" &&
+        (this.trigger as Exclude<Trigger, TriggerList>).comment?.trim()) ||
+      "";
+    const commentTooltipText = !trimmedComment
+      ? ""
+      : trimmedComment.length > 250
+        ? `${trimmedComment.substring(0, 250)}...`
+        : trimmedComment;
+
     return html`
       ${type === "list"
         ? html`<ha-svg-icon
@@ -242,6 +254,22 @@ export default class HaAutomationTriggerRow extends LitElement {
               triggerTargetSpec
             )
           : nothing}
+        ${type !== "list" &&
+        (this.trigger as Exclude<Trigger, TriggerList>).comment?.trim()
+          ? html`
+              <ha-svg-icon
+                id="comment-icon"
+                .path=${mdiCommentTextOutline}
+                .label=${this.hass.localize(
+                  "ui.panel.config.automation.editor.comment.label"
+                )}
+                class="comment-indicator"
+              ></ha-svg-icon>
+              <ha-tooltip for="comment-icon"
+                ><p>${commentTooltipText}</p></ha-tooltip
+              >
+            `
+          : nothing}
       </h3>
       <ha-automation-row-event-chip
         .show=${this._triggered}
@@ -282,7 +310,19 @@ export default class HaAutomationTriggerRow extends LitElement {
             )
           )}
         </ha-dropdown-item>
-
+        ${type !== "list"
+          ? html`<ha-dropdown-item value="edit_comment">
+              <ha-svg-icon
+                slot="icon"
+                .path=${mdiCommentEditOutline}
+              ></ha-svg-icon>
+              ${this._renderOverflowLabel(
+                this.hass.localize(
+                  `ui.panel.config.automation.editor.comment.${(this.trigger as Exclude<Trigger, TriggerList>).comment ? "edit" : "add"}`
+                )
+              )}
+            </ha-dropdown-item>`
+          : nothing}
         <wa-divider></wa-divider>
 
         <ha-dropdown-item value="duplicate" .disabled=${this.disabled}>
@@ -659,6 +699,7 @@ export default class HaAutomationTriggerRow extends LitElement {
       rename: () => {
         this._renameTrigger();
       },
+      editComment: this._editCommentTrigger,
       toggleYamlMode: () => {
         this._toggleYamlMode();
         this.openSidebar();
@@ -802,6 +843,40 @@ export default class HaAutomationTriggerRow extends LitElement {
     }
   };
 
+  private _editCommentTrigger = async (): Promise<void> => {
+    if (isTriggerList(this.trigger)) return;
+    const trigger = this.trigger;
+    const comment = await showPromptDialog(this, {
+      title: this.hass.localize(
+        `ui.panel.config.automation.editor.comment.${trigger.comment ? "edit" : "add"}`
+      ),
+      inputLabel: this.hass.localize(
+        "ui.panel.config.automation.editor.comment.label"
+      ),
+      inputType: "string",
+      defaultValue: trigger.comment,
+      confirmText: this.hass.localize("ui.common.submit"),
+      multiline: true,
+    });
+    if (comment !== null) {
+      const value = { ...trigger };
+      if (comment === "") {
+        delete value.comment;
+      } else {
+        value.comment = comment;
+      }
+      fireEvent(this, "value-changed", {
+        value,
+      });
+
+      if (this._selected && this.optionsInSidebar) {
+        this.openSidebar(value); // refresh sidebar
+      } else if (this._yamlMode) {
+        this.triggerEditor?.yamlEditor?.setValue(value);
+      }
+    }
+  };
+
   private _duplicateTrigger = () => {
     fireEvent(this, "duplicate");
   };
@@ -913,6 +988,9 @@ export default class HaAutomationTriggerRow extends LitElement {
       case "rename":
         this._renameTrigger();
         break;
+      case "edit_comment":
+        this._editCommentTrigger();
+        break;
       case "duplicate":
         this._duplicateTrigger();
         break;

src/panels/config/automation/trigger/types/ha-automation-trigger-device.ts

@@ -212,6 +212,10 @@ export class HaDeviceTrigger extends LitElement {
   }
 
   static styles = css`
+    :host {
+      display: block;
+      margin-bottom: var(--ha-space-3);
+    }
     ha-device-picker {
       display: block;
       margin-bottom: 24px;

src/panels/config/automation/trigger/types/ha-automation-trigger-numeric_state.ts

@@ -1,7 +1,8 @@
 import type { PropertyValues } from "lit";
-import { html, LitElement } from "lit";
+import { css, html, LitElement } from "lit";
 import { customElement, property, state } from "lit/decorators";
 import memoizeOne from "memoize-one";
+import { ensureArray } from "../../../../../common/array/ensure-array";
 import { createDurationData } from "../../../../../common/datetime/create_duration_data";
 import { fireEvent } from "../../../../../common/dom/fire_event";
 import { hasTemplate } from "../../../../../common/string/has-template";
@@ -10,7 +11,6 @@ import "../../../../../components/ha-form/ha-form";
 import type { SchemaUnion } from "../../../../../components/ha-form/types";
 import type { NumericStateTrigger } from "../../../../../data/automation";
 import type { HomeAssistant } from "../../../../../types";
-import { ensureArray } from "../../../../../common/array/ensure-array";
 
 @customElement("ha-automation-trigger-numeric_state")
 export class HaNumericStateTrigger extends LitElement {
@@ -333,6 +333,13 @@ export class HaNumericStateTrigger extends LitElement {
         );
     }
   };
+
+  static styles = css`
+    :host {
+      display: block;
+      margin-bottom: var(--ha-space-3);
+    }
+  `;
 }
 
 declare global {

src/panels/config/automation/trigger/types/ha-automation-trigger-platform.ts

@@ -29,6 +29,7 @@ const DEFAULT_KEYS: (keyof PlatformTrigger)[] = [
   "trigger",
   "target",
   "alias",
+  "comment",
   "id",
   "variables",
   "enabled",

src/panels/config/automation/trigger/types/ha-automation-trigger-state.ts

@@ -1,6 +1,7 @@
 import type { PropertyValues } from "lit";
-import { html, LitElement } from "lit";
+import { css, html, LitElement } from "lit";
 import { customElement, property } from "lit/decorators";
+import memoizeOne from "memoize-one";
 import {
   array,
   assert,
@@ -13,22 +14,21 @@ import {
   string,
   union,
 } from "superstruct";
-import memoizeOne from "memoize-one";
-import type { LocalizeFunc } from "../../../../../common/translations/localize";
 import { ensureArray } from "../../../../../common/array/ensure-array";
+import { createDurationData } from "../../../../../common/datetime/create_duration_data";
 import { fireEvent } from "../../../../../common/dom/fire_event";
 import { hasTemplate } from "../../../../../common/string/has-template";
-import type { StateTrigger } from "../../../../../data/automation";
+import type { LocalizeFunc } from "../../../../../common/translations/localize";
 import { ANY_STATE_VALUE } from "../../../../../components/entity/const";
-import type { HomeAssistant } from "../../../../../types";
-import { baseTriggerStruct, forDictStruct } from "../../structs";
-import type { TriggerElement } from "../ha-automation-trigger-row";
 import "../../../../../components/ha-form/ha-form";
-import { createDurationData } from "../../../../../common/datetime/create_duration_data";
 import type {
   HaFormSchema,
   SchemaUnion,
 } from "../../../../../components/ha-form/types";
+import type { StateTrigger } from "../../../../../data/automation";
+import type { HomeAssistant } from "../../../../../types";
+import { baseTriggerStruct, forDictStruct } from "../../structs";
+import type { TriggerElement } from "../ha-automation-trigger-row";
 
 const stateTriggerStruct = assign(
   baseTriggerStruct,
@@ -303,6 +303,13 @@ export class HaStateTrigger extends LitElement implements TriggerElement {
         ? "ui.components.entity.entity-picker.entity"
         : `ui.panel.config.automation.editor.triggers.type.state.${schema.name}`
     );
+
+  static styles = css`
+    :host {
+      display: block;
+      margin-bottom: var(--ha-space-3);
+    }
+  `;
 }
 
 declare global {

src/panels/config/script/ha-script-field-editor.ts

@@ -42,10 +42,6 @@ export default class HaScriptFieldEditor extends LitElement {
           name: "key",
           selector: { text: {} },
         },
-        {
-          name: "description",
-          selector: { text: {} },
-        },
         {
           name: "required",
           selector: { boolean: {} },

src/panels/config/script/ha-script-field-row.ts

@@ -1,5 +1,7 @@
 import {
   mdiAppleKeyboardCommand,
+  mdiCommentEditOutline,
+  mdiCommentTextOutline,
   mdiDelete,
   mdiDotsVertical,
   mdiPlaylistEdit,
@@ -21,6 +23,7 @@ import "../../../components/ha-dropdown-item";
 import type { ScriptFieldSidebarConfig } from "../../../data/automation";
 import type { Field } from "../../../data/script";
 import { SELECTOR_SELECTOR_BUILDING_BLOCKS } from "../../../data/selector/selector_selector";
+import { showPromptDialog } from "../../../dialogs/generic/show-dialog-box";
 import type { HomeAssistant } from "../../../types";
 import { isMac } from "../../../util/is_mac";
 import { showEditorToast } from "../automation/editor-toast";
@@ -66,6 +69,14 @@ export default class HaScriptFieldRow extends LitElement {
   protected render() {
     const hasSelector =
       this.field.selector && typeof this.field.selector === "object";
+
+    const trimmedComment = this.field.description?.trim() || "";
+    const commentTooltipText = !trimmedComment
+      ? ""
+      : trimmedComment.length > 250
+        ? `${trimmedComment.substring(0, 250)}...`
+        : trimmedComment;
+
     return html`
       <ha-card outlined>
         <ha-automation-row
@@ -90,6 +101,16 @@ export default class HaScriptFieldRow extends LitElement {
               .label=${this.hass.localize("ui.common.menu")}
               .path=${mdiDotsVertical}
             ></ha-icon-button>
+
+            <ha-dropdown-item value="edit_comment">
+              <ha-svg-icon
+                slot="icon"
+                .path=${mdiCommentEditOutline}
+              ></ha-svg-icon>
+              ${this.hass.localize(
+                `ui.panel.config.automation.editor.comment.${this.field.description ? "edit" : "add"}`
+              )}
+            </ha-dropdown-item>
             <ha-dropdown-item value="toggle_yaml_mode">
               <ha-svg-icon slot="icon" .path=${mdiPlaylistEdit}></ha-svg-icon>
               <div class="overflow-label">
@@ -132,7 +153,24 @@ export default class HaScriptFieldRow extends LitElement {
             </ha-dropdown-item>
           </ha-dropdown>
 
-          <h3 slot="header">${this.field.name ?? this.key}</h3>
+          <h3 slot="header">
+            ${this.field.name ?? this.key}
+            ${this.field.description?.trim()
+              ? html`
+                  <ha-svg-icon
+                    id="comment-icon"
+                    .path=${mdiCommentTextOutline}
+                    .label=${this.hass.localize(
+                      "ui.panel.config.automation.editor.comment.label"
+                    )}
+                    class="comment-indicator"
+                  ></ha-svg-icon>
+                  <ha-tooltip for="comment-icon"
+                    ><p>${commentTooltipText}</p></ha-tooltip
+                  >
+                `
+              : nothing}
+          </h3>
 
           <slot name="icons" slot="icons"></slot>
         </ha-automation-row>
@@ -324,11 +362,46 @@ export default class HaScriptFieldRow extends LitElement {
     });
   }
 
-  public openSidebar(selectorEditor = false): void {
+  private _editComment = async (): Promise<void> => {
+    const comment = await showPromptDialog(this, {
+      title: this.hass.localize(
+        `ui.panel.config.automation.editor.comment.${this.field.description ? "edit" : "add"}`
+      ),
+      inputLabel: this.hass.localize(
+        "ui.panel.config.automation.editor.comment.label"
+      ),
+      inputType: "string",
+      defaultValue: this.field.description,
+      confirmText: this.hass.localize("ui.common.submit"),
+      multiline: true,
+    });
+    if (comment !== null) {
+      const value = { ...this.field };
+      if (comment === "") {
+        delete value.description;
+      } else {
+        value.description = comment;
+      }
+      fireEvent(this, "value-changed", {
+        value,
+      });
+
+      if (this._selected) {
+        this.openSidebar(false, value); // refresh sidebar
+      }
+    }
+  };
+
+  public openSidebar(
+    selectorEditor = false,
+    fieldValue?: HaScriptFieldRow["field"]
+  ): void {
     if (!selectorEditor) {
       this._selected = true;
     }
 
+    const field = fieldValue ?? this.field;
+
     fireEvent(this, "open-sidebar", {
       save: (value) => {
         fireEvent(this, "value-changed", { value });
@@ -353,12 +426,13 @@ export default class HaScriptFieldRow extends LitElement {
       },
       delete: this._onDelete,
       config: {
-        field: this.field,
+        field,
         selector: selectorEditor,
         key: this.key,
         excludeKeys: this.excludeKeys,
       },
       yamlMode: this._yamlMode,
+      editComment: this._editComment,
     } satisfies ScriptFieldSidebarConfig);
 
     if (this.narrow) {
@@ -419,6 +493,9 @@ export default class HaScriptFieldRow extends LitElement {
       case "delete":
         this._onDelete();
         break;
+      case "edit_comment":
+        this._editComment();
+        break;
     }
   }
 

src/translations/en.json

@@ -5049,6 +5049,11 @@
               "placeholder": "Optional description",
               "add": "Add description"
             },
+            "comment": {
+              "label": "Comment",
+              "edit": "Edit comment",
+              "add": "Add comment"
+            },
             "leave": {
               "unsaved_new_title": "Save new automation?",
               "unsaved_new_text": "You can save your changes, or delete this automation. You can't undo this action.",