@thinkpixellab-public/px-vue 3.0.1

package/components/PxBalancedText.vue

@@ -0,0 +1,118 @@
+<template>
+    <component
+        :is="tag"
+        class="px-balanced-text"
+        :style="{ opacity: elementOpacity, color: debugColor }"
+    >
+        <!-- html -->
+        <component v-if="hasHtml" :class="bem('inner')" :is="innerTag" ref="text" v-html="html" />
+
+        <!-- slot -->
+        <component v-else :class="bem('inner')" :is="innerTag" ref="text">
+            <slot />
+        </component>
+    </component>
+</template>
+
+<script>
+import PxBaseResize from './PxBaseResize.vue';
+import balanceText from '../utils/balanceText.js';
+
+export default {
+    mixins: [PxBaseResize],
+    props: {
+        // the outer tag element
+        tag: { type: String, default: 'p' },
+
+        // the inner tag element
+        innerTag: { type: String, default: 'span' },
+
+        // html that gets set on the inner tag element
+        html: { type: String, default: null },
+
+        // set to false to disable the balancing alorithm
+        enabled: { type: Boolean, default: true },
+
+        // when true opacity will be set to 0 if balancing is enabled but text is unbalanced (as a
+        // precaution, we also show if balancing fails for some reason)
+        hideUnbalanced: { type: Boolean, default: true },
+
+        // enable to get debug color (blue: balanced html, green: balance slot, red: disabled)
+        debug: { type: Boolean, default: false },
+    },
+    data() {
+        return {
+            balanced: false,
+            balanceFailed: false,
+        };
+    },
+    computed: {
+        hasHtml() {
+            return !!this.htmlValue;
+        },
+
+        htmlValue() {
+            return this.html?.trim();
+        },
+
+        elementOpacity() {
+            if (this.enabled && !this.balanceFailed && !this.balanced) {
+                return 0;
+            }
+            return null;
+        },
+        debugColor() {
+            if (this.debug) {
+                if (!this.enabled) {
+                    return 'red';
+                }
+
+                if (this.balanced && this.hasHtml) {
+                    return 'blue';
+                }
+
+                if (this.balanced) {
+                    return 'green';
+                }
+            }
+            return null;
+        },
+    },
+    watch: {
+        enabled() {
+            this.balanced = false;
+            if (!process.server) {
+                this.$nextTick(() => {
+                    this.resize();
+                });
+            }
+        },
+    },
+    methods: {
+        resize() {
+            if (this.enabled && !process.server) {
+                try {
+                    this.balanceFailed = false;
+                    if (this.$refs.text && this.$refs.text.offsetWidth > 0) {
+                        balanceText(this.$refs.text);
+                    }
+                    this.balanced = true;
+                } catch (error) {
+                    console.error('balanceText failed');
+                    console.error(error);
+                    this.balanceFailed = true;
+                }
+            }
+        },
+    },
+};
+</script>
+
+<style lang="scss">
+.px-balanced-text {
+    width: 100%;
+    &__inner {
+        display: inline-block;
+    }
+}
+</style>

package/components/PxBase.vue

@@ -0,0 +1,15 @@
+<script>
+export default {
+    methods: {
+        /*
+        Get a unique id derived from vue's unique component identifier (this._uid) for use when an
+        id is required for an inputs, labels, etc.
+            uniqueId('label') => 'label-0003'
+        */
+        uniqueId(prefix = null) {
+            let id = ('000000' + Number(this._uid).toString(16).toLowerCase()).slice(-4);
+            return prefix ? prefix + '-' + id : id;
+        },
+    },
+};
+</script>

package/components/PxBaseDate.vue

@@ -0,0 +1,27 @@
+<script>
+export default {
+    model: {
+        prop: 'date',
+        event: 'changed',
+    },
+    props: {
+        date: { type: Date, default: null },
+    },
+    data() {
+        return {
+            dateValue: this.date,
+        };
+    },
+    watch: {
+        date: {
+            handler(nv) {
+                this.dateValue = nv;
+            },
+        },
+        dateValue(nv) {
+            this.$emit('update:date', nv);
+            this.$emit('changed', nv);
+        },
+    },
+};
+</script>

package/components/PxBaseItems.vue

