local-iframe 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +59 -10
- package/index.js +4 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,20 +2,34 @@
|
|
|
2
2
|
|
|
3
3
|
> A web component that renders templates in a local `<iframe>`.
|
|
4
4
|
|
|
5
|
+
## Table of Contents
|
|
6
|
+
|
|
7
|
+
- [Getting Started](#getting-started)
|
|
8
|
+
- [Use Cases](#use-cases)
|
|
9
|
+
- [Example Usage](#example-usage)
|
|
10
|
+
- [1. Child Template](#1-child-template)
|
|
11
|
+
- [2. Template Attribute](#2-template-attribute)
|
|
12
|
+
- [Recommended Styling](#recommended-styling)
|
|
13
|
+
- [Local Development](#local-development)
|
|
14
|
+
|
|
5
15
|
## Getting Started
|
|
6
16
|
|
|
7
|
-
|
|
17
|
+
You may either install and import the package:
|
|
8
18
|
|
|
9
19
|
```sh
|
|
10
20
|
npm install local-iframe
|
|
11
21
|
```
|
|
12
22
|
|
|
23
|
+
```js
|
|
24
|
+
import "local-iframe";
|
|
25
|
+
```
|
|
26
|
+
|
|
13
27
|
Or include it via CDN:
|
|
14
28
|
|
|
15
29
|
```html
|
|
16
30
|
<script
|
|
17
31
|
type="module"
|
|
18
|
-
src="https://cdn.jsdelivr.net/npm/local-iframe@
|
|
32
|
+
src="https://cdn.jsdelivr.net/npm/local-iframe@1.0.1/index.js"
|
|
19
33
|
></script>
|
|
20
34
|
```
|
|
21
35
|
|
|
@@ -30,19 +44,19 @@ I wanted to be able to declaratively render fully local, isolated code demos in
|
|
|
30
44
|
|
|
31
45
|
There are two ways to define the markup for your iframe:
|
|
32
46
|
|
|
33
|
-
|
|
34
|
-
|
|
47
|
+
1. Render a `<template>` as a child of `<local-iframe>`
|
|
48
|
+
2. Define the `<template>` externally and set `template="id-of-your-template"`
|
|
35
49
|
|
|
36
50
|
In both cases, the component will duplicate the content of the template and render it in a local iframe.
|
|
37
51
|
|
|
38
52
|
Any styles and scripts will only affect elements within the iframe itself.
|
|
39
53
|
|
|
40
|
-
### Child Template
|
|
54
|
+
### 1. Child Template
|
|
41
55
|
|
|
42
56
|
The simplest way to use `local-iframe` is to render a `<template>` as a child:
|
|
43
57
|
|
|
44
58
|
```html
|
|
45
|
-
<local-iframe
|
|
59
|
+
<local-iframe>
|
|
46
60
|
<template>
|
|
47
61
|
<div><h1>Hello, world!</h1></div>
|
|
48
62
|
<p>This is awesome!</p>
|
|
@@ -68,10 +82,7 @@ In this example, we render a template with:
|
|
|
68
82
|
- Two scripts to execute within the iframe's context
|
|
69
83
|
- Styles to apply within to elements within the iframe
|
|
70
84
|
|
|
71
|
-
|
|
72
|
-
> To prevent layout shifts when the page loads, set inline styles on the host element and assign it a width and height. The inner `iframe` will fill that space responsively, shrinking or growing as needed.
|
|
73
|
-
|
|
74
|
-
### Template Attribute
|
|
85
|
+
### 2. Template Attribute
|
|
75
86
|
|
|
76
87
|
Alternatively, you can define an external `<template>` and reference it via the `template` attribute, like so:
|
|
77
88
|
|
|
@@ -88,3 +99,41 @@ Alternatively, you can define an external `<template>` and reference it via the
|
|
|
88
99
|
```
|
|
89
100
|
|
|
90
101
|
If the `template` attribute changes, the frame will update its markup with the content of the new template.
|
|
102
|
+
|
|
103
|
+
## Recommended Styling
|
|
104
|
+
|
|
105
|
+
Frames will be initially empty until their content is hydrated. This can cause unwanted vertical layout shifts as the page loads. To fix this, you can reserve an explicit `height` on each frame with inline styles:
|
|
106
|
+
|
|
107
|
+
```html
|
|
108
|
+
<local-iframe style="height: 400px;"></local-iframe>
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
You will need to treat `local-iframe`s as block elements for this to work, preferably with [inline critical styles](https://web.dev/articles/extract-critical-css) in the head of your document:
|
|
112
|
+
|
|
113
|
+
```css
|
|
114
|
+
local-iframe {
|
|
115
|
+
display: block;
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
You may also set an explicit width, although doing so is optional:
|
|
120
|
+
|
|
121
|
+
```html
|
|
122
|
+
<local-iframe style="width: 800px; height: 400px;"></local-iframe>
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
If you do choose to set an explicit width, make sure you also set a `max-width` to prevent horizontal overflow on narrower devices:
|
|
126
|
+
|
|
127
|
+
```diff
|
|
128
|
+
local-iframe {
|
|
129
|
+
display: block;
|
|
130
|
+
+ max-width: 100%;
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Local Development
|
|
135
|
+
|
|
136
|
+
1. Clone this repo.
|
|
137
|
+
2. Run `pnpm install` to install dev dependencies (Vite).
|
|
138
|
+
3. Run `pnpm run dev` to start the local dev server.
|
|
139
|
+
4. Open http://localhost:5173 in your browser.
|
package/index.js
CHANGED
|
@@ -2,6 +2,7 @@ class LocalIframe extends HTMLElement {
|
|
|
2
2
|
static observedAttributes = ['template'];
|
|
3
3
|
|
|
4
4
|
#iframe;
|
|
5
|
+
#hasMounted = false;
|
|
5
6
|
|
|
6
7
|
constructor() {
|
|
7
8
|
super();
|
|
@@ -19,6 +20,9 @@ class LocalIframe extends HTMLElement {
|
|
|
19
20
|
}
|
|
20
21
|
|
|
21
22
|
connectedCallback() {
|
|
23
|
+
if (this.#hasMounted) return;
|
|
24
|
+
this.#hasMounted = true;
|
|
25
|
+
|
|
22
26
|
const templateId = this.getAttribute('template');
|
|
23
27
|
const template = templateId ? document.getElementById(templateId) : this.querySelector('template');
|
|
24
28
|
|