guidex 0.3.3 → 0.4.0

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.
@@ -1,4 +1,4 @@
1
- import { ScriptTransform } from './guidoScriptTransforms';
1
+ import { Mark, TextRun } from './textMarkup';
2
2
  /** How one run of syllable text is drawn. Unset fields inherit from the
3
3
  * surrounding text line: the style set's text font stack, its base weight,
4
4
  * and the theme's text color. */
@@ -15,12 +15,16 @@ export interface PartStyle {
15
15
  /** Raised above the baseline by this fraction of the text size; does
16
16
  * not affect width measurement (position: relative, out of flow) */
17
17
  raise?: number;
18
- /** The run's text is uppercased before measuring and rendering: the
19
- * small-caps look is faked as uniformly scaled capitals, which canvas
20
- * measures exactly like the DOM lays out (font-variant: small-caps
21
- * does not — the browser's canvas synthesis measures wider than the
22
- * real smcp glyphs it uses for DOM layout) */
18
+ /** The run draws in capitals, through CSS text-transform; its
19
+ * capitals are measured as they draw, which canvas does exactly like
20
+ * the DOM lays out (font-variant: small-caps does not — the browser's
21
+ * canvas synthesis measures wider than the real smcp glyphs it uses
22
+ * for DOM layout). Display only: the run's text stays as written. */
23
23
  uppercase?: boolean;
24
+ /** True small caps (the `sc` mark): lowercase letters draw as capitals
25
+ * at `SMALL_CAP_SCALE`, in runs of their own, and the rest at full size.
26
+ * On a resolved run, marks the small letters (Word's small-caps run). */
27
+ smallCaps?: boolean;
24
28
  /** Inline color; absent means inherit (keeps dark mode working) */
25
29
  color?: string;
26
30
  /** The run carries the initial class in the DOM (the `*…*` marker) */
@@ -44,24 +48,21 @@ export interface StyleSet {
44
48
  family: string;
45
49
  weight: '400' | '700';
46
50
  }[];
47
- /** Special syllable renderings keyed by their wrapper character:
48
- * `__…__` the Liturgy font, `_…_` rubrics, `*…*` the initial (which
49
- * may also wrap any part of a syllable) */
50
- decorations: Record<string, PartStyle>;
51
- /** The whole-syllable `**` star: rendered as ∗ at the base size,
52
- * raised like the `+`; measured at 95% because no font in the stacks
53
- * has U+2217 and the fallback glyph's advance is wider than the Times
54
- * `*` (0.523 em vs 0.5 em) — the smaller measure size keeps the star's
55
- * footprint at the plain star's. */
56
- specialStarStyle: PartStyle;
51
+ /** The marks this style set draws, by name: the semantic ones the
52
+ * sugar produces (`liturgy` for `__…__`, `rubric` for `_…_`, `initial`
53
+ * for `*…*`, `star` for `**`, `plus` for a Liturgy run's `+`) and any
54
+ * others a script names in a `{…}` span. A consumer's style set extends
55
+ * them; the primitives (`red`, `b`, `i`, `sc`…) always mean the same. */
56
+ marks: Record<string, PartStyle>;
57
+ /** Colors `color:<name>` and a mark's `color` can name, past the
58
+ * built-in palette: a CSS color or a `var(--…)` the Word export knows */
59
+ colors?: Record<string, string>;
60
+ /** Fonts `font:<name>` can name, past the built-in ones: a font stack.
61
+ * A webfont also belongs in `verifiedFonts`. */
62
+ fonts?: Record<string, string>;
57
63
  /** Line-end padding in px: the break marker `*` lands this far past
58
64
  * the max-width position. Defaults to 0 (the star sits on the edge). */
59
65
  padding?: number;
60
- /** Script transforms applied by default when a score renders in this
61
- * style: whoever parses the score's source (embed runtime, editor)
62
- * starts from this list and layers user-requested transforms (e.g.
63
- * transpose) on top. Defaults to no transforms. */
64
- scriptTransforms?: ScriptTransform[];
65
66
  }
66
67
  export declare const STYLE_SETS: {
67
68
  /** Book Antiqua text with red accents. */
@@ -79,36 +80,33 @@ export declare const STYLE_SETS: {
79
80
  family: string;
80
81
  weight: "700";
81
82
  })[];
