@openstax/ts-utils 1.33.0 → 1.34.0

package/packages/frontend/src/example/screens/Home.tsx

@@ -0,0 +1,78 @@
+import { FetchStateType, stateHasData, stateHasError } from "@openstax/ts-utils/fetch";
+import React from 'react';
+import { useApiClient } from "../api";
+import { Layout } from "../components/Layout";
+import { useAccountsBase, useAuth, useUserRoles } from "../../auth/useAuth";
+import { useFrontendConfigValue } from "../../configProvider/use";
+import { createRoute, makeScreen } from "../../core/services";
+
+export const Home = () => {
+  const [message, setMessage] = React.useState<string>();
+  const accountsBaseUrl = useAccountsBase();
+  const user = useAuth();
+  const apiClient = useApiClient();
+  const configExampleMessage = useFrontendConfigValue('exampleMessage');
+  const roles = useUserRoles();
+
+  React.useEffect(() => {
+    apiClient.apiV0Info({fetchConfig: {credentials: 'include'}})
+      .then(response => response.acceptStatus(200))
+      .then(response => response.load())
+      .then(response => setMessage(response.message))
+    ;
+    /* example edit/create
+     *
+    apiClient.apiV0WriteTestDoc({
+      params: {foobar: 'idString'},
+      payload: {name: 'cool name', description: 'cool description'},
+      fetchConfig: {credentials: 'include'}
+    })
+      .then(response => response.acceptStatus(201))
+      .then(response => response.load())
+      .then(response => console.log(response))
+    ;
+    */
+  }, [apiClient]);
+
+  return (
+    <Layout title="Home">
+      <p>
+        {stateHasData(roles) && roles.data.includes('admin') ? 'whoa we got an admin here folks' : null}
+      </p>
+      <p>
+        {message}
+      </p>
+      {stateHasData(configExampleMessage) && <p>
+        {configExampleMessage.data}
+      </p>}
+      {!!stateHasData(user) && user.data && <>
+        <a
+          href={`${accountsBaseUrl}accounts/logout?r=${window.location.pathname}`}
+          rel="noopener noreferrer"
+        >
+          logout
+        </a>
+      </>}
+      {stateHasData(user) && !user.data && <>
+        <a
+          href={`${accountsBaseUrl}accounts/login?r=${window.location.pathname}`}
+          rel="noopener noreferrer"
+        >
+          login
+        </a>
+        <a
+          href={`${accountsBaseUrl}accounts/signup?r=${window.location.pathname}`}
+          rel="noopener noreferrer"
+        >
+          signup
+        </a>
+      </>}
+      {stateHasError(user) && <strong>error loading user</strong>}
+      {user.type === FetchStateType.LOADING ? <em>establishing user state</em> : null}
+    </Layout>
+  );
+};
+
+export const homeScreen = createRoute({name: 'HomeScreen', path: '/',
+  handler: makeScreen(Home)
+});

package/packages/frontend/src/example/screens/ThingList.spec.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import { TestServiceProvider } from "../../tests/testServices";
+import * as api from "../api";
+import { thingListScreen } from "./ThingList";
+
+afterEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('ThingList', () => {
+  let apiV0SearchExampleDocSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    apiV0SearchExampleDocSpy = jest.fn();
+
+    jest.spyOn(api, 'useApiClient').mockReturnValue({
+      apiV0SearchExampleDoc: apiV0SearchExampleDocSpy
+    } as any);
+  });
+
+  it('shows results', async() => {
+    apiV0SearchExampleDocSpy.mockReturnValue(Promise.resolve({
+      acceptStatus: () => Promise.resolve(
+        {status: 200, load: () => ({meta: {}, items: [{id: 'some id', name: 'some name'}]})}
+      ),
+    }));
+
+    render(<TestServiceProvider>{thingListScreen.handler(undefined, undefined)}</TestServiceProvider>);
+
+    await waitFor(() => {
+      const dataElement = screen.getByText(/some name/i);
+      expect(dataElement).toBeInTheDocument();
+    });
+  });
+
+  it('renders error on unexpected status', async() => {
+    apiV0SearchExampleDocSpy.mockReturnValue(Promise.resolve({
+      acceptStatus: () => Promise.reject(new Error()),
+    }));
+
+    render(<TestServiceProvider>{thingListScreen.handler(undefined, undefined)}</TestServiceProvider>);
+
+    await waitFor(() => {
+      const dataElement = screen.getByText(/connection failed/i);
+      expect(dataElement).toBeInTheDocument();
+    });
+  });
+
+  it('renders fetch failed', async() => {
+    apiV0SearchExampleDocSpy.mockReturnValue(Promise.reject({ }));
+
+    render(<TestServiceProvider>{thingListScreen.handler(undefined, undefined)}</TestServiceProvider>);
+
+    await waitFor(() => {
+      const dataElement = screen.getByText(/connection failed/i);
+      expect(dataElement).toBeInTheDocument();
+    });
+  });
+});

