@chassis-ui/react 0.0.0-20260831090525

package/src/components/toast/context.ts

@@ -0,0 +1,14 @@
+import { createContext } from 'react'
+
+export interface ToastContextProps {
+  /**
+   * Whether the toast is currently visible.
+   */
+  visible?: boolean
+  /**
+   * Dismisses the toast. Wire this to any element's `onClick` — see `useToast`.
+   */
+  close: () => void
+}
+
+export const ToastContext = createContext<ToastContextProps>({ close: () => {} })

package/src/components/toast/index.ts

@@ -0,0 +1,18 @@
+export { Toast } from './Toast'
+export type { ToastProps } from './Toast'
+export { ToastBody } from './ToastBody'
+export type { ToastBodyProps } from './ToastBody'
+export { ToastFooter } from './ToastFooter'
+export type { ToastFooterProps } from './ToastFooter'
+export { ToastHeader } from './ToastHeader'
+export type { ToastHeaderProps } from './ToastHeader'
+export { ToastIcon } from './ToastIcon'
+export type { ToastIconProps } from './ToastIcon'
+
+// Toaster is an independent manager/container component (react-hot-toast-style), not a Toast
+// sub-part — it subscribes to the shared toastQueue and renders Toast instances from it, rather
+// than being composed as a child of Toast. Stays a separate top-level export.
+export { Toaster } from './Toaster'
+export type { ToasterProps } from './Toaster'
+export { addToast, closeToast, toastQueue } from './toastQueue'
+export type { ToastContent } from './toastQueue'

package/src/components/toast/toastQueue.ts

@@ -0,0 +1,56 @@
+import { ReactNode } from 'react'
+import { ToastQueue } from 'react-stately'
+
+import { ContextColor } from '../../types'
+
+export interface ToastContent {
+  /**
+   * Apply a CSS fade transition to the toast.
+   */
+  animation?: boolean
+  /**
+   * Auto hide the toast. The timer starts once the show transition completes and pauses
+   * while the pointer is over the toast or focus is within it.
+   */
+  autohide?: boolean
+  /**
+   * Content of the toast — typically a `Toast.Header`/`Toast.Body`/`Toast.Footer`.
+   */
+  children: ReactNode
+  /**
+   * Sets the color of the component to one of Chassis context colors.
+   */
+  color?: ContextColor
+  /**
+   * Delay hiding the toast (ms).
+   */
+  delay?: number
+  /**
+   * Apply a full-color background with inverted text. Only meaningful alongside `color`.
+   */
+  solid?: boolean
+  /**
+   * Apply a semi-transparent background.
+   */
+  translucent?: boolean
+}
+
+// The queue backing `Toaster` — a module-level singleton so `addToast()` is callable from
+// anywhere (an event handler, an async callback) without threading a `push` prop through
+// render. `Toaster` subscribes to it via `useToastQueue`; nothing renders until a
+// `<Toaster />` is actually mounted somewhere to display the queue's contents.
+export const toastQueue = new ToastQueue<ToastContent>()
+
+// Adds a toast to the queue. Returns the toast's key, which can be passed to `closeToast` to
+// dismiss it programmatically.
+export function addToast(
+  children: ReactNode,
+  options: Omit<ToastContent, 'children'> = {}
+): string {
+  return toastQueue.add({ children, ...options })
+}
+
+// Removes a queued toast immediately, bypassing its own exit animation.
+export function closeToast(key: string): void {
+  toastQueue.close(key)
+}

package/src/components/tooltip/Tooltip.tsx

