2.0.0 • Published 4 months ago
exdom v2.0.0
exdom
Essential DOM utilities.
- Query selector shortcuts
- Soft HTML, text, attribute, and input value setters
- Reconciliation
- Type-safe DOM event management
Inspired by learnings from VANILLA TODO, a case study on viable techniques for vanilla web development.
Installation
Via npm:
npm install exdom
When not using a bundler, exdom can be imported via CDN:
// src/exdom.js or src/exdom.ts
export * from 'https://cdn.jsdelivr.net/npm/exdom@2.0.0/dist/exdom.min.js';
// src/exdom.d.ts
declare module 'https://cdn.jsdelivr.net/npm/exdom@2.0.0/dist/exdom.min.js' {
export * from 'exdom';
}
// src/app.js or src/app.ts
import { ... } from './exdom.js';
// ...
Usage
A very basic to-do app with exdom could look like this (in TypeScript, but JavaScript is equally possible) and covers most of exdom's functions:
import {
CustomEventElement,
qsr,
reconcile,
requestAnimationFrameOnce,
setText,
setValue,
TypedCustomEvent,
} from 'exdom';
// Type-safe custom DOM event details
interface TodoAppEvents {
addTodoItem: string;
toggleTodoItem: string;
todoItem: TodoItemData;
}
interface TodoItemData {
id: string;
label: string;
done: boolean;
}
// Component functions
function TodoApp(el: CustomEventElement<TodoAppEvents>) {
// Base HTML
el.innerHTML = /* html */ `
<h1>To-Do</h1>
<p>
<input type="text" name="label">
<button type="button" class="add">Add</button>
</p>
<ul class="items"></ul>
`;
// Initial data
let items: TodoItemData[] = [
{
id: crypto.randomUUID(),
label: 'Hello, world!',
done: false,
},
];
// Idempotent update
function update() {
// Reconcile todo item components with item list
reconcile({
container: qsr(el, '.items'),
items,
create: () => TodoItem(document.createElement('li')),
update: (el, item) =>
el.dispatchEvent(new TypedCustomEvent('todoItem', { detail: item })),
});
}
// Action handlers
el.addEventListener('addTodoItem', (e) => {
const newItem = {
id: crypto.randomUUID(),
label: e.detail,
done: false,
};
items = [...items, newItem];
requestAnimationFrameOnce(update);
});
el.addEventListener('toggleTodoItem', (e) => {
items = items.map((item) =>
item.id === e.detail ? { ...item, done: !item.done } : item,
);
requestAnimationFrameOnce(update);
});
// UI Events
const labelInput = qsr<HTMLInputElement>(el, '[name=label]');
qsr(el, '.add').addEventListener('click', () => {
el.dispatchEvent(
new TypedCustomEvent('addTodoItem', {
detail: labelInput.value,
bubbles: true,
}),
);
setValue(labelInput, '');
});
update(); // Initial update
return el;
}
function TodoItem(el: CustomEventElement<TodoAppEvents>) {
el.innerHTML = /* html */ `
<input type="checkbox">
<label></label>
`;
let data: TodoItemData;
function update() {
setText(qsr(el, 'label'), data.label);
setValue(qsr(el, '[type=checkbox]'), data.done);
}
el.addEventListener('todoItem', (e) => {
data = e.detail;
requestAnimationFrameOnce(update);
});
qsr(el, '[type=checkbox]').addEventListener('click', () => {
el.dispatchEvent(
new TypedCustomEvent('toggleTodoItem', {
detail: data.id,
bubbles: true,
}),
);
});
return el;
}
// Mount to document
TodoApp(qsr(document, '#app'));
See also API reference
Tests
npx playwright install
(once)npm test