@coreui/react-pro 5.25.0 → 5.26.0

package/src/components/chip/const.ts

@@ -0,0 +1,3 @@
+// Chips advertise their own focusability via `data-coreui-chip-focusable`,
+// so containers (CChipSet, CChipInput) read it instead of re-deriving it.
+export const SELECTOR_CHIP_FOCUSABLE = '[data-coreui-chip-focusable="true"]:not(.disabled)'

package/src/components/chip-set/CChipSet.tsx

@@ -0,0 +1,183 @@
+import React, {
+  ElementType,
+  HTMLAttributes,
+  KeyboardEvent,
+  ReactNode,
+  forwardRef,
+  useState,
+} from 'react'
+import PropTypes from 'prop-types'
+import classNames from 'classnames'
+
+import { useChipSet, type CChipSetItem } from './useChipSet'
+import { PolymorphicRefForwardingComponent } from '../../helpers'
+import { useForkedRef } from '../../hooks'
+
+export type { CChipSetItem }
+
+const itemValue = (item: string | CChipSetItem): string =>
+  typeof item === 'string' ? item : item.value
+
+export interface CChipSetProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+  /**
+   * Provides an accessible label for the remove button of every chip rendered by the React Chip Set component.
+   */
+  ariaRemoveLabel?: string
+  /**
+   * Specifies the root element or custom component used by the React Chip Set component.
+   */
+  as?: ElementType
+  /**
+   * Renders chips from data instead of children. Each item is a string or an object with a `value`, an optional `label`, and any `CChip` props. Children are used when this is omitted.
+   */
+  chips?: (string | CChipSetItem)[]
+  /**
+   * Adds custom classes to the React Chip Set root element.
+   */
+  className?: string
+  /**
+   * Sets the initial uncontrolled chips. In this mode the React Chip Set component owns the list and removes chips itself; use `chips` (with `onRemove`) for a controlled list.
+   */
+  defaultChips?: (string | CChipSetItem)[]
+  /**
+   * Sets the initial uncontrolled selection of the React Chip Set component.
+   */
+  defaultSelected?: string[]
+  /**
+   * Disables every chip rendered by the React Chip Set component.
+   */
+  disabled?: boolean
+  /**
+   * Turns the chips into filter chips, each showing a leading check icon while selected.
+   */
+  filter?: boolean
+  /**
+   * Callback fired when a chip requests removal. The chips are controlled by their rendered children, so remove the chip from your data in response.
+   */
+  onRemove?: (value: string) => void
+  /**
+   * Callback fired when the selected chip values of the React Chip Set component change.
+   */
+  onSelect?: (selected: string[]) => void
+  /**
+   * Displays a remove button on every chip rendered by the React Chip Set component.
+   */
+  removable?: boolean
+  /**
+   * Replaces the default remove icon on every chip with a custom icon node.
+   */
+  removeIcon?: ReactNode
+  /**
+   * Enables selection behavior for the chips rendered by the React Chip Set component.
+   */
+  selectable?: boolean
+  /**
+   * Controls the selected chip values of the React Chip Set component.
+   *
+   * @controllable onSelect
+   */
+  selected?: string[]
+  /**
+   * Replaces the default selected icon shown by filter chips with a custom icon node.
+   */
+  selectedIcon?: ReactNode
+  /**
+   * Sets how many chips can be selected at once in the React Chip Set component.
+   */
+  selectionMode?: 'single' | 'multiple'
+}
+
+export const CChipSet: PolymorphicRefForwardingComponent<'div', CChipSetProps> = forwardRef<
+  HTMLDivElement,
+  CChipSetProps
+>(
+  (
+    {
+      ariaRemoveLabel,
+      as: Component = 'div',
+      children,
+      chips,
+      className,
+      defaultChips,
+      defaultSelected,
+      disabled,
+      filter,
+      onKeyDown,
+      onRemove,
+      onSelect,
+      removable,
+      removeIcon,
+      selectable,
+      selected,
+      selectedIcon,
+      selectionMode,
+      ...rest
+    },
+    ref
+  ) => {
+    // The chip list is controlled by `chips` (or children) or, with `defaultChips`,
+    // uncontrolled — then the set owns the list and removes chips itself.
+    const isUncontrolledList = chips === undefined && defaultChips !== undefined
+    const [_chips, setChips] = useState<(string | CChipSetItem)[]>(defaultChips ?? [])
+
+    const { rootRef, handleKeyDown, renderChips, renderChipsFromData } = useChipSet({
+      ariaRemoveLabel,
+      defaultSelected,
+      disabled,
+      filter,
+      removable,
+      removeIcon,
+      selectable,
+      selected,
+      selectedIcon,
+      selectionMode,
+      onRemoveChip: (value) => {
+        if (isUncontrolledList) {
+          setChips((prev) => prev.filter((item) => itemValue(item) !== value))
+        }
+        onRemove?.(value)
+      },
+      onSelectionChange: onSelect,
+    })
+    const forkedRef = useForkedRef(ref, rootRef)
+
+    const items = chips ?? (isUncontrolledList ? _chips : undefined)
+
+    return (
+      <Component
+        className={classNames('chip-set', { disabled }, className)}
+        {...(disabled && { 'aria-disabled': true })}
+        onKeyDown={(event: KeyboardEvent<HTMLDivElement>) => {
+          handleKeyDown(event)
+          onKeyDown?.(event)
+        }}
+        {...rest}
+        ref={forkedRef}
+      >
+        {items ? renderChipsFromData(items) : renderChips(children)}
+      </Component>
+    )
+  }
+)
+
+CChipSet.propTypes = {
+  ariaRemoveLabel: PropTypes.string,
+  as: PropTypes.elementType,
+  children: PropTypes.node,
+  chips: PropTypes.array,
+  className: PropTypes.string,
+  defaultChips: PropTypes.array,
+  defaultSelected: PropTypes.array,
+  disabled: PropTypes.bool,
+  filter: PropTypes.bool,
+  onRemove: PropTypes.func,
+  onSelect: PropTypes.func,
+  removable: PropTypes.bool,
+  removeIcon: PropTypes.node,
+  selectable: PropTypes.bool,
+  selected: PropTypes.array,
+  selectedIcon: PropTypes.node,
+  selectionMode: PropTypes.oneOf(['single', 'multiple']),
+}
+
+CChipSet.displayName = 'CChipSet'

