ignotum 0.0.13 → 0.0.15

package/src/client/router.ts

@@ -0,0 +1,324 @@
+import {
+  buildUrl,
+  compilePatterns,
+  decodeRouteInputs,
+  matchPattern,
+  parseLocation,
+} from "@ignotum/shared/routing";
+import { Effect, Predicate, Schema } from "effect";
+import { createContext, createElement, type JSX } from "preact";
+import { useContext, useEffect, useLayoutEffect, useRef, useState } from "preact/hooks";
+import {
+  getRouteDefinition,
+  type RouteReference,
+  type ReferenceTypes,
+} from "../internal/routes.js";
+import type { RouteInputs, RouteMatch, RouteLocation, NavigationResult } from "./routes.js";
+import type {
+  RouterStore,
+  RouterSnapshot,
+  NavigationOptions,
+  NavigationState,
+  BlockerState,
+} from "./router-store.js";
+
+export const RouterContext = createContext<RouterStore | undefined>(undefined);
+const useRouter = (): RouterStore => {
+  const router = useContext(RouterContext);
+  if (router === undefined)
+    throw new Error("Ignotum routing hooks require a managed client mount.");
+  return router;
+};
+export const useRouterSnapshot = (router: RouterStore): RouterSnapshot => {
+  const [snapshot, setSnapshot] = useState(router.getSnapshot);
+  useLayoutEffect(() => {
+    const update = () => setSnapshot(router.getSnapshot());
+    const unsubscribe = router.subscribe(update);
+    update();
+    return unsubscribe;
+  }, [router]);
+  return snapshot;
+};
+
+type OptionsArgs<Options> = {} extends Options ? [options?: Options] : [options: Options];
+export type NavigateOptions<Reference extends RouteReference> = RouteInputs<Reference> &
+  NavigationOptions;
+export interface Navigate {
+  <Reference extends RouteReference>(
+    reference: Reference,
+    ...args: OptionsArgs<NavigateOptions<NoInfer<Reference>>>
+  ): Promise<NavigationResult>;
+  back(): void;
+  forward(): void;
+}
+
+export function url<Reference extends RouteReference>(
+  reference: Reference,
+  ...args: OptionsArgs<RouteInputs<NoInfer<Reference>>>
+): string {
+  return Effect.runSync(buildUrl(getRouteDefinition(reference), args[0]));
+}
+
+// Link and navigate own additional options; only URL fields belong to the shared URL codec.
+const destinationHref = (
+  reference: RouteReference,
+  input: {
+    readonly params?: unknown;
+    readonly searchParams?: unknown;
+    readonly hash?: string;
+  } = {},
+): string =>
+  Effect.runSync(
+    buildUrl(getRouteDefinition(reference), {
+      params: input.params,
+      searchParams: input.searchParams,
+      hash: input.hash,
+    }),
+  );
+
+const NavigationInput = Schema.Struct({
+  params: Schema.optional(Schema.Unknown),
+  searchParams: Schema.optional(Schema.Unknown),
+  hash: Schema.optional(Schema.String),
+  replace: Schema.optional(Schema.Boolean),
+  scroll: Schema.optional(Schema.Literals(["auto", "preserve"])),
+}).annotate({ parseOptions: { onExcessProperty: "error" } });
+
+export const useNavigate = (): Navigate => {
+  const router = useRouter();
+  const [navigate] = useState<Navigate>(() =>
+    Object.assign(
+      <Reference extends RouteReference>(
+        reference: Reference,
+        ...args: OptionsArgs<NavigateOptions<NoInfer<Reference>>>
+      ) => {
+        const options = Schema.decodeUnknownSync(NavigationInput)(args[0] ?? {});
+        return router.navigate(destinationHref(reference, options), options);
+      },
+      { back: router.back, forward: router.forward },
+    ),
+  );
+  return navigate;
+};
+export const useLocation = (): RouteLocation => {
+  const snapshot = useRouterSnapshot(useRouter());
+  if (snapshot.location === undefined)
+    throw new Error("The initial Ignotum location has not committed.");
+  return snapshot.location;
+};
+export const useNavigation = (): NavigationState => useRouterSnapshot(useRouter()).navigation;
+
+export const useBlocker = ({ when }: { readonly when: boolean }): BlockerState => {
+  const router = useRouter();
+  const [id] = useState(() => Symbol("blocker"));
+  useRouterSnapshot(router);
+  useLayoutEffect(() => {
+    router.setBlocker(id, when);
+  }, [router, id, when]);
+  useLayoutEffect(() => () => router.setBlocker(id, false), [router, id]);
+  return router.getBlocker(id);
+};
+
+const matchReference = <Reference extends RouteReference>(
+  reference: Reference,
+  snapshot: RouterSnapshot,
+  end: boolean,
+): RouteMatch<Reference> | undefined => {
+  const location = snapshot.location;
+  const outcome = snapshot.branch?.outcome;
+  if (location === undefined || outcome === undefined) return;
+  const definition = getRouteDefinition(reference);
+  if (end && (outcome._tag !== "Matched" || outcome.route.id !== definition.id)) return;
+  const parsed = Effect.runSync(
+    parseLocation(`${location.pathname}${location.search}`).pipe(Effect.result),
+  );
+  if (parsed._tag === "Failure") return;
+  const compiled = Effect.runSync(compilePatterns([{ ...definition, layouts: [] }], []));
+  for (let length = parsed.success.segments.length; length >= 0; length--) {
+    if (length === 0 && parsed.success.segments.length !== 0) break;
+    const match = matchPattern(compiled, parsed.success.segments.slice(0, length));
+    if (match.route !== undefined) {
+      const decoded = Effect.runSync(
+        decodeRouteInputs(definition, match.params, location.search).pipe(Effect.result),
+      );
+      if (decoded._tag === "Failure") return;
+      // SAFETY: The reference's own validated descriptors determine these decoded generic input types.
+      return { ...decoded.success, hash: location.hash } as RouteMatch<Reference>;
+    }
+    if (end) break;
+  }
+  return;
+};
+export function useMatch<Reference extends RouteReference>(
+  reference: Reference,
+  options?: { readonly end?: boolean },
+): RouteMatch<Reference> | undefined {
+  return matchReference(reference, useRouterSnapshot(useRouter()), options?.end ?? true);
+}
+export type RouteState<Reference extends RouteReference> = RouteMatch<Reference> & {
+  readonly setSearchParams: (
+    next:
+      | ReferenceTypes<Reference>["searchInputs"]
+      | ((
+          current: ReferenceTypes<Reference>["searchParams"],
+        ) => ReferenceTypes<Reference>["searchInputs"]),
+    options?: NavigationOptions,
+  ) => Promise<NavigationResult>;
+};
+export function useRoute<Reference extends RouteReference>(
+  reference: Reference,
+): RouteState<Reference> {
+  const router = useRouter();
+  const snapshot = useRouterSnapshot(router);
+  const match = matchReference(reference, snapshot, true);
+  if (match === undefined)
+    throw new Error(`useRoute requires page '${getRouteDefinition(reference).id}' to be active.`);
+  return {
+    ...match,
+    setSearchParams: (next, options) => {
+      const latest = matchReference(reference, router.getSnapshot(), true);
+      const location = router.getSnapshot().location;
+      if (latest === undefined || location === undefined)
+        throw new Error("Cannot update search parameters for an inactive route.");
+      // A function is the only callable alternative in the public search update union.
+      const inputs = Predicate.isFunction(next) ? next(latest.searchParams) : next;
+      const href = destinationHref(reference, {
+        params: latest.params,
+        searchParams: inputs,
+        hash: latest.hash,
+      });
+      const destination = new URL(href, router.browser.location.origin);
+      destination.pathname = location.pathname;
+      const declared = new Set(
+        getRouteDefinition(reference).searchParams.map((field) => field.name),
+      );
+      for (const [name, value] of new URLSearchParams(location.search)) {
+        if (!declared.has(name)) destination.searchParams.append(name, value);
+      }
+      return router.navigate(`${destination.pathname}${destination.search}${destination.hash}`, {
+        scroll: "preserve",
+        ...options,
+      });
+    },
+  };
+}
+
+type AnchorProps = Omit<JSX.AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "class" | "ref">;
+export type LinkProps<Reference extends RouteReference> = AnchorProps &
+  NavigateOptions<Reference> & {
+    readonly to: Reference;
+    readonly class?: string;
+    readonly preload?: "intent" | "none";
+  };
+export type NavLinkProps<Reference extends RouteReference> = Omit<LinkProps<Reference>, "class"> & {
+  readonly end?: boolean;
+  readonly class?: string | ((state: { readonly isActive: boolean }) => string);
+};
+
+const activePath = (current: string, destination: string, end: boolean): boolean => {
+  const source = Effect.runSync(parseLocation(current).pipe(Effect.result));
+  const target = Effect.runSync(parseLocation(destination).pipe(Effect.result));
+  if (source._tag === "Failure" || target._tag === "Failure") return false;
+  const from = source.success.segments;
+  const to = target.success.segments;
+  if (from.length !== to.length && (end || to.length === 0 || from.length < to.length))
+    return false;
+  return to.every((segment, index) => from[index] === segment);
+};
+
+interface AnchorRuntimeProps extends AnchorProps, NavigationOptions {
+  readonly to: RouteReference;
+  readonly params?: unknown;
+  readonly searchParams?: unknown;
+  readonly hash?: string;
+  readonly preload?: "intent" | "none";
+  readonly end?: boolean;
+  readonly active?: boolean;
+  readonly class?: string | ((state: { readonly isActive: boolean }) => string);
+}
+function Anchor(props: AnchorRuntimeProps): JSX.Element {
+  const router = useRouter();
+  const snapshot = useRouterSnapshot(router);
+  const {
+    to,
+    params,
+    searchParams,
+    hash,
+    replace,
+    scroll,
+    preload = "intent",
+    end = true,
+    active = false,
+    class: className,
+    onClick,
+    onMouseEnter,
+    onFocus,
+    ...attributes
+  } = props;
+  const href = destinationHref(to, { params, searchParams, hash });
+  const isActive =
+    active &&
+    snapshot.location !== undefined &&
+    activePath(snapshot.location.pathname, href.split(/[?#]/)[0]!, end);
+  const prepare = () => {
+    if (preload !== "none") void router.preload(href).catch(() => {});
+  };
+  return createElement("a", {
+    ...attributes,
+    href,
+    class: Predicate.isFunction(className) ? className({ isActive }) : className,
+    "aria-current": isActive ? "page" : attributes["aria-current"],
+    onClick: (event: JSX.TargetedMouseEvent<HTMLAnchorElement>): void => {
+      onClick?.(event);
+      const anchor = event.currentTarget;
+      if (
+        event.defaultPrevented ||
+        event.button !== 0 ||
+        event.metaKey ||
+        event.ctrlKey ||
+        event.shiftKey ||
+        event.altKey ||
+        (anchor.target !== "" && anchor.target.toLowerCase() !== "_self") ||
+        anchor.hasAttribute("download") ||
+        anchor.relList.contains("external") ||
+        anchor.origin !== router.browser.location.origin ||
+        `${anchor.pathname}${anchor.search}${anchor.hash}` !== href
+      )
+        return;
+      event.preventDefault();
+      void router.navigate(href, { replace, scroll });
+    },
+    onMouseEnter: (event: JSX.TargetedMouseEvent<HTMLAnchorElement>): void => {
+      onMouseEnter?.(event);
+      if (!event.defaultPrevented) prepare();
+    },
+    onFocus: (event: JSX.TargetedFocusEvent<HTMLAnchorElement>): void => {
+      onFocus?.(event);
+      if (!event.defaultPrevented) prepare();
+    },
+  });
+}
+export function Link<Reference extends RouteReference>(props: LinkProps<Reference>): JSX.Element {
+  return createElement(Anchor, props);
+}
+export function NavLink<Reference extends RouteReference>(
+  props: NavLinkProps<Reference>,
+): JSX.Element {
+  return createElement(Anchor, { ...props, active: true });
+}
+export type RedirectProps<Reference extends RouteReference> = NavigateOptions<Reference> & {
+  readonly to: Reference;
+};
+export function Redirect<Reference extends RouteReference>(props: RedirectProps<Reference>): null {
+  const router = useRouter();
+  const href = destinationHref(props.to, props);
+  const previous = useRef<string>();
+  const replace = props.replace ?? true;
+  useEffect(() => {
+    const identity = JSON.stringify([href, replace, props.scroll]);
+    if (previous.current === identity) return;
+    previous.current = identity;
+    void router.navigate(href, { replace, scroll: props.scroll }, true);
+  }, [router, href, replace, props.scroll]);
+  return null;
+}

package/src/client/routes.ts

@@ -0,0 +1,28 @@
+import type { ReferenceTypes } from "../internal/routes.js";
+
+type Empty = Readonly<Record<string, never>>;
+type Group<Name extends string, Fields> = keyof Fields extends never
+  ? { readonly [Key in Name]?: Empty }
+  : {} extends Fields
+    ? { readonly [Key in Name]?: Fields }
+    : { readonly [Key in Name]: Fields };
+
+/** Decoded values delivered to a page component. */
+export type RouteProps<Reference> = {
+  readonly params: ReferenceTypes<Reference>["params"];
+  readonly searchParams: ReferenceTypes<Reference>["searchParams"];
+};
+/** URL inputs. Search defaults can be omitted when navigating. */
+export type RouteInputs<Reference> = Group<"params", ReferenceTypes<Reference>["params"]> &
+  Group<"searchParams", ReferenceTypes<Reference>["searchInputs"]> & { readonly hash?: string };
+export type RouteMatch<Reference> = RouteProps<Reference> & { readonly hash: string };
+export interface RouteLocation {
+  readonly pathname: string;
+  readonly search: string;
+  readonly hash: string;
+  readonly key: string;
+}
+export type NavigationResult =
+  | { readonly status: "committed" }
+  | { readonly status: "cancelled" }
+  | { readonly status: "failed"; readonly error: unknown };