waveform-analysis 0.1.70 → 0.1.72

package/src/demo/embedBridge.ts

@@ -0,0 +1,85 @@
+import type { Router } from 'vue-router'
+
+type EmbedMessage =
+  | { type: 'ready'; appKey: string }
+  | { type: 'route-change'; appKey: string; route: string }
+  | { type: 'resize'; appKey: string; height: number }
+
+const routeLimit = 2048
+
+export function installDemoEmbedBridge(router: Router) {
+  const hostOrigin = trustedHostOrigin()
+  if (!hostOrigin) return () => undefined
+
+  const post = (message: EmbedMessage) => window.parent.postMessage(message, hostOrigin)
+  const requestedRoute = safeRoute(new URLSearchParams(window.location.search).get('childRoute'))
+  let active = false
+
+  const removeRouteHook = router.afterEach((route) => {
+    if (!active) return
+    post({
+      type: 'route-change',
+      appKey: appKey(),
+      route: route.fullPath,
+    })
+  })
+  const observer = new ResizeObserver(() =>
+    post({
+      type: 'resize',
+      appKey: appKey(),
+      height: Math.ceil(document.documentElement.scrollHeight),
+    }),
+  )
+  observer.observe(document.documentElement)
+  void router.isReady().then(async () => {
+    if (requestedRoute && requestedRoute !== router.currentRoute.value.fullPath)
+      await router.replace(requestedRoute)
+    active = true
+    post({ type: 'ready', appKey: appKey() })
+    post({ type: 'route-change', appKey: appKey(), route: router.currentRoute.value.fullPath })
+    post({
+      type: 'resize',
+      appKey: appKey(),
+      height: Math.ceil(document.documentElement.scrollHeight),
+    })
+  })
+
+  return () => {
+    removeRouteHook()
+    observer.disconnect()
+  }
+}
+
+function appKey() {
+  return import.meta.env.VITE_EMBED_APP_KEY || 'waveform-analysis'
+}
+
+function trustedHostOrigin() {
+  const configured = import.meta.env.VITE_EMBED_HOST_ORIGIN
+  if (!configured || window.parent === window) return null
+  try {
+    const expected = new URL(configured).origin
+    return new URL(document.referrer).origin === expected ? expected : null
+  } catch {
+    return null
+  }
+}
+
+function safeRoute(value: string | null) {
+  if (
+    !value ||
+    value.length > routeLimit ||
+    !value.startsWith('/') ||
+    Array.from(value).some(
+      (character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127,
+    )
+  )
+    return null
+  try {
+    return new URL(value, 'https://waveform.invalid').origin === 'https://waveform.invalid'
+      ? value
+      : null
+  } catch {
+    return null
+  }
+}

package/src/demo/types.ts

@@ -23,6 +23,7 @@ interface SelectOption<T> {
 }
 
 export interface DemoControlPanelModel {
+  toolbarVisible: boolean
   controlsOpen: boolean
   displayMode: WaveformDisplayMode
   overlayMode: WaveformOverlayMode
@@ -50,6 +51,10 @@ export interface DemoControlPanelModel {
   verticalGridColor: string
   xAxisLineVisible: boolean
   yAxisLineVisible: boolean
+  upperPaddingEnabled: boolean
+  lowerPaddingEnabled: boolean
+  upperPaddingPercent: number
+  lowerPaddingPercent: number
   xAxisLabelFormatterEnabled: boolean
   xAxisLabelFormat: DemoXAxisLabelFormat
   xAxisLabelFormatOptions: Array<SelectOption<DemoXAxisLabelFormat>>
@@ -87,6 +92,7 @@ export interface DemoControlPanelModel {
 }
 
 export interface DemoChartModel {
+  toolbarVisible: boolean
   data: WaveformData
   initialXDomain?: [number, number]
   displayMode: WaveformDisplayMode

package/src/index.ts

@@ -41,6 +41,7 @@ export type {
   WaveformXAxisLabelFormatterContext,
   WaveformXAxisLabelFormatter,
   WaveformAxesOptions,
+  WaveformYAxisLabelTextStyle,
   WaveformZeroLineOptions,
   // 数据类型
   SingleWaveformData,
@@ -97,3 +98,20 @@ export {
 } from './core'
 
 export { parseWaveformAnnotations, serializeWaveformAnnotations } from './components/annotation'
+
+export type {
+  WaveformToolbarItem,
+  WaveformToolbarOptions,
+  WaveformControlTarget,
+  WaveformControlAction,
+  WaveformCommandMetadata,
+  WaveformTargetStatus,
+  WaveformViewportSnapshot,
+  WaveformTargetResult,
+  WaveformControlResult,
+  WaveformControlState,
+  WaveformImageExportOptions,
+  WaveformImageExportErrorCode,
+  WaveformImageExportError,
+  WaveformChartHandle,
+} from './types/controls'

package/src/types/chart.ts

@@ -1,3 +1,5 @@
+import type { WaveformCommandMetadata } from './controls'
+
 /**
  * 波形数据点
  */
@@ -19,6 +21,8 @@ export type WaveformLayoutPreset = 'default' | 'edge-compact'
 export type WaveformUnitDisplayMode =
   | 'axis'
   | 'legend-single-series'
+  /** Append units to Y-axis names while retaining names on multi-series pages. */
+  | 'channel-label'
   /** Label and legend units; hide all channel titles on pages containing a multi-series track. */
   | 'channel-label-or-legend'
 
@@ -34,7 +38,7 @@ export type WaveformDisplayMode = 'independent' | 'separated' | 'compact'
 export type WaveformOverlayMode = 'single-axis' | 'multi-axis'
 
 /** 标注工具模式 */
-export type WaveformInteractionMode = 'zoom' | 'annotation'
+export type WaveformInteractionMode = 'zoom' | 'annotation' | 'pan' | 'none'
 
 /** Controls how the initial X viewport is derived when no explicit domain is configured. */
 export interface WaveformXDomainStrategy {
@@ -49,7 +53,7 @@ export interface WaveformXDomainStrategy {
 }
 
 /** Describes the X-axis viewport after a zoom gesture completes. */
-export interface WaveformZoomEndPayload {
+export interface WaveformZoomEndPayload extends WaveformCommandMetadata {
   start: number
   end: number
   yStart?: number
@@ -57,7 +61,7 @@ export interface WaveformZoomEndPayload {
   yRanges?: Record<string, [number, number]>
   trackIndex?: number
   seriesIds?: string[]
-  gesture?: 'wheel' | 'box'
+  gesture?: 'wheel' | 'box' | 'command'
 }
 
 /** Final horizontal viewport after a pan; endpoints are always seconds. */
@@ -69,16 +73,16 @@ export interface WaveformPanEndPayload {
 }
 
 /** Describes the X-axis viewport targeted by a user zoom gesture before rendering settles. */
-export interface WaveformZoomIntentPayload {
+export interface WaveformZoomIntentPayload extends WaveformCommandMetadata {
   start: number
   end: number
-  gesture: 'wheel' | 'box'
+  gesture: 'wheel' | 'box' | 'command'
   trackIndex?: number
   seriesIds?: string[]
 }
 
 /** Identifies the viewport reset by a double-click gesture. */
-export interface WaveformZoomResetPayload {
+export interface WaveformZoomResetPayload extends WaveformCommandMetadata {
   trackIndex?: number
   seriesIds?: string[]
 }
@@ -258,7 +262,19 @@ export type WaveformXAxisLabelFormatter = (
   context: WaveformXAxisLabelFormatterContext,
 ) => string
 
-/** Controls axis baseline visibility while preserving tick marks and axis text. */
+/** Styling for Y-axis series names, separate from numeric tick labels. */
+export interface WaveformYAxisLabelTextStyle {
+  /** Positive font size in pixels. Defaults to 12. */
+  fontSize?: number
+  /** CSS font weight; use 'normal' or 400 to disable bold. Defaults to 600. */
+  fontWeight?: number | string
+  fontFamily?: string
+  fontStyle?: 'normal' | 'italic'
+  /** CSS color. Defaults to the corresponding series color. */
+  color?: string
+}
+
+/** Controls axis baselines, labels, and Y-axis range calculation. */
 export interface WaveformAxesOptions {
   x?: {
     lineVisible?: boolean
@@ -267,12 +283,20 @@ export interface WaveformAxesOptions {
   }
   y?: {
     lineVisible?: boolean
+    /** Styles series names on both left and right Y axes, without changing tick labels. */
+    labelTextStyle?: WaveformYAxisLabelTextStyle
     /** Target total number of equal Y-axis ticks, including endpoints. Defaults to 5. */
     splitNumber?: number
     /** Expands Y-axis domains to equal, human-friendly intervals. Defaults to true. */
     nice?: boolean
-    /** Adds this fraction of the automatic Y span above its maximum. Defaults to 0. */
+    /** Fraction of the automatic Y span added above its maximum. Defaults to 0. */
     upperPaddingRatio?: number
+    /** Fraction of the automatic Y span added below its minimum. Defaults to 0. */
+    lowerPaddingRatio?: number
+    /** False disables upper padding; true defaults an omitted ratio to 0.1. */
+    upperPaddingEnabled?: boolean
+    /** False disables lower padding; true defaults an omitted ratio to 0.1. */
+    lowerPaddingEnabled?: boolean
   }
 }
 

package/src/types/controls.ts

@@ -0,0 +1,80 @@
+import type { WaveformInteractionMode } from './chart'
+
+export type WaveformToolbarItem =
+  'zoom-box' | 'pan' | 'annotate' | 'zoom-in' | 'zoom-out' | 'reset' | 'fit' | 'export'
+export interface WaveformToolbarOptions {
+  visible?: boolean
+  display?: 'hover' | 'always'
+  position?: 'top-right' | 'top-left'
+  items?: WaveformToolbarItem[]
+}
+export interface WaveformControlTarget {
+  trackId?: string
+}
+export type WaveformControlAction = 'zoom-in' | 'zoom-out' | 'set-domain' | 'fit' | 'reset'
+export interface WaveformCommandMetadata {
+  commandId?: string
+  source?: 'toolbar' | 'api'
+  action?: WaveformControlAction
+}
+export type WaveformTargetStatus = 'applied' | 'unchanged' | 'disabled' | 'empty-data'
+export interface WaveformViewportSnapshot {
+  xDomain: [number, number]
+  yDomains: Record<string, [number, number]>
+}
+export interface WaveformTargetResult {
+  trackId: string
+  status: WaveformTargetStatus
+  before?: WaveformViewportSnapshot
+  after?: WaveformViewportSnapshot
+}
+export type WaveformControlResult =
+  | {
+      kind: 'viewport'
+      status: WaveformTargetStatus | 'invalid-target' | 'invalid-domain'
+      targets: WaveformTargetResult[]
+    }
+  | {
+      kind: 'mode'
+      status: 'applied' | 'requested' | 'unchanged' | 'disabled'
+      targets: []
+    }
+export interface WaveformControlState {
+  mode: WaveformInteractionMode
+  independent: boolean
+  targets: Array<{
+    trackId: string
+    label: string
+    viewport: WaveformViewportSnapshot
+    available: Record<WaveformControlAction, boolean>
+  }>
+  available: Record<WaveformToolbarItem, boolean>
+}
+export interface WaveformImageExportOptions {
+  format?: 'png' | 'svg'
+  scale?: number
+  backgroundColor?: string
+}
+export type WaveformImageExportErrorCode =
+  | 'export-invalid-options'
+  | 'export-unavailable'
+  | 'export-busy'
+  | 'export-cancelled'
+  | 'export-render-failed'
+  | 'export-stale'
+  | 'export-timeout'
+export interface WaveformImageExportError extends Error {
+  code: WaveformImageExportErrorCode
+}
+export interface WaveformChartHandle {
+  zoomIn(target?: WaveformControlTarget): WaveformControlResult
+  zoomOut(target?: WaveformControlTarget): WaveformControlResult
+  fitToData(target?: WaveformControlTarget): WaveformControlResult
+  resetViewport(trackIndex?: number): void
+  resetViewport(target: WaveformControlTarget): WaveformControlResult
+  setViewportDomain(domain: [number, number], trackIndex?: number): void
+  setViewportDomain(domain: [number, number], target: WaveformControlTarget): WaveformControlResult
+  setInteractionMode(mode: WaveformInteractionMode): WaveformControlResult
+  getControlState(): WaveformControlState
+  exportImage(options?: WaveformImageExportOptions): Promise<Blob>
+}

package/src/types/index.ts

@@ -35,6 +35,7 @@ export type {
   WaveformXAxisLabelFormatterContext,
   WaveformXAxisLabelFormatter,
   WaveformAxesOptions,
+  WaveformYAxisLabelTextStyle,
   WaveformZeroLineOptions,
 } from './chart'
 
@@ -53,3 +54,20 @@ export type {
   WaveformData,
   NormalizedWaveformSeries,
 } from './data'
+
+export type {
+  WaveformToolbarItem,
+  WaveformToolbarOptions,
+  WaveformControlTarget,
+  WaveformControlAction,
+  WaveformCommandMetadata,
+  WaveformTargetStatus,
+  WaveformViewportSnapshot,
+  WaveformTargetResult,
+  WaveformControlResult,
+  WaveformControlState,
+  WaveformImageExportOptions,
+  WaveformImageExportErrorCode,
+  WaveformImageExportError,
+  WaveformChartHandle,
+} from './controls'

package/src/utils/formatters.ts

@@ -11,6 +11,7 @@ export interface ScientificAxisLabelOptions {
   axisMin?: number
   axisMax?: number
   topTickValue?: number
+  /** Unit prefix for ordinary top ticks; scientific ticks omit it. */
   unit?: string
 }
 
@@ -75,7 +76,7 @@ export function formatScientificAxisLabel(
   const topTickValue = options.topTickValue ?? options.axisMax
   if (value !== topTickValue) return formattedValue
   const unit = options.unit?.trim()
-  const unitLabel = unit ? `(${unit}) ` : ''
+  const unitLabel = exponent === null && unit ? `(${unit}) ` : ''
   const exponentLabel = exponent === null ? '' : `${formatExponent(exponent)} `
   return `${exponentLabel}${unitLabel}${formattedValue}`
 }

package/src/views/WasmSamplingDemo.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed, reactive, ref } from 'vue'
-import { InputNumber, RadioButton, RadioGroup, Select } from 'ant-design-vue'
+import { InputNumber, RadioButton, RadioGroup, Select, Switch } from 'ant-design-vue'
 
 import { WaveformChart } from '../components'
 import type {
@@ -17,6 +17,7 @@ import {
   usesFixedPointCount,
 } from './wasmSamplingDemoSampling'
 
+const toolbarVisible = ref(true)
 const SERIES_COUNT = 10
 const POINTS_PER_SERIES = 100_000
 
@@ -120,6 +121,10 @@ function pointCount(value: number | undefined) {
     </header>
 
     <section class="sampling-demo__controls" aria-label="采样参数">
+      <label
+        ><span>内置工具栏</span
+        ><Switch v-model:checked="toolbarVisible" aria-label="显示内置工具栏" size="small"
+      /></label>
       <label>
         <span>策略</span>
         <Select v-model:value="strategy" :options="strategyOptions" size="small" />
@@ -164,6 +169,8 @@ function pointCount(value: number | undefined) {
     <section class="sampling-demo__workspace">
       <div class="sampling-demo__chart">
         <WaveformChart
+          :toolbar="toolbarVisible"
+          pannable
           :data="data"
           v-model:annotations="annotations"
           :rendering="rendering"