@kaizen/components 0.0.0-canary-package-bundler-v2-20241113055116 → 0.0.0-canary-link-button-wip-canary-20241121010628

package/src/__actions__/Button/v3/Button.tsx

@@ -1,44 +1,110 @@
-import React from "react"
+import React, { forwardRef } from "react"
 import {
   Button as RACButton,
   ButtonProps as RACButtonProps,
 } from "react-aria-components"
 import { useReversedColors } from "~components/__utilities__/v3"
 import { mergeClassNames } from "~components/utils/mergeClassNames"
-import styles from "./Button.module.scss"
+import { ButtonContent, PendingContent } from "./subcomponents"
+import { ButtonSizes, ButtonVariants, PendingButtonProps } from "./types"
+import styles from "./Button.module.css"
 
-export type ButtonVariants = "default"
-
-export type ButtonProps = RACButtonProps & {
+export type ButtonBaseProps = {
+  /** Visually hides the Button's child content used as the label and the `pendingLabel`. Use for icon-only `Button`. @default "false" */
+  hasHiddenLabel?: boolean
   /** The visual style of the button.
    *  @default "default" */
   variant?: ButtonVariants
   /** The visual size of the button. `medium` was formerly `regular`
    *  @default "medium" */
-  size?: "small" | "medium"
+  size?: ButtonSizes
+  /** Renders an icon at the `iconPosition` provided. To the size scales with the button, we recommend using the `Icon` component from `"@kaizen/components/future"` */
+  icon?: JSX.Element
+  /** Controls the position of the Icon passed in as props. @default "start" */
+  iconPosition?: "start" | "end"
+  /** Controls if the button inherits width from its parent. @default "false" */
+  isFullWidth?: boolean
 }
 
-export const Button = ({
-  variant = "default",
-  className,
-  size = "medium",
-  children,
-  ...otherProps
-}: ButtonProps): JSX.Element => {
-  const isReversed = useReversedColors()
+export type ButtonProps = ButtonBaseProps &
+  PendingButtonProps &
+  Omit<RACButtonProps, "children"> & {
+    /** Used as the label for the button. */
+    children: RACButtonProps["children"]
+  }
 
-  return (
-    <RACButton
-      className={mergeClassNames(
-        styles.button,
-        styles[variant],
-        styles[size],
-        isReversed && styles.reversed,
-        className
-      )}
-      {...otherProps}
-    >
-      {children}
-    </RACButton>
-  )
-}
+export const Button = forwardRef(
+  (
+    {
+      variant = "primary",
+      size = "medium",
+      className,
+      children,
+      isDisabled,
+      isFullWidth = false,
+      icon,
+      iconPosition,
+      hasHiddenLabel = false,
+      isPending,
+      hasHiddenPendingLabel: propsHasHiddenPendingLabel = false,
+      pendingLabel,
+      ...restProps
+    }: ButtonProps,
+    ref: React.ForwardedRef<HTMLButtonElement>
+  ) => {
+    const isReversed = useReversedColors()
+    const pendingProps: PendingButtonProps = isPending
+      ? {
+          isPending,
+          hasHiddenPendingLabel: hasHiddenLabel || propsHasHiddenPendingLabel,
+          pendingLabel,
+        }
+      : {}
+    const buttonContentClass = isPending
+      ? !hasHiddenLabel && propsHasHiddenPendingLabel
+        ? styles.retainContentWidth
+        : styles.hideContentWidth
+      : undefined
+
+    return (
+      <RACButton
+        ref={ref}
+        className={mergeClassNames(
+          styles.button,
+          styles[size],
+          hasHiddenLabel && styles[`${size}IconButton`],
+          isDisabled && styles.isDisabled,
+          isReversed ? styles[`${variant}Reversed`] : styles[variant],
+          isFullWidth && styles.fullWidth,
+          className
+        )}
+        isDisabled={isDisabled}
+        isPending={isPending}
+        {...restProps}
+      >
+        {racStateProps => {
+          const childIsFunction = typeof children === "function"
+
+          return (
+            <>
+              <ButtonContent
+                size={size}
+                icon={icon}
+                iconPosition={iconPosition}
+                hasHiddenLabel={hasHiddenLabel}
+                className={buttonContentClass}
+              >
+                {childIsFunction ? children(racStateProps) : children}
+              </ButtonContent>
+              <span aria-live="polite">
+                {pendingProps.isPending && (
+                  <PendingContent {...pendingProps} size={size} />
+                )}
+              </span>
+            </>
+          )
+        }}
+      </RACButton>
+    )
+  }
+)

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

@@ -0,0 +1,151 @@
+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 "./Button.docs.stories"
+import * as specStories from "./Button.spec.stories"
+
+<Meta title="Actions/Button/Button (v3)/API Specification" />
+
+# Button API Specification (v3)
+
+Updated Nov 19, 2024
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__actions__/Button/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-button-button-v3-usage-guidelines--docs"
+/>
+
+<KAIOInstallation exportNames={["Button" ]} family="actions" version="3" />
+
+## Overview
+
+`Button` allows users to perform an action. If the component needs to navigate somewhere and can be opened in a new tab, use a <LinkTo pageId="actions-linkbutton-linkbutton-v3-api-specification--docs">LinkButton</LinkTo> instead.
+
+The following example and table showcases the essential props that enable the core functionality of `Button`. For the remaining suite of API options refer to [this section](#additional-api-options).
+
+<Canvas of={exampleStories.Playground} />
+
+<Controls of={exampleStories.Playground} className="mb-64" include={["children", "hasHiddenLabel", "className",  "size", "variant", "onPress", "icon", "iconPosition", "isFullWidth", "isDisabled", "isPending","pendingLabel", "hasHiddenPendingLabel" ]} />
+
+## Buttons and links
+
+The `Button` component does not support the `href` property or have any inbuilt routing support. This component is intended as a semantic button and should only be used to perform actions on a page. We advise against passing in an `anchor` tag as a child of the `Button` as this can lead to accessibility issues.
+
+A separate [LinkButton](?path=/docs/actions-linkbutton-linkbutton-v3-api-specification--docs) component has been created to handle page navigation and client side routing.
+
+## API
+
+This is built on top of [React Aria's Button component](https://react-spectrum.adobe.com/react-aria/Button.html#props) and seeks to provide a flexible API with convenient abstractions that handles variants, sizes, pending states and icons.
+
+### Variants
+
+`Button` supports the following variants: `primary`, `secondary` and `tertiary`. If the `variant` prop is not specified, the default will be `primary`.
+
+<Canvas of={exampleStories.ButtonVariants} />
+
+Reversed variants are handled via the `ReversedColors` Provider.
+
+<DocsStory of={exampleStories.ButtonVariantsReversed} expanded={false} />
+
+To enable the reversed theme, you will need to wrap the component or application in the `ReversedColors` provider, ie:
+
+```tsx
+import { Button } from "@kaizen/components/v3/actions"
+import { ReversedColors } from "@kaizen/components/v3/utilities"
+// application code
+
+return (
+  <ReversedColors isReversed={true}>
+    <Button {...buttonProps} />
+  </ReversedColors>
+)
+```
+
+### Sizes
+
+Button supports the following sizes: `small`, `medium` and `large`. If the `size` prop is not specified, the default will be `medium`.
+
+<Canvas of={exampleStories.ButtonSizes} />
+
+### `onPress` vs `onClick`
+
+One key change to the `Button`&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 `Button`. Consumers can safely replace `onClick` with `onPress` without any additional changes, ie:
+
+```tsx
+<Button label="Submit" onClick={e => sumbit(e)}/>
+```
+
+Can safely be replaced with the following:
+
+```tsx
+<Button onPress={e => submit(e)}>
+  Submit
+</Button>
+```
+
+### Button content and children
+
+Labels and any button content can be passed into the `Button` as `children`. Content wrapped by the `Button` will be spaced evenly relative to the `size` prop.
+
+```tsx
+<Button variant="secondary" onPress={e => submit(e)}>
+  Label
+</Button>
+```
+
+While in most cases, `children` will be a `ReactNode`, `Button` also accepts a render function with React Aria's `ButtonRenderProps`. 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/Button.html#styling).
+
+### Icons and positioning
+
+The `icon` property abstracts the need to handle positioning and sizing logic for icons within the `Button`. When paired with the [Icon component](/docs/illustrations-icon-icon-future-api-specification--docs), this will scale the icon to the `Button`'s `size` prop.
+
+<Canvas of={exampleStories.ButtonWithIconStart} />
+
+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.ButtonWithIconEnd} />
+
+
+### Icon-only `Button` and `hasHiddenLabel`
+
+To achieve an icon-only `Button` (previously: `IconButton`) use the `icon` prop and set `hasHiddenLabel` to `true`. This will visually hide the button's `children` and `pendingLabel`, while still announcing the content to screen readers.
+
+<Canvas of={exampleStories.IconButton} className="mb-32"  />
+
+This pattern ensures that the `Button`'s accessible name is determined by its children, which helps to announce relevant content to the screen readers, as with the [pending state](#pending-state). You can learn more about this [accessible pattern here](https://cultureamp.atlassian.net/wiki/spaces/PA/pages/3833331831/Accessible+button+and+link+labels).
+
+### Pending state
+
+`isPending` and `pendingLabel` are used to indicate that an interaction is in progress. This will disable the `Button`'s press events while rendering a loading spinner and `pendingLabel`.
+
+<Canvas of={specStories.PendingButton} />
+
+This can be paired with the `hasHiddenPendingLabel` prop to visually hide the `pendingLabel` and maintain the content width. This is ideal for avoid layout shifts when space is a commodity.
+
+The `pendingLabel` should be short and declarative as this will be announced to a screen reader regardless of its visibility.
+
+<Canvas of={specStories.PendingButtonWithHiddenPendingLabel} />
+
+As mentioned in the [previous section](#icon-only-button-and-hashiddenlabel), an icon-only `Button` uses `hasHiddenLabel` to visually hide both the `pendingLabel` and child content, so `hasHiddenPendingLabel` is not needed.
+
+<Canvas of={specStories.PendingIconButton} />
+
+
+### Full width Buttons
+
+If a button is statically the full width of a container you can use the `isFullWidth` property.
+
+<Canvas of={exampleStories.ButtonFullWidth} />
+
+For resizing on smaller screens, consider using the `className` prop to leverage CSS media or container queries, ie: `<Button className="w-full md:w-[initial]">Label</Button>`.
+
+## Additional API options
+
+The following table is a collection of additional React Aria and native HTML props that are exposed from the React Aria API. These are not required for the implementation of `Button` but can be used to extend its functionality. Refer back to the [overview section](#overview) for the core props that enable most use cases.
+
+You can learn more about React Aria's Button API and advance configuration options [here](https://react-spectrum.adobe.com/react-aria/Button.html#props).
+
+<ArgTypes of={exampleStories.Playground} exclude={["children", "hasHiddenLabel", "className",  "size", "variant", "onPress", "icon", "iconPosition", "isFullWidth", "isDisabled", "isPending", "pendingLabel", "hasHiddenPendingLabel" ]} />

package/src/__actions__/Button/v3/_docs/Button--usage-guidelines.mdx

@@ -0,0 +1,30 @@
+import { Canvas, Meta, Controls } from "@storybook/blocks"
+import { ResourceLinks, Installation } from "~storybook/components"
+import * as Button from "./Button.docs.stories"
+
+<Meta title="Actions/Button/Button (v3)/Usage Guidelines" />
+
+# Button (v3)
+
+Updated July 12, 2024
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__actions__/Button/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"
+  apiSpecification="/?path=/docs/actions-button-button-v3-api-specification--docs"
+/>
+
+<Installation
+  installCommand="pnpm add @kaizen/components"
+  importStatement='import { Button } from "@kaizen/components/v3/actions"'
+/>
+
+## Overview
+
+Buttons allow users to perform an action. They have multiple styles for various needs, and are ideal for calling attention to where a user needs to do something in order to move forward in a flow.
+
+<Canvas of={Button.Playground} />
+
+<Controls of={Button.Playground} include={["children", "variant", "size", "isDisabled", "icon", "iconPosition"]} className="mb-64" />
+
+

package/src/__actions__/Button/v3/_docs/Button.docs.stories.tsx

@@ -1,76 +1,138 @@
 import React from "react"
 import { action } from "@storybook/addon-actions"
 import { Meta, StoryObj } from "@storybook/react"
-import { ChevronDownIcon, ChevronUpIcon } from "~components/Icon"
+import { Badge } from "~components/Badge"
+import { Icon } from "~components/__future__"
+import { ReversedColors } from "~components/__utilities__/v3"
 import { Button } from "../index"
 
 const meta = {
-  title: "Actions/Button/Button (v3)/Doc Assets",
+  title: "Actions/Button/Button (v3)",
   component: Button,
   args: {
     children: "Label",
     onPress: action("Button onPress event"),
   },
+  argTypes: {
+    icon: {
+      options: ["delete", "arrow", "plus"],
+      mapping: {
+        delete: <Icon isPresentational name="delete" />,
+        arrow: <Icon isPresentational name="arrow_forward" />,
+        add: <Icon isPresentational name="add" />,
+      },
+    },
+  },
 } satisfies Meta<typeof Button>
 
 export default meta
 
 type Story = StoryObj<typeof meta>
 
-export const ButtonClassModifierWithRenderProps: Story = {
-  render: ({ children, ...otherArgs }) => (
-    <Button
-      {...otherArgs}
-      className={({ isPressed }) => (isPressed ? "!bg-gray-300" : "")}
-    >
-      {children}
-    </Button>
+export const Playground: Story = {}
+
+export const ButtonVariants: Story = {
+  render: args => (
+    <>
+      <Button {...args} variant="primary" />
+      <Button {...args} variant="secondary" />
+      <Button {...args} variant="tertiary" />
+    </>
+  ),
+  decorators: [
+    Story => (
+      <div className="flex gap-8">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export const ButtonVariantsReversed: Story = {
+  render: args => (
+    <ReversedColors isReversed={true}>
+      <Button {...args} variant="primary" />
+      <Button {...args} variant="secondary" />
+      <Button {...args} variant="tertiary" />
+    </ReversedColors>
   ),
   parameters: {
-    docs: {
-      source: {
-        code: `
-    <Button
-      {...otherArgs}
-      className={({ isPressed }) => (isPressed ? "!bg-gray-300" : "")}
-    >
-      {children}
-    </Button>
-      `,
-      },
-    },
+    reverseColors: true,
+    backgrounds: { default: "Purple 700" },
+  },
+  decorators: [
+    Story => (
+      <div className="flex gap-8">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export const ButtonSizes: Story = {
+  render: args => (
+    <>
+      <Button {...args} size="small" />
+      <Button {...args} size="medium" />
+      <Button {...args} size="large" />
+    </>
+  ),
+  decorators: [
+    Story => (
+      <div className="flex gap-8 items-center">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export const ButtonWithIconStart: Story = {
+  args: {
+    icon: <Icon isPresentational name="delete" />,
+  },
+}
+
+export const ButtonWithIconEnd: Story = {
+  args: {
+    icon: <Icon isPresentational name="arrow_forward" shouldMirrorInRTL />,
+    iconPosition: "end",
   },
 }
 
-export const ButtonContentWithRenderProps: Story = {
-  render: ({ children, ...otherArgs }) => (
-    <Button {...otherArgs}>
-      {({ isPressed }) => (
-        <>
-          {children}
-          {isPressed ? (
-            <ChevronDownIcon role="presentation" />
-          ) : (
-            <ChevronUpIcon role="presentation" />
-          )}
-        </>
-      )}
-    </Button>
+export const IconButton: Story = {
+  args: {
+    children: "Remove highlights from: May 8, 2024",
+    icon: <Icon isPresentational name="delete" />,
+    hasHiddenLabel: true,
+  },
+}
+
+export const ReversedButton: Story = {
+  render: args => (
+    <ReversedColors isReversed={true}>
+      <Button {...args} />
+    </ReversedColors>
   ),
   parameters: {
-    docs: {
-      source: {
-        code: `
-    <Button {...otherArgs}>
-      {({isPressed}) => (
-        <>
-          {children}
-          {isPressed ? <ChevronDownIcon role="presentation" /> : <ChevronUpIcon role="presentation" />}
-        </>
-      )}
-    </Button>
-      `,
-      },
-    },
+    backgrounds: { default: "Purple 700" },
+  },
+}
+
+export const ButtonFullWidth: Story = {
+  args: {
+    isFullWidth: true,
+  },
+}
+
+export const ButtonWithBadge: Story = {
+  args: {
+    children: (
+      <>
+        Label
+        <Badge classNameOverride="ms-8" size="small">
+          3
+        </Badge>
+      </>
+    ),
   },
 }