@kaizen/components 1.80.2 → 1.80.3

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

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

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

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

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

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

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

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

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

@@ -0,0 +1 @@
+export declare const useSupportsAnchorPositioning: () => boolean;

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

@@ -1 +1,2 @@
-export declare const Trigger: () => JSX.Element;
+import { type TriggerProps } from '../../types';
+export declare const Trigger: ({ buttonRef }: TriggerProps) => JSX.Element;

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

@@ -2,3 +2,4 @@ export * from './List';
 export * from './ListSection';
 export * from './ListItem';
 export * from './Trigger';
+export * from './Popover';

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

@@ -0,0 +1,45 @@
+import { type RefObject } from 'react';
+import { type Key } from '@react-types/shared';
+export type SelectItem = {
+    label: string;
+    value: string;
+};
+export type SelectSection = {
+    label: string;
+    options: SelectItem[];
+};
+export type SingleSelectProps = {
+    children?: React.ReactNode;
+    items: (SelectItem | SelectSection)[];
+    onSelectionChange?: (key: Key | null) => void;
+};
+export type TriggerProps = {
+    buttonRef: React.RefObject<HTMLButtonElement>;
+};
+export type PopoverProps = {
+    buttonRef: React.RefObject<HTMLElement>;
+    popoverRef: React.RefObject<HTMLDivElement>;
+    racPopoverRef: React.Ref<any>;
+};
+type PositionDataProp = number | string | undefined;
+export type PositionData = {
+    top: PositionDataProp;
+    bottom: PositionDataProp;
+    insetInlineStart: PositionDataProp;
+    maxHeight: PositionDataProp;
+};
+export type LogicalPosition = number | 'auto' | undefined;
+export type Position = {
+    top: LogicalPosition;
+    bottom: LogicalPosition;
+    insetInlineStart: number;
+    maxHeight?: number;
+};
+export type UsePopoverPositioningProps = {
+    triggerRef: RefObject<HTMLElement>;
+    popoverRef: RefObject<HTMLElement>;
+    direction?: 'ltr' | 'rtl';
+    offset?: number;
+    preferredPlacement?: 'top' | 'bottom';
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaizen/components",
-  "version": "1.80.2",
+  "version": "1.80.3",
   "description": "Kaizen component library",
   "author": "Geoffrey Chong <geoff.chong@cultureamp.com>",
   "homepage": "https://cultureamp.design",
@@ -102,8 +102,8 @@
     "kaizen-codemod": "./bin/codemod.sh"
   },
   "dependencies": {
-    "@floating-ui/react-dom": "^2.1.4",
-    "@headlessui/react": "^2.2.6",
+    "@floating-ui/react-dom": "^2.1.5",
+    "@headlessui/react": "^2.2.7",
     "@internationalized/date": "^3.8.2",
     "@popperjs/core": "^2.11.8",
     "@reach/tabs": "^0.18.0",
@@ -179,7 +179,7 @@
     "react-dom": "^19.1.0",
     "react-highlight": "^0.15.0",
     "react-intl": "^7.1.11",
-    "rollup": "^4.46.1",
+    "rollup": "^4.46.2",
     "sass": "1.79.6",
     "serialize-query-params": "^2.0.2",
     "svgo": "^3.3.2",

package/src/__alpha__/SingleSelect/SingleSelect.tsx

@@ -1,23 +1,88 @@
-import React, { type HTMLAttributes, type PropsWithChildren } from 'react'
-import { Popover as RACPopover, Select as RACSelect } from 'react-aria-components'
-import { type OverrideClassName } from '~components/types/OverrideClassName'
-import { List, ListItem, ListSection, Trigger } from './subcomponents'
-import styles from './SingleSelect.module.css'
-
-export type SingleSelectProps = {
-  children?: React.ReactNode
-} & OverrideClassName<HTMLAttributes<Element>>
+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 = ({
-  classNameOverride,
+  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()
+
+    return cloneElement(children as React.ReactElement<ListBoxProps<SelectItem | SelectSection>>, {
+      selectionMode: 'single',
+      selectedKeys,
+      onSelectionChange: handleOnSelectionChange,
+      autoFocus: 'first',
+    })
+  }, [children, handleOnSelectionChange, state.selectedKey])
+
   return (
-    <RACSelect className={classNameOverride} placeholder="" {...restProps}>
-      <Trigger />
-      <RACPopover className={styles.popover}>{children}</RACPopover>
-    </RACSelect>
+    <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} />
+
+        {state.isOpen && (
+          <Popover buttonRef={buttonRef} popoverRef={popoverRef} racPopoverRef={racPopoverRef}>
+            {injectedChildren}
+          </Popover>
+        )}
+      </RACSelect>
+    </SingleSelectContext.Provider>
   )
 }
 

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