@@ -0,0 +1,72 @@
+<!--
+
+    Provides basic items services for controls that maintain lists of items.
+
+-->
+
+<script>
+export default {
+    props: {
+        items: { type: Array },
+        itemsKeyProperty: { type: String, default: 'id' },
+        itemsValueProperty: { type: String, default: 'value' },
+        itemsLabelProperty: { type: String, default: 'label' },
+        itemsDisabledProperty: { type: String, default: 'disabled' },
+    },
+
+    computed: {
+        itemKeys() {
+            if (this.items) {
+                return this.items.map(item => this.getItemKey(item));
+            }
+            return [];
+        },
+    },
+    methods: {
+        isValidItemKey(key) {
+            this.itemKeys.includes(key);
+        },
+
+        getItem(key) {
+            if (typeof key !== 'undefined') {
+                return this.items.find(item => this.getItemKey(item) === key);
+            }
+            return null;
+        },
+
+        getItemKey(item) {
+            if (item && this.itemsKeyProperty) {
+                if (!(this.itemsKeyProperty in item)) {
+                    console.warn(
+                        `Key value property "${this.itemsKeyProperty}" could not be found.`
+                    );
+                }
+                return item[this.itemsKeyProperty];
+            }
+            return null;
+        },
+
+        getItemLabel(item) {
+            if (item && this.itemsLabelProperty && item[this.itemsLabelProperty]) {
+                return item[this.itemsLabelProperty];
+            }
+            // fallback to value
+            return this.getItemValue(item);
+        },
+
+        getItemValue(item) {
+            if (item && this.itemsValueProperty) {
+                return item[this.itemsValueProperty];
+            }
+            return null;
+        },
+
+        getItemDisabled(item) {
+            if (item && this.itemsDisabledProperty) {
+                return item[this.itemsDisabledProperty];
+            }
+            return false;
+        },
+    },
+};
+</script>

package/components/PxBaseItemsSelect.vue

