@ponchia/ui 0.5.0 → 0.6.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.
Files changed (117) hide show
  1. package/CHANGELOG.md +322 -0
  2. package/MIGRATIONS.json +14 -0
  3. package/README.md +28 -5
  4. package/annotations/index.d.ts +398 -276
  5. package/annotations/index.d.ts.map +1 -0
  6. package/annotations/index.js +315 -45
  7. package/behaviors/carousel.js +17 -16
  8. package/behaviors/combobox.js +47 -16
  9. package/behaviors/command.js +18 -15
  10. package/behaviors/connectors.js +4 -5
  11. package/behaviors/crosshair.js +4 -5
  12. package/behaviors/dialog.js +3 -2
  13. package/behaviors/disclosure.js +3 -2
  14. package/behaviors/dismissible.js +3 -2
  15. package/behaviors/forms.js +41 -13
  16. package/behaviors/glyph.js +4 -5
  17. package/behaviors/internal.js +47 -0
  18. package/behaviors/legend.js +23 -2
  19. package/behaviors/menu.js +3 -2
  20. package/behaviors/popover.js +78 -7
  21. package/behaviors/spotlight.js +4 -5
  22. package/behaviors/table.js +39 -12
  23. package/behaviors/tabs.js +14 -14
  24. package/behaviors/theme.js +5 -3
  25. package/behaviors/toast.js +13 -1
  26. package/classes/classes.json +1857 -0
  27. package/classes/index.d.ts +28 -13
  28. package/classes/index.js +34 -18
  29. package/classes/vscode.css-custom-data.json +12 -0
  30. package/connectors/index.d.ts +189 -69
  31. package/connectors/index.d.ts.map +1 -0
  32. package/connectors/index.js +120 -24
  33. package/css/app.css +43 -13
  34. package/css/base.css +15 -10
  35. package/css/connectors.css +17 -0
  36. package/css/content.css +7 -1
  37. package/css/dataviz.css +5 -1
  38. package/css/disclosure.css +38 -6
  39. package/css/dots.css +57 -0
  40. package/css/feedback.css +60 -2
  41. package/css/forms.css +42 -1
  42. package/css/legend.css +11 -7
  43. package/css/marks.css +38 -8
  44. package/css/motion.css +24 -44
  45. package/css/navigation.css +7 -0
  46. package/css/overlay.css +31 -1
  47. package/css/primitives.css +91 -5
  48. package/css/report.css +40 -63
  49. package/css/site.css +16 -2
  50. package/css/sources.css +43 -1
  51. package/css/spotlight.css +1 -1
  52. package/css/tokens.css +36 -1
  53. package/css/workbench.css +1 -1
  54. package/dist/bronto.css +1 -1
  55. package/dist/css/analytical.css +1 -1
  56. package/dist/css/app.css +1 -1
  57. package/dist/css/base.css +1 -1
  58. package/dist/css/connectors.css +1 -1
  59. package/dist/css/content.css +1 -1
  60. package/dist/css/disclosure.css +1 -1
  61. package/dist/css/dots.css +1 -1
  62. package/dist/css/feedback.css +1 -1
  63. package/dist/css/forms.css +1 -1
  64. package/dist/css/legend.css +1 -1
  65. package/dist/css/marks.css +1 -1
  66. package/dist/css/motion.css +1 -1
  67. package/dist/css/navigation.css +1 -1
  68. package/dist/css/overlay.css +1 -1
  69. package/dist/css/primitives.css +1 -1
  70. package/dist/css/report.css +1 -1
  71. package/dist/css/site.css +1 -1
  72. package/dist/css/sources.css +1 -1
  73. package/dist/css/spotlight.css +1 -1
  74. package/dist/css/tokens.css +1 -1
  75. package/dist/css/workbench.css +1 -1
  76. package/docs/adr/0003-theme-model.md +1 -1
  77. package/docs/annotations.md +94 -14
  78. package/docs/architecture.md +50 -6
  79. package/docs/contrast.md +116 -92
  80. package/docs/d2.md +195 -0
  81. package/docs/legends.md +18 -2
  82. package/docs/marks.md +9 -2
  83. package/docs/mermaid.md +152 -0
  84. package/docs/reference.md +78 -22
  85. package/docs/reporting.md +395 -57
  86. package/docs/sources.md +27 -0
  87. package/docs/stability.md +9 -2
  88. package/docs/usage.md +101 -4
  89. package/docs/vega.md +225 -0
  90. package/docs/workbench.md +7 -1
  91. package/glyphs/glyphs.js +6 -4
  92. package/llms.txt +139 -14
  93. package/package.json +50 -12
  94. package/qwik/index.d.ts +42 -59
  95. package/qwik/index.d.ts.map +1 -0
  96. package/qwik/index.js +55 -3
  97. package/react/index.d.ts +39 -61
  98. package/react/index.d.ts.map +1 -0
  99. package/react/index.js +57 -3
  100. package/solid/index.d.ts +64 -61
  101. package/solid/index.d.ts.map +1 -0
  102. package/solid/index.js +60 -3
  103. package/tokens/d2.d.ts +38 -0
  104. package/tokens/d2.js +71 -0
  105. package/tokens/d2.json +43 -0
  106. package/tokens/index.d.ts +5 -5
  107. package/tokens/index.js +15 -1
  108. package/tokens/index.json +9 -0
  109. package/tokens/mermaid.d.ts +23 -0
  110. package/tokens/mermaid.js +181 -0
  111. package/tokens/mermaid.json +163 -0
  112. package/tokens/resolved.json +45 -1
  113. package/tokens/skins.js +3 -2
  114. package/tokens/tokens.dtcg.json +26 -0
  115. package/tokens/vega.d.ts +34 -0
  116. package/tokens/vega.js +155 -0
  117. package/tokens/vega.json +179 -0
