chore!: enable react-hooks v7 rules and address surfaced anti-patterns (#941) (#950)

* chore: enable react-hooks/immutability and enforce _ prefix for unused destructure siblings (#941)

- Re-enable the react-hooks/immutability rule and fix the one
  violation in VariableSizeListItem: replace delete style.height
  (prop mutation) with a non-mutating destructure.
- Tighten @typescript-eslint/no-unused-vars: drop the implicit
  ignoreRestSiblings allowance and instead require unused
  destructure siblings to be _-prefixed (argsIgnorePattern +
  varsIgnorePattern = ^_). This forces intentional-omit cases to
  be visibly marked.
- Apply the convention to the existing intentional-omit sites and
  drop the now-redundant eslint-disable directives.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: enable react-hooks/refs (#941)

- useAsync: per-site suppress on the useReducer initialStateRef
  access. useReducer reads its second arg only on first render,
  at which point initialStateRef.current is the same `state`
  value the ref was just initialized with — safe.
- FilterTag: per-site suppress on the overflow-detection block.
  The current ref-during-render measurement is genuinely broken
  (not reactive to resize / label change). Proper fix tracked
  in #949.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: document react-hooks/incompatible-library as not applicable (#941)

The rule is a React-Compiler-aware check (e.g. TanStack Table /
Virtual return values carry hidden mutable state). findable-ui
does not use the React Compiler, so the rule is not earning its
keep. Keep it off with an inline comment explaining the decision
and pointing at the revisit trigger (Compiler adoption).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: address simple set-state-in-effect sites (#941)

Five sites improved + one unused hook deleted. Rule itself stays
off in this commit; it'll be flipped on once the remaining sites
(MarkdownRenderer, UseTabs, useSessionTimeout, loginGuard, four
terra/* hooks) are addressed.

- useLocalStorage: migrate to useSyncExternalStore. Returns
  undefined from the server snapshot to preserve the "not loaded
  yet" sentinel that CookieBanner depends on; null or a string
  on the client. Reacts to cross-tab storage events.
- useFeatureFlag: migrate to useSyncExternalStore. Returns false
  on the server, the FLAG.TRUE comparison on the client.
- useResetableState: delete. Workspace audit found no consumers.
  The "sync prop to state via effect" shape it implemented is
  also an anti-pattern per current React docs.
- EllipsisContent: drop the redundant mount effect that
  transitioned state from undefined to NONE (behaviorally
  identical to starting at NONE). Tighten helper signatures now
  that ellipsisMode is always defined.
- CollapsableSection: replace the breakpoint useEffect with the
  React-docs adjust-during-render pattern. Replace the
  setTimeout-based transition-duration "settle" trick with
  Collapse's onEntered and onExited callbacks. Drop the outer
  JSX ternary; Collapse stays mounted and `in` is driven by
  `disabled || expanded` so desktop is force-open.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: enable react-hooks/set-state-in-effect (#941)

Final batch of the set-state-in-effect cluster. All flagged sites
addressed; rule now turned on at "error" level. Mix of structural
fixes (preferred) and per-site suppressions (where the pattern is
correct but the rule is overzealous).

Structural fixes:
- useHash: migrate to useSyncExternalStore subscribing to
  `hashchange`. Now SSR-safe (no hydration mismatch on URLs with
  fragments) and reactive to hash changes — both pre-existing
  gaps the old non-subscribing read had.
- useTabs: drop the useState+useEffect indirection; derive
  `value` directly from `useHash()` + outline. Initial value is
  correct on first render — no DEFAULT_TAB_VALUE flash.
- MarkdownRenderer: move the `setError(null)` reset into the
  fetch success handler so there is no synchronous setState in
  the effect body. Trade-off: stale error stays visible one
  parse cycle longer; net win in error→error transitions
  (no zero-error flash between).
- useSessionTimeout: drop useLocation, use useSearchParams from
  next/navigation. Sticky semantics preserved via
  adjust-during-render with a prev-value tracker — the banner
  only goes false via clearSessionTimeout, not via unrelated
  navigation that happens to drop the URL param (the state-sync
  manager does this).
- loginGuard provider: split the auth-success effect into
  adjust-during-render (setOpen(false)) + a separate effect that
  fires the stored callback. Clarifies pure-state vs side-effect.
- useFetchProfiles: drop useState+useEffect; derive `status`
  directly during render via getProfileStatus(...).

Per-site suppressions (with justification comments):
- useFetchTerraNIHProfile, useFetchTerraProfile,
  useFetchTerraTermsOfService: async fetch pattern with a
  synchronous "set to PENDING" before the network call. Refactor
  would require a data-fetching library or external store.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: enable react-hooks/static-components (#941)

Final rule from the v7 cluster. Codebase has zero violations,
so this just turns the rule on at error level to prevent future
regressions (the rule catches components defined inside other
components, which create new component identity on every render).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: address copilot review on #941 markdown renderer

- Move setError(null) out of the isValidElement branch so any
  successful parse clears a stale error, even when the result
  isn't a renderable element.
- Set element to null in the non-element case so we don't leave
  a stale previous element rendering.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: address copilot review on #941 useSessionTimeout init

Initialize both isSessionTimeout and prevSessionTimeout from the
current sessionTimeout value, so the adjust-during-render block
doesn't fire on first mount when the URL param is absent
(searchParams.get returns null in that case, which differed from
the prior `undefined` init and forced a discarded render).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Fran McDade <18710366+frano-m@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: frano-m

eslint.config.mjs

@@ -38,6 +38,10 @@ const config = [
     ],
     rules: {
       "@eslint-community/eslint-comments/require-description": "error",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+      ],
       "jsdoc/check-alignment": "error",
       "jsdoc/check-param-names": "error",
       "jsdoc/require-description": "error",
@@ -50,15 +54,17 @@ const config = [
       "perfectionist/sort-enums": "error",
       "perfectionist/sort-interfaces": "error",
       "react-hooks/exhaustive-deps": "error",
-      // The remaining react-hooks v7 rules below are React-Compiler-aware
-      // checks that surface real anti-patterns in the codebase. Disabled here
-      // to keep this PR scoped to the tooling upgrade; revisit alongside any
-      // future React Compiler adoption.
-      "react-hooks/immutability": "off",
+      "react-hooks/immutability": "error",
+      // react-hooks/incompatible-library is a React-Compiler-aware check
+      // that flags library hooks whose return values carry hidden mutable
+      // state the Compiler can't safely memoize (e.g. TanStack Table /
+      // Virtual). findable-ui does not use the React Compiler, so the rule
+      // is not earning its keep today. Revisit alongside any future React
+      // Compiler adoption.
       "react-hooks/incompatible-library": "off",
-      "react-hooks/refs": "off",
-      "react-hooks/set-state-in-effect": "off",
-      "react-hooks/static-components": "off",
+      "react-hooks/refs": "error",
+      "react-hooks/set-state-in-effect": "error",
+      "react-hooks/static-components": "error",
       // sonarjs v1 dropped `cognitive-complexity` from its recommended preset
       // (the rule's meta lost its `recommended` flag during the v1 rewrite,
       // a discrepancy with the package README). Restore at default threshold

src/components/Filter/components/Filter/components/DrawerTransition/drawerTransition.tsx

@@ -13,7 +13,6 @@ import { DrawerTransitionProps } from "./types";
  */
 export const DrawerTransition = ({
   children,
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- destructured out so it doesn't spread onto the DOM Slide element
   placement: _placement,
   ref,
   ...props

src/components/Filter/components/FilterTag/filterTag.tsx

@@ -33,10 +33,12 @@ export const FilterTag = ({
 }: FilterTagProps): JSX.Element => {
   const Tag = superseded ? SupersededTag : Chip;
   const tagRef = useRef<HTMLDivElement>(null);
+  /* eslint-disable react-hooks/refs -- ref-during-render measurement; needs proper ResizeObserver-in-effect rewrite. Tracked in #949. */
   const tagLabelElement =
     tagRef.current?.querySelector<HTMLElement>(".MuiChip-label");
   const isOverflowed =
     (tagLabelElement?.offsetWidth ?? 0) < (tagLabelElement?.scrollWidth ?? 0);
+  /* eslint-enable react-hooks/refs -- end suppression for #949. */
   return (
     <Tooltip
       arrow

src/components/Filter/components/SearchAllFilters/components/OutlinedInput/outlinedInput.tsx

@@ -10,8 +10,12 @@ import { isButtonIn } from "./utils";
 export const OutlinedInput = (
   props: AutocompleteRenderInputParams,
 ): JSX.Element => {
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Intended behavior, destructure InputLabelProps, as they are not used on the component.
-  const { InputLabelProps, InputProps, ...outlinedInputProps } = props;
+  // Destructure InputLabelProps out so it isn't spread onto the component.
+  const {
+    InputLabelProps: _InputLabelProps,
+    InputProps,
+    ...outlinedInputProps
+  } = props;
   const { onClear, open, searchTerm, surfaceType } = useAutocomplete();
   return (
     <StyledOutlinedInput

src/components/Filter/components/VariableSizeListItem/variableSizeListItem.tsx

@@ -38,7 +38,9 @@ export default function VariableSizeListItem({
     labelRanges,
     value: { count, key, label, selected },
   } = matchedItem;
-  delete style.height; // Remove height style to allow variable size list to set item height.
+  // Strip height so the variable-size list can drive item height via
+  // onUpdateItemSizeByItemKey, without mutating the parent-owned style prop.
+  const { height: _height, ...itemStyle } = style;
 
   // Sets map of list item key to its height.
   useEffect(() => {
@@ -55,7 +57,7 @@ export default function VariableSizeListItem({
       ref={listItemRef}
       onClick={handleItemClicked}
       selected={selected}
-      style={style}
+      style={itemStyle}
     >
       <Checkbox
         checked={selected}

src/components/Layout/components/Outline/hooks/UseHash/hook.ts

@@ -1,17 +1,33 @@
-import { isSSR } from "../../../../../../utils/ssr";
+import { useSyncExternalStore } from "react";
 import { UseHash } from "./types";
 
 /**
  * Hook to get the current URL hash without the leading '#' character.
- *
- * @description
- * Extracts the hash from window.location.hash and removes the leading '#'.
- * Returns empty string when running in SSR environment.
- *
- * @returns Object containing the hash without leading '#', or empty string if SSR.
+ * SSR-safe: returns an empty string on the server and during the hydration
+ * pass; reads `window.location.hash` on the client. Reacts to `hashchange`
+ * events so consumers re-render when the URL hash changes.
+ * @returns Object containing the hash without leading '#', or empty string
+ *   on the server.
  */
 export function useHash(): UseHash {
-  if (isSSR()) return { hash: "" };
-  const { hash } = window.location;
-  return { hash: hash.replace(/^#/, "") };
+  const hash = useSyncExternalStore(
+    subscribe,
+    () => window.location.hash.replace(/^#/, ""),
+    () => "",
+  );
+  return { hash };
+}
+
+/**
+ * Subscribe a callback to the window's `hashchange` event.
+ * Module-scope so its identity stays stable across renders (required by
+ * useSyncExternalStore).
+ * @param callback - Listener invoked when the URL hash changes.
+ * @returns Unsubscribe function.
+ */
+function subscribe(callback: () => void): () => void {
+  window.addEventListener("hashchange", callback);
+  return (): void => {
+    window.removeEventListener("hashchange", callback);
+  };
 }

src/components/Layout/components/Outline/hooks/UseTabs/hook.ts

@@ -1,26 +1,21 @@
 import { TabsProps } from "@mui/material";
 import Router from "next/router";
-import { SyntheticEvent, useCallback, useEffect, useState } from "react";
+import { SyntheticEvent, useCallback } from "react";
 import { TABS_PROPS } from "../../../../../../styles/common/mui/tabs";
 import { OutlineItem } from "../../types";
 import { useHash } from "../UseHash/hook";
-import { DEFAULT_TAB_VALUE } from "./constants";
 import { getNextValue } from "./utils";
 
 export function useTabs(
   outline: OutlineItem[],
 ): Pick<TabsProps, "indicatorColor" | "onChange" | "orientation" | "value"> {
-  const [value, setValue] = useState<TabsProps["value"]>(DEFAULT_TAB_VALUE);
   const { hash } = useHash();
+  const value = getNextValue(hash, outline);
 
   const onChange = useCallback((_event: SyntheticEvent, hash: string): void => {
     Router.push({ hash });
   }, []);
 
-  useEffect(() => {
-    setValue(getNextValue(hash, outline));
-  }, [hash, outline]);
-
   return {
     indicatorColor: value
       ? TABS_PROPS.INDICATOR_COLOR.PRIMARY

src/components/MarkdownRenderer/markdownRenderer.tsx

@@ -35,7 +35,6 @@ export const MarkdownRenderer = ({
 
   useEffect(() => {
     let cancelled = false;
-    setError(null);
 
     const processor = unified()
       .use(remarkParse)
@@ -55,7 +54,8 @@ export const MarkdownRenderer = ({
       .process(value)
       .then((file: VFile) => {
         if (cancelled) return;
-        if (isValidElement(file.result)) setElement(file.result);
+        setError(null);
+        setElement(isValidElement(file.result) ? file.result : null);
       })
       .catch((err: Error) => {
         if (!cancelled) setError(err.message);

src/components/TableCreator/common/utils.ts

@@ -12,10 +12,10 @@ import { ColumnConfig } from "../../../config/entities";
 export function buildBaseColumnDef<T>(
   baseColumnConfig: ColumnConfig<T>,
 ): ColumnDef<T> {
+  // Destructure componentConfig out so it isn't passed through to the columnDef.
   const {
     columnPinned,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Destructure to avoid passing it to the columnDef.
-    componentConfig,
+    componentConfig: _componentConfig,
     header,
     id,
     meta,

src/components/common/EllipsisContent/ellipsisContent.tsx

@@ -23,7 +23,9 @@ export const EllipsisContent = ({
   const ellipsisRef = useRef<HTMLDivElement>(null);
   const { height } =
     useResizeObserver(ellipsisRef, getBorderBoxSizeHeight) || {};
-  const [ellipsisMode, setEllipsisMode] = useState<EllipsisMode | undefined>();
+  const [ellipsisMode, setEllipsisMode] = useState<EllipsisMode>(
+    EllipsisMode.NONE,
+  );
   const isEllipsis = ellipsisMode === EllipsisMode.ON;
 
   /**
@@ -38,14 +40,6 @@ export const EllipsisContent = ({
     });
   };
 
-  /**
-   * Ellipsis mode state is initialized to "NONE" only when the component mounts,
-   * so we guarantee that `ellipsisRef` gets the element handle for resize observer hook.
-   */
-  useEffect(() => {
-    setEllipsisMode(EllipsisMode.NONE);
-  }, []);
-
   /**
    * Ellipsis mode state updates with changes to the rendered content height.
    */
@@ -119,7 +113,7 @@ function calculateRenderedLineCount(
 function getEllipsisMode(
   element: HTMLDivElement | null,
   maxLineCount: number,
-  currentMode: EllipsisMode = EllipsisMode.NONE,
+  currentMode: EllipsisMode,
 ): EllipsisMode {
   // Calculate line count.
   const lineCount = calculateRenderedLineCount(element);
@@ -149,7 +143,7 @@ function getEllipsisMode(
  * @param currentMode - current ellipsis mode.
  * @returns string for display as button text.
  */
-function getModeText(currentMode?: EllipsisMode): string {
+function getModeText(currentMode: EllipsisMode): string {
   if (currentMode === EllipsisMode.ON) {
     return "Read More";
   }
@@ -189,8 +183,8 @@ function getTextNodeDOMRects(node: Node, DOMRects: DOMRect[] = []): DOMRect[] {
  * @param currentMode - current ellipsis mode.
  * @returns true when mode is not "NONE".
  */
-function isModeActivated(currentMode?: EllipsisMode): boolean {
-  return !!currentMode && currentMode !== EllipsisMode.NONE;
+function isModeActivated(currentMode: EllipsisMode): boolean {
+  return currentMode !== EllipsisMode.NONE;
 }
 
 /**