Allow squishing/stretching text (or arbitrary manipulations)

[HSZemi]

Describe your idea

When drawing text via PDFPage.drawText(), it should be possible to squish or stretch the drawn text in the x and/or y direction by given factors.

This would extend pdf-lib by a functionality that is currently lacking as far as I can tell. While some font enthusiasts may already cry at the thought of simply stretching some text, I do believe that there are justifiable applications for that functionality.

This could be achieved by providing a scaling factor for the x or y direction as part of the PDFPageDrawTextOptions, for example for fitting a text width to a given maximum width:

const nameScale = maximumWidth / calculatedTextWidth
page.drawText(myText, {
        x: xPosition,
        y: yPosition,
        size: givenSize,
        font: myFont,
        color: cmyk(0, 0, 0, 1),
        xScale: nameScale,
        yScale: 1,
    })

Alternatively, one could provide a custom TransformationMatrix as part of the PDFPageDrawTextOptions:

const nameScale = maximumWidth / calculatedTextWidth
page.drawText(myText, {
        size: givenSize,
        font: myFont,
        color: cmyk(0, 0, 0, 1),
        matrix: [nameScale, 0, 0, 1, xPosition, yPosition],
    })

How could this be implemented?

PDFPageDrawTextOptions already provides rotate, xSkew and ySkew options, which are used to calculate a transformation matrix for the drawn text https://github.com/Hopding/pdf-lib/blob/b8a44bd24b74f4f32456e9809dc4d2d9dc9bf176/src/api/operators.ts#L263-L277

Sadly, those cannot be combined to simply scale the text into the x or y direction.

For my use case, I resorted to directly passing a TransformationMatrix in the PDFPageDrawTextOptions, overriding any other manipulation: https://github.com/HSZemi/pdf-lib/commit/5e95bd7d85c2684efe2e0dae34986cb943b91018

However, extending PDFPageDrawTextOptions by xScale and yScale options, which might be mutually exclusive with some other options, may be a better albeit less flexible solution.

What problem are you trying to solve?

My specific use case is that I need to constrain some text on a ballot paper to the space that is available for each single person. The go-to solution is to squish the text a little if it is too long.

Why does this matter to you?

Without being able to squish text, I would not be able to build an automatic ballot paper generator. Or rather, I would need to rely on my hacky fork that patched the functionality in, which is not sustainable.

The available alternatives (line breaks, smaller font, abbreviating the text) are vastly inferior and therefore not acceptable.

Would others find this helpful?

While my personal use case is very specific, I think the ability to arbitrarily scale text in the x and y dimension independently from each other can be of use to many creative people.

Are you interested in implementing your proposal?

Yes

Why are you submitting a proposal?

I would love to have this functionality in the official release, so I do not have to rely on a custom fork, and others can profit from it as well.

While I have already built a version that accomplishes what I need (https://github.com/HSZemi/pdf-lib/commit/5e95bd7d85c2684efe2e0dae34986cb943b91018), I suspect that there is a way to go about this that better fits the overall design of pdf-lib and/or interacts better with the rotate/skew options.

Additional Notes

No response