@cerberus-design/react 0.14.2 → 0.15.0

package/src/components/Dialog.tsx

@@ -0,0 +1,165 @@
+import {
+  Dialog as ArkDialog,
+  type DialogContentProps as ArkDialogContentProps,
+  type DialogRootProps,
+  type DialogTitleProps,
+} from '@ark-ui/react'
+import {
+  dialog,
+  type DialogVariantProps,
+} from '@cerberus/styled-system/recipes'
+import { Portal } from './Portal'
+import { cx } from '@cerberus/styled-system/css'
+
+export type DialogProviderProps = DialogRootProps
+
+/**
+ * The provider that controls the dialog components.
+ * @definition [Dialog docs](https://cerberus.digitalu.design/react/dialog)
+ * @example
+ * ```tsx
+ * <DialogProvider>
+ *  <DialogTrigger asChild>
+ *    <Button>Open Dialog</Button>
+ *  </DialogTrigger>
+ *  <Dialog>
+ *    <Text>Dialog Content</Text>
+ *    <DialogCloseTrigger>Close</DialogCloseTrigger>
+ *  </Dialog>
+ * </DialogProvider>
+ * ```
+ */
+export function DialogProvider(props: DialogProviderProps) {
+  return <ArkDialog.Root {...props} />
+}
+
+export interface DialogProps
+  extends Omit<ArkDialogContentProps, 'size'>,
+    DialogVariantProps {}
+
+/**
+ * The content of the dialog. Must be used within the `DialogProvider` component.
+ * @definition [Dialog docs](https://cerberus.digitalu.design/react/dialog)
+ * @example
+ * ```tsx
+ * <DialogProvider>
+ *   <DialogTrigger asChild>
+ *    <Button>Open Dialog</Button>
+ *  </DialogTrigger>
+ *  <Dialog>
+ *    <Text>Dialog Content</Text>
+ *  </Dialog>
+ * </DialogProvider>
+ * ```
+ */
+export function Dialog(props: DialogProps) {
+  const { size, ...contentProps } = props
+  const styles = dialog({ size })
+  return (
+    <Portal>
+      <DialogBackdrop className={styles.backdrop} />
+      <DialogPositioner className={styles.positioner}>
+        <DialogContent className={styles.content} {...contentProps} />
+      </DialogPositioner>
+    </Portal>
+  )
+}
+
+/**
+ * The heading of the dialog. Must be used within the `DialogContent` component.
+ * @definition [Dialog docs](https://cerberus.digitalu.design/react/dialog)
+ * @example
+ * ```tsx
+ * <DialogProvider>
+ *   <DialogTrigger asChild>
+ *    <Button>Open Dialog</Button>
+ *  </DialogTrigger>
+ *  <Dialog>
+ *    <DialogHeading>Dialog Title</DialogHeading>
+ *    <Text>Dialog Content</Text>
+ *  </Dialog>
+ * </DialogProvider>
+ * ```
+ */
+export function DialogHeading(props: DialogTitleProps) {
+  const styles = dialog()
+  return (
+    <ArkDialog.Title {...props} className={cx(props.className, styles.title)} />
+  )
+}
+
+/**
+ * The description of the dialog. Must be used within the `DialogContent` component.
+ * @definition [Dialog docs](https://cerberus.digitalu.design/react/dialog)
+ * @example
+ * ```tsx
+ * <DialogProvider>
+ *   <DialogTrigger asChild>
+ *    <Button>Open Dialog</Button>
+ *  </DialogTrigger>
+ *  <Dialog>
+ *    <DialogHeading>Dialog Title</DialogHeading>
+ *    <DialogDescription>Dialog Description</DialogDescription>
+ *  </Dialog>
+ * </DialogProvider>
+ * ```
+ */
+export function DialogDescription(props: DialogTitleProps) {
+  const styles = dialog()
+  return (
+    <ArkDialog.Description
+      {...props}
+      className={cx(props.className, styles.description)}
+    />
+  )
+}
+
+/**
+ * The trigger that opens the dialog. Must be used within the `DialogProvider`
+ * component.
+ * @definition [Dialog docs](https://cerberus.digitalu.design/react/dialog)
+ * @example
+ * ```tsx
+ * <DialogTrigger asChild>
+ *  <Button>Open Dialog</Button>
+ * </DialogTrigger>
+ * ```
+ */
+export const DialogTrigger = ArkDialog.Trigger
+
+/**
+ * The trigger that closes the dialog. Must be used within the `DialogProvider`
+ * component.
+ * @definition [Dialog docs](https://cerberus.digitalu.design/react/dialog)
+ * @example
+ * ```tsx
+ * <DialogProvider>
+ *   <DialogTrigger asChild>
+ *    <Button>Open Dialog</Button>
+ *  </DialogTrigger>
+ *  <Dialog>
+ *    <Text>Dialog Content</Text>
+ *    <DialogCloseTrigger>Close</DialogCloseTrigger>
+ *  </Dialog>
+ * </DialogProvider>
+ * ```
+ */
+export const DialogCloseTrigger = ArkDialog.CloseTrigger
+
+/**
+ * The backdrop of the dialog. Must be used within the `DialogProvider`
+ * component.
+ */
+export const DialogBackdrop = ArkDialog.Backdrop
+
+/**
+ * The positioner of the dialog. Must be used within the `DialogProvider`
+ * component.
+ */
+export const DialogPositioner = ArkDialog.Positioner
+
+/**
+ * The content of the dialog. Must be used within the `DialogProvider`
+ * component.
+ */
+export const DialogContent = ArkDialog.Content

