@sanity/ui 3.1.13 → 4.0.0-beta.0

package/src/primitives/popover/Popover.tsx

@@ -0,0 +1,291 @@
+import {autoUpdate, type RootBoundary, useFloating} from '@floating-ui/react-dom'
+import {type MaxWidth, popover as popoverCss, type ResponsiveProp} from '@sanity/ui-css'
+import {AnimatePresence} from 'motion/react'
+import {
+  cloneElement,
+  type ForwardedRef,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+  use,
+  useCallback,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+} from 'react'
+
+import {Z_OFFSETS} from '../../core/constants'
+import {getElementRef} from '../../core/getElementRef'
+import type {Assign, Placement} from '../../core/types'
+import {usePrefersReducedMotion} from '../../hooks/usePrefersReducedMotion'
+import {BoundaryElementContext} from '../../utils/boundaryElement/BoundaryElementContext'
+import {Portal} from '../../utils/portal/Portal'
+import {useLayer} from '../layer/useLayer'
+import {
+  DEFAULT_FALLBACK_PLACEMENTS,
+  DEFAULT_POPOVER_DISTANCE,
+  DEFAULT_POPOVER_MARGINS,
+} from './constants'
+import {PopoverLayer, type PopoverLayerOwnProps, type PopoverLayerProps} from './PopoverLayer'
+import type {PopoverMargins, PopoverUpdateCallback} from './types'
+import {useMiddleware} from './useMiddleware'
+
+/** @public */
+export type PopoverOwnProps = Omit<PopoverLayerOwnProps, 'maxWidth'> & {
+  /** @beta */
+  __unstable_distance?: number
+  /**
+   * @beta
+   * @deprecated Will be removed in the next major version */
+  __unstable_margins?: PopoverMargins
+  /** @beta */
+  __unstable_shift?: number
+  /**
+   * @deprecated Will be removed in the next major version
+   */
+  arrow?: boolean
+  children?: ReactElement<{ref: ForwardedRef<HTMLElement>}>
+  /**
+   * When `true`, prevent overflow within the current boundary:
+   * - by flipping on its side axis
+   * - by resizing
+   *
+   * Note that:
+   * - setting `preventOverflow` to `true` also prevents overflow on its side axis
+   * - setting `matchReferenceWidth` to `true` also causes the popover to resize
+   *
+   * @defaultValue false
+   */
+  constrainSize?: boolean
+  content?: ReactNode
+  disabled?: boolean
+  fallbackPlacements?: Placement[]
+  floatingBoundary?: HTMLElement | null
+  /**
+   * When `true`, set the maximum width to match the reference element, and also prevent overflow within
+   * the current boundary by resizing.
+   *
+   * Note that setting `constrainSize` to `true` also causes the popover to resize
+   *
+   * @defaultValue false
+   */
+  matchReferenceWidth?: boolean
+  /**
+   * When true, blocks all pointer interaction with elements beneath the popover until closed.
+   *
+   * @beta
+   * @defaultValue false
+   */
+  modal?: boolean
+  open?: boolean
+  placement?: Placement
+  /**
+   * When 'flip' (default), the placement is determined from the initial placement and the
+   * fallback placements in order. Whichever fits in the viewport first.
+   *
+   * When 'autoPlacement', the initial placement and all fallback placements are evaluated
+   * and the placement with the most viewport space available.
+   *
+   * Option is only relevant if either `constrainSize` or `preventOverflow` is `true`
+   */
+  placementStrategy?: 'flip' | 'autoPlacement'
+  /** Whether or not to render the popover in a portal element. */
+  portal?: boolean | string
+  preventOverflow?: boolean
+  referenceBoundary?: HTMLElement | null
+  /**
+   * When defined, the popover will be positioned relative to this element.
+   * The children of the popover won't be rendered.
+   */
+  referenceElement?: HTMLElement | null
+  /** @beta */
+  updateRef?: Ref<PopoverUpdateCallback | undefined>
+  width?: ResponsiveProp<MaxWidth>
+}
+
+/** @public */
+export type PopoverElementType = 'div'
+
+/** @public */
+export type PopoverProps = Assign<PopoverLayerProps, PopoverOwnProps>
+
+function ViewportOverlay() {
+  const {zIndex} = useLayer()
+
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        inset: 0,
+        width: '100vw',
+        height: '100vh',
+        zIndex,
+      }}
+    />
+  )
+}
+
+/**
+ * The `Popover` component is used to display some content on top of another.
+ *
+ * @public
+ */
+export function Popover(props: PopoverProps): React.JSX.Element {
+  const {
+    // Remove `__unstable_margins` prop in next major version
+    __unstable_margins: _margins = DEFAULT_POPOVER_MARGINS,
+    __unstable_distance: distance = DEFAULT_POPOVER_DISTANCE,
+    __unstable_shift: shift = 0,
+    animate: _animate = false,
+    // Remove `arrow` prop in next major version
+    arrow: _arrow,
+    children: childProp,
+    className,
+    constrainSize = false,
+    content,
+    disabled,
+    fallbackPlacements: _fallbackPlacements,
+    matchReferenceWidth,
+    floatingBoundary: _floatingBoundary,
+    modal,
+    onActivate,
+    open,
+    overflow = 'hidden',
+    padding,
+    placement: placement = 'bottom',
+    placementStrategy = 'flip',
+    portal = true,
+    preventOverflow = true,
+    radius = 4,
+    ref: forwardedRef,
+    referenceBoundary: _referenceBoundary,
+    referenceElement,
+    shadow = 3,
+    width: widthProp = 'auto',
+    zOffset = Z_OFFSETS.popover,
+    updateRef,
+    ...rest
+  } = props
+  const fallbackPlacements =
+    _fallbackPlacements ?? DEFAULT_FALLBACK_PLACEMENTS[props.placement ?? 'bottom']
+  const floatingBoundary = _floatingBoundary ?? use(BoundaryElementContext)
+  const referenceBoundary = _referenceBoundary ?? use(BoundaryElementContext)
+
+  const prefersReducedMotion = usePrefersReducedMotion()
+  const animate = prefersReducedMotion ? false : _animate
+
+  const ref = useRef<HTMLDivElement | null>(null)
+
+  const rootBoundary: RootBoundary = 'viewport'
+
+  useImperativeHandle<HTMLDivElement | null, HTMLDivElement | null>(forwardedRef, () => ref.current)
+
+  // Keep track of reference element width (see `size` middleware below)
+  const referenceWidthRef = useRef<number>(undefined)
+
+  const middleware = useMiddleware({
+    animate,
+    constrainSize,
+    distance,
+    fallbackPlacements,
+    floatingBoundary,
+    matchReferenceWidth,
+    placement,
+    placementStrategy,
+    preventOverflow,
+    referenceBoundary,
+    referenceWidthRef,
+    rootBoundary,
+    shift,
+  })
+
+  const {x, y, middlewareData, refs, strategy, update} = useFloating({
+    middleware,
+    placement: placement,
+    whileElementsMounted: autoUpdate,
+    elements: referenceElement
+      ? {
+          reference: referenceElement,
+        }
+      : undefined,
+  })
+
+  const referenceHidden = middlewareData.hide?.referenceHidden
+
+  const originX = middlewareData['@sanity/ui/origin']?.originX
+  const originY = middlewareData['@sanity/ui/origin']?.originY
+
+  const setFloating = useCallback(
+    (node: HTMLDivElement | null) => {
+      ref.current = node
+      refs.setFloating(node)
+    },
+    [refs],
+  )
+
+  // If there's a child then we need to set the reference element to the cloned child ref
+  // and if child changes we make sure to update or remove the reference element.
+  useImperativeHandle(childProp ? getElementRef(childProp) : null, () => refs.reference.current)
+
+  const child = useMemo(() => {
+    // If a reference element is defined, we don't need to clone the child
+    if (referenceElement) return childProp
+
+    if (!childProp) return null
+
+    return cloneElement(childProp, {ref: refs.setReference})
+  }, [childProp, referenceElement, refs.setReference])
+
+  useImperativeHandle(updateRef, () => update, [update])
+
+  if (disabled) {
+    return childProp || <></>
+  }
+
+  const node = (
+    <>
+      {/* Optional transparent blocking overlay at the top-most z-index layer. Must be positioned
+      before the below popover card. */}
+      {modal && <ViewportOverlay />}
+
+      <PopoverLayer
+        {...rest}
+        ref={setFloating}
+        animate={animate}
+        className={popoverCss({className})}
+        hidden={referenceHidden}
+        maxWidth={widthProp}
+        originX={originX}
+        originY={originY}
+        overflow={overflow}
+        padding={padding}
+        radius={radius}
+        shadow={shadow}
+        strategy={strategy}
+        x={x}
+        y={y}
+        zOffset={zOffset}
+      >
+        {content}
+      </PopoverLayer>
+    </>
+  )
+
+  let children = open ? node : null
+
+  if (open && portal) {
+    children = (
+      <Portal __unstable_name={typeof portal === 'string' ? portal : undefined}>{node}</Portal>
+    )
+  }
+
+  return (
+    <>
+      {/* the popover */}
+      {animate ? <AnimatePresence>{children}</AnimatePresence> : children}
+
+      {/* the referred element */}
+      {child}
+    </>
+  )
+}

