feat: shareable URLs for library components and searches [FC-0076]

src/content-tags-drawer/ContentTagsDrawer.test.jsx

@@ -18,7 +18,7 @@ import {
 } from './data/api.mocks';
 import { getContentTaxonomyTagsApiUrl } from './data/api';
 
-const path = '/content/:contentId/*';
+const path = '/content/:contentId?/*';
 const mockOnClose = jest.fn();
 const mockSetBlockingSheet = jest.fn();
 const mockNavigate = jest.fn();

src/hooks.ts

@@ -1,6 +1,13 @@
-import { useEffect, useState } from 'react';
+import {
+  type Dispatch,
+  type SetStateAction,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
 import { history } from '@edx/frontend-platform';
-import { useLocation } from 'react-router-dom';
+import { useLocation, useSearchParams } from 'react-router-dom';
 
 export const useScrollToHashElement = ({ isLoading }: { isLoading: boolean }) => {
   const [elementWithHash, setElementWithHash] = useState<string | null>(null);
@@ -77,3 +84,124 @@ export const useLoadOnScroll = (
     return () => { };
   }, [hasNextPage, isFetchingNextPage, fetchNextPage]);
 };
+
+/**
+ * Types used by the useListHelpers and useStateWithUrlSearchParam hooks.
+ */
+export type FromStringFn<Type> = (value: string | null) => Type | undefined;
+export type ToStringFn<Type> = (value: Type | undefined) => string | undefined;
+
+/**
+ * Hook that stores/retrieves state variables using the URL search parameters.
+ *
+ * @param defaultValue: Type
+ *   Returned when no valid value is found in the url search parameter.
+ * @param paramName: name of the url search parameter to store this value in.
+ * @param fromString: returns the Type equivalent of the given string value,
+ *   or undefined if the value is invalid.
+ * @param toString: returns the string equivalent of the given Type value.
+ *   Return defaultValue to clear the url search paramName.
+ */
+export function useStateWithUrlSearchParam<Type>(
+  defaultValue: Type,
+  paramName: string,
+  fromString: FromStringFn<Type>,
+  toString: ToStringFn<Type>,
+): [value: Type, setter: Dispatch<SetStateAction<Type>>] {
+  // STATE WORKAROUND:
+  // If we use this hook to control multiple state parameters on the same
+  // page, we can run into state update issues. Because our state variables
+  // are actually stored in setSearchParams, and not in separate variables like
+  // useState would do, the searchParams "previous" state may not be updated
+  // for sequential calls to returnSetter in the same render loop (like in
+  // SearchManager's clearFilters).
+  //
+  // One workaround could be to use window.location.search as the "previous"
+  // value when returnSetter constructs the new URLSearchParams. This works
+  // fine with BrowserRouter, but our test suite uses MemoryRouter, and that
+  // router doesn't store URL search params, cf
+  // https://github.com/remix-run/react-router/issues/9757
+  //
+  // So instead, we maintain a reference to the current useLocation()
+  // object, and use its search params as the "previous" value when
+  // initializing URLSearchParams.
+  const location = useLocation();
+  const locationRef = useRef(location);
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const returnValue: Type = fromString(searchParams.get(paramName)) ?? defaultValue;
+  // Update the url search parameter using:
+  type ReturnSetterParams = (
+    // a Type value
+    value?: Type
+    // or a function that returns a Type from the previous returnValue
+    | ((value: Type) => Type)
+  ) => void;
+  const returnSetter: Dispatch<SetStateAction<Type>> = useCallback<ReturnSetterParams>((value) => {
+    setSearchParams((/* prev */) => {
+      const useValue = value instanceof Function ? value(returnValue) : value;
+      const paramValue = toString(useValue);
+      const newSearchParams = new URLSearchParams(locationRef.current.search);
+      // If the provided value was invalid (toString returned undefined)
+      // or the same as the defaultValue, remove it from the search params.
+      if (paramValue === undefined || paramValue === defaultValue) {
+        newSearchParams.delete(paramName);
+      } else {
+        newSearchParams.set(paramName, paramValue);
+      }
+
+      // Update locationRef
+      locationRef.current.search = newSearchParams.toString();
+
+      return newSearchParams;
+    }, { replace: true });
+  }, [returnValue, setSearchParams]);
+
+  // Return the computed value and wrapped set state function
+  return [returnValue, returnSetter];
+}
+
+/**
+ * Helper hook for useStateWithUrlSearchParam<Type[]>.
+ *
+ * useListHelpers provides toString and fromString handlers that can:
+ * - split/join a list of values using a separator string, and
+ * - validate each value using the provided functions, omitting any invalid values.
+ *
+ * @param fromString
+ *   Serialize a string to a Type, or undefined if not valid.
+ * @param toString
+ *   Deserialize a Type to a string.
+ * @param separator : string to use when splitting/joining the types.
+ *   Defaults value is ','.
+ */
+export function useListHelpers<Type>({
+  fromString,
+  toString,
+  separator = ',',
+}: {
+  fromString: FromStringFn<Type>,
+  toString: ToStringFn<Type>,
+  separator?: string;
+}): [ FromStringFn<Type[]>, ToStringFn<Type[]> ] {
+  const isType = (item: Type | undefined): item is Type => item !== undefined;
+
+  // Split the given string with separator,
+  // and convert the parts to a list of Types, omiting any invalid Types.
+  const fromStringToList : FromStringFn<Type[]> = (value: string) => (
+    value
+      ? value.split(separator).map(fromString).filter(isType)
+      : []
+  );
+  // Convert an array of Types to strings and join with separator.
+  // Returns undefined if the given list contains no valid Types.
+  const fromListToString : ToStringFn<Type[]> = (value: Type[]) => {
+    const stringValues = value.map(toString).filter((val) => val !== undefined);
+    return (
+      stringValues && stringValues.length
+        ? stringValues.join(separator)
+        : undefined
+    );
+  };
+  return [fromStringToList, fromListToString];
+}

