guidex 0.5.0 → 0.6.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.
Files changed (86) hide show
  1. package/CHANGELOG.md +215 -0
  2. package/README.md +62 -16
  3. package/dist/lib/app/App.d.ts +1 -0
  4. package/dist/lib/app/AretinoControls.d.ts +35 -0
  5. package/dist/lib/app/CaretBand.d.ts +28 -0
  6. package/dist/lib/app/Developers.d.ts +13 -0
  7. package/dist/lib/app/EditorContext.d.ts +15 -0
  8. package/dist/lib/app/EditorTextarea.d.ts +18 -1
  9. package/dist/lib/app/EditorToolbar.d.ts +13 -0
  10. package/dist/lib/app/ExportSettings.d.ts +20 -1
  11. package/dist/lib/app/Footer.d.ts +1 -0
  12. package/dist/lib/app/GlyphChooser.d.ts +31 -0
  13. package/dist/lib/app/Inspector.d.ts +26 -0
  14. package/dist/lib/app/LiveScore.d.ts +31 -0
  15. package/dist/lib/app/Opening.d.ts +3 -0
  16. package/dist/lib/app/Reference.d.ts +28 -0
  17. package/dist/lib/app/RenderSettings.d.ts +2 -1
  18. package/dist/lib/app/ScriptViews.d.ts +8 -0
  19. package/dist/lib/app/SectionSize.d.ts +33 -0
  20. package/dist/lib/app/StaffSettings.d.ts +4 -0
  21. package/dist/lib/app/StaffedGlyph.d.ts +8 -0
  22. package/dist/lib/app/Tabs.d.ts +15 -0
  23. package/dist/lib/app/TakeItOut.d.ts +1 -0
  24. package/dist/lib/app/ThemeSwitch.d.ts +1 -0
  25. package/dist/lib/app/TopBar.d.ts +6 -0
  26. package/dist/lib/app/WidthControls.d.ts +21 -0
  27. package/dist/lib/app/aretinoCaret.d.ts +47 -0
  28. package/dist/lib/app/aretinoSource.d.ts +46 -0
  29. package/dist/lib/app/caretSync.d.ts +48 -0
  30. package/dist/lib/app/chantLibrary.d.ts +8 -4
  31. package/dist/lib/app/editorSnapshot.d.ts +11 -0
  32. package/dist/lib/app/editorState.d.ts +38 -5
  33. package/dist/lib/app/expandLink.d.ts +19 -0
  34. package/dist/lib/app/glyphData.d.ts +37 -0
  35. package/dist/lib/app/inCode.d.ts +4 -0
  36. package/dist/lib/app/insertAtCaret.d.ts +12 -0
  37. package/dist/lib/app/learn/Learn.d.ts +1 -0
  38. package/dist/lib/app/learn/LessonCard.d.ts +12 -0
  39. package/dist/lib/app/learn/lessons.d.ts +64 -0
  40. package/dist/lib/app/learn/narrowing.d.ts +24 -0
  41. package/dist/lib/app/learn/progress.d.ts +14 -0
  42. package/dist/lib/app/pageEvents.d.ts +14 -0
  43. package/dist/lib/app/previewHighlight.d.ts +44 -0
  44. package/dist/lib/app/samples.d.ts +9 -1
  45. package/dist/lib/app/scriptParts.d.ts +31 -0
  46. package/dist/lib/app/shareLink.d.ts +12 -2
  47. package/dist/lib/app/showcases/Showcases.d.ts +17 -0
  48. package/dist/lib/app/wordCopy.d.ts +4 -0
  49. package/dist/lib/aretino/fromAretino.d.ts +99 -0
  50. package/dist/lib/aretino/index.d.ts +38 -0
  51. package/dist/lib/aretino/index.js +1870 -0
  52. package/dist/lib/aretino/toAretino.d.ts +27 -0
  53. package/dist/lib/chantLayout-BRQ6FYND.js +1345 -0
  54. package/dist/lib/chantLayout.d.ts +101 -6
  55. package/dist/lib/chantMarkup-DX4K86Rv.js +993 -0
  56. package/dist/lib/drawnStaff.d.ts +39 -5
  57. package/dist/lib/editorStorage.d.ts +48 -6
  58. package/dist/lib/embed/core.d.ts +15 -1
  59. package/dist/lib/embed/index.js +1 -1
  60. package/dist/lib/embed/manual.d.ts +5 -4
  61. package/dist/lib/embed/manual.js +6 -4
  62. package/dist/lib/fonts/guidohu-staffless.woff2 +0 -0
  63. package/dist/lib/fonts/guidohu.ttf +0 -0
  64. package/dist/lib/glyphFamilies.d.ts +5 -1
  65. package/dist/lib/guidoRender.d.ts +30 -1
  66. package/dist/lib/guidoScriptTransforms.d.ts +2 -2
  67. package/dist/lib/guidoStyles-CvnACCsk.js +1466 -0
  68. package/dist/lib/guidoStyles.d.ts +23 -2
  69. package/dist/lib/react/GuidexScore.d.ts +10 -2
  70. package/dist/lib/react/index.js +14 -4
  71. package/dist/lib/{scoreImage-B2SGdROL.js → scoreImage-CKsQxHg5.js} +282 -1026
  72. package/dist/lib/theme.d.ts +13 -0
  73. package/dist/lib/word/index.d.ts +1 -1
  74. package/dist/lib/word/index.js +1 -1
  75. package/dist/lib/{wordChecker-CjYl2yof.js → wordChecker-BN_9dKAx.js} +133 -20
  76. package/dist/lib/wordChecker.d.ts +18 -1
  77. package/dist/lib/wordExport.d.ts +51 -3
  78. package/dist-embed/demo.html +2 -2
  79. package/dist-embed/fonts/guidohu-staffless.woff2 +0 -0
  80. package/dist-embed/fonts/guidohu.ttf +0 -0
  81. package/dist-embed/guidex-embed.min.js +1 -1
  82. package/package.json +10 -1
  83. package/dist/lib/app/ControlsRow.d.ts +0 -1
  84. package/dist/lib/app/SettingsMenu.d.ts +0 -1
  85. package/dist/lib/app/SettingsPanel.d.ts +0 -1
  86. package/dist/lib/chantLayout-BrCQUOhp.js +0 -2616
