guidex 0.3.3 → 0.5.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/CHANGELOG.md +68 -0
- package/README.md +266 -37
- package/dist/lib/app/StaffSettings.d.ts +1 -0
- package/dist/lib/app/editorState.d.ts +32 -23
- package/dist/lib/app/shareLink.d.ts +2 -3
- package/dist/lib/{chantLayout-CVVuJUJl.js → chantLayout-BrCQUOhp.js} +980 -1142
- package/dist/lib/chantLayout.d.ts +32 -3
- package/dist/lib/chantMarkup.d.ts +63 -20
- package/dist/lib/drawnStaff.d.ts +130 -0
- package/dist/lib/editorStorage.d.ts +44 -4
- package/dist/lib/embed/core.d.ts +26 -4
- package/dist/lib/embed/index.js +1 -1
- package/dist/lib/embed/manual.d.ts +9 -3
- package/dist/lib/embed/manual.js +16 -49
- package/dist/lib/fonts/guidohu-staffless.woff2 +0 -0
- package/dist/lib/guidex.css +27 -0
- package/dist/lib/guidoRender.d.ts +22 -4
- package/dist/lib/guidoScript.d.ts +60 -23
- package/dist/lib/guidoScriptTransforms.d.ts +0 -18
- package/dist/lib/guidoStyles.d.ts +85 -74
- package/dist/lib/react/GuidexScore.d.ts +18 -6
- package/dist/lib/react/index.d.ts +2 -0
- package/dist/lib/react/index.js +47 -4
- package/dist/lib/recitationSegments.d.ts +93 -0
- package/dist/lib/scoreImage-B2SGdROL.js +8391 -0
- package/dist/lib/staffGlyphs.d.ts +12 -0
- package/dist/lib/stanzas.d.ts +6 -3
- package/dist/lib/textMarkup.d.ts +67 -0
- package/dist/lib/word/index.js +1 -1
- package/dist/lib/{wordChecker-DG09l_ol.js → wordChecker-CjYl2yof.js} +40 -13
- package/dist/lib/wordExport.d.ts +23 -4
- package/dist-embed/fonts/guidohu-staffless.woff2 +0 -0
- package/dist-embed/guidex-embed.min.css +1 -1
- package/dist-embed/guidex-embed.min.js +1 -1
- package/package.json +3 -2
- package/dist/lib/scoreImage-lvOrTbG-.js +0 -1009
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
What changed for users of the `guidex` package and the script-tag embed.
|
|
4
|
+
While guidex is on 0.x, a minor version can change rendered output; such
|
|
5
|
+
changes are listed under **Changed**, with the option that restores the old
|
|
6
|
+
output.
|
|
7
|
+
Versions before 0.5.0 have no changelog; their GitHub Releases list the
|
|
8
|
+
downloads.
|
|
9
|
+
|
|
10
|
+
## [0.5.0] - 2026-11-08
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **Drawn staff.** `staff: 'drawn'` sets the notes in a staffless copy of
|
|
15
|
+
Guido HU and draws each staff line behind them as one even stroke,
|
|
16
|
+
snapped to device pixels. The font's glyph-by-glyph staff overlaps and
|
|
17
|
+
antialiases unevenly. Layout, line breaks, selection and copied text are
|
|
18
|
+
unchanged (the staffless font keeps every advance width). Options, also
|
|
19
|
+
as `data-staff-*` attributes and `GuidexScore` props:
|
|
20
|
+
- `staffLines`: the fewest lines to draw (1–5). More are drawn when a note
|
|
21
|
+
would otherwise need a ledger line.
|
|
22
|
+
- `staffColor`, `staffLineColors` (by position) and `staffPitchColors` (by
|
|
23
|
+
the pitch a line carries under the clef in effect, e.g. yellow C and
|
|
24
|
+
red F lines). Any CSS color with alpha, or `{ light, dark }`.
|
|
25
|
+
- `staffWeight`, `staffLineWeights` and `staffClefLineWeight`: thickness
|
|
26
|
+
multipliers. The clef's own line can stand out.
|
|
27
|
+
- `staffOverflow: { start, end }` runs the lines past the score (e.g. to
|
|
28
|
+
the screen's edges) without resizing anything.
|
|
29
|
+
- `staffSnap`, and `snapStaff(el)` to snap again after moving a score.
|
|
30
|
+
|
|
31
|
+
See the README's *Drawn staff* section. The default stays the font's
|
|
32
|
+
staff.
|
|
33
|
+
- **Recitation options** (#21). `twoSyllableRecitationsToPlain` (default
|
|
34
|
+
`true`, see Changed) and `plainRunsToRecitation` (default `false`: 3 or
|
|
35
|
+
more plain notes of one pitch on a line draw as a recitation). Both are
|
|
36
|
+
available as render and Word-export options, as
|
|
37
|
+
`data-two-syllable-recitations-to-plain` /
|
|
38
|
+
`data-plain-runs-to-recitation`, and as `GuidexScore` props.
|
|
39
|
+
- New exports from `guidex`: `snapStaff`, `chooseStaffLines`, `staffSpans`,
|
|
40
|
+
`staffLineColor`, `staffLineWeight`, `parseStaffColor`,
|
|
41
|
+
`parseStaffLineColors`, `parseStaffPitchColors`, `parseStaffWeight`,
|
|
42
|
+
`parseStaffLineWeights`, `formatStaffColor`, `STAFFLESS_FONT_FAMILY`, and
|
|
43
|
+
the types `DrawnStaffOptions`, `StaffColor`, `StaffMode`,
|
|
44
|
+
`StaffOverflow`, `StaffLineRange`, `StaffSpan`, `PitchLetter`.
|
|
45
|
+
- README: documentation for stanzas (`stanza`, `stack`, `emptySlots`,
|
|
46
|
+
`stanzas`), note spacing (`junctionDashes`), held groups, `~` empty slots
|
|
47
|
+
and reciting notes. These shipped in earlier versions without docs.
|
|
48
|
+
|
|
49
|
+
### Changed
|
|
50
|
+
|
|
51
|
+
- **Rendered output:** a reciting glyph no longer covers exactly two
|
|
52
|
+
syllables on a line; the pair draws plain notes of the same pitch (`¦` →
|
|
53
|
+
`7`, an accidental kept). The rule is decided per line, after the line
|
|
54
|
+
breaks, and applies to the Word export too. For the old output set
|
|
55
|
+
`twoSyllableRecitationsToPlain: false`
|
|
56
|
+
(`data-two-syllable-recitations-to-plain="false"`).
|
|
57
|
+
|
|
58
|
+
### Fixed
|
|
59
|
+
|
|
60
|
+
- A note group cut at a line end and then moved to a fresh line no longer
|
|
61
|
+
leaves a lone fragment ending the line before it; the whole group moves
|
|
62
|
+
(#109).
|
|
63
|
+
|
|
64
|
+
### Upgrading
|
|
65
|
+
|
|
66
|
+
- Self-hosting the embed or the library's CSS: deploy the new
|
|
67
|
+
`fonts/guidohu-staffless.woff2` next to the other fonts. It is only
|
|
68
|
+
loaded for `staff: 'drawn'`.
|
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@ the scores.
|
|
|
6
6
|
Render plainchant scores from a compact script notation, set in Book
|
|
7
7
|
Antiqua with a true red (`#d40000`) as its hallmark. Works with a
|
|
8
8
|
bundler (vanilla JS, React, Next.js) or as a plain script tag on any
|
|
9
|
-
site.
|
|
9
|
+
site. What changed between versions is in [CHANGELOG.md](CHANGELOG.md).
|
|
10
10
|
|
|
11
11
|
## Install for bundler users
|
|
12
12
|
|
|
@@ -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`,
|
|
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
|
|
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,
|
|
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
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
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
|
-
|
|
125
|
-
//
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
//
|
|
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
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
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 |
|
|
166
|
+
|
|
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.
|
|
147
171
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
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
|
|
|
@@ -320,6 +382,132 @@ await downloadScorePng(el, { foreground: 'black', accent: '#008000', background:
|
|
|
320
382
|
The script-tag runtime exposes the same functions on the `GuidexEmbed`
|
|
321
383
|
global.
|
|
322
384
|
|
|
385
|
+
### Stanzas
|
|
386
|
+
|
|
387
|
+
A hymn's further stanzas ride at the end of its script, one
|
|
388
|
+
`(@stanza …)` statement each (stanza 2, 3, …), sung on the same melody:
|
|
389
|
+
|
|
390
|
+
```
|
|
391
|
+
(M)Te(3) lu(4)cis(5) an(4)te(3) ter(4)mi(5)num,(5-.) (@stanza Ut so-li-ta cle-men-ti-a,)
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
Stanza text: a space between words, `-` between syllables, `=` for a hyphen
|
|
395
|
+
that must show, a lone `-` to hold the previous syllable on the next note
|
|
396
|
+
group, a lone `~` to leave a group without text, and `\` to make any of
|
|
397
|
+
these literal. The count has to match the melody's note groups: a missing
|
|
398
|
+
syllable shows as an ellipsis, extra ones are dropped, and both come back
|
|
399
|
+
as warnings.
|
|
400
|
+
|
|
401
|
+
```js
|
|
402
|
+
// stanza 2 under the notes
|
|
403
|
+
const { warnings } = await renderScore(el, script, { stanza: 2 })
|
|
404
|
+
// every stanza stacked under one staff (or a list: [1, 3])
|
|
405
|
+
await renderScore(el, script, { stack: 'all' })
|
|
406
|
+
// stanza texts from elsewhere, replacing the script's (@stanza …)
|
|
407
|
+
await renderScore(el, script, { stanza: 2, stanzas: ['Ut so-li-ta cle-men-ti-a,'] })
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
`emptySlots` handles groups a stanza leaves empty while another sings
|
|
411
|
+
them: `normal` keeps them as they are, `small` draws them with small heads,
|
|
412
|
+
and `partial` draws every group that some stanza sings and another does not
|
|
413
|
+
with small heads, whatever is rendered. `renderScore` resolves with
|
|
414
|
+
`{ warnings }` (also logged to the console): the rendered stanzas' count
|
|
415
|
+
mismatches and malformed or unknown text markup.
|
|
416
|
+
|
|
417
|
+
### Recitations
|
|
418
|
+
|
|
419
|
+
A reciting note (`¦` and its family) carries a run of syllables on one
|
|
420
|
+
pitch. On a line, a run of 3 or more syllables recites, and a run of
|
|
421
|
+
exactly 2 draws plain notes of the same pitch instead (`¦` → `7`), because
|
|
422
|
+
a reciting glyph over two syllables reads badly. `twoSyllableRecitationsToPlain: false`
|
|
423
|
+
keeps the glyph. `plainRunsToRecitation: true` goes the other way: 3 or
|
|
424
|
+
more plain notes of one pitch on a line draw as a recitation. Both are
|
|
425
|
+
decided per line, after the line breaks, so a run split across lines is
|
|
426
|
+
counted on each line. The Word export follows the same rules.
|
|
427
|
+
|
|
428
|
+
### Drawn staff
|
|
429
|
+
|
|
430
|
+
Guido HU draws its staff glyph by glyph: every glyph carries its own piece
|
|
431
|
+
of each line, so on screen the lines overlap and antialias unevenly. With
|
|
432
|
+
`staff: 'drawn'` the notes are set in a staffless copy of the font (the
|
|
433
|
+
same advance widths, so the layout, line breaks, selection and copied text
|
|
434
|
+
do not change) and each staff line is drawn behind them as one even
|
|
435
|
+
stroke, snapped to whole device pixels. The lines can then take colors,
|
|
436
|
+
weights and a different count. The Word export keeps the font's own staff.
|
|
437
|
+
|
|
438
|
+
```js
|
|
439
|
+
import { renderScore } from 'guidex'
|
|
440
|
+
import 'guidex/guidex.css' // the staffless font and the line styles
|
|
441
|
+
|
|
442
|
+
await renderScore(el, '(@)Ad(3)iu(4)tó(4t)ri(4)um(3) nos(4)trum(3-:)', {
|
|
443
|
+
staff: 'drawn',
|
|
444
|
+
staffLines: 4, // fewest lines; more when needed
|
|
445
|
+
staffPitchColors: { c: { light: '#d9a400', dark: '#ffd24d' }, f: '#d40000' },
|
|
446
|
+
staffClefLineWeight: 1.8, // the clef's own line, heavier
|
|
447
|
+
})
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
| Option | Values | Default |
|
|
451
|
+
| ------ | ------ | ------- |
|
|
452
|
+
| `staff` | `font` (Guido HU's own lines) or `drawn` | `font` |
|
|
453
|
+
| `staffLines` | the fewest lines to draw, 1–5 | `5` |
|
|
454
|
+
| `staffColor` | a color for every drawn line | the notes' color |
|
|
455
|
+
| `staffLineColors` | colors by position, bottom line first | — |
|
|
456
|
+
| `staffPitchColors` | colors by the pitch a line carries, e.g. `{ c: 'gold', f: 'red' }` | — |
|
|
457
|
+
| `staffWeight` | thickness multiplier for every line | `1` |
|
|
458
|
+
| `staffLineWeights` | thickness multipliers by position, bottom line first | — |
|
|
459
|
+
| `staffClefLineWeight` | thickness multiplier for the line the clef sits on | `1` |
|
|
460
|
+
| `staffOverflow` | `{ start, end }`: run the lines past the score (see below) | — |
|
|
461
|
+
| `staffSnap` | snap the lines to device pixels after a render | `true` |
|
|
462
|
+
|
|
463
|
+
**Fewer lines.** The lines sit where the score needs them: the lowest run
|
|
464
|
+
of at least `staffLines` lines that carries every note and clef without a
|
|
465
|
+
ledger line. A note on a line needs that line, a note in a space needs a
|
|
466
|
+
line next to it, and a clef needs its own. When the notes need more lines
|
|
467
|
+
than asked for, more are drawn, so no note is left floating. The choice is
|
|
468
|
+
made once per score, so every system has the same lines.
|
|
469
|
+
|
|
470
|
+
**Colors.** A color is any CSS color, alpha included (`#0008`,
|
|
471
|
+
`rgb(0 0 0 / 0.5)`), or `{ light, dark }` for the two color schemes. The
|
|
472
|
+
dark one applies under an `html.dark` class or, without an `html.light`
|
|
473
|
+
class, when the system prefers dark. The most specific color wins:
|
|
474
|
+
`staffPitchColors` over `staffLineColors` over `staffColor`.
|
|
475
|
+
`staffPitchColors` follows the clef in effect and switches at inline clef
|
|
476
|
+
changes: under the c4 clef the lines are d f a c e (c is line 4), under the
|
|
477
|
+
g clef e g b d f (only the top line is an f, and no line is a c). Lines
|
|
478
|
+
without a color take the notes' own color. You can also theme them from
|
|
479
|
+
CSS by setting `--guidex-staff-light` / `--guidex-staff-dark` on any
|
|
480
|
+
ancestor.
|
|
481
|
+
|
|
482
|
+
**Weights.** Weights multiply: `staffWeight` × `staffLineWeights` ×
|
|
483
|
+
`staffClefLineWeight`. The clef line follows inline clef changes too, so
|
|
484
|
+
with an F clef on line 4 and `staffPitchColors: { f: 'red' }` the red line
|
|
485
|
+
is also the heavy one. A heavier line grows from the middle of the font's
|
|
486
|
+
line.
|
|
487
|
+
|
|
488
|
+
**Overflow.** `staffOverflow` runs every line from `start` to `end`, in px
|
|
489
|
+
from the notes line's left edge (a negative `start` reaches left of it). A
|
|
490
|
+
line that already runs further keeps its own end. Nothing is resized: the
|
|
491
|
+
lines just overflow the score and its container, so how far they go is up
|
|
492
|
+
to the page. To run them across the screen:
|
|
493
|
+
|
|
494
|
+
```js
|
|
495
|
+
const left = el.getBoundingClientRect().left
|
|
496
|
+
renderScore(el, script, {
|
|
497
|
+
staff: 'drawn',
|
|
498
|
+
staffOverflow: { start: -left, end: document.documentElement.clientWidth - left },
|
|
499
|
+
})
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
A scrolling or clipping ancestor (`overflow: auto | hidden`) cuts the lines
|
|
503
|
+
at its edges; make it `overflow: visible` (and clip the page with
|
|
504
|
+
`body { overflow-x: clip }` if you need to).
|
|
505
|
+
|
|
506
|
+
**Snapping.** A render snaps the lines when the score is in the document,
|
|
507
|
+
and embedded scores re-snap on window resize, which a browser zoom also
|
|
508
|
+
fires. If your page moves a score by a fraction of a pixel some other way,
|
|
509
|
+
call `snapStaff(el)` again.
|
|
510
|
+
|
|
323
511
|
### React / Next.js
|
|
324
512
|
|
|
325
513
|
```jsx
|
|
@@ -331,7 +519,12 @@ import 'guidex/guidex.css'
|
|
|
331
519
|
|
|
332
520
|
`GuidexScore` renders into a div on mount, re-renders on resize, and
|
|
333
521
|
updates when the `script` prop changes. Props mirror the options below:
|
|
334
|
-
`maxWidth`, `style`, `bold`, `textPx`, `transpose`, `debug`, `className
|
|
522
|
+
`maxWidth`, `style`, `bold`, `textPx`, `transpose`, `debug`, `className`,
|
|
523
|
+
the stanza, recitation and spacing options (`stanza`, `stack`, `stanzas`,
|
|
524
|
+
`emptySlots`, `onWarnings`, `twoSyllableRecitationsToPlain`,
|
|
525
|
+
`plainRunsToRecitation`, `junctionDashes`, `staffFill`, …), and the drawn
|
|
526
|
+
staff's options (`staff`, `staffLines`, `staffColor`, …). Inline arrays and
|
|
527
|
+
objects are fine: they are compared by content.
|
|
335
528
|
|
|
336
529
|
### Options
|
|
337
530
|
|
|
@@ -341,6 +534,16 @@ updates when the `script` prop changes. Props mirror the options below:
|
|
|
341
534
|
| `style` | `BNS`, `Vesperale` | `BNS` |
|
|
342
535
|
| `bold` | boolean | `false` |
|
|
343
536
|
| `textPx` | base text size in px (notes render at 2×) | `18` |
|
|
537
|
+
| `staffFill` | how far each staff runs: `all-but-last`, `none`, `all`, `longest` | `all-but-last` |
|
|
538
|
+
| `staffFillSnapPx` | with `longest`: fill to the full width when the longest line ends this close to it (`data-staff-fill-snap`) | `0` |
|
|
539
|
+
| `junctionDashes` | the dashes between note groups, in steps of a third (`2.67` is 2⅔); at least 1 | `3` |
|
|
540
|
+
| `twoSyllableRecitationsToPlain` | draw a 2-syllable recitation on a line as plain notes (see [Recitations](#recitations)) | `true` |
|
|
541
|
+
| `plainRunsToRecitation` | draw 3+ plain notes of one pitch on a line as a recitation | `false` |
|
|
542
|
+
| `stanza` | the stanza sung under the notes, 1-based (see [Stanzas](#stanzas)) | `1` |
|
|
543
|
+
| `stack` | stanzas stacked under one staff: `'all'` or a list (`data-stack="all"`, `"1,3"`) | — |
|
|
544
|
+
| `emptySlots` | groups a stanza leaves empty: `normal`, `small`, `partial` | `normal` |
|
|
545
|
+
| `stanzas` | stanza texts replacing the script's `(@stanza …)` (`renderScore` and React only) | — |
|
|
546
|
+
| `staff` and the other `staff…` options | see [Drawn staff](#drawn-staff) | `font` |
|
|
344
547
|
| `transpose` | pitch-row shift (see `transposeBy`) | `0` |
|
|
345
548
|
| `debug` | boolean (measurement titles on spans) | `false` |
|
|
346
549
|
|
|
@@ -355,6 +558,12 @@ overflow is the host page's to handle:
|
|
|
355
558
|
.my-score { overflow-x: auto; } /* or hidden, to clip */
|
|
356
559
|
```
|
|
357
560
|
|
|
561
|
+
`staffFill` sets where each staff stops. `all-but-last` fills every line
|
|
562
|
+
but the last to the available width, `none` stops every line at its own
|
|
563
|
+
notes, `all` fills every line, and `longest` ends every line with the
|
|
564
|
+
score's longest line, text included. Bars stay right after their notes,
|
|
565
|
+
with staff beyond them. With `maxWidth: Infinity`, `all` acts as `longest`.
|
|
566
|
+
|
|
358
567
|
## Embedding with a script tag (no bundler)
|
|
359
568
|
|
|
360
569
|
Host the `dist-embed/` folder (also attached to every GitHub Release)
|
|
@@ -375,7 +584,16 @@ content as a score, in place:
|
|
|
375
584
|
```
|
|
376
585
|
|
|
377
586
|
Parameters ride data attributes on the div (same values as the options
|
|
378
|
-
table above, kebab-cased: `data-max-width`, `data-text-px`,
|
|
587
|
+
table above, kebab-cased: `data-max-width`, `data-text-px`,
|
|
588
|
+
`data-junction-dashes`, `data-stanza`, `data-stack`, `data-empty-slots`,
|
|
589
|
+
and the boolean `data-two-syllable-recitations-to-plain` /
|
|
590
|
+
`data-plain-runs-to-recitation` (bare or `true`, or `false`). The drawn
|
|
591
|
+
staff takes `data-staff="drawn"`, `data-staff-lines`, `data-staff-color`
|
|
592
|
+
(a color or `light|dark`), `data-staff-line-colors` (bottom first,
|
|
593
|
+
separated by `;`), `data-staff-pitch-colors` (`c: gold; f: #d40000|#ff5a4f`),
|
|
594
|
+
`data-staff-weight`, `data-staff-line-weights` (`;`-separated),
|
|
595
|
+
`data-staff-clef-line-weight`, `data-staff-overflow-start`,
|
|
596
|
+
`data-staff-overflow-end` and `data-staff-snap`;
|
|
379
597
|
site-wide defaults can be set with
|
|
380
598
|
`GuidexEmbed.init({ maxWidth: 'auto', style: 'BNS', … })`. Element
|
|
381
599
|
attributes win over init options. New elements added after page load
|
|
@@ -401,6 +619,14 @@ its notes:
|
|
|
401
619
|
- Every syllable of text precedes the parenthesized group of notes it is
|
|
402
620
|
sung to.
|
|
403
621
|
- Whitespace in the source marks word boundaries between syllables.
|
|
622
|
+
- A note group with no text before it is held by the syllable before it:
|
|
623
|
+
`mé(3)(tT4R3E2)` sings `mé` on both groups. A syllable that is exactly
|
|
624
|
+
`~` has notes but no text (`~(4)`), and so does a text-less group right
|
|
625
|
+
after the clef.
|
|
626
|
+
- A reciting note (`Ÿ¡¢£[¥¦©ª«¬`) alone in a group, optionally after one
|
|
627
|
+
accidental, marks recited text: consecutive syllables on the same
|
|
628
|
+
reciting note flow on without junctions, the glyph showing at the run's
|
|
629
|
+
start and at every line start (see [Recitations](#recitations)).
|
|
404
630
|
- The Guidohu dash (`-`) is pure whitespace; spaces are forbidden inside a
|
|
405
631
|
notes line.
|
|
406
632
|
- Marker characters (`,.:?'"+!%/=()ÖÜÓ;` = `SCORE_MARKERS`) carry no
|
|
@@ -440,10 +666,13 @@ its notes:
|
|
|
440
666
|
written as `(@keep)(@keep)verse 1(@keep off)(@keep)verse 2(@keep off)(@keep off)`
|
|
441
667
|
breaks between pairs of verses first, between verses next, and inside
|
|
442
668
|
a verse last.
|
|
669
|
+
`(@stanza …)` statements at the very end hold further stanzas (see
|
|
670
|
+
[Stanzas](#stanzas)).
|
|
443
671
|
- Style decorations on syllable text: `__…__` renders in the Liturgy
|
|
444
|
-
font, bold; `_…_` renders small
|
|
672
|
+
font, bold; `_…_` renders small capitals (BNS) or italic (Vesperale);
|
|
445
673
|
`*…*` marks an initial (bold, red in BNS). A syllable that is exactly
|
|
446
|
-
`**` renders the mediant star glyph.
|
|
674
|
+
`**` renders the mediant star glyph. `{marks:…}` styles any stretch of
|
|
675
|
+
text (see *Styling text under the staff*).
|
|
447
676
|
|
|
448
677
|
In the rendered score, notes are set in the Guidohu font at twice the
|
|
449
678
|
surrounding text size. Notes are measured with a hidden canvas after
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function StaffSettings(): import('react').JSX.Element;
|
|
@@ -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 {
|
|
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
|
|
9
|
-
*
|
|
10
|
-
|
|
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,17 @@ export type EditorAction = {
|
|
|
103
102
|
type: 'SET_JUNCTION_DASHES';
|
|
104
103
|
dashes: number;
|
|
105
104
|
} | {
|
|
106
|
-
type: '
|
|
107
|
-
|
|
105
|
+
type: 'SET_STAFF_FILL';
|
|
106
|
+
fill: StaffFill;
|
|
107
|
+
} | {
|
|
108
|
+
type: 'SET_RECITATION';
|
|
109
|
+
patch: Partial<Pick<RenderSettings, 'twoSyllableRecitationsToPlain' | 'plainRunsToRecitation'>>;
|
|
110
|
+
} | {
|
|
111
|
+
type: 'SET_STAFF_FILL_SNAP';
|
|
112
|
+
px: number;
|
|
113
|
+
} | {
|
|
114
|
+
type: 'SET_STAFF';
|
|
115
|
+
patch: Partial<Pick<RenderSettings, StaffSettingKey | 'staffToEdges'>>;
|
|
108
116
|
} | {
|
|
109
117
|
type: 'SET_MAX_WIDTH';
|
|
110
118
|
px: number;
|
|
@@ -178,47 +186,48 @@ export type EditorAction = {
|
|
|
178
186
|
type: 'HIDE_FEEDBACK';
|
|
179
187
|
slot: FeedbackSlot;
|
|
180
188
|
};
|
|
181
|
-
export declare function hasInitialTransform(transforms: ScriptTransform[]): boolean;
|
|
182
189
|
/** Signed label for the transpose slider: `+2`, `0` or `-3`. */
|
|
183
190
|
export declare function transposeLabel(shift: number): string;
|
|
184
191
|
/** The editor script's stanza facts: how many stanzas the draft has,
|
|
185
192
|
* the one rendered (the picked one, or 1 when the draft no longer has
|
|
186
193
|
* it; `STACK_ALL` while a draft with stanzas stacks them all), and the
|
|
187
|
-
* rendered stanzas' count mismatches. */
|
|
194
|
+
* rendered stanzas' count mismatches and markup problems. */
|
|
188
195
|
export interface EditorStanzas {
|
|
189
196
|
count: number;
|
|
190
197
|
stanza: number;
|
|
191
|
-
warnings: StanzaWarning[];
|
|
198
|
+
warnings: (StanzaWarning | MarkWarning | SpanProblem)[];
|
|
192
199
|
}
|
|
193
200
|
/** The stanza facts of a draft. A draft that does not parse has one
|
|
194
201
|
* stanza — the render reports the parse error itself. */
|
|
195
|
-
export declare function editorStanzas(script: string, picked: StanzaInputs): EditorStanzas;
|
|
202
|
+
export declare function editorStanzas(script: string, picked: StanzaInputs, style?: StyleSetName): EditorStanzas;
|
|
196
203
|
/** Builds the editor script: the draft with the picked stanza swapped
|
|
197
|
-
* in, plus the
|
|
198
|
-
* sets, and the exact transposition. A failing exact transposition (out
|
|
204
|
+
* in, plus the transposition the slider sets and the exact one. A failing exact transposition (out
|
|
199
205
|
* of range, missing glyph) is left out and its message returned for the
|
|
200
206
|
* editor to show. `scripts` is what the preview renders: the script
|
|
201
207
|
* alone, or every stanza stacked (the script is then stanza 1's). */
|
|
202
|
-
export declare function buildEditorScript(state: Pick<EditorState, 'script' | '
|
|
208
|
+
export declare function buildEditorScript(state: Pick<EditorState, 'script' | 'settings' | 'exact'> & Partial<Pick<EditorState, 'stanza'>>): {
|
|
203
209
|
script: GuidoScript;
|
|
204
210
|
scripts: GuidoScript[];
|
|
205
211
|
transposeError: string | null;
|
|
206
212
|
};
|
|
207
|
-
/** The
|
|
208
|
-
*
|
|
213
|
+
/** The drawn staff's settings: saved with the settings, saved chants and
|
|
214
|
+
* share links like the other render settings. */
|
|
215
|
+
export declare const STAFF_SETTING_KEYS: readonly ["staff", "staffLines", "staffColor", "staffLineColors", "staffPitchColors", "staffWeight", "staffLineWeights", "staffClefLineWeight"];
|
|
216
|
+
export type StaffSettingKey = (typeof STAFF_SETTING_KEYS)[number];
|
|
217
|
+
/** The render settings a saved chant snapshots: style, bold, base/chant
|
|
218
|
+
* sizes with their decouple state, and transpose —
|
|
209
219
|
* exactly what loading the chant re-applies. The max-width slider and
|
|
210
220
|
* the color pickers are not part of a chant. */
|
|
211
|
-
export declare function chantPrefsSnapshot(state: Pick<EditorState, 'settings'
|
|
221
|
+
export declare function chantPrefsSnapshot(state: Pick<EditorState, 'settings'>): ChantPrefs;
|
|
212
222
|
/** The full settings blob for storage: the live render settings plus the
|
|
213
|
-
*
|
|
223
|
+
* Word-copy slice's effective values. */
|
|
214
224
|
export declare function settingsSnapshot(state: EditorState): EditorSettings;
|
|
215
225
|
/** The state overlay a ChantPrefs snapshot restores — shared by the
|
|
216
226
|
* LOAD_CHANT reducer case and the shared-link init (issue #63), so both
|
|
217
227
|
* ride the same handoff: a decoupled chant without a custom size adopts
|
|
218
228
|
* the derived 2× base size of the chant's own base font size. */
|
|
219
229
|
export declare function chantPrefsOverlay(prefs: ChantPrefs): {
|
|
220
|
-
settings: Pick<RenderSettings, 'style' | 'bold' | 'transpose' | 'basePx' | 'decoupleNotes' | 'notesPx' | 'notesCustom' | 'junctionDashes'>;
|
|
221
|
-
transforms: ScriptTransform[];
|
|
230
|
+
settings: Pick<RenderSettings, 'style' | 'bold' | 'transpose' | 'basePx' | 'decoupleNotes' | 'notesPx' | 'notesCustom' | 'junctionDashes' | 'staffFill' | 'staffFillSnapPx' | 'twoSyllableRecitationsToPlain' | 'plainRunsToRecitation' | StaffSettingKey>;
|
|
222
231
|
inputs: {
|
|
223
232
|
basePx: string;
|
|
224
233
|
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
|
-
*
|
|
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'
|
|
21
|
+
export declare function buildShareLink(state: Pick<EditorState, 'script' | 'settings'>): string;
|