@flux-ui/visuals 0.0.0

package/README.md

@@ -0,0 +1,32 @@
+# `@flux-ui/visuals`
+
+Visual effect components for [Flux UI](https://flux-ui.dev).
+
+Decorative, animated building blocks (border beams, patterns, animated colors, slot text, and more) that layer on top of the Flux design system.
+
+## Highlights
+
+- Purely decorative, `aria-hidden` visual effects that respect `prefers-reduced-motion`.
+- Same CSS Modules and naming conventions as `@flux-ui/components`.
+- Relies on the Flux theme tokens (`--gray-*`, `--radius`), so load `@flux-ui/components` styles alongside it.
+
+## ⭐️ Prerequisites
+
+- Bun >= 1.2.13
+- Node >= 23
+
+## 🚀 Getting started
+
+1. Make sure the Flux monorepo is checked out.
+2. Run `bun install` in the project root.
+3. Run `bun run --cwd packages/visuals build` to build the package (runs `vue-tsc` then `vite build`).
+4. To link Flux Visuals globally with Bun, run `bun link --cwd packages/visuals`.
+    - In another project, use `link:@flux-ui/visuals` as the dependency version in `package.json`.
+
+## 📦 Sibling packages
+
+- [`@flux-ui/components`](../components)
+- [`@flux-ui/types`](../types)
+- [`@flux-ui/internals`](../internals)
+- [`@flux-ui/application`](../application)
+- [`@flux-ui/statistics`](../statistics)

package/dist/component/FluxVisualAnimatedColors.vue.d.ts

@@ -0,0 +1,10 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    readonly colors?: string[];
+    readonly incrementor?: number;
+    readonly opacity?: number;
+    readonly seed?: number;
+    readonly static?: boolean;
+};
+declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/component/FluxVisualAttention.vue.d.ts

@@ -0,0 +1,40 @@
+import { PropType, DefineComponent, ExtractPropTypes, VNode, RendererNode, RendererElement, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type AttentionEffect = 'pulse' | 'shake' | 'bounce' | 'tada';
+declare const _default: DefineComponent<ExtractPropTypes<{
+    duration: {
+        default: number;
+        type: NumberConstructor;
+    };
+    effect: {
+        default: string;
+        type: PropType<AttentionEffect>;
+    };
+    trigger: {
+        default: any;
+        type: PropType<unknown>;
+    };
+}>, () => VNode<RendererNode, RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+    finished: () => true;
+}, string, PublicProps, Readonly< ExtractPropTypes<{
+    duration: {
+        default: number;
+        type: NumberConstructor;
+    };
+    effect: {
+        default: string;
+        type: PropType<AttentionEffect>;
+    };
+    trigger: {
+        default: any;
+        type: PropType<unknown>;
+    };
+}>> & Readonly<{
+    onFinished?: () => any;
+}>, {
+    duration: number;
+    effect: AttentionEffect;
+    trigger: any;
+}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/component/FluxVisualBorderBeam.vue.d.ts

@@ -0,0 +1,31 @@
+import { BorderBeamVariant } from '../composable/private';
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    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;
+};
+type __VLS_Slots = {
+    default(): any;
+};
+declare const __VLS_base: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+    activate: () => any;
+    deactivate: () => any;
+}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onActivate?: () => any;
+    onDeactivate?: () => any;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/component/FluxVisualBorderShine.vue.d.ts

@@ -0,0 +1,53 @@
+import { PropType, DefineComponent, ExtractPropTypes, VNode, RendererNode, RendererElement, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+declare const _default: DefineComponent<ExtractPropTypes<{
+    colors: {
+        default: string[];
+        type: PropType<string[]>;
+    };
+    duration: {
+        default: number;
+        type: NumberConstructor;
+    };
+    offset: {
+        default: number;
+        type: NumberConstructor;
+    };
+    radius: {
+        default: any;
+        type: PropType<string | number>;
+    };
+    width: {
+        default: number;
+        type: NumberConstructor;
+    };
+}>, () => VNode<RendererNode, RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly< ExtractPropTypes<{
+    colors: {
+        default: string[];
+        type: PropType<string[]>;
+    };
+    duration: {
+        default: number;
+        type: NumberConstructor;
+    };
+    offset: {
+        default: number;
+        type: NumberConstructor;
+    };
+    radius: {
+        default: any;
+        type: PropType<string | number>;
+    };
+    width: {
+        default: number;
+        type: NumberConstructor;
+    };
+}>> & Readonly<{}>, {
+    colors: string[];
+    width: number;
+    duration: number;
+    radius: string | number;
+    offset: number;
+}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/component/FluxVisualDotPattern.vue.d.ts

@@ -0,0 +1,11 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    readonly width?: number;
+    readonly height?: number;
+    readonly cr?: number;
+    readonly cx?: number;
+    readonly cy?: number;
+    readonly glow?: boolean;
+};
+declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/component/FluxVisualFlickeringGrid.vue.d.ts

@@ -0,0 +1,10 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    readonly color?: string;
+    readonly flickerChance?: number;
+    readonly gap?: number;
+    readonly maxOpacity?: number;
+    readonly size?: number;
+};
+declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/component/FluxVisualGridPattern.vue.d.ts

