@txnlab/use-wallet-ui-react 0.3.1 → 0.4.1

package/dist/types/index.d.cts

@@ -85,6 +85,10 @@ declare type RefableElement_2 = ReactElement & {
     ref?: RefObject<HTMLElement> | ((instance: HTMLElement | null) => void);
 };
 
+export declare type ResolvedTheme = 'light' | 'dark';
+
+export declare type Theme = 'light' | 'dark' | 'system';
+
 /**
  * Custom hook to fetch account information for Algorand address
  *
@@ -107,6 +111,15 @@ export declare function useNfd(options?: {
     view?: NfdView;
 }): UseQueryResult<NfdRecord | null>;
 
+/**
+ * Hook to resolve the actual theme value, handling 'system' preference detection.
+ * When theme is 'system', it listens to the user's OS/browser color scheme preference.
+ *
+ * @param theme - The theme setting: 'light', 'dark', or 'system'
+ * @returns The resolved theme: 'light' or 'dark'
+ */
+export declare function useResolvedTheme(theme: Theme): ResolvedTheme;
+
 /**
  * Hook to access the WalletUI context
  * @throws Error if used outside of WalletUIProvider
@@ -124,6 +137,8 @@ declare interface WalletListProps {
 
 declare interface WalletUIContextType {
     queryClient: QueryClient;
+    theme: Theme;
+    resolvedTheme: ResolvedTheme;
 }
 
 /**
@@ -133,8 +148,13 @@ declare interface WalletUIContextType {
  *
  * Automatically prefetches data for all accounts in connected wallets for smoother
  * account switching experience.
+ *
+ * Supports theme configuration via the `theme` prop:
+ * - 'light': Always use light mode
+ * - 'dark': Always use dark mode
+ * - 'system': Follow the user's OS/browser preference (default)
  */
-export declare function WalletUIProvider({ children, queryClient: externalQueryClient, enablePrefetching, prefetchNfdView, }: WalletUIProviderProps): JSX.Element;
+export declare function WalletUIProvider({ children, queryClient: externalQueryClient, enablePrefetching, prefetchNfdView, theme, }: WalletUIProviderProps): JSX.Element;
 
 declare interface WalletUIProviderProps {
     children: ReactNode;
@@ -147,6 +167,16 @@ declare interface WalletUIProviderProps {
      * NFD view type for prefetching (defaults to 'thumbnail')
      */
     prefetchNfdView?: NfdView;
+    /**
+     * Theme setting for wallet UI components.
+     * - 'light': Always use light mode
+     * - 'dark': Always use dark mode
+     * - 'system': Follow the user's OS/browser preference (default)
+     *
+     * The library also respects the `.dark` class on ancestor elements (Tailwind convention),
+     * which will enable dark mode unless explicitly overridden with theme="light".
+     */
+    theme?: Theme;
 }
 
 export { }

package/dist/types/index.d.ts

@@ -85,6 +85,10 @@ declare type RefableElement_2 = ReactElement & {
     ref?: RefObject<HTMLElement> | ((instance: HTMLElement | null) => void);
 };
 
+export declare type ResolvedTheme = 'light' | 'dark';
+
+export declare type Theme = 'light' | 'dark' | 'system';
+
 /**
  * Custom hook to fetch account information for Algorand address
  *
@@ -107,6 +111,15 @@ export declare function useNfd(options?: {
     view?: NfdView;
 }): UseQueryResult<NfdRecord | null>;
 
+/**
+ * Hook to resolve the actual theme value, handling 'system' preference detection.
+ * When theme is 'system', it listens to the user's OS/browser color scheme preference.
+ *
+ * @param theme - The theme setting: 'light', 'dark', or 'system'
+ * @returns The resolved theme: 'light' or 'dark'
+ */
+export declare function useResolvedTheme(theme: Theme): ResolvedTheme;
+
 /**
  * Hook to access the WalletUI context
  * @throws Error if used outside of WalletUIProvider
@@ -124,6 +137,8 @@ declare interface WalletListProps {
 
 declare interface WalletUIContextType {
     queryClient: QueryClient;
+    theme: Theme;
+    resolvedTheme: ResolvedTheme;
 }
 
 /**
@@ -133,8 +148,13 @@ declare interface WalletUIContextType {
  *
  * Automatically prefetches data for all accounts in connected wallets for smoother
  * account switching experience.
+ *
+ * Supports theme configuration via the `theme` prop:
+ * - 'light': Always use light mode
+ * - 'dark': Always use dark mode
+ * - 'system': Follow the user's OS/browser preference (default)
  */
-export declare function WalletUIProvider({ children, queryClient: externalQueryClient, enablePrefetching, prefetchNfdView, }: WalletUIProviderProps): JSX.Element;
+export declare function WalletUIProvider({ children, queryClient: externalQueryClient, enablePrefetching, prefetchNfdView, theme, }: WalletUIProviderProps): JSX.Element;
 
 declare interface WalletUIProviderProps {
     children: ReactNode;
@@ -147,6 +167,16 @@ declare interface WalletUIProviderProps {
      * NFD view type for prefetching (defaults to 'thumbnail')
      */
     prefetchNfdView?: NfdView;
+    /**
+     * Theme setting for wallet UI components.
+     * - 'light': Always use light mode
+     * - 'dark': Always use dark mode
+     * - 'system': Follow the user's OS/browser preference (default)
+     *
+     * The library also respects the `.dark` class on ancestor elements (Tailwind convention),
+     * which will enable dark mode unless explicitly overridden with theme="light".
+     */
+    theme?: Theme;
 }
 
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@txnlab/use-wallet-ui-react",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "React components for use-wallet UI",
   "type": "module",
   "main": "dist/cjs/index.cjs",
@@ -18,10 +18,12 @@
       }
     },
     "./dist/style.css": "./dist/style.css",
