chore: add KnockGuideLocationSensor page, plus a few guide edits (#1206)

* add a page for KnockGuideLocationSensor, along with a few guide edits

* example viz, copy edits

---------

Co-authored-by: Scoti Dodson <scoti@Mac.lan>

Author: thomaswhyyou

content/in-app-ui/guides/render-guides.mdx

@@ -9,7 +9,7 @@ Once you've [created a guide](/in-app-ui/guides/create-guides), you'll need to r
 
 ## Fetching guides
 
-You can fetch guides using Knock's client-side SDKs or by directly calling the [guides API](/api-reference/users/guides).
+There are two ways to fetch and render guides: using Knock's client-side SDKs, which provide built-in state management and helper methods, or by directly calling the [guides API](/api-reference/users/guides) to build a custom implementation. Our [step-by-step React example](/in-app-ui/react/headless/guide) demonstrates how to incorporate the SDK's guide provider into your application and render guide components to your users.
 
 ### Client-side SDKs
 
@@ -53,17 +53,16 @@ Knock exposes a set of client SDKs that provide helpers and logic to make it eas
 
 #### Key SDK resources
 
-When working with Knock's SDKs to fetch and render guides, you'll use the following components and hooks:
+When working with Knock's SDKs to fetch and render guides, you'll use the following components and hooks for React:
 
 - [**KnockGuideProvider**](/in-app-ui/react/sdk/components/knock-guide-provider). Provider component that fetches guides and manages guide state.
 - [**useGuide**](/in-app-ui/react/sdk/hooks/use-guide). Hook to fetch a single guide by type or key.
 - [**useGuides**](/in-app-ui/react/sdk/hooks/use-guides). Hook to fetch multiple guides.
 - [**useGuideContext**](/in-app-ui/react/sdk/hooks/use-guide-context). Hook to access the guide client for advanced use cases.
 
 <Callout
-  emoji="🚧"
+  type="info"
   title="Additional SDK support."
-  bgColor="blue"
   text={
     <>
       We're working on adding guides support to more of our client SDKs. Please
@@ -98,9 +97,9 @@ When multiple guides exist for a single `type` (e.g, a generic "Banner" componen
 
 <AccordionGroup>
   <Accordion title="When should I use useGuide vs useGuides?">
-  The [`useGuide`](/in-app-ui/react/sdk/hooks/use-guide) hook fetches a single guide at a time. This is ideal for components that should only display one guide, like a banner or modal that occupies a specific location in your UI.
+  The [`useGuide`](/in-app-ui/react/sdk/hooks/use-guide) hook returns a single guide at a time, subject to eligibility criteria, throttling rules, and ordering. This is ideal for components that should only display one guide, like a banner or modal that occupies a specific location in your UI.
 
-The [`useGuides`](/in-app-ui/react/sdk/hooks/use-guides) hook fetches one or more guides, subject to eligibility criteria. This is useful for components that can display multiple guides at once, like a list of changelog cards or announcements in a sidebar.
+The [`useGuides`](/in-app-ui/react/sdk/hooks/use-guides) hook fetches one or more guides, subject to eligibility criteria, in the configured order. This is useful for components that can display multiple guides at once, like a list of changelog cards or announcements in a sidebar. The `useGuides` hook is designed to return multiple guides, so it does not apply throttling rules.
 
   </Accordion>
   <Accordion title="How do I render multiple guides in a single component?">
@@ -116,8 +115,8 @@ The [`useGuides`](/in-app-ui/react/sdk/hooks/use-guides) hook fetches one or mor
         <div>
           {guides.map((guide) => (
             <div key={guide.key}>
-              <h3>{guide.step.content.title}</h3>
-              <p>{guide.step.content.body}</p>
+              <h3>{guide.steps[0].content.title}</h3>
+              <p>{guide.steps[0].content.body}</p>
             </div>
           ))}
         </div>
@@ -142,5 +141,5 @@ The [`useGuides`](/in-app-ui/react/sdk/hooks/use-guides) hook fetches one or mor
 
     To see which guides are actually eligible to be rendered, check the `entries` array in the API response, which contains only the guides that match all criteria for the current user and context.
 
-  </Accordion>  
+  </Accordion>
 </AccordionGroup>

content/in-app-ui/react/headless/guide.mdx

@@ -64,6 +64,22 @@ Using our `@knocklabs/react` and `@knocklabs/client` libraries, you can create f
     };
     ```
 
+<Callout
+  type="info"
+  title="If you're using Next.js or Tanstack Router,"
+  text={
+    <>
+      consider using the{" "}
+      <a href="/in-app-ui/react/sdk/components/knock-guide-location-sensor">
+        KnockGuideLocationSensor
+      </a>
+      {` `}
+      helper component inside <code>KnockGuideProvider</code> to facilitate
+      evaluating activation rules based on route changes.
+    </>
+  }
+/>
+>
   </Step>
   <Step title="Setup a custom message type.">
     If you're not using one of our pre-built message types, you'll need to set up a custom message type. You can learn more about how to do this in our [message types](/in-app-ui/message-types/create-message-types) documentation.

content/in-app-ui/react/sdk/components/knock-guide-location-sensor.mdx

@@ -0,0 +1,7 @@
+---
+title: KnockGuideLocationSensor
+description:
+section: SDKs
+---
+
+<Typedoc file="react-core/components/knock-guide-location-sensor" />

data/sidebars/inAppSidebar.ts

@@ -122,6 +122,7 @@ const SHARED_REACT_COMPONENTS = [
   { slug: "/knock-provider", title: "KnockProvider" },
   { slug: "/knock-feed-provider", title: "KnockFeedProvider" },
   { slug: "/knock-guide-provider", title: "KnockGuideProvider" },
+  { slug: "/knock-guide-location-sensor", title: "KnockGuideLocationSensor" },
   { slug: "/knock-slack-provider", title: "KnockSlackProvider" },
   { slug: "/knock-ms-teams-provider", title: "KnockMsTeamsProvider" },
   { slug: "/knock-i18n-provider", title: "KnockI18nProvider" },

typedocs/react-core/components/knock-guide-location-sensor.mdx

@@ -0,0 +1,59 @@
+A React helper component intended for use with select supported frameworks, such as [Next.js](https://nextjs.org/) and [Tanstack Router](https://tanstack.com/router/), for detecting route changes.
+
+Activation rules for guides are evaluated as a user's location changes in your application and, by default, [KnockGuideProvider](/in-app-ui/react/sdk/components/knock-guide-provider) listens for location change events from the global `window` object (enabled via the `trackLocationFromWindow` prop). However, modern frameworks often provide their own first class router APIs for detecting and reacting to route changes, which often works better and more reliably.
+
+Two important notes to keep in mind when implementing `KnockGuideLocationSensor`:
+
+1.  The import path is specific to the corresponding framework (e.g., `@knocklabs/react/next` for Next.js).
+2.  `KnockGuideLocationSensor` must be placed inside `KnockGuideProvider`.
+
+## Usage
+
+### Next.js
+
+```jsx title="Next.js implementation of KnockGuideLocationSensor."
+import { KnockProvider, KnockGuideProvider } from "@knocklabs/react-core";
+import { KnockGuideLocationSensor } from "@knocklabs/react/next";
+
+function App() {
+  return (
+    <KnockProvider apiKey="pk_test_..." userId="user-123">
+      <KnockGuideProvider
+        channelId="..."
+        readyToTarget={true}
+        // Turn off default event listeners on window.
+        trackLocationFromWindow={false}
+      >
+        <MyGuideComponent />
+        // Must be placed inside KnockGuideProvider.
+        <KnockGuideLocationSensor.AppRouter />
+        // If you are using the Pages Router: // <KnockGuideLocationSensor.PagesRouter />
+      </KnockGuideProvider>
+    </KnockProvider>
+  );
+}
+```
+
+### Tanstack Router
+
+```jsx title="Tanstack Router implementation of KnockGuideLocationSensor."
+import { KnockProvider, KnockGuideProvider } from "@knocklabs/react-core";
+import { KnockGuideLocationSensor } from "@knocklabs/react/tanstack";
+
+function App() {
+  return (
+    <KnockProvider apiKey="pk_test_..." userId="user-123">
+      <KnockGuideProvider
+        channelId="..."
+        readyToTarget={true}
+        // Turn off default event listeners on window.
+        trackLocationFromWindow={false}
+      >
+        <MyGuideComponent />
+        // Must be placed inside KnockGuideProvider.
+        <KnockGuideLocationSensor />
+      </KnockGuideProvider>
+    </KnockProvider>
+  );
+}
+```

typedocs/react-core/components/knock-guide-provider.mdx

@@ -15,7 +15,7 @@ function App() {
         colorMode="auto"
         trackLocationFromWindow={true}
       >
-        <GuideRenderer />
+        <MyGuideComponent />
       </KnockGuideProvider>
     </KnockProvider>
   );