├── .prettierrc.json
├── src
    ├── index.ts
    ├── docs.index.ts
    ├── portal.ts
    └── portal.test.ts
├── docs
    ├── assets
    │   ├── hierarchy.js
    │   ├── navigation.js
    │   ├── search.js
    │   ├── highlight.css
    │   ├── icons.svg
    │   └── icons.js
    ├── .nojekyll
    ├── types
    │   └── TargetOrSelector.html
    ├── functions
    │   └── portal.html
    ├── modules.html
    ├── interfaces
    │   └── PortalOptions.html
    ├── classes
    │   └── PortalDirective.html
    └── index.html
├── typedoc.json
├── .gitignore
├── .prettierignore
├── web-test-runner.config.mjs
├── dev
    ├── tsconfig.json
    ├── index.html
    ├── confirmation-dialog.ts
    ├── index.ts
    ├── demo-modify-container.ts
    ├── example-component.ts
    ├── demo-intro.ts
    ├── demo-delegation.ts
    ├── demo-intro-example.ts
    ├── demo-async.ts
    ├── demo-reactive.ts
    └── demo-modals.ts
├── docs.tsconfig.json
├── web-dev-server.config.mjs
├── tsconfig.json
├── LICENSE.txt
├── esbuild.config.js
├── package.json
├── CHANGELOG.md
└── README.md


/.prettierrc.json:
--------------------------------------------------------------------------------
1 | {
2 |   "printWidth": 100,
3 |   "singleQuote": true
4 | }
5 | 


--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
1 | import { portal } from './portal';
2 | 
3 | export { portal };
4 | 


--------------------------------------------------------------------------------
/docs/assets/hierarchy.js:
--------------------------------------------------------------------------------
1 | window.hierarchyData = "eJyrVirKzy8pVrKKjtVRKkpNy0lNLsnMzytWsqqurQUAmx4Kpg=="


--------------------------------------------------------------------------------
/src/docs.index.ts:
--------------------------------------------------------------------------------
1 | export { portal, TargetOrSelector, PortalOptions, PortalDirective } from './portal';
2 | 


--------------------------------------------------------------------------------
/docs/.nojekyll:
--------------------------------------------------------------------------------
1 | TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.


--------------------------------------------------------------------------------
/typedoc.json:
--------------------------------------------------------------------------------
1 | {
2 |   "entryPoints": ["src/docs.index.ts"],
3 |   "name": "Lit Modal Portal Documentation",
4 |   "out": "docs",
5 |   "tsconfig": "docs.tsconfig.json"
6 | }
7 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | node_modules
 2 | *.swp
 3 | *.tsbuildinfo
 4 | 
 5 | # build output
 6 | /lib/
 7 | /index.*
 8 | /modal-portal.*
 9 | /modal-controller.*
10 | /portal.*
11 | /lit-modal-portal-*
12 | /coverage
13 | 


--------------------------------------------------------------------------------
/.prettierignore:
--------------------------------------------------------------------------------
 1 | node_modules
 2 | *.swp
 3 | *.tsbuildinfo
 4 | /CHANGELOG.md
 5 | 
 6 | docs
 7 | 
 8 | # build output
 9 | /lib/
10 | /index.*
11 | /modal-portal.*
12 | /modal-controller.*
13 | /portal.*
14 | /lit-modal-portal-*
15 | 


--------------------------------------------------------------------------------
/docs/assets/navigation.js:
--------------------------------------------------------------------------------
1 | window.navigationData = "eJxdzsEKwjAQBNB/2XMwttiqOXuvoDfxEOLWBtMkJKso0n8Xqpg255l9s6c3ED4JBOxdIGl2OqAi/UBg4CV1IEAZGSNGnhUWHfUGGNy0vYAoys3AMqvxpJ2NSdKWMLRS/bFfY06VVT2hjjJckZpwQIOKXEgavTxGnueZtdyui6qceH4cTkp7t2p8gn+T+X29Gs4fwOFkLQ=="


--------------------------------------------------------------------------------
/web-test-runner.config.mjs:
--------------------------------------------------------------------------------
1 | import { esbuildPlugin } from '@web/dev-server-esbuild';
2 | 
3 | export default {
4 |   nodeResolve: true,
5 |   files: ['src/**/*.test.ts'],
6 |   plugins: [esbuildPlugin({ ts: true, target: 'auto', tsconfig: './tsconfig.json' })],
7 | };
8 | 


--------------------------------------------------------------------------------
/dev/tsconfig.json:
--------------------------------------------------------------------------------
 1 | // For use by typescript-language-server
 2 | {
 3 |   "compilerOptions": {
 4 |     "experimentalDecorators": true,
 5 |     "target": "es2019",
 6 |     "moduleResolution": "node",
 7 |     "plugins": [
 8 |       {
 9 |         "name": "ts-lit-plugin"
10 |       }
11 |     ]
12 |   }
13 | }
14 | 


--------------------------------------------------------------------------------
/dev/index.html:
--------------------------------------------------------------------------------
 1 | <!doctype html>
 2 | <html>
 3 |   <head>
 4 |     <meta charset="utf-8" />
 5 |     <meta name="viewport" content="width=device-width, initial-scale=1" />
 6 |     <title>Lit Modal Portal</title>
 7 |     <script type="module" src="/dev/index.ts"></script>
 8 |   </head>
 9 | 
10 |   <body>
11 |     <app-root></app-root>
12 |   </body>
13 | </html>
14 | 


--------------------------------------------------------------------------------
/docs.tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "include": ["src/**/*.ts"],
 3 |   "exclude": ["src/**/*.test.ts"],
 4 |   "compilerOptions": {
 5 |     "moduleResolution": "node",
 6 |     "experimentalDecorators": true,
 7 |     "target": "es2019",
 8 |     "preserveWatchOutput": true,
 9 |     "skipLibCheck": true
10 |   },
11 |   "watchOptions": {
12 |     "excludeDirectories": ["**/node_modules"]
13 |   }
14 | }
15 | 


--------------------------------------------------------------------------------
/web-dev-server.config.mjs:
--------------------------------------------------------------------------------
 1 | import { env } from 'node:process';
 2 | import { esbuildPlugin } from '@web/dev-server-esbuild';
 3 | 
 4 | export default {
 5 |   nodeResolve: true,
 6 |   port: Number(env['PORT']) || 8000,
 7 |   plugins: [esbuildPlugin({ ts: true, target: 'auto', tsconfig: './tsconfig.json' })],
 8 |   middleware: [
 9 |     // Based on https://modern-web.dev/docs/dev-server/middleware/#rewriting-request-urls
10 |     function rewriteIndex(context, next) {
11 |       if (context.url === '/' || context.url === '/index.html') {
12 |         context.url = '/dev/index.html';
13 |       }
14 | 
15 |       return next();
16 |     },
17 |   ],
18 | };
19 | 


--------------------------------------------------------------------------------
/docs/assets/search.js:
--------------------------------------------------------------------------------
1 | window.searchData = "eJydlk2PmzAQQP/L7NWb8A3h2l562kqterFQhWDStUpsZDtpV4j/XgEBx8BmSW/IM+/NYI0NDUjxR0FKG/jNeAlpFBDg+QkhhVpInVdA4CwrSOF45oVmgqv9ENi96lMXLapcKVSQArRk1HjOIXZDb3J9z+Uv1C/yG1ZYaCEnq36rUe3n4fvuMJq8X/tWXuq+sUnKuEZ5zAtUeyvhrtZ1vJt3r/ICX0VVotxmfbKJmwoE6lwi14tu3yl9EiU7vn0SXOeMby4/UMUN9WALXjLb1M9MYqHZBacOrsb9LP7BIARGLJHfbug939OUe+89TI/vVCyZKgTnWGgst9WdEaa6VuUzU8+1FHoMPtqNxAebsYH/7CUjwHiJfyFt4IJSMcEhBW/n7w5A4MiwKrsbYGiSQCFOp85EoBTFuX/Mrmk/+sPZJQ/ZewcIdYib7A6xm2WEjnAf6BdGh1npQRcIdddAdwG6FugBod4a6C1AzwJ9INRfA/0F6FtgAIQGa2CwAAMLDIHQcA0MF2BogREQGq2B0QKMLDAGQuM1MF6AsQUmQGiyBiYLcFjpZ+qCUmP5ZZgtSmeHrYGf17GLxwPQQAxp07ZmyNKmvZmzLtYVW1xmxhUYV7DJZd3LxuMbj7/Nc/0aGoVjFM4DitLcq8YVGlf4gEuMHz5j8ozJ22Sy7hjjSYwn2ejhsz2OjCLapND9b4CQavpLMDLXyNyPZRmBmtVYMY6Q0qxt/wHhM/RV";


--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "include": ["src/**/*.ts"],
 3 |   "exclude": ["src/docs.index.ts", "src/lib/docs.index.ts"],
 4 |   "compilerOptions": {
 5 |     "module": "esnext",
 6 |     "moduleResolution": "node",
 7 |     "declaration": true,
 8 |     "declarationMap": true,
 9 |     "emitDeclarationOnly": true,
10 |     "removeComments": true,
11 |     "outDir": "./",
12 |     "esModuleInterop": true,
13 |     "experimentalDecorators": true,
14 |     "lib": ["esnext", "DOM", "DOM.Iterable"],
15 |     "target": "es2019",
16 |     "plugins": [{ "name": "ts-lit-plugin" }],
17 |     "preserveWatchOutput": true,
18 |     "useDefineForClassFields": false,
19 |     "types": ["mocha"]
20 |   },
21 |   "watchOptions": {
22 |     "excludeDirectories": ["**/node_modules"]
23 |   }
24 | }
25 | 


--------------------------------------------------------------------------------
/dev/confirmation-dialog.ts:
--------------------------------------------------------------------------------
 1 | import { LitElement, html } from 'lit';
 2 | import { customElement, property } from 'lit/decorators.js';
 3 | import { Ref, ref, createRef } from 'lit/directives/ref.js';
 4 | 
 5 | @customElement('confirmation-dialog')
 6 | export default class ConfirmationDialog extends LitElement {
 7 |   @property({ attribute: false })
 8 |   dialogRef: Ref<HTMLDialogElement> = createRef();
 9 | 
10 |   render() {
11 |     return html`
12 |       <dialog
13 |         ${ref(this.dialogRef)}
14 |         @close=${(e: CloseEvent) => {
15 |           this.dispatchEvent(new CloseEvent('close', { ...e }));
16 |         }}
17 |       >
18 |         <p>This is the confirmation dialog</p>
19 |         <button @click=${() => this.dialogRef.value?.close('cancelled')}>Cancel</button>
20 |         <button @click=${() => this.dialogRef.value?.close('confirmed')}>Confirm Action</button>
21 |       </dialog>
22 |     `;
23 |   }
24 | }
25 | 
26 | declare global {
27 |   interface HTMLElementTagNameMap {
28 |     'confirmation-dialog': ConfirmationDialog;
29 |   }
30 | }
31 | 


--------------------------------------------------------------------------------
/LICENSE.txt:
--------------------------------------------------------------------------------
 1 | Copyright 2024 Nicholas Wilcox <nwilcox@linicks.dev>.
 2 | 
 3 | Permission is hereby granted, free of charge, to any person obtaining a copy of 
 4 | this software and associated documentation files (the "Software"), to deal in 
 5 | the Software without restriction, including without limitation the rights to 
 6 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 
 7 | of the Software, and to permit persons to whom the Software is furnished to do 
 8 | so, subject to the following conditions:
 9 | 
10 | The above copyright notice and this permission notice shall be included in all 
11 | copies or substantial portions of the Software.
12 | 
13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
19 | SOFTWARE.
20 | 


--------------------------------------------------------------------------------
/esbuild.config.js:
--------------------------------------------------------------------------------
 1 | import esbuild from 'esbuild';
 2 | import parser from 'yargs-parser';
 3 | 
 4 | function isBooleanAndTrue(value) {
 5 |   return typeof value === 'boolean' && Boolean(value);
 6 | }
 7 | 
 8 | const localeTimeStringOptions = {
 9 |   hour: '2-digit',
10 |   minute: '2-digit',
11 |   second: '2-digit',
12 | };
13 | 
14 | function getNowAsString() {
15 |   return new Date().toLocaleTimeString([], localeTimeStringOptions);
16 | }
17 | 
18 | const argv = parser(process.argv.slice(2));
19 | const shouldWatch = isBooleanAndTrue(argv.w) || isBooleanAndTrue(argv.watch);
20 | 
21 | const plugins = [
22 |   {
23 |     name: 'on-rebuild-plugin',
24 |     setup(build) {
25 |       if (shouldWatch) {
26 |         build.onEnd((result) => {
27 |           const timeString = getNowAsString();
28 |           if (result.errors.length) console.log(`${timeString}: watch build failed`);
29 |           else console.log(`${timeString}: watch build succeeded`);
30 |         });
31 |       }
32 |     },
33 |   },
34 | ];
35 | 
36 | const context = await esbuild.context({
37 |   entryPoints: ['src/index.ts', 'src/portal.ts'],
38 |   outdir: './',
39 |   bundle: false,
40 |   format: 'esm',
41 |   sourcemap: true,
42 |   plugins,
43 | });
44 | 
45 | if (shouldWatch) {
46 |   await context.watch();
47 |   console.log('watching...');
48 |   process.on('SIGINT', () => context.dispose());
49 | } else {
50 |   await context.rebuild();
51 |   await context.dispose();
52 | }
53 | 


--------------------------------------------------------------------------------
/dev/index.ts:
--------------------------------------------------------------------------------
 1 | import { LitElement, html, css } from 'lit';
 2 | import { customElement, state } from 'lit/decorators.js';
 3 | import { createRef, Ref } from 'lit/directives/ref.js';
 4 | 
 5 | import './demo-intro';
 6 | import './demo-reactive';
 7 | import './demo-modals';
 8 | import './demo-async';
 9 | import './demo-modify-container';
10 | import './demo-delegation';
11 | 
12 | @customElement('app-root')
13 | export class AppRoot extends LitElement {
14 |   static styles = [
15 |     css`
16 |       :host {
17 |         font-size: 1.125rem;
18 |         font-family: sans-serif;
19 |         line-height: 1.5;
20 |       }
21 | 
22 |       #wrapper {
23 |         max-width: 80ch;
24 |       }
25 |     `,
26 |   ];
27 | 
28 |   @state()
29 |   showModal4: boolean = false;
30 | 
31 |   dialogRef: Ref<HTMLDialogElement> = createRef();
32 | 
33 |   @state()
34 |   currentTime: Date = new Date();
35 | 
36 |   get timeString(): string {
37 |     return this.currentTime.toLocaleTimeString([], { timeStyle: 'medium' });
38 |   }
39 | 
40 |   connectedCallback(): void {
41 |     super.connectedCallback();
42 |   }
43 | 
44 |   disconnectedCallback(): void {
45 |     super.disconnectedCallback();
46 |   }
47 | 
48 |   render() {
49 |     return html`
50 |       <div id="wrapper">
51 |         <h1>lit-modal-portal Demo</h1>
52 |         <hr></hr>
53 |         <demo-intro></demo-intro>
54 |         <demo-reactive></demo-reactive>
55 |         <demo-modals></demo-modals>
56 |         <demo-async></demo-async>
57 |         <demo-modify-container></demo-modify-container>
58 |         <demo-delegation></demo-delegation>
59 |       </div>
60 |     `;
61 |   }
62 | }
63 | 


--------------------------------------------------------------------------------
/dev/demo-modify-container.ts:
--------------------------------------------------------------------------------
 1 | import { LitElement, html, css } from 'lit';
 2 | import { customElement, queryAsync } from 'lit/decorators.js';
 3 | import { portal } from '../src/portal';
 4 | 
 5 | @customElement('demo-modify-container')
 6 | export class DemoModifyContainer extends LitElement {
 7 |   static styles = [
 8 |     css`
 9 |       .portal-target {
10 |         border: 1px solid black;
11 |         padding: 0.25rem;
12 |       }
13 | 
14 |       h3 {
15 |         margin-top: 0;
16 |         margin-bottom: 0.25rem;
17 |         line-height: 1;
18 |       }
19 |     `,
20 |   ];
21 | 
22 |   @queryAsync('#portal-target')
23 |   portalTarget: Promise<HTMLElement>;
24 | 
25 |   render() {
26 |     return html`<h2>Modifying Portal Containers</h2>
27 |       <p>
28 |         Portals wrap their content in a container <code>&lt;div&gt;</code>. If you need to make
29 |         adjustments to a portal's container, you may provide a <code>modifyContainer</code> function
30 |         to the <code>portal</code> directive's options.
31 |       </p>
32 |       <p>
33 |         In the example below, the portal's container is styled directly using a
34 |         <code>modifyContainer</code> function.
35 |       </p>
36 |       <div id="portal-target" class="portal-target">
37 |         <h3>Portal target</h3>
38 |       </div>
39 |       ${portal(
40 |         html`<p>This is the portal content. Its container has a red border and some padding.</p>`,
41 |         this.portalTarget,
42 |         {
43 |           modifyContainer: (c) => {
44 |             c.style.border = '2px solid red';
45 |             c.style.padding = '0.5rem';
46 |           },
47 |         },
48 |       )}`;
49 |   }
50 | }
51 | 
52 | declare global {
53 |   interface HTMLElementTagNameMap {
54 |     'demo-modify-container': DemoModifyContainer;
55 |   }
56 | }
57 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "lit-modal-portal",
 3 |   "version": "0.8.0",
 4 |   "description": "A custom portal directive for the Lit framework to render content elsewhere in the DOM",
 5 |   "keywords": [
 6 |     "Lit",
 7 |     "modal",
 8 |     "portal",
 9 |     "custom element",
10 |     "directive"
11 |   ],
12 |   "homepage": "https://github.com/nicholas-wilcox/lit-modal-portal#readme",
13 |   "repository": {
14 |     "type": "git",
15 |     "url": "git+https://github.com/nicholas-wilcox/lit-modal-portal.git"
16 |   },
17 |   "bugs": {
18 |     "url": "https://github.com/nicholas-wilcox/lit-modal-portal/issues"
19 |   },
20 |   "license": "MIT",
21 |   "author": "Nicholas Wilcox",
22 |   "files": [
23 |     "/README.md",
24 |     "/CHANGELOG.md",
25 |     "/LICENSE.txt",
26 |     "/index.{js,js.map,d.ts,d.ts.map}",
27 |     "/portal.{js,js.map,d.ts,d.ts.map}"
28 |   ],
29 |   "main": "./index.js",
30 |   "type": "module",
31 |   "scripts": {
32 |     "build": "npm run clean && npm run tsc && npm run esbuild",
33 |     "build:watch": "concurrently \"npm:tsc:watch\" \"npm:esbuild:watch\"",
34 |     "clean": "rimraf --glob ./index.* ./portal.*",
35 |     "dev": "wds --watch",
36 |     "docs": "typedoc",
37 |     "docs:watch": "typedoc --watch",
38 |     "esbuild": "node esbuild.config.js",
39 |     "esbuild:watch": "node esbuild.config.js -w",
40 |     "lint": "prettier -w .",
41 |     "tsc": "tsc",
42 |     "tsc:watch": "tsc -w",
43 |     "test": "web-test-runner --puppeteer"
44 |   },
45 |   "devDependencies": {
46 |     "@open-wc/testing": "^4.0.0",
47 |     "@types/mocha": "^10.0.6",
48 |     "@web/dev-server": "^0.4.3",
49 |     "@web/dev-server-esbuild": "^1.0.2",
50 |     "@web/test-runner": "^0.20.0",
51 |     "@web/test-runner-puppeteer": "^0.18.0",
52 |     "concurrently": "^9.1.2",
53 |     "esbuild": "^0.25.0",
54 |     "prettier": "^3.2.5",
55 |     "rimraf": "^6.0.1",
56 |     "sinon": "^19.0.2",
57 |     "ts-lit-plugin": "^2.0.2",
58 |     "typedoc": "^0.27.7",
59 |     "typescript": "^5.7.3",
60 |     "yargs-parser": "^21.0.1"
61 |   },
62 |   "peerDependencies": {
63 |     "lit": ">=2"
64 |   },
65 |   "types": "./index.d.ts"
66 | }
67 | 


