Merge pull request #8863 from marmelab/ts-record-reference-fields

Add TS support to fields

Author: fzaninotto

docs/Fields.md

@@ -597,4 +597,39 @@ You can find components for react-admin in third-party repositories.
 
 - [OoDeLally/react-admin-clipboard-list-field](https://github.com/OoDeLally/react-admin-clipboard-list-field): a quick and customizable copy-to-clipboard field.
 - [MrHertal/react-admin-json-view](https://github.com/MrHertal/react-admin-json-view): JSON field and input for react-admin.
-- [alexgschwend/react-admin-color-picker](https://github.com/alexgschwend/react-admin-color-picker): a color field
+- [alexgschwend/react-admin-color-picker](https://github.com/alexgschwend/react-admin-color-picker): a color field
+
+## TypeScript
+
+All field components accept a generic type that describes the record. This lets TypeScript validate that the `source` prop targets an actual field of the record:
+
+```tsx
+import * as React from "react";
+import { Show, SimpleShowLayout, TextField, DateField, RichTextField } from 'react-admin';
+
+// Note that you shouldn't extend RaRecord for this to work
+type Post = {
+    id: number;
+    title: string;
+    teaser: string;
+    body: string;
+    published_at: string;
+}
+
+export const PostShow = () => (
+    <Show>
+        <SimpleShowLayout>
+            <TextField<Post> source="title" />
+            <TextField<Post> source="teaser" />
+            {/* Here TS will show an error because a teasr field does not exist */}
+            <TextField<Post> source="teasr" />
+            <RichTextField<Post> source="body" />
+            <DateField<Post> label="Publication date" source="published_at" />
+        </SimpleShowLayout>
+    </Show>
+);
+```
+
+**Limitation**: You must not extend `RaRecord` for this to work. This is because `RaRecord` extends `Record<string, any>` and TypeScript would not be able to infer your types properties.
+
+Specifying the record type will also allow your IDE to provide auto-completion for both the `source` and `sortBy` prop. Note that the `sortBy` prop also accepts any string.

docs/js/prism.js

@@ -2,7 +2,7 @@ import * as React from 'react';
 import { useRecordContext } from 'react-admin';
 import { Box } from '@mui/material';
 
-import { Company, Contact } from '../types';
+import { Company } from '../types';
 
 const sizeInPixel = {
     medium: 42,
@@ -14,7 +14,7 @@ export const LogoField = ({
 }: {
     size?: 'small' | 'medium';
 }) => {
-    const record = useRecordContext<Company | Contact>();
+    const record = useRecordContext<Company>();
     if (!record) return null;
     return (
         <Box

examples/crm/src/companies/LogoField.tsx

@@ -61,9 +61,7 @@ export const TagsListEdit = () => {
     };
 
     const handleDeleteTag = (id: Identifier) => {
-        const tags: Identifier[] = record.tags.filter(
-            (tagId: Identifier) => tagId !== id
-        );
+        const tags = record.tags.filter(tagId => tagId !== id);
         update('contacts', {
             id: record.id,
             data: { tags },
@@ -72,7 +70,7 @@ export const TagsListEdit = () => {
     };
 
     const handleAddTag = (id: Identifier) => {
-        const tags: Identifier[] = [...record.tags, id];
+        const tags = [...record.tags, id];
         update('contacts', {
             id: record.id,
             data: { tags },

examples/crm/src/contacts/TagsListEdit.tsx

@@ -1,13 +1,13 @@
 import { RaRecord } from 'react-admin';
-import { Company, Contact, ContactNote, Deal, Tag } from '../types';
+import { Company, Contact, ContactNote, Deal, Sale, Tag } from '../types';
 
 export interface Db {
     companies: Company[];
     contacts: Contact[];
     contactNotes: ContactNote[];
     deals: Deal[];
     dealNotes: RaRecord[];
-    sales: RaRecord[];
+    sales: Sale[];
     tags: Tag[];
     tasks: RaRecord[];
 }

examples/crm/src/dataGenerator/types.ts

@@ -1,4 +1,4 @@
-import { RaRecord, Identifier } from 'react-admin';
+import { Identifier, RaRecord } from 'react-admin';
 
 export interface Sale extends RaRecord {
     first_name: string;
@@ -38,6 +38,8 @@ export interface Contact extends RaRecord {
     gender: string;
     sales_id: Identifier;
     nb_notes: number;
+    status: string;
+    background: string;
 }
 
 export interface ContactNote extends RaRecord {
@@ -59,6 +61,7 @@ export interface Deal extends RaRecord {
     amount: number;
     created_at: string;
     updated_at: string;
+    start_at: string;
     sales_id: Identifier;
     index: number;
     nb_notes: number;

examples/crm/src/types.ts

@@ -7,7 +7,7 @@ interface Props {
 
 const ProductReferenceField = (
     props: Props &
-        Omit<Omit<ReferenceFieldProps, 'source'>, 'reference' | 'children'>
+        Omit<ReferenceFieldProps, 'source' | 'reference' | 'children'>
 ) => (
     <ReferenceField
         label="Product"

examples/demo/src/products/ProductReferenceField.tsx

@@ -16,10 +16,10 @@ import {
 } from 'react-admin';
 
 import AvatarField from '../visitors/AvatarField';
-import { Customer } from './../types';
+import { Customer, Review } from './../types';
 
 export const ReviewItem = () => {
-    const record = useRecordContext();
+    const record = useRecordContext<Review>();
     const createPath = useCreatePath();
     if (!record) {
         return null;

examples/demo/src/reviews/ReviewItem.tsx

@@ -1,4 +1,4 @@
-import { RaRecord, Identifier } from 'react-admin';
+import { Identifier, RaRecord } from 'react-admin';
 
 export type ThemeName = 'light' | 'dark';
 
@@ -35,6 +35,7 @@ export interface Customer extends RaRecord {
     groups: string[];
     nb_commands: number;
     total_spent: number;
+    email: string;
 }
 
 export type OrderStatus = 'ordered' | 'delivered' | 'cancelled';
@@ -44,14 +45,22 @@ export interface Order extends RaRecord {
     basket: BasketItem[];
     date: Date;
     total: number;
+    total_ex_taxes: number;
+    delivery_fees: number;
+    tax_rate: number;
+    taxes: number;
+    customer_id: Identifier;
+    reference: string;
 }
 
-export interface BasketItem {
+export type BasketItem = {
     product_id: Identifier;
     quantity: number;
-}
+};
 
-export interface Invoice extends RaRecord {}
+export interface Invoice extends RaRecord {
+    date: Date;
+}
 
 export type ReviewStatus = 'accepted' | 'pending' | 'rejected';
 
@@ -60,6 +69,7 @@ export interface Review extends RaRecord {
     status: ReviewStatus;
     customer_id: Identifier;
     product_id: Identifier;
+    comment: string;
 }
 
 declare global {

examples/demo/src/types.ts

@@ -38,7 +38,7 @@ const FullNameField = (props: Props) => {
 };
 
 FullNameField.defaultProps = {
-    source: 'last_name',
+    source: 'last_name' as const,
     label: 'resources.customers.fields.name',
 };
 

examples/demo/src/visitors/FullNameField.tsx

@@ -5,11 +5,13 @@ import { useGetManyAggregate } from '../../dataProvider';
 import { ListControllerResult, useList } from '../list';
 import { useNotify } from '../../notification';
 
-export interface UseReferenceArrayFieldControllerParams {
+export interface UseReferenceArrayFieldControllerParams<
+    RecordType extends RaRecord = RaRecord
+> {
     filter?: any;
     page?: number;
     perPage?: number;
-    record?: RaRecord;
+    record?: RecordType;
     reference: string;
     resource: string;
     sort?: SortPayload;
@@ -43,8 +45,11 @@ const defaultSort = { field: null, order: null };
  *
  * @returns {ListControllerResult} The reference props
  */
-export const useReferenceArrayFieldController = (
-    props: UseReferenceArrayFieldControllerParams
+export const useReferenceArrayFieldController = <
+    RecordType extends RaRecord = RaRecord,
+    ReferenceRecordType extends RaRecord = RaRecord
+>(
+    props: UseReferenceArrayFieldControllerParams<RecordType>
 ): ListControllerResult => {
     const {
         filter = defaultFilter,
@@ -64,7 +69,9 @@ export const useReferenceArrayFieldController = (
         return emptyArray;
     }, [value, source]);
 
-    const { data, error, isLoading, isFetching, refetch } = useGetManyAggregate(
+    const { data, error, isLoading, isFetching, refetch } = useGetManyAggregate<
+        ReferenceRecordType
+    >(
         reference,
         { ids },
         {
@@ -88,7 +95,7 @@ export const useReferenceArrayFieldController = (
         }
     );
 
-    const listProps = useList({
+    const listProps = useList<ReferenceRecordType>({
         data,
         error,
         filter,

packages/ra-core/src/controller/field/useReferenceArrayFieldController.ts

@@ -5,18 +5,20 @@ import isEqual from 'lodash/isEqual';
 import { useSafeSetState, removeEmpty } from '../../util';
 import { useGetManyReference } from '../../dataProvider';
 import { useNotify } from '../../notification';
-import { RaRecord, SortPayload } from '../../types';
+import { Identifier, RaRecord, SortPayload } from '../../types';
 import { ListControllerResult } from '../list';
 import usePaginationState from '../usePaginationState';
 import { useRecordSelection } from '../list/useRecordSelection';
 import useSortState from '../useSortState';
 import { useResourceContext } from '../../core';
 
-export interface UseReferenceManyFieldControllerParams {
+export interface UseReferenceManyFieldControllerParams<
+    RecordType extends RaRecord = RaRecord
+> {
     filter?: any;
     page?: number;
     perPage?: number;
-    record?: RaRecord;
+    record?: RecordType;
     reference: string;
     resource?: string;
     sort?: SortPayload;
@@ -52,9 +54,12 @@ const defaultFilter = {};
  *
  * @returns {ListControllerResult} The reference many props
  */
-export const useReferenceManyFieldController = (
-    props: UseReferenceManyFieldControllerParams
-): ListControllerResult => {
+export const useReferenceManyFieldController = <
+    RecordType extends RaRecord = RaRecord,
+    ReferenceRecordType extends RaRecord = RaRecord
+>(
+    props: UseReferenceManyFieldControllerParams<RecordType>
+): ListControllerResult<ReferenceRecordType> => {
     const {
         reference,
         record,
@@ -147,11 +152,11 @@ export const useReferenceManyFieldController = (
         isFetching,
         isLoading,
         refetch,
-    } = useGetManyReference(
+    } = useGetManyReference<ReferenceRecordType>(
         reference,
         {
             target,
-            id: get(record, source),
+            id: get(record, source) as Identifier,
             pagination: { page, perPage },
             sort,
             filter: filterValues,

packages/ra-core/src/controller/field/useReferenceManyFieldController.ts

@@ -1,7 +1,7 @@
 import { useMemo } from 'react';
 
 import { useStore, useRemoveFromStore } from '../../store';
-import { Identifier } from '../../types';
+import { RaRecord } from '../../types';
 
 /**
  * Get the list of selected items for a resource, and callbacks to change the selection
@@ -10,14 +10,14 @@ import { Identifier } from '../../types';
  *
  * @returns {Object} Destructure as [selectedIds, { select, toggle, clearSelection }].
  */
-export const useRecordSelection = (
+export const useRecordSelection = <RecordType extends RaRecord = any>(
     resource: string
 ): [
-    Identifier[],
+    RecordType['id'][],
     {
-        select: (ids: Identifier[]) => void;
-        unselect: (ids: Identifier[]) => void;
-        toggle: (id: Identifier) => void;
+        select: (ids: RecordType['id'][]) => void;
+        unselect: (ids: RecordType['id'][]) => void;
+        toggle: (id: RecordType['id']) => void;
         clearSelection: () => void;
     }
 ] => {
@@ -27,18 +27,18 @@ export const useRecordSelection = (
 
     const selectionModifiers = useMemo(
         () => ({
-            select: (idsToAdd: Identifier[]) => {
+            select: (idsToAdd: RecordType['id'][]) => {
                 if (!idsToAdd) return;
                 setIds([...idsToAdd]);
             },
-            unselect(idsToRemove: Identifier[]) {
+            unselect(idsToRemove: RecordType['id'][]) {
                 if (!idsToRemove || idsToRemove.length === 0) return;
                 setIds(ids => {
                     if (!Array.isArray(ids)) return [];
                     return ids.filter(id => !idsToRemove.includes(id));
                 });
             },
-            toggle: (id: Identifier) => {
+            toggle: (id: RecordType['id']) => {
                 if (typeof id === 'undefined') return;
                 setIds(ids => {
                     if (!Array.isArray(ids)) return [...ids];

packages/ra-core/src/controller/list/useRecordSelection.ts

@@ -1,5 +1,6 @@
 import { useContext } from 'react';
 import { RecordContext } from './RecordContext';
+import { RaRecord } from '../../types';
 
 /**
  * Hook to read the record from a RecordContext.
@@ -30,7 +31,7 @@ import { RecordContext } from './RecordContext';
  * @returns {RaRecord} A record object
  */
 export const useRecordContext = <
-    RecordType extends Record<string, unknown> = Record<string, any>
+    RecordType extends RaRecord | Omit<RaRecord, 'id'> = RaRecord
 >(
     props?: UseRecordContextParams<RecordType>
 ): RecordType | undefined => {
@@ -42,7 +43,7 @@ export const useRecordContext = <
 };
 
 export interface UseRecordContextParams<
-    RecordType extends Record<string, unknown> = Record<string, unknown>
+    RecordType extends RaRecord | Omit<RaRecord, 'id'> = RaRecord
 > {
     record?: RecordType;
     [key: string]: any;

packages/ra-core/src/controller/record/useRecordContext.ts

@@ -44,7 +44,7 @@ export interface UseReferenceResult<RecordType extends RaRecord = any> {
  *
  * @returns {UseReferenceResult} The reference record
  */
-export const useReference = <RecordType extends RaRecord = any>({
+export const useReference = <RecordType extends RaRecord = RaRecord>({
     reference,
     id,
     options = {},