@chassis-ui/react 0.0.0-20260831090525

package/src/components/datepicker/DateRangePicker.tsx

@@ -0,0 +1,343 @@
+import React, { forwardRef, HTMLAttributes, ReactNode, useMemo, useRef } from 'react'
+import { mergeProps, RangeValue, useDateRangePicker, useDialog } from 'react-aria'
+import { DateValue, useDateRangePickerState } from 'react-stately'
+
+import { useForkedRef, useFormField, useOverlayPlacement } from '../../hooks'
+import { DateRangePreset } from '../../utils/dateRangePresets'
+import { mergeIsDateUnavailable } from '../../utils/mergeIsDateUnavailable'
+import { renderFormField } from '../form-field/renderFormField'
+import { RangeCalendar } from '../calendar/RangeCalendar'
+import { CalendarToggleButton } from './CalendarToggleButton'
+import { ClearButton } from './ClearButton'
+import { DateField } from './DateField'
+import { renderDatePickerShell } from './renderDatePickerShell'
+import './DatePicker.scss'
+import './DateRangePicker.scss'
+
+export interface DateRangePickerProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'onChange' | 'defaultValue'
+> {
+  /**
+   * An accessible label for the date range picker, used when there's no visible `<label>`.
+   */
+  'aria-label'?: string
+  /**
+   * Identifies a visible `<label>` element for the date range picker.
+   */
+  'aria-labelledby'?: string
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * Whether the calendar popover is open by default (uncontrolled).
+   *
+   * @default false
+   */
+  defaultOpen?: boolean
+  /**
+   * The initial selected date range (uncontrolled).
+   */
+  defaultValue?: RangeValue<DateValue> | null
+  /**
+   * Prevents the date range picker from being focused or interacted with.
+   */
+  disabled?: boolean
+  /**
+   * The day that starts the week in the calendar overlay, overriding the default set by the
+   * active locale.
+   *
+   * @default 'mon'
+   */
+  firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
+  /**
+   * A description for the field, rendered below the date range picker.
+   */
+  help?: ReactNode
+  /**
+   * `id` forwarded to the field's grouping element — useful for pairing with a `<label for>`.
+   */
+  id?: string
+  /**
+   * Set component validation state to invalid.
+   */
+  invalid?: boolean
+  /**
+   * An error message for the field, rendered below the date range picker when `invalid` is set.
+   */
+  invalidFeedback?: ReactNode
+  /**
+   * 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
+  /**
+   * Whether the calendar popover is open (controlled).
+   */
+  isOpen?: boolean
+  /**
+   * The field's caption, rendered as a `FormLabel` associated with the field group.
+   */
+  label?: ReactNode
+  /**
+   * The maximum allowed date that a user may select.
+   */
+  maxValue?: DateValue | null
+  /**
+   * The minimum allowed date that a user may select.
+   */
+  minValue?: DateValue | null
+  /**
+   * Base `name` for a pair of auto-created hidden inputs, kept in sync with the selection, for
+   * native form submission — rendered as `${name}Start` and `${name}End`. Omit to skip creating
+   * them.
+   */
+  name?: string
+  /**
+   * Callback fired when the selected date range changes.
+   */
+  onChange?: (value: RangeValue<DateValue> | null) => void
+  /**
+   * Callback fired when the calendar popover's open state changes.
+   */
+  onOpenChange?: (isOpen: boolean) => void
+  /**
+   * A list of quick-select range presets shown in the overlay next to the calendar. Selecting a
+   * preset commits its range immediately, the same as picking a start and end date from the
+   * calendar. The preset matching the current selection (if any) is marked selected. Omit to not
+   * show a preset list.
+   */
+  presets?: DateRangePreset[]
+  /**
+   * Size the component small or large.
+   */
+  size?: 'small' | 'large'
+  /**
+   * 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.
+   * Applies to both the calendar overlay and typing a date directly into either field.
+   */
+  unavailableDates?: string[]
+  /**
+   * Set component validation state to valid.
+   */
+  valid?: boolean
+  /**
+   * A success message for the field, rendered below the date range picker when `valid` is set.
+   */
+  validFeedback?: ReactNode
+  /**
+   * The selected date range (controlled).
+   */
+  value?: RangeValue<DateValue> | null
+  /**
+   * Number of months to display side by side in the calendar overlay.
+   *
+   * @default 1
+   */
+  visibleMonths?: number
+}
+
+// Mirrors `DatePicker` closely — same field/overlay/dialog composition, just with two
+// segmented fields (`startFieldProps`/`endFieldProps` in place of a single `fieldProps`) and
+// `RangeCalendar` in place of `Calendar` in the overlay, dialog role/ref landing directly on
+// it exactly as `Calendar` does for `DatePicker`. `presets` is passed straight through —
+// `RangeCalendar` owns rendering and selecting them (it's also usable standalone), so completing
+// one goes through the same `state.setValue`/`onChange` path a two-click grid selection does,
+// which is what closes this overlay automatically.
+export const DateRangePicker = forwardRef<HTMLDivElement, DateRangePickerProps>(
+  (
+    {
+      className,
+      defaultOpen,
+      defaultValue,
+      disabled,
+      firstDayOfWeek,
+      help,
+      id,
+      invalid,
+      invalidFeedback,
+      isDateUnavailable,
+      isOpen,
+      label,
+      maxValue,
+      minValue,
+      name,
+      onChange,
+      onOpenChange,
+      presets,
+      size,
+      unavailableDates,
+      valid,
+      validFeedback,
+      value,
+      visibleMonths,
+      ...rest
+    }: DateRangePickerProps,
+    ref
+  ): ReactNode => {
+    const combinedIsDateUnavailable = useMemo(
+      () => mergeIsDateUnavailable(unavailableDates, isDateUnavailable),
+      [unavailableDates, isDateUnavailable]
+    )
+
+    const state = useDateRangePickerState({
+      defaultOpen,
+      defaultValue,
+      isDateUnavailable: combinedIsDateUnavailable,
+      isDisabled: disabled,
+      isOpen,
+      maxValue,
+      minValue,
+      onChange,
+      onOpenChange,
+      value
+    })
+
+    const groupRef = useRef<HTMLDivElement>(null)
+    const forkedGroupRef = useForkedRef(ref, groupRef)
+    const calendarRef = useRef<HTMLDivElement>(null)
+    const overlayRef = useRef<HTMLDivElement>(null)
+    const toggleButtonRef = useRef<HTMLButtonElement>(null)
+
+    const {
+      describedBy,
+      feedbackId,
+      helpId,
+      inputId: groupId,
+      labelId,
+      labelledBy
+    } = useFormField({
+      ariaDescribedBy: rest['aria-describedby'],
+      ariaLabelledBy: rest['aria-labelledby'],
+      help,
+      id,
+      invalid,
+      invalidFeedback,
+      label,
+      valid,
+      validFeedback
+    })
+
+    const { groupProps, startFieldProps, endFieldProps, buttonProps, calendarProps, dialogProps } =
+      useDateRangePicker(
+        {
+          'aria-label': rest['aria-label'],
+          'aria-labelledby': labelledBy,
+          defaultValue,
+          id: groupId,
+          isDateUnavailable: combinedIsDateUnavailable,
+          isDisabled: disabled,
+          isInvalid: invalid,
+          maxValue,
+          minValue,
+          onChange,
+          value
+        },
+        state,
+        groupRef
+      )
+
+    const { overlayStyle, placementAttr, overlayDismissProps } = useOverlayPlacement({
+      overlayRef,
+      state,
+      triggerRef: groupRef
+    })
+
+    const { dialogProps: domDialogProps } = useDialog(dialogProps, calendarRef)
+
+    return renderFormField({
+      children: (
+        <>
+          {renderDatePickerShell({
+            calendar: (
+              <RangeCalendar
+                {...domDialogProps}
+                autoFocus
+                disabled={disabled}
+                firstDayOfWeek={firstDayOfWeek}
+                isDateUnavailable={combinedIsDateUnavailable}
+                maxValue={maxValue}
+                minValue={minValue}
+                onChange={calendarProps.onChange}
+                presets={presets}
+                ref={calendarRef}
+                value={calendarProps.value}
+                visibleMonths={visibleMonths}
+              />
+            ),
+            className,
+            // `state.value` is always a `{ start, end }` object, never `null` itself — even with
+            // nothing picked yet — so the endpoints are what actually indicate a selection to
+            // clear (matching the hidden-input `value`s below, which check the same way).
+            clearButton: (state.value?.start || state.value?.end) && !disabled && (
+              <ClearButton
+                onPress={() => {
+                  state.setValue(null)
+                  // See `DatePicker`'s identical `ClearButton` usage for why this is needed —
+                  // this button unmounts itself once cleared, so focus needs somewhere to land.
+                  toggleButtonRef.current?.focus()
+                }}
+              />
+            ),
+            disabled,
+            field: (
+              <>
+                <DateField fieldProps={startFieldProps} />
+                <span aria-hidden="true" className="daterangepicker-separator">
+                  –
+                </span>
+                <DateField fieldProps={endFieldProps} />
+              </>
+            ),
+            fieldClassName: 'd-flex w-100',
+            groupProps: {
+              ...mergeProps(groupProps, rest),
+              'aria-describedby': describedBy,
+              'aria-labelledby': labelledBy
+            },
+            groupRef: forkedGroupRef,
+            invalid,
+            isOpen: state.isOpen,
+            overlayDismissProps,
+            overlayRef,
+            overlayStyle,
+            placementAttr,
+            size,
+            toggleButton: (
+              <CalendarToggleButton buttonProps={buttonProps} ref={toggleButtonRef} state={state} />
+            ),
+            valid
+          })}
+          {name && (
+            <>
+              <input
+                disabled={disabled}
+                name={`${name}Start`}
+                type="hidden"
+                value={state.value?.start ? state.value.start.toString() : ''}
+              />
+              <input
+                disabled={disabled}
+                name={`${name}End`}
+                type="hidden"
+                value={state.value?.end ? state.value.end.toString() : ''}
+              />
+            </>
+          )}
+        </>
+      ),
+      help,
+      ids: { feedback: feedbackId, help: helpId, label: labelId },
+      invalid,
+      invalidFeedback,
+      label,
+      valid,
+      validFeedback
+    })
+  }
+)
+
+DateRangePicker.displayName = 'DateRangePicker'

