폼 워크플로

미리보기

로컬 미리보기입니다. 실제 계정, 환경, 실행 데이터에는 영향을 주지 않습니다.

사용법

Form, Field, Fieldset, 메시지로 검증, 제출 대기, 필드 오류, 요청 실패, 접근 제한, 성공을 연결하세요. 입력 값은 controlled 상태로 유지하세요. 결과는 제출 시점에 복사한 값으로 설명하세요. 예시는 응답을 수동으로 확정합니다. Complete preview request 로 각 상태를 확인하세요.

• 서비스 호출이나 권한 정책을 프리미티브 안에 숨기지 마세요. 제품에 두세요.
• 오류를 빈 성공으로 보여주지 마세요. 필드 오류, 요청 실패, 접근 제한을 각각의 상태로 보여주세요.
• 취소가 서버를 롤백한다고 약속하지 마세요. 취소는 요청을 멈추고 초안을 보존합니다.
• 클라이언트 검사만 믿지 마세요. 제품 API에도 서버 검증, 권한 확인, 멱등성, 중복 요청 방지가 필요합니다.
• 예시는 접근 복원을 로컬에서 시뮬레이션합니다.

구성

Preview response control → result message → named Form → Fieldset(Fields + errors) + submit/reset actions → pending request controls

키보드와 접근성

• Base UI Form 은 제출 전 검증을 실행하고 첫 번째 오류 입력에 포커스를 둡니다.
• 대기 중에는 중복 제출이 차단되고 포커스가 Cancel 로 이동합니다.
• 서버 필드 오류는 errors 의 Field.name 키로 필드에 매핑됩니다. 필드 오류는 해당 입력으로, 요청 오류는 Retry 로, 성공은 결과 제목으로 포커스를 이동합니다.
• 취소하거나 초기화하면 포커스가 name 입력으로 돌아갑니다.
• Field 는 각 설명과 오류를 컨트롤에 연결합니다. 색만으로 의미를 전달하지 않습니다.

각 컨트롤에 목적을 설명하는 이름을 지정하세요. 오류 메시지를 해당 컨트롤에 연결하고, 상태를 색만으로 알리지 마세요. 자동 검사는 수동 키보드 및 보조 기술 테스트를 대신하지 않습니다.

예시 코드

공유 컴포넌트는 디자인 토큰에서 스타일을 가져옵니다. 각 예시는 자체 구성과 접근성 속성을 설정합니다. 호출하는 화면이 콜백, ref, 제품 데이터를 정의합니다.

import { Form, Field, Fieldset, Button } from '@surflane/ui'

<Form errors={serverErrors} onFormSubmit={submit} aria-busy={pending}>
  <Fieldset.Root disabled={pending}>
    <Fieldset.Legend>Environment details</Fieldset.Legend>
    <Field.Root name='name'>
      <Field.Label>Environment name</Field.Label>
      <Field.Control
        required
        value={name}
        onChange={(e) => setName(e.target.value)}
      />
      <Field.Error />
    </Field.Root>
  </Fieldset.Root>
  <Button type='submit' disabled={pending}>
    Register preview
  </Button>
</Form>

// Product-owned submission contract:
// 1. Guard repeated submits before awaiting. Snapshot validated values.
// 2. Retain an AbortController and request identity.
// 3. Ignore aborted, superseded or unmounted responses.
// 4. Map field errors by Field.name; preserve draft and restore meaningful focus.
// 5. Server-side idempotency and authorization remain required.

주요 API

표는 공통 래퍼의 주요 props를 나열합니다. 전체 타입은 패키지 타입 선언을 참조하세요.

관련 토큰