@svp-chain-sdk/ui 0.1.4 → 0.1.5

package/README.md

@@ -2,90 +2,9 @@
 
 ## 1. 适用范围
 
-`@svp-chain-sdk/ui` 提供 Tailwind provider，也提供 React 钱包公共能力。钱包支持链、钱包分组、RainbowKit 主题、SVP Wallet 检测与安装地址统一维护在 `src/wallet.tsx` 的 `walletDefaults` 及相关导出中。
+`@svp-chain-sdk/ui` 当前的主要接入方式是 Tailwind provider：消费方把 `@svp-chain-sdk/ui/tailwind` 注册为 Tailwind 插件，然后直接在 HTML、React、Vue 或其他模板中组合 `.ui-button` 等 CSS class。
 
-React 项目可直接复用 Provider 和连接按钮：
-
-```tsx
-import {
-  ConnectWalletButton,
-  SvpWalletProvider,
-} from '@svp-chain-sdk/ui'
-import '@rainbow-me/rainbowkit/styles.css'
-
-export function App() {
-  return (
-    <SvpWalletProvider appName="SVP Bridge" projectId={walletConnectProjectId}>
-      <ConnectWalletButton
-        labels={{ connect: '连接钱包', wrongNetwork: '网络错误' }}
-      />
-    </SvpWalletProvider>
-  )
-}
-```
-
-消费项目需要安装本包声明的 React、RainbowKit、TanStack Query、Wagmi 和 Viem peer dependencies。业务层只传应用名、WalletConnect Project ID 和本地化文案；默认链、钱包顺序、弹窗主题与 SVP Wallet 行为由 SDK 统一提供。
-
-### 在现有项目中接入（以 swap-v2 为例）
-
-1. 安装公共包及 peer dependencies：
-
-```sh
-pnpm add @svp-chain-sdk/ui @rainbow-me/rainbowkit @tanstack/react-query wagmi viem
-```
-
-本地联调尚未发布的 SDK 时，可以把依赖临时指向仓库中的 UI 包：
-
-```json
-{
-  "dependencies": {
-    "@svp-chain-sdk/ui": "file:../svp-chain-sdk-monorepo/packages/ui"
-  }
-}
-```
-
-2. 在应用入口导入 SDK 与 RainbowKit 样式，并用 `SvpWalletProvider` 包裹应用。`projectId` 应读取项目自己的 `VITE_WALLETCONNECT_PROJECT_ID`，不要提交真实凭据：
-
-```tsx
-import { SvpWalletProvider } from '@svp-chain-sdk/ui'
-import '@svp-chain-sdk/ui/styles.css'
-import '@rainbow-me/rainbowkit/styles.css'
-
-createRoot(document.getElementById('root')!).render(
-  <SvpWalletProvider
-    appName="NovaSwap"
-    projectId={import.meta.env.VITE_WALLETCONNECT_PROJECT_ID}
-    locale="zh-CN"
-  >
-    <App />
-  </SvpWalletProvider>,
-)
-```
-
-如果项目已经自行声明了 `WagmiProvider`、`QueryClientProvider` 和 `RainbowKitProvider`，应删除重复 Provider，避免出现两个 Wagmi/Query Client 上下文。默认网络、钱包排序、SVP Wallet 图标、安装跳转和弹窗主题由 SDK 提供。
-
-3. 在 Header 或其他业务组件中直接使用连接按钮：
-
-```tsx
-import { ConnectWalletButton } from '@svp-chain-sdk/ui'
-
-export function HeaderWallet() {
-  return (
-    <ConnectWalletButton
-      labels={{
-        connect: '连接钱包',
-        wrongNetwork: '网络错误',
-      }}
-    />
-  )
-}
-```
-
-按钮会自动处理未连接、错误网络和已连接三种状态。`showChain={false}` 可以在已连接时隐藏独立网络按钮；`className` 只应用到钱包操作按钮。SVP Wallet 图标已经随 npm 包构建，不需要消费项目把图片复制到 `public`。
-
-4. 升级 SDK 后执行项目自身的测试与生产构建，至少确认连接弹窗、SVP Wallet 图标、未安装跳转、网络切换和账户弹窗正常。
-
-这是**框架无关、非 React 组件优先**的模式。包根入口仍提供可选的 React `Button`、`buttonVariants` 和 `cn`，也导出 `@svp-chain-sdk/ui/styles.css` 样式入口，但它们不是本文的主要接入方式。目前 Tailwind provider 只注册按钮相关 class，不应假定它包含表单、弹窗或其他尚未实现的组件。
+这是**框架无关样式优先**的模式。包根入口同时提供可选的 React `Button`、零配置 `NoticeMarquee`、`FeedbackWidget` 和 `cn`。Tailwind provider 当前注册按钮与通知走马灯样式；不应假定它包含其他尚未实现的组件。
 
 ## 2. 从公共 npm registry 安装
 