@@ -0,0 +1,155 @@
+import React, { FC, ReactElement, ReactNode, useRef } from 'react'
+import { createPortal } from 'react-dom'
+import classNames from 'classnames'
+import { mergeProps, useOverlayPosition, useTooltip, useTooltipTrigger } from 'react-aria'
+import { useTooltipTriggerState } from 'react-stately'
+import { Transition } from 'react-transition-group'
+
+import { getOverlayArrowStyle, getOverlayTransitionClass, useFloatingOverlay } from '../../hooks'
+import { Placement, resolveDataPlacement, toAriaPlacement } from '../../utils/overlayPlacement'
+
+export type { Placement }
+
+export interface TooltipProps {
+  children: ReactElement
+  /**
+   * Content node for your component.
+   */
+  content: ReactNode | string
+  /**
+   * Offset of the tooltip relative to its target, as `[crossAxis, mainAxis]`.
+   */
+  offset?: [number, number]
+  /**
+   * Callback fired when the component requests to be hidden.
+   */
+  onHide?: () => void
+  /**
+   * Callback fired when the component requests to be shown.
+   */
+  onShow?: () => void
+  /**
+   * Describes the preferred placement of your component. Chassis will flip it to keep it in
+   * view.
+   */
+  placement?: Placement
+  /**
+   * Tooltips always show on focus, since keyboard/screen-reader users need them too. Set to
+   * `'focus'` to disable the hover trigger and show on focus only.
+   */
+  trigger?: 'hover' | 'focus'
+  /**
+   * Toggle the visibility of the tooltip component.
+   */
+  visible?: boolean
+}
+
+export const Tooltip: FC<TooltipProps> = ({
+  children,
+  content,
+  placement = 'top',
+  offset: offsetProp = [0, 6],
+  onHide,
+  onShow,
+  trigger,
+  visible,
+  ...rest
+}) => {
+  const arrowRef = useRef<HTMLDivElement>(null)
+  const triggerRef = useRef<HTMLElement | null>(null)
+  const floatingRef = useRef<HTMLDivElement>(null)
+
+  // react-stately defaults to a 1500ms warmup delay (and 500ms cooldown) before a first tooltip
+  // shows, spectrum-style — chassis-css's own JS plugin defaults to instant (`delay: 0`), so
+  // match that here rather than leaving new adopters to wonder why the first hover lags.
+  const state = useTooltipTriggerState({ trigger, delay: 0, closeDelay: 0 })
+  const { triggerProps, tooltipProps: tooltipTriggerProps } = useTooltipTrigger(
+    { trigger },
+    state,
+    triggerRef
+  )
+  const { tooltipProps } = useTooltip({}, state)
+
+  // Bypasses the hook's hover-warmup delay (`open`/`close`'s `immediate` argument) since a
+  // programmatic `visible` change, an `onShow`/`onHide` sync, or a containing dialog closing
+  // should all apply right away, same as before.
+  const portalContainer = useFloatingOverlay({
+    close: () => state.close(true),
+    isOpen: state.isOpen,
+    open: () => state.open(true),
+    onHide,
+    onShow,
+    triggerRef,
+    visible
+  })
+
+  const {
+    overlayProps,
+    arrowProps,
+    placement: resolvedPlacement
+  } = useOverlayPosition({
+    targetRef: triggerRef,
+    overlayRef: floatingRef,
+    placement: toAriaPlacement(placement),
+    offset: offsetProp[1],
+    crossOffset: offsetProp[0],
+    arrowSize: 8,
+    arrowRef,
+    isOpen: state.isOpen
+  })
+
+  const floatingStyle: React.CSSProperties = {
+    position: overlayProps.style?.position as React.CSSProperties['position'],
+    top: overlayProps.style?.top,
+    left: overlayProps.style?.left
+  }
+  const placementAttr = resolveDataPlacement(placement, resolvedPlacement)
+
+  return (
+    <>
+      {React.cloneElement(children, {
+        ref: (node: HTMLElement | null) => {
+          triggerRef.current = node
+        },
+        ...triggerProps
+      })}
+      {typeof window !== 'undefined' &&
+        createPortal(
+          <Transition
+            in={state.isOpen}
+            mountOnEnter
+            nodeRef={floatingRef}
+            timeout={{
+              enter: 0,
+              exit: 200
+            }}
+            unmountOnExit
+          >
+            {(transitionState) => {
+              const transitionClass = getOverlayTransitionClass(transitionState)
+              return (
+                <div
+                  className={classNames('tooltip cx-tooltip-auto', transitionClass)}
+                  data-cx-placement={placementAttr}
+                  ref={floatingRef}
+                  style={floatingStyle}
+                  {...mergeProps(tooltipTriggerProps, tooltipProps)}
+                  {...rest}
+                >
+                  <div
+                    className="tooltip-arrow"
+                    {...arrowProps}
+                    style={getOverlayArrowStyle(arrowProps)}
+                  ></div>
+                  <div className="tooltip-inner">{content}</div>
+                </div>
+              )
+            }}
+          </Transition>,
+          portalContainer ?? document.body
+        )}
+    </>
+  )
+}
+
+Tooltip.displayName = 'Tooltip'