package/CHANGELOG.md CHANGED
@@ -7,6 +7,221 @@ output.
7
7
  Versions before 0.5.0 have no changelog; their GitHub Releases list the
8
8
  downloads.
9
9
 
10
+ ## [0.6.0] - 2026-11-18
11
+
12
+ ### Added
13
+
14
+ - `guidex/aretino`: conversion between Aretino chant notation and GuidoScript,
15
+ both ways. `aretinoToGuido(source)` returns `{ script, stanzas, warnings,
16
+ lost, metadata, error? }`, `guidoToAretino(script)` returns `{ aretino,
17
+ warnings, lost, error? }`. A GuidoScript sent to Aretino and back comes back
18
+ in the spelling Aretino implies (connectors and virgas re-derived, source
19
+ spacing normalised), and converting it again changes nothing.
20
+ `ARETINO_CONVERTER_VERSION` numbers the Aretino reader: it goes up only
21
+ when `aretinoToGuido` writes different GuidoScript, so a host that stores
22
+ Aretino sources can tell when their scores may have changed.
23
+ `@aretino-chant/core` is a new optional peer dependency, needed only for
24
+ this entry.
25
+ - Reciting notes (longas) on a, b, c' and a'': `€`, `Ž`, `ž` and `¤`, added
26
+ to Guido HU and its staffless copy. They recite like the others, transpose
27
+ in the same row (a reciting note moved past g'' or below d' no longer stops
28
+ at the row's end) and pair with their plain notes, so a run on c' now
29
+ recites, and `plainRunsToRecitation` turns plain runs on these pitches into
30
+ recitations as well.
31
+ - The editor's glyph chooser, under the script (the Glyphs button hides
32
+ it): the Guido HU glyphs by kind (pitches, virga, joined, small heads,
33
+ reciting, cephalicus and strokes, accidentals, bars and marks, clefs) and
34
+ the statements. A click writes the key at the caret, undoable like
35
+ typing; each key shows the glyph and the character that types it.
36
+ - The editor's script is inked as it is typed: note groups, the clef and
37
+ statements in the group red, the syllable text in ink, as in the opening.
38
+ - `sourceMap` (a render option): each syllable span carries `data-syl`, its
39
+ index among `GuidoScript.syllables`, and `data-notes-start` /
40
+ `data-notes-width`, its notes' run on the notes line, and each notes line
41
+ carries `data-groups` (`syllable:from:to` for every group piece on it: a
42
+ split group has one on each line), so a host can tie the score back to
43
+ its script. Off by default; nothing else changes. The layout carries the
44
+ same as `SylSegment.syllable` and `LayoutLine.groups`.
45
+ - The editor follows the caret: the syllable it is in is banded on the score
46
+ and tinted in the script (with its held groups, on every line a split
47
+ group reaches), and the neume the caret is in takes a deeper shade, and a click on a syllable in the score puts the
48
+ caret into its notes ("Follow the caret" turns it off).
49
+ - An Unbound line width in the editor's Layout tab: the whole chant on one
50
+ line, never broken, scrolling sideways (the caret band follows it); the
51
+ width comes back when it is unticked. Kept with the editor settings.
52
+ - Studio, the expanded and full screen editor's layout: one bar on top, the
53
+ score filling the left column, and a rail with the script over the
54
+ settings tabs, the glyph chooser first; a bar between them shares the
55
+ rail. The score scrolls to keep the caret's syllable in view.
56
+ - `paddingPx`: the line's padding, the room for the break star `*` at the
57
+ end of the line width, in px (default: the style set's `padding`, 12 in
58
+ both built-in sets). A render, `layoutScore` and Word-export option, the
59
+ embed's `paddingPx` / `data-padding`, a `GuidexScore` prop, and the
60
+ editor's "Padding" slider in Render settings (saved with the settings,
61
+ saved chants and share links as `padding`; Copy for Word uses it too).
62
+ Changing it never changes the line width.
63
+ - `textFont`: the syllable text in an installed font, by name. The style
64
+ set's stack stays behind it as the fallback (so a missing font falls back
65
+ without misaligning anything: the layout measures the same fallback), and
66
+ marks with a font of their own keep it. A render, `layoutScore` and Word
67
+ export option (Copy for Word names it in the `BNS-textus` style, so Word
68
+ needs it installed), the embed's `data-text-font`, a `GuidexScore` prop,
69
+ and the editor's Text font field (suggesting the installed book faces it
70
+ finds, and saying when a typed font is not installed), saved with the
71
+ settings, saved chants and share links. `isFontAvailable(name)` and
72
+ `cleanFontName` are exported helpers.
73
+ - `clefMark: 'line'`: a line without its clef glyph. The drawn staff marks
74
+ the clef's own line instead (`staffClefLineColor`, which follows inline
75
+ clef changes and wins over the other colors; by default red in BNS, and
76
+ 2.5× heavier in black-and-white Vesperale), keys stay, and the line takes
77
+ the padding on the left too, with the staff running through it and the
78
+ first syllable free to lean into it; the line width stays the same. A
79
+ render, `layoutScore` and embed option (`data-clef-mark`,
80
+ `data-staff-clef-line-color`), `GuidexScore` props, and the editor's Staff
81
+ settings' Clef section), saved with the settings, saved chants and share
82
+ links. It needs the drawn staff: with `staff: 'font'`, and in the Word
83
+ export, the glyph stays. `staffClefLineColor: 'none'` (or
84
+ `data-staff-clef-line-color="none"`) gives the clef line no color of its
85
+ own, the style set's included, so the pitch, position and line colors
86
+ show through; `parseClefLineColor` reads the text form.
87
+ - `checkWordHtml(html, { expectedTabIntervalPt })`: with tab spacers, the
88
+ paste checker reports a document whose Default tab stops differ from the
89
+ interval the copy was made with (Word keeps the document's own interval
90
+ when it pastes, so the tabs land on the wrong grid), naming both values
91
+ and where to set them. Without the option it checks as before.
92
+ - The editor says what to set up in Word while its Tabs spacer is picked:
93
+ the document's Default tab stops at the spacer width, in cm and pt, and
94
+ where to find the setting.
95
+
96
+ ### Changed
97
+
98
+ - d's cephalicus is now `'` in the glyph table (`toCephalicus('1')`, the
99
+ Reference), as typists write it; Guido HU draws `ÿ` the same, and `ÿ` stays
100
+ readable as an alias (`GLYPH_ALIASES`): `baseOf`, the staff-degree and the
101
+ exact transposition treat it as `'`. A transposition that lands on d's
102
+ cephalicus now writes `'` where it wrote `ÿ`, and a `'` against a note moves
103
+ with the melody instead of staying put.
104
+ - An empty slot (`~(…)`, such as an alleluia jubilus written after
105
+ `ia.(…-:) **()`) that does not fit at a line end is now cut at its `-`/`¨`
106
+ to fill the line, exactly as the same notes under a syllable are, instead
107
+ of moving whole to the next line and leaving the alleluia line mostly
108
+ empty. Held groups (a note group with no text, held by the syllable before
109
+ it) still move whole and are cut only when they overflow the fresh line.
110
+ The option `cutEmptySlots: false` (`layoutScore`, `GuidoRender.render`, the
111
+ Word export, the embed's `cutEmptySlots` / `data-cut-empty-slots`, and
112
+ `GuidexScore`) restores the old breaks.
113
+ - A `**()` star right after a group ending in a bar (`,` `:` `;`, doubled or
114
+ not, then any dashes or `¨`) is drawn centred under the bar, taking no
115
+ room, so the notes and the other syllables stand where they would without
116
+ the star. When the line breaks right after the bar, the bar stays and the
117
+ star leads the next line, under its first note or before its first text.
118
+ It used to stand before the next syllable with text, which in an
119
+ alleluia was after the whole jubilus, before the `V.`; in a few scripts it
120
+ also pushed that syllable's notes right. A star after a group with no bar
121
+ is unchanged. In the Word export the star goes into the text line at the
122
+ same place, and the next spacer run takes its width back. The option
123
+ `starUnderBar: false` (`layoutScore`, `GuidoRender.render`, the Word
124
+ export) restores the old placement.
125
+ - The layout's text segments have a new kind, `mark` (`MarkSegment`): the
126
+ star under a bar, at `textStart`, standing in the flow at `flowPx` and
127
+ taking no room. Code that walks `LayoutTextLine.segments` should draw it
128
+ or skip it.
129
+ - **Rendered output: the staff is drawn by default.** Every score sets its
130
+ notes in the staffless Guido HU and draws the staff lines behind them
131
+ (`staff: 'drawn'`), in the renderer, the embed, `GuidexScore` and the
132
+ editor. Notes, text and line breaks land exactly where they did; the
133
+ difference is the staff itself: one even stroke per line, snapped to
134
+ device pixels, instead of the font's glyph-by-glyph lines. The DOM gains
135
+ the staff layer (a `.guidex-staff` span at the start of each notes line)
136
+ and `data-staff="drawn"` on the render container. The Word export keeps
137
+ the font's staff. For the old output set `staff: 'font'`
138
+ (`data-staff="font"`, `<GuidexScore staff="font">`), or
139
+ `init({ staff: 'font' })` for a whole page.
140
+ - The editor lists "drawn" before "from the font" in its Staff settings and
141
+ starts with the drawn staff. Settings, saved chants and share links from
142
+ before 0.5.0, which have no staff setting, now draw it.
143
+ - **The editor moves saved 0.5.x data to the drawn staff, once.** 0.5.0 and
144
+ 0.5.1 stored `staff: 'font'` in every settings blob, saved chant and
145
+ share link whether or not anyone chose it. The editor's storage schema is
146
+ now version 2: a version 1 settings blob or chant library is read with
147
+ its font staff turned into the drawn staff, every other setting kept, and
148
+ written back as version 2, so this happens once. Share links gain `v=2`;
149
+ a link without it that says `staff=font` opens on the drawn staff, a link
150
+ with it keeps `staff=font`. Anyone who picked the font staff on purpose
151
+ in 0.5.x picks it again once, and it stays. The embed and the package
152
+ API store nothing and are not affected.
153
+ - **Transposition: reciting notes go past d' and g''.** `transposeBy` moves
154
+ a reciting note onto the new tenors instead of stopping at the end of its
155
+ row (`¬` up a step was `¬`, now `¤`; `Ÿ` down a step was `Ÿ`, now `ž`);
156
+ the row now ends at a and a''. The exact transposition, which threw for a
157
+ reciting note moved onto a, b, c' or a'' (no such glyph), now writes it.
158
+ No option restores the old stop; a score that relied on it should
159
+ transpose by fewer steps.
160
+ - **Rendered output with `plainRunsToRecitation`:** plain runs on a, b, c'
161
+ and a'' now recite as well (three `0` on a line draw one `ž`), as runs on
162
+ the other pitches already did. Off by default, so nothing changes unless
163
+ it is on; there is no option to keep these four pitches plain while
164
+ reciting the rest.
165
+
166
+ ### Fixed
167
+
168
+ - `toSmallPoint` (and the glyph data under it) knows the small points on b
169
+ (`` ` ``) and a'' (`n`), which Guido HU draws.
170
+ - **Word export: the text lines up under the notes in Word.** The notes
171
+ were copied with `letter-spacing:-.1pt`, which the layout never measured,
172
+ so Word drew every note 0.1pt further left per character than the text's
173
+ spacers aimed at: the syllables drifted right of their notes along each
174
+ line, several points by its end, whatever the spacer width. The notes
175
+ now carry an explicit `letter-spacing:0pt` (so a document style that
176
+ condenses its notes cannot move them either), and the spacer counts and
177
+ line breaks are unchanged. The new `notesLetterSpacingPt` option (and
178
+ `layoutScore`'s `notesLetterSpacingPx`) condenses the notes again, with
179
+ the layout measuring it; `WordLayout.notesLetterSpacingPt` tells `.docx`
180
+ builders which spacing to set. The paste checker warns when the notes
181
+ come back with another spacing.
182
+ - **The line width includes the padding.** `maxWidthPx` (and the Word
183
+ export's `maxWidthPt`, the document's column) is the whole line: the break
184
+ star's right edge lands on it and the notes break the padding short of it.
185
+ The star used to hang the padding past the width, so in a Word document
186
+ with exactly that column every broken notes line wrapped, and a 700px
187
+ editor line was 712px wide. An `auto` width already worked this way.
188
+ - **Word export: a hyphen no longer sticks to the next syllable** (`ec -ce`).
189
+ The spacers on its two sides round together, the odd one after the dash.
190
+ - The `BNS-nota` style has 6pt above and below.
191
+
192
+ ### Upgrading
193
+
194
+ - **Rendered output: fixed-width scores break 12px earlier**, since the
195
+ line width now includes the padding. For the old line breaks, add the
196
+ padding to the width (`maxWidthPx: w + 12`, or `paddingPx: 0` to keep the
197
+ breaks and put the star at the width).
198
+ - Every score now loads `fonts/guidohu-staffless.woff2`. Self-hosting the
199
+ embed or the library's CSS: make sure it is deployed next to the other
200
+ fonts. When it cannot load, the score shows the "Font could not be
201
+ loaded" error note rather than notes without a staff; `staff: 'font'`
202
+ does not need it.
203
+ - Code that reads a notes line's first child as its text should skip the
204
+ staff layer (it holds no text, so `textContent` is unchanged).
205
+ - Opening the editor once converts its stored settings and chant library to
206
+ schema version 2. A 0.5.x editor opened afterwards in the same browser
207
+ ignores version 2 data (it shows its defaults) and does not overwrite it.
208
+ - A hand-built share link that wants the font staff writes `staff=font&v=2`.
209
+
210
+ ## [0.5.1] - 2026-11-09
211
+
212
+ ### Fixed
213
+
214
+ - **`Ô` transposes** (#119). The connector from c′ down two steps to a had
215
+ no pitch, so `transposeScript`, `transposeExact` and `transposeBy` left it
216
+ in place and wrote a wrong note. It now belongs to the `0` family (as `×`
217
+ belongs to `1`): `gClefPitchOf('Ô')` is `c'`, and `PITCH_ROWS` lists it at
218
+ the start of the connect-two-down row.
219
+
220
+ ### Upgrading
221
+
222
+ - No changes needed. Transposed scores that contain `Ô` now come out
223
+ right.
224
+
10
225
  ## [0.5.0] - 2026-11-08
11
226
 
12
227
  ### Added
package/README.md CHANGED
@@ -35,6 +35,13 @@ The package ships a typed ESM build with an exports map:
35
35
  `layoutForWord(script, options?)`, the layout as structured lines for
36
36
  building `.docx` documents directly (see *Structured Word layout*
37
37
  below). Browser-only, like the rest: it measures with canvas.
38
+ - **`guidex/aretino`** — conversion between [Aretino](https://github.com/aretino-chant/aretino-chant)
39
+ chant notation and GuidoScript, both ways: `aretinoToGuido(source)` and
40
+ `guidoToAretino(script)`, each returning the result with `warnings` and
41
+ what the other notation cannot say (`lost`). A GuidoScript sent to Aretino
42
+ and back comes back in guidex's ideal spelling, and a second trip changes
43
+ nothing. `@aretino-chant/core` (Aretino's parser) is an optional peer
44
+ dependency; only users of this entry install it. Works outside the browser.
38
45
  - **`guidex/embed`** — the same API plus auto-render: importing it scans
39
46
  the document for `.guido-script` elements immediately, like the script
40
47
  tag. Don't use this in frameworks that re-render the DOM.
@@ -122,7 +129,7 @@ hold only initials the script itself writes.
122
129
  ```js
123
130
  import { chantHtml, chantRuns } from 'guidex'
124
131
 
125
- const script = '(c4)__V.__() *Psa*lmus(1) **(2) De(7)us(2)'
132
+ const script = '(@)__V.__() *Psa*lmus(1) **(2) De(7)us(2)'
126
133
 
127
134
  chantHtml(script) // '<span class="liturgy">V.</span> <span class="initial">Psa</span>lmus <span class="star">∗</span> Deus'
128
135
  chantHtml(script, { roles: ['sung'], classPrefix: 'gx-' })
@@ -198,6 +205,20 @@ renders plainly and comes back in the render's `warnings`
198
205
  A label or a sign may stand on spacing and a bar (`**(-----,,)`); guidex
199
206
  leaves the choice of bars to the author.
200
207
 
208
+ A `**()` star right after a group that ends in a bar (`,` `:` `;`, doubled
209
+ or not, then any dashes or `¨`) is drawn centred under that bar, the way the
210
+ Graduale prints the end of the intonation: `ia.(tT4-:) **() ~(4u¨78…-.)`.
211
+ The bar keeps its marker spacing, and the star takes no room: no note or
212
+ syllable moves compared with the script without it, and it is pushed right
213
+ of the text before it rather than under it. When the line breaks right after
214
+ the bar, the bar stays at the end of the line and the star leads the next
215
+ one: under the first note of a text-less group (the rest of the jubilus), or
216
+ a word space before the text of a syllable, in the clef's lead-in. After a group with no bar (`e(5) **() sci(5)`) it stands between
217
+ the syllables as before. The Word export can't overlay, so it writes the star
218
+ into the text line at that place, and the next spacer run takes the width
219
+ back. `starUnderBar: false` (a `layoutScore`, render and Word option) turns
220
+ this off.
221
+
201
222
  ### The Liturgy font
202
223
 
203
224
  `liturgy.ttf` maps exactly five characters; anything else in a `__…__` run
@@ -270,6 +291,17 @@ inside Word after pasting. Plain spaces are the fragile choice:
270
291
  survive every paste path — Word can collapse the runs into a single
271
292
  space. Prefer the default no-break spaces or en/em.
272
293
 
294
+ **Tabs need the document set up first.** The copy carries its tab
295
+ interval, but only as a document setting (`tab-interval` on `<body>`),
296
+ and Word keeps the destination document's own **Default tab stops**
297
+ when it pastes, so the tab spacers would land on that grid instead. Set
298
+ the document's Default tab stops to the spacer width before pasting —
299
+ 0.5 mm is 0.05 cm (1.42 pt): on Windows Home › Paragraph dialog
300
+ launcher › Tabs… › Default tab stops, on a Mac Format › Tabs… › Default
301
+ tab stops. It applies to the whole document, so other tabbed text there
302
+ moves too. The no-break space spacer needs no setup. The editor shows
303
+ this note, with the value, while its Tabs spacer is picked.
304
+
273
305
  Marker glyphs travel Word-safely too: the `**` star (U+2217, which no
274
306
  Times-family font has a glyph for) is emitted as the Symbol-font `*`
275
307
  marker run that Word documents already use — the same shape the paste
@@ -299,6 +331,14 @@ report.styleNames // e.g. ['BNS-nota', 'BNS-textus Char1']
299
331
  report.gapCensus // spacer mechanism + effective width per gap class
300
332
  ```
301
333
 
334
+ Pass the interval a tab copy was made with, and the checker reports a
335
+ document whose Default tab stops differ, with both values and where to
336
+ set them:
337
+
338
+ ```js
339
+ checkWordHtml(pastedHtml, { expectedTabIntervalPt: 1.42 })
340
+ ```
341
+
302
342
  #### Structured Word layout
303
343
 
304
344
  To assemble Word documents yourself (e.g. with the `docx` library)
@@ -427,20 +467,21 @@ counted on each line. The Word export follows the same rules.
427
467
 
428
468
  ### Drawn staff
429
469
 
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.
470
+ The staff is drawn by default. Guido HU draws its staff glyph by glyph:
471
+ every glyph carries its own piece of each line, so on screen the lines
472
+ overlap and antialias unevenly. Instead, the notes are set in a staffless
473
+ copy of the font (the same advance widths, so the layout, line breaks,
474
+ selection and copied text do not change) and each staff line is drawn
475
+ behind them as one even stroke, snapped to whole device pixels. The lines
476
+ can then take colors, weights and a different count. `staff: 'font'`
477
+ (`data-staff="font"` in the embed) keeps Guido HU's own lines instead, as
478
+ earlier releases did. The Word export always keeps the font's own staff.
437
479
 
438
480
  ```js
439
481
  import { renderScore } from 'guidex'
440
482
  import 'guidex/guidex.css' // the staffless font and the line styles
441
483
 
442
484
  await renderScore(el, '(@)Ad(3)iu(4)tó(4t)ri(4)um(3) nos(4)trum(3-:)', {
443
- staff: 'drawn',
444
485
  staffLines: 4, // fewest lines; more when needed
445
486
  staffPitchColors: { c: { light: '#d9a400', dark: '#ffd24d' }, f: '#d40000' },
446
487
  staffClefLineWeight: 1.8, // the clef's own line, heavier
@@ -449,7 +490,7 @@ await renderScore(el, '(@)Ad(3)iu(4)tó(4t)ri(4)um(3) nos(4)trum(3-:)', {
449
490
 
450
491
  | Option | Values | Default |
451
492
  | ------ | ------ | ------- |
452
- | `staff` | `font` (Guido HU's own lines) or `drawn` | `font` |
493
+ | `staff` | `drawn` or `font` (Guido HU's own lines) | `drawn` |
453
494
  | `staffLines` | the fewest lines to draw, 1–5 | `5` |
454
495
  | `staffColor` | a color for every drawn line | the notes' color |
455
496
  | `staffLineColors` | colors by position, bottom line first | — |
@@ -494,7 +535,6 @@ to the page. To run them across the screen:
494
535
  ```js
495
536
  const left = el.getBoundingClientRect().left
496
537
  renderScore(el, script, {
497
- staff: 'drawn',
498
538
  staffOverflow: { start: -left, end: document.documentElement.clientWidth - left },
499
539
  })
500
540
  ```
@@ -543,7 +583,7 @@ objects are fine: they are compared by content.
543
583
  | `stack` | stanzas stacked under one staff: `'all'` or a list (`data-stack="all"`, `"1,3"`) | — |
544
584
  | `emptySlots` | groups a stanza leaves empty: `normal`, `small`, `partial` | `normal` |
545
585
  | `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` |
586
+ | `staff` and the other `staff…` options | see [Drawn staff](#drawn-staff) | `drawn` |
547
587
  | `transpose` | pitch-row shift (see `transposeBy`) | `0` |
548
588
  | `debug` | boolean (measurement titles on spans) | `false` |
549
589
 
@@ -574,6 +614,11 @@ on any static server or CDN and drop it into a site's `<head>`:
574
614
  <script src="https://your-host/path/guidex-embed.min.js"></script>
575
615
  ```
576
616
 
617
+ Keep the `fonts/` folder next to the stylesheet: the scores load the Book
618
+ Antiqua, Guido HU and staffless Guido HU (`guidohu-staffless.woff2`, for the
619
+ drawn staff, the default) faces from it. A score whose font cannot load
620
+ shows an error note instead of drawing without it.
621
+
577
622
  Any element classed `guido-script` (or `guidex-script`) renders its text
578
623
  content as a score, in place:
579
624
 
@@ -587,8 +632,9 @@ Parameters ride data attributes on the div (same values as the options
587
632
  table above, kebab-cased: `data-max-width`, `data-text-px`,
588
633
  `data-junction-dashes`, `data-stanza`, `data-stack`, `data-empty-slots`,
589
634
  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`
635
+ `data-plain-runs-to-recitation` (bare or `true`, or `false`). The staff is
636
+ drawn unless `data-staff="font"` keeps the font's own lines; the drawn
637
+ staff takes `data-staff-lines`, `data-staff-color`
592
638
  (a color or `light|dark`), `data-staff-line-colors` (bottom first,
593
639
  separated by `;`), `data-staff-pitch-colors` (`c: gold; f: #d40000|#ff5a4f`),
594
640
  `data-staff-weight`, `data-staff-line-weights` (`;`-separated),
@@ -609,7 +655,7 @@ The source alternates a leading clef group with syllables, each followed by
609
655
  its notes:
610
656
 
611
657
  ```
612
- (MX)Ki(3)rály(3)ként(5) tró(7i)nol(7-:) *() az(7i) Úr(5-/) mind(5)ö(4t)rök(3)ké.(3-.)
658
+ (MX)Ki(3)rály(3)ként(5) tró(7i)nol(7-:) *() az(7i) Úr(5-/) mind(5)ö(4t)rök(3)re.(3-.)
613
659
  ```
614
660
 
615
661
  - The first parenthesized group is the starting clef: one clef glyph
@@ -623,7 +669,7 @@ its notes:
623
669
  `mé(3)(tT4R3E2)` sings `mé` on both groups. A syllable that is exactly
624
670
  `~` has notes but no text (`~(4)`), and so does a text-less group right
625
671
  after the clef.
626
- - A reciting note (`Ÿ¡¢£[¥¦©ª«¬`) alone in a group, optionally after one
672
+ - A reciting note (`€ŽžŸ¡¢£[¥¦©ª«¬¤`) alone in a group, optionally after one
627
673
  accidental, marks recited text: consecutive syllables on the same
628
674
  reciting note flow on without junctions, the glyph showing at the run's
629
675
  start and at every line start (see [Recitations](#recitations)).
@@ -0,0 +1 @@
1
+ export declare function App(): import('react').JSX.Element;
@@ -0,0 +1,35 @@
1
+ import { RefObject } from 'react';
2
+ import { ScriptSyntax } from '../editorStorage';
3
+ /** GuidoScript | Aretino above the script. Picking the other one opens the
4
+ * panel that says what the switch changes; nothing switches until it is
5
+ * confirmed. */
6
+ export declare function SyntaxSwitch({ onAsk }: {
7
+ onAsk: (to: ScriptSyntax) => void;
8
+ }): import('react').JSX.Element;
9
+ /** The switch panel: converts the source, lists what changes, and switches
10
+ * on confirm. A switch is one undo step (UNDO_SWITCH). */
11
+ export declare function SwitchPanel({ to, onClose }: {
12
+ to: ScriptSyntax;
13
+ onClose: () => void;
14
+ }): import('react').JSX.Element;
15
+ /** After a switch: the note that offers it back until the next edit. */
16
+ export declare function SwitchNote(): import('react').JSX.Element | null;
17
+ /** Pasted Aretino in a GuidoScript chant: an offer to read it as Aretino.
18
+ * Nothing switches by itself; the text stays as pasted. */
19
+ export declare function PasteOffer({ onDone }: {
20
+ onDone: () => void;
21
+ }): import('react').JSX.Element;
22
+ /** Under an Aretino source: whether it converted, and how much it left out. */
23
+ export declare function AretinoStatus({ onShow }: {
24
+ onShow: () => void;
25
+ }): import('react').JSX.Element | null;
26
+ /** Aretino's own palette, in place of the glyph chooser while the chant is
27
+ * Aretino: a click types at the caret. */
28
+ export declare function AretinoPalette({ inputRef, hidden }: {
29
+ inputRef: RefObject<HTMLTextAreaElement | null>;
30
+ hidden?: boolean;
31
+ }): import('react').JSX.Element;
32
+ /** The Conversion view: what the Aretino source said that the score cannot. */
33
+ export declare function ConversionView(): import('react').JSX.Element;
34
+ /** The GuidoScript view: the script an Aretino source converts to, read-only. */
35
+ export declare function GuidoScriptView(): import('react').JSX.Element;
@@ -0,0 +1,28 @@
1
+ import { RefObject } from 'react';
2
+ import { CaretTarget } from './caretSync';
3
+ interface Box {
4
+ left: number;
5
+ top: number;
6
+ width: number;
7
+ height: number;
8
+ }
9
+ interface Bands {
10
+ run: Box[];
11
+ neume: Box[];
12
+ }
13
+ /** Both shades of the band for `target` in `host`, relative to `frame`. */
14
+ export declare function caretBands(host: HTMLElement, frame: HTMLElement, target: CaretTarget): Bands;
15
+ /** Scrolls the nearest sideways scroller around `el` just enough to show it
16
+ * with `INLINE_MARGIN` to spare, and nothing vertically. */
17
+ export declare function scrollInline(el: HTMLElement): void;
18
+ export declare function CaretBand({ hostRef, frameRef, target, renderSeq, follow, }: {
19
+ hostRef: RefObject<HTMLElement | null>;
20
+ frameRef: RefObject<HTMLElement | null>;
21
+ target: CaretTarget | null;
22
+ renderSeq: number;
23
+ /** How the bands are kept in view when they move: `both` scrolls every
24
+ * scroller (the Studio panes), `inline` only the score's own sideways
25
+ * scroll, never the page (the page layout, where the script is in view) */
26
+ follow: 'both' | 'inline';
27
+ }): import('react').JSX.Element | null;
28
+ export {};
@@ -0,0 +1,13 @@
1
+ import { LiveScoreOptions, ScoreSource } from './LiveScore';
2
+ export declare const README_URL = "https://github.com/BrownieMaar/guidex#readme";
3
+ export declare const NPM_URL = "https://www.npmjs.com/package/guidex";
4
+ export declare const GITHUB_URL = "https://github.com/BrownieMaar/guidex";
5
+ /** The score a script-tag snippet describes: the text of its first
6
+ * `.guido-script` / `.guidex-script` element and the data attributes the
7
+ * page understands. Null when there is no such element. */
8
+ export declare function readAttributes(html: string): {
9
+ source: ScoreSource;
10
+ options: LiveScoreOptions;
11
+ width: number | 'auto';
12
+ } | null;
13
+ export declare function Developers(): import('react').JSX.Element;
@@ -1,22 +1,37 @@
1
1
  import { Dispatch, RefObject } from 'react';
2
2
  import { GuidoScript } from '../guidoScript';
3
3
  import { SavedChant } from '../editorStorage';
4
+ import { SourceConversion } from './aretinoSource';
4
5
  import { EditorAction, EditorStanzas, EditorState, FeedbackSlot, SyllableRow } from './editorState';
5
6
  export interface EditorContextValue {
6
7
  state: EditorState;
7
8
  dispatch: Dispatch<EditorAction>;
8
9
  script: GuidoScript;
10
+ /** The draft as GuidoScript: the draft itself, or what an Aretino draft
11
+ * converts to (issue #79), with what that conversion could not keep */
12
+ conversion: SourceConversion;
9
13
  /** What the preview renders: the script, or every stanza stacked
10
14
  * (issue #84; `script` is then stanza 1's). */
11
15
  scripts: GuidoScript[];
12
16
  /** The draft's stanza count, the rendered stanza and its mismatches. */
13
17
  stanzas: EditorStanzas;
14
18
  syllableRows: SyllableRow[];
19
+ /** Everything wrong with the draft as rendered: the transposition and
20
+ * render failures, the stanza mismatches and the markup warnings. */
21
+ problems: EditorProblem[];
22
+ /** The lines the live preview drew at this width, null until it has. */
23
+ lineCount: number | null;
15
24
  scoreRef: RefObject<HTMLDivElement | null>;
16
25
  showFeedback: (slot: FeedbackSlot, message: string, error?: boolean) => void;
17
26
  /** Applies one library action's intent over a fresh read of storage
18
27
  * and writes the result; failures surface as visible feedback. */
19
28
  persistChants: (apply: (fresh: SavedChant[]) => SavedChant[] | null) => boolean;
20
29
  }
30
+ export interface EditorProblem {
31
+ message: string;
32
+ /** An error stops something from showing (the score or its
33
+ * transposition); a warning only flags what renders. */
34
+ severity: 'error' | 'warning';
35
+ }
21
36
  export declare const EditorContext: import('react').Context<EditorContextValue | null>;
22
37
  export declare function useEditor(): EditorContextValue;
@@ -1 +1,18 @@
1
- export declare function EditorTextarea(): import('react').JSX.Element;
1
+ import { RefObject } from 'react';
2
+ export declare function EditorTextarea({ inputRef, current, onPaste }?: {
3
+ inputRef?: RefObject<HTMLTextAreaElement | null>;
4
+ /** The caret's syllable with its held groups, and the neume the caret
5
+ * is in (source offsets), tinted in the inked copy in two shades */
6
+ current?: {
7
+ run: {
8
+ start: number;
9
+ end: number;
10
+ };
11
+ neume: {
12
+ start: number;
13
+ end: number;
14
+ } | null;
15
+ } | null;
16
+ /** A paste landed: the pasted text and the whole script after it */
17
+ onPaste?: (text: string, whole: string) => void;
18
+ }): import('react').JSX.Element;
@@ -0,0 +1,13 @@
1
+ /** The name of what the editor holds: the sample or saved chant it was
2
+ * loaded from, or null once the script has been edited by hand. */
3
+ export declare function chantName(activeChipId: string | null, chants: {
4
+ id: string;
5
+ name: string;
6
+ }[]): string | null;
7
+ export declare function EditorToolbar({ libraryOpen, onToggleLibrary }: {
8
+ libraryOpen: boolean;
9
+ onToggleLibrary: () => void;
10
+ }): import('react').JSX.Element;
11
+ export declare function LibraryDrawer({ open }: {
12
+ open: boolean;
13
+ }): import('react').JSX.Element;
@@ -1 +1,20 @@
1
- export declare function ExportSettings(): import('react').JSX.Element;
1
+ /** Copies a link that opens this chant in the editor (issue #63): the
2
+ * raw script plus the render prefs ride in the URL fragment, so the
3
+ * receiving page renders the same score — the transposition re-derives
4
+ * there from the pref the link carries. An empty script has nothing to
5
+ * share: the parser rejects blank ones, so copying one would only mislead
6
+ * with a success note. */
7
+ export declare function ShareLinkButton(): import('react').JSX.Element;
8
+ /** Copies the editor script as the score renders it — the stanza and
9
+ * the transpositions applied to the raw source — so a transposed chant
10
+ * can be pasted wherever the script itself is needed. */
11
+ export declare function ScriptExport(): import('react').JSX.Element;
12
+ /** Exports the live editor score as a PNG — the foreignObject capture in
13
+ * scoreImage.ts rasterizes the same DOM the page paints, so the picture
14
+ * matches the preview by construction. The buffer is looked up at click
15
+ * time (every render swaps in a fresh one); a failed render leaves nothing
16
+ * to export. The custom-colors pickers remap the ink: text and accent
17
+ * colors (seeded from the live theme when enabled) with an optional solid
18
+ * background — off, the export keeps the displayed colors on a transparent
19
+ * canvas. */
20
+ export declare function ImageExport(): import('react').JSX.Element;
@@ -0,0 +1 @@
1
+ export declare function Footer(): import('react').JSX.Element;
@@ -0,0 +1,31 @@
1
+ import { RefObject } from 'react';
2
+ import { TabSpec } from './Tabs';
3
+ /** One key of the chooser. */
4
+ export interface GlyphKey {
5
+ /** What a click writes at the caret. */
6
+ insert: string;
7
+ /** Characters to leave the caret before the end of `insert`. */
8
+ caretBack?: number;
9
+ /** How the key draws it in Guido HU; absent for a text key. */
10
+ show?: string;
11
+ /** The text under the glyph: the key as typed. */
12
+ label: string;
13
+ /** What it is, for its accessible name and title. */
14
+ name: string;
15
+ }
16
+ export interface GlyphRow {
17
+ title?: string;
18
+ keys: GlyphKey[];
19
+ }
20
+ export type GlyphTab = 'pitches' | 'virga' | 'joined' | 'small' | 'reciting' | 'shapes' | 'accidentals' | 'marks' | 'clefs' | 'statements';
21
+ export declare const GLYPH_TABS: readonly TabSpec<GlyphTab>[];
22
+ /** Every tab's rows of keys. */
23
+ export declare function glyphRows(): Record<GlyphTab, GlyphRow[]>;
24
+ export declare function GlyphChooser({ inputRef, hidden, compact }: {
25
+ inputRef: RefObject<HTMLTextAreaElement | null>;
26
+ /** Closed: kept in the document (the Glyphs button points at it). */
27
+ hidden?: boolean;
28
+ /** For a narrow column (the Studio rail): the groups in a dropdown
29
+ * instead of a row of tabs */
30
+ compact?: boolean;
31
+ }): import('react').JSX.Element;
@@ -0,0 +1,26 @@
1
+ import { ReactNode } from 'react';
2
+ export declare const INSPECTOR_TABS: readonly [{
3
+ readonly id: "layout";
4
+ readonly label: "Layout";
5
+ }, {
6
+ readonly id: "text";
7
+ readonly label: "Text";
8
+ }, {
9
+ readonly id: "staff";
10
+ readonly label: "Staff";
11
+ }, {
12
+ readonly id: "pitch";
13
+ readonly label: "Pitch";
14
+ }, {
15
+ readonly id: "stanzas";
16
+ readonly label: "Stanzas";
17
+ }, {
18
+ readonly id: "export";
19
+ readonly label: "Export";
20
+ }];
21
+ /** In the Studio layout the glyph chooser is the inspector's first tab. */
22
+ export type InspectorTab = (typeof INSPECTOR_TABS)[number]['id'] | 'glyphs';
23
+ export declare function Inspector({ glyphs }?: {
24
+ /** The glyph chooser, for a Glyphs tab before the settings (Studio) */
25
+ glyphs?: ReactNode;
26
+ }): import('react').JSX.Element;