guidex 0.3.1 → 0.3.3

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 (35) hide show
  1. package/README.md +81 -4
  2. package/dist/lib/app/EditorContext.d.ts +6 -1
  3. package/dist/lib/app/ExactTransposeControls.d.ts +1 -0
  4. package/dist/lib/app/StanzaControls.d.ts +1 -0
  5. package/dist/lib/app/TransposeSettings.d.ts +1 -0
  6. package/dist/lib/app/editorState.d.ts +81 -6
  7. package/dist/lib/app/shareLink.d.ts +22 -0
  8. package/dist/lib/chantLayout-CVVuJUJl.js +2778 -0
  9. package/dist/lib/chantLayout.d.ts +48 -8
  10. package/dist/lib/composeScript.d.ts +71 -0
  11. package/dist/lib/editorStorage.d.ts +11 -0
  12. package/dist/lib/embed/core.d.ts +34 -3
  13. package/dist/lib/embed/index.js +1 -1
  14. package/dist/lib/embed/manual.d.ts +12 -3
  15. package/dist/lib/embed/manual.js +348 -276
  16. package/dist/lib/exactTranspose.d.ts +54 -0
  17. package/dist/lib/glyphFamilies.d.ts +29 -0
  18. package/dist/lib/guidex.css +29 -2
  19. package/dist/lib/guidoRender.d.ts +7 -3
  20. package/dist/lib/guidoScript.d.ts +109 -10
  21. package/dist/lib/guidoScriptTransforms.d.ts +19 -7
  22. package/dist/lib/noteGroups.d.ts +22 -0
  23. package/dist/lib/react/GuidexScore.d.ts +21 -1
  24. package/dist/lib/react/index.d.ts +2 -1
  25. package/dist/lib/react/index.js +25 -3
  26. package/dist/lib/{scoreImage-oVBasBX5.js → scoreImage-lvOrTbG-.js} +111 -53
  27. package/dist/lib/stanzas.d.ts +135 -0
  28. package/dist/lib/word/index.js +1 -1
  29. package/dist/lib/{wordChecker-C3nJrk_j.js → wordChecker-DG09l_ol.js} +99 -46
  30. package/dist/lib/wordClipboard.d.ts +3 -3
  31. package/dist/lib/wordExport.d.ts +11 -5
  32. package/dist-embed/guidex-embed.min.css +1 -1
  33. package/dist-embed/guidex-embed.min.js +1 -1
  34. package/package.json +1 -1
  35. package/dist/lib/chantLayout-GAfg2iKS.js +0 -1042
package/README.md CHANGED
@@ -19,8 +19,10 @@ The package ships a typed ESM build with an exports map:
19
19
  - **`guidex`** — imperative API, no side effects:
20
20
  `renderScore(el, source, options?)`, `renderAll(root?)`,
21
21
  `init(options?)`, `dispose(el)`, plus the sung-text helpers
22
- (`chantText(script)`, the `GuidoScript` parser, `unescape`) and the
23
- style sets (`STYLE_SETS`, `DEFAULT_STYLE_SET`, `StyleSetName`).
22
+ (`chantText(script)`, the `GuidoScript` parser, `unescape`,
23
+ `scriptSyllables`), the script helpers (`PITCH_ROWS`, `transposeNotes`,
24
+ `SCORE_MARKERS`, `splitNoteMarkers`, `composeScript` — see *Combining
25
+ scripts* below) and the style sets (`STYLE_SETS`, `DEFAULT_STYLE_SET`, `StyleSetName`).
24
26
  Also the Word-compatible export: `toWordHtml(script, options?)`,
25
27
  `toWordText(script, options?)`, the clipboard writers
26
28
  `copyWordHtml` / `copyWordPlainText`, and the paste checker
@@ -64,6 +66,46 @@ new GuidoScript('(M)A(0) di(0q)e(qQ0)bus(1) an(3)ti(1e)quis(qQ0-:)').words
64
66
  // { text: 'antiquis', syllables: [{ text: 'an', notes: '3' }, { text: 'ti', notes: '1e' }, { text: 'quis', notes: 'qQ0-:' }] }]
