@kensio/pinyinjs 1.7.4 → 1.7.5

package/dist/dictionary/word-reading.js

@@ -0,0 +1,76 @@
+import { isSingleCharacter } from "../script/characters.js";
+import { isSameReading } from "./entry.js";
+import { readAlignedReading } from "./reading.js";
+import { repairErhua } from "./erhua-repair.js";
+import { NEUTRAL_SENSE_LOOKUP } from "./neutral-senses.js";
+import { OVERRIDE_READINGS } from "./overrides.js";
+import { nearestReading, preferNeutralTones, reducesToNeutral, } from "./reading-agreement.js";
+/**
+ * Settle it.
+ */
+export function settleReading(word, defaults, cedictEntries, cedictReadings, phraseAligned) {
+    let neutralToneCorrections = 0;
+    let erhuaRepairs = 0;
+    // ── The reading: phrase corpus leads, CC-CEDICT corrects ──
+    let aligned = phraseAligned;
+    let reading = aligned
+        ?.map((read) => read.syllable)
+        .filter((syllable) => syllable !== undefined);
+    if (reading === undefined) {
+        // No phrase entry. Single characters fall back to Unihan, which is the
+        // better source for them anyway; everything else falls back to
+        // CC-CEDICT.
+        const characterDefault = defaults.get(word);
+        if (isSingleCharacter(word) && characterDefault !== undefined) {
+            reading = characterDefault.slice(0, 1);
+            aligned = [{ characters: word, syllable: reading[0] }];
+        }
+        else if (cedictReadings[0] !== undefined) {
+            reading = cedictReadings[0];
+            aligned = readAlignedReading(word, cedictEntries[0]?.readings ?? []);
+        }
+    }
+    if (reading === undefined || reading.length === 0) {
+        return {
+            reading: undefined,
+            aligned: undefined,
+            neutralToneCorrections: 0,
+            erhuaRepairs: 0,
+        };
+    }
+    // ── 儿化, before anything compares two readings ────────────
+    const repaired = repairErhua(word, reading, aligned, cedictEntries, cedictReadings);
+    reading = repaired.reading;
+    aligned = repaired.aligned;
+    if (repaired.isRepaired) {
+        erhuaRepairs++;
+    }
+    // ── Disagreements: CC-CEDICT wins on neutral tones ────────
+    // Which sense to correct against is normally the nearest one. For a word on
+    // the 轻声 list it is the nearest sense that *reduces* a syllable, because
+    // there the nearest sense is the full-tone homograph the corpus happens to
+    // have written and the everyday word is the other one — see
+    // {@link NEUTRAL_SENSE_WORDS}.
+    const chosen = reading;
+    const nearest = phraseAligned === undefined
+        ? undefined
+        : ((NEUTRAL_SENSE_LOOKUP.has(word)
+            ? nearestReading(chosen, cedictReadings.filter((candidate) => reducesToNeutral(chosen, candidate)))
+            : undefined) ?? nearestReading(chosen, cedictReadings));
+    // A sense of a different length describes a different pronunciation, so
+    // there is no syllable-for-syllable correction to make against it.
+    if (nearest !== undefined) {
+        const corrected = preferNeutralTones(reading, nearest);
+        if (!isSameReading(corrected, reading)) {
+            neutralToneCorrections++;
+            reading = corrected;
+        }
+    }
+    // ── The override table has the last word ──────────────────
+    const override = OVERRIDE_READINGS.get(word);
+    if (override !== undefined) {
+        reading = override;
+    }
+    return { reading, aligned, neutralToneCorrections, erhuaRepairs };
+}
+//# sourceMappingURL=word-reading.js.map

package/dist/dictionary/word-reading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"word-reading.js","sourceRoot":"","sources":["../../src/dictionary/word-reading.ts"],"names":[],"mappings":"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"}

package/dist/dictionary/word-readings.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The words whose reading a build must reproduce.
+ *
+ * Each stands for a class of upstream defect a source refresh could
+ * reintroduce — a 儿化 repair, a sandhi normalisation, a polyphone the corpus
+ * would otherwise flatten — so a failure means the merge stopped doing
+ * something it used to, not that one word is wrong.
+ */
+import type { BuildAssertion } from "./built-dictionary.js";
+/**
+ * Assert one word reads a particular way.
+ */
+export declare function reads(word: string, expected: string, why: string): BuildAssertion;
+export declare const WORD_READINGS: readonly BuildAssertion[];
+//# sourceMappingURL=word-readings.d.ts.map

