@kaizen/components 1.72.0 → 1.73.1

package/dist/esm/Link/subcomponents/LinkContent.mjs

@@ -0,0 +1,26 @@
+import React from 'react';
+import { mergeClassNames } from '../../utils/mergeClassNames.mjs';
+import styles from '../Link.module.css.mjs';
+var LinkIcon = function (_a) {
+  var icon = _a.icon;
+  return /*#__PURE__*/React.createElement("span", {
+    className: styles.icon
+  }, icon);
+};
+var LinkContent = function (_a) {
+  var children = _a.children,
+    icon = _a.icon,
+    iconPosition = _a.iconPosition,
+    isUnderlined = _a.isUnderlined;
+  var iconPositionStyling = iconPosition === 'start' ? styles.iconStart : styles.iconEnd;
+  return /*#__PURE__*/React.createElement("span", {
+    className: mergeClassNames(styles.linkContent, isUnderlined && styles.isUnderlined)
+  }, icon && iconPosition === 'start' && /*#__PURE__*/React.createElement(LinkIcon, {
+    icon: icon
+  }), /*#__PURE__*/React.createElement("span", {
+    className: mergeClassNames(icon && iconPositionStyling)
+  }, children), icon && iconPosition === 'end' && /*#__PURE__*/React.createElement(LinkIcon, {
+    icon: icon
+  }));
+};
+export { LinkContent };

package/dist/esm/index.mjs

@@ -316,6 +316,7 @@ export { InputSearch } from './Input/InputSearch/InputSearch.mjs';
 export { KaizenProvider } from './KaizenProvider/KaizenProvider.mjs';
 export { Label } from './Label/Label.mjs';
 export { LabelledMessage } from './LabelledMessage/LabelledMessage.mjs';
+export { Link } from './Link/Link.mjs';
 export { LikertScaleLegacy } from './LikertScaleLegacy/LikertScaleLegacy.mjs';
 export { LinkButton } from './LinkButton/LinkButton.mjs';
 export { LoadingGraphic } from './Loading/LoadingGraphic/LoadingGraphic.mjs';

package/dist/esm/utilitiesV3.mjs

@@ -316,6 +316,7 @@ export { InputSearch } from './Input/InputSearch/InputSearch.mjs';
 export { KaizenProvider } from './KaizenProvider/KaizenProvider.mjs';
 export { Label } from './Label/Label.mjs';
 export { LabelledMessage } from './LabelledMessage/LabelledMessage.mjs';
+export { Link } from './Link/Link.mjs';
 export { LikertScaleLegacy } from './LikertScaleLegacy/LikertScaleLegacy.mjs';
 export { LinkButton } from './LinkButton/LinkButton.mjs';
 export { LoadingGraphic } from './Loading/LoadingGraphic/LoadingGraphic.mjs';

package/dist/styles.css

@@ -5849,6 +5849,126 @@ input[type=range].InputRange-module_ratingScaleRange__gI-rs::-ms-thumb:not(:disa
     left: var(--spacing-md, 1.5rem);
   }
 }
