@bettercms-ai/kit 0.1.0

package/src/core/hooks/usePrefersDark.hydration.test.tsx

@@ -0,0 +1,56 @@
+/** @jest-environment jsdom */
+/**
+ * As this hook is used for top-level theming it's likely to be called while server-rendering
+ * and that's why it's worth it to have a testing suite for hydration
+ */
+import {waitFor} from '@testing-library/dom'
+import {hydrateRoot} from 'react-dom/client'
+
+import {usePrefersDark} from './usePrefersDark'
+
+function Log() {
+  const dark = usePrefersDark()
+
+  return <>dark: {JSON.stringify(dark)}</>
+}
+
+const originalMatchMedia = window.matchMedia
+
+describe('usePrefersDark SSR hydration', () => {
+  beforeAll(() => {
+    window.matchMedia = () =>
+      ({
+        addEventListener: jest.fn(),
+        removeEventListener: jest.fn(),
+        matches: true,
+      }) as any
+  })
+
+  afterAll(() => {
+    window.matchMedia = originalMatchMedia
+  })
+
+  it(`hydrates without any warnings`, async () => {
+    const spy = jest.spyOn(console, 'error').mockImplementation()
+
+    const node = document.createElement('div')
+
+    document.body.appendChild(node)
+
+    node.innerHTML = `dark: <!-- -->false`
+
+    hydrateRoot(node, <Log />)
+
+    // It's false initially
+    await waitFor(() => expect(node.innerHTML).toBe('dark: <!-- -->false'))
+
+    // After hydration it should switch to true
+    await waitFor(() => expect(node.innerHTML).toBe('dark: <!-- -->true'))
+
+    // eslint-disable-next-line no-console
+    expect(console.error).not.toHaveBeenCalled()
+
+    spy.mockReset()
+    spy.mockRestore()
+  })
+})

package/src/core/hooks/usePrefersDark.test.tsx

@@ -0,0 +1,19 @@
+/** @jest-environment node */
+import {renderToStaticMarkup, renderToString} from 'react-dom/server'
+
+import {usePrefersDark} from './usePrefersDark'
+
+function Log() {
+  const dark = usePrefersDark()
+
+  return <>dark: {JSON.stringify(dark)}</>
+}
+
+describe('usePrefersDark', () => {
+  it(`SSR to static markup returns false`, () => {
+    expect(renderToStaticMarkup(<Log />)).toBe('dark: false')
+  })
+  it(`SSR to markup for hydration doesn't throw`, () => {
+    expect(renderToString(<Log />)).toMatchInlineSnapshot(`"dark: <!-- -->false"`)
+  })
+})

package/src/core/hooks/usePrefersDark.ts

@@ -0,0 +1,16 @@
+import {useMatchMedia} from './useMatchMedia'
+
+/**
+ * Returns true if a dark color scheme is preferred, false if a light color scheme is preferred or the preference is not known.
+ *
+ * @param getServerSnapshot - Only called during server-side rendering, and hydration if using hydrateRoot. Since the server environment doesn't have access to the DOM, we can't determine the current value of the media query and we assume `(prefers-color-scheme: light)` since it's the most common scheme (https://react.dev/reference/react/useSyncExternalStore#adding-support-for-server-rendering)
+ *
+ * If you persist the detected preference in a cookie or a header then you may implement your own server snapshot to read it.
+ * Chrome supports reading the `prefers-color-scheme` media query from a header if the server response: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-CH-Prefers-Color-Scheme
+ * @example https://gist.github.com/stipsan/13c0cccf8dfc34f4b44bb1b984baf7df
+ *
+ * @public
+ */
+export function usePrefersDark(getServerSnapshot = () => false): boolean {
+  return useMatchMedia('(prefers-color-scheme: dark)', getServerSnapshot)
+}

package/src/core/hooks/usePrefersReducedMotion.hydration.test.tsx

