@furifont/core 0.1.0 → 0.1.2

package/dist/index.d.mts

@@ -0,0 +1,351 @@
+import * as v from "valibot";
+//#region src/defaults.d.ts
+/**
+ * Every default of a build, and how the prebuilt fonts are built, in one place.
+ * Config files, the CLI, the studio and `scripts/build-fonts.ts` all read it, so
+ * a change here reaches them together. What an option means is in `schema.ts`.
+ */
+export declare const DEFAULTS: {
+  /** What a plan does when a config leaves an option out. */
+  readonly plan: {
+    readonly family: "Furifont Sans";
+    readonly rubyScript: "hiragana";
+    /** Newspaper frequency buckets, nf01 to nf48: the window of words that get ruby. All of them: it adds about 400 glyphs. */
+    readonly nfMin: 1;
+    readonly nfMax: 48;
+    /** JMdict priority tags that select a word whatever its bucket: the first tier of each list, which JMdict marks as common. */
+    readonly selectTags: readonly ["ichi1", "news1", "spec1", "gai1"];
+    readonly places: true;
+    readonly isolated: true;
+    readonly isolatedMinShare: 0.8;
+    /** Sizes in em, relative to the base font. */
+    readonly metrics: {
+      readonly rubyScale: 0.5;
+      readonly rubyGap: 0.05;
+      readonly compressionFloor: 0.8;
+      readonly maxRubyWidth: 1.6;
+    };
+  };
+  /** What the CLI adds to a plan: where the glyphs are drawn, and what is written. */
+  readonly build: {
+    readonly base: "Source Han Sans JP VF";
+    readonly formats: readonly ["otf", "woff2"];
+  };
+};
+/** The prebuilt fonts, which each release carries; the site serves their variable WOFF2s. */
+export declare const PREBUILT: {
+  /** Each Source Han face in each ruby script. The first is the default family. */
+  readonly fonts: readonly [{
+    readonly family: "Furifont Sans";
+    readonly base: "Source Han Sans JP";
+    readonly face: "sans";
+    readonly rubyScript: "hiragana";
+  }, {
+    readonly family: "Furifont Sans Romaji";
+    readonly base: "Source Han Sans JP";
+    readonly face: "sans";
+    readonly rubyScript: "hepburn";
+  }, {
+    readonly family: "Furifont Serif";
+    readonly base: "Source Han Serif JP";
+    readonly face: "serif";
+    readonly rubyScript: "hiragana";
+  }, {
+    readonly family: "Furifont Serif Romaji";
+    readonly base: "Source Han Serif JP";
+    readonly face: "serif";
+    readonly rubyScript: "hepburn";
+  }];
+  /** The static weights of the release, each of the base's weights by name. Bold is the variable font's. */
+  readonly weights: readonly [{
+    readonly style: "Regular";
+    readonly weight: 400;
+  }];
+  /**
+   * Every weight in one font, from the base's variable font (`<base> VF`). It
+   * is named apart, `<family> VF`, so it installs beside the static weights.
+   */
+  readonly variable: {
+    readonly style: "VF";
+    readonly weights: readonly [250, 900];
+  };
+  /** Options set on every prebuilt font over the defaults above, such as `{ nfMax: 24 }`. */
+  readonly options: {};
+};
+/**
+ * The sequence, 。 and VS1, a page measures to tell which version of Furifont
+ * it has: the font maps it to an empty glyph two ems wide plus the revision in
+ * ems (`0.1.2`, revision 0.102, is 2.102 ems). A font from before it draws the
+ * 。 alone, an em wide at most.
+ */
+export declare const VERSION_PROBE: {
+  readonly base: 12290;
+  readonly selector: 65024;
+};
+//#endregion
+//#region src/dictionary.d.ts
+/** One (written form, reading) pair, as compiled by `@furifont/dictionary`. */
+interface DictionaryEntry {
+  form: string;
+  /** JmdictFurigana alignment: `0:に;1:ほん`, or `0-1:きょう` for a reading spanning characters. */
+  furigana: string;
+  /** The form's newspaper frequency bucket (nf01..nf48), 0 when unranked. */
+  nf: number;
+  /** The reading's JMdict priority tags, space separated; empty for uncommon readings. */
+  priority: string;
+  /** Position of the reading among the form's readings, in JMdict order. */
+  order: number;
+  /** `来る`-type verb, whose kanji reads differently as it conjugates. */
+  conjugatesReading?: boolean;
+  /** The JLPT level whose word list has this pair: 5 for N5 down to 1 for N1. */
+  jlpt?: number;
+}
+interface Dictionary {
+  entries: DictionaryEntry[];
+  /** Kanji to its on'yomi, in hiragana. */
+  onyomi: Record<string, string[]>;
+  /** Source datasets and the version each was compiled from. */
+  sources: Record<string, string>;
+  /** Written forms never to annotate, such as 月, whose reading alone is a guess; users' removals add to them. */
+  bare?: string[];
+  /** Curated default readings in inline notation, for words the data ranks wrong; pins override them. */
+  defaults?: string[];
+  /** Place names, each with the one reading to show; common words take precedence over them. */
+  places?: {
+    form: string;
+    furigana: string;
+  }[];
+}
+/** A ruby annotation over characters `[start, end)` of a run. */
+interface RubySpan {
+  start: number;
+  end: number;
+  ruby: string;
+}
+/** A maximal sequence of Han characters with its reading, the unit a shaper sees. */
+interface HanRun {
+  text: string;
+  spans: RubySpan[];
+}
+export declare function isHan(char: string): boolean;
+export declare function parseFurigana(furigana: string): RubySpan[];
+/**
+ * Splits a form into its Han runs. Browsers itemize text by script before
+ * shaping, so a font only ever sees one run at a time: okurigana and other
+ * kana are never visible as context. Runs with an unannotated kanji or an
+ * annotation leaking outside the run are dropped.
+ */
+export declare function hanRuns(form: string, spans: readonly RubySpan[]): HanRun[];
+/**
+ * Parses the inline notation for custom words: `日[に]本[ほん]` for one reading
+ * per kanji, `今日[きょう]` for a reading over several kanji, kana as written.
+ */
+export declare function parseNotation(notation: string): {
+  form: string;
+  spans: RubySpan[];
+};
+export declare function formatNotation(text: string, spans: readonly RubySpan[]): string;
+//#endregion
+//#region src/schema.d.ts
+export declare const RUBY_SCRIPTS: readonly ["hiragana", "katakanaOn", "hepburn"];
+export declare const PRIORITY_TAGS: readonly ["ichi1", "ichi2", "news1", "news2", "spec1", "spec2", "gai1", "gai2"];
+/** Easiest first. */
+export declare const JLPT_LEVELS: readonly ["N5", "N4", "N3", "N2", "N1"];
+type RubyScript = typeof RUBY_SCRIPTS[number];
+/** Sizes in em, relative to the base font. */
+declare const RubyMetricsSchema: v.ObjectSchema<{
+  /** Ruby size relative to the base characters. */
+  readonly rubyScale: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0.2, undefined>, v.MaxValueAction<number, 0.8, undefined>]>, 0.5>;
+  /** Space between the top of the em box and the bottom of the ruby. */
+  readonly rubyGap: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 0.5, undefined>]>, 0.05>;
+  /** Ruby is squeezed horizontally down to this scale before it may overhang. */
+  readonly compressionFloor: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0.3, undefined>, v.MaxValueAction<number, 1, undefined>]>, 0.8>;
+  /** Widest a ruby may get, overhanging its base symmetrically. */
+  readonly maxRubyWidth: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 3, undefined>]>, 1.6>;
+}, undefined>;
+type RubyMetrics = v.InferOutput<typeof RubyMetricsSchema>;
+/** `schema`, checking that its frequency window `nfMin..nfMax` holds a bucket; for schemas that extend the options too. */
+export declare function withNfWindow<T extends v.GenericSchema<unknown, {
+  nfMin: number;
+  nfMax: number;
+}>>(schema: T): v.SchemaWithPipe<readonly [T, v.CheckAction<v.InferOutput<T>, string>]>;
+export declare const PlanOptionsSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
+  readonly family: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.NonEmptyAction<string, undefined>, v.CheckAction<string, "Source is a reserved font name of the base font">]>, "Furifont Sans">;
+  readonly rubyScript: v.OptionalSchema<v.PicklistSchema<readonly ["hiragana", "katakanaOn", "hepburn"], undefined>, "hiragana">;
+  /**
+   * Words whose newspaper frequency bucket is below this stay bare: the most
+   * common ones, which a reader knows. Tags don't bring them back.
+   */
+  readonly nfMin: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 48, undefined>]>, 1>;
+  /** Words whose newspaper frequency bucket is at most this are annotated. */
+  readonly nfMax: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 48, undefined>]>, 48>;
+  /**
+   * JMdict priority tags that select a word whatever its frequency bucket:
+   * `spec1` catches words like 日本 that the newspaper ranking misses.
+   */
+  readonly selectTags: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<readonly ["ichi1", "ichi2", "news1", "news2", "spec1", "spec2", "gai1", "gai2"], undefined>, undefined>, () => ("ichi1" | "news1" | "spec1" | "gai1")[]>;
+  /** Words on the JLPT lists of this level and every easier one stay bare. */
+  readonly skipJlpt: v.OptionalSchema<v.PicklistSchema<readonly ["N5", "N4", "N3", "N2", "N1"], undefined>, undefined>;
+  /** Annotate place names from the dictionary where no common word claims the run. */
+  readonly places: v.OptionalSchema<v.BooleanSchema<undefined>, true>;
+  /** Annotate a kanji alone in its run; when off, only selectors give it ruby. */
+  readonly isolated: v.OptionalSchema<v.BooleanSchema<undefined>, true>;
+  /** A kanji alone in its run is annotated only when one reading has this share of the evidence. */
+  readonly isolatedMinShare: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0.5, undefined>, v.MaxValueAction<number, 1, undefined>]>, 0.8>;
+  readonly words: v.OptionalSchema<v.ObjectSchema<{
+    /** Extra words in inline notation, `日[に]本[ほん]`. */
+    readonly add: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, readonly []>;
+    /** Written forms never to annotate. */
+    readonly remove: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, readonly []>;
+    /** Readings to make the default, in inline notation. */
+    readonly pin: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, readonly []>;
+  }, undefined>, {}>;
+  readonly metrics: v.OptionalSchema<v.ObjectSchema<{
+    /** Ruby size relative to the base characters. */
+    readonly rubyScale: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0.2, undefined>, v.MaxValueAction<number, 0.8, undefined>]>, 0.5>;
+    /** Space between the top of the em box and the bottom of the ruby. */
+    readonly rubyGap: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 0.5, undefined>]>, 0.05>;
+    /** Ruby is squeezed horizontally down to this scale before it may overhang. */
+    readonly compressionFloor: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0.3, undefined>, v.MaxValueAction<number, 1, undefined>]>, 0.8>;
+    /** Widest a ruby may get, overhanging its base symmetrically. */
+    readonly maxRubyWidth: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 3, undefined>]>, 1.6>;
+  }, undefined>, {}>;
+}, undefined>, v.CheckAction<{
+  family: string;
+  rubyScript: "hiragana" | "hepburn" | "katakanaOn";
+  nfMin: number;
+  nfMax: number;
+  selectTags: ("ichi1" | "news1" | "spec1" | "gai1" | "ichi2" | "news2" | "spec2" | "gai2")[];
+  skipJlpt?: "N5" | "N4" | "N3" | "N2" | "N1" | undefined;
+  places: boolean;
+  isolated: boolean;
+  isolatedMinShare: number;
+  words: {
+    add: string[];
+    remove: string[];
+    pin: string[];
+  };
+  metrics: {
+    rubyScale: number;
+    rubyGap: number;
+    compressionFloor: number;
+    maxRubyWidth: number;
+  };
+}, string>]>;
+type PlanOptions = v.InferOutput<typeof PlanOptionsSchema>;
+type PlanOptionsInput = v.InferInput<typeof PlanOptionsSchema>;
+export declare function resolveOptions(input?: PlanOptionsInput): PlanOptions;
+/**
+ * The contract between the planner and the compiler. The compiler makes no
+ * decision about readings: it draws what `glyphs` describes and compiles `fea`.
+ * In `fea`, base characters are named `uniXXXX` / `uXXXXX` after their codepoint.
+ */
+export declare const PlanSchema: v.ObjectSchema<{
+  readonly version: v.LiteralSchema<1, undefined>;
+  readonly names: v.ObjectSchema<{
+    readonly family: v.StringSchema<undefined>;
+    readonly description: v.StringSchema<undefined>;
+  }, undefined>;
+  readonly metrics: v.ObjectSchema<{
+    readonly rubyScale: v.NumberSchema<undefined>;
+    readonly rubyGap: v.NumberSchema<undefined>;
+    readonly compressionFloor: v.NumberSchema<undefined>;
+    readonly maxRubyWidth: v.NumberSchema<undefined>;
+  }, undefined>;
+  /** Base characters the rules name; each must be in the base font's cmap. */
+  readonly codepoints: v.ArraySchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1114111, undefined>]>, undefined>;
+  /**
+   * Base + variation selector sequences to map in `cmap` format 14, each to an
+   * empty glyph named `name`, with the base's advance: the rules replace it.
+   */
+  readonly variants: v.ArraySchema<v.ObjectSchema<{
+    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
+    readonly base: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1114111, undefined>]>;
+    readonly selector: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1114111, undefined>]>;
+  }, undefined>, undefined>;
+  readonly glyphs: v.ArraySchema<v.ObjectSchema<{
+    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
+    /** The base characters drawn side by side; more than one makes a ligature. */
+    readonly bases: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1114111, undefined>]>, undefined>, v.MinLengthAction<number[], 1, undefined>]>;
+    /** Ruby text drawn above characters `[start, end)` of `bases`. */
+    readonly ruby: v.ArraySchema<v.ObjectSchema<{
+      readonly start: v.NumberSchema<undefined>;
+      readonly end: v.NumberSchema<undefined>;
+      readonly text: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, undefined>]>;
+    }, undefined>, undefined>;
+  }, undefined>, undefined>;
+  readonly fea: v.StringSchema<undefined>;
+  /** Subset the base font to these codepoints before building (live previews). */
+  readonly subset: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1114111, undefined>]>, undefined>, undefined>;
+  /** Shaping checks the compiler runs on its output: `text` must shape to `glyphs`. */
+  readonly smoke: v.ArraySchema<v.ObjectSchema<{
+    readonly text: v.StringSchema<undefined>;
+    readonly glyphs: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+  }, undefined>, undefined>;
+}, undefined>;
+type Plan = v.InferOutput<typeof PlanSchema>;
+type PlanGlyph = Plan['glyphs'][number];
+//#endregion
+//#region src/glyphs.d.ts
+export declare function glyphName(codepoint: number): string;
+//#endregion
+//#region src/kana.d.ts
+export declare function toKatakana(hiragana: string): string;
+export declare function toHiragana(katakana: string): string;
+/**
+ * Whether `reading` is one of the kanji's on'yomi as it surfaces inside a word:
+ * as listed, with its first kana voiced (rendaku), or with a final く/き/ち/つ
+ * turned into っ (sokuon), e.g. 学 ガク surfacing as がっ in 学校.
+ */
+export declare function isOnyomi(reading: string, onyomi: readonly string[]): boolean;
+/**
+ * Modified Hepburn with macrons (きょう → kyō, おおきい → ōkii). `following` is
+ * the kana written after this one in the word, so a trailing っ can double
+ * the next consonant (学 がっ before こう → gak).
+ */
+export declare function toHepburn(kana: string, following?: string): string;
+//#endregion
+//#region src/planner.d.ts
+/** VS225: shows the kanji before it without ruby. */
+export declare const SELECTOR_SUPPRESS = 917984;
+/** VS226: reading 1 of the kanji (or word) before it; VS227 reading 2, and so on. */
+export declare const SELECTOR_FIRST_READING = 917985;
+/** The IVD leaves VS225..VS240 unregistered: one to suppress, fifteen readings. */
+export declare const MAX_READINGS = 15;
+interface PlanReport {
+  stats: {
+    patterns: number;
+    places: number;
+    ambiguous: number;
+    isolated: number;
+    protectedAnnotated: number;
+    protectedBare: number;
+    glyphs: number;
+    rules: number;
+  };
+  /**
+   * The lists variation selectors index into, VS226 being the first entry,
+   * and `salt` 1 the same entry through `font-feature-settings`.
+   * Words list their readings in inline notation, the default first. `lone`
+   * is the reading a kanji alone in its run shows without a selector.
+   */
+  ivs: {
+    kanji: Record<string, string[]>;
+    words: Record<string, string[]>;
+    lone: Record<string, string>;
+    /** Whether the font maps `salt` n to the selector n after a run's first kanji: fonts built before it do not, and a preview does not. */
+    salt: boolean;
+  };
+}
+interface PlanResult {
+  plan: Plan;
+  report: PlanReport;
+}
+/**
+ * Indexes the dictionary once into Han runs, then plans fonts from it. Every
+ * decision about readings happens here: which words get ruby, which reading
+ * is the default, which longer words must be protected from a shorter match.
+ */
+export declare function createFontPlanner(dictionary: Dictionary): (options: PlanOptions, coverage: ReadonlySet<number>, previewText?: string) => PlanResult;
+//#endregion
+export type { Dictionary, DictionaryEntry, HanRun, Plan, PlanGlyph, PlanOptions, PlanOptionsInput, PlanReport, PlanResult, RubyMetrics, RubyScript, RubySpan };