Add slots and placeholder logic

MisRob · Jan 12, 2024 · efce7f3 · efce7f3
1 parent 8100cb7
commit efce7f3
Show file tree

Hide file tree

Showing 2 changed files with 131 additions and 3 deletions.
diff --git a/docs/pages/kimg.vue b/docs/pages/kimg.vue
@@ -198,6 +198,74 @@
           />
         </div>
       </DocsShow>
+
+      <h3>Placeholder</h3>
+
+      <p>You can use the <code>#placeholder</code> slot to place its content to the placeholder area. The area is gray by default and respects set dimensions of the image container. You can change its color via the the <code>backgroundColor</code> prop.</p>
+
+      <DocsShowCode language="html">
+        <div>
+          <KImg
+            src=""
+            isDecorative
+            aspectRatio="16:9"
+            maxWidth="200"
+          >
+            <template #placeholder>
+              <span :style="{ display: 'flex', height: '100%', justifyContent: 'center', alignItems: 'center' }">
+                <KIcon icon="readSolid" />
+              </span>
+            </template>
+          </KImg>
+        </div>
+      </DocsShowCode>
+      <DocsShow block>
+        <div>
+          <KImg
+            src=""
+            isDecorative
+            aspectRatio="16:9"
+            maxWidth="200"
+          >
+            <template #placeholder>
+              <span :style="{ display: 'flex', height: '100%', justifyContent: 'center', alignItems: 'center' }">
+                <KIcon icon="readSolid" />
+              </span>
+            </template>
+          </KImg>
+        </div>
+      </DocsShow>
+
+      <h3>Show elements on top of an image</h3>
+
+      <p>You can use <code>#topLeft</code>, <code>#topRight</code>, <code>#bottomLeft</code>, and <code>#bottomRight</code> slots to place elements on top of an image or placeholder area.</p>
+
+      <DocsShowCode language="html">
+        <KImg
+          src="hummingbird.jpg"
+          altText="A sitting hummingbird"
+        >
+          <template #topLeft>
+            <span :style="{ display: 'inline-block', margin: '8px', padding: '2px', backgroundColor: 'white' }">
+              Top left
+            </span>
+          </template>
+        </KImg>
+      </DocsShowCode>
+      <DocsShow>
+        <KImg
+          :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+          altText="A sitting hummingbird"
+        >
+          <template #topLeft>
+            <span :style="{ display: 'inline-block', margin: '8px', padding: '2px', backgroundColor: 'white' }">
+              Top left
+            </span>
+          </template>
+        </KImg>
+      </DocsShow>
+
+
     </DocsPageSection>
 
   </DocsPageTemplate>

diff --git a/lib/KImg.vue b/lib/KImg.vue
@@ -7,8 +7,43 @@
         :alt="alternativeText"
         :style="imgStyles"
       >
-      <!-- @slot An unstyled slot that can be used for anything that other slots are not suitable for. -->
-      <slot></slot>
+      <span
+        v-if="$slots.placeholder"
+        :style="{ position: 'absolute', top: '0', right: '0', left: '0', bottom: '0', zIndex: '0' }"
+      >
+        <!-- @slot Places content to the image placeholder area. -->
+        <slot name="placeholder"></slot>
+      </span>
+
+      <span
+        v-if="$slots.topLeft"
+        :style="{ position: 'absolute', top: '0',left: '0', zIndex: '2' }"
+      >
+        <!-- @slot Places content on top of an image, to its top left corner. -->
+        <slot name="topLeft"></slot>
+      </span>
+      <span
+        v-if="$slots.topRight"
+        :style="{ position: 'absolute', top: '0', right: '0', zIndex: '2' }"
+      >
+        <!-- @slot Places content on top of an image, to its top right corner. -->
+        <slot name="topRight"></slot>
+      </span>
+      <span
+        v-if="$slots.bottomLeft"  
+        :style="{ position: 'absolute', bottom: '0', left: '0', zIndex: '2' }"
+      >
+        <!-- @slot Places content on top of an image, to its bottom left corner. -->
+        <slot name="bottomLeft"></slot>
+      </span>
+      <span
+        v-if="$slots.bottomRight"
+        :style="{ position: 'absolute', bottom: '0', right: '0', zIndex: '2' }"
+      >
+        <!-- @slot Places content on top of an image, to its bottom right corner. -->
+        <slot name="bottomRight"></slot>
+      </span>
+
     </span>
   </span>
 
@@ -137,6 +172,24 @@
         default: 'centerInside', // needs to be duplicated rather than using ScaleTypes.CENTER_INSIDE, otherwise it doesn't render correctly in the auto-generated Props documentation
         validator: isValidScaleType,
       },
+      /**
+       * A color to be displayed instead or behind an image.
+       * It creates a background area which respects the dimensions
+       * set on the container.
+       *
+       * It can serve as (1) a color of the area surrounding an image when
+       * it's letterboxed, (2) creates a placeholder area displayed
+       * over the whole container when an image source is not provided,
+       * (3) creates a progressive loading experience as the colored background
+       * is displayed while an image is loading.
+       *
+       * Its default value is `$themePalette.grey.v_200`.
+       */
+      backgroundColor: {
+        type: String,
+        required: false,
+        default: null,
+      },
     },
     computed: {
       ratio() {
@@ -146,10 +199,15 @@
         return this.isDecorative ? '' : this.altText;
       },
       baseStyles() {
+        const backgroundColor = this.backgroundColor
+          ? this.backgroundColor
+          : this.$themePalette.grey.v_200;
+
         return {
           rootContainer: {
             display: 'block',
-            backgroundColor: this.$themePalette.grey.v_200,
+            position: 'relative',
+            backgroundColor,
             height: this.validateAndFormatUnits(this.height),
             width: this.validateAndFormatUnits(this.width),
             maxHeight: this.validateAndFormatUnits(this.maxHeight),
@@ -162,6 +220,8 @@
           },
           img: {
             display: 'block',
+            position: 'relative',
+            zIndex: '1',
           },
         };
       },