microui-wc 0.1.0 → 0.1.2

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 > **SOTA reference for AI coding assistants.** This document is optimized for LLMs generating microUI code.
 
-## 🚨 REGOLE INVIOLABILI
+## 🚨 MANDATORY RULES
 
 > [!CAUTION]
 > These rules can NEVER be violated. Any code that violates these rules must be rejected.
@@ -10,13 +10,13 @@
 ### ❌ NO SHADOW DOM
 
 **microUI must NEVER use Shadow DOM.** All components must:
-- Usare Light DOM (il DOM normale)
-- Inserire gli elementi direttamente nel documento
-- Usare classi CSS con prefisso `mu-` per l'incapsulamento
-- Mai usare `this.attachShadow()` o `this.shadowRoot`
+- Use Light DOM (normal DOM)
+- Insert elements directly into the document
+- Use CSS classes with `mu-` prefix for encapsulation
+- Never use `this.attachShadow()` or `this.shadowRoot`
 
 ```javascript
-// ❌ FORBIDDEN - Non usare MAI
+// ❌ FORBIDDEN - Never use this
 this.attachShadow({ mode: 'open' });
 this.shadowRoot.innerHTML = '...';
 
@@ -25,12 +25,12 @@ this.innerHTML = '...';
 this.classList.add('mu-component');
 ```
 
-### 🧪 TEST ISOLATION OBBLIGATORIA
+### 🧪 MANDATORY TEST ISOLATION
 
-**Tests MUST be run with `test-isolated.js`**, never with `bun test` diretto.
+**Tests MUST be run with `test-isolated.js`**, never with `bun test` directly.
 
 ```bash
-# ❌ SBAGLIATO - Test falliscono per linkedom globalThis pollution
+# ❌ WRONG - Tests fail due to linkedom globalThis pollution
 bun test tests/components
 
 # ✅ CORRECT - Each test in separate process
@@ -40,15 +40,15 @@ bun run scripts/test-isolated.js
 bun run test:e2e
 ```
 
-**Why?** linkedom (used to simulate DOM in unit tests) pollutes `globalThis` e il registry dei custom elements. When tests are run in parallel in the same process, the registrations conflict.
+**Why?** linkedom (used to simulate DOM in unit tests) pollutes `globalThis` and the custom elements registry. When tests are run in parallel in the same process, the registrations conflict.
 
 ---
 
 ## 🛠️ COMPONENT DEVELOPMENT GUIDELINES
 
-> **Linee guida obbligatorie per creare nuovi componenti microUI.** Seguire queste regole previene memory leak, crash e garantisce consistenza con il framework.
+> **Mandatory guidelines for creating new microUI components.** Following these rules prevents memory leaks, crashes, and ensures consistency with the framework.
 
-### 📋 Template Componente Completo
+### 📋 Complete Component Template
 
 ```javascript
 /**
@@ -59,7 +59,7 @@ bun run test:e2e
  */
 
 import { MuElement, define } from '../core/MuElement.js';
-import { escapeHTML } from '../core/utils.js';  // Per contenuti user-facing
+import { escapeHTML } from '../core/utils.js';  // For user-facing content
 
 export class MuExample extends MuElement {
     static get observedAttributes() {
@@ -75,17 +75,17 @@ export class MuExample extends MuElement {
     }
 
     // ========================
-    // LIFECYCLE (OBBLIGATORIO)
+    // LIFECYCLE (MANDATORY)
     // ========================
     
     connectedCallback() {
-        super.connectedCallback();  // ⚠️ OBBLIGATORIO - Inizializza AbortController
+        super.connectedCallback();  // ⚠️ MANDATORY - Initializes AbortController
         this.render();
     }
 
     disconnectedCallback() {
-        super.disconnectedCallback();  // ⚠️ OBBLIGATORIO se usi timer/subscriptions
-        // Cleanup subscriptions manuali (es. breakpoints.subscribe)
+        super.disconnectedCallback();  // ⚠️ MANDATORY if using timer/subscriptions
+        // Cleanup manual subscriptions (e.g. breakpoints.subscribe)
     }
 
     attributeChangedCallback(name, oldVal, newVal) {
@@ -115,7 +115,7 @@ export class MuExample extends MuElement {
     // ========================
 
     render() {
-        // ✅ SEMPRE escapare contenuti user-facing
+        // ✅ ALWAYS escape user-facing content
         this.innerHTML = `
             <div class="mu-example">
                 <label>${escapeHTML(this.label)}</label>