@@ -0,0 +1,230 @@
+<!--
+    Extends PxBaseItems to include selection. Selection is managed via item key.
+
+    @change: Fired whenever selection changes. The event argument is the array of selected keys.
+    @update:selected: Same as @change (duplicated so that .sync scenarios work)
+
+-->
+
+<script>
+import PxBaseItems from './PxBaseItems.vue';
+import utils from '../utils/utils.js';
+
+export default {
+    mixins: [PxBaseItems],
+
+    model: {
+        prop: 'selected',
+        event: 'update:selected',
+    },
+
+    props: {
+        // whether to allow multiple items to be selected (note: this effects the expeected type for selected)
+        multiSelect: { type: Boolean, default: false },
+
+        // can be either a single value (the selected key) or an array of keys (if multiselect is enabled or selectionIsArray)
+        selected: { default: null },
+
+        // set this to manage selection as an array evne in multiSelect is true
+        selectedIsArray: { type: Boolean, default: false },
+
+        // if true, then an empty selection state will return a value of null instead of an empty array []
+        emptySelectionIsNull: { type: Boolean, default: false },
+
+        // if true, the first item in a collection will be automatically set when items is updated
+        // if no other item is selected
+        autoSelectFirst: { type: Boolean, default: false },
+    },
+
+    data() {
+        return {
+            syncSelected: this.ensureCorrectValue(this.selected),
+        };
+    },
+
+    computed: {
+        selectedIndex() {
+            if (!this.syncSelected) {
+                return -1;
+            }
+            return this.itemKeys.indexOf(this.syncSelected);
+        },
+
+        selectedItem() {
+            if (this.selectedIndex > -1) {
+                return this.items[this.selectedIndex];
+            }
+            return null;
+        },
+    },
+
+    watch: {
+        selected(nv) {
+            this.syncSelected = this.ensureCorrectValue(nv);
+        },
+        syncSelected(nv) {
+            this.emitUpdate(nv);
+        },
+        multiSelect() {
+            this.syncSelected = this.ensureCorrectValue(this.syncSelected);
+        },
+        items() {
+            this.tryAutoSelect();
+        },
+    },
+
+    mounted() {
+        this.$nextTick(() => {
+            this.tryAutoSelect();
+        });
+    },
+
+    methods: {
+        // general purpose method that converts a value to the appropriate type (array or value)
+        // based on whether multiselect is enabled
+        ensureCorrectValue(value) {
+            if (this.multiSelect || this.selectedIsArray) {
+                if (Array.isArray(value)) {
+                    return value;
+                } else {
+                    return value == null || typeof value == 'undefined' ? [] : [value];
+                }
+            } else {
+                if (Array.isArray(value)) {
+                    return value.length ? value[0] : null;
+                }
+            }
+            return value;
+        },
+
+        // emit the change event (as a method so that it can be overriden)
+        emitUpdate(nv) {
+            nv = this.ensureCorrectValue(nv);
+            this.$emit('change', nv);
+            this.$emit('update:selected', nv);
+        },
+
+        // select the first non-disabled item if nothing else is selected
+        tryAutoSelect() {
+            if (this.items?.length && this.autoSelectFirst && !this.syncSelected) {
+                const firstSelectable = this.items.find(item => !this.getItemDisabled(item));
+                if (firstSelectable) {
+                    this.selectItemOnly(firstSelectable);
+                }
+            }
+        },
+
+        // key based methods
+
+        // check if a key is selected
+        isSelected(key) {
+            if (this.multiSelect || this.selectedIsArray) {
+                return this.syncSelected?.includes(key);
+            } else {
+                return this.syncSelected == key;
+            }
+        },
+
+        // add the keys to the current selection (for single select, we set the first item in the addKeys array)
+        selectKeys(addKeys) {
+            if (!addKeys || (Array.isArray(addKeys) && addKeys.length == 0)) {
+                return;
+            }
+
+            addKeys = this.ensureCorrectValue(addKeys);
+
+            if (this.multiSelect) {
+                addKeys.forEach(key => {
+                    if (!this.syncSelected.includes(key)) {
+                        this.syncSelected.push(key);
+                    }
+                });
+            } else {
+                if (this.selectedIsArray) {
+                    this.syncSelected = [addKeys];
+                } else {
+                    this.syncSelected = addKeys;
+                }
+            }
+        },
+
+        unselectKeys(removeKeys) {
+            if (this.multiSelect || this.selectedIsArray) {
+                if (Array.isArray(removeKeys)) {
+                    this.syncSelected = this.syncSelected.filter(k => {
+                        return !removeKeys.includes(k);
+                    });
+                }
+            } else {
+                if (removeKeys.includes(this.selected)) {
+                    this.syncSelected = this.ensureCorrectValue(null);
+                }
+            }
+        },
+
+        selectKeyOnly(key) {
+            this.syncSelected = this.ensureCorrectValue(key);
+        },
+
+        toggleKey(key) {
+            if (this.isSelected[key]) {
+                this.selectKeys([key]);
+            } else {
+                this.unselectKeys([key]);
+            }
+        },
+
+        // item based methods
+
+        isItemSelected(item) {
+            return this.isSelected(this.getItemKey(item));
+        },
+
+        selectItems(addItems) {
+            if (Array.isArray(addItems)) {
+                let keys = addItems.map(item => this.getItemKey(item));
+                this.selectKeys(keys);
+            }
+        },
+
+        unselectItems(removeItems) {
+            if (Array.isArray(removeItems)) {
+                let keys = removeItems.map(item => this.getItemKey(item));
+                this.unselectKeys(keys);
+            }
+        },
+
+        selectItemOnly(item) {
+            this.selectKeyOnly(this.getItemKey(item));
+        },
+
+        toggleItem(item) {
+            this.toggleKey(this.getItemKey(item));
+        },
+
+        // other
+
+        selectIndexSafe(index, wrap = true) {
+            const idx = utils.arraySafeIndex(this.items, index, 0, wrap);
+            if (idx > -1) {
+                this.selectItemOnly(this.items[idx]);
+            }
+        },
+
+        selectOffsetSafe(offset, wrap = true) {
+            const idx = utils.arraySafeIndex(this.items, this.selectedIndex, offset, wrap);
+            if (idx > -1) {
+                this.selectItemOnly(this.items[idx]);
+            }
+        },
+
+        selectAll() {
+            this.selectKeys(this.itemKeys);
+        },
+
+        selectNone() {
+            this.syncSelected = [];
+        },
+    },
+};
+</script>

package/components/PxBaseResize.vue

