@chassis-ui/react 0.0.0-20260831090525

package/src/components/checkbox/Checkbox.tsx

@@ -0,0 +1,236 @@
+import React, {
+  forwardRef,
+  InputHTMLAttributes,
+  ReactNode,
+  useContext,
+  useEffect,
+  useRef
+} from 'react'
+import classNames from 'classnames'
+import {
+  AriaCheckboxGroupItemProps,
+  AriaCheckboxProps,
+  useCheckbox,
+  useCheckboxGroupItem
+} from 'react-aria'
+import { CheckboxGroupState, useToggleState } from 'react-stately'
+
+import { useForkedRef } from '../../hooks'
+import { ContextColor } from '../../types'
+import { validationClassName } from '../../utils/validationClassName'
+
+import { CheckboxGroupContext } from './context'
+import { ButtonObject, renderFormCheck } from '../form/renderFormCheck'
+
+export type { ButtonObject } from '../form/renderFormCheck'
+
+export interface CheckboxProps extends Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  'checked' | 'defaultChecked' | 'onChange' | 'size'
+> {
+  /**
+   * Create button-like checkboxes.
+   */
+  button?: ButtonObject
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Sets the color of the check indicator to one of Chassis context colors. Ignored when `button` is set.
+   */
+  color?: ContextColor
+  /**
+   * Whether the checkbox is selected, uncontrolled. Ignored when rendered inside a `<CheckboxGroup>` —
+   * the group's `value`/`defaultValue` owns selection there.
+   */
+  defaultSelected?: boolean
+  /**
+   * The id global attribute defines an identifier (ID) that must be unique in the whole document.
+   */
+  id?: string
+  /**
+   * Checkbox indeterminate property.
+   */
+  indeterminate?: boolean
+  /**
+   * Set component validation state to invalid.
+   */
+  invalid?: boolean
+  /**
+   * Whether the checkbox is selected, controlled. Ignored when rendered inside a `<CheckboxGroup>` —
+   * the group's `value`/`defaultValue` owns selection there.
+   */
+  isSelected?: boolean
+  /**
+   * The element represents a caption for a component.
+   */
+  label?: ReactNode
+  /**
+   * Callback fired when the selected state changes. Ignored when rendered inside a `<CheckboxGroup>` —
+   * use the group's `onChange` instead.
+   */
+  onChange?: (isSelected: boolean) => void
+  /**
+   * Size the component small or large.
+   */
+  size?: 'small' | 'large'
+  /**
+   * Set component validation state to valid.
+   */
+  valid?: boolean
+  /**
+   * The value of the checkbox, used when submitting an HTML form. Required when rendered inside a
+   * `<CheckboxGroup>` — it identifies this item within the group's selected values.
+   */
+  value?: string
+}
+
+const CheckboxStandalone = forwardRef<HTMLInputElement, CheckboxProps>(
+  (
+    {
+      button,
+      className,
+      color,
+      defaultSelected,
+      disabled,
+      id,
+      indeterminate,
+      invalid,
+      isSelected,
+      label,
+      onChange,
+      size,
+      valid,
+      ...rest
+    },
+    ref
+  ) => {
+    const inputRef = useRef<HTMLInputElement>(null)
+    const forkedRef = useForkedRef(ref, inputRef)
+
+    const toggleState = useToggleState({
+      defaultSelected,
+      isDisabled: disabled,
+      isSelected,
+      onChange
+    })
+
+    const { inputProps } = useCheckbox(
+      {
+        ...rest,
+        children: label,
+        isDisabled: disabled,
+        isIndeterminate: indeterminate,
+        isInvalid: invalid,
+        value: rest.value as string | undefined
+      } as AriaCheckboxProps,
+      toggleState,
+      inputRef
+    )
+
+    const inputClassName = classNames(validationClassName(invalid, valid))
+
+    return renderFormCheck({
+      button,
+      className,
+      color,
+      input: <input {...inputProps} className={inputClassName} id={id} ref={forkedRef} />,
+      invalid,
+      label,
+      size,
+      valid
+    })
+  }
+)
+CheckboxStandalone.displayName = 'CheckboxStandalone'
+
+interface CheckboxGroupItemProps extends CheckboxProps {
+  groupState: CheckboxGroupState
+  groupValid?: boolean
+}
+
+const CheckboxGroupItem = forwardRef<HTMLInputElement, CheckboxGroupItemProps>(
+  (
+    {
+      button,
+      className,
+      color,
+      defaultSelected: _defaultSelected,
+      disabled,
+      groupState,
+      groupValid,
+      id,
+      indeterminate,
+      invalid: itemInvalid,
+      isSelected: _isSelected,
+      label,
+      onChange: _onChange,
+      size,
+      valid: itemValid,
+      ...rest
+    },
+    ref
+  ) => {
+    // The group's own invalid/valid cascades to every item, same as RadioGroup does for Radio —
+    // but an item can still override it with its own invalid/valid, since (unlike a lone Radio) a
+    // lone Checkbox's validity is independently meaningful (see FORMS.md).
+    const invalid = itemInvalid ?? groupState.isInvalid
+    const valid = itemValid ?? groupValid
+    const inputRef = useRef<HTMLInputElement>(null)
+    const forkedRef = useForkedRef(ref, inputRef)
+
+    // Once per mount, not on every render — these are dev-time misuse warnings, not something
+    // that needs to re-fire for every keystroke a parent's re-render happens to cause.
+    useEffect(() => {
+      if (!rest.value) {
+        console.error('Checkbox: a `value` prop is required when rendered inside a CheckboxGroup.')
+      }
+      if (_defaultSelected !== undefined || _isSelected !== undefined || _onChange !== undefined) {
+        console.warn(
+          'Checkbox: `defaultSelected`, `isSelected`, and `onChange` are ignored inside a ' +
+            "CheckboxGroup — selection is owned by the group's `value`/`defaultValue`/`onChange`."
+        )
+      }
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [])
+
+    const { inputProps } = useCheckboxGroupItem(
+      {
+        ...rest,
+        children: label,
+        isDisabled: disabled,
+        isIndeterminate: indeterminate,
+        isInvalid: invalid,
+        value: rest.value as string
+      } as AriaCheckboxGroupItemProps,
+      groupState,
+      inputRef
+    )
+
+    const inputClassName = classNames(validationClassName(invalid, valid))
+
+    return renderFormCheck({
+      button,
+      className,
+      color,
+      input: <input {...inputProps} className={inputClassName} id={id} ref={forkedRef} />,
+      invalid,
+      label,
+      size,
+      valid
+    })
+  }
+)
+CheckboxGroupItem.displayName = 'CheckboxGroupItem'
+
+export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>((props, ref) => {
+  const group = useContext(CheckboxGroupContext)
+  return group ? (
+    <CheckboxGroupItem {...props} groupState={group.state} groupValid={group.valid} ref={ref} />
+  ) : (
+    <CheckboxStandalone {...props} ref={ref} />
+  )
+})
+
+Checkbox.displayName = 'Checkbox'

package/src/components/checkbox/CheckboxGroup.tsx

@@ -0,0 +1,145 @@
+import React, { forwardRef, HTMLAttributes, ReactNode } from 'react'
+import classNames from 'classnames'
+import { AriaCheckboxGroupProps, useCheckboxGroup } from 'react-aria'
+import { useCheckboxGroupState } from 'react-stately'
+
+import { validationClassName } from '../../utils/validationClassName'
+
+import { CheckboxGroupContext } from './context'
+import { FormFeedback } from '../form/FormFeedback'
+import { FormHelp } from '../form/FormHelp'
+import { Flex } from '../flex'
+
+export interface CheckboxGroupProps extends Omit<
+  HTMLAttributes<HTMLFieldSetElement>,
+  'defaultValue' | 'onChange'
+> {
+  /**
+   * One or more `<Checkbox>` elements.
+   */
+  children: ReactNode
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * The selected values, uncontrolled.
+   */
+  defaultValue?: string[]
+  /**
+   * A description for the group, rendered below the options.
+   */
+  description?: ReactNode
+  /**
+   * Disables every checkbox in the group.
+   */
+  disabled?: boolean
+  /**
+   * An error message for the group, rendered below the options when `invalid` is set.
+   */
+  errorMessage?: ReactNode
+  /**
+   * Set group validation state to invalid.
+   */
+  invalid?: boolean
+  /**
+   * The group's caption, rendered as a `<legend>`.
+   */
+  label?: ReactNode
+  /**
+   * The name for the group, used for native form submission.
+   */
+  name?: string
+  /**
+   * Callback fired when the selected values change.
+   */
+  onChange?: (value: string[]) => void
+  /**
+   * Lay the group's checkboxes out on the same horizontal row instead of stacking them.
+   */
+  orientation?: 'horizontal' | 'vertical'
+  /**
+   * Marks the group as required.
+   */
+  required?: boolean
+  /**
+   * Set group validation state to valid.
+   */
+  valid?: boolean
+  /**
+   * The selected values, controlled.
+   */
+  value?: string[]
+}
+
+export const CheckboxGroup = forwardRef<HTMLFieldSetElement, CheckboxGroupProps>(
+  (
+    {
+      children,
+      className,
+      defaultValue,
+      description,
+      disabled,
+      errorMessage,
+      invalid,
+      label,
+      name,
+      onChange,
+      orientation,
+      required,
+      valid,
+      value,
+      ...rest
+    },
+    ref
+  ) => {
+    const groupProps = {
+      ...rest,
+      defaultValue,
+      description,
+      errorMessage,
+      isDisabled: disabled,
+      isInvalid: invalid,
+      isRequired: required,
+      label,
+      name,
+      onChange,
+      value
+    }
+
+    const state = useCheckboxGroupState(groupProps)
+    const {
+      groupProps: ariaGroupProps,
+      labelProps,
+      descriptionProps,
+      errorMessageProps
+    } = useCheckboxGroup(groupProps as AriaCheckboxGroupProps, state)
+
+    const _className = classNames('form-field', validationClassName(invalid, valid), className)
+
+    const items = (
+      <CheckboxGroupContext.Provider value={{ state, valid }}>
+        {children}
+      </CheckboxGroupContext.Provider>
+    )
+
+    return (
+      <fieldset {...rest} {...ariaGroupProps} className={_className} ref={ref}>
+        {label && (
+          <legend className="form-label" {...labelProps}>
+            {label}
+          </legend>
+        )}
+        {orientation === 'horizontal' ? <Flex gap="medium">{items}</Flex> : items}
+        {description && <FormHelp {...descriptionProps}>{description}</FormHelp>}
+        {invalid && errorMessage && (
+          <FormFeedback invalid {...errorMessageProps}>
+            {errorMessage}
+          </FormFeedback>
+        )}
+      </fieldset>
+    )
+  }
+)
+
+CheckboxGroup.displayName = 'CheckboxGroup'

package/src/components/checkbox/context.ts

@@ -0,0 +1,14 @@
+import { createContext } from 'react'
+import { CheckboxGroupState } from 'react-stately'
+
+export interface CheckboxGroupContextValue {
+  state: CheckboxGroupState
+  /**
+   * `CheckboxGroup`'s own `valid` prop, mirrored here since it has no react-stately equivalent to
+   * read off `state` the way `isInvalid` does — each `Checkbox` needs it to apply its own
+   * `is-valid` class when the item doesn't set its own (same pattern as `RadioGroupContext`).
+   */
+  valid?: boolean
+}
+
+export const CheckboxGroupContext = createContext<CheckboxGroupContextValue | null>(null)

package/src/components/checkbox/index.ts

@@ -0,0 +1,4 @@
+export { Checkbox } from './Checkbox'
+export type { CheckboxProps, ButtonObject } from './Checkbox'
+export { CheckboxGroup } from './CheckboxGroup'
+export type { CheckboxGroupProps } from './CheckboxGroup'

package/src/components/chip/Chip.tsx

@@ -0,0 +1,183 @@
+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 ChipOwnProps<C extends ElementType> = {
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Sets the color of the component to one of Chassis context colors.
+   */
+  color?: ContextColor
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   * Defaults to `span`, or `a` when `href` is set.
+   */
+  component?: C
+  /**
+   * Toggle the disabled state for the component. Applied as the native `disabled` attribute when
+   * `component` is `button`, or the `.disabled` class for every other element (a bare `<span>`/
+   * `<a>` has no real `disabled` attribute).
+   */
+  disabled?: boolean
+  /**
+   * Renders the chip as a link to this URL. Defaults `component` to `a`.
+   */
+  href?: string
+  /**
+   * Fires on click. Typed for every element `component` can actually render, rather than
+   * narrowed to whichever element `C` happens to be.
+   */
+  onClick?: MouseEventHandler<HTMLElement>
+  /**
+   * Marks the chip as pressed for toggle-style usage (e.g. a filter chip). Applies the `.active`
+   * class and sets `aria-pressed` so assistive technology announces the toggle state.
+   */
+  pressed?: boolean
+  /**
+   * Size the component small or large.
+   */
+  size?: 'small' | 'large'
+  /**
+   * Specifies the type of button. Only applies when `component` is `button`. Different browsers
+   * may use different default types for the `<button>` element, so always specify it explicitly.
+   */
+  type?: 'button' | 'submit' | 'reset'
+  /**
+   * Set the chip style variant. `solid`/`basic` render the default look with no extra class.
+   */
+  variant?: ContextStyle
+}
+
+export type ChipProps<C extends ElementType = 'span'> = PolymorphicComponentProps<
+  C,
+  ChipOwnProps<C>
+>
+
+type ChipComponent = (<C extends ElementType = 'span'>(
+  props: ChipProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function ChipRender<C extends ElementType = 'span'>(
+  {
+    children,
+    className,
+    color,
+    component,
+    disabled,
+    href,
+    onClick,
+    pressed,
+    size,
+    type = 'button',
+    variant,
+    ...rest
+  }: ChipProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  // Only defaults to `a` when `component` wasn't explicitly passed — an explicit `component`
+  // (even alongside `href`) always wins.
+  const Component = (component ?? (href ? 'a' : 'span')) as ElementType
+  const isButton = Component === 'button'
+  const isAnchor = Component === 'a'
+
+  const _className = classNames(
+    'chip',
+    color,
+    size,
+    {
+      outline: variant === 'outline',
+      smooth: variant === 'smooth',
+      active: pressed,
+      disabled: !isButton && disabled
+    },
+    className
+  )
+
+  // `<a>`/`<span>`/`<div>` have no real `disabled` attribute, so a disabled non-button chip
+  // still fires click (and an anchor still navigates) unless it's blocked here, same guard
+  // `Button`/`CloseButton` apply.
+  const handleClick = useDisabledAnchorGuard<HTMLElement>(!isButton, disabled, onClick)
+
+  // A default (non-`button`/`a`) chip — the documented `pressed`/filter-chip use case — gets a
+  // raw `onClick` with no keyboard semantics otherwise, the same gap `Link` fills via
+  // `useButtonSemantics`. Skipped when the caller already supplied their own `role` via `rest`
+  // (e.g. `ChipList`'s `role="row"` grid semantics) — that caller is trusted to handle its own
+  // keyboard interaction, same as `CloseButton`'s `isComponentReference` escape hatch.
+  const hasExplicitRole = (rest as Record<string, unknown>).role !== undefined
+  const needsButtonSemantics = !isButton && !isAnchor && !!onClick && !hasExplicitRole
+  const { buttonProps, forkedRef } = useButtonSemantics<HTMLElement>(ref as Ref<HTMLElement>, {
+    disabled,
+    onClick
+  })
+
+  if (isButton) {
+    return (
+      <button
+        {...(rest as Record<string, unknown>)}
+        aria-pressed={pressed}
+        className={_className}
+        disabled={disabled}
+        onClick={handleClick as MouseEventHandler<HTMLButtonElement>}
+        ref={ref as Ref<HTMLButtonElement>}
+        type={type}
+      >
+        {children}
+      </button>
+    )
+  }
+
+  if (isAnchor) {
+    return (
+      <a
+        {...(rest as Record<string, unknown>)}
+        aria-pressed={pressed}
+        className={_className}
+        href={href}
+        onClick={handleClick as MouseEventHandler<HTMLAnchorElement>}
+        {...(disabled && { 'aria-disabled': true, tabIndex: -1 })}
+        ref={ref as Ref<HTMLAnchorElement>}
+      >
+        {children}
+      </a>
+    )
+  }
+
+  return (
+    <Component
+      {...(mergeProps(rest, needsButtonSemantics ? buttonProps : {}) as Record<string, unknown>)}
+      aria-pressed={pressed}
+      className={_className}
+      {...(!needsButtonSemantics && { onClick: handleClick })}
+      {...(disabled && { 'aria-disabled': true })}
+      // `href` was only ever forwarded when it also forced `Component` to `'a'` — now that an
+      // explicit `component` wins over that default (see above), it needs to keep reaching a
+      // custom `component`/HTML tag directly, same as `Avatar`'s equivalent fix.
+      {...(href && { href })}
+      ref={needsButtonSemantics ? forkedRef : ref}
+    >
+      {children}
+    </Component>
+  )
+}
+
+export const Chip = createPolymorphicComponent<ChipComponent>(
+  ChipRender as ForwardRefRenderFunction<Element, ChipProps<ElementType>>,
+  'Chip'
+)

package/src/components/chip/index.ts

@@ -0,0 +1,2 @@
+export { Chip } from './Chip'
+export type { ChipProps } from './Chip'