package/packages/frontend/src/example/screens/ThingList.tsx

@@ -0,0 +1,75 @@
+import React from 'react';
+import { createRoute, makeScreen } from "core/services";
+import { Layout } from "../components/Layout";
+import { UnwrapPromise } from "@openstax/ts-utils/types";
+import { useQuery } from "routing/useQuery";
+import { thingViewScreen } from "./ThingView";
+import { RouteLink } from "routing/components/RouteLink";
+import { Pagination } from "components/Pagination";
+import { fetchLoading,
+  FetchState,
+  fetchSuccess,
+  fetchError,
+  stateHasData,
+  stateHasError
+} from "@openstax/ts-utils/fetch";
+import { ApiClient, useApiClient } from "../api";
+
+// query params are not strongly typed... yet
+type SearchOptions = {
+  page?: string;
+};
+
+/*
+ * this execute function is sometimes unnecessary, but in this case its
+ * kinda nice to use it to extract the SearchData return type for the data.
+ *
+ * if there is a convenient type in the api that represents the return type
+ * like a model or something you could also use that directly
+ * */
+const executeSearch = (apiClient: ApiClient, options: SearchOptions) => {
+  return apiClient.apiV0SearchExampleDoc({query: options})
+    .then(response => response.acceptStatus(200))
+    .then(response => response.load());
+};
+type SearchData = UnwrapPromise<ReturnType<typeof executeSearch>>;
+
+const useSearch = (options: SearchOptions) => {
+  const apiClient = useApiClient();
+  const [pageData, setPageData] = React.useState<FetchState<SearchData, string>>(fetchLoading());
+
+  React.useEffect(() => {
+    executeSearch(apiClient, options)
+      .then(data => setPageData(fetchSuccess(data)))
+      .catch(() => setPageData(previous => fetchError('connection failed', previous)))
+    ;
+  }, [apiClient, options]);
+
+  return pageData;
+};
+
+const SearchResults = ({searchData, options}: {searchData: SearchData; options: SearchOptions}) => {
+  return <div>
+    <ol>
+      {searchData.items.map(item => <li key={item.id}>
+        <RouteLink route={thingViewScreen} params={{id: item.id}}>{item.name}</RouteLink>
+      </li>)}
+    </ol>
+    <Pagination {...searchData.meta} />
+  </div>;
+
+};
+
+export const ThingList = () => {
+  const options = useQuery();
+  const searchState = useSearch(options);
+
+  return <Layout title="Thing List">
+    {stateHasError(searchState) ? searchState.error : null}
+    {stateHasData(searchState) ? <SearchResults searchData={searchState.data} options={options} /> : null}
+  </Layout>;
+};
+
+export const thingListScreen = createRoute({name: 'ThingList', path: '/thing-list',
+  handler: makeScreen(ThingList),
+});

package/packages/frontend/src/example/screens/ThingView.spec.tsx

