chore(website): preserve RulesTable filters state in searchParams (#6568

)

* feat(website): preserve RulesTable filters state in searchParams

* Move rules filters state to useLocation

* Revert "Move rules filters state to useLocation"

This reverts commit 7c2e81a.

* Test rules filters in URL

* Use .ruleset prop in RulesTable

* Use useHistorySelector instead of useIsomorphicLayoutEffect

* Move useHistorySelector to src/hooks

* Fix lint errors

packages/eslint-plugin/docs/rules/README.md

@@ -13,11 +13,11 @@ See [Configs](/linting/configs) for how to enable recommended rules using config
 
 import RulesTable from "@site/src/components/RulesTable";
 
-<RulesTable />
+<RulesTable ruleset="supported-rules" />
 
 ## Extension Rules
 
 In some cases, ESLint provides a rule itself, but it doesn't support TypeScript syntax; either it crashes, or it ignores the syntax, or it falsely reports against it.
 In these cases, we create what we call an extension rule; a rule within our plugin that has the same functionality, but also supports TypeScript.
 
-<RulesTable extensionRules />
+<RulesTable ruleset="extension-rules" />

packages/website/src/components/RulesTable/index.tsx

@@ -1,9 +1,14 @@
 import Link from '@docusaurus/Link';
+import { useHistory } from '@docusaurus/router';
 import type { RulesMeta } from '@site/rulesMeta';
 import { useRulesMeta } from '@site/src/hooks/useRulesMeta';
 import clsx from 'clsx';
-import React, { useMemo, useState } from 'react';
+import React, { useMemo } from 'react';
 
