@chassis-ui/react 0.0.0-20260831090525

package/src/components/placeholder/Placeholder.tsx

@@ -0,0 +1,178 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import { ContextColor, ContextStyle } from '../../types'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+
+type PlaceholderAlign = 'start' | 'center' | 'end'
+
+type PlaceholderOwnProps<C extends ElementType> = {
+  /**
+   * Set the horizontal alignment. Only applies when `src` is set.
+   */
+  align?: PlaceholderAlign
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Sets the color of the generated placeholder graphic to one of Chassis context colors. Has no
+   * effect when `src` is set.
+   */
+  color?: ContextColor
+  /**
+   * Sets the variant of the generated placeholder graphic to one of Chassis context styles. Has no
+   * effect when `src` is set.
+   */
+  variant?: Exclude<ContextStyle, 'basic' | 'outline'>
+  /**
+   * Component used for the root node when `src` is set. Either a string to use an HTML element
+   * or a component — e.g. a framework's own `Image` component. Its own props (`src`, `fill`,
+   * `priority`, etc.) are type-checked at the call site once passed here.
+   */
+  component?: C
+  /**
+   * Make the image responsive, so it never grows larger than its parent. Only applies when `src`
+   * is set.
+   */
+  fluid?: boolean
+  /**
+   * Placeholder height.
+   */
+  height?: number | string
+  /**
+   * Give the image a rounded border-radius. Only applies when `src` is set.
+   */
+  rounded?: boolean
+  /**
+   * Renders a real image instead of the generated placeholder graphic, e.g. a default asset or a
+   * `placehold.co` URL.
+   */
+  src?: string
+  /**
+   * Text shown in the generated placeholder graphic. Defaults to `{width}x{height}`. Pass `false`
+   * to hide it. Has no effect when `src` is set.
+   */
+  text?: string | false
+  /**
+   * Give the image a thumbnail appearance (padding, background, border, box-shadow). Only
+   * applies when `src` is set.
+   */
+  thumbnail?: boolean
+  /**
+   * Accessible title for the generated placeholder graphic, rendered as an SVG `<title>`. Pass
+   * `false` to hide it. Has no effect when `src` is set.
+   *
+   * @default 'Placeholder'
+   */
+  title?: string | false
+  /**
+   * Placeholder width.
+   */
+  width?: number | string
+}
+
+export type PlaceholderProps<C extends ElementType = 'img'> = PolymorphicComponentProps<
+  C,
+  PlaceholderOwnProps<C>
+>
+
+type PlaceholderComponent = (<C extends ElementType = 'img'>(
+  props: PlaceholderProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+const alignClassNames = (align: PlaceholderAlign | undefined) => [
+  align === 'start' || align === 'end' ? `float-${align}` : null,
+  align === 'center' ? 'd-block mx-auto' : null
+]
+
+function PlaceholderRender<C extends ElementType = 'img'>(
+  {
+    align,
+    alt,
+    className,
+    color,
+    component,
+    fluid,
+    height,
+    rounded,
+    src,
+    text,
+    thumbnail,
+    title = 'Placeholder',
+    variant,
+    width,
+    ...rest
+  }: PlaceholderProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const showTitle = title !== false
+  const displayText =
+    text === false
+      ? undefined
+      : (text ?? (width !== undefined && height !== undefined ? `${width}x${height}` : undefined))
+  const showText = displayText !== undefined
+  const label =
+    [showTitle && title, showText && displayText].filter(Boolean).join(': ') || undefined
+
+  if (src) {
+    const Component = component ?? 'img'
+    const _className = classNames(
+      { image: fluid || thumbnail, fluid, rounded, thumbnail },
+      alignClassNames(align),
+      className
+    )
+
+    return (
+      <Component
+        src={src}
+        width={width}
+        height={height}
+        alt={alt ?? label ?? ''}
+        className={_className}
+        {...rest}
+        ref={ref}
+      />
+    )
+  }
+
+  const _className = classNames(
+    'image',
+    { context: Boolean(color || variant) },
+    color,
+    variant ? variant : 'bg-evident',
+    'fg-subtle',
+    className
+  )
+
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={width}
+      height={height}
+      aria-label={label}
+      aria-hidden={label ? undefined : true}
+      className={_className}
+      preserveAspectRatio="xMidYMid slice"
+      role={label ? 'img' : undefined}
+      {...rest}
+      ref={ref as PolymorphicRef<'svg'>}
+    >
+      {showTitle && <title>{title}</title>}
+      {showText && (
+        <text dy=".3em" fill="currentColor" textAnchor="middle" x="50%" y="50%">
+          {displayText}
+        </text>
+      )}
+    </svg>
+  )
+}
+
+export const Placeholder = createPolymorphicComponent<PlaceholderComponent>(
+  PlaceholderRender as ForwardRefRenderFunction<Element, PlaceholderProps<ElementType>>,
+  'Placeholder'
+)

package/src/components/placeholder/index.ts

@@ -0,0 +1,2 @@
+export { Placeholder } from './Placeholder'
+export type { PlaceholderProps } from './Placeholder'

package/src/components/popover/Popover.tsx

@@ -0,0 +1,243 @@
+import React, {
+  FC,
+  HTMLAttributes,
+  ReactElement,
+  ReactNode,
+  RefObject,
+  useEffect,
+  useRef
+} from 'react'
+import { createPortal } from 'react-dom'
+import classNames from 'classnames'
+import { mergeProps, useDialog, useOverlayPosition, useOverlayTrigger } from 'react-aria'
+import { useOverlayTriggerState } from 'react-stately'
+import { Transition } from 'react-transition-group'
+
+import { getOverlayArrowStyle, getOverlayTransitionClass, useFloatingOverlay } from '../../hooks'
+import { Placement, resolveDataPlacement, toAriaPlacement } from '../../utils/overlayPlacement'
+
+interface PopoverPanelProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'content'> {
+  arrowProps: HTMLAttributes<HTMLDivElement>
+  content: ReactNode | string
+  overlayRef: RefObject<HTMLDivElement>
+  overlayTriggerProps: HTMLAttributes<HTMLDivElement>
+  title?: ReactNode | string
+}
+
+// A distinct component (rather than inline JSX from the `Transition` render prop) so
+// `useDialog`'s own mount-focus effect — which only fires on this component's mount, not on
+// `overlayRef.current` merely becoming non-null — actually runs each time the popover opens.
+// `Transition`'s `unmountOnExit` genuinely unmounts and remounts this component on every
+// open, giving `useDialog` a fresh mount each time.
+const PopoverPanel = ({
+  arrowProps,
+  content,
+  overlayRef,
+  overlayTriggerProps,
+  title,
+  ...rest
+}: PopoverPanelProps) => {
+  const { dialogProps, titleProps } = useDialog({}, overlayRef)
+
+  return (
+    <div {...mergeProps(overlayTriggerProps, dialogProps, rest)} ref={overlayRef}>
+      <div className="popover-arrow" {...arrowProps} style={getOverlayArrowStyle(arrowProps)}></div>
+      {title && (
+        <div className="popover-header" {...titleProps}>
+          {title}
+        </div>
+      )}
+      <div className="popover-body">{content}</div>
+    </div>
+  )
+}
+
+export interface PopoverProps extends Pick<
+  HTMLAttributes<HTMLDivElement>,
+  'aria-label' | 'aria-labelledby'
+> {
+  children: ReactElement
+  /**
+   * Content node for your component.
+   */
+  content: ReactNode | string
+  /**
+   * Offset of the popover 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
+  /**
+   * Title node for your component.
+   */
+  title?: ReactNode | string
+  /**
+   * Describes the preferred placement of your component. Chassis will flip it to keep it in
+   * view.
+   */
+  placement?: Placement
+  /**
+   * Toggle the visibility of popover component.
+   */
+  visible?: boolean
+}
+
+export const Popover: FC<PopoverProps> = ({
+  children,
+  content,
+  placement = 'right',
+  offset: offsetProp = [0, 8],
+  onHide,
+  onShow,
+  title,
+  visible,
+  ...rest
+}) => {
+  const arrowRef = useRef<HTMLDivElement>(null)
+  const triggerRef = useRef<HTMLElement | null>(null)
+  const floatingRef = useRef<HTMLDivElement>(null)
+
+  const state = useOverlayTriggerState({ defaultOpen: !!visible })
+  const {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    triggerProps: { onPress: _onPress, ...triggerProps },
+    overlayProps: overlayTriggerProps
+  } = useOverlayTrigger({ type: 'dialog' }, state, triggerRef)
+
+  const portalContainer = useFloatingOverlay({
+    close: state.close,
+    isOpen: state.isOpen,
+    open: state.open,
+    onHide,
+    onShow,
+    triggerRef,
+    visible
+  })
+
+  // Escape should always close the popover, regardless of where focus currently is — a
+  // mouse-opened popover leaves focus on the trigger, not inside the panel. Mirrors
+  // `Menu.tsx`'s own window-level Escape handling. `onExited` below already returns focus to the
+  // trigger once the exit transition finishes, so this doesn't need to do that itself.
+  useEffect(() => {
+    if (!state.isOpen) return undefined
+
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape') return
+      state.close()
+    }
+
+    window.addEventListener('keydown', handleEscape)
+    return () => window.removeEventListener('keydown', handleEscape)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [state.isOpen, state.close])
+
+  // Deferred so the click that opened the popover doesn't immediately close it again — mirrors
+  // `Menu.tsx`'s own outside-click handling.
+  useEffect(() => {
+    if (!state.isOpen) return undefined
+
+    const handleDismiss = (event: MouseEvent) => {
+      const target = event.target as Node
+      if (triggerRef.current?.contains(target)) return
+      if (floatingRef.current?.contains(target)) return
+      state.close()
+    }
+
+    const id = window.setTimeout(() => {
+      window.addEventListener('click', handleDismiss)
+    })
+
+    return () => {
+      window.clearTimeout(id)
+      window.removeEventListener('click', handleDismiss)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [state.isOpen, state.close])
+
+  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,
+    // `useOverlayPosition` closes on any window scroll via a backward-compat `WeakMap` that
+    // `useOverlayTrigger` populates for `triggerRef.current` above. Passing `null` opts out so
+    // the popover repositions with its trigger instead of vanishing — matching
+    // `Autocomplete`/`Combobox`, neither of which is wired into that map.
+    onClose: null
+  })
+
+  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,
+        onClick: (event: React.MouseEvent) => {
+          children.props.onClick?.(event)
+          state.toggle()
+        }
+      })}
+      {typeof window !== 'undefined' &&
+        createPortal(
+          <Transition
+            in={state.isOpen}
+            mountOnEnter
+            nodeRef={floatingRef}
+            onExited={() => {
+              const trigger = triggerRef.current
+              if (trigger && document.contains(trigger)) {
+                trigger.focus()
+              }
+            }}
+            timeout={{
+              enter: 0,
+              exit: 200
+            }}
+            unmountOnExit
+          >
+            {(transitionState) => {
+              const transitionClass = getOverlayTransitionClass(transitionState)
+              return (
+                <PopoverPanel
+                  className={classNames('popover cx-popover-auto', transitionClass)}
+                  data-cx-placement={placementAttr}
+                  style={floatingStyle}
+                  overlayTriggerProps={overlayTriggerProps}
+                  overlayRef={floatingRef}
+                  arrowProps={arrowProps}
+                  title={title}
+                  content={content}
+                  {...rest}
+                />
+              )
+            }}
+          </Transition>,
+          portalContainer ?? document.body
+        )}
+    </>
+  )
+}
+
+Popover.displayName = 'Popover'