package/src/components/FileStatus.tsx

@@ -12,8 +12,8 @@ import {
 } from '@cerberus/styled-system/recipes'
 import { css, cx } from '@cerberus/styled-system/css'
 import { hstack, vstack } from '@cerberus/styled-system/patterns'
-import { $cerberusIcons } from '../config/defineIcons'
 import { Field } from '../context/field'
+import { useCerberusContext } from '../context/cerberus'
 import { FieldMessage } from './FieldMessage'
 import { ProgressBar, type ProgressBarProps } from './ProgressBar'
 import { IconButton } from './IconButton'
@@ -188,12 +188,13 @@ interface FileStatusElProps {
 }
 
 function MatchFileStatusIcon(props: FileStatusElProps) {
+  const { icons } = useCerberusContext()
   const {
     waitingFileUploader: TodoIcon,
     fileUploader: FileUploaderIcon,
     invalidAlt: InvalidIcon,
     successNotification: DoneIcon,
-  } = $cerberusIcons
+  } = icons
 
   switch (props.status) {
     case processStatus.TODO:
@@ -225,7 +226,8 @@ function MatchFileStatusText(props: FileStatusElProps) {
 }
 
 function MatchStatusAction(props: FileStatusElProps) {
-  const { close: CloseIcon, redo: RedoIcon, delete: TrashIcon } = $cerberusIcons
+  const { icons } = useCerberusContext()
+  const { close: CloseIcon, redo: RedoIcon, delete: TrashIcon } = icons
   switch (props.status) {
     case processStatus.TODO:
     case processStatus.PROCESSING:

package/src/components/FileUploader.tsx

@@ -5,7 +5,7 @@ import { vstack } from '@cerberus/styled-system/patterns'
 import { type InputHTMLAttributes } from 'react'
 import { Show } from './Show'
 import { fileUploader } from '@cerberus/styled-system/recipes'
-import { $cerberusIcons } from '../config/defineIcons'
+import { useCerberusContext } from '../context/cerberus'
 import { Avatar } from './Avatar'
 
 export interface FileUploaderProps
@@ -29,8 +29,9 @@ export interface FileUploaderProps
  * @see https://cerberus.digitalu.design/react/file-uploader
  */
 export function FileUploader(props: FileUploaderProps) {
+  const { icons } = useCerberusContext()
   const styles = fileUploader()
-  const { waitingFileUploader: Icon } = $cerberusIcons
+  const { waitingFileUploader: Icon } = icons
 
   return (
     <div

package/src/components/Input.tsx

@@ -4,7 +4,7 @@ import type { InputHTMLAttributes, ReactNode } from 'react'
 import { input, type InputVariantProps } from '@cerberus/styled-system/recipes'
 import { cx } from '@cerberus/styled-system/css'
 import { useFieldContext } from '../context/field'
-import { $cerberusIcons } from '../config/defineIcons'
+import { useCerberusContext } from '../context/cerberus'
 import { Show } from './Show'
 
 export interface InputBaseProps
@@ -39,7 +39,9 @@ export function Input(props: InputProps) {
   const inputStyles = input({ size })
   const { invalid, ...fieldStates } = useFieldContext()
   const hasEndIcon = Boolean(endIcon)
-  const { invalid: InvalidIcon } = $cerberusIcons
+
+  const { icons } = useCerberusContext()
+  const { invalid: InvalidIcon } = icons
 
   return (
     <div className={inputStyles.root}>

package/src/components/Modal.tsx

@@ -22,21 +22,6 @@ function ModalEl(props: ModalProps, ref: ForwardedRef<HTMLDialogElement>) {
 }
 
 /**
- * The Modal component is the root element for a customizable modal.
- * @see https://cerberus.digitalu.design/react/modal
- * @example
- * ```tsx
- * const { modalRef } = useModal()
- *
- * <Modal ref={modalRef}>
- *  <Avatar icon={SomeIcon} />
- *  <ModalHeader>
- *    <ModalHeading>Modal Heading</ModalHeading>
- *    <ModalDescription>Modal description</ModalDescription>
- *  </ModalHeader>
- *
- *  {props.children}
- * </Modal>
- * ```
+ * @deprecated use `Dialog` instead
  */
 export const Modal = forwardRef(ModalEl)

package/src/components/ModalDescription.tsx

@@ -10,14 +10,7 @@ import type { HTMLAttributes } from 'react'
 export type ModalDescriptionProps = HTMLAttributes<HTMLParagraphElement>
 
 /**
- * The ModalDescription component is a heading element for a customizable modal.
- * @see https://cerberus.digitalu.design/react/modal
- * @example
- * ```tsx
- * <Modal>
- *   <ModalDescription>Modal Heading</ModalDescription>
- * </Modal>
- * ```
+ * @deprecated use `DialogDescription` instead
  */
 export function ModalDescription(props: ModalDescriptionProps) {
   return <p {...props} className={cx(props.className, modal().description)} />

package/src/components/ModalHeader.tsx

@@ -10,16 +10,7 @@ import type { HTMLAttributes } from 'react'
 export type ModalHeaderProps = HTMLAttributes<HTMLDivElement>
 
 /**
- * The ModalHeader component is a header element for a customizable modal.
- * @see https://cerberus.digitalu.design/react/modal
- * @example
- * ```tsx
- * <Modal>
- *   <ModalHeader>
- *     <h2>Modal Heading</h2>
- *   </ModalHeader>
- * </Modal>
- * ```
+ * @deprecated there is no replacement for this component
  */
 export function ModalHeader(props: ModalHeaderProps) {
   return (

package/src/components/ModalHeading.tsx

@@ -10,14 +10,7 @@ import type { HTMLAttributes } from 'react'
 export type ModalHeadingProps = HTMLAttributes<HTMLParagraphElement>
 
 /**
- * The ModalHeading component is a heading element for a customizable modal.
- * @see https://cerberus.digitalu.design/react/modal
- * @example
- * ```tsx
- * <Modal>
- *   <ModalHeading>Modal Heading</ModalHeading>
- * </Modal>
- * ```
+ * @deprecated use `DialogHeading` instead
  */
 export function ModalHeading(props: ModalHeadingProps) {
   return <p {...props} className={cx(props.className, modal().heading)} />

package/src/components/Notification.tsx

@@ -12,8 +12,8 @@ import {
   type PropsWithChildren,
   type MouseEvent,
 } from 'react'
-import { $cerberusIcons } from '../config/defineIcons'
 import { trapFocus } from '../aria-helpers/trap-focus.aria'
+import { useCerberusContext } from '../context/cerberus'
 
 /**
  * This module exports the Notification component.
@@ -21,13 +21,14 @@ import { trapFocus } from '../aria-helpers/trap-focus.aria'
  */
 
 function MatchNotificationIcon(props: NotificationVariantProps) {
+  const { icons } = useCerberusContext()
   const palette = (props.palette || 'info') as
     | 'info'
     | 'success'
     | 'warning'
     | 'danger'
-  const key = `${palette}Notification` as keyof typeof $cerberusIcons
-  const Icon = $cerberusIcons[key]
+  const key = `${palette}Notification` as keyof typeof icons
+  const Icon = icons[key]
   return <Icon />
 }
 
@@ -62,13 +63,17 @@ export type NotificationProps = NotificationBaseProps & NotificationVariantProps
 export function Notification(props: PropsWithChildren<NotificationProps>) {
   const { children, palette, onClose, ...nativeProps } = props
   const ref = useRef<HTMLDialogElement>(null)
+
   const onKeyDown = trapFocus(ref)
   const styles = notification({ palette })
-  const { close: CloseIcon } = $cerberusIcons
+
+  const { icons } = useCerberusContext()
+  const { close: CloseIcon } = icons
 
   return (
     <dialog
       {...nativeProps}
+      data-placement="left"
       className={cx(
         nativeProps.className,
         hstack({

package/src/components/Select.tsx

@@ -7,8 +7,8 @@ import {
   type SelectVariantProps,
 } from '@cerberus/styled-system/recipes'
 import type { OptionHTMLAttributes, SelectHTMLAttributes } from 'react'
-import { $cerberusIcons } from '../config/defineIcons'
 import { useFieldContext } from '../context/field'
+import { useCerberusContext } from '../context/cerberus'
 import { Show } from './Show'
 
 /**
@@ -50,7 +50,10 @@ export type SelectProps = Omit<
 export function Select(props: SelectProps) {
   const { describedBy, size, ...nativeProps } = props
   const { invalid, ...fieldStates } = useFieldContext()
-  const { invalid: InvalidIcon, selectArrow: SelectArrow } = $cerberusIcons
+
+  const { icons } = useCerberusContext()
+  const { invalid: InvalidIcon, selectArrow: SelectArrow } = icons
+
   const styles = select({
     size,
   })

package/src/components/Tag.tsx

@@ -1,3 +1,5 @@
+'use client'
+
 import type {
   HTMLAttributes,
   MouseEventHandler,
@@ -10,7 +12,7 @@ import {
   tag,
   type TagVariantProps,
 } from '@cerberus/styled-system/recipes'
-import { $cerberusIcons } from '../config/defineIcons'
+import { useCerberusContext } from '../context/cerberus'
 
 /**
  * This module contains the tag component.
@@ -71,7 +73,8 @@ export function Tag(props: PropsWithChildren<TagProps>): JSX.Element {
   const isClosable = Boolean(onClick)
   const shape = isClosable ? 'pill' : initShape
   const closableStyles = isClosable ? closableCss : ''
-  const { close: Close } = $cerberusIcons
+  const { icons } = useCerberusContext()
+  const { close: Close } = icons
 
   return (
     <span

package/src/components/Toggle.tsx

@@ -7,8 +7,8 @@ import {
   type ToggleVariantProps,
 } from '@cerberus/styled-system/recipes'
 import type { InputHTMLAttributes } from 'react'
-import { $cerberusIcons } from '../config/defineIcons'
 import { useFieldContext } from '../context/field'
+import { useCerberusContext } from '../context/cerberus'
 
 /**
  * This module provides a toggle component.
@@ -59,7 +59,8 @@ export function Toggle(props: ToggleProps) {
   const { size, describedBy, ...nativeProps } = props
   const styles = toggle({ size })
   const { invalid, ...state } = useFieldContext()
-  const Icon = $cerberusIcons.toggleChecked
+  const { icons } = useCerberusContext()
+  const CheckedIcon = icons.toggleChecked
 
   return (
     <span
@@ -83,7 +84,7 @@ export function Toggle(props: ToggleProps) {
           }),
         )}
       >
-        <Icon />
+        <CheckedIcon />
       </span>
     </span>
   )

package/src/config/defineIcons.ts

@@ -1,22 +1,34 @@
-import { defaultIcons, type DefinedIcons } from './cerbIcons'
+import { CheckmarkIcon, IndeterminateIcon } from './icons/checkbox.icons'
+import { AnimatingUploadIcon } from '../components/AnimatingUploadIcon'
+import type { DefinedIcons, IconType } from './types'
 
-function _validateIconsProperties(icons: DefinedIcons) {
-  if (!icons.invalid) {
-    throw new Error(
-      'The an invalid property must be defined in your custom icons library.',
-    )
-  }
+const defaultIcons: Pick<
+  DefinedIcons,
+  'checkbox' | 'fileUploader' | 'indeterminate'
+> = {
+  checkbox: CheckmarkIcon,
+  fileUploader: AnimatingUploadIcon,
+  indeterminate: IndeterminateIcon,
 }
 
-export function defineIcons(icons: DefinedIcons): Required<DefinedIcons> {
-  _validateIconsProperties(icons)
-  $cerberusIcons = {
+/**
+ * Defines the icons that will be used in Cerberus React components via the
+ * CerberusProvider.
+ * @param icons The icons that will be used in Cerberus React components.
+ * @returns Icons object compatible with the CerberusProvider SystemConfig.
+ * @example
+ * ```tsx
+ * const icons = defineIcons({
+ *  accordionIndicator: MyAccordionIndicatorIcon,
+ *  ...
+ * })
+ * ```
+ */
+export function defineIcons<T extends IconType>(
+  icons: DefinedIcons,
+): Required<DefinedIcons<T>> {
+  return {
     ...defaultIcons,
     ...icons,
-  } as Required<DefinedIcons>
-  return $cerberusIcons
+  } as Required<DefinedIcons<T>>
 }
-
-// Default icons
-
-export let $cerberusIcons = defaultIcons as Required<DefinedIcons>

package/src/config/index.ts

@@ -0,0 +1,28 @@
+import type { SystemConfig } from './types'
+
+/**
+ * Create a system configuration object to be used on the CerberusProvider.
+ * @param options The system configuration options you want to customize.
+ * @returns A CerberusProvider-compatible system configuration object.
+ * @example
+ * ```tsx
+ * const icons = defineIcons({
+ *  accordionIndicator: MyAccordionIndicatorIcon,
+ *  ...
+ * })
+ * const config = makeSystemConfig({
+ *   icons,
+ * })
+ *
+ * // In your app
+ * <CerberusProvider config={config}>
+ *  <App />
+ * </CerberusProvider>
+ * ```
+ */
+export function makeSystemConfig(options: SystemConfig): SystemConfig {
+  return options
+}
+
+export * from './defineIcons'
+export * from './types'

package/src/config/types.ts

@@ -0,0 +1,42 @@
+import type { ElementType } from 'react'
+
+/**
+ * This module contains the types for the Cerberus React configuration.
+ * @module config.types
+ */
+
+export interface SystemConfig {
+  /**
+   * The icons that will be used in Cerberus React components.
+   */
+  icons: Required<DefinedIcons>
+}
+
+export interface DefinedIcons<T extends IconType = IconType> {
+  accordionIndicator: T
+  avatar: T
+  calendar: T
+  calendarPrev: T
+  calendarNext: T
+  checkbox?: T
+  close: T
+  confirmModal: T
+  delete: T
+  promptModal: T
+  waitingFileUploader: T
+  fileUploader?: T
+  indeterminate?: T
+  infoNotification: T
+  successNotification: T
+  warningNotification: T
+  dangerNotification: T
+  invalid: T
+  invalidAlt: T
+  redo: T
+  selectArrow: T
+  toggleChecked: T
+}
+
+// types
+
+export type IconType = ElementType

package/src/context/cerberus.tsx

@@ -0,0 +1,44 @@
+'use client'
+
+import { createContext, useContext, type PropsWithChildren } from 'react'
+import type { SystemConfig } from '../config'
+
+/**
+ * This  module contains the Cerberus configuration context and helpers.
+ * @module context/cerberus
+ */
+
+type CerberusContextValue = SystemConfig
+
+const CerberusContext = createContext<CerberusContextValue | null>(null)
+
+interface CerberusProviderProps {
+  config: SystemConfig
+}
+
+/**
+ * Cerberus configuration provider.
+ * @param props.config The Cerberus configuration created with
+ * `makeSystemConfig` helper.
+ */
+export function CerberusProvider(
+  props: PropsWithChildren<CerberusProviderProps>,
+) {
+  return (
+    <CerberusContext.Provider value={props.config}>
+      {props.children}
+    </CerberusContext.Provider>
+  )
+}
+
+/**
+ * Returns the Cerberus configuration context.
+ * @returns The Cerberus configuration context.
+ */
+export function useCerberusContext() {
+  const context = useContext(CerberusContext)
+  if (!context) {
+    throw new Error('useCerberus must be used within a CerberusProvider')
+  }
+  return context
+}