@progalaxyelabs/stonescriptui-core

Lightweight TypeScript UI framework combining jQuery-style simplicity with modern tools. Build components with Handlebars templates, explicit control, and zero magic.

Features

• Lightweight (~5KB minified) - No bloat, only what you need
• Module Pattern - Familiar jQuery-style API with full control
• Handlebars Templates - HTML in separate files, not JS strings
• TypeScript - Full type safety and IDE support
• Built-in Router - Client-side routing with guards and lazy loading
• State Management - Simple reactive Store pattern
• Event Handling - Automatic cleanup, no memory leaks
• Utilities - DOM, HTTP, and async helpers included

Installation

npm install @progalaxyelabs/stonescriptui-core handlebars

Quick Start

Module Pattern (Simple)

import { createComponent } from '@progalaxyelabs/stonescriptui-core';

const Counter = createComponent({
    template: '<h1>Count: {{count}}</h1><button id="inc">+</button>',
    initialState: { count: 0 },
    methods: {
        increment() { this.setState({ count: this.getState().count + 1 }); }
    }
});

await Counter.init('#app');
Counter.on('#inc', 'click', () => Counter.increment());

Class-Based (Advanced)

import { Component } from '@progalaxyelabs/stonescriptui-core';

class Counter extends Component<{count: number}> {
    constructor() {
        super({ selector: '#app', template: '...' }, { count: 0 });
    }

    protected bindEvents() {
        this.addEventListener('#inc', 'click', () => {
            this.setState({ count: this.state.count + 1 });
        });
    }
}

await new Counter().init();

Core API

Components

• createComponent(options) - Factory for module pattern components
• Component - Base class for OOP-style components
• Lifecycle: init() → onInit() → onReady() ... destroy() → onDestroy()

Routing

import { Router } from '@progalaxyelabs/stonescriptui-core';

const router = new Router({ mode: 'hash' }); // or 'history'
router.register('/home', () => showHome());
router.register('/user/:id', (params) => showUser(params.id));
// Router starts automatically on instantiation

State Management

import { Store } from '@progalaxyelabs/stonescriptui-core';

interface AppState {
  user: { id: number; name: string } | null;
}

const store = new Store<AppState>({ user: null });
const unsubscribe = store.subscribe('user', (user) => console.log(user));
store.set('user', { id: 1, name: 'John' });
unsubscribe(); // Stop listening

Utilities

import { dom, http, asyncUtils } from '@progalaxyelabs/stonescriptui-core';

dom.$('#id');                      // querySelector
dom.$$('.class');                  // querySelectorAll
await http.get('/api/data');
await http.post('/api/data', {});
asyncUtils.debounce(fn, 300);
asyncUtils.throttle(fn, 1000);

Documentation

• Architecture (HLD.md) - Design decisions and internals
• Changelog - Version history
• Publishing Guide - NPM publishing workflow

Contributing

Contributions are welcome! Please read the architecture docs before submitting PRs.

License

MIT