This is an automated email from the ASF dual-hosted git repository.

mattcasters pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/hop.git


The following commit(s) were added to refs/heads/main by this push:
     new 390cb27a97 Issue #6751 : Annotate a transform or action (#9244)
390cb27a97 is described below

commit 390cb27a97835c492c570ef9dd76bc847afd0051
Author: Matt Casters <[email protected]>
AuthorDate: Fri Nov 6 11:37:51 2026 +0100

    Issue #6751 : Annotate a transform or action (#9244)
    
    Add a callout anchored to a pipeline transform or workflow action. The text 
is plain, the colors follow light and dark mode, and a dashed line can connect 
the callout to its icon.
---
 assemblies/plugins/pom.xml                         |   6 +
 .../assets/images/hop-gui/annotation-callout.png   | Bin 0 -> 49225 bytes
 .../modules/ROOT/pages/hop-gui/notes.adoc          |  16 +-
 plugins/misc/{ => annotation}/pom.xml              |  29 +-
 plugins/misc/annotation/src/assembly/assembly.xml  |  39 +++
 .../java/org/apache/hop/annotation/Annotation.java |  72 +++++
 .../apache/hop/annotation/AnnotationClicks.java    | 254 +++++++++++++++
 .../apache/hop/annotation/AnnotationDialog.java    | 102 ++++++
 .../apache/hop/annotation/AnnotationGeometry.java  | 202 ++++++++++++
 .../apache/hop/annotation/AnnotationGuiPlugin.java | 111 +++++++
 .../org/apache/hop/annotation/AnnotationHit.java   |  26 ++
 .../apache/hop/annotation/AnnotationPainter.java   | 133 ++++++++
 .../apache/hop/annotation/AnnotationPlacement.java |  54 ++++
 .../org/apache/hop/annotation/AnnotationStore.java |  99 ++++++
 .../DrawActionAnnotationExtensionPoint.java        |  53 +++
 .../DrawTransformAnnotationExtensionPoint.java     |  53 +++
 .../PipelineAnnotationMouseExtensionPoints.java    |  65 ++++
 .../WorkflowAnnotationMouseExtensionPoints.java    |  65 ++++
 .../annotation/messages/messages_en_US.properties  |  42 +++
 .../misc/annotation/src/main/resources/version.xml |  20 ++
 .../hop/annotation/AnnotationGeometryTest.java     | 123 +++++++
 .../hop/annotation/AnnotationPainterTest.java      | 355 +++++++++++++++++++++
 .../apache/hop/annotation/AnnotationStoreTest.java | 139 ++++++++
 plugins/misc/pom.xml                               |   1 +
 24 files changed, 2034 insertions(+), 25 deletions(-)

diff --git a/assemblies/plugins/pom.xml b/assemblies/plugins/pom.xml
index 50fcdc80c1..5b533dff52 100644
--- a/assemblies/plugins/pom.xml
+++ b/assemblies/plugins/pom.xml
@@ -636,6 +636,12 @@
             <version>${project.version}</version>
             <type>zip</type>
         </dependency>
+        <dependency>
+            <groupId>org.apache.hop</groupId>
+            <artifactId>hop-misc-annotation</artifactId>
+            <version>${project.version}</version>
+            <type>zip</type>
+        </dependency>
         <dependency>
             <groupId>org.apache.hop</groupId>
             <artifactId>hop-misc-debug</artifactId>
diff --git 
a/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/annotation-callout.png
 
b/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/annotation-callout.png
new file mode 100644
index 0000000000..590b8f4fb6
Binary files /dev/null and 
b/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/annotation-callout.png
 differ
diff --git a/docs/hop-user-manual/modules/ROOT/pages/hop-gui/notes.adoc 
b/docs/hop-user-manual/modules/ROOT/pages/hop-gui/notes.adoc
index cbf5355f9a..a35b101132 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/hop-gui/notes.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/hop-gui/notes.adoc
@@ -15,13 +15,27 @@ specific language governing permissions and limitations
 under the License.
 ////
 :imagesdir: ../assets/images/
-:description: Notes on pipeline and workflow canvases, including Markdown 
formatting, note types, links, and images.
+:description: Notes on pipeline and workflow canvases, including Markdown 
formatting, note types, links, images, and annotations attached to a transform 
or action.
 
 [[CanvasNotes]]
 = Notes on pipelines and workflows
 
 Notes are free-floating annotations on the pipeline and workflow canvas. They 
do not participate in execution; they document design intent for anyone opening 
the file.
 
+== Annotations on a transform or action
+
+An annotation is a short callout attached to one transform or one workflow 
action. It stays next to that icon, and it is not executed.
+
+* Open the context dialog on a transform or action and choose **Annotate**.
+* Choose where it sits relative to the icon: top, top right, right, bottom 
right, bottom, bottom left, left, or top left. The default is above the icon. 
Moving, copying, or renaming the transform or action keeps the callout with it.
+* The text is plain. Hop picks the fill, border, and text colors so the 
callout stays readable in light and dark mode.
+* **Dashed line** draws a dashed line from the callout to the icon. New 
annotations start with the line on. Turn it off to leave the callout 
unconnected.
+* Click the callout to edit it. **Remove annotation** clears it.
+
+image::hop-gui/annotation-callout.png[An annotation with a dashed line to its 
transform,width="80%"]
+
+A note floats on the canvas. An annotation belongs to one icon.
+
 == Create and edit notes
 
 * From an empty area of the canvas, open the context dialog and choose 
**Create a note** (or the equivalent note action).
diff --git a/plugins/misc/pom.xml b/plugins/misc/annotation/pom.xml
similarity index 61%
copy from plugins/misc/pom.xml
copy to plugins/misc/annotation/pom.xml
index 174b1b279c..af13539caa 100644
--- a/plugins/misc/pom.xml
+++ b/plugins/misc/annotation/pom.xml
@@ -14,38 +14,19 @@
   ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   ~ See the License for the specific language governing permissions and
   ~ limitations under the License.
+  ~
   -->
 <project xmlns="http://maven.apache.org/POM/4.0.0"; 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; 
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
http://maven.apache.org/xsd/maven-4.0.0.xsd";>
     <modelVersion>4.0.0</modelVersion>
 
     <parent>
         <groupId>org.apache.hop</groupId>
-        <artifactId>hop-plugins</artifactId>
+        <artifactId>hop-plugins-misc</artifactId>
         <version>2.21.0-SNAPSHOT</version>
     </parent>
 
-    <artifactId>hop-plugins-misc</artifactId>
-    <packaging>pom</packaging>
-    <name>Hop Plugins Miscellaneous</name>
-
-    <modules>
-        <module>debug</module>
-        <module>documentation</module>
-        <module>execution-database</module>
-        <module>git</module>
-        <module>import</module>
-        <module>lint</module>
-        <module>mail</module>
-        <module>marketplace</module>
-        <module>naming</module>
-        <module>passwords</module>
-        <module>projects</module>
-        <module>py4j</module>
-        <module>reflection</module>
-        <module>rest</module>
-        <module>setup</module>
-        <module>static-schema</module>
-        <module>testing</module>
-    </modules>
+    <artifactId>hop-misc-annotation</artifactId>
+    <packaging>jar</packaging>
+    <name>Hop Plugins Miscellaneous Annotation</name>
 
 </project>
diff --git a/plugins/misc/annotation/src/assembly/assembly.xml 
b/plugins/misc/annotation/src/assembly/assembly.xml
new file mode 100644
index 0000000000..cb45b018b7
--- /dev/null
+++ b/plugins/misc/annotation/src/assembly/assembly.xml
@@ -0,0 +1,39 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one or more
+  ~ contributor license agreements.  See the NOTICE file distributed with
+  ~ this work for additional information regarding copyright ownership.
+  ~ The ASF licenses this file to You under the Apache License, Version 2.0
+  ~ (the "License"); you may not use this file except in compliance with
+  ~ the License.  You may obtain a copy of the License at
+  ~
+  ~       http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  ~
+  -->
+
+<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.2.0";
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+    xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.2.0 
http://maven.apache.org/xsd/assembly-2.2.0.xsd";>
+
+    <id>hop-misc-annotation</id>
+    <formats>
+        <format>zip</format>
+    </formats>
+    <baseDirectory>.</baseDirectory>
+    <files>
+        <file>
+            <source>${project.basedir}/src/main/resources/version.xml</source>
+            <outputDirectory>${hop.plugin.libdir}</outputDirectory>
+            <filtered>true</filtered>
+        </file>
+    </files>
+
+    <componentDescriptors>
+        
<componentDescriptor>${maven.multiModuleProjectDirectory}/assemblies/shared/hop-plugin-libs.xml</componentDescriptor>
+    </componentDescriptors>
+</assembly>
diff --git 
a/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/Annotation.java
 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/Annotation.java
new file mode 100644
index 0000000000..6cecbbea17
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/Annotation.java
@@ -0,0 +1,72 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import lombok.Getter;
+import lombok.Setter;
+import org.apache.hop.core.gui.plugin.GuiElementType;
+import org.apache.hop.core.gui.plugin.GuiPlugin;
+import org.apache.hop.core.gui.plugin.GuiWidgetElement;
+import org.apache.hop.core.gui.plugin.GuiWidgetGroupType;
+import org.apache.hop.metadata.api.HopMetadataProperty;
+
+/** Plain-text callout anchored to one transform or one workflow action. */
+@GuiPlugin
+@Getter
+@Setter
+public class Annotation {
+  public static final String GUI_PLUGIN_ELEMENT_PARENT_ID = "AnnotationDialog";
+
+  @GuiWidgetElement(
+      id = "annotation-text",
+      order = "0100",
+      type = GuiElementType.MULTI_LINE_TEXT,
+      multiLineTextHeight = 6,
+      variables = false,
+      label = "i18n::Annotation.Text.Label",
+      toolTip = "i18n::Annotation.Text.Tooltip",
+      parentId = GUI_PLUGIN_ELEMENT_PARENT_ID,
+      groupType = GuiWidgetGroupType.BOXES,
+      group = "i18n::Annotation.Group")
+  @HopMetadataProperty
+  private String text;
+
+  @GuiWidgetElement(
+      id = "annotation-placement",
+      order = "0200",
+      type = GuiElementType.COMBO,
+      label = "i18n::Annotation.Placement.Label",
+      toolTip = "i18n::Annotation.Placement.Tooltip",
+      parentId = GUI_PLUGIN_ELEMENT_PARENT_ID,
+      groupType = GuiWidgetGroupType.BOXES,
+      group = "i18n::Annotation.Group")
+  @HopMetadataProperty
+  private AnnotationPlacement placement = AnnotationPlacement.TOP;
+
+  @GuiWidgetElement(
+      id = "annotation-dashed-line",
+      order = "0300",
+      type = GuiElementType.CHECKBOX,
+      label = "i18n::Annotation.DashedLine.Label",
+      toolTip = "i18n::Annotation.DashedLine.Tooltip",
+      parentId = GUI_PLUGIN_ELEMENT_PARENT_ID,
+      groupType = GuiWidgetGroupType.BOXES,
+      group = "i18n::Annotation.Group")
+  @HopMetadataProperty
+  private boolean dashedLine = true;
+}
diff --git 
a/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationClicks.java
 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationClicks.java
