@kaizen/components 2.0.0 → 2.0.2

package/dist/types/__alpha__/SingleSelect/subcomponents/Popover/Popover.d.ts

@@ -1,6 +1,3 @@
-import React, { type PropsWithChildren } from 'react';
-import { type PopoverProps } from '../../types';
-export declare const Popover: {
-    ({ buttonRef, popoverRef, racPopoverRef, children, }: PopoverProps & PropsWithChildren): React.ReactElement;
-    displayName: string;
-};
+import React from 'react';
+import { type PopoverProps, type SelectItem } from '../../types';
+export declare const Popover: <T extends SelectItem>({ state, popoverRef, children, clearButtonRef, ...restProps }: PopoverProps<T>) => React.ReactElement;

package/dist/types/__alpha__/SingleSelect/subcomponents/Popover/utils/index.d.ts

@@ -1,2 +1,3 @@
 export * from './usePopoverPositioning';
 export * from './useSupportsAnchorPositioning';
+export * from './usePositioningStyles';

package/dist/types/__alpha__/SingleSelect/subcomponents/Popover/utils/usePopoverPositioning.d.ts

@@ -1,4 +1,5 @@
 import { type Position, type UsePopoverPositioningProps } from '../../../types';
 export declare function usePopoverPositioning({ triggerRef, popoverRef, direction, offset, preferredPlacement, }: UsePopoverPositioningProps): Position & {
     isPositioned: boolean;
+    updatePosition: () => void;
 };

package/dist/types/__alpha__/SingleSelect/subcomponents/Popover/utils/usePositioningStyles.d.ts

@@ -1,4 +1,5 @@
 export declare const usePositioningStyles: (buttonRef: React.RefObject<HTMLElement>, popoverRef: React.RefObject<HTMLDivElement>, anchorName: string) => {
     popoverStyle: React.CSSProperties;
     isPositioned: boolean;
+    updatePosition: () => void;
 };

package/dist/types/__alpha__/SingleSelect/subcomponents/Select/Select.d.ts

@@ -0,0 +1,2 @@
+import { type SelectItem, type SelectProps } from '../../types';
+export declare const Select: <T extends SelectItem>(props: SelectProps<T>) => JSX.Element;

package/dist/types/__alpha__/SingleSelect/subcomponents/Select/index.d.ts

@@ -0,0 +1 @@
+export * from './Select';

package/dist/types/__alpha__/SingleSelect/subcomponents/SelectTrigger/SelectTrigger.d.ts

@@ -0,0 +1,2 @@
+import { type SelectTriggerProps } from '../../types';
+export declare const SelectTrigger: ({ triggerProps, valueProps, buttonRef, }: SelectTriggerProps) => JSX.Element;

package/dist/types/__alpha__/SingleSelect/subcomponents/SelectTrigger/index.d.ts

@@ -0,0 +1 @@
+export * from './SelectTrigger';

package/dist/types/__alpha__/SingleSelect/subcomponents/index.d.ts

@@ -1,5 +1,8 @@
 export * from './List';
 export * from './ListSection';
 export * from './ListItem';
-export * from './Trigger';
+export * from './SelectTrigger';
+export * from './ComboBoxTrigger';
 export * from './Popover';
+export * from './Select';
+export * from './ComboBox';

package/dist/types/__alpha__/SingleSelect/types.d.ts

@@ -1,25 +1,66 @@
-import { type RefObject } from 'react';
-import { type Key } from '@react-types/shared';
+import type { DOMAttributes, RefObject } from 'react';
+import type React from 'react';
+import { type ComboBoxState, type ComboBoxStateOptions } from '@react-stately/combobox';
+import type { ListState } from '@react-stately/list';
+import { type SelectState, type SelectStateOptions } from '@react-stately/select';
+import { type Key, type Node } from '@react-types/shared';
+import { type FocusableElement } from '@react-types/shared/src/dom';
+import type { AriaButtonProps, AriaListBoxOptions, AriaPopoverProps } from 'react-aria';
 export type SelectItem = {
     label: string;
     value: string;
+    key: Key;
 };
 export type SelectSection = {
     label: string;
     options: SelectItem[];
 };
