@dotcms/uve 1.2.1-next.7 → 1.2.1-next.8

package/index.cjs.js

@@ -17,7 +17,8 @@ require('@dotcms/types/internal');
  *   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
+ * - **Checkbox group fields**: Normalizes options and derives `defaultValue` from option values
+ *   (creates Record<string, boolean> mapping option keys to their boolean values)
  *
  * @experimental This method is experimental and may be subject to change.
  *
@@ -72,7 +73,6 @@ function normalizeField(field) {
       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') {
@@ -80,12 +80,17 @@ function normalizeField(field) {
     }
   }
   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;
+    // Normalize checkbox options - convert to format expected by UVE
+    // Options already have label, key, and value (boolean)
+    config.options = field.options.map(opt => ({
+      label: opt.label,
+      value: opt.key // UVE expects 'value' to be the key identifier
+    }));
+    // Derive defaultValue from options - map key to boolean value
+    config.defaultValue = field.options.reduce((acc, opt) => {
+      acc[opt.key] = opt.value;
+      return acc;
+    }, {});
   }
   return {
     ...base,
@@ -320,24 +325,68 @@ const styleEditorField = {
     ...config
   }),
   /**
-   * Creates a dropdown field definition.
+   * Creates a dropdown field definition with type-safe default values.
    *
    * 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.
    *
+   * **Type Safety Tip:** For autocomplete on `defaultValue`, use `as const` when defining options:
+   * ```typescript
+   * const options = [
+   *   { label: 'The one', value: 'one' },
+   *   { label: 'The two', value: 'two' }
+   * ] as const;
+   *
+   * styleEditorField.dropdown({
+   *   id: 'my-field',
+   *   label: 'Select option',
+   *   options,
+   *   defaultValue: 'one' // ✓ Autocomplete works! TypeScript knows 'one' | 'two'
+   *   // defaultValue: 'three' // ✗ TypeScript error: not assignable
+   * })
+   * ```
+   *
+   * Without `as const`, the function still works but won't provide autocomplete:
+   * ```typescript
+   * styleEditorField.dropdown({
+   *   id: 'my-field',
+   *   label: 'Select option',
+   *   options: [
+   *     { label: 'The one', value: 'one' },
+   *     { label: 'The two', value: 'two' }
+   *   ],
+   *   defaultValue: 'one' // Works, but no autocomplete
+   * })
+   * ```
+   *
    * @experimental This method is experimental and may be subject to change.
    *
+   * @typeParam TOptions - The options array type (inferred from config, use `as const` for type safety)
    * @param config - Dropdown field configuration (without the 'type' property)
+   * @param config.id - The unique identifier for this field
    * @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
+   * @param config.options - Array of options. Use `as const` for type safety and autocomplete
+   * @param config.defaultValue - Optional default selected value (type-safe when options are `as const`)
    * @returns A complete dropdown field definition with type 'dropdown'
    *
    * @example
    * ```typescript
+   * // With type safety - use 'as const' for autocomplete
+   * const options = [
+   *   { label: 'The one', value: 'one' },
+   *   { label: 'The two', value: 'two' }
+   * ] as const;
+   *
+   * styleEditorField.dropdown({
+   *   id: 'my-field',
+   *   label: 'Select option',
+   *   options,
+   *   defaultValue: 'one' // ✓ Autocomplete works!
+   * })
+   *
    * // Simple string options
    * styleEditorField.dropdown({
+   *   id: 'font-family',
    *   label: 'Font Family',
    *   options: ['Arial', 'Helvetica', 'Times New Roman'],
    *   defaultValue: 'Arial',
@@ -346,6 +395,7 @@ const styleEditorField = {
    *
    * // Object options with custom labels
    * styleEditorField.dropdown({
+   *   id: 'theme',
    *   label: 'Theme',
    *   options: [
    *     { label: 'Light Theme', value: 'light' },
@@ -357,10 +407,12 @@ const styleEditorField = {
    */
   dropdown: config => ({
     type: 'dropdown',
-    ...config
+    ...config,
+    options: config.options,
+    defaultValue: config.defaultValue
   }),
   /**
-   * Creates a radio button field definition.
+   * Creates a radio button field definition with type-safe default values.
    *
    * Allows users to select a single option from a list. Supports visual
    * options with background images for enhanced UI. Options can be provided
@@ -370,19 +422,64 @@ const styleEditorField = {
    * - `columns: 1` (default): Single column list layout
    * - `columns: 2`: Two-column grid layout, ideal for visual options with images
    *
+   * **Type Safety Tip:** For autocomplete on `defaultValue`, use `as const` when defining options:
+   * ```typescript
+   * const options = [
+   *   { label: 'The one', value: 'one' },
+   *   { label: 'The two', value: 'two' }
+   * ] as const;
+   *
+   * styleEditorField.radio({
+   *   id: 'my-field',
+   *   label: 'Select option',
+   *   options,
+   *   defaultValue: 'one' // ✓ Autocomplete works! TypeScript knows 'one' | 'two'
+   *   // defaultValue: 'three' // ✗ TypeScript error: not assignable
+   * })
+   * ```
+   *
+   * Without `as const`, the function still works but won't provide autocomplete:
+   * ```typescript
+   * styleEditorField.radio({
+   *   id: 'my-field',
+   *   label: 'Select option',
+   *   options: [
+   *     { label: 'The one', value: 'one' },
+   *     { label: 'The two', value: 'two' }
+   *   ],
+   *   defaultValue: 'one' // Works, but no autocomplete
+   * })
+   * ```
+   *
    * @experimental This method is experimental and may be subject to change.
    *
+   * @typeParam TOptions - The options array type (inferred from config, use `as const` for type safety)
    * @param config - Radio field configuration (without the 'type' property)
+   * @param config.id - The unique identifier for this field
    * @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
-   * @param config.defaultValue - Optional default selected value (must match one of the option values)
+   * @param config.options - Array of options. Use `as const` for type safety and autocomplete
+   * @param config.defaultValue - Optional default selected value (type-safe when options are `as const`)
    * @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
+   * // With type safety - use 'as const' for autocomplete
+   * const options = [
+   *   { label: 'The one', value: 'one' },
+   *   { label: 'The two', value: 'two' }
+   * ] as const;
+   *
+   * styleEditorField.radio({
+   *   id: 'my-field',
+   *   label: 'Select option',
+   *   options,
+   *   defaultValue: 'one' // ✓ Autocomplete works!
+   * })
+   *
    * // Simple string options (single column)
    * styleEditorField.radio({
+   *   id: 'alignment',
    *   label: 'Alignment',
    *   options: ['Left', 'Center', 'Right'],
    *   defaultValue: 'Left'
@@ -390,6 +487,7 @@ const styleEditorField = {
    *
    * // Two-column grid layout with images
    * styleEditorField.radio({
+   *   id: 'layout',
    *   label: 'Layout',
    *   columns: 2,
    *   options: [
@@ -412,37 +510,59 @@ const styleEditorField = {
    */
   radio: config => ({
     type: 'radio',
-    ...config
+    ...config,
+    options: config.options,
+    defaultValue: config.defaultValue
   }),
   /**
    * 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.
+   * can be independently checked or unchecked. The default checked state
+   * is defined directly in each option's `value` property (boolean).
+   *
+   * **Key Differences from Other Field Types:**
+   * - Uses `key` instead of `value` for the identifier (to avoid confusion)
+   * - Uses `value` for the default boolean checked state (the actual value)
+   * - No separate `defaultValue` property - defaults are embedded in options
+   *
+   * **Why `key` instead of `value`?**
+   * In dropdown and radio fields, `value` represents the actual selected value (string).
+   * In checkbox groups, the actual value is boolean (checked/unchecked), so we use
+   * `key` for the identifier to avoid confusion. This makes it clear that `value`
+   * is the boolean state, not just an identifier.
    *
    * @experimental This method is experimental and may be subject to change.
    *
    * @param config - Checkbox group field configuration (without the 'type' property)
+   * @param config.id - The unique identifier for this field
    * @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
+   * @param config.options - Array of checkbox options with label, key, and value (boolean)
    * @returns A complete checkbox group field definition with type 'checkboxGroup'
    *
    * @example
    * ```typescript
    * styleEditorField.checkboxGroup({
+   *   id: 'text-decoration',
    *   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
-   *   }
+   *     { label: 'Underline', key: 'underline', value: true },
+   *     { label: 'Overline', key: 'overline', value: false },
+   *     { label: 'Line Through', key: 'line-through', value: false }
+   *   ]
+   *   // No defaultValue needed - it's automatically derived from options
+   * })
+   *
+   * // Example with type settings
+   * styleEditorField.checkboxGroup({
+   *   id: 'type-settings',
+   *   label: 'Type settings',
+   *   options: [
+   *     { label: 'Bold', key: 'bold', value: true },
+   *     { label: 'Italic', key: 'italic', value: false },
+   *     { label: 'Underline', key: 'underline', value: false },
+   *     { label: 'Strikethrough', key: 'strikethrough', value: false }
+   *   ]
    * })
    * ```
    */

