@weasel-js/paint 1.17.3 → 1.18.0

package/dist/index.d.ts

@@ -152,6 +152,14 @@ declare function patternPlacementOf(paint: PatternPaint): PatternPlacement;
 /** A tile paint's description of the tile alone, its placement left behind. */
 declare function tileSpecOf(paint: TilePaint): TilePatternSpec;
 
+/** Which way a polar space's hue goes between two endpoints, as CSS
+ *  `hue-interpolation-method`: the arc of at most 180°, or the other one. */
+type HueInterpolation = 'shorter' | 'longer';
+/** The hue `t` of the way from `h1` to `h2`, in degrees, along the arc `method` names, in [0, 360). Both hues are
+ *  taken into [0, 360) first, and a half turn keeps the sign of `h2 - h1`, as CSS's fixup does: 180° to 0° passes
+ *  90°. Equal hues stay put under `longer`, where CSS would go a full turn. */
+declare function lerpHueDeg(h1: number, h2: number, t: number, method?: HueInterpolation): number;
+
 /**
  * Convert a 0..1 float sRGB triple to OKLab — the renderer's own color space,
  * and what a caller holding a `resolveColor` result has. Rounds into the u8
@@ -237,9 +245,6 @@ declare function srgbToHsl(r: number, g: number, b: number): [number, number, nu
  * which keeps its `'rgb'` spelling and its byte-precision paths.
  */
 type ColorInterpolationSpace = 'oklch' | 'oklab' | 'hsl' | 'srgb' | 'srgb-linear';
-/** Which way a polar space's hue goes between two endpoints, as CSS
- *  `hue-interpolation-method`: the arc of at most 180°, or the other one. */
-type HueInterpolation = 'shorter' | 'longer';
 /**
  * Interpolate between two sRGB colors (0..1 floats) in `space`, at `t` in 0..1.
  * Float precision throughout, with no byte round-trip. The result is sRGB;
@@ -568,23 +573,6 @@ interface StrokeNib {
      *  fraction of the width moving across it. */
     ratio: number;
 }
-/**
- * Inflate (positive) or deflate (negative) a rect to honor `align` when
- * stroking it: the returned rect's center-aligned stroke coincides with the
- * requested inner/outer-aligned stroke of the original. `width` is the
- * stroke width (defaults to 1 to match canvas).
- */
-declare function alignedStrokeRect(rect: {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}, align: StrokeAlign, width?: number): {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-};
 /**
  * The named line styles a `Stroke.dash` array reads as.
  *
@@ -749,6 +737,33 @@ declare function strokeHasInk(stroke: Stroke | null | undefined): stroke is Pain
  */
 declare function strokeKey(stroke: Stroke | null | undefined): string;
 