package/src/components/tooltip/index.ts

@@ -0,0 +1,2 @@
+export { Tooltip } from './Tooltip'
+export type { TooltipProps } from './Tooltip'

package/src/global.d.ts

@@ -0,0 +1,2 @@
+declare module '*.css'
+declare module '*.scss'

package/src/hooks/index.ts

@@ -0,0 +1,57 @@
+import { useAutoDismiss } from './useAutoDismiss'
+import { useButtonSemantics } from './useButtonSemantics'
+import { useControllableState } from './useControllableState'
+import { useDialogElement } from './useDialogElement'
+import { useDisabledAnchorGuard } from './useDisabledAnchorGuard'
+import { useDismissibleTransition } from './useDismissibleTransition'
+import { useDrawer } from './useDrawer'
+import {
+  getOverlayArrowStyle,
+  getOverlayTransitionClass,
+  useFloatingOverlay
+} from './useFloatingOverlay'
+import { useForkedRef } from './useForkedRef'
+import { useFormField } from './useFormField'
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'
+import { useModal } from './useModal'
+import { useNotification } from './useNotification'
+import { useOverlayPlacement } from './useOverlayPlacement'
+import { usePagination } from './usePagination'
+import { useToast } from './useToast'
+import { useToastRegionQueue } from './useToastRegionQueue'
+
+export {
+  getOverlayArrowStyle,
+  getOverlayTransitionClass,
+  useAutoDismiss,
+  useButtonSemantics,
+  useControllableState,
+  useDialogElement,
+  useDisabledAnchorGuard,
+  useDismissibleTransition,
+  useDrawer,
+  useFloatingOverlay,
+  useForkedRef,
+  useFormField,
+  useIsomorphicLayoutEffect,
+  useModal,
+  useNotification,
+  useOverlayPlacement,
+  usePagination,
+  useToast,
+  useToastRegionQueue
+}
+export type { UseAutoDismissOptions, UseAutoDismissResult } from './useAutoDismiss'
+export type { UseDialogElementOptions } from './useDialogElement'
+export type {
+  UseDismissibleTransitionOptions,
+  UseDismissibleTransitionResult
+} from './useDismissibleTransition'
+export type { UseDrawerResult } from './useDrawer'
+export type { UseFloatingOverlayOptions } from './useFloatingOverlay'
+export type { UseFormFieldOptions, UseFormFieldResult } from './useFormField'
+export type { UseModalResult } from './useModal'
+export type { UseNotificationResult } from './useNotification'
+export type { UsePaginationResult } from './usePagination'
+export type { UseToastResult } from './useToast'
+export type { UseToastRegionQueueResult } from './useToastRegionQueue'

package/src/hooks/useAutoDismiss.ts

