@saas-ui/forms 2.0.0-next.0 → 2.0.0-next.10

package/src/select/select.tsx

@@ -10,176 +10,192 @@ import {
   MenuListProps,
   MenuItemOption,
   MenuOptionGroup,
-  MenuOptionGroupProps,
   Button,
   ButtonProps,
   omitThemingProps,
   useMultiStyleConfig,
   SystemStyleObject,
-  useFormControl,
-  HTMLChakraProps,
+  MenuItemOptionProps,
+  useFormControlContext,
 } from '@chakra-ui/react'
-import { ChevronDownIcon } from '@chakra-ui/icons'
-import { cx, __DEV__ } from '@chakra-ui/utils'
+import { cx, dataAttr } from '@chakra-ui/utils'
+import { ChevronDownIcon } from '@saas-ui/core'
 
-interface Option {
-  value: string
-  label?: string
-}
+import { FieldOption } from '../types'
 
-interface SelectOptions {
-  /**
-   * An array of options
-   * If you leave this empty the children prop will be rendered.
-   */
-  options?: Option[]
-  /**
-   * Props passed to the MenuList.
-   */
-  menuListProps?: MenuListProps
-  /**
-   * Customize how the value is rendered.
-   * @type (value?: string[]) => React.ReactElement
-   */
-  renderValue?: (value?: string[]) => React.ReactElement | undefined
-  /**
-   * Enable multiple select.
-   */
-  multiple?: boolean
-}
+import {
+  SelectOptions,
+  SelectProvider,
+  useSelect,
+  useSelectContext,
+} from './select-context'
+
+export interface SelectOption
+  extends Omit<MenuItemOptionProps, 'value'>,
+    FieldOption {}
 
 export interface SelectProps
   extends Omit<MenuProps, 'children'>,
-    Pick<ButtonProps, 'isDisabled' | 'leftIcon' | 'rightIcon'>,
-    Pick<MenuOptionGroupProps, 'onChange'>,
     SelectOptions {}
 
