vorma 0.0.0-pre.0 → 0.83.0

package/internal/framework/_typescript/client/src/ui_lib_impl_helpers/link_components.ts

@@ -0,0 +1,131 @@
+import { __getPrefetchHandlers, __makeLinkOnClickFn } from "../links.ts";
+import { __resolvePath } from "../vorma_app_helpers/vorma_app_helpers.ts";
+import { __vormaClientGlobal } from "../vorma_ctx/vorma_ctx.ts";
+
+export type VormaLinkPropsBase<LinkOnClickCallback> = {
+	href?: string;
+	prefetch?: "intent";
+	prefetchDelayMs?: number;
+	beforeBegin?: LinkOnClickCallback;
+	beforeRender?: LinkOnClickCallback;
+	afterRender?: LinkOnClickCallback;
+	scrollToTop?: boolean;
+	replace?: boolean;
+	state?: unknown;
+};
+
+function linkPropsToPrefetchObj<LinkOnClickCallback>(
+	props: VormaLinkPropsBase<LinkOnClickCallback>,
+) {
+	if (!props.href || props.prefetch !== "intent") {
+		return undefined;
+	}
+
+	return __getPrefetchHandlers({
+		href: props.href,
+		delayMs: props.prefetchDelayMs,
+		beforeBegin: props.beforeBegin as any,
+		beforeRender: props.beforeRender as any,
+		afterRender: props.afterRender as any,
+		scrollToTop: props.scrollToTop,
+		replace: props.replace,
+		state: props.state,
+	});
+}
+
+function linkPropsToOnClickFn<LinkOnClickCallback>(
+	props: VormaLinkPropsBase<LinkOnClickCallback>,
+) {
+	return __makeLinkOnClickFn({
+		beforeBegin: props.beforeBegin as any,
+		beforeRender: props.beforeRender as any,
+		afterRender: props.afterRender as any,
+		scrollToTop: props.scrollToTop,
+		replace: props.replace,
+		state: props.state,
+	});
+}
+
+type handlerKeys = {
+	onPointerEnter: string;
+	onFocus: string;
+	onPointerLeave: string;
+	onBlur: string;
+	onTouchCancel: string;
+	onClick: string;
+};
+
+const standardCamelHandlerKeys = {
+	onPointerEnter: "onPointerEnter",
+	onFocus: "onFocus",
+	onPointerLeave: "onPointerLeave",
+	onBlur: "onBlur",
+	onTouchCancel: "onTouchCancel",
+	onClick: "onClick",
+} satisfies handlerKeys;
+
+export function __makeFinalLinkProps<LinkOnClickCallback>(
+	props: VormaLinkPropsBase<LinkOnClickCallback>,
+	keys: {
+		onPointerEnter: string;
+		onFocus: string;
+		onPointerLeave: string;
+		onBlur: string;
+		onTouchCancel: string;
+		onClick: string;
+	} = standardCamelHandlerKeys,
+) {
+	const prefetchObj = linkPropsToPrefetchObj(props);
+
+	return {
+		dataExternal: prefetchObj?.isExternal || undefined,
+		onPointerEnter: (e: any) => {
+			prefetchObj?.start(e);
+			if (isFn((props as any)[keys.onPointerEnter])) {
+				(props as any)[keys.onPointerEnter](e);
+			}
+		},
+		onFocus: (e: any) => {
+			prefetchObj?.start(e);
+			if (isFn((props as any)[keys.onFocus])) {
+				(props as any)[keys.onFocus](e);
+			}
+		},
+		onPointerLeave: (e: any) => {
+			// we don't want to stop on a touch device, because this triggers
+			// even when the user "clicks" on the link for some reason
+			if (!__vormaClientGlobal.get("isTouchDevice")) {
+				prefetchObj?.stop();
+			}
+			if (isFn((props as any)[keys.onPointerLeave])) {
+				(props as any)[keys.onPointerLeave](e);
+			}
+		},
+		onBlur: (e: any) => {
+			prefetchObj?.stop();
+			if (isFn((props as any)[keys.onBlur])) {
+				(props as any)[keys.onBlur](e);
+			}
+		},
+		onTouchCancel: (e: any) => {
+			prefetchObj?.stop();
+			if (isFn((props as any)[keys.onTouchCancel])) {
+				(props as any)[keys.onTouchCancel](e);
+			}
+		},
+		onClick: async (e: any) => {
+			if (isFn((props as any)[keys.onClick])) {
+				(props as any)[keys.onClick](e);
+			}
+			if (prefetchObj) {
+				await prefetchObj.onClick(e);
+			} else {
+				await linkPropsToOnClickFn(props)(e);
+			}
+		},
+	};
+}
+
+function isFn(fn: any): fn is (...args: Array<any>) => any {
+	return typeof fn === "function";
+}

