one 1.1.5 → 1.1.270

package/src/index.ts

@@ -0,0 +1,69 @@
+export type { OneRouter, One } from './interfaces/router'
+import type { OneRouter } from './interfaces/router'
+
+export type Href = OneRouter.Href
+export type LinkProps<T extends string | object = string> = OneRouter.LinkProps<T>
+
+export type { Endpoint, LoaderProps } from './types'
+
+export * from '@vxrn/universal-color-scheme'
+
+export { Root } from './Root'
+export { render } from './render'
+
+export { Stack } from './layouts/Stack'
+export { Tabs } from './layouts/Tabs'
+
+// TODO breaking due to react-native-gesture-handler
+// export { Drawer } from './layouts/Drawer'
+
+export { SafeAreaView } from 'react-native-safe-area-context'
+export { Navigator, Slot } from './views/Navigator'
+export { ErrorBoundary } from './views/ErrorBoundary'
+// export { Unmatched } from './fallbackViews/Unmatched'
+export { ScrollRestoration } from './views/ScrollRestoration'
+export { LoadProgressBar } from './views/LoadProgressBar'
+
+export { createApp } from './createApp'
+export { createRoute, route } from './createRoute'
+export { onClientLoaderResolve } from './clientLoaderResolver'
+
+export { isResponse } from './utils/isResponse'
+export { getURL } from './getURL'
+export { redirect } from './utils/redirect'
+
+export { useLinkTo } from './link/useLinkTo'
+
+export {
+  useRouter,
+  useUnstableGlobalHref,
+  usePathname,
+  useNavigationContainerRef,
+  useParams,
+  useActiveParams,
+  useSegments,
+  useRootNavigationState,
+} from './hooks'
+
+// for easier expo-router migration
+export {
+  useLocalSearchParams,
+  useGlobalSearchParams,
+} from './hooks'
+
+export * as routerStore from './router/router'
+
+export { router } from './imperative-api'
+
+export { Link } from './link/Link'
+export { Redirect } from './link/Redirect'
+
+export { Head } from './head'
+
+export { withLayoutContext } from './layouts/withLayoutContext'
+
+// React Navigation
+export { useFocusEffect } from './useFocusEffect'
+export { useNavigation } from './useNavigation'
+
+export { useLoader } from './useLoader'

package/src/interfaces/router.ts