+    "./theme.css": "./src/theme.css",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src/theme.css",
     "README.md"
   ],
   "keywords": [
@@ -86,7 +88,7 @@
     "react-dom": "19.1.0",
     "tailwindcss": "4.1.11",
     "tsx": "4.20.3",
-    "vite": "6.3.5",
+    "vite": "6.4.1",
     "vite-plugin-dts": "4.5.4",
     "vite-tsconfig-paths": "5.1.4",
     "vitest": "3.2.4"

package/src/theme.css

@@ -0,0 +1,76 @@
+/* Theme CSS custom properties for wallet UI components */
+/* Import this file in Tailwind projects to enable theming */
+
+/* Light mode (default) */
+[data-wallet-ui] {
+  --wui-color-primary: #2d2df1;
+  --wui-color-primary-hover: #2929d9;
+  --wui-color-primary-text: #ffffff;
+  --wui-color-bg: #ffffff;
+  --wui-color-bg-secondary: #f9fafb;
+  --wui-color-bg-tertiary: #f3f4f6;
+  --wui-color-bg-hover: #e9e9fd;
+  --wui-color-text: #1f2937;
+  --wui-color-text-secondary: #6b7280;
+  --wui-color-text-tertiary: #9ca3af;
+  --wui-color-border: #e5e7eb;
+  --wui-color-link: rgba(45, 45, 241, 0.8);
+  --wui-color-link-hover: #2d2df1;
+  --wui-color-overlay: rgba(0, 0, 0, 0.3);
+}
+
+/* Dark mode via data-theme attribute (explicit) */
+[data-wallet-ui][data-theme='dark'] {
+  --wui-color-primary: #bfbff9;
+  --wui-color-primary-hover: #d4d4fa;
+  --wui-color-primary-text: #001324;
+  --wui-color-bg: #001324;
+  --wui-color-bg-secondary: #101b29;
+  --wui-color-bg-tertiary: #192a39;
+  --wui-color-bg-hover: #192a39;
+  --wui-color-text: #e9e9fd;
+  --wui-color-text-secondary: #99a1a7;
+  --wui-color-text-tertiary: #6b7280;
+  --wui-color-border: #192a39;
+  --wui-color-link: #6c6cf1;
+  --wui-color-link-hover: #8080f3;
+  --wui-color-overlay: rgba(0, 0, 0, 0.5);
+}
+
+/* Dark mode via .dark class on ancestor (Tailwind convention) */
+.dark [data-wallet-ui]:not([data-theme='light']) {
+  --wui-color-primary: #bfbff9;
+  --wui-color-primary-hover: #d4d4fa;
+  --wui-color-primary-text: #001324;
+  --wui-color-bg: #001324;
+  --wui-color-bg-secondary: #101b29;
+  --wui-color-bg-tertiary: #192a39;
+  --wui-color-bg-hover: #192a39;
+  --wui-color-text: #e9e9fd;
+  --wui-color-text-secondary: #99a1a7;
+  --wui-color-text-tertiary: #6b7280;
+  --wui-color-border: #192a39;
+  --wui-color-link: #6c6cf1;
+  --wui-color-link-hover: #8080f3;
+  --wui-color-overlay: rgba(0, 0, 0, 0.5);
+}
+
+/* Dark mode via system preference (when theme="system" or no explicit theme) */
+@media (prefers-color-scheme: dark) {
+  [data-wallet-ui]:not([data-theme='light']):not([data-theme='dark']) {
+    --wui-color-primary: #bfbff9;
+    --wui-color-primary-hover: #d4d4fa;
+    --wui-color-primary-text: #001324;
+    --wui-color-bg: #001324;
+    --wui-color-bg-secondary: #101b29;
+    --wui-color-bg-tertiary: #192a39;
+    --wui-color-bg-hover: #192a39;
+    --wui-color-text: #e9e9fd;
+    --wui-color-text-secondary: #99a1a7;
+    --wui-color-text-tertiary: #6b7280;
+    --wui-color-border: #192a39;
+    --wui-color-link: #6c6cf1;
+    --wui-color-link-hover: #8080f3;
+    --wui-color-overlay: rgba(0, 0, 0, 0.5);
+  }
+}