@cerberus-design/react 0.15.0 → 0.16.0-next-4f6c716

package/src/components/field/field.tsx

@@ -0,0 +1,77 @@
+import { type FieldRootProps } from '@ark-ui/react/field'
+import { splitProps } from '../../utils/index'
+import {
+  FieldErrorText,
+  FieldHelperText,
+  FieldLabel,
+  FieldRoot,
+} from './primitives'
+import { HStack } from '@cerberus/styled-system/jsx'
+import { Show } from '../Show'
+
+export interface FieldProps extends FieldRootProps {
+  /**
+   * The label of the field.
+   */
+  label?: string
+  /**
+   * The helper text of the field.
+   */
+  helperText?: string
+  /**
+   * A helper text positioned at the end of the field. Good for Textarea fields.
+   */
+  secondaryHelperText?: string
+  /**
+   * The error text of the field. Shown when the field is invalid.
+   */
+  errorText?: string
+}
+
+/**
+ * The Field component is the context provider for all FieldParts and displays
+ * the label, helperText, and ErrorText.
+ * @description [Field Docs](https://cerberus.digitalu.design/react/field)
+ * @example
+ * ```tsx
+ * <Field
+ *  ids={{
+ *   control: 'firstName',
+ *  }}
+ *  label="Label"
+ *  helperText="This is what people will see on your profile."
+ *  errorText="A first name is required to create an account."
+ *  required
+ * >
+ *   <Input name="firstName" type="text" />
+ * </Field>
+ * ```
+ */
+export function Field(props: FieldProps) {
+  const [statusProps, fieldProps, rootProps] = splitProps(
+    props,
+    ['disabled', 'required', 'readOnly', 'invalid'],
+    ['label', 'helperText', 'secondaryHelperText', 'errorText', 'children'],
+  )
+
+  return (
+    <FieldRoot {...statusProps} {...rootProps}>
+      <Show when={Boolean(fieldProps.label)}>
+        <FieldLabel>{fieldProps.label}</FieldLabel>
+      </Show>
+
+      {fieldProps.children}
+
+      <Show when={Boolean(fieldProps.helperText && !statusProps.invalid)}>
+        <HStack justifyContent="space-between" w="full">
+          <FieldHelperText>{fieldProps.helperText}</FieldHelperText>
+          <Show when={Boolean(fieldProps.secondaryHelperText)}>
+            <FieldHelperText>{fieldProps.secondaryHelperText}</FieldHelperText>
+          </Show>
+        </HStack>
+      </Show>
+
+      <FieldErrorText>{fieldProps.errorText}</FieldErrorText>
+    </FieldRoot>
+  )
+}

package/src/components/field/index.ts

@@ -0,0 +1,5 @@
+export * from './field'
+export * from './primitives'
+export * from './start-indicator'
+export * from './status-indicator'
+export * from './parts'

package/src/components/field/parts.ts

@@ -0,0 +1,77 @@
+import type { ElementType } from 'react'
+import {
+  FieldErrorText,
+  FieldHelperText,
+  FieldInput,
+  FieldLabel,
+  FieldRequiredIndicator,
+  FieldRoot,
+  FieldTextarea,
+} from './primitives'
+import { FieldStatusIndicator } from './status-indicator'
+import { FieldStartIndicator } from './start-indicator'
+
+/**
+ * This module contains the parts of the Field component.
+ * @module 'field/parts'
+ */
+
+interface FieldPartsValue {
+  /**
+   * The container of the field.
+   */
+  Root: ElementType
+  /**
+   * The label of the field.
+   */
+  Label: ElementType
+  /**
+   * The input of the field.
+   */
+  Input: ElementType
+  /**
+   * The textarea of the field.
+   */
+  Textarea: ElementType
+  /**
+   * The text that displays when the field is valid.
+   */
+  HelperText: ElementType
+  /**
+   * The text that displays when the field is invalid.
+   */
+  ErrorText: ElementType
+  /**
+   * The indicator that appears at the start of the field.
+   */
+  StartIndicator: ElementType
+  /**
+   * The status indicator of the field.
+   */
+  StatusIndicator: ElementType
+  /**
+   * The indicator that appears at the end of the field.
+   */
+  RequiredIndicator: 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 FieldParts: FieldPartsValue = {
+  Root: FieldRoot,
+  Label: FieldLabel,
+  Input: FieldInput,
+  Textarea: FieldTextarea,
+  HelperText: FieldHelperText,
+  ErrorText: FieldErrorText,
+  StartIndicator: FieldStartIndicator,
+  StatusIndicator: FieldStatusIndicator,
+  RequiredIndicator: FieldRequiredIndicator,
+}

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,43 @@
+import type { ReactNode } from 'react'
+
+export interface ForProps<T> {
+  /**
+   * The array to iterate over
+   */
+  each: T[]
+  /**
+   * The fallback content to render when the array is empty
+   */
+  fallback?: ReactNode
+  /**
+   * The render function to render each item in the array
+   */
+  children: (item: Exclude<T, undefined>, index: number) => ReactNode
+}
+
+/**
+ * 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 string | number | Record<string, unknown> | object | undefined,
+>(props: ForProps<T>) {
+  const mappableChildren = props.children as unknown as (
+    item: T,
+    index: number,
+  ) => ReactNode
+
+  if (props.each?.length === 0) {
+    return props.fallback || null
+  }
+
+  return props.each?.map(mappableChildren) as ReactNode
+}

package/src/components/radio/index.ts

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