@bettercms-ai/kit 0.1.0

package/src/core/components/dialog/dialog.tsx

@@ -0,0 +1,430 @@
+import {CloseIcon} from '@bettercms-ai/icons'
+import {ThemeColorSchemeKey} from '@bettercms-ai/kit/theme'
+import {forwardRef, useCallback, useEffect, useImperativeHandle, useRef} from 'react'
+import {styled} from 'styled-components'
+
+import {
+  containsOrEqualsElement,
+  focusFirstDescendant,
+  focusLastDescendant,
+  isHTMLElement,
+} from '../../helpers'
+import {useClickOutsideEvent, useGlobalKeyDown, usePrefersReducedMotion} from '../../hooks'
+import {Box, Button, Card, Container, Flex, Text} from '../../primitives'
+import {ResponsivePaddingProps, ResponsiveWidthProps} from '../../primitives/types'
+import {_getArrayProp} from '../../styles'
+import {responsivePaddingStyle, ResponsivePaddingStyleProps} from '../../styles/internal'
+import {useTheme_v2} from '../../theme'
+import {DialogPosition, Radius} from '../../types'
+import {Layer, LayerProps, Portal, useBoundaryElement, useLayer, usePortal} from '../../utils'
+import {
+  animationDialogStyle,
+  AnimationDialogStyleProps,
+  dialogStyle,
+  responsiveDialogPositionStyle,
+  ResponsiveDialogPositionStyleProps,
+} from './styles'
+import {useDialog} from './useDialog'
+
+/**
+ * @public
+ */
+export interface DialogProps extends ResponsivePaddingProps, ResponsiveWidthProps {
+  /**
+   * @beta
+   */
+  __unstable_autoFocus?: boolean
+  /**
+   * @beta
+   */
+  __unstable_hideCloseButton?: boolean
+  cardRadius?: Radius | Radius[]
+  cardShadow?: number | number[]
+  contentRef?: React.ForwardedRef<HTMLDivElement>
+  footer?: React.ReactNode
+  header?: React.ReactNode
+  id: string
+  /** A callback that fires when the dialog becomes the top layer when it was not the top layer before. */
+  onActivate?: LayerProps['onActivate']
+  onClickOutside?: () => void
+  onClose?: () => void
+  portal?: string
+  position?: DialogPosition | DialogPosition[]
+  scheme?: ThemeColorSchemeKey
+  zOffset?: number | number[]
+  /**
+   * Whether the dialog should animate in on mount.
+   *
+   * @beta
+   * @defaultValue false
+   */
+  animate?: boolean
+}
+
+interface DialogCardProps extends ResponsiveWidthProps {
+  /**
+   * @beta
+   */
+  __unstable_autoFocus: boolean
+  /**
+   * @beta
+   */
+  __unstable_hideCloseButton: boolean
+  children: React.ReactNode
+  contentRef?: React.ForwardedRef<HTMLDivElement>
+  footer: React.ReactNode
+  header: React.ReactNode
+  id: string
+  onClickOutside?: () => void
+  onClose?: () => void
+  portal?: string
+  radius: Radius | Radius[]
+  scheme?: ThemeColorSchemeKey
+  shadow: number | number[]
+}
+
+function isTargetWithinScope(
+  boundaryElement: HTMLElement | null,
+  portalElement: HTMLElement | null,
+  target: Node,
+): boolean {
+  if (!boundaryElement || !portalElement) return true
+
+  return (
+    containsOrEqualsElement(boundaryElement, target) ||
+    containsOrEqualsElement(portalElement, target)
+  )
+}
+
+const StyledDialog = styled(Layer)<
+  ResponsiveDialogPositionStyleProps & ResponsivePaddingStyleProps & AnimationDialogStyleProps
+>(responsivePaddingStyle, dialogStyle, responsiveDialogPositionStyle, animationDialogStyle)
+
+const DialogContainer = styled(Container)`
+  &:not([hidden]) {
+    display: flex;
+  }
+  width: 100%;
+  height: 100%;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+`
+
+const DialogCardRoot = styled(Card)`
+  &:not([hidden]) {
+    display: flex;
+  }
+  width: 100%;
+  min-height: 0;
+  max-height: 100%;
+  overflow: hidden;
+  overflow: clip;
+`
+
+const DialogLayout = styled(Flex)`
+  flex: 1;
+  min-height: 0;
+  width: 100%;
+`
+
+const DialogHeader = styled(Box)`
+  position: relative;
+  z-index: 2;
+`
+
+const DialogContent = styled(Box)`
+  position: relative;
+  z-index: 1;
+  overflow: auto;
+  outline: none;
+`
+
+const DialogFooter = styled(Box)`
+  position: relative;
+  z-index: 3;
+`
+
+const DialogCard = forwardRef(function DialogCard(
+  props: DialogCardProps,
+  forwardedRef: React.ForwardedRef<HTMLDivElement>,
+) {
+  const {
+    __unstable_autoFocus: autoFocus,
+    __unstable_hideCloseButton: hideCloseButton,
+    children,
+    contentRef: forwardedContentRef,
+    footer,
+    header,
+    id,
+    onClickOutside,
+    onClose,
+    portal: portalProp,
+    radius: radiusProp,
+    scheme,
+    shadow: shadowProp,
+    width: widthProp,
+  } = props
+  const portal = usePortal()
+  const portalElement = portalProp ? portal.elements?.[portalProp] || null : portal.element
+  const boundaryElement = useBoundaryElement().element
+  const radius = _getArrayProp(radiusProp)
+  const shadow = _getArrayProp(shadowProp)
+  const width = _getArrayProp(widthProp)
+  const ref = useRef<HTMLDivElement | null>(null)
+  const contentRef = useRef<HTMLDivElement | null>(null)
+  const layer = useLayer()
+  const {isTopLayer} = layer
+  const labelId = `${id}_label`
+  const showCloseButton = Boolean(onClose) && hideCloseButton === false
+  const showHeader = Boolean(header) || showCloseButton
+
+  useImperativeHandle<HTMLDivElement | null, HTMLDivElement | null>(forwardedRef, () => ref.current)
+  useImperativeHandle<HTMLDivElement | null, HTMLDivElement | null>(
+    forwardedContentRef,
+    () => contentRef.current,
+  )
+
+  useEffect(() => {
+    if (!autoFocus) return
+
+    // On mount: focus the first focusable element
+    if (ref.current) {
+      focusFirstDescendant(ref.current)
+    }
+  }, [autoFocus, ref])
+
+  useGlobalKeyDown(
+    useCallback(
+      (event: KeyboardEvent) => {
+        if (!isTopLayer || !onClose) return
+
+        const target = document.activeElement
+
+        if (target && !isTargetWithinScope(boundaryElement, portalElement, target)) {
+          // Ignore key presses when the focused element is outside of scope
+          return
+        }
+
+        if (event.key === 'Escape') {
+          event.preventDefault()
+          event.stopPropagation()
+          onClose()
+        }
+      },
+      [boundaryElement, isTopLayer, onClose, portalElement],
+    ),
+  )
+
+  useClickOutsideEvent(
+    isTopLayer &&
+      onClickOutside &&
+      ((event) => {
+        const target = event.target as Node | null
+
+        if (target && !isTargetWithinScope(boundaryElement, portalElement, target)) {
+          // Ignore clicks outside of the scope
+          return
+        }
+
+        onClickOutside()
+      }),
+    () => [ref.current],
+  )
+
+  return (
+    <DialogContainer data-ui="DialogCard" width={width}>
+      <DialogCardRoot radius={radius} ref={ref} scheme={scheme} shadow={shadow}>
+        <DialogLayout direction="column">
+          {showHeader && (
+            <DialogHeader>
+              <Flex align="flex-start" padding={3}>
+                <Box flex={1} padding={2}>
+                  {header && (
+                    <Text id={labelId} size={1} weight="semibold">
+                      {header}
+                    </Text>
+                  )}
+                </Box>
+                {showCloseButton && (
+                  <Box flex="none">
+                    <Button
+                      aria-label="Close dialog"
+                      disabled={!onClose}
+                      icon={CloseIcon}
+                      mode="bleed"
+                      onClick={onClose}
+                      padding={2}
+                    />
+                  </Box>
+                )}
+              </Flex>
+            </DialogHeader>
+          )}
+
+          <DialogContent flex={1} ref={contentRef} tabIndex={-1}>
+            {children}
+          </DialogContent>
+
+          {footer && <DialogFooter>{footer}</DialogFooter>}
+        </DialogLayout>
+      </DialogCardRoot>
+    </DialogContainer>
+  )
+})
+
+DialogCard.displayName = 'ForwardRef(DialogCard)'
+
+/**
+ * The Dialog component.
+ *
+ * @public
+ */
+export const Dialog = forwardRef(function Dialog(
+  props: DialogProps & Omit<React.HTMLProps<HTMLDivElement>, 'as' | 'id' | 'width'>,
+  ref: React.Ref<HTMLDivElement>,
+) {
+  const dialog = useDialog()
+  const {layer} = useTheme_v2()
+  const {
+    __unstable_autoFocus: autoFocus = true,
+    __unstable_hideCloseButton: hideCloseButton = false,
+    cardRadius: cardRadiusProp = 4,
+    cardShadow = 3,
+    children,
+    contentRef,
+    footer,
+    header,
+    id,
+    onActivate,
+    onClickOutside,
+    onClose,
+    onFocus,
+    padding: paddingProp = 3,
+    portal: portalProp,
+    position: _positionProp,
+    scheme,
+    width: widthProp = 0,
+    zOffset: _zOffsetProp,
+    animate: _animate = false,
+    ...restProps
+  } = props
+  const positionProp = _positionProp ?? (dialog.position || 'fixed')
+  const zOffsetProp = _zOffsetProp ?? (dialog.zOffset || layer.dialog.zOffset)
+  const prefersReducedMotion = usePrefersReducedMotion()
+  const animate = prefersReducedMotion ? false : _animate
+  const portal = usePortal()
+  const portalElement = portalProp ? portal.elements?.[portalProp] || null : portal.element
+  const boundaryElement = useBoundaryElement().element
+  const cardRadius = _getArrayProp(cardRadiusProp)
+  const padding = _getArrayProp(paddingProp)
+  const position = _getArrayProp(positionProp)
+  const width = _getArrayProp(widthProp)
+  const zOffset = _getArrayProp(zOffsetProp)
+  const preDivRef = useRef<HTMLDivElement | null>(null)
+  const postDivRef = useRef<HTMLDivElement | null>(null)
+  const cardRef = useRef<HTMLDivElement | null>(null)
+  const focusedElementRef = useRef<HTMLElement | null>(null)
+
+  const handleFocus = useCallback(
+    (event: React.FocusEvent<HTMLDivElement>) => {
+      onFocus?.(event)
+
+      const target = event.target
+      const cardElement = cardRef.current
+
+      if (cardElement && target === preDivRef.current) {
+        focusLastDescendant(cardElement)
+
+        return
+      }
+
+      if (cardElement && target === postDivRef.current) {
+        focusFirstDescendant(cardElement)
+
+        return
+      }
+
+      if (isHTMLElement(event.target)) {
+        focusedElementRef.current = event.target
+      }
+    },
+    [onFocus],
+  )
+
+  const labelId = `${id}_label`
+
+  const rootClickTimeoutRef = useRef<NodeJS.Timeout>(undefined)
+
+  // If the resulting active element (a.k.a. focused element) is not withing scope when clicking
+  // within the dialog, then we want to focus the previously interactive element in the dialog instead.
+  // This is to allow the user to tab or close the dialog by pressing escape.
+  const handleRootClick = useCallback(() => {
+    if (rootClickTimeoutRef.current) {
+      clearTimeout(rootClickTimeoutRef.current)
+    }
+
+    rootClickTimeoutRef.current = setTimeout(() => {
+      const activeElement = document.activeElement
+
+      if (activeElement && !isTargetWithinScope(boundaryElement, portalElement, activeElement)) {
+        const target = focusedElementRef.current
+
+        if (!target || !document.body.contains(target)) {
+          // No previously focused element, or it's not in the document anymore
+          const cardElement = cardRef.current
+          if (cardElement) focusFirstDescendant(cardElement)
+
+          return
+        }
+
+        target.focus()
+      }
+    }, 0)
+  }, [boundaryElement, portalElement])
+
+  return (
+    <Portal __unstable_name={portalProp}>
+      <StyledDialog
+        {...restProps}
+        $animate={animate}
+        $padding={padding}
+        $position={position}
+        aria-labelledby={labelId}
+        aria-modal
+        data-ui="Dialog"
+        id={id}
+        onActivate={onActivate}
+        onClick={handleRootClick}
+        onFocus={handleFocus}
+        ref={ref}
+        role="dialog"
+        zOffset={zOffset}
+      >
+        {/* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */}
+        <div ref={preDivRef} tabIndex={0} />
+        <DialogCard
+          __unstable_autoFocus={autoFocus}
+          __unstable_hideCloseButton={hideCloseButton}
+          contentRef={contentRef}
+          footer={footer}
+          header={header}
+          id={id}
+          onClickOutside={onClickOutside}
+          onClose={onClose}
+          portal={portalProp}
+          radius={cardRadius}
+          ref={cardRef}
+          scheme={scheme}
+          shadow={cardShadow}
+          width={width}
+        >
+          {children}
+        </DialogCard>
+        {/* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */}
+        <div ref={postDivRef} tabIndex={0} />
+      </StyledDialog>
+    </Portal>
+  )
+})
+Dialog.displayName = 'ForwardRef(Dialog)'

