create-viteframe 1.0.0

package/template/src/core/router.js

@@ -0,0 +1,303 @@
+/**
+ * Router — File-based SPA routing
+ * 
+ * Naming conventions (auto-discovered via Vite's import.meta.glob):
+ *   Static pages:  landing.page.html
+ *   Dynamic pages: [id]user.page.html          → /user/:id
+ *                  [id-name-age]profile.page.html → /profile/:id/:name/:age
+ * 
+ * Routes are intercepted on all <a href="..."> clicks.
+ * History API (pushState) is used for navigation.
+ */
+
+import { processComponentTags, executeComponentScripts } from './components.js'
+import { globalState } from './state.js'
+
+// ─── Route registry ───────────────────────────────────────────────
+class Router {
+  #routes = []
+  #currentPage = null
+  #outlet = null
+  #hooks = { before: [], after: [] }
+  #pageModules = {}
+
+  constructor() {
+    this.#loadRoutes()
+    this.#listen()
+  }
+
+  /**
+   * Discover all page files via Vite glob
+   * Pages live in /src/pages/
+   */
+  #loadRoutes() {
+    // Vite glob — static + dynamic pages
+    const pages = import.meta.glob('/src/pages/**/*.page.html', {
+      query: '?raw',
+      import: 'default',
+      eager: false
+    })
+
+    const dynPages = import.meta.glob('/src/pages/**/*dyn.page.html', {
+      query: '?raw',
+      import: 'default',
+      eager: false
+    })
+
+    const allPages = { ...pages, ...dynPages }
+
+    for (const [filePath, loader] of Object.entries(allPages)) {
+      const route = this.#filePathToRoute(filePath)
+      this.#routes.push({ ...route, loader })
+    }
+
+    // Sort: static before dynamic, longer before shorter
+    this.#routes.sort((a, b) => {
+      if (a.isDynamic !== b.isDynamic) return a.isDynamic ? 1 : -1
+      return b.pattern.length - a.pattern.length
+    })
+
+    console.log('[Router] Registered routes:', this.#routes.map(r => r.path))
+  }
+
+  /**
+   * Convert a file path to a route config
+   * 
+   * /src/pages/landing.page.html            → { path: '/', pattern: '/' }
+   * /src/pages/about.page.html              → { path: '/about', pattern: '/about' }
+   * /src/pages/[id]user.page.html           → { path: '/user/:id', pattern: '/user/:id', params: ['id'] }
+   * /src/pages/[id-name-age]profile.page.html → { path: '/profile/:id/:name/:age', params: ['id','name','age'] }
+   */
+  #filePathToRoute(filePath) {
+    // Extract filename without path prefix
+    const fileName = filePath.replace('/src/pages/', '').replace(/^.*\//, '')
+
+    // Check for dynamic route: [params]name.dyn.page.html or [params]name.page.html
+    const dynMatch = fileName.match(/^\[([^\]]+)\]([^.]+)(?:dyn)?\.page\.html$/)
+    if (dynMatch) {
+      const paramNames = dynMatch[1].split('-')
+      const pageName = dynMatch[2]
+      const paramSegments = paramNames.map(p => `:${p}`).join('/')
+      const path = `/${pageName}/${paramSegments}`
+      const regex = this.#buildRegex(path)
+      return { filePath, path, pattern: path, isDynamic: true, paramNames, regex }
+    }
+
+    // Static page
+    const staticMatch = fileName.match(/^(.+)\.page\.html$/)
+    if (staticMatch) {
+      const name = staticMatch[1]
+      const path = name === 'landing' ? '/' : `/${name}`
+      const regex = new RegExp(`^${path === '/' ? '/?$' : path + '/?$'}`)
+      return { filePath, path, pattern: path, isDynamic: false, paramNames: [], regex }
+    }
+
+    throw new Error(`Invalid page filename: ${fileName}`)
+  }
+
+  #buildRegex(pattern) {
+    const escaped = pattern
+      .replace(/\//g, '\\/')
+      .replace(/:([^/]+)/g, '([^/]+)')
+    return new RegExp(`^${escaped}\\/?$`)
+  }
+
+  /**
+   * Match a URL pathname to a registered route
+   */
+  #match(pathname) {
+    for (const route of this.#routes) {
+      const m = pathname.match(route.regex)
+      if (m) {
+        const params = {}
+        route.paramNames.forEach((name, i) => {
+          params[name] = decodeURIComponent(m[i + 1])
+        })
+        return { route, params }
+      }
+    }
+    return null
+  }
+
+  /**
+   * Parse ?key=value query string
+   */
+  #parseQuery(search) {
+    const q = {}
+    new URLSearchParams(search).forEach((v, k) => { q[k] = v })
+    return q
+  }
+
+  /**
+   * Navigate to a path (pushes to history)
+   */
+  async navigate(path, options = {}) {
+    const { replace = false, state = {} } = options
+    const method = replace ? 'replaceState' : 'pushState'
+    window.history[method](state, '', path)
+    await this.#render(path)
+  }
+
+  /**
+   * Render the current URL
+   */
+  async #render(pathname) {
+    if (!this.#outlet) {
+      this.#outlet = document.getElementById('router-outlet')
+    }
+
+    const url = new URL(pathname, window.location.origin)
+    const match = this.#match(url.pathname)
+
+    // Run before hooks
+    for (const hook of this.#hooks.before) {
+      const cont = await hook({ pathname: url.pathname, match })
+      if (cont === false) return
+    }
+
+    // Update global router state
+    globalState.set('route', {
+      pathname: url.pathname,
+      params: match?.params ?? {},
+      query: this.#parseQuery(url.search)
+    })
+
+    if (!match) {
+      this.#outlet.innerHTML = this.#render404(url.pathname)
+      return
+    }
+
+    // Transition out
+    this.#outlet.classList.add('page-exit')
+    await sleep(120)
+
+    try {
+      const html = await match.route.loader()
+      this.#outlet.innerHTML = html
+      this.#outlet.classList.remove('page-exit')
+      this.#outlet.classList.add('page-enter')
+
+      // Inject route context into page
+      this.#injectRouteContext(match.params, this.#parseQuery(url.search))
+
+      // Process <component> tags in the loaded page
+      await processComponentTags(this.#outlet)
+
+      // Fire page lifecycle
+      await this.#runPageLifecycle(this.#outlet, match.params, this.#parseQuery(url.search))
+
+      await sleep(10)
+      this.#outlet.classList.remove('page-enter')
+    } catch (e) {
+      console.error('[Router] Failed to load page:', e)
+      this.#outlet.innerHTML = this.#renderError(e)
+    }
+
+    // Run after hooks
+    for (const hook of this.#hooks.after) {
+      await hook({ pathname: url.pathname, match })
+    }
+
+    // Scroll to top
+    window.scrollTo({ top: 0, behavior: 'smooth' })
+  }
+
+  /**
+   * Inject route params/query as data attributes + window.__route
+   */
+  #injectRouteContext(params, query) {
+    window.__route = { params, query }
+    // Also expose on page element
+    const page = this.#outlet.firstElementChild
+    if (page) {
+      Object.entries(params).forEach(([k, v]) => page.dataset[k] = v)
+    }
+  }
+
+  /**
+   * Run onMount lifecycle function if page exports one
+   * Pages can define: <script data-lifecycle> export function onMount(ctx) { ... } </script>
+   */
+  async #runPageLifecycle(container, params, query) {
+    const scripts = container.querySelectorAll('script[data-lifecycle]')
+    for (const script of scripts) {
+      try {
+        // Rewrite root-relative imports to absolute URLs so they resolve
+        // correctly when executed from a blob: URL (which has no base path)
+        const base = window.location.origin
+        const code = script.textContent.replace(
+          /from\s+['"](\/[^'"]+)['"]/g,
+          (_, path) => `from '${base}${path}'`
+        )
+        const blob = new Blob([code], { type: 'text/javascript' })
+        const blobUrl = URL.createObjectURL(blob)
+        const mod = await import(/* @vite-ignore */ blobUrl)
+        URL.revokeObjectURL(blobUrl)
+        if (typeof mod.onMount === 'function') {
+          await mod.onMount({ params, query, globalState })
+        }
+      } catch (e) {
+        console.error('[Router] Page lifecycle error:', e)
+      }
+    }
+  }
+
+  /**
+   * Listen for link clicks + popstate
+   */
+  #listen() {
+    // Intercept all <a href> clicks
+    document.addEventListener('click', (e) => {
+      const a = e.target.closest('a[href]')
+      if (!a) return
+      const href = a.getAttribute('href')
+      // Skip external, hash-only, or download links
+      if (!href || href.startsWith('http') || href.startsWith('//') || href.startsWith('#') || a.hasAttribute('download') || a.target === '_blank') return
+      e.preventDefault()
+      this.navigate(href)
+    })
+
+    // Browser back/forward
+    window.addEventListener('popstate', () => {
+      this.#render(window.location.pathname + window.location.search)
+    })
+  }
+
+  /** Hooks API */
+  beforeEach(fn) { this.#hooks.before.push(fn); return this }
+  afterEach(fn)  { this.#hooks.after.push(fn); return this }
+
+  #render404(path) {
+    return `
+      <div class="error-page">
+        <span class="error-code">404</span>
+        <p>No page matches <code>${path}</code></p>
+        <a href="/" class="btn">← Back home</a>
+      </div>`
+  }
+
+  #renderError(e) {
+    return `
+      <div class="error-page">
+        <span class="error-code">ERR</span>
+        <p>${e.message}</p>
+        <a href="/" class="btn">← Back home</a>
+      </div>`
+  }
+
+  /** Get current route state */
+  get current() {
+    return globalState.get('route')
+  }
+}
+
+function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms))
+}
+
+// ─── Export singleton ────────────────────────────────────────────
+export const router = new Router()
+
+export function navigate(path, options) {
+  return router.navigate(path, options)
+}

