@carbon/vue 2.45.1 → 3.0.5-alpha.0

package/src/components/CvContentSwitcher/CvContentSwitcher.stories.mdx

@@ -0,0 +1,196 @@
+import { Canvas, Meta, Story } from '@storybook/addon-docs';
+import { CvContentSwitcher } from '.';
+import CvContentSwitcherButton from './CvContentSwitcherButton.vue';
+import CvContentSwitcherContent from './CvContentSwitcherContent.vue';
+import { IbmSecurity20 } from '@carbon/icons-vue';
+import { action } from '@storybook/addon-actions';
+import { sbCompPrefix, storyParametersObject } from '../../global/storybook-utils';
+
+<Meta title={`${sbCompPrefix}/CvContentSwitcher`} component={CvContentSwitcher} />
+
+export const Template = args => ({
+  // Components used in your story `template` are defined in the `components` object
+  components: {
+    CvContentSwitcher,
+    CvContentSwitcherButton,
+    CvContentSwitcherContent,
+  },
+  // The story's `args` need to be mapped into the template through the `setup()` method
+  setup() {
+    return {
+      args: { ...args.data },
+      iconSample: IbmSecurity20,
+      selectedIndex: args.selectedIndex,
+      onSelected: action('selected'),
+    };
+  },
+  // And then the `args` are bound to your component with `v-bind="args"`
+  template: args.template,
+});
+const defaultTemplate = `
+<div>
+  <cv-content-switcher aria-label='Choose content' v-bind='args' @selected="onSelected">
+    <cv-content-switcher-button owner-id="csb-1" :selected="selectedIndex === 0">Button Name 1</cv-content-switcher-button>
+    <cv-content-switcher-button owner-id="csb-2" :selected="selectedIndex === 1">Button Name 2</cv-content-switcher-button>
+    <cv-content-switcher-button :icon="iconSample" owner-id="csb-3" :selected="selectedIndex === 2">Button Name 3</cv-content-switcher-button>
+  </cv-content-switcher>
+  <section style="margin: 10px 0;">
+    <cv-content-switcher-content owner-id="csb-1">
+      <p>This is the content for option 1</p>
+    </cv-content-switcher-content>
+    <cv-content-switcher-content owner-id="csb-2">
+      <p>This is the content for option 2</p>
+    </cv-content-switcher-content>
+    <cv-content-switcher-content owner-id="csb-2" >
+      <p>This is more content for option 2</p>
+    </cv-content-switcher-content>
+    <cv-content-switcher-content owner-id="csb-3">
+      <p>This is the content for option 3</p>
+  </cv-content-switcher-content>
+  </section>
+</div>
+`;
+const defaultCode = defaultTemplate.replace("v-bind='args'", '');
+const domTemplate = `
+<div>
+  <cv-content-switcher aria-label='Choose content' v-bind='args' @selected="onSelected">
+    <cv-content-switcher-button content-selector=".content-1" :selected="selectedIndex === 0">Button Name 1</cv-content-switcher-button>
+    <cv-content-switcher-button content-selector=".content-2" :selected="selectedIndex === 1">Button Name 2</cv-content-switcher-button>
+    <cv-content-switcher-button :icon="iconSample" content-selector=".content-3" :selected="selectedIndex === 2">Button Name 3</cv-content-switcher-button>
+  </cv-content-switcher>
+  <section style="margin: 10px 0;">
+    <div class="content-1">
+      <p>This is the DOM content for option 1</p>
+    </div>
+    <div class="content-2">
+      <p>This is the DOM content for option 2</p>
+    </div>
+    <div class="content-2" >
+      <p>This is more DOM content for option 2</p>
+    </div>
+    <div class="content-3">
+      <p>This is the DOM content for option 3</p>
+    </div>
+  </section>
+</div>
+`;
+const domCode = domTemplate.replace("v-bind='args'", '');
+const multipleTemplate = `
+<div>
+  <cv-content-switcher aria-label='Choose content' v-bind='args' @selected="onSelected" id="star-wars">
+    <cv-content-switcher-button parent-switcher="star-wars" owner-id="episode-1" :selected="selectedIndex === 0">Episode 1</cv-content-switcher-button>
+    <cv-content-switcher-button parent-switcher="star-wars" owner-id="episode-2" :selected="selectedIndex === 1">Episode 2</cv-content-switcher-button>
+    <cv-content-switcher-button parent-switcher="star-wars" :icon="iconSample" owner-id="episode-3" :selected="selectedIndex === 2">Episode 3</cv-content-switcher-button>
+  </cv-content-switcher>
+  <section style="margin: 10px 0;">
+    <cv-content-switcher-content parent-switcher="star-wars" owner-id="episode-1">
+      <p>Padme</p>
+    </cv-content-switcher-content>
+    <cv-content-switcher-content parent-switcher="star-wars" owner-id="episode-2">
+      <p>Anakin</p>
+    </cv-content-switcher-content>
+    <cv-content-switcher-content parent-switcher="star-wars" owner-id="episode-2" >
+      <p>Zam</p>
+    </cv-content-switcher-content>
+    <cv-content-switcher-content parent-switcher="star-wars" owner-id="episode-3">
+      <p>Yoda</p>
+    </cv-content-switcher-content>
+  </section>
+  <cv-content-switcher aria-label='Choose content' v-bind='args' @selected="onSelected" id="LotR">
+    <cv-content-switcher-button parent-switcher="LotR" owner-id="book-1" :selected="selectedIndex === 0">Book 1</cv-content-switcher-button>
+    <cv-content-switcher-button parent-switcher="LotR" owner-id="book-2" :selected="selectedIndex === 1">Book 2</cv-content-switcher-button>
+    <cv-content-switcher-button parent-switcher="LotR" :icon="iconSample" owner-id="book-3" :selected="selectedIndex === 2">Book 3</cv-content-switcher-button>
+  </cv-content-switcher>
+  <section style="margin: 10px 0;">
+    <cv-content-switcher-content parent-switcher="LotR" owner-id="book-1">
+      <p>Bilbo</p>
+    </cv-content-switcher-content>
+    <cv-content-switcher-content parent-switcher="LotR" owner-id="book-2">
+      <p>Frodo</p>
+    </cv-content-switcher-content>
+    <cv-content-switcher-content parent-switcher="LotR" owner-id="book-2" >
+      <p>Sauron</p>
+    </cv-content-switcher-content>
+    <cv-content-switcher-content parent-switcher="LotR" owner-id="book-3">
+      <p>Gandalf</p>
+    </cv-content-switcher-content>
+  </section>
+</div>
+`;
+const multipleCode = multipleTemplate.replace("v-bind='args'", '');
+
+# CvContentSwitcher
+
+**Migration notes:**
+
+- The `light` and '`theme` options continue to be supported but neither seem to have any effect with Carbon 10.
+  The React component does not have these properties listed at all. Even so the `--content-switcher--light` is still
+  applied if `light` is set to true.
+- In the Vue 2 component `cv-content-switcher-content` is set to visible if the controlling `cv-content-switcher` is
+  removed from the DOM. This is no longer supported. If you need this behaviour you can probably achieve the same effect
+  with the direct DOM version of the component plus some visibility logic.
+
+<Canvas>
+  <Story
+    name="Default"
+    parameters={{
+      controls: { exclude: ['default', 'selected', 'template', 'data'] },
+      docs: { source: { code: defaultCode } },
+    }}
+    args={{
+      data: {
+        light: true
+      },
+      selectedIndex: 0,
+      template: defaultTemplate,
+    }}
+  >
+    {Template.bind({})}
+  </Story>
+</Canvas>
+
+Manipulate DOM elements directly. For this mode define `content-selector`. The selector will be passed to
+`document.querySelectorAll()` to find and show or hide elements by setting or removing the `hidden` attribute.
+
+<Canvas>
+  <Story
+    name="Direct DOM"
+    parameters={{
+      controls: { exclude: ['default', 'selected', 'template', 'data'] },
+      docs: { source: { code: domCode } },
+    }}
+    args={{
+      data: {
+        light: true,
+      },
+      selectedIndex: 0,
+      template: domTemplate,
+    }}
+  >
+    {Template.bind({})}
+  </Story>
+</Canvas>
+
+Does it seem like a good idea to have multiple content switchers on the page? Who am I to judge.
+
+If you want to do this you need to define an `id` for the `cv-content-switcher` and share that with the
+`cv-content-switcher-button` and `cv-content-switcher-content` components via the `parent-switcher` property.
+
+<Canvas>
+  <Story
+    name="Multiple Switchers"
+    parameters={{
+      controls: { exclude: ['default', 'selected', 'template', 'data'] },
+      docs: { source: { code: multipleCode } },
+    }}
+    args={{
+      data: {
+        light: true,
+      },
+      selectedIndex: 0,
+      template: multipleTemplate,
+    }}
+  >
+    {Template.bind({})}
+  </Story>
+</Canvas>

