vite-plugin-html-elements 0.0.9 → 0.1.0

package/README.md

@@ -8,9 +8,11 @@ A lightweight Vite plugin for composing reusable HTML elements in static sites.
 
 - **Zero JavaScript** - Pure static HTML output
 - **Hot Reload** - Instant updates during development
-- **Intuitive Syntax** - Natural self-closing `<element />` tags
-- **Shorthand Support** - `<element src="header.html" />`
+- **Intuitive Syntax** - Natural self-closing `<element />` tags with props and slots
+- **Route Manifests** - Explicit control over URL structure
+- **Deployment Ready** - Built-in base path support for subdirectory hosting
 - **TypeScript** - Full type safety
+- **Flexible** - Opinionated defaults or complete control
 - **Tiny** - Minimal footprint, maximum impact
 
 ## 📦 Installation
@@ -91,7 +93,7 @@ npm run build  # Production build
 
 The output is pure static HTML with all elements inlined - no `<element>` tags remain.
 
-## 📝 Syntax
+## 📝 Basic Syntax
 
 ### Shorthand (Recommended)
 
@@ -107,8 +109,55 @@ Automatically resolves to `elements/header.html`
 <element src="elements/nav/mobile.html" />
 ```
 
+### With Slots
+
+```html
+<element src="card.html">
+  <h2>Card Title</h2>
+  <p>Card content goes here</p>
+</element>
+```
+
+**src/elements/card.html:**
+
+```html
+<div class="card">
+  <slot />
+</div>
+```
+
+### With Props
+
+```html
+<element src="hero.html" title="Welcome" subtitle="Build fast static sites">
+  <button>Get Started</button>
+</element>
+```
+
+**src/elements/hero.html:**
+
+```html
+<section class="hero">
+  <h1>{{title}}</h1>
+  <p>{{subtitle}}</p>
+  <slot />
+</section>
+```
+
 ## ⚙️ Configuration
 
+### Basic Options
+
+```typescript
+interface HtmlElementsOptions {
+  debug?: boolean; // Enable verbose logging (default: false)
+  basePath?: string; // Base path for deployment (default: '/')
+  srcDir?: string; // Source directory for HTML files (default: 'src')
+  defaults?: boolean; // Use opinionated structure (default: true)
+  routes?: RouteConfig[]; // Route manifest (optional)
+}
+```
+
 ### Debug Mode
 
 Enable verbose logging to see which elements are being included:
@@ -121,23 +170,115 @@ Output:
 
 ```
 💧 Element included: elements/header.html
-💧 Element included: elements/footer.html
+💧 Element included: elements/footer.html (with slot)
+🗺️  Route: /blog -> blog.html (output: blog/index.html)
+```
+
+### Base Path
+
+Deploy to a subdirectory (e.g., GitHub Pages):
+
+```javascript
+htmlElements({
+  basePath: '/my-site',
+});
 ```
 
+All asset paths will be automatically prefixed with `/my-site`.
+
+### Custom Source Directory
+
+```javascript
+htmlElements({
+  srcDir: 'pages', // Look for HTML files in src/pages/
+});
+```
+
+### Non-Opinionated Mode
+
+Take full control over your Vite configuration:
+
+```javascript
+export default defineConfig({
+  root: './',
+  publicDir: 'static',
+  build: { outDir: 'build' },
+  plugins: [
+    htmlElements({
+      defaults: false, // Disable opinionated defaults
+      srcDir: 'pages',
+    }),
+  ],
+});
+```
+
+## 🗺️ Route Manifests
+
+Define explicit URL structures with route manifests:
+
+```javascript
+htmlElements({
+  basePath: '/my-site',
+  routes: [
+    { path: '/', source: 'index.html' },
+    { path: '/blog', source: 'blog.html' },
+    { path: '/blog/getting-started', source: 'blog/getting-started.html' },
+    { path: '/blog/advanced-tips', source: 'blog/advanced-tips.html' },
+  ],
+});
+```
+
+**Output structure:**
+
+```
+dist/
+├── index.html
+└── blog/
+    ├── index.html
+    ├── getting-started/
+    │   └── index.html
+    └── advanced-tips/
+        └── index.html
+```
+
+**Benefits:**
+
+- Clean URLs (`/blog/getting-started` instead of `/blog-getting-started.html`)
+- Explicit path control
+- Perfect for blogs, documentation, and content sites
+- Works seamlessly with static hosting (Netlify, Vercel, GitHub Pages)
+
 ## 📁 Project Structure
 
-Organize your project however you prefer. Here are some common patterns:
+### Default Structure (Opinionated)
 
-### Simple Structure
+When using `defaults: true` (the default):
 
 ```
 project/
