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
@@ -1,11 +1,7 @@
1
1
  import { GuidoScript } from './guidoScript';
2
+ import { SCORE_MARKERS } from './noteGroups';
2
3
  import { StyleSet, StyleSetName, SyllablePart } from './guidoStyles';
3
- /**
4
- * Score marker characters: they carry no pitch, and when they sit at the
5
- * start or end of a note group (with the adjacent dash) they act as
6
- * whitespace rather than note width.
7
- */
8
- export declare const SCORE_MARKERS = ",.:?'\"+!%/=()\u00D6\u00DC\u00D3;";
4
+ export { SCORE_MARKERS };
9
5
  /**
10
6
  * Special reciting notes: when such a note stands alone in a note group it
11
7
  * marks recited text. The glyph shows at a run's first syllable (the
@@ -117,9 +113,26 @@ export interface LineEndDashSegment {
117
113
  textEndPx: number;
118
114
  }
119
115
  export type LayoutSegment = GapSegment | ConnectorSegment | SylSegment | WordSpaceSegment | LineEndDashSegment;
116
+ /** One text line under a notes line: one underlay's (stanza's) ordered
117
+ * segments with their ideal absolute positions. */
118
+ export interface LayoutTextLine {
119
+ segments: LayoutSegment[];
120
+ /** Where the text line ends (the text cursor when the line closed) */
121
+ textCursor: number;
122
+ /** Whether the text line's last syllable ends its word; null when it
123
+ * carries no syllable at all */
124
+ lastWordEnd: boolean | null;
125
+ }
120
126
  /** One rendered line pair's layout: the notes-line model and the text
121
- * line's ordered segments with their ideal absolute positions. */
127
+ * line's ordered segments with their ideal absolute positions. Stacked
128
+ * stanzas (issue #84) put several text lines under the one notes line
129
+ * (`texts`, one per underlay in order); `segments`, `textCursor` and
130
+ * `lastWordEnd` are the first one's. */
122
131
  export interface LayoutLine {
132
+ /** The clef group the notes line opens with (clef, key and one dash;
133
+ * empty when the script has no clef): the clef and key in effect at
134
+ * the line's start */
135
+ clefPrefix: string;
123
136
  notesParts: string[];
124
137
  segments: LayoutSegment[];
125
138
  /** Where the text line ends (the text cursor when the line closed) */
@@ -129,12 +142,17 @@ export interface LayoutLine {
129
142
  /** Whether the line's last syllable ends its word; null when the
130
143
  * line carries no syllable at all */
131
144
  lastWordEnd: boolean | null;
145
+ /** Every text line under the notes, in underlay order (the first is
146
+ * `segments`/`textCursor`/`lastWordEnd`) */
147
+ texts: LayoutTextLine[];
132
148
  /** The break marker's relative left offset; only set on broken
133
149
  * (non-final) lines, after their staff fill dashes */
134
150
  breakMarkerLeftPx?: number;
135
151
  }
136
152
  export interface LayoutResult {
137
153
  lines: LayoutLine[];
154
+ /** The opening clef prefix (the first line's); later lines carry
155
+ * their own (`LayoutLine.clefPrefix`) after a clef or key change */
138
156
  clefPrefix: string;
139
157
  styleSet: StyleSet;
140
158
  styleName: StyleSetName;
@@ -148,6 +166,12 @@ export interface LayoutResult {
148
166
  starTarget: number;
149
167
  starWidth: number;
150
168
  }
169
+ /** The scripts a layout lays out: one script, or several underlays of
170
+ * one melody stacked under a shared staff (issue #84) — one text line per
171
+ * script, in order. Stacked scripts must have the same tokens with the
172
+ * same notes (`stackStanzas` builds them); only their syllable text, word
173
+ * ends, holds and empty slots may differ. */
174
+ export type LayoutSource = GuidoScript | string | readonly (GuidoScript | string)[];
151
175
  /**
152
176
  * Lays a GuidoScript score out: a notes line in the chant font, and a text
153
177
  * line where each syllable is centered below its notes. The dashes of the
@@ -156,6 +180,15 @@ export interface LayoutResult {
156
180
  * overlap the previous one, it starts right after it and the notes group is
157
181
  * padded with extra dashes until it covers the text.
158
182
  *
183
+ * Stacked stanzas (issue #84): given several underlays of one melody, every
184
+ * line pair gets one text line per underlay. Each text line keeps its own
185
+ * cursor and runs the placement rules on its own (tight pairs, connectors,
186
+ * hyphens, recitation flow); a group takes the most pad dashes any of them
187
+ * asks for, so the notes spacing serves every text line, and a line breaks
188
+ * wherever any of them has to. A group that every underlay holds joins its
189
+ * run with the held join; one that some underlay sings takes the normal
190
+ * junction.
191
+ *
159
192
  * This is the shared layout pass behind every emitter: the DOM renderer
160
193
  * turns the returned lines into (notes div, text paragraph) pairs, and the
161
194
  * Word export turns them into fake-spaced Word HTML. Both consume the same
@@ -166,4 +199,4 @@ export interface LayoutResult {
166
199
  * text/notes sizes. Throws when the style set is unknown or one of its
167
200
  * fonts cannot be loaded.
168
201
  */
169
- export declare function layoutScore(source: GuidoScript | string, options?: LayoutOptions): Promise<LayoutResult>;
202
+ export declare function layoutScore(source: LayoutSource, options?: LayoutOptions): Promise<LayoutResult>;
@@ -0,0 +1,71 @@
1
+ import { TranspositionTarget } from './exactTranspose';
2
+ import { TransposeOverflow } from './guidoScriptTransforms';
3
+ /** A part's transposition: a staff-degree count (`transposeBy`, the
4
+ * renderer's slider: noteheads move, clef and key stay) or an exact
5
+ * target (`transposeScript`: a spelled interval or a final, sounding
6
+ * pitch kept, re-notated). */
7
+ export type PartTranspose = number | TranspositionTarget;
8
+ /** A slice of a script: its text-bearing syllables `from` (inclusive,
9
+ * default 0) to `to` (exclusive, default: the end) — the indices of
10
+ * `scriptSyllables`, like `Array.slice`. A syllable comes with its held
11
+ * groups. Without `from` the slice starts at the script's first token,
12
+ * without `to` it runs to its last (empty slots and statements there
13
+ * included). `stripTrailingMarkers` removes the closing markers (a bar)
14
+ * from the slice's last note group, and drops marker-only held groups
15
+ * after it. The script's stanzas are sliced at the same slots. */
16
+ export interface ScriptSlicePart {
17
+ script: string;
18
+ from?: number;
19
+ to?: number;
20
+ transpose?: PartTranspose;
21
+ stripTrailingMarkers?: boolean;
22
+ }
23
+ /** A text-less run, e.g. a psalm-tone ending, written in the clef and
24
+ * key in effect where it joins. Its note groups (source notation,
25
+ * escapes included) are joined by `separator` (default `--`) into one
26
+ * `~(…)` empty slot; a whitespace separator writes one `~(…)` per
27
+ * entry instead. A target transposition here takes no `clef` or `key`. */
28
+ export interface NotesPart {
29
+ notes: string[];
30
+ transpose?: PartTranspose;
31
+ separator?: string;
32
+ }
33
+ /** A sign between parts:
34
+ *
35
+ * - `intonation`: the BNS `**` star as a syllable of its own, where the
36
+ * choir takes over from the cantor;
37
+ * - `bar` / `finalBar`: a divisio (`,` by default) / the divisio
38
+ * finalis (`.` by default), or `glyph` instead. A bar leads the notes
39
+ * part right after it (`~(,--4…)`), or else closes the note group
40
+ * before it (`3-,`). */
41
+ export interface MarkerPart {
42
+ marker: 'intonation' | 'bar' | 'finalBar';
43
+ glyph?: string;
44
+ }
45
+ export type ScriptPart = ScriptSlicePart | NotesPart | MarkerPart;
46
+ export interface ComposeOptions {
47
+ /** What happens to a part whose clef or key differs from the one in
48
+ * effect where it joins (the first part's, unless an earlier part
49
+ * changes it): `inline` (default) writes a `(@clef …)` or `(@key …)`
50
+ * statement before it, `renotate` re-notates it into the clef and
51
+ * key in effect with `transposeScript`, keeping its sounding pitch
52
+ * (and throws when that runs past the glyph range). */
53
+ clefs?: 'inline' | 'renotate';
54
+ /** Past the end of a pitch row in a staff-degree transposition:
55
+ * `error` (default) throws, `clamp` and `null` behave as in
56
+ * `transposeBy`. */
57
+ overflow?: TransposeOverflow;
58
+ }
59
+ /**
60
+ * Builds one script from parts of others (see `ScriptPart`): script
61
+ * slices, text-less note runs and signs, joined in order with a space
62
+ * (every part boundary is a word boundary). The result opens with the
63
+ * first part's clef; later clef or key differences are reconciled as
64
+ * `options.clefs` says. Stanza k of the result is stanza k of every
65
+ * part in turn: a part without one (every notes and marker part, and a
66
+ * script with fewer stanzas) gets `~` empty slots there; the stanzas
67
+ * are written as `(@stanza …)` statements at the end. Throws on a bad
68
+ * slice, a clef that cannot be reconciled, a transposition past the
69
+ * glyph range, or a bar with no note group to attach to.
70
+ */
71
+ export declare function composeScript(parts: ScriptPart[], options?: ComposeOptions): string;
@@ -168,6 +168,12 @@ export type SaveChantsResult = {
168
168
  quota: boolean;
169
169
  };
170
170
  export declare function newChantId(): string;
171
+ /** Per-field sanitization of a prefs snapshot — stored chant blobs and
172
+ * the shared-link URL fragment (src/app/shareLink.ts) both run their
173
+ * raw, untrusted values through this: anything missing, wrong-typed, or
174
+ * out of range falls back to the corresponding default editor setting;
175
+ * the rest passes through clamped. */
176
+ export declare function sanitizeChantPrefs(raw: unknown): ChantPrefs;
171
177
  /** The stored library, sanitized — an empty array when absent, corrupt,
172
178
  * or written by an unknown schema version. Never throws. */
173
179
  export declare function loadChants(): SavedChant[];
@@ -1,3 +1,4 @@
1
+ import { EmptySlots, StanzaStack, StanzaWarning } from '../stanzas';
1
2
  import { StyleSetName } from '../guidoStyles';
2
3
  export declare const version: string;
3
4
  /** Line-breaking budget: a fixed pixel width, or 'auto' to fit the
@@ -12,8 +13,31 @@ export interface EmbedOptions {
12
13
  bold?: boolean;
13
14
  textPx?: number;
14
15
  transpose?: number;
16
+ /** The stanza sung under the notes (1-based; 1 is the script's own
17
+ * text, 2… its `(@stanza …)` statements or the `stanzas` option). */
18
+ stanza?: number;
19
+ /** Stacked stanzas under one staff (issue #84): `'all'`, or the
20
+ * stanza numbers in order. Replaces `stanza` when set. */
21
+ stack?: StanzaStack;
22
+ /** `'small'` draws the slots the rendered stanza leaves empty while
23
+ * another stanza sings them with small heads (issue #69); stacked,
24
+ * the slots no stacked stanza sings while another stanza does.
25
+ * `'partial'` draws every slot some stanza sings and another does not
26
+ * with small heads, whatever is rendered. */
27
+ emptySlots?: EmptySlots;
15
28
  debug?: boolean;
16
29
  }
30
+ /** Per-element options of `renderScore`: the site-wide ones, plus the
31
+ * stanza texts that replace the script's `(@stanza …)` statements. */
32
+ export interface RenderScoreOptions extends Omit<EmbedOptions, 'selector'> {
33
+ stanzas?: string[];
34
+ }
35
+ /** What a finished render reports: the rendered stanzas' count
36
+ * mismatches (missing syllables show as placeholders, extra ones are
37
+ * dropped). */
38
+ export interface RenderResult {
39
+ warnings: StanzaWarning[];
40
+ }
17
41
  /** Cleans up a programmatically rendered element: stops resize
18
42
  * re-rendering and drops the cached source and option overrides. Does
19
43
  * not remove the rendered score itself. */
@@ -23,8 +47,10 @@ export declare function dispose(el: HTMLElement): void;
23
47
  * element's own text content is replaced by the rendered score and
24
48
  * re-rendered on resize. Call again with a new source to update.
25
49
  * Options set here override `init` defaults; data attributes on the
26
- * element still win. Resolves when the score has finished rendering. */
27
- export declare function renderScore(el: HTMLElement, source: string, options?: Omit<EmbedOptions, 'selector'>): Promise<void>;
50
+ * element still win. `stanzas` replaces the script's `(@stanza …)`
51
+ * statements. Resolves when the score has finished rendering, with the
52
+ * rendered stanza's count mismatches. */
53
+ export declare function renderScore(el: HTMLElement, source: string, options?: RenderScoreOptions): Promise<RenderResult>;
28
54
  /** Renders every target under `root` (default: the whole document).
29
55
  * Already-rendered targets re-render from their cached source, so a
30
56
  * host can change data attributes or the source text and call this to
@@ -1,4 +1,4 @@
1
- import { a as dispose, c as renderScore, i as scoreSvg, l as version, n as downloadScoreSvg, o as init, r as scorePngBlob, s as renderAll, t as downloadScorePng } from "../scoreImage-oVBasBX5.js";
1
+ import { a as dispose, c as renderScore, i as scoreSvg, l as version, n as downloadScoreSvg, o as init, r as scorePngBlob, s as renderAll, t as downloadScorePng } from "../scoreImage-DSEupCru.js";
2
2
  //#region src/embed/index.ts
3
3
  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", () => init(), { once: true });
4
4
  else init();
@@ -3,7 +3,14 @@
3
3
  * runtime's imperative API without any auto-rendering. Nothing happens
4
4
  * until you call `renderScore`, `renderAll`, or `init`. Also re-exports
5
5
  * the script parser and text extraction (`GuidoScript`, `chantText`,
6
- * `unescape`), the marked-up text export (`chantRuns`, `chantHtml`,
6
+ * `unescape`, the syllable walker `scriptSyllables`), the script helpers
7
+ * (`PITCH_ROWS`, `transposeNotes`, `SCORE_MARKERS`, `splitNoteMarkers`)
8
+ * and `composeScript`, which builds one script from parts of others, the
9
+ * transpositions (`transposeBy`, the exact
10
+ * `transposeScript`/`transposeExact` with `parseInterval` and
11
+ * `KEY_SIGNATURES`), the stanzas (`withStanza`, `selectStanza`,
12
+ * `parseStanza`, `stanzaWarnings`, `padStanza`, `stanzaCount`,
13
+ * `slotCount`, and the stacked `stackStanzas`), the marked-up text export (`chantRuns`, `chantHtml`,
7
14
  * plus the raw run resolver `resolveSyllableParts`), the style-set
8
15
  * registry (`STYLE_SETS`, `DEFAULT_STYLE_SET`), the
9
16
  * Word-compatible export (`toWordHtml`, `toWordText`, `layoutForWord`,
@@ -12,10 +19,12 @@
12
19
  * (`scoreSvg`, `scorePngBlob`, `downloadScorePng`, `downloadScoreSvg`).
13
20
  */
14
21
  export * from './core';
15
- export { GuidoScript, unescape, chantText } from '../guidoScript';
22
+ export { GuidoScript, unescape, chantText, scriptSyllables, type ScriptSyllable, } from '../guidoScript';
23
+ export { SCORE_MARKERS, splitNoteMarkers, type NoteGroupParts } from '../noteGroups';
24
+ export { composeScript, type ComposeOptions, type MarkerPart, type NotesPart, type PartTranspose, type ScriptPart, type ScriptSlicePart, } from '../composeScript';
16
25
  export { chantRuns, chantHtml } from '../chantMarkup';
17
26
  export { STYLE_SETS, DEFAULT_STYLE_SET, resolveSyllableParts } from '../guidoStyles';
18
- export type { ScriptTransform } from '../guidoScriptTransforms';
27
+ export { KEY_SIGNATURES, PITCH_ROWS, STANZA_PLACEHOLDER, padStanza, parseInterval, parseStanza, selectStanza, slotCount, smallHeads, stackStanzas, stackedStanzaNumbers, stanzaCount, stanzaTexts, stanzaWarnings, transposeBy, transposeExact, transposeNotes, transposeScript, TranspositionRangeError, withStanza, type EmptySlots, type SelectStanzaOptions, type ScriptTransform, type StanzaOptions, type StanzaStack, type StanzaSyllable, type StanzaWarning, type SpelledInterval, type TransposeOverflow, type TranspositionTarget, } from '../guidoScriptTransforms';
19
28
  export type { StyleSetName, SyllablePart, PartStyle, ChantRunKind } from '../guidoStyles';
20
29
  export type { ChantRun, ChantSyllable, ChantWord, ChantMarkupOptions } from '../chantMarkup';
21
30
  export { DEFAULT_SPACER, DEFAULT_TAB_INTERVAL_PT, SpacerMeter, layoutForWord, toWordHtml, toWordText, wordLayoutText, type SpacerChar, type SpacerConfig, type SpacerWidth, type WordExportOptions, type WordLayout, type WordLine, type WordRun, type WordStyleNames, type WordTextPiece, } from '../wordExport';