eddev 2.3.12 → 2.3.13

package/skills/eddev/docs/routing/api.mdx

@@ -0,0 +1,731 @@
+# Frontend Routing APIs (/docs/routing/api)
+
+**Use eddev routing APIs for links, preloading, and client navigation.**
+
+## `<Link />` [#link-]
+
+The `<Link />` component is a drop-in replacement for `<a />` tags, and is used to enable runtime page transitions via our routing system.
+
+```tsx
+<Link href="/about">About</Link>
+```
+
+The Link component is only a light wrapper around the `a` tag, and provides the following:
+
+* Preloading of page data & components when hovering, via `router.preload(props.href)`
+* When a user clicks, it calls `router.handleClickEvent(e, props.href)` — which kicks off navigation, as long as the user isn't holding Command/Ctrl, ensuring that 'Open in new tab' shortcuts work as expected.
+* Status attributes, `data-active`, `data-child-active` and `data-pending` via `useLinkState(props.href)`, allowing developers to style links based on their active or loading state.
+* In Gutenberg, link clicks are ignored — ensuring that authors don't accidentally navigate to another page while selecting text.
+
+You can prevent navigation by calling `e.preventDefault()` in the `onClick` prop.
+
+It accepts the following props:
+
+```typescript
+type LinkProps<T extends ElementType = "a"> = ComponentPropsWithRef<T> & {
+  /** Override the component/tag that gets rendered @default 'a' */
+  as?: T
+  /** The target URL */
+  href?: string | null
+  /** Target attribute */
+  target?: string | null
+  /** When set to 'true', the link will prefer to navigate back in history if possible — restoring scroll position */
+  preferBack?: boolean | "exact"
+  /** Additional data to attach to the route, which can be read by other components via `useRoute().linkData`, or in router events. */
+  linkData?: Record<string, any>
+}
+```
+
+## `<ScrollRestoration />` [#scrollrestoration-]
+
+Since all navigation is handled by the stack, we need to take care of scrolling to the top of the page when a user clicks a link, and restoring the previous scroll position if the user clicks the browser back button.
+
+The started theme includes `<ScrollRestoration />` in `_app.tsx` with no props, however for sites with more complex animation/rendering/navigation, you can either remove this component entirely, or override the restoration function.
+
+The default restore function looks something like this:
+
+```typescript filename="views/_app.tsx"
+<ScrollRestoration
+  restore={(scroll) => {
+    // The `scroll` object has `left` and `top` values, and `direction` which is either `back` or `forward`.
+    document.scrollingElement?.scrollTo({
+      behavior: "instant",
+      left: scroll.left,
+      top: scroll.top,
+    })
+  }}
+/>
+```
+
+<Callout type="info">
+  For more complex cases, you can build your own using [`useRestorableState()`](#userestorablestate), or by hooking into the `navigate:changed` and `capture-restorable-state` [route events](/routing/events).
+</Callout>
+
+## `<BackButton />` [#backbutton-]
+
+Display a back button that will navigate to the previous page in the router's history.
+
+This will allow you to render a 'back button' on the condition that the back button will not send the user to a different website. You can also specify an optional fallback URL, which will be used when the page is opened as a direct link — again, keeping the user on the site.
+
+When a valid history route is available, the back button will function like `history.go(-1)`. Otherwise, if a `fallbackHref` has been providing, clicking it will send the user to that page.
+
+```tsx
+/** Always displays a back button, but will navigate to /work if the user hasn't navigated here from another page */
+<BackButton
+  fallbackHref="/work"
+  render={(args) => {
+    return <button onClick={args.onClick}>Back</button>
+  }}
+/>
+```
+
+The `BackButton` component has the following props:
+
+* `filter?: (route: RouteState) => boolean`
+
+```tsx
+type BackButtonProps = /**
+   * An optional matching function, which will stop the render button from appearing unless the function returns true.
+   *
+   * The below example will only render a back button if the last route was a project archive.
+   *
+   * eg. `filter={(route) => route.view === 'archive-projects'}`
+   *
+   * @param route The last route in the history stack.
+   */
+  filter?: (route: RouteState) => boolean
+  /**
+   * Whether to use the top-most "global" route, or the "context" route.
+   *
+   * The "global" route is the top-most route, reflected in the URL bar.
+   *
+   * The "context" route will be the route that is currently being rendered, which may be different to the global route when using modals/overlays/route stacks/transitions.
+   *
+   * @default "context"
+   */
+  mode?: "global" | "context"
+  /**
+   * An optional href, which will be used if no back route is found.
+   *
+   * When used, the back button will always render.
+   */
+  fallbackHref?: string
+  /**
+   * A function to render the back button, if one should be rendered.
+   *
+   * Receives a `route` prop to further inspect the route, and an `onClick` function to navigate back.
+   *
+   * @param props
+   * @returns
+   */
+  render: (props: { route: RouteState; onClick: (e?: any) => void }) => ReactNode
+```
+
+## `useRoute()` [#useroute]
+
+This hook provides access to information about the current route. It returns an object with the following properties:
+
+```typescript
+export type RouteState = {
+  /** A unique ID, representing this history item. */
+  id: string
+  /** A unique hash for this URI — useful for page transitions. */
+  key: string
+  /** The current path of the route eg. `"/about"` */
+  pathname: string
+  /** The un-parsed querystring, eg. `"?foo=bar"` */
+  search: string
+  /** The parsed querystring, parsed using the `qs` library, which supports arrays. */
+  query: Record<string, string | string[]>
+  /** The hash of the route, eg. `"#section"` */
+  hash: string
+  /** The normalised URI, composed from pathname, query and hash */
+  uri: string
+  /* An object that can hold transient state, like scroll position.
+   * When a user navigates back to a page, this state is included along with router events.
+   * By default, contains `scrollLeft` and `scrollTop`
+   * See `useRestorableState` for more info. */
+  returnState?: RouteReturnState
+  /** The name of the template, like `front-page` or `single-event` */
+  view: string
+  /** The view component for the current route. */
+  component: FunctionComponent
+  /** The props for this route, to be passed to the component. */
+  props: Props
+  /** Loaded metadata for this route */
+  meta: RouteMeta
+  /** Link data, provided using `<Link linkData={...} />`. Will be `undefined` if none was provided. */
+  linkData?: Record<string, any>
+}
+
+/** Data used for generation of <head /> tags */
+type RouteMeta = {
+  title?: string
+  tags?: {
+    tagName: string,
+    attributes: Record<string, string>
+    inner?: string
+  }[]
+}
+
+```
+
+Note that the `view` and `props` properties are fully typed, so you can extract props directly from a route by first checking it's view property.
+
+```tsx
+const route = useRoute()
+let theme = 'default'
+if (route.view === "single-project") {
+  theme = route.props.project.theme
+}
+```
+
+### `useViewRoute(name)` [#useviewroutename]
+
+Similar to `useRoute()`, there's also `useViewRoute(viewName)`. It returns the same `RouteState` object as `useRoute()`, but it'll only return the route data if the view matches. The return value will be fully typed, so you can access it's props just like you would in the template.
+
+```tsx
+const projectRoute = useViewRoute('single-project')
+if (projectRoute) {
+  return <div>You're viewing the {project.props.project.title} project</div>
+} else {
+  return <div>You're not viewing a project.</div>
+}
+```
+
+## `useRouter()` [#userouter]
+
+This hook provides access to the routing API, so that you can directly control navigation.
+
+```typescript
+type RouterAPI = {
+  /** Preload a page and it's components */
+  preload: (url: string) => Promise<void>
+
+  /** Prefetch the data for a page, but not it's components. */
+  prefetch: (url: string) => Promise<void>
+
+  /** Begin transitioning to a new page */
+  navigate: (url: string, args?: { linkData?: Record<string, any> }) => Promise<void>
+
+  /** Replace the browser search params value with the given data, without transitioning the route */
+  replaceQuery: (search: Record<string, string | string[]>) => void
+
+  /** Replace the hash */
+  replaceHash: (hash: string) => void
+
+  /**
+   * Handle a click event, potentially triggering a route change.
+   *
+   * @param e A pointer or mouse event.
+   * @param href An optional URL. This must be provided if no `href` property exists on the clicked element
+   * @param preferBack If set, clicking this link will send the user 'back', when clicking a link to the previous history item.
+   */
+  handleClickEvent(
+    e: PointerOrMouseEvent,
+    href?: string,
+    preferBack?: boolean | "exact",
+    element?: HTMLElement,
+    linkData?: Record<string, any>,
+  ): void
+
+  /** A reference to the route loader (mostly for internal use) */
+  loader: RouteLoader
+
+  /** Subscribe to router events */
+  subscribe: (subscribe: RouterSubscriber) => () => void
+
+  /** Returns the current RouterAPIState, which contains the active route, history items, and pending navigation */
+  getState: () => RouterAPIState | null
+
+  /** Go back to a previous route in the history stack, or push it onto the stack if it isn't currently on the stack. */
+  restoreRoute: (route: RouteState) => void
+}
+```
+
+So, to manually trigger a route change, you can use something like:
+
+```tsx
+const router = useRouter()
+<button onClick={() => router.navigate("/")}>Go Home</button>
+```
+
+## `useHydrating()` [#usehydrating]
+
+*Formally called `useIsSSR()`*
+
+Use this function to help with SSR edge-cases, especially when relying on querystrings, hash fragments, user preferences, screen-size, random values or the current date/time — values which either aren't available on the server, or will differ on the server.
+
+On the server, this hook will always return `true`.
+
+In the browser, this hook will return `true` for the first render while the page is hydrating, and then switch to `false`.
+
+```tsx
+const isHydrating = useIsHydrating()
+const hash = useRoute().hash
+
+if (isHydrating) {
+  return <Spinner />
+} else {
+  return <p>Hash is {hash}, and the time is {new Date().toString()}.</p>
+}
+```
+
+In the example above, the spinner will be rendered on the server, and for the first frame on the client, until the hash is available.
+
+## `useRestorableState()` [#userestorablestate]
+
+This hook works kinda like `useState`, and is used to store transient state that should be restored when a user navigates back to a page.
+
+This is great if you have tabs or accordions which affect the scroll height of the page, which can be jarring when going forward and then back again.
+
+The routing system uses this system internally for scroll restoration.
+
+You'll need to pass in an `id`, which acts as a key for the state, as well as a default value. The `id` should be unique for the current page, but can be reused across different pages.
+
+```tsx
+/**
+ * The value will default to 0, but if the user changes the slider value,
+ * navigates away, and then comes back, the slider will be at the same value.
+ * 
+ * If the user refreshes the page, the slider will reset back to 0.
+ */
+const [sliderValue, setSliderValue] = useRestorableState('sliderValue', 0)
+
+return <div>
+  <input type="range" value={sliderValue} onChange={e => setSliderValue(e.valueAsNumber)} />
+  <Link href="/another-page">Another page</Link>
+</div>
+```
+
+## `useSearchParams()` [#usesearchparams]
+
+This hook provides a nicer API for working with querystring parameters, and should be used when building search and filter interfaces.
+
+```tsx
+const [params, api] = useSearchParams({
+  tags: [] as string[],
+  search: "",
+})
+```
+
+When calling the hook, you pass in an object of default values — which helps provide TypeScript hints, and ensures that required parameters are never `null` or `undefined`.
+
+Simple arrays are supported, where `api.set('tags', ['a', 'b']):{js}` will result in a querystring of `?tags[]=a&tags[]=b`.
+
+Default values are managed individually — if a parameter is not set in the querystring, then it'll be replaced with the default value.
+
+Also, any parameters which are set back to their default value will be removed from the URL, to keep things tidy.
+
+The hook returns a tuple of two objects:
+
+1. The returned `params` object contains the querystring parameters (arrays and strings)
+2. The returned `api` object provides functions for mutating the query state.
+
+The `api` object has the following methods:
+
+````typescript
+export type SearchParamAPI<T> = {
+  /**
+   * Set an individual parameter value by key.
+   * If the value is `null` or `undefined`, the parameter will be
+   * removed/set back to the default.
+   */
+  set<K extends keyof T>(key: K, value: T[K]): void
+  /**
+   * Set all parameters at once, replacing the entire query string.
+   * Any parameters not present will be replaced with their default value.
+   * Passing an empty object is equivalent to calling `reset()`.
+   */
+  setAll: (value: Partial<T>) => void
+  /**
+   * Returns a memoized setter function for a specific key.
+   * This is useful when you want to pass a setter function to a
+   * child component, without needing to pass the entire API object.
+   * 
+   * For example:
+   * ```tsx
+   * <SearchInput value={params.q} onSearch={api.setter("q")} />
+   * ```
+   *
+   * @param key The search parameter name
+   * @returns (value: T) => void
+   */
+  setter<K extends keyof T>(key: K): (value: T[K]) => void
+  /**
+   * Reset all parameters to their default values.
+   */
+  reset(): void
+  /**
+   * Toggles an array item on or off.
+   *
+   * For example, `api.toggle("tags", "news")` will add "news" to the "tags" array if it isn't already present, or remove it if it is.
+   *
+   * Works well with `.has(key, item)`.
+   */
+  toggle<K extends keyof Extract<T, Array<any>>>(
+    key: K,
+    item: Extract<T, Array<any>>[K] extends Array<infer U> ? U : never,
+    state?: boolean,
+  ): void
+  /**
+   * Returns true/false depending on whether the item is present in the array parameter, or the value is equal.
+   *
+   * For example, `api.has("tags", "news")` will return true if "news" is present in the "tags" array.
+   * 
+   * It can also be used as shorthand for api.get(key) === item, for non-array values.
+   *
+   * Works well with `.toggle(key, item)`.
+   */
+  has<K extends keyof T>(key: K, item: Extract<T, Array<any>>[K] extends Array<infer U> ? U : T[K]): boolean
+  /**
+   * Gets the current value of a parameter.
+   * In most cases, you should use the `params` object returned from `useSearchParams` instead of this method.
+   */
+  get<K extends keyof T>(key: K): T[K]
+}
+````
+
+Below is a more complete example, showing arrays and strings
+
+```tsx
+const [params, api] = useSearchParams({
+  type: "all" as "all" | "news" | "events",
+  tags: [] as string[],
+  search: "",
+})
+
+return (
+  <>
+    {/* Search */}
+    <input type="search" defaultValue={params.search} onChange={(e) => api.set("search", e.currentTarget.value)} />
+    {/* Tags, using `has` and `toggle` */}
+    <ul>
+      {allTags.map((tag) => (
+        <label key={tag.value}>
+          <input
+            type="checkbox"
+            checked={api.has("tags", tag.value)}
+            onChange={(e) => api.toggle("tags", tag.value)}
+          />
+          <span>{tag.label}</span>
+        </label>
+      ))}
+    </ul>
+    {/* Type */}
+    <select value={params.type} onChange={(e) => api.set("type", e.currentTarget.value)}>
+      <option value="all">All</option>
+      <option value="news">News</option>
+      <option value="events">Events</option>
+    </select>
+    {/* Reset */}
+    <button onClick={() => api.reset()}>Reset</button>
+  </>
+)
+```
+
+<Callout>
+  Want to do something more advanced? Internally, this hook uses `route.query` and `router.replaceQuery()`
+</Callout>
+
+## `useLinkState()` [#uselinkstate]
+
+This hooks provides insights on whether a link is currently loading, active, or if it's children are active. It takes hashes and querystrings into account too.
+
+It returns an object with the following structure:
+
+```typescript
+type LinkState = {
+  active: 'path' | 'query' | 'exact' | undefined
+  pending: 'path' | 'query' | 'exact' | undefined
+  childActive: boolean
+}
+```
+
+This object is used by the `Link` component, to provide status attributes as `data-active`, `data-child-active` and `data-pending`.
+
+Truthy values mean that at *least* the path is a match, but more specific values can help you figure out if the querystring and hash are also a match.
+
+* `"path"` means that the path is a match, but not the query/hash
+* `"query"` means the path and query matches, but not the hash
+* `"exact"` means the path, query and hash all match exactly
+
+## Advanced [#advanced]
+
+### `useLinkProps()` [#uselinkprops]
+
+This is used internally by the `Link` component, and accepts all the same props. It then returns the React props that you can add onto an `a` element — notably onMouseEnter/onPointerDown for preloading, and onClick for triggering the page navigation.
+
+```tsx
+function FunnyLink(props: { url: string }) {
+  const linkProps = useLinkProps({ href: props.url })
+
+  return <a {...linkProps}>Click here</a>
+}
+```
+
+<Callout>
+  There's almost no reason to use this, since all functionality is exposed via `useRouter()`. The `router.handleClickEvent()` function provides additional checks such link targets, file extensions and keyboard keys being held down.
+</Callout>
+
+### `useRouterState()` [#userouterstate]
+
+While the `useRouter()` hook provides access to the core navigational functionality of the router, and the `useRoute()` hook provides access to information about the *current route*, the `useRouterState()` hook provides access to the state of the router.
+
+The most common use-case for this hook is to access the 'history stack' — that is, the list of routes that can be accessed via the browsers back button. This can be used alongside the `<RouteRenderer />` component to keep past routes mounted, even while inactive.
+
+You can also access the `activeRoute` to access the currently active route, normally accessed via `useRoute()` — however the `activeRoute` can be used to access the top-most active route, if multiple routes are being rendered.
+
+The Router State object looks like this:
+
+```typescript
+export type RouterAPIState = {
+  /** Router chain */
+  history: RouteState[]
+
+  /** The top-most, active route */
+  activeRoute: RouteState
+
+  /** The pending route */
+  pendingRoute?: RouteState
+  pendingRouteReady?: boolean
+
+  /** Transition blockers */
+  blockers: Promise<void>[]
+}
+```
+
+### `<NativeLinkHandler />` [#nativelinkhandler-]
+
+Renders a wrapper element, which handles link clicks from HTML `<a />` inside it. This can be used when rendering HTML from somewhere else, where it's expected that it may cotnain internal links.
+
+```tsx
+<NativeLinkHandler as="div">
+  <div
+    dangerouslySetInnerHTML={{
+      // When the link is clicked, it'll work as though it was a <Link> element.
+      __html: `<a href="/about">About</a>`
+    }}>
+</NativeLinkHandler>
+```
+
+### `<RouteDisplay />` [#routedisplay-]
+
+The `RouteDisplay` component renders a route object. This is used internally by the router by default, with the result passed to your `_app.tsx` view via `props.children` — however it's exposed for additional use-cases, like rendering historic routes in the background with the *real* route overlaid on top.
+
+The following example shows how you could use this to make a simple modal system, by updating your `_app.tsx` to render routes manually. In the example, any link which opens a team profile, or has `linkData={{openAsModal: true}}` will open a modal overlay, but will still render them as normal pages when accessed via a direct link, or upon refresh.
+
+```tsx
+function isModalRoute(route: RouteState) {
+  return route.linkData.openAsModal || route.view === "single-team"
+}
+
+export default defineView('_app', () => {
+  const pageRoutes = useRouterState((r) => {
+    return r.history.length === 1 ? r.history : r.history.filter((route) => !isModalRoute(route))
+  })
+
+  const modalRoute = useRouterState((r) => {
+    if (r.history.length <= 1) return null
+    const top = r.history[r.history.length - 1]
+    return isModalRoute(top) ? top : null
+  })
+
+  return <>
+    <div style={{ pointerEvents: modalRoute ? 'none' : 'auto' }}>
+      <header>
+        <Link href="/about">About</Link>
+        <Link href="/contact" linkData={{openAsModal: true}}>Contact Modal</Link>
+        <Link href="/team/daniel">Dan's Profile</Link>
+      </header>
+      <RouteDisplay route={pageRoutes[pageRoutes.length - 1]} />
+      <Footer />
+    </div>
+    {modalRoute && <div className="fixed inset-0 overflow-auto">
+      <BackButton render={({onClick}) => <button onClick={onClick}>Close</button>} />
+      <RouteDisplay route={modalRoute} />
+    </div>}
+  </>
+})
+```
+
+### `useRouterEvents()` [#userouterevents]
+
+The `useRouterEvents()` hook allows your components to listen to a large number of events, which are emitted by the router as the user interacts with a site.
+
+You can use this to observe clicks, loading, navigation progress, and navigation errors. Some events can also be cancelled, allowing you to stop navigation when needed.
+
+To use it, just pass an event handler:
+
+```typescript
+useRouterEvents((e) => {
+  if (e.type === 'navigate:start') {
+    console.log('10% loaded...')
+  } else if (e.type === 'navigate:data-ready') {
+    console.log('60% loaded...')
+  } else if (e.type === 'navigate:will-change') {
+    console.log('80% loaded...')
+  } else if (e.type === 'navigate:changed') {
+    console.log('100% loaded!')
+  }
+})
+```
+
+## Events [#events]
+
+Below are all events emitted by the router, which can be monitored using [`useRouterEvents()`](#userouterevents).
+
+### `"clicked"` [#clicked]
+
+Triggered when a `Link` is clicked. It is NOT called when calling `router.navigate()`, but is called when calling `router.handleClickEvent()`.
+
+```typescript
+{
+  type: "clicked"
+  link: RouteLink
+  linkData: Record<string, any> | undefined
+  currentRoute: RouteState
+  // The clicked element
+  target?: HTMLElement
+  // ignore: The event was already cancelled, navigate: Navigation will occur, native: Likely a file download or a modifier key was held
+  mode: "ignore" | "navigate" | "native"
+  href: string | undefined
+  isSameUrl: boolean
+  cancel: () => void
+}
+```
+
+### `"capture-restorable-state"` [#capture-restorable-state]
+
+Triggered when leaving a page. The `state` value can be mutated directly to 'shelve' data until an outgoing route, or update the `scrollLeft`/`scrollTop` properties which are automatically captured. It's used by [`useRestorableState()`](#userestorablestate).
+
+```typescript
+{
+  type: "capture-restorable-state"
+  state: RouteReturnState<Record<string, any>>
+}
+```
+
+### `"navigate:start"` [#navigatestart]
+
+Triggered when the navigation process is starting — just before the page starts to load. You can call `.cancel()` to prevent the transition.
+
+```typescript
+{
+  type: "navigate:start"
+  link: RouteLink
+  linkData: LinkClickData | undefined
+  currentRoute: RouteState
+  hasPreloadedData: boolean
+  goingBack?: boolean
+  cancel: () => void
+}
+```
+
+### `"navigate:data-ready"` [#navigatedata-ready]
+
+Triggered once the page data has been loaded, and the route object is ready. At this point, the actual React components needed by the page may not have loaded yet.
+
+```typescript
+{
+  type: "navigate:data-ready"
+  link: RouteLink
+  linkData: LinkClickData | undefined
+  currentRoute: RouteState
+  loadedRoute: RouteState
+}
+```
+
+### `"navigate:will-change"` [#navigatewill-change]
+
+Triggered immediately before swapping to the new route. The React components still may not have loaded, but the Suspense transition is about to start.
+
+```typescript
+{
+  type: "navigate:will-change"
+  link: RouteLink
+  linkData: LinkClickData | undefined
+  currentRoute: RouteState
+  loadedRoute: RouteState
+}
+```
+
+### `"navigate:changed"` [#navigatechanged]
+
+Triggered once the new route has been fully loaded and rendered, and the transition is complete.
+
+```typescript
+{
+  type: "navigate:changed"
+  link: RouteLink
+  linkData: LinkClickData | undefined
+  lastRoute: RouteState
+  currentRoute: RouteState
+}
+```
+
+### `"preload:start"` [#preloadstart]
+
+Triggered when preloading a page (eg. on hover)
+
+```typescript
+{
+  type: "preload:start"
+  link: RouteLink
+  currentRoute: RouteState
+}
+```
+
+### `"preload:data-ready"` [#preloaddata-ready]
+
+Triggered when page data has finished preloading (eg. on hover)
+
+```typescript
+{
+  type: "preload:data-ready"
+  link: RouteLink
+  currentRoute: RouteState
+  data: RouteData
+}
+```
+
+### `"preload:finished"` [#preloadfinished]
+
+Triggered when page data + the required React page template have finished preloading. Block components will not be loaded until this page is actually displayed.
+
+```typescript
+{
+  type: "preload:finished"
+  link: RouteLink
+  currentRoute: RouteState
+  data: RouteData
+}
+```
+
+### `"error"` [#error]
+
+Called when an error occurs during either navigation or preloading.
+
+If `critical` is `true, then the JSON data of the page couldn't be loaded, and the `\_error\` view is about to be rendered.
+
+```typescript
+{
+  type: "error"
+  critical: boolean
+  linkData: LinkClickData | undefined
+  url?: string
+  shouldReload?: boolean
+  error: Error
+}
+```
+
+### `"error:component-load-failed"` [#errorcomponent-load-failed]
+
+Triggered when the view component couldn't be loaded, which usually indicates a caching or network issue.
+
+```typescript
+{
+  type: "error:component-load-failed"
+  error: Error
+}
+```