@cerberus-design/react 0.9.2 → 0.10.0

package/src/components/FileStatus.tsx

@@ -6,8 +6,6 @@ import {
   type HTMLAttributes,
   type MouseEvent,
 } from 'react'
-import { ProgressBar } from './ProgressBar'
-import { IconButton } from './IconButton'
 import {
   fileStatus,
   type FileStatusVariantProps,
@@ -15,8 +13,10 @@ import {
 import { css, cx } from '@cerberus/styled-system/css'
 import { hstack, vstack } from '@cerberus/styled-system/patterns'
 import { $cerberusIcons } from '../config/defineIcons'
-import { FieldMessage } from './FieldMessage'
 import { Field } from '../context/field'
+import { FieldMessage } from './FieldMessage'
+import { ProgressBar, type ProgressBarProps } from './ProgressBar'
+import { IconButton } from './IconButton'
 import { Avatar } from './Avatar'
 
 /**
@@ -24,13 +24,45 @@ import { Avatar } from './Avatar'
  * @module
  */
 
+/**
+ * The available values of the fileStatus helper Object.
+ * @example
+ * ```tsx
+ * import { fileStatus } from '@cerberus/react'
+ * processStatus.TODO // 'todo'
+ * ```
+ */
 export type FileStatusKey = (typeof processStatus)[keyof typeof processStatus]
+
+/**
+ * The actions that can be performed on a file.
+ */
 export type FileStatusActions = 'cancel' | 'retry' | 'delete'
 export interface FileBaseStatusProps
   extends Omit<HTMLAttributes<HTMLDivElement>, 'onClick'> {
+  /**
+   * The name of the file.
+   */
   file: string
-  now: number
+  /**
+   * The percentage of the file that has been processed.
+   */
+  now: ProgressBarProps['now']
+  /**
+   * The status of the file.
+   */
   status: processStatus
+  /**
+   * The action to perform on the file when a user clicks the
+   * button located at the end of the status card.
+   * @param status - The status of the file.
+   * @param e - The event object.
+   * @example
+   * ```tsx
+   * <FileStatus file="file.txt" now={0} status={processStatus.TODO} action={(status, e) => console.log(status, e)} />
+   * ```
+   * @default () => {}
+   */
   onClick: (status: FileStatusActions, e: MouseEvent<HTMLButtonElement>) => void
 }
 export type FileStatusProps = FileBaseStatusProps & FileStatusVariantProps
@@ -51,13 +83,8 @@ export const enum processStatus {
 }
 
 /**
- * This component displays the status of a file.
- * @param props - {
- *  file: string,
- *  now: number,
- *  status: keyof typeof fileStatus,
- *  action: (status: FileStatusActions, e: MouseEvent<HTMLButtonElement>) => void
- * }.
+ * A component that displays the status of a file during file processing.
+ * @see https://cerberus.digitalu.design/react/file-uploader
  * @example
  * ```tsx
  * <FileStatus file="file.txt" now={0} status={processStatus.TODO} action={(status, e) => console.log(status, e)} />
@@ -121,7 +148,7 @@ export function FileStatus(props: FileStatusProps) {
           {file}
         </small>
         <ProgressBar now={now} size="sm" />
-        <Field invalid={modalIconPalette === 'red'}>
+        <Field invalid={modalIconPalette === 'hades-dark'}>
           <FieldMessage
             className={css({
               color: 'page.text.100',
@@ -233,12 +260,12 @@ function getModalIconPalette(status: FileStatusKey) {
   switch (status) {
     case processStatus.TODO:
     case processStatus.PROCESSING:
-      return 'light-purple'
+      return 'charon-light'
     case processStatus.ERROR:
-      return 'red'
+      return 'hades-dark'
     case processStatus.DONE:
-      return 'green'
+      return 'thanatos-light'
     default:
-      return 'light-purple'
+      return 'charon-light'
   }
 }

package/src/components/FileUploader.tsx

@@ -10,10 +10,20 @@ import { Avatar } from './Avatar'
 
 export interface FileUploaderProps
   extends InputHTMLAttributes<HTMLInputElement> {
+  /**
+   * The optional heading to display in the FileUploader component.
+   */
   heading?: string
+  /**
+   * The name of the file input element.
+   */
   name: string
 }
 
+/**
+ * A component that allows the user to upload files.
+ * @see https://cerberus.digitalu.design/react/file-uploader
+ */
 export function FileUploader(props: FileUploaderProps) {
   const styles = fileUploader()
   const Icon = $cerberusIcons.fileUploader
@@ -29,7 +39,7 @@ export function FileUploader(props: FileUploaderProps) {
     >
       <div className={styles.icon}>
         <Avatar
-          gradient="light-purple"
+          gradient="charon-light"
           ariaLabel=""
           icon={<Icon />}
           size="md"

package/src/components/IconButton.tsx

@@ -1,6 +1,9 @@
 import type { ButtonHTMLAttributes } from 'react'
-import { cx, type RecipeVariantProps } from '@cerberus/styled-system/css'
-import { iconButton } from '@cerberus/styled-system/recipes'
+import { cx } from '@cerberus/styled-system/css'
+import {
+  iconButton,
+  type IconButtonVariantProps,
+} from '@cerberus/styled-system/recipes'
 import type { Positions } from '../types'
 
 /**
@@ -10,15 +13,22 @@ import type { Positions } from '../types'
 
 export interface IconButtonRawProps
   extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /**
+   * The aria-label attribute for the icon button.
+   */
   ariaLabel: string
+  /**
+   * The position of the tooltip relative to the icon button.
+   * @example 'top' | 'right' | 'bottom' | 'left'
+   * @default 'top'
+   */
   tooltipPosition?: Positions
 }
-export type IconButtonRecipeProps = RecipeVariantProps<typeof iconButton>
-export type IconButtonProps = IconButtonRawProps & IconButtonRecipeProps
+export type IconButtonProps = IconButtonRawProps & IconButtonVariantProps
 
 /**
  * A component that allows the user to perform actions using an icon
- * @description https://github.com/omnifed/cerberus/blob/main/packages/react/src/components/IconButton.tsx
+ * @see https://cerberus.digitalu.design/react/icon-button
  */
 export function IconButton(props: IconButtonProps): JSX.Element {
   const { ariaLabel, palette, usage, size, ...nativeProps } = props

package/src/components/Input.tsx

@@ -1,22 +1,39 @@
 'use client'
 
 import type { InputHTMLAttributes, ReactNode } from 'react'
-import { input } from '@cerberus/styled-system/recipes'
-import { cx, type RecipeVariantProps } from '@cerberus/styled-system/css'
+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 { Show } from './Show'
 
-export type InputRecipeProps = RecipeVariantProps<typeof input>
 export interface InputBaseProps
   extends Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'size'> {
+  /**
+   * The id of the FieldMessage component used to describe the input. Required for accessibility.
+   */
   describedBy?: string
+  /**
+   * The unique identifier for the input element. Required for accessibility.
+   */
   id: string
+  /**
+   * An optional icon to display at the start of the input.
+   */
   startIcon?: ReactNode
+  /**
+   * An optional icon to display at the end of the input.
+   */
   endIcon?: ReactNode
 }
-export type InputProps = InputBaseProps & InputRecipeProps
+export type InputProps = InputBaseProps & InputVariantProps
 
+/**
+ * A component that allows the user to input text. Must be wrapped in a Field
+ * component to keep track of the state for entire group of elements related to
+ * the field.
+ * @see https://cerberus.digitalu.design/react/input
+ */
 export function Input(props: InputProps) {
   const { describedBy, size, startIcon, endIcon, ...nativeProps } = props
   const inputStyles = input({ size })

package/src/components/Label.tsx

@@ -1,8 +1,8 @@
 'use client'
 
 import type { HTMLAttributes, PropsWithChildren } from 'react'
-import { label } from '@cerberus/styled-system/recipes'
-import { css, cx, type RecipeVariantProps } from '@cerberus/styled-system/css'
+import { label, type LabelVariantProps } from '@cerberus/styled-system/recipes'
+import { css, cx } from '@cerberus/styled-system/css'
 import { hstack } from '@cerberus/styled-system/patterns'
 import { useFieldContext } from '../context/field'
 import { Show } from './Show'
@@ -11,22 +11,27 @@ import { Show } from './Show'
  * This module contains the Label component.
  * @module
  */
-
-export type LabelRecipeProps = RecipeVariantProps<typeof label>
 export interface LabelBaseProps extends HTMLAttributes<HTMLLabelElement> {
+  /**
+   * The unique identifier for the input element. Required for accessibility.
+   */
   htmlFor: string
+  /**
+   * Used to hide the label from the UI while keeping it accessible to screen readers. Typically used for global search inputs that have no visible label.
+   */
   hidden?: boolean
 }
-export type LabelProps = LabelBaseProps & LabelRecipeProps
+export type LabelProps = LabelBaseProps & LabelVariantProps
 
 /**
- * A screen ready friendly label component.
+ * A a11y compliant label component.
  * @definition [ARIA Forms](https://www.a11yproject.com/checklist/#forms)
- * @definition [Label docs](https://cerberus.digitalu.design/react/label)
+ * @see https://cerberus.digitalu.design/react/label
  * @example
  * ```tsx
  * <Field required>
- *   <Label htmlFor="test">Test Label</Label>
+ *   <Label htmlFor="search" hidden>Search everything</Label>
+ *   <Input id="search" startIcon={Search} type="text" />
  * </Field>
  * ```
  */

package/src/components/Modal.tsx

@@ -23,14 +23,19 @@ 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}>
- *  <ModalIcon icon={$cerberusIcons.alert} />
- *  <h2>Modal Heading</h2>
- *  <p>Modal description</p>
+ *  <Avatar icon={SomeIcon} />
+ *  <ModalHeader>
+ *    <ModalHeading>Modal Heading</ModalHeading>
+ *    <ModalDescription>Modal description</ModalDescription>
+ *  </ModalHeader>
+ *
+ *  {props.children}
  * </Modal>
  * ```
  */

package/src/components/ModalDescription.tsx

@@ -11,6 +11,7 @@ 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>

package/src/components/ModalHeader.tsx

@@ -11,6 +11,7 @@ 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>

package/src/components/ModalHeading.tsx

@@ -11,6 +11,7 @@ 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>

package/src/components/NavMenuLink.tsx

@@ -2,11 +2,33 @@ import type { AnchorHTMLAttributes, ElementType } from 'react'
 import { css, cx } from '@cerberus/styled-system/css'
 import { Show } from './Show'
 
+/**
+ * This module contains the NavMenuLink component.
+ * @module
+ */
+
 export interface NavMenuLinkProps
   extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  /**
+   * The element type to render as. Recommended to use for Next apps with the
+   * `Link` component.
+   */
   as?: ElementType
 }
 
+/**
+ * The NavMenuLink component is a link element that is used within the NavMenu.
+ * @see https://cerberus.digitalu.design/react/nav-menu
+ * @example
+ * ```tsx
+ * <NavMenu>
+ *  <NavMenuList id="nav-menu-list" position="bottom">
+ *   <NavMenuLink href="/home">Home</NavMenuLink>
+ *   <NavMenuLink href="/about">About</NavMenuLink>
+ *  </NavMenuList>
+ * </NavMenu>
+ * ```
+ */
 export function NavMenuLink(props: NavMenuLinkProps): JSX.Element {
   const { as, ...nativeProps } = props
   const hasAs = Boolean(as)

package/src/components/NavMenuList.tsx

@@ -7,13 +7,35 @@ import { useNavMenuContext } from '../context/navMenu'
 import type { Positions } from '../types'
 import { Show } from './Show'
 
+/**
+ * This module contains the NavMenuList component.
+ * @module
+ */
+
 interface GetPositionResult {
+  /**
+   * The left position of the element.
+   */
   left: string
+  /**
+   * The right position of the element.
+   */
   right: string
+  /**
+   * The top position of the element.
+   */
   top: string
+  /**
+   * The bottom position of the element.
+   */
   bottom: string
 }
 
+/**
+ * Returns the position of the NavMenuList based on the position prop.
+ * @param position - The position of the NavMenuList.
+ * @returns The position of the NavMenuList.
+ */
 export function getPosition(position: Positions): GetPositionResult {
   const defaultPositions = {
     left: 'auto',
@@ -67,21 +89,31 @@ const navListStyles = vstack({
 })
 
 export interface NavMenuListProps extends HTMLAttributes<HTMLUListElement> {
+  /**
+   * The unique identifier for the NavMenuList. Required for accessibility.
+   */
   id: string
+  /**
+   * The position of the NavMenuList.
+   * @type 'top' | 'right' | 'bottom' | 'left'
+   * @default 'bottom'
+   */
   position?: Positions
 }
 
 /**
  * A component that allows the user to display a menu of navigation links.
  * @definition [Disclosure Nav](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/)
- * @definition [NavMenu Docs](https://cerberus.digitalu.design/react/nav-menu)
+ * @see https://cerberus.digitalu.design/react/nav-menu
  *
  * @example
  * ```tsx
- * <NavMenuList id="nav-menu-list" position="bottom">
- *  <NavMenuLink href="/home">Home</NavMenuLink>
- * <NavMenuLink href="/about">About</NavMenuLink>
- * </NavMenuList>
+ * <NavMenu>
+ *  <NavMenuList id="nav-menu-list" position="bottom">
+ *   <NavMenuLink href="/home">Home</NavMenuLink>
+ *   <NavMenuLink href="/about">About</NavMenuLink>
+ *  </NavMenuList>
+ * </NavMenu>
  * ```
  **/
 export function NavMenuList(props: NavMenuListProps): JSX.Element {

package/src/components/NavMenuTrigger.tsx

@@ -16,10 +16,23 @@ import { useNavMenuContext } from '../context/navMenu'
 import type { ButtonProps } from './Button'
 import { Show } from './Show'
 
+/**
+ * This module contains the NavMenuTrigger component.
+ * @module
+ */
+
 export interface NavMenuTriggerProps
   extends ButtonHTMLAttributes<HTMLButtonElement>,
     ButtonProps,
     NavTriggerAriaValues {
+  /**
+   * The element type to render as. Recommended to use for an IconButton trigger vs a standard Button.
+   * @default 'button'
+   * @example
+   * ```tsx
+   * <NavMenuTrigger as={IconButton} href="/home" />
+   * ```
+   */
   as?: ElementType
 }
 

package/src/components/Notification.tsx

@@ -31,22 +31,29 @@ function MatchNotificationIcon(props: NotificationVariantProps) {
 
 export interface NotificationBaseProps
   extends Omit<DialogHTMLAttributes<HTMLDialogElement>, 'onClose'> {
+  /**
+   * The unique id of the notification. Required for the onClose callback.
+   */
   id: string
+  /**
+   * Called when the close button is clicked.
+   */
   onClose?: (e: MouseEvent<HTMLButtonElement>) => void
 }
 export type NotificationProps = NotificationBaseProps & NotificationVariantProps
 
 /**
- * The info notification component.
- * @param props - The component props.
- * @returns The info notification component.
+ * A static Notification component that displays a message to the user. This
+ * is typically only used when not utilizing the NotificationCenter.
+ * @see https://cerberus.digitalu.design/react/notification
+ * @memberof module:NotificationCenter
  * @example
  * ```tsx
  * <Notification id="info:1" open>
  *  <NotificationHeading>Info Notification</NotificationHeading>
- * <NotificationDescription>
- *  This is a description with a <a href="#">link</a> in the message.
- * </NotificationDescription>
+ *  <NotificationDescription>
+ *   This is a description with a <a href="#">link</a> in the message.
+ *  </NotificationDescription>
  * </Notification>
  * ```
  */

package/src/components/NotificationDescription.tsx

@@ -1,8 +1,3 @@
-/**
- * This module exports the NotificationDescription component.
- * @module
- */
-
 import { cx } from '@cerberus/styled-system/css'
 import {
   notification,
@@ -10,13 +5,20 @@ import {
 } from '@cerberus/styled-system/recipes'
 import type { HTMLAttributes } from 'react'
 
+/**
+ * This module exports the NotificationDescription component.
+ * @module
+ */
+
 export interface BaseNotificationDescriptionProps
   extends HTMLAttributes<HTMLParagraphElement> {}
 export type NotificationDescriptionProps = BaseNotificationDescriptionProps &
   NotificationVariantProps
 
 /**
- * The NotificationDescription component is used to render the description of a notification.
+ * Used to render the description of a notification.
+ * @see https://cerberus.digitalu.design/react/notification
+ * @memberof module:NotificationCenter
  * @param props - The anything a HTMLParagraphElement can accept.
  */
 export function NotificationDescription(props: NotificationDescriptionProps) {

package/src/components/NotificationHeading.tsx

@@ -1,8 +1,3 @@
-/**
- * This module exports the NotificationHeading component.
- * @module
- */
-
 import { cx } from '@cerberus/styled-system/css'
 import {
   notification,
@@ -10,13 +5,20 @@ import {
 } from '@cerberus/styled-system/recipes'
 import type { HTMLAttributes } from 'react'
 
+/**
+ * This module exports the NotificationHeading component.
+ * @module
+ */
+
 export interface BaseNotificationHeadingProps
   extends HTMLAttributes<HTMLParagraphElement> {}
 export type NotificationHeadingProps = BaseNotificationHeadingProps &
   NotificationVariantProps
 
 /**
- * The NotificationHeading component is used to render the heading of a notification.
+ * Used to render the heading of a notification.
+ * @see https://cerberus.digitalu.design/react/notification
+ * @memberof module:NotificationCenter
  * @param props - The anything a HTMLParagraphElement can accept.
  */
 export function NotificationHeading(props: NotificationHeadingProps) {

package/src/components/Portal.tsx

@@ -7,14 +7,21 @@ import { createPortal } from 'react-dom'
  */
 
 export interface PortalProps {
+  /**
+   * The root container to render the children into.
+   * @default document.body
+   */
   container?: Element | DocumentFragment
+  /**
+   * An optional key to use for the Portal component.
+   */
   key?: null | string
 }
 
 /**
  * The Portal component is used to render children into a DOM node that exists outside the DOM hierarchy of the parent component.
- * @param container - The props for the Portal component.
- * @returns ReactPortal
+ * @see https://cerberus.digitalu.design/react/portal
+ * @definition [React Portal Docs](https://react.dev/reference/react-dom/createPortal)
  */
 export function Portal(props: PropsWithChildren<PortalProps>) {
   const container = props.container || document.body

package/src/components/ProgressBar.tsx

@@ -12,11 +12,23 @@ import type { HTMLAttributes } from 'react'
 
 export interface ProgressBarBaseProps extends HTMLAttributes<HTMLDivElement> {}
 export type NonIndeterminateProgressBarProps = {
+  /**
+   * The state of the progress bar.
+   */
   indeterminate?: never
+  /**
+   * The current value of the progress bar.
+   */
   now: number
 }
 export type IndeterminateProgressBarProps = {
-  indeterminate: true
+  /**
+   * The state of the progress bar.
+   */
+  indeterminate?: true
+  /**
+   * The current value of the progress bar.
+   */
   now?: never
 }
 export type ProgressBarProps = ProgressBarBaseProps &
@@ -25,9 +37,7 @@ export type ProgressBarProps = ProgressBarBaseProps &
 
 /**
  * The ProgressBar component is used to display the progress of a task.
- * @param props - HTML div element attributes
- * @param props.now - The current value of the progress bar
- * @param props.indeterminate - Whether the progress bar is indeterminate
+ * @see https://cerberus.digitalu.design/react/progress-indicators
  * @example
  * ```tsx
  * <ProgressBar value={75} />
@@ -48,7 +58,7 @@ export function ProgressBar(props: ProgressBarProps) {
       aria-valuemax={100}
       aria-valuenow={indeterminate ? 0 : nowClamped}
       className={cx(nativeProps.className, styles.root)}
-      role="meter"
+      role="progressbar"
     >
       <div
         {...(indeterminate && { 'data-indeterminate': true })}

package/src/components/Radio.tsx

@@ -7,13 +7,42 @@ import type { RecipeVariantProps } from '@cerberus/styled-system/types'
 import type { InputHTMLAttributes, PropsWithChildren } from 'react'
 import { useFieldContext } from '../context/field'
 
+/**
+ * This module contains the Radio component.
+ * @module
+ */
+
 export type RadioRecipe = RecipeVariantProps<typeof radio>
 export interface RadioBaseProps
   extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+  /**
+   * A unique identifier for the radio button. Required for accessibility.
+   */
   id: string
 }
 export type RadioProps = RadioBaseProps & RadioRecipe
 
+/**
+ * The Radio component is used to allow users to select a single option from a list of options.
+ * @see https://cerberus.digitalu.design/react/radio
+ * @memberof module:Field
+ * @example
+ * ```tsx
+ * <Field>
+ *  <fieldset name="fruit">
+ *    <Radio id="radio-1" name="fruit" value="1">
+ *     Option 1
+ *    </Radio>
+ *    <Radio id="radio-2" name="fruit" value="2">
+ *     Option 2
+ *    </Radio>
+ *    <Radio id="radio-3" name="fruit" value="3">
+ *     Option 3
+ *    </Radio>
+ *   </fieldset>
+ * </Field>
+ * ```
+ */
 export function Radio(props: PropsWithChildren<RadioProps>) {
   const { children, size, ...nativeProps } = props
   const { invalid, ...state } = useFieldContext()