Update and Add form package docs (#228)

* update FormField doc * update FormSubmit doc * Add new FormSwitch doc * update useTextInput doc
FormidableLabs · Aug 7, 2024 · 128f514 · 128f514
1 parent a45d61a
commit 128f514
Show file tree

Hide file tree

Showing 4 changed files with 84 additions and 38 deletions.
diff --git a/packages/forms/docs/FormField.md b/packages/forms/docs/FormField.md
@@ -7,32 +7,36 @@ This is a generic form field element capable of receiving focus from a [TextInpu
 ## Example
 
 ```jsx
-import { Form } from 'react-native-ama';
-
-<Form.Field id="field-id">
-  <Pressable
-    accessibilityRole="switch"
-    accessibilityLabel={accessibilityLabel}
-    style={[styles.container, style]}
-    onPress={onValueChange}
-    checked={value}>
-    {isLabelPositionLeft ? label : null}
-    {children ? (
-      children
-    ) : (
-      <Switch
-        {...rest}
+import { Form } from '@react-native-ama/forms';
+
+const ExampleFormField = () => {
+  return (
+    <Form.Field id="field-id">
+      <Pressable
+        accessibilityRole="switch"
         accessibilityLabel={accessibilityLabel}
-        style={switchStyle}
-        value={value}
-        onValueChange={onValueChange}
-        accessibilityElementsHidden={true}
-        importantForAccessibility="no"
-      />
-    )}
-    {isLabelPositionLeft ? null : label}
-  </Pressable>
-</Form.Field>
+        style={[styles.container, style]}
+        onPress={onValueChange}
+        checked={value}>
+        {isLabelPositionLeft ? label : null}
+        {children ? (
+          children
+        ) : (
+          <Switch
+            {...rest}
+            accessibilityLabel={accessibilityLabel}
+            style={switchStyle}
+            value={value}
+            onValueChange={onValueChange}
+            accessibilityElementsHidden={true}
+            importantForAccessibility="no"
+          />
+        )}
+        {isLabelPositionLeft ? null : label}
+      </Pressable>
+    </Form.Field>
+  );
+};
 ```
 
 ## Props
@@ -67,6 +71,16 @@ If true the field is marked as possible candidate to be automatically focused wh
 
 The error to be announced as part of the accessibility hint when the validation fails.
 
+### `wrapInsideAccessibleView`
+
+Form Fields are wrapped inside an accessible\* view by default, to disable this pass false to `wrapInsideAccessibleView`.
+
+| Type    | Default |
+| ------- | ------- |
+| boolean | true    |
+
+> *accessible: *When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.\*
+
 ## Related guidelines
 
 - [Forms](../guidelines/forms)
diff --git a/packages/forms/docs/FormSubmit.md b/packages/forms/docs/FormSubmit.md
@@ -1,6 +1,6 @@
 import { Required } from '@site/src/components';
 
-# Form.Submit
+# Form.Submit (FormSubmit)
 
 This is a [Pressable](./Pressable) wrapper for the form Submit button.
 The component triggers the [Form onSubmit](./Form#-onsubmit) callback and therefore focuses on the first invalid field
@@ -9,15 +9,11 @@ if the submission fails.
 ## Usage
 
 ```jsx
-import { Form } from 'react-native-ama';
-
-<Form.Submit
-    accessibilityLabel="Submit"
-    onPress={onSubmit}
-    busy={isBusy}
->
-    <Text>Submit</Text>
-</Form.Submit>
+import { Form } from '@react-native-ama/forms';
+
+<Form.Submit accessibilityLabel="Submit" onPress={onSubmit} busy={isBusy}>
+  <Text>Submit</Text>
+</Form.Submit>;
 ```
 
 :::note
@@ -39,4 +35,3 @@ This parameter is passed to the accessibilityState busy.
 ## Related guidelines
 
 - [Forms](../guidelines/forms)
-
diff --git a/packages/forms/docs/FormSwitch.md b/packages/forms/docs/FormSwitch.md
@@ -0,0 +1,22 @@
+# Form.Switch (FormSwitch)
+
+Provides Switch functionality to be used in Forms, it is simply a compound component of the wrapper [FormField](./FormField.md) and controller [SwitchListItem](../../react-native/docs/SwitchListItem.md) combined for easy of use so you don't need to roll your own.
+
+## Usage
+
+```jsx {1-3, 8}
+import { Form, FormSwitch } from '@react-native-ama/forms';
+
+<Form onSubmit={handleSubmit} ref={ref}>
+  <FormSwitch
+    label={<Text style={styles.switchText}>I'm a switch</Text>}
+    style={styles.switchListItem}
+    value={isSwitchOn}
+    onValueChange={toggleSwitch}
+  />
+</Form>;
+```
+
+## Props
+
+FormSwitch accepts all [SwitchListItem](../../react-native/docs/SwitchListItem.mdx#Props) Props
diff --git a/packages/forms/docs/useTextInput.md b/packages/forms/docs/useTextInput.md
@@ -10,16 +10,31 @@ To use `useTextInput` it must be wrapped by the `<Form>` provider component from
 ## Usage
 
 ```jsx
-// MyTextInput
 import { useTextInput } from '@react-native-ama/forms';
 
-const MyTextInput = () => {
+const FormTextInput = () => {
   const { ref, ...rest } = useTextInput({ ...requiredProps });
 
   return <TextInput ref={ref} {...rest} />;
 };
 ```
 
+Form TextInputs must be wrapped by a [Form Provider](./Form.md#usage)
+
+```jsx
+import { Form } from '@react-native-ama/forms';
+
+import { MyTextInput } from './MyTextInput';
+
+const CustomForm = () => {
+  return (
+    <Form onSubmit={handleSubmit} ref={ref}>
+      <FormTextInput {...props} />
+    </Form>
+  );
+};
+```
+
 ## Accessibility improvements
 
 Compared to the default React Native component, this custom component: