@cerberus-design/react 0.15.0 → 0.16.0-next-feeb186

package/src/components/field/primitives.tsx

@@ -0,0 +1,204 @@
+import {
+  Field,
+  type FieldHelperTextProps,
+  type FieldInputProps as ArkFieldInputProps,
+  type FieldLabelProps,
+  type FieldRootProps as ArkFieldRootProps,
+  type FieldTextareaProps,
+} from '@ark-ui/react/field'
+import type { ReactNode } from 'react'
+import { cx } from '@cerberus/styled-system/css'
+import { field, type FieldVariantProps } from '@cerberus/styled-system/recipes'
+import { FieldStatusIndicator } from './status-indicator'
+import { FieldStartIndicator } from './start-indicator'
+
+/**
+ * This module contains all the primitives of the Field component.
+ * @module 'field'
+ */
+
+export type FieldRootProps = ArkFieldRootProps & FieldVariantProps
+
+/**
+ * The context & container for the Field components.
+ * @description [Field Docs](https://cerberus.digitalu.design/react/field)
+ * @example
+ * ```tsx
+ * <FieldRoot required ids={{ input: 'exampleId' }}>
+ *  <FieldLabel>Label</FieldLabel>
+ *  <FieldInput />
+ * </FieldRoot>
+ * ```
+ */
+export function FieldRoot(props: FieldRootProps) {
+  const { size, ...fieldProps } = props
+  const styles = field({ size })
+  return (
+    <Field.Root
+      {...fieldProps}
+      className={cx(styles.root, fieldProps.className)}
+    />
+  )
+}
+
+/**
+ * The label for the Field component.
+ * @description [Field Docs](https://cerberus.digitalu.design/react/field)
+ * @example
+ * ```tsx
+ * <FieldRoot>
+ *   <FieldLabel>Label</FieldLabel>
+ * </FieldRoot>
+ * ```
+ */
+export function FieldLabel(props: FieldLabelProps) {
+  const { children, ...nativeProps } = props
+  const styles = field()
+  return (
+    <Field.Label {...nativeProps} className={cx(styles.label, props.className)}>
+      {children}
+      <Field.RequiredIndicator>(required)</Field.RequiredIndicator>
+    </Field.Label>
+  )
+}
+
+/**
+ * The required indicator for the Field component.
+ */
+export function FieldRequiredIndicator() {
+  return <Field.RequiredIndicator>(required)</Field.RequiredIndicator>
+}
+
+export interface FieldInputProps
+  extends Omit<ArkFieldInputProps, 'size'>,
+    FieldVariantProps {
+  /**
+   * 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
+}
+
+/**
+ * The input for the Field component.
+ * @description [Field Docs](https://cerberus.digitalu.design/react/field)
+ * @example
+ * ```tsx
+ * <FieldRoot>
+ *   <FieldInput />
+ * </FieldRoot>
+ * ```
+ */
+export function FieldInput(props: FieldInputProps) {
+  const { size, startIcon, endIcon, ...fieldProps } = props
+  const styles = field({ size })
+  const hasStartIcon = Boolean(startIcon)
+
+  return (
+    <div className={styles.inputRoot}>
+      <FieldStartIndicator>{startIcon}</FieldStartIndicator>
+      <Field.Input
+        {...fieldProps}
+        {...(hasStartIcon && { 'data-has': 'start-indicator' })}
+        className={cx(styles.input, fieldProps.className)}
+      />
+      <FieldStatusIndicator fallback={endIcon} />
+    </div>
+  )
+}
+
+/**
+ * The helper text for the Field component that is shown when the field is
+ * valid.
+ * @description [Field Docs](https://cerberus.digitalu.design/react/field)
+ * @example
+ * ```tsx
+ * <FieldRoot>
+ *   <FieldInput />
+ *   <FieldHelperText>Helper text</FieldHelperText>
+ * </FieldRoot>
+ * ```
+ */
+export function FieldHelperText(props: FieldHelperTextProps) {
+  const styles = field()
+
+  if (!props.children) return null
+
+  return (
+    <Field.HelperText
+      {...props}
+      className={cx(styles.helperText, props.className)}
+    />
+  )
+}
+
+/**
+ * The error text for the Field component that is shown when the field is
+ * invalid.
+ * @description [Field Docs](https://cerberus.digitalu.design/react/field)
+ * @example
+ * ```tsx
+ * <FieldRoot>
+ *   <FieldInput />
+ *   <FieldErrorText>Error text</FieldErrorText>
+ * </FieldRoot>
+ * ```
+ */
+export function FieldErrorText(props: FieldHelperTextProps) {
+  const styles = field()
+
+  if (!props.children) return null
+
+  return (
+    <Field.ErrorText
+      {...props}
+      className={cx(styles.errorText, props.className)}
+    />
+  )
+}
+
+/**
+ * The textarea for the Field component.
+ * @description [Field Docs](https://cerberus.digitalu.design/react/field)
+ * @example
+ * ```tsx
+ * <FieldRoot>
+ *   <FieldTextarea />
+ * </FieldRoot>
+ * ```
+ */
+export function FieldTextarea(props: FieldTextareaProps) {
+  const styles = field()
+  return (
+    <Field.Textarea
+      {...props}
+      className={cx(styles.textarea, props.className)}
+    />
+  )
+}
+
+/**
+ * A named export for the FieldInput component.
+ * @description [Field Docs](https://cerberus.digitalu.design/react/field)
+ * @example
+ * ```tsx
+ * import { Input } from '@cerberus/react'
+ *
+ * <Field
+ *   ids={{
+ *    control: 'email',
+ *   }}
+ *   label="Enter your email"
+ *   helperText="We'll never share your email with anyone else."
+ *   errorText="Email is required."
+ *   required
+ * >
+ *   <Input type="email" />
+ * </Field>
+ * ```
+ */
+export const Input = FieldInput
+export const Textarea = FieldTextarea

package/src/components/field/start-indicator.tsx

@@ -0,0 +1,23 @@
+import { cx } from '@cerberus/styled-system/css'
+import { field } from '@cerberus/styled-system/recipes'
+import type { HTMLAttributes } from 'react'
+
+export type FieldIndicatorProps = HTMLAttributes<HTMLSpanElement>
+
+/**
+ * The start indicator displays an indicator at the start of the Input.
+ * @description [Field Docs](https://cerberus.digitalu.design/react/field)
+ */
+export function FieldStartIndicator(props: FieldIndicatorProps) {
+  const styles = field()
+
+  if (!props.children) return null
+
+  return (
+    <span
+      {...props}
+      data-part="start-indicator"
+      className={cx(props.className, styles.startIndicator)}
+    />
+  )
+}

package/src/components/field/status-indicator.tsx

@@ -0,0 +1,58 @@
+'use client'
+
+import { useFieldContext } from '@ark-ui/react'
+import { cx } from '@cerberus/styled-system/css'
+import { field } from '@cerberus/styled-system/recipes'
+import { useCerberusContext } from '../../context/cerberus'
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface FieldStatusIndicatorProps
+  extends HTMLAttributes<HTMLSpanElement> {
+  /**
+   * The fallback content to display when the field is valid.
+   */
+  fallback?: ReactNode
+}
+
+/**
+ * The invalid status indicator for the Field component.
+ * @description [Field Docs](https://cerberus.digitalu.design/react/field)
+ * @example
+ * ```tsx
+ * <FieldRoot>
+ *   <FieldStatusIndicator />
+ * </FieldRoot>
+ * ```
+ */
+export function FieldStatusIndicator(props: FieldStatusIndicatorProps) {
+  const { fallback, ...nativeProps } = props
+  const styles = field()
+  const fieldContext = useFieldContext()
+
+  const { icons } = useCerberusContext()
+  const { invalid: InvalidIcon } = icons
+
+  if (fieldContext.invalid) {
+    return (
+      <span
+        {...nativeProps}
+        aria-hidden="true"
+        data-invalid
+        className={cx(nativeProps.className, styles.statusIndicator)}
+      >
+        <InvalidIcon />
+      </span>
+    )
+  }
+
+  return (
+    <span
+      {...nativeProps}
+      aria-hidden="true"
+      data-part="end-indicator"
+      className={cx(nativeProps.className, styles.endIndicator)}
+    >
+      {fallback}
+    </span>
+  )
+}

package/src/components/fieldset/fieldset.tsx

@@ -0,0 +1,55 @@
+import type { FieldsetRootProps } from '@ark-ui/react'
+import { splitProps } from '../../utils'
+import { FieldsetParts } from './parts'
+import type { FieldsetVariantProps } from '@cerberus/styled-system/recipes'
+
+/**
+ * This module contains the Fieldset component.
+ * @module Fieldset
+ */
+
+export interface FieldsetProps extends FieldsetRootProps, FieldsetVariantProps {
+  /**
+   * The legend/title/label of the fieldset group.
+   */
+  legend?: string
+  /**
+   * The description text for the fieldset group.
+   */
+  helperText?: string
+  /**
+   * The error text for the fieldset group shown when the field is invalid.
+   */
+  errorText?: string
+}
+
+/**
+ * A component used for grouping related fields in a form that is an
+ * abstraction of the Fieldset primitives.
+ * @description [Fieldset Docs](https://cerberus.digitalu.design/react/fieldset)
+ * @description [Primitive Docs](https://ark-ui.com/react/docs/components/fieldset)
+ */
+export function Fieldset(props: FieldsetProps) {
+  const [fieldsetProps, { usage }, rootProps] = splitProps(
+    props,
+    ['legend', 'helperText', 'errorText', 'children'],
+    ['usage'],
+  )
+
+  return (
+    <FieldsetParts.Root {...rootProps}>
+      <FieldsetParts.Legend usage={usage}>
+        {fieldsetProps.legend}
+      </FieldsetParts.Legend>
+      <FieldsetParts.HelperText usage={usage}>
+        {fieldsetProps.helperText}
+      </FieldsetParts.HelperText>
+
+      {fieldsetProps.children}
+
+      <FieldsetParts.ErrorText>
+        {fieldsetProps.errorText}
+      </FieldsetParts.ErrorText>
+    </FieldsetParts.Root>
+  )
+}

package/src/components/fieldset/index.ts

@@ -0,0 +1,3 @@
+export * from './fieldset'
+export * from './parts'
+export * from './primitives'

package/src/components/fieldset/parts.ts

@@ -0,0 +1,47 @@
+import type { ElementType } from 'react'
+import {
+  FieldsetErrorText,
+  FieldsetHelperText,
+  FieldsetLegend,
+  FieldsetRoot,
+} from './primitives'
+
+/**
+ * This module contains the parts of the Field component.
+ * @module 'field/parts'
+ */
+
+interface FieldsetPartsValue {
+  /**
+   * The container of the field.
+   */
+  Root: ElementType
+  /**
+   * The label of the field.
+   */
+  Legend: ElementType
+  /**
+   * The text that displays when the field is valid.
+   */
+  HelperText: ElementType
+  /**
+   * The text that displays when the field is invalid.
+   */
+  ErrorText: ElementType
+}
+
+/**
+ * An Object containing the parts of the Field component. For users that
+ * prefer Object component syntax.
+ *
+ * @remarks
+ *
+ * When using object component syntax, you import the FieldParts object and
+ * the entire family of components vs. only what you use.
+ */
+export const FieldsetParts: FieldsetPartsValue = {
+  Root: FieldsetRoot,
+  Legend: FieldsetLegend,
+  HelperText: FieldsetHelperText,
+  ErrorText: FieldsetErrorText,
+}

package/src/components/fieldset/primitives.tsx

@@ -0,0 +1,79 @@
+import {
+  Fieldset,
+  type FieldsetHelperTextProps,
+  type FieldsetLegendProps,
+  type FieldsetRootProps,
+} from '@ark-ui/react/fieldset'
+import { cx } from '@cerberus/styled-system/css'
+import {
+  fieldset,
+  type FieldsetVariantProps,
+} from '@cerberus/styled-system/recipes'
+
+/**
+ * This module contains all the primitives of the Fieldset component.
+ * @module 'react/fieldset'
+ */
+
+/**
+ * The context & container for the Fieldset components.
+ * @description [Fieldset Docs](https://cerberus.digitalu.design/react/fieldset)
+ * @description [Primitive Docs](https://ark-ui.com/react/docs/components/fieldset)
+ */
+export function FieldsetRoot(props: FieldsetRootProps) {
+  const styles = fieldset()
+  return (
+    <Fieldset.Root {...props} className={cx(styles.root, props.className)} />
+  )
+}
+
+/**
+ * The legend element for the Fieldset group.
+ * @description [Fieldset Docs](https://cerberus.digitalu.design/react/fieldset)
+ * @description [Primitive Docs](https://ark-ui.com/react/docs/components/fieldset)
+ */
+export function FieldsetLegend(
+  props: FieldsetLegendProps & FieldsetVariantProps,
+) {
+  const { usage, ...legendProps } = props
+  const styles = fieldset({ usage })
+  return (
+    <Fieldset.Legend
+      {...legendProps}
+      className={cx(styles.legend, legendProps.className)}
+    />
+  )
+}
+
+/**
+ * The description element for the Fieldset group.
+ * @description [Fieldset Docs](https://cerberus.digitalu.design/react/fieldset)
+ * @description [Primitive Docs](https://ark-ui.com/react/docs/components/fieldset)
+ */
+export function FieldsetHelperText(
+  props: FieldsetHelperTextProps & FieldsetVariantProps,
+) {
+  const { usage, ...helperTextProps } = props
+  const styles = fieldset({ usage })
+  return (
+    <Fieldset.HelperText
+      {...helperTextProps}
+      className={cx(styles.helperText, helperTextProps.className)}
+    />
+  )
+}
+
+/**
+ * The error text element for the Fieldset group.
+ * @description [Fieldset Docs](https://cerberus.digitalu.design/react/fieldset)
+ * @description [Primitive Docs](https://ark-ui.com/react/docs/components/fieldset)
+ */
+export function FieldsetErrorText(props: FieldsetHelperTextProps) {
+  const styles = fieldset()
+  return (
+    <Fieldset.ErrorText
+      {...props}
+      className={cx(styles.errorText, props.className)}
+    />
+  )
+}

package/src/components/for.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode, JSX } from 'react'
+
+export interface ForProps<T extends readonly unknown[], U extends JSX.Element> {
+  /**
+   * The array to iterate over.
+   */
+  each: T | undefined | null | false
+  /**
+   * The fallback to render when the array is empty.
+   */
+  fallback?: JSX.Element
+  /**
+   * The children to render for each item in the array.
+   */
+  children: (item: T[number], index: number) => U
+}
+
+/**
+ * The For component is used to iterate over an array and render a list of
+ * components or display a fallback when the array is empty.
+ * Inspired by the `<For>` component from SolidJS.
+ *
+ * @example
+ * ```tsx
+ * <For each={['a', 'b', 'c']}>
+ *   {(item, index) => <div key={index}>{item}</div>}
+ * </For>
+ * ```
+ */
+export function For<T extends readonly unknown[], U extends JSX.Element>(
+  props: ForProps<T, U>,
+) {
+  if (!props.each || !props.each.length) {
+    return props.fallback || null
+  }
+
+  return props.each?.map(props.children) as ReactNode
+}

