Allow link hrefs with a scope query param

[ptgott]

Closes #35
Closes #33
See gravitational/teleport#11383

Previously, the Link component would always set the "scope" query
parameter in its href to the current value of DocsContext.scope.
I wanted to make it possible to link to other scopes, allowing readers
who are interested in another edition of Teleport to read content
intended for that edition.

We could add explicit links to different
scopes in, for example, warnings at the top of scope-irrelevant
pages or in introduction pages to sections that are only helpful for
a specific Teleport edition (e.g., the Enterprise section).

This change edits useNormalizedHref to add a "scope" value to the
href's query if the input href has a "scope" key and the value is
a valid scope name ("oss", "cloud", or "enterprise").

[vercel]

@ptgott is attempting to deploy a commit to the gravitational Team on Vercel.

A member of the Team first needs to authorize it.

[ptgott]

@iAdramelk Here's a PR based on my earlier discussion comment.

I thought it would be nice to add unit tests to useNormalizedHref, but ran over my allotted time figuring out how to configure the test suite. If I create a file called components/Link/hooks.test.tsx with this content:

import { suite } from "uvu";
import * as assert from "uvu/assert";
import { useNormalizedHref } from "./hooks";
const Suite = suite("components/hooks.tsx");

Suite("Preserves scopes in query strings", () => {
  const href = useNormalizedHref("/getting-started/linux-server/?scope=cloud");
  assert.equal(href, "/getting-started/linux-server/?scope=cloud");
});

Suite.run();

...I get this error from yarn test:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/Users/paulgottschling/Documents/docs/node_modules/next/router' imported from /Users/paulgottschling/Documents/docs/components/Link/hooks.ts
Did you mean to import next/router.js?
    at new NodeError (node:internal/errors:372:5)
    at finalizeResolution (node:internal/modules/esm/resolve:405:11)
    at moduleResolve (node:internal/modules/esm/resolve:966:10)
    at defaultResolve (node:internal/modules/esm/resolve:1176:11)
    at resolve (file:///Users/paulgottschling/Documents/docs/node_modules/tsm/loader.mjs:1:551)
    at ESMLoader.resolve (node:internal/modules/esm/loader:605:30)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:318:18)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:80:40)
    at link (node:internal/modules/esm/module_job:78:36)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
error Command failed with exit code 1.

I've manually tested this change instead.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
docs	❌ Failed (Inspect)		May 11, 2022 at 5:07AM (UTC)

[iAdramelk]

I added some comments about already existing types that we can use to simplify code a little.

About the tests. Problem with them is in the next/router component, it works only inside the Next app. Calling it outside the Next app causes this error. We may emulate it for testing, but we will need to heavily mock it, so probably it would not be that useful. Alternatively we can rewrite this function in the way that receives router from the outside and test it this way, but it will make using the hook less convenient.

[iAdramelk]

FYI: We already have types for scopes and the array of available scopes you can use here instead of defining them again.

See: https://github.com/gravitational/docs/blob/main/layouts/DocsPage/types.ts#L6-L9

[ptgott]

Thanks! Fixed this in 182adf6

[iAdramelk]

You can actually replace this code with scopeValues too(https://github.com/gravitational/docs/blob/main/layouts/DocsPage/types.ts#L6).

Something like scopeValues.includes(scope).

[ptgott]

Thanks! Made this change in 092e699

[ptgott]

@iAdramelk Thanks!
@C-STYR Is there anything else we need to do before we can merge this?

[C-STYR]

@ptgott @iAdramelk the preview build is failing because it's OOM (exit code 137). @iAdramelk is the expert here, but sunsetting older versions of docs certainly can help. Now that @jeffgaynor is here and can be brought into the conversation, this may shift our priorities somewhat on how @Alqanar 's time is used.

[ptgott]

@C-STYR @iAdramelk Thanks! Looks like there are intermittent OOMs with build jobs from other branches as well. I'll try the build again.

[iAdramelk]

@ptgott @C-STYR

Yes, OOM errors right now it the side effect of the way build is organized now. The more pages we have and the larger they are, the more memory build uses. I'm working on a fix that can prevent it from happening in the future in this branch (#48), but it will take some time to finish. Meanwhile, sunsetting older versions can solve the problem for a time.

[ptgott]

@C-STYR Looks like the Vercel build completed