@ugfoundation/swaralipi-js 0.1.0

package/dist/viewer/index.d.ts

@@ -0,0 +1,285 @@
+import { O as Octave, a as SvaraLetter, N as Note, S as Swaralipi } from '../schema-gxhG45OK.js';
+import 'zod';
+
+/**
+ * Per-language glyph tables + Unicode cluster composition for the viewer.
+ *
+ * The akarmatrik system is script-portable: Bengali and Devanagari use the
+ * same letters-with-distinct-komal-forms convention (legend: কোমল র—ঋ,
+ * কোমল গ—জ্ঞ, কড়ি ম—ক্ষ, কোমল ধ—দ, কোমল ন—ণ), the same আ-কার matra carrier,
+ * the same reph-above for taar and understroke for mandra. `en` has no
+ * native convention, so it uses S R G M P D N with CSS marks (komal
+ * underline, tivra prime, octave dots) and no matra carrier.
+ *
+ * Unicode hazards owned here (see composeCluster):
+ *  - mandra can NEVER be a real hasanta: letter + ্ + া is an invalid
+ *    cluster (virama before vowel sign → dotted circle). It is always a
+ *    CSS understroke (`sw-mandra`).
+ *  - ঋ/ऋ (komal re) is an independent VOWEL letter: both র্+ঋ (reph over a
+ *    vowel) and ঋ+া (vowel sign on a vowel) are invalid clusters. taar-ঋ
+ *    falls back to a CSS reph (`sw-reph-css`); a matra following ঋ must be
+ *    emitted as a separate isolated-matra span (`matraSeparate`).
+ *  - Isolated dependent signs (া, ঃ) need a base: U+00A0 NBSP is the
+ *    Unicode-sanctioned placeholder base and avoids dotted circles.
+ */
+
+type ViewerLang = 'bn' | 'hi' | 'en';
+interface LetterForms {
+    shuddha: string;
+    /** Distinct komal glyph (bn/hi); absent for en (CSS underline instead). */
+    komal?: string;
+    /** Distinct tivra glyph (bn/hi ক্ষ/क्ष); absent for en (CSS prime). */
+    tivra?: string;
+}
+declare const LETTERS: Record<ViewerLang, Record<SvaraLetter, LetterForms>>;
+/** Digits 0-9 in the target script (beat labels, avartan). */
+declare const DIGITS: Record<ViewerLang, string>;
+interface LangMarks {
+    /** আ-কার matra carrier appended to a group-final cluster ('' for en). */
+    matra: string;
+    /** Melisma / no-new-attack dash before a sustained cluster. */
+    hyphen: string;
+    /** Lyric continuation mark shown under sustains (the source uses ৹). */
+    melisma: string;
+    /** ছেদ cut/articulation mark (two stacked rings, ঃ-shaped). */
+    cut: string;
+    /** Real-text reph prefix for taar ('' for en → CSS dot instead). */
+    reph: string;
+}
+declare const MARKS: Record<ViewerLang, LangMarks>;
+/** Header labels (NLTR prints নাম / তাল / আবর্তন …). */
+declare const LABELS: Record<ViewerLang, {
+    title: string;
+    taal: string;
+    raag: string;
+    avartan: string;
+    notationBy: string;
+}>;
+/** A composed notation cluster: text plus the CSS classes for marks the
+ * text itself cannot carry (mandra understroke, ati dots, en komal/tivra,
+ * CSS-reph fallback). */
+interface Cluster {
+    text: string;
+    classes: string[];
+    /** Set when the matra could not join the cluster (ঋ/ऋ, or en where the
+     * carrier doesn't exist) and must be emitted as an isolated-matra span. */
+    matraSeparate: boolean;
+}
+interface ComposeOptions {
+    komal?: boolean;
+    tivra?: boolean;
+    octave: Octave;
+    /** Append the আ-কার matra carrier (group-final notes only). */
+    withMatra: boolean;
+    lang: ViewerLang;
+}
+/**
+ * Compose one svara cluster. The single place that knows Unicode
+ * composition order: reph? + base + matra?, with the ঋ/mandra/en fallbacks
+ * documented in the file header.
+ */
+declare function composeCluster(letter: SvaraLetter, opts: ComposeOptions): Cluster;
+/** Map ASCII digits in `s` to the target script's digits. */
+declare function localizeDigits(s: string, lang: ViewerLang): string;
+
+/**
+ * Pure spec-JSON → HTML renderer. No DOM, no side effects: usable for SSR
+ * (Astro/static sites emit `renderToHtml(doc)` next to a
+ * `<style>${SWARALIPI_CSS}</style>`) and unit-testable in plain Node.
+ *
+ * Layout model (mirrors NLTR's 4-row systems): each spec `Row` becomes one
+ * CSS grid with **one column per top-level note** and four grid rows —
+ * above-annotations / notation / below (slur arcs, marks) / lyric. Source
+ * cells (groups of sub-notes sharing one matra) become column *spans*, so
+ * per-sub-note lyric alignment and P2.3's per-note highlight targets fall
+ * out of the column model for free.
+ *
+ * Rendering is spec-driven (semantics, not `raw`): grouping derives from
+ * `durationMatra` accumulation so hand-authored documents without `raw`
+ * render identically. `raw` is consulted only for (a) raw-only fallback
+ * notes (never dropped — dimmed monospace), (b) the ছেদ cut mark and beat
+ * labels, whose grammar lives in raw (see src/convert/codec.ts).
+ */
+
+interface RenderOptions {
+    /** Notation + UI language. Default `bn`. */
+    lang?: ViewerLang;
+    /** Render the NLTR-style নাম/তাল/আবর্তন header block. Default true. */
+    showHeader?: boolean;
+    /**
+     * Lyric/title transliterator for `hi`/`en` (see loadLyricTransliterator).
+     * Without it, non-bn renders keep Bengali lyrics (graceful interim).
+     */
+    transliterate?: (bengaliText: string) => string;
+}
+interface Cell {
+    kind: 'bar' | 'group' | 'raw' | 'carrier';
+    /** Index of the cell's first note within the row's notes array. */
+    start: number;
+    notes: Note[];
+}
+/**
+ * Group a row's notes into rendered cells using a fractional-duration
+ * accumulator (raw-independent — works for hand-authored docs):
+ *  - bar / raw-only / carrier notes force-close and form singleton cells;
+ *  - full-matra notes are singleton groups;
+ *  - fractional notes accumulate until the sum reaches an integer matra
+ *    boundary (epsilon for 1/3, 0.2 chains), then the group closes.
+ * The converter emits k notes × 1/k per source cell, so groups coincide
+ * with source cells; an incomplete trailing group still closes at row end
+ * (the matra carrier lands on its last note).
+ */
+declare function groupRowIntoCells(notes: Note[]): Cell[];
+interface Arc {
+    /** 1-based grid column of the arc's first / last note column. */
+    startCol: number;
+    endCol: number;
+    /** True when the matching end lies on a previous / following system. */
+    openLeft: boolean;
+    openRight: boolean;
+    /** Fill-segments-only row: render a straight underline, no curled ends. */
+    line?: boolean;
+}
+/**
+ * Resolve under-arcs for one row. Sources, scanned left→right:
+ *  - below-annotation raws: `w` opens at its cell's first column, `x`
+ *    closes at its cell's last column ("xw" in one cell = close-then-open);
+ *  - spec `meend: 'start' | 'end'` fields feed the same scan as synthetic
+ *    w/x at the note's own column.
+ * Unmatched `x` → arc from column 1 with a squared-off (open) left end;
+ * unclosed `w` → arc to the last column with an open right end — both
+ * match the print's behavior when an arc continues across a system wrap.
+ * A row with fill segments but no ends at all renders one straight line.
+ */
+declare function resolveArcs(cells: Cell[], noteCount: number): Arc[];
+/** Render a complete swaralipi document to an HTML string. Pair with
+ * SWARALIPI_CSS (shadow DOM does this automatically; SSR consumers emit a
+ * `<style>` themselves). All source text is HTML-escaped. */
+declare function renderToHtml(doc: Swaralipi, opts?: RenderOptions): string;
+
+/**
+ * Encapsulated stylesheet for the viewer. Injected into the
+ * `<swaralipi-sheet>` shadow root automatically; SSR consumers emit it
+ * themselves: `<style>${SWARALIPI_CSS}</style>` next to `renderToHtml()`.
+ *
+ * Theming hooks (CSS custom properties, all optional):
+ *   --sw-font       font stack (default: Noto Sans Bengali + system Bengali)
+ *   --sw-size       base font size
+ *   --sw-cell-gap   horizontal gap between source cells
+ *   --sw-hl         player-highlight background (P2.3)
+ *   --sw-rule       header rule / muted line color
+ *
+ * All ink uses `currentColor`, so the sheet follows the host's text color
+ * (dark mode included). Octave marks that Unicode cannot express in a valid
+ * cluster (mandra understroke, ati dots, ঋ-reph, en octave dots) are drawn
+ * with positioned pseudo-elements; offsets are em-based and tuned against
+ * the NLTR reference rendering of song 4270.
+ */
+declare const SWARALIPI_CSS = "\n.sw-sheet {\n  font-family: var(--sw-font, 'Noto Sans Bengali', 'Kohinoor Bangla', 'Bangla Sangam MN', 'Nirmala UI', 'Noto Sans Devanagari', sans-serif);\n  font-size: var(--sw-size, 1.125rem);\n  line-height: 1.5;\n}\n\n/* ---- header ---- */\n.sw-header {\n  margin: 0 0 0.75em;\n  padding: 0 0 0.5em;\n  border-bottom: 1px solid var(--sw-rule, rgba(128, 128, 128, 0.35));\n  font-size: 0.95em;\n}\n.sw-meta-row { display: flex; gap: 0.3em; }\n.sw-meta-label { font-weight: 600; min-width: 4.5em; }\n.sw-meta-label::after { content: ':'; font-weight: 400; margin-left: 0.15em; }\n\n.sw-part-name { font-size: 0.85em; font-weight: 600; margin: 1em 0 0.2em; opacity: 0.85; }\n\n/* ---- row grid: above / notation / below(arcs) / lyric ---- */\n.sw-row {\n  display: flex;\n  align-items: flex-start;\n  overflow-x: auto;\n  padding: 0.4em 0;\n}\n.sw-label { flex: none; margin-right: 0.8em; font-weight: 600; }\n.sw-grid {\n  display: grid;\n  grid-template-rows: auto auto auto auto;\n  grid-auto-columns: max-content;\n  align-items: end;\n}\n.sw-above   { grid-row: 1; font-size: 0.62em; justify-self: start; white-space: nowrap; padding-left: 0.2em; }\n.sw-n       { grid-row: 2; white-space: nowrap; }\n.sw-arc,\n.sw-below   { grid-row: 3; }\n.sw-lyr     { grid-row: 4; white-space: nowrap; padding-top: 0.3em; }\n.sw-below   { font-size: 0.62em; justify-self: start; white-space: nowrap; padding-left: 0.2em; }\n\n/* inter-cell gap as padding on each cell's first notation item, so arcs\n * and above-spans crossing cells stay continuous */\n.sw-cs { padding-left: var(--sw-cell-gap, 0.55em); }\n\n/* ---- notation clusters & marks ---- */\n.sw-cl { position: relative; display: inline-block; }\n\n/* mandra: hasanta-shaped understroke (a real \u09CD before \u09BE is invalid Unicode) */\n.sw-mandra::after {\n  content: '';\n  position: absolute;\n  left: 0.1em;\n  bottom: -0.08em;\n  width: 0.45em;\n  height: 0.09em;\n  background: currentColor;\n  transform: rotate(-32deg);\n}\n/* ati-mandra: an extra dot below */\n.sw-ati-mandra::before {\n  content: '';\n  position: absolute;\n  left: 0.25em;\n  bottom: -0.35em;\n  width: 0.16em;\n  height: 0.16em;\n  border-radius: 50%;\n  background: currentColor;\n}\n/* ati-taar (reph already in the text): an extra dot above */\n.sw-ati-taar::before {\n  content: '';\n  position: absolute;\n  left: 0.25em;\n  top: -0.3em;\n  width: 0.16em;\n  height: 0.16em;\n  border-radius: 50%;\n  background: currentColor;\n}\n/* CSS reph fallback for vowel letters \u098B/\u090B that reject a real reph */\n.sw-reph-css::before {\n  content: '';\n  position: absolute;\n  top: -0.12em;\n  left: 0.12em;\n  width: 0.3em;\n  height: 0.3em;\n  border: 0.09em solid currentColor;\n  border-right: none;\n  border-bottom: none;\n  border-top-left-radius: 0.3em;\n}\n/* en octave dots (Bhatkhande-style) */\n.sw-dot-above::before,\n.sw-dot-below::before {\n  content: '';\n  position: absolute;\n  left: 50%;\n  margin-left: -0.07em;\n  width: 0.14em;\n  height: 0.14em;\n  border-radius: 50%;\n  background: currentColor;\n}\n.sw-dot-above::before { top: -0.25em; }\n.sw-dot-below::before { bottom: -0.2em; }\n.sw-ati-taar.sw-dot-above::before,\n.sw-ati-mandra.sw-dot-below::before { box-shadow: 0.24em 0 0 currentColor; margin-left: -0.19em; }\n/* en accidentals (bn/hi use distinct letters instead) */\n.sw-komal { text-decoration: underline; text-underline-offset: 0.18em; }\n.sw-tivra::after { content: '\\2032'; font-size: 0.7em; vertical-align: super; }\n\n/* kan grace: small raised cluster left of the main note */\n.sw-kan {\n  position: relative;\n  display: inline-block;\n  font-size: 0.58em;\n  vertical-align: 0.75em;\n  margin-right: 0.08em;\n}\n\n.sw-hy { padding-right: 0.02em; }\n.sw-iso { display: inline-block; margin-left: -0.18em; }\n.sw-cut { font-size: 0.8em; display: inline-block; margin-left: -0.15em; }\n.sw-br { opacity: 0.8; padding: 0 0.06em; }\n.sw-micro { font-size: 0.6em; vertical-align: super; opacity: 0.8; }\n\n/* raw fallback: never dropped, visibly non-notation */\n.sw-raw {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 0.72em;\n  opacity: 0.55;\n}\n\n/* ---- bars: dari (thin) and danda strokes, notation-row height ---- */\n/* horizontal gap before a bar comes from its own .sw-cs padding-left \u2014\n * never reset it with a padding shorthand here */\n.sw-bar {\n  grid-row: 2;\n  align-self: stretch;\n  display: inline-flex;\n  align-items: stretch;\n  gap: 0.16em;\n  padding-right: 0.1em;\n}\n.sw-bar i { display: inline-block; width: 0.14em; min-height: 1.25em; background: currentColor; }\n.sw-bar--dari i { width: 0.05em; opacity: 0.9; }\n.sw-bar--quad i:nth-child(3) { margin-left: 0.18em; }\n.sw-above .sw-bar, .sw-below .sw-bar { display: inline-flex; vertical-align: baseline; }\n.sw-above .sw-bar i, .sw-below .sw-bar i { min-height: 1em; }\n\n/* ---- under-arcs (slurs decoded from w/x segments and meend) ---- */\n.sw-arc {\n  align-self: start;\n  height: 0.4em;\n  margin: 0.05em 0.25em 0;\n  border: 0.09em solid currentColor;\n  border-top: none;\n  border-bottom-left-radius: 0.6em;\n  border-bottom-right-radius: 0.6em;\n  opacity: 0.85;\n}\n.sw-arc--openl { border-left: none; border-bottom-left-radius: 0; }\n.sw-arc--openr { border-right: none; border-bottom-right-radius: 0; }\n.sw-arc--line { border-left: none; border-right: none; border-radius: 0; height: 0.22em; }\n\n/* ---- annotation content ---- */\n.sw-beat { position: relative; display: inline-block; padding: 0 0.1em; }\n.sw-sam::after {\n  content: '';\n  position: absolute;\n  top: -0.45em;\n  left: 50%;\n  width: 0.1em;\n  height: 0.4em;\n  background: currentColor;\n  transform: rotate(14deg);\n}\n.sw-stop i {\n  display: inline-block;\n  width: 0.07em;\n  height: 1em;\n  margin: 0 0.07em;\n  background: currentColor;\n  vertical-align: text-bottom;\n}\n\n/* ---- player sync (P2.3) ---- */\n.sw-hl { background: var(--sw-hl, rgba(255, 196, 64, 0.45)); border-radius: 0.15em; }\n\n/* ---- element error box ---- */\n.sw-error {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 0.85em;\n  padding: 0.6em 0.8em;\n  border: 1px solid rgba(200, 64, 64, 0.6);\n  border-radius: 0.3em;\n  color: #b33;\n  background: rgba(200, 64, 64, 0.08);\n}\n";
+/**
+ * Print stylesheet — pair with `SWARALIPI_CSS` (renderPrintDocument injects
+ * both). Gated on `@media print`, so it also works if a consumer drops it into
+ * a page and prints that page directly.
+ *
+ *  - `print-color-adjust: exact` forces the marks that are drawn as tiny
+ *    `background: currentColor` pseudo-elements (octave dots, arcs, danda
+ *    strokes, sam tick) to actually print — browsers drop backgrounds by
+ *    default, which would silently strip the notation's diacritics.
+ *  - rows are un-clipped (no scrollbar on paper) and kept whole across page
+ *    breaks; part headings stay with their first row.
+ */
+declare const SWARALIPI_PRINT_CSS = "\n@page { margin: 16mm; }\n@media print {\n  .sw-sheet { -webkit-print-color-adjust: exact; print-color-adjust: exact; color: #000; }\n  .sw-row { overflow: visible !important; break-inside: avoid; page-break-inside: avoid; }\n  .sw-part { break-inside: auto; }\n  .sw-part-name, .sw-header { break-after: avoid-page; page-break-after: avoid; }\n  .sw-hl { background: none !important; }\n}\n";
+
+/**
+ * Print / "Save as PDF" support.
+ *
+ * High-fidelity PDF of আকারমাত্রিক notation can only come from the browser's
+ * own print engine — it reuses the exact HarfBuzz shaping (reph, conjuncts,
+ * matra) and the CSS-drawn marks (octave dots, slur arcs, danda strokes) that
+ * the viewer renders on screen. Rasterizers (html2canvas) and PDF-primitive
+ * libraries (jsPDF/pdfmake) have no Indic shaping and drop pseudo-element
+ * marks, so we deliberately avoid them.
+ *
+ * `renderPrintDocument` builds a self-contained HTML page from the pure
+ * `renderToHtml` + `SWARALIPI_CSS` (so it sidesteps the shadow-DOM "print drops
+ * encapsulated styles" gotcha); `printSwaralipi` prints it via a hidden iframe.
+ * Both reuse the same renderer as the viewer, so the PDF matches the screen.
+ */
+
+interface PrintOptions {
+    /** Notation + UI language. Default `bn`. */
+    lang?: ViewerLang;
+    /** Render the নাম/তাল header block. Default true. */
+    showHeader?: boolean;
+    /** Lyric/title transliterator for hi/en (see loadLyricTransliterator). */
+    transliterate?: (bengaliText: string) => string;
+    /** Document `<title>` — the browser's default "Save as PDF" filename.
+     * Defaults to the document's `meta.title`. */
+    title?: string;
+}
+/**
+ * Build a complete, standalone HTML document for printing a swaralipi sheet:
+ * the rendered notation plus `SWARALIPI_CSS` and the print stylesheet, on a
+ * white page. Usable for a hidden-iframe print, a new browser tab, or
+ * server-side headless-Chrome PDF generation.
+ */
+declare function renderPrintDocument(doc: Swaralipi, opts?: PrintOptions): string;
+/**
+ * Open the browser print dialog for a swaralipi document (the user picks a
+ * printer or "Save as PDF"). Renders into an off-screen iframe so it prints
+ * only the sheet — independent of the host page's chrome and CSS — then cleans
+ * up. Browser-only; throws in a non-DOM environment (use renderPrintDocument
+ * for SSR / headless-Chrome instead).
+ */
+declare function printSwaralipi(doc: Swaralipi, opts?: PrintOptions): void;
+
+/**
+ * The `<swaralipi-sheet>` custom element — a thin shadow-DOM shell around
+ * the pure renderer.
+ *
+ * The element class is created lazily inside defineSwaralipiSheet():
+ * a top-level `extends HTMLElement` would throw on import in Node, and this
+ * module must stay importable for SSR (where only renderToHtml is used).
+ * Nothing registers automatically — call defineSwaralipiSheet() once.
+ *
+ * Validation is off by default (converter output is pre-validated); setting
+ * `validate = true` parses documents against the Zod schema via a dynamic
+ * import, so the viewer bundle stays free of bare runtime imports (it can
+ * be loaded directly from dist/ in a browser without a bundler).
+ */
+
+interface SwaralipiSheetElement extends HTMLElement {
+    /** The document to render (property only; renders on assignment). */
+    doc: Swaralipi | undefined;
+    /** Parse documents against the spec schema before rendering. */
+    validate: boolean;
+    /** Add the player-highlight class to the note at "part.row.note". */
+    highlight(path: string): HTMLElement | null;
+    clearHighlights(): void;
+    /** Open the print dialog (→ "Save as PDF") for the current document. */
+    print(options?: PrintOptions): void;
+}
+/**
+ * Register `<swaralipi-sheet>` (or a custom tag name). Idempotent. Throws
+ * outside a DOM environment — use renderToHtml() for SSR.
+ */
+declare function defineSwaralipiSheet(tagName?: string): CustomElementConstructor;
+
+/**
+ * Lazy lyric transliteration for `hi` / `en` renders.
+ *
+ * Swara glyphs come from the sync tables in glyphs.ts; only *linguistic*
+ * text (lyrics, title, names) needs transliteration, so sanscript loads via
+ * dynamic import — `bn`-only consumers (and their bundles) never touch it.
+ */
+
+type Transliterator = (bengaliText: string) => string;
+/**
+ * Load a Bengali→target transliterator for the given viewer language.
+ * Returns undefined for `bn` (no work to do). Pass the result as
+ * `RenderOptions.transliterate`; the `<swaralipi-sheet>` element wires this
+ * automatically when its `lang` attribute changes.
+ */
+declare function loadLyricTransliterator(lang: ViewerLang): Promise<Transliterator | undefined>;
+
+export { type Arc, type Cell, type Cluster, type ComposeOptions, DIGITS, LABELS, LETTERS, MARKS, type PrintOptions, type RenderOptions, SWARALIPI_CSS, SWARALIPI_PRINT_CSS, type SwaralipiSheetElement, type Transliterator, type ViewerLang, composeCluster, defineSwaralipiSheet, groupRowIntoCells, loadLyricTransliterator, localizeDigits, printSwaralipi, renderPrintDocument, renderToHtml, resolveArcs };