@bettercms-ai/kit 0.1.0

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

@@ -0,0 +1,63 @@
+import {useBoolean} from '@bettercms-ai/kit-workshop'
+
+import {Box} from '../../box'
+import {Button} from '../../button'
+import {Container} from '../../container'
+import {Flex} from '../../flex'
+import {Stack} from '../../stack'
+import {Text} from '../../text'
+import {Avatar} from '../avatar'
+import {AvatarStack} from '../avatarStack'
+
+export default function WithinButtonStory() {
+  const disabled = useBoolean('Disabled', false, 'Props')
+
+  return (
+    <Container width={1}>
+      <Stack paddingX={4} paddingY={[5, 6, 7]} space={1}>
+        <Button disabled={disabled} padding={1}>
+          <Flex align="center" gap={3} padding={2}>
+            <Box flex={1}>
+              <Text size={1}>Default button</Text>
+            </Box>
+            <Box flex="none">
+              <AvatarStack>
+                <Avatar color="blue" initials="AB" />
+                <Avatar color="magenta" initials="CD" />
+                <Avatar color="purple" initials="EF" />
+              </AvatarStack>
+            </Box>
+          </Flex>
+        </Button>
+        <Button disabled={disabled} mode="ghost" padding={1}>
+          <Flex align="center" gap={3} padding={2}>
+            <Box flex={1}>
+              <Text size={1}>Ghost button</Text>
+            </Box>
+            <Box flex="none">
+              <AvatarStack>
+                <Avatar color="blue" initials="AB" />
+                <Avatar color="magenta" initials="CD" />
+                <Avatar color="purple" initials="EF" />
+              </AvatarStack>
+            </Box>
+          </Flex>
+        </Button>
+        <Button disabled={disabled} mode="bleed" padding={1}>
+          <Flex align="center" gap={3} padding={2}>
+            <Box flex={1}>
+              <Text size={1}>Bleed button</Text>
+            </Box>
+            <Box flex="none">
+              <AvatarStack>
+                <Avatar color="blue" initials="AB" />
+                <Avatar color="magenta" initials="CD" />
+                <Avatar color="purple" initials="EF" />
+              </AvatarStack>
+            </Box>
+          </Flex>
+        </Button>
+      </Stack>
+    </Container>
+  )
+}

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

@@ -0,0 +1,70 @@
+import {useBoolean} from '@bettercms-ai/kit-workshop'
+
+import {Menu, MenuItem} from '../../../components'
+import {Layer} from '../../../utils'
+import {Box} from '../../box'
+import {Card} from '../../card'
+import {Container} from '../../container'
+import {Flex} from '../../flex'
+import {Text} from '../../text'
+import {Avatar} from '../avatar'
+import {AvatarStack} from '../avatarStack'
+
+export default function WithinMenuItemStory() {
+  const disabled = useBoolean('Disabled', false, 'Props')
+
+  return (
+    <Container width={1}>
+      <Layer>
+        <Box paddingX={4} paddingY={[5, 6, 7]}>
+          <Card radius={3} shadow={3}>
+            <Menu space={1}>
+              <MenuItem disabled={disabled} padding={0}>
+                <Flex align="center" gap={2} padding={2}>
+                  <Box flex={1}>
+                    <Text size={1}>Menu item 1</Text>
+                  </Box>
+                  <Box flex="none">
+                    <AvatarStack>
+                      <Avatar color="blue" initials="AB" />
+                      <Avatar color="magenta" initials="CD" />
+                      <Avatar color="purple" initials="EF" />
+                    </AvatarStack>
+                  </Box>
+                </Flex>
+              </MenuItem>
+              <MenuItem disabled={disabled} padding={0}>
+                <Flex align="center" gap={2} padding={2}>
+                  <Box flex={1}>
+                    <Text size={1}>Menu item 1</Text>
+                  </Box>
+                  <Box flex="none">
+                    <AvatarStack>
+                      <Avatar color="blue" initials="AB" />
+                      <Avatar color="magenta" initials="CD" />
+                      <Avatar color="purple" initials="EF" />
+                    </AvatarStack>
+                  </Box>
+                </Flex>
+              </MenuItem>
+              <MenuItem disabled={disabled} padding={0}>
+                <Flex align="center" gap={2} padding={2}>
+                  <Box flex={1}>
+                    <Text size={1}>Menu item 1</Text>
+                  </Box>
+                  <Box flex="none">
+                    <AvatarStack>
+                      <Avatar color="blue" initials="AB" />
+                      <Avatar color="magenta" initials="CD" />
+                      <Avatar color="purple" initials="EF" />
+                    </AvatarStack>
+                  </Box>
+                </Flex>
+              </MenuItem>
+            </Menu>
+          </Card>
+        </Box>
+      </Layer>
+    </Container>
+  )
+}

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

