@tempots/beatui 0.82.1 → 0.83.0

package/dist/types/utils/color.d.ts

@@ -1,54 +1,126 @@
 /**
- * Color validation utilities for BeatUI color inputs
+ * Color validation, conversion, and formatting utilities for BeatUI.
+ *
+ * Provides comprehensive color handling including validation for multiple color
+ * formats (hex, RGB, RGBA, HSL), conversion between color spaces (RGB, HSL, HWB,
+ * OKLCH), contrast ratio calculation, and color string formatting.
+ *
+ * @module
  */
 /**
- * Validates if a string is a valid hex color
+ * Validates if a string is a valid hex color (3 or 6 character format, with or without `#`).
+ *
  * @param color - The color string to validate
- * @returns true if valid hex color, false otherwise
+ * @returns `true` if valid hex color, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isValidHexColor('#ff0000') // true
+ * isValidHexColor('abc')     // true
+ * isValidHexColor('#gggggg') // false
+ * ```
  */
 export declare function isValidHexColor(color: string): boolean;
 /**
- * Validates if a string is a valid RGB color
- * @param color - The color string to validate (e.g., "rgb(255, 0, 0)")
- * @returns true if valid RGB color, false otherwise
+ * Validates if a string is a valid CSS `rgb()` color with values in range 0-255.
+ *
+ * @param color - The color string to validate (e.g., `"rgb(255, 0, 0)"`)
+ * @returns `true` if valid RGB color, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isValidRgbColor('rgb(255, 0, 0)')   // true
+ * isValidRgbColor('rgb(300, 0, 0)')   // false (out of range)
+ * isValidRgbColor('rgba(0, 0, 0, 1)') // false (use isValidRgbaColor)
+ * ```
  */
 export declare function isValidRgbColor(color: string): boolean;
 /**
- * Validates if a string is a valid RGBA color
- * @param color - The color string to validate (e.g., "rgba(255, 0, 0, 0.5)")
- * @returns true if valid RGBA color, false otherwise
+ * Validates if a string is a valid CSS `rgba()` color with values in range
+ * 0-255 for RGB and 0-1 for alpha.
+ *
+ * @param color - The color string to validate (e.g., `"rgba(255, 0, 0, 0.5)"`)
+ * @returns `true` if valid RGBA color, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isValidRgbaColor('rgba(255, 0, 0, 0.5)') // true
+ * isValidRgbaColor('rgba(255, 0, 0, 2)')   // false (alpha out of range)
+ * ```
  */
 export declare function isValidRgbaColor(color: string): boolean;
 /**
- * Validates if a string is a valid HSL color
- * @param color - The color string to validate (e.g., "hsl(120, 100%, 50%)")
- * @returns true if valid HSL color, false otherwise
+ * Validates if a string is a valid CSS `hsl()` color with hue 0-360 and
+ * saturation/lightness 0-100%.
+ *
+ * @param color - The color string to validate (e.g., `"hsl(120, 100%, 50%)"`)
+ * @returns `true` if valid HSL color, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isValidHslColor('hsl(120, 100%, 50%)') // true
+ * isValidHslColor('hsl(400, 100%, 50%)') // false (hue out of range)
+ * ```
  */
 export declare function isValidHslColor(color: string): boolean;
 /**
- * Validates if a string is any valid color format
+ * Validates if a string is a valid color in any supported format
+ * (hex, RGB, RGBA, or HSL).
+ *
  * @param color - The color string to validate
- * @returns true if valid color in any supported format, false otherwise
+ * @returns `true` if valid color in any supported format, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isValidColor('#ff0000')            // true
+ * isValidColor('rgb(255, 0, 0)')     // true
+ * isValidColor('not-a-color')        // false
+ * ```
  */
 export declare function isValidColor(color: string): boolean;
 /**
- * Normalizes a hex color to always include the # prefix and be 6 characters
+ * Normalizes a hex color to always include the `#` prefix and be 6 characters
+ * (lowercase). Expands 3-character shorthand to full 6-character form.
+ *
  * @param color - The hex color to normalize
- * @returns normalized hex color or null if invalid
+ * @returns Normalized hex color string (e.g., `'#ff0000'`) or `null` if invalid
+ *
+ * @example
+ * ```ts
+ * normalizeHexColor('abc')     // '#aabbcc'
+ * normalizeHexColor('#FF0000') // '#ff0000'
+ * normalizeHexColor('invalid') // null
+ * ```
  */
 export declare function normalizeHexColor(color: string): string | null;
 /**
- * Converts RGB values to hex color
- * @param r - Red value (0-255)
- * @param g - Green value (0-255)
- * @param b - Blue value (0-255)
- * @returns hex color string
+ * Converts RGB channel values to a hex color string. Values are clamped to 0-255.
+ *
+ * @param r - Red channel value (0-255)
+ * @param g - Green channel value (0-255)
+ * @param b - Blue channel value (0-255)
+ * @returns Hex color string with `#` prefix (e.g., `'#ff0000'`)
+ *
+ * @example
+ * ```ts
+ * rgbToHex(255, 0, 0)   // '#ff0000'
+ * rgbToHex(0, 128, 255)  // '#0080ff'
+ * ```
  */
 export declare function rgbToHex(r: number, g: number, b: number): string;
 /**
- * Converts hex color to RGB values
- * @param hex - Hex color string (with or without #)
- * @returns RGB values object or null if invalid
+ * Converts a hex color string to RGB channel values. Handles both 3-character
+ * and 6-character hex values, with or without the `#` prefix.
+ *
+ * @param hex - Hex color string (with or without `#`)
+ * @returns Object with `r`, `g`, `b` properties (0-255 each) or `null` if invalid
+ *
+ * @example
+ * ```ts
+ * hexToRgb('#ff0000') // { r: 255, g: 0, b: 0 }
+ * hexToRgb('abc')     // { r: 170, g: 187, b: 204 }
+ * hexToRgb('invalid') // null
+ * ```
  */
 export declare function hexToRgb(hex: string): {
     r: number;
@@ -56,22 +128,219 @@ export declare function hexToRgb(hex: string): {
     b: number;
 } | null;
 /**
- * Gets the contrast ratio between two colors
- * @param color1 - First color (hex format)
- * @param color2 - Second color (hex format)
- * @returns contrast ratio or null if invalid colors
+ * Calculates the WCAG 2.0 contrast ratio between two hex colors.
+ * The ratio ranges from 1:1 (identical) to 21:1 (black on white).
+ * A ratio of at least 4.5 is required for WCAG AA text compliance.
+ *
+ * @param color1 - First color in hex format
+ * @param color2 - Second color in hex format
+ * @returns The contrast ratio as a number, or `null` if either color is invalid
+ *
+ * @example
+ * ```ts
+ * getContrastRatio('#000000', '#ffffff') // 21
+ * getContrastRatio('#ff0000', '#00ff00') // ~2.91
+ * ```
  */
 export declare function getContrastRatio(color1: string, color2: string): number | null;
+/**
+ * Parses any supported CSS color string into an `[r, g, b, a]` tuple.
+ *
+ * Supported formats:
+ * - Hex: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA` (with or without `#`)
+ * - RGB: `rgb(r, g, b)`
+ * - RGBA: `rgba(r, g, b, a)`
+ * - HSL/HSLA: `hsl(h, s%, l%)`, `hsla(h, s%, l%, a)`, and modern syntax
+ * - HWB: `hwb(h w% b% / a)`
+ * - OKLCH: `oklch(L C h / a)`
+ *
+ * @param v - The color string to parse
+ * @returns A tuple of `[red, green, blue, alpha]` where RGB are 0-255 and alpha is 0-1.
+ *   Returns `[0, 0, 0, 1]` for empty or unparseable input.
+ *
+ * @example
+ * ```ts
+ * parseAnyColor('#ff0000')             // [255, 0, 0, 1]
+ * parseAnyColor('rgba(0, 128, 255, 0.5)') // [0, 128, 255, 0.5]
+ * parseAnyColor('oklch(0.623 0.214 259.815)') // [approximately 59, 130, 246, 1]
+ * ```
+ */
 export declare function parseAnyColor(v: string): [number, number, number, number];
+/**
+ * Formats RGBA values into a CSS `rgba()` string. Alpha is clamped to 0-1
+ * and rounded to 2 decimal places; RGB values are rounded to integers.
+ *
+ * @param r - Red channel (0-255)
+ * @param g - Green channel (0-255)
+ * @param b - Blue channel (0-255)
+ * @param a - Alpha channel (0-1)
+ * @returns A CSS `rgba()` string (e.g., `'rgba(255, 0, 0, 0.5)'`)
+ *
+ * @example
+ * ```ts
+ * toRgbaString(255, 0, 0, 0.5) // 'rgba(255, 0, 0, 0.5)'
+ * ```
+ */
 export declare function toRgbaString(r: number, g: number, b: number, a: number): string;
+/**
+ * Creates a seeded pseudo-random number generator using the Mulberry32 algorithm.
+ * Useful for generating deterministic "random" values (e.g., for color hashing).
+ *
+ * @param seed - The integer seed value
+ * @returns A function that returns the next pseudo-random number in the range [0, 1)
+ *
+ * @example
+ * ```ts
+ * const random = mulberry32(42)
+ * random() // 0.6011037519201636 (deterministic)
+ * random() // 0.4321023514959961
+ * ```
+ */
 export declare function mulberry32(seed: number): () => number;
+/**
+ * Converts HSL color values to RGB. Hue is wrapped to 0-360 range.
+ *
+ * @param h - Hue in degrees (0-360)
+ * @param s - Saturation as a fraction (0-1)
+ * @param l - Lightness as a fraction (0-1)
+ * @returns A tuple of `[red, green, blue]` with values 0-255
+ *
+ * @example
+ * ```ts
+ * hslToRgb(0, 1, 0.5)   // [255, 0, 0] (red)
+ * hslToRgb(120, 1, 0.5)  // [0, 255, 0] (green)
+ * ```
+ */
 export declare function hslToRgb(h: number, s: number, l: number): [number, number, number];
+/**
+ * Converts HWB (Hue-Whiteness-Blackness) color values to RGB.
+ * If whiteness + blackness exceeds 1, they are scaled proportionally.
+ *
+ * @param h - Hue in degrees (0-360)
+ * @param w - Whiteness as a fraction (0-1)
+ * @param bl - Blackness as a fraction (0-1)
+ * @returns A tuple of `[red, green, blue]` with values 0-255
+ *
+ * @example
+ * ```ts
+ * hwbToRgb(0, 0, 0)     // [255, 0, 0] (pure red)
+ * hwbToRgb(0, 0.5, 0.5) // [128, 128, 128] (gray)
+ * ```
+ */
 export declare function hwbToRgb(h: number, w: number, bl: number): [number, number, number];
+/**
+ * Converts RGB color values to HSL. Returns rounded integer values.
+ *
+ * @param r - Red channel (0-255)
+ * @param g - Green channel (0-255)
+ * @param b - Blue channel (0-255)
+ * @returns A tuple of `[hue, saturation, lightness]` where hue is 0-360 and
+ *   saturation/lightness are 0-100 (percentage)
+ *
+ * @example
+ * ```ts
+ * rgbToHsl(255, 0, 0)   // [0, 100, 50]
+ * rgbToHsl(0, 128, 255)  // [210, 100, 50]
+ * ```
+ */
 export declare function rgbToHsl(r: number, g: number, b: number): [number, number, number];
+/**
+ * Converts RGB color values to HWB (Hue-Whiteness-Blackness).
+ *
+ * @param r - Red channel (0-255)
+ * @param g - Green channel (0-255)
+ * @param b - Blue channel (0-255)
+ * @returns A tuple of `[hue, whiteness, blackness]` where hue is 0-360 and
+ *   whiteness/blackness are 0-100 (percentage)
+ *
+ * @example
+ * ```ts
+ * rgbToHwb(255, 0, 0)   // [0, 0, 0]
+ * rgbToHwb(128, 128, 128) // [0, 50, 50]
+ * ```
+ */
 export declare function rgbToHwb(r: number, g: number, b: number): [number, number, number];
+/**
+ * Converts an sRGB channel value (0-255) to linear RGB (0-1).
+ * Applies the standard sRGB gamma decompression curve.
+ *
+ * @param u - sRGB channel value (0-255)
+ * @returns Linear RGB value (0-1)
+ */
 export declare function srgbToLinear(u: number): number;
+/**
+ * Converts a linear RGB value (0-1) to an sRGB channel value (0-255).
+ * Applies the standard sRGB gamma compression curve, clamping and rounding the result.
+ *
+ * @param u - Linear RGB value (0-1)
+ * @returns sRGB channel value (0-255)
+ */
 export declare function linearToSrgb(u: number): number;
+/**
+ * Converts OKLCH color values to sRGB. Uses the OKLab intermediate color space
+ * with matrix transforms to linear sRGB.
+ *
+ * @param L - Lightness (0-1)
+ * @param C - Chroma (0 to approximately 0.4)
+ * @param hDeg - Hue angle in degrees (0-360)
+ * @returns A tuple of `[red, green, blue]` with values 0-255
+ *
+ * @example
+ * ```ts
+ * oklchToRgb(0.623, 0.214, 259.815) // approximately [59, 130, 246] (blue-500)
+ * ```
+ */
 export declare function oklchToRgb(L: number, C: number, hDeg: number): [number, number, number];
+/**
+ * Converts sRGB color values to OKLCH color space.
+ *
+ * @param r - Red channel (0-255)
+ * @param g - Green channel (0-255)
+ * @param b - Blue channel (0-255)
+ * @returns A tuple of `[lightness, chroma, hue]` where lightness is 0-1,
+ *   chroma is 0 to ~0.4, and hue is 0-360 degrees
+ *
+ * @example
+ * ```ts
+ * rgbToOklch(59, 130, 246) // approximately [0.623, 0.214, 259.815]
+ * ```
+ */
 export declare function rgbToOklch(r: number, g: number, b: number): [number, number, number];
+/**
+ * Formats RGBA color values into a CSS color string in the specified format.
+ *
+ * @param r - Red channel (0-255)
+ * @param g - Green channel (0-255)
+ * @param b - Blue channel (0-255)
+ * @param a - Alpha channel (0-1)
+ * @param fmt - The output format: `'hex'`, `'rgb'`, `'rgba'`, `'hsl'`, `'hsla'`, `'hwb'`, or `'oklch'`
+ * @param alphaEnabled - Whether to include alpha in formats that support it (hex, oklch)
+ * @returns A CSS color string in the requested format
+ *
+ * @example
+ * ```ts
+ * formatColor(255, 0, 0, 1, 'hex')           // '#ff0000'
+ * formatColor(255, 0, 0, 0.5, 'hex', true)   // '#ff000080'
+ * formatColor(255, 0, 0, 1, 'hsl')           // 'hsl(0, 100%, 50%)'
+ * formatColor(255, 0, 0, 1, 'oklch')         // 'oklch(0.628 0.258 29.2)'
+ * ```
+ */
 export declare function formatColor(r: number, g: number, b: number, a: number, fmt: 'hex' | 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'hwb' | 'oklch', alphaEnabled?: boolean): string;
+/**
+ * Resolves the effective color format based on whether alpha is enabled.
+ * When alpha is enabled, `'rgb'` becomes `'rgba'` and `'hsl'` becomes `'hsla'`.
+ * When alpha is disabled, `'rgba'` becomes `'rgb'` and `'hsla'` becomes `'hsl'`.
+ * Other formats (hex, hwb, oklch) are returned unchanged.
+ *
+ * @param fmt - The requested color format
+ * @param alphaEnabled - Whether alpha channel is enabled
+ * @returns The resolved effective color format
+ *
+ * @example
+ * ```ts
+ * resolveEffectiveFormat('rgb', true)   // 'rgba'
+ * resolveEffectiveFormat('rgba', false) // 'rgb'
+ * resolveEffectiveFormat('hex', true)   // 'hex'
+ * ```
+ */
 export declare function resolveEffectiveFormat(fmt: 'hex' | 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'hwb' | 'oklch', alphaEnabled: boolean): 'hex' | 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'hwb' | 'oklch';

package/dist/types/utils/download.d.ts

@@ -1,24 +1,116 @@
+/**
+ * File download utilities for BeatUI.
+ *
+ * Provides functions for downloading files from URLs, creating downloads from
+ * in-memory content, and monitoring download progress with reactive signals.
+ *
+ * @module
+ */
 import { Signal } from '@tempots/dom';
+/**
+ * Represents an in-progress download with a known content length.
+ */
 export interface Progress {
+    /** Discriminant for the `DownloadResult` union. */
     type: 'progress';
+    /** Download progress as a fraction from 0 to 1. */
     value: number;
 }
+/**
+ * Represents an in-progress download with an unknown content length.
+ */
 export interface Undetermined {
+    /** Discriminant for the `DownloadResult` union. */
     type: 'undetermined';
 }
+/**
+ * Represents a completed download with the resulting file.
+ */
 export interface Done {
+    /** Discriminant for the `DownloadResult` union. */
     type: 'done';
+    /** The downloaded file. */
     file: File;
 }
+/**
+ * Represents a failed download with the error that occurred.
+ */
 export interface DownloadError {
+    /** Discriminant for the `DownloadResult` union. */
     type: 'error';
+    /** The error that caused the download failure. */
     error: Error;
 }
+/**
+ * Discriminated union representing the current state of a monitored download.
+ * Use the `type` property to determine the current state.
+ */
 export type DownloadResult = Progress | Undetermined | Done | DownloadError;
+/**
+ * Downloads a file from a URL and triggers a browser download dialog.
+ * Falls back to opening the URL in a new tab if the fetch fails (e.g., due to CORS).
+ *
+ * @param url - The URL to download from
+ * @param filename - The suggested filename for the download
+ * @default filename ''
+ *
+ * @example
+ * ```ts
+ * await downloadUrl('https://example.com/file.pdf', 'document.pdf')
+ * ```
+ */
 export declare const downloadUrl: (url: string, filename?: string) => Promise<void>;
+/**
+ * Creates a browser download from in-memory content (string or binary data).
+ *
+ * @param content - The content to download, either a string or a `Uint8Array`
+ * @param filename - The suggested filename for the download
+ * @param type - The MIME type of the content
+ * @default type 'application/octet-stream'
+ *
+ * @example
+ * ```ts
+ * downloadContent('Hello, world!', 'hello.txt', 'text/plain')
+ * downloadContent(new Uint8Array([0x89, 0x50, 0x4e, 0x47]), 'image.png', 'image/png')
+ * ```
+ */
 export declare const downloadContent: (content: string | Uint8Array<ArrayBuffer>, filename: string, type?: string) => void;
+/**
+ * Downloads a file from a URL while providing real-time progress monitoring
+ * through a reactive signal. Returns both the progress signal and a cancel function.
+ *
+ * The signal emits:
+ * - `{ type: 'progress', value: 0..1 }` when content length is known
+ * - `{ type: 'undetermined' }` when content length is unknown
+ * - `{ type: 'done', file }` on successful completion
+ * - `{ type: 'error', error }` on failure
+ *
+ * @param url - The URL to download from
+ * @returns An object with a `signal` for monitoring progress and a `cancel` function to abort
+ *
+ * @example
+ * ```ts
+ * const { signal, cancel } = downloadUrlAndMonitor('https://example.com/large-file.zip')
+ * signal.on(result => {
+ *   if (result.type === 'progress') console.log(`${result.value * 100}%`)
+ *   if (result.type === 'done') downloadFile(result.file)
+ * })
+ * // To cancel: cancel()
+ * ```
+ */
 export declare const downloadUrlAndMonitor: (url: string) => {
     signal: Signal<DownloadResult>;
     cancel: () => void;
 };
+/**
+ * Triggers a browser download dialog for a `File` object.
+ *
+ * @param file - The `File` object to download
+ *
+ * @example
+ * ```ts
+ * const file = new File(['content'], 'example.txt', { type: 'text/plain' })
+ * downloadFile(file)
+ * ```
+ */
 export declare const downloadFile: (file: File) => void;

package/dist/types/utils/focus-trap.d.ts

@@ -1,30 +1,86 @@
+/**
+ * Focus trap utilities for BeatUI.
+ *
+ * Provides a focus trap implementation that constrains keyboard focus within
+ * a container element. Supports Tab/Shift+Tab cycling, Escape key handling,
+ * click-outside detection, initial focus targeting, and focus restoration
+ * on deactivation. Integrates with the `@tempots/dom` reactive rendering system.
+ *
+ * @module
+ */
 import { Renderable } from '@tempots/dom';
 /**
- * Focus trap options
+ * Configuration options for the focus trap behavior.
  */
 export interface FocusTrapOptions {
-    /** Whether the focus trap is active */
+    /**
+     * Whether the focus trap is active.
+     * @default true
+     */
     active?: boolean;
-    /** Whether to handle escape key */
+    /**
+     * Whether pressing Escape deactivates the focus trap.
+     * @default true
+     */
     escapeDeactivates?: boolean;
-    /** Callback when escape key is pressed */
+    /** Callback invoked when the Escape key is pressed (if `escapeDeactivates` is true). */
     onEscape?: () => void;
-    /** Element to focus initially (if not provided, focuses first focusable element) */
+    /**
+     * Element to receive initial focus when the trap activates.
+     * Can be an `HTMLElement` or a function returning one.
+     * If not provided, the first focusable element in the container is focused.
+     */
     initialFocus?: HTMLElement | (() => HTMLElement | null);
-    /** Element to return focus to when trap is deactivated */
+    /**
+     * Element to return focus to when the trap is deactivated.
+     * Can be an `HTMLElement` or a function returning one.
+     * If not provided, focus returns to the element that was focused before activation.
+     */
     returnFocus?: HTMLElement | (() => HTMLElement | null);
-    /** Whether to prevent outside clicks */
+    /**
+     * Whether clicking outside the container triggers deactivation.
+     * @default false
+     */
     clickOutsideDeactivates?: boolean;
-    /** Callback when clicking outside */
+    /** Callback invoked when a click occurs outside the container (if `clickOutsideDeactivates` is true). */
     onClickOutside?: () => void;
 }
 /**
- * Creates a focus trap within an element
- * Returns a TNode that should be added to the container element
+ * Creates a focus trap `Renderable` that constrains keyboard focus within
+ * the parent container element. When added to a container, it intercepts
+ * Tab/Shift+Tab navigation to cycle through focusable children, optionally
+ * handles Escape key, and restores focus on disposal.
+ *
+ * @param options - Configuration for the focus trap behavior
+ * @returns A `Renderable` that should be included as a child of the container element
+ *
+ * @example
+ * ```ts
+ * html.div(
+ *   FocusTrap({
+ *     escapeDeactivates: true,
+ *     onEscape: () => closeDialog(),
+ *   }),
+ *   html.button('Close'),
+ *   html.input({ type: 'text' }),
+ * )
+ * ```
  */
 export declare function FocusTrap(options?: FocusTrapOptions): Renderable;
 /**
- * Hook for managing focus trap state
+ * Creates a focus trap controller with `activate` and `deactivate` methods.
+ * Each call to `activate()` or `deactivate()` returns a new `Renderable`
+ * configured with the provided options.
+ *
+ * @param options - Configuration for the focus trap behavior
+ * @returns An object with `activate` and `deactivate` methods that return `Renderable` instances
+ *
+ * @example
+ * ```ts
+ * const trap = useFocusTrap({ onEscape: () => console.log('escaped') })
+ * // trap.activate() returns a Renderable with active=true
+ * // trap.deactivate() returns a Renderable with active=false
+ * ```
  */
 export declare function useFocusTrap(options?: FocusTrapOptions): {
     activate: () => Renderable;

package/dist/types/utils/format-file-size.d.ts

@@ -1,6 +1,50 @@
+/**
+ * File size formatting utilities for BeatUI.
+ *
+ * Provides human-readable file size formatting with locale-aware number formatting,
+ * configurable units, and support for both `number` and `bigint` inputs.
+ *
+ * @module
+ */
+/**
+ * Options for configuring file size formatting behavior.
+ */
 export type FormatFileSizeOptions = {
+    /**
+     * Array of unit labels from smallest to largest.
+     * @default ['B', 'KB', 'MB', 'GB', 'TB']
+     */
     units?: string[];
+    /**
+     * Number of decimal places to show for values above bytes.
+     * @default 0
+     */
     decimalPlaces?: number;
+    /**
+     * BCP 47 locale string for number formatting (e.g., `'en-US'`, `'de-DE'`).
+     * Uses the browser default locale if not specified.
+     */
     locale?: string;
 };
+/**
+ * Formats a byte count into a human-readable file size string using
+ * `Intl.NumberFormat` for locale-aware formatting.
+ *
+ * Automatically selects the most appropriate unit (B, KB, MB, GB, TB) based
+ * on the magnitude. Supports both `number` and `bigint` inputs for handling
+ * very large file sizes without precision loss.
+ *
+ * @param bytes - The file size in bytes (supports `number` or `bigint`)
+ * @param options - Formatting options
+ * @returns A formatted file size string (e.g., `'1 KB'`, `'2.5 MB'`)
+ *
+ * @example
+ * ```ts
+ * formatFileSize(0)                           // '0 B'
+ * formatFileSize(1024)                        // '1 KB'
+ * formatFileSize(1536, { decimalPlaces: 1 })  // '1.5 KB'
+ * formatFileSize(1073741824n)                 // '1 GB'
+ * formatFileSize(1024, { locale: 'de-DE' })   // '1 KB' (with German formatting)
+ * ```
+ */
 export declare function formatFileSize(bytes: number | bigint, { units, decimalPlaces, locale, }?: FormatFileSizeOptions): string;

package/dist/ur-B6yB2JQ7.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r={signInTitle:"سائن ان",signInButton:"سائن ان",emailLabel:"ای میل",passwordLabel:"پاس ورڈ",rememberMeLabel:"مجھے یاد رکھیں",forgotPasswordLink:"پاس ورڈ بھول گئے؟",noAccountLink:"اکاؤنٹ نہیں ہے؟ سائن اپ کریں",signUpTitle:"سائن اپ",signUpButton:"سائن اپ",nameLabel:"نام",confirmPasswordLabel:"پاس ورڈ کی تصدیق کریں",acceptTermsLabel:"میں شرائط و ضوابط کو قبول کرتا ہوں",hasAccountLink:"پہلے سے اکاؤنٹ ہے؟ سائن ان کریں",resetPasswordTitle:"پاس ورڈ ری سیٹ کریں",resetPasswordButton:"پاس ورڈ ری سیٹ کریں",resetPasswordDescription:"اپنا پاس ورڈ ری سیٹ کرنے کے لیے اپنا ای میل درج کریں۔",backToSignInLink:"سائن ان پر واپس جائیں",continueWithProvider:e=>`${e} کے ساتھ جاری رکھیں`,passwordStrengthWeak:"کمزور",passwordStrengthFair:"ٹھیک",passwordStrengthGood:"اچھا",passwordStrengthStrong:"مضبوط",orDivider:"یا",error:"ایک خرابی ہوئی",required:"ضروری",authenticationTitle:"تصدیق",passwordMinLength:e=>`پاس ورڈ کم از کم ${e} حروف کا ہونا چاہیے`,passwordRequireUppercase:"پاس ورڈ میں کم از کم ایک بڑا حرف ہونا چاہیے",passwordRequireLowercase:"پاس ورڈ میں کم از کم ایک چھوٹا حرف ہونا چاہیے",passwordRequireNumber:"پاس ورڈ میں کم از کم ایک نمبر ہونا چاہیے",passwordRequireSpecialChar:"پاس ورڈ میں کم از کم ایک خاص حرف ہونا چاہیے",emailRequired:"ای میل ضروری ہے",invalidEmail:"براہ کرم ایک درست ای میل پتہ درج کریں",passwordRequired:"پاس ورڈ ضروری ہے",nameRequired:"نام ضروری ہے",confirmPasswordRequired:"براہ کرم پاس ورڈ کی تصدیق کریں",acceptTermsRequired:"آپ کو شرائط و ضوابط قبول کرنا ضروری ہے",passwordsDoNotMatch:"پاس ورڈ مماثل نہیں ہیں",invalidPassword:"غلط پاس ورڈ",invalidEmailAddress:"غلط ای میل"};exports.default=r;

package/dist/ur-CvGP14xo.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./translations-gVgMyNno.cjs"),r={loadingExtended:"لوڈ ہو رہا ہے، براہ کرم انتظار کریں",loadingShort:"لوڈ ہو رہا ہے...",locale:"زبان",iconDescription:"آئیکن",loadingIcon:"لوڈنگ آئیکن",failedToLoadIcon:"آئیکن لوڈ کرنے میں ناکام",editLabel:"ترمیم",selectOne:"ایک منتخب کریں",selectNone:"کوئی نہیں",selectMany:"متعدد منتخب کریں",noResults:"کوئی نتیجہ نہیں",passwordPlaceholderText:"خفیہ پاس ورڈ",togglePasswordVisibility:"پاس ورڈ کی مرئیت تبدیل کریں",toggleMenu:"مینو ٹوگل کریں",toggleAside:"سائیڈ پینل ٹوگل کریں",mainNavigation:"بنیادی نیویگیشن",sidebar:"سائیڈ بار",closeDrawer:"دراز بند کریں",closeModal:"ماڈل بند کریں",confirm:"تصدیق",cancel:"منسوخ",addLabel:"شامل کریں",removeItem:"آئٹم ہٹائیں",currentLocale:"اردو",ar:"عربی",de:"جرمن",en:"انگریزی",es:"ہسپانوی",fr:"فرانسیسی",he:"عبرانی",hi:"ہندی",it:"اطالوی",ja:"جاپانی",ko:"کوریائی",nl:"ڈچ",pl:"پولش",pt:"پرتگالی",ru:"روسی",tr:"ترکی",vi:"ویتنامی",zh:"چینی",fa:"فارسی",ur:"اردو",emailPlaceholderText:"اپنا ای میل داخل کریں",incrementValue:"قدر اضافہ کریں",decrementValue:"قدر کم کریں",dropZoneInstructions:e=>e?"منتخب کرنے کے لیے کلک کریں یا فائلیں یہاں گھسیٹیں، یا فائل منتخب کرنے کے لیے Enter یا Space دبائیں":"فائلیں یہاں گھسیٹیں",fileSizeUnits:["بائٹس","KB","MB","GB","TB"],removeFile:"فائل حذف کریں",clearAllFiles:"تمام فائلیں صاف کریں",clearValue:"قدر صاف کریں",unknownType:"نامعلوم قسم",filesInputInstructions:(e,o,n)=>{let l=e==null||e>1?"منتخب کرنے کے لیے کلک کریں یا فائلیں یہاں گھسیٹیں":"منتخب کرنے کے لیے کلک کریں یا فائل یہاں گھسیٹیں";if(e||o){const t=[];if(e!=null&&e>1&&t.push(`زیادہ سے زیادہ ${e} فائلیں`),o&&n){const a=i.formatFileSize(o,{units:n});t.push(`ہر ایک زیادہ سے زیادہ ${a}`)}t.length>0&&(l+=` (${t.join("، ")})`)}return l},paginationLabel:"صفحہ بندی",firstPage:"پہلا صفحہ",previousPage:"پچھلا صفحہ",nextPage:"اگلا صفحہ",lastPage:"آخری صفحہ",breadcrumbs:"بریڈ کرمبز",commandPalette:"کمانڈ پیلیٹ",typeACommand:"کمانڈ ٹائپ کریں...",noResultsFound:"کوئی نتیجہ نہیں ملا",noMatchingCommands:"کوئی مماثل کمانڈ نہیں ملی",appearanceSystem:"سسٹم",appearanceLight:"ہلکا",appearanceDark:"گہرا",ok:"OK",changeTypeConfirmation:"قسم تبدیل کرنے سے موجودہ قدر صاف ہو جائے گی۔ جاری رکھیں؟",notifications:"اطلاعات",markAllAsRead:"سب کو پڑھا ہوا نشان زد کریں",noNotifications:"کوئی اطلاع نہیں",schemaConflictsDetected:"اسکیما تنازعات کا پتا چلا",schemaViolationsDetected:"اسکیما خلاف ورزیوں کا پتا چلا",properties:"خصوصیات",uploading:"اپ لوڈ ہو رہا ہے...",dropFilesOrBrowse:"فائلیں یہاں چھوڑیں یا براؤز کرنے کے لیے کلک کریں",acceptedTypes:e=>`قابل قبول اقسام: ${e}`,enterUrlPrompt:"URL درج کریں:",exceeded:"(حد سے تجاوز)",pdfPreview:"PDF پیش نظارہ",lexical:{fontFamily:"فونٹ فیملی",fontSize:"فونٹ سائز",fontColor:"فونٹ رنگ",highlightColor:"ہائی لائٹ رنگ",backgroundColor:"پس منظر رنگ",bold:"بولڈ",italic:"ترچھا",underline:"خط کشیدہ",strikethrough:"کٹا ہوا",code:"کوڈ",clearFormatting:"فارمیٹنگ صاف کریں",normal:"عام",heading:e=>`سرخی ${e}`,bulletList:"بلٹ فہرست",orderedList:"نمبر شدہ فہرست",checkList:"چیک فہرست",indent:"اندر کریں",outdent:"باہر کریں",blockquote:"اقتباس",codeBlock:"کوڈ بلاک",horizontalRule:"افقی لکیر",insertTable:"ٹیبل داخل کریں",link:"لنک",undo:"واپس",redo:"دوبارہ",cut:"کاٹیں",copy:"نقل",paste:"چسپاں",defaultOption:"پہلے سے طے شدہ",slashCommands:"سلیش کمانڈز",noCommandsFound:"کوئی کمانڈ نہیں ملی",changeBlockType:"بلاک کی قسم تبدیل کریں",blockTypes:"بلاک کی اقسام",enterUrl:"URL درج کریں:"},prosemirror:{bold:"Bold",italic:"Italic",code:"Code",link:"Link",removeLink:"Remove Link",heading:e=>`Heading ${e}`,bulletList:"Bullet List",orderedList:"Ordered List",blockquote:"Blockquote",codeBlock:"Code Block",horizontalRule:"Horizontal Rule",linkUrlPlaceholder:"https://example.com"},pdfPageViewer:{loading:"Loading PDF...",loadFailed:"Failed to load PDF",invalidPdf:"Invalid PDF file",pageOutOfRange:(e,o)=>`Page ${e} is out of range (1-${o})`,renderFailed:"Failed to render PDF page"}};exports.default=r;