0
# Preferences
1

2
User configuration and customization components for making UI components configurable in react-admin applications. These components enable end-users to customize the interface and have their preferences persisted.
3

4
## Capabilities
5

6
### Configurable Component
7

8
Wrapper component that makes any child component configurable by adding an edit button and preference management.
9

10
```typescript { .api }
11
/**
12
 * Wrapper component to make any component configurable
13
 * @param props - Configurable component configuration props
14
 * @returns Wrapped component with configuration capabilities
15
 */
16
function Configurable(props: ConfigurableProps): ReactElement;
17

18
interface ConfigurableProps {
19
  /** Child component to make configurable */
20
  children: ReactElement;
21
  /** Editor component for configuration UI */
22
  editor?: ReactElement;
23
  /** Unique preference key for storing configuration */
24
  preferenceKey: string;
25
  /** Label for the configuration button */
26
  openButtonLabel?: string;
27
  /** Material UI sx prop for styling */
28
  sx?: SxProps;
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { Configurable } from "ra-ui-materialui";
36

37
// Basic configurable component
38
const ConfigurableTextBlock = ({ preferenceKey = "TextBlock", ...props }) => (
39
  <Configurable 
40
    editor={<TextBlockInspector />} 
41
    preferenceKey={preferenceKey}
42
  >
43
    <TextBlock {...props} />
44
  </Configurable>
45
);
46

47
// Configurable with custom button label
48
const ConfigurableDashboard = () => (
49
  <Configurable
50
    preferenceKey="dashboard"
51
    openButtonLabel="Customize Dashboard"
52
    editor={<DashboardInspector />}
53
  >
54
    <Dashboard />
55
  </Configurable>
56
);
57
```
58

59
### Inspector Component
60

61
Configuration panel component that displays when users want to customize a configurable component.
62

63
```typescript { .api }
64
/**
65
 * Configuration inspector panel component
66
 * @param props - Inspector configuration props
67
 * @returns Configuration panel with controls
68
 */
69
function Inspector(props: InspectorProps): ReactElement;
70

71
interface InspectorProps {
72
  /** Child configuration controls */
73
  children?: ReactNode;
74
  /** CSS class name for styling */
75
  className?: string;
76
  /** Material UI sx prop for styling */
77
  sx?: SxProps;
78
}
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import { Inspector, FieldToggle } from "ra-ui-materialui";
85

86
// Basic inspector with field toggles
87
const DatagridInspector = () => (
88
  <Inspector>
89
    <FieldToggle source="id" />
90
    <FieldToggle source="title" />
91
    <FieldToggle source="author" />
92
    <FieldToggle source="created_at" />
93
  </Inspector>
94
);
95

96
// Inspector with custom controls
97
const CustomInspector = () => (
98
  <Inspector>
99
    <Typography variant="h6">Display Options</Typography>
100
    <FormGroup>
101
      <FormControlLabel 
102
        control={<Switch />} 
103
        label="Show avatars" 
104
      />
105
      <FormControlLabel 
106
        control={<Switch />} 
107
        label="Compact view" 
108
      />
109
    </FormGroup>
110
  </Inspector>
111
);
112
```
113

114
### InspectorButton Component
115

116
Button component for toggling the inspector panel visibility.
117

118
```typescript { .api }
119
/**
120
 * Button for toggling inspector panel visibility
121
 * @param props - Inspector button configuration props
122
 * @returns Button component for opening/closing inspector
123
 */
124
function InspectorButton(props: InspectorButtonProps): ReactElement;
125

126
interface InspectorButtonProps {
127
  /** Button label text */
128
  label?: string;
129
  /** Button icon component */
130
  icon?: ReactElement;
131
  /** CSS class name for styling */
132
  className?: string;
133
  /** Material UI sx prop for styling */
134
  sx?: SxProps;
135
}
136
```
137

138
**Usage Examples:**
139

140
```typescript
141
import { InspectorButton } from "ra-ui-materialui";
142
import SettingsIcon from "@mui/icons-material/Settings";
143

144
// Basic inspector button
145
const MyInspectorButton = () => <InspectorButton />;
146

147
// Custom inspector button with icon
148
const CustomInspectorButton = () => (
149
  <InspectorButton 
150
    label="Customize"
151
    icon={<SettingsIcon />}
152
  />
153
);
154
```
155

156
### Field Toggle Component
157

158
Toggle control for showing/hiding fields in configurable data displays.
159

