@chassis-ui/react 0.0.0-20260831090525

package/src/utils/mergeIsDateUnavailable.ts

@@ -0,0 +1,15 @@
+import { DateValue } from 'react-stately'
+
+// `date.toString()` on a `CalendarDate` (the only `DateValue` variant `Calendar`/`DatePicker`
+// ever produce — both are date-only, no time segments) yields the same ISO 8601 `YYYY-MM-DD`
+// string already used elsewhere for form submission (see `DatePicker`'s hidden input), so
+// `unavailableDates` entries are expected in that same format.
+export const mergeIsDateUnavailable = (
+  unavailableDates: string[] | undefined,
+  isDateUnavailable: ((date: DateValue) => boolean) | undefined
+): ((date: DateValue) => boolean) | undefined => {
+  if (!unavailableDates?.length && !isDateUnavailable) return undefined
+
+  const set = unavailableDates?.length ? new Set(unavailableDates) : null
+  return (date) => Boolean(set?.has(date.toString())) || Boolean(isDateUnavailable?.(date))
+}

package/src/utils/overlayPlacement.ts

@@ -0,0 +1,93 @@
+import type { CSSProperties } from 'react'
+import type { Placement as AriaPlacement, PlacementAxis } from 'react-aria'
+
+// Chassis CSS's floating components (`.menu`, `.tooltip`, `.popover`) read a `data-cx-placement`
+// attribute in this hyphenated, compound form (`"bottom-end"`, `"top-start"`, ...) to pick the
+// right transform-origin for the open/close animation. React Aria's `useOverlayPosition` speaks a
+// different, space-separated placement vocabulary (`"bottom end"`) and only reports back the
+// resolved main axis after flipping, not the full compound value — this module bridges the two.
+export type Placement =
+  | 'top'
+  | 'top-start'
+  | 'top-end'
+  | 'bottom'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'left'
+  | 'left-start'
+  | 'left-end'
+  | 'right'
+  | 'right-start'
+  | 'right-end'
+
+const ARIA_PLACEMENT: Record<Placement, AriaPlacement> = {
+  top: 'top',
+  'top-start': 'top start',
+  'top-end': 'top end',
+  bottom: 'bottom',
+  'bottom-start': 'bottom start',
+  'bottom-end': 'bottom end',
+  left: 'left',
+  'left-start': 'left top',
+  'left-end': 'left bottom',
+  right: 'right',
+  'right-start': 'right top',
+  'right-end': 'right bottom'
+}
+
+// Translates chassis-react's public `placement` prop values into the strings
+// `useOverlayPosition` expects.
+export const toAriaPlacement = (placement: Placement): AriaPlacement => ARIA_PLACEMENT[placement]
+
+// `useOverlayPosition`'s own `shouldFlip` only ever swaps the main axis (top<->bottom or
+// left<->right) — it never changes the requested cross-axis alignment — so the resolved compound
+// value is always the requested cross-axis suffix reattached to the (possibly flipped) main axis
+// `useOverlayPosition` reports back.
+export const resolveDataPlacement = (
+  requested: Placement,
+  resolvedMain: PlacementAxis | null
+): string => {
+  if (!resolvedMain || resolvedMain === 'center') return requested
+  const cross = requested.split('-')[1]
+  return cross ? `${resolvedMain}-${cross}` : resolvedMain
+}
+
+// Shared between `Menu`/`MenuSubmenu` and `Combobox`/`Autocomplete`, whose floating panels all
+// position via `useOverlayPosition` the same way: only `position`/`top`/`left` are taken from the
+// hook's computed style (`zIndex`/`maxHeight` stay owned by chassis-css's own `--zindex`/
+// `--max-height` tokens, see `_menu.scss`), and `data-cx-placement` needs the resolved main axis
+// reattached to the originally-requested cross-axis alignment. Lives here (rather than
+// `components/menu/`) for the same reason `renderMenuItemContent` does — `Combobox.tsx`/
+// `Autocomplete.tsx` need it too, and importing across that folder boundary from three call sites
+// is worse than housing it where none of the four has to reach into a sibling's folder.
+export interface MenuOverlayPositioning {
+  menuStyle: CSSProperties
+  placementAttr: string
+}
+
+export const resolveMenuOverlayPositioning = (
+  overlayStyle: CSSProperties | undefined,
+  requestedPlacement: Placement,
+  resolvedPlacement: PlacementAxis | null
+): MenuOverlayPositioning => ({
+  menuStyle: {
+    position: overlayStyle?.position,
+    top: overlayStyle?.top,
+    left: overlayStyle?.left
+  },
+  placementAttr: resolveDataPlacement(requestedPlacement, resolvedPlacement)
+})
+
+// chassis-css's `.combobox + .menu` sibling-selector rule (`_combobox.scss`) sets
+// `--menu-max-height`/`--menu-overflow-y` from `$combobox-menu-max-height`/
+// `$combobox-menu-overflow-y` (320px/auto by default) — but only while the panel is an adjacent
+// DOM sibling of `.combobox`. `Autocomplete`/`Combobox` portal their panel to `document.body` (or
+// an enclosing open `<dialog>`, via `useFloatingOverlay`), breaking that adjacency, so both inline
+// this as a fallback matching the shipped Sass defaults instead of the generic, uncapped `.menu`
+// fallback (`max-height: none`). A consumer who customized either Sass variable needs to
+// re-override `--menu-max-height`/`--menu-overflow-y` on `.menu` directly, since the
+// sibling-selector auto-application can no longer reach a portaled panel.
+export const COMBOBOX_MENU_OVERLAY_STYLE: CSSProperties = {
+  '--menu-max-height': '320px',
+  '--menu-overflow-y': 'auto'
+} as CSSProperties

