@kaizen/components 0.0.0-canary-v2-20250901045936 → 0.0.0-canary-alpha-release-20250918043833

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('')
+    })
+  },
+}

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

@@ -1,5 +1,8 @@
 import React from 'react'
 import { type Meta } from '@storybook/react'
+import { Avatar } from '~components/Avatar'
+import { Icon } from '~components/Icon'
+import { Text } from '~components/Text'
 import { StickerSheet, type StickerSheetStory } from '~storybook/components/StickerSheet'
 import { SingleSelect } from '../index'
 import { groupedMockItems, singleMockItems } from './mockData'
@@ -14,31 +17,395 @@ export default {
 
 const StickerSheetTemplate: StickerSheetStory = {
   render: ({ isReversed }) => {
+    const [filterText, setFilterText] = React.useState('')
     return (
-      <StickerSheet isReversed={isReversed} title="SingleSelect" headers={['Items', 'Grouped']}>
+      <StickerSheet isReversed={isReversed} title="SingleSelect" headers={['Combobox', 'Select']}>
         <StickerSheet.Row>
-          <SingleSelect items={singleMockItems}>
-            <SingleSelect.List>
-              {singleMockItems.map((item) => (
-                <SingleSelect.ListItem key={item.value} id={item.value}>
+          <SingleSelect label="Coffee" isComboBox description="Default">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect label="Coffee" description="Default">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect
+            label="Coffee"
+            isComboBox
+            description="Manual filter"
+            items={singleMockItems.filter((item) =>
+              item.label.toLowerCase().includes(filterText.toLowerCase()),
+            )}
+            onInputChange={setFilterText}
+          >
+            {(item) => (
+              <SingleSelect.Item key={item.key} textValue={item.label}>
+                {item.label}
+              </SingleSelect.Item>
+            )}
+          </SingleSelect>
+
+          <SingleSelect label="Coffee" description="Render function" items={singleMockItems}>
+            {(item) => (
+              <SingleSelect.Item key={item.key} textValue={item.label}>
+                {item.label}
+              </SingleSelect.Item>
+            )}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect label="Pick a colour" isComboBox description="Grouped">
+            {groupedMockItems.map((section) => (
+              <SingleSelect.Section key={section.label} title={section.label}>
+                {section.options.map((item) => (
+                  <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+                ))}
+              </SingleSelect.Section>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect label="Pick a colour" description="Grouped">
+            {groupedMockItems.map((section) => (
+              <SingleSelect.Section key={section.label} title={section.label}>
+                {section.options.map((item) => (
+                  <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+                ))}
+              </SingleSelect.Section>
+            ))}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect label="Pick a colour" isComboBox description="Label hidden" labelHidden>
+            {groupedMockItems.map((section) => (
+              <SingleSelect.Section key={section.label} title={section.label}>
+                {section.options.map((item) => (
+                  <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+                ))}
+              </SingleSelect.Section>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect label="Pick a colour" description="Label hidden" labelHidden>
+            {groupedMockItems.map((section) => (
+              <SingleSelect.Section key={section.label} title={section.label}>
+                {section.options.map((item) => (
+                  <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+                ))}
+              </SingleSelect.Section>
+            ))}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect label="Coffee" isComboBox description="inline" labelPosition="side">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect label="Coffee" description="inline" labelPosition="side">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect
+            label="Coffee"
+            isComboBox
+            isDisabled
+            description="disabled"
+            defaultSelectedKey={'magic'}
+          >
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect
+            label="Coffee"
+            isDisabled
+            description="disabled"
+            defaultSelectedKey={'magic'}
+          >
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect
+            label="Coffee"
+            isComboBox
+            isReadOnly
+            description="read only"
+            defaultSelectedKey={'magic'}
+          >
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect
+            label="Coffee"
+            isReadOnly
+            description="read only"
+            defaultSelectedKey={'magic'}
+          >
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect label="Coffee" isComboBox variant="secondary" description="secondary">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect label="Coffee" variant="secondary" description="secondary">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect label="Coffee" isComboBox size="small" description="small">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect label="Coffee" size="small" description="small">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect label="Coffee" isComboBox size="medium" description="medium">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect label="Coffee" size="medium" description="medium">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect label="Coffee" isComboBox size="large" description="large">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect label="Coffee" size="large" description="large">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect
+            label="Coffee"
+            isComboBox
+            description="Disabled items"
+            disabledKeys={['magic', 'flat-white']}
+          >
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect
+            label="Coffee"
+            description="Disabled items"
+            disabledKeys={['magic', 'flat-white']}
+          >
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>
+            ))}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect label="Coffee" isComboBox description="Checked items">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item selectedIcon="check" key={item.key}>
+                {item.label}
+              </SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect label="Coffee" description="Radio items">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item selectedIcon="radio" key={item.key}>
+                {item.label}
+              </SingleSelect.Item>
+            ))}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect label="Coffee" isComboBox description="Radio items start">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item selectedIcon="radio" selectedPosition="start" key={item.key}>
+                {item.label}
+              </SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect label="Coffee" description="Check items start">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item selectedIcon="check" selectedPosition="start" key={item.key}>
+                {item.label}
+              </SingleSelect.Item>
+            ))}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect label="Coffee" isComboBox description="Icon at start inline text">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item
+                key={item.key}
+                textValue={item.label}
+                className="flex flex-row items-center"
+              >
+                <Icon name="favorite" isPresentational />
+                <span style={{ paddingRight: 12 }} />
+                <Text
+                  variant="body"
+                  style={{
+                    whiteSpace: 'nowrap',
+                    minWidth: 0,
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    marginRight: 8,
+                    flexShrink: 0,
+                  }}
+                >
                   {item.label}
-                </SingleSelect.ListItem>
-              ))}
-            </SingleSelect.List>
-          </SingleSelect>
-
-          <SingleSelect items={groupedMockItems}>
-            <SingleSelect.List>
-              {groupedMockItems.map((section) => (
-                <SingleSelect.ListSection name={section.label} key={section.label}>
-                  {section.options.map((item) => (
-                    <SingleSelect.ListItem key={item.value} id={item.value}>
-                      {item.label}
-                    </SingleSelect.ListItem>
-                  ))}
-                </SingleSelect.ListSection>
-              ))}
-            </SingleSelect.List>
+                </Text>
+                <Text
+                  variant="body"
+                  style={{
+                    whiteSpace: 'nowrap',
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    minWidth: 0,
+                    flexShrink: 20,
+                  }}
+                >
+                  Supporting text
+                </Text>
+              </SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect label="Coffee" description="Radio and multiline">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item
+                selectedIcon="radio"
+                key={item.key}
+                textValue={item.label}
+                className="flex flex-col"
+              >
+                <Text
+                  variant="body"
+                  style={{
+                    whiteSpace: 'nowrap',
+                    flexShrink: 0,
+                  }}
+                >
+                  {item.label}
+                </Text>
+                <Text
+                  variant="body"
+                  style={{
+                    whiteSpace: 'nowrap',
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    display: 'block',
+                  }}
+                >
+                  Supporting text
+                </Text>
+              </SingleSelect.Item>
+            ))}
+          </SingleSelect>
+        </StickerSheet.Row>
+
+        <StickerSheet.Row>
+          <SingleSelect label="Coffee" isComboBox description="Avatar and inline">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item
+                key={item.key}
+                textValue={item.label}
+                className="flex flex-row items-center"
+              >
+                <div style={{ flexShrink: 0 }}>
+                  <Avatar fullName="Senior Popsicle" size="small" />
+                </div>
+                <span style={{ paddingRight: 12 }} />
+                <Text
+                  variant="body"
+                  style={{
+                    whiteSpace: 'nowrap',
+                    flexShrink: 0,
+                    marginRight: 8,
+                  }}
+                >
+                  {item.label}
+                </Text>
+
+                <Text
+                  variant="body"
+                  style={{
+                    whiteSpace: 'nowrap',
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    display: 'block',
+                  }}
+                >
+                  Supporting text
+                </Text>
+              </SingleSelect.Item>
+            ))}
+          </SingleSelect>
+
+          <SingleSelect label="Coffee" description="Avatar and multiline text">
+            {singleMockItems.map((item) => (
+              <SingleSelect.Item
+                key={item.key}
+                textValue={item.label}
+                className="flex flex-row items-center gap-12"
+              >
+                <Avatar fullName="Senior Popsicle" size="medium" />
+
+                <div style={{ display: 'flex', flexDirection: 'column' }}>
+                  {item.label}
+                  <Text variant="body">Supporting text</Text>
+                </div>
+              </SingleSelect.Item>
+            ))}
           </SingleSelect>
         </StickerSheet.Row>
       </StickerSheet>
@@ -61,17 +428,6 @@ export const StickerSheetDefault: StickerSheetStory = {
   name: 'Sticker Sheet (Default)',
 }
 
-export const StickerSheetReversed: StickerSheetStory = {
-  ...StickerSheetTemplate,
-  name: 'Sticker Sheet (Reversed)',
-  parameters: {
-    /** @note: Only required if template has parameters, otherwise this spread can be removed */
-    ...StickerSheetTemplate.parameters,
-    backgrounds: { default: 'Purple 700' },
-  },
-  args: { isReversed: true },
-}
-
 export const StickerSheetRTL: StickerSheetStory = {
   ...StickerSheetTemplate,
   name: 'Sticker Sheet (RTL)',