vexflow 5.1.2 → 5.3.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 (162) hide show
  1. package/README.md +7 -6
  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 +5325 -1730
  7. package/build/cjs/vexflow-debug-with-tests.js.map +1 -1
  8. package/build/cjs/vexflow-debug.js +4228 -1545
  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 +13 -3
  13. package/build/esm/src/articulation.js +51 -20
  14. package/build/esm/src/beam.js +170 -30
  15. package/build/esm/src/bend.js +24 -19
  16. package/build/esm/src/clef.js +3 -0
  17. package/build/esm/src/clefnote.js +5 -1
  18. package/build/esm/src/curve.js +27 -53
  19. package/build/esm/src/dot.js +14 -5
  20. package/build/esm/src/easyscore/composition.js +336 -0
  21. package/build/esm/src/easyscore/elementindex.js +81 -0
  22. package/build/esm/src/easyscore/elements.js +324 -0
  23. package/build/esm/src/easyscore/policies.js +97 -0
  24. package/build/esm/src/easyscore/rhythm.js +42 -0
  25. package/build/esm/src/easyscore.js +448 -26
  26. package/build/esm/src/element.js +17 -2
  27. package/build/esm/src/engravinggeometry.js +150 -0
  28. package/build/esm/src/engravingprofile.js +44 -0
  29. package/build/esm/src/factory.js +268 -64
  30. package/build/esm/src/formatter.js +40 -4
  31. package/build/esm/src/gracenote.js +43 -38
  32. package/build/esm/src/gracenotegroup.js +53 -56
  33. package/build/esm/src/index.js +2 -0
  34. package/build/esm/src/keysignature.js +10 -2
  35. package/build/esm/src/keysignote.js +2 -2
  36. package/build/esm/src/modifiercontext.js +11 -0
  37. package/build/esm/src/note.js +5 -0
  38. package/build/esm/src/notehead.js +11 -6
  39. package/build/esm/src/ornament.js +38 -18
  40. package/build/esm/src/parenthesis.js +1 -1
  41. package/build/esm/src/parser.js +6 -1
  42. package/build/esm/src/proportionalformatter.js +234 -0
  43. package/build/esm/src/registry.js +27 -0
  44. package/build/esm/src/sheet.js +20 -3
  45. package/build/esm/src/stave.js +9 -2
  46. package/build/esm/src/stavenote.js +140 -127
  47. package/build/esm/src/stavetie.js +39 -7
  48. package/build/esm/src/stem.js +26 -11
  49. package/build/esm/src/stemmablenote.js +6 -1
  50. package/build/esm/src/tickable.js +5 -0
  51. package/build/esm/src/tickcontext.js +19 -0
  52. package/build/esm/src/timesignature.js +5 -0
  53. package/build/esm/src/tuplet.js +60 -19
  54. package/build/esm/src/version.js +3 -3
  55. package/build/esm/src/vexflow.js +6 -1
  56. package/build/esm/tests/beam_tests.js +35 -0
  57. package/build/esm/tests/bend_tests.js +14 -1
  58. package/build/esm/tests/curve_tests.js +14 -4
  59. package/build/esm/tests/demo_repertoire_tests.js +27 -0
  60. package/build/esm/tests/demos/drums.js +54 -0
  61. package/build/esm/tests/demos/electric.js +63 -0
  62. package/build/esm/tests/demos/greensleeves.js +90 -0
  63. package/build/esm/tests/demos/joy.js +61 -0
  64. package/build/esm/tests/demos/kesh.js +80 -0
  65. package/build/esm/tests/demos/prelude.js +59 -0
  66. package/build/esm/tests/demos/quartertones.js +50 -0
  67. package/build/esm/tests/demos/saints.js +65 -0
  68. package/build/esm/tests/easyscore_tests.js +40 -0
  69. package/build/esm/tests/easyscore_types.js +65 -0
  70. package/build/esm/tests/engraving/score-layout.mjs +75 -0
  71. package/build/esm/tests/engraving/score-persistence.mjs +262 -0
  72. package/build/esm/tests/engraving/studies.mjs +279 -0
  73. package/build/esm/tests/formatter_tests.js +51 -1
  74. package/build/esm/tests/index.js +1 -0
  75. package/build/esm/tests/node/audit-dependencies-tests.mjs +42 -0
  76. package/build/esm/tests/node/easyscore-rendering-tests.mjs +332 -0
  77. package/build/esm/tests/node/easyscore-tests.mjs +1024 -0
  78. package/build/esm/tests/node/engraving-layout-tests.mjs +449 -0
  79. package/build/esm/tests/node/local-engraving-tests.mjs +128 -0
  80. package/build/esm/tests/node/proportional-spacing-tests.mjs +278 -0
  81. package/build/esm/tests/node/rendering-tests.mjs +6 -2
  82. package/build/esm/tests/threevoice_tests.js +11 -1
  83. package/build/esm/tests/vexflow_test_helpers.js +19 -10
  84. package/build/esm/tools/audit-dependencies.mjs +61 -0
  85. package/build/esm/tools/easyscore-api-audit.mjs +58 -0
  86. package/build/esm/tools/easyscore-composition.mjs +62 -0
  87. package/build/esm/tools/easyscore-example.mjs +16 -0
  88. package/build/esm/tools/easyscore-families.mjs +61 -0
  89. package/build/esm/tools/easyscore-references-example.mjs +26 -0
  90. package/build/esm/tools/easyscore-rhythm.mjs +58 -0
  91. package/build/esm/tools/easyscore-structure.mjs +88 -0
  92. package/build/esm/tools/explorer/catalog/entries.mjs +6 -0
  93. package/build/esm/tools/explorer/catalog/expression.mjs +68 -0
  94. package/build/esm/tools/explorer/catalog/helpers.mjs +29 -0
  95. package/build/esm/tools/explorer/catalog/layout.mjs +109 -0
  96. package/build/esm/tools/explorer/catalog/notes.mjs +61 -0
  97. package/build/esm/tools/explorer/catalog/staves.mjs +85 -0
  98. package/build/esm/tools/explorer/catalog/strings.mjs +25 -0
  99. package/build/esm/tools/explorer/catalog.mjs +14 -0
  100. package/build/esm/tools/score-fixtures.mjs +23 -6
  101. package/build/types/src/accidental.d.ts +6 -0
  102. package/build/types/src/articulation.d.ts +12 -1
  103. package/build/types/src/beam.d.ts +16 -0
  104. package/build/types/src/clef.d.ts +2 -0
  105. package/build/types/src/curve.d.ts +9 -0
  106. package/build/types/src/dot.d.ts +5 -0
  107. package/build/types/src/easyscore/composition.d.ts +126 -0
  108. package/build/types/src/easyscore/elementindex.d.ts +30 -0
  109. package/build/types/src/easyscore/elements.d.ts +156 -0
  110. package/build/types/src/easyscore/policies.d.ts +12 -0
  111. package/build/types/src/easyscore/rhythm.d.ts +9 -0
  112. package/build/types/src/easyscore.d.ts +153 -11
  113. package/build/types/src/element.d.ts +7 -1
  114. package/build/types/src/engravinggeometry.d.ts +31 -0
  115. package/build/types/src/engravingprofile.d.ts +20 -0
  116. package/build/types/src/factory.d.ts +97 -9
  117. package/build/types/src/formatter.d.ts +7 -1
  118. package/build/types/src/gracenote.d.ts +7 -0
  119. package/build/types/src/gracenotegroup.d.ts +7 -2
  120. package/build/types/src/index.d.ts +2 -0
  121. package/build/types/src/keysignature.d.ts +3 -0
  122. package/build/types/src/keysignote.d.ts +1 -1
  123. package/build/types/src/modifiercontext.d.ts +4 -0
  124. package/build/types/src/note.d.ts +2 -0
  125. package/build/types/src/notehead.d.ts +5 -0
  126. package/build/types/src/ornament.d.ts +7 -0
  127. package/build/types/src/parser.d.ts +5 -0
  128. package/build/types/src/proportionalformatter.d.ts +39 -0
  129. package/build/types/src/registry.d.ts +4 -0
  130. package/build/types/src/stave.d.ts +2 -0
  131. package/build/types/src/stavenote.d.ts +21 -3
  132. package/build/types/src/stavetie.d.ts +4 -0
  133. package/build/types/src/stem.d.ts +10 -1
  134. package/build/types/src/stemmablenote.d.ts +6 -1
  135. package/build/types/src/tickable.d.ts +2 -0
  136. package/build/types/src/tickcontext.d.ts +5 -0
  137. package/build/types/src/timesignature.d.ts +2 -0
  138. package/build/types/src/tuplet.d.ts +5 -48
  139. package/build/types/src/vexflow.d.ts +6 -1
  140. package/changelog/CHANGELOG.md +52 -0
  141. package/package.json +13 -3
  142. package/tests/all.html +277 -0
  143. package/tests/demo_petzold_tests.ts +435 -0
  144. package/tests/demos/drums.ts +55 -0
  145. package/tests/demos/drums.webp +0 -0
  146. package/tests/demos/electric.ts +70 -0
  147. package/tests/demos/electric.webp +0 -0
  148. package/tests/demos/greensleeves.ts +97 -0
  149. package/tests/demos/greensleeves.webp +0 -0
  150. package/tests/demos/joy.ts +65 -0
  151. package/tests/demos/joy.webp +0 -0
  152. package/tests/demos/kesh.ts +86 -0
  153. package/tests/demos/kesh.webp +0 -0
  154. package/tests/demos/prelude.ts +65 -0
  155. package/tests/demos/prelude.webp +0 -0
  156. package/tests/demos/quartertones.ts +51 -0
  157. package/tests/demos/quartertones.webp +0 -0
  158. package/tests/demos/saints.ts +70 -0
  159. package/tests/demos/saints.webp +0 -0
  160. package/tests/flow.html +550 -239
  161. package/tests/fonts.css +493 -0
  162. package/tests/minuet.webp +0 -0