package/internal/framework/_typescript/client/src/ui_lib_impl_helpers/route_components.ts

@@ -0,0 +1,56 @@
+import {
+	__resolvePath,
+	type VormaAppBase,
+	type VormaLoaderPattern,
+	type VormaRouteParams,
+} from "../vorma_app_helpers/vorma_app_helpers.ts";
+import {
+	__vormaClientGlobal,
+	type getRouterData,
+} from "../vorma_ctx/vorma_ctx.ts";
+
+export type VormaRoutePropsGeneric<
+	JSXElement,
+	App extends VormaAppBase,
+	Pattern extends VormaLoaderPattern<App> = VormaLoaderPattern<App>,
+> = {
+	idx: number;
+	Outlet: (props: Record<string, any>) => JSXElement;
+	__phantom_pattern: Pattern;
+} & Record<string, any>;
+
+export type VormaRouteGeneric<
+	JSXElement,
+	App extends VormaAppBase,
+	Pattern extends VormaLoaderPattern<App> = VormaLoaderPattern<App>,
+> = (props: VormaRoutePropsGeneric<JSXElement, App, Pattern>) => JSXElement;
+
+export type ParamsForPattern<
+	App extends VormaAppBase,
+	Pattern extends VormaLoaderPattern<App>,
+> = VormaRouteParams<App, Pattern>;
+
+type BaseRouterData<RootData, Params extends string> = ReturnType<
+	typeof getRouterData<RootData, Record<Params, string>>
+>;
+
+type Wrapper<UseAccessor extends boolean, T> = UseAccessor extends false
+	? T
+	: () => T;
+
+export type UseRouterDataFunction<
+	App extends VormaAppBase,
+	UseAccessor extends boolean = false,
+> = {
+	<Pattern extends VormaLoaderPattern<App>>(
+		props: VormaRoutePropsGeneric<any, App, Pattern>,
+	): Wrapper<
+		UseAccessor,
+		BaseRouterData<App["rootData"], ParamsForPattern<App, Pattern>>
+	>;
+	<Pattern extends VormaLoaderPattern<App>>(): Wrapper<
+		UseAccessor,
+		BaseRouterData<App["rootData"], ParamsForPattern<App, Pattern>>
+	>;
+	(): Wrapper<UseAccessor, BaseRouterData<App["rootData"], string>>;
+};

package/internal/framework/_typescript/client/src/ui_lib_impl_helpers/typed_navigate.ts

@@ -0,0 +1,58 @@
+import { vormaNavigate } from "../client.ts";
+import {
+	__resolvePath,
+	type ExtractApp,
+	type PermissivePatternBasedProps,
+	type VormaAppBase,
+	type VormaAppConfig,
+	type VormaLoaderPattern,
+} from "../vorma_app_helpers/vorma_app_helpers.ts";
+import { __vormaClientGlobal } from "../vorma_ctx/vorma_ctx.ts";
+
+type TypedNavigateOptions<
+	App extends VormaAppBase,
+	Pattern extends VormaLoaderPattern<App>,
+> = PermissivePatternBasedProps<App, Pattern> & {
+	replace?: boolean;
+	scrollToTop?: boolean;
+	search?: string;
+	hash?: string;
+	state?: unknown;
+};
+
+export function makeTypedNavigate<C extends VormaAppConfig>(vormaAppConfig: C) {
+	type App = ExtractApp<C>;
+
+	return async function typedNavigate<
+		Pattern extends VormaLoaderPattern<App>,
+	>(options: TypedNavigateOptions<App, Pattern>): Promise<void> {
+		const {
+			pattern,
+			params,
+			splatValues,
+			replace,
+			scrollToTop,
+			search,
+			hash,
+			state,
+		} = options as any;
+
+		const href = __resolvePath({
+			vormaAppConfig,
+			type: "loader",
+			props: {
+				pattern,
+				...(params && { params }),
+				...(splatValues && { splatValues }),
+			},
+		});
+
+		return vormaNavigate(href, {
+			replace,
+			scrollToTop,
+			search,
+			hash,
+			state,
+		});
+	};
+}