@@ -0,0 +1,200 @@
+import {ThemeColorAvatarColorKey} from '@bettercms-ai/kit/theme'
+import {forwardRef, useCallback, useEffect, useId, useState} from 'react'
+import ReactIs from 'react-is'
+import {styled} from 'styled-components'
+
+import {_getArrayProp} from '../../styles'
+import {useTheme_v2} from '../../theme'
+import {AvatarPosition, AvatarSize, AvatarStatus, ElementType, Props} from '../../types'
+import {Label} from '../label'
+import {avatarStyle, responsiveAvatarSizeStyle} from './styles'
+
+/**
+ * @public
+ */
+export interface AvatarOwnProps {
+  /** @beta */
+  __unstable_hideInnerStroke?: boolean
+  animateArrowFrom?: AvatarPosition
+  arrowPosition?: AvatarPosition
+  color?: ThemeColorAvatarColorKey
+  initials?: string
+  onImageLoadError?: (event: Error) => void
+  size?: AvatarSize | AvatarSize[]
+  src?: string
+  /**
+   * The status of the entity this Avatar represents.
+   * @alpha
+   */
+  status?: AvatarStatus
+  title?: string
+}
+
+/**
+ * @public
+ */
+export type AvatarProps<E extends ElementType = 'div'> = Props<AvatarOwnProps, E>
+
+const StyledAvatar = styled.div<{$color: ThemeColorAvatarColorKey; $size: AvatarSize[]}>(
+  responsiveAvatarSizeStyle,
+  avatarStyle.root,
+)
+
+const Arrow = styled.div(avatarStyle.arrow)
+
+const BgStroke = styled.ellipse(avatarStyle.bgStroke)
+
+const Stroke = styled.ellipse(avatarStyle.stroke)
+
+const Initials = styled.div(avatarStyle.initials)
+
+const InitialsLabel = styled(Label)({
+  color: 'inherit',
+})
+
+const AvatarImage = styled.svg(avatarStyle.image)
+
+const AvatarComponent = forwardRef(function Avatar(
+  props: AvatarOwnProps & {as?: ElementType} & Omit<React.HTMLProps<HTMLDivElement>, 'as' | 'ref'>,
+  ref: React.ForwardedRef<HTMLDivElement>,
+) {
+  const {
+    __unstable_hideInnerStroke,
+    as: asProp,
+    color = 'gray',
+    src,
+    title,
+    initials,
+    onImageLoadError,
+    arrowPosition: arrowPositionProp,
+    animateArrowFrom,
+    status = 'online',
+    size: sizeProp = 1,
+    ...restProps
+  } = props
+  const {avatar} = useTheme_v2()
+  const as = ReactIs.isValidElementType(asProp) ? asProp : 'div'
+  const size = _getArrayProp(sizeProp)
+
+  // eslint-disable-next-line no-warning-comments
+  // @todo: remove this
+  const avatarSize = avatar.sizes[size[0]] || avatar.sizes[0]
+  const _sizeRem = avatarSize.size
+  const _radius = _sizeRem / 2
+
+  const elementId = useId()
+  const [arrowPosition, setArrowPosition] = useState<AvatarPosition | undefined>(
+    animateArrowFrom || arrowPositionProp || 'inside',
+  )
+
+  const [imageFailed, setImageFailed] = useState<boolean>(false)
+
+  const imageId = `avatar-image-${elementId}`
+
+  useEffect(() => {
+    if (arrowPosition === arrowPositionProp) return undefined
+
+    // Start animation in the next frame
+    const raf = requestAnimationFrame(() => setArrowPosition(arrowPositionProp))
+
+    return () => cancelAnimationFrame(raf)
+  }, [arrowPosition, arrowPositionProp])
+
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    if (src) setImageFailed(false)
+  }, [src])
+
+  const handleImageError = useCallback(() => {
+    setImageFailed(true)
+
+    if (onImageLoadError) {
+      onImageLoadError(new Error('Avatar: the image failed to load'))
+    }
+  }, [onImageLoadError])
+
+  return (
+    <StyledAvatar
+      as={as}
+      data-as={typeof as === 'string' ? as : undefined}
+      data-ui="Avatar"
+      {...restProps}
+      $color={color}
+      $size={size}
+      aria-label={title}
+      data-arrow-position={arrowPosition}
+      data-status={status}
+      ref={ref}
+      title={title}
+    >
+      <Arrow>
+        <svg width="11" height="7" viewBox="0 0 11 7" fill="none">
+          <path
+            d="M6.67948 1.50115L11 7L0 7L4.32052 1.50115C4.92109 0.736796 6.07891 0.736795 6.67948 1.50115Z"
+            fill={color}
+          />
+        </svg>
+      </Arrow>
+
+      {!imageFailed && src && (
+        <AvatarImage viewBox={`0 0 ${_sizeRem} ${_sizeRem}`} fill="none">
+          <defs>
+            <pattern id={imageId} patternContentUnits="objectBoundingBox" width="1" height="1">
+              <image href={src} width="1" height="1" onError={handleImageError} />
+            </pattern>
+          </defs>
+
+          <circle cx={_radius} cy={_radius} r={_radius} fill={`url(#${imageId})`} />
+
+          {!__unstable_hideInnerStroke && (
+            <BgStroke
+              cx={_radius}
+              cy={_radius}
+              rx={_radius}
+              ry={_radius}
+              vectorEffect="non-scaling-stroke"
+            />
+          )}
+
+          <Stroke
+            cx={_radius}
+            cy={_radius}
+            rx={_radius}
+            ry={_radius}
+            vectorEffect="non-scaling-stroke"
+          />
+        </AvatarImage>
+      )}
+
+      {(imageFailed || !src) && initials && (
+        <>
+          <Initials>
+            <InitialsLabel
+              forwardedAs="span"
+              size={size.map((s) => {
+                if (s === 1) return 1
+                if (s === 2) return 3
+                if (s === 3) return 5
+
+                return 0
+              })}
+              weight="medium"
+            >
+              {initials}
+            </InitialsLabel>
+          </Initials>
+        </>
+      )}
+    </StyledAvatar>
+  )
+})
+AvatarComponent.displayName = 'ForwardRef(Avatar)'
+
+/**
+ * Avatars are used to represent people and other agents (e.g. bots).
+ *
+ * @public
+ */
+export const Avatar = AvatarComponent as unknown as <E extends ElementType = 'div'>(
+  props: AvatarProps<E>,
+) => React.JSX.Element

