@bettercms-ai/kit 0.1.0

package/src/core/components/toast/toast.tsx

@@ -0,0 +1,198 @@
+import {CloseIcon} from '@bettercms-ai/icons'
+import {motion, type Variant, type Variants} from 'motion/react'
+
+import {usePrefersReducedMotion} from '../../hooks/usePrefersReducedMotion'
+import {Box, Button, Flex, Stack, Text} from '../../primitives'
+import {
+  BUTTON_TONE,
+  LoadingBar,
+  LoadingBarMask,
+  LoadingBarProgress,
+  STATUS_CARD_TONE,
+  StyledToast,
+  TextBox,
+} from './styles'
+
+/**
+ * @public
+ */
+export interface ToastProps {
+  closable?: boolean
+  description?: React.ReactNode
+  onClose: () => void
+  radius?: number | number[]
+  title?: React.ReactNode
+  status?: 'error' | 'warning' | 'success' | 'info'
+  duration?: number
+  updatedAt?: number
+}
+
+const ROLES = {
+  error: 'alert',
+  warning: 'alert',
+  success: 'alert',
+  info: 'alert',
+} as const
+
+// Support pattern used by host apps, that works around the lack of `duration: Infinity` support in older @bettercms-ai/kit versions
+// https://developer.mozilla.org/en-US/docs/Web/API/setTimeout#maximum_delay_value
+const LONG_ENOUGH_BUT_NOT_TOO_LONG = 1000 * 60 * 60 * 24 * 24
+
+/**
+ * The `Toast` component gives feedback to users when an action has taken place.
+ *
+ * Toasts can be closed with a close button, or auto-dismiss after a certain timeout.
+ *
+ * @public
+ */
+export function Toast(
+  props: ToastProps &
+    Omit<
+      React.HTMLProps<HTMLDivElement>,
+      | 'as'
+      | 'height'
+      | 'ref'
+      | 'title'
+      | 'onAnimationStart'
+      | 'onDragStart'
+      | 'onDragEnd'
+      | 'onDrag'
+    >,
+): React.JSX.Element {
+  const {
+    closable,
+    description,
+    duration,
+    onClose,
+    radius = 3,
+    title,
+    status,
+    updatedAt,
+    ...restProps
+  } = props
+  const cardTone = status ? STATUS_CARD_TONE[status] : 'default'
+  const buttonTone = status ? BUTTON_TONE[status] : 'default'
+  const role = status ? ROLES[status] : 'status'
+
+  const prefersReducedMotion = usePrefersReducedMotion()
+
+  const visualDuration: number = prefersReducedMotion ? 0 : 0.26
+  const transition = visualDuration
+    ? {type: 'spring' as const, visualDuration, bounce: 0.25}
+    : {duration: 0}
+
+  const hasDuration = duration && isFinite(duration) && duration < LONG_ENOUGH_BUT_NOT_TOO_LONG
+  const initial: ContainerVariants[] = ['hidden', 'initial']
+  const animate: ContainerVariants[] = ['visible', 'slideIn']
+  const exit: ContainerVariants[] = ['hidden', 'slideOut']
+
+  return (
+    <MotionToast
+      data-ui="Toast"
+      role={role}
+      {...restProps}
+      data-has-duration={hasDuration ? '' : undefined}
+      custom={visualDuration}
+      radius={radius}
+      shadow={2}
+      tone={cardTone}
+      forwardedAs="li"
+      layout="position"
+      variants={container}
+      initial={initial}
+      animate={animate}
+      exit={exit}
+      transition={transition}
+    >
+      <MotionFlex align="flex-start" variants={content} transition={transition}>
+        <TextBox flex={1} padding={3}>
+          <Stack space={3}>
+            {title && (
+              <Text size={1} weight="medium">
+                {title}
+              </Text>
+            )}
+            {description && (
+              <MotionText muted size={1} variants={content} transition={transition}>
+                {description}
+              </MotionText>
+            )}
+          </Stack>
+        </TextBox>
+
+        {closable && (
+          <Box padding={1}>
+            <Button
+              as="button"
+              icon={CloseIcon}
+              mode="bleed"
+              padding={2}
+              tone={buttonTone}
+              onClick={onClose}
+              style={{verticalAlign: 'top'}}
+            />
+          </Box>
+        )}
+      </MotionFlex>
+      {hasDuration && (
+        <MotionLoadingBar variants={content} transition={transition}>
+          <LoadingBarMask tone={cardTone} radius={radius} />
+          <MotionLoadingBarProgress
+            key={`progress-${updatedAt}`}
+            tone={cardTone}
+            initial={{scaleX: 0}}
+            animate={{scaleX: 1}}
+            transition={{delay: visualDuration, duration: duration / 1_000, ease: 'linear'}}
+            onAnimationComplete={onClose}
+          />
+        </MotionLoadingBar>
+      )}
+    </MotionToast>
+  )
+}
+
+Toast.displayName = 'Toast'
+
+const container = {
+  initial: {y: 32, scale: 0.5, zIndex: 1},
+  hidden: {opacity: 0},
+  visible: (visualDuration: number) => {
+    if (!visualDuration) return {opacity: 1}
+
+    return {
+      opacity: 1,
+      transition: {
+        when: 'beforeChildren',
+        staggerChildren: visualDuration / 3,
+        duration: visualDuration / 3,
+      },
+    }
+  },
+  slideIn: {
+    y: 0,
+    scale: 1,
+  },
+  slideOut: {
+    zIndex: 0,
+    scale: 0.75,
+  },
+} satisfies Variants
+type ContainerVariants = keyof typeof container
+
+const content = {
+  initial: {
+    willChange: 'transform',
+  },
+  hidden: {
+    opacity: 0,
+  },
+  visible: {
+    opacity: 1,
+  },
+} satisfies Partial<Record<ContainerVariants, Variant>>
+
+const MotionToast = motion.create(StyledToast)
+const MotionFlex = motion.create(Flex)
+const MotionText = motion.create(Text)
+const MotionLoadingBar = motion.create(LoadingBar)
+const MotionLoadingBarProgress = motion.create(LoadingBarProgress)

