@chassis-ui/react 0.2.0 → 0.3.0

package/src/utils/polymorphic.ts

@@ -1,100 +0,0 @@
-import {
-  ComponentPropsWithoutRef,
-  ComponentPropsWithRef,
-  createElement,
-  ElementType,
-  ForwardRefRenderFunction,
-  forwardRef,
-  Ref
-} from 'react'
-
-import { devWarning } from './devWarning'
-import { getSlotChild, Slot, SlotProvider } from './slot'
-
-// Ref type inferred from a polymorphic component's currently-selected `component` element type.
-export type PolymorphicRef<C extends ElementType> = ComponentPropsWithRef<C>['ref']
-
-/**
- * Ref type for a polymorphic component that can also pick its element from a prop *other* than
- * `component` — `Button`, `Chip`, `Avatar`, `NavbarBrand` and `PaginationItem` all render an
- * `<a>` when given `href`, and `PaginationItem` a `<span>` when `active`, none of which moves `C`
- * off its default. A plain `PolymorphicRef<C>` describes only the `component` branch, so a caller
- * holding a ref for the element that actually gets rendered (`<Button href="/x" ref={anchorRef}>`)
- * got a spurious type error while the runtime happily populated it.
- *
- * `Ref` over the *union* rather than a union of `Ref`s is what makes a
- * `createRef<HTMLButtonElement | HTMLAnchorElement>()` assignable here: `RefObject` is invariant
- * in its type argument, so `RefObject<A | B>` satisfies `Ref<A | B>` but neither `Ref<A>` nor
- * `Ref<B>` on its own.
- */
-export type PolymorphicRefWithFallback<C extends ElementType, Fallback extends HTMLElement> =
-  PolymorphicRef<C> | Ref<Fallback>
-
-/**
- * The `asChild` prop every polymorphic component accepts alongside `component` — see
- * `createPolymorphicComponent` below for how it's implemented once for all of them.
- */
-export interface AsChildProps {
-  /**
-   * Render the single child element in place of this component's own element, with this
-   * component's classes, props and ref merged onto it: `<Button asChild><Link href="/login">Log
-   * in</Link></Button>`. The alternative to `component` for React Server Components — an element
-   * can be passed from the server to this package's client components, a component reference
-   * (`component={Link}`) can't.
-   */
-  asChild?: boolean
-}
-
-/**
- * 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 &
-  AsChildProps &
-  Omit<ComponentPropsWithoutRef<C>, keyof OwnProps | keyof AsChildProps>
-
-/**
- * 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.
- *
- * Also implements `asChild` for every polymorphic component at once (#23): the render function
- * gets `component={Slot}` and the child element's own children, so it computes its classes,
- * props and ref exactly as it would for any component reference (`component={Link}`) — `Slot`
- * then clones the caller's child element with all of that merged on (see `./slot`). No render
- * function needs to know `asChild` exists.
- */
-export function createPolymorphicComponent<T>(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  render: ForwardRefRenderFunction<Element, any>,
-  displayName: string
-): T {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const Component = forwardRef<Element, any>(({ asChild, ...props }, ref) => {
-    const child = asChild ? getSlotChild(props.children, displayName) : null
-    if (!child) return render(props, ref)
-
-    devWarning(
-      props.component !== undefined,
-      `${displayName}: both \`asChild\` and \`component\` were passed; \`asChild\` wins and ` +
-        `\`component\` is ignored.`
-    )
-
-    return createElement(
-      SlotProvider,
-      { value: child },
-      render(
-        { ...props, component: Slot, children: (child.props as PropsWithChildren).children },
-        ref
-      )
-    )
-  }) as unknown as T & { displayName?: string }
-  Component.displayName = displayName
-  return Component
-}
-
-type PropsWithChildren = { children?: unknown }

package/src/utils/renderMenuItemContent.tsx

@@ -1,57 +0,0 @@
-import React, { ReactNode } from 'react'
-
-import { IconSlot } from './iconSlot'
-
-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 — `IconProvider`'s `check` icon.
-   */
-  selected?: boolean
-}
-
-// 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
-}: 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 && <IconSlot icon="check" className="menu-item-check" />}
-    </>
-  )
-}

package/src/utils/setVisibleRangeStart.ts

@@ -1,64 +0,0 @@
-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/slot.tsx

