@carlonicora/nextjs-jsonapi 4.1.2 → 4.2.0

package/dist/billing/index.d.ts

@@ -61,26 +61,56 @@ declare function StripeProvider({ children }: {
 }): React.JSX.Element;
 declare function isStripeConfigured(): boolean;
 
+/** A message translator, as returned by `useTranslations()`. */
+type BillingTranslator = (key: string, values?: Record<string, any>) => string;
+/**
+ * What the billing formatters need from the caller's React context. The
+ * formatters are plain functions and cannot call hooks, so a component reads
+ * `useI18nLocale()` and `useTranslations()` and passes both here.
+ *
+ * Both are optional so existing callers keep their output: without a `locale`
+ * the formatters use "en-US", without `t` they return the English literals they
+ * always returned.
+ */
+type BillingFormatOptions = {
+    /** BCP 47 locale for `Intl` (the app's active locale, from `useI18nLocale()`). */
+    locale?: string;
+    /** Translator for the words the formatters emit. */
+    t?: BillingTranslator;
+};
+
 /**
  * Format price recurring interval for display
  * @param price - Stripe price object
+ * @param options - `t` translates the interval words; without it the output is English
  * @returns Formatted interval string (e.g., "/month", "/year", "/2 weeks", "one-time")
  */
-declare function formatInterval(price: StripePriceInterface): string;
+declare function formatInterval(price: StripePriceInterface, options?: BillingFormatOptions): string;
 /**
  * Format currency amount from cents to localized currency string
  * @param amount - Amount in cents
  * @param currency - Currency code (e.g., "USD", "EUR", "GBP")
+ * @param options - `locale` drives number formatting; defaults to "en-US"
  * @returns Formatted currency string (e.g., "$9.99", "€9,99")
  */
-declare function formatCurrency(amount: number | undefined, currency: string): string;
+declare function formatCurrency(amount: number | undefined, currency: string, options?: BillingFormatOptions): string;
+/**
+ * `value.toFixed(digits)` with the locale's decimal separator ("12.5" in English,
+ * "12,5" in Italian). No grouping, so English output matches `toFixed` exactly.
+ */
+declare function formatFixed(value: number, locale: string | undefined, digits: number): string;
 
 /**
  * Format a date to a localized date string
  * @param date - Date object or ISO string
+ * @param options - `locale` drives the date format (default "en-US"); `t` translates the
+ *   placeholder shown for a missing or invalid date (default English)
  * @returns Formatted date string (e.g., "Jan 15, 2025")
  */
-declare function formatDate(date: Date | string | undefined): string;
+declare function formatDate(date: Date | string | undefined, options?: BillingFormatOptions): string;
+
+/** The active locale and translator, ready to pass to the billing formatters. */
+declare function useBillingFormatOptions(): Required<BillingFormatOptions>;
 
 type BillingAlertBannerProps = {
     subscription: StripeSubscriptionInterface;
@@ -117,8 +147,12 @@ type PriceProviderProps = {
     /** Required in list mode (the prices tab) so new prices attach to the right product. */
     productId?: string;
 };
-/** Human label for a price: its nickname, else amount + interval. */
-declare function priceLabel(price: StripePriceInterface): string;
+/**
+ * Human label for a price: its nickname, else amount + interval. Pass the
+ * caller's `useBillingFormatOptions()` so the amount and interval follow the
+ * active locale; without it the label is formatted in English.
+ */
+declare function priceLabel(price: StripePriceInterface, fmt?: BillingFormatOptions): string;
 declare const PriceProvider: ({ children, dehydratedPrice, publishChrome, productId: productIdProp, }: PriceProviderProps) => React.JSX.Element;
 declare const usePriceContext: () => PriceContextType;
 
@@ -491,4 +525,4 @@ type PromoCodeInputProps = {
 };
 declare function PromoCodeInput({ appliedCode, isValidating, error, onApply, onRemove, disabled, }: PromoCodeInputProps): React.JSX.Element;
 
-export { BillingAlertBanner, BillingDashboardContainer, BillingDetailModal, type BillingInterval, BillingUsageSummaryCard, CancelSubscriptionDialog, CustomerInfoCard, IntervalToggle, type IntervalToggleProps, InvoiceDetails, InvoiceStatusBadge, InvoicesContainer, InvoicesList, InvoicesSummaryCard, PaymentMethodCard, PaymentMethodEditor, PaymentMethodForm, PaymentMethodSummaryCard, PaymentMethodsContainer, PaymentMethodsList, PriceArchiver, PriceContainer, type PriceContextType, PriceDetails, PriceEditor, type PriceEditorProps, PriceProvider, type PriceProviderProps, PricesList, PricingCard, type PricingCardProps, ProductArchiver, ProductContainer, type ProductContextType, ProductDetails, ProductEditor, type ProductEditorProps, ProductPricingList, type ProductPricingListProps, ProductPricingRow, type ProductPricingRowProps, ProductProvider, type ProductProviderProps, ProductsList, ProductsListContainer, PromoCodeInput, ProrationPreview, StripeProvider, SubscriptionConfirmation, SubscriptionDetails, SubscriptionStatusBadge, SubscriptionSummaryCard, SubscriptionWizard, type SubscriptionWizardProps, SubscriptionsContainer, SubscriptionsList, UsageContainer, UsageHistoryTable, UsageSummaryCard, UsageSummaryCards, WizardProgressIndicator, WizardStepPaymentMethod, WizardStepPlanSelection, WizardStepReview, formatCurrency, formatDate, formatInterval, isStripeConfigured, priceLabel, usePriceContext, useProductContext };
+export { BillingAlertBanner, BillingDashboardContainer, BillingDetailModal, type BillingFormatOptions, type BillingInterval, type BillingTranslator, BillingUsageSummaryCard, CancelSubscriptionDialog, CustomerInfoCard, IntervalToggle, type IntervalToggleProps, InvoiceDetails, InvoiceStatusBadge, InvoicesContainer, InvoicesList, InvoicesSummaryCard, PaymentMethodCard, PaymentMethodEditor, PaymentMethodForm, PaymentMethodSummaryCard, PaymentMethodsContainer, PaymentMethodsList, PriceArchiver, PriceContainer, type PriceContextType, PriceDetails, PriceEditor, type PriceEditorProps, PriceProvider, type PriceProviderProps, PricesList, PricingCard, type PricingCardProps, ProductArchiver, ProductContainer, type ProductContextType, ProductDetails, ProductEditor, type ProductEditorProps, ProductPricingList, type ProductPricingListProps, ProductPricingRow, type ProductPricingRowProps, ProductProvider, type ProductProviderProps, ProductsList, ProductsListContainer, PromoCodeInput, ProrationPreview, StripeProvider, SubscriptionConfirmation, SubscriptionDetails, SubscriptionStatusBadge, SubscriptionSummaryCard, SubscriptionWizard, type SubscriptionWizardProps, SubscriptionsContainer, SubscriptionsList, UsageContainer, UsageHistoryTable, UsageSummaryCard, UsageSummaryCards, WizardProgressIndicator, WizardStepPaymentMethod, WizardStepPlanSelection, WizardStepReview, formatCurrency, formatDate, formatFixed, formatInterval, isStripeConfigured, priceLabel, useBillingFormatOptions, usePriceContext, useProductContext };