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
@@ -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
@@ -39,6 +35,13 @@ export interface LayoutOptions {
39
35
  notesPx?: number;
40
36
  /** Maximum notes-line width before a staff break (default: none) */
41
37
  maxWidthPx?: number;
38
+ /** Dashes in a normal junction between note groups: at least 1, in
39
+ * steps of a third (default 3; 2.67 reads as 2⅔). Three `¨` are about
40
+ * as wide as a `-`, so thirds are written with `¨` after the whole
41
+ * dashes (`--¨¨`). A group ending in markers or starting with an
42
+ * accidental takes one less, never under 1. Held groups keep their
43
+ * own join. */
44
+ junctionDashes?: number;
42
45
  }
43
46
  /** A horizontal whitespace gap on the text line: the lead-in shared with
44
47
  * the clef, or the gap after a word-ending syllable. Both emitters fake it
@@ -117,9 +120,26 @@ export interface LineEndDashSegment {
117
120
  textEndPx: number;
118
121
  }
119
122
  export type LayoutSegment = GapSegment | ConnectorSegment | SylSegment | WordSpaceSegment | LineEndDashSegment;
123
+ /** One text line under a notes line: one underlay's (stanza's) ordered
124
+ * segments with their ideal absolute positions. */
125
+ export interface LayoutTextLine {
126
+ segments: LayoutSegment[];
127
+ /** Where the text line ends (the text cursor when the line closed) */
128
+ textCursor: number;
129
+ /** Whether the text line's last syllable ends its word; null when it
130
+ * carries no syllable at all */
131
+ lastWordEnd: boolean | null;
132
+ }
120
133
  /** One rendered line pair's layout: the notes-line model and the text
121
- * line's ordered segments with their ideal absolute positions. */
134
+ * line's ordered segments with their ideal absolute positions. Stacked
135
+ * stanzas (issue #84) put several text lines under the one notes line
136
+ * (`texts`, one per underlay in order); `segments`, `textCursor` and
137
+ * `lastWordEnd` are the first one's. */
122
138
  export interface LayoutLine {
139
+ /** The clef group the notes line opens with (clef, key and one dash;
140
+ * empty when the script has no clef): the clef and key in effect at
141
+ * the line's start */
142
+ clefPrefix: string;
123
143
  notesParts: string[];
124
144
  segments: LayoutSegment[];
125
145
  /** Where the text line ends (the text cursor when the line closed) */
@@ -129,12 +149,17 @@ export interface LayoutLine {
129
149
  /** Whether the line's last syllable ends its word; null when the
130
150
  * line carries no syllable at all */
131
151
  lastWordEnd: boolean | null;
152
+ /** Every text line under the notes, in underlay order (the first is
153
+ * `segments`/`textCursor`/`lastWordEnd`) */
154
+ texts: LayoutTextLine[];
132
155
  /** The break marker's relative left offset; only set on broken
133
156
  * (non-final) lines, after their staff fill dashes */
134
157
  breakMarkerLeftPx?: number;
135
158
  }
136
159
  export interface LayoutResult {
137
160
  lines: LayoutLine[];
161
+ /** The opening clef prefix (the first line's); later lines carry
162
+ * their own (`LayoutLine.clefPrefix`) after a clef or key change */
138
163
  clefPrefix: string;
139
164
  styleSet: StyleSet;
140
165
  styleName: StyleSetName;
@@ -148,6 +173,12 @@ export interface LayoutResult {
148
173
  starTarget: number;
149
174
  starWidth: number;
150
175
  }
176
+ /** The scripts a layout lays out: one script, or several underlays of
177
+ * one melody stacked under a shared staff (issue #84) — one text line per
178
+ * script, in order. Stacked scripts must have the same tokens with the
179
+ * same notes (`stackStanzas` builds them); only their syllable text, word
180
+ * ends, holds and empty slots may differ. */
181
+ export type LayoutSource = GuidoScript | string | readonly (GuidoScript | string)[];
151
182
  /**
152
183
  * Lays a GuidoScript score out: a notes line in the chant font, and a text
153
184
  * line where each syllable is centered below its notes. The dashes of the
@@ -156,6 +187,15 @@ export interface LayoutResult {
156
187
  * overlap the previous one, it starts right after it and the notes group is
157
188
  * padded with extra dashes until it covers the text.
158
189
  *
190
+ * Stacked stanzas (issue #84): given several underlays of one melody, every
191
+ * line pair gets one text line per underlay. Each text line keeps its own
192
+ * cursor and runs the placement rules on its own (tight pairs, connectors,
193
+ * hyphens, recitation flow); a group takes the most pad dashes any of them
194
+ * asks for, so the notes spacing serves every text line, and a line breaks
195
+ * wherever any of them has to. A group that every underlay holds joins its
196
+ * run with the held join; one that some underlay sings takes the normal
197
+ * junction.
198
+ *
159
199
  * This is the shared layout pass behind every emitter: the DOM renderer
160
200
  * turns the returned lines into (notes div, text paragraph) pairs, and the
161
201
  * Word export turns them into fake-spaced Word HTML. Both consume the same
@@ -166,4 +206,4 @@ export interface LayoutResult {
166
206
  * text/notes sizes. Throws when the style set is unknown or one of its
167
207
  * fonts cannot be loaded.
168
208
  */
169
- export declare function layoutScore(source: GuidoScript | string, options?: LayoutOptions): Promise<LayoutResult>;
209
+ 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;
@@ -19,6 +19,8 @@ export declare const MAX_WIDTH_PX_DEFAULT = 700;
19
19
  export declare const MAX_WIDTH_PX_MIN = 300;
20
20
  export declare const MAX_WIDTH_PX_MAX = 1400;
21
21
  /** Declared range of the transpose slider. */
22
+ export declare const JUNCTION_DASHES_MIN = 1;
23
+ export declare const JUNCTION_DASHES_MAX = 8;
22
24
  export declare const TRANSPOSE_MIN = -6;
23
25
  export declare const TRANSPOSE_MAX = 6;
24
26
  /** The destination Word text size default (notes ride at twice it) and the
@@ -54,6 +56,8 @@ export interface EditorSettings {
54
56
  notesPx: number;
55
57
  /** True once the user typed a chant size of their own. */
56
58
  notesCustom: boolean;
59
+ /** Dashes in a normal junction between note groups. */
60
+ junctionDashes: number;
57
61
  customColors: boolean;
58
62
  colorFg: string;
59
63
  colorAccent: string;
@@ -148,6 +152,7 @@ export interface ChantPrefs {
148
152
  notesPx: number;
149
153
  /** True once the user typed a chant size of their own. */
150
154
  notesCustom: boolean;
155
+ junctionDashes: number;
151
156
  transpose: number;
152
157
  }
153
158
  export interface SavedChant {
@@ -168,6 +173,12 @@ export type SaveChantsResult = {
168
173
  quota: boolean;
169
174
  };
170
175
  export declare function newChantId(): string;
176
+ /** Per-field sanitization of a prefs snapshot — stored chant blobs and
177
+ * the shared-link URL fragment (src/app/shareLink.ts) both run their
178
+ * raw, untrusted values through this: anything missing, wrong-typed, or
179
+ * out of range falls back to the corresponding default editor setting;
180
+ * the rest passes through clamped. */
181
+ export declare function sanitizeChantPrefs(raw: unknown): ChantPrefs;
171
182
  /** The stored library, sanitized — an empty array when absent, corrupt,
172
183
  * or written by an unknown schema version. Never throws. */
173
184
  export declare function loadChants(): SavedChant[];
@@ -1,7 +1,11 @@
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
4
- * target element (re-rendered on resize). */
5
+ * target element (re-rendered on resize). `Infinity` (or any large
6
+ * number) means "never break": the score stays on one line, wider than
7
+ * its container if need be, and the host handles the overflow
8
+ * (`overflow-x: auto` to scroll, `hidden` to clip). */
5
9
  export type MaxWidth = number | 'auto';
6
10
  /** Site-wide defaults, settable through `GuidexEmbed.init`. */
7
11
  export interface EmbedOptions {
@@ -11,9 +15,34 @@ export interface EmbedOptions {
11
15
  style?: StyleSetName;
12
16
  bold?: boolean;
13
17
  textPx?: number;
18
+ /** Dashes in a normal junction between note groups, in steps of a third (default 3) */
19
+ junctionDashes?: number;
14
20
  transpose?: number;
21
+ /** The stanza sung under the notes (1-based; 1 is the script's own
22
+ * text, 2… its `(@stanza …)` statements or the `stanzas` option). */
23
+ stanza?: number;
24
+ /** Stacked stanzas under one staff (issue #84): `'all'`, or the
25
+ * stanza numbers in order. Replaces `stanza` when set. */
26
+ stack?: StanzaStack;
27
+ /** `'small'` draws the slots the rendered stanza leaves empty while
28
+ * another stanza sings them with small heads (issue #69); stacked,
29
+ * the slots no stacked stanza sings while another stanza does.
30
+ * `'partial'` draws every slot some stanza sings and another does not
31
+ * with small heads, whatever is rendered. */
32
+ emptySlots?: EmptySlots;
15
33
  debug?: boolean;
16
34
  }
35
+ /** Per-element options of `renderScore`: the site-wide ones, plus the
36
+ * stanza texts that replace the script's `(@stanza …)` statements. */
37
+ export interface RenderScoreOptions extends Omit<EmbedOptions, 'selector'> {
38
+ stanzas?: string[];
39
+ }
40
+ /** What a finished render reports: the rendered stanzas' count
41
+ * mismatches (missing syllables show as placeholders, extra ones are
42
+ * dropped). */
43
+ export interface RenderResult {
44
+ warnings: StanzaWarning[];
45
+ }
17
46
  /** Cleans up a programmatically rendered element: stops resize
18
47
  * re-rendering and drops the cached source and option overrides. Does
19
48
  * not remove the rendered score itself. */
@@ -23,8 +52,10 @@ export declare function dispose(el: HTMLElement): void;
23
52
  * element's own text content is replaced by the rendered score and
24
53
  * re-rendered on resize. Call again with a new source to update.
25
54
  * 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>;
55
+ * element still win. `stanzas` replaces the script's `(@stanza …)`
56
+ * statements. Resolves when the score has finished rendering, with the
57
+ * rendered stanza's count mismatches. */
58
+ export declare function renderScore(el: HTMLElement, source: string, options?: RenderScoreOptions): Promise<RenderResult>;
28
59
  /** Renders every target under `root` (default: the whole document).
29
60
  * Already-rendered targets re-render from their cached source, so a
30
61
  * 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-lvOrTbG-.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';