[WIP] Add scaling logic

MisRob · Nov 9, 2023 · 8b58d01 · 8b58d01
1 parent 9a61e60
commit 8b58d01
Show file tree

Hide file tree

Showing 5 changed files with 415 additions and 36 deletions.
diff --git a/docs/assets/hummingbird CC BY-SA 4.0.jpg b/docs/assets/hummingbird CC BY-SA 4.0.jpg
diff --git a/docs/assets/img_sample_for_kimg.png b/docs/assets/img_sample_for_kimg.png
diff --git a/docs/common/DocsShow.vue b/docs/common/DocsShow.vue
@@ -29,13 +29,29 @@
         type: Boolean,
         required: false,
       },
+      /**
+       * Container width
+       */
+      width: {
+        type: String,
+        required: false,
+      },
+      /**
+       * Container max width
+       */
+      maxWidth: {
+        type: String,
+        required: false,
+      },
     },
     computed: {
       style() {
         return {
           display: this.block ? 'block' : 'inline-block',
           padding: this.padding ? '8px 24px' : null,
           backgroundColor: this.dark ? this.$themePalette.grey.v_500 : undefined,
+          width: this.width ? this.width : undefined,
+          maxWidth: this.maxWidth ? this.maxWidth : undefined,
         };
       },
     },

diff --git a/docs/pages/kimg.vue b/docs/pages/kimg.vue
@@ -2,6 +2,191 @@
 
   <DocsPageTemplate apiDocs>
     <DocsPageSection title="Overview" anchor="#overview">
