@jasy/pdf 1.0.0-alpha.1 → 1.0.0-alpha.2

package/dist/api/layout.d.ts

@@ -3,6 +3,7 @@ import { RowElement } from "../elements/row-element";
 import { RectangleElement } from "../elements/rectangle-element";
 import { ExpandedElement } from "../elements/layout/expanded-element";
 import { PaddingElement } from "../elements/layout/padding-element";
+import { PositionedElement, PositionedInsets } from "../elements/layout/positioned-element";
 import { PDFElement } from "../elements/pdf-element";
 import { MainAlign, CrossAlign } from "../utils/flex-layout";
 import { ColorInput } from "./color";
@@ -45,6 +46,12 @@ export interface BoxOptions {
     height?: number;
     /** Corner radius in points. */
     radius?: number;
+    /** Make this box a positioning frame: `Positioned` children placed inside it resolve their
+     *  offsets against this box (CSS `position: relative`). */
+    relative?: boolean;
+    /** `"hidden"` crops children to the box (rounded corners included); `"visible"` (default) lets a
+     *  `Positioned` child spill over the edge. */
+    overflow?: "hidden" | "visible";
 }
 /**
  * A box: maps to a `RectangleElement` (fill + border + radius) whose children are stacked
@@ -55,6 +62,12 @@ export declare function Box(children: PDFElement[]): RectangleElement;
 export declare function Box(opts: BoxOptions, children: PDFElement[]): RectangleElement;
 /** Insets a single child by `padding` (a number / `{x,y}` / `{top,…}` / 4-tuple). */
 export declare function Padding(padding: Insets, child: PDFElement): PaddingElement;
+/**
+ * Places a child OUT OF FLOW, relative to the nearest enclosing `relative` Box. Offsets are from
+ * the frame's edges (points); a negative `top`/`left` lets the child poke into or out of the corner
+ * - a badge, a tab, a ribbon. `Positioned({ top, left, right, bottom }, child)`.
+ */
+export declare function Positioned(opts: PositionedInsets, child: PDFElement): PositionedElement;
 /**
  * A flexible empty gap that pushes its siblings apart - `Row([a, Spacer(), b])` sends `a`
  * and `b` to the edges. `flex` weights it against other flex children (default 1).

package/dist/api/layout.js

@@ -4,6 +4,7 @@ exports.Column = Column;
 exports.Row = Row;
 exports.Box = Box;
 exports.Padding = Padding;
+exports.Positioned = Positioned;
 exports.Spacer = Spacer;
 exports.Expanded = Expanded;
 const container_element_1 = require("../elements/container-element");
@@ -11,6 +12,7 @@ const row_element_1 = require("../elements/row-element");
 const rectangle_element_1 = require("../elements/rectangle-element");
 const expanded_element_1 = require("../elements/layout/expanded-element");
 const padding_element_1 = require("../elements/layout/padding-element");
+const positioned_element_1 = require("../elements/layout/positioned-element");
 const color_1 = require("./color");
 const insets_1 = require("./insets");
 const args_1 = require("./args");
@@ -77,12 +79,22 @@ function Box(a, b) {
                 left: side(opts.borderLeft),
             }
             : undefined,
+        relative: opts.relative,
+        overflow: opts.overflow,
     });
 }
 /** Insets a single child by `padding` (a number / `{x,y}` / `{top,…}` / 4-tuple). */
 function Padding(padding, child) {
     return new padding_element_1.PaddingElement({ margin: (0, insets_1.toEdges)(padding), child });
 }
