@kaizen/components 0.0.0-canary-package-bundler-v2-20241113071536 → 0.0.0-canary-link-button-wip-canary-20241121043208

package/src/__actions__/Button/v3/types.ts

@@ -0,0 +1,25 @@
+export type ButtonVariants = "primary" | "secondary" | "tertiary"
+
+export type ButtonSizes = "small" | "medium" | "large"
+
+export type PendingPropsUndefined = {
+  isPending?: undefined
+  /** Rendered as the child while `isPending` is `true`. This determines the accessible label for the Button while pending. */
+  pendingLabel?: never
+  /** Visually hides the `pendingLabel` and renders the loading spinner. This will maintain the width of the Button's `children` to avoid layout shifts.
+   * @default false
+   */
+  hasHiddenPendingLabel?: never
+}
+
+export type PendingProps = {
+  isPending: boolean
+  /** Rendered as the child while `pendingLabel` is `true`. This determines the accessible label for the Button while pending. */
+  pendingLabel: string
+  /** Visually Hides the `pendingLabel` and renders the loading spinner. This will maintain the width of the Button's `children` to avoid layout shifts.
+   * @default false
+   */
+  hasHiddenPendingLabel?: boolean
+}
+
+export type PendingButtonProps = PendingProps | PendingPropsUndefined

package/src/__actions__/LinkButton/index.ts

@@ -0,0 +1 @@
+export * from "./v3"

package/src/__actions__/LinkButton/v3/LinkButton.module.css

@@ -0,0 +1,4 @@
+.linkButton {
+  /* Reset */
+  text-decoration: inherit;
+}

package/src/__actions__/LinkButton/v3/LinkButton.tsx

@@ -0,0 +1,72 @@
+import React, { forwardRef } from "react"
+import {
+  Link as RACLink,
+  LinkProps as RACLinkProps,
+} from "react-aria-components"
+import { ButtonBaseProps } from "~components/__actions__/Button/v3"
+import buttonStyles from "~components/__actions__/Button/v3/Button.module.css"
+import { ButtonContent } from "~components/__actions__/Button/v3/subcomponents"
+import { useReversedColors } from "~components/__utilities__/v3"
+import { mergeClassNames } from "~components/utils/mergeClassNames"
+import styles from "./LinkButton.module.css"
+
+export type LinkButtonProps = ButtonBaseProps &
+  Omit<RACLinkProps, "children"> & {
+    /** Used as the label for the LinkButton. */
+    children: RACLinkProps["children"]
+  }
+
+export const LinkButton = forwardRef(
+  (
+    {
+      children,
+      variant = "primary",
+      size = "medium",
+      icon,
+      iconPosition = "start",
+      hasHiddenLabel = false,
+      isFullWidth = false,
+      isDisabled,
+      className,
+      ...otherProps
+    }: LinkButtonProps,
+    ref: React.ForwardedRef<HTMLAnchorElement>
+  ) => {
+    const isReversed = useReversedColors()
+
+    return (
+      <RACLink
+        ref={ref}
+        className={mergeClassNames(
+          styles.linkButton,
+          buttonStyles.button,
+          buttonStyles[size],
+          hasHiddenLabel && buttonStyles[`${size}IconButton`],
+          isDisabled && buttonStyles.isDisabled,
+          isReversed
+            ? buttonStyles[`${variant}Reversed`]
+            : buttonStyles[variant],
+          isFullWidth && buttonStyles.fullWidth,
+          className
+        )}
+        isDisabled={isDisabled}
+        {...otherProps}
+      >
+        {racStateProps => {
+          const childIsFunction = typeof children === "function"
+
+          return (
+            <ButtonContent
+              size={size}
+              icon={icon}
+              iconPosition={iconPosition}
+              hasHiddenLabel={hasHiddenLabel}
+            >
+              {childIsFunction ? children(racStateProps) : children}
+            </ButtonContent>
+          )
+        }}
+      </RACLink>
+    )
+  }
+)

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

