@kasperrt/smolter 0.0.0-stage → 0.0.1-rc.1

package/src/internal/react/context.ts

@@ -0,0 +1,46 @@
+/**
+ * React components and typed data hooks. Import from smolter/react.
+ * @module
+ */
+
+import type { Router, Snapshot } from "../core/index.ts";
+import type { ReactNode } from "./runtime.ts";
+import {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useSyncExternalStore,
+} from "./runtime.ts";
+
+const RouterContext = createContext<Router | undefined>(undefined);
+
+/** Router instance and children rendered within its context. */
+export interface RouterProviderProps {
+  router: Router;
+  children?: ReactNode;
+}
+
+/** Provide a router to descendant hooks and connect its browser lifecycle. */
+export function RouterProvider({
+  router,
+  children,
+}: RouterProviderProps): ReactNode {
+  useEffect(router.start, [router]);
+
+  return createElement(RouterContext.Provider, { value: router }, children);
+}
+/** Hooks require a RouterProvider. */
+export function useRouter(): Router {
+  return useContext(RouterContext) as Router;
+}
+
+type SnapshotSelector<T> = (snapshot: Snapshot) => T;
+
+export function useSnapshot<T>(select: SnapshotSelector<T>): T {
+  const router = useRouter();
+
+  const getSnapshot = () => select(router.getSnapshot());
+
+  return useSyncExternalStore(router.subscribe, getSnapshot, getSnapshot);
+}

package/src/internal/react/fetcher.ts

@@ -0,0 +1,83 @@
+/**
+ * React components and typed data hooks. Import from smolter/react.
+ * @module
+ */
+
+import type {
+  AnyDataFunction,
+  DataFunction,
+  DataOf,
+  FetcherSnapshot,
+  Result,
+  Route as RouteDefinition,
+  RouteModule,
+  SubmitOptions,
+} from "../core/index.ts";
+import { useRouter } from "./context.ts";
+import { Form, type FormProps } from "./form.ts";
+import type { ComponentType } from "./runtime.ts";
+import {
+  createElement,
+  useEffect,
+  useMemo,
+  useSyncExternalStore,
+} from "./runtime.ts";
+
+/** Action method and optional explicit route URL for a fetcher submission. */
+export interface FetcherSubmitOptions extends SubmitOptions {
+  action?: string;
+}
+
+/** Typed independent request state, methods, and a bound Form component. */
+export interface TypedFetcher<T> extends Omit<FetcherSnapshot, "data"> {
+  data?: T;
+  Form: ComponentType<FormProps>;
+  load: (url?: string) => Promise<Result>;
+  submit: (body: FormData, options?: FetcherSubmitOptions) => Promise<Result>;
+}
+
+/** Create a fetcher for independent route reads and mutations; its data stays local. */
+export function useFetcher<T extends RouteModule>(
+  route: RouteDefinition<T>,
+): TypedFetcher<
+  | DataOf<Extract<T["action"] | T["clientAction"], AnyDataFunction>>
+  | DataOf<Extract<T["loader"] | T["clientLoader"], AnyDataFunction>>
+>;
+
+/** Create a fetcher for independent route reads and mutations; its data stays local. */
+export function useFetcher<
+  T extends AnyDataFunction = DataFunction,
+>(): TypedFetcher<DataOf<T>>;
+
+/** Create a fetcher for independent route reads and mutations; its data stays local. */
+export function useFetcher(route?: RouteDefinition): TypedFetcher<unknown> {
+  const router = useRouter();
+  const path = route?.path;
+  const fetcher = useMemo(() => {
+    const store = router.createFetcher();
+    const target = () => {
+      const snapshot = router.getSnapshot();
+
+      return path === undefined || path === snapshot.path ? snapshot.url : path;
+    };
+
+    return {
+      ...store,
+      Form: (props: FormProps) =>
+        createElement(Form, { action: target(), ...props, fetcher: store }),
+      load: (url?: string) => store.load(url ?? target()),
+      submit: (body: FormData, options?: FetcherSubmitOptions) =>
+        store.submit(options?.action ?? target(), body, options),
+    };
+  }, [router, path]);
+
+  useEffect(() => fetcher.dispose, [fetcher]);
+
+  const state = useSyncExternalStore(
+    fetcher.subscribe,
+    fetcher.getSnapshot,
+    fetcher.getSnapshot,
+  );
+
+  return { ...fetcher, ...state };
+}