@@ -0,0 +1,56 @@
+/** @jest-environment jsdom */
+/**
+ * As this hook is used for top-level theming it's likely to be called while server-rendering
+ * and that's why it's worth it to have a testing suite for hydration
+ */
+import {waitFor} from '@testing-library/dom'
+import {hydrateRoot} from 'react-dom/client'
+
+import {usePrefersReducedMotion} from './usePrefersReducedMotion'
+
+function Log() {
+  const reduceMotion = usePrefersReducedMotion()
+
+  return <>prefers-motion: {JSON.stringify(reduceMotion)}</>
+}
+
+const originalMatchMedia = window.matchMedia
+
+describe('usePrefersReducedMotion SSR hydration', () => {
+  beforeAll(() => {
+    window.matchMedia = () =>
+      ({
+        addEventListener: jest.fn(),
+        removeEventListener: jest.fn(),
+        matches: true,
+      }) as any
+  })
+
+  afterAll(() => {
+    window.matchMedia = originalMatchMedia
+  })
+
+  it(`hydrates without any warnings`, async () => {
+    const spy = jest.spyOn(console, 'error').mockImplementation()
+
+    const node = document.createElement('div')
+
+    document.body.appendChild(node)
+
+    node.innerHTML = `prefers-motion: <!-- -->false`
+
+    hydrateRoot(node, <Log />)
+
+    // It's false initially
+    await waitFor(() => expect(node.innerHTML).toBe('prefers-motion: <!-- -->false'))
+
+    // After hydration it should switch to true
+    await waitFor(() => expect(node.innerHTML).toBe('prefers-motion: <!-- -->true'))
+
+    // eslint-disable-next-line no-console
+    expect(console.error).not.toHaveBeenCalled()
+
+    spy.mockReset()
+    spy.mockRestore()
+  })
+})

package/src/core/hooks/usePrefersReducedMotion.test.tsx

@@ -0,0 +1,19 @@
+/** @jest-environment node */
+import {renderToStaticMarkup, renderToString} from 'react-dom/server'
+
+import {usePrefersReducedMotion} from './usePrefersReducedMotion'
+
+function Log() {
+  const reduceMotion = usePrefersReducedMotion()
+
+  return <>prefers-motion: {JSON.stringify(reduceMotion)}</>
+}
+
+describe('usePrefersReducedMotion', () => {
+  it(`SSR to static markup returns false`, () => {
+    expect(renderToStaticMarkup(<Log />)).toBe('prefers-motion: false')
+  })
+  it(`SSR to markup for hydration doesn't throw`, () => {
+    expect(renderToString(<Log />)).toMatchInlineSnapshot(`"prefers-motion: <!-- -->false"`)
+  })
+})

package/src/core/hooks/usePrefersReducedMotion.ts

@@ -0,0 +1,16 @@
+import {useMatchMedia} from './useMatchMedia'
+
+/**
+ * Returns true if motion should be reduced
+ *
+ * @param getServerSnapshot - Only called during server-side rendering, and hydration if using hydrateRoot. Since the server environment doesn't have access to the DOM, we can't determine the current value of the media query and we assume `(prefers-reduced-motion: no-preference)` since it's the most common scheme (https://react.dev/reference/react/useSyncExternalStore#adding-support-for-server-rendering)
+ *
+ * If you persist the detected preference in a cookie or a header then you may implement your own server snapshot to read it.
+ * Chrome supports reading the `prefers-reduced-motion` media query from a header if the server response: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-CH-Prefers-Reduced-Motion
+ * @example https://gist.github.com/stipsan/0c0f839a27842249cada893e9fb7767b
+ *
+ * @public
+ */
+export function usePrefersReducedMotion(getServerSnapshot = () => false): boolean {
+  return useMatchMedia('(prefers-reduced-motion: reduce)', getServerSnapshot)
+}

package/src/core/index.ts

@@ -0,0 +1,10 @@
+export * from './_compat'
+export * from './components'
+export * from './helpers'
+export * from './hooks'
+export * from './observers'
+export * from './primitives'
+export * from './styles'
+export * from './theme'
+export * from './types'
+export * from './utils'

package/src/core/lib/createGlobalScopedContext.ts

@@ -0,0 +1,36 @@
+/**
+ * As `@bettercms-ai/kit` is declared as a dependency, and may be duplicated, sometimes across major versions
+ * it's critical that vital react contexts are shared even when there is a duplicate.
+ * If we used a model similar to `bcms` itself, or `styled-components`, this would be unnecessary as
+ * those libraries enforce single instances.
+ * Since we don't enforce it we have to support a bcms plugin being able to call hooks like `useToast`, and then
+ * read the context setup by `bcms`, which calls `ToastProvider`, even if the provider and hook are different instances in memory.
+ * It's also why it's vital that all changes to globally scoped providers remain fully backwards compatible to v1.
+ */
+
+import {type Context, createContext} from 'react'
+
+import {globalScope} from './globalScope'
+
+export function createGlobalScopedContext<ContextType, const T extends ContextType = ContextType>(
+  /**
+   * Enforce that all Symbol.for keys used for globally scoped contexts have a predictable prefix
+   */
+  key: `@bettercms-ai/kit/context/${string}`,
+  defaultValue: T,
+): Context<ContextType> {
+  const symbol = Symbol.for(key)
+
+  /**
+   * Prevent errors about re-renders on React SSR on Next.js App Router
+   */
+  if (typeof document === 'undefined') {
+    const context = createContext<ContextType>(defaultValue)
+    context.displayName = key
+    return context
+  }
+
+  globalScope[symbol] = globalScope[symbol] || createContext<T>(defaultValue)
+
+  return globalScope[symbol]
+}