new file mode 100644
index 0000000000..66138cf991
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationClicks.java
@@ -0,0 +1,254 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import org.apache.hop.core.IAttributes;
+import org.apache.hop.core.gui.AreaOwner;
+import org.apache.hop.core.variables.IVariables;
+import org.apache.hop.i18n.BaseMessages;
+import org.apache.hop.pipeline.PipelineMeta;
+import org.apache.hop.pipeline.transform.TransformMeta;
+import org.apache.hop.ui.core.dialog.ErrorDialog;
+import org.apache.hop.ui.hopgui.file.pipeline.HopGuiPipelineGraph;
+import 
org.apache.hop.ui.hopgui.file.pipeline.extension.HopGuiPipelineGraphExtension;
+import org.apache.hop.ui.hopgui.file.shared.ISnapshotUndoSupport;
+import org.apache.hop.ui.hopgui.file.workflow.HopGuiWorkflowGraph;
+import 
org.apache.hop.ui.hopgui.file.workflow.extension.HopGuiWorkflowGraphExtension;
+import org.apache.hop.workflow.WorkflowMeta;
+import org.apache.hop.workflow.action.ActionMeta;
+import org.eclipse.swt.events.MouseEvent;
+import org.eclipse.swt.widgets.Shell;
+
+/**
+ * Canvas clicks on an annotation callout. The callout sits outside the icon, 
so the click is
+ * claimed.
+ */
+public final class AnnotationClicks {
+  private static final Class<?> PKG = Annotation.class;
+
+  /**
+   * True after a press on a callout until the matching release. The UI thread 
is the only writer.
+   */
+  private static boolean calloutPressed;
+
+  private AnnotationClicks() {}
+
+  public static void pipelineMouseDown(HopGuiPipelineGraphExtension extension) 
{
+    if (!claim(
+        extension == null ? null : extension.getAreaOwner(),
+        extension == null ? null : extension.getEvent())) {
+      calloutPressed = false;
+      return;
+    }
+    extension.setPreventingDefault(true);
+    calloutPressed = true;
+    if (extension.getEvent().button != 1) {
+      return;
+    }
+    Object subject = ((AnnotationHit) 
extension.getAreaOwner().getParent()).subject();
+    if (subject instanceof TransformMeta transform) {
+      editTransform(extension.getPipelineGraph(), transform);
+    }
+  }
+
+  public static void pipelineMouseUp(HopGuiPipelineGraphExtension extension) {
+    if (extension == null) {
+      calloutPressed = false;
+      return;
+    }
+    swallowRelease(extension.getAreaOwner(), () -> 
extension.setPreventingDefault(true));
+  }
+
+  public static void pipelineDoubleClick(HopGuiPipelineGraphExtension 
extension) {
+    if (isCallout(extension == null ? null : extension.getAreaOwner())) {
+      extension.setPreventingDefault(true);
+    }
+  }
+
+  public static void workflowMouseDown(HopGuiWorkflowGraphExtension extension) 
{
+    if (!claim(
+        extension == null ? null : extension.getAreaOwner(),
+        extension == null ? null : extension.getEvent())) {
+      calloutPressed = false;
+      return;
+    }
+    extension.setPreventingDefault(true);
+    calloutPressed = true;
+    if (extension.getEvent().button != 1) {
+      return;
+    }
+    Object subject = ((AnnotationHit) 
extension.getAreaOwner().getParent()).subject();
+    if (subject instanceof ActionMeta action) {
+      editAction(extension.getWorkflowGraph(), action);
+    }
+  }
+
+  public static void workflowMouseUp(HopGuiWorkflowGraphExtension extension) {
+    if (extension == null) {
+      calloutPressed = false;
+      return;
+    }
+    swallowRelease(extension.getAreaOwner(), () -> 
extension.setPreventingDefault(true));
+  }
+
+  public static void workflowDoubleClick(HopGuiWorkflowGraphExtension 
extension) {
+    if (isCallout(extension == null ? null : extension.getAreaOwner())) {
+      extension.setPreventingDefault(true);
+    }
+  }
+
+  /**
+   * Opens the annotation dialog for a transform and records one undo step 
when the text or
+   * placement changes.
+   *
+   * @param graph the pipeline graph
+   * @param transform the transform to annotate
+   */
+  public static void editTransform(HopGuiPipelineGraph graph, TransformMeta 
transform) {
+    if (graph == null || transform == null) {
+      return;
+    }
+    PipelineMeta pipelineMeta = graph.getPipelineMeta();
+    edit(
+        graph,
+        pipelineMeta::setChanged,
+        transform,
+        graph.getShell(),
+        graph.getVariables(),
+        graph::redraw);
+  }
+
+  /**
+   * Opens the annotation dialog for an action and records one undo step when 
the text or placement
+   * changes.
+   *
+   * @param graph the workflow graph
+   * @param action the action to annotate
+   */
+  public static void editAction(HopGuiWorkflowGraph graph, ActionMeta action) {
+    if (graph == null || action == null) {
+      return;
+    }
+    WorkflowMeta workflowMeta = graph.getWorkflowMeta();
+    edit(
+        graph,
+        workflowMeta::setChanged,
+        action,
+        graph.getShell(),
+        graph.getVariables(),
+        graph::redraw);
+  }
+
+  /**
+   * Removes the annotation and records one undo step.
+   *
+   * @param graph undo and redraw target
+   * @param markChanged marks the file dirty
+   * @param holder transform or action
+   * @param redraw refreshes the canvas
+   */
+  public static void remove(
+      ISnapshotUndoSupport graph, Runnable markChanged, IAttributes holder, 
Runnable redraw) {
+    if (graph == null || holder == null || AnnotationStore.read(holder) == 
null) {
+      return;
+    }
+    byte[] before = graph.captureUndoSnapshot();
+    AnnotationStore.clear(holder);
+    graph.commitDialogUndo(before);
+    if (markChanged != null) {
+      markChanged.run();
+    }
+    if (redraw != null) {
+      redraw.run();
+    }
+  }
+
+  private static void edit(
+      ISnapshotUndoSupport undo,
+      Runnable markChanged,
+      IAttributes holder,
+      Shell shell,
+      IVariables variables,
+      Runnable redraw) {
+    try {
+      byte[] before = undo.captureUndoSnapshot();
+      Annotation existing = AnnotationStore.read(holder);
+      String beforeText = existing == null ? null : existing.getText();
+      AnnotationPlacement beforePlacement = existing == null ? null : 
existing.getPlacement();
+      boolean beforeDashed = existing == null || existing.isDashedLine();
+      Annotation editing = existing == null ? new Annotation() : existing;
+      AnnotationDialog dialog = new AnnotationDialog(shell, variables, 
editing);
+      if (!dialog.open()) {
+        return;
+      }
+      AnnotationStore.write(holder, editing);
+      if (same(beforeText, beforePlacement, beforeDashed, 
AnnotationStore.read(holder))) {
+        return;
+      }
+      undo.commitDialogUndo(before);
+      if (markChanged != null) {
+        markChanged.run();
+      }
+      if (redraw != null) {
+        redraw.run();
+      }
+    } catch (Exception exception) {
+      new ErrorDialog(
+          shell,
+          BaseMessages.getString(PKG, "AnnotationDialog.Error.Title"),
+          BaseMessages.getString(PKG, "AnnotationDialog.Error.Message"),
+          exception);
+    }
+  }
+
+  private static boolean same(
+      String beforeText,
+      AnnotationPlacement beforePlacement,
+      boolean beforeDashed,
+      Annotation after) {
+    boolean beforeBlank = beforeText == null || beforeText.isBlank();
+    boolean afterBlank = after == null || after.getText() == null || 
after.getText().isBlank();
+    if (beforeBlank || afterBlank) {
+      return beforeBlank && afterBlank;
+    }
+    AnnotationPlacement beforeSide =
+        beforePlacement == null ? AnnotationPlacement.TOP : beforePlacement;
+    AnnotationPlacement afterSide =
+        after.getPlacement() == null ? AnnotationPlacement.TOP : 
after.getPlacement();
+    boolean afterDashed = after.isDashedLine();
+    return beforeText.equals(after.getText())
+        && beforeSide == afterSide
+        && beforeDashed == afterDashed;
+  }
+
+  private static void swallowRelease(AreaOwner areaOwner, Runnable 
preventDefault) {
+    if (!calloutPressed && !isCallout(areaOwner)) {
+      return;
+    }
+    calloutPressed = false;
+    preventDefault.run();
+  }
+
+  private static boolean claim(AreaOwner areaOwner, MouseEvent event) {
+    return event != null && isCallout(areaOwner);
+  }
+
+  private static boolean isCallout(AreaOwner areaOwner) {
+    return areaOwner != null && areaOwner.getParent() instanceof AnnotationHit;
+  }
+}
diff --git 
a/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationDialog.java
 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationDialog.java