package/src/components/CvContentSwitcher/CvContentSwitcher.vue

@@ -0,0 +1,64 @@
+<template>
+  <div
+    :class="[
+      `cv-content-switcher ${carbonPrefix}--content-switcher`,
+      {
+        [`${carbonPrefix}--content-switcher--light`]: isLight,
+        [`${carbonPrefix}--content-switcher--${size || 'md'}`]: size || 'md',
+      },
+    ]"
+    role="tablist"
+    :id="cvId"
+  >
+    <slot></slot>
+  </div>
+</template>
+
+<script setup>
+import { carbonPrefix } from '../../global/settings';
+import { props as propsCvId, useCvId } from '../../use/cvId';
+import { useIsLight, props as propsTheme } from '../../use/cvTheme';
+import { onUnmounted, watch } from 'vue';
+import store from './cvContentSwitcherStore';
+
+const emit = defineEmits(['selected']);
+
+const props = defineProps({
+  size: {
+    type: String,
+    default: undefined,
+    validator: val => ['', 'md', 'sm', 'xl'].includes(val),
+  },
+  ...propsTheme,
+  ...propsCvId,
+});
+const cvId = useCvId(props, true);
+const isLight = useIsLight(props);
+store.addParent(cvId.value);
+store.setContentSelected('global', undefined);
+onUnmounted(() => {
+  store.removeParent(cvId.value);
+});
+watch(
+  () => store.state.global.latest,
+  (val, prev) => {
+    // if previous is not set, do not emit. This mimics the current v2 behaviour where the initial content does not generate an event
+    if (prev) emit('selected', val);
+  }
+);
+
+let ourLatest = undefined;
+watch(
+  () => store.state[cvId.value],
+  val => {
+    if (ourLatest !== val?.latest) {
+      // if ourLatest is not set, do not emit. This mimics the current v2 behaviour where the initial content does not generate an event
+      if (ourLatest) emit('selected', val?.latest);
+      ourLatest = val?.latest;
+    }
+  },
+  { deep: true }
+);
+</script>
+
+<style lang="scss"></style>