package/src/core/components/dialog/dialogContext.ts

@@ -0,0 +1,20 @@
+import {createGlobalScopedContext} from '../../lib/createGlobalScopedContext'
+import {DialogPosition} from '../../types'
+
+/**
+ * This API might change. DO NOT USE IN PRODUCTION.
+ * @beta
+ */
+export interface DialogContextValue {
+  version: 0.0
+  position?: DialogPosition | DialogPosition[]
+  zOffset?: number | number[]
+}
+
+/**
+ * @internal
+ */
+export const DialogContext = createGlobalScopedContext<DialogContextValue>(
+  '@bettercms-ai/kit/context/dialog',
+  {version: 0.0},
+)

package/src/core/components/dialog/dialogProvider.tsx

@@ -0,0 +1,35 @@
+import {useMemo} from 'react'
+
+import {DialogPosition} from '../../types'
+import {DialogContext, DialogContextValue} from './dialogContext'
+
+/**
+ * This API might change. DO NOT USE IN PRODUCTION.
+ * @beta
+ */
+export interface DialogProviderProps {
+  children?: React.ReactNode
+  position?: DialogPosition | DialogPosition[]
+  zOffset?: number | number[]
+}
+
+/**
+ * This API might change. DO NOT USE IN PRODUCTION.
+ * @beta
+ */
+export function DialogProvider(props: DialogProviderProps): React.JSX.Element {
+  const {children, position, zOffset} = props
+
+  const contextValue: DialogContextValue = useMemo(
+    () => ({
+      version: 0.0,
+      position,
+      zOffset,
+    }),
+    [position, zOffset],
+  )
+
+  return <DialogContext.Provider value={contextValue}>{children}</DialogContext.Provider>
+}
+
+DialogProvider.displayName = 'DialogProvider'

