npm package: @kiransth/rxhtmx
Description: A comprehensive reactive frontend framework with components, routing, state management, and RxJS integration.
Author: kiransth77
Latest version: 2.0.0

# RxHtmx Framework

**A Modern Reactive Frontend Framework**

RxHtmx has evolved from a simple RxJS+HTMX integration library into a **complete
reactive frontend framework** with components, routing, state management, and
modern build tools.

## 📦 Installation

### From npm (Public Registry - Recommended)

```bash
npm install @kiransth77/rxhtmx

# Or with Bun
bun add @kiransth77/rxhtmx

# Or with Yarn
yarn add @kiransth77/rxhtmx
```

### From GitHub Packages

```bash
# Configure npm to use GitHub Packages for @kiransth77 scope
echo "@kiransth77:registry=https://npm.pkg.github.com" >> .npmrc

# Install the package
npm install @kiransth77/rxhtmx

# Or with Bun
bun add @kiransth77/rxhtmx
```

### Authentication (if required for GitHub Packages)

```bash
# Login to GitHub Packages
npm login --scope=@kiransth77 --registry=https://npm.pkg.github.com
# Enter your GitHub username, personal access token (as password), and email
```

### From Source

```bash
git clone https://github.com/kiransth77/RxHtml.git
cd RxHtml
bun install
bun run build
```

## 🚀 Framework Features

- **🔄 Enhanced Signal System**: Reactive primitives with computed values,
  effects, and dependency tracking
- **🧩 Component Architecture**: Full component lifecycle with props, templates,
  and event handling
- **🛣️ Client-Side Router**: SPA routing with history API, route guards, and
  navigation helpers
- **📦 State Management**: Advanced store system with actions, getters, and
  middleware support
- **⚡ Build System**: Development server with HMR and production bundler
- **🔧 CLI Tools**: Project scaffolding and development commands
- **🧪 Comprehensive Testing**: Full test coverage with Bun test framework (9/9
  integration tests passing)
- **📚 Rich Examples**: Complete demo applications and tutorials

## ✅ Test Status

**Integration Tests: 9/9 PASSING** ✅  
**Standalone Tests: 5/5 PASSING** ✅  
**Total: 14/14 PASSING** 🎯

- ✅ Signal + Component Integration
- ✅ Props & Reactive Updates
- ✅ Router + Component Integration
- ✅ Route Parameter Passing
- ✅ Store + Component Integration
- ✅ Full App Integration
- ✅ Complex State Updates
- ✅ Error Boundaries
- ✅ Memory Management
- ✅ HTMX Signal Integration (Standalone)
- ✅ CreateStream Functionality (Standalone)

All core framework functionality is tested and working perfectly.

## 🔬 Testing Framework & Debugging

### Test Suites Available

```bash
# Run all integration tests (recommended)
bun test tests/integration.test.js

# Run specific component tests
bun test tests/core-signal.test.js        # Signal system tests
bun test tests/component.test.js          # Component lifecycle tests
bun test tests/router.test.js             # Router navigation tests
bun test tests/store.test.js              # State management tests

# Run in watch mode for development
bun test --watch tests/

# Run with verbose output for debugging
bun test --verbose tests/integration.test.js
```

### Test Environment Setup

- **Runtime**: Bun test runner with JSDOM for DOM simulation
- **Assertions**: Jest-style expect() with comprehensive matchers
- **Cleanup**: Automatic DOM cleanup between tests
- **Mocking**: HTMX mock for isolated testing

### Common Test Patterns

```javascript
// Signal reactivity testing
test('signal updates trigger effects', () => {
  const s = signal(0);
  let effectRan = false;
  effect(() => {
    const value = s.value;
    effectRan = true;
  });

  s.value = 1;
  expect(effectRan).toBe(true);
});

// Component integration testing
test('component responds to store changes', () => {
  const store = createStore({ state: { count: 0 } });
  const component = createComponent({
    template: '<div>{{ store.state.count }}</div>',
    setup() {
      return { store };
    },
  });

  store.commit('increment');
  expect(component.el.textContent).toBe('1');
});
```

