Issue-450: Made KTextTruncator

CHANGELOG.md

@@ -7,8 +7,19 @@ Changelog is rather internal in nature. See release notes for the public overvie
 
 ## Version 2.0.0
 
+- [#464]
+  - **Description:** Add KTextTruncator
+  - **Products impact:** new API
+  - **Addresses:** https://github.com/learningequality/kolibri-design-system/issues/450
+  - **Components:** KTextTruncator
+  - **Breaking:** no
+  - **Impacts a11y:** no
+  - **Guidance:** -
+
+[#464]: https://github.com/learningequality/kolibri-design-system/pull/464
+
 - [#460]
-  - **Description:** Implement KLogo
+  - **Description:** Add KLogo
   - **Products impact:** new API
   - **Addresses:** https://github.com/learningequality/kolibri-design-system/issues/373
   - **Components:** KLogo

docs/pages/ktexttruncator.vue

@@ -0,0 +1,18 @@
+<template>
+
+  <DocsPageTemplate :apiDocs="true">
+
+    <DocsPageSection title="Overview" anchor="#overview">
+      <p>
+        Truncates the text to a certain number of lines and adds an ellipsis character "…".
+      </p>
+      <DocsShow>
+        <p>
+          <KTextTruncator text="This is a long text that will be truncated to two line. This is a long text that will be truncated to two line. This is a long text that will be truncated to two line. This is a long text that will be truncated to two line. This is a long text that will be truncated to two line." :maxLines="2" />
+        </p>
+      </DocsShow>
+    </DocsPageSection>
+
+  </DocsPageTemplate>
+
+</template>

docs/tableOfContents.js

@@ -392,6 +392,11 @@ export default [
         isCode: true,
         keywords: ['transition'],
       }),
+      new Page({
+        path: '/ktexttruncator',
+        title: 'KTextTruncator',
+        isCode: true,
+      }),
     ],
   }),
 ];

lib/KTextTruncator.vue

@@ -0,0 +1,149 @@
+<template>
+
+  <!--
+    Text is wrapped in two `spans`s to allow parent components adding
+    padding style directly on `<TextTruncatorCss>` component no matter
+    of what truncating technique is used. Otherwise adding padding directly
+    would break when using technique (B) since text that should be truncated
+    would show in padding area.
+
+    Attributes are inherited by the inner `span` to emulate the same behavior
+    like if only one element would wrap the text to allow attributes be applied
+    as close as possible to the text element.
+
+    Some width information need to be provided to `<span>s` to allow `text-overflow`
+    calculate properly when ellipsis should be added.
+  -->
+  <span :style="{ display: 'inline-block', maxWidth: '100%' }">
+    <span
+      v-bind="$attrs"
+      :style="{ display: 'inline-block', maxWidth: '100%' }"
+      :class="$computedClass(truncate)"
+    >
+      {{ text }}
+    </span>
+  </span>
+
+</template>
+
+
+<script>
+
+  /**
+   * Truncates text to a certain number of lines
+   * and adds an ellipsis character "…"
+   *
+   * Internet Explorer note:
+   * Depending on length of words of the text, there might
+   * be a gap between the last visible word and "…"
+   */
+  export default {
+    name: 'KTextTruncator',
+    inheritAttrs: false,
+    props: {
+      /**
+       * Text to be truncated
+       */
+      text: {
+        type: String,
+        required: true,
+      },
+      /**
+       * Maximum number of lines to be shown
+       */
+      maxLines: {
+        type: Number,
+        required: false,
+        default: 1,
+      },
+      /**
+       * Text line height in rem.
+       * Used only for Internet Explorer fallback.
+       */
+      lineHeightIE: {
+        type: Number,
+        required: false,
+        default: 1.4,
+      },
+    },
+    computed: {
+      truncate() {
+        const nuxtServerSideRendering = process && process.server;
+        if (nuxtServerSideRendering) {
+          return;
+        }
+
+        /*
+            (A)
+            For one line, use standard ellipsis text overflow
+            that works well for such scenario
+          */
+        if (this.maxLines === 1) {
+          return {
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+          };
+        }
+
+        // 54 is random number only to be able to define `supports` test condition
+        if ('CSS' in window && CSS.supports && CSS.supports('-webkit-line-clamp: 54')) {
+          /*
+              (B)
+              For multiple lines, use line clamp in browsers that support it
+              (https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-line-clamp)
+            */
+          return {
+            overflow: 'hidden',
+            display: '-webkit-box',
+            '-webkit-line-clamp': `${this.maxLines}`,
+            '-webkit-box-orient': 'vertical',
+            // needed to make line clamp work for very long word with no spaces
+            overflowWrap: 'break-word',
+          };
+        } else {
+          /*
+              (C)
+              Fallback for multiple lines in Internet Explorer and some older versions
+              of other browsers that don't support line clamp
+              (https://caniuse.com/mdn-css_properties_-webkit-line-clamp).
+              Calculate max height and add "..." in `::before` while covering it with
+              white rectangle defined in `::after` when text doesn't need to be truncated.
+              Adapted from https://hackingui.com/a-pure-css-solution-for-multiline-text-truncation/
+              and https://css-tricks.com/line-clampin/#the-hide-overflow-place-ellipsis-pure-css-way.
+            */
+          const ellipsisWidth = '1rem';
+          return {
+            overflow: 'hidden',
+            position: 'relative',
+            lineHeight: `${this.lineHeightIE}rem`,
+            maxHeight: `${this.maxLines * this.lineHeightIE}rem`,
+            // needed to make truncation work for very long word with no spaces
+            // `word-wrap` is a legacy name for `overflow-wrap` that needs to be used for IE
+            wordWrap: 'break-word',
+            // create space for "..."
+            paddingRight: ellipsisWidth,
+            marginRigth: `-${ellipsisWidth}`,
+            '::before': {
+              content: "'…'",
+              position: 'absolute',
+              right: 0,
+              bottom: 0,
+            },
+            // cover "..." with white rectangle when text
+            // doesn't need to be truncated
+            '::after': {
+              content: "''",
+              position: 'absolute',
+              right: 0,
+              width: ellipsisWidth,
+              height: '100%',
+              background: this.$themeTokens.surface,
+            },
+          };
+        }
+      },
+    },
+  };
+
+</script>

lib/KThemePlugin.js

@@ -31,6 +31,7 @@ import KTabsPanel from './tabs/KTabsPanel';
 import KTextbox from './KTextbox';
 import KTooltip from './KTooltip';
 import KTransition from './KTransition';
+import KTextTruncator from './KTextTruncator';
 import KLogo from './KLogo';
 
 import { themeTokens, themeBrand, themePalette, themeOutlineStyle } from './styles/theme';
@@ -123,4 +124,5 @@ export default function KThemePlugin(Vue) {
   Vue.component('KTextbox', KTextbox);
   Vue.component('KTooltip', KTooltip);
   Vue.component('KTransition', KTransition);
+  Vue.component('KTextTruncator', KTextTruncator);
 }