package/index.esm.js

@@ -16,7 +16,8 @@ import '@dotcms/types/internal';
  *   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
+ * - **Checkbox group fields**: Normalizes options and derives `defaultValue` from option values
+ *   (creates Record<string, boolean> mapping option keys to their boolean values)
  *
  * @experimental This method is experimental and may be subject to change.
  *
@@ -71,7 +72,6 @@ function normalizeField(field) {
       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') {
@@ -79,12 +79,17 @@ function normalizeField(field) {
     }
   }
   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;
+    // Normalize checkbox options - convert to format expected by UVE
+    // Options already have label, key, and value (boolean)
+    config.options = field.options.map(opt => ({
+      label: opt.label,
+      value: opt.key // UVE expects 'value' to be the key identifier
+    }));
+    // Derive defaultValue from options - map key to boolean value
+    config.defaultValue = field.options.reduce((acc, opt) => {
+      acc[opt.key] = opt.value;
+      return acc;
+    }, {});
   }
   return {
     ...base,
@@ -319,24 +324,68 @@ const styleEditorField = {
     ...config
   }),
   /**
-   * Creates a dropdown field definition.
+   * Creates a dropdown field definition with type-safe default values.
    *
    * 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.
    *
+   * **Type Safety Tip:** For autocomplete on `defaultValue`, use `as const` when defining options:
+   * ```typescript
+   * const options = [
+   *   { label: 'The one', value: 'one' },
+   *   { label: 'The two', value: 'two' }
+   * ] as const;
+   *
+   * styleEditorField.dropdown({
+   *   id: 'my-field',
+   *   label: 'Select option',
+   *   options,
+   *   defaultValue: 'one' // ✓ Autocomplete works! TypeScript knows 'one' | 'two'
+   *   // defaultValue: 'three' // ✗ TypeScript error: not assignable
+   * })
+   * ```
+   *
+   * Without `as const`, the function still works but won't provide autocomplete:
+   * ```typescript
+   * styleEditorField.dropdown({
+   *   id: 'my-field',
+   *   label: 'Select option',
+   *   options: [
+   *     { label: 'The one', value: 'one' },
+   *     { label: 'The two', value: 'two' }
+   *   ],
+   *   defaultValue: 'one' // Works, but no autocomplete
+   * })
+   * ```
+   *
    * @experimental This method is experimental and may be subject to change.
    *
+   * @typeParam TOptions - The options array type (inferred from config, use `as const` for type safety)
    * @param config - Dropdown field configuration (without the 'type' property)
+   * @param config.id - The unique identifier for this field
    * @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
+   * @param config.options - Array of options. Use `as const` for type safety and autocomplete
+   * @param config.defaultValue - Optional default selected value (type-safe when options are `as const`)
    * @returns A complete dropdown field definition with type 'dropdown'
    *
    * @example
    * ```typescript
+   * // With type safety - use 'as const' for autocomplete
+   * const options = [
+   *   { label: 'The one', value: 'one' },
+   *   { label: 'The two', value: 'two' }
+   * ] as const;
+   *
+   * styleEditorField.dropdown({
+   *   id: 'my-field',
+   *   label: 'Select option',
+   *   options,
+   *   defaultValue: 'one' // ✓ Autocomplete works!
+   * })
+   *
    * // Simple string options
    * styleEditorField.dropdown({
+   *   id: 'font-family',
    *   label: 'Font Family',
    *   options: ['Arial', 'Helvetica', 'Times New Roman'],
    *   defaultValue: 'Arial',
@@ -345,6 +394,7 @@ const styleEditorField = {
    *
    * // Object options with custom labels
    * styleEditorField.dropdown({
+   *   id: 'theme',
    *   label: 'Theme',
    *   options: [
    *     { label: 'Light Theme', value: 'light' },
@@ -356,10 +406,12 @@ const styleEditorField = {
    */
   dropdown: config => ({
     type: 'dropdown',
-    ...config
+    ...config,
+    options: config.options,
+    defaultValue: config.defaultValue
   }),
   /**
-   * Creates a radio button field definition.
+   * Creates a radio button field definition with type-safe default values.
    *
    * Allows users to select a single option from a list. Supports visual
    * options with background images for enhanced UI. Options can be provided
@@ -369,19 +421,64 @@ const styleEditorField = {
    * - `columns: 1` (default): Single column list layout
    * - `columns: 2`: Two-column grid layout, ideal for visual options with images
    *
+   * **Type Safety Tip:** For autocomplete on `defaultValue`, use `as const` when defining options:
+   * ```typescript
+   * const options = [
+   *   { label: 'The one', value: 'one' },
+   *   { label: 'The two', value: 'two' }
+   * ] as const;
+   *
+   * styleEditorField.radio({
+   *   id: 'my-field',
+   *   label: 'Select option',
+   *   options,
+   *   defaultValue: 'one' // ✓ Autocomplete works! TypeScript knows 'one' | 'two'
+   *   // defaultValue: 'three' // ✗ TypeScript error: not assignable
+   * })
+   * ```
+   *
+   * Without `as const`, the function still works but won't provide autocomplete:
+   * ```typescript
+   * styleEditorField.radio({
+   *   id: 'my-field',
+   *   label: 'Select option',
+   *   options: [
+   *     { label: 'The one', value: 'one' },
+   *     { label: 'The two', value: 'two' }
+   *   ],
+   *   defaultValue: 'one' // Works, but no autocomplete
+   * })
+   * ```
+   *
    * @experimental This method is experimental and may be subject to change.
    *
+   * @typeParam TOptions - The options array type (inferred from config, use `as const` for type safety)
    * @param config - Radio field configuration (without the 'type' property)
+   * @param config.id - The unique identifier for this field
    * @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
-   * @param config.defaultValue - Optional default selected value (must match one of the option values)
+   * @param config.options - Array of options. Use `as const` for type safety and autocomplete
+   * @param config.defaultValue - Optional default selected value (type-safe when options are `as const`)
    * @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
+   * // With type safety - use 'as const' for autocomplete
+   * const options = [
+   *   { label: 'The one', value: 'one' },
+   *   { label: 'The two', value: 'two' }
+   * ] as const;
+   *
+   * styleEditorField.radio({
+   *   id: 'my-field',
+   *   label: 'Select option',
+   *   options,
+   *   defaultValue: 'one' // ✓ Autocomplete works!
+   * })
+   *
    * // Simple string options (single column)
    * styleEditorField.radio({
+   *   id: 'alignment',
    *   label: 'Alignment',
    *   options: ['Left', 'Center', 'Right'],
    *   defaultValue: 'Left'
@@ -389,6 +486,7 @@ const styleEditorField = {
    *
    * // Two-column grid layout with images
    * styleEditorField.radio({
+   *   id: 'layout',
    *   label: 'Layout',
    *   columns: 2,
    *   options: [
@@ -411,37 +509,59 @@ const styleEditorField = {
    */
   radio: config => ({
     type: 'radio',
-    ...config
+    ...config,
+    options: config.options,
+    defaultValue: config.defaultValue
   }),
   /**
    * 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.
+   * can be independently checked or unchecked. The default checked state
+   * is defined directly in each option's `value` property (boolean).
+   *
+   * **Key Differences from Other Field Types:**
+   * - Uses `key` instead of `value` for the identifier (to avoid confusion)
+   * - Uses `value` for the default boolean checked state (the actual value)
+   * - No separate `defaultValue` property - defaults are embedded in options
+   *
+   * **Why `key` instead of `value`?**
+   * In dropdown and radio fields, `value` represents the actual selected value (string).
+   * In checkbox groups, the actual value is boolean (checked/unchecked), so we use
+   * `key` for the identifier to avoid confusion. This makes it clear that `value`
+   * is the boolean state, not just an identifier.
    *
    * @experimental This method is experimental and may be subject to change.
    *
    * @param config - Checkbox group field configuration (without the 'type' property)
+   * @param config.id - The unique identifier for this field
    * @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
+   * @param config.options - Array of checkbox options with label, key, and value (boolean)
    * @returns A complete checkbox group field definition with type 'checkboxGroup'
    *
    * @example
    * ```typescript
    * styleEditorField.checkboxGroup({
+   *   id: 'text-decoration',
    *   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
-   *   }
+   *     { label: 'Underline', key: 'underline', value: true },
+   *     { label: 'Overline', key: 'overline', value: false },
+   *     { label: 'Line Through', key: 'line-through', value: false }
+   *   ]
+   *   // No defaultValue needed - it's automatically derived from options
+   * })
+   *
+   * // Example with type settings
+   * styleEditorField.checkboxGroup({
+   *   id: 'type-settings',
+   *   label: 'Type settings',
+   *   options: [
+   *     { label: 'Bold', key: 'bold', value: true },
+   *     { label: 'Italic', key: 'italic', value: false },
+   *     { label: 'Underline', key: 'underline', value: false },
+   *     { label: 'Strikethrough', key: 'strikethrough', value: false }
+   *   ]
    * })
    * ```
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/uve",
-  "version": "1.2.1-next.7",
+  "version": "1.2.1-next.8",
   "description": "Official JavaScript library for interacting with Universal Visual Editor (UVE)",
   "repository": {
     "type": "git",

package/src/lib/style-editor/public.d.ts

@@ -1,4 +1,4 @@
-import { StyleEditorFormSchema, StyleEditorForm, StyleEditorInputField, StyleEditorDropdownField, StyleEditorRadioField, StyleEditorCheckboxGroupField, StyleEditorFieldInputType, StyleEditorInputFieldConfig } from './types';
+import { StyleEditorFormSchema, StyleEditorForm, StyleEditorInputField, StyleEditorDropdownField, StyleEditorRadioField, StyleEditorCheckboxGroupField, StyleEditorFieldInputType, StyleEditorInputFieldConfig, StyleEditorOption, StyleEditorRadioOption, StyleEditorOptionValues, StyleEditorRadioOptionValues } from './types';
 /**
  * Helper functions for creating style editor field definitions.
  *
@@ -98,24 +98,68 @@ export declare const styleEditorField: {
      */
     input: <T extends StyleEditorFieldInputType>(config: StyleEditorInputFieldConfig<T>) => StyleEditorInputField;
     /**
-     * Creates a dropdown field definition.
+     * Creates a dropdown field definition with type-safe default values.
      *
      * 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.
      *
+     * **Type Safety Tip:** For autocomplete on `defaultValue`, use `as const` when defining options:
+     * ```typescript
+     * const options = [
+     *   { label: 'The one', value: 'one' },
+     *   { label: 'The two', value: 'two' }
+     * ] as const;
+     *
+     * styleEditorField.dropdown({
+     *   id: 'my-field',
+     *   label: 'Select option',
+     *   options,
+     *   defaultValue: 'one' // ✓ Autocomplete works! TypeScript knows 'one' | 'two'
+     *   // defaultValue: 'three' // ✗ TypeScript error: not assignable
+     * })
+     * ```
+     *
+     * Without `as const`, the function still works but won't provide autocomplete:
+     * ```typescript
+     * styleEditorField.dropdown({
+     *   id: 'my-field',
+     *   label: 'Select option',
+     *   options: [
+     *     { label: 'The one', value: 'one' },
+     *     { label: 'The two', value: 'two' }
+     *   ],
+     *   defaultValue: 'one' // Works, but no autocomplete
+     * })
+     * ```
+     *
      * @experimental This method is experimental and may be subject to change.
      *
+     * @typeParam TOptions - The options array type (inferred from config, use `as const` for type safety)
      * @param config - Dropdown field configuration (without the 'type' property)
+     * @param config.id - The unique identifier for this field
      * @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
+     * @param config.options - Array of options. Use `as const` for type safety and autocomplete
+     * @param config.defaultValue - Optional default selected value (type-safe when options are `as const`)
      * @returns A complete dropdown field definition with type 'dropdown'
      *
      * @example
      * ```typescript
+     * // With type safety - use 'as const' for autocomplete
+     * const options = [
+     *   { label: 'The one', value: 'one' },
+     *   { label: 'The two', value: 'two' }
+     * ] as const;
+     *
+     * styleEditorField.dropdown({
+     *   id: 'my-field',
+     *   label: 'Select option',
+     *   options,
+     *   defaultValue: 'one' // ✓ Autocomplete works!
+     * })
+     *
      * // Simple string options
      * styleEditorField.dropdown({
+     *   id: 'font-family',
      *   label: 'Font Family',
      *   options: ['Arial', 'Helvetica', 'Times New Roman'],
      *   defaultValue: 'Arial',
@@ -124,6 +168,7 @@ export declare const styleEditorField: {
      *
      * // Object options with custom labels
      * styleEditorField.dropdown({
+     *   id: 'theme',
      *   label: 'Theme',
      *   options: [
      *     { label: 'Light Theme', value: 'light' },
@@ -133,9 +178,12 @@ export declare const styleEditorField: {
      * })
      * ```
      */