package/dist/dictionary/word-readings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"word-readings.d.ts","sourceRoot":"","sources":["../../src/dictionary/word-readings.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,uBAAuB,CAAC;AAE7E;;GAEG;AACH,wBAAgB,KAAK,CACnB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,cAAc,CAahB;AAED,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EAmBlD,CAAC"}

package/dist/dictionary/word-readings.js

@@ -0,0 +1,38 @@
+/**
+ * Assert one word reads a particular way.
+ */
+export function reads(word, expected, why) {
+    return {
+        description: `${word} → ${expected} (${why})`,
+        check: (dictionary) => {
+            const actual = dictionary.reading(word);
+            if (actual === undefined) {
+                return `${word} is missing from the dictionary`;
+            }
+            return actual === expected
+                ? undefined
+                : `${word} reads ${actual}, expected ${expected}`;
+        },
+    };
+}
+export const WORD_READINGS = [
+    reads("玩儿", "wánr", "儿化 repaired from CC-CEDICT's r5"),
+    reads("女儿", "nǚ ér", "儿 keeps its own syllable here"),
+    reads("这儿", "zhèr", "儿化 despite upstream writing a tone on the er"),
+    reads("儿子", "ér zi", "儿化 exception list consulted"),
+    reads("一丁不识", "yī dīng bù shí", "一 sandhi normalised out"),
+    reads("一不小心", "yī bù xiǎo xīn", "一 and 不 sandhi normalised out"),
+    reads("大夫", "dài fu", "override applied over both sources"),
+    reads("东西", "dōng xi", "the thing, not the compass directions"),
+    reads("东西方", "dōng xī fāng", "and the directions where that is the word"),
+    reads("告诉", "gào su", "the everyday verb, not filing a complaint"),
+    reads("银行", "yín háng", "polyphone survives"),
+    reads("行长", "háng zhǎng", "polyphone survives"),
+    reads("头发", "tóu fa", "CC-CEDICT wins on the neutral tone"),
+    reads("还是", "hái shi", "CC-CEDICT wins on the neutral tone"),
+    reads("頭髮", "tóu fa", "繁體 derived using the reading, and keyed directly"),
+    reads("重複", "chóng fù", "one of two 繁體 spellings, both keyed"),
+    reads("重覆", "chóng fù", "the other, on the same entry"),
+    reads("下麵", "xià miàn", "both spellings of a word CC-CEDICT writes twice"),
+];
+//# sourceMappingURL=word-readings.js.map

package/dist/dictionary/word-readings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"word-readings.js","sourceRoot":"","sources":["../../src/dictionary/word-readings.ts"],"names":[],"mappings":"AAUA;;GAEG;AACH,MAAM,UAAU,KAAK,CACnB,IAAY,EACZ,QAAgB,EAChB,GAAW;IAEX,OAAO;QACL,WAAW,EAAE,GAAG,IAAI,MAAM,QAAQ,KAAK,GAAG,GAAG;QAC7C,KAAK,EAAE,CAAC,UAA2B,EAAsB,EAAE;YACzD,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACxC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,OAAO,GAAG,IAAI,iCAAiC,CAAC;YAClD,CAAC;YACD,OAAO,MAAM,KAAK,QAAQ;gBACxB,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,GAAG,IAAI,UAAU,MAAM,cAAc,QAAQ,EAAE,CAAC;QACtD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAA8B;IACtD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,iCAAiC,CAAC;IACtD,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,+BAA+B,CAAC;IACrD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,8CAA8C,CAAC;IACnE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,6BAA6B,CAAC;IACnD,KAAK,CAAC,MAAM,EAAE,gBAAgB,EAAE,yBAAyB,CAAC;IAC1D,KAAK,CAAC,MAAM,EAAE,gBAAgB,EAAE,+BAA+B,CAAC;IAChE,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,oCAAoC,CAAC;IAC3D,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,uCAAuC,CAAC;IAC/D,KAAK,CAAC,KAAK,EAAE,cAAc,EAAE,2CAA2C,CAAC;IACzE,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,2CAA2C,CAAC;IAClE,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,oBAAoB,CAAC;IAC7C,KAAK,CAAC,IAAI,EAAE,YAAY,EAAE,oBAAoB,CAAC;IAC/C,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,oCAAoC,CAAC;IAC3D,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,oCAAoC,CAAC;IAC5D,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,kDAAkD,CAAC;IACzE,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,qCAAqC,CAAC;IAC9D,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,8BAA8B,CAAC;IACvD,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,iDAAiD,CAAC;CAC3E,CAAC"}