package/src/utils/pointerInteraction.ts

@@ -0,0 +1,21 @@
+// Tracks, per-element, whether its most recent activation came from a real pointer click rather
+// than a keyboard one (a `click` fired by pointer activation has `detail >= 1`; one fired by
+// keyboard activation, e.g. Enter/Space on a focused button, has `detail === 0`) — for callers
+// that need that information later, asynchronously, once React has committed the state update the
+// click triggered (see `Carousel.tsx`'s disabled-end focus redirect, which needs it to decide
+// whether `focusRedirect` should suppress Safari's script-focus-after-pointer-click ring). A
+// `WeakSet` rather than a DOM attribute so it doesn't leak into markup/snapshots, and consuming it
+// clears the entry so a later, unrelated keyboard activation on the same element isn't
+// misattributed as pointer-triggered.
+const pointerClicks = new WeakSet<HTMLElement>()
+
+export function markPointerClick(el: HTMLElement): void {
+  pointerClicks.add(el)
+}
+
+export function consumePointerClick(el: HTMLElement | null): boolean {
+  if (!el) return false
+  const wasPointer = pointerClicks.has(el)
+  pointerClicks.delete(el)
+  return wasPointer
+}

package/src/utils/polymorphic.ts

@@ -0,0 +1,36 @@
+import {
+  ComponentPropsWithoutRef,
+  ComponentPropsWithRef,
+  ElementType,
+  ForwardRefRenderFunction,
+  forwardRef
+} from 'react'
+
+// Ref type inferred from a polymorphic component's currently-selected `component` element type.
+export type PolymorphicRef<C extends ElementType> = ComponentPropsWithRef<C>['ref']
+
+/**
+ * Props for a polymorphic component: `OwnProps` (which must declare `component?: C`) plus
+ * whatever props `C` itself accepts, minus any name already claimed by `OwnProps` so the two
+ * don't conflict. Lets consumers swap `component` for e.g. a framework's `Image` and get full
+ * type-checking/autocomplete for that component's own props at the call site.
+ */
+export type PolymorphicComponentProps<C extends ElementType, OwnProps extends object> = OwnProps &
+  Omit<ComponentPropsWithoutRef<C>, keyof OwnProps>
+
+/**
+ * Wraps a polymorphic component's render function in `forwardRef` and stamps `displayName` — the
+ * two-step wiring every polymorphic component in this library repeats identically. `T` is the
+ * fully generic component type (e.g. `ButtonComponent`) that `forwardRef`'s own return type can't
+ * express, since `forwardRef` only accepts a non-generic render function — the caller still casts
+ * the render function to a concrete `Element`-typed instance before passing it in here.
+ */
+export function createPolymorphicComponent<T>(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  render: ForwardRefRenderFunction<Element, any>,
+  displayName: string
+): T {
+  const Component = forwardRef(render) as unknown as T & { displayName?: string }
+  Component.displayName = displayName
+  return Component
+}

