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

package/src/components/Table.tsx

@@ -8,13 +8,16 @@ import type { PropsWithChildren, TableHTMLAttributes } from 'react'
  */
 
 export interface TableProps extends TableHTMLAttributes<HTMLTableElement> {
+  /**
+   * An easy to understand description of the table. Required for accessibility.
+   */
   caption: string
 }
 
 /**
- * The Table component is used to render a table.
- * @definition [Table docs](https://cerberus.digitalu.design/react/table)
- * @prop caption - An easy to understand description of the table.
+ * An accessible table component.
+ * @definition [ARIA Table pattern](https://www.w3.org/WAI/ARIA/apg/patterns/table/)
+ * @see https://cerberus.digitalu.design/react/table.
  * @example
  * ```tsx
  * <Table caption="Basic Table">

package/src/components/Tag.tsx

@@ -1,5 +1,4 @@
 import type { HTMLAttributes, PropsWithChildren } from 'react'
-import { Close } from '@cerberus/icons'
 import { Show } from './Show'
 import { css, cx } from '@cerberus/styled-system/css'
 import {
@@ -7,6 +6,7 @@ import {
   tag,
   type TagVariantProps,
 } from '@cerberus/styled-system/recipes'
+import { $cerberusIcons } from '../config/defineIcons'
 
 /**
  * This module contains the tag component.
@@ -15,14 +15,39 @@ import {
 
 export type StaticTagProps = HTMLAttributes<HTMLSpanElement> &
   TagVariantProps & {
+    /**
+     * The action to be performed when the tag is clicked. Not available when
+     * the palette or gradient props are provided.
+     */
     onClick?: never
   }
 
 export type ClickableTagProps = HTMLAttributes<HTMLSpanElement> & {
+  /**
+   * The gradient to apply to the tag. Not available when the onClick prop is
+   * provided.
+   */
   gradient?: never
+  /**
+   * The palette to use for the tag. Not available when the onClick prop is
+   * provided.
+   */
   palette?: never
+  /**
+   * The action to be performed when the tag is clicked.
+   */
   onClick: () => void
+  /**
+   * The shape of the tag. Not available when the onClick prop is provided.
+   * @type 'pill' | 'rounded'
+   * @default 'pill'
+   */
   shape: 'pill'
+  /**
+   * The usage of the tag. Not available when the onClick prop is provided.
+   * @type 'filled' | 'outlined'
+   * @default 'filled'
+   */
   usage: 'filled'
 }
 
@@ -30,7 +55,7 @@ export type TagProps = StaticTagProps | ClickableTagProps
 
 /**
  * The Tag component is used to display a meta descriptions.
- * @definition [Tag docs](https://cerberus.digitalu.design/react/tags)
+ * @see https://cerberus.digitalu.design/react/tag
  * @example
  * ```tsx
  * <Tag>Tag</Tag>
@@ -42,6 +67,7 @@ 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
 
   return (
     <span

package/src/components/Tbody.tsx

@@ -2,12 +2,18 @@ import { tbody, type TbodyVariantProps } from '@cerberus/styled-system/recipes'
 import { cx } from '@cerberus/styled-system/css'
 import type { TableHTMLAttributes } from 'react'
 
+/**
+ * This module provides a TBody component.
+ * @module
+ */
+
 export type TbodyBaseProps = TableHTMLAttributes<HTMLTableSectionElement>
 export type TbodyProps = TbodyBaseProps & TbodyVariantProps
 
 /**
  * The TBody component is used to render a table body.
- * @definition [Table docs](https://cerberus.digitalu.design/react/table)
+ * @see https://cerberus.digitalu.design/react/table
+ * @memberof module:Table
  * @example
  * ```tsx
  * <TBody>

package/src/components/Td.tsx

@@ -12,7 +12,8 @@ export type TdProps = TdBaseProps & TdVariantProps
 
 /**
  * Styles for the Th component
- * @definition [Table docs](https://cerberus.digitalu.design/react/table)
+ * @see https://cerberus.digitalu.design/react/table
+ * @memberof module:Table
  * @example
  * ```tsx
  * <Td>Data cell</Td>

package/src/components/Textarea.tsx

@@ -2,9 +2,8 @@
 
 import type { TextareaHTMLAttributes } from 'react'
 import { css, cx } from '@cerberus/styled-system/css'
-import { input } from '@cerberus/styled-system/recipes'
+import { input, type InputVariantProps } from '@cerberus/styled-system/recipes'
 import { useFieldContext } from '../context/field'
-import type { InputRecipeProps } from './Input'
 
 /**
  * This module contains the Textarea component.
@@ -13,14 +12,20 @@ import type { InputRecipeProps } from './Input'
 
 export interface TextareaBaseProps
   extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'id'> {
+  /**
+   * The ID of the FieldMessage that describes the textarea.
+   */
   describedBy?: string
