@bettercms-ai/kit 0.1.0

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

@@ -0,0 +1,105 @@
+import {TreeState} from './types'
+
+export function _findPrevItemElement(
+  state: TreeState,
+  itemElements: HTMLElement[],
+  focusedElement: HTMLElement,
+): HTMLElement | null {
+  const idx = itemElements.indexOf(focusedElement)
+  const els = itemElements.slice(0, idx)
+  const len = els.length
+
+  for (let i = len - 1; i >= 0; i -= 1) {
+    const itemKey = els[i].getAttribute('data-tree-key')
+
+    if (!itemKey) {
+      continue
+    }
+
+    const segments = itemKey.split('/')
+
+    segments.pop()
+
+    const p: string[] = []
+
+    let expanded = true
+
+    for (let j = 0; j < segments.length; j += 1) {
+      p.push(segments[j])
+
+      const k = p.join('/')
+
+      if (!state[k]?.expanded) {
+        expanded = false
+        break
+      }
+    }
+
+    if (expanded) {
+      return els[i]
+    }
+  }
+
+  return null
+}
+
+export function _findNextItemElement(
+  state: TreeState,
+  itemElements: HTMLElement[],
+  focusedElement: HTMLElement,
+): HTMLElement | null {
+  const idx = itemElements.indexOf(focusedElement)
+  const els = itemElements.slice(idx)
+  const len = itemElements.length
+
+  for (let i = 1; i < len; i += 1) {
+    if (!els[i]) {
+      continue
+    }
+
+    const itemKey = els[i].getAttribute('data-tree-key')
+
+    if (!itemKey) {
+      continue
+    }
+
+    const segments = itemKey.split('/')
+
+    segments.pop()
+
+    const p: string[] = []
+
+    let expanded = true
+
+    for (let j = 0; j < segments.length; j += 1) {
+      p.push(segments[j])
+
+      const k = p.join('/')
+
+      if (!state[k]?.expanded) {
+        expanded = false
+        break
+      }
+    }
+
+    if (expanded) {
+      return els[i]
+    }
+  }
+
+  return null
+}
+
+export function _focusItemElement(el: HTMLElement): void {
+  if (el.getAttribute('role') === 'treeitem') {
+    el.focus()
+  }
+
+  if (el.getAttribute('role') === 'none') {
+    const firstChild = el.firstChild
+
+    if (firstChild && firstChild instanceof HTMLElement) {
+      firstChild.focus()
+    }
+  }
+}

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

@@ -0,0 +1,4 @@
+export * from './tree'
+export * from './treeItem'
+export * from './types'
+export * from './useTree'

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

@@ -0,0 +1,105 @@
+import {getTheme_v2} from '@bettercms-ai/kit/theme'
+import {css} from 'styled-components'
+
+import {rem, ThemeProps} from '../../styles'
+import {_cardColorStyle} from '../../styles/card'
+
+export function treeItemRootStyle(): ReturnType<typeof css> {
+  return css`
+    &[role='none'] > [role='treeitem'] {
+      outline: none;
+      cursor: default;
+      border-radius: 3px;
+
+      background-color: var(--card-bg-color);
+      color: var(--treeitem-fg-color);
+
+      &:focus {
+        position: relative;
+      }
+    }
+
+    &[role='treeitem'] {
+      outline: none;
+
+      & > div {
+        cursor: default;
+        border-radius: 3px;
+
+        background-color: var(--card-bg-color);
+        color: var(--treeitem-fg-color);
+      }
+
+      &:focus > div {
+        position: relative;
+      }
+    }
+  `
+}
+
+export function treeItemRootColorStyle(props: ThemeProps): ReturnType<typeof css> {
+  const $tone = 'default'
+  const {color} = getTheme_v2(props.theme)
+  const tone = color.selectable[$tone]
+
+  return css`
+    &[role='none'] {
+      & > [role='treeitem'] {
+        ${_cardColorStyle(color, tone.enabled)}
+      }
+
+      &[data-selected] > [role='treeitem'] {
+        ${_cardColorStyle(color, tone.pressed)}
+      }
+
+      @media (hover: hover) {
+        &:not([data-selected]) > [role='treeitem']:not(:focus):hover {
+          ${_cardColorStyle(color, tone.hovered)}
+        }
+
+        & > [role='treeitem']:focus {
+          ${_cardColorStyle(color, tone.selected)}
+        }
+      }
+    }
+
+    &[role='treeitem'] {
+      & > [data-ui='TreeItem__box'] {
+        ${_cardColorStyle(color, tone.enabled)}
+      }
+
+      &[data-selected] > [data-ui='TreeItem__box'] {
+        ${_cardColorStyle(color, tone.pressed)}
+      }
+
+      @media (hover: hover) {
+        &:not([data-selected]):not(:focus) > [data-ui='TreeItem__box']:hover {
+          ${_cardColorStyle(color, tone.hovered)}
+        }
+
+        &:focus > [data-ui='TreeItem__box'] {
+          ${_cardColorStyle(color, tone.selected)}
+        }
+      }
+    }
+  `
+}
+
+export interface TreeItemBoxStyleProps {
+  $level: number
+}
+
+export function treeItemBoxStyle(
+  props: TreeItemBoxStyleProps & ThemeProps,
+): ReturnType<typeof css> {
+  const {$level} = props
+  const {space} = getTheme_v2(props.theme)
+
+  return css`
+    padding-left: ${rem(space[2] * $level)};
+
+    &[data-as='a'] {
+      text-decoration: none;
+    }
+  `
+}

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

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

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

