@bettercms-ai/kit 0.1.0

package/src/core/components/tree/treeItem.tsx

@@ -0,0 +1,224 @@
+import {ToggleArrowRightIcon} from '@bettercms-ai/icons'
+import {ThemeFontWeightKey} from '@bettercms-ai/kit/theme'
+import {startTransition, useCallback, useEffect, useId, useMemo, useRef, useState} from 'react'
+import {styled} from 'styled-components'
+
+import {Box, Flex, Text} from '../../primitives'
+import {ElementType} from '../../types'
+import {
+  treeItemBoxStyle,
+  TreeItemBoxStyleProps,
+  treeItemRootColorStyle,
+  treeItemRootStyle,
+} from './style'
+import {TreeContext} from './treeContext'
+import {TreeGroup} from './treeGroup'
+import {useTree} from './useTree'
+
+/**
+ * @beta
+ */
+export interface TreeItemProps {
+  expanded?: boolean
+  fontSize?: number | number[]
+  icon?: React.ElementType
+  /**
+   * Allows passing a custom element type to the link component
+   */
+  linkAs?: ElementType
+  padding?: number | number[]
+  gap?: number | number[]
+  /**
+   * @deprecated Use `gap` instead. `space` will be removed in v4.
+   */
+  space?: number | number[]
+  text?: React.ReactNode
+  weight?: ThemeFontWeightKey
+}
+
+const StyledTreeItem = styled.li(treeItemRootStyle, treeItemRootColorStyle)
+
+const TreeItemBox = styled(Box).attrs({forwardedAs: 'a'})<TreeItemBoxStyleProps>(treeItemBoxStyle)
+
+const ToggleArrowText = styled(Text)`
+  & > svg {
+    transition: transform 100ms;
+  }
+`
+
+/**
+ * This API might change. DO NOT USE IN PRODUCTION.
+ * @beta
+ */
+export function TreeItem(
+  props: TreeItemProps & Omit<React.HTMLProps<HTMLLIElement>, 'as' | 'ref' | 'role'>,
+): React.JSX.Element {
+  const {
+    children,
+    expanded: expandedProp = false,
+    fontSize = 1,
+    href,
+    icon: IconComponent,
+    id: idProp,
+    linkAs,
+    muted,
+    onClick,
+    padding = 2,
+    selected = false,
+    gap,
+    space: deprecated_space = 2,
+    text,
+    weight,
+    ...restProps
+  } = props
+  const spacing = gap === undefined ? deprecated_space : gap
+  const [rootElement, _setRootElement] = useState<HTMLLIElement | null>(null)
+  /**
+   * The startTransition wrapper here is to avoid an issue when on React 18 where this error can happen:
+   * >Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate. React limits the number of nested updates to prevent infinite loops.
+   * This doesn't happen on React 19 due to automatic batching of all state updates, the startTransition wrapper here gives a type of batching for 18 users in a way that still works with 19.
+   * NOTE: The startTransition wrapper is not needed in UI v4, since the baseline there is React 19.
+   */
+  const setRootElement = useCallback((node: HTMLLIElement | null) => {
+    startTransition(() => _setRootElement(node))
+  }, [])
+
+  const treeitemRef = useRef<HTMLDivElement | null>(null)
+  const tree = useTree()
+  const {path, registerItem, setExpanded, setFocusedElement} = tree
+  const _id = useId()
+  const id = idProp || _id
+  const [itemPath, itemKey] = useMemo(() => {
+    const itemPath = path.concat([id || ''])
+    return [itemPath, itemPath.join('/')]
+  }, [id, path])
+  const itemState = tree.state[itemKey]
+  const focused = tree.focusedElement === rootElement
+  const expanded = itemState?.expanded === undefined ? expandedProp : itemState?.expanded || false
+  const tabIndex = tree.focusedElement && tree.focusedElement === rootElement ? 0 : -1
+  const contextValue = useMemo(
+    () => ({...tree, level: tree.level + 1, path: itemPath}),
+    [itemPath, tree],
+  )
+
+  const handleClick = useCallback(
+    (event: React.MouseEvent<HTMLLIElement>) => {
+      if (onClick) onClick(event)
+
+      const target = event.target
+
+      if (
+        target instanceof HTMLElement &&
+        (target.getAttribute('data-ui') === 'TreeItem' ||
+          target.closest('[data-ui="TreeItem__box"]'))
+      ) {
+        event.stopPropagation()
+        setExpanded(itemKey, !expanded)
+        setFocusedElement(rootElement)
+      }
+    },
+    [expanded, itemKey, onClick, rootElement, setExpanded, setFocusedElement],
+  )
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLElement>) => {
+      if (focused && event.key === 'Enter') {
+        const el = treeitemRef.current || rootElement
+
+        el?.click()
+      }
+    },
+    [focused, rootElement],
+  )
+
+  useEffect(() => {
+    if (!rootElement) return
+
+    return registerItem(rootElement, itemKey, expanded, selected)
+  }, [expanded, itemKey, registerItem, rootElement, selected])
+
+  const content = (
+    <Flex padding={padding}>
+      <Box
+        marginRight={spacing}
+        style={{
+          visibility: IconComponent || children ? 'visible' : 'hidden',
+          pointerEvents: 'none',
+        }}
+      >
+        {IconComponent && (
+          <Text muted={muted} size={fontSize} weight={weight}>
+            <IconComponent />
+          </Text>
+        )}
+        {!IconComponent && (
+          <ToggleArrowText muted={muted} size={fontSize} weight={weight}>
+            <ToggleArrowRightIcon style={{transform: expanded ? 'rotate(90deg)' : undefined}} />
+          </ToggleArrowText>
+        )}
+      </Box>
+      <Box flex={1}>
+        <Text muted={muted} size={fontSize} textOverflow="ellipsis" weight={weight}>
+          {text}
+        </Text>
+      </Box>
+    </Flex>
+  )
+
+  if (href) {
+    return (
+      <StyledTreeItem
+        data-selected={selected ? '' : undefined}
+        data-tree-id={id}
+        data-tree-key={itemKey}
+        data-ui="TreeItem"
+        {...restProps}
+        onClick={handleClick}
+        ref={setRootElement}
+        role="none"
+      >
+        <TreeItemBox
+          $level={tree.level}
+          aria-expanded={expanded}
+          as={linkAs}
+          data-ui="TreeItem__box"
+          href={href}
+          ref={treeitemRef}
+          role="treeitem"
+          tabIndex={tabIndex}
+        >
+          {content}
+        </TreeItemBox>
+
+        <TreeContext.Provider value={contextValue}>
+          {children && <TreeGroup hidden={!expanded}>{children}</TreeGroup>}
+        </TreeContext.Provider>
+      </StyledTreeItem>
+    )
+  }
+
+  return (
+    <StyledTreeItem
+      data-selected={selected ? '' : undefined}
+      data-ui="TreeItem"
+      data-tree-id={id}
+      data-tree-key={itemKey}
+      {...restProps}
+      aria-expanded={expanded}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      ref={setRootElement}
+      role="treeitem"
+      tabIndex={tabIndex}
+    >
+      <TreeItemBox $level={tree.level} as="div" data-ui="TreeItem__box">
+        {content}
+      </TreeItemBox>
+
+      <TreeContext.Provider value={contextValue}>
+        {children && <TreeGroup expanded={expanded}>{children}</TreeGroup>}
+      </TreeContext.Provider>
+    </StyledTreeItem>
+  )
+}
+TreeItem.displayName = 'TreeItem'