+  /**
+   * The unique id of the textarea.
+   */
   id: string
 }
-export type TextareaProps = InputRecipeProps & TextareaBaseProps
+export type TextareaProps = InputVariantProps & TextareaBaseProps
 
 /**
  * A component that allows the user to input large blocks of text.
- * @description https://github.com/omnifed/cerberus/blob/main/packages/react/src/components/Textarea.tsx
+ * @see https://cerberus.digitalu.design/react/textarea
  */
 export function Textarea(props: TextareaProps): JSX.Element {
   const { describedBy, ...nativeProps } = props

package/src/components/Th.tsx

@@ -9,17 +9,29 @@ import { Show } from './Show'
  */
 
 export type ThBaseProps = TableHTMLAttributes<HTMLTableCellElement> & {
+  /**
+   * Converts the Th into a actionable button. Called when the user clicks on
+   * the Th.
+   */
   onClick?: (e: MouseEvent<HTMLButtonElement>) => void
 }
 export type ThProps = ThBaseProps & ThVariantProps
 
 /**
  * Styles for the Th component
- * @definition [Table docs](https://cerberus.digitalu.design/react/table)
+ * @see https://cerberus.digitalu.design/react/table
+ * @memberof module:Table
  * @example
  * ```tsx
  * <Th>Header 1</Th>
  * ```
+ * @example
+ * ```tsx
+ * <Th onClick={handleClick}>
+ *   Names
+ *   <SortIcon />
+ * </Th>
+ * ```
  */
 export function Th(props: ThProps) {
   const { size, onClick, ...nativeProps } = props

package/src/components/Thead.tsx

@@ -11,7 +11,8 @@ export type TheadProps = TableHTMLAttributes<HTMLTableSectionElement>
 
 /**
  * The Thead component is used to render a table header.
- * @definition [Table docs](https://cerberus.digitalu.design/react/table)
+ * @see https://cerberus.digitalu.design/react/table
+ * @memberof module:Table
  * @example
  * ```tsx
  * <Thead>

package/src/components/Toggle.tsx

@@ -10,16 +10,51 @@ import type { InputHTMLAttributes } from 'react'
 import { $cerberusIcons } from '../config/defineIcons'
 import { useFieldContext } from '../context/field'
 
+/**
+ * This module provides a toggle component.
+ * @module
+ */
+
 export type ToggleBase = Omit<
   InputHTMLAttributes<HTMLInputElement>,
   'size' | 'id' | 'value'
 > & {
+  /**
+   * The FieldMessage providing context for the Toggle.
+   */
   describedBy?: string
+  /**
+   * A unique identifier for the Toggle. Required for accessibility.
+   */
   id: string
+  /**
+   * The value of the Toggle.
+   */
   value: string
 }
 export type ToggleProps = ToggleBase & ToggleVariantProps
 
+/**
+ * The Toggle component is used to switch between two states. Optionally
+ * combine with the `useToggle` hook.
+ * @see https://cerberus.digitalu.design/react/toggle
+ * @example
+ * ```tsx
+ * const { checked, handleChange } = useToggle({ checked: 'toggle' })
+ *
+ * <Hstack justify="space-between" w="full">
+ *  <Field>
+ *    <Label htmlFor="toggle">Show notifications</Label>
+ *    <Toggle
+ *     checked={checked === 'toggle'}
+ *     id="toggle"
+ *     onChange={handleChange}
+ *     value="toggle"
+ *    />
+ *  </Field>
+ * </Hstack>
+ * ```
+ */
 export function Toggle(props: ToggleProps) {
   const { size, describedBy, ...nativeProps } = props
   const styles = toggle({ size })

package/src/context/confirm-modal.tsx

@@ -30,10 +30,26 @@ import { Avatar } from '../components/Avatar'
  */
 
 export interface ShowConfirmModalOptions {
+  /**
+   * The kind of confirm modal to show.
+   * @default 'non-destructive'
+   */
   kind?: 'destructive' | 'non-destructive'
+  /**
+   * The heading of the confirm modal.
+   */
   heading: string
+  /**
+   * The description of the confirm modal.
+   */
   description?: string
+  /**
+   * The text for the action button.
+   */
   actionText: string
+  /**
+   * The text for the cancel button.
+   */
   cancelText: string
 }
 export type ShowResult =
@@ -50,6 +66,7 @@ export interface ConfirmModalProviderProps {}
 
 /**
  * Provides a confirm modal to the app.
+ * @see https://cerberus.digitalu.design/react/confirm-modal
  * @example
  * ```tsx
  * // Wrap the Provider around the root of the feature.

package/src/context/feature-flags.tsx

@@ -19,7 +19,7 @@ export interface FeatureFlagProviderProps {
 
 /**
  * Provides feature flags to the application.
- * @param flags - The flags data for the provider.
+ * @see https://cerberus.digitalu.design/react/feature-flags
  * @example
  * ```tsx
  * // This should be a JSON file or a server response.
@@ -49,6 +49,9 @@ export function FeatureFlags(
   )
 }
 
+/**
+ * Used to retrieve the context of the FeatureFlags provider.
+ */
 export function useFeatureFlags(key: string): boolean {
   const context = useContext(FeatureFlagContext)
   if (context === null) {

package/src/context/field.tsx

@@ -7,15 +7,37 @@ import {
   type PropsWithChildren,
 } from 'react'
 
+/**
+ * This module provides a context and hook for the field.
+ * @module Field
+ */
+
 export interface FieldContextValue {
+  /**
+   * Whether the field is disabled.
+   * @description [Moz Input Attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes)
+   */
   disabled?: boolean
+  /**
+   * Whether the field is read-only.
+   */
   readOnly?: boolean
+  /**
+   * Whether the field is required.
+   */
   required?: boolean
+  /**
+   * Whether the field is invalid.
+   */
   invalid?: boolean
 }
 
 const FieldContext = createContext<FieldContextValue | null>(null)
 
+/**
+ * Provides the field state for a all related components used within a group.
+ * @see https://cerberus.digitalu.design/react/input
+ */
 export function Field(
   props: PropsWithChildren<FieldContextValue>,
 ): JSX.Element {
@@ -36,6 +58,10 @@ export function Field(
   )
 }
 
+/**
+ * Used to access the field context.
+ * @returns The field context.
+ */
 export function useFieldContext(): FieldContextValue {
   const context = useContext(FieldContext)
   if (!context) {

package/src/context/navMenu.tsx

@@ -12,18 +12,39 @@ import {
   type RefObject,
 } from 'react'
 
+/**
+ * This module provides a context and hook for the nav menu.
+ * @module NavMenu
+ */
+
 export type NavTriggerRef = RefObject<HTMLButtonElement>
 export type NavMenuRef = RefObject<HTMLUListElement>
 
 export interface NavMenuContextValue {
+  /**
+   * The ref for the trigger button.
+   */
   triggerRef: NavTriggerRef | null
+  /**
+   * The ref for the menu.
+   */
   menuRef: NavMenuRef | null
+  /**
+   * Whether the menu is expanded.
+   */
   expanded: boolean
+  /**
+   * Called when the menu button is clicked.
+   */
   onToggle: () => void
 }
 
 const NavMenuContext = createContext<NavMenuContextValue | null>(null)
 
+/**
+ * Provides the nav menu state for all the NavMenu family components.
+ * @see https://cerberus.digitalu.design/react/nav-menu
+ */
 export function NavMenu(props: PropsWithChildren): JSX.Element {
   const triggerRef = useRef<HTMLButtonElement>(null)
   const menuRef = useRef<HTMLUListElement>(null)
@@ -56,6 +77,10 @@ export function NavMenu(props: PropsWithChildren): JSX.Element {
   )
 }
 
+/**
+ * Used to access the nav menu context.
+ * @returns The nav menu context.
+ */
 export function useNavMenuContext(): NavMenuContextValue {
   const context = useContext(NavMenuContext)
   if (!context) {

package/src/context/notification-center.tsx

@@ -26,10 +26,26 @@ import { cx } from '@cerberus/styled-system/css'
  */
 
 export interface NotifyOptions {
+  /**
+   * The palette of the notification.
+   * @default 'info'
+   */
   palette: 'info' | 'success' | 'warning' | 'danger'
+  /**
+   * The heading of the notification.
+   */
   heading: string
+  /**
+   * The unique id of the notification.
+   */
   id?: string
+  /**
+   * The description of the notification.
+   */
   description?: ReactNode
+  /**
+   * The action to take when the notification is closed
+   */
   onClose?: () => void
 }
 
@@ -43,6 +59,7 @@ export interface NotificationsProviderProps extends PortalProps {}
 
 /**
  * Provides a notification center to the app.
+ * @see https://cerberus.digitalu.design/react/notification
  * @example
  * ```tsx
  * // Wrap the Provider around the root of the feature.

package/src/context/prompt-modal.tsx

@@ -30,15 +30,34 @@ import { Avatar } from '../components/Avatar'
 
 /**
  * This module provides a context and hook for the prompt modal.
- * @module
+ * @module PromptModal
  */
 
 export interface ShowPromptModalOptions {
+  /**
+   * The kind of prompt modal to show.
+   * @default 'non-destructive'
+   */
   kind?: 'destructive' | 'non-destructive'
+  /**
+   * The heading of the prompt modal.
+   */
   heading: string
+  /**
+   * The description of the prompt modal.
+   */
   description?: string
+  /**
+   * The key to confirm the action.
+   */
   key: string
+  /**
+   * The text for the action button.
+   */
   actionText: string
+  /**
+   * The text for the cancel button.
+   */
   cancelText: string
 }
 export type PromptShowResult =
@@ -46,6 +65,21 @@ export type PromptShowResult =
   | null
 
 export interface PromptModalValue {
+  /**
+   * The method to trigger the prompt modal.
+   * @returns the value of the key if the action is confirmed.
+   * @example
+   * ```tsx
+   * const accepted = await prompt.show({
+   *  kind: 'destructive',
+   *  heading: 'Delete channel?',
+   *  description:
+   *   'This will permanently delete a channel on your account. There is no going back.',
+   *  key: CHANNEL_NAME,
+   *  actionText: 'Yes, delete channel',
+   *  cancelText: 'No, cancel',
+   * })
+   */
   show: (options: ShowPromptModalOptions) => Promise<string>
 }
 
@@ -55,6 +89,7 @@ export interface PromptModalProviderProps {}
 
 /**
  * Provides a prompt modal to the app.
+ * @see https://cerberus.digitalu.design/react/prompt-modal
  * @example
  * ```tsx
  * // Wrap the Provider around the root of the feature.
@@ -236,6 +271,9 @@ export function PromptModal(
   )
 }
 
+/**
+ * Used to retrieve the context of the PromptModal provider.
+ */
 export function usePromptModal(): PromptModalValue {
   const context = useContext(PromptModalContext)
   if (context === null) {

package/src/context/tabs.tsx

@@ -15,30 +15,53 @@ import {
 
 /**
  * This module provides a Tabs component and a hook to access its context.
- * @module
+ * @module Tabs
  */
 
 export interface TabsContextValue {
+  /**
+   * The ref for the tabs.
+   */
   tabs: MutableRefObject<HTMLButtonElement[]>
+  /**
+   * The id of the tabs component.
+   */
   id: string
+  /**
+   * The active tab id.
+   */
   active: string
+  /**
+   * The styles for the tabs.
+   */
   styles: Pretty<Record<'tabList' | 'tab' | 'tabPanel', string>>
+  /**
+   * Called when the active tab is updated.
+   */
   onTabUpdate: (active: string) => void
 }
 
 export const TabsContext = createContext<TabsContextValue | null>(null)
 
 export interface TabsProps {
+  /**
+   * A unique identifier for the Tabs component. Typically used when there are
+   * multiple Tabs components on the same page.
+   */
   id?: string
+  /**
+   * The default active tab id.
+   */
   active?: string
+  /**
+   * Whether to cache the active tab state in local storage.
+   */
   cache?: boolean
 }
 
 /**
  * The Tabs component provides a context to manage tab state.
- * @param id - the id of the tabs component,
- * @param active - the default active tab id,
- * @param cache - whether to cache the active tab state in local storage
+ * @see https://cerberus.digitalu.design/react/tabs
  * @example
  * ```tsx
  * <Tabs cache>
@@ -96,6 +119,10 @@ export function Tabs(
   )
 }
 
+/**
+ * Used to access the tabs context.
+ * @returns The tabs context.
+ */
 export function useTabsContext(): TabsContextValue {
   const context = useContext(TabsContext)
   if (!context) {

package/src/context/theme.tsx

@@ -3,14 +3,31 @@
 import { createContext, useContext, type PropsWithChildren } from 'react'
 import { useTheme, type UseThemeOptions } from '../hooks/useTheme'
 
+/**
+ * This module provides a context and hook for the theme.
+ * @module Theme
+ */
+
 export type DefaultThemes = 'cerberus' | 'acheron'
 export type CustomThemes<K extends string = DefaultThemes> = 'cerberus' | K
 export type ColorModes = 'light' | 'dark' | 'system'
 
 export interface ThemeContextValue<T extends string = DefaultThemes> {
+  /**
+   * The current theme.
+   */
   theme: CustomThemes<T>
+  /**
+   * The current color mode.
+   */
   mode: ColorModes
+  /**
+   * Called when the theme is updated.
+   */
   updateTheme: (theme: T) => void
+  /**
+   * Called when the color mode is updated.
+   */
   updateMode: (mode: ColorModes) => void
 }
 
@@ -19,12 +36,20 @@ const ThemeContext = createContext<ThemeContextValue<DefaultThemes> | null>(
 )
 
 export interface ThemeProviderProps extends UseThemeOptions {
+  /**
+   * The default theme.
+   */
   defaultTheme?: DefaultThemes
+  /**
+   * The default color mode.
+   */
   defaultColorMode?: ColorModes
 }
 
 /**
- * A context provider that allows the user to set the theme and mode of the application.
+ * A context provider that allows the user to set the theme and mode of the
+ * application.
+ * @see https://cerberus.digitalu.design/react/use-theme-context
  * @example
  * ```tsx
  * <ThemeProvider>
@@ -48,6 +73,9 @@ export function ThemeProvider(
   )
 }
 
+/**
+ * Used to access the theme context.
+ */
 export function useThemeContext(): ThemeContextValue<DefaultThemes> {
   const context = useContext(ThemeContext)
   if (!context) {

package/src/hooks/useModal.ts

@@ -8,11 +8,25 @@ import { useCallback, useMemo, useRef, type RefObject } from 'react'
  */
 
 interface UseModalReturnValue {
+  /**
+   * The ref for the modal.
+   */
   modalRef: RefObject<HTMLDialogElement>
+  /**
+   * Shows the modal.
+   */
   show: () => void
+  /**
+   * Closes the modal.
+   */
   close: () => void
 }
 
+/**
+ * Provides a hook for using a custom modal.
+ * @memberof module:Modal
+ * @returns The modal hook.
+ */
 export function useModal(): UseModalReturnValue {
   const modalRef = useRef<HTMLDialogElement | null>(null)