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.
package/README.md CHANGED
@@ -22,7 +22,8 @@ The package ships a typed ESM build with an exports map:
22
22
  (`chantText(script)`, the `GuidoScript` parser, `unescape`,
23
23
  `scriptSyllables`), the script helpers (`PITCH_ROWS`, `transposeNotes`,
24
24
  `SCORE_MARKERS`, `splitNoteMarkers`, `composeScript` — see *Combining
25
- scripts* below) and the style sets (`STYLE_SETS`, `DEFAULT_STYLE_SET`, `StyleSetName`).
25
+ scripts* below) and the style sets (`STYLE_SETS`, `DEFAULT_STYLE_SET`,
26
+ `defineStyleSet`, `StyleSetName`).
26
27
  Also the Word-compatible export: `toWordHtml(script, options?)`,
27
28
  `toWordText(script, options?)`, the clipboard writers
28
29
  `copyWordHtml` / `copyWordPlainText`, and the paste checker
@@ -60,21 +61,25 @@ script — for a lyrics column, a search index, and the like:
60
61
  import { chantText, GuidoScript } from 'guidex'
61
62
 
62
63
  chantText('(M)A(0) di(0q)e(qQ0)bus(1) an(3)ti(1e)quis(qQ0-:)') // 'A diebus antiquis'
64
+ chantText('(M)__V.__() De(1)us(2) **() in(3)') // 'Deus in'
65
+ chantText('(M)__V.__() De(1)us(2)', { labels: true }) // 'V. Deus'
63
66
  new GuidoScript('(M)A(0) di(0q)e(qQ0)bus(1) an(3)ti(1e)quis(qQ0-:)').words
64
67
  // [{ text: 'A', syllables: [{ text: 'A', notes: '0' }] },
65
68
  // { text: 'diebus', syllables: [{ text: 'di', notes: '0q' }, { text: 'e', notes: 'qQ0' }, { text: 'bus', notes: '1' }] },
66
69
  // { text: 'antiquis', syllables: [{ text: 'an', notes: '3' }, { text: 'ti', notes: '1e' }, { text: 'quis', notes: 'qQ0-:' }] }]
67
70
  ```
68
71
 
69
- `scriptSyllables(script)` walks the same syllables with their notes, held
72
+ `scriptSyllables(script)` walks the sung syllables with their notes, held
70
73
  groups, word starts and source offsets (held groups, `~` slots and
71
- statements are skipped, so its count matches `chantText`):
74
+ statements are skipped, and labels and signs too unless `{ roles }` asks
75
+ for them). `text` is the clean text and `source` the syllable as written.
76
+ Its indices are the ones `composeScript` takes:
72
77
 
73
78
  ```js
74
79
  import { scriptSyllables } from 'guidex'
75
80
 
76
81
  scriptSyllables('(M)Ülj(11) az(0) ra,(qQ0-:) mon(3)')[2]
77
- // { text: 'ra,', notes: 'qQ0-:', held: [], wordStart: true, wordEnd: true,
82
+ // { text: 'ra,', source: 'ra,', role: 'sung', notes: 'qQ0-:', held: [], wordStart: true, wordEnd: true,
78
83
  // start: 17, notesStart: 21, notesEnd: 26, end: 27, token: 2 }
79
84
  ```
80
85
 
@@ -108,12 +113,11 @@ composeScript([{ script: antiphon, to: 3 }, { marker: 'intonation' }, { script:
108
113
 
109
114
  ### Marked-up text
110
115
 
111
- The sung text with its markup, for displaying the text outside the
112
- score: `chantRuns` gives the structure (words → syllables → runs), and
113
- `chantHtml` serializes it as HTML. The `**` star renders as `∗`, and the
114
- decoration wrappers become notation-fixed kinds — `liturgy` for `__…__`,
115
- `rubric` for `_…_`, `initial` for `*…*`, `marker` for the `*`/`†` glyph
116
- runs, `plus` for a `+` inside a Liturgy run:
116
+ The text with its markup, for displaying it outside the score: `chantRuns`
117
+ gives the structure (words → syllables → runs) and `chantHtml` serializes
118
+ it as HTML. Runs carry their `marks` and the `role` of their syllable. They
119
+ are the same in every style set, with letter case as written, and they
120
+ hold only initials the script itself writes.
117
121
 
118
122
  ```js
