@kaizen/components 1.71.0 → 1.73.0

package/src/Link/Link.tsx

@@ -0,0 +1,90 @@
+import React, { forwardRef } from 'react'
+import { Link as RACLink, type LinkProps as RACLinkProps } from 'react-aria-components'
+import { type TextProps } from '~components/Text'
+import { mergeClassNames } from '~components/utils/mergeClassNames'
+import { LinkContent } from './subcomponents/LinkContent'
+import styles from './Link.module.css'
+
+export type LinkProps = BaseLinkProps &
+  ((UnderlinedLink | NonUnderlinedLink) & (InlineLink | NonInlineLink))
+
+type BaseLinkProps = {
+  /** Controls the visual style of a link. @default 'primary' */
+  variant?: 'primary' | 'secondary' | 'white'
+  /** Controls the position of a link. @default 'end' */
+  iconPosition?: 'start' | 'end'
+} & Omit<RACLinkProps, 'children'> & {
+    /** Used as the label for the Link. */
+    children: RACLinkProps['children']
+  }
+
+type UnderlinedLink = {
+  /** Toggles the underline of the icon and children @default true */
+  isUnderlined?: true
+  /** The icon to be displayed, optional when link is underlined */
+  icon?: JSX.Element
+}
+
+type NonUnderlinedLink = {
+  /** Toggles the underline of the icon and children */
+  isUnderlined?: false
+  /** The icon to be displayed, required when link is not underlined */
+  icon: JSX.Element
+}
+
+type InlineLink = {
+  /** isInline assumes the Link is wrapped in a [Text](https://cultureamp.design/?path=/docs/components-text--docs) component */
+  isInline: true
+  /** The size of the link, not passed when isInline */
+  size?: never
+}
+
+type NonInlineLink = {
+  /** isInline assumes the Link is wrapped in a [Text](https://cultureamp.design/?path=/docs/components-text--docs) component @default false */
+  isInline?: false
+  /** The size of the link. Sizes correlate to body text sizes. @default 'body' */
+  size?: TextProps['variant']
+}
+
+export const Link = forwardRef(
+  (
+    {
+      children,
+      variant = 'primary',
+      size = 'body',
+      icon,
+      iconPosition = 'end',
+      isInline = false,
+      isDisabled,
+      className,
+      isUnderlined = true,
+      ...otherProps
+    }: LinkProps,
+    ref: React.ForwardedRef<HTMLAnchorElement>,
+  ) => {
+    const childIsFunction = typeof children === 'function'
+
+    return (
+      <RACLink
+        ref={ref}
+        className={mergeClassNames(
+          styles.link,
+          isDisabled && styles.isDisabled,
+          isInline ? styles.isInline : styles[size],
+          styles[variant],
+          className,
+        )}
+        isDisabled={isDisabled}
+        {...otherProps}
+      >
+        {(racStateProps) => (
+          <LinkContent icon={icon} iconPosition={iconPosition} isUnderlined={isUnderlined}>
+            {childIsFunction ? children(racStateProps) : children}
+          </LinkContent>
+        )}
+      </RACLink>
+    )
+  },
+)
+
+Link.displayName = 'Link'

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

