feat: extend direction text formatting in mx::api and unify the enclosure enum

src/include/mx/api/ApiCommon.h

@@ -71,9 +71,11 @@ enum class MeasureNumbering
     system
 };
 
-// The <measure-numbering system="..."> attribute: whether this part's measure numbers are also,
-// or only, associated with the system (as opposed to just this part). unspecified means the
-// attribute is absent.
+// Whether an item is associated with the system rather than only with the part it appears in --
+// the system attribute of <measure-numbering> (MeasureData) and of <direction> and <harmony>
+// (DirectionData). only... means the item is drawn on the top or bottom part of the system instead
+// of this part; also... means it is drawn on both. unspecified means the attribute is absent.
+// onlyBottom and alsoBottom are measure-numbering only; MusicXML has no bottom-of-system direction.
 enum class SystemRelation
 {
     unspecified,
@@ -83,6 +85,31 @@ enum class SystemRelation
     alsoTop,
     alsoBottom
 };
+
+// The shape drawn around a piece of text or a symbol -- MusicXML's enclosure attribute, carried by
+// RehearsalData, WordsData, SymbolData and PercussionData. unspecified means the attribute is
+// absent, which draws no enclosure; none states explicitly that there is none. A bracket is a
+// rectangle with the bottom line missing, as is common in jazz notation, and an invertedBracket is
+// one with the top line missing.
+enum class Enclosure
+{
+    unspecified,
+    rectangle,
+    square,
+    oval,
+    circle,
+    bracket,
+    invertedBracket,
+    triangle,
+    diamond,
+    pentagon,
+    hexagon,
+    heptagon,
+    octagon,
+    nonagon,
+    decagon,
+    none
+};
 } // namespace api
 } // namespace mx
 

src/include/mx/api/ChordData.h

@@ -251,6 +251,13 @@ class ChordData
     ChordKind chordKind;
     std::string text;
     Bool useSymbols;
+    // How the chord's degree alterations (the 'extensions' below) are laid out next to the chord
+    // symbol. stackDegrees stacks them vertically instead of running them left to right;
+    // parenthesesDegrees wraps all of them in parentheses, e.g. C7(#9b13). These are the MusicXML
+    // stack-degrees and parentheses-degrees attributes; unspecified leaves the choice to the
+    // notation software rendering the score.
+    Bool stackDegrees;
+    Bool parenthesesDegrees;
     Step bass;
     int bassAlter;
     // The MusicXML <inversion> (0 = root position, 1 = first inversion, ...). Present only when
@@ -279,6 +286,8 @@ MXAPI_EQUALS_MEMBER(numeralMode)
 MXAPI_EQUALS_MEMBER(chordKind)
 MXAPI_EQUALS_MEMBER(text)
 MXAPI_EQUALS_MEMBER(useSymbols)
+MXAPI_EQUALS_MEMBER(stackDegrees)
+MXAPI_EQUALS_MEMBER(parenthesesDegrees)
 MXAPI_EQUALS_MEMBER(bass)
 MXAPI_EQUALS_MEMBER(bassAlter)
 MXAPI_EQUALS_MEMBER(inversion)

src/include/mx/api/ClefData.h

@@ -21,6 +21,11 @@ enum class ClefSymbol
     jianpu
 };
 