@@ -250,7 +169,8 @@ function submit() {
 `@svp-chain-sdk/ui/tailwind` 提供两个具名导出：
 
 - `uiButtonComponents`：当前按钮组件配置对象。
-- `uiComponents`：默认插件注册的完整组件配置；当前它与 `uiButtonComponents` 是同一个对象。未来若增加其他组件，应优先使用 `uiComponents` 来继承完整配置。
+- `uiNoticeMarqueeComponents`：通知走马灯的完整样式配置对象。
+- `uiComponents`：默认插件注册的完整组件配置，包含按钮和通知走马灯配置。
 
 如需在同一个插件中加入应用级 class，可组合 `uiComponents`：
 
@@ -344,14 +264,132 @@ npm run release:minor -- --dry-run
 
 `prepublishOnly` 保留为 npm 的独立发布保护，会再次运行质量检查；`release` 脚本不依赖 Git 提交或 tag。
 
-## 11. 当前公开入口速查
+## 11. React FeedbackWidget
+
+`FeedbackWidget` 是一个零配置 React 公共组件。其结构和样式对齐 `svp-website-frontend` 的 `.svp-contact-fab.js-contact-us`：桌面端为视口右侧垂直居中的 54px 渐变方形 FAB，560px 以下缩为 48px；点击后在新的浏览器标签页打开 Google Form。
+
+建议在应用最外层 Layout 或 AppShell 中只挂载一次：
+
+```tsx
+import { FeedbackWidget } from '@svp-chain-sdk/ui'
+import '@svp-chain-sdk/ui/styles.css'
+
+export function AppShell() {
+  return (
+    <>
+      {/* 页面与路由内容 */}
+      <FeedbackWidget />
+    </>
+  )
+}
+```
+
+表单短链接由组件内部的 `GOOGLE_FORM_URL` 统一维护，消费页面无需传入地址或了解表单字段。当前源码已内置项目提供的 Google Form 地址。
+
+组件使用带有 `target="_blank"` 和 `rel="noopener noreferrer"` 的链接打开表单，不读取、存储或转发表单内容，也不依赖 iframe 或消费站点的 `frame-src` 配置。
+
+可选 `className` 仅用于宿主页面协调多个悬浮控件。组件使用参考项目相同的 `--svp-primary` 和 `--svp-accent` 变量，并分别回退到 `#2563eb` 与 `#38bdf8`。
+
+`FeedbackWidget` 属于包根入口的 React API，不属于 `@svp-chain-sdk/ui/tailwind` 提供的框架无关 class。
+
+## 12. 当前公开入口速查
 
 以 `packages/ui/package.json` 当前的 `exports` 为准：
 
 | 导入路径 | 当前内容 |
 | --- | --- |
-| `@svp-chain-sdk/ui/tailwind` | 默认 Tailwind plugin；具名 `uiButtonComponents`、`uiComponents` |
-| `@svp-chain-sdk/ui` | 可选 React `Button`、`buttonVariants`、`ButtonProps` 和 `cn` |
+| `@svp-chain-sdk/ui/tailwind` | 默认 Tailwind plugin；具名 `uiButtonComponents`、`uiNoticeMarqueeComponents`、`uiComponents` |
+| `@svp-chain-sdk/ui` | React `Button`、零配置 `NoticeMarquee` 与 `FeedbackWidget`、相关类型和常量、`buttonVariants` 和 `cn` |
 | `@svp-chain-sdk/ui/styles.css` | 包构建产出的 Tailwind v4 CSS 样式入口；当前不包含 provider 的 `.ui-button*` 规则 |
 
 所有 JavaScript 入口均按 ESM 使用。公开 API 之外的源码路径不属于 package exports，不应从消费项目直接导入。
+
+## 13. React NoticeMarquee 通知走马灯
+
+`NoticeMarquee` 是零配置公共组件。业务页面只需要渲染组件，无需传入通知内容或文件地址：
+
+```tsx
+import { NoticeMarquee } from '@svp-chain-sdk/ui'
+
+export function Layout() {
+  return (
+    <>
+      <NoticeMarquee />
+      {/* 页面内容 */}
+    </>
+  )
+}
+```
+
+组件默认读取 `DEFAULT_NOTICE_URL` 指向的公共 IPFS Gateway JSON。地址集中在 SDK 常量中，业务页面无需传入。组件首次加载后默认每 5 分钟静默重新请求一次，不显示 loading，也不会因一次网络失败导致页面报错。
+
+服务端 JSON 格式：
+
+```json
+{
+  "en": "English notice",
+  "zh": "中文通知",
+  "fr": "Notification française"
+}
+```
+
+组件根据 `navigator.language` 选择 `zh`、`fr` 或 `en`。找不到对应语言时先回退到 `en`，再回退到第一个非空字符串。内容始终按纯文本展示，不使用 `innerHTML`。
+
+浏览器会在 `localStorage` 的 `DEFAULT_NOTICE_STORAGE_KEY` 下保存：
+
+```json
+{
+  "seenAt": 1789445000000,
+  "content": "{\"en\":\"English notice\",\"fr\":\"Notification française\",\"zh\":\"中文通知\"}"
+}
+```
+
+`content` 不是当前语言的展示文案，而是完整远程公告对象的 canonical JSON 快照：对象 key 会递归排序，因此属性顺序不同但内容相同的 JSON 会得到相同值。展示文本仍独立地按 `navigator.language` 选择。
+
+规则如下：
+
+1. 浏览器没有记录时，记录当前时间与完整公告快照，并播放当前语言文案。
+2. 完整远程公告与本地快照相同时，不播放；切换浏览器语言也不会把同一公告当作新公告。
+3. 任一语言或其他公告字段变化时，用当前时间和新的完整快照覆盖旧记录，并播放当前语言文案。
+4. 同一页面即使意外挂载多个实例（包括 React StrictMode），同一首次公告也最多由一个实例播放。
+5. 清除浏览器数据、使用无痕窗口或更换设备后，该通知会被视为首次看到。
+6. `localStorage` 不可用时组件不会报错，并在本次页面中播放获取到的内容。
+
+使用 `NoticeMarquee` 时，消费项目可以按第 3 节注册并构建 `@svp-chain-sdk/ui/tailwind` provider，也可以直接导入 `@svp-chain-sdk/ui/styles.css`。两条样式入口都提供相同的固定宽度、走马灯动画、hover 暂停和 `prefers-reduced-motion` 规则，不要同时重复引入。
+
+样式与 `dex-website-frontend` Footer 的 InfiniteMarquee 保持一致：可视区宽度为 `16rem`，两份相同内容首尾衔接，轨道从 `0` 平移至 `-50%`，默认周期为 `32s`，仅在 hover 时原地暂停。可通过 CSS 变量调整滚动周期：
+
+```css
+:root {
+  --ui-notice-marquee-duration: 30s;
+}
+```
+
+高级场景可以覆盖可选参数，但普通业务页面不需要传参：
+
+```tsx
+<NoticeMarquee
+  url="https://example.com/notice.json"
+  storageKey="my-app:notice"
+  refreshIntervalMs={5 * 60 * 1000}
+/>
+```
+
+公开常量和类型：
+
+```ts
+import {
+  DEFAULT_NOTICE_REFRESH_INTERVAL_MS,
+  DEFAULT_NOTICE_STORAGE_KEY,
+  DEFAULT_NOTICE_URL,
+  NoticeMarquee,
+  type NoticeMarqueeProps,
+} from '@svp-chain-sdk/ui'
+```
+
+服务器配置注意事项：
+
+- 跨域地址必须正确配置 CORS。
+- 响应必须是 JSON 对象，语言字段的值应为非空字符串。
+- SDK 不携带 cookie、token 或其他认证信息。
+- IPFS CID 对应不可变内容；发布新通知时需要更新 CID 或改用能指向最新 JSON 的稳定地址。

package/dist/components/button/index.d.ts

@@ -0,0 +1,2 @@
+export { Button, buttonVariants } from './button';
+export type { ButtonProps } from './button';

package/dist/components/feedback-widget/feedback-widget.d.ts

@@ -0,0 +1,4 @@
+export interface FeedbackWidgetProps {
+    className?: string;
+}
+export declare function FeedbackWidget({ className }?: FeedbackWidgetProps): import("react").JSX.Element;

package/dist/components/feedback-widget/index.d.ts

@@ -0,0 +1,2 @@
+export { FeedbackWidget } from './feedback-widget';
+export type { FeedbackWidgetProps } from './feedback-widget';

package/dist/components/index.d.ts

@@ -0,0 +1,6 @@
+export { Button, buttonVariants } from './button';
+export type { ButtonProps } from './button';
+export { FeedbackWidget } from './feedback-widget';
+export type { FeedbackWidgetProps } from './feedback-widget';
+export { DEFAULT_NOTICE_REFRESH_INTERVAL_MS, DEFAULT_NOTICE_STORAGE_KEY, DEFAULT_NOTICE_URL, NoticeMarquee, } from './notice-marquee';
+export type { NoticeMarqueeProps } from './notice-marquee';

package/dist/components/notice-marquee/index.d.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_NOTICE_REFRESH_INTERVAL_MS, DEFAULT_NOTICE_STORAGE_KEY, DEFAULT_NOTICE_URL, NoticeMarquee, } from './notice-marquee';
+export type { NoticeMarqueeProps } from './notice-marquee';

