@strav/view 0.2.4 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/view",
-  "version": "0.2.4",
+  "version": "0.2.8",
   "type": "module",
   "description": "View layer for the Strav framework — template engine, Vue SFC islands, and SPA client router",
   "license": "MIT",
@@ -22,14 +22,15 @@
   ],
   "exports": {
     ".": "./src/index.ts",
+    "./client": "./src/client/index.ts",
     "./client/*": "./src/client/*.ts",
     "./islands/*": "./src/islands/*.ts"
   },
   "peerDependencies": {
     "vue": "^3.5.0",
     "sass": "^1.80.0",
-    "@strav/kernel": "0.1.4",
-    "@strav/http": "0.1.4"
+    "@strav/kernel": "0.2.6",
+    "@strav/http": "0.2.6"
   },
   "peerDependenciesMeta": {
     "sass": {

package/src/cache.ts

@@ -1,6 +1,7 @@
 export interface RenderResult {
   output: string
   blocks: Record<string, string>
+  stacks: Record<string, string[]>
 }
 
 export type RenderFunction = (

package/src/client/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Browser-safe exports from @strav/view
+ *
+ * This module contains only client-side functionality that can be safely
+ * bundled for the browser without pulling in Node.js dependencies.
+ */
+
+// Re-export only browser-safe route helpers
+export { route, routeUrl, registerRoutes } from './route_helper.ts'
+export type { RouteOptions } from './route_helper.ts'
+
+// Re-export client-side router (SPA router)
+export * from './router.ts'

package/src/client/route_helper.ts

@@ -0,0 +1,181 @@
+/**
+ * Browser-safe route helpers that work without the server-side router instance.
+ *
+ * These functions maintain the same API as the server-side route helpers but
+ * require route definitions to be provided at runtime or fallback to URL construction.
+ */
+
+export interface RouteOptions extends Omit<RequestInit, 'body'> {
+  params?: Record<string, any>
+  body?: any
+}
+
+// Global registry for client-side route definitions
+const clientRoutes = new Map<string, { method: string; pattern: string }>()
+
+/**
+ * Register route definitions for client-side use.
+ * This should be called during app initialization with route data from the server.
+ */
+export function registerRoutes(routes: Record<string, { method: string; pattern: string }>) {
+  Object.entries(routes).forEach(([name, def]) => {
+    clientRoutes.set(name, def)
+  })
+}
+
+/**
+ * Generate a URL for a named route with optional parameters.
+ *
+ * @example
+ * const profileUrl = routeUrl('users.profile', { id: 456 })
+ * // Returns '/users/456'
+ */
+export function routeUrl(name: string, params?: Record<string, any>): string {
+  const routeDef = clientRoutes.get(name)
+  if (!routeDef) {
+    throw new Error(`Route '${name}' not found. Make sure to call registerRoutes() with route definitions.`)
+  }
+
+  return generateUrl(routeDef.pattern, params)
+}
+
+/**
+ * Invoke a named route with automatic method detection and smart defaults.
+ *
+ * @example
+ * // Simple POST with JSON body
+ * await route('auth.register', {
+ *   name: 'John',
+ *   email: 'john@example.com',
+ *   password: 'secret'
+ * })
+ *
+ * // GET with URL parameters
+ * await route('users.show', { params: { id: 123 } })
+ */
+export async function route(
+  name: string,
+  data?: any,
+  options?: RouteOptions
+): Promise<Response> {
+  const routeDef = clientRoutes.get(name)
+  if (!routeDef) {
+    throw new Error(`Route '${name}' not found. Make sure to call registerRoutes() with route definitions.`)
+  }
+
+  // Determine if data is the body or options
+  let body: any
+  let opts: RouteOptions = {}
+
+  if (data !== undefined) {
+    // If data has params, body, or any RequestInit properties, treat it as options
+    if (
+      typeof data === 'object' &&
+      !Array.isArray(data) &&
+      !(data instanceof FormData) &&
+      !(data instanceof Blob) &&
+      !(data instanceof ArrayBuffer) &&
+      !(data instanceof URLSearchParams) &&
+      ('params' in data || 'body' in data || 'headers' in data || 'cache' in data ||
+       'credentials' in data || 'mode' in data || 'redirect' in data || 'referrer' in data)
+    ) {
+      opts = data
+      body = opts.body
+    } else {
+      // Otherwise, treat data as the body
+      body = data
+      opts = options || {}
+    }
+  } else {
+    opts = options || {}
+  }
+
+  // Generate URL with parameters
+  const generatedUrl = generateUrl(routeDef.pattern, opts.params)
+
+  // Determine method from route definition
+  const method = opts.method || routeDef.method
+
+  // Build headers with smart defaults
+  const headers = new Headers(opts.headers)
+
+  // Set default Accept header if not provided
+  if (!headers.has('Accept')) {
+    headers.set('Accept', 'application/json')
+  }
+
+  // Handle body and Content-Type
+  let requestBody: string | FormData | Blob | ArrayBuffer | URLSearchParams | undefined
+  if (body !== undefined && method !== 'GET' && method !== 'HEAD') {
+    if (body instanceof FormData || body instanceof Blob || body instanceof ArrayBuffer || body instanceof URLSearchParams) {
+      // Let fetch set the Content-Type for FormData, or use the existing type for Blob/ArrayBuffer
+      requestBody = body
+    } else if (typeof body === 'object') {
+      // JSON body
+      if (!headers.has('Content-Type')) {
+        headers.set('Content-Type', 'application/json')
+      }
+      requestBody = JSON.stringify(body)
+    } else {
+      // String or other primitive
+      requestBody = String(body)
+      if (!headers.has('Content-Type')) {
+        headers.set('Content-Type', 'text/plain')
+      }
+    }
+  }
+
+  // Set default credentials if not provided
+  const credentials = opts.credentials || 'same-origin'
+
+  // Build final fetch options
+  const fetchOptions: RequestInit = {
+    ...opts,
+    method,
+    headers,
+    credentials,
+    ...(requestBody !== undefined && { body: requestBody })
+  }
+
+  // Remove our custom properties
+  delete (fetchOptions as any).params
+
+  return fetch(generatedUrl, fetchOptions)
+}
+
+/**
+ * Generate URL from pattern and parameters (browser-safe version)
+ */
+function generateUrl(pattern: string, params?: Record<string, any>): string {
+  let url = pattern
+  const queryParams: Record<string, string> = {}
+
+  if (params) {
+    Object.entries(params).forEach(([key, value]) => {
+      const paramPattern = `:${key}`
+      const wildcardPattern = `*${key}`
+
+      if (url.includes(paramPattern)) {
+        // Replace route parameter
+        url = url.replace(paramPattern, encodeURIComponent(String(value)))
+      } else if (url.includes(wildcardPattern)) {
+        // Replace wildcard parameter
+        url = url.replace(`/${wildcardPattern}`, `/${encodeURIComponent(String(value))}`)
+      } else {
+        // Add as query parameter
+        queryParams[key] = String(value)
+      }
+    })
+  }
+
+  // Append query parameters
+  const queryString = Object.keys(queryParams)
+    .map(key => `${encodeURIComponent(key)}=${encodeURIComponent(queryParams[key] ?? '')}`)
+    .join('&')
+
+  if (queryString) {
+    url += (url.includes('?') ? '&' : '?') + queryString
+  }
+
+  return url
+}

package/src/compiler.ts

@@ -7,9 +7,10 @@ export interface CompilationResult {
 }
 
 interface StackEntry {
-  type: 'if' | 'each' | 'section'
+  type: 'if' | 'each' | 'section' | 'push' | 'prepend'
   line: number
   blockName?: string
+  stackName?: string
 }
 
 function escapeJs(str: string): string {
@@ -94,6 +95,7 @@ export function compile(tokens: Token[]): CompilationResult {
 
   lines.push('let __out = "";')
   lines.push('const __blocks = {};')
+  lines.push('const __stacks = {};')
 
   for (const token of tokens) {
     switch (token.type) {
@@ -147,7 +149,7 @@ export function compile(tokens: Token[]): CompilationResult {
     throw new TemplateError(`Unclosed @${unclosed.type} block (opened at line ${unclosed.line})`)
   }
 
-  lines.push('return { output: __out, blocks: __blocks };')
+  lines.push('return { output: __out, blocks: __blocks, stacks: __stacks };')
 
   return { code: lines.join('\n'), layout }
 }
@@ -274,6 +276,40 @@ function compileDirective(
       )
       break
 
+    case 'push': {
+      if (!token.args) throw new TemplateError(`@push requires a name at line ${token.line}`)
+      const name = token.args.replace(/^['"]|['"]$/g, '').trim()
+      const nameStr = JSON.stringify(name)
+      // Initialize stack array if it doesn't exist, then capture content and push
+      lines.push(`if (!__stacks[${nameStr}]) __stacks[${nameStr}] = [];`)
+      lines.push(`__stacks[${nameStr}].push((function() { let __out = "";`)
+      stack.push({ type: 'push', line: token.line, stackName: name })
+      break
+    }
+
+    case 'prepend': {
+      if (!token.args) throw new TemplateError(`@prepend requires a name at line ${token.line}`)
+      const name = token.args.replace(/^['"]|['"]$/g, '').trim()
+      const nameStr = JSON.stringify(name)
+      // Initialize stack array if it doesn't exist, then capture content and unshift
+      lines.push(`if (!__stacks[${nameStr}]) __stacks[${nameStr}] = [];`)
+      lines.push(`__stacks[${nameStr}].unshift((function() { let __out = "";`)
+      stack.push({ type: 'prepend', line: token.line, stackName: name })
+      break
+    }
+
+    case 'stack': {
+      if (!token.args) throw new TemplateError(`@stack requires a name at line ${token.line}`)
+      const name = token.args.replace(/^['"]|['"]$/g, '').trim()
+      const nameStr = JSON.stringify(name)
+      // Output joined stack content - merge local and passed stacks
+      lines.push(`{`)
+      lines.push(`  const __mergedStack = [...((__data.__stacks && __data.__stacks[${nameStr}]) || []), ...(__stacks[${nameStr}] || [])];`)
+      lines.push(`  __out += __mergedStack.join('');`)
+      lines.push(`}`)
+      break
+    }
+
     case 'end': {
       if (!stack.length) {
         throw new TemplateError(`Unexpected @end at line ${token.line} — no open block`)
@@ -281,6 +317,8 @@ function compileDirective(
       const top = stack.pop()!
       if (top.type === 'section') {
         lines.push(`  return __out; })();`)
+      } else if (top.type === 'push' || top.type === 'prepend') {
+        lines.push(`  return __out; })());`)
       } else if (top.type === 'each') {
         lines.push(`  }`) // close for loop
         lines.push(`}`) // close block scope

package/src/engine.ts

@@ -48,7 +48,8 @@ export default class ViewEngine {
   private async renderWithDepth(
     name: string,
     data: Record<string, unknown>,
-    depth: number
+    depth: number,
+    parentStacks: Record<string, string[]> = {}
   ): Promise<string> {
     if (depth > MAX_INCLUDE_DEPTH) {
       throw new TemplateError(
@@ -58,21 +59,82 @@ export default class ViewEngine {
 
     const entry = await this.resolve(name)
 
-    const includeFn: IncludeFn = (includeName, includeData) => {
-      return this.renderWithDepth(includeName, { ...data, ...includeData }, depth + 1)
+    // Create an include function that merges stacks from includes
+    const includeFn: IncludeFn = async (includeName, includeData) => {
+      const includeResult = await this.renderWithDepthInternal(
+        includeName,
+        { ...data, ...includeData },
+        depth + 1,
+        {}
+      )
+      // Merge include's stacks into parent stacks
+      this.mergeStacks(parentStacks, includeResult.stacks)
+      return includeResult.output
     }
 
-    const result = await entry.fn(data, includeFn)
+    // Pass parent stacks to the template
+    const dataWithStacks = { ...data, __stacks: { ...parentStacks } }
+    const result = await entry.fn(dataWithStacks, includeFn)
+
+    // Merge current template's stacks with parent stacks
+    this.mergeStacks(parentStacks, result.stacks)
 
-    // Layout inheritance: render child first, then render layout with blocks merged
+    // Layout inheritance: render child first, then render layout with blocks and stacks merged
     if (entry.layout) {
-      const layoutData = { ...data, ...result.blocks }
-      return this.renderWithDepth(entry.layout, layoutData, depth + 1)
+      const layoutData = { ...data, ...result.blocks, __stacks: parentStacks }
+      return this.renderWithDepth(entry.layout, layoutData, depth + 1, parentStacks)
     }
 
     return result.output
   }
 
+  private async renderWithDepthInternal(
+    name: string,
+    data: Record<string, unknown>,
+    depth: number,
+    parentStacks: Record<string, string[]> = {}
+  ): Promise<{ output: string; stacks: Record<string, string[]> }> {
+    if (depth > MAX_INCLUDE_DEPTH) {
+      throw new TemplateError(
+        `Maximum include depth (${MAX_INCLUDE_DEPTH}) exceeded — possible circular include`
+      )
+    }
+
+    const entry = await this.resolve(name)
+
+    const includeFn: IncludeFn = async (includeName, includeData) => {
+      const includeResult = await this.renderWithDepthInternal(
+        includeName,
+        { ...data, ...includeData },
+        depth + 1,
+        {}
+      )
+      this.mergeStacks(parentStacks, includeResult.stacks)
+      return includeResult.output
+    }
+
+    const dataWithStacks = { ...data, __stacks: { ...parentStacks } }
+    const result = await entry.fn(dataWithStacks, includeFn)
+    this.mergeStacks(parentStacks, result.stacks)
+
+    if (entry.layout) {
+      const layoutData = { ...data, ...result.blocks, __stacks: parentStacks }
+      const layoutOutput = await this.renderWithDepth(entry.layout, layoutData, depth + 1, parentStacks)
+      return { output: layoutOutput, stacks: parentStacks }
+    }
+
+    return { output: result.output, stacks: parentStacks }
+  }
+
+  private mergeStacks(target: Record<string, string[]>, source: Record<string, string[]>): void {
+    for (const [key, values] of Object.entries(source)) {
+      if (!target[key]) {
+        target[key] = []
+      }
+      target[key].push(...values)
+    }
+  }
+
   private async resolve(name: string): Promise<CacheEntry> {
     const cached = this.cache.get(name)
 

package/src/index.ts

@@ -10,8 +10,12 @@ export { defineRoutes } from './route_types.ts'
 export { spaRoutes } from './spa_routes.ts'
 export { default as ViewProvider } from './providers/view_provider.ts'
 
+// Client-side route helpers (browser-safe)
+export { route, routeUrl, registerRoutes } from './client/route_helper.ts'
+
 export type { Token, TokenType, VueAttr } from './tokenizer.ts'
 export type { CompilationResult } from './compiler.ts'
 export type { CacheEntry, RenderFunction, IncludeFn, RenderResult } from './cache.ts'
 export type { CssOptions, IslandBuilderOptions, IslandManifest } from './islands/island_builder.ts'
 export type { SpaRouteDefinition } from './route_types.ts'
+export type { RouteOptions } from './client/route_helper.ts'

package/src/islands/island_builder.ts

@@ -12,6 +12,15 @@ import { vueSfcPlugin } from './vue_plugin.ts'
 import ViewEngine from '../engine.ts'
 import type { BunPlugin } from 'bun'
 
+// Router type for route injection (optional dependency)
+interface Router {
+  getAllRoutes(): readonly {
+    name?: string
+    method: string
+    pattern: string
+  }[]
+}
+
 export interface CssOptions {
   /** Sass entry file path. e.g. 'resources/css/app.scss' */
   entry: string
@@ -62,6 +71,7 @@ export class IslandBuilder {
   private _manifest: IslandManifest | null = null
   private cssOpts: { entry: string; outFile: string; outDir: string; basePath: string } | null = null
   private _cssVersion: string | null = null
+  private router: Router | null = null
 
   constructor(options: IslandBuilderOptions = {}) {
     this.islandsDir = resolve(options.islandsDir ?? './resources/islands')
@@ -137,6 +147,25 @@ export class IslandBuilder {
     const lines: string[] = []
 
     lines.push(`import { createApp, defineComponent, h, Teleport } from 'vue';`)
+
+    // Auto-inject route definitions if router is available
+    if (this.router) {
+      const routeDefinitions = this.extractRouteDefinitions()
+      const routeCount = Object.keys(routeDefinitions).length
+
+      if (routeCount > 0) {
+        lines.push(`import { registerRoutes } from '@strav/view/client';`)
+        lines.push('')
+        lines.push(`// Auto-injected route definitions (${routeCount} routes)`)
+        lines.push(`registerRoutes(${JSON.stringify(routeDefinitions, null, 2)});`)
+        console.log(`[islands] ✅ Auto-injecting ${routeCount} route definitions:`, Object.keys(routeDefinitions))
+      } else {
+        console.log(`[islands] ⚠️ Router provided but no named routes found - skipping route auto-injection`)
+      }
+    } else {
+      // Silent: No router provided - skipping route auto-injection
+    }
+
     lines.push('')
 
     if (setupPath) {
@@ -297,6 +326,35 @@ export class IslandBuilder {
     )
   }
 
+  /** Extract route definitions for client-side registration. */
+  private extractRouteDefinitions(): Record<string, { method: string; pattern: string }> {
+    if (!this.router) return {}
+
+    const routeMap: Record<string, { method: string; pattern: string }> = {}
+
+    for (const route of this.router.getAllRoutes()) {
+      if (route.name) {  // Only include named routes
+        routeMap[route.name] = {
+          method: route.method,
+          pattern: route.pattern
+        }
+      }
+    }
+
+    return routeMap
+  }
+
+  /**
+   * Build the islands bundle with route auto-injection.
+   * @param router - Router instance containing routes to inject
+   */
+  async buildWithRoutes(router: Router): Promise<boolean> {
+    this.router = router  // Set the router for this build
+    const result = await this.build()  // Use existing build method
+    this.router = null    // Clear router reference after build
+    return result
+  }
+
   /** Build the islands bundle. Returns true if islands were found and built. */
   async build(): Promise<boolean> {
     const islands = this.discoverIslands()

package/src/tokenizer.ts

@@ -30,6 +30,9 @@ const DIRECTIVES = new Set([
   'csrf',
   'class',
   'style',
+  'push',
+  'prepend',
+  'stack',
 ])
 
 export function tokenize(source: string): Token[] {