@protonradio/proton-ui 0.5.4 → 0.6.1

package/dist/proton-ui.es.d.ts

@@ -20,6 +20,14 @@ import { TableStateProps } from 'react-stately';
 import { TooltipProps as TooltipProps_2 } from 'react-aria-components';
 import { TooltipTriggerComponentProps } from 'react-aria-components';
 
+/**
+ * Converts an RGB array to a CSS string representation.
+ * @param rgb - The RGB array to convert.
+ * @param opacity - Optional opacity value.
+ * @returns A CSS string representation of the RGB array, using `rgb()`, or `rgba()` if an opacity value is provided.
+ */
+export declare const arrayToRgbString: (rgb: RGBArray, opacity?: number) => string;
+
 export declare const Badge: ({ variant, children, ...props }: BadgeProps) => JSX_2.Element;
 
 export declare interface BadgeProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -105,13 +113,120 @@ declare interface BannerProps extends BannerIconProps, default_2.HTMLAttributes<
 
 export declare type BannerVariant = "default" | "success" | "warning" | "danger";
 
+declare interface BaseInputProps {
+    /**
+     * onChange handler for the input
+     * @param {React.ChangeEvent<HTMLInputElement>} event
+     */
+    onChange?: (value: string) => void;
+    /**
+     * onKeyDown handler for the input
+     * @param {React.KeyboardEvent<HTMLInputElement>} event
+     */
+    onKeyDown?: (event: default_2.KeyboardEvent<HTMLInputElement>) => void;
+    /**
+     * Whether the input is disabled.
+     * @param {boolean} isDisabled
+     */
+    isDisabled?: boolean;
+    /**
+     * Should the input be rounded?
+     * @param {boolean} isRounded
+     */
+    isRounded?: boolean;
+    /**
+     * Description text shown above the input.
+     * @param {React.ReactNode | string} description
+     */
+    description?: default_2.ReactNode | string;
+    /**
+     * Error state that changes the input's visual style and displays an error message.
+     * @param {React.ReactNode | string} error
+     */
+    error?: default_2.ReactNode | string;
+    /**
+     * Label for the input element.
+     * @note When a label is provided, the input will have extra padding, and the label will float above the text input when focused or filled.
+     * @param {string} label
+     */
+    label?: string;
+    /**
+     * Test ID for the component.
+     * @param {string} data-testid
+     */
+    "data-testid"?: string;
+    /**
+     * Content to display before the input. Typically used for icons.
+     * @param {React.ReactNode} prefix
+     */
+    prefix?: default_2.ReactNode;
+    /**
+     * Content to display after the input. Typically used for icons.
+     * @param {React.ReactNode} suffix
+     */
+    suffix?: default_2.ReactNode;
+    /**
+     * Should the browser's autocomplete be enabled?
+     * @external https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
+     * @param {boolean} autoComplete
+     */
+    autoComplete?: boolean;
+    /**
+     * Should the input be autofocused?
+     * @external https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autofocus
+     * @param {boolean} autoFocus
+     */
+    autoFocus?: boolean;
+    /**
+     * The name attribute of the input element.
+     * @external https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/name
+     * @param {string} name
+     */
+    name?: string;
+    /**
+     * The placeholder text to display when the input is empty.
+     * @note Placeholder takes precedence over label, if both are provided.
+     * @external https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/placeholder
+     * @param {string} placeholder
+     */
+    placeholder?: string;
+    /**
+     * The pattern attribute of the input element.
+     * @external https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern
+     * @param {string} pattern
+     */
+    pattern?: string;
+    /**
+     * The tab index of the input element.
+     * @external https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex
+     * @param {number} tabIndex
+     */
+    tabIndex?: number;
+    /**
+     * The type attribute of the input element.
+     * @external https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/type
+     * @param {string} type
+     */
+    type?: string;
+    /**
+     * The value of the input.
+     * @external https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#value
+     * @param {string} value
+     */
+    value?: string;
+}
+
 export declare const BRAND: {
     PRIMARY: string;
     PRIMARY_LIGHT: string;
     SECONDARY: string;
 };
 
