From 74a841fc32016350e24565a92183f1fce20d575c Mon Sep 17 00:00:00 2001
From: Natxo <1172351+natxocc@users.noreply.github.com>
Date: Mon, 16 Mar 2026 23:12:25 +0100
Subject: [PATCH] Create Plugin.md

---
 src/Plugin.md | 327 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 327 insertions(+)
 create mode 100644 src/Plugin.md

diff --git a/src/Plugin.md b/src/Plugin.md
new file mode 100644
index 0000000..15a5084
--- /dev/null
+++ b/src/Plugin.md
@@ -0,0 +1,327 @@
+## 🚀 Vite Plugin for SigPro Router
+
+Automatically generates routes from your file structure with zero configuration.
+
+### 📁 File Structure
+
+```
+src/
+  pages/
+    index.js              → /
+    about.js              → /about
+    contact.js            → /contact
+    user/
+      index.js            → /user
+      [id].js             → /user/:id
+      [id]/
+        posts.js          → /user/:id/posts
+        [pid].js          → /user/:id/posts/:pid
+    blog/
+      [year]/
+        [month]/
+          [slug].js       → /blog/:year/:month/:slug
+    dashboard/
+      index.js            → /dashboard
+      settings.js         → /dashboard/settings
+```
+
+### 📦 Installation
+
+```bash
+npm install --save-dev @sigpro/vite-plugin
+# or
+yarn add -D @sigpro/vite-plugin
+# or
+bun add -D @sigpro/vite-plugin
+```
+
+### ⚙️ Setup in `vite.config.js`
+
+```javascript
+import { defineConfig } from 'vite';
+import sigproRouter from '@sigpro/vite-plugin';
+
+export default defineConfig({
+  plugins: [sigproRouter()]
+});
+```
+
+### 🎯 Usage in Your App
+
+```javascript
+// src/app.js
+import { $, html } from 'sigpro';
+import { routes } from 'virtual:sigpro-routes';
+
+const App = () => html`
+  <div class="app">
+    <nav>
+      <a href="#/">Home</a>
+      <a href="#/about">About</a>
+      <a href="#/user/42">User Profile</a>
+      <a href="#/user/42/posts">User Posts</a>
+      <a href="#/user/42/posts/123">Specific Post</a>
+      <a href="#/blog/2024/03/hello-world">Blog Post</a>
+    </nav>
+    
+    <main>
+      ${$.router(routes)}
+    </main>
+  </div>
+`;
+
+document.body.appendChild(App());
+```
+
+### 📄 Creating Pages
+
+#### Static Pages
+
+```javascript
+// src/pages/index.js
+export default (params) => $.page(() => {
+  return html`
+    <div>
+      <h1>Home Page</h1>
+      <p>Welcome to my app!</p>
+    </div>
+  `;
+});
+
+// src/pages/about.js
+export default (params) => $.page(() => {
+  return html`
+    <div>
+      <h1>About Us</h1>
+      <p>Learn more about our company.</p>
+    </div>
+  `;
+});
+```
+
+#### Dynamic Pages with Parameters
+
+```javascript
+// src/pages/user/[id].js
+export default (params) => $.page(({ onUnmount }) => {
+  // params = { id: '42' }
+  const userId = params.id;
+  const userData = $(null);
+  const loading = $(true);
+  
+  // Fetch user data
+  const fetchUser = async () => {
+    loading(true);
+    try {
+      const res = await fetch(`/api/users/${userId}`);
+      const data = await res.json();
+      userData(data);
+    } catch (error) {
+      console.error('Error:', error);
+    } finally {
+      loading(false);
+    }
+  };
+  
+  fetchUser();
+  
+  return html`
+    <div>
+      ${loading() ? html`
+        <div class="loading">Loading user ${userId}...</div>
+      ` : html`
+        <h1>${userData().name}</h1>
+        <p>Email: ${userData().email}</p>
+        <p>Role: ${userData().role}</p>
+      `}
+    </div>
+  `;
+});
+
+// src/pages/user/[id]/posts/[pid].js
+export default (params) => $.page(() => {
+  // params = { id: '42', pid: '123' }
+  const { id, pid } = params;
+  
+  return html`
+    <div>
+      <h1>Post ${pid}</h1>
+      <p>From user ${id}</p>
+      <a href="#/user/${id}/posts">← Back to posts</a>
+    </div>
+  `;
+});
+```
+
+#### Nested Dynamic Routes
+
+```javascript
+// src/pages/blog/[year]/[month]/[slug].js
+export default (params) => $.page(() => {
+  // params = { year: '2024', month: '03', slug: 'hello-world' }
+  const { year, month, slug } = params;
+  
+  return html`
+    <article>
+      <h1>${slug.replace(/-/g, ' ')}</h1>
+      <time>${year}/${month}</time>
+      <div class="content">
+        <p>Blog post content here...</p>
+      </div>
+      <a href="#/blog">← Back to blog</a>
+    </article>
+  `;
+});
+```
+
+### 🔄 Automatic Cleanup
+
+```javascript
+// src/pages/user/[id].js
+export default (params) => $.page(({ onUnmount }) => {
+  const userId = params.id;
+  
+  // ✅ Auto-cleaned by SigPro
+  $.effect(() => {
+    console.log('User effect running for', userId);
+  });
+  
+  // ⚠️ Manual cleanup needed
+  const interval = setInterval(() => {
+    console.log('Polling user', userId);
+  }, 5000);
+  
+  const handleResize = () => {
+    console.log('Window resized');
+  };
+  window.addEventListener('resize', handleResize);
+  
+  // ✅ Cleanup with onUnmount
+  onUnmount(() => {
+    clearInterval(interval);
+    window.removeEventListener('resize', handleResize);
+    console.log('🧹 Cleaned up user', userId);
+  });
+  
+  return html`<div>User ${userId}</div>`;
+});
+```
+
+### 🧭 Navigation
+
+```javascript
+// Programmatic navigation
+import { $ } from 'sigpro';
+
+$.router.go('/user/42');
+$.router.go('/user/42/posts/123');
+$.router.go('about'); // Auto-adds leading slash
+
+// In templates
+html`
+  <nav>
+    <a href="#/">Home</a>
+    <a href="#/user/${userId}">Profile</a>
+    <button @click=${() => $.router.go('/contact')}>
+      Contact
+    </button>
+  </nav>
+`;
+```
+
+### 🎨 Route Parameters in Components
+
+```javascript
+// Access params anywhere
+const currentUserId = () => {
+  const match = window.location.hash.match(/^#\/user\/([^/]+)/);
+  return match ? match[1] : null;
+};
+
+// Use in components
+$.component('user-header', (props) => {
+  const userId = currentUserId();
+  
+  return html`
+    <header>
+      <h1>User Dashboard: ${userId}</h1>
+    </header>
+  `;
+}, []);
+```
+
+### ⚡ Advanced: Custom 404 Page
+
+```javascript
+// src/pages/404.js
+export default (params) => $.page(() => {
+  return html`
+    <div class="text-center py-12">
+      <h1 class="text-4xl font-bold mb-4">404</h1>
+      <p class="text-gray-600 mb-6">Page not found</p>
+      <a href="#/" class="text-blue-500 hover:underline">
+        Go back home
+      </a>
+    </div>
+  `;
+});
+
+// The router automatically shows 404 when no route matches
+```
+
+### 📊 Route Order (Automatic)
+
+The plugin automatically orders routes from most specific to least specific:
+
+```javascript
+// Generated order:
+[
+  { path: '/user/:id/posts/:pid' },  // Most specific first
+  { path: '/user/:id/posts' },
+  { path: '/user/:id' },
+  { path: '/user' },
+  { path: '/about' },
+  { path: '/' },                      // Least specific last
+]
+```
+
+### 🎯 API Reference
+
+#### Virtual Module
+```javascript
+import { routes } from 'virtual:sigpro-routes';
+```
+
+#### Route Object
+```javascript
+{
+  path: string,      // '/user/:id' - Auto-generated from file structure
+  component: Function // Page component that receives params
+}
+```
+
+### 💡 Pro Tips
+
+1. **Index files** become the parent route
+   - `user/index.js` → `/user`
+   - `user/[id]/index.js` → `/user/:id`
+
+2. **Square brackets** `[param]` become route parameters `:param`
+   - `[id].js` → `/:id`
+   - `[slug].js` → `/:slug`
+
+3. **Nested folders** create nested routes
+   - `user/[id]/posts/[pid].js` → `/user/:id/posts/:pid`
+
+4. **Cleanup** is automatic for pages, but manual for intervals/listeners
+
+### 🚀 Benefits
+
+- ✅ **Zero config** - Just create files in `src/pages/`
+- ✅ **Auto-discovery** - No need to manually define routes
+- ✅ **File-based routing** - Intuitive and scalable
+- ✅ **Dynamic routes** - `[param]` syntax for parameters
+- ✅ **Nested routes** - Mirror your folder structure
+- ✅ **Automatic ordering** - Most specific routes first
+- ✅ **TypeScript ready** - Works with `.tsx` files
+- ✅ **Memory leak free** - Built on `$.page` cleanup