effect-motion 0.4.0 → 0.5.0

package/dist/Color.js

@@ -1,8 +1,44 @@
+/**
+ * Colors: construction, adjustment, and conversion.
+ *
+ * @remarks
+ * Reach for {@link hex} for CSS strings, {@link rgba} for byte components,
+ * or {@link tw} for the built-in Tailwind palette. Perceptual spaces
+ * ({@link oklch}, {@link lab}) are available when you want even lightness
+ * across hues.
+ *
+ * Values are immutable and every adjustment is a dual, so operations
+ * compose in either call style. Colors interpolate, so any fill or stroke
+ * animates with the ordinary tween animators.
+ *
+ * @example
+ * ```typescript
+ * import * as Color from "effect-motion/Color";
+ *
+ * const brand = Color.hex("#7f5af0");
+ * const dim = brand.pipe(Color.darken(0.6), Color.alpha(0.75));
+ * ```
+ */
 import chroma from "chroma-js";
 import { Schema } from "effect";
 import * as Function from "effect/Function";
 import * as Pipeable from "effect/Pipeable";
 const clamp = (value, minimum, maximum) => Math.min(Math.max(value, minimum), maximum);
+/**
+ * A color with an alpha channel.
+ *
+ * @remarks
+ * Build one with a constructor below — {@link hex} for CSS strings,
+ * {@link rgba} for byte components, {@link tw} for the Tailwind palette —
+ * rather than the class directly.
+ *
+ * RGB channels are 0–255 while alpha is 0–1, matching CSS. Colors are
+ * immutable and pipeable, so adjustments compose:
+ * `Color.hex("#7f5af0").pipe(Color.darken(0.5), Color.alpha(0.8))`.
+ *
+ * Colors are interpolable, so any fill or stroke can be animated with the
+ * ordinary tween animators.
+ */
 export class Color extends Schema.TaggedClass()("Color", {
     "~r": Schema.Number,
     "~g": Schema.Number,
@@ -44,11 +80,35 @@ const fromChroma = (color) => {
         "~a": color._rgb._unclipped[3],
     });
 };
+/** Whether `value` is a {@link Color}. */
 export const is = (value) => {
     return value instanceof Color;
 };
+/**
+ * A color from red, green, blue (each 0–255) and optional alpha (0–1).
+ *
+ * @defaultValue `alpha` — `1`
+ *
+ * @example
+ * ```typescript
+ * Color.rgba(22, 22, 29)
+ * ```
+ */
 export const rgba = (r, g, b, alpha) => Color.of(r, g, b, alpha);
