diff --git a/README.md b/README.md index c103f7f9..d64c0e0e 100644 --- a/README.md +++ b/README.md @@ -55,9 +55,7 @@ pnpm lint ## Documentation -- **[Architecture Guide](./docs/ARCHITECTURE.md)** - Tech stack, data fetching patterns, and developer guide -- **[Styling Guide](./docs/Styling.md)** - UI component patterns and design system -- **[Code Standards](./.claude/CLAUDE.md)** - Code quality guidelines (Biome/Ultracite) +- **[Developer Guide](./docs/DEVELOPER_GUIDE.md)** - Architecture, state management, components, and styling ## Security diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md deleted file mode 100644 index c5720b30..00000000 --- a/docs/ARCHITECTURE.md +++ /dev/null @@ -1,432 +0,0 @@ -# Monarch Architecture - -Technical reference for Monarch's key configurations and integrations. - ---- - -## System Overview - -Monarch is an interface for Morpho Blue lending markets with maximized customizability: - -- **Dual data sources**: Morpho API (primary) → Subgraph (fallback) -- **Custom RPCs**: User-configurable per-network RPC endpoints -- **Oracle integration**: Parsing Chainlink, Redstone, and Compound price feeds -- **Token management**: Whitelist system -- **Merkl rewards**: External rewards campaign integration -- **Trusted-vaults filters**: Allow filtering through customizable vaults - -**Tech stack**: React 18 · Next.js 15 · TypeScript · Wagmi · TanStack Query · Biome - -**State management**: See [STATE_MANAGEMENT.md](./STATE_MANAGEMENT.md) for React Query + Zustand patterns - -**Data prefetching**: Critical queries (markets, tokens, campaigns, oracles) prefetch on app mount via `DataPrefetcher` component for instant navigation - ---- - -## Data Sources - -### Morpho API vs Subgraph - -Data fetching uses a fallback pattern for reliability: - -``` -1. Try Morpho API (if network supported) - ↓ fails -2. Fallback to The Graph Subgraph - ↓ optional -3. Enhance with on-chain RPC data -``` - -**Network support config**: `src/config/dataSources.ts` - -```typescript -export const supportsMorphoApi = (network: SupportedNetworks): boolean => { - // Returns true for: Mainnet, Base, Unichain, Polygon, Arbitrum, HyperEVM, Monad - // Returns false for networks without Morpho API support -}; -``` - -**Data source files**: -- `src/data-sources/morpho-api/` - Primary GraphQL fetchers -- `src/data-sources/subgraph/` - Fallback GraphQL fetchers - -**Subgraph URLs**: `src/utils/subgraph-urls.ts` - ---- - -## Custom RPC Configuration - -Users can override default RPC endpoints per network. - -**Implementation**: `src/hooks/useCustomRpc.ts` - -```typescript -const { customRpcUrls, setRpcUrl, resetRpcUrl } = useCustomRpc(); - -// Set custom RPC for a network -setRpcUrl(SupportedNetworks.Mainnet, 'https://my-custom-rpc.com'); - -// Reset to default -resetRpcUrl(SupportedNetworks.Mainnet); -``` - -**Storage**: RPC URLs stored in browser localStorage under key `customRpcUrls` - -**Provider integration**: `src/components/providers/CustomRpcProvider.tsx` wraps Wagmi config - -**Default RPCs**: `src/utils/networks.ts` - `getDefaultRPC(chainId)` - ---- - -## Token Management - -### Token Whitelist - -**File**: `src/utils/tokens.ts` - -Defines all supported tokens with: -- Symbol, decimals, icon -- Multi-network addresses -- Optional protocol info -- Price peg (USD, ETH, BTC) for estimation - -**Example**: -```typescript -{ - symbol: 'USDC', - decimals: 6, - networks: [ - { chain: mainnet, address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' }, - { chain: base, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' }, - ], - peg: TokenPeg.USD, -} -``` - -### Finding Tokens - -**Function**: `findToken(address, chainId)` in `src/utils/tokens.ts` - -Returns token metadata if whitelisted, `undefined` otherwise. - ---- - -## Oracle Configuration - -Oracle price feed data is **pre-cached** to avoid runtime API calls. - -### Oracle Scripts - -Located in `scripts/`: - -| Script | Purpose | -|--------|---------| -| `generate-oracle-cache.ts` | Fetches all oracles from Morpho API, generates master cache | -| `generate-chainlink-data.ts` | Fetches Chainlink feed metadata per network | -| `generate-redstone-data.ts` | Fetches Redstone feed metadata per network | - -**Run oracle sync**: -```bash -pnpm generate:oracle # Master cache -pnpm generate:chainlink # Chainlink feeds -pnpm generate:redstone # Redstone feeds -``` - -### Oracle Cache Files - -**Master cache**: `src/constants/oracle/oracle-cache.json` -- All oracle addresses mapped to their metadata -- Indexed by network and oracle address - -**Chainlink data**: `src/constants/oracle/chainlink-data/{network}.json` -- Per-network Chainlink feed configurations -- Includes deviation thresholds, heartbeat - -**Redstone data**: `src/constants/oracle/redstone-data/{network}.json` -- Per-network Redstone feed configurations - -**Compound data**: `src/constants/oracle/compound/` (manually curated) - -### Using Oracle Data - -**Hook**: `src/hooks/queries/useOracleDataQuery.ts` - -```typescript -const { getOracleData } = useOracleDataQuery(); -const oracleInfo = getOracleData(oracleAddress, network); -``` - -Returns oracle type (Chainlink/Redstone/Compound), feed details, deviation thresholds. - ---- - -## Merkl Rewards Integration - -**File**: `src/utils/merklApi.ts` - -Fetches reward campaigns from Merkl API and matches them to Morpho markets. - -**Hook**: `useMerklCampaignsQuery()` in `src/hooks/queries/useMerklCampaignsQuery.ts` - -**Derived hook**: `useMarketCampaigns(marketId, network)` in `src/hooks/useMarketCampaigns.ts` - -**How it works**: -1. Fetch all campaigns from Merkl API for supported networks -2. Match campaigns to markets by checking campaign `mainParameter` (market address) -3. Cache results with React Query (5min stale time) - -**Display**: Reward APRs shown on market cards and detail pages - ---- - -## Trusted by Vaults - -Monarch allow users to choose which Morpho vaults they trust, and use them as filter on markets. - -**Registry**: `src/contexts/VaultRegistryContext.tsx` - -**Hook**: `useAllMorphoVaultsQuery()` in `src/hooks/queries/useAllMorphoVaultsQuery.ts` -- Fetches all vaults from Morpho API -- Caches with TanStack Query - -**Usage**: -```typescript -const { vaults, loading } = useVaultRegistry(); -const vault = getVaultByAddress(vaultAddress, chainId); -``` - -**Vault data source**: `src/data-sources/morpho-api/vaults.ts` - - ---- - -## Transaction Pattern - -**ExecuteTransactionButton** handles wallet connection + chain switching automatically. - -**Standard Pattern**: -```typescript -// 1. Transaction hook (approval + execution logic) -const { approveAndExecute, signAndExecute, isLoading } = useXTransaction({ ... }); - -// 2. Named callback with useCallback -const handleExecute = useCallback(() => { - if (!isApproved) { - void approveAndExecute(); - } else { - void signAndExecute(); - } -}, [isApproved, approveAndExecute, signAndExecute]); - -// 3. ExecuteTransactionButton (handles connection/chain switching) - - Execute - -``` - -**Dynamic Button Text**: -```typescript -const getButtonText = () => { - if (isDeploying) return 'Deploying...'; - if (!ready) return 'Select Item'; - return 'Execute'; -}; - - - {getButtonText()} - -``` - -**Rules**: -- Always use `useCallback` for onClick handlers -- Never put complex logic directly in `onClick` -- Button shows "Connect Wallet" / "Switch Chain" / action text automatically - ---- - -## Component Architecture - -Monarch follows a **feature-based architecture** optimized for Next.js 15 App Router best practices. - -### Core Principles - -**1. `app/` is for Routing, `src/` is for Logic** - -The `app/` directory is a thin routing layer. Each `page.tsx` file: -- Exports metadata for SEO -- Handles URL parameters (server-side) -- Renders a single "View" component from `src/features/` - -**Example** (`app/markets/page.tsx`): -```typescript -import { MarketsView } from '@/features/markets/markets-view'; - -export const metadata = { title: 'Markets' }; - -export default function Page() { - return ; -} -``` - -**2. Features Group Related Logic** - -Each feature in `src/features/` contains: -- Main view component (`{feature}-view.tsx`) -- Supporting components (`components/`) -- Feature-specific hooks (`hooks/`) -- Feature-specific utilities (`utils/`) - -**3. Clear Component Hierarchy** - -``` -src/components/ -├── ui/ # Design system primitives (Button, Badge, Spinner) -├── shared/ # Cross-feature, business-agnostic components -├── layout/ # Layout wrappers (Header, Footer) -└── providers/ # Context providers -``` - -### Feature Structure - -Each feature follows this pattern: - -``` -src/features/{feature-name}/ -├── {feature-name}-view.tsx # Main orchestrator (replaces old "Content") -├── components/ # Feature-specific components -│ ├── filters/ # Grouped by responsibility -│ ├── table/ -│ └── {component}.tsx -├── hooks/ # Feature-specific hooks (optional) -└── utils/ # Feature-specific utilities (optional) -``` - -**Current Features**: -- `markets/` - Market listing, filtering, settings -- `market-detail/` - Individual market pages (borrowers, suppliers, transactions) -- `positions/` - User positions, rebalancing, onboarding -- `positions-report/` - Position reporting -- `autovault/` - Vault listing, deployment, vault detail pages -- `rewards/` - Rewards tracking -- `history/` - Transaction history -- `admin/` - Admin dashboard - -### Global Modals - -Modals triggered from multiple places live in `src/modals/`: - -``` -src/modals/ -├── supply/ # Supply & withdraw flow -├── borrow/ # Borrow & repay flow -├── settings/ # Settings modals -├── wrap-process-modal.tsx -└── risk-notification-modal.tsx -``` - -### Component Guidelines - -**When to use `src/components/ui/`**: -- Zero business logic -- Purely presentational (Button, Badge, Table) -- Shadcn/Radix primitives - -**When to use `src/components/shared/`**: -- Reusable across multiple features -- Business-agnostic (TokenIcon, AccountIdentity, TablePagination) -- No domain-specific logic - -**When to use `src/features/{feature}/components/`**: -- Feature-specific component -- Contains domain logic for that feature -- Used only within that feature's pages - -**When to use `src/modals/`**: -- Modal triggered from multiple locations -- Global state-managed modals -- Complex multi-step flows (supply, borrow) - ---- - -## Common Tasks - -### Adding a New Page/Feature - -1. **Create the page route** in `app/{feature}/page.tsx`: - ```typescript - import { FeatureView } from '@/features/{feature}/{feature}-view'; - - export const metadata = { title: 'Feature Name' }; - - export default function Page() { - return ; - } - ``` - -2. **Create the feature directory** in `src/features/{feature}/`: - ``` - src/features/{feature}/ - ├── {feature}-view.tsx # Main view component - └── components/ # Feature-specific components - ``` - -3. **Build the view component** (`{feature}-view.tsx`): - - Add `'use client'` if using hooks/state - - Import shared components from `@/components/shared/` - - Import UI primitives from `@/components/ui/` - - Keep feature logic self-contained - -### Adding a New Component - -**Ask yourself**: Where does this component belong? - -1. **Is it a pure UI primitive?** → `src/components/ui/` - - No business logic - - Highly reusable (Button, Input, Card) - - Example: `button.tsx`, `badge.tsx` - -2. **Is it reusable across features but not a primitive?** → `src/components/shared/` - - Business-agnostic - - Used in 2+ features - - Example: `token-icon.tsx`, `account-identity.tsx` - -3. **Is it specific to one feature?** → `src/features/{feature}/components/` - - Contains domain logic - - Only used in one feature - - Example: `markets/components/market-identity.tsx` - -4. **Is it a global modal?** → `src/modals/` - - Triggered from multiple places - - Multi-step flows - - Example: `supply/supply-modal.tsx` - -### Adding a New Token - -1. Add token to `src/utils/tokens.ts` in the `supportedTokens` array -2. Include symbol, decimals, icon path, network addresses -3. Optionally set `peg` for USD estimation - -### Adding a Network - -1. Add to `SupportedNetworks` enum in `src/utils/networks.ts` -2. Update `supportsMorphoApi()` in `src/config/dataSources.ts` -3. Add subgraph URL to `src/utils/subgraph-urls.ts` (if available) -4. Add default RPC to `getDefaultRPC()` in `src/utils/networks.ts` -5. Run oracle scripts to generate cache for new network - -### Refreshing Oracle Data - -```bash -pnpm generate:oracle # Refresh all oracles -pnpm generate:chainlink # Refresh Chainlink feeds -pnpm generate:redstone # Redstone feeds -``` - -Commit updated JSON files in `src/constants/oracle/` - ---- diff --git a/docs/DEVELOPER_GUIDE.md b/docs/DEVELOPER_GUIDE.md new file mode 100644 index 00000000..f7a69b27 --- /dev/null +++ b/docs/DEVELOPER_GUIDE.md @@ -0,0 +1,757 @@ +# Monarch Developer Guide + +Consolidated reference for state management, components, and architecture. + +--- + +## 1. Quick Reference + +### State Management Decision Tree + +``` +External Data (API, blockchain) → React Query +User Preferences (persist across refresh) → Zustand + persist +Shared UI State (modals, selections, operations) → Zustand +Computed/Derived → useMemo Hook +Local UI State (single component) → useState +``` + +### Component Location Rules + +``` +src/components/ui/ → Pure UI primitives (Button, Badge, Table) +src/components/shared/ → Cross-feature components (TokenIcon, AccountIdentity) +src/features/{name}/ → Feature-specific components +src/modals/ → Global modals (multi-trigger) +``` + +### Modal Pattern Decision + +``` +Single trigger, depth 0-1 → Local state (useState) +Multi-trigger (2+ places) → Zustand (useModal hook) +Props drilling pain (3+ levels) → Zustand +Modal chaining → Zustand +``` + +### File Naming + +- Stores: `src/stores/use{Feature}{State}.ts` +- Queries: `src/hooks/queries/use{Entity}Query.ts` +- Derived hooks: `src/hooks/use{Processed|Filtered}{Entity}.ts` +- Features: `src/features/{name}/{name}-view.tsx` + +--- + +## 2. State Management + +### React Query (External Data) + +**Location:** `src/hooks/queries/use{Entity}Query.ts` + +```typescript +export const useMarketsQuery = () => { + return useQuery({ + queryKey: ['markets'], + queryFn: fetchMarkets, + staleTime: 5 * 60 * 1000, + }); +}; + +// Usage +const { data, isLoading } = useMarketsQuery(); +``` + +### Zustand + Persist (User Preferences) + +**Location:** `src/stores/use{Feature}{State}.ts` + +```typescript +export const useMarketsFilters = create( + persist( + (set) => ({ + selectedNetwork: null, + setSelectedNetwork: (network) => set({ selectedNetwork: network }), + }), + { name: 'monarch_store_marketsFilters' } + ) +); + +// Usage - separate selectors for primitives +const network = useMarketsFilters((s) => s.selectedNetwork); +const setNetwork = useMarketsFilters((s) => s.setSelectedNetwork); +``` + +### Zustand (Shared UI State) + +**Location:** `src/stores/use{Feature}Store.ts` + +```typescript +// Modal state +export const useVaultModalStore = create((set) => ({ + isOpen: false, + open: () => set({ isOpen: true }), + close: () => set({ isOpen: false }), +})); + +// Selection state +export const useTableSelectionStore = create((set) => ({ + selectedIds: [], + toggleSelection: (id) => set((state) => ({ + selectedIds: state.selectedIds.includes(id) + ? state.selectedIds.filter((i) => i !== id) + : [...state.selectedIds, id] + })), + clearSelection: () => set({ selectedIds: [] }), +})); +``` + +### Derived Data Hooks + +**Location:** `src/hooks/use{Processed|Filtered}{Entity}.ts` + +```typescript +export const useFilteredMarkets = () => { + const { data } = useMarketsQuery(); + const searchQuery = useMarketsFilters((s) => s.searchQuery); + + return useMemo(() => { + return data + .filter((m) => m.symbol.includes(searchQuery)) + .sort((a, b) => b.tvl - a.tvl); + }, [data, searchQuery]); +}; +``` + +### Anti-Patterns + +```typescript +// ❌ Don't fetch in Context +const Provider = () => { + useEffect(() => { fetch().then(setData); }, []); + return {children}; +}; +// ✅ Use React Query +const useDataQuery = () => useQuery({ queryKey: ['data'], queryFn: fetch }); +``` + +```typescript +// ❌ Don't create objects in selectors (infinite loop) +const filters = useStore((s) => s.filters ?? { min: '0' }); +// ✅ Return primitives +const min = useStore((s) => s.filters?.min ?? '0'); +``` + +```typescript +// ❌ Don't use useState for shared state +const [modalOpen, setModalOpen] = useState(false); +// Then pass through 3 levels of props... +// ✅ Use Zustand for shared UI state +const useModalStore = create((set) => ({ + isOpen: false, + open: () => set({ isOpen: true }), +})); +``` + +```typescript +// ❌ Don't chain useEffect +useEffect(() => { setFiltered(data.filter(...)); }, [data]); +useEffect(() => { setSorted(filtered.sort(...)); }, [filtered]); +// ✅ Use useMemo +const processed = useMemo(() => data.filter(...).sort(...), [data]); +``` + +--- + +## 3. Component Usage Guide + +### Modal + +**Import:** `@/components/common/Modal` + +Always use our custom Modal components. The shared wrapper applies Monarch typography, corner radius, background, blur, and z-index rules automatically. + +```tsx +import { Modal, ModalHeader, ModalBody, ModalFooter } from '@/components/common/Modal'; +import { Button } from '@/components/ui/button'; +``` + +#### Standard Modal (settings, workflows) + +```tsx + + + + {/* Modal content */} + + + + + + +``` + +#### Compact Modal (filters, confirmations) + +```tsx + + + + {/* Tighter spacing applied automatically */} + + + + + + +``` + +#### With Icon + +```tsx +} +/> +``` + +#### Z-Index Layers + +```tsx +zIndex="base" // z-50 - Standard modals (Supply, Borrow) +zIndex="process" // z-1100 - Process/transaction modals +zIndex="selection" // z-2200 - Market/item selection modals +zIndex="settings" // z-2300 - Settings modals (HIGHEST) +``` + +#### Modal State Patterns + +**Pattern 1: Local State (Default)** +```tsx +const [showModal, setShowModal] = useState(false); +{showModal && setShowModal(false)} />} +``` + +**Pattern 2: Global State (Zustand)** +```tsx +const { open } = useModal(); + +``` + +Use Pattern 2 only when: multi-trigger (2+ places), props drilling pain, or modal chaining. + +--- + +### Button + +**Import:** `@/components/ui/button` + +```tsx +import { Button } from '@/components/ui/button'; + +// Primary - main actions + + +// Surface - actions in cards, tables + + +// Default - navigation + + +// Ghost - icon buttons + +``` + +**Variants:** `primary` | `surface` | `default` | `ghost` +**Sizes:** `xs` | `sm` | `md` | `lg` | `icon` + +When wrapping Button in Tooltip, wrap it in a `` to prevent ResizeObserver errors. + +--- + +### Table + +**Import:** `@/components/ui/table` + +Never use raw HTML `` tags. + +```tsx +import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@/components/ui/table'; +import { TablePagination } from '@/components/common/TablePagination'; + +
+ + + Name + Amount + + + + + John + $100 + + +
+ + +``` + +**Rules:** +- Use `table-body-compact` on `` for activity tables +- Headers and cells must match alignment (`text-left`, `text-right`, `text-center`) +- Amount columns: use flexbox with `justify-end` + +--- + +### TableContainerWithHeader + +**Import:** `@/components/common/table-container-with-header` + +```tsx +import { TableContainerWithHeader } from '@/components/common/table-container-with-header'; + +// Simple + + {/* content */}
+ + +// With actions + + + + + } +> + {/* content */}
+ +``` + +**Props:** `title`, `actions?`, `children`, `className?` + +--- + +### TablePagination + +**Import:** `@/components/common/TablePagination` + +```tsx +import { TablePagination } from '@/components/common/TablePagination'; + + +``` + +**Props:** `currentPage`, `totalPages`, `totalEntries`, `pageSize`, `onPageChange`, `isLoading?`, `showEntryCount?` + +--- + +### Tooltip + +**Import:** `@/components/ui/tooltip` + +```tsx +import { Tooltip } from '@/components/ui/tooltip'; + +// Basic + + + + +// With placement and delay + + Hover + +``` + +#### Structured Content + +```tsx +import { TooltipContent } from '@/components/shared/tooltip-content'; + +} + title="Title" + detail="Detail text" + secondaryDetail="Secondary detail" + /> + } +> + + +``` + +**Props:** `content`, `placement` (`top` | `bottom` | `left` | `right`), `delay` (ms) +**TooltipContent Props:** `icon`, `title`, `detail`, `secondaryDetail`, `actionIcon`, `actionHref` + +--- + +### Switch + +**Import:** `@/components/ui/icon-switch` + +```tsx +import { IconSwitch } from '@/components/ui/icon-switch'; + +// Plain switch + + +// With icon + +``` + +**Sizes:** `xs` | `sm` | `md` | `lg` + +--- + +### Checkbox + +**Import:** `@/components/ui/checkbox` + +```tsx +import { Checkbox } from '@/components/ui/checkbox'; + + + + +``` + +**Variants:** `default` | `highlighted` + +--- + +### Dropdown Menu + +**Import:** `@/components/ui/dropdown-menu` + +```tsx +import { + DropdownMenu, + DropdownMenuTrigger, + DropdownMenuContent, + DropdownMenuItem, + DropdownMenuSeparator, + DropdownMenuCheckboxItem, +} from '@/components/ui/dropdown-menu'; + + + + + + + Action + }>With Icon + + + Toggle Item + + + +``` + +**Alignment:** `align="start"` | `"center"` | `"end"` + +--- + +### Input + +#### Numerical Inputs (Amounts) + +```tsx +import Input from '@/components/Input/Input'; + + +``` + +#### Text Inputs + +```tsx + handleChange(e.target.value)} + className="bg-hovered h-10 w-full rounded p-2 focus:border-primary focus:outline-none" +/> +``` + +#### Error States + +```tsx +className={`bg-hovered h-10 w-full rounded p-2 focus:border-primary focus:outline-none ${ + error ? 'border border-red-500 focus:border-red-500' : '' +}`} + +{error &&

