@tillsc/progressive-web-components 0.1.0 → 0.1.1

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@tillsc/progressive-web-components",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Server-first web components.",
   "type": "module",
   "license": "MIT",
-  "files": [
-    "dist"
-  ],
+  "publishConfig": { "access": "public" },
+  "files": [ "dist", "src"],
   "exports": {
     "./all": "./dist/all.js",
     "./all-bs5": "./dist/all-bs5.js",

package/src/core/pwc-children-observer-element.js

@@ -0,0 +1,53 @@
+import {PwcElement} from "./pwc-element.js";
+
+/**
+ * Children observer element.
+ *
+ * Calls onChildrenChanged() on connect and on every subsequent child mutation.
+ *
+ * Modes (static observeMode):
+ * - "children": direct children only
+ * - "tree": full subtree
+ */
+export class PwcChildrenObserverElement extends PwcElement {
+  static observeMode = "children"; // "children" | "tree"
+
+  connectedCallback() {
+    if (this._connected) return;
+    super.connectedCallback();
+    this._startChildrenObserver();
+  }
+
+  disconnectedCallback() {
+    this._stopChildrenObserver();
+    super.disconnectedCallback();
+  }
+
+  onChildrenChanged(_mutations) {}
+
+  /** Run fn() without triggering onChildrenChanged for the resulting DOM mutations. */
+  _withoutChildrenChangedNotification(fn) {
+    fn();
+    this._childrenObserver?.takeRecords();
+  }
+
+  _startChildrenObserver() {
+    const mode = this.constructor.observeMode || "children";
+    const subtree = mode === "tree";
+
+    this._childrenObserver = new MutationObserver((mutations) => {
+      if (!this._connected) return;
+      this.onChildrenChanged(mutations);
+    });
+
+    this._childrenObserver.observe(this, { childList: true, subtree });
+
+    this.onChildrenChanged([]);
+  }
+
+  _stopChildrenObserver() {
+    if (!this._childrenObserver) return;
+    this._childrenObserver.disconnect();
+    this._childrenObserver = null;
+  }
+}

package/src/core/pwc-element.js

@@ -0,0 +1,76 @@
+/**
+ * Base class for progressive-web-components.
+ *
+ * Responsibilities:
+ * - Ensure idempotent lifecycle handling
+ * - Declaratively bind and unbind host-level DOM events
+ * - Provide a consistent cleanup hook
+ *
+ * This is intentionally minimal.
+ * No rendering, no templating, no magic.
+ */
+export class PwcElement extends HTMLElement {
+  /**
+   * List of DOM event types to bind on the host element.
+   * Subclasses may override.
+   *
+   * Example:
+   *   static events = ["click", "input"];
+   */
+  static events = [];
+
+  static registerCss(cssText) {
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(cssText);
+    document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+  }
+
+  connectedCallback() {
+    if (this._connected) return;
+    this._connected = true;
+
+    this._bindEvents();
+  }
+
+  disconnectedCallback() {
+    if (!this._connected) return;
+    this._connected = false;
+
+    this._unbindEvents();
+    this.onDisconnect();
+  }
+
+  /**
+   * Optional cleanup hook for subclasses.
+   */
+  onDisconnect() {}
+
+  /**
+   * Bind declared events using the handleEvent pattern.
+   */
+  _bindEvents() {
+    const events = this.constructor.events ?? [];
+    for (const type of events) {
+      this.addEventListener(type, this);
+    }
+  }
+
+  /**
+   * Unbind all previously declared events.
+   */
+  _unbindEvents() {
+    const events = this.constructor.events ?? [];
+    for (const type of events) {
+      this.removeEventListener(type, this);
+    }
+  }
+
+  /**
+   * Default event handler.
+   * Subclasses are expected to override this method
+   * and route events as needed.
+   */
+  handleEvent(_event) {
+    // intentionally empty
+  }
+}

package/src/core/pwc-sentinel-init-element.js

@@ -0,0 +1,56 @@
+import {PwcElement} from "./pwc-element.js";
+
+/**
+ * Sentinel init element.
+ *
+ * Calls onConnect() once per connection, when a sentinel appears in the light DOM.
+ * Uses a MutationObserver only until ready.
+ *
+ * Subclasses may override sentinelSelector().
+ */
+export class PwcSentinelInitElement extends PwcElement {
+  static sentinelSelector = "pwc-sentinel, [data-pwc-sentinel]";
+
+  connectedCallback() {
+    if (this._connected) return;
+    super.connectedCallback();
+
+    if (this._hasSentinel()) {
+      this.onConnect();
+      return;
+    }
+
+    this._sentinelObserver = new MutationObserver(() => {
+      if (!this._connected) return;
+      if (!this._hasSentinel()) return;
+
+      this._stopSentinelObserver();
+      this.onConnect();
+    });
+
+    // subtree:true so the sentinel can be nested (common with templates/partials)
+    this._sentinelObserver.observe(this, { childList: true, subtree: true });
+  }
+
+  disconnectedCallback() {
+    this._stopSentinelObserver();
+    super.disconnectedCallback();
+  }
+
+  /**
+   * Hook for subclasses.
+   * Called once per connection, when the sentinel is present.
+   */
+  onConnect() {}
+
+  _hasSentinel() {
+    const selector = this.constructor.sentinelSelector || PwcSentinelInitElement.sentinelSelector;
+    return Boolean(this.querySelector(selector));
+  }
+
+  _stopSentinelObserver() {
+    if (!this._sentinelObserver) return;
+    this._sentinelObserver.disconnect();
+    this._sentinelObserver = null;
+  }
+}

package/src/core/pwc-simple-init-element.js

@@ -0,0 +1,25 @@
+import {PwcElement} from "./pwc-element.js";
+
+/**
+ * Simple init element.
+ *
+ * Calls onConnect() once per connection, deferred to a microtask.
+ * Use this when a microtask is sufficient to access server-rendered children.
+ */
+export class PwcSimpleInitElement extends PwcElement {
+  connectedCallback() {
+    if (this._connected) return;
+    super.connectedCallback();
+
+    queueMicrotask(() => {
+      if (!this._connected) return;
+      this.onConnect();
+    });
+  }
+
+  /**
+   * Hook for subclasses.
+   * Called once per connection, after microtask deferral.
+   */
+  onConnect() {}
+}

package/src/core/utils.js

@@ -0,0 +1,9 @@
+export function ensureId(el, prefix = "pwc") {
+  if (!el.id) el.id = `${prefix}-${Math.random().toString(36).slice(2)}`;
+  return el.id;
+}
+
+export function defineOnce(name, classDef) {
+  if (customElements.get(name)) return;
+  customElements.define(name, classDef);
+}

package/src/dialog-opener/INTERNALS.md

@@ -0,0 +1,47 @@
+# Dialog-Opener — Internals
+
+## Architecture
+
+- `findOrCreateDialog(src)` — creates/reuses a `<pwc-modal-dialog>` (or `-bs5`), opens it,
+  places the iframe, and wires up the `this.dialog` / `this.modal` adapter.
+
+The base class never touches DOM rendering directly. Variants own the dialog creation and
+provide a uniform adapter interface (`this.modal.show()` / `this.modal.hide()`).
+
+## Flow: link click to dialog
+
+1. Click on an `<a>` inside the component is intercepted (`handleEvent`)
+2. `prepareIFrameLink()` builds the iframe URL:
+   - collects `input` values as `default` query param
+   - appends `_layout=false`
+3. `findOrCreateDialog(src)` (variant hook) creates the modal and iframe
+4. `enhanceIFrame()` waits for the iframe `load` event, then calls `iFrameLoad()`
+5. `iFrameLoad()` checks the iframe URL:
+   - If `dialog_finished_with` is present → close dialog, trigger reload or navigation
+   - Otherwise → run `moveElementsToOuterActions()`, show iframe
+
+## Move-out mechanism
+
+When `move-out` is set, buttons are **cloned** from the iframe document into the dialog footer.
+The original buttons are hidden. Clicking a cloned button triggers `click()` on the original
+inside the iframe, then hides the iframe (to show a loading state while the form submits).
+
+## Local reload
+
+When the dialog completes and `local-reload` is set:
+
+1. The completion URL is fetched via `fetch()`
+2. The response HTML is parsed with `DOMParser`
+3. The element matching `this.id` is extracted from the response
+4. Its children replace the current component's children
+5. Optionally: `history.pushState` / `replaceState` updates the URL
+6. Optionally: inline `<script>` tags are re-executed (cloned into new elements)
+7. A `pwc-dialog-opener:local-reload` custom event is dispatched
+
+If any step fails, it falls back to full page navigation.
+
+## Modal adapter pattern
+
+The base class expects `this.modal` with `.show()` and `.hide()`. Since both variants use
+`<pwc-modal-dialog>` (which is already open by the time `findOrCreateDialog` returns),
+`show()` is a no-op and `hide()` delegates to `modalDialog.close()`.

package/src/dialog-opener/README.md

@@ -0,0 +1,145 @@
+# `<pwc-dialog-opener>`
+
+Server-first dialog opener web component.
+
+`<pwc-dialog-opener>` enhances existing links to open their targets inside a modal dialog.
+It is designed to work with server-rendered HTML and minimal JavaScript.
+
+The component does **not** use Shadow DOM and relies on stable, explicit markup hooks.
+
+---
+
+## Basic usage
+
+```html
+<pwc-dialog-opener>
+  <a href="/path/to/page">Open</a>
+</pwc-dialog-opener>
+```
+
+Clicking the link opens the target URL inside a dialog using an `<iframe>`.
+
+---
+
+## Attributes
+
+### `close`
+Text for the close button inside the dialog.
+
+```html
+<pwc-dialog-opener close="Cancel">
+```
+
+### `move-out`
+Moves action buttons from the iframe content into the dialog footer.
+
+Supported magic values:
+- `submit`
+- `primary` – **Bootstrap 5 variant only**
+
+```html
+<pwc-dialog-opener move-out="submit">
+```
+
+### `local-reload`
+Enables server-side fragment reload instead of full page navigation when the dialog
+signals completion.
+
+Supported tokens (space-separated):
+- `with-scripts` – re-executes inline scripts in the replaced fragment
+- `replace-url` – updates the browser URL via `history.replaceState`
+- `push-url` – updates the browser URL via `history.pushState`
+
+```html
+<pwc-dialog-opener id="editor" local-reload="with-scripts replace-url">
+```
+
+The element **must have an `id`** for `local-reload` to work.
+
+---
+
+## Dialog completion protocol
+
+The iframe content is considered "finished" when its URL contains the query parameter:
+
+```
+dialog_finished_with=ok
+```
+
+When detected:
+- the dialog closes
+- local reload is attempted (if enabled)
+- otherwise a full page navigation is performed
+
+---
+
+## `default` query parameter
+
+When opening the iframe URL, the component collects values from the **first-level inputs inside**
+`<pwc-dialog-opener>` and appends them as a `default` query parameter.
+
+This mechanism is essential for server-driven workflows where the dialog is used as a
+fallback or completion step.
+
+A common example is an autocomplete or reference selector:
+- the user types a value
+- no matching target exists yet
+- the dialog opens a “create” form
+- the previously entered value is forwarded as a default
+
+Current behavior:
+- reads the values of all `input` elements inside the component
+- ignores empty values
+- concatenates values from multiple inputs into a single `default` query parameter
+
+```html
+<pwc-dialog-opener>
+  <input name="search" value="bar">
+  <a href="/teams/new">Open</a>
+</pwc-dialog-opener>
+```
+
+The iframe will be opened with:
+
+```
+/teams/new?default=bar&_layout=false
+```
+
+---
+
+## Styling
+
+The vanilla variant uses the native `<dialog>` element.
+
+Key CSS hooks:
+- `.pwc-dialog-opener-modal`
+- `.pwc-dialog-opener-body`
+- `.pwc-dialog-opener-footer`
+- `.pwc-dialog-opener-close`
+
+Height can be controlled via CSS variables on the host element:
+
+```css
+pwc-dialog-opener {
+  --pwc-dialog-opener-height: 550px;
+}
+```
+
+---
+
+## Bootstrap 5 variant
+
+A Bootstrap 5 styled variant is provided with the same API:
+
+```html
+<pwc-dialog-opener-bs5>
+  <a href="/path/to/page">Open</a>
+</pwc-dialog-opener-bs5>
+```
+
+Notes:
+- Same attributes and behavior as the vanilla component
+- Uses Bootstrap modal markup and classes
+- Requires Bootstrap 5 JavaScript and CSS to be present
+
+---

package/src/dialog-opener/base.js

@@ -0,0 +1,226 @@
+import { PwcElement } from "../core/pwc-element.js";
+
+export class BaseDialogOpener extends PwcElement {
+  static events = ["click"];
+
+  handleEvent(e) {
+    if (e.type !== "click") return;
+    if (e.defaultPrevented) return;
+
+    const link = e.target.closest("a");
+    if (!link || !this.contains(link)) return;
+
+    e.preventDefault();
+
+    if (this.hasAttribute("local-reload") && !this.id) {
+      console.warn("<pwc-dialog-opener> has local-reload attribute but no id", this);
+    }
+
+    const href = link.getAttribute("href");
+    if (!href) return;
+
+    this.open(href);
+  }
+
+  open(href) {
+    const src = this.prepareIFrameLink(href);
+    this.findOrCreateDialog(src);
+    this.enhanceIFrame().then(() => this.modal.show());
+  }
+
+  prepareIFrameLink(src) {
+    const s = new URL(src, document.location.href);
+
+    const defaultValues = [...this.querySelectorAll("input")]
+      .map((input) => {
+        if (input.value) return input.value;
+        return null;
+      })
+      .filter((item) => item !== null);
+
+    if (defaultValues.length > 0) {
+      s.searchParams.set("default", defaultValues.join(","));
+    }
+
+    s.searchParams.set("_layout", false);
+    return s.toString();
+  }
+
+  // Variant hook: must set this.dialog and this.modal
+  // eslint-disable-next-line no-unused-vars
+  findOrCreateDialog(_src) {
+    throw new Error("BaseDialogOpener: findOrCreateDialog(src) must be implemented by a variant");
+  }
+
+  createIFrame(src) {
+    const iframe = document.createElement("iframe");
+    iframe.src = src;
+
+    iframe.style.width = "100%";
+    iframe.style.height = getComputedStyle(this).getPropertyValue("--pwc-dialog-opener-height").trim() || "550px";
+    iframe.style.display = "none";
+
+    return iframe;
+  }
+
+  enhanceIFrame() {
+    this.iframe = this.dialog.querySelector("iframe");
+    return new Promise((resolve) => {
+      this.iframe.addEventListener("load",
+        (e) => this.iFrameLoad(e).then(resolve));
+    });
+  }
+
+  async iFrameLoad(_e) {
+    let uri;
+    try {
+      uri = new URL(this.iframe.contentWindow.location);
+    } catch (e) {
+      throw new Error(`<pwc-dialog-opener> cannot access iframe location (cross-origin?): ${e.message}`);
+    }
+
+    if (uri.searchParams.has("dialog_finished_with")) {
+      this.modal.hide();
+
+      uri.searchParams.delete("_layout");
+      uri.searchParams.set("dummy", Math.floor(Math.random() * 100000));
+
+      const localReloadWorked = await this.tryLocalReload(uri);
+      if (!localReloadWorked) {
+        window.location.href = uri.toString();
+      }
+      return;
+    }
+
+    this.moveElementsToOuterActions();
+    this.iframe.style.display = "unset";
+  }
+
+  async tryLocalReload(newUri) {
+    const currentUri = new URL(window.location.href);
+    if (
+      currentUri.hostname !== newUri.hostname ||
+      currentUri.pathname !== newUri.pathname ||
+      currentUri.protocol !== newUri.protocol
+    ) {
+      console.log(`<dialog-opener> Warning: local-reload got different base uri (${newUri.toString()}) then window has (${currentUri.toString()}). This might lead to problems, but we'll try it anyway.`);
+    }
+
+    if (this.hasAttribute("local-reload") && this.id) {
+      const localReloadOptionTokens = document.createElement("div").classList;
+      if (this.hasAttribute("local-reload")) localReloadOptionTokens.add(...this.getAttribute("local-reload").split(/\s+/));
+      const localReloadOptions = {
+        replaceUrl: localReloadOptionTokens.contains("replace-url"),
+        pushUrl: localReloadOptionTokens.contains("push-url"),
+        withScripts: localReloadOptionTokens.contains("with-scripts")
+      };
+
+      newUri.searchParams.set("local_reload", this.id);
+
+      const res = await fetch(newUri);
+      if (res.ok) {
+        const html = await res.text();
+        const newDocument = new DOMParser().parseFromString(html, "text/html");
+        const fragment = newDocument.getElementById(this.id);
+
+        if (fragment) {
+          this.replaceChildren(...fragment.childNodes);
+
+          // Optional History API update
+          if (localReloadOptions.replaceUrl || localReloadOptions.pushUrl) {
+
+            if (localReloadOptions.pushUrl) {
+              history.pushState(null, "", newUri);
+            }
+            else if (localReloadOptions.replaceUrl) {
+              history.replaceState(null, "", newUri);
+            }
+          }
+
+          if (localReloadOptions.withScripts) {
+            this.executeInlineScripts(this);
+          }
+
+          this.dispatchEvent(
+            new CustomEvent("pwc-dialog-opener:local-reload", {
+              bubbles: true,
+              detail: { url: newUri.toString() }
+            })
+          );
+
+          return true;
+        }
+        console.log("local-reload not possible, falling back to full reload");
+      }
+    }
+
+    return false;
+  }
+
+  executeInlineScripts(root) {
+    console.log("Executing inline scripts in local-reload fragment", root);
+    const scripts = Array.from(root.querySelectorAll("script"));
+
+    for (const old of scripts) {
+      if (old.src) {
+        console.warn("Ignoring external script in local-reload fragment:", old.src);
+        old.remove();
+        continue;
+      }
+
+      // Re-create script to execute it
+      const s = document.createElement("script");
+      // preserve type if present (default is classic)
+      if (old.type) s.type = old.type;
+      if (old.noModule) s.noModule = true;
+
+      s.textContent = old.textContent || "";
+
+      old.replaceWith(s);
+    }
+  }
+
+  moveElementsToOuterActions() {
+    if (!this.getAttribute("move-out")) return;
+
+    const iframeDoc = this.iframe.contentWindow.document;
+    if (!iframeDoc) return;
+
+    let buttonContainer = this.dialog.querySelector("dialog-opener-buttons");
+    if (!buttonContainer) {
+      buttonContainer = document.createElement("dialog-opener-buttons");
+      this.dialog.querySelector(".pwc-dialog-opener-actions").prepend(buttonContainer);
+    } else {
+      buttonContainer.innerHTML = "";
+    }
+
+    const elements = iframeDoc.querySelectorAll(this._moveOutSelector());
+    for (let i = 0; i < elements.length; i++) {
+      const btn = elements[i];
+
+      const outerBtn = document.createElement(btn.tagName);
+      for (const attr of btn.attributes) {
+        outerBtn.setAttribute(attr.name, attr.value);
+      }
+      outerBtn.innerHTML = btn.innerHTML;
+
+      outerBtn.addEventListener("click", () => {
+        this.iframe.style.display = "none";
+        btn.click();
+      });
+
+      buttonContainer.append(outerBtn);
+
+      btn.style.visibility = "hidden";
+      btn.style.display = "none";
+    }
+  }
+
+  _moveOutSelector() {
+    let selector = this.getAttribute("move-out");
+    if (selector === "submit") {
+      selector = "button[type=submit], input[type=submit]";
+    }
+    return selector;
+  }
+}