package/src/components/CvContentSwitcher/CvContentSwitcherButton.vue

@@ -0,0 +1,117 @@
+<!--
+  Carbon content switcher button.
+
+  Attributes:
+    content-selector: A CSS selector for the content to be shown when the button is selected.
+    selected: If true the button is initially selected (only valid on one button per content switcher).
+
+  Usage:
+    See content-switcher.vue
+
+-->
+<template>
+  <button
+    type="button"
+    role="tab"
+    class="cv-content-switcher-button"
+    :class="[
+      `${carbonPrefix}--content-switcher-btn`,
+      {
+        [`${carbonPrefix}--content-switcher--selected`]: isSelected,
+      },
+    ]"
+    :data-target="contentSelector"
+    :aria-selected="isSelected ? 'true' : 'false'"
+    :id="cvId"
+    @click="open"
+  >
+    <CvSvg
+      v-if="icon"
+      :svg="icon"
+      :class="`${carbonPrefix}--content-switcher__icon`"
+      height="16"
+      width="16"
+    />
+    <span :class="`${carbonPrefix}--content-switcher__label`">
+      <slot></slot>
+    </span>
+  </button>
+</template>
+
+<script setup>
+import { carbonPrefix } from '../../global/settings';
+import CvSvg from '../CvSvg/_CvSvg.vue';
+import { computed, onMounted, watch } from 'vue';
+import { props as propsCvId, useCvId } from '../../use/cvId';
+import store from './cvContentSwitcherStore';
+
+const props = defineProps({
+  contentSelector: { type: String, default: undefined },
+  icon: {
+    type: [String, Object],
+    default: undefined,
+    validator(val) {
+      if (!val || typeof val === 'string') {
+        return true;
+      }
+      return val.render !== null;
+    },
+  },
+  ownerId: { type: String, default: undefined },
+  parentSwitcher: { type: String, default: 'global' },
+  selected: Boolean,
+  ...propsCvId,
+});
+const cvId = useCvId(props, true);
+
+function toggleContent(on) {
+  if (!props.contentSelector) {
+    console.error(
+      'CvContentSwitcherButton: Either ownerId or content-selector property must not be defined.'
+    );
+    return;
+  }
+
+  // show/hide content
+  const content = document.querySelectorAll(props.contentSelector);
+  for (const element of content) {
+    // element.style.visibility = on;
+    if (!on) {
+      element.setAttribute('hidden', 'hidden');
+    } else {
+      element.removeAttribute('hidden');
+    }
+    element.setAttribute('aria-hidden', `${!on}`);
+  }
+  if (on) store.setContentSelected(props.parentSwitcher, props.contentSelector);
+}
+
+function open() {
+  store.setSelected(props.parentSwitcher, cvId.value);
+  if (props.ownerId) store.setOwnerContent(props.parentSwitcher, props.ownerId);
+  else toggleContent(true);
+}
+function close() {
+  if (!props.ownerId) toggleContent(false);
+}
+const isSelected = computed(() => {
+  return store.getSelected(props.parentSwitcher, cvId.value);
+});
+watch(isSelected, val => {
+  if (val) open();
+  else close();
+});
+
+// life cycle
+onMounted(() => {
+  if (props.contentSelector === '' && props.ownerId === '') {
+    console.error(
+      'CvContentSwitcherButton: ownerId or content-selector properties must not be empty strings.'
+    );
+  }
+  if (props.selected) open();
+  else close();
+});
+</script>
+
+<style lang="scss"></style>

