@chassis-ui/react 0.0.0-20260831090525

package/src/components/form/renderFormCheck.tsx

@@ -0,0 +1,86 @@
+import React, { ReactNode } from 'react'
+import classNames from 'classnames'
+
+import { ContextColor, Shapes } from '../../types'
+import { validationClassName } from '../../utils/validationClassName'
+
+import { FormLabel } from './FormLabel'
+
+export type ButtonObject = {
+  /**
+   * Sets the color of the component to one of Chassis context colors.
+   */
+  color?: ContextColor
+  /**
+   * Select the shape of the component.
+   */
+  shape?: Shapes
+  /**
+   * Size the component small or large.
+   */
+  size?: 'small' | 'large'
+  /**
+   * Set the button variant to an outlined button or a ghost button.
+   */
+  variant?: 'outline' | 'ghost'
+}
+
+export interface RenderFormCheckOptions {
+  button?: ButtonObject
+  className?: string
+  color?: ContextColor
+  input: ReactNode
+  invalid?: boolean
+  label?: ReactNode
+  size?: 'small' | 'large'
+  valid?: boolean
+}
+
+// Shared nested, modern `.form-check`/`.check-input` markup for Checkbox and Radio —
+// see https://chassis-ui.com/css/docs/forms/checkbox-radio/#modern-inputs. Everything renders
+// nested inside a single <label> (or a bare <span class="check-input"> when there's no label);
+// there is no sibling/`for`-linked layout.
+export const renderFormCheck = ({
+  button,
+  className,
+  color,
+  input,
+  invalid,
+  label,
+  size,
+  valid
+}: RenderFormCheckOptions) => {
+  if (button) {
+    const _className = classNames(
+      'button',
+      'button-check',
+      button.color,
+      button.variant,
+      button.size,
+      button.shape,
+      validationClassName(invalid, valid),
+      className
+    )
+    return (
+      <FormLabel customClassName={_className}>
+        {input}
+        {label}
+      </FormLabel>
+    )
+  }
+
+  const checkInputClassName = classNames('check-input', color, validationClassName(invalid, valid))
+
+  if (!label) {
+    return <span className={checkInputClassName}>{input}</span>
+  }
+
+  const _className = classNames('form-check', size, validationClassName(invalid, valid), className)
+
+  return (
+    <FormLabel customClassName={_className}>
+      <span className={checkInputClassName}>{input}</span>
+      {label}
+    </FormLabel>
+  )
+}

package/src/components/form-field/FormField.tsx

@@ -0,0 +1,84 @@
+import { ReactNode } from 'react'
+
+import { FormFieldIds, renderFormField } from './renderFormField'
+
+export interface FormFieldProps {
+  /**
+   * The form control(s) this field wraps.
+   */
+  children: ReactNode
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * A description for the field, rendered below the control(s).
+   */
+  help?: ReactNode
+  /**
+   * The DOM ids of the wrapped control(s), used to associate the label (`htmlFor`) and
+   * point your control's own `aria-describedby` at the rendered help/feedback text.
+   */
+  ids?: FormFieldIds
+  /**
+   * Set field validation state to invalid.
+   */
+  invalid?: boolean
+  /**
+   * An error message for the field, rendered below the control(s) when `invalid` is set.
+   */
+  invalidFeedback?: ReactNode
+  /**
+   * The field's caption, rendered as a `FormLabel` associated with `ids.input`.
+   */
+  label?: ReactNode
+  /**
+   * Set field validation state to valid.
+   */
+  valid?: boolean
+  /**
+   * A success message for the field, rendered below the control(s) when `valid` is set.
+   */
+  validFeedback?: ReactNode
+}
+
+// Standalone `.form-field` wrapper for the "wrap this yourself" case: a control with no field
+// props of its own, or grouping more than one element under one label (e.g. an input plus a
+// sibling status meter). Combobox/DatePicker/ChipInput/OtpInput do NOT use this — they
+// call `renderFormField` directly and expose label/help/validFeedback/invalidFeedback as their
+// own props (see FORMS.md). Wrapping any of those 10 components in `FormField` produces a
+// nested, empty `.form-field` div — see FORMS.md's Gotchas section.
+export const FormField = ({
+  children,
+  className,
+  help,
+  ids,
+  invalid,
+  invalidFeedback,
+  label,
+  valid,
+  validFeedback
+}: FormFieldProps): ReactNode => {
+  if (label && !ids?.input && !ids?.label) {
+    console.warn(
+      'FormField: `label` is set but `ids.input`/`ids.label` are not — the rendered label ' +
+        "won't be associated with your control (no `htmlFor`, no `aria-labelledby` target). " +
+        'Pass `ids={{ input: yourControlId }}` (or `ids.label` for a group with no single ' +
+        'input) so the label has something to point at.'
+    )
+  }
+
+  return renderFormField({
+    children,
+    className,
+    help,
+    ids,
+    invalid,
+    invalidFeedback,
+    label,
+    valid,
+    validFeedback
+  })
+}
+
+FormField.displayName = 'FormField'