@@ -0,0 +1,71 @@
+import React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import { TestServiceProvider } from "../../tests/testServices";
+import * as api from "../api";
+import { thingViewScreen } from "./ThingView";
+
+
+afterEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('ThingView', () => {
+  let apiV0GetExampleDocSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    apiV0GetExampleDocSpy = jest.fn();
+
+    jest.spyOn(api, 'useApiClient').mockReturnValue({
+      apiV0GetExampleDoc: apiV0GetExampleDocSpy
+    } as any);
+  });
+
+  it('queries given document', async() => {
+    apiV0GetExampleDocSpy.mockReturnValue(Promise.resolve({
+      acceptStatus: () => Promise.resolve({status: 200, load: () => ({theData: 'this is the data'})}),
+    }));
+
+    render(<TestServiceProvider>{thingViewScreen.handler({id: 'some id'}, undefined)}</TestServiceProvider>);
+
+    await waitFor(() => {
+      expect(apiV0GetExampleDocSpy).toHaveBeenCalledWith({params: {key: 'some id'}});
+    });
+  });
+
+  it('renders data', async() => {
+    apiV0GetExampleDocSpy.mockReturnValue(Promise.resolve({
+      acceptStatus: () => Promise.resolve({status: 200, load: () => ({theData: 'this is the data'})}),
+    }));
+
+    render(<TestServiceProvider>{thingViewScreen.handler({id: 'some id'}, undefined)}</TestServiceProvider>);
+
+    await waitFor(() => {
+      const dataElement = screen.getByText(/this is the data/i);
+      expect(dataElement).toBeInTheDocument();
+    });
+  });
+
+  it('renders not found', async() => {
+    apiV0GetExampleDocSpy.mockReturnValue(Promise.resolve({
+      acceptStatus: () => Promise.resolve({status: 404, load: () => ({theData: 'this is the data'})}),
+    }));
+
+    render(<TestServiceProvider>{thingViewScreen.handler({id: 'some id'}, undefined)}</TestServiceProvider>);
+
+    await waitFor(() => {
+      const dataElement = screen.getByText(/item not found/i);
+      expect(dataElement).toBeInTheDocument();
+    });
+  });
+
+  it('renders fetch failed', async() => {
+    apiV0GetExampleDocSpy.mockReturnValue(Promise.reject({ }));
+
+    render(<TestServiceProvider>{thingViewScreen.handler({id: 'some id'}, undefined)}</TestServiceProvider>);
+
+    await waitFor(() => {
+      const dataElement = screen.getByText(/connection failed/i);
+      expect(dataElement).toBeInTheDocument();
+    });
+  });
+});

package/packages/frontend/src/example/screens/ThingView.tsx

@@ -0,0 +1,47 @@
+import React from 'react';
+import { createRoute, makeScreen } from "../../core/services";
+import { Layout } from "../components/Layout";
+import {
+  FetchState,
+  fetchLoading,
+  fetchError,
+  fetchSuccess,
+  stateHasData,
+  stateHasError
+} from "@openstax/ts-utils/fetch";
+import { useApiClient } from "../api";
+import {
+  ExampleDocument
+} from "@project/lambdas/build/src/functions/serviceApi/versions/v0/example/documentStoreMiddleware";
+
+const useGetDocument = (id: string) => {
+  const apiClient = useApiClient();
+  const [data, setData] = React.useState<FetchState<ExampleDocument, string>>(fetchLoading());
+
+  React.useEffect(() => {
+    apiClient.apiV0GetExampleDoc({params: {key: id}})
+      .then(response => response.acceptStatus(200, 404))
+      .then(response => response.status === 200 ? response.load() : undefined)
+      .then(data => data !== undefined
+        ? setData(fetchSuccess(data))
+        : setData(previous => fetchError('item not found', previous))
+      )
+      .catch(() => setData(previous => fetchError('connection failed', previous)))
+    ;
+  }, [apiClient, id]);
+
+  return data;
+};
+
+export const ThingView = ({id}: {id: string}) => {
+  const state = useGetDocument(id);
+
+  return <Layout title={`Thing: ${stateHasData(state) ? state.data.name : ''}`}>
+    {stateHasError(state) ? state.error : null}
+    {stateHasData(state) ? <pre>{JSON.stringify(state.data, null, 2)}</pre> : null}
+  </Layout>;
+};
+
+export const thingViewScreen = createRoute({name: 'ThingView', path: '/things/:id',
+  handler: makeScreen(ThingView),
+});

package/packages/frontend/src/example/screens/index.ts

