@thinkpixellab-public/px-vue 4.1.7 → 4.1.8

package/components/PxBackgroundFader.vue

@@ -0,0 +1,137 @@
+<!--
+    Describe this component...
+-->
+<template>
+    <div :class="bem()">
+        <transition-group :class="bem('group')" name="px-background-fader__fade" tag="div">
+            <div
+                v-for="background in backgrounds"
+                :key="background.id"
+                :class="bem('background')"
+                :style="{
+                    transitionDuration: duration ? duration + 's' : null,
+                }"
+            >
+                <slot name="background" v-bind="background">
+                    <div
+                        :class="[background.value, ...backgroundClassArray]"
+                        :style="backgroundStyle"
+                    />
+                </slot>
+                <slot name="default" />
+            </div>
+        </transition-group>
+    </div>
+</template>
+
+<script>
+export default {
+    name: 'px-background-fader',
+    props: {
+        /** A background items can be anything. This will be made available to the background slot
+         * and the slot can render accordingly. The default slot assumes that the background is a
+         * class names and creates a div and sets the class. When the background is set, we will
+         * crossfade between the contents of the two slots. */
+        background: { default: null },
+
+        /** An additional class that gets applied to the background element in the default slot. */
+        backgroundClass: { default: 'px-background-fader__bg' },
+
+        /** Value for the style property that gets applied to the background element in th default slot */
+        backgroundStyle: { default: null },
+
+        /**
+         * The duration of the fade animation in seconds.
+         */
+        duration: { type: Number, default: 0 },
+    },
+    data() {
+        const backgroundId = 0;
+        const backgrounds = this.background ? [{ id: backgroundId, value: this.background }] : [];
+        return {
+            backgrounds,
+            backgroundId,
+            fadeLeaveDelay: this.duration ? this.duration : '',
+        };
+    },
+
+    computed: {
+        backgroundClassArray() {
+            if (Array.isArray(this.backgroundClass)) {
+                return this.backgroundClass;
+            }
+            return [this.backgroundClass];
+        },
+        fadeLeaveDelayCalc() {
+            if (this.fadeLeaveDelay !== null) {
+                return this.fadeLeaveDelay + 's';
+            }
+            return '--fade-leave-delay-def';
+        },
+    },
+    watch: {
+        background(nv, ov) {
+            if (this.compareItems(nv, ov)) {
+                return;
+            }
+
+            this.fadeLeaveDelay == !!ov ? this.duration : 0;
+
+            if (ov && this.backgrounds.length) {
+                this.backgrounds.shift();
+            }
+
+            if (nv) {
+                this.backgroundId++;
+                this.backgrounds.push({ id: this.backgroundId, value: nv });
+            }
+        },
+    },
+    methods: {
+        compareItems(a, b) {
+            if (a == b) {
+                return true;
+            }
+
+            if (typeof a == 'object' && typeof b == 'object') {
+                return JSON.stringify(a) == JSON.stringify(b);
+            }
+
+            return false;
+        },
+    },
+};
+</script>
+
+<style lang="scss">
+@use '../styles/px.scss' as *;
+
+@include vue-transition(px-background-fader__fade) {
+    $dur: 0.5s;
+
+    @include vt-transition {
+        @include transition(opacity, $dur: $dur);
+    }
+    @include vt-leaving() {
+        --fade-leave-delay-def: $dur;
+        transition-delay: v-bind(fadeLeaveDelayCalc);
+    }
+    @include vt-hidden {
+        opacity: 0;
+    }
+}
+
+.px-background-fader {
+    width: 100%;
+    height: 100%;
+    position: relative;
+
+    &__group {
+        display: contents;
+    }
+
+    &__bg {
+        @include abs();
+    }
+}
+</style>

package/components/PxIconButton.vue

@@ -1,5 +1,6 @@
 <template>
