@yamato-daiwa/frontend-vue 0.1.0 → 0.3.0-alpha.1

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

@@ -0,0 +1,64 @@
+.ValidatableControlShell--YDF(
+  :class="rootElementModifierCSS_Classes"
+)
+
+  .ValidatableControlShell--YDF-Header(
+    v-if="mustDisplayHeader"
+  )
+
+    label.ValidatableControlShell--YDF-Label(
+      v-if="label"
+      :for="coreElementHTML_ID"
+      :id="labelElementHTML_ID"
+    ) {{ label }}
+
+    Badge.ValidatableControlShell--YDF-Badge.ValidatableControlShell--YDF-Badge__Required(
+      v-if="mustDisplayRequiredInputBadge"
+      :valueLabel="localization.requirementBadges.required"
+      :theme="badgeTheme"
+      :geometricVariation="badgeGeometricVariation"
+      :geometricModifiers="[ Badge.GeometricModifiers.pillShape ]"
+      :decorativeVariation="requiredInputBadgeDecorativeVariation"
+    )
+
+    Badge.ValidatableControlShell--YDF-Badge.ValidatableControlShell--YDF-Badge__Optional(
+      v-else-if="mustDisplayOptionalInputBadge"
+      :valueLabel="localization.requirementBadges.optional"
+      :theme="badgeTheme"
+      :geometricVariation="badgeGeometricVariation"
+      :geometricModifiers="[ Badge.GeometricModifiers.pillShape ]"
+      :decorativeVariation="optionalInputBadgeDecorativeVariation"
+    )
+
+    Badge.ValidatableControlShell--YDF-Badge.ValidatableControlShell--YDF-Badge__Invisible(
+      v-else-if="mustAddInvisibleBadgeForHeightEqualizingWhenNoBadge"
+      :valueLabel="localization.requirementBadges.optional"
+      :theme="badgeTheme"
+      :geometricVariation="badgeGeometricVariation"
+      :geometricModifiers="[ Badge.GeometricModifiers.pillShape ]"
+      :decorativeVariation="optionalInputBadgeDecorativeVariation"
+    )
+
+
+  p.ValidatableControlShell--YDF-Guidance(
+    v-if="formattedGuidance"
+    v-html="formattedGuidance"
+  )
+
+
+  .ValidatableControlShell--YDF-MainSlotCustomizableWrapper(
+    :class="mainSlotWrapperAdditionalCSS_Classes"
+  )
+    slot
+
+
+  VerticallySlidingAlwaysMountedContainer.ValidatableControlShell--YDF-ValidationErrorsMessagesList(
+    :modelValue="invalidInputHighlightingIfAnyValidationErrorsMessages && validationErrorsMessages.length > 0"
+    tag="ul"
+    :duration="errorsListExpandingAnimationDuration__milliseconds"
+  )
+
+    li.ValidatableControlShell--YDF-ValidationErrorsMessagesList-Item(
+      v-for="validationErrorMessage of validationErrorsMessagesCopyForAnimating"
+      :key="validationErrorMessage"
+    ) {{ validationErrorMessage }}

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

