@flux-ui/components 3.0.0-next.0

package/README.md

@@ -0,0 +1,45 @@
+# Flux
+
+This repository contains the source code for the basic components that are used throughout our front-end projects. It
+targets Vue 3+. Please read the following instructions and checks in order to proceed.
+
+## 📦 Registry
+
+- The UI library package is available under `@flux-ui/components`.
+- The Dashboard library package is available under `@flux-ui/dashboard`.
+- The internal package is available under `@flux-ui/internals`.
+
+## ⚠️ Requirements
+
+- Install Node.js ^22
+- Install pnpm using `npm i -g pnpm`.
+- Configure a new environment variable `FONTAWESOME_NPM_AUTH_TOKEN`. This should be a valid Font Awesome private npm auth token.
+- Use `pnpm install` to install the required packages.
+- Use `pnpm dev` to start a build watcher for both targets.
+- Use `pnpm build` to build a production bundle.
+- Use `pnpm link` to link the dist folder of flux to your global node_modules.
+
+## 🪵 Git
+
+All commit messages and branches will be in English.
+
+### Branches
+
+- **Main** — Contains the latest stable release and is the exact source that is running in production.
+- **Develop** — Contains the latest staging release that is marked for deployment and is the exact source that is running on staging.
+- **Feature branches** — Any feature should have its own feature branch. Once complete, the branch should be merged into the _develop_ branch and the feature branch should be deleted.
+- **Bugfix branches** — When a bug is found, it should be fixed within a bugfix branch. Once complete the branch should be merged into the _develop_ branch and the feature branch should be deleted.
+
+### Commit messages
+
+Commit messages are bound to the following templates:
+
+- `<type>: <message> `
+- `<type>(<feature>): <message>`
+- `<type>(<feature>): <message> [<issue-number>]`
+
+#### Examples
+
+- `feat(expandable): adds header slot to expandable.`
+- `feat(expandable): adds header slot to expandable. [FLUX-123]`
+- `chore: adds vue 3 build target.`

package/package.json

@@ -0,0 +1,77 @@
+{
+    "name": "@flux-ui/components",
+    "description": "A set of opiniated UI components.",
+    "version": "3.0.0-next.0",
+    "type": "module",
+    "license": "MIT",
+    "funding": "https://github.com/sponsors/basmilius",
+    "homepage": "https://flux.bas.dev",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/basmilius/flux.git",
+        "directory": "packages/components"
+    },
+    "keywords": [
+        "ui library",
+        "component library",
+        "design system",
+        "vue",
+        "vue 3",
+        "ui",
+        "components",
+        "flux"
+    ],
+    "scripts": {
+        "build": "vue-tsc && vite build",
+        "dev": "vite build --mode dev --watch",
+        "prepublishOnly": "cp ../../README.md ."
+    },
+    "engines": {
+        "node": ">=23"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/flux.js"
+        },
+        "./style.css": "./dist/flux.css",
+        "./*": "./*"
+    },
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
+    "files": [
+        "dist",
+        "src",
+        "tsconfig.json"
+    ],
+    "main": "./dist/flux.js",
+    "module": "./dist/flux.js",
+    "types": "./dist/index.d.ts",
+    "typings": "./dist/index.d.ts",
+    "sideEffects": false,
+    "dependencies": {
+        "@basmilius/utils": "^1.12.0",
+        "@flux-ui/internals": "3.0.0-next.0",
+        "@flux-ui/types": "3.0.0-next.0",
+        "@fortawesome/fontawesome-common-types": "^6.7.2",
+        "clsx": "^2.1.1",
+        "imask": "^7.6.1",
+        "lodash-es": "^4.17.21",
+        "luxon": "^3.6.1",
+        "vue": "^3.5.13"
+    },
+    "devDependencies": {
+        "@basmilius/vite-vue-preset": "^2.5.0",
+        "@types/lodash-es": "^4.17.12",
+        "@types/luxon": "^3.6.2",
+        "@types/node": "^22.14.0",
+        "@vitejs/plugin-vue": "^5.2.3",
+        "pinia": "^3.0.1",
+        "sass-embedded": "^1.86.3",
+        "typescript": "^5.8.3",
+        "vite": "^6.2.5",
+        "vue-tsc": "^2.2.8"
+    }
+}

