BarSeries

Read as Markdown

Import from @pibbl/core/viz. This component supports vertical and horizontal value and range bars. For value bars use data, category (category key/accessor), value (numeric key/accessor), categoryScale (band), and valueScale (linear). orientation is "vertical" (default) or "horizontal". Orientation assigns the category and value dimensions to physical axes; callers choose matching scale ranges and Axis positions. For horizontal bars, use a category range of "height" and a value range of "width". baseline is a signal-capable finite domain value, defaulting to zero. Linear mapping extrapolates; use core Clip when clipping to a plot is desired.

Missing categories, unknown categories, null/undefined/nonfinite values, or rows excluded by defined are skipped. Zero-length bars paint and target nothing. Negative values normalize their two mapped endpoints into rectangle geometry. Data accepts a signal; accessor reads belong to the receiving component.

BarSeriesStyle accepts whole and shallow field signals: bandwidth (default "auto", otherwise finite nonnegative local pixels centered in the band), fill (default #2563eb), stroke, strokeWidth (1), opacity (1), and cursor.

Each row renders an ordinary core Rectangle in source order. Series handlers bubble through their parent Group. Hit geometry is ordinary rectangle paint geometry, including stroke; padding and omitted rows do not create targets. Coordinates remain root-logical. There is no datum-enriched event: inspect via useBarScale(id), data, and ordinary events. Per-row nodes have ordinary component cost; this slice makes no large-data batching guarantee.

The former bar coordinate props (x, y, xScale, yScale, yStart, yEnd) were removed. There are no compatibility aliases. Lines and points continue to use coordinate props.

Range and stacked bars

Replace value and baseline with paired valueStart and valueEnd numeric keys or accessors. Mixing the two forms rejects. Each range renders one rectangle between its mapped endpoints; reversed endpoints work, missing/nonfinite endpoints skip the row, and equal endpoints paint and target nothing.

Stacking is a pure data transform that produces these endpoints. BarSeries does not accumulate or reorder rows. The stacked cash flow example accumulates positive and negative values separately from zero, in explicit component order, omitting nonfinite values. This is the example’s stacking policy, not an implicit renderer policy or a new exported stacking helper.

Ranges support the same shared styles, datum style callbacks, threshold fills, and optional group/groupScale placement as ordinary bars. Thresholds continue to use value-scale domain coordinates, not each segment’s magnitude. Hit geometry belongs to each individual segment; no whole-stack hover box is added.

Grouped bars

Supply group (a category key/accessor) and groupScale together. The inner band scale defines group order and spacing within each outer category:

import { BarSeries, BarScale, LinearScale } from "@pibbl/core/viz";
const rows = [
  { month: "Jan", team: "East", sales: 72, category: "Jan", value: 320_000 },
  { month: "Jan", team: "West", sales: 55, category: "Feb", value: -40_000 },
];
const grouped = (
  <BarScale id="month" domain={["Jan", "Feb"]} range="width">
    <BarScale
      id="team"
      domain={["East", "West"]}
      range={{ bandwidthOf: "month" }}
      paddingInner={0.15}
    >
      <LinearScale id="sales" domain={[0, 100]} range="height" reverse>
        <BarSeries
          data={rows}
          category="month"
          value="sales"
          group="team"
          categoryScale="month"
          valueScale="sales"
          groupScale="team"
          style={(row) => ({ fill: row.team === "East" ? "teal" : "orange" })}
        />
      </LinearScale>
    </BarScale>
  </BarScale>
);
void grouped;

Group identity follows band category identity. Missing or unknown groups skip their rows; other groups retain their slots. Reordering the inner domain moves groups consistently across categories. Empty or collapsed bands paint no bars. Offsets add the outer category start to the inner group start. Auto bandwidth uses the inner scale; explicit bandwidth centers within that group slot and may overlap neighboring slots. Duplicate category/group rows paint in source order.

BarStyleResolver<D> receives (datum, index, data) for each eligible row. Return a plain BarSeriesStyle, including threshold fills if desired. Read signals explicitly inside the callback; returned field signals are rejected. Callbacks are synchronous and cannot call hooks. A callback replaces the shared style form rather than merging with it. Each rectangle retains its own cursor, paint, and normal event geometry.

Try Grouped bars with two or three years, group reordering, resizing, and pointer inspection.

Fill by value thresholds

A single series can color regions of each bar by value-scale coordinates:

const thresholdBars = (
  <BarSeries
    data={rows}
    category="category"
    value="value"
    categoryScale="categories"
    valueScale="values"
    style={{
      fill: {
        type: "threshold",
        thresholds: [0, 300_000],
        colors: ["#c36638", "#167b70", "#c43c39"],
      },
    }}
  />
);
void thresholdBars;

BarThresholdFill requires finite, strictly increasing thresholds and exactly one more CSS color than thresholds. Below the first threshold uses the first color; each threshold begins the next interval. Empty thresholds with one color are valid. Colors are sharp regions, not interpolated gradients or whole-bar classifications. A bar crossing multiple intervals receives each corresponding color. Thresholds outside the bar do not extend it. Baseline and reversed value scales preserve the same domain-based coloring in either orientation. Threshold regions follow the physical value axis; group offsets follow the category axis.

The complete fill descriptor can be a signal, as can the whole style. Nested threshold/color arrays contain plain values; replace the descriptor to update. Stroke, opacity, and hit geometry remain those of one complete rectangle; color boundaries add no borders or targets. Standard solid, gradient, and pattern fills continue to work.

Cost and updates

Rendering is O(n) in rows with one ordinary Rectangle per eligible nonzero bar. Accessors and datum styles reevaluate in the receiving component’s tracked evaluation; same callback identity does not cache their results. Signals read inside them schedule updates. Plain in-place mutations alone do not schedule a render. There is no series-owned index, retained geometry cache or extra event system.

API details from source

BarSeries

Value bars in source order; rectangles supply ordinary paint and event geometry.

BarSeries: <D>({ data: input, orientation, category: categoryInput, value: valueInput, valueStart, valueEnd, categoryScale, valueScale, baseline, group, groupScale, defined, style: styleInput, pointerEvents, ...events }: BarSeriesProps<D>) => JSX.Element

Related API: BarSeries, BarSeriesProps, JSX.

Parameters

props — Data, category and value accessors, scales, grouping, and styling. See BarSeriesProps .

Returns

Pibbl nodes drawing the bars.

BarThresholdFill

Domain thresholds divide the bar fill into sharp, ordered color intervals.

interface BarThresholdFill

Related API: BarThresholdFill.

Properties and methods

type

readonly type: "threshold"

The literal “threshold” identifying this variant. See BarThresholdFill.

View source — packages/core/src/features/viz/lib/bar-fill.ts:11

thresholds

readonly thresholds: readonly number[]

Ordered numeric boundaries separating fill-color intervals. See BarThresholdFill.

View source — packages/core/src/features/viz/lib/bar-fill.ts:13

colors

readonly colors: readonly string[]

Colors assigned to successive threshold intervals. See BarThresholdFill.

View source — packages/core/src/features/viz/lib/bar-fill.ts:15

BarCategoryAccessor

A data property or callback that extracts a category, with nullish values treated as missing.

type BarCategoryAccessor<D> = | {
      [K in keyof D]-?: D[K] extends BandCategory | null | undefined
        ? K
        : never;
    }[keyof D]
  | ((
      datum: D,
      index: number,
      data: readonly D[],
    ) => BandCategory | null | undefined)

Related API: BarCategoryAccessor, BandCategory.

Parameters

datum — Datum whose category is being read.
index — Zero-based index in the source data.
data — Complete source data array.

Returns

The category, or null/undefined to indicate a missing category. See BandCategory .

BarSeriesStyle

Supported geometry and presentation properties for BarSeries.

interface BarSeriesStyle

Related API: BarSeriesStyle.

Properties and methods

bandwidth (optional)

readonly bandwidth?: number | "auto" | undefined

Width allocated to one categorical band. See BarSeriesStyle.

View source — packages/core/src/features/viz/lib/bar-series.tsx:59

fill (optional)

readonly fill?: BarThresholdFill | FillStyle | undefined

Related API: BarThresholdFill, FillStyle.

Paint used for the interior. See FillStyle, BarThresholdFill.

View source — packages/core/src/features/viz/lib/bar-series.tsx:61

stroke (optional)

readonly stroke?: StrokeStyle | undefined

Related API: StrokeStyle.

Paint used for the outline. See StrokeStyle.

View source — packages/core/src/features/viz/lib/bar-series.tsx:63

strokeWidth (optional)

readonly strokeWidth?: number | undefined

Width of the painted outline. See BarSeriesStyle.

View source — packages/core/src/features/viz/lib/bar-series.tsx:65

opacity (optional)

readonly opacity?: number | undefined

Related API: opacity.

Opacity of the painted result. See BarSeriesStyle.

View source — packages/core/src/features/viz/lib/bar-series.tsx:67

cursor (optional)

readonly cursor?: string | undefined

Cursor shown while this target owns pointer presentation. See BarSeriesStyle.

View source — packages/core/src/features/viz/lib/bar-series.tsx:69

BarStyleResolver

Computes bar styling from the datum, index, and source data.

type BarStyleResolver<D> = (
  datum: D,
  index: number,
  data: readonly D[],
) => BarSeriesStyle

Related API: BarStyleResolver, BarSeriesStyle.

Parameters

datum — Datum being styled.
index — Zero-based index in the source data.
data — Complete source data array.

Returns

Style for this datum’s bar. See BarSeriesStyle.

BarSeriesProps

Authored inputs for BarSeries, including the declared data and presentation options.

Full type declaration

type BarSeriesProps<D> = BarSeriesBaseProps<D> &
  (
    | {
        /** Value associated with this sample, input, or result. See {@link LineAccessor}. */
        readonly value: LineAccessor<D>;
        /** Numeric value from which each ordinary bar starts. See {@link SignalValue}. */
        readonly baseline?: SignalValue<number>;
        /**
         * Not accepted in this variant; use the alternative fields instead. See
         * {@link BarSeriesProps}.
         */
        readonly valueStart?: never;
        /**
         * Not accepted in this variant; use the alternative fields instead. See
         * {@link BarSeriesProps}.
         */
        readonly valueEnd?: never;
      }
    | {
        /**
         * Not accepted in this variant; use the alternative fields instead. See
         * {@link BarSeriesProps}.
         */
        readonly value?: never;
        /**
         * Not accepted in this variant; use the alternative fields instead. See
         * {@link BarSeriesProps}.
         */
        readonly baseline?: never;
        /** Accessor for the beginning of a range bar. See {@link LineAccessor}. */
        readonly valueStart: LineAccessor<D>;
        /** Accessor for the end of a range bar. See {@link LineAccessor}. */
        readonly valueEnd: LineAccessor<D>;
      }
  ) &
  (
    | {
        /** Accessor identifying the subgroup of each bar. See {@link BarCategoryAccessor}. */
        readonly group: BarCategoryAccessor<D>;
        /** Band scale used to place subgroups within a category. See {@link ScaleId}. */
        readonly groupScale: ScaleId;
      }
    | {
        /** Accessor identifying the subgroup of each bar. See {@link BarSeriesProps}. */
        readonly group?: never;
        /**
         * Not accepted in this variant; use the alternative fields instead. See
         * {@link BarSeriesProps}.
         */
        readonly groupScale?: never;
      }
  )

Properties and methods

data

readonly data: SignalValue<readonly D[]>

Related API: SignalValue.

Application data supplied to the component or reported by the event. See SignalValue.

View source — packages/core/src/features/viz/lib/bar-series.tsx:97

orientation (optional)

readonly orientation?: "horizontal" | "vertical" | undefined

Selects "vertical", "horizontal" for orientation. See BarSeriesBaseProps.

View source — packages/core/src/features/viz/lib/bar-series.tsx:99

Parameters

datum — Record to test.
index — Zero-based index in the source array.
data — Complete source data array.

Returns

Whether this record should contribute a bar.

View source — packages/core/src/features/viz/lib/bar-series.tsx:113

style (optional)

readonly style?: SignalValue<BarStyleResolver<D> | Readonly<{ readonly bandwidth?: SignalValue<number | "auto" | undefined>; readonly fill?: SignalValue<BarThresholdFill | FillStyle | undefined>; readonly stroke?: SignalValue<StrokeStyle | undefined>; readonly strokeWidth?: SignalValue<number | undefined>; readonly opacity?: SignalValue<number | undefined>; readonly cursor?: SignalValue<string | undefined>; }>> | undefined

Declared presentation and layout properties. See SignalValue, SignalStyle, BarSeriesStyle, BarStyleResolver.

View source — packages/core/src/features/viz/lib/bar-series.tsx:118

pointerEvents (optional)

readonly pointerEvents?: PibblPointerEvents | undefined

Related API: PibblPointerEvents.

Whether this content participates in pointer targeting. See PibblPointerEvents.

View source — packages/core/src/lib/events/types.ts:126

value (optional)

readonly value?: LineAccessor<D> | undefined

Related API: LineAccessor.

Value associated with this sample, input, or result. See LineAccessor. Not accepted in this variant; use the alternative fields instead. See BarSeriesProps.

View source — packages/core/src/features/viz/lib/bar-series.tsx:133

baseline (optional)

readonly baseline?: SignalValue<number> | undefined

Related API: SignalValue.

Numeric value from which each ordinary bar starts. See SignalValue. Not accepted in this variant; use the alternative fields instead. See BarSeriesProps.

View source — packages/core/src/features/viz/lib/bar-series.tsx:135

valueStart (optional)

readonly valueStart?: LineAccessor<D> | undefined

Related API: LineAccessor.

Not accepted in this variant; use the alternative fields instead. See BarSeriesProps. Accessor for the beginning of a range bar. See LineAccessor.

View source — packages/core/src/features/viz/lib/bar-series.tsx:140

valueEnd (optional)

readonly valueEnd?: LineAccessor<D> | undefined

Related API: LineAccessor.

Not accepted in this variant; use the alternative fields instead. See BarSeriesProps. Accessor for the end of a range bar. See LineAccessor.

View source — packages/core/src/features/viz/lib/bar-series.tsx:145

group (optional)

readonly group?: BarCategoryAccessor<D> | undefined

Related API: BarCategoryAccessor.

Accessor identifying the subgroup of each bar. See BarCategoryAccessor. Accessor identifying the subgroup of each bar. See BarSeriesProps.

View source — packages/core/src/features/viz/lib/bar-series.tsx:167

groupScale (optional)

readonly groupScale?: ScaleId | undefined

Related API: ScaleId.

Band scale used to place subgroups within a category. See ScaleId. Not accepted in this variant; use the alternative fields instead. See BarSeriesProps.

View source — packages/core/src/features/viz/lib/bar-series.tsx:169

Implementation guidance for agents

Read the Data visualization companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

Threshold-colored bars: Render category bars with a typed style resolver and threshold fill. Plain source

Documentation version

Documentation built with @pibbl/core 0.0.2, revision 380919b. ALPHA — NOT FOR PRODUCTION USE.

BarSeries

Range and stacked bars

Grouped bars

Fill by value thresholds

Cost and updates

API details from source

BarSeries

Parameters

Returns

See also

BarThresholdFill

See also

Properties and methods

BarCategoryAccessor

Parameters

Returns

See also

BarSeriesStyle

See also

Properties and methods

BarStyleResolver

Parameters

Returns

See also

BarSeriesProps

See also

Properties and methods

Parameters

Returns

Implementation guidance for agents

Complete minimal examples

Documentation version