package/src/primitives/popover/PopoverLayer.tsx

@@ -0,0 +1,101 @@
+import type {Strategy} from '@floating-ui/react-dom'
+import {popover_card} from '@sanity/ui-css'
+import {type HTMLMotionProps, motion} from 'motion/react'
+import {useMemo} from 'react'
+
+import {POPOVER_MOTION_PROPS} from '../../core/constants'
+import type {Assign} from '../../core/types'
+import {Flex} from '../flex/Flex'
+import {Layer, type LayerOwnProps} from '../layer/Layer'
+
+/** @internal */
+export interface PopoverLayerOwnProps extends LayerOwnProps {
+  /**
+   * Whether the popover should animate in and out.
+   *
+   * @beta
+   * @defaultValue false
+   */
+  animate?: boolean
+  children?: React.ReactNode
+  originX?: number
+  originY?: number
+  referenceWidth?: number
+  strategy?: Strategy
+  x?: number
+  y?: number
+}
+
+/** @public */
+export type PopoverLayerProps = Assign<HTMLMotionProps<'div'>, PopoverLayerOwnProps>
+
+/** @internal */
+export function PopoverLayer(props: PopoverLayerProps): React.JSX.Element {
+  const {
+    animate = false,
+    children,
+    maxWidth,
+    padding,
+    originX,
+    originY,
+    overflow,
+    radius,
+    referenceWidth,
+    shadow,
+    strategy,
+    style,
+    tone = 'inherit',
+    x,
+    y,
+    ...rest
+  } = props
+
+  const rootStyle = useMemo(
+    () => ({
+      left: x,
+      originX,
+      originY,
+      top: y,
+      width: referenceWidth,
+      willChange: animate ? 'transform' : undefined,
+      ...style,
+    }),
+    [animate, originX, originY, referenceWidth, style, x, y],
+  )
+
+  return (
+    <Layer
+      className={popover_card()}
+      data-ui="Popover"
+      {...rest}
+      animate={animate ? ['visible', 'scaleIn'] : undefined}
+      as={motion.div}
+      display="flex"
+      exit={animate ? ['hidden', 'scaleOut'] : undefined}
+      flexDirection="column"
+      initial={animate ? ['hidden', 'initial'] : undefined}
+      position={strategy}
+      radius={radius}
+      shadow={shadow}
+      sizing="border"
+      style={rootStyle}
+      tone={tone}
+      transition={POPOVER_MOTION_PROPS.transition}
+      variants={POPOVER_MOTION_PROPS.card}
+    >
+      <Flex
+        data-ui="Popover__wrapper"
+        direction="column"
+        flex={1}
+        maxWidth={maxWidth}
+        overflow={overflow}
+        radius={radius}
+        tabIndex={-1}
+      >
+        <Flex direction="column" flex={1} padding={padding}>
+          {children}
+        </Flex>
+      </Flex>
+    </Layer>
+  )
+}