src/library-authoring/LibraryAuthoringPage.test.tsx

@@ -431,27 +431,23 @@ describe('<LibraryAuthoringPage />', () => {
     // Click on the first collection
     fireEvent.click((await screen.findByText('Collection 1')));
 
-    const sidebar = screen.getByTestId('library-sidebar');
-
-    const { getByRole } = within(sidebar);
-
     // Click on the Details tab
-    fireEvent.click(getByRole('tab', { name: 'Details' }));
+    fireEvent.click(screen.getByRole('tab', { name: 'Details' }));
 
     // Change to a component
     fireEvent.click((await screen.findAllByText('Introduction to Testing'))[0]);
 
     // Check that the Details tab is still selected
-    expect(getByRole('tab', { name: 'Details' })).toHaveAttribute('aria-selected', 'true');
+    expect(screen.getByRole('tab', { name: 'Details' })).toHaveAttribute('aria-selected', 'true');
 
     // Click on the Previews tab
-    fireEvent.click(getByRole('tab', { name: 'Preview' }));
+    fireEvent.click(screen.getByRole('tab', { name: 'Preview' }));
 
     // Switch back to the collection
     fireEvent.click((await screen.findByText('Collection 1')));
 
     // The Manage (default) tab should be selected because the collection does not have a Preview tab
-    expect(getByRole('tab', { name: 'Manage' })).toHaveAttribute('aria-selected', 'true');
+    expect(screen.getByRole('tab', { name: 'Manage' })).toHaveAttribute('aria-selected', 'true');
   });
 
   it('can filter by capa problem type', async () => {

src/library-authoring/LibraryAuthoringPage.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import { Helmet } from 'react-helmet';
 import classNames from 'classnames';
 import { StudioFooter } from '@edx/frontend-component-footer';
@@ -16,12 +16,7 @@ import {
   Tabs,
 } from '@openedx/paragon';
 import { Add, ArrowBack, InfoOutline } from '@openedx/paragon/icons';
-import {
-  Link,
-  useLocation,
-  useNavigate,
-  useSearchParams,
-} from 'react-router-dom';
+import { Link } from 'react-router-dom';
 
 import Loading from '../generic/Loading';
 import SubHeader from '../generic/sub-header/SubHeader';
@@ -36,11 +31,12 @@ import {
   SearchKeywordsField,
   SearchSortWidget,
 } from '../search-manager';
-import LibraryContent, { ContentType } from './LibraryContent';
+import LibraryContent from './LibraryContent';
 import { LibrarySidebar } from './library-sidebar';
 import { useComponentPickerContext } from './common/context/ComponentPickerContext';
 import { useLibraryContext } from './common/context/LibraryContext';
 import { SidebarBodyComponentId, useSidebarContext } from './common/context/SidebarContext';
+import { ContentType, useLibraryRoutes } from './routes';
 
 import messages from './messages';
 
@@ -51,7 +47,7 @@ const HeaderActions = () => {
 
   const {
     openAddContentSidebar,
-    openInfoSidebar,
+    openLibrarySidebar,
     closeLibrarySidebar,
     sidebarComponentInfo,
   } = useSidebarContext();
@@ -60,13 +56,19 @@ const HeaderActions = () => {
 
   const infoSidebarIsOpen = sidebarComponentInfo?.type === SidebarBodyComponentId.Info;
 
-  const handleOnClickInfoSidebar = () => {
+  const { navigateTo } = useLibraryRoutes();
+  const handleOnClickInfoSidebar = useCallback(() => {
     if (infoSidebarIsOpen) {
       closeLibrarySidebar();
     } else {
-      openInfoSidebar();
+      openLibrarySidebar();
     }
-  };
+
+    if (!componentPickerMode) {
+      // Reset URL to library home
+      navigateTo();
+    }
+  }, [navigateTo, sidebarComponentInfo, closeLibrarySidebar, openLibrarySidebar]);
 
   return (
     <div className="header-actions">
@@ -124,8 +126,6 @@ interface LibraryAuthoringPageProps {
 
 const LibraryAuthoringPage = ({ returnToLibrarySelection }: LibraryAuthoringPageProps) => {
   const intl = useIntl();
-  const location = useLocation();
-  const navigate = useNavigate();
 
   const {
     isLoadingPage: isLoadingStudioHome,
@@ -139,29 +139,41 @@ const LibraryAuthoringPage = ({ returnToLibrarySelection }: LibraryAuthoringPage
     libraryData,
     isLoadingLibraryData,
     showOnlyPublished,
+    componentId,
+    collectionId,
   } = useLibraryContext();
   const { openInfoSidebar, sidebarComponentInfo } = useSidebarContext();
 
+  const { insideCollections, insideComponents, navigateTo } = useLibraryRoutes();
+
+  // The activeKey determines the currently selected tab.
   const [activeKey, setActiveKey] = useState<ContentType>(ContentType.home);
+  const getActiveKey = () => {
+    if (insideCollections) {
+      return ContentType.collections;
+    }
+    if (insideComponents) {
+      return ContentType.components;
+    }
+    return ContentType.home;
+  };
 
   useEffect(() => {
-    const currentPath = location.pathname.split('/').pop();
+    const contentType = getActiveKey();
 
-    if (componentPickerMode || currentPath === libraryId || currentPath === '') {
+    if (componentPickerMode) {
       setActiveKey(ContentType.home);
-    } else if (currentPath && currentPath in ContentType) {
-      setActiveKey(ContentType[currentPath] || ContentType.home);
+    } else {
+      setActiveKey(contentType);
     }
   }, []);
 
   useEffect(() => {
     if (!componentPickerMode) {
-      openInfoSidebar();
+      openInfoSidebar(componentId, collectionId);
     }
   }, []);
 
-  const [searchParams] = useSearchParams();
-
   if (isLoadingLibraryData) {
     return <Loading />;
   }
@@ -181,10 +193,7 @@ const LibraryAuthoringPage = ({ returnToLibrarySelection }: LibraryAuthoringPage
   const handleTabChange = (key: ContentType) => {
     setActiveKey(key);
     if (!componentPickerMode) {
-      navigate({
-        pathname: key,
-        search: searchParams.toString(),
-      });
+      navigateTo({ contentType: key });
     }
   };
 

src/library-authoring/LibraryContent.tsx

@@ -6,15 +6,10 @@ import { useLibraryContext } from './common/context/LibraryContext';
 import { useSidebarContext } from './common/context/SidebarContext';
 import CollectionCard from './components/CollectionCard';
 import ComponentCard from './components/ComponentCard';
+import { ContentType } from './routes';
 import { useLoadOnScroll } from '../hooks';
 import messages from './collections/messages';
 
-export enum ContentType {
-  home = '',
-  components = 'components',
-  collections = 'collections',
-}
-
 /**
  * Library Content to show content grid
  *