new file mode 100644
index 0000000000..cf8a1e307a
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationDialog.java
@@ -0,0 +1,102 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import org.apache.hop.core.variables.IVariables;
+import org.apache.hop.i18n.BaseMessages;
+import org.apache.hop.ui.core.PropsUi;
+import org.apache.hop.ui.core.dialog.BaseDialog;
+import org.apache.hop.ui.core.gui.GuiCompositeWidgets;
+import org.apache.hop.ui.core.gui.GuiResource;
+import org.apache.hop.ui.pipeline.transform.BaseTransformDialog;
+import org.eclipse.swt.SWT;
+import org.eclipse.swt.layout.FormLayout;
+import org.eclipse.swt.widgets.Button;
+import org.eclipse.swt.widgets.Dialog;
+import org.eclipse.swt.widgets.Shell;
+
+/** Edits the text and placement of one annotation. */
+public class AnnotationDialog extends Dialog {
+  private static final Class<?> PKG = Annotation.class;
+
+  private final IVariables variables;
+  private final Annotation annotation;
+  private Shell shell;
+  private GuiCompositeWidgets widgets;
+  private boolean accepted;
+
+  public AnnotationDialog(Shell parent, IVariables variables, Annotation 
annotation) {
+    super(parent, SWT.NONE);
+    this.variables = variables;
+    this.annotation = annotation;
+  }
+
+  /**
+   * Opens the dialog.
+   *
+   * @return true when the user confirms the edit
+   */
+  public boolean open() {
+    Shell parent = getParent();
+    shell =
+        new Shell(parent, SWT.DIALOG_TRIM | SWT.RESIZE | SWT.MAX | SWT.MIN | 
SWT.APPLICATION_MODAL);
+    shell.setText(BaseMessages.getString(PKG, "AnnotationDialog.Title"));
+    PropsUi.setLook(shell);
+    shell.setImage(GuiResource.getInstance().getImage("ui/images/note.svg"));
+    FormLayout layout = new FormLayout();
+    layout.marginWidth = PropsUi.getFormMargin();
+    layout.marginHeight = PropsUi.getFormMargin();
+    shell.setLayout(layout);
+
+    Button ok = new Button(shell, SWT.PUSH);
+    ok.setText(BaseMessages.getString("System.Button.OK"));
+    ok.addListener(SWT.Selection, event -> accept());
+
+    Button cancel = new Button(shell, SWT.PUSH);
+    cancel.setText(BaseMessages.getString("System.Button.Cancel"));
+    cancel.addListener(SWT.Selection, event -> discard());
+
+    BaseTransformDialog.positionBottomButtons(
+        shell, new Button[] {ok, cancel}, PropsUi.getMargin(), null);
+    shell.setDefaultButton(ok);
+
+    widgets =
+        GuiCompositeWidgets.addScrolledComposite(
+            shell, variables, null, ok, 
Annotation.GUI_PLUGIN_ELEMENT_PARENT_ID, annotation);
+
+    BaseDialog.defaultShellHandling(shell, event -> accept(), event -> 
discard(), false);
+    return accepted;
+  }
+
+  private void accept() {
+    if (shell == null || shell.isDisposed()) {
+      return;
+    }
+    widgets.getWidgetsContents(annotation, 
Annotation.GUI_PLUGIN_ELEMENT_PARENT_ID);
+    accepted = true;
+    shell.dispose();
+  }
+
+  private void discard() {
+    if (shell == null || shell.isDisposed()) {
+      return;
+    }
+    accepted = false;
+    shell.dispose();
+  }
+}
diff --git 
a/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationGeometry.java
 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationGeometry.java
new file mode 100644
index 0000000000..e42130e9c7
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationGeometry.java
@@ -0,0 +1,202 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.function.ToIntFunction;
+
+/** Places an annotation balloon outside the icon it is anchored to. */
+public final class AnnotationGeometry {
+  public static final int GAP_PX = 12;
+  public static final int PADDING_PX = 6;
+  public static final int MAX_TEXT_WIDTH_PX = 180;
+  public static final int RADIUS_PX = 8;
+
+  private AnnotationGeometry() {}
+
+  /** A rectangle in the same coordinate space as the icon. */
+  public record Bounds(int x, int y, int width, int height) {
+    public boolean overlaps(Bounds other) {
+      return x < other.x + other.width
+          && x + width > other.x
+          && y < other.y + other.height
+          && y + height > other.y;
+    }
+
+    public int centerX() {
+      return x + width / 2;
+    }
+
+    public int centerY() {
+      return y + height / 2;
+    }
+  }
+
+  /** A straight connector between two points. */
+  public record Segment(int x1, int y1, int x2, int y2) {}
+
+  /**
+   * Scales a pixel constant by the canvas magnification. A non-positive 
magnification is treated as
+   * 1.
+   *
+   * @param pixels the unscaled size
+   * @param magnification the canvas magnification
+   * @return at least 1
+   */
+  public static int scale(int pixels, float magnification) {
+    float factor = magnification > 0f ? magnification : 1f;
+    return Math.max(1, Math.round(pixels * factor));
+  }
+
+  /**
+   * Balloon rectangle for the measured text. Padding is added here. The text 
size is the wrapped
+   * block, not including padding.
+   *
+   * @param icon icon rectangle
+   * @param textWidth wrapped text width
+   * @param textHeight wrapped text height
+   * @param placement where the balloon sits; null is {@link 
AnnotationPlacement#TOP}
+   * @param magnification canvas magnification
+   * @return the balloon, fully outside the icon when the gap is positive
+   */
+  public static Bounds balloon(
+      Bounds icon,
+      int textWidth,
+      int textHeight,
+      AnnotationPlacement placement,
+      float magnification) {
+    int gap = scale(GAP_PX, magnification);
+    int padding = scale(PADDING_PX, magnification);
+    int width = Math.max(0, textWidth) + 2 * padding;
+    int height = Math.max(0, textHeight) + 2 * padding;
+    AnnotationPlacement side = placement == null ? AnnotationPlacement.TOP : 
placement;
+    int x =
+        switch (side) {
+          case TOP, BOTTOM -> icon.centerX() - width / 2;
+          case TOP_RIGHT, RIGHT, BOTTOM_RIGHT -> icon.x + icon.width + gap;
+          case TOP_LEFT, LEFT, BOTTOM_LEFT -> icon.x - gap - width;
+        };
+    int y =
+        switch (side) {
+          case TOP, TOP_LEFT, TOP_RIGHT -> icon.y - gap - height;
+          case LEFT, RIGHT -> icon.centerY() - height / 2;
+          case BOTTOM, BOTTOM_LEFT, BOTTOM_RIGHT -> icon.y + icon.height + gap;
+        };
+    return new Bounds(x, y, width, height);
+  }
+
+  /**
+   * Dashed connector from the balloon edge to the icon edge. Each end is the 
point on that
+   * rectangle closest to the other rectangle's center.
+   *
+   * @param balloon the callout rectangle
+   * @param icon the transform or action icon
+   * @return the segment to draw
+   */
+  public static Segment connector(Bounds balloon, Bounds icon) {
+    int[] from = nearestPoint(balloon, icon.centerX(), icon.centerY());
+    int[] to = nearestPoint(icon, balloon.centerX(), balloon.centerY());
+    return new Segment(from[0], from[1], to[0], to[1]);
+  }
+
+  private static int[] nearestPoint(Bounds rect, int px, int py) {
+    int x = Math.min(Math.max(px, rect.x()), rect.x() + rect.width());
+    int y = Math.min(Math.max(py, rect.y()), rect.y() + rect.height());
+    return new int[] {x, y};
+  }
+
+  /**
+   * Wraps text to a maximum width. Existing line breaks are kept. A word 
wider than the limit is
+   * split by character.
+   *
+   * @param text the annotation text
+   * @param maxWidth maximum line width in the same units as {@code widthOf}
+   * @param widthOf measures one line
+   * @return the wrapped lines, or an empty list when the text is blank
+   */
+  public static List<String> wrap(String text, int maxWidth, 
ToIntFunction<String> widthOf) {
+    if (text == null || text.isBlank()) {
+      return List.of();
+    }
+    int limit = Math.max(1, maxWidth);
+    List<String> lines = new ArrayList<>();
+    for (String paragraph : text.split("\\R", -1)) {
+      if (paragraph.isEmpty() || widthOf.applyAsInt(paragraph) <= limit) {
+        lines.add(paragraph);
+      } else {
+        lines.addAll(wrapParagraph(paragraph, limit, widthOf));
+      }
+    }
+    return lines;
+  }
+
+  private static List<String> wrapParagraph(
+      String paragraph, int limit, ToIntFunction<String> widthOf) {
+    List<String> lines = new ArrayList<>();
+    StringBuilder current = new StringBuilder();
+    for (String word : paragraph.split(" ", -1)) {
+      if (word.isEmpty()) {
+        continue;
+      }
+      if (widthOf.applyAsInt(word) > limit) {
+        flush(lines, current);
+        lines.addAll(breakWord(word, limit, widthOf));
+        continue;
+      }
+      if (current.isEmpty()) {
+        current.append(word);
+        continue;
+      }
+      String candidate = current + " " + word;
+      if (widthOf.applyAsInt(candidate) <= limit) {
+        current.append(' ').append(word);
+      } else {
+        flush(lines, current);
+        current.append(word);
+      }
+    }
+    flush(lines, current);
+    return lines;
+  }
+
+  private static List<String> breakWord(String word, int limit, 
ToIntFunction<String> widthOf) {
+    List<String> parts = new ArrayList<>();
+    StringBuilder current = new StringBuilder();
+    for (int i = 0; i < word.length(); i++) {
+      current.append(word.charAt(i));
+      if (widthOf.applyAsInt(current.toString()) > limit && current.length() > 
1) {
+        current.setLength(current.length() - 1);
+        parts.add(current.toString());
+        current.setLength(0);
+        current.append(word.charAt(i));
+      }
+    }
+    if (!current.isEmpty()) {
+      parts.add(current.toString());
+    }
+    return parts;
+  }
+
+  private static void flush(List<String> lines, StringBuilder current) {
+    if (!current.isEmpty()) {
+      lines.add(current.toString());
+      current.setLength(0);
+    }
+  }
+}
diff --git 
a/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationGuiPlugin.java
 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationGuiPlugin.java