package/src/components/radio/index.ts

@@ -0,0 +1,3 @@
+export * from './parts'
+export * from './primitives'
+export * from './radio'

package/src/components/radio/parts.ts

@@ -0,0 +1,65 @@
+import type { ElementType } from 'react'
+import {
+  RadioGroupRoot,
+  RadioGroupLabel,
+  RadioGroupIndicator,
+  RadioGroupItem,
+  RadioGroupItemText,
+  RadioGroupItemControl,
+  RadioGroupItemHiddenInput,
+} from './primitives'
+
+/**
+ * This module contains the parts of the Radio parts.
+ * @module 'radio/parts'
+ */
+
+interface RadioPartsValue {
+  /**
+   * The container of the field.
+   */
+  Root: ElementType
+  /**
+   * The label of the field.
+   */
+  Label: ElementType
+  /**
+   * The indicator that appears when a radio is checked.
+   */
+  Indicator: ElementType
+  /**
+   * An individual radio item of the field.
+   */
+  Item: ElementType
+  /**
+   * The text that labels a single radio of the field.
+   */
+  ItemText: ElementType
+  /**
+   * The visual radio control of the field.
+   */
+  ItemControl: ElementType
+  /**
+   * The native input for a radio item in the field.
+   */
+  ItemHiddenInput: ElementType
+}
+
+/**
+ * An Object containing the parts of the Radio component. For users that
+ * prefer Object component syntax.
+ *
+ * @remarks
+ *
+ * When using object component syntax, you import the RadioParts object and
+ * the entire family of components vs. only what you use.
+ */
+export const RadioParts: RadioPartsValue = {
+  Root: RadioGroupRoot,
+  Label: RadioGroupLabel,
+  Indicator: RadioGroupIndicator,
+  Item: RadioGroupItem,
+  ItemText: RadioGroupItemText,
+  ItemControl: RadioGroupItemControl,
+  ItemHiddenInput: RadioGroupItemHiddenInput,
+}