package/src/core/components/tree/types.ts

@@ -0,0 +1,25 @@
+/**
+ * @beta
+ */
+export interface TreeState {
+  [key: string]: {element: HTMLElement; expanded: boolean} | undefined
+}
+
+/**
+ * @beta
+ */
+export interface TreeContextValue {
+  version: 0.0
+  focusedElement: HTMLElement | null
+  level: number
+  path: string[]
+  registerItem: (element: HTMLElement, path: string, expanded: boolean, selected: boolean) => void
+  setExpanded: (path: string, expanded: boolean) => void
+  setFocusedElement: (focusedElement: HTMLElement | null) => void
+  gap: number | number[]
+  /**
+   * @deprecated Use `gap` instead. `space` will be removed in v4.
+   */
+  space: number | number[]
+  state: TreeState
+}

package/src/core/components/tree/useTree.ts

@@ -0,0 +1,17 @@
+import {useContext} from 'react'
+
+import {TreeContext} from './treeContext'
+import {TreeContextValue} from './types'
+
+/**
+ * @beta
+ */
+export function useTree(): TreeContextValue {
+  const tree = useContext(TreeContext)
+
+  if (!tree) {
+    throw new Error('Tree: missing context value')
+  }
+
+  return tree
+}

package/src/core/constants.ts