@@ -34,6 +34,11 @@ export declare const cls: {
34
34
  readonly numPos: 'ui-num--pos';
35
35
  readonly numNeg: 'ui-num--neg';
36
36
  readonly numMuted: 'ui-num--muted';
37
+ readonly delta: 'ui-delta';
38
+ readonly deltaUp: 'ui-delta--up';
39
+ readonly deltaDown: 'ui-delta--down';
40
+ readonly deltaFlat: 'ui-delta--flat';
41
+ readonly deltaInvert: 'ui-delta--invert';
37
42
  readonly badge: 'ui-badge';
38
43
  readonly badgeAccent: 'ui-badge--accent';
39
44
  readonly badgeSuccess: 'ui-badge--success';
@@ -127,6 +132,7 @@ export declare const cls: {
127
132
  readonly meterSuccess: 'ui-meter--success';
128
133
  readonly meterWarning: 'ui-meter--warning';
129
134
  readonly meterDanger: 'ui-meter--danger';
135
+ readonly meterInfo: 'ui-meter--info';
130
136
  readonly steps: 'ui-steps';
131
137
  readonly stepsItem: 'ui-steps__item';
132
138
  readonly stepsItemDone: 'ui-steps__item--done';
@@ -237,7 +243,7 @@ export declare const cls: {
237
243
  readonly reportNumbered: 'ui-report--numbered';
238
244
  readonly reportCover: 'ui-report__cover';
239
245
  readonly reportCoverCompact: 'ui-report__cover--compact';
240
- readonly reportHeader: 'ui-report__header';
246
+ readonly reportHead: 'ui-report__head';
241
247
  readonly reportTitle: 'ui-report__title';
242
248
  readonly reportSubtitle: 'ui-report__subtitle';
243
249
  readonly reportMeta: 'ui-report__meta';
@@ -253,14 +259,10 @@ export declare const cls: {
253
259
  readonly reportSources: 'ui-report__sources';
254
260
  readonly reportAppendix: 'ui-report__appendix';
255
261
  readonly reportFootnotes: 'ui-report__footnotes';
256
- readonly chart: 'ui-chart';
257
- readonly chartCaption: 'ui-chart__caption';
258
- readonly chartPlot: 'ui-chart__plot';
259
- readonly chartBar: 'ui-chart__bar';
260
- readonly chartLabel: 'ui-chart__label';
261
- readonly chartTrack: 'ui-chart__track';
262
- readonly chartFill: 'ui-chart__fill';
263
- readonly chartFallback: 'ui-chart__fallback';
262
+ readonly compare: 'ui-compare';
263
+ readonly compare2up: 'ui-compare--2up';
264
+ readonly compareCol: 'ui-compare__col';
265
+ readonly compareHead: 'ui-compare__head';
264
266
  readonly legend: 'ui-legend';
265
267
  readonly legendVertical: 'ui-legend--vertical';
266
268
  readonly legendCompact: 'ui-legend--compact';
@@ -338,6 +340,7 @@ export declare const cls: {
338
340
  readonly bracketNote: 'ui-bracket-note';
339
341
  readonly bracketNoteLabel: 'ui-bracket-note__label';
340
342
  readonly bracketNoteAccent: 'ui-bracket-note--accent';
343
+ readonly bracketNoteSuccess: 'ui-bracket-note--success';
341
344
  readonly bracketNoteWarning: 'ui-bracket-note--warning';
342
345
  readonly bracketNoteDanger: 'ui-bracket-note--danger';
343
346
  readonly bracketNoteInfo: 'ui-bracket-note--info';
@@ -383,6 +386,7 @@ export declare const cls: {
383
386
  readonly sourceCardActions: 'ui-source-card__actions';
384
387
  readonly provenance: 'ui-provenance';
385
388
  readonly provenanceItem: 'ui-provenance__item';
389
+ readonly src: 'ui-src';
386
390
  readonly srcVerified: 'ui-src--verified';
387
391
  readonly srcUnverified: 'ui-src--unverified';
388
392
  readonly srcGenerated: 'ui-src--generated';
@@ -416,7 +420,7 @@ export declare const cls: {
416
420
  readonly toolCallStatus: 'ui-tool-call__status';
417
421
  readonly toolCallBody: 'ui-tool-call__body';
418
422
  readonly inspector: 'ui-inspector';
419
- readonly inspectorHeader: 'ui-inspector__header';
423
+ readonly inspectorHead: 'ui-inspector__head';
420
424
  readonly inspectorBody: 'ui-inspector__body';
421
425
  readonly property: 'ui-property';
422
426
  readonly propertyLabel: 'ui-property__label';
@@ -463,7 +467,6 @@ export declare const cls: {
463
467
  readonly appShellFull: 'ui-app-shell--full';
464
468
  readonly appRail: 'ui-app-rail';
465
469
  readonly appRailBrand: 'ui-app-rail__brand';
466
- readonly appRailToggle: 'ui-app-rail__toggle';
467
470
  readonly appRailFoot: 'ui-app-rail__foot';
468
471
  readonly appRailAccount: 'ui-app-rail__account';
469
472
  readonly appTopbar: 'ui-app-topbar';
@@ -509,6 +512,16 @@ export interface BadgeOpts {
509
512
  export interface NumOpts {
510
513
  tone?: 'pos' | 'neg' | 'muted';
511
514
  }
515
+ export interface DeltaOpts {
516
+ /** Trend direction — sets the arrow glyph and the conventional tone. */
517
+ dir?: 'up' | 'down' | 'flat';
518
+ /** Swap only the tone when `up` is the bad direction (latency, error rate, cost). */
519
+ invert?: boolean;
520
+ }
521
+ export interface CompareOpts {
522
+ /** Pin exactly two equal columns (hard before/after) instead of the auto-fitting set. */
523
+ cols?: 2;
524
+ }
512
525
  export interface ChipOpts {
513
526
  accent?: boolean;
514
527
  }
@@ -552,7 +565,7 @@ export interface ProgressOpts {
552
565
  indeterminate?: boolean;
553
566
  }
554
567
  export interface MeterOpts {
555
- tone?: 'accent' | 'success' | 'warning' | 'danger';
568
+ tone?: 'accent' | 'success' | 'warning' | 'danger' | 'info';
556
569
  }
557
570
  export interface DotspinnerOpts {
558
571
  size?: 'sm' | 'lg';
@@ -621,7 +634,7 @@ export interface MarkOpts {
621
634
  motion?: 'draw';
622
635
  }
623
636
  export interface BracketNoteOpts {
624
- tone?: 'accent' | 'warning' | 'danger' | 'info';
637
+ tone?: 'accent' | 'success' | 'warning' | 'danger' | 'info';
625
638
  }
626
639
  export interface ConnectorOpts {
627
640
  tone?: 'accent' | 'muted' | 'success' | 'warning' | 'danger' | 'info';
@@ -683,6 +696,8 @@ export interface Ui {
683
696
  card(opts?: CardOpts): string;
684
697
  badge(opts?: BadgeOpts): string;
685
698
  num(opts?: NumOpts): string;
699
+ delta(opts?: DeltaOpts): string;
700
+ compare(opts?: CompareOpts): string;
686
701
  chip(opts?: ChipOpts): string;
687
702
  link(opts?: LinkOpts): string;
688
703
  dot(opts?: DotOpts): string;
package/classes/index.js CHANGED
@@ -38,6 +38,11 @@ export const cls = Object.freeze({
38
38
  numPos: 'ui-num--pos',
39
39
  numNeg: 'ui-num--neg',
40
40
  numMuted: 'ui-num--muted',
41
+ delta: 'ui-delta',
42
+ deltaUp: 'ui-delta--up',
43
+ deltaDown: 'ui-delta--down',
44
+ deltaFlat: 'ui-delta--flat',
45
+ deltaInvert: 'ui-delta--invert',
41
46
  badge: 'ui-badge',
42
47
  badgeAccent: 'ui-badge--accent',
43
48
  badgeSuccess: 'ui-badge--success',
@@ -134,6 +139,7 @@ export const cls = Object.freeze({
134
139
  meterSuccess: 'ui-meter--success',
135
140
  meterWarning: 'ui-meter--warning',
136
141
  meterDanger: 'ui-meter--danger',
142
+ meterInfo: 'ui-meter--info',
137
143
  steps: 'ui-steps',
138
144
  stepsItem: 'ui-steps__item',
139
145
  stepsItemDone: 'ui-steps__item--done',
@@ -251,7 +257,7 @@ export const cls = Object.freeze({
251
257
  reportNumbered: 'ui-report--numbered',
252
258
  reportCover: 'ui-report__cover',
253
259
  reportCoverCompact: 'ui-report__cover--compact',
254
- reportHeader: 'ui-report__header',
260
+ reportHead: 'ui-report__head',
255
261
  reportTitle: 'ui-report__title',
256
262
  reportSubtitle: 'ui-report__subtitle',
257
263
  reportMeta: 'ui-report__meta',
@@ -267,14 +273,10 @@ export const cls = Object.freeze({
267
273
  reportSources: 'ui-report__sources',
268
274
  reportAppendix: 'ui-report__appendix',
269
275
  reportFootnotes: 'ui-report__footnotes',
270
- chart: 'ui-chart',
271
- chartCaption: 'ui-chart__caption',
272
- chartPlot: 'ui-chart__plot',
273
- chartBar: 'ui-chart__bar',
274
- chartLabel: 'ui-chart__label',
275
- chartTrack: 'ui-chart__track',
276
- chartFill: 'ui-chart__fill',
277
- chartFallback: 'ui-chart__fallback',
276
+ compare: 'ui-compare',
277
+ compare2up: 'ui-compare--2up',
278
+ compareCol: 'ui-compare__col',
279
+ compareHead: 'ui-compare__head',
278
280
  // legend (standalone data keys — css/legend.css)
279
281
  legend: 'ui-legend',
280
282
  legendVertical: 'ui-legend--vertical',
@@ -354,6 +356,7 @@ export const cls = Object.freeze({
354
356
  bracketNote: 'ui-bracket-note',
355
357
  bracketNoteLabel: 'ui-bracket-note__label',
356
358
  bracketNoteAccent: 'ui-bracket-note--accent',
359
+ bracketNoteSuccess: 'ui-bracket-note--success',
357
360
  bracketNoteWarning: 'ui-bracket-note--warning',
358
361
  bracketNoteDanger: 'ui-bracket-note--danger',
359
362
  bracketNoteInfo: 'ui-bracket-note--info',
@@ -404,6 +407,7 @@ export const cls = Object.freeze({
404
407
  sourceCardActions: 'ui-source-card__actions',
405
408
  provenance: 'ui-provenance',
406
409
  provenanceItem: 'ui-provenance__item',
410
+ src: 'ui-src',
407
411
  srcVerified: 'ui-src--verified',
408
412
  srcUnverified: 'ui-src--unverified',
409
413
  srcGenerated: 'ui-src--generated',
@@ -440,7 +444,7 @@ export const cls = Object.freeze({
440
444
  toolCallBody: 'ui-tool-call__body',
441
445
  // workbench — inspector / property / selection bar (css/workbench.css)
442
446
  inspector: 'ui-inspector',
443
- inspectorHeader: 'ui-inspector__header',
447
+ inspectorHead: 'ui-inspector__head',
444
448
  inspectorBody: 'ui-inspector__body',
445
449
  property: 'ui-property',
446
450
  propertyLabel: 'ui-property__label',
@@ -490,7 +494,6 @@ export const cls = Object.freeze({
490
494
  appShellFull: 'ui-app-shell--full',
491
495
  appRail: 'ui-app-rail',
492
496
  appRailBrand: 'ui-app-rail__brand',
493
- appRailToggle: 'ui-app-rail__toggle',
494
497
  appRailFoot: 'ui-app-rail__foot',
495
498
  appRailAccount: 'ui-app-rail__account',
496
499
  appTopbar: 'ui-app-topbar',
@@ -543,14 +546,16 @@ const stateTone = (state) =>
543
546
  })[state] || '';
544
547
 
545
548
  // Trust-state → tone class, shared by the source/citation/provenance recipes.
549
+ // Object-literal lookup to match stateTone above (shorter, greppable, one idiom).
546
550
  const srcTone = (state) =>
547
- (state === 'verified' && cls.srcVerified) ||
548
- (state === 'unverified' && cls.srcUnverified) ||
549
- (state === 'generated' && cls.srcGenerated) ||
550
- (state === 'reviewed' && cls.srcReviewed) ||
551
- (state === 'stale' && cls.srcStale) ||
552
- (state === 'conflict' && cls.srcConflict) ||
553
- '';
551
+ ({
552
+ verified: cls.srcVerified,
553
+ unverified: cls.srcUnverified,
554
+ generated: cls.srcGenerated,
555
+ reviewed: cls.srcReviewed,
556
+ stale: cls.srcStale,
557
+ conflict: cls.srcConflict,
558
+ })[state] || '';
554
559
 
555
560
  export const ui = {
556
561
  button: ({ variant, icon, size } = {}) =>
@@ -583,6 +588,15 @@ export const ui = {
583
588
  tone === 'neg' && cls.numNeg,
584
589
  tone === 'muted' && cls.numMuted,
585
590
  ),
591
+ delta: ({ dir, invert } = {}) =>
592
+ j(
593
+ cls.delta,
594
+ dir === 'up' && cls.deltaUp,
595
+ dir === 'down' && cls.deltaDown,
596
+ dir === 'flat' && cls.deltaFlat,
597
+ invert && cls.deltaInvert,
598
+ ),
599
+ compare: ({ cols } = {}) => j(cls.compare, cols === 2 && cls.compare2up),
586
600
  chip: ({ accent } = {}) => j(cls.chip, accent && cls.chipAccent),
587
601
  link: ({ arrow, cta } = {}) => j(cls.link, arrow && cls.linkArrow, cta && cls.linkCta),
588
602
  dot: ({ tone, live } = {}) =>
@@ -634,6 +648,7 @@ export const ui = {
634
648
  tone === 'success' && cls.meterSuccess,
635
649
  tone === 'warning' && cls.meterWarning,
636
650
  tone === 'danger' && cls.meterDanger,
651
+ tone === 'info' && cls.meterInfo,
637
652
  ),
638
653
  dotspinner: ({ size } = {}) =>
639
654
  j(cls.dotspinner, size === 'sm' && cls.dotspinnerSm, size === 'lg' && cls.dotspinnerLg),
@@ -721,6 +736,7 @@ export const ui = {
721
736
  j(
722
737
  cls.bracketNote,
723
738
  tone === 'accent' && cls.bracketNoteAccent,
739
+ tone === 'success' && cls.bracketNoteSuccess,
724
740
  tone === 'warning' && cls.bracketNoteWarning,
725
741
  tone === 'danger' && cls.bracketNoteDanger,
726
742
  tone === 'info' && cls.bracketNoteInfo,
@@ -141,6 +141,14 @@
141
141
  "name": "--display",
142
142
  "description": "Global scale token. Value: `var(--dot-font)`"
143
143
  },
144
+ {
145
+ "name": "--display-weight",
146
+ "description": "Global scale token. Value: `700`"
147
+ },
148
+ {
149
+ "name": "--display-weight-strong",
150
+ "description": "Global scale token. Value: `800`"
151
+ },
144
152
  {
145
153
  "name": "--dot-font",
146
154
  "description": "Global scale token. Value: `'Doto', var(--mono)`"
@@ -213,6 +221,10 @@
213
221
  "name": "--mono",
214
222
  "description": "Global scale token. Value: `'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'SF Mono', ui-monospace, monospace`"
215
223
  },
224
+ {
225
+ "name": "--on-accent",
226
+ "description": "Theme token. Light: `var(--button-text)` · Dark: `var(--button-text)`"
227
+ },
216
228
  {
217
229
  "name": "--panel",
218
230
  "description": "Theme token. Light: `#ffffff` · Dark: `#1c1c1c`"
@@ -1,71 +1,191 @@
1
+ export function finite(name: any, value: any, fallback: any): any;
2
+ export function dimension(name: any, value: any, fallback: any): any;
3
+ export function fmt(value: any): string;
4
+ export function point(x: any, y: any): string;
5
+ export function clamp(value: any, min: any, max: any): any;
1
6
  /**
2
- * @ponchia/ui/connectors dependency-free SVG geometry for leader lines.
3
- * Pure functions: points/rects in, SVG path strings (or coordinates) out.
7
+ * A point on a rect's edge (or centre). `rect` is `{ x, y, width, height }`.
8
+ * @param {Rect} rect
9
+ * @param {Side} [side]
10
+ * @returns {Point}
4
11
  */
5
-
6
- export interface Point {
7
- x: number;
8
- y: number;
9
- }
10
-
11
- export interface Rect {
12
- x: number;
13
- y: number;
14
- width: number;
15
- height: number;
16
- }
17
-
18
- export type Side = 'top' | 'right' | 'bottom' | 'left' | 'center';
19
- export type ConnectorShape = 'straight' | 'elbow' | 'curve';
20
-
21
- export interface ConnectorPathOptions {
22
- from: Point;
23
- to: Point;
24
- shape?: ConnectorShape;
25
- /** Curve control-point reach along the dominant axis (curve shape). Default 0.5. */
26
- curvature?: number;
27
- /** Turn position 0..1 along the span (elbow shape). Default 0.5. */
28
- mid?: number;
29
- }
30
-
31
- export interface ConnectRectsOptions {
32
- fromRect: Rect;
33
- toRect: Rect;
34
- /** Anchor edges. Omit both to auto-pick facing edges from the rects. */
35
- fromSide?: Side;
36
- toSide?: Side;
37
- shape?: ConnectorShape;
38
- curvature?: number;
39
- mid?: number;
40
- }
41
-
42
- export interface ConnectRectsResult {
43
- /** SVG path data. */
44
- d: string;
45
- from: Point;
46
- to: Point;
47
- /**
48
- * The path's **end-tangent** at `to` in radians (`endTangentAngle(from, to,
49
- * shape)`) the direction the path arrives, so rotating an arrowhead at `to`
50
- * by this points it along the path. Equals the straight `from`→`to` angle for
51
- * `shape: 'straight'`; axis-aligned for `elbow`/`curve`.
52
- */
53
- angle: number;
54
- }
55
-
56
- export declare function anchorPoint(rect: Rect, side?: Side): Point;
57
- export declare function angleBetween(from: Point, to: Point): number;
58
- export declare function straightPath(from: Point, to: Point): string;
59
- export declare function elbowPath(from: Point, to: Point, opts?: { mid?: number }): string;
60
- export declare function curvePath(from: Point, to: Point, opts?: { curvature?: number }): string;
61
- export declare function connectorPath(opts: ConnectorPathOptions): string;
62
- export declare function arrowHead(p: Point, angle: number, size?: number): string;
63
- export declare function dotMark(p: Point, radius?: number): string;
64
- export declare function autoSides(
65
- fromRect: Rect,
66
- toRect: Rect,
67
- ): { from: Side; to: Side };
68
- /** Angle (radians) at which a `shape` path arrives at `to` — the chord for
69
- * `straight`, axis-aligned for `elbow`/`curve`. Use it to rotate an end marker. */
70
- export declare function endTangentAngle(from: Point, to: Point, shape?: ConnectorShape): number;
71
- export declare function connectRects(opts: ConnectRectsOptions): ConnectRectsResult;
12
+ export function anchorPoint(rect: Rect, side?: Side): Point;
13
+ /**
14
+ * Angle (radians) from `from` to `to`.
15
+ * @param {Point} from
16
+ * @param {Point} to
17
+ * @returns {number}
18
+ */
19
+ export function angleBetween(from: Point, to: Point): number;
20
+ /**
21
+ * Straight line from `from` to `to`.
22
+ * @param {Point} from
23
+ * @param {Point} to
24
+ * @returns {string}
25
+ */
26
+ export function straightPath(from: Point, to: Point): string;
27
+ /**
28
+ * Right-angle dogleg. Turns on the dominant axis at `mid` (0..1) of the span.
29
+ * @param {Point} from
30
+ * @param {Point} to
31
+ * @param {{ mid?: number }} [opts]
32
+ * @returns {string}
33
+ */
34
+ export function elbowPath(from: Point, to: Point, opts?: {
35
+ mid?: number;
36
+ }): string;
37
+ /**
38
+ * Cubic curve; control points extend along the dominant axis by `curvature`.
39
+ * @param {Point} from
40
+ * @param {Point} to
41
+ * @param {{ curvature?: number }} [opts]
42
+ * @returns {string}
43
+ */
44
+ export function curvePath(from: Point, to: Point, opts?: {
45
+ curvature?: number;
46
+ }): string;
47
+ /**
48
+ * Build a path between two points by `shape` (`straight` | `elbow` | `curve`).
49
+ * @param {ConnectorPathOptions} [opts]
50
+ * @returns {string}
51
+ */
52
+ export function connectorPath(opts?: ConnectorPathOptions): string;
53
+ /**
54
+ * A filled triangle arrowhead at `p`, pointing along `angle` (radians).
55
+ * @param {Point} p
56
+ * @param {number} angle
57
+ * @param {number} [size]
58
+ * @param {number} [spread] Half-angle of the head in radians (default 0.45).
59
+ * Smaller is crisper/sharper; must be in (0, π/2).
60
+ * @returns {string}
61
+ */
62
+ export function arrowHead(p: Point, angle: number, size?: number, spread?: number): string;
63
+ /**
64
+ * A filled dot at `p`.
65
+ * @param {Point} p
66
+ * @param {number} [radius]
67
+ * @returns {string}
68
+ */
69
+ export function dotMark(p: Point, radius?: number): string;
70
+ /**
71
+ * Pick facing edges from the rects' relative centres.
72
+ * @param {Rect} fromRect
73
+ * @param {Rect} toRect
74
+ * @returns {{ from: Side, to: Side }}
75
+ */
76
+ export function autoSides(fromRect: Rect, toRect: Rect): {
77
+ from: Side;
78
+ to: Side;
79
+ };
80
+ /**
81
+ * Angle (radians) at which a `shape` path *arrives* at `to` — straight is the
82
+ * chord; elbow/curve arrive axis-aligned along the dominant axis. Rotate an
83
+ * end marker by this so it points along the path, not the chord.
84
+ * @param {Point} from
85
+ * @param {Point} to
86
+ * @param {ConnectorShape} [shape]
87
+ * @returns {number}
88
+ */
89
+ export function endTangentAngle(from: Point, to: Point, shape?: ConnectorShape): number;
90
+ /**
91
+ * Connect two rects. Resolves anchor points (explicit `fromSide`/`toSide`, else
92
+ * auto), builds the path, and returns `{ d, from, to, angle }` so the caller can
93
+ * place an arrowhead/dot at `to` rotated by `angle`.
94
+ * @param {ConnectRectsOptions} [opts]
95
+ * @returns {ConnectRectsResult}
96
+ */
97
+ export function connectRects(opts?: ConnectRectsOptions): ConnectRectsResult;
98
+ /**
99
+ * @ponchia/ui/connectors — dependency-free SVG geometry for connecting two
100
+ * elements (or two points) with a leader line.
101
+ *
102
+ * Pure functions only: they take points/rects and return SVG path strings (or
103
+ * resolved coordinates). They own no DOM, no scales, and no live tracking —
104
+ * that optional glue lives in `@ponchia/ui/behaviors` (`initConnectors`). This
105
+ * is the page-coordinate, element-to-element cousin of the figure-coordinate
106
+ * `@ponchia/ui/annotations` helpers.
107
+ *
108
+ * import { connectRects } from '@ponchia/ui/connectors';
109
+ * const { d } = connectRects({ fromRect: a, toRect: b, shape: 'elbow' });
110
+ *
111
+ * The public types below are JSDoc `@typedef`s; the shipped `index.d.ts` is
112
+ * generated from them (and these signatures) by `tsc --emitDeclarationOnly`.
113
+ *
114
+ * @typedef {{ x: number, y: number }} Point
115
+ * @typedef {{ x: number, y: number, width: number, height: number }} Rect
116
+ * @typedef {'top' | 'right' | 'bottom' | 'left' | 'center'} Side
117
+ * @typedef {'straight' | 'elbow' | 'curve'} ConnectorShape
118
+ *
119
+ * @typedef {object} ConnectorPathOptions
120
+ * @property {Point} from
121
+ * @property {Point} to
122
+ * @property {ConnectorShape} [shape]
123
+ * @property {number} [curvature] Curve control-point reach along the dominant axis (curve shape). Default 0.5.
124
+ * @property {number} [mid] Turn position 0..1 along the span (elbow shape). Default 0.5.
125
+ *
126
+ * @typedef {object} ConnectRectsOptions
127
+ * @property {Rect} fromRect
128
+ * @property {Rect} toRect
129
+ * @property {Side} [fromSide] Anchor edges. Omit both to auto-pick facing edges from the rects.
130
+ * @property {Side} [toSide]
131
+ * @property {ConnectorShape} [shape]
132
+ * @property {number} [curvature]
133
+ * @property {number} [mid]
134
+ *
135
+ * @typedef {object} ConnectRectsResult
136
+ * @property {string} d SVG path data.
137
+ * @property {Point} from
138
+ * @property {Point} to
139
+ * @property {number} angle The path's end-tangent at `to` in radians — the direction the path arrives, so rotating an arrowhead at `to` by this points it along the path. Equals the straight `from`→`to` angle for `shape: 'straight'`; axis-aligned for `elbow`/`curve`.
140
+ */
141
+ export const PRECISION: 1000;
142
+ export type Point = {
143
+ x: number;
144
+ y: number;
145
+ };
146
+ export type Rect = {
147
+ x: number;
148
+ y: number;
149
+ width: number;
150
+ height: number;
151
+ };
152
+ export type Side = "top" | "right" | "bottom" | "left" | "center";
153
+ export type ConnectorShape = "straight" | "elbow" | "curve";
154
+ export type ConnectorPathOptions = {
155
+ from: Point;
156
+ to: Point;
157
+ shape?: ConnectorShape | undefined;
158
+ /**
159
+ * Curve control-point reach along the dominant axis (curve shape). Default 0.5.
160
+ */
161
+ curvature?: number | undefined;
162
+ /**
163
+ * Turn position 0..1 along the span (elbow shape). Default 0.5.
164
+ */
165
+ mid?: number | undefined;
166
+ };
167
+ export type ConnectRectsOptions = {
168
+ fromRect: Rect;
169
+ toRect: Rect;
170
+ /**
171
+ * Anchor edges. Omit both to auto-pick facing edges from the rects.
172
+ */
173
+ fromSide?: Side | undefined;
174
+ toSide?: Side | undefined;
175
+ shape?: ConnectorShape | undefined;
176
+ curvature?: number | undefined;
177
+ mid?: number | undefined;
178
+ };
179
+ export type ConnectRectsResult = {
180
+ /**
181
+ * SVG path data.
182
+ */
183
+ d: string;
184
+ from: Point;
185
+ to: Point;
186
+ /**
187
+ * The path's end-tangent at `to` in radians — the direction the path arrives, so rotating an arrowhead at `to` by this points it along the path. Equals the straight `from`→`to` angle for `shape: 'straight'`; axis-aligned for `elbow`/`curve`.
188
+ */
189
+ angle: number;
190
+ };
191
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":"AAkDA,kEAIC;AAED,qEAIC;AAED,wCAGC;AAED,8CAEC;AAID,2DAGC;AAED;;;;;GAKG;AACH,kCAJW,IAAI,SACJ,IAAI,GACF,KAAK,CAoBjB;AAED;;;;;GAKG;AACH,mCAJW,KAAK,MACL,KAAK,GACH,MAAM,CAOlB;AAED;;;;;GAKG;AACH,mCAJW,KAAK,MACL,KAAK,GACH,MAAM,CAOlB;AAED;;;;;;GAMG;AACH,gCALW,KAAK,MACL,KAAK,SACL;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACd,MAAM,CAgBlB;AAED;;;;;;GAMG;AACH,gCALW,KAAK,MACL,KAAK,SACL;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACpB,MAAM,CAclB;AAED;;;;GAIG;AACH,qCAHW,oBAAoB,GAClB,MAAM,CAOlB;AAED;;;;;;;;GAQG;AACH,6BAPW,KAAK,SACL,MAAM,SACN,MAAM,WACN,MAAM,GAEJ,MAAM,CAalB;AAED;;;;;GAKG;AACH,2BAJW,KAAK,WACL,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;GAKG;AACH,oCAJW,IAAI,UACJ,IAAI,GACF;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAE,CAWpC;AAED;;;;;;;;GAQG;AACH,sCALW,KAAK,MACL,KAAK,UACL,cAAc,GACZ,MAAM,CAQlB;AAED;;;;;;GAMG;AACH,oCAHW,mBAAmB,GACjB,kBAAkB,CAW9B;AAlRD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAMH,wBAAyB,IAAI,CAAC;oBAhCjB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE;mBACxB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;mBACvD,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ;6BAC9C,UAAU,GAAG,OAAO,GAAG,OAAO;;UAG7B,KAAK;QACL,KAAK;;;;;;;;;;;;cAML,IAAI;YACJ,IAAI;;;;;;;;;;;;;;OAQJ,MAAM;UACN,KAAK;QACL,KAAK;;;;WACL,MAAM"}