new file mode 100644
index 0000000000..b84ae65515
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationGuiPlugin.java
@@ -0,0 +1,111 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import org.apache.hop.core.action.GuiContextAction;
+import org.apache.hop.core.action.GuiContextActionFilter;
+import org.apache.hop.core.gui.plugin.GuiPlugin;
+import org.apache.hop.core.gui.plugin.action.GuiActionType;
+import org.apache.hop.ui.hopgui.file.pipeline.HopGuiPipelineGraph;
+import 
org.apache.hop.ui.hopgui.file.pipeline.context.HopGuiPipelineTransformContext;
+import org.apache.hop.ui.hopgui.file.workflow.HopGuiWorkflowGraph;
+import 
org.apache.hop.ui.hopgui.file.workflow.context.HopGuiWorkflowActionContext;
+
+/** Context actions that add, edit, and remove an annotation. */
+@GuiPlugin
+public class AnnotationGuiPlugin {
+  static final String ACTION_ANNOTATE_TRANSFORM = 
"pipeline-graph-transform-12000-annotate";
+  static final String ACTION_REMOVE_TRANSFORM = 
"pipeline-graph-transform-12001-remove-annotation";
+  static final String ACTION_ANNOTATE_ACTION = 
"workflow-graph-action-12000-annotate";
+  static final String ACTION_REMOVE_ACTION = 
"workflow-graph-action-12001-remove-annotation";
+
+  @GuiContextAction(
+      id = ACTION_ANNOTATE_TRANSFORM,
+      parentId = HopGuiPipelineTransformContext.CONTEXT_ID,
+      type = GuiActionType.Modify,
+      name = "i18n::AnnotationGuiPlugin.Annotate.Name",
+      tooltip = "i18n::AnnotationGuiPlugin.Annotate.Tooltip",
+      image = "ui/images/note.svg",
+      category = "i18n::AnnotationGuiPlugin.Category",
+      categoryOrder = "9")
+  public void annotateTransform(HopGuiPipelineTransformContext context) {
+    HopGuiPipelineGraph graph = context.getPipelineGraph();
+    AnnotationClicks.editTransform(graph, context.getTransformMeta());
+  }
+
+  @GuiContextAction(
+      id = ACTION_REMOVE_TRANSFORM,
+      parentId = HopGuiPipelineTransformContext.CONTEXT_ID,
+      type = GuiActionType.Delete,
+      name = "i18n::AnnotationGuiPlugin.Remove.Name",
+      tooltip = "i18n::AnnotationGuiPlugin.Remove.Tooltip",
+      image = "ui/images/note.svg",
+      category = "i18n::AnnotationGuiPlugin.Category",
+      categoryOrder = "9")
+  public void removeTransformAnnotation(HopGuiPipelineTransformContext 
context) {
+    HopGuiPipelineGraph graph = context.getPipelineGraph();
+    AnnotationClicks.remove(
+        graph, context.getPipelineMeta()::setChanged, 
context.getTransformMeta(), graph::redraw);
+  }
+
+  @GuiContextActionFilter(parentId = HopGuiPipelineTransformContext.CONTEXT_ID)
+  public boolean filterTransformActions(
+      String contextActionId, HopGuiPipelineTransformContext context) {
+    if (!ACTION_REMOVE_TRANSFORM.equals(contextActionId)) {
+      return true;
+    }
+    return AnnotationStore.read(context.getTransformMeta()) != null;
+  }
+
+  @GuiContextAction(
+      id = ACTION_ANNOTATE_ACTION,
+      parentId = HopGuiWorkflowActionContext.CONTEXT_ID,
+      type = GuiActionType.Modify,
+      name = "i18n::AnnotationGuiPlugin.Annotate.Name",
+      tooltip = "i18n::AnnotationGuiPlugin.Annotate.Tooltip",
+      image = "ui/images/note.svg",
+      category = "i18n::AnnotationGuiPlugin.Category",
+      categoryOrder = "9")
+  public void annotateAction(HopGuiWorkflowActionContext context) {
+    HopGuiWorkflowGraph graph = context.getWorkflowGraph();
+    AnnotationClicks.editAction(graph, context.getActionMeta());
+  }
+
+  @GuiContextAction(
+      id = ACTION_REMOVE_ACTION,
+      parentId = HopGuiWorkflowActionContext.CONTEXT_ID,
+      type = GuiActionType.Delete,
+      name = "i18n::AnnotationGuiPlugin.Remove.Name",
+      tooltip = "i18n::AnnotationGuiPlugin.Remove.Tooltip",
+      image = "ui/images/note.svg",
+      category = "i18n::AnnotationGuiPlugin.Category",
+      categoryOrder = "9")
+  public void removeActionAnnotation(HopGuiWorkflowActionContext context) {
+    HopGuiWorkflowGraph graph = context.getWorkflowGraph();
+    AnnotationClicks.remove(
+        graph, context.getWorkflowMeta()::setChanged, context.getActionMeta(), 
graph::redraw);
+  }
+
+  @GuiContextActionFilter(parentId = HopGuiWorkflowActionContext.CONTEXT_ID)
+  public boolean filterActionActions(String contextActionId, 
HopGuiWorkflowActionContext context) {
+    if (!ACTION_REMOVE_ACTION.equals(contextActionId)) {
+      return true;
+    }
+    return AnnotationStore.read(context.getActionMeta()) != null;
+  }
+}
diff --git 
a/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationHit.java
 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationHit.java
new file mode 100644
index 0000000000..83560d0d3d
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationHit.java
@@ -0,0 +1,26 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+/**
+ * Marks a canvas {@code CUSTOM} area as an annotation callout. Other plugins 
also register {@code
+ * CUSTOM} areas, so the parent object is what tells a click apart from a bee 
or a unit-test marker.
+ *
+ * @param subject the {@code TransformMeta} or {@code ActionMeta} the callout 
is anchored to
+ */
+public record AnnotationHit(Object subject) {}
diff --git 
a/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationPainter.java
 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationPainter.java
new file mode 100644
index 0000000000..ff8703b448
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationPainter.java
@@ -0,0 +1,133 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import java.util.List;
+import org.apache.hop.annotation.AnnotationGeometry.Bounds;
+import org.apache.hop.core.NotePadType;
+import org.apache.hop.core.gui.AreaOwner;
+import org.apache.hop.core.gui.DPoint;
+import org.apache.hop.core.gui.IGc;
+import org.apache.hop.core.gui.NotePadStyle;
+import org.apache.hop.core.gui.NotePadStyle.RgbColor;
+
+/** Draws one annotation callout and registers its click area. */
+public final class AnnotationPainter {
+  private AnnotationPainter() {}
+
+  /**
+   * Draws the annotation next to the icon. A blank annotation draws nothing. 
Colors come from the
+   * note General palette, which follows {@link NotePadStyle#isDarkMode()}.
+   *
+   * @param gc canvas graphics
+   * @param areaOwners areas hit-testing reads
+   * @param offset canvas scroll offset subtracted from the click area
+   * @param subject transform or action the callout belongs to
+   * @param iconX icon left, in the same space {@code gc} is drawing in
+   * @param iconY icon top
+   * @param iconSize icon width and height
+   * @param selected true when the owner is selected
+   * @param annotation the annotation, or null
+   */
+  public static void paint(
+      IGc gc,
+      List<AreaOwner> areaOwners,
+      DPoint offset,
+      Object subject,
+      int iconX,
+      int iconY,
+      int iconSize,
+      boolean selected,
+      Annotation annotation) {
+    if (gc == null || areaOwners == null || subject == null || annotation == 
null) {
+      return;
+    }
+    String text = annotation.getText();
+    if (text == null || text.isBlank()) {
+      return;
+    }
+
+    gc.setFont(IGc.EFont.NOTE);
+    float magnification = gc.getMagnification();
+    int maxWidth = 
AnnotationGeometry.scale(AnnotationGeometry.MAX_TEXT_WIDTH_PX, magnification);
+    List<String> lines = AnnotationGeometry.wrap(text, maxWidth, line -> 
gc.textExtent(line).x);
+    if (lines.isEmpty()) {
+      return;
+    }
+
+    int textWidth = 0;
+    for (String line : lines) {
+      textWidth = Math.max(textWidth, gc.textExtent(line).x);
+    }
+    int lineHeight = gc.getFontHeight();
+    if (lineHeight <= 0) {
+      lineHeight = Math.max(1, gc.textExtent("Ag").y);
+    }
+    int textHeight = lines.size() * lineHeight;
+    Bounds icon = new Bounds(iconX, iconY, iconSize, iconSize);
+    Bounds balloon =
+        AnnotationGeometry.balloon(
+            icon, textWidth, textHeight, annotation.getPlacement(), 
magnification);
+
+    RgbColor background = NotePadStyle.backgroundColor(NotePadType.GENERAL);
+    RgbColor border = NotePadStyle.borderColor(NotePadType.GENERAL);
+    RgbColor foreground = NotePadStyle.textColor(NotePadType.GENERAL);
+    int radius = AnnotationGeometry.scale(AnnotationGeometry.RADIUS_PX, 
magnification);
+
+    if (annotation.isDashedLine()) {
+      AnnotationGeometry.Segment connector = 
AnnotationGeometry.connector(balloon, icon);
+      gc.setForeground(border.red(), border.green(), border.blue());
+      gc.setLineWidth(1);
+      gc.setLineStyle(IGc.ELineStyle.DASH);
+      gc.drawLine(connector.x1(), connector.y1(), connector.x2(), 
connector.y2());
+      gc.setLineStyle(IGc.ELineStyle.SOLID);
+    }
+
+    gc.setBackground(background.red(), background.green(), background.blue());
+    gc.setForeground(border.red(), border.green(), border.blue());
+    gc.setLineWidth(NotePadStyle.borderWidth(NotePadType.GENERAL, selected));
+    gc.fillRoundRectangle(
+        balloon.x(), balloon.y(), balloon.width(), balloon.height(), radius, 
radius);
+    gc.drawRoundRectangle(
+        balloon.x(), balloon.y(), balloon.width(), balloon.height(), radius, 
radius);
+
+    gc.setForeground(foreground.red(), foreground.green(), foreground.blue());
+    int padding = AnnotationGeometry.scale(AnnotationGeometry.PADDING_PX, 
magnification);
+    int textX = balloon.x() + padding;
+    int textY = balloon.y() + padding;
+    for (int i = 0; i < lines.size(); i++) {
+      String line = lines.get(i);
+      if (!line.isEmpty()) {
+        gc.drawText(line, textX, textY + i * lineHeight, true);
+      }
+    }
+    gc.setLineWidth(1);
+
+    DPoint areaOffset = offset == null ? new DPoint(0, 0) : offset;
+    areaOwners.add(
+        new AreaOwner(
+            AreaOwner.AreaType.CUSTOM,
+            balloon.x(),
+            balloon.y(),
+            balloon.width(),
+            balloon.height(),
+            areaOffset,
+            new AnnotationHit(subject),
+            subject));
+  }
+}
diff --git 
a/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationPlacement.java
 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationPlacement.java
