@gitlab/duo-ui 0.1.0

package/src/components/utilities/sprintf/sprintf.md

@@ -0,0 +1,243 @@
+## Overview
+
+The `GlSprintf` component lets you do `sprintf`-style string interpolation with
+child components. Each placeholder in the translated string, provided via the
+`message` prop, becomes a slot that you can use to insert any components or
+markup in the rendered output.
+
+> NOTE: `gl-sprintf` does not translate the message for you; you must provide
+> it already translated. In the following examples, it is assumed that
+> a `gettext`-style `__` translation function is available in your Vue
+> templates.
+
+## Displaying messages with text between placeholders (e.g., links, buttons)
+
+Sentences should not be split up into different messages, otherwise they may
+not be translatable into certain languages. To help with this, `GlSprintf`
+interprets placeholders suffixed with `Start` and `End` to indicate the
+boundaries of a component to display within the message. Any text between
+them is passed, via the `content` scoped slot property, to the slot name common
+to the placeholders.
+
+For example, using `linkStart` and `linkEnd` placeholders in a message defines
+a `link` scoped slot:
+
+```html
+<div>
+  <gl-sprintf :message="__('Learn more about %{linkStart}zones%{linkEnd}')">
+    <template #link="{ content }">
+      <gl-link
+        href="https://cloud.google.com/compute/docs/regions-zones/regions-zones"
+        target="_blank"
+      >{{ content }}</gl-link>
+    </template>
+  </gl-sprintf>
+</div>
+```
+
+will render as:
+
+```html
+<div>
+  Learn more about
+  <a
+    href="https://cloud.google.com/compute/docs/regions-zones/regions-zones"
+    target="_blank"
+    rel="noopener noreferrer"
+  >zones</a>
+</div>
+```
+
+Note that _any_ arbitrary HTML tags or Vue component(s) can be used within
+a scoped slot, and that the content passed to it can be used in any way at all;
+for instance, as regular text, or in component attributes or slots.
+
+Here's a more complex example, which `<gl-sprintf>` lets you do in a breeze:
+
+```html
+<div>
+  <gl-sprintf :message="__('Written by %{authorStart}someone%{authorEnd}')">
+    <template #author="{ content }">
+      <my-vue-component v-gl-tooltip="content" @event="handleEvent(content)">
+        {{ content }}
+      </my-vue-component>
+      <p>
+          {{ content }}
+          <div>{{ content }}</div>
+      </p>
+    </template>
+  </gl-sprintf>
+</div>
+```
+
+This is not feasible in a JS-only solution, since arbitrary Vue components
+cannot easily be used. In addition, a JS-only solution is more likely to be
+prone to XSS attacks, as the Vue compiler isn't available to help protect
+against them.
+
+### Customizing start/end placeholders
+
+You can customize the start and end placeholders that `GlSprintf` looks for
+using the `placeholders` prop. For instance:
+
+```html
+<div>
+  <gl-sprintf
+    :message="__('Learn more about %{my_custom_start}zones%{my_custom_end}')"
+    :placeholders="{ link: ['my_custom_start', 'my_custom_end'] }"
+  >
+    <template #link="{ content }">
+      <gl-link
+        href="https://cloud.google.com/compute/docs/regions-zones/regions-zones"
+        target="_blank"
+      >{{ content }}</gl-link>
+    </template>
+  </gl-sprintf>
+</div>
+```
+
+This can be useful if you are migrating an existing string to `GlSprintf` that
+uses different placeholder naming conventions, and don't want invalidate
+existing translations.
+
+## Displaying components within a message
+
+Use slots to replace placeholders in the message with the slots' contents.
+There is a slot for every placeholder in the message. For example, the `author`
+slot name can be used when there is an `%{author}` placeholder in the message:
+
+```html
+<script>
+export default {
+  data() {
+    return {
+      authorName: 'Some author',
+    };
+  },
+};
+</script>
+
+<template>
+  <div>
+    <gl-sprintf :message="__('Written by %{author}')">
+      <template #author>
+        <span>{{ authorName }}</span>
+      </template>
+    </gl-sprintf>
+  </div>
+</template>
+```
+
+The example above renders to this HTML:
+
+```html
+<div>Written by <span>Some author</span></div>
+```
+
+## Usage caveats
+
+### White space
+
+`GlSprintf` does not handle white space in scoped slots specially; it is passed
+through and rendered just like regular text. This means that white space in the
+scoped slot templates *themselves*, including newlines and indentation, are
+passed through untouched (assuming the template compiler you're using doesn't
+trim text nodes at compile time; `vue-template-compiler` preserves white space
+by default, for instance).
+
+Most of the time you don't need to worry about this, since
+[browsers normalize white space][1] automatically, but here's an example, using
+punctuation, where you might want to be conscious of the white space in the
+template:
+
+```html
+<div>
+  <gl-sprintf :message="__('Foo %{boldStart}bar%{boldEnd}!')">
+    <template #bold="{ content }">
+      <b>
+        {{ content }}
+      </b>
+    </template>
+  </gl-sprintf>
+</div>
+```
+
+As written, the literal markup rendered would be:
+
+```html
+<div>  Foo <b>
+        bar
+      </b>!
+</div>
+```
+
+where the white space (including newlines) before and after `bar` is exactly
+the newlines and indentation in the source template. The browser will render
+this as:
+
+<div>  Foo <b>
+        bar
+      </b>!
+</div>
+
+Note the single space between `bar` and `!`. To avoid that, remove the
+white space in the template, or use `v-text`:
+
+```html
+<div>
+  <gl-sprintf :message="__('Foo %{boldStart}bar%{boldEnd}!')">
+    <template #bold="{ content }">
+      <b>{{ content }}</b>
+      <!-- OR -->
+      <b v-text="content" />
+    </template>
+  </gl-sprintf>
+</div>
+```
+
+### Miscellaneous
+
+While there are a lot of caveats here, you don't need to worry about reading
+them _unless_ you find `GlSprintf` isn't rendering what you'd expect.
+
+- Since `GlSprintf` typically renders multiple elements, it can't be used as
+  a component's root, it must be wrapped with at least one other root element,
+  otherwise Vue will throw a `Multiple root nodes returned from render
+  function` error.
+- If a slot for a given placeholder _isn't_ provided, the placeholder
+  will be rendered as-is, e.g., literally `Written by %{author}` if the
+  `author` slot _isn't_ provided, or literally `%{linkStart}foo%{linkEnd}` if
+  the `link` slot isn't provided.
+- Content between `Start` and `End` placeholders is effectively thrown away if
+  the scoped slot of the correct name doesn't consume the `content` property in
+  some way, though the slot's components should still be rendered.
+- If there's no placeholder in the message for a provided named slot, the
+  content of that slot is silently thrown away.
+- If only one of the `Start` or `End` placeholders is in the message, or they
+  are in the wrong order, they are treated as plain slots, i.e., it is assumed
+  there is no text to extract and pass to the scoped slot. This allows you to
+  use plain slots whose names end in `Start` or `End`, e.g., `backEnd`, or
+  `fromStart` in isolation, without their `Start`/`End` counterparts.
+- Text extraction between `Start` and `End` placeholders is only done one level
+  deep. This is intentional, so as to avoid building complex sprintf messages
+  that would better be implemented in components. As an example,
+  `${linkStart}test%{icon}%{linkEnd}`, if provided both the `link` and `icon`
+  slots, would pass `test%{icon}` as a literal string as content to the `link`
+  scoped slot.
+- For more examples and edge cases, please see the test suite for `GlSprintf`.
+- To be successfully used in `GlSprintf`, slot names should:
+  - start with a letter (`[A-Za-z]`)
+  - only contain alpha-numeric characters (`[A-Za-z0-9]`), underscore (`_`) and
+    dash (`-`),
+  - should not end with underscore (`_`) or dash (`-`) So for example:
+    `%{author}`, `%{author_name}`, `%{authorName}` or `%{author-name-100}` are
+    all valid placeholders.
+
+## Internet Explorer 11
+
+This component uses [`String.prototype.startsWith()`] and [`String.prototype.endsWith()`] under the
+hood. Make sure those methods are polyfilled if you plan on using the component on IE11.
+
+[1]: https://www.w3.org/TR/css-text-3/#white-space-phase-1
+[`String.prototype.startsWith()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith
+[`String.prototype.endsWith()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith

package/src/components/utilities/sprintf/sprintf.vue

@@ -0,0 +1,142 @@
+<!-- eslint-disable vue/multi-word-component-names -->
+<script>
+/* eslint-disable no-continue */
+import has from 'lodash/has';
+import isString from 'lodash/isString';
+
+const PREFIX = '%{';
+const SUFFIX = '}';
+const START_SUFFIX = 'Start';
+const END_SUFFIX = 'End';
+const PLACE_HOLDER_REGEX = new RegExp(`(${PREFIX}[a-z]+[\\w-]*[a-z0-9]+${SUFFIX})`, 'gi');
+
+function groupPlaceholdersByStartTag(placeholders = {}) {
+  return Object.entries(placeholders).reduce((acc, [slotName, [startTag, endTag]]) => {
+    acc[startTag] = { slotName, endTag };
+    return acc;
+  }, {});
+}
+
+function getPlaceholderDefinition(chunk, placeholdersByStartTag) {
+  const tagName = chunk.slice(PREFIX.length, -SUFFIX.length);
+
+  if (has(placeholdersByStartTag, tagName)) {
+    // Use provided custom placeholder definition
+    return {
+      ...placeholdersByStartTag[tagName],
+      tagName,
+    };
+  }
+
+  if (tagName.endsWith(START_SUFFIX)) {
+    // Tag conforms to default start/end tag naming convention
+    const slotName = tagName.slice(0, -START_SUFFIX.length);
+
+    return {
+      slotName,
+      endTag: `${slotName}${END_SUFFIX}`,
+      tagName,
+    };
+  }
+
+  return {
+    slotName: tagName,
+    endTag: undefined,
+    tagName,
+  };
+}
+
+export default {
+  name: 'GlSprintf',
+  functional: true,
+  props: {
+    /**
+     * A translated string with named placeholders, e.g., "Written by %{author}".
+     */
+    message: {
+      type: String,
+      required: true,
+    },
+    /**
+     * An object mapping slot names to custom start/end placeholders. Use this
+     * to avoid changing an existing message, and in turn invalidating existing
+     * translations, in the case it uses non-default placeholders.
+     */
+    placeholders: {
+      type: Object,
+      required: false,
+      default: undefined,
+      validator: (value) =>
+        Object.values(value).every(
+          // eslint-disable-next-line unicorn/no-array-callback-reference
+          (tagPair) => Array.isArray(tagPair) && tagPair.length === 2 && tagPair.every(isString)
+        ),
+    },
+  },
+  /**
+   * Available slots are determined by the placeholders in the provided
+   * message prop. For example, a message of "Written by %{author}" has
+   * a slot called "author", and its content is used to replace "%{author}"
+   * in the rendered output. When two placeholders indicate a start and an
+   * end region in the message, e.g., "%{linkStart}foo%{linkEnd}", the common
+   * base name can be used as a scoped slot, where the content between the
+   * placeholders is passed via the `content` scoped slot prop.
+   * @slot * (arbitrary)
+   * @binding {string} content The content to place between start and end placeholders.
+   */
+  render(createElement, context) {
+    // While a functional style is generally preferred, an imperative style is
+    // used here, as it lends itself better to the message parsing algorithm.
+    // This approach is also more performant, as it minimizes (relatively) object
+    // creation/garbage collection, which is important given how frequently this
+    // code may run on a given page.
+
+    let i = 0;
+    const vnodes = [];
+    const slots = context.scopedSlots;
+    const chunks = context.props.message.split(PLACE_HOLDER_REGEX);
+    const placeholdersByStartTag = groupPlaceholdersByStartTag(context.props.placeholders);
+
+    while (i < chunks.length) {
+      const chunk = chunks[i];
+      // Skip past this chunk now we have it
+      i += 1;
+
+      if (!PLACE_HOLDER_REGEX.test(chunk)) {
+        // Not a placeholder, so pass through as-is
+        vnodes.push(chunk);
+        continue;
+      }
+
+      const { slotName, endTag, tagName } = getPlaceholderDefinition(chunk, placeholdersByStartTag);
+
+      if (endTag) {
+        // Peek ahead to find end placeholder, if any
+        const indexOfEnd = chunks.indexOf(`${PREFIX}${endTag}${SUFFIX}`, i);
+        if (indexOfEnd > -1) {
+          // We have a valid start/end placeholder pair! Extract the content
+          // between them and skip past the end placeholder
+          const content = chunks.slice(i, indexOfEnd);
+          i = indexOfEnd + 1;
+
+          if (!has(slots, slotName)) {
+            // Slot hasn't been provided; return placeholders and content as-is
+            vnodes.push(chunk, ...content, chunks[indexOfEnd]);
+            continue;
+          }
+
+          // Provide content to provided scoped slot
+          vnodes.push(slots[slotName]({ content: content.join('') }));
+          continue;
+        }
+      }
+
+      // By process of elimination, chunk must be a plain placeholder
+      vnodes.push(has(slots, tagName) ? slots[tagName]() : chunk);
+      continue;
+    }
+
+    return vnodes;
+  },
+};
+</script>

package/src/components/utilities/truncate/constants.js

@@ -0,0 +1,5 @@
+export const POSITION = {
+  START: 'start',
+  MIDDLE: 'middle',
+  END: 'end',
+};

package/src/components/utilities/truncate/truncate.md

@@ -0,0 +1,14 @@
+The `GlTruncate` component lets you truncate the long texts with ellipsis.
+
+> **Tip:** Try resizing the side panel for truncation.
+
+## Usage
+
+```html
+<gl-truncate :text="text" :position="position" />
+```
+
+By default, the ellipsis position is at the `end`.
+
+Pro Tip: Truncating long filepaths from the `middle` / `start` can help preventing the important
+information in the end, i.e. filenames.

package/src/components/utilities/truncate/truncate.scss

@@ -0,0 +1,21 @@
+.gl-truncate-component {
+  display: inline-flex;
+  max-width: 100%;
+}
+
+.gl-truncate-start,
+.gl-truncate-end {
+  flex: 0 1 auto;
+  white-space: nowrap;
+  overflow: hidden;
+}
+
+.gl-truncate-start {
+  direction: rtl;
+  text-align: left;
+  text-overflow: '';
+}
+
+.gl-truncate-end {
+  text-overflow: ellipsis;
+}

package/src/components/utilities/truncate/truncate.vue

@@ -0,0 +1,109 @@
+<!-- eslint-disable vue/multi-word-component-names -->
+<script>
+import { GlTooltipDirective } from '../../../directives/tooltip';
+import { GlResizeObserverDirective } from '../../../directives/resize_observer/resize_observer';
+import { POSITION } from './constants';
+
+export default {
+  name: 'GlTruncate',
+  POSITION,
+  directives: {
+    GlTooltip: GlTooltipDirective,
+    GlResizeObserver: GlResizeObserverDirective,
+  },
+  props: {
+    /**
+     * Text to be ellipsized
+     */
+    text: {
+      type: String,
+      required: true,
+    },
+    /**
+     * Ellipsis position
+     */
+    position: {
+      type: String,
+      required: false,
+      default: POSITION.END,
+      validator: (value) => Object.values(POSITION).includes(value),
+    },
+    /**
+     * Display the full text in a tooltip only if it is being truncated
+     */
+    withTooltip: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+  },
+  data() {
+    return {
+      isTruncated: false,
+    };
+  },
+  computed: {
+    middleIndex() {
+      return Math.floor(this.text.length / 2);
+    },
+
+    first() {
+      return this.text.slice(0, this.middleIndex);
+    },
+    last() {
+      return this.text.slice(this.middleIndex);
+    },
+    isTooltipDisabled() {
+      return !this.withTooltip || !this.isTruncated;
+    },
+  },
+  watch: {
+    withTooltip(withTooltip) {
+      if (withTooltip) {
+        this.checkTruncationState();
+      }
+    },
+  },
+  methods: {
+    checkTruncationState() {
+      if (this.withTooltip) {
+        this.isTruncated = this.$refs.text.scrollWidth > this.$refs.text.offsetWidth;
+      }
+    },
+  },
+};
+</script>
+
+<template>
+  <span
+    v-if="position === $options.POSITION.START"
+    v-gl-tooltip="{ disabled: isTooltipDisabled }"
+    v-gl-resize-observer:[withTooltip]="checkTruncationState"
+    class="gl-truncate-component"
+    :title="text"
+  >
+    <span ref="text" class="gl-truncate-start !gl-text-ellipsis">&lrm;{{ text }}&lrm;</span>
+  </span>
+
+  <span
+    v-else-if="position === $options.POSITION.MIDDLE"
+    v-gl-tooltip="{ disabled: isTooltipDisabled }"
+    v-gl-resize-observer:[withTooltip]="checkTruncationState"
+    class="gl-truncate-component"
+    :title="text"
+  >
+    <span ref="text" class="gl-truncate-end">{{ first }}</span
+    ><span class="gl-truncate-start">&lrm;{{ last }}&lrm;</span>
+  </span>
+
+  <span
+    v-else
+    v-gl-tooltip="{ disabled: isTooltipDisabled }"
+    v-gl-resize-observer:[withTooltip]="checkTruncationState"
+    class="gl-truncate-component"
+    data-testid="truncate-end-container"
+    :title="text"
+  >
+    <span ref="text" class="gl-truncate-end">{{ text }}</span>
+  </span>
+</template>

package/src/components/utilities/truncate_text/constants.js

@@ -0,0 +1,5 @@
+export const STATES = {
+  INITIAL: 'initial',
+  TRUNCATED: 'truncated',
+  EXTENDED: 'extended',
+};

package/src/components/utilities/truncate_text/truncate_text.md

@@ -0,0 +1,26 @@
+The `GlTruncateText` component lets you truncate a large text by number of lines.
+The last line ends with an ellipsis if the text is truncated.
+Truncation can be toggled by a 'Show more' / 'Show less' button.
+The button will not be shown when no truncation is necessary.
+There is a separate property to set the number of lines initially shown on small screens.
+Use the `showMoreText` and `showLessText` properties to provide translated strings.
+
+> **Tip:** Try resizing the side panel to see the truncated number of lines change.
+
+## Usage
+
+```html
+<gl-truncate-text :show-more-text="__('Show more')" :show-less-text="__('Show less')" :lines="3" :mobile-lines="10">
+  {{ largeText }}
+</gl-truncate-text>
+```
+
+## Usage caveats
+
+When the size of the window is large,
+and the text is displayed on a number of lines greater than the value of the `lines` property,
+but smaller than the value of the `mobileLines` property,
+and the `Show more` button has been clicked to show the entire content of the text,
+and the window is resized to a small size,
+then instead of disappearing,
+the `Show less` button will remain visible and will do nothing when clicked.

package/src/components/utilities/truncate_text/truncate_text.scss

@@ -0,0 +1,14 @@
+/**
+  Note: although vendor-prefixes are used here, these properties are supported by all browsers.
+  See https://caniuse.com/css-line-clamp
+**/
+.gl-truncate-text {
+  // stylelint-disable-next-line value-no-vendor-prefix
+  display: -webkit-box;
+  -webkit-line-clamp: var(--mobile-lines);
+  -webkit-box-orient: vertical;
+
+  @include gl-media-breakpoint-up(sm) {
+    -webkit-line-clamp: var(--lines);
+  }
+}