@netrojs/fnetro 0.2.20 → 0.3.0

package/core.ts

@@ -1,135 +1,41 @@
 // ─────────────────────────────────────────────────────────────────────────────
 //  FNetro · core.ts
-//  Shared types · route builders · path matching · SEO · constants
-//  Reactivity: consumers use solid-js primitives directly
+//  Route builders · path matching · route resolution · async-loader detection
 // ─────────────────────────────────────────────────────────────────────────────
 
-import type { Context, MiddlewareHandler, Hono } from 'hono'
-import type { Component, JSX } from 'solid-js'
-
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 1  Primitive aliases
-// ══════════════════════════════════════════════════════════════════════════════
-
-export type HonoMiddleware = MiddlewareHandler
-export type LoaderCtx      = Context
-
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 2  SEO / head metadata
-// ══════════════════════════════════════════════════════════════════════════════
-
-export interface SEOMeta {
-  // Basic
-  title?:         string
-  description?:   string
-  keywords?:      string
-  author?:        string
-  robots?:        string
-  canonical?:     string
-  themeColor?:    string
-  // Open Graph
-  ogTitle?:       string
-  ogDescription?: string
-  ogImage?:       string
-  ogImageAlt?:    string
-  ogImageWidth?:  string
-  ogImageHeight?: string
-  ogUrl?:         string
-  ogType?:        string
-  ogSiteName?:    string
-  ogLocale?:      string
-  // Twitter / X
-  twitterCard?:        'summary' | 'summary_large_image' | 'app' | 'player'
-  twitterSite?:        string
-  twitterCreator?:     string
-  twitterTitle?:       string
-  twitterDescription?: string
-  twitterImage?:       string
-  twitterImageAlt?:    string
-  // Structured data (JSON-LD)
-  jsonLd?: Record<string, unknown> | Record<string, unknown>[]
-  // Arbitrary extra <meta> tags
-  extra?: Array<{ name?: string; property?: string; httpEquiv?: string; content: string }>
-}
-
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 3  Component prop shapes
-// ══════════════════════════════════════════════════════════════════════════════
-
-export type PageProps<TData extends object = {}> = TData & {
-  url:    string
-  params: Record<string, string>
-}
-
-export interface LayoutProps {
-  children: JSX.Element
-  url:      string
-  params:   Record<string, string>
-}
-
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 4  Route definitions
-// ══════════════════════════════════════════════════════════════════════════════
-
-export interface PageDef<TData extends object = {}> {
-  readonly __type:  'page'
-  path:             string
-  middleware?:      HonoMiddleware[]
-  loader?:          (c: LoaderCtx) => TData | Promise<TData>
-  seo?:             SEOMeta | ((data: TData, params: Record<string, string>) => SEOMeta)
-  layout?:          LayoutDef | false
-  Page:             Component<PageProps<TData>>
-}
-
-export interface GroupDef {
-  readonly __type: 'group'
-  prefix:          string
-  layout?:         LayoutDef | false
-  middleware?:     HonoMiddleware[]
-  routes:          Route[]
-}
-
-export interface LayoutDef {
-  readonly __type: 'layout'
-  Component:       Component<LayoutProps>
-}
-
-export interface ApiRouteDef {
-  readonly __type: 'api'
-  path:            string
-  register:        (app: Hono, globalMiddleware: HonoMiddleware[]) => void
-}
-
-export type Route = PageDef<any> | GroupDef | ApiRouteDef
-
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 5  App config
-// ══════════════════════════════════════════════════════════════════════════════
-
-export interface AppConfig {
-  layout?:    LayoutDef
-  seo?:       SEOMeta
-  middleware?: HonoMiddleware[]
-  routes:     Route[]
-  notFound?:  Component
-  htmlAttrs?: Record<string, string>
-  head?:      string
+import type { Component } from 'vue'
+import type {
+  PageDef, GroupDef, LayoutDef, ApiRouteDef, Route,
+  ResolvedRoute, CompiledPath, HonoMiddleware, AsyncLoader,
+} from './types'
+
+// ── Async-loader detection ────────────────────────────────────────────────────
+//
+// A Vue component (SFC compiled by vite-plugin-vue) always carries one or more
+// of these brand properties.  A plain () => import('./Page.vue') factory has
+// none of them, so checking for their absence is sufficient for real-world use.
+
+const VUE_BRANDS = ['__name', '__file', '__vccOpts', 'setup', 'render', 'data', 'components'] as const
+
+/**
+ * Returns true when `c` is an async factory function (i.e. `() => import(...)`)
+ * rather than a resolved Vue component object.
+ *
+ * Used by both server.ts (to resolve the import before SSR) and client.ts
+ * (to wrap with defineAsyncComponent for lazy hydration).
+ */
+export function isAsyncLoader(c: unknown): c is AsyncLoader {
+  if (typeof c !== 'function') return false
+  const f = c as unknown as Record<string, unknown>
+  for (const brand of VUE_BRANDS) {
+    if (brand in f) return false
+  }
+  return true
 }
 
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 6  Client middleware
-// ══════════════════════════════════════════════════════════════════════════════
-
-export type ClientMiddleware = (
-  url:  string,
-  next: () => Promise<void>,
-) => Promise<void>
+// ── Builder functions ─────────────────────────────────────────────────────────
 
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 7  Builder functions
-// ══════════════════════════════════════════════════════════════════════════════
-
-export function definePage<TData extends object = {}>(
+export function definePage<TData extends object = Record<string, never>>(
   def: Omit<PageDef<TData>, '__type'>,
 ): PageDef<TData> {
   return { __type: 'page', ...def }
@@ -139,8 +45,9 @@ export function defineGroup(def: Omit<GroupDef, '__type'>): GroupDef {
   return { __type: 'group', ...def }
 }
 
-export function defineLayout(Component: Component<LayoutProps>): LayoutDef {
-  return { __type: 'layout', Component }
+/** Wrap a Vue layout component (must render <slot />) as a FNetro layout. */
+export function defineLayout(component: Component): LayoutDef {
+  return { __type: 'layout', component }
 }
 
 export function defineApiRoute(
@@ -150,17 +57,42 @@ export function defineApiRoute(
   return { __type: 'api', path, register }
 }
 
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 8  Internal route resolution
-// ══════════════════════════════════════════════════════════════════════════════
+// ── Path matching (FNetro [param] syntax → RegExp) ────────────────────────────
+
+export function compilePath(path: string): CompiledPath {
+  const keys: string[] = []
+  const src = path
+    .replace(/\[\.\.\.([^\]]+)\]/g, (_, k: string) => { keys.push(k); return '(.*)' })
+    .replace(/\[([^\]]+)\]/g,       (_, k: string) => { keys.push(k); return '([^/]+)' })
+    .replace(/\*/g, '(.*)')
+  return { re: new RegExp(`^${src}$`), keys }
+}
+
+export function matchPath(
+  cp: CompiledPath,
+  pathname: string,
+): Record<string, string> | null {
+  const m = pathname.match(cp.re)
+  if (!m) return null
+  const params: Record<string, string> = {}
+  cp.keys.forEach((k, i) => { params[k] = decodeURIComponent(m[i + 1] ?? '') })
+  return params
+}
 
-export interface ResolvedRoute {
-  fullPath:   string
-  page:       PageDef<any>
-  layout:     LayoutDef | false | undefined
-  middleware: HonoMiddleware[]
+/**
+ * Convert FNetro `[param]` syntax to Vue Router `:param` syntax.
+ *
+ * `/posts/[slug]`    → `/posts/:slug`
+ * `/files/[...path]` → `/files/:path(.*)*`
+ */
+export function toVueRouterPath(fnetroPath: string): string {
+  return fnetroPath
+    .replace(/\[\.\.\.([^\]]+)\]/g, ':$1(.*)*')
+    .replace(/\[([^\]]+)\]/g,       ':$1')
 }
 
+// ── Route resolution ──────────────────────────────────────────────────────────
+
 export function resolveRoutes(
   routes:  Route[],
   options: {
@@ -179,7 +111,11 @@ export function resolveRoutes(
       const prefix = (options.prefix ?? '') + route.prefix
       const mw     = [...(options.middleware ?? []), ...(route.middleware ?? [])]
       const layout = route.layout !== undefined ? route.layout : options.layout
-      const sub    = resolveRoutes(route.routes, { prefix, middleware: mw, layout })
+      const sub    = resolveRoutes(route.routes, {
+        prefix,
+        middleware: mw,
+        ...(layout !== undefined && { layout }),
+      })
       pages.push(...sub.pages)
       apis.push(...sub.apis)
     } else {
@@ -195,42 +131,5 @@ export function resolveRoutes(
   return { pages, apis }
 }
 
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 9  Path matching  (used by both server + client)
-// ══════════════════════════════════════════════════════════════════════════════
-
-export interface CompiledPath {
-  re:   RegExp
-  keys: string[]
-}
-
-export function compilePath(path: string): CompiledPath {
-  const keys: string[] = []
-  const src = path
-    .replace(/\[\.\.\.([^\]]+)\]/g, (_, k: string) => { keys.push(k); return '(.*)' })
-    .replace(/\[([^\]]+)\]/g,       (_, k: string) => { keys.push(k); return '([^/]+)' })
-    .replace(/\*/g, '(.*)')
-  return { re: new RegExp(`^${src}$`), keys }
-}
-
-export function matchPath(
-  compiled: CompiledPath,
-  pathname: string,
-): Record<string, string> | null {
-  const m = pathname.match(compiled.re)
-  if (!m) return null
-  const params: Record<string, string> = {}
-  compiled.keys.forEach((k, i) => {
-    params[k] = decodeURIComponent(m[i + 1] ?? '')
-  })
-  return params
-}
-
-// ══════════════════════════════════════════════════════════════════════════════
-//  § 10  Shared constants
-// ══════════════════════════════════════════════════════════════════════════════
-
-export const SPA_HEADER = 'x-fnetro-spa'
-export const STATE_KEY  = '__FNETRO_STATE__'
-export const PARAMS_KEY = '__FNETRO_PARAMS__'
-export const SEO_KEY    = '__FNETRO_SEO__'
+// Re-export all types so `import from '@netrojs/fnetro'` (root export) works
+export * from './types'

package/dist/client.d.ts

@@ -1,5 +1,6 @@
+import { Component } from 'vue';
 import { Hono, MiddlewareHandler, Context } from 'hono';
-import { Component, JSX } from 'solid-js';
+export { RouterLink, RouterView, useRoute, useRouter } from 'vue-router';
 
 type HonoMiddleware = MiddlewareHandler;
 type LoaderCtx = Context;
@@ -15,44 +16,33 @@ interface SEOMeta {
     ogDescription?: string;
     ogImage?: string;
     ogImageAlt?: string;
-    ogImageWidth?: string;
-    ogImageHeight?: string;
     ogUrl?: string;
     ogType?: string;
     ogSiteName?: string;
-    ogLocale?: string;
     twitterCard?: 'summary' | 'summary_large_image' | 'app' | 'player';
     twitterSite?: string;
-    twitterCreator?: string;
     twitterTitle?: string;
     twitterDescription?: string;
     twitterImage?: string;
-    twitterImageAlt?: string;
+    /** Structured data injected as <script type="application/ld+json">. */
     jsonLd?: Record<string, unknown> | Record<string, unknown>[];
-    extra?: Array<{
-        name?: string;
-        property?: string;
-        httpEquiv?: string;
-        content: string;
-    }>;
 }
-type PageProps<TData extends object = {}> = TData & {
-    url: string;
-    params: Record<string, string>;
-};
-interface LayoutProps {
-    children: JSX.Element;
-    url: string;
-    params: Record<string, string>;
-}
-interface PageDef<TData extends object = {}> {
+type AsyncLoader = () => Promise<{
+    default: Component;
+} | Component>;
+interface PageDef<TData extends object = Record<string, never>> {
     readonly __type: 'page';
     path: string;
     middleware?: HonoMiddleware[];
     loader?: (c: LoaderCtx) => TData | Promise<TData>;
     seo?: SEOMeta | ((data: TData, params: Record<string, string>) => SEOMeta);
+    /** Override or disable the app-level layout for this route. */
     layout?: LayoutDef | false;
-    Page: Component<PageProps<TData>>;
+    /**
+     * The Vue component to render for this route.
+     * Use () => import('./Page.vue') for automatic code splitting.
+     */
+    component: Component | AsyncLoader;
 }
 interface GroupDef {
     readonly __type: 'group';
@@ -63,7 +53,8 @@ interface GroupDef {
 }
 interface LayoutDef {
     readonly __type: 'layout';
-    Component: Component<LayoutProps>;
+    /** Vue layout component — must contain <slot /> for page content. */
+    component: Component;
 }
 interface ApiRouteDef {
     readonly __type: 'api';
@@ -78,38 +69,67 @@ interface AppConfig {
     routes: Route[];
     notFound?: Component;
     htmlAttrs?: Record<string, string>;
+    /** Extra HTML injected into <head> (e.g. font preloads). */
     head?: string;
 }
-type ClientMiddleware = (url: string, next: () => Promise<void>) => Promise<void>;
-declare function definePage<TData extends object = {}>(def: Omit<PageDef<TData>, '__type'>): PageDef<TData>;
-declare function defineGroup(def: Omit<GroupDef, '__type'>): GroupDef;
-declare function defineLayout(Component: Component<LayoutProps>): LayoutDef;
-declare function defineApiRoute(path: string, register: ApiRouteDef['register']): ApiRouteDef;
 interface ResolvedRoute {
     fullPath: string;
     page: PageDef<any>;
     layout: LayoutDef | false | undefined;
     middleware: HonoMiddleware[];
 }
-declare function resolveRoutes(routes: Route[], options?: {
-    prefix?: string;
-    middleware?: HonoMiddleware[];
-    layout?: LayoutDef | false;
-}): {
-    pages: ResolvedRoute[];
-    apis: ApiRouteDef[];
-};
 interface CompiledPath {
     re: RegExp;
     keys: string[];
 }
-declare function compilePath(path: string): CompiledPath;
-declare function matchPath(compiled: CompiledPath, pathname: string): Record<string, string> | null;
+type ClientMiddleware = (url: string, next: () => Promise<void>) => Promise<void>;
+/** Custom request header that identifies an SPA navigation (JSON payload). */
 declare const SPA_HEADER = "x-fnetro-spa";
+/** window key for SSR-injected per-page loader data. */
 declare const STATE_KEY = "__FNETRO_STATE__";
+/** window key for SSR-injected URL params. */
 declare const PARAMS_KEY = "__FNETRO_PARAMS__";
+/** window key for SSR-injected SEO meta. */
 declare const SEO_KEY = "__FNETRO_SEO__";
+/**
+ * Vue provide/inject key for the reactive page-data object.
+ * Symbol.for() ensures the same reference across module instances (SSR safe).
+ */
+declare const DATA_KEY: unique symbol;
+
+/**
+ * Returns true when `c` is an async factory function (i.e. `() => import(...)`)
+ * rather than a resolved Vue component object.
+ *
+ * Used by both server.ts (to resolve the import before SSR) and client.ts
+ * (to wrap with defineAsyncComponent for lazy hydration).
+ */
+declare function isAsyncLoader(c: unknown): c is AsyncLoader;
+declare function definePage<TData extends object = Record<string, never>>(def: Omit<PageDef<TData>, '__type'>): PageDef<TData>;
+declare function defineGroup(def: Omit<GroupDef, '__type'>): GroupDef;
+/** Wrap a Vue layout component (must render <slot />) as a FNetro layout. */
+declare function defineLayout(component: Component): LayoutDef;
+declare function defineApiRoute(path: string, register: ApiRouteDef['register']): ApiRouteDef;
+declare function compilePath(path: string): CompiledPath;
+declare function matchPath(cp: CompiledPath, pathname: string): Record<string, string> | null;
+/**
+ * Convert FNetro `[param]` syntax to Vue Router `:param` syntax.
+ *
+ * `/posts/[slug]`    → `/posts/:slug`
+ * `/files/[...path]` → `/files/:path(.*)*`
+ */
+declare function toVueRouterPath(fnetroPath: string): string;
+declare function resolveRoutes(routes: Route[], options?: {
+    prefix?: string;
+    middleware?: HonoMiddleware[];
+    layout?: LayoutDef | false;
+}): {
+    pages: ResolvedRoute[];
+    apis: ApiRouteDef[];
+};
 
+declare function syncSEO(seo: SEOMeta): void;
+declare function prefetch(url: string): void;
 /**
  * Register a client-side navigation middleware.
  * Must be called **before** `boot()`.
@@ -118,23 +138,25 @@ declare const SEO_KEY = "__FNETRO_SEO__";
  * useClientMiddleware(async (url, next) => {
  *   if (!isLoggedIn() && url.startsWith('/dashboard')) {
  *     await navigate('/login')
- *     return                   // cancel original navigation
+ *     return
  *   }
  *   await next()
  * })
  */
 declare function useClientMiddleware(mw: ClientMiddleware): void;
-interface NavigateOptions {
-    replace?: boolean;
-    scroll?: boolean;
-}
-declare function navigate(to: string, opts?: NavigateOptions): Promise<void>;
-/** Warm the prefetch cache for a URL on hover/focus/etc. */
-declare function prefetch(url: string): void;
+/**
+ * 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
+ */
+declare function usePageData<T extends Record<string, unknown> = Record<string, unknown>>(): T;
 interface BootOptions extends AppConfig {
-    /** Enable hover-based prefetching.  @default true */
+    /** Warm fetch cache on link hover.  @default true */
     prefetchOnHover?: boolean;
 }
 declare function boot(options: BootOptions): Promise<void>;
 
-export { type ApiRouteDef, type AppConfig, type BootOptions, type ClientMiddleware, type CompiledPath, type GroupDef, type HonoMiddleware, type LayoutDef, type LayoutProps, type LoaderCtx, type NavigateOptions, PARAMS_KEY, type PageDef, type PageProps, type ResolvedRoute, type Route, type SEOMeta, SEO_KEY, SPA_HEADER, STATE_KEY, boot, compilePath, defineApiRoute, defineGroup, defineLayout, definePage, matchPath, navigate, prefetch, resolveRoutes, useClientMiddleware };
+export { type ApiRouteDef, type AppConfig, type AsyncLoader, type BootOptions, type ClientMiddleware, type CompiledPath, DATA_KEY, type GroupDef, type HonoMiddleware, type LayoutDef, type LoaderCtx, PARAMS_KEY, type PageDef, type ResolvedRoute, type Route, type SEOMeta, SEO_KEY, SPA_HEADER, STATE_KEY, boot, compilePath, defineApiRoute, defineGroup, defineLayout, definePage, isAsyncLoader, matchPath, prefetch, resolveRoutes, syncSEO, toVueRouterPath, useClientMiddleware, usePageData };