package/src/components/datepicker/index.ts

@@ -0,0 +1,4 @@
+export { DatePicker } from './DatePicker'
+export type { DatePickerProps, DatePickerSingleProps, DatePickerMultipleProps } from './DatePicker'
+export { DateRangePicker } from './DateRangePicker'
+export type { DateRangePickerProps } from './DateRangePicker'

package/src/components/datepicker/renderDatePickerShell.tsx

@@ -0,0 +1,104 @@
+import React, { CSSProperties, HTMLAttributes, ReactNode, Ref } from 'react'
+import classNames from 'classnames'
+import { FocusScope } from 'react-aria'
+
+import { validationClassName } from '../../utils/validationClassName'
+
+export interface RenderDatePickerShellOptions {
+  /**
+   * The fully-built calendar element (`Calendar`/`RangeCalendar`, with its own dialog role/ref
+   * already applied) — only ever mounted while `isOpen`, inside a `FocusScope`.
+   */
+  calendar: ReactNode
+  className?: string
+  /**
+   * The `ClearButton` element, or `null`/`undefined` when there's nothing to clear.
+   */
+  clearButton?: ReactNode
+  disabled?: boolean
+  /**
+   * The field itself — a single segmented `DateField`, a read-only `MultiDateField`, or a pair
+   * of `DateField`s either side of a separator.
+   */
+  field: ReactNode
+  /**
+   * className for the wrapper directly around `field` — differs slightly by variant
+   * (`DateRangePicker`'s two side-by-side fields need `d-flex`, the single-field variants don't).
+   */
+  fieldClassName: string
+  /**
+   * Already-merged props (react-aria's `groupProps`/`mergeProps(rest)`, plus
+   * `aria-describedby`/`aria-labelledby` and any variant-specific ARIA attributes) for the
+   * `.form-input` wrapper — assembling this is the caller's job since react-aria only returns a
+   * `groupProps` shape for the single-select hooks, not the manually-assembled multi-select case.
+   */
+  groupProps: HTMLAttributes<HTMLDivElement>
+  groupRef: Ref<HTMLDivElement>
+  invalid?: boolean
+  isOpen: boolean
+  overlayDismissProps: HTMLAttributes<HTMLElement>
+  overlayRef: Ref<HTMLDivElement>
+  overlayStyle?: CSSProperties
+  placementAttr?: string
+  size?: 'small' | 'large'
+  toggleButton: ReactNode
+  valid?: boolean
+}
+
+// Shared `.form-input` adorn-wrapper + popover-overlay shell for `DatePicker`'s two internal
+// variants (single/multiple selection) and `DateRangePicker` — otherwise duplicated near-verbatim
+// three times. What's left in each caller is only the genuinely variant-specific pieces: which
+// field(s) render inside the wrapper, which calendar (`Calendar`/`RangeCalendar`, single- vs.
+// range-typed props) renders inside the overlay, and how each variant's own `groupProps`/hidden
+// inputs get built.
+export const renderDatePickerShell = ({
+  calendar,
+  className,
+  clearButton,
+  disabled,
+  field,
+  fieldClassName,
+  groupProps,
+  groupRef,
+  invalid,
+  isOpen,
+  overlayDismissProps,
+  overlayRef,
+  overlayStyle,
+  placementAttr,
+  size,
+  toggleButton,
+  valid
+}: RenderDatePickerShellOptions): ReactNode => (
+  <>
+    <div
+      {...groupProps}
+      className={classNames(
+        'form-input',
+        size,
+        { disabled },
+        validationClassName(invalid, valid),
+        className
+      )}
+      ref={groupRef}
+    >
+      <div className={fieldClassName}>{field}</div>
+      {clearButton}
+      {toggleButton}
+    </div>
+    <div
+      className="datepicker"
+      data-cx-placement={placementAttr}
+      hidden={!isOpen}
+      ref={overlayRef}
+      {...overlayDismissProps}
+      style={overlayStyle}
+    >
+      {isOpen && (
+        <FocusScope contain restoreFocus>
+          {calendar}
+        </FocusScope>
+      )}
+    </div>
+  </>
+)