@@ -0,0 +1,415 @@
+import type {
+  NavigationContainerRefWithCurrent,
+  NavigationState,
+  PartialState,
+} from '@react-navigation/core'
+import type { ReactNode } from 'react'
+import type { TextProps, GestureResponderEvent } from 'react-native'
+
+export namespace OneRouter {
+  export interface __routes<T extends string = string> extends Record<string, unknown> {}
+
+  // making a simple helper that gives you everything for a route
+  export type Route<Path> = {
+    Params: InputRouteParams<Path>
+    Props: { params: InputRouteParams<Path> }
+    Loader: (props: { params: InputRouteParams<Path> }) => any
+  }
+
+  type StaticRoutes = __routes extends { StaticRoutes: string } ? __routes['StaticRoutes'] : string
+
+  type DynamicRoutes<T extends string> = __routes<T> extends { DynamicRoutes: any }
+    ? T extends __routes<infer _>['DynamicRoutes']
+      ? T
+      : never
+    : string
+
+  export type DynamicRouteTemplate = __routes extends { DynamicRouteTemplate: string }
+    ? __routes['DynamicRouteTemplate']
+    : string
+
+  export type NavigationRef = NavigationContainerRefWithCurrent<ReactNavigation.RootParamList>
+
+  export type RelativePathString = `./${string}` | `../${string}` | '..'
+  export type AbsoluteRoute = DynamicRouteTemplate | StaticRoutes
+  export type ExternalPathString = `${string}:${string}`
+  export type OneRouterRoutes = DynamicRouteTemplate | StaticRoutes | RelativePathString
+  export type AllRoutes = OneRouterRoutes | ExternalPathString
+
+  export type LinkToOptions = {
+    scroll?: boolean
+  }
+
+  type SearchOrHash = `?${string}` | `#${string}`
+
+  export type UnknownInputParams = Record<
+    string,
+    string | number | undefined | null | (string | number)[]
+  >
+
+  type UnknownOutputParams = Record<string, string | string[]>
+
+  /**
+   * Return only the RoutePart of a string. If the string has multiple parts return never
+   *
+   * string   | type
+   * ---------|------
+   * 123      | 123
+   * /123/abc | never
+   * 123?abc  | never
+   * ./123    | never
+   * /123     | never
+   * 123/../  | never
+   */
+  export type SingleRoutePart<S extends string> = S extends `${string}/${string}`
+    ? never
+    : S extends `${string}${SearchOrHash}`
+      ? never
+      : S extends ''
+        ? never
+        : S extends `(${string})`
+          ? never
+          : S extends `[${string}]`
+            ? never
+            : S
+
+  /**
+   * Return only the CatchAll router part. If the string has search parameters or a hash return never
+   */
+  export type CatchAllRoutePart<S extends string> = S extends `${string}${SearchOrHash}`
+    ? never
+    : S extends ''
+      ? never
+      : S extends `${string}(${string})${string}`
+        ? never
+        : S extends `${string}[${string}]${string}`
+          ? never
+          : S
+
+  /**
+   * Return the name of a route parameter
+   * '[test]'    -> 'test'
+   * 'test'      -> never
+   * '[...test]' -> '...test'
+   */
+  type IsParameter<Part> = Part extends `[${infer ParamName}]` ? ParamName : never
+
+  /**
+   * Return a union of all raw parameter names. If there are no names return never
+   *
+   * This differs from ParameterNames as it returns the `...` for catch all parameters
+   *
+   * /[test]         -> 'test'
+   * /[abc]/[...def] -> 'abc'|'...def'
+   */
+  type ParameterNames<Path> = Path extends `${infer PartA}/${infer PartB}`
+    ? IsParameter<PartA> | ParameterNames<PartB>
+    : IsParameter<Path>
+
+  /**
+   * Returns all segments of a route.
+   *
+   * /(group)/123/abc/[id]/[...rest] -> ['(group)', '123', 'abc', '[id]', '[...rest]'
+   */
+  type RouteSegments<Path> = Path extends `${infer PartA}/${infer PartB}`
+    ? PartA extends '' | '.'
+      ? [...RouteSegments<PartB>]
+      : [PartA, ...RouteSegments<PartB>]
+    : Path extends ''
+      ? []
+      : [Path]
+
+  type AllUngroupedRoutes<Path> = Path extends `(${infer PartA})/${infer PartB}`
+    ? `(${PartA})/${AllUngroupedRoutes<PartB>}` | AllUngroupedRoutes<PartB>
+    : Path
+
+  /**
+   * Returns a Record of the routes parameters as strings and CatchAll parameters
+   *
+   * There are two versions, input and output, as you can input 'string | number' but
+   *  the output will always be 'string'
+   *
+   * /[id]/[...rest] -> { id: string, rest: string[] }
+   * /no-params      -> {}
+   */
+  export type InputRouteParams<Path> = {
+    [Key in ParameterNames<Path> as Key extends `...${infer Name}`
+      ? Name
+      : Key]: Key extends `...${string}` ? string[] : string
+  }
+  // TODO @nate: i commented this out to get better types but we probably need to fix better
+  // & UnknownInputParams
+
+  type OutputRouteParams<Path> = {
+    [Key in ParameterNames<Path> as Key extends `...${infer Name}`
+      ? Name
+      : Key]: Key extends `...${string}` ? string[] : string
+  } & UnknownOutputParams
+
+  /**
+   * Returns the search parameters for a route.
+   */
+  export type SearchParams<T extends AllRoutes = never> = T extends DynamicRouteTemplate
+    ? OutputRouteParams<T>
+    : T extends StaticRoutes
+      ? never
+      : UnknownOutputParams
+
+  /*********
+   * Href  *
+   *********/
+
+  export type DynamicRoutesHref = DynamicRouteString<{ __branded__: any }, DynamicRouteTemplate>
+  export type DynamicRoutesHref2 = DynamicRouteString<string, DynamicRouteTemplate>
+
+  /**
+   * The main routing type for One. Includes all available routes with strongly typed parameters.
+   */
+  export type Href<T extends string | object = { __branded__: any }> =
+    | StringRouteToType<AllUngroupedRoutes<StaticRoutes> | RelativePathString | ExternalPathString>
+    | DynamicRouteString<T, DynamicRouteTemplate>
+    | DynamicRouteObject<
+        StaticRoutes | RelativePathString | ExternalPathString | DynamicRouteTemplate
+      >
+
+  type StringRouteToType<T extends string> =
+    | T
+    | `${T}${SearchOrHash}`
+    | { pathname: T; params?: UnknownInputParams | never }
+
+  /**
+   * Converts a dynamic route template to a Href string type
+   */
+  type DynamicRouteString<
+    T extends string | object,
+    P = DynamicRouteTemplate,
+  > = '__branded__' extends keyof T
+    ? DynamicTemplateToHrefString<P>
+    : T extends string
+      ? DynamicRoutes<T>
+      : never
+
+  type DynamicTemplateToHrefString<Path> = Path extends `${infer PartA}/${infer PartB}`
+    ? // If the current segment (PartA) is dynamic, allow any string. This loop again with the next segment (PartB)
+      `${PartA extends `[${string}]` ? string : PartA}/${DynamicTemplateToHrefString<PartB>}`
+    : // Path is the last segment.
+      Path extends `[${string}]`
+      ? string
+      : Path
+
+  type DynamicRouteObject<T> = T extends DynamicRouteTemplate
+    ? {
+        pathname: T
+        params: InputRouteParams<T>
+      }
+    : never
+
+  export type LoadingState = 'loading' | 'loaded'
+
+  export type ResultState = PartialState<NavigationState> & {
+    state?: ResultState
+    linkOptions?: OneRouter.LinkToOptions
+  }
+
+  export type RootStateListener = (state: ResultState) => void
+  export type LoadingStateListener = (state: LoadingState) => void
+
+  /***********************
+   * One Exports *
+   ***********************/
+
+  export type Router = {
+    /** Go back in the history. */
+    back: () => void
+    /** If there's history that supports invoking the `back` function. */
+    canGoBack: () => boolean
+    /** Navigate to the provided href using a push operation if possible. */
+    push: (href: Href, options?: LinkToOptions) => void
+    /** Navigate to the provided href. */
+    navigate: (href: Href, options?: LinkToOptions) => void
+    /** Navigate to route without appending to the history. */
+    replace: (href: Href, options?: LinkToOptions) => void
+    /** Navigate to the provided href using a push operation if possible. */
+    dismiss: (count?: number) => void
+    /** Navigate to first screen within the lowest stack. */
+    dismissAll: () => void
+    /** If there's history that supports invoking the `dismiss` and `dismissAll` function. */
+    canDismiss: () => boolean
+    /** Update the current route query params. */
+    setParams: <T = ''>(
+      params?: T extends '' ? Record<string, string | undefined | null> : InputRouteParams<T>
+    ) => void
+    /** Subscribe to state updates from the router */
+    subscribe: (listener: RootStateListener) => () => void
+    /** Subscribe to loading state updates */
+    onLoadState: (listener: LoadingStateListener) => () => void
+  }
+
+  /** The imperative router. */
+  export declare const router: Router
+
+  /************
+   * <Link /> *
+   ************/
+  export interface WebAnchorProps {
+    /**
+     * **Web only:** Specifies where to open the `href`.
+     *
+     * - **_self**: the current tab.
+     * - **_blank**: opens in a new tab or window.
+     * - **_parent**: opens in the parent browsing context. If no parent, defaults to **_self**.
+     * - **_top**: opens in the highest browsing context ancestor. If no ancestors, defaults to **_self**.
+     *
+     * This property is passed to the underlying anchor (`<a>`) tag.
+     *
+     * @default '_self'
+     *
+     * @example
+     * <Link href="https://expo.dev" target="_blank">Go to Expo in new tab</Link>
+     */
+    target?: '_self' | '_blank' | '_parent' | '_top' | (string & object)
+
+    /**
+     * **Web only:** Specifies the relationship between the `href` and the current route.
+     *
+     * Common values:
+     * - **nofollow**: Indicates to search engines that they should not follow the `href`. This is often used for user-generated content or links that should not influence search engine rankings.
+     * - **noopener**: Suggests that the `href` should not have access to the opening window's `window.opener` object, which is a security measure to prevent potentially harmful behavior in cases of links that open new tabs or windows.
+     * - **noreferrer**: Requests that the browser not send the `Referer` HTTP header when navigating to the `href`. This can enhance user privacy.
+     *
+     * The `rel` property is primarily used for informational and instructive purposes, helping browsers and web
+     * crawlers make better decisions about how to handle and interpret the links on a web page. It is important
+     * to use appropriate `rel` values to ensure that links behave as intended and adhere to best practices for web
+     * development and SEO (Search Engine Optimization).
+     *
+     * This property is passed to the underlying anchor (`<a>`) tag.
+     *
+     * @example
+     * <Link href="https://expo.dev" rel="nofollow">Go to Expo</Link>
+     */
+    rel?: string
+
+    /**
+     * **Web only:** Specifies that the `href` should be downloaded when the user clicks on the link,
+     * instead of navigating to it. It is typically used for links that point to files that the user should download,
+     * such as PDFs, images, documents, etc.
+     *
+     * The value of the `download` property, which represents the filename for the downloaded file.
+     * This property is passed to the underlying anchor (`<a>`) tag.
+     *
+     * @example
+     * <Link href="/image.jpg" download="my-image.jpg">Download image</Link>
+     */
+    download?: string
+  }
+
+  export interface LinkProps<T extends string | object>
+    extends Omit<TextProps, 'href'>,
+      WebAnchorProps {
+    /** Path to route to. */
+    href: Href<T>
+
+    // TODO: This may need to be extracted for React Native style support.
+    /** Forward props to child component. Useful for custom buttons. */
+    asChild?: boolean
+
+    /** Should replace the current route without adding to the history. */
+    replace?: boolean
+    /** Should push the current route  */
+    push?: boolean
+
+    /** On web, this sets the HTML `class` directly. On native, this can be used with CSS interop tools like Nativewind. */
+    className?: string
+
+    onPress?: (e: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent) => void
+  }
+
+  export interface LinkComponent {
+    <T extends string | object>(props: React.PropsWithChildren<LinkProps<T>>): JSX.Element
+    /** Helper method to resolve an Href object into a string. */
+    resolveHref: (href: Href) => string
+  }
+
+  /**
+   * Component to render link to another route using a path.
+   * Uses an anchor tag on the web.
+   *
+   * @param props.href Absolute path to route (e.g. \`/feeds/hot\`).
+   * @param props.replace Should replace the current route without adding to the history.
+   * @param props.asChild Forward props to child component. Useful for custom buttons.
+   * @param props.children Child elements to render the content.
+   * @param props.className On web, this sets the HTML \`class\` directly. On native, this can be used with CSS interop tools like Nativewind.
+   */
+  export declare const Link: LinkComponent
+
+  /** Redirects to the href as soon as the component is mounted. */
+  export declare const Redirect: (props: React.PropsWithChildren<{ href: Href }>) => ReactNode
+  export type Redirect = typeof Redirect
+
+  /**
+   * Hooks
+   */
+
+  export declare function useRouter(): Router
+  type useRouter = typeof useRouter
+
+  /**
+   * Returns the URL search parameters for the contextually focused route. e.g. \`/acme?foo=bar\` -> \`{ foo: "bar" }\`.
+   * This is useful for stacks where you may push a new screen that changes the query parameters.
+   *
+   * To observe updates even when the invoking route is not focused, use \`useActiveParams()\`.
+   * @see \`useActiveParams\`
+   */
+  export declare function useParams<
+    TParams extends AllRoutes | UnknownOutputParams = UnknownOutputParams,
+  >(): TParams extends AllRoutes ? SearchParams<TParams> : TParams
+  type useParams = typeof useParams
+
+  export declare function useSearchParams<
+    TParams extends AllRoutes | UnknownOutputParams = UnknownOutputParams,
+  >(): TParams extends AllRoutes ? SearchParams<TParams> : TParams
+  type useSearchParams = typeof useSearchParams
+
+  /**
+   * Get the globally selected query parameters, including dynamic path segments. This function will update even when the route is not focused.
+   * Useful for analytics or other background operations that don't draw to the screen.
+   *
+   * When querying search params in a stack, opt-towards using \`useParams\` as these will only
+   * update when the route is focused.
+   *
+   * @see \`useParams\`
+   */
+  export declare function useActiveParams<
+    T extends AllRoutes | UnknownOutputParams = UnknownOutputParams,
+  >(): T extends AllRoutes ? SearchParams<T> : T
+  type useActiveParams = typeof useActiveParams
+
+  /**
+   * Get a list of selected file segments for the currently selected route. Segments are not normalized, so they will be the same as the file path. e.g. /[id]?id=normal -> ["[id]"]
+   *
+   * \`useSegments\` can be typed using an abstract.
+   * Consider the following file structure, and strictly typed \`useSegments\` function:
+   *
+   * \`\`\`md
+   * - app
+   *   - [user]
+   *     - index.js
+   *     - followers.js
+   *   - settings.js
+   * \`\`\`
+   * This can be strictly typed using the following abstract:
+   *
+   * \`\`\`ts
+   * const [first, second] = useSegments<['settings'] | ['[user]'] | ['[user]', 'followers']>()
+   * \`\`\`
+   */
+  export declare function useSegments<
+    T extends AbsoluteRoute | RouteSegments<AbsoluteRoute> | RelativePathString,
+  >(): T extends AbsoluteRoute ? RouteSegments<T> : T extends string ? string[] : T
+  type useSegments = typeof useSegments
+}
+
+// TEMP
+export namespace One {
+  export type Route<Path> = OneRouter.Route<Path>
+}

