Add docs on achieving unique tag macro dropdowns inside list widget (#7639)

editions/tw5.com/tiddlers/macros/TagMacro.tid

@@ -1,12 +1,14 @@
 caption: tag
 created: 20141206130540337
-modified: 20150221224326000
+modified: 20230725201240201
 tags: Macros [[Core Macros]]
 title: tag Macro
 type: text/vnd.tiddlywiki
 
 The <<.def tag>> [[macro|Macros]] generates a tag pill for a specified tag. Clicking the tag pill opens a dropdown. This can be compared to the [[tag-pill Macro]] which also features other parameters.
 
+<<.tip """If a [[list widget|ListWidget]] generates multiple tag macros for the same tag, clicking on one of them will open dropdowns on all of them. The simplest way to prevent this is to add the `counter="transclusion"` attribute to the list widget. See the examples below for more details.""">>
+
 !! Parameters
 
 ;tag

editions/tw5.com/tiddlers/macros/examples/tag.tid

@@ -1,8 +1,29 @@
 created: 20150221211317000
-modified: 20150221224519000
+modified: 20230725203751870
 tags: [[tag Macro]] [[Macro Examples]]
 title: tag Macro (Examples)
 type: text/vnd.tiddlywiki
 
 <$macrocall $name=".example" n="1" eg="""<<tag>>"""/>
 <$macrocall $name=".example" n="2" eg="""<<tag Concepts>>"""/>
+
+If a [[list widget|ListWidget]] generates multiple tag macros for the same tag, clicking any of them opens dropdowns on all of them, as in the example below. This is usually unwanted.
+<$macrocall $name=".example" n="3" eg="""<$list filter="[tag[HelloThere]]">
+
+* <$link/> is tagged with: <$list filter="[<currentTiddler>tags[]]"> <<tag>> </$list>
+
+</$list>"""/>
+
+Adding the `counter="transclusion"` attribute to the list widget that generates multiple identical tag macros causes each of them to be identified as a unique one. Clicking on any of them opens only a single dropdown.
+<$macrocall $name=".example" n="4" eg="""<$list filter="[tag[HelloThere]]" counter="transclusion">
+
+* <$link/> is tagged with: <$list filter="[<currentTiddler>tags[]]"> <<tag>> </$list>
+
+</$list>"""/>
+
+A slightly more performant option is to use the `variable="transclusion"` attribute in the list widget. In this case, the variable `<<transclusion>>` has to be used inside the list widget instead of the `<<currentTiddler>>` .
+<$macrocall $name=".example" n="5" eg="""<$list filter="[tag[HelloThere]]" variable="transclusion">
+
+* <$link to=<<transclusion>>/> is tagged with: <$list filter="[<transclusion>tags[]]"> <<tag>> </$list>
+
+</$list>"""/>

editions/tw5.com/tiddlers/widgets/ListWidget.tid

@@ -1,6 +1,6 @@
 caption: list
 created: 20131024141900000
-modified: 20220718120325494
+modified: 20230725203601441
 tags: Widgets Lists
 title: ListWidget
 type: text/vnd.tiddlywiki
@@ -119,6 +119,8 @@ Displays as:
 
 Note that using the `counter` attribute can reduce performance when working with list items that dynamically reorder or update themselves. The best advice is only to use it when it is really necessary: to obtain a numeric index, or to detect the first or last entries in the list.
 
+Setting `counter="transclusion"` is a handy way to make child elements for each list element be identified as unique. A common use case are multiple [[tag macros|tag Macro]] for the same tag generated by a list widget. Refer to [[tag macro examples|tag Macro (Examples)]] for more details.
+
 !! Edit mode
 
 The `<$list>` widget can optionally render draft tiddlers through a different template to handle editing, see DraftMechanism.