@chassis-ui/react 0.0.0-20260831090525

package/src/components/icon/Icon.tsx

@@ -0,0 +1,74 @@
+import React, { forwardRef, HTMLAttributes, SVGAttributes } from 'react'
+import classNames from 'classnames'
+
+interface IconOwnProps {
+  /**
+   * Icon name, e.g. `folder-tree`. Matches a `cx-{name}` font glyph class or an id in the SVG sprite.
+   */
+  name: string
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Width/height (in px) applied to the SVG. Ignored in `font` mode.
+   */
+  size?: number
+  /**
+   * Accessible name. When set, the icon is exposed to assistive tech instead of hidden.
+   */
+  title?: string
+  /**
+   * Path to the SVG sprite file. Ignored in `font` mode.
+   */
+  sprite?: string
+}
+
+export type IconProps =
+  | (IconOwnProps & { font: true } & Omit<HTMLAttributes<HTMLSpanElement>, keyof IconOwnProps>)
+  | (IconOwnProps & { font?: false } & Omit<SVGAttributes<SVGSVGElement>, keyof IconOwnProps>)
+
+export const Icon = forwardRef<HTMLSpanElement | SVGSVGElement, IconProps>(
+  (
+    { name, className, size = 24, title, sprite = '/static/icons/chassis-icons.svg', ...props },
+    ref
+  ) => {
+    const _className = classNames('icon', { [`cx-${name}`]: props.font }, className)
+
+    if (props.font) {
+      const { font: _, ...rest } = props
+      return (
+        <span
+          className={_className}
+          // A plain `<span>`'s implicit "generic" role doesn't support naming, so `aria-label`
+          // alone is dropped by browsers/assistive tech - `role="img"` (matching the SVG path's
+          // own implicit role) is what actually makes the accessible name stick.
+          role={title ? 'img' : undefined}
+          aria-hidden={title ? undefined : true}
+          aria-label={title}
+          ref={ref as React.Ref<HTMLSpanElement>}
+          {...rest}
+        />
+      )
+    }
+
+    const { font: _, ...rest } = props
+
+    return (
+      <svg
+        className={_className}
+        width={size}
+        height={size}
+        role={title ? 'img' : undefined}
+        aria-hidden={title ? undefined : true}
+        ref={ref as React.Ref<SVGSVGElement>}
+        {...rest}
+      >
+        {title && <title>{title}</title>}
+        <use href={`${sprite}#${name}`} />
+      </svg>
+    )
+  }
+)
+
+Icon.displayName = 'Icon'

package/src/components/icon/index.ts

@@ -0,0 +1,2 @@
+export { Icon } from './Icon'
+export type { IconProps } from './Icon'

package/src/components/input-adorn/InputAdorn.tsx