+// Where a clef sits relative to its measure. A clef at the start of a measure normally prints
+// before the barline; beforeBarline and afterBarline choose between the two, which matters for cue
+// clefs and for the clef that resumes after a repeated section. midMeasure describes a clef change
+// partway through the measure, positioned by tickTimePosition. unspecified leaves the choice to the
+// notation program.
 enum class ClefLocation
 {
     unspecified,
@@ -53,6 +58,12 @@ class ClefData
     bool isOctaveChangeSpecified;
     int tickTimePosition;
     ClefLocation location;
+    // Marks a supplementary clef placed on the staff alongside the regular one - a cue clef, or a
+    // second clef in effect at the same time. MusicXML writes this as clef@additional="yes"; such a
+    // clef sits at a non-standard line position, is not restated at the start of each system, and
+    // notation software disregards its line. unspecified (the default) omits the attribute, which
+    // describes an ordinary clef.
+    Bool additional;
     // Visibility of the clef via the MusicXML print-object attribute.
     // unspecified -> omit the attribute, yes/no -> write print-object verbatim.
     Bool printObject;
@@ -86,6 +97,7 @@ MXAPI_EQUALS_MEMBER(octaveChange)
 MXAPI_EQUALS_MEMBER(isOctaveChangeSpecified)
 MXAPI_EQUALS_MEMBER(tickTimePosition)
 MXAPI_EQUALS_MEMBER(location)
+MXAPI_EQUALS_MEMBER(additional)
 MXAPI_EQUALS_MEMBER(printObject)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(ClefData);

src/include/mx/api/DirectionData.h

@@ -28,6 +28,14 @@ struct DirectionData
     int tickTimePosition;
     Placement placement;
 
+    // The system attribute of <direction> and <harmony>: content that belongs to the whole system
+    // rather than to this part alone, such as a tempo mark drawn once above the top staff. onlyTop
+    // draws it only on the top part of the system, alsoTop on both this part and the top part, and
+    // none states explicitly that it belongs to this part alone. One value covers the direction
+    // types and the chords held here; both elements are written with it. SystemRelation::onlyBottom
+    // and ::alsoBottom exist only for measure numbering; either one here writes no attribute.
+    SystemRelation systemRelation;
+
     // The source's <offset>, in divisions, or absent when it had none. An <offset> nudges only
     // where the direction is *drawn*, shifting it away from the note it is anchored to; it does not
     // move that anchor. tickTimePosition holds the anchor -- the musical location the direction
@@ -73,9 +81,9 @@ struct DirectionData
     std::vector<FiguredBassData> figuredBasses;
 
     DirectionData()
-        : tickTimePosition{0}, placement{Placement::unspecified}, offset{}, voice{VALUE_UNSPECIFIED},
-          isStaffValueSpecified{true}, isSoundDataSpecified{false}, soundData{}, directionTypes{}, chords{},
-          figuredBasses{}
+        : tickTimePosition{0}, placement{Placement::unspecified}, systemRelation{SystemRelation::unspecified}, offset{},
+          voice{VALUE_UNSPECIFIED}, isStaffValueSpecified{true}, isSoundDataSpecified{false}, soundData{},
+          directionTypes{}, chords{}, figuredBasses{}
     {
     }
 };
@@ -89,6 +97,7 @@ inline bool isDirectionDataEmpty(const DirectionData &directionData)
 MXAPI_EQUALS_BEGIN(DirectionData)
 MXAPI_EQUALS_MEMBER(tickTimePosition)
 MXAPI_EQUALS_MEMBER(placement)
+MXAPI_EQUALS_MEMBER(systemRelation)
 MXAPI_EQUALS_MEMBER(offset)
 MXAPI_EQUALS_MEMBER(voice)
 MXAPI_EQUALS_MEMBER(isStaffValueSpecified)

src/include/mx/api/MeasureData.h

@@ -13,6 +13,7 @@
 #include "mx/api/TransposeData.h"
 
 #include <map>
+#include <optional>
 #include <string>
 
 namespace mx
@@ -51,6 +52,15 @@ class MeasureData
     // about measure numbering can be defined using the measure-numbering element.
     std::string number;
 
+    // The measure number as it should appear on the page, when that differs from the 'number'
+    // above. 'number' identifies the measure (and aligns it with the same measure in other parts),
+    // while this is purely what the engraver prints. Set it when the printed numbering does not
+    // follow the identifying numbering -- a second ending that restarts at 8, an editor's numbering
+    // like "12a", or a rehearsal-driven relabeling. Leave it absent and the printed number is the
+    // 'number' value. An empty string is not written; use implicit = Bool::yes to suppress the
+    // number entirely, which is also what makes engravers ignore this field.
+    std::optional<std::string> displayedNumber;
+
     // The measure-numbering-value type describes how measure numbers are displayed on this part:
     // no numbers, numbers every measure, or numbers every system.
     MeasureNumbering measureNumbering;
@@ -65,6 +75,10 @@ class MeasureData
     // The <measure-numbering system="..."> attribute; see SystemRelation.
     SystemRelation measureNumberingSystemRelation;
 
+    // Which staff of the part the measure number is vertically positioned against, zero-based from
+    // the top staff. Meaningful only when measureNumbering != unspecified. Absent means the top staff.
+    std::optional<int> measureNumberingStaffIndex;
+
     // a number greater than zero indicates that this measure is the beginning of a mult-measure
     // rest that will last for the indicated number of measures. following measures will be affected
     // by this.