package/src/core/lib/globalScope.ts

@@ -0,0 +1,19 @@
+/**
+ * Gets the global scope instance in a given environment.
+ *
+ * The strategy is to return the most modern, and if not, the most common:
+ * - The `globalThis` variable is the modern approach to accessing the global scope
+ * - The `window` variable is the global scope in a web browser
+ * - The `self` variable is the global scope in workers and others
+ * - The `global` variable is the global scope in Node.js
+ */
+function getGlobalScope() {
+  if (typeof globalThis !== 'undefined') return globalThis
+  if (typeof window !== 'undefined') return window
+  if (typeof self !== 'undefined') return self
+  if (typeof global !== 'undefined') return global
+
+  throw new Error('@bettercms-ai/kit: could not locate global scope')
+}
+
+export const globalScope = getGlobalScope() as any

package/src/core/lib/isRecord.ts

@@ -0,0 +1,3 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value))
+}

package/src/core/middleware/origin.ts

@@ -0,0 +1,47 @@
+import {Middleware} from '@floating-ui/react-dom'
+
+/**
+ * Custom floating-ui middleware which calculates transform-origin X + Y offsets
+ * based on the current floating rect's dimensions and shift offset.
+ *
+ * Scaling popovers with these transform-origin offsets will give the effect of
+ * popvers slightly 'growing' from the origin/reference element.
+ *
+ * This middleware must be applied after both `@bettercms-ai/kit/size` and `shift` middlewares.
+ */
+export const origin: Middleware = {
+  name: '@bettercms-ai/kit/origin',
+  fn({middlewareData, placement, rects}) {
+    const [side] = placement.split('-')
+
+    const floatingWidth = rects.floating.width
+    const floatingHeight = rects.floating.height
+
+    const shiftX = middlewareData.shift?.x || 0
+    const shiftY = middlewareData.shift?.y || 0
+
+    if (floatingWidth <= 0 || floatingHeight <= 0) {
+      return {}
+    }
+
+    const isVerticalPlacement = ['bottom', 'top'].includes(side)
+
+    const {originX, originY}: {originX: number; originY: number} = isVerticalPlacement
+      ? {
+          originX: clamp(0.5 - shiftX / floatingWidth, 0, 1),
+          originY: side === 'bottom' ? 0 : 1,
+        }
+      : {
+          originX: side === 'left' ? 1 : 0,
+          originY: clamp(0.5 - shiftY / floatingHeight, 0, 1),
+        }
+
+    return {
+      data: {originX, originY},
+    }
+  },
+}
+
+function clamp(num: number, min: number, max: number) {
+  return Math.min(Math.max(num, min), max)
+}

package/src/core/observers/elementSizeObserver.ts

