@cerberus-design/react 0.9.2-next-5604236 → 0.9.2-next-74f2c67

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} />

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()

package/src/components/Select.tsx

@@ -21,21 +21,30 @@ export type SelectProps = Omit<
   'size'
 > &
   SelectVariantProps & {
+    /**
+     * The unique id of the select element. Required for accessibility.
+     */
     id: string
+    /**
+     * The id of the FieldMessage that describes the select element.
+     */
     describedBy?: string
   }
 
 /**
- * Select component
- * props: SelectHTMLAttributes<HTMLSelectElement> & SelectVariantProps & { describedBy?: string }
+ * Used to allow users to select a single option from a list of options.
+ * @see https://cerberus.digitalu.design/react/select
+ * @memberof module:Field
  * @example
  * ```tsx
- * <Select describedby="help:fruit" id="fruit">
- *  <Option value="">Choose option</Option>
- *  <Option value="one">Option 1</Option>
- *  <Option value="two">Option 2</Option>
- *  <Option value="three">Option 3</Option>
- * </Select>
+ * <Field>
+ *   <Select describedby="help:fruit" id="fruit">
+ *    <Option value="">Choose option</Option>
+ *    <Option value="one">Option 1</Option>
+ *    <Option value="two">Option 2</Option>
+ *    <Option value="three">Option 3</Option>
+ *   </Select>
+ * </Field>
  * ```
  */
 export function Select(props: SelectProps) {

package/src/components/Show.tsx

@@ -2,19 +2,30 @@
 
 import { useMemo, type PropsWithChildren, type ReactNode } from 'react'
 
+/**
+ * This module contains the Show component.
+ * @module
+ */
+
 export interface ShowProps {
+  /**
+   * The condition to render memoized children or the fallback content.
+   */
   when: boolean | null | undefined
+  /**
+   * The children to render when the condition is false.
+   */
   fallback?: ReactNode
 }
 
 /**
- * Conditionally render its children or an optional fallback component
- * based on the SolidJS component.
- * @definition [Show docs](https://cerberus.digitalu.design/react/show)
+ * Conditionally render a memoized version of the children or optional fallback
+ * content.
+ * @see https://cerberus.digitalu.design/react/show
  * @example
  * ```tsx
- * <Show when={condition}>
- *  <div>Content</div>
+ * <Show when={isLoggedIn} fallback={<Navigate to="/login" />}>
+ *   <Dashboard />
  * </Show>
  */
 export function Show(props: PropsWithChildren<ShowProps>): ReactNode {

package/src/components/Spinner.tsx

@@ -6,17 +6,24 @@ import type { SVGProps } from 'react'
  */
 
 export type SpinnerProps = SVGProps<SVGSVGElement> & {
+  /**
+   * The size of the spinner
+   */
   size?: number | string
 }
 
 /**
- * The Spinner component is used to display a loading indicator.
- * @param props - SVG element attributes
- * @param props.size - The size of the spinner
- * @description [Spinner Docs](https://cerberus.digitalu.design/react/loading-states/)
+ * The Spinner component is used to display a loading indicator. Typically used
+ * in buttons, modals, and other components that require a loading state.
+ * @see https://cerberus.digitalu.design/react/loading-states/
  * @example
  * ```tsx
- * <Spinner size={24} />
+ * <Button>
+ *   <Show when={loading} fallback={<>Save</>}>
+ *      Saving
+ *      <Spinner size={24} />
+ *   </Show>
+ * </Button>
  * ```
  */
 export function Spinner(props: SpinnerProps) {

package/src/components/Tab.tsx

@@ -14,20 +14,28 @@ import { useTabsKeyboardNavigation } from '../aria-helpers/tabs.aria'
  * This module provides a Tab component.
  * @module
  */
+
 export interface TabProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /**
+   * The id of the tab that will be tracked as the active tab and used for aria
+   * attributes.
+   */
   value: string
 }
 
 /**
  * The Tab component provides a tab element to be used in a TabList.
  * @definition [ARIA Target Size](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html#:~:text=Understanding%20SC%202.5.,%3ATarget%20Size%20(Level%20AAA)&text=The%20size%20of%20the%20target,Equivalent)
- * @definition [Tab docs](https://cerberus.digitalu.design/react/tabs)
- * @param value - the id of the tab that will be tracked as the active tab and used for aria attributes
+ * @see https://cerberus.digitalu.design/react/tabs
+ * @memberof module:Tabs
  * @example
  * ```tsx
- * <Tab value="overview">
- *  Overview
- * </Tab>
+ * <Tabs>
+ *  <TabList description="Profile settings">
+ *   <Tab value="overview">Overview</Tab>
+ *  </TabList>
+ *  <TabPanel tab="overview">...</TabPanel>
+ * </Tabs>
  * ```
  */
 export function Tab(props: TabProps) {

package/src/components/TabList.tsx

@@ -11,12 +11,16 @@ import { useTabsContext } from '../context/tabs'
  */
 
 export interface TabListProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * A description of what the tab list contains. Required for accessibility.
+   */
   description: string
 }
 
 /**
  * The TabList component provides a container for tab elements.
- * @param description - a description of what the tab list contains
+ * @see https://cerberus.digitalu.design/react/tabs
+ * @memberof module:Tabs
  * @example
  * ```tsx
  * <TabList description="Button details">

package/src/components/TabPanel.tsx

@@ -11,12 +11,17 @@ import { Show } from './Show'
  */
 
 export interface TabPanelProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * The unique value of the Tab that is associated with the TabPanel.
+   */
   tab: string
 }
 
 /**
- * The TabPanel component provides a panel element to be used in a Tabs provider.
- * @param tab - the value of the tab that will be tracked as the active tab and used for aria attributes
+ * The TabPanel component provides a panel element to be used in a Tabs
+ * provider.
+ * @see https://cerberus.digitalu.design/react/tabs
+ * @memberof module:Tabs
  * @example
  * ```tsx
  * <TabPanel tab="overview">