@@ -18,10 +18,13 @@ import * as SingleSelectStories from './SingleSelect.stories'
 
 ## Overview
 
-{/* @todo: Update summary. */}
-Brief summary of the component here.
+SingleSelect component that handles selecting items from a dropdown, can be either filterable or not.
 
 <Canvas of={SingleSelectStories.Playground} />
 <Controls of={SingleSelectStories.Playground} />
 
 ## API
+
+## 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.

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

@@ -0,0 +1,100 @@
+import React from 'react'
+import { type Meta, type StoryObj } from '@storybook/react'
+import { expect, screen, userEvent, waitFor } from '@storybook/test'
+import { SingleSelect } from '../SingleSelect'
+import { singleMockItems } from './mockData'
+
+const meta = {
+  title: 'Components/SingleSelect/SingleSelect (alpha)',
+  component: SingleSelect,
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof SingleSelect>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+const args = {
+  items: singleMockItems,
+  children: (
+    <SingleSelect.List>
+      {singleMockItems.map((item) => (
+        <SingleSelect.ListItem key={item.value} id={item.value}>
+          {item.label}
+        </SingleSelect.ListItem>
+      ))}
+    </SingleSelect.List>
+  ),
+}
+
+export const RendersButton: Story = {
+  args,
+  play: async () => {
+    expect(screen.getByRole('button')).toBeInTheDocument()
+  },
+}
+
+export const OpensPopoverOnClick: Story = {
+  args,
+  play: async () => {
+    const trigger = screen.getByRole('button')
+    await userEvent.click(trigger)
+    await waitFor(() => expect(trigger).toHaveAttribute('aria-expanded', 'true'))
+    const options = await screen.findAllByRole('option')
+    expect(options[0]).toBeVisible()
+    expect(options[0]).toHaveTextContent(singleMockItems[0].label)
+  },
+}
+
+export const ClosesPopoverOnSelect: Story = {
+  args,
+  play: async () => {
+    const trigger = screen.getByRole('button')
+    await userEvent.click(trigger)
+    await waitFor(() => expect(trigger).toHaveAttribute('aria-expanded', 'true'))
+    const options = await screen.findAllByRole('option')
+    await userEvent.click(options[0])
+    await waitFor(() => expect(screen.queryAllByRole('option')).toHaveLength(0))
+  },
+}
+
+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 () => {
+    const trigger = screen.getByRole('button')
+    trigger.focus()
+    await userEvent.keyboard('{Enter}')
+    await waitFor(() => expect(trigger).toHaveAttribute('aria-expanded', 'true'))
+    await userEvent.keyboard('{ArrowDown}')
+    await userEvent.keyboard('{Enter}')
+    await waitFor(() => expect(screen.queryAllByRole('option')).toHaveLength(0))
+  },
+}
+
+export const KeyboardEscapeClosesPopover: Story = {
+  args,
+  play: async () => {
+    const trigger = screen.getByRole('button')
+    await userEvent.click(trigger)
+    await waitFor(() => expect(trigger).toHaveAttribute('aria-expanded', 'true'))
+    await userEvent.keyboard('{Escape}')
+    await waitFor(() => expect(trigger).toHaveAttribute('aria-expanded', 'false'))
+  },
+}

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

