@cdx-ui/components 0.2.3 → 0.2.4

package/docs/components/field/content.md

@@ -0,0 +1,277 @@
+# Field (https://design.candescent.com/docs/components/field)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-field--default)
+
+A compound component that supplies accessible labels, descriptions, validation messages, and state to a nested form control.
+
+```tsx
+import { Field } from '@cdx-ui/components';
+```
+
+Wrap related fields in `Form`, then place the interactive control between `Field.Label` and the supporting or validation text. Compatible controls such as `Input` consume the field state and accessibility context automatically.
+
+## Basic
+
+```tsx
+import { Field, Form, Input } from '@cdx-ui/components';
+
+export default function FieldBasicDemo() {
+  return (
+    <Form className="w-full max-w-sm">
+      <Field name="email" isRequired>
+        <Field.Label>Email address</Field.Label>
+        <Input>
+          <Input.Field
+            autoCapitalize="none"
+            autoComplete="email"
+            keyboardType="email-address"
+            placeholder="you@example.com"
+          />
+        </Input>
+        <Field.Helper>We will only use this for account notifications.</Field.Helper>
+      </Field>
+    </Form>
+  );
+}
+```
+
+## States
+
+Set `isRequired`, `isInvalid`, `isDisabled`, or `isReadOnly` on `Field`. Nested Forge UI controls inherit those states through context. `Field.Helper` is hidden while the field is invalid, and `Field.Error` is only rendered when the field is invalid and has a message.
+
+```tsx
+import { Field, Form, Input, Text, VStack } from '@cdx-ui/components';
+
+export default function FieldStatesDemo() {
+  return (
+    <Form className="w-full max-w-sm">
+      <VStack space="lg">
+        <Field name="required-example" isRequired>
+          <Field.Label>Required</Field.Label>
+          <Input>
+            <Input.Field placeholder="Required value" />
+          </Input>
+          <Field.Helper>The required indicator is announced with the label.</Field.Helper>
+        </Field>
+
+        <Field name="disabled-example" isDisabled>
+          <Field.Label>Disabled</Field.Label>
+          <Input>
+            <Input.Field defaultValue="Unavailable value" />
+          </Input>
+          <Field.Helper>This control cannot be edited.</Field.Helper>
+        </Field>
+
+        <Field name="read-only-example" isReadOnly>
+          <Field.Label>Read-only</Field.Label>
+          <Input>
+            <Input.Field defaultValue="Account ending in 1234" />
+          </Input>
+          <Field.Helper>This value can be selected but not changed.</Field.Helper>
+        </Field>
+
+        <Field name="invalid-example" isInvalid isRequired>
+          <Field.Label>Invalid</Field.Label>
+          <Input>
+            <Input.Field defaultValue="not-an-email" keyboardType="email-address" />
+          </Input>
+          <Field.Helper>This helper is hidden while the field is invalid.</Field.Helper>
+          <Field.Error>Enter a valid email address.</Field.Error>
+        </Field>
+
+        <Text size="sm" color="secondary">
+          Field state is shared with each nested control through context.
+        </Text>
+      </VStack>
+    </Form>
+  );
+}
+```
+
+## With other form controls
+
+Explore how other Forge UI form controls compose with `Field` for labels, supporting text, and validation state.
+
+## React Hook Form
+
+Use `Controller` to connect controlled Forge UI inputs to React Hook Form. Pass `fieldState.invalid` to `Field`, render the validation message with `Field.Error`, and forward the controller handlers and ref to the nested input.
+
+```tsx
+import { useState } from 'react';
+import { Controller, useForm } from 'react-hook-form';
+import { Button, Field, Form, Input, Text, VStack } from '@cdx-ui/components';
+
+interface SignInValues {
+  email: string;
+  password: string;
+}
+
+export default function FieldReactHookFormDemo() {
+  const [submitted, setSubmitted] = useState<SignInValues | null>(null);
+  const {
+    control,
+    handleSubmit,
+    formState: { errors },
+  } = useForm<SignInValues>({
+    defaultValues: {
+      email: '',
+      password: '',
+    },
+  });
+
+  const submit = handleSubmit(
+    (values) => setSubmitted(values),
+    () => setSubmitted(null),
+  );
+
+  return (
+    <Form
+      className="w-full max-w-sm"
+      onSubmit={(event) => {
+        event.preventDefault();
+        void submit();
+      }}
+    >
+      <VStack space="lg">
+        <Controller
+          control={control}
+          name="email"
+          rules={{
+            required: 'Email address is required.',
+            pattern: {
+              value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+              message: 'Enter a valid email address.',
+            },
+          }}
+          render={({ field: { onBlur, onChange, ref, value }, fieldState: { invalid } }) => (
+            <Field name="email" isInvalid={invalid} isRequired>
+              <Field.Label>Email address</Field.Label>
+              <Input>
+                <Input.Field
+                  ref={ref}
+                  autoCapitalize="none"
+                  autoComplete="email"
+                  keyboardType="email-address"
+                  placeholder="you@example.com"
+                  value={value}
+                  onBlur={onBlur}
+                  onChangeText={onChange}
+                />
+              </Input>
+              <Field.Helper>Use the email associated with your account.</Field.Helper>
+              <Field.Error>{errors.email?.message}</Field.Error>
+            </Field>
+          )}
+        />
+
+        <Controller
+          control={control}
+          name="password"
+          rules={{
+            required: 'Password is required.',
+            minLength: {
+              value: 8,
+              message: 'Password must contain at least 8 characters.',
+            },
+          }}
+          render={({ field: { onBlur, onChange, ref, value }, fieldState: { invalid } }) => (
+            <Field name="password" isInvalid={invalid} isRequired>
+              <Field.Label>Password</Field.Label>
+              <Input>
+                <Input.Field
+                  ref={ref}
+                  autoComplete="current-password"
+                  placeholder="At least 8 characters"
+                  secureTextEntry
+                  value={value}
+                  onBlur={onBlur}
+                  onChangeText={onChange}
+                />
+              </Input>
+              <Field.Error>{errors.password?.message}</Field.Error>
+            </Field>
+          )}
+        />
+
+        <Button fullWidth onPress={() => void submit()}>
+          <Button.Label>Sign in</Button.Label>
+        </Button>
+
+        {submitted ? (
+          <Text accessibilityRole="alert" color="success">
+            Form submitted for {submitted.email}.
+          </Text>
+        ) : null}
+      </VStack>
+    </Form>
+  );
+}
+```
+
+## API
+
+### Field
+
+Provides field-level state and generated IDs to its label, control, helper text, and error message. The `name` is passed through context to compatible controls for form submission.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `name?` | `string` | — | Field name for form submission. Passed through context so child inputs automatically receive it as their `name` attribute for `FormData` support. |
+| `isInvalid?` | `boolean` | — | If true, the field is marked as invalid. Controls error visibility. |
+| `isRequired?` | `boolean` | — | If true, the field is marked as required. Shows asterisk on label. |
+| `isDisabled?` | `boolean` | — | If true, the field is disabled. Nested controls that read field context are disabled as well. |
+| `isReadOnly?` | `boolean` | — | If true, the field is read-only. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props). `Field` can be used on its own for a single control or inside `Form` for form-level semantics.
+
+## Sub-components
+
+### Field.Label
+
+Labels the nested control. Required fields receive a visible required indicator. On web, the label is associated through `htmlFor`; on native, pressing the label focuses the control registered with the field.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `htmlFor?` | `string` | — | Associates the label with a control `id` on web (`<label htmlFor>`). If omitted, defaults to the same id `Input.Field` gets from form context: `fieldId + "-input"`. |
+| `requiredIndicator?` | `ReactNode` | — | Element to render after the label text when the field is required. Rendered by the primitive (which owns the form-control context) so the styled layer never needs to read `FormControlContext` across packages. |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Field.Helper
+
+Displays supporting text and connects it to the nested control's accessible description. It does not render while `Field` is invalid, allowing the validation message to replace it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Field.Error
+
+Displays a validation icon and message when `Field` is invalid. The error is exposed as an assertive live-region alert and connected to the nested control's accessible description.
+
+Controls that validate themselves, such as `DatePicker` with `minValue`, `maxValue`, or `isDateUnavailable`, mark the whole `Field` invalid and supply a message; a `Field.Error` with no children renders that message.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Error message. When omitted (or `null`), falls back to the message the field's control reports — for example `DatePicker`'s localized `minValue` / `maxValue` / `isDateUnavailable` message. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Accessibility
+
+- Use one `Field.Label` for each field so the control has an accessible name.
+- Put instructions in `Field.Helper` and validation feedback in `Field.Error`; Field manages the generated IDs and description relationships.
+- Set `isRequired` and `isInvalid` from application or form-library state. Field communicates those states but does not run validation itself.
+- Put `autoFocus` on the nested control, not on `Field`.

