@longline/aqua-ui 1.0.299 → 1.0.302

package/formatters/FilesizeFormatter/FilesizeFormatter.js

@@ -1,46 +1,65 @@
 import * as React from 'react';
 /**
- * `FilesizeFormatter` displays a human-readable file size string from a
- * number of bytes.
+ * Converts a byte count into a human-readable file size string with
+ * appropriate unit suffix.
  *
- * Supports SI (base 1000) and binary (base 1024) unit systems.
+ * Supports two unit systems:
+ * - **SI (default)**: Base 1000 (kB, MB, GB, TB, ...)
+ * - **Binary**: Base 1024 (KiB, MiB, GiB, TiB, ...)
  *
- * Localized formatting via `Intl.NumberFormat`.
+ * Use SI units for user-facing displays (matches how most operating systems
+ * report disk space). Use binary units for technical contexts where precise
+ * power-of-two values matter (e.g., RAM, disk sectors).
+ *
+ * ## Output Examples
+ *
+ * | Input | Props | Output |
+ * |-------|-------|--------|
+ * | `500` | (default) | `500 B` |
+ * | `10000` | (default) | `10 kB` |
+ * | `1048576` | `unit="binary"` | `1 MiB` |
+ * | `1500000000` | (default) | `1.5 GB` |
+ * | `1500000000` | `locale="de-DE"` | `1,5 GB` |
+ *
+ * ## Usage
  *
  * ```tsx
- * <FilesizeFormatter value={10000} unit="si" />        // "10.00 kB"
- * <FilesizeFormatter value={1048576} unit="binary" />  // "1.00 MiB"
- * <FilesizeFormatter value="2048000" locale="de-DE" /> // "2,05 MB"
+ * <FilesizeFormatter value={10000} />
+ * <FilesizeFormatter value={1048576} unit="binary" />
+ * <FilesizeFormatter value={2048000} locale="de-DE" />
  * ```
  */
 var FilesizeFormatter = function (_a) {
     var value = _a.value, _b = _a.unit, unit = _b === void 0 ? 'si' : _b, _c = _a.locale, locale = _c === void 0 ? 'en' : _c, _d = _a.decimals, decimals = _d === void 0 ? 2 : _d;
-    if (value == null)
-        return null;
-    var num = typeof value === 'string' ? parseFloat(value) : value;
-    if (isNaN(num))
-        return null;
-    var threshold = unit === 'si' ? 1000 : 1024;
-    var units = unit === 'si'
-        ? ['kB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB']
-        : ['KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB'];
-    if (Math.abs(num) < threshold) {
-        return "".concat(num, " B");
-    }
-    var size = num;
-    var u = -1;
-    do {
-        size /= threshold;
-        ++u;
-    } while (Math.abs(size) >= threshold && u < units.length - 1);
-    var formatter = new Intl.NumberFormat(locale, {
+    // Memoize the formatter to avoid creating a new instance on every render
+    var formatter = React.useMemo(function () { return new Intl.NumberFormat(locale, {
         maximumFractionDigits: decimals,
         minimumFractionDigits: 0,
-    });
-    return (React.createElement(React.Fragment, null,
-        formatter.format(size),
-        " ",
-        units[u]));
+    }); }, [locale, decimals]);
+    var formatted = React.useMemo(function () {
+        if (value == null)
+            return null;
+        var num = typeof value === 'string' ? parseFloat(value) : value;
+        if (isNaN(num))
+            return null;
+        var threshold = unit === 'si' ? 1000 : 1024;
+        var units = unit === 'si'
+            ? ['kB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB']
+            : ['KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB'];
+        if (Math.abs(num) < threshold) {
+            return "".concat(num, " B");
+        }
+        var size = num;
+        var u = -1;
+        do {
+            size /= threshold;
+            ++u;
+        } while (Math.abs(size) >= threshold && u < units.length - 1);
+        return "".concat(formatter.format(size), " ").concat(units[u]);
+    }, [value, unit, formatter]);
+    if (formatted === null)
+        return null;
+    return React.createElement(React.Fragment, null, formatted);
 };
 FilesizeFormatter.displayName = 'FilesizeFormatter';
 export { FilesizeFormatter };

