@chassis-ui/react 0.0.0-20260831090525

package/src/components/avatar/Avatar.tsx

@@ -0,0 +1,134 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import { ContextColor, ExtendedSizing } from '../../types'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+import { Link } from '../link/Link'
+import { Badge } from '../badge'
+import { AvatarImage } from './AvatarImage'
+
+type AvatarOwnProps<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
+  /**
+   * Toggle the disabled state for the component. Only applies when `component` is `a` or `button`.
+   */
+  disabled?: boolean
+  /**
+   * Renders the smooth (tinted background) context variant instead of the solid default.
+   */
+  smooth?: boolean
+  /**
+   * Sets the size of the component to one of Chassis component sizes.
+   */
+  size?: ExtendedSizing
+  /**
+   * 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. Set explicitly to `button` (or another
+   * interactive element/component) to make a non-link avatar focusable and clickable.
+   */
+  component?: C
+  /**
+   * Image source. When set, renders an `AvatarImage` in place of `children`.
+   */
+  src?: string
+  /**
+   * Alt text for the image rendered when `src` is set.
+   */
+  alt?: string
+  /**
+   * Renders the avatar as a link to this URL. Defaults `component` to `a`. Passed through to a
+   * custom `component` too, regardless of whether it resolves to a native `a`/`button`.
+   */
+  href?: string
+  /**
+   * Renders a status badge in the bottom-end corner, in one of the Chassis themed colors.
+   */
+  status?: ContextColor
+  /**
+   * Accessible label for the status badge, exposed to assistive tech as visually hidden text.
+   * Falls back to the `status` value itself.
+   */
+  statusLabel?: string
+}
+
+export type AvatarProps<C extends ElementType = 'span'> = PolymorphicComponentProps<
+  C,
+  AvatarOwnProps<C>
+>
+
+type AvatarComponent = (<C extends ElementType = 'span'>(
+  props: AvatarProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function AvatarRender<C extends ElementType = 'span'>(
+  {
+    children,
+    className,
+    color,
+    disabled,
+    smooth,
+    size,
+    component,
+    src,
+    alt = 'Profile picture',
+    href,
+    status,
+    statusLabel,
+    ...rest
+  }: AvatarProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const tag = component ?? (href ? 'a' : 'span')
+  const isInteractive = tag === 'a' || tag === 'button'
+
+  const _className = classNames(
+    'avatar',
+    color,
+    size,
+    { smooth },
+    !isInteractive && { disabled },
+    className
+  )
+
+  const Component = (isInteractive ? Link : tag) as ElementType
+
+  return (
+    <Component
+      className={_className}
+      {...(isInteractive && { component: tag })}
+      // `disabled`/`href` used to only reach `Component` when `tag` was the native `'a'`/`'button'`
+      // string (routed through `Link`, which already forwards them itself) — a custom `component`
+      // (e.g. a router `Link`) fell through this `isInteractive` check and silently never received
+      // either prop. Passing them unconditionally fixes that; they're harmless no-ops on a plain,
+      // non-interactive `'span'`.
+      disabled={disabled}
+      href={href}
+      {...(tag === 'button' && { type: 'button' })}
+      {...rest}
+      ref={ref}
+    >
+      {src ? <AvatarImage src={src} alt={alt} /> : children}
+      {status && (
+        <Badge color={status} circle>
+          <span className="visually-hidden">{statusLabel ?? status}</span>
+        </Badge>
+      )}
+    </Component>
+  )
+}
+
+export const Avatar = createPolymorphicComponent<AvatarComponent>(
+  AvatarRender as ForwardRefRenderFunction<Element, AvatarProps<ElementType>>,
+  'Avatar'
+)

package/src/components/avatar/AvatarImage.tsx

@@ -0,0 +1,19 @@
+import React, { forwardRef, ImgHTMLAttributes } from 'react'
+import classNames from 'classnames'
+
+export interface AvatarImageProps extends ImgHTMLAttributes<HTMLImageElement> {
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+}
+
+export const AvatarImage = forwardRef<HTMLImageElement, AvatarImageProps>(
+  ({ className, ...rest }, ref) => {
+    const _className = classNames('avatar-image', className)
+
+    return <img className={_className} {...rest} ref={ref} />
+  }
+)
+
+AvatarImage.displayName = 'AvatarImage'

package/src/components/avatar/AvatarStack.tsx

@@ -0,0 +1,98 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement, ReactNode } from 'react'
+import classNames from 'classnames'
+
+import { ContextColor, ExtendedSizing } from '../../types'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+import { Avatar } from './Avatar'
+
+export interface AvatarStackItemDef {
+  /**
+   * React key for the rendered `Avatar`. Falls back to the item's index in `data`.
+   */
+  key?: string | number
+  /**
+   * Image source, rendered via `AvatarImage`.
+   */
+  src?: string
+  /**
+   * Alt text for the image rendered when `src` is set.
+   */
+  alt?: string
+  /**
+   * Renders the avatar as a link to this URL.
+   */
+  href?: string
+  /**
+   * Renders a status badge in one of the Chassis themed colors.
+   */
+  status?: ContextColor
+  /**
+   * Accessible label for the status badge.
+   */
+  statusLabel?: string
+  /**
+   * Content to render when `src` isn't set, e.g. initials or a "+5" overflow count.
+   */
+  content?: ReactNode
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: ElementType
+}
+
+type AvatarStackOwnProps<C extends ElementType> = {
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C
+  /**
+   * Sets the size of every `Avatar` in the stack to one of Chassis component sizes.
+   */
+  size?: ExtendedSizing
+  /**
+   * Renders a `Avatar` for each item, ahead of any JSX `children` (handy for a trailing "+N"
+   * overflow avatar).
+   */
+  items?: AvatarStackItemDef[]
+}
+
+export type AvatarStackProps<C extends ElementType = 'div'> = PolymorphicComponentProps<
+  C,
+  AvatarStackOwnProps<C>
+>
+
+type AvatarStackComponent = (<C extends ElementType = 'div'>(
+  props: AvatarStackProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function AvatarStackRender<C extends ElementType = 'div'>(
+  { children, className, component, items, size, ...rest }: AvatarStackProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = (component ?? 'div') as ElementType
+  const _className = classNames('avatar-stack', size, className)
+
+  return (
+    <Component className={_className} {...rest} ref={ref}>
+      {items?.map(({ key, content, ...item }, index) => (
+        <Avatar key={key ?? index} {...item}>
+          {content}
+        </Avatar>
+      ))}
+      {children}
+    </Component>
+  )
+}
+
+export const AvatarStack = createPolymorphicComponent<AvatarStackComponent>(
+  AvatarStackRender as ForwardRefRenderFunction<Element, AvatarStackProps<ElementType>>,
+  'AvatarStack'
+)

package/src/components/avatar/index.ts

@@ -0,0 +1,6 @@
+export { Avatar } from './Avatar'
+export type { AvatarProps } from './Avatar'
+export { AvatarImage } from './AvatarImage'
+export type { AvatarImageProps } from './AvatarImage'
+export { AvatarStack } from './AvatarStack'
+export type { AvatarStackProps, AvatarStackItemDef } from './AvatarStack'

package/src/components/badge/Badge.tsx

@@ -0,0 +1,94 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import { ContextColor, ContextStyle, Sizing } from '../../types'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+
+type BadgeOwnProps<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
+  /**
+   * Sets the context style of the component. `solid`/`basic` render the default look with no extra class.
+   */
+  variant?: ContextStyle
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C
+  /**
+   * Position badge in one of the corners of a link or button.
+   */
+  position?: 'top-start' | 'top-end' | 'bottom-end' | 'bottom-start'
+  /**
+   * Select the shape of the component.
+   */
+  circle?: boolean
+  /**
+   * Sets the size of the component to one of Chassis component sizes.
+   */
+  size?: Sizing
+}
+
+export type BadgeProps<C extends ElementType = 'span'> = PolymorphicComponentProps<
+  C,
+  BadgeOwnProps<C>
+>
+
+type BadgeComponent = (<C extends ElementType = 'span'>(
+  props: BadgeProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function BadgeRender<C extends ElementType = 'span'>(
+  {
+    children,
+    className,
+    color,
+    variant,
+    component,
+    position,
+    circle,
+    size,
+    ...rest
+  }: BadgeProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'span'
+
+  const _className = classNames(
+    'badge',
+    color,
+    size,
+    {
+      outline: variant === 'outline',
+      smooth: variant === 'smooth',
+      'position-absolute translate-middle': position,
+      'top-0': position?.includes('top'),
+      'top-100': position?.includes('bottom'),
+      'start-100': position?.includes('end'),
+      'start-0': position?.includes('start')
+    },
+    { circle },
+    className
+  )
+
+  return (
+    <Component className={_className} {...rest} ref={ref}>
+      {children}
+    </Component>
+  )
+}
+
+export const Badge = createPolymorphicComponent<BadgeComponent>(
+  BadgeRender as ForwardRefRenderFunction<Element, BadgeProps<ElementType>>,
+  'Badge'
+)

package/src/components/badge/index.ts

@@ -0,0 +1,2 @@
+export { Badge } from './Badge'
+export type { BadgeProps } from './Badge'

package/src/components/breadcrumb/Breadcrumb.tsx

@@ -0,0 +1,59 @@
+import React, { forwardRef, HTMLAttributes } from 'react'
+import classNames from 'classnames'
+
+import { BreadcrumbItem } from './BreadcrumbItem'
+
+export interface BreadcrumbItemDef {
+  /**
+   * Label for the breadcrumb item.
+   */
+  label: React.ReactNode
+  /**
+   * URL for the breadcrumb link. The last item in the array is always rendered as active (no link needed).
+   */
+  href?: string
+}
+
+export interface BreadcrumbProps extends HTMLAttributes<HTMLOListElement> {
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Array of breadcrumb items for data-driven rendering. The last item is automatically marked active.
+   * When provided, children are ignored.
+   */
+  items?: BreadcrumbItemDef[]
+}
+
+export const Breadcrumb = forwardRef<HTMLOListElement, BreadcrumbProps>(
+  ({ children, className, items, ...rest }, ref) => {
+    const _className = classNames('breadcrumb', className)
+
+    const autoContent = items
+      ? items.map((item, idx) => {
+          const isLast = idx === items.length - 1
+          return (
+            <BreadcrumbItem
+              // eslint-disable-next-line react/no-array-index-key
+              key={idx}
+              active={isLast}
+              href={isLast ? undefined : item.href}
+            >
+              {item.label}
+            </BreadcrumbItem>
+          )
+        })
+      : null
+
+    return (
+      <nav aria-label="breadcrumb">
+        <ol className={_className} {...rest} ref={ref}>
+          {autoContent ?? children}
+        </ol>
+      </nav>
+    )
+  }
+)
+
+Breadcrumb.displayName = 'Breadcrumb'

package/src/components/breadcrumb/BreadcrumbItem.tsx

@@ -0,0 +1,38 @@
+import React, { forwardRef, HTMLAttributes } from 'react'
+import classNames from 'classnames'
+
+import { Link } from '../link/Link'
+
+export interface BreadcrumbItemProps extends HTMLAttributes<HTMLLIElement> {
+  /**
+   * Toggle the active state for the component.
+   */
+  active?: boolean
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * The `href` attribute for the inner `<Link>` component.
+   */
+  href?: string
+}
+
+export const BreadcrumbItem = forwardRef<HTMLLIElement, BreadcrumbItemProps>(
+  ({ children, active, className, href, ...rest }, ref) => {
+    const _className = classNames(
+      'breadcrumb-item',
+      {
+        active: active
+      },
+      className
+    )
+    return (
+      <li className={_className} {...(active && { 'aria-current': 'page' })} {...rest} ref={ref}>
+        {href ? <Link href={href}>{children}</Link> : children}
+      </li>
+    )
+  }
+)
+
+BreadcrumbItem.displayName = 'BreadcrumbItem'

package/src/components/breadcrumb/index.ts

@@ -0,0 +1,4 @@
+export { Breadcrumb } from './Breadcrumb'
+export type { BreadcrumbProps, BreadcrumbItemDef } from './Breadcrumb'
+export { BreadcrumbItem } from './BreadcrumbItem'
+export type { BreadcrumbItemProps } from './BreadcrumbItem'

package/src/components/button/Button.tsx

@@ -0,0 +1,229 @@
+import React, {
+  ElementType,
+  ForwardRefRenderFunction,
+  MouseEventHandler,
+  ReactElement,
+  Ref
+} from 'react'
+import classNames from 'classnames'
+import { mergeProps } from 'react-aria'
+
+import { ContextColor, ContextStyle, Shapes } from '../../types'
+import { useButtonSemantics, useDisabledAnchorGuard } from '../../hooks'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+
+type ButtonOwnProps<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.
+   */
+  color?: ContextColor
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C
+  /**
+   * Toggle the disabled state for the component.
+   */
+  disabled?: boolean
+  /**
+   * The href attribute specifies the URL of the page the link goes to.
+   */
+  href?: string
+  /**
+   * Fires on click. Typed for every element `component` can actually render (`button`, `a`,
+   * `input`, or a custom component), rather than narrowed to `HTMLButtonElement` alone.
+   */
+  onClick?: MouseEventHandler<HTMLButtonElement | HTMLAnchorElement | HTMLInputElement>
+  /**
+   * Marks the button as pressed for toggle-style usage (e.g. a formatting toolbar button).
+   * Applies the `.active` class and sets `aria-pressed` so assistive technology announces
+   * "button, pressed" rather than treating the button as a navigation link.
+   */
+  pressed?: boolean
+  /**
+   * Select the shape of the component.
+   */
+  shape?: Shapes
+  /**
+   * 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 button style variant. Same as `ContextStyle`, but `solid` (the unmodified default
+   * look) doesn't apply as a class, and `link` — button-specific, not a context color — makes
+   * the button look and behave like a hyperlink while keeping its `color`.
+   */
+  variant?: Exclude<ContextStyle, 'solid'> | 'link'
+}
+
+export type ButtonProps<C extends ElementType = 'button'> = PolymorphicComponentProps<
+  C,
+  ButtonOwnProps<C>
+>
+
+type ButtonComponent = (<C extends ElementType = 'button'>(
+  props: ButtonProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function ButtonRender<C extends ElementType = 'button'>(
+  {
+    children,
+    className,
+    color = 'primary',
+    component,
+    disabled,
+    href,
+    onClick,
+    pressed,
+    shape,
+    size,
+    type = 'button',
+    variant,
+    ...rest
+  }: ButtonProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  // Only defaults to `a` when `component` wasn't explicitly passed — an explicit `component`
+  // (even alongside `href`, e.g. a router Link component that accepts `href` itself) always wins.
+  const Component = (component ?? (href ? 'a' : 'button')) as ElementType
+  const isAnchor = Component === 'a'
+
+  // A component reference (e.g. a router `Link`) has its own visual identity and is trusted to
+  // handle its own keyboard/role semantics, same as `CloseButton`'s `isComponentReference` escape
+  // hatch — synthesizing `role="button"` and Enter/Space handling on top of it would stamp the
+  // wrong ARIA role onto whatever it actually renders (e.g. an `<a>`) and can double-fire a click
+  // (native anchor Enter→click, plus the synthesized keydown→click). Only a bare, non-native HTML
+  // tag string (e.g. `'div'`) still needs `useButtonSemantics`'s synthesis.
+  const isComponentReference = typeof Component !== 'string'
+
+  const _className = classNames(
+    'button',
+    color,
+    {
+      outline: variant === 'outline',
+      smooth: variant === 'smooth',
+      link: variant === 'link',
+      active: pressed,
+      disabled: Component !== 'button' && disabled
+    },
+    size,
+    shape,
+    className
+  )
+
+  // `<a>` has no real `disabled` attribute, so a disabled link button still fires click
+  // (and still navigates) unless it's blocked here. Native `button`/`input` already stop
+  // clicks on their own once the `disabled` attribute below is set.
+  const handleClick = useDisabledAnchorGuard<
+    HTMLButtonElement | HTMLAnchorElement | HTMLInputElement
+  >(isAnchor, disabled, onClick)
+
+  // Native `button`/`a`/`input` elements get keyboard activation, focus and disabled
+  // handling for free from the browser. A custom `component` doesn't, so useButtonSemantics
+  // fills in role, tabIndex and Enter/Space activation for it, matching native button behavior.
+  // `ref` is cast for the same reason as the branches below — it's declared for whatever `C`
+  // was passed, but this path (a non-native `component`) only ever populates it with a
+  // button/anchor-shaped instance.
+  const { buttonProps, forkedRef } = useButtonSemantics<HTMLButtonElement | HTMLAnchorElement>(
+    ref as Ref<HTMLButtonElement | HTMLAnchorElement>,
+    { disabled, onClick }
+  )
+
+  // Rendered as three separate, literal JSX tags (rather than one `<Component>` tag driven
+  // by a `'button' | 'a' | 'input'`-typed variable) because a union-typed tag makes JSX
+  // intersect all three elements' prop types — `onClick`/`ref` would then need to satisfy
+  // `button`, `a` *and* `input` simultaneously, which `handleClick`/`ref`'s real, narrower
+  // types can't. `ref` is cast per branch since it's declared for the generic `C`, not the
+  // specific element each branch actually renders (true by construction — each branch's ref
+  // only ever populates with a matching instance). The props common to all three
+  // (className/aria-pressed/onClick) are factored out here so a future addition only needs to
+  // change one place, not three.
+  const sharedProps = {
+    className: _className,
+    'aria-pressed': pressed,
+    onClick: handleClick
+  }
+
+  if (Component === 'button') {
+    return (
+      <button
+        {...(rest as Record<string, unknown>)}
+        {...sharedProps}
+        type={type}
+        disabled={disabled}
+        ref={ref as Ref<HTMLButtonElement>}
+      >
+        {children}
+      </button>
+    )
+  }
+
+  if (Component === 'input') {
+    return (
+      // `rest` is cast because it's typed generically, whose event handlers don't structurally
+      // match `<input>`'s own `onChange` (value-change semantics) — `component="input"` is a
+      // fixed set of documented attributes (`type`, `value`, `disabled`, ...), not a
+      // general-purpose input, so this is a safe, deliberate escape.
+      <input
+        {...(rest as Record<string, unknown>)}
+        {...sharedProps}
+        type={type}
+        disabled={disabled}
+        ref={ref as Ref<HTMLInputElement>}
+      />
+    )
+  }
+
+  if (isAnchor) {
+    return (
+      // `rest` is cast for the same reason as the `input` branch above — it's typed generically,
+      // whose DOM event handlers are parameterized for whatever `C` was passed, which don't
+      // structurally match `<a>`'s own `HTMLAnchorElement` ones (e.g. `onCopy`), even though both
+      // accept a real DOM event at runtime.
+      <a
+        {...(rest as Record<string, unknown>)}
+        {...sharedProps}
+        href={href}
+        {...(disabled && { 'aria-disabled': true, tabIndex: -1 })}
+        ref={ref as Ref<HTMLAnchorElement>}
+      >
+        {children}
+      </a>
+    )
+  }
+
+  return (
+    <Component
+      {...(isComponentReference
+        ? ({ disabled, onClick, ...rest } as Record<string, unknown>)
+        : (mergeProps(rest, buttonProps) as Record<string, unknown>))}
+      className={_className}
+      aria-pressed={pressed}
+      // `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={isComponentReference ? ref : forkedRef}
+    >
+      {children}
+    </Component>
+  )
+}
+
+export const Button = createPolymorphicComponent<ButtonComponent>(
+  ButtonRender as ForwardRefRenderFunction<Element, ButtonProps<ElementType>>,
+  'Button'
+)

package/src/components/button/index.ts

@@ -0,0 +1,2 @@
+export { Button } from './Button'
+export type { ButtonProps } from './Button'