package/src/core/primitives/avatar/avatarCounter.tsx

@@ -0,0 +1,91 @@
+import {getTheme_v2} from '@bettercms-ai/kit/theme'
+import {forwardRef} from 'react'
+import {css, styled} from 'styled-components'
+
+import {EMPTY_RECORD} from '../../constants'
+import {_getArrayProp, _responsive, rem, ThemeProps} from '../../styles'
+import {AvatarSize} from '../../types'
+import {Label} from '../label'
+
+function _responsiveAvatarCounterSizeStyle(props: {$size: AvatarSize[]} & ThemeProps) {
+  const {avatar, media} = getTheme_v2(props.theme)
+
+  return _responsive(media, props.$size, (size) => {
+    const avatarSize = avatar.sizes[size]
+
+    if (!avatarSize) return EMPTY_RECORD
+
+    return {
+      borderRadius: rem(avatarSize.size / 2),
+      minWidth: rem(avatarSize.size),
+      height: rem(avatarSize.size),
+    }
+  })
+}
+
+function _avatarCounterBaseStyle(props: ThemeProps) {
+  const {space} = getTheme_v2(props.theme)
+
+  return css`
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    user-select: none;
+    color: inherit;
+    color: var(--card-fg-color);
+    background: var(--card-bg-color);
+    box-shadow:
+      0 0 0 1px var(--card-bg-color),
+      inset 0 0 0 1px var(--card-hairline-hard-color);
+    padding: 0 ${rem(space[2])};
+
+    &:not([hidden]) {
+      display: flex;
+    }
+  `
+}
+
+const StyledAvatarCounter = styled.div<{$size: AvatarSize[]}>(
+  _responsiveAvatarCounterSizeStyle,
+  _avatarCounterBaseStyle,
+)
+
+/**
+ * @public
+ */
+export interface AvatarCounterProps {
+  count: number
+  size?: AvatarSize | AvatarSize[]
+  /** @deprecated No longer supported. */
+  tone?: 'navbar'
+}
+
+/**
+ * @public
+ */
+export const AvatarCounter = forwardRef(function AvatarCounter(
+  props: AvatarCounterProps,
+  ref: React.Ref<HTMLDivElement>,
+) {
+  const {count, size: sizeProp = 1} = props
+  const size = _getArrayProp(sizeProp)
+
+  return (
+    <StyledAvatarCounter $size={size} data-ui="AvatarCounter" ref={ref}>
+      <Label
+        as="span"
+        size={size.map((s) => {
+          if (s === 1) return 1
+          if (s === 2) return 3
+          if (s === 3) return 5
+
+          return 0
+        })}
+        weight="medium"
+      >
+        {count}
+      </Label>
+    </StyledAvatarCounter>
+  )
+})
+AvatarCounter.displayName = 'ForwardRef(AvatarCounter)'