-├── src/
-│   ├── elements/
+├── public/           # Static assets
+│   └── favicon.ico
+├── src/              # Source files (becomes root)
+│   ├── elements/     # Reusable elements
 │   │   ├── header.html
 │   │   └── footer.html
 │   ├── index.html
 │   └── about.html
+├── dist/             # Build output
+└── vite.config.js
+```
+
+### Custom Structure
+
+When using `defaults: false`:
+
+```
+project/
+├── pages/            # You control everything
+│   ├── components/
+│   ├── index.html
+│   └── about.html
+├── build/
 └── vite.config.js
 ```
 
@@ -153,11 +294,11 @@ project/
 │   │   └── nav/
 │   │       ├── mobile.html
 │   │       └── desktop.html
+│   ├── blog/
+│   │   ├── index.html
+│   │   └── post-1.html
 │   ├── index.html
-│   ├── about.html
 │   └── styles.css
-├── public/
-│   └── favicon.ico
 └── vite.config.js
 ```
 
@@ -167,18 +308,21 @@ Perfect for:
 
 - 📄 Landing pages
 - 📝 Documentation sites
-- 📰 Blogs
+- 📰 Blogs with clean URLs
 - 🎨 Marketing sites
 - 🏢 Company websites
 - 🚀 Any multi-page static site
+- 📱 Progressive web apps (start with HTML)
 
 Ideal when you want:
 
-- Reusable HTML components
+- Reusable HTML components with props and slots
 - No build complexity
+- Clean URL structures
 - Progressive enhancement
 - Fast, accessible sites
 - SEO-friendly output
+- Easy deployment to static hosts
 
 ## 💡 Philosophy
 
@@ -190,7 +334,7 @@ Start with solid HTML, add CSS for style, and layer JavaScript only where it add
 
 ## 📚 Examples
 
-### Shared Head Element
+### Shared Head Element with Props
 
 **src/elements/head.html:**
 
@@ -199,7 +343,7 @@ Start with solid HTML, add CSS for style, and layer JavaScript only where it add
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <link rel="stylesheet" href="/styles.css" />
-  <link rel="icon" href="/favicon.ico" />
+  <title>{{pageTitle}}</title>
 </head>
 ```
 
@@ -208,13 +352,55 @@ Start with solid HTML, add CSS for style, and layer JavaScript only where it add
 ```html
 <!doctype html>
 <html lang="en">
-  <element src="head.html" />
+  <element src="head.html" pageTitle="Home | My Site" />
   <body>
     <!-- content -->
   </body>
 </html>
 ```
 
+### Feature Cards with Slots
+
+**src/elements/feature-card.html:**
+
+```html
+<div class="feature-card">
+  <div class="icon">{{icon}}</div>
+  <h3>{{title}}</h3>
+  <slot />
+</div>
+```
+
+**Usage:**
+
+```html
+<element src="feature-card.html" icon="⚡" title="Fast Builds">
+  <p>Lightning-fast hot reloading with Vite.</p>
+</element>
+
+<element src="feature-card.html" icon="🎨" title="Zero JS">
+  <p>Pure static HTML output.</p>
+</element>
+```
+
+### Blog with Route Manifest
+
+```javascript
+// vite.config.js
+export default defineConfig({
+  plugins: [
+    htmlElements({
+      routes: [
+        { path: '/', source: 'index.html' },
+        { path: '/blog', source: 'blog/index.html' },
+        { path: '/blog/post-1', source: 'blog/post-1.html' },
+        { path: '/blog/post-2', source: 'blog/post-2.html' },
+      ],
+    }),
+  ],
+});
+```
+
 ### Component Library
 
 ```
@@ -231,29 +417,41 @@ elements/
 ```
 
 ```html