-export declare function Button({ variant, ...props }: ButtonProps): JSX_2.Element;
+/**
+ * A customizable button component that can render as either a button or anchor element
+ * @interface ButtonProps
+ */
+export declare function Button({ variant, href, onPress, type, isDisabled, "data-testid": testId, children, }: ButtonProps): JSX_2.Element;
 
 export declare function ButtonGroup(props: ButtonGroupProps): JSX_2.Element;
 
@@ -152,24 +267,32 @@ declare interface ButtonGroupProps {
 }
 
 declare interface ButtonProps {
-    /**
-     * The button's visual aesthetic.
+    /** The button's visual aesthetic
+     * @param {ButtonVariant} variant
      */
     variant?: ButtonVariant;
-    /**
-     * Should the button be non-interactive?
+    /** Should the button be non-interactive?
+     * @param {boolean} isDisabled
      */
     isDisabled?: boolean;
-    /**
-     * The URL that the button should link to. Turns the element into an `a` tag.
+    /** The URL that the button should link to. Turns the element into an `a` tag
+     * @param {string} href
      */
     href?: string;
-    /**
-     *  Called when the button is pressed (on release, not keydown).
+    /** Called when the button is pressed (on release, not keydown)
+     * @param {(e: PressEvent) => void} onPress
      */
     onPress?: (e: PressEvent) => void;
-    /**
-     * The content to display within the button.
+    /** The type of button
+     * @param {"button" | "submit" | "reset"} type
+     */
+    type?: "button" | "submit" | "reset";
+    /** The test ID for the button
+     * @param {string} dataTestId
+     */
+    "data-testid"?: string;
+    /** The content to display within the button
+     * @param {React.ReactNode} children
      */
     children?: React.ReactNode;
 }
@@ -180,6 +303,8 @@ export declare const Cell: <T>(props: ProtonColumnProps<T>) => JSX.Element;
 
 export declare const Column: <T>(props: ProtonColumnProps<T>) => JSX.Element;
 
