@thinkpixellab-public/px-vue 3.0.42 → 4.0.0

package/bases/PxBaseItemsSelect.vue

@@ -0,0 +1,415 @@
+<!--
+    #VUE3 Done (has breaking changes)
+-->
+
+<script>
+import PxBaseItems from './PxBaseItems.vue';
+import utils from '../utils/utils.js';
+
+// helper to define what an "empty" key or set of keys looks like
+const isKeySetEmpty = keyOrKeys => {
+    return (
+        keyOrKeys == null ||
+        keyOrKeys == undefined ||
+        (Array.isArray(keyOrKeys) && keyOrKeys.length == 0)
+    );
+};
+
+// helper to ensure that a potential key or set of keys is an array
+const ensureSet = valueOrArray => {
+    if (isKeySetEmpty(valueOrArray)) {
+        return [];
+    }
+
+    return Array.isArray(valueOrArray) ? valueOrArray : [valueOrArray];
+};
+
+export default {
+    mixins: [PxBaseItems],
+
+    props: {
+        /**
+         * Set the selection as either a single item key or an array of item keys.
+         */
+        selected: { default: null },
+
+        /**
+         * If true, the first item in a collection will be automatically selected on load or when
+         * items is updated and no other item is selected
+         */
+        autoSelectFirst: { type: Boolean, default: false },
+    },
+
+    data() {
+        return {
+            selectedKeys: [],
+            baseUpdateMode: 'single',
+        };
+    },
+
+    computed: {
+        /**
+         * Indicates whether the update event arg is a single key or an array of keys.  Note that
+         * selection is always stored internally (selectedKeys) as an array of keys.
+         *
+         * Derived classes should override this to indicate the current update mode and can expose
+         * an additional prop to control it. We're returning the value of a data value so that it
+         * can be set when testing but there's no internal process that would ever change this
+         * value.
+         *
+         * In `single` mode the event is the first selected item or null when empty. The intended
+         * use is components that don't support multiselection.
+         *
+         * In `multi` mode the event is always an array with all selected items.
+         *
+         * @values single, multi
+         */
+        updateMode() {
+            return this.baseUpdateMode;
+        },
+
+        /**
+         * Returns an array that contains the keys for all fo the items in items.
+         */
+        itemKeys() {
+            return this.items.map(item => this.getItemKey(item));
+        },
+
+        /**
+         * Returns the first selected key
+         */
+        selectedKey() {
+            return this.selectedKeys?.length ? this.selectKeys[0] : null;
+        },
+
+        /**
+         * Returns the currently selected items.
+         */
+        selectedItems() {
+            return (this.selectedKeys || []).map(key => {
+                return this.getItem(key);
+            });
+        },
+
+        /**
+         * Returns the first selected item or null if selection is empty.
+         */
+        selectedItem() {
+            return this.selectedItems.length ? this.selectedItems[0] : null;
+        },
+
+        /**
+         * Returns the indices of the currently selected items.
+         */
+        selectedIndices() {
+            return (this.selectedKeys || []).map(key => {
+                return this.getItemKeyIndex(key);
+            });
+        },
+
+        /**
+         * Returns the index of the first selected item or null if selection is empty.
+         */
+        selectedIndex() {
+            return this.selectedIndices.length ? this.selectedIndices[0] : null;
+        },
+    },
+
+    watch: {
+        selected: {
+            immediate: true,
+            handler(nv, ov) {
+                // check for matching values
+                if (nv && ov && nv.length == ov.length) {
+                    let match = true;
+                    for (let i = 0; i < nv.length; i++) {
+                        match = match && nv[i] == ov[i];
+                    }
+                    if (match) {
+                        return;
+                    }
+                }
+                this.setSelection(nv);
+            },
+        },
+        selectedKeys: {
+            immediate: true,
+            handler() {
+                this.emitUpdateEvent();
+            },
+        },
+
+        // selected(nv) {
+        //     this.selectedKeys = this.ensureCorrectValue(nv);
+        // },
+
+        // items() {
+        //     this.tryAutoSelect();
+        // },
+    },
+
+    mounted() {
+        if (this.autoSelectFirst && isKeySetEmpty(this.selected) && this.items?.length) {
+            this.selectAt(0);
+        }
+        // this.$nextTick(() => {
+        //     this.tryAutoSelect();
+        // });
+    },
+
+    methods: {
+        /**
+         * Emit the change / update:selected event
+         */
+        emitUpdateEvent() {
+            let updateArg;
+
+            if (this.updateMode == 'single') {
+                updateArg = this.selectedKeys.length ? this.selectedKeys[0] : null;
+            } else {
+                updateArg = this.selectedKeys;
+            }
+
+            this.$emit('change', updateArg);
+            this.$emit('update:selected', updateArg);
+        },
+
+        /**
+         * Replace the current set of selected keys with the keys provided here. Keys that don't
+         * have a corresponding item in the items collection in items will be ignored.
+         */
+        setSelection(keyOrKeys) {
+            const validKeys = ensureSet(keyOrKeys).filter(key => this.isValidItemKey(key));
+            this.selectedKeys = validKeys;
+        },
+
+        // ----------------------------------------------------------------------
+        // Key-based methods
+
+        /**
+         * Check if the provided key is selected.
+         */
+        isSelected(key) {
+            return !!(this.selectedKeys?.length && this.selectedKeys.includes(key));
+        },
+
+        /**
+         * Add the provided key or keys to the current selection.
+         */
+        selectKeys(addKeyOrKeys, replaceSelection = 'auto') {
+            const replace = this.getShouldReplace(replaceSelection);
+
+            if (isKeySetEmpty(addKeyOrKeys)) {
+                if (replace) {
+                    this.selectedKeys = [];
+                }
+                return;
+            }
+
+            const addKeys = ensureSet(addKeyOrKeys).filter(key => this.isValidItemKey(key));
+
+            if (replace) {
+                this.selectedKeys = addKeys;
+                return;
+            } else {
+                this.selectedKeys = [
+                    ...this.selectedKeys,
+                    ...addKeys.filter(key => !this.selectedKeys.includes(key)),
+                ];
+            }
+        },
+
+        /**
+         * Select the provided key and replace the selection if updateMode is 'single' or add to the
+         * selection if updateMode is 'multi'
+         */
+        selectKey(key, replaceSelection = 'auto') {
+            this.selectKeys(key, this.getShouldReplace(replaceSelection));
+        },
+
+        /**
+         * Select the provided key (and replace the current selection)
+         */
+        selectKeyOnly(key) {
+            this.selectKeys(key, true);
+        },
+
+        /**
+         * Select the provided key or keys (and replace the current selection)
+         */
+        selectKeysOnly(addKeyOrKeys) {
+            this.selectKeys(addKeyOrKeys, true);
+        },
+
+        /**
+         * Remove the provided key or keys from the current selection.
+         */
+        unselectKeys(removeKeyOrKeys) {
+            const removeKeys = ensureSet(removeKeyOrKeys);
+            if (removeKeys.length) {
+                this.selectedKeys = this.selectedKeys.filter(key => !removeKeys.includes(key));
+            }
+        },
+
+        /**
+         * Remove the provided key from the current selection (convenience for better syntax when
+         * working with 'single' mode).
+         */
+        unselectKey(key) {
+            this.unselectKeys(key);
+        },
+
+        /**
+         * Toggle selection of the given key.
+         */
+        toggleKey(key) {
+            if (this.isSelected(key)) {
+                this.unselectKeys(key);
+            } else {
+                this.selectKeys(key);
+            }
+        },
+
+        // ----------------------------------------------------------------------
+        // Item-based methods
+
+        /**
+         * Check if the provided key is selected.
+         */
+        isItemSelected(item) {
+            return this.isSelected(this.getItemKey(item));
+        },
+
+        /**
+         * Add the provided item or items to the current selection. (Note: this is a convenience
+         * method and selection will continue to be stored as keys.)
+         */
+        selectItems(items, replaceSelection = 'auto') {
+            const keys = ensureSet(items).map(item => this.getItemKey(item));
+            this.selectKeys(keys, this.getShouldReplace(replaceSelection));
+        },
+
+        /**
+         * Select the provided item and replace the selection if updateMode is 'single' or add to
+         * the selection if updateMode is 'multi'. (Note: this is a convenience method and selection
+         * will continue to be stored as keys.)
+         */
+        selectItem(item, replaceSelection = 'auto') {
+            this.selectItems(item, this.getShouldReplace(replaceSelection));
+        },
+
+        /**
+         * Select the provided item (and replace the current selection). (Note: this is a convenience
+         * method and selection will continue to be stored as keys.)
+         */
+        selectItemOnly(item) {
+            this.selectItem(item, true);
+        },
+
+        /**
+         * Select the provided item or items (and replace the current selection). (Note: this is a
+         * convenience method and selection will continue to be stored as keys.)
+         */
+        selectItemsOnly(items) {
+            this.selectItems(items, true);
+        },
+
+        /**
+         * Remove the provided item or items from the current selection.
+         */
+        unselectItems(itemOrItems) {
+            const keys = ensureSet(itemOrItems).map(item => this.getItemKey(item));
+            this.unselectKeys(keys);
+        },
+
+        /**
+         * Remove the provided key from the current selection (convenience for better syntax when
+         * working with 'single' mode).
+         */
+        unselectItem(item) {
+            this.unselectItems(item);
+        },
+
+        /**
+         * Toggle selection of the given item.
+         */
+        toggleItem(item) {
+            const key = this.getItemKey(item);
+            if (key) {
+                this.toggleKey(key);
+            }
+        },
+
+        // ----------------------------------------------------------------------
+        // Index-based methods
+
+        selectAt(index, replaceSelection = 'auto') {
+            const keyAtIndex = this.itemKeys[index];
+
+            const replace =
+                replaceSelection == 'auto' ? this.updateMode == 'single' : replaceSelection;
+
+            this.selectKeys(keyAtIndex, replace);
+        },
+
+        selectAtSafe(index, wrap = false, replaceSelection = 'auto') {
+            const replace =
+                replaceSelection == 'auto' ? this.updateMode == 'single' : replaceSelection;
+
+            index = utils.arraySafeIndex(this.items, index, 0, wrap);
+            this.selectAt(index, replace);
+        },
+
+        selectOffset(offsetFromSelectedIndex, wrap = true) {
+            if (this.selectedIndex === null) {
+                this.selectAt(0);
+            } else {
+                const index = utils.arraySafeIndex(
+                    this.items,
+                    this.selectedIndex,
+                    offsetFromSelectedIndex,
+                    wrap
+                );
+                this.selectAt(index, true);
+            }
+        },
+
+        selectNext(wrap = true) {
+            this.selectOffset(1, wrap);
+        },
+
+        selectPrevious(wrap = true) {
+            this.selectOffset(-1, wrap);
+        },
+
+        unselectAt(index) {},
+
+        // ----------------------------------------------------------------------
+        // Other Selection
+
+        selectAll() {
+            if (Array.isArray(this.items) && this.items.length) {
+                if (this.updateMode == 'multi') {
+                    this.selectedKeys = this.itemKeys;
+                } else {
+                    this.selectedKeys = ensureSet(this.getItemKey(this.items[0]));
+                }
+            }
+        },
+
+        selectNone() {
+            this.selectedKeys = [];
+        },
+
+        // ----------------------------------------------------------------------
+        // Internal / helper
+
+        getShouldReplace(value) {
+            if (value == 'auto') {
+                return this.updateMode == 'single';
+            }
+            return value;
+        },
+    },
+};
+</script>

