guidex 0.1.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 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
- A web project for rendering plainchant scores from a compact script
7
- notation, set in Book Antiqua with a true red (`#d40000`) as its hallmark.
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
- ## Stack
11
+ ## Install for bundler users
10
12
 
11
- - [Vite](https://vite.dev/) 8 + [TypeScript](https://www.typescriptlang.org/) — no framework, just DOM
12
- - [Vitest](https://vitest.dev/) 4 + jsdom for tests, [ESLint](https://eslint.org/) for linting
13
- - Plainchant notation via the custom `Guidohu` glyph font (`public/fonts/guidohu.ttf`)
13
+ ```
14
+ npm i guidex
15
+ ```
14
16
 
15
- ## Development
17
+ The package ships a typed ESM build with an exports map:
16
18
 
17
- ```sh
18
- npm install
19
- npm run dev # dev server at http://localhost:5173
20
- npm run build # type-check and production build
21
- npm test # vitest run (jsdom environment)
22
- npm run lint # eslint
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
- CI runs lint and unit tests on every push.
26
-
27
- ## Project layout
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
- ## The script notation
33
+ ### Vanilla JS
52
34
 
53
- The source alternates a leading clef group with syllables, each followed by
54
- its notes:
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
- (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-.)
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
- - The first parenthesized group is the starting clef with note modifiers.
61
- - Every syllable of text precedes the parenthesized group of notes it is
62
- sung to.
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
- In the rendered score, notes are set in the Guidohu font at twice the
71
- surrounding text size. Notes are measured with a hidden canvas after
72
- webfonts load, and each syllable is aligned against the measured ink of
73
- its notes — left-aligned when the notes are wider, centered otherwise.
74
- When a finite max width is given, the score breaks into multiple line
75
- pairs, repeating the clef on every line and hanging a hyphen at line ends
76
- that split a word.
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 on other sites (issue #30)
66
+ ## Embedding with a script tag (no bundler)
79
67
 
80
- `npm run build:embed` produces a self-contained `dist-embed/` folder that
81
- can be hosted on any static server or CDN and dropped into a site's
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; site-wide defaults can be set
99
- with `GuidexEmbed.init({ maxWidth: 'auto', style: 'BNS', … })`. Element
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
- | Attribute | Values | Default |
105
- | ----------------- | ------------------------------- | -------------- |
106
- | `data-max-width` | pixels, or `auto` (fits the element, re-rendered on resize) | `auto` |
107
- | `data-style` | `BNS`, `Vesperale` | `BNS` |
108
- | `data-bold` | boolean | `false` |
109
- | `data-text-px` | base text size in px (notes render at 2×) | `18` |
110
- | `data-transpose` | pitch-row shift (see `transposeBy`) | `0` |
111
- | `data-debug` | boolean (measurement titles on spans) | `false` |
112
-
113
- The build emits `guidex-embed.min.js` (minified IIFE, global
114
- `GuidexEmbed`), `guidex-embed.min.css`, the `fonts/` folder, and a
115
- `demo.html` — open the demo after building (e.g. `npx serve dist-embed`)
116
- to see a rendered example. A failed render (unknown style, unloadable
117
- font) leaves an error note in the target instead of throwing.
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. The main page hosts a
124
- live editor with sample scores. See `CLAUDE.md` for the detailed
125
- rendering model and project guidance.
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.