@lion/ui 0.0.1

package/components/form-core/types/FocusMixinTypes.ts

@@ -0,0 +1,47 @@
+import { Constructor } from '@open-wc/dedupe-mixin';
+import { LitElement } from 'lit';
+
+export declare class FocusHost {
+  /**
+   * Whether the focusable element within (`._focusableNode`) is focused.
+   * Reflects to attribute '[focused]' as a styling hook
+   */
+  focused: boolean;
+
+  /**
+   * Whether the focusable element within (`._focusableNode`) matches ':focus-visible'
+   * Reflects to attribute '[focused-visible]' as a styling hook
+   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible
+   */
+  focusedVisible: boolean;
+
+  /**
+   * Calls `focus()` on focusable element within
+   */
+  focus(): void;
+
+  /**
+   * Calls `blur()` on focusable element within
+   */
+  blur(): void;
+
+  /**
+   * The focusable element:
+   * could be an input, textarea, select, button or any other element with tabindex > -1
+   */
+  protected get _focusableNode(): HTMLElement;
+
+  private __onFocus(): void;
+  private __onBlur(): void;
+  private __registerEventsForFocusMixin(): void;
+  private __teardownEventsForFocusMixin(): void;
+}
+
+export declare function FocusImplementation<T extends Constructor<LitElement>>(
+  superclass: T,
+): T &
+  Constructor<FocusHost> &
+  Pick<typeof FocusHost, keyof typeof FocusHost> &
+  Pick<typeof LitElement, keyof typeof LitElement>;
+
+export type FocusMixin = typeof FocusImplementation;

package/components/form-core/types/FormControlMixinTypes.ts