package/src/components/form-field/index.ts

@@ -0,0 +1,2 @@
+export { FormField } from './FormField'
+export type { FormFieldProps } from './FormField'

package/src/components/form-field/renderFormField.tsx

@@ -0,0 +1,74 @@
+import React, { ReactNode } from 'react'
+import classNames from 'classnames'
+
+import { FormFeedback } from '../form/FormFeedback'
+import { FormHelp } from '../form/FormHelp'
+import { FormLabel } from '../form/FormLabel'
+
+export interface FormFieldIds {
+  feedback?: string
+  help?: string
+  input?: string
+  /**
+   * The label's own id, for controls with no single input to associate via `htmlFor` (e.g. a
+   * multi-input group) — reference it from the control's own `aria-labelledby` instead.
+   */
+  label?: string
+}
+
+export interface RenderFormFieldOptions {
+  children: ReactNode
+  className?: string
+  help?: ReactNode
+  ids?: FormFieldIds
+  invalid?: boolean
+  invalidFeedback?: ReactNode
+  label?: ReactNode
+  valid?: boolean
+  validFeedback?: ReactNode
+}
+
+// Shared `.form-field` grid wrapper for label/control/help/feedback — see
+// https://chassis-ui.com/css/docs/forms/form-field. Renders `children` bare when none of
+// label/help/validFeedback/invalidFeedback are set, so field-capable leaves stay drop-in
+// compatible until a consumer opts into the wrapping.
+export const renderFormField = ({
+  children,
+  className,
+  help,
+  ids = {},
+  invalid,
+  invalidFeedback,
+  label,
+  valid,
+  validFeedback
+}: RenderFormFieldOptions): ReactNode => {
+  const showInvalidFeedback = invalid && invalidFeedback
+  const showValidFeedback = valid && validFeedback
+
+  if (!label && !help && !showInvalidFeedback && !showValidFeedback) {
+    return children
+  }
+
+  return (
+    <div className={classNames('form-field', className)}>
+      {label && (
+        <FormLabel htmlFor={ids.input} id={ids.label}>
+          {label}
+        </FormLabel>
+      )}
+      {children}
+      {help && <FormHelp id={ids.help}>{help}</FormHelp>}
+      {showInvalidFeedback && (
+        <FormFeedback id={ids.feedback} invalid>
+          {invalidFeedback}
+        </FormFeedback>
+      )}
+      {showValidFeedback && (
+        <FormFeedback id={ids.feedback} valid>
+          {validFeedback}
+        </FormFeedback>
+      )}
+    </div>
+  )
+}

package/src/components/grid/Col.tsx

