gradiente 2.0.0 → 2.1.0

package/README.md

@@ -1,111 +1,94 @@
-<div align="center">
-
-  <img src="https://raw.githubusercontent.com/Flowscape-UI/gradiente/fff32510afe7e3e1b7b2f73dbf7246843a06d859/assets/logo.svg" alt="gradiente logo" />
-
-  <h1>gradiente</h1>
-
-  <p>Minimalist & lightweight engine for sophisticated web gradients</p>
-
-  <img src="https://raw.githubusercontent.com/Flowscape-UI/gradiente/d8429051f700698f664d8d2392cfa58a604f8e83/assets/flowscape-badge.svg" alt="npm version" />
-  <br />
-
-  <a href="https://www.npmjs.com/package/gradiente">
-    <img src="https://img.shields.io/npm/v/gradiente.svg?style=flat-square&labelColor=d84f4c&color=black" alt="npm version">
-  </a>
-  <a href="https://bundlephobia.com/result?p=gradiente">
-    <img src="https://img.shields.io/bundlephobia/minzip/gradiente?style=flat-square&labelColor=d84f4c&color=black" alt="bundle size"/>
-  </a>
-  <a href="https://github.com/Flowscape-UI/gradiente/blob/main/LICENSE">
-    <img src="https://img.shields.io/github/license/Flowscape-UI/gradiente?style=flat-square&labelColor=d84f4c&color=black" alt="license"/>
-  </a>
-</div>
-
-
-# Gradiente
-
-**Gradiente** is a lightweight gradient parser and transformer for modern rendering systems.
-
-Parse CSS gradients → work with structured data → render anywhere.
-
-> Gradients as data, not strings.
-
----
-
-## Install
-
-```bash
-npm install gradiente
-````
-
----
-
-## Example
-
-```ts
-import { parse, transformTo } from "gradiente";
-
-const gradient = parse("linear-gradient(red, blue)");
-
-const css = transformTo("css", gradient);
-const canvas = transformTo("canvas", gradient);
-
-canvas.draw(ctx, 300, 300);
-```
-
----
-
-## Supported
-
-```ts
-linear-gradient(...)
-repeating-linear-gradient(...)
-
-radial-gradient(...)
-repeating-radial-gradient(...)
-
-conic-gradient(...)
-repeating-conic-gradient(...)
-```
-
----
-
-## What it does
-
-* Parses gradients into structured objects
-* Normalizes angles, positions, and stops
-* Transforms gradients to different targets:
-
-  * CSS
-  * Canvas
-  * (more coming)
-
----
-
-## Built for
-
-* design tools
-* visual editors
-* canvas engines
-* WebGL / Pixi / Konva
-* custom rendering pipelines
-
----
-
-## Status
-
-* [x] linear gradients
-* [x] radial gradients
-* [x] conic gradients
-* [x] canvas + css transformers
-* [ ] docs
-* [ ] playground
-* [ ] more render targets
-
----
-
-## Philosophy
-
-Gradiente treats gradients as a graphics primitive.
-
-Not a string to preserve -
-but data you can transform and render anywhere.
+<div align="center">
+
+  <img src="https://raw.githubusercontent.com/Flowscape-UI/gradiente/fff32510afe7e3e1b7b2f73dbf7246843a06d859/assets/logo.svg" alt="gradiente logo" />
+
+  <h1>gradiente</h1>
+
+  <p>Minimalist & lightweight engine for sophisticated web gradients</p>
+
+  <img src="https://raw.githubusercontent.com/Flowscape-UI/gradiente/d8429051f700698f664d8d2392cfa58a604f8e83/assets/flowscape-badge.svg" alt="npm version" />
+  <br />
+
+  <a href="https://www.npmjs.com/package/gradiente">
+    <img src="https://img.shields.io/npm/v/gradiente.svg?style=flat-square&labelColor=d84f4c&color=black" alt="npm version">
+  </a>
+  <a href="https://bundlephobia.com/result?p=gradiente">
+    <img src="https://img.shields.io/bundlephobia/minzip/gradiente?style=flat-square&labelColor=d84f4c&color=black" alt="bundle size"/>
+  </a>
+  <a href="https://github.com/Flowscape-UI/gradiente/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/Flowscape-UI/gradiente?style=flat-square&labelColor=d84f4c&color=black" alt="license"/>
+  </a>
+</div>
+
+
+# Gradiente
+
+**Gradiente** is a lightweight gradient parser and transformer for modern rendering systems.
+
+Parse CSS gradients → work with structured data → render anywhere.
+
+> Gradients as data, not strings.
+
+
+## Install
+
+```bash
+npm install gradiente
+```
+
+
+## Example
+
+```ts
+import { parse, transformTo } from "gradiente";
+
+const gradient = parse("linear-gradient(red, blue)");
+
+const css = transformTo("css", gradient);
+const canvas = transformTo("canvas", gradient);
+
+canvas.draw(ctx, 300, 300);
+```
+
+The full documentation is published on [gradiente docs](https://flowscape-ui.github.io/gradiente/). Some quick entry points:
+
+- [Getting started](https://flowscape-ui.github.io/gradiente/getting-started.html)
+- [API References](https://flowscape-ui.github.io/gradiente/core-api/working-with-gradients.html)
+- [Custom Gradients](https://flowscape-ui.github.io/gradiente/core-api/custom-gradients.html)
+
+
+## What it does
+
+- Parses gradients into structured objects
+- Normalizes angles, positions, and stops
+- Transforms gradients to different targets:
+  - CSS
+  - Canvas
+  - (more coming)
+
+---
+
+## Built for
+
+* design tools
+* visual editors
+* canvas engines
+* WebGL / Pixi / Konva
+* custom rendering pipelines
+
+---
+
+## Philosophy
+
+Gradiente treats gradients as a graphics primitive.
+
+Not a string to preserve -
+but data you can transform and render anywhere.
+
+## Contributing
+
+Contributions of all kinds (feedback, ideas, bug fixes, documentation) are welcome.
+
+Please open a GitHub issue/discussion before putting in any work that’s not straightforward.
+
+More in [CONTRIBUTING.md](../../CONTRIBUTING.md).

package/dist/index.d.mts

@@ -10,14 +10,14 @@ declare function fromPercent(value: number): number;
 //#region src/utils/math/angle.d.ts
 type AngleUnit = 'deg' | 'rad' | 'turn' | 'grad';
 declare function isAngleUnit(unit: string): unit is AngleUnit;
+declare function isAngle(value: string): boolean;
+declare function angleValueFromString(value: string): number;
 declare function degToRad(value: number): number;
 declare function radToDeg(value: number): number;
 declare function turnToRad(value: number): number;
 declare function gradToRad(value: number): number;
 declare function normalizeAngleDeg(value: number, digits?: number): number;
-declare function normalizeAngleRad(value: number): number;
-declare function toAngleRad(value: number, unit: AngleUnit): number;
-declare function normalizeAngle(value: number, unit: AngleUnit, digits?: number): number;
+declare function normalizeAngleRad(value: number, digits?: number): number;
 //#endregion
 //#region src/abi.d.ts
 /***************************************************************************************************/
@@ -84,6 +84,17 @@ declare function matchExpression(classified: GradientAbiInput[], patternTokens:
 declare function isValid(input: GradientAbiInput[], pattern: string): boolean;
 declare function validate(classified: GradientAbiInput[], pattern: string): boolean;
 //#endregion
+//#region src/gradients/helpers.d.ts
+declare const GRADIENT_COLOR_SPACE: readonly ["oklab", "lch", "oklch", "hsl", "hwb", "lab", "srgb", "srgb-linear", "xyz", "display-p3", "a98-rgb", "prophoto-rgb", "rec2020"];
+declare const GRADIENT_HUE_INTERPOLATIONS: readonly ['shorter', 'longer', 'increasing', 'decreasing'];
+declare const GRADIENT_POLAR_COLOR_SPACES: readonly ["hsl", "hwb", "lch", "oklch"];
+type GradientHueInterpolation = (typeof GRADIENT_HUE_INTERPOLATIONS)[number];
+type GradientColorSpace = (typeof GRADIENT_COLOR_SPACE)[number];
+type GradientPolarColorSpace = (typeof GRADIENT_POLAR_COLOR_SPACES)[number];
+declare function isGradientHueInterpolation(value: string): value is GradientHueInterpolation;
+declare function isGradientColorSpace(value: string): value is GradientColorSpace;
+declare function isGradientPolarColorSpace(value: string): value is GradientPolarColorSpace;
+//#endregion
 //#region src/gradients/types.d.ts
 /**
  * Shared scalar units
@@ -131,7 +142,6 @@ type GradientPosition = {
  */
 type GradientHueInterpolationMethod = "shorter" | "longer" | "increasing" | "decreasing";
 type GradientRectangularColorSpace = "srgb" | "srgb-linear" | "display-p3" | "display-p3-linear" | "a98-rgb" | "prophoto-rgb" | "rec2020" | "lab" | "oklab" | "xyz" | "xyz-d50" | "xyz-d65";
-type GradientPolarColorSpace = "hsl" | "hwb" | "lch" | "oklch";
 type GradientColorInterpolation = {
   kind: "rectangular";
   space: GradientRectangularColorSpace;
@@ -236,21 +246,28 @@ declare abstract class GradientBase<TConfig = unknown> implements IGradientBase<
 }
 //#endregion
 //#region src/gradients/LinearGradient.d.ts
-type LinearGradientConfig = GradientCommonConfig & {
+type GradientInterpolation = {
+  colorSpace: GradientColorSpace;
+  hue?: GradientHueInterpolation;
+};
+type LinearGradientConfig = {
   angle: number;
+  interpolation?: GradientInterpolation;
 };
 declare class LinearGradient extends GradientBase<LinearGradientConfig> {
   readonly type = "linear-gradient";
   constructor(config: GradientData<LinearGradientConfig>);
-  static normalizeConfig(value: {
-    value: number;
-    unit: AngleUnit;
-  } | string): LinearGradientConfig;
+  static normalizeConfig(value: string): LinearGradientConfig;
   static fromString(input: string): LinearGradient;
   static fromAbi(abi: GradientAbi): LinearGradient;
   clone(): this;
   toString(): string;
   protected _validateConfig(_: LinearGradientConfig): void;
+  private static _normalizeConfigInterpolation;
+  private _parseConfigToString;
+  private _parseAngleToString;
+  private _parseInterpolationToString;
+  private static _tokenizeConfigInput;
 }
 //#endregion
 //#region src/gradients/RadialGradient.d.ts
@@ -338,19 +355,6 @@ interface ICanvasPaintResult {
   draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
 //#endregion
-//#region src/gradient-transformer/GradientTransformer.d.ts
-declare class GradientTransformer {
-  private static readonly _modules;
-  private static _initialized;
-  static add(module: IGradientTransformerModule): void;
-  static get(target: string, gradientType: string): IGradientTransformerModule | null;
-  static remove(target: string, gradientType: string): boolean;
-  static to<TOutput = unknown>(target: string, input: string | GradientBase<any>): TOutput;
-  static from<TOutput = unknown>(target: string, gradientType: string, input: TOutput): GradientBase<any>;
-  private static _ensureInitialized;
-  private static _getKey;
-}
-//#endregion
 //#region src/gradient-transformer/modules/css/ModuleTransformerLinearGradientToCss.d.ts
 declare class ModuleTransformerLinearGradientToCss implements IGradientTransformerModule<string> {
   readonly target = "css";
@@ -374,14 +378,14 @@ declare class ModuleTransformerConicGradientToCss implements IGradientTransforme
 //#endregion
 //#region src/gradient-transformer/modules/canvas/ModuleTransformerLinearGradientToCanvas.d.ts
 declare class ModuleTransformerLinearGradientToCanvas implements IGradientTransformerModule<ICanvasPaintResult> {
-  readonly target = "canvas";
+  readonly target = "canvas-2d";
   readonly gradientType = "linear-gradient";
   to(input: GradientBase<any>): ICanvasPaintResult;
 }
 //#endregion
 //#region src/gradient-transformer/modules/canvas/ModuleTransformerRadialGradientToCanvas.d.ts
 declare class ModuleTransformerRadialGradientToCanvas implements IGradientTransformerModule<ICanvasPaintResult> {
-  readonly target = "canvas";
+  readonly target = "canvas-2d";
   readonly gradientType = "radial-gradient";
   to(input: GradientBase<any>): ICanvasPaintResult;
   private _resolve;
@@ -389,7 +393,7 @@ declare class ModuleTransformerRadialGradientToCanvas implements IGradientTransf
 //#endregion
 //#region src/gradient-transformer/modules/canvas/ModuleTransformerConicGradientToCanvas.d.ts
 declare class ModuleTransformerConicGradientToCanvas implements IGradientTransformerModule<ICanvasPaintResult> {
-  readonly target = "canvas";
+  readonly target = "canvas-2d";
   readonly gradientType = "conic-gradient";
   to(input: GradientBase<any>): ICanvasPaintResult;
   private _resolvePosition;
@@ -404,4 +408,27 @@ declare class ModuleTransformerConicGradientToCanvas implements IGradientTransfo
   private _clamp01;
 }
 //#endregion
-export { AbiInputType, AngleUnit, AnyGradient, ConicGradient, ConicGradientConfig, GradientAbi, GradientAbiInput, GradientAngleUnit, GradientAngleValue, GradientBase, GradientColorHint, GradientColorInterpolation, GradientColorStop, GradientCommonConfig, GradientData, GradientFactory, GradientHueInterpolationMethod, GradientLengthPercentage, GradientLengthUnit, GradientLengthValue, GradientNumberValue, GradientPercentValue, GradientPolarColorSpace, GradientPosition, GradientPositionKeywordX, GradientPositionKeywordY, GradientRectangularColorSpace, GradientStop, GradientTransformer, GradientType, ICanvasPaintResult, IGradientBase, IGradientStatic, IGradientTransformerModule, LinearGradient, LinearGradientConfig, ModuleTransformerConicGradientToCanvas, ModuleTransformerConicGradientToCss, ModuleTransformerLinearGradientToCanvas, ModuleTransformerLinearGradientToCss, ModuleTransformerRadialGradientToCanvas, ModuleTransformerRadialGradientToCss, PatternTokenKind, RadialGradient, RadialGradientConfig, RadialGradientExtent, RadialGradientShape, RadialGradientSize, ceilTo, clamp, degToRad, floorTo, format, fromPercent, gradToRad, isAngleUnit, isColorHint, isColorStop, isConfig, isGradient, isPatternSyntaxValid, isPatternValid, isValid, matchExpression, normalizeAngle, normalizeAngleDeg, normalizeAngleRad, parse, parseStringToAbi, radToDeg, roundTo, splitTopLevelByWhitespace, toAngleRad, toPercent, tokenizePattern, transformFrom, transformTo, truncTo, turnToRad, validate, validatePattern, validatePatternSemantic, validatePatternStructure, validatePatternSyntax };
+//#region src/gradient-transformer/modules/webgl/ModuleTransformerLinearGradientToWebgl.d.ts
+interface IWebGLPaintResult {
+  draw(canvas: HTMLCanvasElement, width: number, height: number): void;
+}
+declare class ModuleTransformerLinearGradientToCanvasWebGL implements IGradientTransformerModule<IWebGLPaintResult> {
+  readonly target = "canvas-webgl";
+  readonly gradientType = "linear-gradient";
+  to(input: GradientBase<any>): IWebGLPaintResult;
+}
+//#endregion
+//#region src/gradient-transformer/GradientTransformer.d.ts
+declare class GradientTransformer {
+  private static readonly _modules;
+  private static _initialized;
+  static add(module: IGradientTransformerModule): void;
+  static get(target: string, gradientType: string): IGradientTransformerModule | null;
+  static remove(target: string, gradientType: string): boolean;
+  static to<TOutput = unknown>(target: string, input: string | GradientBase<any>): TOutput;
+  static from<TOutput = unknown>(target: string, gradientType: string, input: TOutput): GradientBase<any>;
+  private static _ensureInitialized;
+  private static _getKey;
+}
+//#endregion
+export { AbiInputType, AngleUnit, AnyGradient, ConicGradient, ConicGradientConfig, GRADIENT_COLOR_SPACE, GRADIENT_HUE_INTERPOLATIONS, GRADIENT_POLAR_COLOR_SPACES, GradientAbi, GradientAbiInput, GradientAngleUnit, GradientAngleValue, GradientBase, GradientColorHint, GradientColorInterpolation, GradientColorSpace, GradientColorStop, GradientCommonConfig, GradientData, GradientFactory, GradientHueInterpolation, GradientHueInterpolationMethod, GradientInterpolation, GradientLengthPercentage, GradientLengthUnit, GradientLengthValue, GradientNumberValue, GradientPercentValue, GradientPolarColorSpace, GradientPosition, GradientPositionKeywordX, GradientPositionKeywordY, GradientRectangularColorSpace, GradientStop, GradientTransformer, GradientType, ICanvasPaintResult, IGradientBase, IGradientStatic, IGradientTransformerModule, IWebGLPaintResult, LinearGradient, LinearGradientConfig, ModuleTransformerConicGradientToCanvas, ModuleTransformerConicGradientToCss, ModuleTransformerLinearGradientToCanvas, ModuleTransformerLinearGradientToCanvasWebGL, ModuleTransformerLinearGradientToCss, ModuleTransformerRadialGradientToCanvas, ModuleTransformerRadialGradientToCss, PatternTokenKind, RadialGradient, RadialGradientConfig, RadialGradientExtent, RadialGradientShape, RadialGradientSize, angleValueFromString, ceilTo, clamp, degToRad, floorTo, format, fromPercent, gradToRad, isAngle, isAngleUnit, isColorHint, isColorStop, isConfig, isGradient, isGradientColorSpace, isGradientHueInterpolation, isGradientPolarColorSpace, isPatternSyntaxValid, isPatternValid, isValid, matchExpression, normalizeAngleDeg, normalizeAngleRad, parse, parseStringToAbi, radToDeg, roundTo, splitTopLevelByWhitespace, toPercent, tokenizePattern, transformFrom, transformTo, truncTo, turnToRad, validate, validatePattern, validatePatternSemantic, validatePatternStructure, validatePatternSyntax };