@gridui/audio-waveform 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,90 @@
1
- # Temporary Holding Version
1
+ # @gridui/audio-waveform
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ `AudioWaveform` displays signed audio extrema over time, as bars or a continuous
4
+ envelope. Import `AudioWaveform`, `AudioWaveformProps`, and `AudioWaveformData`
5
+ from the package root. Load `@gridui/theme/styles.css`, then
6
+ `@gridui/audio-waveform/styles.css`.
7
+
8
+ ```tsx
9
+ import { AudioWaveform } from "@gridui/audio-waveform";
10
+
11
+ <div style={{ height: 144 }}>
12
+ <AudioWaveform
13
+ label="Recording amplitude"
14
+ data={{
15
+ startTime: 0,
16
+ bucketDuration: 0.02,
17
+ min: [-0.2, -0.8, 0, -0.4],
18
+ max: [0.3, 0.7, 0, 0.6],
19
+ }}
20
+ />
21
+ </div>;
22
+ ```
23
+
24
+ ## Content and Grid ownership
25
+
26
+ The root SVG fills its parent's content box with no padding, margin, border,
27
+ background, axes, heading, controls or structural lines. Give the parent a
28
+ definite height. Grid/GridItem own region size, padding, outer edges and seams;
29
+ labels and controls are separate content in other GridItems. No embedded mode
30
+ or layout prop is necessary. Native SVG props, `className`, inline styles and
31
+ an SVG ref are forwarded.
32
+
33
+ Marks inherit the local `--gridui-accent-background`; the optional playhead uses
34
+ `--gridui-foreground`. A `color` override changes the waveform ink. Neutral, brand
35
+ and custom palettes work through Theme inheritance. Supply the required accessible
36
+ `label`; set `aria-hidden` if an adjacent alternative already conveys the content.
37
+ The SVG is a passive image, with no focus stop or per-frame live announcement.
38
+
39
+ ## Data contract
40
+
41
+ `data` contains:
42
+
43
+ - `startTime`: finite timestamp in seconds on the application's audio clock.
44
+ - `bucketDuration`: positive finite seconds represented by each bucket.
45
+ - `min`, `max`: equal-length `ArrayLike<number>` buffers, such as `Float32Array`.
46
+ Each pair records signed PCM extrema for one consecutive time interval.
47
+
48
+ Bucket `i` occupies `[startTime + i * bucketDuration, startTime + (i + 1) * bucketDuration)`.
49
+ Preserve absolute time when trimming a rolling buffer by advancing `startTime`.
50
+ For symmetric intensity bars, supply `min[i] = -peak[i]` and `max[i] = peak[i]`.
51
+ RMS intensity can be supplied the same way but must be described as RMS by the
52
+ application. The component does not infer units or convert raw PCM into buckets.
53
+
54
+ Clamping keeps finite values within -1…1. Nonfinite or reversed min/max pairs are
55
+ missing data; zero remains genuine silence. Visible display buckets retain the
56
+ minimum and maximum source values, so short transients survive aggregation.
57
+ An entirely missing display bucket breaks the envelope. Missing intervals smaller
58
+ than a display bucket cannot be resolved; use more buckets to show finer gaps.
59
+ Time outside the recorded range stays empty instead of stretching the recording.
60
+ Empty arrays render no waveform. Invalid lengths, clock metadata or options throw
61
+ `RangeError`.
62
+
63
+ The application owns recording, decoding, PCM aggregation, buffer retention and
64
+ updates. Render a new snapshot or rerender after reusing a typed buffer. A visual
65
+ render loop is not a recording clock; derive bucket times from actual audio
66
+ samples. The component has no audio devices, timers or animation lifecycle.
67
+
68
+ ## Presentation and time windows
69
+
70
+ | Prop | Default | Meaning |
71
+ | --- | --- | --- |
72
+ | `variant` | `bars` | `bars` or a filled signed `envelope` |
73
+ | `barCount` | `128` | Maximum display buckets, integer 1–512 |
74
+ | `barGap` | `0.3` | Interior bar gap fraction, 0 ≤ value < 1 |
75
+ | `viewStart` / `viewEnd` | Full recording | Visible time interval in seconds |
76
+ | `playhead` | Omitted | Controlled position in seconds on the same clock |
77
+
78
+ For live input, pass `viewStart={now - 8}` and `viewEnd={now}` and advance `now`
79
+ from the audio clock. For full-file playback, omit the window and pass the
80
+ current playback time. Neither option changes the data or controls playback.
81
+ A finite playhead dims future content, fills played content and draws a cursor
82
+ only while it lies inside the window. A nonfinite playhead is ignored.
83
+
84
+ The SVG scales to the allocated region without measuring it, preserving time
85
+ positions across resizes. Time remains left to right in RTL layouts. Live sources
86
+ own their update rate and reduced-motion presentation.
87
+
88
+ See the [Grid contract](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/docs/README.md),
89
+ [component reference](docs/reference/README.md), and
90
+ [release history](https://github.com/sudo-ui/GridUI-React-Monorepo/tree/main/packages-data/audio-waveform/.changeset/history).
@@ -0,0 +1,17 @@
1
+ import { type ComponentPropsWithRef } from "react";
2
+ import type { AudioWaveformData } from "./types";
3
+ export type AudioWaveformProps = Omit<ComponentPropsWithRef<"svg">, "children" | "viewBox" | "preserveAspectRatio"> & {
4
+ /** Accessible description of the audio source; not a visible heading. */
5
+ readonly label: string;
6
+ readonly data: AudioWaveformData;
7
+ readonly variant?: "bars" | "envelope";
8
+ /** Maximum display buckets. Peak aggregation preserves short transients. */
9
+ readonly barCount?: number;
10
+ readonly barGap?: number;
11
+ /** Seconds on the same clock as data.startTime. */
12
+ readonly viewStart?: number;
13
+ readonly viewEnd?: number;
14
+ /** Controlled playhead in seconds. Omit for unplayed/live input. */
15
+ readonly playhead?: number;
16
+ };
17
+ export declare function AudioWaveform({ label, data, variant, barCount, barGap, viewStart, viewEnd, playhead, className, ...rest }: AudioWaveformProps): import("react").JSX.Element;
@@ -0,0 +1,4 @@
1
+ import type { AudioWaveformData, WaveformModel } from "./types";
2
+ /** Keep time gaps and signed extrema instead of stretching available data over a window. */
3
+ export declare function waveformModel(data: AudioWaveformData, barCount: number, viewStart?: number, viewEnd?: number): WaveformModel;
4
+ export declare function waveformPath(model: WaveformModel, variant: "bars" | "envelope", barGap: number): string;
@@ -0,0 +1,18 @@
1
+ /** Uniform time buckets of signed PCM extrema; arrays have equal lengths. */
2
+ export type AudioWaveformData = {
3
+ readonly startTime: number;
4
+ readonly bucketDuration: number;
5
+ readonly min: ArrayLike<number>;
6
+ readonly max: ArrayLike<number>;
7
+ };
8
+ export type WaveformBucket = {
9
+ readonly start: number;
10
+ readonly end: number;
11
+ readonly min: number;
12
+ readonly max: number;
13
+ };
14
+ export type WaveformModel = {
15
+ readonly buckets: readonly (WaveformBucket | null)[];
16
+ readonly start: number;
17
+ readonly end: number;
18
+ };
@@ -0,0 +1,2 @@
1
+ export { AudioWaveform, type AudioWaveformProps } from "./audio-waveform/audio-waveform";
2
+ export type { AudioWaveformData } from "./audio-waveform/types";
package/dist/index.js ADDED
@@ -0,0 +1,154 @@
1
+ // src/audio-waveform/audio-waveform.tsx
2
+ import { cn } from "@gridui/style-utils";
3
+ import { useId } from "react";
4
+
5
+ // src/audio-waveform/model.ts
6
+ function waveformModel(data, barCount, viewStart, viewEnd) {
7
+ if (!Number.isFinite(data.startTime) || !Number.isFinite(data.bucketDuration) || data.bucketDuration <= 0 || data.min.length !== data.max.length || !Number.isSafeInteger(data.min.length) || data.min.length < 0 || !Number.isInteger(barCount) || barCount < 1 || barCount > 512) {
8
+ throw new RangeError("AudioWaveform requires a finite startTime, positive bucketDuration, equal extrema lengths, and 1\u2013512 bars.");
9
+ }
10
+ const dataEnd = data.startTime + data.min.length * data.bucketDuration;
11
+ const start = viewStart ?? data.startTime;
12
+ const end = viewEnd ?? dataEnd;
13
+ if (!Number.isFinite(start) || !Number.isFinite(end) || !Number.isFinite(dataEnd) || !Number.isFinite(end - start) || end < start || end === start && (data.min.length !== 0 || viewStart !== void 0 || viewEnd !== void 0)) {
14
+ throw new RangeError("AudioWaveform requires an increasing finite time window.");
15
+ }
16
+ if (data.min.length === 0) {
17
+ return { buckets: [], start, end };
18
+ }
19
+ const count = Math.min(barCount, Math.max(1, Math.ceil((end - start) / data.bucketDuration)));
20
+ const duration = (end - start) / count;
21
+ const buckets = Array.from({ length: count }, (_, index) => {
22
+ const from = start + index * duration;
23
+ const to = start + (index + 1) * duration;
24
+ const first = Math.max(0, Math.floor((from - data.startTime) / data.bucketDuration));
25
+ const last = Math.min(data.min.length, Math.ceil((to - data.startTime) / data.bucketDuration));
26
+ let low = Infinity;
27
+ let high = -Infinity;
28
+ let actualStart = to;
29
+ let actualEnd = from;
30
+ for (let source = first; source < last; source++) {
31
+ const sourceStart = data.startTime + source * data.bucketDuration;
32
+ const sourceEnd = data.startTime + (source + 1) * data.bucketDuration;
33
+ if (sourceEnd <= from || sourceStart >= to) {
34
+ continue;
35
+ }
36
+ const min = data.min[source];
37
+ const max = data.max[source];
38
+ if (min === void 0 || max === void 0 || !Number.isFinite(min) || !Number.isFinite(max) || min > max) {
39
+ continue;
40
+ }
41
+ low = Math.min(low, Math.max(-1, Math.min(1, min)));
42
+ high = Math.max(high, Math.max(-1, Math.min(1, max)));
43
+ actualStart = Math.min(actualStart, Math.max(from, sourceStart));
44
+ actualEnd = Math.max(actualEnd, Math.min(to, sourceEnd));
45
+ }
46
+ return low === Infinity ? null : { start: actualStart, end: actualEnd, min: low, max: high };
47
+ });
48
+ return { buckets, start, end };
49
+ }
50
+ function waveformPath(model, variant, barGap) {
51
+ if (!Number.isFinite(barGap) || barGap < 0 || barGap >= 1) {
52
+ throw new RangeError("AudioWaveform barGap must be a finite fraction from 0 (inclusive) to 1 (exclusive).");
53
+ }
54
+ const { buckets, start, end } = model;
55
+ if (end <= start || buckets.length === 0) {
56
+ return "";
57
+ }
58
+ const x = (time) => (time - start) / (end - start) * 1e3;
59
+ const y = (value) => (1 - value) * 50;
60
+ if (variant === "bars") {
61
+ return buckets.map((bucket, index) => {
62
+ if (!bucket || bucket.min === bucket.max) {
63
+ return "";
64
+ }
65
+ const gap = (x(bucket.end) - x(bucket.start)) * barGap / 2;
66
+ const left = x(bucket.start) + (index === 0 ? 0 : gap);
67
+ const right = x(bucket.end) - (index === buckets.length - 1 ? 0 : gap);
68
+ return `M${left},${y(bucket.max)}H${right}V${y(bucket.min)}H${left}Z`;
69
+ }).join(" ");
70
+ }
71
+ const paths = [];
72
+ let run = [];
73
+ const flush = () => {
74
+ if (run.length === 0) {
75
+ return;
76
+ }
77
+ const first = run[0];
78
+ const last = run[run.length - 1];
79
+ const top = run.map((bucket) => `L${x((bucket.start + bucket.end) / 2)},${y(bucket.max)}`).join(" ");
80
+ const bottom = [...run].reverse().map((bucket) => `L${x((bucket.start + bucket.end) / 2)},${y(bucket.min)}`).join(" ");
81
+ paths.push(`M${x(first.start)},${y(first.max)} ${top} L${x(last.end)},${y(last.max)} L${x(last.end)},${y(last.min)} ${bottom} L${x(first.start)},${y(first.min)}Z`);
82
+ run = [];
83
+ };
84
+ for (const bucket of buckets) {
85
+ if (bucket) {
86
+ if (run.length > 0 && bucket.start > run[run.length - 1].end) {
87
+ flush();
88
+ }
89
+ run.push(bucket);
90
+ } else {
91
+ flush();
92
+ }
93
+ }
94
+ flush();
95
+ return paths.join(" ");
96
+ }
97
+
98
+ // src/audio-waveform/audio-waveform.tsx
99
+ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
100
+ function AudioWaveform({
101
+ label,
102
+ data,
103
+ variant = "bars",
104
+ barCount = 128,
105
+ barGap = 0.3,
106
+ viewStart,
107
+ viewEnd,
108
+ playhead,
109
+ className,
110
+ ...rest
111
+ }) {
112
+ const clipId = useId();
113
+ const model = waveformModel(data, barCount, viewStart, viewEnd);
114
+ const path = waveformPath(model, variant, barGap);
115
+ const hasPlayhead = playhead !== void 0 && Number.isFinite(playhead) && model.end > model.start;
116
+ const position = hasPlayhead ? (playhead - model.start) / (model.end - model.start) * 1e3 : 0;
117
+ const playedWidth = Math.max(0, Math.min(1e3, position));
118
+ return /* @__PURE__ */ jsxs(
119
+ "svg",
120
+ {
121
+ role: "img",
122
+ "aria-label": label,
123
+ ...rest,
124
+ className: cn("gridui-audio-waveform", className),
125
+ "data-gridui-component": "audio-waveform",
126
+ "data-gridui-draw": "graphic",
127
+ viewBox: "0 0 1000 100",
128
+ preserveAspectRatio: "none",
129
+ children: [
130
+ /* @__PURE__ */ jsx("path", { d: path, fill: "currentColor", opacity: hasPlayhead ? 0.25 : 1 }),
131
+ hasPlayhead && /* @__PURE__ */ jsxs(Fragment, { children: [
132
+ /* @__PURE__ */ jsx("defs", { children: /* @__PURE__ */ jsx("clipPath", { id: clipId, children: /* @__PURE__ */ jsx("rect", { width: playedWidth, height: 100 }) }) }),
133
+ /* @__PURE__ */ jsx("path", { d: path, fill: "currentColor", clipPath: `url(#${clipId})` }),
134
+ position >= 0 && position <= 1e3 && /* @__PURE__ */ jsx(
135
+ "line",
136
+ {
137
+ className: "gridui-audio-waveform-playhead",
138
+ x1: position,
139
+ x2: position,
140
+ y1: 0,
141
+ y2: 100,
142
+ strokeWidth: 1,
143
+ vectorEffect: "non-scaling-stroke"
144
+ }
145
+ )
146
+ ] })
147
+ ]
148
+ }
149
+ );
150
+ }
151
+ export {
152
+ AudioWaveform
153
+ };
154
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../src/audio-waveform/audio-waveform.tsx", "../src/audio-waveform/model.ts"],
4
+ "sourcesContent": ["import { cn } from \"@gridui/style-utils\";\nimport { useId, type ComponentPropsWithRef } from \"react\";\nimport { waveformModel, waveformPath } from \"./model\";\nimport type { AudioWaveformData } from \"./types\";\n\nexport type AudioWaveformProps = Omit<ComponentPropsWithRef<\"svg\">, \"children\" | \"viewBox\" | \"preserveAspectRatio\"> & {\n /** Accessible description of the audio source; not a visible heading. */\n readonly label: string;\n readonly data: AudioWaveformData;\n readonly variant?: \"bars\" | \"envelope\";\n /** Maximum display buckets. Peak aggregation preserves short transients. */\n readonly barCount?: number;\n readonly barGap?: number;\n /** Seconds on the same clock as data.startTime. */\n readonly viewStart?: number;\n readonly viewEnd?: number;\n /** Controlled playhead in seconds. Omit for unplayed/live input. */\n readonly playhead?: number;\n};\n\nexport function AudioWaveform({\n label, data, variant = \"bars\", barCount = 128, barGap = 0.3,\n viewStart, viewEnd, playhead, className, ...rest\n}: AudioWaveformProps) {\n const clipId = useId();\n const model = waveformModel(data, barCount, viewStart, viewEnd);\n const path = waveformPath(model, variant, barGap);\n const hasPlayhead = playhead !== undefined && Number.isFinite(playhead) && model.end > model.start;\n const position = hasPlayhead ? (playhead - model.start) / (model.end - model.start) * 1000 : 0;\n const playedWidth = Math.max(0, Math.min(1000, position));\n return <svg\n role=\"img\"\n aria-label={label}\n {...rest}\n className={cn(\"gridui-audio-waveform\", className)}\n data-gridui-component=\"audio-waveform\"\n data-gridui-draw=\"graphic\"\n viewBox=\"0 0 1000 100\"\n preserveAspectRatio=\"none\"\n >\n <path d={path} fill=\"currentColor\" opacity={hasPlayhead ? 0.25 : 1} />\n {hasPlayhead && <>\n <defs><clipPath id={clipId}><rect width={playedWidth} height={100} /></clipPath></defs>\n <path d={path} fill=\"currentColor\" clipPath={`url(#${clipId})`} />\n {position >= 0 && position <= 1000 && <line\n className=\"gridui-audio-waveform-playhead\"\n x1={position} x2={position} y1={0} y2={100}\n strokeWidth={1} vectorEffect=\"non-scaling-stroke\"\n />}\n </>}\n </svg>;\n}\n", "import type { AudioWaveformData, WaveformBucket, WaveformModel } from \"./types\";\n\n/** Keep time gaps and signed extrema instead of stretching available data over a window. */\nexport function waveformModel(data: AudioWaveformData, barCount: number, viewStart?: number, viewEnd?: number): WaveformModel {\n if (!Number.isFinite(data.startTime) || !Number.isFinite(data.bucketDuration) || data.bucketDuration <= 0\n || data.min.length !== data.max.length || !Number.isSafeInteger(data.min.length) || data.min.length < 0\n || !Number.isInteger(barCount) || barCount < 1 || barCount > 512) {\n throw new RangeError(\"AudioWaveform requires a finite startTime, positive bucketDuration, equal extrema lengths, and 1\u2013512 bars.\");\n }\n const dataEnd = data.startTime + data.min.length * data.bucketDuration;\n const start = viewStart ?? data.startTime;\n const end = viewEnd ?? dataEnd;\n if (!Number.isFinite(start) || !Number.isFinite(end) || !Number.isFinite(dataEnd) || !Number.isFinite(end - start)\n || end < start || (end === start && (data.min.length !== 0 || viewStart !== undefined || viewEnd !== undefined))) {\n throw new RangeError(\"AudioWaveform requires an increasing finite time window.\");\n }\n if (data.min.length === 0) {return { buckets: [], start, end };}\n const count = Math.min(barCount, Math.max(1, Math.ceil((end - start) / data.bucketDuration)));\n const duration = (end - start) / count;\n const buckets = Array.from({ length: count }, (_, index): WaveformBucket | null => {\n const from = start + index * duration;\n const to = start + (index + 1) * duration;\n const first = Math.max(0, Math.floor((from - data.startTime) / data.bucketDuration));\n const last = Math.min(data.min.length, Math.ceil((to - data.startTime) / data.bucketDuration));\n let low = Infinity;\n let high = -Infinity;\n let actualStart = to;\n let actualEnd = from;\n for (let source = first; source < last; source++) {\n const sourceStart = data.startTime + source * data.bucketDuration;\n const sourceEnd = data.startTime + (source + 1) * data.bucketDuration;\n if (sourceEnd <= from || sourceStart >= to) {continue;}\n const min = data.min[source];\n const max = data.max[source];\n if (min === undefined || max === undefined || !Number.isFinite(min) || !Number.isFinite(max) || min > max) {continue;}\n low = Math.min(low, Math.max(-1, Math.min(1, min)));\n high = Math.max(high, Math.max(-1, Math.min(1, max)));\n actualStart = Math.min(actualStart, Math.max(from, sourceStart));\n actualEnd = Math.max(actualEnd, Math.min(to, sourceEnd));\n }\n return low === Infinity ? null : { start: actualStart, end: actualEnd, min: low, max: high };\n });\n return { buckets, start, end };\n}\n\nexport function waveformPath(model: WaveformModel, variant: \"bars\" | \"envelope\", barGap: number): string {\n if (!Number.isFinite(barGap) || barGap < 0 || barGap >= 1) {\n throw new RangeError(\"AudioWaveform barGap must be a finite fraction from 0 (inclusive) to 1 (exclusive).\");\n }\n const { buckets, start, end } = model;\n if (end <= start || buckets.length === 0) {return \"\";}\n const x = (time: number): number => (time - start) / (end - start) * 1000;\n const y = (value: number): number => (1 - value) * 50;\n if (variant === \"bars\") {\n return buckets.map((bucket, index) => {\n if (!bucket || bucket.min === bucket.max) {return \"\";}\n // Only interior edges get a bar gap; the first and last data edges stay flush.\n const gap = (x(bucket.end) - x(bucket.start)) * barGap / 2;\n const left = x(bucket.start) + (index === 0 ? 0 : gap);\n const right = x(bucket.end) - (index === buckets.length - 1 ? 0 : gap);\n return `M${left},${y(bucket.max)}H${right}V${y(bucket.min)}H${left}Z`;\n }).join(\" \");\n }\n const paths: string[] = [];\n let run: WaveformBucket[] = [];\n const flush = (): void => {\n if (run.length === 0) {return;}\n const first = run[0]!;\n const last = run[run.length - 1]!;\n const top = run.map(bucket => `L${x((bucket.start + bucket.end) / 2)},${y(bucket.max)}`).join(\" \");\n const bottom = [...run].reverse().map(bucket => `L${x((bucket.start + bucket.end) / 2)},${y(bucket.min)}`).join(\" \");\n paths.push(`M${x(first.start)},${y(first.max)} ${top} L${x(last.end)},${y(last.max)} L${x(last.end)},${y(last.min)} ${bottom} L${x(first.start)},${y(first.min)}Z`);\n run = [];\n };\n for (const bucket of buckets) {\n if (bucket) {\n if (run.length > 0 && bucket.start > run[run.length - 1]!.end) {flush();}\n run.push(bucket);\n } else {flush();}\n }\n flush();\n return paths.join(\" \");\n}\n"],
5
+ "mappings": "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",
6
+ "names": []
7
+ }
@@ -0,0 +1,19 @@
1
+ /*! tailwindcss v4.3.5 | MIT License | https://tailwindcss.com */
2
+ @layer theme, base, components, utilities;
3
+ @layer utilities;
4
+ @layer components {
5
+ .gridui-audio-waveform {
6
+ display: block;
7
+ inline-size: 100%;
8
+ block-size: 100%;
9
+ min-inline-size: 0;
10
+ padding: 0;
11
+ margin: 0;
12
+ border: 0;
13
+ background: transparent;
14
+ color: var(--gridui-accent-background);
15
+ }
16
+ .gridui-audio-waveform-playhead {
17
+ stroke: var(--gridui-foreground);
18
+ }
19
+ }
@@ -0,0 +1,38 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "name": "@gridui/audio-waveform",
4
+ "version": "0.0.0",
5
+ "category": "data",
6
+ "description": "Content-only GridUI time-domain audio visualization",
7
+ "usage": "`AudioWaveform` displays signed audio extrema over time, as bars or a continuous envelope. Import `AudioWaveform`, `AudioWaveformProps`, and `AudioWaveformData` from the package root. Load `@gridui/theme/styles.css`, then `@gridui/audio-waveform/styles.css`.",
8
+ "documentation": [
9
+ "README.md",
10
+ "docs/reference/README.md",
11
+ "docs/reference/audio-waveform.md"
12
+ ],
13
+ "exports": [
14
+ {
15
+ "name": "AudioWaveform",
16
+ "kind": "component",
17
+ "importPath": "@gridui/audio-waveform"
18
+ },
19
+ {
20
+ "name": "AudioWaveformData",
21
+ "kind": "type",
22
+ "importPath": "@gridui/audio-waveform"
23
+ },
24
+ {
25
+ "name": "AudioWaveformProps",
26
+ "kind": "type",
27
+ "importPath": "@gridui/audio-waveform"
28
+ }
29
+ ],
30
+ "styles": [
31
+ "@gridui/theme/styles.css",
32
+ "@gridui/audio-waveform/styles.css"
33
+ ],
34
+ "examples": [
35
+ "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-data/audio-waveform/stories/getting-started.mdx",
36
+ "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-data/audio-waveform/stories/audio-waveform.stories.tsx"
37
+ ]
38
+ }
@@ -0,0 +1,4 @@
1
+ <!-- Generated by pnpm docs:storybook. -->
2
+ # Component reference
3
+
4
+ - [AudioWaveform](audio-waveform.md)
@@ -0,0 +1,99 @@
1
+ <!-- Generated from public Props and owned stories. Run pnpm docs:storybook. -->
2
+ # AudioWaveform
3
+
4
+ Displays signed audio extrema over time without owning playback or recording. Use it for full recordings or controlled scrolling time windows inside Grid.
5
+
6
+ Import from ``@gridui/audio-waveform`` and load Theme before this family's stylesheet.
7
+
8
+ ```tsx
9
+ import { AudioWaveform } from "@gridui/audio-waveform";
10
+ import "@gridui/theme/styles.css";
11
+ import "@gridui/audio-waveform/styles.css";
12
+ ```
13
+
14
+ Read the [package contract](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-data/audio-waveform/README.md) for shared behavior and stylesheet dependencies.
15
+
16
+ The [working composition](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-data/audio-waveform/stories/audio-waveform.stories.tsx) demonstrates required context, state, and related components. Use View code in Storybook to inspect the actual implementation.
17
+
18
+ ## API
19
+
20
+ The public Props type is the source of these signatures. Defaults below are explicit implementation defaults; story presets are separate. Native attributes remain available through the exported Props type.
21
+
22
+ ### onFocus
23
+
24
+ ``(event: FocusEvent<SVGSVGElement, Element>): void`` · Optional
25
+
26
+ Called when the corresponding interaction occurs; inspect the arguments in Actions.
27
+
28
+ ### onBlur
29
+
30
+ ``(event: FocusEvent<SVGSVGElement, Element>): void`` · Optional
31
+
32
+ Called when the corresponding interaction occurs; inspect the arguments in Actions.
33
+
34
+ ### onChange
35
+
36
+ ``(event: ChangeEvent<SVGSVGElement, Element>): void`` · Optional
37
+
38
+ Called when the corresponding interaction occurs; inspect the arguments in Actions.
39
+
40
+ ### onSubmit
41
+
42
+ ``(event: SubmitEvent<SVGSVGElement>): void`` · Optional
43
+
44
+ Called when the corresponding interaction occurs; inspect the arguments in Actions.
45
+
46
+ ### onClick
47
+
48
+ ``(event: MouseEvent<SVGSVGElement, MouseEvent>): void`` · Optional
49
+
50
+ Called when the corresponding interaction occurs; inspect the arguments in Actions.
51
+
52
+ ### label
53
+
54
+ ``string`` · Required
55
+
56
+ Accessible description of the audio source; not a visible heading.
57
+
58
+ ### data
59
+
60
+ ``AudioWaveformData`` · Required
61
+
62
+ ### variant
63
+
64
+ ``"bars" | "envelope" | undefined`` · Optional
65
+
66
+ Default: ``"bars"``
67
+
68
+ Visual variant.
69
+
70
+ ### barCount
71
+
72
+ ``number | undefined`` · Optional
73
+
74
+ Default: ``128``
75
+
76
+ Maximum display buckets. Peak aggregation preserves short transients.
77
+
78
+ ### barGap
79
+
80
+ ``number | undefined`` · Optional
81
+
82
+ Default: ``0.3``
83
+
84
+ ### viewStart
85
+
86
+ ``number | undefined`` · Optional
87
+
88
+ Seconds on the same clock as data.startTime.
89
+
90
+ ### viewEnd
91
+
92
+ ``number | undefined`` · Optional
93
+
94
+ ### playhead
95
+
96
+ ``number | undefined`` · Optional
97
+
98
+ Controlled playhead in seconds. Omit for unplayed/live input.
99
+
package/package.json CHANGED
@@ -1,6 +1,51 @@
1
1
  {
2
2
  "name": "@gridui/audio-waveform",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.0.0",
4
+ "description": "Content-only GridUI time-domain audio visualization",
5
+ "license": "UNLICENSED",
6
+ "type": "module",
7
+ "files": [
8
+ "dist",
9
+ "README.md",
10
+ "docs"
11
+ ],
12
+ "sideEffects": [
13
+ "**/*.css"
14
+ ],
15
+ "exports": {
16
+ ".": {
17
+ "types": "./dist/index.d.ts",
18
+ "import": "./dist/index.js"
19
+ },
20
+ "./styles.css": "./dist/styles.css"
21
+ },
22
+ "publishConfig": {
23
+ "access": "public"
24
+ },
25
+ "peerDependencies": {
26
+ "react": "^19.2.0",
27
+ "react-dom": "^19.2.0"
28
+ },
29
+ "dependencies": {
30
+ "@gridui/style-utils": "^4.0.0",
31
+ "@gridui/theme": "^2.6.0"
32
+ },
33
+ "devDependencies": {
34
+ "@gridui-internal/configuration": "0.0.0-internal",
35
+ "@jest/globals": "30.5.2",
36
+ "@storybook/react-vite": "10.6.7",
37
+ "@types/jest": "30.0.0",
38
+ "@types/node": "26.6.6",
39
+ "@types/react": "19.3.0",
40
+ "@types/react-dom": "19.3.0",
41
+ "jest": "30.5.2",
42
+ "react": "19.3.1",
43
+ "react-dom": "19.3.1",
44
+ "typescript": "6.0.3"
45
+ },
46
+ "scripts": {
47
+ "build": "node ../../scripts/compilation/package.ts",
48
+ "compile": "tsc --project tsconfig.json",
49
+ "test": "jest"
50
+ }
6
51
  }