From 12f7b98c4fba93b6d7db2157a2b8ba03e1fd02a4 Mon Sep 17 00:00:00 2001
From: lin onetwo <linonetwo012@gmail.com>
Date: Tue, 13 Jun 2023 22:57:24 +0800
Subject: [PATCH] Docs for widget.destroy (#7508)

---
 .../Widget `destroy` method examples.tid      | 36 +++++++++++++++++
 .../moduletypes/WidgetModules.tid             | 13 ++++--
 editions/dev/tiddlers/system/doc-styles.tid   | 40 +++++++++++++++++++
 .../dev/tiddlers/system/version-macros.tid    | 14 +++++++
 4 files changed, 100 insertions(+), 3 deletions(-)
 create mode 100644 editions/dev/tiddlers/Widget `destroy` method examples.tid
 create mode 100644 editions/dev/tiddlers/system/doc-styles.tid
 create mode 100644 editions/dev/tiddlers/system/version-macros.tid

diff --git a/editions/dev/tiddlers/Widget `destroy` method examples.tid b/editions/dev/tiddlers/Widget `destroy` method examples.tid
new file mode 100644
index 000000000..5ff04bdd0
--- /dev/null
+++ b/editions/dev/tiddlers/Widget `destroy` method examples.tid	
@@ -0,0 +1,36 @@
+created: 20230601123245916
+modified: 20230601125015463
+title: Widget `destroy` method examples
+type: text/vnd.tiddlywiki
+
+!! When using a v-dom library
+
+Virtual DOM libraries manages its internal state and apply state to DOM periodically, this is so called [["controlled" component|https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components]]. When Tiddlywiki remove a DOM element controlled by a v-dom library, it may throws error.
+
+So when creating a plugin providing v-dom library binding, you need to tell v-dom library (for example, React.js) the DOM element is removed. We will use `destroy` method for this.
+
+```js
+  render() {
+    // ...other render related code
+    if (this.root === undefined || this.containerElement === undefined) {
+      // initialize the v-dom library
+      this.root = ReactDom.createRoot(document.createElement('div'));
+    }
+  }
+
+  destroy() {
+    // end the lifecycle of v-dom library
+    this.root && this.root.unmount();
+  }
+```
+
+The `destroy` method will be called by parent widget. If you widget don't have any child widget, you can just write your own tear down logic. If it may have some child widget, don't forget to call original `destroy` method in the `Widget` class to destroy children widgets.
+
+```js
+Widget.prototype.destroy();
+this.root && this.root.unmount();
+/** if you are using ESNext
+super.destroy();
+this.root?.unmount();
+*/
+```
\ No newline at end of file
diff --git a/editions/dev/tiddlers/from tw5.com/moduletypes/WidgetModules.tid b/editions/dev/tiddlers/from tw5.com/moduletypes/WidgetModules.tid
index 1a8bf5edf..0b0b3f33a 100644
--- a/editions/dev/tiddlers/from tw5.com/moduletypes/WidgetModules.tid	
+++ b/editions/dev/tiddlers/from tw5.com/moduletypes/WidgetModules.tid	
@@ -1,7 +1,8 @@
-title: WidgetModules
+created: 20131101130700000
+modified: 20230601130631884
 tags: dev moduletypes
-created: 201311011307
-modified: 201311011307
+title: WidgetModules
+type: text/vnd.tiddlywiki
 
 ! Introduction
 
@@ -78,4 +79,10 @@ The individual methods defined by the widget object are documented in the source
 !! Widget `refreshChildren` method
 !! Widget `findNextSiblingDomNode` method
 !! Widget `findFirstDomNode` method
+!! Widget `destroy` method
+
+<<.from-version "5.3.0">> Gets called when any parent widget is unmounted from the widget tree.
+
+[[Examples|Widget `destroy` method examples]]
+
 !! Widget `removeChildDomNodes` method
diff --git a/editions/dev/tiddlers/system/doc-styles.tid b/editions/dev/tiddlers/system/doc-styles.tid
new file mode 100644
index 000000000..24234d47a
--- /dev/null
+++ b/editions/dev/tiddlers/system/doc-styles.tid
@@ -0,0 +1,40 @@
+created: 20150117152612000
+modified: 20230325101137075
+tags: $:/tags/Stylesheet
+title: $:/editions/tw5.com/doc-styles
+type: text/vnd.tiddlywiki
+
+a.doc-from-version.tc-tiddlylink {
+    display: inline-block;
+    border-radius: 1em;
+	background: <<colour muted-foreground>>;
+	color: <<colour background>>;
+	fill: <<colour background>>;
+    padding: 0 0.4em;
+    font-size: 0.7em;
+    text-transform: uppercase;
+    font-weight: bold;
+    line-height: 1.5;
+    vertical-align: text-bottom;
+}
+
+a.doc-deprecated-version.tc-tiddlylink {
+    display: inline-block;
+    border-radius: 1em;
+	background: red;
+	color: <<colour background>>;
+	fill: <<colour background>>;
+    padding: 0 0.4em;
+    font-size: 0.7em;
+    text-transform: uppercase;
+    font-weight: bold;
+    line-height: 1.5;
+    vertical-align: text-bottom;
+}
+
+.doc-deprecated-version svg,
+.doc-from-version svg {
+	width: 1em;
+	height: 1em;
+    vertical-align: text-bottom;
+}
diff --git a/editions/dev/tiddlers/system/version-macros.tid b/editions/dev/tiddlers/system/version-macros.tid
new file mode 100644
index 000000000..0fb7dcf12
--- /dev/null
+++ b/editions/dev/tiddlers/system/version-macros.tid
@@ -0,0 +1,14 @@
+code-body: yes
+created: 20161008085627406
+modified: 20221007122259593
+tags: $:/tags/Macro
+title: $:/editions/tw5.com/version-macros
+type: text/vnd.tiddlywiki
+
+\define .from-version(version)
+<$link to={{{ [<__version__>addprefix[Release ]] }}} class="doc-from-version">{{$:/core/images/warning}} New in: <$text text=<<__version__>>/></$link>
+\end
+
+\define .deprecated-since(version, superseded:"TODO-Link")
+<$link to="Deprecated - What does it mean" class="doc-deprecated-version tc-btn-invisible">{{$:/core/images/warning}} Deprecated since: <$text text=<<__version__>>/></$link> (see <$link to=<<__superseded__>>><$text text=<<__superseded__>>/></$link>)
+\end