Configurable components

docs/Configurable.md

@@ -0,0 +1,123 @@
+---
+layout: default
+title: "The Configurable Component"
+---
+
+# `<Configurable>`
+
+This component makes another component configurable by the end user. When they enter the configuration mode, users can customize the component's settings via the inspector.
+
+![SimpleListConfigurable](./img/SimpleListConfigurable.gif)
+
+Some react-admin components are already configurable - or rather they have a configurable counterpart:
+
+- [`<SimpleListConfigurable>`](./SimpleList.md#configurable)
+
+## Usage
+
+Wrap any component with `<Configurable>` and define its editor to let users customize it via a UI. Don't forget to pass down props to the inner component. Note that every configurable component needs a unique preference key, that is used to persist the user's preferences in the Store.
+
+```jsx
+import { Configurable } from 'react-admin';
+
+const ConfigurableTextBlock = ({ preferenceKey = "textBlock", ...props }) => (
+    <Configurable editor={<TextBlockEditor />} preferenceKey={preferenceKey}>
+        <TextBlock {...props} />
+    </Configurable>
+);
+```
+
+`<Configurable>` creates a context for the `preferenceKey`, so that both the child component and the editor can access it using `usePreferenceKey()`.
+
+Then, use this component in your app:
+
+```jsx
+import { ConfigurableTextBlock } from './ConfigurableTextBlock';
+
+export const Dashboard = () => (
+    <ConfigurableTextBlock
+        title="Welcome to the administration"
+        content="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+    />
+);
+```
+
+## `children`
+
+The wrapped component must use `usePreferenceKey` to get the preference key, and [`useStore`](./useStore.md) to access the configuration.
+
+```jsx
+import { useStore, usePreferenceKey } from 'react-admin';
+
+const TextBlock = ({ title, content }) => {
+    const preferenceKey = usePreferenceKey();
+    const [color] = useStore(`${preferenceKey}.color`, '#ffffff');
+    return (
+        <Box bgcolor={color}>
+            <Typography variant="h6">{title}</Typography>
+            <Typography>{content}</Typography>
+        </Box>
+    );
+};
+```
+
+## `editor`
+
+The editor component must also use `usePreferenceKey` to get the preference key, and [`useStore`](./useStore.md) to read and write the configuration. When the user selects the configurable component, react-admin renders the `editor` component in the inspector.
+
+```jsx
+import { useStore, usePreferenceKey } from 'react-admin';
+
+const TextBlockEditor = ({ preferenceKey }) => {
+    const preferenceKey = usePreferenceKey();
+    const [color, setColor] = useStore(`${preferenceKey}.color`, '#ffffff');
+    return (
+        <Box>
+            <Typography>Configure the text block</Typography>
+            <TextField
+                label="Color"
+                value={color}
+                onChange={e => setColor(e.target.value)}
+            />
+        </Box>
+    );
+};
+```
+
+## `preferenceKey`
+
+This parameter lets you specify the key used to store the configuration in the user's preferences. This allows you to have more than one configurable component of the same type per page. 
+
+```jsx
+import { Configurable } from 'react-admin';
+
+const ConfigurableTextBlock = ({ preferenceKey, ...props }) => (
+    <Configurable editor={<TextBlockInspector />} preferenceKey={preferenceKey}>
+        <TextBlock {...props} />
+    </Configurable>
+);
+```
+
+Then in your application, set the `preferenceKey` prop to a unique value for each component:
+
+```jsx
+import { ConfigurableTextBlock } from './ConfigurableTextBlock';
+
+export const Dashboard = () => (
+    <>
+        <ConfigurableTextBlock
+            preferenceKey="textBlock1"
+            title="Welcome to the administration"
+            content="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+        />
+        <ConfigurableTextBlock
+            preferenceKey="textBlock2"
+            title="Security reminder"
+            content="Nullam bibendum orci tortor, a posuere arcu sollicitudin ac"
+        />
+    </>
+);
+```
+
+Users will be able to customize each component independently.
+

docs/SimpleList.md

@@ -165,3 +165,35 @@ export const PostList = props => {
     );
 }
 ```
+
+## Configurable
+
+You can let end users customize the fields displayed in the `<SimpleList>` by using the `<SimpleListConfigurable>` component instead.
+
+![SimpleListConfigurable](./img/SimpleListConfigurable.gif)
+
+```diff
+import {
+    List,
+-   SimpleList,
++   SimpleListConfigurable,
+} from 'react-admin';
+
+export const BookList = () => (
+    <List>
+-       <SimpleList
++       <SimpleListConfigurable
+            primaryText={record => record.title}
+            secondaryText={record => record.author}
+            tertiaryText={record => record.date}
+        />
+    </List>
+);
+```
+
+When users enter the configuration mode and select the `<SimpleList>`, they can set the `primaryText`, `secondaryText`, and `tertiaryText` fields via the inspector. `<SimpleList>` uses a simple templating engine (based on [`lodash.template()`](https://lodash.com/docs/4.17.15#template)) to render the fields. The template receives the current record as parameter. This means users can access the record field using the `${field}` syntax, e.g.:
+
+```
+Title: ${title} (by ${author})
+```
+

docs/navigation.html

@@ -185,12 +185,12 @@
 
 <ul><div>The Store</div>
   <li {% if page.path == 'Store.md' %} class="active" {% endif %}><a class="nav-link" href="./Store.html">Introduction</a></li>
-  <li {% if page.path == 'LocalesMenuButton.md' %} class="active" {% endif %}><a class="nav-link" href="./LocalesMenuButton.html"><code>&lt;LocalesMenuButton&gt;</code></a></li>
-  <li {% if page.path == 'ToggleThemeButton.md' %} class="active" {% endif %}><a class="nav-link" href="./ToggleThemeButton.html"><code>&lt;ToggleThemeButton&gt;</code></a></li>
   <li {% if page.path == 'useStore.md' %} class="active" {% endif %}><a class="nav-link" href="./useStore.html"><code>useStore</code></a></li>
   <li {% if page.path == 'useRemoveFromStore.md' %} class="active" {% endif %}><a class="nav-link" href="./useRemoveFromStore.html"><code>useRemoveFromStore</code></a></li>
   <li {% if page.path == 'useResetStore.md' %} class="active" {% endif %}><a class="nav-link" href="./useResetStore.html"><code>useResetStore</code></a></li>
   <li {% if page.path == 'useStoreContext.md' %} class="active" {% endif %}><a class="nav-link" href="./useStoreContext.html"><code>useStoreContext</code></a></li>
+  <li {% if page.path == 'Configurable.md' %} class="active" {% endif %}><a class="nav-link" href="./Configurable.html"><code>&lt;Configurable&gt;</code></a></li>
+  <li {% if page.path == 'ToggleThemeButton.md' %} class="active" {% endif %}><a class="nav-link" href="./ToggleThemeButton.html"><code>&lt;ToggleThemeButton&gt;</code></a></li>
 </ul>
 
 <ul><div>I18N Provider and Translations</div>

examples/simple/src/Layout.tsx

@@ -1,13 +1,20 @@
 import * as React from 'react';
-
+import { memo } from 'react';
 import { ReactQueryDevtools } from 'react-query/devtools';
-import { Layout } from 'react-admin';
-import { CssBaseline } from '@mui/material';
+import { AppBar, Layout, InspectorButton } from 'react-admin';
+import { CssBaseline, Typography } from '@mui/material';
+
+const MyAppBar = memo(props => (
+    <AppBar {...props}>
+        <Typography flex="1" variant="h6" id="react-admin-title" />
+        <InspectorButton />
+    </AppBar>
+));
 
 export default props => (
     <>
         <CssBaseline />
-        <Layout {...props} />
+        <Layout {...props} appBar={MyAppBar} />
         <ReactQueryDevtools
             initialIsOpen={false}
             toggleButtonProps={{ style: { width: 20, height: 30 } }}

packages/ra-core/src/core/CoreAdminContext.tsx

@@ -11,6 +11,7 @@ import {
     defaultDataProvider,
 } from '../dataProvider';
 import { StoreContextProvider, Store, memoryStore } from '../store';
+import { PreferencesEditorContextProvider } from '../preferences/PreferencesEditorContextProvider';
 import { I18nContextProvider } from '../i18n';
 import { ResourceDefinitionContextProvider } from './ResourceDefinitionContext';
 import { NotificationContextProvider } from '../notification';
@@ -81,17 +82,19 @@ React-admin requires a valid dataProvider function to work.`);
         <AuthContext.Provider value={finalAuthProvider}>
             <DataProviderContext.Provider value={finalDataProvider}>
                 <StoreContextProvider value={store}>
