# packages/core/src/features/viz/lib/area-series.tsx This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/272a94aaf62e0bd6ad8726a4c607a76a9ec44ca1/packages/core/src/features/viz/lib/area-series.tsx#L105). [Back to reference](/reference/components/area-series/)
1 import { Path, resolveSignalValue } from "@pibbl/core";
2 import type {
3   FillStyle,
4   PibblEventHandlers,
5   PibblEventParticipationOptions,
6   SignalValue,
7 } from "@pibbl/core";
8 import {
9   useInternalValueMemoSlot,
10   validateTexturePaint,
11 } from "@pibbl/core/internal";
12 import type { SignalStyle } from "@pibbl/core/internal";
13 import type { LineAccessor, LineCoordinate, LineSeriesProps } from "./types.js";
14 import {
15   appendCurveForward,
16   curveGeometry,
17   resolveSeriesCurve,
18 } from "./curve-definition.js";
19 import { opacity } from "./paint.js";
20 import { useContinuousScale } from "./use-continuous-scale.js";
21 
22 /**
23  * Presentation properties for an {@link AreaSeries}.
24  *
25  * @see {@link FillStyle}
26  * @see {@link AreaSeriesProps}
27  */
28 export interface AreaSeriesStyle {
29   /** Paint used for the area interior. */
30   readonly fill?: FillStyle;
31   /** Opacity of the painted area, from zero through one. */
32   readonly opacity?: number;
33   /** Cursor shown while the area target owns pointer presentation. */
34   readonly cursor?: string;
35 }
36 
37 /**
38  * Authored inputs for {@link AreaSeries}.
39  *
40  * The data, coordinate accessors, scales, and defined predicate use the same
41  * contract as {@link LineSeriesProps}. Each contiguous run of at least two
42  * valid observations is closed to `baseline` in data space.
43  *
44  * @see {@link LineSeriesProps}
45  * @see {@link AreaSeriesStyle}
46  */
47 export interface AreaSeriesProps<D>
48   extends PibblEventHandlers, PibblEventParticipationOptions {
49   /** Application data supplied directly or through a signal. */
50   readonly data: LineSeriesProps<D>["data"];
51   /** Property key or callback extracting the horizontal coordinate. */
52   readonly x: LineAccessor<D>;
53   /** Property key or callback extracting the vertical coordinate. */
54   readonly y: LineAccessor<D>;
55   /** Continuous scale used to map horizontal data coordinates. */
56   readonly xScale: LineSeriesProps<D>["xScale"];
57   /** Continuous scale used to map vertical data coordinates and baseline. */
58   readonly yScale: LineSeriesProps<D>["yScale"];
59   /** Selects records that participate in an observed run. */
60   readonly defined?: LineSeriesProps<D>["defined"];
61   /** Curve used to connect successive observed samples. */
62   readonly curve?: LineSeriesProps<D>["curve"];
63   /** Finite data-space value to which each observed run closes. */
64   readonly baseline: SignalValue<number>;
65   /** Shared area presentation. Individual datum styling is not supported. */
66   readonly style?: SignalValue<SignalStyle<AreaSeriesStyle>>;
67 }
68 
69 function accessor<D>(
70   input: LineAccessor<D>,
71 ): (datum: D, index: number, data: readonly D[]) => LineCoordinate {
72   return typeof input === "function"
73     ? input
74     : (datum) => datum[input] as LineCoordinate;
75 }
76 
77 function fill(value: unknown): FillStyle {
78   if (
79     typeof value === "string" ||
80     value instanceof CanvasGradient ||
81     value instanceof CanvasPattern
82   )
83     return value;
84   try {
85     validateTexturePaint(value as never);
86     return value as FillStyle;
87   } catch {
88     throw new TypeError("AreaSeries: invalid fill.");
89   }
90 }
91 
92 /**
93  * Draws each contiguous observed run as a filled polygon closed to an explicit baseline.
94  *
95  * Missing, non-finite, and excluded coordinates split runs. A lone observation has no area.
96  * The component owns one ordinary {@link Path} target, so event participation follows the
97  * standard Path defaults; callers may wrap it in `Clip` when clipping is needed.
98  *
99  * @param props - Data, coordinate accessors, continuous scales, baseline, and presentation.
100  * @returns A Pibbl path node containing all drawable area runs.
101  * @throws When `data` is not an array, the baseline is not finite, or presentation is invalid.
102  *
103  * @see {@link AreaSeriesProps}
104  */
105 export function AreaSeries<D>({
106   data: dataInput,
107   x: xInput,
108   y: yInput,
109   xScale: xId,
110   yScale: yId,
111   baseline: baselineInput,
112   defined,
113   curve,
114   style: styleInput,
115   ...eventProps
116 }: AreaSeriesProps<D>) {
117   const xScale = useContinuousScale(xId).get();
118   const yScale = useContinuousScale(yId).get();
119   const curveDefinition = resolveSeriesCurve(curve);
120   const x = useInternalValueMemoSlot(
121     "vizAreaXAccessor",
122     () => accessor(xInput),
123     [xInput],
124   );
125   const y = useInternalValueMemoSlot(
126     "vizAreaYAccessor",
127     () => accessor(yInput),
128     [yInput],
129   );
130   const data = resolveSignalValue(dataInput);
131   if (!Array.isArray(data))
132     throw new TypeError(
133       "AreaSeries data must be an array or a signal containing an array.",
134     );
135   const baseline = resolveSignalValue(baselineInput);
136   if (typeof baseline !== "number" || !Number.isFinite(baseline))
137     throw new RangeError("AreaSeries baseline must be finite.");
138   const baselineY = yScale.map(baseline);
139   if (!Number.isFinite(baselineY))
140     throw new RangeError(
141       "AreaSeries baseline must map to a finite coordinate.",
142     );
143   const style = resolveSignalValue(styleInput) ?? {};
144   if (style === null || typeof style !== "object" || Array.isArray(style))
145     throw new TypeError("AreaSeries: style must be an object.");
146   const areaFill = fill(resolveSignalValue(style.fill) ?? "#2563eb");
147   const alpha = opacity(resolveSignalValue(style.opacity) ?? 0.2, "AreaSeries");
148   const cursor = resolveSignalValue(style.cursor);
149   if (cursor !== undefined && typeof cursor !== "string")
150     throw new TypeError("AreaSeries: cursor must be a string.");
151 
152   const path = new Path2D();
153   let run: (readonly [number, number])[] = [];
154   const closeRun = () => {
155     if (run.length >= 2) {
156       const first = run[0];
157       const last = run[run.length - 1];
158       const geometry = curveGeometry(curveDefinition, run);
159       path.moveTo(geometry.start[0], geometry.start[1]);
160       appendCurveForward(path, geometry);
161       path.lineTo(last[0], baselineY);
162       path.lineTo(first[0], baselineY);
163       path.closePath();
164     }
165     run = [];
166   };
167   for (let i = 0; i < data.length; i++) {
168     const datum = data[i];
169     if (defined && !defined(datum, i, data)) {
170       closeRun();
171       continue;
172     }
173     const xv = x(datum, i, data);
174     const yv = y(datum, i, data);
175     if (
176       typeof xv !== "number" ||
177       typeof yv !== "number" ||
178       !Number.isFinite(xv) ||
179       !Number.isFinite(yv)
180     ) {
181       closeRun();
182       continue;
183     }
184     const point = [xScale.map(xv), yScale.map(yv)] as const;
185     if (!Number.isFinite(point[0]) || !Number.isFinite(point[1])) {
186       closeRun();
187       continue;
188     }
189     run.push(point);
190   }
191   closeRun();
192   return (
193     <Path
194       {...eventProps}
195       style={{ d: path, fill: areaFill, opacity: alpha, cursor }}
196     />
197   );
198 }
199
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.