package/src/internal/react/form.ts

@@ -0,0 +1,79 @@
+/**
+ * React components and typed data hooks. Import from smolter/react.
+ * @module
+ */
+
+import type { Fetcher, SubmitOptions } from "../core/index.ts";
+import { internalURL } from "../core/index.ts";
+import { useRouter } from "./context.ts";
+import type { FormHTMLAttributes, ReactNode } from "./runtime.ts";
+import { createElement } from "./runtime.ts";
+
+/** Form attributes with GET loader requests or POST, PUT, PATCH, and DELETE actions. */
+export interface FormProps
+  extends Omit<FormHTMLAttributes<HTMLFormElement>, "action" | "method"> {
+  action?: string;
+  method?: "get" | "post" | "put" | "patch" | "delete";
+}
+
+type FormSubmitEvent = Parameters<NonNullable<FormProps["onSubmit"]>>[0];
+
+interface InternalFormProps extends FormProps {
+  fetcher?: Fetcher;
+}
+
+/** Submit form data to a registered route without a document reload. */
+export function Form({
+  action,
+  method = "post",
+  fetcher,
+  onSubmit,
+  ...props
+}: InternalFormProps): ReactNode {
+  const router = useRouter();
+  const submit = (event: FormSubmitEvent) => {
+    onSubmit?.(event);
+
+    if (event.defaultPrevented) return;
+
+    const submitter = (event.nativeEvent as SubmitEvent).submitter;
+    const target = internalURL(
+      router.getSnapshot().url,
+      submitter?.getAttribute("formaction") ?? action,
+    );
+
+    if (!target) return;
+    event.preventDefault();
+
+    const data = new FormData(event.currentTarget, submitter);
+    const verb = (
+      submitter?.getAttribute("formmethod") ?? method
+    ).toUpperCase();
+
+    if (verb === "GET") {
+      const search = new URLSearchParams();
+
+      for (const [key, value] of data)
+        search.append(key, typeof value === "string" ? value : value.name);
+
+      target.search = String(search);
+
+      void (fetcher ? fetcher.load : router.navigate)(target.href);
+
+      return;
+    }
+
+    const options: SubmitOptions = {
+      method: verb as SubmitOptions["method"],
+    };
+
+    void (fetcher ?? router).submit(target.href, data, options);
+  };
+
+  return createElement("form", {
+    ...props,
+    action,
+    method: method === "get" ? "get" : "post",
+    onSubmit: submit,
+  });
+}

package/src/internal/react/hooks.ts

@@ -0,0 +1,72 @@
+/**
+ * React components and typed data hooks. Import from smolter/react.
+ * @module
+ */
+
+import type {
+  AnyDataFunction,
+  DataOf,
+  Route,
+  RouteModule,
+  Router,
+  Snapshot,
+} from "../core/index.ts";
+
+import { useRouter, useSnapshot } from "./context.ts";
+
+/** A route module or loader function used for data inference. */
+export type LoaderSource = RouteModule | AnyDataFunction;
+
+/** Infer server and client loader data from a route module or function. */
+export type LoaderData<T> = T extends AnyDataFunction
+  ? DataOf<T>
+  : T extends RouteModule
+    ? DataOf<Extract<T["loader"] | T["clientLoader"], AnyDataFunction>>
+    : unknown;
+
+/** Infer server and client action data from a route module or function. */
+export type ActionData<T> = T extends AnyDataFunction
+  ? DataOf<T>
+  : T extends RouteModule
+    ? DataOf<Extract<T["action"] | T["clientAction"], AnyDataFunction>>
+    : unknown;
+function useData(key: "data" | "actionData", route?: LoaderSource): unknown {
+  const path = (route as Route | undefined)?.path;
+
+  return useSnapshot((snapshot) => {
+    if (path !== undefined && path !== snapshot.path) return undefined;
+
+    return snapshot[key];
+  });
+}
+/** Pass a route for inference, or use useLoaderData<typeof loader>() in its module. */
+export function useLoaderData<T extends LoaderSource = RouteModule>(
+  route?: T,
+): LoaderData<T> | undefined {
+  return useData("data", route) as LoaderData<T> | undefined;
+}
+
+/** Read the last page action result, optionally inferring its type from a route. */
+export function useActionData<T extends LoaderSource = RouteModule>(
+  route?: T,
+): ActionData<T> | undefined {
+  return useData("actionData", route) as ActionData<T> | undefined;
+}
+
+/** Read path parameters for the active route. */
+export function useParams(): Snapshot["params"] {
+  return useSnapshot((snapshot) => snapshot.params);
+}
+
+/** Read the current path, search, and hash together with the navigate function. */
+export function useLocation(): readonly [string, Router["navigate"]] {
+  const router = useRouter();
+  const url = useSnapshot((snapshot) => snapshot.url);
+
+  return [url.replace(/^\w+:\/\/[^/]+/, ""), router.navigate];
+}
+
+/** Get the function that revalidates the current loader subject to shouldRevalidate. */
+export function useRevalidator(): Router["revalidate"] {
+  return useRouter().revalidate;
+}

