scoobie 14.3.7 → 14.4.0

package/README.md

@@ -345,11 +345,12 @@ export const MyFirstInlineCode = () => (
 
 Render an internal link with the same opinions as our [MdxProvider](#mdxprovider):
 
-- Internal links pass through the `v` and `v-panel` URL parameters for UI version switching
+- Internal links pass through the `v` or [ScoobieLinkProvider] URL parameters for UI version switching
 
 Unlike [SmartTextLink](#smarttextlink), this is not bound to a parent [Text] as it has no underlying [TextLink].
 It can be used to make complex components navigable rather than just sections of text.
 
+[scoobielinkprovider]: #scoobielinkprovider
 [text]: https://seek-oss.github.io/braid-design-system/components/Text/
 [textlink]: https://seek-oss.github.io/braid-design-system/components/TextLink/
 
@@ -398,7 +399,7 @@ export const Component = () => (
 
 Render all underlying links as follows:
 
-- Internal links pass through the `v` and `v-panel` URL parameters for UI version switching
+- Internal links pass through the `v` or [ScoobieLinkProvider] URL parameters for UI version switching
 - External links open in a new tab
 - Links with a [`download` attribute] prompt the user with a file download
 
@@ -421,6 +422,25 @@ export const Component = () => (
 
 [braidprovider]: https://seek-oss.github.io/braid-design-system/components/BraidProvider
 
+### ScoobieLinkProvider
+
+Propagate a custom set of URL parameters on internal links.
+
+```tsx
+import { BraidProvider, TextLink } from 'braid-design-system';
+import apacTheme from 'braid-design-system/themes/apac';
+import React from 'react';
+import { ScoobieLink } from 'scoobie';
+
+export const Component = () => (
+  <ScoobieLinkProvider propagateSearchParams={['debug', 'v']}>
+    <BraidProvider linkComponent={ScoobieLink} theme={apacTheme}>
+      <TextLink href="/root-relative">Internal link</TextLink>
+    </BraidProvider>
+  </ScoobieLinkProvider>
+);
+```
+
 ### SmartTextLink
 
 Render a text link with the same opinions as our [MdxProvider](#mdxprovider):

package/package.json

@@ -4,7 +4,7 @@
   "license": "MIT",
   "main": "src/index.ts",
   "sideEffects": false,
-  "version": "14.3.7",
+  "version": "14.4.0",
   "dependencies": {
     "@capsizecss/core": "^3.0.0",
     "@mdx-js/loader": "^1.6.22",

package/src/components/InternalLink.tsx

@@ -4,6 +4,8 @@ import { NavLink, useLocation } from 'react-router-dom';
 
 import { parseInternalHref } from '../private/url';
 
+import { useScoobieLink } from './ScoobieLinkProvider';
+
 import * as styles from './InternalLink.css';
 
 interface Props
@@ -18,7 +20,12 @@ export const InternalLink = forwardRef<HTMLAnchorElement, Props>(
   ({ className, href, reset = true, state, ...restProps }, ref) => {
     const location = useLocation();
 
-    const to = { ...parseInternalHref(href, location), state };
+    const { propagateSearchParams } = useScoobieLink();
+
+    const to = {
+      ...parseInternalHref(href, location, propagateSearchParams),
+      state,
+    };
 
     return (
       <NavLink

package/src/components/ScoobieLinkProvider.tsx

@@ -0,0 +1,29 @@
+import React, { type ReactNode, createContext, useContext } from 'react';
+
+interface ScoobieLinkContext {
+  propagateSearchParams: string[];
+}
+
+const ctx = createContext<ScoobieLinkContext>({
+  propagateSearchParams: ['v'],
+});
+
+interface ScoobieLinkProviderProps {
+  children: ReactNode;
+
+  /**
+   * The search parameters to propagate on internal links.
+   *
+   * This defaults to `['v']` in the absence of a `ScoobieLinkProvider`.
+   */
+  propagateSearchParams: string[];
+}
+
+export const ScoobieLinkProvider = ({
+  children,
+  ...value
+}: ScoobieLinkProviderProps) => {
+  <ctx.Provider value={value}>{children}</ctx.Provider>;
+};
+
+export const useScoobieLink = () => useContext(ctx);

package/src/index.ts

@@ -5,6 +5,7 @@ export { InlineCode } from './components/InlineCode';
 export { InternalLink } from './components/InternalLink';
 export { MdxProvider } from './components/MdxProvider';
 export { ScoobieLink } from './components/ScoobieLink';
+export { ScoobieLinkProvider } from './components/ScoobieLinkProvider';
 export { SmartTextLink } from './components/SmartTextLink';
 export { Table } from './components/Table';
 export { TableRow } from './components/TableRow';

package/src/private/url.ts

@@ -1,14 +1,5 @@
 const EXAMPLE_BASE_URL = 'https://example.com';
 
-const parseVersionParams = (search: string) => {
-  const urlSearchParams = new URLSearchParams(search);
-
-  return {
-    v: urlSearchParams.get('v'),
-    vPanel: urlSearchParams.get('v-panel'),
-  };
-};
-
 const hrefToUrl = (href: string, pathname: string) => {
   if (href.startsWith('/')) {
     return new URL(`${EXAMPLE_BASE_URL}${href}`);
@@ -27,16 +18,18 @@ export const parseInternalHref = (
     pathname: string;
     search: string;
   },
+  propagateSearchParams: string[],
 ) => {
   const { hash, pathname, searchParams } = hrefToUrl(href, location.pathname);
 
-  const { v, vPanel } = parseVersionParams(location.search);
+  const priorSearchParams = new URLSearchParams(location.search);
 
-  if (v !== null) {
-    searchParams.set('v', v);
-  }
-  if (vPanel !== null) {
-    searchParams.set('v-panel', vPanel);
+  for (const key of propagateSearchParams) {
+    const value = priorSearchParams.get(key);
+
+    if (value !== null) {
+      searchParams.set(key, value);
+    }
   }
 
   const search = searchParams.toString();