package/src/utils/renderMenuItemContent.tsx

@@ -0,0 +1,62 @@
+import React, { ReactNode } from 'react'
+
+import { Icon } from '../components/icon/Icon'
+
+export interface MenuItemContentDef {
+  /**
+   * Icon rendered at the item's leading edge (`.menu-item-icon`).
+   */
+  icon?: ReactNode
+  /**
+   * Label content.
+   */
+  label: ReactNode
+  /**
+   * Secondary line of text rendered below the label (`.menu-item-description`).
+   */
+  description?: ReactNode
+  /**
+   * Renders a `.menu-item-check` at the trailing edge when true.
+   */
+  selected?: boolean
+  /**
+   * Icon name for the selected-state check. Defaults to chassis-css's own doc example.
+   */
+  checkIcon?: string
+}
+
+// Chassis-css defines identical markup for rich item content in both Menu and Combobox items
+// (and, by extension, Autocomplete) — `.menu-item-icon` / `.menu-item-content` (label +
+// `.menu-item-description`) / `.menu-item-check`. Shared here so every consumer produces
+// byte-identical DOM instead of three near-duplicate implementations. Lives in `utils/` rather
+// than `components/menu/` because it crosses that folder boundary — Combobox.tsx and
+// Autocomplete.tsx both import it too. Renders bare `label` when there's nothing else to show,
+// keeping simple items' markup as minimal as chassis-css's own simplest example.
+export const renderMenuItemContent = ({
+  icon,
+  label,
+  description,
+  selected,
+  checkIcon = 'check-solid'
+}: MenuItemContentDef): ReactNode => {
+  if (icon == null && description == null && !selected) return label
+
+  return (
+    <>
+      {icon != null && (
+        <span className="menu-item-icon" aria-hidden="true">
+          {icon}
+        </span>
+      )}
+      {description != null ? (
+        <span className="menu-item-content">
+          <span>{label}</span>
+          <small className="menu-item-description">{description}</small>
+        </span>
+      ) : (
+        label
+      )}
+      {selected && <Icon name={checkIcon} className="menu-item-check" />}
+    </>
+  )
+}

package/src/utils/setVisibleRangeStart.ts

