@refinitiv-ui/elements 5.5.0 → 5.8.1

package/lib/number-field/custom-elements.json

@@ -3,13 +3,8 @@
   "tags": [
     {
       "name": "ef-number-field",
-      "description": "Form control element for numbers",
+      "description": "Form control element for numbers.",
       "attributes": [
-        {
-          "name": "placeholder",
-          "description": "Set placeholder text",
-          "type": "string | null"
-        },
         {
           "name": "no-spinner",
           "description": "Set spinner's visibility",
@@ -32,26 +27,20 @@
           "type": "string | null"
         },
         {
-          "name": "transparent",
-          "description": "Set state to transparent",
+          "name": "disabled",
+          "description": "Set disabled state",
           "type": "boolean",
           "default": "false"
         },
         {
           "name": "error",
-          "description": "Set state to error",
+          "description": "Set error state",
           "type": "boolean",
           "default": "false"
         },
         {
-          "name": "warning",
-          "description": "Set state to warning",
-          "type": "boolean",
-          "default": "false"
-        },
-        {
-          "name": "value",
-          "description": "The value of the number entered into the input.",
+          "name": "placeholder",
+          "description": "Set placeholder text",
           "type": "string",
           "default": "\"\""
         },
@@ -59,22 +48,28 @@
           "name": "readonly",
           "description": "Set readonly state",
           "type": "boolean",
-          "default": "\"false\""
+          "default": "false"
         },
         {
-          "name": "disabled",
-          "description": "Set disabled state",
+          "name": "transparent",
+          "description": "Disables all other states and border/background styles.",
           "type": "boolean",
-          "default": "\"false\""
+          "default": "false"
+        },
+        {
+          "name": "warning",
+          "description": "Set warning state",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "value",
+          "description": "The value of the number entered into the input.",
+          "type": "string",
+          "default": "\"\""
         }
       ],
       "properties": [
-        {
-          "name": "placeholder",
-          "attribute": "placeholder",
-          "description": "Set placeholder text",
-          "type": "string | null"
-        },
         {
           "name": "noSpinner",
           "attribute": "no-spinner",
@@ -101,35 +96,40 @@
           "type": "string | null"
         },
         {
-          "name": "transparent",
-          "attribute": "transparent",
-          "description": "Set state to transparent",
-          "type": "boolean",
-          "default": "false"
+          "name": "valueAsNumber (readonly)",
+          "description": "Returns the value of the element, interpreted as double number",
+          "type": "number"
         },
         {
-          "name": "error",
-          "attribute": "error",
-          "description": "Set state to error",
-          "type": "boolean",
-          "default": "false"
+          "name": "selectionStart",
+          "type": "number | null"
         },
         {
-          "name": "warning",
-          "attribute": "warning",
-          "description": "Set state to warning",
+          "name": "selectionEnd",
+          "type": "number | null"
+        },
+        {
+          "name": "selectionDirection",
+          "type": "\"forward\" | \"backward\" | \"none\" | null"
+        },
+        {
+          "name": "disabled",
+          "attribute": "disabled",
+          "description": "Set disabled state",
           "type": "boolean",
           "default": "false"
         },
         {
-          "name": "valueAsNumber",
-          "description": "Returns the value of the element, interpreted as double number",
-          "type": "number"
+          "name": "error",
+          "attribute": "error",
+          "description": "Set error state",
+          "type": "boolean",
+          "default": "false"
         },
         {
-          "name": "value",
-          "attribute": "value",
-          "description": "The value of the number entered into the input.",
+          "name": "placeholder",
+          "attribute": "placeholder",
+          "description": "Set placeholder text",
           "type": "string",
           "default": "\"\""
         },
@@ -138,14 +138,28 @@
           "attribute": "readonly",
           "description": "Set readonly state",
           "type": "boolean",
-          "default": "\"false\""
+          "default": "false"
         },
         {
-          "name": "disabled",
-          "attribute": "disabled",
-          "description": "Set disabled state",
+          "name": "transparent",
+          "attribute": "transparent",
+          "description": "Disables all other states and border/background styles.",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "warning",
+          "attribute": "warning",
+          "description": "Set warning state",
           "type": "boolean",
-          "default": "\"false\""
+          "default": "false"
+        },
+        {
+          "name": "value",
+          "attribute": "value",
+          "description": "The value of the number entered into the input.",
+          "type": "string",
+          "default": "\"\""
         }
       ],
       "events": [
@@ -159,6 +173,26 @@
         }
       ],
       "methods": [
+        {
+          "name": "onInputInput",
+          "description": "",
+          "params": [
+            {
+              "name": "event",
+              "type": "InputEvent"
+            }
+          ]
+        },
+        {
+          "name": "onInputChange",
+          "description": "",
+          "params": [
+            {
+              "name": "event",
+              "type": "InputEvent"
+            }
+          ]
+        },
         {
           "name": "stepUp",
           "description": "Increases the input value by amount of step",
@@ -190,9 +224,20 @@
           "params": []
         },
         {
-          "name": "select",
-          "description": "Select the contents of input",
-          "params": []
+          "name": "setSelectionRange",
+          "description": "",
+          "params": [
+            {
+              "name": "startSelection"
+            },
+            {
+              "name": "endSelection"
+            },
+            {
+              "name": "selectionDirection",
+              "type": "SelectionDirection"
+            }
+          ]
         }
       ]
     }

