@flux-ui/visuals 0.0.0

package/dist/types.d.ts

@@ -0,0 +1,13 @@
+declare module '*.module.css' {
+    const content: Record<string, string>;
+    export default content;
+}
+
+declare module '*.module.scss' {
+    const content: Record<string, string>;
+    export default content;
+}
+
+declare module '*.svg' {
+    export = string;
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+    "name": "@flux-ui/visuals",
+    "description": "Visual effect components for the Flux UI library.",
+    "version": "0.0.0",
+    "type": "module",
+    "license": "MIT",
+    "funding": "https://github.com/sponsors/basmilius",
+    "homepage": "https://flux-ui.dev",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/basmilius/flux.git",
+        "directory": "packages/visuals"
+    },
+    "keywords": [
+        "ui library",
+        "component library",
+        "design system",
+        "vue",
+        "vue 3",
+        "ui",
+        "components",
+        "flux",
+        "visuals"
+    ],
+    "scripts": {
+        "build": "vue-tsc && vite build",
+        "dev": "vite build --watch --mode development"
+    },
+    "engines": {
+        "node": ">=23"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./style.css": "./dist/index.css"
+    },
+    "publishConfig": {
+        "access": "public",
+        "provenance": false
+    },
+    "files": [
+        "dist",
+        "src"
+    ],
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "sideEffects": false,
+    "dependencies": {
+        "@basmilius/common": "^3.45.0",
+        "@basmilius/utils": "^3.45.0",
+        "@flux-ui/internals": "workspace:*",
+        "clsx": "^2.1.1",
+        "rough-notation": "^0.5.1"
+    },
+    "peerDependencies": {
+        "vue": "^3.6.0-beta.17"
+    },
+    "devDependencies": {
+        "@basmilius/vite-preset": "^3.45.0",
+        "@types/node": "^26.0.1",
+        "@vitejs/plugin-vue": "^6.0.7",
+        "@vue/tsconfig": "^0.9.1",
+        "sass-embedded": "^1.100.0",
+        "typescript": "^6.0.3",
+        "vite": "^8.1.0",
+        "vue-tsc": "^3.3.5"
+    }
+}

package/src/component/FluxVisualAnimatedColors.vue

