@kaizen/components 1.60.3 → 1.61.0

package/src/{__future__/Workflow → __layout__/Workflow/v1}/_docs/WorkflowHeader.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Controls, DocsStory, Meta } from "@storybook/blocks"
-import { KAIOInstallation, KaioLegacyDocsNotification, ResourceLinks } from "~storybook/components"
+import { Installation, ResourceLinks } from "~storybook/components"
 import * as WorkflowHeaderStories from "./WorkflowHeader.stories"
 
 <Meta of={WorkflowHeaderStories} />
@@ -13,10 +13,10 @@ import * as WorkflowHeaderStories from "./WorkflowHeader.stories"
 
 />
 
-
-<KaioLegacyDocsNotification version="1.16.0" />
-
-<KAIOInstallation exportNames="WorkflowHeader" isFuture />
+<Installation
+  installCommand="pnpm add @kaizen/components"
+  importStatement='import { Workflow } from "@kaizen/components/v1/layout"'
+/>
 
 ## Overview
 

package/src/{Workflow → __layout__/Workflow/v1}/_docs/WorkflowHeader.stories.tsx

@@ -6,7 +6,7 @@ import { Workflow } from "../"
 import { WorkflowControls } from "./controls"
 
 const meta = {
-  title: "Pages/Workflow/Components/Header",
+  title: "Layout/Workflow/Workflow (v1)/Components/Header",
   component: Workflow.Header,
   argTypes: {
     ...WorkflowControls.headerActions,

package/src/__layout__/Workflow/v1/index.ts

@@ -0,0 +1,10 @@
+// Since we can't add a deprecation flag on a * export
+import {
+  Workflow as WorkflowV1,
+  WorkflowProps as WorkflowPropsV1,
+} from "./Workflow"
+
+/** * @deprecated upgrade to v3 for the latest release */
+export const Workflow = WorkflowV1
+/** * @deprecated upgrade to v3 for the latest release */
+export type WorkflowProps = WorkflowPropsV1

package/src/{Workflow → __layout__/Workflow/v2}/_docs/ProgressStepper.mdx

@@ -1,6 +1,5 @@
 import { Canvas, Controls, DocsStory, Meta } from "@storybook/blocks"
-import { InlineNotification } from "~components/Notification"
-import { KAIOInstallation, ResourceLinks } from "~storybook/components"
+import { Installation, ResourceLinks } from "~storybook/components"
 import * as ProgressStepperStories from "./ProgressStepper.stories"
 
 <Meta of={ProgressStepperStories} />
@@ -14,12 +13,10 @@ import * as ProgressStepperStories from "./ProgressStepper.stories"
 
 />
 
-<InlineNotification type="negative" persistent>
-  {`This version of the Workflow is deprecated and will be removed in the next major release.
-  Import from "@kaizen/components/future" for the latest version.`}
-</InlineNotification>
-
-<KAIOInstallation exportNames="Workflow" />
+<Installation
+  installCommand="pnpm add @kaizen/components"
+  importStatement='import { Workflow } from "@kaizen/components/v2/layout"'
+/>
 
 ## Overview
 

package/src/{__future__/Workflow → __layout__/Workflow/v2}/_docs/ProgressStepper.stories.tsx

@@ -4,7 +4,7 @@ import { Workflow } from "../"
 import { WorkflowControls } from "./controls"
 
 const meta = {
-  title: "Pages/Workflow/Future/Components/Progress Stepper",
+  title: "Layout/Workflow/Workflow (v2)/Components/Progress Stepper",
   component: Workflow.ProgressStepper,
   argTypes: {
     currentStepId: WorkflowControls.currentStepId,

package/src/{__future__/Workflow → __layout__/Workflow/v2}/_docs/Workflow.mdx

@@ -1,5 +1,5 @@
 import { ArgTypes, Canvas, Meta } from "@storybook/blocks"
-import { KAIOInstallation, KaioLegacyDocsNotification, ResourceLinks } from "~storybook/components"
+import { Installation, ResourceLinks } from "~storybook/components"
 import * as Workflow from "./Workflow.stories"
 import * as WorkflowFooter from "./WorkflowFooter.stories"
 import * as WorkflowHeader from "./WorkflowHeader.stories"
@@ -13,10 +13,10 @@ import * as WorkflowHeader from "./WorkflowHeader.stories"
 
 />
 
-
-<KaioLegacyDocsNotification version="1.16.0" />
-
-<KAIOInstallation exportNames="Workflow" isFuture />
+<Installation
+  installCommand="pnpm add @kaizen/components"
+  importStatement='import { Workflow } from "@kaizen/components/v2/layout"'
+/>
 
 ## Overview
 

package/src/{__future__/Workflow → __layout__/Workflow/v2}/_docs/Workflow.stories.tsx

@@ -27,7 +27,7 @@ const MockContent = (): JSX.Element => (
 )
 
 const meta = {
-  title: "Pages/Workflow/Future",
+  title: "Layout/Workflow/Workflow (v2)",
   component: Workflow,
   argTypes: WorkflowControls,
   args: {

package/src/{Workflow → __layout__/Workflow/v2}/_docs/WorkflowFooter.mdx

@@ -1,6 +1,5 @@
 import { Canvas, Controls, DocsStory, Meta } from "@storybook/blocks"
-import { InlineNotification } from "~components/Notification"
-import { KAIOInstallation, ResourceLinks } from "~storybook/components"
+import { Installation, ResourceLinks } from "~storybook/components"
 import * as WorkflowFooterStories from "./WorkflowFooter.stories"
 
 <Meta of={WorkflowFooterStories} />
@@ -14,12 +13,10 @@ import * as WorkflowFooterStories from "./WorkflowFooter.stories"
 
 />
 
-<InlineNotification type="negative" persistent>
-  {`This version of the Workflow is deprecated and will be removed in the next major release.
-  Import from "@kaizen/components/future" for the latest version.`}
-</InlineNotification>
-
-<KAIOInstallation exportNames="Workflow" />
+<Installation
+  installCommand="pnpm add @kaizen/components"
+  importStatement='import { Workflow } from "@kaizen/components/v2/layout"'
+/>
 
 ## Overview
 

package/src/{__future__/Workflow → __layout__/Workflow/v2}/_docs/WorkflowFooter.stories.tsx

@@ -5,7 +5,7 @@ import { Workflow } from "../"
 import { WorkflowControls } from "./controls"
 
 const meta = {
-  title: "Pages/Workflow/Future/Components/Footer",
+  title: "Layout/Workflow/Workflow (v2)/Components/Footer",
   component: Workflow.Footer,
   argTypes: {
     ...WorkflowControls.nextAction,

package/src/{Workflow → __layout__/Workflow/v2}/_docs/WorkflowHeader.mdx

@@ -1,6 +1,5 @@
 import { Canvas, Controls, DocsStory, Meta } from "@storybook/blocks"
-import { InlineNotification } from "~components/Notification"
-import { KAIOInstallation, ResourceLinks } from "~storybook/components"
+import { Installation, ResourceLinks } from "~storybook/components"
 import * as WorkflowHeaderStories from "./WorkflowHeader.stories"
 
 <Meta of={WorkflowHeaderStories} />
@@ -14,12 +13,10 @@ import * as WorkflowHeaderStories from "./WorkflowHeader.stories"
 
 />
 
-<InlineNotification type="negative" persistent>
-  {`This version of the Workflow is deprecated and will be removed in the next major release.
-  Import from "@kaizen/components/future" for the latest version.`}
-</InlineNotification>
-
-<KAIOInstallation exportNames="Workflow" />
+<Installation
+  installCommand="pnpm add @kaizen/components"
+  importStatement='import { Workflow } from "@kaizen/components/v2/layout"'
+/>
 
 ## Overview
 

package/src/{__future__/Workflow → __layout__/Workflow/v2}/_docs/WorkflowHeader.stories.tsx

@@ -6,7 +6,7 @@ import { Workflow } from "../"
 import { WorkflowControls } from "./controls"
 
 const meta = {
-  title: "Pages/Workflow/Future/Components/Header",
+  title: "Layout/Workflow/Workflow (v2)/Components/Header",
   component: Workflow.Header,
   argTypes: {
     ...WorkflowControls.headerActions,

package/src/__layout__/Workflow/v2/index.ts

@@ -0,0 +1,10 @@
+// Since we can't add a deprecation flag on a * export
+import {
+  Workflow as WorkflowV2,
+  WorkflowProps as WorkflowPropsV2,
+} from "./Workflow"
+
+/** * @deprecated upgrade to v3 for the latest release */
+export const Workflow = WorkflowV2
+/** * @deprecated upgrade to v3 for the latest release */
+export type WorkflowProps = WorkflowPropsV2

package/src/__layout__/Workflow/v3/Workflow.tsx

@@ -0,0 +1,55 @@
+import React, { HTMLAttributes } from "react"
+import { OverrideClassName } from "~components/types/OverrideClassName"
+import {
+  Footer,
+  FooterProps,
+  Header,
+  Main,
+  HeaderProps,
+  ProgressStepper,
+  Wrapper,
+} from "./subcomponents"
+
+export type WorkflowProps = OverrideClassName<HTMLAttributes<HTMLDivElement>> &
+  FooterProps &
+  Pick<HeaderProps, "workflowName" | "statusTag" | "headerActions">
+
+export const Workflow = ({
+  steps,
+  currentStepId,
+  isComplete,
+  workflowName,
+  statusTag,
+  headerActions,
+  children,
+  nextAction,
+  previousAction,
+  classNameOverride,
+  ...restProps
+}: WorkflowProps): JSX.Element => {
+  const currentStep = steps.find(step => step.id === currentStepId)
+  return (
+    <Workflow.Wrapper classNameOverride={classNameOverride} {...restProps}>
+      <Workflow.Header
+        workflowName={workflowName}
+        stepName={currentStep!.label}
+        statusTag={statusTag}
+        headerActions={headerActions}
+      />
+      <Workflow.Main>{children}</Workflow.Main>
+      <Workflow.Footer
+        currentStepId={currentStepId}
+        steps={steps}
+        isComplete={isComplete}
+        nextAction={nextAction}
+        previousAction={previousAction}
+      />
+    </Workflow.Wrapper>
+  )
+}
+
+Workflow.Header = Header
+Workflow.Footer = Footer
+Workflow.Main = Main
+Workflow.ProgressStepper = ProgressStepper
+Workflow.Wrapper = Wrapper

package/src/__layout__/Workflow/v3/_docs/ProgressStepper.mdx

@@ -0,0 +1,37 @@
+import { Canvas, Controls, DocsStory, Meta } from "@storybook/blocks"
+import { Installation, ResourceLinks } from "~storybook/components"
+import * as ProgressStepperStories from "./ProgressStepper.stories"
+
+<Meta of={ProgressStepperStories} />
+
+# Progress Stepper
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/Workflow"
+  figma="https://www.figma.com/file/IJTy1JpS4Xyop5cQwroRje/%F0%9F%9B%A0%EF%B8%8F-Self-reflection%3A-Build-Handoff?node-id=188%3A62005&t=x4zyx07E2G3BmKGw-1"
+  designGuidelines="https://cultureamp.atlassian.net/wiki/spaces/DesignSystem/pages/3064989884/Documentation"
+/>
+
+<Installation
+  installCommand="pnpm add @kaizen/components"
+  importStatement='import { Workflow } from "@kaizen/components/v3/layout"'
+/>
+
+## Overview
+
+This component is used in the `Footer` to track progress of the Workflows steps.
+
+It has no reverse variant and should only be used in the Worflow's `Footer` component.
+
+<Canvas of={ProgressStepperStories.Playground} />
+<Controls of={ProgressStepperStories.Playground} />
+
+## API
+
+<DocsStory of={ProgressStepperStories.ProgressStates} />
+
+<DocsStory of={ProgressStepperStories.AllStepsComplete} />
+
+<DocsStory of={ProgressStepperStories.FewerSteps} />
+
+<DocsStory of={ProgressStepperStories.EightSteps} />

package/src/__layout__/Workflow/v3/_docs/ProgressStepper.stories.tsx

@@ -0,0 +1,86 @@
+import { Meta, StoryObj } from "@storybook/react"
+import { Workflow } from "../"
+import { WorkflowControls } from "./controls"
+
+const meta = {
+  title: "Layout/Workflow/Workflow (v3)/Components/Progress Stepper",
+  component: Workflow.ProgressStepper,
+  argTypes: {
+    currentStepId: WorkflowControls.currentStepId,
+  },
+  args: {
+    currentStepId: "preview-step",
+    steps: [
+      { label: "Settings", id: "settings-step" },
+      { label: "Questions", id: "questions-step" },
+      { label: "Preview", id: "preview-step" },
+      { label: "Employees", id: "employees-step" },
+      { label: "Schedule", id: "schedule-step" },
+    ],
+    isComplete: false,
+  },
+} satisfies Meta<typeof Workflow.ProgressStepper>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * <p>This component is used in the `Footer` to track progress of the Workflows steps.</p>
+ * <p>It has no reverse variant and should only be used in the Worflow's `Footer` component.</p>
+ */
+export const Playground: Story = {
+  parameters: {
+    docs: {
+      canvas: {
+        sourceState: "shown",
+      },
+    },
+  },
+}
+
+/** <p>To ensure WCAG AA compliance, there are 3 visually destinct states.</p>
+ * <p>These are reflected in their accessible names for screen reader: "Completed", "Current" and "Not started"</p>
+ */
+export const ProgressStates: Story = {
+  args: {
+    currentStepId: "questions-step",
+  },
+}
+
+/**
+ * <p>You can use the `isComplete` follow a successful submission to render all steps as complete.</p>
+ */
+export const AllStepsComplete: Story = {
+  args: {
+    currentStepId: "schedule-step",
+    isComplete: true,
+  },
+}
+
+export const FewerSteps: Story = {
+  args: {
+    currentStepId: "questions-step",
+    steps: [
+      { label: "Settings", id: "settings-step" },
+      { label: "Questions", id: "questions-step" },
+      { label: "Preview", id: "preview-step" },
+    ],
+  },
+}
+
+/**
+ * <p>We have baked in a container query to ensure the component can be responsive.</p>
+ * <p>When a step reaches its minimum size (4.5rem), it will hide the display name to maximise realestate.</p>
+ */
+export const EightSteps: Story = {
+  args: {
+    currentStepId: "questions-step",
+    steps: [
+      ...meta.args.steps,
+      { label: "Plan", id: "plan-step" },
+      { label: "Provision", id: "provision-step" },
+      { label: "Procure", id: "procure-step" },
+    ],
+  },
+}

package/src/__layout__/Workflow/v3/_docs/Workflow.mdx

@@ -0,0 +1,165 @@
+import { ArgTypes, Canvas, Meta } from "@storybook/blocks"
+import { Installation, ResourceLinks } from "~storybook/components"
+import * as Workflow from "./Workflow.stories"
+import * as WorkflowFooter from "./WorkflowFooter.stories"
+import * as WorkflowHeader from "./WorkflowHeader.stories"
+
+<Meta of={Workflow} />
+
+# Workflow
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/Workflow"
+
+/>
+
+<Installation
+  installCommand="pnpm add @kaizen/components"
+  importStatement='import { Workflow } from "@kaizen/components/v3/layout"'
+/>
+
+## Overview
+
+This is a page template component containing the header, footer, and main landmarks that compose a Workflow page. Its purpose is to guide a customer through a multi-step form to create a Workflow.
+
+The Worflow is intended as a page wrapper and sets a minimum height of `100vh` with a sticky `Header` component. The `Children` will be wrapped in an unstyled main landmark to provide flexibility for inner content layouts.
+
+To ensure at readability at 400% zoom (See WCAG's [Reflow criteria](https://www.w3.org/WAI/WCAG21/Understanding/reflow.html)) this component will collapse to a vertical layout on smaller screen sizes and remove `sticky` positioning to maximise screen real estate. You can see an example in [the responsive workflow story](/story/pages-workflow-components-workflow--responsive-workflow).
+
+<Canvas layout="fullscreen" of={Workflow.Playground} />
+
+## Header actions
+
+The `headerActions` prop  takes array of JSX elements that will render in the top right of the `Header` component.
+
+While the number of JSX elements is not limited, is important to consider the real estate in the `Header` and how larger strings or components may be rendered on smaller screen sizes.
+
+<Canvas
+  layout="fullscreen"
+  of={WorkflowHeader.MultipleActions}
+  source={{code: `<Workflow
+    headerActions={[
+      <Button
+        key="would-use-uui-1"
+        label="Preview"
+        icon={VisibleIcon}
+        secondary
+        iconPosition="start"
+      />,
+      <Button
+        key="would-use-uui-2"
+        label="Save and close"
+        icon={CloseIcon}
+        secondary
+        iconPosition="end"
+      />
+    ]}
+    {...otherProps}
+  >
+    <MockContent />
+  </Workflow>`}}
+/>
+
+
+## Handling a Workflow exit
+
+A common pattern identified is a Workflow Exit button. An implementation of this component should be passed to the `headerActions` an array to handle a user leaving a Workflow. We've provided an example below that combines a Kaizen `Button` with the `ConfirmationModal` component.
+
+<Canvas
+  layout="fullscreen"
+  of={WorkflowHeader.Playground}
+  source={{code: `
+  const [showModal, setShowModal] = useState<boolean>(false)
+  ...
+  return (
+    <>
+      <Button
+        label={exitLabel}
+        icon={closeIcon}
+        iconPosition="end"
+        secondary
+        onClick={() => setShowModal(true)}
+      />
+      <ConfirmationModal
+        isOpen={showModal}
+        mood={mood}
+        isProminent={true}
+        title={exitTitle}
+        confirmLabel={confirmExitLabel}
+        dismissLabel={dismissExitLabel}
+        onConfirm={onConfirmExitCallback}
+        onDismiss={() => {
+          setShowModal(false)
+        }}
+      >
+        <div>
+          <Text variant="body">{exitDescription}</Text>
+        </div>
+      </ConfirmationModal>
+    </>
+  )`
+  }}
+/>
+
+## Tracking progress
+
+The Footer tracks the progress of the form by using finding the index of the `currentStepId` within the `steps` array.
+
+<Canvas
+  layout="fullscreen"
+  of={WorkflowFooter.FirstStep}
+  source={{code: `<Workflow
+    currentStepId="settings-step"
+    steps={[
+      { label: "Settings", id: "settings-step" },
+      { label: "Questions", id: "questions-step" },
+      { label: "Preview", id: "preview-step" },
+      { label: "Employees", id: "employees-step" },
+      { label: "Schedule", id: "schedule-step" },
+    ]}
+    {...otherProps}
+  >
+    <MockContent />
+  </Workflow>`}}
+/>
+
+The Footer is agnostic to the JSX elements that are used in the `previousAction` and `nextAction`. While we recommend using the Kaizen Button, a button-like component can be used in its place to satisfy project-specific requirements.
+
+
+To hide, disable or change the appearance of the Footer buttons you can leverage the props available for the `@kaizen/button` or pass in undefined to not render the component.
+
+<Canvas
+  layout="fullscreen"
+  of={WorkflowFooter.LastStep}
+  source={{code: `<Workflow
+    nextAction={<Button disabled label="Finish" primary />}
+    previousAction={<Button label="Back" />}
+    {...otherProps}
+  >
+    <MockContent />
+  </Workflow>`}}
+/>
+
+In Instances where users are returning to a completed workflow you can pass the `isComplete` prop to set the indicators to their "complete" status. This will also be reflected in their Aria title.
+
+<Canvas
+  layout="fullscreen"
+  of={WorkflowFooter.AllStepsComplete}
+  source={{code: `<Workflow
+    isComplete
+    {...otherProps}
+  >
+    <MockContent />
+  </Workflow>`}}
+/>
+
+## Composable Worflow
+
+While we do not advise this path, a composable Workflow may be created if required. Refer to the component's stories on how to consume each subcomponent.
+
+<Canvas layout="fullscreen" of={Workflow.ComposableWorkflow} />
+
+
+## Worflow API at a glance
+
+<ArgTypes of={Workflow.Playground} />