-    dropdown: (config: Omit<StyleEditorDropdownField, "type">) => StyleEditorDropdownField;
+    dropdown: <TOptions extends readonly StyleEditorOption[]>(config: Omit<StyleEditorDropdownField, "type" | "options" | "defaultValue"> & {
+        options: TOptions;
+        defaultValue?: StyleEditorOptionValues<TOptions>;
+    }) => StyleEditorDropdownField;
     /**
-     * Creates a radio button field definition.
+     * Creates a radio button field definition with type-safe default values.
      *
      * Allows users to select a single option from a list. Supports visual
      * options with background images for enhanced UI. Options can be provided
@@ -145,19 +193,64 @@ export declare const styleEditorField: {
      * - `columns: 1` (default): Single column list layout
      * - `columns: 2`: Two-column grid layout, ideal for visual options with images
      *
+     * **Type Safety Tip:** For autocomplete on `defaultValue`, use `as const` when defining options:
+     * ```typescript
+     * const options = [
+     *   { label: 'The one', value: 'one' },
+     *   { label: 'The two', value: 'two' }
+     * ] as const;
+     *
+     * styleEditorField.radio({
+     *   id: 'my-field',
+     *   label: 'Select option',
+     *   options,
+     *   defaultValue: 'one' // ✓ Autocomplete works! TypeScript knows 'one' | 'two'
+     *   // defaultValue: 'three' // ✗ TypeScript error: not assignable
+     * })
+     * ```
+     *
+     * Without `as const`, the function still works but won't provide autocomplete:
+     * ```typescript
+     * styleEditorField.radio({
+     *   id: 'my-field',
+     *   label: 'Select option',
+     *   options: [
+     *     { label: 'The one', value: 'one' },
+     *     { label: 'The two', value: 'two' }
+     *   ],
+     *   defaultValue: 'one' // Works, but no autocomplete
+     * })
+     * ```
+     *
      * @experimental This method is experimental and may be subject to change.
      *
+     * @typeParam TOptions - The options array type (inferred from config, use `as const` for type safety)
      * @param config - Radio field configuration (without the 'type' property)
+     * @param config.id - The unique identifier for this field
      * @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
-     * @param config.defaultValue - Optional default selected value (must match one of the option values)
+     * @param config.options - Array of options. Use `as const` for type safety and autocomplete
+     * @param config.defaultValue - Optional default selected value (type-safe when options are `as const`)
      * @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
+     * // With type safety - use 'as const' for autocomplete
+     * const options = [
+     *   { label: 'The one', value: 'one' },
+     *   { label: 'The two', value: 'two' }
+     * ] as const;
+     *
+     * styleEditorField.radio({
+     *   id: 'my-field',
+     *   label: 'Select option',
+     *   options,
+     *   defaultValue: 'one' // ✓ Autocomplete works!
+     * })
+     *
      * // Simple string options (single column)
      * styleEditorField.radio({
+     *   id: 'alignment',
      *   label: 'Alignment',
      *   options: ['Left', 'Center', 'Right'],
      *   defaultValue: 'Left'
@@ -165,6 +258,7 @@ export declare const styleEditorField: {
      *
      * // Two-column grid layout with images
      * styleEditorField.radio({
+     *   id: 'layout',
      *   label: 'Layout',
      *   columns: 2,
      *   options: [
@@ -185,36 +279,59 @@ export declare const styleEditorField: {
      * })
      * ```
      */