@@ -0,0 +1,187 @@
+<template>
+    <canvas
+        ref="canvas"
+        aria-hidden="true"
+        :class="$style.animatedColors"/>
+</template>
+
+<script
+    lang="ts"
+    setup>
+    import { useComponentId } from '@basmilius/common';
+    import { mulberry32 } from '@basmilius/utils';
+    import { prefersReducedMotion, useInView } from '@flux-ui/internals';
+    import { computed, onBeforeUnmount, ref, unref, useTemplateRef, watch } from 'vue';
+    import $style from '~flux/visuals/css/component/Visual.module.scss';
+
+    type Polygon = [number, number, string, PolygonPoint[]];
+    type PolygonPoint = [number, number, number];
+
+    const {
+        colors,
+        incrementor = 1,
+        opacity = .5,
+        seed,
+        static: isStatic
+    } = defineProps<{
+        readonly colors?: string[];
+        readonly incrementor?: number;
+        readonly opacity?: number;
+        readonly seed?: number;
+        readonly static?: boolean;
+    }>();
+
+    const canvasRef = useTemplateRef('canvas');
+    const componentId = useComponentId();
+    const inView = useInView(canvasRef, {initial: true});
+
+    const contextRef = ref<CanvasRenderingContext2D>();
+    const animationFrame = ref(0);
+    const tick = ref(0);
+    const size = ref<{ width: number; height: number; } | null>(null);
+
+    const reducedMotion = prefersReducedMotion();
+
+    const polygons = computed(() => {
+        if (!colors || colors.length === 0) {
+            return [];
+        }
+
+        const mulberry = mulberry32(seed ?? componentId.value);
+        const polygons: Polygon[] = [];
+
+        for (const color of colors) {
+            const localMulberry = mulberry.fork();
+
+            const x = colors.length === 1 ? .5 : localMulberry.next();
+            const y = colors.length === 1 ? .5 : localMulberry.next();
+            const count = Math.round(localMulberry.nextBetween(6, 9));
+            const points: PolygonPoint[] = [];
+
+            for (let p = 0; p < count; ++p) {
+                points.push([
+                    localMulberry.next(),
+                    localMulberry.next(),
+                    localMulberry.next()
+                ]);
+            }
+
+            polygons.push([x, y, color, points]);
+        }
+
+        return polygons;
+    });
+
+    onBeforeUnmount(() => cancel());
+
+    function cancel(): void {
+        cancelAnimationFrame(animationFrame.value);
+        animationFrame.value = 0;
+    }
+
+    function schedule(): void {
+        animationFrame.value = requestAnimationFrame(update);
+        tick.value += incrementor;
+    }
+
+    function update(): void {
+        render();
+
+        if (!isStatic && !reducedMotion && unref(inView)) {
+            schedule();
+        } else {
+            animationFrame.value = 0;
+        }
+    }
+
+    function render(): void {
+        const context = unref(contextRef);
+        const shapes = unref(polygons);
+        const dimensions = unref(size);
+
+        if (!context || shapes.length === 0 || !dimensions) {
+            return;
+        }
+
+        const {width, height} = dimensions;
+        const widthBasedOpacity = Math.min(1, Math.max(.15, 360 / width));
+
+        context.globalAlpha = opacity * widthBasedOpacity;
+        context.globalCompositeOperation = 'screen';
+        context.clearRect(0, 0, width, height);
+
+        for (const [tx, ty, color, shape] of shapes) {
+            context.save();
+            context.translate(tx * width, ty * height);
+            context.beginPath();
+            context.fillStyle = color;
+
+            for (let i = 0; i < shape.length; ++i) {
+                let [x, y, m] = shape[i];
+
+                x = Math.cos(x * Math.PI * 2 + tick.value / (m * 200 + 300)) * (width * .8);
+                y = Math.sin(y * Math.PI * 2 + tick.value / (m * 100 + 300)) * (height * .8);
+
+                if (i === 0) {
+                    context.moveTo(x, y);
+                } else {
+                    context.lineTo(x, y);
+                }
+            }
+
+            context.closePath();
+            context.fill();
+            context.restore();
+        }
+    }
+
+    function restart(): void {
+        cancel();
+
+        if (isStatic || reducedMotion || !unref(inView)) {
+            render();
+            return;
+        }
+
+        schedule();
+    }
+
+    watch(canvasRef, (canvas, _, onCleanup) => {
+        if (!canvas) {
+            contextRef.value = undefined;
+            size.value = null;
+            return;
+        }
+
+        contextRef.value = canvas.getContext('2d', {
+            alpha: true,
+            colorSpace: 'display-p3'
+        })!;
+
+        if (typeof ResizeObserver === 'undefined') {
+            size.value = {width: canvas.offsetWidth, height: canvas.offsetHeight};
+            canvas.width = canvas.offsetWidth;
+            canvas.height = canvas.offsetHeight;
+            return;
+        }
+
+        const observer = new ResizeObserver(() => {
+            const width = canvas.offsetWidth;
+            const height = canvas.offsetHeight;
+
+            if (!width || !height || (size.value?.width === width && size.value?.height === height)) {
+                return;
+            }
+
+            canvas.width = width;
+            canvas.height = height;
+            size.value = {width, height};
+        });
+
+        observer.observe(canvas);
+
+        onCleanup(() => observer.disconnect());
+    }, {immediate: true});
+
+    watch([polygons, () => opacity, size, inView], () => restart());
+</script>

package/src/component/FluxVisualAttention.vue