package/src/layouts/Drawer.tsx

@@ -0,0 +1,19 @@
+import {
+  type DrawerNavigationEventMap,
+  type DrawerNavigationOptions,
+  createDrawerNavigator,
+} from '@react-navigation/drawer'
+import type { DrawerNavigationState, ParamListBase } from '@react-navigation/native'
+
+import { withLayoutContext } from './withLayoutContext'
+
+const DrawerNavigator = createDrawerNavigator().Navigator
+
+export const Drawer = withLayoutContext<
+  DrawerNavigationOptions,
+  typeof DrawerNavigator,
+  DrawerNavigationState<ParamListBase>,
+  DrawerNavigationEventMap
+>(DrawerNavigator)
+
+export default Drawer

package/src/layouts/Stack.tsx

@@ -0,0 +1,19 @@
+import type { ParamListBase, StackNavigationState } from '@react-navigation/native'
+import {
+  type NativeStackNavigationEventMap,
+  type NativeStackNavigationOptions,
+  createNativeStackNavigator,
+} from '@react-navigation/native-stack'
+
+import { withLayoutContext } from './withLayoutContext'
+
+const NativeStackNavigator = createNativeStackNavigator().Navigator
+
+export const Stack = withLayoutContext<
+  NativeStackNavigationOptions,
+  typeof NativeStackNavigator,
+  StackNavigationState<ParamListBase>,
+  NativeStackNavigationEventMap
+>(NativeStackNavigator)
+
+export default Stack

