@chassis-ui/react 0.1.0 → 0.1.1

package/src/hooks/usePagination.ts

@@ -22,8 +22,12 @@ export interface UsePaginationOptions {
 }
 
 export interface UsePaginationResult<T extends HTMLElement = HTMLButtonElement> {
-  prevRef: RefObject<T>
-  nextRef: RefObject<T>
+  // `RefObject<T | null>`, not `RefObject<T>`: these come from `useRef<T>(null)`, so `.current`
+  // really is null before mount (and whenever the control isn't rendered — a hand-composed
+  // pagination may omit Prev/Next entirely). Declaring the non-null form let a consumer write
+  // `prevRef.current.focus()` with no type error and crash at runtime.
+  prevRef: RefObject<T | null>
+  nextRef: RefObject<T | null>
   handlePrevClick: (event: MouseEvent<T>) => void
   handleNextClick: (event: MouseEvent<T>) => void
 }

package/src/index.ts

@@ -24,6 +24,16 @@ import { Breadcrumb, BreadcrumbItem } from './components/breadcrumb'
 import { Button } from './components/button'
 import { ButtonGroup, ButtonToolbar } from './components/button-group'
 import { Calendar, RangeCalendar } from './components/calendar'
+import {
+  DataGrid,
+  DataGridBody,
+  DataGridCell,
+  DataGridColumn,
+  DataGridHeader,
+  DataGridRow,
+  DataGridSelectAllCell,
+  DataGridSelectionCell
+} from './components/datagrid'
 import {
   Card,
   CardBody,
@@ -145,6 +155,14 @@ export {
   ButtonToolbar,
   Calendar,
   RangeCalendar,
+  DataGrid,
+  DataGridBody,
+  DataGridCell,
+  DataGridColumn,
+  DataGridHeader,
+  DataGridRow,
+  DataGridSelectAllCell,
+  DataGridSelectionCell,
   Card,
   CardBody,
   CardFooter,
@@ -274,3 +292,211 @@ export {
   useToast,
   Tooltip
 }
+
+// Type-only public surface. Kept as `export type ... from` re-exports (the same shape
+// `src/hooks/index.ts` uses) rather than the import-then-name-in-the-export-block pattern the
+// value exports above follow — 164 type names would otherwise need 164 more import lines for no
+// added clarity. Every component folder's barrel already exports its own prop types; this block
+// is what actually makes them reachable as `@chassis-ui/react` imports, so a consumer can write
+// `interface MyButtonProps extends ButtonProps` instead of re-deriving it with
+// `ComponentProps<typeof Button>`.
+export type {
+  AccordionBodyProps,
+  AccordionHeaderProps,
+  AccordionItemDef,
+  AccordionItemProps,
+  AccordionProps
+} from './components/accordion'
+export type {
+  AutocompleteGroupProps,
+  AutocompleteItemProps,
+  AutocompleteProps
+} from './components/autocomplete'
+export type {
+  AvatarImageProps,
+  AvatarProps,
+  AvatarStackItemDef,
+  AvatarStackProps
+} from './components/avatar'
+export type { BadgeProps } from './components/badge'
+export type {
+  BreadcrumbItemDef,
+  BreadcrumbItemProps,
+  BreadcrumbProps
+} from './components/breadcrumb'
+export type { ButtonProps } from './components/button'
+export type { ButtonGroupProps, ButtonToolbarProps } from './components/button-group'
+export type {
+  CalendarLabels,
+  CalendarMultipleProps,
+  CalendarProps,
+  CalendarSingleProps,
+  DateRangePreset,
+  RangeCalendarProps
+} from './components/calendar'
+export type {
+  CardBodyProps,
+  CardFooterProps,
+  CardGroupProps,
+  CardHeaderProps,
+  CardImageOverlayProps,
+  CardImageProps,
+  CardLinkProps,
+  CardProps,
+  CardSubtitleProps,
+  CardTextProps,
+  CardTitleProps
+} from './components/card'
+export type {
+  CarouselControlNextProps,
+  CarouselControlPrevProps,
+  CarouselEnds,
+  CarouselIndicatorsProps,
+  CarouselInnerProps,
+  CarouselItemProps,
+  CarouselOverlayProps,
+  CarouselPlayPauseProps,
+  CarouselProps,
+  CarouselSlideDetail,
+  CarouselTransition
+} from './components/carousel'
+export type { ButtonObject, CheckboxGroupProps, CheckboxProps } from './components/checkbox'
+export type { ChipProps } from './components/chip'
+export type { ChipInputProps } from './components/chip-input'
+export type { CloseButtonProps } from './components/close-button'
+export type { CollapseProps } from './components/collapse'
+export type { ColorInputProps } from './components/color-input'
+export type { ComboboxGroupProps, ComboboxItemProps, ComboboxProps } from './components/combobox'
+export type {
+  DatePickerMultipleProps,
+  DatePickerProps,
+  DatePickerSingleProps,
+  DateRangePickerProps
+} from './components/datepicker'
+export type {
+  DrawerBodyProps,
+  DrawerFooterProps,
+  DrawerHeaderProps,
+  DrawerProps,
+  DrawerTitleProps
+} from './components/drawer'
+export type { FileInputProps } from './components/file-input'
+export type { FlexProps } from './components/flex'
+export type { FloatingInputProps } from './components/floating-input'
+export type { FormFeedbackProps, FormHelpProps, FormLabelProps, FormProps } from './components/form'
+export type { FormFieldProps } from './components/form-field'
+export type {
+  ColProps,
+  ContainerProps,
+  GridItemLayout,
+  GridItemProps,
+  GridProps,
+  RowProps
+} from './components/grid'
+export type { IconProps } from './components/icon'
+export type { InputAdornProps } from './components/input-adorn'
+export type { InputGroupAddonProps, InputGroupProps } from './components/input-group'
+export type { LinkProps } from './components/link'
+export type { ListItemDef, ListItemProps, ListProps } from './components/list'
+export type {
+  MenuAutoClose,
+  MenuDividerDef,
+  MenuDividerProps,
+  MenuFocusStrategy,
+  MenuHeaderDef,
+  MenuHeaderProps,
+  MenuItemDef,
+  MenuItemProps,
+  MenuItemsDef,
+  MenuListProps,
+  MenuProps,
+  MenuSubmenuBackProps,
+  MenuSubmenuProps,
+  MenuTextProps,
+  MenuToggleProps
+} from './components/menu'
+export type {
+  ModalBodyProps,
+  ModalFooterProps,
+  ModalHeaderProps,
+  ModalProps,
+  ModalTitleProps
+} from './components/modal'
+export type { NavItemDef, NavLinkProps, NavProps, NavTitleProps } from './components/nav'
+export type {
+  NavbarBrandProps,
+  NavbarNavProps,
+  NavbarProps,
+  NavbarTextProps,
+  NavbarTogglerProps
+} from './components/navbar'
+export type {
+  NotificationContent,
+  NotificationIconProps,
+  NotificationProps,
+  NotificationStackProps,
+  NotificationTextProps,
+  NotificationTitleProps
+} from './components/notification'
+export type { OtpInputProps } from './components/otp-input'
+export type { PaginationItemProps, PaginationProps } from './components/pagination'
+export type { PasswordStrengthProps } from './components/password-strength'
+export type { PlaceholderProps } from './components/placeholder'
+export type { PopoverProps } from './components/popover'
+export type { ProgressBarProps, ProgressProps } from './components/progress'
+export type { RadioGroupProps, RadioProps } from './components/radio'
+export type { RangeInputProps } from './components/range-input'
+export type { SelectOptionDef, SelectProps } from './components/select'
+export type { SkeletonLoaderProps, SkeletonProps } from './components/skeleton'
+export type { SpinnerProps } from './components/spinner'
+export type { StackProps } from './components/stack'
+export type { StepperItemDef, StepperItemProps, StepperProps } from './components/stepper'
+export type { SwitchProps } from './components/switch'
+export type {
+  TableBodyProps,
+  TableCellProps,
+  TableColumnProps,
+  TableHeaderProps,
+  TableProps,
+  TableRowProps
+} from './components/table'
+export type { TabListProps, TabPanelProps, TabProps, TabsProps } from './components/tabs'
+export type { TextInputProps } from './components/text-input'
+export type { TextareaProps } from './components/textarea'
+export type {
+  ToastBodyProps,
+  ToastContent,
+  ToastFooterProps,
+  ToastHeaderProps,
+  ToastIconProps,
+  ToastProps,
+  ToasterProps
+} from './components/toast'
+export type { TooltipProps } from './components/tooltip'
+
+// Cross-cutting types that aren't owned by any one component folder: the scales and vocabularies
+// the prop types above are built from. `types.ts`'s `FontFamily`/`FontWeight`/`FontSize`/
+// `Placements`/`TextColor`/`Triggers` are deliberately not re-exported — nothing in this package
+// references them, so publishing them would commit this package's public API to types it doesn't
+// actually use.
+export type {
+  Breakpoint,
+  ContextColor,
+  ContextStyle,
+  ExtendedSizing,
+  Shapes,
+  Sizing,
+  Spacing
+} from './types'
+// Backs the `placement` prop on `Menu`/`MenuSubmenu`/`Popover`/`Tooltip`. Lives in `utils/`
+// rather than a component barrel because all four share it.
+export type { Placement } from './utils/overlayPlacement'
+// Result types for the five hooks exported as values above. Mirrors what `hooks/index.ts` itself
+// exposes for them — the other hooks in that folder stay internal, so their types do too.
+export type {
+  UseDrawerResult,
+  UseModalResult,
+  UseNotificationResult,
+  UsePaginationResult,
+  UseToastResult
+} from './hooks'

package/src/types.ts

@@ -1,7 +1,7 @@
 /**
  * Breakpoints
  */
-export type Breakpoint = 'small' | 'medium' | 'large' | 'xlarge' | '2xlarge'
+export type Breakpoint = 'sm' | 'md' | 'lg' | 'xl' | '2xl'
 
 /**
  * Context colors
@@ -27,12 +27,12 @@ export type ContextStyle = 'basic' | 'solid' | 'outline' | 'smooth'
 /**
  * Component sizes
  */
-export type Sizing = 'small' | 'medium' | 'large'
+export type Sizing = 'sm' | 'md' | 'lg'
 
 /**
  * Extended sizes
  */
-export type ExtendedSizing = '2xsmall' | 'xsmall' | Sizing | 'xlarge' | '2xlarge'
+export type ExtendedSizing = '2xs' | 'xs' | Sizing | 'xl' | '2xl'
 
 /**
  * Spacing values. `SPACING` is the runtime source of truth — `Spacing` is derived from it so the
@@ -41,19 +41,19 @@ export type ExtendedSizing = '2xsmall' | 'xsmall' | Sizing | 'xlarge' | '2xlarge
  */
 export const SPACING = [
   'zero',
-  '4xsmall',
-  '3xsmall',
-  '2xsmall',
-  'xsmall',
-  'small',
-  'medium',
-  'large',
-  'xlarge',
-  '2xlarge',
-  '3xlarge',
-  '4xlarge',
-  '5xlarge',
-  '6xlarge'
+  '4xs',
+  '3xs',
+  '2xs',
+  'xs',
+  'sm',
+  'md',
+  'lg',
+  'xl',
+  '2xl',
+  '3xl',
+  '4xl',
+  '5xl',
+  '6xl'
 ] as const
 
 export type Spacing = (typeof SPACING)[number]
@@ -72,16 +72,16 @@ export type FontWeight = 'elegant' | 'normal' | 'strong' | 'mass'
  * Font sizes
  */
 export type FontSize =
-  | '2xsmall'
-  | 'xsmall'
-  | 'small'
-  | 'medium'
-  | 'large'
-  | 'xlarge'
-  | '2xlarge'
-  | '3xlarge'
-  | '4xlarge'
-  | '5xlarge'
+  | '2xs'
+  | 'xs'
+  | 'sm'
+  | 'md'
+  | 'lg'
+  | 'xl'
+  | '2xl'
+  | '3xl'
+  | '4xl'
+  | '5xl'
 
 /**
  * Component placements

package/src/utils/breakpoints.ts

@@ -2,7 +2,7 @@ import { Breakpoint } from '../types'
 
 // Mobile-first ascending order. Every responsive layout prop (`Flex`/`Stack`/`Row`/`Col`/
 // `Skeleton`'s `responsive`) keys its overrides by these literal chassis-css breakpoint names.
-export const BREAKPOINTS: Breakpoint[] = ['small', 'medium', 'large', 'xlarge', '2xlarge']
+export const BREAKPOINTS: Breakpoint[] = ['sm', 'md', 'lg', 'xl', '2xl']
 
 // A column/width span: a track count, `'auto'` for a natural-width track, or `true` for the bare
 // (no explicit width) case. Shared by `Col` and `Skeleton`, both of which map it to the same

package/src/utils/devWarning.ts

@@ -0,0 +1,58 @@
+// Development-only misuse warnings, in one place so every component reports misuse the same way
+// and none of it reaches a consumer's production bundle.
+//
+// Two problems this fixes over calling `console.warn` directly, which is what every call site used
+// to do:
+//
+// 1. **They fired in production.** Nothing in this package guarded on `NODE_ENV`, so every
+//    `console.warn` ran for end users of a consuming app. `process.env.NODE_ENV` is the idiom
+//    bundlers (Vite, webpack, Turbopack, Rollup) replace with a literal, so in a production build
+//    `IS_DEV` folds to `false` and no warning is ever emitted. Relying on that substitution adds
+//    no new constraint: `react-dom` — a peer dependency, so always present — already requires
+//    exactly the same replacement.
+// 2. **They repeated.** Most call sites warn during render, so a warning re-fired on every
+//    re-render, and twice per render under StrictMode's double-invoke. De-duplicating on the
+//    message means a misuse is reported once and stays readable in the console.
+//
+// What this does *not* do is strip the message strings from the bundle. Measured with esbuild
+// against the built `dist/index.js`: a `NODE_ENV=production` consumer bundle still contains them.
+// `tsdown` minifies this package's own output first (`minify: true`), collapsing each function to
+// a `IS_DEV && cond && ...` expression, and a consumer's minifier won't then inline that call to
+// discover its arguments are droppable. Building unminified would let them drop, at the cost of
+// shipping pretty-printed dist — not worth it for a few hundred gzipped bytes. The behavior that
+// mattered (nothing logged in production, nothing repeated in development) is the part that's
+// fixed; treat the strings as part of the bundle's fixed cost.
+const IS_DEV = process.env.NODE_ENV !== 'production'
+
+const warned = new Set<string>()
+
+/**
+ * Resets the de-duplication set. Test-only — the suite asserts on these warnings, and without a
+ * reset between tests the *second* test in a file to trigger the same message would see nothing.
+ * Called from a global `beforeEach` in `test/setup.ts`.
+ */
+export function resetDevWarnings(): void {
+  warned.clear()
+}
+
+/**
+ * Logs `message` once via `console.warn` when `condition` is true, in development builds only.
+ * Use for a recoverable misuse: the component still renders something sensible.
+ */
+export function devWarning(condition: boolean, message: string): void {
+  if (!IS_DEV) return
+  if (!condition || warned.has(message)) return
+  warned.add(message)
+  console.warn(message)
+}
+
+/**
+ * Logs `message` once via `console.error` when `condition` is true, in development builds only.
+ * Use for a misuse that leaves the component genuinely broken (e.g. a required prop missing).
+ */
+export function devError(condition: boolean, message: string): void {
+  if (!IS_DEV) return
+  if (!condition || warned.has(message)) return
+  warned.add(message)
+  console.error(message)
+}

package/src/utils/direction.ts

@@ -0,0 +1,14 @@
+/**
+ * Whether `element` renders right-to-left.
+ *
+ * Reads the *computed* direction rather than react-aria's `useLocale()`. The two are deliberately
+ * separate signals in this library (see the Internationalization docs page): `useLocale()` follows
+ * `I18nProvider`, and drives locale-dependent behavior like which calendar system to use;
+ * everything about visual layout — including which physical arrow key moves "forward" through a
+ * horizontally-laid-out control — follows the `dir` attribute, which is what `getComputedStyle`
+ * resolves here. A page can set one without the other, and for arrow-key navigation it's the
+ * rendered order the user sees that has to match.
+ */
+export function isRTL(element: Element): boolean {
+  return getComputedStyle(element).direction === 'rtl'
+}

package/src/utils/focusRedirect.ts

@@ -1,29 +1,23 @@
+import { suppressFocusRing } from './suppressFocusRingGlobally'
+
 // Safari shows a `:focus-visible` ring on an element focused via script even when the
 // interaction that triggered the script was a real pointer click — unlike Chromium/Firefox,
 // which correctly suppress it in that case. Force the ring off for a pointer-triggered redirect,
 // then let normal focus-visible behavior resume the next time this element is genuinely
 // (re)focused, e.g. via Tab.
+//
+// The suppress/restore cycle itself is `suppressFocusRing`'s, not reimplemented here: it owns the
+// re-entrancy guard that keeps a second call before the element blurs from capturing the
+// already-suppressed value as the one to restore (which left the ring off for good — reachable by
+// clicking twice at the same disabled end of a `ends="stop"` carousel). `boxShadow` is suppressed
+// alongside `outline` here, but not on the global pointerdown path, because a redirect can land
+// on an element whose ring is painted that way.
 export function focusRedirect(
   el: HTMLElement | null,
   viaPointer: boolean,
   focusOptions?: FocusOptions
 ): void {
   if (!el) return
-  if (!viaPointer) {
-    el.focus(focusOptions)
-    return
-  }
-  const prevOutline = el.style.outline
-  const prevBoxShadow = el.style.boxShadow
-  el.style.outline = 'none'
-  el.style.boxShadow = 'none'
+  if (viaPointer) suppressFocusRing(el, ['outline', 'boxShadow'])
   el.focus(focusOptions)
-  el.addEventListener(
-    'blur',
-    () => {
-      el.style.outline = prevOutline
-      el.style.boxShadow = prevBoxShadow
-    },
-    { once: true }
-  )
 }

package/src/utils/polymorphic.ts

@@ -3,12 +3,29 @@ import {
   ComponentPropsWithRef,
   ElementType,
   ForwardRefRenderFunction,
-  forwardRef
+  forwardRef,
+  Ref
 } from 'react'
 
 // 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>
+
 /**
  * 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

package/src/utils/suppressFocusRingGlobally.ts

@@ -20,10 +20,22 @@ 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).
-export function suppressFocusRing(el: HTMLElement): void {
+// 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
@@ -33,17 +45,20 @@ export function suppressFocusRing(el: HTMLElement): void {
   // 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.
+  // 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 prevOutline = el.style.outline
-  el.style.outline = 'none'
+  const restore = styles.map((style) => [style, el.style[style]] as const)
+  for (const [style] of restore) el.style[style] = 'none'
   el.addEventListener(
     'blur',
     () => {
-      el.style.outline = prevOutline
+      for (const [style, value] of restore) el.style[style] = value
       suppressed.delete(el)
     },
     { once: true }

package/src/utils/triggerElement.ts

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