@ponchia/ui 0.5.0 → 0.6.3

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.
Files changed (196) hide show
  1. package/CHANGELOG.md +386 -4
  2. package/MIGRATIONS.json +14 -0
  3. package/README.md +29 -6
  4. package/annotations/index.d.ts +398 -276
  5. package/annotations/index.d.ts.map +1 -0
  6. package/annotations/index.js +350 -77
  7. package/behaviors/carousel.d.ts +28 -0
  8. package/behaviors/carousel.d.ts.map +1 -0
  9. package/behaviors/carousel.js +20 -16
  10. package/behaviors/combobox.d.ts +40 -0
  11. package/behaviors/combobox.d.ts.map +1 -0
  12. package/behaviors/combobox.js +111 -29
  13. package/behaviors/command.d.ts +41 -0
  14. package/behaviors/command.d.ts.map +1 -0
  15. package/behaviors/command.js +27 -15
  16. package/behaviors/connectors.d.ts +17 -0
  17. package/behaviors/connectors.d.ts.map +1 -0
  18. package/behaviors/connectors.js +7 -5
  19. package/behaviors/crosshair.d.ts +42 -0
  20. package/behaviors/crosshair.d.ts.map +1 -0
  21. package/behaviors/crosshair.js +23 -6
  22. package/behaviors/dialog.d.ts +20 -0
  23. package/behaviors/dialog.d.ts.map +1 -0
  24. package/behaviors/dialog.js +6 -2
  25. package/behaviors/disclosure.d.ts +10 -0
  26. package/behaviors/disclosure.d.ts.map +1 -0
  27. package/behaviors/disclosure.js +6 -2
  28. package/behaviors/dismissible.d.ts +10 -0
  29. package/behaviors/dismissible.d.ts.map +1 -0
  30. package/behaviors/dismissible.js +6 -2
  31. package/behaviors/forms.d.ts +27 -0
  32. package/behaviors/forms.d.ts.map +1 -0
  33. package/behaviors/forms.js +54 -13
  34. package/behaviors/glyph.d.ts +14 -0
  35. package/behaviors/glyph.d.ts.map +1 -0
  36. package/behaviors/glyph.js +28 -5
  37. package/behaviors/index.d.ts +31 -237
  38. package/behaviors/index.d.ts.map +1 -0
  39. package/behaviors/index.js +17 -0
  40. package/behaviors/inert.d.ts +20 -0
  41. package/behaviors/inert.d.ts.map +1 -0
  42. package/behaviors/inert.js +46 -0
  43. package/behaviors/internal.d.ts +25 -0
  44. package/behaviors/internal.d.ts.map +1 -0
  45. package/behaviors/internal.js +77 -1
  46. package/behaviors/legend.d.ts +35 -0
  47. package/behaviors/legend.d.ts.map +1 -0
  48. package/behaviors/legend.js +32 -2
  49. package/behaviors/menu.d.ts +16 -0
  50. package/behaviors/menu.d.ts.map +1 -0
  51. package/behaviors/menu.js +6 -2
  52. package/behaviors/modal.d.ts +41 -0
  53. package/behaviors/modal.d.ts.map +1 -0
  54. package/behaviors/modal.js +124 -0
  55. package/behaviors/popover.d.ts +28 -0
  56. package/behaviors/popover.d.ts.map +1 -0
  57. package/behaviors/popover.js +78 -7
  58. package/behaviors/spotlight.d.ts +17 -0
  59. package/behaviors/spotlight.d.ts.map +1 -0
  60. package/behaviors/spotlight.js +7 -5
  61. package/behaviors/table.d.ts +36 -0
  62. package/behaviors/table.d.ts.map +1 -0
  63. package/behaviors/table.js +84 -17
  64. package/behaviors/tabs.d.ts +20 -0
  65. package/behaviors/tabs.d.ts.map +1 -0
  66. package/behaviors/tabs.js +17 -14
  67. package/behaviors/theme.d.ts +54 -0
  68. package/behaviors/theme.d.ts.map +1 -0
  69. package/behaviors/theme.js +22 -3
  70. package/behaviors/toast.d.ts +49 -0
  71. package/behaviors/toast.d.ts.map +1 -0
  72. package/behaviors/toast.js +47 -3
  73. package/classes/classes.json +2527 -0
  74. package/classes/index.d.ts +134 -15
  75. package/classes/index.js +280 -80
  76. package/classes/vscode.css-custom-data.json +12 -0
  77. package/connectors/index.d.ts +201 -69
  78. package/connectors/index.d.ts.map +1 -0
  79. package/connectors/index.js +142 -25
  80. package/css/app.css +69 -13
  81. package/css/base.css +15 -10
  82. package/css/bullet.css +108 -0
  83. package/css/code.css +98 -0
  84. package/css/connectors.css +17 -0
  85. package/css/content.css +22 -3
  86. package/css/crosshair.css +7 -7
  87. package/css/dataviz.css +5 -1
  88. package/css/diff.css +153 -0
  89. package/css/disclosure.css +53 -7
  90. package/css/dots.css +94 -7
  91. package/css/feedback.css +97 -7
  92. package/css/forms.css +113 -4
  93. package/css/legend.css +16 -9
  94. package/css/marks.css +38 -8
  95. package/css/motion.css +98 -53
  96. package/css/navigation.css +7 -0
  97. package/css/overlay.css +90 -3
  98. package/css/primitives.css +158 -13
  99. package/css/report.css +73 -56
  100. package/css/sidenote.css +67 -0
  101. package/css/site.css +16 -2
  102. package/css/sources.css +43 -1
  103. package/css/spark.css +62 -0
  104. package/css/spotlight.css +1 -1
  105. package/css/table.css +9 -2
  106. package/css/term.css +110 -0
  107. package/css/textref.css +63 -0
  108. package/css/toc.css +91 -0
  109. package/css/tokens.css +49 -1
  110. package/css/tree.css +134 -0
  111. package/css/workbench.css +1 -1
  112. package/dist/bronto.css +1 -1
  113. package/dist/css/analytical.css +1 -1
  114. package/dist/css/app.css +1 -1
  115. package/dist/css/base.css +1 -1
  116. package/dist/css/bullet.css +1 -0
  117. package/dist/css/code.css +1 -0
  118. package/dist/css/connectors.css +1 -1
  119. package/dist/css/content.css +1 -1
  120. package/dist/css/crosshair.css +1 -1
  121. package/dist/css/diff.css +1 -0
  122. package/dist/css/disclosure.css +1 -1
  123. package/dist/css/dots.css +1 -1
  124. package/dist/css/feedback.css +1 -1
  125. package/dist/css/forms.css +1 -1
  126. package/dist/css/legend.css +1 -1
  127. package/dist/css/marks.css +1 -1
  128. package/dist/css/motion.css +1 -1
  129. package/dist/css/navigation.css +1 -1
  130. package/dist/css/overlay.css +1 -1
  131. package/dist/css/primitives.css +1 -1
  132. package/dist/css/report.css +1 -1
  133. package/dist/css/sidenote.css +1 -0
  134. package/dist/css/site.css +1 -1
  135. package/dist/css/sources.css +1 -1
  136. package/dist/css/spark.css +1 -0
  137. package/dist/css/spotlight.css +1 -1
  138. package/dist/css/table.css +1 -1
  139. package/dist/css/term.css +1 -0
  140. package/dist/css/textref.css +1 -0
  141. package/dist/css/toc.css +1 -0
  142. package/dist/css/tokens.css +1 -1
  143. package/dist/css/tree.css +1 -0
  144. package/dist/css/workbench.css +1 -1
  145. package/docs/adr/0003-theme-model.md +1 -1
  146. package/docs/annotations.md +133 -14
  147. package/docs/architecture.md +49 -6
  148. package/docs/bullet.md +78 -0
  149. package/docs/code.md +76 -0
  150. package/docs/contrast.md +116 -92
  151. package/docs/d2.md +196 -0
  152. package/docs/diff.md +146 -0
  153. package/docs/legends.md +23 -3
  154. package/docs/marks.md +9 -2
  155. package/docs/mermaid.md +169 -0
  156. package/docs/reference.md +201 -26
  157. package/docs/reporting.md +416 -57
  158. package/docs/sidenote.md +64 -0
  159. package/docs/sources.md +27 -0
  160. package/docs/spark.md +78 -0
  161. package/docs/stability.md +10 -2
  162. package/docs/term.md +81 -0
  163. package/docs/textref.md +78 -0
  164. package/docs/theming.md +44 -5
  165. package/docs/toc.md +83 -0
  166. package/docs/tree.md +74 -0
  167. package/docs/usage.md +354 -16
  168. package/docs/vega.md +244 -0
  169. package/docs/workbench.md +7 -1
  170. package/glyphs/glyphs.js +13 -5
  171. package/llms.txt +285 -14
  172. package/package.json +95 -17
  173. package/qwik/index.d.ts +44 -59
  174. package/qwik/index.d.ts.map +1 -0
  175. package/qwik/index.js +65 -3
  176. package/react/index.d.ts +41 -61
  177. package/react/index.d.ts.map +1 -0
  178. package/react/index.js +63 -3
  179. package/solid/index.d.ts +68 -61
  180. package/solid/index.d.ts.map +1 -0
  181. package/solid/index.js +66 -3
  182. package/tokens/d2.d.ts +38 -0
  183. package/tokens/d2.js +71 -0
  184. package/tokens/d2.json +43 -0
  185. package/tokens/index.d.ts +5 -5
  186. package/tokens/index.js +15 -1
  187. package/tokens/index.json +9 -0
  188. package/tokens/mermaid.d.ts +23 -0
  189. package/tokens/mermaid.js +181 -0
  190. package/tokens/mermaid.json +163 -0
  191. package/tokens/resolved.json +45 -1
  192. package/tokens/skins.js +3 -2
  193. package/tokens/tokens.dtcg.json +26 -0
  194. package/tokens/vega.d.ts +34 -0
  195. package/tokens/vega.js +155 -0
  196. package/tokens/vega.json +179 -0