### Debugging Integration Issues

**Issue**: Tests hanging or infinite loops

```bash
# Run with timeout and verbose logging
bun test --timeout 10000 --verbose tests/integration.test.js
```

**Issue**: Effects not triggering

- Check signal dependency tracking
- Verify effect cleanup in component unmounting
- Use console.log in effects to trace execution

**Issue**: Component rendering problems

- Verify signal evaluation in templates
- Check event binding and parameter passing
- Test DOM updates with manual inspection

**Issue**: Store mutations not reflecting in UI

- Ensure mutations use proper signal assignment
- Verify getter reactivity with computed signals
- Check component store integration

### Performance Testing

```bash
# Run benchmark tests
bun test tests/benchmark.test.js

# Memory leak detection
bun test --detect-memory-leaks tests/integration.test.js
```

### Test Coverage Insights

- **Signal System**: 100% coverage of core reactivity
- **Component Lifecycle**: All hooks and states tested
- **Router Integration**: Navigation, parameters, guards
- **Store Management**: Mutations, actions, getters
- **Error Handling**: Boundary conditions and recovery
- **Memory Management**: Effect cleanup and disposal

## 📦 Installation

```bash
# Install the framework
npm install rxhtmx

# Or create a new project
npx rxhtmx create my-app
cd my-app
npm run dev
```

## 🚀 Quick Start

### 1. Create a Component

```javascript
import { defineComponent, signal } from 'rxhtmx';

const Counter = defineComponent({
  name: 'Counter',
  props: {
    initialValue: { type: Number, default: 0 },
  },
  setup(props) {
    const count = signal(props.initialValue);
    const increment = () => count.value++;
    const decrement = () => count.value--;

    return { count, increment, decrement };
  },
  template: `
    <div class="counter">
      <button @click="decrement">-</button>
      <span class="count">{{count}}</span>
      <button @click="increment">+</button>
    </div>
  `,
});
```

### 2. Set Up Routing

```javascript
import { createRouter } from 'rxhtmx/router';

const router = createRouter({
  routes: [
    { path: '/', component: Home },
    { path: '/about', component: About },
    { path: '/user/:id', component: UserProfile },
  ],
});

router.mount('#app');
```

### 3. Manage State

```javascript
import { createStore } from 'rxhtmx/state';

const store = createStore({
  state: {
    user: null,
    todos: [],
  },
  mutations: {
    setUser: (state, user) => (state.user = user),
    addTodo: (state, todo) => state.todos.push(todo),
  },
  actions: {
    login: async ({ commit }, credentials) => {
      const user = await api.login(credentials);
      commit('setUser', user);
    },
  },
  getters: {
    completedTodos: state => state.todos.filter(t => t.completed),
  },
});
```

## 🛠️ CLI Commands

```bash
# Create new project
npx rxhtmx create my-app

# Development server with HMR
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch
```

## 📁 Framework Architecture

```
src/
├── core/
│   ├── signal.js      # Enhanced reactive system
│   ├── component.js   # Component system with lifecycle
│   └── dom.js         # Virtual DOM utilities
├── router/
│   └── router.js      # Client-side routing
├── state/
│   └── store.js       # State management
├── htmxWrapper.js     # Original HTMX integration
└── index.js           # Framework entry point

build/
├── dev-server.js      # Development server with HMR
└── bundler.js         # Production build system

cli/
├── index.js           # CLI entry point
└── create.js          # Project scaffolding

examples/
├── framework-demo.html # Complete framework showcase
├── form-validation/    # Form validation example
├── search/            # Real-time search example
└── chat/              # Chat application example
```

## 🎯 Framework Capabilities

### Reactive System