-/** Parse a CSS color string (`#rgb`, `#rrggbb`, `#rrggbbaa`, named, `rgb()`, …). */
+/**
+ * Parse a CSS color string — the most convenient constructor.
+ *
+ * @remarks
+ * Accepts everything CSS does: `#rgb`, `#rrggbb`, `#rrggbbaa`, named colors
+ * like `"rebeccapurple"`, and functional forms like `rgb()` / `hsl()`.
+ *
+ * @param value - A CSS color string.
+ *
+ * @example
+ * ```typescript
+ * Color.hex("#7f5af0")
+ * ```
+ */
 export const hex = (value) => {
     const c = chroma(value);
     const [r, g, b] = c.rgb();
@@ -92,6 +152,7 @@ export const gl = (g, l, r, alpha) => {
 };
 const secondIsColor = (args) => is(args[1]);
 const firstIsColor = (args) => is(args[0]);
+/** Set a color's opacity (0–1), leaving its channels untouched. */
 export const alpha = Function.dual(firstIsColor, (self, amount) => {
     return new Color({
         "~r": self["~r"],
@@ -100,18 +161,34 @@ export const alpha = Function.dual(firstIsColor, (self, amount) => {
         "~a": amount,
     });
 });
+/** Darken by `amount` steps in Lab space. @defaultValue `amount` — `1` */
 export const darken = Function.dual(firstIsColor, (self, amount) => {
     return fromChroma(toChroma(self).darken(amount));
 });
+/** Brighten by `amount` steps in Lab space. @defaultValue `amount` — `1` */
 export const brighten = Function.dual(firstIsColor, (self, amount) => {
     return fromChroma(toChroma(self).brighten(amount));
 });
+/** Increase saturation by `amount` steps. @defaultValue `amount` — `1` */
 export const saturate = Function.dual(firstIsColor, (self, amount) => {
     return fromChroma(toChroma(self).saturate(amount));
 });
+/** Reduce saturation by `amount` steps. @defaultValue `amount` — `1` */
 export const desaturate = Function.dual(firstIsColor, (self, amount) => {
     return fromChroma(toChroma(self).desaturate(amount));
 });
+/**
+ * Blend two colors, `amount` of the way from `self` to `color`.
+ *
+ * @remarks
+ * `mode` picks the color space the blend travels through, which changes the
+ * intermediate hues considerably: `"lab"` (the animators' default) keeps
+ * perceptual evenness, while `"rgb"` can pass through muddy midpoints.
+ *
+ * @param color - The color to blend toward.
+ * @param amount - 0 keeps `self`, 1 gives `color`.
+ * @param mode - Interpolation space.
+ */
 export const mix = Function.dual(secondIsColor, (self, color, amount, mode) => {
     const colorMix = chroma.mix(toChroma(self), toChroma(color), amount, mode);
     return fromChroma(colorMix);
@@ -181,8 +258,14 @@ export const bytes = (self) => ({
     b: Math.round(self.b),
     a: Math.round(self.a * 255),
 });
+/** Opaque black. */
 export const black = rgba(0, 0, 0, 1);
+/** Opaque white. */
 export const white = rgba(255, 255, 255, 1);
+/**
+ * Fully transparent — the default scene background, which leaves whatever
+ * is behind the composition showing through.
+ */
 export const transparent = rgba(0, 0, 0, 0);
 export const twMap = {
     slate: {
@@ -524,6 +607,23 @@ export const twMap = {
         "950": oklch(0.271, 0.105, 12.094),
     },
 };
+/**
+ * A color from the Tailwind palette.
+ *
+ * @remarks
+ * A ready-made, perceptually even set of hues — handy for getting a scene
+ * looking coherent without hand-picking values.
+ *
+ * @param color - Palette name, e.g. `"violet"`.
+ * @param shade - Lightness step, `"50"` (lightest) to `"950"` (darkest).
+ * @param alpha - Opacity, 0–1.
+ * @defaultValue `shade` — `"400"`; `alpha` — `1`
+ *
+ * @example
+ * ```typescript
+ * Color.tw("violet", "500")
+ * ```
+ */
 export const tw = (color, shade = "400", alpha = 1) => {
     const value = twMap[color][shade];
     return new Color({

package/dist/EffectMotionError.d.ts

@@ -1,10 +1,27 @@
 declare const EffectMotionError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
     readonly _tag: "EffectMotionError";
 } & Readonly<A>;
+/**
+ * The library's error type, raised when something outside the engine fails.
+ *
+ * @remarks
+ * Used at the boundaries where the outside world can go wrong — fetching a
+ * font, decoding an image, talking to the GPU. Because it is a tagged error,
+ * it appears in an Effect's error channel and can be caught by tag, rather
+ * than thrown.
+ *
+ * Author mistakes inside a scene are deliberately NOT this: animating a
+ * field that has no value, or orbiting without a point of interest, fail
+ * loudly as defects, because they are bugs to fix rather than conditions to
+ * handle.
+ *
+ * `cause` carries the underlying failure when there is one.
+ */
 export declare class EffectMotionError extends EffectMotionError_base<{
     readonly message: string;
     readonly cause: unknown;
 }> {
+    /** Build an error with a message and an optional underlying cause. */
     static of(message: string, cause?: unknown): EffectMotionError;
 }
 export {};

package/dist/EffectMotionError.js

@@ -1,5 +1,22 @@
 import { Data } from "effect";
+/**
+ * The library's error type, raised when something outside the engine fails.
+ *
+ * @remarks
+ * Used at the boundaries where the outside world can go wrong — fetching a
+ * font, decoding an image, talking to the GPU. Because it is a tagged error,
+ * it appears in an Effect's error channel and can be caught by tag, rather
+ * than thrown.
+ *
+ * Author mistakes inside a scene are deliberately NOT this: animating a
+ * field that has no value, or orbiting without a point of interest, fail
+ * loudly as defects, because they are bugs to fix rather than conditions to
+ * handle.
+ *
+ * `cause` carries the underlying failure when there is one.
+ */
 export class EffectMotionError extends Data.TaggedError("EffectMotionError") {
+    /** Build an error with a message and an optional underlying cause. */
     static of(message, cause) {
         return new EffectMotionError({ message, cause });
     }