@ansh-ui/core 0.2.0

package/dist/index-Dl8GCsya.d.cts

@@ -0,0 +1,435 @@
+import { R as ReducedMotionStrategy } from './reduced-motion-D0LUgZle.cjs';
+import { E as EasingInput } from './types-B1FLLf3-.cjs';
+
+/**
+ * The Behaviour contract — the DOM counterpart to {@link import('../effects/types').EffectDefinition}.
+ *
+ * An Effect owns a canvas and draws pixels. A Behaviour owns an element and manipulates styles,
+ * transforms or child nodes. Magnetic hover, 3D tilt, marquee scrolling, split-text reveals and
+ * parallax are all Behaviours.
+ *
+ * They share the same shape deliberately: identical lifecycle, identical option-merging, and a
+ * single `createBehaviourComponent` helper per framework. Whether a component is canvas-backed or
+ * DOM-backed becomes an implementation detail rather than an API difference.
+ */
+interface BaseBehaviourOptions {
+    /** Multiplier on the behaviour's characteristic strength. Default `1`. */
+    intensity?: number;
+    /** How to behave under `prefers-reduced-motion`. */
+    reducedMotion?: ReducedMotionStrategy;
+    /** Suspend the behaviour without unmounting. Default `false`. */
+    disabled?: boolean;
+}
+interface BehaviourInstance<Options = Record<string, unknown>> {
+    /** Apply changed options. Omit to have the host remount on any change. */
+    update?(options: Partial<Options>): void;
+    /**
+     * Release everything.
+     *
+     * Must restore any inline styles the behaviour set, remove any nodes it created, and detach
+     * every listener. The test suite's leak harness asserts all three.
+     */
+    destroy(): void;
+}
+interface BehaviourDefinition<Options extends BaseBehaviourOptions = BaseBehaviourOptions, Element extends HTMLElement = HTMLElement> {
+    readonly name: string;
+    readonly defaults: Required<Options>;
+    readonly capability?: string;
+    setup(element: Element, options: Required<Options>): BehaviourInstance<Options>;
+}
+interface BehaviourHandle<Options> {
+    update(options: Partial<Options>): void;
+    destroy(): void;
+}
+/**
+ * Mount a behaviour onto an element.
+ *
+ * Thinner than the effect mount because there is no canvas, no surface and no render loop to
+ * manage — a behaviour that needs frames subscribes to the ticker itself. What this does provide
+ * is the uniform option merge (including the `undefined`-stripping that React and Vue both
+ * require), capability gating, and idempotent teardown.
+ */
+declare function mountBehaviour<Options extends BaseBehaviourOptions, El extends HTMLElement = HTMLElement>(definition: BehaviourDefinition<Options, El>, element: El, userOptions?: Partial<Options>): BehaviourHandle<Options>;
+/** Register a behaviour so the CLI and docs site can discover it. */
+declare function defineBehaviour<Options extends BaseBehaviourOptions, El extends HTMLElement = HTMLElement>(definition: BehaviourDefinition<Options, El>): BehaviourDefinition<Options, El>;
+/**
+ * Remember an element's inline styles so they can be restored exactly on teardown.
+ *
+ * Setting `element.style.transform = ''` is *not* a restore — it destroys an inline transform
+ * the author may have set themselves. This captures the previous value per property and puts it
+ * back, including removing the property entirely if it wasn't there before.
+ */
+declare function captureStyles<K extends keyof CSSStyleDeclaration & string>(element: HTMLElement, properties: readonly K[]): () => void;
+
+/**
+ * Ripple — a wave that expands from the point of contact.
+ *
+ * Material Design's ripple, done properly. Three details most implementations miss:
+ *
+ * **The radius must reach the furthest corner.** A ripple sized to the element's width leaves the
+ * corners untouched on a wide button, which looks like a bug. The correct radius is the distance
+ * from the contact point to the furthest corner, computed per press.
+ *
+ * **Fade-out must outlast expansion.** If opacity and scale finish together, the ripple appears to
+ * vanish mid-motion. The expansion completes first and the fade continues past it, so the ripple
+ * dissolves at full size.
+ *
+ * **Multiple ripples must coexist.** Rapid clicking should produce overlapping ripples, not one
+ * that restarts. Each press gets its own element, and they are cleaned up independently.
+ *
+ * The ripple layer is inserted as a positioned child with `overflow: hidden`, so it is clipped to
+ * the element's own border radius via `border-radius: inherit` — no need for the author to
+ * duplicate their radius in a prop.
+ */
+interface RippleOptions extends BaseBehaviourOptions {
+    /** Ripple colour. Any CSS colour. Default `'currentColor'` at low alpha. */
+    color?: string;
+    /** Peak opacity, in `[0, 1]`. Default `0.28`. */
+    opacity?: number;
+    /** Expansion duration in seconds. Default `0.55`. */
+    duration?: number;
+    /** Additional seconds the fade continues past the expansion. Default `0.25`. */
+    fadeDuration?: number;
+    easing?: EasingInput;
+    /** Always start from the element's centre rather than the contact point. Default `false`. */
+    centered?: boolean;
+    /** Trigger on keyboard activation (Enter/Space) as well as pointer. Default `true`. */
+    keyboard?: boolean;
+    /** Maximum simultaneous ripples. Older ones are removed beyond this. Default `6`. */
+    maxRipples?: number;
+}
+declare const ripple: BehaviourDefinition<RippleOptions, HTMLElement>;
+
+/**
+ * Parallax — elements that move at a different rate from the scroll.
+ *
+ * Parallax has a bad reputation, and mostly it is deserved: it is the effect most likely to
+ * cause motion sickness, and the most commonly implemented by reading
+ * `getBoundingClientRect()` in a `scroll` handler — which forces a synchronous layout on every
+ * scroll event and is the single most common cause of janky scrolling on the web.
+ *
+ * Two structural fixes here:
+ *
+ * **All measurement happens in the ticker's `read` phase, all writes in `write`.** The scroll
+ * handler does nothing at all; scroll position is sampled once per frame. Fifty parallax elements
+ * therefore cost one layout read per frame between them, not fifty per event.
+ *
+ * **The element's own document position is cached and only re-measured on resize.** Scrolling
+ * does not change where an element sits in the document, so re-measuring per frame is pure waste.
+ */
+interface ParallaxOptions extends BaseBehaviourOptions {
+    /**
+     * Movement rate relative to the scroll.
+     *
+     * `0` is fixed to the page (no parallax). `0.3` moves at 30% of scroll speed — the element
+     * appears further away. Negative values move against the scroll, appearing nearer.
+     * Values beyond ±0.5 read as broken rather than deep. Default `0.3`.
+     */
+    speed?: number;
+    /** Axis to translate along. Default `'y'`. */
+    axis?: 'y' | 'x';
+    /** Also scale as the element passes through. `1` disables. Default `1`. */
+    scale?: number;
+    /** Also rotate as the element passes through, in degrees. Default `0`. */
+    rotate?: number;
+    /** Also fade. `[enterOpacity, centreOpacity, exitOpacity]`. Default no fade. */
+    fade?: readonly [number, number, number];
+    /**
+     * Clamp the translation so the element cannot leave its own container.
+     *
+     * Strongly recommended for background images inside a fixed-height section: without it, a
+     * parallax image reveals the empty space behind it at the extremes. Default `true`.
+     */
+    contain?: boolean;
+    /** Smoothing applied to the parallax position, in `[0, 1)`. `0` tracks scroll exactly. Default `0`. */
+    smoothing?: number;
+}
+declare const parallax: BehaviourDefinition<ParallaxOptions, HTMLElement>;
+
+/**
+ * Stagger — the per-element delay that turns N simultaneous animations into a sequence.
+ *
+ * The reason this deserves its own module rather than being `index * 0.05`: *where* the wave
+ * originates changes what the motion communicates. A list that reveals from the top reads as
+ * "loading in order". The same list revealing from the item the user clicked reads as
+ * "responding to you". Getting the origin right is most of the craft in orchestration.
+ */
+/**
+ * Where the stagger wave begins.
+ *
+ * - `'first'`  — index 0 goes first. The default; reads as natural reading order.
+ * - `'last'`   — reversed. Useful for exits, so the last thing in stays longest.
+ * - `'center'` — radiates outward from the middle. Good for symmetric layouts and hero content.
+ * - `'edges'`  — converges inward from both ends. Reads as "gathering".
+ * - a number   — a specific index. Pass the index the user interacted with.
+ */
+type StaggerFrom = 'first' | 'last' | 'center' | 'edges' | number;
+interface StaggerOptions {
+    /** Seconds between consecutive elements. Default `0.05`. */
+    each?: number;
+    /**
+     * Total seconds the whole wave should span. Overrides `each` when set — the more useful knob
+     * for "reveal these however many items there are in 400ms".
+     */
+    total?: number;
+    from?: StaggerFrom;
+    /**
+     * Easing applied to the *distribution* of delays, not to each animation.
+     *
+     * `easeOutQuad` bunches later elements closer together, so a long list accelerates rather
+     * than plodding at a constant rate — the difference between 40 items feeling fast and
+     * feeling interminable.
+     */
+    easing?: EasingInput;
+    /** Base delay added to every element. Default `0`. */
+    delay?: number;
+    /**
+     * For grid layouts: `[columns, rows]`. Distance is then measured in 2D, so `from: 'center'`
+     * radiates as a circle rather than along a single index axis.
+     */
+    grid?: readonly [number, number];
+    /** Which axis to measure along in a grid. `undefined` uses true 2D distance. */
+    axis?: 'x' | 'y';
+}
+/**
+ * Build a delay function for a set of `count` elements.
+ *
+ * @returns `(index) => delayInSeconds`
+ */
+declare function stagger(count: number, options?: StaggerOptions): (index: number) => number;
+/**
+ * Total wall-clock time a staggered set will take.
+ *
+ * Needed so a timeline can place whatever comes *after* a staggered group without the author
+ * having to work out `count × each + duration` themselves.
+ */
+declare function staggerDuration(count: number, itemDuration: number, options?: StaggerOptions): number;
+
+/**
+ * Scroll Reveal — animate elements in as they enter the viewport.
+ *
+ * The critical correctness requirement is **SSR and no-JS safety**. The common implementation
+ * sets `opacity: 0` in CSS and removes it with JavaScript, which means that if JavaScript fails
+ * to load, is blocked, or throws before this runs, the content is permanently invisible. That has
+ * shipped to production on a lot of marketing sites.
+ *
+ * So: the initial hidden state is applied *by this behaviour, in JavaScript*, immediately on
+ * setup. If the script never runs, the content is simply visible — degraded but correct. This is
+ * the only defensible default for content the user came to read.
+ *
+ * The reveal itself runs on the shared ticker rather than a CSS transition, so a staggered group
+ * shares one clock and cannot drift, and so `prefers-reduced-motion` is handled in one place.
+ */
+interface ScrollRevealOptions extends BaseBehaviourOptions {
+    /** Distance in pixels the element travels into place. Default `24`. */
+    distance?: number;
+    /** Direction the element travels *from*. Default `'up'` (enters moving upward). */
+    direction?: 'up' | 'down' | 'left' | 'right' | 'none';
+    /** Starting opacity. Default `0`. */
+    opacity?: number;
+    /** Starting scale. `1` disables scaling. Default `1`. */
+    scale?: number;
+    /** Starting rotation in degrees. Default `0`. */
+    rotate?: number;
+    /** Starting blur in pixels. Default `0`. */
+    blur?: number;
+    /** Duration in seconds. Default `0.7`. */
+    duration?: number;
+    easing?: EasingInput;
+    /** Seconds to wait after entering the viewport. Default `0`. */
+    delay?: number;
+    /** Fraction of the element that must be visible to trigger, in `[0, 1]`. Default `0.15`. */
+    threshold?: number;
+    /** Extra margin around the viewport, as a CSS margin string. Default `'0px 0px -10% 0px'`. */
+    rootMargin?: string;
+    /** Reverse the animation when the element leaves the viewport. Default `false`. */
+    repeat?: boolean;
+    /**
+     * Selector for descendants to reveal individually rather than the host itself.
+     * When set, the host stays untouched and its matching descendants are staggered.
+     *
+     * Named `selector`, not `children`. The framework bindings spread these options onto a
+     * component's props, where `children` means the rendered subtree — a `children: string` option
+     * silently narrows the component's real `children` to `string`, making `<ScrollReveal><p/></ScrollReveal>`
+     * a type error with an unreadable message. The collision is invisible in the engine and only
+     * surfaces at the binding layer.
+     */
+    selector?: string;
+    /** Stagger configuration when `selector` is set. */
+    stagger?: StaggerOptions;
+}
+declare const scrollReveal: BehaviourDefinition<ScrollRevealOptions, HTMLElement>;
+
+type SplitUnit = 'chars' | 'words' | 'lines';
+interface SplitTextOptions extends BaseBehaviourOptions {
+    /**
+     * What to split into. `'lines'` requires a layout measurement pass and re-splits on resize,
+     * so it is more expensive — but it is the only way to animate by visual line.
+     */
+    by?: SplitUnit | readonly SplitUnit[];
+    /** Class applied to character spans. Default `'ansh-char'`. */
+    charClass?: string;
+    /** Class applied to word spans. Default `'ansh-word'`. */
+    wordClass?: string;
+    /** Class applied to line spans. Default `'ansh-line'`. */
+    lineClass?: string;
+    /**
+     * Set `--ansh-index` and `--ansh-total` custom properties on each unit.
+     *
+     * This is what lets a pure-CSS stagger work: `animation-delay: calc(var(--ansh-index) * 40ms)`.
+     * Default `true`.
+     */
+    cssVariables?: boolean;
+    /** Wrap each unit in an extra element with `overflow: hidden`, for mask-reveal animations. */
+    mask?: boolean;
+}
+interface SplitTextResult {
+    chars: HTMLElement[];
+    words: HTMLElement[];
+    lines: HTMLElement[];
+}
+/** Read the split result for an element, if it has been split. */
+declare function getSplitResult(element: HTMLElement): SplitTextResult | undefined;
+declare const splitText: BehaviourDefinition<SplitTextOptions, HTMLElement>;
+/**
+ * Split text imperatively, outside the behaviour lifecycle.
+ *
+ * Returns the produced elements plus a `restore` function. Framework bindings use the behaviour;
+ * this is for one-off use in vanilla JS and in tests.
+ */
+declare function split(element: HTMLElement, options?: Partial<SplitTextOptions>): SplitTextResult & {
+    restore(): void;
+};
+
+/**
+ * Marquee — seamless infinite scrolling content.
+ *
+ * The CSS-only approach (`animation: scroll linear infinite` on a duplicated track) has three
+ * problems this solves:
+ *
+ * 1. **The seam.** A CSS marquee animates `translateX` from `0` to `-50%` on a doubled track. If
+ *    the content doesn't exactly fill the container, there is a visible gap or overlap at the
+ *    wrap point. Here the track is duplicated as many times as needed to exceed the container
+ *    width, and the wrap distance is the measured width of *one* copy — so it is always exact.
+ *
+ * 2. **Speed is expressed in duration, not velocity.** A CSS duration means a marquee with more
+ *    items scrolls faster, so adding a logo to a customer strip changes the animation speed. Here
+ *    speed is pixels per second, which is what an author actually means.
+ *
+ * 3. **Pause on hover can't be smooth.** Toggling `animation-play-state` stops dead. This eases
+ *    the velocity to zero, which reads as deliberate rather than broken.
+ */
+interface MarqueeOptions extends BaseBehaviourOptions {
+    /** Scroll speed in pixels per second. Negative reverses. Default `60`. */
+    speed?: number;
+    /** Scroll direction. Default `'left'`. */
+    direction?: 'left' | 'right' | 'up' | 'down';
+    /** Ease to a stop while the pointer is over the marquee. Default `true`. */
+    pauseOnHover?: boolean;
+    /** Seconds to ease in and out of a pause. Default `0.4`. */
+    pauseEasing?: number;
+    /** Gap between repeated copies, in pixels. Default `0` — use CSS `gap` on the track instead. */
+    gap?: number;
+    /** Fade the edges with a mask, in pixels. `0` disables. Default `0`. */
+    fadeEdges?: number;
+}
+declare const marquee: BehaviourDefinition<MarqueeOptions, HTMLElement>;
+
+/**
+ * Tilt — 3D perspective rotation following the pointer.
+ *
+ * The single most common mistake in tilt implementations is putting `perspective` on the element
+ * being rotated. CSS `perspective` on an element applies to its *children*, so tilting the same
+ * element that carries the perspective produces a flat, sheared result rather than a 3D one. The
+ * perspective must live on the parent, or be baked into the transform via `perspective()` as its
+ * **first** function — which is what this does, so no wrapper element is required.
+ *
+ * The second mistake is omitting the glare. A card that rotates without its highlight moving
+ * reads as a flat image being turned, because the brain expects specular reflection to shift.
+ * The optional glare layer is what makes it read as a physical surface.
+ */
+interface TiltOptions extends BaseBehaviourOptions {
+    /** Maximum rotation in degrees on each axis. Default `10`. */
+    max?: number;
+    /** Perspective distance in pixels. Lower is a more extreme effect. Default `900`. */
+    perspective?: number;
+    /** Scale applied while hovering. Default `1.02`. */
+    scale?: number;
+    /** Spring stiffness. Default `180`. */
+    stiffness?: number;
+    /** Spring damping. Default `22`. */
+    damping?: number;
+    /** Invert the rotation direction. Default `false`. */
+    reverse?: boolean;
+    /** Lift the element toward the viewer in pixels while hovering. Default `0`. */
+    lift?: number;
+    /** Add a moving specular highlight. Default `true`. */
+    glare?: boolean;
+    /** Glare opacity at maximum, in `[0, 1]`. Default `0.18`. */
+    glareOpacity?: number;
+    /** Restrict rotation to one axis. Default `'both'`. */
+    axis?: 'both' | 'x' | 'y';
+}
+declare const tilt: BehaviourDefinition<TiltOptions, HTMLElement>;
+
+/**
+ * Magnetic — an element that leans toward the pointer.
+ *
+ * Deceptively subtle to get right. Three things separate a magnetic button that feels expensive
+ * from one that feels broken:
+ *
+ * 1. **The pull must be spring-driven, not proportional.** Setting
+ *    `translate = pointerOffset * 0.2` means the element is rigidly locked to the cursor with no
+ *    weight. A spring gives it mass, so it lags into position and overshoots slightly on release.
+ *
+ * 2. **The influence zone must extend beyond the element.** If the effect only starts on hover,
+ *    the element jumps the instant the cursor crosses its edge. Tracking from a surrounding
+ *    radius means it is already reaching toward the cursor before contact.
+ *
+ * 3. **Displacement must be capped, not just scaled.** Otherwise a cursor at the far edge of a
+ *    large influence zone drags the element clean out of its layout box.
+ */
+interface MagneticOptions extends BaseBehaviourOptions {
+    /** Maximum displacement in pixels. Default `12`. */
+    strength?: number;
+    /**
+     * Radius in pixels around the element within which the pointer has influence.
+     * Measured from the element's edges, not its centre. Default `120`.
+     */
+    radius?: number;
+    /** Spring stiffness. Higher is snappier. Default `260`. */
+    stiffness?: number;
+    /** Spring damping. Higher settles sooner. Default `24`. */
+    damping?: number;
+    /** Also scale the element on approach. `1.04` is a 4% grow. Default `1`. */
+    scale?: number;
+    /** Also rotate toward the pointer, in degrees at maximum displacement. Default `0`. */
+    rotate?: number;
+    /** Restrict movement to one axis. Default `'both'`. */
+    axis?: 'both' | 'x' | 'y';
+    /**
+     * Apply the transform to a child element instead of the host.
+     *
+     * Useful when the host must stay put for layout or hit-testing reasons — a nav link whose
+     * text should lean but whose click target should not move.
+     */
+    target?: string;
+}
+declare const magnetic: BehaviourDefinition<MagneticOptions, HTMLElement>;
+
+/**
+ * Every built-in behaviour, keyed by name. Used by the CLI and docs site for discovery.
+ * Import individual behaviours in application code so the rest tree-shake away.
+ */
+declare const behaviours: {
+    readonly magnetic: BehaviourDefinition<MagneticOptions, HTMLElement>;
+    readonly tilt: BehaviourDefinition<TiltOptions, HTMLElement>;
+    readonly marquee: BehaviourDefinition<MarqueeOptions, HTMLElement>;
+    readonly 'split-text': BehaviourDefinition<SplitTextOptions, HTMLElement>;
+    readonly 'scroll-reveal': BehaviourDefinition<ScrollRevealOptions, HTMLElement>;
+    readonly parallax: BehaviourDefinition<ParallaxOptions, HTMLElement>;
+    readonly ripple: BehaviourDefinition<RippleOptions, HTMLElement>;
+};
+type BehaviourName = keyof typeof behaviours;
+
+export { type BaseBehaviourOptions as B, type MagneticOptions as M, type ParallaxOptions as P, type RippleOptions as R, type StaggerOptions as S, type TiltOptions as T, type BehaviourDefinition as a, type BehaviourHandle as b, type BehaviourInstance as c, type BehaviourName as d, type MarqueeOptions as e, type ScrollRevealOptions as f, type SplitTextOptions as g, type SplitTextResult as h, type SplitUnit as i, type StaggerFrom as j, behaviours as k, captureStyles as l, defineBehaviour as m, getSplitResult as n, magnetic as o, marquee as p, mountBehaviour as q, parallax as r, ripple as s, scrollReveal as t, split as u, splitText as v, stagger as w, staggerDuration as x, tilt as y };