Update docs for useLinkBuilder

versioned_docs/version-7.x/upgrading-from-6.x.md

@@ -156,9 +156,9 @@ or
 
 With this change, you'd now have full type-safety when using the `Link` component given that you have [configured the global type](typescript.md#specifying-default-types-for-usenavigation-link-ref-etc).
 
-### The `useLinkTo` and `useLinkBuilder` hooks are merged into `useLinkTools`
+### The `useLinkBuilder` hooks now returns an object instead of a function
 
-Previously, the `useLinkTo` and `useLinkBuilder` hooks could be used to build a path for a screen or action for a path respectively. This was primarily useful for building custom navigators. Now, both of these hooks are merged into a single `useLinkTools` hook:
+Previously, the `useLinkBuilder` hooks returned a function to build a `href` for a screen - which is primarily useful for building custom navigators. Now, it returns an object with `buildHref` and `buildAction` methods:
 
 ```js
 const { buildHref, buildAction } = useLinkTools();
@@ -167,7 +167,9 @@ const href = buildHref('Details', { foo: 42 }); // '/details?foo=42'
 const action = buildAction('/details?foo=42'); // { type: 'NAVIGATE', payload: { name: 'Details', params: { foo: 42 } } }
 ```
 
-Note that this hook is intended to be used by custom navigators and not by end users. For end users, the `Link` component and `useLinkProps` are the recommended way to navigate.
+The `buildHref` method acts the same as the previously returned function. The new `buildAction` method can be used to build a navigation action from a `href` string.
+
+Note that this hook is intended to be primarily used by custom navigators and not by end users. For end users, the `Link` component and `useLinkProps` are the recommended way to navigate.
 
 ### The flipper devtools plugin is now removed
 

versioned_docs/version-7.x/use-link-builder.md

@@ -4,30 +4,61 @@ title: useLinkBuilder
 sidebar_label: useLinkBuilder
 ---
 
-The `useLinkBuilder` hook lets us build a path to use for links for a screen in the current navigator's state. It returns a function that takes `name` and `params` for the screen to focus and returns path based on the [`linking` options](navigation-container.md#linking).
+The `useLinkBuilder` hook returns helpers to build `href` or action based on the linking options. It returns an object with the following properties:
+
+- [`buildHref`](#buildhref)
+- [`buildAction`](#buildaction)
+
+## `buildHref`
+
+The `buildHref` method lets us build a path to use for links for a screen in the current navigator's state. It returns a function that takes `name` and `params` for the screen to focus and returns path based on the [`linking` options](navigation-container.md#linking).
 
 ```js
-import { Link, CommonActions, useLinkBuilder } from '@react-navigation/native';
+import { useLinkBuilder } from '@react-navigation/native';
+import { PlatformPressable } from '@react-navigation/elements';
 
 // ...
 
-function DrawerContent({ state, descriptors }) {
-  const buildLink = useLinkBuilder();
+function DrawerContent({ state, descriptors, navigation }) {
+  const { buildHref } = useLinkBuilder();
 
   return state.routes((route) => (
-    <Link
-      to={buildLink(route.name, route.params)}
-      action={CommonActions.navigate(route.name)}
+    <PlatformPressable
+      href={buildHref(route.name, route.params)}
+      onPress={() => navigation.navigate(route.name, route.params)}
     >
       {descriptors[route.key].options.title}
-    </Link>
+    </PlatformPressable>
   ));
 }
 ```
 
-This hook is intended to be used in navigators to show links to various pages in it, such as drawer and tab navigators. If you're building a custom navigator, custom drawer content, custom tab bar etc. then you might want to use this hook.
+This hook is intended to be used in navigators to show links to various pages in the navigator, such as drawer and tab navigators. If you're building a custom navigator, custom drawer content, custom tab bar etc. then you might want to use this hook.
 
 There are couple of important things to note:
 
 - The destination screen must be present in the current navigator. It cannot be in a parent navigator or a navigator nested in a child.
-- It's intended to be only used in custom navigators to keep them reusable in multiple apps. For your regular app code, use paths directly instead of building paths for screens, or use [`Link`](link.md) and [`useLinkProps`](use-link-props.md) which transparently handle paths.
+- It's intended to be only used in custom navigators to keep them reusable in multiple apps. For your regular app code, use screen names directly instead of building paths for screens.
+
+## `buildAction`
+
+The `buildAction` method lets us parse a `href` string into an action object that can be used with [`navigation.dispatch`](navigation-prop.md#dispatch) to navigate to the relevant screen.
+
+```js
+import { Link, CommonActions, useLinkBuilder } from '@react-navigation/native';
+import { Button } from '@react-navigation/elements';
+
+// ...
+
+function MyComponent() {
+  const { buildAction } = useLinkBuilder();
+
+  return (
+    <Button onPress={() => navigation.dispatch(buildAction('/users/jane'))}>
+      Go to Jane's profile
+    </Button>
+  );
+}
+```
+
+The [`useLinkTo`](use-link-to.md) hook is a convenient wrapper around this hook to navigate to a screen using a `href` string.

versioned_docs/version-7.x/use-link-to.md

@@ -22,7 +22,13 @@ function Home() {
 }
 ```
 
-This is a low-level hook used to build more complex behavior on top. We recommended to use the [`useLinkProps` hook](use-link-props.md) to build your custom link components instead of using this hook directly. It will ensure that your component is properly accessible on the web.
+This is a low-level hook used to build more complex behavior on top. We recommended using the [`useLinkProps` hook](use-link-props.md) to build your custom link components instead of using this hook directly. It will ensure that your component is properly accessible on the web.
+
+:::warning
+
+Navigating via `href` strings is not type-safe. If you want to navigate to a screen with type-safety, it's recommended to use screen names directly.
+
+:::
 
 ## Using with class component