@@ -0,0 +1,86 @@
+<script lang="ts">
+    import { flattenVNodeTree, prefersReducedMotion } from '@flux-ui/internals';
+    import { clsx } from 'clsx';
+    import { cloneVNode, defineComponent, Fragment, h, onBeforeUnmount, ref, watch, type PropType } from 'vue';
+    import $style from '~flux/visuals/css/component/Attention.module.scss';
+
+    type AttentionEffect = 'pulse' | 'shake' | 'bounce' | 'tada';
+
+    export default defineComponent({
+        inheritAttrs: false,
+        props: {
+            duration: {default: 700, type: Number},
+            effect: {default: 'pulse', type: String as PropType<AttentionEffect>},
+            trigger: {default: undefined, type: null as unknown as PropType<unknown>}
+        },
+        emits: {
+            finished: () => true
+        },
+        setup(props, {attrs, emit, expose, slots}) {
+            const EFFECT_CLASSES: Record<AttentionEffect, string> = {
+                pulse: $style.pulse,
+                shake: $style.shake,
+                bounce: $style.bounce,
+                tada: $style.tada
+            };
+
+            const isPlaying = ref(false);
+
+            let restartFrame = 0;
+
+            // Drop the effect class and re-add it two frames later so the animation
+            // restarts cleanly, even when the same effect is played back to back.
+            function play(): void {
+                if (prefersReducedMotion()) {
+                    emit('finished');
+                    return;
+                }
+
+                cancelAnimationFrame(restartFrame);
+                isPlaying.value = false;
+
+                restartFrame = requestAnimationFrame(() => {
+                    restartFrame = requestAnimationFrame(() => {
+                        isPlaying.value = true;
+                    });
+                });
+            }
+
+            function onAnimationEnd(event: AnimationEvent): void {
+                if (event.target !== event.currentTarget) {
+                    return;
+                }
+
+                isPlaying.value = false;
+                emit('finished');
+            }
+
+            watch(() => props.trigger, () => {
+                play();
+            });
+
+            onBeforeUnmount(() => {
+                cancelAnimationFrame(restartFrame);
+            });
+
+            expose({
+                play
+            });
+
+            return () => h(
+                Fragment,
+                flattenVNodeTree(slots.default?.() ?? []).map(vnode => cloneVNode(vnode, {
+                    ...attrs,
+                    class: clsx(
+                        attrs.class as string,
+                        isPlaying.value && EFFECT_CLASSES[props.effect]
+                    ),
+                    style: {
+                        '--attention-duration': props.duration
+                    },
+                    onAnimationend: onAnimationEnd
+                }))
+            );
+        }
+    });
+</script>

package/src/component/FluxVisualBorderBeam.vue