119
123
  import { chantHtml, chantRuns } from 'guidex'
@@ -121,33 +125,91 @@ import { chantHtml, chantRuns } from 'guidex'
121
125
  const script = '(c4)__V.__() *Psa*lmus(1) **(2) De(7)us(2)'
122
126
 
123
127
  chantHtml(script) // '<span class="liturgy">V.</span> <span class="initial">Psa</span>lmus <span class="star">∗</span> Deus'
124
- chantRuns(script)
125
- // [{ syllables: [{ runs: [{ text: 'V.', kind: 'liturgy' }] }] },
126
- // { syllables: [{ runs: [{ text: 'Psa', initial: true }, { text: 'lmus' }] }] },
127
- // { syllables: [{ runs: [{ text: '∗', kind: 'star' }] }] },
128
- // { syllables: [{ runs: [{ text: 'De' }] }, { runs: [{ text: 'us' }] }] }]
128
+ chantHtml(script, { roles: ['sung'], classPrefix: 'gx-' })
129
+ // '<span class="gx-initial">Psa</span>lmus Deus'
130
+
131
+ chantRuns(script, { merge: 'word', roles: ['sung', 'label'] })
132
+ // [{ text: 'V.', kind: 'liturgy', marks: ['liturgy'], role: 'label', wordEnd: true },
133
+ // { text: 'Psa', initial: true, marks: ['initial'], role: 'sung', wordEnd: false },
134
+ // { text: 'lmus', marks: [], role: 'sung', wordEnd: true },
135
+ // { text: 'Deus', marks: [], role: 'sung', wordEnd: true }]
129
136
  ```
130
137
 
131
- Both take `{ style }` like the renderer (default BNS) and apply the
132
- style set's default script transforms, so the text matches what a score
133
- render shows. The kinds are identical across style sets and identical to
134
- the class names the rendered score's spans carry, so one stylesheet
135
- serves both. Style them yourself — the BNS and Vesperale looks
136
- correspond to:
138
+ Without `merge`, each syllable keeps its own runs, for consumers that
139
+ hyphenate. `kind` is derived from `marks` and kept for existing consumers.
140
+ `chantTextStyle('red,sc', { style })` gives the resolved look of marks, for
141
+ styling prose to match a score.
142
+
143
+ ### Styling text under the staff
144
+
145
+ Any part of the text can be styled with a `{marks:text}` span, which may
146
+ cross syllables and words. Marks are comma-separated, later ones win, and
147
+ spans nest:
137
148
 
138
- ```css
139
- .liturgy { font-family: 'Liturgy', serif; font-weight: 700; }
140
- .initial { font-weight: 700; }
141
- /* BNS flavour */
142
- .rubric { text-transform: uppercase; font-size: 70%; }
143
- .liturgy, .rubric, .initial { color: #d40000; }
144
- /* Vesperale flavour */
145
- .rubric { font-style: italic; font-size: 80%; }
146
149
  ```
150
+ {red,b:Al}le(1)lú(2)ia(3) part of a word
151
+ {i:Mi(1)se(2)ré(3)re.(4)} across syllables
152
+ {rubric:Pater noster {plain:secreto}}() a black word in a rubric
153
+ *D*{sc:eus}(1) a red initial, then small caps
154
+ ```
155
+
156
+ | Mark | Effect |
157
+ | --- | --- |
158
+ | `red`, `color:<name>` | Colour, from the palette or a style set's `colors` |
159
+ | `b`, `i` | Bold, italic |
160
+ | `sc` | Real small caps: the text itself stays as written |
161
+ | `up` | Capitals, display only |
162
+ | `size:<n>` | Size multiplier |
163
+ | `raise:<n>` | Baseline shift |
164
+ | `font:<name>` | A font: `liturgy`, `times`, or a style set's `fonts` |
165
+ | `plain` | Reset everything before it |
147
166
 
148
- Letter case stays the raw text's (uppercasing BNS rubrics is
149
- presentation), and the syllable boundaries live in `chantRuns` for
150
- consumers that hyphenate.
167
+ These mean the same in every style set. `liturgy`, `rubric` and `initial`
168
+ are the style set's own, and `__x__`, `_x_` and `*x*` are short for them.
169
+ The hyphen inside a span takes the span's look, size included, and the one
170
+ at its edge stays plain. `\{`, `\}`, `\_` and `\*` are literal.
171
+
172
+ A consumer adds its own marks and style sets without patching the package:
173
+
174
+ ```js
175
+ import { defineStyleSet, renderScore } from 'guidex'
176
+
177
+ defineStyleSet('Psalterium', {
178
+ extends: 'BNS',
179
+ marks: { rubric: { smallCaps: true, scale: 0.8, color: 'red' } },
180
+ colors: { gold: '#b8860b' },
181
+ })
182
+ renderScore(el, script, { style: 'Psalterium', marks: { cue: { italic: true } } })
183
+ ```
184
+
185
+ A malformed span, an unknown mark, or a character the Liturgy font lacks
186
+ renders plainly and comes back in the render's `warnings`
187
+ (`markupWarnings(script, { style, marks })` checks without rendering).
188
+
189
+ ### What a syllable is for
190
+
191
+ | Role | What it is | `chantText` | Stanza slot | `scriptSyllables` |
192
+ | --- | --- | --- | --- | --- |
193
+ | `sung` | The words | Yes | Yes | Yes |
194
+ | `label` | A wrapped syllable with no pitch: `V.`, `R.`, `ANT.` | With `{ labels: true }` | No | With `roles` |
195
+ | `sign` | `**`, `*`, `†` alone, the cross `__+__` | No | No | With `roles` |
196
+ | `aid` | Sung, not the text: the differentia, inside `(@aid)…(@aid off)` | With `{ aids: true }` | Yes | Yes |
197
+
198
+ A label or a sign may stand on spacing and a bar (`**(-----,,)`); guidex
199
+ leaves the choice of bars to the author.
200
+
201
+ ### The Liturgy font
202
+
203
+ `liturgy.ttf` maps exactly five characters; anything else in a `__…__` run
204
+ falls back to a serif and warns.
205
+
206
+ | Character | Glyph |
207
+ | --- | --- |
208
+ | `V` | The versicle label, as `__V.__` |
209
+ | `R` | The response label, as `__R.__` |
210
+ | `.` | The stop of those labels |
211
+ | `/` | The font's slash |
212
+ | `+` | The cross, drawn at 70% and raised |
151
213
 