package/src/components/chip-set/__tests__/CChipSet.spec.tsx

@@ -0,0 +1,215 @@
+import * as React from 'react'
+import { fireEvent, render } from '@testing-library/react'
+import '@testing-library/jest-dom'
+import { CChip } from '../../chip'
+import { CChipSet } from '../index'
+
+test('loads and displays CChipSet component', async () => {
+  const { container } = render(
+    <CChipSet>
+      <CChip value="a">A</CChip>
+      <CChip value="b">B</CChip>
+    </CChipSet>
+  )
+  expect(container).toMatchSnapshot()
+  expect(container.firstChild).toHaveClass('chip-set')
+})
+
+test('CChipSet passes selectable down to its chips', async () => {
+  const { getByText } = render(
+    <CChipSet selectable={true}>
+      <CChip value="a">A</CChip>
+      <CChip value="b">B</CChip>
+    </CChipSet>
+  )
+
+  expect(getByText('A')).toHaveAttribute('aria-selected', 'false')
+  fireEvent.click(getByText('A'))
+  expect(getByText('A')).toHaveClass('active')
+})
+
+test('CChipSet allows multiple selected chips by default', async () => {
+  const onSelect = jest.fn()
+  const { getByText } = render(
+    <CChipSet selectable={true} onSelect={onSelect}>
+      <CChip value="a">A</CChip>
+      <CChip value="b">B</CChip>
+    </CChipSet>
+  )
+
+  fireEvent.click(getByText('A'))
+  fireEvent.click(getByText('B'))
+
+  expect(getByText('A')).toHaveClass('active')
+  expect(getByText('B')).toHaveClass('active')
+  expect(onSelect).toHaveBeenLastCalledWith(['a', 'b'])
+})
+
+test('CChipSet deselects siblings in single selection mode', async () => {
+  const onSelect = jest.fn()
+  const { getByText } = render(
+    <CChipSet selectable={true} selectionMode="single" onSelect={onSelect}>
+      <CChip value="a">A</CChip>
+      <CChip value="b">B</CChip>
+    </CChipSet>
+  )
+
+  fireEvent.click(getByText('A'))
+  fireEvent.click(getByText('B'))
+
+  expect(getByText('A')).not.toHaveClass('active')
+  expect(getByText('B')).toHaveClass('active')
+  expect(onSelect).toHaveBeenLastCalledWith(['b'])
+})
+
+test('CChipSet honors a controlled selected', async () => {
+  const { getByText } = render(
+    <CChipSet selectable={true} selected={['b']}>
+      <CChip value="a">A</CChip>
+      <CChip value="b">B</CChip>
+    </CChipSet>
+  )
+
+  expect(getByText('A')).not.toHaveClass('active')
+  expect(getByText('B')).toHaveClass('active')
+})
+
+test('CChipSet forwards filter so a selected chip shows a check icon', async () => {
+  const { getByText, container } = render(
+    <CChipSet filter={true} selected={['a']}>
+      <CChip value="a">A</CChip>
+    </CChipSet>
+  )
+
+  expect(getByText('A')).toHaveClass('active')
+  expect(container.querySelector('.chip-check')).toBeInTheDocument()
+})
+
+test('CChipSet moves focus between chips with the keyboard', async () => {
+  const { getByText } = render(
+    <CChipSet selectable>
+      <CChip value="first">First</CChip>
+      <CChip value="second">Second</CChip>
+      <CChip value="third">Third</CChip>
+    </CChipSet>
+  )
+
+  const first = getByText('First')
+  const second = getByText('Second')
+  const third = getByText('Third')
+
+  first.focus()
+  fireEvent.keyDown(first, { key: 'ArrowRight' })
+  expect(second).toHaveFocus()
+
+  fireEvent.keyDown(second, { key: 'End' })
+  expect(third).toHaveFocus()
+
+  fireEvent.keyDown(third, { key: 'Home' })
+  expect(first).toHaveFocus()
+
+  // No cycling past the first chip.
+  fireEvent.keyDown(first, { key: 'ArrowLeft' })
+  expect(first).toHaveFocus()
+})
+
+test('CChipSet mirrors arrow keys in RTL', async () => {
+  document.documentElement.dir = 'rtl'
+
+  const { getByText } = render(
+    <CChipSet selectable>
+      <CChip value="first">First</CChip>
+      <CChip value="second">Second</CChip>
+    </CChipSet>
+  )
+
+  const first = getByText('First')
+  const second = getByText('Second')
+
+  first.focus()
+  // In RTL, ArrowLeft moves to the next chip.
+  fireEvent.keyDown(first, { key: 'ArrowLeft' })
+  expect(second).toHaveFocus()
+
+  fireEvent.keyDown(second, { key: 'ArrowRight' })
+  expect(first).toHaveFocus()
+
+  document.documentElement.dir = ''
+})
+
+test('CChipSet fires onRemove so the parent can drop the chip', async () => {
+  const onRemove = jest.fn()
+
+  const Example = () => {
+    const [values, setValues] = React.useState(['a', 'b'])
+    return (
+      <CChipSet
+        removable
+        onRemove={(value) => {
+          onRemove(value)
+          setValues((prev) => prev.filter((item) => item !== value))
+        }}
+      >
+        {values.map((value) => (
+          <CChip key={value} value={value}>
+            {value.toUpperCase()}
+          </CChip>
+        ))}
+      </CChipSet>
+    )
+  }
+
+  const { getByText, queryByText } = render(<Example />)
+
+  const removeButton = getByText('A').querySelector('.chip-remove')
+  fireEvent.click(removeButton as Element)
+
+  expect(onRemove).toHaveBeenCalledWith('a')
+  expect(queryByText('A')).not.toBeInTheDocument()
+  expect(getByText('B')).toBeInTheDocument()
+})
+
+test('CChipSet with defaultChips removes the chip itself (uncontrolled list)', async () => {
+  const onRemove = jest.fn()
+  const { getByText, queryByText } = render(
+    <CChipSet removable defaultChips={['a', { value: 'b', label: 'B' }]} onRemove={onRemove} />
+  )
+
+  fireEvent.click(getByText('a').querySelector('.chip-remove') as Element)
+
+  expect(onRemove).toHaveBeenCalledWith('a')
+  expect(queryByText('a')).not.toBeInTheDocument()
+  expect(getByText('B')).toBeInTheDocument()
+})
+
+test('CChipSet renders chips from the chips prop (strings and objects)', async () => {
+  const { getByText, container } = render(
+    <CChipSet
+      selectable
+      chips={[
+        'react',
+        { value: 'vue', label: 'Vue' },
+        { value: 'ng', label: 'Angular', selectable: false },
+      ]}
+    />
+  )
+
+  expect(container.querySelectorAll('.chip')).toHaveLength(3)
+  expect(getByText('react')).toBeInTheDocument()
+  expect(getByText('Vue')).toBeInTheDocument()
+
+  // Per-item override still works with the data-driven API.
+  fireEvent.click(getByText('Angular'))
+  expect(getByText('Angular')).not.toHaveClass('active')
+})
+
+test('CChipSet disables every chip', async () => {
+  const { getByText } = render(
+    <CChipSet disabled={true} removable={true}>
+      <CChip value="a">A</CChip>
+    </CChipSet>
+  )
+
+  expect(getByText('A')).toHaveClass('disabled')
+  expect(getByText('A').querySelector('.chip-remove')).toBeNull()
+})