package/src/component/FluxAction.vue

@@ -0,0 +1,27 @@
+<template>
+    <FluxButton
+        :="{disabled, isLoading, label, href, rel, target, to, type}"
+        :css-class="$style.action"
+        :css-class-icon="$style.actionIcon"
+        :css-class-label="$style.actionLabel"
+        :class="isDestructive && $style.isDestructive"
+        :icon-leading="icon"
+        @click="$emit('click', $event)"
+        @mouseenter="$emit('mouseenter', $event)"
+        @mouseleave="$emit('mouseleave', $event)"/>
+</template>
+
+<script
+    lang="ts"
+    setup>
+    import type { FluxButtonEmits, FluxButtonProps, FluxIconName } from '@flux-ui/types';
+    import FluxButton from './FluxButton.vue';
+    import $style from '$flux/css/component/Action.module.scss';
+
+    defineEmits<FluxButtonEmits>();
+
+    defineProps<Omit<FluxButtonProps, 'iconLeading' | 'iconTrailing' | 'isFilled' | 'size'> & {
+        readonly icon?: FluxIconName;
+        readonly isDestructive?: boolean;
+    }>();
+</script>

package/src/component/FluxActionBar.vue

@@ -0,0 +1,94 @@
+<template>
+    <FluxStack
+        :class="$style.actionBar"
+        direction="horizontal"
+        :gap="9">
+        <slot name="primary"/>
+        <slot name="actionsStart"/>
+
+        <FluxSpacer/>
+
+        <slot name="actionsBeforeSearch"/>
+        <slot name="search"/>
+        <slot name="actionsAfterSearch"/>
+
+        <FluxFlyout v-if="slots.filter">
+            <template #opener="{close, open, toggle}">
+                <slot
+                    v-bind="{close, open, toggle}"
+                    name="filterOpener">
+                    <FluxButtonGroup>
+                        <FluxSecondaryButton
+                            icon-leading="filter"
+                            :label="translate('flux.filter')"
+                            @click="open"/>
+
+                        <FluxTooltip
+                            v-if="isResettable"
+                            :content="translate('flux.filterReset')">
+                            <FluxDestructiveButton
+                                icon-leading="xmark"
+                                @click="$emit('reset')"/>
+                        </FluxTooltip>
+                    </FluxButtonGroup>
+                </slot>
+            </template>
+
+            <template #default="{close, paneX, paneY, openerWidth, openerHeight}">
+                <slot
+                    name="filter"
+                    v-bind="{close, paneX, paneY, openerWidth, openerHeight}"/>
+            </template>
+        </FluxFlyout>
+
+        <slot name="actionsEnd"/>
+    </FluxStack>
+</template>
+
+<script
+    lang="ts"
+    setup>
+    import { useTranslate } from '$flux/composable/private';
+    import FluxButtonGroup from './FluxButtonGroup.vue';
+    import FluxDestructiveButton from './FluxDestructiveButton.vue';
+    import FluxFlyout from './FluxFlyout.vue';
+    import FluxSecondaryButton from './FluxSecondaryButton.vue';
+    import FluxSpacer from './FluxSpacer.vue';
+    import FluxStack from './FluxStack.vue';
+    import FluxTooltip from './FluxTooltip.vue';
+    import $style from '$flux/css/component/Action.module.scss';
+
+    defineEmits<{
+        reset: [];
+    }>();
+
+    defineProps<{
+        readonly isResettable?: boolean;
+    }>();
+
+    const slots = defineSlots<{
+        primary?(): any;
+        actionsEnd?(): any;
+        actionsStart?(): any;
+        actionsAfterSearch?(): any;
+        actionsBeforeSearch?(): any;
+        search?(): any;
+
+        filter?(props: {
+            close(): void;
+
+            readonly paneX: number;
+            readonly paneY: number;
+            readonly openerWidth: number;
+            readonly openerHeight: number;
+        }): any;
+
+        filterOpener?(props: {
+            close(): void;
+            open(): void;
+            toggle(): void;
+        }): any;
+    }>();
+
+    const translate = useTranslate();
+</script>