package/src/layouts/Tabs.tsx

@@ -0,0 +1,57 @@
+import {
+  createBottomTabNavigator,
+  type BottomTabNavigationEventMap,
+  type BottomTabNavigationOptions,
+} from '@react-navigation/bottom-tabs'
+import type { ParamListBase, TabNavigationState } from '@react-navigation/native'
+import { Platform, Pressable } from 'react-native'
+
+import type { OneRouter } from '../interfaces/router'
+import { Link } from '../link/Link'
+import { withLayoutContext } from './withLayoutContext'
+
+// This is the only way to access the navigator.
+const BottomTabNavigator = createBottomTabNavigator().Navigator
+
+export const Tabs = withLayoutContext<
+  BottomTabNavigationOptions & { href?: OneRouter.Href | null },
+  typeof BottomTabNavigator,
+  TabNavigationState<ParamListBase>,
+  BottomTabNavigationEventMap
+>(BottomTabNavigator, (screens) => {
+  // Support the `href` shortcut prop.
+  return screens.map((screen) => {
+    if (typeof screen.options !== 'function' && screen.options?.href !== undefined) {
+      const { href, ...options } = screen.options
+      if (options.tabBarButton) {
+        throw new Error('Cannot use `href` and `tabBarButton` together.')
+      }
+      return {
+        ...screen,
+        options: {
+          ...options,
+          tabBarButton: (props) => {
+            if (href == null) {
+              return null
+            }
+            const children =
+              Platform.OS === 'web' ? props.children : <Pressable>{props.children}</Pressable>
+            return (
+              <Link
+                {...props}
+                style={[{ display: 'flex' }, props.style]}
+                href={href}
+                asChild={Platform.OS !== 'web'}
+                // biome-ignore lint/correctness/noChildrenProp: <explanation>
+                children={children}
+              />
+            )
+          },
+        },
+      }
+    }
+    return screen
+  })
+})
+
+export default Tabs