package/{components → bases}/PxBaseMobileAware.vue

@@ -1,4 +1,6 @@
 <!--
+    #VUE3 Todo
+
     Use for global mobile awareness in javascript. This doesn't actually handle mobile detection
     but provides a consistent interface for communicating between a single component that does
     the detection and other components that subscribe to an eventbus and update a property called
@@ -9,7 +11,7 @@
     ### MyLayout.vue (or other global component)
 
         // add PxBaseMobileAware as a mixin
-        import PxBaseMobileAware from '@thinkpixellab-public/px-vue/components/PxBaseMobileAware.vue';
+        import PxBaseMobileAware from '@thinkpixellab-public/px-vue/bases/PxBaseMobileAware.vue';
         mixins: [PxBaseMobileAware],
 
         // add a resize handler and call setGlobalIsMobile
@@ -32,7 +34,7 @@
     ### MyComponent.vue
 
         // use PxBaseMobileAware as a mixin
-        import PxBaseMobileAware from '@thinkpixellab-public/px-vue/components/PxBaseMobileAware.vue';
+        import PxBaseMobileAware from '@thinkpixellab-public/px-vue/bases/PxBaseMobileAware.vue';
         mixins: [PxBaseMobileAware]
 
         // use the isMobile property as needed in a template

package/{components → bases}/PxBaseResize.vue

