From 57a5ff2dfe04f7b2963e324d86077fe3b5b8184d Mon Sep 17 00:00:00 2001 From: Jan Andrle Date: Thu, 6 Mar 2025 18:26:43 +0100 Subject: [PATCH] :zap: irelands --- bs/docs.js | 3 +- docs/components/code.html.js | 7 +- .../examples/ireland-test/counter.js | 37 ++ docs/components/ireland.html.js | 88 +++++ docs/components/ireland.js.js | 13 + docs/index.html.js | 1 + docs/p09-ssr.html.js | 7 +- docs/p10-ireland.html.js | 360 ++++++++++++++++++ docs/ssr.js | 19 +- index.d.ts | 32 ++ jsdom.js | 2 +- package.json | 3 +- 12 files changed, 556 insertions(+), 16 deletions(-) create mode 100644 docs/components/examples/ireland-test/counter.js create mode 100644 docs/components/ireland.html.js create mode 100644 docs/components/ireland.js.js create mode 100644 docs/p10-ireland.html.js diff --git a/bs/docs.js b/bs/docs.js index 4e6c46d..f9bd3e7 100755 --- a/bs/docs.js +++ b/bs/docs.js @@ -4,7 +4,7 @@ echo("Building static documentation files…"); echo("Preparing…"); import { path_target, pages as pages_registered, styles, dispatchEvent, t } from "../docs/ssr.js"; import { createHTMl } from "./docs/jsdom.js"; -import { register } from "../jsdom.js"; +import { register, queue } from "../jsdom.js"; const pkg= s.cat("package.json").xargs(JSON.parse); if(s.test("-d", path_target.root)){ @@ -31,6 +31,7 @@ for(const { id, info } of pages){ serverDOM.document.body.append( el(page, { pkg, info }), ); + await queue(); echo.use("-R", `Writing ${id}.html…`); dispatchEvent("oneachrender", document); diff --git a/docs/components/code.html.js b/docs/components/code.html.js index 9a697d1..1994fb1 100644 --- a/docs/components/code.html.js +++ b/docs/components/code.html.js @@ -236,12 +236,11 @@ function registerClientPart(page_id){ `), ); - // Register our highlighting script to run after Shiki loads - const scriptElement = el("script", { type: "module" }); - registerClientFile( new URL("./code.js.js", import.meta.url), - scriptElement + { + head: el("script", { type: "module" }), + } ); is_registered[page_id]= true; diff --git a/docs/components/examples/ireland-test/counter.js b/docs/components/examples/ireland-test/counter.js new file mode 100644 index 0000000..9832883 --- /dev/null +++ b/docs/components/examples/ireland-test/counter.js @@ -0,0 +1,37 @@ +import { el } from "deka-dom-el"; +import { S } from "deka-dom-el/signals"; + +const className = "client-side-counter"; +document.body.append( + el("style").append(` +.${className} { + border: 1px dashed #ccc; + padding: 1em; + margin: 1em; +} + `.trim()) +); + +export function CounterStandard() { + // Create reactive state with a signal + const count = S(0); + + // Create UI components that react to state changes + return el("div", { className }).append( + el("h4", "Client-Side Counter"), + el("div", { + // The textContent updates automatically when count changes + textContent: S(() => `Count: ${count.get()}`), + }), + el("div", { className: "controls" }).append( + el("button", { + onclick: () => count.set(count.get() - 1), + textContent: "-", + }), + el("button", { + onclick: () => count.set(count.get() + 1), + textContent: "+", + }) + ) + ); +} diff --git a/docs/components/ireland.html.js b/docs/components/ireland.html.js new file mode 100644 index 0000000..1b2dbc1 --- /dev/null +++ b/docs/components/ireland.html.js @@ -0,0 +1,88 @@ +import { el, queue } from "deka-dom-el"; +import { addEventListener, registerClientFile } from "../ssr.js"; +import { relative } from "node:path"; + +const dir= new URL("./", import.meta.url).pathname; +const dirFE= "irelands"; +// Track all component instances for client-side rehydration +const componentsRegistry = new Map(); +/** + * Creates a component that shows code and its runtime output + * with server-side pre-rendering and client-side rehydration + * + * @param {object} attrs + * @param {URL} attrs.src - Path to the file containing the component + * @param {string} [attrs.exportName="default"] - Name of the export to use + * @param {string} attrs.page_id - ID of the current page + * @param {object} [attrs.props={}] - Props to pass to the component + */ +export function ireland({ src, exportName = "default", props = {} }) { + // relative src against the current directory + const path= "./"+relative(dir, src.pathname); + const id = "ireland-" + generateComponentId(src); + const element = el.mark({ type: "ireland", name: ireland.name }); + queue(import(path).then(module => { + const component = module[exportName]; + element.replaceWith(el(component, props, mark(id))); + })); + + if(!componentsRegistry.size) + addEventListener("oneachrender", registerClientPart); + componentsRegistry.set(id, { + src, + path: dirFE+"/"+path.split("/").pop(), + exportName, + props, + }); + + return element; +} + +function registerClientPart(){ + const todo= Array.from(componentsRegistry.entries()) + .map(([ id, d ]) => { + registerClientFile(d.src, { + folder: dirFE, + // not all browsers support importmap + replacer(file){ + return file + .replaceAll(/ from "deka-dom-el(\/signals)?";/g, ` from "./esm-with-signals.js";`); + } + }); + return [ id, d ]; + }); + const store = JSON.stringify(JSON.stringify(todo)); + registerClientFile(new URL("./ireland.js.js", import.meta.url)); + registerClientFile(new URL("../../dist/esm-with-signals.js", import.meta.url), { folder: dirFE }); + document.head.append( + // not all browsers support importmap + el("script", { type: "importmap" }).append(` +{ + "imports": { + "deka-dom-el": "./${dirFE}/esm-with-signals.js", + "deka-dom-el/signals": "./${dirFE}/esm-with-signals.js" + } +} + `.trim()) + ); + document.body.append( + el("script", { type: "module" }).append(` +import { loadIrelands } from "./ireland.js.js"; +loadIrelands(new Map(JSON.parse(${store}))); + `.trim()) + ) +} +function mark(id) { return el=> el.dataset.ddeMark= id; } +const store_prev= new Map(); +/** @param {URL} src */ +function generateComponentId(src){ + const candidate= parseInt(relative((new URL("..", import.meta.url)).pathname, src.pathname) + .split("") + .map(ch=> ch.charCodeAt(0)) + .join(""), 10) + .toString(36) + .replace(/000+/g, ""); + const count= 1 + ( store_prev.get(candidate) || 0 ); + store_prev.set(candidate, count); + return count.toString()+"-"+candidate; +} diff --git a/docs/components/ireland.js.js b/docs/components/ireland.js.js new file mode 100644 index 0000000..b552395 --- /dev/null +++ b/docs/components/ireland.js.js @@ -0,0 +1,13 @@ +// not all browsers support importmaps +// import { el } from "deka-dom-el"; +import { el } from "./irelands/esm-with-signals.js"; +export function loadIrelands(store) { + document.body.querySelectorAll("[data-dde-mark]").forEach(ireland => { + const { ddeMark }= ireland.dataset; + if(!store.has(ddeMark)) return; + const { path, exportName, props }= store.get(ddeMark); + import("./"+path).then(module => { + ireland.replaceWith(el(module[exportName], props)); + }) + }); +} diff --git a/docs/index.html.js b/docs/index.html.js index c8ea9ee..1de9a71 100644 --- a/docs/index.html.js +++ b/docs/index.html.js @@ -104,6 +104,7 @@ export function page({ pkg, info }){ el("li").append(...T`${el("strong", "Custom Elements")} — Building web components`), el("li").append(...T`${el("strong", "Debugging")} — Tools to help you build and fix your apps`), el("li").append(...T`${el("strong", "Extensions")} — Integrating third-party functionalities`), + el("li").append(...T`${el("strong", "Ireland Components")} — Creating interactive demos with server-side pre-rendering`), el("li").append(...T`${el("strong", "SSR")} — Server-side rendering with DDE`) ), el("p").append(...T` diff --git a/docs/p09-ssr.html.js b/docs/p09-ssr.html.js index a7c5011..843783e 100644 --- a/docs/p09-ssr.html.js +++ b/docs/p09-ssr.html.js @@ -18,9 +18,10 @@ export function page({ pkg, info }){ return el(simplePage, { info, pkg }).append( el("div", { className: "warning" }).append( el("p").append(...T` - This part of the documentation is primarily intended for technical enthusiasts and library authors. - For regular users, this capability will hopefully be covered by third-party libraries or frameworks - that provide simpler SSR integration using deka-dom-el. + This part of the documentation is primarily intended for technical enthusiasts and documentation + authors. It describes an advanced feature, not a core part of the library. Most users will not need to + implement this functionality directly in their applications. This capability will hopefully be covered + by third-party libraries or frameworks that provide simpler SSR integration using deka-dom-el. `) ), el("p").append(...T` diff --git a/docs/p10-ireland.html.js b/docs/p10-ireland.html.js new file mode 100644 index 0000000..b46fd9a --- /dev/null +++ b/docs/p10-ireland.html.js @@ -0,0 +1,360 @@ +import { T, t } from "./utils/index.js"; +export const info= { + title: t`Ireland Components`, + fullTitle: t`Interactive Demo Components with Server-Side Pre-Rendering`, + description: t`Creating live, interactive component examples in documentation with server-side rendering and client-side hydration.`, +}; + +import { el } from "deka-dom-el"; +import { simplePage } from "./layout/simplePage.html.js"; +import { h3 } from "./components/pageUtils.html.js"; +import { code } from "./components/code.html.js"; +import { ireland } from "./components/ireland.html.js"; +/** @param {string} url */ +const fileURL= url=> new URL(url, import.meta.url); + +/** @param {import("./types.js").PageAttrs} attrs */ +export function page({ pkg, info }){ + const page_id= info.id; + return el(simplePage, { info, pkg }).append( + el("div", { className: "warning" }).append( + el("p").append(...T` + This part of the documentation is primarily intended for technical enthusiasts and documentation + authors. It describes an advanced feature, not a core part of the library. Most users will not need to + implement this functionality directly in their applications. This capability will hopefully be covered + by third-party libraries or frameworks that provide simpler SSR integration using deka-dom-el. + `) + ), + + el(h3, t`What Are Ireland Components?`), + el("p").append(...T` + Ireland components are a special type of documentation 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(h3, t`How Ireland Components Work`), + el("p").append(...T` + The Ireland component system consists of several parts working together: + `), + + el("ol").append( + el("li").append(...T` + ${el("strong", "Server-side rendering:")} Components are pre-rendered during the documentation build process + `), + el("li").append(...T` + ${el("strong", "Component registration:")} Source files are copied to the documentation output directory + `), + 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`), + el("p").append(...T` + The core of the Ireland system is implemented in ${el("code", "docs/components/ireland.html.js")}. + It integrates with the SSR build process using the ${el("code", "registerClientFile")} function from ${el("code", "docs/ssr.js")}. + `), + + 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 }), + + el("p").append(...T` + During the build process (${el("code", "bs/docs.js")}), the following happens: + `), + + el("ol").append( + 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(h3, t`Core Implementation Details`), + el("p").append(...T` + Let's look at the key parts of the ireland component implementation: + `), + + 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"; + +// 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 deka-dom-el 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 }), + ); + + // Process the queue of asynchronous operations + await queue(); + + // Trigger render event handlers + dispatchEvent("oneachrender", document); + + // 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 }), + 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 += "/"; + + // Extract filename from URL + const file_name = url.pathname.split("/").pop(); + + // 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())); + + // 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 }), + 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); + + // Generate unique ID for this component instance + const id = "ireland-" + generateComponentId(src); + + // Create placeholder element + const element = el.mark({ type: "ireland", 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))); + })); + + // 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, + }); + + 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 ]; + }); + + // 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 }); + + // 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 }), + 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"; + +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; + + // 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 }), + + el(h3, t`Live Example`), + el("p").append(...T` + 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: + `), + + el(code, { + src: fileURL("./components/examples/ireland-test/counter.js"), + page_id + }), + el(ireland, { + src: fileURL("./components/examples/ireland-test/counter.js"), + exportName: "CounterStandard", + page_id + }), + + 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. + `), + + 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("strong", "Return a DOM element:")} The function should return a valid DOM element created with ${el("code", "el()")} + `), + 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 + considerations to keep in mind: + `), + + 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: + `), + 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`), + el("li", t`Ensure all module dependencies are properly resolved and copied to the output directory`) + ), + 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. + `) + ), + + el("div", { className: "note" }).append( + el("h4", t`Component Dependencies`), + el("p").append(...T` + Real-world components typically depend on multiple modules and assets. The Ireland system would need + to be extended to: + `), + el("ul").append( + 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`) + ) + ), + + el(h3, t`Advanced Usage`), + el("p").append(...T` + The Ireland system can be extended in several ways to address these limitations: + `), + + el("ul").append( + 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`), + el("li", t`Support TypeScript and other languages through transpilation`), + el("li", t`Implement state persistence between runs`) + ), + + el("p").append(...T` + This documentation site itself is built using the techniques described here, + showcasing how deka-dom-el 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. + `) + ); +} diff --git a/docs/ssr.js b/docs/ssr.js index a7349bb..4d151b6 100644 --- a/docs/ssr.js +++ b/docs/ssr.js @@ -13,16 +13,23 @@ export let pages= []; * @typedef registerClientFile * @type {function} * @param {URL} url - * @param {HTMLScriptElement|HTMLLinkElement} [element_head] + * @param {Object} [options] + * @param {HTMLScriptElement|HTMLLinkElement} [options.head] + * @param {string} [options.folder] + * @param {function} [options.replacer] * */ -export function registerClientFile(url, element_head){ +export function registerClientFile(url, { head, folder= "", replacer }= {}){ + if(folder && !folder.endsWith("/")) folder+= "/"; const file_name= url.pathname.split("/").pop(); - s.cat(url).to(path_target.root+file_name); + s.mkdir("-p", path_target.root+folder); + let content= s.cat(url) + if(replacer) content= s.echo(replacer(content.toString())); + content.to(path_target.root+folder+file_name); - if(!element_head) return; - element_head[element_head instanceof HTMLScriptElement ? "src" : "href"]= file_name; + if(!head) return; + head[head instanceof HTMLScriptElement ? "src" : "href"]= file_name; document.head.append( - element_head + head ); } diff --git a/index.d.ts b/index.d.ts index 0950525..011cbdb 100644 --- a/index.d.ts +++ b/index.d.ts @@ -72,6 +72,17 @@ export function assignAttribute[ATT] type ExtendedHTMLElementTagNameMap= HTMLElementTagNameMap & CustomElementTagNameMap; +export namespace el { + /** + * Creates a marker comment for elements + * + * @param {{ type: "component"|"reactive"|"ireland"|"later", name?: string, host?: "this"|"parentElement" }} attrs - Marker attributes + * @param {boolean} [is_open=false] - Whether the marker is open-ended + * @returns {Comment} Comment node marker + */ + export function mark(attrs: { type: "component"|"reactive"|"ireland"|"later", name?: string, host?: "this"|"parentElement" }, is_open?: boolean): Comment; +} + export function el< A extends ddeComponentAttributes, EL extends SupportedElement | ddeDocumentFragment @@ -251,6 +262,27 @@ export function customElementWithDDE HTMLElement)>(custom_e export function lifecyclesToEvents HTMLElement)>(custom_element: EL): EL export function observedAttributes(custom_element: HTMLElement): Record +/** + * This is used primarly for server side rendering. To be sure that all async operations + * are finished before the page is sent to the client. + * ``` + * // on component + * function component(){ + * … + * queue(fetch(...).then(...)); + * } + * + * // building the page + * async function build(){ + * const { component }= await import("./component.js"); + * document.body.append(el(component)); + * await queue(); + * retutn document.body.innerHTML; + * } + * ``` + * */ +export function queue(promise?: Promise): Promise; + /* TypeScript MEH */ declare global{ type ddeAppend= (...nodes: (Node | string)[])=> el; diff --git a/jsdom.js b/jsdom.js index 00d5a2d..8344ae4 100644 --- a/jsdom.js +++ b/jsdom.js @@ -17,7 +17,7 @@ env.setDeleteAttr= function(obj, prop, value){ if(value) return obj.setAttribute(prop, ""); obj.removeAttribute(prop); }; -const keys= { H: "HTMLElement", S: "SVGElement", F: "DocumentFragment", M: "MutationObserver", D: "document" }; +const keys= { H: "HTMLElement", S: "SVGElement", F: "DocumentFragment", D: "document" }; let env_bk= {}; let dom_last; diff --git a/package.json b/package.json index 42a3ebf..37ef1c4 100644 --- a/package.json +++ b/package.json @@ -100,5 +100,6 @@ "jshint": "~2.13", "nodejsscript": "^1.0.2", "size-limit-node-esbuild": "~0.3" - } + }, + "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e" }