@@ -17,22 +17,22 @@ const StickerSheetTemplate: StickerSheetStory = {
     return (
       <StickerSheet isReversed={isReversed} title="SingleSelect" headers={['Items', 'Grouped']}>
         <StickerSheet.Row>
-          <SingleSelect>
+          <SingleSelect items={singleMockItems}>
             <SingleSelect.List>
               {singleMockItems.map((item) => (
-                <SingleSelect.ListItem key={item.value} value={{ value: item.value }}>
+                <SingleSelect.ListItem key={item.value} id={item.value}>
                   {item.label}
                 </SingleSelect.ListItem>
               ))}
             </SingleSelect.List>
           </SingleSelect>
 
-          <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} value={{ value: item.value }}>
+                    <SingleSelect.ListItem key={item.value} id={item.value}>
                       {item.label}
                     </SingleSelect.ListItem>
                   ))}

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

@@ -1,10 +1,30 @@
+import React from 'react'
 import { type Meta, type StoryObj } from '@storybook/react'
 import { SingleSelect } from '../index'
+import { singleMockItems } from './mockData'
 
 const meta = {
   title: 'Components/SingleSelect/SingleSelect (alpha)',
   component: SingleSelect,
-  args: {},
+  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">
+        <Story />
+      </div>
+    ),
+  ],
 } satisfies Meta<typeof SingleSelect>
 
 export default meta
