guidex 0.3.1 → 0.3.2

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 (33) hide show
  1. package/README.md +53 -3
  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 +78 -6
  7. package/dist/lib/app/shareLink.d.ts +22 -0
  8. package/dist/lib/chantLayout-B0xiaMo9.js +2641 -0
  9. package/dist/lib/chantLayout.d.ts +41 -8
  10. package/dist/lib/composeScript.d.ts +71 -0
  11. package/dist/lib/editorStorage.d.ts +6 -0
  12. package/dist/lib/embed/core.d.ts +28 -2
  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 +324 -276
  16. package/dist/lib/exactTranspose.d.ts +54 -0
  17. package/dist/lib/glyphFamilies.d.ts +22 -0
  18. package/dist/lib/guidoRender.d.ts +5 -3
  19. package/dist/lib/guidoScript.d.ts +92 -10
  20. package/dist/lib/guidoScriptTransforms.d.ts +19 -7
  21. package/dist/lib/noteGroups.d.ts +22 -0
  22. package/dist/lib/react/GuidexScore.d.ts +19 -1
  23. package/dist/lib/react/index.d.ts +2 -1
  24. package/dist/lib/react/index.js +23 -3
  25. package/dist/lib/{scoreImage-oVBasBX5.js → scoreImage-DSEupCru.js} +102 -51
  26. package/dist/lib/stanzas.d.ts +135 -0
  27. package/dist/lib/word/index.js +1 -1
  28. package/dist/lib/{wordChecker-C3nJrk_j.js → wordChecker-EQx8frRp.js} +97 -45
  29. package/dist/lib/wordClipboard.d.ts +3 -3
  30. package/dist/lib/wordExport.d.ts +9 -5
  31. package/dist-embed/guidex-embed.min.js +1 -1
  32. package/package.json +1 -1
  33. 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
@@ -341,7 +383,10 @@ its notes:
341
383
  (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
384
  ```
343
385
 
344
- - The first parenthesized group is the starting clef with note modifiers.
386
+ - The first parenthesized group is the starting clef: one clef glyph
387
+ (c-clef `> # & @` on staff lines 1–4, f-clef `{ }` on lines 3–4,
388
+ g-clef `M` or `<` on line 2) followed by the key's modifier glyphs.
389
+ `(@)`/`(@X)` is the c4 clef.
345
390
  - Every syllable of text precedes the parenthesized group of notes it is
346
391
  sung to.
347
392
  - Whitespace in the source marks word boundaries between syllables.
@@ -363,6 +408,11 @@ its notes:
363
408
  is a parse error), and unknown `@` keywords are loud parse errors too.
364
409
  Max-width auto-breaking still applies within each stretch between
365
410
  forced breaks.
411
+ `(@clef &X)` changes the clef (and key) mid-score: the clef group is
412
+ written inline, and later lines open with it. `(@key X)` replaces the
413
+ key and `(@key)` clears it: up to the line end the affected notes (in
414
+ every octave) get their accidental sign, and later lines open with
415
+ the new key. Neither forces a line break.
366
416
  - Style decorations on syllable text: `__…__` renders in the Liturgy
367
417
  font, bold; `_…_` renders small caps (BNS) or italic (Vesperale);
368
418
  `*…*` 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;
@@ -77,6 +108,12 @@ export type EditorAction = {
77
108
  } | {
78
109
  type: 'SET_TRANSPOSE';
79
110
  shift: number;
111
+ } | {
112
+ type: 'SET_EXACT';
113
+ patch: Partial<ExactInputs>;
114
+ } | {
115
+ type: 'SET_STANZA';
116
+ patch: Partial<StanzaInputs>;
80
117
  } | {
81
118
  type: 'SET_BASE_PX';
82
119
  raw: string;
@@ -141,9 +178,29 @@ export type EditorAction = {
141
178
  export declare function hasInitialTransform(transforms: ScriptTransform[]): boolean;
142
179
  /** Signed label for the transpose slider: `+2`, `0` or `-3`. */
143
180
  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;
181
+ /** The editor script's stanza facts: how many stanzas the draft has,
182
+ * the one rendered (the picked one, or 1 when the draft no longer has
183
+ * it; `STACK_ALL` while a draft with stanzas stacks them all), and the
184
+ * rendered stanzas' count mismatches. */
185
+ export interface EditorStanzas {
186
+ count: number;
187
+ stanza: number;
188
+ warnings: StanzaWarning[];
189
+ }
190
+ /** The stanza facts of a draft. A draft that does not parse has one
191
+ * stanza — the render reports the parse error itself. */
192
+ export declare function editorStanzas(script: string, picked: StanzaInputs): EditorStanzas;
193
+ /** Builds the editor script: the draft with the picked stanza swapped
194
+ * in, plus the transforms the checkboxes enable, the transpose slider
195
+ * sets, and the exact transposition. A failing exact transposition (out
196
+ * of range, missing glyph) is left out and its message returned for the
197
+ * editor to show. `scripts` is what the preview renders: the script
198
+ * alone, or every stanza stacked (the script is then stanza 1's). */
199
+ export declare function buildEditorScript(state: Pick<EditorState, 'script' | 'transforms' | 'settings' | 'exact'> & Partial<Pick<EditorState, 'stanza'>>): {
200
+ script: GuidoScript;
201
+ scripts: GuidoScript[];
202
+ transposeError: string | null;
203
+ };
147
204
  /** The render settings a saved chant snapshots: style, bold, the initial
148
205
  * transform, base/chant sizes with their decouple state, and transpose —
149
206
  * exactly what loading the chant re-applies. The max-width slider and
@@ -152,8 +209,23 @@ export declare function chantPrefsSnapshot(state: Pick<EditorState, 'settings' |
152
209
  /** The full settings blob for storage: the live render settings plus the
153
210
  * derived `initial` flag and the Word-copy slice's effective values. */
154
211
  export declare function settingsSnapshot(state: EditorState): EditorSettings;
212
+ /** The state overlay a ChantPrefs snapshot restores — shared by the
213
+ * LOAD_CHANT reducer case and the shared-link init (issue #63), so both
214
+ * ride the same handoff: a decoupled chant without a custom size adopts
215
+ * the derived 2× base size of the chant's own base font size. */
216
+ export declare function chantPrefsOverlay(prefs: ChantPrefs): {
217
+ settings: Pick<RenderSettings, 'style' | 'bold' | 'transpose' | 'basePx' | 'decoupleNotes' | 'notesPx' | 'notesCustom'>;
218
+ transforms: ScriptTransform[];
219
+ inputs: {
220
+ basePx: string;
221
+ notesPx: string;
222
+ };
223
+ };
155
224
  /** The editor's initial state, read straight from storage — the restore
156
225
  * happens before the first render, so the controls mount already in the
157
- * restored state (one render, no first-frame flash). */
226
+ * restored state (one render, no first-frame flash). A shared-chant
227
+ * link (issue #63) overrides the draft: the fragment is the single
228
+ * source for the initial state, and the visitor's own draft is neither
229
+ * read nor written — viewing a shared chant must not clobber it. */
158
230
  export declare function initEditorState(): EditorState;
159
231
  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;