Skip to content

Commit 85221a3

Browse files
djhidjhi
authored
Merge pull request #9234 from marmelab/inline-component-doc
[TypeScript] Add inline documentation for most common components
2 parents b5373de + c7b5e20 commit 85221a3

File tree

10 files changed

+1213
-28
lines changed

10 files changed

+1213
-28
lines changed

‎docs/Admin.md

+45-15
Original file line numberDiff line numberDiff line change
@@ -250,10 +250,17 @@ React-admin apps contain a special route called `/auth-callback` to let external
250250
If you need a different behavior for this route, you can render a custom component by passing it as the `authCallbackPage` prop.
251251

252252
```tsx
253+
import { Admin } from 'react-admin';
254+
import { dataProvider } from './dataProvider';
255+
import { authProvider } from './authProvider';
253256
import MyAuthCallbackPage from './MyAuthCallbackPage';
254257

255258
const App = () => (
256-
<Admin authCallbackPage={MyAuthCallbackPage}>
259+
<Admin
260+
authCallbackPage={MyAuthCallbackPage}
261+
authProvider={authProvider}
262+
dataProvider={dataProvider}
263+
>
257264
...
258265
</Admin>
259266
);
@@ -330,17 +337,18 @@ The Auth Provider also lets you configure redirections after login/logout, anony
330337

331338
## `basename`
332339

333-
Use this prop to make all routes and links in your Admin relative to a "base" portion of the URL pathname that they all share. This is required when using the [`BrowserHistory`](https://github.com/remix-run/history/blob/main/docs/api-reference.md#createbrowserhistory) to serve the application under a sub-path of your domain (for example https://marmelab.com/ra-enterprise-demo), or when embedding react-admin inside a single-page app with its own routing.
340+
Use this prop to make all routes and links in your Admin relative to a "base" portion of the URL pathname that they all share. This is required when using the [`BrowserRouter`](https://reactrouter.com/en/main/router-components/browser-router) to serve the application under a sub-path of your domain (for example https://marmelab.com/ra-enterprise-demo), or when embedding react-admin inside a single-page app with its own routing.
334341

335342
```tsx
336343
import { Admin } from 'react-admin';
337-
import { createBrowserHistory } from 'history';
344+
import { BrowserRouter } from 'react-router-dom';
338345

339-
const history = createBrowserHistory();
340346
const App = () => (
341-
<Admin basename="/admin" history={history}>
342-
...
343-
</Admin>
347+
<BrowserRouter>
348+
<Admin basename="/admin">
349+
...
350+
</Admin>
351+
</BrowserRouter>
344352
);
345353
```
346354

@@ -434,6 +442,7 @@ If you want to support both light and dark mode, you can provide a `darkTheme` i
434442

435443
```tsx
436444
import { Admin } from 'react-admin';
445+
import { dataProvider } from './dataProvider';
437446
import { darkTheme, lightTheme } from './themes';
438447

