@rfkit/charts 1.3.13 → 1.4.1

package/README.md

@@ -1,6 +1,9 @@
 # rfkit-charts
 
-服务于无线电监测产品的 web 图表组件库
+服务于无线电监测产品的 Web 图表组件库。
+
+- 仓库名：`rfkit-charts`
+- npm 发布名：`@rfkit/charts`
 
 ## 安装
 
@@ -8,262 +11,199 @@
 pnpm add @rfkit/charts
 ```
 
-## 基本使用
+正式版本由源码仓库内的 Release PR 自动发布到 npm；仓库里的本地 `publish:*` 脚本只作为维护调试或应急入口，不属于常规发布流程。
+
+## 发布入口
+
+当前对外正式入口只有两个：
+
+- JS / TS：`@rfkit/charts`
+- CSS bridge：`@rfkit/charts/tailwind-bridge.css`
+
+默认直接从包根导入组件即可。组件运行所需样式会随包根入口自动加载，普通消费方不需要额外引 CSS。
+
+## 快速开始
+
+公开组件默认通过 `ref` 暴露 `Publish` 能力，不走 `publish` prop。
 
-```jsx
+```tsx
+import { useEffect, useRef } from 'react';
 import {
-  // 频谱图
+  ChartType,
+  PSType,
   Spectrum,
-  LevelStream,
-  // IQ图
-  IQ,
-  // 仪表图
-  Gauge,
-  Dial,
-  // 辅助图形
-  Heatmap,
-  Occupancy,
+  type Publish
 } from '@rfkit/charts';
 
-// 行为推送
-const publishRef = useRef(null);
-const handlePublishChange = (publish) => {
-  publishRef.current? = publish;
-};
-
-// 图表类型
-export enum ChartType {
-  // 频谱图
-  SingleFrequency = 'singleFrequency',
-  Scan = 'scan',
-  MScan = 'mscan',
-  ScanDF360 = 'ScanDF360',
-  DDC = 'ddc',
-  Lite = 'lite',
-  LiteNormalized = 'liteNormalized',
-  LevelStream = 'levelStream',
-  // IQ图
-  IQEye = 'iqEye',
-  IQLine = 'iqLine',
-  IQPlanisphere = 'iqPlanisphere',
-  IQStream = 'iqStream',
-  // 辅助图形
-  Heatmap = 'heatmap',
-  Occupancy = 'occupancy',
-}
+export function Demo() {
+  const chartRef = useRef<Publish>(null);
+
+  useEffect(() => {
+    chartRef.current?.({
+      pstype: PSType.Spectrum,
+      data: new Float32Array([12, 28, 19, 35, 17])
+    });
+  }, []);
 
-// 频谱图
-<Spectrum type="singleFrequency" publish={handlePublishChange} /> // 单频频谱
-<Spectrum type="scan" publish={handlePublishChange} /> // 扫描频谱
-<Spectrum type="scanDF360" publish={handlePublishChange} /> // 扫描测向概率统计
-<Spectrum type="ddc" publish={handlePublishChange} channel onChannelChange /> // DCC
-<Spectrum type="lite" publish={handlePublishChange} /> // 精简模式
-<Spectrum type="liteNormalized" publish={handlePublishChange} /> // 精简模式（Y轴范围0-1）
-
-// DDC特殊参数
-export interface Props {
-  channel?: number; // 默认32
-  onChannelChange?: (c: {
-    frequency: number;
-    type: MarkerEventType;
-    list: number[];
-  }) => void;
+  return <Spectrum ref={chartRef} type={ChartType.SingleFrequency} />;
 }
+```
 
-// 电平瀑布图
-<LevelStream />
+## Publish 使用方式
 
-// IQ类型
-<IQ type={ChartType} publish={handlePublishChange} />
+大多数图表的数据输入都通过组件 `ref` 返回的 `Publish` 函数完成。
 
