resize-iframe 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# resize-iframe
+
+Iframes that size themselves to their content, cross-origin included. One script on
+each page, no build step, no dependencies, MIT.
+
+- 📐 Auto-resizes on content, DOM, style, font, image and viewport changes
+- ↔️ Vertical, horizontal, or both
+- 🔒 Messages matched against the frame's own window, which cannot be forged
+- 🍪 Storage Access API support for third-party embeds
+- 🧩 Use `iframeResize()` or the `<resize-iframe>` element
+- 📦 ~5KB unminified, across both files
+
+## Installation
+
+```bash
+npm install resize-iframe
+```
+
+Or from a CDN — the parent page needs `resize-iframe.js`, the framed page needs
+`resize-iframe-child.js`:
+
+```html
+<script type="module" src="https://unpkg.com/resize-iframe/resize-iframe.js"></script>
+<script src="https://unpkg.com/resize-iframe/resize-iframe-child.js"></script>
+```
+
+## Setting up the parent page
+
+Give the iframe a percentage width and an initial height, then let the library
+control the other dimension. Starting at `100vh` makes loading look smoother — the
+content below the iframe only appears once it has sized itself.
+
+```html
+<style>
+  #myIframe { width: 100%; height: 100vh; }
+</style>
+
+<iframe id="myIframe" src="https://anotherdomain.com/iframe.html"></iframe>
+
+<script type="module">
+  import { iframeResize } from 'resize-iframe';
+
+  const [frame] = iframeResize({ direction: 'vertical' }, '#myIframe');
+</script>
+```
+
+`iframeResize(options, target)` takes a CSS selector, an element, or a list of
+elements, and returns one handle per iframe. Both arguments are optional — with no
+target it binds every iframe on the page.
+
+Or use the element, which calls `iframeResize` for you:
+
+```html
+<script type="module" src="https://unpkg.com/resize-iframe/resize-iframe.js"></script>
+
+<resize-iframe src="https://anotherdomain.com/iframe.html" title="Pricing table"></resize-iframe>
+```
+
+## Setting up the child page
+
+```html
+<script src="https://unpkg.com/resize-iframe/resize-iframe-child.js"></script>
+```
+
+That alone auto-resizes the frame. A cross-origin parent cannot measure your
+content, so without this script nothing happens — the parent logs a warning after
+five seconds saying exactly that.
+
+The script tag takes two optional attributes:
+
+| Attribute            | Default              | Description                                          |
+| -------------------- | -------------------- | ---------------------------------------------------- |
+| `data-parent-origin` | `*`                  | Only report size to this embedder                    |
+| `data-size-selector` | `[data-iframe-size]` | Measure these elements instead of the body's children |
+
+Marking your content wrapper with `data-iframe-size` is the fix for a page that
+measures larger than it looks — an overlay, a decorative element, a stray margin.
+
+## Third-party embedding and cookies
+
+Once your page is embedded on someone else's domain, browsers partition its
+storage: cookies set first-party are invisible, so sessions and logins break before
+sizing is ever the problem. The
+[Storage Access API](https://developer.mozilla.org/en-US/docs/Web/API/Storage_Access_API)
+is the way back, and the child script wires it up.
+
+**Parent** — grant the permission and, if you sandbox, the matching token:
+
+```html
+<resize-iframe
+  src="https://embed.example.com/app"
+  allow="storage-access"
+  sandbox="allow-scripts allow-same-origin allow-storage-access-by-user-activation">
+</resize-iframe>
+```
+
+**Child** — probe on load and, if access is missing, ask for it from a click:
+
+```html
+<button id="continue" hidden>Continue</button>
+
+<script>
+  addEventListener('load', async () => {
+    if (await parentIframe.hasStorageAccess()) return;
+
+    continue.hidden = false;
+    continue.onclick = async () => {
+      if (await parentIframe.requestStorageAccess()) location.reload();
+    };
+  });
+</script>
+```
+
+Three things decide whether this works, none of them optional:
+
+1. **A user gesture inside the frame.** The request is denied outright without a
+   click or tap in the embedded page. The parent cannot supply one for you, which
+   is why the button has to live in the child.
+2. **A prior first-party visit.** Browsers only grant access to sites the user has
+   used directly. If your embed can be a user's first contact with your domain,
+   open it in a popup or new tab first, let them interact, then request access.
+3. **Reload after granting.** Anything your page read at startup ran without
+   cookies. Reloading is cruder than re-fetching, and far easier to get right.
+
+Probe the API, never the browser. Safari and Chrome both partition storage, and a
+`/safari/i.test(navigator.userAgent)` gate silently skips the prompt everywhere
+else — the failure is invisible, because the page loads fine and just acts logged
+out.
+
+The parent is told the outcome and can render its own fallback:
+
+```javascript
+iframeResize({
+  onStorageAccess: ({ hasAccess }) => {
+    if (!hasAccess) showOpenInNewTabLink();
+  },
+});
+```
+
+## Options
+
+| Option            | Default      | Description                                                           |
+| ----------------- | ------------ | --------------------------------------------------------------------- |
+| `direction`       | `'vertical'` | `'vertical'`, `'horizontal'`, `'both'`, or `'none'`                    |
+| `offsetSize`      | `0`          | Pixels added to the computed size, positive or negative                |
+| `warningTimeout`  | `5000`       | Warn if the frame has not responded in this many ms; `0` to silence it |
+| `onReady`         | —            | `(iframe) => void`, called on the first size message                   |
+| `onResized`       | —            | `({ iframe, height, width }) => void`                                  |
+| `onMessage`       | —            | `({ iframe, message }) => void`                                        |
+| `onStorageAccess` | —            | `({ iframe, hasAccess }) => void`                                      |
+
+With `direction: 'both'` give your content an intrinsic width, or a `width: 100%`
+layout will chase the frame it is being measured in.
+
+There is no `checkOrigin` option. Messages are matched against the frame's own
+window, which the browser sets and a page cannot forge, and that holds even after
+the frame navigates to another domain — the case an origin allowlist has to be
+turned off for.
+
+## Element attributes
+
+| Attribute     | Default            | Description                              |
+| ------------- | ------------------ | ---------------------------------------- |
+| `src`         | —                  | URL to embed                             |
+| `title`       | `Embedded content` | Accessible name for the iframe           |
+| `direction`   | `vertical`         | As above                                 |
+| `offset-size` | `0`                | As above                                 |
+| `min-h`       | —                  | Minimum height constraint                |
+| `max-h`       | —                  | Maximum height constraint                |
+| `allow`       | —                  | Passed through, e.g. `storage-access`    |
+| `sandbox`     | —                  | Passed through                           |
+
+## Methods and events
+
+Parent, on the handle returned by `iframeResize` (also at `iframe.iframeResizer`):
+
+```javascript
+frame.sendMessage({ hello: 'world' }, 'https://anotherdomain.com');
+frame.disconnect(); // call before removing the iframe from the page
+```
+
+Child, on `window.parentIframe`:
+
+```javascript
+parentIframe.sendMessage('ping'); // → parent's onMessage / 'frame-message' event
+parentIframe.autoResize(false); // pause resizing; returns the current state
+parentIframe.resize(); // nudge, for a change neither observer sees
+parentIframe.hasStorageAccess(); // → Promise<boolean>
+parentIframe.requestStorageAccess(); // → Promise<boolean>, from a click handler
+```
+
+Events fire on the iframe and bubble, so `<resize-iframe>` re-emits them:
+
+```javascript
+document.querySelector('resize-iframe').addEventListener('resize', (e) => {
+  console.log(`Frame is now ${e.detail.height}px tall`);
+});
+```
+
+`ready`, `resize`, `frame-message`, and `storage-access` are available.
+
+## TypeScript
+
+Types ship with the package. JSX typing for the element is picked up automatically
+by React 18 and below, Preact, and Solid. React 19 reads `React.JSX` instead, so
+add this once:
+
+```ts
+import type { ResizeIframeAttributes } from 'resize-iframe';
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'resize-iframe': ResizeIframeAttributes;
+    }
+  }
+}
+```
+
+## Testing
+
+```bash
+npx serve
+```
+
+Open `resize-iframe-test.html`; it prints ten PASS lines.
+
+## Browser Support
+
+- Chrome/Edge 80+
+- Firefox 75+
+- Safari 13.1+
+
+Storage Access API support is probed at runtime, so browsers without it simply
+report access as granted.
+
+## Licence
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "resize-iframe",
+  "version": "0.1.0",
+  "description": "Iframes that size themselves to their content, cross-origin included. No build step, no dependencies.",
+  "type": "module",
+  "main": "resize-iframe.js",
+  "module": "resize-iframe.js",
+  "types": "resize-iframe.d.ts",
+  "files": [
+    "resize-iframe.js",
+    "resize-iframe-child.js",
+    "resize-iframe.d.ts"
+  ],
+  "keywords": [
+    "iframe",
+    "iframe-resizer",
+    "resize",
+    "web-components",
+    "custom-element",
+    "postmessage",
+    "storage-access",
+    "third-party-cookies"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jagreehal/resize-iframe"
+  },
+  "author": "Jag Reehal <jag@jagreehal.com>",
+  "license": "MIT"
+}