@@ -0,0 +1,79 @@
+import type {Transition, Variant} from 'motion/react'
+
+/**
+ * @internal
+ */
+export const EMPTY_ARRAY: never[] = []
+
+/**
+ * @internal
+ */
+export const EMPTY_RECORD: Record<string, never> = {}
+
+const POPOVER_MOTION_DURATION = 0.2
+
+/**
+ * Shared `framer-motion` variants used by `Popover` and `Tooltip` components.
+ * @internal
+ */
+export const POPOVER_MOTION_PROPS: {
+  card: {
+    initial: Variant
+    hidden: Variant
+    visible: Variant
+    scaleIn: Variant
+    scaleOut: Variant
+  }
+  children: {
+    hidden: Variant
+    visible: Variant
+  }
+  transition: Transition
+} = {
+  card: {
+    initial: {
+      scale: 0.97,
+      willChange: 'transform',
+    },
+    hidden: {
+      opacity: 0,
+    },
+    visible: {
+      opacity: 1,
+      transition: {
+        when: 'beforeChildren',
+        duration: POPOVER_MOTION_DURATION / 2,
+      },
+    },
+    scaleIn: {
+      scale: 1,
+    },
+    scaleOut: {
+      scale: 0.97,
+    },
+  },
+  children: {
+    hidden: {
+      opacity: 0,
+    },
+    visible: {
+      opacity: 1,
+    },
+  },
+  transition: {
+    type: 'spring',
+    visualDuration: POPOVER_MOTION_DURATION,
+    bounce: 0.25,
+  },
+}
+
+/**
+ * @internal
+ * @deprecated No longer used.
+ */
+export const FLOATING_STATIC_SIDES: Record<string, 'bottom' | 'left' | 'top' | 'right'> = {
+  top: 'bottom',
+  right: 'left',
+  bottom: 'top',
+  left: 'right',
+}

package/src/core/helpers/animation.ts

@@ -0,0 +1,27 @@
+/**
+ * @internal
+ */
+export function _raf(fn: () => void): () => void {
+  const frameId = requestAnimationFrame(fn)
+
+  return () => {
+    cancelAnimationFrame(frameId)
+  }
+}
+
+/**
+ * @internal
+ */
+export function _raf2(fn: () => void): () => void {
+  let innerDispose: (() => void) | null = null
+
+  const outerDispose = _raf(() => {
+    innerDispose = _raf(fn)
+  })
+
+  return () => {
+    if (innerDispose) innerDispose()
+
+    outerDispose()
+  }
+}

package/src/core/helpers/element.ts

@@ -0,0 +1,55 @@
+/**
+ * @internal
+ */
+export function _isEnterToClickElement(element: HTMLElement): boolean {
+  return isHTMLAnchorElement(element) || isHTMLButtonElement(element)
+}
+
+/**
+ * @internal
+ */
+export function isHTMLElement(node: unknown): node is HTMLElement {
+  return node instanceof Node && node.nodeType === Node.ELEMENT_NODE
+}
+
+/**
+ * @internal
+ */
+export function isHTMLAnchorElement(element: unknown): element is HTMLAnchorElement {
+  return isHTMLElement(element) && element.nodeName === 'A'
+}
+
+/**
+ * @internal
+ */
+export function isHTMLInputElement(element: unknown): element is HTMLInputElement {
+  return isHTMLElement(element) && element.nodeName === 'INPUT'
+}
+
+/**
+ * @internal
+ */
+export function isHTMLButtonElement(element: unknown): element is HTMLButtonElement {
+  return isHTMLElement(element) && element.nodeName === 'BUTTON'
+}
+
+/**
+ * @internal
+ */
+export function isHTMLSelectElement(element: unknown): element is HTMLSelectElement {
+  return isHTMLElement(element) && element.nodeName === 'SELECT'
+}
+
+/**
+ * @internal
+ */
+export function isHTMLTextAreaElement(element: unknown): element is HTMLTextAreaElement {
+  return isHTMLElement(element) && element.nodeName === 'TEXTAREA'
+}
+
+/**
+ * @internal
+ */
+export function containsOrEqualsElement(element: HTMLElement, node: Node): boolean {
+  return element.contains(node) || element === node
+}

package/src/core/helpers/focus.ts