@@ -1,280 +1,402 @@
1
- /** @ponchia/ui — SVG annotation geometry helpers. */
2
-
3
- export interface AnnotationPoint {
4
- x: number;
5
- y: number;
6
- }
7
-
8
- export interface AnnotationOffset {
9
- dx: number;
10
- dy: number;
11
- }
12
-
13
- export type AnnotationConnectorType = 'callout' | 'elbow' | 'curve';
14
- export type AnnotationAlign = 'start' | 'middle' | 'end';
15
- export type AnnotationValign = 'top' | 'middle' | 'bottom';
16
- export type AxisOrientation = 'horizontal' | 'vertical';
17
- export type TimelineDirection = 'up' | 'down' | 'left' | 'right';
18
-
19
- export interface CircleSubject {
20
- type: 'circle';
21
- radius: number;
22
- radiusPadding?: number;
23
- }
24
-
25
- export interface RectSubject {
26
- type: 'rect';
27
- width: number;
28
- height: number;
29
- x?: number;
30
- y?: number;
31
- padding?: number;
32
- }
33
-
34
- export type ConnectorSubject = CircleSubject | RectSubject;
35
-
36
- export interface ConnectorOptions extends AnnotationOffset {
37
- subject?: ConnectorSubject;
38
- }
39
-
40
- export interface CircleSubjectOptions {
41
- radius: number;
42
- }
43
-
44
- export interface RectSubjectOptions {
45
- width: number;
46
- height: number;
47
- x?: number;
48
- y?: number;
49
- padding?: number;
50
- }
51
-
52
- export interface ThresholdOptions {
53
- x1?: number;
54
- y1?: number;
55
- x2: number;
56
- y2: number;
57
- }
58
-
59
- export interface AxisThresholdOptions {
60
- orientation?: AxisOrientation;
61
- value?: number;
62
- start?: number;
63
- end: number;
64
- }
65
-
66
- export interface BracketSubjectOptions {
67
- x1: number;
68
- y1: number;
69
- x2: number;
70
- y2: number;
71
- depth?: number;
72
- }
73
-
74
- export interface BandSubjectOptions {
75
- x?: number;
76
- y?: number;
77
- width: number;
78
- height: number;
79
- padding?: number;
80
- }
81
-
82
- export interface SlopeSubjectOptions {
83
- x1: number;
84
- y1: number;
85
- x2: number;
86
- y2: number;
87
- }
88
-
89
- export interface ComparisonBraceOptions {
90
- x1: number;
91
- y1: number;
92
- x2: number;
93
- y2: number;
94
- depth?: number;
95
- }
96
-
97
- export interface OutlierClusterOptions {
98
- points: AnnotationPoint[];
99
- radius?: number;
100
- }
101
-
102
- export interface TimelineEventOptions {
103
- size?: number;
104
- direction?: TimelineDirection;
105
- }
106
-
107
- export interface EvidenceMarkerOptions {
108
- x?: number;
109
- y?: number;
110
- width?: number;
111
- height?: number;
112
- padding?: number;
113
- }
114
-
115
- export interface ConnectorEndDotOptions extends AnnotationPoint {
116
- radius?: number;
117
- }
118
-
119
- export interface ConnectorEndArrowOptions {
120
- x1?: number;
121
- y1?: number;
122
- x2: number;
123
- y2: number;
124
- size?: number;
125
- }
126
-
127
- export interface NoteTransformOptions {
128
- dx?: number;
129
- dy?: number;
130
- x?: number;
131
- y?: number;
132
- align?: AnnotationAlign;
133
- valign?: AnnotationValign;
134
- width?: number;
135
- height?: number;
136
- }
137
-
138
- export interface AnnotationBounds {
139
- x?: number;
140
- y?: number;
141
- width: number;
142
- height: number;
143
- }
144
-
145
- export interface NotePlacementOptions {
146
- x?: number;
147
- y?: number;
148
- width: number;
149
- height: number;
150
- bounds: AnnotationBounds;
151
- padding?: number;
152
- gap?: number;
153
- preferred?: 'right' | 'left' | 'top' | 'bottom';
154
- }
155
-
156
- export interface NotePlacement {
157
- dx: number;
158
- dy: number;
159
- align: AnnotationAlign;
160
- valign: AnnotationValign;
161
- transform: string;
162
- }
163
-
164
- export type AnnotationPartsSubject =
165
- | CircleSubject
166
- | RectSubject
167
- | ({ type: 'threshold' } & ThresholdOptions)
168
- | ({ type: 'bracket' } & BracketSubjectOptions)
169
- | ({ type: 'band' } & BandSubjectOptions)
170
- | ({ type: 'slope' } & SlopeSubjectOptions)
171
- | ({ type: 'compare' } & ComparisonBraceOptions)
172
- | ({ type: 'cluster' } & OutlierClusterOptions)
173
- | ({ type: 'axis' } & AxisThresholdOptions)
174
- | ({ type: 'timeline' } & TimelineEventOptions)
175
- | ({ type: 'evidence' } & EvidenceMarkerOptions);
176
-
177
- export interface AnnotationPartsOptions {
178
- type?: AnnotationConnectorType;
179
- x?: number;
180
- y?: number;
181
- dx?: number;
182
- dy?: number;
183
- subject?: AnnotationPartsSubject;
184
- }
185
-
186
- export interface AnnotationParts {
187
- transform: string;
188
- subject: string;
189
- connector: string;
190
- note: string;
191
- }
192
-
193
- export declare function annotationTransform(point?: Partial<AnnotationPoint>): string;
194
- export declare function noteTransform(options?: NoteTransformOptions): string;
195
- export declare function notePlacement(options: NotePlacementOptions): NotePlacement;
196
- export declare function circleSubjectPath(options: CircleSubjectOptions): string;
197
- export declare function rectSubjectPath(options: RectSubjectOptions): string;
198
- export declare function thresholdPath(options: ThresholdOptions): string;
199
- export declare function axisThresholdPath(options: AxisThresholdOptions): string;
200
- export declare function bracketSubjectPath(options: BracketSubjectOptions): string;
201
- export declare function bandSubjectPath(options: BandSubjectOptions): string;
202
- export declare function slopeSubjectPath(options: SlopeSubjectOptions): string;
203
- export declare function comparisonBracePath(options: ComparisonBraceOptions): string;
204
- export declare function outlierClusterPath(options: OutlierClusterOptions): string;
205
- export declare function timelineEventPath(options?: TimelineEventOptions): string;
206
- export declare function evidenceMarkerPath(options?: EvidenceMarkerOptions): string;
207
- export declare function connectorEndDot(options: ConnectorEndDotOptions): string;
208
- export declare function connectorEndArrow(options: ConnectorEndArrowOptions): string;
209
- export declare function connectorLine(options: ConnectorOptions): string;
210
- export declare function connectorElbow(options: ConnectorOptions): string;
211
- export declare function connectorCurve(options: ConnectorOptions): string;
212
- export declare function annotationParts(options?: AnnotationPartsOptions): AnnotationParts;
213
-
214
- export interface DeclutterLabelItem {
215
- /** Desired centre coordinate along the axis. */
216
- pos: number;
217
- /** The label's extent along the axis. */
218
- size: number;
219
- }
220
- export interface DeclutterLabelsOptions {
221
- /** Minimum gap kept between adjacent labels. Default 0. */
222
- gap?: number;
223
- /** Lower bound of the axis. Default -Infinity. */
224
- min?: number;
225
- /** Upper bound of the axis. Default Infinity. */
226
- max?: number;
227
- }
228
1
  /**
229
- * 1-D label declutter: nudge overlapping labels apart, order-preserving and
230
- * deterministic. Returns the adjusted centre per input item (input order). Not
231
- * a general 2-D collision solver.
2
+ * @param {Partial<AnnotationPoint>} [point]
3
+ * @returns {string}
4
+ */
5
+ export function annotationTransform({ x, y }?: Partial<AnnotationPoint>): string;
6
+ /**
7
+ * @param {NoteTransformOptions} [options]
8
+ * @returns {string}
9
+ */
10
+ export function noteTransform({ dx, dy, x, y, align, valign, width, height, }?: NoteTransformOptions): string;
11
+ /**
12
+ * @param {NotePlacementOptions} options
13
+ * @returns {NotePlacement}
14
+ */
15
+ export function notePlacement({ x, y, width, height, bounds, padding, gap, preferred, inset, }?: NotePlacementOptions): NotePlacement;
16
+ /**
17
+ * @param {CircleSubjectOptions} options
18
+ * @returns {string}
19
+ */
20
+ export function circleSubjectPath({ radius }?: CircleSubjectOptions): string;
21
+ /**
22
+ * @param {RectSubjectOptions} options
23
+ * @returns {string}
24
+ */
25
+ export function rectSubjectPath({ width, height, x, y, padding }?: RectSubjectOptions): string;
26
+ /**
27
+ * @param {ThresholdOptions} options
28
+ * @returns {string}
29
+ */
30
+ export function thresholdPath({ x1, y1, x2, y2 }?: ThresholdOptions): string;
31
+ /**
32
+ * @param {AxisThresholdOptions} options
33
+ * @returns {string}
34
+ */
35
+ export function axisThresholdPath({ orientation, value, start, end }?: AxisThresholdOptions): string;
36
+ /**
37
+ * @param {BracketSubjectOptions} options
38
+ * @returns {string}
39
+ */
40
+ export function bracketSubjectPath({ x1, y1, x2, y2, depth }?: BracketSubjectOptions): string;
41
+ /**
42
+ * @param {BandSubjectOptions} options
43
+ * @returns {string}
44
+ */
45
+ export function bandSubjectPath({ x, y, width, height, padding }?: BandSubjectOptions): string;
46
+ /**
47
+ * @param {SlopeSubjectOptions} options
48
+ * @returns {string}
49
+ */
50
+ export function slopeSubjectPath({ x1, y1, x2, y2 }?: SlopeSubjectOptions): string;
51
+ /**
52
+ * @param {ComparisonBraceOptions} options
53
+ * @returns {string}
232
54
  */