package/dist/components/notice-marquee/notice-marquee.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+export declare const DEFAULT_NOTICE_URL = "https://moccasin-glad-tyrannosaurus-244.mypinata.cloud/ipfs/bafkreiavwd7xwacprggfzpdcicluvv4tzdxdfzj6brlzayxsk64upezdwa";
+export declare const DEFAULT_NOTICE_STORAGE_KEY = "@svp-chain-sdk/ui:notice-marquee";
+export declare const DEFAULT_NOTICE_REFRESH_INTERVAL_MS: number;
+export type NoticeMarqueeProps = {
+    /** Optional override for the SDK default multilingual JSON URL. */
+    url?: string;
+    /** Optional override for the localStorage key used to remember seen content. */
+    storageKey?: string;
+    /** Optional override for the default five-minute silent refresh interval. */
+    refreshIntervalMs?: number;
+    className?: string;
+};
+/**
+ * Zero-config remote notice marquee. It shows unseen localized content once per
+ * browser and remembers the content in localStorage.
+ */
+export declare function NoticeMarquee({ url, storageKey, refreshIntervalMs, className, }?: NoticeMarqueeProps): React.JSX.Element | null;

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-export { Button, buttonVariants } from './button';
-export type { ButtonProps } from './button';
-export { cn } from './utils';
-export { ConnectWalletButton, createSvpWalletConfig, resolveSvpProvider, resolveSvpProviderForConnection, SVP_WALLET_DOWNLOAD_URL, svpTestnet, svpWallet, SvpWalletProvider, walletDefaults, walletTheme, } from './wallet';
-export type { ConnectWalletButtonProps, ConnectWalletLabels, CreateSvpWalletConfigOptions, SvpWalletProviderProps, SvpWalletDefaults, } from './wallet';
+export { Button, buttonVariants, DEFAULT_NOTICE_REFRESH_INTERVAL_MS, DEFAULT_NOTICE_STORAGE_KEY, DEFAULT_NOTICE_URL, FeedbackWidget, NoticeMarquee, } from './components';
+export type { ButtonProps, FeedbackWidgetProps, NoticeMarqueeProps, } from './components';
+export { cn } from './lib/utils';