package/src/components/chip-set/__tests__/__snapshots__/CChipSet.spec.tsx.snap

@@ -0,0 +1,22 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`loads and displays CChipSet component 1`] = `
+<div>
+  <div
+    class="chip-set"
+  >
+    <span
+      class="chip"
+      data-coreui-chip-value="a"
+    >
+      A
+    </span>
+    <span
+      class="chip"
+      data-coreui-chip-value="b"
+    >
+      B
+    </span>
+  </div>
+</div>
+`;

package/src/components/chip-set/index.ts

@@ -0,0 +1,3 @@
+import { CChipSet } from './CChipSet'
+
+export { CChipSet }

package/src/components/chip-set/useChipSet.ts

@@ -0,0 +1,243 @@
+import React, {
+  KeyboardEvent,
+  MouseEvent,
+  ReactNode,
+  isValidElement,
+  useEffect,
+  useRef,
+  useState,
+} from 'react'
+
+import { CChip, type CChipProps } from '../chip/CChip'
+import { SELECTOR_CHIP_FOCUSABLE } from '../chip/const'
+import { resolveChipValue } from './utils'
+import { isRTL } from '../../utils'
+
+export interface CChipSetItem extends Omit<CChipProps, 'value' | 'children'> {
+  /**
+   * The value that identifies the chip and tracks its selection.
+   */
+  value: string
+  /**
+   * The chip content. Falls back to `value` when omitted.
+   */
+  label?: ReactNode
+}
+
+// Build a CChip element from a data item (string or descriptor).
+const buildChip = (item: string | CChipSetItem) => {
+  if (typeof item === 'string') {
+    return React.createElement(CChip, { key: item, value: item }, item)
+  }
+
+  const { label, value, ...chipProps } = item
+  return React.createElement(CChip, { key: value, value, ...chipProps }, label ?? value)
+}
+
+export interface UseChipSetOptions {
+  ariaRemoveLabel?: string
+  defaultSelected?: string[]
+  disabled?: boolean
+  filter?: boolean
+  removable?: boolean
+  removeIcon?: ReactNode
+  /**
+   * Move focus to a neighboring chip after one is removed. Containers that own a
+   * different focus target after removal (e.g. CChipInput refocuses its input)
+   * set this to `false`.
+   */
+  restoreFocusOnRemove?: boolean
+  selectable?: boolean
+  selected?: string[]
+  selectedIcon?: ReactNode
+  selectionMode?: 'single' | 'multiple'
+  onRemoveChip?: (value: string) => void
+  onSelectionChange?: (selected: string[]) => void
+}
+
+/**
+ * The shared chip-set engine. Both `CChipSet` and `CChipInput` build on it — the
+ * React equivalent of the vanilla `ChipInput extends ChipSet`. It owns selection
+ * coordination (single/multiple, controlled-or-uncontrolled), roving focus, the
+ * focus-a-neighbor-after-removal behavior, and the per-chip prop injection.
+ * Existence of the chips stays with the caller (its children / value list).
+ */
+export const useChipSet = (options: UseChipSetOptions) => {
+  const {
+    ariaRemoveLabel,
+    defaultSelected = [],
+    disabled,
+    filter,
+    removable,
+    removeIcon,
+    restoreFocusOnRemove = true,
+    selectable,
+    selected,
+    selectedIcon,
+    selectionMode = 'multiple',
+    onRemoveChip,
+    onSelectionChange,
+  } = options
+
+  const rootRef = useRef<HTMLDivElement>(null)
+  const pendingFocusValue = useRef<string | null>(null)
+  const isControlled = selected !== undefined
+  const [_selected, setSelected] = useState<string[]>(defaultSelected)
+  // In controlled mode the selected prop drives selection directly; _selected is
+  // only read when uncontrolled, so no syncing effect is needed.
+  const selectedValues = isControlled ? (selected as string[]) : _selected
+
+  // Focus the saved neighbor once the removed chip has left the DOM.
+  useEffect(() => {
+    if (pendingFocusValue.current === null) {
+      return
+    }
+
+    const selector = `[data-coreui-chip-value="${pendingFocusValue.current}"]`
+    rootRef.current?.querySelector<HTMLElement>(selector)?.focus()
+    pendingFocusValue.current = null
+  })
+
+  const getFocusableChips = (): HTMLElement[] => [
+    ...(rootRef.current?.querySelectorAll<HTMLElement>(SELECTOR_CHIP_FOCUSABLE) ?? []),
+  ]
+
+  const emitSelection = (next: string[]) => {
+    if (!isControlled) {
+      setSelected(next)
+    }
+    onSelectionChange?.(next)
+  }
+
+  const updateSelection = (chipValue: string, nextSelected: boolean) => {
+    const isSelected = selectedValues.includes(chipValue)
+    if (nextSelected === isSelected) {
+      return
+    }
+
+    if (nextSelected) {
+      // Single selection mode keeps only the freshly selected chip.
+      emitSelection(selectionMode === 'single' ? [chipValue] : [...selectedValues, chipValue])
+      return
+    }
+
+    emitSelection(selectedValues.filter((item) => item !== chipValue))
+  }
+
+  const clearSelection = () => {
+    if (selectedValues.length > 0) {
+      emitSelection([])
+    }
+  }
+
+  const removeChip = (chipValue: string) => {
+    if (restoreFocusOnRemove) {
+      const chips = getFocusableChips()
+      const index = chips.findIndex((chip) => chip.dataset.coreuiChipValue === chipValue)
+      // Prefer the next chip, fall back to the previous one at the end.
+      const neighbor = chips[index + 1] ?? chips[index - 1] ?? null
+      pendingFocusValue.current = neighbor?.dataset.coreuiChipValue ?? null
+    }
+
+    emitSelection(selectedValues.filter((item) => item !== chipValue))
+    onRemoveChip?.(chipValue)
+  }
+
+  // Roving focus: arrow keys move between chips and Home/End jump to the edges,
+  // with no cycling. Returns true when the key was handled.
+  const handleKeyDown = (event: KeyboardEvent<HTMLElement>): boolean => {
+    const chip = (event.target as HTMLElement).closest<HTMLElement>(SELECTOR_CHIP_FOCUSABLE)
+    if (!chip) {
+      return false
+    }
+
+    const chips = getFocusableChips()
+    const index = chips.indexOf(chip)
+    // In RTL the visual direction is mirrored, so left/right swap.
+    const rtl = isRTL(rootRef.current)
+
+    switch (event.key) {
+      case 'ArrowLeft': {
+        event.preventDefault()
+        chips[rtl ? index + 1 : index - 1]?.focus()
+        return true
+      }
+
+      case 'ArrowRight': {
+        event.preventDefault()
+        chips[rtl ? index - 1 : index + 1]?.focus()
+        return true
+      }
+
+      case 'Home': {
+        event.preventDefault()
+        chips[0]?.focus()
+        return true
+      }
+
+      case 'End': {
+        event.preventDefault()
+        chips[chips.length - 1]?.focus()
+        return true
+      }
+
+      default: {
+        return false
+      }
+    }
+  }
+
+  const renderChips = (children: ReactNode): ReactNode =>
+    React.Children.map(children, (child, index) => {
+      if (!isValidElement<CChipProps>(child)) {
+        return child
+      }
+
+      const chipValue = resolveChipValue(child, index)
+      const childSelectable = child.props.selectable ?? selectable
+      const childFilter = child.props.filter ?? filter
+      const childRemovable = child.props.removable ?? removable
+      const isCoordinated = Boolean(childSelectable || childFilter)
+
+      return React.cloneElement(child, {
+        ariaRemoveLabel: child.props.ariaRemoveLabel ?? ariaRemoveLabel,
+        disabled: child.props.disabled ?? disabled,
+        filter: childFilter,
+        removable: childRemovable,
+        removeIcon: child.props.removeIcon ?? removeIcon,
+        selectable: childSelectable,
+        selectedIcon: child.props.selectedIcon ?? selectedIcon,
+        ...(isCoordinated && {
+          selected: selectedValues.includes(chipValue),
+          onSelectedChange: (
+            nextSelected: boolean,
+            event: MouseEvent<HTMLElement> | KeyboardEvent<HTMLElement>
+          ) => {
+            updateSelection(chipValue, nextSelected)
+            child.props.onSelectedChange?.(nextSelected, event)
+          },
+        }),
+        ...(childRemovable && {
+          onRemove: (event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLElement>) => {
+            removeChip(chipValue)
+            child.props.onRemove?.(event)
+          },
+        }),
+      })
+    })
+
+  // Build CChip elements from data, then run them through the same transform —
+  // used by CChipSet's `chips` prop and by CChipInput's value list.
+  const renderChipsFromData = (items: (string | CChipSetItem)[]): ReactNode =>
+    renderChips(items.map((item) => buildChip(item)))
+
+  return {
+    rootRef,
+    selectedValues,
+    clearSelection,
+    getFocusableChips,
+    handleKeyDown,
+    renderChips,
+    renderChipsFromData,
+  }
+}

package/src/components/chip-set/utils.ts

@@ -0,0 +1,19 @@
+import { ReactElement } from 'react'
+
+import type { CChipProps } from '../chip/CChip'
+
+/**
+ * Resolves the value used to identify a chip in a `CChipSet`: its explicit
+ * `value` prop, its text children, or the render index as a last resort.
+ */
+export const resolveChipValue = (chip: ReactElement<CChipProps>, index: number): string => {
+  if (chip.props.value !== undefined) {
+    return chip.props.value
+  }
+
+  if (typeof chip.props.children === 'string') {
+    return chip.props.children
+  }
+
+  return String(index)
+}