@gitlab/ui 115.10.0 → 116.0.0

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

@@ -1,243 +0,0 @@
-## 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/truncate/truncate.md

@@ -1,14 +0,0 @@
-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_text/truncate_text.md

@@ -1,26 +0,0 @@
-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/directives/hover_load/hover_load.md

@@ -1,22 +0,0 @@
-A Vue Directive to help with preloading resources when hovering over an element.
-
-## Usage
-
-```html
-<script>
-import { GlHoverLoadDirective } from '@gitlab/ui';
-
-export default {
-  directives: { GlHoverLoadDirective },
-  methods: {
-    handlePreload() {
-      fetch('some/endpoint');
-    },
-  },
-};
-</script>
-
-<template>
-  <div v-gl-hover-load="handlePreload">Hover me to preload</div>
-</template>
-```

package/src/directives/outside/outside.md

@@ -1,140 +0,0 @@
-A Vue Directive to call a callback when a supported event type occurs *outside* of the element
-the directive is bound to. Any events on the element or any descendant elements are ignored.
-The directive supports the event types `click` and `focusin` and can be configured in several ways.
-If no event type is set, `click` is the default.
-
-## Usage
-
-### Default
-
-The following example listens for click events outside the specified element:
-
-```html
-<script>
-import { GlOutsideDirective as Outside } from '@gitlab/ui';
-
-export default {
-  directives: { Outside },
-  methods: {
-    onClick(event) {
-      console.log('User clicked somewhere outside of this component', event);
-    },
-  },
-};
-</script>
-
-<template>
-  <div v-outside="onClick">Click anywhere but here</div>
-</template>
-```
-
-### When binding another event type than `click`
-
-You can specify event types as modifiers. The following example listens for `focusin` events,
-but not for `click`. With this implementation:
-
-```html
-<script>
-export default {
-  methods: {
-    onFocusin(event) {
-      console.log('User set the focus somewhere outside of this component', event);
-    }
-  }
-};
-</script>
-
-<template>
-  <div v-outside.focusin="onFocusin">...</div>
-</template>
-```
-
-### When binding multiple event types
-
-You can specify multiple event types by providing multiple modifiers. The following example
-listens for `click` and `focusin` events:
-
-```html
-<script>
-export default {
-  methods: {
-    onEvent(event) {
-      console.log('Event occurred outside the element:', event);
-    }
-  }
-};
-</script>
-
-<template>
-  <div v-outside.click.focusin="onEvent">...</div>
-</template>
-```
-
-💡 The callback function receives the `event` as a parameter. You can use the `event.type`
-property to execute different code paths depending on which event triggered the callback.
-
-### When handler expects arguments
-
-In case a click handler expects an arument to be passed, simple `v-outside="onClick('foo')"` will
-invoke the handler instantly when mounting the component and the directive won't be active. The
-simplest solution to pass the arguments to the directive is to wrap the handler into an anonumous
-function.
-
-```html
-<script>
-import { GlOutsideDirective as Outside } from '@gitlab/ui';
-
-export default {
-  directives: { Outside },
-  methods: {
-    onClick(event, foo) {
-      console.log('Event occurred outside the element:', event);
-      console.log('An argument was passed along:', foo);
-    },
-  },
-};
-</script>
-
-<template>
-  <div v-outside="(event) => onClick(event, 'foo')">Click anywhere but here</div>
-</template>
-```
-
-## Caveats
-
-* Clicks cannot be detected across document boundaries (e.g., across an
-  `iframe` boundary), in either direction.
-* Clicks on focusable elements, such as buttons or input fields, will fire both
-  `click` and `focusin` events. When both event types are registered,
-  the callback will be executed twice. To prevent executing the same code twice
-  after only one user interaction, use a flag in the callback to stop its
-  execution. Example:
-
-  ```html
-    <script>
-    export default {
-      data: () => ({
-        isOpen: false,
-      }),
-      methods: {
-        openDropdown() {
-          this.isOpen = true;
-        },
-        closeDropdown() {
-          if(!this.isOpen) {
-            return
-          }
-
-          // more code
-
-          this.isOpen = false;
-        }
-      }
-    };
-    </script>
-
-    <template>
-      <button type="button" @click="openDropdown">Open</button>
-      <div v-outside.click.focusin="closeDropdown">...</div>
-    </template>
-  ```

package/src/directives/resize_observer/resize_observer.md

