npm - @diniz/webcomponents - Versions diffs - 1.1.5 → 1.1.7 - Mend

@diniz/webcomponents 1.1.5 → 1.1.7

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 (17) hide show

package/README.md +563 -750
package/dist/README.md +563 -750
package/dist/button-demo-BcfxxPSq.js +227 -0
package/dist/card-demo-Cxp-wRGW.js +230 -0
package/dist/date-picker-demo-B8y3zapN.js +143 -0
package/dist/form-demo-page-F1iLCgfh.js +351 -0
package/dist/home-page-XUM8cHP7.js +468 -0
package/dist/index-DiYekJaQ.js +2424 -0
package/dist/layout-demo-CJsZ6DI5.js +289 -0
package/dist/modal-demo-page-YN2KgJ31.js +195 -0
package/dist/stepper-demo-page-BkcpKk_F.js +312 -0
package/dist/table-demo-x2ZD8cFh.js +137 -0
package/dist/tabs-demo-BQBtZzw9.js +76 -0
package/dist/toast-demo-page-DLVacHXA.js +260 -0
package/dist/webcomponents.es.js +31 -1883
package/dist/webcomponents.umd.js +2537 -113
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -12,948 +12,761 @@ 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/)**
+**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...
+Each demo includes the component implementation and usage examples. Visit the live demo site to see all components in action.
 ## Installation
 ```bash
 npm install @diniz/webcomponents
 ```
-## Using with Vite (No Framework)
+## Quick Start
+```typescript
+import '@diniz/webcomponents';
+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>
+`;
+```
-This library works seamlessly with Vite without requiring any framework. Here's how to set up a vanilla JavaScript/TypeScript project:
+## Quick Start with Vite (No Framework)
-### 1. Create a New Vite Project
+Create a new Vite project without any framework to use these web components:
+### 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
+### 2. Install the web components library
 ```bash
 npm install @diniz/webcomponents
 ```
-### 3. Import Components in Your Main File
-In your `src/main.ts` file:
+### 3. Import components in your `src/main.ts`
 ```typescript
 import '@diniz/webcomponents';
-import '@diniz/webcomponents/dist/style.css'; // Import styles
+import '@diniz/webcomponents/dist/style.css';
+import './style.css';
-// 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>
+    <ui-button variant="primary">Primary Button</ui-button>
+    <ui-button variant="secondary">Secondary Button</ui-button>
+    <ui-input
+      label="Email"
+      type="email"
+      placeholder="Enter your email"
+      required
+    ></ui-input>
+    <ui-date-picker
+      label="Select Date"
+      format="DD/MM/YYYY"
+    ></ui-date-picker>
   </div>
 `;
-```
-### 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>
-```
-### 5. Add Event Listeners (Optional)
-```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 component events
+document.querySelector('ui-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);
-```
-### 6. TypeScript Support
-For full TypeScript support, create a `src/types.d.ts` file:
-```typescript
-declare module '@diniz/webcomponents' {
-  export interface UIButton extends HTMLElement {
-    variant: 'primary' | 'secondary' | 'ghost';
-    size: 'sm' | 'md' | 'lg';
-    icon?: string;
-    disabled?: boolean;
-  }
-  export interface UIDatePicker extends HTMLElement {
-    format: string;
-    value: string;
-    min?: string;
-    max?: string;
-  }
-  // 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
-  }
-}
+document.querySelector('ui-input')?.addEventListener('input', (e: Event) => {
+  const input = e.target as HTMLInputElement;
+  console.log('Input value:', input.value);
+});
 ```
-### 7. Build for Production
+### 4. Run the development server
 ```bash
-npm run build
+npm run dev
 ```
-The build output will be in the `dist` folder, ready to deploy to any static hosting service.
+Your app is now running with web components! Open your browser and start building.
-### Tree-shaking (Import Only What You Need)
+### Example: Building a Counter with Signals
-You can import individual components to reduce bundle size:
+Create reactive components using the signals system:
+**src/components/counter.ts**
 ```typescript
