| Type/Interface | Description |
| :--- | :--- |
| ParseSelector | Infers element type from CSS selector string. |
| ElementInput | Element or selector input union. |
| SelectorFunction | Dual-mode selector function signature. |
| SVGElementTags | Supported SVG tag names. |
| Unsubscribe | Cleanup function type returned by event listeners. |
| EventMap | Event map for HTML elements, extensible for custom events. |
| ExtractEventDetail | Extracts detail type from CustomEvent. |
| ElementProps | Properties for creating/modifying elements. |
| HElementProps | Hyperscript element props. |
| StrictElementProps | Element properties with element-specific validation. |
| DeepReadonly | Makes all properties deeply readonly. |
| DeepPartial | Makes all properties deeply partial. |
| Path | String or array path for Obj.get/set. |
| FormSerializeOptions | Options for Form.serialize. |
| ClickOutsideOptions | Options for onClickOutside. |
| AutoResizeOptions | Options for autoResize. |
| UploadOptions | Options for createUpload. |
| UploadController | Return type for createUpload. |
| DraggableBounds | Boundaries for draggable. |
| DraggableOptions | Options for draggable. |
| SortableOptions | Options for createSortable. |
| SortableController | Return type for createSortable. |
| MediaQueryMap | Map of media query strings. |
| MediaQueryMatches | Match state for queries. |
| MediaQueryController | Controller from createMediaQuery. |
| A11yRovingOptions | Options for A11y.roving. |
| ListOptions | List helper configuration. |
| BoundList | Bound list helper type. |
| ViewRefsOptions | Options for viewRefs. |
| ViewRefsContext | Context passed to viewRefs. |
| ViewRefsInstance | Instance returned by viewRefs. |
| BindPrimitives | Binding primitive type map. |
| BinderSchema | Binder schema type. |
| InferBinderData | Infers binder input data. |
| EnhancedBinder | Enhanced binder interface. |
| HttpInterceptors | HTTP interceptors. |
| HttpAbortController | Abortable HTTP result. |
| HttpRequestResult | Promise or abortable HTTP result. |
| CreateWebComponentOptions | Options for createWebComponent. |
| WithArgMapped | Result type for Fn.withArg. |
| WithArgFn | Type signature for Fn.withArg. |
| DataLastFn | Dual-mode data-last function type. |
| DataLastMapped | Tuple mapped type for dataLast. |
| DataLastPredFn | Type signature for Fn.dataLastPred. |
| DataLastElFn | Type signature for Fn.dataLastEl. |
| FlexFn | Flexible first/last argument function type. |
| FlexMapped | Tuple mapped type for Fn.flex. |
| FlexElFn | Type signature for Fn.flexEl. |
| FormElement | Union type for form elements (input, select, textarea). |
| QueryValue | Valid URL query parameter value types. |
| QueryParams | Record of query parameters. |
| Ok | Success result type. |
| Err | Error result type. |
| Result | Union of Ok and Err types. |
| Setter | Setter function type. |
| EventSchema | Event schema for binding. |
| Refs | Record of element refs. |
| HttpMethod | HTTP method types. |
| HttpStatus | HTTP status code types. |
| HttpRequestInit | HTTP request configuration. |
| HttpResponse | HTTP response type. |
| HttpConfig | HTTP client configuration. |
| ComponentContext | Component context interface. |
| DomContext | Context type returned by domCtx. |
| ComponentInstance | Component instance type. |

Advanced Patterns

$3

This shows how the utilities compose to handle a common, real-world scenario.

`typescript
import { find, on, modify, Form, Http } from '@doeixd/dom';

const form = find('#login-form');
const submitBtn = find('button[type="submit"]', form);

on(form)('submit', async (e) => {
e.preventDefault();

// 1. Show loading state
modify(submitBtn)({ disabled: true, text: 'Logging in...' });

try {
// 2. Get form data and make API call
const data = Form.serialize(form);
const response = await Http.post('/api/login')(data)();

// 3. Show success state
modify(submitBtn)({ text: 'Success!' });
addClass(form)('form-success');

} catch (error) {
// 4. Handle errors
modify(submitBtn)({ disabled: false, text: 'Try Again' });
addClass(form)('form-error');
}
});
`

