@tuwaio/nova-core 0.5.1 → 0.7.0

package/dist/index.d.cts

@@ -4,6 +4,16 @@ import * as DialogPrimitive from '@radix-ui/react-dialog';
 import { Variants } from 'framer-motion';
 import { ClassValue } from 'clsx';
 
+/**
+ * A chevron that points up when `isOpen` is `true` and down otherwise, animated with `framer-motion` when it flips.
+ * Nova uses it in dropdown triggers such as the chain selector.
+ *
+ * @param props - The chevron props.
+ * @param props.className - Classes merged with the default size and color (`--tuwa-text-secondary`).
+ * @param props.strokeWidth - Stroke width of the SVG path. Defaults to `2`.
+ * @param props.isOpen - Whether the related list is open.
+ * @returns The SVG element.
+ */
 declare function ChevronArrowWithAnim({ className, strokeWidth, isOpen, }: {
     className?: string;
     strokeWidth?: number;
@@ -69,10 +79,29 @@ interface GithubFallbackIconProps extends Omit<ComponentProps<'img'>, 'src'> {
  */
 declare function GithubFallbackIcon({ githubSrc, className, alt, firstPathFill, ...props }: GithubFallbackIconProps): React$1.JSX.Element;
 
+/**
+ * The dialog root (`Root` of `@radix-ui/react-dialog`): holds the open state (`open`, `defaultOpen`, `onOpenChange`).
+ */
 declare const Dialog: React$1.FC<DialogPrimitive.DialogProps>;
+/** The element that opens the dialog (`Trigger` of `@radix-ui/react-dialog`). */
 declare const DialogTrigger: React$1.ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & React$1.RefAttributes<HTMLButtonElement>>;
+/** Renders its children in `document.body` (`Portal` of `@radix-ui/react-dialog`). {@link DialogContent} uses it. */
 declare const DialogPortal: React$1.FC<DialogPrimitive.DialogPortalProps>;
+/** An element that closes the dialog (`Close` of `@radix-ui/react-dialog`). */
 declare const DialogClose: React$1.ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & React$1.RefAttributes<HTMLButtonElement>>;
+/**
+ * The dimmed, blurred backdrop behind the dialog, faded in and out with `framer-motion`. {@link DialogContent} renders
+ * it.
+ *
+ * Side effect: while it is mounted, the `NovaModalOpen` class is set on `document.body`; the stylesheet of this package
+ * uses it to stop the page from scrolling.
+ *
+ * @param props - The overlay props.
+ * @param props.className - Classes added to the backdrop element.
+ * @param props.backdropAnimation - `framer-motion` variants (`initial`, `animate`, `exit`) of the backdrop; a fade by
+ * default.
+ * @returns The backdrop.
+ */
 declare const DialogOverlay: {
     ({ className, backdropAnimation }: {
         backdropAnimation?: Variants;
@@ -80,28 +109,77 @@ declare const DialogOverlay: {
     }): React$1.JSX.Element;
     displayName: string | undefined;
 };
+/**
+ * The dialog panel (`Content` of `@radix-ui/react-dialog`), rendered in a portal above {@link DialogOverlay}. It takes
+ * the props of the Radix `Content` plus `modalAnimation` and `backdropAnimation` (`framer-motion` variants). By default
+ * the panel scales in at the center of the screen, or slides up from the bottom on touch devices (`isTouchDevice`); its
+ * content scrolls when it is taller than the viewport. Use it inside {@link Dialog}.
+ */
 declare const DialogContent: React$1.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogContentProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & {
     modalAnimation?: Variants;
     backdropAnimation?: Variants;
 } & React$1.RefAttributes<HTMLDivElement>>;
+/**
+ * A sticky header row of the dialog, with a bottom border.
+ *
+ * @param props - Props of the `<div>` element; `className` is merged with the default classes.
+ * @returns The header element.
+ */
 declare const DialogHeader: {
     ({ className, ...props }: React$1.HTMLAttributes<HTMLDivElement>): React$1.JSX.Element;
     displayName: string;
 };
+/**
+ * A footer row of the dialog: stacked on small screens, aligned to the end on wider ones.
+ *
+ * @param props - Props of the `<div>` element; `className` is merged with the default classes.
+ * @returns The footer element.
+ */
 declare const DialogFooter: {
     ({ className, ...props }: React$1.HTMLAttributes<HTMLDivElement>): React$1.JSX.Element;
     displayName: string;
 };
+/** The dialog title (`Title` of `@radix-ui/react-dialog`), styled with the Nova theme. */
 declare const DialogTitle: React$1.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogTitleProps & React$1.RefAttributes<HTMLHeadingElement>, "ref"> & React$1.RefAttributes<HTMLHeadingElement>>;
+/** The dialog description (`Description` of `@radix-ui/react-dialog`), styled with the Nova theme. */
 declare const DialogDescription: React$1.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogDescriptionProps & React$1.RefAttributes<HTMLParagraphElement>, "ref"> & React$1.RefAttributes<HTMLParagraphElement>>;
 
+/**
+ * Props of {@link NetworkIcon}.
+ */
 interface NetworkIconProps {
+    /**
+     * The network: an EVM chain ID (`1`), or a string whose part before `:` is a network id of `@web3icons/common`
+     * (`'solana:devnet'`, `'base'`).
+     */
     chainId: number | string;
+    /** Icon style of `@web3icons/react`. Defaults to `'background'`. */
     variant?: 'background' | 'branded' | 'mono';
+    /** Classes merged with the default classes (full size of the parent, rounded). */
     className?: string;
 }
+/**
+ * The icon of a network. Networks listed in `@web3icons/common` are drawn with `@web3icons/react`, loaded on demand
+ * (a pulsing {@link FallbackIcon} is shown meanwhile) and rendered through {@link SvgToImg}. An unknown numeric chain
+ * shows a `?` placeholder; an unknown string id is fetched from the web3icons repository on GitHub
+ * ({@link GithubFallbackIcon}). Testnets and the Solana devnet and testnet are recolored with `--tuwa-testnet-icons`.
+ *
+ * Side effect: a GitHub request (`raw.githubusercontent.com`) for icons that `@web3icons/common` does not list.
+ *
+ * @param props - See {@link NetworkIconProps}.
+ * @returns The icon element.
+ */
 declare function NetworkIcon({ chainId, variant, className }: NetworkIconProps): React$1.JSX.Element;
 
+/**
+ * An animated background of twinkling stars, drawn as SVG circles with CSS animations. It fills its positioned parent
+ * (`absolute`, `inset-0`); the stars are placed at random over the window size after mount, so nothing is rendered on
+ * the server. Nova Connect uses it in the "about wallets" and "get a wallet" screens of the connect modal.
+ *
+ * @param props - The background props.
+ * @param props.starsCount - Number of stars. Defaults to `200`.
+ * @returns The background element.
+ */
 declare function StarsBackground({ starsCount }: {
     starsCount?: number;
 }): React$1.JSX.Element;
@@ -126,7 +204,12 @@ declare function SvgImg({ src, alt, ...props }: SvgImgProps): React$1.JSX.Elemen
  * Props for the SvgToImg component.
  */
 interface SvgToImgProps extends Omit<ComponentProps<'img'>, 'ref' | 'src' | 'children'> {
-    /** Child SVG element to render while converting */
+    /**
+     * Renders the SVG. Pass `ref` to the `<svg>` element: when it mounts, its markup is converted to an image.
+     *
+     * @param ref - Callback ref for the `<svg>` element; it receives the element (or `null` when it unmounts).
+     * @returns The SVG to convert.
+     */
     children: (ref: (node: SVGSVGElement | null) => void) => ReactNode;
     /**
      * Unique identifier for the icon. When this changes, the cached image is reset.
@@ -149,14 +232,22 @@ interface SvgToImgProps extends Omit<ComponentProps<'img'>, 'ref' | 'src' | 'chi
  * Uses a render prop pattern to inject a callback ref that captures
  * the SVG immediately when it mounts.
  *
- * @param props - {@link SvgToImgProps}
- * @returns The converted image or the original children while loading
+ * @param props - See {@link SvgToImgProps}; the other props are passed to the `<img>` element.
+ * @returns The `<img>` with the converted SVG, or the output of `children` until the SVG has mounted.
  *
  * @example
  * ```tsx
- * <SvgToImg iconId={chainId} firstPathFill={TESTNET_FILL}>
- *   {(ref) => <NetworkIconLazy ref={ref} chainId={chainId} />}
- * </SvgToImg>
+ * import { SvgToImg } from '@tuwaio/nova-core';
+ *
+ * export const DotIcon = () => (
+ *   <SvgToImg iconId="dot" alt="Dot">
+ *     {(ref) => (
+ *       <svg ref={ref} viewBox="0 0 24 24">
+ *         <circle cx="12" cy="12" r="10" />
+ *       </svg>
+ *     )}
+ *   </SvgToImg>
+ * );
  * ```
  */
 declare function SvgToImg({ children, iconId, alt, firstPathFill, ...props }: SvgToImgProps): React$1.JSX.Element;
@@ -169,17 +260,14 @@ declare function SvgToImg({ children, iconId, alt, firstPathFill, ...props }: Sv
  */
 type ToastCloseButtonProps = {
     /**
-     * The function to call when the button is clicked. This is typically provided by the
-     * toast library (e.g., react-toastify) to dismiss the notification.
+     * Called when the button is clicked. `react-toastify` passes it to a custom close button to dismiss the toast.
+     *
+     * @param e - The click event.
      */
     closeToast?: (e: React.MouseEvent<HTMLElement>) => void;
-    /**
-     * Optional custom aria-label for accessibility.
-     */
+    /** Accessible label of the button. Defaults to `'Close toast notification'`. */
     ariaLabel?: string;
-    /**
-     * Optional custom title for the button tooltip.
-     */
+    /** Tooltip of the button. Defaults to `'Close toast notification'`. */
     title?: string;
     /**
      * Optional custom className for the button container.
@@ -191,8 +279,11 @@ type ToastCloseButtonProps = {
     iconClassName?: string;
 };
 /**
- * A simple, styled close button component ('X' icon) intended for use within toast notifications.
- * It uses theme-aware CSS variables for styling and i18n labels for accessibility.
+ * A close button with an X icon, placed in the top-right corner of a toast (`absolute`) and styled with the `--tuwa-*`
+ * variables. Pass it to `react-toastify` as `closeButton`, which provides `closeToast`.
+ *
+ * @param props - See {@link ToastCloseButtonProps}.
+ * @returns The button element.
  */
 declare function ToastCloseButton({ closeToast, ariaLabel, title, className, iconClassName, }: ToastCloseButtonProps): React$1.JSX.Element;
 
@@ -230,42 +321,74 @@ declare function WalletIcon({ walletName, variant, className }: WalletIconProps)
  * @file This file contains a custom React hook for copying text to the clipboard.
  */
 /**
- * A custom React hook that provides functionality to copy text to the clipboard.
- * It also manages a "copied" state with a timeout for user feedback.
+ * Result of `copy` of {@link useCopyToClipboard}: `copied: true`, or `copied: false` with the error (also without
+ * text to copy).
+ */
+type CopyToClipboardResult = {
+    copied: true;
+} | {
+    copied: false;
+    error: Error;
+};
+/**
+ * Value returned by {@link useCopyToClipboard}.
+ */
+interface UseCopyToClipboardResult {
+    /** `true` for `timeout` milliseconds after a successful copy */
+    isCopied: boolean;
+    /**
+     * Writes the text to the clipboard (`navigator.clipboard.writeText`). A failed write is logged with
+     * `console.error` and kept in `error` for `timeout` milliseconds.
+     *
+     * @param text - The text to copy.
+     * @returns Whether the text was copied, with the error when it was not.
+     */
+    copy: (text: string) => Promise<CopyToClipboardResult>;
+    /** The error of the last failed write, for `timeout` milliseconds */
+    error: Error | null;
+}
+/**
+ * Copies text to the clipboard and keeps a "copied" state for user feedback.
  *
- * @param {number} [timeout=2000] - The duration in milliseconds to keep the `isCopied` state as true.
- * @returns {{
- * isCopied: boolean;
- * copy: (text: string) => Promise<void>;
- * error: Error | null;
- * }} An object containing the `isCopied` state, the `copy` function, and any potential error.
+ * @param timeout - How long `isCopied` (and `error` after a failure) stays set, in milliseconds (default: `2000`).
+ * @returns See {@link UseCopyToClipboardResult}.
  *
  * @example
- * const MyComponent = () => {
- * const { isCopied, copy } = useCopyToClipboard();
- * const textToCopy = '0x123...';
- *
- * return (
- * <button onClick={() => copy(textToCopy)}>
- * {isCopied ? 'Copied!' : 'Copy Address'}
- * </button>
- * );
+ * ```tsx
+ * import { useCopyToClipboard } from '@tuwaio/nova-core';
+ *
+ * export function CopyAddress({ address }: { address: string }) {
+ *   const { isCopied, copy } = useCopyToClipboard();
+ *
+ *   const handleClick = async () => {
+ *     const result = await copy(address);
+ *     if (!result.copied) console.warn(result.error.message);
+ *   };
+ *
+ *   return (
+ *     <button type="button" onClick={handleClick}>
+ *       {isCopied ? 'Copied!' : 'Copy address'}
+ *     </button>
+ *   );
  * }
+ * ```
  */
-declare function useCopyToClipboard(timeout?: number): {
-    isCopied: boolean;
-    copy: (text: string) => Promise<void>;
-    error: Error | null;
-};
+declare function useCopyToClipboard(timeout?: number): UseCopyToClipboardResult;
 
 /**
  * A custom hook to detect if a media query matches the current screen dimensions.
- * Handles SSR gracefully.
- * @param {string} query - The media query string (e.g., '(max-width: 767px)').
- * @returns {boolean} Whether the query matches or not.
+ * Returns `false` on the server. In the browser it checks the query again on every `resize` event of `window`
+ * (a listener that is removed on unmount).
+ *
+ * @param query - The media query string (e.g., '(max-width: 767px)').
+ * @returns Whether the query matches.
  */
 declare function useMediaQuery(query: string): boolean;
 
+/**
+ * Classes of the standard secondary button of Nova (Tailwind utilities with the `novacore:` prefix, styled with the
+ * `--tuwa-standart-button-*` variables). The connect modal uses them for its buttons.
+ */
 declare const standardButtonClasses = "novacore:cursor-pointer novacore:rounded-[var(--tuwa-rounded-corners)] novacore:bg-[var(--tuwa-standart-button-bg)] novacore:px-3 novacore:py-2 novacore:flex novacore:items-center novacore:gap-1 novacore:text-sm novacore:font-mono novacore:font-semibold novacore:text-[var(--tuwa-text-primary)] novacore:transition-colors novacore:hover:bg-[var(--tuwa-standart-button-hover)] novacore:disabled:cursor-not-allowed novacore:disabled:opacity-50 novacore:min-h-[36px]";
 
 /**
@@ -334,22 +457,24 @@ interface ChainInfo {
  * For string IDs with environment suffixes (like "solana:devnet"),
  * the suffix is appended to the name if it's a known dev/test environment.
  *
+ * The networks are looked up in the metadata of `@web3icons/common`.
+ *
  * @param chainId - Chain identifier (number for EVM, string for non-EVM)
- * @returns Chain information object with name, id, and original chainId
+ * @returns The network name, id and icon file path, and the original `chainId`; `'Unknown'`/`'unknown'` when the
+ * network is not listed.
  *
  * @example
  * ```ts
- * // EVM network
- * getChainName(1)
- * // → { name: "Ethereum", id: "ethereum", chainId: 1 }
+ * import { getChainName } from '@tuwaio/nova-core';
+ *
+ * getChainName(1);
+ * // → { name: 'Ethereum', id: 'ethereum', filePath: 'ethereum', chainId: 1 }
  *
- * // Solana devnet
- * getChainName("solana:devnet")
- * // → { name: "Solana Devnet", id: "solana", chainId: "solana:devnet" }
+ * getChainName('solana:devnet');
+ * // → { name: 'Solana Devnet', id: 'solana', filePath: 'solana', chainId: 'solana:devnet' }
  *
- * // Unknown network
- * getChainName(999999)
- * // → { name: "Unknown", id: "unknown", chainId: 999999 }
+ * getChainName(999999);
+ * // → { name: 'Unknown', id: 'unknown', filePath: 'unknown', chainId: 999999 }
  * ```
  */
 declare function getChainName(chainId: number | string): ChainInfo;
@@ -366,7 +491,7 @@ declare function getChainName(chainId: number | string): ChainInfo;
 declare function isSolanaDev(chainId: number | string): boolean;
 
 /**
- * @fileoverview Utility function to determine if the current environment supports touch input.
+ * @file Utility function to determine if the current environment supports touch input.
  * This is safe to use in Next.js applications as it checks for the `window` object existence.
  */
 /**
@@ -379,14 +504,16 @@ declare function isSolanaDev(chainId: number | string): boolean;
  *
  * This function is safe for server-side rendering (SSR) environments like Next.js.
  *
- * @param {number} [maxWidth=1200] The maximum screen width (in pixels) for a device to be considered 'touch' (default is 1200).
- * @returns {boolean} Returns true if the environment is determined to support touch input AND is within the width limit, otherwise false.
+ * @param {number} [maxWidth=1200] The maximum screen width (in pixels) for a device to be considered 'touch' (default
+ * is 1200).
+ * @returns {boolean} Returns true if the environment is determined to support touch input AND is within the width
+ * limit, otherwise false.
  */
 declare function isTouchDevice(maxWidth?: number): boolean;
 
 /**
- * Resolves a CSS variable to its computed value.
- * Returns the original value if it's not a CSS variable.
+ * Resolves a CSS variable to its computed value on `document.documentElement`.
+ * Returns the original value if it's not a CSS variable. Call it in the browser: it reads `getComputedStyle`.
  *
  * @param value - Color value, potentially a CSS variable like `var(--my-color)`
  * @returns Resolved color value (e.g., `#ff0000`) or original if not a variable
@@ -394,20 +521,20 @@ declare function isTouchDevice(maxWidth?: number): boolean;
 declare function resolveCssVariable(value: string): string;
 /**
  * Modifies the fill attribute of the first `<path>` element in an SVG string.
- * Uses DOMParser for safe XML manipulation.
- * Automatically resolves CSS variables (e.g., `var(--color)`) to their computed values.
+ * Uses DOMParser for safe XML manipulation, so call it in the browser.
+ * Automatically resolves CSS variables (e.g., `var(--color)`) to their computed values with {@link resolveCssVariable}.
  *
  * @param svgString - The original SVG markup
  * @param fillColor - The color to apply (supports CSS variables)
- * @returns Modified SVG string
+ * @returns Modified SVG string, or the original string (with a console warning) when it cannot be parsed
  */
 declare function applyFirstPathFill(svgString: string, fillColor: string): string;
 /**
  * Encodes an SVG string to a base64 data URL.
  *
  * @param svgString - The SVG markup
- * @param firstPathFill - Optional fill color to apply to the first path
- * @returns Base64-encoded data URL
+ * @param firstPathFill - Optional fill color to apply to the first path, with {@link applyFirstPathFill} (browser only)
+ * @returns Base64-encoded data URL (`data:image/svg+xml;base64,…`)
  */
 declare function svgToBase64(svgString: string, firstPathFill?: string): string;
 /**
@@ -421,14 +548,10 @@ declare function svgToBase64(svgString: string, firstPathFill?: string): string;
  *
  * @example
  * ```ts
- * formatIconNameForGithub("Wallet Connect")
- * // → "wallet-connect.svg"
- *
- * formatIconNameForGithub("MetaMask")
- * // → "metamask.svg"
+ * import { formatIconNameForGithub } from '@tuwaio/nova-core';
  *
- * formatIconNameForGithub("coinbase")
- * // → "coinbase.svg"
+ * formatIconNameForGithub('Wallet Connect'); // → 'wallet-connect.svg'
+ * formatIconNameForGithub('MetaMask'); // → 'metamask.svg'
  * ```
  */
 declare const formatIconNameForGithub: (name: string) => string;
@@ -453,4 +576,4 @@ declare const formatIconNameForGithub: (name: string) => string;
  */
 declare function textCenterEllipsis(str: string | undefined | null, from: number, to: number): string;
 
-export { type ChainInfo, ChevronArrowWithAnim, CloseIcon, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, FallbackIcon, type FallbackIconProps, GithubFallbackIcon, NetworkIcon, StarsBackground, SvgImg, type SvgImgProps, SvgToImg, ToastCloseButton, type ToastCloseButtonProps, WalletIcon, applyFirstPathFill, cn, deepMerge, formatIconNameForGithub, getChainName, isSolanaDev, isTouchDevice, resolveCssVariable, standardButtonClasses, svgToBase64, textCenterEllipsis, useCopyToClipboard, useMediaQuery };
+export { type ChainInfo, ChevronArrowWithAnim, CloseIcon, type CopyToClipboardResult, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, FallbackIcon, type FallbackIconProps, GithubFallbackIcon, type GithubFallbackIconProps, NetworkIcon, type NetworkIconProps, StarsBackground, SvgImg, type SvgImgProps, SvgToImg, type SvgToImgProps, ToastCloseButton, type ToastCloseButtonProps, type UseCopyToClipboardResult, WalletIcon, type WalletIconProps, applyFirstPathFill, cn, deepMerge, formatIconNameForGithub, getChainName, isSolanaDev, isTouchDevice, resolveCssVariable, standardButtonClasses, svgToBase64, textCenterEllipsis, useCopyToClipboard, useMediaQuery };