vexflow 5.2.0 → 5.4.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 (189) hide show
  1. package/README.md +2 -0
  2. package/build/cjs/vexflow-bravura.js +2 -2
  3. package/build/cjs/vexflow-bravura.js.map +1 -1
  4. package/build/cjs/vexflow-core.js +2 -2
  5. package/build/cjs/vexflow-core.js.map +1 -1
  6. package/build/cjs/vexflow-debug-with-tests.js +6502 -1708
  7. package/build/cjs/vexflow-debug-with-tests.js.map +1 -1
  8. package/build/cjs/vexflow-debug.js +5622 -1618
  9. package/build/cjs/vexflow-debug.js.map +1 -1
  10. package/build/cjs/vexflow.js +2 -2
  11. package/build/cjs/vexflow.js.map +1 -1
  12. package/build/esm/src/accidental.js +10 -3
  13. package/build/esm/src/alternatingtremolo.js +68 -0
  14. package/build/esm/src/annotation.js +19 -3
  15. package/build/esm/src/articulation.js +28 -6
  16. package/build/esm/src/beam.js +171 -28
  17. package/build/esm/src/bend.js +79 -23
  18. package/build/esm/src/clef.js +3 -0
  19. package/build/esm/src/continuouslayout.js +681 -0
  20. package/build/esm/src/continuousspan.js +159 -0
  21. package/build/esm/src/curve.js +48 -55
  22. package/build/esm/src/dot.js +13 -4
  23. package/build/esm/src/easyscore/composition.js +52 -2
  24. package/build/esm/src/easyscore/policies.js +39 -8
  25. package/build/esm/src/element.js +4 -0
  26. package/build/esm/src/engravinggeometry.js +157 -0
  27. package/build/esm/src/engravingprofile.js +44 -0
  28. package/build/esm/src/factory.js +31 -11
  29. package/build/esm/src/font.js +9 -1
  30. package/build/esm/src/formatter.js +9 -1
  31. package/build/esm/src/fretdiagram.js +77 -0
  32. package/build/esm/src/gracenote.js +43 -38
  33. package/build/esm/src/gracenotegroup.js +53 -56
  34. package/build/esm/src/guitargesture.js +33 -0
  35. package/build/esm/src/guitarmodifiers.js +26 -0
  36. package/build/esm/src/index.js +10 -0
  37. package/build/esm/src/instrumentprofile.js +123 -0
  38. package/build/esm/src/keysignature.js +24 -2
  39. package/build/esm/src/modifiercontext.js +11 -0
  40. package/build/esm/src/notationspelling.js +73 -0
  41. package/build/esm/src/note.js +3 -0
  42. package/build/esm/src/notehead.js +11 -6
  43. package/build/esm/src/ornament.js +43 -18
  44. package/build/esm/src/pagebreaks.js +58 -0
  45. package/build/esm/src/pedalmarking.js +39 -17
  46. package/build/esm/src/phraselayout.js +503 -0
  47. package/build/esm/src/phraseribbon.js +28 -0
  48. package/build/esm/src/proportionalformatter.js +54 -6
  49. package/build/esm/src/publication.js +402 -0
  50. package/build/esm/src/publicationview.js +114 -0
  51. package/build/esm/src/scorenavigation.js +172 -0
  52. package/build/esm/src/sheet.js +14 -2
  53. package/build/esm/src/stave.js +33 -16
  54. package/build/esm/src/stavebarline.js +5 -7
  55. package/build/esm/src/staveconnector.js +1 -0
  56. package/build/esm/src/stavehairpin.js +53 -27
  57. package/build/esm/src/stavenote.js +134 -116
  58. package/build/esm/src/stavetie.js +66 -9
  59. package/build/esm/src/stem.js +26 -11
  60. package/build/esm/src/strokes.js +4 -0
  61. package/build/esm/src/system.js +19 -4
  62. package/build/esm/src/systembreaks.js +42 -0
  63. package/build/esm/src/tabnote.js +6 -1
  64. package/build/esm/src/textbracket.js +24 -5
  65. package/build/esm/src/tickcontext.js +19 -0
  66. package/build/esm/src/timesignature.js +20 -6
  67. package/build/esm/src/tuplet.js +58 -17
  68. package/build/esm/src/version.js +3 -3
  69. package/build/esm/src/vexflow.js +20 -0
  70. package/build/esm/src/voice.js +7 -3
  71. package/build/esm/tests/bend_tests.js +14 -1
  72. package/build/esm/tests/curve_tests.js +14 -4
  73. package/build/esm/tests/demo_repertoire_tests.js +27 -0
  74. package/build/esm/tests/demos/drums.js +54 -0
  75. package/build/esm/tests/demos/electric.js +63 -0
  76. package/build/esm/tests/demos/greensleeves.js +90 -0
  77. package/build/esm/tests/demos/joy.js +61 -0
  78. package/build/esm/tests/demos/kesh.js +80 -0
  79. package/build/esm/tests/demos/prelude.js +59 -0
  80. package/build/esm/tests/demos/quartertones.js +50 -0
  81. package/build/esm/tests/demos/saints.js +65 -0
  82. package/build/esm/tests/engraving/continuous-studies.mjs +140 -0
  83. package/build/esm/tests/engraving/instrument-studies.mjs +273 -0
  84. package/build/esm/tests/engraving/phrase-studies.mjs +63 -0
  85. package/build/esm/tests/engraving/publication-studies.mjs +87 -0
  86. package/build/esm/tests/engraving/score-layout.mjs +75 -0
  87. package/build/esm/tests/engraving/score-persistence.mjs +262 -0
  88. package/build/esm/tests/engraving/specialist-studies.mjs +347 -0
  89. package/build/esm/tests/engraving/studies.mjs +367 -0
  90. package/build/esm/tests/formatter_tests.js +10 -1
  91. package/build/esm/tests/index.js +1 -0
  92. package/build/esm/tests/node/audit-dependencies-tests.mjs +42 -0
  93. package/build/esm/tests/node/continuous-score-tests.mjs +282 -0
  94. package/build/esm/tests/node/easyscore-tests.mjs +71 -0
  95. package/build/esm/tests/node/engraving-layout-tests.mjs +449 -0
  96. package/build/esm/tests/node/instrument-profile-tests.mjs +224 -0
  97. package/build/esm/tests/node/local-engraving-tests.mjs +128 -0
  98. package/build/esm/tests/node/phrase-layout-tests.mjs +281 -0
  99. package/build/esm/tests/node/proportional-spacing-tests.mjs +64 -0
  100. package/build/esm/tests/node/publication-tests.mjs +219 -0
  101. package/build/esm/tests/node/rendering-tests.mjs +6 -2
  102. package/build/esm/tests/threevoice_tests.js +11 -1
  103. package/build/esm/tests/vexflow_test_helpers.js +19 -10
  104. package/build/esm/tools/audit-dependencies.mjs +61 -0
  105. package/build/esm/tools/easyscore-structure.mjs +1 -1
  106. package/build/esm/tools/explorer/catalog/entries.mjs +2 -1
  107. package/build/esm/tools/explorer/catalog/expression.mjs +14 -9
  108. package/build/esm/tools/explorer/catalog/guitar.mjs +238 -0
  109. package/build/esm/tools/explorer/catalog/layout.mjs +8 -6
  110. package/build/esm/tools/explorer/catalog/notes.mjs +16 -14
  111. package/build/esm/tools/explorer/catalog/staves.mjs +12 -6
  112. package/build/esm/tools/explorer/catalog/strings.mjs +10 -7
  113. package/build/esm/tools/score-fixtures.mjs +23 -6
  114. package/build/types/src/accidental.d.ts +4 -0
  115. package/build/types/src/alternatingtremolo.d.ts +13 -0
  116. package/build/types/src/annotation.d.ts +9 -0
  117. package/build/types/src/articulation.d.ts +9 -1
  118. package/build/types/src/beam.d.ts +16 -0
  119. package/build/types/src/bend.d.ts +8 -0
  120. package/build/types/src/clef.d.ts +3 -0
  121. package/build/types/src/continuouslayout.d.ts +103 -0
  122. package/build/types/src/continuousspan.d.ts +60 -0
  123. package/build/types/src/curve.d.ts +20 -0
  124. package/build/types/src/dot.d.ts +5 -0
  125. package/build/types/src/easyscore/composition.d.ts +27 -0
  126. package/build/types/src/easyscore/policies.d.ts +1 -1
  127. package/build/types/src/element.d.ts +2 -0
  128. package/build/types/src/engravinggeometry.d.ts +31 -0
  129. package/build/types/src/engravingprofile.d.ts +20 -0
  130. package/build/types/src/factory.d.ts +6 -1
  131. package/build/types/src/formatter.d.ts +3 -3
  132. package/build/types/src/fretdiagram.d.ts +23 -0
  133. package/build/types/src/gracenote.d.ts +7 -0
  134. package/build/types/src/gracenotegroup.d.ts +7 -2
  135. package/build/types/src/guitargesture.d.ts +26 -0
  136. package/build/types/src/guitarmodifiers.d.ts +3 -0
  137. package/build/types/src/index.d.ts +12 -0
  138. package/build/types/src/instrumentprofile.d.ts +124 -0
  139. package/build/types/src/keysignature.d.ts +9 -0
  140. package/build/types/src/modifiercontext.d.ts +4 -0
  141. package/build/types/src/notationspelling.d.ts +25 -0
  142. package/build/types/src/note.d.ts +15 -0
  143. package/build/types/src/notehead.d.ts +5 -0
  144. package/build/types/src/ornament.d.ts +10 -1
  145. package/build/types/src/pagebreaks.d.ts +26 -0
  146. package/build/types/src/pedalmarking.d.ts +9 -0
  147. package/build/types/src/phraselayout.d.ts +87 -0
  148. package/build/types/src/phraseribbon.d.ts +7 -0
  149. package/build/types/src/proportionalformatter.d.ts +11 -2
  150. package/build/types/src/publication.d.ts +61 -0
  151. package/build/types/src/publicationview.d.ts +27 -0
  152. package/build/types/src/scorenavigation.d.ts +33 -0
  153. package/build/types/src/sheet.d.ts +5 -0
  154. package/build/types/src/stave.d.ts +13 -0
  155. package/build/types/src/stavehairpin.d.ts +18 -0
  156. package/build/types/src/stavenote.d.ts +20 -2
  157. package/build/types/src/stavetie.d.ts +9 -0
  158. package/build/types/src/stem.d.ts +10 -1
  159. package/build/types/src/system.d.ts +8 -1
  160. package/build/types/src/systembreaks.d.ts +9 -0
  161. package/build/types/src/textbracket.d.ts +7 -0
  162. package/build/types/src/tickcontext.d.ts +5 -0
  163. package/build/types/src/timesignature.d.ts +6 -0
  164. package/build/types/src/tuplet.d.ts +5 -48
  165. package/build/types/src/vexflow.d.ts +20 -0
  166. package/build/types/src/voice.d.ts +2 -0
  167. package/changelog/CHANGELOG.md +25 -0
  168. package/package.json +15 -3
  169. package/tests/all.html +277 -0
  170. package/tests/demo_petzold_tests.ts +435 -0
  171. package/tests/demos/drums.ts +55 -0
  172. package/tests/demos/drums.webp +0 -0
  173. package/tests/demos/electric.ts +70 -0
  174. package/tests/demos/electric.webp +0 -0
  175. package/tests/demos/greensleeves.ts +97 -0
  176. package/tests/demos/greensleeves.webp +0 -0
  177. package/tests/demos/joy.ts +65 -0
  178. package/tests/demos/joy.webp +0 -0
  179. package/tests/demos/kesh.ts +86 -0
  180. package/tests/demos/kesh.webp +0 -0
  181. package/tests/demos/prelude.ts +65 -0
  182. package/tests/demos/prelude.webp +0 -0
  183. package/tests/demos/quartertones.ts +51 -0
  184. package/tests/demos/quartertones.webp +0 -0
  185. package/tests/demos/saints.ts +70 -0
  186. package/tests/demos/saints.webp +0 -0
  187. package/tests/flow.html +550 -239
  188. package/tests/fonts.css +493 -0
  189. package/tests/minuet.webp +0 -0