+/**
+ * Whether {@link alignedStrokeRect} draws `align` on `rect`: always, but for an
+ * inner stroke at least as wide as the rect's narrower side, which covers the
+ * whole rect where the shifted rect would turn inside out and draw outside it.
+ */
+declare function alignedStrokeRectHolds(rect: {
+    width: number;
+    height: number;
+}, align: StrokeAlign, width?: number): boolean;
+/**
+ * Inflate (positive) or deflate (negative) a rect to honor `align` when
+ * stroking it: the returned rect's center-aligned stroke coincides with the
+ * requested inner/outer-aligned stroke of the original. `width` is the
+ * stroke width (defaults to 1 to match canvas).
+ */
+declare function alignedStrokeRect(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, align: StrokeAlign, width?: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+
 type Rgba = readonly [number, number, number, number];
 /**
  * `color-mix(in <space>, a p%, b)` for two 0..1 sRGBA colors, `p` as 0..1. The
@@ -826,8 +841,13 @@ declare function lerpStroke(a: Stroke | null | undefined, b: Stroke | null | und
  * names none). `null` for anything else, a missing `#` included.
  */
 declare function parseHexBytes(input: string): [number, number, number, number] | null;
+/** The kit's one hex color writer: a 0..255 channel as two hex digits, rounded and clamped. */
+declare function byteHex(v: number): string;
 /** A hex color's red, green, and blue as 0..255, its alpha dropped. Throws on anything {@link parseHexBytes} does not read. */
 declare function hexToRgbBytes(input: string): [number, number, number];
+/** An RGBA pixel's bytes as `#rrggbb`, or `null` where it is fully transparent: the color a
+ *  sampler reports for what is drawn at a point. Alpha is dropped, not composited. */
+declare function rgbaHex(rgba: ArrayLike<number>): string | null;
 
 /**
  * Parse a CSS color string into [r, g, b, a] with 0..1 components.
@@ -850,9 +870,8 @@ declare function hexToRgbBytes(input: string): [number, number, number];
  * returned tuple as read-only — mutation would corrupt the cache.
  */
 declare function parseColor(input: string): [number, number, number, number];
-/** Cached `parseColor`. Use this from renderer hot paths (per-frame draw
- *  callbacks, gradient ramp builds). The cache is capped at ~1024 entries and
- *  cleared wholesale on overflow. */
+/** `parseColor`, typed read-only: the form for renderer hot paths (per-frame
+ *  draw callbacks, gradient ramp builds), which share its cache. */
 declare function resolveColor(input: string): readonly [number, number, number, number];
 /** Same as `parseColor` but returns integer 0..255 components. */
 declare function parseColorToRgba255(input: string): [number, number, number, number];
@@ -906,7 +925,7 @@ declare function resolveGradientStops(stops: readonly GradStop[]): ResolvedGradi
  *
  * `space` is a gradient's `interpolate`. Alpha is linear in every space —
  * only the color channels travel through OKLab or OKLCh. Returns transparent
- * black for an empty list.
+ * black for an empty list; a NaN `t` reads as the first stop.
  */
 declare function sampleResolvedStops(stops: readonly ResolvedGradientStop[], t: number, space?: ColorSpace): readonly [number, number, number, number];
 /**
@@ -914,7 +933,7 @@ declare function sampleResolvedStops(stops: readonly ResolvedGradientStop[], t:
  * sampling the GL ramp texture bakes, so an editor track and the painted
  * gradient cannot disagree.
  *
- * Returns transparent black for an empty list.
+ * Returns transparent black (`#00000000`) for an empty list.
  */
 declare function sampleGradientStops(stops: readonly GradStop[], t: number, space?: ColorSpace): string;
 /**
@@ -1037,5 +1056,5 @@ declare function cssColorLiteral(css: string): ColorLiteral;
 /** `#rrggbb` or `#rrggbbaa` as an `srgb` literal; `null` for anything else. */
 declare function hexToColorLiteral(hex: string): ColorLiteral | null;
 
-export { INHERIT, MAX_DASH_RUNS, STROKE_DASH_RATIOS, TILE_KINDS, alignedStrokeRect, colorLiteralToCss, colorLiteralToHex, composePatternTransform, contrastLineColor, contrastRatio, cssColorLiteral, cssColorNotation, dashForStrokeStyle, dashPattern, dashPhase, decomposePatternTransform, fillHasInk, gradientForBounds, gradientGeometry, hexToColorLiteral, hexToOklchDeg, hexToRgbBytes, hexToRgba, hslToSrgb, interpolateSrgb, isGradientPaint, isImagePatternPaint, isPatternPaint, isSolidPaint, isTileKind, isTilePaint, lerpColorArray, lerpFill, lerpOklab, lerpOklch, lerpPaint, lerpStroke, linearSrgbToOklab, linearToSrgb, luminanceContrast, mixOklab, mixRgba, mixRgbaWeighted, normalizeHex, oklabToLinearSrgb, oklabToOklch, oklabToSrgbU8, oklchDegToHex, oklchToOklab, paintKey, parseColor, parseColorToRgba255, parseHexBytes, patternPlacementOf, relativeLuminance, resolveColor, resolveFill, resolveGradientStops, resolvePaletteColor, resolvePaletteColors, resolveScreenLength, resolveStroke, rgbaToHex, sampleGradientStops, sampleResolvedStops, scaleVertexWidth, scaledDash, srgbFloatToOklab, srgbToHsl, srgbToLinear, srgbU8ToOklab, strokeDashStyleOf, strokeHasInk, strokeKey, strokeTrimKey, tileSpecOf, tryNormalizeHex, vertexHalfWidths, vertexWidthFromSides, wcagLevels, widestHalfWidth, withGradientKind };
+export { INHERIT, MAX_DASH_RUNS, STROKE_DASH_RATIOS, TILE_KINDS, alignedStrokeRect, alignedStrokeRectHolds, byteHex, colorLiteralToCss, colorLiteralToHex, composePatternTransform, contrastLineColor, contrastRatio, cssColorLiteral, cssColorNotation, dashForStrokeStyle, dashPattern, dashPhase, decomposePatternTransform, fillHasInk, gradientForBounds, gradientGeometry, hexToColorLiteral, hexToOklchDeg, hexToRgbBytes, hexToRgba, hslToSrgb, interpolateSrgb, isGradientPaint, isImagePatternPaint, isPatternPaint, isSolidPaint, isTileKind, isTilePaint, lerpColorArray, lerpFill, lerpHueDeg, lerpOklab, lerpOklch, lerpPaint, lerpStroke, linearSrgbToOklab, linearToSrgb, luminanceContrast, mixOklab, mixRgba, mixRgbaWeighted, normalizeHex, oklabToLinearSrgb, oklabToOklch, oklabToSrgbU8, oklchDegToHex, oklchToOklab, paintKey, parseColor, parseColorToRgba255, parseHexBytes, patternPlacementOf, relativeLuminance, resolveColor, resolveFill, resolveGradientStops, resolvePaletteColor, resolvePaletteColors, resolveScreenLength, resolveStroke, rgbaHex, rgbaToHex, sampleGradientStops, sampleResolvedStops, scaleVertexWidth, scaledDash, srgbFloatToOklab, srgbToHsl, srgbToLinear, srgbU8ToOklab, strokeDashStyleOf, strokeHasInk, strokeKey, strokeTrimKey, tileSpecOf, tryNormalizeHex, vertexHalfWidths, vertexWidthFromSides, wcagLevels, widestHalfWidth, withGradientKind };
 export type { ColorFn, ColorFnContext, ColorInterpolationSpace, ColorLiteral, ColorRef, ColorSeqFn, ColorSource, ColorSpace, CommandFill, CommandPaint, CommandPaintUnits, CommandStroke, ExternalColors, Fill, GradStop, GradientKind, GradientPaint, HalfWidths, HexForm, HueInterpolation, ImagePatternPaint, InCommandUnits, Inherit, KitMarkerKey, MarkerKey, MarkerRef, OklchDeg, Paint, PaintUnits, PaintedFill, PaintedStroke, Palette, PaletteEntry, PatternPaint, PatternPlacement, PatternTransform, PatternTransformParts, PosedPaint, Region, ResolvablePatternKind, ResolvedGradientStop, ScreenLength, SolidPaint, Stroke, StrokeAlign, StrokeDashStyle, StrokeNib, StrokeTrim, TextureHandle, TexturePaint, TileExtent, TileKind, TilePaint, TilePatternSpec, TrimAt, TrimPace, VertexWidth, VertexWidthSides };