docs: make the inline SVG icon example idempotent

CHANGELOG.md

@@ -40,6 +40,7 @@
 * Added a dynamic per-row title example to the menu-title demo (fixes #769)
 * The asynchronous create demo now works on right click (fixes #735)
 * Documented that `$(...).contextMenu({x, y})` takes page coordinates (fixes #812)
+* Made the inline SVG icon example idempotent and documented that a callback `icon` re-runs on every show/update
 
 ### 2.10.2
 

documentation/docs/customize.md

@@ -42,13 +42,26 @@ var items = {
         // or inject an inline <svg> (or <img>) directly into the item and
         // return a class name to mark it as done (see the icon option docs)
         icon: function (opt, $itemElement) {
-            $itemElement.prepend('<svg class="context-menu-icon" ...>...</svg>');
+            // A callback icon runs again every time the menu is shown or
+            // updated, not just once, so anything that adds to the item has to
+            // check first. Without the guard every open would prepend another
+            // <svg> and the item would keep growing.
+            if (!$itemElement.children('svg.my-inline-icon').length) {
+                $itemElement.prepend('<svg class="my-inline-icon" ...>...</svg>');
+            }
             return 'context-menu-icon-inline';
         }
     }
 }
 ```
 
+Give the injected element a class of your own rather than `context-menu-icon`,
+which this plugin already uses on the menu item itself.
+
+Anything that replaces the item's content instead of adding to it is idempotent
+on its own and needs no guard, which is why the
+[icon option](items#icon) example can call `$itemElement.html(...)` directly.
+
 ## Customize CSS
 
 You can use the _variables.scss to adjust variables on pretty much everything you want to change.

documentation/docs/items.md

@@ -148,6 +148,13 @@ Specifies the icon class to set for the item.
 When using a string icons must be defined in CSS with selectors like `.context-menu-item.context-menu-icon-edit`, where `edit` is the icon class specified.
 
 When using a callback you can return a class string to use that as the class on the item. You can also modify the element by using the `$itemElement` argument. 
+
+The callback is invoked every time the menu is shown or updated, not only when
+it is first built, so that the icon can reflect current state. Write it to be
+idempotent: replacing the item's content (as in the example below) is safe,
+while adding to it needs a guard so repeated opens do not stack up duplicates.
+See [using your own SVG icons](customize#using-your-own-svg-icons-without-a-build-step)
+for that pattern.
 
 `icon`: `string` or `function(opt, $itemElement, itemKey, item)`