@carbon/vue 3.0.31 → 3.0.32

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "framework": "vue",
   "name": "@carbon/vue",
-  "version": "3.0.30",
+  "version": "3.0.31",
   "contributions": {
     "html": {
       "description-markup": "markdown",
@@ -3503,6 +3503,14 @@
               },
               "default": "undefined"
             },
+            {
+              "name": "pageSize",
+              "value": {
+                "kind": "expression",
+                "type": "number"
+              },
+              "default": "undefined"
+            },
             {
               "name": "pageSizes",
               "value": {
@@ -3510,11 +3518,33 @@
                 "type": "array"
               },
               "default": "[10, 20, 30, 40, 50]"
+            },
+            {
+              "name": "rangeTextFormatter",
+              "value": {
+                "kind": "expression",
+                "type": "func"
+              },
+              "default": "undefined"
+            },
+            {
+              "name": "pageOfPagesFormatter",
+              "value": {
+                "kind": "expression",
+                "type": "func"
+              },
+              "default": "undefined"
             }
           ],
           "events": [
             {
               "name": "change"
+            },
+            {
+              "name": "update:page"
+            },
+            {
+              "name": "update:pageSize"
             }
           ],
           "slots": [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@carbon/vue",
   "license": "Apache-2.0",
-  "version": "3.0.31",
+  "version": "3.0.32",
   "description": "A collection of components for the Carbon Design System built using Vue.js",
   "packageManager": "yarn@3.2.0",
   "main": "dist/carbon-vue-3.umd.min.js",

package/src/components/CvDropdown/CvDropdown.vue

@@ -296,6 +296,7 @@ const emit = defineEmits(['update:modelValue', 'change']);
 watch(
   () => props.modelValue,
   () => {
+    if (props.modelValue === dataValue.value) return;
     dataValue.value = props.modelValue;
     dataCaption.value = undefined;
   }

package/src/components/CvModal/CvModal.vue

@@ -14,6 +14,7 @@
       tabindex="-1"
       v-bind="$attrs"
       @keydown.esc.prevent="onEsc"
+      @mousedown.self="onMouseDown"
       @click.self="onExternalClick"
     >
       <div
@@ -145,6 +146,8 @@ import {
   watch,
 } from 'vue';
 
+const mouseDownTarget = ref(null);
+
 const props = defineProps({
   /**
    * When set to true, the aria role will be either "alert" or "alertdialog"
@@ -269,6 +272,7 @@ function show() {
 
   el.value?.addEventListener('transitionend', onShown);
   dataVisible.value = true;
+  mouseDownTarget.value = null;
 }
 const content = ref(null);
 function onShown() {
@@ -326,6 +330,7 @@ function hide() {
   }
 
   dataVisible.value = false;
+  mouseDownTarget.value = null;
 }
 function afterHide(event) {
   if (event.propertyName === 'opacity') {
@@ -375,10 +380,13 @@ function focusAfterContent() {
 }
 
 function onExternalClick(ev) {
-  if (ev.target === el.value) {
+  if (ev.target === el.value && mouseDownTarget.value === el.value) {
     _maybeHide(ev, 'external-click');
   }
 }
+function onMouseDown(ev) {
+  mouseDownTarget.value = ev.target;
+}
 function onEsc(ev) {
   _maybeHide(ev, 'escape-press');
 }

package/src/components/CvPagination/CvPagination.stories.mdx

@@ -3,9 +3,29 @@ import { CvPagination } from '.';
 import { sbCompPrefix } from '../../global/storybook-utils';
 import { action } from '@storybook/addon-actions';
 import { ref } from 'vue';
-const myPage=ref(1);
-const myPageSizes=ref([5,7,10,11,13])
-const myNumItems=ref(13)
+const myPage = ref(1);
+const myPageSizes = ref([5, 7, 10, 11, 13]);
+const myNumItems = ref(13);
+const controlledPage = ref(1);
+const controlledPageSize = ref(10);
+const maxAllowedPage = ref(3);
+const onUpdatePageAction = action('update:page');
+const onUpdatePageSizeAction = action('update:page-size');
+function onUpdatePage(page) {
+  onUpdatePageAction(page);
+  // simulate a parent that constrains the page: requests past
+  // maxAllowedPage are declined by simply not assigning them back.
+  if (page <= maxAllowedPage.value) {
+    controlledPage.value = page;
+  }
+}
+function onUpdatePageSize(pageSize) {
+  onUpdatePageSizeAction(pageSize);
+  controlledPageSize.value = pageSize;
+}
+const spanishRangeTextFormatter = ({ start, end, items }) =>
+  `Del ${start} al ${end} de ${items}`;
+const germanPageOfPagesFormatter = ({ pages }) => `von ${pages} Seiten`;
 
 <Meta title={`${sbCompPrefix}/CvPagination`} component={CvPagination} />
 
@@ -21,6 +41,13 @@ export const Template = args => ({
       myPage,
       myPageSizes,
       myNumItems,
+      controlledPage,
+      controlledPageSize,
+      maxAllowedPage,
+      onUpdatePage,
+      onUpdatePageSize,
+      spanishRangeTextFormatter,
+      germanPageOfPagesFormatter,
       onChange: action('change'),
     };
   },
@@ -75,10 +102,42 @@ const slotsTemplate = `
   </template>
   </cv-pagination>
 `;
+const controlledTemplate = `
+  <cv-pagination
+    @change="onChange"
+    v-model:page="controlledPage"
+    v-model:page-size="controlledPageSize"
+    @update:page="onUpdatePage"
+    @update:page-size="onUpdatePageSize"
+    :number-of-items="103">
+  </cv-pagination>
+  <div style="margin-top:2rem; background-color: #888888; padding:1rem">
+    <h3>Parent-owned state</h3>
+    <p>page: {{controlledPage}}, page size: {{controlledPageSize}}</p>
+    <p>
+      Requests for a page beyond max-allowed-page are declined by this
+      story (the parent simply doesn't assign the requested page back) -
+      the displayed page stays put instead of drifting or getting stuck.
+    </p>
+    max allowed page:
+    <button @click="maxAllowedPage--">-</button>
+    {{maxAllowedPage}}
+    <button @click="maxAllowedPage++">+</button>
+  </div>
+`;
+const formattersTemplate = `
+  <cv-pagination
+    @change="onChange"
+    :number-of-items="103"
+    :range-text-formatter="spanishRangeTextFormatter"
+    :page-of-pages-formatter="germanPageOfPagesFormatter">
+  </cv-pagination>
+`;
 
 # CvPagination
 
 Migration notes:
+
 - If you specify `pageNumberLabel` a trailing colon (:) is no longer automatically appended to the text
 
 <Canvas>
@@ -111,14 +170,13 @@ Migration notes:
     argTypes={{
       page: { control: false },
       pageSizes: { control: false },
-      numberOfItems: { control: false }
+      numberOfItems: { control: false },
     }}
   >
     {Template.bind({})}
   </Story>
 </Canvas>
 
-
 Use slots to set the range text and "of n pages" text. A good use case for this is internationalization.
 
 <Canvas>
@@ -126,13 +184,7 @@ Use slots to set the range text and "of n pages" text. A good use case for this
     name="Slots"
     parameters={{
       controls: {
-        exclude: [
-          'default',
-          'template',
-          'data',
-          'change',
-          'of-n-pages',
-        ],
+        exclude: ['default', 'template', 'data', 'change', 'of-n-pages'],
       },
       docs: { source: { code: slotsTemplate } },
     }}
@@ -158,10 +210,71 @@ Use slots to set the range text and "of n pages" text. A good use case for this
       backwardsButtonDisabled: false,
       forwardsButtonDisabled: false,
       actualItemsOnPage: Infinity,
-      locale: 'en'
+      locale: 'en',
     }}
-    argTypes={{
+    argTypes={{}}
+  >
+    {Template.bind({})}
+  </Story>
+</Canvas>
+
+Bind `v-model:page` and/or `v-model:page-size` to opt in to controlled mode:
+the component no longer moves on its own, it emits `update:page` /
+`update:page-size` and only shows the new value once the parent assigns it
+back through the prop. This lets a parent veto a page change - useful when
+loading the next page's data can fail, or is gated behind other state.
+
+<Canvas>
+  <Story
+    name="Controlled"
+    parameters={{
+      controls: {
+        exclude: [
+          'default',
+          'template',
+          'data',
+          'range-text',
+          'change',
+          'of-n-pages',
+        ],
+      },
+      docs: { source: { code: controlledTemplate } },
+    }}
+    args={{
+      data: {},
+      template: controlledTemplate,
+    }}
+    argTypes={{}}
+  >
+    {Template.bind({})}
+  </Story>
+</Canvas>
+
+Use `rangeTextFormatter` and `pageOfPagesFormatter` to translate the range
+and page-count text without reimplementing the `range-text` / `of-n-pages`
+slots.
+
+<Canvas>
+  <Story
+    name="Formatters"
+    parameters={{
+      controls: {
+        exclude: [
+          'default',
+          'template',
+          'data',
+          'range-text',
+          'change',
+          'of-n-pages',
+        ],
+      },
+      docs: { source: { code: formattersTemplate } },
+    }}
+    args={{
+      data: {},
+      template: formattersTemplate,
     }}
+    argTypes={{}}
   >
     {Template.bind({})}
   </Story>

package/src/components/CvPagination/CvPagination.vue

@@ -84,13 +84,20 @@
 
 <script setup>
 import { carbonPrefix } from '../../global/settings';
-import { computed, nextTick, onMounted, ref, useAttrs, watch } from 'vue';
+import {
+  computed,
+  getCurrentInstance,
+  onMounted,
+  ref,
+  useAttrs,
+  watch,
+} from 'vue';
 import { CaretLeft16, CaretRight16 } from '@carbon/icons-vue';
 import CvSelect from '../CvSelect';
 import CvSelectOption from '../CvSelect/CvSelectOption.vue';
 import { useCvId } from '../../use/cvId';
 
-const emit = defineEmits(['change']);
+const emit = defineEmits(['change', 'update:page', 'update:pageSize']);
 
 const props = defineProps({
   backwardsButtonDisabled: { type: Boolean, default: false },
@@ -102,17 +109,38 @@ const props = defineProps({
   numberOfItems: { type: Number, default: Infinity },
   actualItemsOnPage: { type: Number, default: Infinity },
   page: { type: Number, default: undefined },
+  pageSize: { type: Number, default: undefined },
   pageSizes: { type: Array, default: () => [10, 20, 30, 40, 50] },
+  rangeTextFormatter: { type: Function, default: undefined },
+  pageOfPagesFormatter: { type: Function, default: undefined },
 });
 const attrs = useAttrs();
 const cvId = useCvId(attrs, true);
 
+// Read once at setup time: whether the parent bound a v-model listener for
+// this prop. vnode.props is a plain object Vue replaces on patch, not
+// something Vue's reactivity system tracks, so this can't be a computed()
+// that reacts to listeners being added/removed later - it only reflects
+// how the component was initially used.
+const instance = getCurrentInstance();
+const pageControlled = 'onUpdate:page' in (instance.vnode.props || {});
+const pageSizeControlled = 'onUpdate:pageSize' in (instance.vnode.props || {});
+
 const firstItem = ref(1);
-const pageValue = ref(1);
-const pageSizeValue = ref(10);
+const internalPage = ref(1);
+const internalPageSize = ref(10);
 const pageCount = ref(1);
 const pages = ref([1]);
 
+const pageValue = computed(() =>
+  pageControlled && props.page !== undefined ? props.page : internalPage.value
+);
+const pageSizeValue = computed(() =>
+  pageSizeControlled && props.pageSize !== undefined
+    ? props.pageSize
+    : internalPageSize.value
+);
+
 const noWayBack = computed(() => {
   return props.backwardsButtonDisabled || pageValue.value === 1;
 });
@@ -127,6 +155,9 @@ const ofNPagesProps = computed(() => {
 });
 const pageOfPages = computed(() => {
   const { pages, items } = ofNPagesProps.value;
+  if (props.pageOfPagesFormatter) {
+    return props.pageOfPagesFormatter({ pages, items, page: pageValue.value });
+  }
   if (items !== Infinity) {
     return `of ${pages} pages`;
   }
@@ -147,6 +178,9 @@ const rangeProps = computed(() => {
 const rangeText = computed(() => {
   const { start, end, items } = rangeProps.value;
 
+  if (props.rangeTextFormatter) {
+    return props.rangeTextFormatter({ start, end, items });
+  }
   if (items !== Infinity) {
     return `${start}-${end} of ${items} items`;
   } else {
@@ -162,16 +196,23 @@ const internalValue = computed(() => {
 });
 
 function adjustValues() {
-  pageSizeValue.value = newPageSizeValue(props.pageSizes);
+  if (!pageSizeControlled) {
+    internalPageSize.value = newPageSizeValue(props.pageSizes);
+  }
   pageCount.value = newPageCount(props.numberOfItems, pageSizeValue.value);
-  pageValue.value = newPageValue(props.page, pageCount.value);
+  if (!pageControlled) {
+    internalPage.value = newPageValue(props.page, pageCount.value);
+  }
   pages.value = newPagesArray(pageCount.value);
   firstItem.value = newFirstItem(pageValue.value, pageSizeValue.value);
 }
 onMounted(() => {
   adjustValues();
-  // always emit on mount
-  emit('change', internalValue.value);
+  // always emit on mount, unless both page and pageSize are fully
+  // controlled by the parent, in which case nothing here was derived.
+  if (!pageControlled || !pageSizeControlled) {
+    emit('change', internalValue.value);
+  }
 });
 watch(
   () => props.pageSizes,
@@ -186,40 +227,46 @@ watch(
   () => adjustValues()
 );
 
+function propose(nextPage, nextPageSize) {
+  if (!pageControlled) {
+    internalPage.value = nextPage;
+  }
+  if (!pageSizeControlled) {
+    internalPageSize.value = nextPageSize;
+  }
+  firstItem.value = newFirstItem(nextPage, nextPageSize);
+
+  if (pageControlled && nextPage !== pageValue.value) {
+    emit('update:page', nextPage);
+  }
+  if (pageSizeControlled && nextPageSize !== pageSizeValue.value) {
+    emit('update:pageSize', nextPageSize);
+  }
+  emit('change', {
+    start: firstItem.value,
+    page: nextPage,
+    length: nextPageSize,
+  });
+}
 function onPageChange(newVal) {
-  pageValue.value = parseInt(newVal, 10);
-  firstItem.value = newFirstItem(pageValue.value, pageSizeValue.value);
-  emit('change', internalValue.value);
+  propose(parseInt(newVal, 10), pageSizeValue.value);
 }
-watch(
-  () => props.numberOfItems,
-  () => onPageSizeChange(pageSizeValue.value)
-);
 function onPageSizeChange(newVal) {
-  pageSizeValue.value = parseInt(newVal, 10);
-  pageCount.value = newPageCount(props.numberOfItems, pageSizeValue.value);
-  pages.value = newPagesArray(pageCount.value);
-  // what page is firstItem on
-  nextTick(() => {
-    // setting pageValue immediately seems to cause a problem - test set pageSize to 40, page to 3, set pageSize to 10
-    // this previously resulted in 1 being set on Chrome (other browsers untested)
-    pageValue.value = Math.ceil(firstItem.value / pageSizeValue.value);
-    firstItem.value = newFirstItem(pageValue.value, pageSizeValue.value);
-    emit('change', internalValue.value);
-  });
+  const nextPageSize = parseInt(newVal, 10);
+  const nextPageCount = newPageCount(props.numberOfItems, nextPageSize);
+  pageCount.value = nextPageCount;
+  pages.value = newPagesArray(nextPageCount);
+  const nextPage = Math.ceil(firstItem.value / nextPageSize);
+  propose(nextPage, nextPageSize);
 }
 function onPrevPage() {
   if (pageValue.value > 1) {
-    pageValue.value--;
-    firstItem.value = newFirstItem(pageValue.value, pageSizeValue.value);
-    emit('change', internalValue.value);
+    propose(pageValue.value - 1, pageSizeValue.value);
   }
 }
 function onNextPage() {
   if (pageValue.value < pageCount.value) {
-    pageValue.value++;
-    firstItem.value = newFirstItem(pageValue.value, pageSizeValue.value);
-    emit('change', internalValue.value);
+    propose(pageValue.value + 1, pageSizeValue.value);
   }
 }
 function newPageValue(page, lastPage) {