Skip to content

Commit

Permalink
Merge branch 'master' into deprecate-bridge-simple-schema
Browse files Browse the repository at this point in the history
  • Loading branch information
piotrpospiech committed May 24, 2024
2 parents 01705a6 + 1436d4c commit ee87287
Show file tree
Hide file tree
Showing 25 changed files with 263 additions and 948 deletions.
5 changes: 0 additions & 5 deletions .github/labeler.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
'Area: Bridge':
- changed-files:
- any-glob-to-any-file:
- packages/uniforms-bridge-graphql/**/*
- packages/uniforms-bridge-json-schema/**/*
- packages/uniforms-bridge-simple-schema-2/**/*
- packages/uniforms-bridge-zod/**/*
Expand Down Expand Up @@ -49,10 +48,6 @@
- packages/uniforms-mui/**/*
- packages/uniforms-semantic/**/*
- packages/uniforms-unstyled/**/*
'Bridge: GraphQL':
- changed-files:
- any-glob-to-any-file:
- packages/uniforms-bridge-graphql/**/*
'Bridge: JSON Schema':
- changed-files:
- any-glob-to-any-file:
Expand Down
1 change: 0 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,6 @@
- **Inline and asynchronous form validation**
- **Integrations with various schemas:**
- **[JSON Schema](http://json-schema.org/)**
- **[GraphQL](https://github.com/graphql/graphql-js)**
- **[SimpleSchema@2](https://github.com/aldeed/node-simple-schema)**
- **[Zod](https://github.com/colinhacks/zod)**
- **And any other - only [a small wrapper](https://vazco.github.io/uniforms/#/introduction) is needed!**
Expand Down
195 changes: 106 additions & 89 deletions docs/api-bridges.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,105 +11,17 @@ To make use of any schema, uniforms have to create a _bridge_ of it - a unified

Currently available bridges:

- `GraphQLBridge` in `uniforms-bridge-graphql` ([schema documentation](https://graphql.org/))
- `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-helpers#filterdomprops).

## `GraphQLBridge`

This bridge enables using GraphQL schema types as uniforms forms.
This saves you from not having to rewrite the form schema in your code.
As a trade-off, you have to write the validator from scratch. In some cases, it might be easier to rewrite the schema and use, for example, [`JSONSchemaBridge` with `ajv`](/docs/api-bridges#jsonschemabridge).
If only a simple or no validation is needed, this bridge is perfectly suited to work with GraphQL schemas.

The constructor accepts these arguments:

- `schema: GraphQLType` can be any type parsed and extracted from a GraphQL schema.
- `validator: (model: Record<string, unknown>) => any` a custom validator function that should return a falsy value if no errors are present or information about errors in the model as described in the [custom bridge section](/docs/examples-custom-bridge#validator-definition).
- `extras: Record<string, unknown> = {}` used to extend the schema generated from GraphQL type with extra field configuration.
- `provideDefaultLabelFromFieldName = true` if set to `true`, the bridge will use the field name as a label if no label is provided in the schema.

### Code example

```tsx
import { GraphQLBridge } from 'uniforms-bridge-graphql';
import { buildASTSchema, parse } from 'graphql';

const schema = `
type Author {
id: String!
firstName: String
lastName: String
}
type Post {
id: Int!
author: Author!
title: String
votes: Int
}
# This is required by buildASTSchema
type Query { anything: ID }
`;

const schemaType = buildASTSchema(parse(schema)).getType('Post');
const schemaExtras = {
id: {
options: [
{ label: 1, value: 1 },
{ label: 2, value: 2 },
{ label: 3, value: 3 },
],
},
title: {
options: [
{ label: 1, value: 'a' },
{ label: 2, value: 'b' },
],
},
'author.firstName': {
placeholder: 'John',
},
};

const schemaValidator = (model: object) => {
const details = [];

if (!model.id) {
details.push({ name: 'id', message: 'ID is required!' });
}

if (!model.author.id) {
details.push({ name: 'author.id', message: 'Author ID is required!' });
}

if (model.votes < 0) {
details.push({
name: 'votes',
message: 'Votes must be a non-negative number!',
});
}

// ...

return details.length ? { details } : null;
};

const bridge = new GraphQLBridge({
schema: schemaType,
validator: schemaValidator,
extras: schemaExtras,
});
```

## `JSONSchemaBridge`

```tsx
Expand Down Expand Up @@ -268,3 +180,108 @@ const schema = new SimpleSchema({

const bridge = new SimpleSchemaBridge({ 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 });
```

## `GraphQLBridge`

:::caution

GraphQLBridge is deprecated since uniforms v4.

:::

This bridge enables using GraphQL schema types as uniforms forms.
This saves you from not having to rewrite the form schema in your code.
As a trade-off, you have to write the validator from scratch. In some cases, it might be easier to rewrite the schema and use, for example, [`JSONSchemaBridge` with `ajv`](/docs/api-bridges#jsonschemabridge).
If only a simple or no validation is needed, this bridge is perfectly suited to work with GraphQL schemas.

The constructor accepts these arguments:

- `schema: GraphQLType` can be any type parsed and extracted from a GraphQL schema.
- `validator: (model: Record<string, unknown>) => any` a custom validator function that should return a falsy value if no errors are present or information about errors in the model as described in the [custom bridge section](/docs/examples-custom-bridge#validator-definition).
- `extras: Record<string, unknown> = {}` used to extend the schema generated from GraphQL type with extra field configuration.
- `provideDefaultLabelFromFieldName = true` if set to `true`, the bridge will use the field name as a label if no label is provided in the schema.

### Code example

```tsx
import { GraphQLBridge } from 'uniforms-bridge-graphql';
import { buildASTSchema, parse } from 'graphql';

const schema = `
type Author {
id: String!
firstName: String
lastName: String
}
type Post {
id: Int!
author: Author!
title: String
votes: Int
}
# This is required by buildASTSchema
type Query { anything: ID }
`;

const schemaType = buildASTSchema(parse(schema)).getType('Post');
const schemaExtras = {
id: {
options: [
{ label: 1, value: 1 },
{ label: 2, value: 2 },
{ label: 3, value: 3 },
],
},
title: {
options: [
{ label: 1, value: 'a' },
{ label: 2, value: 'b' },
],
},
'author.firstName': {
placeholder: 'John',
},
};

const schemaValidator = (model: object) => {
const details = [];

if (!model.id) {
details.push({ name: 'id', message: 'ID is required!' });
}

if (!model.author.id) {
details.push({ name: 'author.id', message: 'Author ID is required!' });
}

if (model.votes < 0) {
details.push({
name: 'votes',
message: 'Votes must be a non-negative number!',
});
}

// ...

return details.length ? { details } : null;
};

const bridge = new GraphQLBridge({
schema: schemaType,
validator: schemaValidator,
extras: schemaExtras,
});
```
1 change: 0 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,6 @@
"eslint-config-vazco": "6.2.0",
"eslint-import-resolver-alias": "1.1.2",
"eslint-import-resolver-typescript": "2.3.0",
"graphql": "^15.0.0",
"husky": "8.0.1",
"invariant": "^2.0.0",
"jest": "27.0.6",
Expand Down
11 changes: 0 additions & 11 deletions packages/uniforms-bridge-graphql/README.md

This file was deleted.

Loading

0 comments on commit ee87287

Please sign in to comment.