-    radio: (config: Omit<StyleEditorRadioField, "type">) => StyleEditorRadioField;
+    radio: <TOptions extends readonly StyleEditorRadioOption[]>(config: Omit<StyleEditorRadioField, "type" | "options" | "defaultValue"> & {
+        options: TOptions;
+        defaultValue?: StyleEditorRadioOptionValues<TOptions>;
+    }) => StyleEditorRadioField;
     /**
      * 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.
+     * can be independently checked or unchecked. The default checked state
+     * is defined directly in each option's `value` property (boolean).
+     *
+     * **Key Differences from Other Field Types:**
+     * - Uses `key` instead of `value` for the identifier (to avoid confusion)
+     * - Uses `value` for the default boolean checked state (the actual value)
+     * - No separate `defaultValue` property - defaults are embedded in options
+     *
+     * **Why `key` instead of `value`?**
+     * In dropdown and radio fields, `value` represents the actual selected value (string).
+     * In checkbox groups, the actual value is boolean (checked/unchecked), so we use
+     * `key` for the identifier to avoid confusion. This makes it clear that `value`
+     * is the boolean state, not just an identifier.
      *
      * @experimental This method is experimental and may be subject to change.
      *
      * @param config - Checkbox group field configuration (without the 'type' property)
+     * @param config.id - The unique identifier for this field
      * @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
+     * @param config.options - Array of checkbox options with label, key, and value (boolean)
      * @returns A complete checkbox group field definition with type 'checkboxGroup'
      *
      * @example
      * ```typescript
      * styleEditorField.checkboxGroup({
+     *   id: 'text-decoration',
      *   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
-     *   }
+     *     { label: 'Underline', key: 'underline', value: true },
+     *     { label: 'Overline', key: 'overline', value: false },
+     *     { label: 'Line Through', key: 'line-through', value: false }
+     *   ]
+     *   // No defaultValue needed - it's automatically derived from options
+     * })
+     *
+     * // Example with type settings
+     * styleEditorField.checkboxGroup({
+     *   id: 'type-settings',
+     *   label: 'Type settings',
+     *   options: [
+     *     { label: 'Bold', key: 'bold', value: true },
+     *     { label: 'Italic', key: 'italic', value: false },
+     *     { label: 'Underline', key: 'underline', value: false },
+     *     { label: 'Strikethrough', key: 'strikethrough', value: false }
+     *   ]
      * })
      * ```
      */