@@ -0,0 +1,88 @@
+import { useCallback, useEffect, useRef } from 'react'
+
+export interface UseAutoDismissOptions {
+  /**
+   * Enables the auto-dismiss timer. When `false`, `onHide` is never called and the returned
+   * handlers are no-ops.
+   */
+  enabled?: boolean
+  /**
+   * Delay in ms before `onHide` fires once the timer is (re)started.
+   */
+  delay?: number
+  /**
+   * Whether the dismissible element is currently visible. The timer only runs while `true`.
+   */
+  visible: boolean
+  /**
+   * Called once the delay elapses without an intervening pointer/focus interaction.
+   */
+  onHide: () => void
+}
+
+export interface UseAutoDismissResult {
+  onMouseEnter: () => void
+  onMouseLeave: () => void
+  onFocus: () => void
+  onBlur: () => void
+}
+
+// Shared timer logic for components that auto-dismiss after a delay, pausing while the pointer
+// or focus is on the element (mirrors the behavior `Toast` already implements). Extracted so new
+// auto-dismissing components don't reimplement the pause/resume bookkeeping.
+export function useAutoDismiss({
+  enabled = false,
+  delay = 5000,
+  visible,
+  onHide
+}: UseAutoDismissOptions): UseAutoDismissResult {
+  const timeout = useRef<number>()
+  const hasMouseInteraction = useRef(false)
+  const hasKeyboardInteraction = useRef(false)
+
+  const clearAutoDismissTimeout = useCallback(() => {
+    clearTimeout(timeout.current)
+    timeout.current = undefined
+  }, [])
+
+  const maybeScheduleHide = useCallback(() => {
+    clearAutoDismissTimeout()
+    if (!enabled || hasMouseInteraction.current || hasKeyboardInteraction.current) {
+      return
+    }
+    timeout.current = window.setTimeout(onHide, delay)
+  }, [enabled, delay, onHide, clearAutoDismissTimeout])
+
+  // Clears on unmount.
+  useEffect(() => clearAutoDismissTimeout, [clearAutoDismissTimeout])
+
+  useEffect(() => {
+    if (visible) {
+      maybeScheduleHide()
+    } else {
+      clearAutoDismissTimeout()
+    }
+  }, [visible, enabled, delay, maybeScheduleHide, clearAutoDismissTimeout])
+
+  const onMouseEnter = useCallback(() => {
+    hasMouseInteraction.current = true
+    clearAutoDismissTimeout()
+  }, [clearAutoDismissTimeout])
+
+  const onMouseLeave = useCallback(() => {
+    hasMouseInteraction.current = false
+    maybeScheduleHide()
+  }, [maybeScheduleHide])
+
+  const onFocus = useCallback(() => {
+    hasKeyboardInteraction.current = true
+    clearAutoDismissTimeout()
+  }, [clearAutoDismissTimeout])
+
+  const onBlur = useCallback(() => {
+    hasKeyboardInteraction.current = false
+    maybeScheduleHide()
+  }, [maybeScheduleHide])
+
+  return { onMouseEnter, onMouseLeave, onFocus, onBlur }
+}

package/src/hooks/useButtonSemantics.ts

@@ -0,0 +1,33 @@
+import { MouseEventHandler, Ref, RefObject, useRef } from 'react'
+import { AriaButtonProps, useButton } from 'react-aria'
+
+import { useForkedRef } from './useForkedRef'
+
+interface UseButtonSemanticsOptions<T extends HTMLElement> {
+  disabled?: boolean
+  onClick?: MouseEventHandler<T>
+}
+
+// Synthesizes native button semantics (role, tabIndex, Enter/Space activation) for a
+// non-native `component` — a `<button>`/`<a>`/`<input>` gets all of this for free from the
+// browser, but an arbitrary `component` (e.g. `'div'`, `'span'`) doesn't. Shared by
+// `Link`/`Button`/`CloseButton`, which otherwise duplicated this ref/hook wiring near-verbatim.
+// `elementType: 'div'` and the `HTMLDivElement` cast below are fixed regardless of the actual
+// rendered tag — `useButton` only uses `elementType` to pick which ARIA attributes apply
+// (a `div`-shaped set is the right one for an arbitrary non-native element either way), not to
+// constrain the ref's real type.
+export const useButtonSemantics = <T extends HTMLElement>(
+  ref: Ref<T>,
+  { disabled, onClick }: UseButtonSemanticsOptions<T>
+) => {
+  const buttonRef = useRef<T | null>(null)
+  const forkedRef = useForkedRef(ref, buttonRef)
+  const buttonAriaProps: AriaButtonProps<'div'> = {
+    elementType: 'div',
+    isDisabled: disabled,
+    onClick: onClick as unknown as AriaButtonProps<'div'>['onClick']
+  }
+  const { buttonProps } = useButton(buttonAriaProps, buttonRef as RefObject<HTMLDivElement | null>)
+
+  return { buttonProps, forkedRef }
+}

package/src/hooks/useControllableState.ts

