Merge pull request #5 from AegisJSProject/feature/customization

Improve customization

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v0.0.4] - 2024-03-30
+
+### Added
+- Add functions to easily add/set stylesheets
+- Add option to set custom stringify/map function in HTML parsers
+- Add web component example in README
+
 ## [v0.0.3] - 2024-03-29
 
 ### Added

README.md

@@ -72,6 +72,28 @@ document.adoptedStyleSheets = [css`
 `];
 ```
 
+## Web Component Example
+
+```js
+import { template } from './template.js';
+import { base, dark, light } from './theme.js';
+import { btnStyles, cardStyles } from './styles.js';
+
+class MyComponent extends HTMLElement {
+  #shadow;
+
+  constructor() {
+    super();
+
+    this.#shadow = this.attachShadow({ mode: 'closed' });
+    this.#shadow.append(template);
+    this.#shadow.adoptedStyleSheets = [base, dark, light btnStyles, cardStyes];
+  }
+}
+
+customElements.define('my-component', MyComponent);
+```
+
 > [!WARNING]
 > The Sanitizer API is still being developed, and could change. Until the API
 > is stable, this project will remain pre-v1.0.0

css.js

@@ -31,3 +31,19 @@ export function styleSheetToLink(sheet, { crossOrigin = 'anonymous', referrerPol
 	link.href = URL.createObjectURL(file);
 	return link;
 }
+
+export function setStyleSheets(node, ...styles) {
+	if (node instanceof HTMLDocument || node instanceof ShadowRoot) {
+		node.adoptedStyleSheets = styles;
+	} else {
+		throw new TypeError('Node must be a `HTMLDocument` or `ShadowRoot`.');
+	}
+}
+
+export function addStyleSheets(node, ...styles) {
+	if (node instanceof Document || node instanceof ShadowRoot) {
+		node.adoptedStyleSheets = [...node.adoptedStyleSheets, ...styles];
+	} else {
+		throw new TypeError('Node must be a `HTMLDocument` or `ShadowRoot`.');
+	}
+}

html.js

@@ -1,15 +1,17 @@
 import { sanitizer } from '@aegisjsproject/sanitizer/config/base.js';
 import { stringify } from './utils.js';
 
-export const createHTMLParser = (config = sanitizer) => (strings, ...values) => {
-	const el = document.createElement('div');
-	const frag = document.createDocumentFragment();
-	el.setHTML(String.raw(strings, ...values.map(stringify)).trim(), { sanitizer: config });
-	frag.append(...el.childNodes);
-	return frag;
-};
+export function createHTMLParser(config = sanitizer, { mapper = stringify } = {}) {
+	return (strings, ...values) => {
+		const el = document.createElement('div');
+		const frag = document.createDocumentFragment();
+		el.setHTML(String.raw(strings, ...values.map(mapper)).trim(), { sanitizer: config });
+		frag.append(...el.childNodes);
+		return frag;
+	};
+}
 
-export const html = createHTMLParser(sanitizer);
+export const html = createHTMLParser(sanitizer, { mapper: stringify });
 
 export const el = (...args) => html.apply(null, args).firstElementChild;
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aegisjsproject/parsers",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "A collection of secure & minimal parsers for HTML, CSS, SVG, MathML, XML, and JSON",
   "keywords": [
     "aegis",

parsers.js

@@ -1,5 +1,8 @@
 export { html, el, doc, createHTMLParser } from './html.js';
-export { css, createCSSParser, styleSheetToLink, createStyleSheet } from './css.js';
+export {
+	css, createCSSParser, styleSheetToLink, createStyleSheet, addStyleSheets,
+	setStyleSheets,
+} from './css.js';
 export { svg } from './svg.js';
 export { math } from './math.js';
 export { xml } from './xml.js';

utils.js

@@ -11,7 +11,7 @@ export function stringify(thing) {
 			return thing;
 
 		case 'function':
-			throw new TypeError('Functions are not allowed.');
+			throw new TypeError('Functions are not supported.');
 
 		case 'object':
 			if (thing === null) {