package/src/components/CvContentSwitcher/CvContentSwitcherContent.vue

@@ -0,0 +1,21 @@
+<template>
+  <div v-show="isVisible" class="cv-content-switcher-content">
+    <slot></slot>
+  </div>
+</template>
+
+<script setup>
+import { computed } from 'vue';
+import store from './cvContentSwitcherStore';
+
+const props = defineProps({
+  ownerId: { type: String, required: true },
+  parentSwitcher: { type: String, default: 'global' },
+});
+
+const isVisible = computed(() => {
+  return store.isOwnerContent(props.parentSwitcher, props.ownerId);
+});
+</script>
+
+<style lang="scss"></style>

package/src/components/CvContentSwitcher/cvContentSwitcherStore.js

@@ -0,0 +1,30 @@
+import { reactive } from 'vue';
+export default reactive({
+  state: { global: { latest: undefined, selected: '', owner: '' } },
+  addParent(parentId) {
+    this.state[parentId] = { latest: undefined, selected: '', owner: '' };
+  },
+  setSelected(parentId, childId) {
+    this.getParent(parentId).selected = childId;
+  },
+  getSelected(parentId, childId) {
+    return this.getParent(parentId).selected === childId;
+  },
+  removeParent(parentId) {
+    delete this.state[parentId];
+  },
+  getParent(parentId) {
+    if (!this.state[parentId]) this.addParent(parentId);
+    return this.state[parentId];
+  },
+  setContentSelected(parentId, selected) {
+    this.getParent(parentId).latest = selected;
+  },
+  setOwnerContent(parentId, ownerId) {
+    this.getParent(parentId).owner = ownerId;
+    this.setContentSelected(parentId, ownerId);
+  },
+  isOwnerContent(parentId, ownerId) {
+    return this.getParent(parentId).owner === ownerId;
+  },
+});

package/src/components/CvContentSwitcher/index.js

@@ -0,0 +1,3 @@
+import CvContentSwitcher from './CvContentSwitcher.vue';
+export { CvContentSwitcher };
+export default CvContentSwitcher;

package/src/components/CvCopyButton/CvCopyButton.stories.js