+.Link-module_link__8oxip {
+  color: var(--link-text-color, var(--color-blue-500));
+  font-family: var(--typography-paragraph-body-font-family);
+  font-size: var(--link-font-size, inherit);
+  line-height: var(--link-line-height, inherit);
+  font-weight: var(--typography-paragraph-body-font-weight);
+  text-decoration: none;
+  position: relative;
+  white-space: nowrap;
+  outline: 0;
+}
+
+.Link-module_link__8oxip[data-focus-visible]::after {
+  content: '';
+  position: absolute;
+  background: transparent;
+  border-color: var(--color-blue-500);
+  border-radius: 0;
+  border-width: var(--border-focus-ring-border-width);
+  border-style: var(--border-focus-ring-border-style);
+  inset: calc(-1 * (var(--border-focus-ring-border-width) * 2) - 1px);
+}
+
+.Link-module_isUnderlined__qvbtS {
+  border-bottom: var(--spacing-1) solid var(--link-text-color, var(--color-blue-500));
+}
+
+.Link-module_icon__CXh2J > * {
+  vertical-align: text-bottom;
+  font-size: var(--icon-font-size, 1em);
+}
+
+.Link-module_iconStart__ZysGR {
+  margin-inline-start: var(--text-icon-gap, 0.5em);
+}
+
+.Link-module_iconEnd__-DTiD {
+  margin-inline-end: var(--text-icon-gap, 0.5em);
+}
+
+.Link-module_primary__bmhX0[data-hovered] {
+  --link-text-color: var(--color-blue-600);
+}
+
+.Link-module_primary__bmhX0[data-pressed] {
+  --link-text-color: var(--color-blue-700);
+}
+
+.Link-module_secondary__pyYIV {
+  --link-text-color: var(--color-purple-800);
+}
+
+.Link-module_secondary__pyYIV[data-hovered] {
+  --link-text-color: var(--color-gray-600);
+}
+
+.Link-module_secondary__pyYIV[data-pressed] {
+  --link-text-color: var(--color-black);
+}
+
+[class*='extra-small'] .Link-module_link__8oxip.Link-module_isInline__sznAm,
+.Link-module_extra-small__nScM0 {
+  --link-font-size: var(--typography-paragraph-extra-small-font-size);
+  --link-line-height: var(--typography-paragraph-extra-small-line-height);
+  --icon-font-size: 0.875rem;
+  --text-icon-gap: var(--spacing-2);
+}
+
+[class*='body'] .Link-module_link__8oxip.Link-module_isInline__sznAm,
+.Link-module_body__H4Jgj {
+  --link-font-size: var(--typography-paragraph-body-font-size);
+  --link-line-height: var(--typography-paragraph-body-line-height);
+  --icon-font-size: 1.25rem;
+  --text-icon-gap: var(--spacing-6);
+}
+
+[class*='intro-lede'] .Link-module_link__8oxip.Link-module_isInline__sznAm,
+.Link-module_intro-lede__38Y6J {
+  --link-font-size: var(--typography-paragraph-intro-lede-font-size);
+  --link-line-height: var(--typography-paragraph-intro-lede-line-height);
+  --icon-font-size: 1.5rem;
+  --text-icon-gap: var(--spacing-8);
+}
+
+[class*='small']:not([class*='extra-small']) .Link-module_link__8oxip.Link-module_isInline__sznAm,
+.Link-module_small__4kJcR {
+  --link-font-size: var(--typography-paragraph-small-font-size);
+  --link-line-height: var(--typography-paragraph-small-line-height);
+  --icon-font-size: 1rem;
+  --text-icon-gap: var(--spacing-4);
+}
+
+.Link-module_white__qQr6q {
+  --link-text-color: var(--color-white);
+}
+
+.Link-module_white__qQr6q[data-focus-visible]::after {
+  border-color: var(--color-blue-300);
+}
+
+.Link-module_white__qQr6q.Link-module_isDisabled__gvLNv {
+  --link-text-color: rgba(var(--color-white-rgb), 0.2);
+}
+
+.Link-module_reversed__IqX8B {
+  --link-text-color: var(--color-white);
+}
+
+.Link-module_reversed__IqX8B[data-focus-visible]::after {
+  border-color: var(--color-blue-300);
+}
+
+.Link-module_link__8oxip.Link-module_isDisabled__gvLNv {
+  --link-text-color: var(--color-gray-400);
+}
+
+.Link-module_reversed__IqX8B.Link-module_isDisabled__gvLNv {
+  --link-text-color: rgba(var(--color-white-rgb), 0.2);
+}
+
 /** THIS IS AN AUTOGENERATED FILE **/
 /** THIS IS AN AUTOGENERATED FILE **/
 /** THIS IS AN AUTOGENERATED FILE **/

package/dist/types/Link/Link.d.ts

@@ -0,0 +1,39 @@
+import React from 'react';
+import { type LinkProps as RACLinkProps } from 'react-aria-components';
+import { type TextProps } from "../Text";
+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 declare const Link: React.ForwardRefExoticComponent<LinkProps & React.RefAttributes<HTMLAnchorElement>>;
+export {};

package/dist/types/Link/index.d.ts

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

package/dist/types/Link/subcomponents/LinkContent.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from 'react';
+export type LinkContentProps = {
+    children: ReactNode;
+    icon?: JSX.Element;
+    iconPosition?: 'start' | 'end';
+    isUnderlined: boolean;
+};
+export declare const LinkContent: ({ children, icon, iconPosition, isUnderlined, }: LinkContentProps) => JSX.Element;

package/dist/types/index.d.ts

@@ -30,6 +30,7 @@ export * from './Input';
 export * from './KaizenProvider';
 export * from './Label';
 export * from './LabelledMessage';
+export * from './Link';
 export * from './LikertScaleLegacy';
 export * from './LinkButton';
 export * from './Loading';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaizen/components",
