feat(metadata): add optional editor hints for metadata

doc/2/concepts/metadatadetails/index.md

@@ -0,0 +1,252 @@
+---
+code: false
+type: page
+title: Metadata details
+description: structure of metadataDetails
+---
+
+# Metadata details
+
+Defining metadata details is a way to enhance the user experience by improving the metadata management workflow on an asset or a device. There are multiple features you can use :
+
+- [Translation](#translations-mandatory) (**_mandatory_**)
+- [Group](#group-optional) (**_optional_**)
+- [Editor hint](#editor-hint-optional) (change UI elements) (**_optional_**)
+
+## Translations (_mandatory_)
+
+This property allows to add a localized user-friendly name and description to the metadata. Those will be automatically substitued according to the user's language.
+
+**Example**
+
+```js
+{
+  metadataMappings: {
+    company: { type: "keyword" },
+  },
+  metadataDetails: {
+    locales: {
+      en: {
+        friendlyName: "Manufacturer",
+        description: "The company that manufactured the plane",
+      },
+      fr: {
+        friendlyName: "Fabricant",
+        description: "L'entreprise qui a fabriqué l'avion",
+      },
+    },
+  },
+}
+```
+
+## Group (_optional_)
+
+This property allows to group metadata together.
+
+First, create a `metadataGroups` object at the same level as `metadataDetails`, using the group's name as a key and mapping them to their localization details. Then in the `metadataDetails` object, specify the group of the metadata by using the `group` property.
+
+**Example**
+
+```js
+{
+  metadataMappings: {
+    company: { type: "keyword" },
+  },
+  metadataDetails: {
+    company: {
+      group: "companyInfo",
+    },
+  },
+  metadataGroups: {
+    companyInfo: {
+      locales: {
+        en: {
+          groupFriendlyName: "Company Information",
+          description: "All company related informations",
+        },
+        fr: {
+          groupFriendlyName: "Informations sur l'entreprise",
+          description: "Toutes les informations relatives a l'entreprise",
+        },
+      },
+    },
+  },
+}
+```
+
+## Editor hint (_optional_)
+
+This property allows to specify the frontend whether it should display a custom widget to edit the metadata, like a dropdown of values, a clock picker or date picker with or without time, make a metadata read-only, and so on.
+
+You have to set the enum type associated to the hint you want and fill the properties with your values.
+
+This is the list of the available hints:
+
+- [Read only](#read-only)
+- [Dropdown of values](#dropdown-of-values)
+- [Date/Datetime/Clock picker](#datedatetimeclock-picker)
+
+<h3 id="read-only" style="color: #e94e77">Read only <a href="#read-only" class="heading-anchor-link">#</a></h3>
+
+The read-only feature allows to prevent users to edit a metadata.
+
+**NOTE:** The readOnly property can be set with **any** Enum type.
+
+Enum type: `BASE`
+
+:warning: Set to BASE if you **only** want the readOnly property.
+
+<table>
+  <thead>
+    <tr>
+      <th style="background-color: #e94e77" colspan="4" align="center">PROPERTIES</th>
+    </tr>
+    <tr>
+      <th>Name</th>
+      <th>Type</th>
+      <th>Description</th>
+      <th>Optional</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>readOnly</td>
+      <td><code>boolean</code></td>
+      <td>It displays or not the edit button</td>
+      <td>Yes</td>
+    </tr>
+  </tbody>
+</table>
+
+**Example**
+
+```js
+{
+  metadataMappings: {
+    network: { type: "keyword" },
+  },
+  metadataDetails: {
+		network: {
+			editorHint: {
+				type: EditorHintEnum.BASE,
+				readOnly: true,
+			},
+		},
+	}
+},
+```
+
+<h3 id="dropdown-of-values" style="color: #e94e77">Dropdown of values <a href="#dropdown-of-values" class="heading-anchor-link">#</a></h3>
+
+The dropdown feature allows to display a list of values to choose in a dropdown.
+
+Enum type: `OPTION_SELECTOR`
+
+<table>
+  <thead>
+    <tr>
+      <th style="background-color: #e94e77" colspan="4" align="center">PROPERTIES</th>
+    </tr>
+    <tr>
+      <th>Name</th>
+      <th>Type</th>
+      <th>Description</th>
+      <th>Optional</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>values</td>
+      <td><code>string[] | number[] | boolean[]</code></td>
+      <td>A list that represents all the values displayed in a dropdown.</td>
+      <td>No</td>
+    </tr>
+    <tr>
+      <td>customValueAllowed</td>
+      <td><code>boolean</code></td>
+      <td>Allows users to add custom values.</td>
+      <td>Yes</td>
+    </tr>
+  </tbody>
+</table>
+
+**Example**
+
+```js
+{
+  metadataMappings: {
+    company: { type: "keyword" },
+  },
+  metadataDetails: {
+		company: {
+			editorHint: {
+				type: EditorHintEnum.OPTION_SELECTOR,
+				values: ["red", "blue"],
+				customValueAllowed: true,
+			},
+		}
+  },
+},
+```
+
+**Visual**
+
+![dropdown-of-values](./dropdown-of-values.png)
+
+<h3 id="datedatetimeclock-picker" style="color: #e94e77">Date/Datetime/Clock picker <a href="#datedatetimeclock-picker" class="heading-anchor-link">#</a></h3>
+
+This feature allows to display either a date picker with or without a time picker, or a clock picker.
+
+Enum type: `DATETIME`
+
+<table>
+  <thead>
+    <tr>
+      <th style="background-color: #e94e77" colspan="4" align="center">PROPERTIES</th>
+    </tr>
+    <tr>
+      <th>Name</th>
+      <th>Type</th>
+      <th>Description</th>
+      <th>Optional</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>date</td>
+      <td><code>boolean</code></td>
+      <td>If true, displays a date picker, otherwise displays a clock picker.</td>
+      <td>No</td>
+    </tr>
+    <tr>
+      <td>time</td>
+      <td><code>boolean</code></td>
+      <td>If `date` is true, setting this to true will add time picking to the date picker.</td>
+      <td>Yes</td>
+    </tr>
+  </tbody>
+</table>
+
+**Example**
+
+```js
+{
+  metadataMappings: {
+    date: { type: "date" },
+  },
+  metadataDetails: {
+    date: {
+			editorHint: {
+				type: EditorHintEnum.DATETIME,
+				date: true,
+				time: true,
+				customTimeZoneAllowed: true,
+			},
+    }
+  },
+},
+```
+
+**Visual**
+
+![clock-picker](./clock-picker.png)

doc/2/concepts/models/index.md

@@ -22,8 +22,11 @@ A sensor model contains the following information:
 - `decoder`: (optional) instance of a [Decoder] to normalize the data
 - `metadataMappings`: (optional) metadata mappings (See [Collection Mappings](https://docs.kuzzle.io/core/2/guides/main-concepts/data-storage/#collection-mappings))
 - `defaultMetadata`: (optional) default metadata values
-- `metadataDetails`: (optional) Metadata group and translations. You can use it to keep consistency on translations between your apps
-- `metadataGroups`: (optional) Groups list with translations for group name. You can use it to group metadatas by their concerns
+- `metadataDetails`: (optional) Translations, metadata group and editor hint.
+  - Translations: you can use it to keep consistency on translations between your apps.
+  - Group: metadata can be displayed grouped, you need to define `metadataGroups` to use it.
+  - Editor hint: it unlock functionalities depending on the metadata type you define.
+- `metadataGroups`: (optional) Map of group names to their translations. You can use it to group metadata.
 
 It is possible to create new models on the Kuzzle IoT Platform using either:
 
@@ -58,7 +61,6 @@ The API also allows to:
 - list available models `device-manager/models:listDevices`
 - get a model `device-manager/models:getDevices`
 
-
 ## Measure Model
 
 A measure model contains the following information:
@@ -77,27 +79,27 @@ It is possible to create new models on the Kuzzle IoT Platform using either:
 
 ```typescript
 await sdk.query({
-      controller: 'device-manager/models',
-      action: 'writeMeasure',
-      body: {
-        type: 'light',
-        valuesMappings: {
-          light: { type: 'integer' },
+  controller: "device-manager/models",
+  action: "writeMeasure",
+  body: {
+    type: "light",
+    valuesMappings: {
+      light: { type: "integer" },
+    },
+    valuesDetails: {
+      light: {
+        en: {
+          friendlyName: "Light intensity",
+          unit: "lux",
         },
-        valuesDetails: {
-          light: {
-            en: {
-              friendlyName: 'Light intensity',
-              unit: 'lux',
-            },
-            fr: {
-              friendlyName: 'Intensité lumineuse',
-              unit: 'lux',
-            },
-          },
+        fr: {
+          friendlyName: "Intensité lumineuse",
+          unit: "lux",
         },
       },
-    });
+    },
+  },
+});
 ```
 
 The API also allows to:
@@ -115,9 +117,12 @@ An asset model contains the following information:
 - `engineGroup`: engine group to which the model belongs.
 - `measures`: received measurements
 - `metadataMappings`: (optional) metadata mappings (See [Collection Mappings](https://docs.kuzzle.io/core/2/guides/main-concepts/data-storage/#collection-mappings))
-- `defaultMetadata`: (optional) default metadata values- 
-- `metadataDetails`: (optional) Metadata group and translations. You can use it to keep consistency on translations between your apps
-- `metadataGroups`: (optional) Groups list with translations for group name. You can use it to group metadatas by their concerns
+- `defaultMetadata`: (optional) default metadata values-
+- `metadataDetails`: (optional) Translations, metadata group and editor hint.
+  - Translations: you can use it to keep consistency on translations between your apps.
+  - Group: metadata can be displayed grouped, you need to define `metadataGroups` to use it.
+  - Editor hint: it unlock functionalities depending on the metadata type you define.
+- `metadataGroups`: (optional) Map of group names to their translations. You can use it to group metadata.
 - `tooltipModels`: (optional) Tooltip model list, each containing labels and tooltip content to be shown. You can use it to create templates that displays relevant information in dashboards
 
 It is possible to create new models on the Kuzzle IoT Platform using either:

doc/2/controllers/models/update-asset/index.md

@@ -48,7 +48,7 @@ Method: PUT
                 description: string;
               };
             };
-            readOnly?: boolean;
+            editorHint?: BaseEditorHint | OptionsSelectorDefinition | DatetimeEditorHint;
           };
       */
     },
@@ -137,8 +137,8 @@ Method: PUT
 
 - `metadataMappings`: Mappings of the metadata in Elasticsearch format
 - `defaultValues`: Default values for the metadata
-- `metadataDetails`: Metadata group and translations
-- `metadataGroups`: Groups list with translations for group name 
+- `metadataDetails`: Translations, metadata group and editor hint
+- `metadataGroups`: Groups list with translations for group name
 - `tooltipModels`: Tooltip model list, containing each labels and tooltip content to display
 - `measures`: Array of measure definition. Each item defines `type` and `name` properties for the measure.
 
@@ -164,4 +164,4 @@ Method: PUT
 
 ## Errors
 
-Updating an asset with metadata mappings can cause conflicts, in this case a [ MappingsConflictsError ](../../../errors/mappings-conflicts/index.md) will be thrown with the HTTP code **409**.
+Updating an asset with metadata mappings can cause conflicts, in this case a [ MappingsConflictsError ](../../../errors/mappings-conflicts/index.md) will be thrown with the HTTP code **409**.

doc/2/controllers/models/write-asset/index.md

@@ -40,7 +40,7 @@ Method: POST
     },
     "metadataDetails": {
       /*
-        Metadata details including tanslations and group.
+        Metadata details including tanslations, group and editor hint.
           [name: string]: {
             group?: string;
             locales: {
@@ -49,7 +49,7 @@ Method: POST
                 description: string;
               };
             };
-            readOnly?: boolean;
+            editorHint?: BaseEditorHint | OptionsSelectorDefinition | DatetimeEditorHint;
           };
       */
     },
@@ -133,8 +133,8 @@ Method: POST
 - `model`: Asset model name
 - `metadataMappings`: Mappings of the metadata in Elasticsearch format
 - `defaultValues`: Default values for the metadata
-- `metadataDetails`: Metadata group and translations
-- `metadataGroups`: Groups list with translations for group name 
+- `metadataDetails`: Translations, metadata group, and editor hint (See [ MetadataDetails ](../../../concepts/metadatadetails/index.md))
+- `metadataGroups`: Groups list with translations for group name
 - `tooltipModels`: Tooltip model list, containing each labels and tooltip content to display
 - `measures`: Array of measure definition. Each item define a `type` and `name` properties for the measure.
 
@@ -160,4 +160,4 @@ Method: POST
 
 ## Errors
 
-Writing an asset with metadata mappings can cause conflicts, in this case a [ MappingsConflictsError ](../../../errors/mappings-conflicts/index.md) will be thrown with the HTTP code **409**.
+Writing an asset with metadata mappings can cause conflicts, in this case a [ MappingsConflictsError ](../../../errors/mappings-conflicts/index.md) will be thrown with the HTTP code **409**.