Technical review: Document responsive iframe sizing

files/en-us/web/api/window/index.md

@@ -238,6 +238,8 @@ _This interface inherits methods from the {{domxref("EventTarget")}} interface._
   - : Tells the browser that an animation is in progress, requesting that the browser schedule a repaint of the window for the next animation frame.
 - {{domxref("Window.requestIdleCallback()")}}
   - : Enables the scheduling of tasks during a browser's idle periods.
+- {{domxref("Window.requestResize()")}}
+  - : Updates the size information shared by an embedded document with its embedding parent, but only if the embedded document has opted in to sharing its size information.
 - {{domxref("Window.resizeBy()")}}
   - : Resizes the current window by a certain amount.
 - {{domxref("Window.resizeTo()")}}

files/en-us/web/api/window/requestresize/index.md

@@ -0,0 +1,135 @@
+---
+title: "Window: requestResize() method"
+short-title: requestResize()
+slug: Web/API/Window/requestResize
+page-type: web-api-instance-method
+browser-compat: api.Window.requestResize
+---
+
+{{APIRef}}
+
+The **`requestResize()`** method of the {{domxref("Window")}} interface updates the size information shared by an embedded document with its embedding parent, but only if the embedded document has opted in to sharing its size information.
+
+## Syntax
+
+```js-nolint
+requestResize()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+None ({{jsxref("undefined")}}).
+
+### Exceptions
+
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : Thrown if:
+    - The `requestResize()` method was called from a top-level (non-embedded) document.
+    - The embedding element is not an {{htmlelement("iframe")}}.
+    - The embedded document has not opted in to sharing its layout size by including a [`<meta name="responsive-embedded-sizing">`](/en-US/docs/Web/HTML/Reference/Elements/meta/name/responsive-embedded-sizing) tag.
+
+> [!NOTE]
+> If the parent document doesn't set the {{cssxref("frame-sizing")}} CSS property on the embedding `<iframe>`, no exception is thrown, but the `<iframe>` will not be resized.
+
+## Description
+
+For security and privacy reasons, {{htmlelement("iframe")}} elements do not by default expose any information to the parent document about the size of the content in the document they are embedding.
+
+To enable responsive sizing of `<iframe>` elements based on their content, the [`<meta name="responsive-embedded-sizing">`](/en-US/docs/Web/HTML/Reference/Elements/meta/name/responsive-embedded-sizing) tag can be included in an embedded document to opt it in to sharing its size information with the parent document. The {{cssxref("frame-sizing")}} CSS property can then be set on the `<iframe>` to cause it to adopt the same horizontal or vertical size as the embedded document's actual layout size (termed the **internal layout intrinsic size** in the spec). This is useful for avoiding scrollbars on `<iframe>` content so that it fits more seamlessly with its embedder.
+
+To resize the `<iframe>` dynamically as the embedded document changes layout size, you can call the {{domxref("Window.requestResize()")}} method from the embedded document to make it report an updated size, typically from within the event handler that caused its content to change size. If the `<iframe>` is sized using `frame-sizing`, it will then update its size automatically so that it still neatly contains the embeded content.
+
+The embedded document's layout size is automatically reported once when its {{domxref("Document.DOMContentLoaded_event", "DOMContentLoaded")}} event fires, and again when the {{domxref("Window")}} object's {{domxref("Window.load_event", "load")}} event fires. The `requestResize()` method is needed to report subsequent layout size changes.
+
+## Examples
+
+### Using `requestResize()`
+
+Our [`requestResize()` demo](https://mdn.github.io/dom-examples/responsive-iframe-sizing/js-request-resize/) ([see source code](https://github.com/mdn/dom-examples/tree/main/responsive-iframe-sizing/js-request-resize)) demonstrates usage of the `requestResize()` method.
+
+#### HTML
+
+We have two HTML documents. The main `index.html` document contains a heading and an `<iframe>`, into which is embedded the `frame.html` document:
+
+```html
+<h1>Responsive iframes — basic example</h1>
+
+<iframe src="frame.html"></iframe>
+```
+
+The `frame.html` document includes a {{htmlelement("div")}} element with a [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) value of `0` set so that it is focusable. It contains a heading and some paragraphs. The document also includes the `<meta name="responsive-embedded-sizing" />` tag, which opts it in to sharing its content layout size with the parent document.
+
+```html
+<head>
+  ...
+
+  <meta name="responsive-embedded-sizing" />
+
+  ...
+</head>
+<body>
+  <div tabindex="0">
+    <h1>This is my frame</h1>
+    <p>This is the content of my discontent.</p>
+    <p>This is some more content.</p>
+  </div>
+</body>
+```
+
+#### CSS
+
+The `<iframe>` inside `index.html` is given a `frame-sizing` value of `content-block-size`. Because the `<iframe>` has a horizontal `writing-mode`, its `height` will be set to the embedded document's layout height.
+
+```css
+iframe {
+  frame-sizing: content-block-size;
+  border: 2px solid gray;
+}
+```
+
+#### JavaScript
+
+The script inside `frame.html` starts by grabbing a reference to the `<div>` element. It then sets `click` and `keypress` event listeners on the `<div>`, both of which run a custom function called `addParagraph()` when the event fires.
+
+```js
+const divElem = document.querySelector("div");
+divElem.addEventListener("click", addParagraph);
+window.addEventListener("keypress", addParagraph);
+```
+
+The `addParagraph()` function generates a new paragraph element and appends it to the end of the `<div>` as a child, increasing its height. It then calls `requestResize()` so that the new height is reported to the parent document.
+
+```js
+function addParagraph() {
+  const para = document.createElement("p");
+  para.textContent = "New content.";
+  divElem.appendChild(para);
+  window.requestResize();
+}
+```
+
+#### Result
+
+{{EmbedGHLiveSample("responsive-iframe-sizing/js-request-resize/", "100%", 300)}}
+
+Even though no explicit `height` has been set on the `<iframe>`, it is sized to the right height to exactly contain its embedded document, with no scroll bars. Try clicking on the `<div>` or focusing it and pressing a key on the keyboard. As a new paragraph is added to the `<div>`, the `<div>` grows in height, but the `<iframe>` also grows in height to match it.
+
+You can also [load the demo in a separate tab](https://mdn.github.io/dom-examples/responsive-iframe-sizing/js-request-resize/) and view the [source code](https://github.com/mdn/dom-examples/tree/main/responsive-iframe-sizing/js-request-resize).
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("frame-sizing")}} CSS property
+- [CSS box sizing](/en-US/docs/Web/CSS/Guides/Box_sizing) module
+- [`<meta name="responsive-embedded-sizing">`](/en-US/docs/Web/HTML/Reference/Elements/meta/name/responsive-embedded-sizing)

files/en-us/web/css/guides/box_sizing/index.md

@@ -30,6 +30,7 @@ The [logical properties and values module](/en-US/docs/Web/CSS/Guides/Logical_pr
 - {{cssxref("contain-intrinsic-inline-size")}}
 - {{cssxref("contain-intrinsic-size")}}
 - {{cssxref("contain-intrinsic-width")}}
+- {{cssxref("frame-sizing")}}
 - {{cssxref("height")}}
 - {{cssxref("max-height")}}
 - {{cssxref("max-width")}}

files/en-us/web/css/reference/properties/frame-sizing/index.md

@@ -0,0 +1,129 @@
+---
+title: "`frame-sizing` CSS property"
+short-title: frame-sizing
+slug: Web/CSS/Reference/Properties/frame-sizing
+page-type: css-property
+browser-compat: css.properties.frame-sizing
+sidebar: cssref
+---
+
+The **`frame-sizing`** [CSS](/en-US/docs/Web/CSS) property can be used to set an {{htmlelement("iframe")}} element's horizontal or vertical size to equal the layout size of its embedded document in the same dimension, but only if the embedded document has opted in to sharing its size information.
+
+## Syntax
+
+```css
+/* Keyword values */
+frame-sizing: auto;
+frame-sizing: content-width;
+frame-sizing: content-height;
+frame-sizing: content-inline-size;
+frame-sizing: content-block-size;
+
+/* Global values */
+frame-sizing: inherit;
+frame-sizing: initial;
+frame-sizing: revert;
+frame-sizing: revert-layer;
+frame-sizing: unset;
+```
+
+### Values
+
+The `frame-sizing` property value is equal to one of the following keywords:
+
+- `auto`
+  - : The inital value. The `<iframe>` element's size is not affected by the layout size of its embedded document.
+- `content-width`
+  - : The `<iframe>` element's {{cssxref("width")}} is set to the layout width of its embedded document.
+- `content-height`
+  - : The `<iframe>` element's {{cssxref("height")}} is set to the layout height of its embedded document.
+- `content-inline-size`
+  - : The `<iframe>` element's {{cssxref("inline-size")}} is set to the layout size of its embedded document in the inline direction.
+- `content-block-size`
+  - : The `<iframe>` element's {{cssxref("block-size")}} is set to the layout size of its embedded document in the block direction.
+
+## Description
+
+For security and privacy reasons, {{htmlelement("iframe")}} elements do not by default expose any information to the parent document about the size of the content in the document they are embedding.
+
+To enable responsive sizing of {{htmlelement("iframe")}} elements based on their content, the [`<meta name="responsive-embedded-sizing">`](/en-US/docs/Web/HTML/Reference/Elements/meta/name/responsive-embedded-sizing) tag can be included in an embedded document to opt it in to sharing its size information with the parent document. The `frame-sizing` property can then be set on the `<iframe>` to cause it to adopt the same horizontal or vertical size as the embedded document's actual content size (termed the **internal layout intrinsic size** in the spec, but abbreviated to "layout size" in our documentation). This is useful for avoiding scrollbars on `<iframe>` content so that it fits more seamlessly with its embedder.
+
+The `frame-sizing` property can take values of `content-width` or `content-height` to cause the `<iframe>` element's `width` or `height` to adopt the embedded document's layout width or layout height, respectively.
+
+There are also logical equivalents available — `frame-sizing` can take values of `content-inline-size` or `content-block-size` to cause the `<iframe>` element's `inline-size` or `block-size` to adopt the embedded document's inline size or block size, respectively. The block or inline direction is determined by the `<iframe>` element's {{cssxref("writing-mode")}}, not that of the embedded document's content.
+
+To resize the `<iframe>` dynamically as the embedded document changes layout size, you can call the {{domxref("Window.requestResize()")}} method from the embedded document to make it report an updated size.
+
+## Formal definition
+
+{{cssinfo}}
+
+## Formal syntax
+
+{{csssyntax}}
+
+## Examples
+
+### Basic usage
+
+Our [basic responsive `<iframe>` sizing demo](https://mdn.github.io/dom-examples/responsive-iframe-sizing/basic/) ([see source code](https://github.com/mdn/dom-examples/tree/main/responsive-iframe-sizing/basic)) demonstrates usage of the `frame-sizing` property.
+
+#### HTML
+
+We have two HTML documents. The main `index.html` document contains a heading and an `<iframe>`, into which is embedded the `frame.html` document:
+
+```html
+<h1>Responsive iframes — basic example</h1>
+
+<iframe src="frame.html"></iframe>
+```
+
+The `frame.html` document contains a heading and some paragraphs. More significantly, however, it includes the `<meta name="responsive-embedded-sizing" />` tag, which opts it in to sharing its content layout size with the parent document.
+
+```html
+<head>
+  ...
+
+  <meta name="responsive-embedded-sizing" />
+
+  ...
+</head>
+<body>
+  <h1>This is my frame</h1>
+  <p>This is the content of my discontent.</p>
+  <p>This is some more content.</p>
+</body>
+```
+
+#### CSS
+
+The `<iframe>` inside `index.html` is given a `frame-sizing` value of `content-block-size`. Because the `<iframe>` has a horizontal `writing-mode`, its `height` will be set to the embedded document's layout height.
+
+```css
+iframe {
+  frame-sizing: content-block-size;
+  border: 2px solid gray;
+}
+```
+
+#### Result
+
+{{EmbedGHLiveSample("responsive-iframe-sizing/basic/", "100%", 300)}}
+
+Even though no explicit `height` has been set on the `<iframe>`, it is sized to the right height to exactly contain its embedded document, with no scroll bars.
+
+You can also [load the demo in a separate tab](https://mdn.github.io/dom-examples/responsive-iframe-sizing/basic/) and view the [source code](https://github.com/mdn/dom-examples/tree/main/responsive-iframe-sizing/basic).
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [CSS box sizing](/en-US/docs/Web/CSS/Guides/Box_sizing) module
+- [`<meta name="responsive-embedded-sizing">`](/en-US/docs/Web/HTML/Reference/Elements/meta/name/responsive-embedded-sizing)
+- {{domxref("Window.requestResize()")}}

files/en-us/web/html/reference/elements/meta/name/index.md

@@ -58,10 +58,12 @@ The HTML specification defines the following set of standard metadata names:
 
 ### Meta names defined in other specifications
 
-- [`viewport`](/en-US/docs/Web/HTML/Reference/Elements/meta/name/viewport)
-  - : Gives hints about the initial size of the {{glossary("viewport")}}. Defined in the [CSS viewport module](/en-US/docs/Web/CSS/Guides/Viewport).
+- [`responsive-embedded-sizing`](/en-US/docs/Web/HTML/Reference/Elements/meta/name/responsive-embedded-sizing) {{experimental_inline}}
+  - : Opts in an embedded document to sharing its size information with the parent page. Defined in the [CSS box sizing module](/en-US/docs/Web/CSS/Guides/Box_sizing).
 - [`text-scale`](/en-US/docs/Web/HTML/Reference/Elements/meta/name/text-scale) {{experimental_inline}}
   - : Enables opting the page in to having the {{htmlelement("html")}} root element's {{cssxref("font-size")}} scale in proportion to OS and browser-level text scale settings. Defined in the [CSS fonts module](/en-US/docs/Web/CSS/Guides/Fonts).
+- [`viewport`](/en-US/docs/Web/HTML/Reference/Elements/meta/name/viewport)
+  - : Gives hints about the initial size of the {{glossary("viewport")}}. Defined in the [CSS viewport module](/en-US/docs/Web/CSS/Guides/Viewport).
 
 ### Meta names defined in the WHATWG MetaExtensions wiki
 

files/en-us/web/html/reference/elements/meta/name/responsive-embedded-sizing/index.md

@@ -0,0 +1,42 @@
+---
+title: <meta name="responsive-embedded-sizing">
+short-title: responsive-embedded-sizing
+slug: Web/HTML/Reference/Elements/meta/name/responsive-embedded-sizing
+page-type: html-attribute-value
+status:
+  - experimental
+browser-compat: html.elements.meta.name.responsive-embedded-sizing
+sidebar: htmlsidebar
+---
+
+{{SeeCompatTable}}
+
+The **`responsive-embedded-sizing`** value for the [`name`](/en-US/docs/Web/HTML/Reference/Elements/meta/name) attribute of a {{htmlelement("meta")}} element opts in an embedded document to sharing its size information with the parent document. The embedding {{htmlelement("iframe")}} can then be sized relative to the embedded document's layout size using the {{cssxref("frame-sizing")}} CSS property.
+
+## Description
+
+For security and privacy reasons, {{htmlelement("iframe")}} elements do not by default expose any information to the parent document about the size of the content in the document they are embedding.
+
+To enable responsive sizing of {{htmlelement("iframe")}} elements based on their content, the `<meta name="responsive-embedded-sizing">` tag can be included in an embedded document to opt it in to sharing its size information with the parent document.
+
+The {{cssxref("frame-sizing")}} CSS property can then be set on the `<iframe>` to cause it to adopt the same horizontal or vertical size as the embedded document's actual content size (termed the **internal layout intrinsic size** in the spec, but abbreviated to "layout size" in our documentation). This is useful for avoiding scrollbars on `<iframe>` content so that it fits more seamlessly with its embedder.
+
+To resize the `<iframe>` dynamically as the embedded document changes layout size, you can call the {{domxref("Window.requestResize()")}} method from the embedded document to make it report an updated size.
+
+## Examples
+
+See the {{cssxref("frame-sizing")}} and {{domxref("Window.requestResize()")}} pages for complete examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("Window.requestResize()")}}
+- {{cssxref("frame-sizing")}} CSS property
+- [CSS box sizing](/en-US/docs/Web/CSS/Guides/Box_sizing) module