package/dist/format/annotate.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Writing a conversion as ruby annotation.
+ *
+ * The pinyin sits above the characters rather than beside them, so the pieces
+ * are regrouped against the text they annotate.
+ */
+import { type HtmlOptions } from "./html.js";
+import { type ConvertedPiece } from "../decode/convert.js";
+import type { Dictionary } from "../dictionary/dictionary.js";
+/**
+ * What the characters being annotated declare themselves to be.
+ *
+ * The mirror of {@link languageTag}: inside an annotation the base is hanzi and
+ * only the reading is pinyin, so on an English page the two need different tags
+ * and neither can be left to inherit.
+ *
+ * **`zh`, with no script subtag, and that is deliberate.** `Hans` or `Hant`
+ * would be better for font selection, and neither can be known here. The
+ * conversion's locale does not settle it — script and locale are separate axes,
+ * and a mainland edition of a classical text is 繁體 read as `zh-CN` — and
+ * detecting it from the characters needs the script tables, which load
+ * separately from the dictionary precisely so that converting does not pay for
+ * them. A tag that is merely unspecific is worth more than one that is wrong,
+ * so a caller who knows the script should wrap the output and say so there.
+ */
+export declare const BASE_TAG = "zh";
+/**
+ * One base and everything read off it.
+ */
+export interface Annotation {
+    /** The characters, or undefined for text that reads as nothing. */
+    readonly source: string | undefined;
+    readonly pieces: readonly ConvertedPiece[];
+}
+/**
+ * Gather pieces into the bases they are readings of.
+ *
+ * A piece naming characters opens a group and every piece after it that names
+ * none reads on into the same one, which is how 玩儿 keeps `wánr` over both
+ * characters and 95% keeps `bǎifēnzhījiǔshíwǔ` over all three. Pieces writing
+ * no reading at all — the spaces between words, and runs that were never Han —
+ * are their own groups, with nothing to annotate.
+ */
+export declare function annotationsOf(pieces: readonly ConvertedPiece[]): Annotation[];
+/**
+ * Mark up a converted text as hanzi with its reading above, syllable by
+ * syllable.
+ *
+ * The output every other mode cannot give: `convert` and {@link toHtml} write
+ * the pinyin *instead of* the hanzi, and a learner's text, a subtitle and a
+ * dictionary entry all want both at once. The markup is `<ruby>`, which every
+ * current browser lays out natively and which degrades to parentheses through
+ * `<rp>` where it is not supported.
+ *
+ * ```html
+ * <ruby lang="zh">银<rp>(</rp><rt><span …>yín</span></rt><rp>)</rp></ruby>
+ * ```
+ *
+ * Each `<rt>` holds whatever {@link toHtml} would have written for those
+ * syllables, so tone classes and uncertainty marking work inside an annotation
+ * exactly as they do outside one.
+ *
+ * **A base is not always one character.** 玩儿 is two characters and the one
+ * syllable `wánr`, and a read number reverses on the way — 95% is
+ * `bǎifēnzhījiǔshíwǔ` — so both are annotated whole. Splitting them per
+ * character is what everything that emits ruby from a pinyin library gets
+ * wrong, and it is why {@link ConvertedPiece.source} exists.
+ */
+export declare function toAnnotatedHtml(pieces: readonly ConvertedPiece[], options?: HtmlOptions): string;
+/**
+ * Convert hanzi to pinyin as HTML, hanzi and reading together.
+ *
+ * {@link toAnnotatedHtml} applied to a fresh conversion; see it for what the
+ * markup is and why a base is not always one character.
+ */
+export declare function convertToAnnotatedHtml(dictionary: Dictionary, text: string, options?: HtmlOptions): string;
+/**
+ * Convert hanzi to pinyin as HTML, one element per syllable.
+ *
+ * What per-syllable confidence is for, and the reason ALGORITHM.md asks for it:
+ * a reading the decode was guessing at can be *shown* to be a guess, which for
+ * a learner is a feature rather than a diagnostic. No styling is imposed — the
+ * classes are hooks, and the page decides whether a fourth tone is red and an
+ * uncertain reading is dotted underneath.
+ *
+ * Nothing is wrapped around the whole conversion, and anything that is not Han
+ * passes through escaped rather than marked up.
+ */
+export declare function convertToHtml(dictionary: Dictionary, text: string, options?: HtmlOptions): string;
+//# sourceMappingURL=annotate.d.ts.map

