🤖 Merge PR DefinitelyTyped#72044 fix(Verovio): Add missing methods by @bbloomf

Author: bbloomf

types/verovio/VerovioOptions.d.ts

@@ -1870,6 +1870,13 @@ export interface VerovioOptions {
      */
     ligatureAsBracket?: boolean;
 
+    /**
+     * Ligature oblique shape
+     *
+     * default: "auto"
+     */
+    ligatureOblique?: "auto" | "straight" | "curved";
+
     /**
      * Convert mensural content to a more responsive view reduced to the seleceted markup
      *

types/verovio/index.d.ts

@@ -16,9 +16,13 @@ export interface GetMeiOptions {
      */
     pageNo?: number;
     /**
-     * default true
+     * Score Based, default true
      */
     scoreBased?: boolean;
+    /**
+     * Basic, default false
+     */
+    basic?: boolean;
     /**
      * remove all @xml:id not used in the data; default false
      */
@@ -31,6 +35,50 @@ export interface TimeMapEntry {
     off?: string[];
     tempo?: number;
 }
+export interface RedoLayoutOptions {
+    /**
+     * true by default
+     */
+    resetCache?: boolean;
+}
+export interface TimeMapOptions {
+    /**
+     * Include measures in the timemap (false by default)
+     */
+    includeMeasures?: boolean;
+    /**
+     * Include rests in the timemap (false by default)
+     */
+    includeRests?: boolean;
+}
+export interface Selection {
+    measureRange?: string;
+    start?: string;
+    end?: string;
+}
+export interface PAEValidationMessage {
+    column: number;
+    row: number;
+    code: number;
+    text: string;
+    type: "error" | "warning";
+}
+export interface PAEValidation {
+    clef?: PAEValidationMessage;
+    data?: PAEValidationMessage[];
+}
+interface ExpansionMap {
+    [key: string]: any;
+}
+export interface DescriptiveFeatures {
+    intervalsChromatic: string[];
+    intervalsDiatonic: string[];
+    intervalsIds: string[];
+    pitchesChromatic: string[];
+    pitchesDiatonic: string[];
+    pitchesIds: string[];
+}
+type DescriptiveFeaturesOptions = unknown;
 
 export const module: VerovioModule;
 export interface VerovioModule {
@@ -48,14 +96,36 @@ export interface VerovioModule {
 
 export class toolkit {
     constructor(module?: VerovioModule);
+    destroy: () => void;
 
     /**
-     * Edit the MEI data.
+     * Filter Humdrum data.
+     * @returns The Humdrum data as a string
+     */
+    convertHumdrumToHumdrum: (humdrumData: string) => string;
+
+    /**
+     * Convert Humdrum data to MIDI.
+     * @returns The MIDI file as a base64-encoded string
+     */
+    convertHumdrumToMIDI: (humdrumData: string) => string;
+
+    /**
+     * Convert MEI data into Humdrum data.
+     * @returns The Humdrum data as a string
+     */
+    convertMEIToHumdrum: (mei: string) => string;
+
+    /**
+     * Edit the MEI data - experimental code not to rely on.
+     * @param editorAction The editor actions as a stringified JSON object
+     * @returns True if the edit action was successfully applied
      */
     edit: (editorAction: EditorAction) => boolean;
 
     /**
-     * Return the editor status.
+     * Return the editor status - experimental code not to rely on.
+     * @returns The editor status as a string
      */
     editInfo: () => EditorAction;
 
@@ -67,79 +137,114 @@ export class toolkit {
     getAvailableOptions: () => AvailableOptions;
 
     /**
-     * Returns array of IDs of elements being currently played.
-     * @returns A JSON object with the page and notes being played
+     * Return a dictionary of all the options with their default value.
      */
-    getElementsAtTime: (millisec: number) => { notes: string[]; page: number };
+    getDefaultOptions: () => VerovioOptions;
+
+    /**
+     * Return descriptive features as a JSON string.
+     *
+     * The features are tailored for implementing incipit search.
+     * @param jsonOptions A JSON object with the feature extraction options
+     * @returns A JSON object with the requested features
+     */
+    getDescriptiveFeatures: (jsonOptions: DescriptiveFeaturesOptions) => DescriptiveFeatures;
 
     /**
      * Return element attributes as a JSON string.
      *
      * The attributes returned include the ones not supported by Verovio
+     * @param xmlId the ID (@xml:id) of the element being looked for
      * @returns A JSON object with all attributes
      */
     getElementAttr: (xmlId: string) => { [attribute: string]: string };
 
+    /**
+     * Returns array of IDs of elements being currently played.
+     * @param millisec The time in milliseconds
+     * @returns A JSON object with the page and notes being played
+     */
+    getElementsAtTime: (millisec: number) => { notes: string[]; page: number };
+
     /**
      * Returns a vector of ID strings of all elements (the notated and the expanded) for a given element.
+     * @param xmlId the ID (@xml:id) of the element being looked for
+     * @returns A JSON object with all IDs
      */
     getExpansionIdsForElement: (xmlId: string) => { [notated: string]: string };
 
     /**
      * Get the humdrum buffer.
+     * @returns The humdrum buffer as a string
      */
     getHumdrum: () => string;
 
     /**
-     * Returns the log message of the last performed operation, for example after having called loadData.
+     * Get the log content for the latest operation.
+     * @returns The log content as a string
      */
     getLog: () => string;
 
     /**
-     * Returns the MEI data loaded in the toolkit. If a page number is provided (i.e. > 0), then
-     * only that page is exported. In score-based MEI, then only the section element will be
-     * output. Set options.scoreBased to true for standard score-based MEI and false for the
-     * internal page-based MEI.
+     * Get the MEI as a string.
+     * @param options A JSON object with the output options; pageNo: integer; (1-based), all pages if none (or 0) specified; scoreBased: true or false; true by default; basic: true or false; false by default; removeIds: true or false; false by default - remove all @xml:id not used in the data;
      */
     getMEI: (options?: GetMeiOptions) => string;
 
     /**
      * Return MIDI values of the element with the ID (xml:id)
      *
      * RenderToMIDI() must be called prior to using this method
+     * @param xmlId the ID (@xml:id) of the element being looked for
+     * @returns a JSON object with the MIDI values
      */
     getMIDIValuesForElement: (xmlId: string) => MIDIValues;
 
     /**
      * Returns the ID string of the notated (the original) element.
+     * @param xmlId the ID (@xml:id) of the element being looked for
+     * @returns An ID string
      */
     getNotatedIdForElement: (xmlId: string) => string;
 
+    /**
+     * Return a dictionary of all the options with their current value.
+     * @returns A JSON object
+     */
+    getOptions: (defaultValues?: boolean) => VerovioOptions;
+
     /**
      * Return the number of pages in the loaded document.
      *
      * The number of pages depends one the page size and if encoded layout was taken into account or not.
+     * @returns The number of pages
      */
     getPageCount: () => number;
 
     /**
      * Return the page on which the element is the ID (xml:id) is rendered.
      *
      * This takes into account the current layout options.
+     * @param xmlId the ID (@xml:id) of the element being looked for
+     * @returns the page number (1-based) where the element is (0 if not found)
      */
     getPageWithElement: (xmlId: string) => number;
 
     /**
      * Return the time at which the element is the ID (xml:id) is played.
      *
      * RenderToMIDI() must be called prior to using this method.
+     * @param xmlId the ID (@xml:id) of the element being looked for
+     * @returns The time in milliseconds
      */
     getTimeForElement: (xmlId: string) => number;
 
     /**
      * Return a JSON object string with the following key values for a given note.
      *
      * Return scoreTimeOnset, scoreTimeOffset, scoreTimeTiedDuration, realTimeOnsetMilliseconds, realTimeOffsetMilliseconds, realTimeTiedDurationMilliseconds.
+     * @param xmlId the ID (@xml:id) of the element being looked for
+     * @returns A JSON object with the values
      */
     getTimesForElement: (xmlId: string) => {
         scoreTimeOnset: number;
@@ -152,25 +257,29 @@ export class toolkit {
 
     /**
      * Return the version number.
+     * @returns the version number as a string
      */
     getVersion: () => string;
 
     /**
      * Load a string data with the type previously specified in the options.
      *
      * By default, the methods try to auto-detect the type.
+     * @param data A string with the data (e.g., MEI data) to be loaded
      * @returns True if the data was successfully loaded
      */
-    loadData: (meiData: string) => boolean;
+    loadData: (data: string) => boolean;
 
     /**
      * Load a MusicXML compressed file passed as base64 encoded string.
+     * @param zipDataBase64 A ZIP file as a base64 encoded string
      * @returns True if the data was successfully loaded
      */
     loadZipDataBase64: (zipDataBase64: string) => boolean;
 
     /**
      * Load a MusicXML compressed file passed as a buffer of bytes.
+     * @param zipDataBuffer A ZIP file as a buffer of bytes
      * @returns True if the data was successfully loaded
      */
     loadZipDataBuffer: (zipDataBuffer: ArrayBuffer) => boolean;
@@ -179,8 +288,9 @@ export class toolkit {
      * Redo the layout of the loaded data.
      *
      * This can be called once the rendering option were changed, for example with a new page (sceen) height or a new zoom level.
+     * @param options A JSON object with the action options resetCache: true or false; true by default;
      */
-    redoLayout: () => void;
+    redoLayout: (options?: RedoLayoutOptions) => void;
 
     /**
      * Redo the layout of the pitch postitions of the current drawing page.
@@ -190,12 +300,20 @@ export class toolkit {
     redoPagePitchPosLayout: () => void;
 
     /**
-     * Loads and the data with the options passed as JSON object and renders the first page. This
-     * methods is a shortcut for loadData and then renderPage and is appropriate for rendering small
-     * data snippets. The data does stay in memory once loaded. Also, up to version 0.9.12, the JSON
-     * object had to be stringified.
+     * Render the first page of the data to SVG.
+     *
+     * This method is a wrapper for setting options, loading data and rendering the first page. It will return an empty string if the options cannot be set or the data cannot be loaded.
+     * @param data A string with the data (e.g., MEI data) to be loaded
+     * @param options A JSON object with the output options
+     * @returns The SVG first page as a string
+     */
+    renderData: (data: string, options: VerovioOptions) => string;
+
+    /**
+     * Render a document’s expansionMap, if existing.
+     * @returns The expansion map as a JSON object
      */
-    renderData: (meiData: string, options: VerovioOptions) => string;
+    renderToExpansionMap: () => ExpansionMap;
 
     /**
      * Render the document to MIDI.
@@ -204,33 +322,65 @@ export class toolkit {
     renderToMIDI: () => string;
 
     /**
-     * Render a document to Plaine and Easie.
+     * Render a document to Plaine and Easie code.
      *
      * Only the top staff / layer is exported.
      * @returns The PAE as a string
      */
     renderToPAE: () => string;
 
     /**
-     * Renders a page for the data loaded in the toolkit and returns it in SVG. The page numbering
-     * is 1-based.
+     * Render a page to SVG.
+     * @param pageNumber The page to render (1-based), default 1
+     * @param xmlDeclaration True for including the xml declaration in the SVG output, default false
      * @returns The SVG page as a string
      */
-    renderToSVG: (pageNumber: number) => string;
+    renderToSVG: (pageNumber?: number, xmlDeclaration?: boolean) => string;
 
     /**
      * Render a document to a timemap.
+     * @param options A stringified JSON objects with the timemap options
+     * @returns The timemap as a JSON object
      */
-    renderToTimemap: () => TimeMapEntry[];
+    renderToTimemap: (options?: TimeMapOptions) => TimeMapEntry[];
+
     /**
-     * Sets the options as JSON for the toolkit instance. Up to version 0.9.12, the JSON object had to be stringified.
+     * Reset all options to default values.
      */
-    setOptions: (options: VerovioOptions) => void;
+    resetOptions: () => void;
 
     /**
-     * Return a dictionary of all the options.
+     * Reset the seed used to generate MEI @xml:id attribute values.
      *
-     * @param defaultValues True for getting the default values and false for the current values
+     * Passing 0 will seed the @xml:id generator with a random (time-based) seed value. This method will have no effect if the xml-id-checksum option is set.
+     * @param seed The seed value for generating the @xml:id values (0 for a time-based random seed)
      */
-    getOptions: (defaultValues?: boolean) => VerovioOptions;
+    resetXmlIdSeed: (seed: number) => void;
+
+    /**
+     * Set the value for a selection.
+     *
+     * The selection will be applied only when some data is loaded or the layout is redone. The selection can be reset (cancelled) by passing an empty string or an empty JSON object. A selection across multiple mdivs is not possible.
+     * @param selection The selection as a stringified object
+     * @returns True if the selection was successfully parsed or reset
+     */
+    select: (selection: Selection) => boolean;
+
+    /**
+     * Set option values.
+     *
+     * The name of each option to be set is to be given as JSON key.
+     * @param options A JSON object with the output options
+     * @returns True if the options were successfully set
+     */
+    setOptions: (options: VerovioOptions) => boolean;
+
+    /**
+     * Validate the Plaine & Easie code passed in the string data.
+     *
+     * A single JSON object is returned when there is a global input error. When reading the input succeeds, validation is grouped by input keys. The methods always returns errors in PAE pedantic mode. No data remains loaded after the validation.
+     * @param data A string with the data in JSON or with PAE @ keys
+     * @returns A JSON object with the validation warnings or errors
+     */
+    validatePAE: (data: string | { [key: string]: string }) => PAEValidation;
 }

types/verovio/package.json

@@ -1,7 +1,7 @@
 {
     "private": true,
     "name": "@types/verovio",
-    "version": "5.0.9999",
+    "version": "5.1.9999",
     "exports": {
         ".": "./index.d.ts",
         "./esm": {