package/src/primitives/popover/__workshop__/AlignedStory.tsx

@@ -0,0 +1,76 @@
+import {EllipsisVerticalIcon} from '@sanity/icons'
+import {Button, Card, Flex, Popover, Text, useClickOutsideEvent} from '@sanity/ui'
+import {CONTAINER} from '@sanity/ui/tokens'
+import {useBoolean, useSelect} from '@sanity/ui-workshop'
+import {useCallback, useRef, useState} from 'react'
+
+import {
+  WORKSHOP_FLEX_ALIGN_OPTIONS,
+  WORKSHOP_FLEX_JUSTIFY_OPTIONS,
+  WORKSHOP_PLACEMENT_OPTIONS,
+} from '$workshop'
+
+export default function AlignedStory(): React.JSX.Element {
+  const constrainSize = useBoolean('Constrain size', false)
+  const placement = useSelect('Placement', WORKSHOP_PLACEMENT_OPTIONS)
+  const portal = useBoolean('Portal', true)
+  const width = useSelect('Width', CONTAINER, 'auto')
+  const flexAlign = useSelect('Align', WORKSHOP_FLEX_ALIGN_OPTIONS)
+  const flexJustify = useSelect('Justify', WORKSHOP_FLEX_JUSTIFY_OPTIONS)
+
+  const [open, setOpen] = useState(false)
+  const [boundaryElement, setBoundaryElement] = useState<HTMLDivElement | null>(null)
+  const buttonElementRef = useRef<HTMLButtonElement | null>(null)
+  const popoverElementRef = useRef<HTMLDivElement | null>(null)
+
+  const content = (
+    <Text size={1}>
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque at nisl at sem tempor
+      hendrerit scelerisque ut libero. Maecenas iaculis efficitur lorem, ac faucibus mi imperdiet
+      quis. Cras a consectetur erat. Fusce imperdiet, dolor et pellentesque iaculis, ex quam luctus
+      felis, non ultrices enim sem vitae quam. Duis lorem velit, lacinia at rhoncus a, tempus vel
+      neque. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae;
+      Sed id mauris quam. Nam finibus sapien non lacinia ultricies. Integer fermentum tortor at
+      pellentesque faucibus. In venenatis commodo placerat. Curabitur commodo tortor libero, vel
+      pellentesque elit luctus sodales. Donec mattis tristique nunc ac lacinia. Vestibulum non
+      pulvinar turpis, posuere consequat arcu. Fusce ut urna blandit, finibus nisi a, molestie elit.
+      Nulla sed eleifend mi.
+    </Text>
+  )
+
+  const handleToggleOpen = useCallback(() => setOpen((v) => !v), [])
+
+  useClickOutsideEvent(
+    () => setOpen(false),
+    () => [buttonElementRef.current, popoverElementRef.current],
+  )
+
+  return (
+    <Card height="fill" padding={[4, 5, 6]} sizing="border" tone="transparent">
+      <Card ref={setBoundaryElement} height="fill" padding={2} shadow={1} sizing="border">
+        <Flex align={flexAlign} height="fill" justify={flexJustify}>
+          <Popover
+            ref={popoverElementRef}
+            constrainSize={constrainSize}
+            content={content}
+            floatingBoundary={boundaryElement}
+            open={open}
+            overflow="auto"
+            padding={3}
+            placement={placement}
+            portal={portal}
+            width={width}
+          >
+            <Button
+              ref={buttonElementRef}
+              icon={EllipsisVerticalIcon}
+              mode="bleed"
+              selected={open}
+              onClick={handleToggleOpen}
+            />
+          </Popover>
+        </Flex>
+      </Card>
+    </Card>
+  )
+}