@@ -0,0 +1,10 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    readonly width?: number;
+    readonly height?: number;
+    readonly strokeDasharray?: number | string;
+    readonly squares?: Array<[x: number, y: number]>;
+    readonly glow?: boolean;
+};
+declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/component/FluxVisualHighlighter.vue.d.ts

@@ -0,0 +1,36 @@
+import { HighlighterVariant } from '../composable/private';
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    readonly variant?: HighlighterVariant;
+    readonly color?: string;
+    readonly strokeWidth?: number;
+    readonly animationDuration?: number;
+    readonly iterations?: number;
+    readonly padding?: number;
+    readonly multiline?: boolean;
+    readonly whenInView?: boolean;
+};
+type __VLS_Slots = {
+    default(): any;
+};
+declare function show(): void;
+declare function hide(): void;
+declare function replay(): void;
+declare const __VLS_base: DefineComponent<__VLS_Props, {
+    hide: typeof hide;
+    replay: typeof replay;
+    show: typeof show;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+    hidden: () => any;
+    shown: () => any;
+}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onHidden?: () => any;
+    onShown?: () => any;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/component/FluxVisualHighlighterGroup.vue.d.ts

@@ -0,0 +1,13 @@
+import { HighlighterGroupProps } from '../composable/private';
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Slots = {
+    default(): any;
+};
+declare const __VLS_base: DefineComponent<HighlighterGroupProps, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<HighlighterGroupProps> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/component/FluxVisualNoise.vue.d.ts

@@ -0,0 +1,9 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type NoiseBlendMode = 'normal' | 'multiply' | 'screen' | 'overlay' | 'soft-light' | 'plus-lighter';
+type __VLS_Props = {
+    readonly animated?: boolean;
+    readonly blend?: NoiseBlendMode;
+    readonly opacity?: number;
+};
+declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/component/FluxVisualNumberFlow.vue.d.ts

@@ -0,0 +1,14 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type NumberFlowEasingKeyword = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
+type NumberFlowEasingFunction = (t: number) => number;
+type NumberFlowEasing = NumberFlowEasingKeyword | `cubic-bezier(${string})` | NumberFlowEasingFunction;
+type __VLS_Props = {
+    readonly value: number;
+    readonly animateOnMount?: boolean;
+    readonly duration?: number;
+    readonly easing?: NumberFlowEasing;
+    readonly format?: Intl.NumberFormatOptions;
+    readonly locale?: string;
+};
+declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/component/FluxVisualPing.vue.d.ts

@@ -0,0 +1,8 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    readonly color?: 'gray' | 'primary' | 'danger' | 'info' | 'success' | 'warning';
+    readonly size?: number;
+    readonly duration?: number;
+};
+declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/component/FluxVisualSlotText.vue.d.ts

@@ -0,0 +1,41 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type SlotTextColor = string | ((index: number, total: number) => string);
+type SlotTextDirection = 'up' | 'down';
+type AnimateOptions = {
+    direction?: SlotTextDirection;
+    stagger?: number;
+    duration?: number;
+    exitOffset?: number;
+    easing?: string;
+    bounce?: number;
+    color?: SlotTextColor;
+    colorFade?: number;
+    skipUnchanged?: boolean;
+    interrupt?: boolean;
+};
+type FlashOptions = {
+    revertAfter?: number;
+    enter?: AnimateOptions;
+    exit?: AnimateOptions;
+};
+type __VLS_Props = {
+    readonly text: string;
+    readonly bounce?: number;
+    readonly chromatic?: boolean;
+    readonly color?: string;
+    readonly colorFade?: number;
+    readonly direction?: SlotTextDirection;
+    readonly duration?: number;
+    readonly easing?: string;
+    readonly exitOffset?: number;
+    readonly interrupt?: boolean;
+    readonly skipUnchanged?: boolean;
+    readonly stagger?: number;
+};
+declare function set(toText: string, options?: AnimateOptions): void;
+declare function flash(toText: string, { revertAfter, enter, exit }?: FlashOptions): void;
+declare const _default: DefineComponent<__VLS_Props, {
+    flash: typeof flash;
+    set: typeof set;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/component/FluxVisualTextScramble.vue.d.ts

@@ -0,0 +1,20 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    readonly text: string;
+    readonly characters?: string;
+    readonly duration?: number;
+    readonly skipUnchanged?: boolean;
+    readonly speed?: number;
+    readonly stagger?: number;
+};
+declare function set(toText: string): void;
+declare function replay(): void;
+declare const _default: DefineComponent<__VLS_Props, {
+    replay: typeof replay;
+    set: typeof set;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+    finished: () => any;
+}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onFinished?: () => any;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/component/FluxVisualTextShimmer.vue.d.ts

@@ -0,0 +1,18 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    readonly color?: string;
+    readonly duration?: number;
+    readonly shimmerColor?: string;
+    readonly spread?: number;
+};
+type __VLS_Slots = {
+    default(): any;
+};
+declare const __VLS_base: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/component/index.d.ts