@@ -0,0 +1,24 @@
+import { useState } from 'react'
+
+/**
+ * Shared controlled/uncontrolled state pattern: `value` present means controlled (the returned
+ * state always mirrors it), otherwise state is tracked internally starting from `defaultValue`.
+ * The returned setter updates internal state (when uncontrolled) and always calls `onChange`,
+ * leaving the caller free to layer additional logic (e.g. an `onComplete` callback) around it.
+ */
+export function useControllableState<T>(
+  value: T | undefined,
+  defaultValue: T,
+  onChange?: (value: T) => void
+): [T, (next: T) => void] {
+  const isControlled = value !== undefined
+  const [uncontrolledValue, setUncontrolledValue] = useState<T>(defaultValue)
+  const state = isControlled ? (value as T) : uncontrolledValue
+
+  const setState = (next: T) => {
+    if (!isControlled) setUncontrolledValue(next)
+    onChange?.(next)
+  }
+
+  return [state, setState]
+}

package/src/hooks/useDialogElement.ts

@@ -0,0 +1,216 @@
+import {
+  ForwardedRef,
+  MouseEvent as ReactMouseEvent,
+  SyntheticEvent,
+  useEffect,
+  useRef,
+  useState
+} from 'react'
+import { usePreventScroll } from 'react-aria'
+
+import { useForkedRef } from './useForkedRef'
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'
+import { executeAfterTransition } from '../utils/dialogTransition'
+
+export interface UseDialogElementOptions {
+  /**
+   * Same-named prop from the caller (`Modal`/`Drawer`) — only ever consulted here to
+   * distinguish `'static'` from everything else for the backdrop-click/Escape bounce.
+   */
+  backdrop?: boolean | 'static'
+  /**
+   * Disables the open/close transition entirely.
+   */
+  instant?: boolean
+  /**
+   * Whether this open should use `showModal()` (top-layer, native backdrop, scroll-locked) or
+   * `show()` — `Modal` passes its own `modal` prop straight through; `Drawer` derives it from
+   * `backdrop`/`scroll` instead, since its vanilla chassis-css counterpart does the same.
+   */
+  isModal: boolean
+  /**
+   * Closes on the escape key / native `cancel` event.
+   */
+  keyboard?: boolean
+  /**
+   * Fires synchronously right before a closed dialog actually opens (after the "already open"
+   * bail-out, before capturing the pre-open trigger element) — `Drawer`'s only hook into the
+   * show effect, used to auto-close every other open drawer first.
+   */
+  onBeforeShow?: (dialog: HTMLDialogElement) => void
+  onClose?: () => void
+  onClosePrevented?: () => void
+  onHidden?: () => void
+  onShow?: () => void
+  onShown?: () => void
+  ref: ForwardedRef<HTMLDialogElement>
+  visible?: boolean
+}
+
+// Shared open/close machinery for a native `<dialog>`-based component — `Modal` and `Drawer`
+// otherwise duplicated this near-verbatim: forked ref, the show/begin-hide effect (showModal()
+// vs. show(), initial focus, scroll lock), the finish-hide effect (waits out the exit
+// transition), the non-modal Escape-key listener (the native `cancel` event only fires for
+// dialogs opened with `showModal()`), and the static-backdrop "bounce" used by both the
+// backdrop-click handler and the Escape/`cancel` handler. What's left in each caller is only
+// what's genuinely component-specific: `Modal`/`Drawer`'s own `_className` building, and
+// `Drawer`'s cross-instance "auto-close every other open drawer" registry (wired in via
+// `onBeforeShow`, since it needs to run at one precise point inside the show effect).
+export const useDialogElement = ({
+  backdrop,
+  instant,
+  isModal,
+  keyboard = true,
+  onBeforeShow,
+  onClose,
+  onClosePrevented,
+  onHidden,
+  onShow,
+  onShown,
+  ref,
+  visible
+}: UseDialogElementOptions) => {
+  const dialogRef = useRef<HTMLDialogElement>(null)
+  const forkedRef = useForkedRef(ref, dialogRef)
+
+  const [_visible, setVisible] = useState(visible)
+  const [hiding, setHiding] = useState(false)
+  const [staticBounce, setStaticBounce] = useState(false)
+  const [scrollLocked, setScrollLocked] = useState(false)
+  const openedAsModalRef = useRef(false)
+  const triggerRef = useRef<HTMLElement | null>(null)
+
+  // Locked from showModal() until the exit transition finishes (see the show/hide effect
+  // below) — usePreventScroll releases it automatically on unmount too, even mid-transition.
+  usePreventScroll({ isDisabled: !scrollLocked })
+
+  useEffect(() => {
+    setVisible(visible)
+  }, [visible])
+
+  const close = () => {
+    onClose?.()
+  }
+
+  const triggerStaticBounce = () => {
+    onClosePrevented?.()
+    const dialog = dialogRef.current
+    if (!dialog) return
+    setStaticBounce(true)
+    executeAfterTransition(dialog, () => setStaticBounce(false), !instant)
+  }
+
+  // Read through refs, kept current every render, so the keydown listener below — which only
+  // resubscribes when `keyboard` changes — never invokes a stale `close`/`triggerStaticBounce`
+  // closure if `onClose`/`onClosePrevented`/`instant` change identity without `keyboard` also
+  // changing. Same pattern as `Drawer`'s own `closeRef` and `useFloatingOverlay`'s `closeRef`.
+  const closeRef = useRef(close)
+  closeRef.current = close
+  const triggerStaticBounceRef = useRef(triggerStaticBounce)
+  triggerStaticBounceRef.current = triggerStaticBounce
+
+  // Show / begin-hide
+  useIsomorphicLayoutEffect(() => {
+    const dialog = dialogRef.current
+    if (!dialog) return undefined
+
+    if (_visible) {
+      if (dialog.open) return undefined
+
+      onBeforeShow?.(dialog)
+
+      triggerRef.current =
+        document.activeElement instanceof HTMLElement ? document.activeElement : null
+
+      openedAsModalRef.current = isModal
+      if (isModal) {
+        dialog.showModal()
+        setScrollLocked(true)
+      } else {
+        dialog.show()
+      }
+
+      const autofocusEl = dialog.querySelector<HTMLElement>('[autofocus]')
+      if (autofocusEl) {
+        autofocusEl.focus()
+      } else {
+        dialog.setAttribute('tabindex', '-1')
+        dialog.focus()
+      }
+
+      onShow?.()
+      setHiding(false)
+
+      return executeAfterTransition(dialog, () => onShown?.(), !instant)
+    }
+
+    if (!dialog.open) return undefined
+    setHiding(true)
+    return undefined
+  }, [_visible])
+
+  // Finish hide once the exit transition (or lack thereof) completes
+  useEffect(() => {
+    const dialog = dialogRef.current
+    if (!hiding || !dialog) return undefined
+
+    return executeAfterTransition(
+      dialog,
+      () => {
+        if (dialog.open) {
+          dialog.close()
+        }
+        if (openedAsModalRef.current) {
+          setScrollLocked(false)
+        }
+        setHiding(false)
+        onHidden?.()
+        const trigger = triggerRef.current
+        if (trigger && document.contains(trigger)) {
+          trigger.focus()
+        }
+      },
+      !instant
+    )
+  }, [hiding])
+
+  // Escape key for non-modal (show()) dialogs — the native `cancel` event below only
+  // fires for dialogs opened with showModal().
+  useEffect(() => {
+    const dialog = dialogRef.current
+    if (!dialog) return undefined
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape' || openedAsModalRef.current) return
+      event.preventDefault()
+      if (!keyboard) {
+        triggerStaticBounceRef.current()
+        return
+      }
+      closeRef.current()
+    }
+
+    dialog.addEventListener('keydown', handleKeyDown)
+    return () => dialog.removeEventListener('keydown', handleKeyDown)
+  }, [keyboard])
+
+  const handleCancel = (event: SyntheticEvent<HTMLDialogElement>) => {
+    event.preventDefault()
+    if (!keyboard) {
+      triggerStaticBounce()
+      return
+    }
+    close()
+  }
+
+  const handleBackdropClick = (event: ReactMouseEvent<HTMLDialogElement>) => {
+    if (event.target !== dialogRef.current || !openedAsModalRef.current) return
+    if (backdrop === 'static') {
+      triggerStaticBounce()
+      return
+    }
+    close()
+  }
+
+  return { close, dialogRef, forkedRef, handleBackdropClick, handleCancel, hiding, staticBounce }
+}