82
- decorations: {
83
- __: {
83
+ marks: {
84
+ liturgy: {
84
85
  fontFamily: string;
85
86
  weight: "700";
86
87
  color: string;
87
88
  };
88
- _: {
89
+ rubric: {
89
90
  uppercase: true;
90
91
  scale: number;
91
92
  color: string;
92
93
  };
93
- '*': {
94
+ initial: {
94
95
  weight: "700";
95
96
  color: string;
96
97
  initial: true;
97
98
  };
98
- };
99
- specialStarStyle: {
100
- fontFamily: string;
101
- weight: "700";
102
- scale: number;
103
- measureScale: number;
104
- raise: number;
105
- color: string;
99
+ star: {
100
+ fontFamily: string;
101
+ weight: "700";
102
+ scale: number;
103
+ measureScale: number;
104
+ raise: number;
105
+ color: string;
106
+ };
107
+ plus: PartStyle;
106
108
  };
107
109
  padding: number;
108
- scriptTransforms: {
109
- name: string;
110
- apply: (source: string) => string;
111
- }[];
112
110
  };
113
111
  /** Times New Roman text, strictly black and white. */
114
112
  Vesperale: {
@@ -121,33 +119,45 @@ export declare const STYLE_SETS: {
121
119
  family: string;
122
120
  weight: "700";
123
121
  })[];
124
- decorations: {
125
- __: {
122
+ marks: {
123
+ liturgy: {
126
124
  fontFamily: string;
127
125
  weight: "700";
128
126
  };
129
- _: {
127
+ rubric: {
130
128
  scale: number;
131
129
  italic: true;
132
130
  };
133
- '*': {
131
+ initial: {
134
132
  weight: "700";
135
133
  initial: true;
136
134
  };
137
- };
138
- specialStarStyle: {
139
- fontFamily: string;
140
- weight: "700";
141
- scale: number;
142
- measureScale: number;
143
- raise: number;
135
+ star: {
136
+ fontFamily: string;
137
+ weight: "700";
138
+ scale: number;
139
+ measureScale: number;
140
+ raise: number;
141
+ };
142
+ plus: PartStyle;
144
143
  };
145
144
  padding: number;
146
- scriptTransforms: never[];
147
145
  };
148
146
  };
149
- export type StyleSetName = keyof typeof STYLE_SETS;
147
+ /** A style set's name: a built-in one, or one `defineStyleSet` added. */
148
+ export type StyleSetName = keyof typeof STYLE_SETS | (string & {});
150
149
  export declare const DEFAULT_STYLE_SET: StyleSetName;
150
+ /** The style set of that name, built-in or defined. */
151
+ export declare function styleSetOf(name: StyleSetName): StyleSet | undefined;
152
+ /** What a new style set says: the set it extends (default: the default
153
+ * one), and whatever differs from it. `marks`, `colors` and `fonts` merge
154
+ * over the extended set's, the rest replaces it. */
155
+ export type StyleSetDefinition = Partial<StyleSet> & {
156
+ extends?: StyleSetName;
157
+ };
158
+ /** Adds a style set under a name `style` can then give, without patching
159
+ * the package. Returns it. */
160
+ export declare function defineStyleSet(name: string, definition: StyleSetDefinition): StyleSet;
151
161
  /** What one run of syllable text is, independent of how a style set
152
162
  * draws it: the notation-fixed meaning of the markup that produced it.
153
163
  * `liturgy` the `__…__` wrapper, `rubric` `_…_`, `star` the whole-syllable
@@ -162,30 +172,31 @@ export interface SyllablePart {
162
172
  style: PartStyle;
163
173
  kind?: ChantRunKind;
164
174
  }
165
- /**
166
- * Resolves a syllable's raw text into the runs it renders as: the whole-
167
- * syllable `**` star renders as the bold ∗ operator, a `__…__` or `_…_`
168
- * wrapper (the same characters on both ends, content between) picks up
169
- * its decoration rule from the style set, and paired `*` markers wrap any
170
- * part of the syllable — even the whole of it — with the initial rule
171
- * (`*sam*ple` → "sam" in the initial style, "ple" normal; an unmatched
172
- * `*` renders literally), the `bold` option forces weight 700 onto every
173
- * run, and the marker characters (`*`, `†`) split off into runs of their
174
- * own — with the style set's `markerGlyphs` font when one is configured,
175
- * the text font otherwise (always the `marker` kind).
176
- * Inside a Liturgy-font run, `+` gets its own weight-400 runs — the font
177
- * is bold-looking by design, so the weight stays normal. The wrapper
178
- * characters themselves are dropped. Each run also carries `kind`, the
179
- * notation-fixed semantic of its markup (`liturgy`, `rubric`, `star`,
180
- * `marker`, `plus`) — the vocabulary the marked-up text export and the
181
- * renderer's run classes share, identical across style sets. `rawCase`
182
- * skips the BNS rubric uppercasing: uppercasing is presentation, so the
183
- * marked-up text export keeps the raw letter case (a consumer CSS applies
184
- * text-transform instead).
185
- */
186
- export declare function resolveSyllableParts(text: string, styleSet: StyleSet, bold: boolean, options?: {
187
- rawCase?: boolean;
188
- }): SyllablePart[];
175
+ /** How much smaller small capitals draw than the full capitals. */
176
+ export declare const SMALL_CAP_SCALE = 0.75;
177
+ /** The run kind of a run's marks: the last of the notation's own. */
178
+ export declare function kindOf(marks: Mark[]): ChantRunKind | undefined;
179
+ /** Marks a score adds to its style set's. */
180
+ export type MarkDefinitions = Record<string, PartStyle>;
181
+ /** The look of comma-separated marks (`red,sc`), for a host styling prose
182
+ * to match the score. */
183
+ export declare function resolveMarks(marks: string, styleSet: StyleSet, extra?: MarkDefinitions): PartStyle;
184
+ /** The marks of `marks` that neither the primitives, the style set nor
185
+ * `extra` define. */
186
+ export declare function unknownMarks(marks: Mark[], styleSet: StyleSet, extra?: MarkDefinitions): Mark[];
187
+ /** Resolves parsed text runs (`SyllableToken.runs`) into how a style set
188
+ * draws them: each run takes the style of its marks, the `bold` option
189
+ * forces weight 700 onto every run, and `kind` names its notation-fixed
190
+ * semantic (`liturgy`, `rubric`, `star`, `marker`, `plus`), the vocabulary
191
+ * the marked-up text export and the renderer's run classes share. A
192
+ * small-caps run splits into full and small parts. Text stays as written:
193
+ * capitals are the part's display (`drawnText`). */
194
+ export declare function resolveTextRuns(runs: readonly TextRun[], styleSet: StyleSet, bold: boolean, extra?: MarkDefinitions): SyllablePart[];
195
+ /** The characters a part draws, which measuring must see. */
196
+ export declare function drawnText(part: Pick<SyllablePart, 'text' | 'style'>): string;
197
+ /** Parses a syllable as written (`SyllableToken.source`) and resolves its
198
+ * runs in one step (see `resolveSpans`, `resolveTextRuns`). */
199
+ export declare function resolveSyllableParts(written: string, styleSet: StyleSet, bold: boolean, extra?: MarkDefinitions): SyllablePart[];
189
200
  /** The canvas font shorthand for measuring a run at the text size. */
190
201
  export declare function measurementFont(style: PartStyle, textPx: number, fallbackStack: string): string;
191
202
  /** The inline CSS properties that draw a run, as dash-cased names for
@@ -1,6 +1,7 @@
1
- import { MaxWidth } from '../embed/core';
2
- import { StyleSetName } from '../guidoStyles';
3
- import { EmptySlots, StanzaStack, StanzaWarning } from '../stanzas';
1
+ import { MaxWidth, ScoreWarning } from '../embed/core';
2
+ import { StaffFill } from '../chantLayout';
3
+ import { StyleSetName, MarkDefinitions } from '../guidoStyles';
4
+ import { EmptySlots, StanzaStack } from '../stanzas';
4
5
  export interface GuidexScoreProps {
5
6
  /** The score source in GuidoScript notation, e.g. `'(M)A(0) di(0q)e(qQ0)bus(1) an(3)ti(1e)quis(qQ0-:)'`. */
6
7
  script: string;
@@ -13,6 +14,12 @@ export interface GuidexScoreProps {
13
14
  textPx?: number;
14
15
  /** Dashes in a normal junction between note groups, in steps of a third (default 3). */
15
16
  junctionDashes?: number;
17
+ /** Marks this score adds to its style set's */
18
+ marks?: MarkDefinitions;
19
+ /** How far each staff line runs (default `all-but-last`). */
20
+ staffFill?: StaffFill;
21
+ /** With `staffFill: 'longest'`: the distance from the available width within which every line runs to it instead (default 0). */
22
+ staffFillSnapPx?: number;
16
23
  /** Transpose the score by N diatonic steps. */
17
24
  transpose?: number;
18
25
  /** The stanza sung under the notes (1-based, default 1: the
@@ -31,9 +38,9 @@ export interface GuidexScoreProps {
31
38
  emptySlots?: EmptySlots;
32
39
  /** Called after each render with the rendered stanzas' count
33
40
  * mismatches (empty when it fits). */
34
- onWarnings?: (warnings: StanzaWarning[]) => void;
41
+ onWarnings?: (warnings: ScoreWarning[]) => void;
35
42
  /** Render measurement debug markers. */
36
43
  debug?: boolean;
37
44
  className?: string;
38
45
  }
39
- export declare function GuidexScore({ script, maxWidth, style, bold, textPx, junctionDashes, transpose, stanza, stack, stanzas, emptySlots, onWarnings, debug, className, }: GuidexScoreProps): import('react').JSX.Element;
46
+ export declare function GuidexScore({ script, maxWidth, style, bold, textPx, junctionDashes, marks, staffFill, staffFillSnapPx, transpose, stanza, stack, stanzas, emptySlots, onWarnings, debug, className, }: GuidexScoreProps): import('react').JSX.Element;
@@ -5,5 +5,7 @@
5
5
  export { GuidexScore, type GuidexScoreProps } from './GuidexScore';
6
6
  export { renderScore, renderAll, init, dispose, version, type EmbedOptions, type MaxWidth, type RenderResult, type RenderScoreOptions, } from '../embed/core';
7
7
  export { downloadScorePng, downloadScoreSvg, scorePngBlob, scoreSvg, type ScoreDownloadOptions, type ScoreImageOptions, } from '../scoreImage';
8
+ export type { StaffFill } from '../chantLayout';
8
9
  export type { StyleSetName } from '../guidoStyles';
10
+ export type { MarkWarning } from '../chantMarkup';
9
11
  export type { EmptySlots, StanzaStack, StanzaWarning } from '../stanzas';
@@ -1,5 +1,5 @@
1
1
  "use client";
2
- 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
+ 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-Dz3c55Zi.js";
3
3
  import { useEffect, useRef } from "react";
4
4
  import { jsx } from "react/jsx-runtime";
5
5
  //#region src/react/GuidexScore.tsx
@@ -10,24 +10,29 @@ import { jsx } from "react/jsx-runtime";
10
10
  * client'` directive marks it for React Server Components (Next.js App
11
11
  * Router); in plain client-side React it is a no-op.
12
12
  */
13
- function GuidexScore({ script, maxWidth, style, bold, textPx, junctionDashes, transpose, stanza, stack, stanzas, emptySlots, onWarnings, debug, className }) {
13
+ function GuidexScore({ script, maxWidth, style, bold, textPx, junctionDashes, marks, staffFill, staffFillSnapPx, transpose, stanza, stack, stanzas, emptySlots, onWarnings, debug, className }) {
14
14
  const ref = useRef(null);
15
15
  const onWarningsRef = useRef(onWarnings);
16
16
  onWarningsRef.current = onWarnings;
17
17
  const stanzasKey = stanzas === void 0 ? void 0 : JSON.stringify(stanzas);
18
+ const marksKey = marks === void 0 ? void 0 : JSON.stringify(marks);
18
19
  const stackKey = stack === void 0 ? void 0 : JSON.stringify(stack);
19
20
  useEffect(() => {
20
21
  const el = ref.current;
21
22
  if (!el) return;
22
23
  let live = true;
24
+ const scoreMarks = marksKey === void 0 ? void 0 : JSON.parse(marksKey);
23
25
  const stanzaTexts = stanzasKey === void 0 ? void 0 : JSON.parse(stanzasKey);
24
26
  const stacked = stackKey === void 0 ? void 0 : JSON.parse(stackKey);
25
27
  renderScore(el, script, {
26
28
  maxWidth,
27
29
  style,
30
+ marks: scoreMarks,
28
31
  bold,
29
32
  textPx,
30
33
  junctionDashes,
34
+ staffFill,
35
+ staffFillSnapPx,
31
36
  transpose,
32
37
  stanza,
33
38
  stack: stacked,
@@ -45,9 +50,12 @@ function GuidexScore({ script, maxWidth, style, bold, textPx, junctionDashes, tr
45
50
  script,
46
51
  maxWidth,
47
52
  style,
53
+ marksKey,
48
54
  bold,
49
55
  textPx,
50
56
  junctionDashes,
57
+ staffFill,
58
+ staffFillSnapPx,
51
59
  transpose,
52
60
  stanza,
53
61
  stackKey,