guidex 0.3.3 → 0.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.
@@ -1,6 +1,6 @@
1
1
  import { GuidoScript } from './guidoScript';
2
2
  import { SCORE_MARKERS } from './noteGroups';
3
- import { StyleSet, StyleSetName, SyllablePart } from './guidoStyles';
3
+ import { StyleSet, MarkDefinitions, StyleSetName, SyllablePart } from './guidoStyles';
4
4
  export { SCORE_MARKERS };
5
5
  /**
6
6
  * Special reciting notes: when such a note stands alone in a note group it
@@ -22,11 +22,20 @@ export declare const NOTE_MODIFIERS: string;
22
22
  /** Canvas text measurement, shared with the emitters (the Word export
23
23
  * measures the spacer character's natural advance for the unit width). */
24
24
  export declare function measure(text: string, font: string): number;
25
+ /** How far each staff line runs (issue #107). `all-but-last` fills every
26
+ * line but the last to the available width; `none` stops every line at its
27
+ * own notes; `all` fills every line to the available width, or acts as
28
+ * `longest` at natural width, where there is none; `longest` fills every
29
+ * line to the end of the score's longest line, its text included. */
30
+ export type StaffFill = 'all-but-last' | 'none' | 'all' | 'longest';
31
+ export declare const STAFF_FILLS: readonly StaffFill[];
25
32
  /** Options for one layout pass. All fields optional; defaults reproduce the
26
33
  * original Book Antiqua look (style set BNS). */
