diff --git a/CHANGELOG.md b/CHANGELOG.md index f988d0c..e63edf9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,11 @@ Minimum requirements bumped to Node 20 and npm 10. +### Added + +- The functions `line()`, `rect()`, `circle()`, and `path()` to create + graphics shapes with less code and better tool support. + ### Deprecated - `TextAttrs` in favor of `TextProps`. @@ -11,6 +16,10 @@ Minimum requirements bumped to Node 20 and npm 10. - `InfoAttrs` in favor of `InfoProps`. - `CustomInfoAttrs` in favor of `CustomInfoProps`. - `Text` in favor of `TextSpan`. +- `LineOpts` in favor of `StrokeProps`. +- `RectOpts` in favor of `RectProps`. +- `CircleOpts` in favor of `CircleProps`. +- `PathOpts` in favor of `PathProps`. ## [0.5.4] - 2024-02-25 diff --git a/src/api/graphics.ts b/src/api/graphics.ts index ce49ca7..4ad42c2 100644 --- a/src/api/graphics.ts +++ b/src/api/graphics.ts @@ -23,9 +23,25 @@ export type Line = { * The y coordinate of the end point of the line. */ y2: number; -} & LineOpts; +} & LineProps; -export type LineOpts = Omit & TransformProps; +export type LineProps = Omit & TransformProps; + +/** @deprecated Use `LineProps` instead. */ +export type LineOpts = LineProps; + +/** + * Creates a line with the given coordinates and properties. + * + * @param x1 The x coordinate of the start of the line. + * @param y1 The y coordinate of the start of the line. + * @param x2 The x coordinate of the end of the line. + * @param y2 The y coordinate of the end of the line. + * @param props Optional properties for the line. + */ +export function line(x1: number, y1: number, x2: number, y2: number, props?: LineProps): Line { + return { ...props, type: 'line', x1, y1, x2, y2 }; +} /** * A rectangle. @@ -48,9 +64,25 @@ export type Rect = { * The height of the rectangle. */ height: number; -} & RectOpts; +} & RectProps; -export type RectOpts = Omit & FillProps & TransformProps; +export type RectProps = Omit & FillProps & TransformProps; + +/** @deprecated Use `RectProps` instead. */ +export type RectOpts = RectProps; + +/** + * Creates a rectangle with the given coordinates and properties. + * + * @param x The x coordinate of the top left corner of the rectangle. + * @param y The y coordinate of the top left corner of the rectangle. + * @param width The width of the rectangle. + * @param height The height of the rectangle. + * @param props Optional properties for the rectangle. + */ +export function rect(x: number, y: number, width: number, height: number, props?: RectProps): Rect { + return { ...props, type: 'rect', x, y, width, height }; +} /** * A circle. @@ -69,9 +101,24 @@ export type Circle = { * The radius of the circle. */ r: number; -} & CircleOpts; +} & CircleProps; -export type CircleOpts = Omit & FillProps & TransformProps; +export type CircleProps = Omit & FillProps & TransformProps; + +/** @deprecated Use `CircleProps` instead. */ +export type CircleOpts = CircleProps; + +/** + * Creates a circle with the given center, radius, and properties. + * + * @param cx The x coordinate of the center of the circle. + * @param cy The y coordinate of the center of the circle. + * @param r The radius of the circle. + * @param props Optional properties for the circle. + */ +export function circle(cx: number, cy: number, r: number, props?: CircleProps): Circle { + return { ...props, type: 'circle', cx, cy, r }; +} /** * An SVG path element. @@ -82,9 +129,22 @@ export type Path = { * An SVG path. See https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d for details. */ d: string; -} & PathOpts; +} & PathProps; -export type PathOpts = LineProps & FillProps & TransformProps; +export type PathProps = StrokeProps & FillProps & TransformProps; + +/** @deprecated Use `PathProps` instead. */ +export type PathOpts = PathProps; + +/** + * Creates a path with the given path data and properties. + * + * @param d The path data. See https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d for details. + * @param props Optional properties for the path. + */ +export function path(d: string, props?: PathProps): Path { + return { ...props, type: 'path', d }; +} /** * A polyline, i.e. a line consisting of multiple segments. @@ -102,12 +162,13 @@ export type Polyline = { closePath?: boolean; } & PolyLineOpts; -export type PolyLineOpts = LineProps & FillProps & TransformProps; +/** @deprecated Use `Path` instead of `PolyLine`. */ +export type PolyLineOpts = StrokeProps & FillProps & TransformProps; export type LineCap = 'butt' | 'round' | 'square'; export type LineJoin = 'miter' | 'round' | 'bevel'; -type LineProps = { +type StrokeProps = { /** * The width of stroked lines in pt. */