65
67
  ```
66
68
 
69
+ `scriptSyllables(script)` walks the same syllables with their notes, held
70
+ groups, word starts and source offsets (held groups, `~` slots and
71
+ statements are skipped, so its count matches `chantText`):
72
+
73
+ ```js
74
+ import { scriptSyllables } from 'guidex'
75
+
76
+ scriptSyllables('(M)Ülj(11) az(0) ra,(qQ0-:) mon(3)')[2]
77
+ // { text: 'ra,', notes: 'qQ0-:', held: [], wordStart: true, wordEnd: true,
78
+ // start: 17, notesStart: 21, notesEnd: 26, end: 27, token: 2 }
79
+ ```
80
+
81
+ ### Combining scripts
82
+
83
+ `composeScript(parts, options?)` builds one script out of parts of others —
84
+ a slice of a script (`from`/`to` are `scriptSyllables` indices, `to`
85
+ exclusive), a text-less run of notes (written as `~(…)` empty slots), or a
86
+ sign (`intonation` = the BNS `**`, `bar`, `finalBar`). Parts join with a
87
+ word boundary. The first part's clef stays; a part in another clef or key
88
+ gets an inline `(@clef …)` / `(@key …)` (`clefs: 'inline'`, the default) or
89
+ is re-notated at the same sounding pitch (`clefs: 'renotate'`). `transpose`
90
+ takes staff degrees (a number) or a `transposeScript` target. Stanzas join
91
+ one by one; parts without a stanza get `~` there.
92
+
93
+ ```js
94
+ import { composeScript } from 'guidex'
95
+
96
+ const antiphon = '(M)Ülj(11) az(0) ra,(qQ0-:) mon(3)'
97
+ // An intonation: the antiphon through "ra," and a psalm-tone ending
98
+ composeScript([
99
+ { script: antiphon, to: 3, stripTrailingMarkers: true },
100
+ { marker: 'bar' },
101
+ { notes: ['4', '3', '4t', '4'] },
102
+ { marker: 'finalBar' },
103
+ ]) // '(M)Ülj(11) az(0) ra,(qQ0) ~(,--4--3--4t--4-.)'
104
+ // The reprise: the whole antiphon with the ** after the intonation
105
+ composeScript([{ script: antiphon, to: 3 }, { marker: 'intonation' }, { script: antiphon, from: 3 }])
106
+ // '(M)Ülj(11) az(0) ra,(qQ0-:) **() mon(3)'
107
+ ```
108
+
67
109
  ### Marked-up text
68
110
 
69
111
  The sung text with its markup, for displaying the text outside the
@@ -295,13 +337,24 @@ updates when the `script` prop changes. Props mirror the options below:
295
337
 
296
338
  | Option | Values | Default |
297
339
  | ----------- | ------------------------------- | -------------- |
298
- | `maxWidth` | pixels, or `auto` (fits the element, re-rendered on resize) | `auto` |
340
+ | `maxWidth` | pixels, `Infinity` (never break), or `auto` (fits the element, re-rendered on resize) | `auto` |
299
341
  | `style` | `BNS`, `Vesperale` | `BNS` |
300
342
  | `bold` | boolean | `false` |
301
343
  | `textPx` | base text size in px (notes render at 2×) | `18` |
302
344
  | `transpose` | pitch-row shift (see `transposeBy`) | `0` |
303
345
  | `debug` | boolean (measurement titles on spans) | `false` |
304
346
 
347
+ guidex breaks the lines itself and the browser never re-wraps them. With
348
+ `auto` every line fits the element, apart from a single note group too
349
+ wide for it. A number can be wider than the element, and `Infinity` (or
350
+ any large number; `data-max-width="Infinity"` works too) means "never
351
+ break". The score then grows past its container as one box, and the
352
+ overflow is the host page's to handle:
353
+
354
+ ```css
355
+ .my-score { overflow-x: auto; } /* or hidden, to clip */
356
+ ```
357
+
305
358
  ## Embedding with a script tag (no bundler)
306
359
 
307
360
  Host the `dist-embed/` folder (also attached to every GitHub Release)
@@ -341,7 +394,10 @@ its notes:
341
394
  (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-.)
342
395
  ```
343
396
 
344
- - The first parenthesized group is the starting clef with note modifiers.
397
+ - The first parenthesized group is the starting clef: one clef glyph
398
+ (c-clef `> # & @` on staff lines 1–4, f-clef `{ }` on lines 3–4,
399
+ g-clef `M` or `<` on line 2) followed by the key's modifier glyphs.
400
+ `(@)`/`(@X)` is the c4 clef.
345
401
  - Every syllable of text precedes the parenthesized group of notes it is
346
402
  sung to.
347
403
  - Whitespace in the source marks word boundaries between syllables.
