@cerberus-design/react 0.9.2 → 0.10.0

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

@@ -0,0 +1,82 @@
+import type { SVGProps } from 'react'
+
+/**
+ * This module contains the Spinner component.
+ * @module
+ */
+
+export type SpinnerProps = SVGProps<SVGSVGElement> & {
+  /**
+   * The size of the spinner
+   */
+  size?: number | string
+}
+
+/**
+ * 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
+ * <Button>
+ *   <Show when={loading} fallback={<>Save</>}>
+ *      Saving
+ *      <Spinner size={24} />
+ *   </Show>
+ * </Button>
+ * ```
+ */
+export function Spinner(props: SpinnerProps) {
+  return (
+    <svg
+      aria-busy="true"
+      role="status"
+      xmlns="http://www.w3.org/2000/svg"
+      height={props.size}
+      width={props.size}
+      viewBox="0 0 24 24"
+      {...props}
+    >
+      <g
+        fill="none"
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={2}
+      >
+        <path
+          strokeDasharray={16}
+          strokeDashoffset={16}
+          d="M12 3c4.97 0 9 4.03 9 9"
+        >
+          <animate
+            fill="freeze"
+            attributeName="stroke-dashoffset"
+            dur="0.15s"
+            values="16;0"
+          ></animate>
+          <animateTransform
+            attributeName="transform"
+            dur="0.75s"
+            repeatCount="indefinite"
+            type="rotate"
+            values="0 12 12;360 12 12"
+          ></animateTransform>
+        </path>
+        <path
+          strokeDasharray={64}
+          strokeDashoffset={64}
+          strokeOpacity={0.3}
+          d="M12 3c4.97 0 9 4.03 9 9c0 4.97 -4.03 9 -9 9c-4.97 0 -9 -4.03 -9 -9c0 -4.97 4.03 -9 9 -9Z"
+        >
+          <animate
+            fill="freeze"
+            attributeName="stroke-dashoffset"
+            dur="0.6s"
+            values="64;0"
+          ></animate>
+        </path>
+      </g>
+    </svg>
+  )
+}

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">

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,27 +1,53 @@
 import type { HTMLAttributes, PropsWithChildren } from 'react'
-import { Close } from '@cerberus/icons'
 import { Show } from './Show'
 import { css, cx } from '@cerberus/styled-system/css'
-import { iconButton, tag } from '@cerberus/styled-system/recipes'
-import type { RecipeVariantProps } from '@cerberus/styled-system/types'
+import {
+  iconButton,
+  tag,
+  type TagVariantProps,
+} from '@cerberus/styled-system/recipes'
+import { $cerberusIcons } from '../config/defineIcons'
 
 /**
  * This module contains the tag component.
  * @module
  */
 
-export type TagRecipeProps = RecipeVariantProps<typeof tag>
-
 export type StaticTagProps = HTMLAttributes<HTMLSpanElement> &
-  TagRecipeProps & {
+  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'
 }
 
@@ -29,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>
@@ -41,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.
@@ -134,7 +151,7 @@ export function ConfirmModal(
                 fallback={
                   <Avatar
                     ariaLabel=""
-                    gradient="light-purple"
+                    gradient="charon-light"
                     icon={<ConfirmIcon size={24} />}
                     src=""
                   />
@@ -142,7 +159,7 @@ export function ConfirmModal(
               >
                 <Avatar
                   ariaLabel=""
-                  gradient="red"
+                  gradient="hades-dark"
                   icon={<ConfirmIcon size={24} />}
                   src=""
                 />

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