-// 仪表盘
-<Gauge publish={handlePublishChange} />
-<Dial axisY={{range}} onChange={onChange} publish={handlePublishChange} />
-```
+```tsx
+import { useEffect, useRef } from 'react';
+import {
+  Gauge,
+  PSType,
+  type Publish
+} from '@rfkit/charts';
 
-**publish（行为推送工具）**
-
-```typescript
-export enum PSType {
-  // 频谱数据
-  SPECTRUM = 'spectrum',
-  // 天线因子数据
-  ANTENNA_FACTOR = 'antennaFactor',
-  // 占用度数据
-  OCCUPANCY = 'occupancy',
-  // 电平流数据
-  LEVEL_STREAM = 'levelStream',
-  // 瀑布图数据
-  HEATMAP = 'heatmap',
-  // IQ数据
-  IQ = 'IQ',
-  // 示向度盘
-  DIAL = 'dial',
-  // 刻度尺
-  GAUGE = 'gauge',
-
-  // 频谱线属性
-  SERIES = 'series',
-  // 频谱带宽规则：一般用于单频频谱
-  SPECTRUM_BANDWIDTH = 'spectrumBandwidth',
-  // 多段扫描规则：一般用于扫描数据的多段组合
-  SEGMENTS = 'segments',
-  // 多路DCC
-  CHANNELS = 'channels',
-  // Marker
-  MARKER = 'marker',
-
-  // 图形操作
-  RESET = 'reset',
-}
+export function GaugeDemo() {
+  const gaugeRef = useRef<Publish>(null);
 
-// 系列配置
-interface SeriesConfig {
-  readonly name: string;
-  // 内外可设置属性
-  label?: string;
-  color?: string;
-}
+  useEffect(() => {
+    gaugeRef.current?.({
+      pstype: PSType.Gauge,
+      value: 42,
+      limit: 60
+    });
 
-// 推送频谱线属性
-export interface SetSeries extends SeriesConfig {
-  pstype: PSType.Series;
-}
+    gaugeRef.current?.({
+      pstype: PSType.Reset
+    });
+  }, []);
 
-// 设置频谱带宽规则
-export interface SetSpectrumBandwidth extends SpectrumBandwidth {
-  pstype: PSType.SpectrumBandwidth;
+  return <Gauge ref={gaugeRef} />;
 }
+```
 
-// 设置多段扫描规则
-export interface SetSegments {
-  pstype: PSType.Segments;
-  event?: SegmentsEvent; // 事件类型：默认覆盖数据
-  data?: SegmentsOriginal[]; // 多段扫描规则：设置数据才使用
-  index?: number; // 段索引：需要外部聚焦某段才使用
-}
+常用公开类型：
 
-// 设置天线因子
-export interface SetAntennaFactor {
-  pstype: PSType.AntennaFactor;
-  data: Float32Array;
-}
+- `Publish`
+- `PublishData`
+- `PublishSpectrum`
+- `PublishHeatmap`
+- `PublishIQ`
+- `PublishLevelStream`
+- `PublishDial`
+- `PublishGauge`
+- `SetSeries`
+- `SetSegments`
+- `SetMarker`
 
-// 设置台站库信息
-export interface SetStationInfo {
-  pstype: PSType.StationInfo;
-  data: StationInfoType[];
-}
+工具栏相关命名统一使用：
 
-// 设置多路DCC信道
-export interface SetChannels {
-  pstype: PSType.Channels;
-  event: MarkerEventType;
-  frequency?: number;
-}
+- 工具栏枚举使用 `ToolbarItemType`
+- 组件参数使用 `toolbar`
 
-// 设置Marker
-export interface SetMarker {
-  pstype: PSType.Marker;
-  event: MarkerEventType;
-  marker?: Partial<MarkerType>;
-  frequencies?: number[]; // 设计规定：frequencies必须是频率数据
-  silent?: boolean; // 是否通知外部onChange回调
-}
+## 主题接入
 
