npm - @diniz/webcomponents - Versions diffs - 1.1.4 → 1.1.6 - Mend

@diniz/webcomponents 1.1.4 → 1.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +291 -824
package/dist/README.md +291 -824
package/dist/style.css +180 -0
package/dist/webcomponents.es.js +593 -400
package/dist/webcomponents.umd.js +108 -72
package/package.json +1 -1

package/dist/README.md CHANGED Viewed

@@ -12,948 +12,415 @@ A lightweight, framework-agnostic web components library built with vanilla Type
 🎯 **Tree-shakeable** - Import only what you need
 ♿ **Accessible** - ARIA attributes and keyboard navigation
-## 🚀 Live Demo
+## 🚀 Live Demo & Component Documentation
-Check out the interactive demo and component examples:
+Check out the interactive demo and explore component implementations:
 **[View Live Demo →](https://rodiniz.github.io/webcomponents/)**
-## Installation
-```bash
-npm install @diniz/webcomponents
-```
-## Using with Vite (No Framework)
+**Component source code and demos are located in the `src/features/` directory:**
+- Button Demo: `src/features/button-demo/`
+- Input Demo: `src/features/input-demo/`
+- Table Demo: `src/features/table-demo/`
+- Form Demo: `src/features/form-demo/`
+- Date Picker Demo: `src/features/date-picker-demo/`
+- And more...
-This library works seamlessly with Vite without requiring any framework. Here's how to set up a vanilla JavaScript/TypeScript project:
+Each demo includes the component implementation and usage examples. Visit the live demo site to see all components in action.
-### 1. Create a New Vite Project
-```bash
-# Create a new Vite project with vanilla TypeScript template
-npm create vite@latest my-app -- --template vanilla-ts
-cd my-app
-npm install
-```
-### 2. Install the Library
+## Installation
 ```bash
 npm install @diniz/webcomponents
 ```
-### 3. Import Components in Your Main File
-In your `src/main.ts` file:
+## Quick Start
 ```typescript
 import '@diniz/webcomponents';
-import '@diniz/webcomponents/dist/style.css'; // Import styles
-// Now you can use the components in your HTML
-document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
-  <div>
-    <h1>My Web Components App</h1>
-    <ui-button variant="primary" size="md">Click Me</ui-button>
-    <ui-date-picker format="DD/MM/YYYY"></ui-date-picker>
-  </div>
+import '@diniz/webcomponents/dist/style.css';
+// Components are now available
+document.body.innerHTML = `
+  <ui-button variant="primary">Click Me</ui-button>
+  <ui-date-picker format="DD/MM/YYYY"></ui-date-picker>
 `;
 ```
-### 4. Use Components in HTML
-In your `index.html`:
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>My App</title>
-  </head>
-  <body>
-    <div id="app">
-      <ui-button variant="primary">Click Me</ui-button>
-      <ui-date-picker format="DD/MM/YYYY"></ui-date-picker>
-      <ui-table></ui-table>
-    </div>
-    <script type="module" src="/src/main.ts"></script>
-  </body>
-</html>
-```
+## Components
-### 5. Add Event Listeners (Optional)
+- **ui-button** - Button with variants, sizes, icons
+- **ui-input** - Input with validation
+- **ui-table** - Data table with actions
+- **ui-date-picker** - Date picker
+- **ui-pagination** - Pagination control
+- **ui-select** - Dropdown selection
+- **ui-checkbox** - Checkbox input
+- **ui-modal** - Modal dialog
+- **ui-card** - Card container
+- **ui-tabs** - Tab navigation
+- **ui-stepper** - Step indicator
+- **ui-toast** - Toast notifications
+- **ui-upload** - File upload
+- **ui-layout** - Application layout
+For detailed documentation on each component, see the demo implementations in `src/features/`.
-```typescript
-// Wait for components to be defined
-customElements.whenDefined('ui-button').then(() => {
-  const button = document.querySelector('ui-button');
-  button?.addEventListener('click', () => {
-    console.log('Button clicked!');
-  });
-});
-// Listen to custom events
-const picker = document.querySelector('ui-date-picker');
-picker?.addEventListener('date-change', ((e: CustomEvent) => {
-  console.log('Date selected:', e.detail.value);
-}) as EventListener);
-```
+## Core Features
-### 6. TypeScript Support
+### Signals & Reactivity
-For full TypeScript support, create a `src/types.d.ts` file:
+Create reactive, auto-updating UI with signals. Changes automatically trigger re-renders:
 ```typescript
-declare module '@diniz/webcomponents' {
-  export interface UIButton extends HTMLElement {
-    variant: 'primary' | 'secondary' | 'ghost';
-    size: 'sm' | 'md' | 'lg';
-    icon?: string;
-    disabled?: boolean;
-  }
+import { BaseComponent } from '@diniz/webcomponents';
+class CounterComponent extends BaseComponent {
+  // Create a reactive signal with initial value 0
+  private count = this.useSignal(0);
-  export interface UIDatePicker extends HTMLElement {
-    format: string;
-    value: string;
-    min?: string;
-    max?: string;
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
   }
-  // Add other component interfaces as needed
-}
-declare global {
-  interface HTMLElementTagNameMap {
-    'ui-button': import('@diniz/webcomponents').UIButton;
-    'ui-date-picker': import('@diniz/webcomponents').UIDatePicker;
-    // Add other components as needed
+  private increment() {
+    // Update signal value - automatically triggers re-render
+    this.count.set(this.count.get() + 1);
   }
-}
-```
-### 7. Build for Production
-```bash
-npm run build
-```
-The build output will be in the `dist` folder, ready to deploy to any static hosting service.
-### Tree-shaking (Import Only What You Need)
-You can import individual components to reduce bundle size:
-```typescript
-// Import only specific components
-import { UIButton } from '@diniz/webcomponents';
-import '@diniz/webcomponents/dist/style.css';
-// The component is automatically registered
-// Now you can use <ui-button> in your HTML
-```
-### Configuration Tips
-**Vite Config** - No special configuration needed! Web Components work out of the box with Vite.
-**CSS Customization** - Override CSS custom properties to match your theme:
+  private reset() {
+    this.count.set(0);
+  }
-```css
-:root {
-  --color-primary: #3b82f6;
-  --color-secondary: #8b5cf6;
-  --color-success: #10b981;
-  --color-danger: #ef4444;
-  --color-warning: #f59e0b;
-  --color-info: #06b6d4;
-  --radius-sm: 0.25rem;
-  --radius-md: 0.375rem;
-  --radius-lg: 0.5rem;
+  render() {
+    const currentCount = this.count.get();
+    this.shadowRoot!.innerHTML = `
+      <style>
+        :host {
+          display: flex;
+          flex-direction: column;
+          gap: 1rem;
+          padding: 2rem;
+        }
+        .count-display {
+          font-size: 2rem;
+          font-weight: bold;
+          color: var(--color-primary, #24ec71);
+        }
+      </style>
+      <div class="count-display">Count: ${currentCount}</div>
+      <button id="increment">Increment</button>
+      <button id="reset">Reset</button>
+    `;
+    // Connect event listeners to update signals
+    this.shadowRoot!.getElementById('increment')?.addEventListener('click',
+      () => this.increment()
+    );
+    this.shadowRoot!.getElementById('reset')?.addEventListener('click',
+      () => this.reset()
+    );
+  }
 }
-```
-**Update `src/main.ts`:**
-```typescript
-import '@diniz/webcomponents';
-import '@diniz/webcomponents/dist/style.css';
-document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
-  <div>
-    <h1>My Web Components App</h1>
-    <ui-button variant="primary">Click Me</ui-button>
-    <ui-date-picker format="DD/MM/YYYY"></ui-date-picker>
-    <ui-table id="myTable"></ui-table>
-  </div>
-`;
-// Add some data to the table
-const table = document.getElementById('myTable') as any;
-table.data = {
-  columns: [
-    { key: 'name', label: 'Name' },
-    { key: 'role', label: 'Role' }
-  ],
-  rows: [
-    { name: 'Alice', role: 'Admin' },
-    { name: 'Bob', role: 'User' }
-  ]
-};
+customElements.define('counter-app', CounterComponent);
 ```
-### Using via CDN or Direct Import
+**Usage in HTML:**
 ```html
-<script type="module">
-  import '@diniz/webcomponents';
-</script>
-<ui-button variant="primary">Click Me</ui-button>
-<ui-date-picker format="DD/MM/YYYY"></ui-date-picker>
-<ui-table></ui-table>
+<counter-app></counter-app>
 ```
-## Components
-### 🔘 Button (`ui-button`)
+**Key features:**
+- `this.useSignal(value)` - Create a reactive signal
+- `signal.get()` - Read the current value
+- `signal.set(newValue)` - Update value and trigger re-render
+- `this.setState({ ... })` - Update multiple values at once
+- Changes are isolated within component's shadow DOM
-A versatile button component with multiple variants, sizes, and icon support.
+### Signals with Separated HTML & TypeScript Files
-**Features:**
-- 3 variants: `primary`, `secondary`, `ghost`
-- 3 sizes: `sm`, `md`, `lg`
-- Icon support with [Feather Icons](https://feathericons.com/)
-- Icon positioning (left/right)
-- Icon-only buttons
-- Disabled state support
-- Button type support
-- Smooth transitions and hover effects
+When using separate HTML template files, you can achieve automatic reactivity so the HTML updates whenever a signal changes:
-**Usage:**
+**counter.html**
 ```html
-<ui-button variant="primary" size="md">Primary Button</ui-button>
-<ui-button variant="secondary" size="sm">Secondary</ui-button>
-<ui-button variant="ghost" disabled>Disabled</ui-button>
-<!-- With icons -->
-<ui-button variant="primary" icon="check">Save</ui-button>
-<ui-button variant="secondary" icon="trash-2" icon-position="right">Delete</ui-button>
-<ui-button variant="ghost" icon="settings"></ui-button>
-```
-**Attributes:**
-- `variant` - Button style (`primary` | `secondary` | `ghost`)
-- `size` - Button size (`sm` | `md` | `lg`)
-- `icon` - Icon name from Feather Icons
-- `icon-position` - Icon position (`left` | `right`, default: `left`)
-- `disabled` - Disable the button
-- `type` - Button type (`button` | `submit` | `reset`)
----
-### 📅 Date Picker (`ui-date-picker`)
-A customizable date picker with multiple format options and calendar support.
-**Features:**
-- 5 date formats: `YYYY-MM-DD`, `DD/MM/YYYY`, `MM/DD/YYYY`, `DD-MM-YYYY`, `MM-DD-YYYY`
-- Native calendar picker integration
-- Min/max date constraints
-- Text input with format validation
-- Real-time format conversion
-- Disabled state support
-- Custom events for date changes
+<style>
+  :host {
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+    padding: 2rem;
+  }
+  .count-display {
+    font-size: 2rem;
+    font-weight: bold;
+    color: var(--color-primary, #24ec71);
+  }
+</style>
-**Usage:**
-```html
-<ui-date-picker
-  format="DD/MM/YYYY"
-  value="2026-02-26"
-  min="2026-01-01"
-  max="2026-12-31"
-></ui-date-picker>
-<script>
-  const picker = document.querySelector('ui-date-picker');
-  picker.addEventListener('date-change', (e) => {
-    console.log('ISO:', e.detail.value);
-    console.log('Formatted:', e.detail.formattedValue);
-  });
-</script>
+<div class="count-display">
+  Count: <span id="countValue">0</span>
+</div>
+<button id="incrementBtn">Increment</button>
+<button id="resetBtn">Reset</button>
 ```
-**Attributes:**
-- `format` - Date display format
-- `value` - Date value in ISO format (YYYY-MM-DD)
-- `min` - Minimum date (ISO format)
-- `max` - Maximum date (ISO format)
-- `disabled` - Disable the picker
-- `placeholder` - Placeholder text
-**Methods:**
-- `getISOValue()` - Get date in ISO format
-- `getFormattedValue()` - Get date in display format
-- `setValue(isoDate)` - Set the date value
-- `clear()` - Clear the date
-**Events:**
-- `date-change` - Fired when date changes
-- `date-input` - Fired during input
----
-### 📋 Table (`ui-table`)
-A dynamic data table with customizable columns and alignment.
-**Features:**
-- Dynamic column configuration
-- Text alignment per column (left, center, right)
-- Responsive layout
-- Automatic row rendering
-- Theme-aware styling
-**Usage:**
-```html
-<ui-table id="myTable"></ui-table>
+**counter.ts - Automatic Reactivity Approach**
+```typescript
+import { BaseComponent } from '@diniz/webcomponents';
+import template from './counter.html?raw';
-<script type="module">
-  const table = document.getElementById('myTable');
+class CounterComponent extends BaseComponent {
+  private count = this.useSignal(0);
-  table.data = {
-    columns: [
-      { key: 'name', label: 'Name' },
-      { key: 'role', label: 'Role' },
-      { key: 'score', label: 'Score', align: 'right' }
-    ],
-    rows: [
-      { name: 'Alice', role: 'Admin', score: 95 },
-      { name: 'Bob', role: 'User', score: 87 }
-    ]
-  };
-</script>
-```
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+    this.setupEventListeners();
+    // Subscribe to signal changes - re-render when count changes
+    this.watchSignal(this.count, () => {
+      this.updateCountDisplay();
+    });
+  }
-**Properties:**
-- `data` - Object with `columns` and `rows`
-  - `columns`: Array of `{ key, label, align? }`
-  - `rows`: Array of objects matching column keys
+  private increment() {
+    this.count.set(this.count.get() + 1);
+  }
----
+  private reset() {
+    this.count.set(0);
+  }
-### 📄 Pagination (`ui-pagination`)
+  // Single method that updates the display - called whenever signal changes
+  private updateCountDisplay() {
+    const countValue = this.shadowRoot?.getElementById('countValue');
+    if (countValue) {
+      countValue.textContent = String(this.count.get());
+    }
+  }
-Smart pagination component with ellipsis for large page counts.
+  private setupEventListeners() {
+    this.shadowRoot?.getElementById('incrementBtn')?.addEventListener('click',
+      () => this.increment()
+    );
+    this.shadowRoot?.getElementById('resetBtn')?.addEventListener('click',
+      () => this.reset()
+    );
+  }
-**Features:**
-- Automatic page number generation
-- Smart ellipsis for large page counts
-- Previous/Next navigation
-- "Showing X to Y of Z" info display
-- Disabled states for edge pages
-- Custom events for page changes
-- ARIA labels for accessibility
+  render() {
+    this.shadowRoot!.innerHTML = template;
+    this.updateCountDisplay(); // Initial display
+  }
+}
-**Usage:**
-```html
-<ui-pagination
-  total="250"
-  current-page="5"
-  page-size="10"
-></ui-pagination>
-<script>
-  const pagination = document.querySelector('ui-pagination');
-  pagination.addEventListener('page-change', (e) => {
-    console.log('Page:', e.detail.page);
-    console.log('Total Pages:', e.detail.totalPages);
-    // Load new data...
-  });
-</script>
+customElements.define('counter-app', CounterComponent);
 ```
-**Attributes/Properties:**
-- `total` - Total number of items
-- `current-page` - Current page number
-- `page-size` - Items per page (default: 10)
-**Computed Properties:**
-- `totalPages` - Total number of pages
-**Events:**
-- `page-change` - Fired when page changes, includes pagination details
----
-### 📝 Input (`ui-input`)
-Advanced form input with built-in validation and error handling.
-**Features:**
-- Multiple input types: `text`, `email`, `password`, `number`, `tel`, `url`
-- Built-in validation rules:
-  - Email domain validation
-  - Password matching
-  - Min/max length
-  - Regex patterns
-- Custom validators
-- Real-time validation feedback
-- Error message display
-- Touched state tracking
-- Disabled state support
-**Usage:**
-```html
-<ui-input
-  type="email"
-  label="Email"
-  placeholder="you@example.com"
-  required
-  validate="emailDomain:company.com"
-></ui-input>
-<ui-input
-  type="password"
-  label="Password"
-  minlength="8"
-  required
-></ui-input>
-```
+**Alternative: Full Re-render on Signal Change**
-**Attributes:**
-- `type` - Input type
-- `label` - Label text
-- `placeholder` - Placeholder text
-- `required` - Required field
-- `pattern` - Regex pattern
-- `minlength` / `maxlength` - Length constraints
-- `min` / `max` - Number constraints
-- `error-message` - Custom error message
-- `disabled` - Disable input
-- `name` - Form field name
-- `validate` - Validation rule (e.g., `emailDomain:company.com`)
-**State:**
-- `value` - Current input value
-- `valid` - Validation state
-- `touched` - Whether field has been interacted with
-- `error` - Current error message
----
-### 🪟 Modal (`ui-modal`)
-Responsive modal dialog with customizable sizes and behaviors.
-**Features:**
-- 5 size options: `sm`, `md`, `lg`, `xl`, `full`
-- Auto-close on Escape key (configurable)
-- Auto-close on backdrop click (configurable)
-- Smooth animations (fade in, slide up)
-- Header, body, and footer slots
-- Programmatic open/close API
-- Custom events
-- Body scroll lock when open
-**Usage:**
-```html
-<ui-button id="openModal">Open Modal</ui-button>
+For simpler components, you can also re-render the entire template when any signal changes:
-<ui-modal id="myModal" title="Welcome!" size="md">
-  <p>This is the modal content.</p>
-  <p>You can include any HTML here.</p>
-  <div slot="footer">
-    <ui-button id="closeBtn" variant="secondary">Cancel</ui-button>
-    <ui-button id="confirmBtn" variant="primary">Confirm</ui-button>
-  </div>
-</ui-modal>
-<script>
-  const modal = document.getElementById('myModal');
-  const openBtn = document.getElementById('openModal');
-  const closeBtn = document.getElementById('closeBtn');
-  openBtn.addEventListener('click', () => modal.open());
-  closeBtn.addEventListener('click', () => modal.close());
+```typescript
+class CounterComponent extends BaseComponent {
+  private count = this.useSignal(0);
-  modal.addEventListener('modal-close', () => {
-    console.log('Modal closed');
-  });
-</script>
-```
-**Attributes:**
-- `title` - Modal title text
-- `size` - Modal size (`sm` | `md` | `lg` | `xl` | `full`)
-- `open` - Open state attribute
-- `no-close-on-escape` - Disable closing on Escape key
-- `no-close-on-backdrop` - Disable closing on backdrop click
-**Methods:**
-- `open()` - Open the modal
-- `close()` - Close the modal
-**Events:**
-- `modal-open` - Fired when modal opens
-- `modal-close` - Fired when modal closes
----
-### 📋 Select (`ui-select`)
-Customizable dropdown select with search capability.
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+    this.setupEventListeners();
+    // Re-render entire component when signal changes
+    this.watchSignal(this.count, () => this.render());
+  }
-**Features:**
-- JSON-based options configuration
-- Searchable dropdown (optional)
-- Keyboard navigation
-- Disabled options support
-- Custom placeholder text
-- Change events with full option details
-- Click-outside to close
-- Smooth animations
-- Theme-aware styling
+  private increment() {
+    this.count.set(this.count.get() + 1);
+    // No need to manually update - render() is called automatically
+  }
-**Usage:**
-```html
-<ui-select
-  id="mySelect"
-  label="Choose a Country"
-  placeholder="Select country..."
-  searchable
-></ui-select>
-<script>
-  const select = document.getElementById('mySelect');
-  // Set options
-  const options = [
-    { value: 'us', label: 'United States' },
-    { value: 'uk', label: 'United Kingdom' },
-    { value: 'ca', label: 'Canada' },
-    { value: 'au', label: 'Australia', disabled: true }
-  ];
-  select.setAttribute('options', JSON.stringify(options));
-  // Set initial value
-  select.setAttribute('value', 'us');
-  // Listen for changes
-  select.addEventListener('select-change', (e) => {
-    console.log('Value:', e.detail.value);
-    console.log('Option:', e.detail.option);
-  });
-</script>
-```
+  private reset() {
+    this.count.set(0);
+  }
-**Attributes:**
-- `label` - Label text above select
-- `placeholder` - Placeholder when no selection
-- `options` - JSON string of options array
-- `value` - Currently selected value
-- `disabled` - Disable the select
-- `searchable` - Enable search functionality
+  private setupEventListeners() {
+    // Re-attach listeners after each render
+    this.shadowRoot?.getElementById('incrementBtn')?.addEventListener('click',
+      () => this.increment()
+    );
+    this.shadowRoot?.getElementById('resetBtn')?.addEventListener('click',
+      () => this.reset()
+    );
+  }
-**Option Format:**
-```typescript
-{
-  value: string;      // The option value
-  label: string;      // Display text
-  disabled?: boolean; // Optional: disable option
+  render() {
+    const currentCount = this.count.get();
+    this.shadowRoot!.innerHTML = `
+      <style>
+        :host {
+          display: flex;
+          flex-direction: column;
+          gap: 1rem;
+          padding: 2rem;
+        }
+        .count-display {
+          font-size: 2rem;
+          font-weight: bold;
+          color: var(--color-primary, #24ec71);
+        }
+      </style>
+      <div class="count-display">Count: ${currentCount}</div>
+      <button id="incrementBtn">Increment</button>
+      <button id="resetBtn">Reset</button>
+    `;
+    this.setupEventListeners();
+  }
 }
-```
-**Events:**
-- `select-change` - Fired when selection changes
-  - `detail.value` - Selected value
-  - `detail.option` - Full option object
----
-### ☑️ Checkbox (`ui-checkbox`)
-Flexible checkbox with indeterminate state support.
-**Features:**
-- 3 sizes: `sm`, `md`, `lg`
-- Checked/unchecked states
-- Indeterminate state (useful for "select all")
-- Disabled state
-- Label support (attribute or slot)
-- Programmatic API
-- Custom events
-- Smooth animations and transitions
-- Theme-aware styling
-**Usage:**
-```html
-<!-- Basic usage -->
-<ui-checkbox label="Accept terms"></ui-checkbox>
-<ui-checkbox label="Subscribe" checked></ui-checkbox>
-<ui-checkbox label="Disabled" disabled></ui-checkbox>
-<!-- With sizes -->
-<ui-checkbox label="Small" size="sm"></ui-checkbox>
-<ui-checkbox label="Medium" size="md"></ui-checkbox>
-<ui-checkbox label="Large" size="lg"></ui-checkbox>
-<!-- Programmatic usage -->
-<ui-checkbox id="myCheckbox" label="Select All"></ui-checkbox>
-<script>
-  const checkbox = document.getElementById('myCheckbox');
-  // Listen for changes
-  checkbox.addEventListener('checkbox-change', (e) => {
-    console.log('Checked:', e.detail.checked);
-  });
-  // Set states programmatically
-  checkbox.setChecked(true);
-  checkbox.setIndeterminate(true);
-</script>
+customElements.define('counter-app', CounterComponent);
 ```
-**Attributes:**
-- `label` - Label text
-- `checked` - Checked state
-- `indeterminate` - Indeterminate state
-- `disabled` - Disable checkbox
-- `size` - Checkbox size (`sm` | `md` | `lg`)
-**Methods:**
-- `setChecked(checked: boolean)` - Set checked state
-- `setIndeterminate(indeterminate: boolean)` - Set indeterminate state
-**Events:**
-- `checkbox-change` - Fired when state changes
-  - `detail.checked` - New checked state
+**Key improvements:**
+- Use `this.watchSignal(signal, callback)` to subscribe to signal changes
+- When signal updates, callback triggers automatically - no manual DOM updates needed
+- Choose between:
+  - **Selective updates** - Only update specific DOM elements (better performance)
+  - **Full re-render** - Re-render entire template (simpler logic, less efficient)
+- The HTML automatically stays in sync with signal values
----
+### Enhanced: useSignalHtml for Direct DOM Binding
-### 🎯 Sidebar (`app-sidebar`)
+For even cleaner code, use `useSignalHtml()` to create a signal that automatically updates a specific HTML element:
-Navigation sidebar component with links.
-**Features:**
-- Workspace navigation
-- Active link highlighting (via routing)
-- Theme-aware styling
-**Usage:**
+**counter.html**
 ```html
-<app-sidebar></app-sidebar>
-```
----
-### 📐 Layout (`app-layout`)
-Application layout wrapper with navigation and sidebar.
-**Features:**
-- Top navigation bar
-- Sidebar integration
-- Main content area with slot
-- Responsive layout
+<style>
+  :host {
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+    padding: 2rem;
+  }
+  .count-display {
+    font-size: 2rem;
+    font-weight: bold;
+    color: var(--color-primary, #24ec71);
+  }
+</style>
-**Usage:**
-```html
-<app-layout>
-  <your-page-component></your-page-component>
-</app-layout>
+<div class="count-display">
+  Count: <span id="countValue">0</span>
+</div>
+<button id="incrementBtn">Increment</button>
+<button id="resetBtn">Reset</button>
 ```
----
-## Core Features
-### Base Component
-All components extend `BaseComponent` which provides:
-**Signal-based Reactivity:**
+**counter.ts - Simplified with useSignalHtml**
 ```typescript
-class MyComponent extends BaseComponent {
-  private count = this.useSignal(0);
+import { BaseComponent } from '@diniz/webcomponents';
+import template from './counter.html?raw';
+class CounterComponent extends BaseComponent {
+  // Create signal bound to HTML element with ID 'countValue'
+  // Automatically updates the element's textContent when signal changes
+  private count = this.useSignalHtml('countValue', 0);
   connectedCallback() {
     super.connectedCallback();
-    // count.set() automatically triggers re-render
-    this.count.set(this.count.get() + 1);
+    this.render();
+    this.setupEventListeners();
   }
-}
-```
-**State Management:**
-```typescript
-class MyComponent extends BaseComponent<{ user: string }> {
-  constructor() {
-    super();
-    this.state = { user: '' };
-  }
-  updateUser() {
-    this.setState({ user: 'Alice' }); // Triggers re-render
+  private increment() {
+    // Just update the signal - HTML updates automatically
+    this.count.set(this.count.get() + 1);
   }
-}
-```
-### Router
-Built-in client-side router with layouts:
-```typescript
-const routes = [
-  {
-    path: '/',
-    layout: 'app-layout',
-    load: () => import('./features/home/home-page'),
-    component: 'home-page'
+  private reset() {
+    // Just update the signal - HTML updates automatically
+    this.count.set(0);
   }
-];
-```
-### Store
-Global state management:
-```typescript
-import { store } from './core/store';
+  private setupEventListeners() {
+    this.shadowRoot?.getElementById('incrementBtn')?.addEventListener('click',
+      () => this.increment()
+    );
+    this.shadowRoot?.getElementById('resetBtn')?.addEventListener('click',
+      () => this.reset()
+    );
+  }
-store.setState({ theme: 'dark' });
-const currentState = store.getState();
+  render() {
+    this.shadowRoot!.innerHTML = template;
+  }
+}
-store.subscribe(state => {
-  console.log('State changed:', state);
-});
+customElements.define('counter-app', CounterComponent);
 ```
-### HTTP Client
-Lightweight HTTP client with interceptor support for API requests:
+**Benefits of `useSignalHtml()`:**
+- No need for `watchSignal()` subscription
+- No need for manual `updateDisplay()` functions
+- Automatically syncs signal value to element's `textContent`
+- One line instead of multiple lines of setup
+- Perfect for data binding in separated HTML/TS architecture
+**Signature:**
 ```typescript
-import { http } from '@diniz/webcomponents';
-// Set base URL for all requests
-http.setBaseURL('https://api.example.com');
-// Set default headers
-http.setDefaultHeaders({ 'Authorization': 'Bearer token' });
-// Make requests
-const users = await http.get<User[]>('/users');
-const newUser = await http.post<User>('/users', { name: 'Alice' });
-await http.put(`/users/${id}`, updatedData);
-await http.delete(`/users/${id}`);
+useSignalHtml<T>(elementId: string, initialValue: T): Signal<T>
 ```
-**Request Interceptors:**
+Returns a signal that automatically updates the specified HTML element whenever the value changes.
-```typescript
-// Add auth token to every request
-http.interceptors.request.use((config) => {
-  const token = localStorage.getItem('auth_token');
-  if (token) {
-    config.headers = config.headers || {};
-    config.headers['Authorization'] = `Bearer ${token}`;
-  }
-  return config;
-});
-// Handle request errors
-http.interceptors.request.use(
-  (config) => config,
-  (error) => {
-    console.error('Request failed:', error);
-    throw error;
-  }
-);
-```
+This pattern is used throughout the demo components in `src/features/`.
-**Response Interceptors:**
+### HTTP Client
 ```typescript
-// Transform response data
-http.interceptors.response.use((response) => {
-  // Unwrap API response if it's nested
-  if (response.data?.result) {
-    response.data = response.data.result;
-  }
-  return response;
-});
-// Handle errors globally
-http.interceptors.response.use(
-  (response) => response,
-  (error) => {
-    if (error.response?.status === 401) {
-      // Handle unauthorized
-      localStorage.removeItem('auth_token');
-      window.location.href = '/login';
-    }
-    throw error;
-  }
-);
-```
-**Methods:**
-- `get<T>(url, config?)` - GET request
-- `post<T>(url, data?, config?)` - POST request
-- `put<T>(url, data?, config?)` - PUT request
-- `patch<T>(url, data?, config?)` - PATCH request
-- `delete<T>(url, config?)` - DELETE request
-- `head<T>(url, config?)` - HEAD request
-**Configuration:**
+import { http } from '@diniz/webcomponents';
-```typescript
-interface RequestConfig {
-  method?: string;
-  headers?: Record<string, string>;
-  body?: string | FormData | null;
-  timeout?: number;      // Default: 30000ms
-}
+const users = await http.get<User[]>('/api/users');
+const newUser = await http.post<User>('/api/users', data);
 ```
-**Features:**
-- ✅ Request/response interceptors with error handling
-- ✅ Automatic JSON serialization/deserialization
-- ✅ Timeout support (default 30s)
-- ✅ Global headers and base URL configuration
-- ✅ FormData support for file uploads
-- ✅ TypeScript generics for type-safe responses
-- ✅ Automatic error messages with status codes
+### Router & Store
----
+Built-in routing and global state management utilities.
 ## Theming
-All components use CSS custom properties for easy theming:
+Customize colors and spacing using CSS custom properties:
 ```css
 :root {
   --color-primary: #24ec71;
-  --color-primary-contrast: #ffffff;
-  --color-ink: #0f172a;
-  --color-muted: #f1f5f9;
-  --color-border: #e2e8f0;
+  --color-secondary: #8b5cf6;
   --radius-md: 12px;
-  --radius-pill: 999px;
 }
 ```
----
-## Dependencies
-### Icons
-This library uses **[Feather Icons](https://feathericons.com/)** for beautiful, minimal SVG icons. Feather provides a consistent set of 286 icons perfect for UI components.
-```typescript
-import feather from 'feather-icons';
+## Development
-// Use icons in components
-<ui-button icon="plus">Add Item</ui-button>
-<ui-button icon="trash-2" variant="danger">Delete</ui-button>
+```bash
+npm install
+npm run dev      # Start dev server
+npm run build    # Build for production
+npm run build:lib # Build library distribution
 ```
-[Browse all available Feather icons →](https://feathericons.com/)
----
-## Bundle Size
-@diniz/webcomponents is extremely lightweight with zero runtime dependencies:
-| Package | Size (minified) | Size (gzipped) |
-|---------|-----------------|----------------|
-| **@diniz/webcomponents** | ~45KB | ~12KB |
-| Vue 3 + Router | ~185KB | ~65KB |
-| React 18 + Router | ~245KB | ~85KB |
-| Angular 15 | ~500KB+ | ~150KB+ |
-| Svelte | ~60KB | ~15KB |
-*Sizes are approximate and vary based on included components and tree-shaking effectiveness*
-**Why Web Components?**
-- ✅ No framework overhead - use with any framework or vanilla JS
-- ✅ Smaller initial bundle size than traditional frameworks
-- ✅ Progressive enhancement - works without JavaScript
-- ✅ Share components across different projects/frameworks
-- ✅ Built-in browser APIs - no external polyfills needed for modern browsers
----
 ## Browser Support
 - ✅ Chrome/Edge (latest)
 - ✅ Firefox (latest)
 - ✅ Safari (latest)
-- ✅ All modern browsers with Custom Elements support
----
-## Development
-```bash
-# Install dependencies
-npm install
-# Start dev server
-npm run dev
-# Build library
-npm run build:lib
-# Build production app
-npm run build:prod
-```
----
-## Project Structure
-```
-src/
-├── core/
-│   ├── base-component.ts  # Base class with signals
-│   ├── router.ts          # Client-side routing
-│   └── store.ts           # Global state management
-├── shared/
-│   └── components/        # Reusable UI components
-│       ├── button.ts
-│       ├── checkbox.ts
-│       ├── date-picker.ts
-│       ├── input.ts
-│       ├── modal.ts
-│       ├── pagination.ts
-│       ├── select.ts
-│       └── table.ts
-├── layouts/
-│   └── app-layout.ts      # Application shell
-├── features/              # Page components
-└── styles/
-    └── theme.css          # Global theme variables
-```
-## Contributing
-Contributions are welcome! Please feel free to submit a Pull Request.
----
 ## License
 MIT © Rodrigo Diniz