$3

For more complex UI, the component helper collects elements with data-ref attributes into a typed object, avoiding repeated find calls.

HTML:
`html


// Now access elements directly and with full type safety
modify(profile.name)({ text: 'Jane Doe' });
on(profile.editBtn)('click', () => openEditModal());
`

Advanced Features

The library includes powerful features for building modern, reactive UIs without a framework.

$3

VanJS-style element creation using Proxy-based property access. Cleaner syntax than el() with automatic SVG namespace handling.

`typescript
import { h, refs } from '@doeixd/dom';

// Create elements with clean syntax
const card = h.div({ class: { card: true } }, [
h.h2({ dataRef: 'title' }, ['Card Title']),
h.p({ dataRef: 'content' }, ['Card description']),
h.button({ dataRef: 'btn' }, ['Action'])
]);

// SVG elements get correct namespace automatically
const icon = h.svg({ attr: { viewBox: '0 0 24 24', width: '24', height: '24' } }, [
h.path({ attr: { d: 'M12 2L2 12h3v8h5v-6h4v6h5v-8h3z', fill: 'currentColor' } })
]);

// Extract refs for type-safe access
const { title, content, btn } = refs(card);
title.textContent = 'Updated Title';
`

When to use:
- Building declarative UI hierarchies
- Creating SVG graphics (automatic namespace)
- Component templates with viewRefs()

📖 Full Documentation

$3

Create reusable component templates with automatic ref extraction and smart update methods.

`typescript
import { viewRefs, h } from '@doeixd/dom';

// Define typed template
interface CardRefs {
title: HTMLElement;
content: HTMLElement;
button: HTMLElement;
}

const Card = viewRefs(({ refs }) =>
h.div({ class: { card: true } }, [
h.h2({ dataRef: 'title' }),
h.p({ dataRef: 'content' }),
h.button({ dataRef: 'button' }, ['Click'])
])
);

// Create instances with full type safety
const { element, refs, updateRefs, bind } = Card({
className: 'featured-card'
});

// Smart updates handle strings, numbers, and ElementProps
updateRefs({
title: 'Card Title',
content: 'Description text',
button: { text: 'Buy Now', class: { primary: true } }
});

// Get setter functions for individual refs
const setTitle = bind('title');
setTitle('Updated Title');

document.body.appendChild(element);
`

When to use:
- Reusable component patterns
- Type-safe ref access
- Dynamic UI that needs frequent updates

📖 Full Documentation

$3

Efficient DOM rendering for dynamic collections with three reconciliation strategies.

`typescript
import { List, h } from '@doeixd/dom';

interface Todo {
id: number;
text: string;
done: boolean;
}

const container = document.querySelector('#todos');

// Keyed mode for efficient updates
const list = List(container, {
key: todo => todo.id, // Enables smart diffing
render: (todo) => h.li({
class: { done: todo.done }
}, [
h.input({ attr: { type: 'checkbox', checked: todo.done } }),
h.span({}, [todo.text])
]),
update: (el, todo) => {
// Optional: efficient update without re-rendering
el.classList.toggle('done', todo.done);
}
});

// Rich API for list manipulation
list.set([
{ id: 1, text: 'Buy groceries', done: false },
{ id: 2, text: 'Walk dog', done: true }
]);

list.append([{ id: 3, text: 'Call mom', done: false }]);
list.remove(todo => todo.done); // Remove completed items
`

Three modes:
- Default: Simple blow-away (fast for small lists)
- Keyed: Efficient diffing with key function (reuses elements)
- Custom: User-provided reconciliation (e.g., morphdom)

📖 Full Documentation

$3

