@nexus-cross/dapp-ui 2.3.4-beta.1 → 2.4.0-beta.2

package/AI_INTEGRATION.md

@@ -0,0 +1,55 @@
+# AI Integration Contract
+
+Use this file when an AI coding agent is asked to add `@nexus-cross/dapp-ui` to a React DApp.
+
+## Get ONEUSD
+
+Prefer the turn-key wagmi wrapper when the app already uses CROSSx Connect Kit:
+
+```tsx
+import type { ReactNode } from "react";
+import { CrossGetOneUsd } from "@nexus-cross/connect-kit-react";
+
+export function AppLayout({ children }: { children: ReactNode }) {
+  return (
+    <>
+      {children}
+      <CrossGetOneUsd env="production" mode="floating" theme="dark" />
+    </>
+  );
+}
+```
+
+Mount `CrossGetOneUsd` once in the persistent app/root layout, below
+`CrossConnectKitProvider` and outside route pages. This keeps the floating
+transaction status visible during same-site client-side route changes. A full
+page reload or navigation to another site does not preserve an in-memory status.
+
+Rules:
+
+- Do not recreate the chooser, Swap, Bridge, Relay, History, Recover, APR, or transaction-status UI.
+- Use `mode="floating"` for the fixed FAB and `mode="button"` for an inline trigger.
+- In both modes, a submitted Swap/Bridge status is always rendered as a floating status surface.
+- Use `buttonComponent` only when the host must supply a styled button component.
+- Keep the component mounted while a transaction is pending; do not conditionally render it per route.
+- `GetOneUsd` reads the S3 `getOneUsd.modes` flags. Missing flags default to Swap `true`, Bridge `true`, Transfer Crypto `false`.
+- The Transfer Crypto modal owns the `Deposit`, `History`, and `Recover` tabs. It shares one live orders subscription across them.
+- `CrossGetOneUsd` supplies wagmi Bridge and Relay adapters. Do not duplicate those adapters in DApp code.
+- Use the low-level `GetOneUsd` export only when the host already owns every `bridge` and `relay` function port required by its TypeScript props.
+
+For an inline host-styled trigger:
+
+```tsx
+const GetOneUsdButton = styled.button`
+  border-radius: 12px;
+`;
+
+<CrossGetOneUsd
+  env="production"
+  mode="button"
+  buttonComponent={GetOneUsdButton}
+/>;
+```
+
+Keep all visible user-facing copy in English. Let the package own its modal
+copy, colors, mobile keyboard behavior, safe-area handling, and transaction lock.

package/README.md

@@ -2,12 +2,13 @@
 
 CROSS 생태계 DApp 공통 UI 컴포넌트 패키지.
 
-네 가지 독립적인 기능을 제공한다:
+공통 DApp 기능을 제공한다. 주요 진입점:
 
 - **AppLauncher**: 글로벌 서비스 메뉴
 - **WalletInfo**: 지갑 잔액·가격·등락률 조회 UI
 - **WalletConnectModal**: 지갑 연결 모달/드로어 UI
 - **WalletPortfolio**: 리워드·DEX 포지션 포트폴리오 UI
+- **GetOneUsd**: Swap·Bridge·Relay를 묶은 ONEUSD 획득 플로팅/버튼 위젯
 
 > 이전 패키지 이름: `cross-app-launcher` (`@nexus-cross/dapp-ui@0.0.1+` 부터 rename).
 