package/formatters/GIS/CoordinateFormatter.d.ts

@@ -0,0 +1,58 @@
+import * as React from 'react';
+interface ICoordinateFormatterProps {
+    /**
+     * Value to format.
+     */
+    value: number | string;
+    /**
+     * Type of coordinate: 'latitude' or 'longitude'.
+     * Latitude values must be between -90 and 90 degrees.
+     * Longitude values must be between -180 and 180 degrees.
+     */
+    type: 'latitude' | 'longitude';
+    /**
+     * String to show if formatting fails.
+     * @default "(no coordinates)"
+     */
+    defaultStr?: string;
+}
+/**
+ * Formats decimal coordinates as degrees, minutes, and seconds (DMS).
+ *
+ * Converts fractional latitude/longitude values to the traditional DMS
+ * notation used in navigation and cartography (e.g., `34° 13′ 18″ N`).
+ *
+ * ## Valid Ranges
+ *
+ * - **Latitude**: -90 to 90 (negative = South, positive = North)
+ * - **Longitude**: -180 to 180 (negative = West, positive = East)
+ *
+ * Values outside these ranges return the fallback string.
+ *
+ * ## Output Examples
+ *
+ * | Value | Type | Output |
+ * |-------|------|--------|
+ * | `34.2216` | `latitude` | 34° 13′ 18″ N |
+ * | `-34.2216` | `latitude` | 34° 13′ 18″ S |
+ * | `-118.4848` | `longitude` | 118° 29′ 05″ W |
+ * | `139.6917` | `longitude` | 139° 41′ 30″ E |
+ * | `null` | any | (no coordinates) |
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * <CoordinateFormatter type="latitude" value={34.2216} />
+ * <CoordinateFormatter type="longitude" value={-118.4848} />
+ * <CoordinateFormatter type="latitude" value={null} defaultStr="N/A" />
+ * ```
+ *
+ * For convenience, you can also use the specialized wrappers:
+ * - `<LatitudeFormatter value={34.2216} />`
+ * - `<LongitudeFormatter value={-118.4848} />`
+ */
+declare const CoordinateFormatter: {
+    ({ value, type, defaultStr }: ICoordinateFormatterProps): React.JSX.Element;
+    displayName: string;
+};
+export { CoordinateFormatter, ICoordinateFormatterProps };

package/formatters/GIS/CoordinateFormatter.js

@@ -0,0 +1,51 @@
+import * as React from 'react';
+import { DMS } from '../../helper/DMS';
+var COORDINATE_CONFIG = {
+    latitude: { max: 90, positive: 'N', negative: 'S' },
+    longitude: { max: 180, positive: 'E', negative: 'W' }
+};
+/**
+ * Formats decimal coordinates as degrees, minutes, and seconds (DMS).
+ *
+ * Converts fractional latitude/longitude values to the traditional DMS
+ * notation used in navigation and cartography (e.g., `34° 13′ 18″ N`).
+ *
+ * ## Valid Ranges
+ *
+ * - **Latitude**: -90 to 90 (negative = South, positive = North)
+ * - **Longitude**: -180 to 180 (negative = West, positive = East)
+ *
+ * Values outside these ranges return the fallback string.
+ *
+ * ## Output Examples
+ *
+ * | Value | Type | Output |
+ * |-------|------|--------|
+ * | `34.2216` | `latitude` | 34° 13′ 18″ N |
+ * | `-34.2216` | `latitude` | 34° 13′ 18″ S |
+ * | `-118.4848` | `longitude` | 118° 29′ 05″ W |
+ * | `139.6917` | `longitude` | 139° 41′ 30″ E |
+ * | `null` | any | (no coordinates) |
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * <CoordinateFormatter type="latitude" value={34.2216} />
+ * <CoordinateFormatter type="longitude" value={-118.4848} />
+ * <CoordinateFormatter type="latitude" value={null} defaultStr="N/A" />
+ * ```
+ *
+ * For convenience, you can also use the specialized wrappers:
+ * - `<LatitudeFormatter value={34.2216} />`
+ * - `<LongitudeFormatter value={-118.4848} />`
+ */
+var CoordinateFormatter = function (_a) {
+    var value = _a.value, type = _a.type, _b = _a.defaultStr, defaultStr = _b === void 0 ? "(no coordinates)" : _b;
+    var config = COORDINATE_CONFIG[type];
+    var formatted = React.useMemo(function () {
+        return DMS.toDMSString(value, defaultStr, config.max, config.positive, config.negative);
+    }, [value, defaultStr, config]);
+    return React.createElement(React.Fragment, null, formatted);
+};
+CoordinateFormatter.displayName = "CoordinateFormatter";
+export { CoordinateFormatter };

