Refactor the React OpenAPI admin framework to support fully customizable field rendering and UI composition. (#11)

# Summary

Refactor the React OpenAPI admin framework to support fully customizable field rendering and UI composition.

## Changes

### Admin UI Customization

* Added support for custom:

  * Dashboard component
  * Layout component
  * Login page component
* Introduced `AdminAppProps` and extended `Admin` configuration API.
* Renamed internal dashboard implementation to `DefaultDashboard`.

### Field Component Architecture

* Extracted field rendering into dedicated field components:

  * TextField
  * NumberField
  * BooleanField
  * DateField
  * EnumField
  * RelationField
  * ObjectField
  * FallbackField
  * DateRangeField
  * NumberRangeField
* Added `defaultFieldComponents` registry.
* Refactored `FormField` to resolve components dynamically from a component map instead of hardcoded field type handling.

### Resource Customization

* Added `FieldComponents` support across:

  * Admin
  * ResourceView
  * GenericForm
  * useResource
* Introduced wrapped `FormField` and `GenericForm` components generated from configured field overrides.

### Table Customization

* Added `EnhancedTableComponents`.
* Added support for custom cell renderers per field type.
* Enabled custom rendering for both desktop and mobile table layouts.

### Filter Improvements

* Exported `FilterAutocomplete`.
* Added support for custom date-range and number-range filter components.
* Added filter component extension points.
* Updated filter option label resolution to support `displayFormat`.

### Display Formatting

* Replaced `displayField` usage with `displayFormat`.
* Added template-based display rendering support through `resolveTemplate`.
* Improved relation display configuration handling.

### TypeScript Improvements

* Added TypeScript as a project dependency.
* Removed multiple `@ts-ignore` usages.
* Added strongly typed Axios wrapper methods with generic response support.
* Improved typing across hooks and component interfaces.

### OpenAPI Configuration Validation

* Added validation for enum fields without enum values.
* Added validation for relation resources missing `referenceOptions.enumOption`.
* Improved relation metadata propagation during schema parsing.

### Library Exports

* Exported:

  * Field component types
  * Override types
  * EnhancedTable
  * GenericForm
  * ResourceView
  * Field components and defaults
* Expanded public API surface for consumers extending the framework.

## Benefits

* Enables complete UI customization without modifying framework internals.
* Simplifies creation of custom field types and renderers.
* Improves type safety and developer experience.
* Provides consistent extension points for forms, tables, filters, and admin layouts.
* Makes the framework more suitable for reusable library distribution.

Reviewed-on: #11
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>

react-openapi/components/fields/BooleanField.tsx

@@ -0,0 +1,17 @@
+import { FormControlLabel, Checkbox } from '@mui/material';
+import { FieldComponentProps } from '../../types/overrides';
+
+export default function BooleanField({ field, value, onChange, disabled }: FieldComponentProps) {
+  return (
+    <FormControlLabel
+      control={
+        <Checkbox
+          checked={!!value}
+          onChange={(e) => onChange(e.target.checked)}
+          disabled={disabled}
+        />
+      }
+      label={field.label}
+    />
+  );
+}

react-openapi/components/fields/DateField.tsx

@@ -0,0 +1,18 @@
+import { TextField as MuiTextField } from '@mui/material';
+import { FieldComponentProps } from '../../types/overrides';
+
+export default function DateField({ field, value, onChange, disabled }: FieldComponentProps) {
+  const isDatetime = field.type === 'datetime';
+  return (
+    <MuiTextField
+      fullWidth
+      label={field.label}
+      type={isDatetime ? "datetime-local" : "date"}
+      InputLabelProps={{ shrink: true }}
+      value={value ? new Date(value).toISOString().slice(0, isDatetime ? 16 : 10) : ''}
+      onChange={(e) => onChange(e.target.value)}
+      disabled={disabled}
+      required={field.required}
+    />
+  );
+}

react-openapi/components/fields/DateRangeField.tsx

@@ -0,0 +1,30 @@
+import { Box, TextField as MuiTextField } from '@mui/material';
+import { FieldComponentProps } from '../../types/overrides';
+
+export default function DateRangeField({ value, onChange, disabled }: FieldComponentProps) {
+  const rangeVal = (value as { start?: string; end?: string }) || {};
+  return (
+    <Box sx={{ display: "flex", gap: 1 }}>
+      <MuiTextField
+        type="date"
+        placeholder="From"
+        size="small"
+        value={rangeVal.start ?? ""}
+        onChange={(e) => onChange({ ...rangeVal, start: e.target.value || undefined })}
+        InputLabelProps={{ shrink: true }}
+        sx={{ width: 170 }}
+        disabled={disabled}
+      />
+      <MuiTextField
+        type="date"
+        placeholder="To"
+        size="small"
+        value={rangeVal.end ?? ""}
+        onChange={(e) => onChange({ ...rangeVal, end: e.target.value || undefined })}
+        InputLabelProps={{ shrink: true }}
+        sx={{ width: 170 }}
+        disabled={disabled}
+      />
+    </Box>
+  );
+}

react-openapi/components/fields/DefaultFieldComponents.ts

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import { FieldComponents, FieldComponentProps } from '../../types/overrides';
+import TextFieldEntry from './TextField';
+import NumberField from './NumberField';
+import BooleanField from './BooleanField';
+import DateField from './DateField';
+import EnumField from './EnumField';
+import RelationField from './RelationField';
+import ImageUploadField from './ImageUploadField';
+import FallbackField from './FallbackField';
+import DateRangeField from './DateRangeField';
+import NumberRangeField from './NumberRangeField';
+
+const WrappedImageUploadField = (props: FieldComponentProps) =>
+  React.createElement(ImageUploadField, {
+    label: props.field.label,
+    value: props.value || '',
+    onUpload: async (file: File) => {
+      const url = await props.uploadFile?.(file);
+      if (url) props.onChange(url);
+    },
+    uploading: props.uploading,
+    baseUrl: props.baseUrl || '',
+    disabled: props.disabled,
+  });
+
+export const defaultFieldComponents: FieldComponents = {
+  string: TextFieldEntry,
+  markdown: TextFieldEntry,
+  number: NumberField,
+  boolean: BooleanField,
+  date: DateField,
+  datetime: DateField,
+  enum: EnumField,
+  image: WrappedImageUploadField,
+  relation: RelationField,
+  default: FallbackField,
+  dateRange: DateRangeField,
+  numberRange: NumberRangeField,
+};

react-openapi/components/fields/EnumField.tsx

@@ -0,0 +1,24 @@
+import { FormControl, InputLabel, Select, MenuItem } from '@mui/material';
+import { getFieldOptions } from '../../utils/options';
+import { FieldComponentProps } from '../../types/overrides';
+
+export default function EnumField({ field, value, onChange, disabled }: FieldComponentProps) {
+  const options = getFieldOptions(field);
+  return (
+    <FormControl fullWidth>
+      <InputLabel>{field.label}</InputLabel>
+      <Select
+        value={value || ''}
+        label={field.label}
+        onChange={(e) => onChange(e.target.value)}
+        disabled={disabled}
+      >
+        {options.map((opt) => (
+          <MenuItem key={opt.key} value={opt.key}>
+            {opt.value}
+          </MenuItem>
+        ))}
+      </Select>
+    </FormControl>
+  );
+}

react-openapi/components/fields/FallbackField.tsx

@@ -0,0 +1,13 @@
+import { TextField } from '@mui/material';
+import { FieldComponentProps } from '../../types/overrides';
+
+export default function FallbackField({ field, value }: FieldComponentProps) {
+  return (
+    <TextField
+      fullWidth
+      label={field.label}
+      value={typeof value === 'object' ? JSON.stringify(value) : value || ''}
+      disabled
+    />
+  );
+}

react-openapi/components/fields/FormField.tsx

@@ -1,30 +1,19 @@
 import * as React from 'react';
-import {
-  TextField,
-  FormControl,
-  InputLabel,
-  Select,
-  MenuItem,
-  FormControlLabel,
-  Checkbox,
-  Typography,
-  Box,
-  Divider,
-} from '@mui/material';
 import { ResourceField } from '../../types/config';
-import { getFieldOptions } from '../../utils/options';
-import ImageUploadField from './ImageUploadField';
+import { FieldComponentProps, FieldComponents } from '../../types/overrides';
+import ObjectField from './ObjectField';
 
-interface FormFieldProps {
+export interface FormFieldProps {
   name: string;
   field: ResourceField;
   value: any;
   onChange: (val: any) => void;
   disabled?: boolean;
-  uploadFile: (file: File) => Promise<string | null>;
-  uploading: boolean;
-  baseUrl: string;
-  relationDataMap?: Record<string, any[]>; // Map of relation name to data array
+  uploadFile?: (file: File) => Promise<string | null>;
+  uploading?: boolean;
+  baseUrl?: string;
+  relationDataMap?: Record<string, any[]>;
+  components: FieldComponents;
 }
 
 export default function FormField({
@@ -37,190 +26,60 @@ export default function FormField({
   uploading,
   baseUrl,
   relationDataMap = {},
+  components,
 }: FormFieldProps) {
-  const label = field.label;
+  const fieldProps: FieldComponentProps = {
+    name,
+    field,
+    value,
+    onChange,
+    disabled,
+    baseUrl,
+    relationDataMap,
+    uploadFile,
+    uploading,
+  };
 
-  // 1. Recursive Rendering for Objects (Not Relations)
+  const childComponents = components;
+
+  // 1. Object (recursive) - requires parent FormField for recursion
   if (field.type === 'object' && field.schema && !field.relation) {
-    return (
-      <Box sx={{ ml: 2, mt: 2, p: 2, borderLeft: '2px solid #e0e0e0' }}>
-        <Typography variant="subtitle2" color="primary" gutterBottom>
-          {label}
-        </Typography>
-        <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
-          {Object.entries(field.schema).map(([subKey, subField]) => (
-            <FormField
-              key={subKey}
-              name={`${name}.${subKey}`}
-              field={subField}
-              value={value?.[subKey]}
-              onChange={(newVal) => {
-                const updated = { ...(value || {}), [subKey]: newVal };
-                onChange(updated);
-              }}
-              disabled={disabled}
-              uploadFile={uploadFile}
-              uploading={uploading}
-              baseUrl={baseUrl}
-              relationDataMap={relationDataMap}
-            />
-          ))}
-        </Box>
-      </Box>
+    const renderChild = (childProps: FieldComponentProps) => (
+      <FormField
+        name={childProps.name}
+        field={childProps.field}
+        value={childProps.value}
+        onChange={childProps.onChange}
+        disabled={childProps.disabled}
+        uploadFile={childProps.uploadFile}
+        uploading={childProps.uploading}
+        baseUrl={childProps.baseUrl}
+        relationDataMap={childProps.relationDataMap}
+        components={components}
+      />
     );
+    return <ObjectField {...fieldProps} renderField={renderChild} />;
   }
 
-  // 2. Relation Handling (Select / Multi-Select)
-  if (field.relation && relationDataMap[field.relation]) {
-    const relationData = relationDataMap[field.relation].data;
-    const isArrayRelation = field.type === 'array';
-    const options = getFieldOptions(field, relationData);
-    const keyField = field.enumOption?.key ?? 'id';
-
-    // Normalize value: API returns whole objects on GET, but form uses key strings
-    const normalizedValue = (() => {
-      if (isArrayRelation && Array.isArray(value)) {
-        return value.map((v: any) => (v != null && typeof v === 'object' ? String(v[keyField] ?? '') : String(v)));
-      }
-      if (value != null && typeof value === 'object') {
-        return String(value[keyField] ?? '');
-      }
-      return value ?? (isArrayRelation ? [] : "");
-    })();
-
-    return (
-      <FormControl fullWidth>
-        <InputLabel shrink>{label}</InputLabel>
-        <Select
-          multiple={isArrayRelation}
-          value={normalizedValue}
-          label={label}
-          displayEmpty
-          onChange={(e) => onChange(e.target.value)}
-          disabled={disabled}
-          renderValue={(selected: any) => {
-            if (isArrayRelation) {
-              return (selected as string[]).map(k => options.find(o => o.key === k)?.value ?? k).join(', ');
-            }
-            return options.find(o => o.key === selected)?.value ?? selected;
-          }}
-        >
-          {options.map((opt) => (
-            <MenuItem key={opt.key} value={opt.key}>
-              {opt.value}
-            </MenuItem>
-          ))}
-        </Select>
-      </FormControl>
-    );
-  }
-
-  // 3. Image Handling
+  // 2. Image
   if (field.type === 'image') {
-    return (
-      <ImageUploadField
-        label={label}
-        value={value}
-        onUpload={async (file: any) => {
-          const url = await uploadFile(file);
-          if (url) onChange(url);
-        }}
-        uploading={uploading}
-        baseUrl={baseUrl}
-        disabled={disabled}
-      />
-    );
+    const ImageField = components.image;
+    if (!ImageField) return null;
+    return <ImageField {...fieldProps} />;
   }
 
-  // 4. Boolean Handling
-  if (field.type === 'boolean') {
-    return (
-      <FormControlLabel
-        control={
-          <Checkbox
-            checked={!!value}
-            onChange={(e) => onChange(e.target.checked)}
-            disabled={disabled}
-          />
-        }
-        label={label}
-      />
-    );
+  // 3. Relation
+  if (field.relation && relationDataMap[field.relation]) {
+    const RelationFieldComp = components.relation;
+    if (!RelationFieldComp) return null;
+    return <RelationFieldComp {...fieldProps} />;
   }
 
-  // 5. Enum Handling
-  if (field.type === 'enum') {
-    const options = getFieldOptions(field);
-    return (
-      <FormControl fullWidth>
-        <InputLabel>{label}</InputLabel>
-        <Select
-          value={value || ''}
-          label={label}
-          onChange={(e) => onChange(e.target.value)}
-          disabled={disabled}
-        >
-          {options.map((opt) => (
-            <MenuItem key={opt.key} value={opt.key}>
-              {opt.value}
-            </MenuItem>
-          ))}
-        </Select>
-      </FormControl>
-    );
+  // 4. Lookup by field type
+  const Component = components[field.type] || components.default;
+  if (Component) {
+    return <Component {...fieldProps} />;
   }
 
-  // 6. Common Text Fields
-  if (field.type === 'datetime' || field.type === 'date') {
-    return (
-      <TextField
-        fullWidth
-        label={label}
-        type={field.type === 'datetime' ? "datetime-local" : "date"}
-        InputLabelProps={{ shrink: true }}
-        value={value ? new Date(value).toISOString().slice(0, field.type === 'datetime' ? 16 : 10) : ''}
-        onChange={(e) => onChange(e.target.value)}
-        disabled={disabled}
-        required={field.required}
-      />
-    );
-  }
-
-  if (field.type === 'markdown' || field.type === 'string') {
-    return (
-      <TextField
-        fullWidth
-        label={label}
-        value={value || ''}
-        multiline={field.type === 'markdown'}
-        rows={field.type === 'markdown' ? 4 : 1}
-        onChange={(e) => onChange(e.target.value)}
-        disabled={disabled}
-        required={field.required}
-      />
-    );
-  }
-
-  if (field.type === 'number') {
-    return (
-      <TextField
-        fullWidth
-        label={label}
-        type="number"
-        value={value === undefined || value === null ? '' : value}
-        onChange={(e) => onChange(e.target.value === '' ? '' : Number(e.target.value))}
-        disabled={disabled}
-        required={field.required}
-      />
-    );
-  }
-
-  return (
-    <TextField
-      fullWidth
-      label={label}
-      value={typeof value === 'object' ? JSON.stringify(value) : value || ''}
-      disabled
-    />
-  );
+  return null;
 }

react-openapi/components/fields/NumberField.tsx

@@ -0,0 +1,16 @@
+import { TextField as MuiTextField } from '@mui/material';
+import { FieldComponentProps } from '../../types/overrides';
+
+export default function NumberField({ field, value, onChange, disabled }: FieldComponentProps) {
+  return (
+    <MuiTextField
+      fullWidth
+      label={field.label}
+      type="number"
+      value={value === undefined || value === null ? '' : value}
+      onChange={(e) => onChange(e.target.value === '' ? '' : Number(e.target.value))}
+      disabled={disabled}
+      required={field.required}
+    />
+  );
+}

react-openapi/components/fields/NumberRangeField.tsx

@@ -0,0 +1,28 @@
+import { Box, TextField as MuiTextField } from '@mui/material';
+import { FieldComponentProps } from '../../types/overrides';
+
+export default function NumberRangeField({ value, onChange, disabled }: FieldComponentProps) {
+  const rangeVal = (value as { min?: string; max?: string }) || {};
+  return (
+    <Box sx={{ display: "flex", gap: 1 }}>
+      <MuiTextField
+        type="number"
+        placeholder="Min"
+        size="small"
+        value={rangeVal.min ?? ""}
+        onChange={(e) => onChange({ ...rangeVal, min: e.target.value || undefined })}
+        sx={{ width: 100 }}
+        disabled={disabled}
+      />
+      <MuiTextField
+        type="number"
+        placeholder="Max"
+        size="small"
+        value={rangeVal.max ?? ""}
+        onChange={(e) => onChange({ ...rangeVal, max: e.target.value || undefined })}
+        sx={{ width: 100 }}
+        disabled={disabled}
+      />
+    </Box>
+  );
+}

react-openapi/components/fields/ObjectField.tsx

@@ -0,0 +1,36 @@
+import { Box, Typography } from '@mui/material';
+import { FieldComponentProps } from '../../types/overrides';
+
+export interface ObjectFieldProps extends FieldComponentProps {
+  renderField: (props: FieldComponentProps) => React.ReactNode;
+}
+
+export default function ObjectField({ name, field, value, onChange, disabled, baseUrl, uploadFile, uploading, relationDataMap, renderField }: ObjectFieldProps) {
+  if (!field.schema) return null;
+
+  return (
+    <Box sx={{ ml: 2, mt: 2, p: 2, borderLeft: '2px solid #e0e0e0' }}>
+      <Typography variant="subtitle2" color="primary" gutterBottom>
+        {field.label}
+      </Typography>
+      <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+        {Object.entries(field.schema).map(([subKey, subField]) =>
+          renderField({
+            name: `${name}.${subKey}`,
+            field: subField,
+            value: value?.[subKey],
+            onChange: (newVal: any) => {
+              const updated = { ...(value || {}), [subKey]: newVal };
+              onChange(updated);
+            },
+            disabled,
+            baseUrl,
+            uploadFile,
+            uploading,
+            relationDataMap,
+          })
+        )}
+      </Box>
+    </Box>
+  );
+}

react-openapi/components/fields/RelationField.tsx

@@ -0,0 +1,50 @@
+import { FormControl, InputLabel, Select, MenuItem } from '@mui/material';
+import { getFieldOptions } from '../../utils/options';
+import { FieldComponentProps } from '../../types/overrides';
+
+export default function RelationField({ field, value, onChange, disabled, relationDataMap = {} }: FieldComponentProps) {
+  if (!field.relation || !relationDataMap[field.relation]) {
+    return null;
+  }
+
+  const relationData = relationDataMap[field.relation];
+  const isArrayRelation = field.type === 'array';
+  const options = getFieldOptions(field, relationData);
+  const keyField = field.enumOption?.key ?? 'id';
+
+  const normalizedValue = (() => {
+    if (isArrayRelation && Array.isArray(value)) {
+      return value.map((v: any) => (v != null && typeof v === 'object' ? String(v[keyField] ?? '') : String(v)));
+    }
+    if (value != null && typeof value === 'object') {
+      return String(value[keyField] ?? '');
+    }
+    return value ?? (isArrayRelation ? [] : "");
+  })();
+
+  return (
+    <FormControl fullWidth>
+      <InputLabel shrink>{field.label}</InputLabel>
+      <Select
+        multiple={isArrayRelation}
+        value={normalizedValue}
+        label={field.label}
+        displayEmpty
+        onChange={(e) => onChange(e.target.value)}
+        disabled={disabled}
+        renderValue={(selected: any) => {
+          if (isArrayRelation) {
+            return (selected as string[]).map(k => options.find(o => o.key === k)?.value ?? k).join(', ');
+          }
+          return options.find(o => o.key === selected)?.value ?? selected;
+        }}
+      >
+        {options.map((opt) => (
+          <MenuItem key={opt.key} value={opt.key}>
+            {opt.value}
+          </MenuItem>
+        ))}
+      </Select>
+    </FormControl>
+  );
+}

react-openapi/components/fields/TextField.tsx

@@ -0,0 +1,18 @@
+import { TextField as MuiTextField } from '@mui/material';
+import { FieldComponentProps } from '../../types/overrides';
+
+export default function TextField({ field, value, onChange, disabled }: FieldComponentProps) {
+  const isMarkdown = field.type === 'markdown';
+  return (
+    <MuiTextField
+      fullWidth
+      label={field.label}
+      value={value || ''}
+      multiline={isMarkdown}
+      rows={isMarkdown ? 4 : 1}
+      onChange={(e) => onChange(e.target.value)}
+      disabled={disabled}
+      required={field.required}
+    />
+  );
+}

react-openapi/components/fields/index.ts

@@ -0,0 +1,14 @@
+export { default as FormField } from './FormField';
+export { default as ImageUploadField } from './ImageUploadField';
+export { default as TextField } from './TextField';
+export { default as NumberField } from './NumberField';
+export { default as BooleanField } from './BooleanField';
+export { default as DateField } from './DateField';
+export { default as EnumField } from './EnumField';
+export { default as RelationField } from './RelationField';
+export { default as ObjectField } from './ObjectField';
+export { default as FallbackField } from './FallbackField';
+export { default as DateRangeField } from './DateRangeField';
+export { default as NumberRangeField } from './NumberRangeField';
+export { defaultFieldComponents } from './DefaultFieldComponents';
+export type { ObjectFieldProps } from './ObjectField';