@@ -0,0 +1,28 @@
+import CvCopyButton from '.';
+
+import { action } from '@storybook/addon-actions';
+import {
+  sbCompPrefix,
+  storyParametersObject,
+} from '../../global/storybook-utils';
+
+export default {
+  title: `${sbCompPrefix}/CvCopyButton`,
+  component: CvCopyButton,
+  argTypes: {},
+};
+
+const template = `<cv-copy-button v-bind="args" @copy="copy" />`;
+const Template = args => ({
+  components: { CvCopyButton },
+  setup: () => ({ args, copy: action('copy') }),
+  template,
+});
+
+export const Default = Template.bind({});
+Default.args = {};
+Default.parameters = storyParametersObject(
+  Default.parameters,
+  template,
+  Default.args
+);

package/src/components/CvCopyButton/CvCopyButton.vue

@@ -0,0 +1,45 @@
+<template>
+  <cvi-copy-button
+    :class="`${carbonPrefix}--copy-btn`"
+    :aria-label="iconDescription"
+    :title="iconDescription"
+    :feedback="feedback"
+    :feedback-timeout="feedbackTimeout"
+    @copy="$emit('copy')"
+  >
+    <copy16 :class="`${carbonPrefix}--snippet__icon`" />
+  </cvi-copy-button>
+</template>
+
+<script>
+import { Copy16 } from '@carbon/icons-vue';
+import { carbonPrefix } from '../../global/settings';
+import CviCopyButton from './_CviCopyButton.vue';
+
+export default {
+  name: 'CvCopyButton',
+  props: {
+    /** Text shown when button is clicked */
+    feedback: {
+      type: String,
+      default: 'Copied!',
+    },
+    /** How long the feedback text stays visible for */
+    feedbackTimeout: {
+      type: Number,
+      default: 2000,
+    },
+    /** A11y description for copy icon */
+    iconDescription: {
+      type: String,
+      default: 'Copy to clipboard',
+    },
+  },
+  emits: [
+    /** Emitted when user clicks on the button */
+    'copy',
+  ],
+  components: { CviCopyButton, Copy16 },
+  setup: () => ({ carbonPrefix }),
+};
+</script>

package/src/components/CvCopyButton/_CviCopyButton.vue

@@ -0,0 +1,71 @@
+<template>
+  <button
+    type="button"
+    :class="[
+      `${carbonPrefix}--copy`,
+      {
+        [`${carbonPrefix}--copy-btn--animating`]: isAnimating,
+        [`${carbonPrefix}--copy-btn--${activeAnimation}`]: isAnimating,
+      },
+    ]"
+    @click="handleClick"
+    @animationend="handleAnimationEnd"
+    aria-live="polite"
+    :aria-label="feedback"
+  >
+    <slot />
+    {{ feedback }}
+    <span
+      aria-hidden="true"
+      :class="[
+        `${carbonPrefix}--assistive-text`,
+        `${carbonPrefix}--copy-btn__feedback`,
+      ]"
+      >{{ feedback }}</span
+    >
+  </button>
+</template>
+
+<script>
+import { ref, computed } from 'vue';
+import { useDebounceFn } from '@vueuse/core';
+import { carbonPrefix } from '../../global/settings';
+
+export default {
+  props: {
+    feedback: { type: String, required: true },
+    feedbackTimeout: { type: Number, required: true },
+  },
+  emits: ['copy'],
+  setup(props, { emit }) {
+    const activeAnimation = ref('');
+    const isAnimating = computed(() => activeAnimation.value.length > 0);
+
+    const fadeOut = useDebounceFn(() => {
+      activeAnimation.value = 'fade-out';
+    }, props.feedbackTimeout);
+
+    const handleClick = () => {
+      emit('copy');
+      activeAnimation.value = 'fade-in';
+      fadeOut();
+    };
+
+    const handleAnimationEnd = event => {
+      if (event.animationName !== 'hide-feedback') {
+        return;
+      }
+
+      activeAnimation.value = '';
+    };
+
+    return {
+      carbonPrefix,
+      activeAnimation,
+      isAnimating,
+      handleClick,
+      handleAnimationEnd,
+    };
+  },
+};
+</script>

package/src/components/CvCopyButton/index.js

@@ -0,0 +1,3 @@
+import CvCopyButton from './CvCopyButton.vue';
+export { CvCopyButton };
+export default CvCopyButton;