package/src/core/components/toast/toastContext.ts

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

package/src/core/components/toast/toastLayer.tsx

@@ -0,0 +1,51 @@
+import {styled} from 'styled-components'
+
+import {Grid} from '../../primitives/grid'
+import {useLayer} from '../../utils'
+
+/**
+ * @public
+ */
+export interface ToastLayerProps {
+  children: React.ReactNode
+  padding?: number | number[]
+  paddingX?: number | number[]
+  paddingY?: number | number[]
+  gap?: number | number[]
+}
+
+/**
+ * @internal
+ */
+export function ToastLayer(props: ToastLayerProps): React.JSX.Element {
+  const {children, padding = 4, paddingX, paddingY, gap = 3} = props
+  const {zIndex} = useLayer()
+
+  return (
+    <StyledLayer
+      forwardedAs="ul"
+      data-ui="ToastProvider"
+      padding={padding}
+      paddingX={paddingX}
+      paddingY={paddingY}
+      gap={gap}
+      columns={1}
+      style={{zIndex}}
+    >
+      {children}
+    </StyledLayer>
+  )
+}
+
+ToastLayer.displayName = 'ToastLayer'
+
+const StyledLayer = styled(Grid)`
+  box-sizing: border-box;
+  position: fixed;
+  right: 0;
+  bottom: 0;
+  list-style: none;
+  pointer-events: none;
+  max-width: 420px;
+  width: 100%;
+`

package/src/core/components/toast/toastProvider.tsx