package/src/core/components/dialog/index.ts

@@ -0,0 +1,4 @@
+export * from './dialog'
+export * from './dialogContext'
+export * from './dialogProvider'
+export * from './useDialog'

package/src/core/components/dialog/styles.ts

@@ -0,0 +1,77 @@
+import {CSSObject, getTheme_v2} from '@bettercms-ai/kit/theme'
+import {css} from 'styled-components'
+
+import {_responsive, ThemeProps} from '../../styles'
+import {DialogPosition} from '../../types'
+
+/**
+ * @internal
+ */
+export interface ResponsiveDialogPositionStyleProps {
+  $position: DialogPosition[]
+}
+
+export function dialogStyle({theme}: ThemeProps): CSSObject {
+  const {color} = getTheme_v2(theme)
+
+  return {
+    '&:not([hidden])': {
+      display: 'flex',
+    },
+
+    'top': 0,
+    'left': 0,
+    'right': 0,
+    'bottom': 0,
+    'alignItems': 'center',
+    'justifyContent': 'center',
+    'outline': 'none',
+    'background': color.backdrop,
+  }
+}
+
+export function responsiveDialogPositionStyle(
+  props: ResponsiveDialogPositionStyleProps & ThemeProps,
+): CSSObject[] {
+  const {media} = getTheme_v2(props.theme)
+
+  return _responsive(media, props.$position, (position) => ({'&&': {position}}))
+}
+
+/**
+ * @internal
+ */
+export interface AnimationDialogStyleProps {
+  $animate: boolean
+}
+
+export function animationDialogStyle(props: AnimationDialogStyleProps): ReturnType<typeof css> {
+  if (!props.$animate) return css``
+
+  return css`
+    @keyframes zoomIn {
+      from {
+        opacity: 0;
+        transform: scale(0.95);
+      }
+      to {
+        opacity: 1;
+        transform: scale(1);
+      }
+    }
+    @keyframes fadeIn {
+      from {
+        opacity: 0;
+      }
+      to {
+        opacity: 1;
+      }
+    }
+
+    animation: fadeIn 200ms ease-out;
+    // Animates the dialog card.
+    & > [data-ui='DialogCard'] {
+      animation: zoomIn 200ms ease-out;
+    }
+  `
+}