package/dist/format/annotate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotate.d.ts","sourceRoot":"","sources":["../../src/format/annotate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAU,KAAK,WAAW,EAAsB,MAAM,WAAW,CAAC;AACzE,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,QAAQ,OAAO,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,UAAU,EAAE,CAc7E;AA2ED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,GAAE,WAAgB,GACxB,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GACxB,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GACxB,MAAM,CAER"}

package/dist/format/annotate.js

@@ -0,0 +1,168 @@
+/**
+ * Writing a conversion as ruby annotation.
+ *
+ * The pinyin sits above the characters rather than beside them, so the pieces
+ * are regrouped against the text they annotate.
+ */
+import { escape, toHtml, writePiece } from "./html.js";
+import { convertPieces } from "../decode/convert.js";
+/**
+ * What the characters being annotated declare themselves to be.
+ *
+ * The mirror of {@link languageTag}: inside an annotation the base is hanzi and
+ * only the reading is pinyin, so on an English page the two need different tags
+ * and neither can be left to inherit.
+ *
+ * **`zh`, with no script subtag, and that is deliberate.** `Hans` or `Hant`
+ * would be better for font selection, and neither can be known here. The
+ * conversion's locale does not settle it — script and locale are separate axes,
+ * and a mainland edition of a classical text is 繁體 read as `zh-CN` — and
+ * detecting it from the characters needs the script tables, which load
+ * separately from the dictionary precisely so that converting does not pay for
+ * them. A tag that is merely unspecific is worth more than one that is wrong,
+ * so a caller who knows the script should wrap the output and say so there.
+ */
+export const BASE_TAG = "zh";
+/**
+ * Gather pieces into the bases they are readings of.
+ *
+ * A piece naming characters opens a group and every piece after it that names
+ * none reads on into the same one, which is how 玩儿 keeps `wánr` over both
+ * characters and 95% keeps `bǎifēnzhījiǔshíwǔ` over all three. Pieces writing
+ * no reading at all — the spaces between words, and runs that were never Han —
+ * are their own groups, with nothing to annotate.
+ */
+export function annotationsOf(pieces) {
+    const groups = [];
+    for (const [at, piece] of pieces.entries()) {
+        const open = groups.at(-1);
+        if (open?.source !== undefined && continues(piece, pieces[at + 1])) {
+            groups[groups.length - 1] = {
+                source: open.source,
+                pieces: [...open.pieces, piece],
+            };
+            continue;
+        }
+        groups.push({ source: piece.source, pieces: [piece] });
+    }
+    return groups;
+}
+/**
+ * Whether a piece belongs to the annotation the group before it opened.
+ *
+ * Three kinds do:
+ *
+ * - A **syllable naming no characters** is reading on into the ones already
+ *   named, which is 儿化 and every syllable of a read number after the first.
+ * - A **separator that is not a space** is a mark *inside* one orthographic
+ *   word rather than a gap between two — the hyphen of `gāngān-jìngjìng`, the
+ *   only one GB/T 16159 writes — so it belongs beside the syllables it divides.
+ * - A **space with more of the same reading after it**. 1988 is read
+ *   `yī jiǔ bā bā`, four syllables over one base, and the spaces between them
+ *   are inside that reading rather than between two of them.
+ *
+ * That last one is why this needs the piece after it. A space is written the
+ * same way whether it separates two words or two syllables of one number, and
+ * what tells them apart is whether what follows is still reading the same
+ * characters. Told apart wrongly, the reading escapes its own annotation:
+ * 1988年 came out as `1988` over `yī` with `jiǔ bā bā` loose beside it.
+ *
+ * A space between two words is the case that does not continue, and dropping it
+ * is the point: the hanzi it annotates has no space in it, and each base is
+ * already its own group on the page.
+ */
+function continues(piece, next) {
+    if (piece.syllable !== undefined) {
+        return piece.source === undefined;
+    }
+    if (piece.source !== undefined) {
+        return false;
+    }
+    return (piece.text.trim() !== "" ||
+        (next?.syllable !== undefined && next.source === undefined));
+}
+/**
+ * Mark up one base and its reading.
+ */
+function writeAnnotation(annotation, options) {
+    const { lang = true } = options;
+    const { source, pieces } = annotation;
+    if (pieces.every((piece) => piece.syllable === undefined)) {
+        // Nothing is read here. Either it is source text that simply has no
+        // reading — punctuation, a Latin word — and is written as the author wrote
+        // it, or it is pinyin orthography with no source behind it at all: the
+        // space between two words, and the hyphen in `gāngān-jìngjìng`. Writing
+        // those into the hanzi would annotate 干干净净 as 干干-净净.
+        return source === undefined ? "" : escape(source);
+    }
+    if (source === undefined) {
+        // A reading whose piece never named what it reads. Nothing a conversion
+        // builds looks like this — every group is opened by a piece carrying its
+        // characters — but {@link toAnnotatedHtml} takes pieces from the caller,
+        // and there is no base to hang an annotation on, so it is written as the
+        // plain markup it would have got from {@link toHtml}.
+        return pieces.map((piece) => writePiece(piece, options)).join("");
+    }
+    const reading = pieces.map((piece) => writePiece(piece, options)).join("");
+    // The tag goes on the <ruby> rather than around the base, and the syllables
+    // inside the <rt> override it with their own. `<rb>` would be the obvious
+    // place for it and is not an element any more: the WHATWG parser drops it,
+    // leaving the base as bare text, so writing one would mean emitting markup
+    // that no browser keeps.
+    const opening = lang ? `<ruby lang="${BASE_TAG}">` : "<ruby>";
+    return `${opening}${escape(source)}<rp>(</rp><rt>${reading}</rt><rp>)</rp></ruby>`;
+}
+/**
+ * Mark up a converted text as hanzi with its reading above, syllable by
+ * syllable.
+ *
+ * The output every other mode cannot give: `convert` and {@link toHtml} write
+ * the pinyin *instead of* the hanzi, and a learner's text, a subtitle and a
+ * dictionary entry all want both at once. The markup is `<ruby>`, which every
+ * current browser lays out natively and which degrades to parentheses through
+ * `<rp>` where it is not supported.
+ *
+ * ```html
+ * <ruby lang="zh">银<rp>(</rp><rt><span …>yín</span></rt><rp>)</rp></ruby>
+ * ```
+ *
+ * Each `<rt>` holds whatever {@link toHtml} would have written for those
+ * syllables, so tone classes and uncertainty marking work inside an annotation
+ * exactly as they do outside one.
+ *
+ * **A base is not always one character.** 玩儿 is two characters and the one
+ * syllable `wánr`, and a read number reverses on the way — 95% is
+ * `bǎifēnzhījiǔshíwǔ` — so both are annotated whole. Splitting them per
+ * character is what everything that emits ruby from a pinyin library gets
+ * wrong, and it is why {@link ConvertedPiece.source} exists.
+ */
+export function toAnnotatedHtml(pieces, options = {}) {
+    return annotationsOf(pieces)
+        .map((annotation) => writeAnnotation(annotation, options))
+        .join("");
+}
+/**
+ * Convert hanzi to pinyin as HTML, hanzi and reading together.
+ *
+ * {@link toAnnotatedHtml} applied to a fresh conversion; see it for what the
+ * markup is and why a base is not always one character.
+ */
+export function convertToAnnotatedHtml(dictionary, text, options = {}) {
+    return toAnnotatedHtml(convertPieces(dictionary, text, options), options);
+}
+/**
+ * Convert hanzi to pinyin as HTML, one element per syllable.
+ *
+ * What per-syllable confidence is for, and the reason ALGORITHM.md asks for it:
+ * a reading the decode was guessing at can be *shown* to be a guess, which for
+ * a learner is a feature rather than a diagnostic. No styling is imposed — the
+ * classes are hooks, and the page decides whether a fourth tone is red and an
+ * uncertain reading is dotted underneath.
+ *
+ * Nothing is wrapped around the whole conversion, and anything that is not Han
+ * passes through escaped rather than marked up.
+ */
+export function convertToHtml(dictionary, text, options = {}) {
+    return toHtml(convertPieces(dictionary, text, options), options);
+}
+//# sourceMappingURL=annotate.js.map