+export declare function csx(...classnames: unknown[]): string;
+
 export declare const DANGER: {
     SUPER_DARK: string;
     DARK: string;
@@ -214,6 +339,19 @@ export declare const GRAYSCALE: {
     BORDER: string;
 };
 
+/**
+ * Handles internal navigation clicks by preventing default browser behavior and
+ * programmatically updating the URL and history state.
+ *
+ * @param e - The click event from the anchor element
+ * @param to - The destination path to navigate to
+ *
+ * @remarks
+ * - Converts relative paths to absolute by prepending "/" if needed
+ * - Updates browser history using pushState and dispatches a popstate event
+ */
+export declare const handleInternalNavigation: (e: React.MouseEvent<HTMLAnchorElement>, to: string) => void;
+
 export declare function Icon(props: Omit<IconProps, "svgContent">): JSX_2.Element;
 
 declare type IconID = "external-link" | "caret-down";
@@ -233,6 +371,24 @@ declare interface IconProps {
     color?: string;
 }
 
+/**
+ * A controlled and customizable input component with support for labels, prefixes, suffixes, and error states.
+ */
+export declare const Input: default_2.ForwardRefExoticComponent<BaseInputProps & default_2.RefAttributes<HTMLInputElement>>;
+
+/**
+ * [isUrlExternal] - determine if passed absolute url is external to the current domain.
+ */
+export declare const isUrlExternal: (url: any) => boolean;
+
+/**
+ * Lightens an RGB color by a specified factor.
+ * @param rgb - The RGB color array to lighten.
+ * @param factor - The factor between 0 (darker) - 1 (lighter) by which to transform the color.
+ * @returns The lightened RGB color array, RGB values are clamped to 42 (dark) - 179 (light).
+ */
+export declare const lightenRGBColor: (rgb: RGBArray, factor: number) => RGBArray;
+
 export declare function Popover({ children, state, arrow, offset, ...props }: PopoverProps): JSX_2.Element;
 
 /**
@@ -269,67 +425,38 @@ export declare type RGBArray = [number, number, number];
 
 export { Row }
 
-export declare const SearchInput: default_2.FC<SearchInputProps>;
-
-/** Properties for the SearchInput component
- * @interface SearchInputProps
+/**
+ * A search input component with optional clear functionality and URL parameter sync.
  */
-declare interface SearchInputProps {
-    /**
-     * The controlled value of the search input.
-     * If you provide a value, you should typically also provide an onChange handler to update it.
-     * @param {string} value
-     */
-    defaultValue?: string;
-    /**
-     * Should the browser's autocomplete be enabled?
-     * @param {boolean} autoComplete
-     */
-    autoComplete?: boolean;
-    /**
-     * The name attribute of the input element.
-     * @param {string} name
-     */
-    name?: string;
-    /**
-     * The placeholder text to display when the input is empty.
-     * @param {string} placeholder
-     */
-    placeholder?: string;
+export declare const SearchInput: ({ name, placeholder, autoComplete, isClearable, isRounded, error, urlSearchParam, defaultValue, "data-testid": testId, onChange, onClear, }: SearchInputProps) => JSX_2.Element;
+
+declare interface SearchInputProps extends Omit<BaseInputProps, "prefix" | "suffix" | "value" | "onChange"> {
     /**
      * Should the clear button be shown when there is text?
      * @param {boolean} isClearable
      */
     isClearable?: boolean;
+    /**
+     * Called when the input value changes.
+     * @note Required when using the input as a controlled component.
+     * @param {(value: string) => void} onChange
+     */
+    onChange?: (value: string) => void;
     /**
      * Called when the clear button is clicked.
      * @param {() => void} onClear
      */
     onClear?: () => void;
-    /**
-     * Called when the input value changes. Required when using the input as a controlled component.
-     * @param {(event: { target: { value: string } }) => void} onChange
-     */
-    onChange?: (event: {
-        target: {
-            value: string;
-        };
-    }) => void;
     /**
      * URL search parameter key to sync the input value with.
      * @param {string} urlSearchParam
      */
     urlSearchParam?: string;
     /**
-     * Error state that changes the input's visual style.
-     * @param {React.ReactNode | string} error
-     */
-    error?: default_2.ReactNode | string;
-    /**
-     * Test ID for the component.
-     * @param {string} data-testid
+     * The initial value of the input.
+     * @param {string} defaultValue
      */
-    "data-testid"?: string;
+    defaultValue?: string;
 }
 
 export { Section }
@@ -489,6 +616,61 @@ export declare const WARNING: {
     SUPER_LIGHT: string;
 };
 
+/**
+ * A waveform visualization component that displays audio data with interactive features.
+ *
+ * @component
+ * @interface WaveformProps
+ *
+ * @returns {JSX.Element} A waveform visualization with optional timestamps and interactive features
+ */
+export declare function Waveform({ data: waveformData, resolution, startDuration, endDuration, currentTime, showTimestamps, totalDuration, onClick, timestampColor: timestampColorProp, "data-testid": testId, }: WaveformProps): JSX_2.Element;
+
+declare interface WaveformProps {
+    /**
+     * Array of normalized amplitude values (0-1) representing the waveform.
+     * If not provided, uses a sample sine wave.
+     */
+    data?: number[];
+    /**
+     * Total duration of the audio in seconds.
+     */
+    totalDuration: number;
+    /**
+     * Current playback position in seconds.
+     */
+    currentTime?: number;
+    /**
+     * Width in pixels of each waveform bar.
+     */
+    resolution?: number;
+    /**
+     * Start time to display from in seconds.
+     */
+    startDuration?: number;
+    /**
+     * End time to display until in seconds.
+     */
+    endDuration?: number;
+    /**
+     * Whether to show timestamp markers.
+     */
+    showTimestamps?: boolean;
+    /**
+     * Click handler that receives the clicked position (0-1) and event.
+     */
+    onClick?: (position: number, e: React.MouseEvent<HTMLDivElement>) => void;
+    /**
+     * Custom color for timestamp text backgrounds.
+     * Will use theme color by default.
+     */
+    timestampColor?: string;
+    /**
+     * Test ID for testing purposes.
+     */
+    "data-testid"?: string;
+}
+
 export { }