popup-button-plugin 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# popup-button-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A tiny, **framework-free** web component: register content by name,
+and `<popup-button name="...">` automatically shows it in a popup when
+clicked. No React/Angular/Vue/Stencil required to use it — works in
+any HTML page as-is, and inside React/Angular/Vue too since it's a
+standard custom element.
+
+See the full design write-up and integration steps in
+[popup-button-prd.md](./popup-button-prd.md) and
+[popup-button-integration-guide.md](./popup-button-integration-guide.md).
+
+## Quick start
+
+```bash
+npm install
+npm run build
+```
+
+```ts
+import { registerButtonContent } from 'popup-button-plugin';
+
+registerButtonContent('save-info', {
+  title: 'Save changes?',
+  body: 'This will overwrite your previous draft.',
+});
+```
+
+```html
+<popup-button name="save-info" label="Save"></popup-button>
+```
+
+Open `examples/index.html` (via a local static server, e.g. `npx serve .`)
+to see it working.
+
+## Why plain text only, no HTML content?
+
+Registered `body` content is inserted as `textContent`/escaped, never
+as raw HTML. This means it can never execute a script, even if the
+content came from somewhere less trusted — safety by default.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { registerButtonContent, getButtonContent, unregisterButtonContent } from './popup-registry';
+export type { PopupContent } from './popup-registry';
+export { PopupButton } from './popup-button';

package/dist/index.js

@@ -0,0 +1,6 @@
+// This is the single file an app imports. Importing it:
+//   1. Registers the <popup-button> custom element (side effect of
+//      the import below — customElements.define runs once).
+//   2. Gives the app the registry functions it needs to call.
+export { registerButtonContent, getButtonContent, unregisterButtonContent } from './popup-registry';
+export { PopupButton } from './popup-button';

package/dist/popup-button.d.ts

@@ -0,0 +1,25 @@
+export declare class PopupButton extends HTMLElement {
+    private isOpen;
+    private content?;
+    constructor();
+    /**
+     * Runs once, the first time this tag is attached to the page.
+     * (Equivalent to a component's "mount"/"componentDidMount".)
+     */
+    connectedCallback(): void;
+    /** Reads the `name` HTML attribute, e.g. <popup-button name="save-info">. */
+    private get buttonName();
+    /** Reads the `label` HTML attribute (button text), with a default. */
+    private get label();
+    /** Runs when the visible <button> inside our shadow DOM is clicked. */
+    private handleButtonClick;
+    /** Runs when the popup's close button or backdrop is clicked. */
+    private handleClose;
+    /**
+     * Rebuilds this element's shadow DOM to match current state
+     * (isOpen / content). There's no automatic re-render like Stencil —
+     * we call this ourselves every time state changes.
+     */
+    private render;
+    private renderPopupMarkup;
+}

package/dist/popup-button.js

