@k-l-lambda/lilylet 0.1.68 → 0.1.70

package/source/lilylet/abcDecoder.ts

@@ -37,7 +37,9 @@ import {
 	MarkupEvent,
 	DynamicEvent,
 	Placement,
+	InstrumentName,
 } from "./types";
+import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
 
 
 // ============ Constants ============
@@ -395,6 +397,9 @@ const convertClef = (clefStr: string): Clef | undefined => {
 	// Split off an optional ABC octave shift suffix: "treble-8", "bass+8", "treble-15".
 	// ABC: "-N" lowers the sounding pitch (small N drawn below), "+N" raises it.
 	// LilyPond/Lilylet: "_N" = below, "^N" = above. Translate the sign accordingly.
+	// (Only octave amounts 8/15 are handled here; the Lilylet "_N"/"^N" clef suffix
+	// itself accepts arbitrary diatonic intervals — see meiEncoder.resolveClef — and a
+	// voice's transpose= property is folded into the same suffix via transposeClefSuffix.)
 	const shift = clefStr?.match(/^(.*?)([+-])(8|15)$/);
 	const base = shift ? shift[1] : clefStr;
 	let resolved: string | undefined;
@@ -408,6 +413,29 @@ const convertClef = (clefStr: string): Clef | undefined => {
 	return resolved as Clef;
 };
 
+/**
+ * Fold an ABC voice `transpose=N` property (a written→sounding shift in
+ * SEMITONES) into the Lilylet clef-suffix form `_M` / `^M`, where M is a
+ * diatonic interval number. ABC carries only semitones, so the diatonic
+ * interval is approximated by the nearest scale-step count
+ * (steps = round(semi * 7/12), interval number = |steps| + 1); `_` lowers,
+ * `^` raises. The Lilylet→MEI encoder later expands the suffix back into
+ * trans.diat / trans.semi (see meiEncoder.resolveClef). This is exact when the
+ * semitone count is a major/perfect interval (e.g. -2, -9, +2, ±12) and a
+ * nearest-interval approximation otherwise.
+ */
+const transposeClefSuffix = (clef: Clef | undefined, semitones: number): Clef | undefined => {
+	if (!clef || !semitones) return clef;
+	// A clef that already carries an octave suffix (treble_8 etc.) is left as-is;
+	// stacking another shift on top is not meaningful for ABC sources.
+	if (/[_^]\d+$/.test(clef as string)) return clef;
+	const steps = Math.round((semitones * 7) / 12);
+	if (steps === 0) return clef;
+	const num = Math.abs(steps) + 1;
+	const suffix = (steps < 0 ? "_" : "^") + num;
+	return (clef + suffix) as Clef;
+};
+
 /**
  * Convert ABC barline to Lilylet barline style
  */
@@ -516,6 +544,161 @@ const parseScoreLayout = (
 };
 
 
+/**
+ * Translate an ABC %%score layout into the equivalent lilylet staves expression.
+ *
+ * The two models differ in their leaf unit: ABC %%score is VOICE-leaf (an arc `( … )`
+ * collapses several voices onto one staff), whereas lilylet staves is STAFF-leaf. So
+ * each ABC staff becomes exactly one lilylet staff id, named (per spec) by the FIRST
+ * voice token inside its arc.
+ *
+ * Bracket mapping (ABC → lilylet):
+ *   ( … )  arc    → one staff leaf (id = first voice)         e.g. (1 3) → "1"
+ *   bare   leaf   → one staff leaf (id = that voice)          e.g. 7     → "7"
+ *   { … }  curly  → brace (grand staff)                       → { … }
+ *   [ … ]  square → bracket (orchestral)                      → < … >
+ *
+ * Conjunction between two siblings: a trailing `|` in %%score means barlines run through
+ * the two staves, mapped to the solid conjunction `-`; otherwise the blank `,` is used.
+ */
+const abcLayoutToStaves = (layout: ABC.StaffGroup[]): string | null => {
+	// First voice token under a node (the staff's lilylet id).
+	const firstVoice = (node: ABC.StaffGroup | string): string | null => {
+		if (typeof node === "string") return node;
+		for (const item of node.items || []) {
+			const v = firstVoice(item);
+			if (v !== null) return v;
+		}
+		return null;
+	};
+
+	// A node is a single staff (an arc, or a bare leaf) iff it has no curly/square nesting.
+	const isStaffLeaf = (node: ABC.StaffGroup | string): boolean => {
+		if (typeof node === "string") return true;
+		if (node.bound === "curly" || node.bound === "square") return false;
+		// arc or unbounded: a staff only if every descendant is too (no nested groups)
+		return (node.items || []).every(isStaffLeaf);
+	};
+
+	const emit = (node: ABC.StaffGroup | string): string => {
+		if (isStaffLeaf(node)) return firstVoice(node) || "";
+
+		const group = node as ABC.StaffGroup;
+		const open = group.bound === "curly" ? "{" : "<";   // square → bracket <>, curly → brace {}
+		const close = group.bound === "curly" ? "}" : ">";
+
+		const items = group.items || [];
+		let inner = "";
+		items.forEach((item, i) => {
+			inner += emit(item);
+			if (i < items.length - 1) {
+				const conj = (item as ABC.StaffGroup).barThruAfter ? "-" : ",";
+				inner += conj;
+			}
+		});
+		return `${open}${inner}${close}`;
+	};
+
+	const tops = layout.map((top, i) => {
+		let s = emit(top);
+		// A bare top-level staff leaf (e.g. the `9` in `[ … ] 9 [ … ]`) still occupies a slot;
+		// emit() already yields its id with no wrapper, which is the desired output.
+		return { s, barThru: !!top.barThruAfter, isLast: i === layout.length - 1 };
+	});
+
+	let out = "";
+	tops.forEach((t, i) => {
+		out += t.s;
+		if (i < tops.length - 1) out += t.barThru ? " - " : " ";
+	});
+
+	out = out.trim();
+	return out.length > 0 ? out : null;
+};
+
+
+/**
+ * Translate ABC voice instrument names (V:n nm="…" snm="…") into a lilylet `instruments`
+ * map keyed by staff-layout group key.
+ *
+ * ABC names sit on individual voices; lilylet staves are staff-leaf (an arc's first voice
+ * is the staff id). So we first collect a per-staff name from the staff-id voice. Then,
+ * per the user's rule: if a GROUP carries an instrument only on its first staff and the
+ * rest of the group is unnamed, the name belongs to the whole group — hoist it to the
+ * group key and drop it from the leaf. This matches engraving convention (one bracketed
+ * section, e.g. "Violini", named once for the group rather than on its top staff).
+ *
+ * `voiceInstr` maps an ABC voice number to its {name, shortName}. The layout's staff ids
+ * are arc-first voice numbers, so a staff id "5" looks up voice 5's name.
+ */
+const abcInstrumentsToLilylet = (
+	stavesCode: string,
+	voiceInstr: Map<number, InstrumentName>,
+): { [key: string]: InstrumentName } | null => {
+	const layout = parseStaffLayout(stavesCode);
+	const result: { [key: string]: InstrumentName } = {};
+
+	// Per-staff instrument, keyed by staff id (the arc-first voice number as a string).
+	const staffInstr = new Map<string, InstrumentName>();
+	for (const id of layout.staffIds) {
+		const v = parseInt(id, 10);
+		if (!isNaN(v) && voiceInstr.has(v)) staffInstr.set(id, voiceInstr.get(v)!);
+	}
+
+	// First staff id under a group (in layout order).
+	const firstStaffId = (group: StaffGroup): string | undefined => {
+		if (group.staff) return group.staff;
+		for (const sub of group.subs || []) {
+			const id = firstStaffId(sub);
+			if (id !== undefined) return id;
+		}
+		return undefined;
+	};
+
+	// All staff ids under a group except the first.
+	const restStaffIds = (group: StaffGroup): string[] => {
+		const all: string[] = [];
+		const collect = (g: StaffGroup) => {
+			if (g.staff) all.push(g.staff);
+			(g.subs || []).forEach(collect);
+		};
+		collect(group);
+		return all.slice(1);
+	};
+
+	// Walk groups top-down; hoist a first-staff-only name onto the group, else keep leaves.
+	const walk = (group: StaffGroup) => {
+		const isLeaf = !!group.staff && (!group.subs || group.subs.length === 0);
+		if (isLeaf) {
+			// A plain leaf keeps its own name (assigned in the flush pass below).
+			return;
+		}
+
+		const first = firstStaffId(group);
+		const firstInstr = first !== undefined ? staffInstr.get(first) : undefined;
+		const rest = restStaffIds(group);
+		const restNamed = rest.some(id => staffInstr.has(id));
+
+		// Group with a real grouping symbol, named only on its first staff → hoist.
+		const hasSymbol = group.type !== StaffGroupType.Default;
+		if (hasSymbol && firstInstr && !restNamed && group.key !== undefined) {
+			result[group.key] = firstInstr;
+			staffInstr.delete(first!);  // consumed by the group
+			return;  // children below the hoisted name carry nothing
+		}
+
+		for (const sub of group.subs || []) walk(sub);
+	};
+
+	walk(layout.group);
+
+	// Flush any per-staff names that weren't hoisted onto a group.
+	for (const [id, instr] of staffInstr) result[id] = instr;
+
+	return Object.keys(result).length > 0 ? result : null;
+};
+
+
 // ============ Marks/Decorations Conversion ============
 
 const convertArticulationMark = (artName: string): Mark | undefined => {
@@ -768,7 +951,7 @@ const processBarPatch = (
 
 		// Grace notes
 		if ((term as any).grace) {
-			const graceEvents = convertGraceEvents(term as any, unitLength);
+			const graceEvents = convertGraceEvents(term as any, unitLength, pitchCtx);
 			events.push(...graceEvents);
 			i++;
 			continue;
@@ -955,7 +1138,8 @@ const convertEventTerm = (
  */
 const convertGraceEvents = (
 	graceTerm: any,
-	unitLength: { numerator: number; denominator: number }
+	unitLength: { numerator: number; denominator: number },
+	pitchCtx?: PitchContext
 ): NoteEvent[] => {
 	const events: NoteEvent[] = [];
 	if (!graceTerm.events) return events;
@@ -968,7 +1152,7 @@ const convertGraceEvents = (
 
 			const pitches = chord.pitches.filter((p: ABC.Pitch) =>
 				p.phonet !== "z" && p.phonet !== "Z" && p.phonet !== "x"
-			).map(convertPitch);
+			).map((p: ABC.Pitch) => convertPitch(p, pitchCtx));
 
 			if (pitches.length === 0) continue;
 
@@ -1102,7 +1286,17 @@ const decodeTune = (tune: ABC.Tune, options: DecodeOptions = {}): LilyletDoc =>
 						properties: voiceValue?.properties,
 					});
 					if (clefStr) {
-						const clef = convertClef(clefStr);
+						let clef = convertClef(clefStr);
+						// Fold a voice transpose= (semitones) into the clef suffix so it
+						// survives to MEI as trans.diat/trans.semi (transposing instruments
+						// like "Clarinet transpose=-2", "Horn transpose=-9").
+						const transposeRaw = (voiceValue as any)?.properties?.transpose;
+						const transposeSemi = typeof transposeRaw === "number"
+							? transposeRaw
+							: (transposeRaw != null ? Number(transposeRaw) : NaN);
+						if (clef && Number.isFinite(transposeSemi) && transposeSemi !== 0) {
+							clef = transposeClefSuffix(clef, transposeSemi);
+						}
 						if (clef) voiceClefs.set(voiceId, clef);
 					}
 				}
@@ -1114,6 +1308,36 @@ const decodeTune = (tune: ABC.Tune, options: DecodeOptions = {}): LilyletDoc =>
 	// Parse score layout
 	const scoreLayout = parseScoreLayout(headers);
 
+	// Translate the ABC %%score layout into a lilylet staves expression (staff-leaf model).
+	const layoutHeader = headers.find((h: any) => h.staffLayout);
+	if (layoutHeader) {
+		const staves = abcLayoutToStaves((layoutHeader as any).staffLayout);
+		if (staves) metadata.staves = staves;
+
+		// Translate per-voice nm/snm into a lilylet instruments map. Collect names by ABC
+		// voice number (the staff id is the arc-first voice), then let abcInstrumentsToLilylet
+		// apply the first-staff-only → whole-group hoisting rule.
+		if (metadata.staves) {
+			const voiceInstr = new Map<number, InstrumentName>();
+			for (const [vid, config] of voiceConfigs) {
+				const props = config.properties;
+				if (!props) continue;
+				const name = props.nm ?? props.name;
+				if (typeof name !== "string" || !name.length) continue;
+				const v = typeof vid === "number" ? vid : parseInt(String(vid), 10);
+				if (isNaN(v)) continue;
+				const short = props.snm ?? props.sname;
+				voiceInstr.set(v, typeof short === "string" && short.length
+					? { name, shortName: short }
+					: { name });
+			}
+			if (voiceInstr.size > 0) {
+				const instruments = abcInstrumentsToLilylet(metadata.staves, voiceInstr);
+				if (instruments) metadata.instruments = instruments;
+			}
+		}
+	}
+
 	// Group measures by voice
 	// ABC measures contain BarPatches, each with a voice control V:n
 	const measures = body.measures;