233
- export declare function declutterLabels(
234
- items: DeclutterLabelItem[],
235
- opts?: DeclutterLabelsOptions,
236
- ): number[];
237
-
238
- export interface DirectLabelItem {
239
- /** The true data point the label refers to (figure coordinates). */
240
- anchor: AnnotationPoint;
241
- /** The label's extent along the layout axis. */
242
- size: number;
243
- /** Optional identifier, echoed back on the matching output (input order). */
244
- key?: string | number;
245
- }
246
- export interface DirectLabelsOptions {
247
- /** Axis the labels declutter along. 'y' = a vertical column. Default 'y'. */
248
- axis?: 'x' | 'y';
249
- /** Fixed coordinate on the other axis where the label column/row sits. Default 0. */
250
- cross?: number;
251
- /** Minimum gap kept between adjacent labels. Default 0. */
252
- gap?: number;
253
- /** Lower bound of the layout axis. Default -Infinity. */
254
- min?: number;
255
- /** Upper bound of the layout axis. Default Infinity. */
256
- max?: number;
257
- /** Leader-line shape. Default 'straight'. */
258
- shape?: 'straight' | 'elbow' | 'curve';
259
- }
260
- export interface DirectLabel {
261
- /** Placed label point — the leader's label-side end. */
262
- x: number;
263
- y: number;
264
- /** The echoed input anchor. */
265
- anchor: AnnotationPoint;
266
- /** The echoed input key, if any. */
267
- key?: string | number;
268
- /** SVG path for the leader (anchor → label point); '' if they coincide. */
269
- d: string;
270
- }
55
+ export function comparisonBracePath({ x1, y1, x2, y2, depth }?: ComparisonBraceOptions): string;
271
56
  /**
272
- * Direct labeling: declutter labels along one axis and draw a leader from each
273
- * anchor to its placed label (reusing the connector kernel). Deterministic and
274
- * pure — no scales, no DOM, no 2-D placement. Output feeds a
275
- * `<path class="ui-annotation__connector">` plus a label at `{x, y}`.
57
+ * @param {OutlierClusterOptions} options
58
+ * @returns {string}
276
59
  */
