feat(code): iframe component

projects/code/DEVELOPMENT.md

@@ -8,6 +8,7 @@
 | `pnpm run test`            | Run unit tests                            |
 | `pnpm run test:watch`      | Run unit tests in watch mode              |
 | `pnpm run test:axe`        | Run accessibility tests                   |
+| `pnpm run test:ssr`        | Run server-side rendering tests           |
 | `pnpm run test:coverage`   | Run unit tests with coverage              |
 | `pnpm run test:lighthouse` | Run Lighthouse performance tests          |
 | `pnpm run ci`              | Run the full CI pipeline                  |

projects/code/package.json

@@ -4,7 +4,7 @@
   "release": {
     "extends": "../../release.config.js"
   },
-  "description": "Code authoring related components. Providing syntax-highlighted code blocks with support for multiple programming languages.",
+  "description": "NVIDIA Elements code authoring related components such as syntax-highlighted code blocks and an iframe isolation components.",
   "keywords": [
     "nvidia",
     "web-components",
@@ -169,6 +169,18 @@
     "./codeblock/languages/yaml.js": {
       "types": "./dist/codeblock/languages/yaml.d.ts",
       "default": "./dist/codeblock/languages/yaml.js"
+    },
+    "./iframe": {
+      "types": "./dist/iframe/index.d.ts",
+      "default": "./dist/iframe/index.js"
+    },
+    "./iframe/index.js": {
+      "types": "./dist/iframe/index.d.ts",
+      "default": "./dist/iframe/index.js"
+    },
+    "./iframe/define.js": {
+      "types": "./dist/iframe/define.d.ts",
+      "default": "./dist/iframe/define.js"
     }
   },
   "sideEffects": [
@@ -184,6 +196,7 @@
     "lint": "wireit",
     "test": "wireit",
     "test:axe": "wireit",
+    "test:ssr": "wireit",
     "test:coverage": "wireit",
     "test:watch": "wireit",
     "test:lighthouse": "wireit"
@@ -233,6 +246,7 @@
         "lint",
         "publint",
         "test:axe",
+        "test:ssr",
         "test:coverage"
       ]
     },
@@ -368,6 +382,28 @@
         "NODE_ENV": "production"
       }
     },
+    "test:ssr": {
+      "command": "vitest run --config=vitest.ssr.ts",
+      "files": [
+        "dist/**/*.js",
+        "src/**/*.test.ssr.ts",
+        "tsconfig.json",
+        "vitest.ssr.ts"
+      ],
+      "output": [
+        "coverage/ssr/**"
+      ],
+      "dependencies": [
+        "../internals/vite:ci",
+        {
+          "script": "build",
+          "cascade": false
+        }
+      ],
+      "env": {
+        "NODE_ENV": "production"
+      }
+    },
     "lint": {
       "dependencies": [
         "lint:eslint",

projects/code/src/bundle.ts

@@ -17,5 +17,7 @@ import '@nvidia-elements/code/codeblock/languages/typescript.js';
 import '@nvidia-elements/code/codeblock/languages/xml.js';
 import '@nvidia-elements/code/codeblock/languages/yaml.js';
 import '@nvidia-elements/code/codeblock/define.js';
+import '@nvidia-elements/code/iframe/define.js';
 
 export * from '@nvidia-elements/code/codeblock';
+export * from '@nvidia-elements/code/iframe';

projects/code/src/iframe/define.ts

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { define } from '@nvidia-elements/core/internal';
+import { Iframe } from './iframe.js';
+
+define(Iframe);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'nve-iframe': Iframe;
+  }
+}

projects/code/src/iframe/iframe.css

@@ -0,0 +1,18 @@
+/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. */
+/* SPDX-License-Identifier: Apache-2.0 */
+
+:host {
+  --width: var(--_width, fit-content);
+  --height: var(--_height, fit-content);
+  --border: none;
+  display: block;
+  width: fit-content;
+  height: fit-content;
+  border: var(--border);
+}
+
+iframe {
+  width: var(--width);
+  height: var(--height);
+  border: 0;
+}

projects/code/src/iframe/iframe.examples.ts