@@ -0,0 +1,265 @@
+import { Constructor } from '@open-wc/dedupe-mixin';
+import { LitElement, nothing, TemplateResult, CSSResultArray } from 'lit';
+import { DisabledHost } from '../../core/types/DisabledMixinTypes.js';
+import { SlotHost } from '../../core/types/SlotMixinTypes.js';
+import { FormRegisteringHost } from './registration/FormRegisteringMixinTypes.js';
+
+import { LionValidationFeedback } from '../src/validate/LionValidationFeedback.js';
+import { Unparseable } from '../src/validate/Unparseable.js';
+
+export type ModelValueEventDetails = {
+  /**
+   * A list that represents the path of FormControls the model-value-changed event
+   * 'traveled through'.
+   * (every FormControl stops propagation of its child and sends a new event, hereby adding
+   * itself to the beginning of formPath)
+   */
+  formPath: HTMLElement[];
+
+  /**
+   * Sometimes it can be helpful to detect whether a value change was caused by a user or
+   * via a programmatical change.
+   * This feature acts as a normalization layer: since we use `model-value-changed` as a single
+   * source of truth event for all FormControls, there should be no use cases for
+   * (inconsistently implemented (cross browser)) events
+   * like 'input'/'change'/'user-input-changed' etc.)
+   */
+  isTriggeredByUser: boolean;
+
+  /**
+   * Whether it is the first event sent on initialization of the form (other
+   * model-value-changed events are triggered imperatively or via user input (in the latter
+   * case `isTriggeredByUser` is true))
+   */
+  initialize?: boolean;
+};
+
+export declare interface HTMLElementWithValue extends HTMLElement {
+  value: string;
+  selectionStart?: number;
+  selectionEnd?: number;
+}
+
+export declare class FormControlHost {
+  static get styles(): CSSResultArray;
+  static get properties(): {
+    name: {
+      type: StringConstructor;
+      reflect: boolean;
+    };
+    readOnly: {
+      type: BooleanConstructor;
+      attribute: string;
+      reflect: boolean;
+    };
+    label: StringConstructor;
+    helpText: {
+      type: StringConstructor;
+      attribute: string;
+    };
+    modelValue: { attribute: boolean };
+    _ariaLabelledNodes: { attribute: boolean };
+    _ariaDescribedNodes: { attribute: boolean };
+    _repropagationRole: { attribute: boolean };
+    _isRepropagationEndpoint: { attribute: boolean };
+  };
+
+  /**
+   * A boolean attribute which, if present, indicates that the user should not be able to edit
+   * the value of the input. The difference between disabled and readonly is that read-only
+   * controls can still function, whereas disabled controls generally do not function as
+   * controls until they are enabled.
+   * See: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-readonly
+   */
+  readOnly: boolean;
+
+  /**
+   * The name the element will be registered with to the .formElements collection
+   * of the parent. Also, it serves as the key of key/value pairs in
+   *  modelValue/serializedValue objects
+   */
+  name: string;
+
+  /**
+   * The model value is the result of the parser function(when available).
+   * It should be considered as the internal value used for validation and reasoning/logic.
+   * The model value is 'ready for consumption' by the outside world (think of a Date
+   * object or a float). The modelValue can(and is recommended to) be used as both input
+   * value and output value of the `LionField`.
+   *
+   * Examples:
+   * - For a date input: a String '20/01/1999' will be converted to new Date('1999/01/20')
+   * - For a number input: a formatted String '1.234,56' will be converted to a Number:
+   *   1234.56
+   */
+  get modelValue(): any | Unparseable;
+  set modelValue(value: any | Unparseable);
+
+  /**
+   * The label text for the input node.
+   * When no light dom defined via [slot=label], this value will be used
+   */
+  get label(): string;
+  set label(arg: string);
+
+  /**
+   * The helpt text for the input node.
+   * When no light dom defined via [slot=help-text], this value will be used
+   */
+  get helpText(): string;
+  set helpText(arg: string);
+
+  /**
+   * Will be used in validation messages to refer to the current field
+   */
+  set fieldName(arg: string);
+  get fieldName(): string;
+
+  /**
+   * Allows to add extra element references to aria-labelledby attribute.
+   */
+  addToAriaLabelledBy(
+    element: HTMLElement,
+    customConfig?: {
+      idPrefix?: string | undefined;
+      reorder?: boolean | undefined;
+    },
+  ): void;
+
+  /**
+   * Allows to add extra element references to aria-describedby attribute.
+   */
+  addToAriaDescribedBy(
+    element: HTMLElement,
+    customConfig?: {
+      idPrefix?: string | undefined;
+      reorder?: boolean | undefined;
+    },
+  ): void;
+
+  /**
+   * Allows to remove element references from aria-labelledby attribute.
+   */
+  removeFromAriaLabelledBy(
+    element: HTMLElement,
+    customConfig?: {
+      reorder?: boolean | undefined;
+    },
+  ): void;
+
+  /**
+   * Allows to remove element references from aria-describedby attribute.
+   */
+  removeFromAriaDescribedBy(
+    element: HTMLElement,
+    customConfig?: {
+      reorder?: boolean | undefined;
+    },
+  ): void;
+
+  updated(changedProperties: import('lit').PropertyValues): void;
+
+  /**
+   * The interactive (form) element. Can be a native element like input/textarea/select or
+   * an element with tabindex > -1
+   */
+  protected get _inputNode(): HTMLElementWithValue | HTMLInputElement | HTMLTextAreaElement;
+
+  /**
+   * Element where label will be rendered to
+   */
+  protected get _labelNode(): HTMLElement;
+
+  /**
+   * Element where help text will be rendered to
+   */
+  protected get _helpTextNode(): HTMLElement;
+
+  /**
+   * Element where validation feedback will be rendered to
+   */
+  protected get _feedbackNode(): LionValidationFeedback;
+
+  /**
+   * Unique id that can be used in all light dom
+   */
+  protected _inputId: string;
+
+  /**
+   * Contains all elements that should end up in aria-labelledby of `._inputNode`
+   * @type {HTMLElement[]}
+   */
+  protected _ariaLabelledNodes: HTMLElement[];
+
+  /**
+   * Contains all elements that should end up in aria-describedby of `._inputNode`
+   */
+  protected _ariaDescribedNodes: HTMLElement[];
+
+  /**
+   * Based on the role, details of handling model-value-changed repropagation differ.
+   */
+  protected _repropagationRole: 'child' | 'choice-group' | 'fieldset';
+
+  /**
+   * By default, a field with _repropagationRole 'choice-group' will act as an
+   * 'endpoint'. This means it will be considered as an individual field: for
+   * a select, individual options will not be part of the formPath. They
+   * will.
+   * Similarly, components that (a11y wise) need to be fieldsets, but 'interaction wise'
+   * (from Application Developer perspective) need to be more like fields
+   * (think of an amount-input with a currency select box next to it), can set this
+   * to true to hide private internals in the formPath.
+   */
+  protected _isRepropagationEndpoint: boolean;
+  protected _parentFormGroup: FormControlHost | undefined;
+  protected _groupOneTemplate(): TemplateResult;
+  protected _groupTwoTemplate(): TemplateResult;
+  protected _labelTemplate(): TemplateResult;
+  protected _helpTextTemplate(): TemplateResult;
+  protected _inputGroupTemplate(): TemplateResult;
+  protected _inputGroupBeforeTemplate(): TemplateResult;
+  protected _inputGroupPrefixTemplate(): TemplateResult | typeof nothing;
+  protected _inputGroupInputTemplate(): TemplateResult;
+  protected _inputGroupSuffixTemplate(): TemplateResult | typeof nothing;
+  protected _inputGroupAfterTemplate(): TemplateResult;
+  protected _feedbackTemplate(): TemplateResult;
+  protected _triggerInitialModelValueChangedEvent(): void;
+  protected _enhanceLightDomClasses(): void;
+  protected _enhanceLightDomA11y(): void;
+  protected _enhanceLightDomA11yForAdditionalSlots(additionalSlots?: string[]): void;
+  protected _isEmpty(modelValue?: any): boolean;
+  protected _getAriaDescriptionElements(): HTMLElement[];
+  protected _dispatchInitialModelValueChangedEvent(): void;
+  protected _onBeforeRepropagateChildrenValues(ev: CustomEvent): void;
+  protected _repropagationCondition(target: FormControlHost): boolean;
+
+  private __helpText: string | undefined;
+  private __label: string;
+  private __fieldName: string | undefined;
+  private __reorderAriaLabelledNodes: boolean | undefined;
+  private __reflectAriaAttr(
+    attrName: string,
+    nodes: HTMLElement[],
+    reorder: boolean | undefined,
+  ): void;
+  private __reorderAriaDescribedNodes: boolean | undefined;
+  private __getDirectSlotChild(slotName: string): HTMLElement | undefined;
+  private __repropagateChildrenInitialized: boolean | undefined;
+  private __repropagateChildrenValues(ev: CustomEvent): void;
+}
+
+export declare function FormControlImplementation<T extends Constructor<LitElement>>(
+  superclass: T,
+): T &
+  Constructor<FormControlHost> &
+  Pick<typeof FormControlHost, keyof typeof FormControlHost> &
+  Constructor<FormRegisteringHost> &
+  Pick<typeof FormRegisteringHost, keyof typeof FormRegisteringHost> &
+  Constructor<DisabledHost> &
+  Pick<typeof DisabledHost, keyof typeof DisabledHost> &
+  Constructor<SlotHost> &
+  Pick<typeof SlotHost, keyof typeof SlotHost> &
+  Pick<typeof LitElement, keyof typeof LitElement>;
+
+export type FormControlMixin = typeof FormControlImplementation;