package/src/primitives/popover/__workshop__/MarginsStory.tsx

@@ -0,0 +1,31 @@
+import {Box, Card, Container, Flex, Popover, Text} from '@sanity/ui'
+
+export default function MarginsStory(): React.JSX.Element {
+  return (
+    <Flex align="center" height="fill" justify="center" padding={[4, 5, 6]} sizing="border">
+      <Popover
+        __unstable_margins={[-8, 8, -8, 8]}
+        arrow={false}
+        content={
+          <Box padding={2}>
+            <Text align="center" muted size={1}>
+              Popover
+            </Text>
+          </Box>
+        }
+        matchReferenceWidth
+        open
+        placement="bottom-start"
+        // radius={0}
+      >
+        <Container width={0}>
+          <Card muted padding={2} shadow={1}>
+            <Text align="center" muted size={1}>
+              Reference
+            </Text>
+          </Card>
+        </Container>
+      </Popover>
+    </Flex>
+  )
+}

package/src/primitives/popover/__workshop__/MatchReferenceWidthStory.tsx

@@ -0,0 +1,32 @@
+import {Box, Button, Container, Flex, Popover, Stack, Text} from '@sanity/ui'
+import {useBoolean, useSelect} from '@sanity/ui-workshop'
+
+import {WORKSHOP_PLACEMENT_OPTIONS} from '$workshop'
+
+export default function MatchReferenceWidthStory(): React.JSX.Element {
+  const arrow = useBoolean('Arrow', true)
+  const placement = useSelect('Placement', WORKSHOP_PLACEMENT_OPTIONS, 'bottom')
+
+  return (
+    <Flex align="center" height="fill" justify="center" padding={[4, 5, 6]} sizing="border">
+      <Popover
+        arrow={arrow}
+        content={
+          <Box padding={3}>
+            <Text size={1}>Content</Text>
+          </Box>
+        }
+        matchReferenceWidth
+        open
+        placement={placement}
+        radius={2}
+      >
+        <Container width={0}>
+          <Stack>
+            <Button fontSize={1} mode="ghost" selected text="Button" />
+          </Stack>
+        </Container>
+      </Popover>
+    </Flex>
+  )
+}

