reamkit 1.21.0 → 1.23.0

package/dist/esm/pdf/shading.d.ts

@@ -25,4 +25,23 @@ export declare function shapeBbox(shape: VectorShape): Bbox | undefined;
  * @returns A reference to the `/Pattern` object, for a `/Pattern cs /Pn scn` fill.
  */
 export declare function buildGradientPattern(doc: PdfDocument, gradient: ShapeGradient, bbox: Bbox, ctm: readonly [number, number, number, number, number, number]): PdfRef;
+/**
+ * §11.6.5.2 — the luminosity soft mask a gradient with per-stop TRANSPARENCY is
+ * painted through.
+ *
+ * A PDF shading has one colour per point and no alpha, so a gradient that fades
+ * out is drawn as the colour shading masked by a second shading of the same
+ * geometry whose GREY is the transparency: white where the stop is opaque,
+ * black where it is clear. 45541_Footer's master lays a white band down the
+ * left of every slide that starts half transparent, and painted flat it covered
+ * the artwork behind it.
+ *
+ * @param doc      The document to add the objects to.
+ * @param gradient The gradient fill.
+ * @param bbox     The shape's local-space bounding box.
+ * @param ctm      The shape's CTM, as the form's `/Matrix`.
+ * @returns The mask form XObject, or `undefined` when every stop is opaque or
+ *          the sweep has no shading type that can carry a mask.
+ */
+export declare function buildGradientAlphaMask(doc: PdfDocument, gradient: ShapeGradient, bbox: Bbox, ctm: readonly [number, number, number, number, number, number]): PdfRef | undefined;
 export {};

package/dist/esm/pdf/shading.js

@@ -49,7 +49,7 @@ function buildGradientPattern(doc, gradient, bbox, ctm) {
 		Matrix: [...ctm]
 	}));
 }
-function axialShading(angleDeg, b, fnRef) {
+function axialShading(angleDeg, b, fnRef, cs = "DeviceRGB") {
 	const rad = angleDeg * Math.PI / 180;
 	const dx = Math.cos(rad);
 	const dy = -Math.sin(rad);
@@ -70,7 +70,7 @@ function axialShading(angleDeg, b, fnRef) {
 	}
 	return dict({
 		ShadingType: 2,
-		ColorSpace: name("DeviceRGB"),
+		ColorSpace: name(cs),
 		Coords: [
 			cx + (tmin - cproj) * dx,
 			cy + (tmin - cproj) * dy,
@@ -81,13 +81,13 @@ function axialShading(angleDeg, b, fnRef) {
 		Extend: [true, true]
 	});
 }
-function radialShading(b, fnRef, center) {
+function radialShading(b, fnRef, center, cs = "DeviceRGB") {
 	const cx = center ? b.minX + center.x * (b.maxX - b.minX) : (b.minX + b.maxX) / 2;
 	const cy = center ? b.maxY - center.y * (b.maxY - b.minY) : (b.minY + b.maxY) / 2;
 	const r = Math.hypot(b.maxX - b.minX, b.maxY - b.minY) / 2;
 	return dict({
 		ShadingType: 3,
-		ColorSpace: name("DeviceRGB"),
+		ColorSpace: name(cs),
 		Coords: [
 			cx,
 			cy,
@@ -171,6 +171,77 @@ function ps(n) {
 	const s = n.toFixed(6).replace(/0+$/u, "").replace(/\.$/u, "");
 	return s === "" || s === "-0" ? "0" : s;
 }
+/**
+* §11.6.5.2 — the luminosity soft mask a gradient with per-stop TRANSPARENCY is
+* painted through.
+*
+* A PDF shading has one colour per point and no alpha, so a gradient that fades
+* out is drawn as the colour shading masked by a second shading of the same
+* geometry whose GREY is the transparency: white where the stop is opaque,
+* black where it is clear. 45541_Footer's master lays a white band down the
+* left of every slide that starts half transparent, and painted flat it covered
+* the artwork behind it.
+*
+* @param doc      The document to add the objects to.
+* @param gradient The gradient fill.
+* @param bbox     The shape's local-space bounding box.
+* @param ctm      The shape's CTM, as the form's `/Matrix`.
+* @returns The mask form XObject, or `undefined` when every stop is opaque or
+*          the sweep has no shading type that can carry a mask.
+*/
+function buildGradientAlphaMask(doc, gradient, bbox, ctm) {
+	if (!gradient.stops.some((s) => (s.alpha ?? 1) < 1)) return void 0;
+	if (gradient.kind === "radial" && gradient.sweep === "rect") return void 0;
+	const fn = doc.add(buildAlphaRamp(gradient.stops));
+	const shading = gradient.kind === "radial" ? radialShading(bbox, fn, gradient.center, "DeviceGray") : axialShading(gradient.angle ?? 0, bbox, fn, "DeviceGray");
+	return doc.add(stream({
+		Type: name("XObject"),
+		Subtype: name("Form"),
+		BBox: [
+			bbox.minX,
+			bbox.minY,
+			bbox.maxX,
+			bbox.maxY
+		],
+		Matrix: [...ctm],
+		Group: dict({
+			S: name("Transparency"),
+			CS: name("DeviceGray")
+		}),
+		Resources: dict({ Shading: dict({ Sm: doc.add(shading) }) })
+	}, new TextEncoder().encode("q /Sm sh Q")));
+}
+function buildAlphaRamp(stopsIn) {
+	const stops = normalizeStops(stopsIn);
+	if (stops.length <= 2) return dict({
+		FunctionType: 2,
+		Domain: [0, 1],
+		C0: [stops[0].alpha],
+		C1: [stops[stops.length - 1].alpha],
+		N: 1
+	});
+	const functions = [];
+	const bounds = [];
+	const encode = [];
+	for (let i = 0; i < stops.length - 1; i++) {
+		functions.push(dict({
+			FunctionType: 2,
+			Domain: [0, 1],
+			C0: [stops[i].alpha],
+			C1: [stops[i + 1].alpha],
+			N: 1
+		}));
+		if (i > 0) bounds.push(stops[i].offset);
+		encode.push(0, 1);
+	}
+	return dict({
+		FunctionType: 3,
+		Domain: [0, 1],
+		Functions: functions,
+		Bounds: bounds,
+		Encode: encode
+	});
+}
 function buildRamp(stopsIn) {
 	const stops = normalizeStops(stopsIn);
 	if (stops.length <= 2) return dict({
@@ -205,19 +276,21 @@ function buildRamp(stopsIn) {
 function normalizeStops(stops) {
 	const out = stops.map((s) => ({
 		offset: Math.max(0, Math.min(1, s.offset)),
-		colorHex: s.colorHex
+		colorHex: s.colorHex,
+		alpha: Math.max(0, Math.min(1, s.alpha ?? 1))
 	})).sort((a, b) => a.offset - b.offset);
 	if (out.length === 0) return [{
 		offset: 0,
-		colorHex: "000000"
+		colorHex: "000000",
+		alpha: 1
 	}];
 	out[0] = {
-		offset: 0,
-		colorHex: out[0].colorHex
+		...out[0],
+		offset: 0
 	};
 	out[out.length - 1] = {
-		offset: 1,
-		colorHex: out[out.length - 1].colorHex
+		...out[out.length - 1],
+		offset: 1
 	};
 	return out;
 }
@@ -235,4 +308,4 @@ function rgb01(hex) {
 	];
 }
 //#endregion
-export { buildGradientPattern, shapeBbox };
+export { buildGradientAlphaMask, buildGradientPattern, shapeBbox };