package/src/core/components/dialog/useDialog.ts

@@ -0,0 +1,11 @@
+import {useContext} from 'react'
+
+import {DialogContext, DialogContextValue} from './dialogContext'
+
+/**
+ * This API might change. DO NOT USE IN PRODUCTION.
+ * @beta
+ */
+export function useDialog(): DialogContextValue {
+  return useContext(DialogContext)
+}

package/src/core/components/hotkeys/__workshop__/index.ts

@@ -0,0 +1,14 @@
+import {defineScope} from '@bettercms-ai/kit-workshop'
+import {lazy} from 'react'
+
+export default defineScope({
+  name: 'components/hotkeys',
+  title: 'Hotkeys',
+  stories: [
+    {
+      name: 'plain',
+      title: 'Plain',
+      component: lazy(() => import('./plain')),
+    },
+  ],
+})

package/src/core/components/hotkeys/__workshop__/plain.tsx

@@ -0,0 +1,9 @@
+import {Flex, Hotkeys} from '@bettercms-ai/kit'
+
+export default function PlainStory() {
+  return (
+    <Flex align="center" height="fill" justify="center">
+      <Hotkeys keys={['Ctrl', 'Shift', 'P']} />
+    </Flex>
+  )
+}

package/src/core/components/hotkeys/hotkeys.test.tsx

