@dotcms/uve 1.2.0 → 1.2.1-next.2

package/index.cjs.js

@@ -1,10 +1,596 @@
 'use strict';
 
 var _public = require('./public.cjs.js');
-require('@dotcms/types');
+var types = require('@dotcms/types');
 require('@dotcms/types/internal');
 
+/**
+ * Normalizes a field definition into the schema format expected by UVE.
+ *
+ * Converts developer-friendly field definitions into a normalized structure where
+ * all type-specific configuration properties are moved into a `config` object.
+ * This transformation ensures consistency in the schema format sent to UVE.
+ *
+ * **Field Type Handling:**
+ * - **Input fields**: Extracts `inputType`, `placeholder`, and `defaultValue` into config
+ * - **Dropdown fields**: Normalizes options (strings become `{ label, value }` objects),
+ *   extracts `placeholder` and `defaultValue` into config
+ * - **Radio fields**: Normalizes options (preserves image properties like `imageURL`, `width`, `height`),
+ *   extracts `defaultValue` into config
+ * - **Checkbox group fields**: Normalizes options and extracts `defaultValue` (as Record<string, boolean>) into config
+ *
+ * @experimental This method is experimental and may be subject to change.
+ *
+ * @param field - The field definition to normalize. Must be one of: input, dropdown, radio, or checkboxGroup
+ * @returns The normalized field schema with type, label, and config properties ready to be sent to UVE
+ *
+ * @example
+ * ```typescript
+ * // Input field normalization
+ * normalizeField({
+ *   type: 'input',
+ *   label: 'Font Size',
+ *   inputType: 'number',
+ *   defaultValue: 16,
+ *   placeholder: 'Enter size'
+ * })
+ * // Returns: {
+ * //   type: 'input',
+ * //   label: 'Font Size',
+ * //   config: { inputType: 'number', defaultValue: 16, placeholder: 'Enter size' }
+ * // }
+ *
+ * // Dropdown field with string options normalization
+ * normalizeField({
+ *   type: 'dropdown',
+ *   label: 'Font Family',
+ *   options: ['Arial', 'Helvetica']
+ * })
+ * // Returns: {
+ * //   type: 'dropdown',
+ * //   label: 'Font Family',
+ * //   config: { options: [{ label: 'Arial', value: 'Arial' }, { label: 'Helvetica', value: 'Helvetica' }] }
+ * // }
+ * ```
+ */
+function normalizeField(field) {
+  const base = {
+    type: field.type,
+    label: field.label
+  };
+  const config = {};
+  // Handle type-specific properties
+  if (field.type === 'input') {
+    config.inputType = field.inputType;
+    config.placeholder = field.placeholder;
+    config.defaultValue = field.defaultValue;
+  }
+  if (field.type === 'dropdown' || field.type === 'radio') {
+    // Normalize options to consistent format
+    config.options = field.options.map(opt => typeof opt === 'string' ? {
+      label: opt,
+      value: opt
+    } : opt);
+    config.placeholder = field.type === 'dropdown' ? field.placeholder : undefined;
+    config.defaultValue = field.defaultValue;
+    // Handle radio-specific properties
+    if (field.type === 'radio') {
+      config.columns = field.columns;
+    }
+  }
+  if (field.type === 'checkboxGroup') {
+    // Normalize options to consistent format
+    config.options = field.options.map(opt => typeof opt === 'string' ? {
+      label: opt,
+      value: opt
+    } : opt);
+    config.defaultValue = field.defaultValue;
+  }
+  return {
+    ...base,
+    config
+  };
+}
+/**
+ * Normalizes a section definition into the schema format expected by UVE.
+ *
+ * Converts a section with a flat array of fields into the normalized schema format
+ * where fields are organized as a multi-dimensional array (array of column arrays).
+ * Currently, all sections are normalized to a single-column layout structure.
+ *
+ * **Normalization Process:**
+ * 1. Normalizes each field in the section using `normalizeField`
+ * 2. Wraps the normalized fields array in an outer array to create the column structure
+ * 3. Preserves the section title
+ *
+ * The output format always uses a multi-dimensional array structure (`fields: StyleEditorFieldSchema[][]`),
+ * even for single-column layouts, ensuring consistency in the UVE schema format.
+ *
+ * @experimental This method is experimental and may be subject to change.
+ *
+ * @param section - The section definition to normalize, containing a title and array of fields
+ * @param section.title - The section title displayed to users
+ * @param section.fields - Array of field definitions to normalize
+ * @returns The normalized section schema with fields organized as a single-column array structure
+ *
+ * @example
+ * ```typescript
+ * normalizeSection({
+ *   title: 'Typography',
+ *   fields: [
+ *     { type: 'input', label: 'Font Size', inputType: 'number' },
+ *     { type: 'dropdown', label: 'Font Family', options: ['Arial'] }
+ *   ]
+ * })
+ * // Returns: {
+ * //   title: 'Typography',
+ * //   fields: [
+ * //     [
+ * //       { type: 'input', label: 'Font Size', config: { inputType: 'number' } },
+ * //       { type: 'dropdown', label: 'Font Family', config: { options: [...] } }
+ * //     ]
+ * //   ]
+ * // }
+ * ```
+ */
+function normalizeSection(section) {
+  // Determine if fields is multi-column or single column
+  const normalizedFields = section.fields.map(normalizeField);
+  return {
+    title: section.title,
+    fields: normalizedFields
+  };
+}
+/**
+ * Normalizes a complete form definition into the schema format expected by UVE.
+ *
+ * This is the main entry point for converting a developer-friendly form definition
+ * into the normalized schema structure that UVE (Universal Visual Editor) can consume.
+ * The normalization process transforms the entire form hierarchy:
+ *
+ * **Normalization Process:**
+ * 1. Preserves the `contentType` identifier
+ * 2. Processes each section using `normalizeSection`, which:
+ *    - Normalizes all fields in the section using `normalizeField`
+ *    - Organizes fields into the required multi-dimensional array structure
+ * 3. Returns a fully normalized schema with consistent structure across all sections
+ *
+ * The resulting schema has all field-specific properties moved into `config` objects
+ * and all sections using the consistent single-column array structure, regardless
+ * of the input format.
+ *
+ * @experimental This method is experimental and may be subject to change.
+ *
+ * @param form - The complete form definition to normalize
+ * @param form.contentType - The content type identifier this form is associated with
+ * @param form.sections - Array of section definitions, each containing a title and fields
+ * @returns The normalized form schema ready to be sent to UVE, with all fields and sections normalized
+ *
+ * @example
+ * ```typescript
+ * const schema = normalizeForm({
+ *   contentType: 'my-content-type',
+ *   sections: [
+ *     {
+ *       title: 'Typography',
+ *       fields: [
+ *         { type: 'input', label: 'Font Size', inputType: 'number', defaultValue: 16 },
+ *         { type: 'dropdown', label: 'Font Family', options: ['Arial', 'Helvetica'] }
+ *       ]
+ *     },
+ *     {
+ *       title: 'Colors',
+ *       fields: [
+ *         { type: 'input', label: 'Primary Color', inputType: 'text', defaultValue: '#000000' }
+ *       ]
+ *     }
+ *   ]
+ * });
+ * // Returns: {
+ * //   contentType: 'my-content-type',
+ * //   sections: [
+ * //     {
+ * //       title: 'Typography',
+ * //       fields: [
+ * //         [
+ * //           { type: 'input', label: 'Font Size', config: { inputType: 'number', defaultValue: 16 } },
+ * //           { type: 'dropdown', label: 'Font Family', config: { options: [...] } }
+ * //         ]
+ * //       ]
+ * //     },
+ * //     {
+ * //       title: 'Colors',
+ * //       fields: [
+ * //         [
+ * //           { type: 'input', label: 'Primary Color', config: { inputType: 'text', defaultValue: '#000000' } }
+ * //         ]
+ * //       ]
+ * //     }
+ * //   ]
+ * // }
+ * ```
+ */
+function normalizeForm(form) {
+  return {
+    contentType: form.contentType,
+    sections: form.sections.map(normalizeSection)
+  };
+}
 