@@ -355,6 +411,12 @@ its notes:
355
411
  follows: they hang in the junction whitespace, the syllable text is
356
412
  positioned under the note characters only, and a group starting with
357
413
  a modifier needs only a 2-dash junction.
414
+ - A bracketed accidental at the start of a note group (`ÄôŨ¨õÕö`: a
415
+ bracket pair `Â`/`Ã`, `Ä`/`Å` or `Æ`/`Ç` around accidental signs, plus
416
+ any `¨`/`-` right after it) hangs the same way: it adds staff width in
417
+ the white space before the group, the syllable text aligns with the
418
+ note after it, and the group takes the 2-dash junction. A line never
419
+ breaks inside it.
358
420
  - Control statements are groups whose content is an `@`-keyword, set
359
421
  between syllables where a syllable's text would stand:
360
422
  `(@break)` ends the current line pair at its position — the staff fills
@@ -363,6 +425,21 @@ its notes:
363
425
  is a parse error), and unknown `@` keywords are loud parse errors too.
364
426
  Max-width auto-breaking still applies within each stretch between
365
427
  forced breaks.
428
+ `(@clef &X)` changes the clef (and key) mid-score: the clef group is
429
+ written inline, and later lines open with it. `(@key X)` replaces the
430
+ key and `(@key)` clears it: up to the line end the affected notes (in
431
+ every octave) get their accidental sign, and later lines open with
432
+ the new key. Neither forces a line break.
433
+ `(@tight)` … `(@tight off)` sets a run of syllables one dash closer
434
+ (the `E u o u a e` of a psalm termination), `(@keep)` … `(@keep off)`
435
+ keeps a run on one line, and `(@unit)` … `(@unit off)` does both. Runs
436
+ nest, and each `off` closes one level; a run left open lasts to the end
437
+ of the script. Wide text still widens the notes inside a tight run. A
438
+ kept run wider than a whole line wraps normally, and one with kept runs
439
+ inside it dissolves into them, starting on its own line. So a hymn
440
+ written as `(@keep)(@keep)verse 1(@keep off)(@keep)verse 2(@keep off)(@keep off)`
441
+ breaks between pairs of verses first, between verses next, and inside
442
+ a verse last.
366
443
  - Style decorations on syllable text: `__…__` renders in the Liturgy
367
444
  font, bold; `_…_` renders small caps (BNS) or italic (Vesperale);
368
445
  `*…*` marks an initial (bold, red in BNS). A syllable that is exactly
@@ -1,11 +1,16 @@
1
1
  import { Dispatch, RefObject } from 'react';
2
2
  import { GuidoScript } from '../guidoScript';
3
3
  import { SavedChant } from '../editorStorage';