@@ -0,0 +1,133 @@
+import { Canvas, Meta, Controls, ArgTypes, DocsStory } from '@storybook/blocks'
+import { ResourceLinks, KAIOInstallation, LinkTo } from '~storybook/components'
+import * as exampleStories from './Link.doc.stories'
+
+<Meta title="Components/Link/API Specification" />
+
+# Link API Specification
+
+Update Jan 29, 2025
+
+<ResourceLinks
+  sourceCode="blah blah update when available on main"
+  figma="https://www.figma.com/design/FWIOtGjpv9z0by95j1SgP0/Link?node-id=273-4107"
+  designGuidelines="/?path=/docs/components-link-usage-guidelines--docs"
+/>
+
+<KAIOInstallation exportNames={'Link'} />
+
+## Overview
+
+`Link` allows users to navigate to another page or resource. It is a wrapper around the native `a` element, with additional functionality and styling.
+
+The following example and table showcases the essential props that enable the core functionality of `Link`. For the remaining suite of API options refer to [this section](#additional-api-options).
+
+<Canvas of={exampleStories.Playground} />
+
+<Controls
+  of={exampleStories.Playground}
+  include={[
+    'className',
+    'children',
+    'href',
+    'variant',
+    'size',
+    'icon',
+    'iconPosition',
+    'underlined',
+    'isInline',
+    'isUnderlined',
+    'isReversed',
+    'isDisabled',
+  ]}
+/>
+
+## API
+
+This is built on top of [React Aria's Link component](https://react-spectrum.adobe.com/react-aria/Link.html)
+
+## Navigation and native anchor attributes
+
+Out of the box, `Link` supports the majority of native `anchor` attributes and shares the same basic behaviour, i.e. `href` will trigger new page loads.
+
+While client side routing is possible, the `Link` is agnostic to the routing technology chosen. Refer to our general set up guide to get started with [client side routing](#client-side-routing).
+
+#### Opening new tabs and accessibility considerations
+
+The general recommendation is to limit the number of links that open a new tab or window on a single page. While there are valid scenarios that can help avoid loss of data and or progress, as with links in forms, opening new tabs can be disorienting for users - especially for those who have difficulty perceiving visual content.
+
+In order to provide advance warning to all users, it is recommended that links using `target="_blank"` be accompanied by a visual indicator and audible warning. As shown in the following example, additional context can be provided via a visually hidden element within the `children` of the component.
+
+You may also consider using the `rel="noopener noreferrer"` attribute to prevent the new tab from accessing the `window.opener` object, which can be a security risk. Read more about this consideration on the [Lighthouse docs](https://developer.chrome.com/docs/lighthouse/best-practices/external-anchors-use-rel-noopener).
+
+<Canvas of={exampleStories.LinkOpensInNewTab} />
+
+For more context on this recommendation, we recommend taking a look at the [W3C page on the G200 success criteria](https://www.w3.org/TR/WCAG20-TECHS/G200.html).
+
+### Variants
+
+`Link` supports `primary`, `secondary` and `white` variants. If the `variant` prop is not specified, the default variant is `primary`.
+
+<Canvas of={exampleStories.LinkVariants} />
+
+<DocsStory of={exampleStories.LinkVariantWhite} expanded={false} />
+
+### Sizes
+
+Link supports the following sizes: `extra-small`, `small`, `body` and `intro-lede`. If the `size` prop is not specified, the default size is `body`.
+
+<Canvas of={exampleStories.LinkSizes} />
+
+### Links within Text
+
+The `isInline` prop can be toggled to have the `Link` inherit the sizing from the parent text element. This is useful when the `Link` is nested within a paragraph or other text element.
+
+### Link content and children
+
+Labels and any `Link` content can be passed to the component via `children`. Where possible, ensure `Link` does not break over multiple lines. [See the section](/docs/components-link-usage-guidelines--docs) for standalone links for guidance. For icons as content, refer to the [next section](#icons-and-positioning).
+
+```tsx
+<Link href="#link">Label</Link>
+```
+
+While in most cases, `children` will be a `ReactNode`, `Link` also accepts a render function with React Aria's `LinkRenderProps`. This allows for more advanced styling and rendering options by hooking into React Aria's internal Link state. You can read more about this [here](https://react-spectrum.adobe.com/react-aria/Link.html#styling).
+
+### Icons and positioning
+
+[This is the intended icon](docs/components-icon-icon-future-api-specification--docs) component to be used with `Link`. The `icon` property abstracts the need to handle positioning and sizing of icons within the `Link` component. The `iconPosition` prop allows for the icon to be positioned to the left or right of the `children`.
+
+### Icons and Underlines
+
+The underline on the `Link` can be toggled using the `isUnderlined` prop and is `true` by default. If the `Link` is not underlined, the `icon` prop must be passed. The `icon` prop is optional if the link is underlined.
+
+<Canvas of={exampleStories.LinkWithIconStart} />
+
+Setting the `iconPosition` props will ensure content is flipped in `RTL` layouts. Note that icons will need the [shouldMirrorInRTL](/docs/illustrations-icon-icon-future-api-specification--docs#mirror-in-rtl) prop set to `true` when mirroring is required.
+
+<Canvas of={exampleStories.LinkWithIconEnd} />
+
+## Client side routing
+
+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 `Link` component.
+
+## Additional API options
+
+The following table is a collection of additional React Aria and native HTML props that are exposed from the [React Aria Link API](https://react-spectrum.adobe.com/react-aria/Link.html). These are not required for the implementation of `LinkButton` but can be used to extend its functionality. Refer back to the [overview section](#overview) for the core props that enable most use cases.
+
+<ArgTypes
+  of={exampleStories.Playground}
+  exclude={[
+    'className',
+    'children',
+    'href',
+    'variant',
+    'size',
+    'icon',
+    'iconPosition',
+    'underlined',
+    'isInline',
+    'isUnderlined',
+    'isReversed',
+    'isDisabled',
+  ]}
+/>

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>,
+}