-export type SingleSelectProps = {
-    children?: React.ReactNode;
-    items: (SelectItem | SelectSection)[];
-    onSelectionChange?: (key: Key | null) => void;
+export type SelectLabel = {
+    labelHidden: true;
+    label: string;
+} | {
+    labelHidden?: false;
+    label: React.ReactNode;
+};
+export type SelectBaseProps = {
+    variant?: 'primary' | 'secondary';
+    size?: 'small' | 'medium' | 'large';
+    labelPosition?: 'top' | 'side';
+    isReadOnly?: boolean;
+} & SelectLabel;
+export type SelectProps<T extends SelectItem> = Omit<SelectStateOptions<T>, 'label' | 'defaultFilter' | 'menuTrigger' | 'allowsCustomValue'> & SelectBaseProps;
+export type ComboBoxProps<T extends SelectItem> = Omit<ComboBoxStateOptions<T>, 'label' | 'defaultFilter' | 'menuTrigger' | 'allowsCustomValue'> & SelectBaseProps;
+export type SingleSelectProps<T extends SelectItem> = (ComboBoxProps<T> & {
+    isComboBox?: true;
+}) | (SelectProps<T> & {
+    isComboBox?: false;
+});
+export type SelectTriggerProps = {
+    triggerProps: AriaButtonProps<'button'>;
+    valueProps: DOMAttributes<FocusableElement>;
+    buttonRef: React.MutableRefObject<HTMLButtonElement | null>;
+};
+export type ComboBoxTriggerProps = {
+    inputProps: React.InputHTMLAttributes<HTMLInputElement>;
+    inputRef: React.MutableRefObject<HTMLInputElement | null>;
+    buttonProps: AriaButtonProps<'button'>;
+    buttonRef: React.MutableRefObject<HTMLButtonElement | null>;
+    triggerWrapperRef: React.MutableRefObject<HTMLDivElement | null>;
+    clearButtonRef: React.MutableRefObject<HTMLButtonElement | null>;
+};
+export type ChevronButtonProps = AriaButtonProps<'button'> & {
+    buttonRef: React.MutableRefObject<HTMLButtonElement | null>;
 };
-export type TriggerProps = {
-    buttonRef: React.RefObject<HTMLButtonElement>;
+export type ClearButtonProps = {
+    clearButtonRef: React.RefObject<HTMLButtonElement>;
+    inputRef: React.RefObject<HTMLInputElement>;
 };
-export type PopoverProps = {
-    buttonRef: React.RefObject<HTMLElement>;
+export type PopoverProps<T extends SelectItem> = AriaPopoverProps & {
+    state: ComboBoxState<T> | SelectState<T>;
+    triggerRef: React.RefObject<HTMLElement>;
     popoverRef: React.RefObject<HTMLDivElement>;
-    racPopoverRef: React.Ref<any>;
+    clearButtonRef?: React.RefObject<HTMLButtonElement>;
+    children: React.ReactNode;
 };
 type PositionDataProp = number | string | undefined;
 export type PositionData = {
@@ -42,4 +83,20 @@ export type UsePopoverPositioningProps = {
     offset?: number;
     preferredPlacement?: 'top' | 'bottom';
 };
+export type ListProps<T extends SelectItem> = {
+    state: ComboBoxState<T> | SelectState<T>;
+    listBoxOptions: AriaListBoxOptions<T>;
+    listBoxRef: React.RefObject<HTMLUListElement>;
+};
+export type ListItemProps<T extends SelectItem> = {
+    item: Node<T>;
+    state: ListState<T>;
+    selectedIcon?: 'check' | 'radio';
+    selectedPosition?: 'start' | 'end';
+    className?: string;
+};
+export type ListSectionProps<T extends SelectItem> = {
+    section: Node<T>;
+    state: ComboBoxState<T> | SelectState<T>;
+};
 export {};

package/locales/en.json

@@ -185,8 +185,16 @@
     "description": "Prompts user to interact with button to hide information",
     "message": "Hide information:"
   },
+  "singleSelect.chevronButton": {
+    "description": "Aria label text for the SingleSelect button to open and close suggestions list",
+    "message": "Show suggestions for {field}"
+  },
+  "singleSelect.clearButtonAlt": {
+    "description": "Alt text for the clear selection button",
+    "message": "Clear {field} selection"
+  },
   "splitButton.dropdownButton.label": {
     "description": "Label for a dropdown menu holding additional actions",
     "message": "Additional actions"
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaizen/components",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Kaizen component library",
   "author": "Geoffrey Chong <geoff.chong@cultureamp.com>",
   "homepage": "https://cultureamp.design",
@@ -15,6 +15,7 @@
   "files": [
     "bin",
     "codemods",
+    "alpha",
     "future",
     "next",
     "libs",
@@ -36,6 +37,11 @@
       "import": "./dist/esm/index.mjs",
       "require": "./dist/cjs/index.cjs"
     },
+    "./alpha": {
+      "types": "./dist/types/__alpha__/index.d.ts",
+      "import": "./dist/esm/alpha.mjs",
+      "require": "./dist/cjs/alpha.cjs"
+    },
     "./next": {
       "types": "./dist/types/__next__/index.d.ts",
       "import": "./dist/esm/next.mjs",
@@ -86,6 +92,7 @@
     "@react-aria/select": "^3.15.7",
     "@react-aria/utils": "^3.29.1",
     "@react-stately/collections": "^3.12.5",
+    "@react-stately/combobox": "^3.11.1",
     "@react-stately/datepicker": "^3.14.2",
     "@react-stately/list": "^3.12.3",
     "@react-stately/menu": "^3.9.5",
@@ -152,8 +159,8 @@
     "sass": "1.79.6",
     "serialize-query-params": "^2.0.2",
     "svgo": "^3.3.2",
-    "tslib": "^2.8.1",
     "ts-patch": "^3.3.0",
+    "tslib": "^2.8.1",
     "tsx": "^4.20.3",
     "@kaizen/design-tokens": "11.0.0"
   },

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