new file mode 100644
index 0000000000..72a6d827e5
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationPlacement.java
@@ -0,0 +1,54 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import org.apache.hop.i18n.BaseMessages;
+import org.apache.hop.metadata.api.IEnumHasCode;
+import org.apache.hop.metadata.api.IEnumHasCodeAndDescription;
+
+/** Where a callout sits relative to the transform or action icon it is 
anchored to. */
+public enum AnnotationPlacement implements IEnumHasCodeAndDescription {
+  TOP,
+  TOP_RIGHT,
+  RIGHT,
+  BOTTOM_RIGHT,
+  BOTTOM,
+  BOTTOM_LEFT,
+  LEFT,
+  TOP_LEFT;
+
+  @Override
+  public String getCode() {
+    return name();
+  }
+
+  @Override
+  public String getDescription() {
+    return BaseMessages.getString(AnnotationPlacement.class, 
"AnnotationPlacement." + name());
+  }
+
+  /**
+   * Placement stored on the transform or action. An unknown or empty code is 
{@link #TOP}.
+   *
+   * @param code the stored code, or null
+   * @return the matching placement
+   */
+  public static AnnotationPlacement fromCode(String code) {
+    return IEnumHasCode.lookupCode(AnnotationPlacement.class, code, TOP);
+  }
+}
diff --git 
a/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationStore.java
 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationStore.java
new file mode 100644
index 0000000000..59235218a2
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/AnnotationStore.java
@@ -0,0 +1,99 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import java.util.HashMap;
+import java.util.Map;
+import org.apache.hop.core.IAttributes;
+
+/** Reads and writes one annotation on a transform or action attribute map. */
+public final class AnnotationStore {
+  public static final String GROUP = "annotation";
+  static final String KEY_TEXT = "text";
+  static final String KEY_PLACEMENT = "placement";
+  static final String KEY_DASHED_LINE = "dashed-line";
+
+  private AnnotationStore() {}
+
+  /**
+   * @param holder the transform or action, or null
+   * @return the annotation, or null when there is none or the text is blank
+   */
+  public static Annotation read(IAttributes holder) {
+    if (holder == null) {
+      return null;
+    }
+    Map<String, String> group = holder.getAttributes(GROUP);
+    if (group == null) {
+      return null;
+    }
+    String text = group.get(KEY_TEXT);
+    if (isBlank(text)) {
+      return null;
+    }
+    Annotation annotation = new Annotation();
+    annotation.setText(text);
+    
annotation.setPlacement(AnnotationPlacement.fromCode(group.get(KEY_PLACEMENT)));
+    // A missing key stays connected. Annotations saved before the option 
existed get the line.
+    
annotation.setDashedLine(!"N".equalsIgnoreCase(group.get(KEY_DASHED_LINE)));
+    return annotation;
+  }
+
+  /**
+   * Stores the annotation on a new group map. A blank text removes the group. 
Replacing the map
+   * leaves a shallow clone, such as {@code ActionMeta.clone()}, holding the 
previous values.
+   *
+   * @param holder the transform or action
+   * @param annotation the annotation to store, or null to remove it
+   */
+  public static void write(IAttributes holder, Annotation annotation) {
+    if (holder == null) {
+      return;
+    }
+    if (annotation == null || isBlank(annotation.getText())) {
+      clear(holder);
+      return;
+    }
+    AnnotationPlacement placement =
+        annotation.getPlacement() == null ? AnnotationPlacement.TOP : 
annotation.getPlacement();
+    Map<String, String> group = new HashMap<>();
+    group.put(KEY_TEXT, annotation.getText());
+    group.put(KEY_PLACEMENT, placement.getCode());
+    group.put(KEY_DASHED_LINE, annotation.isDashedLine() ? "Y" : "N");
+    holder.setAttributes(GROUP, group);
+  }
+
+  /**
+   * Removes the annotation group.
+   *
+   * @param holder the transform or action
+   */
+  public static void clear(IAttributes holder) {
+    if (holder == null) {
+      return;
+    }
+    Map<String, Map<String, String>> attributes = holder.getAttributesMap();
+    if (attributes != null) {
+      attributes.remove(GROUP);
+    }
+  }
+
+  private static boolean isBlank(String text) {
+    return text == null || text.isBlank();
+  }
+}
diff --git 
a/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/DrawActionAnnotationExtensionPoint.java
 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/DrawActionAnnotationExtensionPoint.java
new file mode 100644
index 0000000000..638671c713
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/DrawActionAnnotationExtensionPoint.java
@@ -0,0 +1,53 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import org.apache.hop.core.extension.ExtensionPoint;
+import org.apache.hop.core.extension.IExtensionPoint;
+import org.apache.hop.core.logging.ILogChannel;
+import org.apache.hop.core.variables.IVariables;
+import org.apache.hop.workflow.WorkflowPainterExtension;
+import org.apache.hop.workflow.action.ActionMeta;
+
+/** Draws the annotation anchored to a workflow action. */
+@ExtensionPoint(
+    id = "DrawActionAnnotationExtensionPoint",
+    extensionPointId = "WorkflowPainterAction",
+    description = "Draw an annotation callout next to a workflow action")
+public class DrawActionAnnotationExtensionPoint
+    implements IExtensionPoint<WorkflowPainterExtension> {
+
+  @Override
+  public void callExtensionPoint(
+      ILogChannel log, IVariables variables, WorkflowPainterExtension 
extension) {
+    if (extension == null || extension.actionMeta == null) {
+      return;
+    }
+    ActionMeta action = extension.actionMeta;
+    AnnotationPainter.paint(
+        extension.gc,
+        extension.areaOwners,
+        extension.offset,
+        action,
+        extension.x1,
+        extension.y1,
+        extension.iconSize,
+        action.isSelected(),
+        AnnotationStore.read(action));
+  }
+}
diff --git 
a/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/DrawTransformAnnotationExtensionPoint.java
 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/DrawTransformAnnotationExtensionPoint.java
new file mode 100644
index 0000000000..6c4060d109
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/DrawTransformAnnotationExtensionPoint.java
@@ -0,0 +1,53 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import org.apache.hop.core.extension.ExtensionPoint;
+import org.apache.hop.core.extension.IExtensionPoint;
+import org.apache.hop.core.logging.ILogChannel;
+import org.apache.hop.core.variables.IVariables;
+import org.apache.hop.pipeline.PipelinePainterExtension;
+import org.apache.hop.pipeline.transform.TransformMeta;
+
+/** Draws the annotation anchored to a pipeline transform. */
+@ExtensionPoint(
+    id = "DrawTransformAnnotationExtensionPoint",
+    extensionPointId = "PipelinePainterTransform",
+    description = "Draw an annotation callout next to a pipeline transform")
+public class DrawTransformAnnotationExtensionPoint
+    implements IExtensionPoint<PipelinePainterExtension> {
+
+  @Override
+  public void callExtensionPoint(
+      ILogChannel log, IVariables variables, PipelinePainterExtension 
extension) {
+    if (extension == null || extension.transformMeta == null) {
+      return;
+    }
+    TransformMeta transform = extension.transformMeta;
+    AnnotationPainter.paint(
+        extension.gc,
+        extension.areaOwners,
+        extension.offset,
+        transform,
+        extension.x1,
+        extension.y1,
+        extension.iconSize,
+        transform.isSelected(),
+        AnnotationStore.read(transform));
+  }
+}
diff --git 
a/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/PipelineAnnotationMouseExtensionPoints.java
 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/PipelineAnnotationMouseExtensionPoints.java
