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

package/src/internal/core/types.ts

@@ -0,0 +1,151 @@
+/**
+ * Framework-independent route matching, data requests, and state.
+ * @module
+ */
+
+/** Framework-independent data routing. No global request state. */
+export type Params = Record<string, string>;
+
+/** Request, path parameters, and cancellation signal passed to a data handler. */
+export interface DataArgs {
+  request: Request;
+  params: Params;
+  signal: AbortSignal;
+}
+
+/** A loader or action that returns data, a Response, or an Error value. */
+export type DataFunction = (args: DataArgs) => unknown;
+
+/** A handler signature used to infer data from specialized loader and action arguments. */
+export type AnyDataFunction = (...args: never[]) => unknown;
+
+/** Client loader arguments, including a typed call to the server loader. */
+export interface ClientLoaderArgs<L extends AnyDataFunction = DataFunction>
+  extends DataArgs {
+  serverLoader: () => Promise<DataOf<L>>;
+}
+
+/** Client action arguments, including a typed call to the server action. */
+export interface ClientActionArgs<A extends AnyDataFunction = DataFunction>
+  extends DataArgs {
+  serverAction: () => Promise<DataOf<A>>;
+}
+
+/** The resolved data returned by a handler, excluding Error values. */
+export type DataOf<F> = F extends AnyDataFunction
+  ? Exclude<Awaited<ReturnType<F>>, Error>
+  : undefined;
+
+/** Mutation details supplied when deciding whether to reload route data. */
+export interface RevalidationContext {
+  formMethod?: string;
+  formAction?: string;
+  formData?: FormData;
+  actionResult?: unknown;
+}
+
+/** Current URL, mutation result, and reason passed to shouldRevalidate. */
+export interface RevalidationArgs extends RevalidationContext {
+  currentUrl: URL;
+  nextUrl: URL;
+  defaultShouldRevalidate: boolean;
+  url: URL;
+  reason: "manual" | "action" | "navigation";
+}
+
+/** A route component and its optional server and client data handlers. */
+export interface RouteModule {
+  default?: unknown;
+  HydrateFallback?: unknown;
+  ErrorBoundary?: unknown;
+  loader?: DataFunction;
+  action?: DataFunction;
+  clientLoader?(args: ClientLoaderArgs): unknown;
+  clientAction?(args: ClientActionArgs): unknown;
+  shouldRevalidate?: (args: RevalidationArgs) => boolean;
+}
+
+/** A route module associated with an explicit URL pattern. */
+export type Route<M extends RouteModule = RouteModule> = M & { path: string };
+
+/** The first matching route and its decoded path parameters. */
+export interface Match {
+  route: Route;
+  params: Params;
+}
+/** Immutable current route state observed by framework hooks. */
+export interface Snapshot {
+  url: string;
+  path?: string;
+  params: Params;
+  data?: unknown;
+  /** Whether this route has completed a loader, including an undefined result. */
+  loaded?: boolean;
+  actionData?: unknown;
+  error?: Error;
+  state: "idle" | "loading" | "submitting";
+}
+
+/** Initial URL, browser history, and hydration configuration. */
+export interface RouterOptions {
+  url?: string;
+  /** Explicitly opt into browser history; leave off for SSR and tests. */
+  browser?: boolean;
+  hydrationData?: Snapshot;
+}
+
+/** Options for replacing rather than appending a browser history entry. */
+export interface NavigateOptions {
+  replace?: boolean;
+}
+
+/** HTTP method for a route action submission; defaults to POST. */
+export interface SubmitOptions {
+  method?: "POST" | "PUT" | "PATCH" | "DELETE";
+}
+
+/** A resolved operation result, with either data or a normalized Error. */
+export interface Result<T = unknown> {
+  data?: T;
+  error?: Error;
+}
+
+/** Independent fetcher data, error, and pending state. */
+export interface FetcherSnapshot extends Result {
+  state: Snapshot["state"];
+}
+
+/** An independent loader/action channel that does not navigate the page. */
+export interface Fetcher {
+  getSnapshot: () => FetcherSnapshot;
+  subscribe: (listener: () => void) => () => void;
+  load: (url: string) => Promise<Result>;
+  submit: (
+    url: string,
+    body: FormData,
+    options?: SubmitOptions,
+  ) => Promise<Result>;
+  /** Abort work and release subscriptions when this imperative fetcher is no longer used. */
+  dispose: () => void;
+}
+
+/** Route navigation, subscriptions, fetchers, and loader revalidation. */
+export interface Router {
+  routes: readonly Route[];
+  getSnapshot: () => Snapshot;
+  subscribe: (listener: () => void) => () => void;
+  start: () => () => void;
+  navigate: (url: string, options?: NavigateOptions) => Promise<void>;
+  revalidate: (
+    reason?: RevalidationArgs["reason"],
+    context?: RevalidationContext,
+  ) => Promise<void>;
+  submit: (
+    url: string,
+    body: FormData,
+    options?: SubmitOptions,
+  ) => Promise<Result>;
+  /** Create an independent fetcher. Framework useFetcher hooks manage disposal automatically. */
+  createFetcher: () => Fetcher;
+  dispose: () => void;
+}

