@gram-lang/i18n 1.4.2 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @gram-lang/i18n
2
2
 
3
- [![npm version](https://badge.fury.io/js/@gram-lang%2Fi18n.svg)](https://www.npmjs.com/package/@gram-lang/i18n)
3
+ [![npm](https://img.shields.io/npm/v/@gram-lang/i18n?color=cb3837&style=flat-square)](https://www.npmjs.com/package/@gram-lang/i18n)
4
4
  [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
5
5
 
6
6
  *Part of the [Gram monorepo](https://git.gram-lang.org/gram-lang/gram).*
@@ -11,7 +11,7 @@ The translation and normalization module of the Gram recipe language: it normali
11
11
 
12
12
  ## 📚 General Documentation
13
13
 
14
- For full syntax specifications, grammar details, cheatsheets, and best practices, please refer to the **[Gram Documentation](https://docs.gram-lang.org/)**.
14
+ For full syntax specifications, grammar details, cheatsheets, and best practices, please refer to the **[Gram Documentation](https://gram-lang.org/docs/)**.
15
15
 
16
16
  ---
17
17
 
@@ -47,11 +47,13 @@ console.log(resolveTimeUnit('minutes')); // 'm'
47
47
  `getDictionary(lang)` returns the dictionary of a language (`en` or `fr`): the labels of the renderer's views (`renderer.*`, including the names of the outputs and of the formats), the units of durations (`renderer.durationUnits`, `1h 30min` or `1j 1h`) and the strings of the playground. `fillTemplate(template, values)` fills the `{name}` placeholders of a dictionary string (`"Serve at {time}"` becomes `"Serve at 20:00"`) and leaves a name with no value as written, so a missing value shows up instead of vanishing.
48
48
 
49
49
  ```javascript
50
- import { getDictionary, fillTemplate } from '@gram-lang/i18n';
50
+ import { getDictionary, fillTemplate, formatNumber, parseDuration } from '@gram-lang/i18n';
51
51
 
52
52
  const t = getDictionary('fr');
53
53
  console.log(t.renderer.durationUnits); // { day: 'j', hour: 'h', minute: 'min', second: 's' }
54
54
  console.log(fillTemplate('Serve at {time}', { time: '20:00' })); // 'Serve at 20:00'
55
+ console.log(formatNumber(1.5, 'fr')); // '1,5'
56
+ console.log(parseDuration('1h 30min')); // { ok: true, kind: 'single', ... }
55
57
  ```
56
58
 
57
59
  A key is added in both languages together: a surface never carries a word of its own.
@@ -70,6 +72,9 @@ If a language-specific code (e.g., `'fr'`) is provided, the function checks the
70
72
  * `src/dictionary.ts`: Dictionary compiler helper that transforms structured translations into flat `O(1)` maps.
71
73
  * `src/units.ts`: Mass and volume unit dictionary (French & English) and normalizer.
72
74
  * `src/time.ts`: Time unit dictionary (French & English) and normalizer.
75
+ * `src/duration.ts`: Compound, clock, prime, and range duration parser (`parseDuration()`).
76
+ * `src/numbers.ts`: Locale-aware number formatting (`formatNumber()`, `localizeDecimals()`, `toKitchenFraction()`).
77
+ * `src/quantity.ts`: Quantity term arithmetic and formatting (`termsTotal()`, `mergeTerms()`, `scaleTerms()`, `formatTerms()`).
73
78
  * `src/locales/`: The `en` and `fr` dictionaries (renderer views, nutrients, playground) and `getDictionary()`.
74
79
  * `src/template.ts`: `fillTemplate()`.
75
80
  * `src/categories.ts`: Shopping list category keys and their labels per language.
package/dist/index.d.ts CHANGED
@@ -36,6 +36,45 @@ declare const UNIT_CONVERSIONS: {
36
36
  mass: UnitMap;
37
37
  volume: UnitMap;
38
38
  };
39
+ /**
40
+ * A run of units of one measuring system whose sizes are exact whole-number
41
+ * multiples of each other: what a cook can add up without rounding
42
+ * (`1 cup + 1 tbsp` = `17 tbsp`). Each step is the unit's size counted in the
43
+ * ladder's smallest unit (1 cup = 48 tsp).
44
+ *
45
+ * `UNIT_CONVERSIONS` says how much a unit weighs or holds in grams or
46
+ * milliliters, with its factors rounded (`cup: 236.588`); a ladder only says
47
+ * how units of one system relate, exactly. The two agree to 0.01%
48
+ * (`units-ladders.test.ts`).
49
+ */
50
+ interface UnitLadder {
51
+ id: "usVolume" | "imperialMass" | "metricMass" | "metricVolume";
52
+ family: keyof typeof UNIT_CONVERSIONS;
53
+ /** Canonical unit → its size in the ladder's smallest unit. */
54
+ steps: Readonly<Record<string, number>>;
55
+ }
56
+ declare const UNIT_LADDERS: readonly UnitLadder[];
57
+ /** Where a unit stands on its ladder. */
58
+ interface LadderStep {
59
+ ladder: UnitLadder;
60
+ /** The canonical unit (`cup` for `cups`, `tbsp` for `càs`). */
61
+ unit: string;
62
+ /** Its size in the ladder's smallest unit. */
63
+ size: number;
64
+ }
65
+ /**
66
+ * The ladder a unit belongs to (any spelling: `cups`, `càs`, `kilo`), or
67
+ * `null` for a unit on no ladder (`pinch`, `gousse`, no unit at all).
68
+ */
69
+ declare function ladderOf(rawUnit: string | undefined | null, lang?: string): LadderStep | null;
70
+ /**
71
+ * True when every unit stands on one same ladder (`cup`, `tbsp`, `tsp`), so
72
+ * their amounts add up exactly. False for no unit at all, for a unit on no
73
+ * ladder, and across systems (`cup` and `ml`, `oz` and `g`).
74
+ */
75
+ declare function sameLadder(rawUnits: readonly (string | undefined | null)[], lang?: string): boolean;
76
+ /** The spelling of a canonical unit (`tbsp`) in a language (`càs` in French). */
77
+ declare function unitSpelling(canonical: string, lang?: string): string;
39
78
  /**
40
79
  * Normalizes a raw string unit into a standard canon unit.
41
80
  * Examples: 'càs' -> 'tbsp', 'kilo' -> 'kg'.
@@ -69,6 +108,25 @@ declare function toLargerMetricUnit(value: number, rawUnit: string | undefined |
69
108
  value: number;
70
109
  unit: string;
71
110
  };
111
+ /**
112
+ * Converts a value between two units of the same family, mass to mass or
113
+ * volume to volume (`1 l` → `1000 ml`, `1 lb` → `453.59 g`), through
114
+ * `UNIT_CONVERSIONS` alone. The same unit, however spelled, gives the value
115
+ * back. Across families (mass and volume), or for a unit that is neither,
116
+ * `null`: crossing needs a density, which only the caller can bring.
117
+ */
118
+ declare function convertUnitInFamily(value: number, fromUnit: string | null | undefined, toUnit: string | null | undefined, lang?: string): number | null;
119
+ /**
120
+ * True when two counting units (neither a mass nor a volume) name the same
121
+ * thing: the same spelling, or one is the other with a plural ending `s`,
122
+ * `es` or `x` (`gousse`/`gousses`, `tranche`/`tranches`, `box`/`boxes`,
123
+ * `chou`/`choux`). Forms are compared, never a suffix stripped (`tranches`
124
+ * less `es` is `tranch`), and no plural is looked for under three letters.
125
+ * No unit, and every spelling of "a piece" (`pièce`, `pc`, `unit`...), count
126
+ * as the same: no unit. For ratios only: the shopping list keeps `gousse` and
127
+ * `gousses` apart.
128
+ */
129
+ declare function sameCountUnit(a: string | null | undefined, b: string | null | undefined, lang?: string): boolean;
72
130
  /** True for a unit of mass or volume Gram knows (g, kg, cup, tbsp, c.à.s...). */
73
131
  declare function isMeasureUnit(rawUnit: string | undefined | null, lang?: string): boolean;
74
132
  /**
@@ -89,14 +147,37 @@ declare function unitContainsQuantity(rawUnit: string | undefined | null, lang?:
89
147
  * `formatNumber(1500, "fr")` is `"1500"`.
90
148
  */
91
149
  declare function formatNumber(value: number, lang?: string, maxDecimals?: number): string;
150
+ /**
151
+ * How many decimals an amount keeps when it is shown: 3 significant digits,
152
+ * never fewer than its whole part (`152.37` → `152`, `15.24` → `15.2`,
153
+ * `1.15` → `1.15`), and 2 significant digits below 1 (`0.15`, `0.03`,
154
+ * `0.0047`), so a small amount is never shown as `0`. The precision follows
155
+ * the size of the amount, not its unit: rounded to a fixed decimal in the
156
+ * author's unit, `0.15 kg` read `0.2 kg` and `0.02 kg` read `0 kg` (#230).
157
+ */
158
+ declare function amountDecimals(value: number): number;
159
+ /** An amount rounded as it is shown (see `amountDecimals`). */
160
+ declare function roundAmount(value: number): number;
161
+ /** An amount as it is shown, in the reader's language (see `amountDecimals`). */
162
+ declare function formatAmount(value: number, lang?: string): string;
92
163
  /** The decimal separator of a language: `"."` in English, `","` in French. */
93
164
  declare function decimalSeparator(lang?: string): string;
94
165
  /**
95
- * The decimal points of a quantity already written as text (a range
96
- * `1.5-2`, a timer `1.5`) in the reader's language: `"1,5-2"` in French.
97
- * Only a point between two digits changes, so `1/2` or a unit stay as they are.
166
+ * The decimal separators of a quantity already written as text (a range
167
+ * `1.5-2`, a timer `1,5`) in the reader's language: `"1,5-2"` in French,
168
+ * `"1.5"` in English. Gram reads a point or a comma between two digits as a
169
+ * decimal separator, so both change; `1/2` or a unit stay as they are.
98
170
  */
99
171
  declare function localizeDecimals(text: string, lang?: string): string;
172
+ /**
173
+ * A comma that a reader could take for a thousands separator: exactly three
174
+ * digits after it and a whole part of one to three digits, not zero
175
+ * (`1,000`, `12,500`). Gram reads it as a decimal (1, 12.5), as it reads every
176
+ * comma between two digits, and has no thousands separator; `0,125` or
177
+ * `1,25` cannot be one. The point is not concerned: it has always been a
178
+ * decimal in Gram, so `1.000` keeps meaning 1.
179
+ */
180
+ declare function looksLikeThousands(text: string): boolean;
100
181
  /** `"1/4"` for a value strictly between 0 and 1 that is (nearly) a common fraction. */
101
182
  declare function commonFraction(value: number): string | undefined;
102
183
  /** True for a unit read in fractions (spoons, cups, imperial measures). */
@@ -268,6 +349,10 @@ declare const en: {
268
349
  runSheetInStock: string;
269
350
  runSheetProgramStep: string;
270
351
  runSheetProgramSteps: string;
352
+ /**
353
+ * @deprecated Since 1.5.0, will be removed in 2.0.0. (Ref: i18n-run-sheet-range)
354
+ * The run sheet writes a range with `formatDurationRange` (`8–16 h`), as the steps do.
355
+ */
271
356
  runSheetRange: string;
272
357
  runSheetPossibleFrom: string;
273
358
  runSheetFixedService: string;
@@ -316,6 +401,8 @@ declare const en: {
316
401
  tooltipBakers: string;
317
402
  tooltipTakenFrom: string;
318
403
  alternatives: string;
404
+ tooltipRatio: string;
405
+ relativeOf: string;
319
406
  decreasePortions: string;
320
407
  editPortions: string;
321
408
  increasePortions: string;
@@ -477,6 +564,10 @@ declare const en: {
477
564
  stepQuantitiesDesc: string;
478
565
  nutritionBasis: string;
479
566
  nutritionBasisAuto: string;
567
+ clock: string;
568
+ clockAuto: string;
569
+ clock12h: string;
570
+ clock24h: string;
480
571
  rejectedSlots: string;
481
572
  forceReference: string;
482
573
  autoDetect: string;
@@ -500,6 +591,7 @@ declare const en: {
500
591
  scaleByIngredient: string;
501
592
  bakersMath: string;
502
593
  comments: string;
594
+ clock: string;
503
595
  stepQuantities: string;
504
596
  nutritionBasis: string;
505
597
  bakersMathOnly: string;
@@ -534,6 +626,8 @@ declare const en: {
534
626
  show: string;
535
627
  expandConsole: string;
536
628
  collapseConsole: string;
629
+ notInDatabase: string;
630
+ showDatabase: string;
537
631
  };
538
632
  errorState: {
539
633
  title: string;
@@ -541,6 +635,12 @@ declare const en: {
541
635
  jumpToError: string;
542
636
  line: string;
543
637
  };
638
+ database: {
639
+ tabLabel: string;
640
+ project: string;
641
+ docLink: string;
642
+ docHref: string;
643
+ };
544
644
  tabs: {
545
645
  addFile: string;
546
646
  removeFile: string;
@@ -566,6 +666,18 @@ declare const en: {
566
666
  statusWarnings: string;
567
667
  copyBtn: string;
568
668
  };
669
+ cook: {
670
+ /** Under a step of `gram cook`: the state that ends it (`={ribbon stage}`). */
671
+ targetState: string;
672
+ /** When a timer of a step rings: the target states to check, `{states}`. */
673
+ checkTargetState: string;
674
+ };
675
+ languageServer: {
676
+ /** Hover on a section anchor: `{duration}` is the anticipation. */
677
+ anchorReady: string;
678
+ anchorInDays: string;
679
+ anchorInHours: string;
680
+ };
569
681
  };
570
682
  type GramLocale = typeof en;
571
683
 
@@ -578,4 +690,331 @@ declare function getDictionary(lang?: string): GramLocale;
578
690
  */
579
691
  declare function fillTemplate(template: string, values: Readonly<Record<string, string>>): string;
580
692
 
581
- export { CATEGORY_KEYS, type CategoryKey, type CompiledDict, type GramLocale, type LanguageDict, TIME_BY_LANG, TIME_DICTIONARIES, TIME_GLOBAL, TIME_TO_MINUTES, UNIT_BY_LANG, UNIT_CONVERSIONS, UNIT_DICTIONARIES, UNIT_GLOBAL, type UnitMap, commonFraction, compileDictionary, decimalSeparator, fillTemplate, formatNumber, getAiLanguageInstruction, getCategoryLabels, getDefaultCategories, getDictionary, isCategoryKey, isCoarseUnit, isFractionUnit, isMeasureUnit, isMetricMassUnit, localizeDecimals, normalizeUnit, resolveTimeUnit, toKitchenFraction, toLargerMetricUnit, unitContainsQuantity, unitKey };
693
+ /**
694
+ * Durations as a recipe writes them: `1h30`, `1 hr 30 mins`, `1 heure 30`,
695
+ * `1:30 h`, `5'30"`, `45 min - 1 h`. `parseDuration` reads one into minutes,
696
+ * or says precisely why it will not: it never guesses, and never turns an
697
+ * unclear duration into 0.
698
+ *
699
+ * Reading happens in two steps. The text is first cut into tokens by kind of
700
+ * character (numbers, letters, primes, `:`, `+`, `-`), so spaces carry no
701
+ * meaning (`1h30`, `1 h 30`, `1hr 30` read alike), except between a whole
702
+ * number and a fraction (`1 1/2`). The token sequence is then checked against
703
+ * the three forms (units, clock, primes) and the range rules.
704
+ *
705
+ * The units come from `TIME_DICTIONARIES`, every language at once: a timer
706
+ * reads without knowing the language of the recipe.
707
+ */
708
+ /** A canonical time unit: day, hour, minute, second. */
709
+ type DurationUnit = "d" | "h" | "m" | "s";
710
+ /** How a duration is written: `1h30` (units), `1:30 h` (clock), `5'30"` (primes). */
711
+ type DurationForm = "units" | "clock" | "prime";
712
+ /** One term of a duration, in the unit it was written in (`1h30` is `1 h` and `30 m`). */
713
+ interface DurationPart {
714
+ value: number;
715
+ unit: DurationUnit;
716
+ }
717
+ /** One duration, or one side of a range. */
718
+ interface DurationSide {
719
+ minutes: number;
720
+ parts: DurationPart[];
721
+ form: DurationForm;
722
+ }
723
+ /**
724
+ * Why a text is not a duration Gram reads:
725
+ * - `empty`: nothing between the braces;
726
+ * - `missingUnit`: a number with no unit at all (`30`, `1-2`);
727
+ * - `unknownUnit`: a word right after a number that is not a time unit (`3 bananas`);
728
+ * - `words`: any other word (`half an hour`, `1 heure et demie`, `about 10 min`);
729
+ * - `multiplication`: `2 * 2 min`, written as the total instead;
730
+ * - `iso8601`: `PT1H30M`, a notation for machines;
731
+ * - `unexpected`: a character or a sign out of place (`1h, 30min`, `-10 min`, `1/0 h`);
732
+ * - `ambiguousClock`: a two-part clock with no unit (`1:30`: hours or minutes?);
733
+ * - `clockFormat`: a malformed clock (`1:5 h`, `1:30 d`, more than three parts);
734
+ * - `unitOrder`: units not from the largest to the smallest (`30min 1h`);
735
+ * - `duplicateUnit`: the same unit twice (`1h 2h`);
736
+ * - `overflow60`: 60 or more after an hour or a minute, where the unit is
737
+ * implied, in a clock or with a prime (`1h75`, `1:75 h`, `5'90"`); with its
738
+ * unit written out it is read as written (`1 h 75 min` is 2 h 15 min);
739
+ * - `decimalInCompound`: a decimal or a fraction in a duration of several terms (`1.5h30`);
740
+ * - `decimalPrime`: a decimal or a fraction with a prime (`1.5'`);
741
+ * - `bareNumber`: a number with no unit where none can be implied (`1j3`, `1 30 min`);
742
+ * - `reversedRange`: a range written from the largest to the smallest (`2-1 h`):
743
+ * the minimum comes first, in the order of the text (logical order, so a
744
+ * right-to-left language writes it the same way);
745
+ * - `emptyRange`: a range whose two sides are equal (`1-1 h`);
746
+ * - `ambiguousRange`: a range where one side's unit cannot be told (`1-2h30`).
747
+ */
748
+ type DurationFailure = "empty" | "missingUnit" | "unknownUnit" | "words" | "multiplication" | "iso8601" | "unexpected" | "ambiguousClock" | "clockFormat" | "unitOrder" | "duplicateUnit" | "overflow60" | "decimalInCompound" | "decimalPrime" | "bareNumber" | "reversedRange" | "emptyRange" | "ambiguousRange";
749
+ type DurationResult = {
750
+ ok: true;
751
+ /** The duration the schedule uses: the middle of a range. */
752
+ minutes: number;
753
+ range?: {
754
+ min: number;
755
+ max: number;
756
+ };
757
+ /** One side, or the two sides of a range. */
758
+ sides: [DurationSide] | [DurationSide, DurationSide];
759
+ } | {
760
+ ok: false;
761
+ reason: DurationFailure;
762
+ /** The word read as a unit, for `unknownUnit`. */
763
+ unit?: string;
764
+ };
765
+ type Failure = Extract<DurationResult, {
766
+ ok: false;
767
+ }>;
768
+ /**
769
+ * `int`: digits only (`30`). `decimal`: `1.5`, `1,5`. `fraction`: `1/2`, `½`,
770
+ * `1½`, `1 1/2`. Only an `int` follows an hour or a minute without a unit, or
771
+ * makes a clock.
772
+ */
773
+ type NumKind = "int" | "decimal" | "fraction";
774
+ type Token = {
775
+ kind: "num";
776
+ value: number;
777
+ text: string;
778
+ num: NumKind;
779
+ space: boolean;
780
+ } | {
781
+ kind: "word";
782
+ text: string;
783
+ unit?: DurationUnit;
784
+ } | {
785
+ kind: "prime";
786
+ unit: "m" | "s";
787
+ } | {
788
+ kind: "colon";
789
+ } | {
790
+ kind: "plus";
791
+ } | {
792
+ kind: "dash";
793
+ } | {
794
+ kind: "star";
795
+ };
796
+ /**
797
+ * Cuts a duration into tokens: the step that makes `1h30`, `1 h 30` and
798
+ * `1hr 30` the same sequence. A unit is any run of letters, in any script,
799
+ * lowercased, with a `.` right after it dropped (`hr.`, `min.`, `Std.`).
800
+ */
801
+ declare function tokenizeDuration(text: string): {
802
+ ok: true;
803
+ tokens: Token[];
804
+ } | Failure;
805
+ /**
806
+ * Reads a duration as a recipe writes it, in any language Gram knows:
807
+ * `parseDuration("1h30")` is `{ ok: true, minutes: 90, … }`,
808
+ * `parseDuration("1:30")` is `{ ok: false, reason: "ambiguousClock" }`.
809
+ *
810
+ * A range keeps both sides and gives its middle as `minutes`, as the schedule
811
+ * uses it. No sign is read (an anchor's `-` is the caller's), and no duration
812
+ * is capped: that is the compiler's job.
813
+ */
814
+ declare function parseDuration(text: string): DurationResult;
815
+
816
+ /**
817
+ * A numeric value as the compiled recipe stores it: a plain number, or the
818
+ * parser's single / fraction / range shape (structurally the parser's
819
+ * `QuantityValueAST`, redeclared here so this module stays free of it).
820
+ */
821
+ type QuantityValue = {
822
+ type: "single";
823
+ value: number;
824
+ text?: string;
825
+ } | {
826
+ type: "fraction";
827
+ value: number;
828
+ numerator: number;
829
+ denominator: number;
830
+ text?: string;
831
+ } | {
832
+ type: "range";
833
+ value: number;
834
+ range: {
835
+ min: number;
836
+ max: number;
837
+ };
838
+ text?: string;
839
+ };
840
+ /** The value of one term: kept in the shape it was written in. */
841
+ type TermValue = number | QuantityValue;
842
+ interface Term {
843
+ value: TermValue;
844
+ unit: string | null;
845
+ /** Taken away from the total (`- 2 tbsp`). */
846
+ minus?: boolean;
847
+ }
848
+ /** What a list of terms amounts to, in the compiled recipe's `qty` / `unit` shape. */
849
+ interface TermsTotal {
850
+ qty: TermValue;
851
+ unit: string | null;
852
+ }
853
+ /** Raised by `scaleTerms` when a scaled value stops being a finite number. */
854
+ declare class QuantityOverflowError extends RangeError {
855
+ readonly factor: number;
856
+ constructor(factor: number);
857
+ }
858
+ /**
859
+ * Rounds a mass/quantity value to 2 decimal places, returning a `number`
860
+ * (not a string). Centralizes the `parseFloat(x.toFixed(2))` idiom used
861
+ * throughout kitchen/analyzer so there is a single, documented rounding rule
862
+ * to port when the compiler is reimplemented in another language: `toFixed`
863
+ * uses round-half-away-from-zero on the value's shortest decimal
864
+ * representation, which differs from IEEE round-half-to-even on exact ties.
865
+ */
866
+ declare const round2: (value: number) => number;
867
+ /**
868
+ * Rounds a stored quantity or mass like `round2`, but never to fewer than 2
869
+ * significant digits: `1.234` → `1.23` and `0.333` → `0.33` as before, but
870
+ * `0.0047` stays `0.0047` instead of becoming `0`. Rounded to 2 decimals in
871
+ * the author's unit, a recipe divided by 10 lost its `0.02 kg` of salt, and
872
+ * a ratio of a pinch weighed `0 g` (#230). The views round what they show
873
+ * (`formatAmount`).
874
+ */
875
+ declare const roundQuantity: (value: number) => number;
876
+ /** True for a value a term can hold (a number, or a single / fraction / range). */
877
+ declare function isTermValue(value: unknown): value is TermValue;
878
+ /**
879
+ * The number a value stands for: the number itself, or its `value` (the
880
+ * middle of a range). `null` when the value carries no number.
881
+ */
882
+ declare function termValueNumber(value: TermValue): number | null;
883
+ /**
884
+ * What the terms amount to.
885
+ *
886
+ * - no term: `null`;
887
+ * - one term added: that term as written (a range stays a range, a fraction
888
+ * keeps its text);
889
+ * - several terms of one unit (its spellings count as one: `cup` / `cups`):
890
+ * their sum in that unit, never converted (`1 tasse + 1 tasse` is
891
+ * `2 tasses`), spelled as the first term added;
892
+ * - several units of one ladder (`UNIT_LADDERS`): their exact sum in the
893
+ * smallest unit written (`1 cup + 1 tbsp` is `17 tbsp`);
894
+ * - several units of one family across systems (`cup` and `ml`, `oz` and
895
+ * `g`): their sum in grams or milliliters, rounded to 2 decimals;
896
+ * - otherwise (`cup` and `g`, `gousse` and `pièce`, a term with no unit next
897
+ * to one with a unit): `null`, the terms do not add up to one amount.
898
+ *
899
+ * A range is added by its bounds (`2-3 g + 200 g` is `202-203 g`): a term
900
+ * taken away removes its highest number from the lowest bound and its lowest
901
+ * number from the highest one. A total with a range in it stays a range.
902
+ */
903
+ declare function termsTotal(terms: readonly Term[]): TermsTotal | null;
904
+ /**
905
+ * How terms are grouped (`mergeKey`): by unit, by ladder of units (`cup` and
906
+ * `tbsp`), or by family, the kind of amount a unit measures (`familyOf`:
907
+ * every mass together, every volume together).
908
+ */
909
+ type MergeMode = "unit" | "ladder" | "family";
910
+ /**
911
+ * The kind of amount a unit measures, for telling the families of a sum
912
+ * apart: a mass, a volume, or (a unit Gram cannot convert, `gousse`) that
913
+ * unit itself.
914
+ */
915
+ declare function familyOf(unit: string | null): string;
916
+ /**
917
+ * The key `mergeTerms` groups a term's unit under: its family in `"family"`
918
+ * mode (`familyOf`), its ladder in `"ladder"` mode (`cup` and `tbsp`, `g`
919
+ * and `kg`), otherwise the unit itself, its spellings counted as one (`cup`
920
+ * / `cups`). A unit Gram does not know (`gousse`) is only lowercased:
921
+ * `gousse` and `gousses` stay two units.
922
+ */
923
+ declare function mergeKey(unit: string | null, mode: MergeMode): string;
924
+ /** The terms grouped by `mergeKey`, groups in the order their first term comes. */
925
+ declare function groupTerms(terms: readonly Term[], mode: MergeMode): Term[][];
926
+ /**
927
+ * Puts the terms of several amounts of one ingredient together, terms added
928
+ * before terms taken away (`2 tbsp` then `1 cup - 4 tbsp` gives
929
+ * `1 cup - 2 tbsp`, never a term taken away first).
930
+ *
931
+ * - `"unit"` adds up the terms of each unit into one, its spellings counted
932
+ * as one (`100 g` and `100 g` give `200 g`); two units stay apart, even on
933
+ * one ladder (`1 cup`, `2 tbsp`): this is how a section lists an
934
+ * ingredient it uses several times.
935
+ * - `"ladder"` adds up the terms of each ladder into one, in the smallest
936
+ * unit written (`1 cup`, `2 tbsp` and `- 4 tbsp` give `14 tbsp`, see
937
+ * `termsTotal`), and the terms of each unit on no ladder into one; two
938
+ * systems (`cup` and `ml`) or two families stay apart.
939
+ *
940
+ * Each result keeps the place of the first term it adds up; a negative
941
+ * result is a term taken away, a result of zero is left out (unless nothing
942
+ * else is left). A lone term stays as written.
943
+ */
944
+ declare function mergeTerms(terms: readonly Term[], mode: MergeMode): Term[];
945
+ /**
946
+ * Multiplies a value by `factor`, rounded to 2 decimals. The source text of a
947
+ * value (`text`, a fraction's `numerator` / `denominator`) only describes the
948
+ * unscaled value, so it is dropped: a scaled fraction becomes a single value.
949
+ * A value that is not a number (a malformed object) comes back untouched.
950
+ * Throws `QuantityOverflowError` when the product is no longer finite.
951
+ */
952
+ declare function scaleTermValue<T extends TermValue>(value: T, factor: number): TermValue;
953
+ /** Every term multiplied by `factor` (see `scaleTermValue`); units are kept. */
954
+ declare function scaleTerms(terms: readonly Term[], factor: number): Term[];
955
+ /** One term as written: its number (or source text) and its unit, without its sign. */
956
+ declare function formatTerm(term: Term): string;
957
+ interface FormatTermsOptions {
958
+ /** Placed between two terms added. Default ` + `. */
959
+ plus?: string;
960
+ /** Placed before a term taken away. Default ` − `. */
961
+ minus?: string;
962
+ /**
963
+ * `"written"` (default): the terms as the author wrote them.
964
+ * `"computed"`: an amount Gram worked out (scaled, or added up from
965
+ * several occurrences), written the way a cook measures it (see
966
+ * `formatTerms`).
967
+ */
968
+ mode?: "written" | "computed";
969
+ /** The reader's language: decimals, and the spelling of a unit Gram brings in. */
970
+ lang?: string;
971
+ /**
972
+ * Writes a number next to its unit. Default: the number as it is in
973
+ * `"written"` mode; in `"computed"` mode a whole number, a kitchen
974
+ * fraction for a spoon or an imperial unit (`1 1/2`), otherwise a
975
+ * decimal in the reader's language.
976
+ */
977
+ number?: (value: number, unit: string | null) => string;
978
+ /** Writes a value's source text (`1/2`, `2.5-3`). Default: as it is. */
979
+ text?: (text: string) => string;
980
+ /**
981
+ * `"computed"` only: an amount the reader buys (a shopping list). A
982
+ * metric amount reaches the larger unit (`1500 g` is `1.5 kg`), and a
983
+ * spoon or imperial amount is recomposed from the top of its scale
984
+ * (`34 tbsp` is `2 cup + 2 tbsp`) once it reaches one of a unit at least
985
+ * four times larger than its own (`3 tsp` stays `3 tsp`).
986
+ */
987
+ buying?: boolean;
988
+ /**
989
+ * `"computed"` only, default `true`: a recomposition may round its last
990
+ * term to what its unit measures (a scaled amount was no exact measure
991
+ * anyway: `1.1 cup` is `1 cup + 1 tbsp + 2 tsp`). `false` writes an
992
+ * amount that does not recompose exactly as it is (`1.6 cup`).
993
+ */
994
+ rounding?: boolean;
995
+ }
996
+ /**
997
+ * The terms as text, in their written order (`1 cup + 1 tbsp`,
998
+ * `1 cup − 2 tbsp + 30 g`); a list that would start with a term taken away
999
+ * writes the terms added first (`1 cup − 2 tbsp`, never `−2 tbsp + 1 cup`).
1000
+ *
1001
+ * `"written"` mode (the default) writes each term as the author wrote it.
1002
+ * `"computed"` mode writes an amount Gram worked out, ladder by ladder (two
1003
+ * systems stay apart, term by term):
1004
+ *
1005
+ * - a spoon, cup or imperial amount is recomposed the way a cook measures
1006
+ * it: one amount of the largest unit written when that unit measures it
1007
+ * (`MEASURED_FRACTIONS`: `1 1/2 cup`, never `2 1/8 cup`), the terms as they
1008
+ * are when each is measurable, otherwise whole units then the rest in the
1009
+ * next unit down (`cup`, `tbsp`, `tsp`; `gal`, `qt`, `pt`, `fl oz`; `lb`,
1010
+ * `oz`), never above the largest unit written, three terms at most;
1011
+ * - a metric amount is one decimal amount in the largest unit written
1012
+ * (`1 kg + 200 g` doubled is `2.4 kg`; `800 g + 200 g` is `1000 g`, never
1013
+ * `1 kg`, unless `buying`);
1014
+ * - a range shares what both bounds have in common and puts the range on
1015
+ * the last term (`2 cup + 2-4 tbsp`), otherwise writes each bound in full;
1016
+ * - a unit on no ladder adds up with itself only (`2 gousses`).
1017
+ */
1018
+ declare function formatTerms(terms: readonly Term[], options?: FormatTermsOptions): string;
1019
+
1020
+ export { CATEGORY_KEYS, type CategoryKey, type CompiledDict, type DurationFailure, type DurationForm, type DurationPart, type DurationResult, type DurationSide, type DurationUnit, type FormatTermsOptions, type GramLocale, type LadderStep, type LanguageDict, type MergeMode, QuantityOverflowError, type QuantityValue, TIME_BY_LANG, TIME_DICTIONARIES, TIME_GLOBAL, TIME_TO_MINUTES, type Term, type TermValue, type TermsTotal, UNIT_BY_LANG, UNIT_CONVERSIONS, UNIT_DICTIONARIES, UNIT_GLOBAL, UNIT_LADDERS, type UnitLadder, type UnitMap, amountDecimals, commonFraction, compileDictionary, convertUnitInFamily, decimalSeparator, familyOf, fillTemplate, formatAmount, formatNumber, formatTerm, formatTerms, getAiLanguageInstruction, getCategoryLabels, getDefaultCategories, getDictionary, groupTerms, isCategoryKey, isCoarseUnit, isFractionUnit, isMeasureUnit, isMetricMassUnit, isTermValue, ladderOf, localizeDecimals, looksLikeThousands, mergeKey, mergeTerms, normalizeUnit, parseDuration, resolveTimeUnit, round2, roundAmount, roundQuantity, sameCountUnit, sameLadder, scaleTermValue, scaleTerms, termValueNumber, termsTotal, toKitchenFraction, toLargerMetricUnit, tokenizeDuration, unitContainsQuantity, unitKey, unitSpelling };