package/lib/number-field/custom-elements.md

@@ -0,0 +1,42 @@
+# ef-number-field
+
+Form control element for numbers.
+
+## Properties
+
+| Property                   | Attribute     | Type                                        | Default | Description                                      |
+|----------------------------|---------------|---------------------------------------------|---------|--------------------------------------------------|
+| `disabled`                 | `disabled`    | `boolean`                                   | false   | Set disabled state                               |
+| `error`                    | `error`       | `boolean`                                   | false   | Set error state                                  |
+| `max`                      | `max`         | `string \| null`                            | null    | Set maximum value.<br />This value must be greater than or equal to the value of the `min` attribute |
+| `min`                      | `min`         | `string \| null`                            | null    | Set minimum value.<br />This value must be less than or equal to the value of the `max` attribute |
+| `noSpinner`                | `no-spinner`  | `boolean`                                   | false   | Set spinner's visibility                         |
+| `placeholder`              | `placeholder` | `string`                                    | ""      | Set placeholder text                             |
+| `readonly`                 | `readonly`    | `boolean`                                   | false   | Set readonly state                               |
+| `selectionDirection`       |               | `"forward" \| "backward" \| "none" \| null` |         |                                                  |
+| `selectionEnd`             |               | `number \| null`                            |         |                                                  |
+| `selectionStart`           |               | `number \| null`                            |         |                                                  |
+| `step`                     | `step`        | `string \| null`                            | null    | Set step value                                   |
+| `transparent`              | `transparent` | `boolean`                                   | false   | Disables all other states and border/background styles. |
+| `value`                    | `value`       | `string`                                    | ""      | The value of the number entered into the input.  |
+| `valueAsNumber (readonly)` |               | `number`                                    |         | Returns the value of the element, interpreted as double number |
+| `warning`                  | `warning`     | `boolean`                                   | false   | Set warning state                                |
+
+## Methods
+
+| Method              | Type                                             | Description                                      |
+|---------------------|--------------------------------------------------|--------------------------------------------------|
+| `checkValidity`     | `(): boolean`                                    | Returns true if an input element contains valid data. |
+| `onInputChange`     | `(event: any): void`                             |                                                  |
+| `onInputInput`      | `(event: any): void`                             |                                                  |
+| `reportValidity`    | `(): boolean`                                    | Validate input. Mark as error if input is invalid |
+| `setSelectionRange` | `(startSelection: number \| null, endSelection: number \| null, selectionDirection?: "forward" \| "backward" \| "none" \| undefined): void` |                                                  |
+| `stepDown`          | `(stepIncrement?: number \| undefined): void`    | Decreases the input value by amount of step<br /><br />**stepIncrement**: The stepIncrement parameter is a numeric value. If no parameter is passed, stepIncrement defaults to 1. |
+| `stepUp`            | `(stepIncrement?: number \| undefined): void`    | Increases the input value by amount of step<br /><br />**stepIncrement**: The stepIncrement parameter is a numeric value. If no parameter is passed, stepIncrement defaults to 1. |
+
+## Events
+
+| Event           | Description                         |
+|-----------------|-------------------------------------|
+| `error-changed` | Dispatched when error state changes |
+| `value-changed` | Dispatched when value changes       |

