@temboplus/frontend-core 0.3.0 → 0.4.0

package/dist/models/amount/amount.d.ts

@@ -46,16 +46,16 @@ export type AmountJSON = z.infer<typeof AmountJSONSchema>;
  * @example
  * ```typescript
  * // Currency-amount combinations
- * Amount.from('TZS10000');           // TSh 10,000.00
- * Amount.from('TZS 10,000');         // TSh 10,000.00 (spaces removed)
- * Amount.from('10000TZS');           // TSh 10,000.00
- * Amount.from('TZS1,234.56');        // TSh 1,234.56
- * Amount.from('-TZS1000');           // -TSh 1,000.00
- * Amount.from('TZS-1000');           // -TSh 1,000.00
+ * Amount.from('TZS10000');           // TZS 10,000.00
+ * Amount.from('TZS 10,000');         // TZS 10,000.00 (spaces removed)
+ * Amount.from('10000TZS');           // TZS 10,000.00
+ * Amount.from('TZS1,234.56');        // TZS 1,234.56
+ * Amount.from('-TZS1000');           // -TZS 1,000.00
+ * Amount.from('TZS-1000');           // -TZS 1,000.00
  *
  * // Traditional usage still works
- * Amount.from(1000, 'TZS');          // TSh 1,000.00
- * Amount.from('1000', 'USD');        // $1,000.00
+ * Amount.from(1000, 'TZS');          // TZS 1,000.00
+ * Amount.from('1000', 'USD');        // USD 1,000.00
  * ```
  */
 /**
@@ -75,13 +75,13 @@ export interface AmountJson {
  * Formatting options for the enhanced format method
  */
 interface AmountFormatOptions {
-    /** Include currency symbol (e.g., $, TSh) */
-    includeSymbol?: boolean;
-    /** Include currency code (e.g., USD, TZS) */
-    includeCurrency?: boolean;
-    /** Position of currency symbol */
-    symbolPosition?: "before" | "after";
-    /** Use thousands separators (commas) */
+    /** Show currency indicator (code by default, or symbol if useSymbol is true). Default: true */
+    showCurrency?: boolean;
+    /** Use currency symbol (e.g., $, TSh) instead of code (e.g., USD, TZS). Default: false */
+    useSymbol?: boolean;
+    /** Position of currency indicator. Default: "before" */
+    currencyPosition?: "before" | "after";
+    /** Use thousands separators (commas). Default: true */
     useGrouping?: boolean;
     /** Minimum number of decimal places */
     minimumFractionDigits?: number;
@@ -95,10 +95,8 @@ interface AmountFormatOptions {
     thousandsSeparator?: string;
     /** Custom decimal separator */
     decimalSeparator?: string;
-    /** Use native formatting with Intl.NumberFormat (defaults to false for backward compatibility) */
+    /** Use native formatting with Intl.NumberFormat (defaults to false) */
     useNativeFormatting?: boolean;
-    /** Use native currency symbol instead of international symbol */
-    useNativeSymbol?: boolean;
     /** Prefer native locale for the currency (overrides provided locale) */
     useNativeLocale?: boolean;
 }
@@ -116,9 +114,9 @@ interface AmountFormatOptions {
  * @example
  * ```typescript
  * // Creating amounts
- * const positive = Amount.from(1000, 'USD'); // $1,000.00
- * const negative = Amount.from(-500, 'USD');  // -$500.00
- * const fromString = Amount.from('-1,234.56', 'EUR'); // -€1,234.56
+ * const positive = Amount.from(1000, 'USD'); // USD 1,000.00
+ * const negative = Amount.from(-500, 'USD');  // -USD 500.00
+ * const fromString = Amount.from('-1,234.56', 'EUR'); // -EUR 1,234.56
  *
  * // Mathematical operations
  * const sum = positive.add(negative); // $500.00
@@ -480,51 +478,41 @@ declare class Amount {
      * const amount = Amount.from(-1234.56, 'USD');
      * const tzAmount = Amount.from(1234.56, 'TZS');
      *
-     * // Basic formatting (existing behavior)
-     * amount.format(); // "-$1,234.56"
+     * // Default formatting (currency codes)
+     * amount.format(); // "-USD 1,234.56"
+     * tzAmount.format(); // "TZS 1,234.56"
      *
-     * // Native formatting with proper spacing and locale
-     * tzAmount.format({ useNativeFormatting: true }); // "TSh 1,234.56"
+     * // Symbol formatting (opt-in)
+     * amount.format({ useSymbol: true }); // "-$1,234.56"
+     * tzAmount.format({ useSymbol: true }); // "TSh 1,234.56"
+     *
+     * // Native formatting with Intl (uses symbols via browser locale)
      * tzAmount.format({ useNativeFormatting: true, useNativeLocale: true }); // Uses Swahili locale
      *
-     * // Manual formatting with native symbols
-     * amount.format({ useNativeSymbol: true }); // "-$1,234.56"
-     * tzAmount.format({ useNativeSymbol: true }); // "-TSh 1,234.56" (with proper spacing)
-     *
-     * // Advanced native formatting
-     * amount.format({
-     *   useNativeFormatting: true,
-     *   useNativeLocale: true,
-     *   showSign: 'always'
-     * }); // "+$1,234.56" (US formatting)
-     *
-     * // European formatting
-     * Amount.from(1234.56, 'EUR').format({
-     *   useNativeFormatting: true,
-     *   useNativeLocale: true
-     * }); // "1.234,56 €" (German formatting)
-     *
-     * // Custom formatting (existing behavior preserved)
-     * amount.format({ symbolPosition: 'after', useGrouping: false }); // "-1234.56$"
+     * // Currency position
+     * amount.format({ currencyPosition: 'after' }); // "-1,234.56 USD"
+     *
+     * // No currency
+     * amount.format({ showCurrency: false }); // "-1,234.56"
      * ```
      */
     format(options?: AmountFormatOptions): string;
     /**
-     * Convenience method for native formatting
+     * Convenience method for native formatting using Intl.NumberFormat with symbols
      * @param options Additional formatting options
-     * @returns Formatted string using native currency conventions
+     * @returns Formatted string using native currency conventions with symbols
      */
     formatNative(options?: Omit<AmountFormatOptions, "useNativeFormatting">): string;
     /**
-     * Enhanced label using native formatting for better UX
+     * Primary display label using currency codes (e.g., "TZS 1,000.00", "USD 500.00")
      */
     get label(): string;
     /**
-     * International label using consistent formatting
+     * International label using currency codes with en-US locale
      */
     get internationalLabel(): string;
     /**
-     * Returns the amount as a plain number string without currency symbols
+     * Returns the amount as a plain number string without currency indicator
      *
      * @param options - Formatting options for the numeric value
      * @returns Plain numeric string
@@ -538,35 +526,34 @@ declare class Amount {
      * }); // "1,234.5000"
      * ```
      */
-    toPlainNumber(options?: Omit<AmountFormatOptions, "includeSymbol" | "includeCurrency" | "symbolPosition">): string;
+    toPlainNumber(options?: Omit<AmountFormatOptions, "showCurrency" | "useSymbol" | "currencyPosition">): string;
     /**
      * Formats amount in compact notation (K, M, B, T)
      *
      * @param precision - Number of decimal places for compact numbers (default: 1)
-     * @param includeSymbol - Whether to include currency symbol (default: true)
      * @param options - Additional formatting options
      * @returns Compact formatted string
      *
      * @example
      * ```typescript
-     * Amount.from(1500).toCompactFormat();        // "$1.5K"
-     * Amount.from(-2500000).toCompactFormat();    // "-$2.5M"
-     * Amount.from(1234567890).toCompactFormat();  // "$1.2B"
-     * Amount.from(999).toCompactFormat();         // "$999"
-     * Amount.from(1000000, 'EUR').toCompactFormat(2); // "€1.00M"
-     * Amount.from(1000000).toCompactFormat(2, true, { alwaysShowDecimals: true }); // "$1.00M"
-     * Amount.from(1500000).toCompactFormat(0);    // "$2M" (rounded)
+     * Amount.from(1500).toCompactFormat();        // "TZS 1.5K"
+     * Amount.from(-2500000, 'USD').toCompactFormat();    // "-USD 2.5M"
+     * Amount.from(1234567890, 'USD').toCompactFormat();  // "USD 1.2B"
+     * Amount.from(999, 'USD').toCompactFormat();         // "USD 999"
+     * Amount.from(1000000, 'EUR').toCompactFormat(2, { alwaysShowDecimals: true }); // "EUR 1.00M"
+     * Amount.from(1500000, 'USD').toCompactFormat(0);    // "USD 2M" (rounded)
      * ```
      */
     toCompactFormat(precision?: number, options?: {
-        includeSymbol?: boolean;
+        showCurrency?: boolean;
+        useSymbol?: boolean;
         alwaysShowDecimals?: boolean;
         roundingMode?: "round" | "floor" | "ceil";
     }): string;
     /**
      * Returns the amount rounded to the nearest whole number
      *
-     * @param includeSymbol - Whether to include currency symbol (default: false)
+     * @param showCurrency - Whether to include currency code (default: false)
      * @param useGrouping - Whether to use thousands separators (default: true)
      * @returns Whole number formatted string
      *
@@ -574,11 +561,11 @@ declare class Amount {
      * ```typescript
      * Amount.from(1234.56).toWholeNumber();                // "1,235"
      * Amount.from(-1234.44).toWholeNumber();               // "-1,234"
-     * Amount.from(1000.5).toWholeNumber(true);             // "$1,001"
+     * Amount.from(1000.5, 'USD').toWholeNumber(true);      // "USD 1,001"
      * Amount.from(999.4).toWholeNumber(false, false);      // "999"
      * ```
      */
-    toWholeNumber(includeSymbol?: boolean, useGrouping?: boolean): string;
+    toWholeNumber(showCurrency?: boolean, useGrouping?: boolean): string;
     /**
      * Helper method to get the actual rounded value as a number (for toWholeNumber)
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temboplus/frontend-core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A JavaScript/TypeScript package providing common utilities and logic shared across front-end TemboPlus projects.",
   "author": "Okello Gerald",
   "license": "MIT",