@svgrid/enterprise 3.0.2 → 3.1.0

package/dist/sheet/number-format.d.ts

@@ -35,29 +35,76 @@ export type CompiledFormat = {
     /** The pattern this was compiled from, for round-tripping to xlsx. */
     readonly pattern: string;
 };
-export declare function compileNumberFormat(pattern: string): CompiledFormat;
+/**
+ * The marks a rendered number carries.
+ *
+ * The PATTERN is always written the invariant way, `#,##0.00`, whatever
+ * the locale: that is how Excel stores one and how the file carries it.
+ * These are what the pattern's `,` and `.` come out AS.
+ */
+export type NumberMarks = {
+    decimal: string;
+    group: string;
+};
+export declare const INVARIANT_MARKS: NumberMarks;
+export declare function compileNumberFormat(pattern: string, marks?: NumberMarks): CompiledFormat;
 /** Format one value against a pattern. Convenience over compile-then-call. */
 export declare function formatWithPattern(value: unknown, pattern: string): string;
-/** The presets behind Ctrl+Shift+1 through 6. */
+/** The presets behind Ctrl+Shift+1 through 6 and the ribbon's $ % , buttons.
+ *  Percent is Excel's Percent Style, no decimals: 0.425 reads 43%. */
 export declare const FORMAT_PRESETS: {
     readonly general: "General";
     readonly number: "#,##0.00";
     readonly time: "h:mm AM/PM";
     readonly date: "yyyy-mm-dd";
     readonly currency: "$#,##0.00;($#,##0.00)";
-    readonly percent: "0.00%";
+    readonly accounting: "_($* #,##0.00_);_($* (#,##0.00);_($* \"-\"??_);_(@_)";
+    readonly percent: "0%";
     readonly scientific: "0.00E+00";
 };
+/** What the ribbon's Number Format combo applies for a category. Excel's
+ *  "Percentage" there carries two decimals where its % button carries none;
+ *  the other entries are the presets. */
+export declare const FORMAT_CATEGORY_PATTERNS: Record<keyof typeof FORMAT_PRESETS, string>;
+/** Excel's Special category: fixed-shape numbers laid into a mask. */
+export declare const SPECIAL_FORMATS: {
+    readonly zip: {
+        readonly label: "Zip Code";
+        readonly pattern: "00000";
+    };
+    readonly zip4: {
+        readonly label: "Zip Code + 4";
+        readonly pattern: "00000-0000";
+    };
+    readonly phone: {
+        readonly label: "Phone Number";
+        readonly pattern: "[<=9999999]###-####;(###) ###-####";
+    };
+    readonly ssn: {
+        readonly label: "Social Security Number";
+        readonly pattern: "000-00-0000";
+    };
+};
+export type SpecialFormatName = keyof typeof SPECIAL_FORMATS;
+/** The pattern Excel's Accounting category spells for a symbol and a
+ *  number of decimals; an empty symbol is its "None". */
+export declare function accountingPattern(symbol: string, decimals: number): string;
+/** The symbol and decimals an accounting pattern was built from, or null
+ *  when the pattern is not one `accountingPattern` would spell. */
+export declare function accountingParts(fmt: string | undefined): {
+    symbol: string;
+    decimals: number;
+} | null;
 export type FormatPresetName = keyof typeof FORMAT_PRESETS;
 /**
  * Which of Excel's categories a pattern belongs to, with the decimals and
  * separator it carries, so the ribbon's combo can say "Percentage" for a
- * cell holding `0%` (a typed 12%) as well as for the preset's `0.00%`, and
+ * cell holding `0%` (a typed 12%) as well as for the combo's `0.00%`, and
  * Format Cells can open on the right category. A pattern that is none of
  * them is 'custom'.
  */
 export declare function formatCategory(fmt: string | undefined): {
-    category: FormatPresetName | 'custom';
+    category: FormatPresetName | 'special' | 'custom';
     decimals: number;
     thousands: boolean;
 };