@@ -1,12 +1,29 @@
1
1
  import { Accidental } from './accidental';
2
2
  import { PartialBeamDirection } from './beam';
3
- import { Factory } from './factory';
3
+ import { EasyScoreComposition, EasyScoreCompositionSpec } from './easyscore/composition';
4
+ import { EasyScoreSource } from './easyscore/elementindex';
5
+ import { EasyScoreElements } from './easyscore/elements';
6
+ import { EasyScoreAutoBeamOptions } from './easyscore/rhythm';
7
+ import { Element, ElementStyle } from './element';
8
+ import { Factory, FactoryElementRole, FactoryOptions } from './factory';
9
+ import { Modifier } from './modifier';
4
10
  import { Note } from './note';
5
11
  import { Grammar, Match, Parser, Result, Rule, RuleFunction } from './parser';
6
12
  import { RenderContext } from './rendercontext';
13
+ import { Sheet, SheetOptions } from './sheet';
14
+ import { Stave } from './stave';
15
+ import { StaveModifier } from './stavemodifier';
16
+ import { StaveNoteStruct } from './stavenote';
7
17
  import { StemmableNote } from './stemmablenote';
18
+ import { System, SystemOptions } from './system';
19
+ import { Tickable } from './tickable';
8
20
  import { TupletOptions } from './tuplet';