@@ -0,0 +1,69 @@
+import React, { forwardRef, HTMLAttributes } from 'react'
+import classNames from 'classnames'
+
+import { Span, buildResponsiveClassNames } from '../../utils/breakpoints'
+import { Breakpoint } from '../../types'
+
+export interface ColLayout {
+  /**
+   * Columns (of 12) this Col spans, or `'auto'`/`true` for a natural-width column.
+   *
+   * @type { 'auto' | number | string | boolean }
+   */
+  span?: Span
+  /**
+   * Columns to offset the start of this Col by.
+   */
+  offset?: number | string
+  /**
+   * Visual order relative to sibling columns.
+   *
+   * @type { 'first' | 'last' | number | string }
+   */
+  order?: 'first' | 'last' | number | string
+}
+
+export interface ColProps extends HTMLAttributes<HTMLDivElement>, ColLayout {
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * Overrides `span`/`offset`/`order` at a breakpoint and up.
+   *
+   * @type { Partial<Record<'small' | 'medium' | 'large' | 'xlarge' | '2xlarge', { span?: 'auto' | number | string | boolean, offset?: number | string, order?: 'first' | 'last' | number | string }>> }
+   */
+  responsive?: Partial<Record<Breakpoint, ColLayout>>
+}
+
+const layoutClassNames = ({ span, offset, order }: ColLayout, prefix: string) => [
+  typeof span === 'number' || typeof span === 'string' ? `${prefix}col-${span}` : null,
+  span === true ? `${prefix}col` : null,
+  typeof offset === 'number' || typeof offset === 'string' ? `${prefix}offset-${offset}` : null,
+  typeof order === 'number' || typeof order === 'string' ? `${prefix}order-${order}` : null
+]
+
+export const Col = forwardRef<HTMLDivElement, ColProps>(
+  ({ children, className, span, offset, order, responsive, ...rest }, ref) => {
+    const layoutClassList = buildResponsiveClassNames(
+      layoutClassNames,
+      { span, offset, order },
+      responsive
+    )
+
+    // The base breakpoint only gets its equal-width flex sizing from an explicit `span` (base or
+    // `col`'s own class) or from the fallback bare `col` below — `offset`/`order` alone (or a
+    // `span` set only inside `responsive`) don't provide it, so without this the column would
+    // render at `flex: 0 1 auto` instead of a proper flexible column below the first tier that
+    // sets a span.
+    const _className = classNames(span === undefined && 'col', layoutClassList, className)
+
+    return (
+      <div className={_className} {...rest} ref={ref}>
+        {children}
+      </div>
+    )
+  }
+)
+
+Col.displayName = 'Col'

package/src/components/grid/Container.tsx

