From edab346a605b5e968b29736c070a03091c0a173e Mon Sep 17 00:00:00 2001
From: RomanTsukanov <sergeich16@gmail.com>
Date: Tue, 11 Feb 2025 16:55:13 +0400
Subject: [PATCH] Describe theme-related APIs

---
 .../survey-creator-core/src/creator-base.ts   | 35 ++++++++++++++++---
 .../src/creator-events-api.ts                 |  6 ++++
 .../src/creator-options.ts                    |  5 +++
 3 files changed, 42 insertions(+), 4 deletions(-)

diff --git a/packages/survey-creator-core/src/creator-base.ts b/packages/survey-creator-core/src/creator-base.ts
index 41b8cc2a41..adbae83945 100644
--- a/packages/survey-creator-core/src/creator-base.ts
+++ b/packages/survey-creator-core/src/creator-base.ts
@@ -180,6 +180,11 @@ export class SurveyCreatorModel extends Base
    * @see saveThemeFunc
    */
   @property({ defaultValue: false }) showThemeTab: boolean;
+  /**
+   * Specifies whether users can modify the [Survey Creator theme](https://surveyjs.io/survey-creator/documentation/api-reference/survey-creator#creatorTheme). Applies only if [`propertyGridNavigationMode`](https://surveyjs.io/survey-creator/documentation/api-reference/survey-creator#propertyGridNavigationMode) is `"buttons"`.
+   * 
+   * Default value: `true`
+   */
   @property({ defaultValue: true }) showCreatorThemeSettings: boolean;
   /**
    * Specifies whether the "Zoom In", "Zoom Out", and "Zoom to 100%" buttons are available.
@@ -957,6 +962,9 @@ export class SurveyCreatorModel extends Base
    * ```
    */
   public onCreateCustomMessagePanel: EventBase<SurveyCreatorModel, CreateCustomMessagePanelEvent> = this.addCreatorEvent<SurveyCreatorModel, CreateCustomMessagePanelEvent>();
+  /**
+   * An event that is raised when users change a property in a [Survey Creator theme](https://surveyjs.io/survey-creator/documentation/api-reference/survey-creator#creatorTheme).
+   */
   public onCreatorThemePropertyChanged: EventBase<SurveyCreatorModel, CreatorThemePropertyChangedEvent> = this.addCreatorEvent<SurveyCreatorModel, CreatorThemePropertyChangedEvent>();
 
   public getSurveyJSONTextCallback: () => { text: string, isModified: boolean };
@@ -3085,6 +3093,11 @@ export class SurveyCreatorModel extends Base
     return val;
   }
 
+  /**
+   * Opens [Survey Creator theme](https://surveyjs.io/survey-creator/documentation/api-reference/survey-creator#creatorTheme) settings in Property Grid. Applies only if [`propertyGridNavigationMode`](https://surveyjs.io/survey-creator/documentation/api-reference/survey-creator#propertyGridNavigationMode) is `"buttons"`.
+   * @see closeCreatorThemeSettings
+   * @see showCreatorThemeSettings
+   */
   public openCreatorThemeSettings(): void {
     const designerPlugin = this.getPlugin("designer") as TabDesignerPlugin;
     if (designerPlugin) {
@@ -3092,6 +3105,11 @@ export class SurveyCreatorModel extends Base
     }
   }
 
+  /**
+   * Closes [Survey Creator theme](https://surveyjs.io/survey-creator/documentation/api-reference/survey-creator#creatorTheme) settings in Property Grid. Applies only if [`propertyGridNavigationMode`](https://surveyjs.io/survey-creator/documentation/api-reference/survey-creator#propertyGridNavigationMode) is `"buttons"`.
+   * @see openCreatorThemeSettings
+   * @see showCreatorThemeSettings
+   */
   public closeCreatorThemeSettings(): void {
     const designerPlugin = this.getPlugin("designer") as TabDesignerPlugin;
     if (designerPlugin) {
@@ -3099,6 +3117,10 @@ export class SurveyCreatorModel extends Base
     }
   }
 