@@ -1,78 +0,0 @@
-import React, {
-  cloneElement,
-  createContext,
-  forwardRef,
-  Fragment,
-  isValidElement,
-  ReactElement,
-  ReactNode,
-  Ref,
-  useContext,
-  version
-} from 'react'
-import { mergeProps } from 'react-aria'
-
-import { useForkedRef } from '../hooks/useForkedRef'
-import { devWarning } from './devWarning'
-
-// Backs the `asChild` prop every polymorphic component accepts (see `createPolymorphicComponent`).
-// The component renders `Slot` as its `component`, exactly like any other component reference;
-// `Slot` then renders the caller's child element in its place, with the props the component
-// computed (className, handlers, ARIA attributes, ref) merged onto it.
-//
-// The child element travels through context rather than a prop because a render function spreads
-// its `rest` props onto `component` in its own way (some filter them, some don't forward every
-// one) — context reaches `Slot` no matter how the render function wires it up. `Slot` resets the
-// context for its own subtree, so a polymorphic component nested *inside* the child doesn't pick
-// up the outer one's element.
-type SlotElement = ReactElement<Record<string, unknown>>
-
-const SlotContext = createContext<SlotElement | null>(null)
-
-export const SlotProvider = SlotContext.Provider
-
-// React 19 moved `ref` onto `props` (and warns on reading `element.ref`); React 18 only has
-// `element.ref`. The package supports both (`peerDependencies.react: >=18`).
-const REACT_19 = parseInt(version, 10) >= 19
-
-function getElementRef(element: SlotElement): Ref<unknown> | undefined {
-  return REACT_19
-    ? (element.props as { ref?: Ref<unknown> }).ref
-    : (element as unknown as { ref?: Ref<unknown> }).ref
-}
-
-// `Record` rather than a declared prop list: `Slot` forwards whatever the render function hands it.
-type SlotProps = Record<string, unknown>
-
-export const Slot = forwardRef<unknown, SlotProps>(function Slot({ children, ...slotProps }, ref) {
-  const element = useContext(SlotContext)
-  const forkedRef = useForkedRef(ref, element ? getElementRef(element) : undefined)
-  if (!element) return null
-
-  return (
-    <SlotContext.Provider value={null}>
-      {cloneElement(
-        element,
-        // react-aria's `mergeProps`: the child's own props win over the component's, except that
-        // classNames concatenate, event handlers chain (the component's first), and ids merge.
-        { ...mergeProps(slotProps, element.props), ref: forkedRef } as Record<string, unknown>,
-        children as ReactNode
-      )}
-    </SlotContext.Provider>
-  )
-})
-
-// The single element `asChild` renders in place of the component's own element, or `null` (with
-// a dev warning) when `children` isn't exactly one — the component then falls back to rendering
-// its default element, so a misuse degrades to a working, if unstyled-as-intended, UI.
-export function getSlotChild(children: ReactNode, displayName: string): SlotElement | null {
-  if (isValidElement<Record<string, unknown>>(children) && children.type !== Fragment) {
-    return children
-  }
-  devWarning(
-    true,
-    `${displayName}: \`asChild\` expects exactly one React element as its child (not text, a ` +
-      `fragment, or several elements); rendering the default element instead.`
-  )
-  return null
-}

package/src/utils/spacingClassName.ts

@@ -1,14 +0,0 @@
-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