package/src/component/FluxActionPane.vue

@@ -0,0 +1,40 @@
+<template>
+    <FluxPane
+        :class="$style.actionPane"
+        :variant="paneVariant">
+        <slot name="base"/>
+
+        <div :class="$style.actionPaneGrid">
+            <FluxPaneBody :class="$style.actionPaneBody">
+                <slot/>
+            </FluxPaneBody>
+
+            <FluxPaneBody
+                v-if="slots.buttons"
+                :class="$style.actionPaneBody">
+                <FluxButtonStack direction="vertical">
+                    <slot name="buttons"/>
+                </FluxButtonStack>
+            </FluxPaneBody>
+        </div>
+    </FluxPane>
+</template>
+
+<script
+    lang="ts"
+    setup>
+    import FluxButtonStack from './FluxButtonStack.vue';
+    import FluxPane from './FluxPane.vue';
+    import FluxPaneBody from './FluxPaneBody.vue';
+    import $style from '$flux/css/component/Action.module.scss';
+
+    defineProps<{
+        readonly paneVariant?: 'default' | 'flat' | 'well';
+    }>();
+
+    const slots = defineSlots<{
+        default?(): any;
+        buttons?(): any;
+        base?(): any;
+    }>();
+</script>

package/src/component/FluxActions.vue

@@ -0,0 +1,27 @@
+<template>
+    <FluxStack
+        ref="element"
+        direction="horizontal"
+        :gap="1"
+        tag="nav">
+        <slot/>
+    </FluxStack>
+</template>
+
+<script
+    lang="ts"
+    setup>
+    import { useFocusZone } from '@flux-ui/internals';
+    import { useTemplateRef } from 'vue';
+    import FluxStack from './FluxStack.vue';
+
+    defineSlots<{
+        default(): any;
+    }>();
+
+    const elementRef = useTemplateRef('element');
+
+    useFocusZone(elementRef, {
+        direction: 'horizontal'
+    });
+</script>

package/src/component/FluxAlert.vue

@@ -0,0 +1,37 @@
+<template>
+    <FluxPane>
+        <FluxPaneHeader
+            :icon="alert.icon"
+            :title="alert.title"/>
+
+        <FluxPaneBody v-html="alert.message"/>
+
+        <FluxPaneFooter>
+            <FluxSpacer/>
+
+            <FluxPrimaryButton
+                icon-leading="circle-check"
+                :label="translate('flux.ok')"
+                @click="alert.onClose()"/>
+        </FluxPaneFooter>
+    </FluxPane>
+</template>
+
+<script
+    lang="ts"
+    setup>
+    import type { FluxAlertObject } from '@flux-ui/types';
+    import { useTranslate } from '$flux/composable/private';
+    import FluxPane from './FluxPane.vue';
+    import FluxPaneBody from './FluxPaneBody.vue';
+    import FluxPaneFooter from './FluxPaneFooter.vue';
+    import FluxPaneHeader from './FluxPaneHeader.vue';
+    import FluxPrimaryButton from './FluxPrimaryButton.vue';
+    import FluxSpacer from './FluxSpacer.vue';
+
+    defineProps<{
+        readonly alert: FluxAlertObject;
+    }>();
+
+    const translate = useTranslate();
+</script>

package/src/component/FluxAnimatedColors.vue

