npm - @netrojs/fnetro - Versions diffs - 0.2.20 → 0.3.0 - Mend

@netrojs/fnetro 0.2.20 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/client.ts CHANGED Viewed

@@ -1,99 +1,58 @@
 // ─────────────────────────────────────────────────────────────────────────────
 //  FNetro · client.ts
-//  SolidJS hydration · SPA routing · client middleware · SEO sync · prefetch
+//  Vue 3 SSR hydration · Vue Router SPA · reactive page data · SEO sync
 // ─────────────────────────────────────────────────────────────────────────────
-import { createSignal, createMemo, createComponent } from 'solid-js'
-import { hydrate } from 'solid-js/web'
 import {
-  resolveRoutes, compilePath, matchPath,
-  SPA_HEADER, STATE_KEY, PARAMS_KEY, SEO_KEY,
-  type AppConfig, type ResolvedRoute, type CompiledPath,
-  type LayoutDef, type SEOMeta, type ClientMiddleware,
+  createSSRApp,
+  defineAsyncComponent,
+  defineComponent,
+  h,
+  inject,
+  reactive,
+  readonly,
+  type Component,
+  type InjectionKey,
+} from 'vue'
+import {
+  createRouter,
+  createWebHistory,
+  RouterView,
+} from 'vue-router'
+import {
+  isAsyncLoader,
+  resolveRoutes,
+  toVueRouterPath,
+  compilePath,
+  matchPath,
+  SPA_HEADER,
+  STATE_KEY,
+  PARAMS_KEY,
+  SEO_KEY,
+  DATA_KEY,
+  type AppConfig,
+  type LayoutDef,
+  type SEOMeta,
+  type ClientMiddleware,
 } from './core'
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 1  Compiled route cache (module-level, populated on boot)
-// ══════════════════════════════════════════════════════════════════════════════
-interface CRoute { route: ResolvedRoute; cp: CompiledPath }
-let _routes:    CRoute[]          = []
-let _appLayout: LayoutDef | undefined
-function findRoute(pathname: string) {
-  for (const { route, cp } of _routes) {
-    const params = matchPath(cp, pathname)
-    if (params !== null) return { route, params }
-  }
-  return null
-}
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 2  Navigation state signal
-// ══════════════════════════════════════════════════════════════════════════════
-interface NavState {
-  path:   string
-  data:   Record<string, unknown>
-  params: Record<string, string>
-}
-// Populated by createAppRoot(); exposed so navigate() can update it.
-let _setNav: ((s: NavState) => void) | null = null
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 3  Client middleware
-// ══════════════════════════════════════════════════════════════════════════════
-const _mw: ClientMiddleware[] = []
-/**
- * Register a client-side navigation middleware.
- * Must be called **before** `boot()`.
- *
- * @example
- * useClientMiddleware(async (url, next) => {
- *   if (!isLoggedIn() && url.startsWith('/dashboard')) {
- *     await navigate('/login')
- *     return                   // cancel original navigation
- *   }
- *   await next()
- * })
- */
-export function useClientMiddleware(mw: ClientMiddleware): void {
-  _mw.push(mw)
-}
+// ── SEO ───────────────────────────────────────────────────────────────────────
-async function runMiddleware(url: string, done: () => Promise<void>): Promise<void> {
-  const chain = [..._mw, async (_u: string, next: () => Promise<void>) => { await done(); await next() }]
-  let i = 0
-  const run = async (): Promise<void> => {
-    const fn = chain[i++]
-    if (fn) await fn(url, run)
-  }
-  await run()
-}
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 4  SEO — client-side <head> sync
-// ══════════════════════════════════════════════════════════════════════════════
-function setMeta(selector: string, attr: string, val: string | undefined): void {
+function setMeta(selector: string, attr: string, val?: string): void {
   if (!val) { document.querySelector(selector)?.remove(); return }
   let el = document.querySelector<HTMLMetaElement>(selector)
   if (!el) {
     el = document.createElement('meta')
-    const m = /\[(\w+[:-]?\w*)="([^"]+)"\]/.exec(selector)
-    if (m) el.setAttribute(m[1], m[2])
+    // Destructuring with defaults avoids string|undefined from noUncheckedIndexedAccess
+    const [, attrName = '', attrVal = ''] = /\[([^=]+)="([^"]+)"\]/.exec(selector) ?? []
+    if (attrName) el.setAttribute(attrName, attrVal)
     document.head.appendChild(el)
   }
   el.setAttribute(attr, val)
 }