@@ -0,0 +1,64 @@
+import { flushSync } from 'react-dom'
+import { CalendarState, RangeCalendarState } from 'react-stately'
+import { CalendarDate } from '@internationalized/date'
+
+// Moves a (possibly multi-month) calendar's visible range so it starts at `desiredStart` — used by
+// `CalendarMonthYearPicker` to jump straight to a picked month/year, in any visible block.
+//
+// `state.setFocusedDate` is the only way to move `visibleRange` from outside react-stately, but it
+// doesn't just set `visibleRange.start` to wherever focus goes: react-stately keeps the visible
+// range as separate internal state, only repositioning it when the newly focused date falls
+// entirely *before* the current range (realigning so the range *ends* at that date's month) or
+// entirely *after* it (realigning so it *starts* there) — a focused date that lands inside the
+// current range moves focus without paging the range at all. That means a single `setFocusedDate`
+// call can only land exactly on an arbitrary `desiredStart` when it's at least a full
+// `visibleDuration` away from the current range. Anything closer — the common case here, since
+// adjacent blocks in a multi-month calendar are only one month apart — either no-ops (desired
+// start still inside the current range) or overshoots by up to a full `visibleDuration` (desired
+// start just outside it, but not far enough for the realignment to land exactly).
+//
+// Worked around with two `setFocusedDate` hops when a single one can't reach exactly: first past
+// `desiredStart` by one extra `visibleDuration` in the same direction (always far enough to land
+// exactly, by the same rule), flushed synchronously so `visibleRange` actually updates before the
+// second call runs, then back onto `desiredStart` itself — which, relative to that intermediate
+// range, is now exactly one `visibleDuration` away and so lands exactly too.
+export const setVisibleRangeStart = (
+  state: CalendarState<'single' | 'multiple'> | RangeCalendarState,
+  desiredStart: CalendarDate
+): void => {
+  const { start: currentStart, end: currentEnd } = state.visibleRange
+  if (desiredStart.compare(currentStart) === 0) return
+
+  const durationMonths = state.visibleDuration.months || 1
+  const isForward = desiredStart.compare(currentStart) > 0
+
+  const reachableInOneHop = isForward
+    ? desiredStart.compare(currentEnd) > 0
+    : desiredStart.add({ months: durationMonths - 1 }).compare(currentStart) < 0
+
+  if (reachableInOneHop) {
+    state.setFocusedDate(focusedDateForStart(desiredStart, isForward, durationMonths))
+    return
+  }
+
+  const overshootStart = isForward
+    ? desiredStart.add({ months: durationMonths })
+    : desiredStart.subtract({ months: durationMonths })
+
+  flushSync(() => {
+    state.setFocusedDate(focusedDateForStart(overshootStart, isForward, durationMonths))
+  })
+  // Relative to the now-updated range, `desiredStart` sits exactly one `visibleDuration` back the
+  // way we came — always far enough for a single hop to land exactly.
+  state.setFocusedDate(focusedDateForStart(desiredStart, !isForward, durationMonths))
+}
+
+// react-stately's forward-paging realignment anchors the new range to whatever month
+// `focusedDate` itself falls in; its backward-paging one anchors it `visibleDuration - 1` months
+// *before* `focusedDate`'s month instead — so landing on a specific desired start takes a
+// different `focusedDate` depending on which of the two is going to fire.
+const focusedDateForStart = (
+  desiredStart: CalendarDate,
+  isForward: boolean,
+  durationMonths: number
+): CalendarDate => (isForward ? desiredStart : desiredStart.add({ months: durationMonths - 1 }))

package/src/utils/spacingClassName.ts

@@ -0,0 +1,14 @@
+import { Spacing } from '../types'
+
+// A spacing prop (`gap`/`rowGap`/`gutter`/...) is typed `Spacing | 0`, but `0` is meaningful
+// (chassis-css's `gap-0` etc. exist) while `undefined`/`false`-ish values mean "not set" — a
+// plain truthy check would drop `0`, so every caller needs this same `typeof` guard instead.
+// Shared by `Flex`, `Stack`, `Row`, and `CardBody`'s own `layoutClassNames`/`_className` builders,
+// which otherwise duplicated it once per spacing prop (`gap`, `rowGap`, `columnGap`, `gutter`,
+// `gutterX`, `gutterY`, ...).
+export const spacingClassName = (
+  base: string,
+  value: Spacing | 0 | undefined,
+  prefix = ''
+): string | null =>
+  typeof value === 'string' || typeof value === 'number' ? `${prefix}${base}-${value}` : null

package/src/utils/suppressFocusRingGlobally.ts