package/dist/format/annotate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotate.js","sourceRoot":"","sources":["../../src/format/annotate.ts"],"names":[],"mappings":"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"}

package/dist/format/html.d.ts

@@ -1,5 +1,5 @@
-import { type ConvertedPiece, type ConvertOptions } from "../decode/convert.js";
-import type { Dictionary } from "../dictionary/dictionary.js";
+export { convertToAnnotatedHtml, convertToHtml, toAnnotatedHtml, } from "./annotate.js";
+import type { ConvertedPiece, ConvertOptions } from "../decode/convert.js";
 /**
  * How a conversion is marked up.
  */
@@ -29,55 +29,24 @@ export interface HtmlOptions extends ConvertOptions {
     readonly lang?: boolean;
 }
 /**
- * Mark up a converted text, one element per syllable.
- *
- * Takes the pieces {@link convertPieces} produces, so that a caller can convert
- * once and render more than one way.
- */
-export declare function toHtml(pieces: readonly ConvertedPiece[], options?: HtmlOptions): string;
-/**
- * Mark up a converted text as hanzi with its reading above, syllable by
- * syllable.
- *
- * The output every other mode cannot give: `convert` and {@link toHtml} write
- * the pinyin *instead of* the hanzi, and a learner's text, a subtitle and a
- * dictionary entry all want both at once. The markup is `<ruby>`, which every
- * current browser lays out natively and which degrades to parentheses through
- * `<rp>` where it is not supported.
+ * Escape text for markup.
  *
- * ```html
- * <ruby lang="zh">银<rp>(</rp><rt><span …>yín</span></rt><rp>)</rp></ruby>
- * ```
- *
- * Each `<rt>` holds whatever {@link toHtml} would have written for those
- * syllables, so tone classes and uncertainty marking work inside an annotation
- * exactly as they do outside one.
- *
- * **A base is not always one character.** 玩儿 is two characters and the one
- * syllable `wánr`, and a read number reverses on the way — 95% is
- * `bǎifēnzhījiǔshíwǔ` — so both are annotated whole. Splitting them per
- * character is what everything that emits ruby from a pinyin library gets
- * wrong, and it is why {@link ConvertedPiece.source} exists.
+ * Applied to everything, including the source's own text: a conversion passes
+ * anything that is not Han through untouched, so `<script>` in the input
+ * reaches the output as written. The apostrophe is deliberately not escaped:
+ * every attribute here is double-quoted, and the 隔音符号 of `Xī'ān` is a
+ * letter of the orthography that a reader should see as one.
  */
