@kaizen/components 1.72.0 → 1.73.1

package/src/Link/_docs/Link--api-usage-guidelines.mdx

@@ -0,0 +1,107 @@
+import { Canvas, Meta, Controls } from '@storybook/blocks'
+import {
+  ResourceLinks,
+  KAIOInstallation,
+  LinkTo,
+  DosAndDonts,
+  DoOrDont,
+} from '~storybook/components'
+import * as Link from './Link.doc.stories'
+
+<Meta title="Components/Link/Usage Guidelines" />
+
+# Link
+
+Updated Jan 30, 2025
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/Link"
+  figma="https://www.figma.com/design/FWIOtGjpv9z0by95j1SgP0/Link?node-id=273-4107"
+  apiSpecification="/?path=/docs/components-link-api-specification--docs"
+/>
+
+<KAIOInstallation exportNames={'Link'} />
+
+## Overview
+
+`Link` allow users to navigate to a different location. They can be presented inside a paragraph or as standalone text.
+
+<Canvas of={Link.Playground} />
+
+<Controls
+  of={Link.Playground}
+  include={['href', 'variant', 'size', 'isDisabled', 'icon', 'iconPosition']}
+  className="mb-64"
+/>
+
+## When to use
+
+- Navigating to a different page within the application
+- Navigating to an entirely different site
+- Jump to an element on the same page
+- Link to emails or phone numbers
+
+## When not to use
+
+- Do not use links for actions that will change data or manipulate how it is displayed, change a state, or trigger an action. Instead, use buttons to guide users to specific actions.
+
+### Use primary links to highlight
+
+The primary link is the default and is blue. This should be used to call attention to the link and for when the blue color won’t feel too overwhelming in the experience.
+
+### Use secondary links to optimise readability
+
+The secondary link is the same color as the paragraph text. Its subdued appearance is optimal for when the primary variant is too overwhelming, such as in blocks of text with several references linked throughout.
+
+### Use links in body copy
+
+Put links in regular text, not in titles. If you need something bigger or more noticeable, try using a button instead.
+
+### Use a relative link size
+
+The link component has four size variants, each aligning with body text sizes.
+
+- **Inline Links**: Use the isInline prop to inherit the font size from the parent Text component.
+- **Standalone Links**: Choose a size that maintains consistency with the surrounding text within the same component or pattern.
+
+### Give context to inline links
+
+For links in a sentence, write them as part of the sentence and include enough information so people know what to expect. This approach can draw a user’s focus to the linked text. If the link leads to more content, it can be helpful to write it as a descriptive noun (e.g., “survey feedback”). If the link launches a task or action, start it with a verb (e.g., “Share your feedback”).
+
+### Specs
+
+#### Write standalone links like calls-to-action
+
+Standalone links are not full sentences, and do not have punctuation at the end. Treat these like calls-to-action by writing them as short verb phrases. Where possible, do not break over multiple lines.
+
+<DosAndDonts>
+  <DoOrDont story={Link.StandaloneLinkDo} />
+  <DoOrDont story={Link.StandaloneLinkDont} isDont />
+</DosAndDonts>
+
+#### Ensure clarity by prioritizing the most valuable links
+
+Think about how many links you use and where you put them. Don't overload your interface with too many links as clustering links can confuse people.
+
+<DosAndDonts>
+  <DoOrDont story={Link.OneLinkInSentence} />
+  <DoOrDont story={Link.FiveLinksInSentence} isDont />
+</DosAndDonts>
+
+#### Use icons in links sparingly and consistently
+
+Overusing icons can create visual clutter and overwhelm users. Use them sparingly to highlight common and recognisable navigation.
+
+<DosAndDonts>
+  <DoOrDont story={Link.ExternalIconLink} />
+  <DoOrDont story={Link.RandomIconLink} isDont />
+</DosAndDonts>
+
+#### Links should make sense in isolation
+
+If links on a page have the same label repeated multiple times, they should have distinct, accessible names that add context for users. This ensures [better accessibility for screen reader](https://cultureamp.atlassian.net/wiki/spaces/PA/pages/3240099910/Buttons+and+link+labels+make+sense+in+isolation) users, who rely on descriptive labels to distinguish between links.
+
+<DosAndDonts>
+  <DoOrDont story={Link.DistinctNamedLink} />
+  <DoOrDont story={Link.GenericNamedLink} isDont />
+</DosAndDonts>

package/src/Link/_docs/Link.doc.stories.tsx

@@ -0,0 +1,238 @@
+import React from 'react'
+import { type Meta, type StoryObj } from '@storybook/react'
+import { Text } from '~components/Text'
+import { Icon } from '~components/__next__/Icon'
+import { Link } from '../Link'
+
+const meta = {
+  title: 'Components/Link',
+  component: Link,
+  args: {
+    children: 'Link',
+    href: 'https://www.google.com',
+  },
+  argTypes: {
+    variant: {
+      options: ['primary', 'secondary', 'white'],
+    },
+    size: {
+      options: ['intro-lede', 'body', 'small', 'extra-small'],
+    },
+    icon: {
+      options: ['arrow_forward', 'open_in_new'],
+      mapping: {
+        // eslint-disable-next-line camelcase
+        arrow_forward: <Icon isPresentational name="arrow_forward" />,
+        // eslint-disable-next-line camelcase
+        open_in_new: <Icon isPresentational name="open_in_new" />,
+      },
+      description:
+        'Renders an icon at the specified `iconPosition`. For size scaling, use the `Icon` component from `"@kaizen/components/future"`. See [all available icons](https://cultureamp.design/?path=/docs/components-icon-icon-future-api-specification--docs)',
+    },
+  },
+} satisfies Meta<typeof Link>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {
+  render: (props) =>
+    props.variant !== 'white' ? (
+      <Link {...props} />
+    ) : (
+      <div className="flex p-12 bg-purple-600">
+        {' '}
+        <Link {...props} />
+      </div>
+    ),
+}
+
+export const LinkVariants: Story = {
+  render: (props) => (
+    <>
+      <Link {...props} variant="primary" />
+      <br />
+      <Link {...props} variant="secondary" />
+    </>
+  ),
+  decorators: [
+    (Story) => (
+      <div className="flex gap-8">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export const LinkVariantWhite: Story = {
+  render: (props) => <Link {...props} variant="white" />,
+  parameters: {
+    reverseColors: true,
+  },
+}
+
+export const LinkWithIconStart: Story = {
+  render: (props) => (
+    <Link {...props} icon={<Icon name="add" isPresentational />} iconPosition="start" />
+  ),
+}
+
+export const LinkWithIconEnd: Story = {
+  render: (props) => (
+    <Link {...props} icon={<Icon name="add" isPresentational />} iconPosition="end" />
+  ),
+}
+
+export const LinkOpensInNewTab: Story = {
+  render: (props) => (
+    <Link
+      {...props}
+      target="_blank"
+      icon={<Icon name="open_in_new" isPresentational />}
+      iconPosition="end"
+    />
+  ),
+}
+
+export const WithText: Story = {
+  render: ({ size: _, ...otherArgs }) => (
+    <>
+      <Text variant="intro-lede">
+        Lorem ipsum dolor sit amet consectetur adipisicing elit. Quae eaque amet atque. Dolores
+        repellendus eligendi <span style={{ textDecoration: 'underline' }}> totam.</span>{' '}
+        <Link {...otherArgs} icon={<Icon name="add" isPresentational />} isInline /> Mollitia vero
+        asperiores assumenda, odit ratione id perspiciatis suscipit molestias quas facere, commodi
+        saepe! Quisquam, quidem quas a quos quae quia quidem, quod, voluptates, dolorum quibusdam.
+        Quisquam, quidem quas a quos quae
+      </Text>
+      <br />
+      <Text variant="body">
+        Lorem ipsum dolor sit amet consectetur adipisicing elit. Quae eaque amet atque. Dolores
+        repellendus eligendi <span style={{ textDecoration: 'underline' }}> totam.</span>{' '}
+        <Link
+          {...otherArgs}
+          icon={<Icon name="add" isPresentational />}
+          isInline
+          size={undefined}
+        />
+        Mollitia vero asperiores assumenda, odit ratione id perspiciatis suscipit molestias quas
+        facere, commodi saepe! Quisquam, quidem quas a quos quae quia quidem, quod, voluptates,
+        dolorum quibusdam. Quisquam, quidem quas a quos quae
+      </Text>
+      <br />
+      <Text variant="small">
+        Lorem ipsum dolor sit amet consectetur adipisicing elit. Quae eaque amet atque. Dolores
+        repellendus eligendi <span style={{ textDecoration: 'underline' }}> totam.</span>{' '}
+        <Link {...otherArgs} icon={<Icon name="add" isPresentational />} isInline /> Mollitia vero
+        asperiores assumenda, odit ratione id perspiciatis suscipit molestias quas facere, commodi
+        saepe! Quisquam, quidem quas a quos quae quia quidem, quod, voluptates, dolorum quibusdam.
+        Quisquam, quidem quas a quos quae
+      </Text>
+      <br />
+      <Text variant="extra-small">
+        Lorem ipsum dolor sit amet consectetur adipisicing elit. Quae eaque amet atque. Dolores
+        repellendus eligendi <span style={{ textDecoration: 'underline' }}> totam.</span>{' '}
+        <Link {...otherArgs} icon={<Icon name="add" isPresentational />} isInline /> Mollitia vero
+        asperiores assumenda, odit ratione id perspiciatis suscipit molestias quas facere, commodi
+        saepe! Quisquam, quidem quas a quos quae quia quidem, quod, voluptates, dolorum quibusdam.
+        Quisquam, quidem quas a quos quae
+      </Text>
+    </>
+  ),
+}
+
+// Links of every different size
+export const LinkSizes: Story = {
+  render: ({ children: _, size: __, isInline: ___, ...otherArgs }) => (
+    <>
+      <Link size="extra-small" {...otherArgs}>
+        Extra Small
+      </Link>
+      <br />
+      <Link {...otherArgs} size="small">
+        Small
+      </Link>
+      <br />
+      <Link {...otherArgs} size="body">
+        Body
+      </Link>
+      <br />
+      <Link {...otherArgs} size="intro-lede">
+        Intro Lede
+      </Link>
+    </>
+  ),
+}
+
+export const StandaloneLinkDo: Story = {
+  render: (props) => <Link {...props}>Learn more about demographics</Link>,
+}
+
+export const StandaloneLinkDont: Story = {
+  render: ({ size: _, ...otherArgs }) => (
+    <Text variant="body">
+      Learn more about{' '}
+      <Link {...otherArgs} isInline>
+        demographics
+      </Link>
+    </Text>
+  ),
+}
+
+export const OneLinkInSentence: Story = {
+  render: (props) => (
+    <Text variant="body">
+      Lorem ipsum dolor sit amet consectetur adipisicing elit. Illo ad nobis, ut aspernatur deserunt
+      fuga expedita amet architecto{' '}
+      <Link {...props} isInline size={undefined}>
+        pariatur cum itaque
+      </Link>{' '}
+      dicta veritatis inventore ea esse rem dolore natus! Architecto.
+    </Text>
+  ),
+}
+
+export const FiveLinksInSentence: Story = {
+  render: ({ size: _, ...otherArgs }) => (
+    <Text variant="body">
+      Lorem ipsum dolor sit amet consectetur adipisicing elit. Illo{' '}
+      <Link {...otherArgs} isInline>
+        {' '}
+        ad nobis
+      </Link>
+      , ut aspernatur{' '}
+      <Link {...otherArgs} isInline>
+        deserunt fuga expedita amet architecto
+      </Link>{' '}
+      <Link {...otherArgs} isInline>
+        pariatur cum itaque
+      </Link>{' '}
+      dicta veritatis{' '}
+      <Link {...otherArgs} isInline>
+        inventore ea
+      </Link>{' '}
+      esse rem dolore{' '}
+      <Link {...otherArgs} isInline>
+        natus
+      </Link>
+      ! Architecto.
+    </Text>
+  ),
+}
+
+export const ExternalIconLink: Story = {
+  render: (props) => <Link {...props} icon={<Icon name="open_in_new" isPresentational />} />,
+}
+
+export const RandomIconLink: Story = {
+  render: (props) => <Link {...props} icon={<Icon name="flag" isPresentational />} />,
+}
+
+export const DistinctNamedLink: Story = {
+  render: (props) => <Link {...props}>View Q4 2024 dataset</Link>,
+}
+
+export const GenericNamedLink: Story = {
+  render: (props) => <Link {...props}>Learn more</Link>,
+}

package/src/Link/_docs/Link.stickersheet.stories.tsx

@@ -0,0 +1,191 @@
+import React from 'react'
+import { type Meta } from '@storybook/react'
+import { within } from '@storybook/test'
+import { Icon } from '~components/__next__/Icon'
+import { StickerSheet, type StickerSheetStory } from '~storybook/components/StickerSheet'
+import { Link, type LinkProps } from '../Link'
+
+export default {
+  title: 'Components/Link',
+  component: Link,
+  parameters: {
+    chromatic: { disable: false },
+    controls: { disable: true },
+  },
+} satisfies Meta
+
+const variants = ['primary', 'secondary'] satisfies LinkProps['variant'][]
+const sizes = ['extra-small', 'small', 'body', 'intro-lede'] satisfies LinkProps['size'][]
+const href = 'https://www.google.com' satisfies LinkProps['href']
+
+const StickerSheetTemplate: StickerSheetStory = {
+  render: ({ isReversed }) => (
+    <>
+      <StickerSheet
+        title="Link"
+        headers={[
+          'isUnderlined',
+          'isUnderlined + Icon Start',
+          'isUnderlined + Icon End',
+          'Icon start',
+          'Icon end',
+          'isDisabled',
+        ]}
+        isReversed={isReversed}
+      >
+        {variants.map((variant) =>
+          sizes.map((size) => (
+            <StickerSheet.Row key={size + variant} header={`${variant} (${size})`}>
+              <Link
+                variant={isReversed ? 'white' : variant}
+                size={size}
+                href={href}
+                isUnderlined={true}
+                isInline={false}
+              >
+                Link
+              </Link>
+              <Link
+                variant={isReversed ? 'white' : variant}
+                size={size}
+                href={href}
+                isUnderlined={true}
+                isInline={false}
+                icon={<Icon name="add" isPresentational />}
+                iconPosition="start"
+              >
+                Link
+              </Link>
+              <Link
+                variant={isReversed ? 'white' : variant}
+                size={size}
+                href={href}
+                isUnderlined={true}
+                isInline={false}
+                icon={<Icon name="add" isPresentational />}
+                iconPosition="end"
+              >
+                Link
+              </Link>
+              <Link
+                variant={isReversed ? 'white' : variant}
+                size={size}
+                href={href}
+                isUnderlined={false}
+                isInline={false}
+                icon={<Icon name="add" isPresentational />}
+                iconPosition="start"
+              >
+                Link
+              </Link>
+              <Link
+                variant={isReversed ? 'white' : variant}
+                size={size}
+                href={href}
+                isUnderlined={false}
+                isInline={false}
+                icon={<Icon name="add" isPresentational />}
+                iconPosition="end"
+              >
+                Link
+              </Link>
+              <Link
+                variant={isReversed ? 'white' : variant}
+                size={size}
+                href={href}
+                isUnderlined={true}
+                isInline={false}
+                isDisabled={true}
+              >
+                Link
+              </Link>
+            </StickerSheet.Row>
+          )),
+        )}
+      </StickerSheet>
+      <StickerSheet
+        title="Pseudo states"
+        headers={['isHovered', 'isFocusVisible', 'isPressed']}
+        isReversed={isReversed}
+      >
+        {variants.map((variant) => (
+          <StickerSheet.Row key={variant} isReversed={isReversed} header={variant}>
+            <Link
+              variant={isReversed ? 'white' : variant}
+              size="small"
+              href={href}
+              isUnderlined={true}
+              isInline={false}
+              icon={<Icon name="add" isPresentational />}
+              data-testid="testid__link-hover"
+            >
+              Label
+            </Link>
+            <Link
+              variant={isReversed ? 'white' : variant}
+              size="small"
+              href={href}
+              isUnderlined={true}
+              isInline={false}
+              icon={<Icon name="add" isPresentational />}
+              data-testid="testid__link-focus"
+            >
+              Label
+            </Link>
+            <Link
+              variant={isReversed ? 'white' : variant}
+              size="small"
+              href={href}
+              isUnderlined={true}
+              isInline={false}
+              icon={<Icon name="add" isPresentational />}
+              data-testid="testid__link-pressed"
+            >
+              Label
+            </Link>
+          </StickerSheet.Row>
+        ))}
+      </StickerSheet>
+    </>
+  ),
+  play: ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const focusLinks = canvas.getAllByTestId('testid__link-focus')
+    const hoverLinks = canvas.getAllByTestId('testid__link-hover')
+    const pressedLinks = canvas.getAllByTestId('testid__link-pressed')
+
+    focusLinks.forEach((Link) => {
+      Link.setAttribute('data-focus-visible', 'true')
+    })
+    hoverLinks.forEach((Link) => {
+      Link.setAttribute('data-hovered', 'true')
+    })
+    pressedLinks.forEach((Link) => {
+      Link.setAttribute('data-pressed', 'true')
+    })
+  },
+}
+
+export const StickerSheetDefault: StickerSheetStory = {
+  ...StickerSheetTemplate,
+  name: 'Sticker Sheet (Default)',
+}
+
+export const StickerSheetRTL: StickerSheetStory = {
+  ...StickerSheetTemplate,
+  name: 'Sticker Sheet (RTL)',
+  parameters: {
+    textDirection: 'rtl',
+  },
+}
+
+export const StickerSheetWhite: StickerSheetStory = {
+  ...StickerSheetTemplate,
+  name: 'Sticker Sheet (White)',
+  parameters: {
+    reverseColors: true,
+  },
+  args: {
+    isReversed: true,
+  },
+}

package/src/Link/index.ts

@@ -0,0 +1 @@
+export * from './Link'

package/src/Link/subcomponents/LinkContent.tsx

@@ -0,0 +1,31 @@
+import React, { type ReactNode } from 'react'
+import { mergeClassNames } from '~components/utils/mergeClassNames'
+import styles from '../Link.module.css'
+
+export type LinkContentProps = {
+  children: ReactNode
+  icon?: JSX.Element
+  iconPosition?: 'start' | 'end'
+  isUnderlined: boolean
+}
+
+const LinkIcon = ({ icon }: { icon: JSX.Element }): JSX.Element => (
+  <span className={styles.icon}>{icon}</span>
+)
+
+export const LinkContent = ({
+  children,
+  icon,
+  iconPosition,
+  isUnderlined,
+}: LinkContentProps): JSX.Element => {
+  const iconPositionStyling = iconPosition === 'start' ? styles.iconStart : styles.iconEnd
+
+  return (
+    <span className={mergeClassNames(styles.linkContent, isUnderlined && styles.isUnderlined)}>
+      {icon && iconPosition === 'start' && <LinkIcon icon={icon} />}
+      <span className={mergeClassNames(icon && iconPositionStyling)}>{children}</span>
+      {icon && iconPosition === 'end' && <LinkIcon icon={icon} />}
+    </span>
+  )
+}

package/src/LinkButton/_docs/LinkButton--api-specification.mdx

@@ -163,63 +163,7 @@ For resizing on smaller screens, consider using the `className` prop to leverage
 
 ## Client side routing
 
-To enable client side routing with the `LinkButton`, you will need to wrap your application in a [RouterProvider](https://react-spectrum.adobe.com/react-aria/routing.html#routerprovider) from the `react-aria-components` library. The allows you to set the `navigation` method that performs the client side routing in the `LinkButton` component. Refer to the framework specific guidance below for [Next.js](#nextjs-config-example) or [React Router](#react-router-config-example).
-
-### Next.js config example
-
-The following example demonstrates how you might use the React Aria's `RouterProvider` with `Next.js`'s Pages router. This will allow the `LinkButton` to navigate using the `router.push` method.
-
-```tsx
-// ...imports
-import type { AppProps } from 'next/app'
-import { type NextRouter } from 'next/router'
-import { RouterProvider as RacRouterProvider } from 'react-aria-components'
-
-// This provides the correct types for `routerOptions` based on the routing solution. As the component agnostic to routing technology this must defined here
-declare module 'react-aria-components' {
-  interface RouterConfig {
-    // index 2 is the types for the pages routerOptions
-    routerOptions: NonNullable<Parameters<NextRouter['push']>[2]>
-  }
-}
-
-function App({ Component, pageProps, router }: AppProps) {
-  return (
-    <FrontendServices {...config}>
-      {/* application code */}
-      <RacRouterProvider navigate={(href, opts) => router.push(href, undefined, opts)}>
-        <Component {...pageProps} />
-      </RacRouterProvider>
-      {/* application code */}
-    </FrontendServices>
-  )
-}
-
-export default App
-```
-
-The implementation in your application would then look something like this:
-
-```tsx
-import { useRouter } from 'next/router'
-import { LinkButton } from '@kaizen/components'
-
-const Component = () => {
-  const router = useRouter()
-
-  return (
-    <>
-      <LinkButton href="http://google.com">External link</LinkButton>
-      <LinkButton href={`${router.pathname}/path-1`}>Internal link</LinkButton>
-      <LinkButton href={`${router.pathname}/path-2`} routerOptions={{ scroll: false }}>
-        Link with routerOptions
-      </LinkButton>
-    </>
-  )
-}
-```
-
-Additional config options for Next.js can be found in the React Aria's documentation on the [RouterProvider](https://react-spectrum.adobe.com/react-aria/routing.html#nextjs), including the alternative setup for the [App router](https://react-spectrum.adobe.com/react-aria/routing.html##app-router).
+Please refer to the [client side routing](/docs/guides-client-side-routing--docs) for more information on how to set up client side routing with the `LinkButton`.
 
 ### React Router config example