@@ -0,0 +1,116 @@
+import {_ResizeObserver} from './resizeObserver'
+
+/**
+ * @beta
+ */
+export interface ElementRectValue {
+  width: number
+  height: number
+}
+
+/**
+ * @beta
+ */
+export interface ElementSize {
+  content: ElementRectValue
+  border: ElementRectValue
+
+  /** @deprecated INTERNAL ONLY */
+  _contentRect: DOMRectReadOnly
+}
+
+/**
+ * @internal
+ */
+export type _ElementSizeSubscriber = (elementRect: ElementSize) => void
+
+/**
+ * @internal
+ */
+export interface _ElementSizeObserver {
+  subscribe: (element: HTMLElement, subscriber: _ElementSizeSubscriber) => () => void
+}
+
+/**
+ * @internal
+ */
+export interface _ElementSizeListener {
+  subscribe: (element: HTMLElement, subscriber: _ElementSizeSubscriber) => () => void
+}
+
+// Initialize element size observer
+// NOTE: this should NOT have size effects
+/**
+ * @internal
+ */
+export const _elementSizeObserver = _createElementSizeObserver()
+
+function _createElementRectValueListener(): _ElementSizeListener {
+  return {
+    subscribe(element, subscriber) {
+      const resizeObserver = new _ResizeObserver(([entry]) => {
+        subscriber({
+          _contentRect: entry.contentRect,
+          border: {
+            width: entry.borderBoxSize[0].inlineSize,
+            height: entry.borderBoxSize[0].blockSize,
+          },
+          content: {
+            width: entry.contentRect.width,
+            height: entry.contentRect.height,
+          },
+        })
+      })
+
+      resizeObserver.observe(element)
+
+      return () => {
+        resizeObserver.unobserve(element)
+        resizeObserver.disconnect()
+      }
+    },
+  }
+}
+
+function _createElementSizeObserver(): _ElementSizeObserver {
+  const disposeCache = new WeakMap<HTMLElement, () => void>()
+  const subscribersCache = new WeakMap<HTMLElement, _ElementSizeSubscriber[]>()
+
+  return {
+    subscribe(element, subscriber) {
+      const subscribers = subscribersCache.get(element) || []
+
+      let dispose = disposeCache.get(element)
+
+      if (!subscribersCache.has(element)) {
+        subscribersCache.set(element, subscribers)
+
+        const listener = _createElementRectValueListener()
+
+        // listen
+        dispose = listener.subscribe(element, (elementRect) => {
+          for (const sub of subscribers) {
+            sub(elementRect)
+          }
+        })
+      }
+
+      subscribers.push(subscriber)
+
+      return () => {
+        // dispose
+
+        const idx = subscribers.indexOf(subscriber)
+
+        if (idx > -1) {
+          subscribers.splice(idx, 1)
+        }
+
+        if (subscribers.length === 0) {
+          // unlisten
+          if (dispose) dispose()
+        }
+      }
+    },
+  }
+}

package/src/core/observers/index.ts

@@ -0,0 +1,2 @@
+export * from './elementSizeObserver'
+export * from './resizeObserver'

package/src/core/observers/resizeObserver.ts

@@ -0,0 +1,9 @@
+import {ResizeObserver as ResizeObserverPolyfill} from '@juggle/resize-observer'
+
+/**
+ * @internal
+ */
+export const _ResizeObserver: typeof ResizeObserver =
+  typeof document !== 'undefined' && typeof window !== 'undefined' && window.ResizeObserver
+    ? window.ResizeObserver
+    : ResizeObserverPolyfill

package/src/core/primitives/_selectable/index.ts

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

package/src/core/primitives/_selectable/selectable.tsx

@@ -0,0 +1,15 @@
+import {styled} from 'styled-components'
+
+import {responsiveRadiusStyle, ResponsiveRadiusStyleProps} from '../../styles/radius'
+import {Box} from '../box'
+import {selectableBaseStyle, selectableColorStyle, SelectableStyleProps} from './style'
+
+/**
+ * @internal
+ */
+export const Selectable = styled(Box)<SelectableStyleProps & ResponsiveRadiusStyleProps>(
+  responsiveRadiusStyle,
+  selectableBaseStyle,
+  selectableColorStyle,
+)
+Selectable.displayName = 'Selectable'

package/src/core/primitives/_selectable/style.ts