package/src/layouts/withLayoutContext.tsx

@@ -0,0 +1,110 @@
+import type { EventMapBase, NavigationState } from '@react-navigation/native'
+import React from 'react'
+
+import { useContextKey } from '../Route'
+import type { PickPartial } from '../types'
+import { useSortedScreens, type ScreenProps } from '../useScreens'
+import { Screen } from '../views/Screen'
+
+export function useFilterScreenChildren(
+  children: React.ReactNode,
+  {
+    isCustomNavigator,
+    contextKey,
+  }: {
+    isCustomNavigator?: boolean
+    /** Used for sending developer hints */
+    contextKey?: string
+  } = {}
+) {
+  return React.useMemo(() => {
+    const customChildren: any[] = []
+    const screens = React.Children.map(children, (child) => {
+      if (React.isValidElement(child) && child && child.type === Screen) {
+        if (!child.props.name) {
+          throw new Error(
+            `<Screen /> component in \`default export\` at \`app${contextKey}/_layout\` must have a \`name\` prop when used as a child of a Layout Route.`
+          )
+        }
+        if (process.env.NODE_ENV !== 'production') {
+          if (['children', 'component', 'getComponent'].some((key) => key in child.props)) {
+            throw new Error(
+              `<Screen /> component in \`default export\` at \`app${contextKey}/_layout\` must not have a \`children\`, \`component\`, or \`getComponent\` prop when used as a child of a Layout Route`
+            )
+          }
+        }
+        return child.props
+      }
+
+      if (isCustomNavigator) {
+        customChildren.push(child)
+      } else {
+        console.warn(
+          `Layout children must be of type Screen, all other children are ignored. To use custom children, create a custom <Layout />. Update Layout Route at: "app${contextKey}/_layout"`
+        )
+      }
+    })
+
+    // Add an assertion for development
+    if (process.env.NODE_ENV !== 'production') {
+      // Assert if names are not unique
+      const names = screens?.map((screen) => screen.name)
+      if (names && new Set(names).size !== names.length) {
+        throw new Error('Screen names must be unique: ' + names)
+      }
+    }
+
+    return {
+      screens,
+      children: customChildren,
+    }
+  }, [children, contextKey, isCustomNavigator])
+}
+
+/** Return a navigator that automatically injects matched routes and renders nothing when there are no children. Return type with children prop optional */
+export function withLayoutContext<
+  TOptions extends object,
+  T extends React.ComponentType<any>,
+  State extends NavigationState,
+  EventMap extends EventMapBase,
+>(
+  Nav: T,
+  processor?: (
+    options: ScreenProps<TOptions, State, EventMap>[]
+  ) => ScreenProps<TOptions, State, EventMap>[]
+): React.ForwardRefExoticComponent<
+  React.PropsWithoutRef<PickPartial<React.ComponentProps<T>, 'children'>> &
+    React.RefAttributes<unknown>
+> & {
+  Screen: (props: ScreenProps<TOptions, State, EventMap>) => null
+} {
+  const Navigator = React.forwardRef<unknown, React.ComponentProps<T>>(
+    ({ children: userDefinedChildren, ...props }, ref) => {
+      const contextKey = useContextKey()
+
+      const { screens } = useFilterScreenChildren(userDefinedChildren, {
+        contextKey,
+      })
+
+      const processed = processor ? processor(screens ?? []) : screens
+
+      const sorted = useSortedScreens(processed ?? [])
+
+      // Prevent throwing an error when there are no screens.
+      if (!sorted.length) {
+        return null
+      }
+
+      return (
+        // @ts-expect-error
+        // biome-ignore lint/correctness/noChildrenProp: <explanation>
+        <Nav {...props} id={contextKey} ref={ref} children={sorted} />
+      )
+    }
+  )
+
+  // @ts-expect-error
+  Navigator.Screen = Screen
+  // @ts-expect-error
+  return Navigator
+}