277
- export declare function directLabels(
278
- items: DirectLabelItem[],
279
- opts?: DirectLabelsOptions,
280
- ): DirectLabel[];
60
+ export function outlierClusterPath({ points, radius }?: OutlierClusterOptions): string;
61
+ /**
62
+ * @param {TimelineEventOptions} [options]
63
+ * @returns {string}
64
+ */
65
+ export function timelineEventPath({ size, direction }?: TimelineEventOptions): string;
66
+ /**
67
+ * @param {EvidenceMarkerOptions} [options]
68
+ * @returns {string}
69
+ */
70
+ export function evidenceMarkerPath({ x, y, width, height, padding }?: EvidenceMarkerOptions): string;
71
+ /**
72
+ * @param {ConnectorEndDotOptions} options
73
+ * @returns {string}
74
+ */
75
+ export function connectorEndDot({ x, y, radius }?: ConnectorEndDotOptions): string;
76
+ /**
77
+ * @param {ConnectorEndArrowOptions} options
78
+ * @returns {string}
79
+ */
80
+ export function connectorEndArrow({ x1, y1, x2, y2, size, spread }?: ConnectorEndArrowOptions): string;
81
+ /**
82
+ * @param {ConnectorOptions} opts
83
+ * @returns {string}
84
+ */
85
+ export function connectorLine(opts?: ConnectorOptions): string;
86
+ /**
87
+ * @param {ConnectorOptions} opts
88
+ * @returns {string}
89
+ */
90
+ export function connectorElbow(opts?: ConnectorOptions): string;
91
+ /**
92
+ * @param {ConnectorOptions} opts
93
+ * @returns {string}
94
+ */
95
+ export function connectorCurve(opts?: ConnectorOptions): string;
96
+ /**
97
+ * @param {AnnotationPartsOptions} [opts]
98
+ * @returns {AnnotationParts}
99
+ */
100
+ export function annotationParts(opts?: AnnotationPartsOptions): AnnotationParts;
101
+ /**
102
+ * Declutter labels along ONE axis: nudge overlapping labels apart so each keeps
103
+ * `gap` from its neighbours, sweeping up from `min`; if the run overflows `max`
104
+ * it slides up to fit. Deterministic and order-preserving — NOT a general 2-D
105
+ * collision solver (with more labels than the range holds, the overflow past
106
+ * `min` is the caller's to resolve: fewer labels, a longer axis, or rotation).
107
+ *
108
+ * `items`: `[{ pos, size }]` — `pos` is the desired centre coordinate along the
109
+ * axis, `size` the label's extent along it. Returns the adjusted centre per
110
+ * input item, in the original order.
111
+ *
112
+ * @param {DeclutterLabelItem[]} items
113
+ * @param {DeclutterLabelsOptions} [opts]
114
+ * @returns {number[]}
115
+ */
116
+ export function declutterLabels(items: DeclutterLabelItem[], opts?: DeclutterLabelsOptions): number[];
117
+ /**
118
+ * Direct labeling: declutter labels along one axis and draw a leader line from
119
+ * each true anchor to its placed label. This is the 1-D core of Labella,
120
+ * completed with leaders via the shared connector kernel — deterministic and
121
+ * pure. It owns no scales (map data → figure coords first), no DOM, no
122
+ * nearest-anchor matching, and no 2-D placement; those stay the host's job.
123
+ *
124
+ * Each `items[i]` is `{ anchor: {x, y}, size, key? }`: `anchor` is the true
125
+ * data point in figure coordinates, `size` is the label's extent along the
126
+ * layout `axis`. Labels declutter along `axis` ('y' = a vertical column,
127
+ * default) and sit at the fixed `cross` coordinate on the other axis. Returns,
128
+ * in input order, the placed label point `{x, y}`, the echoed `anchor` and
129
+ * `key`, and the leader path `d` (anchor → label; `''` if they coincide) ready
130
+ * for a `<path class="ui-annotation__connector">`.
131
+ *
132
+ * @param {DirectLabelItem[]} items
133
+ * @param {DirectLabelsOptions} [opts]
134
+ * @returns {DirectLabel[]}
135
+ */
136
+ export function directLabels(items: DirectLabelItem[], opts?: DirectLabelsOptions): DirectLabel[];
137
+ export type AnnotationPoint = {
138
+ x: number;
139
+ y: number;
140
+ };
141
+ export type AnnotationOffset = {
142
+ dx: number;
143
+ dy: number;
144
+ };
145
+ export type AnnotationConnectorType = "callout" | "elbow" | "curve";
146
+ export type AnnotationAlign = "start" | "middle" | "end";
147
+ export type AnnotationValign = "top" | "middle" | "bottom";
148
+ export type AxisOrientation = "horizontal" | "vertical";
149
+ export type TimelineDirection = "up" | "down" | "left" | "right";
150
+ export type CircleSubject = {
151
+ type: "circle";
152
+ radius: number;
153
+ radiusPadding?: number | undefined;
154
+ };
155
+ export type RectSubject = {
156
+ type: "rect";
157
+ width: number;
158
+ height: number;
159
+ x?: number | undefined;
160
+ y?: number | undefined;
161
+ padding?: number | undefined;
162
+ };
163
+ export type ConnectorSubject = CircleSubject | RectSubject;
164
+ export type ConnectorOptions = AnnotationOffset & {
165
+ subject?: ConnectorSubject;
166
+ mid?: number;
167
+ };
168
+ export type CircleSubjectOptions = {
169
+ radius: number;
170
+ };
171
+ export type RectSubjectOptions = {
172
+ width: number;
173
+ height: number;
174
+ x?: number | undefined;
175
+ y?: number | undefined;
176
+ padding?: number | undefined;
177
+ };
178
+ export type ThresholdOptions = {
179
+ x1?: number | undefined;
180
+ y1?: number | undefined;
181
+ x2: number;
182
+ y2: number;
183
+ };
184
+ export type AxisThresholdOptions = {
185
+ orientation?: AxisOrientation | undefined;
186
+ value?: number | undefined;
187
+ start?: number | undefined;
188
+ end: number;
189
+ };
190
+ export type BracketSubjectOptions = {
191
+ x1: number;
192
+ y1: number;
193
+ x2: number;
194
+ y2: number;
195
+ depth?: number | undefined;
196
+ };
197
+ export type BandSubjectOptions = {
198
+ x?: number | undefined;
199
+ y?: number | undefined;
200
+ width: number;
201
+ height: number;
202
+ padding?: number | undefined;
203
+ };
204
+ export type SlopeSubjectOptions = {
205
+ x1: number;
206
+ y1: number;
207
+ x2: number;
208
+ y2: number;
209
+ };
210
+ export type ComparisonBraceOptions = {
211
+ x1: number;
212
+ y1: number;
213
+ x2: number;
214
+ y2: number;
215
+ depth?: number | undefined;
216
+ };
217
+ export type OutlierClusterOptions = {
218
+ points: AnnotationPoint[];
219
+ radius?: number | undefined;
220
+ };
221
+ export type TimelineEventOptions = {
222
+ size?: number | undefined;
223
+ direction?: TimelineDirection | undefined;
224
+ };
225
+ export type EvidenceMarkerOptions = {
226
+ x?: number | undefined;
227
+ y?: number | undefined;
228
+ width?: number | undefined;
229
+ height?: number | undefined;
230
+ padding?: number | undefined;
231
+ };
232
+ export type ConnectorEndDotOptions = AnnotationPoint & {
233
+ radius?: number;
234
+ };
235
+ export type ConnectorEndArrowOptions = {
236
+ x1?: number | undefined;
237
+ y1?: number | undefined;
238
+ x2: number;
239
+ y2: number;
240
+ size?: number | undefined;
241
+ /**
242
+ * Half-angle of the arrowhead in radians (default
243
+ * 0.32 ≈ a crisp 37° included angle). Larger = blunter.
244
+ */
245
+ spread?: number | undefined;
246
+ };
247
+ export type NoteTransformOptions = {
248
+ dx?: number | undefined;
249
+ dy?: number | undefined;
250
+ x?: number | undefined;
251
+ y?: number | undefined;
252
+ align?: AnnotationAlign | undefined;
253
+ valign?: AnnotationValign | undefined;
254
+ width?: number | undefined;
255
+ height?: number | undefined;
256
+ };
257
+ export type AnnotationBounds = {
258
+ x?: number | undefined;
259
+ y?: number | undefined;
260
+ width: number;
261
+ height: number;
262
+ };
263
+ export type NotePlacementOptions = {
264
+ x?: number | undefined;
265
+ y?: number | undefined;
266
+ width: number;
267
+ height: number;
268
+ bounds: AnnotationBounds;
269
+ padding?: number | undefined;
270
+ gap?: number | undefined;
271
+ preferred?: "top" | "right" | "bottom" | "left" | undefined;
272
+ /**
273
+ * Extra margin (user units) the note must keep from
274
+ * the bounds edge, on top of `padding`. Reserve the note's title stroke-halo
275
+ * (~3) or a leader stub so a placement that "fits" doesn't clip. Default 0.
276
+ */
277
+ inset?: number | undefined;
278
+ };
279
+ export type NotePlacement = {
280
+ dx: number;
281
+ dy: number;
282
+ align: AnnotationAlign;
283
+ valign: AnnotationValign;
284
+ transform: string;
285
+ };
286
+ export type AnnotationPartsSubject = (CircleSubject | RectSubject | ({
287
+ type: "threshold";
288
+ } & ThresholdOptions) | ({
289
+ type: "bracket";
290
+ } & BracketSubjectOptions) | ({
291
+ type: "band";
292
+ } & BandSubjectOptions) | ({
293
+ type: "slope";
294
+ } & SlopeSubjectOptions) | ({
295
+ type: "compare";
296
+ } & ComparisonBraceOptions) | ({
297
+ type: "cluster";
298
+ } & OutlierClusterOptions) | ({
299
+ type: "axis";
300
+ } & AxisThresholdOptions) | ({
301
+ type: "timeline";
302
+ } & TimelineEventOptions) | ({
303
+ type: "evidence";
304
+ } & EvidenceMarkerOptions));
305
+ export type AnnotationPartsOptions = {
306
+ type?: AnnotationConnectorType | undefined;
307
+ x?: number | undefined;
308
+ y?: number | undefined;
309
+ dx?: number | undefined;
310
+ dy?: number | undefined;
311
+ subject?: AnnotationPartsSubject | undefined;
312
+ };
313
+ export type AnnotationParts = {
314
+ transform: string;
315
+ subject: string;
316
+ connector: string;
317
+ note: string;
318
+ };
319
+ export type DeclutterLabelItem = {
320
+ /**
321
+ * Desired centre coordinate along the axis.
322
+ */
323
+ pos: number;
324
+ /**
325
+ * The label's extent along the axis.
326
+ */
327
+ size: number;
328
+ };
329
+ export type DeclutterLabelsOptions = {
330
+ /**
331
+ * Minimum gap kept between adjacent labels. Default 0.
332
+ */
333
+ gap?: number | undefined;
334
+ /**
335
+ * Lower bound of the axis. Default -Infinity.
336
+ */
337
+ min?: number | undefined;
338
+ /**
339
+ * Upper bound of the axis. Default Infinity.
340
+ */
341
+ max?: number | undefined;
342
+ };
343
+ export type DirectLabelItem = {
344
+ /**
345
+ * The true data point the label refers to (figure coordinates).
346
+ */
347
+ anchor: AnnotationPoint;
348
+ /**
349
+ * The label's extent along the layout axis.
350
+ */
351
+ size: number;
352
+ /**
353
+ * Optional identifier, echoed back on the matching output (input order).
354
+ */
355
+ key?: string | number | undefined;
356
+ };
357
+ export type DirectLabelsOptions = {
358
+ /**
359
+ * Axis the labels declutter along. 'y' = a vertical column. Default 'y'.
360
+ */
361
+ axis?: "x" | "y" | undefined;
362
+ /**
363
+ * Fixed coordinate on the other axis where the label column/row sits. Default 0.
364
+ */
365
+ cross?: number | undefined;
366
+ /**
367
+ * Minimum gap kept between adjacent labels. Default 0.
368
+ */
369
+ gap?: number | undefined;
370
+ /**
371
+ * Lower bound of the layout axis. Default -Infinity.
372
+ */
373
+ min?: number | undefined;
374
+ /**
375
+ * Upper bound of the layout axis. Default Infinity.
376
+ */
377
+ max?: number | undefined;
378
+ /**
379
+ * Leader-line shape. Default 'straight'.
380
+ */
381
+ shape?: "straight" | "elbow" | "curve" | undefined;
382
+ };
383
+ export type DirectLabel = {
384
+ /**
385
+ * Placed label point — the leader's label-side end.
386
+ */
387
+ x: number;
388
+ y: number;
389
+ /**
390
+ * The echoed input anchor.
391
+ */
392
+ anchor: AnnotationPoint;
393
+ /**
394
+ * The echoed input key, if any.
395
+ */
396
+ key?: string | number | undefined;
397
+ /**
398
+ * SVG path for the leader (anchor → label point); '' if they coincide.
399
+ */
400
+ d: string;
401
+ };
402
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":"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"}