160
```typescript { .api }
161
/**
162
 * Toggle control for field visibility in configurable components
163
 * @param props - Field toggle configuration props
164
 * @returns Toggle switch for field visibility
165
 */
166
function FieldToggle(props: FieldToggleProps): ReactElement;
167

168
interface FieldToggleProps {
169
  /** Field source name */
170
  source: string;
171
  /** Display label for the field */
172
  label?: string;
173
  /** Whether the field is disabled */
174
  disabled?: boolean;
175
  /** CSS class name for styling */
176
  className?: string;
177
}
178
```
179

180
**Usage Examples:**
181

182
```typescript
183
import { FieldToggle } from "ra-ui-materialui";
184

185
// Basic field toggle
186
const PostFieldToggle = () => <FieldToggle source="title" />;
187

188
// Field toggle with custom label
189
const CustomFieldToggle = () => (
190
  <FieldToggle 
191
    source="author_name"
192
    label="Author"
193
    disabled={false}
194
  />
195
);
196
```
197

198
### Fields Selector Component
199

200
Component for selecting which fields to display in a configurable list or datagrid.
201

202
```typescript { .api }
203
/**
204
 * Component for selecting visible fields in configurable displays
205
 * @param props - Fields selector configuration props
206
 * @returns Field selection interface
207
 */
208
function FieldsSelector(props: FieldsSelectorProps): ReactElement;
209

210
interface FieldsSelectorProps {
211
  /** Available field options */
212
  fields?: FieldOption[];
213
  /** Currently selected fields */
214
  selectedFields?: string[];
215
  /** Callback when field selection changes */
216
  onSelectionChange?: (fields: string[]) => void;
217
  /** CSS class name for styling */
218
  className?: string;
219
}
220

221
interface FieldOption {
222
  /** Field source name */
223
  source: string;
224
  /** Display label */
225
  label: string;
226
  /** Whether field is required */
227
  required?: boolean;
228
}
229
```
230

231
**Usage Examples:**
232

233
```typescript
234
import { FieldsSelector } from "ra-ui-materialui";
235

236
const PostFieldsSelector = () => {
237
  const fields = [
238
    { source: 'id', label: 'ID', required: true },
239
    { source: 'title', label: 'Title' },
240
    { source: 'author', label: 'Author' },
241
    { source: 'created_at', label: 'Created' },
242
  ];
243

244
  return (
245
    <FieldsSelector 
246
      fields={fields}
247
      selectedFields={['id', 'title', 'author']}
248
      onSelectionChange={(selected) => {
249
        // Save preference
250
        console.log('Selected fields:', selected);
251
      }}
252
    />
253
  );
254
};
255
```
256

257
## Preference Hooks
258

259
### usePreferenceKey Hook
260

261
Hook for accessing the current preference key context.
262

263
```typescript { .api }
264
/**
265
 * Hook for accessing preference key from context
266
 * @returns Current preference key string
267
 */
268
function usePreferenceKey(): string;
269
```
270

271
### usePreferencesEditor Hook
272

273
Hook for accessing the preferences editor context and state.
274

275
```typescript { .api }
276
/**
277
 * Hook for accessing preferences editor context
278
 * @returns Preferences editor context object
279
 */
280
function usePreferencesEditor(): PreferencesEditorContext | null;
281

282
interface PreferencesEditorContext {
283
  /** Whether edit mode is enabled */
284
  isEnabled: boolean;
285
  /** Enable edit mode */
286
  enable: () => void;
287
  /** Disable edit mode */
288
  disable: () => void;
289
  /** Toggle edit mode */
290
  toggle: () => void;
291
}
292
```
293

294
**Usage Examples:**
295

296
```typescript
297
import { usePreferenceKey, usePreferencesEditor } from "ra-ui-materialui";
298

299
const ConfigurableComponent = () => {
300
  const preferenceKey = usePreferenceKey();
301
  const editor = usePreferencesEditor();
302
  
303
  return (
304
    <div>
305
      <h3>Component: {preferenceKey}</h3>
306
      {editor?.isEnabled && (
307
        <button onClick={editor.disable}>
308
          Exit Edit Mode
309
        </button>
310
      )}
311
    </div>
312
  );
313
};
314
```
315

316
## Types
317

318
```typescript { .api }
319
interface PreferenceKeyContextProvider {
320
  preferenceKey: string;
321
  children: ReactNode;
322
}
323

324
interface PreferencesState {
325
  [key: string]: any;
326
}
327

328
type PreferenceValue = string | number | boolean | object | null;
329
```