@@ -0,0 +1,141 @@
+<template>
+    <canvas
+        ref="canvas"
+        :class="$style.animatedColors"/>
+</template>
+
+<script
+    lang="ts"
+    setup>
+    import { mulberry32 } from '@basmilius/utils';
+    import { useComponentId } from '@flux-ui/internals';
+    import { computed, onBeforeUnmount, onMounted, ref, unref, useTemplateRef, watch } from 'vue';
+    import $style from '$flux/css/component/Visual.module.scss';
+
+    type Polygon = [number, number, string, PolygonPoint[]];
+    type PolygonPoint = [number, number, number];
+
+    const {
+        colors,
+        incrementor = 1,
+        opacity = .5,
+        seed
+    } = defineProps<{
+        readonly colors?: string[];
+        readonly incrementor?: number;
+        readonly opacity?: number;
+        readonly seed?: number;
+    }>();
+
+    const canvasRef = useTemplateRef('canvas');
+    const componentId = useComponentId();
+
+    const contextRef = ref<CanvasRenderingContext2D>();
+    const animationFrame = ref(0);
+    const tick = ref(0);
+
+    const polygons = computed(() => {
+        if (!colors || colors.length === 0) {
+            return [];
+        }
+
+        const mulberry = mulberry32(seed ?? unref(componentId));
+        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;
+    });
+
+    onMounted(() => schedule());
+    onBeforeUnmount(() => cancel());
+
+    function cancel(): void {
+        cancelAnimationFrame(animationFrame.value);
+    }
+
+    function schedule(): void {
+        animationFrame.value = requestAnimationFrame(update);
+        tick.value += incrementor;
+    }
+
+    function update(): void {
+        const context = unref(contextRef);
+        const shapes = unref(polygons);
+
+        if (!context || shapes.length === 0) {
+            return;
+        }
+
+        const width = context.canvas.offsetWidth;
+        const height = context.canvas.offsetHeight;
+        context.canvas.width = width;
+        context.canvas.height = height;
+
+        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();
+        }
+
+        schedule();
+    }
+
+    watch(canvasRef, canvas => {
+        if (!canvas) {
+            contextRef.value = undefined;
+            return;
+        }
+
+        contextRef.value = canvas.getContext('2d', {
+            alpha: true,
+            colorSpace: 'display-p3'
+        })!;
+    }, {immediate: true});
+
+    watch(polygons, () => {
+        cancel();
+        schedule();
+    });
+</script>

package/src/component/FluxAspectRatio.vue

@@ -0,0 +1,21 @@
+<template>
+    <div
+        :class="$style.aspectRatio"
+        :style="{aspectRatio}">
+        <slot/>
+    </div>
+</template>
+
+<script
+    lang="ts"
+    setup>
+    import $style from '$flux/css/component/Layout.module.scss';
+
+    defineProps<{
+        aspectRatio: number;
+    }>();
+
+    defineSlots<{
+        default(): any;
+    }>();
+</script>

package/src/component/FluxAutoGrid.vue

@@ -0,0 +1,27 @@
+<template>
+    <div
+        :class="$style.autoGrid"
+        :style="{
+            gap: `${gap}px`,
+            '--min-column-width': minColumnWidth
+        }">
+        <slot/>
+    </div>
+</template>
+
+<script
+    lang="ts"
+    setup>
+    import $style from '$flux/css/component/Layout.module.scss';
+
+    const {
+        gap = 30
+    } = defineProps<{
+        readonly gap?: number;
+        readonly minColumnWidth: number;
+    }>();
+
+    defineSlots<{
+        default(): any;
+    }>();
+</script>

package/src/component/FluxAvatar.vue