@@ -0,0 +1,171 @@
+<template>
+    <div
+        ref="wrapper"
+        :class="clsx(
+            $style.borderBeam,
+            VARIANT_CLASSES[variant],
+            $style[colorVariant],
+            isActive && !isFading && $style.isActive,
+            isFading && $style.isFading,
+            isPaused && $style.isPaused,
+            isStatic && $style.isStatic
+        )"
+        :style="style"
+        @animationend="onAnimationEnd">
+        <slot/>
+
+        <div
+            aria-hidden="true"
+            :class="$style.bloom"/>
+    </div>
+</template>
+
+<script
+    lang="ts"
+    setup>
+    import { useInView } from '@flux-ui/internals';
+    import { clsx } from 'clsx';
+    import { computed, ref, unref, useTemplateRef, watch } from 'vue';
+    import { useBorderBeamPulse, type BorderBeamVariant } from '~flux/visuals/composable/private';
+    import $style from '~flux/visuals/css/component/BorderBeam.module.scss';
+
+    const emit = defineEmits<{
+        activate: [];
+        deactivate: [];
+    }>();
+
+    const {
+        active = true,
+        brightness,
+        colorVariant = 'colorful',
+        duration,
+        hueRange = 30,
+        radius,
+        saturation,
+        staticColors = false,
+        strength = 1,
+        variant = 'md'
+    } = defineProps<{
+        readonly active?: boolean;
+        readonly brightness?: number;
+        readonly colorVariant?: 'colorful' | 'mono' | 'ocean' | 'sunset';
+        readonly duration?: number;
+        readonly hueRange?: number;
+        readonly radius?: string | number;
+        readonly saturation?: number;
+        readonly staticColors?: boolean;
+        readonly strength?: number;
+        readonly variant?: BorderBeamVariant;
+    }>();
+
+    defineSlots<{
+        default(): any;
+    }>();
+
+    const VARIANT_CLASSES: Record<BorderBeamVariant, string> = {
+        'sm': $style.sm,
+        'md': $style.md,
+        'line': $style.line,
+        'pulse-inner': $style.pulseInner,
+        'pulse-outside': $style.pulseOutside
+    };
+
+    const wrapperRef = useTemplateRef('wrapper');
+    const inView = useInView(wrapperRef, {initial: true, rootMargin: '256px'});
+
+    const isActive = ref(active);
+    const isFading = ref(false);
+    const glowScale = ref<{ x: number; y: number; } | null>(null);
+
+    const isPulse = computed(() => variant === 'pulse-inner' || variant === 'pulse-outside');
+    const isStatic = computed(() => staticColors || colorVariant === 'mono');
+    const isPaused = computed(() => isActive.value && !isFading.value && !inView.value);
+    const resolvedDuration = computed(() => duration ?? (variant === 'line' ? 3.1 : isPulse.value ? 2.3 : 1.96));
+
+    const style = computed(() => ({
+        '--beam-brightness': brightness,
+        '--beam-duration': resolvedDuration.value,
+        '--beam-glow-sx': glowScale.value?.x,
+        '--beam-glow-sy': glowScale.value?.y,
+        '--beam-hue-range': variant === 'line' ? Math.min(hueRange, 13) : hueRange,
+        '--beam-radius': typeof radius === 'number' ? `${radius}px` : radius,
+        '--beam-saturation': saturation,
+        '--beam-strength': Math.max(0, Math.min(1, strength))
+    }));
+
+    useBorderBeamPulse({
+        duration: resolvedDuration,
+        elementRef: wrapperRef,
+        enabled: computed(() => (isActive.value || isFading.value) && inView.value),
+        staticColors: isStatic,
+        variant: computed(() => variant)
+    });
+
+    watch(() => active, value => {
+        if (value) {
+            // Also covers re-activating while the fade-out is still running: cancel the
+            // fade, otherwise its animationend would turn the beam off for good.
+            isFading.value = false;
+            isActive.value = true;
+        } else if (isActive.value && !isFading.value) {
+            isFading.value = true;
+        }
+    });
+
+    // The pulse-outside glow geometry is authored in fixed pixels for a reference
+    // element of ~350x140; measure the wrapped element and scale the glow per-axis
+    // so the halo fits any component it's applied to.
+    watch([wrapperRef, () => variant], (_, __, onCleanup) => {
+        glowScale.value = null;
+
+        const wrapper = unref(wrapperRef);
+
+        if (!wrapper || variant !== 'pulse-outside' || typeof ResizeObserver === 'undefined') {
+            return;
+        }
+
+        const child = wrapper.firstElementChild;
+
+        if (!child || !(child instanceof HTMLElement)) {
+            return;
+        }
+
+        const clamp = (value: number): number => Math.max(.35, Math.min(4, value));
+
+        const measure = (): void => {
+            const rect = child.getBoundingClientRect();
+
+            if (!rect.width || !rect.height) {
+                return;
+            }
+
+            const x = +clamp(rect.width / 350).toFixed(3);
+            const y = +clamp(rect.height / 140).toFixed(3);
+
+            if (glowScale.value?.x !== x || glowScale.value?.y !== y) {
+                glowScale.value = {x, y};
+            }
+        };
+
+        measure();
+
+        const observer = new ResizeObserver(measure);
+        observer.observe(child);
+
+        onCleanup(() => observer.disconnect());
+    }, {immediate: true});
+
+    function onAnimationEnd(event: AnimationEvent): void {
+        if (event.target !== event.currentTarget) {
+            return;
+        }
+
+        if (isFading.value) {
+            isActive.value = false;
+            isFading.value = false;
+            emit('deactivate');
+        } else if (isActive.value) {
+            emit('activate');
+        }
+    }
+</script>

package/src/component/FluxVisualBorderShine.vue

@@ -0,0 +1,36 @@
+<script lang="ts">
+    import { flattenVNodeTree, orange600, pink600, purple600 } from '@flux-ui/internals';
+    import { clsx } from 'clsx';
+    import { cloneVNode, defineComponent, Fragment, h, type PropType } from 'vue';
+    import $style from '~flux/visuals/css/component/Visual.module.scss';
+
+    export default defineComponent({
+        inheritAttrs: false,
+        props: {
+            colors: {default: [purple600, 'transparent', orange600, 'transparent', pink600, 'transparent', purple600], type: Array as PropType<string[]>},
+            duration: {default: 9, type: Number},
+            offset: {default: 1, type: Number},
+            radius: {default: undefined, type: [String, Number] as PropType<string | number>},
+            width: {default: 2, type: Number}
+        },
+        setup(props, {attrs, slots}) {
+            return () => h(
+                Fragment,
+                flattenVNodeTree(slots.default?.() ?? []).map(vnode => cloneVNode(vnode, {
+                    ...attrs,
+                    class: clsx(
+                        attrs.class as string,
+                        $style.borderShine
+                    ),
+                    style: {
+                        '--shine-colors': props.colors.join(', '),
+                        '--shine-duration': props.duration,
+                        '--shine-offset': props.offset,
+                        '--shine-radius': typeof props.radius === 'number' ? `${props.radius}px` : props.radius,
+                        '--shine-width': props.width
+                    }
+                }))
+            );
+        }
+    });
+</script>