@@ -0,0 +1,240 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+
+import {Stack} from '../../primitives'
+import {_findNextItemElement, _findPrevItemElement, _focusItemElement} from './helpers'
+import {TreeContext} from './treeContext'
+import {TreeContextValue, TreeState} from './types'
+
+/**
+ * This API might change. DO NOT USE IN PRODUCTION.
+ * @beta
+ */
+export interface TreeProps {
+  gap?: number | number[]
+  /**
+   * @deprecated Use `gap` instead. `space` will be removed in v4.
+   */
+  space?: number | number[]
+}
+
+/**
+ * This API might change. DO NOT USE IN PRODUCTION.
+ * @beta
+ */
+export const Tree = forwardRef(function Tree(
+  props: TreeProps &
+    Omit<React.HTMLProps<HTMLUListElement>, 'align' | 'as' | 'height' | 'ref' | 'role' | 'wrap'>,
+  forwardedRef: React.ForwardedRef<HTMLUListElement>,
+): React.JSX.Element {
+  const {children, gap, space: deprecated_space = 1, onFocus, ...restProps} = props
+  const spacing = gap === undefined ? deprecated_space : gap
+  const ref = useRef<HTMLUListElement | null>(null)
+  const [focusedElement, setFocusedElement] = useState<HTMLElement | null>(null)
+  const focusedElementRef = useRef(focusedElement)
+  const path: string[] = useMemo(() => [], [])
+  const [itemElements, setItemElements] = useState<HTMLElement[]>([])
+  const [state, setState] = useState<TreeState>({})
+  const stateRef = useRef(state)
+
+  useImperativeHandle<HTMLUListElement | null, HTMLUListElement | null>(
+    forwardedRef,
+    () => ref.current,
+  )
+
+  useEffect(() => {
+    focusedElementRef.current = focusedElement
+  }, [focusedElement])
+
+  useEffect(() => {
+    stateRef.current = state
+  }, [state])
+
+  const registerItem = useCallback(
+    (element: HTMLElement, path: string, expanded: boolean, selected: boolean) => {
+      setState((s) => ({...s, [path]: {element, expanded}}))
+
+      if (selected) {
+        setFocusedElement(element)
+      }
+
+      return () => {
+        setState((s) => {
+          const newState = {...s}
+
+          delete newState[path]
+
+          return newState
+        })
+      }
+    },
+    [],
+  )
+
+  const setExpanded = useCallback((path: string, expanded: boolean) => {
+    setState((s) => {
+      const itemState = s[path]
+
+      if (!itemState) return s
+
+      return {...s, [path]: {...itemState, expanded}}
+    })
+  }, [])
+
+  const contextValue: TreeContextValue = useMemo(
+    () => ({
+      version: 0.0,
+      focusedElement: focusedElement || itemElements[0] || null,
+      level: 0,
+      path,
+      registerItem,
+      setExpanded,
+      setFocusedElement,
+      gap: spacing,
+      space: spacing,
+      state,
+    }),
+    [focusedElement, itemElements, path, registerItem, setExpanded, spacing, state],
+  )
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLUListElement>) => {
+      if (!focusedElementRef.current) return
+
+      if (event.key === 'ArrowDown') {
+        event.preventDefault()
+
+        const nextEl = _findNextItemElement(
+          stateRef.current,
+          itemElements,
+          focusedElementRef.current,
+        )
+
+        if (nextEl) {
+          _focusItemElement(nextEl)
+          setFocusedElement(nextEl)
+        }
+
+        return
+      }
+
+      if (event.key === 'ArrowUp') {
+        event.preventDefault()
+
+        const prevEl = _findPrevItemElement(
+          stateRef.current,
+          itemElements,
+          focusedElementRef.current,
+        )
+
+        if (prevEl) {
+          _focusItemElement(prevEl)
+          setFocusedElement(prevEl)
+        }
+
+        return
+      }
+
+      if (event.key === 'ArrowLeft') {
+        event.preventDefault()
+
+        const itemKey = focusedElementRef.current.getAttribute('data-tree-key')
+
+        if (!itemKey) return
+
+        const itemState = stateRef.current[itemKey]
+
+        if (!itemState) return
+
+        if (itemState.expanded) {
+          setState((s) => {
+            const itemState = s[itemKey]
+
+            if (!itemState) return s
+
+            return {...s, [itemKey]: {...itemState, expanded: false}}
+          })
+        } else {
+          const itemPath = itemKey.split('/')
+
+          itemPath.pop()
+
+          const parentKey = itemPath.join('/')
+          const parentState = parentKey && stateRef.current[parentKey]
+
+          if (parentState) {
+            parentState.element.focus()
+            setFocusedElement(parentState.element)
+          }
+        }
+
+        return
+      }
+
+      if (event.key === 'ArrowRight') {
+        event.preventDefault()
+
+        const focusedKey = focusedElementRef.current.getAttribute('data-tree-key')
+
+        if (!focusedKey) return
+
+        if (!stateRef.current[focusedKey]?.expanded) {
+          setState((s) => {
+            const itemState = s[focusedKey]
+
+            if (!itemState) return s
+
+            return {...s, [focusedKey]: {...itemState, expanded: true}}
+          })
+        }
+
+        return
+      }
+    },
+    [itemElements],
+  )
+
+  const handleFocus = useCallback(
+    (event: React.FocusEvent<HTMLUListElement>) => {
+      setFocusedElement(event.target)
+
+      // Call the element's `focus` handler
+      onFocus?.(event)
+    },
+    [onFocus],
+  )
+
+  useEffect(() => {
+    if (!ref.current) return
+    const _itemElements = Array.from(
+      ref.current.querySelectorAll('[data-ui="TreeItem"]'),
+    ) as HTMLElement[]
+
+    setItemElements(_itemElements)
+  }, [children])
+
+  return (
+    <TreeContext.Provider value={contextValue}>
+      <Stack
+        as="ul"
+        data-ui="Tree"
+        {...restProps}
+        onFocus={handleFocus}
+        onKeyDown={handleKeyDown}
+        ref={ref}
+        role="tree"
+        gap={spacing}
+      >
+        {children}
+      </Stack>
+    </TreeContext.Provider>
+  )
+})
+Tree.displayName = 'ForwardRef(Tree)'

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