-// Import only specific components
-import { UIButton } from '@diniz/webcomponents';
-import '@diniz/webcomponents/dist/style.css';
+import { BaseComponent } from '@diniz/webcomponents';
-// The component is automatically registered
-// Now you can use <ui-button> in your HTML
-```
-### Configuration Tips
+class CounterComponent extends BaseComponent {
+  private count = this.useSignal(0);
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+  }
-**Vite Config** - No special configuration needed! Web Components work out of the box with Vite.
+  private increment() {
+    this.count.set(this.count.get() + 1);
+  }
-**CSS Customization** - Override CSS custom properties to match your theme:
+  private decrement() {
+    this.count.set(this.count.get() - 1);
+  }
-```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() {
+    this.shadowRoot!.innerHTML = `
+      <style>
+        :host {
+          display: block;
+          padding: 2rem;
+          text-align: center;
+        }
+        .count {
+          font-size: 3rem;
+          margin: 1rem 0;
+          color: var(--color-primary, #24ec71);
+        }
+        .buttons {
+          display: flex;
+          gap: 1rem;
+          justify-content: center;
+        }
+      </style>
+      <div>
+        <h2>Counter</h2>
+        <div class="count">${this.count.get()}</div>
+        <div class="buttons">
+          <ui-button id="decrement" variant="secondary">-</ui-button>
+          <ui-button id="increment" variant="primary">+</ui-button>
+        </div>
+      </div>
+    `;
+    this.shadowRoot!.getElementById('increment')?.addEventListener('click',
+      () => this.increment()
+    );
+    this.shadowRoot!.getElementById('decrement')?.addEventListener('click',
+      () => this.decrement()
+    );
+  }
 }
+customElements.define('my-counter', CounterComponent);
 ```
-**Update `src/main.ts`:**
+**src/main.ts**
 ```typescript
 import '@diniz/webcomponents';
 import '@diniz/webcomponents/dist/style.css';
+import './components/counter';
+import './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>
+    <my-counter></my-counter>
   </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' }
-  ]
-};
-```
-### Using via CDN or Direct Import
-```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>
 ```
-## Components
-### 🔘 Button (`ui-button`)
-A versatile button component with multiple variants, sizes, and icon support.
+### Adding Routing to Your App
-**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
+The library includes a built-in router for client-side navigation. Here's how to set it up:
-**Usage:**
-```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>
-```
+#### 1. Create your route configuration
-**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`)
+**src/router.ts**
+```typescript
+import { createRouter, type Route } from '@diniz/webcomponents';
-A customizable date picker with multiple format options and calendar support.
+export const routes: Route[] = [
+  {
+    path: '/',
+    load: () => import('./pages/home'),
+    component: 'home-page'
+  },
+  {
+    path: '/about',
+    load: () => import('./pages/about'),
+    component: 'about-page'
+  },
+  {
+    path: '/counter',
+    load: () => import('./components/counter'),
+    component: 'my-counter'
+  }
+];
-**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
+// Initialize the router with your routes
+// The router automatically sets up navigation and loads the initial route
+createRouter(routes);
-**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>
+// Optional: specify a custom app container selector (default is '#app')
+// createRouter(routes, '#my-app-container');
 ```
