@docusaurus/theme-common 0.0.0-5892 → 0.0.0-5898

package/lib/index.d.ts

@@ -27,6 +27,7 @@ export { duplicates, uniq } from './utils/jsUtils';
 export { usePrismTheme } from './hooks/usePrismTheme';
 export { useDocsPreferredVersion } from './contexts/docsPreferredVersion';
 export { processAdmonitionProps } from './utils/admonitionUtils';
+export { useHistorySelector, useQueryString, useQueryStringList, useClearQueryString, } from './utils/historyUtils';
 export { SkipToContentFallbackId, SkipToContentLink, } from './utils/skipToContentUtils';
 export { UnlistedBannerTitle, UnlistedBannerMessage, UnlistedMetadata, } from './utils/unlistedUtils';
 export { ErrorBoundaryTryAgainButton, ErrorBoundaryError, ErrorBoundaryErrorMessageFallback, ErrorCauseBoundary, } from './utils/errorBoundaryUtils';

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EACL,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAC,OAAO,IAAI,eAAe,EAAC,MAAM,8BAA8B,CAAC;AAExE,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAC,0BAA0B,EAAC,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EACL,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EAAC,cAAc,EAAE,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAErE,OAAO,EAAC,eAAe,EAAC,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAC,oBAAoB,EAAC,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EACL,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAC,YAAY,EAAE,qBAAqB,EAAC,MAAM,uBAAuB,CAAC;AAE1E,OAAO,EAAC,YAAY,EAAE,KAAK,SAAS,EAAC,MAAM,sBAAsB,CAAC;AAElE,OAAO,EACL,yBAAyB,EACzB,KAAK,4BAA4B,GAClC,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAOpD,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAC,wBAAwB,EAAC,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAC,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAC,UAAU,EAAE,IAAI,EAAC,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EAAC,uBAAuB,EAAC,MAAM,iCAAiC,CAAC;AAExE,OAAO,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAE/D,OAAO,EACL,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,iCAAiC,EACjC,kBAAkB,GACnB,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EACL,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAC,OAAO,IAAI,eAAe,EAAC,MAAM,8BAA8B,CAAC;AAExE,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAC,0BAA0B,EAAC,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EACL,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EAAC,cAAc,EAAE,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAErE,OAAO,EAAC,eAAe,EAAC,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAC,oBAAoB,EAAC,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EACL,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAC,YAAY,EAAE,qBAAqB,EAAC,MAAM,uBAAuB,CAAC;AAE1E,OAAO,EAAC,YAAY,EAAE,KAAK,SAAS,EAAC,MAAM,sBAAsB,CAAC;AAElE,OAAO,EACL,yBAAyB,EACzB,KAAK,4BAA4B,GAClC,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAOpD,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAC,wBAAwB,EAAC,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAC,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAC,UAAU,EAAE,IAAI,EAAC,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EAAC,uBAAuB,EAAC,MAAM,iCAAiC,CAAC;AAExE,OAAO,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAE/D,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,iCAAiC,EACjC,kBAAkB,GACnB,MAAM,4BAA4B,CAAC"}

package/lib/index.js

@@ -34,6 +34,7 @@ export { duplicates, uniq } from './utils/jsUtils';
 export { usePrismTheme } from './hooks/usePrismTheme';
 export { useDocsPreferredVersion } from './contexts/docsPreferredVersion';
 export { processAdmonitionProps } from './utils/admonitionUtils';