@@ -0,0 +1,113 @@
+import {AnimatePresence} from 'motion/react'
+import {startTransition, useMemo, useState} from 'react'
+
+import {useMounted} from '../../hooks/useMounted'
+import {LayerProvider} from '../../utils'
+import {Toast} from './toast'
+import {ToastContext} from './toastContext'
+import {ToastLayer, type ToastLayerProps} from './toastLayer'
+import {generateToastId} from './toastState'
+import {ToastContextValue, ToastParams} from './types'
+
+type ToastState = {
+  dismiss: () => void
+  id: string
+  updatedAt: number
+  params: ToastParams
+}[]
+
+/**
+ * @public
+ */
+export interface ToastProviderProps extends Omit<ToastLayerProps, 'children'> {
+  children?: React.ReactNode
+  zOffset?: number | number[]
+}
+
+/**
+ * @public
+ */
+export function ToastProvider(props: ToastProviderProps): React.JSX.Element {
+  const {children, padding, paddingX, paddingY, gap, zOffset = 1} = props
+  const [state, setState] = useState<ToastState>([])
+  const mounted = useMounted()
+
+  const value: ToastContextValue = useMemo(() => {
+    const push = (params: ToastParams) => {
+      const id = params.id || generateToastId()
+      const duration = params.duration || 5000
+
+      startTransition(() => {
+        setState((prevState): ToastState => {
+          /**
+           * Backwards compatibility for `bcms` patterns workaround a lack of programatically dismissible toasts.
+           * It uses a super short duration that closes the toast immediately in previous versions of `@bettercms-ai/kit`.
+           * We interpret this as a request to dismiss the toast immediately, and remove it from the state right away.
+           * Even once we support programatic dismissal we'll need to keep this for backwards compatibility with v2 and v1.
+           */
+          if (duration === 0.01) {
+            return prevState.filter((toast) => toast.id !== id)
+          }
+
+          /**
+           * Creates a function to dismiss this specific toast.
+           * This function will be passed to the Toast component
+           * and called either on close button click or after duration.
+           */
+          const dismiss = () =>
+            startTransition(() =>
+              setState((currentState) => currentState.filter((toast) => toast.id !== id)),
+            )
+
+          /**
+           * Create updated state by:
+           * 1. Removing any existing toast with the same ID (prevents duplicates)
+           * 2. Adding the new toast with its dismiss handler
+           * 3. Updates the `updatedAt` timestamp, which resets progress bar count downs.
+           */
+          return [
+            ...prevState.filter((toast) => toast.id !== id),
+            {
+              dismiss,
+              id,
+              updatedAt: Date.now(),
+              params: {...params, duration},
+            },
+          ]
+        })
+      })
+
+      return id
+    }
+
+    return {version: 0.0, push}
+  }, [])
+
+  return (
+    <ToastContext.Provider value={value}>
+      {children}
+      {mounted && (
+        <LayerProvider zOffset={zOffset}>
+          <ToastLayer padding={padding} paddingX={paddingX} paddingY={paddingY} gap={gap}>
+            <AnimatePresence initial={false} mode="popLayout">
+              {state.map(({dismiss, id, params, updatedAt}) => (
+                <Toast
+                  key={id}
+                  closable={params.closable}
+                  description={params.description}
+                  onClose={dismiss}
+                  status={params.status}
+                  title={params.title}
+                  duration={params.duration}
+                  updatedAt={updatedAt}
+                />
+              ))}
+            </AnimatePresence>
+          </ToastLayer>
+        </LayerProvider>
+      )}
+    </ToastContext.Provider>
+  )
+}
+
+ToastProvider.displayName = 'ToastProvider'

package/src/core/components/toast/toastState.ts

@@ -0,0 +1,6 @@
+let toastId = 0
+
+/** @internal */
+export function generateToastId(): string {
+  return String(toastId++)
+}

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

@@ -0,0 +1,26 @@
+/**
+ * @public
+ */
+export interface ToastParams {
+  closable?: boolean
+  description?: React.ReactNode
+  duration?: number
+  id?: string
+  onClose?: () => void
+  title?: React.ReactNode
+  status?: 'error' | 'warning' | 'success' | 'info'
+}
+
+/**
+ * @public
+ */
+export interface ToastContextValue {
+  version: 0.0
+  /**
+   * Creates or updates a toast notification.
+   * If a toast with the same ID already exists, it will be updated.
+   * If an ID is not provided, a random one will be generated.
+   * The returned ID can be used to programatically update a toast.
+   */
+  push: (params: ToastParams) => string
+}

package/src/core/components/toast/useToast.ts

@@ -0,0 +1,25 @@
+import {useContext} from 'react'
+
+import {isRecord} from '../../lib/isRecord'
+import {ToastContext} from './toastContext'
+import {ToastContextValue} from './types'
+
+/**
+ * @public
+ */
+export function useToast(): ToastContextValue {
+  const value = useContext(ToastContext)
+
+  if (!value) {
+    throw new Error('useToast(): missing context value')
+  }
+
+  // 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(value) || value.version !== 0.0) {
+    throw new Error('useToast(): the context value is not compatible')
+  }
+
+  return value
+}

package/src/core/components/tree/__workshop__/basic.perf.ts

@@ -0,0 +1,19 @@
+import {PerfTestProps, PerfTestRunFn} from '@bettercms-ai/kit-workshop/plugin-perf'
+import {findByTestId, fireEvent} from '@testing-library/dom'
+
+function test<ElementType = unknown>(
+  title: string,
+  run: PerfTestRunFn<ElementType>,
+): PerfTestProps<ElementType> {
+  return {name: title, run}
+}
+
+export const perfTests = [
+  test('Toggle tree groups', async ({target}: {target: HTMLUListElement}) => {
+    const apples = await findByTestId(target, 'apples')
+    const oranges = await findByTestId(target, 'oranges')
+
+    fireEvent.click(apples)
+    fireEvent.click(oranges)
+  }),
+]

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