--------------------------------------------------------------------------------
/dev/example-component.ts:
--------------------------------------------------------------------------------
 1 | import { LitElement, css, html, PropertyValueMap } from 'lit';
 2 | import { customElement, state } from 'lit/decorators.js';
 3 | 
 4 | @customElement('example-component')
 5 | export class ExampleComponent extends LitElement {
 6 |   static styles = [
 7 |     css`
 8 |       #wrapper {
 9 |         border: 1px solid black;
10 |         padding: 0.25rem;
11 |       }
12 | 
13 |       h3 {
14 |         margin: 0;
15 |       }
16 |     `,
17 |   ];
18 | 
19 |   @state()
20 |   name: string = 'Your name here';
21 | 
22 |   constructor() {
23 |     super();
24 |     console.log('ExampleComponent::constructor()');
25 |   }
26 | 
27 |   connectedCallback() {
28 |     super.connectedCallback();
29 |     console.log('ExampleComponent::connectedCallback()');
30 |   }
31 | 
32 |   disconnectedCallback() {
33 |     super.disconnectedCallback();
34 |     console.log('ExampleComponent::disconnectedCallback()');
35 |   }
36 | 
37 |   firstUpdated(_changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>) {
38 |     console.log('ExampleComponent::firstUpdated()');
39 |   }
40 | 
41 |   updated(_changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>) {
42 |     console.log('ExampleComponent::updated()');
43 |   }
44 | 
45 |   willUpdate(_changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>) {
46 |     console.log('ExampleComponent::willUpdate()');
47 |   }
48 | 
49 |   render() {
50 |     return html`<div id="wrapper">
51 |       <h3>Example component</h3>
52 |       <p>
53 |         This component is a modified version of the <code>&lt;name-tag&gt;</code> component that is
54 |         developed in
55 |         <a target="_blank" href="https://lit.dev/tutorials/intro-to-lit/#4"
56 |           >Lit's interactive tutorial</a
57 |         >.
58 |       </p>
59 |       <p>Hello, ${this.name}</p>
60 |       <input @input=${this.changeName} placeholder="Enter your name" />
61 |     </div>`;
62 |   }
63 | 
64 |   changeName(event: Event) {
65 |     const input = event.target as HTMLInputElement;
66 |     this.name = input.value;
67 |   }
68 | }
69 | 
70 | declare global {
71 |   interface HTMLElementTagNameMap {
72 |     'example-component': ExampleComponent;
73 |   }
74 | }
75 | 


--------------------------------------------------------------------------------
/dev/demo-intro.ts:
--------------------------------------------------------------------------------
 1 | import { LitElement, html } from 'lit';
 2 | import { customElement } from 'lit/decorators.js';
 3 | 
 4 | import './demo-intro-example';
 5 | 
 6 | @customElement('demo-intro')
 7 | export class DemoIntro extends LitElement {
 8 |   render() {
 9 |     return html`
10 |       <h2>Introduction</h2>
11 |       <p>
12 |         The <code>lit-modal-portal</code> package provides a <code>portal</code> directive. This
13 |         directive works like
14 |         <a target="_blank" href="https://react.dev/reference/react-dom/createPortal"
15 |           >React's <code>createPortal</code> function</a
16 |         >, in the sense that you provide the content and the target DOM node you want the content
17 |         rendered in. When the <code>portal</code> directive renders, it will create a container
18 |         <code>&lt;div&gt;</code> as a child of the target. The content provided to the directive
19 |         will be rendered in this container using
20 |         <a target="_blank" href="https://lit.dev/docs/api/templates/#render"
21 |           >Lit's <code>render</code> function</a
22 |         >.
23 |       </p>
24 |       <p>
25 |         The <code>portal</code> directive is a custom, asynchronous directive (see
26 |         <a target="_blank" href="https://lit.dev/docs/templates/custom-directives/#async-directives"
27 |           >Lit documentation</a
28 |         >). This means it has a lifecycle and can automatically remove the content (and its
29 |         container) whenever the directive itself is removed.
30 |       </p>
31 |       <p>
32 |         In the component below, there are three buttons that toggle on (i.e. set to
33 |         <code>true</code>) some reactive boolean flags in the component's internal state. Each flag
34 |         is used to optionally render a portal, and the content of each portal contains a button to
35 |         turn the respective boolean flag back to <code>off</code>. Each portal targets the same
36 |         root, which is a <code>&lt;div&gt;</code> that is also in the component.
37 |       </p>
38 |       <demo-intro-example></demo-intro-example>
39 |       <p>
40 |         This results in a stack. A portal's content is added to (or removed from) the stack when the
41 |         respective <code>portal</code> directive is included (or excluded) from the template.
42 |       </p>
43 |     `;
44 |   }
45 | }
46 | 
47 | declare global {
48 |   interface HTMLElementTagNameMap {
49 |     'demo-intro': DemoIntro;
50 |   }
51 | }
52 | 


--------------------------------------------------------------------------------
/dev/demo-delegation.ts:
--------------------------------------------------------------------------------
 1 | import { html, LitElement, css } from 'lit';
 2 | import { customElement, property, state, queryAsync } from 'lit/decorators.js';
 3 | import { when } from 'lit/directives/when.js';
 4 | import { portal } from '../src/portal';
 5 | 
 6 | @customElement('dynamic-portal')
 7 | export class DynamicPortal extends LitElement {
 8 |   static styles = [
 9 |     css`
10 |       .dynamic-portal {
11 |         border: 1px solid black;
12 |         padding: 0.25rem;
13 |       }
14 |     `,
15 |   ];
16 | 
17 |   @property({ attribute: false })
18 |   portalContent: unknown;
19 | 
20 |   @property({ attribute: false })
21 |   portalTarget: Promise<HTMLElement>;
22 | 
23 |   @state()
24 |   enablePortal = false;
25 | 
26 |   render() {
27 |     return html`
28 |       <div class="dynamic-portal">
29 |         <p>
30 |           This component manages a reactive boolean value that is toggled by the button below. By
31 |           default, this component will render its provided content in-place. When the portal is
32 |           enabled, the content will be rendered in the provided target with a portal.
33 |         </p>
34 |         <button @click=${() => (this.enablePortal = !this.enablePortal)}>Toggle Portal</button>
35 |         ${when(
36 |           this.enablePortal,
37 |           () =>
38 |             portal(
39 |               html`
40 |                 ${this.portalContent}
41 |                 <p>Rendered in a portal.</p>
42 |               `,
43 |               this.portalTarget,
44 |             ),
45 |           () => html`
46 |             ${this.portalContent}
47 |             <p>Rendered in-place.</p>
48 |           `,
49 |         )}
50 |       </div>
51 |     `;
52 |   }
53 | }
54 | 
55 | @customElement('demo-delegation')
56 | export class DemoDelegation extends LitElement {
57 |   static styles = [
58 |     css`
59 |       .portal-target {
60 |         border: 1px solid black;
61 |         padding: 0.25rem;
62 |         margin-top: 0.5rem;
63 |       }
64 | 
65 |       h3 {
66 |         margin-top: 0;
67 |         margin-bottom: 0.25rem;
68 |         line-height: 1;
69 |       }
70 |     `,
71 |   ];
72 | 
73 |   @queryAsync('#portal-target')
74 |   portalTarget: Promise<HTMLElement>;
75 | 
76 |   render() {
77 |     return html`
78 |       <h2>Delegating portals</h2>
79 |       <p>
80 |         You can create components that define certain portalling behaviors but use values provided
81 |         by a parent component for the portal's content and target.
82 |       </p>
83 |       <dynamic-portal
84 |         .portalTarget=${this.portalTarget}
85 |         .portalContent=${html`<p>This is the portal content.</p>`}
86 |       ></dynamic-portal>
87 |       <div id="portal-target" class="portal-target">
88 |         <h3>Portal target</h3>
89 |       </div>
90 |     `;
91 |   }
92 | }
93 | 


--------------------------------------------------------------------------------
/dev/demo-intro-example.ts:
--------------------------------------------------------------------------------
  1 | import { LitElement, html, css } from 'lit';
  2 | import { customElement, queryAsync, state } from 'lit/decorators.js';
  3 | import { when } from 'lit/directives/when.js';
  4 | import { styleMap } from 'lit/directives/style-map.js';
  5 | import { portal } from '../src/portal';
  6 | 
  7 | @customElement('demo-intro-example')
  8 | export class DemoIntroExample extends LitElement {
  9 |   static styles = [
 10 |     css`
 11 |       #wrapper {
 12 |         display: flex;
 13 |         flex-wrap: wrap;
 14 |         border: 1px solid black;
 15 |         align-items: stretch;
 16 |         gap: 0.5rem;
 17 |         padding: 0.25rem;
 18 |       }
 19 | 
 20 |       #buttons {
 21 |         display: flex;
 22 |         flex-direction: column;
 23 |         gap: 0.5rem;
 24 |         align-items: flex-start;
 25 |       }
 26 | 
 27 |       #portal-target {
 28 |         border: 1px solid black;
 29 |         padding: 0.25rem;
 30 |         display: flex;
 31 |         flex-direction: column;
 32 |         gap: 0.25rem;
 33 |       }
 34 | 
 35 |       #portal-target h3 {
 36 |         margin-top: 0;
 37 |         margin-bottom: 0.25rem;
 38 |         line-height: 1;
 39 |       }
 40 |     `,
 41 |   ];
 42 | 
 43 |   @state()
 44 |   enablePortal1 = false;
 45 | 
 46 |   @state()
 47 |   enablePortal2 = false;
 48 | 
 49 |   @state()
 50 |   enablePortal3 = false;
 51 | 
 52 |   @queryAsync('#portal-target')
 53 |   portalTarget: Promise<HTMLElement>;
 54 | 
 55 |   portalContentStyles = {
 56 |     borderWidth: '2px',
 57 |     borderStyle: 'solid',
 58 |     padding: '0.25rem',
 59 |   };
 60 | 
 61 |   portalContent(label: string, borderColor: string, closeCallback: Function) {
 62 |     return html`
 63 |       <div style=${styleMap({ borderColor, ...this.portalContentStyles })}>
 64 |         <p>${label} content</p>
 65 |         <button @click=${closeCallback}>Close ${label}</button>
 66 |       </div>
 67 |     `;
 68 |   }
 69 | 
 70 |   render() {
 71 |     return html`
 72 |       <div id="wrapper">
 73 |         <div id="buttons">
 74 |           <button @click=${() => (this.enablePortal1 = true)}>Enable Portal 1</button>
 75 |           ${when(this.enablePortal1, () =>
 76 |             portal(
 77 |               this.portalContent('Portal 1', 'red', () => (this.enablePortal1 = false)),
 78 |               this.portalTarget,
 79 |             ),
 80 |           )}
 81 | 
 82 |           <button @click=${() => (this.enablePortal2 = true)}>Enable Portal 2</button>
 83 |           ${when(this.enablePortal2, () =>
 84 |             portal(
 85 |               this.portalContent('Portal 2', 'blue', () => (this.enablePortal2 = false)),
 86 |               this.portalTarget,
 87 |             ),
 88 |           )}
 89 | 
 90 |           <button @click=${() => (this.enablePortal3 = true)}>Enable Portal 3</button>
 91 |           ${when(this.enablePortal3, () =>
 92 |             portal(
 93 |               this.portalContent('Portal 3', 'green', () => (this.enablePortal3 = false)),
 94 |               this.portalTarget,
 95 |             ),
 96 |           )}
 97 |         </div>
 98 |         <div id="portal-target">
 99 |           <h3>Portal target</h3>
100 |         </div>
101 |       </div>
102 |     `;
103 |   }
104 | }
105 | 
106 | declare global {
107 |   interface HTMLElementTagNameMap {
108 |     'demo-intro-example': DemoIntroExample;
109 |   }
110 | }
111 | 


--------------------------------------------------------------------------------
/docs/assets/highlight.css:
--------------------------------------------------------------------------------
  1 | :root {
  2 |     --light-hl-0: #001080;
  3 |     --dark-hl-0: #9CDCFE;
  4 |     --light-hl-1: #000000;
  5 |     --dark-hl-1: #D4D4D4;
  6 |     --light-hl-2: #008000;
  7 |     --dark-hl-2: #6A9955;
  8 |     --light-hl-3: #800000;
  9 |     --dark-hl-3: #808080;
 10 |     --light-hl-4: #800000;
 11 |     --dark-hl-4: #569CD6;
 12 |     --light-hl-5: #E50000;
 13 |     --dark-hl-5: #9CDCFE;
 14 |     --light-hl-6: #000000FF;
 15 |     --dark-hl-6: #D4D4D4;
 16 |     --light-hl-7: #0000FF;
 17 |     --dark-hl-7: #CE9178;
 18 |     --light-hl-8: #AF00DB;
 19 |     --dark-hl-8: #C586C0;
 20 |     --light-hl-9: #A31515;
 21 |     --dark-hl-9: #CE9178;
 22 |     --light-hl-10: #795E26;
 23 |     --dark-hl-10: #DCDCAA;
 24 |     --light-hl-11: #0000FF;
 25 |     --dark-hl-11: #569CD6;
 26 |     --light-hl-12: #267F99;
 27 |     --dark-hl-12: #4EC9B0;
 28 |     --light-code-background: #FFFFFF;
 29 |     --dark-code-background: #1E1E1E;
 30 | }
 31 | 
 32 | @media (prefers-color-scheme: light) { :root {
 33 |     --hl-0: var(--light-hl-0);
 34 |     --hl-1: var(--light-hl-1);
 35 |     --hl-2: var(--light-hl-2);
 36 |     --hl-3: var(--light-hl-3);
 37 |     --hl-4: var(--light-hl-4);
 38 |     --hl-5: var(--light-hl-5);
 39 |     --hl-6: var(--light-hl-6);
 40 |     --hl-7: var(--light-hl-7);
 41 |     --hl-8: var(--light-hl-8);
 42 |     --hl-9: var(--light-hl-9);
 43 |     --hl-10: var(--light-hl-10);
 44 |     --hl-11: var(--light-hl-11);
 45 |     --hl-12: var(--light-hl-12);
 46 |     --code-background: var(--light-code-background);
 47 | } }
 48 | 
 49 | @media (prefers-color-scheme: dark) { :root {
 50 |     --hl-0: var(--dark-hl-0);
 51 |     --hl-1: var(--dark-hl-1);
 52 |     --hl-2: var(--dark-hl-2);
 53 |     --hl-3: var(--dark-hl-3);
 54 |     --hl-4: var(--dark-hl-4);
 55 |     --hl-5: var(--dark-hl-5);
 56 |     --hl-6: var(--dark-hl-6);
 57 |     --hl-7: var(--dark-hl-7);
 58 |     --hl-8: var(--dark-hl-8);
 59 |     --hl-9: var(--dark-hl-9);
 60 |     --hl-10: var(--dark-hl-10);
 61 |     --hl-11: var(--dark-hl-11);
 62 |     --hl-12: var(--dark-hl-12);
 63 |     --code-background: var(--dark-code-background);
 64 | } }
 65 | 
 66 | :root[data-theme='light'] {
 67 |     --hl-0: var(--light-hl-0);
 68 |     --hl-1: var(--light-hl-1);
 69 |     --hl-2: var(--light-hl-2);
 70 |     --hl-3: var(--light-hl-3);
 71 |     --hl-4: var(--light-hl-4);
 72 |     --hl-5: var(--light-hl-5);
 73 |     --hl-6: var(--light-hl-6);
 74 |     --hl-7: var(--light-hl-7);
 75 |     --hl-8: var(--light-hl-8);
 76 |     --hl-9: var(--light-hl-9);
 77 |     --hl-10: var(--light-hl-10);
 78 |     --hl-11: var(--light-hl-11);
 79 |     --hl-12: var(--light-hl-12);
 80 |     --code-background: var(--light-code-background);
 81 | }
 82 | 
 83 | :root[data-theme='dark'] {
 84 |     --hl-0: var(--dark-hl-0);
 85 |     --hl-1: var(--dark-hl-1);
 86 |     --hl-2: var(--dark-hl-2);
 87 |     --hl-3: var(--dark-hl-3);
 88 |     --hl-4: var(--dark-hl-4);
 89 |     --hl-5: var(--dark-hl-5);
 90 |     --hl-6: var(--dark-hl-6);
 91 |     --hl-7: var(--dark-hl-7);
 92 |     --hl-8: var(--dark-hl-8);
 93 |     --hl-9: var(--dark-hl-9);
 94 |     --hl-10: var(--dark-hl-10);
 95 |     --hl-11: var(--dark-hl-11);
 96 |     --hl-12: var(--dark-hl-12);
 97 |     --code-background: var(--dark-code-background);
 98 | }
 99 | 
100 | .hl-0 { color: var(--hl-0); }
101 | .hl-1 { color: var(--hl-1); }
102 | .hl-2 { color: var(--hl-2); }
103 | .hl-3 { color: var(--hl-3); }
104 | .hl-4 { color: var(--hl-4); }
105 | .hl-5 { color: var(--hl-5); }
106 | .hl-6 { color: var(--hl-6); }
107 | .hl-7 { color: var(--hl-7); }
108 | .hl-8 { color: var(--hl-8); }
109 | .hl-9 { color: var(--hl-9); }
110 | .hl-10 { color: var(--hl-10); }
111 | .hl-11 { color: var(--hl-11); }
112 | .hl-12 { color: var(--hl-12); }
113 | pre, code { background: var(--code-background); }
114 | 