package/components/form-core/types/FormatMixinTypes.ts

@@ -0,0 +1,197 @@
+import { Constructor } from '@open-wc/dedupe-mixin';
+import { LitElement } from 'lit';
+import { ValidateHost } from './validate/ValidateMixinTypes.js';
+import { FormControlHost } from './FormControlMixinTypes.js';
+
+export type FormatOptions = { mode: 'pasted' | 'auto' } & object;
+export declare class FormatHost {
+  /**
+   * Converts viewValue to modelValue
+   * For instance, a localized date to a Date Object
+   * @param {string} v - viewValue: the formatted value inside <input>
+   * @param {FormatOptions} opts
+   * @returns {*} modelValue
+   */
+  parser(v: string, opts: FormatOptions): unknown;
+
+  /**
+   * Converts modelValue to formattedValue (formattedValue will be synced with
+   * `._inputNode.value`)
+   * For instance, a Date object to a localized date.
+   * @param {*} v - modelValue: can be an Object, Number, String depending on the
+   * input type(date, number, email etc)
+   * @param {FormatOptions} opts
+   * @returns {string} formattedValue
+   */
+  formatter(v: unknown, opts?: FormatOptions): string;
+
+  /**
+   * Converts `.modelValue` to `.serializedValue`
+   * For instance, a Date object to an iso formatted date string
+   * @param {?} v - modelValue: can be an Object, Number, String depending on the
+   * input type(date, number, email etc)
+   * @returns {string} serializedValue
+   */
+  serializer(v: unknown): string;
+
+  /**
+   * Converts `.serializedValue` to `.modelValue`
+   * For instance, an iso formatted date string to a Date object
+   * @param {?} v - modelValue: can be an Object, Number, String depending on the
+   * input type(date, number, email etc)
+   * @returns {?} modelValue
+   */
+  deserializer(v: string): unknown;
+
+  /**
+   * Preprocessors could be considered 'live formatters'. Their result is shown to the user
+   * on keyup instead of after blurring the field. The biggest difference between preprocessors
+   * and formatters is their moment of execution: preprocessors are run before modelValue is
+   * computed (and work based on view value), whereas formatters are run after the parser (and
+   * are based on modelValue)
+   * Automatically formats code while typing. It depends on a preprocessro that smartly
+   * updates the viewValue and caret position for best UX.
+   * @example
+   * ```js
+   * preprocessor(viewValue) {
+   *   // only use digits
+   *   return viewValue.replace(/\D/g, '');
+   * }
+   * @param {string} v - the raw value from the <input> after keyUp/Down event
+   * @param {FormatOptions & { prevViewValue: string; currentCaretIndex: number }} opts - the raw value from the <input> after keyUp/Down event
+   * @returns {{ viewValue:string; caretIndex:number; }|string|undefined} preprocessedValue: the result of preprocessing for invalid input
+   */
+  preprocessor(
+    v: string,
+    options: FormatOptions & { prevViewValue: string; currentCaretIndex: number },
+  ): { viewValue: string; caretIndex: number } | string | undefined;
+
+  /**
+   * The view value is the result of the formatter function (when available).
+   * The result will be stored in the native _inputNode (usually an input[type=text]).
+   *
+   * Examples:
+   * - For a date input, this would be '20/01/1999' (dependent on locale).
+   * - For a number input, this could be '1,234.56' (a String representation of modelValue
+   * 1234.56)
+   * @type {string|undefined}
+   * @readOnly
+   */
+  formattedValue: string | undefined;
+
+  /**
+   * The serialized version of the model value.
+   * This value exists for maximal compatibility with the platform API.
+   * The serialized value can be an interface in context where data binding is not
+   * supported and a serialized string needs to be set.
+   *
+   * Examples:
+   * - For a date input, this would be the iso format of a date, e.g. '1999-01-20'.
+   * - For a number input this would be the String representation of a float ('1234.56'
+   *   instead of 1234.56)
+   *
+   * When no parser is available, the value is usually the same as the formattedValue
+   * (being _inputNode.value)
+   */
+  serializedValue: string | undefined;
+
+  /**
+   * Event that will trigger formatting (more precise, visual update of the view, so the
+   * user sees the formatted value)
+   * Default: 'change'
+   * @deprecated use _reflectBackOn()
+   * @protected
+   */
+  formatOn: string;
+
+  /**
+   * Configuration object that will be available inside the formatter function
+   */
+  formatOptions: FormatOptions;
+
+  /**
+   * The view value. Will be delegated to `._inputNode.value`
+   */
+  get value(): string;
+  set value(value: string);
+
+  /**
+   * Flag that will be set when user interaction takes place (for instance after an 'input'
+   * event). Will be added as meta info to the `model-value-changed` event. Depending on
+   * whether a user is interacting, formatting logic will be handled differently.
+   */
+  protected _isHandlingUserInput: boolean;
+
+  /**
+   * Whether the user is pasting content. Allows Subclassers to do this in their subclass:
+   * @example
+   * ```js
+   * _reflectBackOn() {
+   *   return super._reflectBackOn() || this._isPasting;
+   * }
+   * ```
+   */
+  protected _isPasting: boolean;
+
+  /**
+   * Responsible for storing all representations(modelValue, serializedValue, formattedValue
+   * and value) of the input value. Prevents infinite loops, so all value observers can be
+   * treated like they will only be called once, without indirectly calling other observers.
+   * (in fact, some are called twice, but the __preventRecursiveTrigger lock prevents the
+   * second call from having effect).
+   * @param {{source:'model'|'serialized'|'formatted'|null}} config
+   * the type of value that triggered this method. It should not be set again, so that its
+   * observer won't be triggered. Can be: 'model'|'formatted'|'serialized'.
+   */
+  protected _calculateValues(opts: { source: 'model' | 'serialized' | 'formatted' | null }): void;
+  protected _onModelValueChanged(arg: { modelValue: unknown }): void;
+  protected _dispatchModelValueChangedEvent(): void;
+
+  /**
+   * Synchronization from `._inputNode.value` to `LionField` (flow [2])
+   * Downwards syncing should only happen for `LionField`.value changes from 'above'.
+   * This triggers _onModelValueChanged and connects user input
+   * to the parsing/formatting/serializing loop.
+   */
+  protected _syncValueUpwards(): void;
+  protected _reflectBackFormattedValueToUser(): void;
+  private _reflectBackFormattedValueDebounced(): void;
+
+  /**
+   * Every time .formattedValue is attempted to sync to the view value (on change/blur and on
+   * modelValue change), this condition is checked. When enhancing it, it's recommended to
+   * call `super._reflectBackOn()`
+   * @overridable
+   * @return {boolean}
+   * @protected
+   */
+  protected _reflectBackOn(): boolean;
+
+  /**
+   * This can be called whenever the view value should be updated. Dependent on component type
+   * ("input" for <input> or "change" for <select>(mainly for IE)) a different event should be
+   * used  as source for the "user-input-changed" event (which can be seen as an abstraction
+   * layer on top of other events (input, change, whatever))
+   * @protected
+   */
+  protected _proxyInputEvent(): void;
+  protected _onUserInputChanged(): void;
+  protected _callParser(value: string | undefined): object;
+  protected _callFormatter(): string;
+
+  private __preventRecursiveTrigger: boolean;
+  private __prevViewValue: string;
+}
+
+export declare function FormatImplementation<T extends Constructor<LitElement>>(
+  superclass: T,
+): T &
+  Constructor<FormatHost> &
+  Pick<typeof FormatHost, keyof typeof FormatHost> &
+  Constructor<ValidateHost> &
+  Pick<typeof ValidateHost, keyof typeof ValidateHost> &
+  Constructor<FormControlHost> &
+  Pick<typeof FormControlHost, keyof typeof FormControlHost> &
+  Pick<typeof LitElement, keyof typeof LitElement>;
+
+export type FormatMixin = typeof FormatImplementation;