package/formatters/GIS/LatitudeFormatter.d.ts

@@ -11,13 +11,14 @@ interface ILatitudeFormatterProps {
     defaultStr?: string;
 }
 /**
- * Formats a fractional latitude value as degrees, minutes and seconds (as a
- * string). If provided with a string, `LatitudeFormatter` will convert it to
- * a number first. Returns the fallback string if formatting fails or value
- * is out of range.
+ * Formats a fractional latitude value as degrees, minutes and seconds (DMS format).
+ * If provided with a string, `LatitudeFormatter` will convert it to a number first.
+ * Returns the fallback string if formatting fails or value is out of range.
  *
  * Latitude value must be between -90 and 90 degrees.
  *
+ * This is a convenience wrapper around `CoordinateFormatter` with `type="latitude"`.
+ *
  * ```tsx
  * <LatitudeFormatter value={34.2216}/>
  * <LatitudeFormatter value={null} defaultStr="Invalid latitude"/>

package/formatters/GIS/LatitudeFormatter.js

@@ -1,13 +1,14 @@
 import * as React from 'react';
-import { DMS } from '../../helper/DMS';
+import { CoordinateFormatter } from './CoordinateFormatter';
 /**
- * Formats a fractional latitude value as degrees, minutes and seconds (as a
- * string). If provided with a string, `LatitudeFormatter` will convert it to
- * a number first. Returns the fallback string if formatting fails or value
- * is out of range.
+ * Formats a fractional latitude value as degrees, minutes and seconds (DMS format).
+ * If provided with a string, `LatitudeFormatter` will convert it to a number first.
+ * Returns the fallback string if formatting fails or value is out of range.
  *
  * Latitude value must be between -90 and 90 degrees.
  *
+ * This is a convenience wrapper around `CoordinateFormatter` with `type="latitude"`.
+ *
  * ```tsx
  * <LatitudeFormatter value={34.2216}/>
  * <LatitudeFormatter value={null} defaultStr="Invalid latitude"/>
@@ -15,12 +16,7 @@ import { DMS } from '../../helper/DMS';
  */
 var LatitudeFormatter = function (_a) {
     var value = _a.value, _b = _a.defaultStr, defaultStr = _b === void 0 ? "(no coordinates)" : _b;
-    // Value and defaultStr and mostly stable. Memoize the formatted string to
-    // avoid unnecessary recalculations on every render.
-    var formatted = React.useMemo(function () {
-        return DMS.toDMSString(value, defaultStr, 90, "N", "S");
-    }, [value, defaultStr]);
-    return (React.createElement(React.Fragment, null, formatted));
+    return (React.createElement(CoordinateFormatter, { type: "latitude", value: value, defaultStr: defaultStr }));
 };
 LatitudeFormatter.displayName = "LatitudeFormatter";
 export { LatitudeFormatter };

package/formatters/GIS/LongitudeFormatter.d.ts

