@datalking/begonia-table 0.0.0-stage → 0.3.6

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.
@@ -0,0 +1,227 @@
1
+ /**
2
+ * Leaf types the table contracts need.
3
+ *
4
+ * These four primitives - inline revision spans, measured line slices, text line
5
+ * frames and drawing payloads - started in `../types.ts`. That made the table
6
+ * directory import its own parent while `types.ts` imported the table barrel,
7
+ * a type-level cycle that would break the moment table contracts moved into
8
+ * their own package.
9
+ *
10
+ * They live here now, with their transitive type dependencies, so the table
11
+ * directory is a leaf: every import below is local to `table/`. `../types.ts`
12
+ * re-exports every name it used to declare and keeps re-exporting the names the
13
+ * rest of layout-contracts imports, so no consumer changes.
14
+ */
15
+ export type InlineTextTransform = 'uppercase' | 'lowercase' | 'capitalize' | 'none';
16
+ export type InlineRevisionKind = 'insert' | 'delete' | 'format';
17
+ export type InlineRevisionRelationship = 'parent' | 'child';
18
+ export interface InlineRevisionLayer {
19
+ revisionKind: InlineRevisionKind;
20
+ changeId: string;
21
+ authorName?: string | null;
22
+ createdAt?: string | null;
23
+ source?: string | null;
24
+ prompt?: string | null;
25
+ overlapParentId?: string | null;
26
+ relationship?: InlineRevisionRelationship | null;
27
+ }
28
+ export interface InlineImageObjectMetadata {
29
+ readonly kind: 'image';
30
+ readonly src: string;
31
+ /** CSS pixels. */
32
+ readonly width: number | null;
33
+ /** CSS pixels. */
34
+ readonly height: number | null;
35
+ readonly alt: string | null;
36
+ readonly title: string | null;
37
+ readonly objectId: string | null;
38
+ }
39
+ export interface LayoutDrawingPrimitive {
40
+ kind: 'path' | 'rect' | 'ellipse';
41
+ d?: string | null;
42
+ x?: number | null;
43
+ y?: number | null;
44
+ width?: number | null;
45
+ height?: number | null;
46
+ rx?: number | null;
47
+ ry?: number | null;
48
+ cx?: number | null;
49
+ cy?: number | null;
50
+ fill?: string | null;
51
+ fillColor?: string | null;
52
+ fillOpacity?: number | null;
53
+ stroke?: string | null;
54
+ strokeOpacity?: number | null;
55
+ strokeWidth?: number | null;
56
+ strokeDasharray?: string | null;
57
+ strokeLinecap?: string | null;
58
+ strokeLinejoin?: string | null;
59
+ markerStart?: string | null;
60
+ markerEnd?: string | null;
61
+ fillRule?: 'evenodd' | 'nonzero' | null;
62
+ clipRule?: 'evenodd' | 'nonzero' | null;
63
+ }
64
+ export interface LayoutDrawingText {
65
+ lines: readonly string[];
66
+ centerX: number;
67
+ startY: number;
68
+ fontSize: number;
69
+ fontFamily: string;
70
+ fontWeight: 400 | 500 | 600 | 700;
71
+ lineHeight: number;
72
+ fill: string;
73
+ stroke: string | null;
74
+ strokeWidth: number | null;
75
+ }
76
+ export interface LayoutDrawingNode {
77
+ kind: 'shape' | 'group' | 'connector' | 'picture' | 'fallback';
78
+ x: number;
79
+ y: number;
80
+ width: number;
81
+ height: number;
82
+ rotation: number;
83
+ flipH: boolean;
84
+ flipV: boolean;
85
+ opacity: number | null;
86
+ filter: string | null;
87
+ supported: boolean;
88
+ primitives: readonly LayoutDrawingPrimitive[];
89
+ text: LayoutDrawingText | null;
90
+ children: readonly LayoutDrawingNode[];
91
+ }
92
+ export interface LayoutAnchorPosition {
93
+ hRelativeFrom: string | null;
94
+ vRelativeFrom: string | null;
95
+ alignH?: 'left' | 'center' | 'right' | null;
96
+ alignV?: 'top' | 'center' | 'bottom' | null;
97
+ marginOffset?: Readonly<{
98
+ horizontal?: number | null;
99
+ top?: number | null;
100
+ }> | null;
101
+ }
102
+ export interface LayoutWrapDistances {
103
+ distTop: number;
104
+ distRight: number;
105
+ distBottom: number;
106
+ distLeft: number;
107
+ }
108
+ export interface LayoutAnchorOptions {
109
+ behindDoc: boolean | null;
110
+ allowOverlap: boolean | null;
111
+ layoutInCell: boolean | null;
112
+ relativeHeight: number | null;
113
+ }
114
+ export interface LayoutDrawingPayload {
115
+ sourceNodeType: 'ooxml_shape' | 'ooxml_chart' | 'ooxml_math';
116
+ objectId: string | null;
117
+ label: string;
118
+ kind: 'vectorShape' | 'shapeGroup' | 'picture' | 'fallback';
119
+ intrinsicWidth: number;
120
+ intrinsicHeight: number;
121
+ width: number;
122
+ height: number;
123
+ displayMode: 'inline' | 'anchor';
124
+ wrapMode: 'square' | 'tight' | 'through' | 'topBottom' | 'none' | null;
125
+ offsetX: number | null;
126
+ offsetY: number | null;
127
+ alignment: 'left' | 'center' | 'right' | null;
128
+ /** OOXML anchor reference axes and optional authored alignment. */
129
+ position?: Readonly<LayoutAnchorPosition> | null;
130
+ /** Text-wrap clearance, normalized from EMUs to CSS pixels. */
131
+ wrapDistances?: Readonly<LayoutWrapDistances> | null;
132
+ /** Anchor behavior that affects painting and text exclusion. */
133
+ anchorOptions?: Readonly<LayoutAnchorOptions> | null;
134
+ viewBox: string;
135
+ svg: string;
136
+ defs: string | null;
137
+ supported: boolean;
138
+ scene: LayoutDrawingNode;
139
+ }
140
+ export interface InlineDrawingObjectMetadata {
141
+ readonly kind: 'drawing';
142
+ readonly family: 'shape' | 'chart';
143
+ /** CSS pixels. */
144
+ readonly width: number | null;
145
+ /** CSS pixels. */
146
+ readonly height: number | null;
147
+ readonly label: string;
148
+ readonly objectId: string | null;
149
+ readonly renderKey: string;
150
+ readonly drawing: Readonly<LayoutDrawingPayload> | null;
151
+ }
152
+ export type InlineObjectMetadata = InlineImageObjectMetadata | InlineDrawingObjectMetadata;
153
+ /**
154
+ * One inline revision run.
155
+ *
156
+ * The page-field pair is inlined rather than extending `InlinePageFieldSpan`
157
+ * from `../page-field-kind.ts`: the shape is identical, so it stays assignable
158
+ * to that interface, and this module stays free of parent imports.
159
+ */
160
+ export interface InlineRevisionSpan {
161
+ pageFieldKind?: 'page' | 'numpages' | 'section' | 'sectionpages' | null;
162
+ /** The field instruction, kept so a substituted value stays traceable. */
163
+ pageFieldInstruction?: string | null;
164
+ text: string;
165
+ revisionKind?: InlineRevisionKind | null;
166
+ changeId?: string | null;
167
+ authorName?: string | null;
168
+ createdAt?: string | null;
169
+ source?: string | null;
170
+ prompt?: string | null;
171
+ overlapParentId?: string | null;
172
+ relationship?: InlineRevisionRelationship | null;
173
+ revisionLayers?: readonly InlineRevisionLayer[] | null;
174
+ bold?: boolean;
175
+ italic?: boolean;
176
+ underline?: boolean;
177
+ strike?: boolean;
178
+ href?: string | null;
179
+ color?: string | null;
180
+ highlight?: string | null;
181
+ fontFamily?: string | null;
182
+ /** CSS pixels. */
183
+ fontSize?: number | null;
184
+ /** CSS pixels between grapheme clusters. */
185
+ letterSpacing?: number | null;
186
+ vertAlign?: 'superscript' | 'subscript' | 'baseline' | null;
187
+ baselineShift?: number | null;
188
+ textTransform?: InlineTextTransform | null;
189
+ textTransformContextText?: string | null;
190
+ textTransformContextOffset?: number | null;
191
+ smallCaps?: boolean;
192
+ sourceNodeType?: string | null;
193
+ sourceObjectId?: string | null;
194
+ sourceNodeSelectable?: boolean;
195
+ /**
196
+ * Comment threads this text belongs to, outermost first. Comments are boundary
197
+ * nodes rather than a mark, so the ids are accumulated between the boundaries;
198
+ * without them the layout cannot highlight or resolve a commented run.
199
+ */
200
+ commentIds?: readonly string[] | null;
201
+ /**
202
+ * Bookmark anchors starting at this span's first character.
203
+ *
204
+ * A bookmark is a zero-width marker: it occupies a position but no text, so
205
+ * it cannot be a span of its own without inventing a character. Hanging its
206
+ * id on the span starting at the same offset keeps the ids aligned.
207
+ */
208
+ bookmarkIds?: readonly string[] | null;
209
+ readonly inlineObject?: Readonly<InlineObjectMetadata> | null;
210
+ }
211
+ export interface MeasuredLineSlice {
212
+ lineIndex: number;
213
+ lineCount: number;
214
+ text: string;
215
+ fromOffset: number;
216
+ toOffset: number;
217
+ discretionaryHyphen?: boolean;
218
+ }
219
+ export interface TextLineFrame {
220
+ lineIndex: number;
221
+ lineCount: number;
222
+ leftInset: number;
223
+ rightInset: number;
224
+ availableWidth: number;
225
+ fontAscent?: number | null;
226
+ fontDescent?: number | null;
227
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Row measurements already taken during the current pagination pass.
3
+ *
4
+ * Pagination decides where a table row breaks by simulating candidate page breaks:
5
+ * it asks whether the row fits, tries the split, backs out and tries the next
6
+ * candidate. Each attempt re-measured every cell of the row it probed, which for a
7
+ * five row table came to 684 measurements of the same six rows in one pass of a
8
+ * one page document, all of them identical.
9
+ *
10
+ * A layout pass creates this memo, fills it while it paginates and throws it away,
11
+ * so an entry can only be read by the pass that wrote it, and the typography, the
12
+ * measurer and the block it was measured from are fixed for as long as it lives.
13
+ * It is internal to a layout pass; callers must not supply their own.
14
+ */
15
+ export type LayoutTableRowMeasureMemo = Map<object, Map<string, unknown>>;
@@ -0,0 +1,120 @@
1
+ /**
2
+ * The one definition of the text space a laid-out table row is addressed in.
3
+ *
4
+ * A table is projected as a single block. Its rows are flattened into one
5
+ * character string per row - every cell's painted text, joined by
6
+ * {@link TABLE_CELL_TEXT_SEPARATOR} - and the rows themselves are stacked one
7
+ * character apart ({@link TABLE_ROW_TEXT_ADVANCE}). That string is what the
8
+ * renderer annotates (\`data-begonia-cell-text-start\`), what the caret geometry
9
+ * measures, what the row slicer reports, and what the document-to-projection
10
+ * mapping recomputes from the model.
11
+ *
12
+ * Every one of those call sites used to carry its own copy of the arithmetic:
13
+ * \`row.join(' | ').length + 1\` in one module, a running cursor over
14
+ * \`cellText.length\` plus \`' | '.length\` in another, a trimmed variant in a
15
+ * third. They agreed only as long as nobody edited one of them, and the
16
+ * disagreement showed up as a caret painted one character off. This module is
17
+ * the only place allowed to decide:
18
+ *
19
+ * - the cell separator and its length,
20
+ * - the advance between rows,
21
+ * - how a cell's painted text becomes a cell span inside the row,
22
+ * - which characters are addressable (trailing plain spaces are painted but
23
+ * not addressable; a tab or a line break at the end still is),
24
+ * - what the row's measured \"paint text\" is (see
25
+ * {@link TableTextSpaceRow.paintText}).
26
+ *
27
+ * It is deliberately pure and dependency-free so every layer - the table
28
+ * contract, the paginator, the projection geometry and the browser SDK - can
29
+ * share it instead of re-deriving offsets.
30
+ */
31
+ /** Separator the layout paints between two cells of the same row. */
32
+ export declare const TABLE_CELL_TEXT_SEPARATOR = " | ";
33
+ /**
34
+ * Characters the layout spends past a row before the next row starts.
35
+ *
36
+ * One, because a row is addressed as one line: the next row's first character
37
+ * sits one past the previous row's last addressable offset. It is not painted,
38
+ * so it belongs to no cell.
39
+ */
40
+ export declare const TABLE_ROW_TEXT_ADVANCE = 1;
41
+ /** A cell span inside a row's flattened text. */
42
+ export interface TableTextSpaceCell {
43
+ /** Offset of the cell's first painted character, relative to the row. */
44
+ readonly textStart: number;
45
+ /** Painted characters the cell occupies, trailing spaces included. */
46
+ readonly textLength: number;
47
+ /**
48
+ * Characters a caret may address.
49
+ *
50
+ * Trailing plain spaces paint nothing at the end of a cell, so the boundary
51
+ * past them is not reachable; a trailing tab or hard break opens its own
52
+ * caret slot and stays addressable. Everything before the first trailing
53
+ * plain space is addressable either way.
54
+ */
55
+ readonly addressableLength: number;
56
+ /** The cell's painted text, exactly as the layout joins it. */
57
+ readonly text: string;
58
+ /** {@link addressableLength} characters of {@link text}. */
59
+ readonly addressableText: string;
60
+ }
61
+ /** A row inside the table's flattened text. */
62
+ export interface TableTextSpaceRow {
63
+ /** Offset of the row's first character, relative to the table's text. */
64
+ readonly from: number;
65
+ /** One past the row's last character. The row advance follows it. */
66
+ readonly to: number;
67
+ /** The row's offset string: every cell, joined by the separator. */
68
+ readonly text: string;
69
+ /**
70
+ * The string the measured line geometry uses for this row.
71
+ *
72
+ * Deliberately NOT the offset string: empty cells paint no glyphs, so a
73
+ * measured row is the non-empty trimmed cells joined by the separator. It can
74
+ * therefore be shorter than \`to - from\`, and a measured line's text may cover
75
+ * fewer characters than its offset range. That is an approximation of the
76
+ * measurement, not of the offsets - offsets always come from {@link from},
77
+ * {@link to} and the cell spans below.
78
+ */
79
+ readonly paintText: string;
80
+ readonly cells: readonly TableTextSpaceCell[];
81
+ }
82
+ /** A whole table's flattened text, row by row. */
83
+ export interface TableTextSpace {
84
+ readonly rows: readonly TableTextSpaceRow[];
85
+ /** One past the last row's end. */
86
+ readonly length: number;
87
+ }
88
+ /**
89
+ * A cell's addressable text: trailing plain spaces removed.
90
+ *
91
+ * Only U+0020 is dropped. A trailing tab still advances the line and a trailing
92
+ * hard break still opens an empty one, so both keep their caret slot; trimming
93
+ * them made the last position of such a cell unreachable.
94
+ */
95
+ export declare function trimTableCellAddressableText(text: string): string;
96
+ /** The offset string of one row: every cell joined by the separator. */
97
+ export declare function resolveTableRowText(row: readonly string[]): string;
98
+ /** The row's flattened length plus the advance the layout spends past it. */
99
+ export declare function resolveTableRowAdvance(row: readonly string[]): number;
100
+ /** The row's measured string: non-empty trimmed cells joined by the separator. */
101
+ export declare function resolveTableRowPaintText(row: readonly string[]): string;
102
+ /** One row's cell spans, starting at \`from\` in the table's text. */
103
+ export declare function resolveTableRowTextSpace(row: readonly string[], from?: number): TableTextSpaceRow;
104
+ /** Every row's cell spans, numbered the way the layout numbers them. */
105
+ export declare function resolveTableTextSpace(rows: readonly (readonly string[])[]): TableTextSpace;
106
+ /**
107
+ * The table offset of a cell-relative character boundary.
108
+ *
109
+ * \`inCellOffset\` may exceed the cell's addressable length: a boundary past the
110
+ * last glyph still has a place in the row, and callers that want to reject it
111
+ * compare against {@link TableTextSpaceCell.addressableLength} first.
112
+ */
113
+ export declare function resolveTableCellTextOffset(space: TableTextSpace, rowIndex: number, cellIndex: number, inCellOffset: number): number | null;
114
+ /** The cell that owns a table offset, or null for a separator or a gap. */
115
+ export declare function resolveTableCellAtTextOffset(space: TableTextSpace, offset: number): {
116
+ rowIndex: number;
117
+ cellIndex: number;
118
+ cell: TableTextSpaceCell;
119
+ inCell: number;
120
+ } | null;
package/package.json CHANGED
@@ -1,6 +1,65 @@
1
1
  {
2
2
  "name": "@datalking/begonia-table",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.3.6",
4
+ "description": "Editor-agnostic table contracts and placement helpers shared by the begonia layout pipeline",
5
+ "license": "AGPL-3.0",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/uptonking/begonia.git",
9
+ "directory": "packages/table"
10
+ },
11
+ "files": [
12
+ "dist"
13
+ ],
14
+ "type": "module",
15
+ "sideEffects": false,
16
+ "main": "./dist/index.js",
17
+ "types": "./dist/index.d.ts",
18
+ "exports": {
19
+ ".": {
20
+ "types": "./dist/index.d.ts",
21
+ "import": "./dist/index.js"
22
+ },
23
+ "./contracts": {
24
+ "types": "./dist/contracts.d.ts",
25
+ "import": "./dist/contracts.js"
26
+ },
27
+ "./table-cell-anchor-position": {
28
+ "types": "./dist/table-cell-anchor-position.d.ts",
29
+ "import": "./dist/table-cell-anchor-position.js"
30
+ },
31
+ "./table-cell-blocks": {
32
+ "types": "./dist/table-cell-blocks.d.ts",
33
+ "import": "./dist/table-cell-blocks.js"
34
+ },
35
+ "./table-cell-margins": {
36
+ "types": "./dist/table-cell-margins.d.ts",
37
+ "import": "./dist/table-cell-margins.js"
38
+ },
39
+ "./table-cell-placement": {
40
+ "types": "./dist/table-cell-placement.d.ts",
41
+ "import": "./dist/table-cell-placement.js"
42
+ },
43
+ "./table-cell-text-segment": {
44
+ "types": "./dist/table-cell-text-segment.d.ts",
45
+ "import": "./dist/table-cell-text-segment.js"
46
+ },
47
+ "./table-cell-vertical-align": {
48
+ "types": "./dist/table-cell-vertical-align.d.ts",
49
+ "import": "./dist/table-cell-vertical-align.js"
50
+ },
51
+ "./table-layout": {
52
+ "types": "./dist/table-layout.d.ts",
53
+ "import": "./dist/table-layout.js"
54
+ }
55
+ },
56
+ "publishConfig": {
57
+ "access": "public"
58
+ },
59
+ "scripts": {
60
+ "build": "node ../../scripts/run-tsup.mjs src/index.ts src/contracts.ts src/table-layout.ts src/table-cell-anchor-position.ts src/table-cell-blocks.ts src/table-cell-margins.ts src/table-cell-placement.ts src/table-cell-text-segment.ts src/table-cell-vertical-align.ts --format esm --dts --clean",
61
+ "build:test": "tsup src/index.ts src/contracts.ts src/table-layout.ts src/table-cell-anchor-position.ts src/table-cell-blocks.ts src/table-cell-margins.ts src/table-cell-placement.ts src/table-cell-text-segment.ts src/table-cell-vertical-align.ts --format esm",
62
+ "typecheck": "tsc --noEmit"
63
+ },
64
+ "dependencies": {}
65
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
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.