{error}

} +``` + +--- + +### AccountIdentity + +**Import:** `@/components/common/AccountIdentity` + +```tsx +import { AccountIdentity } from '@/components/common/AccountIdentity'; + +// Badge - minimal inline (no avatar) + + +// Compact - small avatar + text in badge + + +// Full - avatar + address badge + extra info badges + +``` + +**Variants:** `badge` | `compact` | `full` + +--- + +### MarketIdentity + +**Import:** `@/components/MarketIdentity` + +```tsx +import { MarketIdentity, MarketIdentityMode, MarketIdentityFocus } from '@/components/MarketIdentity'; + +// Normal mode - both assets shown equally + + +// Focused mode - emphasizes one asset + + +// Minimum mode - only focused asset + +``` + +**Modes:** `Normal` | `Focused` | `Minimum` + +--- + +### MarketDetailsBlock + +**Import:** `@/components/common/MarketDetailsBlock` + +```tsx +import { MarketDetailsBlock } from '@/components/common/MarketDetailsBlock'; + + +``` + +--- + +### TransactionIdentity + +**Import:** `@/components/common/TransactionIdentity` + +```tsx +import { TransactionIdentity } from '@/components/common/TransactionIdentity'; + + + +``` + +--- + +### CollateralIconsDisplay + +**Import:** `@/features/positions/components/collateral-icons-display` + +```tsx +import { CollateralIconsDisplay } from '@/features/positions/components/collateral-icons-display'; + + +``` + +**Props:** `collaterals`, `chainId`, `maxDisplay?` (default 8), `iconSize?` (default 20) + +--- + +### Toast + +**Import:** `@/hooks/useStyledToast` + +```tsx +import { useStyledToast } from '@/hooks/useStyledToast'; + +const { success, error } = useStyledToast(); + +success('Success', 'Detail of the success'); +error('Error', 'Detail of the error'); +``` + +--- + +## 4. Architecture + +### Tech Stack + +React 18 · Next.js 15 · TypeScript · Wagmi · TanStack Query · Biome + +### Feature Structure + +``` +src/features/{feature-name}/ +├── {feature-name}-view.tsx # Main orchestrator +├── components/ # Feature-specific components +│ ├── filters/ +│ ├── table/ +│ └── {component}.tsx +├── hooks/ # Feature-specific hooks (optional) +└── utils/ # Feature-specific utilities (optional) +``` + +### Component Hierarchy + +``` +src/components/ +├── ui/ # Design system primitives (Button, Badge, Spinner) +├── shared/ # Cross-feature, business-agnostic components +├── common/ # Common layout components (Modal, TableContainer) +├── layout/ # Layout wrappers (Header, Footer) +└── providers/ # Context providers +``` + +### Data Flow + +``` +1. Try Morpho API (if network supported) + ↓ fails +2. Fallback to The Graph Subgraph + ↓ optional +3. Enhance with on-chain RPC data +``` + +### Transaction Pattern + +```typescript +// 1. Transaction hook +const { approveAndExecute, signAndExecute, isLoading } = useXTransaction({ ... }); + +// 2. Named callback with useCallback +const handleExecute = useCallback(() => { + if (!isApproved) { + void approveAndExecute(); + } else { + void signAndExecute(); + } +}, [isApproved, approveAndExecute, signAndExecute]); + +// 3. ExecuteTransactionButton (handles connection/chain switching) + + Execute + +``` + +--- + +## 5. Styling Guidelines + +### Rounding + +- `rounded` - Modals, Cards, Tables, large containers +- `rounded-sm` - Buttons, Inputs, Tooltips, Tags + +### Background + +- `bg-surface` - First layer components +- `bg-hovered` - Hoverable elements or components on bg-surface + +### Typography + +- Avoid bold weights for emphasis +- Use `text-primary` / `text-secondary` for hierarchy +- Prefer `font-zen` for vault UI surfaces diff --git a/docs/STATE_MANAGEMENT.md b/docs/STATE_MANAGEMENT.md deleted file mode 100644 index 8d5f7f09..00000000 --- a/docs/STATE_MANAGEMENT.md +++ /dev/null @@ -1,191 +0,0 @@ -# State Management Guide - -Quick reference for choosing the right pattern. - ---- - -## Decision Tree - -``` -External Data (API, blockchain) → React Query -User Preferences (persist across refresh) → Zustand + persist -Shared UI State (modals, selections, operations) → Zustand -Computed/Derived → useMemo Hook -Local UI State (single component) → useState -``` - ---- - -## 1. React Query - -**When:** Fetching external data -**Location:** `src/hooks/queries/use{Entity}Query.ts` - -```typescript -export const useMarketsQuery = () => { - return useQuery({ - queryKey: ['markets'], - queryFn: fetchMarkets, - staleTime: 5 * 60 * 1000, - }); -}; - -// Usage -const { data, isLoading } = useMarketsQuery(); -``` - ---- - -## 2. Zustand Stores - -### 2a. With Persist (User Preferences) - -**When:** Filters, settings, preferences that should survive refresh -**Location:** `src/stores/use{Feature}{State}.ts` - -```typescript -export const useMarketsFilters = create( - persist( - (set) => ({ - selectedNetwork: null, - setSelectedNetwork: (network) => set({ selectedNetwork: network }), - }), - { name: 'monarch_store_marketsFilters' } - ) -); - -// Usage - separate selectors for primitives -const network = useMarketsFilters((s) => s.selectedNetwork); -const setNetwork = useMarketsFilters((s) => s.setSelectedNetwork); -``` - -### 2b. Without Persist (Shared UI State) - -**When:** State shared across components but doesn't need persistence -**Use cases:** Modals, selections, operation states, multi-step flows -**Location:** `src/stores/use{Feature}Store.ts` - -```typescript -// Modal state -export const useVaultModalStore = create((set) => ({ - isOpen: false, - open: () => set({ isOpen: true }), - close: () => set({ isOpen: false }), -})); - -// Selection state -export const useTableSelectionStore = create((set) => ({ - selectedIds: [], - toggleSelection: (id) => set((state) => ({ - selectedIds: state.selectedIds.includes(id) - ? state.selectedIds.filter((i) => i !== id) - : [...state.selectedIds, id] - })), - clearSelection: () => set({ selectedIds: [] }), -})); - -// Operation state -export const useOperationStore = create((set) => ({ - isProcessing: false, - currentStep: 1, - setProcessing: (processing) => set({ isProcessing: processing }), - nextStep: () => set((state) => ({ currentStep: state.currentStep + 1 })), -})); -``` - ---- - -## 3. Derived Data Hooks - -**When:** Filtering, sorting, enriching data -**Location:** `src/hooks/use{Processed|Filtered}{Entity}.ts` - -```typescript -export const useFilteredMarkets = () => { - const { data } = useMarketsQuery(); - const searchQuery = useMarketsFilters((s) => s.searchQuery); - - return useMemo(() => { - return data - .filter((m) => m.symbol.includes(searchQuery)) - .sort((a, b) => b.tvl - a.tvl); - }, [data, searchQuery]); -}; -``` - ---- - -## 4. Component State - -**When:** Ephemeral UI state in a single component - -```typescript -function Modal() { - const [amount, setAmount] = useState(''); - return ; -} -``` - ---- - -## Anti-Patterns - -```typescript -// ❌ Don't fetch in Context -const Provider = () => { - useEffect(() => { fetch().then(setData); }, []); - return {children}; -}; - -// ✅ Use React Query -const useDataQuery = () => useQuery({ queryKey: ['data'], queryFn: fetch }); -``` - -```typescript -// ❌ Don't create objects in selectors (infinite loop) -const filters = useStore((s) => s.filters ?? { min: '0' }); - -// ✅ Return primitives -const min = useStore((s) => s.filters?.min ?? '0'); -``` - -```typescript -// ❌ Don't use useState for shared state -const [modalOpen, setModalOpen] = useState(false); -const [selectedIds, setSelectedIds] = useState([]); -// Then pass through 3 levels of props... - -// ✅ Use Zustand for shared UI state -const useModalStore = create((set) => ({ - isOpen: false, - open: () => set({ isOpen: true }), -})); -``` - -```typescript -// ❌ Don't chain useEffect -useEffect(() => { setFiltered(data.filter(...)); }, [data]); -useEffect(() => { setSorted(filtered.sort(...)); }, [filtered]); - -// ✅ Use useMemo -const processed = useMemo(() => data.filter(...).sort(...), [data]); -``` - ---- - -## Quick Reference - -| Pattern | Use Case | Location | -|---------|----------|----------| -| React Query | External data | `src/hooks/queries/` | -| Zustand + persist | User preferences | `src/stores/` | -| Zustand | Shared UI state (modals, selections, operations) | `src/stores/` | -| Derived Hook | Computed data | `src/hooks/` | -| useState | Local component state | Component | - -**Before creating Context:** -- External data? → React Query -- Persisted preferences? → Zustand + persist -- Shared UI state? → Zustand -- Computed data? → Derived hook -- Local UI? → useState diff --git a/docs/Styling.md b/docs/Styling.md deleted file mode 100644 index c36632de..00000000 --- a/docs/Styling.md +++ /dev/null @@ -1,998 +0,0 @@ -# Styling and CSS Guidelines - -## Core Components - -Use these shared components instead of raw HTML elements: - -- `Button`: Import from `@/components/ui/button` for all clickable actions -- `Modal`: For **all** modal dialogs (always import from `@/components/common/Modal`) -- `Card`: For contained content sections - -## Modal Guidelines - -**IMPORTANT**: Always use our custom Modal components from `@/components/common/Modal`. The shared wrapper applies Monarch typography, corner radius, background, blur, and z-index rules automatically. - -All modals MUST follow consistent styling standards for typography, spacing, and structure. There are two modal patterns based on use case. - -### Modal Types - -**1. Standard Modal** - For settings, management, and primary workflows -- Large settings modals (Trusted Vaults, Blacklisted Markets, Market Settings) -- Transaction modals (Rebalance, Market Selection) -- Onboarding and setup flows - -**2. Compact Modal** - For filters, confirmations, and secondary dialogs -- Filter modals (Supply Asset Filter) -- Confirmation dialogs (Blacklist Confirmation) - -### Using Our Modal Components - -Import the primitives from our shared entry point (and nowhere else): - -```tsx -import { Modal, ModalHeader, ModalBody, ModalFooter } from '@/components/common/Modal'; -import { Button } from '@/components/ui/button'; -``` - -### Modal State Management: Two Patterns - -**DEFAULT: Use Pattern 1 (Local State) for most modals.** - -Use Pattern 2 (Zustand) ONLY when: -- ✓ Multiple unrelated trigger locations (2+ places) -- ✓ Props drilling pain (passing callbacks through 2+ levels) -- ✓ Modal chaining (modal opens from within another modal) - ---- - -#### Pattern 1: Local State (Default) ✅ - -State lives in parent component. Modal receives `isOpen` and `onClose` props. - -```tsx -const [showModal, setShowModal] = useState(false); -{showModal && setShowModal(false)} />} -``` - -**When:** Single usage location, no props drilling pain, state available in parent. - -**Examples:** RebalanceModal, VaultSettingsModal, BorrowModal, all process/filter modals. - ---- - -#### Pattern 2: Global State (Zustand) 🌐 - -Modal opened via `useModal()` hook from anywhere. No local state needed. - -```tsx -const { open } = useModal(); - -``` - -**Setup:** Add to `useModalStore.ts` ModalProps type → Register in `registry.tsx` → Use `useModal()` hook. - -**When:** Multi-trigger (2+ unrelated places), props drilling pain, modal chaining. - -**Examples:** SupplyModalV2 (3 triggers), MarketSettingsModal (2 triggers + chaining), TrustedVaultsModal (modal chaining). - ---- - -#### The "Trigger Depth" Decision Framework - -**Trigger Depth = Component levels between state and trigger button** - -``` -Depth 0: Button & state in same file → Pattern 1 ✅ -Depth 1: Parent (state) → Child (button) → Pattern 1 ✅ -Depth 2-3: Deep nesting → Pattern 1 OK if no pain, else Pattern 2 -Multi-trigger: Different locations → Pattern 2 ✅ -``` - -**Migration Checklist:** -1. Used from 2+ unrelated places? → Migrate ✅ -2. Painful props drilling (3+ levels)? → Migrate ✅ -3. Modal chaining? → Migrate ✅ -4. Otherwise? → Keep local ✅ - ---- - -### Complete Modal Inventory (28 Total) - -#### Pattern 2: Zustand (5 modals) - Already Migrated ✅ -| Modal | Triggers | Depth | Reason | -|-------|----------|-------|--------| -| SupplyModalV2 | Markets, Market Detail, Positions (3) | 0-3 | Multi-trigger | -| MarketSettingsModal | 2 tables | 1-2 | Multi-trigger + chaining | -| TrustedVaultsModal | Settings + chained from MarketSettings (3) | 0-2 | Modal chaining | -| BridgeSwapModal | Chained from SupplyModal (1) | N/A | Modal chaining | -| BlacklistedMarketsModal | Settings (1) | 0 | Consistency with TrustedVaults | - -#### Pattern 1: Local State (23 modals) - Keep As-Is ✅ - -**Feature Modals (8):** -- RebalanceModal - positions-view (Depth 0, single use) -- VaultSettingsModal - vault-view (Depth 0-1, single use, many props) -- BorrowModal - market-view (Depth 0, single use) -- DepositToVaultModal - vault-view (Depth 0, single use) -- OnboardingModal - positions-view (Depth 0, single use) -- CampaignModal - market-view (Depth 0, single use) -- VaultInitializationModal - vault-view (Depth 0, single use) -- DeploymentModal - autovault (Depth 0, single use) - -**Utility Modals (2):** -- MarketSelectionModal - Reusable utility, used by RebalanceModal (Depth 0) -- BlacklistConfirmationModal - Inline confirmation (Depth 0) - -**Info Modals (2):** -- ChainlinkRiskTiersModal - Informational (Depth 0) -- RedstoneTypesModal - Informational (Depth 0) - -**Process Modals (6):** Transaction flows, always local -- SupplyProcessModal, BorrowProcessModal, RepayProcessModal -- RebalanceProcessModal, VaultDepositProcessModal, WrapProcessModal - -**Filter Modals (3):** Always scoped to parent view -- BorrowerFiltersModal, SupplierFiltersModal, TransactionFiltersModal - -**Settings Modals (2):** -- AddMarketCapModal - vault settings tab (Depth 1) -- RiskNotificationModal - settings (Depth 0) - -### Standard Modal Pattern - -Use this pattern for primary workflows, settings, and management interfaces: - -```tsx - - - - - {/* Modal content - spacing and font-zen applied automatically */} - - - - - - - -``` - -**With Icon Support:** - -```tsx -import { TokenIcon } from '@/components/TokenIcon'; - - - - } - /> - {/* content */} - -``` - -**With Actions in Header:** - -```tsx - - Refresh - - } -/> -``` - -**Auto-Applied Standards:** -- **Spacing**: Automatically applied based on variant (no extra padding needed) -- **Typography**: `font-zen` and text scales handled for you -- **Icon + actions slots**: Header provides `mainIcon`, `actions`, and an always-on close button -- **Z-Index**: Managed through named layers (base, process, selection, settings) -- **Backdrops**: Unified blur/opacity, so you get consistent overlays everywhere -- **Portal**: All modals render to `document.body` to avoid stacking bugs - -### Compact Modal Pattern - -Use this pattern for filters, confirmations, and quick actions: - -```tsx - - - - - {/* Modal content - tighter spacing applied automatically */} - - - - - - - -``` - -**Auto-Applied Differences from Standard:** -- **Smaller padding**: `px-6 pt-4` vs `px-10 pt-6` -- **Smaller title**: `text-base` vs `text-lg` -- **Tighter spacing**: `gap-4` vs `gap-5` - -### Z-Index Management - -Our Modal component manages z-index automatically through named layers. This prevents conflicts when multiple modals are open: - -```tsx -// Z-Index Layers (from lowest to highest): -zIndex="base" // z-50 - Standard modals (Supply, Borrow, Campaign) -zIndex="process" // z-1100 - Process/transaction modals -zIndex="selection" // z-2200 - Market/item selection modals -zIndex="settings" // z-2300 - Settings modals (HIGHEST - always on top) -``` - -**Usage Example:** - -```tsx -// Settings modal (should be on top of everything) - - - {/* ... */} - - -// Market selection modal (opened from settings) - - - {/* ... */} - - -// Base modal (standard use case) - - - {/* ... */} - -``` - - -### Typography Rules - -Typography is automatically handled by our Modal components. You don't need to specify font weights or sizes manually - just use the title/description props. - -**IMPORTANT**: Never manually add bold or semibold font weights in modal headings/labels; rely on the shared components. - -```tsx -// ✅ Correct - let the component handle typography - - -// ❌ Incorrect - don't override with manual styles -Settings} /> -``` - -Use color and size to create hierarchy, not font weight: -- **Primary text**: `text-primary` -- **Secondary text**: `text-secondary` -- **Title size**: Automatically set based on variant -- **Description size**: Automatically set to `text-sm` - -### Section Headers in Modal Body - -For section headers within modal content, use consistent styling: - -```tsx -// ✅ Correct -