@@ -0,0 +1,478 @@
+/* ─── Assets ─────────────────────────────────────────────────────────────────────────────────────────────────────── */
+import componentVueTemplate from "./ValidatableControlShell.vue.pug";
+import {
+  type ValidatableControlShellLocalization,
+  validatableControlShellYDF_ComponentLocalization__english,
+  replaceMarkdownBold,
+  replaceMarkdownLink
+} from "@yamato-daiwa/frontend";
+
+/* ─── Related GUI Components ─────────────────────────────────────────────────────────────────────────────────────── */
+import Badge from "../../Badge/Badge.vue";
+import { Vue3SlideUpDown as VerticallySlidingAlwaysMountedContainer } from "vue3-slide-up-down";
+
+/* ─── Validations ────────────────────────────────────────────────────────────────────────────────────────────────── */
+import VuePropertyValidator from "../../_VuePropertiesValidators/VuePropertyValidator";
+import preventNullForOptionalVueProperty from "../../_Decorators/preventNullForOptionalVueProperty";
+import NonEmptyStringVuePropertyValidator from "../../_VuePropertiesValidators/NonEmptyStringVuePropertyValidator";
+import BooleanVuePropertyValidator from "../../_VuePropertiesValidators/BooleanVuePropertyValidator";
+import ThemeVuePropertyValidator from "../../_VuePropertiesValidators/ThemeVuePropertyValidator";
+import GeometricVariationVuePropertyValidator from "../../_VuePropertiesValidators/GeometricVariationVuePropertyValidator";
+import DecorativeVariationVuePropertyValidator from "../../_VuePropertiesValidators/DecorativeVariationVuePropertyValidator";
+
+/* ─── 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 AccessibleFromTemplateAsNonReactive from "../../_Decorators/AccessibleFromTemplateAsNonReactive";
+import {
+  secondsToMilliseconds,
+  isArrayOfCertainTypeElements,
+  isNonEmptyString,
+  isNotUndefined
+} from "@yamato-daiwa/es-extensions";
+
+
+@VueComponentConfiguration({
+  name: ValidatableControlShell.CSS_NAMESPACE,
+  template: componentVueTemplate,
+  components: {
+    Badge,
+    VerticallySlidingAlwaysMountedContainer
+  }
+})
+class ValidatableControlShell extends VueComponent {
+
+  public static CSS_NAMESPACE: string = "ValidatableControlShell--YDF";
+
+
+  /* ━━━ Component Common Properties ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  /* ─── Textings ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+  @VueProperty({
+    required: false,
+    get validator(): VuePropertyValidator {
+      return NonEmptyStringVuePropertyValidator({
+        propertyName: "label",
+        isPropertyRequired: this.required === true,
+        componentName: ValidatableControlShell.CSS_NAMESPACE
+      });
+    }
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly label?: string;
+
+  @VueProperty({
+    required: false,
+    get validator(): VuePropertyValidator {
+      return NonEmptyStringVuePropertyValidator({
+        propertyName: "guidance",
+        isPropertyRequired: this.required === true,
+        componentName: ValidatableControlShell.CSS_NAMESPACE
+      });
+    }
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly guidance?: string;
+
+  protected get formattedGuidance(): string | null {
+    return isNotUndefined(this.guidance) ?
+        replaceMarkdownLink(
+          replaceMarkdownBold(
+            this.guidance,
+            (boldedContent: string): string =>
+                `<span class="ValidatableControlShell--YDF-Guidance-AccentedFragment">${ boldedContent }</span>`
+          ),
+          ({ URI, anchorText }: Readonly<{ URI: string; anchorText: string; }>): string =>
+            "<a " +
+              "class=\"Link--YDF ValidatableControlShell--YDF-Guidance-Link\" " +
+              `href="${ URI }" ` +
+              "target=\"_blank\" " +
+              "rel=\"noopener noreferrer nofollow\"" +
+            ">" +
+              anchorText +
+            "</a>"
+        ) :
+        null;
+  }
+
+
+  /* ─── Inputting Requirement ────────────────────────────────────────────────────────────────────────────────────── */
+  @VueProperty({
+    default: false,
+    get validator(): VuePropertyValidator {
+      return BooleanVuePropertyValidator({
+        propertyName: "required",
+        isPropertyRequired: this.required === true,
+        componentName: ValidatableControlShell.CSS_NAMESPACE
+      });
+    }
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly required!: boolean;
+
+  @VueProperty({
+    default: false,
+    get validator(): VuePropertyValidator {
+      return BooleanVuePropertyValidator({
+        propertyName: "mustDisplayAppropriateBadgeIfInputIsRequired",
+        isPropertyRequired: this.required === true,
+        componentName: ValidatableControlShell.CSS_NAMESPACE
+      });
+    }
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly mustDisplayAppropriateBadgeIfInputIsRequired!: boolean;
+
+  @VueProperty({
+    default: false,
+    get validator(): VuePropertyValidator {
+      return BooleanVuePropertyValidator({
+        propertyName: "mustDisplayAppropriateBadgeIfInputIsOptional",
+        isPropertyRequired: this.required === true,
+        componentName: ValidatableControlShell.CSS_NAMESPACE
+      });
+    }
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly mustDisplayAppropriateBadgeIfInputIsOptional!: boolean;
+
+  @VueProperty({
+    default: false,
+    get validator(): VuePropertyValidator {
+      return BooleanVuePropertyValidator({
+        propertyName: "mustAddInvisibleBadgeForHeightEqualizingWhenNoBadge",
+        isPropertyRequired: this.required === true,
+        componentName: ValidatableControlShell.CSS_NAMESPACE
+      });
+    }
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly mustAddInvisibleBadgeForHeightEqualizingWhenNoBadge!: boolean;
+
+
+    /* ─── Displaying of Validation Messages ────────────────────────────────────────────────────────────────────────── */
+  @VueProperty({
+    default: false,
+    get validator(): VuePropertyValidator {
+      return BooleanVuePropertyValidator({
+        propertyName: "invalidInputHighlightingIfAnyValidationErrorsMessages",
+        isPropertyRequired: this.required === true,
+        componentName: ValidatableControlShell.CSS_NAMESPACE
+      });
+    }
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly invalidInputHighlightingIfAnyValidationErrorsMessages!: boolean;
+
+  @VueProperty({
+    default: false,
+    get validator(): VuePropertyValidator {
+      return BooleanVuePropertyValidator({
+        propertyName: "validValueHighlightingIfNoValidationErrorsMessages",
+        isPropertyRequired: this.required === true,
+        componentName: ValidatableControlShell.CSS_NAMESPACE
+      });
+    }
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly validValueHighlightingIfNoValidationErrorsMessages!: boolean;
+
+
+  /* ─── HTML IDs ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+  @VueProperty({
+    required: false,
+    get validator(): VuePropertyValidator {
+      return NonEmptyStringVuePropertyValidator({
+        propertyName: "coreElementHTML_ID",
+        isPropertyRequired: this.required === true,
+        componentName: ValidatableControlShell.CSS_NAMESPACE
+      });
+    }
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly coreElementHTML_ID?: string;
+
+  @VueProperty({
+    required: false,
+    get validator(): VuePropertyValidator {
+      return NonEmptyStringVuePropertyValidator({
+        propertyName: "labelElementHTML_ID",
+        isPropertyRequired: this.required === true,
+        componentName: ValidatableControlShell.CSS_NAMESPACE
+      });
+    }
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly labelElementHTML_ID?: string;
+
+
+  /* ─── CSS Classes ──────────────────────────────────────────────────────────────────────────────────────────────── */
+  @VueProperty({
+    default: (): ReadonlyArray<string> => [],
+    validator: VuePropertyValidator.create({
+      checker: (rawValue: unknown): boolean => isArrayOfCertainTypeElements(rawValue, isNonEmptyString),
+      messageSpecificPart: "If specified, must be an array of non-empty strings.",
+      propertyName: "mainSlotWrapperAdditionalCSS_Classes",
+      componentName: ValidatableControlShell.CSS_NAMESPACE
+    })
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly mainSlotWrapperAdditionalCSS_Classes!: ReadonlyArray<string>;
+
+
+  /* ━━━ Validation Errors Messages ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  @VueProperty({
+    default: (): ReadonlyArray<string> => [],
+    validator: VuePropertyValidator.create({
+      checker: (rawValue: unknown): boolean => isArrayOfCertainTypeElements(rawValue, isNonEmptyString),
+      messageSpecificPart: "If specified, must be an array of non-empty strings.",
+      propertyName: "validationErrorsMessages",
+      componentName: ValidatableControlShell.CSS_NAMESPACE
+    })
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly validationErrorsMessages!: ReadonlyArray<string>;
+
+  /* [ Theory ]
+   * Even if `validationErrorsMessages` has become to empty array, the validation errors messages are still
+   *   required to animate the collapsing. */
+  protected validationErrorsMessagesCopyForAnimating: ReadonlyArray<string> = [ ...this.validationErrorsMessages ];
+
+  protected static readonly ERRORS_LIST_EXPANDING_ANIMATION_DURATION_PER_ONE_ERROR_MESSAGE__SECONDS: number = 0.2;
+
+  protected get errorsListExpandingAnimationDuration__milliseconds(): number {
+    return secondsToMilliseconds(
+      ValidatableControlShell.ERRORS_LIST_EXPANDING_ANIMATION_DURATION_PER_ONE_ERROR_MESSAGE__SECONDS *
+      this.validationErrorsMessagesCopyForAnimating.length
+    );
+  }
+
+  @onVueComponentFieldUpdated("invalidInputHighlightingIfAnyValidationErrorsMessages")
+  @onVueComponentFieldUpdated("validationErrorsMessages")
+  protected onValidationErrorsMessagesUpdated(): void {
+
+    if (this.validationErrorsMessages.length > 0) {
+      this.validationErrorsMessagesCopyForAnimating = [ ...this.validationErrorsMessages ];
+      return;
+    }
+
+
+    setTimeout(
+      (): void => {
+        this.validationErrorsMessagesCopyForAnimating = [];
+      },
+      this.errorsListExpandingAnimationDuration__milliseconds
+    );
+
+  }
+
+
+  /* ━━━ Conditional Rendering ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  protected get mustDisplayRequiredInputBadge(): boolean {
+    return this.required && this.mustDisplayAppropriateBadgeIfInputIsRequired;
+  }
+
+  protected get mustDisplayOptionalInputBadge(): boolean {
+    return !this.required && this.mustDisplayAppropriateBadgeIfInputIsOptional;
+  }
+
+  protected get mustDisplayHeader(): boolean {
+    return isNotUndefined(this.label) ||
+      this.mustDisplayRequiredInputBadge ||
+      this.mustDisplayOptionalInputBadge ||
+      this.mustAddInvisibleBadgeForHeightEqualizingWhenNoBadge;
+  }
+
+
+  /* ━━━ Theming ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  public static readonly Themes: ValidatableControlShell.Themes = { regular: "REGULAR" };
+
+  public static readonly selfAndChildrenComponentsThemesCorrespondence:
+      { badge: { [ownThemeValue: string]: string; }; } =
+          { badge: { [ValidatableControlShell.Themes.regular]: Badge.Themes.regular } };
+
+  @VueProperty({
+    default: ValidatableControlShell.Themes.regular,
+    validator: ThemeVuePropertyValidator(ValidatableControlShell)
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly theme!: string;
+
+  protected get badgeTheme(): string {
+    return ValidatableControlShell.selfAndChildrenComponentsThemesCorrespondence.badge[this.theme];
+  }
+
+  public static defineThemes(
+    ownAndChildrenThemesCorrespondenceDefinition: Readonly<{
+      [ownThemeKey: string]: Readonly<{ badge: string; }>;
+    }>
+  ): typeof ValidatableControlShell {
+    return YDF_ComponentsCoordinator.defineThemesAndSetCorrespondenceWithOnesOfChildrenComponents(
+      ownAndChildrenThemesCorrespondenceDefinition, ValidatableControlShell
+    );
+  }
+
+  public static areThemesCSS_ClassesCommon: boolean = YDF_ComponentsCoordinator.areThemesCSS_ClassesCommon;
+
+  public static considerThemesAsCommon(): void {
+    ValidatableControlShell.areThemesCSS_ClassesCommon = true;
+  }
+
+  @VueProperty({
+    default: ValidatableControlShell.areThemesCSS_ClassesCommon,
+    get validator(): VuePropertyValidator {
+      return BooleanVuePropertyValidator({
+        propertyName: "areThemesCSS_ClassesCommon",
+        componentName: ValidatableControlShell.CSS_NAMESPACE,
+        isPropertyRequired: this.required === true
+      });
+    }
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly areThemesCSS_ClassesCommon!: boolean;
+
+
+  /* ─── Geometry ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+  public static readonly GeometricVariations: ValidatableControlShell.GeometricVariations = {
+    regular: "REGULAR",
+    small: "SMALL"
+  };
+
+  public static readonly selfAndChildrenComponentsGeometricVariationsCorrespondence:
+      { badge: { [ownGeometricVariationValue: string]: string; }; } =
+          {
+            badge: {
+
+              [ValidatableControlShell.GeometricVariations.regular]: Badge.GeometricVariations.regular,
+
+              /* [ Approach ]
+               * `Badge__YDF.GeometricVariations.regular` is NOT a mistake because `Badge__YDF.GeometricVariations.small`
+               *    is too small, while the actual size can be flexibly adjusted by relative CSS units.
+               * */
+              [ValidatableControlShell.GeometricVariations.small]: Badge.GeometricVariations.regular
+
+            }
+          };
+
+  @VueProperty({
+    default: ValidatableControlShell.GeometricVariations.regular,
+    validator: GeometricVariationVuePropertyValidator(ValidatableControlShell)
+  })
+  @preventNullForOptionalVueProperty
+  protected readonly geometricVariation!: string;
+
+  protected get badgeGeometricVariation(): string {
+    return ValidatableControlShell.selfAndChildrenComponentsGeometricVariationsCorrespondence.badge[this.geometricVariation];
+  }
+
+  public static defineGeometricVariations(
+    ownAndChildrenGeometricVariationsAndCorrespondenceDefinition: Readonly<{
+      [ownGeometricVariationKey: string]: Readonly<{ badge: string; }>;
+    }>
+  ): typeof ValidatableControlShell {
+    return YDF_ComponentsCoordinator.defineGeometricVariationsAndSetCorrespondenceWithOnesOfChildrenComponents(
+      ownAndChildrenGeometricVariationsAndCorrespondenceDefinition, ValidatableControlShell
+    );
+  }
+
+
+  /* ─── Decoration ───────────────────────────────────────────────────────────────────────────────────────────────── */
+  public static readonly DecorativeVariations: ValidatableControlShell.DecorativeVariations = { regular: "REGULAR" };
+
+  public static readonly selfAndChildrenComponentsDecorativeVariationsCorrespondence:
+      {
+        requiredInputBadge: { [ownDecorativeVariationValue: string]: string; };
+        optionalInputBadge: { [ownDecorativeVariationValue: string]: string; };
+      } =
+          {
+            requiredInputBadge: {
+              [ValidatableControlShell.DecorativeVariations.regular]: Badge.DecorativeVariations.veryCatchyBright
+            },
+            optionalInputBadge: {
+              [ValidatableControlShell.DecorativeVariations.regular]: Badge.DecorativeVariations.modestlyCalmingBright
+            }
+          };
+
+  @VueProperty({
+    default: ValidatableControlShell.GeometricVariations.regular,
+    validator: DecorativeVariationVuePropertyValidator(ValidatableControlShell)
+  })
+  protected readonly decorativeVariation!: string;
+
+  protected get requiredInputBadgeDecorativeVariation(): string {
+    return ValidatableControlShell.selfAndChildrenComponentsDecorativeVariationsCorrespondence.
+        requiredInputBadge[this.decorativeVariation];
+  }
+
+  protected get optionalInputBadgeDecorativeVariation(): string {
+    return ValidatableControlShell.selfAndChildrenComponentsDecorativeVariationsCorrespondence.
+        optionalInputBadge[this.decorativeVariation];
+  }
+
+  public static defineDecorativeVariations(
+    ownAndChildrenDecorativeVariationsAndCorrespondenceDefinition: Readonly<{
+      [ownDecorativeVariationKey: string]: Readonly<{
+        requiredInputBadge: string;
+        optionalInputBadge: string;
+      }>;
+    }>
+  ): typeof ValidatableControlShell {
+    return YDF_ComponentsCoordinator.defineDecorativeVariationsAndSetCorrespondenceWithOnesOfChildrenComponents(
+      ownAndChildrenDecorativeVariationsAndCorrespondenceDefinition, 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
+    });
+  }
+
+
+  /* ━━━ Non-reactive Fields ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  @AccessibleFromTemplateAsNonReactive
+  protected static readonly Badge: typeof Badge = Badge;
+
+  @AccessibleFromTemplateAsNonReactive
+  public static localization: ValidatableControlShellLocalization = validatableControlShellYDF_ComponentLocalization__english;
+
+}
+
+
+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;