@kaizen/components 0.0.0-canary-v2-20250901045936 → 0.0.0-canary-debug-tab-20251015223744

package/src/Notification/InlineNotification/InlineNotification.tsx

@@ -35,7 +35,7 @@ export const InlineNotification = forwardRef<HTMLDivElement, InlineNotificationP
   ): JSX.Element => (
     <GenericNotification
       style="inline"
-      persistent={persistent ?? hideCloseIcon}
+      persistent={persistent || hideCloseIcon}
       classNameOverride={classnames(classNameOverride, [isSubtle && styles.subtle])}
       ref={ref}
       {...otherProps}

package/src/RichTextEditor/RichTextEditor/RichTextEditor.spec.stories.tsx

@@ -1,6 +1,6 @@
 import React, { useState } from 'react'
 import { type StoryObj } from '@storybook/react'
-import { expect, userEvent, within } from '@storybook/test'
+import { expect, userEvent, waitFor, within } from '@storybook/test'
 import { type EditorContentArray } from '../types'
 import { RichTextEditor, type RichTextEditorProps } from './RichTextEditor'
 
@@ -149,8 +149,9 @@ export const CreateALink: Story = {
   name: 'Create a link',
   play: async (context) => {
     const { canvasElement, step } = context
-    const { getByRole, getByText } = within(canvasElement)
+    const { getByRole, getByText, queryByRole, findByRole } = within(canvasElement)
     const editor = getByRole('textbox')
+
     await step('Focus on editor', async () => {
       await userEvent.click(editor)
       expect(editor).toHaveFocus()
@@ -185,8 +186,14 @@ export const CreateALink: Story = {
       await userEvent.keyboard('{Tab}{Enter}')
     })
 
+    await step('The Link Modal closes', async () => {
+      await waitFor(() => {
+        expect(queryByRole('dialog')).not.toBeInTheDocument()
+      })
+    })
+
     await step('Link exists in the RTE', async () => {
-      const link = getByRole('link', { name: 'Link' })
+      const link = await findByRole('link', { name: 'Link' })
       expect(link).toBeInTheDocument()
     })
   },

package/src/SingleSelect/subcomponents/ListBox/ListBox.tsx

@@ -70,10 +70,10 @@ export const ListBox = <Option extends SingleSelectOption>({
       const focusToElement = safeQuerySelector(`[data-key='${optionKey}']`)
 
       if (focusToElement) {
-        focusToElement.focus()
+        focusToElement.focus({ preventScroll: true })
       } 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()
+        ref.current?.focus({ preventScroll: true })
       }
     }
     // Only run this effect for checking the first successful render

package/src/Tabs/subcomponents/TabList/TabList.tsx

@@ -66,39 +66,49 @@ export const TabList = (props: TabListProps): JSX.Element => {
       return
     }
 
-    const firstTabObserver = new IntersectionObserver(
-      (entries) => {
-        if (!entries[0].isIntersecting) {
-          setLeftArrowEnabled(true)
-          return
-        }
-        setLeftArrowEnabled(false)
-      },
-      {
-        threshold: 0.8,
-        root: containerElement,
-      },
-    )
-    firstTabObserver.observe(isRTL ? tabs[tabs.length - 1] : tabs[0])
+    let firstTabObserver: IntersectionObserver | null = null
+    let lastTabObserver: IntersectionObserver | null = null
 
-    const lastTabObserver = new IntersectionObserver(
-      (entries) => {
-        if (!entries[0].isIntersecting) {
-          setRightArrowEnabled(true)
-          return
-        }
-        setRightArrowEnabled(false)
-      },
-      {
-        threshold: 0.8,
-        root: containerElement,
-      },
-    )
-    lastTabObserver.observe(isRTL ? tabs[0] : tabs[tabs.length - 1])
+    requestAnimationFrame(() => {
+      const tabList = tabListRef.current
+      if (!tabList) {
+        return
+      }
+
+      firstTabObserver = new IntersectionObserver(
+        (entries) => {
+          if (!entries[0].isIntersecting) {
+            setLeftArrowEnabled(true)
+            return
+          }
+          setLeftArrowEnabled(false)
+        },
+        {
+          threshold: 0.8,
+          root: containerElement,
+        },
+      )
+      firstTabObserver.observe(isRTL ? tabs[tabs.length - 1] : tabs[0])
+
+      lastTabObserver = new IntersectionObserver(
+        (entries) => {
+          if (!entries[0].isIntersecting) {
+            setRightArrowEnabled(true)
+            return
+          }
+          setRightArrowEnabled(false)
+        },
+        {
+          threshold: 0.8,
+          root: containerElement,
+        },
+      )
+      lastTabObserver.observe(isRTL ? tabs[0] : tabs[tabs.length - 1])
+    })
 
     return () => {
-      firstTabObserver.disconnect()
-      lastTabObserver.disconnect()
+      firstTabObserver?.disconnect()
+      lastTabObserver?.disconnect()
     }
   }, [isDocumentReady, containerElement, isRTL, tabListContext?.collection.size])
 

package/src/__alpha__/SingleSelect/SingleSelect.tsx

@@ -1,92 +1,39 @@
-import React, { cloneElement, isValidElement, useId, useMemo, type PropsWithChildren } from 'react'
-import { useSelectState } from '@react-stately/select'
-import { type Key, type Selection } from '@react-types/shared'
-import { Select as RACSelect, type ListBoxProps } from 'react-aria-components'
-import { SingleSelectContext } from './context'
-import { List, ListItem, ListSection, Popover, Trigger } from './subcomponents'
-import { type SelectItem, type SelectSection, type SingleSelectProps } from './types'
-
-export const SingleSelect = ({
-  items,
-  onSelectionChange,
-  children,
-  ...restProps
-}: PropsWithChildren<SingleSelectProps>): JSX.Element => {
-  const buttonRef = React.useRef<HTMLButtonElement>(null)
-  const popoverRef = React.useRef<HTMLDivElement>(null)
-  const racPopoverRef = React.useRef<HTMLElement>(null)
-  const uniqueId = useId()
-  const anchorName = `--trigger-${uniqueId}`
-
-  const state = useSelectState({
-    items,
-  })
-
-  const handleOnSelectionChange = React.useCallback(
-    (keys: Selection): void => {
-      let key: Key | null = null
-
-      if (keys instanceof Set && keys.size > 0) {
-        key = Array.from(keys)[0]
-      }
-
-      state.setSelectedKey(key)
-      if (onSelectionChange) {
-        onSelectionChange(key)
-      }
-    },
-    [state, onSelectionChange],
-  )
-
-  // Cloning children here to allow users to pass in a custom ListItem or ListSection
-  // and still have the SingleSelect handle selection state
-  const injectedChildren = useMemo(() => {
-    if (!isValidElement(children)) return null
-
-    const selectedKeys: Iterable<Key> = state.selectedKey
-      ? new Set<Key>([state.selectedKey])
-      : new Set()
+import React from 'react'
+import { Item as StatelyItem, Section } from '@react-stately/collections'
+import { ComboBox, Select } from './subcomponents'
+import {
+  type ComboBoxProps,
+  type SelectItem,
+  type SelectProps,
+  type SingleSelectProps,
+} from './types'
+
+export const SingleSelect = <T extends SelectItem>(props: SingleSelectProps<T>): JSX.Element => {
+  const { isComboBox, children, ...rest } = props
+
+  if (isComboBox) {
+    return <ComboBox {...(rest as ComboBoxProps<T>)}>{children}</ComboBox>
+  }
+
+  return <Select {...(rest as SelectProps<T>)}>{children}</Select>
+}
 
-    return cloneElement(children as React.ReactElement<ListBoxProps<SelectItem | SelectSection>>, {
-      selectionMode: 'single',
-      selectedKeys,
-      onSelectionChange: handleOnSelectionChange,
-      autoFocus: 'first',
-    })
-  }, [children, handleOnSelectionChange, state.selectedKey])
+type CustomItemProps = {
+  selectedIcon?: 'check' | 'radio'
+  selectedPosition?: 'start' | 'end'
+  key: string
+  children?: React.ReactNode
+  [key: string]: any
+}
 
-  return (
-    <SingleSelectContext.Provider
-      value={{
-        isOpen: state.isOpen,
-        setOpen: state.setOpen,
-        selectedKey: state.selectedKey,
-        items: items,
-        anchorName,
-      }}
-    >
-      <RACSelect
-        // TODO: allow user to pass in label
-        aria-label={'single-select'}
-        onSelectionChange={(key) =>
-          handleOnSelectionChange(key != null ? new Set([key]) : new Set())
-        }
-        placeholder=""
-        {...restProps}
-      >
-        <Trigger buttonRef={buttonRef} />
+export const Item = React.forwardRef<HTMLElement, CustomItemProps>((props, ref) => {
+  // @ts-expect-error: StatelyItem doesn't know about our internal item props
+  return <StatelyItem {...props} ref={ref} />
+})
 
-        {state.isOpen && (
-          <Popover buttonRef={buttonRef} popoverRef={popoverRef} racPopoverRef={racPopoverRef}>
-            {injectedChildren}
-          </Popover>
-        )}
-      </RACSelect>
-    </SingleSelectContext.Provider>
-  )
-}
+// @ts-expect-error: doesn't know that the Item can have this static property
+Item.getCollectionNode = StatelyItem.getCollectionNode
+Item.displayName = 'SingleSelectItem'
 
-SingleSelect.displayName = 'SingleSelect'
-SingleSelect.List = List
-SingleSelect.ListItem = ListItem
-SingleSelect.ListSection = ListSection
+SingleSelect.Item = Item
+SingleSelect.Section = Section

package/src/__alpha__/SingleSelect/_docs/SingleSelect.mdx

@@ -1,14 +1,15 @@
 import { Canvas, Controls, DocsStory, Meta } from '@storybook/blocks'
 import { ResourceLinks, KAIOInstallation, AlphaNotice } from '~storybook/components'
-import * as SingleSelectStories from './SingleSelect.stories'
+import { Playground } from './SingleSelect.stories'
+import { SingleSelect } from '../index'
 
-<Meta of={SingleSelectStories} />
+<Meta title="Components/SingleSelect/SingleSelect (alpha)" component={SingleSelect} />
 
 # SingleSelect
 
 <ResourceLinks
   sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__alpha__/SingleSelect"
-  figma=""
+  figma="https://www.figma.com/design/umhYV8q0yC4qwbCOIfJDY5/-Alpha--Select?node-id=2122-15597&t=EgUdLXABrcuWMIay-0"
   designGuidelines=""
 />
 
@@ -16,15 +17,104 @@ import * as SingleSelectStories from './SingleSelect.stories'
 
 <KAIOInstallation exportNames="SingleSelect" isAlpha />
 
+## Alpha notice
+
+This component is currently in **alpha** and not yet fully feature-complete. The following capabilities are planned or in progress:
+
+- Form validation and integration with form libraries
+- Support for passing a custom defaultFilter function from React Aria
+- Full support for asynchronous list loading and dynamic items
+- Ability to use the component in a fully controlled manner (selectedKey, inputValue, etc.)
+- Forwarding refs to the appropriate internal elements
+- Enhanced composability beyond the provided Item and Section components
+
+We welcome feedback as we continue to improve the component.
+
 ## Overview
 
-SingleSelect component that handles selecting items from a dropdown, can be either filterable or not.
+The `SingleSelect` component allows users to select a single item from a dropdown list. It can be configured as a **Select** or **Combobox**. A Select provides a predefined list of options, while a Combobox adds a filterable input to help users find an option quickly.
 
-<Canvas of={SingleSelectStories.Playground} />
-<Controls of={SingleSelectStories.Playground} />
+<Canvas of={Playground} />
+<Controls of={Playground} />
 
 ## API
 
+## Combobox vs. Select
+
+The `SingleSelect` component supports two different behaviors:
+
+- **Select**: A classic dropdown menu where the user can only select from a predefined list of options. It's ideal for short, fixed lists.
+- **Combobox**: An input field combined with a dropdown. The user can either type to filter the options or click to open the full list. This is best for long lists or when quick searching is a priority.
+
+To use the Combobox behavior, simply add the `isComboBox` prop.
+
+```tsx
+// Select
+<SingleSelect label="Select an item">
+  <SingleSelect.Item key="1">Item 1</SingleSelect.Item>
+  <SingleSelect.Item key="2">Item 2</SingleSelect.Item>
+</SingleSelect>
+
+// Combobox
+<SingleSelect label="Select an item" isComboBox>
+  <SingleSelect.Item key="1">Item 1</SingleSelect.Item>
+  <SingleSelect.Item key="2">Item 2</SingleSelect.Item>
+</SingleSelect>
+```
+
+## Filtering
+
+Children as static elements (leaves)
+
+```tsx
+<SingleSelect label="Choose a coffee" isComboBox items={coffeeItems}>
+  {(item) => <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>}
+</SingleSelect>
+```
+
+Children as a render function + `items` prop
+
+```tsx
+const [filterText, setFilterText] = useState('')
+
+<SingleSelect
+  label="Choose a coffee"
+  isComboBox
+  items={coffeeItems.filter((item) => item.label.toLowerCase().includes(filterText.toLowerCase()))}
+  onInputChange={setFilterText}
+>
+  {(item) => <SingleSelect.Item key={item.key} textValue={item.label}>{item.label}</SingleSelect.Item>}
+</SingleSelect>
+```
+
+## Flexible Rendering of items
+
+The SingleSelect.Item component is flexible and can accommodate a wide variety of content beyond simple text labels. You can render avatars, icons, or any custom React nodes within an item, while still preserving accessibility by providing the textValue prop.
+
+```tsx
+<SingleSelect label="Coffee" isComboBox description="Avatar and inline">
+  {singleMockItems.map((item) => (
+    <SingleSelect.Item key={item.key} textValue={item.label} className="flex items-center gap-3">
+      <Avatar fullName="Senior Popsicle" size="small" />
+
+      <Text variant="body" className="flex-shrink-0 whitespace-nowrap mr-2">
+        {item.label}
+      </Text>
+
+      <Text variant="body" className="truncate">
+        Supporting text
+      </Text>
+    </SingleSelect.Item>
+  ))}
+</SingleSelect>
+```
+
 ## Positioning and z-index Management
 
 The SingleSelect component leverages the native Popover API to manage its dropdown functionality. By using popover instead of custom portal logic, the component takes full advantage of CSS layers, ensuring dropdowns appear above other content without manual z-index management.
+
+## Known issues
+
+### Accessibility
+
+Using the default SingleSelect component without combobox, there is a known accessibility issue for keyboard navigation when the component is used as the last focusable element on the page. After the list is opened pressing Tab should close the list, instead Tab brings the user to a unqiue state where they cannot use the escape key to close the list. Instead the user will have to navigate either forward of back again using the Tab key.

package/src/__alpha__/SingleSelect/_docs/SingleSelect.spec.stories.tsx

@@ -17,16 +17,9 @@ export default meta
 type Story = StoryObj<typeof meta>
 
 const args = {
+  label: 'Choose a coffee',
   items: singleMockItems,
-  children: (
-    <SingleSelect.List>
-      {singleMockItems.map((item) => (
-        <SingleSelect.ListItem key={item.value} id={item.value}>
-          {item.label}
-        </SingleSelect.ListItem>
-      ))}
-    </SingleSelect.List>
-  ),
+  children: (item: any) => <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>,
 }
 
 export const RendersButton: Story = {
@@ -60,21 +53,6 @@ export const ClosesPopoverOnSelect: Story = {
   },
 }
 
-export const KeyboardNavigation: Story = {
-  args,
-  play: async () => {
-    const trigger = screen.getByRole('button')
-    trigger.focus()
-    await userEvent.keyboard('{Enter}')
-    await waitFor(() => expect(trigger).toHaveAttribute('aria-expanded', 'true'))
-    const options = await screen.findAllByRole('option')
-    await userEvent.keyboard('{ArrowDown}')
-    expect(options[1]).toHaveAttribute('data-focused', 'true')
-    await userEvent.keyboard('{ArrowUp}')
-    expect(options[0]).toHaveAttribute('data-focused', 'true')
-  },
-}
-
 export const KeyboardSelectsItem: Story = {
   args,
   play: async () => {
@@ -98,3 +76,23 @@ export const KeyboardEscapeClosesPopover: Story = {
     await waitFor(() => expect(trigger).toHaveAttribute('aria-expanded', 'false'))
   },
 }
+
+export const XButtonClearsSelection: Story = {
+  args: { ...args, isComboBox: true },
+  play: async () => {
+    const input = screen.getByRole('combobox')
+
+    await userEvent.type(input, 'short')
+    const options = await screen.findAllByRole('option')
+    await userEvent.click(options[0])
+
+    const clearButton = await screen.findByRole('button', {
+      name: 'Clear Choose a coffee selection',
+    })
+    await waitFor(() => expect(clearButton).toBeVisible())
+    await userEvent.click(clearButton)
+    await waitFor(() => {
+      expect(input).toHaveValue('')
+    })
+  },
+}