# Field

> Membungkus satu kontrol form dengan label, hint, dan pesan error.

Field menaruh label di atas kontrol form, hint satu kalimat di bawahnya, dan pesan error dari backend saat nilainya ditolak.

## Kapan dipakai

- Bungkus setiap kontrol form yang diisi orang: Input, Textarea, Select, Combobox, Input OTP.
- Pakai `FieldSet` dengan `FieldLegend` untuk mengelompokkan kontrol yang menjawab satu pertanyaan, misalnya Radio Group.
- Pakai orientasi `horizontal` hanya untuk Switch atau Checkbox, dengan kontrol di depan labelnya.
- Jangan tulis pesan error di klien. Backend memeriksa setiap field dan mengirim pesannya; klien hanya menonaktifkan tombol kirim sampai field wajib terisi.

_Pratinjau langsung versi React dan Vue: https://design.sosialoka.tech/id/components/field/_

## Anatomi

1. Label
2. Kontrol, garis merah saat tidak valid
3. Petunjuk
4. Pesan error dari backend

1. **Label** (`FieldLabel`): di atas kontrol, warna `foreground`. Berubah `destructive` saat field tidak valid.
2. **Kontrol**: input, textarea, atau kontrol lain, dengan `aria-invalid` selama nilainya ditolak.
3. **Hint** (`FieldDescription`): satu kalimat praktis berwarna `muted-foreground`.
4. **Error** (`FieldError`): pesan dari backend berwarna `destructive`, dengan `role="alert"`.

Hubungkan kontrol ke hint dan error lewat `aria-describedby`, supaya pembaca layar membacakan keduanya. Field tidak menambahkan id-nya otomatis.

## Varian

| Orientasi | Pakai untuk |
| --- | --- |
| `vertical` (bawaan) | Semua kontrol teks: label di atas, hint dan error di bawah. |
| `horizontal` | Switch atau Checkbox: kontrol di kiri, label dan hint di kanan. |

## Props

| React | Vue | Flutter | Tipe | Default | Kegunaan |
| --- | --- | --- | --- | --- | --- |
| `orientation` di `Field` | `orientation` di `Field` | widget terpisah (`ShadSwitch` punya `label` sendiri) | `vertical` / `horizontal` | `vertical` | Menaruh label di atas atau di samping kontrol. |
| `data-invalid` di `Field` | `data-invalid="true"` di `Field` (`data-invalid` tanpa nilai dirender kosong dan tidak cocok) | `forceErrorText` | boolean / teks | tidak ada | Menandai field yang ditolak. |
| `FieldLabel htmlFor` | `FieldLabel for` | `label` | teks | tidak ada | Nama kontrol. |
| `FieldDescription` | `FieldDescription` | `description` | teks | tidak ada | Hint satu kalimat. |
| `FieldError` | `FieldError` | `forceErrorText` | teks | tidak ada | Pesan error dari backend. |
| `FieldSet`, `FieldLegend` | `FieldSet`, `FieldLegend` | judul `Text` di atas kelompok | tidak ada | tidak ada | Mengelompokkan kontrol yang menjawab satu pertanyaan. |

## Kode

**React**
```tsx
import { useId } from "react"
import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { Textarea } from "@/components/ui/textarea"

export default function FieldDemo() {
  const id = useId()
  return (
    <FieldGroup className="w-full max-w-sm">
      {/* The error comes from the backend; the client only shows it. */}
      <Field data-invalid>
        <FieldLabel htmlFor={`${id}-title`}>Judul lagu</FieldLabel>
        <Input
          id={`${id}-title`}
          aria-invalid
          aria-describedby={`${id}-title-hint ${id}-title-error`}
        />
        <FieldDescription id={`${id}-title-hint`}>Tulis sesuai sampul rilis.</FieldDescription>
        <FieldError id={`${id}-title-error`}>Judul lagunya belum diisi.</FieldError>
      </Field>
      <Field>
        <FieldLabel htmlFor={`${id}-notes`}>Catatan</FieldLabel>
        <Textarea id={`${id}-notes`} aria-describedby={`${id}-notes-hint`} />
        <FieldDescription id={`${id}-notes-hint`}>Opsional, untuk tim rilis.</FieldDescription>
      </Field>
    </FieldGroup>
  )
}
```

**Vue**
```vue
<script setup lang="ts">
import { useId } from "vue"
import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { Textarea } from "@/components/ui/textarea"

const id = useId()
</script>

<template>
  <FieldGroup class="w-full max-w-sm">
    <!-- The error comes from the backend; the client only shows it. -->
    <Field data-invalid="true">
      <FieldLabel :for="`${id}-title`">Judul lagu</FieldLabel>
      <Input :id="`${id}-title`" aria-invalid="true" :aria-describedby="`${id}-title-hint ${id}-title-error`" />
      <FieldDescription :id="`${id}-title-hint`">Tulis sesuai sampul rilis.</FieldDescription>
      <FieldError :id="`${id}-title-error`">Judul lagunya belum diisi.</FieldError>
    </Field>
    <Field>
      <FieldLabel :for="`${id}-notes`">Catatan</FieldLabel>
      <Textarea :id="`${id}-notes`" :aria-describedby="`${id}-notes-hint`" />
      <FieldDescription :id="`${id}-notes-hint`">Opsional, untuk tim rilis.</FieldDescription>
    </Field>
  </FieldGroup>
</template>
```

**Flutter**
```dart
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';

class FieldDemo extends StatelessWidget {
  const FieldDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return ConstrainedBox(
      constraints: const BoxConstraints(maxWidth: 384),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        crossAxisAlignment: CrossAxisAlignment.stretch,
        spacing: 24,
        children: [
          // The error comes from the backend; the field only shows it.
          ShadInputFormField(
            id: 'title',
            label: const Text('Judul lagu'),
            description: const Text('Tulis sesuai sampul rilis.'),
            forceErrorText: 'Judul lagunya belum diisi.',
          ),
          ShadTextareaFormField(
            id: 'notes',
            label: const Text('Catatan'),
            description: const Text('Opsional, untuk tim rilis.'),
          ),
        ],
      ),
    );
  }
}
```

## Pasang

**React**
```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/field.json
```

**Vue**
```bash
npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/field.json
```

## Aksesibilitas

- Setiap kontrol punya label yang terlihat dan terhubung lewat `htmlFor` / `for`.
- Kontrol yang tidak valid punya `aria-invalid="true"` dan `aria-describedby` berisi id hint dan id error.
- Error punya `role="alert"`, jadi langsung dibacakan saat muncul.
- `FieldSet` diberi nama oleh `FieldLegend`-nya.
