add dynamic enum Tutorial

closes eclipsesource#270

content/docs/tutorial/dynamic-enum.mdx

@@ -0,0 +1,260 @@
+---
+id: dynamic-enum
+title: Dynamic Renderers
+description: This tutorial describes how to create a dynamic enum
+---
+
+import { WithRegionRenderer } from '../../../src/components/docs/tutorials/dynamic-enum';
+
+
+In this tutorial, you will learned how to handle dynamic data in React using [custom renderers](./custom-renderers), React Context, and the `useJsonForms` hook.
+This approach allows you to build flexible and interactive forms that adapt to user selections and API responses.
+
+### Scenario
+
+Imagine a form where users need to provide their location by selecting a country, a region and a city.
+The options for countries and regions are fetched from an API.
+The available regions depend on the selected country.
+To tacks those requirements. we'll create custom renderers for the country and region.
+The example is also implemented in the [react-seed](https://github.com/eclipsesource/jsonforms-react-seed) app.
+
+<WithRegionRenderer />
+
+
+#### Schema
+
+To begin, let's introduce the corresponding JSON schema.
+We have created an object with properties for country, region, and city.
+In our example, the schema also includes a property `x-url`, which specifies the entry point of the corresponding API.
+Both `country` and `region` have a property `endpoint`, indicating the endpoint from which the data should be fetched.
+Additionally, they have a field specifying which fields depend on the input.
+In the case of the `country` field, the `region` and `city` fields depend on it and will get reset, if the value of the `country` changes.
+The `city` field, in turn, is dependent on the `region` field.
+
+```js
+{
+  "type": "object",
+  "x-url": "www.api.com",
+  "properties": {
+    "country": {
+      "type": "string",
+      "x-endpoint": "countries",
+      "dependencies": ["region", "city"]
+    },
+    "region": {
+      "type": "string",
+      "x-endpoint": "regions",
+      "dependencies": ["city"]
+    },
+    "city": {
+      "type": "string"
+    }
+  }
+}
+```
+
+
+### Accessing Schema Data and Initialising the React Context
+
+In this step we will access the data from the schema and initialize the react context.
+
+#### Accessing the API URL from Schema
+
+To access the URL defined from the schema we can simply access  the `x-url` attribute.
+
+```js
+const url = schema['x-url'];
+```
+
+#### Initializing the React Context
+
+Now that we have access to the API URL, we can use React Context to make this data available across our renderers.
+React Context allows you to share data globally within your application, enabling components deep in the component tree to access data without needing to pass properties through all parent elements.
+To set up the React Context for your API service, create it in your application as follows:
+
+```js
+export const APIContext = React.createContext(new API(url));
+
+const App = () =>{
+
+  ...
+  <JsonForms/>
+}
+```
+
+### The Country Renderer
+
+The core of the country renderer is a dropdown, we can reuse the MaterialEnumControl from the material-renderer set.
+To reuse material renderers, the Unwrapped renderers must be used. (more information regarding reusing renderers can be seen [here](./custom-renderers#reusing-existing-controls))
+
+```js
+import { Unwrapped, WithOptionLabel } from '@jsonforms/material-renderers';
+
+const { MaterialEnumControl } = Unwrapped;
+
+...
+
+<MaterialEnumControl
+      {...props}
+      options = {options}
+      handleChange = {handleChange}
+    />
+...
+```
+
+With the `MaterialEnumControl`in place the main question remains how to set the `options` and the `handleChange` attribute.
+To determine the available options, we need to access the API.
+And to implement the `handleChange` function, we need access to the `dependened` field in the schema.
+
+#### Accessing the API context
+
+
+Access the API service using the context:
+
+```js
+const api = React.useContext(APIContext);
+```
+
+Changing the context's value will trigger a re-render of components that use it, making it a powerful tool for managing dynamic data.
+
+#### Accessing Schema Data
+
+The `endpoint` and `dependent` fields can be obtained from the schema object provided to the custom renderer via JSON Forms.
+Since these fields are not part of the standard JSON schema type in JSON Forms, we must add them to the schema´s interface and access them as follows:
+
+```js
+type JsonSchemaWithDependenciesAndEndpoint = JsonSchema & {
+  dependened: string[];
+  endpoint: string;
+};
+export const Country = (
+  props: ControlProps & OwnPropsOfEnum & WithOptionLabel & TranslateProps
+) => {
+...
+
+  const schema = props.schema as JsonSchemaWithDependenciesAndEndpoint;
+  const endponit = schema.endpoint;
+  const dependened = schema.dependened
+...
+}
+```
+
+#### The Country Renderer
+
+The country renderer uses the `APIContext` to query the API and fetch the available options.
+We utilize the `useEffect` hook to reload new options, if API changes.
+While waiting for the API response, we set the available options to empty and display a loading spinner.
+In the `handleChange` function, we set the new selected value and reset all dependent fields;
+When changing the country, both the region and city will be reset to `undefined`.
+
+```js
+import { Unwrapped, WithOptionLabel } from '@jsonforms/material-renderers';
+
+const { MaterialEnumControl } = Unwrapped;
+
+type JsonSchemaWithDependenciesAndEndpoint = JsonSchema & {
+  dependened: string[];
+  endpoint: string;
+};
+
+export const Country = (
+  props: ControlProps & OwnPropsOfEnum & WithOptionLabel & TranslateProps
+) => {
+  const { handleChange } = props;
+  const [options, setOptions] = useState<string[]>([]);
+  const api = React.useContext(APIContext);
+  const schema = props.schema as JsonSchemaWithDependenciesAndEndpoint;
+
+  const endponit = schema.endpoint;
+  const dependened: string[] = schema.dependened ? schema.dependened : [];
+
+  useEffect(() => {
+    setOptions([]);
+    api.get(endponit).then((result) => {
+      setOptions(result);
+    });
+  }, [api, endponit]);
+
+  if (options.length === 0) {
+    return <CircularProgress />;
+  }
+
+  return (
+    <MaterialEnumControl
+      {...props}
+      handleChange={(path: string, value: any) => {
+        handleChange(path, value);
+        dependened.forEach((path) => {
+          handleChange(path, undefined);
+        });
+      }}
+      options={options.map((option) => {
+        return { label: option, value: option };
+      })}
+    />
+  );
+};
+```
+
+Now all that´s left to do is to [create a tester](./custom-renderers#2-create-a-tester) and [register](./custom-renderers#3-register-the-renderer) the new custom renderer in our application.
+
+### The Region Renderer
+
+The region renderer can be implemented similarly to the country renderer.
+It also accesses the API via the context and includes `endpoint` and `dependent` fields defined in its schema.
+However, the options, on the other hand, are also dependent on the selected country.
+JSON Forms provides the `useJsonForms` hook, allowing you to access form data and trigger component rerenders when the data changes.
+Let's use this hook in our region renderer to access the selected country:
+
+```js
+import { Unwrapped, WithOptionLabel } from '@jsonforms/material-renderers';
+const { MaterialEnumControl } = Unwrapped;
+
+type JsonSchemaWithDependenciesAndEndpont = JsonSchema & {
+  dependened: string[];
+  endpoint: string;
+};
+
+export const Region = (
+  props: ControlProps & OwnPropsOfEnum & WithOptionLabel & TranslateProps
+) => {
+  const schema = props.schema as JsonSchemaWithDependenciesAndEndpont;
+  const { handleChange } = props;
+  const [options, setOptions] = useState<string[]>([]);
+  const api = React.useContext(APIContext);
+  const country = useJsonForms().core?.data.country;
+  const [previousCountry, setPreviousCountry] = useState<String>();
+
+  const endponit = schema.endpoint;
+  const dependened: string[] = schema.dependened ? schema.dependened : [];
+
+  if (previousCountry !== country) {
+    setOptions([]);
+    setPreviousCountry(country);
+    api.get(endponit + '/' + country).then((result) => {
+      setOptions(result);
+    });
+  }
+
+  if (options.length === 0 && country !== undefined) {
+    return <CircularProgress />;
+  }
+
+  return (
+    <MaterialEnumControl
+      {...props}
+      handleChange={(path: string, value: any) => {
+        handleChange(path, value);
+        dependened.forEach((path) => {
+          handleChange(path, undefined);
+        });
+      }}
+      options={options.map((option) => {
+        return { label: option, value: option };
+      })}
+    />
+  );
+};
+```
+Again we need to create a [create a tester](./custom-renderers#2-create-a-tester) and [register](./custom-renderers#3-register-the-renderer) the new custom renderer.
+A running example of the scenario can also be seen at the [react-seed](https://github.com/eclipsesource/jsonforms-react-seed) app.

docusaurus.config.js

@@ -225,6 +225,10 @@ module.exports = {
             to: '/docs/tutorial/custom-renderers',
             from: '/docs/custom-renderers',
           },
+          {
+            to: '/docs/tutorial/dynamic-enum',
+            from: '/docs/dynamic-enum',
+          },
           {
             to: '/docs/tutorial/multiple-forms',
             from: '/docs/multiple-forms',

src/components/common/api.ts

@@ -0,0 +1,92 @@
+export class API {
+  private url: string;
+
+  constructor(url: string) {
+    this.url = url;
+  }
+
+  async get(endpoint: string): Promise<string[]> {
+    switch (this.url + '/' + endpoint) {
+      case 'www.api.com/regions/Germany':
+        return germanStates;
+      case 'www.api.com/regions/US':
+        return usStates;
+      case 'www.api.com/countries':
+        return ['Germany', 'US'];
+      default:
+        return [];
+    }
+  }
+}
+
+const germanStates = [
+  'Berlin',
+  'Bayern',
+  'Niedersachsen',
+  'Baden-Württemberg',
+  'Rheinland-Pfalz',
+  'Sachsen',
+  'Thüringen',
+  'Hessen',
+  'Nordrhein-Westfalen',
+  'Sachsen-Anhalt',
+  'Brandenburg',
+  'Mecklenburg-Vorpommern',
+  'Hamburg',
+  'Schleswig-Holstein',
+  'Saarland',
+  'Bremen',
+];
+
+const usStates = [
+  'Alabama',
+  'Alaska',
+  'Arizona',
+  'Arkansas',
+  'California',
+  'Colorado',
+  'Connecticut',
+  'Delaware',
+  'Florida',
+  'Georgia',
+  'Hawaii',
+  'Idaho',
+  'Illinois',
+  'Indiana',
+  'Iowa',
+  'Kansas',
+  'Kentucky',
+  'Louisiana',
+  'Maine',
+  'Maryland',
+  'Massachusetts',
+  'Michigan',
+  'Minnesota',
+  'Mississippi',
+  'Missouri',
+  'Montana',
+  'Nebraska',
+  'Nevada',
+  'New Hampshire',
+  'New Jersey',
+  'New Mexico',
+  'New York',
+  'North Carolina',
+  'North Dakota',
+  'Ohio',
+  'Oklahoma',
+  'Oregon',
+  'Pennsylvania',
+  'Rhode Island',
+  'South Carolina',
+  'South Dakota',
+  'Tennessee',
+  'Texas',
+  'Utah',
+  'Vermont',
+  'Virginia',
+  'Washington',
+  'West Virginia',
+  'Wisconsin',
+  'Wyoming',
+];