From 7024a6c1c8df41d6b861fcd333a2f8e150853ff2 Mon Sep 17 00:00:00 2001
From: Tomas Kikutis <t.kikutis@gmail.com>
Date: Wed, 6 Nov 2024 10:25:21 +0100
Subject: [PATCH] Improve documentation of generic fields (#4651)

---
 .../apps/authoring-react/fields/attachments/index.tsx | 10 ++++++++++
 scripts/apps/authoring-react/fields/date/index.tsx    |  1 +
 .../apps/authoring-react/fields/dateline/index.tsx    |  1 +
 scripts/apps/authoring-react/fields/dropdown/index.ts |  1 +
 .../apps/authoring-react/fields/duration/index.tsx    |  1 +
 scripts/apps/authoring-react/fields/editor3/index.tsx |  1 +
 scripts/apps/authoring-react/fields/embed/index.tsx   |  1 +
 .../authoring-react/fields/linked-items/index.tsx     |  1 +
 scripts/apps/authoring-react/fields/media/index.tsx   |  1 +
 .../authoring-react/fields/package-items/index.tsx    | 11 +++++++++++
 .../apps/authoring-react/fields/tag-input/index.tsx   |  1 +
 scripts/apps/authoring-react/fields/time/index.tsx    |  1 +
 scripts/apps/authoring-react/fields/urls/index.tsx    |  1 +
 .../authoring/authoring-custom-field.spec.tsx         |  1 +
 .../controllers/VocabularyEditController.tsx          |  2 +-
 scripts/core/superdesk-api.d.ts                       |  7 +++++--
 scripts/extensions/booleanField/src/extension.tsx     |  1 +
 .../src/authoring-fields/subitems/index.tsx           |  2 +-
 scripts/extensions/datetimeField/src/extension.tsx    |  1 +
 .../extensions/predefinedTextField/src/extension.tsx  |  1 +
 20 files changed, 43 insertions(+), 4 deletions(-)

diff --git a/scripts/apps/authoring-react/fields/attachments/index.tsx b/scripts/apps/authoring-react/fields/attachments/index.tsx
index e003638bbf..1c7e772cb6 100644
--- a/scripts/apps/authoring-react/fields/attachments/index.tsx
+++ b/scripts/apps/authoring-react/fields/attachments/index.tsx
@@ -28,6 +28,16 @@ export const ATTACHMENTS_WIDGET_ID = 'attachments';
 export function getAttachmentsField(): IAttachmentsField {
     const field: IAttachmentsField = {
         id: ATTACHMENTS_FIELD_ID,
+
+        /**
+         * Not generic due to:
+         * - having a hardcoded fieldId in a side-widget
+         *
+         * Could be made generic by getting rid of side-widget
+         * or changing side-widget to support multiple fields.
+         */
+        generic: false,
+
         label: gettext('Attachments (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,
diff --git a/scripts/apps/authoring-react/fields/date/index.tsx b/scripts/apps/authoring-react/fields/date/index.tsx
index 19e22ff266..665e45324b 100644
--- a/scripts/apps/authoring-react/fields/date/index.tsx
+++ b/scripts/apps/authoring-react/fields/date/index.tsx
@@ -13,6 +13,7 @@ export function getDateField()
 : ICustomFieldType<IDateValueOperational, IDateValueStorage, IDateFieldConfig, IDateUserPreferences> {
     const field: ICustomFieldType<IDateValueOperational, IDateValueStorage, IDateFieldConfig, IDateUserPreferences> = {
         id: DATE_FIELD_ID,
+        generic: true,
         label: gettext('Date (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,
diff --git a/scripts/apps/authoring-react/fields/dateline/index.tsx b/scripts/apps/authoring-react/fields/dateline/index.tsx
index f65bbc483f..7befed567e 100644
--- a/scripts/apps/authoring-react/fields/dateline/index.tsx
+++ b/scripts/apps/authoring-react/fields/dateline/index.tsx
@@ -23,6 +23,7 @@ export function getDatelineField()
 : DatelineFieldType {
     const field: DatelineFieldType = {
         id: DATELINE_FIELD_ID,
+        generic: true,
         label: gettext('Dateline (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,
diff --git a/scripts/apps/authoring-react/fields/dropdown/index.ts b/scripts/apps/authoring-react/fields/dropdown/index.ts
index 92cc613e45..ccd473be7f 100644
--- a/scripts/apps/authoring-react/fields/dropdown/index.ts
+++ b/scripts/apps/authoring-react/fields/dropdown/index.ts
@@ -17,6 +17,7 @@ export const DROPDOWN_FIELD_ID = 'dropdown';
 export function getDropdownField(): ICustomFieldType<IDropdownValue, IDropdownValue, IDropdownConfig, never> {
     const field: ICustomFieldType<IDropdownValue, IDropdownValue, IDropdownConfig, never> = {
         id: 'dropdown',
+        generic: true,
         label: gettext('Dropdown (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,
diff --git a/scripts/apps/authoring-react/fields/duration/index.tsx b/scripts/apps/authoring-react/fields/duration/index.tsx
index 1730d2536d..deb570b623 100644
--- a/scripts/apps/authoring-react/fields/duration/index.tsx
+++ b/scripts/apps/authoring-react/fields/duration/index.tsx
@@ -16,6 +16,7 @@ export function geDurationField()
 : ICustomFieldType<IDurationValueOperational, IDurationValueStorage, IDurationFieldConfig, IDurationUserPreferences> {
     const field: ReturnType<typeof geDurationField> = {
         id: DURATION_FIELD_ID,
+        generic: true,
         label: gettext('Duration (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,
diff --git a/scripts/apps/authoring-react/fields/editor3/index.tsx b/scripts/apps/authoring-react/fields/editor3/index.tsx
index a31f661b07..3d0b19f885 100644
--- a/scripts/apps/authoring-react/fields/editor3/index.tsx
+++ b/scripts/apps/authoring-react/fields/editor3/index.tsx
@@ -53,6 +53,7 @@ export function getEditor3Field()
 : ICustomFieldType<IEditor3ValueOperational, IEditor3ValueStorage, IEditor3Config, IUserPreferences> {
     const field: ICustomFieldType<IEditor3ValueOperational, IEditor3ValueStorage, IEditor3Config, IUserPreferences> = {
         id: EDITOR_3_FIELD_TYPE,
+        generic: true,
         label: gettext('Editor3 (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,
diff --git a/scripts/apps/authoring-react/fields/embed/index.tsx b/scripts/apps/authoring-react/fields/embed/index.tsx
index e8da208afd..11ce05b143 100644
--- a/scripts/apps/authoring-react/fields/embed/index.tsx
+++ b/scripts/apps/authoring-react/fields/embed/index.tsx
@@ -14,6 +14,7 @@ export function getEmbedField()
 : ICustomFieldType<IEmbedValueOperational, IEmbedValueStorage, IEmbedConfig, IEmbedUserPreferences> {
     const field: ReturnType<typeof getEmbedField> = {
         id: 'embed',
+        generic: true,
         label: gettext('Embed (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,
diff --git a/scripts/apps/authoring-react/fields/linked-items/index.tsx b/scripts/apps/authoring-react/fields/linked-items/index.tsx
index 1de70676bf..81084574e4 100644
--- a/scripts/apps/authoring-react/fields/linked-items/index.tsx
+++ b/scripts/apps/authoring-react/fields/linked-items/index.tsx
@@ -24,6 +24,7 @@ export const LINKED_ITEMS_FIELD_TYPE = 'linked-items';
 export function getLinkedItemsField(): ILinkedItemsField {
     const field: ILinkedItemsField = {
         id: LINKED_ITEMS_FIELD_TYPE,
+        generic: true,
         label: gettext('Linked items (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,
diff --git a/scripts/apps/authoring-react/fields/media/index.tsx b/scripts/apps/authoring-react/fields/media/index.tsx
index 44aeea9bc8..6cfe50e333 100644
--- a/scripts/apps/authoring-react/fields/media/index.tsx
+++ b/scripts/apps/authoring-react/fields/media/index.tsx
@@ -17,6 +17,7 @@ export function getMediaField()
 : ICustomFieldType<IMediaValueOperational, IMediaValueStorage, IMediaConfig, IMediaUserPreferences> {
     const field: ReturnType<typeof getMediaField> = {
         id: MEDIA_FIELD_ID,
+        generic: true,
         label: gettext('Media (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,
diff --git a/scripts/apps/authoring-react/fields/package-items/index.tsx b/scripts/apps/authoring-react/fields/package-items/index.tsx
index e3255649c4..889bbb61c5 100644
--- a/scripts/apps/authoring-react/fields/package-items/index.tsx
+++ b/scripts/apps/authoring-react/fields/package-items/index.tsx
@@ -22,6 +22,17 @@ export const PACKAGE_ITEMS_FIELD_ID = 'package_items';
 export function getArticlesInPackageField(): IPackageItemsField {
     const field: IPackageItemsField = {
         id: PACKAGE_ITEMS_FIELD_ID,
+
+        /**
+         * 'linked_items' is a very similar field, but generic.
+         * It appears this field type was implemented to save time in comparison to
+         * creating configuration options for linked_items.
+         *
+         * It looks though there would only be 1 config needed,
+         * so I think we should do the config and drop this one in the future.
+         */
+        generic: false,
+
         label: gettext('Package items (authoring-react)'),
 
         editorComponent: Editor,
diff --git a/scripts/apps/authoring-react/fields/tag-input/index.tsx b/scripts/apps/authoring-react/fields/tag-input/index.tsx
index 31877cad72..8f07ed72ab 100644
--- a/scripts/apps/authoring-react/fields/tag-input/index.tsx
+++ b/scripts/apps/authoring-react/fields/tag-input/index.tsx
@@ -22,6 +22,7 @@ type TagInputFieldType = ICustomFieldType<
 export function getTagInputField(): TagInputFieldType {
     const field: TagInputFieldType = {
         id: TAG_INPUT_FIELD_ID,
+        generic: true,
         label: gettext('Tag-input (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,
diff --git a/scripts/apps/authoring-react/fields/time/index.tsx b/scripts/apps/authoring-react/fields/time/index.tsx
index 3a103e0eed..a4a9504f8f 100644
--- a/scripts/apps/authoring-react/fields/time/index.tsx
+++ b/scripts/apps/authoring-react/fields/time/index.tsx
@@ -16,6 +16,7 @@ export function getTimeField()
 : ICustomFieldType<ITimeValueOperational, ITimeValueStorage, ITimeFieldConfig, ITimeUserPreferences> {
     const field: ICustomFieldType<ITimeValueOperational, ITimeValueStorage, ITimeFieldConfig, ITimeUserPreferences> = {
         id: TIME_FIELD_ID,
+        generic: true,
         label: gettext('Time (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,
diff --git a/scripts/apps/authoring-react/fields/urls/index.tsx b/scripts/apps/authoring-react/fields/urls/index.tsx
index d3559a4b06..c5d864f34d 100644
--- a/scripts/apps/authoring-react/fields/urls/index.tsx
+++ b/scripts/apps/authoring-react/fields/urls/index.tsx
@@ -16,6 +16,7 @@ export function getUrlsField()
 : ICustomFieldType<IUrlsFieldValueOperational, IUrlsFieldValueStorage, IUrlsFieldConfig, IUrlsFieldUserPreferences> {
     const field: ReturnType<typeof getUrlsField> = {
         id: URL_FIELD_ID,
+        generic: true,
         label: gettext('Urls (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,
diff --git a/scripts/apps/authoring/authoring/authoring-custom-field.spec.tsx b/scripts/apps/authoring/authoring/authoring-custom-field.spec.tsx
index 2fb661f956..8a1d619fde 100644
--- a/scripts/apps/authoring/authoring/authoring-custom-field.spec.tsx
+++ b/scripts/apps/authoring/authoring/authoring-custom-field.spec.tsx
@@ -41,6 +41,7 @@ class TestEditorComponent extends React.PureComponent<IEditorComponentProps<stri
 
 const customField: ICustomFieldType<string, string, string, never> = {
     id: 'test-custom-authoring-field',
+    generic: true,
     label: 'Test Field',
     editorComponent: TestEditorComponent,
     previewComponent: () => null,
diff --git a/scripts/apps/vocabularies/controllers/VocabularyEditController.tsx b/scripts/apps/vocabularies/controllers/VocabularyEditController.tsx
index c25afa50d2..3521e4eb8f 100644
--- a/scripts/apps/vocabularies/controllers/VocabularyEditController.tsx
+++ b/scripts/apps/vocabularies/controllers/VocabularyEditController.tsx
@@ -311,7 +311,7 @@ export function VocabularyEditController(
 
     const fields = getFields();
 
-    $scope.customFieldTypes = Object.keys(fields).filter((id) => fields[id].private !== true).map((id) => ({
+    $scope.customFieldTypes = Object.keys(fields).filter((id) => fields[id].generic === true).map((id) => ({
         id: id,
         label: fields[id].label,
     }));
diff --git a/scripts/core/superdesk-api.d.ts b/scripts/core/superdesk-api.d.ts
index a303c51c82..3c02015920 100644
--- a/scripts/core/superdesk-api.d.ts
+++ b/scripts/core/superdesk-api.d.ts
@@ -3700,9 +3700,12 @@ declare module 'superdesk-api' {
         previewComponent: React.ComponentType<IPreviewComponentProps<IValueOperational, IConfig>>;
 
         /**
-         * Allows for the field to be hidden from custom field type config
+         * Field types should be made generic when possible.
+         * Making field types generic means multiple fields of the same type can be enabled in the same editing view.
+         * Generic fields will be available for adding to content profile via user interface (settings).
          */
-        private?: boolean;
+        generic: boolean;
+
         /**
          * Must return `true` if not empty.
          */
diff --git a/scripts/extensions/booleanField/src/extension.tsx b/scripts/extensions/booleanField/src/extension.tsx
index 943e8b7ef6..4e7d6306cc 100644
--- a/scripts/extensions/booleanField/src/extension.tsx
+++ b/scripts/extensions/booleanField/src/extension.tsx
@@ -13,6 +13,7 @@ const {gettext} = superdesk.localization;
 
 const booleanField: ICustomFieldType<IValueOperational, IValueStorage, ICommonFieldConfig, IUserPreferences> = {
     id: 'boolean',
+    generic: true,
     label: gettext('Boolean'),
     editorComponent: Editor,
     previewComponent: Preview,
diff --git a/scripts/extensions/broadcasting/src/authoring-fields/subitems/index.tsx b/scripts/extensions/broadcasting/src/authoring-fields/subitems/index.tsx
index db51b12c17..4154b3c343 100644
--- a/scripts/extensions/broadcasting/src/authoring-fields/subitems/index.tsx
+++ b/scripts/extensions/broadcasting/src/authoring-fields/subitems/index.tsx
@@ -31,7 +31,7 @@ export function getSubItemsField(): ISubItemsFieldType {
         editorComponent: Editor,
         previewComponent: Preview,
 
-        private: true,
+        generic: false,
         hasValue: (valueOperational) => valueOperational != null && Object.keys(valueOperational).length > 0,
         getEmptyValue: () => [],
 
diff --git a/scripts/extensions/datetimeField/src/extension.tsx b/scripts/extensions/datetimeField/src/extension.tsx
index 04fb181d66..1b7a7a6089 100644
--- a/scripts/extensions/datetimeField/src/extension.tsx
+++ b/scripts/extensions/datetimeField/src/extension.tsx
@@ -25,6 +25,7 @@ function onTemplateCreate(_value: string, config: IConfig) {
 const datetimeField: ICustomFieldType<IValueOperational, IValueStorage, IConfig, IUserPreferences> = {
     id: 'datetime',
     label: gettext('Datetime'),
+    generic: true,
     editorComponent: Editor,
     previewComponent: Preview,
     configComponent: Config,
diff --git a/scripts/extensions/predefinedTextField/src/extension.tsx b/scripts/extensions/predefinedTextField/src/extension.tsx
index d27aaa5600..fdb9f91b1c 100644
--- a/scripts/extensions/predefinedTextField/src/extension.tsx
+++ b/scripts/extensions/predefinedTextField/src/extension.tsx
@@ -10,6 +10,7 @@ const {gettext} = superdesk.localization;
 const predefinedField: ICustomFieldType<IValueOperational, IValueStorage, IConfig, IUserPreferences> = {
     id: 'predefined-text',
     label: gettext('Predefined text field'),
+    generic: true,
     editorComponent: Editor,
     previewComponent: Preview,
     configComponent: Config,