-const SelectButton = forwardRef((props, ref) => {
-  const styles = useMultiStyleConfig('Input', props)
-
-  /* @ts-ignore */
-  const focusStyles = styles.field._focusVisible
-
-  const height = styles.field.h || styles.field.height
-
-  const buttonStyles: SystemStyleObject = {
-    fontWeight: 'normal',
-    textAlign: 'left',
-    color: 'inherit',
-    _active: {
-      bg: 'transparent',
-    },
-    minH: height,
-    _focus: focusStyles,
-    _expanded: focusStyles,
-    ...styles.field,
-    h: 'auto',
+export interface SelectButtonProps extends ButtonProps {}
+
+/**
+ * Button that opens the select menu and displays the selected value.
+ *
+ * @see https://saas-ui.dev/docs/components/forms/select
+ */
+export const SelectButton = forwardRef<SelectButtonProps, 'button'>(
+  (props, ref) => {
+    const styles = useMultiStyleConfig('SuiSelect', props)
+
+    const {
+      displayValue,
+      renderValue,
+      placeholder,
+      isDisabled: isSelectDisabled,
+    } = useSelectContext()
+
+    const context = useFormControlContext()
+
+    const {
+      isInvalid,
+      isReadOnly,
+      isDisabled,
+      isFocused,
+      isRequired,
+      id,
+      onBlur,
+      onFocus,
+    } = context || {}
+
+    const { rightIcon = <ChevronDownIcon />, ...rest } = props
+
+    /* @ts-ignore */
+    const focusStyles = styles.field?._focusVisible
+    /* @ts-ignore */
+    const readOnlyStyles = styles.field?._readOnly
+    /* @ts-ignore */
+    const invalid = styles.field?._invalid
+
+    const height = styles.field?.h || styles.field?.height
+
+    const buttonStyles: SystemStyleObject = {
+      fontWeight: 'normal',
+      textAlign: 'left',
+      color: 'inherit',
+      _active: {
+        bg: 'transparent',
+      },
+      minH: height,
+      _focus: focusStyles,
+      _expanded: focusStyles,
+      _readOnly: readOnlyStyles,
+      _invalid: invalid,
+      ...styles.field,
+      h: 'auto',
+    }
+
+    // Using a Button, so we can simply use leftIcon and rightIcon
+    return (
+      <MenuButton
+        as={Button}
+        id={id || React.useId()}
+        {...rest}
+        onFocus={onFocus}
+        onBlur={onBlur}
+        isDisabled={isDisabled || isSelectDisabled}
+        data-invalid={dataAttr(isInvalid)}
+        data-read-only={dataAttr(isReadOnly)}
+        data-focus={dataAttr(isFocused)}
+        data-required={dataAttr(isRequired)}
+        rightIcon={rightIcon}
+        ref={ref}
+        sx={buttonStyles}
+      >
+        {renderValue(displayValue) || placeholder}
+      </MenuButton>
+    )
   }
+)
 
-  // Using a Button, so we can simply use leftIcon and rightIcon
-  return <MenuButton as={Button} {...props} ref={ref} sx={buttonStyles} />
-})
-
-if (__DEV__) {
-  SelectButton.displayName = 'SelectButton'
-}
+SelectButton.displayName = 'SelectButton'
 
+/**
+ * Allow users to select a value from a list of options.
+ *
+ * @see https://saas-ui.dev/docs/components/forms/select
+ */
 export const Select = forwardRef<SelectProps, 'select'>((props, ref) => {
-  const {
-    name,
-    options,
-    children,
-    onChange,
-    defaultValue,
-    value,
-    placeholder,
-    isDisabled,
-    leftIcon,
-    rightIcon = <ChevronDownIcon />,
-    multiple,
-    size,
-    variant,
-    menuListProps,
-    renderValue = (value) => value?.join(', '),
-    ...rest
-  } = props
-  const menuProps = omitThemingProps(rest)
+  const { name, children, isDisabled, multiple, ...rest } = props
 
-  const [currentValue, setCurrentValue] = React.useState(value || defaultValue)
-
-  const controlProps = useFormControl({ name } as HTMLChakraProps<'input'>)
+  const menuProps = omitThemingProps(rest)
 
-  const handleChange = (value: string | string[]) => {
-    setCurrentValue(value)
-    onChange?.(value)
-  }
+  const context = useSelect(props)
 
-  const buttonProps = {
-    isDisabled,
-    leftIcon,
-    rightIcon,
-    size,
-    variant,
-  }
+  const { value, controlProps } = context
 
-  const getDisplayValue = React.useCallback(
-    (value: string) => {
-      if (!options) {
-        return value
-      }
-
-      for (const option of options) {
-        if (option.label && option.value === value) {
-          return option.label
-        }
-      }
-
-      return value
-    },
-    [options]
+  return (
+    <SelectProvider value={context}>
+      <Menu {...menuProps} closeOnSelect={!multiple}>
+        <chakra.div className={cx('sui-select')}>
+          {children}
+          <chakra.input
+            {...controlProps}
+            ref={ref}
+            name={name}
+            type="hidden"
+            value={value || ''}
+            className="saas-select__input"
+          />
+        </chakra.div>
+      </Menu>
+    </SelectProvider>
   )
+})
+
+export interface SelectListProps extends MenuListProps {}
 
-  const displayValue = currentValue
-    ? (Array.isArray(currentValue) ? currentValue : [currentValue]).map(
-        getDisplayValue
-      )
-    : []
+/**
+ * The list of options to choose from.
+ *
+ * @see https://saas-ui.dev/docs/components/forms/select
+ */
+export const SelectList: React.FC<SelectListProps> = (props) => {
+  const { defaultValue, value, options, multiple, onChange } =
+    useSelectContext()
 
   return (
-    <Menu {...menuProps} closeOnSelect={!multiple}>
-      <chakra.div className={cx('sui-select')}>
-        <SelectButton ref={ref} {...buttonProps}>
-          {renderValue(displayValue) || placeholder}
-        </SelectButton>
-        <MenuList maxH="60vh" overflowY="auto" {...menuListProps}>
-          <MenuOptionGroup
-            defaultValue={
-              (defaultValue || value) as string | string[] | undefined
-            }
-            onChange={handleChange}
-            type={multiple ? 'checkbox' : 'radio'}
-          >
-            {options
-              ? options.map(({ value, label, ...rest }, i) => (
-                  <MenuItemOption key={i} value={value} {...rest}>
-                    {label || value}
-                  </MenuItemOption>
-                ))
-              : children}
-          </MenuOptionGroup>
-        </MenuList>
-        <chakra.input
-          {...controlProps}
-          name={name}
-          type="hidden"
-          value={currentValue}
-          className="saas-select__input"
-        />
-      </chakra.div>
-    </Menu>
+    <MenuList maxH="100vh" overflowY="auto" {...props}>
+      <MenuOptionGroup
+        defaultValue={(defaultValue || value) as string | string[] | undefined}
+        value={value}
+        onChange={onChange}
+        type={multiple ? 'checkbox' : 'radio'}
+      >
+        {options
+          ? options.map(({ value, label, ...rest }, i) => (
+              <SelectOption key={i} value={value} {...rest}>
+                {label || value}
+              </SelectOption>
+            ))
+          : props.children}
+      </MenuOptionGroup>
+    </MenuList>
   )
-})
-
-if (__DEV__) {
-  Select.displayName = 'Select'
 }
+
+Select.displayName = 'Select'
+
+/**
+ * An option in a select list
+ *
+ * @see https://saas-ui.dev/docs/components/forms/select
+ */
+export const SelectOption = forwardRef<MenuItemOptionProps, 'button'>(
+  (props, ref) => {
+    return <MenuItemOption ref={ref} {...props} />
+  }
+)
+SelectOption.id = 'MenuItemOption'
+SelectOption.displayName = 'SelectOption'

package/src/step-form.tsx

@@ -10,7 +10,7 @@ import {
   ThemingProps,
 } from '@chakra-ui/react'
 
-import { callAllHandlers, runIfFn, cx, __DEV__ } from '@chakra-ui/utils'
+import { callAllHandlers, runIfFn, cx } from '@chakra-ui/utils'
 
 import {
   StepperProvider,
@@ -38,6 +38,11 @@ export interface StepFormProps<
   TContext extends object = object
 > extends UseStepFormProps<TFieldValues> {}
 
+/**
+ * The wrapper component provides context, state, and focus management.
+ *
+ * @see Docs https://saas-ui.dev/docs/components/forms/step-form
+ */
 export const StepForm = React.forwardRef(
   <
     TFieldValues extends FieldValues = FieldValues,
@@ -89,6 +94,11 @@ export interface FormStepperProps
   extends StepperStepsProps,
     ThemingProps<'Stepper'> {}
 
+/**
+ * Renders a stepper that displays progress above the form.
+ *
+ * @see Docs https://saas-ui.dev/docs/components/forms/step-form
+ */
 export const FormStepper: React.FC<FormStepperProps> = (props) => {
   const { activeIndex, setIndex } = useStepperContext()
 
@@ -139,7 +149,11 @@ export interface FormStepProps
     Omit<HTMLChakraProps<'div'>, 'onSubmit'> {
   onSubmit?: FormStepSubmitHandler
 }
-
+/**
+ * The form step containing fields for a specific step.
+ *
+ * @see Docs https://saas-ui.dev/docs/components/forms/step-form
+ */
 export const FormStep: React.FC<FormStepProps> = (props) => {
   const { name, schema, resolver, children, className, onSubmit, ...rest } =
     props
@@ -154,10 +168,13 @@ export const FormStep: React.FC<FormStepProps> = (props) => {
   ) : null
 }
 
-if (__DEV__) {
-  FormStep.displayName = 'FormStep'
-}
+FormStep.displayName = 'FormStep'
 
+/**
+ * A button that this opens the previous step when clicked. Disabled on the first step.
+ *
+ * @see Docs https://saas-ui.dev/docs/components/forms/step-form
+ */
 export const PrevButton: React.FC<ButtonProps> = (props) => {
   const { isFirstStep, isCompleted, prevStep } = useStepperContext()
 
@@ -172,15 +189,18 @@ export const PrevButton: React.FC<ButtonProps> = (props) => {
   )
 }
 
-if (__DEV__) {
-  PrevButton.displayName = 'PrevButton'
-}
+PrevButton.displayName = 'PrevButton'
 
 export interface NextButtonProps extends Omit<ButtonProps, 'children'> {
   submitLabel?: string
   label?: string
 }
 
+/**
+ * A button that submits the active step.
+ *
+ * @see Docs https://saas-ui.dev/docs/components/forms/step-form
+ */
 export const NextButton: React.FC<NextButtonProps> = (props) => {
   const { label = 'Next', submitLabel = 'Complete', ...rest } = props
   const { isLastStep, isCompleted } = useStepperContext()
@@ -196,6 +216,4 @@ export const NextButton: React.FC<NextButtonProps> = (props) => {
   )
 }
 
-if (__DEV__) {
-  NextButton.displayName = 'NextButton'
-}
+NextButton.displayName = 'NextButton'

package/src/submit-button.tsx

@@ -20,7 +20,11 @@ export interface SubmitButtonProps extends ButtonProps {
    */
   disableIfInvalid?: boolean
 }
-
+/**
+ * A button with type submit and default color scheme primary and isLoading state when the form is submitting.
+ *
+ * @see Docs https://saas-ui.dev/docs/components/forms/form
+ */
 export const SubmitButton = forwardRef<SubmitButtonProps, 'button'>(
   (props, ref) => {
     const {

package/src/types.ts

@@ -0,0 +1,144 @@
+import { FormControlProps } from '@chakra-ui/react'
+import { MaybeRenderProp } from '@chakra-ui/react-utils'
+import { FieldPath, FieldValues, RegisterOptions } from 'react-hook-form'
+import { DefaultFields } from './default-fields'
+import { FormProps, FormRenderContext } from './form'
+import { SubmitButtonProps } from './submit-button'
+
+export type FieldOption = { label?: string; value: string }
+export type FieldOptions<TOption extends FieldOption = FieldOption> =
+  | Array<string>
+  | Array<TOption>
+
+export type ValueOf<T> = T[keyof T]
+export type ShallowMerge<A, B> = Omit<A, keyof B> & B
+
+type Split<S extends string, D extends string> = string extends S
+  ? string[]
+  : S extends ''
+  ? []
+  : S extends `${infer T}${D}${infer U}`
+  ? [T, ...Split<U, D>]
+  : [S]
+
+type MapPath<T extends string[]> = T extends [infer U, ...infer R]
+  ? U extends string
+    ? `${U extends `${number}` ? '$' : U}${R[0] extends string
+        ? '.'
+        : ''}${R extends string[] ? MapPath<R> : ''}`
+    : ''
+  : ''
+
+type TransformPath<T extends string> = MapPath<Split<T, '.'>>
+
+export type ArrayFieldPath<Name extends string> = Name extends string
+  ? TransformPath<Name>
+  : never
+
+export interface BaseFieldProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
+> extends Omit<FormControlProps, 'label' | 'type'> {
+  /**
+   * The field name
+   */
+  name: TName | ArrayFieldPath<TName>
+  /**
+   * The field label
+   */
+  label?: string
+  /**
+   * Hide the field label
+   */
+  hideLabel?: boolean
+  /**
+   * Field help text
+   */
+  help?: string
+  /**
+   * React hook form rules
+   */
+  rules?: Omit<
+    RegisterOptions<TFieldValues, TName>,
+    'valueAsNumber' | 'valueAsDate' | 'setValueAs' | 'disabled'
+  >
+  /**
+   * Build-in types:
+   * text, number, password, textarea, select, native-select, checkbox, radio, switch, pin
+   *
+   * Will default to a text field if there is no matching type.
+   */
+  type?: string
+  /**
+   * The input placeholder
+   */
+  placeholder?: string
+}
+
+type FieldPathWithArray<
+  TFieldValues extends FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
+> = TName | ArrayFieldPath<TName>
+
+type MergeFieldProps<
+  FieldDefs,
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
+> = ValueOf<{
+  [K in keyof FieldDefs]: FieldDefs[K] extends React.FC<infer Props>
+    ? { type?: K } & ShallowMerge<Props, BaseFieldProps<TFieldValues, TName>>
+    : never
+}>
+
+export type FieldProps<TFieldValues extends FieldValues = FieldValues> =
+  MergeFieldProps<DefaultFields, TFieldValues>
+
+export type FormChildren<
+  FieldDefs,
+  TFieldValues extends FieldValues = FieldValues,
+  TContext extends object = object
+> = MaybeRenderProp<
+  FormRenderContext<
+    TFieldValues,
+    TContext,
+    MergeFieldProps<
+      FieldDefs extends never
+        ? DefaultFields
+        : ShallowMerge<DefaultFields, FieldDefs>,
+      TFieldValues
+    >
+  >
+>
+
+export type DefaultFieldOverrides = {
+  submit?: SubmitButtonProps
+  [key: string]: any
+}
+
+export type FieldOverrides<
+  FieldDefs,
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
+> = {
+  [K in FieldPathWithArray<TFieldValues, TName>]?: Omit<
+    MergeFieldProps<
+      FieldDefs extends never
+        ? DefaultFields
+        : ShallowMerge<DefaultFields, FieldDefs>,
+      TFieldValues
+    >,
+    'name'
+  >
+}
+
+export type WithFields<
+  TFormProps extends FormProps<any, any, any, any>,
+  FieldDefs
+> = TFormProps extends FormProps<infer TFieldValues, infer TContext>
+  ? Omit<TFormProps, 'children' | 'fields'> & {
+      children?: FormChildren<FieldDefs, TFieldValues, TContext>
+      fields?: FieldOverrides<FieldDefs, TFieldValues> & {
+        submit?: SubmitButtonProps
+      }
+    }
+  : never

package/src/use-array-field.tsx

@@ -1,10 +1,13 @@
 import * as React from 'react'
 import {
   useFieldArray,
-  useFormContext,
   UseFieldArrayReturn,
+  FieldValues,
+  FieldPath,
 } from 'react-hook-form'
 
+import { useFormContext } from './form-context'
+
 import { createContext } from '@chakra-ui/react-utils'
 
 export interface UseArrayFieldReturn extends UseFieldArrayReturn {
@@ -59,11 +62,14 @@ export const [ArrayFieldRowProvider, useArrayFieldRowContext] =
     name: 'ArrayFieldRowContext',
   })
 
-export interface ArrayFieldOptions {
+export interface ArrayFieldOptions<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
+> {
   /**
    * The field name
    */
-  name: string
+  name: TName
   /**
    * Default value for new values in the array
    */

package/src/utils.ts

@@ -1,13 +1,35 @@
 import * as React from 'react'
+import { FieldOption, FieldOptions } from './types'
 
 export const mapNestedFields = (name: string, children: React.ReactNode) => {
   return React.Children.map(children, (child) => {
     if (React.isValidElement(child) && child.props.name) {
+      let childName = child.props.name
+      if (childName.includes('.')) {
+        childName = childName.replace(/^.*\.(.*)/, '$1')
+      } else if (childName.includes('.$')) {
+        childName = childName.replace(/^.*\.\$(.*)/, '$1')
+      }
+
       return React.cloneElement(child, {
         ...child.props,
-        name: `${name}.${child.props.name}`,
+        name: `${name}.${childName}`,
       })
     }
     return child
   })
 }
+
+export const mapOptions = <TOption extends FieldOption = FieldOption>(
+  options: FieldOptions<TOption>
+) => {
+  return options.map((option) => {
+    if (typeof option === 'string') {
+      return {
+        label: option,
+        value: option,
+      }
+    }
+    return option
+  })
+}

package/src/watch-field.tsx

@@ -1,9 +1,5 @@
-import {
-  FieldValues,
-  useFormContext,
-  UseFormReturn,
-  useWatch,
-} from 'react-hook-form'
+import { FieldValues, useWatch } from 'react-hook-form'
+import { useFormContext, UseFormReturn } from './form-context'
 
 export interface WatchFieldProps<
   Value = unknown,