@@ -0,0 +1,210 @@
+import { Canvas, Meta, Controls, ArgTypes, DocsStory } from "@storybook/blocks"
+import { ResourceLinks, KAIOInstallation } from "~storybook/components"
+import { LinkTo } from "../../../../../../../docs/components/LinkTo"
+import * as exampleStories from "./LinkButton.doc.stories"
+
+<Meta title="Actions/LinkButton/LinkButton (v3)/API Specification" />
+
+# Button API Specification (v3)
+
+Updated Nov 12, 2024
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__actions__/LinkButton/v3"
+  figma="https://www.figma.com/design/eZKEE5kXbEMY3lx84oz8iN/branch/sPhYSlgPScLOAOYfAbkaI5/%F0%9F%92%9C-Heart-UI-Kit?node-id=1929-17364&node-type=canvas&m=dev"
+  designGuidelines="/?path=/docs/actions-linkbutton-linkbutton-v3-usage-guidelines--docs"
+/>
+
+<KAIOInstallation exportNames={["LinkButton" ]} family="actions" version="3" />
+
+## Overview
+
+`LinkButton` allows users to navigate to another page or resource within a web page or application.
+
+The following example and table showcases the essential props that enable the core functionality of `LinkButton`. 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", "target", "download", "onPress", "routerOptions", "hasHiddenLabel",  "size", "variant", "icon", "iconPosition", "isFullWidth", "isDisabled" ]} />
+
+## API
+
+This is built on top of [React Aria's Link component](https://react-spectrum.adobe.com/react-aria/Link.html) and is the counterpart to the <LinkTo pageId="actions-button-button-v3-api-specification--docs">Kaizen Button</LinkTo>, handling icons, variants and sizes in the same way. It provides a semantic wrapper for navigational buttons and allows for native `href` navigation and client side routing with [additional configuration](#client-side-routing) .
+
+### Navigation and routing
+
+{/* // TODO: basic docs on href usage */}
+
+
+### Client side routing
+
+While the `LinkButton` supports native `href` navigation out of the box, it is agnostic to the routing technology chosen. As such, additional set up is required to support client side routing from `React Router` or `Next.js`.
+
+In order to achieve this, you can use the [RouterProvider](https://react-spectrum.adobe.com/react-aria/routing.html#routerprovider) from the `react-aria-components` library, along with the additional configuration for each routing solution.
+
+#### Next.js config example
+
+The following example demonstrates how to use the `RouterProvider` with `Next.js`'s Pages router. This will allow the `LinkButton` to navigate using the `router.push` method.
+
+```tsx
+import type {AppProps} from "next/app"
+import {type NextRouter, useRouter} from "next/router"
+import { RouterProvider } from "react-aria-components"
+
+// This provides the necessary typings for the routerOptions to uses of LinkButton across the app
+declare module "react-aria-components" {
+  interface RouterConfig {
+    routerOptions: NonNullable<Parameters<NextRouter["push"]>[2]>;
+  }
+}
+
+export default function NextPageRouterApp({ Component, pageProps }: AppProps) {
+  const router = useRouter()
+
+  return (
+    <RouterProvider
+      navigate={(href, opts) => router.push(href, undefined, opts)}
+    >
+      {/* ...application code */}
+    </RouterProvider>
+  )
+}
+```
+
+Additional notes on Next.js config can be found in the React Aria's documentation on the [RouterProvider](https://react-spectrum.adobe.com/react-aria/routing.html#routerprovider), including the alternative setup for the [App router](https://react-spectrum.adobe.com/react-aria/routing.html##app-router).
+
+#### React Router config example
+The following example demonstrates how to use the `RouterProvider` with `React Router`'s. This will allow the `LinkButton` to navigate using the `useNavigate` hook.
+
+```tsx
+import { RouterProvider } from "react-aria-components"
+import { BrowserRouter, NavigateOptions, useHref, useNavigate } from "react-router-dom"
+
+declare module "react-aria-components" {
+  interface RouterConfig {
+    routerOptions: NavigateOptions
+  }
+}
+
+function ReactRouterApp() {
+  const navigate = useNavigate()
+
+  return (
+    <RouterProvider navigate={navigate} useHref={useHref}>
+      {/* ...application code */}
+      <Routes>
+        <Route path="/" element={<HomePage />} />
+        {/* ...routes */}
+      </Routes>
+    </RouterProvider>
+  )
+}
+```
+
+Additional notes can be found in the React Aria's documentation on the using the `RouterProvider` with [React Router](https://react-spectrum.adobe.com/react-aria/routing.html#react-router).
+
+### Target `_blank` and opening in a new tab
+
+The general recommendation is to limit the number of links that open in a new tab or window on a page. While there are valid scenarios that help avoid loss of data and or progress on a page, opening a new tab or window can be disorienting for users, especially those who have difficulty perceiving visual content.
+
+In order to provide advance warning to all users, it is recommended that `LinkButton`'s that use `target="_blank"` be accompanied by a visual indicator and audible warning, as in the example below.
+
+<Canvas of={exampleStories.LinkButtonOpensInNewTab} />
+
+You can get more context on this recommendation via the [W3C page on the G200 success criteria](https://www.w3.org/TR/WCAG20-TECHS/G200.html).
+
+### Variants
+
+`LinkButton` supports the following variants: `primary`, `secondary` and `tertiary`. If the `variant` prop is not specified, the default will be `primary`.
+
+<Canvas of={exampleStories.LinkButtonVariants} />
+
+Reversed variants are handled via the `ReversedColors` Provider.
+
+<DocsStory of={exampleStories.LinkButtonVariantsReversed} expanded={false} />
+
+To enable the reversed theme, you will need to wrap the component or application in the `ReversedColors` provider, ie:
+
+```tsx
+import { RouterProvider } from "react-aria-components"
+import { Button } from "@kaizen/components/v3/actions"
+import { ReversedColors } from "@kaizen/components/v3/utilities"
+// application code
+
+return (
+  <ReversedColors isReversed={true}>
+    <LinkButton {...LinkbuttonProps} />
+  </ReversedColors>
+)
+```
+
+### Sizes
+
+LinkButton supports the following sizes: `small`, `medium` and `large`. If the `size` prop is not specified, the default will be `medium`.
+
+<Canvas of={exampleStories.LinkButtonSizes} />
+
+### `onPress`
+
+TODO: revamp this section: One key change to the `LinkButton`&apos;s API is the shift from `onClick` to React Aria's implementation of `onPress`. This approach has been adopted as it provides better support for consistent touch events across device types, such mobile, desktop and tablet. You can read more about the development and reason behind this pattern [here](https://react-spectrum.adobe.com/blog/building-a-button-part-1.html#touch-interactions).
+
+Functionally this does not change the way we pass actions into `LinkButton`. Consumers can safely replace `onClick` with `onPress` without any additional changes, ie:
+
+```tsx
+<LinkButton label="Submit" onClick={e => sumbit(e)}/>
+```
+
+Can safely be replaced with the following:
+
+```tsx
+<LinkButton onPress={e => submit(e)}>
+  Submit
+</LinkButton>
+```
+
+
+### Button content and children
+
+Labels and any button content can be passed into the `LinkButton` as `children`. Content wrapped by the `LinkButton` will be spaced evenly relative to the `size` prop.
+
+```tsx
+<LinkButton variant="secondary" href="#link">
+  Label
+</LinkButton>
+```
+
+While in most cases, `children` will be a `ReactNode`, `LinkButton` 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 button state. You can read more about this [here](https://react-spectrum.adobe.com/react-aria/Link.html#styling).
+
+### Icons and positioning
+
+The `icon` property abstracts the need to handle positioning and sizing logic for icons within the `LinkButton`. When paired with the [Icon component](/docs/illustrations-icon-icon-future-api-specification--docs), this will scale the icon to the `LinkButton`'s `size` prop.
+
+<Canvas of={exampleStories.LinkButtonWithIconStart} />
+
+Set the position of the icon using the `iconPosition` prop. This 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.LinkButtonWithIconEnd} />
+
+
+### Icon-only `LinkButton` and `hasHiddenLabel`
+
+To achieve an icon-only `LinkButton` (previously: `IconButton`) use the `icon` prop and set `hasHiddenLabel` to `true`. This will visually hide the button's `children`, while still announcing the content to screen readers.
+
+<Canvas of={exampleStories.IconLinkButton} />
+
+This pattern ensures that the `LinkButton`'s accessible name is determined by its children, which helps to announce relevant content to the screen readers. You can learn more about this [accessible pattern here](https://cultureamp.atlassian.net/wiki/spaces/PA/pages/3833331831/Accessible+button+and+link+labels).
+
+
+### Full width LinkButtons
+
+If a `LinkButton` is statically the full width of a container you can use the `isFullWidth` property.
+
+<Canvas of={exampleStories.LinkButtonFullWidth} />
+
+For resizing on smaller screens, consider using the `className` prop to leverage CSS media or container queries, ie: `<LinkButton className="w-full md:w-[initial]">Label</LinkButton>`.
+
+## 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", "target", "download", "routerOptions", "hasHiddenLabel",  "size", "variant", "onPress", "icon", "iconPosition", "isFullWidth", "isDisabled" ]}/>

package/src/__actions__/LinkButton/v3/_docs/LinkButton.doc.stories.tsx

@@ -0,0 +1,132 @@
+import React from "react"
+import { Meta, StoryObj } from "@storybook/react"
+import { VisuallyHidden } from "~components/VisuallyHidden"
+import { Icon } from "~components/__future__"
+import { ReversedColors } from "~components/__utilities__/v3"
+import { LinkButton } from "../index"
+
+const meta = {
+  title: "Actions/LinkButton/LinkButton (v3)",
+  component: LinkButton,
+  args: {
+    children: "Label",
+    href: "#link-button-clicked",
+    target: "_blank",
+  },
+} satisfies Meta<typeof LinkButton>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {}
+
+export const LinkButtonOpensInNewTab: Story = {
+  args: {
+    children: (
+      <>
+        Label
+        <VisuallyHidden> opens a new tab</VisuallyHidden>
+      </>
+    ),
+    href: "https://www.google.com",
+    target: "_blank",
+    icon: <Icon isPresentational name="open_in_new" shouldMirrorInRTL />,
+    iconPosition: "end",
+  },
+}
+
+export const LinkButtonVariants: Story = {
+  render: args => (
+    <>
+      <LinkButton {...args} variant="primary" />
+      <LinkButton {...args} variant="secondary" />
+      <LinkButton {...args} variant="tertiary" />
+    </>
+  ),
+  decorators: [
+    Story => (
+      <div className="flex gap-8">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export const LinkButtonVariantsReversed: Story = {
+  render: args => (
+    <ReversedColors isReversed={true}>
+      <LinkButton {...args} variant="primary" />
+      <LinkButton {...args} variant="secondary" />
+      <LinkButton {...args} variant="tertiary" />
+    </ReversedColors>
+  ),
+  parameters: {
+    reverseColors: true,
+  },
+  decorators: [
+    Story => (
+      <div className="flex gap-8 bg-purple-700 p-16">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export const LinkButtonSizes: Story = {
+  render: args => (
+    <>
+      <LinkButton {...args} size="small" />
+      <LinkButton {...args} size="medium" />
+      <LinkButton {...args} size="large" />
+    </>
+  ),
+  decorators: [
+    Story => (
+      <div className="[&>*]:ms-8">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export const LinkButtonWithIconStart: Story = {
+  args: {
+    icon: <Icon isPresentational name="delete" />,
+  },
+}
+
+export const LinkButtonWithIconEnd: Story = {
+  args: {
+    icon: <Icon isPresentational name="arrow_forward" shouldMirrorInRTL />,
+    iconPosition: "end",
+  },
+}
+
+export const IconLinkButton: Story = {
+  args: {
+    children: "Remove highlights from: May 8, 2024",
+    icon: <Icon isPresentational name="delete" />,
+    hasHiddenLabel: true,
+  },
+}
+
+export const ReversedLinkButton: Story = {
+  parameters: {
+    reverseColors: true,
+    docs: {
+      source: {
+        code: `<ReversedColors isReversed={true}>
+          <LinkButton>Label</LinkButton>
+        </ReversedColors>
+      `,
+      },
+    },
+  },
+}
+
+export const LinkButtonFullWidth: Story = {
+  args: {
+    isFullWidth: true,
+  },
+}

package/src/__actions__/LinkButton/v3/_docs/LinkButton.spec.stories.tsx

@@ -0,0 +1,100 @@
+import React from "react"
+import { Meta, StoryObj } from "@storybook/react"
+import { userEvent, waitFor, within, expect } from "@storybook/test"
+import { VisuallyHidden } from "~components/VisuallyHidden"
+import { Icon } from "~components/__future__/Icon"
+import { LinkButton } from "../index"
+
+const meta = {
+  title: "Actions/LinkButton/LinkButton (v3)/LinkButton (v3) tests",
+  component: LinkButton,
+  args: {
+    children: "Label",
+  },
+} satisfies Meta<typeof LinkButton>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const IconLinkButtonWithHiddenLabel: Story = {
+  args: {
+    hasHiddenLabel: true,
+    icon: <Icon name="add" isPresentational />,
+    children: (
+      <span>
+        Hidden label <span>is</span> <span>accessible</span>
+      </span>
+    ),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement.parentElement!)
+    const linkButton = canvas.getByRole("link")
+
+    expect(linkButton).toHaveAccessibleName("Hidden label is accessible")
+  },
+}
+
+export const RACRenderPropsWithChildren: Story = {
+  render: ({ children: _, ...otherArgs }) => (
+    <LinkButton {...otherArgs}>
+      {({ isFocusVisible }) => (
+        <>
+          Label
+          <VisuallyHidden>
+            {isFocusVisible ? " is focused" : " is unfocused"}
+          </VisuallyHidden>
+          <Icon
+            name={isFocusVisible ? "thumb_up" : "thumb_down"}
+            isPresentational
+            isFilled={true}
+            className="ms-8 [--icon-size:16]"
+          />
+        </>
+      )}
+    </LinkButton>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement.parentElement!)
+    const linkButton = canvas.getByRole("link")
+
+    await step("link icon reflects unfocused state", async () => {
+      await waitFor(() =>
+        expect(linkButton).toHaveAccessibleName("Label is unfocused")
+      )
+    })
+
+    await step("focus on link and update icon", async () => {
+      await userEvent.tab()
+      await waitFor(() =>
+        expect(linkButton).toHaveAccessibleName("Label is focused")
+      )
+    })
+  },
+}
+
+export const RACRenderPropsWithClassName: Story = {
+  args: {
+    className: ({ isFocusVisible }) => (isFocusVisible ? "!bg-gray-300" : ""),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement.parentElement!)
+    const linkButton = canvas.getByRole("link")
+    await linkButton.focus()
+  },
+}
+
+// Test cases:
+
+/**
+ * Can route to a new page when clicked
+ *
+ * has accepts routing options from a client side router (will have to mock this)
+ *
+ * can have href and onPress at the same item
+ *
+ * can have href, onPress and download
+ *
+ * ping will send a post request with body ping to URL
+ *
+ */