@chassis-ui/react 0.0.0-20260831090525

package/src/components/calendar/RangeCalendar.tsx

@@ -0,0 +1,361 @@
+import React, { forwardRef, HTMLAttributes, useMemo, useRef, useState } from 'react'
+import classNames from 'classnames'
+import {
+  AriaRangeCalendarProps,
+  mergeProps,
+  RangeValue,
+  useCalendarCell,
+  useLocale,
+  useRangeCalendar
+} from 'react-aria'
+import { DateValue, RangeCalendarState, useRangeCalendarState } from 'react-stately'
+import {
+  CalendarDate,
+  createCalendar,
+  getLocalTimeZone,
+  isSameDay,
+  isToday,
+  isWeekend
+} from '@internationalized/date'
+
+import { useForkedRef } from '../../hooks'
+import { CalendarMonthBlock } from './CalendarMonthBlock'
+import { CalendarNavButton } from './CalendarNavButton'
+import { DateRangePreset } from '../../utils/dateRangePresets'
+import { mergeIsDateUnavailable } from '../../utils/mergeIsDateUnavailable'
+import { suppressFocusRing } from '../../utils/suppressFocusRingGlobally'
+import './Calendar.scss'
+import './RangeCalendar.scss'
+
+export interface RangeCalendarProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'onChange' | 'defaultValue'
+> {
+  /**
+   * An accessible label for the calendar, used when there's no visible label. Required for
+   * standalone use — a calendar grid has no other accessible name of its own.
+   */
+  'aria-label'?: string
+  /**
+   * Identifies a visible label element for the calendar.
+   */
+  'aria-labelledby'?: string
+  /**
+   * Whether to automatically focus the calendar when it mounts.
+   */
+  autoFocus?: boolean
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * The initial selected date range (uncontrolled).
+   */
+  defaultValue?: RangeValue<DateValue> | null
+  /**
+   * Prevents the calendar from being focused or interacted with.
+   */
+  disabled?: boolean
+  /**
+   * The day that starts the week, overriding the default set by the active locale.
+   *
+   * @default 'mon'
+   */
+  firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
+  /**
+   * Callback that is called for each date in the calendar. If it returns `true`, that date is
+   * shown but cannot be selected.
+   */
+  isDateUnavailable?: (date: DateValue) => boolean
+  /**
+   * The maximum allowed date that a user may select.
+   */
+  maxValue?: DateValue | null
+  /**
+   * The minimum allowed date that a user may select.
+   */
+  minValue?: DateValue | null
+  /**
+   * Callback fired when a complete range is selected (both a start and end date).
+   */
+  onChange?: (value: RangeValue<DateValue>) => void
+  /**
+   * A list of quick-select range presets shown beside the calendar. Selecting a preset commits
+   * its range immediately, the same as picking a start and end date from the grid. The preset
+   * matching the current selection (if any) is marked selected. Omit to not show a preset list.
+   */
+  presets?: DateRangePreset[]
+  /**
+   * ISO 8601 dates (`YYYY-MM-DD`) to mark unselectable, as a convenience alternative to
+   * `isDateUnavailable` for data-driven cases (e.g. booked dates fetched from an API). Composed
+   * with `isDateUnavailable` when both are given — a date unavailable by either is unavailable.
+   */
+  unavailableDates?: string[]
+  /**
+   * The selected date range (controlled).
+   */
+  value?: RangeValue<DateValue> | null
+  /**
+   * Number of months to display side by side, sharing one selection. Wraps to multiple rows in
+   * a narrow container (e.g. a popover on a small screen) rather than overflowing — the wrap is
+   * driven by the calendar's own width, not the viewport, so it adapts correctly regardless of
+   * where the calendar is embedded.
+   *
+   * @default 1
+   */
+  visibleMonths?: number
+}
+
+// Range counterpart to `Calendar` — same dialog-agnostic composition boundary (see that
+// component's own comment) and the same header/month-year-picker/grid visual language, reusing
+// `Calendar.scss`'s shared classes directly. Kept as its own component rather than a `mode` prop
+// on `Calendar`: the underlying react-stately/react-aria hooks are a genuinely different pair
+// (`useRangeCalendarState`/`useRangeCalendar` vs `useCalendarState`/`useCalendar`), and the cell
+// rendering has range-only concerns (start/end/in-between pill styling) with no single-date
+// equivalent.
+export const RangeCalendar = forwardRef<HTMLDivElement, RangeCalendarProps>(
+  (
+    {
+      autoFocus,
+      className,
+      defaultValue,
+      disabled,
+      firstDayOfWeek = 'mon',
+      isDateUnavailable,
+      maxValue,
+      minValue,
+      onChange,
+      presets,
+      unavailableDates,
+      value,
+      visibleMonths = 1,
+      ...rest
+    },
+    forwardedRef
+  ) => {
+    const { locale } = useLocale()
+    const internalRef = useRef<HTMLDivElement>(null)
+    const ref = useForkedRef(internalRef, forwardedRef)
+    const combinedIsDateUnavailable = useMemo(
+      () => mergeIsDateUnavailable(unavailableDates, isDateUnavailable),
+      [unavailableDates, isDateUnavailable]
+    )
+    const resolvedPresets = presets && presets.length > 0 ? presets : null
+    // Tracks each visible month block's own view, keyed by `monthIndex` — needed only to know
+    // whether *any* block has switched away from the day grid. `CalendarYearGrid` owns its own
+    // prev/next pager, which would otherwise sit right underneath the global `.datepicker-controls`
+    // overlay below (see its own comment) — and even in the month view, where there's no such
+    // literal overlap, the global pager would still page the day grid one block is no longer
+    // showing, which reads as it doing nothing.
+    const [monthViews, setMonthViews] = useState<Record<number, 'days' | 'months' | 'years'>>({})
+    const hasPickerView = Object.values(monthViews).some((view) => view !== 'days')
+
+    const state = useRangeCalendarState({
+      autoFocus,
+      createCalendar,
+      defaultValue,
+      firstDayOfWeek,
+      isDateUnavailable: combinedIsDateUnavailable,
+      isDisabled: disabled,
+      locale,
+      maxValue,
+      minValue,
+      onChange,
+      // Prev/next always slide the visible window by one month, regardless of `visibleMonths` —
+      // react-stately's own default (`pageBehavior: 'visible'`) instead pages by the *entire*
+      // visible span at once (e.g. jumping straight from Nov/Dec to Jan/Feb for `visibleMonths={2}`,
+      // skipping Dec/Jan entirely), which reads as broken next to `CalendarMonthYearDropdowns`'
+      // own one-month-at-a-time jumps.
+      pageBehavior: 'single',
+      value,
+      visibleDuration: { months: visibleMonths }
+    })
+
+    const ariaProps: AriaRangeCalendarProps<DateValue> = {
+      'aria-label': rest['aria-label'],
+      'aria-labelledby': rest['aria-labelledby'],
+      autoFocus,
+      defaultValue,
+      isDateUnavailable: combinedIsDateUnavailable,
+      isDisabled: disabled,
+      maxValue,
+      minValue,
+      onChange,
+      value
+    }
+
+    const { calendarProps, prevButtonProps, nextButtonProps } = useRangeCalendar(
+      ariaProps,
+      state,
+      internalRef
+    )
+    // A single pair of buttons, placed in exactly one spot depending on `visibleMonths` — inline
+    // in the (only) month's own header for a single month, or once as a global overlay for
+    // several — never both, so there's no risk of two DOM nodes fighting over one ref.
+    const prevButton = <CalendarNavButton buttonProps={prevButtonProps} direction="prev" />
+    const nextButton = <CalendarNavButton buttonProps={nextButtonProps} direction="next" />
+    const singleMonthArrows = visibleMonths === 1 ? { next: nextButton, prev: prevButton } : null
+
+    // Goes through the same `state.setValue` path a two-click grid selection does (rather than
+    // calling `onChange` directly), so it behaves identically whether `value` is controlled or
+    // uncontrolled — including `DateRangePicker`, which relies on this to auto-close its popover
+    // the same way completing a range in the grid already does.
+    const handlePresetSelect = (range: RangeValue<DateValue>) => {
+      state.setValue(range)
+    }
+
+    return (
+      <div
+        {...mergeProps(calendarProps, rest)}
+        className={classNames('datepicker', className)}
+        data-cx-inline="true"
+        ref={ref}
+      >
+        <div className="datepicker-grid">
+          {resolvedPresets && (
+            <DateRangePresets
+              onSelect={handlePresetSelect}
+              presets={resolvedPresets}
+              value={state.value}
+            />
+          )}
+          <div className="datepicker-body">
+            {visibleMonths > 1 && !hasPickerView && (
+              <div className="datepicker-controls">
+                {prevButton}
+                {nextButton}
+              </div>
+            )}
+            <div className="datepicker-grid">
+              {[...new Array(visibleMonths).keys()].map((monthIndex) => (
+                <CalendarMonthBlock
+                  arrows={monthIndex === 0 ? singleMonthArrows : null}
+                  firstDayOfWeek={firstDayOfWeek}
+                  key={monthIndex}
+                  monthIndex={monthIndex}
+                  onViewChange={(view) =>
+                    setMonthViews((prev) => ({ ...prev, [monthIndex]: view }))
+                  }
+                  renderCell={(date, i, week) => (
+                    <CalendarCell
+                      date={date}
+                      isFirstInRow={i === 0}
+                      isLastInRow={i === week.length - 1}
+                      locale={locale}
+                      state={state}
+                    />
+                  )}
+                  state={state}
+                />
+              ))}
+            </div>
+          </div>
+        </div>
+      </div>
+    )
+  }
+)
+
+RangeCalendar.displayName = 'RangeCalendar'
+
+interface CalendarCellProps {
+  date: CalendarDate
+  isFirstInRow: boolean
+  isLastInRow: boolean
+  locale: string
+  state: RangeCalendarState
+}
+
+const CalendarCell = ({ date, isFirstInRow, isLastInRow, locale, state }: CalendarCellProps) => {
+  const ref = useRef<HTMLButtonElement>(null)
+  const {
+    cellProps,
+    buttonProps,
+    isSelected,
+    isOutsideVisibleRange,
+    isDisabled,
+    isUnavailable,
+    formattedDate
+  } = useCalendarCell({ date }, state, ref)
+
+  // `isSelected` is true for every day in the range, not just its endpoints — the pill's rounded
+  // caps belong only at the true start/end (or wherever a row wraps mid-range, so the band still
+  // reads as continuous week to week); everything else in between is a flush, square-edged band.
+  const { highlightedRange } = state
+  const isRangeStart = Boolean(highlightedRange && isSameDay(date, highlightedRange.start))
+  const isRangeEnd = Boolean(highlightedRange && isSameDay(date, highlightedRange.end))
+  const isCurrentDate = isToday(date, getLocalTimeZone())
+
+  return (
+    <div
+      {...cellProps}
+      aria-current={isCurrentDate ? 'date' : undefined}
+      className={classNames('datepicker-date', {
+        'datepicker-date-today': isCurrentDate,
+        'datepicker-date-in-range': isSelected,
+        'datepicker-date-range-start': isSelected && (isRangeStart || isFirstInRow),
+        'datepicker-date-range-end': isSelected && (isRangeEnd || isLastInRow),
+        'datepicker-date-outside': isOutsideVisibleRange,
+        'datepicker-date-disabled': isDisabled,
+        'datepicker-date-unavailable': isUnavailable,
+        'datepicker-date-weekend': isWeekend(date, locale)
+      })}
+    >
+      <button
+        {...mergeProps(buttonProps, {
+          // Hovering to preview a range's end date moves real DOM focus via `element.focus()`
+          // (`useCalendarCell`'s `onPointerEnter` -> `state.highlightDate`), which browsers can
+          // paint as a visible focus ring even though the input modality is a pointer, not a
+          // keyboard — suppress it the same way a mouse press does elsewhere in the library.
+          onPointerEnter: () => {
+            if (state.anchorDate && ref.current) suppressFocusRing(ref.current)
+          }
+        })}
+        type="button"
+        className={classNames('datepicker-date-btn', {
+          'datepicker-date-range-start': isRangeStart,
+          'datepicker-date-range-end': isRangeEnd
+        })}
+        ref={ref}
+      >
+        {formattedDate}
+      </button>
+    </div>
+  )
+}
+
+interface DateRangePresetsProps {
+  onSelect: (range: RangeValue<DateValue>) => void
+  presets: DateRangePreset[]
+  value: RangeValue<DateValue> | null
+}
+
+// A preset "matches" the current selection when both endpoints land on the same day — the same
+// granularity `CalendarCell` already uses to compare dates, so a preset stays marked selected
+// regardless of whether `value` is a `CalendarDate`, `CalendarDateTime`, or `ZonedDateTime`.
+const isSameRange = (a: RangeValue<DateValue>, b: RangeValue<DateValue>) =>
+  isSameDay(a.start, b.start) && isSameDay(a.end, b.end)
+
+// Plain buttons in a list, not a listbox — a group of independent actions (each one commits
+// immediately) rather than a single-selection widget, so native Tab/Enter/Space is the right
+// interaction model without extra roving-tabindex/arrow-key wiring.
+const DateRangePresets = ({ onSelect, presets, value }: DateRangePresetsProps) => (
+  <ul className="datepicker-presets">
+    {presets.map((preset) => {
+      const isSelected = Boolean(value && isSameRange(value, preset.range))
+
+      return (
+        <li key={preset.label}>
+          <button
+            aria-current={isSelected ? 'true' : undefined}
+            className={classNames('datepicker-preset', { selected: isSelected })}
+            onClick={() => onSelect(preset.range)}
+            type="button"
+          >
+            {preset.label}
+          </button>
+        </li>
+      )
+    })}
+  </ul>
+)

