@chassis-ui/react 0.0.0-20260831090525

package/src/components/chip-input/ChipInput.tsx

@@ -0,0 +1,363 @@
+import React, {
+  forwardRef,
+  HTMLAttributes,
+  KeyboardEvent,
+  ReactNode,
+  useMemo,
+  useRef,
+  useState
+} from 'react'
+import classNames from 'classnames'
+import { useTextField } from 'react-aria'
+import { Item, Key, useListState } from 'react-stately'
+
+import { useControllableState, useForkedRef, useFormField } from '../../hooks'
+import { validationClassName } from '../../utils/validationClassName'
+import { renderFormField } from '../form-field/renderFormField'
+import { ChipList, ChipItem } from './ChipList'
+
+// `allowDuplicates` means two tags can share a value, but react-stately's collection needs a
+// unique key per item — keying on the value alone collapses duplicates into the same node, so
+// selecting or removing one affects all of them. Key on (value, occurrence-within-the-array)
+// instead, recomputed fresh from `tags` on every call rather than cached, so it stays correct
+// whether the array changed via our own add/remove or via an externally-controlled `value` prop.
+const buildTagIds = (list: string[]): string[] => {
+  const seen = new Map<string, number>()
+  return list.map((tag) => {
+    const occurrence = seen.get(tag) ?? 0
+    seen.set(tag, occurrence + 1)
+    return occurrence === 0 ? tag : `${tag}\u0000${occurrence}`
+  })
+}
+
+export interface ChipInputProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'onChange' | 'defaultValue'
+> {
+  /**
+   * An accessible label for the chip group, used when there's no visible `<label>`.
+   */
+  'aria-label'?: string
+  /**
+   * Identifies a visible `<label>` element for the chip group.
+   */
+  'aria-labelledby'?: string
+  /**
+   * Allow the same value to be added more than once. Defaults to `false`.
+   */
+  allowDuplicates?: boolean
+  /**
+   * Space-separated chassis-css chip modifier classes (e.g. `"primary smooth"`) applied to every
+   * chip. Defaults to `"default"`.
+   */
+  chipVariant?: string
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * The initial set of chip values (uncontrolled).
+   */
+  defaultValue?: string[]
+  /**
+   * Prevents new chips from being added and makes existing chips non-interactive.
+   */
+  disabled?: boolean
+  /**
+   * A description for the field, rendered below the chips.
+   */
+  help?: ReactNode
+  /**
+   * `id` forwarded to the text input — useful for pairing with a `<label for>`.
+   */
+  id?: string
+  /**
+   * Set component validation state to invalid.
+   */
+  invalid?: boolean
+  /**
+   * An error message for the field, rendered below the chips when `invalid` is set.
+   */
+  invalidFeedback?: ReactNode
+  /**
+   * The field's caption, rendered as a `FormLabel` associated with the text input.
+   */
+  label?: ReactNode
+  /**
+   * Maximum number of chips allowed. Omit for no limit.
+   */
+  maxChips?: number
+  /**
+   * `name` of an auto-created hidden input per chip, kept in sync with the values, for native
+   * form submission. Omit to skip creating them.
+   */
+  name?: string
+  /**
+   * Callback fired whenever a chip is added or removed.
+   */
+  onChange?: (values: string[]) => void
+  /**
+   * Placeholder shown in the input when empty.
+   */
+  placeholder?: string
+  /**
+   * Character that creates a new chip when typed, or pasted text is split on. Set to `null` to
+   * disable. Defaults to `,`.
+   */
+  separator?: string | null
+  /**
+   * Size the component small or large.
+   */
+  size?: 'small' | 'large'
+  /**
+   * Set component validation state to valid.
+   */
+  valid?: boolean
+  /**
+   * A success message for the field, rendered below the chips when `valid` is set.
+   */
+  validFeedback?: ReactNode
+  /**
+   * The set of chip values (controlled).
+   */
+  value?: string[]
+}
+
+export const ChipInput = forwardRef<HTMLDivElement, ChipInputProps>(
+  (
+    {
+      allowDuplicates = false,
+      'aria-describedby': ariaDescribedBy,
+      'aria-label': ariaLabel,
+      'aria-labelledby': ariaLabelledBy,
+      chipVariant = 'default',
+      className,
+      defaultValue,
+      disabled,
+      help,
+      id,
+      invalid,
+      invalidFeedback,
+      label,
+      maxChips,
+      name,
+      onChange,
+      placeholder,
+      separator = ',',
+      size,
+      valid,
+      validFeedback,
+      value,
+      ...rest
+    }: ChipInputProps,
+    ref
+  ): ReactNode => {
+    const [tags, updateTags] = useControllableState<string[]>(value, defaultValue ?? [], onChange)
+
+    // The one memoized computation of `tags`' ids — `removeTags`, `items`, and `focusLastChip`
+    // below all used to independently recompute this same array from scratch (fresh on every
+    // render, not just when `tags` actually changed); they now all read this instead.
+    const ids = useMemo(() => buildTagIds(tags), [tags])
+
+    // Shared by `addTag` and the paste handler's loop: whether `raw` (already trimmed) is
+    // addable to `list` given `allowDuplicates`. `maxChips` is deliberately not part of this
+    // predicate — the paste loop needs to `break` (stop entirely) on hitting the limit, while an
+    // empty/duplicate value should just be skipped and the loop should keep going.
+    const isAddableValue = (list: string[], trimmed: string) =>
+      trimmed !== '' && (allowDuplicates || !list.includes(trimmed))
+
+    const addTag = (raw: string) => {
+      const trimmed = raw.trim()
+      if (!isAddableValue(tags, trimmed)) return
+      if (maxChips != null && tags.length >= maxChips) return
+      updateTags([...tags, trimmed])
+    }
+
+    const removeTags = (keys: Iterable<Key>) => {
+      const toRemove = new Set(keys)
+      updateTags(tags.filter((_tag, index) => !toRemove.has(ids[index]!)))
+    }
+
+    const items = useMemo<ChipItem[]>(
+      () => tags.map((tag, index) => ({ id: ids[index]!, value: tag })),
+      [tags, ids]
+    )
+
+    const listState = useListState<ChipItem>({
+      children: (item: ChipItem) => (
+        <Item key={item.id} textValue={item.value}>
+          {item.value}
+        </Item>
+      ),
+      disabledKeys: disabled ? items.map((item) => item.id) : undefined,
+      items,
+      selectionMode: 'multiple'
+    })
+
+    const groupRef = useRef<HTMLDivElement>(null)
+    const containerRef = useRef<HTMLDivElement>(null)
+    const forkedRef = useForkedRef(ref, containerRef)
+    const inputRef = useRef<HTMLInputElement>(null)
+    const [inputValue, setInputValue] = useState('')
+
+    const focusLastChip = (extend: boolean) => {
+      if (tags.length === 0) return
+      const lastKey = ids[ids.length - 1]!
+      if (extend) {
+        listState.selectionManager.extendSelection(lastKey)
+      } else {
+        listState.selectionManager.replaceSelection(lastKey)
+      }
+      const rows = groupRef.current?.querySelectorAll<HTMLElement>('[role="row"]')
+      rows?.[rows.length - 1]?.focus()
+    }
+
+    const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+      if (disabled) return
+
+      if (separator && event.key === separator) {
+        event.preventDefault()
+        addTag(inputValue)
+        setInputValue('')
+        return
+      }
+
+      switch (event.key) {
+        case 'Enter': {
+          event.preventDefault()
+          addTag(inputValue)
+          setInputValue('')
+          break
+        }
+        case 'Backspace':
+        case 'Delete': {
+          if (inputValue === '') {
+            event.preventDefault()
+            focusLastChip(false)
+          }
+          break
+        }
+        case 'ArrowLeft': {
+          const input = inputRef.current
+          if (input && input.selectionStart === 0 && input.selectionEnd === 0) {
+            event.preventDefault()
+            focusLastChip(event.shiftKey)
+          }
+          break
+        }
+        case 'Escape': {
+          setInputValue('')
+          listState.selectionManager.clearSelection()
+          inputRef.current?.blur()
+          break
+        }
+        default:
+          break
+      }
+    }
+
+    const handlePaste = (event: React.ClipboardEvent<HTMLInputElement>) => {
+      if (disabled || !separator) return
+      const pasted = event.clipboardData.getData('text')
+      if (!pasted.includes(separator)) return
+
+      event.preventDefault()
+      const parts = pasted.split(separator)
+
+      // Accumulate locally rather than calling `addTag` per part: each call to `addTag` reads
+      // `tags` from this render's closure, so several calls in a row within one event would all
+      // start from the same stale array instead of building on each other.
+      let next = tags
+      // `i` tracks how far the loop got, so a `maxChips` cutoff can leave everything from that
+      // point on (not just the final unsplit part) in the input instead of silently dropping it.
+      let i = 0
+      for (; i < parts.length - 1; i++) {
+        if (maxChips != null && next.length >= maxChips) break
+        const trimmed = parts[i]!.trim()
+        if (!isAddableValue(next, trimmed)) continue
+        next = [...next, trimmed]
+      }
+      if (next !== tags) updateTags(next)
+      setInputValue(parts.slice(i).join(separator))
+    }
+
+    const { describedBy, feedbackId, helpId, inputId, labelId, labelledBy } = useFormField({
+      ariaDescribedBy,
+      ariaLabelledBy,
+      help,
+      id,
+      invalid,
+      invalidFeedback,
+      label,
+      valid,
+      validFeedback
+    })
+
+    const { inputProps } = useTextField(
+      {
+        'aria-describedby': describedBy,
+        'aria-label': ariaLabel ?? (ariaLabelledBy || label ? undefined : 'Add value'),
+        'aria-labelledby': labelledBy,
+        id: inputId,
+        isDisabled: disabled,
+        isInvalid: invalid,
+        onChange: setInputValue,
+        onFocus: () => listState.selectionManager.clearSelection(),
+        onKeyDown: handleKeyDown,
+        placeholder,
+        value: inputValue
+      },
+      inputRef
+    )
+
+    return renderFormField({
+      children: (
+        <div
+          className={classNames(
+            'form-input',
+            'chip-input',
+            size,
+            { disabled },
+            validationClassName(invalid, valid),
+            className
+          )}
+          {...rest}
+          ref={forkedRef}
+        >
+          <ChipList
+            chipVariant={chipVariant}
+            disabled={disabled}
+            groupRef={groupRef}
+            props={{
+              'aria-label': ariaLabel,
+              'aria-labelledby': labelledBy,
+              onRemove: disabled ? undefined : removeTags
+            }}
+            size={size}
+            state={listState}
+          />
+          <input {...inputProps} className="ghost-input" onPaste={handlePaste} ref={inputRef} />
+          {name &&
+            items.map((item) => (
+              <input
+                disabled={disabled}
+                key={item.id}
+                name={name}
+                type="hidden"
+                value={item.value}
+              />
+            ))}
+        </div>
+      ),
+      help,
+      ids: { feedback: feedbackId, help: helpId, input: inputId, label: labelId },
+      invalid,
+      invalidFeedback,
+      label,
+      valid,
+      validFeedback
+    })
+  }
+)
+
+ChipInput.displayName = 'ChipInput'