152
214
  ### Word export
153
215
 
@@ -341,6 +403,8 @@ updates when the `script` prop changes. Props mirror the options below:
341
403
  | `style` | `BNS`, `Vesperale` | `BNS` |
342
404
  | `bold` | boolean | `false` |
343
405
  | `textPx` | base text size in px (notes render at 2×) | `18` |
406
+ | `staffFill` | how far each staff runs: `all-but-last`, `none`, `all`, `longest` | `all-but-last` |
407
+ | `staffFillSnapPx` | with `longest`: fill to the full width when the longest line ends this close to it (`data-staff-fill-snap`) | `0` |
344
408
  | `transpose` | pitch-row shift (see `transposeBy`) | `0` |
345
409
  | `debug` | boolean (measurement titles on spans) | `false` |
346
410
 
@@ -355,6 +419,12 @@ overflow is the host page's to handle:
355
419
  .my-score { overflow-x: auto; } /* or hidden, to clip */
356
420
  ```
357
421
 
422
+ `staffFill` sets where each staff stops. `all-but-last` fills every line
423
+ but the last to the available width, `none` stops every line at its own
424
+ notes, `all` fills every line, and `longest` ends every line with the
425
+ score's longest line, text included. Bars stay right after their notes,
426
+ with staff beyond them. With `maxWidth: Infinity`, `all` acts as `longest`.
427
+
358
428
  ## Embedding with a script tag (no bundler)
359
429
 
360
430
  Host the `dist-embed/` folder (also attached to every GitHub Release)
@@ -441,9 +511,10 @@ its notes:
441
511
  breaks between pairs of verses first, between verses next, and inside
442
512
  a verse last.
443
513
  - Style decorations on syllable text: `__…__` renders in the Liturgy
444
- font, bold; `_…_` renders small caps (BNS) or italic (Vesperale);
514
+ font, bold; `_…_` renders small capitals (BNS) or italic (Vesperale);
445
515
  `*…*` marks an initial (bold, red in BNS). A syllable that is exactly
446
- `**` renders the mediant star glyph.
516
+ `**` renders the mediant star glyph. `{marks:…}` styles any stretch of
517
+ text (see *Styling text under the staff*).
447
518
 
448
519
  In the rendered score, notes are set in the Guidohu font at twice the
449
520
  surrounding text size. Notes are measured with a hidden canvas after
@@ -1,14 +1,16 @@
1
+ import { StaffFill } from '../chantLayout';
1
2
  import { ChantPrefs, EditorSettings, SavedChant } from '../editorStorage';
2
3
  import { StyleSetName } from '../guidoStyles';
3
- import { ScriptTransform, TranspositionTarget } from '../guidoScriptTransforms';
4
+ import { TranspositionTarget } from '../guidoScriptTransforms';
4
5
  import { GuidoScript } from '../guidoScript';
6
+ import { MarkWarning } from '../chantMarkup';
7
+ import { SpanProblem } from '../textMarkup';
5
8
  import { EmptySlots, StanzaWarning } from '../stanzas';
6
9
  import { SpacerChar } from '../wordExport';
7
10
  import { WordInputs } from './wordCopy';
8
- /** The render settings minus the fields that live elsewhere: `word` has
9
- * its own raw-string inputs (wordCopy.ts) and `initial` is derived from
10
- * the live transforms array — the single source of truth for both. */
11
- export type RenderSettings = Omit<EditorSettings, 'word' | 'initial'>;
11
+ /** The render settings minus `word`, which has its own raw-string inputs
12
+ * (wordCopy.ts). */
13
+ export type RenderSettings = Omit<EditorSettings, 'word'>;
12
14
  /** Transient feedback slots: one `word-copy-feedback`-style span each,
13
15
  * shown for 4 s and cleared by their own timer (FeedbackSpan). */
14
16
  export type FeedbackSlot = 'draft' | 'copyScript' | 'copyLink' | 'downloadImage' | 'wordCopy' | 'chantSaved' | 'chantSaveForm' | 'chantList';
@@ -33,9 +35,6 @@ export interface EditorState {
33
35
  * from; any hand edit clears it. */
34
36
  activeChipId: string | null;
35
37
  settings: RenderSettings;
36
- /** The live transform set: rebuilt by style changes, toggled by the
37
- * initial checkbox, persisted as the derived `initial` boolean. */
38
- transforms: ScriptTransform[];
39
38
  /** Raw typed strings of the base/chant size inputs — the render and
40
39
  * persistence use the clamped settings numbers. */
41
40
  inputs: {
@@ -103,8 +102,11 @@ export type EditorAction = {
103
102
  type: 'SET_JUNCTION_DASHES';
104
103
  dashes: number;
105
104
  } | {
106
- type: 'SET_INITIAL';
107
- initial: boolean;
105
+ type: 'SET_STAFF_FILL';
106
+ fill: StaffFill;
107
+ } | {
108
+ type: 'SET_STAFF_FILL_SNAP';
109
+ px: number;
108
110
  } | {
109
111
  type: 'SET_MAX_WIDTH';
110
112
  px: number;
@@ -178,47 +180,44 @@ export type EditorAction = {
178
180
  type: 'HIDE_FEEDBACK';
179
181
  slot: FeedbackSlot;
180
182
  };
181
- export declare function hasInitialTransform(transforms: ScriptTransform[]): boolean;
182
183
  /** Signed label for the transpose slider: `+2`, `0` or `-3`. */
183
184
  export declare function transposeLabel(shift: number): string;
184
185
  /** The editor script's stanza facts: how many stanzas the draft has,
185
186
  * the one rendered (the picked one, or 1 when the draft no longer has
186
187
  * it; `STACK_ALL` while a draft with stanzas stacks them all), and the
187
- * rendered stanzas' count mismatches. */
188
+ * rendered stanzas' count mismatches and markup problems. */
188
189
  export interface EditorStanzas {
189
190
  count: number;
190
191
  stanza: number;
191
- warnings: StanzaWarning[];
192
+ warnings: (StanzaWarning | MarkWarning | SpanProblem)[];
192
193
  }
193
194
  /** The stanza facts of a draft. A draft that does not parse has one
194
195
  * stanza — the render reports the parse error itself. */
195
- export declare function editorStanzas(script: string, picked: StanzaInputs): EditorStanzas;
196
+ export declare function editorStanzas(script: string, picked: StanzaInputs, style?: StyleSetName): EditorStanzas;
196
197
  /** Builds the editor script: the draft with the picked stanza swapped
197
- * in, plus the transforms the checkboxes enable, the transpose slider
198
- * sets, and the exact transposition. A failing exact transposition (out
198
+ * in, plus the transposition the slider sets and the exact one. A failing exact transposition (out
199
199
  * of range, missing glyph) is left out and its message returned for the
200
200
  * editor to show. `scripts` is what the preview renders: the script
201
201
  * alone, or every stanza stacked (the script is then stanza 1's). */
202
- export declare function buildEditorScript(state: Pick<EditorState, 'script' | 'transforms' | 'settings' | 'exact'> & Partial<Pick<EditorState, 'stanza'>>): {
202
+ export declare function buildEditorScript(state: Pick<EditorState, 'script' | 'settings' | 'exact'> & Partial<Pick<EditorState, 'stanza'>>): {
203
203
  script: GuidoScript;
204
204
  scripts: GuidoScript[];
205
205
  transposeError: string | null;
206
206
  };
207
- /** The render settings a saved chant snapshots: style, bold, the initial
208
- * transform, base/chant sizes with their decouple state, and transpose —
207
+ /** The render settings a saved chant snapshots: style, bold, base/chant
208
+ * sizes with their decouple state, and transpose —
209
209
  * exactly what loading the chant re-applies. The max-width slider and
210
210
  * the color pickers are not part of a chant. */
211
- export declare function chantPrefsSnapshot(state: Pick<EditorState, 'settings' | 'transforms'>): ChantPrefs;
211
+ export declare function chantPrefsSnapshot(state: Pick<EditorState, 'settings'>): ChantPrefs;
212
212
  /** The full settings blob for storage: the live render settings plus the
213
- * derived `initial` flag and the Word-copy slice's effective values. */
213
+ * Word-copy slice's effective values. */
214
214
  export declare function settingsSnapshot(state: EditorState): EditorSettings;
215
215
  /** The state overlay a ChantPrefs snapshot restores — shared by the
216
216
  * LOAD_CHANT reducer case and the shared-link init (issue #63), so both
217
217
  * ride the same handoff: a decoupled chant without a custom size adopts
218
218
  * the derived 2× base size of the chant's own base font size. */
219
219
  export declare function chantPrefsOverlay(prefs: ChantPrefs): {
220
- settings: Pick<RenderSettings, 'style' | 'bold' | 'transpose' | 'basePx' | 'decoupleNotes' | 'notesPx' | 'notesCustom' | 'junctionDashes'>;
221
- transforms: ScriptTransform[];
220
+ settings: Pick<RenderSettings, 'style' | 'bold' | 'transpose' | 'basePx' | 'decoupleNotes' | 'notesPx' | 'notesCustom' | 'junctionDashes' | 'staffFill' | 'staffFillSnapPx'>;
222
221
  inputs: {
223
222
  basePx: string;
224
223
  notesPx: string;
@@ -14,9 +14,8 @@ export interface SharedChant {
14
14
  * the stored chant blobs. */
15
15
  export declare function parseShareFragment(hash: string): SharedChant | null;
16
16
  /** The share URL for the editor's current content: the raw script (the
17
- * transforms re-derive on the receiving end from the `initial` and
18
- * transpose prefs) plus the full prefs snapshot — every param always
17
+ * transposition re-derives on the receiving end from its pref) plus the full prefs snapshot — every param always
19
18
  * emitted, so a link renders identically even if the defaults ever
20
19
  * change. Percent-encoding rides on `URLSearchParams`, whose decoding
21
20
  * the fragment parser mirrors. */
22
- export declare function buildShareLink(state: Pick<EditorState, 'script' | 'settings' | 'transforms'>): string;
21
+ export declare function buildShareLink(state: Pick<EditorState, 'script' | 'settings'>): string;