Skip to content

Commit a89364a

Browse files
authored
Merge pull request #1 from AegisJSProject/release/0.0.1
Initial release
2 parents ea41597 + 90bbc2e commit a89364a

18 files changed

+545
-285
lines changed

CHANGELOG.md

Lines changed: 1 addition & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6,21 +6,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
66

77
## [Unreleased]
88

9-
## [v0.0.4] - 2024-03-03
10-
11-
### Changed
12-
- Update dependencies
13-
14-
## [v0.0.3] - 2024-02-28
15-
16-
### Changed
17-
- Renamed to `@aegisjsproject/template`
18-
19-
## [v0.0.2]
20-
21-
### Changed
22-
- Update dependencies
23-
24-
## [v0.0.1] - 2024-02-04
9+
## [v0.0.1] - 2024-03-04
2510

2611
Initial Release

README.md

Lines changed: 102 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,25 @@
1-
# `@aegisjsproject/template`
1+
# `@aegisjsproject/aegis-modal`
22

3-
Template repository for [`@aegisjsproject/component`](https://github.com/AegisJSProject/component) components
3+
An `<aegis-modal>` component built using [`@aegisjsproject/component`](https://npmjs.org/package/@aegisjsproject/component),
4+
offering full built-in accessibility, customization, and enhanced security.
45

5-
[![CodeQL](https://@github.com/AegisJSProject/template/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/shgysk8zer0/npm-template/actions/workflows/codeql-analysis.yml)
6-
![Node CI](https://@github.com/AegisJSProject/template/workflows/Node%20CI/badge.svg)
7-
![Lint Code Base](https://@github.com/AegisJSProject/template/workflows/Lint%20Code%20Base/badge.svg)
6+
[![CodeQL](https://@github.com/AegisJSProject/aegis-modal/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/shgysk8zer0/npm-template/actions/workflows/codeql-analysis.yml)
7+
![Node CI](https://@github.com/AegisJSProject/aegis-modal/workflows/Node%20CI/badge.svg)
8+
![Lint Code Base](https://@github.com/AegisJSProject/aegis-modal/workflows/Lint%20Code%20Base/badge.svg)
89

9-
[![GitHub license](https://img.shields.io/github/license/AegisJSProject/template.svg)](https://@github.com/AegisJSProject/template/blob/master/LICENSE)
10-
[![GitHub last commit](https://img.shields.io/github/last-commit/AegisJSProject/template.svg)](https://@github.com/AegisJSProject/template/commits/master)
11-
[![GitHub release](https://img.shields.io/github/release/AegisJSProject/template?logo=github)](https://@github.com/AegisJSProject/template/releases)
10+
[![GitHub license](https://img.shields.io/github/license/AegisJSProject/aegis-modal.svg)](https://@github.com/AegisJSProject/aegis-modal/blob/master/LICENSE)
11+
[![GitHub last commit](https://img.shields.io/github/last-commit/AegisJSProject/aegis-modal.svg)](https://@github.com/AegisJSProject/aegis-modal/commits/master)
12+
[![GitHub release](https://img.shields.io/github/release/AegisJSProject/aegis-modal?logo=github)](https://@github.com/AegisJSProject/aegis-modal/releases)
1213
[![GitHub Sponsors](https://img.shields.io/github/sponsors/shgysk8zer0?logo=github)](https://github.com/sponsors/shgysk8zer0)
1314

14-
[![npm](https://img.shields.io/npm/v/@aegisjsproject/template)](https://www.npmjs.com/package/@aegisjsproject/template)
15-
![node-current](https://img.shields.io/node/v/@aegisjsproject/template)
16-
![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/%40aegisjsproject%template)
17-
[![npm](https://img.shields.io/npm/dw/@aegisjsproject/npm-template?logo=npm)](https://www.npmjs.com/package/@aegisjsproject/template)
15+
[![npm](https://img.shields.io/npm/v/@aegisjsproject/aegis-modal)](https://www.npmjs.com/package/@aegisjsproject/aegis-modal)
16+
![node-current](https://img.shields.io/node/v/@aegisjsproject/aegis-modal)
17+
![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/%40aegisjsproject%aegis-modal)
18+
[![npm](https://img.shields.io/npm/dw/@aegisjsproject/aegis-modal?logo=npm)](https://www.npmjs.com/package/@aegisjsproject/aegis-modal)
1819

1920
[![GitHub followers](https://img.shields.io/github/followers/AegisJSProject.svg?style=social)](https://github.com/AegisJSProoject)
20-
![GitHub forks](https://img.shields.io/github/forks/AegisJSProject/template.svg?style=social)
21-
![GitHub stars](https://img.shields.io/github/stars/AegisJSProject/template.svg?style=social)
21+
![GitHub forks](https://img.shields.io/github/forks/AegisJSProject/aegis-modal.svg?style=social)
22+
![GitHub stars](https://img.shields.io/github/stars/AegisJSProject/aegis-modal.svg?style=social)
2223
[![Twitter Follow](https://img.shields.io/twitter/follow/shgysk8zer0.svg?style=social)](https://twitter.com/shgysk8zer0)
2324

2425
[![Donate using Liberapay](https://img.shields.io/liberapay/receives/shgysk8zer0.svg?logo=liberapay)](https://liberapay.com/shgysk8zer0/donate "Donate using Liberapay")
@@ -28,125 +29,101 @@ Template repository for [`@aegisjsproject/component`](https://github.com/AegisJS
2829
- [Contributing](./.github/CONTRIBUTING.md)
2930
<!-- - [Security Policy](./.github/SECURITY.md) -->
3031

31-
This is a [GitHub Template Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository)
32-
to create components using [`@aegisjsproject/component`](https://npmjs.com/package/@aegisjsproject/component).
33-
It serves as a quick-start to creating light-weight, secure, web standards based
34-
components. It provides the essentials, such as:
35-
36-
- The essential packages:
37-
- [`@aegisjsproject/core`](https://github.com/AegisJSProject/aegis)
38-
- [`@aegisjsproject/styles`](https://github.com/AegisJSProject/styles)
39-
- [`@aegisjsproject/component`](https://github.com/AegisJSProject/component)
40-
- Build tools
41-
- [eslint](https://npmjs.com/eslint)
42-
- [rollup](https://npmjs.com/rollup)
43-
- [Dependabot](https://github.com/dependabot) & [CodeQL](https://github.com/github/codeql) config
44-
- Pull Request & Issue templates
45-
- Automated releases to npm on `git tag` (when pushed using `git push --tags`)
46-
- Provides GitHub Action for Package Provenance
47-
48-
To start creating your own component, just go to the [GitHub repo](https://@github.com/AegisJSProject/template)
49-
and click the "Use this template" button.
50-
51-
## Steps to Create a Component
52-
53-
- Create Repository from the GitHub Template Repository
54-
- Clone your new Aegis Component Repository
55-
- Update the `README.md`, `package.json`, & `CHANGELOG.md` as needed (especially the name)
56-
- Create your component
57-
- Update `rollup.config.js` (don't forget to update `input` & `output.file`)
58-
- Publish (create and merge PR)
59-
60-
## Using Automated Releases
61-
62-
The following setup will create an automated GitHub Release and publish on npm
63-
for every signed git tag (`git tag -s vx.y.z`) pushed to GitHub:
64-
65-
- Create a "Classic Token" (Automation) on [npmjs.org](https://www.npmjs.com/)
66-
- Give that token a descriptive name name and copy it
67-
- Paste it into your repository's "Repository secrets" in "settings" -> "Secrets and variables" -> Actions
68-
- Done!
69-
70-
Now, every time you create a new PGP signed tag on GitHub (don't forget to `git push --tags`)
71-
it will create a new GitHub Release and a new release on npm with Package Provenance.
72-
73-
## Example Component:
74-
75-
```js
76-
import { AegisComponent, SYMBOLS, TRIGGERS } from '@aegisjsproject/component';
77-
import { html, appendTo } from '@aegisjsproject/core';
78-
79-
class HTMLHelloWorldElement extends AegisComponent {
80-
async [SYMBOLS.render](type, { shadow }) {
81-
switch(type) {
82-
case TRIGGERS.constructed:
83-
appendTo(shadow, html`<h1>Hello, World!</h1>`);
84-
break;
85-
}
86-
}
87-
}
32+
## Important differences compared to [`<dialog>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog)
33+
34+
- `<aegis-modal>` is modal-only
35+
- `<aegis-modal>` **SHOULD** only be appended as a direct child of `<body>`
36+
- `<aegis-modal>` automatically adds a sticky header and close button
37+
- Provides simple open/close animations
38+
- Has an `autoremove` attribute to automatically remove the element once closed
39+
- Supports an optional `AbortController` in the `show({ signal })` method
40+
- Adds `whenOpened` and `whenClosed` getter methods, returning relevant promises
41+
- Adds a static `create()` method, which creates and optionally appends and opens if given a `signal`
42+
43+
## Compatibility / polyfills
44+
45+
The entire AegisJSProject ecosystem requires support for [`Element.prototype.setHTML()`](https://github.com/WICG/sanitizer-api)
46+
and [Constructable Stylesheets](https://web.dev/articles/constructable-stylesheets).
47+
Additionally, [`Promise.withResolvers()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers)
48+
as well as [`inert`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inert)
49+
are also required for proper functionality.
50+
51+
Such polyfills are *not* included to avoid the bloat/duplication of polyfills. However,
52+
an extensive polyfill script that ensures compatibility is available via:
53+
54+
```html
55+
<script type="application/javascript" defer="" referrerpolicy="no-referrer" crossorigin="anonymous" integrity="sha384-Shkrmxly5RI9mCU8DQr6l4VLVJzjPzgx9KP/f5i7pEcl7ZUt0wHiAweGjbpjU2d5" src="https://unpkg.com/@shgysk8zer0/polyfills@0.3.1/all.min.js" fetchpriority="auto"></script>
56+
```
57+
58+
## Installation
59+
60+
### Via CDN:
61+
62+
```html
63+
<script type="module" src="https://unpkg.com/@aegisjsproject/aegis-modal[@:version]/aegis-modal.js" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
64+
```
65+
66+
### Via npm
67+
68+
```bash
69+
npm i @aegisjsproject/aegis-markdown
70+
```
71+
72+
### Via [Git Submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
8873

89-
HTMLHelloWorldElement.register('hello-world');
74+
```bash
75+
git subomdule add https://github.com/AegisJSProject/aegis-modal [:destination]
9076
```
9177

92-
## Package, Component, & Repository Requirements
78+
## Using [`<script type="importmap">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap)
9379

94-
All packages **MUST** adhere to strict but fairly easy security guidelines:
80+
All `@aegisjsproject/*` libraries are available and ready to use without a build
81+
process such as webpack, but will require a `<script type="importmap">` that includes
82+
all dependencies:
9583

96-
- All commits and tags **MUST** be [PGP/GPG signed](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
97-
- All web-based commits **MUST** be signed off by the contributor (a setting in GitHub repo settings)
98-
- All releases **MUST** use [Package Provenance](https://github.blog/2023-04-19-introducing-npm-package-provenance/)
99-
- Components **MUST** adhere to a strict [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)
100-
- Components **MUST** comply with the provided [`TrustedTypesPolicy`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy) or add their own, which **SHOULD**:
101-
- Use `:component-name#html` for writing HTML as a string
102-
- Use `:component-name#script-url`
103-
- Components **MUST** be `import`able from a CDN (such as `unpkg.com`) without any build step/bundler
104-
- Component **SHOULD** provide a `<script type="importmap">` or `importmap.json` as necessary
105-
- Components **MUST NOT** use inline scripts (`script-src 'unsafe-inline`) or styles (`style-src 'unsafe-inline'`)
106-
- Components **MUST NOT** use `element.innerHTML` or similar
107-
- Components **MUST NOT** use `eval()` or `onclick` or anything similar
108-
- Components using [life cycle callbacks](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#using_the_lifecycle_callbacks) **MUST** have a `[Symbol.for('aegis:render')]` method
10984

110-
## Content-Security-Policy
85+
### Short & Basic
11186

112-
This is the base CSP (with comments):
87+
```html
88+
<script type="importmap">
89+
{
90+
"imports": {
91+
"@aegisjsproject/": "https://unpkg.com/@aegisjsproject/"
92+
}
93+
}
94+
</script>
95+
```
96+
97+
### More detailed & with versions
11398

99+
```html
100+
{
101+
"imports": {
102+
"@aegisjsproject/core/": "https://unpkg.com/@aegisjsproject/core@0.1.2/",
103+
"@aegisjsproject/styles/": "https://unpkg.com/@aegisjsproject/styles@0.1.1/",
104+
"@aegisjsproject/component/": "https://unpkg.com/@aegisjsproject/component@0.1.1/",
105+
"@aegisjsproject/aegis-modal/": "https://unpkg.com/@aegisjsproject/aegis-modal@0.0.1/"
106+
}
107+
}
114108
```
115-
default-src 'none'; // Block everything by default
116-
style-src 'self' blob:; // `blob:` essential for constructable stylesheet polyfill
117-
script-src 'self' https://unpkg.com/@aegisjsproject/; // Your script source may/should be added
118-
connect-src 'self'; // Add any data sources as needed, but as specific as possible
119-
trusted-types emtpy#html mepty#script sanitizer-raw#html; // Add to as necessary
120-
require-trusted-types-for 'script'; // This is required and currently the only option
109+
110+
... or ...
111+
112+
```html
113+
<script type="importmap">
114+
{
115+
"imports": {
116+
"@aegisjsproject/": "/node_modules/@aegisjsproject/"
117+
}
118+
}
119+
</script>
121120
```
122121

123-
Components **MAY** differ from this in requiring additional `script-src` (other
124-
than `unnsafe-inline`, `unsafe-eval`, and additional `nonce-*` or `sha*` hashes
125-
(URL only permitted). Components **MAY** add to the `trusted-types`, if necessary,
126-
such as to add additional [`policy.createScriptURL()`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy/createScript)s
127-
as essential. Any such policy created for script URLs (namely, `<iframe>`s)
128-
**SHOULD** be of the form `:component-name#script-url`.
129-
130-
Components **SHOULD NOT** utilize methods or setters (such as `innerHTML`) which
131-
write HTML as strings and would require [`policy.createHTML()`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy/createHTML).
132-
Components **MAY** use the text alternatives, such as `textContent`. However,
133-
should the component require such things, the component **MUST** create an
134-
additional `TrsutedTypePolicy`, which **SHOULD** be named as `:component-name#html`:
135-
136-
Components **SHOULD NOT** include any [`policy.createScript()`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy/createScript)
137-
unless absolutely essential, as this would violate the strict CSP requirement and
138-
restriction from using `unsafe-*` in `script-src`. However, should your component
139-
absolutely and justifiably require this, it **SHOULD** use a `TrustedTypes` Policy
140-
name of the form `:component-name#script`.
141-
142-
Any component which requires more than one of `createHTML()`, `createScriptURL()`,
143-
or `createScript()` **MAY** instead combine the above simple into a single policy,
144-
which **SHOULD** be named `:component-name`.
145-
146-
Components **MUST** explicitly list any necessary changes to their CSP (including)
147-
`TrustedTypes` in their README.
148-
149-
To be listed in the upcoming Aegis component registry, components **MUST NOT**
150-
implement their own `createHTML()` (`:component-name#html`) or `createScript()`
151-
(`component-name#script`) methods, but **MAY** implement a `createScriptURL()`
152-
(`:component-name#script-url`) method.
122+
## Example
123+
124+
```html
125+
<aegis-modal>
126+
<h1 slot="heading">Lorem Ipsum</h1>
127+
<p>Error aut mollitia qui alias aut. Temporibus vitae impedit deserunt repellat voluptatibus et. Minima aut et tempore. Ut officiis sed consectetur. Voluptas praesentium ipsam rerum eligendi dolorum. Voluptatem similique omnis quis quidem.</p>
128+
</aegis-modal>
129+
```

0 commit comments

Comments
 (0)