-<element src="buttons/primary.html" /> <element src="cards/product.html" />
+<element src="buttons/primary.html">Buy Now</element>
+<element src="cards/product.html" title="Product" price="$99">
+  <p>Product description here</p>
+</element>
 ```
 
 ## ❓ FAQ
 
-**Can I use relative paths?**  
-Yes! Paths are resolved relative to the HTML file containing the `<element />` tag.
+**Can I use props and slots together?**  
+Yes! Props replace `{{propName}}` placeholders, while slots inject content into `<slot />` tags.
+
+**Does it work with Tailwind CSS?**  
+Yes! Fully compatible with Tailwind and other CSS frameworks.
 
-**Does it work with other Vite plugins?**  
-Yes! Fully compatible with Tailwind CSS and other Vite plugins.
+**Can I deploy to GitHub Pages?**  
+Yes! Use `basePath: '/repo-name'` to match your repository name.
+
+**What's the difference between `defaults: true` and `defaults: false`?**  
+`defaults: true` applies opinionated structure (`src/` as root, `public/`, `dist/`). Set to `false` to fully control your Vite config.
 
 **Can elements include JavaScript?**  
-Elements are just HTML. You can include `<script>` tags in your elements if needed.
+Yes! Elements are just HTML. Include `<script>` tags as needed.
 
 **What about dynamic content?**  
-This plugin is for static composition at build time. For dynamic content, layer on JavaScript after your HTML is built.
+This plugin is for static composition at build time. Layer on JavaScript for dynamic behavior.
 
 **Do I need Node.js at runtime?**  
-No! The plugin runs at build time. The output is pure static HTML that works anywhere.
+No! The plugin runs at build time. Output is pure static HTML that works anywhere.
+
+**How do route manifests work with static hosting?**  
+Routes like `/blog/post-1` output to `blog/post-1/index.html`, which static hosts serve automatically at the clean URL.
 
 ## 🤝 Contributing
 
-Contributions welcome! Please open an issue or PR on GitHub.
+Contributions welcome! Please open an issue or PR on Codeberg.
 
 ## 📄 License
 
@@ -262,6 +460,6 @@ MIT
 ## 🔗 Links
 
 - [Documentation](https://htmlelements.dev)
-- [GitHub](https://codeberg.org/nexusocean/vite-plugin-html-elements)
+- [Codeberg](https://codeberg.org/nexusocean/vite-plugin-html-elements)
 - [npm](https://www.npmjs.com/package/vite-plugin-html-elements)
 - [Issues](https://codeberg.org/nexusocean/vite-plugin-html-elements/issues)

package/dist/index.d.ts

@@ -1,11 +1,43 @@
 import type { Plugin } from 'vite';
+export interface RouteConfig {
+    /**
+     * URL path for the route (e.g., '/', '/blog', '/blog/today-is-nice')
+     */
+    path: string;
+    /**
+     * Source HTML file relative to srcDir
+     */
+    source: string;
+}
 export interface HtmlElementsOptions {
     /**
      * Enable debug logging
      * @default false
      */
-    debug: boolean;
+    debug?: boolean;
+    /**
+     * Base path for deployment (e.g., '/my-site' for GitHub Pages)
+     * @default '/'
+     */
+    basePath?: string;
+    /**
+     * Route manifest for explicit path configuration
+     * If provided, automatic HTML discovery is disabled
+     */
+    routes?: RouteConfig[];
+    /**
+     * Source directory for HTML files (relative to Vite's root)
+     * @default 'src'
+     */
+    srcDir?: string;
+    /**
+     * Apply default project structure conventions
+     * When true: sets root to 'src', publicDir to '../public', outDir to '../dist'
+     * When false: respects user's Vite config completely
+     * @default false
+     */
+    defaults?: boolean;
 }
 export declare function htmlElements(options?: HtmlElementsOptions): Plugin;
-export declare function getHtmlEntries(srcDir: string): Record<string, string>;
+export declare function getHtmlEntries(srcDir: string, debug?: boolean): Record<string, string>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAA6B,MAAM,MAAM,CAAC;AAI9D,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,YAAY,CAC1B,OAAO,GAAE,mBAAsC,GAC9C,MAAM,CA8BR;AAgED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiBrE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAyC,MAAM,MAAM,CAAC;AAI1E,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IAEvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAiEtE;AAyHD,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,OAAe,GACrB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA4BxB"}

package/dist/index.js

@@ -1,20 +1,47 @@
 import { readdirSync, readFileSync, existsSync } from 'fs';
 import { resolve } from 'path';
-export function htmlElements(options = { debug: false }) {
-    const { debug } = options;
+export function htmlElements(options = {}) {
+    const { debug = false, basePath = '/', routes, srcDir = 'src', defaults = false, } = options;
     return {
         name: 'vite-plugin-html-elements',
-        config() {
-            const srcDir = 'src';
-            const resolvedSrcDir = resolve(process.cwd(), srcDir);
+        config(userConfig) {
+            const root = defaults ? srcDir : userConfig.root || process.cwd();
+            const resolvedSrcDir = defaults
+                ? resolve(process.cwd(), srcDir)
+                : resolve(root, srcDir);
+            if (debug) {
+                console.log(`🔧 html-elements config:`);
+                console.log(`   Defaults mode: ${defaults}`);
+                console.log(`   Root: ${root}`);
+                console.log(`   Source dir: ${resolvedSrcDir}`);
+                console.log(`   Base path: ${basePath}`);
+                if (routes) {
+                    console.log(`   Routes: ${routes.length} defined`);
+                }
+            }
+            if (defaults) {
+                return {
+                    root: srcDir,
+                    publicDir: '../public',
+                    base: basePath,
+                    build: {
+                        outDir: '../dist',
+                        emptyOutDir: true,
+                        rollupOptions: {
+                            input: routes
+                                ? getRoutesEntries(routes, resolvedSrcDir, debug)
+                                : getHtmlEntries(resolvedSrcDir, debug),
+                        },
+                    },
+                };
+            }
             return {
-                root: srcDir,
-                publicDir: '../public',
+                base: basePath,
                 build: {
-                    outDir: '../dist',
-                    emptyOutDir: true,
                     rollupOptions: {
-                        input: getHtmlEntries(resolvedSrcDir),
+                        input: routes
+                            ? getRoutesEntries(routes, resolvedSrcDir, debug)
+                            : getHtmlEntries(resolvedSrcDir, debug),
                     },
                 },
             };
@@ -22,20 +49,48 @@ export function htmlElements(options = { debug: false }) {
         transformIndexHtml: {
             order: 'pre',
             handler(html, _ctx) {
-                return processElements(html, debug);
+                return processElements(html, debug, srcDir);
             },
         },
     };
 }
-function processElements(html, debug) {
+function getRoutesEntries(routes, srcDir, debug) {
+    const entries = {};
+    routes.forEach((route) => {
+        const sourcePath = resolve(srcDir, route.source);
+        if (!existsSync(sourcePath)) {
+            console.error(`❌ Route source not found: ${route.source} for path ${route.path}`);
+            return;
+        }
+        // Convert route path to entry name
+        // '/' -> 'index'
+        // '/blog' -> 'blog/index'
+        // '/blog/today-is-nice' -> 'blog/today-is-nice/index'
+        let entryName;
+        if (route.path === '/') {
+            entryName = 'index';
+        }
+        else {
+            // Remove leading slash and add /index for directory structure
+            const cleanPath = route.path.replace(/^\//, '');
+            entryName = `${cleanPath}/index`;
+        }
+        entries[entryName] = sourcePath;
+        if (debug) {
+            console.log(`🗺️  Route: ${route.path} -> ${route.source} (output: ${entryName}.html)`);
+        }
+    });
+    return entries;
+}
+function processElements(html, debug, srcDir) {
     const pattern = /<element\s+src=["']([^"']+)["']([^>]*?)(?:\/>|>([\s\S]*?)<\/element>)/g;
     return html.replace(pattern, (_match, filepath, attributes, slotContent = '') => {
         let resolvedPath = filepath;
         if (!filepath.includes('elements/') && filepath.includes('.html')) {
             resolvedPath = `elements/${filepath}`;
         }
-        const srcDir = resolve(process.cwd(), 'src');
-        const fullPath = resolve(srcDir, resolvedPath);
+        const resolvedSrcDir = resolve(process.cwd(), srcDir);
+        const fullPath = resolve(resolvedSrcDir, resolvedPath);
         if (!existsSync(fullPath)) {
             console.error(`❌ Element not found: ${filepath}`);
             if (debug) {
@@ -80,7 +135,7 @@ function parseAttributes(attrString) {
     }
     return attrs;
 }
-export function getHtmlEntries(srcDir) {
+export function getHtmlEntries(srcDir, debug = false) {
     try {
         const htmlFiles = readdirSync(srcDir).filter((file) => file.endsWith('.html'));
         const entries = {};
@@ -88,10 +143,17 @@ export function getHtmlEntries(srcDir) {
             const name = file.replace('.html', '');
             entries[name] = resolve(srcDir, file);
         });
+        if (debug) {
+            console.log(`📄 Auto-discovered HTML files: ${Object.keys(entries).join(', ')}`);
+        }
         return entries;
     }
     catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
         console.warn(`⚠️  Could not read directory: ${srcDir}`);
+        if (debug) {
+            console.error(`   ${errorMessage}`);
+        }
         return {};
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-html-elements",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "description": "Modular HTML without the JavaScript",
   "author": "Vincent Medina",
   "license": "MIT",
@@ -22,24 +22,43 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "prepublishOnly": "npm run build",
+    "prepare": "npx simple-git-hooks"
+  },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
-    "eslint": "^8.0.0",
-    "eslint-config-prettier": "^9.0.0",
-    "prettier": "^3.6.2",
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^24.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.3.0",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.8.1",
+    "simple-git-hooks": "^2.13.1",
+    "tseslint": "^0.0.2",
+    "tsparser": "^1.0.2",
     "typescript": "^5.9.3",
-    "vite": "^7.2.2"
+    "vite": "^7.3.1"
   },
-  "scripts": {
-    "build": "tsc",
-    "lint": "eslint src --ext .ts",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "format:check": "prettier --check \"src/**/*.ts\"",
-    "prepublis`hO`nly": "npm run build"
+  "simple-git-hooks": {
+    "pre-commit": "npx lint-staged"
+  },
+  "lint-staged": {
+    "*.{mjs,js,ts,tsx}": [
+      "prettier --write",
+      "eslint"
+    ],
+    "*.{css,less,scss,json,graphql}": [
+      "prettier --write"
+    ]
   }
-}
+}