chore: Address feedback

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[];
 

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';

src/anchor-navigation/scroll-spy.tsx → 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);