guidex 0.2.1 → 0.2.4
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 +90 -82
- package/dist/lib/core-dx503oih.js +1191 -0
- package/dist/lib/embed/core.d.ts +35 -0
- package/dist/lib/embed/index.d.ts +8 -0
- package/dist/lib/embed/index.js +6 -0
- package/dist/lib/embed/manual.d.ts +6 -0
- package/dist/lib/embed/manual.js +2 -0
- package/dist/lib/fonts/antquab.ttf +0 -0
- package/dist/lib/fonts/antquabi.ttf +0 -0
- package/dist/lib/fonts/antquai.ttf +0 -0
- package/dist/lib/fonts/bkant.ttf +0 -0
- package/dist/lib/fonts/guidohu.ttf +0 -0
- package/dist/lib/fonts/liturgy.ttf +0 -0
- package/dist/lib/guidex.css +122 -0
- package/dist/lib/guidex.css.d.ts +2 -0
- package/dist/lib/guidoRender.d.ts +66 -0
- package/dist/lib/guidoScript.d.ts +38 -0
- package/dist/lib/guidoScriptTransforms.d.ts +41 -0
- package/dist/lib/guidoStyles.d.ts +171 -0
- package/dist/lib/main.d.ts +1 -0
- package/dist/lib/react/GuidexScore.d.ts +19 -0
- package/dist/lib/react/index.d.ts +7 -0
- package/dist/lib/react/index.js +42 -0
- package/dist/lib/settingsMenu.d.ts +1 -0
- package/dist/lib/theme.d.ts +19 -0
- package/dist-embed/guidex-embed.min.js +1 -1
- package/package.json +42 -2
package/README.md
CHANGED
|
@@ -3,83 +3,70 @@
|
|
|
3
3
|
Guidex — plainchant in code, after Guido of Arezzo, whose font renders
|
|
4
4
|
the scores.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
Render plainchant scores from a compact script notation, set in Book
|
|
7
|
+
Antiqua with a true red (`#d40000`) as its hallmark. Works with a
|
|
8
|
+
bundler (vanilla JS, React, Next.js) or as a plain script tag on any
|
|
9
|
+
site.
|
|
8
10
|
|
|
9
|
-
##
|
|
11
|
+
## Install for bundler users
|
|
10
12
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
13
|
+
```
|
|
14
|
+
npm i guidex
|
|
15
|
+
```
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
The package ships a typed ESM build with an exports map:
|
|
16
18
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
19
|
+
- **`guidex`** — imperative API, no side effects:
|
|
20
|
+
`renderScore(el, source, options?)`, `renderAll(root?)`,
|
|
21
|
+
`init(options?)`, `dispose(el)`, plus the parser and style sets.
|
|
22
|
+
- **`guidex/react`** — the `GuidexScore` client component (`'use client'`
|
|
23
|
+
marked, works in Next.js App Router Server Components). React ≥ 18 is
|
|
24
|
+
an optional peer dependency; only React users install it.
|
|
25
|
+
- **`guidex/embed`** — the same API plus auto-render: importing it scans
|
|
26
|
+
the document for `.guido-script` elements immediately, like the script
|
|
27
|
+
tag. Don't use this in frameworks that re-render the DOM.
|
|
24
28
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
- `src/main.ts` — the main page: the interactive editor at the top
|
|
30
|
-
(`#editor` with a multi-line textarea, sample-picker chips, quick-tips),
|
|
31
|
-
then the intro prose, the Gaudeámus score, the syllable breakdown table,
|
|
32
|
-
and the `GuidoRender` recap score under `#test-score`
|
|
33
|
-
- `src/guidoScript.ts` — the `GuidoScript` class: parses script notation
|
|
34
|
-
into clef, syllables (`{ text, notes, wordEnd }`), and whole words;
|
|
35
|
-
`toString()` round-trips; `normalized` applies typing conveniences
|
|
36
|
-
- `src/guidoRender.ts` — `GuidoRender`: renders a score from a
|
|
37
|
-
`GuidoScript` or string using canvas measurements (2× scale,
|
|
38
|
-
assembled-prefix measurement); supports multi-line scores via a
|
|
39
|
-
`maxWidthPx` parameter, with staff breaking and in-group splitting at
|
|
40
|
-
dashes; also exports `SCORE_MARKERS`
|
|
41
|
-
- `src/style.css` — the global styleset (fonts, red palette, typography,
|
|
42
|
-
score components); imports `src/explainers.css`
|
|
43
|
-
- `src/explainers.css` — main-page styles: page layout, editor, sample
|
|
44
|
-
chips, syllable table, debug guides
|
|
45
|
-
- `tests/` — Vitest suite: parser round-trip/normalization, placement
|
|
46
|
-
rules, junction widths, and an overlap-invariant sweep (`setup.ts`
|
|
47
|
-
installs a deterministic fake canvas and fake font loading)
|
|
48
|
-
- `public/fonts/` — Book Antiqua family and the Guidohu notation font
|
|
49
|
-
- `public/favicon.svg` — monospace `(g)` on five staff lines, paper + red
|
|
29
|
+
The stylesheet ships as `guidex/guidex.css`; the fonts load from its
|
|
30
|
+
relative `./fonts/…` URLs, so bundlers must see the package's
|
|
31
|
+
`dist/lib/fonts/` (Vite, Next.js, and webpack all handle this).
|
|
50
32
|
|
|
51
|
-
|
|
33
|
+
### Vanilla JS
|
|
52
34
|
|
|
53
|
-
|
|
54
|
-
|
|
35
|
+
```js
|
|
36
|
+
import { renderScore } from 'guidex'
|
|
37
|
+
import 'guidex/guidex.css'
|
|
55
38
|
|
|
39
|
+
renderScore(document.querySelector('#score'), '(c4) Fat(2)ue(2)', { textPx: 22 })
|
|
56
40
|
```
|
|
57
|
-
|
|
41
|
+
|
|
42
|
+
### React / Next.js
|
|
43
|
+
|
|
44
|
+
```jsx
|
|
45
|
+
import { GuidexScore } from 'guidex/react'
|
|
46
|
+
import 'guidex/guidex.css'
|
|
47
|
+
|
|
48
|
+
<GuidexScore script="(c4) Fat(2)ue(2)" textPx={22} />
|
|
58
49
|
```
|
|
59
50
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
- Whitespace in the source marks word boundaries between syllables.
|
|
64
|
-
- The Guidohu dash (`-`) is pure whitespace; spaces are forbidden inside a
|
|
65
|
-
notes line.
|
|
66
|
-
- Marker characters (`,.:?'"+!%/=()ÖÜÓ;` = `SCORE_MARKERS`) carry no
|
|
67
|
-
pitch; at the edges of a note group they count as whitespace, so a
|
|
68
|
-
junction after a marker-ending group needs only 2 dashes instead of 3.
|
|
51
|
+
`GuidexScore` renders into a div on mount, re-renders on resize, and
|
|
52
|
+
updates when the `script` prop changes. Props mirror the options below:
|
|
53
|
+
`maxWidth`, `style`, `bold`, `textPx`, `transpose`, `debug`, `className`.
|
|
69
54
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
55
|
+
### Options
|
|
56
|
+
|
|
57
|
+
| Option | Values | Default |
|
|
58
|
+
| ----------- | ------------------------------- | -------------- |
|
|
59
|
+
| `maxWidth` | pixels, or `auto` (fits the element, re-rendered on resize) | `auto` |
|
|
60
|
+
| `style` | `BNS`, `Vesperale` | `BNS` |
|
|
61
|
+
| `bold` | boolean | `false` |
|
|
62
|
+
| `textPx` | base text size in px (notes render at 2×) | `18` |
|
|
63
|
+
| `transpose` | pitch-row shift (see `transposeBy`) | `0` |
|
|
64
|
+
| `debug` | boolean (measurement titles on spans) | `false` |
|
|
77
65
|
|
|
78
|
-
## Embedding
|
|
66
|
+
## Embedding with a script tag (no bundler)
|
|
79
67
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
`<head>`:
|
|
68
|
+
Host the `dist-embed/` folder (also attached to every GitHub Release)
|
|
69
|
+
on any static server or CDN and drop it into a site's `<head>`:
|
|
83
70
|
|
|
84
71
|
```html
|
|
85
72
|
<link rel="stylesheet" href="https://your-host/path/guidex-embed.min.css">
|
|
@@ -95,31 +82,52 @@ content as a score, in place:
|
|
|
95
82
|
data-style="Vesperale">(MX)Ki(3)rály(3)ként(5) tró(7i)nol(7-:)</div>
|
|
96
83
|
```
|
|
97
84
|
|
|
98
|
-
Parameters ride data attributes on the div
|
|
99
|
-
|
|
85
|
+
Parameters ride data attributes on the div (same values as the options
|
|
86
|
+
table above, kebab-cased: `data-max-width`, `data-text-px`, …);
|
|
87
|
+
site-wide defaults can be set with
|
|
88
|
+
`GuidexEmbed.init({ maxWidth: 'auto', style: 'BNS', … })`. Element
|
|
100
89
|
attributes win over init options. New elements added after page load
|
|
101
90
|
render automatically; already-rendered elements re-render when
|
|
102
91
|
`GuidexEmbed.renderAll()` is called.
|
|
103
92
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
93
|
+
A failed render (unknown style, unloadable font) leaves an error note
|
|
94
|
+
in the target instead of throwing.
|
|
95
|
+
|
|
96
|
+
## The script notation
|
|
97
|
+
|
|
98
|
+
The source alternates a leading clef group with syllables, each followed by
|
|
99
|
+
its notes:
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
(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-.)
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
- The first parenthesized group is the starting clef with note modifiers.
|
|
106
|
+
- Every syllable of text precedes the parenthesized group of notes it is
|
|
107
|
+
sung to.
|
|
108
|
+
- Whitespace in the source marks word boundaries between syllables.
|
|
109
|
+
- The Guidohu dash (`-`) is pure whitespace; spaces are forbidden inside a
|
|
110
|
+
notes line.
|
|
111
|
+
- Marker characters (`,.:?'"+!%/=()ÖÜÓ;` = `SCORE_MARKERS`) carry no
|
|
112
|
+
pitch; at the edges of a note group they count as whitespace, so a
|
|
113
|
+
junction after a marker-ending group needs only 2 dashes instead of 3.
|
|
114
|
+
- Style decorations on syllable text: `__…__` renders in the Liturgy
|
|
115
|
+
font, bold; `_…_` renders small caps (BNS) or italic (Vesperale);
|
|
116
|
+
`*…*` marks an initial (bold, red in BNS). A syllable that is exactly
|
|
117
|
+
`**` renders the mediant star glyph.
|
|
118
|
+
|
|
119
|
+
In the rendered score, notes are set in the Guidohu font at twice the
|
|
120
|
+
surrounding text size. Notes are measured with a hidden canvas after
|
|
121
|
+
webfonts load, and each syllable is aligned against the measured ink of
|
|
122
|
+
its notes — left-aligned when the notes are wider, centered otherwise.
|
|
123
|
+
When a finite max width is given, the score breaks into multiple line
|
|
124
|
+
pairs, repeating the clef on every line and hanging a hyphen at line ends
|
|
125
|
+
that split a word.
|
|
118
126
|
|
|
119
127
|
## State
|
|
120
128
|
|
|
121
129
|
Parsing and rendering both work end to end: a script is parsed into
|
|
122
130
|
syllables and words, and the renderer produces multi-line scores with
|
|
123
|
-
correct spacing, junctions, and dash placement.
|
|
124
|
-
|
|
125
|
-
rendering model
|
|
131
|
+
correct spacing, junctions, and dash placement. See `DEVELOPMENT.md` in
|
|
132
|
+
the repository for the project layout, development commands, and the
|
|
133
|
+
detailed rendering model.
|