@bettercms-ai/kit 0.1.0

package/src/core/utils/boundaryElement/boundaryElement.test.tsx

@@ -0,0 +1,100 @@
+/** @jest-environment jsdom */
+
+import {render} from '../../../../test'
+import {BoundaryElementContext} from './boundaryElementContext'
+import {BoundaryElementContextValue} from './types'
+import {useBoundaryElement} from './useBoundaryElement'
+
+describe('utils/boundaryElement', () => {
+  describe('useBoundaryElement', () => {
+    it('should get context value', async () => {
+      const log = jest.fn()
+
+      function Debug() {
+        const rootBoundaryElement = useBoundaryElement()
+
+        log(rootBoundaryElement)
+
+        return <>debug</>
+      }
+
+      function Root() {
+        const value: BoundaryElementContextValue = {
+          version: 0.0,
+          element: null,
+        }
+
+        return (
+          <BoundaryElementContext.Provider value={value}>
+            <Debug />
+          </BoundaryElementContext.Provider>
+        )
+      }
+
+      render(<Root />)
+
+      expect(log.mock.calls[0][0].version).toBe(0.0)
+      expect(log.mock.calls[0][0].element).toBe(null)
+    })
+
+    it('should provide default value when no context value is provided', async () => {
+      const log = jest.fn()
+
+      function Debug() {
+        const rootBoundaryElement = useBoundaryElement()
+
+        log(rootBoundaryElement)
+
+        return null
+      }
+
+      function Root() {
+        const value = undefined
+
+        return (
+          <BoundaryElementContext.Provider value={value as any}>
+            <Debug />
+          </BoundaryElementContext.Provider>
+        )
+      }
+
+      render(<Root />)
+
+      expect(log.mock.calls[0][0].version).toBe(0.0)
+      expect(log.mock.calls[0][0].element).toBe(null)
+    })
+
+    it('should fail when context value is not compatible', async () => {
+      const log = jest.fn()
+
+      function Debug() {
+        try {
+          useBoundaryElement()
+        } catch (err) {
+          log(err)
+        }
+
+        return null
+      }
+
+      function Root() {
+        // NOTE: we’re testing this because the context value may be a function in the future
+        const value = () => {
+          return {version: 1}
+        }
+
+        return (
+          <BoundaryElementContext.Provider value={value as any}>
+            <Debug />
+          </BoundaryElementContext.Provider>
+        )
+      }
+
+      render(<Root />)
+
+      expect(log.mock.calls[0][0].message).toEqual(
+        'useBoundaryElement(): the context value is not compatible',
+      )
+    })
+  })
+})

package/src/core/utils/boundaryElement/boundaryElementContext.ts

@@ -0,0 +1,7 @@
+import {createGlobalScopedContext} from '../../lib/createGlobalScopedContext'
+import {BoundaryElementContextValue} from './types'
+
+export const BoundaryElementContext = createGlobalScopedContext<BoundaryElementContextValue | null>(
+  '@bettercms-ai/kit/context/boundaryElement',
+  null,
+)

package/src/core/utils/boundaryElement/boundaryElementProvider.tsx

@@ -0,0 +1,24 @@
+import {useMemo} from 'react'
+
+import {BoundaryElementContext} from './boundaryElementContext'
+import {BoundaryElementContextValue} from './types'
+
+/**
+ * @public
+ */
+export interface BoundaryElementProviderProps {
+  children: React.ReactNode
+  element: HTMLElement | null
+}
+
+/**
+ * @public
+ */
+export function BoundaryElementProvider(props: BoundaryElementProviderProps): React.JSX.Element {
+  const {children, element} = props
+  const value: BoundaryElementContextValue = useMemo(() => ({version: 0.0, element}), [element])
+
+  return <BoundaryElementContext.Provider value={value}>{children}</BoundaryElementContext.Provider>
+}
+
+BoundaryElementProvider.displayName = 'BoundaryElementProvider'

package/src/core/utils/boundaryElement/index.ts

@@ -0,0 +1,3 @@
+export * from './boundaryElementProvider'
+export * from './types'
+export * from './useBoundaryElement'

package/src/core/utils/boundaryElement/types.ts

@@ -0,0 +1,7 @@
+/**
+ * @public
+ */
+export interface BoundaryElementContextValue {
+  version: 0.0
+  element: HTMLElement | null
+}