package/src/internal/core/url.ts

@@ -0,0 +1,6 @@
+/** Resolve an internal URL; external links remain the browser's responsibility. */
+export function internalURL(base: string, href = base): URL | undefined {
+  const url = new URL(href, base);
+
+  if (url.origin === new URL(base).origin) return url;
+}

package/src/internal/files/index.ts

@@ -0,0 +1,112 @@
+/**
+ * Build-time discovery of flat file routes.
+ * @module
+ */
+
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { safeWrapAsync } from "../core/index.ts";
+
+/** A discovered flat route pattern and its module file path. */
+export interface RouteFile {
+  path: string;
+  file: string;
+}
+
+const routeFile = /^route\.[jt]sx?$/;
+const flatFile = /\.[jt]sx?$/;
+
+/** Read only flat files and immediate route folders. Colocated helpers are ignored. */
+export async function flatRoutes(
+  directory: string,
+): Promise<RouteFile[] | Error> {
+  const result = await safeWrapAsync(async () => {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const routes: RouteFile[] = [];
+    const patterns = new Set<string>();
+
+    for (const entry of entries) {
+      let name = entry.name;
+      let file = resolve(directory, name);
+
+      if (entry.isDirectory()) {
+        const candidates = (await readdir(file)).filter((name) =>
+          routeFile.test(name),
+        );
+
+        if (candidates.length > 1)
+          return new Error(`Multiple route files in ${file}`);
+
+        if (!candidates.length) continue;
+
+        file = resolve(file, candidates[0]);
+      } else {
+        if (!entry.isFile() || !flatFile.test(name) || name.endsWith(".d.ts"))
+          continue;
+
+        name = name.replace(flatFile, "");
+      }
+
+      if (/[()[\]:*?]/.test(name))
+        return new Error(`Unsupported flat route name: ${name}`);
+
+      const segments = name.split(".");
+      const parts: string[] = [];
+
+      for (const [index, segment] of segments.entries()) {
+        if (!segment) return new Error(`Empty route segment: ${name}`);
+
+        if (segment === "_index" && index !== segments.length - 1)
+          return new Error(`_index must be last: ${name}`);
+
+        if (segment === "$" && index !== segments.length - 1)
+          return new Error(`Splat must be last: ${name}`);
+
+        if (segment.startsWith("_")) continue;
+
+        const part = segment.replace(/_$/, "");
+        parts.push(part === "$" ? "*" : part.replace(/^\$/, ":"));
+      }
+
+      // Pathless grouping modules are not nested layouts in a flat router.
+      if (segments.at(-1)?.startsWith("_") && segments.at(-1) !== "_index")
+        continue;
+
+      const path = `/${parts.join("/")}`;
+      const pattern = path.replace(/:[^/]+/g, ":");
+
+      if (patterns.has(pattern))
+        return new Error(`Conflicting flat route: ${path}`);
+
+      patterns.add(pattern);
+      routes.push({ path, file });
+    }
+
+    return routes.sort((a, b) => {
+      const left = a.path.split("/");
+      const right = b.path.split("/");
+      const rank = (part: string | undefined) =>
+        part === "*"
+          ? 0
+          : part?.startsWith(":")
+            ? 1
+            : part === undefined
+              ? 2
+              : 3;
+
+      for (
+        let index = 0;
+        index < Math.max(left.length, right.length);
+        index++
+      ) {
+        const difference = rank(right[index]) - rank(left[index]);
+
+        if (difference) return difference;
+      }
+
+      return a.path.localeCompare(b.path);
+    });
+  });
+
+  return result.error ?? result.data!;
+}

package/src/internal/preact/context.ts

@@ -0,0 +1,46 @@
+/**
+ * Preact components and typed data hooks. Import from @kasperrt/smolter/preact.
+ * @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/preact/fetcher.ts

@@ -0,0 +1,83 @@
+/**
+ * Preact components and typed data hooks. Import from @kasperrt/smolter/preact.
+ * @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/preact/form.ts

@@ -0,0 +1,79 @@
+/**
+ * Preact components and typed data hooks. Import from @kasperrt/smolter/preact.
+ * @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 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/preact/hooks.ts

@@ -0,0 +1,72 @@
+/**
+ * Preact components and typed data hooks. Import from @kasperrt/smolter/preact.
+ * @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/preact/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/preact/link.ts

@@ -0,0 +1,46 @@
+/**
+ * Preact components and typed data hooks. Import from @kasperrt/smolter/preact.
+ * @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/preact/routes.ts

@@ -0,0 +1,50 @@
+/**
+ * Preact components and typed data hooks. Import from @kasperrt/smolter/preact.
+ * @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/preact/runtime.ts

@@ -0,0 +1,15 @@
+export type {
+  AnchorHTMLAttributes,
+  ComponentType,
+  FormHTMLAttributes,
+  MouseEvent,
+  ReactNode,
+} from "preact/compat";
+export {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useMemo,
+  useSyncExternalStore,
+} from "preact/compat";