@kaizen/components 1.55.1 → 1.56.0

package/src/__actions__/Button/v2/Button/_docs/Button.stories.tsx

@@ -0,0 +1,170 @@
+import React, { useState } from "react"
+import { StoryObj, Meta } from "@storybook/react"
+import { ArrowForwardIcon, ArrowRightIcon } from "~components/Icon"
+import { LoadingInput } from "~components/Loading"
+import { TextField } from "~components/TextField"
+import { Button } from "../index"
+
+const meta = {
+  title: "Actions/Button/v2",
+  component: Button,
+  args: {
+    label: "Label",
+  },
+} satisfies Meta<typeof Button>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {
+  parameters: {
+    docs: {
+      canvas: {
+        sourceState: "shown",
+      },
+    },
+  },
+}
+
+export const Variants: Story = {
+  render: ({ reversed }) => (
+    <>
+      <Button label="Default" reversed={reversed} />
+      <Button label="Primary" primary reversed={reversed} />
+      <Button label="Destructive" destructive reversed={reversed} />
+      <Button label="Secondary" secondary reversed={reversed} />
+      {!reversed && (
+        <Button label="Secondary Destructive" secondary destructive />
+      )}
+    </>
+  ),
+  decorators: [
+    Story => (
+      <div style={{ display: "flex", gap: "1rem" }}>
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: { controls: { disable: true } },
+}
+
+export const Reversed: Story = {
+  ...Variants,
+  args: { reversed: true },
+  parameters: {
+    ...Variants.parameters,
+    backgrounds: { default: "Purple 700" },
+  },
+}
+
+export const Disabled: Story = {
+  args: { disabled: true },
+}
+
+const sourceCodeIcon = `
+import { Button, ArrowForwardIcon } from "@kaizen/components"
+
+<Button label="Label" icon={<ArrowForwardIcon role="presentation" />} />
+`
+
+export const Icon: Story = {
+  args: {
+    icon: <ArrowForwardIcon role="presentation" />,
+  },
+  parameters: {
+    docs: { source: { code: sourceCodeIcon } },
+  },
+}
+
+export const IconPosition: Story = {
+  args: {
+    icon: <ArrowRightIcon role="presentation" />,
+    iconPosition: "end",
+  },
+}
+
+export const Badge: Story = {
+  args: {
+    badge: { text: "3", variant: "active" },
+    secondary: true,
+  },
+}
+
+export const FullWidth: Story = {
+  args: { fullWidth: true },
+}
+
+export const Working: Story = {
+  render: () => (
+    <>
+      <Button label="Label" working workingLabel="Submitting" />
+      <Button
+        label="Label"
+        working
+        workingLabel="Submitting"
+        workingLabelHidden
+      />
+    </>
+  ),
+  decorators: [
+    Story => (
+      <div style={{ display: "flex", gap: "1rem" }}>
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: { controls: { disable: true } },
+}
+
+export const Loading: Story = {
+  render: () => <LoadingInput isAnimated width={13} />,
+  parameters: { controls: { disable: true } },
+}
+
+export const NativeFormButton: Story = {
+  render: () => (
+    <>
+      <form className="mb-6" id="unique-form-id">
+        <TextField labelText="Sample text field" defaultValue="content" />
+      </form>
+      <Button
+        label="Submit"
+        type="submit"
+        form="unique-form-id"
+        formTarget="_blank"
+        formAction="/"
+        formMethod="get"
+        formEncType="text/plain"
+        formNoValidate={false}
+      />
+    </>
+  ),
+  parameters: { controls: { disable: true } },
+}
+
+export const ResolveWorking: Story = {
+  render: () => {
+    const [state, setState] = useState<"Ready" | "Working" | "Completed">(
+      "Ready"
+    )
+    const handleClick = (): void => {
+      if (state === "Ready") {
+        setState("Working")
+        setTimeout(() => setState("Completed"), 3000)
+      } else {
+        setState("Ready")
+      }
+    }
+
+    return (
+      <Button
+        label={state}
+        working={state === "Working"}
+        workingLabel="Button is doing some work"
+        workingLabelHidden
+        onClick={handleClick}
+      />
+    )
+  },
+}

package/src/__actions__/Button/v2/Button/index.ts

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

package/src/__actions__/Button/v2/GenericButton/index.ts

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

package/src/__actions__/Button/v2/IconButton/_docs/IconButton.mdx

@@ -0,0 +1,24 @@
+import { Canvas, Controls, Meta } from "@storybook/blocks"
+import { ResourceLinks, KAIOInstallation, LinkTo } from "~storybook/components"
+import * as IconButtonStories from "./IconButton.stories"
+
+<Meta of={IconButtonStories} />
+
+# IconButton (v2)
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/Button/IconButton"
+  figma="https://www.figma.com/file/ZRfnoNUXbGZv4eVWLbF4Az/%F0%9F%96%BC%EF%B8%8F-Component-Gallery?type=design&node-id=5-539&mode=design&t=HKGcnRVyIDipQ2OI-0"
+  designGuidelines="https://cultureamp.atlassian.net/wiki/spaces/DesignSystem/pages/3062890984/Button"
+
+/>
+
+<KAIOInstallation exportNames="IconButton" family="actions" version="2" />
+
+## Overview
+
+A button with an icon and no visible text (a label is required for accessibility).
+Use any <LinkTo pageId="components-icons">Icon</LinkTo> component in the `icon` prop.
+
+<Canvas of={IconButtonStories.Playground} />
+<Controls of={IconButtonStories.Playground} />

package/src/__actions__/Button/v2/IconButton/_docs/IconButton.stories.tsx

@@ -0,0 +1,37 @@
+import React from "react"
+import { Meta, StoryObj } from "@storybook/react"
+import { AddIcon, MeatballsIcon } from "~components/Icon"
+import { IconButton } from "../index"
+
+const meta = {
+  title: "Actions/IconButton/v2",
+  component: IconButton,
+  argTypes: {
+    icon: {
+      options: ["MeatballsIcon", "AddIcon"],
+      control: { type: "radio" },
+      mapping: {
+        MeatballsIcon: <MeatballsIcon role="presentation" />,
+        AddIcon: <AddIcon role="presentation" />,
+      },
+    },
+  },
+  args: {
+    label: "icon button",
+    icon: <MeatballsIcon role="presentation" />,
+  },
+} satisfies Meta<typeof IconButton>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {
+  parameters: {
+    docs: {
+      canvas: {
+        sourceState: "shown",
+      },
+    },
+  },
+}

package/src/__actions__/Button/v2/IconButton/index.ts

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

package/src/__actions__/Button/v2/index.ts

@@ -0,0 +1,3 @@
+export type { CustomButtonProps } from "./GenericButton"
+export * from "../v1/Button"
+export * from "../v1/IconButton"

package/src/__actions__/Button/v3/Button.module.scss

@@ -0,0 +1,104 @@
+.button {
+  --button-min-height-width: var(--spacing-48);
+  --button-padding-x: calc(
+    #{var(--spacing-12)} - #{var(--border-solid-border-width)}
+  );
+  --button-padding-y: calc(
+    #{var(--spacing-8)} - #{var(--border-solid-border-width)}
+  );
+  --button-icon-size: var(--spacing-24);
+
+  // RESET
+  appearance: none;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  margin: 0;
+  border: none;
+  // RESET
+  border: var(--border-solid-border-width) var(--border-solid-border-style);
+  border-radius: var(--border-solid-border-radius);
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  text-align: left;
+  gap: var(--spacing-8);
+  font-family: var(--typography-button-primary-font-family);
+  font-weight: var(--typography-button-primary-font-weight);
+  font-size: var(--typography-button-primary-font-size);
+  line-height: var(--typography-button-primary-line-height);
+  min-height: var(--button-min-height-width);
+  min-width: var(--button-min-height-width);
+  outline: none;
+  position: relative;
+  padding: var(--button-padding-y) var(--button-padding-x);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+
+  &[data-focus-visible]::after {
+    content: "";
+    position: absolute;
+    background: transparent;
+    border-color: var(--color-blue-500);
+    border-radius: var(--border-focus-ring-border-radius);
+    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));
+  }
+
+  svg {
+    height: var(--button-icon-size);
+    width: var(--button-icon-size);
+  }
+}
+
+.default {
+  border-color: var(--color-gray-500);
+  color: var(--color-purple-800);
+
+  &[data-hovered],
+  &[data-focus-visible],
+  &[data-pressed] {
+    background-color: var(--color-gray-200);
+    border-color: var(--color-purple-800);
+  }
+
+  &[data-disabled] {
+    opacity: 0.3;
+  }
+
+  &.reversed {
+    background-color: transparent;
+    border-color: rgba(var(--color-white-rgb), 0.65);
+    color: var(--color-white);
+
+    &[data-hovered],
+    &[data-focus-visible] {
+      background-color: rgba(var(--color-white-rgb), 0.1);
+      border-color: var(--color-white);
+    }
+
+    &[data-focus-visible]::after {
+      border-color: var(--color-blue-300);
+    }
+
+    &[data-disabled]::after {
+      border-color: var(--color-gray-400);
+    }
+  }
+}
+
+.small {
+  // spacing-40 does not currently exist. Holding on adding this until the button rfc has been signed off
+  --button-min-height-width: 2.5rem;
+  --button-padding-x: calc(
+    #{var(--spacing-8)} - #{var(--border-solid-border-width)}
+  );
+  --button-padding-y: calc(
+    #{var(--spacing-8)} - #{var(--border-solid-border-width)}
+  );
+  --button-icon-size: var(--spacing-16);
+
+  gap: var(--spacing-8);
+}

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

@@ -0,0 +1,44 @@
+import React from "react"
+import {
+  Button as RACButton,
+  ButtonProps as RACButtonProps,
+} from "react-aria-components"
+import { useReversedColors } from "~components/__utilities__/v3"
+import { mergeClassNames } from "~utils/mergeClassNames"
+import styles from "./Button.module.scss"
+
+export type ButtonVariants = "default"
+
+export type ButtonProps = RACButtonProps & {
+  /** 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"
+}
+
+export const Button = ({
+  variant = "default",
+  className,
+  size = "medium",
+  children,
+  ...otherProps
+}: ButtonProps): JSX.Element => {
+  const isReversed = useReversedColors()
+
+  return (
+    <RACButton
+      className={mergeClassNames(
+        styles.button,
+        styles[variant],
+        styles[size],
+        isReversed && styles.reversed,
+        className
+      )}
+      {...otherProps}
+    >
+      {children}
+    </RACButton>
+  )
+}

package/src/__actions__/Button/v3/_docs/ApiSpecification.mdx

@@ -0,0 +1,173 @@
+import { Canvas, Meta, Controls } from "@storybook/blocks"
+import { ResourceLinks, SbContent, KAIOInstallation } from "~storybook/components"
+import * as docsStories from "./Button.docs.stories"
+import * as exampleStories from "./Button.stories"
+
+<Meta title="Actions/Button/v3/API specification" />
+
+<SbContent>
+  # Button API Specification (v3)
+
+
+  Updated July 15, 2024
+</SbContent>
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__actions__/Button/v3"
+  figma="https://www.figma.com/design/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-Heart-UI-Kit?m=auto&t=a6VcoKBJx6snn0ut-1"
+  ariaComponentPage="https://react-spectrum.adobe.com/react-aria/Button.html"
+  designGuidelines="/?path=/docs/actions-button-v3-usage-guidelines--docs"
+/>
+
+<SbContent className="mb-24">
+  <div className="bg-yellow-100 border-default border-yellow-400 rounded px-24">
+    ### Disclaimer
+
+    The `v3` of `Button` is a partial rebuild to support [Menu v3](/docs/actions-menu-v3-api-specification--docs). As the changes to the API between `v1/v2` to `v3` is significant, our recommendation is to hold on adopting this outside of `Menu` `v3` as it will have a limited set of options.
+  </div>
+</SbContent>
+
+<SbContent>
+  <KAIOInstallation exportNames={["Tooltip", "TooltipTrigger" ]} family="actions" version="3" />
+
+
+  ## Overview
+
+</SbContent>
+
+<Canvas of={exampleStories.Playground} />
+
+<SbContent className="mb-64">
+  ### React Aria
+
+  This component is built using the react-aria-components library and extends the [Button](https://react-spectrum.adobe.com/react-aria/Button.html) component.
+
+  As this shares the same core [anatomy](https://react-spectrum.adobe.com/react-aria/Button.html#anatomy), [props types](https://react-spectrum.adobe.com/react-aria/Button.html#anatomy) and [event handlers](https://react-spectrum.adobe.com/react-aria/Button.html#events), the guidance below is tailored to our implementation and should cover most known use cases of the Button.
+
+  For more scenarios that may not be present below, we recommend checkout out React Aria&apos;s documentation on the [Button's available hooks](https://react-spectrum.adobe.com/react-aria/Button.html#hooks) or [advanced customization](https://react-spectrum.adobe.com/react-aria/Button.html#advanced-customization) options.
+</SbContent>
+
+<SbContent>
+  ## API
+</SbContent>
+
+
+<Controls of={exampleStories.Playground} className="mb-64" />
+
+<SbContent className="mb-64">
+  ### onPress vs onClick
+
+  One key change to the `Button`&apos;s API is the shift from `onClick` to `onPress`. This will not require a change to the implementation of `onClick` logic, ie:
+  ```
+  <Button label="Submit" onClick={(e) => sumbit(e)}/>
+  // can safely be migrated to:
+  <Button onPress={(e) => submit(e)}>
+    Submit
+  </Button>
+  ```
+
+  React Aria&apos;s implementation of `onPress` 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).
+</SbContent>
+
+<SbContent>
+
+  ### Interactive states and styling pseudo-classes
+
+  Psuedo classes, such as `hover`, `focus` or `focus-visible`, are now targeted and styled with HTML data attributes that reflect the internal state of the React Aria Button (ie: `isHovered`, `isFocusVisible`).
+
+  When styling in CSS, it is recommended to use [data attributes](https://react-spectrum.adobe.com/react-aria/Button.html#styling), such as `:[data-hovered]` or `:[data-focus-visible]`, instead of using pseudo selectors like `:hover` or `:focus-visible`.
+
+  ```css
+  .button {
+    background-color: $color-white;
+    &:hover {
+      background-color: $color-gray-200;
+    }
+  }
+  // becomes
+  .button {
+    background-color: $color-white;
+    &:[data-hovered] {
+      background-color: $color-gray-200;
+    }
+  }
+  ```
+
+  #### Dynamic styles with ButtonRenderProps
+
+  As `Button` extends React Aria&apos;s functionality, `className` can now accept either a `string` or function that receives the `Button`&apos;s state for styling, such as `isPressed` or `isHovered`. This useful for add dynamic styling tweaks with Tailwind or other CSS-in-JS libraries.
+</SbContent>
+
+<Canvas of={docsStories.ButtonClassModifierWithRenderProps} sourceState="shown" />
+
+<SbContent className="mb-64">
+  This can also be styled in directly with Tailwind targeting the data attributes, ie:
+
+  ```tsx
+    <Button className="[&[data-focused='true']]:bg-blue-300">Label</Button>
+  ```
+
+  React Aria also offers a [Tailwind plugin](https://react-spectrum.adobe.com/react-aria/styling.html#plugin) that exposes the styling states of React Aria Components into Tailwind. This can make classes and allows you to leverage intellisense when working with React Aria components, ie:
+
+  ```tsx
+    <Button className="pressed:bg-blue-300">Label</Button>
+  ```
+
+
+  For more on styling with React Aria and other ways to extend the `Button`&apos;s styles, we recommend checking out the [docs here](https://react-spectrum.adobe.com/react-aria/Button.html#styling).
+</SbContent>
+
+<SbContent>
+  ### Icons, labels and content as children
+
+  In `v3`, labels, icons and their positions are controlled by the consumer as `children`. The immediate children of `Button` are spaced using `flex-gap` to ensure `RTL` can be supported out of the box for most cases.
+</ SbContent>
+
+<Canvas of={exampleStories.ButtonWithIcon} />
+
+<SbContent>
+  While the expected default is that `children` will be a `ReactNode`, it also accepts a render function that takes `ButtonRenderProps`. Similar to the className, this exposes the internal state (`isPressed`, `isHovered`, etc) of the button and can be used for conditional rendering.
+
+  ```tsx
+  <Button>
+    {({isPressed}) => (
+      <>
+        {isPressed && <PressHighlight />}
+        Press me
+      </>
+    )}
+  </Button>
+```
+</ SbContent>
+
+
+<SbContent>
+  ### Icon only buttons
+
+  To achieve the `IconButton` pattern in `v3`, we recommend passing an icon in as a the sole child. The label should be added to the icon&apos;s `aria-label` prop in the SVG Icon.
+</ SbContent>
+
+<Canvas of={exampleStories.IconButton} className="mb-32" />
+
+<SbContent className="mb-64">
+  We recommend against setting the `aria-label` on the `Button` itself, and letting the accessible label be [determined by the children](https://cultureamp.atlassian.net/wiki/spaces/PA/pages/3833331831/Accessible+button+and+link+labels). You can achieve this by using visually hidden elements as children, which will create an accessible label based off the contents of the button.
+</SbContent>
+
+<SbContent className="mb-64">
+  ### Reversed Colors
+
+  The `Button` uses the `useReversedColors` hook and `ReversedColors` provider to control the dark and light theme.
+
+  <Canvas className="bg-purple-600 mb-24" of={exampleStories.OnReversed} />
+
+  To enable the reversed theme, you will need to the component or application in the ReversedColors provider.
+</ SbContent>
+
+<SbContent>
+  ### Buttons and links
+
+  `v3` of the `Button` component does not support the `href` prop. While a `Link` component will be coming to Kaizen, we recommend using the `v2` of button if a `anchor` or routing link is needed.
+
+  We do not advise passing in an `anchor` tag as a child of the `Button` as this can lead to accessibility issues.
+</ SbContent>
+

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

@@ -0,0 +1,76 @@
+import React from "react"
+import { action } from "@storybook/addon-actions"
+import { Meta, StoryObj } from "@storybook/react"
+import { ChevronDownIcon, ChevronUpIcon } from "~components/Icon"
+import { Button } from "../index"
+
+const meta = {
+  title: "Actions/Button/v3/Doc Assets",
+  component: Button,
+  args: {
+    children: "Label",
+    onPress: action("Button onPress event"),
+  },
+} 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>
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `
+    <Button
+      {...otherArgs}
+      className={({ isPressed }) => (isPressed ? "!bg-gray-300" : "")}
+    >
+      {children}
+    </Button>
+      `,
+      },
+    },
+  },
+}
+
+export const ButtonContentWithRenderProps: Story = {
+  render: ({ children, ...otherArgs }) => (
+    <Button {...otherArgs}>
+      {({ isPressed }) => (
+        <>
+          {children}
+          {isPressed ? (
+            <ChevronDownIcon role="presentation" />
+          ) : (
+            <ChevronUpIcon role="presentation" />
+          )}
+        </>
+      )}
+    </Button>
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `
+    <Button {...otherArgs}>
+      {({isPressed}) => (
+        <>
+          {children}
+          {isPressed ? <ChevronDownIcon role="presentation" /> : <ChevronUpIcon role="presentation" />}
+        </>
+      )}
+    </Button>
+      `,
+      },
+    },
+  },
+}

package/src/__actions__/Button/v3/_docs/Button.mdx

@@ -0,0 +1,41 @@
+import { Canvas, Meta, Controls } from "@storybook/blocks"
+import { ResourceLinks, SbContent, Installation } from "~storybook/components"
+import * as Button from "./Button.stories"
+
+<Meta title="Actions/Button/v3/Usage Guidelines" />
+
+<SbContent>
+  # Button (v3)
+
+  Updated July 12, 2024
+</SbContent>
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__actions__/Button/v3"
+  figma="https://www.figma.com/design/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-Heart-UI-Kit?m=auto&t=a6VcoKBJx6snn0ut-1"
+  ariaComponentPage="https://react-spectrum.adobe.com/react-aria/Menu.html"
+  apiSpecification="/?path=/docs/actions-button-v3-api-specification--docs"
+/>
+
+<SbContent className="mb-24">
+  <div className="bg-yellow-100 border-default border-yellow-400 rounded px-24">
+    ### Disclaimer
+
+    The `v3` of `Button` is a partial rebuild to support [Menu v3](/docs/actions-menu-v3-api-specification--docs). As the changes to the API between `v1/v2` to `v3` is significant, our recommendation is to hold on adopting this outside of `Menu` `v3` as it will have a limited set of options.
+  </div>
+</SbContent>
+
+<SbContent>
+  <Installation
+    installCommand="pnpm add @kaizen/components"
+    importStatement='import { Button } from "@kaizen/components/v3/actions"'
+  />
+
+  ## Overview
+
+  This is the rebuild of the Button component - the main changes present in `v3` will relate to an updated API. More guidance will be provided following the completion of the Button RFC.
+</SbContent>
+
+<Canvas of={Button.Playground} />
+<Controls of={Button.Playground} include={["children", "variant", "isDisabled"]} className="mb-64" />
+