@strav/view 0.1.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@strav/view",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "View layer for the Strav framework — template engine, Vue SFC islands, and SPA client router",
+  "license": "MIT",
+  "keywords": [
+    "bun",
+    "framework",
+    "typescript",
+    "strav",
+    "view",
+    "template",
+    "vue",
+    "islands"
+  ],
+  "files": [
+    "src/",
+    "package.json",
+    "tsconfig.json",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./client/*": "./src/client/*.ts",
+    "./islands/*": "./src/islands/*.ts"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0",
+    "sass": "^1.80.0",
+    "@strav/kernel": "0.1.0",
+    "@strav/http": "0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "sass": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@vue/compiler-sfc": "^3.5.28"
+  },
+  "devDependencies": {
+    "sass": "^1.80.0"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/asset_versioner.ts

@@ -0,0 +1,92 @@
+import { join, resolve } from 'node:path'
+import { watch, type FSWatcher } from 'node:fs'
+
+/**
+ * Appends content-based hashes to public asset URLs for cache busting.
+ *
+ * Pre-compute hashes at boot with `add()`, then use the sync `resolve()`
+ * in templates via a ViewEngine global.
+ *
+ * @example
+ * ```typescript
+ * const assets = new AssetVersioner('./public')
+ * await assets.add('/css/app.css')
+ *
+ * ViewEngine.setGlobal('asset', (path: string) => assets.resolve(path))
+ * ```
+ *
+ * In templates: `{{ asset('/css/app.css') }}` → `/css/app.css?v=abc12345`
+ */
+export class AssetVersioner {
+  private publicDir: string
+  private cache = new Map<string, string>()
+  private watchers = new Map<string, FSWatcher>()
+
+  constructor(publicDir: string) {
+    this.publicDir = resolve(publicDir)
+  }
+
+  /**
+   * Compute the content hash for a public asset and cache the versioned URL.
+   * Returns the versioned URL (e.g. `/css/app.css?v=abc12345`).
+   * If the file doesn't exist, caches and returns the path as-is.
+   */
+  async add(publicPath: string): Promise<string> {
+    const filePath = join(this.publicDir, publicPath)
+    const file = Bun.file(filePath)
+
+    if (!(await file.exists())) {
+      this.cache.set(publicPath, publicPath)
+      return publicPath
+    }
+
+    const content = new Uint8Array(await file.arrayBuffer())
+    const hash = this.computeHash(content)
+    const versioned = `${publicPath}?v=${hash}`
+    this.cache.set(publicPath, versioned)
+    return versioned
+  }
+
+  /**
+   * Sync lookup — returns the cached versioned URL, or the original path
+   * if the asset hasn't been added yet.
+   */
+  resolve(publicPath: string): string {
+    return this.cache.get(publicPath) ?? publicPath
+  }
+
+  /**
+   * Watch a previously added asset for changes and re-hash automatically.
+   * Useful in development when CSS/JS is rebuilt by external watchers.
+   */
+  watch(publicPath: string): void {
+    if (this.watchers.has(publicPath)) return
+
+    const filePath = join(this.publicDir, publicPath)
+    let timeout: ReturnType<typeof setTimeout> | null = null
+
+    const watcher = watch(filePath, () => {
+      // Debounce — file may be written in chunks
+      if (timeout) clearTimeout(timeout)
+      timeout = setTimeout(() => {
+        this.add(publicPath)
+      }, 100)
+    })
+
+    this.watchers.set(publicPath, watcher)
+  }
+
+  /** Stop all file watchers. */
+  close(): void {
+    for (const watcher of this.watchers.values()) {
+      watcher.close()
+    }
+    this.watchers.clear()
+  }
+
+  private computeHash(content: Uint8Array): string {
+    const hasher = new Bun.CryptoHasher('md5')
+    hasher.update(content)
+    return hasher.digest('hex').slice(0, 8)
+  }
+}

package/src/cache.ts

@@ -0,0 +1,47 @@
+export interface RenderResult {
+  output: string
+  blocks: Record<string, string>
+}
+
+export type RenderFunction = (
+  data: Record<string, unknown>,
+  includeFn: IncludeFn
+) => Promise<RenderResult>
+
+export type IncludeFn = (name: string, data: Record<string, unknown>) => Promise<string>
+
+export interface CacheEntry {
+  fn: RenderFunction
+  layout?: string
+  mtime: number
+  filePath: string
+}
+
+export default class TemplateCache {
+  private entries = new Map<string, CacheEntry>()
+
+  get(name: string): CacheEntry | undefined {
+    return this.entries.get(name)
+  }
+
+  set(name: string, entry: CacheEntry): void {
+    this.entries.set(name, entry)
+  }
+
+  async isStale(name: string): Promise<boolean> {
+    const entry = this.entries.get(name)
+    if (!entry) return true
+    const file = Bun.file(entry.filePath)
+    const exists = await file.exists()
+    if (!exists) return true
+    return file.lastModified > entry.mtime
+  }
+
+  delete(name: string): void {
+    this.entries.delete(name)
+  }
+
+  clear(): void {
+    this.entries.clear()
+  }
+}

package/src/client/islands.ts

@@ -0,0 +1,84 @@
+// @ts-nocheck — Client-side script; requires DOM types provided by the app's bundler config.
+/**
+ * Vue Islands Bootstrap
+ *
+ * Auto-discovers elements with [data-vue] attributes and mounts
+ * Vue components on them via a single shared Vue app instance.
+ * All islands share the same app context (plugins, provide/inject,
+ * global components), connected to their marker elements via Teleport.
+ *
+ * Register your components on the window before this script runs:
+ *
+ *   import Counter from './components/Counter.vue'
+ *   window.__vue_components = { counter: Counter }
+ *
+ * Optionally provide a setup function to install plugins:
+ *
+ *   window.__vue_setup = (app) => {
+ *     app.use(somePlugin)
+ *     app.provide('key', value)
+ *   }
+ *
+ * Then in your .strav templates:
+ *   <vue:counter :initial="{{ count }}" label="Click me" />
+ */
+
+import { createApp, defineComponent, h, Teleport } from 'vue'
+
+declare global {
+  interface Window {
+    __vue_components?: Record<string, any>
+    __vue_setup?: (app: any) => void
+  }
+}
+
+function toPascalCase(str: string): string {
+  return str.replace(/(^|-)(\w)/g, (_match, _sep, char) => char.toUpperCase())
+}
+
+function mountIslands(): void {
+  const components = window.__vue_components ?? {}
+
+  const islands: { Component: any; props: Record<string, any>; el: HTMLElement }[] = []
+
+  document.querySelectorAll<HTMLElement>('[data-vue]').forEach(el => {
+    const name = el.dataset.vue
+    if (!name) return
+
+    const Component = components[name] ?? components[toPascalCase(name)]
+    if (!Component) {
+      console.warn(`[islands] Unknown component: ${name}`)
+      return
+    }
+
+    const props = JSON.parse(el.dataset.props ?? '{}')
+    islands.push({ Component, props, el })
+  })
+
+  if (islands.length === 0) return
+
+  const Root = defineComponent({
+    render() {
+      return islands.map(island =>
+        h(Teleport, { to: island.el }, [h(island.Component, island.props)])
+      )
+    },
+  })
+
+  const app = createApp(Root)
+
+  if (typeof window.__vue_setup === 'function') {
+    window.__vue_setup(app)
+  }
+
+  const root = document.createElement('div')
+  root.style.display = 'contents'
+  document.body.appendChild(root)
+  app.mount(root)
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', mountIslands)
+} else {
+  mountIslands()
+}

package/src/client/router.ts

@@ -0,0 +1,272 @@
+// @ts-nocheck — Client-side script; requires DOM types provided by the app's bundler config.
+
+/**
+ * Stravigor Client Router
+ *
+ * A lightweight Vue 3 router for SPA navigation within the islands architecture.
+ * Uses shared route definitions (from defineRoutes) so server and client stay in sync.
+ *
+ * Usage:
+ *   import { createRouter, useRouter, useRoute } from '@stravigor/view/client/router'
+ */
+
+import {
+  ref,
+  computed,
+  inject,
+  defineComponent,
+  h,
+  type App,
+  type Plugin,
+  type Ref,
+  type ComputedRef,
+  type InjectionKey,
+  type Component,
+  type PropType,
+} from 'vue'
+import type { SpaRouteDefinition } from '../route_types.ts'
+export { defineRoutes } from '../route_types.ts'
+export type { SpaRouteDefinition } from '../route_types.ts'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Resolved route — the current matched state. */
+export interface RouteLocation {
+  /** The full URL path */
+  path: string
+  /** Route name, or null if no match */
+  name: string | null
+  /** Extracted URL params (all strings) */
+  params: Record<string, string>
+  /** Resolved component props (from route.props function) */
+  resolvedProps: Record<string, unknown>
+  /** The matched view key, or null if 404 */
+  view: string | null
+}
+
+/** Navigation target — string path or named route. */
+export type RouteTarget = string | { name: string; params?: Record<string, string | number> }
+
+/** Router instance exposed via useRouter(). */
+export interface RouterInstance {
+  push(to: RouteTarget): void
+  replace(to: RouteTarget): void
+  back(): void
+  forward(): void
+  readonly route: ComputedRef<RouteLocation>
+}
+
+export interface RouterOptions {
+  /** Route definitions (from defineRoutes) */
+  routes: readonly SpaRouteDefinition[]
+  /** Map of view name → Vue component */
+  views: Record<string, Component>
+  /** Fallback component when no route matches */
+  fallback?: Component
+}
+
+// ---------------------------------------------------------------------------
+// Injection Keys
+// ---------------------------------------------------------------------------
+
+const ROUTER_KEY: InjectionKey<RouterInstance> = Symbol('strav-router')
+const ROUTE_KEY: InjectionKey<ComputedRef<RouteLocation>> = Symbol('strav-route')
+
+// ---------------------------------------------------------------------------
+// Route Matching
+// ---------------------------------------------------------------------------
+
+interface CompiledRoute {
+  definition: SpaRouteDefinition
+  regex: RegExp
+  paramNames: string[]
+}
+
+/** Compile a route pattern into a RegExp, extracting param names. */
+function compilePattern(pattern: string): { regex: RegExp; paramNames: string[] } {
+  const paramNames: string[] = []
+  const regexStr = pattern.replace(/:(\w+)/g, (_, name) => {
+    paramNames.push(name)
+    return '([^/]+)'
+  })
+  return { regex: new RegExp(`^${regexStr}$`), paramNames }
+}
+
+/** Build the path for a named route with param substitution. */
+function buildPath(
+  route: CompiledRoute,
+  params: Record<string, string | number>,
+): string {
+  return route.definition.path.replace(/:(\w+)/g, (_, name) => String(params[name]))
+}
+
+/** Match a path against compiled routes. Returns the first match. */
+function matchRoute(path: string, compiled: CompiledRoute[]): RouteLocation {
+  for (const route of compiled) {
+    const match = route.regex.exec(path)
+    if (match) {
+      const params: Record<string, string> = {}
+      for (let i = 0; i < route.paramNames.length; i++) {
+        params[route.paramNames[i]] = match[i + 1]
+      }
+      const resolvedProps = route.definition.props
+        ? route.definition.props(params)
+        : {}
+      return {
+        path,
+        name: route.definition.name,
+        params,
+        resolvedProps,
+        view: route.definition.view,
+      }
+    }
+  }
+  // No match — 404
+  return { path, name: null, params: {}, resolvedProps: {}, view: null }
+}
+
+// ---------------------------------------------------------------------------
+// createRouter — Vue Plugin Factory
+// ---------------------------------------------------------------------------
+
+export function createRouter(options: RouterOptions): Plugin {
+  const compiled: CompiledRoute[] = options.routes.map(def => ({
+    definition: def,
+    ...compilePattern(def.path),
+  }))
+
+  const currentPath = ref(window.location.pathname)
+
+  const currentRoute = computed(() => matchRoute(currentPath.value, compiled))
+
+  function resolvePath(to: RouteTarget): string {
+    if (typeof to === 'string') return to
+    const match = compiled.find(r => r.definition.name === to.name)
+    if (!match) {
+      console.warn(`[strav-router] Unknown route name: ${to.name}`)
+      return '/'
+    }
+    return buildPath(match, to.params ?? {})
+  }
+
+  function push(to: RouteTarget): void {
+    const path = resolvePath(to)
+    history.pushState(null, '', path)
+    currentPath.value = path
+  }
+
+  function replace(to: RouteTarget): void {
+    const path = resolvePath(to)
+    history.replaceState(null, '', path)
+    currentPath.value = path
+  }
+
+  const router: RouterInstance = {
+    push,
+    replace,
+    back: () => history.back(),
+    forward: () => history.forward(),
+    route: currentRoute,
+  }
+
+  // ---- RouterView --------------------------------------------------------
+
+  const RouterView = defineComponent({
+    name: 'RouterView',
+    setup() {
+      return () => {
+        const r = currentRoute.value
+        if (r.view && options.views[r.view]) {
+          return h(options.views[r.view], r.resolvedProps)
+        }
+        if (options.fallback) {
+          return h(options.fallback)
+        }
+        return null
+      }
+    },
+  })
+
+  // ---- RouterLink --------------------------------------------------------
+
+  const RouterLink = defineComponent({
+    name: 'RouterLink',
+    props: {
+      to: { type: [String, Object] as PropType<RouteTarget>, required: true },
+      replace: { type: Boolean, default: false },
+    },
+    setup(props, { slots, attrs }) {
+      const href = computed(() => resolvePath(props.to))
+
+      const isActive = computed(() => {
+        const h = href.value
+        const p = currentRoute.value.path
+        return p === h || p.startsWith(h + '/')
+      })
+
+      const isExactActive = computed(() => currentRoute.value.path === href.value)
+
+      function onClick(e: MouseEvent) {
+        if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return
+        e.preventDefault()
+        if (props.replace) {
+          replace(href.value)
+        } else {
+          push(href.value)
+        }
+      }
+
+      return () => h(
+        'a',
+        { href: href.value, onClick, ...attrs },
+        slots.default?.({
+          href: href.value,
+          isActive: isActive.value,
+          isExactActive: isExactActive.value,
+          navigate: onClick,
+        }),
+      )
+    },
+  })
+
+  // ---- Plugin install ----------------------------------------------------
+
+  return {
+    install(app: App) {
+      window.addEventListener('popstate', () => {
+        currentPath.value = window.location.pathname
+      })
+
+      app.provide(ROUTER_KEY, router)
+      app.provide(ROUTE_KEY, currentRoute)
+
+      app.component('RouterView', RouterView)
+      app.component('RouterLink', RouterLink)
+
+      // Backward compat: components that inject('navigate') still work
+      app.provide('navigate', (to: string) => push(to))
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Composables
+// ---------------------------------------------------------------------------
+
+/** Access the router instance for programmatic navigation. */
+export function useRouter(): RouterInstance {
+  const router = inject(ROUTER_KEY)
+  if (!router) throw new Error('[strav-router] useRouter() called outside of router context')
+  return router
+}
+
+/** Access the current reactive route location. */
+export function useRoute(): ComputedRef<RouteLocation> {
+  const route = inject(ROUTE_KEY)
+  if (!route) throw new Error('[strav-router] useRoute() called outside of router context')
+  return route
+}
+
+export type { SpaRouteDefinition }