4
- import { EditorAction, EditorState, FeedbackSlot, SyllableRow } from './editorState';
4
+ import { EditorAction, EditorStanzas, EditorState, FeedbackSlot, SyllableRow } from './editorState';
5
5
  export interface EditorContextValue {
6
6
  state: EditorState;
7
7
  dispatch: Dispatch<EditorAction>;
8
8
  script: GuidoScript;
9
+ /** What the preview renders: the script, or every stanza stacked
10
+ * (issue #84; `script` is then stanza 1's). */
11
+ scripts: GuidoScript[];
12
+ /** The draft's stanza count, the rendered stanza and its mismatches. */
13
+ stanzas: EditorStanzas;
9
14
  syllableRows: SyllableRow[];
10
15
  scoreRef: RefObject<HTMLDivElement | null>;
11
16
  showFeedback: (slot: FeedbackSlot, message: string, error?: boolean) => void;
@@ -0,0 +1 @@
1
+ export declare function ExactTransposeControls(): import('react').JSX.Element;
@@ -0,0 +1 @@
1
+ export declare function StanzaControls(): import('react').JSX.Element | null;
@@ -0,0 +1 @@
1
+ export declare function TransposeSettings(): import('react').JSX.Element;
@@ -1,7 +1,8 @@
1
1
  import { ChantPrefs, EditorSettings, SavedChant } from '../editorStorage';
2
2
  import { StyleSetName } from '../guidoStyles';
3
- import { ScriptTransform } from '../guidoScriptTransforms';
3
+ import { ScriptTransform, TranspositionTarget } from '../guidoScriptTransforms';
4
4
  import { GuidoScript } from '../guidoScript';
5
+ import { EmptySlots, StanzaWarning } from '../stanzas';
5
6
  import { SpacerChar } from '../wordExport';
6
7
  import { WordInputs } from './wordCopy';
7
8
  /** The render settings minus the fields that live elsewhere: `word` has
@@ -10,7 +11,7 @@ import { WordInputs } from './wordCopy';
10
11
  export type RenderSettings = Omit<EditorSettings, 'word' | 'initial'>;
11
12
  /** Transient feedback slots: one `word-copy-feedback`-style span each,
12
13
  * shown for 4 s and cleared by their own timer (FeedbackSpan). */
13
- export type FeedbackSlot = 'draft' | 'copyScript' | 'downloadImage' | 'wordCopy' | 'chantSaved' | 'chantSaveForm' | 'chantList';
14
+ export type FeedbackSlot = 'draft' | 'copyScript' | 'copyLink' | 'downloadImage' | 'wordCopy' | 'chantSaved' | 'chantSaveForm' | 'chantList';
14
15
  export interface Feedback {
15
16
  message: string;
16
17
  error: boolean;
@@ -52,7 +53,37 @@ export interface EditorState {
52
53
  * already open — the form refocuses its name input. */
53
54
  focusNameSeq: number;
54
55
  feedback: Partial<Record<FeedbackSlot, Feedback>>;
56
+ /** The exact-transposition controls (issue #70); session-only. */
57
+ exact: ExactInputs;
58
+ /** The stanza picker (issue #69); session-only. */
59
+ stanza: StanzaInputs;
55
60
  }
61
+ /** The stanza picker: the stanza sung under the notes (1-based, or
62
+ * `STACK_ALL` for every stanza stacked under the staff, issue #84) and
63
+ * how the slots it leaves empty are drawn. */
64
+ export interface StanzaInputs {
65
+ stanza: number;
66
+ emptySlots: EmptySlots;
67
+ }
68
+ /** The stanza picker's "all, stacked" choice. */
69
+ export declare const STACK_ALL = 0;
70
+ export declare const INITIAL_STANZA: StanzaInputs;
71
+ /** The exact-transposition controls: `off`, a named interval with its
72
+ * direction, or a target final; plus an optional target clef (`''`
73
+ * keeps the clefs as written) and key (`'move'` moves it with the
74
+ * melody, otherwise a signed count of sharps/flats). */
75
+ export interface ExactInputs {
76
+ mode: 'off' | 'interval' | 'final';
77
+ interval: string;
78
+ direction: 'up' | 'down';
79
+ final: string;
80
+ clef: string;
81
+ key: string;
82
+ }
83
+ export declare const INITIAL_EXACT: ExactInputs;
84
+ /** The backend target the exact-transposition controls describe, or
85
+ * null when they are off. */
86
+ export declare function exactTarget(exact: ExactInputs): TranspositionTarget | null;
56
87
  export type EditorAction = {
57
88
  type: 'EDIT_SCRIPT';
58
89
  script: string;
@@ -68,6 +99,9 @@ export type EditorAction = {
68
99
  } | {
69
100
  type: 'SET_BOLD';
70
101
  bold: boolean;
102
+ } | {
103
+ type: 'SET_JUNCTION_DASHES';
104
+ dashes: number;
71
105
  } | {
72
106
  type: 'SET_INITIAL';
73
107
  initial: boolean;
@@ -77,6 +111,12 @@ export type EditorAction = {
77
111
  } | {
78
112
  type: 'SET_TRANSPOSE';
79
113
  shift: number;
114
+ } | {
115
+ type: 'SET_EXACT';
116
+ patch: Partial<ExactInputs>;
117
+ } | {
118
+ type: 'SET_STANZA';
119
+ patch: Partial<StanzaInputs>;
80
120
  } | {
81
121
  type: 'SET_BASE_PX';
82
122
  raw: string;
@@ -141,9 +181,29 @@ export type EditorAction = {
141
181
  export declare function hasInitialTransform(transforms: ScriptTransform[]): boolean;
142
182
  /** Signed label for the transpose slider: `+2`, `0` or `-3`. */
143
183
  export declare function transposeLabel(shift: number): string;
144
- /** Builds the editor script: the draft plus the transforms the
145
- * checkboxes enable and the transpose slider sets. */
146
- export declare function buildEditorScript(state: Pick<EditorState, 'script' | 'transforms' | 'settings'>): GuidoScript;
184
+ /** The editor script's stanza facts: how many stanzas the draft has,
185
+ * the one rendered (the picked one, or 1 when the draft no longer has
186
+ * it; `STACK_ALL` while a draft with stanzas stacks them all), and the
187
+ * rendered stanzas' count mismatches. */
188
+ export interface EditorStanzas {
189
+ count: number;
190
+ stanza: number;
191
+ warnings: StanzaWarning[];
192
+ }
193
+ /** The stanza facts of a draft. A draft that does not parse has one
194
+ * stanza — the render reports the parse error itself. */
195
+ export declare function editorStanzas(script: string, picked: StanzaInputs): EditorStanzas;
196
+ /** Builds the editor script: the draft with the picked stanza swapped
197
+ * in, plus the transforms the checkboxes enable, the transpose slider
198
+ * sets, and the exact transposition. A failing exact transposition (out
199
+ * of range, missing glyph) is left out and its message returned for the
200
+ * editor to show. `scripts` is what the preview renders: the script
201
+ * alone, or every stanza stacked (the script is then stanza 1's). */
202
+ export declare function buildEditorScript(state: Pick<EditorState, 'script' | 'transforms' | 'settings' | 'exact'> & Partial<Pick<EditorState, 'stanza'>>): {
203
+ script: GuidoScript;
204
+ scripts: GuidoScript[];
205
+ transposeError: string | null;
206
+ };
147
207
  /** The render settings a saved chant snapshots: style, bold, the initial
148
208
  * transform, base/chant sizes with their decouple state, and transpose —
149
209
  * exactly what loading the chant re-applies. The max-width slider and
@@ -152,8 +212,23 @@ export declare function chantPrefsSnapshot(state: Pick<EditorState, 'settings' |
152
212
  /** The full settings blob for storage: the live render settings plus the
153
213
  * derived `initial` flag and the Word-copy slice's effective values. */
154
214
  export declare function settingsSnapshot(state: EditorState): EditorSettings;
215
+ /** The state overlay a ChantPrefs snapshot restores — shared by the
216
+ * LOAD_CHANT reducer case and the shared-link init (issue #63), so both
217
+ * ride the same handoff: a decoupled chant without a custom size adopts
218
+ * the derived 2× base size of the chant's own base font size. */
219
+ export declare function chantPrefsOverlay(prefs: ChantPrefs): {
220
+ settings: Pick<RenderSettings, 'style' | 'bold' | 'transpose' | 'basePx' | 'decoupleNotes' | 'notesPx' | 'notesCustom' | 'junctionDashes'>;
221
+ transforms: ScriptTransform[];
222
+ inputs: {
223
+ basePx: string;
224
+ notesPx: string;
225
+ };
226
+ };
155
227
  /** The editor's initial state, read straight from storage — the restore
156
228
  * happens before the first render, so the controls mount already in the
157
- * restored state (one render, no first-frame flash). */
229
+ * restored state (one render, no first-frame flash). A shared-chant
230
+ * link (issue #63) overrides the draft: the fragment is the single
231
+ * source for the initial state, and the visitor's own draft is neither
232
+ * read nor written — viewing a shared chant must not clobber it. */
158
233
  export declare function initEditorState(): EditorState;
159
234
  export declare function editorReducer(state: EditorState, action: EditorAction): EditorState;
@@ -0,0 +1,22 @@
1
+ import { ChantPrefs } from '../editorStorage';
2
+ import { EditorState } from './editorState';
3
+ /** A chant carried by a share link: its raw script plus the render
4
+ * prefs the link specifies (absent or invalid params fall back to the
5
+ * fresh-browser defaults, via `sanitizeChantPrefs`). */
6
+ export interface SharedChant {
7
+ script: string;
8
+ prefs: ChantPrefs;
9
+ }
10
+ /** Parses a location hash into the shared chant it carries, or null
11
+ * when there is nothing to load — no hash at all, or no usable `script`
12
+ * param (without it the editor starts as today). Unknown params are
13
+ * ignored; the known ones go through the same defensive sanitization as
14
+ * the stored chant blobs. */
15
+ export declare function parseShareFragment(hash: string): SharedChant | null;
16
+ /** The share URL for the editor's current content: the raw script (the
17
+ * transforms re-derive on the receiving end from the `initial` and
18
+ * transpose prefs) plus the full prefs snapshot — every param always
19
+ * emitted, so a link renders identically even if the defaults ever
20
+ * change. Percent-encoding rides on `URLSearchParams`, whose decoding
21
+ * the fragment parser mirrors. */
22
+ export declare function buildShareLink(state: Pick<EditorState, 'script' | 'settings' | 'transforms'>): string;