package/src/components/drawer/Drawer.tsx

@@ -0,0 +1,211 @@
+import React, {
+  createContext,
+  DialogHTMLAttributes,
+  forwardRef,
+  useEffect,
+  useId,
+  useRef
+} from 'react'
+import classNames from 'classnames'
+
+import { useDialogElement } from '../../hooks'
+
+export interface DrawerProps extends Omit<
+  DialogHTMLAttributes<HTMLDialogElement>,
+  'onCancel' | 'onClose'
+> {
+  /**
+   * Show a backdrop while the drawer is open. `'static'` blocks closing on backdrop click
+   * (the drawer nudges instead).
+   */
+  backdrop?: boolean | 'static'
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * Size the height to the drawer's content instead of `--drawer-height`. Meaningful for
+   * `placement="bottom"`.
+   */
+  fitContent?: boolean
+  /**
+   * Expand the panel to fill the viewport, animating in from the direction of `placement`.
+   */
+  fullscreen?: boolean
+  /**
+   * Disable the open/close transition entirely.
+   */
+  instant?: boolean
+  /**
+   * Closes the drawer when the escape key is pressed.
+   */
+  keyboard?: boolean
+  /**
+   * Callback fired when the drawer requests to be closed (escape, backdrop click, close button,
+   * or another drawer opening).
+   */
+  onClose?: () => void
+  /**
+   * Callback fired when a close attempt is blocked (static backdrop click, or escape with `keyboard=false`).
+   */
+  onClosePrevented?: () => void
+  /**
+   * Callback fired after the exit transition completes and the drawer is fully hidden.
+   */
+  onHidden?: () => void
+  /**
+   * Callback fired when the drawer starts to open.
+   */
+  onShow?: () => void
+  /**
+   * Callback fired after the entry transition completes and the drawer is fully visible.
+   */
+  onShown?: () => void
+  /**
+   * Which viewport edge the panel slides in from. Always required — there is no default
+   * off-screen transform without one.
+   */
+  placement: 'start' | 'end' | 'top' | 'bottom'
+  /**
+   * Renders as a drawer only below this breakpoint — inline as a flex container above it.
+   */
+  responsive?: 'small' | 'medium' | 'large' | 'xlarge' | '2xlarge'
+  /**
+   * Allow the page behind the drawer to scroll while it's open.
+   */
+  scroll?: boolean
+  /**
+   * Remove the inset gap, border radius, and border so the panel sits flush against the
+   * viewport edge.
+   */
+  sheet?: boolean
+  /**
+   * Apply a frosted-glass background to the panel.
+   */
+  translucent?: boolean
+  /**
+   * Toggle the visibility of the drawer component.
+   */
+  visible?: boolean
+}
+
+export interface DrawerContextProps {
+  /**
+   * Requests the drawer be closed — fires `onClose`. Wire this to any element's `onClick`; see
+   * `useDrawer`.
+   */
+  close: () => void
+  /**
+   * Id generated by `Drawer` and applied automatically by `DrawerTitle` to itself, so the
+   * dialog's `aria-labelledby` resolves to it without any manual wiring.
+   */
+  titleId?: string
+}
+
+export const DrawerContext = createContext<DrawerContextProps>({ close: () => {} })
+
+// Currently-open drawers, so opening one can auto-close any other open drawer
+// ("When a second drawer opens while one is already open, the first closes automatically").
+const openDrawers = new Set<{ dialog: HTMLDialogElement; close: () => void }>()
+
+export const Drawer = forwardRef<HTMLDialogElement, DrawerProps>(
+  (
+    {
+      children,
+      backdrop = true,
+      className,
+      fitContent,
+      fullscreen,
+      instant,
+      keyboard = true,
+      onClose,
+      onClosePrevented,
+      onHidden,
+      onShow,
+      onShown,
+      placement,
+      responsive,
+      scroll = false,
+      sheet,
+      translucent,
+      visible,
+      ...rest
+    },
+    ref
+  ) => {
+    const { close, dialogRef, forkedRef, handleBackdropClick, handleCancel, hiding, staticBounce } =
+      useDialogElement({
+        backdrop,
+        instant,
+        isModal: Boolean(backdrop) || !scroll,
+        keyboard,
+        onBeforeShow: (dialog) => {
+          for (const entry of openDrawers) {
+            if (entry.dialog !== dialog) entry.close()
+          }
+        },
+        onClose,
+        onClosePrevented,
+        onHidden,
+        onShow,
+        onShown,
+        ref,
+        visible
+      })
+
+    const titleId = useId()
+
+    const closeRef = useRef(close)
+    closeRef.current = close
+
+    // Register in the cross-instance registry so other drawers can auto-close this one.
+    useEffect(() => {
+      const dialog = dialogRef.current
+      if (!dialog) return undefined
+      const entry = { dialog, close: () => closeRef.current() }
+      openDrawers.add(entry)
+      return () => {
+        openDrawers.delete(entry)
+      }
+    }, [dialogRef])
+
+    // `hiding` has to stay on the class list for the whole exit transition: the native `open`
+    // attribute — and with it, the `[class*="drawer"]:not([open], .hiding)` escape hatch
+    // chassis-css's navbar styles use to suppress the drawer-flash transition when the navbar
+    // itself crosses its `expand` breakpoint — would otherwise get stripped the instant `open`
+    // is removed, which would also strip the *intentional* close transition this class exists
+    // to protect.
+    const _className = classNames(
+      responsive ? `max-${responsive}:drawer` : 'drawer',
+      `drawer-${placement}`,
+      {
+        fullscreen,
+        sheet,
+        translucent,
+        instant,
+        'drawer-fit-content': fitContent,
+        nonmodal: !(Boolean(backdrop) || !scroll),
+        static: staticBounce,
+        hiding
+      },
+      className
+    )
+
+    return (
+      <DrawerContext.Provider value={{ close, titleId }}>
+        <dialog
+          aria-labelledby={titleId}
+          {...rest}
+          className={_className}
+          onCancel={handleCancel}
+          onClick={handleBackdropClick}
+          ref={forkedRef}
+        >
+          {children}
+        </dialog>
+      </DrawerContext.Provider>
+    )
+  }
+)
+
+Drawer.displayName = 'Drawer'

package/src/components/drawer/DrawerBody.tsx

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