package/src/core/utils/boundaryElement/useBoundaryElement.ts

@@ -0,0 +1,26 @@
+import {useContext} from 'react'
+
+import {isRecord} from '../../lib/isRecord'
+import {BoundaryElementContext} from './boundaryElementContext'
+import {BoundaryElementContextValue} from './types'
+
+const DEFAULT_VALUE: BoundaryElementContextValue = {
+  version: 0.0,
+  element: null,
+}
+
+/**
+ * @public
+ */
+export function useBoundaryElement(): BoundaryElementContextValue {
+  const value = useContext(BoundaryElementContext)
+
+  // NOTE: This check is for future-compatiblity
+  // - If the value is not an object, it’s not compatible with the current version
+  // - If the value is an object, but doesn’t have `version: 0.0`, it’s not compatible with the current version
+  if (value && (!isRecord(value) || value.version !== 0.0)) {
+    throw new Error('useBoundaryElement(): the context value is not compatible')
+  }
+
+  return value || DEFAULT_VALUE
+}

package/src/core/utils/conditionalWrapper/conditionalWrapper.tsx

@@ -0,0 +1,21 @@
+/**
+ * @internal
+ * @deprecated this component will be removed in the next major release
+ */
+export function ConditionalWrapper({
+  children,
+  condition,
+  wrapper,
+}: {
+  children: React.ReactNode
+  condition: boolean
+  wrapper: (children: React.ReactNode) => React.ReactNode
+}): React.ReactNode {
+  if (!condition) {
+    return children
+  }
+
+  return wrapper(children)
+}
+
+ConditionalWrapper.displayName = 'ConditionalWrapper'

package/src/core/utils/conditionalWrapper/index.ts

@@ -0,0 +1 @@
+export * from './conditionalWrapper'

package/src/core/utils/elementQuery/__workshop__/customMedia.tsx

@@ -0,0 +1,30 @@
+import {Box, Card, ElementQuery, Text} from '@bettercms-ai/kit'
+import {styled} from 'styled-components'
+
+const TestCard = styled(Card)`
+  --card-fg-color: orange;
+
+  [data-eq-min~='0'] > & {
+    --card-fg-color: green;
+  }
+
+  [data-eq-min~='1'] > & {
+    --card-fg-color: blue;
+  }
+`
+
+export default function CustomMediaQuery() {
+  return (
+    <Box padding={[3, 4, 5]}>
+      <Box marginBottom={[3, 4, 5]}>
+        <Text>Resize this frame to see the text color change:</Text>
+      </Box>
+
+      <ElementQuery media={[100, 200, 300]}>
+        <TestCard padding={2} shadow={1}>
+          <Text>This card sits inside an element query.</Text>
+        </TestCard>
+      </ElementQuery>
+    </Box>
+  )
+}

package/src/core/utils/elementQuery/__workshop__/index.ts

@@ -0,0 +1,14 @@
+import {defineScope} from '@bettercms-ai/kit-workshop'
+import {lazy} from 'react'
+
+export default defineScope({
+  name: 'utils/elementQuery',
+  title: 'ElementQuery',
+  stories: [
+    {
+      name: 'custom-media',
+      title: 'Custom media',
+      component: lazy(() => import('./customMedia')),
+    },
+  ],
+})

package/src/core/utils/elementQuery/elementQuery.tsx

@@ -0,0 +1,53 @@
+import {forwardRef, useImperativeHandle, useMemo, useState} from 'react'
+
+import {useElementSize} from '../../hooks'
+import {useTheme_v2} from '../../theme'
+import {findMaxBreakpoints, findMinBreakpoints} from './helpers'
+
+/**
+ * DO NOT USE IN PRODUCTION.
+ * @beta
+ */
+export interface MediaQueryProps {
+  as?: React.ElementType | keyof React.JSX.IntrinsicElements
+  media?: number[]
+}
+
+/**
+ * DO NOT USE IN PRODUCTION.
+ * @beta
+ */
+export const ElementQuery = forwardRef(function ElementQuery(
+  props: MediaQueryProps & Omit<React.HTMLProps<HTMLDivElement>, 'as' | 'media'>,
+  forwardedRef: React.ForwardedRef<HTMLDivElement>,
+) {
+  const theme = useTheme_v2()
+  const {children, media: _media, ...restProps} = props
+  const media = _media ?? theme.media
+
+  const [element, setElement] = useState<HTMLDivElement | null>(null)
+  const elementSize = useElementSize(element)
+  const width = useMemo(() => elementSize?.border.width ?? window.innerWidth, [elementSize])
+
+  const max = useMemo(() => {
+    const eq = findMaxBreakpoints(media, width)
+
+    return eq.length ? eq.join(' ') : undefined
+  }, [media, width])
+  const min = useMemo(() => {
+    const eq = findMinBreakpoints(media, width)
+
+    return eq.length ? eq.join(' ') : undefined
+  }, [media, width])
+
+  useImperativeHandle<HTMLDivElement | null, HTMLDivElement | null>(forwardedRef, () => element, [
+    element,
+  ])
+
+  return (
+    <div data-ui="ElementQuery" {...restProps} data-eq-max={max} data-eq-min={min} ref={setElement}>
+      {children}
+    </div>
+  )
+})
+ElementQuery.displayName = 'ForwardRef(ElementQuery)'