@@ -0,0 +1,60 @@
+<script>
+import debounce from 'debounce';
+
+export default {
+    data() {
+        return {
+            resizing: false,
+        };
+    },
+    computed: {
+        // return something other than 0 to enable debounced resize (only evaluated in mounted in
+        // the current implementation)
+        resizeDebounceValue() {
+            return 0;
+        },
+
+        // the element to observe for size changes, defaults to this.$el (only evaluated in mounted
+        // in the current implementation)
+        observeElementValue() {
+            return this.$el;
+        },
+    },
+    mounted() {
+        const resizeDebouncedFn =
+            this.resizeDebounceValue && this.resize
+                ? debounce(e => {
+                      this.resize(e);
+                      this.resizing = false;
+                  }, this.resizeDebounceValue)
+                : null;
+
+        const resizeFn = entries => {
+            // debounced version
+            if (resizeDebouncedFn) {
+                if (!this.resizing) {
+                    this.resizing = true;
+                    if (this.resizeStarted) {
+                        this.resizeStarted(entries[0]);
+                    }
+                }
+                resizeDebouncedFn(entries[0]);
+            }
+
+            // regular version
+            else {
+                if (this.resize) {
+                    this.resize(entries[0]);
+                }
+            }
+        };
+
+        this.resizeObserver = new ResizeObserver(resizeFn);
+        this.resizeObserver.observe(this.observeElementValue);
+    },
+    beforeDestroy() {
+        this.resizeObserver.disconnect();
+        delete this.resizeObserver;
+    },
+};
+</script>

package/components/PxBaseToggle.vue

@@ -0,0 +1,56 @@
+<!--
+
+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 (syncChecked) that
+mirrors the checked prop. The intention is that this property will only be used internally as
+v-model.
+
+-->
+
+<script>
+import PxBase from './PxBase.vue';
+export default {
+    mixins: [PxBase],
+    model: {
+        prop: 'checked',
+        event: 'update:checked',
+    },
+    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 },
+
+        // disabled interaction
+        disabled: { type: Boolean, default: false },
+    },
+    data() {
+        return {
+            syncChecked: this.checked,
+        };
+    },
+    watch: {
+        syncChecked(nv) {
+            this.$emit('update:checked', nv);
+            if (nv) {
+                this.$emit('checked');
+            }
+            if (!nv) {
+                this.$emit('unchecked');
+            }
+        },
+        checked(nv) {
+            this.syncChecked = nv;
+        },
+    },
+    methods: {
+        toggleChecked() {
+            if (this.disabled) {
+                return;
+            }
+            this.syncChecked = !this.syncChecked;
+        },
+    },
+};
+</script>

package/components/PxBaseVariants.vue

@@ -0,0 +1,62 @@
+<!--
+
+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
+usage might look like:
+
+    Component code:
+    <div :class="'bem(variantsMap)'" />
+
+    User code:
+    <my-control variant="one two" />
+
+    This would produce:
+    <div class="my-component my-component--one my-component--two" />
+
+-->
+
+<script>
+import variants from '../utils/variants.js';
+export default {
+    props: {
+        variant: { type: String, default: 'default' },
+    },
+    computed: {
+        // get the value for variant (allows derived classes to provide a different source)
+        variantValue() {
+            return this.variant;
+        },
+
+        // all variants as an array
+        variants() {
+            return this.stringToVariants(this.variantValue);
+        },
+
+        // variants as a map like {one: true, two: true}
+        variantsMap() {
+            return this.stringToVariantsMap(this.variantValue);
+        },
+    },
+    methods: {
+        // true if the given variant is present
+        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) {
+                if (this.isVariant(key)) {
+                    return valueMap[key];
+                }
+            }
+            return fallback;
+        },
+        stringToVariants: str => {
+            return variants.stringToVariants(str);
+        },
+        stringToVariantsMap: str => {
+            return variants.stringToVariantsMap(str);
+        },
+    },
+};
+</script>

package/components/PxBaseVisible.vue

@@ -0,0 +1,40 @@
+<!--
+    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.
+-->
+
+<script>
+export default {
+    props: {
+        visible: { default: false },
+    },
+    data() {
+        return {
+            // mirrors visible
+            visibleValue: this.visible,
+        };
+    },
+    watch: {
+        visible(nv) {
+            // update visibleValue when visible changes
+            this.visibleValue = nv;
+        },
+
+        visibleValue(nv) {
+            // emit update when visibleValue changes (enables .sync on parent)
+            this.$emit('update:visible', nv);
+        },
+    },
+    methods: {
+        show() {
+            this.visibleValue = true;
+        },
+        hide() {
+            this.visibleValue = false;
+        },
+        toggle() {
+            this.visibleValue = !this.visibleValue;
+        },
+    },
+};
+</script>