@diniz/webcomponents 1.1.6 → 1.1.7

package/README.md

@@ -47,6 +47,352 @@ document.body.innerHTML = `
 `;
 ```
 
+## Quick Start with Vite (No Framework)
+
+Create a new Vite project without any framework to use these web components:
+
+### 1. Create a new Vite project
+
+```bash
+npm create vite@latest my-app -- --template vanilla-ts
+cd my-app
+```
+
+### 2. Install the web components library
+
+```bash
+npm install @diniz/webcomponents
+```
+
+### 3. Import components in your `src/main.ts`
+
+```typescript
+import '@diniz/webcomponents';
+import '@diniz/webcomponents/dist/style.css';
+import './style.css';
+
+document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
+  <div>
+    <h1>My Web Components App</h1>
+    
+    <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>
+`;
+
+// Listen to component events
+document.querySelector('ui-button')?.addEventListener('click', () => {
+  console.log('Button clicked!');
+});
+
+document.querySelector('ui-input')?.addEventListener('input', (e: Event) => {
+  const input = e.target as HTMLInputElement;
+  console.log('Input value:', input.value);
+});
+```
+
+### 4. Run the development server
+
+```bash
+npm run dev
+```
+
+Your app is now running with web components! Open your browser and start building.
+
+### Example: Building a Counter with Signals
+
+Create reactive components using the signals system:
+
+**src/components/counter.ts**
+```typescript
+import { BaseComponent } from '@diniz/webcomponents';
+
+class CounterComponent extends BaseComponent {
+  private count = this.useSignal(0);
+  
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+  }
+
+  private increment() {
+    this.count.set(this.count.get() + 1);
+  }
+
+  private decrement() {
+    this.count.set(this.count.get() - 1);
+  }
+
+  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);
+```
+
+**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>
+    <my-counter></my-counter>
+  </div>
+`;
+```
+
+### Adding Routing to Your App
+
+The library includes a built-in router for client-side navigation. Here's how to set it up:
+
+#### 1. Create your route configuration
+
+**src/router.ts**
+```typescript
+import { createRouter, type Route } from '@diniz/webcomponents';
+
+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'
+  }
+];
+
+// Initialize the router with your routes
+// The router automatically sets up navigation and loads the initial route
+createRouter(routes);
+
+// Optional: specify a custom app container selector (default is '#app')
+// createRouter(routes, '#my-app-container');
+```
+
+> **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.
+
+**Optional: Adding Route Guards**
+
+You can protect routes with guard functions that return a boolean or a Promise:
+
+```typescript
+import { createRouter, type Route } from '@diniz/webcomponents';
+
+// Example: Synchronous guard
+const isAuthenticated = () => {
+  return localStorage.getItem('user') !== null;
+};
+
+// 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;
+};
+
+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
+  }
+];
+
+createRouter(routes);
+```
+
+#### 2. Create page components (with optional shared navigation)
+
+You can create a reusable navigation component:
+
+**src/components/nav.ts**
+```typescript
+import { BaseComponent } from '@diniz/webcomponents';
+
+class NavComponent extends BaseComponent {
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+  }
+
+  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>
+    `;
+  }
+}
+
+customElements.define('app-nav', NavComponent);
+```
+
+**src/pages/home.ts**
+```typescript
+import { BaseComponent } from '@diniz/webcomponents';
+import '../components/nav';
+
+class HomePage extends BaseComponent {
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+  }
+
+  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);
+```
+
+**src/pages/about.ts**
+```typescript
+import { BaseComponent } from '@diniz/webcomponents';
+import '../components/nav';
+
+class AboutPage extends BaseComponent {
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+  }
+
+  render() {
+    this.shadowRoot!.innerHTML = `
+      <app-nav></app-nav>
+      <h1>About</h1>
+      <p>This is a Vite app using web components with routing.</p>
+    `;
+  }
+}
+
+customElements.define('about-page', AboutPage);
+```
+
+#### 3. Initialize the router in main.ts
+
+**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
+```
+
+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
+
+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
 
 - **ui-button** - Button with variants, sizes, icons