@@ -0,0 +1,115 @@
+import {getTheme_v2} from '@bettercms-ai/kit/theme'
+import {css} from 'styled-components'
+
+import {ThemeProps} from '../../styles'
+import {_cardColorStyle} from '../../styles/card'
+import {SelectableTone} from '../../types'
+
+/**
+ * @internal
+ */
+export interface SelectableStyleProps {
+  $tone: SelectableTone
+}
+
+export function selectableBaseStyle(): ReturnType<typeof css> {
+  return css`
+    background-color: inherit;
+    color: inherit;
+
+    &[data-as='button'] {
+      -webkit-font-smoothing: inherit;
+      appearance: none;
+      outline: none;
+      font: inherit;
+      text-align: inherit;
+      border: 0;
+      width: -moz-available;
+      width: -webkit-fill-available;
+      width: stretch;
+    }
+
+    /* &:is(a) */
+    &[data-as='a'] {
+      text-decoration: none;
+    }
+  `
+}
+
+export function selectableColorStyle(
+  props: SelectableStyleProps & ThemeProps,
+): ReturnType<typeof css> {
+  const {$tone} = props
+  const {color, style} = getTheme_v2(props.theme)
+  const tone = color.selectable[$tone]
+
+  return css`
+    ${_cardColorStyle(color, tone.enabled)}
+
+    background-color: var(--card-bg-color);
+    color: var(--card-fg-color);
+    outline: none;
+
+    /* &:is(button) */
+    &[data-as='button'] {
+      &:disabled {
+        ${_cardColorStyle(color, tone.disabled)}
+      }
+
+      &:not(:disabled) {
+        &[aria-pressed='true'] {
+          ${_cardColorStyle(color, tone.pressed)}
+        }
+
+        &[data-selected],
+        &[aria-selected='true'] > & {
+          ${_cardColorStyle(color, tone.selected)}
+        }
+
+        @media (hover: hover) {
+          &:not([data-selected]) {
+            &[data-hovered],
+            &:hover {
+              ${_cardColorStyle(color, tone.hovered)}
+            }
+
+            &:active {
+              ${_cardColorStyle(color, tone.pressed)}
+            }
+          }
+        }
+      }
+    }
+
+    /* &:is(a) */
+    &[data-as='a'] {
+      &[data-disabled] {
+        ${_cardColorStyle(color, tone.disabled)}
+      }
+
+      &:not([data-disabled]) {
+        &[data-pressed] {
+          ${_cardColorStyle(color, tone.pressed)}
+        }
+
+        &[data-selected] {
+          ${_cardColorStyle(color, tone.selected)}
+        }
+
+        @media (hover: hover) {
+          &:not([data-selected]) {
+            &[data-hovered],
+            &:hover {
+              ${_cardColorStyle(color, tone.hovered)}
+            }
+            &:active {
+              ${_cardColorStyle(color, tone.pressed)}
+            }
+          }
+        }
+      }
+    }
+
+    ${style?.card?.root}
+  `
+}

package/src/core/primitives/avatar/__workshop__/asButton.tsx

@@ -0,0 +1,14 @@
+import {Avatar, Flex} from '@bettercms-ai/kit'
+import {useSelect} from '@bettercms-ai/kit-workshop'
+
+import {WORKSHOP_AVATAR_SIZE_OPTIONS} from '../../../__workshop__/constants'
+
+export default function AsButtonStory() {
+  const size = useSelect('Size', WORKSHOP_AVATAR_SIZE_OPTIONS, 1, 'Props')
+
+  return (
+    <Flex align="center" height="fill" justify="center">
+      <Avatar as="button" color="purple" initials="uq" size={size} />
+    </Flex>
+  )
+}

package/src/core/primitives/avatar/__workshop__/index.ts

@@ -0,0 +1,29 @@
+import {defineScope} from '@bettercms-ai/kit-workshop'
+import {lazy} from 'react'
+
+export default defineScope({
+  name: 'primitives/avatar',
+  title: 'Avatar',
+  stories: [
+    {
+      name: 'as-button',
+      title: 'As button',
+      component: lazy(() => import('./asButton')),
+    },
+    {
+      name: 'avatar-stack',
+      title: 'Avatar stack',
+      component: lazy(() => import('./stack')),
+    },
+    {
+      name: 'within-button',
+      title: 'Within button',
+      component: lazy(() => import('./withinButton')),
+    },
+    {
+      name: 'within-menu-item',
+      title: 'Within menu item',
+      component: lazy(() => import('./withinMenuItem')),
+    },
+  ],
+})

package/src/core/primitives/avatar/__workshop__/stack.tsx

@@ -0,0 +1,25 @@
+import {Avatar, AvatarCounter, AvatarStack, Flex} from '@bettercms-ai/kit'
+import {useSelect} from '@bettercms-ai/kit-workshop'
+
+import {WORKSHOP_AVATAR_SIZE_OPTIONS} from '../../../__workshop__/constants'
+
+export default function StackStory() {
+  const size = useSelect('Size', WORKSHOP_AVATAR_SIZE_OPTIONS, 1, 'Props')
+
+  return (
+    <Flex align="center" height="fill" justify="center">
+      <AvatarStack size={size}>
+        <AvatarCounter count={2} />
+        <Avatar color="magenta" initials="uq" />
+        <Avatar
+          color="purple"
+          src="https://avatars3.githubusercontent.com/u/406933?s=400&u=af898b0a50ef2ef1248be32dfa1410ccb55f6f65&v=4"
+        />
+        <Avatar
+          color="blue"
+          src="https://avatars3.githubusercontent.com/u/406933?s=400&u=af898b0a50ef2ef1248be32dfa1410ccb55f6f65&v=4"
+        />
+      </AvatarStack>
+    </Flex>
+  )
+}