-function syncSEO(seo: SEOMeta): void {
+export function syncSEO(seo: SEOMeta): void {
   if (seo.title) document.title = seo.title
   setMeta('[name="description"]',        'content', seo.description)
   setMeta('[name="keywords"]',           'content', seo.keywords)
   setMeta('[name="robots"]',             'content', seo.robots)
@@ -108,220 +67,243 @@ function syncSEO(seo: SEOMeta): void {
   setMeta('[name="twitter:description"]','content', seo.twitterDescription)
   setMeta('[name="twitter:image"]',      'content', seo.twitterImage)
-  // Canonical link
-  const canon = seo.canonical
-  let linkEl = document.querySelector<HTMLLinkElement>('link[rel="canonical"]')
-  if (canon) {
-    if (!linkEl) {
-      linkEl = document.createElement('link')
-      linkEl.rel = 'canonical'
-      document.head.appendChild(linkEl)
+  let link = document.querySelector<HTMLLinkElement>('link[rel="canonical"]')
+  if (seo.canonical) {
+    if (!link) {
+      link = document.createElement('link')
+      link.rel = 'canonical'
+      document.head.appendChild(link)
     }
-    linkEl.href = canon
+    link.href = seo.canonical
   } else {
-    linkEl?.remove()
+    link?.remove()
   }
 }
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 5  Prefetch cache
-// ══════════════════════════════════════════════════════════════════════════════
+// ── SPA data fetch + prefetch cache ──────────────────────────────────────────
-interface NavPayload {
+interface SpaPayload {
   state:  Record<string, unknown>
   params: Record<string, string>
   seo:    SEOMeta
-  url:    string
 }
-const _cache = new Map<string, Promise<NavPayload>>()
+// Module-level cache so repeated visits to the same URL don't re-fetch
+const _fetchCache = new Map<string, Promise<SpaPayload>>()
-function fetchPayload(href: string): Promise<NavPayload> {
-  if (!_cache.has(href)) {
-    _cache.set(
+function fetchSPA(href: string): Promise<SpaPayload> {
+  if (!_fetchCache.has(href)) {
+    _fetchCache.set(
       href,
-      fetch(href, { headers: { [SPA_HEADER]: '1' } })
-        .then(r => {
-          if (!r.ok) throw new Error(`${r.status} ${r.statusText}`)
-          return r.json() as Promise<NavPayload>
-        }),
+      fetch(href, { headers: { [SPA_HEADER]: '1' } }).then(r => {
+        if (!r.ok) throw new Error(`[fnetro] ${r.status} ${r.statusText} — ${href}`)
+        return r.json() as Promise<SpaPayload>
+      }),
     )
   }
-  return _cache.get(href)!
-}
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 6  navigate / prefetch
-// ══════════════════════════════════════════════════════════════════════════════
-export interface NavigateOptions {
-  replace?: boolean
-  scroll?:  boolean
-}
-export async function navigate(to: string, opts: NavigateOptions = {}): Promise<void> {
-  const u = new URL(to, location.origin)
-  if (u.origin !== location.origin) { location.href = to; return }
-  if (!findRoute(u.pathname))        { location.href = to; return }
-  await runMiddleware(u.pathname, async () => {
-    try {
-      const payload = await fetchPayload(u.toString())
-      history[opts.replace ? 'replaceState' : 'pushState'](
-        { url: u.pathname }, '', u.pathname,
-      )
-      if (opts.scroll !== false) window.scrollTo(0, 0)
-      _setNav?.({ path: u.pathname, data: payload.state ?? {}, params: payload.params ?? {} })
-      syncSEO(payload.seo ?? {})
-    } catch (err) {
-      console.error('[fnetro] Navigation error:', err)
-      location.href = to
-    }
-  })
+  return _fetchCache.get(href)!
 }
-/** Warm the prefetch cache for a URL on hover/focus/etc. */
 export function prefetch(url: string): void {
   try {
     const u = new URL(url, location.origin)
-    if (u.origin !== location.origin || !findRoute(u.pathname)) return
-    fetchPayload(u.toString())
-  } catch { /* ignore invalid URLs */ }
+    if (u.origin === location.origin) fetchSPA(u.toString())
+  } catch { /* ignore malformed URLs */ }
 }
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 7  DOM event intercepts
-// ══════════════════════════════════════════════════════════════════════════════
-function onLinkClick(e: MouseEvent): void {
-  if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return
-  const a = e.composedPath().find(
-    (el): el is HTMLAnchorElement => el instanceof HTMLAnchorElement,
-  )
-  if (!a?.href) return
-  if (a.target && a.target !== '_self') return
-  if (a.hasAttribute('data-no-spa') || a.rel?.includes('external')) return
-  const u = new URL(a.href)
-  if (u.origin !== location.origin) return
-  e.preventDefault()
-  navigate(a.href)
-}
+// ── Client middleware ─────────────────────────────────────────────────────────
-function onLinkHover(e: MouseEvent): void {
-  const a = e.composedPath().find(
-    (el): el is HTMLAnchorElement => el instanceof HTMLAnchorElement,
-  )
-  if (a?.href) prefetch(a.href)
-}
+const _mw: ClientMiddleware[] = []
-function onPopState(): void {
-  navigate(location.href, { replace: true, scroll: false })
+/**
+ * Register a client-side navigation middleware.
+ * Must be called **before** `boot()`.
+ *
+ * @example
+ * useClientMiddleware(async (url, next) => {
+ *   if (!isLoggedIn() && url.startsWith('/dashboard')) {
+ *     await navigate('/login')
+ *     return
+ *   }
+ *   await next()
+ * })
+ */
+export function useClientMiddleware(mw: ClientMiddleware): void {
+  _mw.push(mw)
 }
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 8  App root component (created inside hydrate's reactive owner)
-// ══════════════════════════════════════════════════════════════════════════════
-function AppRoot(props: { initial: NavState; appLayout: LayoutDef | undefined }): any {
-  const [nav, setNav] = createSignal<NavState>(props.initial)
-  // Expose setter so navigate() can trigger re-renders
-  _setNav = setNav
-  const view = createMemo(() => {
-    const { path, data, params } = nav()
-    const m = findRoute(path)
-    if (!m) {
-      // No match client-side — shouldn't happen but handle gracefully
-      return null as any
-    }
-    const layout = m.route.layout !== undefined ? m.route.layout : props.appLayout
-    const pageEl = createComponent(m.route.page.Page as any, { ...data, url: path, params })
-    if (!layout) return pageEl
+async function runMw(url: string, done: () => Promise<void>): Promise<void> {
+  const chain: ClientMiddleware[] = [
+    ..._mw,
+    async (_: string, next: () => Promise<void>) => { await done(); await next() },
+  ]
+  let i = 0
+  const run = async (): Promise<void> => {
+    const fn = chain[i++]
+    if (fn) await fn(url, run)
+  }
+  await run()
+}
-    return createComponent(layout.Component as any, {
-      url: path,
-      params,
-      get children() { return pageEl },
-    })
-  })
+// ── Reactive page data ────────────────────────────────────────────────────────
+//
+// A single module-level reactive object that lives for the app's lifetime.
+// On SPA navigation it is updated in-place so page components re-render
+// reactively without being unmounted.
+//
+// The app provides it as readonly via DATA_KEY so page components cannot
+// mutate it directly.
+const _pageData = reactive<Record<string, unknown>>({})
+function updatePageData(newData: Record<string, unknown>): void {
+  // Delete keys that are no longer present in the new data
+  for (const k of Object.keys(_pageData)) {
+    if (!(k in newData)) delete _pageData[k]
+  }
+  Object.assign(_pageData, newData)
+}
-  return view
+/**
+ * Access the current page's loader data inside any Vue component.
+ * The returned object is reactive — it updates automatically on navigation.
+ *
+ * @example
+ * const data = usePageData<{ title: string; posts: Post[] }>()
+ * // data.title is typed and reactive
+ */
+export function usePageData<T extends Record<string, unknown> = Record<string, unknown>>(): T {
+  // DATA_KEY is typed as symbol; cast to InjectionKey for strong inference
+  const data = inject(DATA_KEY as InjectionKey<T>)
+  if (data === undefined) {
+    throw new Error('[fnetro] usePageData() must be called inside a component setup().')
+  }
+  return data
 }
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 9  boot()
-// ══════════════════════════════════════════════════════════════════════════════
+// ── boot() ────────────────────────────────────────────────────────────────────
 export interface BootOptions extends AppConfig {
-  /** Enable hover-based prefetching.  @default true */
+  /** Warm fetch cache on link hover.  @default true */
   prefetchOnHover?: boolean
 }
 export async function boot(options: BootOptions): Promise<void> {
+  const container = document.getElementById('fnetro-app')
+  if (!container) {
+    console.error('[fnetro] #fnetro-app not found — aborting hydration.')
+    return
+  }
   const { pages } = resolveRoutes(options.routes, {
-    layout:     options.layout,
+    ...(options.layout !== undefined && { layout: options.layout }),
     middleware: [],
   })
-  _routes    = pages.map(r => ({ route: r, cp: compilePath(r.fullPath) }))
-  _appLayout = options.layout
-  const pathname = location.pathname
-  if (!findRoute(pathname)) {
-    console.warn(`[fnetro] No route matched "${pathname}" — skipping hydration`)
-    return
-  }
-  // Server-injected initial state (no refetch needed on first load)
+  // Read server-injected bootstrap data
   const stateMap  = (window as any)[STATE_KEY]  as Record<string, Record<string, unknown>> ?? {}
-  const paramsMap = (window as any)[PARAMS_KEY] as Record<string, string>                  ?? {}
   const seoData   = (window as any)[SEO_KEY]    as SEOMeta                                 ?? {}
+  const pathname  = location.pathname
-  const initial: NavState = {
-    path:   pathname,
-    data:   stateMap[pathname] ?? {},
-    params: paramsMap,
-  }
+  // Seed reactive store and sync SEO from server data (no network request)
+  updatePageData(stateMap[pathname] ?? {})
+  syncSEO(seoData)
-  const container = document.getElementById('fnetro-app')
-  if (!container) {
-    console.error('[fnetro] #fnetro-app not found — aborting hydration')
-    return
+  // Build Vue Router route table
+  // Async loaders are wrapped with defineAsyncComponent for code splitting.
+  const vueRoutes = pages.map(r => {
+    const layout = r.layout !== undefined ? r.layout : options.layout
+    const comp   = r.page.component
+    const PageComp: Component = isAsyncLoader(comp)
+      ? defineAsyncComponent(comp)
+      : comp as Component
+    const routeComp: Component = layout
+      ? defineComponent({
+          name:  'FNetroRoute',
+          setup: () => () => h((layout as LayoutDef).component as Component, null, {
+            default: () => h(PageComp),
+          }),
+        })
+      : PageComp
+    return { path: toVueRouterPath(r.fullPath), component: routeComp }
+  })
+  // Pre-load the current route's async chunk BEFORE hydrating to guarantee the
+  // client VDOM matches the SSR HTML (avoids hydration mismatch on first load).
+  const currentRoute = pages.find(r => matchPath(compilePath(r.fullPath), pathname) !== null)
+  if (currentRoute && isAsyncLoader(currentRoute.page.component)) {
+    await currentRoute.page.component()
   }
-  // Sync initial SEO (document.title etc.)
-  syncSEO(seoData)
+  // createSSRApp: tells Vue to hydrate existing DOM instead of re-rendering
+  const app = createSSRApp({ name: 'FNetroApp', render: () => h(RouterView) })
+  app.provide(DATA_KEY as InjectionKey<typeof _pageData>, readonly(_pageData))
+  const router = createRouter({ history: createWebHistory(), routes: vueRoutes })
+  // Track whether this is the initial (server-hydrated) navigation.
+  // We skip data fetching for the first navigation — the server already
+  // injected the data into window.__FNETRO_STATE__.
+  let isInitialNav = true
+  router.beforeEach(async (to, _from, next) => {
+    if (isInitialNav) {
+      isInitialNav = false
+      return next()
+    }
-  // Hydrate the server-rendered HTML with SolidJS
-  hydrate(
-    () => createComponent(AppRoot as any, { initial, appLayout: _appLayout }) as any,
-    container,
-  )
+    const href = new URL(to.fullPath, location.origin).toString()
-  // Wire up SPA navigation
-  document.addEventListener('click', onLinkClick)
+    try {
+      await runMw(to.fullPath, async () => {
+        const payload = await fetchSPA(href)
+        updatePageData(payload.state ?? {})
+        syncSEO(payload.seo ?? {})
+        window.scrollTo(0, 0)
+      })
+      next()
+    } catch (err) {
+      console.error('[fnetro] Navigation error:', err)
+      // Hard navigate as fallback — the server will handle the request
+      location.href = to.fullPath
+    }
+  })
+  app.use(router)
+  await router.isReady()
+  app.mount(container)
+  // Hover prefetch — warm the fetch cache before the user clicks
   if (options.prefetchOnHover !== false) {
-    document.addEventListener('mouseover', onLinkHover)
+    document.addEventListener('mouseover', (e) => {
+      const a = (e as MouseEvent).composedPath()
+        .find((el): el is HTMLAnchorElement => el instanceof HTMLAnchorElement)
+      if (a?.href) prefetch(a.href)
+    })
   }
-  window.addEventListener('popstate', onPopState)
 }
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 10  Re-exports
-// ══════════════════════════════════════════════════════════════════════════════
+// ── Re-exports ────────────────────────────────────────────────────────────────
 export {
-  definePage, defineGroup, defineLayout, defineApiRoute,
-  resolveRoutes, compilePath, matchPath,
-  SPA_HEADER, STATE_KEY, PARAMS_KEY, SEO_KEY,
+  definePage, defineGroup, defineLayout, defineApiRoute, isAsyncLoader,
+  resolveRoutes, compilePath, matchPath, toVueRouterPath,
+  SPA_HEADER, STATE_KEY, PARAMS_KEY, SEO_KEY, DATA_KEY,
 } from './core'
 export type {
   AppConfig, PageDef, GroupDef, LayoutDef, ApiRouteDef, Route,
-  PageProps, LayoutProps, SEOMeta, HonoMiddleware, LoaderCtx,
-  ResolvedRoute, CompiledPath, ClientMiddleware,
+  SEOMeta, HonoMiddleware, LoaderCtx, ResolvedRoute, CompiledPath,
+  ClientMiddleware, AsyncLoader,
 } from './core'
+// Vue Router composables re-exported for convenience
+export {
+  useRoute,
+  useRouter,
+  RouterLink,
+  RouterView,
+} from 'vue-router'