$tep Framework

Model-View-Controller framework in TypeScript/Vanilla JS for Single Page Applications

🎯 Panoramica

$tep è un framework MVC leggero e modulare per costruire Single Page Applications senza dipendenze esterne. Fornisce pattern predefiniti per gestire le interazioni utente più comuni (liste, dettagli, wizard) con un sistema di routing robusto e data binding reattivo.

Cosa rende $tep speciale?

• ✅ Zero dipendenze - Completamente vanilla, nessun vendor lock-in
• ✅ TypeScript-first - Type safety e autocomplete eccezionale
• ✅ Pattern predefiniti - Lista, Dettaglio, Wizard, Lookup pronti all'uso
• ✅ Data binding reattivo - Observable pattern integrato
• ✅ Routing SPA - History API con stack management
• ✅ PWA-ready - Pattern Memento per stato persistente
• ✅ Sicuro - Protezione XSS integrata
• ✅ Performante - Debouncing, throttling, gestione memoria

📦 Installazione

# Installa dipendenze
npm install

# Build TypeScript
npm run build

# Development con watch mode
npm run build:watch

🏗️ Architettura

Il framework implementa un pattern MVC per SPA con tre layer principali:

• Model: Observable/Computed per data binding reattivo
• View: Template HTML con binding dichiarativo
• Controller: Step classes che orchestrano logica e navigazione

📚 Pattern Disponibili

Core Patterns

| Pattern | Descrizione | Use Case | |---------|-------------|----------| | DetailStep | CRUD singola entità | Form inserimento/modifica | | CollectionStep | Liste con ricerca | Tabelle, elenchi | | WizardStep | Multi-fase progressivo | Checkout, onboarding | | LookupStep | Selezione da dizionario | Autocomplete, picker |

🆕 Advanced Patterns (New!)

| Pattern | Descrizione | Use Case | File | |---------|-------------|----------|------| | TreeStep 🗂️ | Strutture gerarchiche con drag & drop | Organigrammi, categorie, menu | AbstractTreeStep.ts | | ImportStep 📥 | Import massivo con validazione (wizard) | Import Excel/CSV, migrazione dati | AbstractImportStep.ts | | ApprovalStep ✅ | Workflow approvazioni multi-livello | Ordini, note spese, documenti | AbstractApprovalStep.ts |

📖 Vedi esempi completi in /examples

🔗 Data Binding

import Observable from './data-binding/Observable.js';

const nome = new Observable('Mario');

// Subscribe a cambiamenti
nome.subscribe(value => console.log('Cambiato:', value));

// Binding con input HTML
nome.bindToHtmlElement(inputElement, validator);

⚙️ Configurazione

import Config from './config/Config.js';

Config.init({
    apiBaseUrl: 'https://api.example.com',
    debug: true,
    logLevel: 'info'
});

🔒 Sicurezza (v2.0.0)

Criticità Risolte

• ✅ XSS Protection: Sanitizzazione HTML automatica
• ✅ Memory Leaks: Cleanup automatico Observable
• ✅ Back Button: Gestione corretta della history
• ✅ Error Handling: Sistema centralizzato con retry
• ✅ Performance: Debouncing input, stack limitati

Protezione XSS

import HtmlSanitizer from './utils/HtmlSanitizer.js';

// Escape automatico
const safe = HtmlSanitizer.escapeHtml(userInput);

// Nelle CollectionStep
setCollection(data) {
    this.collection = this.sanitizeForXss(data);
}

📝 Changelog v2.0.0

Nuove Features

• ✨ Migrazione TypeScript completa (100%)
• ✨ Sistema configurazione centralizzata
• ✨ HtmlSanitizer per protezione XSS
• ✨ ErrorHandler con retry automatico
• ✨ Debouncing/throttling utilities
• ✨ TreeStep - Alberi gerarchici con drag & drop
• ✨ ImportStep - Import massivo dati con validazione
• ✨ ApprovalStep - Workflow approvazioni multi-livello
• ✨ Esempi completi in /examples

Bug Fix

• 🐛 Fix back button behavior
• 🐛 Fix memory leak in Observable
• 🐛 Fix hasOwnProperty pattern
• 🐛 Stack memento limitato (max 50)

Miglioramenti

• 📈 Debouncing su input validation
• 📈 Fetch con timeout e retry
• 📈 Gestione errori migliorata
• 📈 Documentazione completa

🛠️ Build e Deploy

# Development
npm run build:watch

# Production
npm run build

# Type check
npm run type-check

# Test
npm test

📄 License

MIT License

👤 Autore

Salvatore Milazzo

• GitHub: @smilazzo-lab

Made with ❤️ in Italy