@paragraf/layout 0.0.0-stage → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 paragraf contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,167 @@
1
- # Temporary Holding Version
1
+ # @paragraf/layout
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Page geometry, unit converters, and named page sizes for the [paragraf](https://github.com/kadetr/paragraf) typesetter. Browser-safe — no rendering logic, ink, or colour handling.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @paragraf/layout
9
+ ```
10
+
11
+ ## Quick start
12
+
13
+ ```ts
14
+ import { PageLayout, mm } from '@paragraf/layout';
15
+
16
+ const layout = new PageLayout({
17
+ size: 'A4',
18
+ margins: mm(20),
19
+ columns: 2,
20
+ gutter: mm(5),
21
+ bleed: mm(3),
22
+ });
23
+
24
+ // Feed frames into layoutDocument from @paragraf/typography
25
+ const frames = layout.frames(pageCount);
26
+
27
+ // PDF box metadata
28
+ const [pageW, pageH] = layout.pageSize; // includes bleed
29
+ const trimBox = layout.trimBox; // the cut line
30
+ const bleedBox = layout.bleedBox; // full expanded page
31
+ ```
32
+
33
+ ## Unit converters
34
+
35
+ All converters return **points** (pt), the native unit used throughout paragraf. 1 inch = 72 pt.
36
+
37
+ ```ts
38
+ import { mm, cm, inch, px } from '@paragraf/layout';
39
+
40
+ mm(20) // → 56.693 pt
41
+ cm(2) // → 56.693 pt
42
+ inch(0.5) // → 36 pt
43
+ px(100) // → 75 pt (96 dpi, CSS default)
44
+ px(100, 300) // → 24 pt (300 dpi print)
45
+ ```
46
+
47
+ | Function | Formula |
48
+ |---|---|
49
+ | `mm(v)` | `v × 72 / 25.4` |
50
+ | `cm(v)` | `v × 72 / 2.54` |
51
+ | `inch(v)` | `v × 72` |
52
+ | `px(v, dpi?)` | `v × 72 / dpi` (default dpi = 96) |
53
+
54
+ ## Dimension strings
55
+
56
+ Some layout helpers accept a `Dimension` value — either a raw number (already in points) or a string with a unit suffix:
57
+
58
+ ```ts
59
+ import { parseDimension } from '@paragraf/layout';
60
+ import type { Dimension } from '@paragraf/layout';
61
+
62
+ parseDimension(36) // → 36 (pass-through)
63
+ parseDimension('20mm') // → mm(20) ≈ 56.69 pt
64
+ parseDimension('2cm') // → cm(2) ≈ 56.69 pt
65
+ parseDimension('0.5in') // → 36 pt
66
+ parseDimension('36pt') // → 36 pt
67
+ parseDimension('100px') // → px(100) ≈ 75 pt
68
+ ```
69
+
70
+ Supported suffixes: `mm`, `cm`, `in`, `pt`, `px` (case-insensitive). Throws if the string format is unrecognised.
71
+
72
+ ## Named page sizes
73
+
74
+ ```ts
75
+ import { PAGE_SIZES, resolvePageSize } from '@paragraf/layout';
76
+
77
+ PAGE_SIZES.A4 // [595.28, 841.89]
78
+ resolvePageSize('A4') // [595.28, 841.89]
79
+ resolvePageSize([300, 400]) // [300, 400] — pass-through
80
+ ```
81
+
82
+ Available names: `A0`, `A1`, `A2`, `A3`, `A4`, `A5`, `A6`, `B4`, `B5`, `SRA3`, `SRA4`, `Letter`, `Legal`, `Tabloid`.
83
+
84
+ ## Orientation helpers
85
+
86
+ ```ts
87
+ import { landscape, portrait } from '@paragraf/layout';
88
+
89
+ landscape('A4') // [841.89, 595.28] — wider side as width
90
+ portrait('A4') // [595.28, 841.89] — taller side as height (unchanged)
91
+ landscape([595, 842]) // [842, 595]
92
+ ```
93
+
94
+ `landscape` and `portrait` also accept `[width, height]` tuples. Use them to rotate a named size before passing it to `PageLayout`:
95
+
96
+ ```ts
97
+ const layout = new PageLayout({ size: landscape('A4'), margins: mm(20) });
98
+ ```
99
+
100
+ ## Column width helper
101
+
102
+ ```ts
103
+ import { columnWidths } from '@paragraf/layout';
104
+ import type { Frame } from '@paragraf/types';
105
+
106
+ const widths = columnWidths(frame);
107
+ // Single-column frame → [frame.width]
108
+ // Two-column frame with 5mm gutter → [(frame.width - mm(5)) / 2, same]
109
+ ```
110
+
111
+ `columnWidths` computes `(frame.width - (n-1) × gutter) / n` for each of the `n` columns and returns an array of equal widths.
112
+
113
+ ## PageLayout API
114
+
115
+ ### Constructor
116
+
117
+ ```ts
118
+ new PageLayout(opts: PageLayoutOptions)
119
+ ```
120
+
121
+ | Option | Type | Default | Description |
122
+ |---|---|---|---|
123
+ | `size` | `PageSizeName \| [number, number]` | — | Named size or `[width, height]` in points |
124
+ | `margins` | `number \| Margins` | — | Equal margin (number) or per-side object, in points |
125
+ | `columns` | `number` | `1` | Number of text columns per frame |
126
+ | `gutter` | `number` | `0` | Space between columns in points |
127
+ | `bleed` | `number` | `0` | Bleed expansion in points (all four sides) |
128
+
129
+ ### Properties
130
+
131
+ | Property | Type | Description |
132
+ |---|---|---|
133
+ | `pageSize` | `[number, number]` | Page dimensions including bleed — use for PDF MediaBox |
134
+ | `trimSize` | `[number, number]` | Nominal page dimensions without bleed |
135
+ | `trimBox` | `Rect` | Cut-line rectangle within the bleed-expanded space |
136
+ | `bleedBox` | `Rect` | Full page rectangle including bleed area |
137
+
138
+ ### Methods
139
+
140
+ ```ts
141
+ layout.frames(pageCount: number): Frame[]
142
+ ```
143
+
144
+ Returns one `Frame` per page. Each frame covers the printable area (page minus margins), positioned within the bleed-expanded coordinate space. Multi-column frames carry `columnCount` and `gutter`.
145
+
146
+ ## Known limitations
147
+
148
+ ### Facing pages (recto/verso)
149
+
150
+ `PageLayout` uses symmetric margins per frame — there is currently no way to declare different inner/outer margins for left (verso) and right (recto) pages. Professional book layouts commonly require this (e.g. wider inner margin for binding, wider outer for thumb tabs).
151
+
152
+ **Current workaround:** call `frames()` separately for odd and even pages with two `PageLayout` instances using mirrored `Margins` objects, then interleave the resulting `Frame` arrays by page number.
153
+
154
+ A first-class `facingPages: true` option, or a separate `FacingPageLayout` class, is planned for a future release. This limitation is tracked as a known design gap.
155
+
156
+ ## Notes
157
+
158
+ This package handles **geometry only**. It does not produce ink, CMYK values, spot colours, or printer marks. Bleed expands the page size and positions frames correctly — crop marks and output intents are handled by `@paragraf/render-pdf`.
159
+
160
+ ## Layer
161
+
162
+ `@paragraf/layout` is **Layer 1** in the paragraf stack. It depends only on `@paragraf/types`.
163
+
164
+ ```
165
+ Layer 0 @paragraf/types
166
+ Layer 1 @paragraf/layout ← this package
167
+ ```
@@ -0,0 +1,205 @@
1
+ import { Frame } from '@paragraf/types';
2
+
3
+ /** Millimetres → points. */
4
+ declare function mm(value: number): number;
5
+ /** Centimetres → points. */
6
+ declare function cm(value: number): number;
7
+ /** Inches → points. */
8
+ declare function inch(value: number): number;
9
+ /**
10
+ * Pixels → points.
11
+ * @param value Pixel count.
12
+ * @param dpi Screen/print resolution in dots per inch. Defaults to 96 (CSS pixel).
13
+ */
14
+ declare function px(value: number, dpi?: number): number;
15
+ /**
16
+ * A dimension value: either a number (already in points) or a string with a
17
+ * unit suffix — '20mm', '2cm', '0.5in', '100px', '36pt'.
18
+ * Use parseDimension() to resolve to points before passing to layout APIs.
19
+ */
20
+ type Dimension = number | string;
21
+ /**
22
+ * Resolve a Dimension to points.
23
+ * - number → pass-through (already in points)
24
+ * - '20mm' → mm(20), '2cm' → cm(2), '0.5in' → inch(0.5), '100px' → px(100), '36pt' → 36
25
+ * @throws if the string format is unrecognised
26
+ */
27
+ declare function parseDimension(d: Dimension): number;
28
+
29
+ /** Named page size → [width, height] in points. */
30
+ declare const PAGE_SIZES: {
31
+ readonly A0: [number, number];
32
+ readonly A1: [number, number];
33
+ readonly A2: [number, number];
34
+ readonly A3: [number, number];
35
+ readonly A4: [number, number];
36
+ readonly A5: [number, number];
37
+ readonly A6: [number, number];
38
+ readonly B4: [number, number];
39
+ readonly B5: [number, number];
40
+ readonly SRA3: [number, number];
41
+ readonly SRA4: [number, number];
42
+ readonly Letter: [number, number];
43
+ readonly Legal: [number, number];
44
+ readonly Tabloid: [number, number];
45
+ readonly 'JIS-B0': [number, number];
46
+ readonly 'JIS-B1': [number, number];
47
+ readonly 'JIS-B2': [number, number];
48
+ readonly 'JIS-B3': [number, number];
49
+ readonly 'JIS-B4': [number, number];
50
+ readonly 'JIS-B5': [number, number];
51
+ readonly 'JIS-B6': [number, number];
52
+ readonly C5: [number, number];
53
+ readonly C6: [number, number];
54
+ readonly DL: [number, number];
55
+ };
56
+ type PageSizeName = keyof typeof PAGE_SIZES;
57
+ /** Named size string or explicit [width, height] tuple in points. */
58
+ type PageSize = PageSizeName | [number, number];
59
+ /**
60
+ * Resolve a PageSize to a concrete [width, height] tuple in points.
61
+ * Pass-through for tuples; lookup for named sizes.
62
+ */
63
+ declare function resolvePageSize(size: PageSize): [number, number];
64
+ /**
65
+ * Return the size in landscape orientation (wider side as width).
66
+ * If the size is already landscape (or square), it is returned unchanged.
67
+ */
68
+ declare function landscape(size: PageSize): [number, number];
69
+ /**
70
+ * Return the size in portrait orientation (taller side as height).
71
+ * If the size is already portrait (or square), it is returned unchanged.
72
+ */
73
+ declare function portrait(size: PageSize): [number, number];
74
+
75
+ /** Per-side margin values in points. */
76
+ interface Margins {
77
+ top: number;
78
+ right: number;
79
+ bottom: number;
80
+ left: number;
81
+ }
82
+ interface PageLayoutOptions {
83
+ /** Named page size or explicit [width, height] tuple in points. */
84
+ size: PageSize;
85
+ /**
86
+ * Margins in points. Pass a single number for equal margins on all sides,
87
+ * or a Margins object for per-side control.
88
+ */
89
+ margins: number | Margins;
90
+ /** Number of text columns per frame. Defaults to 1. */
91
+ columns?: number;
92
+ /** Space between columns in points. Defaults to 0. */
93
+ gutter?: number;
94
+ /**
95
+ * Bleed in points. The page size is expanded by this amount on all four
96
+ * sides. Text frames are unaffected — they are still positioned relative
97
+ * to the trim edge. Defaults to 0.
98
+ */
99
+ bleed?: number;
100
+ }
101
+ /** Axis-aligned rectangle in points. */
102
+ interface Rect {
103
+ x: number;
104
+ y: number;
105
+ width: number;
106
+ height: number;
107
+ }
108
+ declare class PageLayout {
109
+ private readonly _trimWidth;
110
+ private readonly _trimHeight;
111
+ private readonly _bleed;
112
+ private readonly _margins;
113
+ private readonly _columns;
114
+ private readonly _gutter;
115
+ constructor(opts: PageLayoutOptions);
116
+ /**
117
+ * Page dimensions in points **including bleed** on all four sides.
118
+ * Use this for the PDF MediaBox.
119
+ */
120
+ get pageSize(): [number, number];
121
+ /**
122
+ * Page dimensions in points **without bleed** (the nominal/finished size).
123
+ */
124
+ get trimSize(): [number, number];
125
+ /**
126
+ * The cut-line rectangle — the finished page boundary within the
127
+ * bleed-expanded page coordinate space.
128
+ */
129
+ get trimBox(): Rect;
130
+ /**
131
+ * The full bleed rectangle — covers the entire page including bleed area.
132
+ * Equivalent to { x: 0, y: 0, width: pageSize[0], height: pageSize[1] }.
133
+ */
134
+ get bleedBox(): Rect;
135
+ /**
136
+ * Produce one Frame per page, each filling the printable area defined by
137
+ * the margins, positioned within the bleed-expanded coordinate space.
138
+ *
139
+ * @param pageCount Number of pages to produce frames for.
140
+ */
141
+ frames(pageCount: number): Frame[];
142
+ }
143
+ /**
144
+ * Compute the width of each text column within a frame.
145
+ *
146
+ * For frames with no `columnCount` (single-column), returns `[frame.width]`.
147
+ * For multi-column frames, distributes `frame.width` evenly after subtracting
148
+ * the total gutter space: `(frame.width - (n-1) × gutter) / n` for each column.
149
+ */
150
+ declare function columnWidths(frame: Frame): number[];
151
+
152
+ /**
153
+ * A rectangular region on a page, optionally sub-divided into columns.
154
+ * Regions within a page stack vertically by default (auto-stack).
155
+ * Set `y` explicitly to override the auto-stack position.
156
+ */
157
+ interface RegionSpec {
158
+ /**
159
+ * Height of the region in points or as a Dimension string.
160
+ * Required — regions must have an explicit height.
161
+ */
162
+ height: Dimension;
163
+ /**
164
+ * Number of columns within this region. Defaults to 1.
165
+ */
166
+ columns?: number;
167
+ /**
168
+ * Space between columns in points or as a Dimension string. Defaults to 0.
169
+ */
170
+ gutter?: Dimension;
171
+ /**
172
+ * Horizontal offset from the left edge of the text area in points or as a
173
+ * Dimension string. Defaults to 0 (flush with the left margin).
174
+ */
175
+ x?: Dimension;
176
+ /**
177
+ * Vertical offset from the top edge of the text area in points or as a
178
+ * Dimension string. When omitted, the region is positioned immediately
179
+ * below the previous region (auto-stack). When set, the value is used
180
+ * as-is; the auto-stack pointer still advances by this region's height.
181
+ */
182
+ y?: Dimension;
183
+ /**
184
+ * Width of the region in points or as a Dimension string.
185
+ * Defaults to the full text-area width (trimWidth − left margin − right margin).
186
+ */
187
+ width?: Dimension;
188
+ }
189
+ /**
190
+ * Produce one Frame per column of each region, in reading order.
191
+ *
192
+ * @param regions Array of region specifications.
193
+ * @param textX Left edge of the text area (bleed + margin.left).
194
+ * @param textY Top edge of the text area (bleed + margin.top).
195
+ * @param textWidth Full width of the text area (trimWidth − left − right margins).
196
+ * @param page 0-based page index to stamp on every produced frame.
197
+ * @returns Flat Frame array: all columns of region[0], then region[1], etc.
198
+ *
199
+ * Output frames are single-column (no columnCount / gutter fields set).
200
+ * Auto-stack: regions without an explicit `y` are positioned immediately below
201
+ * the previous region. The stack pointer always advances by each region's height.
202
+ */
203
+ declare function framesForRegions(regions: RegionSpec[], textX: number, textY: number, textWidth: number, page: number): Frame[];
204
+
205
+ export { type Dimension, type Margins, PAGE_SIZES, PageLayout, type PageLayoutOptions, type PageSize, type PageSizeName, type Rect, type RegionSpec, cm, columnWidths, framesForRegions, inch, landscape, mm, parseDimension, portrait, px, resolvePageSize };
package/dist/index.js ADDED
@@ -0,0 +1,276 @@
1
+ // src/units.ts
2
+ var PT_PER_MM = 72 / 25.4;
3
+ var PT_PER_CM = 72 / 2.54;
4
+ var PT_PER_INCH = 72;
5
+ function mm(value) {
6
+ return value * PT_PER_MM;
7
+ }
8
+ function cm(value) {
9
+ return value * PT_PER_CM;
10
+ }
11
+ function inch(value) {
12
+ return value * PT_PER_INCH;
13
+ }
14
+ function px(value, dpi = 96) {
15
+ return value * PT_PER_INCH / dpi;
16
+ }
17
+ function parseDimension(d) {
18
+ if (typeof d === "number") return d;
19
+ const m = d.trim().match(/^(-?[\d.]+)(mm|cm|in|pt|px)$/i);
20
+ if (!m)
21
+ throw new Error(
22
+ `Unrecognised dimension: "${d}" \u2014 expected format like "20mm", "2cm", "0.5in", "36pt", "100px"`
23
+ );
24
+ const value = parseFloat(m[1]);
25
+ switch (m[2].toLowerCase()) {
26
+ case "mm":
27
+ return mm(value);
28
+ case "cm":
29
+ return cm(value);
30
+ case "in":
31
+ return inch(value);
32
+ case "pt":
33
+ return value;
34
+ case "px":
35
+ return px(value);
36
+ default:
37
+ throw new Error(`Unknown unit: "${m[2]}"`);
38
+ }
39
+ }
40
+
41
+ // src/sizes.ts
42
+ var PAGE_SIZES = {
43
+ // ISO A-series
44
+ A0: [2383.94, 3370.39],
45
+ A1: [1683.78, 2383.94],
46
+ A2: [1190.55, 1683.78],
47
+ A3: [841.89, 1190.55],
48
+ A4: [595.28, 841.89],
49
+ A5: [419.53, 595.28],
50
+ A6: [297.64, 419.53],
51
+ // ISO B-series
52
+ B4: [708.66, 1000.63],
53
+ B5: [498.9, 708.66],
54
+ // SRA (bleed paper — common in European commercial print)
55
+ SRA3: [907.09, 1275.59],
56
+ SRA4: [637.8, 907.09],
57
+ // North American
58
+ Letter: [612, 792],
59
+ Legal: [612, 1008],
60
+ Tabloid: [792, 1224],
61
+ // JIS B-series (JIS P 0138 — Japanese Industrial Standard, not ISO B)
62
+ "JIS-B0": [2919.69, 4127.24],
63
+ "JIS-B1": [2063.62, 2919.69],
64
+ "JIS-B2": [1459.84, 2063.62],
65
+ "JIS-B3": [1031.81, 1459.84],
66
+ "JIS-B4": [728.5, 1031.81],
67
+ "JIS-B5": [515.91, 728.5],
68
+ "JIS-B6": [362.83, 515.91],
69
+ // ISO envelope sizes (C-series and DL)
70
+ C5: [459.21, 649.13],
71
+ C6: [323.15, 459.21],
72
+ DL: [311.81, 623.62]
73
+ };
74
+ function resolvePageSize(size) {
75
+ if (Array.isArray(size)) return size;
76
+ const result = PAGE_SIZES[size];
77
+ if (result === void 0)
78
+ throw new Error(
79
+ `Unknown page size: "${String(size)}" \u2014 valid sizes: ${Object.keys(PAGE_SIZES).join(", ")}`
80
+ );
81
+ return result;
82
+ }
83
+ function landscape(size) {
84
+ const [w, h] = resolvePageSize(size);
85
+ return w >= h ? [w, h] : [h, w];
86
+ }
87
+ function portrait(size) {
88
+ const [w, h] = resolvePageSize(size);
89
+ return h >= w ? [w, h] : [h, w];
90
+ }
91
+
92
+ // src/page-layout.ts
93
+ function resolveMargins(m) {
94
+ if (typeof m === "number") {
95
+ return { top: m, right: m, bottom: m, left: m };
96
+ }
97
+ return m;
98
+ }
99
+ var PageLayout = class {
100
+ _trimWidth;
101
+ _trimHeight;
102
+ _bleed;
103
+ _margins;
104
+ _columns;
105
+ _gutter;
106
+ constructor(opts) {
107
+ const [w, h] = resolvePageSize(opts.size);
108
+ this._trimWidth = w;
109
+ this._trimHeight = h;
110
+ this._bleed = opts.bleed ?? 0;
111
+ this._margins = resolveMargins(opts.margins);
112
+ this._columns = opts.columns ?? 1;
113
+ this._gutter = opts.gutter ?? 0;
114
+ if (this._bleed < 0) {
115
+ throw new Error(
116
+ `PageLayout: bleed must be >= 0pt; received ${this._bleed}pt.`
117
+ );
118
+ }
119
+ if (this._columns < 1) {
120
+ throw new Error(
121
+ `PageLayout: columns must be >= 1; received ${this._columns}.`
122
+ );
123
+ }
124
+ if (this._gutter < 0) {
125
+ throw new Error(
126
+ `PageLayout: gutter must be >= 0pt; received ${this._gutter}pt.`
127
+ );
128
+ }
129
+ const horizontalMargins = this._margins.left + this._margins.right;
130
+ if (horizontalMargins >= this._trimWidth) {
131
+ throw new Error(
132
+ `PageLayout: left + right margins (${this._margins.left}pt + ${this._margins.right}pt = ${horizontalMargins}pt) must be less than the trim width (${this._trimWidth}pt).`
133
+ );
134
+ }
135
+ const verticalMargins = this._margins.top + this._margins.bottom;
136
+ if (verticalMargins >= this._trimHeight) {
137
+ throw new Error(
138
+ `PageLayout: top + bottom margins (${this._margins.top}pt + ${this._margins.bottom}pt = ${verticalMargins}pt) must be less than the trim height (${this._trimHeight}pt).`
139
+ );
140
+ }
141
+ if (this._columns > 1) {
142
+ const textWidth = this._trimWidth - horizontalMargins;
143
+ const totalGutter = this._gutter * (this._columns - 1);
144
+ if (totalGutter >= textWidth) {
145
+ throw new Error(
146
+ `PageLayout: gutter (${this._gutter}pt \xD7 ${this._columns - 1} gaps = ${totalGutter}pt) is wider than the available text area (${textWidth}pt). Reduce the gutter or increase the page width / reduce the margins.`
147
+ );
148
+ }
149
+ }
150
+ }
151
+ /**
152
+ * Page dimensions in points **including bleed** on all four sides.
153
+ * Use this for the PDF MediaBox.
154
+ */
155
+ get pageSize() {
156
+ return [
157
+ this._trimWidth + 2 * this._bleed,
158
+ this._trimHeight + 2 * this._bleed
159
+ ];
160
+ }
161
+ /**
162
+ * Page dimensions in points **without bleed** (the nominal/finished size).
163
+ */
164
+ get trimSize() {
165
+ return [this._trimWidth, this._trimHeight];
166
+ }
167
+ /**
168
+ * The cut-line rectangle — the finished page boundary within the
169
+ * bleed-expanded page coordinate space.
170
+ */
171
+ get trimBox() {
172
+ return {
173
+ x: this._bleed,
174
+ y: this._bleed,
175
+ width: this._trimWidth,
176
+ height: this._trimHeight
177
+ };
178
+ }
179
+ /**
180
+ * The full bleed rectangle — covers the entire page including bleed area.
181
+ * Equivalent to { x: 0, y: 0, width: pageSize[0], height: pageSize[1] }.
182
+ */
183
+ get bleedBox() {
184
+ const [w, h] = this.pageSize;
185
+ return { x: 0, y: 0, width: w, height: h };
186
+ }
187
+ /**
188
+ * Produce one Frame per page, each filling the printable area defined by
189
+ * the margins, positioned within the bleed-expanded coordinate space.
190
+ *
191
+ * @param pageCount Number of pages to produce frames for.
192
+ */
193
+ frames(pageCount) {
194
+ const result = [];
195
+ const frameX = this._bleed + this._margins.left;
196
+ const frameY = this._bleed + this._margins.top;
197
+ const frameW = this._trimWidth - this._margins.left - this._margins.right;
198
+ const frameH = this._trimHeight - this._margins.top - this._margins.bottom;
199
+ for (let i = 0; i < pageCount; i++) {
200
+ const frame = {
201
+ page: i,
202
+ x: frameX,
203
+ y: frameY,
204
+ width: frameW,
205
+ height: frameH
206
+ };
207
+ if (this._columns > 1) {
208
+ frame.columnCount = this._columns;
209
+ frame.gutter = this._gutter;
210
+ }
211
+ result.push(frame);
212
+ }
213
+ return result;
214
+ }
215
+ };
216
+ function columnWidths(frame) {
217
+ const count = frame.columnCount ?? 1;
218
+ const gutter = frame.gutter ?? 0;
219
+ const colWidth = (frame.width - (count - 1) * gutter) / count;
220
+ return Array.from({ length: count }, () => colWidth);
221
+ }
222
+
223
+ // src/region-layout.ts
224
+ function framesForRegions(regions, textX, textY, textWidth, page) {
225
+ const frames = [];
226
+ let stackY = 0;
227
+ for (const region of regions) {
228
+ const regionHeight = parseDimension(region.height);
229
+ const regionX = region.x !== void 0 ? parseDimension(region.x) : 0;
230
+ const regionY = region.y !== void 0 ? parseDimension(region.y) : stackY;
231
+ const regionWidth = region.width !== void 0 ? parseDimension(region.width) : textWidth;
232
+ const columns = region.columns ?? 1;
233
+ const gutter = region.gutter !== void 0 ? parseDimension(region.gutter) : 0;
234
+ if (!Number.isInteger(columns) || columns < 1) {
235
+ throw new RangeError(
236
+ `[paragraf] framesForRegions(): columns must be a positive integer (got ${columns})`
237
+ );
238
+ }
239
+ if (gutter < 0) {
240
+ throw new RangeError(
241
+ `[paragraf] framesForRegions(): gutter must be non-negative (got ${gutter})`
242
+ );
243
+ }
244
+ const colWidth = columns === 1 ? regionWidth : (regionWidth - gutter * (columns - 1)) / columns;
245
+ if (colWidth <= 0) {
246
+ throw new RangeError(
247
+ `[paragraf] framesForRegions(): computed column width is ${colWidth}pt \u2014 check regionWidth, columns, and gutter values`
248
+ );
249
+ }
250
+ for (let c = 0; c < columns; c++) {
251
+ frames.push({
252
+ page,
253
+ x: textX + regionX + c * (colWidth + gutter),
254
+ y: textY + regionY,
255
+ width: colWidth,
256
+ height: regionHeight
257
+ });
258
+ }
259
+ stackY += regionHeight;
260
+ }
261
+ return frames;
262
+ }
263
+ export {
264
+ PAGE_SIZES,
265
+ PageLayout,
266
+ cm,
267
+ columnWidths,
268
+ framesForRegions,
269
+ inch,
270
+ landscape,
271
+ mm,
272
+ parseDimension,
273
+ portrait,
274
+ px,
275
+ resolvePageSize
276
+ };
package/package.json CHANGED
@@ -1,6 +1,61 @@
1
1
  {
2
2
  "name": "@paragraf/layout",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.7.0",
4
+ "description": "Page geometry, unit converters, and named page sizes for the paragraf typesetter.",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "https://github.com/kadetr/paragraf.git",
9
+ "directory": "1c-layout"
10
+ },
11
+ "homepage": "https://github.com/kadetr/paragraf/tree/main/1c-layout#readme",
12
+ "keywords": [
13
+ "typography",
14
+ "typesetting",
15
+ "layout",
16
+ "page",
17
+ "geometry",
18
+ "paragraf"
19
+ ],
20
+ "type": "module",
21
+ "engines": {
22
+ "node": ">=22"
23
+ },
24
+ "files": [
25
+ "dist/",
26
+ "README.md"
27
+ ],
28
+ "exports": {
29
+ ".": {
30
+ "types": "./dist/index.d.ts",
31
+ "default": "./dist/index.js"
32
+ }
33
+ },
34
+ "publishConfig": {
35
+ "access": "public",
36
+ "exports": {
37
+ ".": {
38
+ "types": "./dist/index.d.ts",
39
+ "default": "./dist/index.js"
40
+ }
41
+ }
42
+ },
43
+ "scripts": {
44
+ "build": "tsup",
45
+ "prepublishOnly": "npm run build",
46
+ "test": "vitest run --passWithNoTests",
47
+ "test:watch": "vitest",
48
+ "typecheck": "tsc --noEmit",
49
+ "prepack": "node ../scripts/publishconfig-swap.mjs apply",
50
+ "postpack": "node ../scripts/publishconfig-swap.mjs restore"
51
+ },
52
+ "dependencies": {
53
+ "@paragraf/types": "^0.7.0"
54
+ },
55
+ "devDependencies": {
56
+ "@types/node": "^22.19.15",
57
+ "tsup": "^8.5.1",
58
+ "typescript": "^5.4.0",
59
+ "vitest": "^3.2.4"
60
+ }
61
+ }