--------------------------------------------------------------------------------
/dev/demo-async.ts:
--------------------------------------------------------------------------------
  1 | import { LitElement, html, css } from 'lit';
  2 | import { customElement, queryAsync } from 'lit/decorators.js';
  3 | import { portal } from '../src/portal';
  4 | 
  5 | @customElement('demo-async')
  6 | export class DemoAsync extends LitElement {
  7 |   static styles = [
  8 |     css`
  9 |       .wrapper {
 10 |         display: flex;
 11 |         flex-wrap: wrap;
 12 |         border: 1px solid black;
 13 |         align-items: stretch;
 14 |         gap: 0.5rem;
 15 |         padding: 0.25rem;
 16 |       }
 17 | 
 18 |       h3 {
 19 |         margin-top: 0;
 20 |         margin-bottom: 0.25rem;
 21 |         line-height: 1;
 22 |       }
 23 | 
 24 |       .portal-target {
 25 |         flex-basis: 0;
 26 |         flex-grow: 1;
 27 |         border: 1px solid black;
 28 |         padding: 0.25rem;
 29 |       }
 30 |     `,
 31 |   ];
 32 | 
 33 |   @queryAsync('#portal-target')
 34 |   portalTarget: Promise<HTMLElement>;
 35 | 
 36 |   @queryAsync('#second-portal-target')
 37 |   secondPortalTarget: Promise<HTMLElement>;
 38 | 
 39 |   async getAsynchronousContent(content: unknown) {
 40 |     const sleepPromise = new Promise((resolve) => setTimeout(resolve, 3000));
 41 |     return sleepPromise.then(() => content);
 42 |   }
 43 | 
 44 |   render() {
 45 |     return html`
 46 |       <h2>Asynchronous Content</h2>
 47 |       <p>
 48 |         You can provide a
 49 |         <a
 50 |           href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise"
 51 |           ><code>Promise</code></a
 52 |         >
 53 |         to the <code>portal</code> directive, both for the content of the portal as well as the
 54 |         target.
 55 |       </p>
 56 |       <p>
 57 |         Using a promise for the target can be useful when the target is part of a Lit component that
 58 |         may have not yet rendered or can change. The examples earlier in this demo used Lit's
 59 |         <a target="_blank" href="https://lit.dev/docs/api/decorators/#queryAsync"
 60 |           ><code>queryAsync</code></a
 61 |         >
 62 |         decorator for exactly these reasons.
 63 |       </p>
 64 |       <p>
 65 |         Using a promise for the portal content is useful when the content relies on asynchronous
 66 |         data, such as that received from an HTTPRequest.
 67 |       </p>
 68 |       <div class="wrapper">
 69 |         <p>
 70 |           This example renders one portal immediately when the page loads and another portal after a
 71 |           few seconds. You may refresh this webpage in order to repeat the example.
 72 |         </p>
 73 |         ${portal(html`<p>This portal renders immediately.</p>`, this.portalTarget)}
 74 |         ${portal(
 75 |           this.getAsynchronousContent(html`<p>This portal renders three seconds later.</p>`),
 76 |           this.portalTarget,
 77 |         )}
 78 |         <div id="portal-target" class="portal-target">
 79 |           <h3>Portal target</h3>
 80 |         </div>
 81 |       </div>
 82 |       <p>You can provide a placeholder value to render until the content promise resolves.</p>
 83 |       <div class="wrapper">
 84 |         <p>
 85 |           This example is similar to the previous one, except the second portal is also rendered
 86 |           immediately with placeholder content. Like before, you may refresh the page to observe the
 87 |           placeholder being replaced with the other content.
 88 |         </p>
 89 |         ${portal(html`<p>This portal renders immediately.</p>`, this.secondPortalTarget)}
 90 |         ${portal(
 91 |           this.getAsynchronousContent(
 92 |             html`<p>
 93 |               This portal rendered first with a placeholder and was updated after three seconds.
 94 |             </p>`,
 95 |           ),
 96 |           this.secondPortalTarget,
 97 |           {
 98 |             placeholder: html`<p>Placeholder</p>`,
 99 |           },
100 |         )}
101 |         <div id="second-portal-target" class="portal-target">
102 |           <h3>Portal target</h3>
103 |         </div>
104 |         <p>
105 |           Observe that the portal with a placeholder appears above the other portal. This behaviour
106 |           is unexpected and possibly results from a race condition, since both portals have the same
107 |           target.
108 |         </p>
109 |       </div>
110 |     `;
111 |   }
112 | }
113 | 
114 | declare global {
115 |   interface HTMLElementTagNameMap {
116 |     'demo-async': DemoAsync;
117 |   }
118 | }
119 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
  1 | # Changelog
  2 | 
  3 | All notable changes to this project will be documented in this file.
  4 | 
  5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
  6 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
  7 | 
  8 | ## [Unreleased]
  9 | 
 10 | ### Added
 11 | - Notes about creating components that delegate portal behavior and render generic content provided by parent components.
 12 | 
 13 | ## [0.8.0] - 2025-05-03
 14 | 
 15 | ### Added
 16 | - Add `modifyContainer` function to `portal` directive options.
 17 | 
 18 | ### Fixed
 19 | - Fixed bugs in esbuild.config.js
 20 | 
 21 | ## [0.7.1] - 2025-02-16
 22 | 
 23 | ### Fixed
 24 | - Fix typo in typedoc
 25 | - Typos in README
 26 | 
 27 | ### Changed
 28 | - Updated dev dependencies
 29 | 
 30 | ## [0.7.0] - 2024-04-17
 31 | 
 32 | ### Fixed
 33 | - Added `TargetOrSelector` type alias to typedoc.
 34 | 
 35 | ### Changed
 36 | - Improved how portals can be cleaned up during tests.
 37 | - The disconnected method on the `portal` directive now checks that the portal container is in the target's children.
 38 |   If not, then a warning will be printed that the container was already removed from the target.
 39 | 
 40 |   The prevalence of this issue is unknown, but it was encountered while working with components
 41 |   in portals rendered using `open-wc`'s `fixture` helper.
 42 | - Refactor lambdas out of tests to support setting the Mocha timeout limit.
 43 | - Refactor the `portal` directive's `value` argument to be named `content`.
 44 | 
 45 | ### Added
 46 | - Tests for Lit lifecycle methods called on components that are in portals.
 47 | - Support for asynchronous portal content, with tests and demo code.
 48 |   - Portals with asynchronous content can render a placeholder while the content resolves.
 49 | 
 50 | ## [0.6.2] - 2024-04-09
 51 | 
 52 | ### Changed
 53 | - Refactored type of portal target to be `Node` instead of `HTMLElement`.
 54 | 
 55 | ## [0.6.1] - 2024-04-07
 56 | 
 57 | ### Changed
 58 | - Removed the "(currently unreleased)" text from the README notice about version 0.6
 59 | 
 60 | ## [0.6.0] - 2024-04-07
 61 | 
 62 | Major refactor.
 63 | 
 64 | ### Added
 65 | - Some tests! Can you even believe that?
 66 | 
 67 | ### Changed
 68 | - Almost everything, but especially the `portal` directive
 69 | 
 70 | ### Removed
 71 | - Almost everything else, notably the `modalController` and the `<modal-portal>` component.
 72 | 
 73 | ## [0.5.0-pre] - 2024-03-27
 74 | Thanks to [klasjersevi](https://github.com/klasjersevi)
 75 | 
 76 | ### Changed
 77 | - Updated dependencies.
 78 | - Explicitly set tsconfig in esbuild usage.
 79 | 
 80 | ### Fixed
 81 | - Set Lit to be a peer dependency.
 82 | 
 83 | ## [0.4.1] - 2022-06-16
 84 | ### Fixed
 85 | - Example code in README.md
 86 | 
 87 | ## [0.4.0] - 2022-06-16
 88 | ### Added
 89 | - Demo video in README.md
 90 | 
 91 | ### Removed
 92 | - Minified build
 93 | 
 94 | ## [0.3.1] - 2022-06-13
 95 | ### Changed
 96 | - Refactored the modules and exports again to permit usage of the minified build.
 97 | 
 98 | ### Added
 99 | - All the things that should be in a README.
100 | 
101 | ## [0.3.0] - 2022-06-13
102 | ### Changed
103 | - Reconfigured `index` and `lib` modules to actually work for both docs and exports.
104 | 
105 | ## [0.2.1] - 2022-06-10
106 | ### Changed
107 | - Set immutable-js to be a regular dependency.
108 | 
109 | ### Fixed
110 | - The links in the changelog, lol.
111 | 
112 | ## [0.2.0] - 2022-06-10
113 | First release tag.
114 | 
115 | [Unreleased]: https://github.com/nicholas-wilcox/lit-modal-portal/compare/v0.8.0...HEAD
116 | [0.8.0]: https://github.com/nicholas-wilcox/lit-modal-portal/compare/v0.7.1...v0.8.0
117 | [0.7.1]: https://github.com/nicholas-wilcox/lit-modal-portal/compare/v0.7.0...v0.7.1
118 | [0.7.0]: https://github.com/nicholas-wilcox/lit-modal-portal/compare/v0.6.2...v0.7.0
119 | [0.6.2]: https://github.com/nicholas-wilcox/lit-modal-portal/compare/v0.6.1...v0.6.2
120 | [0.6.1]: https://github.com/nicholas-wilcox/lit-modal-portal/compare/v0.6.0...v0.6.1
121 | [0.6.0]: https://github.com/nicholas-wilcox/lit-modal-portal/compare/v0.5.0-pre...v0.6.0
122 | [0.5.0-pre]: https://github.com/nicholas-wilcox/lit-modal-portal/compare/v0.4.1...v0.5.0-pre
123 | [0.4.1]: https://github.com/nicholas-wilcox/lit-modal-portal/compare/v0.4.0...v0.4.1
124 | [0.4.0]: https://github.com/nicholas-wilcox/lit-modal-portal/compare/v0.3.1...v0.4.0
125 | [0.3.1]: https://github.com/nicholas-wilcox/lit-modal-portal/compare/v0.3.0...v0.3.1
126 | [0.3.0]: https://github.com/nicholas-wilcox/lit-modal-portal/compare/v0.2.1...v0.3.0
127 | [0.2.1]: https://github.com/nicholas-wilcox/lit-modal-portal/compare/v0.2.0...v0.2.1
128 | [0.2.0]: https://github.com/nicholas-wilcox/lit-modal-portal/releases/tag/v0.2.0
129 | 


--------------------------------------------------------------------------------
/docs/types/TargetOrSelector.html:
--------------------------------------------------------------------------------
1 | <!DOCTYPE html><html class="default" lang="en" data-base=".."><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>TargetOrSelector | Lit Modal Portal Documentation</title><meta name="description" content="Documentation for Lit Modal Portal Documentation"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search"><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="../index.html" class="title">Lit Modal Portal Documentation</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb"><li><a href="../modules.html">Lit Modal Portal Documentation</a></li><li><a href="TargetOrSelector.html">TargetOrSelector</a></li></ul><h1>Type Alias TargetOrSelector</h1></div><div class="tsd-signature"><span class="tsd-kind-type-alias">TargetOrSelector</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Node</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">string</span></div><div class="tsd-comment tsd-typography"><p>The acceptable types used to specify a portal target.</p>
2 | </div><div class="tsd-comment tsd-typography"></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/nicholas-wilcox/lit-modal-portal/blob/be82851f21b339aca2b221f9473e0791861e2360/src/portal.ts#L8">src/portal.ts:8</a></li></ul></aside></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">Lit Modal Portal Documentation</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
3 | 


--------------------------------------------------------------------------------
/dev/demo-reactive.ts:
--------------------------------------------------------------------------------
  1 | import { LitElement, html, css } from 'lit';
  2 | import { customElement, state, queryAsync } from 'lit/decorators.js';
  3 | import { when } from 'lit/directives/when.js';
  4 | import { portal } from '../src/portal';
  5 | 
  6 | import './example-component';
  7 | 
  8 | @customElement('demo-reactive')
  9 | export class DemoReactive extends LitElement {
 10 |   static styles = [
 11 |     css`
 12 |       .wrapper {
 13 |         display: flex;
 14 |         flex-wrap: wrap;
 15 |         border: 1px solid black;
 16 |         align-items: stretch;
 17 |         gap: 0.5rem;
 18 |         padding: 0.25rem;
 19 |       }
 20 | 
 21 |       .current-time,
 22 |       .portal-target {
 23 |         border: 1px solid black;
 24 |         padding: 0.25rem;
 25 |       }
 26 | 
 27 |       h3 {
 28 |         margin-top: 0;
 29 |         margin-bottom: 0.25rem;
 30 |         line-height: 1;
 31 |       }
 32 | 
 33 |       .multi-portal-target-wrapper {
 34 |         flex-grow: 1;
 35 |       }
 36 |       .multi-portal-target-subwrapper {
 37 |         display: flex;
 38 |         flex-wrap: wrap;
 39 |         gap: 0.25rem;
 40 |       }
 41 | 
 42 |       .multi-portal-target-subwrapper .portal-target {
 43 |         flex-basis: 0;
 44 |         flex-grow: 1;
 45 |       }
 46 | 
 47 |       #component-portal-target {
 48 |         flex-basis: 100%;
 49 |       }
 50 |     `,
 51 |   ];
 52 | 
 53 |   @state()
 54 |   timeString = new Date().toLocaleTimeString();
 55 | 
 56 |   @state()
 57 |   multiPortalTargetIndex = 0;
 58 | 
 59 |   intervalId = undefined;
 60 | 
 61 |   @queryAsync('#single-portal-target')
 62 |   singlePortalTarget: Promise<HTMLElement>;
 63 | 
 64 |   @queryAsync('.portal-target[data-current-portal-target=true]')
 65 |   multiPortalTarget: Promise<HTMLElement>;
 66 | 
 67 |   @state()
 68 |   showComponentPortal = false;
 69 | 
 70 |   @queryAsync('#component-portal-target')
 71 |   componentPortalTarget: Promise<HTMLElement>;
 72 | 
 73 |   connectedCallback() {
 74 |     super.connectedCallback();
 75 |     this.intervalId = setInterval(() => {
 76 |       this.timeString = new Date().toLocaleTimeString();
 77 |       this.multiPortalTargetIndex = (this.multiPortalTargetIndex + 1) % 3;
 78 |     }, 1000);
 79 |   }
 80 | 
 81 |   disconnectedCallback() {
 82 |     super.disconnectedCallback();
 83 |     clearInterval(this.intervalId);
 84 |   }
 85 | 
 86 |   render() {
 87 |     return html`
 88 |       <h2>Reactive Updates</h2>
 89 |       <p>
 90 |         When the component that consumes the <code>portal</code> directive re-renders and changes
 91 |         the content of the portal, the directive will re-render the new content in the same
 92 |         container. In other words, portals are reactive.
 93 |       </p>
 94 |       <p>
 95 |         This section of the demo is a component that manages an
 96 |         <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/API/setInterval"
 97 |           >interval</a
 98 |         >
 99 |         to update its internal reactive state once per second. The current time is rendered both
100 |         directly in the component's template and also in the content of a portal.
101 |       </p>
102 |       <div class="wrapper">
103 |         <div class="current-time">
104 |           <h3>Current time</h3>
105 |           <p>${this.timeString}</p>
106 |           ${portal(html`<p>${this.timeString}</p>`, this.singlePortalTarget)}
107 |         </div>
108 |         <div id="single-portal-target" class="portal-target">
109 |           <h3>Portal target</h3>
110 |         </div>
111 |       </div>
112 | 
113 |       <!-- Dynamically changing the portal target -->
114 |       <p>
115 |         In addition to updating the content of a portal,
116 |         <em>you can also update a portal's target</em>. This will remove the portal's content from
117 |         the old target and append it to the new target. (Credit to
118 |         <a target="_blank" href="https://github.com/ronak-lm/lit-portal"
119 |           >ronak-lm's <code>lit-portal</code> package</a
120 |         >
121 |         for designing and implementing this behavior before I did.)
122 |       </p>
123 |       <div class="wrapper">
124 |         <div class="current-time">
125 |           <h3>Current time</h3>
126 |           <p>${this.timeString}</p>
127 |           ${portal(html`<p>${this.timeString}</p>`, this.multiPortalTarget)}
128 |         </div>
129 |         <div class="multi-portal-target-wrapper">
130 |           <h3>Portal targets</h3>
131 |           <div class="multi-portal-target-subwrapper">
132 |             <div
133 |               id="multi-portal-target-0"
134 |               class="portal-target"
135 |               data-current-portal-target=${this.multiPortalTargetIndex === 0}
136 |             ></div>
137 |             <div
138 |               id="multi-portal-target-1"
139 |               class="portal-target"
140 |               data-current-portal-target=${this.multiPortalTargetIndex === 1}
141 |             ></div>
142 |             <div
143 |               id="multi-portal-target-2"
144 |               class="portal-target"
145 |               data-current-portal-target=${this.multiPortalTargetIndex === 2}
146 |             ></div>
147 |           </div>
148 |         </div>
149 |       </div>
150 | 
151 |       <!-- Send another Lit component through a portal -->
152 |       <p>
153 |         Finally, as you would expect, a Lit component can be rendered through a portal and still
154 |         work.
155 |       </p>
156 |       <div class="wrapper">
157 |         ${when(this.showComponentPortal, () =>
158 |           portal(html`<example-component></example-component>`, this.componentPortalTarget),
159 |         )}
160 |         <p>
161 |           Right above this paragraph's <code>&lt;p&gt;</code> tag is a <code>portal</code> directive
162 |           that renders an example component in the following portal target <code>&lt;div&gt;</code>.
163 |         </p>
164 |         <p>
165 |           The portal can be toggled using the button below this text. You can observe that the
166 |           components lifecycle methods are called appropriately by looking at the console logs.
167 |         </p>
168 |         <button @click=${() => (this.showComponentPortal = !this.showComponentPortal)}>
169 |           Toggle Portal
170 |         </button>
171 |         <div id="component-portal-target" class="portal-target">
172 |           <h3>Portal target</h3>
173 |         </div>
174 |       </div>
175 |     `;
176 |   }
177 | }
178 | 


--------------------------------------------------------------------------------
/dev/demo-modals.ts:
--------------------------------------------------------------------------------
  1 | import { LitElement, html } from 'lit';
  2 | import { StyleInfo, styleMap } from 'lit/directives/style-map.js';
  3 | import { customElement, state } from 'lit/decorators.js';
  4 | import { ref, createRef } from 'lit/directives/ref.js';
  5 | import { when } from 'lit/directives/when.js';
  6 | import { portal } from '../src/portal';
  7 | import './confirmation-dialog';
  8 | 
  9 | const modalStyles: StyleInfo = {
 10 |   position: 'fixed',
 11 |   background: 'hsl(0deg 0% 0% / 0.4)',
 12 |   inset: 0,
 13 |   padding: '1rem',
 14 | };
 15 | 
 16 | const modalContentStyles: StyleInfo = {
 17 |   background: 'white',
 18 |   padding: '1rem',
 19 | };
 20 | 
 21 | @customElement('demo-modals')
 22 | export class DemoModals extends LitElement {
 23 |   @state()
 24 |   enableModalPortal = false;
 25 | 
 26 |   dialogRef = createRef<HTMLDialogElement>();
 27 | 
 28 |   confirmationDialogRef = createRef<HTMLDialogElement>();
 29 | 
 30 |   @state()
 31 |   confirmationResponse: unknown;
 32 | 
 33 |   render() {
 34 |     return html`
 35 |       <h2>Modals</h2>
 36 |       <p>
 37 |         The <code>portal</code> directive can be used to display modal content in the same way as
 38 |         React's <code>createPortal</code> function. In other words, simply target
 39 |         <code>document.body</code>. (Although you may prefer to create a dedicated
 40 |         <code>&lt;div&gt;</code> within the <code>&lt;body&gt;</code> and target that element
 41 |         instead.)
 42 |       </p>
 43 | 
 44 |       <!-- Showing a modal based on a boolean flag -->
 45 |       <p>The button below will enable a portal that contains modal content.</p>
 46 |       <button @click=${() => (this.enableModalPortal = true)}>Show Modal</button>
 47 |       ${when(this.enableModalPortal, () =>
 48 |         portal(
 49 |           html`<div style=${styleMap(modalStyles)}>
 50 |             <div style=${styleMap(modalContentStyles)}>
 51 |               <p>
 52 |                 This is the modal. It is a <code>&lt;div&gt;</code> with fixed positioning, zero
 53 |                 insets, and a slightly transparent background color.
 54 |               </p>
 55 |               <button @click=${() => (this.enableModalPortal = false)}>Close Modal</button>
 56 |             </div>
 57 |           </div>`,
 58 |           document.body,
 59 |         ),
 60 |       )}
 61 | 
 62 |       <!-- Imperatively showing a dialog -->
 63 |       <p>
 64 |         Alternatively, you can use the <code>portal</code> directive with
 65 |         <code>&lt;dialog&gt;</code> elements. Rather than conditionally including a portal based on
 66 |         a boolean flag, you can simply render the <code>&lt;dialog&gt;</code> in the portal and
 67 |         imperatively call the
 68 |         <a
 69 |           target="_blank"
 70 |           href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal"
 71 |           ><code>HTMLDialogElement.showModal()</code> method</a
 72 |         >.
 73 |       </p>
 74 |       <p>
 75 |         The button below does exactly that by using a
 76 |         <a
 77 |           target="_blank"
 78 |           href="https://lit.dev/docs/templates/directives/#referencing-rendered-dom"
 79 |           >Lit ref</a
 80 |         >
 81 |         that is attached to the <code>&lt;dialog&gt;</code> element used in the portal.
 82 |       </p>
 83 |       <button @click=${() => this.dialogRef.value?.showModal()}>Show Dialog</button>
 84 |       ${portal(
 85 |         html`<dialog ${ref(this.dialogRef)}>
 86 |           <p>
 87 |             This is a paragraph in a <code>&lt;dialog&gt;</code> element. You are seeing it because
 88 |             its <code>showModal</code> function was called.
 89 |           </p>
 90 |           <p>
 91 |             You may close the dialog by clicking the button below or by pressing the Escape key.
 92 |           </p>
 93 |           <button @click=${() => this.dialogRef.value?.close()}>Close Dialog</button>
 94 |         </dialog>`,
 95 |         document.body,
 96 |       )}
 97 | 
 98 |       <h3>Confirmation Dialogs</h3>
 99 |       <p>Putting all of this together, we can create a confirmation dialog component.</p>
100 |       <button @click=${() => this.confirmationDialogRef.value?.showModal()}>
101 |         Show Confirmation Dialog
102 |       </button>
103 |       ${portal(
104 |         html`<confirmation-dialog
105 |           @close=${() => {
106 |             this.confirmationResponse = this.confirmationDialogRef.value?.returnValue;
107 |           }}
108 |           .dialogRef=${this.confirmationDialogRef}
109 |         ></confirmation-dialog>`,
110 |         document.body,
111 |       )}
112 |       ${when(
113 |         this.confirmationResponse,
114 |         () => html`<span><strong>Return value:</strong> ${this.confirmationResponse}</span>`,
115 |       )}
116 |       <p>
117 |         The component shown with the button above accepts a Lit ref as a property. This means that
118 |         the parent component can call the dialog's <code>showModal</code> method to open the dialog.
119 |         The <code>&lt;confirmation-dialog&gt;</code> component that contains the dialog has two
120 |         buttons that each close it, but with a different return value. (See
121 |         <a
122 |           target="_blank"
123 |           href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/close"
124 |           >MDN documentation</a
125 |         >
126 |         on the <code>HTMLDialogElement.close()</code> method.)
127 |       </p>
128 |       <p>
129 |         Additionally, the
130 |         <code>&lt;confirmation-dialog&gt;</code> component listens to and forwards the
131 |         <code>&lt;dialog&gt;</code>'s <code>close</code> event. This allows the parent component to
132 |         react and update based on the return value. Note that closing the dialog with the Escape key
133 |         does not change the <code>returnValue</code> attribute of the dialog.
134 |       </p>
135 |       <p>
136 |         On a final note, consider that there are many different ways that you might want to
137 |         implement and use a modal. You may want to avoid using a <code>&lt;dialog&gt;</code> tag, or
138 |         you may prefer a component that accepts callback functions over a component that dispatches
139 |         events. For these reasons, I've decided to focus on the utility of the
140 |         <code>portal</code> directive and not provide any modal components in this package's
141 |         exports.
142 |       </p>
143 |     `;
144 |   }
145 | }
146 | 


--------------------------------------------------------------------------------
/src/portal.ts:
--------------------------------------------------------------------------------
  1 | import { render as litRender, nothing } from 'lit';
  2 | import { directive } from 'lit/directive.js';
  3 | import { AsyncDirective } from 'lit/async-directive.js';
  4 | 
  5 | /**
  6 |  * The acceptable types used to specify a portal target.
  7 |  */
  8 | export type TargetOrSelector = Node | string;
  9 | 
 10 | /**
 11 |  * @property placeholder - When provided, `placeholder` will be immediately rendered in the portal.
 12 |  * Assuming that `content` is a promise, it will replace the placeholder once it resolves.
 13 |  *
 14 |  * @property modifyContainer - When provided, the `modifyContainer` function will be called with
 15 |  * the portal's container given as the argument. This allows you to programmatically control the
 16 |  * container before the portal renders.
 17 |  */
 18 | export interface PortalOptions {
 19 |   placeholder?: unknown;
 20 |   modifyContainer?: (container: HTMLElement) => void;
 21 | }
 22 | 
 23 | /**
 24 |  * Utility function to get an HTMLElement by reference or by a document query selector.
 25 |  */
 26 | function getTarget(targetOrSelector: TargetOrSelector): Node {
 27 |   let target = targetOrSelector;
 28 |   // Treat the argument as a query selector if it's a string.
 29 |   if (typeof target === 'string') {
 30 |     target = document.querySelector(target) as Node;
 31 |     if (target === null) {
 32 |       throw Error(`Could not locate portal target with selector "${targetOrSelector}".`);
 33 |     }
 34 |   }
 35 | 
 36 |   return target;
 37 | }
 38 | 
 39 | /**
 40 |  * A directive to render a Lit template somewhere in the DOM.
 41 |  *
 42 |  * See [Lit docs on Custom Directives](https://lit.dev/docs/templates/custom-directives/).
 43 |  */
 44 | export class PortalDirective extends AsyncDirective {
 45 |   private containerId = `portal-${self.crypto.randomUUID()}`;
 46 |   private container: HTMLElement | undefined;
 47 |   private target: Node | undefined;
 48 | 
 49 |   /**
 50 |    * Main render function for the directive.
 51 |    *
 52 |    * For clarity's sake, here is the outline of the function body::
 53 |    *
 54 |    * - Resolve `targetOrSelector` to an element.
 55 |    *
 56 |    * - If the directive's `container` property is `undefined`,
 57 |    *   - then create the container element and store it in the property.
 58 |    *
 59 |    * - If `modifyContainer` is provided in the `options`,
 60 |    *   - then call `modifyContainer(container)`.
 61 |    *
 62 |    * - If the target has changed from one element to another,
 63 |    *   - then migrate `container` to the new target and reassign the directive's `target` property.
 64 |    *
 65 |    * - If the directive's `target` property is `undefined`,
 66 |    *   - then store the target element in the property.
 67 |    *
 68 |    *   - If a `placeholder` is provided in the `options`,
 69 |    *     - then append `container` to `target` (if necessary) and render `placeholder` in `container`.
 70 |    *
 71 |    * - Resolve `content` (awaited).
 72 |    *
 73 |    * - Append `container` to `target` (if necessary) and render `content` in `container`.
 74 |    *
 75 |    * The steps are organized this way to balance the initalization and refreshing of crucial properties
 76 |    * like `container` and `target` while ensuring that `container` isn't added to the DOM until
 77 |    * the directive is about to render something (either `placeholder` or `content`).
 78 |    *
 79 |    * @param content - The content of the portal.
 80 |    * This parameter is passed as the `value` parameter in [Lit's `render` function](https://lit.dev/docs/api/templates/#render).
 81 |    *
 82 |    * The `content` parameter can be a promise, which will be rendered in the portal once it resolves.
 83 |    *
 84 |    * @param targetOrSelector - The "target" for the portal.
 85 |    * If the value is a string, then it is treated as a query selector and passed to `document.querySelector()` in order to locate the portal target.
 86 |    * If no element is found with the selector, then an error is thrown.
 87 |    *
 88 |    * @param options - See {@link PortalOptions}.
 89 |    *
 90 |    * @returns This function always returns Lit's [`nothing`](https://lit.dev/docs/api/templates/#nothing) value,
 91 |    * because nothing ever renders where the portal is used.
 92 |    */
 93 |   render(
 94 |     content: unknown | Promise<unknown>,
 95 |     targetOrSelector: TargetOrSelector | Promise<TargetOrSelector>,
 96 |     options?: PortalOptions,
 97 |   ) {
 98 |     // Resolve targetOrSelector first, because nothing can happen without that.
 99 |     Promise.resolve(targetOrSelector).then(async (targetOrSelector) => {
100 |       if (!targetOrSelector) {
101 |         throw Error(
102 |           "Target was falsy. Are you using a Lit ref before its value is defined? If so, try using Lit's @queryAsync decorator instead (https://lit.dev/docs/api/decorators/#queryAsync).",
103 |         );
104 |       }
105 |       const newTarget = getTarget(targetOrSelector);
106 | 
107 |       // Create container if it doesn't already exist.
108 |       if (!this.container) {
109 |         const newContainer = document.createElement('div');
110 |         newContainer.id = this.containerId;
111 |         if (options?.modifyContainer) {
112 |           options.modifyContainer(newContainer);
113 |         }
114 |         this.container = newContainer;
115 |       }
116 | 
117 |       // If we are getting a new target, then migrate the container.
118 |       if (this.target && this.target !== newTarget) {
119 |         this.target?.removeChild(this.container);
120 |         newTarget.appendChild(this.container);
121 |         this.target = newTarget;
122 |       }
123 | 
124 |       // Set the target if it's undefined
125 |       if (!this.target) {
126 |         this.target = newTarget;
127 | 
128 |         // Render the placeholder if it's provided
129 |         if (options?.placeholder) {
130 |           // Only append the container to the target if we are about to render.
131 |           if (!this.target.contains(this.container)) {
132 |             this.target.appendChild(this.container);
133 |           }
134 |           litRender(options.placeholder, this.container);
135 |         }
136 |       }
137 | 
138 |       const resolvedContent = await Promise.resolve(content);
139 | 
140 |       // Add the container to the target if it isn't included already.
141 |       if (!this.target.contains(this.container)) {
142 |         this.target.appendChild(this.container);
143 |       }
144 | 
145 |       litRender(resolvedContent, this.container);
146 |     });
147 | 
148 |     return nothing;
149 |   }
150 | 
151 |   /** Remove container from target when the directive is disconnected. */
152 |   protected disconnected(): void {
153 |     if (this.target?.contains(this.container)) {
154 |       this.target?.removeChild(this.container);
155 |     } else {
156 |       console.warn(
157 |         'portal directive was disconnected after the portal container was removed from the target.',
158 |       );
159 |     }
160 |   }
161 | 
162 |   /** Append container to target when the directive is reconnected. */
163 |   protected reconnected(): void {
164 |     this.target?.appendChild(this.container);
165 |   }
166 | }
167 | 
168 | /**
169 |  * To be used in Lit templates.
170 |  *
171 |  * See {@link PortalDirective.render | PortalDirective.render}
172 |  */
173 | export const portal = directive(PortalDirective);
174 | 


--------------------------------------------------------------------------------
/docs/functions/portal.html:
--------------------------------------------------------------------------------
1 | <!DOCTYPE html><html class="default" lang="en" data-base=".."><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>portal | Lit Modal Portal Documentation</title><meta name="description" content="Documentation for Lit Modal Portal Documentation"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search"><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="../index.html" class="title">Lit Modal Portal Documentation</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb"><li><a href="../modules.html">Lit Modal Portal Documentation</a></li><li><a href="portal.html">portal</a></li></ul><h1>Function portal</h1></div><section class="tsd-panel tsd-comment"><div class="tsd-comment tsd-typography"><p>To be used in Lit templates.</p>
2 | <p>See <a href="../classes/PortalDirective.html#render" class="tsd-kind-method">PortalDirective.render</a></p>
3 | </div><div class="tsd-comment tsd-typography"></div></section><section class="tsd-panel"><ul class="tsd-signatures"><li class=""><div class="tsd-signature tsd-anchor-link"><a id="portal" class="tsd-anchor"></a><span class="tsd-kind-call-signature">portal</span><span class="tsd-signature-symbol">(</span><br/>    <span class="tsd-signature-symbol">...</span><span class="tsd-kind-parameter">values</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">[</span><br/>        content<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">,</span><br/>        targetOrSelector<span class="tsd-signature-symbol">:</span> <a href="../types/TargetOrSelector.html" class="tsd-signature-type tsd-kind-type-alias">TargetOrSelector</a><br/>        <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><a href="../types/TargetOrSelector.html" class="tsd-signature-type tsd-kind-type-alias">TargetOrSelector</a><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol">,</span><br/>        options<span class="tsd-signature-symbol">?:</span> <a href="../interfaces/PortalOptions.html" class="tsd-signature-type tsd-kind-interface">PortalOptions</a><span class="tsd-signature-symbol">,</span><br/>    <span class="tsd-signature-symbol">]</span><span class="tsd-signature-symbol">,</span><br/><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">DirectiveResult</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-keyword">typeof</span> <a href="../classes/PortalDirective.html" class="tsd-signature-type tsd-kind-class">PortalDirective</a><span class="tsd-signature-symbol">&gt;</span><a href="#portal" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-parameters"><h4 class="tsd-parameters-title">Parameters</h4><ul class="tsd-parameter-list"><li><span><span class="tsd-signature-symbol">...</span><span class="tsd-kind-parameter">values</span>: <span class="tsd-signature-symbol">[</span><br/>    content<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">,</span><br/>    targetOrSelector<span class="tsd-signature-symbol">:</span> <a href="../types/TargetOrSelector.html" class="tsd-signature-type tsd-kind-type-alias">TargetOrSelector</a><br/>    <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><a href="../types/TargetOrSelector.html" class="tsd-signature-type tsd-kind-type-alias">TargetOrSelector</a><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol">,</span><br/>    options<span class="tsd-signature-symbol">?:</span> <a href="../interfaces/PortalOptions.html" class="tsd-signature-type tsd-kind-interface">PortalOptions</a><span class="tsd-signature-symbol">,</span><br/><span class="tsd-signature-symbol">]</span></span></li></ul></div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">DirectiveResult</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-keyword">typeof</span> <a href="../classes/PortalDirective.html" class="tsd-signature-type tsd-kind-class">PortalDirective</a><span class="tsd-signature-symbol">&gt;</span></h4><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/nicholas-wilcox/lit-modal-portal/blob/be82851f21b339aca2b221f9473e0791861e2360/src/portal.ts#L173">src/portal.ts:173</a></li></ul></aside></div></li></ul></section></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">Lit Modal Portal Documentation</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
4 | 


--------------------------------------------------------------------------------
/docs/modules.html:
--------------------------------------------------------------------------------
1 | <!DOCTYPE html><html class="default" lang="en" data-base="."><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>Lit Modal Portal Documentation</title><meta name="description" content="Documentation for Lit Modal Portal Documentation"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search"><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">Lit Modal Portal Documentation</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb"><li><a href="modules.html">Lit Modal Portal Documentation</a></li></ul><h1>Lit Modal Portal Documentation</h1></div><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Classes"><h2><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg> Classes</h2></summary><dl class="tsd-member-summaries"><dt class="tsd-member-summary"><a id="portaldirective" class="tsd-anchor"></a><span class="tsd-member-summary-name"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg><a href="classes/PortalDirective.html">PortalDirective</a><a href="#portaldirective" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></span></dt><dd class="tsd-member-summary"></dd></dl></details><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Interfaces"><h2><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg> Interfaces</h2></summary><dl class="tsd-member-summaries"><dt class="tsd-member-summary"><a id="portaloptions" class="tsd-anchor"></a><span class="tsd-member-summary-name"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Interface"><use href="assets/icons.svg#icon-256"></use></svg><a href="interfaces/PortalOptions.html">PortalOptions</a><a href="#portaloptions" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></span></dt><dd class="tsd-member-summary"></dd></dl></details><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Type Aliases"><h2><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg> Type Aliases</h2></summary><dl class="tsd-member-summaries"><dt class="tsd-member-summary"><a id="targetorselector" class="tsd-anchor"></a><span class="tsd-member-summary-name"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Type Alias"><use href="assets/icons.svg#icon-2097152"></use></svg><a href="types/TargetOrSelector.html">TargetOrSelector</a><a href="#targetorselector" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></span></dt><dd class="tsd-member-summary"></dd></dl></details><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Functions"><h2><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg> Functions</h2></summary><dl class="tsd-member-summaries"><dt class="tsd-member-summary"><a id="portal" class="tsd-anchor"></a><span class="tsd-member-summary-name"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Function"><use href="assets/icons.svg#icon-64"></use></svg><a href="functions/portal.html">portal</a><a href="#portal" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></span></dt><dd class="tsd-member-summary"></dd></dl></details></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>On This Page</h3></summary><div class="tsd-accordion-details"><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Classes"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Classes</summary><div><a href="#portaldirective" class=""><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg><span>Portal<wbr/>Directive</span></a></div></details><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Interfaces"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Interfaces</summary><div><a href="#portaloptions" class=""><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Interface"><use href="assets/icons.svg#icon-256"></use></svg><span>Portal<wbr/>Options</span></a></div></details><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Type Aliases"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Type Aliases</summary><div><a href="#targetorselector" class=""><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Type Alias"><use href="assets/icons.svg#icon-2097152"></use></svg><span>Target<wbr/>Or<wbr/>Selector</span></a></div></details><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Functions"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Functions</summary><div><a href="#portal" class=""><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Function"><use href="assets/icons.svg#icon-64"></use></svg><span>portal</span></a></div></details></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html" class="current">Lit Modal Portal Documentation</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
2 | 


--------------------------------------------------------------------------------
/src/portal.test.ts:
--------------------------------------------------------------------------------
  1 | import { LitElement, html, PropertyValueMap } from 'lit';
  2 | import { ref, createRef, Ref } from 'lit/directives/ref.js';
  3 | import { when } from 'lit/directives/when.js';
  4 | import { customElement, state, property } from 'lit/decorators.js';
  5 | import { expect, fixture, nextFrame } from '@open-wc/testing';
  6 | import { portal, PortalOptions } from './portal';
  7 | import sinon, { spy } from 'sinon';
  8 | 
  9 | @customElement('example-component-manager')
 10 | export class ExampleComponentManager extends LitElement {
 11 |   @state()
 12 |   enablePortal = false;
 13 | 
 14 |   @property({ attribute: false })
 15 |   buttonRef: Ref<HTMLButtonElement>;
 16 | 
 17 |   @property({ attribute: false })
 18 |   exampleComponentRef: Ref<ExampleComponent>;
 19 | 
 20 |   render() {
 21 |     return html`
 22 |       <button
 23 |         ${ref(this.buttonRef)}
 24 |         @click=${() => (this.enablePortal = !this.enablePortal)}
 25 |       ></button>
 26 |       ${when(this.enablePortal, () =>
 27 |         portal(html`<example-component></example-component>`, document.body),
 28 |       )}
 29 |     `;
 30 |   }
 31 | }
 32 | 
 33 | @customElement('example-component')
 34 | export class ExampleComponent extends LitElement {
 35 |   // If there is a better way to test the lifecycle methods than through a side-effect spy,
 36 |   // then I would like to hear about it.
 37 |   static lifecycleSpy = spy();
 38 | 
 39 |   constructor() {
 40 |     super();
 41 |     ExampleComponent.lifecycleSpy('constructor');
 42 |   }
 43 | 
 44 |   connectedCallback(): void {
 45 |     super.connectedCallback();
 46 |     ExampleComponent.lifecycleSpy('connectedCallback');
 47 |   }
 48 | 
 49 |   protected willUpdate(
 50 |     _changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>,
 51 |   ): void {
 52 |     ExampleComponent.lifecycleSpy('willUpdate');
 53 |   }
 54 | 
 55 |   protected firstUpdated(
 56 |     _changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>,
 57 |   ): void {
 58 |     ExampleComponent.lifecycleSpy('firstUpdated');
 59 |   }
 60 | 
 61 |   protected updated(_changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>): void {
 62 |     ExampleComponent.lifecycleSpy('updated');
 63 |   }
 64 | 
 65 |   disconnectedCallback(): void {
 66 |     super.disconnectedCallback();
 67 |     ExampleComponent.lifecycleSpy('disconnectedCallback');
 68 |   }
 69 | 
 70 |   render() {
 71 |     return html`<p>${PORTAL_CONTENT}</p>`;
 72 |   }
 73 | }
 74 | 
 75 | const PORTAL_CONTENT = 'portal content';
 76 | const PORTAL_CONTAINER_ID_REGEX = /portal(-[0-9a-f])+/;
 77 | 
 78 | async function createPortalFixture(portalTarget: HTMLElement | string, options?: PortalOptions) {
 79 |   await fixture(html`${portal(html`<p>${PORTAL_CONTENT}</p>`, portalTarget, options)}`);
 80 | }
 81 | 
 82 | async function createPortalFixtureWithToggledComponent() {
 83 |   const buttonRef: Ref<HTMLButtonElement> = createRef();
 84 |   const exampleComponentRef: Ref<ExampleComponent> = createRef();
 85 |   const clickButtonAsync = async () => {
 86 |     buttonRef.value.click();
 87 |     await nextFrame();
 88 |   };
 89 | 
 90 |   await fixture(html`
 91 |     <example-component-manager
 92 |       .buttonRef=${buttonRef}
 93 |       .exampleComponentRef=${exampleComponentRef}
 94 |     ></example-component-manager>
 95 |   `);
 96 | 
 97 |   return { exampleComponentRef, clickButtonAsync };
 98 | }
 99 | 
100 | async function createAsynchronousPortalFixture(
101 |   portalTarget: HTMLElement | string,
102 |   delay = 1000,
103 |   placeholder?: unknown,
104 | ) {
105 |   const sleepPromise = new Promise((resolve) => setTimeout(resolve, delay));
106 |   await fixture(
107 |     html`${portal(
108 |       sleepPromise.then(() => html`<p>${PORTAL_CONTENT}</p>`),
109 |       portalTarget,
110 |       { placeholder },
111 |     )}`,
112 |   );
113 | }
114 | 
115 | describe('portal', async function () {
116 |   const getPortalsInDocumentBody = () => document.body.querySelectorAll('[id|=portal]');
117 | 
118 |   afterEach(function () {
119 |     getPortalsInDocumentBody().forEach((portal) => portal.remove());
120 |     sinon.restore();
121 |     ExampleComponent.lifecycleSpy.resetHistory();
122 |   });
123 | 
124 |   it('creates a portal in document.body', async function () {
125 |     await createPortalFixture(document.body);
126 | 
127 |     expect(document.body.lastElementChild).to.be.instanceof(HTMLDivElement);
128 |     expect(document.body.lastElementChild.id).match(PORTAL_CONTAINER_ID_REGEX);
129 |     expect((document.body.lastElementChild as HTMLDivElement).innerText).to.equal(PORTAL_CONTENT);
130 |   });
131 | 
132 |   it('creates a portal in a div using a query selector', async function () {
133 |     const portalTarget = document.createElement('div');
134 |     const portalTargetId = `portal-target`;
135 |     portalTarget.id = portalTargetId;
136 | 
137 |     document.body.appendChild(portalTarget);
138 |     await createPortalFixture('#portal-target');
139 | 
140 |     expect(portalTarget.lastElementChild).to.be.instanceof(HTMLDivElement);
141 |     expect(portalTarget.lastElementChild.id).match(PORTAL_CONTAINER_ID_REGEX);
142 |     expect((portalTarget.lastElementChild as HTMLDivElement).innerText).to.equal(PORTAL_CONTENT);
143 |   });
144 | 
145 |   it('modifies the portal container', async function () {
146 |     const portalTarget = document.createElement('div');
147 |     const portalTargetId = `portal-target`;
148 |     portalTarget.id = portalTargetId;
149 | 
150 |     const className = 'modified-classname';
151 |     document.body.appendChild(portalTarget);
152 |     await createPortalFixture('#portal-target', {
153 |       modifyContainer: (div) => div.classList.add(className),
154 |     });
155 | 
156 |     expect(portalTarget.lastElementChild).to.be.instanceof(HTMLDivElement);
157 |     expect(portalTarget.lastElementChild.id).match(PORTAL_CONTAINER_ID_REGEX);
158 |     expect(portalTarget.lastElementChild.classList.contains(className));
159 |   });
160 | 
161 |   describe('Lit lifecycle methods for components in portals', async function () {
162 |     let clickButtonAsync: Function;
163 | 
164 |     beforeEach(async function () {
165 |       ({ clickButtonAsync } = await createPortalFixtureWithToggledComponent());
166 |       expect(ExampleComponent.lifecycleSpy).to.have.not.been.called;
167 |     });
168 | 
169 |     it("calls a component's constructor method", async function () {
170 |       await clickButtonAsync();
171 |       expect(ExampleComponent.lifecycleSpy.getCall(0).calledWith('constructor'));
172 |       await clickButtonAsync();
173 |     });
174 | 
175 |     it("calls a component's connectedCallback method", async function () {
176 |       await clickButtonAsync();
177 |       expect(ExampleComponent.lifecycleSpy.getCall(1).calledWith('connectedCallback'));
178 |       await clickButtonAsync();
179 |     });
180 | 
181 |     it("calls a component's willUpdate method", async function () {
182 |       await clickButtonAsync();
183 |       expect(ExampleComponent.lifecycleSpy.getCall(2).calledWith('willUpdate'));
184 |       await clickButtonAsync();
185 |     });
186 | 
187 |     it("calls a component's firstUpdated method", async function () {
188 |       await clickButtonAsync();
189 |       expect(ExampleComponent.lifecycleSpy.getCall(3).calledWith('firstUpdated'));
190 |       await clickButtonAsync();
191 |     });
192 | 
193 |     it("calls a component's updated method", async function () {
194 |       await clickButtonAsync();
195 |       expect(ExampleComponent.lifecycleSpy.getCall(4).calledWith('updated'));
196 |       await clickButtonAsync();
197 |     });
198 | 
199 |     it("calls a component's disconnectedCallback method", async function () {
200 |       await clickButtonAsync();
201 |       await clickButtonAsync();
202 |       expect(ExampleComponent.lifecycleSpy).callCount(6);
203 |       expect(ExampleComponent.lifecycleSpy.getCall(5).calledWith('disconnectedCallback'));
204 |     });
205 |   });
206 | 
207 |   describe('Asynchronous behavior', async function () {
208 |     it("doesn't render a portal with asynchronous content until it resolves", async function () {
209 |       this.timeout(2000);
210 | 
211 |       await createAsynchronousPortalFixture(document.body, 1000);
212 |       expect(getPortalsInDocumentBody()).to.be.empty;
213 | 
214 |       await new Promise((resolve) => setTimeout(resolve, 1500));
215 |       expect(getPortalsInDocumentBody()).to.not.be.empty;
216 |     });
217 | 
218 |     it('renders a placeholder while asynchronous content resolves', async function () {
219 |       this.timeout(2000);
220 | 
221 |       await createAsynchronousPortalFixture(document.body, 1000, html`<p>placeholder</p>`);
222 |       const portals = getPortalsInDocumentBody();
223 |       expect(portals).to.not.be.empty;
224 |       expect((portals[0] as HTMLElement).innerText).to.equal('placeholder');
225 | 
226 |       await new Promise((resolve) => setTimeout(resolve, 1500));
227 |       expect((portals[0] as HTMLElement).innerText).to.equal(PORTAL_CONTENT);
228 |     });
229 |   });
230 | 
231 |   describe('test helpers', async function () {
232 |     describe('afterEach', function () {
233 |       it('expects no portals on document.body before adding a portal', async function () {
234 |         expect(getPortalsInDocumentBody()).to.be.empty;
235 |         await createPortalFixture(document.body);
236 |         expect(getPortalsInDocumentBody()).to.not.be.empty;
237 |       });
238 | 
239 |       it('expects (again) no portals on document.body before adding a portal', async function () {
240 |         expect(getPortalsInDocumentBody()).to.be.empty;
241 |         await createPortalFixture(document.body);
242 |         expect(getPortalsInDocumentBody()).to.not.be.empty;
243 |       });
244 |     });
245 | 
246 |     describe('createPortalFixtureWithToggledComponent', async function () {
247 |       it('creates and removes a portal with the returned values', async function () {
248 |         const { clickButtonAsync } = await createPortalFixtureWithToggledComponent();
249 | 
250 |         await clickButtonAsync();
251 |         expect(getPortalsInDocumentBody()).to.not.be.empty;
252 | 
253 |         await clickButtonAsync();
254 |         expect(getPortalsInDocumentBody()).to.be.empty;
255 |       });
256 |     });
257 |   });
258 | });
259 | 
260 | declare global {
261 |   interface HTMLElementTagNameMap {
262 |     'example-component-manager': ExampleComponentManager;
263 |     'example-component': ExampleComponent;
264 |   }
265 | }
266 | 


--------------------------------------------------------------------------------
/docs/interfaces/PortalOptions.html:
--------------------------------------------------------------------------------
1 | <!DOCTYPE html><html class="default" lang="en" data-base=".."><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>PortalOptions | Lit Modal Portal Documentation</title><meta name="description" content="Documentation for Lit Modal Portal Documentation"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search"><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="../index.html" class="title">Lit Modal Portal Documentation</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb"><li><a href="../modules.html">Lit Modal Portal Documentation</a></li><li><a href="PortalOptions.html">PortalOptions</a></li></ul><h1>Interface PortalOptions</h1></div><div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">PortalOptions</span> <span class="tsd-signature-symbol">{</span><br/>    <a class="tsd-kind-property" href="PortalOptions.html#modifycontainer">modifyContainer</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">container</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">HTMLElement</span><span class="tsd-signature-symbol">)</span> <span class="tsd-signature-symbol">=&gt;</span> <span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">;</span><br/>    <a class="tsd-kind-property" href="PortalOptions.html#placeholder">placeholder</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">;</span><br/><span class="tsd-signature-symbol">}</span></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/nicholas-wilcox/lit-modal-portal/blob/be82851f21b339aca2b221f9473e0791861e2360/src/portal.ts#L18">src/portal.ts:18</a></li></ul></aside><section class="tsd-panel-group tsd-index-group"><section class="tsd-panel tsd-index-panel"><details class="tsd-index-content tsd-accordion" open><summary class="tsd-accordion-summary tsd-index-summary"><h5 class="tsd-index-heading uppercase" role="button" aria-expanded="false" tabIndex="0"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronSmall"></use></svg> Index</h5></summary><div class="tsd-accordion-details"><section class="tsd-index-section"><h3 class="tsd-index-heading">Properties</h3><div class="tsd-index-list"><a href="PortalOptions.html#modifycontainer" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Property"><use href="../assets/icons.svg#icon-1024"></use></svg><span>modify<wbr/>Container?</span></a>
2 | <a href="PortalOptions.html#placeholder" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Property"><use href="../assets/icons.svg#icon-1024"></use></svg><span>placeholder?</span></a>
3 | </div></section></div></details></section></section><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Properties"><h2><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg> Properties</h2></summary><section><section class="tsd-panel tsd-member"><a id="modifycontainer" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><code class="tsd-tag">Optional</code><span>modify<wbr/>Container</span><a href="#modifycontainer" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">modifyContainer</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">container</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">HTMLElement</span><span class="tsd-signature-symbol">)</span> <span class="tsd-signature-symbol">=&gt;</span> <span class="tsd-signature-type">void</span></div><div class="tsd-comment tsd-typography"><p>When provided, the <code>modifyContainer</code> function will be called with
4 | the portal's container given as the argument. This allows you to programmatically control the
5 | container before the portal renders.</p>
6 | </div><div class="tsd-comment tsd-typography"></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/nicholas-wilcox/lit-modal-portal/blob/be82851f21b339aca2b221f9473e0791861e2360/src/portal.ts#L20">src/portal.ts:20</a></li></ul></aside></section><section class="tsd-panel tsd-member"><a id="placeholder" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><code class="tsd-tag">Optional</code><span>placeholder</span><a href="#placeholder" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">placeholder</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">unknown</span></div><div class="tsd-comment tsd-typography"><p>When provided, <code>placeholder</code> will be immediately rendered in the portal.
7 | Assuming that <code>content</code> is a promise, it will replace the placeholder once it resolves.</p>
8 | </div><div class="tsd-comment tsd-typography"></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/nicholas-wilcox/lit-modal-portal/blob/be82851f21b339aca2b221f9473e0791861e2360/src/portal.ts#L19">src/portal.ts:19</a></li></ul></aside></section></section></details></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>On This Page</h3></summary><div class="tsd-accordion-details"><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Properties"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Properties</summary><div><a href="#modifycontainer" class=""><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Property"><use href="../assets/icons.svg#icon-1024"></use></svg><span>modify<wbr/>Container</span></a><a href="#placeholder" class=""><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Property"><use href="../assets/icons.svg#icon-1024"></use></svg><span>placeholder</span></a></div></details></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">Lit Modal Portal Documentation</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
9 | 


--------------------------------------------------------------------------------
/docs/assets/icons.svg:
--------------------------------------------------------------------------------
1 | <svg xmlns="http://www.w3.org/2000/svg"><g id="icon-1" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-module)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">M</text></g><g id="icon-2" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-module)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">M</text></g><g id="icon-4" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-namespace)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">N</text></g><g id="icon-8" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-enum)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">E</text></g><g id="icon-16" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-property)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">P</text></g><g id="icon-32" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-variable)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">V</text></g><g id="icon-64" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-function)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">F</text></g><g id="icon-128" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-class)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">C</text></g><g id="icon-256" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-interface)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">I</text></g><g id="icon-512" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-constructor)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">C</text></g><g id="icon-1024" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-property)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">P</text></g><g id="icon-2048" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-method)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">M</text></g><g id="icon-4096" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-function)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">F</text></g><g id="icon-8192" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-property)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">P</text></g><g id="icon-16384" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-constructor)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">C</text></g><g id="icon-32768" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-property)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">P</text></g><g id="icon-65536" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-type-alias)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">T</text></g><g id="icon-131072" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-type-alias)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">T</text></g><g id="icon-262144" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-accessor)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">A</text></g><g id="icon-524288" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-accessor)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">A</text></g><g id="icon-1048576" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-accessor)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">A</text></g><g id="icon-2097152" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-type-alias)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">T</text></g><g id="icon-4194304" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-reference)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">R</text></g><g id="icon-8388608" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-document)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><g stroke="var(--color-icon-text)" fill="none" stroke-width="1.5"><polygon points="6,5 6,19 18,19, 18,10 13,5"></polygon><line x1="9" y1="9" x2="13" y2="9"></line><line x1="9" y1="12" x2="15" y2="12"></line><line x1="9" y1="15" x2="15" y2="15"></line></g></g><g id="icon-folder" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-document)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><g stroke="var(--color-icon-text)" fill="none" stroke-width="1.5"><polygon points="5,5 10,5 12,8 19,8 19,18 5,18"></polygon></g></g><g id="icon-chevronDown" class="tsd-no-select"><path d="M4.93896 8.531L12 15.591L19.061 8.531L16.939 6.409L12 11.349L7.06098 6.409L4.93896 8.531Z" fill="var(--color-icon-text)"></path></g><g id="icon-chevronSmall" class="tsd-no-select"><path d="M1.5 5.50969L8 11.6609L14.5 5.50969L12.5466 3.66086L8 7.96494L3.45341 3.66086L1.5 5.50969Z" fill="var(--color-icon-text)"></path></g><g id="icon-checkbox" class="tsd-no-select"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></g><g id="icon-menu" class="tsd-no-select"><rect x="1" y="3" width="14" height="2" fill="var(--color-icon-text)"></rect><rect x="1" y="7" width="14" height="2" fill="var(--color-icon-text)"></rect><rect x="1" y="11" width="14" height="2" fill="var(--color-icon-text)"></rect></g><g id="icon-search" class="tsd-no-select"><path d="M15.7824 13.833L12.6666 10.7177C12.5259 10.5771 12.3353 10.499 12.1353 10.499H11.6259C12.4884 9.39596 13.001 8.00859 13.001 6.49937C13.001 2.90909 10.0914 0 6.50048 0C2.90959 0 0 2.90909 0 6.49937C0 10.0896 2.90959 12.9987 6.50048 12.9987C8.00996 12.9987 9.39756 12.4863 10.5008 11.6239V12.1332C10.5008 12.3332 10.5789 12.5238 10.7195 12.6644L13.8354 15.7797C14.1292 16.0734 14.6042 16.0734 14.8948 15.7797L15.7793 14.8954C16.0731 14.6017 16.0731 14.1267 15.7824 13.833ZM6.50048 10.499C4.29094 10.499 2.50018 8.71165 2.50018 6.49937C2.50018 4.29021 4.28781 2.49976 6.50048 2.49976C8.71001 2.49976 10.5008 4.28708 10.5008 6.49937C10.5008 8.70852 8.71314 10.499 6.50048 10.499Z" fill="var(--color-icon-text)"></path></g><g id="icon-anchor" class="tsd-no-select"><g stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></g></g><g id="icon-alertNote" class="tsd-no-select"><path fill="var(--color-alert-note)" d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></g><g id="icon-alertTip" class="tsd-no-select"><path fill="var(--color-alert-tip)" d="M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z"></path></g><g id="icon-alertImportant" class="tsd-no-select"><path fill="var(--color-alert-important)" d="M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></g><g id="icon-alertWarning" class="tsd-no-select"><path fill="var(--color-alert-warning)" d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></g><g id="icon-alertCaution" class="tsd-no-select"><path fill="var(--color-alert-caution)" d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></g></svg>


