tonus 0.1.8 → 0.5.0

package/dist/engines/score/emitters/svg.d.ts

@@ -0,0 +1,143 @@
+import type { ChantTabulaRow } from "../tabula.js";
+import type { Chant } from "../../chant/types.js";
+import type { LyricRun } from "../types.js";
+import { type AccidentalMode, type CentsBaseline } from "./accidentals.js";
+import { type TrackData, type TrackName } from "./tracks.js";
+/** A font face to embed into the SVG itself: the CALLER's bytes, base64.
+ * tonus ships no font files — it is a conduit for data the consumer supplies,
+ * so the consumer also carries the face's license terms. */
+export interface FontEmbed {
+    base64: string;
+    format?: "opentype" | "truetype" | "woff" | "woff2";
+}
+/** One text role's face: a family string, or a family with weight, a size
+ * factor (the "bit of tweaks" a display hand needs — e.g. a Gothic lyric face
+ * usually wants scale ~1.15 to match the serif's apparent size), and an
+ * optional `embed`. Without `embed`, the SVG carries a font-family REFERENCE
+ * and the host page supplies the face (@font-face); with it, the face rides
+ * inside the SVG's own <style> and the file is self-contained. */
+export type FontSlot = string | {
+    family: string;
+    weight?: number;
+    scale?: number;
+    embed?: FontEmbed;
+};
+/** Per-role faces. Anything unset falls back to `fontFamily` (the house serif).
+ *
+ * The four roles are the four kinds of text a chant page sets, and they are
+ * deliberately separate: a book's dropcap is very often NOT its lyric face —
+ * a Lombardic or uncial initial against a text hand — which is exactly the
+ * pairing the printed books use. */
+export interface FontSpec {
+    dropcap?: FontSlot;
+    title?: FontSlot;
+    annotation?: FontSlot;
+    lyric?: FontSlot;
+}
+/** The ink. Every value reaches the SVG as a CSS custom property with the
+ * theme's own value as the fallback — `var(--tonus-note, #111)` — so a host
+ * stylesheet can retheme a rendered chant without re-rendering it, while a
+ * file opened on its own still carries the colours it was drawn with. */
+export interface ThemeColors {
+    /** Noteheads, stems, episemata, lyric text. */
+    note?: string;
+    /** The four staff lines. */
+    staffLine?: string;
+    /** Liturgical red: the dropcap, rubrics, and the annotation block. */
+    rubrica?: string;
+}
+export interface Theme {
+    fonts?: FontSpec;
+    colors?: ThemeColors;
+}
+interface ResolvedFont {
+    family: string;
+    weight: number | null;
+    scale: number;
+    embed: FontEmbed | null;
+}
+/** One @font-face rule per embedded (family, weight); deduped across slots. */
+export declare function fontFaceCss(fonts: ResolvedFont[]): string;
+/** The emitter's options — INTERNAL. `inscriptio` is the public surface, and
+ *  it is the only caller: the measurements below are no longer settable from
+ *  outside, and a default named here is the emitter's own, not a promise to a
+ *  caller. `scale` is the public control, resolved to `staffHeight` before it
+ *  arrives (see inscriptio.ts). */
+export interface SvgOpts {
+    /** Height of the 4-line staff in px (line 1 to line 4). Default 40.
+     *  Set from the public `scale`; not settable directly. */
+    staffHeight?: number;
+    /** Notehead/clef size relative to the SMuFL nominal (1 = fill the space). Default 0.7. */
+    noteScale?: number;
+    /** Horizontal padding / left margin in px. Default 12. */
+    padding?: number;
+    /** Colour of staff lines. Defaults to `noteColor`. */
+    staffLineColor?: string;
+    /** Colour of notation glyphs. Default "#111". */
+    noteColor?: string;
+    /** Font-family for lyric text. Default a serif stack. */
+    fontFamily?: string;
+    fonts?: FontSpec;
+    /** Wrap systems to this px width. Absent = a single system. */
+    width?: number;
+    /** Vertical gap between systems, px. Defaults to 0.6 × staffHeight, so it
+     *  follows the scale rather than staying a fixed 24px under a large chant. */
+    systemGap?: number;
+    /** Draw a custos (line-end guide note) at each system break. Defaults to
+     *  true whenever `width` wraps — a chant book sets one at every line's end,
+     *  so wrapping is the condition, not a separate choice. */
+    custos?: boolean;
+    /** A headline above the score. */
+    title?: string;
+    /** A right-corner annotation line (feast, page cite). */
+    rubric?: string;
+    /** Derive the rubric block from chant meta (genus · modus · book). */
+    annotation?: "auto";
+    /** Draw a rubricated initial from the first lyric; the first system indents. */
+    dropcap?: boolean;
+    /** The liturgical red for dropcap and annotations. Default a sober red. */
+    rubricaColor?: string;
+    /** The intonation channel: standard accidentals, HEJI commas, or cents labels. */
+    accidentals?: AccidentalMode;
+    /** Baseline for the cents channel; the chant's home intonation by default. */
+    centsBaseline?: CentsBaseline;
+    /** Analysis tracks to draw beneath each system; they stack in a fixed order. */
+    tracks?: readonly TrackName[];
+    /** Score-level analysis the tracks consume — supplied by inscriptio. */
+    trackData?: TrackData;
+}
+/** The `annotation: "auto"` mark, derived from chant meta and stacked as the
+ * books set it ("Intr." over "8.") — shared by both species. */
+export declare function autoRubricLines(chant: Chant): string[];
+/**
+ * A syllable's lyric as SVG text content: styled runs become <tspan>s
+ * (italic, bold, small caps, rubric color); a plain lyric stays a bare
+ * escaped string. Shared by both species — callers pass runs whose
+ * concatenation equals the plain text they measure with.
+ */
+export declare function lyricMarkup(runs: LyricRun[] | undefined, plain: string, rubricaColor: string): string;
+/**
+ * One entry per tabula row, in tabula order — the TRACK CONTRACT. Analysis
+ * overlays (chironomy, tonarium) consume score data + this geometry to place
+ * marks against notes, without scraping the SVG for coordinates.
+ */
+export interface NoteGeometry {
+    phraseIndex: number;
+    syllableIndex: number;
+    neumeGroup: number;
+    noteIndex: number;
+    /** Which system (staff line) the note landed in — 0 when nothing wraps. */
+    system: number;
+    /** Notehead anchor in svg user units. */
+    x: number;
+    y: number;
+    /** The system's top offset within the svg — 0 in the first system. */
+    systemY: number;
+}
+export interface SvgResult {
+    svg: string;
+    geometry: NoteGeometry[];
+}
+export declare function toSvg(rows: ChantTabulaRow[], chant: Chant, options?: SvgOpts): SvgResult;
+export {};
+//# sourceMappingURL=svg.d.ts.map