Section Title

-``` - -### Custom Modals - -For custom modals using `framer-motion`, apply `font-zen` to the outer container: - -```tsx -// ✅ Correct - font-zen on the modal overlay -
-
- {/* Modal content */} -
-
- -// With framer-motion - - - - {/* Modal content */} - - - -``` - -## Component Guidelines - -### Rounding - -- Use `rounded` for: - - Modals - - Cards - - Large content areas - - Container components - - Tables - - Market info blocks -- Use `rounded-sm` for: - - Buttons - - Inputs - - Filter components - - Small interactive elements - - Tooltips - - Tags/badges - - Helper text containers - -### Button - -Always use `Button` from `@/components/ui/button`. - -```tsx -import { Button } from '@/components/ui/button'; - -// Primary - main actions - - -// Surface - actions in cards, tables - - -// Default - navigation - - -// Ghost - icon buttons - -``` - -Variants: `primary` | `surface` | `default` | `ghost` -Sizes: `xs` | `sm` | `md` | `lg` | `icon` - -When wrapping Button in Tooltip, wrap it in a `` to prevent ResizeObserver errors. - -### Switch - -Always use `IconSwitch` from `@/components/ui/icon-switch`. - -```tsx -import { IconSwitch } from '@/components/ui/icon-switch'; - -// Plain switch (no icon) - - -// With icon -function ViewIcon({ isSelected, className }: { isSelected?: boolean; className?: string }) { - return isSelected ? : ; -} - - -``` - -Sizes: `xs` | `sm` | `md` | `lg` - -### Checkbox - -Always use `Checkbox` from `@/components/ui/checkbox`. - -```tsx -import { Checkbox } from '@/components/ui/checkbox'; - -// Default - - -// Highlighted - -``` - -Variants: `default` | `highlighted` - -### Dropdown Menu - -Always use `DropdownMenu` from `@/components/ui/dropdown-menu`. - -```tsx -import { - DropdownMenu, - DropdownMenuTrigger, - DropdownMenuContent, - DropdownMenuItem, - DropdownMenuSeparator, - DropdownMenuCheckboxItem, -} from '@/components/ui/dropdown-menu'; - -// Basic - - - - - - Action - - - -// With icons -}>Supply -}>Explorer - -// Sections - - -// Multi-select - - Item - - -// Prevent auto-close (for switches) - e.preventDefault()}> - {/* custom content */} - -``` - -Alignment: `align="start"` | `"center"` | `"end"` - -## Background, Border - -- Use `bg-surface` first layer components -- Use `bg-hovered` for hoverable elements or components on "bg-surface" - -## Tooltip - -### Basic Tooltip - -```tsx -import { Tooltip } from '@/components/ui/tooltip'; - - - - - - - Hover - - - - - -``` - -**Props:** `content`, `placement` (`top` | `bottom` | `left` | `right`), `delay` (ms), `className` - -### Structured Content - -```tsx -import { Tooltip } from '@/components/ui/tooltip'; -import { TooltipContent } from '@/components/shared/tooltip-content'; - -// Icon + title -} title="Title" />}> - - - -// With details -} - title="Title" - detail="Detail text" - secondaryDetail="Secondary detail" - /> - } -> - - - -// With action link -} - actionHref="https://..." - /> - } -> - - -``` - -**TooltipContent Props:** `icon`, `title`, `detail`, `secondaryDetail`, `className`, `actionIcon`, `actionHref`, `onActionClick` - -### Primitives - -```tsx -import { TooltipRoot, TooltipTrigger, TooltipContent } from '@/components/ui/tooltip'; - - - - - - - Custom content - - -``` - -### Provider - -```tsx -import { TooltipProvider } from '@/components/ui/tooltip'; - - - - -``` - -### Table Component - -**Always use Table components from `@/components/ui/table`** - never use raw HTML `` tags. - -**Components:** -```tsx -import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@/components/ui/table'; -import { TablePagination } from '@/components/common/TablePagination'; -``` - -**Basic Usage:** -```tsx -
- - - Name - Amount - - - - - John - $100 - - -
- -{/* Pagination - always use TablePagination */} - -``` - -**Key Rules:** - -1. **Variants**: Use `table-body-compact` on `` for activity/transaction tables (adds 6px cushion vs standard padding) -2. **Alignment**: Headers and cells must match - use `text-left`, `text-right`, or `text-center` -3. **Amount Columns**: Use flexbox with `justify-end` for right-aligned token icons, and use `text-sm` for text: - ```tsx - -
- {amount} - -
- - ``` -4. **Pagination**: Always use `TablePagination` component - -**Styling:** All styling applied via `app/global.css` - don't add inline styles or override padding. - -### TableContainerWithHeader Component - -**TableContainerWithHeader** (`@/components/common/table-container-with-header`) -- Standard wrapper for tables with header section -- Provides title on left, optional actions on right -- Consistent styling with border separator, overflow handling, and responsive layout - -**Structure:** -- Outer wrapper with `bg-surface`, `rounded-md`, `font-zen`, `shadow-sm` -- Header section with border bottom separator -- Title uses `font-monospace text-xs uppercase text-secondary` -- Actions area with flexbox gap spacing -- Overflow-x-auto wrapper for table content - -**Props:** -- `title`: Table heading (e.g., "Asset Activity", "Supplied Positions") -- `actions?`: Optional React node for controls (filters, refresh, settings dropdowns) -- `children`: Table component -- `className?`: Additional classes for outer wrapper - -**Usage Examples:** - -```tsx -import { TableContainerWithHeader } from '@/components/common/table-container-with-header'; -import { Table, TableHeader, TableBody } from '@/components/ui/table'; -import { Button } from '@/components/ui/button'; -import { DropdownMenu } from '@/components/ui/dropdown-menu'; - -// Simple table with title only - - - {/* table content */} -
- - -// Table with actions (filters, refresh, settings) - - - - - - - {/* filter options */} - - - - - - } -> - - {/* table content */} -
- -``` - -**Examples in codebase:** -- `src/features/admin/components/asset-metrics-table.tsx` -- `src/features/positions/components/supplied-morpho-blue-grouped-table.tsx` - -### TablePagination Component - -**TablePagination** (`@/components/common/TablePagination`) -- Unified pagination component for all tables in the app -- Provides consistent styling, smart page numbers with ellipsis, and jump-to-page functionality -- All text uses `font-zen !font-normal` (no bold styling) - -**Features:** -- Smart page numbers with ellipsis for large page counts (shows 7 pages max) -- Jump-to-page search icon (appears when >10 pages) -- Optional entry count display ("Showing X-Y of Z entries") -- Loading states with disabled buttons -- Tighter spacing (gap-2) when used in layouts - -**Props:** -- `currentPage`: Current active page (1-indexed) -- `totalPages`: Total number of pages -- `totalEntries`: Total number of items across all pages -- `pageSize`: Number of items per page -- `onPageChange`: Callback when page changes -- `isLoading?`: Show loading state (default: false) -- `showEntryCount?`: Display entry count below controls (default: true) - -**Usage Examples:** - -```tsx -import { TablePagination } from '@/components/common/TablePagination'; - -// Basic usage with entry count - - -// Without entry count (e.g., main markets table) - - -// In a table layout with tighter spacing -
- - {/* table content */} -
- -
-``` - -### AccountIdentity - -Use `AccountIdentity` from `@/components/common/AccountIdentity` for displaying addresses, ENS names, and vault names. - -```tsx -import { AccountIdentity } from '@/components/common/AccountIdentity'; - -// Badge - minimal inline (no avatar) - - -// Compact - small avatar + text in badge - - -// Full - avatar + address badge + extra info badges - -``` - -Variants: `badge` | `compact` | `full` - -Clicking opens actions popover (copy, view account, explorer). Disable with `showActions={false}`. - -### MarketIdentity - -Use `MarketIdentity` from `@/components/MarketIdentity` for displaying market info in tables, lists, and cards. - -```tsx -import { MarketIdentity, MarketIdentityMode, MarketIdentityFocus } from '@/components/MarketIdentity'; - -// Normal mode - both assets shown equally - - -// Focused mode - emphasizes one asset - - -// Minimum mode - only focused asset - - -// Wide layout - for table cells - -``` - -Modes: `Normal` | `Focused` | `Minimum` - -### MarketDetailsBlock - -Use `MarketDetailsBlock` from `@/components/common/MarketDetailsBlock` for expandable market details in modals. - -```tsx -import { MarketDetailsBlock } from '@/components/common/MarketDetailsBlock'; - - -``` - -### TransactionIdentity - -Use `TransactionIdentity` from `@/components/common/TransactionIdentity` for displaying transaction hashes. - -```tsx -import { TransactionIdentity } from '@/components/common/TransactionIdentity'; - - - -``` - -### CollateralIconsDisplay - -Use `CollateralIconsDisplay` from `@/features/positions/components/collateral-icons-display` for displaying collateral tokens with smart overflow handling. - -**Features:** -- Shows up to `maxDisplay` collateral icons (default: 8) -- Overlapping icon style with proper z-index stacking -- Automatic sorting by amount (descending) -- "+X more" badge for additional collaterals with tooltip -- Opacity support for collaterals with zero balance - -**Props:** -- `collaterals`: Array of collateral objects with `address`, `symbol`, `amount` -- `chainId`: Network chain ID for token icons -- `maxDisplay?`: Maximum icons to display before showing "+X more" badge (default: 8) -- `iconSize?`: Size of token icons in pixels (default: 20) - -**Usage:** - -```tsx -import { CollateralIconsDisplay } from '@/features/positions/components/collateral-icons-display'; - -// Basic usage - - -// Custom display limit and icon size - -``` - -**Pattern:** -This component follows the same overlapping icon pattern as `TrustedByCell` in `trusted-vault-badges.tsx`: -- First icon has `ml-0`, subsequent icons have `-ml-2` for overlapping effect -- Z-index decreases from left to right for proper stacking -- "+X more" badge shows remaining items in tooltip - -**Examples in codebase:** -- `src/features/positions/components/supplied-morpho-blue-grouped-table.tsx` - -## Input Components - -The codebase uses two different input approaches depending on the use case: - -### Numerical Inputs (Amounts, Currency) - -For numerical inputs with bigint values, decimals, and max validation, use the custom Input component: - -```typescript -import Input from '@/components/Input/Input'; - - -``` - -This component: - -- Uses `bg-hovered h-10 w-full rounded p-2 focus:border-primary focus:outline-none` -- Includes a "Max" button when `max` prop is provided -- Handles bigint conversion and decimal formatting -- Validates against maximum values - -### Text Inputs (URLs, Strings) - -For simple text inputs, use native HTML input with consistent styling: - -```typescript - handleChange(e.target.value)} - className="bg-hovered h-10 w-full rounded p-2 focus:border-primary focus:outline-none" -/> -``` - -#### With Button Inside Input - -```typescript -
- handleChange(e.target.value)} - className="bg-hovered h-10 w-full rounded p-2 pr-16 focus:border-primary focus:outline-none" - /> - -
-``` - -#### Error States - -```typescript -className={`bg-hovered h-10 w-full rounded p-2 focus:border-primary focus:outline-none ${ - error ? 'border border-red-500 focus:border-red-500' : '' -}`} - -{error && ( -

{error}

-)} -``` - -### Input Styling Guidelines - -- Always use `bg-hovered` for background -- Standard height: `h-10` -- Always use `rounded` (not `rounded-sm`) -- Standard padding: `p-2` -- Focus state: `focus:border-primary focus:outline-none` -- Error state: `border border-red-500 focus:border-red-500` -- Error text: `text-sm text-red-500` - -## Toast - -Use `useStyledToast` hook to create toasts. - -```typescript -import { useStyledToast } from '@/hooks/useStyledToast'; - -const { success, error } = useStyledToast(); - -success('Success', 'Detail of the success'); -error('Error', 'Detail of the error'); -``` - -### Typography Notes - -- Avoid bold weights for emphasis. Use color, size, or layout treatments (e.g., `text-secondary`, `text-primary`, spacing) instead of `font-semibold`/`font-bold`. -- Prefer `font-zen` for vault UI surfaces; keep typography consistent with existing components. diff --git a/src/components/ui/icon-switch.tsx b/src/components/ui/icon-switch.tsx index 1ae86074..800d94c4 100644 --- a/src/components/ui/icon-switch.tsx +++ b/src/components/ui/icon-switch.tsx @@ -11,7 +11,7 @@ export type IconSwitchProps = { size?: 'xs' | 'sm' | 'md' | 'lg'; color?: 'primary' | 'secondary' | 'accent' | 'destructive'; onChange?: (selected: boolean) => void; - thumbIcon?: React.ComponentType<{ className?: string; isSelected?: boolean }> | null; + thumbIcon?: React.ComponentType<{ className?: string }> | null; thumbIconOn?: React.ComponentType<{ className?: string }>; thumbIconOff?: React.ComponentType<{ className?: string }>; classNames?: { @@ -241,11 +241,7 @@ export function IconSwitch({ classNames?.thumbIcon, )} > - {thumbIconOn && thumbIconOff ? ( - - ) : ( - - )} + )} diff --git a/src/features/markets/components/table/markets-table-actions.tsx b/src/features/markets/components/table/markets-table-actions.tsx new file mode 100644 index 00000000..32d9a86c --- /dev/null +++ b/src/features/markets/components/table/markets-table-actions.tsx @@ -0,0 +1,94 @@ +'use client'; + +import { ReloadIcon } from '@radix-ui/react-icons'; +import { CgCompress } from 'react-icons/cg'; +import { FiSettings } from 'react-icons/fi'; +import { RiExpandHorizontalLine } from 'react-icons/ri'; +import { Button } from '@/components/ui/button'; +import { Tooltip } from '@/components/ui/tooltip'; +import { TooltipContent } from '@/components/shared/tooltip-content'; +import { SuppliedAssetFilterCompactSwitch } from '@/features/positions/components/supplied-asset-filter-compact-switch'; +import { useModal } from '@/hooks/useModal'; +import { useMarketPreferences } from '@/stores/useMarketPreferences'; + +type MarketsTableActionsProps = { + onRefresh: () => void; + isRefetching: boolean; + isMobile: boolean; +}; + +export function MarketsTableActions({ onRefresh, isRefetching, isMobile }: MarketsTableActionsProps) { + const { open: openModal } = useModal(); + const { tableViewMode, setTableViewMode } = useMarketPreferences(); + const effectiveTableViewMode = isMobile ? 'compact' : tableViewMode; + + return ( + <> + openModal('marketSettings', {})} /> + + + } + > + + + + {!isMobile && ( + : } + title={effectiveTableViewMode === 'compact' ? 'Expand Table' : 'Compact Table'} + detail={ + effectiveTableViewMode === 'compact' + ? 'Expand table to full width, useful when more columns are enabled.' + : 'Restore compact table view' + } + /> + } + > + + + )} + + + } + > + + + + ); +} diff --git a/src/features/markets/components/table/markets-table.tsx b/src/features/markets/components/table/markets-table.tsx index f94ed0b4..9c597609 100644 --- a/src/features/markets/components/table/markets-table.tsx +++ b/src/features/markets/components/table/markets-table.tsx @@ -1,28 +1,20 @@ import { useCallback, useMemo, useState } from 'react'; import { FaRegStar, FaStar } from 'react-icons/fa'; -import { ReloadIcon } from '@radix-ui/react-icons'; -import { CgCompress } from 'react-icons/cg'; -import { FiSettings } from 'react-icons/fi'; -import { RiExpandHorizontalLine } from 'react-icons/ri'; import { Table, TableHeader, TableRow, TableHead } from '@/components/ui/table'; import { TablePagination } from '@/components/shared/table-pagination'; -import { Button } from '@/components/ui/button'; -import { Tooltip } from '@/components/ui/tooltip'; -import { TooltipContent } from '@/components/shared/tooltip-content'; import { TableContainerWithHeader } from '@/components/common/table-container-with-header'; import EmptyScreen from '@/components/status/empty-screen'; import LoadingScreen from '@/components/status/loading-screen'; -import { SuppliedAssetFilterCompactSwitch } from '@/features/positions/components/supplied-asset-filter-compact-switch'; import { useMarketsQuery } from '@/hooks/queries/useMarketsQuery'; import { useFilteredMarkets } from '@/hooks/useFilteredMarkets'; import { useRateLabel } from '@/hooks/useRateLabel'; -import { useModal } from '@/hooks/useModal'; import { useMarketPreferences } from '@/stores/useMarketPreferences'; import { useTrustedVaults } from '@/stores/useTrustedVaults'; import { buildTrustedVaultMap } from '@/utils/vaults'; import { SortColumn } from '../constants'; import { MarketTableBody } from './market-table-body'; import { HTSortable } from './market-table-utils'; +import { MarketsTableActions } from './markets-table-actions'; type MarketsTableProps = { currentPage: number; @@ -40,9 +32,6 @@ function MarketsTable({ currentPage, setCurrentPage, className, tableClassName, // Get trusted vaults directly from store (no prop drilling!) const { vaults: trustedVaults } = useTrustedVaults(); - // Get modal management directly from store (no prop drilling!) - const { open: openModal } = useModal(); - const markets = useFilteredMarkets(); const isEmpty = !rawMarkets; @@ -57,8 +46,6 @@ function MarketsTable({ currentPage, setCurrentPage, className, tableClassName, sortDirection, setSortDirection, entriesPerPage, - tableViewMode, - setTableViewMode, includeUnknownTokens, showUnknownOracle, trustedVaultsOnly, @@ -94,85 +81,11 @@ function MarketsTable({ currentPage, setCurrentPage, className, tableClassName, const totalPages = Math.ceil(markets.length / entriesPerPage); - const effectiveTableViewMode = isMobile ? 'compact' : tableViewMode; - const containerClassName = ['flex flex-col gap-2 pb-4', loading || isEmpty || markets.length === 0 ? 'container items-center' : className] .filter((value): value is string => Boolean(value)) .join(' '); const tableClassNames = ['responsive', tableClassName].filter((value): value is string => Boolean(value)).join(' '); - // Header actions (filter, refresh, expand/compact, settings) - const headerActions = ( - <> - openModal('marketSettings', {})} /> - - - } - > - - - - {/* Hide expand/compact toggle on mobile */} - {!isMobile && ( - : } - title={effectiveTableViewMode === 'compact' ? 'Expand Table' : 'Compact Table'} - detail={ - effectiveTableViewMode === 'compact' - ? 'Expand table to full width, useful when more columns are enabled.' - : 'Restore compact table view' - } - /> - } - > - - - )} - - - } - > - - - - ); - // Determine empty state hint based on active filters const getEmptyStateHint = () => { if (!includeUnknownTokens) { @@ -194,7 +107,13 @@ function MarketsTable({ currentPage, setCurrentPage, className, tableClassName,
+ } className="w-full" > {loading ? ( diff --git a/src/hooks/useMarketData.ts b/src/hooks/useMarketData.ts index 9e78f832..d1f1f21e 100644 --- a/src/hooks/useMarketData.ts +++ b/src/hooks/useMarketData.ts @@ -93,6 +93,7 @@ export const useMarketData = (uniqueKey: string | undefined, network: SupportedN }, enabled: !!uniqueKey && !!network, staleTime: 1000 * 60 * 2, + refetchInterval: 1000 * 60 * 2, // Match staleTime for consistency placeholderData: (previousData) => previousData ?? null, retry: 1, }); diff --git a/src/stores/useBlacklistedMarkets.ts b/src/stores/useBlacklistedMarkets.ts index e7c7e7a2..b1bf9512 100644 --- a/src/stores/useBlacklistedMarkets.ts +++ b/src/stores/useBlacklistedMarkets.ts @@ -11,6 +11,8 @@ export type BlacklistedMarket = { type BlacklistedMarketsState = { customBlacklistedMarkets: BlacklistedMarket[]; + /** Cached Set of all blacklisted keys (default + custom) */ + _cachedBlacklistedKeys: Set | null; }; type BlacklistedMarketsActions = { @@ -32,6 +34,7 @@ export const useBlacklistedMarkets = create()( persist( (set, get) => ({ customBlacklistedMarkets: [], + _cachedBlacklistedKeys: null, addBlacklistedMarket: (uniqueKey, chainId, reason) => { const state = get(); @@ -50,6 +53,7 @@ export const useBlacklistedMarkets = create()( set((prevState) => ({ customBlacklistedMarkets: [...prevState.customBlacklistedMarkets, newMarket], + _cachedBlacklistedKeys: null, // Invalidate cache })); return true; @@ -58,6 +62,7 @@ export const useBlacklistedMarkets = create()( removeBlacklistedMarket: (uniqueKey) => { set((state) => ({ customBlacklistedMarkets: state.customBlacklistedMarkets.filter((m) => m.uniqueKey !== uniqueKey), + _cachedBlacklistedKeys: null, // Invalidate cache })); }, @@ -72,14 +77,26 @@ export const useBlacklistedMarkets = create()( getAllBlacklistedKeys: () => { const state = get(); + // Return cached Set if available + if (state._cachedBlacklistedKeys) { + return state._cachedBlacklistedKeys; + } + // Compute and cache the Set const customKeys = state.customBlacklistedMarkets.map((m) => m.uniqueKey); - return new Set([...defaultBlacklistedMarkets, ...customKeys]); + const newSet = new Set([...defaultBlacklistedMarkets, ...customKeys]); + // Update cache (using set() to avoid mutation) + set({ _cachedBlacklistedKeys: newSet }); + return newSet; }, - setAll: (newState) => set(newState), + setAll: (newState) => set({ ...newState, _cachedBlacklistedKeys: null }), }), { name: 'monarch_store_blacklistedMarkets', + partialize: (state) => ({ + // Only persist customBlacklistedMarkets, not the cache + customBlacklistedMarkets: state.customBlacklistedMarkets, + }), }, ), );