+
Title
+
Content
+ ` })
),
el(example, { src: fileURL("./components/examples/customElement/shadowRoot.js"), page_id }),
@@ -234,7 +241,7 @@ export function page({ pkg, info }){
el("dt", t`Purpose`),
el("dd", t`Provides slot functionality when you cannot/do not want to use shadow DOM`),
el("dt", t`Parameters`),
- el("dd", t`A mapping object of slot names to DOM elements`)
+ el("dd", t`A mapping object of slot names to DOM elements`)
)
),
@@ -266,7 +273,7 @@ export function page({ pkg, info }){
el("dt", t`Events not firing properly`),
el("dd", t`Make sure you called customElementWithDDE before defining the element`),
el("dt", t`Attributes not updating`),
- el("dd", t`Check that you've properly listed them in static observedAttributes`),
+ el("dd", t`Check that you’ve properly listed them in static observedAttributes`),
el("dt", t`Component not rendering`),
el("dd", t`Verify customElementRender is called in connectedCallback, not constructor`)
)
diff --git a/docs/p07-debugging.html.js b/docs/p07-debugging.html.js
index daf1cf1..80568d4 100644
--- a/docs/p07-debugging.html.js
+++ b/docs/p07-debugging.html.js
@@ -19,7 +19,7 @@ export function page({ pkg, info }){
return el(simplePage, { info, pkg }).append(
el("p").append(...T`
Debugging is an essential part of application development. This guide provides techniques
- and best practices for debugging applications built with dd
, with a focus on signals.
+ and best practices for debugging applications built with dd, with a focus on signals.
`),
el(h3, t`Debugging signals`),
@@ -30,42 +30,40 @@ export function page({ pkg, info }){
el("h4", t`Inspecting signal values`),
el("p").append(...T`
- The simplest way to debug a signal is to log its current value by calling the get method:
+ The simplest way to debug a signal is to log its current value by calling the get method:
`),
el(code, { content: `
-const signal = S(0);
-console.log('Current value:', signal.get());
-// without triggering updates
-console.log('Current value:', signal.valueOf());
- `, page_id }),
+ const signal = S(0);
+ console.log('Current value:', signal.get());
+ // without triggering updates
+ console.log('Current value:', signal.valueOf());
+ `, page_id }),
el("p").append(...T`
- You can also monitor signal changes by adding a listener:
+ You can also monitor signal changes by adding a listener:
`),
- el(code, {
- content:
- "// Log every time the signal changes\nS.on(signal, value => console.log('Signal changed:', value));",
- page_id }),
+ el(code, { content: `
+ // Log every time the signal changes
+ S.on(signal, value => console.log('Signal changed:', value));
+ `, page_id }),
el("h4", t`Debugging derived signals`),
el("p").append(...T`
- With derived signals (created with ${el("code", "S(() => computation))")}), debugging is a bit more complex
- because the value depends on other signals. To understand why a derived signal isn't updating correctly:
+ With derived signals (created with ${el("code", "S(() => computation))")}), debugging is a bit more complex
+ because the value depends on other signals. To understand why a derived signal isn’t updating correctly:
`),
el("ol").append(
el("li", t`Check that all dependency signals are updating correctly`),
- el("li", t`Add logging inside the computation function to see when it runs`),
+ el("li", t`Add logging/debugger inside the computation function to see when it runs`),
el("li", t`Verify that the computation function actually accesses the signal values with .get()`)
),
el(example, { src: fileURL("./components/examples/debugging/consoleLog.js"), page_id }),
el(h3, t`Common signal debugging issues`),
el("h4", t`Signal updates not triggering UI changes`),
- el("p").append(...T`
- If signal updates aren't reflected in the UI, check:
- `),
+ el("p", t`If signal updates aren’t reflected in the UI, check:`),
el("ul").append(
- el("li", t`That you're using signal.set() to update the value, not modifying objects/arrays directly`),
- el("li", t`For mutable objects, ensure you're using actions or making proper copies before updating`),
+ el("li", t`That you’re using signal.set() to update the value, not modifying objects/arrays directly`),
+ el("li", t`For mutable objects, ensure you’re using actions or making proper copies before updating`),
el("li", t`That the signal is actually connected to the DOM element (check your S.el or attribute binding code)`)
),
el(code, { src: fileURL("./components/examples/debugging/mutations.js"), page_id }),
@@ -77,12 +75,10 @@ console.log('Current value:', signal.valueOf());
`),
el("h4", t`Performance issues with frequently updating signals`),
- el("p").append(...T`
- If you notice performance issues with signals that update very frequently:
- `),
+ el("p", t`If you notice performance issues with signals that update very frequently:`),
el("ul").append(
el("li", t`Consider debouncing or throttling signal updates`),
- el("li", t`Make sure derived signals don't perform expensive calculations unnecessarily`),
+ el("li", t`Make sure derived signals don’t perform expensive calculations unnecessarily`),
el("li", t`Keep signal computations focused and minimal`)
),
el(code, { src: fileURL("./components/examples/debugging/debouncing.js"), page_id }),
@@ -96,13 +92,13 @@ console.log('Current value:', signal.valueOf());
el("p").append(...T`
dd marks components in the DOM with special comment nodes to help you identify component boundaries.
Components created with ${el("code", "el(ComponentFunction)")} are marked with comment nodes
- ${el("code", "")} and
+ ${el("code", ``)} and
includes:
`),
el("ul").append(
- el("li", "type - Identifies the type of marker (\"component\", \"reactive\", or \"later\")"),
- el("li", "name - The name of the component function"),
- el("li", "host - Indicates whether the host is \"this\" (for DocumentFragments) or \"parentElement\""),
+ el("li", t`type - Identifies the type of marker ("component", "reactive", or "later")`),
+ el("li", t`name - The name of the component function`),
+ el("li", t`host - Indicates whether the host is "this" (for DocumentFragments) or "parentElement"`),
),
el("h4", t`Finding reactive elements in the DOM`),
@@ -113,7 +109,7 @@ console.log('Current value:', signal.valueOf());
`),
el(code, { src: fileURL("./components/examples/debugging/dom-reactive-mark.html"), page_id }),
el("p").append(...T`
- This is particularly useful when debugging why a reactive section isn't updating as expected.
+ This is particularly useful when debugging why a reactive section isn’t updating as expected.
You can inspect the elements between the comment nodes to see their current state and the
signal connections through \`__dde_reactive\` of the host element.
`),
@@ -124,48 +120,49 @@ console.log('Current value:', signal.valueOf());
`),
el("p").append(...T`
${el("code", ".__dde_reactive")} - An array property on DOM elements that tracks signal-to-element
- relationships. This allows you to quickly identify which elements are reactive and what signals they're
- bound to. Each entry in the array contains:
+ relationships. This allows you to quickly identify which elements are reactive and what signals they’re
+ bound to. Each entry in the array contains:
`),
el("ul").append(
- el("li", "A pair of signal and listener function: [signal, listener]"),
- el("li", "Additional context information about the element or attribute"),
- el("li", "Automatically managed by signal.el(), signal.observedAttributes(), and processReactiveAttribute()")
+ el("li", t`A pair of signal and listener function: [signal, listener]`),
+ el("li", t`Additional context information about the element or attribute`),
+ el("li", t`Automatically managed by signal.el(), signal.observedAttributes(), and processReactiveAttribute()`)
),
el("p").append(...T`
- These properties make it easier to understand the reactive structure of your application when inspecting elements.
+ These properties make it easier to understand the reactive structure of your application when inspecting
+ elements.
`),
el(example, { src: fileURL("./components/examples/signals/debugging-dom.js"), page_id }),
el("h4", t`Examining signal connections`),
el("p").append(...T`
- ${el("code", ".__dde_signal")} - A Symbol property used to identify and store the internal state of
+ ${el("code", ".__dde_signal")} - A Symbol property used to identify and store the internal state of
signal objects. It contains the following information:
`),
el("ul").append(
- el("li", "listeners: A Set of functions called when the signal value changes"),
- el("li", "actions: Custom actions that can be performed on the signal"),
- el("li", "onclear: Functions to run when the signal is cleared"),
- el("li", "host: Reference to the host element/scope"),
- el("li", "defined: Stack trace information for debugging"),
- el("li", "readonly: Boolean flag indicating if the signal is read-only")
+ el("li", t`listeners: A Set of functions called when the signal value changes`),
+ el("li", t`actions: Custom actions that can be performed on the signal`),
+ el("li", t`onclear: Functions to run when the signal is cleared`),
+ el("li", t`host: Reference to the host element/scope`),
+ el("li", t`defined: Stack trace information for debugging`),
+ el("li", t`readonly: Boolean flag indicating if the signal is read-only`)
),
el("p").append(...T`
…to determine the current value of the signal, call ${el("code", "signal.valueOf()")}.
`),
el("p").append(...T`
You can inspect (host) element relationships and bindings with signals in the DevTools console using
- ${el("code", "$0.__dde_reactive")} (for currently selected element). In the console you will see a list of
- ${el("code", "[ [ signal, listener ], element, property ]")}, where:
+ ${el("code", "$0.__dde_reactive")} (for currently selected element). In the console you will see a list of
+ ${el("code", `[ [ signal, listener ], element, property ]`)}, where:
`),
el("ul").append(
- el("li", "signal — the signal triggering the changes"),
- el("li", "listener — the listener function (this is an internal function for dd)"),
- el("li", "element — the DOM element that is bound to the signal"),
- el("li", "property — the attribute or property name which is changing based on the signal"),
+ el("li", t`signal — the signal triggering the changes`),
+ el("li", t`listener — the listener function (this is an internal function for dd)`),
+ el("li", t`element — the DOM element that is bound to the signal`),
+ el("li", t`property — the attribute or property name which is changing based on the signal`),
),
el("p").append(...T`
- …the structure of \`__dde_reactive\` utilizes the browser's behavior of packing the first field,
+ …the structure of \`__dde_reactive\` utilizes the browser’s behavior of packing the first field,
so you can see the element and property that changes in the console right away.
`),
diff --git a/docs/p08-extensions.html.js b/docs/p08-extensions.html.js
index 46ad1a4..3b00db6 100644
--- a/docs/p08-extensions.html.js
+++ b/docs/p08-extensions.html.js
@@ -25,8 +25,8 @@ export function page({ pkg, info }){
el(h3, t`DOM Element Extensions with Addons`),
el("p").append(...T`
The primary method for extending DOM elements in dd is through the Addon pattern.
- Addons are functions that take an element and applying some functionality to it. This pattern enables a
- clean, functional approach to element enhancement.
+ Addons are functions that take an element and applying some functionality to it. This pattern enables
+ a clean, functional approach to element enhancement.
`),
el("div", { className: "callout" }).append(
el("h4", t`What are Addons?`),
@@ -34,60 +34,60 @@ export function page({ pkg, info }){
Addons are simply functions with the signature: (element) => void. They:
`),
el("ul").append(
- el("li", t`Accept a DOM element as input`),
+ el("li", t`Accept a DOM element as input`),
el("li", t`Apply some behavior, property, or attribute to the element`),
)
),
el(code, { content: `
-// Basic structure of an addon
-function myAddon(config) {
- return function(element) {
- // Apply functionality to element
- element.dataset.myAddon = config.option;
- };
-}
+ // Basic structure of an addon
+ function myAddon(config) {
+ return function(element) {
+ // Apply functionality to element
+ element.dataset.myAddon = config.option;
+ };
+ }
-// Using an addon
-el("div", { id: "example" }, myAddon({ option: "value" }));
- `.trim(), page_id }),
+ // Using an addon
+ el("div", { id: "example" }, myAddon({ option: "value" }));
+ `, page_id }),
el(h3, t`Resource Cleanup with Abort Signals`),
el("p").append(...T`
When extending elements with functionality that uses resources like event listeners, timers,
- or external subscriptions, it's critical to clean up these resources when the element is removed
+ or external subscriptions, it’s critical to clean up these resources when the element is removed
from the DOM. dd provides utilities for this through AbortSignal integration.
`),
el("div", { className: "tip" }).append(
el("p").append(...T`
- The ${el("code", "scope.signal")} property creates an AbortSignal that automatically
- triggers when an element is disconnected from the DOM, making cleanup much easier to manage.
+ The ${el("code", "scope.signal")} property creates an AbortSignal that automatically
+ triggers when an element is disconnected from the DOM, making cleanup much easier to manage.
`)
),
el(code, { content: `
-// Third-party library addon with proper cleanup
-function externalLibraryAddon(config, signal) {
- return function(element) {
- // Initialize the third-party library
- const instance = new ExternalLibrary(element, config);
+ // Third-party library addon with proper cleanup
+ function externalLibraryAddon(config, signal) {
+ return function(element) {
+ // Initialize the third-party library
+ const instance = new ExternalLibrary(element, config);
- // Set up cleanup when the element is removed
- signal.addEventListener('abort', () => {
- instance.destroy();
- });
+ // Set up cleanup when the element is removed
+ signal.addEventListener('abort', () => {
+ instance.destroy();
+ });
- return element;
- };
-}
-// dde component
-function Component(){
- const { signal }= scope;
- return el("div", null, externalLibraryAddon({ option: "value" }, signal));
-}
- `.trim(), page_id }),
+ return element;
+ };
+ }
+ // dde component
+ function Component(){
+ const { signal }= scope;
+ return el("div", null, externalLibraryAddon({ option: "value" }, signal));
+ }
+ `, page_id }),
el(h3, t`Building Library-Independent Extensions`),
el("p").append(...T`
- When creating extensions, it's a good practice to make them as library-independent as possible.
+ When creating extensions, it’s a good practice to make them as library-independent as possible.
This approach enables better interoperability and future-proofing.
`),
el("div", { className: "illustration" }).append(
@@ -96,37 +96,37 @@ function Component(){
el("div", { className: "tab" }).append(
el("h5", t`✅ Library-Independent`),
el(code, { content: `
-function enhancementElement({ signal, ...config }) {
- // do something
- return function(element) {
- // do something
- signal.addEventListener('abort', () => {
- // do cleanup
- });
- };
-}
-`.trim(), page_id })
+ function enhancementElement({ signal, ...config }) {
+ // do something
+ return function(element) {
+ // do something
+ signal.addEventListener('abort', () => {
+ // do cleanup
+ });
+ };
+ }
+ `, page_id })
),
el("div", { className: "tab" }).append(
el("h5", t`⚠️ Library-Dependent`),
el(code, { content: `
-// Tightly coupled to dd
-function enhancementElement(config) {
- return function(element) {
- // do something
- on.disconnected(()=> {
- // do cleanup
- })(element);
- };
-}
- `.trim(), page_id })
+ // Tightly coupled to dd
+ function enhancementElement(config) {
+ return function(element) {
+ // do something
+ on.disconnected(()=> {
+ // do cleanup
+ })(element);
+ };
+ }
+ `, page_id })
)
)
),
el(h3, t`Signal Extensions and Future Compatibility`),
el("p").append(...T`
- Unlike DOM elements, signal functionality in dd currently lacks a standardized
+ Unlike DOM elements, signal functionality in dd currently lacks a standardized
way to create library-independent extensions. This is because signals are implemented
differently across libraries.
`),
@@ -143,30 +143,27 @@ function enhancementElement(config) {
future migration easier.
`),
el(code, { content: `
-// Signal extension with clear interface
-function createEnhancedSignal(initialValue) {
- const signal = S(initialValue);
+ // Signal extension with clear interface
+ function createEnhancedSignal(initialValue) {
+ const signal = S(initialValue);
- // Extension functionality
- const increment = () => signal.set(signal.get() + 1);
- const decrement = () => signal.set(signal.get() - 1);
+ // Extension functionality
+ const increment = () => signal.set(signal.get() + 1);
+ const decrement = () => signal.set(signal.get() - 1);
- // Return the original signal with added methods
- return Object.assign(signal, {
- increment,
- decrement
- });
-}
+ // Return the original signal with added methods
+ return { signal, increment, decrement };
+ }
-// Usage
-const counter = createEnhancedSignal(0);
-el("button")({ onclick: () => counter.increment() }, "Increment");
-el("div", S.text\`Count: \${counter}\`);
- `.trim(), page_id }),
+ // Usage
+ const counter = createEnhancedSignal(0);
+ el("button", { textContent: "Increment", onclick: () => counter.increment() });
+ el("div", S.text\`Count: \${counter}\`);
+ `, page_id }),
el(h3, t`Using Signals Independently`),
el("p").append(...T`
- While signals are tightly integrated with DDE's DOM elements, you can also use them independently.
+ While signals are tightly integrated with DDE’s DOM elements, you can also use them independently.
This can be useful when you need reactivity in non-UI code or want to integrate with other libraries.
`),
el("p").append(...T`
@@ -174,37 +171,39 @@ el("div", S.text\`Count: \${counter}\`);
`),
el("ol").append(
el("li").append(...T`
- ${el("strong", "Standard import")}: ${el("code", "import { S } from \"deka-dom-el/signals\";")}
- — This automatically registers signals with DDE's DOM reactivity system
+ ${el("strong", "Standard import")}: ${el("code", `import { S } from "deka-dom-el/signals";`)}
+ — This automatically registers signals with DDE’s DOM reactivity system
`),
el("li").append(...T`
- ${el("strong", "Independent import")}: ${el("code", "import { S } from \"deka-dom-el/src/signals-lib\";")}
+ ${el("strong", "Independent import")}: ${el("code", `import { S } from "deka-dom-el/src/signals-lib";`)}
— This gives you just the signal system without DOM integration
`)
),
- el(code, { content: `// Independent signals without DOM integration
-import { signal as S, isSignal } from "deka-dom-el/src/signals-lib";
+ el(code, { content: `
+ // Independent signals without DOM integration
+ import { signal, isSignal } from "deka-dom-el/src/signals-lib";
-// Create and use signals as usual
-const count = S(0);
-const doubled = S(() => count.get() * 2);
+ // Create and use signals as usual
+ const count = signal(0);
+ const doubled = signal(() => count.get() * 2);
-// Subscribe to changes
-S.on(count, value => console.log(value));
+ // Subscribe to changes
+ signal.on(count, value => console.log(value));
-// Update signal value
-count.set(5); // Logs: 5
-console.log(doubled.get()); // 10`, page_id }),
+ // Update signal value
+ count.set(5); // Logs: 5
+ console.log(doubled.get()); // 10
+ `, page_id }),
el("p").append(...T`
The independent signals API includes all core functionality (${el("code", "S()")}, ${el("code", "S.on()")},
${el("code", "S.action()")}).
`),
- el("div", { class: "callout" }).append(
+ el("div", { className: "callout" }).append(
el("h4", t`When to Use Independent Signals`),
el("ul").append(
el("li", t`For non-UI state management in your application`),
el("li", t`When integrating with other libraries or frameworks`),
- el("li", t`To minimize bundle size when you don't need DOM integration`)
+ el("li", t`To minimize bundle size when you don’t need DOM integration`)
)
),
@@ -247,7 +246,7 @@ console.log(doubled.get()); // 10`, page_id }),
el("dd", t`Prefer compositional approaches with addons over modifying element prototypes`),
el("dt", t`Complex initialization in addons`),
- el("dd", t`Split complex logic into a separate initialization function that the addon can call`)
+ el("dd", t`Split complex logic into a separate initialization function that the addon can call`)
)
)
);
diff --git a/docs/p09-ssr.html.js b/docs/p09-ssr.html.js
index 4225640..b871b45 100644
--- a/docs/p09-ssr.html.js
+++ b/docs/p09-ssr.html.js
@@ -26,10 +26,10 @@ export function page({ pkg, info }){
`)
),
el("p").append(...T`
- dd isn't limited to browser environments. Thanks to its flexible architecture,
+ dd isn’t limited to browser environments. Thanks to its flexible architecture,
it can be used for server-side rendering (SSR) to generate static HTML files.
This is achieved through integration with for example ${el("a", { href: "https://github.com/tmpvar/jsdom",
- textContent: "jsdom" })}, a JavaScript implementation of web standards for Node.js.
+ textContent: "jsdom" })}, a JavaScript implementation of web standards for Node.js.
`),
el("p").append(...T`
Additionally, you might consider using these alternative solutions:
@@ -37,7 +37,7 @@ export function page({ pkg, info }){
el("ul").append(
el("li").append(...T`
${el("a", { href: "https://github.com/capricorn86/happy-dom", textContent: "happy-dom" })} - A JavaScript implementation
- of a web browser without its graphical user interface that's faster than jsdom
+ of a web browser without its graphical user interface that’s faster than jsdom
`),
el("li").append(...T`
${el("a", { href: "https://github.com/WebReflection/linkedom", textContent: "linkedom" })} - A lightweight DOM implementation
@@ -61,40 +61,40 @@ export function page({ pkg, info }){
el(h3, t`How jsdom Integration Works`),
el("p").append(...T`
The jsdom export in dd provides the necessary tools to use the library in Node.js
- by integrating with jsdom. Here's what it does:
+ by integrating with jsdom. Here’s what it does:
`),
el("ol").append(
- el("li", t`Creates a virtual DOM environment in Node.js using jsdom`),
+ el("li", t`Creates a virtual DOM environment in Node.js using jsdom`),
el("li", t`Registers DOM globals like HTMLElement, document, etc. for dd to use`),
- el("li", t`Sets an SSR flag in the environment to enable SSR-specific behaviors`),
- el("li", t`Provides a promise queue system for managing async operations during rendering`),
+ el("li", t`Sets an SSR flag in the environment to enable SSR-specific behaviors`),
+ el("li", t`Provides a promise queue system for managing async operations during rendering`),
el("li", t`Handles DOM property/attribute mapping differences between browsers and jsdom`)
),
el(code, { src: fileURL("./components/examples/ssr/start.js"), page_id }),
el(h3, t`Basic SSR Example`),
el("p").append(...T`
- Here's a simple example of how to use dd for server-side rendering in a Node.js script:
+ Here’s a simple example of how to use dd for server-side rendering in a Node.js script:
`),
el(code, { src: fileURL("./components/examples/ssr/basic-example.js"), page_id }),
- el(h3, t`Building a Static Site Generator`),
+ el(h3, t`Building a Static Site Generator`),
el("p").append(...T`
- You can build a complete static site generator with dd. In fact, this documentation site
- is built using dd for server-side rendering! Here's how the documentation build process works:
+ You can build a complete static site generator with dd. In fact, this documentation site
+ is built using dd for server-side rendering! Here’s how the documentation build process works:
`),
el(code, { src: fileURL("./components/examples/ssr/static-site-generator.js"), page_id }),
el(h3, t`Working with Async Content in SSR`),
el("p").append(...T`
- The jsdom export includes a queue system to handle asynchronous operations during rendering.
+ The jsdom export includes a queue system to handle asynchronous operations during rendering.
This is crucial for components that fetch data or perform other async tasks.
`),
el(code, { src: fileURL("./components/examples/ssr/async-data.js"), page_id }),
el(h3, t`Working with Dynamic Imports for SSR`),
el("p").append(...T`
- When structuring server-side rendering code, a crucial pattern to follow is using dynamic imports
+ When structuring server-side rendering code, a crucial pattern to follow is using dynamic imports
for both the deka-dom-el/jsdom module and your page components.
`),
el("p").append(...T`
@@ -107,7 +107,7 @@ export function page({ pkg, info }){
`),
el("li").append(...T`
${el("strong", "Environment registration timing:")} The jsdom module auto-registers the DOM environment
- when imported, which must happen ${el("em", "after")} you've created your JSDOM instance and
+ when imported, which must happen ${el("em", "after")} you’ve created your JSDOM instance and
${el("em", "before")} you import your components using ${el("code", "import { el } from \"deka-dom-el\";")}.
`),
el("li").append(...T`
@@ -126,9 +126,9 @@ export function page({ pkg, info }){
`),
el("ul").append(
el("li", t`Browser-specific APIs like window.localStorage are not available in jsdom by default`),
- el("li", t`Event listeners added during SSR won't be functional in the final HTML unless hydrated on the client`),
+ el("li", t`Event listeners added during SSR won’t be functional in the final HTML unless hydrated on the client`),
el("li", t`Some DOM features may behave differently in jsdom compared to real browsers`),
- el("li", t`For large sites, you may need to optimize memory usage by creating a new jsdom instance for each page`)
+ el("li", t`For large sites, you may need to optimize memory usage by creating a new jsdom instance for each page`)
),
el("p").append(...T`
For advanced SSR applications, consider implementing hydration on the client-side to restore
@@ -137,7 +137,7 @@ export function page({ pkg, info }){
el(h3, t`Real Example: How This Documentation is Built`),
el("p").append(...T`
- This documentation site itself is built using dd's SSR capabilities.
+ This documentation site itself is built using dd’s SSR capabilities.
The build process collects all page components, renders them with jsdom, and outputs static HTML files.
`),
el(code, { src: fileURL("./components/examples/ssr/static-site-generator.js"), page_id }),
diff --git a/docs/p10-ireland.html.js b/docs/p10-ireland.html.js
index 554d072..733602f 100644
--- a/docs/p10-ireland.html.js
+++ b/docs/p10-ireland.html.js
@@ -30,14 +30,11 @@ export function page({ pkg, info }){
el(h3, t`What Are Ireland Components?`),
el("p").append(...T`
- Ireland components are a special type of documentation component that:
+ Ireland components are a special type of component that:
`),
el("ul").append(
- el("li", t`Display source code with syntax highlighting`),
- el("li", t`Pre-render components on the server during documentation build`),
- el("li", t`Copy component source files to the documentation output`),
- el("li", t`Provide client-side rehydration for interactive demos`),
- el("li", t`Allow users to run and experiment with components in real-time`)
+ el("li", t`Pre-render components on the server during SSR build`),
+ el("li", t`Provide client-side rehydration for the component`),
),
el(h3, t`How Ireland Components Work`),
@@ -55,9 +52,6 @@ export function page({ pkg, info }){
el("li").append(...T`
${el("strong", "Client-side scripting:")} JavaScript code is generated to load and render components
`),
- el("li").append(...T`
- ${el("strong", "User interaction:")} The "Run Component" button dynamically loads and renders the component
- `)
),
el(h3, t`Implementation Architecture`),
@@ -68,11 +62,12 @@ export function page({ pkg, info }){
`),
el(code, { content: `
-// Basic usage of an ireland component
-el(ireland, {
- src: fileURL("./components/examples/path/to/component.js"),
- exportName: "NamedExport", // optional, defaults to "default",
-})`, page_id }),
+ // Basic usage of an ireland component
+ el(ireland, {
+ src: fileURL("./components/examples/path/to/component.js"),
+ exportName: "NamedExport", // optional, defaults to "default",
+ })
+ `, page_id }),
el("p").append(...T`
During the build process (${el("code", "bs/docs.js")}), the following happens:
@@ -82,7 +77,7 @@ el(ireland, {
el("li", t`Component source code is loaded and displayed with syntax highlighting`),
el("li", t`Source files are registered to be copied to the output directory`),
el("li", t`Client-side scripts are generated for each page with ireland components`),
- el("li", t`The component is wrapped in a UI container with controls`)
+ el("li", t`The component is rerendered on the page ready`),
),
el(h3, t`Core Implementation Details`),
@@ -92,174 +87,174 @@ el(ireland, {
el("h4", t`Building SSR`),
el(code, { content: `
-// From bs/docs.js - Server-side rendering engine
-import { createHTMl } from "./docs/jsdom.js";
-import { register, queue } from "../jsdom.js";
-import { path_target, dispatchEvent } from "../docs/ssr.js";
+ // From bs/docs.js - Server-side rendering engine
+ import { createHTMl } from "./docs/jsdom.js";
+ import { register, queue } from "../jsdom.js";
+ import { path_target, dispatchEvent } from "../docs/ssr.js";
-// For each page, render it on the server
-for(const { id, info } of pages) {
- // Create a virtual DOM environment for server-side rendering
- const serverDOM = createHTMl("");
- serverDOM.registerGlobally("HTMLScriptElement");
+ // For each page, render it on the server
+ for(const { id, info } of pages) {
+ // Create a virtual DOM environment for server-side rendering
+ const serverDOM = createHTMl("");
+ serverDOM.registerGlobally("HTMLScriptElement");
- // Register dd with the virtual DOM
- const { el } = await register(serverDOM.dom);
+ // Register dd with the virtual DOM
+ const { el } = await register(serverDOM.dom);
- // Import and render the page component
- const { page } = await import(\`../docs/\${id}.html.js\`);
- serverDOM.document.body.append(
- el(page, { pkg, info }),
- );
+ // Import and render the page component
+ const { page } = await import(\`../docs/\${id}.html.js\`);
+ serverDOM.document.body.append(
+ el(page, { pkg, info }),
+ );
- // Process the queue of asynchronous operations
- await queue();
+ // Process the queue of asynchronous operations
+ await queue();
- // Trigger render event handlers
- dispatchEvent("oneachrender", document);
+ // Trigger render event handlers
+ dispatchEvent("oneachrender", document);
- // Write the HTML to the output file
- s.echo(serverDOM.serialize()).to(path_target.root+id+".html");
-}
+ // Write the HTML to the output file
+ s.echo(serverDOM.serialize()).to(path_target.root+id+".html");
+ }
-// Final build step - trigger SSR end event
-dispatchEvent("onssrend");
-`, page_id }),
+ // Final build step - trigger SSR end event
+ dispatchEvent("onssrend");
+ `, page_id }),
el("h4", t`File Registration`),
el(code, { content: `
-// From docs/ssr.js - File registration system
-export function registerClientFile(url, { head, folder = "", replacer } = {}) {
- // Ensure folder path ends with a slash
- if(folder && !folder.endsWith("/")) folder += "/";
+ // From docs/ssr.js - File registration system
+ export function registerClientFile(url, { head, folder = "", replacer } = {}) {
+ // Ensure folder path ends with a slash
+ if(folder && !folder.endsWith("/")) folder += "/";
- // Extract filename from URL
- const file_name = url.pathname.split("/").pop();
+ // Extract filename from URL
+ const file_name = url.pathname.split("/").pop();
- // Create target directory if needed
- s.mkdir("-p", path_target.root+folder);
+ // Create target directory if needed
+ s.mkdir("-p", path_target.root+folder);
- // Get file content and apply optional replacer function
- let content = s.cat(url);
- if(replacer) content = s.echo(replacer(content.toString()));
+ // Get file content and apply optional replacer function
+ let content = s.cat(url);
+ if(replacer) content = s.echo(replacer(content.toString()));
- // Write content to the output directory
- content.to(path_target.root+folder+file_name);
+ // Write content to the output directory
+ content.to(path_target.root+folder+file_name);
- // If a head element was provided, add it to the document
- if(!head) return;
- head[head instanceof HTMLScriptElement ? "src" : "href"] = file_name;
- document.head.append(head);
-}
-`, page_id }),
+ // If a head element was provided, add it to the document
+ if(!head) return;
+ head[head instanceof HTMLScriptElement ? "src" : "href"] = file_name;
+ document.head.append(head);
+ }
+ `, page_id }),
el("h4", t`Server-Side Rendering`),
el(code, { content: `
-// From docs/components/ireland.html.js - Server-side component implementation
-export function ireland({ src, exportName = "default", props = {} }) {
- // Calculate relative path for imports
- const path = "./"+relative(dir, src.pathname);
+ // From docs/components/ireland.html.js - Server-side component implementation
+ export function ireland({ src, exportName = "default", props = {} }) {
+ // Calculate relative path for imports
+ const path = "./"+relative(dir, src.pathname);
- // Generate unique ID for this component instance
- const id = "ireland-" + generateComponentId(src);
+ // Generate unique ID for this component instance
+ const id = "ireland-" + generateComponentId(src);
- // Create placeholder element
- const element = el.mark({ type: "later", name: ireland.name });
+ // Create placeholder element
+ const element = el.mark({ type: "later", name: ireland.name });
- // Import and render the component during SSR
- queue(import(path).then(module => {
- const component = module[exportName];
- element.replaceWith(el(component, props, mark(id)));
- }));
+ // Import and render the component during SSR
+ queue(import(path).then(module => {
+ const component = module[exportName];
+ element.replaceWith(el(component, props, mark(id)));
+ }));
- // Register client-side hydration on first component
- if(!componentsRegistry.size)
- addEventListener("oneachrender", registerClientPart);
+ // Register client-side hydration on first component
+ if(!componentsRegistry.size)
+ addEventListener("oneachrender", registerClientPart);
- // Store component info for client-side hydration
- componentsRegistry.set(id, {
- src,
- path: dirFE+"/"+path.split("/").pop(),
- exportName,
- props,
- });
+ // Store component info for client-side hydration
+ componentsRegistry.set(id, {
+ src,
+ path: dirFE+"/"+path.split("/").pop(),
+ exportName,
+ props,
+ });
- return element;
-}
+ return element;
+ }
-// Register client-side resources
-function registerClientPart() {
- // Process all component registrations
- const todo = Array.from(componentsRegistry.entries())
- .map(([ id, d ]) => {
- // Copy the component source file to output directory
- registerClientFile(d.src, {
- folder: dirFE,
- // Replace bare imports for browser compatibility
- replacer(file) {
- return file.replaceAll(
- / from "deka-dom-el(\/signals)?";/g,
- \` from "./esm-with-signals.js";\`
- );
- }
- });
- return [ id, d ];
- });
+ // Register client-side resources
+ function registerClientPart() {
+ // Process all component registrations
+ const todo = Array.from(componentsRegistry.entries())
+ .map(([ id, d ]) => {
+ // Copy the component source file to output directory
+ registerClientFile(d.src, {
+ folder: dirFE,
+ // Replace bare imports for browser compatibility
+ replacer(file) {
+ return file.replaceAll(
+ / from "deka-dom-el(\/signals)?";/g,
+ \` from "./esm-with-signals.js";\`
+ );
+ }
+ });
+ return [ id, d ];
+ });
- // Serialize the component registry for client-side use
- const store = JSON.stringify(JSON.stringify(todo));
+ // Serialize the component registry for client-side use
+ const store = JSON.stringify(JSON.stringify(todo));
- // Copy client-side scripts to output
- registerClientFile(new URL("./ireland.js.js", import.meta.url));
- registerClientFile(new URL("../../dist/esm-with-signals.js", import.meta.url), { folder: dirFE });
+ // Copy client-side scripts to output
+ registerClientFile(new URL("./ireland.js.js", import.meta.url));
+ registerClientFile(new URL("../../dist/esm-with-signals.js", import.meta.url), { folder: dirFE });
- // Add import map for package resolution
- document.head.append(
- el("script", { type: "importmap" }).append(\`
-{
- "imports": {
- "deka-dom-el": "./\${dirFE}/esm-with-signals.js",
- "deka-dom-el/signals": "./\${dirFE}/esm-with-signals.js"
- }
-}
- \`.trim())
- );
+ // Add import map for package resolution
+ document.head.append(
+ el("script", { type: "importmap" }).append(\`
+ {
+ "imports": {
+ "deka-dom-el": "./\${dirFE}/esm-with-signals.js",
+ "deka-dom-el/signals": "./\${dirFE}/esm-with-signals.js"
+ }
+ }
+ \`.trim())
+ );
- // Add bootstrap script to load components
- document.body.append(
- el("script", { type: "module" }).append(\`
-import { loadIrelands } from "./ireland.js.js";
-loadIrelands(new Map(JSON.parse(\${store})));
- \`.trim())
- );
-}
-`, page_id }),
+ // Add bootstrap script to load components
+ document.body.append(
+ el("script", { type: "module" }).append(\`
+ import { loadIrelands } from "./ireland.js.js";
+ loadIrelands(new Map(JSON.parse(\${store})));
+ \`.trim())
+ );
+ }
+ `, page_id }),
el("h4", t`Client-Side Hydration`),
el(code, { content: `
-// From docs/components/ireland.js.js - Client-side hydration
-import { el } from "./irelands/esm-with-signals.js";
+ // From docs/components/ireland.js.js - Client-side hydration
+ import { el } from "./irelands/esm-with-signals.js";
-export function loadIrelands(store) {
- // Find all marked components in the DOM
- document.body.querySelectorAll("[data-dde-mark]").forEach(ireland => {
- const { ddeMark } = ireland.dataset;
+ export function loadIrelands(store) {
+ // Find all marked components in the DOM
+ document.body.querySelectorAll("[data-dde-mark]").forEach(ireland => {
+ const { ddeMark } = ireland.dataset;
- // Skip if this component isn't in our registry
- if(!store.has(ddeMark)) return;
+ // Skip if this component isn’t in our registry
+ if(!store.has(ddeMark)) return;
- // Get component information
- const { path, exportName, props } = store.get(ddeMark);
+ // Get component information
+ const { path, exportName, props } = store.get(ddeMark);
- // Dynamically import the component module
- import("./" + path).then(module => {
- // Replace the server-rendered element with the client-side version
- ireland.replaceWith(el(module[exportName], props));
- });
- });
-}
-`, page_id }),
+ // Dynamically import the component module
+ import("./" + path).then(module => {
+ // Replace the server-rendered element with the client-side version
+ ireland.replaceWith(el(module[exportName], props));
+ });
+ });
+ }
+ `, page_id }),
el(h3, t`Live Example`),
el("p").append(...T`
- Here's a live example of an Ireland component showing a standard counter.
+ Here’s a live example of an Ireland component showing a standard counter.
The component is defined in ${el("code", "docs/components/examples/ireland-test/counter.js")} and
rendered with the Ireland component system:
`),
@@ -275,34 +270,11 @@ export function loadIrelands(store) {
}),
el("p").append(...T`
- When the "Run Component" button is clicked, the component is loaded and rendered dynamically.
- The counter state is maintained using signals, allowing for reactive updates as you click
- the buttons to increment and decrement the value.
+ When the page is loaded, the component is also loaded and rendered. The counter state is maintained
+ using signals, allowing for reactive updates as you click the buttons to increment and decrement the
+ value.
`),
- el(h3, t`Creating Your Own Components`),
- el("p").append(...T`
- To create components for use with the Ireland system, follow these guidelines:
- `),
-
- el("ol").append(
- el("li").append(...T`
- ${el("strong", "Export a function:")} Components should be exported as named or default functions
- `),
- el("li").append(...T`
-
- `),
- el("li").append(...T`
- ${el("strong", "Accept props:")} Components should accept a props object, even if not using it
- `),
- el("li").append(...T`
- ${el("strong", "Manage reactivity:")} Use signals for state management where appropriate
- `),
- el("li").append(...T`
- ${el("strong", "Handle cleanup:")} Include any necessary cleanup for event listeners or signals
- `)
- ),
-
el(h3, t`Practical Considerations and Limitations`),
el("p").append(...T`
When implementing Ireland components in real documentation, there are several important
@@ -312,9 +284,9 @@ export function loadIrelands(store) {
el("div", { className: "warning" }).append(
el("h4", t`Module Resolution and Bundling`),
el("p").append(...T`
- The examples shown here use bare module specifiers like ${el("code", "import { el } from \"deka-dom-el\"")}
- which aren't supported in all browsers without importmaps. In a production implementation, you would need to:
- `),
+ The examples shown here use bare module specifiers like ${el("code",
+ `import { el } from "deka-dom-el"`)} which aren’t supported in all browsers without importmaps.
+ In a production implementation, you would need to: `),
el("ol").append(
el("li", t`Replace bare import paths with actual paths during the build process`),
el("li", t`Bundle component dependencies to avoid multiple requests`),
@@ -322,7 +294,7 @@ export function loadIrelands(store) {
),
el("p").append(...T`
In this documentation, we replace the paths with ${el("code", "./esm-with-signals.js")} and provide
- a bundled version of the library, but more complex components might require a dedicated bundling step.
+ a bundled version of the library, but more complex components might require a dedicated bundling step.
`)
),
@@ -333,7 +305,7 @@ export function loadIrelands(store) {
to be extended to:
`),
el("ul").append(
- el("li", t`Detect and analyze all dependencies of a component`),
+ el("li", t`Detect and analyze all dependencies of a component`),
el("li", t`Bundle these dependencies together or ensure they're properly copied to the output directory`),
el("li", t`Handle non-JavaScript assets like CSS, images, or data files`)
)
@@ -345,7 +317,7 @@ export function loadIrelands(store) {
`),
el("ul").append(
- el("li", t`Integrate with a bundler like esbuild, Rollup, or Webpack`),
+ el("li", t`Integrate with a bundler like esbuild, Rollup, or Webpack`),
el("li", t`Add props support for configuring components at runtime`),
el("li", t`Implement module caching to reduce network requests`),
el("li", t`Add code editing capabilities for interactive experimentation`),
@@ -357,7 +329,7 @@ export function loadIrelands(store) {
This documentation site itself is built using the techniques described here,
showcasing how dd can be used to create both the documentation and
the interactive examples within it. The implementation here is simplified for clarity,
- while a production-ready system would need to address the considerations above.
+ while a production-ready system would need to address the considerations above.
`)
);
}