package/template/src/core/state.js

@@ -0,0 +1,132 @@
+/**
+ * StateManager — Global + scoped reactive state
+ * 
+ * Usage:
+ *   import { globalState, createPageState } from './state.js'
+ * 
+ *   globalState.set('user', { name: 'Alice' })
+ *   globalState.get('user')
+ *   globalState.subscribe('user', (val) => console.log(val))
+ * 
+ *   const ps = createPageState({ count: 0 })
+ *   ps.set('count', ps.get('count') + 1)
+ */
+
+class StateStore {
+  #data = {}
+  #listeners = {}
+
+  constructor(initial = {}) {
+    this.#data = structuredClone(initial)
+  }
+
+  get(key) {
+    return this.#data[key]
+  }
+
+  getAll() {
+    return structuredClone(this.#data)
+  }
+
+  set(key, value) {
+    const prev = this.#data[key]
+    this.#data[key] = value
+    this.#notify(key, value, prev)
+    return this
+  }
+
+  update(key, updater) {
+    const next = updater(this.#data[key])
+    this.set(key, next)
+    return this
+  }
+
+  merge(key, partial) {
+    const current = this.#data[key] ?? {}
+    this.set(key, { ...current, ...partial })
+    return this
+  }
+
+  delete(key) {
+    const prev = this.#data[key]
+    delete this.#data[key]
+    this.#notify(key, undefined, prev)
+    return this
+  }
+
+  subscribe(key, callback) {
+    if (!this.#listeners[key]) this.#listeners[key] = new Set()
+    this.#listeners[key].add(callback)
+    // Return unsubscribe fn
+    return () => this.#listeners[key].delete(callback)
+  }
+
+  subscribeAll(callback) {
+    return this.subscribe('*', callback)
+  }
+
+  #notify(key, value, prev) {
+    this.#listeners[key]?.forEach(cb => cb(value, prev))
+    this.#listeners['*']?.forEach(cb => cb(key, value, prev))
+  }
+
+  // Bind a DOM element's text/value to a state key
+  bind(key, element, transform = v => v ?? '') {
+    const update = (val) => {
+      if (element.tagName === 'INPUT' || element.tagName === 'TEXTAREA' || element.tagName === 'SELECT') {
+        element.value = transform(val)
+      } else {
+        element.textContent = transform(val)
+      }
+    }
+    update(this.get(key))
+    return this.subscribe(key, update)
+  }
+
+  // Bind with two-way sync (input → state)
+  bindInput(key, element) {
+    const unsub = this.bind(key, element)
+    const handler = (e) => this.set(key, e.target.value)
+    element.addEventListener('input', handler)
+    return () => {
+      unsub()
+      element.removeEventListener('input', handler)
+    }
+  }
+
+  reset(initial = {}) {
+    this.#data = structuredClone(initial)
+    this.#listeners = {}
+  }
+}
+
+// ─── Singleton global state ───────────────────────────────────────
+export const globalState = new StateStore({
+  theme: 'dark',
+  user: null,
+  notifications: []
+})
+
+// ─── Factory for page / component scoped state ───────────────────
+export function createPageState(initial = {}) {
+  return new StateStore(initial)
+}
+
+// ─── Computed values (derived state) ─────────────────────────────
+export function computed(deps, stores, computeFn) {
+  const run = () => computeFn(...deps.map((key, i) => stores[i].get(key)))
+  let value = run()
+  const listeners = new Set()
+
+  deps.forEach((key, i) => {
+    stores[i].subscribe(key, () => {
+      value = run()
+      listeners.forEach(cb => cb(value))
+    })
+  })
+
+  return {
+    get: () => value,
+    subscribe: (cb) => { listeners.add(cb); return () => listeners.delete(cb) }
+  }
+}

package/template/src/main.js

@@ -0,0 +1,46 @@
+/**
+ * ViteFrame — main entry
+ * Bootstraps the router, state, and initial render
+ */
+
+import { router, navigate } from './core/router.js'
+import { globalState, createPageState, computed } from './core/state.js'
+import { mountComponent, loadComponent, processComponentTags } from './core/components.js'
+
+// ─── Theme init ──────────────────────────────────────────────────
+const savedTheme = localStorage.getItem('vf-theme') || 'dark'
+globalState.set('theme', savedTheme)
+document.documentElement.setAttribute('data-theme', savedTheme)
+
+globalState.subscribe('theme', (theme) => {
+  document.documentElement.setAttribute('data-theme', theme)
+  localStorage.setItem('vf-theme', theme)
+})
+
+// ─── Guard example: redirect /admin if not authed ────────────────
+router.beforeEach(({ pathname }) => {
+  // if (pathname.startsWith('/admin') && !globalState.get('user')) {
+  //   router.navigate('/login')
+  //   return false
+  // }
+})
+
+// ─── Expose ALL core APIs on window.__vf ─────────────────────────
+// Lifecycle scripts access these via window.__vf to avoid bare
+// import() paths that break inside blob: URLs.
+window.__vf = {
+  router,
+  navigate,
+  globalState,
+  createPageState,
+  computed,
+  mountComponent,
+  loadComponent,
+  processComponentTags,
+}
+
+// ─── Initial render ──────────────────────────────────────────────
+router.navigate(window.location.pathname + window.location.search, { replace: true })
+
+console.log('%c ViteFrame ⚡ ', 'background:#7c3aed;color:#fff;padding:4px 8px;border-radius:4px;font-weight:bold')
+console.log('Access framework: window.__vf')

package/template/src/pages/[id]post.page.html

@@ -0,0 +1,72 @@
+<div class="page">
+  <component src="header"></component>
+  <main class="page-content">
+    <div class="container" style="max-width:680px;">
+
+      <a href="/" class="btn btn-ghost" style="margin-bottom:24px;display:inline-flex;">← Back</a>
+
+      <!-- Route info card -->
+      <div class="card" style="background:var(--bg-2);border-style:dashed;margin-bottom:24px;">
+        <p class="text-xs text-mono text-muted" style="margin-bottom:10px;">
+          DYNAMIC ROUTE · [id]post.page.html → /post/:id
+        </p>
+        <div class="flex gap-6">
+          <div>
+            <div class="text-xs text-muted">param: id</div>
+            <div class="text-mono text-accent" style="font-size:1.4rem;font-weight:700;" id="r-id">—</div>
+          </div>
+          <div>
+            <div class="text-xs text-muted">query string</div>
+            <div class="text-mono" style="font-size:.85rem;color:var(--green);" id="r-query">none</div>
+          </div>
+        </div>
+      </div>
+
+      <!-- Post content -->
+      <article>
+        <span class="badge badge-purple" id="post-cat">—</span>
+        <h1 id="post-title" class="mt-4 fade-up">—</h1>
+        <p class="text-sm text-muted mt-4" id="post-meta"></p>
+        <div class="divider"></div>
+        <p id="post-body" class="fade-up delay-1"></p>
+      </article>
+
+      <!-- Prev / Next -->
+      <div class="flex-between mt-8">
+        <a href="#" id="nav-prev" class="btn btn-ghost">← Prev</a>
+        <a href="#" id="nav-next" class="btn btn-ghost">Next →</a>
+      </div>
+
+    </div>
+  </main>
+</div>
+
+<script data-lifecycle>
+const POSTS = [
+  { id:1, title:'Getting started with ViteFrame', cat:'Tutorial', author:'Alice', date:'Jan 2025', body:'ViteFrame is scaffolded directly into your project. Every file in src/core/ is yours to read and modify. Start with router.js to understand how pages are discovered via import.meta.glob, then explore state.js for the reactive store.' },
+  { id:2, title:'Building reactive components',   cat:'Guide',    author:'Bob',   date:'Feb 2025', body:'Components in ViteFrame are plain HTML files with optional <style> and <script> blocks. Props are injected via {{propName}} template syntax before the HTML is inserted into the DOM. Scripts run automatically after mounting.' },
+  { id:3, title:'State management patterns',      cat:'Advanced', author:'Carol', date:'Mar 2025', body:'Use globalState for data shared across pages (auth, theme, cart). Use createPageState inside onMount for data scoped to a single page visit — it is garbage collected when you navigate away, keeping memory clean.' },
+]
+
+export function onMount({ params, query }) {
+  const id = parseInt(params.id) || 1
+  const post = POSTS.find(p => p.id === id) || POSTS[0]
+  const idx  = POSTS.indexOf(post)
+
+  document.getElementById('r-id').textContent    = params.id
+  document.getElementById('r-query').textContent = Object.keys(query).length
+    ? JSON.stringify(query) : 'none'
+
+  document.getElementById('post-cat').textContent   = post.cat
+  document.getElementById('post-title').textContent = post.title
+  document.getElementById('post-meta').textContent  = `By ${post.author} · ${post.date}`
+  document.getElementById('post-body').textContent  = post.body
+
+  const prev = POSTS[(idx - 1 + POSTS.length) % POSTS.length]
+  const next = POSTS[(idx + 1) % POSTS.length]
+  const pEl  = document.getElementById('nav-prev')
+  const nEl  = document.getElementById('nav-next')
+  pEl.href = `/post/${prev.id}`; pEl.textContent = `← ${prev.title.slice(0,20)}…`
+  nEl.href = `/post/${next.id}`; nEl.textContent = `${next.title.slice(0,20)}… →`
+}
+</script>

package/template/src/pages/about.page.html

@@ -0,0 +1,40 @@
+<div class="page">
+  <component src="header"></component>
+  <main class="page-content">
+    <div class="container" style="max-width:680px;">
+
+      <p class="text-xs text-mono text-muted mb-4 fade-up">about.page.html → /about</p>
+      <h1 class="fade-up">About</h1>
+      <p class="mt-4 fade-up delay-1">
+        ViteFrame is a minimal SPA framework scaffolded into your project — no black boxes,
+        no hidden build steps. The entire framework is three files totalling ~380 lines of
+        readable JavaScript that live in your <code>src/core/</code> folder.
+      </p>
+
+      <div class="divider mt-8"></div>
+
+      <h2 class="mt-8 fade-up">Project structure</h2>
+      <div class="code-block mt-4 fade-up delay-1">src/
+├── core/
+│   ├── router.js       <span class="cmt"># File-based SPA router</span>
+│   ├── state.js        <span class="cmt"># Reactive state (global + page-scoped)</span>
+│   └── components.js   <span class="cmt"># Dynamic HTML component loader</span>
+├── pages/
+│   ├── landing.page.html          <span class="cmt"># → /</span>
+│   ├── about.page.html            <span class="cmt"># → /about</span>
+│   ├── docs.page.html             <span class="cmt"># → /docs</span>
+│   └── [id]post.page.html         <span class="cmt"># → /post/:id  (dynamic)</span>
+├── components/
+│   ├── header.comp.html
+│   └── toast.comp.html
+├── styles/
+│   └── main.css        <span class="cmt"># Design tokens + utilities</span>
+└── main.js             <span class="cmt"># Bootstrap</span></div>
+
+      <div class="flex gap-4 mt-8 fade-up">
+        <a href="/docs" class="btn btn-primary">Read the docs →</a>
+        <a href="/" class="btn btn-ghost">← Home</a>
+      </div>
+    </div>
+  </main>
+</div>