diff --git a/.gitignore b/.gitignore index 281ce7e..07d58ae 100644 --- a/.gitignore +++ b/.gitignore @@ -5,5 +5,5 @@ dist/ .DS_Store *.log coverage/ -data/ +/data/ uploads/ diff --git a/README.md b/README.md index b89ea75..173ba3d 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/apps/demo-screen/src/demo/dataSources.ts b/apps/demo-screen/src/demo/dataSources.ts new file mode 100644 index 0000000..384ff36 --- /dev/null +++ b/apps/demo-screen/src/demo/dataSources.ts @@ -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 + }) +}) diff --git a/apps/demo-screen/src/pages/DemoOverview.tsx b/apps/demo-screen/src/pages/DemoOverview.tsx index 15820e3..bfb1ff8 100644 --- a/apps/demo-screen/src/pages/DemoOverview.tsx +++ b/apps/demo-screen/src/pages/DemoOverview.tsx @@ -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 ( - +
客户项目大屏模板 运营态势总览 +
+ HTTP / WebSocket / MQTT / SignalR ready + scaleMode={scaleMode} +
@@ -96,32 +113,38 @@ export function DemoOverview() {
- + {capacityTrend ? ( + + ) : null} - + {stackedOrders ? ( + + ) : null} - + {regionRank ? ( + + ) : null} @@ -129,34 +152,36 @@ export function DemoOverview() { - + {fulfillmentMix ? ( + + ) : null} - + {qualityRadar ? ( + + ) : null}
- - ) } diff --git a/apps/demo-screen/src/styles/screen.css b/apps/demo-screen/src/styles/screen.css index 0b2c732..114a8b4 100644 --- a/apps/demo-screen/src/styles/screen.css +++ b/apps/demo-screen/src/styles/screen.css @@ -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; diff --git a/doc/data-integration-guide.md b/doc/data-integration-guide.md new file mode 100644 index 0000000..3cc1230 --- /dev/null +++ b/doc/data-integration-guide.md @@ -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`。 + +## 2. 当前实现状态 + +已实现: + +- `mockSource` +- `httpSource` +- `websocketSource` +- `defineDataSources` +- `useScreenDataSources` + +已预留类型和声明函数: + +- `signalrSource` +- `mqttSource` + +SignalR 和 MQTT 当前不会引入 SDK,也不会真实连接;它们会返回 `idle` 状态和提示信息。后续客户项目需要时,再接入具体 SDK 或后端网关。 + +## 3. 统一状态模型 + +每个数据源都会返回同一种结构: + +```ts +type DataState = { + 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 ( + <> + + + + ) +} +``` + +## 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`,展示组件只消费干净数据。 +- 真实项目里要补鉴权、断线重连、心跳、错误提示策略。 diff --git a/doc/framework.md b/doc/framework.md index 3aac56e..4ea498a 100644 --- a/doc/framework.md +++ b/doc/framework.md @@ -38,11 +38,27 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个 使用方式: ```tsx - + ``` +`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`。 ### 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`:水位图。 推荐组合: diff --git a/doc/project-plan.md b/doc/project-plan.md index 012358f..7fc2a96 100644 --- a/doc/project-plan.md +++ b/doc/project-plan.md @@ -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. 成功标准 diff --git a/packages/data/package.json b/packages/data/package.json new file mode 100644 index 0000000..a9ec26e --- /dev/null +++ b/packages/data/package.json @@ -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" + } +} diff --git a/packages/data/src/index.ts b/packages/data/src/index.ts new file mode 100644 index 0000000..bf251e4 --- /dev/null +++ b/packages/data/src/index.ts @@ -0,0 +1,5 @@ +export * from './usePollingData' +export * from './useScreenDataSources' +export * from './request' +export * from './sources' +export * from './types' diff --git a/packages/data/src/request.ts b/packages/data/src/request.ts new file mode 100644 index 0000000..4a27cca --- /dev/null +++ b/packages/data/src/request.ts @@ -0,0 +1,9 @@ +export async function requestJson(url: string, init?: RequestInit): Promise { + const response = await fetch(url, init) + + if (!response.ok) { + throw new Error(`Request failed: ${response.status}`) + } + + return response.json() as Promise +} diff --git a/packages/data/src/sources.ts b/packages/data/src/sources.ts new file mode 100644 index 0000000..3dfe802 --- /dev/null +++ b/packages/data/src/sources.ts @@ -0,0 +1,36 @@ +import type { + DataSource, + HttpDataSource, + MockDataSource, + MqttDataSource, + SignalRDataSource, + WebSocketDataSource +} from './types' + +export function mockSource(source: Omit, 'type'>): MockDataSource { + return { type: 'mock', ...source } +} + +export function httpSource(source: Omit, 'type'>): HttpDataSource { + return { type: 'http', ...source } +} + +export function websocketSource( + source: Omit, 'type'> +): WebSocketDataSource { + return { type: 'websocket', ...source } +} + +export function signalrSource( + source: Omit, 'type'> +): SignalRDataSource { + return { type: 'signalr', ...source } +} + +export function mqttSource(source: Omit, 'type'>): MqttDataSource { + return { type: 'mqtt', ...source } +} + +export function defineDataSources>>(sources: TSources): TSources { + return sources +} diff --git a/packages/data/src/types.ts b/packages/data/src/types.ts new file mode 100644 index 0000000..eabfb84 --- /dev/null +++ b/packages/data/src/types.ts @@ -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 = { + data: T | null + loading: boolean + error: string | null + status: DataConnectionStatus + lastUpdated?: number + sourceType?: DataSourceType +} + +export type DataTransform = (raw: Raw, previous: Result | null) => Result + +type BaseDataSource = { + enabled?: boolean + transform?: DataTransform +} + +export type MockDataSource = BaseDataSource & { + type: 'mock' + data: Result | (() => Result) + intervalMs?: number +} + +export type HttpDataSource = BaseDataSource & { + type: 'http' + url: string + init?: RequestInit + intervalMs?: number + immediate?: boolean +} + +export type WebSocketDataSource = BaseDataSource & { + type: 'websocket' + url: string + protocols?: string | string[] + mode?: RealtimeUpdateMode + maxItems?: number +} + +export type SignalRDataSource = BaseDataSource & { + type: 'signalr' + url: string + method: string + mode?: RealtimeUpdateMode + maxItems?: number +} + +export type MqttDataSource = BaseDataSource & { + type: 'mqtt' + url: string + topic: string + mode?: RealtimeUpdateMode + maxItems?: number +} + +export type DataSource = + | MockDataSource + | HttpDataSource + | WebSocketDataSource + | SignalRDataSource + | MqttDataSource + +export type DataSourceMap = Record> + +export type InferDataSourceResult = TSource extends DataSource ? Result : never + +export type DataStates = { + [Key in keyof TSources]: DataState> +} diff --git a/packages/data/src/usePollingData.ts b/packages/data/src/usePollingData.ts new file mode 100644 index 0000000..b93858d --- /dev/null +++ b/packages/data/src/usePollingData.ts @@ -0,0 +1,43 @@ +import { useEffect, useState } from 'react' + +type PollingState = { + data?: T + loading: boolean + error?: string + updatedAt?: string +} + +export function usePollingData(loader: () => Promise, intervalMs = 30000): PollingState { + const [state, setState] = useState>({ 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 +} diff --git a/packages/data/src/useScreenDataSources.ts b/packages/data/src/useScreenDataSources.ts new file mode 100644 index 0000000..38891c2 --- /dev/null +++ b/packages/data/src/useScreenDataSources.ts @@ -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): DataState { + return { + data: null, + loading: source.enabled === false ? false : true, + error: null, + status: source.enabled === false ? 'idle' : 'connecting', + sourceType: source.type + } +} + +function readMockValue(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, + 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(sources: TSources): DataStates { + const sourceEntries = useMemo(() => Object.entries(sources), [sources]) + + const [states, setStates] = useState>>(() => + 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>) => { + 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(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 +} diff --git a/packages/data/tsconfig.json b/packages/data/tsconfig.json new file mode 100644 index 0000000..d0b8519 --- /dev/null +++ b/packages/data/tsconfig.json @@ -0,0 +1,7 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "jsx": "react-jsx" + }, + "include": ["src"] +} diff --git a/packages/screen-core/src/ScreenStage.tsx b/packages/screen-core/src/ScreenStage.tsx index 276c36a..bbc2fef 100644 --- a/packages/screen-core/src/ScreenStage.tsx +++ b/packages/screen-core/src/ScreenStage.tsx @@ -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 (
-
+
{children}
+ {debug ? : null}
) } + +function StageDebug({ metrics }: { metrics: StageMetrics }) { + return ( + + ) +} diff --git a/packages/screen-core/src/scale.ts b/packages/screen-core/src/scale.ts index 3a4787e..403cd11 100644 --- a/packages/screen-core/src/scale.ts +++ b/packages/screen-core/src/scale.ts @@ -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'