Describe the Masks API (#7976)

* Describe the Masks API

* Fix a typo

docs/sidebar.json

@@ -134,7 +134,7 @@
     },
     {
       "Name": "api",
-      "Title": "API",
+      "Title": "Form Library API",
       "Items": [
         {
           "Name": "surveymodel",
@@ -256,6 +256,22 @@
           "Name": "ICustomQuestionTypeConfiguration",
           "Title": "ICustomQuestionTypeConfiguration"
         },
+        {
+          "Name": "inputmasknumeric",
+          "Title": "InputMaskNumeric"
+        },
+        {
+          "Name": "inputmaskcurrency",
+          "Title": "InputMaskCurrency"
+        },
+        {
+          "Name": "inputmaskdatetime",
+          "Title": "InputMaskDateTime"
+        },
+        {
+          "Name": "inputmaskpattern",
+          "Title": "InputMaskPattern"
+        },
         {
           "Name": "settings",
           "Title": "Global Settings"

src/mask/mask_base.ts

@@ -3,6 +3,11 @@ import { JsonObject, Serializer, property } from "../jsonobject";
 import { IInputMask, IMaskedInputResult, ITextInputParams } from "./mask_utils";
 
 export class InputMaskBase extends Base implements IInputMask {
+  /**
+   * Specifies whether to store the question value with an applied mask in survey results.
+   *
+   * Default value: `false`
+   */
   @property() saveMaskedValue: boolean;
 
   public getType(): string {

src/mask/mask_currency.ts

@@ -2,8 +2,34 @@ import { Serializer, property } from "../jsonobject";
 import { InputMaskNumeric } from "./mask_numeric";
 import { IMaskedInputResult, ITextInputParams } from "./mask_utils";
 
+/**
+ * A class that describes an input mask of the `"currency"` [`maskType`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maskType).
+ *
+ * The following code shows how to specify the properties of this class within a survey JSON schema:
+ *
+ * ```
+ * const surveyJson = {
+ *   "elements": [{
+ *     "name": "textquestion1"
+ *     "type": "text",
+ *     "maskType": "currency",
+ *     "maskSettings": {
+ *       // Specify the properties of a currency input mask here
+ *     }
+ *   }]
+ * }
+ * ```
+ */
 export class InputMaskCurrency extends InputMaskNumeric {
+  /**
+   * One or several symbols to be displayed before the currency value.
+   * @see suffix
+   */
   @property() prefix: string;
+  /**
+   * One or several symbols to be displayed after the currency value.
+   * @see prefix
+   */
   @property() suffix: string;
 
   public getType(): string {

src/mask/mask_datetime.ts

@@ -101,12 +101,37 @@ export function getDateTimeLexems(pattern: string): Array<IDateTimeMaskLexem> {
   return result;
 }
 
+/**
+ * A class that describes an input mask of the `"datetime"` [`maskType`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maskType).
+ *
+ * The following code shows how to specify the properties of this class within a survey JSON schema:
+ *
+ * ```
+ * const surveyJson = {
+ *   "elements": [{
+ *     "name": "textquestion1"
+ *     "type": "text",
+ *     "maskType": "datetime",
+ *     "maskSettings": {
+ *       // Specify the properties of a date-time input mask here
+ *     }
+ *   }]
+ * }
+ * ```
+ */
 export class InputMaskDateTime extends InputMaskPattern {
   private turnOfTheCentury = 68;
   private lexems: Array<IDateTimeMaskLexem> = [];
   private inputDateTimeData: Array<IInputDateTimeData> = [];
-
+  /**
+   * A minimum date and time value that respondents can enter.
+   * @see max
+   */
   @property() min: string;
+  /**
+   * A maximum date and time value that respondents can enter.
+   * @see min
+   */
   @property() max: string;
 
   public getType(): string {

src/mask/mask_numeric.ts

@@ -26,12 +26,66 @@ export function splitString(str: string, reverse = true, n = 3): Array<string> {
   return arr;
 }
 
+/**
+ * A class that describes an input mask of the `"numeric"` [`maskType`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maskType).
+ *
+ * The following code shows how to specify the properties of this class within a survey JSON schema:
+ *
+ * ```
+ * const surveyJson = {
+ *   "elements": [{
+ *     "name": "textquestion1"
+ *     "type": "text",
+ *     "maskType": "numeric",
+ *     "maskSettings": {
+ *       // Specify the properties of a numeric input mask here
+ *     }
+ *   }]
+ * }
+ * ```
+ */
 export class InputMaskNumeric extends InputMaskBase {
+  /**
+   * Specifies whether respondents can enter negative values.
+   *
+   * Default value: `true`
+   * @see min
+   * @see max
+   */
   @property() allowNegativeValues: boolean;
+  /**
+   * A symbol used to separate the fractional part from the integer part of a displayed number.
+   *
+   * Default value: `"."`
+   * @see precision
+   * @see thousandsSeparator
+   */
   @property() decimalSeparator: string;
+  /**
+   * Limits how many digits to retain after the decimal point for a displayed number.
+   *
+   * Default value: 2
+   * @see decimalSeparator
+   */
   @property() precision: number;
+  /**
+   * A symbol used to separate the digits of a large number into groups of three.
+   *
+   * Default value: `","`
+   * @see decimalSeparator
+   */
   @property() thousandsSeparator: string;
+  /**
+   * A minimum value that respondents can enter.
+   * @see max
+   * @see allowNegativeValues
+   */
   @property() min: number;
+  /**
+   * A maximum value that respondents can enter.
+   * @see min
+   * @see allowNegativeValues
+   */
   @property() max: number;
 
   private calccaretPosition(leftPart: string, args: ITextInputParams, maskedValue: string) {

src/mask/mask_pattern.ts

@@ -98,9 +98,52 @@ export function getUnmaskedValueByPattern(str: string, pattern: string | Array<I
   return result;
 }
 
+/**
+ * A class that describes an input mask of the `"pattern"` [`maskType`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maskType).
+ *
+ * The following code shows how to specify the properties of this class within a survey JSON schema:
+ *
+ * ```
+ * const surveyJson = {
+ *   "elements": [{
+ *     "name": "textquestion1"
+ *     "type": "text",
+ *     "maskType": "pattern",
+ *     "maskSettings": {
+ *       // Specify the properties of a pattern input mask here
+ *     }
+ *   }]
+ * }
+ * ```
+ */
 export class InputMaskPattern extends InputMaskBase {
   private literals: Array<IMaskLiteral> = [];
 
+  /**
+   * A pattern for the input value.
+   *
+   * If you set the [`maskType`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maskType) to `"pattern"`, the mask can contain string literals and the following placeholders:
+   *
+   * - `9` - A digit.
+   * - `a` - An upper- or lower-case letter.
+   * - `#` - A digit or an upper- or lower-case letter.
+   *
+   * Use backslash `\` to escape a character.
+   *
+   * Example: `+1(999)-999-99-99`
+   *
+   * If you set the [`maskType`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maskType) to `"datetime"`, the mask can contain separator characters and the following placeholders:
+   *
+   * - `m` - Month number.
+   * - `mm` - Month number, with leading zero for single-digit values.
+   * - `d` - Day of the month.
+   * - `dd` - Day of the month, with leading zero for single-digit values.
+   * - `yy` - Last two digits of the year.
+   * - `yyyy` - A four-digit year.
+   *
+   * Example: `mm/dd/yyyy`
+   * @see [settings.maskSettings](https://surveyjs.io/form-library/documentation/api-reference/settings#maskSettings)
+   */
   @property() pattern: string;
 
   protected updateLiterals(): void {

src/question_text.ts

@@ -45,6 +45,18 @@ export class QuestionTextModel extends QuestionTextBase {
     this.updateMaskAdapter();
   }
 
+  /**
+   * Specifies the type of a mask applied to the input.
+   *
+   * Possible values:
+   *
+   * - `"none"` (default)
+   * - `"numeric"`
+   * - `"currency"`
+   * - `"datetime"`
+   * - `"pattern"`
+   * @see maskSettings
+   */
   @property({
     onSet: (newValue: string, target: QuestionTextModel) => { target.onSetMaskType(newValue); }
   }) maskType: string;
@@ -53,6 +65,18 @@ export class QuestionTextModel extends QuestionTextBase {
     return this.maskType === "none";
   }
 
+  /**
+   * An object with properties that configure the mask applied to the input.
+   *
+   * Available properties depend on the specified [`maskType`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maskType) and belong to corresponding classes. Refer to the class APIs for a full list of properties:
+   *
+   * | `maskType` | Class |
+   * | ---------- | ----- |
+   * | `"numeric"` | [`InputMaskNumeric`](https://surveyjs.io/form-library/documentation/api-reference/inputmasknumeric) |
+   * | `"currency"` | [`InputMaskCurrency`](https://surveyjs.io/form-library/documentation/api-reference/inputmaskcurrency) |
+   * | `"datetime"` | [`InputMaskDateTime`](https://surveyjs.io/form-library/documentation/api-reference/inputmaskdatetime) |
+   * | `"pattern"` | [`InputMaskPattern`](https://surveyjs.io/form-library/documentation/api-reference/inputmaskpattern) |
+   */
   public get maskSettings(): InputMaskBase {
     return this.getPropertyValue("maskSettings");
   }

src/settings.ts

@@ -78,7 +78,7 @@ export var settings = {
    * Nested properties:
    *
    * - `useLocalTimeZone`: `boolean`\
-   * Disable this property if you want internal SurveyJS functions to use methods that work with UTC date and time (`setUTCDate()` `setUTCHours()`, etc.) instead of methods that work with local date and time (`setYear`, `setHours()`, etc.). Default value: `true`.
+   * Disable this property if you want internal SurveyJS functions to use methods that work with UTC date and time (`setUTCDate()` `setUTCHours()`, etc.) instead of methods that work with local date and time (`setYear()`, `setHours()`, etc.). Default value: `true`.
    *
    * - `defaultLocaleName`: `string`\
    * A property key that stores a translation for the default locale. Default value: `"default"`.
@@ -731,6 +731,20 @@ export var settings = {
     ]
   },
   legacyProgressBarView: false,
+  /**
+   * An object with properties that configure input masks.
+   *
+   * Nested properties:
+   *
+   * - `patternPlaceholderChar`: `string`\
+   * A symbol used as a placeholder for characters to be entered in [pattern masks](https://surveyjs.io/form-library/documentation/api-reference/inputmaskpattern). Default value: `"_"`.
+   *
+   * - `patternEscapeChar`: `string`\
+   * A symbol used to insert literal representations of special characters in [pattern masks](https://surveyjs.io/form-library/documentation/api-reference/inputmaskpattern). Default value: `"\\"`.
+   *
+   * - `patternDefinitions`: `<{ [key: string]: RegExp }>`\
+   * An object that maps placeholder symbols to regular expressions in [pattern masks](https://surveyjs.io/form-library/documentation/api-reference/inputmaskpattern). Default value: `{ "9": /[0-9]/, "a": /[a-zA-Z]/, "#": /[a-zA-Z0-9]/ }`.
+   */
   maskSettings: {
     patternPlaceholderChar: "_",
     patternEscapeChar: "\\",

src/survey.ts

@@ -2616,7 +2616,7 @@ export class SurveyModel extends SurveyElementCore
    * - `"belowHeader"` - Displays the progress bar below the survey header.
    * - `"bottom"` - Displays the progress bar below survey content.
    * - `"topBottom"` - Displays the progress bar above and below survey content.
-   * - `"auto"` - Automatically selects between `"aboveHeader"` and `"belowHeader"`.
+   * - `"auto"` - Displays the progress bar below the survey header if the header has a [background image](https://surveyjs.io/form-library/documentation/api-reference/iheader#backgroundImage) or color. Otherwise, the progress bar is displayed above the header.
    * - `"top"` - *(Obsolete)* Use the `"aboveHeader"` or `"belowHeader"` property value instead.
    * - `"both"` - *(Obsolete)* Use the `"topBottom"` property value instead.
    *