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

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

@@ -1,23 +1,12 @@
 import React from 'react'
 import { type Meta, type StoryObj } from '@storybook/react'
 import { SingleSelect } from '../index'
+import { type SelectItem, type SingleSelectProps } from '../types'
 import { singleMockItems } from './mockData'
 
-const meta = {
+const meta: Meta = {
   title: 'Components/SingleSelect/SingleSelect (alpha)',
   component: SingleSelect,
-  args: {
-    items: singleMockItems,
-    children: (
-      <SingleSelect.List>
-        {singleMockItems.map((item) => (
-          <SingleSelect.ListItem key={item.value} id={item.value}>
-            {item.label}
-          </SingleSelect.ListItem>
-        ))}
-      </SingleSelect.List>
-    ),
-  },
   decorators: [
     (Story) => (
       <div className="h-200 justify-center items-center position-relative flex">
@@ -25,18 +14,48 @@ const meta = {
       </div>
     ),
   ],
-} satisfies Meta<typeof SingleSelect>
+  argTypes: {
+    label: { control: 'text', description: 'The label for the select/combobox input' },
+    labelHidden: { control: 'boolean', description: 'Visually hide the label' },
+    labelPosition: {
+      control: { type: 'radio' },
+      options: ['top', 'side'],
+      description: 'Position of the label relative to the input',
+    },
+    variant: {
+      control: { type: 'radio' },
+      options: ['primary', 'secondary'],
+      description: 'Visual variant',
+    },
+    size: {
+      control: { type: 'radio' },
+      options: ['small', 'medium', 'large'],
+      description: 'Size of the input',
+    },
+    isReadOnly: { control: 'boolean', description: 'Whether the input is read-only' },
+    isDisabled: { control: 'boolean', description: 'Whether the input is disabled' },
+    isComboBox: {
+      control: 'boolean',
+      description: 'Whether to render as a combobox (filterable input) or select',
+    },
+    items: { control: 'object', description: 'List of options to display' },
+  },
+}
 
 export default meta
 
-type Story = StoryObj<typeof meta>
-
-export const Playground: Story = {
+export const Playground: StoryObj<SingleSelectProps<SelectItem>> = {
+  args: {
+    label: 'Choose an item',
+    isComboBox: false,
+    items: singleMockItems,
+  },
+  render: (args: SingleSelectProps<SelectItem>) => (
+    <SingleSelect {...args}>
+      {(item) => <SingleSelect.Item key={item.key}>{item.label}</SingleSelect.Item>}
+    </SingleSelect>
+  ),
   parameters: {
-    docs: {
-      canvas: {
-        sourceState: 'shown',
-      },
-    },
+    docs: { canvas: { sourceState: 'shown' } },
   },
 }

package/src/__alpha__/SingleSelect/_docs/mockData.ts

@@ -1,29 +1,35 @@
 export const singleMockItems = [
-  { label: 'Short black', value: 'short-black' },
-  { label: 'Long black', value: 'long-black' },
-  { label: 'Batch brew', value: 'batch-brew' },
-  { label: 'Latte', value: 'latte' },
-  { label: 'Flat white', value: 'flat-white' },
-  { label: 'Mocha', value: 'mocha' },
-  { label: 'Cappuccino', value: 'cappuccino' },
-  { label: 'Magic', value: 'magic' },
+  {
+    key: 'short-black',
+    label: 'Short black',
+    value: 'short-black',
+  },
+  { key: 'long-black', label: 'Long black', value: 'long-black' },
+  { key: 'batch-brew', label: 'Batch brew', value: 'batch-brew' },
+  { key: 'latte', label: 'Latte', value: 'latte' },
+  { key: 'flat-white', label: 'Flat white', value: 'flat-white' },
+  { key: 'mocha', label: 'Mocha', value: 'mocha' },
+  { key: 'cappuccino', label: 'Cappuccino', value: 'cappuccino' },
+  { key: 'magic', label: 'Magic', value: 'magic' },
 ]
 
 export const groupedMockItems = [
   {
+    type: 'section',
     label: 'Colours',
     options: [
-      { label: 'Blue', value: 'blue' },
-      { label: 'Red', value: 'red' },
-      { label: 'Green', value: 'green' },
+      { key: 'blue', label: 'Blue', value: 'blue' },
+      { key: 'red', label: 'Red', value: 'red' },
+      { key: 'green', label: 'Green', value: 'green' },
     ],
   },
   {
+    type: 'section',
     label: 'Flavours',
     options: [
-      { label: 'Vanilla', value: 'vanilla' },
-      { label: 'Chocolate', value: 'chocolate' },
-      { label: 'Strawberry', value: 'strawberry' },
+      { key: 'vanilla', label: 'Vanilla', value: 'vanilla' },
+      { key: 'chocolate', label: 'Chocolate', value: 'chocolate' },
+      { key: 'strawberry', label: 'Strawberry', value: 'strawberry' },
     ],
   },
 ]

package/src/__alpha__/SingleSelect/context/SingleSelectContext.tsx

@@ -1,15 +1,26 @@
 import { createContext, useContext } from 'react'
-import { type Key } from '@react-types/shared'
-import { type SelectItem, type SelectSection } from '../types'
+import { type ComboBoxState } from '@react-stately/combobox'
+import { type SelectState } from '@react-stately/select'
 
-type SingleSelectContextType = {
-  isOpen: boolean
-  setOpen: (open: boolean) => void
-  selectedKey: Key | null
-  items: (SelectItem | SelectSection)[]
+type BaseSingleSelectContextType = {
   anchorName: string
+  isDisabled: boolean
+  isReadOnly: boolean
+  secondary: boolean
+  size?: 'small' | 'medium' | 'large'
+  fieldLabel: React.ReactNode
 }
 
+type SingleSelectContextType =
+  | (BaseSingleSelectContextType & {
+      state: ComboBoxState<object>
+      isComboBox: true
+    })
+  | (BaseSingleSelectContextType & {
+      state: SelectState<object>
+      isComboBox: false
+    })
+
 export const SingleSelectContext = createContext<SingleSelectContextType | undefined>(undefined)
 
 export const useSingleSelectContext = (): SingleSelectContextType => {

package/src/__alpha__/SingleSelect/subcomponents/ComboBox/ComboBox.module.css

@@ -0,0 +1,35 @@
+@layer kz-components {
+  .topLabel {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
+  .sideLabel {
+    display: grid;
+    grid-template-columns: auto 1fr;
+    grid-template-rows: auto auto;
+    gap: var(--spacing-4) var(--spacing-6);
+    align-items: center;
+  }
+
+  .label {
+    grid-column: 1;
+    grid-row: 1;
+  }
+
+  .labelTop {
+    margin-bottom: var(--spacing-6);
+  }
+
+  .comboBoxTrigger {
+    grid-column: 2;
+    grid-row: 1;
+    width: 100%;
+  }
+
+  .description {
+    grid-column: 2;
+    grid-row: 2;
+  }
+}

package/src/__alpha__/SingleSelect/subcomponents/ComboBox/ComboBox.tsx

@@ -0,0 +1,106 @@
+import React, { useId, useRef } from 'react'
+import { useComboBoxState } from '@react-stately/combobox'
+import classNames from 'classnames'
+import { useComboBox, useFilter } from 'react-aria'
+import { FieldMessage } from '~components/FieldMessage'
+import { Label } from '~components/Label'
+import { SingleSelectContext } from '../../context'
+import { type ComboBoxProps, type SelectItem } from '../../types'
+import { ComboBoxTrigger } from '../ComboBoxTrigger'
+import { List } from '../List'
+import { Popover } from '../Popover'
+import styles from './ComboBox.module.css'
+
+export const ComboBox = <T extends SelectItem>(props: ComboBoxProps<T>): JSX.Element => {
+  const {
+    items,
+    children,
+    label,
+    description,
+    labelHidden,
+    labelPosition = 'top',
+    isReadOnly,
+    isDisabled,
+    size = 'medium',
+    variant = 'primary',
+  } = props
+
+  const { contains } = useFilter({ sensitivity: 'base' })
+
+  const state = useComboBoxState({
+    ...props,
+    items: items,
+    defaultFilter: contains,
+    children: children,
+    menuTrigger: 'focus',
+  })
+
+  const inputRef = useRef<HTMLInputElement>(null)
+  const popoverRef = useRef<HTMLDivElement>(null)
+  const listBoxRef = useRef<HTMLUListElement>(null)
+  const buttonRef = useRef<HTMLButtonElement>(null)
+  const clearButtonRef = useRef<HTMLButtonElement>(null)
+  const triggerWrapperRef = useRef<HTMLDivElement>(null)
+
+  const { labelProps, descriptionProps, inputProps, listBoxProps, buttonProps } = useComboBox(
+    {
+      ...props,
+      'aria-label': labelHidden ? label : undefined,
+      inputRef,
+      buttonRef,
+      popoverRef,
+      listBoxRef,
+    },
+    state,
+  )
+  const uniqueId = useId()
+  const anchorName = `--trigger-${uniqueId}`
+
+  return (
+    <SingleSelectContext.Provider
+      value={{
+        anchorName,
+        state,
+        isComboBox: true,
+        isDisabled: isDisabled ?? false,
+        isReadOnly: isReadOnly ?? false,
+        secondary: variant === 'secondary',
+        size,
+        fieldLabel: label,
+      }}
+    >
+      <div className={labelPosition === 'top' ? styles.topLabel : styles.sideLabel}>
+        {!labelHidden && (
+          <div className={classNames(styles.label, { [styles.labelTop]: labelPosition === 'top' })}>
+            <Label {...labelProps}>{label}</Label>
+          </div>
+        )}
+        <div className={styles.comboBoxTrigger}>
+          <ComboBoxTrigger
+            inputProps={inputProps}
+            inputRef={inputRef}
+            buttonRef={buttonRef}
+            buttonProps={buttonProps}
+            clearButtonRef={clearButtonRef}
+            triggerWrapperRef={triggerWrapperRef}
+          />
+        </div>
+
+        {description && (
+          <div className={styles.description}>
+            <FieldMessage message={description} {...descriptionProps} />
+          </div>
+        )}
+      </div>
+
+      <Popover
+        state={state}
+        triggerRef={triggerWrapperRef}
+        popoverRef={popoverRef}
+        clearButtonRef={clearButtonRef}
+      >
+        <List listBoxOptions={listBoxProps} state={state} listBoxRef={listBoxRef} />
+      </Popover>
+    </SingleSelectContext.Provider>
+  )
+}

package/src/__alpha__/SingleSelect/subcomponents/ComboBox/index.ts

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

package/src/__alpha__/SingleSelect/subcomponents/ComboBoxTrigger/ComboBoxTrigger.module.css

@@ -0,0 +1,130 @@
+@layer kz-components {
+  .trigger {
+    anchor-name: var(--anchor-name);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    font-family: var(--typography-paragraph-body-font-family);
+    font-weight: var(--typography-paragraph-body-font-weight);
+    font-size: var(--typography-paragraph-body-font-size);
+    line-height: var(--typography-paragraph-body-line-height);
+    letter-spacing: var(--typography-paragraph-body-letter-spacing);
+    height: var(--spacing-40);
+    min-width: var(--spacing-200);
+    width: 100%;
+    background-color: var(--color-white);
+    border-radius: 0.4375rem;
+    border: var(--spacing-2) solid var(--color-gray-500);
+    box-sizing: border-box;
+  }
+
+  .smallText {
+    font-family: var(--typography-paragraph-small-font-family);
+    font-weight: var(--typography-paragraph-small-font-weight);
+    font-size: var(--typography-paragraph-small-font-size);
+    line-height: var(--typography-paragraph-small-line-height);
+    letter-spacing: var(--typography-paragraph-small-letter-spacing);
+  }
+
+  .secondary:not(.disabled, .readOnly) {
+    border-radius: 0.4375rem 0.4375rem 0 0;
+    border: 2px solid transparent;
+    border-bottom: var(--spacing-2) solid var(--color-gray-400);
+  }
+
+  .secondary:not(.disabled, .readOnly):hover {
+    border: var(--spacing-2) solid var(--color-gray-600);
+    border-radius: 0.4375rem;
+  }
+
+  .secondary:not(.disabled, .readOnly):focus-within {
+    border: var(--spacing-2) solid var(--color-gray-600);
+    border-radius: 0.4375rem;
+  }
+
+  .input {
+    outline: none;
+    text-overflow: ellipsis;
+    background-color: var(--color-white);
+    padding: var(--spacing-8) 0;
+    margin-inline-start: var(--spacing-16);
+    height: 2.25rem;
+    box-sizing: border-box;
+    width: inherit;
+  }
+
+  .small .input {
+    height: 1.75rem;
+  }
+
+  .disabled {
+    pointer-events: none;
+    border: var(--spacing-2) solid var(--color-gray-300);
+    background-color: var(--color-gray-100);
+
+    .input {
+      background-color: var(--color-gray-100);
+      color: var(--color-gray-500);
+    }
+  }
+
+  .readOnly {
+    pointer-events: none;
+    background-color: var(--color-gray-200);
+    border: var(--spacing-2) solid var(--color-gray-200);
+
+    .input {
+      background-color: var(--color-gray-200);
+    }
+  }
+
+  .trigger:focus-within {
+    outline-offset: var(--spacing-2);
+    outline: var(--spacing-2) solid var(--color-blue-500);
+    background-color: var(--color-white);
+    border-radius: 0.4375rem;
+
+    .input {
+      background-color: var(--color-white);
+    }
+  }
+
+  .trigger:hover:not(:focus-within) {
+    border-color: var(--color-gray-600);
+    background-color: var(--color-gray-200);
+
+    .input {
+      background-color: var(--color-gray-200);
+    }
+  }
+
+  .small {
+    height: var(--spacing-32);
+  }
+
+  .large {
+    height: var(--spacing-48);
+  }
+
+  .clearButton {
+    background: none;
+    padding: 0;
+    display: flex;
+  }
+
+  .clearButton:focus-visible {
+    outline: var(--spacing-2) solid var(--color-blue-500);
+    border-radius: 50%;
+  }
+
+  .chevronButton {
+    background: none;
+    padding-block: var(--spacing-8);
+    padding-inline: var(--spacing-6) var(--spacing-16);
+    display: flex;
+  }
+
+  .hidden {
+    visibility: hidden;
+  }
+}

package/src/__alpha__/SingleSelect/subcomponents/ComboBoxTrigger/ComboBoxTrigger.tsx

@@ -0,0 +1,121 @@
+import React from 'react'
+import { useIntl } from '@cultureamp/i18n-react-intl'
+import classNames from 'classnames'
+import { useButton } from 'react-aria'
+import { Icon } from '~components/Icon'
+import { VisuallyHidden } from '~components/VisuallyHidden'
+import { useSingleSelectContext } from '../../context'
+import {
+  type ChevronButtonProps,
+  type ClearButtonProps,
+  type ComboBoxTriggerProps,
+} from '../../types'
+import styles from './ComboBoxTrigger.module.css'
+
+const ClearButton = ({ clearButtonRef, inputRef }: ClearButtonProps): JSX.Element => {
+  const { state, isComboBox, fieldLabel } = useSingleSelectContext()
+
+  const { formatMessage } = useIntl()
+
+  const clearButtonAlt = formatMessage(
+    {
+      id: 'singleSelect.clearButtonAlt',
+      defaultMessage: 'Clear {field} selection',
+      description: 'Alt text for the clear selection button',
+    },
+    { field: fieldLabel },
+  )
+
+  const { buttonProps } = useButton(
+    {
+      onPress: () => {
+        if (isComboBox) {
+          state.setSelectedKey(null)
+        }
+        inputRef.current?.focus()
+      },
+    },
+    clearButtonRef,
+  )
+
+  return (
+    <button
+      {...buttonProps}
+      ref={clearButtonRef}
+      type="button"
+      className={classNames(styles.clearButton, { [styles.hidden]: !state.selectedKey })}
+      tabIndex={0}
+    >
+      <Icon name="cancel" isPresentational isFilled />
+      <VisuallyHidden>{clearButtonAlt}</VisuallyHidden>
+    </button>
+  )
+}
+
+const ChevronButton = (props: ChevronButtonProps): JSX.Element => {
+  const { state, fieldLabel } = useSingleSelectContext()
+  const { formatMessage } = useIntl()
+
+  const chevronButton = formatMessage(
+    {
+      id: 'singleSelect.chevronButton',
+      defaultMessage: 'Show suggestions for {field}',
+      description: 'Aria label text for the SingleSelect button to open and close suggestions list',
+    },
+    { field: fieldLabel },
+  )
+
+  const { buttonProps } = useButton(
+    { ...props, 'aria-label': String(chevronButton), 'aria-labelledby': undefined },
+    props.buttonRef,
+  )
+
+  return (
+    <button
+      type="button"
+      {...buttonProps}
+      ref={props.buttonRef}
+      className={styles.chevronButton}
+      tabIndex={-1}
+    >
+      <Icon isPresentational name={state.isOpen ? 'keyboard_arrow_up' : 'keyboard_arrow_down'} />
+    </button>
+  )
+}
+
+export const ComboBoxTrigger = ({
+  inputProps,
+  inputRef,
+  buttonProps,
+  buttonRef,
+  triggerWrapperRef,
+  clearButtonRef,
+}: ComboBoxTriggerProps): JSX.Element => {
+  const { anchorName, isDisabled, isReadOnly, secondary, size } = useSingleSelectContext()
+
+  return (
+    <>
+      <div
+        style={{ '--anchor-name': anchorName } as React.CSSProperties}
+        ref={triggerWrapperRef}
+        className={classNames(styles.trigger, {
+          [styles.disabled]: isDisabled,
+          [styles.readOnly]: isReadOnly,
+          [styles.secondary]: secondary,
+          [styles.small]: size === 'small',
+          [styles.large]: size === 'large',
+        })}
+      >
+        <input
+          {...inputProps}
+          ref={inputRef}
+          className={classNames(styles.input, { [styles.smallText]: size === 'small' })}
+        />
+        {!isDisabled && !isReadOnly && (
+          <ClearButton clearButtonRef={clearButtonRef} inputRef={inputRef} />
+        )}
+        {!isReadOnly && <ChevronButton {...buttonProps} buttonRef={buttonRef} />}
+      </div>
+    </>
+  )
+}

package/src/__alpha__/SingleSelect/subcomponents/ComboBoxTrigger/index.ts

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

package/src/__alpha__/SingleSelect/subcomponents/List/List.module.css

@@ -2,5 +2,10 @@
   .list {
     display: flex;
     flex-direction: column;
+    flex: 1 1 auto;
+    list-style: none;
+    overflow-y: auto;
+    padding: 0.875rem;
+    margin: 0;
   }
 }

package/src/__alpha__/SingleSelect/subcomponents/List/List.tsx

@@ -1,18 +1,41 @@
-import React, { type PropsWithChildren } from 'react'
-import classNames from 'classnames'
-import { ListBox as RACListBox, type ListBoxProps } from 'react-aria-components'
-import { type SelectItem, type SelectSection } from '../../types'
+import React from 'react'
+import type { Node } from '@react-types/shared'
+import { useListBox } from 'react-aria'
+import { type ListProps, type SelectItem } from '../../types'
+import { ListItem } from '../ListItem'
+import { ListSection } from '../ListSection'
 import styles from './List.module.css'
 
-export const List = ({
-  children,
-  className,
-  ...props
-}: ListBoxProps<SelectItem | SelectSection> & PropsWithChildren): React.ReactElement => {
+export const List = <T extends SelectItem>({
+  state,
+  listBoxOptions,
+  listBoxRef,
+}: ListProps<T>): JSX.Element => {
+  const { listBoxProps } = useListBox({ ...listBoxOptions, autoFocus: 'first' }, state, listBoxRef)
+
+  const renderNode = (node: Node<T>): JSX.Element | null => {
+    if (node.type === 'section') {
+      return node.rendered ? (
+        <ListSection key={String(node.key)} section={node} state={state} />
+      ) : null
+    } else {
+      const { selectedIcon, selectedPosition, className } = node.props
+      return (
+        <ListItem
+          key={String(node.key)}
+          item={node}
+          state={state}
+          selectedIcon={selectedIcon}
+          selectedPosition={selectedPosition}
+          className={className}
+        />
+      )
+    }
+  }
+
   return (
-    <RACListBox className={classNames(styles.list, className)} {...props}>
-      {children}
-    </RACListBox>
+    <ul {...listBoxProps} ref={listBoxRef} className={styles.list}>
+      {Array.from(state.collection).map(renderNode)}
+    </ul>
   )
 }
-List.displayName = 'SingleSelect.List'