@@ -1,6 +1,13 @@
+<!--
+    #VUE3 Todo
+-->
+
 <script>
-import { debounce } from 'debounce';
+import { debounce } from 'throttle-debounce';
 
+/**
+ * Mixin that provides size watch capabilities using the ResizeObserver api.
+ */
 export default {
     data() {
         return {
@@ -23,10 +30,10 @@ export default {
     mounted() {
         const resizeDebouncedFn =
             this.resizeDebounceValue && this.resize
-                ? debounce(e => {
+                ? debounce(this.resizeDebounceValue, e => {
                       this.resize(e);
                       this.resizing = false;
-                  }, this.resizeDebounceValue)
+                  })
                 : null;
 
         const resizeFn = () => {
@@ -52,7 +59,7 @@ export default {
         this.resizeObserver = new ResizeObserver(resizeFn);
         this.resizeObserver.observe(this.observeElementValue);
     },
-    beforeDestroy() {
+    beforeUnmount() {
         this.resizeObserver.disconnect();
         delete this.resizeObserver;
     },

package/bases/PxBaseScroll.vue

@@ -0,0 +1,46 @@
+<!--
+    #VUE3 Todo
+-->
+
+<script>
+
+export default {
+    // components: { Component },
+    // mixins: [ Mixin ],
+    // props: { a: { type: Boolean, default: false } },
+    data() {
+        return { scrollPosition: { x: 0, y: 0 } };
+    },
+    computed: {
+        scrollingElement() {
+            // derived classes can return something here to watch somethign other than document
+            return window !== undefined ? window : null;
+        },
+    },
+    // watch: {},
+    mounted() {
+        if (this.scrollingElement && this.scroll) {
+            let scroller = this.scrollingElement;
+            let ticking = false;
+
+            scroller.addEventListener('scroll', event => {
+                this.scrollPosition.x = scroller.scrollX;
+                this.scrollPosition.y = scroller.scrollY;
+
+                if (!ticking) {
+                    window.requestAnimationFrame(() => {
+                        this.scroll();
+                        ticking = false;
+                    });
+
+                    ticking = true;
+                }
+            });
+        }
+    },
+    methods: {
+        // base class should override
+        // onScroll() {},
+    },
+};
+</script>

package/bases/PxBaseToggle.vue

@@ -0,0 +1,67 @@
+<!--
+    #VUE3 Todo
+
+    Base class for classes that manage a checked state. In order to simplify the data
+    synchronization with the input, we enable v-model binding by also providing a data property
+    (checkedValue) that mirrors the checked prop. The intention is that this property will only be
+    used internally as v-model.
+
+-->
+
+<script>
+export default {
+    props: {
+        /**
+         * The value of the checked property.
+         */
+        checked: { type: Boolean, default: false },
+
+        /**
+         * Class that should be set on the component when checked.
+         */
+        checkedClass: { type: String, default: null },
+
+        /**
+         * Disables interaction.
+         */
+        disabled: { type: Boolean, default: false },
+    },
+    data() {
+        return {
+            checkedValue: this.checked,
+        };
+    },
+
+    watch: {
+        checked(nv) {
+            // update checkedValue when checked changes
+            this.checkedValue = nv;
+        },
+
+        checkedValue(nv) {
+            // emit update when checkedValue changes (enables .sync on parent)
+            this.$emit('update:checked', nv);
+
+            if (nv) {
+                this.$emit('checked');
+            }
+            if (!nv) {
+                this.$emit('unchecked');
+            }
+        },
+    },
+    computed: {
+        calcCheckedClass() {
+            return this.checkedValue && this.checkedClass ? this.checkedClass : null;
+        },
+    },
+    methods: {
+        toggleChecked() {
+            if (this.disabled) {
+                return;
+            }
+            this.checkedValue = !this.checkedValue;
+        },
+    },
+};
+</script>

package/bases/PxBaseUniqueId.vue

@@ -0,0 +1,18 @@
+<!--
+    #VUE3 Todo
+-->
+
+<script>
+// TODO: this is currently not compatible with SSR
+
+export default {
+    methods: {
+        uniqueId(prefix) {
+            if (!this.__uniqueId) {
+                this.__uniqueId = Math.random().toString(36).substring(2);
+            }
+            return (prefix ? `${prefix}-` : '') + this.__uniqueId;
+        },
+    },
+};
+</script>

package/{components → bases}/PxBaseVariants.vue

@@ -1,4 +1,6 @@
 <!--
+    #VUE3 Done
+
 
 Provides a standardized way of specifying variants of a component. Variants are typically css-based
 modifications to a component and might be defined by the component or declared in the app. Typical
@@ -19,6 +21,11 @@ usage might look like:
 import variants from '../utils/variants.js';
 export default {
     props: {
+        /**
+         * The variant property is intepreted in different ways by different components, but
+         * typically used to trigger a different style or layout otherwise effect the way the
+         * component is rendered or used.
+         */
         variant: { type: String, default: 'default' },
     },
     computed: {
@@ -42,6 +49,7 @@ export default {
         isVariant(variantName) {
             return this.variants?.includes(variantName);
         },
+
         // find the first matching variant key in a map and return the correspond value
         variantsToValue(valueMap, fallback) {
             for (let key in valueMap) {
@@ -51,9 +59,11 @@ export default {
             }
             return fallback;
         },
+
         stringToVariants: str => {
             return variants.stringToVariants(str);
         },
+
         stringToVariantsMap: str => {
             return variants.stringToVariantsMap(str);
         },

package/{components → bases}/PxBaseVariantsOverride.vue

@@ -1,10 +1,12 @@
 <!--
+    #VUE3 Done
+
     Extends PxBaseVariants with the ability to specify default and base variants
     (see descriptions of props below).
 -->
 
 <script>
-import PxBaseVariants from './PxBaseVariants.vue';
+import PxBaseVariants from '../bases/PxBaseVariants.vue';
 export default {
     mixins: [PxBaseVariants],
     props: {
@@ -18,7 +20,7 @@ export default {
         variantValue() {
             return (
                 (this.variantBase ? `${this.variantBase} ` : '') +
-                (this.variant ?? this.variantDefault)
+                (this.variantDefault ? this.variantDefault : this.variant)
             );
         },
     },

package/{components → bases}/PxBaseVisible.vue

@@ -1,4 +1,6 @@
 <!--
+    #VUE3 Done
+
     Base class that provides a single visible property / data value this is sync capable. Also
     provides show/hide/toggle methods. Override the visible prop to change the default state.
 -->