@@ -0,0 +1,112 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { html } from 'lit';
+import '@nvidia-elements/code/iframe/define.js';
+
+export default {
+  title: 'Code/Iframe',
+  component: 'nve-iframe'
+};
+
+/**
+ * @summary Supplies the iframe with Elements themes, utilities, fonts, and component registrations through its head template. Use this structure because iframe documents do not inherit resources from the parent document.
+ */
+export const Default = {
+  render: () => html`
+<nve-iframe aria-label="Elements iframe example">
+  <template slot="head">
+    <title>Elements iframe example</title>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nvidia-elements/themes/dist/bundles/index.css" />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nvidia-elements/themes/dist/fonts/inter.css" />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nvidia-elements/styles/dist/bundles/index.css" />
+    <script type="module" src="https://cdn.jsdelivr.net/npm/@nvidia-elements/core/dist/bundles/index.min.js"></script>
+  </template>
+  <template>
+    <nve-alert status="success">isolated iframe content</nve-alert>
+  </template>
+</nve-iframe>
+  `
+};
+
+/**
+ * @summary Synchronizes the iframe height with expandable content so the host layout avoids empty space or internal scrollbars. Use for previews whose intrinsic height changes after interaction.
+ * @tags test-case
+ */
+export const DynamicHeight = {
+  render: () => html`
+<nve-iframe aria-label="Dynamic height iframe example" style="--border: 1px solid red">
+  <template slot="head">
+    <title>Dynamic iframe height</title>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nvidia-elements/themes/dist/bundles/index.css" />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nvidia-elements/themes/dist/fonts/inter.css" />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nvidia-elements/styles/dist/bundles/index.css" />
+    <script type="module" src="https://cdn.jsdelivr.net/npm/@nvidia-elements/core/dist/bundles/index.min.js"></script>
+  </template>
+  <template>
+    <nve-accordion behavior-expand>
+      <nve-accordion-header>
+        <h2 nve-text="heading xs medium" slot="prefix">Dynamic height in iframe</h2>
+      </nve-accordion-header>
+      <nve-accordion-content>
+        The iframe expands when this content opens and contracts when it closes.
+      </nve-accordion-content>
+    </nve-accordion>
+  </template>
+</nve-iframe>
+  `
+};
+
+/**
+ * @summary Overrides intrinsic iframe dimensions with `--width` and `--height` to create a stable preview viewport. Use when you need to inspect embedded content at a fixed size regardless of its rendered bounds.
+ * @tags test-case
+ */
+export const FixedSize = {
+  render: () => html`
+<nve-iframe aria-label="Fixed-size iframe example" style="--height: 256px; --width: 256px; --border: 1px solid red">
+  <template><p style="height: 128px; width: 128px; margin: 1px; outline: 1px solid yellow;">override iframe size</p></template>
+</nve-iframe>
+  `
+};
+
+/**
+ * @summary The iframe browsing-context boundary clips popovers at its viewport and prevents them from escaping. Keep overlays inside the frame, or render them outside the iframe when they must overlap surrounding content.
+ * @tags test-case
+ */
+export const OverflowClip = {
+  render: () => html`
+<nve-iframe aria-label="Overflow clipping iframe example" style="--height: 150px; --border: 1px solid red">
+  <template slot="head">
+    <title>Clipped iframe popover</title>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nvidia-elements/themes/dist/bundles/index.css" />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nvidia-elements/themes/dist/fonts/inter.css" />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nvidia-elements/styles/dist/bundles/index.css" />
+    <script type="module" src="https://cdn.jsdelivr.net/npm/@nvidia-elements/core/dist/bundles/index.min.js"></script>
+  </template>
+  <template>
+    <div nve-layout="pad:md">
+      <nve-dropdown id="dropdown">Popovers <strong>are clipped</strong> by the iframe.</nve-dropdown>
+      <nve-button popovertarget="dropdown">Open popover</nve-button>
+    </div>
+  </template>
+</nve-iframe>
+  `
+};
+
+/**
+ * @summary Regenerates the iframe document when its source template changes. Use for live previews or generated output that must stay synchronized with edits made in the parent document.
+ * @tags test-case
+ */
+export const DynamicallyUpdatedContent = {
+  render: () => html`
+<nve-iframe id="property-example" aria-label="Dynamically updated iframe example">
+  <template>
+    <p nve-text="body">Initial iframe content.</p>
+  </template>
+</nve-iframe>
+<script type="module">
+  document.querySelector('#property-example template').innerHTML =
+    '<p nve-text="body">This template was dynamically updated.</p>';
+</script>
+  `
+};

projects/code/src/iframe/iframe.test.axe.ts

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { html } from 'lit';
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { createFixture, elementIsStable, removeFixture } from '@internals/testing';
+import { runAxe } from '@internals/testing/axe';
+import { Iframe } from '@nvidia-elements/code/iframe';
+import '@nvidia-elements/code/iframe/define.js';
+
+describe(Iframe.metadata.tag, () => {
+  let fixture: HTMLElement;
+  let element: Iframe;
+
+  beforeEach(async () => {
+    fixture = await createFixture(html`<nve-iframe aria-label="iframe test"></nve-iframe>`);
+    element = fixture.querySelector<Iframe>(Iframe.metadata.tag)!;
+    await elementIsStable(element);
+  });
+
+  afterEach(() => {
+    removeFixture(fixture);
+  });
+
+  it('should pass axe check', async () => {
+    const results = await runAxe([Iframe.metadata.tag]);
+    expect(results.violations.length).toBe(0);
+  });
+});

projects/code/src/iframe/iframe.test.lighthouse.ts

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { expect, test, describe } from 'vitest';
+import { lighthouseRunner } from '@internals/vite';
+
+describe('iframe lighthouse report', () => {
+  test('iframe should meet lighthouse benchmarks', async () => {
+    const report = await lighthouseRunner.getReport('nve-iframe', /* html */`
+      <nve-iframe aria-label="iframe test"></nve-iframe>
+      <script type="module">
+        import '@nvidia-elements/code/iframe/define.js';
+      </script>
+    `);
+
+    expect(report.scores.performance).toBe(100);
+    expect(report.scores.accessibility).toBe(100);
+    expect(report.scores.bestPractices).toBe(100);
+    expect(report.payload.javascript.kb).toBeLessThan(10);
+  });
+});

projects/code/src/iframe/iframe.test.ssr.ts

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { html } from 'lit';
+import { describe, expect, it } from 'vitest';
+import { ssrRunner } from '@internals/vite';
+import { Iframe } from '@nvidia-elements/code/iframe';
+import '@nvidia-elements/code/iframe/define.js';
+
+describe(Iframe.metadata.tag, () => {
+  it('should pass baseline ssr check', async () => {
+    const result = await ssrRunner.render(html`
+      <nve-iframe>
+        <template slot="head"><title>Iframe SSR test</title></template>
+        <template><p nve-text="body">Iframe SSR content</p></template>
+      </nve-iframe>
+    `);
+
+    expect(result.includes('shadowroot="open"')).toBe(true);
+    expect(result.includes('nve-iframe')).toBe(true);
+    expect(result.includes('sandbox="allow-scripts"')).toBe(true);
+    expect(result.includes('allow-same-origin')).toBe(false);
+  });
+});