Weave

A modern TypeScript reactive library that makes any existing HTML reactive without compilation, custom attributes, or Virtual DOM.

Features

• Zero Markup Pollution: No custom attributes in HTML - all configuration is in pure TypeScript
• Progressive Enhancement: Start simple, add complexity only when needed
• Bidirectional Sync: model() creates automatic two-way binding between inputs and refs
• Type Safety: Full TypeScript strict mode with complete type inference
• Performance First: Lazy resolution, surgical observers, automatic batching
• Store System: Global reactive state management with actions and computed properties
• Lifecycle Hooks: onInit, onUpdate, onDestroy for complete control
• Advanced Features: Promise integration, template rendering, head management, page transitions
• teleport(): Move elements to any DOM target (modals, tooltips)
• dispatch(): Emit custom events between components without a shared store
• $refs(): Access DOM elements by weave-ref attribute without CSS selectors
• nextTick(): Execute code after the current reactive cycle
• [weave-cloak]: Hide elements until Weave is ready, no flash of un-initialized content

Installation

npm / yarn

npm install @ludoows/weave

yarn add @ludoows/weave

CDN

<!-- unpkg -->
<script src="https://unpkg.com/@ludoows/weave"></script>

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@ludoows/weave"></script>

Quick Start

import { weave } from '@ludoows/weave';

weave('#app', ({ $, ref }) => {
  const count = ref(0);
  
  $('#counter').text(() => `Count: ${count.value}`);
  $('#increment').on('click', () => count.value++);
});

Documentation

• Getting Started - Installation, basic usage, and new APIs
• Reactive State In Depth - ref, computed, watch, memo, batch and how reactivity works
• Store System - Global state, actions, plugins and store groups
• Extensibility - Macro system: context, NodeRef and collection macros
• Examples - Common use cases and patterns
• Performance - Best practices for performance
• Security - Security best practices
• Browser Compatibility - Supported browsers and features
• Troubleshooting - Common issues and solutions

Core Concepts

Reactive State with ref()

weave('#app', ({ ref }) => {
  const name = ref('World');
  const count = ref(0);
  
  // Refs are reactive - changes trigger updates
  name.value = 'Weave';
  count.value++;
});

Computed Properties

weave('#app', ({ ref, computed }) => {
  const firstName = ref('John');
  const lastName = ref('Doe');
  
  computed('fullName', () => `${firstName.value} ${lastName.value}`);
  
  // Access via proxy
  console.log(instance.fullName); // "John Doe"
});

DOM Directives

weave('#app', ({ $, ref }) => {
  const message = ref('Hello');
  const isVisible = ref(true);
  
  $('#output').text(() => message.value);
  $('#container').show(() => isVisible.value);
  $('#title').addClass('active');
  $('#input').bind('value', () => message.value);
});

Store System

import { createStore } from '@ludoows/weave';

const counterStore = createStore('counter', ({ state, action, computed }) => {
  state({ count: 0 });
  
  computed('double', (s) => s.count * 2);
  
  action('increment', (s) => s.count++);
  action('decrement', (s) => s.count--);
});

weave('#app', ({ store }) => {
  store(counterStore);
  
  // Access store state
  console.log(counterStore.state.count);
  
  // Call actions
  counterStore.actions.increment();
});

Lifecycle Hooks

weave('#app', ({ ref, onInit, onUpdate, onDestroy, cleanup }) => {
  const data = ref(null);
  
  onInit(async (state) => {
    // Initialize after all refs/computed are resolved
    data.value = await fetchData();
  });
  
  onUpdate((newState, oldState) => {
    // Called after every state change
    console.log('State changed:', newState);
  });
  
  onDestroy((state) => {
    // Called before destruction
    console.log('Cleaning up');
  });
  
  cleanup(() => {
    // Release resources
  });
});

Browser Compatibility

Weave requires modern browser features:

• Proxy (ES2015)
• MutationObserver
• AbortController (for promise cancellation)

Supported browsers:

• Chrome/Edge 49+
• Firefox 18+
• Safari 10+

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build
npm run build

# Development mode
npm run dev

Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

• Development setup and workflow
• Coding standards and best practices
• Testing guidelines
• Commit message conventions
• Pull request process

We appreciate all contributions, from bug reports to new features!

License

MIT