package/dist/README.md

@@ -47,6 +47,352 @@ document.body.innerHTML = `
 `;
 ```
 
+## Quick Start with Vite (No Framework)
+
+Create a new Vite project without any framework to use these web components:
+
+### 1. Create a new Vite project
+
+```bash
+npm create vite@latest my-app -- --template vanilla-ts
+cd my-app
+```
+
+### 2. Install the web components library
+
+```bash
+npm install @diniz/webcomponents
+```
+
+### 3. Import components in your `src/main.ts`
+
+```typescript
+import '@diniz/webcomponents';
+import '@diniz/webcomponents/dist/style.css';
+import './style.css';
+
+document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
+  <div>
+    <h1>My Web Components App</h1>
+    
+    <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>
+`;
+
+// Listen to component events
+document.querySelector('ui-button')?.addEventListener('click', () => {
+  console.log('Button clicked!');
+});
+
+document.querySelector('ui-input')?.addEventListener('input', (e: Event) => {
+  const input = e.target as HTMLInputElement;
+  console.log('Input value:', input.value);
+});
+```
+
+### 4. Run the development server
+
+```bash
+npm run dev
+```
+
+Your app is now running with web components! Open your browser and start building.
+
+### Example: Building a Counter with Signals
+
+Create reactive components using the signals system:
+
+**src/components/counter.ts**
+```typescript
+import { BaseComponent } from '@diniz/webcomponents';
+
+class CounterComponent extends BaseComponent {
+  private count = this.useSignal(0);
+  
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+  }
+
+  private increment() {
+    this.count.set(this.count.get() + 1);
+  }
+
+  private decrement() {
+    this.count.set(this.count.get() - 1);
+  }
+
+  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);
+```
+
+**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>
+    <my-counter></my-counter>
+  </div>
+`;
+```
+
+### Adding Routing to Your App
+
+The library includes a built-in router for client-side navigation. Here's how to set it up:
+
+#### 1. Create your route configuration
+
+**src/router.ts**
+```typescript
+import { createRouter, type Route } from '@diniz/webcomponents';
+
+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'
+  }
+];
+
+// Initialize the router with your routes
+// The router automatically sets up navigation and loads the initial route
+createRouter(routes);
+
+// Optional: specify a custom app container selector (default is '#app')
+// createRouter(routes, '#my-app-container');
+```
+
+> **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.
+
+**Optional: Adding Route Guards**
+
+You can protect routes with guard functions that return a boolean or a Promise:
+
+```typescript
+import { createRouter, type Route } from '@diniz/webcomponents';
+
+// Example: Synchronous guard
+const isAuthenticated = () => {
+  return localStorage.getItem('user') !== null;
+};
+
+// 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;
+};
+
+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
+  }
+];
+
+createRouter(routes);
+```
+
+#### 2. Create page components (with optional shared navigation)
+
+You can create a reusable navigation component:
+
+**src/components/nav.ts**
+```typescript
+import { BaseComponent } from '@diniz/webcomponents';
+
+class NavComponent extends BaseComponent {
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+  }
+
+  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>
+    `;
+  }
+}
+
+customElements.define('app-nav', NavComponent);
+```
+
+**src/pages/home.ts**
+```typescript
+import { BaseComponent } from '@diniz/webcomponents';
+import '../components/nav';
+
+class HomePage extends BaseComponent {
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+  }
+
+  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);
+```
+
+**src/pages/about.ts**
+```typescript
+import { BaseComponent } from '@diniz/webcomponents';
+import '../components/nav';
+
+class AboutPage extends BaseComponent {
+  connectedCallback() {
+    super.connectedCallback();
+    this.render();
+  }
+
+  render() {
+    this.shadowRoot!.innerHTML = `
+      <app-nav></app-nav>
+      <h1>About</h1>
+      <p>This is a Vite app using web components with routing.</p>
+    `;
+  }
+}
+
+customElements.define('about-page', AboutPage);
+```
+
+#### 3. Initialize the router in main.ts
+
+**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
+```
+
+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
+
+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
 
 - **ui-button** - Button with variants, sizes, icons