API Reference pages in docs

README.md

@@ -11,7 +11,7 @@
 </p>
 
 <p align="center">
-    <strong><a href="https://uniforms.tools/docs/api-forms">API</a></strong> |
+    <strong><a href="https://uniforms.tools/docs/api-reference/forms">API</a></strong> |
     <strong><a href="https://github.com/vazco/uniforms/blob/master/.github/CONTRIBUTING.md">Contribute</a></strong> |
     <strong><a href="https://uniforms.tools/docs/tutorials-basic-uniforms-usage">Quick Start</a></strong> |
     <strong><a href="https://vazco.github.io/uniforms/playground">Playground</a></strong> |

website/docs/api-reference/_category_.json

@@ -0,0 +1,5 @@
+{
+  "position": 4,
+  "label": "API Reference",
+  "collapsible": false
+}

website/docs/api-reference/bridges.mdx

@@ -0,0 +1,167 @@
+---
+id: bridges
+title: 'Bridges'
+sidebar_position: 3
+---
+
+To make use of any schema, uniforms have to create a _bridge_ of it - a unified schema mapper.
+
+<p align="center">
+  <img src="/img/bridge-concept.svg" alt="" />
+</p>
+
+Currently available bridges:
+
+- `JSONSchemaBridge` in `uniforms-bridge-json-schema` ([schema documentation](https://json-schema.org/))
+- `SimpleSchema2Bridge` in `uniforms-bridge-simple-schema-2` ([schema documentation](https://github.com/longshotlabs/simpl-schema#readme))
+- `ZodBridge` in `uniforms-bridge-zod` ([schema documentation](https://zod.dev/))
+
+Deprecated bridges:
+
+- `SimpleSchemaBridge` in `uniforms-bridge-simple-schema` ([schema documentation](https://github.com/Meteor-Community-Packages/meteor-simple-schema/blob/master/DOCS.md))
+- `GraphQLBridge` in `uniforms-bridge-graphql` ([schema documentation](https://graphql.org/))
+
+If you see a lot of [`Warning: Unknown props...`](https://fb.me/react-unknown-prop) logs, check if your schema or theme doesn't provide extra props. If so, consider [registering it with `filterDOMProps`](/docs/api-reference/helpers#filterdomprops).
+
+## `JSONSchemaBridge`
+
+```tsx
+import Ajv from 'ajv';
+import { JSONSchemaBridge } from 'uniforms-bridge-json-schema';
+
+const ajv = new Ajv({ allErrors: true, useDefaults: true });
+
+const schema = {
+  title: 'Person',
+  type: 'object',
+  properties: {
+    firstName: { type: 'string' },
+    lastName: { type: 'string' },
+    age: {
+      description: 'Age in years',
+      type: 'integer',
+      minimum: 0,
+    },
+  },
+  required: ['firstName', 'lastName'],
+};
+
+function createValidator(schema: object) {
+  const validator = ajv.compile(schema);
+
+  return (model: object) => {
+    validator(model);
+    return validator.errors?.length ? { details: validator.errors } : null;
+  };
+}
+
+const validator = createValidator(schema);
+
+const bridge = new JSONSchemaBridge({ schema, validator });
+```
+
+### Note on `allOf`/`anyOf`/`oneOf`
+
+The current handling of `allOf`/`anyOf`/`oneOf` is not complete and does not work with all possible cases. For an in-detail discussion, see [\#863](https://github.com/vazco/uniforms/issues/863). How it works, is that only a few properties are being used:
+
+- `properties`, where all subfields are merged (last definition wins),
+- `required`, where all properties are accumulated, and
+- `type`, where the first one is being used.
+
+Below is an example of these implications:
+
+```ts
+{
+  "type": "object",
+  "properties": {
+    // This will render `NumField` WITHOUT `min` nor `max` properties.
+    // It will be properly validated, but without any UI guidelines.
+    "foo": {
+      "type": "number",
+      "allOf": [{ "minimum": 0 }, { "maximum": 10 }]
+    },
+    // This will render as `TextField`.
+    "bar": {
+      "oneOf": [{ "type": "string" }, { "type": "number" }]
+    }
+  }
+}
+```
+
+### Note on Bluebird
+
+If you're using the [`bluebird`](https://www.npmjs.com/package/bluebird) package, you may have seen the following warning ([docs](http://bluebirdjs.com/docs/warning-explanations.html#warning-a-promise-was-rejected-with-a-non-error)):
+
+> Warning: a promise was rejected with a non-error [object Object]
+
+There could be multiple causes of this error. One of it is not returning a proper error object.
+
+In order to fix it, your `validator` function should return a `Error`-like object instead of an object with a single `details` property. The cleanest would be to create a custom `ValidationError` class:
+
+```ts
+import { ErrorObject } from 'ajv';
+
+class ValidationError extends Error {
+  name = 'ValidationError';
+
+  constructor(public details: ErrorObject[]) {
+    super('ValidationError');
+  }
+}
+
+// Usage.
+return validator.errors?.length ? new ValidationError(validator.errors) : null;
+```
+
+Another cause of this error may be two different implementations of the `Promise` object when using an asynchronous validate function.
+Ensure that you are returning the same `Promise` object implementation that Bluebird is expecting.
+The simplest way to do that should be to avoid using the `async` keyword and instead make the function return a `Promise` instead.
+
+See [#1047](https://github.com/vazco/uniforms/discussions/1047) for more details.
+
+## `SimpleSchema2Bridge`
+
+```tsx
+import SimpleSchema from 'simpl-schema';
+import SimpleSchema2Bridge from 'uniforms-bridge-simple-schema-2';
+
+const schema = new SimpleSchema({
+  // ...
+
+  aboutMe: {
+    type: String,
+    uniforms: MyText, // Component...
+    uniforms: {
+      // ...or object...
+      component: MyText, // ...with component...
+      propA: 1, // ...and/or extra props.
+    },
+  },
+});
+
+const bridge = new SimpleSchema2Bridge({ schema });
+```
+
+## `ZodBridge`
+
+```tsx
+import ZodBridge from 'uniforms-bridge-zod';
+import z from 'zod';
+
+const schema = z.object({ aboutMe: z.string() });
+
+const bridge = new ZodBridge({ schema });
+```
+
+```
+
+## `ZodBridge`
+
+```tsx
+import ZodBridge from 'uniforms-bridge-zod';
+import z from 'zod';
+
+const schema = z.object({ aboutMe: z.string() });
+
+const bridge = new ZodBridge({ schema });
+```

website/docs/api-reference/context-data.mdx

@@ -0,0 +1,132 @@
+---
+id: context-data
+title: 'Context data'
+sidebar_position: 4
+---
+
+Some components might need to know a current form state, which is passed as [React context](https://reactjs.org/docs/context.html).
+Properties stored in the context relates either to the form values or the form instance itself.
+That means, besides current form state, you can access form methods or encounter some metadata, e.g. about the used schema.
+Some of them were designed for internal use, but you can still take advantage of them.
+
+## Accessing context data
+
+A direct way of accessing the context data is to use the [`useForm`](/docs/api-reference/helpers#useform) hook:
+
+```tsx
+import { useForm } from 'uniforms';
+
+function Example() {
+  const context = useForm();
+}
+```
+
+For convenience, it's also accessible through the [`useField`](/docs/api-reference/helpers#usefield) hook:
+
+```tsx
+import { useField } from 'uniforms';
+
+function Example(rawProps) {
+  const [props, context] = useField(rawProps.name, rawProps);
+}
+```
+
+## Available context data
+
+### `changed`
+
+Indicates whether there was a change on form.
+
+### `changedMap`
+
+A map of changed fields. Rather internal one, used for checking if _other_ fields has changed.
+
+### `error`
+
+An object with a `details` field, which is an array of any validation errors.
+
+### `formRef`
+
+Contains reference to the form component that gives access to [the form methods](/docs/api-reference/forms#methods).
+
+### `model`
+
+An object with current form fields values structured `{field: value}`.
+
+### `name`
+
+It is an array of the parent fields names:
+
+```tsx
+<Field name="x">
+  // name = []
+  <Field name="y.z">
+    // name = ['x']
+    <Field name="a" /> // name = ['x', 'y', 'z']
+  </Field>
+</Field>
+```
+
+For example if we define a `CompositeField`:
+
+```tsx
+const Composite = () => (
+  <section>
+    <AutoField name="firstName" />
+    <AutoField name="lastName" />
+  </section>
+);
+```
+
+And use it like that:
+
+```tsx
+<AutoForm schema={schema}>
+  <CompositeField name="personA" />
+  <SubmitField />
+</AutoForm>
+```
+
+The `name` array of the nested `AutoFields` will store a `personA` value.
+
+### `onChange`
+
+You can directly access to the `onChange` method. E.g. `onChange(field, value)`.
+
+### `onSubmit`
+
+Access to `onSubmit` method.
+
+### `randomId`
+
+Access to `randomId` method, created using the [`randomIds()`](/docs/api-reference/helpers#randomids) helper.
+
+### `schema`
+
+A bridge class instance with `schema` and `validator` properties.
+
+The `schema` is simply your schema object and `validator` is your validating function.
+
+### `state`
+
+The `state` is an object representing your current form status.
+
+The state properties are:
+
+|       Name        |                     Description                      |
+| :---------------: | :--------------------------------------------------: |
+|    `disabled`     |       Indicates whether the form is disabled.        |
+|    `readOnly`     |       Indicates whether the form is read-only.       |
+| `showInlineError` | Indicates whether the inline errors should be shown. |
+
+### `submitted`
+
+Indicates whether the form was submitted.
+
+### `submitting`
+
+Indicates whether the form is in the `submitting` state. Helpful when handling asynchronous submission.
+
+### `validating`
+
+Indicates whether the form is in the `validating` state. Helpful when handling asynchronous validation.