+/**
+ * Helper functions for creating style editor field definitions.
+ *
+ * Provides type-safe factory functions for creating different types of form fields
+ * used in the style editor. Each function creates a field definition with the
+ * appropriate `type` property automatically set, eliminating the need to manually
+ * specify the type discriminator.
+ *
+ * **Available Field Types:**
+ * - `input`: Text or number input fields
+ * - `dropdown`: Single-value selection from a dropdown list
+ * - `radio`: Single-value selection from radio button options (supports visual options with images)
+ * - `checkboxGroup`: Multiple-value selection from checkbox options
+ *
+ * These factory functions ensure type safety by inferring the correct field type
+ * based on the configuration provided, and they automatically set the `type` property
+ * to match the factory function used.
+ *
+ * @experimental This API is experimental and may be subject to change.
+ *
+ * @example
+ * ```typescript
+ * const form = defineStyleEditorSchema({
+ *   contentType: 'my-content-type',
+ *   sections: [
+ *     {
+ *       title: 'Typography',
+ *       fields: [
+ *         styleEditorField.input({
+ *           label: 'Font Size',
+ *           inputType: 'number',
+ *           defaultValue: 16
+ *         }),
+ *         styleEditorField.dropdown({
+ *           label: 'Font Family',
+ *           options: ['Arial', 'Helvetica'],
+ *           defaultValue: 'Arial'
+ *         }),
+ *         styleEditorField.radio({
+ *           label: 'Alignment',
+ *           options: ['Left', 'Center', 'Right'],
+ *           defaultValue: 'Left'
+ *         })
+ *       ]
+ *     }
+ *   ]
+ * });
+ * ```
+ */
+const styleEditorField = {
+  /**
+   * Creates an input field definition with type-safe default values.
+   *
+   * Supports both text and number input types. The `defaultValue` type is
+   * enforced based on the `inputType` using TypeScript generics:
+   * - When `inputType` is `'number'`, `defaultValue` must be a `number`
+   * - When `inputType` is `'text'`, `defaultValue` must be a `string`
+   *
+   * This provides compile-time type checking to prevent mismatched types,
+   * such as passing a string when a number is expected.
+   *
+   * @experimental This method is experimental and may be subject to change.
+   *
+   * @typeParam T - The input type ('text' or 'number'), inferred from `config.inputType`
+   * @param config - Input field configuration
+   * @param config.label - The label displayed for this input field
+   * @param config.inputType - The type of input ('text' or 'number')
+   * @param config.placeholder - Optional placeholder text for the input
+   * @param config.defaultValue - Optional default value (type enforced based on inputType)
+   * @returns A complete input field definition with type 'input'
+   *
+   * @example
+   * ```typescript
+   * // Number input - defaultValue must be a number
+   * styleEditorField.input({
+   *   label: 'Font Size',
+   *   inputType: 'number',
+   *   placeholder: 'Enter font size',
+   *   defaultValue: 16 // ✓ Correct: number
+   * })
+   *
+   * // Text input - defaultValue must be a string
+   * styleEditorField.input({
+   *   label: 'Font Name',
+   *   inputType: 'text',
+   *   placeholder: 'Enter font name',
+   *   defaultValue: 'Arial' // ✓ Correct: string
+   * })
+   *
+   * // TypeScript error - type mismatch
+   * styleEditorField.input({
+   *   label: 'Font Size',
+   *   inputType: 'number',
+   *   defaultValue: '16' // ✗ Error: Type 'string' is not assignable to type 'number'
+   * })
+   * ```
+   */
+  input: config => ({
+    type: 'input',
+    ...config
+  }),
+  /**
+   * Creates a dropdown field definition.
+   *
+   * Allows users to select a single value from a list of options.
+   * Options can be provided as simple strings or as objects with label and value.
+   *
+   * @experimental This method is experimental and may be subject to change.
+   *
+   * @param config - Dropdown field configuration (without the 'type' property)
+   * @param config.label - The label displayed for this dropdown field
+   * @param config.options - Array of options. Can be strings or objects with label and value
+   * @param config.defaultValue - Optional default selected value (must match one of the option values)
+   * @param config.placeholder - Optional placeholder text shown when no value is selected
+   * @returns A complete dropdown field definition with type 'dropdown'
+   *
+   * @example
+   * ```typescript
+   * // Simple string options
+   * styleEditorField.dropdown({
+   *   label: 'Font Family',
+   *   options: ['Arial', 'Helvetica', 'Times New Roman'],
+   *   defaultValue: 'Arial',
+   *   placeholder: 'Select a font'
+   * })
+   *
+   * // Object options with custom labels
+   * styleEditorField.dropdown({
+   *   label: 'Theme',
+   *   options: [
+   *     { label: 'Light Theme', value: 'light' },
+   *     { label: 'Dark Theme', value: 'dark' }
+   *   ],
+   *   defaultValue: 'light'
+   * })
+   * ```
+   */
+  dropdown: config => ({
+    type: 'dropdown',
+    ...config
+  }),
+  /**
+   * Creates a radio button field definition.
+   *
+   * Allows users to select a single option from a list. Supports visual
+   * options with background images for enhanced UI. Options can be provided
+   * as simple strings or as objects with label, value, and optional image properties.
+   *
+   * **Layout Options:**
+   * - `columns: 1` (default): Single column list layout
+   * - `columns: 2`: Two-column grid layout, ideal for visual options with images
+   *
+   * @experimental This method is experimental and may be subject to change.
+   *
+   * @param config - Radio field configuration (without the 'type' property)
+   * @param config.label - The label displayed for this radio group
+   * @param config.options - Array of options. Can be strings or objects with label, value, and optional imageURL, width, height
+   * @param config.defaultValue - Optional default selected value (must match one of the option values)
+   * @param config.columns - Optional number of columns (1 or 2). Defaults to 1 (single column)
+   * @returns A complete radio field definition with type 'radio'
+   *
+   * @example
+   * ```typescript
+   * // Simple string options (single column)
+   * styleEditorField.radio({
+   *   label: 'Alignment',
+   *   options: ['Left', 'Center', 'Right'],
+   *   defaultValue: 'Left'
+   * })
+   *
+   * // Two-column grid layout with images
+   * styleEditorField.radio({
+   *   label: 'Layout',
+   *   columns: 2,
+   *   options: [
+   *     {
+   *       label: 'Left',
+   *       value: 'left',
+   *       imageURL: 'https://example.com/layout-left.png',
+   *       width: 80,
+   *       height: 50
+   *     },
+   *     {
+   *       label: 'Right',
+   *       value: 'right',
+   *       imageURL: 'https://example.com/layout-right.png',
+   *       width: 80,
+   *       height: 50
+   *     },
+   *     { label: 'Center', value: 'center' },
+   *     { label: 'Overlap', value: 'overlap' }
+   *   ],
+   *   defaultValue: 'right'
+   * })
+   * ```
+   */
+  radio: config => ({
+    type: 'radio',
+    ...config
+  }),
+  /**
+   * Creates a checkbox group field definition.
+   *
+   * Allows users to select multiple options simultaneously. Each option
+   * can be independently checked or unchecked. The defaultValue is a
+   * record mapping option values to their boolean checked state.
+   *
+   * @experimental This method is experimental and may be subject to change.
+   *
+   * @param config - Checkbox group field configuration (without the 'type' property)
+   * @param config.label - The label displayed for this checkbox group
+   * @param config.options - Array of options. Can be strings or objects with label and value
+   * @param config.defaultValue - Optional default checked state as a record of option values to boolean
+   * @returns A complete checkbox group field definition with type 'checkboxGroup'
+   *
+   * @example
+   * ```typescript
+   * styleEditorField.checkboxGroup({
+   *   label: 'Text Decoration',
+   *   options: [
+   *     { label: 'Underline', value: 'underline' },
+   *     { label: 'Overline', value: 'overline' },
+   *     { label: 'Line Through', value: 'line-through' }
+   *   ],
+   *   defaultValue: {
+   *     'underline': true,
+   *     'overline': false,
+   *     'line-through': false
+   *   }
+   * })
+   * ```
+   */
+  checkboxGroup: config => ({
+    type: 'checkboxGroup',
+    ...config
+  })
+};
+/**
+ * Normalizes and validates a style editor form definition.
+ *
+ * Converts the developer-friendly form structure into the schema format
+ * expected by UVE (Universal Visual Editor). This function processes the
+ * form definition and transforms it into the normalized schema format where:
+ *
+ * - All field-specific properties are moved into `config` objects
+ * - String options are normalized to `{ label, value }` objects
+ * - Sections are organized into the multi-dimensional array structure required by UVE
+ *
+ * The normalization process ensures consistency and type safety in the schema
+ * format sent to UVE. After normalization, use `registerStyleEditorSchemas`
+ * to register the schema with the UVE editor.
+ *
+ * @experimental This method is experimental and may be subject to change.
+ *
+ * @param form - The style editor form definition containing contentType and sections
+ * @param form.contentType - The content type identifier for this form
+ * @param form.sections - Array of sections, each containing a title and fields array
+ * @returns The normalized form schema ready to be sent to UVE
+ *
+ * @example
+ * ```typescript
+ * const formSchema = defineStyleEditorSchema({
+ *   contentType: 'my-content-type',
+ *   sections: [
+ *     {
+ *       title: 'Typography',
+ *       fields: [
+ *         styleEditorField.input({
+ *           label: 'Font Size',
+ *           inputType: 'number',
+ *           defaultValue: 16
+ *         }),
+ *         styleEditorField.dropdown({
+ *           label: 'Font Family',
+ *           options: ['Arial', 'Helvetica'],
+ *           defaultValue: 'Arial'
+ *         })
+ *       ]
+ *     },
+ *     {
+ *       title: 'Colors',
+ *       fields: [
+ *         styleEditorField.input({
+ *           label: 'Primary Color',
+ *           inputType: 'text',
+ *           defaultValue: '#000000'
+ *         }),
+ *         styleEditorField.input({
+ *           label: 'Secondary Color',
+ *           inputType: 'text',
+ *           defaultValue: '#FFFFFF'
+ *         })
+ *       ]
+ *     }
+ *   ]
+ * });
+ *
+ * // Register the schema with UVE
+ * registerStyleEditorSchemas([formSchema]);
+ * ```
+ */
+function defineStyleEditorSchema(form) {
+  return normalizeForm(form);
+}
+/**
+ * Registers style editor form schemas with the UVE editor.
+ *
+ * Sends normalized style editor schemas to the UVE (Universal Visual Editor)
+ * for registration. The schemas must be normalized using `defineStyleEditorSchema`
+ * before being passed to this function.
+ *
+ * **Behavior:**
+ * - Only registers schemas when UVE is in EDIT mode
+ * - Validates that each schema has a `contentType` property
+ * - Skips schemas without `contentType` and logs a warning
+ * - Sends the validated schemas to UVE via the `REGISTER_STYLE_SCHEMAS` action
+ *
+ * **Note:** This function will silently return early if UVE is not in EDIT mode,
+ * so it's safe to call even when the editor is not active.
+ *
+ * @experimental This method is experimental and may be subject to change.
+ *
+ * @param schemas - Array of normalized style editor form schemas to register with UVE
+ * @returns void - This function does not return a value
+ *
+ * @example
+ * ```typescript
+ * // Create and normalize a form schema
+ * const formSchema = defineStyleEditorSchema({
+ *   contentType: 'my-content-type',
+ *   sections: [
+ *     {
+ *       title: 'Typography',
+ *       fields: [
+ *         styleEditorField.input({
+ *           label: 'Font Size',
+ *           inputType: 'number',
+ *           defaultValue: 16
+ *         })
+ *       ]
+ *     }
+ *   ]
+ * });
+ *
+ * // Register the schema with UVE
+ * registerStyleEditorSchemas([formSchema]);
+ *
+ * // Register multiple schemas at once
+ * const schema1 = defineStyleEditorSchema({ ... });
+ * const schema2 = defineStyleEditorSchema({ ... });
+ * registerStyleEditorSchemas([schema1, schema2]);
+ * ```
+ */
+function registerStyleEditorSchemas(schemas) {
+  const {
+    mode
+  } = _public.getUVEState() || {};
+  if (!mode || mode !== types.UVE_MODE.EDIT) {
+    return;
+  }
+  const validatedSchemas = schemas.filter((schema, index) => {
+    if (!schema.contentType) {
+      console.warn(`[registerStyleEditorSchemas] Skipping schema with index [${index}] for not having a contentType`);
+      return false;
+    }
+    return true;
+  });
+  _public.sendMessageToUVE({
+    action: types.DotCMSUVEAction.REGISTER_STYLE_SCHEMAS,
+    payload: {
+      schemas: validatedSchemas
+    }
+  });
+}
 
 exports.createUVESubscription = _public.createUVESubscription;
 exports.editContentlet = _public.editContentlet;
@@ -16,3 +602,6 @@ exports.isAnalyticsActive = _public.isAnalyticsActive;
 exports.reorderMenu = _public.reorderMenu;
 exports.sendMessageToUVE = _public.sendMessageToUVE;
 exports.updateNavigation = _public.updateNavigation;
+exports.defineStyleEditorSchema = defineStyleEditorSchema;
+exports.registerStyleEditorSchemas = registerStyleEditorSchemas;
+exports.styleEditorField = styleEditorField;