@@ -0,0 +1,42 @@
+/** @jest-environment jsdom */
+
+import {render} from '../../../../test'
+import {Inline} from '../../primitives'
+import {Hotkeys} from './hotkeys'
+
+jest.mock('../../primitives', () => {
+  const actual = jest.requireActual('../../primitives')
+
+  return {
+    ...actual,
+    Inline: jest.fn((props: Record<string, unknown>) => (actual.Inline as any).render(props, null)),
+  }
+})
+
+describe('components/hotkeys spacing', () => {
+  const mockedInline = jest.mocked(Inline)
+
+  beforeEach(() => {
+    mockedInline.mockClear()
+  })
+
+  it('should support `space` and `gap` with the same behavior', () => {
+    render(<Hotkeys keys={['Ctrl', 'S']} space={2} />)
+    expect(mockedInline.mock.calls.map(([props]) => props)).toContainEqual(
+      expect.objectContaining({gap: [2]}),
+    )
+
+    mockedInline.mockClear()
+    render(<Hotkeys gap={2} keys={['Ctrl', 'S']} />)
+    expect(mockedInline.mock.calls.map(([props]) => props)).toContainEqual(
+      expect.objectContaining({gap: [2]}),
+    )
+  })
+
+  it('should prefer `gap` over `space` when both are provided', () => {
+    render(<Hotkeys gap={3} keys={['Ctrl', 'S']} space={1} />)
+    const propsList = mockedInline.mock.calls.map(([props]) => props)
+    expect(propsList).toContainEqual(expect.objectContaining({gap: [3]}))
+    expect(propsList).not.toContainEqual(expect.objectContaining({gap: [1]}))
+  })
+})