Skip to content

Commit

Permalink
docs: update readme (#106)
Browse files Browse the repository at this point in the history 
* update readme

* remove lorem ipsum from storybook
  • Loading branch information
@DrewHoo
DrewHoo authored Dec 30, 2024
1 parent fadef43 commit 4154bf0
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 185 deletions.
84 changes: 21 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,12 @@
# Ant Design Renderers for `jsonforms`

[jsonforms](jsonforms.io) is "a declarative framework for efficiently building form-based web UIs." `jsonforms` has multiple renderer packages for different frameworks and component libraries, and this is one such package.

## Storybook

This package includes a storybook to help you see the different renderers in action. To run the storybook:

```bash
$ pnpm storybook
```

To view the published storybook, visit [https://great-expectations.github.io/jsonforms-antd-renderers/](https://great-expectations.github.io/jsonforms-antd-renderers/)
You can preview the renderers via storybook [here](https://great-expectations.github.io/jsonforms-antd-renderers/).

## Getting started

```bash
$ npm install @great-expectations/jsonforms-antd-renderers
npm install @great-expectations/jsonforms-antd-renderers
```

### Using AntD Renderers
Expand All @@ -31,9 +22,10 @@ import {
cellRegistryEntries,
} from "@great-expectations/jsonforms-antd-renderers"

function MyForm() {
function MyForm({ data }: { data: Record<string, unknown> }) {
return (
<JsonForms
data={data}
schema={schema}
renderers={rendererRegistryEntries}
cells={cellRegistryEntries}
Expand All @@ -47,85 +39,51 @@ function MyForm() {
This package expands upon the types and configurability of [jsonforms UISchemas](https://jsonforms.io/docs/uischema). When writing UISchemas, you'll want to provide your jsonschema's type to our `UISchema` type to take advantage of advanced typechecking & UI configurability. See our storybooks (instructions for running storybooks under `Contributing`) for more examples.

```tsx
import { useState } from "react"
import { Form, Button } from "antd"
import { JsonForms } from "@jsonforms/react"
import {
rendererRegistryEntries,
cellRegistryEntries,
UISchema,
} from "@great-expectations/jsonforms-antd-renderers"

const schema = {
type: "object",
properties: { password: { type: "string" } },
}
} as const
// Be sure to use an `as const` assertion so that UISchema
// can see the specific types of `type` fields within a schema.
// i.e. without `as const`, the value "object" is interpreted
// as a string type, and not the string literal type "object"

const uischema: UISchema<typeof schema> = {
type: "VerticalLayout",
elements: [
{
type: "Control",
scope: "#/properties/password",
// properties like type: "password" here are unique to this renderer package. This allows you more declarative control over how your forms
// render. In this case, the password field will be rendered with AntD's password input component
// Properties like type: "password" here are unique to this renderer package.
// This allows you more declarative control over how your forms render.
// In this case, the password field will be rendered with AntD's password input component.
options: { type: "password" },
},
],
}

function MyForm() {
return (
<JsonForms
schema={schema}
uischema={uischema}
renderers={rendererRegistryEntries}
cells={cellRegistryEntries}
/>
)
}
```

### Form Validation & Submission

Here's a somewhat minimal example showing how to validate & save a form on form submission

```tsx
import { useCallback, useState } from "react"
import { Form, Button } from "antd"
import { JsonForms } from "@jsonforms/react"
import {
rendererRegistryEntries,
cellRegistryEntries,
} from "@great-expectations/jsonforms-antd-renderers"

function MyForm() {
const [data, setData] = useState<Record<string, unknown>>({})
const [form] = Form.useForm()
const onSubmit = useCallback(async () => {
const formValidationResult = await form
.validateFields()
.then((values: Record<string, unknown>) => values)
.catch((errorInfo: { errorFields: unknown[] }) => errorInfo)

if ("errorFields" in formValidationResult) {
return // nothing to do; validateFields will have already rendered error messages on form fields
}
// api call to save form data goes here, e.g.
await yourApiCall(data)
}, [form, data])

return (
<Form form={form}>
<Form onFinish={() => myApiCall(data)}>
<JsonForms
data={data}
onChange={(result) => setData(result.data as Record<string, unknown>)}
schema={schema}
uischema={uischema}
renderers={rendererRegistryEntries}
cells={cellRegistryEntries}
/>
<Form.Item>
<Button type="primary" onClick={onSubmit}>
Submit
</Button>
<Button htmlType="submit">Submit</Button>
</Form.Item>
</Form>
)
Expand Down Expand Up @@ -160,8 +118,8 @@ function MyForm() {

- We use [semantic release](https://github.com/semantic-release/semantic-release) to version & release our package, so make sure your commits adhere to the [conventional commit format](https://semantic-release.gitbook.io/semantic-release#commit-message-format)

### Testing package locally
### Testing the package locally

- Run pack: `pnpm pack`
- If you previously installed the package, you may need to remove it first: `yarn remove @great-expectations/jsonforms-antd-renderers` and clear cache: `yarn cache clean`
- Install the package in your project: `yarn add /path/to/jsonforms-antd-renderers-0.0.0-semantic-release.tgz`
- Create an installable tarball file from this directory: `pnpm pack`
- If you previously installed the package, you may need to remove it first: `npm uninstall @great-expectations/jsonforms-antd-renderers` and possibly clear your package manager's cache
- Install the package in your project: `npm install /path/to/jsonforms-antd-renderers-0.0.0-semantic-release.tgz`
125 changes: 3 additions & 122 deletions src/stories/Configure.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,131 +22,12 @@ export const RightArrow = () => (

<div className="sb-container">
<div className='sb-section-title'>
# Getting Started

lorem ipsum

</div>
<div className="sb-section">
<div className="sb-section-item">
<h4 className="sb-section-item-heading">Add styling and CSS</h4>
</div>
# @great-expectations/jsonforms-antd-renderers
You can check out the different control and layout components in the sidebar to the left,
and note that the jsonschemas and uischemas are editable in case you'd like to experiment!
</div>
</div>
<div className="sb-container">
<div className='sb-section-title'>
# Do more with Storybook

Now that you know the basics, let's explore other parts of Storybook that will improve your experience. This list is just to get you started. You can customise Storybook in many ways to fit your needs.

</div>

<div className="sb-section">
<div className="sb-features-grid">
<div className="sb-grid-item">
<h4 className="sb-section-item-heading">Autodocs</h4>
<p className="sb-section-item-paragraph">Auto-generate living,
interactive reference documentation from your components and stories.</p>
<a
href="https://storybook.js.org/docs/react/writing-docs/autodocs"
target="_blank"
>Learn more<RightArrow /></a>
</div>
<div className="sb-grid-item">
<h4 className="sb-section-item-heading">Publish to Chromatic</h4>
<p className="sb-section-item-paragraph">Publish your Storybook to review and collaborate with your entire team.</p>
<a
href="https://storybook.js.org/docs/react/sharing/publish-storybook#publish-storybook-with-chromatic"
target="_blank"
>Learn more<RightArrow /></a>
</div>
<div className="sb-grid-item">
<h4 className="sb-section-item-heading">Figma Plugin</h4>
<p className="sb-section-item-paragraph">Embed your stories into Figma to cross-reference the design and live
implementation in one place.</p>
<a
href="https://storybook.js.org/docs/react/sharing/design-integrations#embed-storybook-in-figma-with-the-plugin"
target="_blank"
>Learn more<RightArrow /></a>
</div>
<div className="sb-grid-item">
<h4 className="sb-section-item-heading">Testing</h4>
<p className="sb-section-item-paragraph">Use stories to test a component in all its variations, no matter how
complex.</p>
<a
href="https://storybook.js.org/docs/react/writing-tests"
target="_blank"
>Learn more<RightArrow /></a>
</div>
<div className="sb-grid-item">
<h4 className="sb-section-item-heading">Accessibility</h4>
<p className="sb-section-item-paragraph">Automatically test your components for a11y issues as you develop.</p>
<a
href="https://storybook.js.org/docs/react/writing-tests/accessibility-testing"
target="_blank"
>Learn more<RightArrow /></a>
</div>
<div className="sb-grid-item">
<h4 className="sb-section-item-heading">Theming</h4>
<p className="sb-section-item-paragraph">Theme Storybook's UI to personalize it to your project.</p>
<a
href="https://storybook.js.org/docs/react/configure/theming"
target="_blank"
>Learn more<RightArrow /></a>
</div>
</div>
</div>
</div>
<div className='sb-addon'>
<div className='sb-addon-text'>
<h4>Addons</h4>
<p className="sb-section-item-paragraph">Integrate your tools with Storybook to connect workflows.</p>
<a
href="https://storybook.js.org/integrations/"
target="_blank"
>Discover all addons<RightArrow /></a>
</div>
<div className='sb-addon-img'>
</div>
</div>

<div className="sb-section sb-socials">
<div className="sb-section-item">
Join our contributors building the future of UI development.

<a
href="https://github.com/storybookjs/storybook"
target="_blank"
>Star on GitHub<RightArrow /></a>
</div>
<div className="sb-section-item">
<div>
Get support and chat with frontend developers.

<a
href="https://discord.gg/storybook"
target="_blank"
>Join Discord server<RightArrow /></a>
</div>
</div>
<div className="sb-section-item">
<div>
Watch tutorials, feature previews and interviews.

<a
href="https://www.youtube.com/@chromaticui"
target="_blank"
>Watch on YouTube<RightArrow /></a>
</div>
</div>
<div className="sb-section-item">
<p>Follow guided walkthroughs on for key workflows.</p>

<a
href="https://storybook.js.org/tutorials/"
target="_blank"
>Discover tutorials<RightArrow /></a>
</div>

</div>

Expand Down

0 comments on commit 4154bf0

Please sign in to comment.