rename FrameDisposalModeName, SVGOptions and TextStyle to FrameDisposalMode, RenderSVGOptions and TextStyleOptions

Author: matmen

CHANGELOG.md

@@ -8,7 +8,7 @@ Upgrading from 3.x? Upgrade to the latest 3.x release first, fix the deprecation
 
 - **Methods that take options refuse anything else than an object**: a stray number, string, boolean or `null` as the options of `cropCircle()`, `Image.renderText()`, the encoders (`encodeWebP()`, `encodeAVIF()`, `encodeJXL()`, ...), `quantize()`, `transform()`, `dropShadow()`, `outline()`, the gradients, `Image.decode()`, the animation encoders, and `new GainMap()` throws a `TypeError` that names the working form (e.g. `cropCircle({ size: 'cover' })`), so the 3.x calls that are gone like `cropCircle(true)` or `Image.renderText(font, 32, 'Hi')` fail instead of being ignored. Only the type of the argument is checked: a key that isn't an option is still ignored, so a typo like `{ maxWith: 300 }` isn't caught.
 
-- **The mode constants are removed, modes are plain strings**: `Image.RESIZE_*`, `Image.SVG_MODE_*`, `Frame.DISPOSAL_*` and the `ResizeModes`, `SVGScaleModes` and `FrameDisposalModes` classes are gone. Resize modes are `'nearest-neighbor'`, `'bilinear'`, `'bicubic'` and `'area'` (the `ResizeMode` type), disposal modes `'any'`, `'keep'`, `'previous'` and `'background'` (`FrameDisposalModeName`), and the SVG modes became options of `renderSVG()` (below). `Image.RESIZE_AUTO`/`ResizeModes.AUTO` is `image.resize({ width: 256 })`. The old values are no longer accepted either: `'RESIZE_BILINEAR'`, the numbers 1-3 for SVG scale modes and the numeric disposal ids 0-3.
+- **The mode constants are removed, modes are plain strings**: `Image.RESIZE_*`, `Image.SVG_MODE_*`, `Frame.DISPOSAL_*` and the `ResizeModes`, `SVGScaleModes` and `FrameDisposalModes` classes are gone. Resize modes are `'nearest-neighbor'`, `'bilinear'`, `'bicubic'` and `'area'` (the `ResizeMode` type), disposal modes `'any'`, `'keep'`, `'previous'` and `'background'` (`FrameDisposalMode`), and the SVG modes became options of `renderSVG()` (below). `Image.RESIZE_AUTO`/`ResizeModes.AUTO` is `image.resize({ width: 256 })`. The old values are no longer accepted either: `'RESIZE_BILINEAR'`, the numbers 1-3 for SVG scale modes and the numeric disposal ids 0-3.
 
 - **`absolute` is removed from `opacity()`, `red()`, `green()`, `blue()`, `lightness()` and `saturation()`**: they only scale now, `image.red(0.5)` (and `AdjustOptions`, the type of their options, is removed). For a fixed color, use `image.recolor()`. In JavaScript a leftover `image.red(0.5, true)` scales the channel instead of setting it.
 
@@ -54,7 +54,7 @@ Upgrading from 3.x? Upgrade to the latest 3.x release first, fix the deprecation
 
 - **Loop counts a format can't store throw a `RangeError`**: a GIF stores up to 65535 loops, a WebP up to 65534 and an APNG up to 2147483646 (2^31 - 2). A larger count used to wrap around silently (65536 as a GIF was forever). The encoders and the streaming encoders refuse it before encoding; `Infinity` is always fine.
 