Schema-based binding between data and DOM with automatic dirty checking.

`typescript
import { createBinder, bind, refs, h } from '@doeixd/dom';

const form = h.form({}, [
h.input({ dataRef: 'nameInput', attr: { type: 'text' } }),
h.input({ dataRef: 'emailInput', attr: { type: 'email' } }),
h.button({ dataRef: 'submitBtn' }, ['Submit']),
h.div({ dataRef: 'errorMsg', class: { error: true } })
]);

const formRefs = refs(form);

// Create binder with schema
const ui = createBinder(formRefs, {
nameInput: bind.value,
emailInput: bind.value,
submitBtn: (el) => bind.prop('disabled', el),
errorMsg: bind.text
});

// Update UI declaratively
ui({
nameInput: 'John Doe',
emailInput: 'john@example.com',
submitBtn: false,
errorMsg: ''
});

// Individual setters for event handlers
ui.set.errorMsg('Invalid email address');

// Batch updates
ui.batch(() => {
ui({ submitBtn: true });
ui({ errorMsg: 'Submitting...' });
});
`

Bind primitives:
- bind.text - Text content
- bind.html - Inner HTML
- bind.value - Input values (with dirty checking)
- bind.prop() - Element properties (disabled, checked, etc.)
- bind.classes - Multiple class toggles
- bind.show - Show/hide elements
- bind.attr() - HTML attributes
- bind.toggle() - Single class toggle

📖 Full Documentation

$3

Combining all features for a complete reactive UI:

`typescript
import { h, viewRefs, List, createBinder, bind, refs } from '@doeixd/dom';

// 1. Define component template
interface TodoRefs {
checkbox: HTMLElement;
text: HTMLElement;
deleteBtn: HTMLElement;
}

const TodoItem = viewRefs(({ refs }) =>
h.li({ class: { 'todo-item': true } }, [
h.input({ dataRef: 'checkbox', attr: { type: 'checkbox' } }),
h.span({ dataRef: 'text' }),
h.button({ dataRef: 'deleteBtn' }, ['×'])
])
);

// 2. Create form with binder
const form = h.div({ class: { 'todo-app': true } }, [
h.input({ dataRef: 'input', attr: { type: 'text', placeholder: 'Add todo...' } }),
h.button({ dataRef: 'addBtn' }, ['Add']),
h.ul({ dataRef: 'list' })
]);

const { input, addBtn, list } = refs(form);

const formUI = createBinder({ input, addBtn }, {
input: bind.value,
addBtn: (el) => bind.prop('disabled', el)
});

// 3. Create reactive list
interface Todo {
id: number;
text: string;
done: boolean;
}

let todos: Todo[] = [];

const todoList = List(list, {
key: todo => todo.id,
render: (todo) => {
const { element, refs } = TodoItem();
const ui = createBinder(refs, {
checkbox: (el) => bind.prop('checked', el),
text: bind.text
});

ui({ checkbox: todo.done, text: todo.text });

refs.checkbox.addEventListener('change', () => {
todo.done = (refs.checkbox as HTMLInputElement).checked;
todos = [...todos]; // Trigger re-render
todoList.set(todos);
});

refs.deleteBtn.onclick = () => {
todos = todos.filter(t => t.id !== todo.id);
todoList.set(todos);
};

return element;
}
});

// 4. Add todo handler
addBtn?.addEventListener('click', () => {
const text = (input as HTMLInputElement)?.value.trim();
if (text) {
todos.push({ id: Date.now(), text, done: false });
todoList.set(todos);
formUI({ input: '' });
}
});

document.body.appendChild(form);
`

Troubleshooting & Common Patterns

$3

1. Null Safety is Built-in
All functions handle null/undefined gracefully. You don't need to check if elements exist:

`typescript
// This is safe - no errors even if button doesn't exist
const btn = find(document)('.missing-button'); // null
modify(btn)({ text: 'Hello' }); // Does nothing, returns null
on(btn)('click', handler); // Returns no-op cleanup function
`