@@ -0,0 +1,155 @@
+// =====================================================================
+// <popup-button> — a native Web Component (no framework, no build
+// tool like Stencil needed to USE it — just plain JS/HTML).
+// ---------------------------------------------------------------------
+// WHY THIS FILE EXISTS / WHAT IT DOES:
+// This is the ONE tag the app puts in HTML. On click, it:
+//   1. Looks up content for its `name` attribute in the registry.
+//   2. If found -> shows a popup (modal) with that content.
+//   3. If NOT found -> fires a "popup-content-missing" event (so the
+//      app/dev can catch a typo instead of nothing happening silently).
+//
+// HOW CUSTOM ELEMENTS WORK (since there's no Stencil here to hide it):
+// - A custom element is just a JS class that `extends HTMLElement`.
+// - `customElements.define('popup-button', PopupButton)` registers the
+//   tag name <popup-button> to use this class, globally, once.
+// - `connectedCallback()` runs automatically when the browser inserts
+//   the tag into the page (like a component "mount").
+// - `attachShadow({ mode: 'open' })` gives the element its own isolated
+//   DOM + CSS, so our button/modal styles can't leak out, and page
+//   styles can't accidentally break our popup.
+// =====================================================================
+import { getButtonContent } from './popup-registry';
+export class PopupButton extends HTMLElement {
+    constructor() {
+        super();
+        // Tracks whether the popup is currently visible.
+        this.isOpen = false;
+        /** Runs when the visible <button> inside our shadow DOM is clicked. */
+        this.handleButtonClick = () => {
+            const found = getButtonContent(this.buttonName);
+            if (!found) {
+                // Nothing registered for this name — tell the outside world via
+                // a CustomEvent, instead of failing silently. `bubbles: true` so
+                // the app can listen on a parent element too, not just this tag.
+                this.dispatchEvent(new CustomEvent('popup-content-missing', {
+                    detail: { name: this.buttonName },
+                    bubbles: true,
+                }));
+                return;
+            }
+            this.content = found;
+            this.isOpen = true;
+            this.render();
+        };
+        /** Runs when the popup's close button or backdrop is clicked. */
+        this.handleClose = () => {
+            this.isOpen = false;
+            this.render();
+        };
+        // `mode: 'open'` means outside JS *can* still read this.shadowRoot
+        // if it really needs to (useful for testing); 'closed' would hide it.
+        this.attachShadow({ mode: 'open' });
+    }
+    /**
+     * Runs once, the first time this tag is attached to the page.
+     * (Equivalent to a component's "mount"/"componentDidMount".)
+     */
+    connectedCallback() {
+        this.render();
+    }
+    /** Reads the `name` HTML attribute, e.g. <popup-button name="save-info">. */
+    get buttonName() {
+        var _a;
+        return (_a = this.getAttribute('name')) !== null && _a !== void 0 ? _a : '';
+    }
+    /** Reads the `label` HTML attribute (button text), with a default. */
+    get label() {
+        var _a;
+        return (_a = this.getAttribute('label')) !== null && _a !== void 0 ? _a : 'Click me';
+    }
+    /**
+     * Rebuilds this element's shadow DOM to match current state
+     * (isOpen / content). There's no automatic re-render like Stencil —
+     * we call this ourselves every time state changes.
+     */
+    render() {
+        const shadow = this.shadowRoot;
+        shadow.innerHTML = `
+      <style>${STYLES}</style>
+      <button class="btn">${escapeHtml(this.label)}</button>
+      ${this.isOpen ? this.renderPopupMarkup() : ''}
+    `;
+        // Re-attach listeners every render, since innerHTML = '...' above
+        // destroys and recreates the actual DOM nodes (old listeners are
+        // gone with them).
+        shadow.querySelector('.btn').addEventListener('click', this.handleButtonClick);
+        if (this.isOpen) {
+            shadow.querySelector('.backdrop').addEventListener('click', this.handleClose);
+            shadow.querySelector('.close').addEventListener('click', this.handleClose);
+            // Stop clicks INSIDE the popup box from bubbling to the backdrop
+            // (otherwise clicking the popup content would also close it).
+            shadow.querySelector('.popup').addEventListener('click', (e) => e.stopPropagation());
+        }
+    }
+    renderPopupMarkup() {
+        var _a, _b, _c, _d;
+        const title = (_b = (_a = this.content) === null || _a === void 0 ? void 0 : _a.title) !== null && _b !== void 0 ? _b : '';
+        const body = (_d = (_c = this.content) === null || _c === void 0 ? void 0 : _c.body) !== null && _d !== void 0 ? _d : '';
+        return `
+      <div class="backdrop">
+        <div class="popup">
+          <div class="popup__header">
+            <span class="popup__title">${escapeHtml(title)}</span>
+            <button class="close" aria-label="Close">&times;</button>
+          </div>
+          <div class="popup__body">${escapeHtml(body)}</div>
+        </div>
+      </div>
+    `;
+    }
+}
+// Plain-text content only (see PRD): we escape it before inserting
+// into innerHTML, so registered content is always treated as TEXT,
+// never as HTML/script — this is what keeps this component safe from
+// XSS even though we build markup with innerHTML.
+function escapeHtml(value) {
+    const div = document.createElement('div');
+    div.textContent = value;
+    return div.innerHTML;
+}
+const STYLES = `
+  :host { display: inline-block; font-family: inherit; }
+  .btn {
+    padding: 8px 16px;
+    border-radius: 6px;
+    border: none;
+    background: #2563eb;
+    color: #fff;
+    font-size: 14px;
+    cursor: pointer;
+  }
+  .btn:hover { background: #1d4ed8; }
+  .backdrop {
+    position: fixed; inset: 0;
+    background: rgba(0,0,0,0.5);
+    display: flex; align-items: center; justify-content: center;
+    z-index: 1000;
+  }
+  .popup {
+    background: #fff; border-radius: 10px;
+    min-width: 320px; max-width: 90vw;
+    box-shadow: 0 10px 30px rgba(0,0,0,0.2);
+  }
+  .popup__header {
+    display: flex; align-items: center; justify-content: space-between;
+    padding: 16px; border-bottom: 1px solid #e5e7eb;
+  }
+  .popup__title { font-size: 16px; font-weight: 700; color: #111827; }
+  .close { background: none; border: none; font-size: 20px; cursor: pointer; color: #6b7280; }
+  .popup__body { padding: 16px; color: #374151; }
+`;
+// Registers the <popup-button> tag globally. This file only needs to
+// be imported ONCE anywhere in the app for the tag to start working
+// everywhere on the page.
+customElements.define('popup-button', PopupButton);