+/**
+ * Places a child OUT OF FLOW, relative to the nearest enclosing `relative` Box. Offsets are from
+ * the frame's edges (points); a negative `top`/`left` lets the child poke into or out of the corner
+ * - a badge, a tab, a ribbon. `Positioned({ top, left, right, bottom }, child)`.
+ */
+function Positioned(opts, child) {
+    return new positioned_element_1.PositionedElement(Object.assign({ child }, opts));
+}
 /**
  * A flexible empty gap that pushes its siblings apart - `Row([a, Spacer(), b])` sends `a`
  * and `b` to the edges. `flex` weights it against other flex children (default 1).

package/dist/elements/index.d.ts

@@ -6,5 +6,6 @@ export * from "./rectangle-element";
 export * from "./image-element";
 export * from "./layout/expanded-element";
 export * from "./layout/padding-element";
+export * from "./layout/positioned-element";
 export * from "./line-element";
 export * from "./row-element";

package/dist/elements/index.js

@@ -24,5 +24,6 @@ __exportStar(require("./rectangle-element"), exports);
 __exportStar(require("./image-element"), exports);
 __exportStar(require("./layout/expanded-element"), exports);
 __exportStar(require("./layout/padding-element"), exports);
+__exportStar(require("./layout/positioned-element"), exports);
 __exportStar(require("./line-element"), exports);
 __exportStar(require("./row-element"), exports);

package/dist/elements/layout/positioned-element.d.ts

@@ -0,0 +1,31 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints";
+import { LayoutContext, PDFElement, WithChild } from "../pdf-element";
+/** Offsets from the frame's box edges, in points. Negative lets the child poke outside. */
+export interface PositionedInsets {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+interface PositionedElementParams extends WithChild, PositionedInsets {
+}
+/**
+ * An out-of-flow child, placed relative to the nearest enclosing positioning frame (a `relative`
+ * Box). It takes ZERO space in the normal flow - `calculateLayout` returns `Size(0,0)` and instead
+ * registers a placement closure on the frame. The frame runs that closure once it knows its own
+ * size, so `right`/`bottom` resolve against the final box and the child can overflow it (a negative
+ * `top`/`left` makes it poke into / out of the corner, e.g. a badge or tab).
+ *
+ * With no frame in scope the element is a no-op (nothing is drawn) - `Positioned` only makes sense
+ * inside a `relative` Box.
+ */
+export declare class PositionedElement extends PDFElement {
+    private child;
+    private insets;
+    constructor({ child, top, right, bottom, left }: PositionedElementParams);
+    calculateLayout(_constraints: BoxConstraints, _offset: Offset, ctx: LayoutContext): Size;
+    /** Lays the child out at the resolved position inside (or overflowing) the frame box. */
+    private placeInFrame;
+    getProps(): WithChild;
+}
+export {};

package/dist/elements/layout/positioned-element.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PositionedElement = void 0;
+const box_constraints_1 = require("../../layout/box-constraints");
+const pdf_element_1 = require("../pdf-element");
+/**
+ * An out-of-flow child, placed relative to the nearest enclosing positioning frame (a `relative`
+ * Box). It takes ZERO space in the normal flow - `calculateLayout` returns `Size(0,0)` and instead
+ * registers a placement closure on the frame. The frame runs that closure once it knows its own
+ * size, so `right`/`bottom` resolve against the final box and the child can overflow it (a negative
+ * `top`/`left` makes it poke into / out of the corner, e.g. a badge or tab).
+ *
+ * With no frame in scope the element is a no-op (nothing is drawn) - `Positioned` only makes sense
+ * inside a `relative` Box.
+ */
+class PositionedElement extends pdf_element_1.PDFElement {
+    constructor({ child, top, right, bottom, left }) {
+        super();
+        this.child = child;
+        this.insets = { top, right, bottom, left };
+    }
+    calculateLayout(_constraints, _offset, ctx) {
+        var _a;
+        // Defer to the frame: it calls back once it has sized itself. Out of flow either way.
+        (_a = ctx.frame) === null || _a === void 0 ? void 0 : _a.place.push((frame, frameCtx) => this.placeInFrame(frame, frameCtx));
+        return { width: 0, height: 0 };
+    }
+    /** Lays the child out at the resolved position inside (or overflowing) the frame box. */
+    placeInFrame(frame, ctx) {
+        const { top, right, bottom, left } = this.insets;
+        // An axis is PINNED (stretched) only when BOTH of its insets are given; otherwise the child
+        // shrink-wraps its content (unbounded), the CSS rule for an absolutely-positioned element.
+        const width = left !== undefined && right !== undefined
+            ? Math.max(0, frame.size.width - left - right)
+            : Infinity;
+        const height = top !== undefined && bottom !== undefined
+            ? Math.max(0, frame.size.height - top - bottom)
+            : Infinity;
+        const constraints = box_constraints_1.BoxConstraints.loose(width, height);
+        // Measure first (so right/bottom can resolve against the child's own size).
+        const measured = this.child.calculateLayout(constraints, { x: 0, y: 0 }, ctx);
+        let x = frame.origin.x + (left !== null && left !== void 0 ? left : 0);
+        if (left === undefined && right !== undefined) {
+            x = frame.origin.x + frame.size.width - measured.width - right;
+        }
+        let y = frame.origin.y + (top !== null && top !== void 0 ? top : 0);
+        if (top === undefined && bottom !== undefined) {
+            y = frame.origin.y + frame.size.height - measured.height - bottom;
+        }
+        // Place it for real at the resolved corner.
+        this.child.calculateLayout(constraints, { x, y }, ctx);
+    }
+    getProps() {
+        return { child: this.child };
+    }
+}
+exports.PositionedElement = PositionedElement;

package/dist/elements/page-element.js

@@ -70,7 +70,18 @@ class PageElement extends pdf_element_1.PDFElement {
         // content box when there is neither - byte-identical to a plain page).
         const bands = layoutPageBands(this.config, this.header, this.footer, pageCtx);
         const childConstraints = box_constraints_1.BoxConstraints.loose(bands.bodyWidth, bands.bodyHeight);
-        this.children.forEach((child) => child.calculateLayout(childConstraints, bands.bodyOrigin, pageCtx));
+        // The page body is itself a positioning frame: a `Positioned` with no `relative` ancestor
+        // resolves against the content box (a `relative` Box overrides it for its own subtree). Drained
+        // after the body is laid out, so a page-level Positioned isn't a silent no-op.
+        const frame = {
+            origin: bands.bodyOrigin,
+            size: { width: bands.bodyWidth, height: bands.bodyHeight },
+            place: [],
+        };
+        const bodyCtx = Object.assign(Object.assign({}, pageCtx), { frame });
+        this.children.forEach((child) => child.calculateLayout(childConstraints, bands.bodyOrigin, bodyCtx));
+        for (const place of frame.place)
+            place(frame, pageCtx);
         const { width, height } = resolvePageContentBox(this.config);
         return { width, height };
     }

package/dist/elements/pdf-element.d.ts

@@ -7,9 +7,25 @@ import type { BoxConstraints, Offset, Size } from "../layout/box-constraints";
  * `PageElement` sets `pageConfig` for its subtree, so each page flips against its own
  * height. The PDF byte writer is deliberately absent - layout must not touch it.
  */
+/**
+ * A positioning frame - the CSS "containing block" that `Positioned` children resolve their
+ * offsets against. A `relative` Box (later the page) creates one and threads it to its subtree;
+ * `Positioned` descendants register a placement closure in `place`, which the frame drains once it
+ * has finished sizing itself (so `right`/`bottom` can resolve against the final box).
+ */
+export interface PositioningFrame {
+    origin: Offset;
+    size: Size;
+    place: Array<(frame: {
+        origin: Offset;
+        size: Size;
+    }, ctx: LayoutContext) => void>;
+}
 export interface LayoutContext {
     metrics: FontMetrics;
     pageConfig: PDFPageConfig;
+    /** The nearest enclosing positioning frame, if any (set by a `relative` Box). */
+    frame?: PositioningFrame;
 }
 export declare abstract class PDFElement {
     abstract getProps(): unknown;

package/dist/elements/rectangle-element.d.ts

@@ -18,6 +18,11 @@ interface RectangleElementParams extends SizedElement, WithChildren {
     radius?: number;
     /** Individual side borders; overrides the uniform `color` border when present. */
     sideBorders?: SideBorders;
+    /** When true, this box is a positioning frame for `Positioned` descendants (CSS `relative`). */
+    relative?: boolean;
+    /** `"hidden"` crops children to the box (CSS `overflow: hidden`); `"visible"` (default) lets a
+     *  `Positioned` child spill over the edge. */
+    overflow?: "hidden" | "visible";
 }
 export declare class RectangleElement extends SizedPDFElement implements Fragmentable {
     private children;
@@ -26,8 +31,10 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
     private borderWidth;
     private radius;
     private sideBorders?;
+    private relative;
+    private overflow;
     private sizeMemory;
-    constructor({ children, color, backgroundColor, borderWidth, width, height, radius, sideBorders, }: RectangleElementParams);
+    constructor({ children, color, backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, }: RectangleElementParams);
     /**
      * Splits the bordered box across pages (box-decoration-break: clone - every fragment
      * gets its own full border). The children stack is packed into the space left after
@@ -50,6 +57,7 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
         borderWidth: number;
         radius: number;
         sideBorders: SideBorders | undefined;
+        overflow: "hidden" | "visible";
     };
 }
 export {};

package/dist/elements/rectangle-element.js

@@ -6,7 +6,7 @@ const box_constraints_1 = require("../layout/box-constraints");
 const fragmentation_1 = require("../layout/fragmentation");
 const pdf_element_1 = require("./pdf-element");
 class RectangleElement extends pdf_element_1.SizedPDFElement {
-    constructor({ children = [], color = new color_1.Color(0, 0, 0), backgroundColor, borderWidth, width, height, radius, sideBorders, }) {
+    constructor({ children = [], color = new color_1.Color(0, 0, 0), backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, }) {
         super({ x: 0, y: 0, width, height });
         this.children = [];
         this.children = children;
@@ -16,6 +16,8 @@ class RectangleElement extends pdf_element_1.SizedPDFElement {
         this.borderWidth = borderWidth !== null && borderWidth !== void 0 ? borderWidth : 1;
         this.radius = radius !== null && radius !== void 0 ? radius : 0;
         this.sideBorders = sideBorders;
+        this.relative = relative !== null && relative !== void 0 ? relative : false;
+        this.overflow = overflow !== null && overflow !== void 0 ? overflow : "visible";
         this.sizeMemory = { x: 0, y: 0, width, height };
     }
     /**
@@ -56,10 +58,12 @@ class RectangleElement extends pdf_element_1.SizedPDFElement {
             borderWidth: this.borderWidth,
             radius: this.radius,
             sideBorders: this.sideBorders,
+            relative: this.relative,
+            overflow: this.overflow,
         });
     }
     calculateLayout(constraints, offset, ctx) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e;
         // Width: an explicit size wins (clamped), else fill the offered box. (Without this a
         // fixed box would balloon to the parent's size.)
         this.width =
@@ -68,6 +72,9 @@ class RectangleElement extends pdf_element_1.SizedPDFElement {
                 : constraints.hasBoundedWidth
                     ? constraints.maxWidth
                     : this.width;
+        // Width shrink-wrap: no explicit width AND an unbounded region (e.g. a `Box` badge inside a
+        // `Positioned`). Resolved after the children are measured, just below.
+        const shrinkWrapWidth = this.sizeMemory.width === undefined && !constraints.hasBoundedWidth;
         // Height: explicit wins; otherwise FILL a bounded region (e.g. inside an Expanded) but
         // SHRINK-WRAP the content in an unbounded one (a note box in a stack). Shrink-wrap is
         // resolved after the children are measured, just below.
@@ -80,26 +87,47 @@ class RectangleElement extends pdf_element_1.SizedPDFElement {
                     : this.height;
         this.x = this.sizeMemory.x + offset.x;
         this.y = this.sizeMemory.y + offset.y;
+        // A `relative` box is a positioning frame: thread a fresh frame to the subtree so any
+        // `Positioned` descendant registers against it (out of flow), then drain it below once the
+        // box is sized. A plain box leaves `ctx` untouched -> byte-identical.
+        const frame = this.relative
+            ? { origin: { x: 0, y: 0 }, size: { width: 0, height: 0 }, place: [] }
+            : undefined;
+        const childCtx = frame ? Object.assign(Object.assign({}, ctx), { frame }) : ctx;
         // Lay out children stacked inside the border (inset by the border width). Width is
         // finalized here; height is left unbounded so each child sizes to its own content.
-        const innerWidth = Math.max(0, ((_a = this.width) !== null && _a !== void 0 ? _a : 0) - 2 * this.borderWidth);
+        const innerWidth = shrinkWrapWidth
+            ? Infinity
+            : Math.max(0, ((_a = this.width) !== null && _a !== void 0 ? _a : 0) - 2 * this.borderWidth);
+        let contentWidth = 0;
         let contentHeight = 0;
         let yCursor = this.y + this.borderWidth;
         for (const child of this.children) {
-            const childSize = child.calculateLayout(box_constraints_1.BoxConstraints.loose(innerWidth, Infinity), { x: this.x + this.borderWidth, y: yCursor }, ctx);
+            const childSize = child.calculateLayout(box_constraints_1.BoxConstraints.loose(innerWidth, Infinity), { x: this.x + this.borderWidth, y: yCursor }, childCtx);
             yCursor += childSize.height;
             contentHeight += childSize.height;
+            contentWidth = Math.max(contentWidth, childSize.width);
         }
+        // No explicit width and no bounded region: shrink-wrap to the widest child.
+        if (shrinkWrapWidth)
+            this.width = contentWidth + 2 * this.borderWidth;
         // No explicit height and no bounded region: the border hugs its content.
         if (shrinkWrapHeight)
             this.height = contentHeight + 2 * this.borderWidth;
+        // The box is sized now: place any out-of-flow `Positioned` descendants against its box.
+        if (frame) {
+            frame.origin = { x: this.x, y: this.y };
+            frame.size = { width: (_b = this.width) !== null && _b !== void 0 ? _b : 0, height: (_c = this.height) !== null && _c !== void 0 ? _c : 0 };
+            for (const place of frame.place)
+                place(frame, ctx);
+        }
         // Border-box model: width/height ARE the outer box (the rect we draw); the content
         // is inset by the border on every side. Report the honest box size - no phantom
         // border added on (that asymmetric "+border" was the source of the magic-3 fudge in
         // fragment). Top-left coordinates; the Y-flip happens at the IR -> backend seam.
         return {
-            width: (_b = this.width) !== null && _b !== void 0 ? _b : 0,
-            height: (_c = this.height) !== null && _c !== void 0 ? _c : 0,
+            width: (_d = this.width) !== null && _d !== void 0 ? _d : 0,
+            height: (_e = this.height) !== null && _e !== void 0 ? _e : 0,
         };
     }
     getProps() {
@@ -114,6 +142,7 @@ class RectangleElement extends pdf_element_1.SizedPDFElement {
             borderWidth: this.borderWidth,
             radius: this.radius,
             sideBorders: this.sideBorders,
+            overflow: this.overflow,
         };
     }
 }

package/dist/ir/display-list.d.ts

@@ -70,5 +70,22 @@ export interface Image {
     /** Corner radius in points for the image box; absent/0 = sharp corners. */
     radius?: number;
 }
+/**
+ * Pushes a clipping region (a rectangle, rounded when `radius` is set). Everything between this and
+ * the matching `ClipPop` is clipped to it - what a Box with `overflow: "hidden"` wraps its children
+ * in, so a `Positioned` child gets cropped at the box edge instead of spilling over.
+ */
+export interface ClipPush {
+    type: "clip-push";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius?: number;
+}
+/** Closes the most recent `ClipPush` (restores the graphics state). */
+export interface ClipPop {
+    type: "clip-pop";
+}
 /** The closed set of primitives the PDF backend knows how to draw. */
-export type IRNode = TextRun | Rect | Line | Image;
+export type IRNode = TextRun | Rect | Line | Image | ClipPush | ClipPop;

package/dist/renderer/pdf-backend.js

@@ -35,6 +35,11 @@ class PdfBackend {
                     }
                     return flipped;
                 }
+                case "clip-push":
+                    // Flip the clip rect around its bottom edge, like a rect.
+                    return Object.assign(Object.assign({}, node), { y: pageHeight - node.y - node.height });
+                case "clip-pop":
+                    return node;
                 default: {
                     const unknown = node;
                     return unknown;
@@ -95,7 +100,7 @@ class PdfBackend {
      * `om` is used only by primitives that allocate PDF resources (images, fonts).
      */
     static serializeNode(node, om) {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c, _d, _e, _f;
         switch (node.type) {
             case "line":
                 // q/Q isolates the graphics state; "[] 0 d" resets the dash pattern to solid.
@@ -173,6 +178,16 @@ class PdfBackend {
                     : `${c.x} ${c.y} ${c.width} ${c.height} re `;
                 return `q\n${clipPath}\nW n \n` + draw + `Q\n`;
             }
+            case "clip-push": {
+                // Save the graphics state and intersect the clip with this (rounded) rect. Everything
+                // drawn until the matching clip-pop is cropped to it.
+                const path = ((_f = node.radius) !== null && _f !== void 0 ? _f : 0) > 0
+                    ? PdfBackend.roundedRectPath(node.x, node.y, node.width, node.height, node.radius)
+                    : `${node.x} ${node.y} ${node.width} ${node.height} re`;
+                return `q\n${path}\nW n\n`;
+            }
+            case "clip-pop":
+                return `Q\n`;
             default: {
                 // Exhaustiveness guard: if a new IRNode variant is added, this fails to compile.
                 const unknown = node;

package/dist/renderer/pdf-renderer.js

@@ -28,6 +28,8 @@ const repeating_header_element_1 = require("../elements/layout/repeating-header-
 const repeating_header_renderer_1 = require("./repeating-header-renderer");
 const deferred_element_1 = require("../elements/layout/deferred-element");
 const deferred_renderer_1 = require("./deferred-renderer");
+const positioned_element_1 = require("../elements/layout/positioned-element");
+const positioned_renderer_1 = require("./positioned-renderer");
 const box_constraints_1 = require("../layout/box-constraints");
 class PDFRenderer {
     static render(document, objectManager) {
@@ -43,6 +45,7 @@ class PDFRenderer {
             renderer_registry_1.RendererRegistry.register(elements_1.LineElement, line_renderer_1.LineRenderer.render);
             renderer_registry_1.RendererRegistry.register(repeating_header_element_1.RepeatingHeaderElement, repeating_header_renderer_1.RepeatingHeaderRenderer.render);
             renderer_registry_1.RendererRegistry.register(deferred_element_1.DeferredElement, deferred_renderer_1.DeferredRenderer.render);
+            renderer_registry_1.RendererRegistry.register(positioned_element_1.PositionedElement, positioned_renderer_1.PositionedRenderer.render);
             let pdfContent = "";
             // Header: version line + the PDF/A binary marker (the object manager owns it so its length
             // matches the xref offset calculation).

package/dist/renderer/positioned-renderer.d.ts

@@ -0,0 +1,6 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager";
+import { PositionedElement } from "../elements/layout/positioned-element";
+import { IRNode } from "../ir/display-list";
+export declare class PositionedRenderer {
+    static render(positionedElement: PositionedElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/positioned-renderer.js

@@ -0,0 +1,25 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PositionedRenderer = void 0;
+const renderer_registry_1 = require("../utils/renderer-registry");
+class PositionedRenderer {
+    static render(positionedElement, objectManager) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // The child was already placed (by the frame) during layout; just emit its IR. It is drawn
+            // after the frame's flow content, so it paints on top.
+            const { child } = positionedElement.getProps();
+            const renderer = renderer_registry_1.RendererRegistry.getRenderer(child);
+            return renderer ? renderer(child, objectManager) : [];
+        });
+    }
+}
+exports.PositionedRenderer = PositionedRenderer;

package/dist/renderer/rectangle-renderer.js

@@ -14,7 +14,7 @@ const renderer_registry_1 = require("../utils/renderer-registry");
 class RectangleRenderer {
     static render(rectangleElement, objectManager) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { x, y, width, height, children, color, backgroundColor, borderWidth, radius, sideBorders, } = rectangleElement.getProps();
+            const { x, y, width, height, children, color, backgroundColor, borderWidth, radius, sideBorders, overflow, } = rectangleElement.getProps();
             const h = height;
             const nodes = [];
             if (sideBorders) {
@@ -33,7 +33,13 @@ class RectangleRenderer {
                     width, height: h, stroke: color, strokeWidth: borderWidth }, (backgroundColor ? { fill: backgroundColor } : {})), (radius ? { radius } : {}));
                 nodes.push(node);
             }
-            // Children follow the box (Rectangle is also a container).
+            // Children follow the box (Rectangle is also a container). With overflow: "hidden" they are
+            // wrapped in a clip to the (rounded) box rect, so a Positioned child is cropped at the edge
+            // instead of spilling over. Default "visible" emits no clip - byte-identical.
+            const clip = overflow === "hidden";
+            if (clip) {
+                nodes.push(Object.assign({ type: "clip-push", x, y, width, height: h }, (radius ? { radius } : {})));
+            }
             if (children)
                 for (const child of children) {
                     const renderer = renderer_registry_1.RendererRegistry.getRenderer(child);
@@ -41,6 +47,8 @@ class RectangleRenderer {
                         nodes.push(...(yield renderer(child, objectManager)));
                     }
                 }
+            if (clip)
+                nodes.push({ type: "clip-pop" });
             return nodes;
         });
     }

package/dist/validators/element-validator.js

@@ -21,11 +21,10 @@ class Validator {
         }
         // Layout validation: geometry comes from the typed getSize(), not the props bag.
         if (element instanceof pdf_element_1.SizedPDFElement) {
-            const { x, y, width, height } = element.getSize();
-            if (x < 0 || y < 0) {
-                throw new Error(`Element ${element.constructor.name} has invalid coordinates (x: ${x}, y: ${y})`);
-            }
-            // 0 is legitimate (a hairline divider, an empty spacer); only a NEGATIVE size is invalid.
+            const { width, height } = element.getSize();
+            // Negative coordinates are allowed: a `Positioned` child overflows its frame on purpose,
+            // and the page clips anything past its edge. 0 size is legitimate (a hairline divider, an
+            // empty spacer); only a NEGATIVE size is invalid.
             if ((width !== undefined && width < 0) || (height !== undefined && height < 0)) {
                 throw new Error(`Element ${element.constructor.name} has invalid size (width: ${width}, height: ${height})`);
             }
@@ -36,11 +35,10 @@ class Validator {
         }
     }
     static validateSizedElement(element) {
-        const { x, y, width, height } = element.getSize();
-        if (x < 0 || y < 0) {
-            throw new Error(`Element ${element.constructor.name} has invalid coordinates (x: ${x}, y: ${y})`);
-        }
-        // A size must be set, but 0 is legitimate (a hairline divider); only NEGATIVE is invalid.
+        const { width, height } = element.getSize();
+        // Negative coordinates are legitimate: a `Positioned` child overflows its frame on purpose
+        // (a corner badge), and the page clips anything off its edge. A size must be set, but 0 is
+        // legitimate (a hairline divider); only a NEGATIVE size is invalid.
         if (width === undefined || height === undefined || width < 0 || height < 0) {
             throw new Error(`Element ${element.constructor.name} has invalid size (width: ${width}, height: ${height})`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasy/pdf",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.2",
   "description": "Declarative, component-based PDF generation in pure TypeScript - Flutter-style components, real AFM font metrics, a hand-rolled PDF writer. No headless browser, no Java.",
   "keywords": [
     "declarative",