package/src/core/primitives/avatar/avatarStack.tsx

@@ -0,0 +1,100 @@
+import {getTheme_v2} from '@bettercms-ai/kit/theme'
+import {Children, cloneElement, forwardRef, isValidElement} from 'react'
+import {css, styled} from 'styled-components'
+
+import {EMPTY_RECORD} from '../../constants'
+import {_getArrayProp, _responsive, rem, ThemeProps} from '../../styles'
+import {AvatarSize} from '../../types'
+import {AvatarCounter} from './avatarCounter'
+
+const BASE_STYLES = css`
+  white-space: nowrap;
+
+  & > div {
+    vertical-align: top;
+
+    &:not([hidden]) {
+      display: inline-block;
+    }
+  }
+`
+
+function avatarStackStyle() {
+  return BASE_STYLES
+}
+
+function responsiveAvatarStackSizeStyle(props: {$size: AvatarSize[]} & ThemeProps) {
+  const {avatar, media} = getTheme_v2(props.theme)
+
+  return _responsive(media, props.$size, (size) => {
+    const avatarSize = avatar.sizes[size]
+
+    if (!avatarSize) return EMPTY_RECORD
+
+    return {
+      '& > div + div': {
+        marginLeft: rem(avatarSize.distance),
+      },
+    }
+  })
+}
+
+const StyledAvatarStack = styled.div<{$size: AvatarSize[]}>(
+  responsiveAvatarStackSizeStyle,
+  avatarStackStyle,
+)
+
+/**
+ * @public
+ */
+export interface AvatarStackProps {
+  children: React.ReactNode
+  maxLength?: number
+  size?: AvatarSize | AvatarSize[]
+  /** @deprecated No longer supported. */
+  tone?: 'navbar'
+}
+
+/**
+ * @public
+ */
+export const AvatarStack = forwardRef(function AvatarStack(
+  props: AvatarStackProps & Omit<React.HTMLProps<HTMLDivElement>, 'as' | 'ref'>,
+  ref: React.ForwardedRef<HTMLDivElement>,
+) {
+  const {
+    children: childrenProp,
+    maxLength: maxLengthProp = 4,
+    size: sizeProp = 1,
+    ...restProps
+  } = props
+  const children: React.JSX.Element[] = Children.toArray(childrenProp).filter(isValidElement)
+  const maxLength = Math.max(maxLengthProp, 0)
+  const size = _getArrayProp(sizeProp)
+
+  const len = children.length
+  const visibleCount = maxLength - 1
+  const extraCount = len - visibleCount
+  const visibleChildren = extraCount > 1 ? children.slice(extraCount, len) : children
+
+  return (
+    <StyledAvatarStack data-ui="AvatarStack" {...restProps} ref={ref} $size={size}>
+      {len === 0 && (
+        <div>
+          <AvatarCounter count={len} size={size} />
+        </div>
+      )}
+
+      {len !== 0 && extraCount > 1 && (
+        <div>
+          <AvatarCounter count={extraCount} size={size} />
+        </div>
+      )}
+
+      {visibleChildren.map((child, childIndex) => (
+        <div key={String(childIndex)}>{cloneElement(child, {size})}</div>
+      ))}
+    </StyledAvatarStack>
+  )
+})
+AvatarStack.displayName = 'ForwardRef(AvatarStack)'

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

@@ -0,0 +1,4 @@
+export * from './avatar'
+export * from './avatarCounter'
+export * from './avatarStack'
+export * from './types'

package/src/core/primitives/avatar/styles.ts