package/src/components/chip-input/ChipList.tsx

@@ -0,0 +1,95 @@
+import React, { RefObject, useRef } from 'react'
+import classNames from 'classnames'
+import { AriaTagGroupOptions, useButton, useTag, useTagGroup } from 'react-aria'
+import { ListState, Node } from 'react-stately'
+
+import { Chip } from '../chip/Chip'
+import { CloseButton } from '../close-button/CloseButton'
+
+// react-stately's collection builder caches nodes in a WeakMap keyed by each item's own
+// identity, so `items` must be objects — plain tag strings can't be WeakMap keys.
+export interface ChipItem {
+  id: string
+  value: string
+}
+
+interface ChipListProps {
+  chipVariant?: string
+  disabled?: boolean
+  groupRef: RefObject<HTMLDivElement | null>
+  props: AriaTagGroupOptions<ChipItem>
+  size?: 'small' | 'large'
+  state: ListState<ChipItem>
+}
+
+export const ChipList = ({
+  chipVariant,
+  disabled,
+  groupRef,
+  props,
+  size,
+  state
+}: ChipListProps) => {
+  const { gridProps } = useTagGroup(props, state, groupRef)
+
+  return (
+    <div {...gridProps} style={{ display: 'contents' }} ref={groupRef as RefObject<HTMLDivElement>}>
+      {[...state.collection].map((item) => (
+        <ChipRow
+          chipVariant={chipVariant}
+          disabled={disabled}
+          item={item}
+          key={item.key}
+          size={size}
+          state={state}
+        />
+      ))}
+    </div>
+  )
+}
+
+interface ChipRowProps {
+  chipVariant?: string
+  disabled?: boolean
+  item: Node<ChipItem>
+  size?: 'small' | 'large'
+  state: ListState<ChipItem>
+}
+
+// Renders one tag as the shared `Chip` component, wrapped in the row/gridcell markup
+// `useTag`'s grid semantics require — see FORMS.md-adjacent notes in ChipInput.tsx for why the
+// grid role lives on `ChipList`'s own wrapper rather than `.chip-input` itself. The `active`
+// class communicates selection directly (react-aria's `aria-selected`, from `rowProps`, is the
+// actual ARIA signal); `Chip`'s own `pressed`/`aria-pressed` prop is deliberately left unset
+// here since `aria-pressed` isn't a valid property on a `role="row"` element.
+const ChipRow = ({ chipVariant, disabled, item, size, state }: ChipRowProps) => {
+  const ref = useRef<HTMLDivElement>(null)
+  const { rowProps, gridCellProps, removeButtonProps, allowsRemoving } = useTag(
+    { item },
+    state,
+    ref
+  )
+  const buttonRef = useRef<HTMLButtonElement>(null)
+  const { buttonProps } = useButton(removeButtonProps, buttonRef)
+
+  return (
+    <Chip
+      {...rowProps}
+      className={classNames(chipVariant, { active: state.selectionManager.isSelected(item.key) })}
+      component="div"
+      disabled={disabled}
+      ref={ref}
+      size={size}
+    >
+      <div {...gridCellProps} style={{ display: 'contents' }}>
+        {item.rendered}
+        {allowsRemoving && (
+          // react-aria's generic ButtonHTMLAttributes typing includes a legacy `color?: string`
+          // attribute that's wider than CloseButton's `color?: ContextColor` prop; buttonProps
+          // never actually sets it, so it's safe to omit from the spread's type.
+          <CloseButton {...(buttonProps as Omit<typeof buttonProps, 'color'>)} ref={buttonRef} />
+        )}
+      </div>
+    </Chip>
+  )
+}

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