-  "version": "1.72.0",
+  "version": "1.73.1",
   "description": "Kaizen component library",
   "author": "Geoffrey Chong <geoff.chong@cultureamp.com>",
   "homepage": "https://cultureamp.design",
@@ -185,8 +185,8 @@
     "svgo": "^3.3.2",
     "tslib": "^2.8.1",
     "tsx": "^4.19.2",
-    "@kaizen/package-bundler": "2.0.4",
-    "@kaizen/design-tokens": "10.8.7"
+    "@kaizen/design-tokens": "10.8.7",
+    "@kaizen/package-bundler": "2.0.4"
   },
   "devDependenciesComments": {
     "sass": "Prevent deprecation warnings introduced in 1.80 as we plan to move away from sass",

package/src/Link/Link.module.css

@@ -0,0 +1,119 @@
+.link {
+  color: var(--link-text-color, var(--color-blue-500));
+  font-family: var(--typography-paragraph-body-font-family);
+  font-size: var(--link-font-size, inherit);
+  line-height: var(--link-line-height, inherit);
+  font-weight: var(--typography-paragraph-body-font-weight);
+  text-decoration: none;
+  position: relative;
+  white-space: nowrap;
+  outline: 0;
+}
+
+.link[data-focus-visible]::after {
+  content: '';
+  position: absolute;
+  background: transparent;
+  border-color: var(--color-blue-500);
+  border-radius: 0;
+  border-width: var(--border-focus-ring-border-width);
+  border-style: var(--border-focus-ring-border-style);
+  inset: calc(-1 * (var(--border-focus-ring-border-width) * 2) - 1px);
+}
+
+.isUnderlined {
+  border-bottom: var(--spacing-1) solid var(--link-text-color, var(--color-blue-500));
+}
+
+.icon > * {
+  vertical-align: text-bottom;
+  font-size: var(--icon-font-size, 1em);
+}
+
+.iconStart {
+  margin-inline-start: var(--text-icon-gap, 0.5em);
+}
+
+.iconEnd {
+  margin-inline-end: var(--text-icon-gap, 0.5em);
+}
+
+.primary[data-hovered] {
+  --link-text-color: var(--color-blue-600);
+}
+
+.primary[data-pressed] {
+  --link-text-color: var(--color-blue-700);
+}
+
+.secondary {
+  --link-text-color: var(--color-purple-800);
+}
+
+.secondary[data-hovered] {
+  --link-text-color: var(--color-gray-600);
+}
+
+.secondary[data-pressed] {
+  --link-text-color: var(--color-black);
+}
+
+[class*='extra-small'] .link.isInline,
+.extra-small {
+  --link-font-size: var(--typography-paragraph-extra-small-font-size);
+  --link-line-height: var(--typography-paragraph-extra-small-line-height);
+  --icon-font-size: 0.875rem;
+  --text-icon-gap: var(--spacing-2);
+}
+
+[class*='body'] .link.isInline,
+.body {
+  --link-font-size: var(--typography-paragraph-body-font-size);
+  --link-line-height: var(--typography-paragraph-body-line-height);
+  --icon-font-size: 1.25rem;
+  --text-icon-gap: var(--spacing-6);
+}
+
+[class*='intro-lede'] .link.isInline,
+.intro-lede {
+  --link-font-size: var(--typography-paragraph-intro-lede-font-size);
+  --link-line-height: var(--typography-paragraph-intro-lede-line-height);
+  --icon-font-size: 1.5rem;
+  --text-icon-gap: var(--spacing-8);
+}
+
+[class*='small']:not([class*='extra-small']) .link.isInline,
+.small {
+  --link-font-size: var(--typography-paragraph-small-font-size);
+  --link-line-height: var(--typography-paragraph-small-line-height);
+  --icon-font-size: 1rem;
+  --text-icon-gap: var(--spacing-4);
+}
+
+.white {
+  --link-text-color: var(--color-white);
+}
+
+.white[data-focus-visible]::after {
+  border-color: var(--color-blue-300);
+}
+
+.white.isDisabled {
+  --link-text-color: rgba(var(--color-white-rgb), 0.2);
+}
+
+.reversed {
+  --link-text-color: var(--color-white);
+}
+
+.reversed[data-focus-visible]::after {
+  border-color: var(--color-blue-300);
+}
+
+.link.isDisabled {
+  --link-text-color: var(--color-gray-400);
+}
+
+.reversed.isDisabled {
+  --link-text-color: rgba(var(--color-white-rgb), 0.2);
+}

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',
+  ]}
+/>