package/lib/number-field/index.d.ts

@@ -1,38 +1,52 @@
 import { JSXInterface } from '../jsx';
-import { ControlElement, CSSResult, TemplateResult, PropertyValues } from '@refinitiv-ui/core';
-import '../icon';
+import { FormFieldElement, CSSResultGroup, TemplateResult, PropertyValues, TapEvent } from '@refinitiv-ui/core';
+import { TemplateMap } from '@refinitiv-ui/core/lib/directives/template-map.js';
+import '../icon/index.js';
+declare type SelectionDirection = 'forward' | 'backward' | 'none';
+declare enum Direction {
+    Up = 1,
+    Down = -1
+}
 /**
- * Form control element for numbers
+ * Form control element for numbers.
  *
  * @fires value-changed - Dispatched when value changes
  * @fires error-changed - Dispatched when error state changes
  *
- * @attr {string} value - Input's default value
- * @prop {string} [value=] - Input's value
+ * @attr {boolean} disabled - Set disabled state
+ * @prop {boolean} [disabled=false] - Set disabled state
+ *
+ * @attr {boolean} error - Set error state
+ * @prop {boolean} [error=false] - Set error state
+ *
+ * @attr {string} placeholder - Set placeholder text
+ * @prop {string} [placeholder=""] - Set placeholder text
  *
  * @attr {boolean} readonly - Set readonly state
  * @prop {boolean} [readonly=false] - Set readonly state
  *
- * @attr {boolean} disabled - Set disabled state
- * @prop {boolean} [disabled=false] - Set disabled state
+ * @attr {boolean} transparent - Disables all other states and border/background styles.
+ * @prop {boolean} [transparent=false] - Disables all other states and border/background styles.
+ *
+ * @attr {boolean} warning - Set warning state
+ * @prop {boolean} [warning=false] - Set warning state
+ *
+ * @attr {string} value - Input's value
+ * @prop {string} [value=""] - Input's value
  */
