guidex 0.4.0 → 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 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
 
@@ -382,6 +382,132 @@ await downloadScorePng(el, { foreground: 'black', accent: '#008000', background:
382
382
  The script-tag runtime exposes the same functions on the `GuidexEmbed`
383
383
  global.
384
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
+
385
511
  ### React / Next.js
386
512
 
387
513
  ```jsx
@@ -393,7 +519,12 @@ import 'guidex/guidex.css'
393
519
 
394
520
  `GuidexScore` renders into a div on mount, re-renders on resize, and
395
521
  updates when the `script` prop changes. Props mirror the options below:
396
- `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.
397
528
 
398
529
  ### Options
399
530
 
@@ -405,6 +536,14 @@ updates when the `script` prop changes. Props mirror the options below:
405
536
  | `textPx` | base text size in px (notes render at 2×) | `18` |
406
537
  | `staffFill` | how far each staff runs: `all-but-last`, `none`, `all`, `longest` | `all-but-last` |
407
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` |
408
547
  | `transpose` | pitch-row shift (see `transposeBy`) | `0` |
409
548
  | `debug` | boolean (measurement titles on spans) | `false` |
410
549
 
@@ -445,7 +584,16 @@ content as a score, in place:
445
584
  ```
446
585
 
447
586
  Parameters ride data attributes on the div (same values as the options
448
- 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`;
449
597
  site-wide defaults can be set with
450
598
  `GuidexEmbed.init({ maxWidth: 'auto', style: 'BNS', … })`. Element
451
599
  attributes win over init options. New elements added after page load
@@ -471,6 +619,14 @@ its notes:
471
619
  - Every syllable of text precedes the parenthesized group of notes it is
472
620
  sung to.
473
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)).
474
630
  - The Guidohu dash (`-`) is pure whitespace; spaces are forbidden inside a
475
631
  notes line.
476
632
  - Marker characters (`,.:?'"+!%/=()ÖÜÓ;` = `SCORE_MARKERS`) carry no
@@ -510,6 +666,8 @@ its notes:
510
666
  written as `(@keep)(@keep)verse 1(@keep off)(@keep)verse 2(@keep off)(@keep off)`
511
667
  breaks between pairs of verses first, between verses next, and inside
512
668
  a verse last.
669
+ `(@stanza …)` statements at the very end hold further stanzas (see
670
+ [Stanzas](#stanzas)).
513
671
  - Style decorations on syllable text: `__…__` renders in the Liturgy
514
672
  font, bold; `_…_` renders small capitals (BNS) or italic (Vesperale);
515
673
  `*…*` marks an initial (bold, red in BNS). A syllable that is exactly
@@ -0,0 +1 @@
1
+ export declare function StaffSettings(): import('react').JSX.Element;
@@ -104,9 +104,15 @@ export type EditorAction = {
104
104
  } | {
105
105
  type: 'SET_STAFF_FILL';
106
106
  fill: StaffFill;
107
+ } | {
108
+ type: 'SET_RECITATION';
109
+ patch: Partial<Pick<RenderSettings, 'twoSyllableRecitationsToPlain' | 'plainRunsToRecitation'>>;
107
110
  } | {
108
111
  type: 'SET_STAFF_FILL_SNAP';
109
112
  px: number;
113
+ } | {
114
+ type: 'SET_STAFF';
115
+ patch: Partial<Pick<RenderSettings, StaffSettingKey | 'staffToEdges'>>;
110
116
  } | {
111
117
  type: 'SET_MAX_WIDTH';
112
118
  px: number;
@@ -204,6 +210,10 @@ export declare function buildEditorScript(state: Pick<EditorState, 'script' | 's
204
210
  scripts: GuidoScript[];
205
211
  transposeError: string | null;
206
212
  };
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];
207
217
  /** The render settings a saved chant snapshots: style, bold, base/chant
208
218
  * sizes with their decouple state, and transpose —
209
219
  * exactly what loading the chant re-applies. The max-width slider and
@@ -217,7 +227,7 @@ export declare function settingsSnapshot(state: EditorState): EditorSettings;
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' | 'staffFill' | 'staffFillSnapPx'>;
230
+ settings: Pick<RenderSettings, 'style' | 'bold' | 'transpose' | 'basePx' | 'decoupleNotes' | 'notesPx' | 'notesCustom' | 'junctionDashes' | 'staffFill' | 'staffFillSnapPx' | 'twoSyllableRecitationsToPlain' | 'plainRunsToRecitation' | StaffSettingKey>;
221
231
  inputs: {
222
232
  basePx: string;
223
233
  notesPx: string;