[Doc] Add <ReferenceInputBase> and <ReferenceArrayInputBase> documentation in headless doc site
#10965
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR adds documentation for two headless React Admin components, <ReferenceInputBase> and <ReferenceArrayInputBase>, to the headless documentation site. These are essential components for handling foreign key relationships in forms but were previously undocumented.
- Creates comprehensive documentation for
<ReferenceInputBase>and<ReferenceArrayInputBase>components - Adds both components to the navigation menu under the "Inputs" section
- Provides detailed examples, props documentation, and usage patterns for each component
Reviewed Changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs_headless/src/content/docs/ReferenceInputBase.md | Complete documentation for the <ReferenceInputBase> component including usage examples, props table, and performance notes |
| docs_headless/src/content/docs/ReferenceArrayInputBase.md | Complete documentation for the <ReferenceArrayInputBase> component with array-specific examples and configuration options |
| docs_headless/astro.config.mjs | Updates navigation menu to include the two new documentation pages in the "Inputs" section |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
| <ReferenceInputBase | ||
| source="company_id" | ||
| reference="companies" | ||
| enableGetChoices={({ q }) => !!(q && q.length >= 2)} |
There was a problem hiding this comment.
The double negation !! is unnecessary here since the function should return a boolean. The expression q && q.length >= 2 already evaluates to a boolean-like value that can be returned directly.
| enableGetChoices={({ q }) => !!(q && q.length >= 2)} | |
| enableGetChoices={({ q }) => q && q.length >= 2} |
Copilot uses AI. Check for mistakes.
| <ReferenceArrayInputBase | ||
| source="tag_ids" | ||
| reference="tags" | ||
| enableGetChoices={({ q }) => q && q.length >= 2} |
There was a problem hiding this comment.
This implementation is inconsistent with the same pattern in ReferenceInputBase.md (line 199) which uses !!(q && q.length >= 2). Consider using the same pattern in both files for consistency.
| enableGetChoices={({ q }) => q && q.length >= 2} | |
| enableGetChoices={({ q }) => !!(q && q.length >= 2)} |
Copilot uses AI. Check for mistakes.
| const { choices, isLoading, error } = useChoicesContext(); | ||
| const { field, id } = useInput(); |
There was a problem hiding this comment.
| const { choices, isLoading, error } = useChoicesContext(); | |
| const { field, id } = useInput(); | |
| const { choices, isLoading, error, source } = useChoicesContext(); | |
| const { field, id } = useInput({ source }); |
Not tested but I'm pretty sure you need that.
A story would have helped identify this mistake.
| }); | ||
| ``` | ||
|
|
||
| `<ReferenceInputBase>` handles the data fetching and provides the choices through a [`ChoicesContext`](./useChoicesContext.md). It's up to the child components to render the selection interface. |
| const { choices, isLoading, error } = useChoicesContext(); | ||
| const { field, id } = useInput(); |
There was a problem hiding this comment.
| const { choices, isLoading, error } = useChoicesContext(); | |
| const { field, id } = useInput(); | |
| const { choices, isLoading, error, source } = useChoicesContext(); | |
| const { field, id } = useInput({ source }); |
| | `source` | Required | `string` | - | Name of the entity property to use for the input value | | ||
| | `reference` | Required | `string` | '' | Name of the reference resource, e.g. 'companies'. | | ||
| | `children` | Optional | `ReactNode` | - | The actual selection component | | ||
| | `render` | Optional | `(context) => ReactNode` | - | Function that takes the choices context and renders the selection interface | |
There was a problem hiding this comment.
I don't think there is a render prop, is it? 🤔
| const { choices, isLoading, error } = useChoicesContext(); | ||
| const { field, id } = useInput(); |
There was a problem hiding this comment.
| const { choices, isLoading, error } = useChoicesContext(); | |
| const { field, id } = useInput(); | |
| const { choices, isLoading, error, source } = useChoicesContext(); | |
| const { field, id } = useInput({ source }); |
| <label key={choice.id} style={{ display: 'block' }}> | ||
| <input | ||
| type="checkbox" | ||
| name={field.name} |
There was a problem hiding this comment.
| name={field.name} | |
| name={choice.name} |
There was a problem hiding this comment.
Nope, we want the field name here
| }); | ||
| ``` | ||
|
|
||
| `<ReferenceArrayInputBase>` handles the data fetching and provides the choices through a [`ChoicesContext`](./useChoicesContext.md). It's up to the child components to render the selection interface. |
| const { choices, isLoading, error } = useChoicesContext(); | ||
| const { field, id } = useInput(); |
There was a problem hiding this comment.
| const { choices, isLoading, error } = useChoicesContext(); | |
| const { field, id } = useInput(); | |
| const { choices, isLoading, error, source } = useChoicesContext(); | |
| const { field, id } = useInput({ source }); |
| <label key={choice.id} style={{ display: 'block' }}> | ||
| <input | ||
| type="checkbox" | ||
| name={field.name} |
There was a problem hiding this comment.
| name={field.name} | |
| name={choice.name} |
Problem
<ReferenceInputBase>and<ReferenceArrayInputBase>are essential components that are not documented on https://marmelab.com/ra-core/Solution
Document them
How To Test
make doc-headlessAdditional Checks
masterfor a bugfix or a documentation fix, ornextfor a featureAlso, please make sure to read the contributing guidelines.