-**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
+> **How it works:** The `createRouter()` function sets up the routing system, registers event listeners for navigation, and automatically loads the initial route when the page loads. Navigation happens via links with the `data-link` attribute, and the browser's back/forward buttons work automatically.
-**Events:**
-- `date-change` - Fired when date changes
-- `date-input` - Fired during input
+**Optional: Adding Route Guards**
----
+You can protect routes with guard functions that return a boolean or a Promise:
-### 📋 Table (`ui-table`)
+```typescript
+import { createRouter, type Route } from '@diniz/webcomponents';
-A dynamic data table with customizable columns and alignment.
+// Example: Synchronous guard
+const isAuthenticated = () => {
+  return localStorage.getItem('user') !== null;
+};
-**Features:**
-- Dynamic column configuration
-- Text alignment per column (left, center, right)
-- Responsive layout
-- Automatic row rendering
-- Theme-aware styling
+// Example: Async guard (e.g., checking with an API)
+const hasPermission = async () => {
+  const response = await fetch('/api/check-permission');
+  const data = await response.json();
+  return data.hasAccess;
+};
-**Usage:**
-```html
-<ui-table id="myTable"></ui-table>
+export const routes: Route[] = [
+  {
+    path: '/',
+    load: () => import('./pages/home'),
+    component: 'home-page'
+  },
+  {
+    path: '/profile',
+    load: () => import('./pages/profile'),
+    component: 'profile-page',
+    guard: isAuthenticated // Redirect to home if guard returns false
+  },
+  {
+    path: '/admin',
+    load: () => import('./pages/admin'),
+    component: 'admin-page',
+    guard: hasPermission // Supports async guards
+  }
+];
-<script type="module">
-  const table = document.getElementById('myTable');
-  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>
+createRouter(routes);
 ```
-**Properties:**
-- `data` - Object with `columns` and `rows`
-  - `columns`: Array of `{ key, label, align? }`
-  - `rows`: Array of objects matching column keys
+#### 2. Create page components (with optional shared navigation)
----
+You can create a reusable navigation component:
-### 📄 Pagination (`ui-pagination`)
+**src/components/nav.ts**
+```typescript
+import { BaseComponent } from '@diniz/webcomponents';
-Smart pagination component with ellipsis for large page counts.
+class NavComponent extends BaseComponent {
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+  }
-**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 = `
+      <style>
+        nav {
+          background: var(--color-surface, #1e1e1e);
+          padding: 1rem;
+          display: flex;
+          gap: 1rem;
+          margin-bottom: 2rem;
+        }
+        nav a {
+          color: var(--color-text, #fff);
+          text-decoration: none;
+          padding: 0.5rem 1rem;
+          border-radius: 0.25rem;
+        }
+        nav a:hover {
+          background: var(--color-surface-hover, #2a2a2a);
+        }
+      </style>
+      <nav>
+        <a href="/" data-link>Home</a>
+        <a href="/about" data-link>About</a>
+        <a href="/counter" data-link>Counter</a>
+      </nav>
+    `;
+  }
+}
-**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('app-nav', NavComponent);
 ```
-**Attributes/Properties:**
-- `total` - Total number of items
-- `current-page` - Current page number
-- `page-size` - Items per page (default: 10)
+**src/pages/home.ts**
+```typescript
+import { BaseComponent } from '@diniz/webcomponents';
+import '../components/nav';
-**Computed Properties:**
-- `totalPages` - Total number of pages
+class HomePage extends BaseComponent {
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+  }
-**Events:**
-- `page-change` - Fired when page changes, includes pagination details
+  render() {
+    this.shadowRoot!.innerHTML = `
+      <app-nav></app-nav>
+      <h1>Home Page</h1>
+      <p>Welcome to my web components app!</p>
+      <ui-button variant="primary">
+        <a href="/counter" data-link style="color: inherit; text-decoration: none;">
+          Try Counter
+        </a>
+      </ui-button>
+    `;
+  }
+}
----
+customElements.define('home-page', HomePage);
+```
-### 📝 Input (`ui-input`)
+**src/pages/about.ts**
+```typescript
+import { BaseComponent } from '@diniz/webcomponents';
+import '../components/nav';
-Advanced form input with built-in validation and error handling.
+class AboutPage extends BaseComponent {
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+  }
-**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
+  render() {
+    this.shadowRoot!.innerHTML = `
+      <app-nav></app-nav>
+      <h1>About</h1>
+      <p>This is a Vite app using web components with routing.</p>
+    `;
+  }
+}
-**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>
+customElements.define('about-page', AboutPage);
 ```
-**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>
-<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>
+#### 3. Initialize the router in main.ts
-<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());
-  modal.addEventListener('modal-close', () => {
-    console.log('Modal closed');
-  });
-</script>
+**src/main.ts**
+```typescript
+import '@diniz/webcomponents';
+import '@diniz/webcomponents/dist/style.css';
+import './style.css';
+import './router'; // This loads the routes and initializes routing
 ```
-**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
+The moment you import `./router`, the routing system:
+1. ✅ Registers all event listeners for navigation
+2. ✅ Automatically loads the initial route based on the current URL
+3. ✅ Starts handling clicks on `[data-link]` elements
+4. ✅ Enables browser back/forward button support
-**Events:**
-- `modal-open` - Fired when modal opens
-- `modal-close` - Fired when modal closes
+That's it! Your app now has client-side routing with:
+- ✅ Lazy-loaded pages
+- ✅ Browser back/forward navigation
+- ✅ Declarative routing with `data-link` attribute
+- ✅ Optional route guards for protected pages
+- ✅ Reusable navigation component
----
+## Components
-### 📋 Select (`ui-select`)
+- **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/`.
-Customizable dropdown select with search capability.
+## Core Features
-**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
+### Signals & Reactivity
-**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>
-```
+Create reactive, auto-updating UI with signals. Changes automatically trigger re-renders:
-**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
-**Option Format:**
 ```typescript