-// 额外的频谱数据
-export interface SpectrumExtraData {
-  [key: string]: Float32Array;
-}
-// 推送频谱数据
-export interface PublishSpectrum {
-  pstype: PSType.Spectrum;
-  data?: Float32Array;
-  // 一般仅在静态绘制
-  maxData?: Float32Array;
-  minData?: Float32Array;
-  avgData?: Float32Array;
-  backgroundNoiseData?: Float32Array;
-  templateData?: Float32Array;
-  extraData?: SpectrumExtraData;
-  // 瀑布图可选参数
-  timestamp?: string;
-  // 扫描可选参数
-  offset?: number; // 当前段的点偏移量
-  segmentOffset?: number; // 当前段的索引
-}
+charts 只读取根节点上的两个契约：
 
-// 推送瀑布图数据
-export interface PublishHeatmap {
-  pstype: PSType.Heatmap;
-  data: TimestampedFloat32Array[];
-  timestamps: number[];
-}
+- `theme="light" | "dark"`
+- `theme-follow-OS="true" | "false"`
 
-// 推送占用度数据
-export interface PublishOccupancy {
-  pstype: PSType.Occupancy;
-  data: Float32Array;
-  totalOccupancy: number;
-}
+应用层直接写这两个属性即可：
 
-// 推送电平流数据
-export interface PublishLevelStream {
-  pstype: PSType.LevelStream;
-  data: number;
-}
+```ts
+document.documentElement.setAttribute('theme', 'dark');
+document.documentElement.setAttribute('theme-follow-OS', 'false');
+```
 
-// 推送IQ数据
-export interface PublishIQ {
-  pstype: PSType.IQ;
-  IData: number[];
-  Qdata: number[];
-}
+如果宿主已经在用 `@rfkit/theme`，通常不需要额外迁移，因为它写的也是同一套根契约。
+
+### `initChartsTheme()`
+
+`initChartsTheme()` 现在只承担三件事：
+
+- 覆盖 charts 默认 `tokens`
+- 覆盖默认 `sizes`
+- 通过 `onChange` 订阅解析后的主题状态
+
+```ts
+import { initChartsTheme } from '@rfkit/charts';
+
+initChartsTheme({
+  onChange: ({ followOS, theme, contractTheme }) => {
+    console.log(followOS, theme, contractTheme);
+  },
+  tokens: {
+    semantic: {
+      primary: {
+        light: '#2A51F7',
+        dark: '#4371F8'
+      }
+    }
+  },
+  sizes: {
+    spacing: {
+      base: {
+        middle: '8px',
+        small: '4px'
+      }
+    }
+  }
+});
+```
 
-// 推送Dial数据
-export interface PublishDial {
-  pstype?: PSType.Dial;
-  series: Array<{
-    value: number;
-    color: string;
-  }>;
-  range?: number[]; // 概率范围 0-360
-  yawAngle?: number; // 偏航角 0-360
-  isNorthFacing?: boolean; // 是否朝北
-}
+### 读取和订阅主题状态
 
-// 推送Gauge数据
-export interface PublishGauge {
-  pstype?: PSType.Gauge;
-  value: number; // 值
-  limit: number; // 门限值
-}
+```ts
+import {
+  getChartsThemeState,
+  subscribeChartsThemeChange
+} from '@rfkit/charts';
 
-// 推送图形操作
-export interface Reset {
-  pstype: PSType.Reset;
-}
+const state = getChartsThemeState();
+console.log(state.theme, state.preference);
 
-// 推送渲染数据（内部）
-export interface Render {
-  pstype: PSType.Render;
-  [key: string]: unknown;
-}
+const cleanup = subscribeChartsThemeChange((nextState) => {
+  console.log(nextState.followOS, nextState.contractTheme);
+});
+
+cleanup();
+```
+
+### `tailwind-bridge.css`
 