package/src/primitives/popover/__workshop__/OpenOnMountStory.tsx

@@ -0,0 +1,11 @@
+import {Button, Card, Popover, Text} from '@sanity/ui'
+
+export default function OpenOnMountStory(): React.JSX.Element {
+  return (
+    <Card height="fill" padding={3} sizing="border">
+      <Popover content={<Text size={1}>popover content</Text>} open padding={3} tone="default">
+        <Button text="This button is the popover reference" />
+      </Popover>
+    </Card>
+  )
+}

package/src/primitives/popover/__workshop__/PlainStory.tsx

@@ -0,0 +1,68 @@
+import {Button, Card, Popover, PortalProvider, Text} from '@sanity/ui'
+import {CONTAINER, RADIUS, SPACE} from '@sanity/ui/tokens'
+import {useBoolean, useSelect} from '@sanity/ui-workshop'
+import {useState} from 'react'
+
+import {WORKSHOP_PLACEMENT_OPTIONS} from '$workshop'
+
+export default function PlainStory(): React.JSX.Element {
+  const arrow = useBoolean('Arrow', true)
+  const boundaryElementFlag = useBoolean('Boundary element', true)
+  const constrainSize = useBoolean('Constrain size', true)
+  const matchReferenceWidth = useBoolean('Match reference width', false)
+  const open = useBoolean('Open', true)
+  const padding = useSelect('Padding', SPACE, 3)
+  const placement = useSelect('Placement', WORKSHOP_PLACEMENT_OPTIONS, 'bottom')
+  const portal = useBoolean('Portal', true)
+  const preventOverflow = useBoolean('Prevent overflow', true)
+  const radius = useSelect('Radius', RADIUS, 2)
+  const width = useSelect('Width', CONTAINER, 'auto')
+
+  const [portalElement, setPortalElement] = useState<HTMLDivElement | null>(null)
+  const [boundaryElement, setBoundaryElement] = useState<HTMLDivElement | null>(null)
+
+  return (
+    <Card height="fill" padding={3} sizing="border">
+      <PortalProvider element={portalElement}>
+        <Text align="center" muted size={1}>
+          Scroll this box to reveal the popover
+        </Text>
+        <div
+          ref={setBoundaryElement}
+          style={{
+            height: 'calc(100vh - 120px)',
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            margin: 60,
+            overflow: 'auto',
+            outline: '1px solid red',
+            width: 'calc(100vw - 120px)',
+          }}
+        >
+          <div style={{padding: '150vh 0', textAlign: 'center'}}>
+            <Popover
+              __unstable_margins={[1, 1, 1, 1]}
+              arrow={arrow}
+              constrainSize={constrainSize}
+              content={<Text size={1}>popover content</Text>}
+              fallbackPlacements={['top', 'bottom']}
+              floatingBoundary={boundaryElementFlag ? boundaryElement : undefined}
+              matchReferenceWidth={matchReferenceWidth}
+              open={open}
+              padding={padding}
+              placement={placement}
+              portal={portal}
+              preventOverflow={preventOverflow}
+              radius={radius}
+              width={width}
+            >
+              <Button text="This button is the popover reference" />
+            </Popover>
+          </div>
+        </div>
+        <div ref={setPortalElement} />
+      </PortalProvider>
+    </Card>
+  )
+}