-    <button
+    <component
+        :is="tag"
         :class="
             bem({
                 ...variantsMap,
@@ -10,7 +11,7 @@
         @click="tryToggleChecked"
     >
         <px-icon :class="iconClass" v-bind="calcIconAttrs" />
-    </button>
+    </component>
 </template>
 
 <script>
@@ -67,6 +68,8 @@ export default {
         toggles: { type: Boolean, default: false },
 
         iconClass: { type: String, default: null },
+
+        tag: { type: String, default: 'button' },
     },
     computed: {
         calcIcon() {

package/components/PxImage.vue

@@ -0,0 +1,399 @@
+<template>
+    <div :class="[bem({ fit }), isEmpty ? emptyClass : '', isError ? errorClass : '']">
+        <transition :name="transitionName">
+            <img
+                v-if="imageA"
+                :key="'A'"
+                :class="
+                    bem('img', {
+                        [imageA.state]:
+                            imageA.state === IMAGE_STATES.LOADING ||
+                            imageA.state === IMAGE_STATES.UNLOADING
+                                ? loadingVisible
+                                : true,
+                    })
+                "
+                :src="imageA.src"
+                @load="imageLoad(imageA)"
+                @error="imageError($event, imageA)"
+            />
+        </transition>
+        <transition :name="transitionName">
+            <img
+                v-if="imageB"
+                :key="'B'"
+                :class="
+                    bem('img', {
+                        [imageB.state]:
+                            imageB.state === IMAGE_STATES.LOADING ||
+                            imageB.state === IMAGE_STATES.UNLOADING
+                                ? loadingVisible
+                                : true,
+                    })
+                "
+                :src="imageB.src"
+                @load="imageLoad(imageB)"
+                @error="imageError($event, imageB)"
+            />
+        </transition>
+
+        <slot name="placeholder" v-if="isEmpty"></slot>
+
+        <slot name="error" v-if="isError">
+            <PxIcon :class="bem('error-icon')" size="1.5em" :src="AlertTriangleSvgUrl" />
+        </slot>
+
+        <slot name="loading" v-if="loadingVisible">
+            <PxSpinner v-if="showLoadingSpinner" :visible="true" />
+        </slot>
+    </div>
+</template>
+
+<script>
+import PxSpinner from './PxSpinner.vue';
+import PxIcon from './PxIcon.vue';
+import AlertTriangleSvgUrl from '../assets/feather/alert-triangle.svg?url';
+
+/**
+
+An image component that can be used to easily access advanced functionality for displaying images.
+
+Current functionality includes:
+
+- Monitory image load state and displaying a loading indicator
+- Cusotmization (via css) of a background for the empty state
+- Fade in on load
+- Crossfade between images when source changes
+- Customizable error state
+- Handles background-like layout scenarios with cover and contain natively
+
+Future functionality:
+
+- Customization of previous (unloaded) image state when source changes (via class)
+- srcset (with img tag) / image-set (with background)
+- Prioritized / depriotized loading (relative to other images)
+- Only load on active state (via active property) or when in viewport
+- Deal with natural block layout (that allows the container to grow with the image data)
+
+IMPLEMENTATION NOTE:
+
+We ended up with the two image solution after trying a number of different approaches. The
+primary advantage of this approach is that it keeps image data and loading attached to an img
+elmement in the DOM which seems to simplify a lot of corner conditions like cancelling loads if the
+src changes partway through loading, etc. and issues with flickering when loading large image files.
+Mentioning here so that future me can avoid trying to "optimize" this later and making the same
+mistakes.
+
+ */
+
+const IMAGE_STATES = {
+    // inactive so it won't be rendered
+    INACTIVE: 'inactive',
+
+    // src has set but image isn't loaded
+    LOADING: 'loading',
+
+    // image has loaded with valid source
+    LOADED: 'loaded',
+
+    // image is unloading (previous image)
+    UNLOADING: 'unloading',
+};
+
+export default {
+    name: 'px-image',
+    components: { PxSpinner, PxIcon },
+    // mixins: [ Mixin ],
+    props: {
+        /**
+         * The image source.
+         */
+        src: { type: String, default: null },
+
+        /**
+         * The fit property specifies how the image should be sized to fit its container.
+         */
+        fit: { type: String, default: 'contain' },
+
+        /**
+         * Class that gets applied to the component if there is no current src (typically the
+         * initial state). Default behaviorOverridden is to set the background to a semi-transparent
+         * gray.
+         */
+        emptyClass: { type: [String, Array, Object], default: 'px-image--empty' },
+
+        /**
+         * Class that gets applied to the component if there is an error state. Default
+         * behaviorOverridden is to set the background to a semi-transparent gray like the empty
+         * state (and show the default error slot but that is controlled by the slot, not this
+         * prop).
+         */
+        errorClass: { type: [String, Array, Object], default: 'px-image--error' },
+
+        /**
+         * When true, we'll restore an "unloading" image when possible if the new image fails to
+         * load. In this case, we'll continue to raise an event but we won't show the error state or
+         * set the error class.
+         */
+        retorePreviousOnError: { type: Boolean, default: false },
+
+        // /**
+        //  * Class that gets applied to the component when an image is loading. No default.
+        //  */
+        // loadingClass: { type: [String, Array, Object], default: null },
+
+        // /**
+        //  * Class that gets applied to all image elements. The default sets the opacity transition.
+        //  */
+        // imageClass: { type: [String, Array, Object], default: 'px-image__image' },
+
+        // /**
+        //  * Class that gets applied to all image elements while loading. Default set opacity to 0.
+        //  */
+        // imageLoadingClass: { type: [String, Array, Object], default: 'px-image__image--loading' },
+
+        // /**
+        //  * Class that gets applied to all image elements while unloading. Default sets opacity to 0.5.
+        //  */
+        // imageUnloadingClass: {
+        //     type: [String, Array, Object],
+        //     default: 'px-image__image--unloading',
+        // },
+
+        /**
+         * A delay (in seconds) before showing loading state to avoid flickering when loading is fast.
+         */
+        loadingVisibleDelay: { type: Number, default: 0.5 },
+
+        /**
+         * Whether to show a loading spinner when loading in the default loading slot.
+         */
+        showLoadingSpinner: { type: Boolean, default: true },
+
+        /**
+         * Transition that gets applied when the src changes (we will generate multiple img elements
+         * in this case and apply this transition between them, leave as null to use the default
+         * which will fade.)
+         */
+        transitionName: { type: String, default: 'px-image__fade' },
+
+        /**
+         * Duration of the transition in seconds.
+         */
+        transitionDuration: { type: Number, default: 0.5 },
+    },
+    data() {
+        const image = {
+            state: IMAGE_STATES.INACTIVE,
+            src: null,
+        };
+
+        return {
+            // we manage the data for two images of these (one for the loaded image and one for the
+            // next image so we can fade on load) but only render as needed
+            images: [{ ...image }, { ...image }],
+
+            // reference to the last loading error if there is one (otherwise null)
+            error: null,
+
+            // whether to show the loading state (baed on loadingVisibleDelay)
+            loadingVisible: false,
+
+            // so we can access from the template
+            IMAGE_STATES,
+            AlertTriangleSvgUrl,
+        };
+    },
+    computed: {
+        imageA() {
+            return this.images[0]?.state !== IMAGE_STATES.INACTIVE ? this.images[0] : null;
+        },
+        imageB() {
+            return this.images[1]?.state !== IMAGE_STATES.INACTIVE ? this.images[1] : null;
+        },
+        isError() {
+            return !!this.error;
+        },
+        isEmpty() {
+            return !this.isError && !this.imageA?.src && !this.imageB?.src;
+        },
+        isLoading() {
+            return !this.isError && this.images.some(i => i.state === IMAGE_STATES.LOADING);
+        },
+        cssTransitionDuration() {
+            return this.transitionDuration + 's';
+        },
+    },
+    watch: {
+        src: {
+            immediate: true,
+            handler(nv) {
+                // clear previous errors
+                this.error = null;
+
+                // trim src (just in case but also to prevent false positives on empty string)
+                nv = typeof nv === 'string' ? nv.trim() : null;
+
+                if (!nv) {
+                    // if we have no src, just mark both images as inactive
+                    this.images.forEach(i => (i.state = IMAGE_STATES.INACTIVE));
+                    return;
+                }
+
+                // find an an inactive, unloaded or loading image to update (priotize loading so we don't end
+                // up with two loading)
+
+                const nextImage =
+                    this.images.find(i => i.state === IMAGE_STATES.LOADING) ||
+                    this.images.find(i => i.state === IMAGE_STATES.INACTIVE);
+
+                if (nextImage) {
+                    nextImage.src = nv;
+                    nextImage.state = IMAGE_STATES.LOADING;
+                } else {
+                    console.warn('No image available to update');
+                    return;
+                }
+
+                // if we have a loaded image, mark it as unloading
+                const prevImage = this.images.find(i => i.state === IMAGE_STATES.LOADED);
+
+                if (prevImage) {
+                    prevImage.state = IMAGE_STATES.UNLOADING;
+                }
+
+                //image.state = IMAGE_STATES.LOADING;
+            },
+        },
+        isLoading(nv) {
+            clearTimeout(this.loadingTimeout);
+
+            if (!nv) {
+                this.loadingVisible = false;
+                return;
+            }
+
+            this.loadingTimeout = setTimeout(() => {
+                this.loadingVisible = this.isLoading;
+            }, this.loadingVisibleDelay * 1000);
+        },
+    },
+    mounted() {
+        this.nextId = 0;
+        this.invalidIds = [];
+    },
+    methods: {
+        resetImages() {
+            this.images[0].state = IMAGE_STATES.INACTIVE;
+            this.images[0].src = null;
+            this.images[1].state = IMAGE_STATES.INACTIVE;
+            this.images[1].src = null;
+        },
+        imageLoad(image) {
+            this.$emit('load', image.src);
+
+            // mark the current image as loaded
+            image.state = IMAGE_STATES.LOADED;
+
+            // mark the previous image as inactive so we can hide remove it from the DOM
+            const prevImage = this.images.find(i => i.state === IMAGE_STATES.UNLOADING);
+            if (prevImage) {
+                prevImage.state = IMAGE_STATES.INACTIVE;
+            }
+
+            // we shouldn't have only have loaded or inactive images at this point
+            const loadingImage = this.images.find(
+                i => !(i.state == IMAGE_STATES.LOADED || i.state == IMAGE_STATES.INACTIVE),
+            );
+            if (loadingImage) {
+                console.warn('Loading image not properly cleared');
+            }
+        },
+        imageError(e, image) {
+            const error = { event: e, image };
+            this.$emit('error', error);
+
+            image.state = IMAGE_STATES.INACTIVE;
+
+            // try to restore a previous image if we have one and retorePreviousOnError is true
+            if (this.retorePreviousOnError) {
+                const prevImage = this.images.find(i => i.state === IMAGE_STATES.UNLOADING);
+                if (prevImage) {
+                    prevImage.state = IMAGE_STATES.LOADED;
+                    prevImage.src = image.src;
+                    return;
+                }
+            }
+
+            // otherwise, set the error and reset images
+            this.error = error;
+            this.resetImages();
+        },
+    },
+};
+</script>
+
+<style lang="scss">
+@use '../styles/px.scss' as *;
+
+$ease: $ease-out-cubic;
+$dur: v-bind(cssTransitionDuration);
+$name: px-image__fade;
+
+.px-image {
+    width: 100%;
+    height: 100%;
+    position: relative;
+
+    // so that placeholder and loading are centered
+    display: flex;
+    align-items: center;
+    justify-content: center;
+
+    // for the error and empty states
+    @include transition(background-color);
+
+    img {
+        @include abs-fill();
+        object-position: center center;
+    }
+
+    &--fit-cover {
+        img {
+            object-fit: cover;
+        }
+    }
+
+    &--fit-contain {
+        img {
+            object-fit: contain;
+        }
+    }
+
+    &--error,
+    &--empty {
+        background-color: rgba(#444, 0.1);
+    }
+
+    &__img {
+        transition: opacity $dur $ease;
+
+        // default transition is to fade
+
+        &.#{$name}-enter,
+        &.#{$name}-enter-from,
+        &.#{$name}-leave-to {
+            opacity: 0;
+        }
+
+        &--loading {
+            visibility: hidden;
+            opacity: 0 !important;
+        }
+
+        &--unloading {
+            opacity: 0.5;
+        }
+    }
+}
+</style>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thinkpixellab-public/px-vue",
-    "version": "4.1.7",
+    "version": "4.1.8",
     "description": "General purpose Vue components and helpers that can be used across projects.",
     "author": {
         "name": "Pixel Lab"

package/stories/PxBackgroundFader.stories.js

@@ -0,0 +1,42 @@
+import PxBackgroundFader from '@/components/PxBackgroundFader.vue';
+import PxButton from '@/components/PxButton.vue';
+import { extractArgTypes } from '@/storybook/sb-utils.js';
+
+export default {
+    title: 'PxBackgroundFader',
+    component: PxBackgroundFader,
+
+    argTypes: {
+        ...extractArgTypes(PxBackgroundFader),
+    },
+};
+
+export const Basic = {
+    render: (args, { argTypes }) => ({
+        components: { PxBackgroundFader, PxButton },
+
+        data() {
+            return {
+                args,
+                currentBackground: 'story-bg-blue',
+            };
+        },
+
+        template: `
+        <div class="story-aspect-16-9" style="overflow: hidden;">
+            <PxBackgroundFader :background="currentBackground"></PxBackgroundFader>
+            <PxButton style="position: absolute; top: 1em; left: 1em; z-index: 1" @click="changeBackground">Fade</PxButton>
+        </div>
+        `,
+
+        methods: {
+            changeBackground() {
+                const backgrounds = 'story-bg-orange|story-bg-blue|story-bg-green|story-bg-gold'
+                    .split('|')
+                    .filter(c => c !== this.currentBackground);
+                this.currentBackground =
+                    backgrounds[Math.floor(Math.random() * backgrounds.length)];
+            },
+        },
+    }),
+};

package/stories/PxImage.stories.js

@@ -0,0 +1,113 @@
+import PxImage from '@/components/PxImage.vue';
+import PxButton from '@/components/PxButton.vue';
+import { extractArgTypes } from '@/storybook/sb-utils.js';
+import px01jpg from '@/stories/assets/px-01.jpg';
+import px02jpg from '@/stories/assets/px-02.jpg';
+import px03jpg from '@/stories/assets/px-03.jpg';
+import px04jpg from '@/stories/assets/px-04.jpg';
+
+const localImages = [px01jpg, px02jpg, px03jpg, px04jpg];
+
+const largeImages = [
+    'https://images.unsplash.com/photo-1738969773091-abcf274f7e0a?q=80&w=3000',
+    'https://images.unsplash.com/photo-1738940251292-49709608c8aa?q=80&w=5970',
+    'https://images.unsplash.com/photo-1551692554-d83872f34d55?q=80&w=3226',
+];
+
+const images = localImages;
+
+// REFERENCE:
+//
+// https://storybook.js.org/docs/get-started/frameworks/vue3-vite?renderer=vue
+// https://storybook.js.org/docs/vue/essentials/controls#annotation?renderer=vue
+// https://storybook.js.org/docs/vue/api/argtypes#available-properties?renderer=vue
+//
+// See preview.scss for helper styles.
+
+export default {
+    title: 'PxImage',
+    component: PxImage,
+
+    // decorators: [ ... ],
+
+    // parameters: {
+    //     layout: 'fullscreen', // centered, fullscreen, padded (default)
+    // },
+
+    argTypes: {
+        ...extractArgTypes(PxImage),
+    },
+
+    args: {
+        fit: 'contain',
+        position: null,
+        cacheBuster: 'cb',
+    },
+};
+
+export const Basic = {
+    render: (args, { argTypes }) => ({
+        components: { PxImage, PxButton },
+
+        data() {
+            return {
+                args,
+                currentSourceIndex: -1,
+            };
+        },
+
+        template: `
+
+            <div class="story-aspect-16-9" style="overflow: hidden;">
+                <PxImage :src="currentSrc" v-bind="args"></PxImage>
+            </div>
+            <br>
+            <p style="max-width: 50em">NOTE: when running with cache disabled, cross fades may appear jumpy because the image will be reloaded while it's fading in. To allow easier visualization of loading (without cache disabled), we a cache buster to the urls when testing (so don't run with cache disabled).</p>
+            <div style="display: flex; gap: 1em;">
+                <PxButton @click="nextSource">Next Source</PxButton>
+                <PxButton @click="clearSource">Clear</PxButton>
+                <PxButton @click="invalidSource">Error</PxButton>
+            </div>
+
+        `,
+
+        computed: {
+            currentSrc() {
+                if (this.currentSourceIndex == -999) {
+                    return 'https://thisurldoesnotexist.com/faker-mc-fakerson-face.jpg';
+                }
+
+                if (this.currentSourceIndex == -1) {
+                    return null;
+                }
+
+                const src = images[this.currentSourceIndex];
+                const sep = src.includes('?') ? '&' : '?';
+                const cacheBuster = `${sep}${this.cacheBuster}=${Date.now()}`;
+
+                return src + cacheBuster;
+            },
+        },
+        methods: {
+            nextSource() {
+                const current = Math.max(this.currentSourceIndex, -1);
+                this.currentSourceIndex = (current + 1) % images.length;
+            },
+            clearSource() {
+                this.currentSourceIndex = -1;
+            },
+            invalidSource() {
+                this.currentSourceIndex = -999;
+            },
+        },
+    }),
+};
+
+// export const CovertBottomRight = {
+//     ...Basic,
+//     args: { fit: 'cover', position: 'bottom right' },
+// };
+
+// export const Advanced = {
+//     ...Basic,
+// };

package/storybook/sb-styles.scss

@@ -1,7 +1,5 @@
-
 @use '@thinkpixellab-public/px-styles/all' as *;
 
-
 // Update this to test font inheritance
 .sbdocs {
     font-family: sans-serif;
@@ -88,9 +86,7 @@ body {
 }
 
 .story-aspect-16-9 {
-    background-color: tomato;
     width: 100%;
-    border-radius: 8px;
     aspect-ratio: 16/9;
 }
 
@@ -124,6 +120,31 @@ body {
     padding: 1em;
 }
 
+.story-state-blue {
+    background-color: dodgerblue;
+    color: white;
+    width: 3em;
+    height: 3em;
+    border-radius: 8px;
+    padding: 1em;
+}
+
+.story-bg-orange {
+    background-color: tomato;
+}
+
+.story-bg-blue {
+    background-color: dodgerblue;
+}
+
+.story-bg-green {
+    background-color: yellowgreen;
+}
+
+.story-bg-gold {
+    background-color: gold;
+}
+
 .story-size-xs {
     width: 2em;
     height: 2em;