+import {
+  type HistorySelector,
+  useHistorySelector,
+} from '../../hooks/useHistorySelector';
 import styles from './styles.module.css';
 
 function interpolateCode(text: string): (JSX.Element | string)[] | string {
@@ -118,82 +123,60 @@ function match(mode: FilterMode, value: boolean): boolean | undefined {
 }
 
 export default function RulesTable({
-  extensionRules,
+  ruleset,
 }: {
-  extensionRules?: boolean;
+  ruleset: 'extension-rules' | 'supported-rules';
 }): JSX.Element {
+  const [filters, changeFilter] = useRulesFilters(ruleset);
+
   const rules = useRulesMeta();
-  const [showRecommended, setShowRecommended] = useState<FilterMode>('neutral');
-  const [showStrict, setShowStrict] = useState<FilterMode>('neutral');
-  const [showFixable, setShowFixable] = useState<FilterMode>('neutral');
-  const [showHasSuggestions, setShowHasSuggestion] =
-    useState<FilterMode>('neutral');
-  const [showTypeCheck, setShowTypeCheck] = useState<FilterMode>('neutral');
+  const extensionRules = ruleset === 'extension-rules';
   const relevantRules = useMemo(
     () =>
       rules
         .filter(r => !!extensionRules === !!r.docs?.extendsBaseRule)
         .filter(r => {
           const opinions = [
             match(
-              showRecommended,
+              filters.recommended,
               r.docs?.recommended === 'error' || r.docs?.recommended === 'warn',
             ),
-            match(showStrict, r.docs?.recommended === 'strict'),
-            match(showFixable, !!r.fixable),
-            match(showHasSuggestions, !!r.hasSuggestions),
-            match(showTypeCheck, !!r.docs?.requiresTypeChecking),
+            match(filters.strict, r.docs?.recommended === 'strict'),
+            match(filters.fixable, !!r.fixable),
+            match(filters.suggestions, !!r.hasSuggestions),
+            match(filters.typeInformation, !!r.docs?.requiresTypeChecking),
           ].filter((o): o is boolean => o !== undefined);
           return opinions.every(o => o);
         }),
-    [
-      rules,
-      extensionRules,
-      showRecommended,
-      showStrict,
-      showFixable,
-      showHasSuggestions,
-      showTypeCheck,
-    ],
+    [rules, extensionRules, filters],
   );
+
   return (
     <>
       <ul className={clsx('clean-list', styles.checkboxList)}>
         <RuleFilterCheckBox
-          mode={showRecommended}
-          setMode={(newMode): void => {
-            setShowRecommended(newMode);
-
-            if (newMode === 'include' && showStrict === 'include') {
-              setShowStrict('exclude');
-            }
-          }}
+          mode={filters.recommended}
+          setMode={(newMode): void => changeFilter('recommended', newMode)}
           label="✅ recommended"
         />
         <RuleFilterCheckBox
-          mode={showStrict}
-          setMode={(newMode): void => {
-            setShowStrict(newMode);
-
-            if (newMode === 'include' && showRecommended === 'include') {
-              setShowRecommended('exclude');
-            }
-          }}
+          mode={filters.strict}
+          setMode={(newMode): void => changeFilter('strict', newMode)}
           label="🔒 strict"
         />
         <RuleFilterCheckBox
-          mode={showFixable}
-          setMode={setShowFixable}
+          mode={filters.fixable}
+          setMode={(newMode): void => changeFilter('fixable', newMode)}
           label="🔧 fixable"
         />
         <RuleFilterCheckBox
-          mode={showHasSuggestions}
-          setMode={setShowHasSuggestion}
+          mode={filters.suggestions}
+          setMode={(newMode): void => changeFilter('suggestions', newMode)}
           label="💡 has suggestions"
         />
         <RuleFilterCheckBox
-          mode={showTypeCheck}
-          setMode={setShowTypeCheck}
+          mode={filters.typeInformation}
+          setMode={(newMode): void => changeFilter('typeInformation', newMode)}
           label="💭 requires type information"
         />
       </ul>
@@ -224,3 +207,97 @@ export default function RulesTable({
     </>
   );
 }
+
+type FilterCategory =
+  | 'recommended'
+  | 'strict'
+  | 'fixable'
+  | 'suggestions'
+  | 'typeInformation';
+type FiltersState = Record<FilterCategory, FilterMode>;
+const neutralFiltersState: FiltersState = {
+  recommended: 'neutral',
+  strict: 'neutral',
+  fixable: 'neutral',
+  suggestions: 'neutral',
+  typeInformation: 'neutral',
+};
+
+const selectSearch: HistorySelector<string> = history =>
+  history.location.search;
+const getServerSnapshot = (): string => '';
+
+function useRulesFilters(
+  paramsKey: string,
+): [FiltersState, (category: FilterCategory, mode: FilterMode) => void] {
+  const history = useHistory();
+  const search = useHistorySelector(selectSearch, getServerSnapshot);
+
+  const paramValue = new URLSearchParams(search).get(paramsKey) ?? '';
+  // We can't compute this in selectSearch, because we need the snapshot to be
+  // comparable by value.
+  const filtersState = useMemo(
+    () => parseFiltersState(paramValue),
+    [paramValue],
+  );
+
+  const changeFilter = (category: FilterCategory, mode: FilterMode): void => {
+    const newState = { ...filtersState, [category]: mode };
+
+    if (
+      category === 'strict' &&
+      mode === 'include' &&
+      filtersState.recommended === 'include'
+    ) {
+      newState.recommended = 'exclude';
+    } else if (
+      category === 'recommended' &&
+      mode === 'include' &&
+      filtersState.strict === 'include'
+    ) {
+      newState.strict = 'exclude';
+    }
+
+    const searchParams = new URLSearchParams(history.location.search);
+    const filtersString = stringifyFiltersState(newState);
+
+    if (filtersString) {
+      searchParams.set(paramsKey, filtersString);
+    } else {
+      searchParams.delete(paramsKey);
+    }
+
+    history.replace({ search: searchParams.toString() });
+  };
+
+  return [filtersState, changeFilter];
+}
+
+const NEGATION_SYMBOL = 'x';
+
+function stringifyFiltersState(filters: FiltersState): string {
+  return Object.entries(filters)
+    .map(([key, value]) =>
+      value === 'include'
+        ? key
+        : value === 'exclude'
+        ? `${NEGATION_SYMBOL}${key}`
+        : '',
+    )
+    .filter(Boolean)
+    .join('-');
+}
+
+function parseFiltersState(str: string): FiltersState {
+  const res: FiltersState = { ...neutralFiltersState };
+
+  for (const part of str.split('-')) {
+    const exclude = part.startsWith(NEGATION_SYMBOL);
+    const key = exclude ? part.slice(1) : part;
+    if (Object.hasOwn(neutralFiltersState, key)) {
+      res[key] = exclude ? 'exclude' : 'include';
+    }
+  }
+
+  return res;
+}

packages/website/src/hooks/useHistorySelector.ts

@@ -0,0 +1,17 @@
+import { useHistory } from '@docusaurus/router';
+import type * as H from 'history';
+import { useSyncExternalStore } from 'react';
+
+export type HistorySelector<T> = (history: H.History<H.LocationState>) => T;
+
+export function useHistorySelector<T>(
+  selector: HistorySelector<T>,
+  getServerSnapshot: () => T,
+): T {
+  const history = useHistory();
+  return useSyncExternalStore(
+    history.listen,
+    () => selector(history),
+    getServerSnapshot,
+  );
+}

packages/website/tests/rules.spec.ts

@@ -0,0 +1,32 @@
+import AxeBuilder from '@axe-core/playwright';
+import { expect, test } from '@playwright/test';
+
+test.describe('Rules Page', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/rules');
+  });
+
+  test('Accessibility', async ({ page }) => {
+    await new AxeBuilder({ page }).analyze();
+  });
+
+  test('Rules filters are saved to the URL', async ({ page }) => {
+    await page.getByText('🔧 fixable').first().click();
+    await page.getByText('✅ recommended').first().click();
+    await page.getByText('✅ recommended').first().click();
+
+    expect(new URL(page.url()).search).toBe(
+      '?supported-rules=xrecommended-fixable',
+    );
+  });
+
+  test('Rules filters are read from the URL on page load', async ({ page }) => {
+    await page.goto('/rules?supported-rules=strict-xfixable');
+
+    const strict = page.getByText('🔒 strict').first();
+    const fixable = page.getByText('🔧 fixable').first();
+
+    await expect(strict).toHaveAttribute('aria-label', /Current: include/);
+    await expect(fixable).toHaveAttribute('aria-label', /Current: exclude/);
+  });
+});