@@ -0,0 +1,2 @@
+export { ChipInput } from './ChipInput'
+export type { ChipInputProps } from './ChipInput'

package/src/components/close-button/CloseButton.tsx

@@ -0,0 +1,205 @@
+import React, {
+  ElementType,
+  ForwardRefRenderFunction,
+  MouseEventHandler,
+  ReactElement,
+  Ref
+} from 'react'
+import classNames from 'classnames'
+import { mergeProps } from 'react-aria'
+
+import { ContextColor, ContextStyle } from '../../types'
+import { useButtonSemantics, useDisabledAnchorGuard } from '../../hooks'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+
+type CloseButtonOwnProps<C extends ElementType> = {
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * Sets the color of the component to one of Chassis context colors. Applies the
+   * `context` class alongside it, so the icon picks up that color without needing
+   * an ancestor `.context` wrapper.
+   */
+  color?: ContextColor
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   * A custom HTML tag (e.g. `'span'`) gets button semantics — role, focus, Enter/Space
+   * activation — filled in automatically. A component is trusted to handle its own semantics,
+   * so pass one that's already interactive (e.g. `Button`).
+   */
+  component?: C
+  /**
+   * Toggle the disabled state for the component.
+   */
+  disabled?: boolean
+  /**
+   * The href attribute specifies the URL of the page the link goes to. Only meaningful when
+   * `component` is `'a'`.
+   */
+  href?: string
+  /**
+   * The accessible label announced by assistive technology. Override this to
+   * localize the button for non-English contexts.
+   */
+  label?: string
+  /**
+   * Fires on click. Typed for every element `component` can actually render (`button` or `a`
+   * natively, plus whatever a custom `component` renders), rather than narrowed to
+   * `HTMLButtonElement` alone.
+   */
+  onClick?: MouseEventHandler<HTMLButtonElement | HTMLAnchorElement>
+  /**
+   * Size the component small or large.
+   */
+  size?: 'small' | 'large'
+  /**
+   * Specifies the type of button. Always specify the type attribute for the `<button>` element.
+   * Different browsers may use different default types for the `<button>` element.
+   */
+  type?: 'button' | 'submit' | 'reset'
+  /**
+   * Set the close button's context style variant. Applies the `context` class
+   * alongside it, same as `color`.
+   */
+  variant?: ContextStyle
+}
+
+export type CloseButtonProps<C extends ElementType = 'button'> = PolymorphicComponentProps<
+  C,
+  CloseButtonOwnProps<C>
+>
+
+type CloseButtonComponent = (<C extends ElementType = 'button'>(
+  props: CloseButtonProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function CloseButtonRender<C extends ElementType = 'button'>(
+  {
+    children,
+    className,
+    color,
+    component,
+    disabled,
+    href,
+    label,
+    onClick,
+    size,
+    type = 'button',
+    variant,
+    ...rest
+  }: CloseButtonProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const component_ = component ?? 'button'
+
+  // A component reference (e.g. `Button`) has its own visual identity and its own
+  // `color`/`size`/`variant` semantics — CloseButton's icon styling (the `close-button`
+  // class and its context/color/variant/size classes) would just conflict with it, and
+  // would also swallow those props before the component ever saw them. So a component
+  // reference gets none of CloseButton's own styling; `color`/`size`/`variant` pass
+  // through untouched, same as `className`, letting the component interpret them itself.
+  const isComponentReference = typeof component_ !== 'string'
+
+  // Only a bare, non-`button` HTML tag needs the `.disabled` class applied by hand — a real
+  // `<button>` gets native `:disabled` styling for free (chassis-css matches both selectors,
+  // `&:disabled, &.disabled`), and a component reference isn't styled by CloseButton at all
+  // (see `isComponentReference` above).
+  const _className = isComponentReference
+    ? className
+    : classNames(
+        'close-button',
+        { context: color || variant, disabled: component_ !== 'button' && disabled },
+        color,
+        variant,
+        size,
+        className
+      )
+
+  // The default icon-only close button has no visible text, so it needs the 'Close' fallback
+  // as its accessible name. Once `children` renders visible content (e.g. custom text passed
+  // through `component`), let that content be the accessible name instead — forcing the
+  // fallback label here would silently override it (a Label-in-Name accessibility failure).
+  // An explicit `label` always wins either way, same as an explicit `aria-label` always did.
+  const _label = label ?? (children == null ? 'Close' : undefined)
+
+  // `<a>` has no real `disabled` attribute, so a disabled link close-button still fires
+  // click (and still navigates) unless it's blocked here, same guard `Button` applies.
+  const handleClick = useDisabledAnchorGuard<HTMLButtonElement | HTMLAnchorElement>(
+    component_ === 'a',
+    disabled,
+    onClick
+  )
+
+  const { buttonProps, forkedRef } = useButtonSemantics<HTMLButtonElement | HTMLAnchorElement>(
+    ref as Ref<HTMLButtonElement | HTMLAnchorElement>,
+    { disabled, onClick }
+  )
+
+  // Rendered as explicit branches, same as `Button`, rather than one `<Component>` tag
+  // driven by a `'button' | 'a' | ElementType`-typed variable — a union-typed tag would
+  // make JSX intersect all of `button`/`a`/custom prop types at once.
+  // `aria-label={_label}` comes before `...rest` in every branch below so that an explicit
+  // `aria-label` (not destructured above, so it lands in `rest`) overrides the computed
+  // fallback via JSX's last-attribute-wins rule, rather than the other way around.
+  if (component_ === 'button') {
+    return (
+      <button
+        className={_className}
+        aria-label={_label}
+        {...(rest as Record<string, unknown>)}
+        type={type}
+        disabled={disabled}
+        onClick={handleClick}
+        ref={ref as Ref<HTMLButtonElement>}
+      >
+        {children}
+      </button>
+    )
+  }
+
+  if (component_ === 'a') {
+    return (
+      <a
+        className={_className}
+        aria-label={_label}
+        {...(rest as Record<string, unknown>)}
+        href={href}
+        onClick={handleClick}
+        {...(disabled && { 'aria-disabled': true, tabIndex: -1 })}
+        ref={ref as Ref<HTMLAnchorElement>}
+      >
+        {children}
+      </a>
+    )
+  }
+
+  const Component = component_ as ElementType
+
+  // Only a bare, non-`button`/`a` HTML tag (e.g. `'span'`) reaches here needing synthesized
+  // button semantics — a component reference is trusted to already be interactive, so it
+  // skips `buttonProps` (double keyboard activation) and instead gets `color`/`size`/`variant`
+  // passed through untouched, per the comment on `isComponentReference` above.
+  return (
+    <Component
+      className={_className}
+      aria-label={_label}
+      {...(isComponentReference
+        ? ({ color, size, variant, disabled, onClick, ...rest } as Record<string, unknown>)
+        : (mergeProps(rest, buttonProps) as Record<string, unknown>))}
+      ref={isComponentReference ? ref : forkedRef}
+    >
+      {children}
+    </Component>
+  )
+}
+
+export const CloseButton = createPolymorphicComponent<CloseButtonComponent>(
+  CloseButtonRender as ForwardRefRenderFunction<Element, CloseButtonProps<ElementType>>,
+  'CloseButton'
+)

package/src/components/close-button/index.ts

@@ -0,0 +1,2 @@
+export { CloseButton } from './CloseButton'
+export type { CloseButtonProps } from './CloseButton'