package/internal/framework/_typescript/client/src/utils/errors.ts

@@ -0,0 +1,10 @@
+import { logError } from "./logging.ts";
+
+export function isAbortError(error: unknown) {
+	return error instanceof Error && error.name === "AbortError";
+}
+
+export function panic(msg?: string): never {
+	logError("Panic");
+	throw new Error(msg ?? "panic");
+}

package/internal/framework/_typescript/client/src/utils/logging.ts

@@ -0,0 +1,7 @@
+export function logInfo(message?: any, ...optionalParams: Array<any>) {
+	console.log("Vorma:", message, ...optionalParams);
+}
+
+export function logError(message?: any, ...optionalParams: Array<any>) {
+	console.error("Vorma:", message, ...optionalParams);
+}

package/internal/framework/_typescript/client/src/vorma_app_helpers/vorma_app_helpers.ts

@@ -0,0 +1,290 @@
+import { serializeToSearchParams } from "vorma/kit/json";
+import type { SubmitOptions } from "../client.ts";
+
+export type VormaAppConfig = {
+	actionsRouterMountRoot: string;
+	actionsDynamicRune: string;
+	actionsSplatRune: string;
+	loadersDynamicRune: string;
+	loadersSplatRune: string;
+	loadersExplicitIndexSegment: string;
+	__phantom?: any;
+};
+
+export type VormaAppBase = {
+	routes: readonly any[];
+	appConfig: VormaAppConfig;
+	rootData: any;
+};
+
+export type ExtractApp<C extends VormaAppConfig> = C["__phantom"];
+
+type RouteByType<App extends VormaAppBase, T extends string> = Extract<
+	App["routes"][number],
+	{ _type: T }
+>;
+
+type RouteByPattern<Routes, P> = Extract<Routes, { pattern: P }>;
+
+type VormaLoader<App extends VormaAppBase> = RouteByType<App, "loader">;
+type VormaQuery<App extends VormaAppBase> = RouteByType<App, "query">;
+type VormaMutation<App extends VormaAppBase> = RouteByType<App, "mutation">;
+
+// Pattern types
+export type VormaLoaderPattern<App extends VormaAppBase> =
+	VormaLoader<App>["pattern"];
+export type VormaQueryPattern<App extends VormaAppBase> =
+	VormaQuery<App>["pattern"];
+export type VormaMutationPattern<App extends VormaAppBase> =
+	VormaMutation<App>["pattern"];
+
+// IO types
+export type VormaLoaderOutput<
+	App extends VormaAppBase,
+	P extends VormaLoaderPattern<App>,
+> =
+	RouteByPattern<VormaLoader<App>, P> extends { phantomOutputType: infer T }
+		? T
+		: null | undefined;
+
+export type VormaQueryInput<
+	App extends VormaAppBase,
+	P extends VormaQueryPattern<App>,
+> =
+	RouteByPattern<VormaQuery<App>, P> extends { phantomInputType: infer T }
+		? T
+		: null | undefined;
+
+export type VormaQueryOutput<
+	App extends VormaAppBase,
+	P extends VormaQueryPattern<App>,
+> =
+	RouteByPattern<VormaQuery<App>, P> extends { phantomOutputType: infer T }
+		? T
+		: null | undefined;
+
+export type VormaMutationInput<
+	App extends VormaAppBase,
+	P extends VormaMutationPattern<App>,
+> =
+	RouteByPattern<VormaMutation<App>, P> extends { phantomInputType: infer T }
+		? T
+		: null | undefined;
+
+export type VormaMutationOutput<
+	App extends VormaAppBase,
+	P extends VormaMutationPattern<App>,
+> =
+	RouteByPattern<VormaMutation<App>, P> extends { phantomOutputType: infer T }
+		? T
+		: null | undefined;
+
+export type VormaMutationMethod<
+	App extends VormaAppBase,
+	P extends VormaMutationPattern<App>,
+> =
+	RouteByPattern<VormaMutation<App>, P> extends { method: infer M }
+		? M extends string
+			? M
+			: "POST"
+		: "POST";
+
+// Route metadata
+type RouteMetadata<App extends VormaAppBase, P extends string> = Extract<
+	App["routes"][number],
+	{ pattern: P }
+>;
+
+export type GetParams<App extends VormaAppBase, P extends string> =
+	RouteMetadata<App, P> extends { params: ReadonlyArray<infer Params> }
+		? Params extends string
+			? Params
+			: never
+		: never;
+
+export type VormaRouteParams<
+	App extends VormaAppBase,
+	P extends VormaLoaderPattern<App>,
+> = GetParams<App, P>;
+
+export type HasParams<App extends VormaAppBase, P extends string> =
+	GetParams<App, P> extends never ? false : true;
+
+export type IsSplat<App extends VormaAppBase, P extends string> =
+	RouteMetadata<App, P> extends { isSplat: true } ? true : false;
+
+export type IsEmptyInput<T> = [T] extends [null | undefined | never]
+	? true
+	: false;
+
+// Pattern-based props composition
+type ConditionalParams<App extends VormaAppBase, P extends string> =
+	HasParams<App, P> extends true
+		? { params: { [K in GetParams<App, P>]: string } }
+		: {};
+
+type ConditionalSplat<App extends VormaAppBase, P extends string> =
+	IsSplat<App, P> extends true ? { splatValues: Array<string> } : {};
+
+export type PatternBasedProps<App extends VormaAppBase, P extends string> = {
+	pattern: P;
+} & ConditionalParams<App, P> &
+	ConditionalSplat<App, P>;
+
+export type PermissivePatternBasedProps<
+	App extends VormaAppBase,
+	P extends VormaLoaderPattern<App>,
+> = {
+	pattern: PermissiveLoaderPattern<App, P>;
+} & ConditionalParams<App, P> &
+	ConditionalSplat<App, P>;
+
+type PermissiveLoaderPattern<
+	App extends VormaAppBase,
+	P extends VormaLoaderPattern<App>,
+> = P extends `${infer Prefix}/${App["appConfig"]["loadersExplicitIndexSegment"]}`
+	? P | (Prefix extends "" ? "/" : Prefix)
+	: P;
+
+export type VormaRoutePropsGeneric<
+	JSXElement,
+	App extends VormaAppBase,
+	P extends VormaLoaderPattern<App>,
+> = {
+	idx: number;
+	Outlet: (props: Record<string, any>) => JSXElement;
+	__phantom_pattern: P;
+} & Record<string, any>;
+
+/////////////////////////////////////////////////////////////////////
+/////// API CLIENT HELPERS
+/////////////////////////////////////////////////////////////////////
+
+type Props = PatternBasedProps<any, string> & {
+	options?: SubmitOptions;
+	requestInit?: RequestInit;
+	input?: any;
+};
+
+type APIClientHelperOpts = {
+	vormaAppConfig: VormaAppConfig;
+	type: "loader" | "query" | "mutation";
+	props: Props;
+};
+
+export type VormaQueryProps<
+	App extends VormaAppBase,
+	P extends VormaQueryPattern<App>,
+> = (PatternBasedProps<App, P> & {
+	options?: SubmitOptions;
+	requestInit?: Omit<RequestInit, "method"> & { method?: "GET" };
+}) &
+	(IsEmptyInput<VormaQueryInput<App, P>> extends true
+		? { input?: VormaQueryInput<App, P> }
+		: { input: VormaQueryInput<App, P> });
+
+export type VormaMutationProps<
+	App extends VormaAppBase,
+	P extends VormaMutationPattern<App>,
+> = PatternBasedProps<App, P> & {
+	options?: SubmitOptions;
+} & (VormaMutationMethod<App, P> extends "POST"
+		? { requestInit?: Omit<RequestInit, "method"> & { method?: "POST" } }
+		: {
+				requestInit: RequestInit & {
+					method: VormaMutationMethod<App, P>;
+				};
+			}) &
+	(IsEmptyInput<VormaMutationInput<App, P>> extends true
+		? { input?: VormaMutationInput<App, P> }
+		: { input: VormaMutationInput<App, P> });
+
+export function buildQueryURL(
+	vormaAppConfig: VormaAppConfig,
+	props: Props,
+): URL {
+	return buildURL({ vormaAppConfig, props, type: "query" });
+}
+
+export function buildMutationURL(
+	vormaAppConfig: VormaAppConfig,
+	props: Props,
+): URL {
+	return buildURL({ vormaAppConfig, props, type: "mutation" });
+}
+
+export function resolveBody(props: Props): BodyInit | null | undefined {
+	const { input } = props;
+	if (
+		input == null ||
+		typeof input === "string" ||
+		input instanceof Blob ||
+		input instanceof FormData ||
+		input instanceof URLSearchParams ||
+		input instanceof ReadableStream ||
+		input instanceof ArrayBuffer ||
+		ArrayBuffer.isView(input)
+	) {
+		return input;
+	}
+	return JSON.stringify(input);
+}
+
+function buildURL(opts: APIClientHelperOpts): URL {
+	const base_path = stripTrailingSlash(
+		opts.vormaAppConfig.actionsRouterMountRoot,
+	);
+	const resolved_path = __resolvePath(opts);
+	const url = new URL(base_path + resolved_path, getCurrentOrigin());
+
+	if (opts.type === "query" && opts.props.input) {
+		url.search = serializeToSearchParams(opts.props.input).toString();
+	}
+
+	return url;
+}
+
+export function __resolvePath(opts: APIClientHelperOpts): string {
+	const { props, vormaAppConfig } = opts;
+	let path = props.pattern;
+
+	let dynamicParamPrefixRune = vormaAppConfig.actionsDynamicRune;
+	let splatSegmentRune = vormaAppConfig.actionsSplatRune;
+
+	if (opts.type === "loader") {
+		dynamicParamPrefixRune = vormaAppConfig.loadersDynamicRune;
+		splatSegmentRune = vormaAppConfig.loadersSplatRune;
+	}
+
+	if ("params" in props && props.params) {
+		for (const [key, value] of Object.entries(props.params)) {
+			path = path.replace(
+				`${dynamicParamPrefixRune}${key}`,
+				String(value),
+			);
+		}
+	}
+
+	if ("splatValues" in props && props.splatValues) {
+		const splatPath = (props.splatValues as Array<string>).join("/");
+		path = path.replace(splatSegmentRune, splatPath);
+	}
+
+	// Strip explicit index segment
+	if (opts.type === "loader" && vormaAppConfig.loadersExplicitIndexSegment) {
+		const indexSegment = `/${vormaAppConfig.loadersExplicitIndexSegment}`;
+		if (path.endsWith(indexSegment)) {
+			path = path.slice(0, -indexSegment.length) || "/";
+		}
+	}
+
+	return path;
+}
+
+function getCurrentOrigin(): string {
+	return new URL(window.location.href).origin;
+}
+
+function stripTrailingSlash(path: string): string {
+	return path.endsWith("/") ? path.slice(0, -1) : path;
+}