@@ -0,0 +1,15 @@
+export { default as FluxVisualAnimatedColors } from './FluxVisualAnimatedColors.vue';
+export { default as FluxVisualAttention } from './FluxVisualAttention.vue';
+export { default as FluxVisualBorderBeam } from './FluxVisualBorderBeam.vue';
+export { default as FluxVisualBorderShine } from './FluxVisualBorderShine.vue';
+export { default as FluxVisualDotPattern } from './FluxVisualDotPattern.vue';
+export { default as FluxVisualFlickeringGrid } from './FluxVisualFlickeringGrid.vue';
+export { default as FluxVisualGridPattern } from './FluxVisualGridPattern.vue';
+export { default as FluxVisualHighlighter } from './FluxVisualHighlighter.vue';
+export { default as FluxVisualHighlighterGroup } from './FluxVisualHighlighterGroup.vue';
+export { default as FluxVisualNoise } from './FluxVisualNoise.vue';
+export { default as FluxVisualNumberFlow } from './FluxVisualNumberFlow.vue';
+export { default as FluxVisualPing } from './FluxVisualPing.vue';
+export { default as FluxVisualSlotText } from './FluxVisualSlotText.vue';
+export { default as FluxVisualTextScramble } from './FluxVisualTextScramble.vue';
+export { default as FluxVisualTextShimmer } from './FluxVisualTextShimmer.vue';

package/dist/composable/private/index.d.ts

@@ -0,0 +1,2 @@
+export { default as useBorderBeamPulse, type BorderBeamVariant } from './useBorderBeamPulse';
+export { default as useHighlighterGroup, useHighlighterGroupInjection, type HighlighterGroupContext, type HighlighterGroupEntry, type HighlighterGroupProps, type HighlighterVariant } from './useHighlighterGroup';

package/dist/composable/private/useBorderBeamPulse.d.ts

@@ -0,0 +1,21 @@
+import { Ref } from 'vue';
+export type BorderBeamVariant = 'sm' | 'md' | 'line' | 'pulse-inner' | 'pulse-outside';
+type UseBorderBeamPulseOptions = {
+    readonly duration: Ref<number>;
+    readonly elementRef: Ref<HTMLElement | null>;
+    readonly enabled: Ref<boolean>;
+    readonly staticColors: Ref<boolean>;
+    readonly variant: Ref<BorderBeamVariant>;
+};
+/**
+ * Drives the breathing of a pulse border beam from the shared, frame-rate-capped
+ * animation loop while the instance is enabled. Respects prefers-reduced-motion
+ * and resolves the theme from the nearest `[dark]` ancestor.
+ *
+ * @param options The reactive instance options.
+ *
+ * @author Bas Milius <bas@mili.us>
+ * @since 1.0.0
+ */
+export default function useBorderBeamPulse(options: UseBorderBeamPulseOptions): void;
+export {};

package/dist/composable/private/useHighlighterGroup.d.ts

@@ -0,0 +1,51 @@
+import { annotationGroup } from 'rough-notation';
+type Annotation = Parameters<typeof annotationGroup>[0][number];
+export type HighlighterVariant = 'highlight' | 'box' | 'circle' | 'underline' | 'strike-through' | 'crossed-off' | 'bracket';
+export type HighlighterGroupProps = {
+    readonly variant?: HighlighterVariant;
+    readonly color?: string;
+    readonly strokeWidth?: number;
+    readonly animationDuration?: number;
+    readonly iterations?: number;
+    readonly padding?: number;
+    readonly multiline?: boolean;
+    readonly whenInView?: boolean;
+};
+export type HighlighterGroupEntry = {
+    readonly element: HTMLElement;
+    getAnnotation(): Annotation | null;
+};
+export type HighlighterGroupContext = {
+    readonly defaults: HighlighterGroupProps;
+    add(entry: HighlighterGroupEntry): void;
+    remove(entry: HighlighterGroupEntry): void;
+    notify(): void;
+};
+/**
+ * Injects the enclosing highlighter group, if any. A `FluxVisualHighlighter`
+ * that finds a group registers its annotation with it and lets the group drive
+ * the cascade instead of drawing itself.
+ *
+ * @author Bas Milius <bas@mili.us>
+ * @since 1.0.0
+ */
+export declare function useHighlighterGroupInjection(): HighlighterGroupContext | null;
+/**
+ * Collects the annotations of the descendant highlighters and reveals them as a
+ * single rough-notation group, so they draw one after another in document order
+ * rather than all at once. The draw is debounced so the initial burst of child
+ * registrations (and any surrounding chrome settling its layout) coalesces into
+ * one cascade, and — when `whenInView` is set — it waits until the first
+ * highlighter scrolls into view. rough-notation keeps the drawn annotations
+ * aligned on later resizes itself.
+ *
+ * The reactive props object is provided as `defaults` on the group context, so
+ * descendant highlighters can inherit annotation props they don't set themselves.
+ *
+ * @param props The reactive props of the group component.
+ *
+ * @author Bas Milius <bas@mili.us>
+ * @since 1.0.0
+ */
+export default function useHighlighterGroup(props: HighlighterGroupProps): void;
+export {};