2. Curried Functions Support Two Styles

Most functions work in both imperative and curried style:

`typescript
// Imperative (all args at once)
modify(element, { text: 'Hello' });
css(element, { color: 'red' });

// Curried (target first, config later)
modify(element)({ text: 'Hello' });
css(element)({ color: 'red' });

// Curried style enables composition
const updateButton = modify(button);
updateButton({ text: 'Loading...' });
updateButton({ text: 'Done!' });
`

3. Class Objects Use Boolean Toggles

When using the class property in modify, use boolean values to toggle classes:

`typescript
// Correct ✓
modify(el)({
class: {
active: true, // Add 'active'
disabled: false, // Remove 'disabled'
loading: isLoading // Conditional
}
});

// Wrong ✗
modify(el)({ class: 'active disabled' }); // This won't work
`

4. Dataset Auto-Converts to Kebab-Case

Data attributes are automatically converted:

`typescript
modify(el)({
dataset: {
userId: 123, // becomes data-user-id="123"
isActive: true, // becomes data-is-active="true"
apiEndpoint: '/api' // becomes data-api-endpoint="/api"
}
});
`

5. Event Listeners Return Cleanup Functions

Always store and call cleanup functions to prevent memory leaks:

`typescript
// Store the cleanup
const unsub = on(button)('click', handler);

// Later, when component unmounts or modal closes
unsub(); // Removes the listener

// For multiple listeners
const cleanups = [
on(btn1)('click', h1),
on(btn2)('click', h2),
on(input)('input', h3)
];

// Clean up all at once
cleanups.forEach(fn => fn());
`

6. Type Inference Works Best with Literals

Use string literals (not variables) for selectors to get automatic type inference:

`typescript
// Good: Type is inferred as HTMLButtonElement | null
const btn = find(document)('button');

// Less ideal: Type is generic HTMLElement | null
const selector = 'button';
const btn2 = find(document)(selector);

// Solution: Use type annotation
const btn3 = find(document)<'button'>(selector);
// Or: Type assertion
const btn4 = find(document)(selector) as HTMLButtonElement | null;
`

7. onDelegated Has Different Signature

Event delegation requires selector first, then event:

`typescript
// Regular event listener
on(button)('click', handler);

// Delegated listener (note the extra selector call)
onDelegated(container)('button')('click', handler);
// ^^^^^^^^ selector for matching children
`

8. HTML Templates Don't Auto-Escape

The html function uses innerHTML, so be careful with user input:

`typescript
// Unsafe with user input ✗
const userInput = getUserInput();
const div = html

// Safe alternatives ✓
const div = el('div')({ text: userInput }); // Uses innerText
modify(div)({ text: userInput }); // Uses innerText
`

$3

Pattern 1: Conditional Element Updates

`typescript
// Update multiple elements based on state
const updateUI = (state: AppState) => {
modify(submitBtn)({
text: state.loading ? 'Loading...' : 'Submit',
disabled: state.loading,
class: { loading: state.loading, error: state.error }
});

if (state.error) {
modify(errorMsg)({ text: state.error, style: { display: 'block' } });
} else {
modify(errorMsg)({ style: { display: 'none' } });
}
};
`

Pattern 2: Batch Operations on Collections

`typescript
// Apply same operation to multiple elements
const buttons = findAll(document)('button');

// Imperative style
buttons.forEach(btn => modify(btn)({ disabled: true }));

// Or use the $$ wrapper
$$(buttons).forEach(btn => {
modify(btn)({ disabled: true });
cls.add(btn)('disabled-state');
});
`

Pattern 3: Cleanup on Component Unmount

`typescript
class MyComponent {
private cleanups: Unsubscribe[] = [];

mount(root: HTMLElement) {
const btn = find(root)('button');

// Store all cleanup functions
this.cleanups.push(
on(btn)('click', this.handleClick),
on(window)('resize', this.handleResize),
Local.watch('user')(this.handleUserChange)
);
}

unmount() {
// Clean up all listeners at once
this.cleanups.forEach(fn => fn());
this.cleanups = [];
}
}
`