package/components/form-core/types/InteractionStateMixinTypes.ts

@@ -0,0 +1,99 @@
+import { Constructor } from '@open-wc/dedupe-mixin';
+import { LitElement } from 'lit';
+import { FormControlHost } from './FormControlMixinTypes.js';
+
+/**
+ * A set of meta info about a FormControl that helps in the context of determining validation
+ * feedback visibility
+ */
+export type InteractionStates = {
+  submitted: boolean;
+  touched: boolean;
+  dirty: boolean;
+  filled: boolean;
+  prefilled: boolean;
+};
+export declare class InteractionStateHost {
+  /**
+   * True when user has focused and left(blurred) the field.
+   */
+  touched: boolean;
+
+  /**
+   * True when user has changed the value of the field.
+   */
+  dirty: boolean;
+
+  /**
+   * True when user has left non-empty field or input is prefilled.
+   * The name must be seen from the point of view of the input field:
+   * once the user enters the input field, the value is non-empty.
+   */
+  prefilled: boolean;
+
+  /**
+   * True when the modelValue is non-empty (see _isEmpty in FormControlMixin)
+   */
+  filled: boolean;
+
+  /**
+   * True when user has attempted to submit the form, e.g. through a button
+   * of type="submit"
+   */
+  submitted: boolean;
+
+  /**
+   * Evaluations performed on connectedCallback.
+   * This method is public, so it can be called at a later moment (when we need to wait for
+   * registering children for instance) as well.
+   * Since this method will be called twice in last mentioned scenario, it must stay idempotent.
+   */
+  initInteractionState(): void;
+
+  /**
+   * Resets touched and dirty, and recomputes prefilled
+   */
+  resetInteractionState(): void;
+
+  /**
+   * The event that triggers the touched state
+   */
+  protected _leaveEvent: string;
+
+  /**
+   * The event that triggers the dirty state
+   */
+  protected _valueChangedEvent: string;
+
+  /**
+   * Sets touched value to true and reevaluates prefilled state.
+   * When false, on next interaction, user will start with a clean state.
+   */
+  protected _iStateOnLeave(): void;
+
+  /**
+   * Sets dirty value and validates when already touched or invalid
+   */
+  protected _iStateOnValueChange(): void;
+
+  /**
+   * Dispatches event on touched state change
+   */
+  protected _onTouchedChanged(): void;
+
+  /**
+   * Dispatches event on touched state change
+   */
+  protected _onDirtyChanged(): void;
+}
+
+export declare function InteractionStateImplementation<T extends Constructor<LitElement>>(
+  superclass: T,
+): T &
+  Constructor<InteractionStateHost> &
+  Pick<typeof InteractionStateHost, keyof typeof InteractionStateHost> &
+  Constructor<FormControlHost> &
+  Pick<typeof FormControlHost, keyof typeof FormControlHost> &
+  Pick<typeof LitElement, keyof typeof LitElement>;
+
+export type InteractionStateMixin = typeof InteractionStateImplementation;