@@ -0,0 +1,9 @@
+import {homeScreen} from './Home';
+import { thingListScreen } from "./ThingList";
+import { thingViewScreen } from "./ThingView";
+
+export const exampleRoutes = () => ([
+  homeScreen,
+  thingListScreen,
+  thingViewScreen,
+]);

package/packages/frontend/src/index.css

@@ -0,0 +1,159 @@
+html {
+  font-family: "Neue Helvetica W01", Helvetica, Arial, sans-serif;
+  font-size: 62.5%;
+  text-size-adjust: 100%; /* Prevent font scaling in landscape while allowing user zoom */
+}
+
+body {
+  margin: 0;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+code {
+  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
+    monospace;
+}
+
+#root, body, html {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+}
+
+#root {
+  display: flex;
+  flex-direction: column;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+.visually-hidden {
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  height: 1px;
+  overflow: hidden;
+  position: absolute;
+  white-space: nowrap;
+  width: 1px;
+}
+
+@import url('https://fonts.googleapis.com/css2?family=Libre+Baskerville:wght@700&display=swap');
+@import url("https://fast.fonts.net/t/1.css?apiType=css&projectid=437b6557-ce99-4f35-97ff-64a93247731f");
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: url("https://openstax.org/cms/assets/fonts/e206f16e-f3ae-45eb-b7a9-c0a42ed7537f.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/f4d1bafa-befd-4f3f-ba25-7c0f77c6651e.woff") format("woff");
+  font-weight: 100;
+  font-style: normal; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: url("https://openstax.org/cms/assets/fonts/91faf02a-e602-411f-8235-45b42c914e41.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/a5919350-0aef-4bd2-9809-88c50c764770.woff") format("woff");
+  font-weight: 100;
+  font-style: italic; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: url("https://openstax.org/cms/assets/fonts/4ff9f3fa-9221-4fc5-97e6-93572b6efa24.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/ca8d25cd-e264-4404-b271-4afc45c779c4.woff") format("woff");
+  font-weight: 200;
+  font-style: normal; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: url("https://openstax.org/cms/assets/fonts/a9445981-191b-46c7-866c-acb67f9cc1db.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/a0e9ae86-436e-483a-8201-6c694e90e9ee.woff") format("woff");
+  font-weight: 200;
+  font-style: italic; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: url("https://openstax.org/cms/assets/fonts/3a46542f-f429-4821-9a88-62e3be54a640.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/50ac1699-f3d2-47b6-878f-67a368a17c41.woff") format("woff");
+  font-weight: 300;
+  font-style: normal; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: url("https://openstax.org/cms/assets/fonts/261b4efb-3d70-4965-977d-38af9422700d.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/2e00514e-1764-4250-a0c5-aca3e5a8d133.woff") format("woff");
+  font-weight: 300;
+  font-style: italic; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: local('Helvetica Neue'),
+  url("https://openstax.org/cms/assets/fonts/3dac71eb-afa7-4c80-97f0-599202772905.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/34e0e4c0-c294-49bb-9a8e-1b2cafd54e32.woff") format("woff");
+  font-weight: 400;
+  font-style: normal; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: local('Helvetica Neue Italic'),
+  url("https://openstax.org/cms/assets/fonts/21c44514-f4d6-4cff-a5de-e4cac5e61aff.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/e7c4b231-76ad-47c7-a54b-5d84dcd78d0f.woff") format("woff");
+  font-weight: 400;
+  font-style: italic; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: url("https://openstax.org/cms/assets/fonts/5b1fbd62-45dc-4433-a7df-a2b24a146411.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/050b1948-f226-4d20-a65a-15d8ed031222.woff") format("woff");
+  font-weight: 500;
+  font-style: normal; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: url("https://openstax.org/cms/assets/fonts/657c2fa4-585b-4761-9e2e-65ab13159323.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/400869f0-f0d5-49a0-8a11-f4fb4279d125.woff") format("woff");
+  font-weight: 500;
+  font-style: italic; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: local('Helvetica Neue Bold'),
+  url("https://openstax.org/cms/assets/fonts/531c5a28-5575-4f58-96d4-a80f7b702d7b.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/439c5962-f9fe-4eaf-a1f6-f41d42edba75.woff") format("woff");
+  font-weight: 700;
+  font-style: normal; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: local('Helvetica Neue Bold Italic'),
+  url("https://openstax.org/cms/assets/fonts/ade4dbae-c607-4c84-a375-f0c4de0cc357.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/5b864741-6f14-4ed9-a297-27a4d73edf51.woff") format("woff");
+  font-weight: 700;
+  font-style: italic; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: url("https://openstax.org/cms/assets/fonts/dd7814bd-8abf-46c5-a4be-db0977de2cca.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/20ffa4b4-0154-4ca6-800c-468cecbd60f1.woff") format("woff");
+  font-weight: 800;
+  font-style: normal; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: url("https://openstax.org/cms/assets/fonts/a1ce96fc-e8fa-4118-8a5c-e06d8d094e56.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/c577fdb4-0e4a-4767-aa14-5510cf2c8fa4.woff") format("woff");
+  font-weight: 800;
+  font-style: italic; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: url("https://openstax.org/cms/assets/fonts/bd8486cc-4614-412d-ba1d-15e1a7c9fada.woff2") format("woff2"), url("https://openstax.org/cms/assets/fonts/a7bdf5a9-752e-4e69-b17c-b7e62575b07a.woff") format("woff");
+  font-weight: 900;
+  font-style: normal; }
+
+@font-face {
+  font-display: swap;
+  font-family: 'Neue Helvetica W01';
+  src: url("https://openstax.org/cms/assets/fonts/42535969-7bc6-4047-b3ce-bd8aea29420c.woff2") format("woff2"), url("https://openstax.orghttps://openstax.org/cms/assets/fonts/35e69fef-20b6-4357-b3a2-075224efa08a.woff") format("woff");
+  font-weight: 900;
+  font-style: italic; }