@@ -1,54 +0,0 @@
-This directive can be used to get notified whenever a given element's size (width or height) changes
-and to retrieve the updated dimensions.
-
-Under the hood, it leverages the [Resize Observer API](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
-If you use GitLab UI in an older browser which doesn't support the Resize Observer API,
-you can use a [polyfill](https://github.com/que-etc/resize-observer-polyfill).
-
-The directive accepts a callback as a value and passes on the received
-[contentRect](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry/contentRect)
-and the target element whenever a resize event gets triggered.
-
-```html
-<script>
-export default {
-  data() {
-    return {
-      width: 0,
-      height: 0,
-    };
-  },
-  methods: {
-    handleResize({ contentRect: { width, height } }) {
-      this.width = width;
-      this.height = height;
-    },
-  },
-};
-</script>
-<template>
-  <div v-gl-resize-observer-directive="handleResize">
-    <p>{{ width }} x {{ height }}</p>
-  </div>
-</template>
-```
-
-The observer can be toggled on or off by passing a boolean argument to the directive:
-
-```html
-<script>
-export default {
-  data() {
-    return {
-      shouldObserve: true,
-    };
-  },
-  methods: {
-    handleResize() {},
-  },
-};
-</script>
-<template>
-  <div v-gl-resize-observer-directive[shouldObserve]="handleResize"></div>
-</template>
-```

package/src/directives/safe_html/safe_html.md

@@ -1,58 +0,0 @@
-A Vue Directive to sanitize HTML to avoid any XSS vulnerabilities.
-
-## Usage
-
-This directive can be used to sanitize HTML code which may contain user input, to prevent cross-site
-scripting (XSS) vulnerabilities.
-
-Under the hood, it uses [DOMPurify](https://github.com/cure53/DOMPurify) to sanitize the provided HTML.
-
-DOMPurify will strip out dangerous HTML and will keep the safe HTML. You can refer complete list of
-[tags][1] and [attributes][2] allowed by DOMPurify.
-
-[1]: https://github.com/cure53/DOMPurify/blob/main/src/tags.js
-[2]: https://github.com/cure53/DOMPurify/blob/main/src/attrs.js
-
-## Example
-
-```html
-<script>
-import { GlSafeHtmlDirective as SafeHtml } from '@gitlab/ui';
-
-export default {
-  directives: {
-    SafeHtml,
-  },
-  data() {
-    return {
-      rawHtml: "Hello! <script>alert('XSS')</script>",
-    };
-  },
-};
-</script>
-
-<template>
-  <div v-safe-html="rawHtml"></div>
-</template>
-```
-
-## Advanced configuration
-
-```js
-// It allows only <b> tags
-const config = { ALLOWED_TAGS: ['b'] };
-
-// It doesn't allow any html tags
-const config = { ALLOWED_TAGS: [] };
-```
-
-```html
-<div v-safe-html:[config]="rawHtml"></div>
-```
-
-For advanced configuration options, please refer to [DOMPurify's documentation](https://github.com/cure53/DOMPurify#can-i-configure-dompurify).
-
-### Notes
-
-1. `target` attribute is not allowed by default - See <https://gitlab.com/gitlab-org/gitlab-ui/-/issues/1427>.
-1. To know more about other tips & caveats - See <https://gitlab.com/groups/gitlab-org/-/epics/4273#caveats>.

package/src/directives/safe_link/safe_link.md

@@ -1,37 +0,0 @@
-A Vue directive to make the hyperlinks secure by default.
-
-## Security measures
-
-### rel
-
-When setting target to `_blank`, the rel attribute gets set automatically to `noopener noreferrer`,
-this is done to avoid the `window.opener` [API exploit]. If you set the `rel` attribute manually,
-this will overwrite the aforementioned logic.
-
-### href
-
-This directive enforces "safe" URLs. What this means is that, if the provided `href`
-doesn't point to a safe protocol (one of `http:`, `https:`, `mailto:` or `ftp:`), then it is
-replaced with `about:blank` to prevent [URL injections].
-
-```html
-<script>
-import { GlSafeLinkDirective as SafeLink } from '@gitlab/ui';
-
-export default {
-  data() {
-    return {
-      url: 'javascript:alert(1)',
-    };
-  },
-  directives: { SafeLink },
-};
-</script>
-<template>
-  <a v-safe-link href="url" target="_blank">Click</a>
-  <!-- Renders to: <a href="about:blank" target="_blank">Click</a> -->
-</template>
-```
-
-[API exploit]: https://www.jitbit.com/alexblog/256-targetblank---the-most-underestimated-vulnerability-ever/
-[URL injections]: https://vuejs.org/v2/guide/security.html#Injecting-URLs

package/src/internal/color_contrast/color_contrast.md

@@ -1,8 +0,0 @@
-## Usage
-
-`GlColorContrast` is an **internal** component to display color contrast
-scores and levels for design token stories.
-
-`GlColorContrast` accepts `foreground` and `background` color props to
-calculate a contrast score (e.g. `4.5`) and level (e.g. `AA`) consistent
-with [WCAG 2.1 1.4.3: Contrast (Minimum) level](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html).

package/src/internal/color_contrast/color_contrast.vue

@@ -1,52 +0,0 @@
-<script>
-import { HEX_REGEX } from '../../utils/constants';
-import { getColorContrast } from '../../utils/utils';
-
-export default {
-  name: 'GlColorContrast',
-  props: {
-    foreground: {
-      type: String,
-      required: true,
-      validator: (value) => HEX_REGEX.test(value),
-    },
-    background: {
-      type: String,
-      required: true,
-      validator: (value) => HEX_REGEX.test(value),
-    },
-  },
-  computed: {
-    isValidColorCombination() {
-      return HEX_REGEX.test(this.foreground) && HEX_REGEX.test(this.background);
-    },
-    classes() {
-      if (!this.isValidColorCombination) return 'gl-text-neutral-950';
-      const { grade } = this.contrast.level;
-      const isFail = grade === 'F';
-      const contrastScore = getColorContrast('#fff', this.background).score > 4.5;
-      const textClass = contrastScore ? 'gl-text-neutral-0' : 'gl-text-neutral-950';
-      const failClasses = contrastScore
-        ? 'gl-shadow-inner-1-red-300 gl-text-red-300'
-        : 'gl-shadow-inner-1-red-500 gl-text-red-500';
-      return [isFail ? failClasses : textClass];
-    },
-    contrast() {
-      return getColorContrast(this.foreground, this.background);
-    },
-  },
-};
-</script>
-
-<template>
-  <code
-    class="gl-w-10 gl-rounded-base gl-p-2 gl-text-center gl-text-xs"
-    :class="classes"
-    :style="{ backgroundColor: background }"
-  >
-    <template v-if="isValidColorCombination">
-      {{ contrast.level.grade }} {{ contrast.score }}
-    </template>
-    <template v-else>???</template>
-  </code>
-</template>