initial implementation of kimg component

docs/pages/kimg.vue

@@ -0,0 +1,113 @@
+<template>
+
+  <DocsPageTemplate apiDocs>
+    <DocsPageSection title="Overview" anchor="#overview">
+      <div>
+        The <DocsLibraryLink component="KImg" /> component displays images based on an image source and optional image
+        dimensions provided by the implementer.
+
+        <h3>Sample implementations of <DocsLibraryLink component="KImg" /> including props:</h3>
+
+        <div>
+          Dimensions may be either numbers or strings consisting of a numeral and valid units (e.g. <code>px</code>,
+          <code>em</code>, <code>vh</code>).
+        </div>
+
+        <div class="img-example-1">
+          <DocsShow>
+            <KImg
+              :src="require('../assets/img_sample_for_kimg.png')"
+              altText="Computers are run by bees"
+              :height="'250px'"
+              :width="225"
+            />
+          </DocsShow>
+
+          <pre><samp>
+            :src="require('../assets/img_sample_for_kimg.png')"
+            altText="Computers are run by bees"
+            :height="'250px'"
+            :width="225"
+          </samp></pre>
+        </div>
+      </div>
+
+      <div class="img-example-2">
+        <DocsLibraryLink component="KImg" /> requires alternative text that describes the image unless
+        <code>isDecorative</code> is <code>true</code>. In that case, any alt text provided will be overwritten to an
+        empty string.
+        <div>
+          <div>
+            <DocsShow>
+              <KImg
+                :src="require('../assets/img_sample_for_kimg.png')"
+                isDecorative
+                :height="50"
+                :width="50"
+              />
+            </DocsShow>
+          </div>
+          <pre><samp>
+            :src="require('../assets/img_sample_for_kimg.png')"
+            isDecorative
+            :height="50"
+            :width="50"
+          </samp></pre>
+        </div>
+      </div>
+
+      <div>
+        If dimensions for the image are not specified, the size will default to the height and width of the source
+        image.
+        <DocsShow>
+          <KImg
+            :src="require('../assets/img_sample_for_kimg.png')"
+            altText="Computers are run by bees"
+          />
+        </DocsShow>
+        <pre><samp>
+          :src="require('../assets/img_sample_for_kimg.png')"
+          altText="Computers are run by bees"
+        </samp></pre>
+      </div>
+    </DocsPageSection>
+  </DocsPageTemplate>
+
+</template>
+
+
+<script>
+
+  export default {};
+
+</script>
+
+
+<style lang="scss" scoped>
+
+  pre {
+    margin: 0;
+  }
+
+  .img-example-1 {
+    display: flex;
+    margin-top: 20px;
+  }
+
+  .img-example-2 {
+    margin-top: 20px;
+    margin-bottom: 20px;
+  }
+
+  .img-example-2 > div {
+    display: flex;
+  }
+
+  .img-example-2 > div > div {
+    margin-top: 30px;
+  }
+
+</style>
+
+
+

docs/tableOfContents.js

@@ -232,6 +232,11 @@ export default [
         isCode: true,
         keywords: buttonRelatedKeywords,
       }),
