@refinitiv-ui/elements 5.12.2 → 6.0.0-next.2

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

@@ -0,0 +1,322 @@
+import { JSXInterface } from '../jsx';
+import { PropertyValues, TemplateResult } from '@refinitiv-ui/core';
+import { TemplateMap } from '@refinitiv-ui/core/directives/template-map.js';
+import { Locale } from '@refinitiv-ui/utils/date.js';
+import { TranslateDirective } from '@refinitiv-ui/translate';
+import { NavigationKeys, DateTimeFormatPart } from './types';
+import { TextField } from '../text-field/index.js';
+import '@refinitiv-ui/phrasebook/locale/en/datetime-field.js';
+/**
+ * A form control element for datetime input.
+ *
+ * @fires value-changed - Dispatched when value changes
+ * @fires error-changed - Dispatched when error state changes
+ * @fires icon-click - Dispatched when icon is clicked
+ *
+ * @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} icon - Specify icon to display in input. Value can be icon name
+ * @prop {string | null} [icon=null] - Specify icon to display in input. Value can be icon name
+ *
+ * @attr {boolean} icon-has-action - Specify when icon need to be clickable
+ * @prop {boolean} [iconHasAction=false] - Specify when icon need to be clickable
+ *
+ * @attr {number} maxlength - Set character max limit
+ * @prop {number | null} [maxLength=null] - Set character max limit
+ *
+ * @attr {number} minlength - Set character min limit
+ * @prop {number | null} [minLength=null] - Set character min limit
+ *
+ * @prop {string} [pattern=""] - Set regular expression for input validation
+ *
+ * @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} 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
+ */
+export declare class DatetimeField extends TextField {
+    /**
+     * Element version number
+     * @returns version number
+     */
+    static get version(): string;
+    /**
+     * Delay selecting a part to ensure
+     * that scroll can be updated
+     */
+    private selectPartFrame;
+    /**
+     * Set minimum date.
+     * This value must follow the `format` and be less
+     * than or equal to the value of the `max` attribute
+     */
+    min: string | null;
+    /**
+     * Set maximum date.
+     * This value must follow the `format` and be greater
+     * than or equal to the value of the `min` attribute
+     */
+    max: string | null;
+    private _timepicker;
+    /**
+     * Toggle to display the time picker
+     * @param timepicker true to set timepicker mode
+     * @default false
+     */
+    set timepicker(timepicker: boolean);
+    get timepicker(): boolean;
+    private _showSeconds;
+    /**
+     * Toggle to display the seconds
+     * @param showSeconds true to show seconds
+     * @default false
+     */
+    set showSeconds(showSeconds: boolean);
+    get showSeconds(): boolean;
+    private _amPm;
+    /**
+     * Overrides 12hr time display format
+     * @param amPm true to show 12hr time format
+     * @default false
+     */
+    set amPm(amPm: boolean);
+    get amPm(): boolean;
+    private _formatOptions;
+    /**
+     * Set the datetime format options based on
+     * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat
+     * `formatOptions` overrides `timepicker` and `showSeconds` properties.
+     * Note: time-zone is not supported
+     * @param formatOptions Format options
+     * @default - null
+     */
+    set formatOptions(formatOptions: Intl.DateTimeFormatOptions | null);
+    get formatOptions(): Intl.DateTimeFormatOptions | null;
+    /**
+     * Used for translations
+     */
+    protected t: TranslateDirective;
+    /**
+     * Format, which is based on locale
+     */
+    private _locale;
+    protected get locale(): Locale;
+    private interimValueState;
+    /**
+     * Current date time value
+     * @param value Calendar value
+     * @default -
+     */
+    set value(value: string);
+    get value(): string;
+    /**
+     * Returns the value of the element, interpreted as double number
+     */
+    get valueAsNumber(): number;
+    /**
+     * Set the value of the element, interpreted as double number
+     * @param value number value
+     */
+    set valueAsNumber(value: number);
+    /**
+     * Returns the value of the element, interpreted as Date
+     */
+    get valueAsDate(): null | Date;
+    /**
+     * Set the value of the element, interpreted as Date
+     * @param value date value
+     */
+    set valueAsDate(value: null | Date);
+    /**
+     * Currently selected part
+     */
+    protected partLabel: string;
+    /**
+     * Transform Date object to date string
+     * @param value Date
+     * @returns dateSting
+     */
+    protected dateToString(value: Date): string;
+    /**
+     * Returns true if the datetime field has timepicker
+     * @returns hasTimePicker
+     */
+    protected get hasTimePicker(): boolean;
+    /**
+     * Returns true if the datetime field has seconds
+     * @returns hasSeconds
+     */
+    protected get hasSeconds(): boolean;
+    /**
+     * Returns true if the datetime field has am-pm
+     * @returns hasAmPm
+     */
+    protected get hasAmPm(): boolean;
+    /**
+     * Get today's date noon as the start date when the value is not set
+     */
+    protected get startDate(): string;
+    /**
+     * Updates the element
+     * @param changedProperties Properties that has changed
+     * @returns {void}
+     */
+    willUpdate(changedProperties: PropertyValues): void;
+    /**
+     * Check if input value should be synchronised with component value
+     * @param changedProperties Properties that has changed
+     * @returns True if input should be synchronised
+     */
+    protected shouldSyncInputValue(changedProperties: PropertyValues): boolean;
+    /**
+     * Synchronise input value with value.
+     * Override the method if value and input value are not the same
+     * @param changedProperties Properties that has changed
+     * @returns {void}
+     */
+    protected syncInputValue(changedProperties: PropertyValues): void;
+    protected syncInputValue(): void;
+    /**
+     * Check if input should be re-validated
+     * @param changedProperties Properties that has changed
+     * @returns True if input should be re-validated
+     */
+    protected shouldValidateInput(changedProperties: PropertyValues): boolean;
+    /**
+     * Validate input according `pattern`, `minLength` and `maxLength` properties
+     * change state of `error` property according pattern validation
+     * @returns {void}
+     */
+    protected validateInput(): void;
+    /**
+     * Override validation method for value
+     * @param value value
+     * @returns value validity
+     */
+    protected isValidValue(value: string): boolean;
+    /**
+     * Used to show a warning when the value does not pass the validation
+     * @param value that is invalid
+     * @returns {void}
+     */
+    protected warnInvalidValue(value: string): void;
+    /**
+     * Resolve locale based on element parameters
+     * @returns locale Resolved locale
+     */
+    protected resolveLocale(): Locale;
+    /**
+     * Get Intl.DateTimeFormat object from locale
+     */
+    protected get formatter(): Intl.DateTimeFormat;
+    /**
+     * Try to format ISO date/time/datetime string into datetime format parts
+     * Throw an error if value is invalid
+     * @param value ISO string date/time/datetime
+     * @returns parts
+     */
+    protected formatToParts(value: string): DateTimeFormatPart[];
+    /**
+     * Format value to inputValue
+     * @param value Date string
+     * @returns inputValue
+     */
+    protected toInputValue(value: string): string;
+    /**
+     * Format inputValue to value
+     * @param inputValue Date string
+     * @returns value
+     */
+    protected toValue(inputValue: string): string;
+    /**
+     * On *user-interaction* set the value and notify.
+     * @param value New value
+     * @returns {void}
+     */
+    protected setValueAndNotify(value: string): void;
+    /**
+     * Reset error state on input
+     * @returns {void}
+     */
+    protected resetError(): void;
+    /**
+     * Returns true if an input element contains valid data.
+     * @returns true if input is valid
+     */
+    checkValidity(): boolean;
+    /**
+     * Validate input. Mark as error if input is invalid
+     * @returns false if there is an error
+     */
+    reportValidity(): boolean;
+    /**
+     * Select part
+     * @param index Part index
+     * @param parts The list of parts
+     * @returns {void}
+     */
+    protected selectPart(index: number | undefined, parts: DateTimeFormatPart[]): void;
+    /**
+     * Change value or selection based on keyboard navigation
+     * @param key Navigation key
+     * @param event Keyboard event
+     * @returns {void}
+     */
+    protected onNavigation(key: NavigationKeys, event: KeyboardEvent): void;
+    /**
+     * Check if value is changed and fire event
+     * @returns {void}
+     */
+    protected onPossibleValueChange(event: InputEvent): void;
+    /**
+     * Handles key down input event
+     * @param event Key down event object
+     * @returns {void}
+     */
+    protected onInputKeyDown(event: KeyboardEvent): void;
+    /**
+     * Decorate `<input>` element with common properties.
+     * @returns template map
+     */
+    protected get decorateInputMap(): TemplateMap;
+    /**
+     * Used to announce part and value statuses
+     */
+    protected get screenReaderTemplate(): TemplateResult | null;
+    /**
+     * A `TemplateResult` that will be used
+     * to render the updated internal template.
+     * @return Render template
+     */
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'ef-datetime-field': DatetimeField;
+    }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ef-datetime-field': DatetimeField;
+  }
+
+  namespace JSX {
+    interface IntrinsicElements {
+      'ef-datetime-field': Partial<DatetimeField> | JSXInterface.HTMLAttributes<DatetimeField>;
+    }
+  }
+}
+
+export {};