Improving Include, homepage

Author: michaelpb

src/devlog/2024-12.html

@@ -5,12 +5,10 @@
 
 
 I'm happy to announce the release of Alpha 0.0.73, which brings quite a few new
-handy features, while still keeping it all under 2000 lines of code.
-
-Finally, I'm happy to announce that after extensive "dog-fooding", Modulo is
-getting ready for prime time -- or at least "prime-ish" time!). To communicate
-it's feature stability, the project is ready to transition to a "beta" phase.
-More info on the release plans contained below.
+handy features, while still keeping it all under 2000 lines of code.  This
+release marks the first that starts the process toward a more stable `0.1.0` or
+"beta" release (likely around the `~0.0.75` or `~0.0.80` releases).  More info
+on the release plans contained below.
 
 
 ## Alpha 73
@@ -60,13 +58,17 @@
 The simplest way to use `Include` is as a global definition. It will "include"
 it's contents in the head of the document  as soon as Modulo loads. Note that
 it will NEVER include the same thing twice (it uses hashes to identify
-resources).
+resources).  This mode is great for following tutorials for integrating JS
+projects. 
 
-This mode is great for following tutorials for integrating JS projects. You can
-often simply copy and paste whatever you are given into the `Include`, as such:
+For example, to include Quill JS, it's as easy as just pasting in the head
+content they give you:
 
 ```
-<Include></Include>
+<Include>
+    <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/quill.snow.css" rel="stylesheet" />
+    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/quill.js">/script>
+</Include>
 ```
 
 
@@ -77,31 +79,18 @@
 
 ```
 <Include>
-    <meta name="charset" charset="utf8" />
-    <meta name="content-type" http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <meta name="description" content="A great Modulo website" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="charset" charset="utf8" />
 </Include>
 ```
 
-### Example 3: For NPM dependencies
-
-One of the most powerful features of _Include_ is the ability to bring in
-packages from NPM (or equivalent), given their package name and a CDN server.
-See below:
-
-```
-<Component>
-    <Include
-        -server="unpkg.com"
-        cke="1.3.4"
-    ></Include>
-    <Template>
-        <textare></textarea>
-    </Template>
-</Component>
-```
+### Additional features
 
-Also, note that you can use `-load-mode="lazy"` to make it skip
+Also, note that you can use `-load-mode="lazy"` to make it skip the bundle, and
+only get inserted as-is on page load. This is great for fixing bugs with
+integrating other JS packages, while supporting advanced features like
+JavaScript modules and `import` statements.
 
 
 ### Alpha 73 Deprecation FAQ
@@ -144,8 +133,9 @@
 
 This means I am trying my best to avoid having to add or remove any major
 features from "beta" to "1.0".  The goal of the subseuqent beta releases (e.g.,
-`0.2.x`, `0.3.x`), in preparation for a highly-stable, semi-final 1.0 release, are
-to polish
+`0.2.x`, `0.3.x`), in preparation for a highly-stable, semi-final 1.0 release,
+are to polish, stabilize, and provide crystal-clear documentation and
+best-practices.
 
 In the mean time, check out the following early work in progress "teasers" of
 what's in store:

src/docs/core/component.html

@@ -6,12 +6,10 @@
 # Component
 
 > **Low-level interface** - Component developers will typically
-only need to use the `name="..."` attribute on *Component*,
-and sometimes `mode="vanish-into-document"` for  page-level
-components. Similarly, none of the `renderObj.component` properties
-are typically useful for component developers. Instead, they are used
-internally by CParts (notably *Template*) in order to move along the
-rendering cycle.
+only need to use the `name="..."` attribute on *Component*. Similarly, none of
+the `renderObj.component` properties are typically useful for component
+developers. Instead, they are used internally by CParts (notably *Template*) in
+order to move along the rendering cycle.
 
 The *Component* definition is the most central to Modulo. It's how we register
 components to be mounted on the page, and define the CParts that go inside
@@ -138,12 +136,13 @@ <h3>To Do example:</h3>
 render mode of this component. This changes what is considered to be the root
 of the element, and thus where the content of the Template goes during
 reconciliation. In "regular" and "vanish", it's the custom component itself