@@ -174,7 +174,7 @@ export class MuExample extends MuElement {
 
     _validate() {
         if (!this.label) {
-            // ✅ Segnala errori per AI agent debugging
+            // ✅ Report errors for AI agent debugging
             this.logError('MISSING_LABEL', 'mu-example requires a label attribute');
         }
     }
@@ -189,57 +189,57 @@ if (!customElements.get('mu-example')) {
 ### ⚠️ ANTI-PATTERN: What NEVER to Do
 
 ```javascript
-// ❌ FORBIDDEN: addEventListener diretto (memory leak)
+// ❌ FORBIDDEN: Direct addEventListener (memory leak)
 this.querySelector('button').addEventListener('click', handler);
 
 // ❌ FORBIDDEN: setTimeout/setInterval raw (memory leak)
 setTimeout(() => this.update(), 1000);
 setInterval(() => this.poll(), 5000);
 
-// ❌ FORBIDDEN: Nessun super.connectedCallback() (AbortController non inizializzato)
+// ❌ FORBIDDEN: No super.connectedCallback() (AbortController not initialized)
 connectedCallback() {
-    this.render();  // this.listen() non funzionerà!
+    this.render();  // this.listen() won't work!
 }
 
-// ❌ FORBIDDEN: innerHTML senza escaping (XSS vulnerability)
+// ❌ FORBIDDEN: innerHTML without escaping (XSS vulnerability)
 this.innerHTML = `<div>${userInput}</div>`;
 
-// ❌ FORBIDDEN: removeEventListener con arrow function (non funziona mai)
+// ❌ FORBIDDEN: removeEventListener with arrow function (never works)
 window.removeEventListener('resize', () => this.handleResize());
 
-// ❌ FORBIDDEN: Temporal dead zone con setTimeout
+// ❌ FORBIDDEN: Temporal dead zone with setTimeout
 const id = setTimeout(() => { this._timers.delete(id); }, delay);
 
 // ❌ FORBIDDEN: Shadow DOM
 this.attachShadow({ mode: 'open' });
 
-// ❌ FORBIDDEN: DOM Teleportation senza reset del flag listener (Bug Jan 2026)
+// ❌ FORBIDDEN: DOM Teleportation without resetting listener flag (Bug Jan 2026)
 // When a component moves ITSELF in the DOM (e.g. appendChild(this)),
-// disconnectedCallback aborta i listener ma il flag impedisce ri-registrazione
+// disconnectedCallback aborts listeners but the flag prevents re-registration
 connectedCallback() {
-    if (!this._listenerSetup) {  // ⚠️ Il flag resta true dopo disconnect!
+    if (!this._listenerSetup) {  // ⚠️ Flag stays true after disconnect!
         this._listenerSetup = true;
-        this.listen(this, 'click', handler);  // Perso dopo teleportation
+        this.listen(this, 'click', handler);  // Lost after teleportation
     }
 }
-// ✅ CORRECT: Reset del flag in disconnectedCallback
+// ✅ CORRECT: Reset flag in disconnectedCallback
 disconnectedCallback() {
     super.disconnectedCallback();
-    this._listenerSetup = false;  // Permette ri-registrazione dopo move
+    this._listenerSetup = false;  // Allows re-registration after move
 }
 ```
 
-### ✅ PATTERN OBBLIGATORI
+### ✅ MANDATORY PATTERNS
 
 | Pattern | Method | Why |
 |---------|--------|--------|
 | **Event Listeners** | `this.listen(target, type, handler)` | Auto-cleanup via AbortController |
-| **Timers** | `this.setTimeout()` / `this.setInterval()` | Auto-cleanup su disconnectedCallback |
-| **XSS Prevention** | `escapeHTML(userInput)` | Previene injection in innerHTML |
-| **Keyboard A11y** | `this.setupActivation(callback)` | Gestisce Enter/Space per elementi interattivi |
-| **AI Debugging** | `this.logError(code, message)` | Errori strutturati per AI agents |
-| **Lifecycle** | `super.connectedCallback()` | Inizializza AbortController per this.listen() |
-| **DOM Teleportation** | Reset flag in `disconnectedCallback()` | Previene listener orfani dopo move |
+| **Timers** | `this.setTimeout()` / `this.setInterval()` | Auto-cleanup on disconnectedCallback |
+| **XSS Prevention** | `escapeHTML(userInput)` | Prevents injection in innerHTML |
+| **Keyboard A11y** | `this.setupActivation(callback)` | Handles Enter/Space for interactive elements |
+| **AI Debugging** | `this.logError(code, message)` | Structured errors for AI agents |
+| **Lifecycle** | `super.connectedCallback()` | Initializes AbortController for this.listen() |
+| **DOM Teleportation** | Reset flag in `disconnectedCallback()` | Prevents orphan listeners after move |
 
 ### 🚀 SOTA Patterns (Feb 2026)
 
@@ -247,15 +247,15 @@ Modern patterns that should be used for new components and migrations.
 
 #### ✅ Performance CSS (Implemented)
 
-Il framework applica **by default** le seguenti ottimizzazioni:
+The framework applies **by default** the following optimizations:
 
-| Tecnica | File | Beneficio |
+| Technique | File | Benefit |
 |---------|------|-----------|
-| `will-change` | animations.css | GPU compositor hints per 13+ classi animazione |
-| `CSS contain` | layout.css, components.css | Isola repaint scope per mu-layout, modals |
-| `content-visibility: auto` | components.css | Skip rendering off-screen per mu-example |
-| Speculation Rules API | shell.html | Prefetch route bundle predittivo |
-| View Transitions API | shell.html | Animazioni smooth tra pagine SPA |
+| `will-change` | animations.css | GPU compositor hints for 13+ animation classes |
+| `CSS contain` | layout.css, components.css | Isolates repaint scope for mu-layout, modals |
+| `content-visibility: auto` | components.css | Skip rendering off-screen for mu-example |
+| Speculation Rules API | shell.html | Predictive route bundle prefetch |
+| View Transitions API | shell.html | Smooth page transitions in SPA |
 
 **Lighthouse Score**: 98/100 Performance, 100/100 Accessibility/BP/SEO
 
@@ -276,37 +276,37 @@ mu-layout {
 }
 ```
 
-#### ✅ Native `<dialog>` per Modal (COMPLETATO)
-**mu-modal** usa ora `<dialog>` nativo con `showModal()`:
-- Top-layer automatico (niente z-index manuali)
-- Focus trap built-in
-- ESC key gestito nativamente
-- `::backdrop` per scrim animato
-- `margin: auto` per centrare
+#### ✅ Native `<dialog>` for Modal (COMPLETED)
+**mu-modal** now uses native `<dialog>` with `showModal()`:
+- Automatic top-layer (no manual z-index)
+- Built-in focus trap
+- Native ESC key handling
+- Animated `::backdrop` scrim
+- `margin: auto` for centering
 
 ```javascript
 // ✅ SOTA: Native dialog
 this.#dialog = document.createElement('dialog');
 this.#dialog.showModal();
 
-// ❌ VECCHIO: Position fixed + z-index + manual focus trap
+// ❌ OLD: Position fixed + z-index + manual focus trap
 this.style.cssText = 'position:fixed;z-index:9999;';
 document.body.appendChild(this);
 ```
 
-#### 🔜 Popover API (CANDIDATI)
-I seguenti componenti potrebbero beneficiare della **Popover API**:
+#### 🔜 Popover API (CANDIDATES)
+The following components could benefit from the **Popover API**:
 
-| Componente | Pattern Attuale | SOTA Migration |
+| Component | Current Pattern | SOTA Migration |
 |------------|----------------|----------------|
 | `mu-dropdown` | Portal container + z-index | `popover` attribute |
 | `mu-tooltip` | Position fixed + z-index | `popover` attribute |
 
-**Benefici Popover API**:
-- Light-dismiss automatico (click outside)
-- Top-layer (niente z-index issues)
+**Popover API Benefits**:
+- Automatic light-dismiss (click outside)
+- Top-layer (no z-index issues)
 - `showPopover()` / `hidePopover()` / `togglePopover()`
-- Keyboard accessibility built-in
+- Built-in keyboard accessibility
 
 ```html
 <!-- SOTA: Declarative popover -->
@@ -316,27 +316,27 @@ I seguenti componenti potrebbero beneficiare della **Popover API**:
 
 ### 🔒 Security Checklist
 
-Prima di completare un componente, verifica:
+Before completing a component, verify:
 
-- [ ] Tutti i contenuti user-facing usano `escapeHTML()`
+- [ ] All user-facing content uses `escapeHTML()`
 - [ ] Interpolated attributes in innerHTML are escaped
 - [ ] Slot content controlled (developer-provided) or escaped
-- [ ] Nessun `eval()`, `Function()`, `document.write()`
+- [ ] No `eval()`, `Function()`, `document.write()`
 
 ### ♿ Accessibility Checklist
 
-- [ ] Elementi interattivi hanno `tabindex="0"`
-- [ ] Role ARIA appropriato (`role="button"`, `role="menuitem"`, etc.)
-- [ ] `setupActivation()` per attivazione via keyboard (Enter/Space)
-- [ ] `aria-label` o label associata per screen reader
-- [ ] Stati (`aria-checked`, `aria-expanded`, etc.) aggiornati dinamicamente
+- [ ] Interactive elements have `tabindex="0"`
+- [ ] Appropriate ARIA role (`role="button"`, `role="menuitem"`, etc.)
+- [ ] `setupActivation()` for keyboard activation (Enter/Space)
+- [ ] `aria-label` or associated label for screen readers
+- [ ] States (`aria-checked`, `aria-expanded`, etc.) dynamically updated
 
 ### 🧪 Testing Checklist
 
-- [ ] Unit test con `bun run scripts/test-isolated.js`
-- [ ] E2E test per interazioni browser reali
+- [ ] Unit test with `bun run scripts/test-isolated.js`
+- [ ] E2E test for real browser interactions
 - [ ] Coverage ≥97%
-- [ ] Test memory leak: componente aggiunto/rimosso dal DOM non lascia listener
+- [ ] Test memory leak: component added/removed from DOM leaves no listeners
 
 ---
 

package/CHANGELOG.md

@@ -44,4 +44,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Live Demo
 
-🌐 https://giuseppescottolavina.github.io/microUI/demo/shell.html
+🌐 https://giuseppescottolavina.github.io/microUI/

package/README.md

@@ -6,15 +6,20 @@
 
 <p align="center">
   <strong>The AI-First Web Components Framework</strong><br>
-  <sub>49 Components • 808 Tests Passing • 100% Lighthouse • Zero Config</sub>
+  <sub>49 Components • 868 Tests Passing • 100% Lighthouse • Zero Config</sub>
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/tests-808%20passing-brightgreen" alt="808 tests">
+  <a href="https://www.npmjs.com/package/microui-wc"><img src="https://img.shields.io/npm/v/microui-wc?color=blue&label=npm" alt="npm version"></a>
+  <a href="https://github.com/GiuseppeScottoLavina/microUI/actions"><img src="https://img.shields.io/github/actions/workflow/status/GiuseppeScottoLavina/microUI/ci.yml?label=CI" alt="CI Status"></a>
   <img src="https://img.shields.io/badge/lighthouse-100%25-brightgreen" alt="100% Lighthouse">
-  <img src="https://img.shields.io/badge/security-Grade%20A-brightgreen" alt="Security Grade A">
-  <img src="https://img.shields.io/badge/bundle-8KB%20initial-blue" alt="8KB initial">
-  <img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache 2.0">
+  <a href="https://github.com/GiuseppeScottoLavina/microUI/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/microui-wc" alt="License"></a>
+</p>
+
+<p align="center">
+  <a href="https://giuseppescottolavina.github.io/microUI/"><strong>🚀 Live Demo</strong></a> •
+  <a href="./docs/getting-started.md"><strong>📖 Docs</strong></a> •
+  <a href="./AGENTS.md"><strong>🤖 Agent Guide</strong></a>
 </p>
 
 ---
@@ -27,7 +32,7 @@
 | Native Web Components | ✅ | ❌ | ❌ | ❌ |
 | AI Agent optimized | ✅ | ❌ | ❌ | ❌ |
 | Config required | None | Babel, Webpack | Vite/CLI | Rollup |
-| Initial bundle | **8 KB** | ~45 KB | ~35 KB | ~15 KB |
+| Bundle (gzipped) | **~59 KB** | ~44 KB | ~34 KB | ~4 KB |
 | Learning curve | HTML | JSX + Hooks | SFC + Composition | Runes |
 
 > **Stop reinventing the wheel.** microUI gives you production-ready components with Material Design 3, full accessibility, and perfect Lighthouse scores—out of the box.
@@ -177,7 +182,7 @@ if (breakpoints.isCompact) {
 
 | Metric | Value |
 |--------|-------|
-| Unit tests | **808 passing** |
+| Unit tests | **868 passing** |
 | Test coverage | Components: 100% |
 | Lighthouse Performance | **100** |
 | Lighthouse Accessibility | **100** |
@@ -191,10 +196,10 @@ if (breakpoints.isCompact) {
 
 ```bash
 # npm
-npm install microui
+npm install microui-wc
 
 # bun (recommended)
-bun add microui
+bun add microui-wc
 
 # CDN (no install)
 <script type="module" src="https://unpkg.com/microui-wc/dist/microui.esm.js"></script>