package/docs/components/form/content.md

@@ -0,0 +1,62 @@
+# Form (https://design.candescent.com/docs/components/form)
+
+`Form` groups fields with consistent vertical spacing. Labels, helper text, and validation belong on [`Field`](https://design.candescent.com/docs/components/field/content.md).
+
+```tsx
+import { Form } from '@cdx-ui/components';
+```
+
+## Basic
+
+Place fields and a submit button inside `Form`.
+
+On web, `Form` renders a `<form>`. Handle submission with `onSubmit`, or call `requestSubmit()` on a ref to the form from a button press. On iOS and Android, `onSubmit`, `action`, and `method` are ignored; validate and submit from the button's press handler.
+
+```tsx
+import { Button, Field, Form, Input } from '@cdx-ui/components';
+
+export default function FormBasicDemo() {
+  return (
+    <Form className="w-full max-w-sm">
+      <Field name="email" isRequired>
+        <Field.Label>Email</Field.Label>
+        <Input>
+          <Input.Field
+            autoCapitalize="none"
+            autoComplete="email"
+            keyboardType="email-address"
+            placeholder="you@example.com"
+          />
+        </Input>
+        <Field.Helper>We will never share your email.</Field.Helper>
+      </Field>
+      <Button>
+        <Button.Label>Submit</Button.Label>
+      </Button>
+    </Form>
+  );
+}
+```
+
+## API
+
+### Form
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `onSubmit?` | `((e: React.SyntheticEvent) => void)` | — | Called when the form is submitted. Web only; ignored on native. |
+| `action?` | `string \| ((formData: FormData) => void \| Promise<void>)` | — | HTML `action` URL, or a function that receives the submitted `FormData`. Web only; ignored on native. |
+| `method?` | `string` | — | HTTP method. Web only; ignored on native. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props). On web the root is a `<form>` element. On native it is a `View`, and `onSubmit`, `action`, and `method` are ignored.
+
+| Attribute   | Values | Description  |
+| ----------- | ------ | ------------ |
+| `data-slot` | `form` | Root element |
+
+## Accessibility
+
+On web, the `<form>` element is exposed as a form landmark. On iOS and Android, `Form` renders a `View` with no role. Accessible names, descriptions, and validation messages come from `Field`.