@calimero-network/mero-react 1.1.0 → 2.1.0

package/README.md

@@ -2,15 +2,15 @@
 
 React bindings for [@calimero-network/mero-js](../mero-js) — the Calimero Network SDK.
 
-No UI components. No styled-components. No axios. Just a provider, hooks, and storage helpers.
+No external UI framework. No styled-components. No axios. A provider, 44 hooks, storage helpers, and optional headless utility components (ConnectButton, LoginModal).
 
 ## Installation
 
 ```bash
-pnpm add @calimero-network/mero-react @calimero-network/mero-js
+pnpm add @calimero-network/mero-react
 ```
 
-Peer dependencies: `react` ^18 || ^19, `react-dom` ^18 || ^19.
+Peer dependencies: `react` ^18 || ^19, `react-dom` ^18 || ^19. `mero-js` is a bundled dependency — no separate install needed.
 
 ## Quick start
 
@@ -234,50 +234,141 @@ import {
 } from '@calimero-network/mero-react';
 ```
 
-## Enums
+## Theming
+
+`ConnectButton` and `LoginModal` default to the green Calimero palette used in admin-dashboard, tauri-app, and app-registry. Pass nothing for the default — provide a partial `MeroTheme` to override any subset.
 
 ```tsx
+import { ConnectButton } from '@calimero-network/mero-react';
+
+// Default green palette — no theme prop needed
+<ConnectButton />
+
+// Override only what you want; the rest stay default
+<ConnectButton
+  theme={{
+    primary: '#ff4081',
+    primaryHover: '#e91e63',
+    primaryText: '#ffffff',
+  }}
+/>
+```
+
+The same theme is forwarded to the embedded `LoginModal` and is also exposed as CSS variables on the component root, so a global stylesheet works too:
+
+```css
+:root {
+  --mero-accent: #ff4081;
+  --mero-accent-hover: #e91e63;
+}
+```
+
+`MeroTheme` keys (all optional): `primary`, `primaryHover`, `primaryText`, `background`, `backgroundSecondary`, `backgroundTertiary`, `border`, `text`, `textSecondary`, `error`, `overlay`, `radius`. Defaults: `#a5ff11` / `#8ed40d` / `#0d1117` / `#161b22` / `#1c2128` / `#30363d` / `#e6edf3` / `#8b949e` / `#ff6b6b` / `rgba(0,0,0,0.75)` / `8px`.
+
+Helpers: `defaultMeroTheme` (the full default palette), `resolveMeroTheme(partial?)` (merges a partial with defaults), and `themeToCssVars(resolved)` (returns a `CSSProperties` map of `--mero-*` variables for applying to your own container) are exported for advanced use.
+
+**Browser support**: hover-state and modal tints use CSS [`color-mix()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix), which requires Chrome 111+, Safari 16.2+, or Firefox 113+ (all 2023). On older browsers the bundled `styles.css` falls back to the default green `rgba()` for the button hover; the modal renders without subtle tints but is otherwise fully functional.
+
+### `<ConnectButton>` props
 
+```tsx
+// Square 40×40 icon button — logo only, no text
+<ConnectButton logoOnly />
+
+// Custom label (shorthand: bare string overrides the disconnected label)
+<ConnectButton label="Sign in with Calimero" />
+
+// Per-state label overrides
+<ConnectButton
+  label={{
+    connect: 'Sign in',
+    connected: 'Signed in',
+    reconnecting: 'Reconnecting…',
+  }}
+/>
+```
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `connectionType` | `ConnectionType \| CustomConnectionConfig` | `RemoteAndLocal` | Which options the embedded LoginModal shows. `Custom` skips the modal. |
+| `theme` | `MeroTheme` | — | Partial token override. |
+| `logoOnly` | `boolean` | `false` | Render only the Calimero logo (square button). The label is still announced via `aria-label`. |
+| `label` | `string \| { connect?, connected?, reconnecting? }` | — | Override default labels. Bare string targets the disconnected state. |
+| `className` / `style` | — | — | Forwarded to the inner `<button>`. |
+
+## Enums
+
+```tsx
 AppMode.SingleContext   // 'single-context'
 AppMode.MultiContext    // 'multi-context'
 AppMode.Admin           // 'admin'
 
-ConnectionType.Custom   // 'custom'
-ConnectionType.Local    // 'local'
-ConnectionType.Remote   // 'remote'
-
+ConnectionType.RemoteAndLocal  // 'remote-and-local'
+ConnectionType.Remote          // 'remote'
+ConnectionType.Local           // 'local'
+ConnectionType.Custom          // 'custom'
 ```
 
 ## Types
 
 ```tsx
 import type {
-  MeroContextValue,      // useMero() return type
-  MeroProviderConfig,    // MeroProvider props (without children)
-  MeroProviderProps,     // MeroProvider props (with children)
-  CustomConnectionConfig,// { type: ConnectionType.Custom, url: string }
-  AppContext,            // { contextId, executorId, applicationId }
-  ExecutionResult,       // { success, result?, error? }
+  MeroContextValue,        // useMero() return type
+  MeroProviderConfig,      // MeroProvider props (without children)
+  MeroProviderProps,       // MeroProvider props (with children)
+  CustomConnectionConfig,  // { type: ConnectionType.Custom, url: string }
+  AppContext,              // { contextId, executorId, applicationId }
+  ExecutionResult,         // { success, result?, error? }
+  ApplicationContextRecord,// { contextId, applicationId }
+  ContextDiscoveryOptions, // options for useContextDiscovery
+  ContextDiscoveryState,   // return type of useContextDiscovery
+  MeroTheme,               // partial theme override for ConnectButton / LoginModal
+  ResolvedMeroTheme,       // fully populated theme returned by resolveMeroTheme()
 } from '@calimero-network/mero-react';
 ```
 
 ## Full exports list
 
 ```
-// Provider & hooks (mero-react)
+// Provider & context (mero-react)
 MeroProvider, useMero, MeroContext
-useExecute, useSubscription, useContexts
+
+// Components (mero-react)
+ConnectButton, LoginModal
+
+// Theming (mero-react)
+MeroTheme, ResolvedMeroTheme, defaultMeroTheme, resolveMeroTheme, themeToCssVars
 
 // Enums (mero-react)
+AppMode, ConnectionType
+
+// Hooks (mero-react)
+useExecute, useSubscription
+useContexts, useApplicationContexts, useContextGroup, useContextDiscovery
+useCreateContext, useDeleteContext, useJoinContext
+useGroupInfo, useGroupMembers, useGroupContexts, useGroupInvitations, useGroupCapabilities
+useJoinGroup, useDeleteGroup, useAddGroupMembers, useRemoveGroupMembers
+useSyncGroup, useNestGroup, useUnnestGroup, useSubgroups
+useUpgradeGroup, useGroupUpgradeStatus, useRetryGroupUpgrade
+useRegisterGroupSigningKey, useUpdateGroupSettings
+useSetGroupAlias, useSetMemberAlias, useUpdateMemberRole
+useSetDefaultCapabilities, useSetSubgroupVisibility, useSetTeeAdmissionPolicy
+useDetachContextFromGroup
+useNamespaces, useNamespace, useNamespaceGroups, useNamespaceIdentity
+useNamespacesForApplication, useCreateNamespace, useDeleteNamespace
+useJoinNamespace, useCreateNamespaceInvitation, useCreateGroupInNamespace
 
 // Types (mero-react)
 MeroContextValue, MeroProviderConfig, MeroProviderProps
 CustomConnectionConfig, AppContext, ExecutionResult
+ApplicationContextRecord, ContextDiscoveryOptions, ContextDiscoveryState
 
 // Storage (mero-react)
 localStorageTokenStorage
 getNodeUrl, setNodeUrl, clearNodeUrl
 getApplicationId, setApplicationId, clearApplicationId
+getContextId, setContextId, clearContextId
+getContextIdentity, setContextIdentity, clearContextIdentity
 clearAllStorage
 
 // Everything from @calimero-network/mero-js (auto re-exported)