create-viteframe 1.0.0

package/README.md

@@ -0,0 +1,228 @@
+# create-viteframe
+
+Scaffold a new ViteFrame app — a lightweight SPA framework built on Vite with file-based routing, reactive state, and dynamic HTML components. No external JS dependencies.
+
+## Quick start
+
+```bash
+npm create viteframe@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Or with pnpm / yarn:
+
+```bash
+pnpm create viteframe my-app
+yarn create viteframe my-app
+```
+
+---
+
+## What you get
+
+```
+src/
+├── core/
+│   ├── router.js       # File-based SPA router (~180 lines)
+│   ├── state.js        # Reactive state store (~100 lines)
+│   └── components.js   # Dynamic component loader (~120 lines)
+├── pages/
+│   ├── landing.page.html          # → /
+│   ├── about.page.html            # → /about
+│   ├── docs.page.html             # → /docs
+│   └── [id]post.page.html         # → /post/:id
+├── components/
+│   ├── header.comp.html
+│   └── toast.comp.html
+├── styles/
+│   └── main.css        # Design tokens + utility classes
+└── main.js             # Bootstrap
+```
+
+All framework code lives in your project — read it, modify it, own it.
+
+---
+
+## Routing
+
+File name determines the route. Drop files in `src/pages/`.
+
+| File | Route |
+|------|-------|
+| `landing.page.html` | `/` |
+| `about.page.html` | `/about` |
+| `[id]post.page.html` | `/post/:id` |
+| `[id-slug]post.page.html` | `/post/:id/:slug` |
+| `[lang-id]post.page.html` | `/post/:lang/:id` |
+
+### Programmatic navigation
+
+```js
+window.__vf.navigate('/about')
+window.__vf.navigate('/post/42', { replace: true })
+```
+
+---
+
+## State
+
+### Global state
+
+Shared across all pages. Persists during navigation.
+
+```js
+const { globalState } = window.__vf
+
+globalState.set('user', { name: 'Alice' })
+globalState.get('user')
+globalState.subscribe('user', (val) => console.log(val))
+
+// Bind value → DOM (auto-updates when state changes)
+globalState.bind('user', el, u => u?.name ?? 'Guest')
+
+// Two-way bind: input ↔ state
+globalState.bindInput('search', inputEl)
+
+// Partial merge
+globalState.merge('settings', { darkMode: true })
+```
+
+### Page state
+
+Isolated to a single page visit. Created inside `onMount`, discarded on navigation.
+
+```js
+export function onMount() {
+  const { createPageState } = window.__vf
+  const state = createPageState({ count: 0, open: false })
+
+  state.update('count', n => n + 1)
+  state.bind('count', document.getElementById('counter'))
+}
+```
+
+### Computed values
+
+```js
+const { computed, globalState } = window.__vf
+
+const fullName = computed(
+  ['firstName', 'lastName'],
+  [globalState, globalState],
+  (first, last) => `${first} ${last}`
+)
+
+fullName.get()              // 'Alice Smith'
+fullName.subscribe(v => …)  // fires when either dep changes
+```
+
+---
+
+## Components
+
+Components are `.comp.html` files in `src/components/`. They support scoped `<style>` and `<script>` blocks.
+
+### Use in HTML
+
+```html
+<!-- Simple -->
+<component src="header"></component>
+
+<!-- With props via data-* attributes -->
+<component src="card" data-title="Hello" data-body="World"></component>
+```
+
+### Template syntax
+
+```html
+<!-- src/components/card.comp.html -->
+<div class="card">
+  <h3>{{title}}</h3>
+  <p>{{body}}</p>
+</div>
+```
+
+### Mount from JavaScript
+
+```js
+const { mountComponent } = window.__vf
+
+await mountComponent('#target', 'card', { title: 'Hello', body: 'World' })
+```
+
+---
+
+## Page lifecycle
+
+Add `<script data-lifecycle>` to any page and export `onMount`:
+
+```html
+<script data-lifecycle>
+export function onMount({ params, query, globalState }) {
+  // params  → route params  e.g. { id: '42' }
+  // query   → ?key=val      e.g. { tab: 'info' }
+  // globalState → shared store
+
+  console.log('id:', params.id)
+  console.log('tab:', query.tab)
+
+  const { createPageState } = window.__vf
+  const state = createPageState({ count: 0 })
+}
+</script>
+```
+
+---
+
+## Navigation guards
+
+In `src/main.js`:
+
+```js
+router.beforeEach(({ pathname }) => {
+  if (pathname.startsWith('/admin') && !globalState.get('user')) {
+    router.navigate('/login')
+    return false  // cancel navigation
+  }
+})
+```
+
+---
+
+## Toast notifications
+
+Include `<component src="toast">` on a page, then anywhere:
+
+```js
+window.toast('Saved!', 'success')          // green
+window.toast('Something broke', 'error')   // red
+window.toast('FYI', 'info', 5000)          // purple, 5s
+```
+
+---
+
+## CSS design tokens
+
+All colors, spacing, and radii are CSS variables in `src/styles/main.css`.
+
+```css
+/* Override in your own CSS */
+:root {
+  --accent:   #your-color;
+  --radius:   12px;
+}
+```
+
+Dark/light theme is toggled by setting `data-theme="light"` on `<html>`:
+
+```js
+window.__vf.globalState.set('theme', 'light')
+```
+
+---
+
+## License
+
+MIT

package/bin/create.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import fs from 'fs'
+import path from 'path'
+import { execSync } from 'child_process'
+import { fileURLToPath } from 'url'
+import readline from 'readline'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const templateDir = path.join(__dirname, '../template')
+
+// ─── Colors ──────────────────────────────────────────────────────
+const c = {
+  reset:  '\x1b[0m',
+  bold:   '\x1b[1m',
+  dim:    '\x1b[2m',
+  purple: '\x1b[35m',
+  green:  '\x1b[32m',
+  cyan:   '\x1b[36m',
+  yellow: '\x1b[33m',
+  red:    '\x1b[31m',
+}
+const bold   = s => `${c.bold}${s}${c.reset}`
+const purple = s => `${c.purple}${s}${c.reset}`
+const green  = s => `${c.green}${s}${c.reset}`
+const dim    = s => `${c.dim}${s}${c.reset}`
+const yellow = s => `${c.yellow}${s}${c.reset}`
+const red    = s => `${c.red}${s}${c.reset}`
+
+// ─── Prompt helper ───────────────────────────────────────────────
+function prompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  return new Promise(resolve => {
+    rl.question(question, answer => { rl.close(); resolve(answer.trim()) })
+  })
+}
+
+// ─── Copy template recursively ───────────────────────────────────
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true })
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath  = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath)
+    } else {
+      // Rename _gitignore → .gitignore (npm strips dot-files from published packages)
+      const finalDest = destPath.replace(/_gitignore$/, '.gitignore')
+      fs.copyFileSync(srcPath, finalDest)
+    }
+  }
+}
+
+// ─── Main ─────────────────────────────────────────────────────────
+async function main() {
+  console.log()
+  console.log(bold(purple('  ⚡ ViteFrame')))
+  console.log(dim('  File-based SPA framework powered by Vite\n'))
+
+  // Project name from arg or prompt
+  let projectName = process.argv[2]
+  if (!projectName) {
+    projectName = await prompt(`  ${bold('Project name')} ${dim('(my-app)')} › `)
+    if (!projectName) projectName = 'my-app'
+  }
+
+  // Sanitize
+  const dirName = projectName.replace(/\s+/g, '-').toLowerCase()
+  const targetDir = path.resolve(process.cwd(), dirName)
+
+  // Check if dir exists
+  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+    const overwrite = await prompt(`  ${yellow('!')} Directory "${dirName}" is not empty. Overwrite? ${dim('(y/N)')} › `)
+    if (!overwrite.toLowerCase().startsWith('y')) {
+      console.log(`\n  ${red('Aborted.')}\n`)
+      process.exit(1)
+    }
+    fs.rmSync(targetDir, { recursive: true, force: true })
+  }
+
+  // Detect package manager
+  const agent = process.env.npm_config_user_agent || ''
+  const pm = agent.startsWith('pnpm') ? 'pnpm'
+           : agent.startsWith('yarn') ? 'yarn'
+           : 'npm'
+
+  // Copy template
+  console.log(`\n  Creating ${bold(dirName)}...\n`)
+  copyDir(templateDir, targetDir)
+
+  // Write package.json with project name
+  const pkgPath = path.join(targetDir, 'package.json')
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
+  pkg.name = dirName
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+
+  // Done
+  const rel = path.relative(process.cwd(), targetDir)
+  const cdCmd = rel === dirName ? dirName : rel
+
+  console.log(`  ${green('✓')} Created ${bold(dirName)}\n`)
+  console.log(`  Next steps:\n`)
+  console.log(`    ${dim('$')} ${bold(`cd ${cdCmd}`)}`)
+  console.log(`    ${dim('$')} ${bold(`${pm} install`)}`)
+  console.log(`    ${dim('$')} ${bold(`${pm} run dev`)}`)
+  console.log()
+  console.log(`  ${dim('Docs → src/pages/docs.page.html')}`)
+  console.log()
+}
+
+main().catch(e => {
+  console.error(red(`\n  Error: ${e.message}\n`))
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "create-viteframe",
+  "version": "1.0.0",
+  "description": "Create a new ViteFrame app — file-based routing, reactive state, dynamic components",
+  "keywords": ["vite", "spa", "router", "framework", "scaffold"],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-viteframe": "./bin/create.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/template/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+.DS_Store

package/template/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>ViteFrame App</title>
+  <link rel="stylesheet" href="/src/styles/main.css" />
+</head>
+<body>
+  <div id="app">
+    <div id="router-outlet"></div>
+  </div>
+  <script type="module" src="/src/main.js"></script>
+</body>
+</html>

package/template/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "my-viteframe-app",
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "vite": "^5.0.0"
+  }
+}

package/template/src/components/header.comp.html

@@ -0,0 +1,42 @@
+<header class="vf-header">
+  <div class="container flex-between">
+    <a href="/" class="vf-logo">⚡ ViteFrame</a>
+    <nav class="flex gap-4">
+      <a href="/" class="vf-nav-link">Home</a>
+      <a href="/about" class="vf-nav-link">About</a>
+      <a href="/docs" class="vf-nav-link">Docs</a>
+    </nav>
+    <button class="btn btn-ghost" id="vf-theme-btn" style="padding:6px 12px;font-size:.8rem;">◑</button>
+  </div>
+</header>
+
+<style>
+.vf-header {
+  position: sticky; top: 0; z-index: 100; height: 56px;
+  display: flex; align-items: center;
+  background: color-mix(in srgb, var(--bg) 80%, transparent);
+  backdrop-filter: blur(12px);
+  border-bottom: 1px solid var(--border);
+}
+.vf-logo { font-weight: 800; color: var(--text); font-size: .95rem; }
+.vf-nav-link {
+  font-size: .875rem; font-weight: 500; color: var(--text-2);
+  padding: 4px 8px; border-radius: 6px; transition: all .15s;
+}
+.vf-nav-link:hover,
+.vf-nav-link.active { color: var(--text); background: var(--surface-2); }
+</style>
+
+<script>
+(function () {
+  // Theme toggle
+  document.getElementById('vf-theme-btn')?.addEventListener('click', () => {
+    const next = document.documentElement.getAttribute('data-theme') === 'dark' ? 'light' : 'dark'
+    window.__vf?.globalState.set('theme', next)
+  })
+  // Active link
+  document.querySelectorAll('.vf-nav-link').forEach(a => {
+    a.classList.toggle('active', a.getAttribute('href') === location.pathname)
+  })
+})()
+</script>

package/template/src/components/toast.comp.html

@@ -0,0 +1,12 @@
+<div id="toast-container"></div>
+
+<script>
+// window.toast('Message', 'success' | 'error' | 'info', ms?)
+window.toast = function (msg, type = 'info', ms = 3000) {
+  let el = document.getElementById('toast-container')
+  if (!el) { el = document.createElement('div'); el.id = 'toast-container'; document.body.append(el) }
+  const t = Object.assign(document.createElement('div'), { className: `toast toast-${type}`, textContent: msg })
+  el.append(t)
+  setTimeout(() => { t.classList.add('exit'); t.addEventListener('animationend', () => t.remove()) }, ms)
+}
+</script>

package/template/src/core/components.js

@@ -0,0 +1,134 @@
+/**
+ * ComponentLoader — Dynamic HTML component loading system
+ * 
+ * Naming: anything ending in .comp.html
+ * 
+ * Usage in HTML:
+ *   <component src="header"></component>
+ *   <component src="card" props='{"title":"Hello"}'></component>
+ * 
+ * Usage in JS:
+ *   import { loadComponent, mountComponent } from './components.js'
+ *   const html = await loadComponent('header', { user: 'Alice' })
+ *   await mountComponent('#target', 'card', { title: 'Hello' })
+ */
+
+const componentCache = new Map()
+
+/**
+ * Fetch and parse a .comp.html file
+ * Props are injected as {{propName}} template variables
+ */
+export async function loadComponent(name, props = {}) {
+  const cacheKey = name
+  
+  if (!componentCache.has(cacheKey)) {
+    const path = `/src/components/${name}.comp.html`
+    const res = await fetch(path)
+    if (!res.ok) throw new Error(`Component not found: ${name} (${path})`)
+    const text = await res.text()
+    componentCache.set(cacheKey, text)
+  }
+
+  let html = componentCache.get(cacheKey)
+
+  // Inject props via {{propName}} syntax
+  html = interpolate(html, props)
+
+  return html
+}
+
+/**
+ * Mount a component into a DOM element
+ */
+export async function mountComponent(selectorOrEl, name, props = {}) {
+  const el = typeof selectorOrEl === 'string'
+    ? document.querySelector(selectorOrEl)
+    : selectorOrEl
+
+  if (!el) throw new Error(`Mount target not found: ${selectorOrEl}`)
+  
+  const html = await loadComponent(name, props)
+  el.innerHTML = html
+
+  // Auto-process any nested <component> tags
+  await processComponentTags(el)
+
+  // Run any inline <script> tags in the component
+  await executeComponentScripts(el)
+
+  return el
+}
+
+/**
+ * Process all <component src="name"> tags in a container
+ */
+export async function processComponentTags(container = document) {
+  const tags = container.querySelectorAll('component[src]')
+  const tasks = Array.from(tags).map(async (tag) => {
+    const name = tag.getAttribute('src')
+    const propsAttr = tag.getAttribute('props')
+    const props = propsAttr ? JSON.parse(propsAttr) : {}
+
+    // Merge data-* attributes as props too
+    Object.entries(tag.dataset).forEach(([k, v]) => {
+      try { props[k] = JSON.parse(v) } catch { props[k] = v }
+    })
+
+    try {
+      const html = await loadComponent(name, props)
+      const wrapper = document.createElement('div')
+      wrapper.className = tag.className || ''
+      wrapper.innerHTML = html
+      tag.replaceWith(wrapper)
+      await processComponentTags(wrapper)
+      await executeComponentScripts(wrapper)
+    } catch (e) {
+      console.error(`Failed to load component <${name}>:`, e)
+      tag.replaceWith(createErrorPlaceholder(name, e.message))
+    }
+  })
+  await Promise.all(tasks)
+}
+
+/**
+ * Execute <script> tags inside a freshly-inserted HTML fragment
+ */
+export async function executeComponentScripts(container) {
+  const scripts = container.querySelectorAll('script')
+  for (const script of scripts) {
+    const newScript = document.createElement('script')
+    newScript.type = script.type || 'text/javascript'
+    if (script.src) {
+      newScript.src = script.src
+    } else {
+      newScript.textContent = script.textContent
+    }
+    script.replaceWith(newScript)
+  }
+}
+
+/**
+ * Simple {{key}} template interpolation
+ * Supports nested: {{user.name}}
+ */
+function interpolate(template, data) {
+  return template.replace(/\{\{([\w.]+)\}\}/g, (_, path) => {
+    const value = path.split('.').reduce((obj, key) => obj?.[key], data)
+    return value !== undefined ? String(value) : ''
+  })
+}
+
+function createErrorPlaceholder(name, msg) {
+  const div = document.createElement('div')
+  div.style.cssText = 'border:1px dashed #ff4444;padding:8px;color:#ff4444;font-size:12px;font-family:monospace'
+  div.textContent = `⚠ Component "${name}": ${msg}`
+  return div
+}
+
+/**
+ * Clear the component cache (useful during HMR / dev)
+ */
+export function clearComponentCache() {
+  componentCache.clear()
+}