Pattern 4: Loading States with tempStyle

`typescript
async function fetchData() {
const btn = find(document)('button');

// Apply temporary loading styles
const revert = tempStyle(btn)({
opacity: '0.6',
pointerEvents: 'none',
cursor: 'wait'
});

try {
const data = await Http.get('/api/data');
return data;
} finally {
revert(); // Always restore original styles
}
}
`

Pattern 5: Form Validation with Input Watchers

`typescript
const emailInput = find(document)('#email');

Input.watchDebounced(emailInput)(async (value) => {
// Don't validate if empty
if (!value) {
Input.validate(emailInput)('');
return;
}

// Async validation
const isValid = await checkEmailAvailable(value);
Input.validate(emailInput)(
isValid ? '' : 'Email already taken'
);
}, 300);
`

Pattern 6: Modal with Focus Trap and Cleanup

`typescript
function openModal() {
const modal = find(document)('.modal');
const closeBtn = find(modal)('.close-btn');

modify(modal)({ style: { display: 'block' } });
cls.add(document.body)('modal-open');

// Trap focus within modal
const releaseFocus = Focus.trap(modal);

// Close on button or escape
const cleanups = [
releaseFocus,
on(closeBtn)('click', closeModal),
on(document)('keydown', (e) => {
if (Key.matches(e, 'Escape')) closeModal();
})
];

function closeModal() {
modify(modal)({ style: { display: 'none' } });
cls.remove(document.body)('modal-open');
cleanups.forEach(fn => fn());
}
}
`

Pattern 7: Optimistic UI Updates

`typescript
async function deleteItem(itemId: string) {
const item = find(document)([data-id="${itemId}"]);

// Optimistic: Remove from UI immediately
const parent = item?.parentElement;
const nextSibling = item?.nextSibling;
remove(item);

try {
await Http.delete(/api/items/${itemId})({});
} catch (error) {
// Rollback: Restore item on error
if (parent && item) {
if (nextSibling) {
before(nextSibling)(item);
} else {
append(parent)(item);
}
}
alert('Failed to delete item');
}
}
`

Pattern 8: Infinite Scroll with Intersection Observer

`typescript
const container = find(document)('.infinite-scroll');
const sentinel = find(container)('.sentinel');

let page = 1;
const observer = new IntersectionObserver(async (entries) => {
if (entries[0].isIntersecting) {
const items = await fetchPage(page++);
const elements = items.map(item =>
el('div')({ class: { item: true } })([item.name])
);
append(container)(...elements);
}
});

if (sentinel) observer.observe(sentinel);
`

Pattern 9: Component Pattern with Refs

`typescript
interface ProfileCardRefs {
name: HTMLHeadingElement;
email: HTMLParagraphElement;
avatar: HTMLImageElement;
editBtn: HTMLButtonElement;
}

function createProfileCard(userData: User) {
const card = component('#profile-card');

// Type-safe access to all refs
modify(card.name)({ text: userData.name });
modify(card.email)({ text: userData.email });
modify(card.avatar)({ attr: { src: userData.avatarUrl } });

return on(card.editBtn)('click', () => editProfile(userData.id));
}
`

Pattern 10: State Machine with cycleClass

`typescript
const button = find(document)('.toggle-btn');

// Define state classes
const states = ['idle', 'loading', 'success', 'error'];
const nextState = cycleClass(button)(states);

// Initial state
cls.add(button)('idle');

async function handleAction() {
nextState(); // idle -> loading

try {
await performAction();
nextState(); // loading -> success

setTimeout(() => {
nextState(); // success -> error
nextState(); // error -> idle (cycles back)
}, 2000);
} catch (err) {
nextState(); // loading -> success
nextState(); // success -> error
}
}
``

License

MIT