package/src/internal/react/index.ts

@@ -0,0 +1,13 @@
+/** Framework components and typed data hooks. @module */
+export type * from "../core/index.ts";
+export { createRouter, defineRoute } from "../core/index.ts";
+export {
+  RouterProvider,
+  type RouterProviderProps,
+  useRouter,
+} from "./context.ts";
+export * from "./fetcher.ts";
+export * from "./form.ts";
+export * from "./hooks.ts";
+export * from "./link.ts";
+export * from "./routes.ts";

package/src/internal/react/link.ts

@@ -0,0 +1,46 @@
+/**
+ * React components and typed data hooks. Import from smolter/react.
+ * @module
+ */
+
+import { internalURL } from "../core/index.ts";
+import { useRouter } from "./context.ts";
+import type { AnchorHTMLAttributes, MouseEvent, ReactNode } from "./runtime.ts";
+import { createElement } from "./runtime.ts";
+
+/** Anchor attributes with internal navigation and optional history replacement. */
+export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  href: string;
+  replace?: boolean;
+}
+
+/** Render an anchor that handles internal navigation and preserves native modified clicks. */
+export function Link({
+  href,
+  replace,
+  onClick,
+  ...props
+}: LinkProps): ReactNode {
+  const router = useRouter();
+  const click = (event: MouseEvent<HTMLAnchorElement>) => {
+    onClick?.(event);
+
+    if (
+      event.defaultPrevented ||
+      event.button ||
+      event.metaKey ||
+      event.ctrlKey ||
+      event.altKey ||
+      event.shiftKey ||
+      props.download !== undefined ||
+      (props.target && props.target !== "_self")
+    )
+      return;
+
+    if (!internalURL(router.getSnapshot().url, href)) return;
+    event.preventDefault();
+    void router.navigate(href, { replace });
+  };
+
+  return createElement("a", { ...props, href, onClick: click });
+}

package/src/internal/react/routes.ts

@@ -0,0 +1,50 @@
+/**
+ * React components and typed data hooks. Import from smolter/react.
+ * @module
+ */
+
+import type { Route as RouteDefinition, RouteModule } from "../core/index.ts";
+import { useRouter, useSnapshot } from "./context.ts";
+import type { ComponentType, ReactNode } from "./runtime.ts";
+import { createElement, useMemo } from "./runtime.ts";
+
+/** Renderable route module with optional loading and error components. */
+export interface ViewModule extends RouteModule {
+  default?: ComponentType;
+  HydrateFallback?: ComponentType;
+  ErrorBoundary?: ComponentType<ErrorProps>;
+}
+
+/** Normalized route error supplied to an ErrorBoundary component. */
+export interface ErrorProps {
+  error: Error;
+}
+
+/** Fallback content used when no matching component can be rendered. */
+export interface RoutesProps {
+  fallback?: ReactNode;
+}
+/** Renders the first matching registered module. */
+export function Routes({ fallback = null }: RoutesProps): ReactNode {
+  const router = useRouter();
+  const state = useSnapshot((snapshot) => snapshot);
+  const module = router.routes.find((route) => route.path === state.path) as
+    | RouteDefinition<ViewModule>
+    | undefined;
+  const component = state.error
+    ? module?.ErrorBoundary
+    : state.state === "loading" && !state.loaded
+      ? module?.HydrateFallback
+      : module?.default;
+
+  const element = useMemo(
+    () =>
+      component &&
+      createElement(component as ComponentType<ErrorProps>, {
+        error: state.error!,
+      }),
+    [component, state.error],
+  );
+
+  return element ?? state.error?.message ?? fallback;
+}