-export type PublishData =
-  | SetSeries
-  | SetSpectrumBandwidth
-  | SetSegments
-  | SetChannels
-  | SetMarker
-  | SetAntennaFactor
-  | PublishSpectrum
-  | PublishHeatmap
-  | PublishOccupancy
-  | PublishLevelStream
-  | PublishIQ
-  | PublishDial
-  | PublishGauge
-  | Reset
-  | Render;
+只有当宿主自己也在用 `Tailwind CSS v4 + shadcn/ui`，并且想复用 charts 的 canonical token 时，才需要额外引入：
+
+```css
+@import "tailwindcss";
+@import "@rfkit/charts/tailwind-bridge.css";
 ```
+
+这份 bridge 的边界是：
+
+- 只做 canonical charts token 到 Tailwind / shadcn 语义色板的映射
+- 不包含全局 reset
+- 不再兜底旧 `--theme-*` 变量
+- 不负责替宿主生成 `:root` 上的 canonical token
+
+## 非公开边界
+
+以下内容不属于对外源码 API：
+
+- 任意 `src/**` 源码路径
+- `test/**` preview / example 宿主
+- 仓库内部工程文档
+
+## 主题变更摘要
+
+当前主题系统已经完成二阶段收口，外部需要注意的 breaking change 主要有：
+
+- `initChartsTheme()` 不再接受 `themeConfigs` / `sizeConfigs` / `subscribeThemeChange`
+- 新配置入口改为 `tokens` / `sizes` / `onChange`
+- `applyChartsTheme()` 与 `applyChartsThemePreference()` 已移除
+- 默认运行时不再输出旧 `--theme-*` alias
+- `@rfkit/charts/tailwind-bridge.css` 不再暴露 deprecated bridge token
+
+## 文档边界
+
+- 对外安装、接入方式、主题契约和常用用法以本文为准。
+- 精确公开 API 以 `@rfkit/charts` 包根导出的类型声明和编辑器智能提示为准。
+- npm 打包产物只同步根 `README.md`，不会把仓库内的 `docs/*` 一并作为公开文档入口发布。
+- 仓库内部专题文档只在源码仓库内维护，不属于发布包对外文档入口。

package/{lib → charts}/index.d.ts

@@ -5,4 +5,4 @@ import IQ from './IQ';
 import LevelStream from './LevelStream';
 import Occupancy from './Occupancy';
 import Spectrum from './Spectrum';
-export { Spectrum, LevelStream, IQ, Gauge, Dial, Heatmap, Occupancy };
+export { Dial, Gauge, Heatmap, IQ, LevelStream, Occupancy, Spectrum };

package/components/AxisY/heatmap/index.d.ts

@@ -1,6 +1,6 @@
 import type React from 'react';
 import type { RenderChartType } from '../../../types';
-import GradientRibbon from './type/Default/GradientRibbon';
+import GradientRibbon from './variants/standard/GradientRibbon';
 export { GradientRibbon };
 interface Props {
     id: string;

package/components/AxisY/heatmap/variants/standard/index.d.ts

@@ -0,0 +1,6 @@
+import type React from 'react';
+interface Props {
+    id: string;
+}
+declare const StandardHeatmapAxisYVariant: React.FC<Props>;
+export default StandardHeatmapAxisYVariant;

package/components/AxisY/spectrum/controls/index.d.ts

@@ -0,0 +1,3 @@
+export { default as AutorangingControl } from './AutorangingControl';
+export { default as StepControl } from './StepControl';
+export { default as UnitControl } from './UnitControl';

package/components/AxisY/spectrum/index.d.ts

@@ -1,9 +1,10 @@
 import type React from 'react';
 import type { RenderChartType } from '../../../types';
-import { useRangeAutoFocus } from './useRanging/ranging';
 interface Props {
     chart: RenderChartType;
 }
 declare const AxisYSpectrum: React.FC<Props>;
 export default AxisYSpectrum;
-export { useRangeAutoFocus };
+export * from './controls';
+export * from './presenters';
+export * from './useRanging';

package/components/AxisY/spectrum/{components/Ticks → presenters/TicksPanel}/index.d.ts

@@ -7,12 +7,12 @@ interface RangeProps {
         isHand: string;
     }) => void;
     moveBoundary?: (isUP: boolean, isTop: boolean) => void;