-export declare class NumberField extends ControlElement {
+export declare class NumberField extends FormFieldElement {
     /**
      * Element version number
      * @returns version number
      */
     static get version(): string;
     /**
-     * A `CSSResult` that will be used
+     * A `CSSResultGroup` that will be used
      * to style the host, slotted children
      * and the internal template of the element.
-     * @return {CSSResult | CSSResult[]} CSS template
+     * @return CSS template
      */
-    static get styles(): CSSResult | CSSResult[];
-    /**
-     * Set placeholder text
-     */
-    placeholder: string | null;
+    static get styles(): CSSResultGroup;
     /**
      * Set spinner's visibility
      */
@@ -51,22 +65,11 @@ export declare class NumberField extends ControlElement {
      * This value must be greater than or equal to the value of the `min` attribute
      */
     max: string | null;
-    /**
-     * Set state to transparent
-     */
-    transparent: boolean;
-    /**
-     * Set state to error
-     */
-    error: boolean;
-    /**
-     * Set state to warning
-     */
-    warning: boolean;
     private interimValueState;
     /**
     * The value of the number entered into the input.
     * @param value number-field value
+    * @default -
     */
     set value(value: string);
     get value(): string;
@@ -74,10 +77,6 @@ export declare class NumberField extends ControlElement {
      * Returns the value of the element, interpreted as double number
      */
     get valueAsNumber(): number;
-    /**
-     * Get native input element from shadow root
-     */
-    private inputEl;
     /**
      * Get spinner up element
      */
@@ -145,47 +144,49 @@ export declare class NumberField extends ControlElement {
      * @returns string of input value
      */
     private get internalValue();
-    /**
-     * Get native input value
-     * @returns string of input value
-     */
-    private get inputValue();
-    /**
-     * Set native input value
-     * @param value input's value
-     */
-    private set inputValue(value);
     /**
      * Handles key down input event
      * @param event Key down event object
      * @returns {void}
      */
-    private onNativeInputKeyDown;
+    protected onInputKeyDown(event: KeyboardEvent): void;
     /**
      * Run when spinner has been tapped
      * @param event tap event
      * @returns {void}
      */
-    private onSpinnerTap;
+    protected onSpinnerTap(event: TapEvent): void;
     /**
      * Step down or up and notify value change
      * @param direction Up or Down
      * @returns {void}
      */
-    private onApplyStep;
+    protected onApplyStep(direction: Direction): void;
     /**
      * Run before input changes
      * Prevent invalid characters
      * @param event before input event
      * @returns {void}
      */
-    private onNativeBeforeInputChange;
+    protected onBeforeInputChange(event: InputEvent): void;
+    /**
+     * Runs on input element `input` event
+     * @param event `input` event
+     * @returns {void}
+     */
+    protected onInputInput(event: InputEvent): void;
+    /**
+     * Runs on input element `change` event
+     * @param event `change` event
+     * @returns {void}
+     */
+    protected onInputChange(event: InputEvent): void;
     /**
      * Triggers when native input value change with input event or change event
      * @param event Input event
      * @returns {void}
      */
-    private onNativeInputChange;
+    protected onNativeInputChange(event: InputEvent): void;
     /**
      * Stripe characters from input text based on previous input and data
      * @param input The new input to process
@@ -262,15 +263,58 @@ export declare class NumberField extends ControlElement {
      */
     reportValidity(): boolean;
     /**
-     * Select the contents of input
-     * @returns void
+     * @ignore
+     * @inheritDoc
+     */
+    get selectionStart(): number | null;
+    /**
+     * @ignore
+     * @inheritDoc
+     */
+    set selectionStart(index: number | null);
+    /**
+     * @ignore
+     * @inheritDoc
      */
-    select(): void;
+    get selectionEnd(): number | null;
+    /**
+     * @ignore
+     * @inheritDoc
+     */
+    set selectionEnd(index: number | null);
+    /**
+     * @ignore
+     * @inheritDoc
+     */
+    get selectionDirection(): SelectionDirection | null;
+    /**
+     * @ignore
+     * @inheritDoc
+     */
+    set selectionDirection(direction: SelectionDirection | null);
+    /**
+     * @ignore
+     * @inheritDoc
+     */
+    setSelectionRange(startSelection: number | null, endSelection: number | null, selectionDirection?: SelectionDirection): void;
     /**
      * Renders spinner
      * @returns {TemplateResult} spinner part template
      */
-    private renderSpinner;
+    protected renderSpinner(): TemplateResult;
+    /**
+     * Decorate `<input>` element with common properties extended from form field element:
+     * type="text" - always `text`
+     * part="input" - always "input", used for styling
+     * inputmode="decimal" - show decimals keyboard by default
+     * pattern="'^[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?$'" - numbers only
+     * role="spinbutton" - number field is actually a spinner
+     * aria-valuenow - current value or 0
+     * @keydown - Listener for `keydown` event. Runs `this.onInputKeyDown`
+     * @beforeinput - Listener for `beforeinput` event. Runs `this.onBeforeInputChange`
+     * @returns template map
+     */
+    protected get decorateInputMap(): TemplateMap;
     /**
      * A `TemplateResult` that will be used
      * to render the updated internal template.
@@ -278,6 +322,7 @@ export declare class NumberField extends ControlElement {
      */
     protected render(): TemplateResult;
 }
+export {};
 
 declare global {
   interface HTMLElementTagNameMap {
@@ -286,7 +331,7 @@ declare global {
 
   namespace JSX {
     interface IntrinsicElements {
-      'ef-number-field': Partial<NumberField> | JSXInterface.ControlHTMLAttributes<NumberField>;
+      'ef-number-field': Partial<NumberField> | JSXInterface.HTMLAttributes<NumberField>;
     }
   }
 }