@@ -0,0 +1,119 @@
+<template>
+    <FluxPressable
+        :class="clsx(
+            !status && $style.avatar,
+            !!status && $style.statusAvatar,
+            type !== 'none' && $style.avatarClickable
+        )"
+        :style="{
+            '--color': color,
+            fontSize: size && `${size}px`
+        }"
+        :component-type="type"
+        role="img"
+        :aria-label="alt"
+        :tabindex="tabindex"
+        :href="href"
+        :rel="rel"
+        :target="target"
+        :to="to"
+        @click="$emit('click', $event)"
+        @mouseenter="$emit('mouseenter', $event)"
+        @mouseleave="$emit('mouseleave', $event)">
+        <img
+            v-if="src"
+            :class="$style.avatarImage"
+            :alt="alt"
+            :src="src"/>
+
+        <div
+            v-else
+            :class="fallback === 'colorized' ? $style.avatarFallbackColorized : $style.avatarFallbackNeutral">
+            <span v-if="fallbackInitials">
+                {{ fallbackInitials }}
+            </span>
+
+            <FluxIcon
+                v-else-if="fallbackIcon"
+                :name="fallbackIcon"/>
+        </div>
+
+        <FluxFadeTransition>
+            <div
+                v-if="isLoading"
+                :class="$style.avatarLoading">
+                <FluxSpinner/>
+            </div>
+        </FluxFadeTransition>
+
+        <div
+            v-if="status"
+            :class="STATUS_CLASS_MAP[status]"/>
+    </FluxPressable>
+</template>
+
+<script
+    lang="ts"
+    setup>
+    import { amber600, blue600, cyan600, emerald600, fuchsia600, green600, indigo600, lime600, orange600, pink600, purple600, red600, rose600, sky600, teal600, violet600, yellow600 } from '@flux-ui/internals';
+    import type { FluxButtonEmits, FluxColor, FluxIconName, FluxPressableType, FluxTo } from '@flux-ui/types';
+    import { clsx } from 'clsx';
+    import { computed, unref } from 'vue';
+    import { FluxFadeTransition } from '$flux/transition';
+    import FluxIcon from './FluxIcon.vue';
+    import FluxPressable from './FluxPressable.vue';
+    import FluxSpinner from './FluxSpinner.vue';
+    import $style from '$flux/css/component/Avatar.module.scss';
+
+    const STATUS_CLASS_MAP = {
+        gray: $style.avatarStatusGray,
+        primary: $style.avatarStatusPrimary,
+        danger: $style.avatarStatusDanger,
+        info: $style.avatarStatusInfo,
+        success: $style.avatarStatusSuccess,
+        warning: $style.avatarStatusWarning
+    } as const;
+
+    defineEmits<FluxButtonEmits>();
+
+    const {
+        fallback = 'colorized',
+        fallbackColors = [lime600, green600, emerald600, teal600, cyan600, sky600, blue600, indigo600, violet600, purple600, fuchsia600, pink600, rose600, red600, orange600, amber600, yellow600],
+        fallbackIcon = 'user',
+        fallbackInitials,
+        type = 'none'
+    } = defineProps<{
+        readonly alt?: string;
+        readonly fallback?: 'colorized' | 'neutral';
+        readonly fallbackColors?: string[];
+        readonly fallbackIcon?: FluxIconName;
+        readonly fallbackInitials?: string;
+        readonly isLoading?: boolean;
+        readonly size?: number;
+        readonly src?: string;
+        readonly status?: FluxColor;
+        readonly type?: FluxPressableType;
+        readonly tabindex?: string | number;
+        readonly href?: string;
+        readonly rel?: string;
+        readonly target?: string;
+        readonly to?: FluxTo;
+    }>();
+
+    const color = computed(() => fallbackColors[unref(colorSeed) % fallbackColors.length]);
+    const colorSeed = computed(() => {
+        let seed = 6;
+
+        if (fallbackInitials) {
+            for (let i = 0; i < fallbackInitials.length; ++i) {
+                seed ^= fallbackInitials.charCodeAt(i);
+            }
+        } else if (fallbackIcon) {
+            for (let i = 0; i < fallbackIcon.length; ++i) {
+                seed ^= fallbackIcon.charCodeAt(i);
+            }
+        }
+
+        return seed;
+    });
+</script>