new file mode 100644
index 0000000000..166b0c6e3f
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/PipelineAnnotationMouseExtensionPoints.java
@@ -0,0 +1,65 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import org.apache.hop.core.extension.ExtensionPoint;
+import org.apache.hop.core.extension.IExtensionPoint;
+import org.apache.hop.core.logging.ILogChannel;
+import org.apache.hop.core.variables.IVariables;
+import 
org.apache.hop.ui.hopgui.file.pipeline.extension.HopGuiPipelineGraphExtension;
+
+/** Mouse extension points for a pipeline annotation. Each class is one 
extension point. */
+final class PipelineAnnotationMouseExtensionPoints {
+  private PipelineAnnotationMouseExtensionPoints() {}
+
+  @ExtensionPoint(
+      id = "PipelineAnnotationMouseDownExtensionPoint",
+      extensionPointId = "PipelineGraphMouseDown",
+      description = "Edit an annotation when its callout is clicked on a 
pipeline")
+  public static class MouseDown implements 
IExtensionPoint<HopGuiPipelineGraphExtension> {
+    @Override
+    public void callExtensionPoint(
+        ILogChannel log, IVariables variables, HopGuiPipelineGraphExtension 
extension) {
+      AnnotationClicks.pipelineMouseDown(extension);
+    }
+  }
+
+  @ExtensionPoint(
+      id = "PipelineAnnotationMouseUpExtensionPoint",
+      extensionPointId = "PipelineGraphMouseUp",
+      description = "Keep a pipeline annotation click from acting as a canvas 
click")
+  public static class MouseUp implements 
IExtensionPoint<HopGuiPipelineGraphExtension> {
+    @Override
+    public void callExtensionPoint(
+        ILogChannel log, IVariables variables, HopGuiPipelineGraphExtension 
extension) {
+      AnnotationClicks.pipelineMouseUp(extension);
+    }
+  }
+
+  @ExtensionPoint(
+      id = "PipelineAnnotationMouseDoubleClickExtensionPoint",
+      extensionPointId = "PipelineGraphMouseDoubleClick",
+      description = "Keep a pipeline annotation double-click from opening the 
pipeline properties")
+  public static class MouseDoubleClick implements 
IExtensionPoint<HopGuiPipelineGraphExtension> {
+    @Override
+    public void callExtensionPoint(
+        ILogChannel log, IVariables variables, HopGuiPipelineGraphExtension 
extension) {
+      AnnotationClicks.pipelineDoubleClick(extension);
+    }
+  }
+}
diff --git 
a/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/WorkflowAnnotationMouseExtensionPoints.java
 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/WorkflowAnnotationMouseExtensionPoints.java
new file mode 100644
index 0000000000..d3ac54a29f
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/java/org/apache/hop/annotation/WorkflowAnnotationMouseExtensionPoints.java
@@ -0,0 +1,65 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import org.apache.hop.core.extension.ExtensionPoint;
+import org.apache.hop.core.extension.IExtensionPoint;
+import org.apache.hop.core.logging.ILogChannel;
+import org.apache.hop.core.variables.IVariables;
+import 
org.apache.hop.ui.hopgui.file.workflow.extension.HopGuiWorkflowGraphExtension;
+
+/** Mouse extension points for a workflow annotation. Each class is one 
extension point. */
+final class WorkflowAnnotationMouseExtensionPoints {
+  private WorkflowAnnotationMouseExtensionPoints() {}
+
+  @ExtensionPoint(
+      id = "WorkflowAnnotationMouseDownExtensionPoint",
+      extensionPointId = "WorkflowGraphMouseDown",
+      description = "Edit an annotation when its callout is clicked on a 
workflow")
+  public static class MouseDown implements 
IExtensionPoint<HopGuiWorkflowGraphExtension> {
+    @Override
+    public void callExtensionPoint(
+        ILogChannel log, IVariables variables, HopGuiWorkflowGraphExtension 
extension) {
+      AnnotationClicks.workflowMouseDown(extension);
+    }
+  }
+
+  @ExtensionPoint(
+      id = "WorkflowAnnotationMouseUpExtensionPoint",
+      extensionPointId = "WorkflowGraphMouseUp",
+      description = "Keep a workflow annotation click from acting as a canvas 
click")
+  public static class MouseUp implements 
IExtensionPoint<HopGuiWorkflowGraphExtension> {
+    @Override
+    public void callExtensionPoint(
+        ILogChannel log, IVariables variables, HopGuiWorkflowGraphExtension 
extension) {
+      AnnotationClicks.workflowMouseUp(extension);
+    }
+  }
+
+  @ExtensionPoint(
+      id = "WorkflowAnnotationMouseDoubleClickExtensionPoint",
+      extensionPointId = "WorkflowGraphMouseDoubleClick",
+      description = "Keep a workflow annotation double-click from opening the 
workflow properties")
+  public static class MouseDoubleClick implements 
IExtensionPoint<HopGuiWorkflowGraphExtension> {
+    @Override
+    public void callExtensionPoint(
+        ILogChannel log, IVariables variables, HopGuiWorkflowGraphExtension 
extension) {
+      AnnotationClicks.workflowDoubleClick(extension);
+    }
+  }
+}
diff --git 
a/plugins/misc/annotation/src/main/resources/org/apache/hop/annotation/messages/messages_en_US.properties
 
b/plugins/misc/annotation/src/main/resources/org/apache/hop/annotation/messages/messages_en_US.properties
new file mode 100644
index 0000000000..5d260c8311
--- /dev/null
+++ 
b/plugins/misc/annotation/src/main/resources/org/apache/hop/annotation/messages/messages_en_US.properties
@@ -0,0 +1,42 @@
+#
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+#
+
+Annotation.Group=Annotation
+Annotation.Text.Label=Text
+Annotation.Text.Tooltip=Plain text shown next to this transform or action
+Annotation.Placement.Label=Position
+Annotation.Placement.Tooltip=Where the annotation sits relative to the icon
+Annotation.DashedLine.Label=Dashed line
+Annotation.DashedLine.Tooltip=Draw a dashed line from this annotation to the 
transform or action
+AnnotationDialog.Title=Annotation
+AnnotationDialog.Error.Title=Error
+AnnotationDialog.Error.Message=Error editing the annotation
+AnnotationGuiPlugin.Category=Documentation
+AnnotationGuiPlugin.Annotate.Name=Annotate
+AnnotationGuiPlugin.Annotate.Tooltip=Add or edit the annotation on this 
transform or action
+AnnotationGuiPlugin.Remove.Name=Remove annotation
+AnnotationGuiPlugin.Remove.Tooltip=Remove the annotation from this transform 
or action
+AnnotationPlacement.TOP=Top
+AnnotationPlacement.TOP_RIGHT=Top right
+AnnotationPlacement.RIGHT=Right
+AnnotationPlacement.BOTTOM_RIGHT=Bottom right
+AnnotationPlacement.BOTTOM=Bottom
+AnnotationPlacement.BOTTOM_LEFT=Bottom left
+AnnotationPlacement.LEFT=Left
+AnnotationPlacement.TOP_LEFT=Top left
diff --git a/plugins/misc/annotation/src/main/resources/version.xml 
b/plugins/misc/annotation/src/main/resources/version.xml
new file mode 100644
index 0000000000..36ab20e22e
--- /dev/null
+++ b/plugins/misc/annotation/src/main/resources/version.xml
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one or more
+  ~ contributor license agreements.  See the NOTICE file distributed with
+  ~ this work for additional information regarding copyright ownership.
+  ~ The ASF licenses this file to You under the Apache License, Version 2.0
+  ~ (the "License"); you may not use this file except in compliance with
+  ~ the License.  You may obtain a copy of the License at
+  ~
+  ~       http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  ~
+  -->
+
+<version>${project.version}</version>
diff --git 
a/plugins/misc/annotation/src/test/java/org/apache/hop/annotation/AnnotationGeometryTest.java
 
b/plugins/misc/annotation/src/test/java/org/apache/hop/annotation/AnnotationGeometryTest.java
new file mode 100644
index 0000000000..24d6d1157e
--- /dev/null
+++ 
b/plugins/misc/annotation/src/test/java/org/apache/hop/annotation/AnnotationGeometryTest.java
@@ -0,0 +1,123 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+import org.apache.hop.annotation.AnnotationGeometry.Bounds;
+import org.apache.hop.annotation.AnnotationGeometry.Segment;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
+
+class AnnotationGeometryTest {
+
+  private static final Bounds ICON = new Bounds(100, 80, 32, 32);
+
+  @ParameterizedTest
+  @EnumSource(AnnotationPlacement.class)
+  void balloonSitsOutsideTheIconOnThatSide(AnnotationPlacement placement) {
+    int gap = AnnotationGeometry.scale(AnnotationGeometry.GAP_PX, 1f);
+    Bounds balloon = AnnotationGeometry.balloon(ICON, 40, 16, placement, 1f);
+
+    assertFalse(balloon.overlaps(ICON));
+    assertEquals(
+        40 + 2 * AnnotationGeometry.scale(AnnotationGeometry.PADDING_PX, 1f), 
balloon.width());
+    switch (placement) {
+      case TOP -> {
+        assertEquals(ICON.y(), balloon.y() + balloon.height() + gap);
+        assertEquals(ICON.centerX(), balloon.centerX());
+      }
+      case BOTTOM -> {
+        assertEquals(ICON.y() + ICON.height() + gap, balloon.y());
+        assertEquals(ICON.centerX(), balloon.centerX());
+      }
+      case LEFT -> {
+        assertEquals(ICON.x(), balloon.x() + balloon.width() + gap);
+        assertEquals(ICON.centerY(), balloon.centerY());
+      }
+      case RIGHT -> {
+        assertEquals(ICON.x() + ICON.width() + gap, balloon.x());
+        assertEquals(ICON.centerY(), balloon.centerY());
+      }
+      case TOP_LEFT -> {
+        assertEquals(ICON.x(), balloon.x() + balloon.width() + gap);
+        assertEquals(ICON.y(), balloon.y() + balloon.height() + gap);
+      }
+      case TOP_RIGHT -> {
+        assertEquals(ICON.x() + ICON.width() + gap, balloon.x());
+        assertEquals(ICON.y(), balloon.y() + balloon.height() + gap);
+      }
+      case BOTTOM_LEFT -> {
+        assertEquals(ICON.x(), balloon.x() + balloon.width() + gap);
+        assertEquals(ICON.y() + ICON.height() + gap, balloon.y());
+      }
+      case BOTTOM_RIGHT -> {
+        assertEquals(ICON.x() + ICON.width() + gap, balloon.x());
+        assertEquals(ICON.y() + ICON.height() + gap, balloon.y());
+      }
+      default -> throw new IllegalStateException(placement.name());
+    }
+  }
+
+  @Test
+  void magnifiedGapMovesTheBalloonFurtherFromTheIcon() {
+    Bounds near = AnnotationGeometry.balloon(ICON, 20, 10, 
AnnotationPlacement.TOP, 1f);
+    Bounds far = AnnotationGeometry.balloon(ICON, 20, 10, 
AnnotationPlacement.TOP, 2f);
+    int gap = AnnotationGeometry.scale(AnnotationGeometry.GAP_PX, 2f);
+
+    assertEquals(24, gap);
+    assertEquals(ICON.y(), far.y() + far.height() + gap);
+    assertTrue(far.y() < near.y());
+  }
+
+  @Test
+  void connectorJoinsTheFacingEdges() {
+    Bounds above = AnnotationGeometry.balloon(ICON, 40, 16, 
AnnotationPlacement.TOP, 1f);
+    Segment vertical = AnnotationGeometry.connector(above, ICON);
+    assertEquals(above.centerX(), vertical.x1());
+    assertEquals(above.y() + above.height(), vertical.y1());
+    assertEquals(ICON.centerX(), vertical.x2());
+    assertEquals(ICON.y(), vertical.y2());
+
+    Bounds corner = AnnotationGeometry.balloon(ICON, 40, 16, 
AnnotationPlacement.TOP_LEFT, 1f);
+    Segment diagonal = AnnotationGeometry.connector(corner, ICON);
+    assertEquals(corner.x() + corner.width(), diagonal.x1());
+    assertEquals(corner.y() + corner.height(), diagonal.y1());
+    assertEquals(ICON.x(), diagonal.x2());
+    assertEquals(ICON.y(), diagonal.y2());
+  }
+
+  @Test
+  void nullPlacementIsAboveTheIcon() {
+    Bounds balloon = AnnotationGeometry.balloon(ICON, 20, 10, null, 1f);
+    assertTrue(balloon.y() + balloon.height() <= ICON.y());
+  }
+
+  @Test
+  void wrapKeepsLineBreaksAndSplitsLongWords() {
+    assertTrue(AnnotationGeometry.wrap("   ", 10, String::length).isEmpty());
+    assertEquals(List.of("aa", "", "bb"), AnnotationGeometry.wrap("aa\n\nbb", 
10, String::length));
+    assertEquals(
+        List.of("hello", "world"), AnnotationGeometry.wrap("hello world", 5, 
String::length));
+    assertEquals(List.of("abc", "def"), AnnotationGeometry.wrap("abcdef", 3, 
String::length));
+  }
+}
diff --git 
a/plugins/misc/annotation/src/test/java/org/apache/hop/annotation/AnnotationPainterTest.java
 
b/plugins/misc/annotation/src/test/java/org/apache/hop/annotation/AnnotationPainterTest.java
new file mode 100644
index 0000000000..85d7467516
--- /dev/null
+++ 
b/plugins/misc/annotation/src/test/java/org/apache/hop/annotation/AnnotationPainterTest.java
@@ -0,0 +1,355 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.ArrayList;
+import java.util.List;
+import org.apache.hop.annotation.AnnotationGeometry.Bounds;
+import org.apache.hop.annotation.AnnotationGeometry.Segment;
+import org.apache.hop.core.NotePadType;
+import org.apache.hop.core.exception.HopException;
+import org.apache.hop.core.gui.AreaOwner;
+import org.apache.hop.core.gui.DPoint;
+import org.apache.hop.core.gui.IGc;
+import org.apache.hop.core.gui.NotePadStyle;
+import org.apache.hop.core.gui.Point;
+import org.apache.hop.core.svg.SvgFile;
+import org.apache.hop.pipeline.PipelinePainterExtension;
+import org.apache.hop.pipeline.transform.TransformMeta;
+import org.apache.hop.workflow.WorkflowPainterExtension;
+import org.apache.hop.workflow.action.ActionMeta;
+import org.apache.hop.workflow.actions.dummy.ActionDummy;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+class AnnotationPainterTest {
+
+  @AfterEach
+  void resetDarkMode() {
+    NotePadStyle.setDarkMode(false);
+  }
+
+  @Test
+  void paintsACalloutOnlyWhenThereIsText() {
+    NotePadStyle.setDarkMode(false);
+    TransformMeta transform = new TransformMeta();
+    transform.setSelected(true);
+    Annotation annotation = new Annotation();
+    annotation.setText("Hi");
+    annotation.setPlacement(AnnotationPlacement.TOP);
+
+    StubGc gc = new StubGc();
+    List<AreaOwner> areas = new ArrayList<>();
+    DPoint offset = new DPoint(4, 6);
+    AnnotationPainter.paint(gc, areas, offset, transform, 100, 80, 32, true, 
annotation);
+
+    assertEquals(IGc.EFont.NOTE, gc.font);
+    assertEquals(NotePadStyle.backgroundColor(NotePadType.GENERAL).red(), 
gc.backgroundRed);
+    assertEquals(230, gc.backgroundRed);
+    assertEquals(2, gc.roundRectLineWidth);
+    assertEquals(1, areas.size());
+    AreaOwner area = areas.get(0);
+    assertEquals(AreaOwner.AreaType.CUSTOM, area.getAreaType());
+    AnnotationHit hit = assertInstanceOf(AnnotationHit.class, 
area.getParent());
+    assertSame(transform, hit.subject());
+
+    Bounds expected =
+        AnnotationGeometry.balloon(
+            new Bounds(100, 80, 32, 32), gc.textExtent("Hi").x, 10, 
AnnotationPlacement.TOP, 1f);
+    assertEquals(expected.x(), gc.roundX);
+    assertEquals(expected.y(), gc.roundY);
+    assertEquals(expected.x() - 4, area.getArea().x);
+    assertEquals(expected.y() - 6, area.getArea().y);
+    assertEquals(expected.width(), area.getArea().width);
+    assertTrue(gc.drawnText.contains("Hi"));
+    assertEquals(1, gc.lineCount);
+    assertEquals(IGc.ELineStyle.DASH, gc.drawnLineStyle);
+    Segment connector = AnnotationGeometry.connector(expected, new Bounds(100, 
80, 32, 32));
+    assertEquals(connector.x1(), gc.lineX1);
+    assertEquals(connector.y1(), gc.lineY1);
+    assertEquals(connector.x2(), gc.lineX2);
+    assertEquals(connector.y2(), gc.lineY2);
+    assertEquals(IGc.ELineStyle.SOLID, gc.lineStyle);
+
+    areas.clear();
+    annotation.setText("  ");
+    AnnotationPainter.paint(gc, areas, offset, transform, 100, 80, 32, false, 
annotation);
+    assertTrue(areas.isEmpty());
+  }
+
+  @Test
+  void darkModeUsesTheDarkGeneralPalette() {
+    NotePadStyle.setDarkMode(true);
+    ActionMeta action = new ActionMeta(new ActionDummy("end"));
+    Annotation annotation = new Annotation();
+    annotation.setText("End");
+    List<AreaOwner> areas = new ArrayList<>();
+    StubGc gc = new StubGc();
+
+    AnnotationPainter.paint(gc, areas, new DPoint(0, 0), action, 0, 0, 32, 
false, annotation);
+
+    assertEquals(NotePadStyle.backgroundColor(NotePadType.GENERAL).red(), 
gc.backgroundRed);
+    assertEquals(55, gc.backgroundRed);
+    assertEquals(1, gc.roundRectLineWidth);
+    assertEquals(1, areas.size());
+  }
+
+  @Test
+  void dashedLineCanBeTurnedOff() {
+    Annotation annotation = new Annotation();
+    annotation.setText("Hi");
+    annotation.setDashedLine(false);
+    StubGc gc = new StubGc();
+    AnnotationPainter.paint(
+        gc, new ArrayList<>(), new DPoint(0, 0), new TransformMeta(), 0, 0, 
32, false, annotation);
+    assertEquals(0, gc.lineCount);
+  }
+
+  @Test
+  void painterExtensionReadsTheStoredAnnotation() throws HopException {
+    TransformMeta transform = new TransformMeta();
+    Annotation annotation = new Annotation();
+    annotation.setText("In");
+    annotation.setPlacement(AnnotationPlacement.RIGHT);
+    AnnotationStore.write(transform, annotation);
+
+    List<AreaOwner> areas = new ArrayList<>();
+    PipelinePainterExtension pipeline =
+        new PipelinePainterExtension(
+            new StubGc(),
+            areas,
+            null,
+            transform,
+            null,
+            10,
+            20,
+            0,
+            0,
+            0,
+            0,
+            new DPoint(0, 0),
+            32,
+            null);
+    new DrawTransformAnnotationExtensionPoint().callExtensionPoint(null, null, 
pipeline);
+    assertEquals(1, areas.size());
+
+    ActionMeta action = new ActionMeta(new ActionDummy("go"));
+    AnnotationStore.write(action, annotation);
+    List<AreaOwner> actionAreas = new ArrayList<>();
+    WorkflowPainterExtension workflow =
+        new WorkflowPainterExtension(
+            new StubGc(),
+            actionAreas,
+            null,
+            null,
+            action,
+            10,
+            20,
+            0,
+            0,
+            0,
+            0,
+            new DPoint(0, 0),
+            32);
+    new DrawActionAnnotationExtensionPoint().callExtensionPoint(null, null, 
workflow);
+    assertEquals(1, actionAreas.size());
+    assertSame(action, ((AnnotationHit) 
actionAreas.get(0).getParent()).subject());
+  }
+
+  /** Minimal IGc that records the callout colors and shape. */
+  private static final class StubGc implements IGc {
+    private int lineWidth = 1;
+    private IGc.EFont font;
+    private int backgroundRed = -1;
+    private int roundX;
+    private int roundY;
+    private int roundRectLineWidth = -1;
+    private final List<String> drawnText = new ArrayList<>();
+    private IGc.ELineStyle lineStyle = IGc.ELineStyle.SOLID;
+    private IGc.ELineStyle drawnLineStyle;
+    private int lineCount;
+    private int lineX1;
+    private int lineY1;
+    private int lineX2;
+    private int lineY2;
+
+    @Override
+    public void setLineWidth(int width) {
+      lineWidth = width;
+    }
+
+    @Override
+    public void setFont(EFont font) {
+      this.font = font;
+    }
+
+    @Override
+    public int getFontHeight() {
+      return 10;
+    }
+
+    @Override
+    public Point textExtent(String text) {
+      int length = text == null ? 0 : text.length();
+      return new Point(Math.max(length * 7, 1), 14);
+    }
+
+    @Override
+    public Point getDeviceBounds() {
+      return new Point(1000, 1000);
+    }
+
+    @Override
+    public void setBackground(EColor color) {}
+
+    @Override
+    public void setForeground(EColor color) {}
+
+    @Override
+    public void setBackground(int red, int green, int blue) {
+      backgroundRed = red;
+    }
+
+    @Override
+    public void setForeground(int red, int green, int blue) {}
+
+    @Override
+    public void fillRectangle(int x, int y, int width, int height) {}
+
+    @Override
+    public void fillGradientRectangle(int x, int y, int width, int height, 
boolean vertical) {}
+
+    @Override
+    public void drawImage(EImage image, int x, int y, float magnification) {}
+
+    @Override
+    public void drawImage(EImage image, int x, int y, float magnification, 
double angle) {}
+
+    @Override
+    public void drawImage(
+        SvgFile svgFile,
+        int x,
+        int y,
+        int desiredWidth,
+        int desiredHeight,
+        float magnification,
+        double angle) {}
+
+    @Override
+    public boolean drawFileImage(String path, int x, int y, int width, int 
height) {
+      return false;
+    }
+
+    @Override
+    public void drawLine(int x, int y, int x2, int y2) {
+      lineCount++;
+      drawnLineStyle = lineStyle;
+      lineX1 = x;
+      lineY1 = y;
+      lineX2 = x2;
+      lineY2 = y2;
+    }
+
+    @Override
+    public void setLineStyle(ELineStyle lineStyle) {
+      this.lineStyle = lineStyle;
+    }
+
+    @Override
+    public void drawRectangle(int x, int y, int width, int height) {}
+
+    @Override
+    public void drawPoint(int x, int y) {}
+
+    @Override
+    public void drawText(String text, int x, int y) {
+      drawnText.add(text);
+    }
+
+    @Override
+    public void drawText(String text, int x, int y, boolean transparent) {
+      drawnText.add(text);
+    }
+
+    @Override
+    public void fillRoundRectangle(
+        int x, int y, int width, int height, int circleWidth, int 
circleHeight) {
+      roundX = x;
+      roundY = y;
+    }
+
+    @Override
+    public void drawRoundRectangle(
+        int x, int y, int width, int height, int circleWidth, int 
circleHeight) {
+      roundRectLineWidth = lineWidth;
+    }
+
+    @Override
+    public void fillPolygon(int[] polygon) {}
+
+    @Override
+    public void drawPolygon(int[] polygon) {}
+
+    @Override
+    public void drawPolyline(int[] polyline) {}
+
+    @Override
+    public void setAntialias(boolean antiAlias) {}
+
+    @Override
+    public void setTransform(float translationX, float translationY, float 
magnification) {}
+
+    @Override
+    public float getMagnification() {
+      return 1f;
+    }
+
+    @Override
+    public void setAlpha(int alpha) {}
+
+    @Override
+    public void dispose() {}
+
+    @Override
+    public int getAlpha() {
+      return 255;
+    }
+
+    @Override
+    public void setFont(String fontName, int fontSize, boolean fontBold, 
boolean fontItalic) {}
+
+    @Override
+    public void switchForegroundBackgroundColors() {}
+
+    @Override
+    public Point getArea() {
+      return new Point(1000, 1000);
+    }
+
+    @Override
+    public void drawTransformIcon(int x, int y, TransformMeta transformMeta, 
float magnification) {}
+
+    @Override
+    public void drawActionIcon(int x, int y, ActionMeta actionMeta, float 
magnification) {}
+  }
+}
diff --git 
a/plugins/misc/annotation/src/test/java/org/apache/hop/annotation/AnnotationStoreTest.java
 
b/plugins/misc/annotation/src/test/java/org/apache/hop/annotation/AnnotationStoreTest.java
new file mode 100644
index 0000000000..5c78c24085
--- /dev/null
+++ 
b/plugins/misc/annotation/src/test/java/org/apache/hop/annotation/AnnotationStoreTest.java
@@ -0,0 +1,139 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hop.annotation;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNotSame;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.Map;
+import org.apache.hop.core.attributes.AttributesUtil;
+import org.apache.hop.pipeline.transform.TransformMeta;
+import org.apache.hop.pipeline.transforms.dummy.DummyMeta;
+import org.apache.hop.workflow.action.ActionMeta;
+import org.apache.hop.workflow.actions.dummy.ActionDummy;
+import org.junit.jupiter.api.Test;
+
+class AnnotationStoreTest {
+
+  @Test
+  void roundTripOnATransform() {
+    TransformMeta transform = new TransformMeta("Dummy", "read", new 
DummyMeta());
+    Annotation annotation = annotation("Start here", 
AnnotationPlacement.TOP_RIGHT);
+
+    AnnotationStore.write(transform, annotation);
+
+    Annotation read = AnnotationStore.read(transform);
+    assertNotNull(read);
+    assertEquals("Start here", read.getText());
+    assertEquals(AnnotationPlacement.TOP_RIGHT, read.getPlacement());
+    assertTrue(read.isDashedLine());
+    assertEquals(
+        "Y", transform.getAttribute(AnnotationStore.GROUP, 
AnnotationStore.KEY_DASHED_LINE));
+    String xml = AttributesUtil.getAttributesXml(transform.getAttributesMap());
+    assertTrue(xml.contains("annotation"));
+    assertTrue(xml.contains("Start here"));
+    assertTrue(xml.contains("TOP_RIGHT"));
+  }
+
+  @Test
+  void roundTripOnAnActionAndUnknownPlacementFallsBackToTop() {
+    ActionMeta action = new ActionMeta(new ActionDummy("wait"));
+    Annotation annotation = annotation("Wait for the file", 
AnnotationPlacement.LEFT);
+    AnnotationStore.write(action, annotation);
+
+    Annotation read = AnnotationStore.read(action);
+    assertEquals("Wait for the file", read.getText());
+    assertEquals(AnnotationPlacement.LEFT, read.getPlacement());
+
+    action.setAttribute(AnnotationStore.GROUP, AnnotationStore.KEY_PLACEMENT, 
"beside");
+    assertEquals(AnnotationPlacement.TOP, 
AnnotationStore.read(action).getPlacement());
+  }
+
+  @Test
+  void dashedLineIsStoredAndAMissingKeyStaysConnected() {
+    TransformMeta transform = new TransformMeta();
+    Annotation annotation = annotation("Start", AnnotationPlacement.TOP);
+    annotation.setDashedLine(false);
+    AnnotationStore.write(transform, annotation);
+
+    assertFalse(AnnotationStore.read(transform).isDashedLine());
+    assertEquals(
+        "N", transform.getAttribute(AnnotationStore.GROUP, 
AnnotationStore.KEY_DASHED_LINE));
+
+    
transform.getAttributes(AnnotationStore.GROUP).remove(AnnotationStore.KEY_DASHED_LINE);
+    assertTrue(AnnotationStore.read(transform).isDashedLine());
+  }
+
+  @Test
+  void blankTextClearsTheGroup() {
+    TransformMeta transform = new TransformMeta();
+    AnnotationStore.write(transform, annotation("Keep", 
AnnotationPlacement.BOTTOM));
+    assertNotNull(AnnotationStore.read(transform));
+
+    AnnotationStore.write(transform, annotation("   ", 
AnnotationPlacement.BOTTOM));
+    assertNull(AnnotationStore.read(transform));
+    assertNull(transform.getAttributes(AnnotationStore.GROUP));
+
+    AnnotationStore.write(transform, annotation("Again", 
AnnotationPlacement.TOP));
+    AnnotationStore.clear(transform);
+    assertNull(AnnotationStore.read(transform));
+  }
+
+  @Test
+  void writeReplacesTheGroupMapAShallowCloneStillHolds() {
+    ActionMeta original = new ActionMeta(new ActionDummy("start"));
+    AnnotationStore.write(original, annotation("Start", 
AnnotationPlacement.RIGHT));
+    Map<String, String> shared = original.getAttributes(AnnotationStore.GROUP);
+
+    ActionMeta shallow = new ActionMeta(new ActionDummy("start-copy"));
+    shallow.getAttributesMap().put(AnnotationStore.GROUP, shared);
+
+    AnnotationStore.write(original, annotation("End", 
AnnotationPlacement.LEFT));
+
+    assertEquals("Start", shared.get(AnnotationStore.KEY_TEXT));
+    assertEquals("End", original.getAttribute(AnnotationStore.GROUP, 
AnnotationStore.KEY_TEXT));
+    assertEquals("Start", shallow.getAttribute(AnnotationStore.GROUP, 
AnnotationStore.KEY_TEXT));
+    assertNotSame(
+        original.getAttributes(AnnotationStore.GROUP),
+        shallow.getAttributes(AnnotationStore.GROUP));
+  }
+
+  @Test
+  void transformCloneKeepsTheAnnotationItHad() throws Exception {
+    TransformMeta original = new TransformMeta("Dummy", "read", new 
DummyMeta());
+    AnnotationStore.write(original, annotation("Start", 
AnnotationPlacement.TOP));
+
+    TransformMeta cloned = (TransformMeta) original.clone();
+    AnnotationStore.write(original, annotation("Moved", 
AnnotationPlacement.BOTTOM));
+
+    assertEquals("Moved", AnnotationStore.read(original).getText());
+    assertEquals(AnnotationPlacement.TOP, 
AnnotationStore.read(cloned).getPlacement());
+    assertEquals("Start", AnnotationStore.read(cloned).getText());
+  }
+
+  private static Annotation annotation(String text, AnnotationPlacement 
placement) {
+    Annotation annotation = new Annotation();
+    annotation.setText(text);
+    annotation.setPlacement(placement);
+    return annotation;
+  }
+}
diff --git a/plugins/misc/pom.xml b/plugins/misc/pom.xml
index 174b1b279c..91ef5d0991 100644
--- a/plugins/misc/pom.xml
+++ b/plugins/misc/pom.xml
@@ -29,6 +29,7 @@
     <name>Hop Plugins Miscellaneous</name>
 
     <modules>
+        <module>annotation</module>
         <module>debug</module>
         <module>documentation</module>
         <module>execution-database</module>

Reply via email to