package/resize-iframe-child.js

@@ -0,0 +1,113 @@
+// Load this inside the framed page:
+//   <script src=".../resize-iframe-child.js"></script>
+// Optional attributes on that script tag:
+//   data-parent-origin="https://parent.example"  report size only to that embedder
+//   data-size-selector=".content"                measure these elements instead
+// Or mark elements in the page with data-iframe-size to the same effect.
+const config = document.currentScript?.dataset ?? {};
+const targetOrigin = config.parentOrigin || '*';
+const sizeSelector = config.sizeSelector || '[data-iframe-size]';
+
+const start = () => {
+  let last = { height: 0, width: 0 };
+  let queued = false;
+  let auto = true;
+
+  // Measure the bottom and right edges of the marked elements, or of body's
+  // children. Never body itself: it stretches to fill the frame in quirks mode
+  // or under `body { height: 100% }`, which ratchets the frame larger and never
+  // lets it shrink back.
+  // ponytail: body's own bottom/right padding and margin are ignored — zero them
+  // if that gap matters, or wrap your content and mark it with data-iframe-size.
+  const measure = () => {
+    const marked = document.querySelectorAll(sizeSelector);
+    const elements = marked.length ? marked : document.body.children;
+    if (!elements.length) {
+      const body = document.body.getBoundingClientRect();
+      return { height: Math.ceil(body.bottom), width: Math.ceil(body.right) };
+    }
+    let height = 0;
+    let width = 0;
+    for (const element of elements) {
+      const box = element.getBoundingClientRect();
+      height = Math.max(height, box.bottom);
+      width = Math.max(width, box.right);
+    }
+    return { height: Math.ceil(height), width: Math.ceil(width) };
+  };
+
+  const post = () => {
+    queued = false;
+    const size = measure();
+    if (size.height === last.height && size.width === last.width) return;
+    last = size;
+    parent.postMessage({ 'resize-iframe': size }, targetOrigin);
+  };
+
+  // Batch to one measurement per frame: mutations arrive in bursts and every
+  // measure() forces a layout.
+  const schedule = () => {
+    if (queued || !auto) return;
+    queued = true;
+    requestAnimationFrame(post);
+  };
+
+  // ResizeObserver catches reflow (images, fonts, viewport). MutationObserver
+  // catches DOM and style changes, which the observer misses entirely whenever
+  // body is stretched to the frame and so never changes size itself.
+  new ResizeObserver(schedule).observe(document.body);
+  new MutationObserver(schedule).observe(document.body, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    characterData: true,
+  });
+  addEventListener('load', schedule); // images and fonts landing late
+
+  // Third-party cookies: an embedded page gets partitioned storage until the user
+  // grants access. Probe the API rather than sniffing the browser — Safari and
+  // Chrome both partition, and which browsers do is not a stable list.
+  const hasStorageAccess = () =>
+    document.hasStorageAccess?.().catch(() => false) ?? Promise.resolve(true);
+
+  const reportStorageAccess = async () => {
+    const access = await hasStorageAccess();
+    parent.postMessage({ 'resize-iframe-storage': { hasAccess: access } }, targetOrigin);
+    return access;
+  };
+
+  window.parentIframe = {
+    autoResize(state) {
+      if (state !== undefined) auto = state;
+      if (auto) schedule();
+      return auto;
+    },
+    resize() {
+      post(); // nudge, for the rare change neither observer sees
+    },
+    sendMessage(message, origin = targetOrigin) {
+      parent.postMessage({ 'resize-iframe-message': message }, origin);
+    },
+    hasStorageAccess,
+    // MUST be called from a click or tap handler in this page: the browser denies
+    // the request without a user gesture here, and the parent cannot supply one.
+    // Reload afterwards if your page reads cookies during startup.
+    async requestStorageAccess() {
+      if (!document.requestStorageAccess) return true;
+      try {
+        await document.requestStorageAccess();
+      } catch {
+        // Denied, or the user has never visited this site first-party.
+      }
+      return reportStorageAccess();
+    },
+  };
+
+  reportStorageAccess();
+  post();
+};
+
+if (parent !== window) {
+  if (document.body) start();
+  else addEventListener('DOMContentLoaded', start);
+}