package/src/components/calendar/index.ts

@@ -0,0 +1,5 @@
+export { Calendar } from './Calendar'
+export type { CalendarProps, CalendarSingleProps, CalendarMultipleProps } from './Calendar'
+export { RangeCalendar } from './RangeCalendar'
+export type { RangeCalendarProps } from './RangeCalendar'
+export type { DateRangePreset } from '../../utils/dateRangePresets'

package/src/components/card/Card.tsx

@@ -0,0 +1,173 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement, ReactNode } from 'react'
+import classNames from 'classnames'
+
+import { Breakpoint, ContextColor, ContextStyle, Sizing } from '../../types'
+import {
+  buildResponsiveClassNames,
+  flexDirectionClassNames,
+  FlexDirection
+} from '../../utils/breakpoints'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+import { CardBody } from './CardBody'
+import { CardFooter } from './CardFooter'
+import { CardImage } from './CardImage'
+import { CardSubtitle } from './CardSubtitle'
+import { CardText } from './CardText'
+import { CardTitle } from './CardTitle'
+
+type CardOwnProps<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
+  /**
+   * Sets the color of the component to one of Chassis context colors.
+   */
+  color?: ContextColor
+  /**
+   * Switches the card from its default stacked (column) layout to a side-by-side (row) layout.
+   * Wrap the image and body in `Col` to control each side's width.
+   */
+  direction?: FlexDirection
+  /**
+   * Shorthand for a `CardFooter`, rendered after the image/title/subtitle/text/`children` block.
+   */
+  footer?: ReactNode
+  /**
+   * Shorthand for a `CardImage` — pass either a `src` URL (combine with `imageAlt`/
+   * `imageOrientation`) or a fully-formed element — a `<CardImage>`, `<Skeleton>`,
+   * `<Placeholder>`, or anything else — rendered as-is in its place. `imageAlt`/`imageOrientation`
+   * only apply to the `src` form; set them directly on your own element otherwise. For a
+   * horizontal layout or an overlay, omit this and compose `CardImage` directly as a child
+   * instead.
+   */
+  image?: ReactNode
+  /**
+   * Accessible alt text for `image`. Ignored unless `image` is set.
+   */
+  imageAlt?: string
+  /**
+   * Orientates `image` to the top (default) or bottom of the card.
+   */
+  imageOrientation?: 'top' | 'bottom'
+  /**
+   * Overrides `direction` at one or more breakpoints — e.g. `{ large: 'row' }` to lay the card
+   * out horizontally from `large` up while stacking below it.
+   */
+  responsive?: Partial<Record<Breakpoint, FlexDirection>>
+  /**
+   * Sets the size of the component to one of Chassis component sizes.
+   */
+  size?: Sizing
+  /**
+   * Shorthand for a `CardSubtitle`, rendered directly after `title`.
+   */
+  subtitle?: ReactNode
+  /**
+   * Shorthand for a `CardText`, rendered after `title`/`subtitle`.
+   */
+  text?: ReactNode
+  /**
+   * Shorthand for a `CardTitle`. Set alongside `subtitle`/`text` (or plain `children`, e.g. a
+   * `Button`) to build a standard card without composing `CardBody`/`CardTitle` yourself — all
+   * render together inside a single `CardBody`, in that order. Only takes effect when at least
+   * one of `image`/`title`/`subtitle`/`text`/`footer` is set; otherwise `children` render as-is,
+   * so full manual composition (`CardHeader`, lists, overlays, nav headers, …) keeps working
+   * unchanged. Mixing shorthand props with a manually-composed `children` tree isn't supported —
+   * pick one approach per card.
+   */
+  title?: ReactNode
+  /**
+   * Sets the context style of the component. `basic` (the default) renders with no extra class.
+   */
+  variant?: ContextStyle
+}
+
+export type CardProps<C extends ElementType = 'div'> = PolymorphicComponentProps<C, CardOwnProps<C>>
+
+type CardComponent = (<C extends ElementType = 'div'>(
+  props: CardProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function CardRender<C extends ElementType = 'div'>(
+  {
+    children,
+    className,
+    color,
+    component,
+    direction,
+    footer,
+    image,
+    imageAlt,
+    imageOrientation = 'top',
+    responsive,
+    size,
+    subtitle,
+    text,
+    title,
+    variant,
+    ...rest
+  }: CardProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'div'
+  const _className = classNames(
+    'card',
+    color,
+    {
+      context: !!color,
+      solid: variant === 'solid',
+      smooth: variant === 'smooth',
+      outline: variant === 'outline',
+      small: size === 'small',
+      large: size === 'large'
+    },
+    buildResponsiveClassNames(flexDirectionClassNames, direction, responsive),
+    className
+  )
+
+  const hasShorthand =
+    image != null || title != null || subtitle != null || footer != null || text != null
+  const hasBodyContent = title != null || subtitle != null || text != null || children != null
+  const renderedImage =
+    typeof image === 'string' ? (
+      <CardImage orientation={imageOrientation} src={image} alt={imageAlt ?? ''} />
+    ) : (
+      image
+    )
+
+  return (
+    <Component className={_className} {...rest} ref={ref}>
+      {hasShorthand ? (
+        <>
+          {image != null && imageOrientation === 'top' && renderedImage}
+          {hasBodyContent && (
+            <CardBody>
+              {title != null && <CardTitle>{title}</CardTitle>}
+              {subtitle != null && <CardSubtitle>{subtitle}</CardSubtitle>}
+              {text != null && <CardText>{text}</CardText>}
+              {children}
+            </CardBody>
+          )}
+          {image != null && imageOrientation === 'bottom' && renderedImage}
+          {footer != null && <CardFooter>{footer}</CardFooter>}
+        </>
+      ) : (
+        children
+      )}
+    </Component>
+  )
+}
+
+export const Card = createPolymorphicComponent<CardComponent>(
+  CardRender as ForwardRefRenderFunction<Element, CardProps<ElementType>>,
+  'Card'
+)

package/src/components/card/CardBody.tsx

@@ -0,0 +1,75 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import { Breakpoint, Spacing } from '../../types'
+import {
+  buildResponsiveClassNames,
+  flexDirectionClassNames,
+  FlexDirection
+} from '../../utils/breakpoints'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+import { spacingClassName } from '../../utils/spacingClassName'
+
+type CardBodyOwnProps<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
+  /**
+   * Switches the body from its default stacked (column) layout to a side-by-side (row) layout —
+   * for placing an image beside text within a single padded region. Wrap the image and text in
+   * `Col` to control each side's width, and nest another `CardBody` (with `.p-0`) for the text
+   * side so it doesn't receive double padding.
+   */
+  direction?: FlexDirection
+  /**
+   * Spacing between children, mapped to the `gap-*` utility classes. Overrides the card's default
+   * gap between body children.
+   */
+  gap?: Spacing | 0
+  /**
+   * Overrides `direction` at one or more breakpoints.
+   */
+  responsive?: Partial<Record<Breakpoint, FlexDirection>>
+}
+
+export type CardBodyProps<C extends ElementType = 'div'> = PolymorphicComponentProps<
+  C,
+  CardBodyOwnProps<C>
+>
+
+type CardBodyComponent = (<C extends ElementType = 'div'>(
+  props: CardBodyProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function CardBodyRender<C extends ElementType = 'div'>(
+  { children, className, component, direction, gap, responsive, ...rest }: CardBodyProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'div'
+  const _className = classNames(
+    'card-body',
+    buildResponsiveClassNames(flexDirectionClassNames, direction, responsive),
+    spacingClassName('gap', gap),
+    className
+  )
+
+  return (
+    <Component className={_className} {...rest} ref={ref}>
+      {children}
+    </Component>
+  )
+}
+
+export const CardBody = createPolymorphicComponent<CardBodyComponent>(
+  CardBodyRender as ForwardRefRenderFunction<Element, CardBodyProps<ElementType>>,
+  'CardBody'
+)

package/src/components/card/CardFooter.tsx

@@ -0,0 +1,47 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+
+type CardFooterOwnProps<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
+}
+
+export type CardFooterProps<C extends ElementType = 'div'> = PolymorphicComponentProps<
+  C,
+  CardFooterOwnProps<C>
+>
+
+type CardFooterComponent = (<C extends ElementType = 'div'>(
+  props: CardFooterProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function CardFooterRender<C extends ElementType = 'div'>(
+  { children, className, component, ...rest }: CardFooterProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'div'
+  const _className = classNames('card-footer', className)
+
+  return (
+    <Component className={_className} {...rest} ref={ref}>
+      {children}
+    </Component>
+  )
+}
+
+export const CardFooter = createPolymorphicComponent<CardFooterComponent>(
+  CardFooterRender as ForwardRefRenderFunction<Element, CardFooterProps<ElementType>>,
+  'CardFooter'
+)