+      new Page({
+        path: '/kimg',
+        title: 'KImg',
+        isCode: true,
+      }),
       new Page({
         path: '/klabeledicon',
         title: 'KLabeledIcon',

lib/KImg.vue

@@ -0,0 +1,159 @@
+<template>
+
+  <div>
+    <img
+      id="kimg"
+      :src="src"
+      :alt="alternateText"
+      :style="cssVars"
+    >
+    <slot></slot>
+  </div>
+
+</template>
+
+
+<script>
+
+  export default {
+    name: 'KImg',
+    props: {
+      /**
+       * Sets the image path
+       */
+      src: {
+        type: String,
+        default: null,
+      },
+      /**
+       * Alternate text for the image. This is required and will throw a warning when it's not provided (empty) unless isDecorative is true
+       */
+      altText: {
+        type: String,
+        default: '',
+      },
+      /**
+       * Sets the image as decorative. This sets the alt image property to an empty string.
+       */
+      isDecorative: {
+        type: Boolean,
+        default: false,
+      },
+      /**
+       * Sets the height for the component
+       */
+      height: {
+        type: [Number, String],
+        default: undefined,
+      },
+      /**
+       * Sets the width for the component
+       */
+      width: {
+        type: [Number, String],
+        default: undefined,
+      },
+      /**
+       * Sets the maximum height for the component
+       */
+      maxHeight: {
+        type: [Number, String],
+        default: undefined,
+      },
+      /**
+       * Sets the minimum height for the component
+       */
+      minHeight: {
+        type: [Number, String],
+        default: undefined,
+      },
+      /**
+       * Sets the maximum width for the component
+       */
+      maxWidth: {
+        type: [Number, String],
+        default: undefined,
+      },
+      /**
+       * 	Sets the minimum width for the component
+       */
+      minWidth: {
+        type: [Number, String],
+        default: undefined,
+      },
+    },
+    computed: {
+      alternateText() {
+        return this.isDecorative ? '' : this.altText;
+      },
+      imgHeight() {
+        return this.validateAndFormatUnits(this.height);
+      },
+      imgWidth() {
+        return this.validateAndFormatUnits(this.width);
+      },
+      imgMaxHeight() {
+        return this.validateAndFormatUnits(this.maxHeight);
+      },
+      imgMinHeight() {
+        return this.validateAndFormatUnits(this.minHeight);
+      },
+      imgMaxWidth() {
+        return this.validateAndFormatUnits(this.maxWidth);
+      },
+      imgMinWidth() {
+        return this.validateAndFormatUnits(this.minWidth);
+      },
+      cssVars() {
+        return {
+          '--height': this.imgHeight,
+          '--width': this.imgWidth,
+          '--max-height': this.imgMaxHeight,
+          '--min-height': this.imgMinHeight,
+          '--max-width': this.imgMaxWidth,
+          '--min-width': this.imgMinWidth,
+        };
+      },
+    },
+    created() {
+      if (!this.isDecorative && !this.altText) {
+        throw new Error('Missing required prop - provide altText or indicate isDecorative');
+      }
+    },
+    methods: {
+      validateAndFormatUnits(propValue) {
+        if (propValue) {
+          if (Number.isInteger(propValue)) {
+            return `${propValue}px`;
+          } else {
+            // split numbers apart from units
+            const [, ...arr] = propValue.match(/(\d*)([\s\S]*)/);
+            const validUnits = ['px', 'em', 'rem', 'vh'];
+
+            // if made up of valid numbers and valid units
+            if (!isNaN(arr[0]) && validUnits.includes(arr[1])) {
+              return propValue;
+            }
+          }
+        }
+        return 'auto';
+      },
+    },
+  };
+
+</script>
+
+
+<style scoped>
+
+  #kimg {
+    height: var(--height);
+    width: var(--width);
+    max-height: var(--max-height);
+    min-height: var(--min-height);
+    max-width: var(--max-width);
+    min-width: var(--min-width);
+  }
+
+</style>
+

lib/KThemePlugin.js

@@ -15,6 +15,7 @@ import KGrid from './grids/KGrid';
 import KGridItem from './grids/KGridItem';
 import KIcon from './KIcon';
 import KIconButton from './buttons-and-links/KIconButton';
+import KImg from './KImg';
 import KLabeledIcon from './KLabeledIcon';
 import KLinearLoader from './loaders/KLinearLoader';
 import KModal from './KModal';
@@ -99,6 +100,7 @@ export default function KThemePlugin(Vue) {
   Vue.component('KGridItem', KGridItem);
   Vue.component('KIcon', KIcon);
   Vue.component('KIconButton', KIconButton);
+  Vue.component('KImg', KImg);
   Vue.component('KLabeledIcon', KLabeledIcon);
   Vue.component('KLinearLoader', KLinearLoader);
   Vue.component('KModal', KModal);