439448
const App = () => (
@@ -482,11 +491,11 @@ You can opt out of telemetry by simply adding `disableTelemetry` to the `<Admin>
482491

483492
```tsx
484493
// in src/App.js
485-
import * as React from "react";
486494
import { Admin } from 'react-admin';
495+
import { dataProvider } from './dataProvider';
487496

488497
const App = () => (
489-
<Admin disableTelemetry>
498+
<Admin disableTelemetry dataProvider={dataProvider}>
490499
// ...
491500
</Admin>
492501
);
@@ -572,10 +581,17 @@ Finally, you can also pass a custom component as the `layout` prop. It must cont
572581
If you want to customize the Login page, or switch to another authentication strategy than a username/password form, pass a component of your own as the `loginPage` prop. React-admin will display this component whenever the `/login` route is called.
573582

574583
```tsx
584+
import { Admin } from 'react-admin';
585+
import { dataProvider } from './dataProvider';
586+
import { authProvider } from './authProvider';
575587
import MyLoginPage from './MyLoginPage';
576588

577589
const App = () => (
578-
<Admin loginPage={MyLoginPage}>
590+
<Admin
591+
loginPage={MyLoginPage}
592+
authProvider={authProvider}
593+
dataProvider={dataProvider}
594+
>
579595
...
580596
</Admin>
581597
);
@@ -737,9 +753,17 @@ Some pages in react-admin apps may allow anonymous access. For that reason, reac
737753
If you know your app will never accept anonymous access, you can force the app to wait for the `authProvider.checkAuth()` to resolve before rendering the page layout, by setting the `<Admin requireAuth>` prop.
738754

739755
```tsx
756+
import { Admin } from 'react-admin';
757+
import { dataProvider } from './dataProvider';
758+
import { authProvider } from './authProvider';
759+
740760
const App = () => (
741-
<Admin dataProvider={dataProvider} authProvider={authProvider} requireAuth>
742-
<Resource name="posts" list={PostList} />
761+
<Admin
762+
requireAuth
763+
authProvider={authProvider}
764+
dataProvider={dataProvider}
765+
>
766+
...
743767
</Admin>
744768
);
745769
```
@@ -748,7 +772,12 @@ const App = () => (
748772

749773
The `<Admin>` component initializes a [Store](./Store.md) for user preferences using `localStorage` as the storage engine. You can override this by passing a custom `store` prop.
750774

751-
For instance, you can store the data in memory instead of `localStorage`. This is useful e.g. for tests, or for apps that should not persist user data between sessions:
775+
Built-in stores are:
776+
777+
- `memoryStore`: stores data in memory
778+
- `localStorageStore`: stores data in `localStorage`
779+
780+
For instance, you can store the user preferences in memory, e.g. for tests, or for apps that should not persist user data between sessions:
752781

753782
```tsx
754783
import { Admin, Resource, memoryStore } from 'react-admin';
@@ -854,10 +883,11 @@ const App = () => (
854883

855884
React-admin links are absolute (e.g. `/posts/123/show`). If you serve your admin from a sub path (e.g. `/admin`), react-admin works seamlessly as it only appends a hash (URLs will look like `/admin#/posts/123/show`).
856885

857-
However, if you serve your admin from a sub path AND use another Router (like `BrowserRouter` for instance), you need to set the `<Admin basename>` prop, so that react-admin routes include the basename in all links (e.g. `/admin/posts/123/show`).
886+
However, if you serve your admin from a sub path AND use another Router (like [`<BrowserRouter>`](https://reactrouter.com/en/main/router-components/browser-router) for instance), you need to set the `<Admin basename>` prop, so that react-admin routes include the basename in all links (e.g. `/admin/posts/123/show`).
858887

859888
```tsx
860889
import { Admin, Resource } from 'react-admin';
890+
import { BrowserRouter } from 'react-router-dom';
861891

862892
const App = () => (
863893
<BrowserRouter>
@@ -870,7 +900,7 @@ const App = () => (
870900

871901
This makes all links be prefixed with `/admin`.
872902

873-
Note that it is your responsibility to serve the admin from the sub path, e.g. by setting the `homepage` field in your `package.json` if you use [Create React App](https://create-react-app.dev/docs/deployment/#building-for-relative-paths).
903+
Note that it is your responsibility to serve the admin from the sub path, e.g. by setting the `base` field in `vite.config.ts` if you use [Vite.js](https://vitejs.dev/config/shared-options.html#base), or the `homepage` field in `package.json` if you use [Create React App](https://create-react-app.dev/docs/deployment/#building-for-relative-paths).
874904

875905
If you want to use react-admin as a sub path of a larger React application, check the next section for instructions.
876906

‎packages/ra-core/src/controller/list/useListController.ts

+189
Original file line numberDiff line numberDiff line change
@@ -179,16 +179,163 @@ export const useListController = <RecordType extends RaRecord = any>(
179179
};
180180

181181
export interface ListControllerProps<RecordType extends RaRecord = any> {
182+
/**
183+
* The debounce delay for filter queries in milliseconds. Defaults to 500ms.
184+
*
185+
* @see https://marmelab.com/react-admin/List.html#debounce
186+
* @example
187+
* // wait 1 seconds instead of 500 milliseconds befoce calling the dataProvider
188+
* const PostList = () => (
189+
* <List debounce={1000}>
190+
* ...
191+
* </List>
192+
* );
193+
*/
182194
debounce?: number;
195+
196+
/**
197+
* Allow anonymous access to the list view. Defaults to false.
198+
*
199+
* @see https://marmelab.com/react-admin/List.html#disableauthentication
200+
* @example
201+
* import { List } from 'react-admin';
202+
*
203+
* const BoolkList = () => (
204+
* <List disableAuthentication>
205+
* ...
206+
* </List>
207+
* );
208+
*/
183209
disableAuthentication?: boolean;
210+
184211
/**
185212
* Whether to disable the synchronization of the list parameters with the current location (URL search parameters)
213+
*
214+
* @see https://marmelab.com/react-admin/List.html#disablesyncwithlocation
215+
* @example
216+
* const Dashboard = () => (
217+
* <div>
218+
* // ...
219+
* <ResourceContextProvider value="posts">
220+
* <List disableSyncWithLocation>
221+
* <SimpleList
222+
* primaryText={record => record.title}
223+
* secondaryText={record => `${record.views} views`}
224+
* tertiaryText={record => new Date(record.published_at).toLocaleDateString()}
225+
* />
226+
* </List>
227+
* </ResourceContextProvider>
228+
* <ResourceContextProvider value="comments">
229+
* <List disableSyncWithLocation>
230+
* <SimpleList
231+
* primaryText={record => record.title}
232+
* secondaryText={record => `${record.views} views`}
233+
* tertiaryText={record => new Date(record.published_at).toLocaleDateString()}
234+
* />
235+
* </List>
236+
* </ResourceContextProvider>
237+
* </div>
238+
* )
186239
*/
187240
disableSyncWithLocation?: boolean;
241+
242+
/**
243+
* The function called when a user exports the list
244+
*
245+
* @see https://marmelab.com/react-admin/List.html#exporter
246+
* @example
247+
* import { List, downloadCSV } from 'react-admin';
248+
* import jsonExport from 'jsonexport/dist';
249+
*
250+
* const exporter = posts => {
251+
* const postsForExport = posts.map(post => {
252+
* const { backLinks, author, ...postForExport } = post; // omit backLinks and author
253+
* postForExport.author_name = post.author.name; // add a field
254+
* return postForExport;
255+
* });
256+
* jsonExport(postsForExport, {
257+
* headers: ['id', 'title', 'author_name', 'body'] // order fields in the export
258+
* }, (err, csv) => {
259+
* downloadCSV(csv, 'posts'); // download as 'posts.csv` file
260+
* });
261+
* };
262+
*
263+
* const PostList = () => (
264+
* <List exporter={exporter}>
265+
* ...
266+
* </List>
267+
* )
268+
*/
188269
exporter?: Exporter | false;
270+
271+
/**
272+
* Permanent filter applied to all getList queries, regardless of the user selected filters.
273+
*
274+
* @see https://marmelab.com/react-admin/List.html#filter
275+
* @example
276+
* export const PostList = () => (
277+
* <List filter={{ is_published: true }}>
278+
* ...
279+
* </List>
280+
* );
281+
*/
189282
filter?: FilterPayload;
283+
284+
/**
285+
* The filter to apply when calling getList if the filter is empty.
286+
*
287+
* @see https://marmelab.com/react-admin/List.html#filterdefaultvalues
288+
* @example
289+
* const postFilters = [
290+
* <TextInput label="Search" source="q" alwaysOn />,
291+
* <BooleanInput source="is_published" alwaysOn />,
292+
* <TextInput source="title" defaultValue="Hello, World!" />,
293+
* ];
294+
*
295+
* export const PostList = () => (
296+
* <List filters={postFilters} filterDefaultValues={{ is_published: true }}>
297+
* ...
298+
* </List>
299+
* );
300+
*/
190301
filterDefaultValues?: object;
302+
303+
/**
304+
* The number of results per page. Defaults to 10.
305+
*
306+
* @see https://marmelab.com/react-admin/List.html#perpage
307+
* @example
308+
* export const PostList = () => (
309+
* <List perPage={25}>
310+
* ...
311+
* </List>
312+
* );
313+
*/
191314
perPage?: number;
315+
316+
/**
317+
* The options passed to react-query's useQuery when calling getList.
318+
*
319+
* @see https://marmelab.com/react-admin/List.html#queryoptions
320+
* @example
321+
* import { useNotify, useRedirect, List } from 'react-admin';
322+
*
323+
* const PostList = () => {
324+
* const notify = useNotify();
325+
* const redirect = useRedirect();
326+
*
327+
* const onError = (error) => {
328+
* notify(`Could not load list: ${error.message}`, { type: 'error' });
329+
* redirect('/dashboard');
330+
* };
331+
*
332+
* return (
333+
* <List queryOptions={{ onError }}>
334+
* ...
335+
* </List>
336+
* );
337+
* }
338+
*/
192339
queryOptions?: UseQueryOptions<{
193340
data: RecordType[];
194341
total?: number;
@@ -197,8 +344,50 @@ export interface ListControllerProps<RecordType extends RaRecord = any> {
197344
hasPreviousPage?: boolean;
198345
};
199346
}> & { meta?: any };
347+
348+
/**
349+
* The resource name. Defaults to the resource from ResourceContext.
350+
*
351+
* @see https://marmelab.com/react-admin/List.html#resource
352+
* @example
353+
* import { List } from 'react-admin';
354+
*
355+
* const PostList = () => (
356+
* <List resource="posts">
357+
* ...
358+
* </List>
359+
* );
360+
*/
200361
resource?: string;
362+
363+
/**
364+
* The default sort field and order. Defaults to { field: 'id', order: 'ASC' }.
365+
*
366+
* @see https://marmelab.com/react-admin/List.html#sort
367+
* @example
368+
* export const PostList = () => (
369+
* <List sort={{ field: 'published_at', order: 'DESC' }}>
370+
* ...
371+
* </List>
372+
* );
373+
*/
201374
sort?: SortPayload;
375+
376+
/**
377+
* The key to use to store the current filter & sort. Pass false to disable.
378+
*
379+
* @see https://marmelab.com/react-admin/List.html#storekey
380+
* @example
381+
* const NewerBooks = () => (
382+
* <List
383+
* resource="books"
384+
* storeKey="newerBooks"
385+
* sort={{ field: 'year', order: 'DESC' }}
386+
* >
387+
* ...
388+
* </List>
389+
* );
390+
*/
202391
storeKey?: string | false;
203392
}
204393

0 commit comments

Comments
 (0)