@yamato-daiwa/frontend-vue 0.1.0 → 0.2.0

package/Source/GUI_Components/Controls/ValidatableControlShell/ValidatableControlShell.vue.ts

@@ -0,0 +1,296 @@
+import { Vue3SlideUpDown as VerticallySlidingAlwaysMountedContainer } from "vue3-slide-up-down";
+
+/* ─── Assets ─────────────────────────────────────────────────────────────────────────────────────────────────────── */
+import componentVueTemplate from "./ValidatableControlShell.vue.pug";
+import {
+  type ValidatableControlShellLocalization,
+  validatableControlShellYDF_ComponentLocalization__english
+} from "@yamato-daiwa/frontend";
+
+/* ─── Framework ──────────────────────────────────────────────────────────────────────────────────────────────────── */
+import {
+  ComponentBase as VueComponentConfiguration,
+  Vue as VueComponent,
+  Prop as VueProperty,
+  Watch as onVueComponentFieldUpdated
+} from "vue-facing-decorator";
+
+/* ─── Utils ──────────────────────────────────────────────────────────────────────────────────────────────────────── */
+import YDF_ComponentsCoordinator from "../../YDF_ComponentsCoordinator";
+import OptionalButNotNullableVueProperty from "../../_Decorators/OptionalButNotNullableVueProperty";
+import validateVuePropertyAndLogIfInvalid from "../../_Utils/validateVuePropertyAndLogIfInvalid";
+import {
+  isNonEmptyString,
+  isElementOfEnumeration,
+  secondsToMilliseconds,
+  isNeitherUndefinedNorNull
+} from "@yamato-daiwa/es-extensions";
+
+
+@VueComponentConfiguration({
+  name: ValidatableControlShell.CSS_NAMESPACE,
+  template: componentVueTemplate,
+  components: {
+    VerticallySlidingAlwaysMountedContainer
+  }
+})
+class ValidatableControlShell extends VueComponent {
+
+  public static CSS_NAMESPACE: string = "ValidatableControlShell--YDF";
+
+
+  /* ━━━ Component Common Properties ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  /* ─── Textings ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+  @VueProperty({
+    validator: validateVuePropertyAndLogIfInvalid({
+      checker: isNonEmptyString,
+      message: "If string specified it must be non-empty."
+    })
+  })
+  @OptionalButNotNullableVueProperty
+  protected readonly label?: string;
+
+  @VueProperty({
+    validator: validateVuePropertyAndLogIfInvalid({
+      checker: isNonEmptyString,
+      message: "If string specified it must be non-empty."
+    })
+  })
+  @OptionalButNotNullableVueProperty
+  protected readonly guidance?: string;
+
+
+  /* ─── Inputting Requirement ────────────────────────────────────────────────────────────────────────────────────── */
+  @VueProperty({ type: Boolean, default: false })
+  @OptionalButNotNullableVueProperty
+  protected readonly required!: boolean;
+
+  @VueProperty({ type: Boolean, default: false })
+  @OptionalButNotNullableVueProperty
+  protected readonly mustDisplayAppropriateBadgeIfInputIsRequired!: boolean;
+
+  @VueProperty({ type: Boolean, default: false })
+  @OptionalButNotNullableVueProperty
+  protected readonly mustDisplayAppropriateBadgeIfInputIsOptional!: boolean;
+
+  @VueProperty({ type: Boolean, default: false })
+  @OptionalButNotNullableVueProperty
+  protected readonly mustAddInvisibleBadgeForHeightEqualizingWhenNoBadge!: boolean;
+
+  /* ─── HTML IDs ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+  @VueProperty({
+    validator: validateVuePropertyAndLogIfInvalid({
+      checker: isNonEmptyString,
+      message: "If string specified it must be non-empty."
+    })
+  })
+  @OptionalButNotNullableVueProperty
+  protected readonly coreElementHTML_ID?: string;
+
+  @VueProperty({
+    validator: validateVuePropertyAndLogIfInvalid({
+      checker: isNonEmptyString,
+      message: "If string specified it must be non-empty."
+    })
+  })
+  @OptionalButNotNullableVueProperty
+  protected readonly labelElementHTML_ID?: string;
+
+
+  /* ─── Displaying of Validation Messages ────────────────────────────────────────────────────────────────────────── */
+  @VueProperty({ type: Boolean, default: false })
+  @OptionalButNotNullableVueProperty
+  protected readonly invalidInputHighlightingIfAnyValidationErrorsMessages!: boolean;
+
+  @VueProperty({ type: Boolean, default: false })
+  @OptionalButNotNullableVueProperty
+  protected readonly validValueHighlightingIfNoValidationErrorsMessages!: boolean;
+
+
+  /* ─── CSS Classes ──────────────────────────────────────────────────────────────────────────────────────────────── */
+  @VueProperty({ type: [ Array ], default: (): ReadonlyArray<string> => [] })
+  @OptionalButNotNullableVueProperty
+  protected readonly mainSlotWrapperAdditionalCSS_Classes!: ReadonlyArray<string>;
+
+
+  /* ━━━ Validation Errors Messages ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  @VueProperty({ type: Array, default: (): ReadonlyArray<string> => [] })
+  @OptionalButNotNullableVueProperty
+  protected readonly validationErrorsMessages!: ReadonlyArray<string>;
+
+  /* [ Theory ]
+   * Even if `validationErrorsMessages` has become to empty array, the validation errors messages are still
+   *   require to animate the expanding. */
+  protected validationErrorsMessagesCopyForAnimating: ReadonlyArray<string> = [ ...this.validationErrorsMessages ];
+
+  protected static readonly ERRORS_LIST_EXPANDING_ANIMATION_DURATION_PER_ONE_ERROR_MESSAGE__SECONDS: number = 0.2;
+  protected static readonly ERRORS_LIST_COLLAPSING_ANIMATION_DURATION__SECONDS: number = 0.2;
+
+  @onVueComponentFieldUpdated("validationErrorsMessages")
+  protected onValidationErrorsMessagesUpdated(newValidationErrorsMessages: ReadonlyArray<string>): void {
+
+    if (newValidationErrorsMessages.length > 0) {
+      this.validationErrorsMessagesCopyForAnimating = [ ...newValidationErrorsMessages ];
+      return;
+    }
+
+
+    setTimeout(
+      (): void => {
+        this.validationErrorsMessagesCopyForAnimating = [];
+      },
+      secondsToMilliseconds(ValidatableControlShell.ERRORS_LIST_COLLAPSING_ANIMATION_DURATION__SECONDS)
+    );
+
+  }
+
+
+  /* ━━━ Theming ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  public static readonly Themes: ValidatableControlShell.Themes = { regular: "REGULAR" };
+
+  @VueProperty({
+    type: String,
+    default: ValidatableControlShell.Themes.regular,
+    validator: validateVuePropertyAndLogIfInvalid({
+      checker: (rawValue: string): boolean => isElementOfEnumeration(rawValue, ValidatableControlShell.Themes),
+      message:
+          "Must be the one among values of `ValidatableControlShell.Themes` associative array including the ones " +
+            "defined via `ValidatableControlShell.defineThemes()`."
+    })
+  })
+  @OptionalButNotNullableVueProperty
+  protected readonly theme!: string;
+
+  public static defineThemes(themesNames: ReadonlyArray<string>): typeof ValidatableControlShell {
+    return YDF_ComponentsCoordinator.defineThemes(themesNames, ValidatableControlShell);
+  }
+
+  public static areThemesCSS_ClassesCommon: boolean = YDF_ComponentsCoordinator.areThemesCSS_ClassesCommon;
+
+  public static considerThemesAsCommon(): void {
+    ValidatableControlShell.areThemesCSS_ClassesCommon = true;
+  }
+
+  @VueProperty({ type: Boolean, default: ValidatableControlShell.areThemesCSS_ClassesCommon })
+  @OptionalButNotNullableVueProperty
+  private readonly areThemesCSS_ClassesCommon!: boolean;
+
+
+  /* ─── Geometry ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+  public static readonly GeometricVariations: ValidatableControlShell.GeometricVariations = {
+    regular: "REGULAR",
+    small: "SMALL"
+  };
+
+  @VueProperty({
+    type: String,
+    default: ValidatableControlShell.GeometricVariations.regular,
+    validator: validateVuePropertyAndLogIfInvalid({
+      checker: (rawValue: string): boolean => isElementOfEnumeration(rawValue, ValidatableControlShell.GeometricVariations),
+      message:
+          "Must be the one among values of `ValidatableControlShell.GeometricVariations` associative array including the ones " +
+            "defined via `ValidatableControlShell.defineGeometricVariations()`."
+    })
+  })
+  @OptionalButNotNullableVueProperty
+  protected readonly geometricVariation!: string;
+
+  public static defineGeometricVariations(geometricVariationsNames: ReadonlyArray<string>): typeof ValidatableControlShell {
+    return YDF_ComponentsCoordinator.defineGeometricVariations(geometricVariationsNames, ValidatableControlShell);
+  }
+
+
+  /* ─── Decoration ───────────────────────────────────────────────────────────────────────────────────────────────── */
+  public static readonly DecorativeVariations: ValidatableControlShell.DecorativeVariations = {
+    regular: "REGULAR"
+  };
+
+  @VueProperty({
+    type: String,
+    default: ValidatableControlShell.DecorativeVariations.regular,
+    validator: validateVuePropertyAndLogIfInvalid({
+      checker: (rawValue: string): boolean => isElementOfEnumeration(rawValue, ValidatableControlShell.DecorativeVariations),
+      message:
+        "Must be the one among values of `ValidatableControlShell.DecorativeVariations` associative array including the ones " +
+          "defined via `ValidatableControlShell.defineDecorativeVariations()`."
+    })
+  })
+  protected readonly decorativeVariation!: string;
+
+  public static defineDecorativeVariations(decorativeVariationsNames: ReadonlyArray<string>): typeof ValidatableControlShell {
+    return YDF_ComponentsCoordinator.defineDecorativeVariations(decorativeVariationsNames, ValidatableControlShell);
+  }
+
+
+  /* ━━━ CSS Classes ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  protected get rootElementModifierCSS_Classes(): ReadonlyArray<string> {
+    return YDF_ComponentsCoordinator.generateRootElementModifierCSS_Classes({
+      CSS_Namespace: ValidatableControlShell.CSS_NAMESPACE,
+      activeTheme: this.theme,
+      allThemes: ValidatableControlShell.Themes,
+      areThemesCSS_ClassesCommon: this.areThemesCSS_ClassesCommon,
+      activeGeometricVariation: this.geometricVariation,
+      allGeometricVariations: ValidatableControlShell.GeometricVariations,
+      activeDecorativeVariation: this.decorativeVariation,
+      allDecorativeVariations: ValidatableControlShell.DecorativeVariations
+    });
+  }
+
+
+  // ━━━ TODO ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /* ━━━ Conditional Rendering ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  private get mustDisplayRequiredInputBadge(): boolean {
+    return this.required && this.mustDisplayAppropriateBadgeIfInputIsRequired;
+  }
+
+  private get mustDisplayOptionalInputBadge(): boolean {
+    return this.required && this.mustDisplayAppropriateBadgeIfInputIsOptional;
+  }
+
+  protected get mustDisplayHeader(): boolean {
+    return isNeitherUndefinedNorNull(this.label) ||
+        this.mustDisplayRequiredInputBadge ||
+        this.mustDisplayOptionalInputBadge ||
+        this.mustAddInvisibleBadgeForHeightEqualizingWhenNoBadge;
+  }
+
+
+  /* ━━━ Lifecycle Hooks ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  public created(): void {
+    this.initializeNonReactiveClassFields();
+  }
+
+
+  /* ━━━ Non-reactive Fields ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  public static localization: ValidatableControlShellLocalization = validatableControlShellYDF_ComponentLocalization__english;
+  protected localization!: ValidatableControlShellLocalization;
+
+  private initializeNonReactiveClassFields(): void {
+    this.localization = ValidatableControlShell.localization;
+  }
+
+}
+
+
+namespace ValidatableControlShell {
+
+  export type Themes = {
+    readonly regular: "REGULAR";
+    [themeName: string]: string;
+  };
+
+  export type GeometricVariations = {
+    readonly regular: "REGULAR";
+    readonly small: "SMALL";
+    [geometricVariationName: string]: string;
+  };
+
+  export type DecorativeVariations = {
+    readonly regular: "REGULAR";
+    [decorativeVariationName: string]: string;
+  };
+
+}
+
+
+export default ValidatableControlShell;

package/Source/GUI_Components/Controls/Validatables/InputtableControl.ts

@@ -0,0 +1,134 @@
+/* ─── Framework ──────────────────────────────────────────────────────────────────────────────────────────────────── */
+import {
+  ComponentBase as VueComponentConfiguration,
+  Vue as VueComponent,
+  Prop as VueProperty
+} from "vue-facing-decorator";
+
+/* ─── Utils ──────────────────────────────────────────────────────────────────────────────────────────────────────── */
+import {
+  Logger,
+  isNonEmptyString,
+  isEitherUndefinedOrNull
+} from "@yamato-daiwa/es-extensions";
+import InvalidVuePropertiesCombinationError from
+    "../../_Errors/InvalidVuePropertiesCombination/InvalidVuePropertiesCombinationError";
+import OptionalButNotNullableVueProperty from "../../_Decorators/OptionalButNotNullableVueProperty";
+import validateVuePropertyAndLogIfInvalid from "../../_Utils/validateVuePropertyAndLogIfInvalid";
+
+
+@VueComponentConfiguration({})
+export default class InputtableControl extends VueComponent {
+
+  /* ━━━ Component Common Properties ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  /* ─── Textings ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+  @VueProperty({
+    validator: validateVuePropertyAndLogIfInvalid({
+      checker: isNonEmptyString,
+      message: "If string specified it must be non-empty"
+    })
+  })
+  @OptionalButNotNullableVueProperty
+  protected readonly label?: string;
+
+  @VueProperty({
+    validator: validateVuePropertyAndLogIfInvalid({
+      checker: isNonEmptyString,
+      message: "If string specified it must be non-empty"
+    })
+  })
+  @OptionalButNotNullableVueProperty
+  protected readonly accessibilityGuidance?: string;
+
+  @VueProperty({
+    validator: validateVuePropertyAndLogIfInvalid({
+      checker: isNonEmptyString,
+      message: "If string specified it must be non-empty"
+    })
+  })
+  @OptionalButNotNullableVueProperty
+  protected readonly externalLabelHTML_ID?: string;
+
+  @VueProperty({
+    validator: validateVuePropertyAndLogIfInvalid({
+      checker: isNonEmptyString,
+      message: "If string specified it must be non-empty"
+    })
+  })
+  @OptionalButNotNullableVueProperty
+  protected readonly guidance?: string;
+
+
+  /* ─── Requirement ──────────────────────────────────────────────────────────────────────────────────────────────── */
+  @VueProperty({ type: Boolean, default: false })
+  @OptionalButNotNullableVueProperty
+  protected readonly required!: boolean;
+
+  @VueProperty({ type: Boolean, default: false })
+  @OptionalButNotNullableVueProperty
+  protected readonly mustDisplayAppropriateBadgeIfInputIsRequired!: boolean;
+
+  @VueProperty({ type: Boolean, default: false })
+  @OptionalButNotNullableVueProperty
+  protected readonly mustDisplayAppropriateBadgeIfInputIsOptional!: boolean;
+
+  @VueProperty({ type: Boolean, default: false })
+  @OptionalButNotNullableVueProperty
+  protected readonly mustAddInvisibleBadgeForHeightEqualizingWhenNoBadge!: boolean;
+
+
+  /* ─── State Limitations ─────────────────────────────────────────────────────────────────────────────────────────── */
+  @VueProperty({ type: Boolean, default: false })
+  @OptionalButNotNullableVueProperty
+  protected readonly disabled!: boolean;
+
+  @VueProperty({ type: Boolean, default: false })
+  @OptionalButNotNullableVueProperty
+  protected readonly readonly!: boolean;
+  // ━━━ TODO ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /* === State ====================================================================================================== */
+  protected invalidInputHighlightingIfAnyValidationErrorsMessages: boolean = false;
+  protected validInputHighlightingIfAnyErrorsMessages: boolean = false;
+
+
+  /* === Methods ==================================================================================================== */
+  public highlightInvalidInput(): this {
+    this.invalidInputHighlightingIfAnyValidationErrorsMessages = true;
+    return this;
+  }
+
+  public getRootElement(): Element {
+    return this.$el;
+  }
+
+  public resetStateToInitial(): void {
+    Object.assign(this.$data, this.$options.data?.({}));
+  }
+
+
+  /* === Livecycle hooks ========================================================================================== */
+  public beforeCreate(): void {
+
+    const inheritedComponentNameForLogging: string = this.$options.name ?? "(Unnamed component)";
+
+    if (
+      isEitherUndefinedOrNull(this.label) &&
+      isEitherUndefinedOrNull(this.accessibilityGuidance) &&
+      isEitherUndefinedOrNull(this.externalLabelHTML_ID)
+    ) {
+      Logger.logError({
+        errorType: InvalidVuePropertiesCombinationError.NAME,
+        title: InvalidVuePropertiesCombinationError.localization.defaultTitle,
+        description: InvalidVuePropertiesCombinationError.localization.generateMessage({
+          vueComponentName: inheritedComponentNameForLogging,
+          messageSpecificPart: "From the accessibility requirements, one of next properties must be specified:\n" +
+              "● label\n● accessibilityGuidance\n● externalLabelHTML_ID"
+
+        }),
+        occurrenceLocation: `${ inheritedComponentNameForLogging }.beforeCreate()`
+      });
+    }
+
+  }
+
+}

package/Source/GUI_Components/Controls/Validatables/TextBox/TextBox.vue.pug

@@ -0,0 +1,29 @@
+ValidatableControlShell.TextBox--YDF(
+
+  :label="label"
+  :guidance="guidance"
+
+  :required="required"
+  :mustDisplayAppropriateBadgeIfInputIsRequired="mustDisplayAppropriateBadgeIfInputIsRequired"
+  :mustDisplayAppropriateBadgeIfInputIsOptional="mustDisplayAppropriateBadgeIfInputIsOptional"
+  :mustAddInvisibleBadgeForHeightEqualizingWhenNoBadge="mustAddInvisibleBadgeForHeightEqualizingWhenNoBadge"
+
+)
+
+  textarea.TextBox--YDF-InputOrTextAreaElement(
+    v-if="multiline"
+    :placeholder="placeholder"
+    :readonly="readonly"
+    :disabled="disabled"
+    :required="required"
+  )
+
+  //- [ Bundler bug ] The `v-else` is being compiled to `v-else="v-else"`
+  input.TextBox--YDF-InputOrTextAreaElement(
+    v-else-if="!multiline"
+    :type="HTML_Type"
+    :placeholder="placeholder"
+    :readonly="readonly"
+    :disabled="disabled"
+    :required="required"
+  )