27
34
  export interface LayoutOptions {
28
- /** Named style set from STYLE_SETS (default: BNS) */
35
+ /** Named style set (default: BNS) */
29
36
  style?: StyleSetName;
37
+ /** Marks this score adds to its style set's */
38
+ marks?: MarkDefinitions;
30
39
  /** Lay out all text bold, measurements included */
31
40
  bold?: boolean;
32
41
  /** Text line size in px (default 18) */
@@ -42,6 +51,12 @@ export interface LayoutOptions {
42
51
  * accidental takes one less, never under 1. Held groups keep their
43
52
  * own join. */
44
53
  junctionDashes?: number;
54
+ /** How far each staff line runs (default `all-but-last`) */
55
+ staffFill?: StaffFill;
56
+ /** With `staffFill: 'longest'`: when the longest line ends within this
57
+ * many px of the available width, every line runs to the available
58
+ * width instead (default 0) */
59
+ staffFillSnapPx?: number;
45
60
  }
46
61
  /** A horizontal whitespace gap on the text line: the lead-in shared with
47
62
  * the clef, or the gap after a word-ending syllable. Both emitters fake it
@@ -62,6 +77,8 @@ export interface GapSegment {
62
77
  /** A dash connector centered between two syllables of the same word. */
63
78
  export interface ConnectorSegment {
64
79
  kind: 'connector';
80
+ /** The hyphen's look, when a `{…}` span runs on across it */
81
+ parts?: SyllablePart[];
65
82
  /** Each side pad's width in px (the DOM emitter's twin spacer spans) */
66
83
  pad: number;
67
84
  /** The full gap the dash centers in, px */
@@ -107,6 +124,8 @@ export interface WordSpaceSegment {
107
124
  * the line's text end and its notes end. */
108
125
  export interface LineEndDashSegment {
109
126
  kind: 'line-end-dash';
127
+ /** The hyphen's look, when a `{…}` span runs on across it */
128
+ parts?: SyllablePart[];
110
129
  /** Each side pad's width in px (the DOM emitter's twin spacer spans) */
111
130
  pad: number;
112
131
  dashWidth: number;
@@ -129,6 +148,13 @@ export interface LayoutTextLine {
129
148
  /** Whether the text line's last syllable ends its word; null when it
130
149
  * carries no syllable at all */
131
150
  lastWordEnd: boolean | null;
151
+ /** The hyphen after the text line's last syllable */
152
+ hyphen?: Hyphen;
153
+ }
154
+ /** A text hyphen: its look when it has one of its own, and its width. */
155
+ export interface Hyphen {
156
+ parts?: SyllablePart[];
157
+ width: number;
132
158
  }
133
159
  /** One rendered line pair's layout: the notes-line model and the text
134
160
  * line's ordered segments with their ideal absolute positions. Stacked
@@ -146,6 +172,8 @@ export interface LayoutLine {
146
172
  textCursor: number;
147
173
  /** Where the notes line ends (the notes width when the line closed) */
148
174
  notesEnd: number;
175
+ /** Where the staff ends: `notesEnd` plus any staff fill */
176
+ staffEnd: number;
149
177
  /** Whether the line's last syllable ends its word; null when the
150
178
  * line carries no syllable at all */
151
179
  lastWordEnd: boolean | null;
@@ -1,11 +1,20 @@
1
- import { ChantRunKind, StyleSetName } from './guidoStyles';
2
- /** One run of marked-up chant text: the rendered text plus what markup
3
- * produced it. An absent `kind` is plain text; `initial` marks the
4
- * `*…*` initial and can combine with a `kind`. */
1
+ import { GuidoScript, SyllableRole } from './guidoScript';
2
+ import { ChantRunKind, MarkDefinitions, PartStyle, StyleSetName } from './guidoStyles';
3
+ import { Mark, SpanProblem } from './textMarkup';
4
+ /** One run of marked-up chant text. `marks` are all its marks; `kind` the
5
+ * notation-fixed one among them, absent on plain text (derived from
6
+ * `marks`, kept for existing consumers); `initial` a `*…*` initial, which
7
+ * combines with a `kind`. `role` is what its syllable is for. */
5
8
  export interface ChantRun {
6
9
  text: string;
7
10
  kind?: ChantRunKind;
8
11
  initial?: boolean;
12
+ marks: Mark[];
13
+ role: SyllableRole;
14
+ }
15
+ /** A merged run, which says where its word ends. */
16
+ export interface ChantWordRun extends ChantRun {
17
+ wordEnd: boolean;
9
18
  }
10
19
  /** The runs of one syllable. */
11
20
  export interface ChantSyllable {
@@ -16,21 +25,55 @@ export interface ChantWord {
16
25
  syllables: ChantSyllable[];
17
26
  }
18
27
  export interface ChantMarkupOptions {
19
- /** The style set whose default script transforms apply, mirroring
20
- * what a score render does (BNS marks the first initial). Defaults
21
- * to DEFAULT_STYLE_SET; presentation differences between style sets
22
- * never reach the output. */
28
+ /** The roles to keep (default: all of them) */
29
+ roles?: readonly SyllableRole[];
30
+ }
31
+ /** The marked-up text of the script: its words, their syllables, and each
32
+ * syllable's runs, as written (letter case included) and the same in every
33
+ * style set. With `merge: 'word'`, a flat list instead: within a word,
34
+ * neighbouring runs with the same marks and role join, so `De` + `us` read
35
+ * as `Deus`. */
36
+ export declare function chantRuns(script: string, options?: ChantMarkupOptions & {
37
+ merge?: undefined;
38
+ }): ChantWord[];
39
+ export declare function chantRuns(script: string, options: ChantMarkupOptions & {
40
+ merge: 'word';
41
+ }): ChantWordRun[];
42
+ /** Options of `chantHtml`. */
43
+ export interface ChantHtmlOptions extends ChantMarkupOptions {
44
+ /** Put before every class name, so they cannot collide with the host
45
+ * page's (`gx-` gives `gx-liturgy`) */
46
+ classPrefix?: string;
47
+ }
48
+ /** The marked-up text as an HTML string: one span per marked run, classed
49
+ * with its kind, `initial` and any marks of its own, bare text otherwise.
50
+ * Syllables of a word concatenate and words join with single spaces —
51
+ * hyphenation is the consumer's job, and `chantRuns` has the syllable
52
+ * boundaries. Text is HTML-escaped. */
53
+ export declare function chantHtml(script: string, options?: ChantHtmlOptions): string;
54
+ /** A style set and a score's own marks, for the look of a mark. */
55
+ export interface MarkLookOptions {
23
56
  style?: StyleSetName;
57
+ marks?: MarkDefinitions;
24
58
  }
25
- /** The marked-up sung text of the script: its words, their syllables,
26
- * and each syllable's runs of notation-fixed kinds. Renders exactly the
27
- * text a score render would (including the style set's default script
28
- * transforms) with the style-set presentation stripped; letter case is
29
- * the raw text's, so a BNS-look consumer uppercases rubrics in CSS. */
30
- export declare function chantRuns(script: string, options?: ChantMarkupOptions): ChantWord[];
31
- /** The marked-up sung text as an HTML string: one span per kinded or
32
- * initial run, classed with the kind (and `initial`), bare text
33
- * otherwise. Syllables of a word concatenate and words join with single
34
- * spaces — hyphenation is the consumer's job, and `chantRuns` has the
35
- * syllable boundaries. Text is HTML-escaped. */
36
- export declare function chantHtml(script: string, options?: ChantMarkupOptions): string;
59
+ /** The resolved look of comma-separated marks (`red,sc`), for a host styling
60
+ * prose to match a score. */
61
+ export declare function chantTextStyle(marks: string, options?: MarkLookOptions): PartStyle;
62
+ /** A mark no style set or score defines, or a character a mark's font does
63
+ * not have. The text still renders, without that look or in a fallback
64
+ * font. */
65
+ export type MarkWarning = {
66
+ kind: 'mark';
67
+ mark: Mark;
68
+ text: string;
69
+ message: string;
70
+ } | {
71
+ kind: 'glyph';
72
+ char: string;
73
+ text: string;
74
+ message: string;
75
+ };
76
+ /** What is wrong with the script's text markup: malformed `{…}` spans,
77
+ * unknown marks, and characters the Liturgy font does not have, each once
78
+ * per syllable. */
79
+ export declare function markupWarnings(script: GuidoScript | string, options?: MarkLookOptions): (SpanProblem | MarkWarning)[];
@@ -1,3 +1,4 @@
1
+ import { StaffFill } from './chantLayout';
1
2
  import { StyleSetName } from './guidoStyles';
2
3
  import { SpacerChar } from './wordExport';
3
4
  /** Versioned localStorage key; an unknown version is ignored wholesale. */
@@ -21,6 +22,8 @@ export declare const MAX_WIDTH_PX_MAX = 1400;
21
22
  /** Declared range of the transpose slider. */
22
23
  export declare const JUNCTION_DASHES_MIN = 1;
23
24
  export declare const JUNCTION_DASHES_MAX = 8;
25
+ export declare const STAFF_FILL_SNAP_MIN = 0;
26
+ export declare const STAFF_FILL_SNAP_MAX = 60;
24
27
  export declare const TRANSPOSE_MIN = -6;
25
28
  export declare const TRANSPOSE_MAX = 6;
26
29
  /** The destination Word text size default (notes ride at twice it) and the
@@ -46,8 +49,6 @@ export interface WordCopySettings {
46
49
  export interface EditorSettings {
47
50
  style: StyleSetName;
48
51
  bold: boolean;
49
- /** The start-with-initial transform enabled. */
50
- initial: boolean;
51
52
  maxWidthPx: number;
52
53
  transpose: number;
53
54
  basePx: number;
@@ -58,6 +59,10 @@ export interface EditorSettings {
58
59
  notesCustom: boolean;
59
60
  /** Dashes in a normal junction between note groups. */
60
61
  junctionDashes: number;
62
+ /** How far each staff line runs. */
63
+ staffFill: StaffFill;
64
+ /** With `longest`: the distance from the max width that snaps to it. */
65
+ staffFillSnapPx: number;
61
66
  customColors: boolean;
62
67
  colorFg: string;
63
68
  colorAccent: string;
@@ -144,8 +149,6 @@ export declare const CHANTS_SCHEMA_VERSION = 1;
144
149
  export interface ChantPrefs {
145
150
  style: StyleSetName;
146
151
  bold: boolean;
147
- /** The start-with-initial transform enabled. */
148
- initial: boolean;
149
152
  basePx: number;
150
153
  decoupleNotes: boolean;
151
154
  /** The chant size while decoupled (the adopted 2× base or a typed one). */
@@ -153,6 +156,8 @@ export interface ChantPrefs {
153
156
  /** True once the user typed a chant size of their own. */
154
157
  notesCustom: boolean;
155
158
  junctionDashes: number;
159
+ staffFill: StaffFill;
160
+ staffFillSnapPx: number;
156
161
  transpose: number;
157
162
  }
158
163
  export interface SavedChant {
@@ -1,5 +1,8 @@
1
1
  import { EmptySlots, StanzaStack, StanzaWarning } from '../stanzas';
2
- import { StyleSetName } from '../guidoStyles';
2
+ import { MarkWarning } from '../chantMarkup';
3
+ import { SpanProblem } from '../textMarkup';
4
+ import { StaffFill } from '../chantLayout';
5
+ import { MarkDefinitions, StyleSetName } from '../guidoStyles';
3
6
  export declare const version: string;
4
7
  /** Line-breaking budget: a fixed pixel width, or 'auto' to fit the
5
8
  * target element (re-rendered on resize). `Infinity` (or any large
@@ -15,8 +18,15 @@ export interface EmbedOptions {
15
18
  style?: StyleSetName;
16
19
  bold?: boolean;
17
20
  textPx?: number;
21
+ /** Marks this score adds to its style set's */
22
+ marks?: MarkDefinitions;
18
23
  /** Dashes in a normal junction between note groups, in steps of a third (default 3) */
19
24
  junctionDashes?: number;
25
+ /** How far each staff line runs (default `all-but-last`) */
26
+ staffFill?: StaffFill;
27
+ /** With `staffFill: 'longest'`: the distance from the available width
28
+ * within which every line runs to it instead (default 0) */
29
+ staffFillSnapPx?: number;
20
30
  transpose?: number;
21
31
  /** The stanza sung under the notes (1-based; 1 is the script's own
22
32
  * text, 2… its `(@stanza …)` statements or the `stanzas` option). */
@@ -39,10 +49,13 @@ export interface RenderScoreOptions extends Omit<EmbedOptions, 'selector'> {
39
49
  }
40
50
  /** What a finished render reports: the rendered stanzas' count
41
51
  * mismatches (missing syllables show as placeholders, extra ones are
42
- * dropped). */
52
+ * dropped) and the characters the Liturgy font does not have. */
43
53
  export interface RenderResult {
44
- warnings: StanzaWarning[];
54
+ warnings: ScoreWarning[];
45
55
  }
56
+ /** What a render warns about: a stanza's count mismatch, a malformed
57
+ * `{…}` span, an unknown mark, or a character the Liturgy font lacks. */
58
+ export type ScoreWarning = StanzaWarning | MarkWarning | SpanProblem;
46
59
  /** Cleans up a programmatically rendered element: stops resize
47
60
  * re-rendering and drops the cached source and option overrides. Does
48
61
  * not remove the rendered score itself. */
@@ -1,4 +1,4 @@
1
- import { a as dispose, c as renderScore, i as scoreSvg, l as version, n as downloadScoreSvg, o as init, r as scorePngBlob, s as renderAll, t as downloadScorePng } from "../scoreImage-lvOrTbG-.js";
1
+ import { a as dispose, c as renderScore, i as scoreSvg, l as version, n as downloadScoreSvg, o as init, r as scorePngBlob, s as renderAll, t as downloadScorePng } from "../scoreImage-Dz3c55Zi.js";
2
2
  //#region src/embed/index.ts
3
3
  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", () => init(), { once: true });
4
4
  else init();
@@ -11,6 +11,7 @@
11
11
  * `KEY_SIGNATURES`), the stanzas (`withStanza`, `selectStanza`,
12
12
  * `parseStanza`, `stanzaWarnings`, `padStanza`, `stanzaCount`,
13
13
  * `slotCount`, and the stacked `stackStanzas`), the marked-up text export (`chantRuns`, `chantHtml`,
14
+ * `chantTextStyle`, `markupWarnings`,
14
15
  * plus the raw run resolver `resolveSyllableParts`), the style-set
15
16
  * registry (`STYLE_SETS`, `DEFAULT_STYLE_SET`), the
16
17
  * Word-compatible export (`toWordHtml`, `toWordText`, `layoutForWord`,
@@ -19,13 +20,15 @@
19
20
  * (`scoreSvg`, `scorePngBlob`, `downloadScorePng`, `downloadScoreSvg`).
20
21
  */
21
22
  export * from './core';
22
- export { GuidoScript, unescape, chantText, scriptSyllables, type ScriptSyllable, } from '../guidoScript';
23
+ export { GuidoScript, unescape, chantText, scriptSyllables, type ChantTextOptions, type ScriptSyllable, type SyllableRole, } from '../guidoScript';
23
24
  export { SCORE_MARKERS, splitNoteMarkers, type NoteGroupParts } from '../noteGroups';
24
25
  export { composeScript, type ComposeOptions, type MarkerPart, type NotesPart, type PartTranspose, type ScriptPart, type ScriptSlicePart, } from '../composeScript';
25
- export { chantRuns, chantHtml } from '../chantMarkup';
26
- export { STYLE_SETS, DEFAULT_STYLE_SET, resolveSyllableParts } from '../guidoStyles';
26
+ export { chantRuns, chantHtml, chantTextStyle, markupWarnings, type ChantHtmlOptions, type ChantWordRun, type MarkWarning, } from '../chantMarkup';
27
+ export { STYLE_SETS, DEFAULT_STYLE_SET, defineStyleSet, resolveSyllableParts, type MarkDefinitions, type StyleSetDefinition, } from '../guidoStyles';
28
+ export type { Mark, SpanProblem, TextRun } from '../textMarkup';
27
29
  export { KEY_SIGNATURES, PITCH_ROWS, STANZA_PLACEHOLDER, padStanza, parseInterval, parseStanza, selectStanza, slotCount, smallHeads, stackStanzas, stackedStanzaNumbers, stanzaCount, stanzaTexts, stanzaWarnings, transposeBy, transposeExact, transposeNotes, transposeScript, TranspositionRangeError, withStanza, type EmptySlots, type SelectStanzaOptions, type ScriptTransform, type StanzaOptions, type StanzaStack, type StanzaSyllable, type StanzaWarning, type SpelledInterval, type TransposeOverflow, type TranspositionTarget, } from '../guidoScriptTransforms';
28
30
  export type { StyleSetName, SyllablePart, PartStyle, ChantRunKind } from '../guidoStyles';
31
+ export type { StaffFill } from '../chantLayout';
29
32
  export type { ChantRun, ChantSyllable, ChantWord, ChantMarkupOptions } from '../chantMarkup';
30
33
  export { DEFAULT_SPACER, DEFAULT_TAB_INTERVAL_PT, SpacerMeter, layoutForWord, toWordHtml, toWordText, wordLayoutText, type SpacerChar, type SpacerConfig, type SpacerWidth, type WordExportOptions, type WordLayout, type WordLine, type WordRun, type WordStyleNames, type WordTextPiece, } from '../wordExport';
31
34
  export { baseOf, gClefPitchOf, modifyDown, modifyNatural, modifyUp, toCephalicus, toConnectDown, toLonga, toSmallHead, toSmallPoint, toVirga, variantOf, type VariantRole, } from '../glyphFamilies';
@@ -1,6 +1,6 @@
1
- import { a as dispose, c as renderScore, i as scoreSvg, l as version, n as downloadScoreSvg, o as init, r as scorePngBlob, s as renderAll, t as downloadScorePng } from "../scoreImage-lvOrTbG-.js";
2
- import { $ as toVirga, A as stanzaWarnings, B as unescape, C as selectStanza, D as stackedStanzaNumbers, E as stackStanzas, F as chantText, G as modifyDown, H as baseOf, I as escape, J as toCephalicus, K as modifyNatural, L as runProperties, M as SCORE_MARKERS, N as splitNoteMarkers, O as stanzaCount, P as GuidoScript, Q as toSmallPoint, R as scriptSyllables, S as parseStanza, T as smallHeads, U as gClefPitchOf, W as isClefGlyph, X as toLonga, Y as toConnectDown, Z as toSmallHead, _ as transposeExact, a as DEFAULT_STYLE_SET, b as isSlot, d as transposeBy, et as variantOf, f as transposeNotes, g as sameKeyGlyphs, h as parseInterval, j as withStanza, k as stanzaTexts, l as resolveSyllableParts, m as TranspositionRangeError, o as STYLE_SETS, p as KEY_SIGNATURES, q as modifyUp, u as PITCH_ROWS, v as transposeScript, w as slotCount, x as padStanza, y as STANZA_PLACEHOLDER, z as statementSource } from "../chantLayout-CVVuJUJl.js";
3
- import { a as DEFAULT_TAB_INTERVAL_PT, c as toWordHtml, i as DEFAULT_SPACER, l as toWordText, n as copyWordHtml, o as SpacerMeter, r as copyWordPlainText, s as layoutForWord, t as checkWordHtml, u as wordLayoutText } from "../wordChecker-DG09l_ol.js";
1
+ import { A as stackStanzas, C as STANZA_PLACEHOLDER, D as selectStanza, E as parseStanza, F as withStanza, M as stanzaCount, N as stanzaTexts, O as slotCount, P as stanzaWarnings, S as transposeScript, T as padStanza, _ as KEY_SIGNATURES, a as dispose, b as sameKeyGlyphs, c as renderScore, d as chantRuns, f as chantTextStyle, g as transposeNotes, h as transposeBy, i as scoreSvg, j as stackedStanzaNumbers, k as smallHeads, l as version, m as PITCH_ROWS, n as downloadScoreSvg, o as init, p as markupWarnings, r as scorePngBlob, s as renderAll, t as downloadScorePng, u as chantHtml, v as TranspositionRangeError, w as isSlot, x as transposeExact, y as parseInterval } from "../scoreImage-Dz3c55Zi.js";
2
+ import { B as toConnectDown, C as scriptSyllables, E as unescape, G as variantOf, H as toSmallHead, I as modifyDown, L as modifyNatural, M as baseOf, N as gClefPitchOf, O as SCORE_MARKERS, P as isClefGlyph, R as modifyUp, S as runProperties, T as syllableText, U as toSmallPoint, V as toLonga, W as toVirga, _ as GuidoScript, a as DEFAULT_STYLE_SET, c as defineStyleSet, k as splitNoteMarkers, p as resolveSyllableParts, s as STYLE_SETS, v as chantText, w as statementSource, y as escape, z as toCephalicus } from "../chantLayout-g_xuQ9nD.js";
3
+ import { a as DEFAULT_TAB_INTERVAL_PT, c as toWordHtml, i as DEFAULT_SPACER, l as toWordText, n as copyWordHtml, o as SpacerMeter, r as copyWordPlainText, s as layoutForWord, t as checkWordHtml, u as wordLayoutText } from "../wordChecker-B_9vyTt6.js";
4
4
  //#region src/composeScript.ts
5
5
  /**
6
6
  * Combining scripts (issue #71): one GuidoScript built from parts of
@@ -50,13 +50,18 @@ function stateAfter(tokens, state) {
50
50
  function openRuns(tokens) {
51
51
  const depth = {
52
52
  tight: 0,
53
- keep: 0
53
+ keep: 0,
54
+ aid: 0
54
55
  };
55
56
  for (const tok of tokens) {
56
- if (tok.kind !== "tight" && tok.kind !== "keep" && tok.kind !== "unit") continue;
57
+ if (tok.kind !== "tight" && tok.kind !== "keep" && tok.kind !== "unit" && tok.kind !== "aid") continue;
57
58
  for (const prop of runProperties(tok.kind)) depth[prop] = Math.max(0, depth[prop] + (tok.on ? 1 : -1));
58
59
  }
59
- return ["tight", "keep"].flatMap((prop) => Array(depth[prop]).fill(prop));
60
+ return [
61
+ "tight",
62
+ "keep",
63
+ "aid"
64
+ ].flatMap((prop) => Array(depth[prop]).fill(prop));
60
65
  }
61
66
  /** Tokens written back as script source (the `GuidoScript.toString`
62
67
  * rules: an empty slot always writes its `~`). */
@@ -64,14 +69,14 @@ function writeTokens(tokens) {
64
69
  return tokens.map((tok, i) => {
65
70
  const prefix = i > 0 && tok.spaceBefore ? " " : "";
66
71
  if (tok.kind !== "syllable") return prefix + statementSource(tok);
67
- return `${prefix}${tok.empty ? "~" : tok.text === "~" ? "\\~" : escape(tok.text)}(${escape(tok.notes)})`;
72
+ return `${prefix}${tok.empty ? "~" : tok.source}(${escape(tok.notes)})`;
68
73
  }).join("");
69
74
  }
70
75
  /** A stanza item written back as stanza text (see `parseStanza`). */
71
76
  function stanzaItemSource(item) {
72
77
  if (item.kind === "hold") return "-";
73
78
  if (item.kind === "empty") return "~";
74
- const text = Array.from(item.text, (ch) => /\s/.test(ch) ? "~" : "\\-=­~()".includes(ch) ? `\\${ch}` : ch).join("");
79
+ const text = (item.source ?? escape(item.text)).replace(/\\.|./gsu, (unit) => unit[0] === "\\" ? unit : /\s/.test(unit) ? "~" : "-=­~".includes(unit) ? `\\${unit}` : unit);
75
80
  return item.wordEnd ? text : `${text}-`;
76
81
  }
77
82
  /** Applies a staff-degree or exact transposition to a whole script. */
@@ -268,7 +273,8 @@ function composeScript(parts, options = {}) {
268
273
  append({
269
274
  tokens: [{
270
275
  kind: "syllable",
271
- text: "**",
276
+ ...syllableText("**"),
277
+ role: "sign",
272
278
  notes: "",
273
279
  wordEnd: true,
274
280
  spaceBefore: false
@@ -345,43 +351,4 @@ function composeScript(parts, options = {}) {
345
351
  return clefGroup(opening) + writeTokens(out) + stanzas.join("");
346
352
  }
347
353
  //#endregion
348
- //#region src/chantMarkup.ts
349
- /**
350
- * The marked-up sung text of a chant script, for other applications: the
351
- * same run resolution the renderer draws, expressed as notation-fixed
352
- * semantic kinds instead of style-set CSS values. `chantRuns` gives the
353
- * structured form (words → syllables → runs); `chantHtml` serializes it
354
- * as HTML spans classed with those kinds (`liturgy`, `rubric`, `star`,
355
- * `marker`, `plus`, plus `initial`), so a consumer styles the classes
356
- * with its own CSS.
357
- */
358
- var chantRunOf = (part) => {
359
- const run = { text: part.text };
360
- if (part.kind !== void 0) run.kind = part.kind;
361
- if (part.style.initial) run.initial = true;
362
- return run;
363
- };
364
- /** The marked-up sung text of the script: its words, their syllables,
365
- * and each syllable's runs of notation-fixed kinds. Renders exactly the
366
- * text a score render would (including the style set's default script
367
- * transforms) with the style-set presentation stripped; letter case is
368
- * the raw text's, so a BNS-look consumer uppercases rubrics in CSS. */
369
- function chantRuns(script, options = {}) {
370
- const styleSet = STYLE_SETS[options.style ?? "BNS"];
371
- return new GuidoScript(script, { transforms: styleSet.scriptTransforms ?? [] }).words.map((word) => ({ syllables: word.syllables.map((syl) => ({ runs: resolveSyllableParts(syl.text, styleSet, false, { rawCase: true }).map(chantRunOf) })) }));
372
- }
373
- /** The marked-up sung text as an HTML string: one span per kinded or
374
- * initial run, classed with the kind (and `initial`), bare text
375
- * otherwise. Syllables of a word concatenate and words join with single
376
- * spaces — hyphenation is the consumer's job, and `chantRuns` has the
377
- * syllable boundaries. Text is HTML-escaped. */
378
- function chantHtml(script, options = {}) {
379
- return chantRuns(script, options).map((word) => word.syllables.map((syl) => syl.runs.map(runHtml).join("")).join("")).join(" ");
380
- }
381
- var runHtml = (run) => {
382
- const classes = [...run.kind ? [run.kind] : [], ...run.initial ? ["initial"] : []].join(" ");
383
- return classes ? `<span class="${classes}">${escapeHtml(run.text)}</span>` : escapeHtml(run.text);
384
- };
385
- var escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
386
- //#endregion
387
- export { DEFAULT_SPACER, DEFAULT_STYLE_SET, DEFAULT_TAB_INTERVAL_PT, GuidoScript, KEY_SIGNATURES, PITCH_ROWS, SCORE_MARKERS, STANZA_PLACEHOLDER, STYLE_SETS, SpacerMeter, TranspositionRangeError, baseOf, chantHtml, chantRuns, chantText, checkWordHtml, composeScript, copyWordHtml, copyWordPlainText, dispose, downloadScorePng, downloadScoreSvg, gClefPitchOf, init, layoutForWord, modifyDown, modifyNatural, modifyUp, padStanza, parseInterval, parseStanza, renderAll, renderScore, resolveSyllableParts, scorePngBlob, scoreSvg, scriptSyllables, selectStanza, slotCount, smallHeads, splitNoteMarkers, stackStanzas, stackedStanzaNumbers, stanzaCount, stanzaTexts, stanzaWarnings, toCephalicus, toConnectDown, toLonga, toSmallHead, toSmallPoint, toVirga, toWordHtml, toWordText, transposeBy, transposeExact, transposeNotes, transposeScript, unescape, variantOf, version, withStanza, wordLayoutText };
354
+ export { DEFAULT_SPACER, DEFAULT_STYLE_SET, DEFAULT_TAB_INTERVAL_PT, GuidoScript, KEY_SIGNATURES, PITCH_ROWS, SCORE_MARKERS, STANZA_PLACEHOLDER, STYLE_SETS, SpacerMeter, TranspositionRangeError, baseOf, chantHtml, chantRuns, chantText, chantTextStyle, checkWordHtml, composeScript, copyWordHtml, copyWordPlainText, defineStyleSet, dispose, downloadScorePng, downloadScoreSvg, gClefPitchOf, init, layoutForWord, markupWarnings, modifyDown, modifyNatural, modifyUp, padStanza, parseInterval, parseStanza, renderAll, renderScore, resolveSyllableParts, scorePngBlob, scoreSvg, scriptSyllables, selectStanza, slotCount, smallHeads, splitNoteMarkers, stackStanzas, stackedStanzaNumbers, stanzaCount, stanzaTexts, stanzaWarnings, toCephalicus, toConnectDown, toLonga, toSmallHead, toSmallPoint, toVirga, toWordHtml, toWordText, transposeBy, transposeExact, transposeNotes, transposeScript, unescape, variantOf, version, withStanza, wordLayoutText };
@@ -1,11 +1,13 @@
1
- import { StyleSetName } from './guidoStyles';
2
- import { LayoutSource } from './chantLayout';
1
+ import { MarkDefinitions, StyleSetName } from './guidoStyles';
2
+ import { LayoutSource, StaffFill } from './chantLayout';
3
3
  export { NOTE_MODIFIERS, SCORE_MARKERS } from './chantLayout';
4
4
  /** Options for one render. All fields optional; defaults reproduce the
5
5
  * original Book Antiqua look (style set BNS). */
6
6
  export interface RenderOptions {
7
- /** Named style set from STYLE_SETS (default: BNS) */
7
+ /** Named style set (default: BNS) */
8
8
  style?: StyleSetName;
9
+ /** Marks this score adds to its style set's */
10
+ marks?: MarkDefinitions;
9
11
  /** Render all text bold, measurements included */
10
12
  bold?: boolean;
11
13
  /** Text line size in px (default 18) */
@@ -18,6 +20,11 @@ export interface RenderOptions {
18
20
  maxWidthPx?: number;
19
21
  /** Dashes in a normal junction between note groups, in steps of a third (default 3) */
20
22
  junctionDashes?: number;
23
+ /** How far each staff line runs (default `all-but-last`) */
24
+ staffFill?: StaffFill;
25
+ /** With `staffFill: 'longest'`: the distance from the available width
26
+ * within which every line runs to it instead (default 0) */
27
+ staffFillSnapPx?: number;
21
28
  }
22
29
  /**
23
30
  * Renders a GuidoScript into a tidy score: a notes line in the chant font,
@@ -58,6 +65,7 @@ export declare class GuidoRender {
58
65
  * run, carrying the run's inline styles and its notation-fixed kind
59
66
  * class (`liturgy`, `rubric`, `star`, `marker`, `plus`); runs marked
60
67
  * `initial` by the `*…*` marker carry the initial class. */
68
+ private static dashSpan;
61
69
  private static sylSpan;
62
70
  private static spacer;
63
71
  }
@@ -1,16 +1,30 @@
1
1
  import { ScriptTransform } from './guidoScriptTransforms';
2
+ import { SpanProblem, TextRun } from './textMarkup';
2
3
  /** One parsed token of the script: a syllable, or a control statement.
3
4
  * `spaceBefore` records whether the source had whitespace between the
4
5
  * previous group and this token's group — it feeds the previous
5
6
  * syllable's `wordEnd` and the `toString()` round-trip. */
6
7
  export type ScriptToken = SyllableToken | StatementToken;
8
+ /** What a syllable token is for, independent of its look. `sung` is the
9
+ * text; `label` a heading that is not sung (`V.`, `ANT.`: a wrapped syllable
10
+ * with no pitch); `sign` a singer's sign (`**`, `*`, the cross); `aid` sung
11
+ * but not part of the text (the differentia, inside `(@aid)`). */
12
+ export type SyllableRole = 'sung' | 'label' | 'sign' | 'aid';
7
13
  /** A syllable token. `held` marks a text-less group held by the syllable
8
14
  * before it (its `wordEnd` is that syllable's); `empty` marks an empty
9
15
  * slot (`~`, or a text-less group at the start): notes but no syllable.
10
- * Both flags are only present when set. */
16
+ * Both flags are only present when set. `text` is what it reads, with no
17
+ * markup in it; `runs` what it draws; `source` how it is written, standing
18
+ * on its own, which is what the rewrites write back. `hyphen` is the marks
19
+ * of the hyphen after it, when a `{…}` span runs on into the next syllable.
20
+ * Text fields are empty on a held group and an empty slot. */
11
21
  export type SyllableToken = {
12
22
  kind: 'syllable';
13
23
  text: string;
24
+ source: string;
25
+ runs: TextRun[];
26
+ hyphen?: string[];
27
+ role: SyllableRole;
14
28
  notes: string;
15
29
  wordEnd: boolean;
16
30
  spaceBefore: boolean;
@@ -19,6 +33,11 @@ export type SyllableToken = {
19
33
  };
20
34
  /** A syllable as `GuidoScript.syllables` lists it. */
21
35
  export type Syllable = Pick<SyllableToken, 'text' | 'notes' | 'wordEnd' | 'held' | 'empty'>;
36
+ /** One word of the script (`GuidoScript.words`). */
37
+ export interface Word {
38
+ text: string;
39
+ syllables: Pick<SyllableToken, 'text' | 'source' | 'runs' | 'role' | 'notes'>[];
40
+ }
22
41
  /** Source offsets of one token (see `GuidoScript.tokenSpans`): `start`
23
42
  * is its text's first character (its group's `(` when it has no text),
24
43
  * `notesStart`/`notesEnd` bound its group's content, `end` is just past
@@ -56,12 +75,17 @@ export type StatementToken = {
56
75
  kind: 'unit';
57
76
  on: boolean;
58
77
  spaceBefore: boolean;
78
+ } | {
79
+ kind: 'aid';
80
+ on: boolean;
81
+ spaceBefore: boolean;
59
82
  };
60
83
  /** The statements that open and close a run of syllables (issue #100):
61
- * `tight` spacing, `keep` on one line, `unit` both. */
62
- export type RunStatementKind = 'tight' | 'keep' | 'unit';
84
+ * `tight` spacing, `keep` on one line, `unit` both, and `aid` the syllables
85
+ * that are sung but are not the text (issue #110). */
86
+ export type RunStatementKind = 'tight' | 'keep' | 'unit' | 'aid';
63
87
  /** The run properties a run statement sets. */
64
- export declare function runProperties(kind: RunStatementKind): ('tight' | 'keep')[];
88
+ export declare function runProperties(kind: RunStatementKind): ('tight' | 'keep' | 'aid')[];
65
89
  /** Whether a group's content is a control statement (`@`-keyword,
66
90
  * trimmed). Shared with the transforms, which must leave statement
67
91
  * groups alone — their keyword characters are pitch glyphs otherwise.
@@ -96,6 +120,9 @@ export declare class GuidoScript {
96
120
  * content and just past its group's `)`. The walker
97
121
  * (`scriptSyllables`) reads them. */
98
122
  get tokenSpans(): TokenSpan[];
123
+ /** What is wrong with the script's `{…}` spans: such a span renders
124
+ * plainly instead of failing the score. */
125
+ get spanProblems(): SpanProblem[];
99
126
  private parse;
100
127
  /** The script broken into syllables, each with its sung text and
101
128
  * notes — the syllable tokens, statements filtered out. */
@@ -112,21 +139,18 @@ export declare class GuidoScript {
112
139
  private get normalized();
113
140
  /** The syllables grouped into the words of the text. Held groups and
114
141
  * empty slots sing no syllable of their own, so they are left out. */
115
- get words(): {
116
- text: string;
117
- syllables: {
118
- text: string;
119
- notes: string;
120
- }[];
121
- }[];
142
+ get words(): Word[];
122
143
  /** The script rebuilt from the parsed pieces — a round-trip of the
123
144
  * source, statements and stanzas included. */
124
145
  toString(): string;
125
146
  }
126
- /** One text-bearing syllable of a script (see `scriptSyllables`). */
147
+ /** One syllable of a script (see `scriptSyllables`). */
127
148
  export interface ScriptSyllable {
128
- /** Its text, escapes folded and whitespace trimmed */
149
+ /** The text to read: escapes folded, no markup in it */
129
150
  text: string;
151
+ /** Its text as written, markup and escapes kept */
152
+ source: string;
153
+ role: SyllableRole;
130
154
  /** Its own note group's content, escapes folded */
131
155
  notes: string;
132
156
  /** The groups it holds (issue #83), escapes folded, in order */
@@ -147,17 +171,30 @@ export interface ScriptSyllable {
147
171
  token: number;
148
172
  }
149
173
  /**
150
- * The syllables of a script that carry text, in order — the ones the
151
- * sung text is made of, so their count and texts match `chantText`
152
- * (and `GuidoScript.words`). Held groups ride on their syllable
153
- * (`held`), `~` empty slots, statements and `(@stanza …)` are skipped.
154
- * Offsets index the script's source; index i is the "syllable i" of
155
- * `composeScript`'s `from`/`to`.
174
+ * The syllables of a script, in order: by default the sung ones, labels and
175
+ * signs left out (`roles` chooses others). Held groups ride on their
176
+ * syllable (`held`); `~` empty slots, statements and `(@stanza …)` are
177
+ * skipped. Word starts and ends are the listed syllables' own, so a word
178
+ * end on a left-out syllable lands on the one before it. Offsets index the
179
+ * script's source; index i is the "syllable i" of `composeScript`'s
180
+ * `from`/`to`.
156
181
  */
157
- export declare function scriptSyllables(script: GuidoScript | string): ScriptSyllable[];
158
- /** The sung text of the script: the clef stripped, syllables joined
159
- * into words, and the words joined with single spaces. */
160
- export declare function chantText(script: string): string;
182
+ export declare function scriptSyllables(script: GuidoScript | string, options?: {
183
+ roles?: readonly SyllableRole[];
184
+ }): ScriptSyllable[];
185
+ /** What `chantText` adds to the sung words, both off by default. */
186
+ export interface ChantTextOptions {
187
+ /** Keep the labels (`V.`, `R.`, `ANT.`) */
188
+ labels?: boolean;
189
+ /** Keep the sung aids (the differentia) */
190
+ aids?: boolean;
191
+ }
192
+ /** The text of the script to read: the sung words joined with single
193
+ * spaces, with no markup, labels, signs or aids in them. Characters the
194
+ * author escaped stay. */
195
+ export declare function chantText(script: string, options?: ChantTextOptions): string;
196
+ /** A syllable's text fields, from text written on its own. */
197
+ export declare function syllableText(written: string): Pick<SyllableToken, 'text' | 'source' | 'runs' | 'hyphen'>;
161
198
  /** Folds backslash escapes into the characters they stand for. Shared
162
199
  * with the transforms module (guidoScriptTransforms.ts). */
163
200
  export declare function unescape(text: string): string;
@@ -5,24 +5,6 @@ export interface ScriptTransform {
5
5
  name: string;
6
6
  apply: (source: string) => string;
7
7
  }
8
- /** The `startWithInitial` transform: finds the first syllable group with
9
- * actual notes and text (the clef, no-notes groups, control statements,
10
- * text-less groups and `~` empty slots don't count) and wraps the
11
- * syllable's first character in the `*…*` initial marker. Already-marked
12
- * text (leading `*`) is left alone. */
13
- declare function startWithInitial(source: string): string;
14
- /**
15
- * The built-in transformations, keyed by name; pass the ones a feature
16
- * needs to the GuidoScript constructor.
17
- */
18
- export declare const SCRIPT_TRANSFORMS: {
19
- /** Wraps the first letter of the first syllable that has notes in
20
- * `*…*`, the initial marker of the style marking system. */
21
- startWithInitial: {
22
- name: string;
23
- apply: typeof startWithInitial;
24
- };
25
- };
26
8
  /** The pitch rows of the chant font: every character carrying pitch
27
9
  * information, grouped into rows of neighbouring pitches from low to
28
10
  * high. A transpose shift moves a character this many positions along