@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/renderables/effects.d.ts

@@ -0,0 +1,252 @@
+/**
+ * The effect catalogue: shimmer, pulse, sparkle and wheel, which loop for as
+ * long as they are drawn, and fade-in and dissolve-out, which run once and
+ * are done. Each is an `Effect` for `Effected` (`./effect.ts`); the defaults
+ * in `EFFECT_CURVES` are the ones signed off by eye in the effects-feel demo
+ * (`npm run effects-feel`), at 30 fps and at one frame a second.
+ *
+ * Each effect is something a first-time observer already knows from life —
+ * a slow glow, sunlight moving on water, the colours of daylight, fireflies, ink
+ * blooming in water, mist lifting — because a motion the eye recognises
+ * reads as calm and alive, where a motion it has to learn reads as a widget.
+ * What makes those motions familiar is what every curve here keeps:
+ *
+ * - Nothing jumps. Every curve is continuous in time, built from smooth
+ *   noise (`core/noise.ts`) and smooth waveforms, so at one frame a second a cell
+ *   moves a little and at thirty it glides.
+ * - Nothing repeats exactly. Rhythms are perturbed by slow noise, and each
+ *   breath, firefly's flash and pass of light is an event of its own, with
+ *   its own strength and moment, the way no breath or gust is the last one
+ *   again. A weaker event is a shorter one, so its strength costs nothing
+ *   in smoothness.
+ * - Neighbours move together. Variation is spatially coherent — patches,
+ *   filaments, fronts — never per-cell static.
+ * - Light only ever lights, and never takes the words away. Ink and the
+ *   fill under it both move toward the light and never darken, each by its
+ *   own share: the share a colour can take while every cell it is drawn in
+ *   still reads at its resting contrast or WCAG AA, whichever is lower. A
+ *   cell with contrast to spare glows brightly; one with none barely moves.
+ * - Elements are apart. Each sits at its own `z` in the noise, so two
+ *   elements under one effect do not move in lockstep.
+ *
+ * Colour moves are in OKLCH, where equal steps look equal. A curve's `ease`
+ * maps its intensity in [0, 1] — how strongly the effect acts on a cell at a
+ * moment — onto its swing, for the loops and the transitions alike.
+ *
+ * [LAW:no-ambient-temporal-coupling] No curve reads a clock; `t` is the
+ * effect's argument, so the frame owner decides when to sample.
+ *
+ * Every import below names something the package exports, but for `noise`,
+ * which the docs' effects playground page supplies itself: each of its
+ * cards runs this file's own declarations as the program a visitor edits
+ * (`examples/effects-playground/programs.ts`), on the published library.
+ */
+import { ColorRgba } from "../core/color.js";
+import { type Ease } from "../core/easing.js";
+import type { CellColors, Effect, EffectCell } from "./effect.js";
+/** What a loop does to one colour at strength `w` in [0, 1]: at 0, nothing. */
+export type Touch = (color: ColorRgba, w: number) => ColorRgba;
+/** How strongly a loop acts on a cell at a moment, in [0, 1]; `onColors` holds a field outside it to it. */
+export type Field = (cell: EffectCell, t: number) => number;
+/** A looping effect: what it does to a colour, and where and when, how strongly. */
+export interface Loop {
+    readonly touch: Touch;
+    readonly field: Field;
+}
+/**
+ * A cell's ink and ground as the screen shows them, and which of the two are
+ * the terminal's: what an `Effect` is handed for that cell.
+ */
+export interface Pair extends CellColors {
+    readonly terminal: EffectCell["terminal"];
+}
+/**
+ * How much of `touch` each of `colors` (hex) can take: the largest share in
+ * [0, 1] at which every pair in `pairs` that shows it, touched at the same
+ * strength, still reads at its resting contrast or `LEGIBLE`, whichever is
+ * lower. A colour in a pair but not in `colors` takes none, and so does one
+ * the terminal supplies, whatever its hex, as in `onColors`. One of `colors`
+ * no pair writes has nothing to be measured against, and throws.
+ *
+ * Colours are settled lightest first, each against every partner: one
+ * already settled at its share, one not yet settled as it is. So the lighter
+ * colour of a cell takes the light first and its darker partner spends
+ * whatever contrast is left — pale lettering lifting off a dark fill gives
+ * the fill room to glow — and a darker colour left as it is always holds,
+ * because its lighter partner was settled against exactly that.
+ */
+export declare function shares(pairs: readonly Pair[], colors: ReadonlySet<string>, touch: Touch): Map<string, number>;
+/**
+ * A loop as an `Effect` on a subject's own colours, by hex, wherever a cell
+ * shows them, each touched at its share of the cell's strength. A powerline
+ * strip's fill is the ground of its cells and the ink of the seam glyphs
+ * between them, so the arrow moves with the cell it points out of. A colour
+ * the terminal supplies (`EffectCell.terminal`) is not the subject's, whatever
+ * its hex, and takes no share.
+ */
+export declare function onColors(share: ReadonlyMap<string, number>, loop: Loop): Effect;
+/** How the curves below are tuned: one period (or duration), ease and swing. */
+export interface Curve {
+    /** Seconds: a looping effect's period, a transition's duration. */
+    readonly seconds: number;
+    /** Intensity in [0, 1] to the fraction of `swing` applied. One that overshoots, as a CSS `cubic-bezier` may, saturates: an effect never acts past its swing. */
+    readonly ease: Ease;
+    /** How far the move goes at full intensity, in [0, 1]; what 1 means is the effect's. */
+    readonly swing: number;
+}
+/**
+ * Each effect's curve as it was signed off. Every loop's period is a prime
+ * number of seconds, so no two loops come back into step within a sitting.
+ * The periods are long on purpose: at one frame a second a loop's colour
+ * moves by no more than a just-noticeable step from one frame to the next.
+ */
+export declare const EFFECT_CURVES: {
+    readonly shimmer: {
+        readonly seconds: 109;
+        readonly ease: Ease;
+        readonly swing: 0.9;
+    };
+    readonly pulse: {
+        readonly seconds: 43;
+        readonly ease: Ease;
+        readonly swing: 0.85;
+    };
+    readonly sparkle: {
+        readonly seconds: 139;
+        readonly ease: Ease;
+        readonly swing: 0.95;
+    };
+    readonly wheel: {
+        readonly seconds: 907;
+        readonly ease: Ease;
+        readonly swing: 1;
+    };
+    readonly fade: {
+        readonly seconds: 20;
+        readonly ease: Ease;
+        readonly swing: 1;
+    };
+    readonly dissolve: {
+        readonly seconds: 30;
+        readonly ease: Ease;
+        readonly swing: 1;
+    };
+};
+/** The lights the loops were signed off casting, warm as sunlight and fireflies are. */
+export declare const EFFECT_LIGHTS: {
+    readonly sun: ColorRgba;
+    readonly firefly: ColorRgba;
+};
+/** How far a shimmer's light reaches either side of its centre, in columns, as signed off. */
+export declare const SHIMMER_WIDTH = 24;
+/**
+ * A colour under `glow`: the one way every light here falls. It moves `w` of
+ * the way toward the light's colour, and never below its own lightness —
+ * light can warm a colour and lift it, never darken it. A colour already
+ * lighter than the light only warms, and white, which has no warmer shade at
+ * its lightness, stays white.
+ */
+export declare function light(glow: ColorRgba): Touch;
+/**
+ * Pulse, as a gentle glow on one element of a screen: the colours handed to
+ * it, an element's own, warm into `light` and settle back, over and over, the
+ * way an indicator breathes while something is waiting. Swing: how far into
+ * the light it goes at the top of a beat, 0–1. The element glows as one —
+ * every cell it is drawn in at once — and the colours not handed to it, the
+ * rest of the screen, stay as they are, so what pulses is what was chosen.
+ * Each element keeps a time of its own, a little quicker or slower than
+ * another's by `z`, and no beat is quite the last: the rhythm wanders ahead
+ * and behind its metronome and each beat goes a little deeper or shallower
+ * than the one before. A beat starts and ends in rest, so `t = 0` draws the
+ * element untouched.
+ */
+export declare function pulse(curve: Curve, glow: ColorRgba, z: number): Loop;
+/**
+ * Shimmer, as sunlight moving across water. Swing: how far into `light` the
+ * brightest glint goes, 0–1. A soft band of light, `width` columns either
+ * side of its centre, crosses columns 0 to `span`, entering and leaving
+ * fully off the row, `STRIDE` columns in about three quarters of a period. Its passes
+ * come the way light comes and goes on water as clouds move: while the sun
+ * is out they are bright and follow close on one another, one sometimes
+ * catching the last; under cloud they thin to faint ones with the row still
+ * for a while between, and the light is never gone for long. Each crosses at its own unhurried pace, drifting a little ahead
+ * and behind as it goes. Inside a band the light is a faint glow broken
+ * into a glitter path — bright filaments where two ripples cross — carried
+ * on a slow current and re-forming as they go, so the glints dance while
+ * the band glides. Before the first pass enters, the row is untouched.
+ */
+export declare function shimmer(curve: Curve, span: number, width: number, glow: ColorRgba, z: number): Loop;
+/**
+ * Sparkle, as fireflies. Swing: how far into the firefly's `light` a glow
+ * goes at its brightest, 0–1. About one firefly to every eight columns of
+ * `span`, each keeping near a home of its own. A firefly flashes — kindles,
+ * drifts a few cells glowing, slowing as it fades — then flies on in the
+ * dark and flashes again somewhere a few cells off, the way fireflies at
+ * dusk are seen: a short lit stroke, then gone, each time a little
+ * elsewhere. Each keeps its own irregular time, now and then letting a turn
+ * pass dark, so most moments a few are lit, at different brightnesses. Its
+ * light is a soft halo several cells wide, brightest where it is, so as it
+ * drifts the glow slides between cells rather than hopping. `seconds` is a firefly's
+ * turn: its brightest flash, rise and fall, takes `FLASH` of it, and a
+ * dimmer one less.
+ */
+export declare function sparkle(curve: Curve, span: number, glow: ColorRgba, z: number): Loop;
+/**
+ * How much of a cell shows at `t`: 1 is the cell as drawn, 0 is the cell gone
+ * to the terminal's ground. Read per cell, so cells can arrive or leave apart. One
+ * outside [0, 1] is held to it.
+ */
+export type Visibility = (cell: EffectCell, t: number) => number;
+/**
+ * A cell mixed toward the terminal's `ground` by how hidden it is: its fill
+ * toward the ground, and its ink toward that fill, so an element with fills
+ * of its own — a powerline strip — arrives and leaves whole, fill and words
+ * together, never as bare coloured blocks. Invisible is ink and fill equal
+ * to the ground. `swing` scales the hiding — 1 reaches fully invisible. A
+ * cell wholly shown is returned as it was.
+ */
+export declare function veiled(visibility: Visibility, swing: number, ground: ColorRgba): Effect;
+/**
+ * An effect that runs once: a fade-in or a dissolve-out from its start time
+ * over its curve's `seconds`. `done(t)` is true from the moment every cell
+ * has arrived or gone, so the caller knows when to stop drawing an element
+ * that is leaving, or to drop the effect from one that has arrived.
+ */
+export interface Transition {
+    readonly effect: Effect;
+    done(t: number): boolean;
+}
+/**
+ * Fade-in starting at `start`, as ink blooming in water: patches of the
+ * element surface first and the rest follows outward from them, each cell
+ * rising smoothly over its own part of the duration. Whole at
+ * `start + seconds`.
+ */
+export declare function fadeIn(curve: Curve, start: number, z: number, ground: ColorRgba): Transition;
+/**
+ * Dissolve-out starting at `start`, as mist lifting: the element thins in
+ * drifting patches, each cell fading smoothly over its own part of the
+ * duration, until nothing is left at `start + seconds`. Mist does not lift
+ * in one breath: towards the end, patches of what is left — the later a cell
+ * goes, the likelier — rise back part way, as the last of it eddies, before
+ * they thin away for good.
+ */
+export declare function dissolveOut(curve: Curve, start: number, z: number, ground: ColorRgba): Transition;
+/**
+ * Wheel, as the colour of daylight going round: every hue turning the whole
+ * way round once a period — far too slowly to be seen moving, so a glance
+ * sees a steady palette and an hour's absence a different one — each
+ * segment of the element at its own pace. Swing: how far the segments stray
+ * from one another, 0–1, 1 being half a turn apart. A segment is a fill of
+ * the element's own — one of `fills`, the colours it draws as a ground — and
+ * it turns at its own pace wherever it is drawn: as the ground of its cells,
+ * and as the ink of the seam glyph pointing out of it into the next, so a
+ * powerline cap keeps the colour of the cell it caps. An ink that is no fill
+ * turns with the ground it sits on, so a cell's words and fill turn
+ * together; on the terminal's ground, a run of text's ink is a segment of
+ * its own. A segment's stray is slow noise of its own, at `STRAY_PERIODS`,
+ * so no two keep step, and the row never shows one spread of hues twice.
+ * Lightness and chroma are kept, so the words read as they did; the turn
+ * only happens to `colors`, the element's own, never the terminal's.
+ */
+export declare function wheel(curve: Curve, colors: ReadonlySet<string>, fills: ReadonlySet<string>, z: number): Effect;