package/packages/frontend/src/index.tsx

@@ -0,0 +1,67 @@
+import { createApiGateway } from "@openstax/ts-utils/services/apiGateway";
+import { createUserRoleValidator } from "@openstax/ts-utils/services/authProvider/utils/userRoleValidator";
+import { ErrorBoundary, createSentryLogger } from "@openstax/ui-components";
+import { createBrowserHistory, Location } from "history";
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { createAuthProvider } from "./auth/authProvider";
+import { frontendConfigProvider } from "./configProvider";
+import { getRequestResponder } from "./core";
+import { serviceProviderMiddleware } from "./core/context/services";
+import { composeResponseServiceMiddleware } from "./core/services";
+import './index.css';
+
+/*
+ * the use of the service container pattern in an app that only
+ * has one entry point is pretty academic. it might become relevant
+ * if you had some external dependencies the FE accessed directly
+ * that you wanted to use a fake driver for in dev (or something like that)
+ */
+const makeApiGateway = createApiGateway({fetch: fetch.bind(window)});
+const configProvider = frontendConfigProvider(makeApiGateway);
+const authProvider = createAuthProvider({window})(configProvider);
+const services = {
+  authProvider,
+  logger: createSentryLogger(),
+  roleValidator: createUserRoleValidator(authProvider, {application: () => configProvider.getValue('roleApplication')}),
+  history: createBrowserHistory(),
+  createApiGateway: makeApiGateway,
+  configProvider,
+};
+
+export type BrowserServices = typeof services;
+
+const handler = getRequestResponder(services, composeResponseServiceMiddleware(
+  serviceProviderMiddleware,
+));
+
+const Router = () => {
+  const [location, setLocation] = React.useState<Location>(services.history.location);
+
+  React.useEffect(() => {
+    return services.history.listen((locationChange) => {
+      setLocation(locationChange.location);
+    });
+  }, []);
+
+  return <>{handler(location)}</>;
+};
+
+const ErrorBoundaryComponent = () => {
+  return (
+    <ErrorBoundary
+      renderFallback
+      // sentryDsn='https://examplePublicKey@o0.ingest.sentry.io/0'
+
+    >
+      <Router />
+    </ErrorBoundary>
+  );
+};
+
+ReactDOM.render(
+  <React.StrictMode>
+    <ErrorBoundaryComponent />
+  </React.StrictMode>,
+  document.getElementById('root')
+);

