what-framework 0.11.7 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-framework",
-  "version": "0.11.7",
+  "version": "0.12.0",
   "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.12.0",
+    "what-router": "^0.12.0",
+    "what-server": "^0.12.0",
+    "what-compiler": "^0.12.0"
   }
 }

package/router.d.ts

@@ -1,6 +1,6 @@
 // What Framework Router - TypeScript Definitions
 
-import { VNode, VNodeChild, Component, Signal, Computed } from './index';
+import { VNode, VNodeChild, Component, Signal, Computed } from './index.js';
 
 // --- Route State ---
 
@@ -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 {
@@ -52,7 +49,7 @@ export interface RouteConfig {
   /** Loading component */
   loading?: Component<{}>;
   /** Error component */
-  error?: Component<{ error: Error }>;
+  error?: Component<{ error: Error; reset: () => void }>;
   /** Route middleware */
   middleware?: RouteMiddleware[];
 }
@@ -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; reset: () => void }>;
+}
+
+/** 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,113 +1,11 @@
-// What Framework Server - TypeScript Definitions
-
-import { VNode, VNodeChild, Signal } from './index';
-
-// --- SSR ---
-
-/** Render VNode tree to HTML string */
-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;
-
-// --- Page Configuration ---
-
-export interface PageConfig {
-  /** Rendering mode */
-  mode?: 'static' | 'server' | 'client' | 'hybrid';
-  /** Page title */
-  title?: string;
-  /** Meta tags */
-  meta?: Record<string, string>;
-  /** Page component */
-  component: (data?: any) => VNode;
-  /** Islands to hydrate */
-  islands?: string[];
-  /** Scripts to load */
-  scripts?: string[];
-  /** Stylesheets to load */
-  styles?: string[];
-}
-
-export function definePage(config: Partial<PageConfig>): PageConfig;
-
-// --- Islands ---
-
-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;
-  /** Media query for 'media' mode */
-  media?: string;
-  /** Priority (higher = hydrate first) */
-  priority?: number;
-  /** Shared stores this island uses */
-  stores?: string[];
-}
-
-/** Register an island component */
-export function island(
-  name: string,
-  loader: () => Promise<any>,
-  options?: IslandOptions
-): void;
-
-/** Island component wrapper for SSR */
-export function Island(props: {
-  name: string;
-  props?: Record<string, any>;
-  mode?: IslandMode;
-  priority?: number;
-  stores?: string[];
-  children?: VNodeChild;
-}): VNode;
-
-/** Hydrate all islands on the page */
-export function hydrateIslands(): void;
-
-// --- Server Actions ---
-
-export interface ActionOptions {
-  id?: string;
-  onError?: (error: Error) => void;
-  onSuccess?: (result: any) => void;
-  revalidate?: string[];
-}
-
-/** Create a server action */
-export function createAction<T extends any[], R>(
-  fn: (...args: T) => Promise<R>,
-  options?: ActionOptions
-): (...args: T) => Promise<R>;
-
-/** Hook for using server actions */
-export interface UseActionResult<T extends any[], R> {
-  trigger: (...args: T) => Promise<R>;
-  isPending: () => boolean;
-  error: () => Error | null;
-  data: () => R | null;
-  reset: () => void;
-}
-
-export function useAction<T extends any[], R>(
-  actionFn: (...args: T) => Promise<R>
-): UseActionResult<T, R>;
+// what-framework/server re-exports the full server API. Its runtime
+// (src/server.js) is a pure barrel, so its declarations are one too: this file
+// used to hand-mirror what-server's surface and had drifted 45 exports behind it,
+// which is invisible to every TypeScript user and caught by nothing.
+export * from 'what-server';
+export * from 'what-server/islands';
+
+// The island shapes are exported by both entries (the root re-exports them for
+// convenience). An explicit re-export outranks the two star exports and resolves
+// the ambiguity, which is what TS2308 asks for.
+export type { IslandOptions, IslandStore, IslandStatus } from 'what-server/islands';

package/testing.d.ts