package/src/lib/style-editor/types.d.ts

@@ -120,7 +120,69 @@ export interface StyleEditorRadioOptionObject extends StyleEditorOptionObject {
  * };
  * ```
  */
-export type StyleEditorOption = string | StyleEditorOptionObject;
+export type StyleEditorOption = StyleEditorOptionObject;
+/**
+ * Helper type that extracts the union of all option values from an array of options.
+ *
+ * This type extracts the `value` property from each option object and creates
+ * a union type of all possible values. This enables type-safe `defaultValue`
+ * that can only be one of the option values when used with `as const`.
+ *
+ * **Note:** For full type safety and autocomplete, use `as const` when defining options:
+ * ```typescript
+ * const options = [
+ *   { label: 'The one', value: 'one' },
+ *   { label: 'The two', value: 'two' }
+ * ] as const;
+ * ```
+ *
+ * @typeParam T - Array of option objects (should be `as const` for best results)
+ *
+ * @example
+ * ```typescript
+ * const options = [
+ *   { label: 'The one', value: 'one' },
+ *   { label: 'The two', value: 'two' }
+ * ] as const;
+ *
+ * type OptionValues = StyleEditorOptionValues<typeof options>;
+ * // Result: 'one' | 'two'
+ * ```
+ */
+export type StyleEditorOptionValues<T extends readonly StyleEditorOption[]> = T[number] extends {
+    value: infer V;
+} ? V : never;
+/**
+ * Helper type that extracts the union of all radio option values from an array of radio options.
+ *
+ * Similar to `StyleEditorOptionValues`, but handles radio options which can be
+ * strings or objects. Extracts the `value` property from option objects, or uses
+ * the string itself if the option is a string.
+ *
+ * **Note:** For full type safety and autocomplete, use `as const` when defining options:
+ * ```typescript
+ * const options = [
+ *   { label: 'The one', value: 'one' },
+ *   { label: 'The two', value: 'two' }
+ * ] as const;
+ * ```
+ *
+ * @typeParam T - Array of radio option objects or strings (should be `as const` for best results)
+ *
+ * @example
+ * ```typescript
+ * const options = [
+ *   { label: 'The one', value: 'one' },
+ *   { label: 'The two', value: 'two' }
+ * ] as const;
+ *
+ * type RadioOptionValues = StyleEditorRadioOptionValues<typeof options>;
+ * // Result: 'one' | 'two'
+ * ```
+ */
+export type StyleEditorRadioOptionValues<T extends readonly StyleEditorRadioOption[]> = T[number] extends infer U ? U extends string ? U : U extends {
+    value: infer V;
+} ? V : never : never;
 /**
  * Option type for radio fields with visual support.
  *
@@ -141,11 +203,40 @@ export type StyleEditorOption = string | StyleEditorOptionObject;
  * ```
  */
 export type StyleEditorRadioOption = string | StyleEditorRadioOptionObject;