package/components/form-core/types/NativeTextFieldMixinTypes.ts

@@ -0,0 +1,46 @@
+import { Constructor } from '@open-wc/dedupe-mixin';
+import { LitElement } from 'lit';
+import { FocusHost } from './FocusMixinTypes.js';
+import { FormatHost } from './FormatMixinTypes.js';
+import { FormControlHost } from './FormControlMixinTypes.js';
+// import { FocusHost } from '@lion/ui/form-core/types/FocusMixinTypes.js';
+// import { FormControlHost } from '@lion/ui/form-core/types/FormControlMixinTypes.js';
+// import { FormatHost } from '@lion/ui/form-core/types/FormatMixinTypes.js';
+
+export declare class NativeTextFieldHost {
+  /**
+   * Delegates autocomplete to input/textarea
+   */
+  autocomplete: string;
+
+  /**
+   * Delegates selectionStart to input/textarea
+   */
+  get selectionStart(): number;
+  set selectionStart(value: number);
+
+  /**
+   * Delegates selectionEnd to input/textarea
+   */
+  get selectionEnd(): number;
+  set selectionEnd(value: number);
+
+  /**
+   * Restores the cursor to its original position after updating the value.
+   */
+  protected _setValueAndPreserveCaret(value: string): void;
+}
+
+export declare function NativeTextFieldImplementation<T extends Constructor<LitElement>>(
+  superclass: T,
+): T &
+  Constructor<NativeTextFieldHost> &
+  Pick<typeof NativeTextFieldHost, keyof typeof NativeTextFieldHost> &
+  Constructor<FormatHost> &
+  Pick<typeof FormatHost, keyof typeof FormatHost> &
+  Constructor<FocusHost> &
+  Pick<typeof FocusHost, keyof typeof FocusHost> &
+  Constructor<FormControlHost> &
+  Pick<typeof FormControlHost, keyof typeof FormControlHost>;
+
+export type NativeTextFieldMixin = typeof NativeTextFieldImplementation;