package/src/internal/react/runtime.ts

@@ -0,0 +1,18 @@
+// @deno-types="npm:@types/react@19.3.0"
+
+// @deno-types="npm:@types/react@19.3.0"
+export type {
+  AnchorHTMLAttributes,
+  ComponentType,
+  FormHTMLAttributes,
+  MouseEvent,
+  ReactNode,
+} from "react";
+export {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useMemo,
+  useSyncExternalStore,
+} from "react";

package/src/internal/server/index.ts

@@ -0,0 +1,120 @@
+/**
+ * Request-scoped server rendering and HTTP data dispatch.
+ * @module
+ */
+
+import {
+  createRouter,
+  type DataFunction,
+  matchRoutes,
+  type Route,
+  type Router,
+  type Snapshot,
+  safeWrapAsync,
+} from "../core/index.ts";
+/** Create one router per server request, await this, then render the provider. */
+export async function loadRouter(
+  routes: readonly Route[],
+  input: string | Request,
+): Promise<Router> {
+  const url = typeof input === "string" ? input : input.url;
+  const wrap = (handler?: DataFunction): DataFunction | undefined => {
+    if (!handler || typeof input === "string") return handler;
+
+    return (args) => {
+      const signal = AbortSignal.any([input.signal, args.signal]);
+      const request = new Request(args.request, { signal });
+
+      input.headers.forEach((value, name) => {
+        if (!request.headers.has(name)) request.headers.set(name, value);
+      });
+
+      return handler({ ...args, request, signal });
+    };
+  };
+  const serverRoutes = routes.map((route) => ({
+    ...route,
+    clientLoader: undefined,
+    clientAction: undefined,
+    loader: wrap(route.loader),
+    action: wrap(route.action),
+  }));
+  const router = createRouter(serverRoutes, { url });
+
+  await router.navigate(url);
+
+  const snapshot = router.getSnapshot();
+
+  if (
+    !snapshot.error &&
+    snapshot.data === undefined &&
+    routes.some(
+      (route) =>
+        route.path === snapshot.path && route.clientLoader && !route.loader,
+    )
+  ) {
+    return createRouter(serverRoutes, {
+      url,
+      hydrationData: { ...snapshot, loaded: false, state: "loading" },
+    });
+  }
+
+  return router;
+}
+/** Safe inside a script element. Data must be JSON serializable; error stacks and causes are omitted. */
+export function serialize(snapshot: Snapshot): string {
+  return JSON.stringify({
+    ...snapshot,
+    error: snapshot.error && {
+      name: snapshot.error.name,
+      message: snapshot.error.message,
+    },
+  })
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+/** Dispatch an HTTP data request to a registered server loader or action. */
+export async function handleRequest(
+  routes: readonly Route[],
+  request: Request,
+): Promise<Response> {
+  const match = matchRoutes(routes, new URL(request.url).pathname);
+  const reading = request.method === "GET";
+
+  if (!match) return Response.json({ error: "No route" }, { status: 404 });
+
+  if (!reading && !["POST", "PUT", "PATCH", "DELETE"].includes(request.method))
+    return Response.json({ error: "Method not allowed" }, { status: 405 });
+
+  const handler = reading ? match.route.loader : match.route.action;
+
+  if (!handler)
+    return Response.json(
+      { error: `No ${reading ? "loader" : "action"}` },
+      { status: 405 },
+    );
+
+  const result = await safeWrapAsync(() =>
+    handler({ request, params: match.params, signal: request.signal }),
+  );
+  const error = result.error ?? (result.data instanceof Error && result.data);
+
+  if (error) return Response.json({ error: error.message }, { status: 500 });
+
+  if (result.data instanceof Response) {
+    const location = result.data.headers.get("Location");
+
+    if (location)
+      return new Response(null, {
+        headers: { "X-Smolter-Redirect": location },
+      });
+
+    return result.data;
+  }
+
+  return Response.json(result.data ?? null, {
+    headers: { "Cache-Control": "no-store" },
+  });
+}