@@ -1,3 +1,4 @@
1
+ import { BoundingBox } from './boundingbox';
1
2
  import { Element } from './element';
2
3
  import { Fraction } from './fraction';
3
4
  import { RenderContext } from './rendercontext';
@@ -18,6 +19,8 @@ export declare class Beam extends Element {
18
19
  beamWidth: number;
19
20
  maxSlope: number;
20
21
  minSlope: number;
22
+ /** Keep automatic slope in the endpoint contour and align level in-staff beams to a half-space. */
23
+ contourSlope?: boolean;
21
24
  slopeIterations: number;
22
25
  slopeCost: number;
23
26
  stemletExtension: number;
@@ -30,6 +33,9 @@ export declare class Beam extends Element {
30
33
  private readonly _stemDirection;
31
34
  private readonly _ticks;
32
35
  protected yShift: number;
36
+ /** Derived extensions must be removed before formatting the next width. */
37
+ private fittedStems;
38
+ private flatOffset?;
33
39
  private breakOnIndexes;
34
40
  private _beamCount;
35
41
  private unbeamable?;
@@ -128,6 +134,8 @@ export declare class Beam extends Element {
128
134
  getSlopeY(x: number, firstX: number, firstY: number, slope: number): number;
129
135
  /** Calculate the best possible slope for the provided notes. */
130
136
  calculateSlope(): void;
137
+ /** Shorten stems together when a beam cuts through an outer voice at or between attacks. */
138
+ private clearOtherVoiceHeads;
131
139
  /** Calculate a slope and y-shift for flat beams. */
132
140
  calculateFlatSlope(): void;
133
141
  /** Return the Beam y offset. */
@@ -146,7 +154,15 @@ export declare class Beam extends Element {
146
154
  }[];
147
155
  /** Render the stems for each note. */
148
156
  protected drawStems(ctx: RenderContext): void;
157
+ /** Each filled strip has two sloping edges separated by a signed thickness. */
158
+ private getStrips;
159
+ /** Conservative local obstacles for sloping strips. Stems remain owned by the notes. */
160
+ getStripBounds(): BoundingBox[];
161
+ /** Bounds of the beam strips alone. The note geometry owns the stem segments. */
162
+ getBoundingBox(): BoundingBox;
149
163
  protected drawBeamLines(ctx: RenderContext): void;
164
+ /** Release only the adjustments from the last fit. Preserve intervening native edits. */
165
+ resetLayout(): void;
150
166
  /** Pre-format the beam. */
151
167
  preFormat(): this;
152
168
  /**
@@ -1,4 +1,5 @@
1
1
  import { ElementStyle } from './element';
2
+ import { TimedStringBend } from './guitargesture';
2
3
  import { Modifier } from './modifier';
3
4
  import { ModifierContextState } from './modifiercontext';
4
5
  export interface BendPhrase {
@@ -11,9 +12,16 @@ export interface BendPhrase {
11
12
  /** Bend implements tablature bends. */
12
13
  export declare class Bend extends Modifier {
13
14
  static get CATEGORY(): string;
15
+ /** A vertical attack into an already raised pitch. */
16
+ static readonly PREBEND = 2;
17
+ /** Continue at the raised pitch before a release. */
18
+ static readonly HOLD = 3;
14
19
  static get UP(): number;
15
20
  static get DOWN(): number;
16
21
  static format(bends: Bend[], state: ModifierContextState): boolean;
22
+ private timing?;
23
+ /** Construct a single rise with optional hold and release. Phase ends are fractions of the host attack. */
24
+ static timed(spec: TimedStringBend): Bend;
17
25
  protected tap: string;
18
26
  protected phrase: BendPhrase[];
19
27
  protected styleLine: ElementStyle;
@@ -1,3 +1,4 @@
1
+ import { BoundingBox } from './boundingbox';
1
2
  import { Stave } from './stave';
2
3
  import { StaveModifier } from './stavemodifier';
3
4
  /**
@@ -35,6 +36,8 @@ export declare class Clef extends StaveModifier {
35
36
  static getPoint(size?: string): number;
36
37
  /** Set associated stave. */
37
38
  setStave(stave: Stave): this;
39
+ /** Positioned glyph ink, including an octave annotation if present. */
40
+ getInkBounds(): BoundingBox;
38
41
  /** Render clef. */
39
42
  draw(): void;
40
43
  }
@@ -0,0 +1,103 @@
1
+ import { Accidental } from './accidental';
2
+ import { ContinuousSpan, SpanFragment } from './continuousspan';
3
+ import type { EasyScoreComposition, EasyScoreCompositionSpec, EasyScoreStaffState } from './easyscore/composition';
4
+ import { Element } from './element';
5
+ import { RenderContext } from './rendercontext';
6
+ import type { SheetOptions, SheetRow } from './sheet';
7
+ export interface ContinuousBoundary {
8
+ /** One-based source measure number, independent of rest compression. */
9
+ measure: number;
10
+ breakBefore?: 'force' | 'keep';
11
+ rehearsal?: string;
12
+ navigation?: {
13
+ kind: 'segno' | 'coda';
14
+ id: string;
15
+ } | {
16
+ kind: 'dalSegno' | 'toCoda';
17
+ target: string;
18
+ } | {
19
+ kind: 'daCapo' | 'fine';
20
+ };
21
+ repeatStart?: boolean;
22
+ repeatEnd?: boolean;
23
+ keepRest?: boolean;
24
+ }
25
+ export interface ContinuousOptions {
26
+ mode?: 'balanced' | 'greedy';
27
+ boundaries?: readonly ContinuousBoundary[];
28
+ spans?: readonly ContinuousSpan[];
29
+ hideEmptyStaves?: boolean;
30
+ compressRests?: boolean;
31
+ measureNumbers?: boolean;
32
+ courtesy?: boolean;
33
+ /** Unflagged heads on different staves sharing an onset, duration and stem direction. */
34
+ splitChords?: readonly {
35
+ id: string;
36
+ upper: string;
37
+ lower: string;
38
+ }[];
39
+ groups?: readonly {
40
+ first: string;
41
+ last: string;
42
+ type: 'brace' | 'bracket';
43
+ barlines?: boolean;
44
+ }[];
45
+ }
46
+ export interface ContinuousRow extends SheetRow {
47
+ measures: number[];
48
+ visibleStaves: string[];
49
+ restGroups: number[][];
50
+ }
51
+ type State = Required<EasyScoreStaffState>;
52
+ /** A row has one shared staff map. A compressed rest maps back to every original measure. */
53
+ export declare class ContinuousLayout {
54
+ private readonly score;
55
+ private readonly spec;
56
+ readonly hidden: Set<Element>;
57
+ readonly diagnostics: {
58
+ code: 'RowOverflow' | 'CurveCollision' | 'SplitStemAlignment' | 'SpanOverflow' | 'StaffSpacingLimit';
59
+ measures: number[];
60
+ source?: string;
61
+ }[];
62
+ readonly fragments: SpanFragment[];
63
+ readonly rows: ContinuousRow[];
64
+ private readonly marks;
65
+ private readonly boundaries;
66
+ private readonly spans;
67
+ private readonly names;
68
+ private readonly groups;
69
+ private drawing;
70
+ private readonly headerLabels;
71
+ /** Reuse measured labels when a resize moves a measure to another row. */
72
+ private headerLabel;
73
+ private headerParts;
74
+ private readonly splitChords;
75
+ private readonly spelledSpans;
76
+ private readonly options;
77
+ private readonly arrivals;
78
+ constructor(score: EasyScoreComposition, spec: EasyScoreCompositionSpec, starts: State[][], ends: State[][], placed?: Set<Accidental>);
79
+ /** Only undecorated, wholly resting measures can disappear into a numbered rest. */
80
+ private plainRest;
81
+ /** Add cached signs for the candidate boundaries and reserve actual end-modifier width. */
82
+ private boundaryWidth;
83
+ private units;
84
+ private endWidth;
85
+ private install;
86
+ private indent;
87
+ /** Preserve staves carrying a spanning instruction or cross-staff note, including silent middle rows. */
88
+ private visible;
89
+ private suppress;
90
+ format(options: Required<SheetOptions>): ContinuousRow[];
91
+ /** Measure native ink once the horizontal positions and beam fits for this row are known. */
92
+ private measureStaffInk;
93
+ /** Share the largest required staff distance across all measures, bounded to four native refits. */
94
+ private alignStaves;
95
+ /** Reconcile staff envelopes across all measures in a row, then translate the entire solved row once. */
96
+ private layoutRow;
97
+ /** Keep continuation hooks and labels on the correct end when a span crosses a row. */
98
+ private addFragment;
99
+ /** Add labels, connectors and numbered rests after all native positions have settled. */
100
+ private decorate;
101
+ draw(context: RenderContext): void;
102
+ }
103
+ export {};
@@ -0,0 +1,60 @@
1
+ import { Bounds } from './boundingbox';
2
+ import { Element } from './element';
3
+ import { Note } from './note';
4
+ import { RenderContext } from './rendercontext';
5
+ import { Stave } from './stave';
6
+ export type ContinuousSpanKind = 'tie' | 'slur' | 'crescendo' | 'diminuendo' | 'pedal' | 'lyric' | 'hyphen' | 'volta' | 'ottava' | 'trill' | 'tuplet' | 'palmMute';
7
+ export interface ContinuousSpan {
8
+ kind: ContinuousSpanKind;
9
+ /** Required for palmMute. String numbers are one-based. */
10
+ strings?: readonly number[];
11
+ id: string;
12
+ from: string;
13
+ to: string;
14
+ /** Optional chord-head indices for each end of a tie or slur. */
15
+ fromHead?: number;
16
+ toHead?: number;
17
+ side?: 'above' | 'below';
18
+ /** Syllable, ending number, tuplet ratio or octave label, according to kind. */
19
+ text?: string;
20
+ }
21
+ export interface SpanAnchor {
22
+ measure: number;
23
+ staff: number;
24
+ note: Note;
25
+ }
26
+ export interface ResolvedSpan {
27
+ spec: ContinuousSpan;
28
+ first: SpanAnchor;
29
+ last: SpanAnchor;
30
+ label?: Element;
31
+ }
32
+ export interface SpanFragment {
33
+ id: string;
34
+ kind: ContinuousSpanKind;
35
+ row: number;
36
+ part: 'single' | 'first' | 'middle' | 'last';
37
+ x1: number;
38
+ x2: number;
39
+ y1: number;
40
+ y2: number;
41
+ /** Fraction of the drawn span used to interpolate the aperture across a system break. */
42
+ progress: [number, number];
43
+ /** String numbers covered by a palm-mute fragment. */
44
+ strings?: readonly number[];
45
+ /** Authored TAB endpoints appear on the fragments containing them. */
46
+ from?: string;
47
+ to?: string;
48
+ rise?: number;
49
+ above: boolean;
50
+ space: number;
51
+ }
52
+ /** Unlike a glyph sized in a default font, labels contribute their actual current text width to reservations. */
53
+ export declare function spanLabel(spec: ContinuousSpan): Element | undefined;
54
+ export declare function spanAbove(span: ContinuousSpan): boolean;
55
+ /** Retain the written pitch through a clef change at a continuation edge. */
56
+ export declare function continuationPitch(anchor: SpanAnchor, stave: Stave, index?: number): number;
57
+ /** Prefer the shallowest clear curve. Preserve the best finite candidate if the space is infeasible. */
58
+ export declare function fitSpan(f: SpanFragment, obstacles: Bounds[]): boolean;
59
+ /** Draw only the hooks, labels and wedge apertures belonging to this particular segment. */
60
+ export declare function drawSpan(ctx: RenderContext, f: SpanFragment, label?: Element): void;
@@ -15,6 +15,10 @@ export interface CurveOptions {
15
15
  invert?: boolean;
16
16
  openingDirection?: 'up' | 'down' | 'auto';
17
17
  }
18
+ type Point = {
19
+ x: number;
20
+ y: number;
21
+ };
18
22
  interface CurveRenderParams {
19
23
  firstX: number;
20
24
  firstY: number;
@@ -34,6 +38,17 @@ export declare class Curve extends Element {
34
38
  static get Position(): typeof CurvePosition;
35
39
  static get PositionString(): Record<string, number>;
36
40
  constructor(from: Note | undefined, to: Note | undefined, options: CurveOptions);
41
+ private layoutRise;
42
+ private readonly authoredControls;
43
+ /** Automatic routing changes only the derived lift, preserving the authored control points. */
44
+ setLayoutRise(rise: number): void;
45
+ hasManualControls(): boolean;
46
+ getNotes(): {
47
+ firstNote?: Note;
48
+ lastNote?: Note;
49
+ };
50
+ /** Subdivided ink of the actual rendered cubic. */
51
+ getRouteParts(): BoundingBox[];
37
52
  setNotes(from: Note | undefined, to: Note | undefined): this;
38
53
  /**
39
54
  * @return {boolean} Returns true if this is a partial bar.
@@ -54,6 +69,11 @@ export declare class Curve extends Element {
54
69
  * The box is exact: it is fitted to the extrema of the bezier curves, not to their control points.
55
70
  */
56
71
  getBoundingBox(): BoundingBox;
72
+ /** Endpoints on the rendered curve after authored shifts. */
73
+ getAnchors(): {
74
+ start: Point;
75
+ end: Point;
76
+ };
57
77
  draw(): boolean;
58
78
  }
59
79
  export {};
@@ -14,6 +14,11 @@ export declare class Dot extends Modifier {
14
14
  static format(dots: Dot[], state: ModifierContextState): boolean;
15
15
  constructor();
16
16
  setNote(note: Note): this;
17
+ private restShiftY;
17
18
  setDotShiftY(y: number): this;
19
+ /** Place the glyph using the same coordinates for measurement and drawing. */
20
+ private positionGlyph;
21
+ /** Visible glyph after formatting, including cautionary or authored shifts. */
22
+ getInkBounds(): import("./boundingbox").BoundingBox;
18
23
  draw(): void;
19
24
  }
@@ -1,6 +1,8 @@
1
+ import { ContinuousOptions } from '../continuouslayout';
1
2
  import type { EasyScore, EasyScoreVoiceOptions } from '../easyscore';
2
3
  import type { Element } from '../element';
3
4
  import { Factory } from '../factory';
5
+ import { GraceNoteStruct } from '../gracenote';
4
6
  import { Note } from '../note';
5
7
  import { Sheet, SheetOptions } from '../sheet';
6
8
  import { Stave, StaveOptions } from '../stave';
@@ -17,11 +19,26 @@ export interface EasyScoreStaffState {
17
19
  key?: string;
18
20
  time?: string;
19
21
  }
22
+ /** Explicit signs survive key-aware generation, including cautionaries and microtones. */
23
+ interface GracePitchSpec extends GraceNoteStruct {
24
+ accidentals?: readonly {
25
+ index: number;
26
+ type: string;
27
+ cautionary?: boolean;
28
+ }[];
29
+ }
30
+ interface GraceGroupSpec {
31
+ side: 'before' | 'after';
32
+ notes: readonly GracePitchSpec[];
33
+ slur?: boolean;
34
+ beam?: boolean;
35
+ }
20
36
  /** Typed wrappers add IDs and cross-staff assignment without changing native note fields. */
21
37
  export type EasyScoreContent = string | StaveNoteStruct | Tickable | {
22
38
  note: StaveNoteStruct;
23
39
  id?: string;
24
40
  stave?: string;
41
+ grace?: GraceGroupSpec;
25
42
  } | {
26
43
  tab: TabNoteStruct;
27
44
  id?: string;
@@ -44,12 +61,18 @@ export interface EasyScoreVoiceSpec {
44
61
  }
45
62
  /** span is the actual duration of a pickup; time remains its displayed meter. */
46
63
  export interface EasyScoreMeasureSpec extends EasyScoreStaffState {
64
+ instrument?: {
65
+ name: string;
66
+ shortName?: string;
67
+ };
47
68
  voices: readonly EasyScoreVoiceSpec[];
48
69
  span?: VoiceTime | string;
49
70
  }
50
71
  /** Staves have aligned measure arrays. Missing or uneven measures are errors. */
51
72
  export interface EasyScoreStaveSpec extends EasyScoreStaffState {
52
73
  id: string;
74
+ name?: string;
75
+ shortName?: string;
53
76
  kind?: 'stave' | 'tab';
54
77
  options?: StaveOptions;
55
78
  spaceAbove?: number;
@@ -79,9 +102,12 @@ export type EasyScoreSpanSpec = {
79
102
  /** Layout policies are explicit. Sheet does not split spans or repeat signatures at row starts. */
80
103
  export interface EasyScoreCompositionSpec {
81
104
  staves: readonly EasyScoreStaveSpec[];
105
+ continuous?: ContinuousOptions;
82
106
  sheet?: Omit<SheetOptions, 'factory'>;
83
107
  system?: Omit<SystemOptions, 'factory' | 'width' | 'autoWidth' | 'noJustification'>;
84
108
  accidentals?: 'literal' | 'key-aware';
109
+ /** Include written grace pitches in key-aware state at their host onset. */
110
+ graceAccidentals?: 'explicit' | 'ordered';
85
111
  signatures?: 'changes' | 'every-measure';
86
112
  spans?: readonly EasyScoreSpanSpec[];
87
113
  crossMeasureSpans?: 'reject' | 'manual';
@@ -105,3 +131,4 @@ export interface EasyScoreComposition {
105
131
  }
106
132
  /** Compose aligned measure arrays atomically. Formatting and drawing remain explicit native operations. */
107
133
  export declare function compose(score: EasyScore, spec: EasyScoreCompositionSpec): EasyScoreComposition;
134
+ export {};
@@ -9,4 +9,4 @@ export interface KeyChange {
9
9
  key: string;
10
10
  }
11
11
  /** Each onset is evaluated against one prior state, so voice ordering cannot change accidental output. */
12
- export declare function applyCompositionAccidentals(score: EasyScore, voices: Voice[], key: string, changes: KeyChange[], generated: Set<Accidental>, stave: Stave): void;
12
+ export declare function applyCompositionAccidentals(score: EasyScore, voices: Voice[], key: string, changes: KeyChange[], generated: Set<Accidental>, stave: Stave, includeGrace?: boolean, placed?: Set<Accidental>): void;
@@ -167,6 +167,8 @@ export declare class Element {
167
167
  onIdChange(validate: (id: string | undefined) => void, changed: () => void): () => void;
168
168
  /** Set an attribute such as 'id', 'class', or 'type'. */
169
169
  setAttribute(name: string, value: string | undefined): this;
170
+ /** Visible text in renderer pixels at a supplied glyph origin. Positive y points down. */
171
+ getTextInk(x: number, y: number): BoundingBox;
170
172
  /** Get the boundingBox. */
171
173
  getBoundingBox(): BoundingBox;
172
174
  /** Return the context, such as an SVGContext or CanvasContext object. */
@@ -0,0 +1,31 @@
1
+ import { BoundingBox, Bounds } from './boundingbox';
2
+ import { Element } from './element';
3
+ /** Enclosing rectangles can be conservative for strokes and curves. */
4
+ export interface EngravingShape {
5
+ parts: Bounds[];
6
+ anchors: Record<string, {
7
+ x: number;
8
+ y: number;
9
+ }>;
10
+ }
11
+ /** Codes are stable. Source IDs come from the native element or its author. */
12
+ export interface GeometryDiagnostic {
13
+ code: 'UnsupportedGeometry' | 'UnformattedGeometry' | 'InvalidGeometry' | 'LayoutOverflow';
14
+ phase: 'measure';
15
+ severity: 'error' | 'warning';
16
+ sourceId: string;
17
+ }
18
+ /** Return undefined from an extension adapter to delegate to the built-in participants. */
19
+ export interface GeometryOptions {
20
+ extension?: (element: Element) => EngravingShape | undefined;
21
+ paddingPx?: number;
22
+ viewport?: Bounds;
23
+ }
24
+ /** Union and layout bounds are absent for empty or invalid geometry. Check diagnostics for partial results. */
25
+ export interface EngravingGeometry extends EngravingShape {
26
+ ink?: BoundingBox;
27
+ layout?: BoundingBox;
28
+ diagnostics: GeometryDiagnostic[];
29
+ }
30
+ /** Measure after formatting and assigning staves. Never calls draw or touches a renderer. */
31
+ export declare function measureEngraving(element: Element, options?: GeometryOptions): EngravingGeometry;
@@ -0,0 +1,20 @@
1
+ /** Metadata may be passed directly from an installed font. All distances are in staff spaces. */
2
+ export interface EngravingProfileOptions {
3
+ musicFont: string;
4
+ metadata?: unknown;
5
+ beamThickness?: number;
6
+ clearance?: number;
7
+ }
8
+ /** Coordinates in a SMuFL font, where positive y points up. */
9
+ type Anchor = readonly [number, number];
10
+ /** Holds a validated copy of the supported metadata. Never changes global Metrics or fonts. */
11
+ export declare class EngravingProfile {
12
+ readonly musicFont: string;
13
+ readonly beamThickness: number;
14
+ readonly clearance: number;
15
+ private readonly anchors;
16
+ constructor(options: EngravingProfileOptions);
17
+ /** Missing or malformed anchors delegate to VF5's native glyph fallback. */
18
+ stemAnchor(glyph: string, direction: 'up' | 'down'): Anchor | undefined;
19
+ }
20
+ export {};
@@ -12,6 +12,7 @@ import { Curve, CurveOptions } from './curve';
12
12
  import { Dot } from './dot';
13
13
  import { EasyScore, EasyScoreOptions } from './easyscore';
14
14
  import { Element } from './element';
15
+ import { EngravingProfile } from './engravingprofile';
15
16
  import { FontInfo } from './font';
16
17
  import { Formatter, FormatterOptions } from './formatter';
17
18
  import { FretHandFinger } from './frethandfinger';
@@ -67,6 +68,8 @@ import { Voice, VoiceTime } from './voice';
67
68
  /** Explicit drawing role for a native extension adopted into a Factory. */
68
69
  export type FactoryElementRole = 'note' | 'modifier' | 'staveModifier' | 'drawable';
69
70
  export interface FactoryOptions {
71
+ /** Optional per-score pitched notation and beam policy. */
72
+ engraving?: EngravingProfile;
70
73
  stave?: {
71
74
  space: number;
72
75
  };
@@ -94,7 +97,7 @@ export declare class Factory {
94
97
  * `const vf: Factory = VexFlow.Factory.newFromElementId('boo', 1200, 600 );`
95
98
  */
96
99
  static newFromElementId(elementId: string | null, width?: number, height?: number): Factory;
97
- protected options: Required<FactoryOptions>;
100
+ protected options: Required<Omit<FactoryOptions, 'engraving'>> & Pick<FactoryOptions, 'engraving'>;
98
101
  protected stave?: Stave;
99
102
  protected context: RenderContext;
100
103
  protected staves: Stave[];
@@ -163,6 +166,8 @@ export declare class Factory {
163
166
  }): TabStave;
164
167
  /** Construct a native Bend with an explicit drawing role. */
165
168
  Bend(...args: ConstructorParameters<typeof Bend>): Bend;
169
+ /** Apply a score's music family to glyph elements while retaining their individual sizes. */
170
+ private musicGlyph;
166
171
  /** Construct a native Clef with an explicit drawing role. */
167
172
  Clef(...args: ConstructorParameters<typeof Clef>): Clef;
168
173
  /** Construct a native KeySignature with an explicit drawing role. */
@@ -1,6 +1,6 @@
1
1
  import { BoundingBox } from './boundingbox';
2
2
  import { ModifierContext } from './modifiercontext';
3
- import { ProportionalSpacing } from './proportionalformatter';
3
+ import { MeasuredSpacing } from './proportionalformatter';
4
4
  import { RenderContext } from './rendercontext';
5
5
  import { Stave } from './stave';
6
6
  import { StemmableNote } from './stemmablenote';
@@ -9,10 +9,10 @@ import { TabStave } from './tabstave';
9
9
  import { Tickable } from './tickable';
10
10
  import { TickContext } from './tickcontext';
11
11
  import { Voice } from './voice';
12
- export type { ProportionalSpacing } from './proportionalformatter';
12
+ export type { MeasuredSpacing, ProportionalSpacing } from './proportionalformatter';
13
13
  export interface FormatterOptions {
14
14
  /** Omit to use the default engraving layout. */
15
- spacing?: ProportionalSpacing;
15
+ spacing?: MeasuredSpacing;
16
16
  /** Defaults to Tables.SOFTMAX_FACTOR. */
17
17
  softmaxFactor?: number;
18
18
  /** Defaults to `false`. */
@@ -0,0 +1,23 @@
1
+ import { BoundingBox } from './boundingbox';
2
+ import { Element } from './element';
3
+ /** Frets are absolute; 0 = open, 'x' = muted. A barre names one-based string numbers. */
4
+ export interface FretDiagramSpec {
5
+ frets: readonly (number | 'x')[];
6
+ firstFret?: number;
7
+ rows?: number;
8
+ barre?: {
9
+ fret: number;
10
+ from: number;
11
+ to: number;
12
+ };
13
+ }
14
+ export declare class FretDiagram extends Element {
15
+ private readonly frets;
16
+ private readonly first;
17
+ private readonly rows;
18
+ private readonly barre?;
19
+ constructor(spec: FretDiagramSpec);
20
+ /** The top-left position includes the open-string marks and starting fret label. */
21
+ getBoundingBox(): BoundingBox;
22
+ draw(): void;
23
+ }
@@ -9,6 +9,13 @@ export declare class GraceNote extends StaveNote {
9
9
  protected slur: boolean;
10
10
  constructor(noteStruct: GraceNoteStruct);
11
11
  getStemExtension(): number;
12
+ /** Absolute endpoints of the grace slash used by both measurement and drawing. */
13
+ getSlash(): {
14
+ x1: number;
15
+ y1: number;
16
+ x2: number;
17
+ y2: number;
18
+ } | undefined;
12
19
  draw(): void;
13
20
  calcBeamedNotesSlashBBox(slashStemOffset: number, slashBeamOffset: number, protrusions: {
14
21
  beam: number;
@@ -22,8 +22,11 @@ export declare class GraceNoteGroup extends Modifier {
22
22
  };
23
23
  protected slur?: StaveTie | TabTie;
24
24
  protected beams: Beam[];
25
- /** Arranges groups inside a `ModifierContext`. */
26
- static format(gracenoteGroups: GraceNoteGroup[], state: ModifierContextState): boolean;
25
+ /** Right-side material at the same onset must not move a before-grace cluster to the left. */
26
+ private afterWidth;
27
+ private afterOffset;
28
+ /** Opposing groups reserve their own side. Voices with simultaneous before-graces align at the host. */
29
+ static format(groups: GraceNoteGroup[], state: ModifierContextState): boolean;
27
30
  constructor(graceNotes: StemmableNote[], showSlur?: boolean);
28
31
  preFormat(): void;
29
32
  beamNotes(graceNotes?: StemmableNote[]): this;
@@ -34,5 +37,7 @@ export declare class GraceNoteGroup extends Modifier {
34
37
  private positionGraceNotes;
35
38
  /** Enclose the positioned grace notes (not the slur). Drawing is not required. */
36
39
  getBoundingBox(): BoundingBox;
40
+ /** Positioned components, including the optional slur, shared with geometry consumers. */
41
+ getLayoutElements(): (Note | Beam | StaveTie)[];
37
42
  draw(): void;
38
43
  }
@@ -0,0 +1,26 @@
1
+ import type { NotationIdentity } from './note';
2
+ /** One right-hand action. Direction follows the physical order of strings for either arrow convention. */
3
+ export interface GuitarStroke {
4
+ finger: 'p' | 'i' | 'm' | 'a' | 'e';
5
+ direction: 'bass-to-treble' | 'treble-to-bass';
6
+ golpe?: boolean;
7
+ /** One freely rolled chord occupies its written value. Individual finger attacks are unspecified. */
8
+ roll?: boolean;
9
+ arrows?: 'strings' | 'hand';
10
+ }
11
+ /** Endpoints are exact fractions of this attack's duration, measured from its onset. */
12
+ export interface TimedStringBend {
13
+ string: number;
14
+ semitones: number;
15
+ rise: readonly [number, number];
16
+ hold?: readonly [number, number];
17
+ release?: readonly [number, number];
18
+ /** Optional written amount, e.g. “½”. Defaults to full, ½ or an explicit semitone count. */
19
+ label?: string;
20
+ }
21
+ /** Normalize the written amount independently of the bend's horizontal length. */
22
+ export declare function bendAmount(bend: TimedStringBend): string;
23
+ /** Validate the performed order before constructing a modifier or changing a note. */
24
+ export declare function copyBend(bend: TimedStringBend): TimedStringBend;
25
+ /** Preserve the action as structured score metadata as well as a spoken description. */
26
+ export declare function strokeIdentity(action: GuitarStroke): NotationIdentity;
@@ -0,0 +1,3 @@
1
+ import type { Note } from './note';
2
+ /** Attach native modifiers once, after a new note has initialized its heads or string positions. */
3
+ export declare function attachGuitarGestures(note: Note): void;
@@ -1,4 +1,5 @@
1
1
  export * from './accidental';
2
+ export * from './alternatingtremolo';
2
3
  export * from './annotation';
3
4
  export * from './articulation';
4
5
  export * from './barnote';
@@ -14,8 +15,13 @@ export * from './curve';
14
15
  export * from './dot';
15
16
  export * from './easyscore';
16
17
  export * from './element';
18
+ export * from './engravinggeometry';
19
+ export * from './engravingprofile';
17
20
  export * from './factory';
18
21
  export * from './font';
22
+ export * from './fretdiagram';
23
+ export * from './instrumentprofile';
24
+ export * from './notationspelling';
19
25
  export * from './flag';
20
26
  export * from './formatter';
21
27
  export * from './fraction';
@@ -40,10 +46,12 @@ export * from './ornament';
40
46
  export * from './parenthesis';
41
47
  export * from './parser';
42
48
  export * from './pedalmarking';
49
+ export * from './phraselayout';
43
50
  export * from './registry';
44
51
  export * from './rendercontext';
45
52
  export * from './renderer';
46
53
  export * from './repeatnote';
54
+ export * from './scorenavigation';
47
55
  export * from './sheet';
48
56
  export * from './stave';
49
57
  export * from './stavebarline';
@@ -81,6 +89,10 @@ export * from './tuning';
81
89
  export * from './tuplet';
82
90
  export * from './typeguard';
83
91
  export * from './util';
92
+ export * from './continuouslayout';
93
+ export type { ContinuousSpan, ContinuousSpanKind, SpanFragment } from './continuousspan';
94
+ export type { GuitarStroke, TimedStringBend } from './guitargesture';
95
+ export * from './publication';
84
96
  export * from './vexflow';
85
97
  export * from './vibrato';
86
98
  export * from './vibratobracket';