@@ -39,9 +40,17 @@ import {
   WalletInfo,
   WalletConnectModal,
   WalletPortfolio,
+  GetOneUsd,
 } from "@nexus-cross/dapp-ui";
 ```
 
+## AI-assisted integration
+
+Give an AI coding agent [`AI_INTEGRATION.md`](./AI_INTEGRATION.md) as the
+implementation contract. It contains the canonical Get ONEUSD mount location,
+route-persistent floating transaction status rule, mode behavior, and the
+boundary between `CrossGetOneUsd` and the low-level `GetOneUsd` ports.
+
 ---
 
 ## AppLauncher
@@ -173,6 +182,7 @@ Context Provider + Popover/Drawer Root.
 | `showQR`           | `boolean`                                     | `true`         | QR 코드 버튼/뷰 활성화 여부                        |
 | `onCopyAddress`    | `(address: string, success: boolean) => void` | -              | 주소 복사 콜백 (토스트 표시용)                      |
 | `onBuy`            | `() => void`                                  | -              | 기본 액션 row의 Buy 클릭 핸들러                     |
+| `showOnePop`       | `boolean`                                     | `true`         | 액션 row의 ONEpop 카드 + ONEpop 화면 노출 (아래 참조) |
 | `onDisconnect`     | `() => void`                                  | -              | 지정 시 하단에 기본 Disconnect(Log Out) 버튼 렌더   |
 | `disconnectLabel`  | `string`                                      | `'Disconnect'` | 기본 Disconnect 버튼 라벨                           |
 | `open`             | `boolean`                                     | -              | 외부에서 열림 상태를 제어 (controlled)              |
@@ -230,6 +240,47 @@ Log Out 처리는 레이아웃 목표에 따라 택일한다: **(A)** 단독 Dis
 | ---------- | ----------- | ------- | ----------- |
 | `children` | `ReactNode` | (필수)  | 푸터 콘텐츠 |
 
+### ONEpop 화면
+
+기본 액션 row는 **Buy / Bridge / ONEpop / Portfolio** 이고, Send는 총자산 금액
+우측의 아이콘 버튼이다. ONEpop 카드를 누르면 소셜 핸들 드롭 진입 화면이 열린다.
+
+이 화면은 **렌더링만** 한다 — dapp-ui는 `@nexus-cross/pop`(viem 필수)에 의존할
+수 없고, one-pop-api `/drops`·`/histories`는 SIWE 서명을 요구하기 때문이다.
+표시할 상태와 액션 목적지는 주입받는다.
+
+| Prop                | Type            | Description                                                        |
+| ------------------- | --------------- | ------------------------------------------------------------------ |
+| `showOnePop`        | `boolean`       | ONEpop 카드/화면 노출 (기본 `true`)                                |
+| `onePopSummary`     | `OnePopSummary` | 수령 대기 수·합계, replies 카운트, 최근 활동. 미주입 시 온보딩 화면 |
+| `onOnePopOpen`      | `() => void`    | 화면 진입 시 호출 — 조회를 이 시점까지 미루는 트리거                |
+| `onOnePopSend`      | `() => void`    | Send POP 카드 + "Send your first POP!"                             |
+| `onOnePopClaim`     | `() => void`    | Claim POPs 카드 + 수령 대기 배너                                    |
+| `onOnePopActivity`  | `() => void`    | Activity 카드 + "See all activity" + replies 배너                   |
+| `onePopLogoSrc`     | `string`        | 브랜드 워드마크 이미지 (미지정 시 내장 SVG)                         |
+| `onePopHeroSrc`     | `string`        | 히어로 일러스트 이미지 (미지정 시 내장 SVG)                         |
+
+미주입 콜백의 버튼은 비활성으로 보인다. `Available` 카드는 지갑이 이미 불러온
+CROSS 체인 ONEUSD 잔액을 그대로 쓰고, `Get ONEUSD ›`는 `onBuy`(on-ramp)를
+재사용한다.
+
+`@nexus-cross/connect-kit-react`를 쓰고 `onePopEnabled: true`면
+`onePopSummary`가 자동 주입된다. 자세한 내용은 `docs/dapp-ui/onepop.md`.
+
+```tsx
+<WalletInfo
+  walletAddress={address}
+  showBalance
+  onePopSummary={summary}
+  onOnePopSend={() => router.push('/onepop/send')}
+  onOnePopClaim={() => router.push('/onepop/claim')}
+  onOnePopActivity={() => router.push('/onepop/activity')}
+>
+```
+
+`OnePopSummary`의 금액 필드는 raw wei-scale 문자열(`amountRaw` /
+`claimableTotalRaw`) + `decimals` 로 받는다 — 표시 시 소수점 2자리 버림.
+
 ### 토큰 노출 정책
 
 | 규칙            | 설명                                                                    |