@@ -0,0 +1,105 @@
+import {LinkIcon} from '@bettercms-ai/icons'
+import {Box, Tree, TreeItem} from '@bettercms-ai/kit'
+import {usePerfTest} from '@bettercms-ai/kit-workshop/plugin-perf'
+import {useCallback, useState} from 'react'
+
+import {perfTests} from './basic.perf'
+
+export default function BasicStory() {
+  const {ref, Wrapper} = usePerfTest(perfTests[0])
+
+  const [id, setId] = useState('')
+
+  const handleClick = useCallback((event: React.MouseEvent) => {
+    event.preventDefault()
+
+    const testid = event.currentTarget.getAttribute('data-testid')
+
+    if (testid) setId(testid)
+  }, [])
+
+  return (
+    <Box padding={[4, 5, 6]}>
+      <Wrapper>
+        <Tree ref={ref} space={1}>
+          <TreeItem onClick={handleClick} expanded text="Fruit">
+            <TreeItem
+              data-testid="oranges"
+              onClick={handleClick}
+              selected={id === 'oranges'}
+              text="Oranges"
+            />
+            <TreeItem
+              data-testid="pineapples"
+              onClick={handleClick}
+              text="Pineapples"
+              selected={id === 'pineapples'}
+            />
+            <TreeItem data-testid="apples" onClick={handleClick} text="Apples">
+              <TreeItem
+                data-testid="apples/macintosh"
+                onClick={handleClick}
+                href="/apples/macintosh"
+                icon={LinkIcon}
+                text="Macintosh"
+              />
+              <TreeItem
+                data-testid="apples/granny-smith"
+                onClick={handleClick}
+                text="Granny Smith"
+              />
+              <TreeItem data-testid="apples/fuji" onClick={handleClick} text="Fuji" />
+            </TreeItem>
+            <TreeItem onClick={handleClick} text="Bananas" />
+            <TreeItem onClick={handleClick} text="Pears">
+              <TreeItem onClick={handleClick} text="Anjou" />
+              <TreeItem onClick={handleClick} text="Bartlett" />
+              <TreeItem onClick={handleClick} text="Bosc" />
+              <TreeItem onClick={handleClick} text="Concorde" />
+              <TreeItem onClick={handleClick} text="Seckel" />
+              <TreeItem onClick={handleClick} text="Starkrimson" />
+            </TreeItem>
+          </TreeItem>
+          <TreeItem onClick={handleClick} text="Vegetables">
+            <TreeItem onClick={handleClick} text="Podded vegetables">
+              <TreeItem onClick={handleClick} text="Lentil" />
+              <TreeItem onClick={handleClick} text="Pea" />
+              <TreeItem onClick={handleClick} text="Peanut" />
+            </TreeItem>
+            <TreeItem onClick={handleClick} text="Bulb and stem vegetables">
+              <TreeItem onClick={handleClick} text="Asparagus" />
+              <TreeItem onClick={handleClick} text="Celery" />
+              <TreeItem onClick={handleClick} text="Leek" />
+              <TreeItem onClick={handleClick} text="Onion" />
+            </TreeItem>
+            <TreeItem onClick={handleClick} text="Root and tuberous vegetables">
+              <TreeItem onClick={handleClick} text="Carrot" />
+              <TreeItem onClick={handleClick} text="Ginger" />
+              <TreeItem onClick={handleClick} text="Parsnip" />
+              <TreeItem onClick={handleClick} text="Potato" />
+            </TreeItem>
+          </TreeItem>
+          <TreeItem onClick={handleClick} text="Grains">
+            <TreeItem onClick={handleClick} text="Cereal grains">
+              <TreeItem onClick={handleClick} text="Barley" />
+              <TreeItem onClick={handleClick} text="Oats" />
+              <TreeItem onClick={handleClick} text="Rice" />
+            </TreeItem>
+            <TreeItem onClick={handleClick} text="Pseudocereal grains">
+              <TreeItem onClick={handleClick} text="Amaranth" />
+              <TreeItem onClick={handleClick} text="Buckwheat" />
+              <TreeItem onClick={handleClick} text="Chia" />
+              <TreeItem onClick={handleClick} text="Quinoa" />
+            </TreeItem>
+            <TreeItem onClick={handleClick} text="Oilseeds">
+              <TreeItem onClick={handleClick} text="India mustard" />
+              <TreeItem onClick={handleClick} text="Safflower" />
+              <TreeItem onClick={handleClick} text="Flax seed" />
+              <TreeItem onClick={handleClick} text="Poppy seed" />
+            </TreeItem>
+          </TreeItem>
+        </Tree>
+      </Wrapper>
+    </Box>
+  )
+}

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

