@factorialco/f0-react 1.310.0 → 1.311.1

package/dist/f0.d.ts

@@ -10,6 +10,7 @@ import { AvatarListCellValue as AvatarListCellValue_2 } from './types/avatarList
 import * as AvatarPrimitive from '@radix-ui/react-avatar';
 import { AvatarProps as AvatarProps_2 } from '@radix-ui/react-avatar';
 import { baseColors } from '@factorialco/f0-core';
+import { BigNumberProps as BigNumberProps_2 } from './types';
 import { BlockContentExtraProps } from './blocks/BlockContent';
 import { BlockProps } from './blocks/Block';
 import { CategoryBarProps } from './CategoryBarChart';
@@ -561,6 +562,14 @@ declare type BaseTag<T extends {
     type: string;
 }> = T & WithTooltipDescription;
 
+export declare type BigNumberProps = {
+    value: Numeric | NumberWithFormatter | number;
+    label?: string;
+    trend?: boolean | TrendConfig;
+    comparisonHint?: string;
+    comparison: Numeric | NumberWithFormatter | number;
+};
+
 export declare const buildTranslations: (translations: TranslationsType) => TranslationsType;
 
 /**
@@ -2212,6 +2221,13 @@ export declare type F0AvatarTeamProps = {
     badge?: AvatarBadge;
 } & Pick<BaseAvatarProps, "aria-label" | "aria-labelledby">;
 
+export declare const F0BigNumber: {
+    ({ label, ...props }: BigNumberProps_2): JSX_2.Element;
+    displayName: string;
+} & {
+    Skeleton: () => JSX_2.Element;
+};
+
 export declare const F0Button: ForwardRefExoticComponent<Omit<ButtonInternalProps, "style" | "className" | "variant" | "pressed" | "append" | "compact" | "noAutoTooltip" | "noTitle"> & {
 variant?: Exclude<ButtonInternalProps["variant"], "ai">;
 } & RefAttributes<HTMLAnchorElement | HTMLButtonElement>>;
@@ -3373,13 +3389,128 @@ declare type NumberFilterValue = {
     };
 } | undefined;
 
-declare interface NumericValue {
-    number: number;
-    units?: string;
-    unitsPosition?: "left" | "right";
-    decimalPlaces?: number | undefined;
+export declare type NumberWithFormatter = NumericWithFormatter & {
+    animated?: boolean;
+};
+
+declare type Numeric = NumericValue | number | undefined | null;
+
+/**
+ * Formats a numeric value according to the provided options.
+ *
+ * @param value - The numeric value to format.
+ * @param options - The formatting options.
+ * @returns The formatted value as a string.
+ */
+declare type NumericFormatter = (value: Numeric, options?: NumericFormatterOptions) => string;
+
+/**
+ * Configuration options for the numeric formatter.
+ */
+declare type NumericFormatterOptions = {
+    /**
+     * Locale string for number formatting (e.g., "en-US", "es-ES", "de-DE").
+     * Determines the decimal separator and other locale-specific formatting rules.
+     *
+     * @default "en-US"
+     */
     locale?: string;
-}
+    /**
+     * Maximum number of decimal places to display.
+     * The formatter will round the number to this precision.
+     *
+     * @default 2
+     */
+    decimalPlaces?: number;
+    /**
+     * Whether to hide the units from the formatted value.
+     *
+     * @default false
+     */
+    hideUnits?: boolean;
+    /**
+     * Whether to space the units from the formatted value.
+     *
+     * @default false
+     */
+    unitsSpaced?: boolean;
+    /**
+     * Whether to use compact notation for the formatted value.
+     *
+     * @default false
+     */
+    compact?: boolean;
+    /**
+     * Placeholder text to return when value is undefined or null.
+     */
+    emptyPlaceholder?: string;
+    /**
+     * Whether to use grouping for the formatted value.
+     *
+     * @default true
+     */
+    useGrouping?: boolean;
+};
+
+/**
+ * Represents a numeric value that can be formatted with optional units.
+ *
+ * The value can be provided in two formats:
+ * - `value`: Direct numeric value (e.g., 123.45)
+ * - `value_x100`: Value stored as integer multiplied by 100 (e.g., 12345 represents 123.45)
+ *
+ * @example
+ * ```ts
+ * // Direct value
+ * const directValue: NumericValue = { value: 123.45, units: "€" }
+ *
+ * // Value stored as x100 (useful for avoiding floating point precision issues)
+ * const x100Value: NumericValue = { value_x100: 12345, units: "€" }
+ * ```
+ */
+declare type NumericValue = {
+    /**
+     * Optional unit string to append or prepend to the formatted number.
+     * Common examples: "€", "$", "kg", "%", etc.
+     */
+    units?: string;
+    /**
+     * Position of the units relative to the number.
+     * - "prepend": Units appear before the number (e.g., "$123.45")
+     * - "append": Units appear after the number (e.g., "123.45€")
+     *
+     * @default "append"
+     */
+    unitsPosition?: "prepend" | "append";
+} & ({
+    /**
+     * Direct numeric value to format.
+     */
+    value: number | undefined;
+} | {
+    /**
+     * Numeric value stored as an integer multiplied by 100.
+     * This format is useful for avoiding floating-point precision issues.
+     * The formatter will automatically divide by 100 before formatting.
+     *
+     * @example
+     * value_x100: 12345 represents 123.45
+     */
+    value_x100: number | undefined;
+});
+
+/**
+ * A numeric value that can be formatted with an optional formatter and options.
+ *
+ * @param value - The numeric value to format.
+ * @param formatter - The formatter to use.
+ * @param formatterOptions - The formatting options.
+ */
+declare type NumericWithFormatter = {
+    numericValue: NumericValue;
+    formatter?: NumericFormatter;
+    formatterOptions?: NumericFormatterOptions;
+};
 
 declare type OnBulkActionCallback<Record extends RecordType, Filters extends FiltersDefinition> = (...args: [
 action: BulkAction,
@@ -3788,6 +3919,14 @@ declare type RegularAction = BaseAction & {
     variant: ButtonVariant;
 };
 
+/**
+ * A numeric value that can be formatted with an optional formatter and options.
+ * This is a relaxed version of NumericWithFormatter that allows the numeric value to be a Numeric.
+ */
+declare type RelaxedNumericWithFormatter = Omit<NumericWithFormatter, "numericValue"> & {
+    numericValue: Numeric;
+};
+
 declare type RendererDefinition = ValueDisplayRendererDefinition;
 
 export declare type ResolvedRecordType<R> = R extends RecordType ? R : RecordType;
@@ -4095,13 +4234,16 @@ export declare type TagBalanceProps = {
      */
     nullText?: string;
     /**
-     * Amount to display next to the tag
+     * Value to display next to the tag can be a number, a Numeric or a NumericWithFormatter
      */
-    amount?: number | NumericValue | null;
+    amount: RelaxedNumericWithFormatter | Numeric;
 } & ({
-    percentage: number | Omit<NumericValue, "units" | "unitsPosition">;
+    percentage: (Omit<RelaxedNumericWithFormatter, "value"> & {
+        value: Omit<Numeric, "units" | "unitsPosition">;
+    }) | Omit<Numeric, "units" | "unitsPosition">;
 } | {
     percentage?: null;
+    formatterOptions?: undefined;
 });
 
 export declare interface TagCompanyProps {
@@ -4293,6 +4435,11 @@ declare type TranslationShape<T> = {
 
 export declare type TranslationsType = TranslationShape<typeof defaultTranslations>;
 
+export declare type TrendConfig = {
+    show?: boolean;
+    invertStatus?: boolean;
+};
+
 export declare const TwoColumnLayout: ForwardRefExoticComponent<Omit<TwoColumnLayoutProps & RefAttributes<HTMLDivElement>, "ref"> & RefAttributes<HTMLElement | SVGElement>>;
 
 export declare interface TwoColumnLayoutProps {
@@ -4802,6 +4949,11 @@ declare module "@tiptap/core" {
 }
 
 
+declare namespace Calendar {
+    var displayName: string;
+}
+
+
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
         moodTracker: {
@@ -4809,8 +4961,3 @@ declare module "@tiptap/core" {
         };
     }
 }
-
-
-declare namespace Calendar {
-    var displayName: string;
-}