From 6b0a82ce65f28ca80a5f9c1fa2c24cf45b79c92f Mon Sep 17 00:00:00 2001
From: Allan Otodi Opeto <103313919+AllanOXDi@users.noreply.github.com>
Date: Fri, 2 Aug 2024 20:27:19 +0300
Subject: [PATCH] restores code comments

---
 lib/KCard/index.vue | 104 +++++++++++++++++++++++++++++++++++---------
 1 file changed, 84 insertions(+), 20 deletions(-)

diff --git a/lib/KCard/index.vue b/lib/KCard/index.vue
index 882807411..52062a2fc 100644
--- a/lib/KCard/index.vue
+++ b/lib/KCard/index.vue
@@ -5,21 +5,19 @@
     :title="title"
     :headingLevel="headingLevel"
     :titleLines="titleLines"
-    :class="rootClasses"
+    :class="['k-card',rootClasses]"
     :headingStyles="headingStyles"
   >
     <template v-if="$slots.title" #title>
-      <div
-        data-test="title"
-        class="title"
-      >
-
-        <!-- @slot Optional slot section containing the title contents, should not contain a heading element. -->
-        <slot name="title"></slot>
-      </div>
+      <!-- @slot Optional slot section containing the title contents, should not contain a heading element. -->
+      <slot name="title"></slot>
     </template>
     <template #default>
       <div class="thumbnail">
+        <!--
+          Render KImg even if thumbnailSrc is not provided since in that case
+          KImg
+        -->
         <KImg
           :src="thumbnailSrc"
           :scaleType="thumbnailScaleType"
@@ -27,6 +25,13 @@
           :isDecorative="true"
           :appearanceOverrides="thumbnailStyles"
         />
+        <!--
+          This is a duplicate of the same slot in KImg. I didn't find a way to utilize
+          KImg's placeholder slot from here, likely because this part of code is nested
+          in one slot already
+          Show it even when thumbnail source is provided - then the placeholder serves
+          as progressive loading experience.
+        -->
         <span
           v-if="$slots.thumbnailPlaceholder"
           class="thumbnail-placeholder"
@@ -77,40 +82,84 @@
     name: 'KCard',
     components: { BaseCard, KImg },
     props: {
+      /**
+       * Sets card title if provided. The title should be
+       * unique and descriptive to aid searching through list of links.
+       */
       title: {
         type: String,
         required: false,
         default: null,
       },
+      /**
+       * Sets the HTML heading level in range (h2 - h6) for the title .
+       */
       headingLevel: {
         type: Number,
         required: true,
       },
+      /**
+       * An object containing the route definition for the link.
+       * Required and cannot be empty.
+       */
       to: {
         type: Object,
         required: true,
       },
+      /**
+       * Controls card orientation. Required and cannot be empty.
+       * Expected Options: 'horizontal' (default) or 'vertical'.
+       *
+       * @param {String} value - The layout value.
+       * @returns {Boolean} - True if the value is not empty, false otherwise.
+       */
       layout: {
         type: String,
         default: 'horizontal',
         validator: value => ['horizontal', 'vertical'].includes(value),
       },
+      /**
+       * Controls how the thumbnail appears in the card.
+       * Expected Options: 'none' (default), 'small', or 'large'.
+       * */
       thumbnailDisplay: {
         type: String,
         required: false,
         default: 'none',
         validator: value => ['none', 'small', 'large'].includes(value),
       },
+      /**
+       * Sets the thumbnail path.
+       * Defaults to null if not provided.
+       *
+       * @type {String}
+       * @default null
+       * */
       thumbnailSrc: {
         type: String,
         required: false,
         default: null,
       },
+
+      /**
+       * Specifies how the thumbnail scales in the card.
+       * Options: 'centerInside', 'contain', 'fitXY'.
+       * @type {String}
+       * @default 'centerInside'
+       */
       thumbnailScaleType: {
         type: String,
         default: 'centerInside',
         validator: value => ['centerInside', 'contain', 'fitXY'].includes(value),
       },
+      /**
+       * Sets the thumbnail in a specific direction on the card.
+       * Options: 'left', 'right'.
+       * Defaults to left if not provided.
+       *
+       * @type {String}
+       * @default left
+       * */
       thumbnailAlign: {
         type: String,
         default: ThumbnailAlign.LEFT,
@@ -119,7 +168,7 @@
     },
     computed: {
       rootClasses() {
-        return ['k-card', `thumbnail-${this.thumbnailAlign}`, ...this.stylesAndClasses.rootClasses];
+        return [`thumbnail-${this.thumbnailAlign}`, ...this.stylesAndClasses.rootClasses];
       },
       titleLines() {
         return this.stylesAndClasses.titleLines;
@@ -133,6 +182,12 @@
       thumbnailStyles() {
         return this.stylesAndClasses.thumbnailStyles;
       },
+      /*
+        Returns dynamic classes and few style-like data that CSS was cumbersome/impossible to use for ,or are in need of using theme, grouped by all possible combinations of layouts.
+        New styles and classes are meant to be added to this single-source-of-truth object so
+        that we can easily locate all styling being applied to a particular layout
+        Could be further simplified by using solely dynamic styles, but that would have detrimental effects on our auto RTL machinery and we would need to take care manually of more places.
+      */
       stylesAndClasses() {
         const baseClasses = [];
         const headingCommonStyles = {
@@ -229,8 +284,16 @@
 
   $spacer: 12px;
 
+  /*
+      Just couple of comments that are referenced from several places:
+      - (1) Intentionally fixed. Cards on the same row of a grid should have the same overall height and their sections too should have the same height so that information is placed consistently. As documented, consumers need to ensure that contents provided via slots fits well or is truncated.
+      - (2) Solves issues with fixed height in a flex item
+    */
+
+  /************* Common styles **************/
+
   .k-card {
-    position: relative;
+    position: relative; /* basis for absolute positioning of thumbnail images */
     display: flex;
     flex-direction: column;
     flex-wrap: nowrap;
@@ -239,24 +302,24 @@
   }
 
   .thumbnail {
-    position: relative;
+    position: relative; /* basis for absolute positioning of 'thumbnailPlaceholder' slot content */
     order: 1;
   }
 
   .above-title {
     order: 2;
-    height: 24px;
-    min-height: 24px;
+    height: 24px; /* (1) */
+    min-height: 24px; /* (2) */
     margin: $spacer $spacer 0;
-    overflow: hidden;
+    overflow: hidden; /* (1) */
   }
 
   .below-title {
     order: 4;
-    height: 18px;
-    min-height: 18px;
+    height: 18px; /* (1) */
+    min-height: 18px; /* (2) */
     margin: 0 $spacer $spacer;
-    overflow: hidden;
+    overflow: hidden; /* (1) */
   }
 
   .footer {
@@ -273,9 +336,10 @@
     right: 0;
     bottom: 0;
     left: 0;
-    z-index: 0;
+    z-index: 0; /* <img> in KImg with z-index 1 should cover the placeholder after loaded */
   }
 
+  /************* Layout-specific styles *************/
   .vertical {
     &.with-large-thumbnail {
       height: 480px;
@@ -310,7 +374,7 @@
       .above-title,
       .below-title,
       .footer {
-        width: calc(60% - 2 * #{$spacer});
+        width: calc(60% - 2 * #{$spacer}); /* same as heading width defined in script */
       }
 
       &.thumbnail-left {