package/src/component/FluxVisualDotPattern.vue

@@ -0,0 +1,119 @@
+<template>
+    <svg
+        ref="root"
+        aria-hidden="true"
+        :class="$style.dotPattern">
+        <defs>
+            <pattern
+                :id="id"
+                :width="width"
+                :height="height"
+                patternContentUnits="userSpaceOnUse"
+                patternUnits="userSpaceOnUse"
+                :x="-1"
+                :y="-1">
+                <circle
+                    :r="cr"
+                    :cx="width / 2 - cx"
+                    :cy="height / 2 - cy"/>
+            </pattern>
+
+            <pattern
+                v-if="glow"
+                :id="glowId"
+                :width="width"
+                :height="height"
+                patternContentUnits="userSpaceOnUse"
+                patternUnits="userSpaceOnUse"
+                :x="-1"
+                :y="-1">
+                <circle
+                    :class="$glow.glowDot"
+                    :r="cr"
+                    :cx="width / 2 - cx"
+                    :cy="height / 2 - cy"/>
+            </pattern>
+        </defs>
+
+        <rect
+            width="100%"
+            height="100%"
+            stroke-width="0"
+            :fill="`url(#${id})`"/>
+
+        <rect
+            v-if="glow"
+            :class="[$glow.glowLayer, active && $glow.isActive]"
+            width="100%"
+            height="100%"
+            stroke-width="0"
+            :fill="`url(#${glowId})`"/>
+    </svg>
+</template>
+
+<script
+    lang="ts"
+    setup>
+    import { ref, unref, useId, useTemplateRef, watch } from 'vue';
+    import $glow from '~flux/visuals/css/component/PatternGlow.module.scss';
+    import $style from '~flux/visuals/css/component/Visual.module.scss';
+
+    const {
+        width = 16,
+        height = 16,
+        cr = 1,
+        cx = 1,
+        cy = 1,
+        glow = false
+    } = defineProps<{
+        readonly width?: number;
+        readonly height?: number;
+        readonly cr?: number;
+        readonly cx?: number;
+        readonly cy?: number;
+        readonly glow?: boolean;
+    }>();
+
+    const id = useId();
+    const glowId = `${id}-glow`;
+    const rootRef = useTemplateRef<SVGSVGElement>('root');
+    const active = ref(false);
+
+    // The pattern svg has pointer-events: none, so the cursor is tracked on the
+    // parent scroll/overflow container instead. The position is written straight
+    // to CSS custom properties to avoid a re-render on every pointermove.
+    watch([rootRef, () => glow], (_, __, onCleanup) => {
+        const root = unref(rootRef);
+
+        if (!glow || !root || !root.parentElement) {
+            return;
+        }
+
+        const parent = root.parentElement;
+
+        const onPointerMove = (event: PointerEvent): void => {
+            const rect = parent.getBoundingClientRect();
+            root.style.setProperty('--pattern-glow-x', `${event.clientX - rect.left}px`);
+            root.style.setProperty('--pattern-glow-y', `${event.clientY - rect.top}px`);
+        };
+
+        const onPointerEnter = (): void => {
+            active.value = true;
+        };
+
+        const onPointerLeave = (): void => {
+            active.value = false;
+        };
+
+        parent.addEventListener('pointermove', onPointerMove, {passive: true});
+        parent.addEventListener('pointerenter', onPointerEnter);
+        parent.addEventListener('pointerleave', onPointerLeave);
+
+        onCleanup(() => {
+            active.value = false;
+            parent.removeEventListener('pointermove', onPointerMove);
+            parent.removeEventListener('pointerenter', onPointerEnter);
+            parent.removeEventListener('pointerleave', onPointerLeave);
+        });
+    }, {immediate: true});
+</script>