+/**
+ * Checkbox option object with label, key identifier, and default boolean value.
+ *
+ * Unlike dropdown and radio options where `value` represents the actual value,
+ * checkbox options use `key` as the identifier and `value` as the default checked state (boolean).
+ * This distinction makes it clear that the boolean is the actual value, not just an identifier.
+ *
+ * @property label - Display label shown to users
+ * @property key - Unique identifier/key used in the defaultValue object
+ * @property value - Default checked state (true or false)
+ *
+ * @example
+ * ```typescript
+ * const checkboxOption: StyleEditorCheckboxOption = {
+ *   label: 'Underline',
+ *   key: 'underline',
+ *   value: true
+ * };
+ * ```
+ */
+export interface StyleEditorCheckboxOption {
+    /** Display label shown to users */
+    label: string;
+    /** Unique identifier/key used in the defaultValue object */
+    key: string;
+    /** Default checked state (true = checked by default, false = unchecked by default) */
+    value: boolean;
+}
 /**
  * Default value type for checkbox group fields.
  *
- * A record mapping option values to their boolean checked state.
- * Keys should match the option values, values indicate whether the option is checked.
+ * A record mapping option keys to their boolean checked state.
+ * This is derived automatically from checkbox options during normalization.
+ * Keys match the `key` property from checkbox options, values indicate whether the option is checked.
  *
  * @example
  * ```typescript
@@ -243,10 +334,22 @@ export type StyleEditorInputField = (StyleEditorBaseField & {
  * Options can be provided as simple strings or as objects with
  * separate label and value properties for more flexibility.
  *
+ * **Type Safety Tip:** For autocomplete on `defaultValue`, use `as const` when defining options:
+ * ```typescript
+ * const options = [
+ *   { label: 'The one', value: 'one' },
+ *   { label: 'The two', value: 'two' }
+ * ] as const;
+ *
+ * styleEditorField.dropdown({
+ *   options,
+ *   defaultValue: 'one' // ✓ Autocomplete works! TypeScript knows 'one' | 'two'
+ * })
+ * ```
+ *
  * @property type - Must be 'dropdown'
  * @property options - Array of selectable options. Can be strings or objects with label/value
  * @property defaultValue - Optional default selected value (must match one of the option values)
- * @property placeholder - Optional placeholder text shown when no value is selected
  *
  * @example
  * ```typescript
@@ -254,8 +357,7 @@ export type StyleEditorInputField = (StyleEditorBaseField & {
  *   type: 'dropdown',
  *   label: 'Font Family',
  *   options: ['Arial', 'Helvetica', { label: 'Times New Roman', value: 'times' }],
- *   defaultValue: 'Arial',
- *   placeholder: 'Select a font'
+ *   defaultValue: 'Arial'
  * };
  * ```
  */