@@ -0,0 +1,59 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+import { Breakpoint } from '../../types'
+
+type ContainerOwnProps<C extends ElementType> = {
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C
+  /**
+   * Set container 100% wide until the given breakpoint, after which it scales up with `max-width`
+   * at every larger breakpoint.
+   *
+   * @type Breakpoint
+   */
+  fluidUntil?: Breakpoint
+  /**
+   * Set container 100% wide, spanning the entire width of the viewport.
+   */
+  fluid?: boolean
+}
+
+export type ContainerProps<C extends ElementType = 'div'> = PolymorphicComponentProps<
+  C,
+  ContainerOwnProps<C>
+>
+
+type ContainerComponent = (<C extends ElementType = 'div'>(
+  props: ContainerProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function ContainerRender<C extends ElementType = 'div'>(
+  { children, className, component, fluidUntil, fluid, ...rest }: ContainerProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'div'
+  const _className = classNames('container', fluid && 'fluid', fluidUntil, className)
+
+  return (
+    <Component className={_className} {...rest} ref={ref}>
+      {children}
+    </Component>
+  )
+}
+
+export const Container = createPolymorphicComponent<ContainerComponent>(
+  ContainerRender as ForwardRefRenderFunction<Element, ContainerProps<ElementType>>,
+  'Container'
+)

package/src/components/grid/Grid.tsx

@@ -0,0 +1,86 @@
+import React, { CSSProperties, ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+import { Spacing } from '../../types'
+import { resolveGap } from './gap'
+
+type GridStyle = CSSProperties & {
+  '--cx-grid-columns'?: number
+  '--cx-grid-rows'?: number
+  '--cx-grid-gap'?: string
+  '--cx-gap'?: string
+}
+
+type GridOwnProps<C extends ElementType> = {
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C
+  /**
+   * Number of columns in the grid template, set via the `--cx-grid-columns` custom property
+   * (defaults to `12` in CSS when omitted). Has no effect when `fill` is set.
+   */
+  columns?: number
+  /**
+   * Number of rows in the grid template, set via the `--cx-grid-rows` custom property (defaults
+   * to `1` in CSS when omitted). Has no effect when `fill` is set.
+   */
+  rows?: number
+  /**
+   * Gap between grid items, set via the `--cx-grid-gap` custom property (or `--cx-gap` when
+   * `fill` is set). Accepts a `Spacing` token (mapped to the matching `--cx-space-*` custom
+   * property) or any raw CSS `gap` value, including a `"{row} {column}"` pair.
+   *
+   * @type { Spacing | string }
+   */
+  gap?: Spacing | (string & {})
+  /**
+   * Renders `.grid-fill` instead of `.grid` — columns expand equally to fill the available
+   * width, with the column count determined by the number of children rather than `columns`.
+   */
+  fill?: boolean
+}
+
+export type GridProps<C extends ElementType = 'div'> = PolymorphicComponentProps<C, GridOwnProps<C>>
+
+type GridComponent = (<C extends ElementType = 'div'>(
+  props: GridProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function GridRender<C extends ElementType = 'div'>(
+  { children, className, component, columns, rows, gap, fill, style, ...rest }: GridProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'div'
+  const _className = classNames(fill ? 'grid-fill' : 'grid', className)
+
+  const _style: GridStyle = { ...style }
+
+  if (fill) {
+    if (gap !== undefined) _style['--cx-gap'] = resolveGap(gap)
+  } else {
+    if (columns !== undefined) _style['--cx-grid-columns'] = columns
+    if (rows !== undefined) _style['--cx-grid-rows'] = rows
+    if (gap !== undefined) _style['--cx-grid-gap'] = resolveGap(gap)
+  }
+
+  return (
+    <Component className={_className} style={_style} {...rest} ref={ref}>
+      {children}
+    </Component>
+  )
+}
+
+export const Grid = createPolymorphicComponent<GridComponent>(
+  GridRender as ForwardRefRenderFunction<Element, GridProps<ElementType>>,
+  'Grid'
+)

package/src/components/grid/GridItem.tsx

@@ -0,0 +1,123 @@
+import React, { CSSProperties, ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+import { buildResponsiveClassNames } from '../../utils/breakpoints'
+import { Breakpoint, Spacing } from '../../types'
+import { resolveGap } from './gap'
+
+type GridItemStyle = CSSProperties & {
+  '--cx-grid-rows'?: number
+  '--cx-grid-gap'?: string
+}
+
+export interface GridItemLayout {
+  /**
+   * Number of grid column tracks (of the parent `<Grid>`'s `columns`) this item spans, mapped to
+   * the `g-col-{n}` class.
+   */
+  span?: number
+  /**
+   * Grid column line to start this item at, mapped to the `g-start-{n}` class.
+   */
+  start?: number
+}
+
+type GridItemOwnProps<C extends ElementType> = GridItemLayout & {
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C
+  /**
+   * Overrides `span`/`start` at a breakpoint and up.
+   *
+   * @type { Partial<Record<'small' | 'medium' | 'large' | 'xlarge' | '2xlarge', { span?: number, start?: number }>> }
+   */
+  responsive?: Partial<Record<Breakpoint, GridItemLayout>>
+  /**
+   * Turns this item into a nested subgrid: adds `.grid`/`.grid-cols-subgrid` alongside its
+   * `g-col-{n}`/`g-start-{n}` placement classes, so its own children inherit the parent
+   * `<Grid>`'s column tracks instead of defining new ones. Combine with `span` — a subgrid
+   * item must itself be a grid item of the parent for `grid-template-columns: subgrid` to take
+   * effect, which is why `subgrid` lives on `<GridItem>` (the element actually placed as a grid
+   * item) rather than on a `<Grid>` nested inside it.
+   */
+  subgrid?: boolean
+  /**
+   * Number of rows in the subgrid's own row template, set via the `--cx-grid-rows` custom
+   * property (defaults to `1` in CSS when omitted). Only relevant when `subgrid` is set —
+   * subgrid only inherits the parent's column tracks, not its rows.
+   */
+  rows?: number
+  /**
+   * Gap between the subgrid's children, set via the `--cx-grid-gap` custom property. Only
+   * relevant when `subgrid` is set — a subgrid doesn't inherit its parent's gap.
+   *
+   * @type { Spacing | string }
+   */
+  gap?: Spacing | (string & {})
+}
+
+export type GridItemProps<C extends ElementType = 'div'> = PolymorphicComponentProps<
+  C,
+  GridItemOwnProps<C>
+>
+
+type GridItemComponent = (<C extends ElementType = 'div'>(
+  props: GridItemProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+const layoutClassNames = ({ span, start }: GridItemLayout, prefix: string) => [
+  typeof span === 'number' ? `${prefix}g-col-${span}` : null,
+  typeof start === 'number' ? `${prefix}g-start-${start}` : null
+]
+
+function GridItemRender<C extends ElementType = 'div'>(
+  {
+    children,
+    className,
+    component,
+    span,
+    start,
+    responsive,
+    subgrid,
+    rows,
+    gap,
+    style,
+    ...rest
+  }: GridItemProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'div'
+  const _className = classNames(
+    buildResponsiveClassNames(layoutClassNames, { span, start }, responsive),
+    subgrid && 'grid grid-cols-subgrid',
+    className
+  )
+
+  const _style: GridItemStyle = { ...style }
+
+  if (subgrid) {
+    if (rows !== undefined) _style['--cx-grid-rows'] = rows
+    if (gap !== undefined) _style['--cx-grid-gap'] = resolveGap(gap)
+  }
+
+  return (
+    <Component className={_className} style={_style} {...rest} ref={ref}>
+      {children}
+    </Component>
+  )
+}
+
+export const GridItem = createPolymorphicComponent<GridItemComponent>(
+  GridItemRender as ForwardRefRenderFunction<Element, GridItemProps<ElementType>>,
+  'GridItem'
+)

package/src/components/grid/Row.tsx

@@ -0,0 +1,71 @@
+import React, { forwardRef, HTMLAttributes } from 'react'
+import classNames from 'classnames'
+
+import { buildResponsiveClassNames } from '../../utils/breakpoints'
+import { spacingClassName } from '../../utils/spacingClassName'
+import { Breakpoint, Spacing } from '../../types'
+
+export interface RowLayout {
+  /**
+   * Equal-width columns per row, or `'auto'` for content-sized columns.
+   *
+   * @type { 'auto' | number | string }
+   */
+  cols?: 'auto' | number | string
+  /**
+   * Gutter width on both axes.
+   *
+   * @type { Spacing | 0 }
+   */
+  gutter?: Spacing | 0
+  /**
+   * Horizontal gutter width.
+   *
+   * @type { Spacing | 0 }
+   */
+  gutterX?: Spacing | 0
+  /**
+   * Vertical gutter width.
+   *
+   * @type { Spacing | 0 }
+   */
+  gutterY?: Spacing | 0
+}
+
+export interface RowProps extends HTMLAttributes<HTMLDivElement>, RowLayout {
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * Overrides `cols`/`gutter`/`gutterX`/`gutterY` at a breakpoint and up.
+   *
+   * @type { Partial<Record<'small' | 'medium' | 'large' | 'xlarge' | '2xlarge', { cols?: 'auto' | number | string, gutter?: Spacing | 0, gutterX?: Spacing | 0, gutterY?: Spacing | 0 }>> }
+   */
+  responsive?: Partial<Record<Breakpoint, RowLayout>>
+}
+
+const layoutClassNames = ({ cols, gutter, gutterX, gutterY }: RowLayout, prefix: string) => [
+  cols ? `${prefix}row-cols-${cols}` : null,
+  spacingClassName('g', gutter, prefix),
+  spacingClassName('gx', gutterX, prefix),
+  spacingClassName('gy', gutterY, prefix)
+]
+
+export const Row = forwardRef<HTMLDivElement, RowProps>(
+  ({ children, className, cols, gutter, gutterX, gutterY, responsive, ...rest }, ref) => {
+    const _className = classNames(
+      'row',
+      buildResponsiveClassNames(layoutClassNames, { cols, gutter, gutterX, gutterY }, responsive),
+      className
+    )
+
+    return (
+      <div className={_className} {...rest} ref={ref}>
+        {children}
+      </div>
+    )
+  }
+)
+
+Row.displayName = 'Row'

package/src/components/grid/gap.ts

@@ -0,0 +1,8 @@
+import { SPACING } from '../../types'
+
+const SPACING_TOKENS = new Set<string>(SPACING)
+
+// `Spacing` tokens map to the matching `--cx-space-*` custom property; anything else (a raw CSS
+// value, e.g. `"1rem"` or `".25rem 1rem"`) passes through unchanged.
+export const resolveGap = (gap: string) =>
+  SPACING_TOKENS.has(gap) ? `var(--cx-space-${gap})` : gap

package/src/components/grid/index.ts

@@ -0,0 +1,10 @@
+export { Col } from './Col'
+export type { ColProps } from './Col'
+export { Container } from './Container'
+export type { ContainerProps } from './Container'
+export { Grid } from './Grid'
+export type { GridProps } from './Grid'
+export { GridItem } from './GridItem'
+export type { GridItemProps, GridItemLayout } from './GridItem'
+export { Row } from './Row'
+export type { RowProps } from './Row'