diff --git a/docs/ja/README.md b/docs/ja/README.md new file mode 100644 index 00000000..a4c043e0 --- /dev/null +++ b/docs/ja/README.md @@ -0,0 +1,38 @@ +# Documentation + +- はじめに + - [概要](./overview.md) + - [チュートリアル](./tutorial.md) + - [v1 へのアップグレード](./upgrading-v1.md) +- ガイド + - [バリデーション](./validation.md) + - [ネストされたオブジェクトと配列](./complex-structures.md) + - [インテントボタン](./intent-button.md) + - [チェックボックスとラジオグループ](./checkbox-and-radio-group.md) + - [ファイルのアップロード](./file-upload.md) + - [アクセシビリティ](./accessibility.md) +- インテグレーション + - [UI ライブラリ](./integration/ui-libraries.md) + - [Remix](./integration/remix.md) + - [Next.js](./integration/nextjs.md) +- API リファレンス + - @conform-to/react + - [useForm](./api/react/useForm.md) + - [useField](./api/react/useField.md) + - [useFormMetadata](./api/react/useFormMetadata.md) + - [useInputControl](./api/react/useInputControl.md) + - [FormProvider](./api/react/FormProvider.md) + - [FormStateInput](./api/react/FormStateInput.md) + - [getFormProps](./api/react/getFormProps.md) + - [getFieldsetProps](./api/react/getFieldsetProps.md) + - [getInputProps](./api/react/getInputProps.md) + - [getSelectProps](./api/react/getSelectProps.md) + - [getTextareaProps](./api/react/getTextareaProps.md) + - [getCollectionProps](./api/react/getCollectionProps.md) + - @conform-to/yup + - [parseWithYup](./api/yup/parseWithYup.md) + - [getYupConstraint](./api/yup/getYupConstraint.md) + - @conform-to/zod + - [parseWithZod](./api/zod/parseWithZod.md) + - [getZodConstraint](./api/zod/getZodConstraint.md) + - [conformZodMessage](./api/zod/conformZodMessage.md) diff --git a/docs/ja/accessibility.md b/docs/ja/accessibility.md new file mode 100644 index 00000000..ebc0dbb7 --- /dev/null +++ b/docs/ja/accessibility.md @@ -0,0 +1,183 @@ +# アクセシビリティ + +フォームをアクセシブルにするには、各フォーム要素を適切な属性で設定する必要がありますが、 Conform がその手助けをします。 + +## Aria 属性 + +アクセシビリティに関しては、通常、異なる要素を関連付けるために一意の ID が必要になる Aria 属性が最初に思い浮かびます。Conform は、必要なすべての ID を生成してくれることで、この点でのサポートを提供します。 + +```tsx +import { useForm } from '@conform-to/react'; + +function Example() { + const [form, fields] = useForm(); + + return ( +
+ + +
The message you want to send
+
{fields.message.errors}
+ +
+ ); +} +``` + +## バリデーション属性 + +バリデーション属性も、スクリーンリーダーのヒントを改善するなど、アクセシビリティにおいて重要な役割を果たします。 Conform を使用すると、 zod や yup スキーマからバリデーション属性を導出し、各フィールドのメタデータにそれらを反映させることができます。 + +```tsx +import { parseWithZod, getZodConstraint } from '@conform-to/zod'; +import { useForm } from '@conform-to/react'; +import { z } from 'zod'; + +const schema = z.object({ + message: z + .string() + .min(10) + .max(100) + .regex(/^[A-Za-z0-9 ]{10-100}$/), +}); + +function Example() { + const [form, fields] = useForm({ + constraint: getZodConstraint(schema), + onValidate({ formData }) { + return parseWithZod(formData, { schema }); + }, + }); + + return ( +
+ + +
+ ); +} +``` + +## プログレッシブエンハンスメント + +プログレッシブエンハンスメントも、一時的なネットワークの問題の影響を最小限に抑えるなど、アクセシビリティを支援します。たとえば、 Conform を使用すると、ページのリフレッシュをまたいでもフォームデータと状態が保持されるように、フィールドリストを操作できます。 + +```tsx +import { useForm } from '@conform-to/react'; + +export default function Example() { + const [form, fields] = useForm(); + + return ( +
+ + + +
+ ); +} +``` + +## ボイラープレートの削減 + +上記で述べたすべての属性を設定することは、面倒でエラーが発生しやすい作業です。 Conform は 、関連するすべての属性を導出する一連のヘルパーを提供することで、この作業を支援しようとしています。 + +> 注意: これらすべてのヘルパーはネイティブ HTML 要素用に設計されています。 react-aria-components や Radix UI のようなカスタム UI コンポーネントを使用している場合、それらの API を通じて既に属性が設定されている可能性があるため、これらのヘルパーが不要になるかもしれません。 + +- [getFormProps](./api/react/getFormProps.md) +- [getFieldsetProps](./api/react/getFieldsetProps.md) +- [getInputProps](./api/react/getInputProps.md) +- [getSelectProps](./api/react/getSelectProps.md) +- [getTextareaProps](./api/react/getTextareaProps.md) +- [getCollectionProps](./api/react/getButtonProps.md) + +以下は、手動設定と比較した場合の例です。ヘルパーについて詳しく知りたい場合は、上記リンクの対応するドキュメントを確認してください。 + +```tsx +import { parseWithZod, getZodConstraint } from '@conform-to/zod'; +import { useForm } from '@conform-to/react'; +import { z } from 'zod'; + +const schema = z.object({ + message: z + .string() + .min(10) + .max(100) + .regex(/^[A-Za-z0-9 ]{10-100}$/), +}); + +function Example() { + const [form, fields] = useForm({ + constraint: getZodConstraint(schema), + onValidate({ formData }) { + return parseWithZod(formData, { schema }); + }, + }); + + return ( +
+ {/* ビフォー */} + + {/* アフター */} + + +
+ ); +} +``` diff --git a/docs/ja/api/react/FormProvider.md b/docs/ja/api/react/FormProvider.md new file mode 100644 index 00000000..1dad29c2 --- /dev/null +++ b/docs/ja/api/react/FormProvider.md @@ -0,0 +1,82 @@ +# FormProvider + +フォームコンテキストのための [Context Provider](https://react.dev/reference/react/createContext#provider) をレンダリングする React コンポーネントです。 [useField](./useField.md) や [useFormMetadata](./useFormMetadata.md) フックを使用したい場合には必須です。 + +```tsx +import { FormProvider, useForm } from '@conform-to/react'; + +export default function SomeParent() { + const [form, fields] = useForm(); + + return {/* ... */}; +} +``` + +## プロパティ + +### `context` + +フォームコンテキストです。これは [useForm](./useForm.md) で作成され、 `form.context` を通じてアクセスできます。 + +## Tips + +### FormProvider は、フォームの直接の親である必要はありません。 + +入力が [form 属性](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement#instance_properties_related_to_the_parent_form) を通じて関連付けられている限り、フォームの外部のどこにでも自由に入力を配置できます。 + +```tsx +function Example() { + const [form, fields] = useForm(); + return ( + +
+
+
+
+ +
+ + ); +} +``` + +### FormProvider はネストすることができます + +これは、レイアウトの制約のために 1 つのフォームを別のフォームの内部に配置する必要がある場合に便利です。 + +```tsx +import { FormProvider, useForm } from '@conform-to/react'; + +function Field({ name, formId }) { + // formId が指定されていない場合、 useField は最も近い FormContext を探します。 + const [meta] = useField(name, { formId }); + + return ; +} + +function Parent() { + const [form, fields] = useForm({ id: 'parent' }); + return ( + + + + + + + ); +} + +function Child() { + const [form, fields] = useForm({ id: 'child' }); + + return ( + + + + + {/* これは代わりに 'id' が 'parent' のフォームコンテキストを探します。 */} + + + ); +} +``` diff --git a/docs/ja/api/react/FormStateInput.md b/docs/ja/api/react/FormStateInput.md new file mode 100644 index 00000000..c9253cff --- /dev/null +++ b/docs/ja/api/react/FormStateInput.md @@ -0,0 +1,27 @@ +# FormStateInput + +ドキュメントの再読み込みが発生した場合にフォームの状態を維持するために、非表示の入力をレンダリングする React コンポーネントです。 + +```tsx +import { FormProvider, FormStateInput, useForm } from '@conform-to/react'; + +export default function SomeParent() { + const [form, fields] = useForm(); + + return ( + + + + ); +} +``` + +## プロパティ + +このコンポーネントはプロパティを受け入れません。 + +## Tips + +### 完全なプログレッシブエンハンスメントを求めている場合にのみ、これが必要です。 + +ドキュメントが再読み込みされると、フォームの状態の一部が失われます。例えば、 Conform は検証されたフィールドのエラーのみを表示しますが、新しいフィールドをリストに挿入するなど、サブミット以外の意図でフォームを送信している場合、この情報は失われます。 FormStateInput をレンダリングすることで、 Conform はフォームの状態を復元し、検証されたすべてのフィールドのエラーが引き続き表示されることを保証できます。 diff --git a/docs/ja/api/react/getCollectionProps.md b/docs/ja/api/react/getCollectionProps.md new file mode 100644 index 00000000..959f811b --- /dev/null +++ b/docs/ja/api/react/getCollectionProps.md @@ -0,0 +1,113 @@ +# getCollectionProps + +チェックボックスまたはラジオボタンのグループをアクセシブルにするために必要なすべてのプロパティを返すヘルパーです。 + +```tsx +const collectionProps = getCollectionProps(meta, options); +``` + +## 例 + +```tsx +import { useForm, getCollectionProps } from '@conform-to/react'; + +function Example() { + const [form, fields] = useForm(); + + return ( + <> + {getCollectionProps(fields.color, { + type: 'radio', + options: ['red', 'green', 'blue'], + }).map((props) => ( + + ))} + + ); +} +``` + +## オプション + +### `type` + +コレクションのタイプです。 **checkbox** （チェックボックス）または **radio** （ラジオボタン）のいずれかになります。 + +### `options` + +コレクションのオプションです。各オプションは入力の値として扱われ、対応する **key** または **id** を導出するために使用されます。 + +### `value` + +このヘルパーは、例えばコントロールされた入力のように、これが `false` に設定されていない限り、 **defaultValue** を返します。 + +### `ariaAttributes` + +結果のプロパティに `aria-invalid` と `aria-describedby` を含めるかどうかを決定します。デフォルトは **true** です。 + +### `ariaInvalid` + +ARIA 属性が `meta.errors` または `meta.allErrors` に基づくべきかどうかを決定します。デフォルトは **errors** です。 + +### `ariaDescribedBy` + +`aria-describedby` 属性に追加の **id** を付加します。フィールドメタデータから `meta.descriptionId` を渡すことができます。 + +## Tips + +### ヘルパーは任意です + +このヘルパーは、定型文を減らし、読みやすくするための便利な機能です。チェックボックス要素のプロパティを設定するために、いつでもフィールドメタデータを直接使用することができます。 + +```tsx +// Before +function Example() { + return ( + + {['a', 'b', 'c'].map((value) => ( + + ))} + x + + ); +} + +// After +function Example() { + return ( +
+ {getCollectionProps(fields.category, { + type: 'checkbox', + options: ['a', 'b', 'c'], + }).map((props) => ( + + ))} +
+ ); +} +``` + +### 自分のヘルパーを作る + +このヘルパーは、ネイティブのチェックボックス要素用に設計されています。カスタムコンポーネントを使用する必要がある場合は、自分自身のヘルパーを作成することができます。 diff --git a/docs/ja/api/react/getFieldsetProps.md b/docs/ja/api/react/getFieldsetProps.md new file mode 100644 index 00000000..0385ec93 --- /dev/null +++ b/docs/ja/api/react/getFieldsetProps.md @@ -0,0 +1,63 @@ +# getFieldsetProps + +フィールドセット要素をアクセシブルにするために必要なすべてのプロパティを返すヘルパーです。 + +```tsx +const props = getFieldsetProps(meta, options); +``` + +## 例 + +```tsx +import { useForm, getFieldsetProps } from '@conform-to/react'; + +function Example() { + const [form, fields] = useForm(); + + return
; +} +``` + +## オプション + +### `ariaAttributes` + +結果のプロパティに `aria-invalid` と `aria-describedby` を含めるかどうかを決定します。デフォルトは **true** です。 + +### `ariaInvalid` + +ARIA 属性が `meta.errors` または `meta.allErrors` に基づくべきかどうかを決定します。デフォルトは **errors** です。 + +### `ariaDescribedBy` + +`aria-describedby` 属性に追加の **id** を付加します。フィールドメタデータから `meta.descriptionId` を渡すことができます。 + +## Tips + +### ヘルパーは任意です + +このヘルパーは、定型文を減らし、読みやすくするための便利な機能です。入力要素のプロパティを設定するために、常にフィールドのメタデータを直接使用することもできます。 + +```tsx +// Before +function Example() { + return ( +
+ ); +} + +// After +function Example() { + return
; +} +``` + +### 自分のヘルパーを作る + +このヘルパーは、ネイティブの入力要素用に設計されています。カスタムコンポーネントを使用する必要がある場合は、自分自身のヘルパーを作成することができます。 diff --git a/docs/ja/api/react/getFormProps.md b/docs/ja/api/react/getFormProps.md new file mode 100644 index 00000000..70f5349f --- /dev/null +++ b/docs/ja/api/react/getFormProps.md @@ -0,0 +1,63 @@ +# getFormProps + +フォーム要素をアクセシブルにするために必要なすべてのプロパティを返すヘルパーです。 + +```tsx +const props = getFormProps(form, options); +``` + +## 例 + +```tsx +import { useForm, getFormProps } from '@conform-to/react'; + +function Example() { + const [form, fields] = useForm(); + + return
; +} +``` + +## オプション + +### `ariaAttributes` + +結果のプロパティに `aria-invalid` と `aria-describedby` を含めるかどうかを決定します。デフォルトは **true** です。 + +### `ariaInvalid` + +aria 属性が `meta.errors` または `meta.allErrors` に基づくべきかを決定します。デフォルトは **errors** です。 + +### `ariaDescribedBy` + +追加の **id** を `aria-describedby` 属性に追加します。フィールドのメタデータから `meta.descriptionId` を渡すことができます。 + +## Tips + +### ヘルパーは任意です + +ヘルパーは、定型文を減らし、読みやすくするための便利な関数にすぎません。フォーム要素のプロパティを設定するには、いつでもフォームのメタデータを直接使うことができます。 + +```tsx +// Before +function Example() { + return ( + + ); +} + +// After +function Example() { + return ; +} +``` + +### 自分のヘルパーを作る + +ヘルパーはネイティブのフォーム要素のために設計されています。カスタムコンポーネントを使う必要がある場合、いつでも独自のヘルパーを作ることができます。 diff --git a/docs/ja/api/react/getInputProps.md b/docs/ja/api/react/getInputProps.md new file mode 100644 index 00000000..d4321d5f --- /dev/null +++ b/docs/ja/api/react/getInputProps.md @@ -0,0 +1,111 @@ +# getInputProps + +入力要素をアクセシブルにするために必要なすべてのプロパティを返すヘルパーです。 + +```tsx +const props = getInputProps(meta, options); +``` + +## 例 + +```tsx +import { useForm, getInputProps } from '@conform-to/react'; + +function Example() { + const [form, fields] = useForm(); + + return ; +} +``` + +## オプション + +### `type` + +入力のタイプです。これは、 **defaultValue** （デフォルト値）または **defaultChecked** （デフォルトでチェックされている状態）が必要かどうかを判断するために使用されます。 + +### `value` + +これは主に、タイプが `checkbox` または `radio` の場合に入力の値を設定するために使用されます。しかし、 **defaultValue** や **defaultChecked** の状態の設定をスキップしたい場合、例えばコントロールされた入力の場合には、 `false` に設定することもできます。 + +### `ariaAttributes` + +結果のプロパティに `aria-invalid` と `aria-describedby` を含めるかどうかを決定します。デフォルトは **true** です。 + +### `ariaInvalid` + +ARIA 属性を `meta.errors` または `meta.allErrors` に基づいて設定するかどうかを決定します。デフォルトは **errors** です。 + +### `ariaDescribedBy` + +`aria-describedby` 属性に追加の **id** を追加します。フィールドのメタデータから `meta.descriptionId` を渡すことができます。 + +## Tips + +### ヘルパーは任意です + +このヘルパーは、定型文を減らし、読みやすくするための便利な機能です。入力要素のプロパティを設定するために、常にフィールドのメタデータを直接使用することもできます。 + +```tsx +// Before +function Example() { + return ( + + {/* text input */} + + {/* checkbox */} + +
+ ); +} + +// After +function Example() { + return ( +
+ {/* text input */} + + {/* checkbox */} + +
+ ); +} +``` + +### 自分のヘルパーを作る + +このヘルパーは、ネイティブの入力要素用に設計されています。カスタムコンポーネントを使用する必要がある場合は、自分自身のヘルパーを作成することができます。 diff --git a/docs/ja/api/react/getSelectProps.md b/docs/ja/api/react/getSelectProps.md new file mode 100644 index 00000000..c0468f87 --- /dev/null +++ b/docs/ja/api/react/getSelectProps.md @@ -0,0 +1,79 @@ +# getSelectProps + +セレクト要素をアクセシブルにするために必要なすべてのプロパティを返すヘルパーです。 + +```tsx +const props = getSelectProps(meta, options); +``` + +## 例 + +```tsx +import { useForm, getSelectProps } from '@conform-to/react'; + +function Example() { + const [form, fields] = useForm(); + + return + + ); +} + +// After +function Example() { + return ( +
+