@@ -0,0 +1,21 @@
+import {defineScope} from '@bettercms-ai/kit-workshop'
+import {lazy} from 'react'
+
+export default defineScope({
+  name: 'components/tree',
+  title: 'Tree',
+  stories: [
+    {
+      name: 'basic',
+      title: 'Basic',
+      component: lazy(() => import('./basic')),
+      // options: {perfTests: () => import('./basic.perf')},
+    },
+    {
+      name: 'tab',
+      title: 'Tab',
+      component: lazy(() => import('./tabFromElement')),
+      // options: {perfTests: () => import('./basic.perf')},
+    },
+  ],
+})

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

@@ -0,0 +1,84 @@
+import {LinkIcon} from '@bettercms-ai/icons'
+import {Box, Text, TextInput, Tree, TreeItem} from '@bettercms-ai/kit'
+import {usePerfTest} from '@bettercms-ai/kit-workshop/plugin-perf'
+import {useCallback, useState} from 'react'
+
+import {perfTests} from './basic.perf'
+
+export default function BasicStory() {
+  const {ref, Wrapper} = usePerfTest(perfTests[0])
+
+  const [id, setId] = useState('')
+  const [focus, setFocus] = useState('')
+
+  const handleClick = useCallback((event: React.MouseEvent) => {
+    event.preventDefault()
+
+    const testid = event.currentTarget.getAttribute('data-testid')
+
+    if (testid) setId(testid)
+  }, [])
+
+  const handleFocus = useCallback((event: React.FocusEvent<HTMLElement>) => {
+    const elementFocus = event.target.getAttribute('data-testid')
+    if (elementFocus) setFocus(elementFocus)
+  }, [])
+
+  return (
+    <Box padding={[4, 5, 6]}>
+      <Box paddingY={3}>
+        <Text muted size={1}>
+          This example is to demonstrate that when you tab from an outside element (using the
+          keyboard to navigate), you can still access the tree and tree item. Press the input
+          beneath and start tabbing / using the arrow.
+        </Text>
+      </Box>
+      <Box paddingY={3}>
+        <Text>Focus: {focus}</Text>
+      </Box>
+      <Wrapper>
+        <TextInput />
+        <Tree ref={ref} space={1} onFocus={handleFocus}>
+          <TreeItem data-testid="fruit" onClick={handleClick} expanded text="Fruit">
+            <TreeItem
+              data-testid="oranges"
+              onClick={handleClick}
+              selected={id === 'oranges'}
+              text="Oranges"
+            />
+            <TreeItem
+              data-testid="pineapples"
+              onClick={handleClick}
+              text="Pineapples"
+              selected={id === 'pineapples'}
+            />
+            <TreeItem data-testid="apples" onClick={handleClick} text="Apples">
+              <TreeItem
+                data-testid="apples/macintosh"
+                onClick={handleClick}
+                href="/apples/macintosh"
+                icon={LinkIcon}
+                text="Macintosh"
+              />
+              <TreeItem
+                data-testid="apples/granny-smith"
+                onClick={handleClick}
+                text="Granny Smith"
+              />
+              <TreeItem data-testid="apples/fuji" onClick={handleClick} text="Fuji" />
+            </TreeItem>
+            <TreeItem data-testid="bananas" onClick={handleClick} text="Bananas" />
+            <TreeItem data-testid="pears" onClick={handleClick} text="Pears">
+              <TreeItem data-testid="pears/anjou" onClick={handleClick} text="Anjou" />
+              <TreeItem data-testid="pears/bartlett" onClick={handleClick} text="Bartlett" />
+              <TreeItem data-testid="pears/bosc" onClick={handleClick} text="Bosc" />
+              <TreeItem data-testid="pears/concorde" onClick={handleClick} text="Concorde" />
+              <TreeItem data-testid="pears/seckel" onClick={handleClick} text="Seckel" />
+              <TreeItem data-testid="pears/starkrimson" onClick={handleClick} text="Starkrimson" />
+            </TreeItem>
+          </TreeItem>
+        </Tree>
+      </Wrapper>
+    </Box>
+  )
+}