keystonejs / keystonejs/keystone
Improve custom field documentation
- Dominant language
- TypeScript
- Stars
- 10k
- Forks
- 1.3k
- Avg merge
- 19h 14m
- Merged PRs (30d)
- 19
Description
I've been trying to create my own "Select images from media gallery" custom field which basically just replicates [this document component block extension](https://github.com/beemstream/keystone-document-gallery), but I feel like I'm basically throwing my head against a wall trying to understand what all the different custom field config options actually do. While I do appreciate that everything is typed, reverse engineering from the types alone is very painful.
Here's some things I think would be very helpful if explained in documentation:
1. What is the config object passed into your custom field function? For example:
```ts
export function text({
isIndexed,
...config // <-- this
}
```
2. Explanation of the `graphql` object exported from `@keystone-6/core`
2. Detailed explanation of the `input` and `output` properties required by the `fieldType()` function
2. How does this magical `controller` object work? How does it hook in to everything else? Maybe some simple diagrams?
2. Detailed explanation of all the properties in the following types:
- `FieldControllerConfig`
- `FieldController`
I'm sure there's more that I've missed, but better documentation for custom fields would be a god-send.
Contributor guide
Research direction
No documentation file is named. Start by tracing the custom field function, the graphql export, fieldType() input and output properties, and the FieldControllerConfig and FieldController types. Done means the custom-field configuration and controller behavior are explained with practical examples, including the requested diagrams where useful.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- graphql, typescript
- Domain
- developer-experience, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100