@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/renderables/effects.d.ts

@@ -1,7 +1,8 @@
 /**
  * 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
+ * long as they are drawn, fade-in and dissolve-out, which run once and are
+ * done, a blink and a bold pulse, which move an attribute on a beat, and a
+ * gradient, which lays a colour ramp across an element and may move it. 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, and
  * `EFFECT_CATALOGUE` makes every one of them at those, by name, one way.
@@ -13,7 +14,10 @@
  * One effect here is not ambience but a signal, and keeps none of this on
  * purpose: `steppedInk` steps its ink through colours on a beat, the news
  * that something is at its limit, and jumps from slot to slot where the
- * loops hold still. What makes the loops' motions familiar is what every
+ * loops hold still. Nor is `gradient` a light: it paints an ink rather than
+ * lighting it, so it may darken one, and a ramp scrolled across it jumps
+ * where the ramp wraps unless its ends are one colour. Of the list below it
+ * keeps the words. What makes the loops' motions familiar is what every
  * curve of theirs keeps:
  *
  * - Nothing jumps. Every curve is continuous in time, built from smooth
@@ -46,9 +50,11 @@
  * cards runs this file's own declarations as the program a visitor edits
  * (`examples/effects-playground/programs.ts`), on the published library.
  */
+import { Animation } from "../core/animation.js";
 import { ColorRgba } from "../core/color.js";