@@ -112,10 +126,12 @@ MXAPI_EQUALS_MEMBER(staves)
 MXAPI_EQUALS_MEMBER(timeSignature)
 MXAPI_EQUALS_MEMBER(staffTimeSignatures)
 MXAPI_EQUALS_MEMBER(number)
+MXAPI_EQUALS_MEMBER(displayedNumber)
 MXAPI_EQUALS_MEMBER(measureNumbering)
 MXAPI_EQUALS_MEMBER(measureNumberingMultipleRestAlways)
 MXAPI_EQUALS_MEMBER(measureNumberingMultipleRestRange)
 MXAPI_EQUALS_MEMBER(measureNumberingSystemRelation)
+MXAPI_EQUALS_MEMBER(measureNumberingStaffIndex)
 MXAPI_EQUALS_MEMBER(multiMeasureRest)
 MXAPI_EQUALS_MEMBER(multiMeasureRestUseSymbols)
 MXAPI_EQUALS_MEMBER(implicit)

src/include/mx/api/NoteData.h

@@ -13,6 +13,7 @@
 #include "mx/api/PrintData.h"
 
 #include <optional>
+#include <string>
 #include <vector>
 
 namespace mx
@@ -132,6 +133,22 @@ class NoteData
     bool isCue;
 
     Notehead notehead;
+
+    // The <notehead> element's filled attribute: whether the notehead shape is drawn solid or
+    // hollow. Leave it unspecified to get MusicXML's default, which follows the note's duration
+    // (hollow for a half note and longer, solid for shorter). Set yes or no to override that,
+    // for example a solid whole note in a rhythm-notation part.
+    Bool noteheadFilled;
+
+    // The <notehead> element's smufl attribute: the canonical SMuFL glyph name to draw for this
+    // notehead, for example "noteheadSlashHorizontalEnds". It names a glyph directly, so a
+    // notation program can draw a notehead that MusicXML has no value for -- pair it with
+    // Notehead::other -- or narrow one that MusicXML names only broadly, such as
+    // Notehead::cluster. Note-name noteheads (the SMuFL ranges U+E150-U+E1AF and U+EEE0-U+EEFF)
+    // are not written this way; MusicXML spells those out in <notehead-text>. An empty string
+    // names no glyph and is written the same as leaving this empty.
+    std::optional<std::string> noteheadSmufl;
+
     PitchData pitchData; // step, alter, octave, accidental, etc
     int userRequestedVoiceNumber;
 
@@ -196,6 +213,9 @@ MXAPI_EQUALS_MEMBER(tieLetRing)
 MXAPI_EQUALS_MEMBER(isGrace)
 MXAPI_EQUALS_MEMBER(isCue)
 MXAPI_EQUALS_MEMBER(graceSlash)
+MXAPI_EQUALS_MEMBER(notehead)
+MXAPI_EQUALS_MEMBER(noteheadFilled)
+MXAPI_EQUALS_MEMBER(noteheadSmufl)
 MXAPI_EQUALS_MEMBER(pitchData)
 MXAPI_EQUALS_MEMBER(userRequestedVoiceNumber)
 MXAPI_EQUALS_MEMBER(writeStaffNumber)

src/include/mx/api/PercussionData.h

@@ -464,27 +464,6 @@ class PercussionDataChoice
 
 MXAPI_NOT_EQUALS_AND_VECTORS(PercussionDataChoice);
 
-// How a percussion pictogram is enclosed, MusicXML's enclosure attribute on <percussion>.
-enum class PercussionEnclosure
-{
-    unspecified,
-    rectangle,
-    square,
-    oval,
-    circle,
-    bracket,
-    invertedBracket,
-    triangle,
-    diamond,
-    pentagon,
-    hexagon,
-    heptagon,
-    octagon,
-    nonagon,
-    decagon,
-    none
-};
-
 // A percussion pictogram, MusicXML's <percussion> element: a symbol for an unpitched instrument
 // or the implement striking it, used in percussion parts and legends. Several PercussionData in
 // one direction read as a group (for example a membrane pictogram followed by a beater).