-(which will be removed after rendering with "vanish"), in "shadow", it uses an
-attached shadow DOM as the root, and with "vanish-into-document" it replaces
-the entire page.  This allows you to isolate outside CSS from your component
-using "shadow", do one-time renders only with "vanish", or make your component
-replace the entire document with "vanish-into-document". A detailed discussion
-of valid options are below:
+(which will be removed after rendering with "vanish"), and in "shadow", it uses an
+attached shadow DOM as the root.  This allows you to isolate outside CSS from
+your component using "shadow" or do one-time renders only with "vanish".
+
+
+A detailed discussion of valid options are below:
+
 * `mode="regular"` - The default behavior, where the content generated by this
   the element will be attached to the regular DOM, as the element itself. This
   means that CSS stylesheets attached the normal way (e.g. with a "link" tag)
@@ -181,21 +180,6 @@ <h3>To Do example:</h3>
   generators, when you just want to generate plain HTML, with no Modulo JS or
   behavior in the end.
 
-* `mode="vanish-into-document"` - This setting is useful in one situation: When
-  you want to create a "page" level component that changes tags that belong in
-  the document head, such as `&lt;title&gt;`. Like with `mode="vanish"`
-  described above, setting this will cause the component to remove itself after
-  the first time it renders. However, with vanish-into-document, it will
-  instead replace the entire page.  It will also attempt to correctly insert
-  all tags that belong in the document head (meta, title, link, script to be
-  specific), causing link and script tags alike (e.g.  `&lt;script
-  src=".."&gt;&lt;/script&gt;`) to load.  Finally, the document will be wiped,
-  and anything else it finds will be put directly into the document's body, for
-  a clean DOM structure that removes itself entirely during this "one-time
-  render".
-        * *DEPRECATION NOTICE* - `vanish-into-document` may be removed, and
-          simply `vanish` will also support insertion to head
-
 * `mode="custom-root"` - This is rarely useful, but allows for setting some
   other DOM element as the new root element for the component to target for
   rendering it's content. This is done by assigning a value to
@@ -225,12 +209,10 @@ <h3>To Do example:</h3>
 `{this.props.children}`.)  For more on the slot interface, see Mozilla's
 [The Web Component Slot element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot)
 