@@ -11,15 +11,18 @@ interface ILongitudeFormatterProps {
     defaultStr?: string;
 }
 /**
- * Formats a fractional longitude value as degrees, minutes and seconds (as a
- * string). If provided with a string, `LongitudeFormatter` will convert it to
- * a number first. Returns the fallback string if formatting fails or value is
- * out of range.
+ * Formats a fractional longitude value as degrees, minutes and seconds (DMS format).
+ * If provided with a string, `LongitudeFormatter` will convert it to a number first.
+ * Returns the fallback string if formatting fails or value is out of range.
+ *
+ * Longitude value must be between -180 and 180 degrees.
+ *
+ * This is a convenience wrapper around `CoordinateFormatter` with `type="longitude"`.
  *
  * ```tsx
- * <LongitudeFormatter value={34.2216}/>
+ * <LongitudeFormatter value={-118.4848}/>
  * <LongitudeFormatter value={null} defaultStr="Invalid longitude"/>
- * ```*
+ * ```
  */
 declare const LongitudeFormatter: {
     ({ value, defaultStr }: ILongitudeFormatterProps): React.JSX.Element;

package/formatters/GIS/LongitudeFormatter.js

@@ -1,24 +1,22 @@
 import * as React from 'react';
-import { DMS } from '../../helper/DMS';
+import { CoordinateFormatter } from './CoordinateFormatter';
 /**
- * Formats a fractional longitude value as degrees, minutes and seconds (as a
- * string). If provided with a string, `LongitudeFormatter` will convert it to
- * a number first. Returns the fallback string if formatting fails or value is
- * out of range.
+ * Formats a fractional longitude value as degrees, minutes and seconds (DMS format).
+ * If provided with a string, `LongitudeFormatter` will convert it to a number first.
+ * Returns the fallback string if formatting fails or value is out of range.
+ *
+ * Longitude value must be between -180 and 180 degrees.
+ *
+ * This is a convenience wrapper around `CoordinateFormatter` with `type="longitude"`.
  *
  * ```tsx
- * <LongitudeFormatter value={34.2216}/>
+ * <LongitudeFormatter value={-118.4848}/>
  * <LongitudeFormatter value={null} defaultStr="Invalid longitude"/>
- * ```*
+ * ```
  */
 var LongitudeFormatter = function (_a) {
     var value = _a.value, _b = _a.defaultStr, defaultStr = _b === void 0 ? "(no coordinates)" : _b;
-    // Value and defaultStr and mostly stable. Memoize the formatted string to
-    // avoid unnecessary recalculations on every render.
-    var formatted = React.useMemo(function () {
-        return DMS.toDMSString(value, defaultStr, 180, "E", "W");
-    }, [value, defaultStr]);
-    return (React.createElement(React.Fragment, null, formatted));
+    return (React.createElement(CoordinateFormatter, { type: "longitude", value: value, defaultStr: defaultStr }));
 };
 LongitudeFormatter.displayName = "LongitudeFormatter";
 export { LongitudeFormatter };

package/formatters/GIS/index.d.ts

@@ -1,2 +1,3 @@
+export * from './CoordinateFormatter';
 export * from './LatitudeFormatter';
 export * from './LongitudeFormatter';

package/formatters/GIS/index.js

@@ -1,2 +1,3 @@
+export * from './CoordinateFormatter';
 export * from './LatitudeFormatter';
 export * from './LongitudeFormatter';

package/formatters/HighlightFormatter/HighlightFormatter.d.ts

@@ -23,14 +23,35 @@ interface IHighlightFormatterProps {
     color?: string;
 }
 /**
- * Given an input string and a search query, `HighlightFormatter` highlights
- * the first occurrence or all occurrences (if any) of the search query and
- * returns a styled string (as a `ReactNode`). By default, matching is
- * case-insensitive, but this can be changed with the `caseSensitive` prop.
+ * Highlights search query matches within a string using a `<mark>` element.
+ *
+ * Useful for search result displays, autocomplete suggestions, or any UI
+ * where users need to see where their search term appears in text.
+ *
+ * By default, only the first match is highlighted and matching is
+ * case-insensitive. Special regex characters in the query are escaped
+ * automatically.
+ *
+ * ## Behavior
+ *
+ * - **No match**: Returns the original string unchanged
+ * - **Empty query**: Returns the original string unchanged
+ * - **Default color**: Uses theme's accent color for highlighting
+ *
+ * ## Usage
  *
  * ```tsx
- * <HighlightFormatter value="Hello, world" q="hello"/>
+ * // Basic (case-insensitive, first match only)
+ * <HighlightFormatter value="Hello, world" q="hello" />
+ *
+ * // Case-sensitive matching
  * <HighlightFormatter value="Hello, world" q="Hello" caseSensitive />
+ *
+ * // Highlight all occurrences
+ * <HighlightFormatter value="foo bar foo" q="foo" matchAll />
+ *
+ * // Custom highlight color
+ * <HighlightFormatter value="Important text" q="important" color="#ffeb3b" />
  * ```
  */
 declare const HighlightFormatter: {

package/formatters/HighlightFormatter/HighlightFormatter.js

@@ -1,14 +1,35 @@
 import * as React from 'react';
 import { useTheme } from 'styled-components';
 /**
- * Given an input string and a search query, `HighlightFormatter` highlights
- * the first occurrence or all occurrences (if any) of the search query and
- * returns a styled string (as a `ReactNode`). By default, matching is
- * case-insensitive, but this can be changed with the `caseSensitive` prop.
+ * Highlights search query matches within a string using a `<mark>` element.
+ *
+ * Useful for search result displays, autocomplete suggestions, or any UI
+ * where users need to see where their search term appears in text.
+ *
+ * By default, only the first match is highlighted and matching is
+ * case-insensitive. Special regex characters in the query are escaped
+ * automatically.
+ *
+ * ## Behavior
+ *
+ * - **No match**: Returns the original string unchanged
+ * - **Empty query**: Returns the original string unchanged
+ * - **Default color**: Uses theme's accent color for highlighting
+ *
+ * ## Usage
  *
  * ```tsx
- * <HighlightFormatter value="Hello, world" q="hello"/>
+ * // Basic (case-insensitive, first match only)
+ * <HighlightFormatter value="Hello, world" q="hello" />
+ *
+ * // Case-sensitive matching
  * <HighlightFormatter value="Hello, world" q="Hello" caseSensitive />
+ *
+ * // Highlight all occurrences
+ * <HighlightFormatter value="foo bar foo" q="foo" matchAll />
+ *
+ * // Custom highlight color
+ * <HighlightFormatter value="Important text" q="important" color="#ffeb3b" />
  * ```
  */
 var HighlightFormatter = function (_a) {

package/formatters/HttpStatusFormatter/HttpStatusFormatter.d.ts

@@ -1,4 +1,5 @@
-interface IProps {
+import * as React from 'react';
+interface IHttpStatusFormatterProps {
     /**
      * HTTP status code, e.g. 503
      */
@@ -11,17 +12,36 @@ interface IProps {
     type?: 'title' | 'description';
 }
 /**
- * This formatter converts a HTTP status code to either a short title
- * (e.g. status 503 would be "Service unavailable") or a long description
- * (e.g. status 503 would be "The server is not ready to handle the request.
- * Common causes are a server that is down for maintenance or that is
- * overloaded. Note that together with this response, a user-friendly page
- * explaining the problem should be sent. This response should be used for
- * temporary conditions and the Retry-After HTTP header should, if possible,
- * contain the estimated time before the recovery of the service. The
- * webmaster must also take care about the caching-related headers that are
- * sent along with this response, as these temporary condition responses
- * should usually not be cached.").
+ * Converts an HTTP status code to a human-readable title or description.
+ *
+ * Useful for displaying user-friendly error messages in API response
+ * handlers, error boundaries, or status dashboards.
+ *
+ * Supports all standard HTTP status codes (1xx-5xx). Unknown codes
+ * return "Unknown error".
+ *
+ * ## Output Examples
+ *
+ * | status | type | Output |
+ * |--------|------|--------|
+ * | `200` | `title` | OK |
+ * | `404` | `title` | Resource not found |
+ * | `404` | `description` | The requested resource could not be found on the server. |
+ * | `500` | `title` | Internal server error |
+ * | `503` | `title` | Service unavailable |
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * // Short title (default)
+ * <HttpStatusFormatter status={404} />
+ *
+ * // Full description
+ * <HttpStatusFormatter status={503} type="description" />
+ * ```
  */
-declare const HttpStatusFormatter: (props: IProps) => string;
-export { HttpStatusFormatter };
+declare const HttpStatusFormatter: {
+    ({ status, type }: IHttpStatusFormatterProps): React.JSX.Element;
+    displayName: string;
+};
+export { HttpStatusFormatter, IHttpStatusFormatterProps };

package/formatters/HttpStatusFormatter/HttpStatusFormatter.js

@@ -1,3 +1,4 @@
+import * as React from 'react';
 var HttpStatusCodes = {
     100: {
         header: "Continue",
@@ -253,22 +254,40 @@ var HttpStatusCodes = {
     }
 };
 /**
- * This formatter converts a HTTP status code to either a short title
- * (e.g. status 503 would be "Service unavailable") or a long description
- * (e.g. status 503 would be "The server is not ready to handle the request.
- * Common causes are a server that is down for maintenance or that is
- * overloaded. Note that together with this response, a user-friendly page
- * explaining the problem should be sent. This response should be used for
- * temporary conditions and the Retry-After HTTP header should, if possible,
- * contain the estimated time before the recovery of the service. The
- * webmaster must also take care about the caching-related headers that are
- * sent along with this response, as these temporary condition responses
- * should usually not be cached.").
+ * Converts an HTTP status code to a human-readable title or description.
+ *
+ * Useful for displaying user-friendly error messages in API response
+ * handlers, error boundaries, or status dashboards.
+ *
+ * Supports all standard HTTP status codes (1xx-5xx). Unknown codes
+ * return "Unknown error".
+ *
+ * ## Output Examples
+ *
+ * | status | type | Output |
+ * |--------|------|--------|
+ * | `200` | `title` | OK |
+ * | `404` | `title` | Resource not found |
+ * | `404` | `description` | The requested resource could not be found on the server. |
+ * | `500` | `title` | Internal server error |
+ * | `503` | `title` | Service unavailable |
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * // Short title (default)
+ * <HttpStatusFormatter status={404} />
+ *
+ * // Full description
+ * <HttpStatusFormatter status={503} type="description" />
+ * ```
  */
-var HttpStatusFormatter = function (props) {
-    var status = HttpStatusCodes[props.status];
-    if (!status)
-        return "Unknown error";
-    return props.type === 'description' ? status.desc : status.header;
+var HttpStatusFormatter = function (_a) {
+    var status = _a.status, _b = _a.type, type = _b === void 0 ? 'title' : _b;
+    var statusInfo = HttpStatusCodes[status];
+    if (!statusInfo)
+        return React.createElement(React.Fragment, null, "Unknown error");
+    return React.createElement(React.Fragment, null, type === 'description' ? statusInfo.desc : statusInfo.header);
 };
+HttpStatusFormatter.displayName = 'HttpStatusFormatter';
 export { HttpStatusFormatter };

package/formatters/HumanFormatter/HumanFormatter.d.ts

@@ -14,12 +14,32 @@ interface IHumanFormatterProps {
     decimals?: number;
 }
 /**
- * `HumanFormatter` formats large numbers using `Intl.NumberFormat` for
- * locale-aware output and optional compact display (e.g. "10K", "1.2M").
+ * Abbreviates large numbers using compact notation (K, M, B, etc.).
+ *
+ * Use `HumanFormatter` for dashboard metrics, social media counts, or any
+ * context where approximate magnitude matters more than precision. For
+ * exact values with thousands separators, use `NumberFormatter` instead.
+ *
+ * Compact notation is locale-aware: German uses "Mio." for millions,
+ * while English uses "M".
+ *
+ * ## Output Examples
+ *
+ * | Input | Props | Output |
+ * |-------|-------|--------|
+ * | `999` | (default) | `999` |
+ * | `1200` | (default) | `1K` |
+ * | `1200` | `decimals={1}` | `1.2K` |
+ * | `1500000` | (default) | `2M` |
+ * | `1500000` | `locale="de-DE"` | `2 Mio.` |
+ * | `2500000000` | (default) | `3B` |
+ *
+ * ## Usage
  *
  * ```tsx
- * <HumanFormatter value={1200}/>                   // => "1.2K"
- * <HumanFormatter value={999999} locale="de-DE" /> // => "1 Mio."
+ * <HumanFormatter value={1200} />
+ * <HumanFormatter value={1500000} decimals={1} />
+ * <HumanFormatter value={999999} locale="de-DE" />
  * ```
  */
 declare const HumanFormatter: {

package/formatters/HumanFormatter/HumanFormatter.js

@@ -1,25 +1,50 @@
 import * as React from 'react';
 /**
- * `HumanFormatter` formats large numbers using `Intl.NumberFormat` for
- * locale-aware output and optional compact display (e.g. "10K", "1.2M").
+ * Abbreviates large numbers using compact notation (K, M, B, etc.).
+ *
+ * Use `HumanFormatter` for dashboard metrics, social media counts, or any
+ * context where approximate magnitude matters more than precision. For
+ * exact values with thousands separators, use `NumberFormatter` instead.
+ *
+ * Compact notation is locale-aware: German uses "Mio." for millions,
+ * while English uses "M".
+ *
+ * ## Output Examples
+ *
+ * | Input | Props | Output |
+ * |-------|-------|--------|
+ * | `999` | (default) | `999` |
+ * | `1200` | (default) | `1K` |
+ * | `1200` | `decimals={1}` | `1.2K` |
+ * | `1500000` | (default) | `2M` |
+ * | `1500000` | `locale="de-DE"` | `2 Mio.` |
+ * | `2500000000` | (default) | `3B` |
+ *
+ * ## Usage
  *
  * ```tsx
- * <HumanFormatter value={1200}/>                   // => "1.2K"
- * <HumanFormatter value={999999} locale="de-DE" /> // => "1 Mio."
+ * <HumanFormatter value={1200} />
+ * <HumanFormatter value={1500000} decimals={1} />
+ * <HumanFormatter value={999999} locale="de-DE" />
  * ```
  */
 var HumanFormatter = function (_a) {
     var value = _a.value, _b = _a.locale, locale = _b === void 0 ? 'en' : _b, _c = _a.decimals, decimals = _c === void 0 ? 0 : _c;
-    if (value == null)
-        return null;
-    var num = typeof value === 'string' ? parseFloat(value) : value;
-    if (isNaN(num))
-        return null;
-    var formatOptions = {
+    // Memoize the formatter to avoid creating a new instance on every render
+    var formatter = React.useMemo(function () { return new Intl.NumberFormat(locale, {
         notation: 'compact',
         maximumFractionDigits: decimals
-    };
-    var formatted = new Intl.NumberFormat(locale, formatOptions).format(num);
+    }); }, [locale, decimals]);
+    var formatted = React.useMemo(function () {
+        if (value == null)
+            return null;
+        var num = typeof value === 'string' ? parseFloat(value) : value;
+        if (isNaN(num))
+            return null;
+        return formatter.format(num);
+    }, [value, formatter]);
+    if (formatted === null)
+        return null;
     return React.createElement(React.Fragment, null, formatted);
 };
 HumanFormatter.displayName = 'HumanFormatter';