-                    <QueryClientProvider client={finalQueryClient}>
-                        <AdminRouter history={history} basename={basename}>
-                            <I18nContextProvider value={i18nProvider}>
-                                <NotificationContextProvider>
-                                    <ResourceDefinitionContextProvider>
-                                        {children}
-                                    </ResourceDefinitionContextProvider>
-                                </NotificationContextProvider>
-                            </I18nContextProvider>
-                        </AdminRouter>
-                    </QueryClientProvider>
+                    <PreferencesEditorContextProvider>
+                        <QueryClientProvider client={finalQueryClient}>
+                            <AdminRouter history={history} basename={basename}>
+                                <I18nContextProvider value={i18nProvider}>
+                                    <NotificationContextProvider>
+                                        <ResourceDefinitionContextProvider>
+                                            {children}
+                                        </ResourceDefinitionContextProvider>
+                                    </NotificationContextProvider>
+                                </I18nContextProvider>
+                            </AdminRouter>
+                        </QueryClientProvider>
+                    </PreferencesEditorContextProvider>
                 </StoreContextProvider>
             </DataProviderContext.Provider>
         </AuthContext.Provider>

packages/ra-core/src/i18n/TranslationMessages.ts

@@ -175,5 +175,20 @@ export interface TranslationMessages extends StringMap {
             remove_message: string;
             help: string;
         };
