replacing doc update

docs-src/config.ts

@@ -1,9 +1,9 @@
 import Home from './index.page'
 import Documentation from './documentation/index.page'
 import InstallationPage from './documentation/installation.page'
-import EssentialTrainingPage from './documentation/essential-training.page'
-import TutorialPage from './documentation/tutorial.page'
-import ExamplesPage from './documentation/examples.page'
+// import EssentialTrainingPage from './documentation/essential-training.page'
+// import TutorialPage from './documentation/tutorial.page'
+// import ExamplesPage from './documentation/examples.page'
 import CreatingAndRenderingPage from './documentation/creating-and-rendering.page'
 import TemplatingValuesPage from './documentation/template-values.page'
 import ReplacingContentPage from './documentation/replacing-content.page'

docs-src/documentation/replacing-content.page.ts

@@ -14,22 +14,24 @@ export default ({ page, nextPage, prevPage, docsMenu }: PageComponentProps) =>
         html`
             ${Heading(page.name)}
             <p>
-                One special thing about templates is that you can treat it like
-                a DOM element for few things. One of these things is the ability
-                to replace one template with the another.
+                One special thing about Markup template is that it is an
+                instance object, which you can do a lot of things to. One of
+                these things is the ability to replace one template with the
+                another.
             </p>
             <p>
-                Let's take for example an async scenario where you render a
-                loading indicator then need to replace this loading indicator
-                with the loaded content.
+                Let's take for example an async rendering scenario where you
+                render a loading indicator then need to replace this loading
+                indicator with the actual loaded content.
             </p>
             ${CodeSnippet(
                 'const loadingIndicator = html`<p>loading...</p>`;\n' +
                     '\n' +
                     'const fetchContent = () => {\n' +
-                    '  setTimeout(() => {\n' +
+                    '  setTimeout(() => { // simulate HTTP call\n' +
                     '    const content = html`<p>loaded content</p>`;\n' +
                     '    \n' +
+                    '    // render content by telling it what to replace\n' +
                     '    content.replace(loadingIndicator)\n' +
                     '  }, 2500)\n' +
                     '}\n' +
@@ -51,14 +53,14 @@ export default ({ page, nextPage, prevPage, docsMenu }: PageComponentProps) =>
                 This means that you can have multiple tags, and it will just
                 replace them all.
             </p>
-            ${Heading('Replacing a DOM Element', 'h3')}
+            ${Heading('Replacing HTML Element', 'h3')}
             <p>
-                You may also target a specific DOM Element. Here is the sample
+                You may also target a specific DOM Element. Here is the same
                 example but with the loading indicator as an Element instead of
-                a template.
+                an HTML Template.
             </p>
             ${CodeSnippet(
-                '// using a P Element instead\n' +
+                '// using a HTMLParagraphElement instance\n' +
                     "const loadingIndicator = document.createElement('p');\n" +
                     "loadingIndicator.textContent = 'Loading...'\n" +
                     '\n' +
@@ -76,7 +78,30 @@ export default ({ page, nextPage, prevPage, docsMenu }: PageComponentProps) =>
                     'fetchContent();',
                 'typescript'
             )}
-            <p>This will have the same effect.</p>
+            ${Heading('Replacing "Must known"', 'h3')}
+            <ul>
+                <li>
+                    The target template must be already rendered in the DOM in
+                    order for the "replacing" to happen.
+                </li>
+                <li>
+                    The target can be a
+                    <a
+                        href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement"
+                        >HTMLElement</a
+                    >
+                    instance but it cannot be <code>HTMLBodyElement</code>,
+                    <code>HTMLHeadElement</code>, <code>HTMLHtmlElement</code>,
+                    or <code>ShadowRoot</code> as these are crucial elements in
+                    the document.
+                </li>
+                <li>
+                    If the replacement template has not been yet rendered, it
+                    will but if it is already rendered somewhere else in the
+                    DOM, it will be moved from that location to the location
+                    where the target is.
+                </li>
+            </ul>
             ${DocPrevNextNav({
                 prev: prevPage,
                 next: nextPage,

src/html.ts

@@ -155,19 +155,19 @@ export class HtmlTemplate {
                 this.#init(element)
             }
 
-            if (element.parentNode) {
-                const frag = doc.createDocumentFragment()
-                frag.append(...this.nodes)
-                element.parentNode.replaceChild(frag, element)
+            const frag = doc.createDocumentFragment()
+            frag.append(...this.nodes)
+            element.parentNode?.replaceChild(frag, element)
 
-                if (target instanceof HtmlTemplate) {
-                    target.unmount()
-                }
-            } else {
-                return
+            // only need to unmount the template nodes
+            // if the target is not a template, it will be automatically removed
+            // when replaceChild is called above.
+            if (target instanceof HtmlTemplate) {
+                target.unmount()
             }
 
-            this.#renderTarget = element
+            this.#renderTarget = element.parentNode as HTMLElement
+
             return
         }