@alchemy.run/sigil 0.0.0-alpha.3 → 0.0.0-alpha.5

package/src/router/components.tsx

@@ -0,0 +1,343 @@
+/** @jsxImportSource react */
+// MemoryRouter/Routes/Route/Navigate/Outlet are ported from react-router's
+// declarative components (lib/components.tsx, MIT). Link is Sigil-native.
+import {
+  Children,
+  Fragment,
+  isValidElement,
+  startTransition,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+
+import { Text, type Props as TextProps } from "#/components/Text.tsx";
+import { useFocus } from "#/hooks/use-focus.ts";
+import { useInput } from "#/hooks/use-input.ts";
+import { LocationContext, NavigationContext, type Navigator } from "#/router/context.ts";
+import {
+  createMemoryHistory,
+  type InitialEntry,
+  type Location,
+  type To,
+} from "#/router/history.ts";
+import {
+  useLocation,
+  useNavigate,
+  useOutlet,
+  useResolvedPath,
+  useRoutes,
+} from "#/router/hooks.tsx";
+import { normalizePathname, type RouteObject } from "#/router/matcher.ts";
+
+export type MemoryRouterProps = {
+  /**
+	The navigation stack to start with. Defaults to `["/"]`.
+	*/
+  initialEntries?: InitialEntry[];
+
+  /**
+	The index of the initial entry to render. Defaults to the last entry.
+	*/
+  initialIndex?: number;
+
+  children?: ReactNode;
+};
+
+/**
+The routing container for a Sigil app. Stores the navigation stack in memory —
+routes aren't URLs, they're screen states.
+
+```tsx
+<MemoryRouter>
+  <Routes>
+    <Route path="/" element={<Home />} />
+    <Route path="/settings" element={<Settings />} />
+  </Routes>
+</MemoryRouter>
+```
+*/
+export function MemoryRouter({ initialEntries, initialIndex, children }: MemoryRouterProps) {
+  const historyRef = useRef<ReturnType<typeof createMemoryHistory> | null>(null);
+  historyRef.current ??= createMemoryHistory({ initialEntries, initialIndex });
+
+  const history = historyRef.current;
+  const [state, setState] = useState({
+    action: history.action,
+    location: history.location,
+  });
+
+  // Navigation is a transition: if the destination screen suspends, the
+  // current screen stays visible until it's ready.
+  useLayoutEffect(
+    () =>
+      history.listen(({ action, location }) => {
+        startTransition(() => {
+          setState({ action, location });
+        });
+      }),
+    [history],
+  );
+
+  const navigator = useMemo<Navigator>(
+    () => ({
+      push: (to, historyState) => history.push(to, historyState),
+      replace: (to, historyState) => history.replace(to, historyState),
+      go: (delta) => history.go(delta),
+      canGoBack: () => history.canGoBack,
+      canGoForward: () => history.canGoForward,
+    }),
+    [history],
+  );
+
+  const navigationContext = useMemo(() => ({ navigator }), [navigator]);
+  const locationContext = useMemo(
+    () => ({ location: state.location, navigationType: state.action }),
+    [state],
+  );
+
+  return (
+    <NavigationContext.Provider value={navigationContext}>
+      <LocationContext.Provider value={locationContext}>{children}</LocationContext.Provider>
+    </NavigationContext.Provider>
+  );
+}
+
+export type RouteProps = {
+  /**
+	The path pattern to match, relative to the parent route. Supports `:param`
+	dynamic segments, optional segments (`:param?`, `edit?`), and a trailing
+	`*` splat.
+	*/
+  path?: string;
+
+  /**
+	Render this route in the parent's `<Outlet>` at the parent's exact path.
+	Index routes cannot have children.
+	*/
+  index?: boolean;
+
+  /**
+	The element to render when this route matches.
+	*/
+  element?: ReactNode;
+
+  /**
+	Nested `<Route>` elements, rendered into this route's `<Outlet>`.
+	*/
+  children?: ReactNode;
+};
+
+/**
+Declares a route. Only valid as a child of `<Routes>` or another `<Route>`.
+*/
+export function Route(_props: RouteProps): ReactElement | null {
+  throw new Error(
+    "A <Route> is only ever to be used as the child of a <Routes> element, " +
+      "never rendered directly. Please wrap your <Route> in a <Routes>.",
+  );
+}
+
+function createRoutesFromChildren(children: ReactNode): RouteObject[] {
+  const routes: RouteObject[] = [];
+
+  Children.forEach(children, (element) => {
+    if (!isValidElement(element)) {
+      // Ignore non-elements. This allows people to more easily inline
+      // conditionals in their route config.
+      return;
+    }
+
+    if (element.type === Fragment) {
+      // Transparently support React.Fragment and its children.
+      routes.push(
+        ...createRoutesFromChildren((element.props as { children?: ReactNode }).children),
+      );
+      return;
+    }
+
+    if (element.type !== Route) {
+      throw new Error(
+        `[${typeof element.type === "string" ? element.type : ((element.type as { name?: string }).name ?? "unknown")}] ` +
+          `is not a <Route> component. All component children of <Routes> must be a <Route> or <React.Fragment>.`,
+      );
+    }
+
+    const props = element.props as RouteProps;
+    const route: RouteObject = {
+      path: props.path,
+      index: props.index,
+      element: props.element,
+    };
+
+    if (props.children) {
+      route.children = createRoutesFromChildren(props.children);
+    }
+
+    routes.push(route);
+  });
+
+  return routes;
+}
+
+export type RoutesProps = {
+  children?: ReactNode;
+
+  /**
+	Match against this location instead of the current one. Useful for
+	rendering a screen other than the one navigated to (e.g. transitions).
+	*/
+  location?: Partial<Location> | string;
+};
+
+/**
+Renders the branch of child `<Route>` elements that best matches the current
+location.
+*/
+export function Routes({ children, location }: RoutesProps): ReactElement | null {
+  return useRoutes(createRoutesFromChildren(children), location);
+}
+
+export type OutletProps = {
+  /**
+	A value to make available to descendant routes via `useOutletContext()`.
+	*/
+  context?: unknown;
+};
+
+/**
+Renders the matching child route of a parent route, or nothing if no child
+matches.
+*/
+export function Outlet(props: OutletProps): ReactElement | null {
+  return useOutlet(props.context);
+}
+
+export type NavigateProps = {
+  to: To;
+  replace?: boolean;
+  state?: unknown;
+};
+
+/**
+Navigates as soon as it renders. The component form of `useNavigate`, for
+declarative redirects:
+
+```tsx
+<Route path="/" element={<Navigate to="/home" replace />} />
+```
+*/
+export function Navigate({ to, replace, state }: NavigateProps): null {
+  const navigate = useNavigate();
+  const { pathname, search } = useResolvedPath(to);
+
+  useEffect(() => {
+    navigate({ pathname, search }, { replace, state });
+  }, [navigate, pathname, search, replace, state]);
+
+  return null;
+}
+
+type LinkRenderState = {
+  /**
+	Whether this link currently has focus.
+	*/
+  isFocused: boolean;
+
+  /**
+	Whether the current location is the link's destination or a descendant of
+	it.
+	*/
+  isActive: boolean;
+};
+
+export type LinkProps = Omit<TextProps, "children"> & {
+  /**
+	The destination to navigate to when the link is activated.
+	*/
+  to: To;
+
+  /**
+	Replace the current entry in the navigation stack instead of pushing.
+	*/
+  replace?: boolean;
+
+  /**
+	State to attach to the destination location.
+	*/
+  state?: unknown;
+
+  /**
+	Focus this link if nothing else is focused yet.
+	*/
+  autoFocus?: boolean;
+
+  /**
+	An ID for programmatic focus via `useFocusManager().focus(id)`.
+	*/
+  id?: string;
+
+  /**
+	Link content. Pass a function to take full control of rendering based on
+	focus and active state.
+	*/
+  children?: ReactNode | ((state: LinkRenderState) => ReactNode);
+};
+
+/**
+A focusable navigation element — the terminal's `<a>` tag. Focus it with
+<kbd>Tab</kbd> and activate it with <kbd>Enter</kbd>. By default the focused
+link renders inverse; pass a function as `children` (or any `Text` props) to
+customize.
+
+```tsx
+<Link to="/settings">Settings</Link>
+```
+*/
+export function Link({
+  to,
+  replace = false,
+  state,
+  autoFocus = false,
+  id,
+  children,
+  ...textProps
+}: LinkProps) {
+  const navigate = useNavigate();
+  const path = useResolvedPath(to);
+  const { pathname: locationPathname } = useLocation();
+  const { isFocused } = useFocus({ autoFocus, id });
+
+  const toPathname = normalizePathname(path.pathname);
+  const isActive =
+    locationPathname === toPathname ||
+    (locationPathname.startsWith(toPathname) && locationPathname.charAt(toPathname.length) === "/");
+
+  const activate = useCallback(() => {
+    navigate({ pathname: path.pathname, search: path.search }, { replace, state });
+  }, [navigate, path.pathname, path.search, replace, state]);
+
+  useInput(
+    (_input, key) => {
+      if (key.return) {
+        activate();
+      }
+    },
+    { isActive: isFocused },
+  );
+
+  if (typeof children === "function") {
+    return <>{children({ isFocused, isActive })}</>;
+  }
+
+  return (
+    <Text inverse={isFocused} {...textProps}>
+      {children}
+    </Text>
+  );
+}

package/src/router/context.ts

@@ -0,0 +1,41 @@
+import { createContext, type ReactElement } from "react";
+
+import { type Location, type NavigationType, type Path } from "#/router/history.ts";
+import { type RouteMatch } from "#/router/matcher.ts";
+
+/**
+The imperative interface `useNavigate` drives. Backed by the memory history
+inside `<MemoryRouter>`.
+*/
+export type Navigator = {
+  push: (to: Path, state?: unknown) => void;
+  replace: (to: Path, state?: unknown) => void;
+  go: (delta: number) => void;
+  canGoBack: () => boolean;
+  canGoForward: () => boolean;
+};
+
+export type NavigationContextObject = {
+  navigator: Navigator;
+};
+
+export const NavigationContext = createContext<NavigationContextObject | null>(null);
+
+export type LocationContextObject = {
+  location: Location;
+  navigationType: NavigationType;
+};
+
+export const LocationContext = createContext<LocationContextObject | null>(null);
+
+export type RouteContextObject = {
+  outlet: ReactElement | null;
+  matches: RouteMatch[];
+};
+
+export const RouteContext = createContext<RouteContextObject>({
+  outlet: null,
+  matches: [],
+});
+
+export const OutletContext = createContext<unknown>(null);

package/src/router/history.ts

@@ -0,0 +1,194 @@
+// Ported from react-router's createMemoryHistory (lib/router/history.ts, MIT),
+// without URL semantics: no hash, no href/URL creation, no encoding.
+
+/**
+The type of navigation that produced the current location:
+
+- `"POP"` — moving through existing history entries (`navigate(-1)`, initial load).
+- `"PUSH"` — a new entry was added to the stack.
+- `"REPLACE"` — the current entry was overwritten.
+*/
+export type NavigationType = "POP" | "PUSH" | "REPLACE";
+
+/**
+The two parseable pieces of a route path. Sigil routes have no hash — a
+terminal has no scroll anchors.
+*/
+export type Path = {
+  /**
+	The path of the screen, beginning with `/`.
+	*/
+  pathname: string;
+
+  /**
+	The query string, beginning with `?`, or an empty string.
+	*/
+  search: string;
+};
+
+/**
+An entry in the navigation stack.
+*/
+export type Location<State = unknown> = Path & {
+  /**
+	Arbitrary state attached to this entry via `navigate(to, {state})`. Unlike the
+	browser, this is held in memory and never serialized — any value works.
+	*/
+  state: State;
+
+  /**
+	A unique key for this entry, stable across re-renders. Useful as a React
+	`key` to remount a screen when re-navigating to the same path.
+	*/
+  key: string;
+};
+
+/**
+A destination to navigate to: either a path string (`"/users/123?tab=posts"`)
+or a partial `Path` object.
+*/
+export type To = string | Partial<Path>;
+
+/**
+Splits a path string into its pathname and search parts.
+*/
+export const parsePath = (path: string): Partial<Path> => {
+  const parsedPath: Partial<Path> = {};
+
+  if (path) {
+    const searchIndex = path.indexOf("?");
+    if (searchIndex >= 0) {
+      parsedPath.search = path.slice(searchIndex);
+      path = path.slice(0, searchIndex);
+    }
+
+    if (path) {
+      parsedPath.pathname = path;
+    }
+  }
+
+  return parsedPath;
+};
+
+/**
+Joins a `Path` back into a single string.
+*/
+export const createPath = ({ pathname = "/", search = "" }: Partial<Path>): string =>
+  pathname + (search && search !== "?" ? (search.startsWith("?") ? search : `?${search}`) : "");
+
+type Update = {
+  action: NavigationType;
+  location: Location;
+  delta: number;
+};
+
+type Listener = (update: Update) => void;
+
+/**
+The in-memory navigation stack backing `<MemoryRouter>`.
+*/
+export type MemoryHistory = {
+  readonly index: number;
+  readonly action: NavigationType;
+  readonly location: Location;
+  readonly canGoBack: boolean;
+  readonly canGoForward: boolean;
+  push: (to: To, state?: unknown) => void;
+  replace: (to: To, state?: unknown) => void;
+  go: (delta: number) => void;
+  listen: (listener: Listener) => () => void;
+};
+
+/**
+An entry to seed the navigation stack with: a path string or a partial
+`Location` (which may carry `state`).
+*/
+export type InitialEntry = string | Partial<Location>;
+
+type MemoryHistoryOptions = {
+  initialEntries?: InitialEntry[];
+  initialIndex?: number;
+};
+
+export const createMemoryHistory = ({
+  initialEntries = ["/"],
+  initialIndex,
+}: MemoryHistoryOptions = {}): MemoryHistory => {
+  let keyCounter = 0;
+  const createKey = () => `k${keyCounter++}`;
+
+  const createLocation = (to: To, state: unknown = null): Location => {
+    const path = typeof to === "string" ? parsePath(to) : to;
+    const location: Location = {
+      pathname: path.pathname ?? "/",
+      search: path.search ?? "",
+      state,
+      key: createKey(),
+    };
+    if (!location.pathname.startsWith("/")) {
+      throw new Error(
+        `Route pathnames must be absolute, but "${location.pathname}" was used to initialize the navigation stack.`,
+      );
+    }
+
+    return location;
+  };
+
+  const entries: Location[] = initialEntries.map((entry) =>
+    createLocation(entry, typeof entry === "string" ? null : (entry.state ?? null)),
+  );
+  let index = Math.min(Math.max(initialIndex ?? entries.length - 1, 0), entries.length - 1);
+  let action: NavigationType = "POP";
+  let listener: Listener | null = null;
+
+  const history: MemoryHistory = {
+    get index() {
+      return index;
+    },
+    get action() {
+      return action;
+    },
+    get location() {
+      return entries[index]!;
+    },
+    get canGoBack() {
+      return index > 0;
+    },
+    get canGoForward() {
+      return index < entries.length - 1;
+    },
+    push(to, state) {
+      action = "PUSH";
+      const nextLocation = createLocation(to, state);
+      index += 1;
+      // Pushing truncates any forward entries, exactly like browser history.
+      entries.splice(index, entries.length, nextLocation);
+      listener?.({ action, location: nextLocation, delta: 1 });
+    },
+    replace(to, state) {
+      action = "REPLACE";
+      const nextLocation = createLocation(to, state);
+      entries[index] = nextLocation;
+      listener?.({ action, location: nextLocation, delta: 0 });
+    },
+    go(delta) {
+      action = "POP";
+      const nextIndex = Math.min(Math.max(index + delta, 0), entries.length - 1);
+      const actualDelta = nextIndex - index;
+      index = nextIndex;
+      listener?.({ action, location: entries[index]!, delta: actualDelta });
+    },
+    listen(newListener) {
+      if (listener) {
+        throw new Error("A memory history only supports one listener at a time.");
+      }
+
+      listener = newListener;
+      return () => {
+        listener = null;
+      };
+    },
+  };
+
+  return history;
+};