package/resize-iframe.d.ts

@@ -0,0 +1,76 @@
+export interface ResizeIframeOptions {
+  /** Which dimension the library controls. Default 'vertical'. */
+  direction?: 'vertical' | 'horizontal' | 'both' | 'none';
+  /** Pixels added to the computed size, positive or negative. Default 0. */
+  offsetSize?: number;
+  /** Warn if the frame has not responded in this many ms. 0 disables. Default 5000. */
+  warningTimeout?: number;
+  onReady?: (iframe: HTMLIFrameElement) => void;
+  onResized?: (data: {
+    iframe: HTMLIFrameElement;
+    height: number;
+    width: number;
+  }) => void;
+  onMessage?: (data: { iframe: HTMLIFrameElement; message: unknown }) => void;
+  onStorageAccess?: (data: {
+    iframe: HTMLIFrameElement;
+    hasAccess: boolean;
+  }) => void;
+}
+
+export interface ResizeIframeHandle {
+  /** Call before removing the iframe from the page, or the listener leaks. */
+  disconnect(): void;
+  sendMessage(message: unknown, targetOrigin?: string): void;
+}
+
+/** Binds to a selector, an element, a list of elements, or every iframe on the page. */
+export function iframeResize(
+  options?: ResizeIframeOptions,
+  target?: string | HTMLIFrameElement | HTMLIFrameElement[] | NodeList
+): ResizeIframeHandle[];
+
+/** Available inside the framed page once resize-iframe-child.js has loaded. */
+export interface ParentIframe {
+  autoResize(state?: boolean): boolean;
+  resize(): void;
+  sendMessage(message: unknown, targetOrigin?: string): void;
+  hasStorageAccess(): Promise<boolean>;
+  /** Must be called from a click or tap handler in the framed page. */
+  requestStorageAccess(): Promise<boolean>;
+}
+
+/** Attributes of the <resize-iframe> element. */
+export interface ResizeIframeAttributes {
+  src?: string;
+  title?: string;
+  direction?: 'vertical' | 'horizontal' | 'both' | 'none';
+  'offset-size'?: number | string;
+  'min-h'?: string;
+  'max-h'?: string;
+  allow?: string;
+  sandbox?: string;
+  /** Whatever else the host framework puts on an element: class, ref, key. */
+  [attribute: string]: unknown;
+}
+
+declare global {
+  interface Window {
+    parentIframe?: ParentIframe;
+  }
+
+  interface HTMLElementTagNameMap {
+    'resize-iframe': HTMLElement & {
+      readonly height: string | undefined;
+      sendMessage(message: unknown, targetOrigin?: string): void;
+    };
+  }
+
+  // Picked up by React 18 and below, Preact, and Solid. React 19 moved to
+  // React.JSX — see the README for the one-line augmentation it needs.
+  namespace JSX {
+    interface IntrinsicElements {
+      'resize-iframe': ResizeIframeAttributes;
+    }
+  }
+}

