Add unified data sources and stage debug

This commit is contained in:
zhougf committed 2026-05-31 00:04:45 +08:00
1 parent 3fae670e6b
commit 5b300dee0d
18 files changed
+940 -72

No files matched your search

+1 -1
View File
@@ -5,5 +5,5 @@ dist/
.DS_Store
*.log
coverage/
data/
/data/
uploads/
+1
View File
@@ -100,3 +100,4 @@ pnpm build
- [项目框架说明](doc/framework.md)
- [交付流程](doc/delivery-workflow.md)
- [图表工厂与 visual-kit 使用教程](doc/charts-and-visual-kit-guide.md)
- [外部数据接入设计与使用教程](doc/data-integration-guide.md)
+45
View File
@@ -0,0 +1,45 @@
import { defineDataSources, mockSource } from '@dev-screen-starter/data'
import {
alertRows,
capacityTrend,
fulfillmentMix,
issueRose,
metrics,
operationEvents,
qualityRadar,
regionRank,
stackedOrders
} from './mockData'
export const demoDataSources = defineDataSources({
metrics: mockSource({
data: metrics,
intervalMs: 15000
}),
alerts: mockSource({
data: alertRows,
intervalMs: 12000
}),
operationEvents: mockSource({
data: operationEvents,
intervalMs: 10000
}),
capacityTrend: mockSource({
data: capacityTrend
}),
stackedOrders: mockSource({
data: stackedOrders
}),
regionRank: mockSource({
data: regionRank
}),
issueRose: mockSource({
data: issueRose
}),
fulfillmentMix: mockSource({
data: fulfillmentMix
}),
qualityRadar: mockSource({
data: qualityRadar
})
})
+78 -53
View File
@@ -8,8 +8,7 @@ import {
createStackedBarOption,
EChart
} from '@dev-screen-starter/charts'
import { DebugBadge } from '@dev-screen-starter/debug'
import { MetricCard, Panel, ScreenStage } from '@dev-screen-starter/screen-core'
import { MetricCard, Panel, ScreenStage, type ScaleMode } from '@dev-screen-starter/screen-core'
import {
CornerFrame,
Divider,
@@ -23,24 +22,42 @@ import {
TrendBadge,
WaterLevel
} from '@dev-screen-starter/visual-kit'
import {
alertRows,
capacityTrend,
fulfillmentMix,
issueRose,
metrics,
operationEvents,
qualityRadar,
regionRank,
stackedOrders
} from '../demo/mockData'
import { useScreenDataSources } from '@dev-screen-starter/data'
import { demoDataSources } from '../demo/dataSources'
const scaleModes: ScaleMode[] = ['fit', 'fill', 'stretch', 'none']
function readScaleMode(): ScaleMode {
if (typeof window === 'undefined') {
return 'fit'
}
const value = new URLSearchParams(window.location.search).get('scaleMode')
return scaleModes.includes(value as ScaleMode) ? (value as ScaleMode) : 'fit'
}
export function DemoOverview() {
const scaleMode = readScaleMode()
const data = useScreenDataSources(demoDataSources)
const metrics = data.metrics.data ?? []
const alertRows = data.alerts.data ?? []
const operationEvents = data.operationEvents.data ?? []
const capacityTrend = data.capacityTrend.data
const stackedOrders = data.stackedOrders.data
const regionRank = data.regionRank.data
const issueRose = data.issueRose.data ?? []
const fulfillmentMix = data.fulfillmentMix.data
const qualityRadar = data.qualityRadar.data
return (
<ScreenStage background="#061826">
<ScreenStage background="#061826" scaleMode={scaleMode} debug>
<header className="screen-title">
<span>客户项目大屏模板</span>
<strong>运营态势总览</strong>
<div className="screen-title-meta">
<span>HTTP / WebSocket / MQTT / SignalR ready</span>
<span>scaleMode={scaleMode}</span>
</div>
</header>
<section className="visual-strip">
@@ -96,32 +113,38 @@ export function DemoOverview() {
<section className="chart-grid">
<Panel title="面积趋势:吞吐走势">
<EChart
option={createAreaTrendOption({
categories: capacityTrend.xAxis,
series: capacityTrend.series
})}
/>
{capacityTrend ? (
<EChart
option={createAreaTrendOption({
categories: capacityTrend.xAxis,
series: capacityTrend.series
})}
/>
) : null}
</Panel>
<Panel title="堆叠柱:区域订单">
<EChart
option={createStackedBarOption({
categories: stackedOrders.categories,
series: stackedOrders.series
})}
/>
{stackedOrders ? (
<EChart
option={createStackedBarOption({
categories: stackedOrders.categories,
series: stackedOrders.series
})}
/>
) : null}
</Panel>
<Panel title="排名条:区域排行">
<EChart
option={createRankBarOption({
categories: regionRank.categories,
values: regionRank.values,
name: '订单',
color: '#7aa7ff'
})}
/>
{regionRank ? (
<EChart
option={createRankBarOption({
categories: regionRank.categories,
values: regionRank.values,
name: '订单',
color: '#7aa7ff'
})}
/>
) : null}
</Panel>
<Panel title="玫瑰图:异常来源">
@@ -129,34 +152,36 @@ export function DemoOverview() {
</Panel>
<Panel title="双轴图:订单与履约">
<EChart
option={createDualAxisOption({
categories: fulfillmentMix.categories,
leftName: '订单',
rightName: '履约率',
bar: { name: '订单', values: fulfillmentMix.orders, color: '#63a4ff' },
line: { name: '履约率', values: fulfillmentMix.rates, color: '#d8a13e' }
})}
/>
{fulfillmentMix ? (
<EChart
option={createDualAxisOption({
categories: fulfillmentMix.categories,
leftName: '订单',
rightName: '履约率',
bar: { name: '订单', values: fulfillmentMix.orders, color: '#63a4ff' },
line: { name: '履约率', values: fulfillmentMix.rates, color: '#d8a13e' }
})}
/>
) : null}
</Panel>
<Panel title="雷达图:运营质量">
<EChart
option={createRadarOption({
indicators: qualityRadar.indicators,
values: qualityRadar.values,
name: '质量评分',
color: '#d8a13e'
})}
/>
{qualityRadar ? (
<EChart
option={createRadarOption({
indicators: qualityRadar.indicators,
values: qualityRadar.values,
name: '质量评分',
color: '#d8a13e'
})}
/>
) : null}
</Panel>
<Panel title="仪表盘:履约率" className="compact-panel">
<EChart option={createGaugeOption({ name: '履约率', value: 87, unit: '%', color: '#56d08a' })} />
</Panel>
</section>
<DebugBadge enabled scale={1} />
</ScreenStage>
)
}
+34
View File
@@ -46,6 +46,19 @@ body {
letter-spacing: 0;
}
.screen-title-meta {
display: flex;
gap: 10px;
}
.screen-title-meta span {
border: 1px solid rgb(99 164 255 / 22%);
border-radius: 999px;
color: #9fb4cc;
font-size: 12px;
padding: 5px 9px;
}
.event-strip {
background: rgb(8 22 36 / 72%);
border: 1px solid rgb(88 130 171 / 34%);
@@ -202,6 +215,27 @@ body {
right: 18px;
}
.screen-stage-debug {
background: rgb(3 8 13 / 84%);
border: 1px solid rgb(100 135 170 / 35%);
border-radius: 6px;
bottom: 18px;
color: #9fb4cc;
display: flex;
flex-wrap: wrap;
gap: 10px;
max-width: min(760px, calc(100vw - 36px));
padding: 8px 10px;
position: absolute;
right: 18px;
z-index: 10;
}
.screen-stage-debug span {
font-size: 12px;
white-space: nowrap;
}
.visual-status-row {
display: flex;
gap: 8px;
+292
View File
@@ -0,0 +1,292 @@
# 外部数据接入设计与使用教程
本文档说明 Dev Screen Starter 的统一数据源设计。目标是让一个大屏页面可以集中声明多个数据源,并同时支持 HTTP、WebSocket、SignalR、MQTT 等不同协议。
## 1. 核心原则
一个大屏页面可以有多个图表和多个数据源。不同数据源可以使用不同协议:
- 指标卡来自 HTTP 轮询。
- 告警列表来自 WebSocket 推送。
- 设备状态来自 MQTT topic。
- .NET 后端事件来自 SignalR hub。
页面不应该在组件里分散写 `fetch`、`new WebSocket`、MQTT 订阅等细节。推荐把数据源集中放在一个文件中:
```txt
apps/demo-screen/src/demo/dataSources.ts
```
业务组件只消费统一的 `DataState<T>`。
## 2. 当前实现状态
已实现:
- `mockSource`
- `httpSource`
- `websocketSource`
- `defineDataSources`
- `useScreenDataSources`
已预留类型和声明函数:
- `signalrSource`
- `mqttSource`
SignalR 和 MQTT 当前不会引入 SDK,也不会真实连接;它们会返回 `idle` 状态和提示信息。后续客户项目需要时,再接入具体 SDK 或后端网关。
## 3. 统一状态模型
每个数据源都会返回同一种结构:
```ts
type DataState<T> = {
data: T | null
loading: boolean
error: string | null
status: 'idle' | 'connecting' | 'open' | 'closed' | 'error'
lastUpdated?: number
sourceType?: 'mock' | 'http' | 'websocket' | 'signalr' | 'mqtt'
}
```
组件不需要关心底层协议,只看 `data/loading/error/status`。
## 4. 页面集中声明数据源
示例:
```ts
import {
defineDataSources,
httpSource,
mockSource,
mqttSource,
signalrSource,
websocketSource
} from '@dev-screen-starter/data'
export const screenDataSources = defineDataSources({
overview: httpSource({
url: '/api/overview',
intervalMs: 10000,
transform: (raw) => ({
todayOrders: raw.today_orders,
onlineDevices: raw.online_devices,
alertCount: raw.alert_count
})
}),
orderTrend: httpSource({
url: '/api/order-trend',
intervalMs: 30000,
transform: (raw) => ({
categories: raw.times,
values: raw.items.map((item) => item.count)
})
}),
alerts: websocketSource({
url: 'ws://localhost:3000/ws/alerts',
mode: 'append',
maxItems: 20,
transform: (raw) => ({
time: raw.time,
area: raw.area,
status: raw.message
})
}),
deviceStatus: mqttSource({
url: 'ws://broker.example.com/mqtt',
topic: 'factory/device/status',
mode: 'replace'
}),
dotnetEvents: signalrSource({
url: '/hubs/screen',
method: 'screenEvent',
mode: 'append',
maxItems: 50
}),
localFallback: mockSource({
data: {
title: '本地 mock 数据'
}
})
})
```
## 5. 页面消费数据源
```tsx
import { useScreenDataSources } from '@dev-screen-starter/data'
import { screenDataSources } from './dataSources'
export function ProjectScreen() {
const data = useScreenDataSources(screenDataSources)
const overview = data.overview.data
const alerts = data.alerts.data ?? []
return (
<>
<MetricCard label="今日订单" value={overview?.todayOrders ?? 0} unit="单" />
<AlertList rows={alerts} />
</>
)
}
```
## 6. HTTP 数据源
适合:
- 指标卡
- 趋势图
- 排行图
- 低频刷新数据
- 页面初始化数据
```ts
const sources = defineDataSources({
overview: httpSource({
url: '/api/overview',
intervalMs: 10000,
transform: (raw) => ({
orders: raw.orders,
devices: raw.devices
})
})
})
```
字段说明:
- `url`: 请求地址。
- `init`: `fetch` 的 RequestInit 参数。
- `intervalMs`: 轮询间隔,不传则只请求一次。
- `immediate`: 是否立即请求,默认 `true`。
- `transform`: 数据清洗函数。
## 7. WebSocket 数据源
适合:
- 实时告警
- 订单流水
- 设备状态
- 秒级推送数据
```ts
const sources = defineDataSources({
alerts: websocketSource({
url: 'ws://localhost:3000/ws/alerts',
mode: 'append',
maxItems: 20,
transform: (raw) => ({
time: raw.time,
message: raw.message
})
})
})
```
字段说明:
- `url`: WebSocket 地址。
- `protocols`: 可选 WebSocket protocols。
- `mode`: `replace` 或 `append`,默认 `replace`。
- `maxItems`: `append` 模式最多保留多少条。
- `transform`: 单条消息的清洗函数。
WebSocket 消息如果是字符串,会优先尝试 `JSON.parse`。如果不是 JSON,会把原始字符串传给 `transform`。
## 8. MQTT 数据源
当前已预留类型:
```ts
deviceStatus: mqttSource({
url: 'ws://broker.example.com/mqtt',
topic: 'factory/device/status',
mode: 'replace'
})
```
建议:
- 浏览器端 MQTT 通常使用 MQTT over WebSocket。
- 如果客户现场已有 MQTT broker,可以按项目接入 MQTT SDK。
- 如果鉴权复杂,优先让后端网关把 MQTT 转成 WebSocket,再给大屏消费。
## 9. SignalR 数据源
当前已预留类型:
```ts
dotnetEvents: signalrSource({
url: '/hubs/screen',
method: 'screenEvent',
mode: 'append',
maxItems: 50
})
```
建议:
- 客户后端是 .NET 时再引入 SignalR SDK。
- SignalR 适配器应只放在 `packages/data` 或客户项目的数据层,不要散落在业务组件里。
## 10. Demo 当前接入方式
当前 demo 使用 `mockSource` 模拟集中数据源:
```ts
export const demoDataSources = defineDataSources({
metrics: mockSource({ data: metrics, intervalMs: 15000 }),
alerts: mockSource({ data: alertRows, intervalMs: 12000 }),
operationEvents: mockSource({ data: operationEvents, intervalMs: 10000 }),
capacityTrend: mockSource({ data: capacityTrend })
})
```
页面中统一消费:
```ts
const data = useScreenDataSources(demoDataSources)
const metrics = data.metrics.data ?? []
const alertRows = data.alerts.data ?? []
```
后续替换成真实接口时,只需要改 `dataSources.ts`,页面渲染结构可以尽量少改。
## 11. 推荐落地顺序
第一步:
- 使用 `mockSource` 完成页面开发。
- 用 `transform` 提前对齐组件需要的数据结构。
第二步:
- 把初始化数据换成 `httpSource`。
- 对接客户 REST API。
第三步:
- 把告警、设备状态、流水数据换成 `websocketSource`。
第四步:
- 项目确实需要时,再引入 MQTT 或 SignalR SDK,实现对应 adapter。
## 12. 注意事项
- `dataSources` 建议定义在组件外部,保证引用稳定。
- 高频数据不要全部刷新整页,只更新对应数据源。
- WebSocket 的 `append` 模式要设置 `maxItems`,避免列表无限增长。
- 数据清洗放在 `transform`,展示组件只消费干净数据。
- 真实项目里要补鉴权、断线重连、心跳、错误提示策略。
+43 -12
View File
@@ -38,11 +38,27 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
使用方式:
```tsx
<ScreenStage background="#061826">
<ScreenStage background="#061826" scaleMode="fit" debug>
<YourScreen />
</ScreenStage>
```
`scaleMode` 支持:
- `fit`:完整显示设计稿,保持比例,可能留黑边,推荐默认使用。
- `fill`:铺满窗口,保持比例,可能裁切边缘。
- `stretch`:横向和纵向分别缩放,不留黑边,但会变形。
- `none`:不缩放,适合局部调试。
`debug` 开启后会显示设计尺寸、视口尺寸、缩放模式和缩放比例。demo 页面支持通过 URL 参数切换:
```txt
http://localhost:5173/?scaleMode=fit
http://localhost:5173/?scaleMode=fill
http://localhost:5173/?scaleMode=stretch
http://localhost:5173/?scaleMode=none
```
### Panel
用于常规图表面板或信息区域。
@@ -75,11 +91,16 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
当前提供:
- `createLineOption`:折线图,支持单序列和多序列。
- `createAreaTrendOption`:面积趋势图。
- `createBarOption`:柱状图,支持单序列和多序列。
- `createStackedBarOption`:堆叠柱状图。
- `createDualAxisOption`:双轴折线柱状图。
- `createRankBarOption`:横向排名条。
- `createPieOption`:饼图/环图。
- `createRosePieOption`:玫瑰图。
- `createGaugeOption`:仪表盘。
- `createRadarOption`:雷达图。
- `mergeChartOption`:在默认工厂配置基础上做局部覆盖。
推荐用法:
@@ -95,7 +116,7 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
## 4. data
`data` 提供轻量数据工具。
`data` 提供统一数据源工具。一个页面可以集中声明多个数据源,并让不同组件消费同一种 `DataState<T>`。
### requestJson
@@ -105,18 +126,25 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
用于定时刷新接口数据。
适合:
### useScreenDataSources
- 30 秒刷新指标。
- 5 秒刷新告警。
- 项目开发时接 mock loader。
统一消费页面级数据源:
不适合:
```tsx
const data = useScreenDataSources(screenDataSources)
const metrics = data.metrics.data ?? []
```
- 高频毫秒级数据。
- 大规模实时流。
配套声明函数:
这些场景建议按项目单独实现 WebSocket、SSE 或 MQTT。
- `defineDataSources`
- `mockSource`
- `httpSource`
- `websocketSource`
- `mqttSource`
- `signalrSource`
其中 `mockSource`、`httpSource`、`websocketSource` 已可用;`mqttSource`、`signalrSource` 已预留类型和声明入口,具体 SDK 在客户项目需要时再接。
## 5. debug
@@ -126,8 +154,6 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
显示缩放比例、数据更新时间等轻量信息。生产环境默认不显示,项目可显式打开。
## 6. 项目模板
## 6. visual-kit
`visual-kit` 提供轻量大屏视觉材料,不承担图表逻辑。
@@ -137,9 +163,14 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
- `GlowPanel`:带轻微光感的内容面板。
- `CornerFrame`:四角框容器。
- `SectionTitle`:区块标题。
- `TitleBar`:标题栏,支持右侧 action。
- `Divider`:装饰分割线。
- `DigitalNumber`:数字强调。
- `FlipNumber`:数字翻牌。
- `StatusPill`:状态标签。
- `TrendBadge`:趋势标签。
- `ScrollTable`:紧凑滚动表格结构。
- `MarqueeList`:自动滚动列表。
- `WaterLevel`:水位图。
推荐组合:
+5 -2
View File
@@ -98,6 +98,8 @@ doc/
- `TrendBadge`
- `MarqueeList`
- demo-screen 已改为使用图表工厂和 visual-kit 组合出项目型模板。
- `ScreenStage` 已增强 debug 信息展示,支持运行时查看设计尺寸、视口尺寸、缩放模式和缩放比例。
- demo-screen 支持通过 `?scaleMode=fit|fill|stretch|none` 验证不同屏幕适配策略。
后续计划:
@@ -126,13 +128,14 @@ doc/
- 基础装饰组件支持 `className`、`style`、`tone`、`size` 等通用属性。
- 图表工厂覆盖常用交付场景,并保留 ECharts 原生 option 覆盖能力。
- demo-screen 已包含状态区、运行事件、指标卡、趋势、堆叠、排行、玫瑰、双轴、雷达和仪表盘示例。
- `data` 包已新增统一数据源设计,支持页面集中声明 mock、HTTP、WebSocket 数据源,并预留 MQTT、SignalR 类型。
下一步建议:
- 做 `ChartPanel` 组合组件,把 `Panel + EChart + loading/empty/error` 固化下来。
- 给 `data` 包增加 mock/real 数据源切换。
- 给 `data` 包补 WebSocket 重连、心跳、鉴权 header/token 约定。
- 增加 `.env.example` 和项目级接口配置约定。
- 对 `ScreenStage` 做 1366x768、1920x1080、4K 的浏览器截图验收。
- 对 `ScreenStage` 做更多截图验收,覆盖 1366x768、1920x1080、4K 和不同 `scaleMode`。
## 8. 成功标准
+20
View File
@@ -0,0 +1,20 @@
{
"name": "@dev-screen-starter/data",
"version": "0.1.0",
"private": true,
"type": "module",
"exports": {
".": "./src/index.ts"
},
"scripts": {
"build": "tsc --noEmit",
"typecheck": "tsc --noEmit"
},
"dependencies": {
"react": "^19.1.1"
},
"devDependencies": {
"@types/react": "^19.1.16",
"typescript": "^5.9.2"
}
}
+5
View File
@@ -0,0 +1,5 @@
export * from './usePollingData'
export * from './useScreenDataSources'
export * from './request'
export * from './sources'
export * from './types'
+9
View File
@@ -0,0 +1,9 @@
export async function requestJson<T>(url: string, init?: RequestInit): Promise<T> {
const response = await fetch(url, init)
if (!response.ok) {
throw new Error(`Request failed: ${response.status}`)
}
return response.json() as Promise<T>
}
+36
View File
@@ -0,0 +1,36 @@
import type {
DataSource,
HttpDataSource,
MockDataSource,
MqttDataSource,
SignalRDataSource,
WebSocketDataSource
} from './types'
export function mockSource<Result>(source: Omit<MockDataSource<Result>, 'type'>): MockDataSource<Result> {
return { type: 'mock', ...source }
}
export function httpSource<Result, Raw = Result>(source: Omit<HttpDataSource<Result, Raw>, 'type'>): HttpDataSource<Result, Raw> {
return { type: 'http', ...source }
}
export function websocketSource<Result, Raw = Result>(
source: Omit<WebSocketDataSource<Result, Raw>, 'type'>
): WebSocketDataSource<Result, Raw> {
return { type: 'websocket', ...source }
}
export function signalrSource<Result, Raw = Result>(
source: Omit<SignalRDataSource<Result, Raw>, 'type'>
): SignalRDataSource<Result, Raw> {
return { type: 'signalr', ...source }
}
export function mqttSource<Result, Raw = Result>(source: Omit<MqttDataSource<Result, Raw>, 'type'>): MqttDataSource<Result, Raw> {
return { type: 'mqtt', ...source }
}
export function defineDataSources<TSources extends Record<string, DataSource<any, any>>>(sources: TSources): TSources {
return sources
}
+74
View File
@@ -0,0 +1,74 @@
export type DataSourceType = 'mock' | 'http' | 'websocket' | 'signalr' | 'mqtt'
export type DataConnectionStatus = 'idle' | 'connecting' | 'open' | 'closed' | 'error'
export type RealtimeUpdateMode = 'replace' | 'append'
export type DataState<T> = {
data: T | null
loading: boolean
error: string | null
status: DataConnectionStatus
lastUpdated?: number
sourceType?: DataSourceType
}
export type DataTransform<Raw, Result> = (raw: Raw, previous: Result | null) => Result
type BaseDataSource<Result, Raw = unknown> = {
enabled?: boolean
transform?: DataTransform<Raw, Result>
}
export type MockDataSource<Result> = BaseDataSource<Result, Result> & {
type: 'mock'
data: Result | (() => Result)
intervalMs?: number
}
export type HttpDataSource<Result, Raw = unknown> = BaseDataSource<Result, Raw> & {
type: 'http'
url: string
init?: RequestInit
intervalMs?: number
immediate?: boolean
}
export type WebSocketDataSource<Result, Raw = unknown> = BaseDataSource<Result, Raw> & {
type: 'websocket'
url: string
protocols?: string | string[]
mode?: RealtimeUpdateMode
maxItems?: number
}
export type SignalRDataSource<Result, Raw = unknown> = BaseDataSource<Result, Raw> & {
type: 'signalr'
url: string
method: string
mode?: RealtimeUpdateMode
maxItems?: number
}
export type MqttDataSource<Result, Raw = unknown> = BaseDataSource<Result, Raw> & {
type: 'mqtt'
url: string
topic: string
mode?: RealtimeUpdateMode
maxItems?: number
}
export type DataSource<Result = unknown, Raw = unknown> =
| MockDataSource<Result>
| HttpDataSource<Result, Raw>
| WebSocketDataSource<Result, Raw>
| SignalRDataSource<Result, Raw>
| MqttDataSource<Result, Raw>
export type DataSourceMap = Record<string, DataSource<any, any>>
export type InferDataSourceResult<TSource> = TSource extends DataSource<infer Result, any> ? Result : never
export type DataStates<TSources extends DataSourceMap> = {
[Key in keyof TSources]: DataState<InferDataSourceResult<TSources[Key]>>
}
+43
View File
@@ -0,0 +1,43 @@
import { useEffect, useState } from 'react'
type PollingState<T> = {
data?: T
loading: boolean
error?: string
updatedAt?: string
}
export function usePollingData<T>(loader: () => Promise<T>, intervalMs = 30000): PollingState<T> {
const [state, setState] = useState<PollingState<T>>({ loading: true })
useEffect(() => {
let active = true
const run = async () => {
try {
const data = await loader()
if (active) {
setState({ data, loading: false, updatedAt: new Date().toISOString() })
}
} catch (error) {
if (active) {
setState((current) => ({
...current,
loading: false,
error: error instanceof Error ? error.message : String(error)
}))
}
}
}
void run()
const timer = window.setInterval(run, intervalMs)
return () => {
active = false
window.clearInterval(timer)
}
}, [intervalMs, loader])
return state
}
+193
View File
@@ -0,0 +1,193 @@
import { useEffect, useMemo, useState } from 'react'
import { requestJson } from './request'
import type { DataSource, DataSourceMap, DataState, DataStates, RealtimeUpdateMode } from './types'
function createInitialState(source: DataSource<unknown, unknown>): DataState<unknown> {
return {
data: null,
loading: source.enabled === false ? false : true,
error: null,
status: source.enabled === false ? 'idle' : 'connecting',
sourceType: source.type
}
}
function readMockValue<T>(value: T | (() => T)): T {
return typeof value === 'function' ? (value as () => T)() : value
}
function parsePayload(payload: unknown): unknown {
if (typeof payload !== 'string') {
return payload
}
try {
return JSON.parse(payload) as unknown
} catch {
return payload
}
}
function applyTransform(
source: DataSource<unknown, unknown>,
raw: unknown,
previous: unknown
): unknown {
return source.transform ? source.transform(raw, previous) : raw
}
function mergeRealtimeData(
current: unknown,
next: unknown,
mode: RealtimeUpdateMode = 'replace',
maxItems = 100
): unknown {
if (mode !== 'append') {
return next
}
const currentItems = Array.isArray(current) ? current : []
const nextItems = Array.isArray(next) ? next : [next]
return [...nextItems, ...currentItems].slice(0, maxItems)
}
function toErrorMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error)
}
export function useScreenDataSources<TSources extends DataSourceMap>(sources: TSources): DataStates<TSources> {
const sourceEntries = useMemo(() => Object.entries(sources), [sources])
const [states, setStates] = useState<Record<string, DataState<unknown>>>(() =>
Object.fromEntries(sourceEntries.map(([key, source]) => [key, createInitialState(source)]))
)
useEffect(() => {
setStates(Object.fromEntries(sourceEntries.map(([key, source]) => [key, createInitialState(source)])))
const cleanups: Array<() => void> = []
for (const [key, source] of sourceEntries) {
if (source.enabled === false) {
continue
}
const updateState = (patch: Partial<DataState<unknown>>) => {
setStates((current) => ({
...current,
[key]: {
...current[key],
...patch,
sourceType: source.type
}
}))
}
const commitData = (raw: unknown, mode?: RealtimeUpdateMode, maxItems?: number) => {
setStates((current) => {
const previous = current[key]?.data ?? null
const transformed = applyTransform(source, raw, previous)
const data = source.type === 'websocket' || source.type === 'signalr' || source.type === 'mqtt'
? mergeRealtimeData(previous, transformed, mode, maxItems)
: transformed
return {
...current,
[key]: {
data,
loading: false,
error: null,
status: 'open',
lastUpdated: Date.now(),
sourceType: source.type
}
}
})
}
if (source.type === 'mock') {
const run = () => commitData(readMockValue(source.data))
run()
if (source.intervalMs) {
const timer = window.setInterval(run, source.intervalMs)
cleanups.push(() => window.clearInterval(timer))
}
}
if (source.type === 'http') {
let active = true
let abortController: AbortController | null = null
const run = async () => {
abortController?.abort()
abortController = new AbortController()
updateState({ loading: true, error: null, status: 'connecting' })
try {
const raw = await requestJson<unknown>(source.url, {
...source.init,
signal: abortController.signal
})
if (active) {
commitData(raw)
}
} catch (error) {
if (active && !(error instanceof DOMException && error.name === 'AbortError')) {
updateState({ loading: false, error: toErrorMessage(error), status: 'error' })
}
}
}
if (source.immediate !== false) {
void run()
}
if (source.intervalMs) {
const timer = window.setInterval(run, source.intervalMs)
cleanups.push(() => window.clearInterval(timer))
}
cleanups.push(() => {
active = false
abortController?.abort()
})
}
if (source.type === 'websocket') {
if (typeof WebSocket === 'undefined') {
updateState({ loading: false, error: 'WebSocket is not available in this runtime.', status: 'error' })
continue
}
updateState({ status: 'connecting', error: null })
const socket = new WebSocket(source.url, source.protocols)
socket.addEventListener('open', () => updateState({ loading: false, status: 'open', error: null }))
socket.addEventListener('message', (event) => {
commitData(parsePayload(event.data), source.mode, source.maxItems)
})
socket.addEventListener('close', () => updateState({ loading: false, status: 'closed' }))
socket.addEventListener('error', () => updateState({ loading: false, status: 'error', error: 'WebSocket connection error.' }))
cleanups.push(() => socket.close())
}
if (source.type === 'signalr' || source.type === 'mqtt') {
updateState({
loading: false,
status: 'idle',
error: `${source.type} adapter is declared but not installed yet.`
})
}
}
return () => {
cleanups.forEach((cleanup) => cleanup())
}
}, [sourceEntries])
return states as DataStates<TSources>
}
+7
View File
@@ -0,0 +1,7 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"jsx": "react-jsx"
},
"include": ["src"]
}
+44 -4
View File
@@ -1,16 +1,31 @@
import { type CSSProperties, type ReactNode, useEffect, useMemo, useState } from 'react'
import { calculateStageScale, type ScaleMode } from './scale'
import { calculateStageScale, type ScaleMode, type StageMetrics } from './scale'
type ScreenStageProps = {
width?: number
height?: number
scaleMode?: ScaleMode
background?: string
className?: string
debug?: boolean
children: ReactNode
}
export function ScreenStage({ width = 1920, height = 1080, scaleMode = 'fit', background = '#061826', children }: ScreenStageProps) {
const [viewport, setViewport] = useState({ width: window.innerWidth, height: window.innerHeight })
const defaultViewport = () => ({
width: typeof window === 'undefined' ? 1920 : window.innerWidth,
height: typeof window === 'undefined' ? 1080 : window.innerHeight
})
export function ScreenStage({
width = 1920,
height = 1080,
scaleMode = 'fit',
background = '#061826',
className = '',
debug = false,
children
}: ScreenStageProps) {
const [viewport, setViewport] = useState(defaultViewport)
useEffect(() => {
const onResize = () => setViewport({ width: window.innerWidth, height: window.innerHeight })
@@ -20,6 +35,19 @@ export function ScreenStage({ width = 1920, height = 1080, scaleMode = 'fit', ba
const scale = useMemo(() => calculateStageScale({ width, height, scaleMode }, viewport.width, viewport.height), [height, scaleMode, viewport.height, viewport.width, width])
const metrics: StageMetrics = useMemo(
() => ({
designWidth: width,
designHeight: height,
viewportWidth: viewport.width,
viewportHeight: viewport.height,
scaleMode,
scaleX: scale.scaleX,
scaleY: scale.scaleY
}),
[height, scale.scaleX, scale.scaleY, scaleMode, viewport.height, viewport.width, width]
)
const stageStyle: CSSProperties = {
width,
height,
@@ -29,9 +57,21 @@ export function ScreenStage({ width = 1920, height = 1080, scaleMode = 'fit', ba
return (
<main className="screen-viewport">
<section className="screen-stage" style={stageStyle}>
<section className={`screen-stage ${className}`} style={stageStyle}>
{children}
</section>
{debug ? <StageDebug metrics={metrics} /> : null}
</main>
)
}
function StageDebug({ metrics }: { metrics: StageMetrics }) {
return (
<aside className="screen-stage-debug">
<span>design {metrics.designWidth}x{metrics.designHeight}</span>
<span>viewport {metrics.viewportWidth}x{metrics.viewportHeight}</span>
<span>mode {metrics.scaleMode}</span>
<span>scale {metrics.scaleX.toFixed(3)} / {metrics.scaleY.toFixed(3)}</span>
</aside>
)
}
+10
View File
@@ -11,6 +11,16 @@ export type StageScale = {
scaleY: number
}
export type StageMetrics = {
designWidth: number
designHeight: number
viewportWidth: number
viewportHeight: number
scaleMode: ScaleMode
scaleX: number
scaleY: number
}
export function calculateStageScale(screen: ScreenSize, viewportWidth: number, viewportHeight: number): StageScale {
const scaleMode = screen.scaleMode ?? 'fit'