9
- import { Voice } from './voice';
21
+ import { RuntimeError } from './util';
22
+ import { Voice, VoiceMode, VoiceTime } from './voice';
23
+ export type { EasyScoreComposition, EasyScoreCompositionDiagnostic, EasyScoreCompositionSpec, EasyScoreContent, EasyScoreMeasureSpec, EasyScoreSpanSpec, EasyScoreStaffState, EasyScoreStaveSpec, EasyScoreVoiceSpec, } from './easyscore/composition';
24
+ export type { EasyScoreSource } from './easyscore/elementindex';
25
+ export type { EasyScoreTabSpan } from './easyscore/elements';
26
+ export type { EasyScoreAutoBeamOptions } from './easyscore/rhythm';
10
27
  export type CommitHook = (obj: any, note: StemmableNote, builder: Builder) => void;
11
28
  export declare class EasyScoreGrammar implements Grammar {
12
29
  builder: Builder;
@@ -55,6 +72,8 @@ export interface NotePiece {
55
72
  octave?: string;
56
73
  }
57
74
  export declare class Piece {
75
+ /** Range of this piece in the most recently parsed input. */
76
+ source?: EasyScoreSourceSpan;
58
77
  chord: NotePiece[];
59
78
  duration: string;
60
79
  dots: number;
@@ -69,6 +88,16 @@ export interface BuilderElements {
69
88
  accidentals: (Accidental | undefined)[][];
70
89
  }
71
90
  export interface BuilderOptions extends Record<string, any> {
91
+ /** Native note options. String notation still supplies keys, duration, dots, and type. */
92
+ octaveShift?: StaveNoteStruct['octaveShift'];
93
+ strokePx?: StaveNoteStruct['strokePx'];
94
+ alignCenter?: StaveNoteStruct['alignCenter'];
95
+ line?: StaveNoteStruct['line'];
96
+ durationOverride?: StaveNoteStruct['durationOverride'];
97
+ id?: string;
98
+ class?: string;
99
+ articulations?: string;
100
+ fingerings?: string;
72
101
  stem?: string;
73
102
  clef?: string;
74
103
  /** Initial duration for notes that omit one. Defaults to an eighth note. */
@@ -80,8 +109,10 @@ export declare class Builder {
80
109
  options: BuilderOptions;
81
110
  piece: Piece;
82
111
  commitHooks: CommitHook[];
112
+ /** @internal EasyScore observes completed pieces after application hooks have run. */
113
+ onNote?: (note: StemmableNote, source?: EasyScoreSourceSpan) => void;
83
114
  rollingDuration: string;
84
- constructor(factory: Factory);
115
+ constructor(factory?: Factory);
85
116
  reset(options?: BuilderOptions): void;
86
117
  getFactory(): Factory;
87
118
  getElements(): BuilderElements;
@@ -94,17 +125,65 @@ export declare class Builder {
94
125
  addNote(key?: string, accid?: string | null, octave?: string): void;
95
126
  addSingleNote(key: string, accid?: string | null, octave?: string): void;
96
127
  addChord(notes: Match[]): void;
97
- commitPiece(): void;
128
+ commitPiece(source?: EasyScoreSourceSpan): void;
129
+ }
130
+ /** Zero-based, end-exclusive source range. */
131
+ export interface EasyScoreSourceSpan {
132
+ start: number;
133
+ end: number;
134
+ }
135
+ /** Editor-friendly error. Line and column are one-based. */
136
+ export interface EasyScoreDiagnostic extends EasyScoreSourceSpan {
137
+ code: string;
138
+ message: string;
139
+ line: number;
140
+ column: number;
141
+ measure?: number;
142
+ }
143
+ /** Parsed notation contains data only; no VexFlow elements or render context. */
144
+ export interface EasyScoreParsedPiece extends Piece {
145
+ source: EasyScoreSourceSpan;
146
+ }
147
+ export interface EasyScoreParseResult {
148
+ success: boolean;
149
+ pieces: EasyScoreParsedPiece[];
150
+ diagnostics: EasyScoreDiagnostic[];
151
+ }
152
+ /** The same diagnostics are available to callers that prefer exceptions. */
153
+ export declare class EasyScoreError extends RuntimeError {
154
+ readonly diagnostics: EasyScoreDiagnostic[];
155
+ constructor(diagnostics: EasyScoreDiagnostic[]);
156
+ }
157
+ /** Voice settings are applied before inserting notes, including strictness and resolution. */
158
+ export interface EasyScoreVoiceOptions {
159
+ time?: VoiceTime | string;
160
+ mode?: 'strict' | 'soft' | 'full' | VoiceMode;
161
+ softmaxFactor?: number;
162
+ /** Legacy spelling remains supported. */
163
+ options?: {
164
+ softmaxFactor: number;
165
+ };
166
+ }
167
+ /** Pure extension validation runs before any Factory construction or commit hook. */
168
+ export interface EasyScoreValidationContext {
169
+ piece: Readonly<EasyScoreParsedPiece>;
170
+ options: Readonly<BuilderOptions>;
98
171
  }
99
172
  export interface EasyScoreOptions {
100
173
  factory?: Factory;
101
174
  builder?: Builder;
102
175
  commitHooks?: CommitHook[];
103
176
  throwOnError?: boolean;
177
+ /** Reject unknown built-in options. Enabled by create(); legacy factories keep their extension behavior. */
178
+ strictOptions?: boolean;
179
+ /** Extra option names consumed by application commit hooks in strict mode. */
180
+ extensions?: readonly string[];
181
+ /** Throw to return a source diagnostic. Must not mutate input or application state. */
182
+ validate?: (context: EasyScoreValidationContext) => void;
104
183
  }
105
184
  export interface EasyScoreDefaults extends Record<string, any> {
106
185
  clef?: string;
107
- time?: string;
186
+ time?: VoiceTime | string;
108
187
  stem?: string;
109
188
  }
110
189
  /**
@@ -112,6 +191,54 @@ export interface EasyScoreDefaults extends Record<string, any> {
112
191
  */
113
192
  export declare class EasyScore {
114
193
  static DEBUG: boolean;
194
+ private references;
195
+ /** The complete measure input, when parse() is constructing a trimmed measure. */
196
+ private sourceContext?;
197
+ /** Inspect notation provenance without installing a global Registry. Useful for visual tooling. */
198
+ static getSource(element: Element): EasyScoreSource | undefined;
199
+ /** Look up a native object in this score. Missing IDs return undefined. */
200
+ getElement(id: string): Element | undefined;
201
+ /** Resolve a named note for typed relationship APIs. Missing IDs and non-notes throw. */
202
+ getNote(id: string): Note;
203
+ /** Return a defensive copy of a generated element's source, or undefined for native objects. */
204
+ getSource(element: Element): EasyScoreSource | undefined;
205
+ /** Explicitly join a native extension to this score's ownership and drawing lifecycle. */
206
+ adopt<T extends Element>(element: T, role: FactoryElementRole): T;
207
+ /** Stage local references together with Factory queues and ambient registry entries. */
208
+ private transaction;
209
+ /** Create a strict EasyScore facade with its own Factory. Load fonts before constructing notation. */
210
+ static create(options: FactoryOptions, scoreOptions?: Omit<EasyScoreOptions, 'factory' | 'builder'>): EasyScore;
211
+ /** Typed constructors return native objects and share the facade's transaction boundary. */
212
+ readonly make: EasyScoreElements;
213
+ /** Attach a modifier once. Native custom modifiers are welcome; foreign Factory objects are rejected. */
214
+ attach<T extends Note>(note: T, modifier: Modifier, index?: number): T;
215
+ /** Attach staff notation once; the stave owns its drawing lifecycle. */
216
+ attachToStave<T extends Stave>(stave: T, modifier: StaveModifier, position?: number): T;
217
+ /** Apply temporary defaults to synchronous managed construction; restore them on success or failure. */
218
+ withDefaults<T>(defaults: EasyScoreDefaults, construct: (score: EasyScore) => T & (T extends PromiseLike<unknown> ? never : unknown)): T;
219
+ /** Construct aligned measures and resolve forward references before layout or drawing. */
220
+ compose(spec: EasyScoreCompositionSpec): EasyScoreComposition;
221
+ /** Build a normal System; its staff API and formatter options stay available. */
222
+ system(options?: SystemOptions): System;
223
+ /** Create a native responsive Sheet. Its systems remain managed by this Factory. */
224
+ sheet(options?: Omit<SheetOptions, 'factory'>): Sheet;
225
+ /**
226
+ * Stage a group of synchronous construction calls. Failed groups release their new objects and IDs.
227
+ * Existing-object setters and application side effects remain the caller's responsibility.
228
+ */
229
+ build<T>(construct: (score: EasyScore) => T & (T extends PromiseLike<unknown> ? never : unknown)): T;
230
+ /** Apply the Factory foreground defaults without changing global metrics or fonts. */
231
+ setStyle(style: Pick<ElementStyle, 'fillStyle' | 'strokeStyle'>): this;
232
+ /** Delegate drawing and the existing opt-in retained lifecycle to Factory. */
233
+ draw(options?: {
234
+ retain?: boolean;
235
+ }): void;
236
+ /** Release queued notation and the builder's last result. */
237
+ reset(): this;
238
+ /** Endpoints and voice notes must share this facade's Factory. */
239
+ private requireOwned;
240
+ /** Reject invalid chord-head references before attaching or queuing notation. */
241
+ private checkIndex;
115
242
  defaults: EasyScoreDefaults;
116
243
  options: EasyScoreOptions;
117
244
  factory: Factory;
@@ -134,7 +261,18 @@ export declare class EasyScore {
134
261
  */
135
262
  setOptions(options: EasyScoreOptions): this;
136
263
  setContext(context: RenderContext): this;
264
+ /** Parse and validate without touching this builder, its hooks, Factory queues, or registries. */
265
+ parseNotation(line: string, options?: BuilderOptions): EasyScoreParseResult;
266
+ /** Validate built-in fields before allocating notes. Extension values are left to application hooks. */
267
+ private validatePiece;
268
+ /** Observe source ranges only during this parse, including legacy partial results. */
137
269
  parse(line: string, options?: BuilderOptions): Result;
270
+ /** Strict construction is transactional; the legacy non-throwing parser retains partial output. */
271
+ private parseInput;
272
+ /**
273
+ * Resolve automatic stems for the whole group while respecting explicit stems.
274
+ * autoStem: true overrides explicit directions; false preserves all directions.
275
+ */
138
276
  beam(notes: StemmableNote[], options?: {
139
277
  autoStem?: boolean;
140
278
  secondaryBeamBreaks?: number[];
@@ -142,19 +280,23 @@ export declare class EasyScore {
142
280
  [noteIndex: number]: PartialBeamDirection;
143
281
  };
144
282
  }): StemmableNote[];
283
+ /** Generate and own native beam groups without changing rhythmic duration. */
284
+ autoBeam(notes: StemmableNote[], options?: EasyScoreAutoBeamOptions): import("./beam").Beam[];
285
+ /** Explicit pitched stems constrain the group; conflicting explicit stems remain mixed. */
286
+ private resolveBeamStems;
145
287
  tuplet(notes: StemmableNote[], options?: TupletOptions): StemmableNote[];
146
288
  notes(line: string, options?: BuilderOptions): StemmableNote[];
289
+ /** Mix notation fragments, full native note structs, and already-owned native tickables. */
290
+ sequence(items: readonly (string | StaveNoteStruct | Tickable)[], options?: BuilderOptions): Tickable[];
147
291
  /**
148
292
  * Parse bar-separated measures. Durations carry across bars; notes() is unchanged.
149
293
  * A bar may have adjacent commas. Quoted option values may contain literal bars.
150
294
  * Empty measures and invalid notation throw, rather than returning partial music.
151
295
  */
152
296
  measures(line: string, options?: BuilderOptions): StemmableNote[][];
153
- voice(notes: Note[], options?: {
154
- time?: string;
155
- options?: {
156
- softmaxFactor: number;
157
- };
158
- }): Voice;
297
+ /** Split only unquoted bars and retain each trimmed measure's original source offset. */
298
+ private splitMeasures;
299
+ /** Configure time, mode, and spacing before inserting tickables. */
300
+ voice(notes: Tickable[], options?: EasyScoreVoiceOptions): Voice;
159
301
  addCommitHook(commitHook: CommitHook): void;
160
302
  }
@@ -84,6 +84,8 @@ export declare class Element {
84
84
  /** Distinguishes caller overrides from built-in metric colors. */
85
85
  protected styleExplicit: boolean;
86
86
  protected registry?: Registry;
87
+ /** Independent ID indexes can validate changes without replacing the default Registry. */
88
+ private idListeners?;
87
89
  protected _fontInfo: Required<FontInfo>;
88
90
  protected fontScale: number;
89
91
  protected _text: string;
@@ -150,7 +152,7 @@ export declare class Element {
150
152
  /** Remove a class label (An element can have multiple class labels). */
151
153
  removeClass(className: string): this;
152
154
  /** Call back from registry after the element is registered. */
153
- onRegister(registry: Registry): this;
155
+ onRegister(registry?: Registry): this;
154
156
  /** Return the rendered status. */
155
157
  isRendered(): boolean;
156
158
  /** Set the rendered status. */
@@ -161,8 +163,12 @@ export declare class Element {
161
163
  getAttribute(name: string): any;
162
164
  /** Return associated SVGElement. */
163
165
  getSVGElement(suffix?: string): SVGElement | undefined;
166
+ /** @internal Subscribe a local ID index. All validators run before an ID is changed. */
167
+ onIdChange(validate: (id: string | undefined) => void, changed: () => void): () => void;
164
168
  /** Set an attribute such as 'id', 'class', or 'type'. */
165
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;
166
172
  /** Get the boundingBox. */
167
173
  getBoundingBox(): BoundingBox;
168
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 {};
@@ -3,11 +3,16 @@ import { Annotation, AnnotationHorizontalJustify, AnnotationVerticalJustify } fr
3
3
  import { Articulation } from './articulation';
4
4
  import { BarNote } from './barnote';
5
5
  import { Beam, PartialBeamDirection } from './beam';
6
+ import { Bend } from './bend';
6
7
  import { ChordSymbol } from './chordsymbol';
8
+ import { Clef } from './clef';
7
9
  import { ClefNote } from './clefnote';
10
+ import { Crescendo } from './crescendo';
8
11
  import { Curve, CurveOptions } from './curve';
12
+ import { Dot } from './dot';
9
13
  import { EasyScore, EasyScoreOptions } from './easyscore';
10
14
  import { Element } from './element';
15
+ import { EngravingProfile } from './engravingprofile';
11
16
  import { FontInfo } from './font';
12
17
  import { Formatter, FormatterOptions } from './formatter';
13
18
  import { FretHandFinger } from './frethandfinger';
@@ -15,36 +20,56 @@ import { GhostNote } from './ghostnote';
15
20
  import { GlyphNote, GlyphNoteOptions } from './glyphnote';
16
21
  import { GraceNote, GraceNoteStruct } from './gracenote';
17
22
  import { GraceNoteGroup } from './gracenotegroup';
23
+ import { GraceTabNote } from './gracetabnote';
24
+ import { KeySignature } from './keysignature';
18
25
  import { KeySigNote } from './keysignote';
26
+ import { Modifier } from './modifier';
19
27
  import { ModifierContext } from './modifiercontext';
20
28
  import { MultiMeasureRest, MultimeasureRestRenderOptions } from './multimeasurerest';
21
29
  import { Note, NoteStruct } from './note';
22
30
  import { NoteSubGroup } from './notesubgroup';
23
31
  import { Ornament } from './ornament';
32
+ import { Parenthesis } from './parenthesis';
24
33
  import { PedalMarking } from './pedalmarking';
25
34
  import { RenderContext } from './rendercontext';
26
35
  import { RepeatNote } from './repeatnote';
27
36
  import { Sheet, SheetOptions } from './sheet';
28
37
  import { Stave, StaveOptions } from './stave';
29
- import { BarlineType } from './stavebarline';
38
+ import { Barline, BarlineType } from './stavebarline';
30
39
  import { StaveConnector, StaveConnectorType } from './staveconnector';
40
+ import { StaveHairpin, StaveHairpinRenderOptions } from './stavehairpin';
31
41
  import { StaveLine } from './staveline';
32
42
  import { StaveNote, StaveNoteStruct } from './stavenote';
43
+ import { Repetition } from './staverepetition';
44
+ import { StaveSection } from './stavesection';
45
+ import { StaveTempo } from './stavetempo';
46
+ import { StaveText } from './stavetext';
33
47
  import { StaveTie } from './stavetie';
48
+ import { Volta } from './stavevolta';
34
49
  import { StemmableNote } from './stemmablenote';
35
50
  import { StringNumber } from './stringnumber';
51
+ import { Stroke } from './strokes';
36
52
  import { System, SystemOptions } from './system';
37
53
  import { TabNote, TabNoteStruct } from './tabnote';
54
+ import { TabSlide } from './tabslide';
38
55
  import { TabStave } from './tabstave';
56
+ import { TabTie } from './tabtie';
39
57
  import { TextBracket } from './textbracket';
40
58
  import { TextDynamics } from './textdynamics';
41
59
  import { TextNote, TextNoteStruct } from './textnote';
42
60
  import { TickContext } from './tickcontext';
61
+ import { TimeSignature } from './timesignature';
43
62
  import { TimeSigNote } from './timesignote';
63
+ import { Tremolo } from './tremolo';
44
64
  import { Tuplet, TupletOptions } from './tuplet';
65
+ import { Vibrato } from './vibrato';
45
66
  import { VibratoBracket } from './vibratobracket';
46
67
  import { Voice, VoiceTime } from './voice';
68
+ /** Explicit drawing role for a native extension adopted into a Factory. */
69
+ export type FactoryElementRole = 'note' | 'modifier' | 'staveModifier' | 'drawable';
47
70
  export interface FactoryOptions {
71
+ /** Optional per-score pitched notation and beam policy. */
72
+ engraving?: EngravingProfile;
48
73
  stave?: {
49
74
  space: number;
50
75
  };
@@ -72,7 +97,7 @@ export declare class Factory {
72
97
  * `const vf: Factory = VexFlow.Factory.newFromElementId('boo', 1200, 600 );`
73
98
  */
74
99
  static newFromElementId(elementId: string | null, width?: number, height?: number): Factory;
75
- protected options: Required<FactoryOptions>;
100
+ protected options: Required<Omit<FactoryOptions, 'engraving'>> & Pick<FactoryOptions, 'engraving'>;
76
101
  protected stave?: Stave;
77
102
  protected context: RenderContext;
78
103
  protected staves: Stave[];
@@ -81,6 +106,24 @@ export declare class Factory {
81
106
  protected systems: System[];
82
107
  protected sheets: Sheet[];
83
108
  private retained;
109
+ /** Ownership survives drawing; weak keys do not retain discarded notation. */
110
+ private static owners;
111
+ private constructionScopes;
112
+ private groupScopes;
113
+ private static groups;
114
+ /** A grouped note draws only through its modifier, never through a main voice or queue. */
115
+ static getGroup(note: Note): Modifier | undefined;
116
+ /** Identify the Factory that created an element, without changing its draw role. */
117
+ static getOwner(element: Element): Factory | undefined;
118
+ /** Record ownership independently of whether the element draws itself or attaches to a note. */
119
+ private own;
120
+ /**
121
+ * Adopt a native extension without guessing its drawing role. Attachment and layout remain explicit.
122
+ * Repeating adoption cannot enqueue an element twice. Ownership survives draw/reset.
123
+ */
124
+ adopt<T extends Element>(element: T, role: FactoryElementRole): T;
125
+ /** Stage synchronous construction. Failed operations preserve existing queues and registry entries. */
126
+ transaction<T>(build: () => T): T;
84
127
  /** Foreground defaults survive reset(), like renderer options. */
85
128
  protected style: {
86
129
  fillStyle?: string;
@@ -121,6 +164,34 @@ export declare class Factory {
121
164
  width?: number;
122
165
  options?: StaveOptions;
123
166
  }): TabStave;
167
+ /** Construct a native Bend with an explicit drawing role. */
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;
171
+ /** Construct a native Clef with an explicit drawing role. */
172
+ Clef(...args: ConstructorParameters<typeof Clef>): Clef;
173
+ /** Construct a native KeySignature with an explicit drawing role. */
174
+ KeySignature(...args: ConstructorParameters<typeof KeySignature>): KeySignature;
175
+ /** Construct a native TimeSignature with an explicit drawing role. */
176
+ TimeSignature(...args: ConstructorParameters<typeof TimeSignature>): TimeSignature;
177
+ /** Construct a native Barline with an explicit drawing role. */
178
+ Barline(...args: ConstructorParameters<typeof Barline>): Barline;
179
+ /** Construct a native Repetition with an explicit drawing role. */
180
+ Repetition(...args: ConstructorParameters<typeof Repetition>): Repetition;
181
+ /** Construct a native Volta with an explicit drawing role. */
182
+ Volta(...args: ConstructorParameters<typeof Volta>): Volta;
183
+ /** Construct a native StaveSection with an explicit drawing role. */
184
+ StaveSection(...args: ConstructorParameters<typeof StaveSection>): StaveSection;
185
+ /** Construct a native StaveTempo with an explicit drawing role. */
186
+ StaveTempo(...args: ConstructorParameters<typeof StaveTempo>): StaveTempo;
187
+ /** Construct a native StaveText with an explicit drawing role. */
188
+ StaveText(...args: ConstructorParameters<typeof StaveText>): StaveText;
189
+ /** Construct a native TabTie with an explicit drawing role. */
190
+ TabTie(...args: ConstructorParameters<typeof TabTie>): TabTie;
191
+ /** Construct a native TabSlide with an explicit drawing role. */
192
+ TabSlide(...args: ConstructorParameters<typeof TabSlide>): TabSlide;
193
+ /** Grace tab children draw through a GraceNoteGroup, never as standalone tickables. */
194
+ GraceTabNote(options: TabNoteStruct): GraceTabNote;
124
195
  StaveNote(noteStruct: StaveNoteStruct): StaveNote;
125
196
  GlyphNote(glyph: string, noteStruct: NoteStruct, options?: GlyphNoteOptions): GlyphNote;
126
197
  RepeatNote(type: string, noteStruct?: NoteStruct, options?: GlyphNoteOptions): RepeatNote;
@@ -143,8 +214,9 @@ export declare class Factory {
143
214
  key: string;
144
215
  cancelKey?: string;
145
216
  alterKey?: string[];
217
+ clef?: string;
146
218
  }): KeySigNote;
147
- TabNote(noteStruct: TabNoteStruct): TabNote;
219
+ TabNote(noteStruct: TabNoteStruct, drawStem?: boolean): TabNote;
148
220
  GraceNote(noteStruct: GraceNoteStruct): GraceNote;
149
221
  GraceNoteGroup(params: {
150
222
  notes: StemmableNote[];
@@ -177,12 +249,7 @@ export declare class Factory {
177
249
  lowerAccidental?: string;
178
250
  delayed?: boolean;
179
251
  }): Ornament;
180
- TextDynamics(params?: {
181
- text?: string;
182
- duration?: string;
183
- dots?: number;
184
- line?: number;
185
- }): TextDynamics;
252
+ TextDynamics(params?: Partial<TextNoteStruct>): TextDynamics;
186
253
  Fingering(params: {
187
254
  number?: string;
188
255
  position?: string;
@@ -283,6 +350,27 @@ export declare class Factory {
283
350
  NoteSubGroup(params?: {
284
351
  notes?: Note[];
285
352
  }): NoteSubGroup;
353
+ /** Transfer unvoiced notes to one modifier. Validation happens before native voice assignment. */
354
+ groupNotes<T extends Modifier>(notes: Note[], construct: () => T): T;
355
+ /** Construct a native Dot for attachment; preserve its full constructor options. */
356
+ Dot(...args: ConstructorParameters<typeof Dot>): Dot;
357
+ /** Construct a native Parenthesis for attachment; preserve its full constructor options. */
358
+ Parenthesis(...args: ConstructorParameters<typeof Parenthesis>): Parenthesis;
359
+ /** Construct a native Stroke for attachment; preserve its full constructor options. */
360
+ Stroke(...args: ConstructorParameters<typeof Stroke>): Stroke;
361
+ /** Construct a native Tremolo for attachment; preserve its full constructor options. */
362
+ Tremolo(...args: ConstructorParameters<typeof Tremolo>): Tremolo;
363
+ /** Construct a native Vibrato for attachment; preserve its full constructor options. */
364
+ Vibrato(...args: ConstructorParameters<typeof Vibrato>): Vibrato;
365
+ /** Timed crescendo note; span hairpins have a separate constructor. */
366
+ Crescendo(...args: ConstructorParameters<typeof Crescendo>): Crescendo;
367
+ /** Stave-bound hairpin. The native renderer requires both endpoints. */
368
+ StaveHairpin(params: {
369
+ from: Note;
370
+ to: Note;
371
+ type: number;
372
+ options?: Partial<StaveHairpinRenderOptions>;
373
+ }): StaveHairpin;
286
374
  /** Render the score. */
287
375
  draw(options?: {
288
376
  retain?: boolean;
@@ -1,5 +1,6 @@
1
1
  import { BoundingBox } from './boundingbox';
2
2
  import { ModifierContext } from './modifiercontext';
3
+ import { MeasuredSpacing } from './proportionalformatter';
3
4
  import { RenderContext } from './rendercontext';
4
5
  import { Stave } from './stave';
5
6
  import { StemmableNote } from './stemmablenote';
@@ -8,7 +9,10 @@ import { TabStave } from './tabstave';
8
9
  import { Tickable } from './tickable';
9
10
  import { TickContext } from './tickcontext';
10
11
  import { Voice } from './voice';
12
+ export type { MeasuredSpacing, ProportionalSpacing } from './proportionalformatter';
11
13
  export interface FormatterOptions {
14
+ /** Omit to use the default engraving layout. */
15
+ spacing?: MeasuredSpacing;
12
16
  /** Defaults to Tables.SOFTMAX_FACTOR. */
13
17
  softmaxFactor?: number;
14
18
  /** Defaults to `false`. */
@@ -69,7 +73,9 @@ export declare class Formatter {
69
73
  protected totalCost: number;
70
74
  protected totalShift: number;
71
75
  protected tickContexts: AlignmentTickContexts;
72
- protected formatterOptions: Required<FormatterOptions>;
76
+ protected formatterOptions: Required<Omit<FormatterOptions, 'spacing'>> & Pick<FormatterOptions, 'spacing'>;
77
+ /** Present only for the opt-in rational timeline. */
78
+ private proportional?;
73
79
  protected modifierContexts: AlignmentModifierContexts[];
74
80
  protected voices: Voice[];
75
81
  protected lossHistory: number[];
@@ -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
  }
@@ -14,6 +14,8 @@ export * from './curve';
14
14
  export * from './dot';
15
15
  export * from './easyscore';
16
16
  export * from './element';
17
+ export * from './engravinggeometry';
18
+ export * from './engravingprofile';
17
19
  export * from './factory';
18
20
  export * from './font';
19
21
  export * from './flag';
@@ -5,6 +5,7 @@ export declare class KeySignature extends StaveModifier {
5
5
  static get CATEGORY(): string;
6
6
  protected paddingForced: boolean;
7
7
  protected formatted?: boolean;
8
+ protected clefOverride?: string;
8
9
  protected cancelKeySpec?: string;
9
10
  protected accList: {
10
11
  type: string;
@@ -38,6 +39,8 @@ export declare class KeySignature extends StaveModifier {
38
39
  }[]): void;
39
40
  getPadding(index: number): number;
40
41
  getWidth(): number;
42
+ /** Override staff clef for an inline signature following an inline clef change. */
43
+ setClef(clef?: string): this;
41
44
  setKeySig(keySpec: string, cancelKeySpec?: string, alterKeySpec?: string[]): this;
42
45
  alterKey(alterKeySpec: string[]): this;
43
46
  protected convertToAlterAccList(alterKeySpec: string[]): void;
@@ -4,7 +4,7 @@ import { Note } from './note';
4
4
  export declare class KeySigNote extends Note {
5
5
  static get CATEGORY(): string;
6
6
  protected keySignature: KeySignature;
7
- constructor(keySpec: string, cancelKeySpec?: string, alterKeySpec?: string[]);
7
+ constructor(keySpec: string, cancelKeySpec?: string, alterKeySpec?: string[], clef?: string);
8
8
  addToModifierContext(mc: ModifierContext): this;
9
9
  preFormat(): this;
10
10
  draw(): void;
@@ -45,6 +45,10 @@ export declare class ModifierContext {
45
45
  getRightShift(): number;
46
46
  /** Ties clear nearby modifiers, but must not start beyond a lyric's text box. */
47
47
  getRightShiftForTie(): number;
48
+ private measuredTopLines;
49
+ private measuredBottomLines;
50
+ /** Keep the line allowance for other marks when using actual annotation ink bounds. */
51
+ getUnmeasuredTextLines(above: boolean): number;
48
52
  getState(): ModifierContextState;
49
53
  getMetrics(): ModifierContextMetrics;
50
54
  preFormat(): void;
@@ -132,6 +132,8 @@ export declare abstract class Note extends Tickable {
132
132
  addStroke(index: number, stroke: Stroke): this;
133
133
  /** Get the target stave. */
134
134
  getStave(): Stave | undefined;
135
+ /** Release a staged stave assignment when managed composition fails. */
136
+ clearStave(): this;
135
137
  /** Check and get the target stave. */
136
138
  checkStave(): Stave;
137
139
  /** Set the target stave. */