feat: ability to share a tag scene with a filter applied (#1142)

* Tag filters from method / type tag scenes pushed to URL with location event listeners in both scenes

* Added util functions in path for validating tag filters to account for error inputs

* Custom reconciliation hooks for APIExplorer and Method/Type Tag Scenes

* Unit testing for both tag scenes

* Unit testing for globalStoreSync and tagStoreSync 

* Changing 'v' param to 't', final refactor and code cleanup

Co-authored-by: Joseph Axisa <[email protected]>

Author: patnir41

packages/api-explorer/package.json

@@ -38,6 +38,7 @@
     "@styled-icons/styled-icon": "^10.6.3",
     "@testing-library/jest-dom": "^5.11.6",
     "@testing-library/react": "^11.2.2",
+    "@testing-library/react-hooks": "^8.0.1",
     "@testing-library/user-event": "^12.6.0",
     "@types/expect-puppeteer": "^4.4.6",
     "@types/jest-environment-puppeteer": "^4.4.1",
@@ -67,11 +68,11 @@
     "webpack-merge": "^5.7.3"
   },
   "dependencies": {
-    "@looker/extension-utils": "^0.1.13",
     "@looker/code-editor": "^0.1.23",
     "@looker/components": "^2.8.1",
     "@looker/components-date": "^2.4.1",
     "@looker/design-tokens": "^2.7.1",
+    "@looker/extension-utils": "^0.1.13",
     "@looker/icons": "^1.5.3",
     "@looker/redux": "0.0.0",
     "@looker/run-it": "^0.9.36",

packages/api-explorer/src/ApiExplorer.tsx

@@ -60,16 +60,15 @@ import { AppRouter } from './routes'
 import { apixFilesHost } from './utils/lodeUtils'
 import {
   useSettingActions,
-  useSettingStoreState,
   useLodeActions,
   useLodesStoreState,
   useSpecActions,
   useSpecStoreState,
   selectSpecs,
   selectCurrentSpec,
-  selectSdkLanguage,
+  useSettingStoreState,
 } from './state'
-import { getSpecKey, diffPath, useNavigation, findSdk, allAlias } from './utils'
+import { getSpecKey, diffPath, findSdk, useGlobalStoreSync } from './utils'
 
 export interface ApiExplorerProps {
   adaptor: IApixAdaptor
@@ -86,23 +85,21 @@ export const ApiExplorer: FC<ApiExplorerProps> = ({
   declarationsLodeUrl = `${apixFilesHost}/declarationsIndex.json`,
   headless = false,
 }) => {
-  const { initialized } = useSettingStoreState()
   useLodesStoreState()
   const { working, description } = useSpecStoreState()
   const specs = useSelector(selectSpecs)
   const spec = useSelector(selectCurrentSpec)
-  const selectedSdkLanguage = useSelector(selectSdkLanguage)
   const { initLodesAction } = useLodeActions()
+  const { initialized } = useSettingStoreState()
   const { initSettingsAction, setSearchPatternAction, setSdkLanguageAction } =
     useSettingActions()
   const { initSpecsAction, setCurrentSpecAction } = useSpecActions()
 
   const location = useLocation()
-  const navigate = useNavigation()
+  useGlobalStoreSync()
   const [hasNavigation, setHasNavigation] = useState(true)
   const toggleNavigation = (target?: boolean) =>
     setHasNavigation(target || !hasNavigation)
-  const searchParams = new URLSearchParams(location.search)
 
   const hasNavigationToggle = useCallback((e: MessageEvent<any>) => {
     if (e.origin === window.origin && e.data.action === 'toggle_sidebar') {
@@ -121,29 +118,6 @@ export const ApiExplorer: FC<ApiExplorerProps> = ({
     return () => unregisterEnvAdaptor()
   }, [])
 
-  useEffect(() => {
-    // reconcile local storage state with URL or vice versa
-    if (initialized) {
-      const sdkParam = searchParams.get('sdk') || ''
-      const sdk = findSdk(sdkParam)
-      const validSdkParam =
-        !sdkParam.localeCompare(sdk.alias, 'en', { sensitivity: 'base' }) ||
-        !sdkParam.localeCompare(sdk.language, 'en', { sensitivity: 'base' })
-      if (validSdkParam) {
-        // sync store with URL
-        setSdkLanguageAction({
-          sdkLanguage: sdk.language,
-        })
-      } else {
-        // sync URL with store
-        const { alias } = findSdk(selectedSdkLanguage)
-        navigate(location.pathname, {
-          sdk: alias === allAlias ? null : alias,
-        })
-      }
-    }
-  }, [initialized])
-
   useEffect(() => {
     const maybeSpec = location.pathname?.split('/')[1]
     if (spec && maybeSpec && maybeSpec !== diffPath && maybeSpec !== spec.key) {
@@ -153,6 +127,7 @@ export const ApiExplorer: FC<ApiExplorerProps> = ({
 
   useEffect(() => {
     if (!initialized) return
+    const searchParams = new URLSearchParams(location.search)
     const searchPattern = searchParams.get('s') || ''
     const sdkParam = searchParams.get('sdk') || 'all'
     const { language: sdkLanguage } = findSdk(sdkParam)

packages/api-explorer/src/components/DocMarkdown/DocMarkdown.tsx

@@ -40,7 +40,7 @@ interface DocMarkdownProps {
 
 export const DocMarkdown: FC<DocMarkdownProps> = ({ source, specKey }) => {
   const searchPattern = useSelector(selectSearchPattern)
-  const navigate = useNavigation()
+  const { navigate } = useNavigation()
 
   const linkClickHandler = (pathname: string, url: string) => {
     if (pathname.startsWith(`/${specKey}`)) {

packages/api-explorer/src/components/SelectorContainer/ApiSpecSelector.tsx

@@ -40,7 +40,7 @@ interface ApiSpecSelectorProps {
 
 export const ApiSpecSelector: FC<ApiSpecSelectorProps> = ({ spec }) => {
   const location = useLocation()
-  const navigate = useNavigation()
+  const { navigate } = useNavigation()
   const specs = useSelector(selectSpecs)
   const options = Object.entries(specs).map(([key, spec]) => ({
     value: key,

packages/api-explorer/src/components/SelectorContainer/SdkLanguageSelector.tsx

@@ -35,7 +35,7 @@ import { allSdkLanguageOptions } from './utils'
  * Allows the user to select their preferred SDK language
  */
 export const SdkLanguageSelector: FC = () => {
-  const navigate = useNavigation()
+  const { navigate } = useNavigation()
   const selectedSdkLanguage = useSelector(selectSdkLanguage)
   const [language, setLanguage] = useState(selectedSdkLanguage)
   const options = allSdkLanguageOptions()

packages/api-explorer/src/components/SelectorContainer/SelectorContainer.tsx

@@ -32,7 +32,7 @@ import { ChangeHistory } from '@styled-icons/material/ChangeHistory'
 import type { SpecItem } from '@looker/sdk-codegen'
 
 import { Link } from '../Link'
-import { diffPath } from '../../utils'
+import { diffPath, useNavigation } from '../../utils'
 import { SdkLanguageSelector } from './SdkLanguageSelector'
 import { ApiSpecSelector } from './ApiSpecSelector'
 
@@ -50,12 +50,12 @@ export const SelectorContainer: FC<SelectorContainerProps> = ({
   spec,
   ...spaceProps
 }) => {
-  const searchParams = new URLSearchParams(location.search)
+  const { buildPathWithGlobalParams } = useNavigation()
   return (
     <Space width="auto" {...spaceProps}>
       <SdkLanguageSelector />
       <ApiSpecSelector spec={spec} />
-      <Link to={`/${diffPath}/${spec.key}/?${searchParams.toString()}`}>
+      <Link to={buildPathWithGlobalParams(`/${diffPath}/${spec.key}/`)}>
         <IconButton
           toggle
           label="Compare Specifications"

packages/api-explorer/src/components/SideNav/SideNav.tsx

@@ -70,7 +70,7 @@ interface SideNavProps {
 
 export const SideNav: FC<SideNavProps> = ({ headless = false, spec }) => {
   const location = useLocation()
-  const navigate = useNavigation()
+  const { navigate, navigateWithGlobalParams } = useNavigation()
   const specKey = spec.key
   const tabNames = ['methods', 'types']
   const pathParts = location.pathname.split('/')
@@ -84,12 +84,12 @@ export const SideNav: FC<SideNavProps> = ({ headless = false, spec }) => {
     if (parts[1] === 'diff') {
       if (parts[3] !== tabNames[index]) {
         parts[3] = tabNames[index]
-        navigate(parts.join('/'))
+        navigateWithGlobalParams(parts.join('/'))
       }
     } else {
       if (parts[2] !== tabNames[index]) {
         parts[2] = tabNames[index]
-        navigate(parts.join('/'))
+        navigateWithGlobalParams(parts.join('/'))
       }
     }
   }

packages/api-explorer/src/components/SideNav/SideNavMethods.tsx

@@ -29,7 +29,7 @@ import styled from 'styled-components'
 import { Accordion2, Heading } from '@looker/components'
 import type { MethodList } from '@looker/sdk-codegen'
 import { useSelector } from 'react-redux'
-import { useLocation, useRouteMatch } from 'react-router-dom'
+import { useRouteMatch } from 'react-router-dom'
 import { useNavigation, highlightHTML, buildMethodPath } from '../../utils'
 import { Link } from '../Link'
 import { selectSearchPattern } from '../../state'
@@ -44,9 +44,7 @@ interface MethodsProps {
 
 export const SideNavMethods = styled(
   ({ className, methods, tag, specKey, defaultOpen = false }: MethodsProps) => {
-    const location = useLocation()
-    const navigate = useNavigation()
-    const searchParams = new URLSearchParams(location.search)
+    const { navigate, buildPathWithGlobalParams } = useNavigation()
     const searchPattern = useSelector(selectSearchPattern)
     const match = useRouteMatch<{ methodTag: string }>(
       `/:specKey/methods/:methodTag/:methodName?`
@@ -85,12 +83,9 @@ export const SideNavMethods = styled(
           {Object.values(methods).map((method) => (
             <li key={method.name}>
               <Link
-                to={`${buildMethodPath(
-                  specKey,
-                  tag,
-                  method.name,
-                  searchParams.toString()
-                )}`}
+                to={buildPathWithGlobalParams(
+                  buildMethodPath(specKey, tag, method.name)
+                )}
               >
                 {highlightHTML(searchPattern, method.summary)}
               </Link>

packages/api-explorer/src/components/SideNav/SideNavTypes.tsx

@@ -28,7 +28,7 @@ import React, { useEffect, useState } from 'react'
 import styled from 'styled-components'
 import { Accordion2, Heading } from '@looker/components'
 import type { TypeList } from '@looker/sdk-codegen'
-import { useLocation, useRouteMatch } from 'react-router-dom'
+import { useRouteMatch } from 'react-router-dom'
 import { useSelector } from 'react-redux'
 import { Link } from '../Link'
 import { highlightHTML, useNavigation, buildTypePath } from '../../utils'
@@ -44,9 +44,7 @@ interface TypesProps {
 
 export const SideNavTypes = styled(
   ({ className, types, tag, specKey, defaultOpen = false }: TypesProps) => {
-    const location = useLocation()
-    const navigate = useNavigation()
-    const searchParams = new URLSearchParams(location.search)
+    const { navigate, buildPathWithGlobalParams } = useNavigation()
     const searchPattern = useSelector(selectSearchPattern)
     const match = useRouteMatch<{ typeTag: string }>(
       `/:specKey/types/:typeTag/:typeName?`
@@ -85,12 +83,9 @@ export const SideNavTypes = styled(
           {Object.values(types).map((type) => (
             <li key={type.name}>
               <Link
-                to={`${buildTypePath(
-                  specKey,
-                  tag,
-                  type.name,
-                  searchParams.toString()
-                )}`}
+                to={buildPathWithGlobalParams(
+                  buildTypePath(specKey, tag, type.name)
+                )}
               >
                 {highlightHTML(searchPattern, type.name)}
               </Link>

packages/api-explorer/src/scenes/DiffScene/DiffScene.tsx

@@ -84,7 +84,7 @@ const validateParam = (specs: SpecList, specKey = '') => {
 
 export const DiffScene: FC<DiffSceneProps> = ({ specs, toggleNavigation }) => {
   const adaptor = getApixAdaptor()
-  const navigate = useNavigation()
+  const { navigate } = useNavigation()
   const spec = useSelector(selectCurrentSpec)
   const currentSpecKey = spec.key
   const match = useRouteMatch<{ l: string; r: string }>(`/${diffPath}/:l?/:r?`)

packages/api-explorer/src/scenes/DiffScene/DocDiff/DiffItem.tsx

@@ -59,7 +59,7 @@ export const DiffMethodLink: FC<DiffMethodLinkProps> = ({
   method,
   specKey,
 }) => {
-  const navigate = useNavigation()
+  const { navigate } = useNavigation()
 
   if (!method) return <Heading as="h4">{`Missing in ${specKey}`}</Heading>
 

packages/api-explorer/src/scenes/MethodScene/MethodScene.tsx

@@ -77,7 +77,7 @@ const showRunIt = async (adaptor: IEnvironmentAdaptor) => {
 export const MethodScene: FC<MethodSceneProps> = ({ api }) => {
   const adaptor = getApixAdaptor()
   const history = useHistory()
-  const navigate = useNavigation()
+  const { navigate } = useNavigation()
   const sdkLanguage = useSelector(selectSdkLanguage)
   const { specKey, methodTag, methodName } = useParams<MethodSceneParams>()
   const { value, toggle, setOn } = useToggle()

packages/api-explorer/src/scenes/MethodTagScene/MethodTagScene.spec.tsx

@@ -29,16 +29,28 @@ import { screen, waitFor } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 
 import { api } from '../../test-data'
-import { renderWithRouter } from '../../test-utils'
+import { renderWithRouterAndReduxProvider } from '../../test-utils'
 import { MethodTagScene } from './MethodTagScene'
 
 const opBtnNames = /ALL|GET|POST|PUT|PATCH|DELETE/
 
+const mockHistoryPush = jest.fn()
+jest.mock('react-router-dom', () => {
+  const ReactRouterDOM = jest.requireActual('react-router-dom')
+  return {
+    ...ReactRouterDOM,
+    useHistory: () => ({
+      push: mockHistoryPush,
+      location,
+    }),
+  }
+})
+
 describe('MethodTagScene', () => {
   Element.prototype.scrollTo = jest.fn()
 
   test('it renders operation buttons and all methods for a given method tag', () => {
-    renderWithRouter(
+    renderWithRouterAndReduxProvider(
       <Route path="/:specKey/methods/:methodTag">
         <MethodTagScene api={api} />
       </Route>,
@@ -62,7 +74,7 @@ describe('MethodTagScene', () => {
 
   test('it only renders operation buttons for operations that exist under that tag', () => {
     /** ApiAuth contains two POST methods and a DELETE method */
-    renderWithRouter(
+    renderWithRouterAndReduxProvider(
       <Route path="/:specKey/methods/:methodTag">
         <MethodTagScene api={api} />
       </Route>,
@@ -75,30 +87,29 @@ describe('MethodTagScene', () => {
     ).toHaveLength(3)
   })
 
-  test('it filters methods by operation type', async () => {
-    renderWithRouter(
+  test('it pushes filter to URL on toggle', async () => {
+    renderWithRouterAndReduxProvider(
       <Route path="/:specKey/methods/:methodTag">
         <MethodTagScene api={api} />
       </Route>,
       ['/3.1/methods/Look']
     )
-    const allLookMethods = /^\/look.*/
-    expect(screen.getAllByText(allLookMethods)).toHaveLength(7)
     /** Filter by GET operation */
     userEvent.click(screen.getByRole('button', { name: 'GET' }))
     await waitFor(() => {
-      expect(screen.getAllByText(allLookMethods)).toHaveLength(4)
+      expect(mockHistoryPush).toHaveBeenCalledWith({
+        pathname: location.pathname,
+        search: 't=get',
+      })
     })
     /** Filter by DELETE operation */
     userEvent.click(screen.getByRole('button', { name: 'DELETE' }))
     await waitFor(() => {
       // eslint-disable-next-line jest-dom/prefer-in-document
-      expect(screen.getAllByText(allLookMethods)).toHaveLength(1)
-    })
-    /** Restore original state */
-    userEvent.click(screen.getByRole('button', { name: 'ALL' }))
-    await waitFor(() => {
-      expect(screen.getAllByText(allLookMethods)).toHaveLength(7)
+      expect(mockHistoryPush).toHaveBeenCalledWith({
+        pathname: location.pathname,
+        search: 't=delete',
+      })
     })
   })
 })