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

@netrojs/fnetro 0.2.21 → 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,79 +1,51 @@
 // ─────────────────────────────────────────────────────────────────────────────
 //  FNetro · client.ts
-//  SolidJS hydration · @solidjs/router SPA routing · client middleware · SEO
+//  Vue 3 SSR hydration · Vue Router SPA · reactive page data · SEO sync
 // ─────────────────────────────────────────────────────────────────────────────
-import { createSignal, createComponent, lazy, Suspense } from 'solid-js'
-import { hydrate } from 'solid-js/web'
-import { Router, Route } from '@solidjs/router'
 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  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)
-}
-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()
-}
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 3  SEO — client-side <head> sync
-// ══════════════════════════════════════════════════════════════════════════════
+// ── SEO ───────────────────────────────────────────────────────────────────────
-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)
@@ -81,7 +53,6 @@ function setMeta(selector: string, attr: string, val: string | undefined): 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)
@@ -96,243 +67,243 @@ export 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()
   }
 }
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 4  Prefetch cache + SPA data fetching
-// ══════════════════════════════════════════════════════════════════════════════
+// ── 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>>()
-export 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)!
+  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 */ }
 }
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 5  Route components with data loading for @solidjs/router
-// ══════════════════════════════════════════════════════════════════════════════
+// ── Client middleware ─────────────────────────────────────────────────────────
+const _mw: ClientMiddleware[] = []
 /**
- * Creates a solid-router-compatible route component that:
- * 1. On first render: uses server-injected state (no network request)
- * 2. On SPA navigation: fetches data from the FNetro server handler
+ * 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()
+ * })
  */
-function makeRouteComponent(
-  route: ResolvedRoute,
-  appLayout: LayoutDef | undefined,
-  initialState: Record<string, unknown>,
-  initialParams: Record<string, string>,
-  initialSeo: SEOMeta,
-  prefetchOnHover: boolean,
-) {
-  // The component returned here is used as @solidjs/router's <Route component>
-  return function FNetroRouteComponent(routerProps: any) {
-    // routerProps.params comes from @solidjs/router's URL matching
-    const routeParams: Record<string, string> = routerProps.params ?? {}
-    const pathname: string = routerProps.location?.pathname ?? location.pathname
-    // Determine the data source:
-    // - If this matches the server's initial state key, use it directly (no fetch needed on first load)
-    // - Otherwise fetch from the server via the SPA JSON endpoint
-    const serverData = initialState[pathname] as Record<string, unknown> | undefined
-    const [data, setData] = createSignal<Record<string, unknown>>(serverData ?? {})
-    const [params, setParams] = createSignal<Record<string, string>>(serverData ? initialParams : routeParams)
-    // Load data if we don't have it yet from the server
-    if (!serverData) {
-      const url = new URL(pathname, location.origin).toString()
-      fetchPayload(url).then(payload => {
-        setData(payload.state ?? {})
-        setParams(payload.params ?? {})
-        syncSEO(payload.seo ?? {})
-      }).catch(err => {
-        console.error('[fnetro] Failed to load route data:', err)
-      })
-    } else {
-      // Sync SEO for the initial page from server-injected data
-      syncSEO(initialSeo)
-    }
-    // Render the page (and optional layout wrapper)
-    const layout = route.layout !== undefined ? route.layout : appLayout
-    const pageEl = () => createComponent(route.page.Page as any, {
-      ...data(),
-      url: pathname,
-      params: params(),
-    })
-    if (!layout) return pageEl()
+export function useClientMiddleware(mw: ClientMiddleware): void {
+  _mw.push(mw)
+}
-    return createComponent(layout.Component as any, {
-      url: pathname,
-      params: params(),
-      get children() { 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()
 }
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 6  navigate / prefetch (convenience exports, wraps solid-router navigate)
-// ══════════════════════════════════════════════════════════════════════════════
-export interface NavigateOptions {
-  replace?: boolean
-  scroll?:  boolean
+// ── 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)
 }
 /**
- * Programmatic navigation — delegates to history API and triggers
- * @solidjs/router's reactive location update.
+ * 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 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 {
-      // Prefetch/cache the payload so the route component can use it
-      const payload = await fetchPayload(u.toString())
-      history[opts.replace ? 'replaceState' : 'pushState'](
-        { url: u.pathname }, '', u.pathname,
-      )
-      if (opts.scroll !== false) window.scrollTo(0, 0)
-      syncSEO(payload.seo ?? {})
-      // Dispatch a popstate-like event so @solidjs/router's location signal updates
-      window.dispatchEvent(new PopStateEvent('popstate', { state: history.state }))
-    } catch (err) {
-      console.error('[fnetro] Navigation error:', err)
-      location.href = to
-    }
-  })
+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
 }
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 7  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
+  // Seed reactive store and sync SEO from server data (no network request)
+  updatePageData(stateMap[pathname] ?? {})
+  syncSEO(seoData)
+  // 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 }
+  })
-  const container = document.getElementById('fnetro-app')
-  if (!container) {
-    console.error('[fnetro] #fnetro-app not found — aborting hydration')
-    return
+  // 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()
   }
-  const prefetchOnHover = options.prefetchOnHover !== false
-  // Build @solidjs/router <Route> elements for each resolved page
-  const routeElements = pages.map(route =>
-    createComponent(Route, {
-      path: route.fullPath,
-      component: makeRouteComponent(
-        route,
-        _appLayout,
-        stateMap,
-        paramsMap,
-        seoData,
-        prefetchOnHover,
-      ),
-    }) as any
-  )
-  // Hydrate with @solidjs/router wrapping all routes
-  hydrate(
-    () => createComponent(Router as any, {
-      get children() { return routeElements },
-    }) as any,
-    container,
-  )
-  // Hover prefetch
-  if (prefetchOnHover) {
-    document.addEventListener('mouseover', (e: MouseEvent) => {
-      const a = e.composedPath().find(
-        (el): el is HTMLAnchorElement => el instanceof HTMLAnchorElement,
-      )
+  // 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()
+    }
+    const href = new URL(to.fullPath, location.origin).toString()
+    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', (e) => {
+      const a = (e as MouseEvent).composedPath()
+        .find((el): el is HTMLAnchorElement => el instanceof HTMLAnchorElement)
       if (a?.href) prefetch(a.href)
     })
   }
 }
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 8  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'
-// Re-export solid-router primitives for convenience
-export { useNavigate, useParams, useLocation, A, useSearchParams } from '@solidjs/router'
+// Vue Router composables re-exported for convenience
+export {
+  useRoute,
+  useRouter,
+  RouterLink,
+  RouterView,
+} from 'vue-router'