Skip to content

Commit

Permalink
[WIP] Add scaling logic
Browse files Browse the repository at this point in the history
  • Loading branch information
@MisRob
MisRob committed Nov 15, 2023
1 parent 9a61e60 commit 3933f84
Show file tree
Hide file tree
Showing 5 changed files with 424 additions and 37 deletions.
Binary file added docs/assets/hummingbird CC BY-SA 4.0.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/img_sample_for_kimg.png
View file
Binary file not shown.
16 changes: 16 additions & 0 deletions docs/common/DocsShow.vue
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,13 +29,29 @@
type: Boolean,
required: false,
},
/**
* Container width
*/
width: {

Check warning on line 35 in docs/common/DocsShow.vue

View workflow job for this annotation

GitHub Actions / lint 

Prop 'width' requires default value to be set
type: String,
required: false,
},
/**
* Container max width
*/
maxWidth: {

Check warning on line 42 in docs/common/DocsShow.vue

View workflow job for this annotation

GitHub Actions / lint 

Prop 'maxWidth' requires default value to be set
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,
};
},
},
Expand Down
232 changes: 221 additions & 11 deletions docs/pages/kimg.vue
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,213 @@

<DocsPageTemplate apiDocs>
<DocsPageSection title="Overview" anchor="#overview">
<p>
It displays an image and provides additional functionality to manipulate it such as setting dimensions, aspect ratio, scaling, letterboxing, and more.
</p>
</DocsPageSection>

<DocsPageSection title="Usage" anchor="#usage">
<p>Note that when setting dimensions of the image in any of the supported ways, the settings is applied to its container rather than the image itself. Depending on the scale type and other settings, the image may be letterboxed. If you need to apply dimensions directly to the image, you can use fitXY scale type. This, and other modes are illustrated in the examples below, where the original image dimensions is 200px wide and 114px heigh.</p>

<p>Unless you set fixed dimensions, <code>KImg</code> is responsive by default.</p>

<h3>Rendering within inline and block elements</h3>

<h4>Inline</h4>

<p>When rendered within an inline element, the image will preserve its original dimensions.</p>

<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>Dimensions</h3>

<p>You can set the most common dimensions right on the <code>KImg</code> via props like <code>width</code>, <code>maxHeight</code>, etc. See <a href="#props">Props</a> for a full list. Values may be either numbers or strings consisting of a numeral and valid units.The following units are supported: %, cm, em, ex, ch, in, lh, mm, px, rem, rlh, vh, vw. If you don't provide a unit, px will be used.</p>

<DocsShowCode language="html">
<div>
<KImg
src="hummingbird.jpg"
altText="A sitting hummingbird"
height="250.2px"
width="100%"
maxWidth="10vw"
:minWidth="25"
/>
</div>
</DocsShowCode>

<h3>Alternative text</h3>

<p>Alternative text (<code>altText</code>) is required by default. If an image <DocsExternalLink text="is decorative" href="https://www.w3.org/WAI/tutorials/images/decorative/" />, then set <code>isDecorative</code> to truthy value. Then, alternative text won't be required and the image will be hidden from assistive technologies.</p>

<DocsShowCode language="html">
<div>
<KImg
src="hummingbird.jpg"
isDecorative
/>
</div>
</DocsShowCode>

<h3>Scaling</h3>

<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.</p>

<p>The original aspect ratio is maintained. 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.</p>

<p>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.</p>

<p>This mode may distort the image as its original aspect 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>Aspect ratio</h2>

<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>

<DocsShowCode language="html">
<div>
<KImg
src="hummingbird.jpg"
altText="A sitting hummingbird"
aspectRatio="4:3"
/>
</div>
</DocsShowCode>
<DocsShow block>
<div>
<KImg
:src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
altText="A sitting hummingbird"
aspectRatio="4:3"
/>
</div>
</DocsShow>

<!--
<div>
The <DocsLibraryLink component="KImg" /> component displays images based on an image source and optional image
dimensions provided by the implementer.
Expand Down Expand Up @@ -77,8 +284,9 @@
/>
</DocsShowCode>
</div>
</div> -->
</DocsPageSection>

</DocsPageTemplate>

</template>
Expand All @@ -95,21 +303,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>

Expand Down
Loading

0 comments on commit 3933f84

Please sign in to comment.