Form

어느 field가 잘못되었는지 아는 <form>입니다. 제출하면 모든 field의 유효성을 한 번에 모아 처음 실패한 곳으로 focus를 옮기고, 서버가 보낸 오류는 그 오류가 속한 field 위에 놓입니다.

import { Button, Form, TextField } from 'neba';

<Form onSubmit={(values) => save(values)}>
  <TextField label="Email" name="email" type="email" required />
  <Button type="submit">Create account</Button>
</Form>;

Props

Prop	타입	기본값	설명
onSubmit	(values: Record<string, unknown>) => void	—	모든 field가 유효할 때만, 각 field의 name을 키로 하는 값 객체와 함께 호출됩니다. 네이티브 submit 이벤트는 막히므로 페이지가 이동하지 않습니다
validationMode	'onSubmit' | 'onBlur' | 'onChange'	'onSubmit'	field가 언제 검사받는지. onSubmit은 제출할 때(그 뒤로는 변경할 때마다), onBlur는 focus가 빠질 때, onChange는 키를 누를 때마다입니다
errors	Record<string, string | string[]>	—	브라우저 바깥에서 온 오류(서버, form action, 스키마)를 field의 name으로 키를 잡아 전달합니다. 해당 field에 표시되고 그 field가 바뀌면 사라집니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	children 사이의 간격. form은 세로 열이고, 이것이 어느 사다리 위에 쌓이는지를 정합니다
children	ReactNode	—	field들과 제출 버튼

<form>의 모든 속성이 그대로 전달됩니다. 이벤트 대신 값을 받는 onSubmit만 예외입니다. 이것은 form 라이브러리가 아닙니다. 스키마도, resolver도, field array도 없습니다. 그런 것이 필요한 프로젝트는 쓰던 것을 그대로 쓰고 결과를 errors로 넘기면 됩니다. 이 컴포넌트는 그 이음매를 중심으로 설계되었습니다.

children은 size가 정한 간격의 세로 열로 놓입니다. 다른 배치가 필요하면 안에 Grid나 Fieldset을 두세요.

예시

onSubmit

모든 field가 유효할 때만 호출되며, 각 field의 name을 키로 하는 값 객체를 받습니다. 네이티브 submit 이벤트는 막히므로 페이지가 이동하지 않습니다.

validationMode

기본값 onSubmit은 사용자가 아직 이메일을 입력하는 도중에 틀렸다고 말하지 않는 유일한 값입니다. 첫 제출 이후에는 변경할 때마다 다시 검사합니다. onBlur는 focus가 빠질 때, onChange는 키를 누를 때마다 검사합니다.

import { Button, Form, TextField } from 'neba';

const modes = ['onSubmit', 'onBlur', 'onChange'] as const;

export default function FormValidationMode() {
  return (
    <div className="grid w-full max-w-2xl grid-cols-1 gap-6 sm:grid-cols-3">
      {modes.map((mode) => (
        <Form key={mode} size="sm" validationMode={mode} onSubmit={() => {}}>
          <TextField
            size="sm"
            label={mode}
            name="email"
            type="email"
            required
            placeholder="[email protected]"
          />
          <Button size="sm" type="submit">
            Submit
          </Button>
        </Form>
      ))}
    </div>
  );
}

errors

브라우저 자체 유효성 검사 바깥에서 온 오류(서버, form action, 스키마)를 각 오류가 속한 field의 name으로 키를 잡아 전달합니다. 해당 field 위에 표시되고, 그 field가 바뀌는 즉시 사라집니다.

import { useState } from 'react';
import { Button, Form, TextField } from 'neba';

/** Stands in for a server that already knows this address. */
const TAKEN = '[email protected]';

export default function FormErrors() {
  const [errors, setErrors] = useState<Record<string, string>>({});

  return (
    <Form
      className="w-full max-w-sm"
      errors={errors}
      onSubmit={(values) =>
        setErrors(values.email === TAKEN ? { email: 'That address is already taken.' } : {})
      }
    >
      <TextField
        label="Email"
        name="email"
        type="email"
        required
        defaultValue={TAKEN}
        description={`Submit as ${TAKEN} to see the server answer.`}
      />
      <Button type="submit">Check</Button>
    </Form>
  );
}

접근성

• 제출이 실패하면 처음 유효하지 않은 field로 focus가 옮겨갑니다. 문제가 있다고 알리는 대신 문제로 데려갑니다.
• 각 메시지는 aria-describedby로 자기 field와 연결되고, field에는 aria-invalid가 붙습니다.
• 한 페이지에 form이 둘 이상이면 aria-label을 주세요.