add TextLink docs (#657)

packages/react/docs/media-queries.mdx

@@ -3,7 +3,7 @@ import { Meta, Unstyled } from '@storybook/blocks';
 import { BodyText, Flex, Divider } from '../src/components';
 import { media } from '../src/utils/media';
 
-<Meta title="Documentation / Media Queries" />
+<Meta title="Utilities / Media Queries" />
 
 # Media Queries
 

packages/react/src/components/BodyText/BodyText.docs.mdx

@@ -4,7 +4,7 @@ import * as Stories from './BodyText.stories';
 
 import { DocsHeader } from '../../storybook/DocsHeader';
 
-<Meta title="Documentation / BodyText" />
+<Meta title="Components / BodyText" />
 
 <DocsHeader
   componentName="BodyText"

packages/react/src/components/Divider/Divider.docs.mdx

@@ -4,7 +4,7 @@ import * as Stories from './Divider.stories';
 
 import { DocsHeader } from '../../storybook/DocsHeader';
 
-<Meta title="Documentation / Divider" />
+<Meta title="Components / Divider" />
 
 <DocsHeader
   componentName="Divider"

packages/react/src/components/TextLink/TextLink.docs.mdx

@@ -0,0 +1,166 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+
+import * as Stories from './TextLink.stories';
+
+import { DocsHeader } from '../../storybook/DocsHeader';
+
+<Meta title="Components / TextLink" />
+
+<DocsHeader
+  componentName="TextLink"
+  stories={Stories}
+  figmaLink="https://www.figma.com/design/4FFYTLWJ2hQpj36JplQQUw/UW-Web-UI?node-id=6834-38146"
+/>
+
+<Canvas of={Stories.Workshop} sourceState="none" />
+
+- [Semantic HTML](#semantic-html)
+- [Guidelines](#guidelines)
+- [Size](#size)
+- [Colour](#colour)
+- [Usage with Next.js](#usage-with-next.js)
+  - [Next.js v13](#next.js-v13)
+  - [Next.js before v13](#next.js-before-v13)
+- [API](#api)
+
+## Semantic HTML
+
+> If it goes somewhere it's a link, if it does something it's a button.
+
+A semantic HTML `a` is rendered by default, however you can change the
+underlying HTML element by using the `asChild` prop.
+
+When `asChild` is set to true, we will not render a default DOM element,
+instead cloning the child and passing it the props and behaviour required to
+make it functional.
+
+Read more about this idea in the [Radix UI composition docs](https://www.radix-ui.com/primitives/docs/guides/composition).
+
+```tsx
+// You may need to disable this eslint warning:
+// eslint-disable-next-line jsx-a11y/anchor-is-valid
+<TextLink asChild>
+  <button type="button" onClick={onClick}>
+    View benefits
+    <ChevronRightMediumIcon />
+  </button>
+</TextLink>
+```
+
+<Canvas of={Stories.AsButton} />
+
+## Guidelines
+
+Try and avoid using `target=_blank` if possible: [When to use target="\_blank"](https://css-tricks.com/use-target_blank/).
+Though if you do use it, then be aware that [browsers now implicitly set rel=noopener for any target=\_blank link](https://mathiasbynens.github.io/rel-noopener/).
+
+## Size
+
+The `TextLink` component must be wrapped in a `Text` component, and will
+inherit it's styles, so it's size will be controlled by the parent
+`Text` variant.
+
+## Colour
+
+You can use the `color` prop to override the `TextLink` colours. This will set
+the `active` & `visited` states to the same colour as the default state. If you
+set it to `"inherit"` then the `TextLink` component will inherit the colour of
+the parent element.
+
+```tsx
+import { Box, Text, TextLink } from "@utilitywarehouse/web-ui";
+
+[...]
+
+<Box padding={2} background={colorsCommon.brandMidnight}>
+  <Text variant="body" color={colorsCommon.brandPink}>
+    Text with a{' '}
+    <TextLink {...args} color="inherit">
+      TextLink
+    </TextLink>{' '}
+    on brand midnight background with custom color
+  </Text>
+</Box>
+<Box padding={2}>
+  <Text variant="body">
+    Text with a{' '}
+    <TextLink {...args} color={colors.green500}>
+      TextLink
+    </TextLink>{' '}
+    on white background with custom color
+  </Text>
+</Box>
+```
+
+> **NOTE:** While it is technically possible to use a custom, or inherited,
+> colour, it is not encouraged.
+
+## Usage with Next.js
+
+### Next.js v13
+
+The Next.js `Link` component behaviour has changed in v13, so that an `<a>` is
+no longer required as a child. You can render the Web UI `TextLink` component as a
+Next.js `Link` component using `asChild`:
+
+```tsx
+import NextLink from 'next/link';
+import { TextLink } from '@utilitywarehouse/ds-react';
+
+[...]
+
+{/* // eslint-disable-next-line jsx-a11y/anchor-is-valid */}
+<TextLink asChild>
+  <NextLink href={href} onClick={onClick}>
+    {title}
+  </NextLink>
+</TextLink>
+```
+
+You can also use the `legacyBehavior` prop directly on the Next.js Link component:
+
+```tsx
+import NextLink from 'next/link';
+import { TextLink } from '@utilitywarehouse/ds-react';
+
+[...]
+
+<NextLink href={href} passHref onClick={onClick} legacyBehavior>
+  {/* // eslint-disable-next-line jsx-a11y/anchor-is-valid */}
+  <TextLink>{title}</TextLink>
+</NextLink>
+```
+
+And if you want to set this behavior globally you can use the following Next.js
+configuration:
+
+```
+{
+  experimental: {
+    newNextLinkBehavior: false
+  }
+}
+```
+
+### Next.js before v13
+
+```tsx
+import NextLink from 'next/link';
+import { TextLink } from '@utilitywarehouse/ds-react';
+
+[...]
+
+<NextLink href={href} passHref onClick={onClick}>
+  {/* // eslint-disable-next-line jsx-a11y/anchor-is-valid */}
+  <TextLink>{title}</TextLink>
+</NextLink>
+```
+
+## API
+
+This component is based on the `a` element.
+
+| Prop      | Type      | Description                                                                                           | Default           |
+| --------- | --------- | ----------------------------------------------------------------------------------------------------- | ----------------- |
+| `color`   | `string`  | Override the default TextLink colours.                                                                | `--color-grey175` |
+| `asChild` | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behaviour. | `false`           |

packages/react/src/components/TextLink/TextLink.props.ts

@@ -9,7 +9,7 @@ export interface TextLinkProps extends ComponentPropsWithout<'a', RemovedProps>
    */
   color?: string;
   /**
-   * Change the default rendered element for the one passed as a child, merging their props and behavior.
+   * Change the default rendered element for the one passed as a child, merging their props and behaviour.
    */
   asChild?: boolean;
 }