package/src/primitives/popover/__workshop__/RecursiveStory.tsx

@@ -0,0 +1,71 @@
+import {Button, Flex, LayerProvider, type Placement, Popover, useLayer} from '@sanity/ui'
+import {CARD_TONES} from '@sanity/ui/tokens'
+import {useCallback, useEffect, useMemo, useRef, useState} from 'react'
+
+export default function RecursiveStory(): React.JSX.Element {
+  return (
+    <Flex align="center" height="fill" justify="center" padding={[4, 5, 6]} sizing="border">
+      <LayerProvider>
+        <RecursiveExample />
+      </LayerProvider>
+    </Flex>
+  )
+}
+
+const placements: Placement[] = ['top', 'right', 'bottom', 'left']
+
+function RecursiveExample({onClose}: {onClose?: () => void}) {
+  const [open, setOpen] = useState(false)
+  const buttonRef = useRef<HTMLButtonElement | null>(null)
+  const {isTopLayer} = useLayer()
+  const [toneSeed] = useState(() => Math.floor(Math.random() * CARD_TONES.length))
+  const [placementSeed] = useState(() => Math.floor(Math.random() * placements.length))
+  const fallbackPlacements = useMemo(() => {
+    const before = placements.slice(placementSeed)
+    const after = placements.slice(0, placementSeed)
+
+    return before.concat(after)
+  }, [placementSeed])
+
+  useEffect(() => {
+    if (open === false) buttonRef.current?.focus()
+  }, [open])
+
+  useEffect(() => {
+    setTimeout(() => {
+      buttonRef.current?.focus()
+    }, 0)
+  }, [])
+
+  const handleOpen = useCallback(() => setOpen(true), [])
+  const handleClose = useCallback(() => setOpen(false), [])
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLButtonElement>) => {
+      if (!isTopLayer) return
+      if (event.key === 'Escape' && onClose) onClose()
+    },
+    [isTopLayer, onClose],
+  )
+
+  return (
+    <Popover
+      content={<RecursiveExample onClose={handleClose} />}
+      fallbackPlacements={fallbackPlacements}
+      open={open}
+      padding={1}
+      placement={fallbackPlacements[3]}
+      portal
+      tone={CARD_TONES[toneSeed]}
+    >
+      <Button
+        ref={buttonRef}
+        // disabled={!isTopLayer}
+        mode="bleed"
+        text="Open"
+        onClick={handleOpen}
+        onKeyDown={handleKeyDown}
+      />
+    </Popover>
+  )
+}