@svp-chain-sdk/ui 0.1.3 → 0.1.5

package/README.md

@@ -4,7 +4,7 @@
 
 `@svp-chain-sdk/ui` 当前的主要接入方式是 Tailwind provider：消费方把 `@svp-chain-sdk/ui/tailwind` 注册为 Tailwind 插件，然后直接在 HTML、React、Vue 或其他模板中组合 `.ui-button` 等 CSS class。
 
-这是**框架无关、非 React 组件优先**的模式。包根入口仍提供可选的 React `Button`、`buttonVariants` 和 `cn`，也导出 `@svp-chain-sdk/ui/styles.css` 样式入口，但它们不是本文的主要接入方式。目前 Tailwind provider 只注册按钮相关 class，不应假定它包含表单、弹窗或其他尚未实现的组件。
+这是**框架无关样式优先**的模式。包根入口同时提供可选的 React `Button`、零配置 `NoticeMarquee`、`FeedbackWidget` 和 `cn`。Tailwind provider 当前注册按钮与通知走马灯样式；不应假定它包含其他尚未实现的组件。
 
 ## 2. 从公共 npm registry 安装
 
@@ -169,7 +169,8 @@ function submit() {
 `@svp-chain-sdk/ui/tailwind` 提供两个具名导出：
 
 - `uiButtonComponents`：当前按钮组件配置对象。
-- `uiComponents`：默认插件注册的完整组件配置；当前它与 `uiButtonComponents` 是同一个对象。未来若增加其他组件，应优先使用 `uiComponents` 来继承完整配置。
+- `uiNoticeMarqueeComponents`：通知走马灯的完整样式配置对象。
+- `uiComponents`：默认插件注册的完整组件配置，包含按钮和通知走马灯配置。
 
 如需在同一个插件中加入应用级 class，可组合 `uiComponents`：
 
@@ -263,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,3 +1,3 @@
-export { Button, buttonVariants } from './button';
-export type { ButtonProps } from './button';
-export { cn } from './utils';
+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';