@@ -266,8 +368,6 @@ export interface StyleEditorDropdownField extends StyleEditorBaseField {
     options: StyleEditorOption[];
     /** Optional default selected value (must match one of the option values) */
     defaultValue?: string;
-    /** Optional placeholder text shown when no value is selected */
-    placeholder?: string;
 }
 /**
  * Radio button field definition for single-value selection with visual options.
@@ -281,6 +381,35 @@ export interface StyleEditorDropdownField extends StyleEditorBaseField {
  * - `columns: 1` (default): Single column list layout
  * - `columns: 2`: Two-column grid layout, ideal for visual options with images
  *
+ * **Type Safety Tip:** For autocomplete on `defaultValue`, use `as const` when defining options:
+ * ```typescript
+ * const options = [
+ *   { label: 'The one', value: 'one' },
+ *   { label: 'The two', value: 'two' }
+ * ] as const;
+ *
+ * styleEditorField.radio({
+ *   id: 'my-field',
+ *   label: 'Select option',
+ *   options,
+ *   defaultValue: 'one' // ✓ Autocomplete works! TypeScript knows 'one' | 'two'
+ *   // defaultValue: 'three' // ✗ TypeScript error: not assignable
+ * })
+ * ```
+ *
+ * Without `as const`, the function still works but won't provide autocomplete:
+ * ```typescript
+ * styleEditorField.radio({
+ *   id: 'my-field',
+ *   label: 'Select option',
+ *   options: [
+ *     { label: 'The one', value: 'one' },
+ *     { label: 'The two', value: 'two' }
+ *   ],
+ *   defaultValue: 'one' // Works, but no autocomplete
+ * })
+ * ```
+ *
  * @property type - Must be 'radio'
  * @property options - Array of selectable options. Can be strings or objects with label, value, and optional image properties
  * @property defaultValue - Optional default selected value (must match one of the option values)
@@ -288,17 +417,33 @@ export interface StyleEditorDropdownField extends StyleEditorBaseField {
  *
  * @example
  * ```typescript
- * // Single column layout (default)
+ * // With type safety - use 'as const' for autocomplete
+ * const options = [
+ *   { label: 'The one', value: 'one' },
+ *   { label: 'The two', value: 'two' }
+ * ] as const;
+ *
  * const radioField: StyleEditorRadioField = {
  *   type: 'radio',
+ *   id: 'my-field',
+ *   label: 'Select option',
+ *   options,
+ *   defaultValue: 'one' // ✓ Autocomplete works!
+ * };
+ *
+ * // Single column layout (default)
+ * const alignmentField: StyleEditorRadioField = {
+ *   type: 'radio',
+ *   id: 'alignment',
  *   label: 'Alignment',
  *   options: ['Left', 'Center', 'Right'],
- *   defaultValue: 'left'
+ *   defaultValue: 'Left'
  * };
  *
  * // Two-column grid layout with images
  * const layoutField: StyleEditorRadioField = {
  *   type: 'radio',
+ *   id: 'layout',
  *   label: 'Layout',
  *   columns: 2,
  *   options: [
@@ -341,41 +486,42 @@ export interface StyleEditorRadioField extends StyleEditorBaseField {
  * Checkbox group field definition for multiple-value selection.
  *
  * 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.
+ * can be independently checked or unchecked. The default checked state
+ * is defined directly in each option's `value` property (boolean).
+ *
+ * **Key Differences from Other Field Types:**
+ * - Uses `key` instead of `value` for the identifier (to avoid confusion)
+ * - Uses `value` for the default boolean checked state (the actual value)
+ * - No separate `defaultValue` property - defaults are embedded in options
  *
  * @property type - Must be 'checkboxGroup'
- * @property options - Array of selectable options. Can be strings or objects with label/value
- * @property defaultValue - Optional default checked state as a record mapping option values to boolean
+ * @property options - Array of checkbox options with label, key, and value (boolean)
  *
  * @example
  * ```typescript
  * const checkboxField: StyleEditorCheckboxGroupField = {
  *   type: 'checkboxGroup',
+ *   id: 'text-decoration',
  *   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
- *   }
+ *     { label: 'Underline', key: 'underline', value: true },
+ *     { label: 'Overline', key: 'overline', value: false },
+ *     { label: 'Line Through', key: 'line-through', value: false }
+ *   ]
+ *   // No defaultValue needed - it's derived from options during normalization
  * };
  * ```
  */
 export interface StyleEditorCheckboxGroupField extends StyleEditorBaseField {
     /** Discriminator: must be 'checkboxGroup' */
     type: 'checkboxGroup';
-    /** Array of selectable options. Can be strings or objects with label and value properties */
-    options: StyleEditorOption[];
     /**
-     * Optional default checked state as a record mapping option values to boolean.
-     * Keys should match the option values, values indicate whether the option is checked.
+     * Array of checkbox options. Each option contains:
+     * - `label`: Display text shown to users
+     * - `key`: Unique identifier used in the normalized defaultValue object
+     * - `value`: Default checked state (true = checked, false = unchecked)
      */
-    defaultValue?: StyleEditorCheckboxDefaultValue;
+    options: StyleEditorCheckboxOption[];
 }
 /**
  * Union type of all possible field definitions.
@@ -397,10 +543,18 @@ export interface StyleEditorCheckboxGroupField extends StyleEditorBaseField {
  * @example
  * ```typescript
  * const fields: StyleEditorField[] = [
- *   { type: 'input', label: 'Font Size', inputType: 'number', defaultValue: 16 },
- *   { type: 'dropdown', label: 'Font Family', options: ['Arial', 'Helvetica'] },
- *   { type: 'radio', label: 'Theme', options: ['Light', 'Dark'] },
- *   { type: 'checkboxGroup', label: 'Styles', options: ['Bold', 'Italic'] }
+ *   { type: 'input', id: 'font-size', label: 'Font Size', inputType: 'number', defaultValue: 16 },
+ *   { type: 'dropdown', id: 'font-family', label: 'Font Family', options: ['Arial', 'Helvetica'] },
+ *   { type: 'radio', id: 'theme', label: 'Theme', options: ['Light', 'Dark'] },
+ *   {
+ *     type: 'checkboxGroup',
+ *     id: 'styles',
+ *     label: 'Styles',
+ *     options: [
+ *       { label: 'Bold', key: 'bold', value: true },
+ *       { label: 'Italic', key: 'italic', value: false }
+ *     ]
+ *   }
  * ];
  *
  * // TypeScript can narrow the type based on the discriminator
@@ -508,9 +662,9 @@ export interface StyleEditorForm {
  *
  * **Note:** All properties are optional since different field types use different subsets:
  * - Input fields use: `inputType`, `placeholder`, `defaultValue`
- * - Dropdown fields use: `options`, `placeholder`, `defaultValue`
+ * - Dropdown fields use: `options`, `defaultValue`
  * - Radio fields use: `options`, `columns`, `defaultValue`
- * - Checkbox fields use: `options`, `defaultValue`
+ * - Checkbox fields use: `options`, `defaultValue` (derived from option values during normalization)
  */
 export interface StyleEditorFieldSchemaConfig {
     /** Optional input type for input fields ('text' or 'number') */