symbiotic/README.md

A lightweight DOM attachment framework

# Symbiote

A lightweight, high-performance DOM attachment framework that automatically attaches JavaScript behaviors to HTML elements based on CSS selectors. Symbiote makes your HTML "smart" without writing repetitive JavaScript.

## 🚀 Features

- **🎯 Automatic DOM Attachment**: Attach behaviors to elements using CSS selectors
- **⚡ High Performance**: Sub-millisecond event handling, 0ms initialization
- **🔄 Dynamic DOM Support**: Automatically handles added/removed elements
- **🎨 Template Rendering**: Built-in template system with content rendering
- **🌐 Global Behaviors**: Define reusable behaviors across your application
- **📦 Batching System**: Queue DOM operations for optimal performance
- **🧠 Memory Efficient**: Zero memory leaks, automatic cleanup
- **🎭 CSS Selector Support**: Classes, IDs, attributes, complex selectors
- **🔧 Error Handling**: Graceful degradation, comprehensive error logging
- **📱 Browser Compatible**: Works in all modern browsers
- **📏 Lightweight**: ~2KB minified, zero dependencies

## 📦 Installation

```bash
npm install symbiotic
```

## 🎯 Quick Start

### Basic Usage

```javascript
import createSymbiote from 'symbiotic';

const symbiote = createSymbiote({
  '.js-button': (el) => {
    el.addEventListener('click', () => console.log('Button clicked!'));
  },
  '.js-modal': (el) => {
    el.addEventListener('click', () => el.style.display = 'none');
  }
});

// Automatically waits for DOM and attaches behaviors
await symbiote.attach();
```

### HTML Structure

```html
<button class="js-button">Click me!</button>
<div class="js-modal">Modal content</div>
```

## 🎨 CSS Selector Support

Symbiote supports comprehensive CSS selectors:

```javascript
const symbiote = createSymbiote({
  // Class selectors
  '.js-button': (el) => { /* button behavior */ },
  
  // ID selectors
  '#main-content': (el) => { /* main content behavior */ },
  
  // Tag selectors
  'button': (el) => { /* all buttons */ },
  
  // Attribute selectors
  '[data-action="save"]': (el) => { /* save buttons */ },
  '[disabled]': (el) => { /* disabled elements */ },
  
  // Complex selectors
  '.header > .close-btn': (el) => { /* close buttons in header */ },
  '.parent .child': (el) => { /* child elements */ },
  
  // Universal selector
  '*': (el) => { /* all elements */ }
});
```

## 🔄 Template Rendering System

Symbiote includes a powerful template rendering system:

### HTML Template

```html
<template class="js-user-card">
  <div class="card">
    <h3>John Doe</h3>
    <p>john@example.com</p>
    <button class="js-edit">Edit</button>
  </div>
</template>
```

### JavaScript Setup

```javascript
const symbiote = createSymbiote({
  '.js-user-card': (renderFn, batch) => {
    // renderFn renders the template element's content after the template
    // and passes setup functions for the newly rendered elements
    renderFn((el) => {
      // This setup function runs on each newly rendered element
      // el is the rendered element (not the template)
      el.style.border = '1px solid #ccc';
      el.addEventListener('click', () => {
        console.log('User card clicked!');
      });
    }); // Uses template.innerHTML as content source
  },
  
  '.js-edit': (el) => {
    el.addEventListener('click', () => {
      console.log('Edit button clicked!');
    });
  }
});
```

### How Template Rendering Works

1. **Template Element**: Contains the content to be rendered
2. **renderFn(setupFunction)**: Renders the template's content after the template element
3. **Content Source**: Uses `template.content`
4. **Setup Function**: The function passed to `renderFn` runs on each newly rendered element
5. **Element Parameter**: The setup function receives the rendered element (not the template)

## 🌐 Global Behaviors

Define reusable behaviors that work across your entire application:

```javascript
import { defineSetup } from 'symbiotic';

// Define global behaviors
defineSetup('.js-tooltip', (el) => {
  el.addEventListener('mouseenter', () => showTooltip(el));
  el.addEventListener('mouseleave', () => hideTooltip(el));
});

defineSetup('[data-confirm]', (el) => {
  el.addEventListener('click', (e) => {
    if (!confirm(el.dataset.confirm)) {
      e.preventDefault();
    }
  });
});

// All existing and future Symbiote instances will use these behaviors
const symbiote = createSymbiote({
  '.js-button': (el) => {
    // This button will also get tooltip behavior if it has js-tooltip class
  }
});
```

## 📦 Batching System

Queue DOM operations for optimal performance:

```javascript
const symbiote = createSymbiote({
  '.js-batch': (el, batch) => {
    // batch queues DOM operations for optimal performance
    batch(() => {
      el.style.color = 'red';
      el.style.fontSize = '18px';
      el.textContent = 'Updated!';
    });
    
    // Returns a Promise that resolves when operations complete
    batch(() => {
      // More DOM operations
    }).then(() => {
      console.log('Batch operations completed!');
    });
  }
});
```

## 🔧 Advanced Usage

### Cleanup Functions

Return cleanup functions to handle element removal:

```javascript
const symbiote = createSymbiote({
  '.js-component': (el) => {
    const handler = () => console.log('Component clicked');
    el.addEventListener('click', handler);
    
    // Return cleanup function
    return () => {
      el.removeEventListener('click', handler);
    };
  }
});
```

### Custom Root Element

Attach to a specific part of the DOM:

```javascript
const symbiote = createSymbiote({
  '.js-widget': (el) => { /* widget behavior */ }
});

// Only attach to elements within #app
await symbiote.attach(document.getElementById('app'));
```

### Update Method

Check for new setup functions on existing elements:

```javascript
const symbiote = createSymbiote({
  '.js-button': (el) => { /* button behavior */ }
});

await symbiote.attach();

// Later, define new behaviors
defineSetup('.js-new-feature', (el) => { /* new behavior */ });

// Update existing elements to get new behaviors
await symbiote.update();
```

## 📊 Performance

Symbiote is designed for high performance:

- **Initialization**: 0ms (instantaneous)
- **DOM Attachment**: 0ms for 50 elements
- **Event Handling**: 0.2-0.3ms per event
- **Memory Usage**: Zero memory leaks
- **Stress Test**: 100 events in 32ms

### Browser Performance Test

Run the included browser performance test:

```bash
npm run test:browser
```

This opens an interactive test suite that validates performance in real browser environments.

## 🧪 Testing

Symbiote includes comprehensive testing:

```bash
# Run all tests
npm test

# Run tests once
npm run test:run

# Run with coverage
npm run test:coverage

# Browser performance test
npm run test:browser
```

## 📚 API Reference

### `createSymbiote(setupFunctions)`

Creates a new Symbiote instance.

**Parameters:**
- `setupFunctions` (Object): Object mapping CSS selectors to setup functions

**Returns:**
- `Symbiote`: A Symbiote instance

### `symbiote.attach(root?)`

Attaches behaviors to the DOM.

**Parameters:**
- `root` (HTMLElement, optional): Root element to attach to. Defaults to `document.body`

**Returns:**
- `Promise<void>`: Resolves when attachment is complete

### `symbiote.update(root?)`

Updates existing elements with new setup functions.

**Parameters:**
- `root` (HTMLElement, optional): Root element to update. Defaults to `document.body`

**Returns:**
- `Promise<void>`: Resolves when update is complete

### `defineSetup(selector, setupFunction)`

Creates a global setup function.

**Parameters:**
- `selector` (string): CSS selector for the setup function
- `setupFunction` (function): Function to execute when elements match

**Returns:**
- `Object`: Object with `remove()` method to unregister the setup function

## 🎯 Examples

### Counter Component

```javascript
const symbiote = createSymbiote({
  '.js-counter': (el) => {
    let count = 0;
    el.addEventListener('click', () => {
      count++;
      el.textContent = `Clicked ${count} times`;
    });
  }
});

await symbiote.attach();
```

### Modal System

```javascript
const symbiote = createSymbiote({
  '.js-modal-trigger': (el) => {
    el.addEventListener('click', () => {
      const modal = document.querySelector('.js-modal');
      modal.style.display = 'block';
    });
  },
  '.js-modal-close': (el) => {
    el.addEventListener('click', () => {
      const modal = el.closest('.js-modal');
      modal.style.display = 'none';
    });
  }
});

await symbiote.attach();
```

### Form Validation

```javascript
const symbiote = createSymbiote({
  '.js-validate': (el) => {
    el.addEventListener('blur', () => {
      if (!el.value) {
        el.classList.add('error');
      } else {
        el.classList.remove('error');
      }
    });
  }
});

await symbiote.attach();
```

### Data Table

```javascript
const symbiote = createSymbiote({
  '.js-sort': (el) => {
    el.addEventListener('click', () => {
      const column = el.dataset.column;
      sortTable(column);
    });
  },
  '.js-filter': (el) => {
    el.addEventListener('input', () => {
      const value = el.value;
      filterTable(value);
    });
  }
});

await symbiote.attach();
```

## 🌍 Browser Support

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

## 📦 Build Outputs

Symbiote provides multiple build formats:

- **ES Modules**: `dist/symbiote.esm.js`
- **UMD**: `dist/symbiote.umd.js`
- **IIFE**: `dist/symbiote.iife.js`
- **Minified versions**: All formats include `.min.js` versions

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## 📄 License

MIT

---

**Symbiote** - Making HTML smart, one selector at a time! 🚀