@@ -1,84 +0,0 @@
-// 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>()
-
-// Which ring-painting style properties a given call suppresses. The global `pointerdown` path
-// only ever needs `outline` (that's the whole of chassis-css's `:focus-visible` ring); a
-// script-driven focus redirect also clears `boxShadow`, since an element it lands on may carry a
-// ring painted that way — see `focusRedirect`.
-export type SuppressibleStyle = 'outline' | 'boxShadow'
-
-const DEFAULT_STYLES: readonly SuppressibleStyle[] = ['outline']
-
-// 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, and
-// `focusRedirect`, which delegates here rather than reimplementing the save/restore cycle).
-export function suppressFocusRing(
-  el: HTMLElement,
-  styles: readonly SuppressibleStyle[] = DEFAULT_STYLES
-): 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, the pointer re-entering a cell, or a repeated `focusRedirect` onto the same
-  // element) would otherwise stack a second blur listener whose "previous" value it captured
-  // *after* the first call already set the property to `none` — restoring `none` and leaving the
-  // ring permanently suppressed. One shared set across every caller, so a global-listener
-  // suppression and a `focusRedirect` one can't stack on each other either.
-  if (suppressed.has(el)) return
-
-  suppressed.add(el)
-  const restore = styles.map((style) => [style, el.style[style]] as const)
-  for (const [style] of restore) el.style[style] = 'none'
-  el.addEventListener(
-    'blur',
-    () => {
-      for (const [style, value] of restore) el.style[style] = value
-      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/tableClassName.ts

@@ -1,93 +0,0 @@
-import classNames from 'classnames'
-
-import { Breakpoint, ContextColor } from '../types'
-
-// The styling props `Table` and `StaticTable` share. Kept in one place so the two can't drift into
-// applying different chassis-css classes for the same prop — `StaticTable` exists to be the
-// zero-JS twin of `Table`'s look, so a prop meaning something different on each would defeat it.
-export interface TableStyleProps {
-  /**
-   * Set the vertical alignment of cell content.
-   */
-  align?: 'bottom' | 'middle' | 'top'
-  /**
-   * Add borders on all sides of the table and cells.
-   */
-  bordered?: boolean
-  /**
-   * Remove borders on all sides of the table and cells.
-   */
-  borderless?: boolean
-  /**
-   * A string of all className you want applied to the component.
-   */
-  className?: string
-  /**
-   * Sets the color of the component.
-   */
-  color?: ContextColor
-  /**
-   * Enable a hover state on table rows.
-   */
-  hover?: boolean
-  /**
-   * Make any table responsive across all viewports or pick a maximum breakpoint.
-   */
-  responsive?: boolean | Breakpoint
-  /**
-   * Make table more compact by cutting all cell padding.
-   */
-  sm?: boolean
-  /**
-   * Convert rows into stacked label/value blocks below a container width, for tables with too
-   * many columns to read comfortably even with horizontal scrolling. `true` always stacks; a
-   * breakpoint name stacks only below it. Implies `responsive` when `responsive` isn't set
-   * separately, since stacking needs the same `.table-responsive` container-query ancestor.
-   */
-  stacked?: boolean | Breakpoint
-  /**
-   * Add zebra-striping to table rows.
-   */
-  striped?: boolean
-}
-
-export function tableClassName({
-  align,
-  bordered,
-  borderless,
-  className,
-  color,
-  hover,
-  sm,
-  stacked,
-  striped
-}: TableStyleProps): string | undefined {
-  return (
-    classNames(
-      'table',
-      color,
-      {
-        [`align-${align}`]: align,
-        bordered,
-        borderless,
-        hoverable: hover,
-        sm,
-        stacked: stacked === true,
-        striped
-      },
-      typeof stacked === 'string' ? `max-${stacked}:stacked` : undefined,
-      className
-    ) || undefined
-  )
-}
-
-// `undefined` when the table needs no wrapper at all. Stacking needs the same `.table-responsive`
-// container-query ancestor as horizontal scrolling, so `stacked` alone still gets one.
-export function tableWrapperClassName({
-  responsive,
-  stacked
-}: Pick<TableStyleProps, 'responsive' | 'stacked'>): string | undefined {
-  if (!responsive && !stacked) return undefined
-  if (!responsive || responsive === true) return 'table-responsive'
-  return `max-${responsive}:table-responsive`
-}

package/src/utils/triggerElement.ts

@@ -1,25 +0,0 @@
-import { HTMLAttributes, ReactElement, Ref, version as reactVersion } from 'react'
-
-/**
- * `Popover`/`Tooltip` both take their trigger as a single `ReactElement` child and re-render it
- * with `cloneElement`. A bare `ReactElement` types its props as `unknown`, which makes
- * `cloneElement`'s config `Partial<unknown> & Attributes` — no `ref`, no event handlers, nothing
- * to merge against. This is the narrowed view both components read the child through.
- *
- * Kept internal: each component's own public `children: ReactElement` stays as-is, so a caller
- * can still pass any element without having to satisfy this shape.
- */
-export type TriggerElementProps = HTMLAttributes<HTMLElement> & { ref?: Ref<HTMLElement> }
-
-export type TriggerElement = ReactElement<TriggerElementProps>
-
-export const asTriggerElement = (element: ReactElement): TriggerElement => element as TriggerElement
-
-// React 19 turned `ref` into an ordinary prop; before that it lived on the element itself and was
-// stripped out of `props`. React 19's development build installs a warning getter on
-// `element.ref`, so this reads only the location that's correct for the React actually running
-// rather than probing both and tripping that warning on every trigger that has no ref at all.
-const REF_LIVES_IN_PROPS = parseInt(reactVersion, 10) >= 19
-
-export const getTriggerRef = (element: TriggerElement): Ref<HTMLElement> | undefined =>
-  REF_LIVES_IN_PROPS ? element.props.ref : (element as { ref?: Ref<HTMLElement> }).ref

package/src/utils/validationClassName.ts

@@ -1,8 +0,0 @@
-// 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

@@ -1,16 +0,0 @@
-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