package/src/components/radio/primitives.tsx

@@ -0,0 +1,123 @@
+import {
+  RadioGroup as ArkRadioGroup,
+  type RadioGroupIndicatorProps,
+  type RadioGroupItemControlProps,
+  type RadioGroupItemHiddenInputProps,
+  type RadioGroupItemProps,
+  type RadioGroupItemTextProps,
+  type RadioGroupLabelProps,
+  type RadioGroupRootProps,
+} from '@ark-ui/react/radio-group'
+import { cx } from '@cerberus/styled-system/css'
+import {
+  radioGroup,
+  type RadioGroupVariantProps,
+} from '@cerberus/styled-system/recipes'
+
+/**
+ * This module contains the Radio primitives
+ * @module 'react/radio'
+ */
+
+/**
+ * The RadioGroupRoot component is used to group radio buttons together.
+ */
+export function RadioGroupRoot(
+  props: RadioGroupRootProps & RadioGroupVariantProps,
+) {
+  const { size, orientation, ...rootProps } = props
+  const styles = radioGroup({ size, orientation })
+  return (
+    <ArkRadioGroup.Root
+      {...rootProps}
+      className={cx(styles.root, rootProps.className)}
+    />
+  )
+}
+
+/**
+ * The RadioGroupLabel component is used to label a group of radio buttons.
+ */
+export function RadioGroupLabel(props: RadioGroupLabelProps) {
+  const styles = radioGroup()
+  return (
+    <ArkRadioGroup.Label
+      {...props}
+      className={cx(styles.label, props.className)}
+    />
+  )
+}
+
+/**
+ * The RadioGroupIndicator component is used to indicate the selected radio
+ * button in a group.
+ */
+export function RadioGroupIndicator(props: RadioGroupIndicatorProps) {
+  const styles = radioGroup()
+  return (
+    <ArkRadioGroup.Indicator
+      {...props}
+      className={cx(styles.indicator, props.className)}
+    />
+  )
+}
+
+/**
+ * The RadioGroupItem component is used to render a single radio button in a
+ * group.
+ */
+export function RadioGroupItem(props: RadioGroupItemProps) {
+  const styles = radioGroup()
+  return (
+    <ArkRadioGroup.Item
+      {...props}
+      className={cx(styles.item, props.className)}
+    />
+  )
+}
+
+/**
+ * The RadioGroupItemText component is used to render the text label for a
+ * single radio button in a group.
+ */
+export function RadioGroupItemText(
+  props: RadioGroupItemTextProps & RadioGroupVariantProps,
+) {
+  const { size, orientation, ...itemTextProps } = props
+  const styles = radioGroup({ size, orientation })
+  return (
+    <ArkRadioGroup.ItemText
+      {...itemTextProps}
+      className={cx(styles.itemText, itemTextProps.className)}
+    />
+  )
+}
+
+/**
+ * The RadioGroupItemControl component is used to render the control for a
+ * single radio button in a group.
+ */
+export function RadioGroupItemControl(
+  props: RadioGroupItemControlProps & RadioGroupVariantProps,
+) {
+  const { size, orientation, ...itemControlProps } = props
+  const styles = radioGroup({ size, orientation })
+  return (
+    <ArkRadioGroup.ItemControl
+      {...itemControlProps}
+      className={cx(styles.itemControl, itemControlProps.className)}
+    />
+  )
+}
+
+/**
+ * The RadioGroupItemHiddenInput component is used to render the hidden input
+ * for a single radio button in a group.
+ */
+export function RadioGroupItemHiddenInput(
+  props: RadioGroupItemHiddenInputProps,
+) {
+  return <ArkRadioGroup.ItemHiddenInput {...props} />
+}
+
+export const RadioGroup = RadioGroupRoot