waveform-analysis 0.1.28 → 0.1.30

package/dist/types/components/WaveformChart.vue.d.ts

@@ -48,6 +48,7 @@ declare const __VLS_export: import("vue").DefineComponent<WaveformChartProps, {
     annotationsVisible: boolean;
     grid: import("..").WaveformGridOptions;
     rendering: import("..").WaveformRenderingOptions;
+    plotMargin: import("..").WaveformPlotMargin;
     defaultHiddenSeriesIds: string[];
     cleanView: boolean;
     presentationMode: boolean;

package/dist/types/components/core/constants.d.ts

@@ -8,6 +8,8 @@ export declare const margin: {
     bottom: number;
     left: number;
 };
+/** Distance from the drawing SVG bottom edge to the X-axis title baseline. */
+export declare const X_AXIS_TITLE_BOTTOM_OFFSET = 12;
 /**
  * 图表最小高度（像素）
  */

package/dist/types/components/core/trackLayoutBuilder.d.ts

@@ -1,6 +1,6 @@
 import { type ZoomTransform } from 'd3';
 import { type ResolvedWaveformRenderingOptions } from '../../core/rendering';
-import type { WaveformDisplayMode, WaveformOverlayMode } from '../../types';
+import type { WaveformDisplayMode, WaveformOverlayMode, WaveformXAxisLabelFormatter } from '../../types';
 import { type GridCellGeometry, type NormalizedWaveformGridOptions } from './grid';
 import type { DisplayTrack, TrackLayout } from './types';
 interface SeriesGridCell extends GridCellGeometry {
@@ -19,6 +19,7 @@ export interface BuildTrackLayoutsOptions {
     fixedYDomains?: Record<string, [number, number]>;
     yDomains?: Record<string, [number, number]>;
     timeUnit: 's' | 'ms';
+    xAxisLabelFormatter?: WaveformXAxisLabelFormatter;
     rendering: ResolvedWaveformRenderingOptions;
     hideSecondaryLabels: boolean;
     yAxisLabelX: number;

package/dist/types/components/core/useWaveformChartController.d.ts

@@ -287,7 +287,6 @@ export declare function useWaveformChartController(props: ResolvedWaveformChartP
     resolveSeriesYScale: (track: import("./types").TrackLayout, seriesId: string) => import("d3").ScaleLinear<number, number, never>;
     annotationTrackLayouts: import("../annotation").AnnotationTrackLayout[];
     renderedAnnotations: import("../annotation").RenderedAnnotation[];
-    xAxisTitleY: number;
     editorSeries: import("../annotation").AnnotationSeriesInfo | undefined;
     resolveFrameNumber: (trackIndex: number) => string | number | undefined;
     fixedWidth: number | undefined;
@@ -318,8 +317,13 @@ export declare function useWaveformChartController(props: ResolvedWaveformChartP
     titleMeasureStyle: import("vue").CSSProperties;
     titleLayout: import("./title").RotatedTitleLayout;
     titleAreaHeight: number;
+    resolvedPlotMargin: {
+        top: number;
+        bottom: number;
+    };
     chartTopMargin: number;
     drawingHeight: number;
+    xAxisTitleY: number;
     innerHeight: number;
     titleAreaStyle: import("vue").CSSProperties;
     titleVisualStyle: import("vue").CSSProperties;
@@ -349,6 +353,7 @@ export declare function useWaveformChartController(props: ResolvedWaveformChartP
     interactionMode?: import("..").WaveformInteractionMode | undefined;
     grid: import("./grid").WaveformGridOptions;
     rendering: import("..").WaveformRenderingOptions;
+    plotMargin: import("..").WaveformPlotMargin;
     title?: import("..").WaveformTitleOptions | undefined;
     legend: import("..").WaveformLegendOptions;
     hiddenSeriesIds?: string[] | undefined;

package/dist/types/components/core/useWaveformLayout.d.ts

@@ -54,7 +54,6 @@ export declare function useWaveformLayout(context: LayoutContext): {
     resolveSeriesYScale: (track: TrackLayout, seriesId: string) => import("d3").ScaleLinear<number, number, never>;
     annotationTrackLayouts: ComputedRef<AnnotationTrackLayout[]>;
     renderedAnnotations: ComputedRef<import("../annotation").RenderedAnnotation[]>;
-    xAxisTitleY: ComputedRef<number>;
     editorSeries: ComputedRef<AnnotationSeriesInfo | undefined>;
     resolveFrameNumber: (trackIndex: number) => string | number | undefined;
 };

package/dist/types/components/core/useWaveformPresentation.d.ts

@@ -39,8 +39,13 @@ export declare function useWaveformPresentation(context: PresentationContext): {
     titleMeasureStyle: import("vue").ComputedRef<CSSProperties>;
     titleLayout: import("vue").ComputedRef<import("./title").RotatedTitleLayout>;
     titleAreaHeight: import("vue").ComputedRef<number>;
+    resolvedPlotMargin: import("vue").ComputedRef<{
+        top: number;
+        bottom: number;
+    }>;
     chartTopMargin: import("vue").ComputedRef<number>;
     drawingHeight: import("vue").ComputedRef<number>;
+    xAxisTitleY: import("vue").ComputedRef<number>;
     innerHeight: import("vue").ComputedRef<number>;
     titleAreaStyle: import("vue").ComputedRef<CSSProperties>;
     titleVisualStyle: import("vue").ComputedRef<CSSProperties>;

package/dist/types/components/core/waveformChartTypes.d.ts

@@ -1,4 +1,4 @@
-import type { WaveformAnnotation, WaveformAxesOptions, WaveformData, WaveformDisplayMode, WaveformFrameStyle, WaveformInteractionMode, WaveformLegendOptions, WaveformOverlayMode, WaveformPoint, WaveformRenderingOptions, WaveformTitleOptions, WaveformZeroLineOptions, WaveformZoomEndPayload } from '../data/types';
+import type { WaveformAnnotation, WaveformAxesOptions, WaveformData, WaveformDisplayMode, WaveformFrameStyle, WaveformInteractionMode, WaveformLegendOptions, WaveformOverlayMode, WaveformPlotMargin, WaveformPoint, WaveformRenderingOptions, WaveformTitleOptions, WaveformZeroLineOptions, WaveformZoomEndPayload } from '../data/types';
 import type { WaveformGridOptions } from './grid';
 export interface WaveformChartProps {
     data: WaveformData;
@@ -27,6 +27,7 @@ export interface WaveformChartProps {
     interactionMode?: WaveformInteractionMode;
     grid?: WaveformGridOptions;
     rendering?: WaveformRenderingOptions;
+    plotMargin?: WaveformPlotMargin;
     title?: WaveformTitleOptions;
     legend?: WaveformLegendOptions;
     hiddenSeriesIds?: string[];
@@ -35,7 +36,7 @@ export interface WaveformChartProps {
     presentationMode?: boolean;
     zeroLine?: WaveformZeroLineOptions;
 }
-type DefaultedProp = 'displayMode' | 'overlayMode' | 'yLabel' | 'lineColor' | 'showTooltip' | 'zoomable' | 'pannable' | 'minVisiblePoints' | 'timeUnit' | 'annotations' | 'annotationsVisible' | 'grid' | 'rendering' | 'legend' | 'defaultHiddenSeriesIds' | 'cleanView' | 'presentationMode' | 'zeroLine';
+type DefaultedProp = 'displayMode' | 'overlayMode' | 'yLabel' | 'lineColor' | 'showTooltip' | 'zoomable' | 'pannable' | 'minVisiblePoints' | 'timeUnit' | 'annotations' | 'annotationsVisible' | 'grid' | 'rendering' | 'plotMargin' | 'legend' | 'defaultHiddenSeriesIds' | 'cleanView' | 'presentationMode' | 'zeroLine';
 export type ResolvedWaveformChartProps = Readonly<WaveformChartProps & Required<Pick<WaveformChartProps, DefaultedProp>>>;
 export interface WaveformChartEmit {
     (event: 'point-hover', point: WaveformPoint | null): void;

package/dist/types/components/data/types.d.ts

@@ -2,6 +2,6 @@
  * 数据系统类型定义
  * 重新导出 src/types 中的类型，方便组件内部使用
  */
-export type { WaveformPoint, WaveformDisplayMode, WaveformOverlayMode, WaveformInteractionMode, WaveformZoomEndPayload, WaveformAnnotationStyle, WaveformAnnotation, WaveformRenderingOptions, WaveformTitleTextStyle, WaveformTitleOptions, WaveformLegendPosition, WaveformLegendOrientation, WaveformLegendOptions, WaveformFrameStyle, WaveformAxesOptions, WaveformZeroLineOptions, SingleWaveformData, WaveformLineType, WaveformLineStyle, WaveformPointType, WaveformErrorBarOptions, ResolvedWaveformErrorBarOptions, WaveformSeries, WaveformData, NormalizedWaveformSeries, } from '../../types';
+export type { WaveformPoint, WaveformDisplayMode, WaveformOverlayMode, WaveformInteractionMode, WaveformZoomEndPayload, WaveformAnnotationStyle, WaveformAnnotation, WaveformRenderingOptions, WaveformPlotMargin, WaveformTitleTextStyle, WaveformTitleOptions, WaveformLegendPosition, WaveformLegendOrientation, WaveformLegendOptions, WaveformFrameStyle, WaveformAxesOptions, WaveformZeroLineOptions, SingleWaveformData, WaveformLineType, WaveformLineStyle, WaveformPointType, WaveformErrorBarOptions, ResolvedWaveformErrorBarOptions, WaveformSeries, WaveformData, NormalizedWaveformSeries, } from '../../types';
 export type { WaveformGridOptions, WaveformGridLineOptions, WaveformGridTrackLines, } from '../core/grid';
 export { normalizeWaveformData, normalizeWaveformSeries } from '../../core';

package/dist/types/components/index.d.ts

@@ -1,5 +1,5 @@
 export { default as WaveformChart } from './WaveformChart.vue';
-export type { SingleWaveformData, WaveformData, WaveformDisplayMode, WaveformOverlayMode, WaveformInteractionMode, WaveformZoomEndPayload, WaveformAnnotationStyle, WaveformAnnotation, WaveformRenderingOptions, WaveformTitleTextStyle, WaveformTitleOptions, WaveformLegendPosition, WaveformLegendOrientation, WaveformLegendOptions, WaveformFrameStyle, WaveformAxesOptions, WaveformZeroLineOptions, WaveformPoint, WaveformSeries, WaveformLineType, WaveformLineStyle, WaveformPointType, WaveformErrorBarOptions, WaveformGridOptions, WaveformGridLineOptions, WaveformGridTrackLines, } from './data/types';
+export type { SingleWaveformData, WaveformData, WaveformDisplayMode, WaveformOverlayMode, WaveformInteractionMode, WaveformZoomEndPayload, WaveformAnnotationStyle, WaveformAnnotation, WaveformRenderingOptions, WaveformPlotMargin, WaveformTitleTextStyle, WaveformTitleOptions, WaveformLegendPosition, WaveformLegendOrientation, WaveformLegendOptions, WaveformFrameStyle, WaveformAxesOptions, WaveformZeroLineOptions, WaveformPoint, WaveformSeries, WaveformLineType, WaveformLineStyle, WaveformPointType, WaveformErrorBarOptions, WaveformGridOptions, WaveformGridLineOptions, WaveformGridTrackLines, } from './data/types';
 export type { WaveformGridOptions as WaveformGridConfig } from './core/grid';
 export { WaveformTooltip } from './interaction';
 export { WaveformTrack } from './rendering';

package/dist/types/components/waveform.d.ts

@@ -2,5 +2,5 @@
  * 向后兼容的导出文件
  * 保留原有导入路径，内部从新的模块结构导出
  */
-export type { WaveformPoint, WaveformDisplayMode, WaveformOverlayMode, WaveformInteractionMode, WaveformAnnotationStyle, WaveformAnnotation, WaveformRenderingOptions, WaveformTitleTextStyle, WaveformTitleOptions, WaveformFrameStyle, SingleWaveformData, WaveformSeries, WaveformLineStyle, WaveformData, NormalizedWaveformSeries, } from '../types';
+export type { WaveformPoint, WaveformDisplayMode, WaveformOverlayMode, WaveformInteractionMode, WaveformAnnotationStyle, WaveformAnnotation, WaveformRenderingOptions, WaveformPlotMargin, WaveformTitleTextStyle, WaveformTitleOptions, WaveformFrameStyle, SingleWaveformData, WaveformSeries, WaveformLineStyle, WaveformData, NormalizedWaveformSeries, } from '../types';
 export { normalizeWaveformData, normalizeWaveformSeries } from '../core';

package/dist/types/demo/types.d.ts

@@ -1,4 +1,5 @@
-import type { WaveformAnnotation, WaveformAxesOptions, WaveformData, WaveformDisplayMode, WaveformFrameStyle, WaveformGridTrackLines, WaveformInteractionMode, WaveformLegendOrientation, WaveformLegendPosition, WaveformLineStyle, WaveformOverlayMode, WaveformTitleOptions, WaveformZeroLineOptions, WaveformZoomEndPayload } from '../components';
+import type { WaveformAnnotation, WaveformAxesOptions, WaveformData, WaveformDisplayMode, WaveformFrameStyle, WaveformGridTrackLines, WaveformInteractionMode, WaveformLegendOrientation, WaveformLegendPosition, WaveformLineStyle, WaveformOverlayMode, WaveformPlotMargin, WaveformTitleOptions, WaveformZeroLineOptions, WaveformZoomEndPayload } from '../components';
+import type { DemoXAxisLabelFormat, DemoXAxisLabelTimeZone } from './useDemoXAxisLabelControls';
 interface SelectOption<T> {
     label: string;
     value: T;
@@ -8,6 +9,8 @@ export interface DemoControlPanelModel {
     displayMode: WaveformDisplayMode;
     overlayMode: WaveformOverlayMode;
     showTooltip: boolean;
+    plotMarginTop: number;
+    plotMarginBottom: number;
     cleanView: boolean;
     presentationMode: boolean;
     selectedSeriesId: string;
@@ -27,6 +30,14 @@ export interface DemoControlPanelModel {
     verticalGridColor: string;
     xAxisLineVisible: boolean;
     yAxisLineVisible: boolean;
+    xAxisLabelFormatterEnabled: boolean;
+    xAxisLabelFormat: DemoXAxisLabelFormat;
+    xAxisLabelFormatOptions: Array<SelectOption<DemoXAxisLabelFormat>>;
+    xAxisLabelMultiplier: number;
+    xAxisLabelFractionDigits: number;
+    xAxisLabelTimeZone: DemoXAxisLabelTimeZone;
+    xAxisLabelTimeZoneOptions: Array<SelectOption<DemoXAxisLabelTimeZone>>;
+    xAxisLabelShowMilliseconds: boolean;
     frameBorderColor: string;
     frameBackgroundColor: string;
     frameBorderWidth: number;
@@ -72,6 +83,7 @@ export interface DemoChartModel {
     cleanView: boolean;
     presentationMode: boolean;
     showTooltip: boolean;
+    plotMargin: WaveformPlotMargin;
     zeroLine: WaveformZeroLineOptions;
     frameWatermarkVisible: boolean;
     annotations: WaveformAnnotation[];

package/dist/types/demo/useDemoXAxisLabelControls.d.ts

@@ -0,0 +1,32 @@
+import type { WaveformXAxisLabelFormatter } from '../types';
+export type DemoXAxisLabelFormat = 'number' | 'datetime';
+export type DemoXAxisLabelTimeZone = 'local' | 'Asia/Shanghai' | 'UTC';
+export declare function formatDemoTimestamp(value: number, timeZone: DemoXAxisLabelTimeZone, showMilliseconds: boolean): string;
+export declare function useDemoXAxisLabelControls(): {
+    controlModel: {
+        xAxisLabelFormatterEnabled: import("vue").Ref<boolean, boolean>;
+        xAxisLabelFormat: import("vue").Ref<DemoXAxisLabelFormat, DemoXAxisLabelFormat>;
+        xAxisLabelFormatOptions: ({
+            label: string;
+            value: "number";
+        } | {
+            label: string;
+            value: "datetime";
+        })[];
+        xAxisLabelMultiplier: import("vue").Ref<number, number>;
+        xAxisLabelFractionDigits: import("vue").Ref<number, number>;
+        xAxisLabelTimeZone: import("vue").Ref<DemoXAxisLabelTimeZone, DemoXAxisLabelTimeZone>;
+        xAxisLabelTimeZoneOptions: ({
+            label: string;
+            value: "Asia/Shanghai";
+        } | {
+            label: string;
+            value: "local";
+        } | {
+            label: string;
+            value: "UTC";
+        })[];
+        xAxisLabelShowMilliseconds: import("vue").Ref<boolean, boolean>;
+    };
+    xAxisLabelFormatter: import("vue").ComputedRef<WaveformXAxisLabelFormatter | undefined>;
+};

package/dist/types/index.d.ts

@@ -3,7 +3,7 @@
  * @packageDocumentation
  */
 export { default as WaveformChart } from './components/WaveformChart.vue';
-export type { WaveformPoint, WaveformDisplayMode, WaveformOverlayMode, WaveformInteractionMode, WaveformZoomEndPayload, WaveformAnnotationStyle, WaveformAnnotation, WaveformRenderingOptions, WaveformTitleTextStyle, WaveformTitleOptions, WaveformLegendPosition, WaveformLegendOrientation, WaveformLegendOptions, WaveformFrameStyle, WaveformAxesOptions, WaveformZeroLineOptions, SingleWaveformData, WaveformLineType, WaveformLineStyle, WaveformPointType, WaveformErrorBarOptions, ResolvedWaveformErrorBarOptions, WaveformSeries, WaveformData, NormalizedWaveformSeries, } from './types';
+export type { WaveformPoint, WaveformDisplayMode, WaveformOverlayMode, WaveformInteractionMode, WaveformZoomEndPayload, WaveformAnnotationStyle, WaveformAnnotation, WaveformRenderingOptions, WaveformPlotMargin, WaveformTitleTextStyle, WaveformTitleOptions, WaveformLegendPosition, WaveformLegendOrientation, WaveformLegendOptions, WaveformFrameStyle, WaveformXAxisLabelKind, WaveformXAxisLabelFormatterContext, WaveformXAxisLabelFormatter, WaveformAxesOptions, WaveformZeroLineOptions, SingleWaveformData, WaveformLineType, WaveformLineStyle, WaveformPointType, WaveformErrorBarOptions, ResolvedWaveformErrorBarOptions, WaveformSeries, WaveformData, NormalizedWaveformSeries, } from './types';
 export type { WaveformGridOptions, WaveformGridLineOptions, WaveformGridTrackLines, } from './components/core/grid';
 export { normalizeWaveformData, normalizeWaveformSeries } from './core';
 export { paddedDomain, buildMinorTicks, displayTime, formatEndpointTime, formatAxisTime, formatTooltipTime, resolveTrackGeometry, clamp, type TimeUnit, type TrackGeometry, } from './utils';

package/dist/types/types/chart.d.ts

@@ -66,6 +66,13 @@ export interface WaveformRenderingOptions {
     /** Minimum horizontal CSS-pixel spacing between rendered error bars. Use 0 to disable. */
     errorBarMinSpacing?: number;
 }
+/** Pixel margins reserved above and below the waveform plotting area. */
+export interface WaveformPlotMargin {
+    /** Space between the top of the drawing SVG and the plotting area. Defaults to 18. */
+    top?: number;
+    /** Space between the plotting area and the bottom of the drawing SVG. Defaults to 52. */
+    bottom?: number;
+}
 /** Text styling for the chart-level title. */
 export interface WaveformTitleTextStyle {
     color?: string;
@@ -106,10 +113,25 @@ export interface WaveformFrameStyle {
     borderStyle?: 'solid' | 'dashed' | 'dotted';
     backgroundColor?: string;
 }
+export type WaveformXAxisLabelKind = 'tick' | 'start' | 'end';
+/** Context passed to custom X-axis label formatters. */
+export interface WaveformXAxisLabelFormatterContext {
+    kind: WaveformXAxisLabelKind;
+    /** X coordinate in the source data, before time-unit conversion. */
+    rawValue: number;
+    timeUnit: 's' | 'ms';
+    /** Current visible X domain in source coordinates. */
+    domain: [number, number];
+    /** Current visible X domain converted to the selected display unit. */
+    displayDomain: [number, number];
+}
+export type WaveformXAxisLabelFormatter = (value: number, context: WaveformXAxisLabelFormatterContext) => string;
 /** Controls axis baseline visibility while preserving tick marks and axis text. */
 export interface WaveformAxesOptions {
     x?: {
         lineVisible?: boolean;
+        /** Formats display-unit X values for ticks and visible-range endpoints. */
+        labelFormatter?: WaveformXAxisLabelFormatter;
     };
     y?: {
         lineVisible?: boolean;

package/dist/types/types/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * 类型定义统一导出
  */
-export type { WaveformPoint, WaveformDisplayMode, WaveformOverlayMode, WaveformInteractionMode, WaveformZoomEndPayload, WaveformAnnotationStyle, WaveformAnnotation, WaveformRenderingOptions, WaveformTitleTextStyle, WaveformTitleOptions, WaveformLegendPosition, WaveformLegendOrientation, WaveformLegendOptions, WaveformFrameStyle, WaveformAxesOptions, WaveformZeroLineOptions, } from './chart';
+export type { WaveformPoint, WaveformDisplayMode, WaveformOverlayMode, WaveformInteractionMode, WaveformZoomEndPayload, WaveformAnnotationStyle, WaveformAnnotation, WaveformRenderingOptions, WaveformPlotMargin, WaveformTitleTextStyle, WaveformTitleOptions, WaveformLegendPosition, WaveformLegendOrientation, WaveformLegendOptions, WaveformFrameStyle, WaveformXAxisLabelKind, WaveformXAxisLabelFormatterContext, WaveformXAxisLabelFormatter, WaveformAxesOptions, WaveformZeroLineOptions, } from './chart';
 export type { SingleWaveformData, WaveformLineType, WaveformLineStyle, WaveformPointType, WaveformErrorBarOptions, ResolvedWaveformErrorBarOptions, WaveformSeries, WaveformData, NormalizedWaveformSeries, } from './data';

package/dist/types/utils/formatters.d.ts

@@ -1,3 +1,4 @@
+import type { WaveformXAxisLabelFormatter, WaveformXAxisLabelKind } from '../types';
 /**
  * 时间单位类型
  */
@@ -33,6 +34,8 @@ export declare function formatPlainNumber(value: number): string;
  * @returns 转换后的显示值
  */
 export declare function displayTime(value: number, timeUnit: TimeUnit): number;
+/** Format an X-axis value without changing its source coordinate. */
+export declare function formatXAxisLabel(rawValue: number, domain: [number, number], timeUnit: TimeUnit, kind: WaveformXAxisLabelKind, formatter?: WaveformXAxisLabelFormatter): string;
 /**
  * 计算端点标签的小数位数
  * @param domain 数据域 [最小值, 最大值]
@@ -41,7 +44,7 @@ export declare function displayTime(value: number, timeUnit: TimeUnit): number;
  */
 export declare function endpointFractionDigits(domain: [number, number], timeUnit: TimeUnit): number;
 /**
- * 将 X 轴端点时间格式化为当前显示单位下的普通整数
+ * 将 X 轴端点时间格式化为当前显示单位下的普通十进制文本
  * @param value 时间值（秒）
  * @param _domain 数据域（为保持现有调用签名而保留）
  * @param timeUnit 时间单位
@@ -49,7 +52,7 @@ export declare function endpointFractionDigits(domain: [number, number], timeUni
  */
 export declare function formatEndpointTime(value: number, _domain: [number, number], timeUnit: TimeUnit): string;
 /**
- * 将 X 轴时间刻度格式化为当前显示单位下的普通整数
+ * 将 X 轴时间刻度格式化为当前显示单位下的普通十进制文本
  * @param value 时间值（秒）
  * @param timeUnit 时间单位
  * @param _domain 数据域（为保持现有调用签名而保留）

package/dist/types/utils/index.d.ts

@@ -2,6 +2,6 @@
  * 工具函数模块统一导出
  */
 export { paddedDomain, buildMinorTicks } from './domain';
-export { displayTime, endpointFractionDigits, formatEndpointTime, formatAxisTime, formatTooltipTime, formatAnnotationTime, formatPlainNumber, formatScientificAxisLabel, formatScientificAxisExponent, formatScientificYAxisLabel, formatTooltipNumber, resolveScientificAxisExponent, shouldUseScientificAxisLabel, shouldUseScientificYAxisLabel, type ScientificAxisLabelOptions, type ScientificYAxisLabelOptions, type TimeUnit, } from './formatters';
+export { displayTime, endpointFractionDigits, formatEndpointTime, formatAxisTime, formatXAxisLabel, formatTooltipTime, formatAnnotationTime, formatPlainNumber, formatScientificAxisLabel, formatScientificAxisExponent, formatScientificYAxisLabel, formatTooltipNumber, resolveScientificAxisExponent, shouldUseScientificAxisLabel, shouldUseScientificYAxisLabel, type ScientificAxisLabelOptions, type ScientificYAxisLabelOptions, type TimeUnit, } from './formatters';
 export { resolveTrackGeometry, clamp, type TrackGeometry } from './geometry';
 export { downsampleLTTB, downsampleMinMax, adaptiveSampling, calculateSamplingThreshold, } from './sampling';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waveform-analysis",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/types/index.d.ts",

package/src/App.vue

@@ -14,6 +14,7 @@ import {
   type WaveformLegendOrientation,
   type WaveformLegendPosition,
   type WaveformOverlayMode,
+  type WaveformPlotMargin,
   type WaveformTitleOptions,
   type WaveformZoomEndPayload,
   type WaveformZeroLineOptions,
@@ -23,6 +24,7 @@ import { createSimulatedWaveformData } from './data/simulatedWaveforms'
 import DemoChartHost from './demo/DemoChartHost.vue'
 import DemoControlPanel from './demo/DemoControlPanel.vue'
 import type { DemoChartModel, DemoControlPanelModel } from './demo/types'
+import { useDemoXAxisLabelControls } from './demo/useDemoXAxisLabelControls'
 
 const fullChartData = createSimulatedWaveformData()
 const displayMode = ref<WaveformDisplayMode>('independent')
@@ -40,11 +42,14 @@ const verticalGridVisible = ref(true)
 const verticalGridColor = ref('#dfe5ef')
 const xAxisLineVisible = ref(false)
 const yAxisLineVisible = ref(false)
+const { controlModel: xAxisLabelControlModel, xAxisLabelFormatter } = useDemoXAxisLabelControls()
 const annotations = ref<WaveformAnnotation[]>([])
 const annotationsVisible = ref(true)
 const cleanView = ref(false)
 const presentationMode = ref(false)
 const showTooltip = ref(true)
+const plotMarginTop = ref(18)
+const plotMarginBottom = ref(52)
 const zeroLineVisible = ref(false)
 const zeroLineColor = ref('#98a2b3')
 const zeroLineWidth = ref(1)
@@ -112,7 +117,10 @@ const frameStyle = computed<WaveformFrameStyle>(() => ({
   backgroundColor: frameBackgroundColor.value,
 }))
 const axes = computed<WaveformAxesOptions>(() => ({
-  x: { lineVisible: xAxisLineVisible.value },
+  x: {
+    lineVisible: xAxisLineVisible.value,
+    ...(xAxisLabelFormatter.value ? { labelFormatter: xAxisLabelFormatter.value } : {}),
+  },
   y: { lineVisible: yAxisLineVisible.value },
 }))
 const zeroLine = computed<WaveformZeroLineOptions>(() => ({
@@ -121,6 +129,10 @@ const zeroLine = computed<WaveformZeroLineOptions>(() => ({
   width: zeroLineWidth.value,
   dash: zeroLineDash.value,
 }))
+const plotMargin = computed<WaveformPlotMargin>(() => ({
+  top: plotMarginTop.value,
+  bottom: plotMarginBottom.value,
+}))
 
 const initialXValues = normalizeWaveformSeries(fullChartData).flatMap((series) =>
   series.points.map((point) => point.x),
@@ -289,6 +301,8 @@ const controlPanelModel = reactive({
   displayMode,
   overlayMode,
   showTooltip,
+  plotMarginTop,
+  plotMarginBottom,
   cleanView,
   presentationMode,
   selectedSeriesId,
@@ -308,6 +322,7 @@ const controlPanelModel = reactive({
   verticalGridColor,
   xAxisLineVisible,
   yAxisLineVisible,
+  ...xAxisLabelControlModel,
   frameBorderColor,
   frameBackgroundColor,
   frameBorderWidth,
@@ -354,6 +369,7 @@ const chartModel = reactive({
   cleanView,
   presentationMode,
   showTooltip,
+  plotMargin,
   zeroLine,
   frameWatermarkVisible,
   annotations,

package/src/components/WaveformChart.vue

@@ -23,6 +23,7 @@ const props = withDefaults(defineProps<WaveformChartProps>(), {
   interactionMode: undefined,
   grid: () => ({ rowCount: 2, columnCount: 1, showPagination: true }),
   rendering: () => ({}),
+  plotMargin: () => ({}),
   legend: () => ({ position: 'top-right', orientation: 'auto' }),
   defaultHiddenSeriesIds: () => [],
   cleanView: false,

package/src/components/WaveformChartView.vue

@@ -19,6 +19,7 @@ const {
   overlayMode,
   resolvedChartLeftMargin,
   titleAreaHeight,
+  resolvedPlotMargin,
   pointerInsideChart,
   handleNativeContextMenu,
   titleAreaReserved,
@@ -118,6 +119,8 @@ const {
     :data-presentation-mode="isPresentationMode"
     :data-overlay-mode="overlayMode"
     :data-chart-left-margin="resolvedChartLeftMargin"
+    :data-plot-margin-top="resolvedPlotMargin.top"
+    :data-plot-margin-bottom="resolvedPlotMargin.bottom"
     :data-title-area-height="titleAreaHeight"
     @pointerenter="pointerInsideChart = true"
     @pointerleave="pointerInsideChart = false"
@@ -287,18 +290,18 @@ const {
             />
           </g>
         </g>
-
-        <text
-          v-if="resolvedXLabel && !isCleanView"
-          class="waveform-chart__label waveform-chart__x-label"
-          :x="innerWidth / 2"
-          :y="xAxisTitleY"
-          text-anchor="middle"
-        >
-          {{ resolvedXLabel }}
-        </text>
       </g>
 
+      <text
+        v-if="resolvedXLabel && !isCleanView"
+        class="waveform-chart__label waveform-chart__x-label"
+        :x="resolvedChartLeftMargin + innerWidth / 2"
+        :y="xAxisTitleY"
+        text-anchor="middle"
+      >
+        {{ resolvedXLabel }}
+      </text>
+
       <text
         v-if="hasChartArea && !hasWaveformData"
         class="waveform-chart__empty"

package/src/components/core/constants.ts

@@ -7,6 +7,9 @@
 /** 图表边距 */
 export const margin = { top: 18, right: 24, bottom: 52, left: 64 }
 
+/** Distance from the drawing SVG bottom edge to the X-axis title baseline. */
+export const X_AXIS_TITLE_BOTTOM_OFFSET = 12
+
 /**
  * 图表最小高度（像素）
  */

package/src/components/core/trackLayoutBuilder.ts

@@ -12,8 +12,13 @@ import {
   selectSeriesRenderPoints,
   type ResolvedWaveformRenderingOptions,
 } from '../../core/rendering'
-import type { WaveformDisplayMode, WaveformOverlayMode, WaveformPoint } from '../../types'
-import { buildMinorTicks, formatEndpointTime } from '../../utils'
+import type {
+  WaveformDisplayMode,
+  WaveformOverlayMode,
+  WaveformPoint,
+  WaveformXAxisLabelFormatter,
+} from '../../types'
+import { buildMinorTicks, formatXAxisLabel } from '../../utils'
 import {
   getBottomRowCellIndexes,
   type GridCellGeometry,
@@ -45,6 +50,7 @@ export interface BuildTrackLayoutsOptions {
   fixedYDomains?: Record<string, [number, number]>
   yDomains?: Record<string, [number, number]>
   timeUnit: 's' | 'ms'
+  xAxisLabelFormatter?: WaveformXAxisLabelFormatter
   rendering: ResolvedWaveformRenderingOptions
   hideSecondaryLabels: boolean
   yAxisLabelX: number
@@ -147,8 +153,20 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
     const yAxisTickValues = yAxes[0]?.tickValues ?? []
     const domain = xScale.domain() as [number, number]
     const endpointLabels = {
-      start: formatEndpointTime(domain[0], domain, options.timeUnit),
-      end: formatEndpointTime(domain[1], domain, options.timeUnit),
+      start: formatXAxisLabel(
+        domain[0],
+        domain,
+        options.timeUnit,
+        'start',
+        options.xAxisLabelFormatter,
+      ),
+      end: formatXAxisLabel(
+        domain[1],
+        domain,
+        options.timeUnit,
+        'end',
+        options.xAxisLabelFormatter,
+      ),
     }
     const leftClearance = endpointLabels.start.length * 7 + 10
     const rightClearance = endpointLabels.end.length * 7 + 10

package/src/components/core/useWaveformLayout.ts

@@ -24,7 +24,6 @@ import {
   normalizeGridOptions,
   paginateSeries,
   resolveGridCellGeometry,
-  X_AXIS_BAND,
 } from './grid'
 import {
   buildTrackLayouts,
@@ -285,6 +284,7 @@ export function useWaveformLayout(context: LayoutContext) {
             )
           : sharedYDomains.value,
       timeUnit: props.timeUnit,
+      xAxisLabelFormatter: props.axes?.x?.labelFormatter,
       rendering: renderingOptions.value,
       hideSecondaryLabels: isCleanView.value || yAxisLayout.value.hideSecondaryLabels,
       yAxisLabelX: yAxisMetrics.value.labelCenterX,
@@ -315,7 +315,6 @@ export function useWaveformLayout(context: LayoutContext) {
         )
       : [],
   )
-  const xAxisTitleY = computed(() => innerHeight.value + X_AXIS_BAND + 10)
   const editorSeries = computed<AnnotationSeriesInfo | undefined>(() => {
     const seriesId = annotationInteraction.editorDraft.value?.annotation.seriesId
     const series = chartSeries.value.find((item) => item.id === seriesId)
@@ -359,7 +358,6 @@ export function useWaveformLayout(context: LayoutContext) {
     resolveSeriesYScale,
     annotationTrackLayouts,
     renderedAnnotations,
-    xAxisTitleY,
     editorSeries,
     resolveFrameNumber,
   }

package/src/components/core/useWaveformPresentation.ts

@@ -7,6 +7,7 @@ import {
   TITLE_CHAR_WIDTH_RATIO,
   TITLE_DEFAULT_FONT_SIZE,
   TITLE_LINE_HEIGHT,
+  X_AXIS_TITLE_BOTTOM_OFFSET,
   ZERO_LINE_DEFAULTS,
 } from './constants'
 import { calculateRotatedTitleLayout, TITLE_AREA_HORIZONTAL_PADDING } from './title'
@@ -144,11 +145,23 @@ export function useWaveformPresentation(context: PresentationContext) {
   const titleAreaHeight = computed(() =>
     titleAreaReserved.value ? titleLayout.value.areaHeight : 0,
   )
-  const chartTopMargin = computed(() => margin.top)
+  const resolvePlotMargin = (value: number | undefined, fallback: number) =>
+    typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback
+  const resolvedPlotMargin = computed(() => ({
+    top: resolvePlotMargin(props.plotMargin.top, margin.top),
+    bottom: resolvePlotMargin(props.plotMargin.bottom, margin.bottom),
+  }))
+  const chartTopMargin = computed(() => resolvedPlotMargin.value.top)
   const drawingHeight = computed(() =>
     Math.max(0, chartHeight.value - titleAreaHeight.value - paginationBandHeight.value),
   )
-  const innerHeight = computed(() => Math.max(0, drawingHeight.value - margin.top - margin.bottom))
+  const xAxisTitleY = computed(() => Math.max(0, drawingHeight.value - X_AXIS_TITLE_BOTTOM_OFFSET))
+  const innerHeight = computed(() =>
+    Math.max(
+      0,
+      drawingHeight.value - resolvedPlotMargin.value.top - resolvedPlotMargin.value.bottom,
+    ),
+  )
   const titleAreaStyle = computed<CSSProperties>(() => ({
     height: `${titleAreaHeight.value}px`,
     justifyContent:
@@ -193,8 +206,10 @@ export function useWaveformPresentation(context: PresentationContext) {
     titleMeasureStyle,
     titleLayout,
     titleAreaHeight,
+    resolvedPlotMargin,
     chartTopMargin,
     drawingHeight,
+    xAxisTitleY,
     innerHeight,
     titleAreaStyle,
     titleVisualStyle,

package/src/components/core/waveformChartTypes.ts

@@ -7,6 +7,7 @@ import type {
   WaveformInteractionMode,
   WaveformLegendOptions,
   WaveformOverlayMode,
+  WaveformPlotMargin,
   WaveformPoint,
   WaveformRenderingOptions,
   WaveformTitleOptions,
@@ -42,6 +43,7 @@ export interface WaveformChartProps {
   interactionMode?: WaveformInteractionMode
   grid?: WaveformGridOptions
   rendering?: WaveformRenderingOptions
+  plotMargin?: WaveformPlotMargin
   title?: WaveformTitleOptions
   legend?: WaveformLegendOptions
   hiddenSeriesIds?: string[]
@@ -65,6 +67,7 @@ type DefaultedProp =
   | 'annotationsVisible'
   | 'grid'
   | 'rendering'
+  | 'plotMargin'
   | 'legend'
   | 'defaultHiddenSeriesIds'
   | 'cleanView'

package/src/components/data/types.ts

@@ -13,6 +13,7 @@ export type {
   WaveformAnnotationStyle,
   WaveformAnnotation,
   WaveformRenderingOptions,
+  WaveformPlotMargin,
   WaveformTitleTextStyle,
   WaveformTitleOptions,
   WaveformLegendPosition,

package/src/components/index.ts

@@ -11,6 +11,7 @@ export type {
   WaveformAnnotationStyle,
   WaveformAnnotation,
   WaveformRenderingOptions,
+  WaveformPlotMargin,
   WaveformTitleTextStyle,
   WaveformTitleOptions,
   WaveformLegendPosition,