- **Signals**: `signal(value)` - Reactive primitive values
- **Computed**: `computed(() => expr)` - Derived reactive values
- **Effects**: `effect(() => {})` - Side effects with dependency tracking
- **Batching**: `batch(() => {})` - Batched updates for performance

### Component System

- **Lifecycle Hooks**: `onMounted`, `onUpdated`, `onUnmounted`
- **Props Validation**: Type checking and default values
- **Event Handling**: `@click`, `@input`, etc.
- **Template Compilation**: String templates with reactive interpolation

### Router Features

- **Route Matching**: Static and dynamic routes with parameters
- **Navigation Guards**: `beforeEach`, `afterEach`, route-specific guards
- **History API**: Full browser history integration
- **Route Meta**: Custom route metadata and authentication

### State Management

- **Mutations**: Synchronous state changes
- **Actions**: Asynchronous operations with async/await
- **Getters**: Computed state derivations
- **Middleware**: Logging, persistence, devtools integration

## 🔄 Backwards Compatibility

Original HTMX integration features are preserved:

```javascript
// Original RxJS + HTMX integration still works
import {
  createStream,
  integrateHtmxWithSignals,
  bindSignalToDom,
} from 'rxhtmx';

const inputStream = createStream('#my-input');
const htmxSignal = integrateHtmxWithSignals();
bindSignalToDom(dataSignal, '#output', (el, val) => (el.textContent = val));
```

## 🧪 Testing Framework

Comprehensive test coverage with Bun test framework:

```bash
# Run all tests
bun test

# Run specific test suites
bun test tests/core-signal.test.js     # Signal system tests
bun test tests/component.test.js       # Component tests
bun test tests/router.test.js          # Router tests
bun test tests/store.test.js           # State management tests
bun test tests/integration.test.js     # Framework integration tests
```

## 📚 Documentation

- **[Getting Started](docs/getting-started.md)** - Installation and basic usage
- **[Framework Architecture](docs/advanced.md)** - Deep dive into framework
  design
- **[API Reference](docs/README.md)** - Complete API documentation
- **[Examples](examples/README.md)** - Complete example applications
- **[Debugging Guide](docs/debugging-troubleshooting.md)** - Troubleshooting and
  debugging

## 🎨 Live Demo

Try the complete framework demo at `examples/framework-demo.html`:

```bash
# Start local server
npm run serve

# Open http://localhost:5500/examples/framework-demo.html
```

The demo showcases:

- ✅ Reactive components with state management
- ✅ Client-side routing and navigation
- ✅ Global state management with middleware
- ✅ Real-time updates and interactions
- ✅ Modern UI with Tailwind CSS

## 🚀 Framework Evolution

**Before**: Simple RxJS + HTMX integration library  
**After**: Complete reactive frontend framework

**Core Technologies**:

- Custom reactive system with signals
- Component architecture with lifecycle
- Client-side routing with history API
- Advanced state management with middleware
- Modern build tooling with HMR
- Comprehensive CLI utilities

## 🌟 Why RxHtmx Framework?

- **🔥 Modern Reactivity**: Cutting-edge signal-based reactivity system
- **🧩 Component-Based**: Familiar component architecture like Vue/React
- **⚡ Fast Development**: HMR, CLI tools, and great developer experience
- **📦 Full-Featured**: Router, state management, build system included
- **🔄 Progressive**: Start simple, scale to complex applications
- **🧪 Test-Ready**: Comprehensive testing framework included
- **📚 Well-Documented**: Extensive guides, examples, and API docs

## 🔧 Browser Compatibility

This framework is designed to work in modern browsers that support:

- ES6 modules and classes
- DOM APIs and Custom Events
- History API for routing
- Local Storage for persistence

## 🤝 Contributing

We welcome contributions! Please read our contributing guidelines:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Add tests for new functionality
4. Ensure all tests pass (`bun test`)
5. Submit a pull request

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

---

**RxHtmx Framework** - From simple library to complete framework! 🚀