+export { useHistorySelector, useQueryString, useQueryStringList, useClearQueryString, } from './utils/historyUtils';
 export { SkipToContentFallbackId, SkipToContentLink, } from './utils/skipToContentUtils';
 export { UnlistedBannerTitle, UnlistedBannerMessage, UnlistedMetadata, } from './utils/unlistedUtils';
 export { ErrorBoundaryTryAgainButton, ErrorBoundaryError, ErrorBoundaryErrorMessageFallback, ErrorCauseBoundary, } from './utils/errorBoundaryUtils';

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AAEH,OAAO,EACL,cAAc,GAYf,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAC,OAAO,IAAI,eAAe,EAAC,MAAM,8BAA8B,CAAC;AAExE,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAC,0BAA0B,EAAC,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EACL,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EAAC,cAAc,EAAE,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAErE,OAAO,EAAC,eAAe,EAAC,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAC,oBAAoB,EAAC,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EACL,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAC,YAAY,EAAE,qBAAqB,EAAC,MAAM,uBAAuB,CAAC;AAE1E,OAAO,EAAC,YAAY,EAAiB,MAAM,sBAAsB,CAAC;AAElE,OAAO,EACL,yBAAyB,GAE1B,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEpD;;;GAGG;AAEH,OAAO,EACL,sBAAsB,EACtB,iBAAiB,GAElB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAC,wBAAwB,EAAC,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAC,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAC,UAAU,EAAE,IAAI,EAAC,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EAAC,uBAAuB,EAAC,MAAM,iCAAiC,CAAC;AAExE,OAAO,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAE/D,OAAO,EACL,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,iCAAiC,EACjC,kBAAkB,GACnB,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AAEH,OAAO,EACL,cAAc,GAYf,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAC,OAAO,IAAI,eAAe,EAAC,MAAM,8BAA8B,CAAC;AAExE,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAC,0BAA0B,EAAC,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EACL,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EAAC,cAAc,EAAE,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAErE,OAAO,EAAC,eAAe,EAAC,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAC,oBAAoB,EAAC,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EACL,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAC,YAAY,EAAE,qBAAqB,EAAC,MAAM,uBAAuB,CAAC;AAE1E,OAAO,EAAC,YAAY,EAAiB,MAAM,sBAAsB,CAAC;AAElE,OAAO,EACL,yBAAyB,GAE1B,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEpD;;;GAGG;AAEH,OAAO,EACL,sBAAsB,EACtB,iBAAiB,GAElB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAC,wBAAwB,EAAC,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAC,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAC,UAAU,EAAE,IAAI,EAAC,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EAAC,uBAAuB,EAAC,MAAM,iCAAiC,CAAC;AAExE,OAAO,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAE/D,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,iCAAiC,EACjC,kBAAkB,GACnB,MAAM,4BAA4B,CAAC"}

package/lib/utils/historyUtils.d.ts