package/resize-iframe.js

@@ -0,0 +1,151 @@
+// Iframes that size themselves to their content, cross-origin included.
+// Two ways in: iframeResize(options, target) for existing iframes, or the
+// <resize-iframe src="..."> element. Both need resize-iframe-child.js in the
+// framed page — a cross-origin parent cannot measure the content itself.
+const DEFAULTS = {
+  direction: 'vertical', // 'vertical' | 'horizontal' | 'both' | 'none'
+  offsetSize: 0,
+  warningTimeout: 5000,
+  onReady: null,
+  onResized: null,
+  onMessage: null,
+  onStorageAccess: null,
+};
+
+const toIframes = (target) => {
+  if (target == null) return [...document.querySelectorAll('iframe')];
+  if (typeof target === 'string') return [...document.querySelectorAll(target)];
+  return Array.isArray(target) || target instanceof NodeList ? [...target] : [target];
+};
+
+export function iframeResize(options = {}, target) {
+  const settings = { ...DEFAULTS, ...options };
+  return toIframes(target).map((iframe) => connect(iframe, settings));
+}
+
+function connect(iframe, settings) {
+  const { direction, offsetSize } = settings;
+  let ready = false;
+
+  const warning = settings.warningTimeout
+    ? setTimeout(() => {
+        if (!ready) {
+          console.warn(
+            `[resize-iframe] no response from ${iframe.src || 'iframe'} — is resize-iframe-child.js loaded in the framed page?`
+          );
+        }
+      }, settings.warningTimeout)
+    : 0;
+
+  const emit = (type, detail) =>
+    iframe.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
+
+  const onMessage = (event) => {
+    // The browser sets event.source, so it cannot be forged: only messages from
+    // this frame's own window get through, wherever it has navigated to. That
+    // covers what iframe-resizer's checkOrigin option does, without the config.
+    if (event.source !== iframe.contentWindow) return;
+    if (typeof event.data !== 'object' || event.data === null) return;
+
+    if ('resize-iframe-message' in event.data) {
+      const message = event.data['resize-iframe-message'];
+      settings.onMessage?.({ iframe, message });
+      emit('frame-message', message);
+      return;
+    }
+
+    if ('resize-iframe-storage' in event.data) {
+      const { hasAccess } = event.data['resize-iframe-storage'];
+      settings.onStorageAccess?.({ iframe, hasAccess });
+      emit('storage-access', { hasAccess });
+      return;
+    }
+
+    const size = event.data['resize-iframe'];
+    if (!size) return;
+    const height = size.height + offsetSize;
+    const width = size.width + offsetSize;
+
+    if (direction === 'vertical' || direction === 'both') iframe.style.height = `${height}px`;
+    if (direction === 'horizontal' || direction === 'both') iframe.style.width = `${width}px`;
+
+    if (!ready) {
+      ready = true;
+      clearTimeout(warning);
+      settings.onReady?.(iframe);
+      emit('ready', { iframe });
+    }
+    settings.onResized?.({ iframe, height, width });
+    emit('resize', { height, width });
+  };
+
+  addEventListener('message', onMessage);
+
+  // Call disconnect() before removing the iframe, or the listener leaks.
+  iframe.iframeResizer = {
+    disconnect() {
+      removeEventListener('message', onMessage);
+      clearTimeout(warning);
+      delete iframe.iframeResizer;
+    },
+    sendMessage(message, targetOrigin = '*') {
+      iframe.contentWindow?.postMessage(message, targetOrigin);
+    },
+  };
+  return iframe.iframeResizer;
+}
+
+class ResizeIframe extends HTMLElement {
+  static get observedAttributes() {
+    return ['src', 'min-h', 'max-h', 'allow', 'sandbox'];
+  }
+
+  connectedCallback() {
+    if (!this.shadowRoot) {
+      this.attachShadow({ mode: 'open' }).innerHTML = `
+        <style>
+          :host { display: block; }
+          iframe { display: block; width: 100%; border: 0; }
+        </style>
+        <iframe part="frame"></iframe>`;
+      this.iframe = this.shadowRoot.querySelector('iframe');
+      // An iframe without an accessible name is a screen reader dead end.
+      this.iframe.title = this.getAttribute('title') || 'Embedded content';
+      for (const name of ResizeIframe.observedAttributes) {
+        this.attributeChangedCallback(name, null, this.getAttribute(name));
+      }
+    }
+    iframeResize(
+      {
+        direction: this.getAttribute('direction') || DEFAULTS.direction,
+        offsetSize: Number(this.getAttribute('offset-size')) || 0,
+      },
+      this.iframe
+    );
+  }
+
+  disconnectedCallback() {
+    this.iframe?.iframeResizer?.disconnect();
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (!this.iframe || newValue === null) return;
+    if (name === 'src') this.iframe.src = newValue;
+    if (name === 'min-h') this.iframe.style.minHeight = newValue;
+    if (name === 'max-h') this.iframe.style.maxHeight = newValue;
+    // Passed through because third-party embeds need them: storage access is
+    // denied outright unless the frame carries allow="storage-access", and a
+    // sandboxed frame also needs allow-storage-access-by-user-activation.
+    if (name === 'allow' || name === 'sandbox') this.iframe.setAttribute(name, newValue);
+  }
+
+  get height() {
+    return this.iframe?.style.height;
+  }
+
+  sendMessage(message, targetOrigin) {
+    this.iframe?.iframeResizer?.sendMessage(message, targetOrigin);
+  }
+}
+
+customElements.define('resize-iframe', ResizeIframe);