+      <p>
+        The <code>KImg</code> component displays an image and provides additional functionality to manipulate it such as setting an aspect ratio, scaling, letterboxing, and more.
+      </p>
+
+      <DocsShowCode language="html">
+        <KImg
+          src="hummingbird.jpg"
+          altText="A sitting hummingbird"
+        />
+      </DocsShowCode>
+      <DocsShow>
+        <KImg
+          :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+          altText="A sitting hummingbird"
+        />
+      </DocsShow>
+    </DocsPageSection>
+
+    <DocsPageSection title="Examples" anchor="#examples">
+      TODO: Mention original image dimension
+
+      In the examples below, you can resize the screen to observe how responsive behavior is achieved.
+
+      <h3>Inline vs block</h3>
+
+      <h4>Inline</h4>
+      <DocsShowCode language="html">
+        <span>
+          <KImg
+            src="hummingbird.jpg"
+            altText="A sitting hummingbird"
+          />
+        </span>
+      </DocsShowCode>
+      <DocsShow>
+        <span>
+          <KImg
+            :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+            altText="A sitting hummingbird"
+          />
+        </span>
+      </DocsShow>
+
+
+      <h4>Block</h4>
+
+      <p>When rendered within a block element, by default the image scales to its parent element with the <code>'centerInside'</code> scale type (see below).</p>
+
+      <DocsShowCode language="html">
+        <div>
+          <KImg
+            src="hummingbird.jpg"
+            altText="A sitting hummingbird"
+          />
+        </div>
+      </DocsShowCode>
+      <DocsShow block>
+        <div>
+          <KImg
+            :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+            altText="A sitting hummingbird"
+          />
+        </div>
+      </DocsShow>
+
+      <h3>Units</h3>
+
+      <p>TODO</p>
+      <h3>Alternative text</h3>
+
+      <p>TODO</p>
+
+      <h3>Scaling</h3>
+      <p>TODO: Mention that width etc are set on container rather than the image itself</p>
+
+      <h4><code style="font-weight: bold">'centerInside'</code> scale type</h4>
+
+      <p>Scales the image uniformly and maintains its original aspect ratio so that both its width and height are equal to or less than the container. The image can be letterboxed. It's the safest mode as it never distorts the image.</p>
+
+      <DocsShowCode language="html">
+        <div>
+          <KImg
+            src="hummingbird.jpg"
+            altText="A sitting hummingbird"
+            height="200"
+            width="100%"
+            maxWidth="500"
+            scaleType="centerInside"
+          />
+        </div>
+      </DocsShowCode>
+      <DocsShow block>
+        <div>
+          <KImg
+            :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+            altText="A sitting hummingbird"
+            height="200"
+            width="100%"
+            maxWidth="500"
+            scaleType="centerInside"
+          />
+        </div>
+      </DocsShow>
+
+      <h4><code style="font-weight: bold">'contain'</code> scale type</h4>
+
+      <p>Behaves like <code>'centerInside'</code> except it ensures that at least one axis of the image fits the container exactly. The original aspect ratio is maintained. The image can be letterboxed. This mode may distort the image by enlarging it above its original size.</p>
+
+      <DocsShowCode language="html">
+        <div>
+          <KImg
+            src="hummingbird.jpg"
+            altText="A sitting hummingbird"
+            height="200"
+            width="100%"
+            maxWidth="500"
+            scaleType="contain"
+          />
+        </div>
+      </DocsShowCode>
+      <DocsShow block>
+        <div>
+          <KImg
+            :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+            altText="A sitting hummingbird"
+            height="200"
+            width="100%"
+            maxWidth="500"
+            scaleType="contain"
+          />
+        </div>
+      </DocsShow>
+
+      <h4><code style="font-weight: bold">'fitXY'</code> scale type</h4>
+
+      <p>Scales X and Y axis of the image independently, so that the image matches the container exactly. This mode may distort the image as its originalaspect ratio is ignored and the image won't be letterboxed. It could also distort the image by enlarging it above its original size.</p>
+
+      <DocsShowCode language="html">
+        <div>
+          <KImg
+            src="hummingbird.jpg"
+            altText="A sitting hummingbird"
+            height="200"
+            width="100%"
+            maxWidth="500"
+            scaleType="fitXY"
+          />
+        </div>
+      </DocsShowCode>
+      <DocsShow block>
+        <div>
+          <KImg
+            :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+            altText="A sitting hummingbird"
+            height="200"
+            width="100%"
+            maxWidth="500"
+            scaleType="fitXY"
+          />
+        </div>
+      </DocsShow>
+
+      <h2>With ratio</h2>
+
+      <DocsShowCode language="html">
+        <KImg
+          src="hummingbird.jpg"
+          altText="A sitting hummingbird"
+          aspectRatio="4:3"
+        />
+      </DocsShowCode>
+      <DocsShow block>
+        <KImg
+          :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+          altText="A sitting hummingbird"
+          aspectRatio="4:3"
+        />
+      </DocsShow>
+
+      <p>Note that ratio styles are based on the width information, therefore it needs to be available in some way. For example, it could be provided directly to <code>KImg</code>, or you could ensure that its parent element has width by setting it explicitly or by using a block element.</p>
+
+      <p>You may combine aspect ratio with any of the scale types.</p>
+
+      <!-- 
+
       <div>
         The <DocsLibraryLink component="KImg" /> component displays images based on an image source and optional image
         dimensions provided by the implementer.
@@ -77,8 +262,9 @@
           />
         </DocsShowCode>
 
-      </div>
+      </div> -->
     </DocsPageSection>
+
   </DocsPageTemplate>
 
 </template>
@@ -95,21 +281,23 @@
 
   .img-example-1 {
     display: flex;
+    flex-wrap: wrap;
     margin-top: 20px;
   }
 
-  .img-example-2 {
-    margin-top: 20px;
-    margin-bottom: 20px;
-  }
+  /* 
+    .img-example-2 {
+      margin-top: 20px;
+      margin-bottom: 20px;
+    }
 
-  .img-example-2 > div {
-    display: flex;
-  }
+    .img-example-2 > div {
+      display: flex;
+    }
 
-  .img-example-2 > div > div {
-    margin-top: 30px;
-  }
+    .img-example-2 > div > div {
+      margin-top: 30px;
+    } */
 
 </style>