+  /**
+   * Activates a specified category in Property Grid. Applies only if [`propertyGridNavigationMode`](https://surveyjs.io/survey-creator/documentation/api-reference/survey-creator#propertyGridNavigationMode) is `"buttons"`.
+   * @param name A [category name](https://surveyjs.io/form-library/documentation/customize-question-types/add-custom-properties-to-a-form#category).
+   */
   public activatePropertyGridCategory(name: string): void {
     if (!!this.designerPropertyGrid) {
       this.designerPropertyGrid.activateCategory(name);
@@ -3115,7 +3137,7 @@ export class SurveyCreatorModel extends Base
     return this.designerPropertyGrid.survey;
   }
   /**
-   * Collapses a specified category in Property Grid.
+   * Collapses a specified category in Property Grid. Applies only if [`propertyGridNavigationMode`](https://surveyjs.io/survey-creator/documentation/api-reference/survey-creator#propertyGridNavigationMode) is `"accordion"`.
    * @param name A [category name](https://surveyjs.io/form-library/documentation/customize-question-types/add-custom-properties-to-a-form#category).
    * @see expandPropertyGridCategory
    */
@@ -3125,9 +3147,10 @@ export class SurveyCreatorModel extends Base
     }
   }
   /**
-   * Expands a specified category in Property Grid.
+   * Expands a specified category in Property Grid. Applies only if [`propertyGridNavigationMode`](https://surveyjs.io/survey-creator/documentation/api-reference/survey-creator#propertyGridNavigationMode) is `"accordion"`.
    * @param name A [category name](https://surveyjs.io/form-library/documentation/customize-question-types/add-custom-properties-to-a-form#category).
    * @see collapsePropertyGridCategory
+   * @see activatePropertyGridCategory
    */
   public expandPropertyGridCategory(name: string) {
     if (!!this.designerPropertyGrid) {
@@ -3135,7 +3158,7 @@ export class SurveyCreatorModel extends Base
     }
   }
   /**
-   * Collapses all categories in Property Grid.
+   * Collapses all categories in Property Grid. Applies only if [`propertyGridNavigationMode`](https://surveyjs.io/survey-creator/documentation/api-reference/survey-creator#propertyGridNavigationMode) is `"accordion"`.
    * @see expandAllPropertyGridCategories
    */
   public collapseAllPropertyGridCategories() {
@@ -3144,7 +3167,7 @@ export class SurveyCreatorModel extends Base
     }
   }
   /**
-   * Expands all categories in Property Grid.
+   * Expands all categories in Property Grid. Applies only if [`propertyGridNavigationMode`](https://surveyjs.io/survey-creator/documentation/api-reference/survey-creator#propertyGridNavigationMode) is `"accordion"`.
    * @see collapseAllPropertyGridCategories
    */
   public expandAllPropertyGridCategories() {
@@ -4264,6 +4287,10 @@ export class SurveyCreatorModel extends Base
   }
 
   @property({ defaultValue: {} }) themeVariables: { [index: string]: string } = {};
+  /**
+   * Gets or sets a theme for the Survey Creator UI.
+   * @see showCreatorThemeSettings
+   */
   @property() creatorTheme: ICreatorTheme;
 
   public preferredColorPalette: string = "light";
diff --git a/packages/survey-creator-core/src/creator-events-api.ts b/packages/survey-creator-core/src/creator-events-api.ts
index 4d2bba0dc7..0891b7d895 100644
--- a/packages/survey-creator-core/src/creator-events-api.ts
+++ b/packages/survey-creator-core/src/creator-events-api.ts
@@ -1089,6 +1089,12 @@ export interface DragStartEndEvent {
   toElement: IElement;
 }
 export interface CreatorThemePropertyChangedEvent {
+  /**
+   * A property name.
+   */
   name: string;
+  /**
+   * A new property value.
+   */
   value: any;
 }
\ No newline at end of file
diff --git a/packages/survey-creator-core/src/creator-options.ts b/packages/survey-creator-core/src/creator-options.ts
index e5384fd49f..a655c115b2 100644
--- a/packages/survey-creator-core/src/creator-options.ts
+++ b/packages/survey-creator-core/src/creator-options.ts
@@ -52,6 +52,11 @@ export interface ICreatorOptions {
    * [Theme Editor](https://surveyjs.io/survey-creator/documentation/theme-editor (linkStyle))
    */
   showThemeTab?: boolean;
+  /**
+   * Specifies whether users can modify the [Survey Creator theme](https://surveyjs.io/survey-creator/documentation/api-reference/survey-creator#creatorTheme). Applies only if [`propertyGridNavigationMode`](https://surveyjs.io/survey-creator/documentation/api-reference/icreatoroptions#propertyGridNavigationMode) is `"buttons"`.
+   * 
+   * Default value: `true`
+   */
   showCreatorThemeSettings?: boolean;
   /**
    * Specifies whether the "Zoom In", "Zoom Out", and "Zoom to 100%" buttons are available.