package/dist/popup-registry.d.ts

@@ -0,0 +1,20 @@
+/** The shape of content a popup can display. */
+export interface PopupContent {
+    title?: string;
+    body: string;
+}
+/**
+ * Call this once per button `name` (usually right when your app starts)
+ * to say what should appear in the popup for that name.
+ *
+ * Example: registerButtonContent('save-info', { title: 'Save?', body: 'Sure?' })
+ */
+export declare function registerButtonContent(name: string, content: PopupContent): void;
+/**
+ * Used internally by <popup-button> on click, to find what to show.
+ * Returns undefined if nothing was registered for this name — almost
+ * always means a typo somewhere.
+ */
+export declare function getButtonContent(name: string): PopupContent | undefined;
+/** Optional cleanup — e.g. remove a mapping when a page/feature unmounts. */
+export declare function unregisterButtonContent(name: string): void;

package/dist/popup-registry.js

@@ -0,0 +1,34 @@
+// =====================================================================
+// POPUP REGISTRY
+// ---------------------------------------------------------------------
+// WHY THIS FILE EXISTS:
+// The app using this plugin should only have to say, ONCE:
+//   "when a button named X is clicked, show THIS content"
+// We store that (name -> content) mapping here, in memory, so ANY
+// <popup-button> on the page can look it up by its `name` attribute
+// at click time. One shared "address book" for the whole page.
+// =====================================================================
+// Map (not a plain {} object) so a button literally named "toString"
+// or "constructor" can never collide with built-in object properties.
+const registry = new Map();
+/**
+ * Call this once per button `name` (usually right when your app starts)
+ * to say what should appear in the popup for that name.
+ *
+ * Example: registerButtonContent('save-info', { title: 'Save?', body: 'Sure?' })
+ */
+export function registerButtonContent(name, content) {
+    registry.set(name, content);
+}
+/**
+ * Used internally by <popup-button> on click, to find what to show.
+ * Returns undefined if nothing was registered for this name — almost
+ * always means a typo somewhere.
+ */
+export function getButtonContent(name) {
+    return registry.get(name);
+}
+/** Optional cleanup — e.g. remove a mapping when a page/feature unmounts. */
+export function unregisterButtonContent(name) {
+    registry.delete(name);
+}

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "popup-button-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A tiny, standalone, framework-free button-with-popup web component: register content by name, and <popup-button name=\"...\"> automatically shows it when clicked.",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "tsc -p tsconfig.json --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["web-components", "custom-elements", "popup", "modal", "button"],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}