what-framework 0.11.7 → 0.11.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-framework",
-  "version": "0.11.7",
+  "version": "0.11.8",
   "description": "The web framework built for AI agents — signals, components, islands, SSR",
   "type": "module",
   "main": "src/index.js",
@@ -84,9 +84,9 @@
   },
   "homepage": "https://whatfw.com",
   "dependencies": {
-    "what-core": "^0.11.7",
-    "what-router": "^0.11.7",
-    "what-server": "^0.11.7",
-    "what-compiler": "^0.11.7"
+    "what-core": "^0.11.8",
+    "what-router": "^0.11.8",
+    "what-server": "^0.11.8",
+    "what-compiler": "^0.11.8"
   }
 }

package/router.d.ts

@@ -37,9 +37,6 @@ export interface NavigateOptions {
 /** Navigate to a new URL */
 export function navigate(to: string, options?: NavigateOptions): Promise<void>;
 
-/** Redirect (throws to navigate) */
-export function redirect(to: string, options?: NavigateOptions): never;
-
 // --- Route Configuration ---
 
 export interface RouteConfig {
@@ -81,6 +78,25 @@ export interface RouterProps {
 
 export function Router(props: RouterProps): VNode;
 
+// --- File-Based Router ---
+
+export interface FileRouteConfig {
+  path: string;
+  component: Component<RouteComponentProps>;
+  layout?: Component<LayoutProps>;
+  mode?: 'static' | 'server' | 'client' | 'hybrid';
+}
+
+export interface FileRouterProps {
+  routes: FileRouteConfig[];
+  layout?: Component<{ children?: VNodeChild }>;
+  fallback?: Component<{}>;
+  error?: Component<{ error: Error }>;
+}
+
+/** Router driven by what-compiler's generated route manifest (virtual:what-routes). */
+export function FileRouter(props: FileRouterProps): VNode;
+
 // --- Link Component ---
 
 export interface LinkProps {
@@ -104,25 +120,141 @@ export function NavLink(props: LinkProps): VNode;
 /** Define routes from object config */
 export function defineRoutes(config: Record<string, Component | Partial<RouteConfig>>): RouteConfig[];
 
+/** Create nested routes with shared options */
+export function nestedRoutes(
+  basePath: string,
+  children: RouteConfig[],
+  options?: { layout?: Component; loading?: Component; error?: Component }
+): RouteConfig[];
+
+/** Group routes without affecting URLs */
+export function routeGroup(
+  name: string,
+  routes: RouteConfig[],
+  options?: { layout?: Component; middleware?: RouteMiddleware[] }
+): RouteConfig[];
+
+// --- Redirect ---
+
+export function Redirect(props: { to: string }): null;
+
+// --- Guards ---
+
+/** Create a route guard */
+export function guard(
+  check: (props: RouteComponentProps) => boolean,
+  fallback: string | Component
+): <P>(component: Component<P>) => Component<P>;
+
+/** Create an async route guard */
+export function asyncGuard(
+  check: (props: RouteComponentProps) => Promise<boolean>,
+  options?: { fallback?: string | Component; loading?: Component }
+): <P>(component: Component<P>) => Component<P>;
+
 // --- Prefetch ---
 
-export function prefetchRoute(href: string): void;
+export function prefetch(href: string): void;
 
-// --- Navigation Hooks ---
+// --- Scroll Restoration ---
 
-export function beforeNavigate(fn: (to: string, from: string) => boolean | Promise<boolean>): () => void;
-export function afterNavigate(fn: (to: string, from: string) => void): () => void;
+export function enableScrollRestoration(): void;
+
+// --- View Transitions ---
+
+export function viewTransitionName(name: string): { style: { viewTransitionName: string } };
+export function setViewTransition(type: string): void;
 
-// --- useRoute Hooks ---
+// --- useRoute Hook ---
 
-export function useRoute(): {
+export interface UseRouteResult {
   path: Computed<string>;
   params: Computed<Record<string, string>>;
   query: Computed<Record<string, string>>;
   hash: Computed<string>;
   isNavigating: Computed<boolean>;
-};
+  navigate: typeof navigate;
+  prefetch: typeof prefetch;
+}
+
+export function useRoute(): UseRouteResult;
+
+// --- Route Accessors ---
+
+/** Current route params. Subscribes when read inside a tracking scope. */
+export function useParams<T = Record<string, string>>(): T;
 
-export function useParams<T extends Record<string, string> = Record<string, string>>(): T;
-export function useSearch<T extends Record<string, string> = Record<string, string>>(): T;
+/**
+ * Query string of the last successfully matched route, parsed. Subscribes when
+ * read inside a tracking scope. Only the Router's match branch writes it, so on
+ * an unmatched (404) route this is the previous route's query, not the current
+ * URL's. Same value and same caveat as `route.query`.
+ */
+export function useSearch<T = Record<string, string>>(): T;
+
+/** The navigate function, for symmetry with useParams/useSearch. */
 export function useNavigate(): typeof navigate;
+
+/** Prefetch a route's assets. */
+export function prefetchRoute(href: string): void;
+
+// --- Redirect Signal ---
+
+/**
+ * Abort the current render and navigate.
+ *
+ * Throws a navigation signal. Two places catch it: route middleware, caught by
+ * the Router's matching pass, and a component body, caught by the runtime where
+ * it instantiates components. Anywhere else (an event handler, a promise
+ * callback, a timer, or a reactive thunk such as `{() => cond() && redirect(to)}`)
+ * nothing catches it and the signal surfaces as an uncaught error carrying
+ * `ERR_REDIRECT_NOT_CAUGHT`; call `navigate(to)` there instead. In a thunk the
+ * first render reports the error, but on a later re-run the navigation simply
+ * does not happen and the stale DOM stays, so prefer `navigate(to)` there.
+ * A `try/catch` around the call also swallows it, so rethrow anything whose
+ * `name` is `RouterRedirect`. On the server the signal escapes `renderToString`
+ * to its caller: read `.to` and emit a 302.
+ */
+export function redirect(to: string, options?: NavigateOptions): never;
+
+// --- Navigation Hooks ---
+
+/**
+ * Run before every route navigation; return false to cancel. Returns an
+ * unsubscribe. Not consulted for same-page hash navigation (`navigate('#x')`
+ * scrolls, it does not change the route). Cancelling a back/forward navigation
+ * restores the address bar by pushing the previous URL as a new history entry:
+ * the entry the browser moved to is not recovered and its `history.state` is
+ * not carried over.
+ */
+export function beforeNavigate(fn: (to: string, from: string) => boolean | Promise<boolean>): () => void;
+
+/** Run after every committed navigation. Returns an unsubscribe. */
+export function afterNavigate(fn: (to: string, from: string) => void): () => void;
+
+// --- Outlet ---
+
+export function Outlet(props: { children?: VNodeChild }): VNode;
+
+// --- Path Matching ---
+
+export interface CompiledPath {
+  regex: RegExp;
+  paramNames: string[];
+  catchAll: string | null;
+}
+
+/** Compile a path pattern (`/users/:id`, `/posts/*`, `/[slug]`) to a matcher. */
+export function compilePath(path: string): CompiledPath;
+
+/** Match a pathname against routes, most specific first. */
+export function matchRoute<T extends { path?: string }>(
+  path: string,
+  routes: T[],
+): { route: T; params: Record<string, string> } | null;
+
+/** Parse a query string into a null-prototype object. */
+export function parseQuery(search: string): Record<string, string>;
+
+/** Reject javascript:, data:, vbscript: and protocol-relative URLs. */
+export function isSafeUrl(url: string): boolean;

package/server.d.ts

@@ -1,6 +1,6 @@
 // What Framework Server - TypeScript Definitions
 
-import { VNode, VNodeChild, Signal } from './index';
+import { Component, VNode, VNodeChild, Signal } from './index';
 
 // --- SSR ---
 
@@ -10,14 +10,18 @@ export function renderToString(vnode: VNode): string;
 /** Render VNode tree as async iterator for streaming */
 export function renderToStream(vnode: VNode): AsyncGenerator<string>;
 
-/** Render a full page with document wrapper */
-export function renderPage(vnode: VNode, options?: {
-  title?: string;
-  meta?: Record<string, string>;
-  scripts?: string[];
-  styles?: string[];
-  mode?: 'static' | 'server' | 'client' | 'hybrid';
-}): string;
+export interface RenderRequestContext {
+  params?: Record<string, string>;
+  query?: Record<string, string>;
+  request?: any;
+  [key: string]: any;
+}
+
+/** Run a page module's loader, then render it. Returns the body, head and loader data. */
+export function renderPage(
+  pageModule: { default: Component<any>; loader?: (ctx: RenderRequestContext) => any } | Component<any>,
+  reqCtx?: RenderRequestContext,
+): Promise<{ body: string; head: string; loaderData: any }>;
 
 // --- Page Configuration ---
 
@@ -44,15 +48,6 @@ export function definePage(config: Partial<PageConfig>): PageConfig;
 
 export type IslandMode = 'static' | 'idle' | 'visible' | 'load' | 'media' | 'action';
 
-export const IslandModes: {
-  STATIC: 'static';
-  IDLE: 'idle';
-  VISIBLE: 'visible';
-  LOAD: 'load';
-  MEDIA: 'media';
-  ACTION: 'action';
-};
-
 export interface IslandOptions {
   /** Hydration mode */
   mode?: IslandMode;
@@ -93,8 +88,8 @@ export interface ActionOptions {
   revalidate?: string[];
 }
 
-/** Create a server action */
-export function createAction<T extends any[], R>(
+/** Define a server action */
+export function action<T extends any[], R>(
   fn: (...args: T) => Promise<R>,
   options?: ActionOptions
 ): (...args: T) => Promise<R>;