-{
-  value: string;      // The option value
-  label: string;      // Display text
-  disabled?: boolean; // Optional: disable option
-}
-```
+import { BaseComponent } from '@diniz/webcomponents';
-**Events:**
-- `select-change` - Fired when selection changes
-  - `detail.value` - Selected value
-  - `detail.option` - Full option object
+class CounterComponent extends BaseComponent {
+  // Create a reactive signal with initial value 0
+  private count = this.useSignal(0);
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+  }
----
+  private increment() {
+    // Update signal value - automatically triggers re-render
+    this.count.set(this.count.get() + 1);
+  }
-### ☑️ Checkbox (`ui-checkbox`)
+  private reset() {
+    this.count.set(0);
+  }
-Flexible checkbox with indeterminate state support.
+  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()
+    );
+  }
+}
-**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
+customElements.define('counter-app', CounterComponent);
+```
-**Usage:**
+**Usage in HTML:**
 ```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>
+<counter-app></counter-app>
 ```
-**Attributes:**
-- `label` - Label text
-- `checked` - Checked state
-- `indeterminate` - Indeterminate state
-- `disabled` - Disable checkbox
-- `size` - Checkbox size (`sm` | `md` | `lg`)
+**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
-**Methods:**
-- `setChecked(checked: boolean)` - Set checked state
-- `setIndeterminate(indeterminate: boolean)` - Set indeterminate state
+### Signals with Separated HTML & TypeScript Files
-**Events:**
-- `checkbox-change` - Fired when state changes
-  - `detail.checked` - New checked state
+When using separate HTML template files, you can achieve automatic reactivity so the HTML updates whenever a signal changes:
----
+**counter.html**
+```html
+<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>
-### 🎯 Sidebar (`app-sidebar`)
+<div class="count-display">
+  Count: <span id="countValue">0</span>
+</div>
+<button id="incrementBtn">Increment</button>
+<button id="resetBtn">Reset</button>
+```
-Navigation sidebar component with links.
+**counter.ts - Automatic Reactivity Approach**
+```typescript
+import { BaseComponent } from '@diniz/webcomponents';
+import template from './counter.html?raw';
-**Features:**
-- Workspace navigation
-- Active link highlighting (via routing)
-- Theme-aware styling
+class CounterComponent extends BaseComponent {
+  private count = this.useSignal(0);
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+    this.setupEventListeners();
+    // Subscribe to signal changes - re-render when count changes
+    this.watchSignal(this.count, () => {
+      this.updateCountDisplay();
+    });
+  }
-**Usage:**
-```html
-<app-sidebar></app-sidebar>
-```
+  private increment() {
+    this.count.set(this.count.get() + 1);
+  }
----
+  private reset() {
+    this.count.set(0);
+  }
-### 📐 Layout (`app-layout`)
+  // 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());
+    }
+  }
-Application layout wrapper with navigation and sidebar.
+  private setupEventListeners() {
+    this.shadowRoot?.getElementById('incrementBtn')?.addEventListener('click',
+      () => this.increment()
+    );
+    this.shadowRoot?.getElementById('resetBtn')?.addEventListener('click',
+      () => this.reset()
+    );
+  }
-**Features:**
-- Top navigation bar
-- Sidebar integration
-- Main content area with slot
-- Responsive layout
+  render() {
+    this.shadowRoot!.innerHTML = template;
+    this.updateCountDisplay(); // Initial display
+  }
+}
-**Usage:**
-```html
-<app-layout>
-  <your-page-component></your-page-component>
-</app-layout>
+customElements.define('counter-app', CounterComponent);
 ```
----
-## Core Features
-### Base Component
+**Alternative: Full Re-render on Signal Change**
-All components extend `BaseComponent` which provides:
+For simpler components, you can also re-render the entire template when any signal changes:
-**Signal-based Reactivity:**
 ```typescript