package/src/core/utils/elementQuery/helpers.ts

@@ -0,0 +1,27 @@
+export function findMaxBreakpoints(media: number[], width: number): number[] {
+  const ret: number[] = []
+
+  for (let i = 0; i < media.length; i += 1) {
+    const bp = media[i]
+
+    if (bp > width) {
+      ret.push(i)
+    }
+  }
+
+  return ret
+}
+
+export function findMinBreakpoints(media: number[], width: number): number[] {
+  const ret: number[] = []
+
+  for (let i = 0; i < media.length; i += 1) {
+    const bp = media[i]
+
+    if (bp <= width) {
+      ret.push(i)
+    }
+  }
+
+  return ret
+}

package/src/core/utils/elementQuery/index.ts

@@ -0,0 +1 @@
+export * from './elementQuery'

package/src/core/utils/errorBoundary.tsx

@@ -0,0 +1,48 @@
+import {Component, PropsWithChildren} from 'react'
+
+import {Code} from '../primitives/code'
+
+/**
+ * DO NOT USE IN PRODUCTION
+ * @beta
+ */
+export type ErrorBoundaryProps = PropsWithChildren<{
+  onCatch: (params: {error: Error; info: React.ErrorInfo}) => void
+}>
+
+/**
+ * DO NOT USE IN PRODUCTION
+ * @beta
+ */
+export interface ErrorBoundaryState {
+  error: Error | null
+}
+
+/**
+ * DO NOT USE IN PRODUCTION
+ * @beta
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = {error: null}
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    // Update state so the next render will show the fallback UI.
+    return {error}
+  }
+
+  componentDidCatch(error: Error, info: React.ErrorInfo): void {
+    this.props.onCatch({error, info})
+  }
+
+  render(): React.ReactNode {
+    const {error} = this.state
+
+    if (error) {
+      const message = typeof error?.message === 'string' ? error.message : 'Error'
+
+      return <Code>{message}</Code>
+    }
+
+    return this.props.children
+  }
+}

package/src/core/utils/getElementRef.ts

@@ -0,0 +1,26 @@
+// Based on https://github.com/radix-ui/primitives/blob/0bade6a704e5821b90a6da0f3d8cfa8a7711127d/packages/react/slot/src/Slot.tsx#L128-L150
+// Before React 19 accessing `element.props.ref` will throw a warning and suggest using `element.ref`
+// After React 19 accessing `element.ref` does the opposite.
+// https://github.com/facebook/react/pull/28348
+//
+// Access the ref using the method that doesn't yield a warning.
+export function getElementRef(element: React.ReactElement) {
+  // React <=18 in DEV
+  let getter = Object.getOwnPropertyDescriptor(element.props, 'ref')?.get
+  let mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning
+
+  if (mayWarn) {
+    return (element as any).ref
+  }
+
+  // React 19 in DEV
+  getter = Object.getOwnPropertyDescriptor(element, 'ref')?.get
+  mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning
+
+  if (mayWarn) {
+    return (element.props as {ref?: React.Ref<unknown>}).ref
+  }
+
+  // Not DEV
+  return (element.props as {ref?: React.Ref<unknown>}).ref || (element as any).ref
+}

package/src/core/utils/index.ts

@@ -0,0 +1,9 @@
+export * from './arrow'
+export * from './boundaryElement'
+export * from './conditionalWrapper'
+export * from './elementQuery'
+export * from './errorBoundary'
+export * from './layer'
+export * from './portal'
+export * from './srOnly'
+export * from './virtualList'

package/src/core/utils/layer/__workshop__/_debug.tsx

@@ -0,0 +1,17 @@
+import {Code, useLayer} from '@bettercms-ai/kit'
+
+export function LayerDebugInfo(props: {id?: string}) {
+  const {id} = props
+  const layer = useLayer()
+
+  return (
+    <Code id={id} size={1}>
+      {[
+        //
+        `isTopLayer=${layer.isTopLayer}`,
+        `size=${layer.size}`,
+        `zIndex=${layer.zIndex}`,
+      ].join('\n')}
+    </Code>
+  )
+}

package/src/core/utils/layer/__workshop__/index.ts

@@ -0,0 +1,24 @@
+import {defineScope} from '@bettercms-ai/kit-workshop'
+import {lazy} from 'react'
+
+export default defineScope({
+  name: 'utils/layer',
+  title: 'Layer',
+  stories: [
+    {
+      name: 'nested',
+      title: 'Nested',
+      component: lazy(() => import('./nested')),
+    },
+    {
+      name: 'multiple-roots',
+      title: 'Multiple roots',
+      component: lazy(() => import('./multipleRoots')),
+    },
+    {
+      name: 'responsive-z-offset',
+      title: 'Responsive z-offset',
+      component: lazy(() => import('./responsiveZOffset')),
+    },
+  ],
+})

package/src/core/utils/layer/__workshop__/multipleRoots.tsx

@@ -0,0 +1,49 @@
+import {Card, Layer, LayerProvider, Stack} from '@bettercms-ai/kit'
+
+import {LayerDebugInfo} from './_debug'
+
+export default function MultipleRootsStory() {
+  return (
+    <Stack space={4}>
+      <LayerProvider zOffset={100}>
+        <Card padding={3} shadow={1}>
+          <Stack space={3}>
+            <LayerDebugInfo />
+            <Layer>
+              <Card padding={3} shadow={1}>
+                <Stack space={3}>
+                  <LayerDebugInfo />
+                  <Layer>
+                    <Card padding={3} shadow={1}>
+                      <LayerDebugInfo />
+                    </Card>
+                  </Layer>
+                </Stack>
+              </Card>
+            </Layer>
+          </Stack>
+        </Card>
+      </LayerProvider>
+
+      <LayerProvider zOffset={200}>
+        <Card as={Layer} padding={3} shadow={5} style={{top: -50, left: 30}}>
+          <Stack space={3}>
+            <LayerDebugInfo />
+            <Layer>
+              <Card padding={3} shadow={1}>
+                <Stack space={3}>
+                  <LayerDebugInfo />
+                  <Layer>
+                    <Card padding={3} shadow={1}>
+                      <LayerDebugInfo />
+                    </Card>
+                  </Layer>
+                </Stack>
+              </Card>
+            </Layer>
+          </Stack>
+        </Card>
+      </LayerProvider>
+    </Stack>
+  )
+}

package/src/core/utils/layer/__workshop__/nested.tsx

@@ -0,0 +1,98 @@
+import {CloseIcon} from '@bettercms-ai/icons'
+import {Box, Button, Card, Flex, Layer, LayerProvider, Stack, Text} from '@bettercms-ai/kit'
+import {useCallback, useState} from 'react'
+
+import {LayerDebugInfo} from './_debug'
+
+export default function PlainStory() {
+  return (
+    <Box padding={3}>
+      <Root />
+      <Root />
+      <Root />
+    </Box>
+  )
+}
+
+function Root() {
+  const [open, setOpen] = useState(false)
+  const handleOpen = useCallback(() => setOpen(true), [])
+  const handleClose = useCallback(() => setOpen(false), [])
+
+  return (
+    <LayerProvider>
+      <Card radius={2} shadow={1}>
+        <Box padding={3}>
+          <Text>
+            <strong>Root layer</strong>
+          </Text>
+        </Box>
+        <Box padding={3}>
+          <Stack space={3}>
+            <LayerDebugInfo id="layer-debug-info-1" />
+            <Button id="open-layer-1" mode="ghost" onClick={handleOpen} text="Open layer 1" />
+            {open && (
+              <Layer style={{display: 'flex', alignItems: 'center', justifyContent: 'center'}}>
+                <Layer1 onClose={handleClose} />
+              </Layer>
+            )}
+          </Stack>
+        </Box>
+      </Card>
+    </LayerProvider>
+  )
+}
+
+function Layer1({onClose}: {onClose: () => void}) {
+  const [open, setOpen] = useState(false)
+  const handleOpen = useCallback(() => setOpen(true), [])
+  const handleClose = useCallback(() => setOpen(false), [])
+
+  return (
+    <Card radius={2} shadow={3}>
+      <Flex>
+        <Box flex={1} padding={3}>
+          <Text>
+            <strong>Layer 1</strong>
+          </Text>
+        </Box>
+        <Box padding={1}>
+          <Button icon={CloseIcon} mode="bleed" onClick={onClose} padding={2} />
+        </Box>
+      </Flex>
+      <Box padding={3}>
+        <Stack space={3}>
+          <LayerDebugInfo />
+          <Button id="open-layer-2" mode="ghost" onClick={handleOpen} text="Open layer 2" />
+          {open && (
+            <Layer style={{display: 'flex', alignItems: 'center', justifyContent: 'center'}}>
+              <Layer2 onClose={handleClose} />
+            </Layer>
+          )}
+        </Stack>
+      </Box>
+    </Card>
+  )
+}
+
+function Layer2({onClose}: {onClose: () => void}) {
+  return (
+    <Card radius={2} shadow={3}>
+      <Flex>
+        <Box flex={1} padding={3}>
+          <Text>
+            <strong>Layer 2</strong>
+          </Text>
+        </Box>
+        <Box padding={1}>
+          <Button icon={CloseIcon} mode="bleed" onClick={onClose} padding={2} />
+        </Box>
+      </Flex>
+      <Box padding={3}>
+        <Stack space={3}>
+          <LayerDebugInfo />
+        </Stack>
+      </Box>
+    </Card>
+  )
+}

package/src/core/utils/layer/__workshop__/responsiveZOffset.tsx

@@ -0,0 +1,13 @@
+import {Card, Layer} from '@bettercms-ai/kit'
+
+import {LayerDebugInfo} from './_debug'
+
+export default function ResponsiveZOffsetStory() {
+  return (
+    <Layer id="responsive-layer" zOffset={[1, 2, 3, 4, 5, 6, 7]}>
+      <Card padding={[1, 2, 3, 4, 5, 6, 7]} shadow={1}>
+        <LayerDebugInfo />
+      </Card>
+    </Layer>
+  )
+}

package/src/core/utils/layer/getLayerContext.test.ts

@@ -0,0 +1,30 @@
+import {getLayerContext} from './getLayerContext'
+import {LayerContextValue} from './types'
+
+describe('getLayerContext', () => {
+  describe('0.0', () => {
+    it('should convert 0.0 to 0.0', () => {
+      const contextValue: LayerContextValue = {
+        version: 0.0,
+        isTopLayer: true,
+        level: 0,
+        registerChild: () => () => {
+          //
+        },
+        size: 0,
+        zIndex: 0,
+      }
+
+      const result = getLayerContext(contextValue)
+
+      expect(result).toEqual({
+        version: 0.0,
+        isTopLayer: true,
+        level: 0,
+        registerChild: expect.any(Function),
+        size: 0,
+        zIndex: 0,
+      })
+    })
+  })
+})

package/src/core/utils/layer/getLayerContext.ts

@@ -0,0 +1,21 @@
+import {isRecord} from '../../lib/isRecord'
+import {LayerContextValue} from './types'
+
+export function getLayerContext(contextValue: LayerContextValue): LayerContextValue {
+  // NOTE: This check is for future-compatiblity
+  // - If the value is not an object, it’s not compatible with the current version
+  // - If the value is an object, but doesn’t have `version: 0.0`, it’s not compatible with the current version
+  if (!isRecord(contextValue) || contextValue.version !== 0.0) {
+    throw new Error('the context value is not compatible')
+  }
+
+  if (!contextValue) {
+    throw new Error('components using `useLayer()` should be wrapped in a <LayerProvider>.')
+  }
+
+  if (contextValue.version === 0.0) {
+    return contextValue
+  }
+
+  throw new Error('could not get layer context')
+}

package/src/core/utils/layer/index.ts

@@ -0,0 +1,4 @@
+export * from './layer'
+export * from './layerProvider'
+export * from './types'
+export * from './useLayer'