@@ -0,0 +1,10 @@
+import {createGlobalScopedContext} from '../../lib/createGlobalScopedContext'
+import {TreeContextValue} from './types'
+
+/**
+ * @internal
+ */
+export const TreeContext = createGlobalScopedContext<TreeContextValue | null>(
+  '@bettercms-ai/kit/context/tree',
+  null,
+)

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

@@ -0,0 +1,28 @@
+import {Stack} from '../../primitives'
+import {useTree} from './useTree'
+
+export interface TreeGroupProps {
+  expanded?: boolean
+}
+
+export function TreeGroup(
+  props: TreeGroupProps &
+    Omit<React.HTMLProps<HTMLUListElement>, 'as' | 'height' | 'ref' | 'role' | 'wrap'>,
+): React.JSX.Element {
+  const {children, expanded = false, ...restProps} = props
+  const tree = useTree()
+
+  return (
+    <Stack
+      as="ul"
+      data-ui="TreeGroup"
+      {...restProps}
+      hidden={!expanded}
+      marginTop={tree.gap}
+      role="group"
+      gap={tree.gap}
+    >
+      {children}
+    </Stack>
+  )
+}

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

@@ -0,0 +1,65 @@
+/** @jest-environment jsdom */
+
+import {render} from '../../../../test'
+import {Box} from '../../primitives'
+import {TreeContext} from './treeContext'
+import {TreeItem} from './treeItem'
+import {TreeContextValue, TreeState} from './types'
+
+jest.mock('../../primitives', () => {
+  const actual = jest.requireActual('../../primitives')
+
+  return {
+    ...actual,
+    Box: jest.fn((props: Record<string, unknown>) => (actual.Box as any).render(props, null)),
+  }
+})
+
+const treeContextValue: TreeContextValue = {
+  version: 0.0,
+  focusedElement: null,
+  gap: 1,
+  level: 0,
+  path: [],
+  registerItem: () => () => undefined,
+  setExpanded: () => undefined,
+  setFocusedElement: () => undefined,
+  space: 1,
+  state: {} as TreeState,
+}
+
+function renderTreeItem(props: Partial<React.ComponentProps<typeof TreeItem>> = {}) {
+  return render(
+    <TreeContext.Provider value={treeContextValue}>
+      <TreeItem text="Item" {...props} />
+    </TreeContext.Provider>,
+  )
+}
+
+describe('components/treeItem spacing', () => {
+  const mockedBox = jest.mocked(Box)
+
+  beforeEach(() => {
+    mockedBox.mockClear()
+  })
+
+  it('should support `space` and `gap` with the same behavior', () => {
+    renderTreeItem({space: 2})
+    expect(mockedBox.mock.calls.map(([props]) => props)).toContainEqual(
+      expect.objectContaining({marginRight: 2}),
+    )
+
+    mockedBox.mockClear()
+    renderTreeItem({gap: 2})
+    expect(mockedBox.mock.calls.map(([props]) => props)).toContainEqual(
+      expect.objectContaining({marginRight: 2}),
+    )
+  })
+
+  it('should prefer `gap` over `space` when both are provided', () => {
+    renderTreeItem({gap: 3, space: 1})
+    const propsList = mockedBox.mock.calls.map(([props]) => props)
+    expect(propsList).toContainEqual(expect.objectContaining({marginRight: 3}))
+    expect(propsList).not.toContainEqual(expect.objectContaining({marginRight: 1}))
+  })
+})