-Note that Modulo uses this interface for both `mode="shadow"` (e.g. using
-`shadowRoot` as the root element for reconciliation) and all the other DOM
-rendering modes (e.g.  `mode="regular"`, `mode="vanish-into-document"`). For
-Shadow DOM, it will fall-back on Browser behavior. For everything else, it will
-detach any nodes it finds and reattach the nodes just before the beginning of
-the reconciliation process (it's DOM load-directive).
+Note that Modulo components can even use this without using shadow rendering
+(e.g. `mode="shadow"`).  Modulo will attempt to simulate the Shadow DOM
+Behavior: it will detach any nodes it finds and reattach the nodes just before
+the beginning of the reconciliation process (it's DOM load-directive).
 
 ### Defaults
 
@@ -298,3 +280,20 @@ <h1><slot name="topTitle">Picture</slot></h1>
 </x-PhotoFrame>
 ```
 
+### Deprecated features
+
+
+* *Alpha 73 - Deprecated, do not use in new projects:*
+  `mode="vanish-into-document"` - This setting is useful in one situation: When
+  you want to create a "page" level component that changes tags that belong in
+  the document head, such as `&lt;title&gt;`. Like with `mode="vanish"`
+  described above, setting this will cause the component to remove itself after
+  the first time it renders. However, with vanish-into-document, it will
+  instead replace the entire page.  It will also attempt to correctly insert
+  all tags that belong in the document head (meta, title, link, script to be
+  specific), causing link and script tags alike (e.g.  `&lt;script
+  src=".."&gt;&lt;/script&gt;`) to load.  Finally, the document will be wiped,
+  and anything else it finds will be put directly into the document's body, for
+  a clean DOM structure that removes itself entirely during this "one-time
+  render".
+

src/docs/core/index.html

@@ -33,8 +33,9 @@
 definitions, along with a summary of each:
 
 
-1.  [Configuration](configuration.html) - *(Extending or configuring Modulo and
-including third-party JavaScript libraries)*
+1.  [Configuration](configuration.html) _and_ [Include](configuration.html)  -
+*(Extending or configuring Modulo and including third-party JavaScript
+libraries)*
 2.  [Library](library.html) - *(Importing component libraries with
 non-conflicting namespaces or aliases)*
 3.  [Artifact](artifact.html) - *(Customizing build behavior or specifying

src/static/components/layout/HomeSplash/HomeSplash.html

@@ -18,15 +18,23 @@ <h2 style="color: var(--color-fg-semidark)">The Declarative HTML Web Component F
     </ul>
 
     <x-TabPane hadjust="true">
-        <x tab-title="HelloCount">
+        <x tab-title="Hello">
+            <!-- TODO: Remove "preview=..." -->
             <x-DemoEditor
-              src="/static/demos/eg/HelloCount.html"
-              preview="<button style='font-size: 13.3px; font-weight: 400'>Hello 42</button>"
-            ></x-DemoEditor>
+              src="/static/demos/eg/HelloModulo.html"
+              preview='<div style="border: 2px dotted Indigo; padding: 10px;">
+        <p>Building <tt style="color: Indigo">Modulo</tt>
+           HTML web components is <em>fun</em>!</p>
+    </div>'></x-DemoEditor>
         </x>
         <x tab-title="SimpleStyle">
             <x-DemoEditor src="/static/demos/eg/SimpleStyle.html"></x-DemoEditor>
         </x>
+        <x tab-title="Count">
+            <x-DemoEditor
+              src="/static/demos/eg/HelloCount.html"
+            ></x-DemoEditor>
+        </x>
         <x tab-title="JSON">
             <x-DemoEditor src="/static/demos/eg/JSON.html"></x-DemoEditor>
         </x>

src/static/components/layout/Page/Page.html

@@ -117,21 +117,18 @@
                 <em>YOU!</em></p>
                 <h3><span alt="Lower case Greek alpha">α</span></h3>
 
-                <iframe
-                src="https://ghbtns.com/github-btn.html?user=modulojs&repo=modulo&type=star&count=true&size=large"
-                frameborder="0" scrolling="0" width="160" height="30"
-                title="GitHub"></iframe>
-
                 <p style="font-size: 0.9rem; margin:0; padding:0">The Modulo
                 project needs you (the user), 1) to be aware that it is
                 "alpha", released for early feedback, and thus you might
                 encounter <a style="font-size: 0.9rem;"
                 href="https://github.com/modulojs/modulo/issues">some annoying
                 bugs</a>, 2) use it to make cool stuff anyway, 3) to star it
-                and/or follow development on GitHub, which boosts the
-                framework's visibility, and 4) finally, and most importantly,
-                to share your cool Modulo creations, both with the world, and
-                with us, so we know which features to best support.</p>
+                and/or follow development on <a
+                href="https://github.com/modulojs/modulo/">GitHub</a>, which
+                boosts the framework's visibility, and 4) finally, and most
+                importantly, to share your cool Modulo creations, both with the
+                world, and with us, so we know which features to best
+                support.</p>
                 </div>
             </aside>
             <nav slot="right">

src/static/data/links/documentation.js

@@ -141,6 +141,12 @@
                     'shadow', 'vanish', 'vanish-into-document',
                     'component.event', 'component.slot', 'component.dataProp'],
                 },
+                {
+                    label: 'Include',
+                    filename: 'include.html',
+                    keywords: ['head', 'integrating scripts', 'integrating link tags',
+                    'meta tags', 'lazy loading', 'component includes' ],
+                },
                 {
                     label: 'Library',
                     filename: 'library.html',

src/static/demos/eg/HelloModulo.html

@@ -1,15 +1,10 @@
-<!-- The simplest re-usable component: Template only -->
+<!-- The simplest component: HTML Template only -->
 <Template>
-    <!-- <Template> support almost any HTML, including
-         embedding CSS with inline style attributes -->
-    <div style="
-            border: 2px dotted DarkGreen;
-            padding: 10px;
-        ">
-        <p>Building <tt style="color: Green">Modulo</tt>
-            HTML web components is <em>fun</em>!</p>
+    <div style="border: 2px dotted Indigo; padding: 10px;">
+        <p>Building <tt style="color: Indigo">Modulo</tt>
+           HTML web components is <em>fun</em>!</p>
     </div>
-    <!-- HINT: First time with Moduolo?
-        1. Make a change and click RUN to see result
-        2. Hover over RUN button for more options -->
 </Template>
+<!-- HINT: First time with Modulo?
+     1. Make a change and click RUN to see result
+     2. Hover over RUN button for more options -->