-import { type Ease } from "../core/easing.js";
-import { type Drawn, type Effect, type EffectCell } from "./effect.js";
+import { type Beat, type Timing } from "../core/easing.js";
+import type { ColorRamp } from "../themes/ramp.js";
+import { type CellAttributes, type Drawn, type Effect, type 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;
 /**
@@ -98,21 +104,53 @@ export declare function shares({ pairs, depth, theme }: Drawn, colors: ReadonlyS
  * drawing what an earlier one drew costs no settling.
  */
 export declare function onColors(loop: Loop, colors?: ReadonlySet<string>): Effect;
+/**
+ * A ramp laid across the element: each lit cell's ink is the colour `ramp`
+ * shows at `t` at the cell's column, the element's leftmost cell reading
+ * the ramp's first stop and its rightmost its last, each at its cell's
+ * centre — or, where that colour would not read on the cell's ground, the
+ * nearest that does (`legibleInks`, as `steppedInk` writes its steps). A
+ * ramp that moves (`ColorRamp.moving`) scrolls along the element and turns
+ * its hues, and the frame changes when the ramp does — every frame for a
+ * loop, never again once a tween settles; a still one is
+ * `Animation.constant(ramp)`. Lit cells are those whose ink is one of
+ * `colors`, named as a style names them (`"#a6e3a1"`, `"bright_green"`),
+ * opaque, and matched as the screen shows them at the frame's depth — so
+ * below truecolor every ink that lands on the same palette colour is lit —
+ * by default every colour the element sets itself — never an ink the terminal supplies: a
+ * rule's line by its colour and not its title, a panel's border and not its
+ * body. The element is where its frame lists
+ * cells, as the fireflies read it, so a padded or confined element has the
+ * ramp across what it shows. On a sixteen-colour terminal nothing moves
+ * (`stillOnSlots`): a gradient there is jumps between slots, and the cells
+ * hold as drawn.
+ */
+export declare function gradient(ramp: Animation<ColorRamp>, colors?: readonly string[]): Effect;
 /**
  * A loop as an `Effect` on colours by hex, each touched at the share
  * `share` gives it of the cell's strength in a frame drawing what `Drawn`
  * says; a colour it gives none, and one the terminal supplies, stays as it is.
  */
 export declare function atShares(loop: Loop, share: (drawn: Drawn) => ReadonlyMap<string, number>): 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 the curves below are tuned: a `Timing` — seconds, a looping effect's
+ * period or a transition's duration, and an ease, intensity in [0, 1] to
+ * the fraction of `swing` applied; one that overshoots, as a CSS
+ * `cubic-bezier` may, saturates, since an effect never acts past its swing —
+ * and the swing itself.
+ */
+export interface Curve extends Timing {
     /** How far the move goes at full intensity, in [0, 1]; what 1 means is the effect's. */
     readonly swing: number;
 }
+/** Throws, naming the field, unless `curve` has a positive, finite `seconds` and a `swing` in [0, 1]. */
+export declare function requireCurve(curve: Curve): void;
+/**
+ * Throws, naming `what`, unless `z` is a finite place in the noise. Noise at
+ * a place that is not a number is not a number, which no effect could tell
+ * from a dim cell or an empty sky. [LAW:no-silent-failure]
+ */
+export declare function requireZ(what: string, z: number): void;
 /**
  * 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.
@@ -122,32 +160,32 @@ export interface Curve {
 export declare const EFFECT_CURVES: {
     readonly shimmer: {
         readonly seconds: 109;
-        readonly ease: Ease;
+        readonly ease: import("../core/easing.js").Ease;
         readonly swing: 0.9;
     };
     readonly pulse: {
         readonly seconds: 43;
-        readonly ease: Ease;
+        readonly ease: import("../core/easing.js").Ease;
         readonly swing: 0.85;
     };
     readonly sparkle: {
         readonly seconds: 139;
-        readonly ease: Ease;
+        readonly ease: import("../core/easing.js").Ease;
         readonly swing: 0.95;
     };
     readonly wheel: {
         readonly seconds: 907;
-        readonly ease: Ease;
+        readonly ease: import("../core/easing.js").Ease;
         readonly swing: 1;
     };
     readonly fade: {
         readonly seconds: 20;
-        readonly ease: Ease;
+        readonly ease: import("../core/easing.js").Ease;
         readonly swing: 1;
     };
     readonly dissolve: {
         readonly seconds: 30;
-        readonly ease: Ease;
+        readonly ease: import("../core/easing.js").Ease;
         readonly swing: 1;
     };
 };
@@ -239,13 +277,48 @@ export declare function veiled(visibility: Visibility, swing: number): Effect;
  * draws it at the time since it began. `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.
- * Until then the effect's frame changes every frame, and from then never:
- * its `nextChange` is `done` read as a time. [LAW:one-source-of-truth]
+ *
+ * `schedule` is when its frame next changes on that clock, whatever the
+ * element draws: what a caller drawing the transition inside an animation —
+ * a lifecycle — says its frame does, since the frame it hands over carries
+ * no word of its own (`stampFrame`, `../core/animation.ts`). Until done it changes
+ * every frame, or on each hold of a beat (`onBeat`), and from then never.
+ * [LAW:one-source-of-truth] `done` is that schedule read as a fact — done
+ * from the first moment it never changes again — so no transition carries
+ * two answers to when it is over.
  */
-export interface Transition {
-    readonly effect: Effect;
+export declare class Transition<E = Effect> {
+    readonly effect: E;
+    readonly schedule: Animation<unknown>;
+    constructor(effect: E, schedule: Animation<unknown>);
     done(t: number): boolean;
 }
+/**
+ * `effect` run once over `seconds` as a `Transition`: what it draws until it
+ * is done, then held. [LAW:single-enforcer] The one rule for when a
+ * transition is done and what it answers after, for a colour effect and a
+ * glyph effect (`./glyph-effects.ts`) alike.
+ */
+export declare function transition<D, F>(seconds: number, effect: (drawn: D) => Animation<F>): Transition<(drawn: D) => Animation<F>>;
+/**
+ * `effect` sampled and held on `beat`: drawn at the moment the hold in
+ * progress began (`Beat.lastChange`), so within a hold every frame is the frame
+ * at its start, and at each hold's start it moves on. A continuous effect
+ * given a short curve becomes one that steps — a `wheel` turning a sixth of
+ * a turn once a second — and at one redraw a second a hold shorter than a
+ * second is skipped, as frames are. [LAW:no-ambient-temporal-coupling] The
+ * held time is a function of `t`, so the same `t` draws the same bytes at
+ * any rate. The frame next changes at a hold's start, and only one the
+ * sampled effect has moved by (`Animation.onBeat`): an effect that moves
+ * every frame turns the beat at the end of this hold, and one that is done
+ * and says never leaves the beat saying never too.
+ *
+ * A transition steps the same way, its schedule with it, so a fade-in on a
+ * beat arrives a hold at a time and is done at the first hold that starts
+ * after it was: an element arriving through it wakes its host on the beats.
+ */
+export declare function onBeat(effect: Effect, beat: Beat): Effect;
+export declare function onBeat<E extends (drawn: never) => Animation<unknown>>(transition: Transition<E>, beat: Beat): Transition<E>;
 /**
  * Fade-in, as ink blooming in water: patches of the element surface first
  * and the rest follows outward from them, each cell rising smoothly over its
@@ -305,17 +378,56 @@ export interface ColorStep {
  * that does (`stillOnSlots`). A cell whose ground no offered colour reads
  * on keeps the ink it rested in.
  *
- * The search is settled once for each ink, ground and step, so a frame
+ * The search is settled once for each ground and step — below truecolor,
+ * which colours read on a ground once for that ground — so a frame
  * inside a step redoes none, and nor does a later pass of the beat: at sixty
  * frames a second a one-second step is sixty identical frames, and the
- * frame says it changes next when the step ends (`Beat.end`).
+ * frame changes when the beat does: the signal is the beat mapped to inks.
  * [LAW:no-ambient-temporal-coupling] The beat is `core/easing.ts`'s, and
  * nothing here reads a clock.
  */
 export declare function steppedInk(steps: readonly ColorStep[]): Effect;
+/**
+ * A text attribute turned on and off on a beat: each pass, the cell as its
+ * element drew it for `off` seconds, then with `attribute` on for `on`.
+ */
+export interface Blink {
+    readonly attribute: keyof CellAttributes;
+    readonly off: number;
+    readonly on: number;
+}
+/**
+ * `spec.attribute` blinking: off, the cell as drawn, so that hold's frame is
+ * the identity and writes the element's own bytes; on, the attribute set.
+ * It changes when its beat does, at a hold's end, and never between.
+ * A blink and a bold pulse are this one function at two specs
+ * (`ATTRIBUTE_DEFAULTS`) [LAW:one-type-per-behavior].
+ */
+export declare function blink({ attribute, off, on }: Blink): Effect;
+/** The names of the effects that move an attribute. */
+export type AttributeLoopName = "blink" | "boldPulse";
+/**
+ * Each attribute effect's spec: a blink hides the words for half of each
+ * second, as a terminal's own blink does, and a bold pulse holds them bold
+ * for the last three tenths of each second.
+ */
+export declare const ATTRIBUTE_DEFAULTS: {
+    readonly blink: {
+        readonly attribute: "conceal";
+        readonly off: 0.5;
+        readonly on: 0.5;
+    };
+    readonly boldPulse: {
+        readonly attribute: "bold";
+        readonly off: 0.7;
+        readonly on: 0.3;
+    };
+};
 /**
  * What a catalogue effect is made for: the element it is drawn on, at `z` in
- * the noise, so two elements under one effect do not move in lockstep. How
+ * the noise, so two elements under one effect drawn from noise do not move in
+ * lockstep. An effect on a beat alone (a blink) draws no noise, and keeps
+ * every element in step, as a terminal's own blink does. How
  * wide the element is, the effect reads off each frame (`Drawn.cells`).
  */
 export interface EffectTarget {
@@ -339,4 +451,5 @@ export type TransitionName = "fade" | "dissolve";
 export declare const EFFECT_CATALOGUE: {
     readonly loops: Readonly<Record<LoopName, (element: EffectTarget, curve?: Curve) => Effect>>;
     readonly transitions: Readonly<Record<TransitionName, (element: EffectTarget, curve?: Curve) => Transition>>;
+    readonly attributes: Readonly<Record<AttributeLoopName, (element: EffectTarget) => Effect>>;
 };