-class MyComponent extends BaseComponent {
+class CounterComponent extends BaseComponent {
   private count = this.useSignal(0);
   connectedCallback() {
     super.connectedCallback();
-    // count.set() automatically triggers re-render
-    this.count.set(this.count.get() + 1);
+    this.render();
+    this.setupEventListeners();
+    // Re-render entire component when signal changes
+    this.watchSignal(this.count, () => this.render());
   }
-}
-```
-**State Management:**
-```typescript
-class MyComponent extends BaseComponent<{ user: string }> {
-  constructor() {
-    super();
-    this.state = { user: '' };
-  }
-  updateUser() {
-    this.setState({ user: 'Alice' }); // Triggers re-render
+  private increment() {
+    this.count.set(this.count.get() + 1);
+    // No need to manually update - render() is called automatically
   }
-}
-```
-### Router
+  private reset() {
+    this.count.set(0);
+  }
-Built-in client-side router with layouts:
+  private setupEventListeners() {
+    // Re-attach listeners after each render
+    this.shadowRoot?.getElementById('incrementBtn')?.addEventListener('click',
+      () => this.increment()
+    );
+    this.shadowRoot?.getElementById('resetBtn')?.addEventListener('click',
+      () => this.reset()
+    );
+  }
-```typescript
-const routes = [
-  {
-    path: '/',
-    layout: 'app-layout',
-    load: () => import('./features/home/home-page'),
-    component: 'home-page'
+  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();
   }
-];
+}
+customElements.define('counter-app', CounterComponent);
 ```
-### Store
+**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
-Global state management:
+### Enhanced: useSignalHtml for Direct DOM Binding
-```typescript
-import { store } from './core/store';
+For even cleaner code, use `useSignalHtml()` to create a signal that automatically updates a specific HTML element:
-store.setState({ theme: 'dark' });
-const currentState = store.getState();
+**counter.html**
+```html
+<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>
-store.subscribe(state => {
-  console.log('State changed:', state);
-});
+<div class="count-display">
+  Count: <span id="countValue">0</span>
+</div>
+<button id="incrementBtn">Increment</button>
+<button id="resetBtn">Reset</button>
 ```
-### HTTP Client
-Lightweight HTTP client with interceptor support for API requests:
+**counter.ts - Simplified with useSignalHtml**
 ```typescript
-import { http } from '@diniz/webcomponents';
+import { BaseComponent } from '@diniz/webcomponents';
+import template from './counter.html?raw';
-// Set base URL for all requests
-http.setBaseURL('https://api.example.com');
-// Set default headers
-http.setDefaultHeaders({ 'Authorization': 'Bearer token' });
+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();
+    this.render();
+    this.setupEventListeners();
+  }
-// 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}`);
-```
+  private increment() {
+    // Just update the signal - HTML updates automatically
+    this.count.set(this.count.get() + 1);
+  }
-**Request Interceptors:**
+  private reset() {
+    // Just update the signal - HTML updates automatically
+    this.count.set(0);
+  }
-```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;
-});
+  private setupEventListeners() {
+    this.shadowRoot?.getElementById('incrementBtn')?.addEventListener('click',
+      () => this.increment()
+    );
+    this.shadowRoot?.getElementById('resetBtn')?.addEventListener('click',
+      () => this.reset()
+    );
+  }
-// Handle request errors
-http.interceptors.request.use(
-  (config) => config,
-  (error) => {
-    console.error('Request failed:', error);
-    throw error;
+  render() {
+    this.shadowRoot!.innerHTML = template;
   }
-);
+}
+customElements.define('counter-app', CounterComponent);
 ```
-**Response Interceptors:**
+**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
-// 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;
-  }
-);
+useSignalHtml<T>(elementId: string, initialValue: T): Signal<T>
 ```
-**Methods:**
+Returns a signal that automatically updates the specified HTML element whenever the value changes.
-- `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
+This pattern is used throughout the demo components in `src/features/`.
-**Configuration:**
+### HTTP Client
 ```typescript
-interface RequestConfig {
-  method?: string;
-  headers?: Record<string, string>;
-  body?: string | FormData | null;
-  timeout?: number;      // Default: 30000ms
-}
-```
+import { http } from '@diniz/webcomponents';
-**Features:**
+const users = await http.get<User[]>('/api/users');
+const newUser = await http.post<User>('/api/users', data);
+```
-- ✅ 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