+        configurable?: {
+            customize: string;
+            templateError: string;
+            configureMode: string;
+            inspector: {
+                title: string;
+                content: string;
+                reset: string;
+            };
+            SimpleList: {
+                primaryText: string;
+                secondaryText: string;
+                tertiaryText: string;
+            };
+        };
     };
 }

packages/ra-core/src/index.ts

@@ -1,13 +1,14 @@
-export * from './core';
 export * from './auth';
+export * from './controller';
+export * from './core';
+export * from './preferences';
 export * from './dataProvider';
 export * from './export';
+export * from './form';
 export * from './i18n';
 export * from './inference';
-export * from './util';
-export * from './controller';
-export * from './form';
 export * from './notification';
-export * from './store';
 export * from './routing';
+export * from './store';
 export * from './types';
+export * from './util';

packages/ra-core/src/preferences/PreferenceKeyContext.tsx

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import { createContext, useContext } from 'react';
+
+export const PreferenceKeyContext = createContext<string>('');
+
+export const PreferenceKeyContextProvider = ({
+    value = '',
+    children,
+}: {
+    value?: string;
+    children: React.ReactNode;
+}) => (
+    <PreferenceKeyContext.Provider value={value}>
+        {children}
+    </PreferenceKeyContext.Provider>
+);
+
+export const usePreferenceKey = () => {
+    return useContext(PreferenceKeyContext);
+};

packages/ra-core/src/preferences/PreferencesEditorContext.tsx

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import { createContext, ReactElement } from 'react';
+
+export const PreferencesEditorContext = createContext<
+    PreferencesEditorContextValue
+>(undefined);
+
+export type PreferencesEditorContextValue = {
+    editor: ReactElement | null;
+    setEditor: React.Dispatch<React.SetStateAction<ReactElement>>;
+    preferenceKey?: string;
+    setPreferenceKey: React.Dispatch<React.SetStateAction<string>>;
+    title: string | null;
+    titleOptions?: any;
+    setTitle: (title: string, titleOptions?: any) => void;
+    isEnabled: boolean;
+    enable: () => void;
+    disable: () => void;
+    path: string | null;
+    setPath: (path: string) => void;
+};

packages/ra-core/src/preferences/PreferencesEditorContextProvider.tsx

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import { ReactElement, useCallback, useMemo, useState } from 'react';
+import {
+    PreferencesEditorContext,
+    PreferencesEditorContextValue,
+} from './PreferencesEditorContext';
+
+export const PreferencesEditorContextProvider = ({ children }) => {
+    const [isEnabled, setIsEnabled] = useState(false);
+    const [editor, setEditor] = useState<ReactElement>(null);
+    const [preferenceKey, setPreferenceKey] = useState<string>();
+    const [path, setPath] = useState<string>(null);
+    const [title, setTitleString] = useState<string>(null);
+    const [titleOptions, setTitleOptions] = useState<any>();
+    const enable = useCallback(() => setIsEnabled(true), []);
+    const disable = useCallback(() => {
+        setIsEnabled(false);
+        setEditor(null);
+    }, []);
+
+    const setTitle = useCallback((title: string, titleOptions?: any) => {
+        setTitleString(title);
+        setTitleOptions(titleOptions);
+    }, []);
+
+    const context = useMemo<PreferencesEditorContextValue>(() => {
+        return {
+            editor,
+            setEditor,
+            preferenceKey,
+            setPreferenceKey,
+            title,
+            titleOptions,
+            setTitle,
+            isEnabled,
+            disable,
+            enable,
+            path,
+            setPath,
+        };
+    }, [
+        disable,
+        enable,
+        editor,
+        preferenceKey,
+        isEnabled,
+        path,
+        setPath,
+        title,
+        titleOptions,
+        setTitle,
+    ]);
+
+    return (
+        <PreferencesEditorContext.Provider value={context}>
+            {children}
+        </PreferencesEditorContext.Provider>
+    );
+};

packages/ra-core/src/preferences/index.ts

@@ -0,0 +1,7 @@
+export * from './PreferencesEditorContext';
+export * from './PreferencesEditorContextProvider';
+export * from './useRenderTemplate';
+export * from './usePreferencesEditor';
+export * from './usePreferenceInput';
+export * from './useSetInspectorTitle';
+export * from './PreferenceKeyContext';