@@ -0,0 +1,167 @@
+import {CSSObject, getTheme_v2} from '@bettercms-ai/kit/theme'
+
+import {_responsive, rem, ThemeProps} from '../../styles'
+import {focusRingStyle} from '../../styles/internal'
+import {AvatarRootStyleProps, ResponsiveAvatarSizeStyleProps} from './types'
+
+export const avatarStyle = {
+  root: avatarRootStyle,
+  arrow: avatarArrowStyle,
+  bgStroke: avatarBgStrokeStyle,
+  stroke: avatarStrokeStyle,
+  initials: avatarInitialsStyle,
+  image: avatarImageStyle,
+}
+
+function avatarArrowStyle(): CSSObject {
+  return {
+    'position': 'absolute',
+    'boxSizing': 'border-box',
+    'zIndex': '0',
+    'opacity': '0',
+    'transition': 'all 0.2s linear',
+    'transform': 'rotate(-90deg) translate3d(0, 6px, 0)',
+    'left': 0,
+    'right': 0,
+    'top': 0,
+    'bottom': 0,
+
+    '& > svg': {
+      'width': '11px',
+      'height': '7px',
+      'position': 'absolute',
+      'top': '-5px',
+      'left': '50%',
+      'transform': 'translateX(-6px)',
+
+      '&:not([hidden])': {
+        display: 'block',
+      },
+    },
+
+    "[data-arrow-position='inside'] > &": {
+      transform: 'rotate(-90deg) translate3d(0, 6px, 0)',
+      opacity: '0',
+    },
+
+    "[data-arrow-position='top'] > &": {
+      opacity: '1',
+      transform: 'rotate(0deg)',
+    },
+
+    "[data-arrow-position='bottom'] > &": {
+      opacity: '1',
+      transform: 'rotate(-180deg)',
+    },
+  }
+}
+
+export function avatarRootStyle(props: AvatarRootStyleProps & ThemeProps): CSSObject {
+  const {$color} = props
+  const {avatar} = getTheme_v2(props.theme)
+
+  return {
+    '--avatar-bg-color': `var(--card-avatar-${$color}-bg-color)`,
+    '--avatar-fg-color': `var(--card-avatar-${$color}-fg-color)`,
+
+    'backgroundColor': 'var(--avatar-bg-color)',
+    'position': 'relative',
+    'boxSizing': 'border-box',
+    'userSelect': 'none',
+    'boxShadow': '0 0 0 1px var(--card-bg-color)',
+
+    '&[data-status="inactive"]': {
+      opacity: '0.5',
+    },
+
+    '&>svg': {
+      '&:not([hidden])': {
+        display: 'block',
+      },
+    },
+
+    /* &:is(button) */
+    '&[data-as="button"]': {
+      'WebkitFontSmoothing': 'inherit',
+      'appearance': 'none',
+      'margin': 0,
+      'padding': 0,
+      'border': 0,
+      'font': 'inherit',
+      'color': 'inherit',
+      'outline': 'none',
+
+      '&:focus': {
+        boxShadow: focusRingStyle({focusRing: avatar.focusRing}),
+      },
+
+      '&:focus:not(:focus-visible)': {
+        boxShadow: 'none',
+      },
+    },
+  }
+}
+
+export function responsiveAvatarSizeStyle(
+  props: ResponsiveAvatarSizeStyleProps & ThemeProps,
+): CSSObject[] {
+  const {avatar, media} = getTheme_v2(props.theme)
+
+  return _responsive(media, props.$size, (size) => {
+    const avatarSize = avatar.sizes[size] || avatar.sizes[0]
+
+    return {
+      'width': rem(avatarSize.size),
+      'height': rem(avatarSize.size),
+      'borderRadius': rem(avatarSize.size / 2),
+
+      '&>svg': {
+        width: rem(avatarSize.size),
+        height: rem(avatarSize.size),
+        borderRadius: rem(avatarSize.size / 2),
+      },
+    }
+  })
+}
+
+export function avatarImageStyle(): CSSObject {
+  return {
+    position: 'relative',
+  }
+}
+
+export function avatarInitialsStyle(): CSSObject {
+  return {
+    'width': '100%',
+    'height': '100%',
+    'color': 'var(--avatar-fg-color)',
+    'alignItems': 'center',
+    'justifyContent': 'center',
+    'textTransform': 'uppercase',
+    'textAlign': 'center',
+    'borderRadius': '50%',
+
+    '&:not([hidden])': {
+      display: 'flex',
+    },
+  }
+}
+
+function avatarBgStrokeStyle(): CSSObject {
+  return {
+    strokeWidth: '4px',
+    stroke: 'var(--card-bg-color)',
+  }
+}
+
+function avatarStrokeStyle(): CSSObject {
+  return {
+    'strokeWidth': '2px',
+    'stroke': 'var(--avatar-bg-color)',
+
+    '[data-status="editing"] &': {
+      strokeDasharray: '2 4',
+      strokeLinecap: 'round',
+    },
+  }
+}