package/src/components/popover/index.ts

@@ -0,0 +1,2 @@
+export { Popover } from './Popover'
+export type { PopoverProps } from './Popover'

package/src/components/progress/Progress.tsx

@@ -0,0 +1,154 @@
+import React, {
+  CSSProperties,
+  ElementType,
+  ForwardRefRenderFunction,
+  ReactElement,
+  ReactNode,
+  useId
+} from 'react'
+import classNames from 'classnames'
+
+import { ContextColor } from '../../types'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+import { ProgressBar } from './ProgressBar'
+
+type ProgressStyle = CSSProperties & {
+  '--cx-height'?: string
+}
+
+type ProgressOwnProps<C extends ElementType> = {
+  /**
+   * Use to animate the stripes right to left via CSS3 animations.
+   */
+  animated?: boolean
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Sets the color of the component to one of Chassis context colors.
+   */
+  color?: ContextColor
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C
+  /**
+   * Sets the height of the component, via the `--cx-height` custom property. If you set that
+   * value the inner bar (and the striped pattern's tile size) automatically resizes accordingly.
+   */
+  height?: number
+  /**
+   * Shows the current value as text inside the bar, independently of `showValue` — combine both
+   * to get a `label` + `showValue` caption above the bar alongside an `inlineValue` reading
+   * inside it.
+   */
+  inlineValue?: boolean
+  /**
+   * A text label describing the progress. Rendered in a caption row above the bar. Also used as
+   * the default accessible name when no `aria-label`/`aria-labelledby` is supplied.
+   */
+  label?: ReactNode
+  /**
+   * Shows the current value as text in the caption row above the bar, alongside `label` when
+   * both are set, or alone otherwise. Use `inlineValue` to show it inside the bar instead.
+   */
+  showValue?: boolean
+  /**
+   * Adds a diagonal stripe pattern over the bar's background.
+   */
+  striped?: boolean
+  /**
+   * The percent to progress the ProgressBar (out of 100).
+   */
+  value?: number
+}
+
+export type ProgressProps<C extends ElementType = 'div'> = PolymorphicComponentProps<
+  C,
+  ProgressOwnProps<C>
+>
+
+type ProgressComponent = (<C extends ElementType = 'div'>(
+  props: ProgressProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function ProgressRender<C extends ElementType = 'div'>(
+  {
+    'aria-label': ariaLabel,
+    animated,
+    children,
+    className,
+    color,
+    component,
+    height,
+    inlineValue,
+    label,
+    showValue,
+    striped,
+    style,
+    value = 0,
+    ...rest
+  }: ProgressProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'div'
+  const _className = classNames('progress', className)
+  const clampedValue = Math.min(100, Math.max(0, value))
+
+  const barChildren =
+    children !== undefined ? children : inlineValue ? `${clampedValue}%` : undefined
+  const hasCaption = Boolean(label || showValue)
+
+  const labelId = useId()
+  const isNodeLabel = label != null && typeof label !== 'string'
+
+  const _style: ProgressStyle = { ...style }
+  if (height !== undefined) _style['--cx-height'] = `${height}px`
+
+  const progressElement = (
+    <Component
+      {...rest}
+      className={_className}
+      role="progressbar"
+      aria-valuenow={clampedValue}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-label={ariaLabel ?? (typeof label === 'string' ? label : undefined)}
+      aria-labelledby={!ariaLabel && isNodeLabel ? labelId : undefined}
+      style={_style}
+      ref={ref}
+    >
+      <ProgressBar animated={animated} color={color} striped={striped} value={clampedValue}>
+        {barChildren}
+      </ProgressBar>
+    </Component>
+  )
+
+  if (!hasCaption) return progressElement
+
+  return (
+    <div className="d-flex flex-column gap-xsmall">
+      <div
+        className={classNames('d-flex', label ? 'justify-content-between' : 'justify-content-end')}
+      >
+        {label ? (
+          <span className="font-strong" id={isNodeLabel ? labelId : undefined}>
+            {label}
+          </span>
+        ) : null}
+        {showValue ? <span className="font-strong">{clampedValue}%</span> : null}
+      </div>
+      {progressElement}
+    </div>
+  )
+}
+
+export const Progress = createPolymorphicComponent<ProgressComponent>(
+  ProgressRender as ForwardRefRenderFunction<Element, ProgressProps<ElementType>>,
+  'Progress'
+)

package/src/components/progress/ProgressBar.tsx

@@ -0,0 +1,88 @@
+import React, { ElementType, ForwardRefRenderFunction, ReactElement } from 'react'
+import classNames from 'classnames'
+
+import { ContextColor } from '../../types'
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+
+type ProgressBarOwnProps<C extends ElementType> = {
+  /**
+   * Use to animate the stripes right to left via CSS3 animations.
+   */
+  animated?: boolean
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Sets the color of the component to one of Chassis context colors.
+   */
+  color?: ContextColor
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C
+  /**
+   * Adds a diagonal stripe pattern over the bar's background.
+   */
+  striped?: boolean
+  /**
+   * The percent to progress the ProgressBar.
+   */
+  value?: number
+}
+
+export type ProgressBarProps<C extends ElementType = 'div'> = PolymorphicComponentProps<
+  C,
+  ProgressBarOwnProps<C>
+>
+
+type ProgressBarComponent = (<C extends ElementType = 'div'>(
+  props: ProgressBarProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function ProgressBarRender<C extends ElementType = 'div'>(
+  {
+    children,
+    animated,
+    className,
+    color,
+    component,
+    striped,
+    style,
+    value = 0,
+    ...rest
+  }: ProgressBarProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'div'
+  const clampedValue = Math.min(100, Math.max(0, value))
+  const _className = classNames(
+    'progress-bar',
+    color && `bg-${color} fg-contrast`,
+    {
+      striped,
+      animated
+    },
+    className
+  )
+
+  return (
+    <Component
+      {...rest}
+      className={_className}
+      style={{ width: `${clampedValue}%`, ...style }}
+      ref={ref}
+    >
+      <span className="mx-2xsmall">{children}</span>
+    </Component>
+  )
+}
+
+export const ProgressBar = createPolymorphicComponent<ProgressBarComponent>(
+  ProgressBarRender as ForwardRefRenderFunction<Element, ProgressBarProps<ElementType>>,
+  'ProgressBar'
+)

package/src/components/progress/index.ts

@@ -0,0 +1,4 @@
+export { Progress } from './Progress'
+export type { ProgressProps } from './Progress'
+export { ProgressBar } from './ProgressBar'
+export type { ProgressBarProps } from './ProgressBar'