guidex 0.3.0 → 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.
- package/README.md +69 -3
- package/dist/lib/app/EditorContext.d.ts +6 -1
- package/dist/lib/app/ExactTransposeControls.d.ts +1 -0
- package/dist/lib/app/StanzaControls.d.ts +1 -0
- package/dist/lib/app/TransposeSettings.d.ts +1 -0
- package/dist/lib/app/editorState.d.ts +78 -6
- package/dist/lib/app/shareLink.d.ts +22 -0
- package/dist/lib/chantLayout-B0xiaMo9.js +2641 -0
- package/dist/lib/chantLayout.d.ts +41 -8
- package/dist/lib/composeScript.d.ts +71 -0
- package/dist/lib/editorStorage.d.ts +6 -0
- package/dist/lib/embed/core.d.ts +28 -2
- package/dist/lib/embed/index.js +1 -1
- package/dist/lib/embed/manual.d.ts +13 -3
- package/dist/lib/embed/manual.js +324 -4
- package/dist/lib/exactTranspose.d.ts +54 -0
- package/dist/lib/glyphFamilies.d.ts +68 -0
- package/dist/lib/guidoRender.d.ts +5 -3
- package/dist/lib/guidoScript.d.ts +92 -10
- package/dist/lib/guidoScriptTransforms.d.ts +19 -7
- package/dist/lib/noteGroups.d.ts +22 -0
- package/dist/lib/react/GuidexScore.d.ts +19 -1
- package/dist/lib/react/index.d.ts +2 -1
- package/dist/lib/react/index.js +23 -3
- package/dist/lib/{scoreImage-DnFIbtF_.js → scoreImage-DSEupCru.js} +102 -51
- package/dist/lib/stanzas.d.ts +135 -0
- package/dist/lib/word/index.js +1 -1
- package/dist/lib/{wordChecker-C3nJrk_j.js → wordChecker-EQx8frRp.js} +97 -45
- package/dist/lib/wordClipboard.d.ts +3 -3
- package/dist/lib/wordExport.d.ts +9 -5
- package/dist-embed/guidex-embed.min.js +1 -1
- package/package.json +1 -1
- 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
|
|
23
|
-
|
|
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
|
|
@@ -229,6 +271,22 @@ A run with `symbol` set (the `**` star) has no glyph in the destination
|
|
|
229
271
|
fonts: emit `symbol.char` in `symbol.font` (the Symbol asterisk) instead
|
|
230
272
|
of its text. Absent run fields inherit the textus paragraph style.
|
|
231
273
|
|
|
274
|
+
### Glyph families
|
|
275
|
+
|
|
276
|
+
The variant glyphs of each pitch glyph, for building notation tools on top
|
|
277
|
+
of the font: `toVirga`, `toLonga`, `toSmallHead`, `toCephalicus`,
|
|
278
|
+
`toConnectDown(ch, 1–4)`, `toSmallPoint`, the accidentals `modifyUp`,
|
|
279
|
+
`modifyDown`, `modifyNatural`, and `baseOf` for the reverse lookup. Each
|
|
280
|
+
returns `undefined` when the pitch has no such variant.
|
|
281
|
+
|
|
282
|
+
```js
|
|
283
|
+
import { toVirga, modifyUp, baseOf } from 'guidex'
|
|
284
|
+
|
|
285
|
+
toVirga('1') // 'q'
|
|
286
|
+
modifyUp('1') // 'Ì'
|
|
287
|
+
baseOf('q') // { base: '1', role: 'virga' }
|
|
288
|
+
```
|
|
289
|
+
|
|
232
290
|
### Image export
|
|
233
291
|
|
|
234
292
|
Take a rendered score out as an image. The export captures the very DOM
|
|
@@ -325,7 +383,10 @@ its notes:
|
|
|
325
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-.)
|
|
326
384
|
```
|
|
327
385
|
|
|
328
|
-
- The first parenthesized group is the starting clef
|
|
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.
|
|
329
390
|
- Every syllable of text precedes the parenthesized group of notes it is
|
|
330
391
|
sung to.
|
|
331
392
|
- Whitespace in the source marks word boundaries between syllables.
|
|
@@ -347,6 +408,11 @@ its notes:
|
|
|
347
408
|
is a parse error), and unknown `@` keywords are loud parse errors too.
|
|
348
409
|
Max-width auto-breaking still applies within each stretch between
|
|
349
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.
|
|
350
416
|
- Style decorations on syllable text: `__…__` renders in the Liturgy
|
|
351
417
|
font, bold; `_…_` renders small caps (BNS) or italic (Vesperale);
|
|
352
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
|
-
/**
|
|
145
|
-
*
|
|
146
|
-
|
|
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;
|