-- **Removed and narrowed exported types**: `TextOptions` is `RenderTextOptions`, `FrameDisposalModeId` is removed (`FrameDisposalModeName` has the names), `AdjustOptions` is removed with `absolute`, `PNGMetadata` is `Metadata`, and `AnimationEncoderOptions`, `WebPAnimationEncoderOptions`, `GIFAnimationEncoderOptions` and `APNGAnimationEncoderOptions` are `AnimationEncodeOptions`, `WebPAnimationEncodeOptions`, `GIFAnimationEncodeOptions` and `APNGEncodeOptions`. `ResizeMode` is narrowed to the lower-case names (`'area'`, ...), and `SVGScaleMode` is removed.
+- **Removed and narrowed exported types**: `TextOptions` is `RenderTextOptions`, `FrameDisposalModeId` is removed (`FrameDisposalMode` has the names), `AdjustOptions` is removed with `absolute`, `PNGMetadata` is `Metadata`, and `AnimationEncoderOptions`, `WebPAnimationEncoderOptions`, `GIFAnimationEncoderOptions` and `APNGAnimationEncoderOptions` are `AnimationEncodeOptions`, `WebPAnimationEncodeOptions`, `GIFAnimationEncodeOptions` and `APNGEncodeOptions`. `ResizeMode` is narrowed to the lower-case names (`'area'`, ...), and `SVGScaleMode` is removed.
 
 - **`contain()` pads to the box, `fit()` is removed**: `image.contain(w, h)` resizes the image to fit inside the box and centers it on a canvas of exactly that size, like CSS' `object-fit: contain` (what `fit()` did), with transparent bars or a `background` color. The resize without bars, which `contain()` did, is `resize({ width, height, fit: 'inside' })`.
 
@@ -76,6 +76,8 @@ Upgrading from 3.x? Upgrade to the latest 3.x release first, fix the deprecation
 
 - **Removed**: `getRGBAAt()` (use `Colors.toRGBA(image.getPixelAt(x, y))`).
 
+- **Renamed types**: `FrameDisposalModeName` is `FrameDisposalMode`, `SVGOptions` is `RenderSVGOptions` (like `RenderTextOptions`) and `TextStyle` is `TextStyleOptions` (like `TextLayoutOptions`). They are types only, nothing changes at runtime.
+
 - **Renamed**: `greyscale()` is `grayscale()` (American spelling throughout), `region()` is `extract()`, the `resize` option of `rotate()` is `expand` (like `transform()`, `outline()` and `dropShadow()`), `GainMap`'s `gainMapMin` and `gainMapMax` (properties and options) are `min` and `max`, and the parameters of `setPixelAt()`, `lightness()` and `saturation()` are `color` and `factor`.
 
 - **Fewer types and classes**: `TextLayout` isn't exported, `renderText()` takes the layout options with its other options (`{ font, size, maxWidth: 300 }`). `AnimationDecodeOptions` is `DecodeOptions`, which all decode functions take. `encodeTGA()` takes `TGAEncodeOptions`; `EncodeOptions` is the `metadata` that every encoder's options extend, and the `gainMap` option of the JPEG, AVIF and JPEG XL encoders is `boolean | GainMapEmbedOptions`.

guides/Migrating to 4.0.md

@@ -192,7 +192,7 @@ Search your code for: `.crop(`, `.cover(` and `.rotate(` on frames.
 
 Each table maps a 3.x API to its 4.0 replacement. The deprecation hint in 3.x names a replacement too, but some of those
 replacements were reshaped in 4.0 as well (for example `ResizeModes`, which became plain strings); the tables give the
-4.0 form. The replacements are documented on their own pages: {@link ResizeMode}, {@link FrameDisposalModeName},
+4.0 form. The replacements are documented on their own pages: {@link ResizeMode}, {@link FrameDisposalMode},
 {@link Colors}, {@link Frame}, {@link Animation}, {@link AnimationEncoder} and {@link Metadata}.
 
 ### Constants and modes
