@ugfoundation/swaralipi-js 0.6.0 → 0.7.0

package/dist/viewer/index.d.cts

@@ -106,12 +106,39 @@ interface Cell {
  * 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).
+ *
+ * Adjacent bar/carrier cells are finally merged, because NLTR types them as
+ * ONE table cell: the song-end `L L` (‖ ‖) and the asthayi-return `l [ ] l`
+ * each occupy a single column, not two or four.
  */
 declare function groupRowIntoCells(notes: Note[]): Cell[];
+interface Layout {
+    /** Total columns the document's grid needs. */
+    width: number;
+    /** Column offset of each row, in document order. */
+    offsets: number[];
+}
+/**
+ * Give every row of a document its column offset, so all rows share one set
+ * of grid tracks (NLTR's single-table layout, re-derived from the spec JSON
+ * — the source column index is not stored).
+ *
+ * A full line is `W` cells wide (the modal width of rows that open on a bar).
+ * A shorter row is right-aligned into the সম only when it *starts* a phrase —
+ * it opens without a bar, or it is the first row, or the previous row closed
+ * a section (‖). A short row that merely finishes one stays flush left. A row
+ * without its own closing bar leaves that last column empty, so it ends one
+ * column earlier.
+ *
+ * Measured against all 1738 NLTR pages: 99.1 % of rows and 99.4 % of cells
+ * land on the source's exact column. The residual is source defects — rows
+ * where NLTR itself skips a column — which this packs flush instead.
+ */
+declare function alignRows(rows: Cell[][]): Layout;
 interface Arc {
-    /** 1-based grid column of the arc's first / last note column. */
-    startCol: number;
-    endCol: number;
+    /** 0-based index of the arc's first / last **cell** within the row. */
+    start: number;
+    end: number;
     /** True when the matching end lies on a previous / following system. */
     openLeft: boolean;
     openRight: boolean;
@@ -119,17 +146,17 @@ interface Arc {
     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.
+ * Resolve under-arcs for one row, in **cell** indices (cells are the grid's
+ * columns). Sources, scanned left→right:
+ *  - below-annotation raws: `w` opens at its cell, `x` closes at its cell
+ *    ("xw" in one cell = close-then-open, in the order typed);
+ *  - spec `meend: 'start' | 'end'` fields feed the same scan.
+ * Unmatched `x` → arc from cell 0 with a squared-off (open) left end;
+ * unclosed `w` → arc to the last cell 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[];
+declare function resolveArcs(cells: Cell[]): Arc[];
 /**
  * The matra marks a cell's final note carries: its total duration as whole
  * আ-কার matras plus an optional অর্ধমাত্রা ঃ (legend `রাঃ` = 1½, `সঃ` = ½).
@@ -152,6 +179,33 @@ declare function renderMetaHeader(meta: Meta, lang: GridLang, tr?: (s: string) =
  * `<style>` themselves). All source text is HTML-escaped. */
 declare function renderToHtml(doc: Swaralipi, opts?: RenderOptions): string;
 
+/**
+ * Fit a sheet's shared grid to the width it has, then layer a user zoom on
+ * top.
+ *
+ * The whole document is one grid (see render.ts), so a sheet has exactly one
+ * natural width — a wide তাল overruns a phone or an A4 page. Everything
+ * inside is em-relative, so scaling the sheet's `font-size` scales the
+ * notation without disturbing the column alignment; a `transform` would
+ * scale it too, but would also break print pagination.
+ *
+ * Free-scaling by default (no floor): the sheet should always fit on first
+ * paint rather than fall back to `.sw-scroll`'s horizontal scrollbar — a
+ * `minScale` floor exists only for print, where paper cannot scroll.
+ * `zoom` (default 1) multiplies the fit scale so callers can zoom in past
+ * fit-to-width; past that point `.sw-scroll` panning is expected, same as a
+ * photo viewer.
+ *
+ * Self-contained on purpose — print.ts serialises this function into the
+ * print page, so it must not close over anything or import anything.
+ */
+declare function fitSwaralipi(root: Document | ShadowRoot | HTMLElement, minScale?: number, zoom?: number): void;
+/** Zoom bounds/step for zoomIn()/zoomOut()/the `zoom` property — exported so
+ * a consumer's own zoom UI (e.g. a slider) can match the element's clamp. */
+declare const MIN_ZOOM = 0.5;
+declare const MAX_ZOOM = 3;
+declare const ZOOM_STEP = 1.2;
+
 /**
  * Encapsulated stylesheet for the viewer. Injected into the
  * `<swaralipi-sheet>` shadow root automatically; SSR consumers emit it
@@ -188,7 +242,7 @@ declare const SWARALIPI_CSS: string;
  *  - 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, .sw-staff { -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  /* Keep each engraved staff system whole across a page break (the abcjs line\n     is a <div> wrapping the <svg>, so the break rule must sit on the div). */\n  .sw-staff-lines > div { break-inside: avoid; page-break-inside: avoid; }\n  .sw-staff-meta { break-after: avoid-page; page-break-after: avoid; }\n}\n";
+declare const SWARALIPI_PRINT_CSS = "\n@page { margin: 16mm; }\n@media print {\n  .sw-sheet, .sw-staff { -webkit-print-color-adjust: exact; print-color-adjust: exact; color: #000; }\n  .sw-scroll { overflow: visible !important; }\n  .sw-row { break-inside: avoid; page-break-inside: avoid; }\n  .sw-part-name, .sw-header { break-after: avoid-page; page-break-after: avoid; }\n  .sw-hl { background: none !important; }\n  /* Keep each engraved staff system whole across a page break (the abcjs line\n     is a <div> wrapping the <svg>, so the break rule must sit on the div). */\n  .sw-staff-lines > div { break-inside: avoid; page-break-inside: avoid; }\n  .sw-staff-meta { break-after: avoid-page; page-break-after: avoid; }\n}\n";
 /** Staff-notation (abcjs) wrapper chrome: instrument/tempo header + a fluid
  * SVG. The engraving itself is drawn by abcjs; this only frames it. */
 declare const SWARALIPI_STAFF_CSS = "\n.sw-staff { color: currentColor; }\n.sw-staff-meta { display: flex; gap: 1.25em; align-items: baseline; margin: 0 0 .5em; font-size: .95em; opacity: .85; }\n.sw-staff-instrument { font-weight: 600; }\n.sw-staff-drums { opacity: .75; }\n.sw-staff-tempo { font-variant-numeric: tabular-nums; }\n/* abcjs (oneSvgPerLine) wraps the music into one <div><svg> per system; stack\n   them as short, swaralipi-style lines. abcjs sets a fixed pixel height +\n   overflow:hidden on each wrapper div \u2014 neutralise it so the viewBox'd SVG can\n   scale to the container (and to the print page) instead of being clipped. */\n.sw-staff-lines > div { margin: 0 0 .35em; height: auto !important; overflow: visible !important; }\n/* Fill up to the engraved (staffwidth) size \u2014 shrink to fit a narrow container,\n   but never stretch past natural width (abcToSvg pins per-SVG max-width in px),\n   else a short last system balloons. */\n.sw-staff-lines svg { display: block; width: 100%; height: auto; }\n.sw-staff-missing { padding: 1em; border: 1px dashed currentColor; border-radius: 6px; opacity: .8; font-size: .9em; }\n.sw-staff-title { font-size: 1.15em; font-weight: 700; }\n.sw-staff-subtitle { opacity: .8; font-size: .95em; margin-top: .15em; }\n";
@@ -436,6 +490,18 @@ interface SwaralipiSheetElement extends HTMLElement {
     print(options?: PrintOptions): void;
     /** Options for the `staff` language (instrument label, tonic, bpm…). */
     staffOptions: StaffOptions;
+    /** Re-fit the notation to the element's current width. */
+    fit(): void;
+    /** Zoom factor on top of fit-to-width (1 = fit; clamped to
+     * [MIN_ZOOM, MAX_ZOOM]). Assigning re-fits immediately. Resets to 1 on the
+     * next doc/lang re-render — a resize alone (fit()) does not reset it. */
+    zoom: number;
+    /** `zoom *= ZOOM_STEP`, clamped. */
+    zoomIn(): void;
+    /** `zoom /= ZOOM_STEP`, clamped. */
+    zoomOut(): void;
+    /** Back to fit-to-width (`zoom = 1`). */
+    resetZoom(): void;
 }
 /**
  * Register `<swaralipi-sheet>` (or a custom tag name). Idempotent. Throws
@@ -460,4 +526,4 @@ type Transliterator = (bengaliText: string) => string;
  */
 declare function loadLyricTransliterator(lang: ViewerLang): Promise<Transliterator | undefined>;
 
-export { type Arc, type Cell, type Cluster, type ComposeOptions, DEFAULT_NOTATOR, DEFAULT_WATERMARK, DIGITS, type GridLang, LABELS, MARKS, NOTATION_FONT_URLS, type PrintOptions, type RenderOptions, SWARALIPI_CSS, SWARALIPI_PRINT_CSS, SWARALIPI_STAFF_CSS, type StaffOptions, type SwaralipiSheetElement, type TaalStaffOptions, type Transliterator, type ViewerLang, abcDuration, abcToSvg, buildAbc, buildTaalAbc, cellMatra, composeCluster, defineSwaralipiSheet, docToAbc, groupRowIntoCells, loadLyricTransliterator, localizeDigits, midiToAbc, printSwaralipi, renderMetaHeader, renderPrintDocument, renderStaffHtml, renderStaffPrintDocument, renderTaalStaffHtml, renderToHtml, resolveArcs };
+export { type Arc, type Cell, type Cluster, type ComposeOptions, DEFAULT_NOTATOR, DEFAULT_WATERMARK, DIGITS, type GridLang, LABELS, type Layout, MARKS, MAX_ZOOM, MIN_ZOOM, NOTATION_FONT_URLS, type PrintOptions, type RenderOptions, SWARALIPI_CSS, SWARALIPI_PRINT_CSS, SWARALIPI_STAFF_CSS, type StaffOptions, type SwaralipiSheetElement, type TaalStaffOptions, type Transliterator, type ViewerLang, ZOOM_STEP, abcDuration, abcToSvg, alignRows, buildAbc, buildTaalAbc, cellMatra, composeCluster, defineSwaralipiSheet, docToAbc, fitSwaralipi, groupRowIntoCells, loadLyricTransliterator, localizeDigits, midiToAbc, printSwaralipi, renderMetaHeader, renderPrintDocument, renderStaffHtml, renderStaffPrintDocument, renderTaalStaffHtml, renderToHtml, resolveArcs };

package/dist/viewer/index.d.ts

@@ -106,12 +106,39 @@ interface Cell {
  * 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).
+ *
+ * Adjacent bar/carrier cells are finally merged, because NLTR types them as
+ * ONE table cell: the song-end `L L` (‖ ‖) and the asthayi-return `l [ ] l`
+ * each occupy a single column, not two or four.
  */
 declare function groupRowIntoCells(notes: Note[]): Cell[];
+interface Layout {
+    /** Total columns the document's grid needs. */
+    width: number;
+    /** Column offset of each row, in document order. */
+    offsets: number[];
+}
+/**
+ * Give every row of a document its column offset, so all rows share one set
+ * of grid tracks (NLTR's single-table layout, re-derived from the spec JSON
+ * — the source column index is not stored).
+ *
+ * A full line is `W` cells wide (the modal width of rows that open on a bar).
+ * A shorter row is right-aligned into the সম only when it *starts* a phrase —
+ * it opens without a bar, or it is the first row, or the previous row closed
+ * a section (‖). A short row that merely finishes one stays flush left. A row
+ * without its own closing bar leaves that last column empty, so it ends one
+ * column earlier.
+ *
+ * Measured against all 1738 NLTR pages: 99.1 % of rows and 99.4 % of cells
+ * land on the source's exact column. The residual is source defects — rows
+ * where NLTR itself skips a column — which this packs flush instead.
+ */
+declare function alignRows(rows: Cell[][]): Layout;
 interface Arc {
-    /** 1-based grid column of the arc's first / last note column. */
-    startCol: number;
-    endCol: number;
+    /** 0-based index of the arc's first / last **cell** within the row. */
+    start: number;
+    end: number;
     /** True when the matching end lies on a previous / following system. */
     openLeft: boolean;
     openRight: boolean;
@@ -119,17 +146,17 @@ interface Arc {
     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.
+ * Resolve under-arcs for one row, in **cell** indices (cells are the grid's
+ * columns). Sources, scanned left→right:
+ *  - below-annotation raws: `w` opens at its cell, `x` closes at its cell
+ *    ("xw" in one cell = close-then-open, in the order typed);
+ *  - spec `meend: 'start' | 'end'` fields feed the same scan.
+ * Unmatched `x` → arc from cell 0 with a squared-off (open) left end;
+ * unclosed `w` → arc to the last cell 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[];
+declare function resolveArcs(cells: Cell[]): Arc[];
 /**
  * The matra marks a cell's final note carries: its total duration as whole
  * আ-কার matras plus an optional অর্ধমাত্রা ঃ (legend `রাঃ` = 1½, `সঃ` = ½).
@@ -152,6 +179,33 @@ declare function renderMetaHeader(meta: Meta, lang: GridLang, tr?: (s: string) =
  * `<style>` themselves). All source text is HTML-escaped. */
 declare function renderToHtml(doc: Swaralipi, opts?: RenderOptions): string;
 
+/**
+ * Fit a sheet's shared grid to the width it has, then layer a user zoom on
+ * top.
+ *
+ * The whole document is one grid (see render.ts), so a sheet has exactly one
+ * natural width — a wide তাল overruns a phone or an A4 page. Everything
+ * inside is em-relative, so scaling the sheet's `font-size` scales the
+ * notation without disturbing the column alignment; a `transform` would
+ * scale it too, but would also break print pagination.
+ *
+ * Free-scaling by default (no floor): the sheet should always fit on first
+ * paint rather than fall back to `.sw-scroll`'s horizontal scrollbar — a
+ * `minScale` floor exists only for print, where paper cannot scroll.
+ * `zoom` (default 1) multiplies the fit scale so callers can zoom in past
+ * fit-to-width; past that point `.sw-scroll` panning is expected, same as a
+ * photo viewer.
+ *
+ * Self-contained on purpose — print.ts serialises this function into the
+ * print page, so it must not close over anything or import anything.
+ */
+declare function fitSwaralipi(root: Document | ShadowRoot | HTMLElement, minScale?: number, zoom?: number): void;
+/** Zoom bounds/step for zoomIn()/zoomOut()/the `zoom` property — exported so
+ * a consumer's own zoom UI (e.g. a slider) can match the element's clamp. */
+declare const MIN_ZOOM = 0.5;
+declare const MAX_ZOOM = 3;
+declare const ZOOM_STEP = 1.2;
+
 /**
  * Encapsulated stylesheet for the viewer. Injected into the
  * `<swaralipi-sheet>` shadow root automatically; SSR consumers emit it
@@ -188,7 +242,7 @@ declare const SWARALIPI_CSS: string;
  *  - 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, .sw-staff { -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  /* Keep each engraved staff system whole across a page break (the abcjs line\n     is a <div> wrapping the <svg>, so the break rule must sit on the div). */\n  .sw-staff-lines > div { break-inside: avoid; page-break-inside: avoid; }\n  .sw-staff-meta { break-after: avoid-page; page-break-after: avoid; }\n}\n";
+declare const SWARALIPI_PRINT_CSS = "\n@page { margin: 16mm; }\n@media print {\n  .sw-sheet, .sw-staff { -webkit-print-color-adjust: exact; print-color-adjust: exact; color: #000; }\n  .sw-scroll { overflow: visible !important; }\n  .sw-row { break-inside: avoid; page-break-inside: avoid; }\n  .sw-part-name, .sw-header { break-after: avoid-page; page-break-after: avoid; }\n  .sw-hl { background: none !important; }\n  /* Keep each engraved staff system whole across a page break (the abcjs line\n     is a <div> wrapping the <svg>, so the break rule must sit on the div). */\n  .sw-staff-lines > div { break-inside: avoid; page-break-inside: avoid; }\n  .sw-staff-meta { break-after: avoid-page; page-break-after: avoid; }\n}\n";
 /** Staff-notation (abcjs) wrapper chrome: instrument/tempo header + a fluid
  * SVG. The engraving itself is drawn by abcjs; this only frames it. */
 declare const SWARALIPI_STAFF_CSS = "\n.sw-staff { color: currentColor; }\n.sw-staff-meta { display: flex; gap: 1.25em; align-items: baseline; margin: 0 0 .5em; font-size: .95em; opacity: .85; }\n.sw-staff-instrument { font-weight: 600; }\n.sw-staff-drums { opacity: .75; }\n.sw-staff-tempo { font-variant-numeric: tabular-nums; }\n/* abcjs (oneSvgPerLine) wraps the music into one <div><svg> per system; stack\n   them as short, swaralipi-style lines. abcjs sets a fixed pixel height +\n   overflow:hidden on each wrapper div \u2014 neutralise it so the viewBox'd SVG can\n   scale to the container (and to the print page) instead of being clipped. */\n.sw-staff-lines > div { margin: 0 0 .35em; height: auto !important; overflow: visible !important; }\n/* Fill up to the engraved (staffwidth) size \u2014 shrink to fit a narrow container,\n   but never stretch past natural width (abcToSvg pins per-SVG max-width in px),\n   else a short last system balloons. */\n.sw-staff-lines svg { display: block; width: 100%; height: auto; }\n.sw-staff-missing { padding: 1em; border: 1px dashed currentColor; border-radius: 6px; opacity: .8; font-size: .9em; }\n.sw-staff-title { font-size: 1.15em; font-weight: 700; }\n.sw-staff-subtitle { opacity: .8; font-size: .95em; margin-top: .15em; }\n";
@@ -436,6 +490,18 @@ interface SwaralipiSheetElement extends HTMLElement {
     print(options?: PrintOptions): void;
     /** Options for the `staff` language (instrument label, tonic, bpm…). */
     staffOptions: StaffOptions;
+    /** Re-fit the notation to the element's current width. */
+    fit(): void;
+    /** Zoom factor on top of fit-to-width (1 = fit; clamped to
+     * [MIN_ZOOM, MAX_ZOOM]). Assigning re-fits immediately. Resets to 1 on the
+     * next doc/lang re-render — a resize alone (fit()) does not reset it. */
+    zoom: number;
+    /** `zoom *= ZOOM_STEP`, clamped. */
+    zoomIn(): void;
+    /** `zoom /= ZOOM_STEP`, clamped. */
+    zoomOut(): void;
+    /** Back to fit-to-width (`zoom = 1`). */
+    resetZoom(): void;
 }
 /**
  * Register `<swaralipi-sheet>` (or a custom tag name). Idempotent. Throws
@@ -460,4 +526,4 @@ type Transliterator = (bengaliText: string) => string;
  */
 declare function loadLyricTransliterator(lang: ViewerLang): Promise<Transliterator | undefined>;
 
-export { type Arc, type Cell, type Cluster, type ComposeOptions, DEFAULT_NOTATOR, DEFAULT_WATERMARK, DIGITS, type GridLang, LABELS, MARKS, NOTATION_FONT_URLS, type PrintOptions, type RenderOptions, SWARALIPI_CSS, SWARALIPI_PRINT_CSS, SWARALIPI_STAFF_CSS, type StaffOptions, type SwaralipiSheetElement, type TaalStaffOptions, type Transliterator, type ViewerLang, abcDuration, abcToSvg, buildAbc, buildTaalAbc, cellMatra, composeCluster, defineSwaralipiSheet, docToAbc, groupRowIntoCells, loadLyricTransliterator, localizeDigits, midiToAbc, printSwaralipi, renderMetaHeader, renderPrintDocument, renderStaffHtml, renderStaffPrintDocument, renderTaalStaffHtml, renderToHtml, resolveArcs };
+export { type Arc, type Cell, type Cluster, type ComposeOptions, DEFAULT_NOTATOR, DEFAULT_WATERMARK, DIGITS, type GridLang, LABELS, type Layout, MARKS, MAX_ZOOM, MIN_ZOOM, NOTATION_FONT_URLS, type PrintOptions, type RenderOptions, SWARALIPI_CSS, SWARALIPI_PRINT_CSS, SWARALIPI_STAFF_CSS, type StaffOptions, type SwaralipiSheetElement, type TaalStaffOptions, type Transliterator, type ViewerLang, ZOOM_STEP, abcDuration, abcToSvg, alignRows, buildAbc, buildTaalAbc, cellMatra, composeCluster, defineSwaralipiSheet, docToAbc, fitSwaralipi, groupRowIntoCells, loadLyricTransliterator, localizeDigits, midiToAbc, printSwaralipi, renderMetaHeader, renderPrintDocument, renderStaffHtml, renderStaffPrintDocument, renderTaalStaffHtml, renderToHtml, resolveArcs };