@kaizen/components 1.64.13 → 1.65.0

package/src/Filter/FilterSelect/FilterSelect.spec.tsx

@@ -48,7 +48,7 @@ describe("<FilterSelect>", () => {
   it("shows the options initially when isOpen is true", async () => {
     render(<FilterSelectWrapper isOpen />)
     await waitFor(() => {
-      expect(screen.queryByRole("listbox")).toBeVisible()
+      expect(screen.getByRole("listbox")).toBeVisible()
     })
   })
 
@@ -107,10 +107,82 @@ describe("<FilterSelect>", () => {
         render(<FilterSelectWrapper isOpen />)
         expect(screen.queryByRole("listbox")).toBeVisible()
         await waitFor(() => {
-          expect(screen.queryByRole("listbox")).toHaveFocus()
+          expect(screen.getAllByRole("option")[0]).toHaveFocus()
         })
       })
 
+      it("moves focus to the first item on ArrowDown if nothing has been selected", async () => {
+        render(<FilterSelectWrapper selectedKey={undefined} />)
+        const trigger = screen.getByRole("button", { name: "Coffee" })
+        await user.tab()
+        await waitFor(() => {
+          expect(trigger).toHaveFocus()
+        })
+        await user.keyboard("{ArrowDown}")
+
+        await waitFor(() => {
+          expect(screen.getAllByRole("option")[0]).toHaveFocus()
+        })
+      })
+      it("moves focus to the last item on ArrowUp if nothing has been selected", async () => {
+        render(<FilterSelectWrapper selectedKey={undefined} />)
+        const trigger = screen.getByRole("button", { name: "Coffee" })
+        await user.tab()
+        await waitFor(() => {
+          expect(trigger).toHaveFocus()
+        })
+        await user.keyboard("{ArrowUp}")
+
+        await waitFor(() => {
+          const options = screen.getAllByRole("option")
+          expect(options[options.length - 1]).toHaveFocus()
+        })
+      })
+      it("moves focus to the current selected item on Enter", async () => {
+        render(<FilterSelectWrapper selectedKey="hazelnut" />)
+        const trigger = screen.getByRole("button", {
+          name: "Coffee : Hazelnut",
+        })
+        await user.tab()
+        await waitFor(() => {
+          expect(trigger).toHaveFocus()
+        })
+        await user.keyboard("{Enter}")
+
+        await waitFor(() => {
+          expect(screen.getByRole("option", { name: "Hazelnut" })).toHaveFocus()
+        })
+      })
+      it("moves focus to the current selected item on ArrowUp", async () => {
+        render(<FilterSelectWrapper selectedKey="hazelnut" />)
+        const trigger = screen.getByRole("button", {
+          name: "Coffee : Hazelnut",
+        })
+        await user.tab()
+        await waitFor(() => {
+          expect(trigger).toHaveFocus()
+        })
+        await user.keyboard("{ArrowUp}")
+
+        await waitFor(() => {
+          expect(screen.getByRole("option", { name: "Hazelnut" })).toHaveFocus()
+        })
+      })
+      it("moves focus to the current selected item on ArrowDown", async () => {
+        render(<FilterSelectWrapper selectedKey="hazelnut" />)
+        const trigger = screen.getByRole("button", {
+          name: "Coffee : Hazelnut",
+        })
+        await user.tab()
+        await waitFor(() => {
+          expect(trigger).toHaveFocus()
+        })
+        await user.keyboard("{ArrowDown}")
+
+        await waitFor(() => {
+          expect(screen.getByRole("option", { name: "Hazelnut" })).toHaveFocus()
+        })
+      })
       it("closes when user hits the escape key", async () => {
         render(<FilterSelectWrapper isOpen />)
         expect(screen.queryByRole("listbox")).toBeVisible()
@@ -168,6 +240,29 @@ describe("<FilterSelect>", () => {
   })
 })
 
+describe("Stringified object values", () => {
+  it("finds selected option when value is a stringified object", () => {
+    const { getByRole } = render(
+      <FilterSelectWrapper
+        items={[
+          {
+            value: '{"sortBy":"creator_name","sortOrder":"asc"}',
+            label: "Created by A-Z",
+          },
+          {
+            value: '{"sortBy":"creator_name","sortOrder":"dsc"}',
+            label: "Created by Z-A",
+          },
+        ]}
+        selectedKey='{"sortBy":"creator_name","sortOrder":"asc"}'
+      />
+    )
+    expect(
+      getByRole("button", { name: "Coffee : Created by A-Z" })
+    ).toBeInTheDocument()
+  })
+})
+
 const defaultProps: FilterSelectProps = {
   label: "Coffee",
   isOpen: false,

package/src/Filter/FilterSelect/FilterSelect.tsx

@@ -78,6 +78,9 @@ export const FilterSelect = <Option extends SelectOption = SelectOption>({
   )
 
   const { buttonProps } = useButton(triggerProps, triggerRef)
+
+  // `aria-labelledby` and `aria-controls` are being remapped because the `buttonProps` ids generated by React Aria point to nothing.
+  // This should ideally be refactored but for now the `aria-controls` is set to the Filter's Listbox (menuProps.id) and the `aria-labelledby` to undefined so the accessible name is derived from the buttons content.
   const renderTriggerButtonProps = {
     ...buttonProps,
     "aria-labelledby": undefined,

package/src/Tabs/subcomponents/index.ts

@@ -2,4 +2,3 @@ export * from "./Tab"
 export * from "./TabList"
 export * from "./TabPanel"
 export * from "./TabPanels"
-export * from "./Tab"

package/src/__future__/Select/Select.spec.tsx

@@ -194,11 +194,13 @@ describe("<Select />", () => {
       })
 
       describe("Given the menu is opened", () => {
-        it("focuses the listbox initially", async () => {
-          const { getByRole } = render(<SelectWrapper defaultOpen />)
+        it("focuses on the first item", async () => {
+          const { getByRole, getAllByRole } = render(
+            <SelectWrapper defaultOpen />
+          )
           expect(getByRole("listbox")).toBeVisible()
           await waitFor(() => {
-            expect(getByRole("listbox")).toHaveFocus()
+            expect(getAllByRole("option")[0]).toHaveFocus()
           })
         })
         it("is closed when hits the escape key", async () => {

package/src/__future__/Select/_docs/Select.mdx

@@ -98,8 +98,6 @@ Set `isFullWidth` to `true` to have the Select span the full width of its contai
 
 By default, the Select's popover will attach itself to the `body` of the document using React's `createPortal`.
 
-You can change the default behaviour by providing a `portalContainerId` to attach this to different element in the DOM. This can help to resolve issues that may arise with `z-index` or having a Select in a modal.
+You can change the default behavior by providing a `portalContainerId` to attach this to different element in the DOM. This can help to resolve issues that may arise with `z-index` or having a Select in a modal.
 
 <Canvas of={SelectStories.PortalContainer} />
-
-There is currently a known issue whereby a selected option will cause the page to scroll to the top of the window on open (click on [default to see example](https://cultureamp.design/?path=/docs/components-select-future--docs#portals)). This can be solved by setting a `portalContainerId` to the closest parent of the Select.

package/src/__future__/Select/_docs/Select.stories.tsx

@@ -1,5 +1,6 @@
 import React from "react"
 import { Meta, StoryObj } from "@storybook/react"
+import { ContextModal } from "~components/Modal"
 import { RadioField, RadioGroup } from "~components/Radio"
 import { Select } from "../Select"
 import { SelectOption } from "../types"
@@ -170,25 +171,40 @@ export const FullWidth: Story = {
 export const PortalContainer: Story = {
   render: args => {
     const portalContainerId = "id--portal-container"
+
+    const [isOpen, setIsOpen] = React.useState(false)
+
+    const handleOpen = (): void => setIsOpen(true)
+    const handleClose = (): void => setIsOpen(false)
     return (
       <>
-        <div
-          id={portalContainerId}
-          className="flex gap-24 bg-gray-200 p-12 overflow-hidden h-[200px] relative"
-        >
-          <Select
-            {...args}
-            label="Default"
-            selectedKey="batch-brew"
-            id="id--select-default"
-          />
-          <Select
-            {...args}
-            label="Inner portal"
-            selectedKey="batch-brew"
-            id="id--select-inner"
-            portalContainerId={portalContainerId}
-          />
+        <div className=" h-[500px] mb-24 block bg-gray-100 flex flex-col gap-16 justify-center items-center">
+          Page content
+          <button
+            type="button"
+            className="border border-gray-500"
+            onClick={handleOpen}
+          >
+            Open Modal
+          </button>
+          <ContextModal
+            isOpen={isOpen}
+            onConfirm={handleClose}
+            onDismiss={handleClose}
+            title="Select test"
+          >
+            <div
+              className="flex gap-24 bg-gray-200 p-12"
+              id={portalContainerId}
+            >
+              <Select
+                {...args}
+                label="Select within a modal"
+                id="id--select-inner"
+                portalContainerId={portalContainerId}
+              />
+            </div>
+          </ContextModal>
         </div>
       </>
     )

package/src/__future__/Select/subcomponents/ListBox/ListBox.tsx

@@ -1,6 +1,8 @@
-import React, { HTMLAttributes } from "react"
+import React, { HTMLAttributes, Key, useEffect, useRef, ReactNode } from "react"
 import { AriaListBoxOptions, useListBox } from "@react-aria/listbox"
+import { SelectState } from "@react-stately/select"
 import classnames from "classnames"
+import { useIsClientReady } from "~components/__utilities__/useIsClientReady"
 import { OverrideClassName } from "~components/types/OverrideClassName"
 import { useSelectContext } from "../../context"
 import { SelectOption, SelectItem } from "../../types"
@@ -9,25 +11,75 @@ import styles from "./ListBox.module.scss"
 export type SingleListBoxProps<Option extends SelectOption> = OverrideClassName<
   HTMLAttributes<HTMLUListElement>
 > & {
-  children: React.ReactNode
+  children: ReactNode
   /** Props for the popup. */
   menuProps: AriaListBoxOptions<SelectItem<Option>>
 }
 
+/** A util to retrieve the key of the correct focusable items based of the focus strategy
+ * This is used to determine which element from the collection to focus to on open base on the keyboard event
+ * ie: UpArrow will set the focusStrategy to "last"
+ */
+const getOptionKeyFromCollection = (
+  state: SelectState<SelectItem<any>>
+): Key | null => {
+  if (state.selectedItem) {
+    return state.selectedItem.key
+  } else if (state.focusStrategy === "last") {
+    return state.collection.getLastKey()
+  }
+  return state.collection.getFirstKey()
+}
+
+/** This makes the use of query selector less brittle in instances where a failed selector is passed in
+ */
+const safeQuerySelector = (selector: string): HTMLElement | null => {
+  try {
+    return document.querySelector(selector)
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error("Kaizen querySelector failed:", error)
+    return null
+  }
+}
+
 export const ListBox = <Option extends SelectOption>({
   children,
   menuProps,
   classNameOverride,
   ...restProps
 }: SingleListBoxProps<Option>): JSX.Element => {
+  const isClientReady = useIsClientReady()
   const { state } = useSelectContext<Option>()
-  const ref = React.useRef<HTMLUListElement>(null)
+  const ref = useRef<HTMLUListElement>(null)
   const { listBoxProps } = useListBox(
-    { ...menuProps, disallowEmptySelection: true },
+    {
+      ...menuProps,
+      disallowEmptySelection: true,
+      // This is to ensure that the listbox doesn't use React Aria's auto focus feature for Listbox, which creates a visual bug
+      autoFocus: false,
+    },
     state,
     ref
   )
 
+  /**
+   * This uses the new useIsClientReady to ensure document exists before trying to querySelector and give the time to focus to the correct element
+   */
+  useEffect(() => {
+    if (isClientReady) {
+      const optionKey = getOptionKeyFromCollection(state)
+      const focusToElement = safeQuerySelector(`[data-key='${optionKey}']`)
+
+      if (focusToElement) {
+        focusToElement.focus()
+      } else {
+        // If an element is not found, focus on the listbox. This ensures the list can still be navigated to via keyboard if the keys do not align to the data attributes of the list items.
+        ref.current?.focus()
+      }
+    }
+  }, [isClientReady])
+
   return (
     <ul
       ref={ref}

package/src/__future__/Select/subcomponents/Overlay/Overlay.tsx

@@ -36,7 +36,7 @@ export const Overlay = <Option extends SelectOption>({
       {...restProps}
     >
       {/* eslint-disable-next-line jsx-a11y/no-autofocus */}
-      <FocusScope autoFocus restoreFocus>
+      <FocusScope autoFocus={false} restoreFocus>
         <DismissButton onDismiss={state.close} />
         {children}
         <DismissButton onDismiss={state.close} />

package/src/__future__/Tabs/Tabs.tsx

@@ -0,0 +1,18 @@
+import React from "react"
+import {
+  Tabs as RACTabs,
+  TabsProps as RACTabsProps,
+  Key as RACKey,
+} from "react-aria-components"
+
+export type TabsProps = Omit<RACTabsProps, "orientation">
+export type Key = RACKey
+
+/**
+ * {@link https://cultureamp.atlassian.net/wiki/spaces/DesignSystem/pages/3081929117/Tabs Guidance} |
+ * {@link https://cultureamp.design/?path=/docs/components-tabs--controlled Storybook}
+ *
+ * Wrapper around all of the tab subcomponents
+ * Holds a TabList and TabPanels
+ */
+export const Tabs = (props: TabsProps): JSX.Element => <RACTabs {...props} />

package/src/__future__/Tabs/_docs/Tabs--api-specification.mdx

@@ -0,0 +1,43 @@
+import { Canvas, Controls, Meta } from "@storybook/blocks"
+import { ResourceLinks, KAIOInstallation } from "~storybook/components"
+import * as TabsStories from "./Tabs.stories"
+
+<Meta title="Components/Tabs/Tabs (Future)/API Specification" />
+
+# Tabs
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/Tabs"
+  figma="https://www.figma.com/file/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-UI-Kit%3A-Heart?type=design&node-id=1929%3A28886&mode=design&t=AGMmnoJia9RscurE-1"
+  designGuidelines="https://cultureamp.atlassian.net/wiki/spaces/DesignSystem/pages/3081929117/Tabs"
+
+/>
+
+<KAIOInstallation
+  exportNames={["Tabs", "TabList", "Tab", "TabPanel"]}
+  isFuture
+/>
+
+## Overview
+
+<Canvas of={TabsStories.Playground} />
+<Controls of={TabsStories.Playground} />
+
+## Uncontrolled vs controlled
+
+This component is uncontrolled by default. You can specify a default active tab on load with `defaultSelectedKey`.
+
+If you need to control the state of the active tabs on the consuming side, use the `selectedKey` prop instead of `defaultSelectedKey`, and hook into `onSelectionChange`.
+
+<Canvas of={TabsStories.Controlled} />
+
+
+## `tablist|tab` role vs `nav|link`
+
+This component implements the `tablist` role and WAI ARIA guidelines for tabs:
+https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role
+https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
+
+It's not intended to be used for a navigation bar where you need links wrapped in a `<nav>` instead.
+
+If you really need to, you can add a URL history change here (using onChange), but that's probably a sign that this component is being misused.

package/src/__future__/Tabs/_docs/Tabs--migration-guide.mdx

@@ -0,0 +1,93 @@
+import { Meta } from "@storybook/blocks"
+
+<Meta title="Components/Tabs/Tabs (Future)/Migration Guide" />
+
+# Future Tabs migration guide
+
+A brief guide on how and why to migrate from Kaizen's current `Tabs` to the `future` release.
+
+## Why the change?
+
+Current Tabs uses the Reach UI library under the hood, which is no longer actively maintained. This switches the library used internally to React Aria Components.
+
+## Component and API changes at a glance
+
+The Reach UI and React Aria APIs are fairly similar so there's not too much to adjust.
+
+The biggest adjustment is that you now need to provide an `id` for each `<Tab>` and match it with the one on `<TabPanel>`
+
+Additionally:
+- `<TabPanel>`s no longer needs to be wrapped in a `<TabPanels>` component
+- `classNameOverride` changes to `className`
+- `<Tabs defaultIndex={}>` changes to `<Tabs defaultSelectedKey={}>`
+- `<Tabs index={}>` changes to `<Tabs selectedKey={}>`
+- `<Tabs onChange={}>` changes to `<Tabs onSelectionChange={}>`
+- `<Tab disabled>` changes to `<Tab isDisabled>`
+
+## Migration examples
+
+### Uncontrolled
+
+#### Before
+
+```tsx
+<Tabs defaultIndex={1}>
+  <TabList>
+    <Tab>Tab 1</Tab>
+    <Tab>Tab 2</Tab>
+    <Tab disabled>Disabled tab</Tab>
+  </TabList>
+  <TabPanels>
+    <TabPanel classNameOverride="p-4">Content 1</TabPanel>
+    <TabPanel>Content 2</TabPanel>
+    <TabPanel>Disabled content</TabPanel>
+  </TabPanels>
+</Tabs>
+```
+
+#### After
+
+```tsx
+<Tabs defaultSelectedKey="two">
+  <TabList>
+    <Tab id="one">Tab 1</Tab>
+    <Tab id="two">Tab 2</Tab>
+    <Tab id="three" isDisabled>Disabled tab</Tab>
+  </TabList>
+  <TabPanel id="one" className="p-4">Content 1</TabPanel>
+  <TabPanel id="two">Content 2</TabPanel>
+</Tabs>
+```
+
+### Controlled
+
+#### Before
+
+```tsx
+<Tabs onChange={setSelectedTab} defaultIndex={1}>
+  <TabList>
+    <Tab>Tab 1</Tab>
+    <Tab>Tab 2</Tab>
+    <Tab disabled>Disabled tab</Tab>
+  </TabList>
+  <TabPanels>
+    <TabPanel>Content 1</TabPanel>
+    <TabPanel>Content 2</TabPanel>
+    <TabPanel>Disabled content</TabPanel>
+  </TabPanels>
+</Tabs>
+```
+
+#### After
+
+```tsx
+<Tabs onSelectionChange={setSelectedTab} selectedKey="two">
+  <TabList>
+    <Tab id="one">Tab 1</Tab>
+    <Tab id="two">Tab 2</Tab>
+    <Tab id="three" isDisabled>Disabled tab</Tab>
+  </TabList>
+  <TabPanel id="one">Content 1</TabPanel>
+  <TabPanel id="two">Content 2</TabPanel>
+</Tabs>
+```

package/src/__future__/Tabs/_docs/Tabs.stories.tsx

@@ -0,0 +1,74 @@
+import React, { useState } from "react"
+import { Meta, StoryObj } from "@storybook/react"
+import { Text } from "~components/Text"
+import { Button } from "~components/__actions__/v2"
+import { Tab, TabList, TabPanel, Tabs, Key } from "../index"
+
+const meta = {
+  title: "Components/Tabs/Tabs (Future)",
+  component: Tabs,
+  args: {
+    children: (
+      <>
+        <TabList aria-label="Tabs">
+          <Tab id="one">Tab 1</Tab>
+          <Tab id="two">Tab 2</Tab>
+          <Tab id="three" badge="3">
+            Tab 3
+          </Tab>
+          <Tab id="four" isDisabled>
+            Disabled Tab
+          </Tab>
+        </TabList>
+        <TabPanel id="one" className="p-24">
+          <Text variant="body">Content 1</Text>
+        </TabPanel>
+        <TabPanel id="two" className="p-24">
+          <Text variant="body">Content 2</Text>
+        </TabPanel>
+        <TabPanel id="three" className="p-24">
+          <Text variant="body">Content 3</Text>
+        </TabPanel>
+      </>
+    ),
+  },
+} satisfies Meta<typeof Tabs>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {
+  parameters: {
+    chromatic: { disable: false },
+    docs: {
+      canvas: {
+        sourceState: "shown",
+      },
+    },
+  },
+  args: {
+    defaultSelectedKey: "one",
+    // eslint-disable-next-line no-console
+    onSelectionChange: (key): void => console.log("Tab changed to ", key),
+  },
+}
+
+export const Controlled: Story = {
+  render: args => {
+    const [selectedKey, setSelectedKey] = useState<Key>(0)
+    return (
+      <>
+        <Tabs
+          {...args}
+          selectedKey={selectedKey}
+          onSelectionChange={setSelectedKey}
+        />
+        <Button
+          label="Switch to tab 2"
+          onClick={(): void => setSelectedKey("two")}
+        />
+      </>
+    )
+  },
+}

package/src/__future__/Tabs/index.ts

@@ -0,0 +1,2 @@
+export * from "./Tabs"
+export * from "./subcomponents"

package/src/__future__/Tabs/subcomponents/Tab/Tab.module.css

@@ -0,0 +1,94 @@
+.tab {
+  display: inline-flex;
+  align-items: center;
+  border: 2px solid transparent;
+  border-bottom: 0;
+  border-top-left-radius: var(--border-borderless-border-radius);
+  border-top-right-radius: var(--border-borderless-border-radius);
+  background: var(--color-white);
+  white-space: nowrap;
+  text-decoration: none;
+  padding: var(--spacing-md) var(--spacing-md);
+  margin: 0;
+  font-family: var(--typography-heading-4-font-family);
+  font-size: var(--typography-heading-4-font-size);
+  font-weight: var(--typography-heading-4-font-weight);
+  line-height: var(--typography-heading-4-line-height);
+  letter-spacing: var(--typography-heading-4-letter-spacing);
+  color: var(--color-purple-800);
+
+  &:focus {
+    outline: none;
+  }
+
+  &:focus-visible {
+    background: var(--color-blue-100);
+    color: var(--color-blue-500);
+    border-color: var(--color-blue-500);
+  }
+
+  &[data-disabled] {
+    opacity: 0.3;
+  }
+
+  &:not(:first-child) {
+    margin-inline-start: var(--spacing-xs);
+  }
+
+  &:not([data-disabled]):hover {
+    background: var(--color-blue-100);
+    color: var(--color-blue-500);
+  }
+}
+
+.tab[data-selected] {
+  position: relative;
+  color: var(--color-blue-500);
+
+  &::before {
+    content: "";
+    display: block;
+    border-top-left-radius: 5px;
+    border-top-right-radius: 5px;
+    background-color: currentcolor;
+    height: 5px;
+    width: 100%;
+    position: absolute;
+    left: 0;
+    right: 0;
+    bottom: 0;
+  }
+}
+
+.badge {
+  margin-inline-start: var(--spacing-sm);
+  display: inline-flex;
+  align-items: center;
+}
+
+@media (forced-colors: active) {
+  .tab {
+    border: 2px solid transparent;
+
+    &:focus-visible::after {
+      content: "";
+      position: absolute;
+      background: transparent;
+      border-radius: var(--border-focus-ring-border-radius);
+      border-width: var(--border-focus-ring-border-width);
+      border-style: var(--border-focus-ring-border-style);
+      border-color: transparent;
+      inset: -2px;
+    }
+  }
+
+  .tab[data-selected]::before {
+    /* High contrast also doesn't see the pseudo element created to show the active tab. */
+    content: "";
+    position: absolute;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    border-bottom: 2px solid transparent;
+  }
+}