package/internal/framework/_typescript/client/src/vorma_ctx/vorma_ctx.ts

@@ -0,0 +1,128 @@
+import type { PatternRegistry } from "vorma/kit/matcher/register";
+import type { VormaAppConfig } from "../vorma_app_helpers/vorma_app_helpers.ts";
+
+export type HeadEl = {
+	tag?: string;
+	attributesKnownSafe?: Record<string, string>;
+	booleanAttributes?: Array<string>;
+	dangerousInnerHTML?: string;
+};
+
+type Meta = {
+	title: HeadEl | null | undefined;
+	metaHeadEls: Array<HeadEl> | null | undefined;
+	restHeadEls: Array<HeadEl> | null | undefined;
+};
+
+type shared = {
+	outermostServerError?: string;
+	outermostClientError?: string;
+	outermostServerErrorIdx?: number;
+	outermostClientErrorIdx?: number;
+	outermostError?: string; // derived from above
+	outermostErrorIdx?: number; // derived from above
+
+	matchedPatterns: Array<string>;
+	loadersData: Array<any>;
+	importURLs: Array<string>;
+	exportKeys: Array<string>;
+	errorExportKeys: string[];
+	hasRootData: boolean;
+
+	params: Record<string, string>;
+	splatValues: Array<string>;
+
+	buildID: string;
+
+	activeComponents: Array<any> | null;
+	activeErrorBoundary?: any;
+};
+
+export type GetRouteDataOutput = Omit<shared, "buildID"> &
+	Meta & {
+		deps: Array<string>;
+		cssBundles: Array<string>;
+	};
+
+export const VORMA_SYMBOL = Symbol.for("__vorma_internal__");
+
+export type RouteErrorComponent = (props: { error: string }) => any;
+
+export type ClientLoaderAwaitedServerData<RD, LD> = {
+	matchedPatterns: string[];
+	loaderData: LD;
+	rootData: RD;
+	buildID: string;
+};
+
+export type VormaClientGlobal = shared & {
+	isDev: boolean;
+	viteDevURL: string;
+	publicPathPrefix: string;
+	isTouchDevice: boolean;
+	patternToWaitFnMap: Record<
+		string,
+		(props: {
+			params: Record<string, string>;
+			splatValues: string[];
+			serverDataPromise: Promise<ClientLoaderAwaitedServerData<any, any>>;
+			signal: AbortSignal;
+		}) => Promise<any>
+	>;
+	clientLoadersData: Array<any>;
+	defaultErrorBoundary: RouteErrorComponent;
+	useViewTransitions: boolean;
+	deploymentID: string;
+	vormaAppConfig: VormaAppConfig;
+	// SSR'd
+	routeManifestURL: string;
+	// Fetched at startup -- fine because progressive enhancement
+	// and not needed until any given route's second navigation
+	// anyway
+	routeManifest: Record<string, number> | undefined;
+	// built up as we navigate
+	clientModuleMap: Record<
+		string,
+		{
+			importURL: string;
+			exportKey: string;
+			errorExportKey: string;
+		}
+	>;
+	patternRegistry: PatternRegistry;
+};
+
+export function __getVormaClientGlobal() {
+	const dangerousGlobalThis = globalThis as any;
+	function get<K extends keyof VormaClientGlobal>(key: K) {
+		return dangerousGlobalThis[VORMA_SYMBOL][key] as VormaClientGlobal[K];
+	}
+	function set<
+		K extends keyof VormaClientGlobal,
+		V extends VormaClientGlobal[K],
+	>(key: K, value: V) {
+		dangerousGlobalThis[VORMA_SYMBOL][key] = value;
+	}
+	return { get, set };
+}
+
+export const __vormaClientGlobal = __getVormaClientGlobal();
+
+// to debug ctx in browser, paste this:
+// const vorma_ctx = window[Symbol.for("__vorma_internal__")];
+
+export function getRouterData<
+	T = any,
+	P extends Record<string, string> = Record<string, string>,
+>() {
+	const rootData: T = __vormaClientGlobal.get("hasRootData")
+		? __vormaClientGlobal.get("loadersData")[0]
+		: null;
+	return {
+		buildID: __vormaClientGlobal.get("buildID") || "",
+		matchedPatterns: __vormaClientGlobal.get("matchedPatterns") || [],
+		splatValues: __vormaClientGlobal.get("splatValues") || [],
+		params: (__vormaClientGlobal.get("params") || {}) as P,
+		rootData,
+	};
+}