@@ -0,0 +1,55 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+
+type InputAdornOwnProps<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. Use
+   * `"button"` or `"a"` for an actionable adorn, e.g. a password reveal toggle or a clear button.
+   */
+  component?: C
+}
+
+export type InputAdornProps<C extends ElementType = 'span'> = PolymorphicComponentProps<
+  C,
+  InputAdornOwnProps<C>
+>
+
+type InputAdornComponent = (<C extends ElementType = 'span'>(
+  props: InputAdornProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function InputAdornRender<C extends ElementType = 'span'>(
+  { children, className, component, onMouseDown, ...rest }: InputAdornProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'span'
+  const _className = classNames('input-adorn', className)
+  const handleMouseDown: React.MouseEventHandler<Element> = (event) => {
+    onMouseDown?.(event)
+    // Keep focus on the associated input (e.g. a password toggle) instead of
+    // letting the browser shift it to this button/anchor on mousedown.
+    if (!event.defaultPrevented) {
+      event.preventDefault()
+    }
+  }
+  return (
+    <Component className={_className} onMouseDown={handleMouseDown} {...rest} ref={ref}>
+      {children}
+    </Component>
+  )
+}
+
+export const InputAdorn = createPolymorphicComponent<InputAdornComponent>(
+  InputAdornRender as ForwardRefRenderFunction<Element, InputAdornProps<ElementType>>,
+  'InputAdorn'
+)

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

@@ -0,0 +1,2 @@
+export { InputAdorn } from './InputAdorn'
+export type { InputAdornProps } from './InputAdorn'

package/src/components/input-group/InputGroup.tsx

@@ -0,0 +1,50 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+
+type InputGroupOwnProps<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
+  /**
+   * Size the component small or large.
+   */
+  size?: 'small' | 'large'
+}
+
+export type InputGroupProps<C extends ElementType = 'div'> = PolymorphicComponentProps<
+  C,
+  InputGroupOwnProps<C>
+>
+
+type InputGroupComponent = (<C extends ElementType = 'div'>(
+  props: InputGroupProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function InputGroupRender<C extends ElementType = 'div'>(
+  { children, className, component, size, ...rest }: InputGroupProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'div'
+  const _className = classNames('input-group', size, className)
+  return (
+    <Component className={_className} {...rest} ref={ref}>
+      {children}
+    </Component>
+  )
+}
+
+export const InputGroup = createPolymorphicComponent<InputGroupComponent>(
+  InputGroupRender as ForwardRefRenderFunction<Element, InputGroupProps<ElementType>>,
+  'InputGroup'
+)

package/src/components/input-group/InputGroupAddon.tsx

@@ -0,0 +1,50 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+
+type InputGroupAddonOwnProps<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
+  /**
+   * The id of the form control this addon labels, when rendered as `component="label"`.
+   */
+  htmlFor?: string
+}
+
+export type InputGroupAddonProps<C extends ElementType = 'span'> = PolymorphicComponentProps<
+  C,
+  InputGroupAddonOwnProps<C>
+>
+
+type InputGroupAddonComponent = (<C extends ElementType = 'span'>(
+  props: InputGroupAddonProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function InputGroupAddonRender<C extends ElementType = 'span'>(
+  { children, className, component, ...rest }: InputGroupAddonProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'span'
+  const _className = classNames('input-addon', className)
+  return (
+    <Component className={_className} {...rest} ref={ref}>
+      {children}
+    </Component>
+  )
+}
+
+export const InputGroupAddon = createPolymorphicComponent<InputGroupAddonComponent>(
+  InputGroupAddonRender as ForwardRefRenderFunction<Element, InputGroupAddonProps<ElementType>>,
+  'InputGroupAddon'
+)

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

@@ -0,0 +1,4 @@
+export { InputGroup } from './InputGroup'
+export type { InputGroupProps } from './InputGroup'
+export { InputGroupAddon } from './InputGroupAddon'
+export type { InputGroupAddonProps } from './InputGroupAddon'

package/src/components/link/Link.tsx

@@ -0,0 +1,148 @@
+import React, {
+  ElementType,
+  ForwardRefRenderFunction,
+  MouseEventHandler,
+  ReactElement,
+  Ref
+} from 'react'
+import classNames from 'classnames'
+import { mergeProps } from 'react-aria'
+
+import { ContextColor } from '../../types'
+import { useButtonSemantics, useDisabledAnchorGuard } from '../../hooks'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+
+type LinkOwnProps<C extends ElementType> = {
+  /**
+   * Toggle the active state for the component.
+   */
+  active?: boolean
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Sets the link color to one of Chassis context colors, including its interactive
+   * (`:hover`/`:focus`/`:active`/`:visited`) states.
+   */
+  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. Only meaningful when
+   * `component` resolves to (or accepts) `'a'`. Declared explicitly here — rather than left to
+   * flow through generically from whatever `C` is — so consumers that wrap `Link` (`MenuItem`,
+   * `ListItem`, `NavLink`) can read it with a concrete type regardless of `component`.
+   */
+  href?: string
+  /**
+   * Fires on click.
+   */
+  onClick?: MouseEventHandler<HTMLElement>
+  /**
+   * Aligns a leading or trailing icon with the link text using flexbox, with a gap between
+   * them and an offset underline. Icons need to be passed as `children` alongside the text.
+   * Named `iconLink` rather than `icon` to avoid colliding with components (e.g. `MenuItem`)
+   * that already have their own, differently-typed `icon` prop for the icon content itself.
+   */
+  iconLink?: boolean
+  /**
+   * Removes the foreground color override, so the link inherits its color from the nearest
+   * ancestor instead of the default link color.
+   */
+  reset?: boolean
+  /**
+   * Expands the link's click target to fill its positioned ancestor (the nearest ancestor with
+   * a `position` other than `static`).
+   */
+  stretched?: boolean
+  /**
+   * Specifies the type of button. Only applies when `component="button"`. Different browsers may
+   * use different default types for the `<button>` element, so always specify it explicitly.
+   */
+  type?: 'button' | 'submit' | 'reset'
+}
+
+export type LinkProps<C extends ElementType = 'a'> = PolymorphicComponentProps<C, LinkOwnProps<C>>
+
+type LinkComponent = (<C extends ElementType = 'a'>(
+  props: LinkProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function LinkRender<C extends ElementType = 'a'>(
+  {
+    children,
+    active,
+    className,
+    color,
+    component,
+    disabled,
+    iconLink,
+    onClick,
+    reset,
+    stretched,
+    type = 'button',
+    ...rest
+  }: LinkProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = (component ?? 'a') as ElementType
+
+  const _className = classNames(
+    color && `link-${color}`,
+    { 'icon-link': iconLink, 'fg-reset': reset, 'stretched-link': stretched },
+    { active, disabled },
+    className
+  )
+
+  const isInteractive = Component === 'a' || Component === 'button'
+  // 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).
+  const isComponentReference = typeof Component !== 'string'
+  // `<a>` has no real `disabled` attribute, so a disabled anchor link still fires click (and
+  // still navigates) unless it's blocked here, same guard `Button`/`CloseButton` apply. A real
+  // `<button>` already stops clicks on its own once the `disabled` attribute below is set.
+  const handleClick = useDisabledAnchorGuard<HTMLElement>(Component === 'a', disabled, onClick)
+
+  // A `component` that isn't a native interactive element gets a raw onClick with no
+  // keyboard semantics otherwise — mouse-only, unlike `Button`/`CloseButton`, which
+  // synthesize this via `useButtonSemantics` for exactly this "arbitrary component" case. A
+  // component reference is excluded (see `isComponentReference` above).
+  const needsButtonSemantics = !isInteractive && !isComponentReference && !!onClick
+  const { buttonProps, forkedRef } = useButtonSemantics<HTMLElement>(ref as Ref<HTMLElement>, {
+    disabled,
+    onClick
+  })
+
+  return (
+    <Component
+      {...(mergeProps(rest, needsButtonSemantics ? buttonProps : {}) as Record<string, unknown>)}
+      className={_className}
+      {...(active && { 'aria-current': 'page' })}
+      {...(Component === 'a' && disabled && { 'aria-disabled': true, tabIndex: -1 })}
+      {...(!needsButtonSemantics && { onClick: handleClick })}
+      {...(Component === 'button' && { disabled, type })}
+      ref={needsButtonSemantics ? forkedRef : ref}
+    >
+      {children}
+    </Component>
+  )
+}
+
+export const Link = createPolymorphicComponent<LinkComponent>(
+  LinkRender as ForwardRefRenderFunction<Element, LinkProps<ElementType>>,
+  'Link'
+)

package/src/components/link/index.ts

@@ -0,0 +1,2 @@
+export { Link } from './Link'
+export type { LinkProps } from './Link'

package/src/components/list/List.tsx

@@ -0,0 +1,193 @@
+import React, {
+  Children,
+  ElementType,
+  ForwardRefRenderFunction,
+  isValidElement,
+  ReactElement
+} from 'react'
+import classNames from 'classnames'
+
+import { ContextColor, ContextStyle } from '../../types'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+import { ListItem } from './ListItem'
+
+export interface ListItemDef {
+  /**
+   * Stable key for the rendered item. Falls back to the item's index in `items`.
+   */
+  id?: number | string
+  /**
+   * Item label content.
+   */
+  label: React.ReactNode
+  /**
+   * Makes the item a link.
+   */
+  href?: string
+  /**
+   * Sets the color of the item.
+   */
+  color?: ContextColor
+  /**
+   * Marks the item as active.
+   */
+  active?: boolean
+  /**
+   * Marks the item as disabled.
+   */
+  disabled?: boolean
+}
+
+type ListOwnProps<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.
+   * Defaults to `'ul'`, unless an item (a data-driven item with `href`, or a `<ListItem
+   * component="a">`/`<ListItem component="button">` child) is interactive — a bare `<a>`/
+   * `<button>` isn't a valid direct child of `<ul>`/`<ol>`, so the default switches to `'div'`
+   * instead. Pass `component` explicitly to opt out of this.
+   */
+  component?: C
+  /**
+   * Sets the color of the component to one of Chassis context colors.
+   */
+  color?: ContextColor
+  /**
+   * Remove outer borders and rounded corners to render list items edge-to-edge in a parent component (e.g., `<Card>`).
+   */
+  flush?: boolean
+  /**
+   * Array of item definitions for data-driven rendering. When provided, children are ignored.
+   */
+  items?: ListItemDef[]
+  /**
+   * Specify a layout type.
+   */
+  layout?:
+    | 'horizontal'
+    | 'small:horizontal'
+    | 'medium:horizontal'
+    | 'large:horizontal'
+    | 'xlarge:horizontal'
+    | '2xlarge:horizontal'
+  /**
+   * Number list items sequentially using CSS counters. Pair with `component="ol"` for semantic correctness.
+   */
+  numbered?: boolean
+  /**
+   * Remove outer borders, rounded corners, and horizontal padding for a minimal, edge-to-edge appearance.
+   */
+  plain?: boolean
+  /**
+   * Applies a `.solid`, `.outline`, or `.smooth` context style. Only meaningful together with `color`.
+   */
+  variant?: ContextStyle
+}
+
+export type ListProps<C extends ElementType = 'ul'> = PolymorphicComponentProps<C, ListOwnProps<C>>
+
+type ListComponent = (<C extends ElementType = 'ul'>(
+  props: ListProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function ListRender<C extends ElementType = 'ul'>(
+  {
+    children,
+    className,
+    component,
+    color,
+    variant,
+    flush,
+    items,
+    layout,
+    numbered,
+    plain,
+    ...rest
+  }: ListProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  // A linked item (data-driven `href`, or a `<ListItem component="a"|"button">` child) can't
+  // render as a bare `<a>`/`<button>` inside the default `<ul>`/`<ol>` root — only `<li>`/
+  // `script`/`template` are valid children there. Default to `<div>` instead when that's the
+  // case (unless the caller already chose their own `component`), matching the same
+  // `component="div"` pattern already documented for `Stepper`'s composed interactive usage.
+  const hasInteractiveItem = items
+    ? items.some((item) => !!item.href)
+    : Children.toArray(children).some(
+        (child) =>
+          isValidElement<{ component?: string | ElementType }>(child) &&
+          child.type === ListItem &&
+          (child.props.component === 'a' || child.props.component === 'button')
+      )
+  const Component = (component ?? (hasInteractiveItem ? 'div' : 'ul')) as ElementType
+  const isListSemantic = Component === 'ul' || Component === 'ol'
+
+  const _className = classNames(
+    'list',
+    color && 'context',
+    color,
+    variant,
+    layout,
+    {
+      flush,
+      plain,
+      numbered
+    },
+    className
+  )
+
+  const autoContent = items
+    ? items.map((item, idx) => {
+        const itemClass = classNames('list-item', item.color && 'context', item.color, {
+          'list-action': !!item.href,
+          active: item.active,
+          disabled: item.disabled
+        })
+        const Tag = item.href ? 'a' : isListSemantic ? 'li' : 'div'
+        return (
+          <Tag
+            key={item.id ?? idx}
+            className={itemClass}
+            {...(item.href ? { href: item.href } : {})}
+            {...(item.active ? { 'aria-current': 'page' } : {})}
+            {...(item.disabled ? { 'aria-disabled': true } : {})}
+          >
+            {item.label}
+          </Tag>
+        )
+      })
+    : null
+
+  // When the root switched to `div` because of an interactive child, every plain `<ListItem>`
+  // sibling defaulting to `<li>` would be just as invalid (only valid inside `<ul>`/`<ol>`/
+  // `<menu>`) — so give each `ListItem` child the same `div` treatment the auto-generated items
+  // above already get, unless it set its own `component`. Other child types are left untouched
+  // — this is only meaningful for `List`'s own list items.
+  const renderedChildren =
+    autoContent ??
+    (isListSemantic
+      ? children
+      : Children.map(children, (child) =>
+          isValidElement<{ component?: string | ElementType }>(child) && child.type === ListItem
+            ? React.cloneElement(child, { component: child.props.component ?? 'div' })
+            : child
+        ))
+
+  return (
+    <Component className={_className} {...rest} ref={ref}>
+      {renderedChildren}
+    </Component>
+  )
+}
+
+export const List = createPolymorphicComponent<ListComponent>(
+  ListRender as ForwardRefRenderFunction<Element, ListProps<ElementType>>,
+  'List'
+)

package/src/components/list/ListItem.tsx

@@ -0,0 +1,91 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import { ContextColor } from '../../types'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+import { Link } from '../link/Link'
+
+type ListItemOwnProps<C extends ElementType> = {
+  /**
+   * Toggle the active state for the component.
+   */
+  active?: boolean
+  /**
+   * 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.
+   */
+  disabled?: boolean
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C
+  /**
+   * The href attribute specifies the URL of the page the link goes to. Only applicable when
+   * `component` is `"a"`.
+   */
+  href?: string
+}
+
+export type ListItemProps<C extends ElementType = 'li'> = PolymorphicComponentProps<
+  C,
+  ListItemOwnProps<C>
+>
+
+type ListItemComponent = (<C extends ElementType = 'li'>(
+  props: ListItemProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function ListItemRender<C extends ElementType = 'li'>(
+  { children, active, className, disabled, color, component, ...rest }: ListItemProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const tag = component ?? 'li'
+  const isInteractive = tag === 'a' || tag === 'button'
+
+  const _className = classNames(
+    'list-item',
+    color && 'context',
+    color,
+    {
+      'list-action': isInteractive,
+      active,
+      disabled
+    },
+    className
+  )
+
+  const Component = (isInteractive ? Link : tag) as ElementType
+
+  const finalRest = {
+    ...(isInteractive && {
+      active,
+      disabled,
+      component: tag
+    }),
+    ...(active && { 'aria-current': 'page' }),
+    ...(disabled && { 'aria-disabled': true }),
+    ...rest
+  }
+
+  return (
+    <Component className={_className} {...finalRest} ref={ref}>
+      {children}
+    </Component>
+  )
+}
+
+export const ListItem = createPolymorphicComponent<ListItemComponent>(
+  ListItemRender as ForwardRefRenderFunction<Element, ListItemProps<ElementType>>,
+  'ListItem'
+)

package/src/components/list/index.ts

@@ -0,0 +1,4 @@
+export { List } from './List'
+export type { ListProps, ListItemDef } from './List'
+export { ListItem } from './ListItem'
+export type { ListItemProps } from './ListItem'