@ansh-ui/vue 0.2.0

package/dist/motion.d.ts

@@ -0,0 +1,681 @@
+import * as vue from 'vue';
+import { VNode, PropType, ComputedRef } from 'vue';
+import { EasingInput, SpringOptions, springs, StaggerFrom, ColorInput, ReducedMotionMode } from '@ansh-ui/core';
+
+/**
+ * Declarative motion — the Vue counterpart of `@ansh-ui/react`'s `Motion`/`AnimatePresence`/
+ * `Draggable`.
+ *
+ * A deliberately **small** subset of what a full motion library does: transform properties and
+ * opacity, animated from `initial` to `animate`, plus hover and press states and an exit animation
+ * when paired with `AnimatePresence`.
+ *
+ * That scope is a decision, not a gap. Layout animation (FLIP), shared-element transitions and
+ * variant propagation each need machinery an order of magnitude larger than this file, and a
+ * half-implementation of them is worse than none — it works in the demo and fails on the real page.
+ * For those, use a dedicated library; for the 90% case of "fade this in, slide that up, spring the
+ * card on hover", this costs a fraction of the bundle.
+ *
+ * Values are written straight to the element's `style` from the ticker's write phase, outside Vue's
+ * reactivity — the same principle `useMotionStyle` documents in `composables/use-motion.ts`. `Motion`
+ * and `Draggable` are built on `useAnimate()` (scope-bound imperative animation, auto-stopping the
+ * previous run) and `useInView()` (the `whileInView` trigger) rather than calling the ticker
+ * primitives from scratch, so cleanup and scope-disposal are inherited for free.
+ */
+interface MotionValues {
+    opacity?: number;
+    x?: number;
+    y?: number;
+    scale?: number;
+    scaleX?: number;
+    scaleY?: number;
+    rotate?: number;
+    /** Blur radius in px. */
+    blur?: number;
+}
+interface MotionTransition {
+    /** Seconds. Ignored when `spring` is set. Default `0.4`. */
+    duration?: number;
+    /** Seconds to wait. Default `0`. */
+    delay?: number;
+    easing?: EasingInput;
+    /** Use a spring instead of a tween. `true` uses the `smooth` preset. */
+    spring?: boolean | SpringOptions | keyof typeof springs;
+}
+/**
+ * An animated element.
+ *
+ * ```vue
+ * <Motion :initial="{ opacity: 0, y: 24 }" :animate="{ opacity: 1, y: 0 }" while-in-view>
+ *   <Card />
+ * </Motion>
+ * ```
+ */
+declare const Motion: vue.DefineComponent<vue.ExtractPropTypes<{
+    as: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** Starting values. Applied before the first paint. */
+    initial: {
+        type: PropType<MotionValues>;
+        default: undefined;
+    };
+    /** Target values. Changing these animates to the new target. */
+    animate: {
+        type: PropType<MotionValues>;
+        default: undefined;
+    };
+    exit: {
+        type: PropType<MotionValues>;
+        default: undefined;
+    };
+    transition: {
+        type: PropType<MotionTransition>;
+        default: undefined;
+    };
+    whileHover: {
+        type: PropType<MotionValues>;
+        default: undefined;
+    };
+    whileTap: {
+        type: PropType<MotionValues>;
+        default: undefined;
+    };
+    /** Animate to `animate` only once scrolled into view. */
+    whileInView: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Fraction visible before `whileInView` triggers. Default `0.2`. */
+    inViewAmount: {
+        type: NumberConstructor;
+        default: number;
+    };
+}>, () => VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    as: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** Starting values. Applied before the first paint. */
+    initial: {
+        type: PropType<MotionValues>;
+        default: undefined;
+    };
+    /** Target values. Changing these animates to the new target. */
+    animate: {
+        type: PropType<MotionValues>;
+        default: undefined;
+    };
+    exit: {
+        type: PropType<MotionValues>;
+        default: undefined;
+    };
+    transition: {
+        type: PropType<MotionTransition>;
+        default: undefined;
+    };
+    whileHover: {
+        type: PropType<MotionValues>;
+        default: undefined;
+    };
+    whileTap: {
+        type: PropType<MotionValues>;
+        default: undefined;
+    };
+    /** Animate to `animate` only once scrolled into view. */
+    whileInView: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Fraction visible before `whileInView` triggers. Default `0.2`. */
+    inViewAmount: {
+        type: NumberConstructor;
+        default: number;
+    };
+}>> & Readonly<{}>, {
+    initial: MotionValues;
+    as: string;
+    animate: MotionValues;
+    exit: MotionValues;
+    transition: MotionTransition;
+    whileHover: MotionValues;
+    whileTap: MotionValues;
+    whileInView: boolean;
+    inViewAmount: number;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+interface AnimatePresenceProps {
+    /** Seconds to keep a removed child mounted. Default `0.35`. */
+    exitDuration?: number;
+}
+/**
+ * Keep removed children mounted long enough to animate out.
+ *
+ * Vue unmounts a `v-for`/`v-if` item the instant it disappears from its source array, so an exit
+ * animation never gets a chance to run. This holds departing children in its own state, plays their
+ * `exit` values (swapped into `animate` on a cloned vnode), then drops them.
+ *
+ * Children **must** have stable `:key`s — that is how removals are detected at all. Without keys,
+ * Vue reuses vnode positions and this sees no removal to animate, same as the React version.
+ *
+ * Vue's own `<TransitionGroup>` was considered instead of this hand-rolled reconciliation, but it
+ * drives *CSS* transition/animation classes on move — it has no hook for "swap this prop and let the
+ * child's own animation system take it from here," which is what `exit` needs to compose with
+ * `Motion`. Cloning the departing vnode with its `animate` prop swapped to `exit` is the direct
+ * Vue-side equivalent of the React version's `cloneElement`.
+ */
+declare const AnimatePresence: vue.DefineComponent<vue.ExtractPropTypes<{
+    exitDuration: {
+        type: NumberConstructor;
+        default: number;
+    };
+}>, () => VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>[], {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    exitDuration: {
+        type: NumberConstructor;
+        default: number;
+    };
+}>> & Readonly<{}>, {
+    exitDuration: number;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+interface DraggableProps {
+    /** Constrain movement. */
+    axis?: 'x' | 'y' | 'both';
+    /** Bounds relative to the starting position, in px. */
+    bounds?: {
+        left?: number;
+        right?: number;
+        top?: number;
+        bottom?: number;
+    };
+    /** Spring back to the origin on release. */
+    snapBack?: boolean;
+    /** Carry momentum after release. Default `true` when not snapping back. */
+    momentum?: boolean;
+}
+/**
+ * A draggable surface with inertia.
+ *
+ * The momentum on release is what separates a drag that feels physical from one that stops dead.
+ * Velocity is measured over the last few pointer samples rather than the last two — a single pair
+ * of events is dominated by whatever jitter the final sample had, which produces a flick in the
+ * wrong direction often enough to be noticeable.
+ *
+ * `onDragStart`/`onDragEnd` from the React version become `dragStart`/`dragEnd` emits — this
+ * package's convention for event-callback props (see `Input`'s `change`/`clear` emits).
+ */
+declare const Draggable: vue.DefineComponent<vue.ExtractPropTypes<{
+    axis: {
+        type: PropType<"x" | "y" | "both">;
+        default: string;
+    };
+    bounds: {
+        type: PropType<{
+            left?: number;
+            right?: number;
+            top?: number;
+            bottom?: number;
+        }>;
+        default: undefined;
+    };
+    snapBack: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    momentum: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+}>, () => VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, ("dragStart" | "dragEnd")[], "dragStart" | "dragEnd", vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    axis: {
+        type: PropType<"x" | "y" | "both">;
+        default: string;
+    };
+    bounds: {
+        type: PropType<{
+            left?: number;
+            right?: number;
+            top?: number;
+            bottom?: number;
+        }>;
+        default: undefined;
+    };
+    snapBack: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    momentum: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+}>> & Readonly<{
+    onDragStart?: ((...args: any[]) => any) | undefined;
+    onDragEnd?: ((...args: any[]) => any) | undefined;
+}>, {
+    axis: "y" | "x" | "both";
+    bounds: {
+        left?: number;
+        right?: number;
+        top?: number;
+        bottom?: number;
+    };
+    snapBack: boolean;
+    momentum: boolean;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+/**
+ * Text filled with a perceptual gradient.
+ *
+ * The stops are generated through the OKLab interpolator rather than handed to CSS as two
+ * endpoints. That is the entire point: a CSS `linear-gradient(#0275f4, #9f0550)` passes through a
+ * desaturated grey-brown at its midpoint, and on text — where the gradient crosses a narrow band —
+ * the midpoint is exactly where the eye lands.
+ *
+ * The optional animation is a CSS `background-position` shift rather than a JS loop, because for a
+ * single non-interactive property the browser's compositor beats anything we could do on the main
+ * thread.
+ */
+declare const GradientText: vue.DefineComponent<vue.ExtractPropTypes<{
+    text: {
+        type: StringConstructor;
+        default: string;
+    };
+    colors: {
+        type: PropType<readonly ColorInput[] | string>;
+        default: undefined;
+    };
+    /** Gradient angle in degrees. */
+    angle: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Seconds per cycle. `0` holds a static gradient. */
+    duration: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Interpolated stops handed to CSS. More is smoother. */
+    stops: {
+        type: NumberConstructor;
+        default: number;
+    };
+    as: {
+        type: StringConstructor;
+        default: string;
+    };
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    text: {
+        type: StringConstructor;
+        default: string;
+    };
+    colors: {
+        type: PropType<readonly ColorInput[] | string>;
+        default: undefined;
+    };
+    /** Gradient angle in degrees. */
+    angle: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Seconds per cycle. `0` holds a static gradient. */
+    duration: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Interpolated stops handed to CSS. More is smoother. */
+    stops: {
+        type: NumberConstructor;
+        default: number;
+    };
+    as: {
+        type: StringConstructor;
+        default: string;
+    };
+}>> & Readonly<{}>, {
+    as: string;
+    colors: string | readonly ColorInput[];
+    angle: number;
+    stops: number;
+    duration: number;
+    text: string;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+/**
+ * Text that reveals unit by unit.
+ *
+ * The split happens during render, so the markup is server-rendered and the real text is present in
+ * the HTML source for SEO and for readers without JavaScript. The animation runs on the shared
+ * ticker, so a page full of these shares one clock and cannot drift apart.
+ *
+ * Under `prefers-reduced-motion` the text renders in its final state and never animates.
+ */
+declare const AnimatedText: vue.DefineComponent<vue.ExtractPropTypes<{
+    text: {
+        type: StringConstructor;
+        required: true;
+    };
+    /** Split granularity. */
+    by: {
+        type: PropType<"chars" | "words">;
+        default: string;
+    };
+    /** Seconds per unit. */
+    duration: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Seconds between units. */
+    each: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Where the reveal wave begins. */
+    from: {
+        type: PropType<StaggerFrom>;
+        default: string;
+    };
+    easing: {
+        type: PropType<EasingInput>;
+        default: string;
+    };
+    /** Distance each unit travels into place, in pixels. */
+    distance: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Starting blur in pixels — the "focus in" look. */
+    blur: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Starting rotation in degrees. */
+    rotate: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Clip each unit so it rises from behind a mask. */
+    mask: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Wait until scrolled into view. */
+    whenInView: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Replay every time it re-enters the viewport. */
+    repeat: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Seconds to wait before starting. */
+    delay: {
+        type: NumberConstructor;
+        default: number;
+    };
+    as: {
+        type: StringConstructor;
+        default: string;
+    };
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, "complete"[], "complete", vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    text: {
+        type: StringConstructor;
+        required: true;
+    };
+    /** Split granularity. */
+    by: {
+        type: PropType<"chars" | "words">;
+        default: string;
+    };
+    /** Seconds per unit. */
+    duration: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Seconds between units. */
+    each: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Where the reveal wave begins. */
+    from: {
+        type: PropType<StaggerFrom>;
+        default: string;
+    };
+    easing: {
+        type: PropType<EasingInput>;
+        default: string;
+    };
+    /** Distance each unit travels into place, in pixels. */
+    distance: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Starting blur in pixels — the "focus in" look. */
+    blur: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Starting rotation in degrees. */
+    rotate: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /** Clip each unit so it rises from behind a mask. */
+    mask: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Wait until scrolled into view. */
+    whenInView: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Replay every time it re-enters the viewport. */
+    repeat: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Seconds to wait before starting. */
+    delay: {
+        type: NumberConstructor;
+        default: number;
+    };
+    as: {
+        type: StringConstructor;
+        default: string;
+    };
+}>> & Readonly<{
+    onComplete?: ((...args: any[]) => any) | undefined;
+}>, {
+    repeat: boolean;
+    as: string;
+    blur: number;
+    rotate: number;
+    duration: number;
+    easing: EasingInput;
+    distance: number;
+    delay: number;
+    by: "chars" | "words";
+    each: number;
+    from: StaggerFrom;
+    mask: boolean;
+    whenInView: boolean;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+/**
+ * Application-level configuration providers — the Vue counterpart of `@ansh-ui/react`'s
+ * `providers.tsx`. `provide`/`inject` replace React context; everything else about the two designs
+ * is intentionally identical, because the underlying correctness constraints (no hydration
+ * mismatch, no theme flash) don't change with the framework.
+ */
+interface MotionConfigValue {
+    reducedMotion: ReducedMotionMode;
+    /** Global playback rate. `0.5` is slow motion across every animation on the page. */
+    timeScale: number;
+    /** Pin adaptive quality, or `null` to let the frame budget decide. */
+    quality: number | null;
+}
+/**
+ * Application-level motion configuration.
+ *
+ * Optional — every component works without it. Mount it once at the root when you need app-wide
+ * control:
+ *
+ * ```vue
+ * <MotionConfig :reduced-motion="userPrefersCalm ? 'always' : 'auto'">
+ *   <App />
+ * </MotionConfig>
+ * ```
+ *
+ * `reducedMotion="always"` is genuinely useful in production, as the backing for an in-app "reduce
+ * motion" setting — many users who want calmer interfaces have never found the OS toggle.
+ */
+declare const MotionConfig: vue.DefineComponent<vue.ExtractPropTypes<{
+    reducedMotion: {
+        type: PropType<ReducedMotionMode>;
+        default: string;
+    };
+    timeScale: {
+        type: NumberConstructor;
+        default: number;
+    };
+    quality: {
+        type: PropType<number | null>;
+        default: null;
+    };
+    /**
+     * Pause every animation while the document is hidden. Default `true`.
+     *
+     * Leave this on. Animating a background tab burns battery and spins fans for output nobody can
+     * see, and it is the most common performance complaint about animation-heavy sites.
+     */
+    pauseWhenHidden: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    pauseWhenBlurred: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    respectBattery: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>[] | undefined, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    reducedMotion: {
+        type: PropType<ReducedMotionMode>;
+        default: string;
+    };
+    timeScale: {
+        type: NumberConstructor;
+        default: number;
+    };
+    quality: {
+        type: PropType<number | null>;
+        default: null;
+    };
+    /**
+     * Pause every animation while the document is hidden. Default `true`.
+     *
+     * Leave this on. Animating a background tab burns battery and spins fans for output nobody can
+     * see, and it is the most common performance complaint about animation-heavy sites.
+     */
+    pauseWhenHidden: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    pauseWhenBlurred: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    respectBattery: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{}>, {
+    quality: number | null;
+    reducedMotion: ReducedMotionMode;
+    timeScale: number;
+    pauseWhenHidden: boolean;
+    pauseWhenBlurred: boolean;
+    respectBattery: boolean;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+/** Read the nearest {@link MotionConfig}. Returns sensible defaults with no provider present. */
+declare function useMotionConfig(): ComputedRef<MotionConfigValue>;
+type ThemeSetting = 'light' | 'dark' | 'system';
+interface ThemeContextValue {
+    /** What was requested, including `'system'`. */
+    theme: ThemeSetting;
+    /** What is actually rendering. `'system'` is resolved to one or the other. */
+    resolved: 'light' | 'dark';
+    setTheme: (theme: ThemeSetting) => void;
+}
+/**
+ * Theme control over the `@ansh-ui/tokens` stylesheet.
+ *
+ * Sets `data-theme` on `<html>`, which the token stylesheet already understands. Two details that
+ * are easy to get wrong and are handled here:
+ *
+ * **`'system'` removes the attribute rather than writing a resolved value.** The token stylesheet
+ * guards its `prefers-color-scheme` rule with `:root:not([data-theme])`, so removing the attribute
+ * hands control back to the OS — and, importantly, means the theme keeps following the OS if the
+ * user changes it while the page is open.
+ *
+ * **The initial render always reports `'light'`.** Reading `localStorage` during setup would be a
+ * hydration mismatch, since the server has no access to it. The stored value is applied `onMounted`.
+ * To avoid a flash of the wrong theme, ship the small inline script from {@link themeScript} in your
+ * document `<head>` — that is the only way to set the attribute before first paint. `@ansh-ui/nuxt`
+ * does this automatically.
+ */
+declare const ThemeProvider: vue.DefineComponent<vue.ExtractPropTypes<{
+    /** Initial setting. Default `'system'`. */
+    defaultTheme: {
+        type: PropType<ThemeSetting>;
+        default: string;
+    };
+    /** Persist the choice under this `localStorage` key. Pass `null` to disable. */
+    storageKey: {
+        type: PropType<string | null>;
+        default: string;
+    };
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>[] | undefined, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    /** Initial setting. Default `'system'`. */
+    defaultTheme: {
+        type: PropType<ThemeSetting>;
+        default: string;
+    };
+    /** Persist the choice under this `localStorage` key. Pass `null` to disable. */
+    storageKey: {
+        type: PropType<string | null>;
+        default: string;
+    };
+}>> & Readonly<{}>, {
+    defaultTheme: ThemeSetting;
+    storageKey: string | null;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+declare function useTheme(): ComputedRef<ThemeContextValue>;
+/**
+ * The blocking script that prevents a theme flash.
+ *
+ * Inject this in `<head>`, before any stylesheet. It reads the stored preference and sets
+ * `data-theme` synchronously, before the browser paints — the only point at which it can be done
+ * without a visible flash. Deliberately tiny and dependency-free.
+ *
+ * `@ansh-ui/nuxt` injects this automatically; a bare Vue app should call it from `index.html`.
+ */
+declare function themeScript(storageKey?: string): string;
+
+export { AnimatePresence, type AnimatePresenceProps, AnimatedText, Draggable, type DraggableProps, GradientText, Motion, MotionConfig, type MotionConfigValue, type MotionTransition, type MotionValues, type ThemeContextValue, ThemeProvider, type ThemeSetting, themeScript, useMotionConfig, useTheme };

package/dist/motion.js

@@ -0,0 +1,5 @@
+export { AnimatePresence, AnimatedText, Draggable, GradientText, Motion, MotionConfig, ThemeProvider, themeScript, useMotionConfig, useTheme } from './chunk-6ABPGOJP.js';
+import './chunk-EVO23GUS.js';
+import './chunk-NJDDNO4C.js';
+//# sourceMappingURL=motion.js.map
+//# sourceMappingURL=motion.js.map

package/dist/motion.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"motion.js"}