@@ -0,0 +1,100 @@
+import {
+  isHTMLAnchorElement,
+  isHTMLButtonElement,
+  isHTMLElement,
+  isHTMLInputElement,
+  isHTMLSelectElement,
+  isHTMLTextAreaElement,
+} from './element'
+
+// export const globalFocusState = {
+//   IgnoreUtilFocusChanges: false,
+// }
+
+/**
+ * @internal
+ */
+export function _hasFocus(element: HTMLElement): boolean {
+  return Boolean(document.activeElement) && element.contains(document.activeElement)
+}
+
+/**
+ * @internal
+ */
+export function isFocusable(element: HTMLElement): boolean {
+  if (
+    element.tabIndex > 0 ||
+    (element.tabIndex === 0 && element.getAttribute('tabIndex') !== null)
+  ) {
+    return true
+  }
+
+  if (isHTMLAnchorElement(element)) {
+    return Boolean(element.href) && element.rel !== 'ignore'
+  }
+
+  if (isHTMLInputElement(element)) {
+    return element.type !== 'hidden' && element.type !== 'file' && !element.disabled
+  }
+
+  if (
+    isHTMLButtonElement(element) ||
+    isHTMLSelectElement(element) ||
+    isHTMLTextAreaElement(element)
+  ) {
+    return !element.disabled
+  }
+
+  return false
+}
+
+/**
+ * @internal
+ */
+export function attemptFocus(element: HTMLElement): boolean {
+  if (!isFocusable(element)) {
+    return false
+  }
+
+  // globalFocusState.IgnoreUtilFocusChanges = true
+
+  try {
+    element.focus()
+  } catch {
+    // ignore
+  }
+
+  // globalFocusState.IgnoreUtilFocusChanges = false
+
+  return document.activeElement === element
+}
+
+/**
+ * @internal
+ */
+export function focusFirstDescendant(element: HTMLElement): boolean {
+  for (let i = 0; i < element.childNodes.length; i++) {
+    const child = element.childNodes[i]
+
+    if (isHTMLElement(child) && (attemptFocus(child) || focusFirstDescendant(child))) {
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * @internal
+ */
+export function focusLastDescendant(element: HTMLElement): boolean {
+  for (let i = element.childNodes.length - 1; i >= 0; i--) {
+    const child = element.childNodes[i]
+
+    if (isHTMLElement(child) && (attemptFocus(child) || focusLastDescendant(child))) {
+      return true
+    }
+  }
+
+  return false
+}

package/src/core/helpers/index.ts

@@ -0,0 +1,4 @@
+export * from './animation'
+export * from './element'
+export * from './focus'
+export * from './scroll'

package/src/core/helpers/scroll.ts

@@ -0,0 +1,15 @@
+/**
+ * @internal
+ */
+export function _isScrollable(el: Node): boolean {
+  if (!(el instanceof Element)) return false
+
+  const style = window.getComputedStyle(el)
+
+  return (
+    style.overflowX.includes('auto') ||
+    style.overflowX.includes('scroll') ||
+    style.overflowY.includes('auto') ||
+    style.overflowY.includes('scroll')
+  )
+}

package/src/core/hooks/index.ts

@@ -0,0 +1,12 @@
+export {type ArrayPropPrimitive, useArrayProp} from './useArrayProp'
+export * from './useClickOutside'
+export * from './useClickOutsideEvent'
+export * from './useCustomValidity'
+export * from './useElementRect'
+export * from './useElementSize'
+export * from './useForwardedRef'
+export * from './useGlobalKeyDown'
+export * from './useMatchMedia'
+export * from './useMediaIndex'
+export * from './usePrefersDark'
+export * from './usePrefersReducedMotion'

package/src/core/hooks/useArrayProp.ts

@@ -0,0 +1,17 @@
+import {useMemo} from 'react'
+
+import {_getArrayProp} from '../styles'
+
+/** @beta */
+export type ArrayPropPrimitive = string | number | boolean | undefined | null
+
+/**
+ * @deprecated instead of `useArrayProp(width)` use `Array.isArray(width) ? width : [width]` instead
+ * @beta
+ */
+export function useArrayProp<T extends ArrayPropPrimitive = ArrayPropPrimitive>(
+  val: T | T[] | undefined,
+  defaultVal?: T[],
+): T[] {
+  return useMemo(() => _getArrayProp(val, defaultVal), [val, defaultVal])
+}