@depup/sanity 5.17.1-depup.0

package/lib/router.d.ts

@@ -0,0 +1,560 @@
+import { _ as RouterContextValue, a as MatchError, b as SearchParam, c as NavigateBaseOptions, d as NextStateOrOptions, f as Route, g as Router, h as RouteTransform, i as InternalSearchParam, l as NavigateOptions, m as RouteSegment, n as IntentJsonParams, o as MatchOk, p as RouteChildren, r as IntentParameters, s as MatchResult, t as BaseIntentParams, u as NavigateOptionsWithState, v as RouterNode, y as RouterState } from "./_chunks-dts/types3.js";
+import * as react from "react";
+import { ComponentType, FunctionComponent, HTMLProps, MouseEventHandler, ReactNode } from "react";
+import { RouterContext } from "sanity/_singletons";
+/**
+ * Props for the {@link IntentLink} component.
+ *
+ * @public
+ */
+interface IntentLinkProps {
+  /**
+   * The name of the intent.
+   */
+  intent: string;
+  /**
+   * The parameters to include in the intent.
+   * {@link IntentParameters}
+   */
+  params?: IntentParameters;
+  /**
+   * Whether to replace the current URL in the browser history instead of adding a new entry.
+   */
+  replace?: boolean;
+  /**
+   * search params to include in the intent.
+   */
+  searchParams?: SearchParam[];
+}
+/**
+ * @public
+ *
+ * @param props - Props to pass to `IntentLink` component.
+ *  See {@link IntentLinkProps}
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *  return <IntentLink intent="edit" params={{id: 'abc123'}}>Edit</IntentLink>
+ * }
+ * ```
+ */
+declare const IntentLink: react.ForwardRefExoticComponent<Omit<IntentLinkProps & HTMLProps<HTMLAnchorElement>, "ref"> & react.RefAttributes<HTMLAnchorElement>>;
+/**
+ * Props for the {@link Link} component.
+ *
+ * @public
+ */
+interface LinkProps {
+  /**
+   * Whether to replace the current URL in the browser history instead of adding a new entry.
+   */
+  replace?: boolean;
+}
+/**
+ * A component that creates an HTML anchor element.
+ *
+ * @public
+ *
+ * @param props - Props to pass to the `Link` component.
+ *  See {@link LinkProps}
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   return (
+ *    <Link href="https://www.sanity.io" target="_blank" replace>
+ *      Go to Sanity
+ *    </Link>
+ *   )
+ * }
+ * ```
+ */
+declare const Link: react.ForwardRefExoticComponent<Omit<LinkProps & HTMLProps<HTMLAnchorElement>, "ref"> & react.RefAttributes<HTMLAnchorElement>>;
+/**
+ * @public
+ */
+interface RouteNodeOptions {
+  /**
+   * The path of the route node.
+   */
+  path?: string;
+  /**
+   * The children of the route node. See {@link RouteChildren}
+   */
+  children?: RouteChildren;
+  /**
+   * The transforms to apply to the route node. See {@link RouteTransform}
+   */
+  transform?: {
+    [key: string]: RouteTransform<any>;
+  };
+  /**
+   * The scope of the route node.
+   */
+  scope?: string;
+  /**
+   * Optionally disable scoping of search params
+   * Scoped search params will be represented as scope[param]=value in the url
+   * Disabling this will still scope search params based on any parent scope unless the parent scope also has disabled search params scoping
+   * Caution: enabling this can cause conflicts with multiple plugins defining search params with the same name
+   */
+  __unsafe_disableScopedSearchParams?: boolean;
+}
+/**
+ * Interface for the {@link route} object.
+ *
+ * @public
+ */
+interface RouteObject {
+  /**
+   * Creates a new router.
+   * Returns {@link Router}
+   * See {@link RouteNodeOptions} and {@link RouteChildren}
+   */
+  create: (routeOrOpts: RouteNodeOptions | string, childrenOrOpts?: RouteNodeOptions | RouteChildren | null, children?: Router | RouteChildren) => Router;
+  /**
+   * Creates a new router for handling intents.
+   * Returns {@link Router}
+   */
+  intents: (base: string) => Router;
+  /**
+   * Creates a new router scope.
+   * Returns {@link Router}
+   */
+  scope(scopeName: string, routeOrOpts: RouteNodeOptions | string, childrenOrOpts?: RouteNodeOptions | RouteChildren | null, children?: Router | RouteChildren): Router;
+}
+/**
+ * An object containing functions for creating routers and router scopes.
+ * See {@link RouteObject}
+ *
+ * @public
+ *
+ * @example
+ * ```ts
+ * const router = route.create({
+ *   path: "/foo",
+ *   children: [
+ *     route.create({
+ *       path: "/bar",
+ *       children: [
+ *         route.create({
+ *           path: "/:baz",
+ *           transform: {
+ *             baz: {
+ *               toState: (id) => ({ id }),
+ *               toPath: (state) => state.id,
+ *             },
+ *           },
+ *         }),
+ *       ],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare const route: RouteObject;
+/**
+ * @internal
+ * @param options - Route node options
+ */
+declare function _createNode(options: RouteNodeOptions): Router;
+/**
+ * The props for the {@link RouterProvider} component.
+ *
+ * @public
+ */
+interface RouterProviderProps {
+  /**
+   * A function that is called when the user navigates to a new path.
+   * Takes an object containing the path to navigate to and an optional `replace` flag.
+   */
+  onNavigate: (opts: {
+    path: string;
+    replace?: boolean;
+  }) => void;
+  /**
+   * The router object that is used to handle navigation. See {@link Router}
+   */
+  router: Router;
+  /**
+   * The current state of the router. See {@link RouterState}
+   */
+  state: RouterState;
+  /**
+   * The child elements to render.
+   */
+  children: ReactNode;
+}
+/**
+ * @example
+ * ```tsx
+ * import {
+ *   NavigateOptions,
+ *   route,
+ *   RouterProvider,
+ *   RouterState
+ * } from 'sanity'
+ * import {useCallback, useMemo} from 'react'
+ *
+ * function Root() {
+ *   const [router] = useState(() => route.create('/'))
+ *
+ *   const [state, setState] = useState<RouterState>({})
+ *
+ *   const handleNavigate = useCallback((
+ *     path: string,
+ *     options?: NavigateOptions
+ *   ) => {
+ *     console.log('navigate', path, options)
+ *
+ *     setState(router.decode(path))
+ *   }, [router])
+ *
+ *   return (
+ *     <RouterProvider
+ *       onNavigate={handleNavigate}
+ *       router={router}
+ *       state={state}
+ *     >
+ *       <div>This is a routed application</div>
+ *     </RouterProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @param props - The component props.
+ *  {@link RouterProviderProps}
+ *
+ * @public
+ */
+declare function RouterProvider(props: RouterProviderProps): React.JSX.Element;
+/**
+ * Props for the {@link RouteScope} component.
+ *
+ * @public
+ */
+interface RouteScopeProps {
+  /**
+   * The scope for the nested routes.
+   */
+  scope: string;
+  /**
+   * Optionally disable scoping of search params
+   * Scoped search params will be represented as scope[param]=value in the url
+   * Disabling this will still scope search params based on any parent scope unless the parent scope also has disabled search params scoping
+   * Caution: enabling this can cause conflicts with multiple plugins defining search params with the same name
+   */
+  __unsafe_disableScopedSearchParams?: boolean;
+  /**
+   * The content to display inside the route scope.
+   */
+  children: ReactNode;
+}
+declare function RouteScope(props: RouteScopeProps): React.JSX.Element;
+declare namespace RouteScope {
+  var displayName: string;
+}
+/**
+ * Props for the {@link StateLink} component.
+ *
+ * @public
+ */
+interface StateLinkProps {
+  /**
+   * Whether to replace the current history entry instead of adding a new one.
+   */
+  replace?: boolean;
+  /**
+   * The state to associate with the link.
+   */
+  state?: Record<string, unknown>;
+  /**
+   * Whether to navigate to the index page of the app.
+   */
+  toIndex?: boolean;
+}
+/**
+ * A component that creates a link that updates the URL state.
+ *
+ * @remarks
+ * This component uses the {@link useStateLink} hook
+ * to create a link that updates the URL state.
+ *
+ * @param props - Props to pass to the `StateLink` component.
+ *  See {@link StateLinkProps}.
+ *
+ * @public
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *  return <StateLink state={{foo: 'bar'}}>Link</StateLink>
+ * }
+ * ```
+ */
+declare const StateLink: react.ForwardRefExoticComponent<Omit<StateLinkProps & Omit<HTMLProps<HTMLAnchorElement>, "href">, "ref"> & react.RefAttributes<HTMLAnchorElement>>;
+/**
+ * @internal
+ */
+declare const STICKY_PARAMS: string[];
+/**
+ * @public
+ */
+interface UseIntentLinkOptions {
+  /**
+   * The name of the intent to trigger.
+   */
+  intent: string;
+  /**
+   * An optional click event handler.
+   */
+  onClick?: React.MouseEventHandler<HTMLElement>;
+  /**
+   * Optional parameters to pass to the intent. See {@link IntentParameters}
+   */
+  params?: IntentParameters;
+  /**
+   * Whether to replace the current URL in the browser history.
+   */
+  replace?: boolean;
+  /**
+   * The target window or frame to open the link in.
+   */
+  target?: string;
+  searchParams?: SearchParam[];
+}
+/**
+ *
+ * Returns props for an anchor element that will trigger an intent when clicked.
+ *
+ * @example
+ * ```tsx
+ * const {onClick, href} = useIntentLink({
+ *   intent: 'edit',
+ *   params: {id: 'foo'}
+ * })
+ *
+ * <a href={href} onClick={onClick}>Link to "foo" editor</a>
+ * ```
+ *
+ * @public
+ *
+ * @param options - Options to use for the link
+ *  {@link UseIntentLinkOptions}
+ *
+ * @returns - An object with `onClick` and `href` props to use for the link
+ */
+declare function useIntentLink(options: UseIntentLinkOptions): {
+  onClick: React.MouseEventHandler<HTMLElement>;
+  href: string;
+};
+/**
+ * @public
+ */
+interface UseLinkOptions {
+  /**
+   * The URL that the link should navigate to.
+   */
+  href?: string;
+  /**
+   * The event handler function that should be called when the link is clicked.
+   */
+  onClick?: React.MouseEventHandler<HTMLElement>;
+  /**
+   * Whether the link should replace the current URL in the browser history.
+   */
+  replace?: boolean;
+  /**
+   * The target window or frame that the linked document will open in.
+   */
+  target?: string;
+}
+/**
+ * Returns an object with an `onClick` function that can be used as a click handler for a link.
+ *
+ * @public
+ *
+ * @param options - An object containing the properties for the link.
+ *  See {@link UseLinkOptions}
+ *
+ * @returns An object with an `onClick` function.
+ *
+ * @example
+ * ```tsx
+ * const linkProps = useLink({
+ *  href: 'https://www.sanity.io',
+ *  target: '_blank'
+ * })
+ *
+ * <a {...linkProps}>Link</a>
+ * ```
+ */
+declare function useLink(options: UseLinkOptions): {
+  onClick: React.MouseEventHandler<HTMLElement>;
+};
+/**
+ * Returns the router context value.
+ * @public
+ *
+ * @returns The router context value.
+ *  {@link RouterContextValue}
+ * @throws An error if the router context value is missing.
+ *
+ * @example
+ * ```tsx
+ * const router = useRouter()
+ * ```
+ */
+declare function useRouter(): RouterContextValue;
+/**
+ * @public
+ *
+ * @param selector - A selector function that receives the router state and returns a value. See {@link RouterState}
+ *
+ * @returns The value returned by the selector function or RouterState. See {@link RouterState}
+ *
+ * @example
+ * ```tsx
+ * const {activeTool} = useRouterState(state => state.tool)
+ * ```
+ */
+declare function useRouterState<R = RouterState>(selector: (routerState: RouterState) => R): R;
+/**
+ * @public
+ *
+ * @returns The router state. See {@link RouterState}
+ *
+ * @example
+ * ```tsx
+ * const routerState = useRouterState()
+ * ```
+ */
+declare function useRouterState(): RouterState;
+/**
+ * @public
+ */
+interface UseStateLinkOptions {
+  /**
+   * The click event handler for the link.
+   */
+  onClick?: MouseEventHandler<HTMLElement>;
+  /**
+   * Whether to replace the current history entry instead of adding a new one.
+   */
+  replace?: boolean;
+  /**
+   * The state object to update when the link is clicked.
+   */
+  state?: Record<string, unknown>;
+  /**
+   * The target window or frame to open the linked document in.
+   */
+  target?: string;
+  /**
+   * Whether to navigate to the index page of the linked document.
+   */
+  toIndex?: boolean;
+}
+/**
+ * @public
+ *
+ * @param options - Options to use for the link
+ *  {@link UseStateLinkOptions}
+ *
+ * @returns - An object with `onClick` and `href` props to use for the link
+ *
+ * @example
+ * ```tsx
+ * const {onClick, href} = useStateLink({state: {foo: 'bar'}})
+ * ```
+ */
+declare function useStateLink(options: UseStateLinkOptions): {
+  onClick: MouseEventHandler<HTMLElement>;
+  href: string;
+};
+/**
+ * Decode a path segment containing JSON parameters
+ *
+ * @param pathSegment - The path segment to decode
+ * @returns The decoded parameters
+ * @internal
+ * @hidden
+ */
+declare function decodeJsonParams(pathSegment?: string): any;
+/**
+ * Encodes a set of parameters as a path segment, using base64url
+ *
+ * @param params - Paramters to encode
+ * @returns The encoded parameters as a path segment
+ * @internal
+ * @hidden
+ */
+declare function encodeJsonParams(params?: any): string;
+/**
+ * A higher-order component that injects the `router` object from the `useRouter` hook
+ * into the props of the wrapped component.
+ *
+ * @internal
+ * @deprecated - Use the `useRouter` hook instead.
+ *
+ * @param Component - The component to wrap.
+ *
+ * @returns The wrapped component.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent(props) {
+ *  return <div>{props.router.state.myParam}</div>
+ * }
+ *
+ * export default withRouter(MyComponent)
+ * ```
+ */
+declare function withRouter<Props extends {
+  router: RouterContextValue;
+}>(Component: ComponentType<Props>): FunctionComponent<Omit<Props, 'router'>>;
+/**
+ * @internal
+ * @deprecated - Use the `useRouter` hook instead.
+ */
+interface WithRouterProps {
+  /**
+   * The `router` object from the `useRouter` hook.
+   *  {@link RouterContextValue}
+   */
+  router: RouterContextValue;
+  /**
+   * A function that renders the wrapped component with the `router` object as a parameter.
+   */
+  children: (router: RouterContextValue) => React.JSX.Element;
+}
+/**
+ * A higher-order component that injects the router object into its child component.
+ *
+ * @internal
+ * @deprecated - Use the `useRouter` hook instead.
+ *
+ * @returns The rendered component.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent(props: {router: Router}) {
+ *   const {location} = props.router
+ *   const {pathname} = location
+ *   return <p>The current path is: {pathname}</p>
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Router>
+ *       <WithRouter>
+ *         {router => <MyComponent router={router} />}
+ *       </WithRouter>
+ *     </Router>
+ *   )
+ * }
+ * ```
+ */
+declare const WithRouter: FunctionComponent<Omit<WithRouterProps, "router">>;
+export { type BaseIntentParams, type IntentJsonParams, IntentLink, IntentLinkProps, type IntentParameters, type InternalSearchParam, Link, LinkProps, type MatchError, type MatchOk, type MatchResult, type NavigateBaseOptions, type NavigateOptions, type NavigateOptionsWithState, type NextStateOrOptions, type Route, type RouteChildren, RouteNodeOptions, RouteObject, RouteScope, RouteScopeProps, type RouteSegment, type RouteTransform, type Router, RouterContext, type RouterContextValue, type RouterNode, RouterProvider, RouterProviderProps, type RouterState, STICKY_PARAMS, type SearchParam, StateLink, StateLinkProps, UseIntentLinkOptions, UseLinkOptions, UseStateLinkOptions, WithRouter, WithRouterProps, _createNode, decodeJsonParams, encodeJsonParams, route, useIntentLink, useLink, useRouter, useRouterState, useStateLink, withRouter };