package/packages/frontend/src/react-app-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="react-scripts" />

package/packages/frontend/src/routing/components/RouteLink.spec.tsx

@@ -0,0 +1,55 @@
+import { render, screen, fireEvent } from '@testing-library/react';
+import { createRouteLink } from "./RouteLink";
+import { TestServiceProvider, testServices } from "../../tests/testServices";
+import { createRoute } from "../../core/services";
+
+const testRoute = createRoute({name: 'TestScreen', path: '/', handler: () => <div />});
+const testPropsRoute = createRoute({
+  name: 'TestPropsScreen',
+  path: '/:prop',
+  handler: (props: {prop: string}) => <div />
+});
+
+type RouteUnion = (typeof testRoute) | (typeof testPropsRoute);
+
+const RouteLink = createRouteLink<RouteUnion>();
+
+describe('RouteLink', () => {
+  it('renders a link', () => {
+    render(<TestServiceProvider><RouteLink route={testRoute}>link text</RouteLink></TestServiceProvider>);
+    expect(screen.getByText(/link text/i)).toMatchInlineSnapshot(`
+<a
+  href="/"
+>
+  link text
+</a>
+`);
+  });
+
+  it('renders a link with props', () => {
+    render(<TestServiceProvider>
+      <RouteLink route={testPropsRoute} params={{prop: 'value'}}>link text</RouteLink>
+    </TestServiceProvider>);
+    expect(screen.getByText(/link text/i)).toMatchInlineSnapshot(`
+<a
+  href="/value"
+>
+  link text
+</a>
+`);
+  });
+
+  it('pushes history', () => {
+    render(
+      <TestServiceProvider>
+        <RouteLink route={testPropsRoute} params={{prop: 'value'}}>link text</RouteLink>
+      </TestServiceProvider>
+    );
+
+    const pushSpy = jest.spyOn(testServices.history, 'push');
+
+    fireEvent.click(screen.getByText(/link text/i));
+
+    expect(pushSpy).toHaveBeenCalledWith('/value');
+  });
+});

package/packages/frontend/src/routing/components/RouteLink.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { ParamsForRoute, renderAnyRouteUrl, AnyRoute, QueryParams } from "@openstax/ts-utils/routing";
+import { useServices } from "core/context/services";
+import { TRoutes } from "core";
+
+export const isClickWithModifierKeys = (e: React.MouseEvent | MouseEvent) =>
+  e.shiftKey || e.ctrlKey || e.metaKey || e.altKey;
+
+export function useRouteLinkOnClick() {
+  const {history} = useServices();
+
+  return (e: React.MouseEvent<HTMLAnchorElement>) => {
+    if (isClickWithModifierKeys(e) || e.currentTarget.getAttribute('target') === '_blank') {
+      return;
+    }
+    e.preventDefault();
+    const {pathname, search, hash} = new URL(e.currentTarget.href);
+    const target = `${pathname}${search}${hash}`;
+    history.push(target);
+  };
+}
+
+export const createRouteLink = <Ru,>() => <R extends Ru>(
+  {
+    route, params, query, children, ...props
+  }: React.PropsWithChildren<{route: R extends AnyRoute<R> ? R : never; query?: QueryParams}> & (
+    ParamsForRoute<R> extends undefined ? {params?: undefined} : {params: ParamsForRoute<R>}
+  ) & React.HTMLProps<HTMLAnchorElement>
+) => {
+  const url = renderAnyRouteUrl<R>(route, params as ParamsForRoute<R>, query);
+
+  return <a {...props} href={url} onClick={useRouteLinkOnClick()}>{children}</a>;
+};
+
+export const RouteLink = createRouteLink<TRoutes>();

package/packages/frontend/src/routing/middleware.ts

@@ -0,0 +1,6 @@
+import queryString from 'query-string';
+import { AppServices } from "../core/types";
+
+export const getQuery = ({history}: AppServices) => {
+  return queryString.parse(history.location.search);
+};