@@ -1,103 +1,3 @@
-// What Framework - Testing Utilities Type Definitions
-
-import { VNode, Signal } from './index';
-
-// Setup and Cleanup
-export function setupDOM(): HTMLElement | null;
-export function cleanup(): void;
-
-// Render
-export interface RenderResult {
-  container: HTMLElement;
-  unmount: () => void;
-  getByText: (text: string | RegExp) => HTMLElement | null;
-  getByTestId: (id: string) => HTMLElement | null;
-  getByRole: (role: string) => HTMLElement | null;
-  getAllByText: (text: string | RegExp) => HTMLElement[];
-  queryByText: (text: string | RegExp) => HTMLElement | null;
-  queryByTestId: (id: string) => HTMLElement | null;
-  debug: () => void;
-  findByText: (text: string | RegExp, timeout?: number) => Promise<HTMLElement>;
-  findByTestId: (id: string, timeout?: number) => Promise<HTMLElement>;
-}
-
-export interface RenderOptions {
-  container?: HTMLElement;
-}
-
-export function render(vnode: VNode, options?: RenderOptions): RenderResult;
-
-// Fire Events
-export interface FireEvent {
-  click(element: HTMLElement): MouseEvent;
-  change(element: HTMLInputElement, value: string): Event;
-  input(element: HTMLInputElement, value: string): Event;
-  submit(element: HTMLFormElement): Event;
-  focus(element: HTMLElement): FocusEvent;
-  blur(element: HTMLElement): FocusEvent;
-  keyDown(element: HTMLElement, key: string, options?: KeyboardEventInit): KeyboardEvent;
-  keyUp(element: HTMLElement, key: string, options?: KeyboardEventInit): KeyboardEvent;
-  mouseEnter(element: HTMLElement): MouseEvent;
-  mouseLeave(element: HTMLElement): MouseEvent;
-}
-
-export const fireEvent: FireEvent;
-
-// Wait Utilities
-export interface WaitOptions {
-  timeout?: number;
-  interval?: number;
-}
-
-export function waitFor<T>(callback: () => T, options?: WaitOptions): Promise<T>;
-export function waitForElementToBeRemoved(callback: () => HTMLElement | null, options?: WaitOptions): Promise<void>;
-
-// Act
-export function act<T>(callback: () => T | Promise<T>): Promise<T>;
-
-// Signal Testing Helpers
-export interface TestSignal<T> {
-  signal: Signal<T>;
-  value: T;
-  history: T[];
-  reset(): void;
-}
-
-export function createTestSignal<T>(initial: T): TestSignal<T>;
-
-// Mocking
-export interface MockComponent {
-  (props: Record<string, any>): VNode;
-  displayName: string;
-  calls: Array<{ props: Record<string, any>; timestamp: number }>;
-  lastCall(): { props: Record<string, any>; timestamp: number } | undefined;
-  reset(): void;
-}
-
-export function mockComponent(name?: string): MockComponent;
-
-// Assertions
-export interface Expect {
-  toBeInTheDocument(element: HTMLElement | null): void;
-  toHaveTextContent(element: HTMLElement | null, text: string | RegExp): void;
-  toHaveAttribute(element: HTMLElement | null, attr: string, value?: string): void;
-  toHaveClass(element: HTMLElement | null, className: string): void;
-  toBeVisible(element: HTMLElement | null): void;
-  toBeDisabled(element: HTMLElement | null): void;
-  toHaveValue(element: HTMLInputElement | null, value: string): void;
-}
-
-export const expect: Expect;
-
-// Screen
-export interface Screen {
-  getByText(text: string | RegExp): HTMLElement | null;
-  getByTestId(id: string): HTMLElement | null;
-  getByRole(role: string): HTMLElement | null;
-  getAllByText(text: string | RegExp): HTMLElement[];
-  queryByText(text: string | RegExp): HTMLElement | null;
-  queryByTestId(id: string): HTMLElement | null;
-  debug(): void;
-}
-
-export const screen: Screen;
+// what-framework/testing re-exports what-core/testing. Runtime is a pure barrel
+// (src/testing.js), so the declarations mirror it rather than duplicating them.
+export * from 'what-core/testing';