@@ -12,7 +32,6 @@ export default meta
 type Story = StoryObj<typeof meta>
 
 export const Playground: Story = {
-  args: {},
   parameters: {
     docs: {
       canvas: {

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

@@ -0,0 +1,21 @@
+import { createContext, useContext } from 'react'
+import { type Key } from '@react-types/shared'
+import { type SelectItem, type SelectSection } from '../types'
+
+type SingleSelectContextType = {
+  isOpen: boolean
+  setOpen: (open: boolean) => void
+  selectedKey: Key | null
+  items: (SelectItem | SelectSection)[]
+  anchorName: string
+}
+
+export const SingleSelectContext = createContext<SingleSelectContextType | undefined>(undefined)
+
+export const useSingleSelectContext = (): SingleSelectContextType => {
+  const context = useContext(SingleSelectContext)
+  if (!context) {
+    throw new Error('useSingleSelectContext must be used within a SingleSelectContext.Provider')
+  }
+  return context
+}

package/src/__alpha__/SingleSelect/context/index.ts

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

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

@@ -2,6 +2,5 @@
   .list {
     display: flex;
     flex-direction: column;
-    gap: var(--spacing-16);
   }
 }

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

@@ -1,13 +1,14 @@
 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 styles from './List.module.css'
 
 export const List = ({
   children,
   className,
   ...props
-}: ListBoxProps<object> & PropsWithChildren): React.ReactElement => {
+}: ListBoxProps<SelectItem | SelectSection> & PropsWithChildren): React.ReactElement => {
   return (
     <RACListBox className={classNames(styles.list, className)} {...props}>
       {children}

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

@@ -5,5 +5,12 @@
     font-size: var(--typography-paragraph-body-font-size);
     line-height: var(--typography-paragraph-body-line-height);
     letter-spacing: var(--typography-paragraph-body-letter-spacing);
+    padding: var(--spacing-8) var(--spacing-16);
+  }
+
+  .listItem:focus-visible {
+    background-color: var(--color-blue-200);
+    outline: none;
+    border-color: white;
   }
 }

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

@@ -1,13 +1,14 @@
 import React, { type PropsWithChildren } from 'react'
 import classNames from 'classnames'
 import { ListBoxItem as RACListBoxItem, type ListBoxItemProps } from 'react-aria-components'
+import { type SelectItem } from '../../types'
 import styles from './ListItem.module.css'
 
 export const ListItem = ({
   children,
   className,
   ...props
-}: ListBoxItemProps<object> & PropsWithChildren): React.ReactElement => {
+}: ListBoxItemProps<SelectItem> & PropsWithChildren): React.ReactElement => {
   return (
     <RACListBoxItem className={classNames(styles.listItem, className)} {...props}>
       {children}

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

@@ -5,6 +5,7 @@ import {
   ListBoxSection as RACListBoxSection,
   type ListBoxSectionProps,
 } from 'react-aria-components'
+import { type SelectSection } from '../../types'
 import styles from './ListSection.module.css'
 
 export const ListSection = ({
@@ -12,7 +13,8 @@ export const ListSection = ({
   className,
   children,
   ...props
-}: ListBoxSectionProps<object> & PropsWithChildren & { name: string }): React.ReactElement => {
+}: ListBoxSectionProps<SelectSection> &
+  PropsWithChildren & { name: string }): React.ReactElement => {
   return (
     <RACListBoxSection {...props}>
       <RACHeader className={classNames(styles.listSectionHeader, className)}>{name}</RACHeader>

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

@@ -0,0 +1,24 @@
+@layer kz-components {
+  .popover {
+    position: absolute;
+    height: auto;
+    background-color: var(--color-white);
+    border-radius: var(--spacing-8);
+    padding: 0;
+    box-shadow: var(--shadow-small-box-shadow);
+    overflow: hidden auto;
+    margin: 0;
+    box-sizing: border-box;
+
+    /* TODO: update width based on design */
+    width: 200px;
+
+    @supports (anchor-name: --anchor) {
+      position-anchor: var(--position-anchor);
+      margin-block: var(--spacing-4);
+      position-area: var(--position-area) center;
+      /* stylelint-disable-next-line declaration-property-value-no-unknown */
+      width: anchor-size(width);
+    }
+  }
+}

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

@@ -0,0 +1,54 @@
+import React, { useLayoutEffect, useMemo, type PropsWithChildren } from 'react'
+
+import { Popover as RACPopover } from 'react-aria-components'
+import { useSingleSelectContext } from '../../context'
+import { type PopoverProps } from '../../types'
+import { usePositioningStyles } from './utils/usePositioningStyles'
+import styles from './Popover.module.css'
+
+export const Popover = ({
+  buttonRef,
+  popoverRef,
+  racPopoverRef,
+  children,
+}: PopoverProps & PropsWithChildren): React.ReactElement => {
+  const { isOpen, setOpen, anchorName } = useSingleSelectContext()
+
+  const { popoverStyle, isPositioned } = usePositioningStyles(buttonRef, popoverRef, anchorName)
+
+  const shouldShowPopover = useMemo(() => isOpen && isPositioned, [isOpen, isPositioned])
+
+  useLayoutEffect(() => {
+    const popover = popoverRef.current
+    if (!popover?.showPopover || !popover?.hidePopover) return
+
+    if (shouldShowPopover) {
+      popover.showPopover()
+    } else {
+      popover.hidePopover()
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [shouldShowPopover])
+
+  return (
+    <RACPopover
+      shouldUpdatePosition={false}
+      trigger="manual"
+      isOpen={isOpen}
+      onOpenChange={setOpen}
+      ref={racPopoverRef}
+    >
+      <div
+        // @ts-expect-error - popover attribute is not included in current ts version, ignore type error
+        popover="manual"
+        ref={popoverRef}
+        className={styles.popover}
+        style={popoverStyle}
+      >
+        {children}
+      </div>
+    </RACPopover>
+  )
+}
+
+Popover.displayName = 'SingleSelect.Popover'

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

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

package/src/__alpha__/SingleSelect/subcomponents/Popover/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './usePopoverPositioning'
+export * from './useSupportsAnchorPositioning'