diff --git a/website/src/content/pages/components/field.mdx b/website/src/content/pages/components/field.mdx index cc8747cb50..87a818b987 100644 --- a/website/src/content/pages/components/field.mdx +++ b/website/src/content/pages/components/field.mdx @@ -12,7 +12,9 @@ description: Provides a flexible container for form inputs, labels, and helper t ```tsx - + + + @@ -33,6 +35,48 @@ This example shows how to use the `Field` component with a standard input field. +### Disabled + +Set `disabled` on the root to disable the control and mark every part with `data-disabled`. + + + +### Invalid + +Set `invalid` to show the error text and mark the control with `aria-invalid`. The error text stays mounted and hidden +while the field is valid. + + + +### Indicator + +`Field.Indicator` is shown only when its `type` matches the field state: `required`, `invalid`, `valid` or `validating`. +Use it inside the label to show a required marker. + + + +### Validation + +The field validates the control natively, using attributes like `required` and `type="email"`. Set `validationMode` to +choose when results show (`onSubmit`, `onBlur` or `onChange`), and pass `match` to `Field.ErrorText` to show it only for +one native failure such as `valueMissing` or `typeMismatch`. + + + +### Custom Validation + +Pass `validate` to run your own rules. Return an error message, a list of messages, or nothing when the value is valid. +It can also return a promise. The messages are available as `errors` on the field context. + + + +### Server Errors + +Pass `errors` to show errors that come from outside the field, such as a server response. The field is invalid while +`errors` is not empty. + + + ### Textarea This example illustrates how to use the `Field` component with a textarea element. diff --git a/website/src/content/pages/components/fieldset.mdx b/website/src/content/pages/components/fieldset.mdx index dfb3bc48b3..fd3a964289 100644 --- a/website/src/content/pages/components/fieldset.mdx +++ b/website/src/content/pages/components/fieldset.mdx @@ -25,6 +25,18 @@ components natively support these contexts, you can also use the `Field` compone +### Disabled + +Set `disabled` on the fieldset to disable every field inside it, including fields that do not render a control. + + + +### Invalid + +Set `invalid` to show the fieldset error text alongside the errors of each field. + + + ### Field This example demonstrates how to use the `Field` component with a standard input field within a `Fieldset`. diff --git a/website/src/content/pages/overview/upgrade-guide.mdx b/website/src/content/pages/overview/upgrade-guide.mdx index 4eda9da39f..d057fd32c4 100644 --- a/website/src/content/pages/overview/upgrade-guide.mdx +++ b/website/src/content/pages/overview/upgrade-guide.mdx @@ -259,6 +259,29 @@ the part being a block, a rotating accordion indicator for example, give it an e In React, refs to these parts are now typed `HTMLSpanElement`. +### Field and Fieldset use the Zag machines + +`Field` and `Fieldset` are now built on `@zag-js/field` and `@zag-js/fieldset`. Fields validate +natively and with `validate`, show results by `validationMode`, and accept server `errors`. Most +usage keeps working; these changes need a look: + +- `Field.RequiredIndicator` is replaced by `Field.Indicator`, which takes a `type`. +- The `input`, `textarea` and `select` parts are renamed to `control`, and `required-indicator` to + `indicator`. Update selectors from `[data-field-input]` to `[data-field-control]` and from + `[data-field-required-indicator]` to `[data-field-indicator]`. +- Generated ids are now `{id}:label` and `{id}:control`. Update any code that reads them. +- `Field.ErrorText` stays mounted and hidden while the field is valid, so style it with `[hidden]` + rather than relying on it being removed. +- `Field.Root` no longer sets `role="group"`. + +```diff + + Email +- * ++ * + +``` + ### `TagsInput` is no longer editable by default Tags no longer open for editing on double-click unless you pass `editable`. The diff --git a/website/src/lib/example-registry.ts b/website/src/lib/example-registry.ts index f81debb856..992adf2cfd 100644 --- a/website/src/lib/example-registry.ts +++ b/website/src/lib/example-registry.ts @@ -391,6 +391,7 @@ const exampleModules: Record Promise> = { 'number-flow/root-provider': () => import('@examples/number-flow/examples/root-provider'), 'number-flow/timing': () => import('@examples/number-flow/examples/timing'), 'number-flow/trend': () => import('@examples/number-flow/examples/trend'), + 'number-flow/with-timer': () => import('@examples/number-flow/examples/with-timer'), 'number-input/basic': () => import('@examples/number-input/examples/basic'), 'number-input/context': () => import('@examples/number-input/examples/context'), 'number-input/formatting': () => import('@examples/number-input/examples/formatting'),