@@ -214,7 +214,7 @@ replacements were reshaped in 4.0 as well (for example `ResizeModes`, which beca
 | Numeric disposal ids: `frame.disposalMode = 3`, `disposalMode: 3` in the frame options | The names: `frame.disposalMode = 'background'`, `disposalMode: 'background'`. `FrameDisposalModeId` is removed |
 
 The modes are plain strings in 4.0: the `ResizeModes` and `FrameDisposalModes` classes are removed, and the types
-{@link ResizeMode} and {@link FrameDisposalModeName} list the names. The old string and number values are not accepted
+{@link ResizeMode} and {@link FrameDisposalMode} list the names. The old string and number values are not accepted
 any more, so `image.resize(256, 256, { mode: 'RESIZE_BICUBIC' })` throws.
 
 ### Colors, pixels and encoding on `Image`
@@ -317,7 +317,7 @@ Methods that took options as their last positional arguments take the options ob
 object under the names of their options. The options of each method are on its own page, for example
 {@link ResizeOptions}, {@link CompositeOptions}, {@link RotateOptions}, {@link SharpenOptions},
 {@link DominantColorOptions}, {@link RoundCornersOptions}, {@link FisheyeOptions}, {@link TrimOptions},
-{@link ColorToAlphaOptions}, {@link PNGEncodeOptions}, {@link JPEGEncodeOptions}, {@link SVGOptions} and
+{@link ColorToAlphaOptions}, {@link PNGEncodeOptions}, {@link JPEGEncodeOptions}, {@link RenderSVGOptions} and
 {@link FrameOptions}. The animation options are {@link GIFAnimationEncodeOptions}, {@link APNGEncodeOptions},
 {@link DecodeOptions} and {@link GainMapEncodeOptions} for `GainMap.encode()`.
 
@@ -379,6 +379,9 @@ false })` grows the image again), so search for them too.
 | `image.getRGBAAt(x, y)` | `Colors.toRGBA(image.getPixelAt(x, y))`, an array (`getRGBAAt()` returned a view into the bitmap) |
 | `image.region(x, y, w, h)` | `image.extract(x, y, w, h)` |
 | `animation.encodeGIF({ quality })`, `Animation.gifEncoder(w, h, { quality })` | `{ colors }`: the palette size, 2-256. A quality of 90 and above is the default `256`; below, `colors: Math.round(8 * 32 ** (quality / 90))` gives the old palette size. `dither` (`'floyd-steinberg'` by default, `'atkinson'`, `'ordered'` or `'none'`) and `ditherStrength` are new |
+| `FrameDisposalModeName` (type) | `FrameDisposalMode`: the `Name` suffix is gone, as `FrameDisposalModeId` is |
+| `SVGOptions` (type) | `RenderSVGOptions`, like `RenderTextOptions` |
+| `TextStyle` (type) | `TextStyleOptions`, like `TextLayoutOptions` |
 | `GIFEncodeOptions` (the options of `Animation.encodeGIF()`) | `GIFAnimationEncodeOptions`. `GIFEncodeOptions` is now the options of the new `Image.encodeGIF()` |
 | `AnimationDecodeOptions` (type) | `DecodeOptions`, which `Image.decode()`, `Animation.decode()` and `decode()` all take |
 | `EncodeOptions` (type) as the options of `encodeTGA()` | `TGAEncodeOptions`. `EncodeOptions` is now the `metadata` that all encoder options extend |
@@ -453,7 +456,7 @@ grep -rnE 'rgbaToColor|rgbToColor|hslaToColor|hslToColor|rgbaToHSLA|colorToRGBA?
 grep -rnE 'iterateWithColors|for \(const \[[a-z]+, ?[a-z]+\] of' src
 
 # types and classes
-grep -rnE 'PNGMetadata|AnimationEncoderOptions|AdjustOptions|TextOptions|FrameDisposalModeId|\bGIF\b' src
+grep -rnE 'PNGMetadata|AnimationEncoderOptions|AdjustOptions|TextOptions|FrameDisposalModeId|FrameDisposalModeName|SVGOptions|\bTextStyle\b|\bGIF\b' src
 
 # decode and animations
 grep -rnE 'decode\(.*, *(true|false)\)' src

src/frame.ts

@@ -8,12 +8,12 @@ import { checkOptions, finite } from './util/options.ts';
  * - `'previous'`: the frame's area goes back to what it was before the frame
  * - `'any'`: the decoder decides (in practice like `'keep'`)
  */
-export type FrameDisposalModeName = 'any' | 'keep' | 'previous' | 'background';
+export type FrameDisposalMode = 'any' | 'keep' | 'previous' | 'background';
 
 // the ids the library stores the modes as (0 any, 1 keep, 2 previous, 3 background, like GIFs)
 type DisposalId = 0 | 1 | 2 | 3;
 
-const DISPOSAL_MODES: readonly FrameDisposalModeName[] = ['any', 'keep', 'previous', 'background'];
+const DISPOSAL_MODES: readonly FrameDisposalMode[] = ['any', 'keep', 'previous', 'background'];
 
 /** Options of {@link Frame} */
 export interface FrameOptions {
@@ -24,7 +24,7 @@ export interface FrameOptions {
     /** The frame's offset on the y-axis. Default: `0` */
     yOffset?: number;
     /** The frame's disposal mode, see {@link Frame.disposalMode}. Default: `'keep'` */
-    disposalMode?: FrameDisposalModeName;
+    disposalMode?: FrameDisposalMode;
 }
 
 /**
@@ -53,7 +53,7 @@ export class Frame {
      * @internal
      * @ignore
      */
-    static __convert_disposal_mode__(mode: FrameDisposalModeName): DisposalId {
+    static __convert_disposal_mode__(mode: FrameDisposalMode): DisposalId {
         const id = DISPOSAL_MODES.indexOf(mode);
         if (id < 0)
             throw new RangeError('Invalid disposal mode');
@@ -147,8 +147,8 @@ export class Frame {
         this.__y__ = finite(y, 'y offset');
     }
 
-    /** The frame's disposal mode, see {@link FrameDisposalModeName} */
-    get disposalMode(): FrameDisposalModeName {
+    /** The frame's disposal mode, see {@link FrameDisposalMode} */
+    get disposalMode(): FrameDisposalMode {
         return DISPOSAL_MODES[this.__disposalMode__];
     }
 
@@ -165,7 +165,7 @@ export class Frame {
      * Sets the disposal mode
      * @param disposalMode The mode's name (`'any'`, `'keep'`, `'previous'`, `'background'`)
      */
-    set disposalMode(disposalMode: FrameDisposalModeName) {
+    set disposalMode(disposalMode: FrameDisposalMode) {
         this.__disposalMode__ = Frame.__convert_disposal_mode__(disposalMode);
     }
 

src/image.ts

@@ -362,7 +362,7 @@ export interface FisheyeOptions {
 }
 
 /** Options of {@link Image.renderSVG} */
-export interface SVGOptions {
+export interface RenderSVGOptions {
     /**
      * The width in pixels, the height follows the SVG's aspect ratio. Give one of `width`, `height` and `scale`.
      * Default: the SVG's own width
@@ -397,9 +397,9 @@ export interface SVGOptions {
 
 /**
  * Options of {@link Image.renderText}: the font and size, the text color, the layout (wrapping, cutting off and alignment,
- * see {@link TextLayoutOptions}) and the style (see {@link TextStyle})
+ * see {@link TextLayoutOptions}) and the style (see {@link TextStyleOptions})
  */
-export interface RenderTextOptions extends TextStyle, TextLayoutOptions {
+export interface RenderTextOptions extends TextStyleOptions, TextLayoutOptions {
     /**
      * TrueType (ttf/ttc), OpenType (otf) or WOFF font buffer to use, or several by priority: every character comes
      * from the first font that has it (e.g. `[text, emoji]`), the first one sets the line height. Color glyphs (COLR
@@ -512,7 +512,7 @@ export interface AVIFEncodeOptions extends EncodeOptions {
 }
 
 /** Text style options of {@link Image.renderText} */
-export interface TextStyle {
+export interface TextStyleOptions {
     /** Width of an outline around the glyphs in pixels. Default: `0` */
     strokeWidth?: number;
     /** Color of the outline. Default: `0x000000ff` */
@@ -2680,8 +2680,8 @@ export class Image {
      * Creates a new image from the given SVG.
      * Supports shapes, paths, transforms, use/symbol, CSS styles, gradients, patterns, strokes, markers, clip paths,
      * masks, opacity, blend modes, filters (all primitives and the filter functions) and images embedded as data URIs
-     * (PNG, JPEG, GIF, WebP, SVG) or given with {@link SVGOptions.images}, and text with the given or embedded fonts
-     * (see {@link SVGOptions.fonts}). Hrefs are resolved from the options and the data URIs only, never from files or URLs.
+     * (PNG, JPEG, GIF, WebP, SVG) or given with {@link RenderSVGOptions.images}, and text with the given or embedded fonts
+     * (see {@link RenderSVGOptions.fonts}). Hrefs are resolved from the options and the data URIs only, never from files or URLs.
      * @example
      * ```ts
      * const logo = await Image.renderSVG(
@@ -2690,11 +2690,11 @@ export class Image {
      * );
      * ```
      * @param svg The SVG content
-     * @param options See {@link SVGOptions}
+     * @param options See {@link RenderSVGOptions}
      * @return The rendered SVG graphic
      */
-    static renderSVG(svg: string | BinaryData, options?: SVGOptions): Promise<Image>;
-    static async renderSVG(svg: string | BinaryData, options: SVGOptions = {}): Promise<Image> {
+    static renderSVG(svg: string | BinaryData, options?: RenderSVGOptions): Promise<Image>;
+    static async renderSVG(svg: string | BinaryData, options: RenderSVGOptions = {}): Promise<Image> {
         checkOptions(options, 'renderSVG(svg, { width: 512 })');
         const { width: givenWidth, height: givenHeight, scale, fonts = [], images: givenImages = {} } = options;
         const sizes = [givenWidth, givenHeight, scale].filter(value => value !== undefined).length;

src/index.ts

@@ -9,9 +9,9 @@ import { ImageType } from './image-type.ts';
 
 export { Image } from './image.ts';
 export { Colors } from './colors.ts';
-export type { Color, ColorFunction, ResizeMode, TextStyle, DecodeOptions, CompositeOptions, BlendMode, CropCircleOptions, DominantColorOptions, RotateOptions, ColorToAlphaOptions, ResizeOptions, ResizeToOptions, ContainOptions, SharpenOptions, PNGEncodeOptions, JPEGEncodeOptions, WebPEncodeOptions, AVIFEncodeOptions, JXLEncodeOptions, EncodeOptions, TGAEncodeOptions, GIFEncodeOptions, DitherMethod, GainMapEmbedOptions, SVGOptions, RenderTextOptions, ShadowOptions, OutlineOptions, QuantizeOptions, TransformOptions, TransformMode, GradientOptions, LinearGradientOptions, RadialGradientOptions, RoundCornersOptions, FisheyeOptions, TrimOptions } from './image.ts';
+export type { Color, ColorFunction, ResizeMode, TextStyleOptions, DecodeOptions, CompositeOptions, BlendMode, CropCircleOptions, DominantColorOptions, RotateOptions, ColorToAlphaOptions, ResizeOptions, ResizeToOptions, ContainOptions, SharpenOptions, PNGEncodeOptions, JPEGEncodeOptions, WebPEncodeOptions, AVIFEncodeOptions, JXLEncodeOptions, EncodeOptions, TGAEncodeOptions, GIFEncodeOptions, DitherMethod, GainMapEmbedOptions, RenderSVGOptions, RenderTextOptions, ShadowOptions, OutlineOptions, QuantizeOptions, TransformOptions, TransformMode, GradientOptions, LinearGradientOptions, RadialGradientOptions, RoundCornersOptions, FisheyeOptions, TrimOptions } from './image.ts';
 export { Frame } from './frame.ts';
-export type { FrameDisposalModeName, FrameOptions } from './frame.ts';
+export type { FrameDisposalMode, FrameOptions } from './frame.ts';
 export { GainMap } from './gainmap.ts';
 export type { GainMapOptions, GainMapEncodeOptions } from './gainmap.ts';
 export { Animation } from './animation.ts';