npm package: @petit-kit/template
Description: A lightweight virtual DOM library with template literal support for building reactive web applications.
Author: @petitssoldats
Latest version: 0.0.2

# @petit-kit/template

A lightweight virtual DOM library with template literal support for building reactive web applications.

## Features

- **Lightweight Virtual DOM**: Minimal virtual DOM implementation for efficient DOM updates
- **Template Literal Support**: Use HTML template literals for intuitive component creation
- **Event Handling**: Built-in event listener management
- **Web Component Support**: Native support for custom elements
- **SVG Support**: Full SVG element rendering
- **Controlled Inputs**: Automatic handling of form input state
- **Key-based Updates**: Efficient list rendering with key support
- **Mounted Class Support**: Add CSS classes after DOM insertion

## Installation

```bash
npm install @petit-kit/template
```

## Quick Start

```javascript
import { h, html, template } from '@petit-kit/template';

// Using hyperscript (h function)
const vnode = h('div', { class: 'container' }, 
  h('h1', null, 'Hello World'),
  h('p', null, 'This is a paragraph')
);

// Using template literals
const vnode = html`
  <div class="container">
    <h1>Hello World</h1>
    <p>This is a paragraph</p>
  </div>
`;

// Render to DOM
const container = document.getElementById('app');
const update = template(container);
update(vnode);
```

## API Reference

### `h(type, props, ...children)`

Creates a virtual DOM node (hyperscript).

```javascript
h('div', { class: 'box', id: 'main' }, 'Hello', h('span', null, 'World'))
```

**Parameters:**
- `type` (string): HTML tag name or component name
- `props` (object): Element properties and attributes
- `...children` (any): Child nodes (strings, numbers, or other vnodes)

### `html(strings, ...values)`

Creates virtual DOM nodes from template literals.

```javascript
const name = 'World';
const vnode = html`
  <div class="greeting">
    <h1>Hello ${name}!</h1>
    <button onclick=${() => alert('Clicked!')}>Click me</button>
  </div>
`;
```

**Features:**
- Automatic event binding with `onclick`, `onchange`, etc.
- Expression interpolation
- Array flattening
- Boolean attribute handling

### `render(vnode, parentNS)`

Renders a virtual DOM node to a real DOM element.

```javascript
const vnode = h('div', null, 'Hello');
const element = render(vnode);
document.body.appendChild(element);
```

### `template(container)`

Creates a template function for efficient DOM updates.

```javascript
const container = document.getElementById('app');
const update = template(container);

// Initial render
update(h('div', null, 'Hello'));

// Update with new content
update(h('div', null, 'Updated content'));
```

**Returns:** A function that efficiently updates the container with new virtual DOM nodes.

### `updateElement(parent, next, prev, index)`

Updates a specific child element in the DOM.

```javascript
const parent = document.getElementById('list');
const next = h('li', null, 'New item');
const prev = h('li', null, 'Old item');
updateElement(parent, next, prev, 0);
```

## Event Handling

### Automatic Event Binding

```javascript
const vnode = html`
  <button onclick=${() => console.log('clicked')}>
    Click me
  </button>
`;
```

### Manual Event Binding

```javascript
const vnode = h('button', {
  onclick: () => console.log('clicked')
}, 'Click me');
```

## Web Component Support

```javascript
// Custom element
class MyElement extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }
}

customElements.define('my-element', MyElement);

// Usage in template
const vnode = html`
  <my-element>
    <span>Custom content</span>
  </my-element>
`;
```

## SVG Support

```javascript
const svg = html`
  <svg width="100" height="100">
    <circle cx="50" cy="50" r="40" fill="red" />
    <rect x="10" y="10" width="80" height="80" fill="none" stroke="black" />
  </svg>
`;
```

## Controlled Inputs

```javascript
let value = '';

const input = h('input', {
  value: value,
  oninput: (e) => {
    value = e.target.value;
    update(input); // Re-render with new value
  }
});
```

## Key-based Updates

```javascript
const items = ['A', 'B', 'C'];

const list = html`
  <ul>
    ${items.map((item, index) => 
      html`<li key=${index}>${item}</li>`
    )}
  </ul>
`;
```

## Mounted Class Support

Add CSS classes after DOM insertion:

```javascript
const vnode = h('div', { 
  mountedclass: 'fade-in' 
}, 'This will get the fade-in class after mounting');

// CSS
.fade-in {
  animation: fadeIn 0.3s ease-in;
}
```

## Advanced Usage

### Conditional Rendering

```javascript
const showMessage = true;

const vnode = html`
  <div>
    ${showMessage ? html`<p>Message is visible</p>` : null}
  </div>
`;
```

### List Rendering

```javascript
const todos = [
  { id: 1, text: 'Learn petit-kit', done: false },
  { id: 2, text: 'Build app', done: true }
];

const todoList = html`
  <ul>
    ${todos.map(todo => 
      html`<li key=${todo.id} class=${todo.done ? 'done' : ''}>
        ${todo.text}
      </li>`
    )}
  </ul>
`;
```

### Component Pattern

```javascript
function Button({ text, onClick, disabled = false }) {
  return h('button', {
    onclick: onClick,
    disabled: disabled,
    class: 'btn'
  }, text);
}

const app = html`
  <div>
    ${Button({ text: 'Click me', onClick: () => alert('Hello!') })}
    ${Button({ text: 'Disabled', disabled: true })}
  </div>
`;
```

## Performance Tips

1. **Use keys for lists**: Always provide unique keys for list items
2. **Avoid inline functions**: Define event handlers outside the render function
3. **Batch updates**: Use the template function for efficient updates
4. **Minimize DOM queries**: Cache DOM elements when possible

## Browser Support

- Modern browsers with ES6+ support
- IE11+ (with polyfills for template literals)

## License

MIT © [@petitssoldats](https://github.com/petitssoldats)