From da8988c9b7a8ae307cfa448f57ca301d420d6052 Mon Sep 17 00:00:00 2001
From: Ruben Carvalho <rucarva@amazon.com>
Date: Wed, 20 Sep 2023 11:17:33 +0000
Subject: [PATCH] chore: Address feedback

---
 src/anchor-navigation/interfaces.ts                |  1 +
 src/anchor-navigation/internal.tsx                 |  2 +-
 .../{scroll-spy.tsx => use-scroll-spy.tsx}         | 14 +++++++++++++-
 3 files changed, 15 insertions(+), 2 deletions(-)
 rename src/anchor-navigation/{scroll-spy.tsx => use-scroll-spy.tsx} (76%)

diff --git a/src/anchor-navigation/interfaces.ts b/src/anchor-navigation/interfaces.ts
index 0de2d82275..3309541fdd 100644
--- a/src/anchor-navigation/interfaces.ts
+++ b/src/anchor-navigation/interfaces.ts
@@ -22,6 +22,7 @@ export interface AnchorNavigationProps extends BaseComponentProps {
    * * `level` (number) - Level of nesting of the anchor.
    * * `info` (string | undefined) - Additional information to display next to the link, for example: "New" or "Updated".
    *
+   * Note: The list of anchors should be sorted in the order they appear on the page.
    */
   anchors: AnchorNavigationProps.Anchor[];
 
diff --git a/src/anchor-navigation/internal.tsx b/src/anchor-navigation/internal.tsx
index 257eca4113..8697d0d003 100644
--- a/src/anchor-navigation/internal.tsx
+++ b/src/anchor-navigation/internal.tsx
@@ -6,7 +6,7 @@ import styles from './styles.css.js';
 import testUtilsStyles from './test-classes/styles.css.js';
 import { AnchorNavigationProps } from './interfaces';
 import { checkSafeUrl } from '../internal/utils/check-safe-url';
-import useScrollSpy from './scroll-spy.js';
+import useScrollSpy from './use-scroll-spy.js';
 import { fireCancelableEvent, fireNonCancelableEvent, isPlainLeftClick } from '../internal/events/index';
 import { InternalBaseComponentProps } from '../internal/hooks/use-base-component/index.js';
 import { getBaseProps } from '../internal/base-component/index.js';
diff --git a/src/anchor-navigation/scroll-spy.tsx b/src/anchor-navigation/use-scroll-spy.tsx
similarity index 76%
rename from src/anchor-navigation/scroll-spy.tsx
rename to src/anchor-navigation/use-scroll-spy.tsx
index e6d1f07443..b129138e9b 100644
--- a/src/anchor-navigation/scroll-spy.tsx
+++ b/src/anchor-navigation/use-scroll-spy.tsx
@@ -4,6 +4,18 @@ import { useCallback, useEffect, useState } from 'react';
 
 const isBrowser = typeof window !== 'undefined';
 
+/**
+ * Hook to implement scroll-spy functionality.
+ *
+ * @param hrefs An array of href strings that correspond to the IDs of the target elements on the page.
+ * The hrefs should be sorted in the order they appear on the page for accurate scroll-spy behavior.
+ * @param scrollSpyOffset The number of pixels to offset from the top of the document when activating anchors.
+ * Useful for accommodating fixed or sticky headers.
+ * @param activeHref The currently active href. If provided, the hook will operate in a controlled manner,
+ * and the scroll-spy logic will be disabled.
+ *
+ * @returns {string | undefined} - The href of the currently active element as per scroll position, or undefined if none is active.
+ */
 export default function useScrollSpy({
   hrefs,
   scrollSpyOffset,
@@ -34,7 +46,7 @@ export default function useScrollSpy({
     return lastAnchorExists && Math.ceil(window.scrollY) >= Math.floor(document.body.scrollHeight - window.innerHeight);
   }, [lastAnchorExists]);
 
-  // Find the href for which the element is within the viewport
+  // Find the first href for which the element is within the viewport
   const findHrefInView = useCallback(() => {
     return hrefs.find(href => {
       const rect = getRectByHref(href);