@@ -495,13 +474,17 @@ class PercussionData
 {
   public:
     PercussionDataChoice choice;
-    PercussionEnclosure enclosure;
+
+    // A shape drawn around the pictogram. Enclosure::unspecified draws no enclosure;
+    // Enclosure::none states explicitly that there is none.
+    Enclosure enclosure;
+
     PositionData positionData;
     FontData fontData;
     std::optional<ColorData> color;
     std::optional<std::string> id;
 
-    PercussionData() : choice{}, enclosure{PercussionEnclosure::unspecified}, positionData{}, fontData{}, color{}, id{}
+    PercussionData() : choice{}, enclosure{Enclosure::unspecified}, positionData{}, fontData{}, color{}, id{}
     {
     }
 };

src/include/mx/api/RehearsalData.h

@@ -6,25 +6,13 @@
 
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
+#include "mx/api/FontData.h"
 #include "mx/api/PositionData.h"
 
 namespace mx
 {
 namespace api
 {
-enum class RehearsalEnclosure
-{
-    unspecified,
-    rectangle,
-    square,
-    oval,
-    circle,
-    bracket,
-    triangle,
-    diamond,
-    none
-};
-
 class RehearsalData
 {
   public:
@@ -33,11 +21,20 @@ class RehearsalData
     bool isColorSpecified;
     ColorData colorData;
     FontData fontData;
-    RehearsalEnclosure enclosure;
+
+    // A shape drawn around the text. Enclosure::unspecified draws no enclosure; Enclosure::none
+    // states explicitly that there is none.
+    Enclosure enclosure;
+
+    // The `justify` attribute of `<rehearsal>`: how the mark's lines sit relative to each other
+    // when its text runs to more than one line. `unspecified` means the attribute is absent.
+    // Distinct from the `halign` attribute, which is carried in `positionData.horizontalAlignment`
+    // and says which edge of the text the position refers to; MusicXML defines both.
+    HorizontalAlignment justify;
 
     RehearsalData()
-        : text{}, positionData{}, isColorSpecified{false}, colorData{}, fontData{},
-          enclosure{RehearsalEnclosure::unspecified}
+        : text{}, positionData{}, isColorSpecified{false}, colorData{}, fontData{}, enclosure{Enclosure::unspecified},
+          justify{HorizontalAlignment::unspecified}
     {
     }
 };
@@ -49,6 +46,7 @@ MXAPI_EQUALS_MEMBER(isColorSpecified)
 MXAPI_EQUALS_MEMBER(colorData)
 MXAPI_EQUALS_MEMBER(fontData)
 MXAPI_EQUALS_MEMBER(enclosure)
+MXAPI_EQUALS_MEMBER(justify)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(RehearsalData);
 } // namespace api

src/include/mx/api/SymbolData.h

@@ -8,7 +8,6 @@
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
 #include "mx/api/PositionData.h"
-#include "mx/api/RehearsalData.h"
 
 #include <optional>
 #include <string>
@@ -32,11 +31,19 @@ class SymbolData
     FontData fontData;
     std::optional<ColorData> color;
 
-    // A shape drawn around the symbol. RehearsalEnclosure::unspecified draws no enclosure;
-    // RehearsalEnclosure::none states explicitly that there is none.
-    RehearsalEnclosure enclosure;
+    // A shape drawn around the symbol. Enclosure::unspecified draws no enclosure; Enclosure::none
+    // states explicitly that there is none.
+    Enclosure enclosure;
 
-    SymbolData() : smufl{}, positionData{}, fontData{}, color{}, enclosure{RehearsalEnclosure::unspecified}
+    // The `justify` attribute of `<symbol>`. `unspecified` means the attribute is absent. Distinct
+    // from the `halign` attribute, which is carried in `positionData.horizontalAlignment` and says
+    // which edge of the glyph the position refers to; MusicXML defines both on `<symbol>`, whose
+    // symbol-formatting attributes mirror the text-formatting ones on `<words>`.
+    HorizontalAlignment justify;
+
+    SymbolData()
+        : smufl{}, positionData{}, fontData{}, color{}, enclosure{Enclosure::unspecified},
+          justify{HorizontalAlignment::unspecified}
     {
     }
 };
@@ -47,6 +54,7 @@ MXAPI_EQUALS_MEMBER(positionData)
 MXAPI_EQUALS_MEMBER(fontData)
 MXAPI_EQUALS_MEMBER(color)
 MXAPI_EQUALS_MEMBER(enclosure)
+MXAPI_EQUALS_MEMBER(justify)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(SymbolData);
 } // namespace api