@deriv-com/dds-marketing 1.0.1 → 1.1.0

package/dist/components/core/background/halftone.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The halftone, drawn on a canvas and only when it has to be.
+ *
+ * A grid of dots, each as large and as bright as the glow is where it sits: full at the glow's
+ * centre, falling away along a soft ellipse, and gone at the edges. The glow rests at the middle of
+ * the band's bottom edge and — where the band allows it — follows the pointer. The dots themselves
+ * answer the pointer too: a moving pointer shoves the ones near it aside and a click sends a ripple
+ * out from where it landed, and each dot springs back to its place in the grid.
+ *
+ * What it costs is the reason it is written this way rather than as CSS or as an animation loop:
+ *
+ * - It draws on change and nowhere else. A resize draws one frame; a pointer draws frames only
+ *   while the glow is catching up or a dot is still moving. The resting drift is the one thing that
+ *   keeps it drawing, at half the display's rate, and only while the band is on screen and motion
+ *   is allowed — with the drift set to nothing, a band nobody is touching runs no code at all.
+ * - A band out of view draws nothing, and catches up with one frame when it returns.
+ * - The bitmap is held to twice the CSS pixel density, which is all a dot this small can use.
+ * - The dots are batched by brightness into a few dozen paths, so a frame is a few dozen fills
+ *   rather than one per dot. Drawing visits only the rows below the pattern's edge, rejects a dot
+ *   too small to be seen before working out its light — every dot, while the size floor keeps the
+ *   screen across the whole band — and draws a dot under a pixel and a half as a square, which
+ *   nobody can tell from a circle at that size.
+ * - Pointer events only record where the pointer is. The frame reads the band's position once and
+ *   acts on it, so a fast mouse costs one layout read a frame rather than one per event; a shove or
+ *   a ripple visits the grid cells it can reach, and the spring visits only the dots still moving.
+ *
+ * Every default comes from a token: the inks are the canvas's computed `color` (the glow's edge) and
+ * `outline-color` (its centre), the grid is
+ * size.halftone.pitch and size.halftone.dot, and the glow's movement is the canvas's transition
+ * duration and timing function. The rest are settings this file names, and `retune` overrides any
+ * of them while a pattern is being decided — the preview's Tune panel, and nothing a page uses.
+ */
+export interface HalftoneOptions {
+    /** Whether the pattern answers the pointer. Ignored for reduced motion. */
+    interactive: boolean;
+    /** Whether the resting glow drifts on its own. Ignored for reduced motion. */
+    animated: boolean;
+    /**
+     * Where the pointer is listened for, when that is not the band itself — a Background used as a
+     * layer behind a block's content, where the content covers the layer and the pointer never
+     * reaches it. Positions are still measured against the band.
+     */
+    host?: HTMLElement;
+}
+export interface Halftone {
+    /** Stop listening, stop drawing, and let go of every observer. */
+    destroy: () => void;
+}
+/** Every setting the pattern is drawn with. Colours are any CSS colour; lengths are CSS pixels. */
+export interface HalftoneTuning {
+    /** The dots' colour at the edge of the glow. Defaults to the canvas's `color`. */
+    base: string;
+    /** The dots' colour at the glow's centre. Defaults to the canvas's outline colour. */
+    active: string;
+    /** How opaque the faintest dots are, from 0 to 1 — what makes the edge a fade, not a line. */
+    floor: number;
+    /**
+     * How strong the whole pattern is, from 0 to 1: every dot's opacity, scaled. The pattern's shape
+     * is untouched — the glow, the fade, the floor — only how loudly it is drawn.
+     */
+    opacity: number;
+    /** The widest a dot grows, at the glow's centre. size.halftone.dot. */
+    dot: number;
+    /** Centre to centre, between neighbouring dots. size.halftone.pitch. */
+    pitch: number;
+    /** How wide the glow reaches, as a share of the band's width. */
+    reachX: number;
+    /** How tall the glow reaches, as a share of the band's height. */
+    reachY: number;
+    /**
+     * How large the glow is while a pointer is over the band, as a share of its resting size. Below 1
+     * the light gathers under the pointer instead of washing across the band it rested across.
+     */
+    hoverScale: number;
+    /**
+     * Where the pattern begins, as a share of the band's height from the top. Above it no dot is
+     * drawn, whatever the glow is doing — 0.3 would keep the pattern to the band's lower seven tenths.
+     */
+    top: number;
+    /** How soft the pattern's upper edge is, as a share of the band's height. */
+    topFade: number;
+    /**
+     * The smallest a dot gets, however far it is from the glow, as a share of its widest — what
+     * keeps the screen of dots across the whole band rather than only around the glow. 0 lets the
+     * dots far from the glow shrink to nothing.
+     */
+    sizeFloor: number;
+    /** The highest the glow may rise towards the pointer, as a share of the band's height from the top. */
+    ceiling: number;
+    /** How sharply the glow falls off — higher is a tighter, harder-edged glow. */
+    falloff: number;
+    /**
+     * How far the glow's edge wanders from a smooth ellipse, from 0 to 1. A slow field of waves warps
+     * the distance each dot is lit by, so the pool of light has lobes and inlets that drift as it
+     * moves — light on a surface rather than a spotlight. 0 is the plain ellipse.
+     */
+    texture: number;
+    /**
+     * How strong a soft wash of the dots' own ink is under the glow, from 0 to 1 — the light the dots
+     * are lit by, as well as the dots. It follows the glow and takes its shape. 0 draws dots alone.
+     */
+    bloom: number;
+    /** Where the glow rests, as a share of the band's width. */
+    restX: number;
+    /** Where the glow rests, as a share of the band's height. */
+    restY: number;
+    /** How long the glow takes to catch up with the pointer and to glide back to rest, in ms. */
+    follow: number;
+    /** How far the resting glow drifts either side of its rest, as a share of the band's width. 0 holds it still. */
+    drift: number;
+    /** How far it rises and falls as it drifts, as a share of the band's height. */
+    driftRise: number;
+    /** How long one sweep of the drift takes, in seconds — longer is slower. */
+    driftPeriod: number;
+    /** How far from a moving pointer the dots are shoved aside, in px. 0 turns the shove off. */
+    proximity: number;
+    /** How hard the dots resist being shoved — higher moves them less. */
+    resistance: number;
+    /** How long a shoved dot takes to settle back into the grid, in seconds. */
+    returnDuration: number;
+    /** How far a click's ripple reaches, in px. 0 turns the ripple off. */
+    shockRadius: number;
+    /** How hard a click's ripple pushes the dots it reaches. */
+    shockStrength: number;
+}
+/**
+ * Override settings on every halftone on the page, live. For deciding a pattern — the preview's
+ * Tune panel calls it — and never for a page: what a page draws is what the tokens and the
+ * settings above say.
+ */
+export declare function retune(next: Partial<HalftoneTuning>): void;
+/** The settings the last halftone drew with, overrides included — for a panel to show. */
+export declare function currentTuning(): HalftoneTuning | null;
+export declare function halftone(root: HTMLElement, canvas: HTMLCanvasElement, options: HalftoneOptions): Halftone;