--------------------------------------------------------------------------------
/docs/assets/icons.js:
--------------------------------------------------------------------------------
 1 | (function() {
 2 |     addIcons();
 3 |     function addIcons() {
 4 |         if (document.readyState === "loading") return document.addEventListener("DOMContentLoaded", addIcons);
 5 |         const svg = document.body.appendChild(document.createElementNS("http://www.w3.org/2000/svg", "svg"));
 6 |         svg.innerHTML = `<g id="icon-1" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-module)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">M</text></g><g id="icon-2" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-module)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">M</text></g><g id="icon-4" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-namespace)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">N</text></g><g id="icon-8" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-enum)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">E</text></g><g id="icon-16" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-property)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">P</text></g><g id="icon-32" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-variable)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">V</text></g><g id="icon-64" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-function)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">F</text></g><g id="icon-128" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-class)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">C</text></g><g id="icon-256" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-interface)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">I</text></g><g id="icon-512" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-constructor)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">C</text></g><g id="icon-1024" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-property)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">P</text></g><g id="icon-2048" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-method)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">M</text></g><g id="icon-4096" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-function)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">F</text></g><g id="icon-8192" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-property)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">P</text></g><g id="icon-16384" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-constructor)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">C</text></g><g id="icon-32768" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-property)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">P</text></g><g id="icon-65536" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-type-alias)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">T</text></g><g id="icon-131072" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-type-alias)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">T</text></g><g id="icon-262144" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-accessor)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">A</text></g><g id="icon-524288" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-accessor)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">A</text></g><g id="icon-1048576" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-accessor)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">A</text></g><g id="icon-2097152" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-type-alias)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">T</text></g><g id="icon-4194304" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-reference)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="12"></rect><text fill="var(--color-icon-text)" x="50%" y="50%" dominant-baseline="central" text-anchor="middle">R</text></g><g id="icon-8388608" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-document)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><g stroke="var(--color-icon-text)" fill="none" stroke-width="1.5"><polygon points="6,5 6,19 18,19, 18,10 13,5"></polygon><line x1="9" y1="9" x2="13" y2="9"></line><line x1="9" y1="12" x2="15" y2="12"></line><line x1="9" y1="15" x2="15" y2="15"></line></g></g><g id="icon-folder" class="tsd-no-select"><rect fill="var(--color-icon-background)" stroke="var(--color-document)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6"></rect><g stroke="var(--color-icon-text)" fill="none" stroke-width="1.5"><polygon points="5,5 10,5 12,8 19,8 19,18 5,18"></polygon></g></g><g id="icon-chevronDown" class="tsd-no-select"><path d="M4.93896 8.531L12 15.591L19.061 8.531L16.939 6.409L12 11.349L7.06098 6.409L4.93896 8.531Z" fill="var(--color-icon-text)"></path></g><g id="icon-chevronSmall" class="tsd-no-select"><path d="M1.5 5.50969L8 11.6609L14.5 5.50969L12.5466 3.66086L8 7.96494L3.45341 3.66086L1.5 5.50969Z" fill="var(--color-icon-text)"></path></g><g id="icon-checkbox" class="tsd-no-select"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></g><g id="icon-menu" class="tsd-no-select"><rect x="1" y="3" width="14" height="2" fill="var(--color-icon-text)"></rect><rect x="1" y="7" width="14" height="2" fill="var(--color-icon-text)"></rect><rect x="1" y="11" width="14" height="2" fill="var(--color-icon-text)"></rect></g><g id="icon-search" class="tsd-no-select"><path d="M15.7824 13.833L12.6666 10.7177C12.5259 10.5771 12.3353 10.499 12.1353 10.499H11.6259C12.4884 9.39596 13.001 8.00859 13.001 6.49937C13.001 2.90909 10.0914 0 6.50048 0C2.90959 0 0 2.90909 0 6.49937C0 10.0896 2.90959 12.9987 6.50048 12.9987C8.00996 12.9987 9.39756 12.4863 10.5008 11.6239V12.1332C10.5008 12.3332 10.5789 12.5238 10.7195 12.6644L13.8354 15.7797C14.1292 16.0734 14.6042 16.0734 14.8948 15.7797L15.7793 14.8954C16.0731 14.6017 16.0731 14.1267 15.7824 13.833ZM6.50048 10.499C4.29094 10.499 2.50018 8.71165 2.50018 6.49937C2.50018 4.29021 4.28781 2.49976 6.50048 2.49976C8.71001 2.49976 10.5008 4.28708 10.5008 6.49937C10.5008 8.70852 8.71314 10.499 6.50048 10.499Z" fill="var(--color-icon-text)"></path></g><g id="icon-anchor" class="tsd-no-select"><g stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></g></g><g id="icon-alertNote" class="tsd-no-select"><path fill="var(--color-alert-note)" d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></g><g id="icon-alertTip" class="tsd-no-select"><path fill="var(--color-alert-tip)" d="M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z"></path></g><g id="icon-alertImportant" class="tsd-no-select"><path fill="var(--color-alert-important)" d="M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></g><g id="icon-alertWarning" class="tsd-no-select"><path fill="var(--color-alert-warning)" d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></g><g id="icon-alertCaution" class="tsd-no-select"><path fill="var(--color-alert-caution)" d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></g>`;
 7 |         svg.style.display = "none";
 8 |         if (location.protocol === "file:") updateUseElements();
 9 |     }
10 | 
11 |     function updateUseElements() {
12 |         document.querySelectorAll("use").forEach(el => {
13 |             if (el.getAttribute("href").includes("#icon-")) {
14 |                 el.setAttribute("href", el.getAttribute("href").replace(/.*#/, "#"));
15 |             }
16 |         });
17 |     }
18 | })()


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # lit-modal-portal
  2 | 
  3 | The `lit-modal-portal` package provides a [custom Lit directive](https://lit.dev/docs/templates/custom-directives/), `portal`, that renders a Lit template elsewhere in the DOM.
  4 | Its main goals are:
  5 | 
  6 | 1. to provide an API that is similar to React's [`createPortal`](https://react.dev/reference/react-dom/createPortal) function, and
  7 | 2. to rely on the existing Lit API wherever possible.
  8 | 
  9 | This package also supports _asynchronous_ portal content.
 10 | 
 11 | ## :warning: Notice on version 0.6
 12 | 
 13 | This package was heavily altered between versions 0.4 and 0.6.
 14 | Changes include:
 15 | 
 16 | - Add support for Lit v3 and fixed dependency declaration for v0.5. (Thanks, [klasjersevi](https://github.com/klasjersevi).)
 17 | - Removed the following code:
 18 |   - Dependency of the [immutable](https://www.npmjs.com/package/immutable) package.
 19 |   - The `<modal-portal>` component and the singleton `modalController`.
 20 |   - All pre-made components, such as the `<confirm-modal>`.
 21 | - Refactor the `portal` directive to use Lit's `render` function.
 22 |   - This was primarily inspired by [ronak-lm](https://github.com/ronak-lm)'s [lit-portal](https://www.npmjs.com/package/lit-portal) package, which more closely resembles React's portal API than previous versions of this package.
 23 |   - This simplifies usage of the package and expands the potential use cases.
 24 | 
 25 | ## Installation and Usage
 26 | 
 27 | You can install `lit-modal-portal` via NPM.
 28 | 
 29 | ```
 30 | npm install lit-modal-portal
 31 | ```
 32 | 
 33 | Suppose we have the following Lit application:
 34 | 
 35 | ```html
 36 | <!-- index.html -->
 37 | <!doctype html>
 38 | <html>
 39 |   <head>
 40 |     <title>lit-modal-portal Usage Example</title>
 41 |     <!-- Your bundle/script -->
 42 |     <script type="module" src="main.js"></script>
 43 |   </head>
 44 |   <body>
 45 |     <!-- Your custom element -->
 46 |     <app-root></app-root>
 47 |   </body>
 48 | </html>
 49 | ```
 50 | 
 51 | ```js
 52 | // index.ts (source code for main.js)
 53 | import { LitElement, html } from 'lit';
 54 | import { customElement } from 'lit/decorators.js';
 55 | import { portal } from 'lit-modal-portal';
 56 | 
 57 | @customElement('app-root')
 58 | export class AppRoot extends LitElement {
 59 |   render() {
 60 |     return html`
 61 |       <h1>lit-modal-portal Usage Example</h1>
 62 |       ${portal(html`<p>portal content</p>`, document.body)}
 63 |     `;
 64 |   }
 65 | }
 66 | ```
 67 | 
 68 | When the `<app-root>` component renders, it will activate the `portal` directive, which will return `nothing` but use Lit's API to asynchronously render the content in a container `<div>` and append that container to `document.body`.
 69 | 
 70 | When the portal's content is updated, the directive will re-render the new content in the same container. Additionally, if the target changes, then the container will be removed from the old target and appended to the new target.
 71 | 
 72 | ## API
 73 | 
 74 | ```ts
 75 | type TargetOrSelector = Node | string;
 76 | 
 77 | type PortalOptions = {
 78 |   placeholder?: unknown;
 79 |   modifyContainer?: (container: HTMLElement) => void;
 80 | };
 81 | 
 82 | portal(
 83 |   content: unknown | Promise<unknown>,
 84 |   targetOrSelector: TargetOrSelector | Promise<TargetOrSelector>,
 85 |   options?: PortalOptions,
 86 | ): DirectiveResult<typeof PortalDirective>
 87 | ```
 88 | 
 89 | Parameters:
 90 | 
 91 | - `content`: The content of the portal. This parameter is passed as the `value` parameter in [Lit's `render` function](https://lit.dev/docs/api/templates/#render).
 92 | 
 93 |   > Any renderable value typically a [`TemplateResult`](https://lit.dev/docs/api/templates/#TemplateResult)
 94 |   > created by evaluating a template tag like [`html`](https://lit.dev/docs/api/templates/#html) or [`svg`](https://lit.dev/docs/api/templates/#svg).
 95 | 
 96 | - `targetOrSelector`: An element or a string that identifies the portal's target.
 97 | 
 98 |   If the value is a string, then it is treated as a query selector and passed to `document.querySelector()` in order to locate the portal target.
 99 |   If no element is found with the selector, then an error is thrown.
100 | 
101 | - `options`: Configuration parameters for the portal.
102 | 
103 |   - `placeholder`: A value that will be rendered while the `content` is resolving.
104 | 
105 |   - `modifyContainer`: A function that will be called with the portal's container provided as an argument.
106 |     This allows you to programmatically control the container before the portal renders.
107 | 
108 | This function will always return [Lit's `nothing` value](https://lit.dev/docs/api/templates/#nothing), because nothing is supposed to render where the portal is used.
109 | 
110 | Both the `content` and the `targetOrSelector` parameters may be promises.
111 | The `targetOrSelector` must resolve before the portal renders.
112 | 
113 | If the `content` is a promise, then an optional `placeholder` may be provided.
114 | If no `placeholder` is provided, then the portal will not render until the `content` resolves.
115 | 
116 | See [the docs](https://nicholas-wilcox.github.io/lit-modal-portal/classes/PortalDirective.html#render) for more information on how the `portal` directive works.
117 | 
118 | ## Advanced Usage
119 | 
120 | ### Modals and dialogs
121 | 
122 | This package no longer provides modal components. Instead, it focuses on a directive that is simple to use in different ways and encourages users to implement their own modals.
123 | 
124 | One recommended approach is to use the [`dialog`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog) element and its [`showModal`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal) method,
125 | which can be accessed using [Lit's `ref` directive](https://lit.dev/docs/templates/directives/#referencing-rendered-dom).
126 | 
127 | Consider the following:
128 | 
129 | ```ts
130 | // example-app.ts
131 | import { LitElement, html } from 'lit';
132 | import { customElement } from 'lit/decorators.js';
133 | import { ref, createRef } from 'lit/directives/ref.js';
134 | import { portal } from 'lit-modal-portal';
135 | 
136 | import './lit-dialog';
137 | 
138 | @customElement('example-app')
139 | export class ExampleApp extends LitElement {
140 |   dialogRef = createRef<HTMLDialogElement>();
141 | 
142 |   render() {
143 |     return html`
144 |       <h1>lit-modal-portal Dialog Example</h1>
145 |       <button @click=${() => this.dialogRef.value?.showModal()}>Show Dialog</button>
146 |       ${portal(html`<lit-dialog .dialogRef=${this.dialogRef}></lit-dialog>`, document.body)}
147 |     `;
148 |   }
149 | }
150 | ```
151 | 
152 | ```ts
153 | // lit-dialog.ts
154 | import { LitElement, html } from 'lit';
155 | import { customElement, property } from 'lit/decorators.js';
156 | import { ref, createRef, Ref } from 'lit/directives/ref.js';
157 | 
158 | @customElement('lit-dialog')
159 | export class LitDialog extends LitElement {
160 |   @property({ attribute: false })
161 |   dialogRef: Ref<HTMLDialogElement> = createRef();
162 | 
163 |   render() {
164 |     return html`
165 |       <dialog ${ref(this.dialogRef)}>
166 |         <p>This is the dialog</p>
167 |         <button @click=${() => this.dialogRef.value?.close()}>Close Dialog</button>
168 |       </dialog>
169 |     `;
170 |   }
171 | }
172 | ```
173 | 
174 | In this example, we have a `<lit-dialog>` component that accepts a `dialogRef` from the parent `<example-app>`.
175 | This allows the parent to open the dialog and the child to imperatively close it on a button's `@click` event.
176 | 
177 | This basic pattern can be extended as necessary. Examples include:
178 | 
179 | - Listening to the dialog's `close` event, which would trigger if the dialog was closed with the Escape key.
180 | - Adding styles to the `<lit-dialog>` component.
181 | - Adding callback function properties to `<lit-dialog>`.
182 | - Using slotted content in the dialog component's template.
183 | 
184 | ### Targeting elements in the Shadow DOM
185 | 
186 | Using a DOM node in a Lit component as a target for a portal is tricky (and perhaps useless or inadvisable), for a number of reasons:
187 | 
188 | 1. The `querySelector` method does not penetrate through the shadow root, so running queries on the `document` node won't return anything.
189 | 2. The `portal` directive is _asynchronous_, so if it renders at the same time as the component's first render, _then the target might not even exist yet_.
190 | 
191 | We cannot simply call `querySelector` on a different render root, such as a component's shadow root, because it might be empty. However, this is still possible to accomplish safely with the use of [Lit's `queryAsync` decorator](https://lit.dev/docs/api/decorators/#queryAsync).
192 | 
193 | ```ts
194 | import { LitElement, html } from 'lit';
195 | import { customElement, queryAsync } from 'lit/decorators.js';
196 | import { portal } from 'lit-modal-portal';
197 | 
198 | @customElement('example-component')
199 | export class ExampleComponent extends LitElement {
200 |   @queryAsync('#portal-target')
201 |   portalTarget: Promise<HTMLElement>;
202 | 
203 |   render() {
204 |     return html`<div>
205 |       ${portal(html`<p>Portal content</p>`, this.portalTarget)}
206 |       <p>The portal isn't rendered before this paragraph, but in the following div.</p>
207 |       <div id="portal-target"></div>
208 |     </div>`;
209 |   }
210 | }
211 | ```
212 | 
213 | In this example, `this.portalTarget` is a promise that resolves to the `<div id="portal-target>` element after the `<example-component>` renders.
214 | 
215 | See [Lit's documentation](https://lit.dev/docs/components/shadow-dom/) for more information on components and the Shadow DOM.
216 | 
217 | ### Styling portal content
218 | 
219 | Another consquence of the Shadow DOM is that only [inherited CSS properties](https://lit.dev/docs/components/styles/#inheritance) affect elements inside a shadow root. Coupled with the fact that a portal serves to render content in a different location, this makes it difficult for a component that uses the `portal` directive to style the portal's content.
220 | 
221 | **It is recommended that the content of a portal should be another Lit component that can own its CSS.** Alternatively, the [`styleMap` directive](https://lit.dev/docs/templates/directives/#stylemap) can be used in the template provided to the `portal` directive.
222 | 
223 | See [Lit's documentation](https://lit.dev/docs/components/styles/#shadow-dom) for more information on working with CSS styles and the Shadow DOM.
224 | 
225 | ### Modifying portal containers
226 | 
227 | A portal renders its content inside a container `<div>`. You can access and manipulate this element by supplying a `modifyContainer` function to the options for the `portal` directive. For example, the following code adds styles to the container:
228 | 
229 | ```ts
230 | portal(
231 |   html`<p>This is the portal content. Its container has a red border and some padding.</p>`,
232 |   document.body,
233 |   {
234 |     modifyContainer: (c) => {
235 |       c.style.border = '2px solid red';
236 |       c.style.padding = '0.5rem';
237 |     },
238 |   },
239 | );
240 | ```
241 | 
242 | Credit to [SimeonC](https://github.com/SimeonC) for suggesting this feature and even providing the code changes to make it possible.
243 | 
244 | ### Delegating portals
245 | 
246 | You may wish to create a reusable component that implements certain behaviors around portalling while letting a parent component define the content that is sent through the portal. For example, consider a child component that dynamically renders content either in-place or through a portal, based on reactive state.
247 | 
248 | There are many issues with using slotted content for this purpose. (See [this GitHub issue](https://github.com/nicholas-wilcox/lit-modal-portal/issues/6) for more context.) Instead, you should declare a property on the child component and pass a Lit template through the parent component. You may refer to [the example code](https://github.com/nicholas-wilcox/lit-modal-portal/blob/main/dev/demo-delegation.ts) in the `dev/` directory of this repository for an example.
249 | 
250 | ## Documentation
251 | 
252 | More in-depth documentation for this package is included in the repo, under the `/docs` directory.
253 | It is also [hosted on GitHub Pages](https://nicholas-wilcox.github.io/lit-modal-portal/index.html).
254 | 
255 | The documentation is generated using [TypeDoc](https://typedoc.org/).
256 | Please note the separate `docs.tsconfig.json` and `src/docs.index.ts` files if you plan to make changes related to the documentation.
257 | 
258 | ## Development
259 | 
260 | For demonstration and testing purposes, you can start a local development server by running `npm run dev`.
261 | There are multiple examples of the `portal` directive that explain its features and supported usage.
262 | 
263 | The default host is `localhost:8000`, and you may override the port number by setting the PORT environment variable.
264 | 
265 | The development server is [Modern Web's server](https://modern-web.dev/docs/dev-server/overview/),
266 | running in watch mode, so you can see code changes reloaded into the browser automatically.
267 | Note the middleware in `web-dev-server.config.mjs` that rewrites requests for the root so that `dev/index.html` is served.
268 | 
269 | ### Testing
270 | 
271 | There are some tests for the `portal` directive in `src/portal.test.ts`. They use [Modern Web's test runner](https://modern-web.dev/guides/test-runner/getting-started/) and the [Open Web Components `@open-wc/testing`](https://open-wc.org/guides/developing-components/testing/) framework.
272 | 
273 | You can execute the tests by running `npm run test`.
274 | 
275 | ## Contributing and Bug Reports
276 | 
277 | Currently, there is no standard procedure for contributing to this project.
278 | You are absolutely welcome to fork the repository and make a pull request,
279 | and to file issues if you encounter problems while using it.
280 | 


--------------------------------------------------------------------------------
/docs/classes/PortalDirective.html:
--------------------------------------------------------------------------------
 1 | <!DOCTYPE html><html class="default" lang="en" data-base=".."><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>PortalDirective | Lit Modal Portal Documentation</title><meta name="description" content="Documentation for Lit Modal Portal Documentation"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search"><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="../index.html" class="title">Lit Modal Portal Documentation</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb"><li><a href="../modules.html">Lit Modal Portal Documentation</a></li><li><a href="PortalDirective.html">PortalDirective</a></li></ul><h1>Class PortalDirective</h1></div><section class="tsd-panel tsd-comment"><div class="tsd-comment tsd-typography"><p>A directive to render a Lit template somewhere in the DOM.</p>
 2 | <p>See <a href="https://lit.dev/docs/templates/custom-directives/">Lit docs on Custom Directives</a>.</p>
 3 | </div><div class="tsd-comment tsd-typography"></div></section><section class="tsd-panel tsd-hierarchy" data-refl="11"><h4>Hierarchy</h4><ul class="tsd-hierarchy"><li class="tsd-hierarchy-item"><span class="tsd-signature-type">AsyncDirective</span><ul class="tsd-hierarchy"><li class="tsd-hierarchy-item"><span class="tsd-hierarchy-target">PortalDirective</span></li></ul></li></ul></section><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/nicholas-wilcox/lit-modal-portal/blob/be82851f21b339aca2b221f9473e0791861e2360/src/portal.ts#L44">src/portal.ts:44</a></li></ul></aside><section class="tsd-panel-group tsd-index-group"><section class="tsd-panel tsd-index-panel"><details class="tsd-index-content tsd-accordion" open><summary class="tsd-accordion-summary tsd-index-summary"><h5 class="tsd-index-heading uppercase" role="button" aria-expanded="false" tabIndex="0"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronSmall"></use></svg> Index</h5></summary><div class="tsd-accordion-details"><section class="tsd-index-section"><h3 class="tsd-index-heading">Constructors</h3><div class="tsd-index-list"><a href="PortalDirective.html#constructor" class="tsd-index-link tsd-is-external"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Constructor"><use href="../assets/icons.svg#icon-512"></use></svg><span>constructor</span></a>
 4 | </div></section><section class="tsd-index-section"><h3 class="tsd-index-heading">Properties</h3><div class="tsd-index-list"><a href="PortalDirective.html#isconnected" class="tsd-index-link tsd-is-inherited tsd-is-external"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Property"><use href="../assets/icons.svg#icon-1024"></use></svg><span>is<wbr/>Connected</span></a>
 5 | </div></section><section class="tsd-index-section"><h3 class="tsd-index-heading">Accessors</h3><div class="tsd-index-list"><a href="PortalDirective.html#_isconnected" class="tsd-index-link tsd-is-inherited tsd-is-external"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Accessor"><use href="../assets/icons.svg#icon-262144"></use></svg><span>_$is<wbr/>Connected</span></a>
 6 | </div></section><section class="tsd-index-section"><h3 class="tsd-index-heading">Methods</h3><div class="tsd-index-list"><a href="PortalDirective.html#_initialize" class="tsd-index-link tsd-is-inherited tsd-is-external"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>_$initialize</span></a>
 7 | <a href="PortalDirective.html#disconnected" class="tsd-index-link tsd-is-protected"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>disconnected</span></a>
 8 | <a href="PortalDirective.html#reconnected" class="tsd-index-link tsd-is-protected"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>reconnected</span></a>
 9 | <a href="PortalDirective.html#render" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>render</span></a>
10 | <a href="PortalDirective.html#setvalue" class="tsd-index-link tsd-is-inherited tsd-is-external"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>set<wbr/>Value</span></a>
11 | <a href="PortalDirective.html#update" class="tsd-index-link tsd-is-inherited tsd-is-external"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>update</span></a>
12 | </div></section></div></details></section></section><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Constructors"><h2><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg> Constructors</h2></summary><section><section class="tsd-panel tsd-member tsd-is-external"><a id="constructor" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span>constructor</span><a href="#constructor" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures tsd-is-external"><li class="tsd-is-external"><div class="tsd-signature tsd-anchor-link"><a id="constructorportaldirective" class="tsd-anchor"></a><span class="tsd-signature-keyword">new</span> <span class="tsd-kind-constructor-signature">PortalDirective</span><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">_partInfo</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">PartInfo</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <a href="PortalDirective.html" class="tsd-signature-type tsd-kind-class">PortalDirective</a><a href="#constructorportaldirective" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-parameters"><h4 class="tsd-parameters-title">Parameters</h4><ul class="tsd-parameter-list"><li><span><span class="tsd-kind-parameter">_partInfo</span>: <span class="tsd-signature-type">PartInfo</span></span></li></ul></div><h4 class="tsd-returns-title">Returns <a href="PortalDirective.html" class="tsd-signature-type tsd-kind-class">PortalDirective</a></h4><aside class="tsd-sources"><p>Inherited from AsyncDirective.constructor</p><ul><li>Defined in node_modules/lit-html/directive.d.ts:61</li></ul></aside></div></li></ul></section></section></details><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Properties"><h2><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg> Properties</h2></summary><section><section class="tsd-panel tsd-member tsd-is-inherited tsd-is-external"><a id="isconnected" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span>is<wbr/>Connected</span><a href="#isconnected" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">isConnected</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">boolean</span></div><div class="tsd-comment tsd-typography"><p>The connection state for this Directive.</p>
13 | </div><div class="tsd-comment tsd-typography"></div><aside class="tsd-sources"><p>Inherited from AsyncDirective.isConnected</p><ul><li>Defined in node_modules/lit-html/async-directive.d.ts:143</li></ul></aside></section></section></details><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Accessors"><h2><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg> Accessors</h2></summary><section><section class="tsd-panel tsd-member tsd-is-inherited tsd-is-external"><a id="_isconnected" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span>_$is<wbr/>Connected</span><a href="#_isconnected" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures tsd-is-inherited tsd-is-external"><li class="tsd-is-inherited tsd-is-external"><div class="tsd-signature" id="_isconnected-1"><span class="tsd-signature-keyword">get</span> <span class="tsd-kind-get-signature">_$isConnected</span><span class="tsd-signature-symbol">()</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">boolean</span></div><div class="tsd-description"><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">boolean</span></h4><aside class="tsd-sources"><p>Inherited from AsyncDirective._$isConnected</p><ul><li>Defined in node_modules/lit-html/directive.d.ts:62</li></ul></aside></div></li></ul></section></section></details><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Methods"><h2><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg> Methods</h2></summary><section><section class="tsd-panel tsd-member tsd-is-inherited tsd-is-external"><a id="_initialize" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span>_$initialize</span><a href="#_initialize" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures tsd-is-inherited tsd-is-external"><li class="tsd-is-inherited tsd-is-external"><div class="tsd-signature tsd-anchor-link"><a id="_initialize-1" class="tsd-anchor"></a><span class="tsd-kind-call-signature">_$initialize</span><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">part</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Part</span><span class="tsd-signature-symbol">,</span> <span class="tsd-kind-parameter">parent</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Disconnectable</span><span class="tsd-signature-symbol">,</span> <span class="tsd-kind-parameter">attributeIndex</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">number</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">void</span><a href="#_initialize-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-comment tsd-typography"><p>Initialize the part with internal fields</p>
14 | </div><div class="tsd-parameters"><h4 class="tsd-parameters-title">Parameters</h4><ul class="tsd-parameter-list"><li><span><span class="tsd-kind-parameter">part</span>: <span class="tsd-signature-type">Part</span></span><div class="tsd-comment tsd-typography"></div></li><li><span><span class="tsd-kind-parameter">parent</span>: <span class="tsd-signature-type">Disconnectable</span></span><div class="tsd-comment tsd-typography"></div></li><li><span><span class="tsd-kind-parameter">attributeIndex</span>: <span class="tsd-signature-type">number</span></span><div class="tsd-comment tsd-typography"></div></li></ul></div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4><div class="tsd-comment tsd-typography"></div><aside class="tsd-sources"><p>Inherited from AsyncDirective._$initialize</p><ul><li>Defined in node_modules/lit-html/async-directive.d.ts:150</li></ul></aside></div></li></ul></section><section class="tsd-panel tsd-member tsd-is-protected"><a id="disconnected" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><code class="tsd-tag">Protected</code><span>disconnected</span><a href="#disconnected" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures tsd-is-protected"><li class=""><div class="tsd-signature tsd-anchor-link"><a id="disconnected-1" class="tsd-anchor"></a><span class="tsd-kind-call-signature">disconnected</span><span class="tsd-signature-symbol">()</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">void</span><a href="#disconnected-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-comment tsd-typography"><p>Remove container from target when the directive is disconnected.</p>
15 | </div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4><div class="tsd-comment tsd-typography"></div><aside class="tsd-sources"><p>Overrides AsyncDirective.disconnected</p><ul><li>Defined in <a href="https://github.com/nicholas-wilcox/lit-modal-portal/blob/be82851f21b339aca2b221f9473e0791861e2360/src/portal.ts#L152">src/portal.ts:152</a></li></ul></aside></div></li></ul></section><section class="tsd-panel tsd-member tsd-is-protected"><a id="reconnected" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><code class="tsd-tag">Protected</code><span>reconnected</span><a href="#reconnected" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures tsd-is-protected"><li class=""><div class="tsd-signature tsd-anchor-link"><a id="reconnected-1" class="tsd-anchor"></a><span class="tsd-kind-call-signature">reconnected</span><span class="tsd-signature-symbol">()</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">void</span><a href="#reconnected-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-comment tsd-typography"><p>Append container to target when the directive is reconnected.</p>
16 | </div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4><div class="tsd-comment tsd-typography"></div><aside class="tsd-sources"><p>Overrides AsyncDirective.reconnected</p><ul><li>Defined in <a href="https://github.com/nicholas-wilcox/lit-modal-portal/blob/be82851f21b339aca2b221f9473e0791861e2360/src/portal.ts#L163">src/portal.ts:163</a></li></ul></aside></div></li></ul></section><section class="tsd-panel tsd-member"><a id="render" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span>render</span><a href="#render" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures"><li class=""><div class="tsd-signature tsd-anchor-link"><a id="render-1" class="tsd-anchor"></a><span class="tsd-kind-call-signature">render</span><span class="tsd-signature-symbol">(</span><br/>    <span class="tsd-kind-parameter">content</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">,</span><br/>    <span class="tsd-kind-parameter">targetOrSelector</span><span class="tsd-signature-symbol">:</span> <a href="../types/TargetOrSelector.html" class="tsd-signature-type tsd-kind-type-alias">TargetOrSelector</a> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><a href="../types/TargetOrSelector.html" class="tsd-signature-type tsd-kind-type-alias">TargetOrSelector</a><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol">,</span><br/>    <span class="tsd-kind-parameter">options</span><span class="tsd-signature-symbol">?:</span> <a href="../interfaces/PortalOptions.html" class="tsd-signature-type tsd-kind-interface">PortalOptions</a><span class="tsd-signature-symbol">,</span><br/><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">symbol</span><a href="#render-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-comment tsd-typography"><p>Main render function for the directive.</p>
17 | <p>For clarity's sake, here is the outline of the function body::</p>
18 | <ul>
19 | <li>
20 | <p>Resolve <code>targetOrSelector</code> to an element.</p>
21 | </li>
22 | <li>
23 | <p>If the directive's <code>container</code> property is <code>undefined</code>,</p>
24 | <ul>
25 | <li>then create the container element and store it in the property.</li>
26 | </ul>
27 | </li>
28 | <li>
29 | <p>If <code>modifyContainer</code> is provided in the <code>options</code>,</p>
30 | <ul>
31 | <li>then call <code>modifyContainer(container)</code>.</li>
32 | </ul>
33 | </li>
34 | <li>
35 | <p>If the target has changed from one element to another,</p>
36 | <ul>
37 | <li>then migrate <code>container</code> to the new target and reassign the directive's <code>target</code> property.</li>
38 | </ul>
39 | </li>
40 | <li>
41 | <p>If the directive's <code>target</code> property is <code>undefined</code>,</p>
42 | <ul>
43 | <li>
44 | <p>then store the target element in the property.</p>
45 | </li>
46 | <li>
47 | <p>If a <code>placeholder</code> is provided in the <code>options</code>,</p>
48 | <ul>
49 | <li>then append <code>container</code> to <code>target</code> (if necessary) and render <code>placeholder</code> in <code>container</code>.</li>
50 | </ul>
51 | </li>
52 | </ul>
53 | </li>
54 | <li>
55 | <p>Resolve <code>content</code> (awaited).</p>
56 | </li>
57 | <li>
58 | <p>Append <code>container</code> to <code>target</code> (if necessary) and render <code>content</code> in <code>container</code>.</p>
59 | </li>
60 | </ul>
61 | <p>The steps are organized this way to balance the initalization and refreshing of crucial properties
62 | like <code>container</code> and <code>target</code> while ensuring that <code>container</code> isn't added to the DOM until
63 | the directive is about to render something (either <code>placeholder</code> or <code>content</code>).</p>
64 | </div><div class="tsd-parameters"><h4 class="tsd-parameters-title">Parameters</h4><ul class="tsd-parameter-list"><li><span><span class="tsd-kind-parameter">content</span>: <span class="tsd-signature-type">unknown</span></span><div class="tsd-comment tsd-typography"><p>The content of the portal.
65 | This parameter is passed as the <code>value</code> parameter in <a href="https://lit.dev/docs/api/templates/#render">Lit's <code>render</code> function</a>.</p>
66 | <p>The <code>content</code> parameter can be a promise, which will be rendered in the portal once it resolves.</p>
67 | </div><div class="tsd-comment tsd-typography"></div></li><li><span><span class="tsd-kind-parameter">targetOrSelector</span>: <a href="../types/TargetOrSelector.html" class="tsd-signature-type tsd-kind-type-alias">TargetOrSelector</a> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><a href="../types/TargetOrSelector.html" class="tsd-signature-type tsd-kind-type-alias">TargetOrSelector</a><span class="tsd-signature-symbol">&gt;</span></span><div class="tsd-comment tsd-typography"><p>The &quot;target&quot; for the portal.
68 | If the value is a string, then it is treated as a query selector and passed to <code>document.querySelector()</code> in order to locate the portal target.
69 | If no element is found with the selector, then an error is thrown.</p>
70 | </div><div class="tsd-comment tsd-typography"></div></li><li><span><code class="tsd-tag">Optional</code><span class="tsd-kind-parameter">options</span>: <a href="../interfaces/PortalOptions.html" class="tsd-signature-type tsd-kind-interface">PortalOptions</a></span><div class="tsd-comment tsd-typography"><p>See <a href="../interfaces/PortalOptions.html" class="tsd-kind-interface">PortalOptions</a>.</p>
71 | </div><div class="tsd-comment tsd-typography"></div></li></ul></div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">symbol</span></h4><p>This function always returns Lit's <a href="https://lit.dev/docs/api/templates/#nothing"><code>nothing</code></a> value,
72 | because nothing ever renders where the portal is used.</p>
73 | <div class="tsd-comment tsd-typography"></div><aside class="tsd-sources"><p>Overrides AsyncDirective.render</p><ul><li>Defined in <a href="https://github.com/nicholas-wilcox/lit-modal-portal/blob/be82851f21b339aca2b221f9473e0791861e2360/src/portal.ts#L93">src/portal.ts:93</a></li></ul></aside></div></li></ul></section><section class="tsd-panel tsd-member tsd-is-inherited tsd-is-external"><a id="setvalue" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span>set<wbr/>Value</span><a href="#setvalue" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures tsd-is-inherited tsd-is-external"><li class="tsd-is-inherited tsd-is-external"><div class="tsd-signature tsd-anchor-link"><a id="setvalue-1" class="tsd-anchor"></a><span class="tsd-kind-call-signature">setValue</span><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">value</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">void</span><a href="#setvalue-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-comment tsd-typography"><p>Sets the value of the directive's Part outside the normal <code>update</code>/<code>render</code>
74 | lifecycle of a directive.</p>
75 | <p>This method should not be called synchronously from a directive's <code>update</code>
76 | or <code>render</code>.</p>
77 | </div><div class="tsd-parameters"><h4 class="tsd-parameters-title">Parameters</h4><ul class="tsd-parameter-list"><li><span><span class="tsd-kind-parameter">value</span>: <span class="tsd-signature-type">unknown</span></span><div class="tsd-comment tsd-typography"><p>The value to set</p>
78 | </div><div class="tsd-comment tsd-typography"></div></li></ul></div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4><div class="tsd-comment tsd-typography"></div><aside class="tsd-sources"><p>Inherited from AsyncDirective.setValue</p><ul><li>Defined in node_modules/lit-html/async-directive.d.ts:161</li></ul></aside></div></li></ul></section><section class="tsd-panel tsd-member tsd-is-inherited tsd-is-external"><a id="update" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span>update</span><a href="#update" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures tsd-is-inherited tsd-is-external"><li class="tsd-is-inherited tsd-is-external"><div class="tsd-signature tsd-anchor-link"><a id="update-1" class="tsd-anchor"></a><span class="tsd-kind-call-signature">update</span><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">_part</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Part</span><span class="tsd-signature-symbol">,</span> <span class="tsd-kind-parameter">props</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">[]</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">unknown</span><a href="#update-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-parameters"><h4 class="tsd-parameters-title">Parameters</h4><ul class="tsd-parameter-list"><li><span><span class="tsd-kind-parameter">_part</span>: <span class="tsd-signature-type">Part</span></span></li><li><span><span class="tsd-kind-parameter">props</span>: <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">[]</span></span></li></ul></div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">unknown</span></h4><aside class="tsd-sources"><p>Inherited from AsyncDirective.update</p><ul><li>Defined in node_modules/lit-html/directive.d.ts:64</li></ul></aside></div></li></ul></section></section></details></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>On This Page</h3></summary><div class="tsd-accordion-details"><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Constructors"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Constructors</summary><div><a href="#constructor" class="tsd-is-external"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Constructor"><use href="../assets/icons.svg#icon-512"></use></svg><span>constructor</span></a></div></details><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Properties"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Properties</summary><div><a href="#isconnected" class="tsd-is-inherited tsd-is-external"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Property"><use href="../assets/icons.svg#icon-1024"></use></svg><span>is<wbr/>Connected</span></a></div></details><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Accessors"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Accessors</summary><div><a href="#_isconnected" class="tsd-is-inherited tsd-is-external"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Accessor"><use href="../assets/icons.svg#icon-262144"></use></svg><span>_$is<wbr/>Connected</span></a></div></details><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Methods"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Methods</summary><div><a href="#_initialize" class="tsd-is-inherited tsd-is-external"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>_$initialize</span></a><a href="#disconnected" class="tsd-is-protected"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>disconnected</span></a><a href="#reconnected" class="tsd-is-protected"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>reconnected</span></a><a href="#render" class=""><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>render</span></a><a href="#setvalue" class="tsd-is-inherited tsd-is-external"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>set<wbr/>Value</span></a><a href="#update" class="tsd-is-inherited tsd-is-external"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>update</span></a></div></details></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">Lit Modal Portal Documentation</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
79 | 


--------------------------------------------------------------------------------
/docs/index.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html><html class="default" lang="en" data-base="."><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>Lit Modal Portal Documentation</title><meta name="description" content="Documentation for Lit Modal Portal Documentation"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search"><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">Lit Modal Portal Documentation</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>Lit Modal Portal Documentation</h1></div><div class="tsd-panel tsd-typography"><a id="lit-modal-portal" class="tsd-anchor"></a><h1 class="tsd-anchor-link">lit-modal-portal<a href="#lit-modal-portal" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1><p>The <code>lit-modal-portal</code> package provides a <a href="https://lit.dev/docs/templates/custom-directives/">custom Lit directive</a>, <code>portal</code>, that renders a Lit template elsewhere in the DOM.
  2 | Its main goals are:</p>
  3 | <ol>
  4 | <li>to provide an API that is similar to React's <a href="https://react.dev/reference/react-dom/createPortal"><code>createPortal</code></a> function, and</li>
  5 | <li>to rely on the existing Lit API wherever possible.</li>
  6 | </ol>
  7 | <p>This package also supports <em>asynchronous</em> portal content.</p>
  8 | <a id="warning-notice-on-version-06" class="tsd-anchor"></a><h2 class="tsd-anchor-link">:warning: Notice on version 0.6<a href="#warning-notice-on-version-06" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>This package was heavily altered between versions 0.4 and 0.6.
  9 | Changes include:</p>
 10 | <ul>
 11 | <li>Add support for Lit v3 and fixed dependency declaration for v0.5. (Thanks, <a href="https://github.com/klasjersevi">klasjersevi</a>.)</li>
 12 | <li>Removed the following code:
 13 | <ul>
 14 | <li>Dependency of the <a href="https://www.npmjs.com/package/immutable">immutable</a> package.</li>
 15 | <li>The <code>&lt;modal-portal&gt;</code> component and the singleton <code>modalController</code>.</li>
 16 | <li>All pre-made components, such as the <code>&lt;confirm-modal&gt;</code>.</li>
 17 | </ul>
 18 | </li>
 19 | <li>Refactor the <code>portal</code> directive to use Lit's <code>render</code> function.
 20 | <ul>
 21 | <li>This was primarily inspired by <a href="https://github.com/ronak-lm">ronak-lm</a>'s <a href="https://www.npmjs.com/package/lit-portal">lit-portal</a> package, which more closely resembles React's portal API than previous versions of this package.</li>
 22 | <li>This simplifies usage of the package and expands the potential use cases.</li>
 23 | </ul>
 24 | </li>
 25 | </ul>
 26 | <a id="installation-and-usage" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Installation and Usage<a href="#installation-and-usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>You can install <code>lit-modal-portal</code> via NPM.</p>
 27 | <pre><code><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-0">install</span><span class="hl-1"> </span><span class="hl-0">lit</span><span class="hl-1">-</span><span class="hl-0">modal</span><span class="hl-1">-</span><span class="hl-0">portal</span>
 28 | </code><button>Copy</button></pre>
 29 | 
 30 | <p>Suppose we have the following Lit application:</p>
 31 | <pre><code class="html"><span class="hl-2">&lt;!-- index.html --&gt;</span><br/><span class="hl-3">&lt;!</span><span class="hl-4">doctype</span><span class="hl-1"> </span><span class="hl-5">html</span><span class="hl-3">&gt;</span><br/><span class="hl-3">&lt;</span><span class="hl-4">html</span><span class="hl-3">&gt;</span><br/><span class="hl-1">  </span><span class="hl-3">&lt;</span><span class="hl-4">head</span><span class="hl-3">&gt;</span><br/><span class="hl-1">    </span><span class="hl-3">&lt;</span><span class="hl-4">title</span><span class="hl-3">&gt;</span><span class="hl-1">lit-modal-portal Usage Example</span><span class="hl-3">&lt;/</span><span class="hl-4">title</span><span class="hl-3">&gt;</span><br/><span class="hl-1">    </span><span class="hl-2">&lt;!-- Your bundle/script --&gt;</span><br/><span class="hl-1">    </span><span class="hl-3">&lt;</span><span class="hl-4">script</span><span class="hl-6"> </span><span class="hl-5">type</span><span class="hl-6">=</span><span class="hl-7">&quot;module&quot;</span><span class="hl-6"> </span><span class="hl-5">src</span><span class="hl-6">=</span><span class="hl-7">&quot;main.js&quot;</span><span class="hl-3">&gt;&lt;/</span><span class="hl-4">script</span><span class="hl-3">&gt;</span><br/><span class="hl-1">  </span><span class="hl-3">&lt;/</span><span class="hl-4">head</span><span class="hl-3">&gt;</span><br/><span class="hl-1">  </span><span class="hl-3">&lt;</span><span class="hl-4">body</span><span class="hl-3">&gt;</span><br/><span class="hl-1">    </span><span class="hl-2">&lt;!-- Your custom element --&gt;</span><br/><span class="hl-1">    </span><span class="hl-3">&lt;</span><span class="hl-4">app-root</span><span class="hl-3">&gt;&lt;/</span><span class="hl-4">app-root</span><span class="hl-3">&gt;</span><br/><span class="hl-1">  </span><span class="hl-3">&lt;/</span><span class="hl-4">body</span><span class="hl-3">&gt;</span><br/><span class="hl-3">&lt;/</span><span class="hl-4">html</span><span class="hl-3">&gt;</span>
 32 | </code><button type="button">Copy</button></pre>
 33 | 
 34 | <pre><code class="js"><span class="hl-2">// index.ts (source code for main.js)</span><br/><span class="hl-8">import</span><span class="hl-1"> { </span><span class="hl-0">LitElement</span><span class="hl-1">, </span><span class="hl-0">html</span><span class="hl-1"> } </span><span class="hl-8">from</span><span class="hl-1"> </span><span class="hl-9">&#39;lit&#39;</span><span class="hl-1">;</span><br/><span class="hl-8">import</span><span class="hl-1"> { </span><span class="hl-0">customElement</span><span class="hl-1"> } </span><span class="hl-8">from</span><span class="hl-1"> </span><span class="hl-9">&#39;lit/decorators.js&#39;</span><span class="hl-1">;</span><br/><span class="hl-8">import</span><span class="hl-1"> { </span><span class="hl-0">portal</span><span class="hl-1"> } </span><span class="hl-8">from</span><span class="hl-1"> </span><span class="hl-9">&#39;lit-modal-portal&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-1">@</span><span class="hl-10">customElement</span><span class="hl-1">(</span><span class="hl-9">&#39;app-root&#39;</span><span class="hl-1">)</span><br/><span class="hl-8">export</span><span class="hl-1"> </span><span class="hl-11">class</span><span class="hl-1"> </span><span class="hl-12">AppRoot</span><span class="hl-1"> </span><span class="hl-11">extends</span><span class="hl-1"> </span><span class="hl-12">LitElement</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-10">render</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-8">return</span><span class="hl-1"> </span><span class="hl-10">html</span><span class="hl-9">`</span><br/><span class="hl-9">      &lt;h1&gt;lit-modal-portal Usage Example&lt;/h1&gt;</span><br/><span class="hl-9">      </span><span class="hl-11">${</span><span class="hl-10">portal</span><span class="hl-6">(</span><span class="hl-10">html</span><span class="hl-9">`&lt;p&gt;portal content&lt;/p&gt;`</span><span class="hl-6">, </span><span class="hl-0">document</span><span class="hl-6">.</span><span class="hl-0">body</span><span class="hl-6">)</span><span class="hl-11">}</span><br/><span class="hl-9">    `</span><span class="hl-1">;</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 35 | </code><button type="button">Copy</button></pre>
 36 | 
 37 | <p>When the <code>&lt;app-root&gt;</code> component renders, it will activate the <code>portal</code> directive, which will return <code>nothing</code> but use Lit's API to asynchronously render the content in a container <code>&lt;div&gt;</code> and append that container to <code>document.body</code>.</p>
 38 | <p>When the portal's content is updated, the directive will re-render the new content in the same container. Additionally, if the target changes, then the container will be removed from the old target and appended to the new target.</p>
 39 | <a id="api" class="tsd-anchor"></a><h2 class="tsd-anchor-link">API<a href="#api" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><pre><code class="ts"><span class="hl-11">type</span><span class="hl-1"> </span><span class="hl-12">TargetOrSelector</span><span class="hl-1"> = </span><span class="hl-12">Node</span><span class="hl-1"> | </span><span class="hl-12">string</span><span class="hl-1">;</span><br/><br/><span class="hl-11">type</span><span class="hl-1"> </span><span class="hl-12">PortalOptions</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-0">placeholder</span><span class="hl-1">?: </span><span class="hl-12">unknown</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-10">modifyContainer</span><span class="hl-1">?: (</span><span class="hl-0">container</span><span class="hl-1">: </span><span class="hl-12">HTMLElement</span><span class="hl-1">) </span><span class="hl-11">=&gt;</span><span class="hl-1"> </span><span class="hl-12">void</span><span class="hl-1">;</span><br/><span class="hl-1">};</span><br/><br/><span class="hl-10">portal</span><span class="hl-1">(</span><br/><span class="hl-1">  </span><span class="hl-0">content</span><span class="hl-1">: </span><span class="hl-0">unknown</span><span class="hl-1"> | </span><span class="hl-12">Promise</span><span class="hl-1">&lt;</span><span class="hl-0">unknown</span><span class="hl-1">&gt;,</span><br/><span class="hl-1">  </span><span class="hl-0">targetOrSelector</span><span class="hl-1">: </span><span class="hl-0">TargetOrSelector</span><span class="hl-1"> | </span><span class="hl-12">Promise</span><span class="hl-1">&lt;</span><span class="hl-0">TargetOrSelector</span><span class="hl-1">&gt;,</span><br/><span class="hl-1">  </span><span class="hl-0">options</span><span class="hl-1">?: </span><span class="hl-0">PortalOptions</span><span class="hl-1">,</span><br/><span class="hl-1">): </span><span class="hl-0">DirectiveResult</span><span class="hl-1">&lt;</span><span class="hl-11">typeof</span><span class="hl-1"> </span><span class="hl-0">PortalDirective</span><span class="hl-1">&gt;</span>
 40 | </code><button type="button">Copy</button></pre>
 41 | 
 42 | <p>Parameters:</p>
 43 | <ul>
 44 | <li>
 45 | <p><code>content</code>: The content of the portal. This parameter is passed as the <code>value</code> parameter in <a href="https://lit.dev/docs/api/templates/#render">Lit's <code>render</code> function</a>.</p>
 46 | <blockquote>
 47 | <p>Any renderable value typically a <a href="https://lit.dev/docs/api/templates/#TemplateResult"><code>TemplateResult</code></a>
 48 | created by evaluating a template tag like <a href="https://lit.dev/docs/api/templates/#html"><code>html</code></a> or <a href="https://lit.dev/docs/api/templates/#svg"><code>svg</code></a>.</p>
 49 | </blockquote>
 50 | </li>
 51 | <li>
 52 | <p><code>targetOrSelector</code>: An element or a string that identifies the portal's target.</p>
 53 | <p>If the value is a string, then it is treated as a query selector and passed to <code>document.querySelector()</code> in order to locate the portal target.
 54 | If no element is found with the selector, then an error is thrown.</p>
 55 | </li>
 56 | <li>
 57 | <p><code>options</code>: Configuration parameters for the portal.</p>
 58 | <ul>
 59 | <li>
 60 | <p><code>placeholder</code>: A value that will be rendered while the <code>content</code> is resolving.</p>
 61 | </li>
 62 | <li>
 63 | <p><code>modifyContainer</code>: A function that will be called with the portal's container provided as an argument.
 64 | This allows you to programmatically control the container before the portal renders.</p>
 65 | </li>
 66 | </ul>
 67 | </li>
 68 | </ul>
 69 | <p>This function will always return <a href="https://lit.dev/docs/api/templates/#nothing">Lit's <code>nothing</code> value</a>, because nothing is supposed to render where the portal is used.</p>
 70 | <p>Both the <code>content</code> and the <code>targetOrSelector</code> parameters may be promises.
 71 | The <code>targetOrSelector</code> must resolve before the portal renders.</p>
 72 | <p>If the <code>content</code> is a promise, then an optional <code>placeholder</code> may be provided.
 73 | If no <code>placeholder</code> is provided, then the portal will not render until the <code>content</code> resolves.</p>
 74 | <p>See <a href="https://nicholas-wilcox.github.io/lit-modal-portal/classes/PortalDirective.html#render">the docs</a> for more information on how the <code>portal</code> directive works.</p>
 75 | <a id="advanced-usage" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Advanced Usage<a href="#advanced-usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><a id="modals-and-dialogs" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Modals and dialogs<a href="#modals-and-dialogs" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>This package no longer provides modal components. Instead, it focuses on a directive that is simple to use in different ways and encourages users to implement their own modals.</p>
 76 | <p>One recommended approach is to use the <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog"><code>dialog</code></a> element and its <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal"><code>showModal</code></a> method,
 77 | which can be accessed using <a href="https://lit.dev/docs/templates/directives/#referencing-rendered-dom">Lit's <code>ref</code> directive</a>.</p>
 78 | <p>Consider the following:</p>
 79 | <pre><code class="ts"><span class="hl-2">// example-app.ts</span><br/><span class="hl-8">import</span><span class="hl-1"> { </span><span class="hl-0">LitElement</span><span class="hl-1">, </span><span class="hl-0">html</span><span class="hl-1"> } </span><span class="hl-8">from</span><span class="hl-1"> </span><span class="hl-9">&#39;lit&#39;</span><span class="hl-1">;</span><br/><span class="hl-8">import</span><span class="hl-1"> { </span><span class="hl-0">customElement</span><span class="hl-1"> } </span><span class="hl-8">from</span><span class="hl-1"> </span><span class="hl-9">&#39;lit/decorators.js&#39;</span><span class="hl-1">;</span><br/><span class="hl-8">import</span><span class="hl-1"> { </span><span class="hl-0">ref</span><span class="hl-1">, </span><span class="hl-0">createRef</span><span class="hl-1"> } </span><span class="hl-8">from</span><span class="hl-1"> </span><span class="hl-9">&#39;lit/directives/ref.js&#39;</span><span class="hl-1">;</span><br/><span class="hl-8">import</span><span class="hl-1"> { </span><span class="hl-0">portal</span><span class="hl-1"> } </span><span class="hl-8">from</span><span class="hl-1"> </span><span class="hl-9">&#39;lit-modal-portal&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">import</span><span class="hl-1"> </span><span class="hl-9">&#39;./lit-dialog&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-1">@</span><span class="hl-10">customElement</span><span class="hl-1">(</span><span class="hl-9">&#39;example-app&#39;</span><span class="hl-1">)</span><br/><span class="hl-8">export</span><span class="hl-1"> </span><span class="hl-11">class</span><span class="hl-1"> </span><span class="hl-12">ExampleApp</span><span class="hl-1"> </span><span class="hl-11">extends</span><span class="hl-1"> </span><span class="hl-12">LitElement</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-0">dialogRef</span><span class="hl-1"> = </span><span class="hl-10">createRef</span><span class="hl-1">&lt;</span><span class="hl-12">HTMLDialogElement</span><span class="hl-1">&gt;();</span><br/><br/><span class="hl-1">  </span><span class="hl-10">render</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-8">return</span><span class="hl-1"> </span><span class="hl-10">html</span><span class="hl-9">`</span><br/><span class="hl-9">      &lt;h1&gt;lit-modal-portal Dialog Example&lt;/h1&gt;</span><br/><span class="hl-9">      &lt;button @click=</span><span class="hl-11">${</span><span class="hl-6">() </span><span class="hl-11">=&gt;</span><span class="hl-6"> </span><span class="hl-11">this</span><span class="hl-6">.</span><span class="hl-0">dialogRef</span><span class="hl-6">.</span><span class="hl-0">value</span><span class="hl-6">?.</span><span class="hl-10">showModal</span><span class="hl-6">()</span><span class="hl-11">}</span><span class="hl-9">&gt;Show Dialog&lt;/button&gt;</span><br/><span class="hl-9">      </span><span class="hl-11">${</span><span class="hl-10">portal</span><span class="hl-6">(</span><span class="hl-10">html</span><span class="hl-9">`&lt;lit-dialog .dialogRef=</span><span class="hl-11">${</span><span class="hl-11">this</span><span class="hl-6">.</span><span class="hl-0">dialogRef</span><span class="hl-11">}</span><span class="hl-9">&gt;&lt;/lit-dialog&gt;`</span><span class="hl-6">, </span><span class="hl-0">document</span><span class="hl-6">.</span><span class="hl-0">body</span><span class="hl-6">)</span><span class="hl-11">}</span><br/><span class="hl-9">    `</span><span class="hl-1">;</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 80 | </code><button type="button">Copy</button></pre>
 81 | 
 82 | <pre><code class="ts"><span class="hl-2">// lit-dialog.ts</span><br/><span class="hl-8">import</span><span class="hl-1"> { </span><span class="hl-0">LitElement</span><span class="hl-1">, </span><span class="hl-0">html</span><span class="hl-1"> } </span><span class="hl-8">from</span><span class="hl-1"> </span><span class="hl-9">&#39;lit&#39;</span><span class="hl-1">;</span><br/><span class="hl-8">import</span><span class="hl-1"> { </span><span class="hl-0">customElement</span><span class="hl-1">, </span><span class="hl-0">property</span><span class="hl-1"> } </span><span class="hl-8">from</span><span class="hl-1"> </span><span class="hl-9">&#39;lit/decorators.js&#39;</span><span class="hl-1">;</span><br/><span class="hl-8">import</span><span class="hl-1"> { </span><span class="hl-0">ref</span><span class="hl-1">, </span><span class="hl-0">createRef</span><span class="hl-1">, </span><span class="hl-0">Ref</span><span class="hl-1"> } </span><span class="hl-8">from</span><span class="hl-1"> </span><span class="hl-9">&#39;lit/directives/ref.js&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-1">@</span><span class="hl-10">customElement</span><span class="hl-1">(</span><span class="hl-9">&#39;lit-dialog&#39;</span><span class="hl-1">)</span><br/><span class="hl-8">export</span><span class="hl-1"> </span><span class="hl-11">class</span><span class="hl-1"> </span><span class="hl-12">LitDialog</span><span class="hl-1"> </span><span class="hl-11">extends</span><span class="hl-1"> </span><span class="hl-12">LitElement</span><span class="hl-1"> {</span><br/><span class="hl-1">  @</span><span class="hl-10">property</span><span class="hl-1">({ </span><span class="hl-0">attribute:</span><span class="hl-1"> </span><span class="hl-11">false</span><span class="hl-1"> })</span><br/><span class="hl-1">  </span><span class="hl-0">dialogRef</span><span class="hl-1">: </span><span class="hl-12">Ref</span><span class="hl-1">&lt;</span><span class="hl-12">HTMLDialogElement</span><span class="hl-1">&gt; = </span><span class="hl-10">createRef</span><span class="hl-1">();</span><br/><br/><span class="hl-1">  </span><span class="hl-10">render</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-8">return</span><span class="hl-1"> </span><span class="hl-10">html</span><span class="hl-9">`</span><br/><span class="hl-9">      &lt;dialog </span><span class="hl-11">${</span><span class="hl-10">ref</span><span class="hl-6">(</span><span class="hl-11">this</span><span class="hl-6">.</span><span class="hl-0">dialogRef</span><span class="hl-6">)</span><span class="hl-11">}</span><span class="hl-9">&gt;</span><br/><span class="hl-9">        &lt;p&gt;This is the dialog&lt;/p&gt;</span><br/><span class="hl-9">        &lt;button @click=</span><span class="hl-11">${</span><span class="hl-6">() </span><span class="hl-11">=&gt;</span><span class="hl-6"> </span><span class="hl-11">this</span><span class="hl-6">.</span><span class="hl-0">dialogRef</span><span class="hl-6">.</span><span class="hl-0">value</span><span class="hl-6">?.</span><span class="hl-10">close</span><span class="hl-6">()</span><span class="hl-11">}</span><span class="hl-9">&gt;Close Dialog&lt;/button&gt;</span><br/><span class="hl-9">      &lt;/dialog&gt;</span><br/><span class="hl-9">    `</span><span class="hl-1">;</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 83 | </code><button type="button">Copy</button></pre>
 84 | 
 85 | <p>In this example, we have a <code>&lt;lit-dialog&gt;</code> component that accepts a <code>dialogRef</code> from the parent <code>&lt;example-app&gt;</code>.
 86 | This allows the parent to open the dialog and the child to imperatively close it on a button's <code>@click</code> event.</p>
 87 | <p>This basic pattern can be extended as necessary. Examples include:</p>
 88 | <ul>
 89 | <li>Listening to the dialog's <code>close</code> event, which would trigger if the dialog was closed with the Escape key.</li>
 90 | <li>Adding styles to the <code>&lt;lit-dialog&gt;</code> component.</li>
 91 | <li>Adding callback function properties to <code>&lt;lit-dialog&gt;</code>.</li>
 92 | <li>Using slotted content in the dialog component's template.</li>
 93 | </ul>
 94 | <a id="targeting-elements-in-the-shadow-dom" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Targeting elements in the Shadow DOM<a href="#targeting-elements-in-the-shadow-dom" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Using a DOM node in a Lit component as a target for a portal is tricky (and perhaps useless or inadvisable), for a number of reasons:</p>
 95 | <ol>
 96 | <li>The <code>querySelector</code> method does not penetrate through the shadow root, so running queries on the <code>document</code> node won't return anything.</li>
 97 | <li>The <code>portal</code> directive is <em>asynchronous</em>, so if it renders at the same time as the component's first render, <em>then the target might not even exist yet</em>.</li>
 98 | </ol>
 99 | <p>We cannot simply call <code>querySelector</code> on a different render root, such as a component's shadow root, because it might be empty. However, this is still possible to accomplish safely with the use of <a href="https://lit.dev/docs/api/decorators/#queryAsync">Lit's <code>queryAsync</code> decorator</a>.</p>
100 | <pre><code class="ts"><span class="hl-8">import</span><span class="hl-1"> { </span><span class="hl-0">LitElement</span><span class="hl-1">, </span><span class="hl-0">html</span><span class="hl-1"> } </span><span class="hl-8">from</span><span class="hl-1"> </span><span class="hl-9">&#39;lit&#39;</span><span class="hl-1">;</span><br/><span class="hl-8">import</span><span class="hl-1"> { </span><span class="hl-0">customElement</span><span class="hl-1">, </span><span class="hl-0">queryAsync</span><span class="hl-1"> } </span><span class="hl-8">from</span><span class="hl-1"> </span><span class="hl-9">&#39;lit/decorators.js&#39;</span><span class="hl-1">;</span><br/><span class="hl-8">import</span><span class="hl-1"> { </span><span class="hl-0">portal</span><span class="hl-1"> } </span><span class="hl-8">from</span><span class="hl-1"> </span><span class="hl-9">&#39;lit-modal-portal&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-1">@</span><span class="hl-10">customElement</span><span class="hl-1">(</span><span class="hl-9">&#39;example-component&#39;</span><span class="hl-1">)</span><br/><span class="hl-8">export</span><span class="hl-1"> </span><span class="hl-11">class</span><span class="hl-1"> </span><span class="hl-12">ExampleComponent</span><span class="hl-1"> </span><span class="hl-11">extends</span><span class="hl-1"> </span><span class="hl-12">LitElement</span><span class="hl-1"> {</span><br/><span class="hl-1">  @</span><span class="hl-10">queryAsync</span><span class="hl-1">(</span><span class="hl-9">&#39;#portal-target&#39;</span><span class="hl-1">)</span><br/><span class="hl-1">  </span><span class="hl-0">portalTarget</span><span class="hl-1">: </span><span class="hl-12">Promise</span><span class="hl-1">&lt;</span><span class="hl-12">HTMLElement</span><span class="hl-1">&gt;;</span><br/><br/><span class="hl-1">  </span><span class="hl-10">render</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-8">return</span><span class="hl-1"> </span><span class="hl-10">html</span><span class="hl-9">`&lt;div&gt;</span><br/><span class="hl-9">      </span><span class="hl-11">${</span><span class="hl-10">portal</span><span class="hl-6">(</span><span class="hl-10">html</span><span class="hl-9">`&lt;p&gt;Portal content&lt;/p&gt;`</span><span class="hl-6">, </span><span class="hl-11">this</span><span class="hl-6">.</span><span class="hl-0">portalTarget</span><span class="hl-6">)</span><span class="hl-11">}</span><br/><span class="hl-9">      &lt;p&gt;The portal isn&#39;t rendered before this paragraph, but in the following div.&lt;/p&gt;</span><br/><span class="hl-9">      &lt;div id=&quot;portal-target&quot;&gt;&lt;/div&gt;</span><br/><span class="hl-9">    &lt;/div&gt;`</span><span class="hl-1">;</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
101 | </code><button type="button">Copy</button></pre>
102 | 
103 | <p>In this example, <code>this.portalTarget</code> is a promise that resolves to the <code>&lt;div id=&quot;portal-target&gt;</code> element after the <code>&lt;example-component&gt;</code> renders.</p>
104 | <p>See <a href="https://lit.dev/docs/components/shadow-dom/">Lit's documentation</a> for more information on components and the Shadow DOM.</p>
105 | <a id="styling-portal-content" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Styling portal content<a href="#styling-portal-content" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Another consquence of the Shadow DOM is that only <a href="https://lit.dev/docs/components/styles/#inheritance">inherited CSS properties</a> affect elements inside a shadow root. Coupled with the fact that a portal serves to render content in a different location, this makes it difficult for a component that uses the <code>portal</code> directive to style the portal's content.</p>
106 | <p><strong>It is recommended that the content of a portal should be another Lit component that can own its CSS.</strong> Alternatively, the <a href="https://lit.dev/docs/templates/directives/#stylemap"><code>styleMap</code> directive</a> can be used in the template provided to the <code>portal</code> directive.</p>
107 | <p>See <a href="https://lit.dev/docs/components/styles/#shadow-dom">Lit's documentation</a> for more information on working with CSS styles and the Shadow DOM.</p>
108 | <a id="documentation" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Documentation<a href="#documentation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>More in-depth documentation for this package is included in the repo, under the <code>/docs</code> directory.
109 | It is also <a href="https://nicholas-wilcox.github.io/lit-modal-portal/index.html">hosted on GitHub Pages</a>.</p>
110 | <p>The documentation is generated using <a href="https://typedoc.org/">TypeDoc</a>.
111 | Please note the separate <code>docs.tsconfig.json</code> and <code>src/docs.index.ts</code> files if you plan to make changes related to the documentation.</p>
112 | <a id="development" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Development<a href="#development" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>For demonstration and testing purposes, you can start a local development server by running <code>npm run dev</code>.
113 | There are multiple examples of the <code>portal</code> directive that explain its features and supported usage.</p>
114 | <p>The default host is <code>localhost:8000</code>, and you may override the port number by setting the PORT environment variable.</p>
115 | <p>The development server is <a href="https://modern-web.dev/docs/dev-server/overview/">Modern Web's server</a>,
116 | running in watch mode, so you can see code changes reloaded into the browser automatically.
117 | Note the middleware in <code>web-dev-server.config.mjs</code> that rewrites requests for the root so that <code>dev/index.html</code> is served.</p>
118 | <a id="testing" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Testing<a href="#testing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>There are some tests for the <code>portal</code> directive in <code>src/portal.test.ts</code>. They use <a href="https://modern-web.dev/guides/test-runner/getting-started/">Modern Web's test runner</a> and the <a href="https://open-wc.org/guides/developing-components/testing/">Open Web Components <code>@open-wc/testing</code></a> framework.</p>
119 | <p>You can execute the tests by running <code>npm run test</code>.</p>
120 | <a id="contributing-and-bug-reports" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Contributing and Bug Reports<a href="#contributing-and-bug-reports" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Currently, there is no standard procedure for contributing to this project.
121 | You are absolutely welcome to fork the repository and make a pull request,
122 | and to file issues if you encounter problems while using it.</p>
123 | </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#lit-modal-portal"><span>lit-<wbr/>modal-<wbr/>portal</span></a><ul><li><a href="#warning-notice-on-version-06"><span>:warning: <wbr/>Notice on version 0.6</span></a></li><li><a href="#installation-and-usage"><span>Installation and <wbr/>Usage</span></a></li><li><a href="#api"><span>API</span></a></li><li><a href="#advanced-usage"><span>Advanced <wbr/>Usage</span></a></li><li><ul><li><a href="#modals-and-dialogs"><span>Modals and dialogs</span></a></li><li><a href="#targeting-elements-in-the-shadow-dom"><span>Targeting elements in the <wbr/>Shadow DOM</span></a></li><li><a href="#styling-portal-content"><span>Styling portal content</span></a></li></ul></li><li><a href="#documentation"><span>Documentation</span></a></li><li><a href="#development"><span>Development</span></a></li><li><ul><li><a href="#testing"><span>Testing</span></a></li></ul></li><li><a href="#contributing-and-bug-reports"><span>Contributing and <wbr/>Bug <wbr/>Reports</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">Lit Modal Portal Documentation</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
124 | 


--------------------------------------------------------------------------------