-export declare function toAnnotatedHtml(pieces: readonly ConvertedPiece[], options?: HtmlOptions): string;
+export declare function escape(text: string): string;
 /**
- * Convert hanzi to pinyin as HTML, hanzi and reading together.
- *
- * {@link toAnnotatedHtml} applied to a fresh conversion; see it for what the
- * markup is and why a base is not always one character.
+ * Mark up one piece of a conversion.
  */
-export declare function convertToAnnotatedHtml(dictionary: Dictionary, text: string, options?: HtmlOptions): string;
+export declare function writePiece(piece: ConvertedPiece, options: HtmlOptions): string;
 /**
- * Convert hanzi to pinyin as HTML, one element per syllable.
- *
- * What per-syllable confidence is for, and the reason ALGORITHM.md asks for it:
- * a reading the decode was guessing at can be *shown* to be a guess, which for
- * a learner is a feature rather than a diagnostic. No styling is imposed — the
- * classes are hooks, and the page decides whether a fourth tone is red and an
- * uncertain reading is dotted underneath.
+ * Mark up a converted text, one element per syllable.
  *
- * Nothing is wrapped around the whole conversion, and anything that is not Han
- * passes through escaped rather than marked up.
+ * Takes the pieces {@link convertPieces} produces, so that a caller can convert
+ * once and render more than one way.
  */
-export declare function convertToHtml(dictionary: Dictionary, text: string, options?: HtmlOptions): string;
+export declare function toHtml(pieces: readonly ConvertedPiece[], options?: HtmlOptions): string;
 //# sourceMappingURL=html.d.ts.map

package/dist/format/html.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/format/html.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAI9D;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AA+HD;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,GAAE,WAAgB,GACxB,MAAM,CAER;AA+HD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,GAAE,WAAgB,GACxB,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GACxB,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GACxB,MAAM,CAER"}
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/format/html.ts"],"names":[],"mappings":"AACA,OAAO,EACL,sBAAsB,EACtB,aAAa,EACb,eAAe,GAChB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3E;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAwDD;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK3C;AAwBD;;GAEG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,WAAW,GACnB,MAAM,CA4BR;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,GAAE,WAAgB,GACxB,MAAM,CAER"}