@@ -0,0 +1,69 @@
+// Chromium/WebKit's `:focus-visible` heuristic has no interaction history to consult on the very
+// first focus event of a page load, so a genuine pointer press can still paint a focus ring as if
+// it came from the keyboard — most visible on whatever element happens to be the first thing a
+// visitor clicks. A single capture-phase `pointerdown` listener on `document`, installed once (see
+// `install` below, called for its side effect from `index.ts`), preemptively suppresses the
+// outline on whatever focusable element the press is about to focus — before the browser's own
+// default action grants focus and paints the ring for it — then restores it on blur. Safe to run
+// on every press, not just the page's first: if the browser was already going to correctly
+// withhold the ring, this suppress/restore cycle is a no-op within the same frame.
+//
+// Mirrors react-aria's own `@react-aria/interactions` global modality tracking (one document-level
+// listener rather than one per component/instance) without switching this library's focus rings
+// from chassis-css's native `:focus-visible` CSS to JS-driven state — react-aria's `isFocusVisible`
+// is consumed by applying a class/attribute, which would fork focus-ring styling from the vanilla,
+// non-React product chassis-css also ships. Deliberately unscoped to this library's own markup, for
+// the same reason react-aria's own fix is unscoped: the browser bug isn't specific to any one
+// component library, and a page generally wants one consistent focus-ring policy for every
+// focusable element on it, not just the subset a component library happens to own.
+const FOCUSABLE_SELECTOR = 'a[href], button, input, select, textarea, [tabindex]'
+
+const suppressed = new WeakSet<HTMLElement>()
+
+// Shared by the global `pointerdown` listener below and by call sites that move focus themselves
+// via script (e.g. `RangeCalendar`'s hover-to-preview-a-range, which calls `element.focus()` from
+// a `pointerenter` handler — outside the `pointerdown` this module otherwise listens for).
+export function suppressFocusRing(el: HTMLElement): void {
+  // chassis-css's `.form-input` placeholder deliberately grants its focus ring on `:focus-within`
+  // as well as `:focus-visible` (see `_form.scss`), unlike the `:focus-visible`-only policy this
+  // module otherwise mirrors for buttons/links/checks/etc. — a form field is meant to show its
+  // ring regardless of whether the focus came from a click or the keyboard, so the very
+  // first-press-of-page-load quirk this module works around isn't a bug for `.form-input` in the
+  // first place: forcing its outline off here would fight, then correctly-but-uselessly restore,
+  // an outline chassis-css wants visible the whole time the field is focused.
+  if (el.classList.contains('form-input')) return
+  // `suppressed` guards re-entrancy: a second call for the same element before it blurs (e.g. a
+  // rapid re-press, or the pointer re-entering a cell) would otherwise stack a second blur
+  // listener that clobbers the first restoration and leaves the ring permanently suppressed.
+  if (suppressed.has(el)) return
+
+  suppressed.add(el)
+  const prevOutline = el.style.outline
+  el.style.outline = 'none'
+  el.addEventListener(
+    'blur',
+    () => {
+      el.style.outline = prevOutline
+      suppressed.delete(el)
+    },
+    { once: true }
+  )
+}
+
+function handlePointerDown(event: PointerEvent) {
+  const target = event.target
+  if (!(target instanceof Element)) return
+  const el = target.closest<HTMLElement>(FOCUSABLE_SELECTOR)
+  if (!el) return
+  suppressFocusRing(el)
+}
+
+let installed = false
+
+export function install(): void {
+  if (installed || typeof document === 'undefined') return
+  installed = true
+  document.addEventListener('pointerdown', handlePointerDown, true)
+}
+
+install()

package/src/utils/validationClassName.ts

@@ -0,0 +1,8 @@
+// Chassis-css's validation-state classes, shared by every form control that supports
+// `invalid`/`valid` (Radio, Switch, RangeInput, Select, TextInput, Textarea). Returns a
+// `classNames`-compatible object rather than a resolved string so callers can still combine it
+// with their own base/size classes and `className` in one `classNames(...)` call.
+export const validationClassName = (invalid?: boolean, valid?: boolean) => ({
+  'is-invalid': invalid,
+  'is-valid': valid
+})

package/src/utils/virtualFocusStyle.ts

@@ -0,0 +1,16 @@
+import { CSSProperties } from 'react'
+
+// Options in a virtually-focused listbox (react-aria's combobox/listbox patterns) never receive
+// real DOM focus — focus stays on the trigger (a text input or button) while the highlighted
+// option is tracked virtually, so `:hover`/`:focus-visible` can't style it. To indicate the
+// highlight without touching chassis-css, we reuse its own hover color tokens (already defined
+// on the ancestor `.menu`, prefixed `--cx-` by chassis-css's build) as inline overrides instead
+// of relying on `.active`, which chassis-css reserves for the pressed/`:active` look.
+export const virtualFocusStyle: CSSProperties = {
+  '--cx-icon-color': 'var(--cx-item-hover-icon-color)',
+  '--cx-item-fg-color': 'var(--cx-item-hover-fg-color)',
+  '--cx-item-bg-color': 'var(--cx-item-hover-bg-color)'
+} as CSSProperties
+
+export const getVirtualFocusStyle = (isFocused: boolean): CSSProperties | undefined =>
+  isFocused ? virtualFocusStyle : undefined