@@ -24,11 +24,14 @@ export declare function useHistorySelector<Value>(selector: (history: History<un
  * @param key
  */
 export declare function useQueryStringValue(key: string | null): string | null;
-export declare function useQueryStringKeySetter(): (key: string, newValue: string | null, options?: {
-    push: boolean;
-}) => void;
-export declare function useQueryString(key: string): [string, (newValue: string, options?: {
+export declare function useQueryString(key: string): [string, (newValue: string | null, options?: {
     push: boolean;
 }) => void];
+type ListUpdate = string[] | ((oldValues: string[]) => string[]);
+type ListUpdateFunction = (update: ListUpdate, options?: {
+    push: boolean;
+}) => void;
+export declare function useQueryStringList(key: string): [string[], ListUpdateFunction];
+export declare function useClearQueryString(): () => void;
 export {};
 //# sourceMappingURL=historyUtils.d.ts.map

package/lib/utils/historyUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"historyUtils.d.ts","sourceRoot":"","sources":["../../src/utils/historyUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAC,MAAM,SAAS,CAAC;AAEvD,KAAK,mBAAmB,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,KAAK,CAAC;AAiBhF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CASvE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EACtC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,KAAK,GAC7C,KAAK,CAOP;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAOrE;AAED,wBAAgB,uBAAuB,IAAI,CACzC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,OAAO,CAAC,EAAE;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,KACtB,IAAI,CAiBR;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,GACV,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,KAAK,IAAI,CAAC,CAYjE"}
+{"version":3,"file":"historyUtils.d.ts","sourceRoot":"","sources":["../../src/utils/historyUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAC,MAAM,SAAS,CAAC;AAEvD,KAAK,mBAAmB,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,KAAK,CAAC;AAiBhF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CASvE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EACtC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,KAAK,GAC7C,KAAK,CAOP;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAOrE;AAuBD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,GACV,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,KAAK,IAAI,CAAC,CAIxE;AAaD,KAAK,UAAU,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC,CAAC;AACjE,KAAK,kBAAkB,GAAG,CACxB,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,KACtB,IAAI,CAAC;AAuBV,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,GACV,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC,CAIhC;AAED,wBAAgB,mBAAmB,IAAI,MAAM,IAAI,CAOhD"}

package/lib/utils/historyUtils.js

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { useCallback, useEffect, useSyncExternalStore } from 'react';
+import { useCallback, useEffect, useMemo, useSyncExternalStore } from 'react';
 import { useHistory } from '@docusaurus/router';
 import { useEvent } from './reactUtils';
 /**
@@ -56,9 +56,9 @@ export function useQueryStringValue(key) {
         return new URLSearchParams(history.location.search).get(key);
     });
 }
-export function useQueryStringKeySetter() {
+function useQueryStringUpdater(key) {
     const history = useHistory();
-    return useCallback((key, newValue, options) => {
+    return useCallback((newValue, options) => {
         const searchParams = new URLSearchParams(history.location.search);
         if (newValue) {
             searchParams.set(key, newValue);
@@ -66,20 +66,54 @@ export function useQueryStringKeySetter() {
         else {
             searchParams.delete(key);
         }
-        const updaterFn = options?.push ? history.push : history.replace;
-        updaterFn({
+        const updateHistory = options?.push ? history.push : history.replace;
+        updateHistory({
             search: searchParams.toString(),
         });
-    }, [history]);
+    }, [key, history]);
 }
 export function useQueryString(key) {
     const value = useQueryStringValue(key) ?? '';
-    const setQueryString = useQueryStringKeySetter();
-    return [
-        value,
-        useCallback((newValue, options) => {
-            setQueryString(key, newValue, options);
-        }, [setQueryString, key]),
-    ];
+    const update = useQueryStringUpdater(key);
+    return [value, update];
+}
+function useQueryStringListValues(key) {
+    // Unfortunately we can't just use searchParams.getAll(key) in the selector
+    // It would create a new array every time and lead to an infinite loop...
+    // The selector has to return a primitive/string value to avoid that...
+    const arrayJsonString = useHistorySelector((history) => {
+        const values = new URLSearchParams(history.location.search).getAll(key);
+        return JSON.stringify(values);
+    });
+    return useMemo(() => JSON.parse(arrayJsonString), [arrayJsonString]);
+}
+function useQueryStringListUpdater(key) {
+    const history = useHistory();
+    const setValues = useCallback((update, options) => {
+        const searchParams = new URLSearchParams(history.location.search);
+        const newValues = Array.isArray(update)
+            ? update
+            : update(searchParams.getAll(key));
+        searchParams.delete(key);
+        newValues.forEach((v) => searchParams.append(key, v));
+        const updateHistory = options?.push ? history.push : history.replace;
+        updateHistory({
+            search: searchParams.toString(),
+        });
+    }, [history, key]);
+    return setValues;
+}
+export function useQueryStringList(key) {
+    const values = useQueryStringListValues(key);
+    const setValues = useQueryStringListUpdater(key);
+    return [values, setValues];
+}
+export function useClearQueryString() {
+    const history = useHistory();
+    return useCallback(() => {
+        history.replace({
+            search: undefined,
+        });
+    }, [history]);
 }
 //# sourceMappingURL=historyUtils.js.map

package/lib/utils/historyUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"historyUtils.js","sourceRoot":"","sources":["../../src/utils/historyUtils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"historyUtils.js","sourceRoot":"","sources":["../../src/utils/historyUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAC,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,oBAAoB,EAAC,MAAM,OAAO,CAAC;AAC5E,OAAO,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAC,QAAQ,EAAC,MAAM,cAAc,CAAC;AAMtC;;;;GAIG;AACH,SAAS,uBAAuB,CAAC,OAA4B;IAC3D,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACxC,SAAS;IACP,kFAAkF;IAClF,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,EAC1E,CAAC,OAAO,EAAE,aAAa,CAAC,CACzB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAA4B;IAC/D,uBAAuB,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;QAC3C,IAAI,MAAM,KAAK,KAAK,EAAE;YACpB,kDAAkD;YAClD,OAAO,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;SAClC;QACD,uCAAuC;QACvC,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAA8C;IAE9C,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,OAAO,oBAAoB,CACzB,OAAO,CAAC,MAAM,EACd,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,EACvB,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CACxB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAkB;IACpD,OAAO,kBAAkB,CAAC,CAAC,OAAO,EAAE,EAAE;QACpC,IAAI,GAAG,KAAK,IAAI,EAAE;YAChB,OAAO,IAAI,CAAC;SACb;QACD,OAAO,IAAI,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,qBAAqB,CAC5B,GAAW;IAEX,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,OAAO,WAAW,CAChB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE;QACpB,MAAM,YAAY,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAClE,IAAI,QAAQ,EAAE;YACZ,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;SACjC;aAAM;YACL,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;SAC1B;QACD,MAAM,aAAa,GAAG,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;QACrE,aAAa,CAAC;YACZ,MAAM,EAAE,YAAY,CAAC,QAAQ,EAAE;SAChC,CAAC,CAAC;IACL,CAAC,EACD,CAAC,GAAG,EAAE,OAAO,CAAC,CACf,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,GAAW;IAEX,MAAM,KAAK,GAAG,mBAAmB,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IAC7C,MAAM,MAAM,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC1C,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,wBAAwB,CAAC,GAAW;IAC3C,2EAA2E;IAC3E,yEAAyE;IACzE,uEAAuE;IACvE,MAAM,eAAe,GAAG,kBAAkB,CAAC,CAAC,OAAO,EAAE,EAAE;QACrD,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxE,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC;AACvE,CAAC;AAQD,SAAS,yBAAyB,CAAC,GAAW;IAC5C,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,SAAS,GAAuB,WAAW,CAC/C,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE;QAClB,MAAM,YAAY,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAClE,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YACrC,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACrC,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;QAEtD,MAAM,aAAa,GAAG,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;QACrE,aAAa,CAAC;YACZ,MAAM,EAAE,YAAY,CAAC,QAAQ,EAAE;SAChC,CAAC,CAAC;IACL,CAAC,EACD,CAAC,OAAO,EAAE,GAAG,CAAC,CACf,CAAC;IACF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,GAAW;IAEX,MAAM,MAAM,GAAG,wBAAwB,CAAC,GAAG,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,yBAAyB,CAAC,GAAG,CAAC,CAAC;IACjD,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,OAAO,WAAW,CAAC,GAAG,EAAE;QACtB,OAAO,CAAC,OAAO,CAAC;YACd,MAAM,EAAE,SAAS;SAClB,CAAC,CAAC;IACL,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-common",
-  "version": "0.0.0-5892",
+  "version": "0.0.0-5898",
   "description": "Common code for Docusaurus themes.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -30,13 +30,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/mdx-loader": "0.0.0-5892",
-    "@docusaurus/module-type-aliases": "0.0.0-5892",
-    "@docusaurus/plugin-content-blog": "0.0.0-5892",
-    "@docusaurus/plugin-content-docs": "0.0.0-5892",
-    "@docusaurus/plugin-content-pages": "0.0.0-5892",
-    "@docusaurus/utils": "0.0.0-5892",
-    "@docusaurus/utils-common": "0.0.0-5892",
+    "@docusaurus/mdx-loader": "0.0.0-5898",
+    "@docusaurus/module-type-aliases": "0.0.0-5898",
+    "@docusaurus/plugin-content-blog": "0.0.0-5898",
+    "@docusaurus/plugin-content-docs": "0.0.0-5898",
+    "@docusaurus/plugin-content-pages": "0.0.0-5898",
+    "@docusaurus/utils": "0.0.0-5898",
+    "@docusaurus/utils-common": "0.0.0-5898",
     "@types/history": "^4.7.11",
     "@types/react": "*",
     "@types/react-router-config": "*",
@@ -47,8 +47,8 @@
     "utility-types": "^3.10.0"
   },
   "devDependencies": {
-    "@docusaurus/core": "0.0.0-5892",
-    "@docusaurus/types": "0.0.0-5892",
+    "@docusaurus/core": "0.0.0-5898",
+    "@docusaurus/types": "0.0.0-5898",
     "fs-extra": "^11.1.1",
     "lodash": "^4.17.21",
     "schema-dts": "^1.1.2"
@@ -60,5 +60,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "6727d4eeec677bd7ff3c4f9e23b3b125f30b17f9"
+  "gitHead": "9ae3e7f8841dc5ae7c07b084c48c1e80d4d355fe"
 }

package/src/index.ts

@@ -98,6 +98,13 @@ export {useDocsPreferredVersion} from './contexts/docsPreferredVersion';
 
 export {processAdmonitionProps} from './utils/admonitionUtils';
 
+export {
+  useHistorySelector,
+  useQueryString,
+  useQueryStringList,
+  useClearQueryString,
+} from './utils/historyUtils';
+
 export {
   SkipToContentFallbackId,
   SkipToContentLink,

package/src/utils/historyUtils.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useCallback, useEffect, useSyncExternalStore} from 'react';
+import {useCallback, useEffect, useMemo, useSyncExternalStore} from 'react';
 import {useHistory} from '@docusaurus/router';
 import {useEvent} from './reactUtils';
 
@@ -74,41 +74,86 @@ export function useQueryStringValue(key: string | null): string | null {
   });
 }
 
-export function useQueryStringKeySetter(): (
+function useQueryStringUpdater(
   key: string,
-  newValue: string | null,
-  options?: {push: boolean},
-) => void {
+): (newValue: string | null, options?: {push: boolean}) => void {
   const history = useHistory();
   return useCallback(
-    (key, newValue, options) => {
+    (newValue, options) => {
       const searchParams = new URLSearchParams(history.location.search);
       if (newValue) {
         searchParams.set(key, newValue);
       } else {
         searchParams.delete(key);
       }
-      const updaterFn = options?.push ? history.push : history.replace;
-      updaterFn({
+      const updateHistory = options?.push ? history.push : history.replace;
+      updateHistory({
         search: searchParams.toString(),
       });
     },
-    [history],
+    [key, history],
   );
 }
 
 export function useQueryString(
   key: string,
-): [string, (newValue: string, options?: {push: boolean}) => void] {
+): [string, (newValue: string | null, options?: {push: boolean}) => void] {
   const value = useQueryStringValue(key) ?? '';
-  const setQueryString = useQueryStringKeySetter();
-  return [
-    value,
-    useCallback(
-      (newValue: string, options) => {
-        setQueryString(key, newValue, options);
-      },
-      [setQueryString, key],
-    ),
-  ];
+  const update = useQueryStringUpdater(key);
+  return [value, update];
+}
+
+function useQueryStringListValues(key: string): string[] {
+  // Unfortunately we can't just use searchParams.getAll(key) in the selector
+  // It would create a new array every time and lead to an infinite loop...
+  // The selector has to return a primitive/string value to avoid that...
+  const arrayJsonString = useHistorySelector((history) => {
+    const values = new URLSearchParams(history.location.search).getAll(key);
+    return JSON.stringify(values);
+  });
+  return useMemo(() => JSON.parse(arrayJsonString), [arrayJsonString]);
+}
+
+type ListUpdate = string[] | ((oldValues: string[]) => string[]);
+type ListUpdateFunction = (
+  update: ListUpdate,
+  options?: {push: boolean},
+) => void;
+
+function useQueryStringListUpdater(key: string): ListUpdateFunction {
+  const history = useHistory();
+  const setValues: ListUpdateFunction = useCallback(
+    (update, options) => {
+      const searchParams = new URLSearchParams(history.location.search);
+      const newValues = Array.isArray(update)
+        ? update
+        : update(searchParams.getAll(key));
+      searchParams.delete(key);
+      newValues.forEach((v) => searchParams.append(key, v));
+
+      const updateHistory = options?.push ? history.push : history.replace;
+      updateHistory({
+        search: searchParams.toString(),
+      });
+    },
+    [history, key],
+  );
+  return setValues;
+}
+
+export function useQueryStringList(
+  key: string,
+): [string[], ListUpdateFunction] {
+  const values = useQueryStringListValues(key);
+  const setValues = useQueryStringListUpdater(key);
+  return [values, setValues];
+}
+
+export function useClearQueryString(): () => void {
+  const history = useHistory();
+  return useCallback(() => {
+    history.replace({
+      search: undefined,
+    });
+  }, [history]);
 }