-    setAxisY(e: {
+    setAxisY(event: {
         realRange: AxisYRange;
     }): unknown;
 }
 interface Props {
     ranging: RangeProps;
 }
-declare const Ticks: React.FC<Props>;
-export default Ticks;
+declare const TicksPanel: React.FC<Props>;
+export default TicksPanel;

package/components/AxisY/spectrum/presenters/index.d.ts

@@ -0,0 +1 @@
+export { default as TicksPanel } from './TicksPanel';

package/components/AxisY/spectrum/useRanging/index.d.ts

@@ -1,7 +1,10 @@
+import { useVirtualRange } from './tools';
 import type { RenderChartType } from '../../../../types';
-import Ranging from './ranging';
+import Ranging, { RangeController, useRangeAutoFocus, useRangeMove, useRangeSet } from './ranging';
+import { getVirtualLevel, range2realRange } from './tools';
 interface Props {
     chart: RenderChartType;
 }
 declare const useRange: ({ chart }: Props) => Ranging;
 export default useRange;
+export { getVirtualLevel, RangeController, range2realRange, useRangeAutoFocus, useRangeMove, useRangeSet, useVirtualRange };

package/components/AxisY/spectrum/useRanging/ranging.d.ts

@@ -4,7 +4,7 @@ import type { AxisYRange, RecursiveFunction, RecursiveObject } from '../../../..
  *
  * @class Range
  */
-export default class Range {
+declare class RangeController {
     state: RecursiveObject;
     constructor(props: RecursiveObject);
     /**
@@ -47,3 +47,5 @@ export default class Range {
 export declare const useRangeAutoFocus: (id: string, func?: RecursiveFunction) => (...args: any[]) => void;
 export declare const useRangeMove: (globalID: string, func?: RecursiveFunction) => (...args: any[]) => void;
 export declare const useRangeSet: (globalID: string, func?: RecursiveFunction) => (...args: any[]) => void;
+export { RangeController };
+export default RangeController;

package/components/Container/runtime.d.ts

@@ -0,0 +1,10 @@
+import type { SystemConfig } from '../../types/store';
+export interface ContainerSizeSnapshot {
+    height: number;
+    width: number;
+}
+type ContainerElementLike = Pick<HTMLElement, 'offsetHeight' | 'offsetWidth'>;
+export declare const readContainerSize: (element: ContainerElementLike | null | undefined) => ContainerSizeSnapshot | null;
+export declare const hasContainerSizeChanged: (previousSize: ContainerSizeSnapshot | null, nextSize: ContainerSizeSnapshot | null) => boolean;
+export declare const createNextSystemConfig: (system: SystemConfig, size: ContainerSizeSnapshot) => SystemConfig;
+export {};

package/components/Cursor/popover-support.d.ts

@@ -0,0 +1,8 @@
+import type React from 'react';
+export declare const POPOVER_ROW_CLASS = "mt-1 flex items-center justify-between gap-1 text-xs text-popover-foreground";
+export declare const POPOVER_VALUE_CLASS = "inline-flex min-w-9 justify-end";
+export declare const useCursorPopoverUpdateKey: (key: string, id: string) => number;
+export declare const FrequencyDisplay: React.FC<{
+    frequency: string;
+    unit: string;
+}>;

package/components/Cursor/registry.d.ts

@@ -0,0 +1,7 @@
+import type React from 'react';
+import { ModuleType } from '../../config';
+export declare const resolveCursorPopover: ({ id, mode, type }: {
+    id: string;
+    mode?: ModuleType;
+    type: ModuleType;
+}) => React.ReactNode;

package/components/DragSelectBox/index.d.ts

@@ -3,12 +3,14 @@
  * 用于创建可拖拽、可调整大小的矩形框
  */
 import type React from 'react';
-import type { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 import { type RectPosition } from '../../hooks/useDragSelect';
 export interface DragSelectBoxProps {
     enabled: boolean;
     defaultRect?: Partial<RectPosition>;
     minSize?: number;
+    minWidth?: number;
+    minHeight?: number;
     maxSize?: number;
     snapThreshold?: number;
     onChange?: (rect: RectPosition) => void;

package/components/GridLines/OccupancyDashed/index.d.ts

@@ -0,0 +1,3 @@
+import type React from 'react';
+declare const OccupancyDashed: React.FC;
+export default OccupancyDashed;

package/components/{Dropdown → Overlay/Dropdown}/index.d.ts

@@ -1,17 +1,25 @@
 import type React from 'react';
 export interface DropdownOption {
-    value: string | number | null;
-    label: string;
+    type?: 'item' | 'separator';
+    value?: string | number | null;
+    label?: string;
     style?: React.CSSProperties;
     render?: () => React.ReactNode;
     disabled?: boolean;
+    onSelect?: (value: string | number | null) => void;
 }
 interface DropdownProps {
     value: string | number | null;
     options: DropdownOption[];
     onChange?: (value: string | number | null) => void;
     placeholder?: string | React.ReactNode;
+    triggerContent?: React.ReactNode;
+    triggerTitle?: React.ReactNode;
     closeOnSelect?: boolean;
+    triggerVariant?: 'default' | 'plain';
+    showChevron?: boolean;
+    triggerClassName?: string;
+    contentClassName?: string;
 }
 declare const Dropdown: React.FC<DropdownProps>;
 export default Dropdown;

package/components/{Tooltip → Overlay/Tooltip}/index.d.ts

@@ -1,4 +1,4 @@
-import React from 'react';
+import type React from 'react';
 type TooltipTriggerProps = React.HTMLAttributes<HTMLElement> & React.RefAttributes<HTMLElement>;
 type TooltipTriggerElement = React.ReactElement<TooltipTriggerProps>;
 interface TooltipProps {

package/components/Overlay/index.d.ts

@@ -0,0 +1,4 @@
+export { type DropdownOption, default as Dropdown } from './Dropdown';
+export { default as Popover } from './Popover';
+export { default as Portal } from './Portal';
+export { default as Tooltip } from './Tooltip';

package/components/{ToolsBar → Toolbar/controls}/SeriesControl/index.d.ts

@@ -1,4 +1,4 @@
-import { ChartType } from '../../../config';
+import { ChartType } from '../../../../config';
 interface Props {
     type?: ChartType;
 }

package/components/Toolbar/controls/index.d.ts

@@ -0,0 +1,4 @@
+export { default as Reset } from './Reset';
+export { default as SegmentsDisplayControl } from './SegmentsDisplayControl';
+export { default as SeriesControl } from './SeriesControl';
+export { default as SeriesDisplayControl } from './SeriesDisplayControl';

package/components/{ToolsBar → Toolbar/decorations}/GradientRibbon/index.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { type CSMCallback } from '../../../utils/subscription';
+import { type CSMCallback } from '../../../../utils/subscription';
 export declare const handleColor: (globalID?: string, name?: string, func?: CSMCallback) => (...args: any[]) => void;
 declare const _default: React.NamedExoticComponent<{}>;
 export default _default;

package/components/Toolbar/decorations/index.d.ts

@@ -0,0 +1,2 @@
+export { default as GradientRibbon, handleColor } from './GradientRibbon';
+export { default as SpacerLine } from './SpacerLine';

package/components/Toolbar/primitives/IconBox.d.ts

@@ -0,0 +1,11 @@
+import type React from 'react';
+import type { ReactNode } from 'react';
+import { type ToolbarTone } from './styles';
+import { type ToolbarSurfaceProps } from './ToolbarSurface';
+export interface IconBoxProps extends Pick<ToolbarSurfaceProps, 'style' | 'className' | 'title' | 'disabled' | 'onClick' | 'onDoubleClick'> {
+    children: ReactNode;
+    active?: boolean;
+    tone?: ToolbarTone;
+}
+declare const IconBox: React.FC<IconBoxProps>;
+export default IconBox;