# BarSeries

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](/playground/#/examples/composition/viz-stacked-bars)
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:

```tsx
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](/playground/#/examples/composition/viz-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:

```tsx
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

<span id="api-BarSeries"></span>

### BarSeries

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

```ts
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](/reference/components/bar-series/), [BarSeriesProps](/reference/components/bar-series/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Data, category and value accessors, scales, grouping, and styling. See
[BarSeriesProps](/reference/components/bar-series/) .

#### Returns

Pibbl nodes drawing the bars.

#### See also

[BarSeriesProps](/reference/components/bar-series/)

[View source — packages/core/src/features/viz/lib/bar-series.tsx:190](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L190)

<span id="api-BarThresholdFill"></span>

### BarThresholdFill

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

```ts
interface BarThresholdFill
```

Related API: [BarThresholdFill](/reference/components/bar-series/).

#### See also

[BarSeriesStyle](/reference/components/bar-series/)

[View source — packages/core/src/features/viz/lib/bar-fill.ts:9](/source/packages/core/src/features/viz/lib/bar-fill-ts/#L9)

#### Properties and methods

<span id="api-BarThresholdFill-type"></span>
<details>
<summary>type</summary>


```ts
readonly type: "threshold"
```

The literal "threshold" identifying this variant. See BarThresholdFill.

[View source — packages/core/src/features/viz/lib/bar-fill.ts:11](/source/packages/core/src/features/viz/lib/bar-fill-ts/#L11)

</details>

<span id="api-BarThresholdFill-thresholds"></span>
<details>
<summary>thresholds</summary>


```ts
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](/source/packages/core/src/features/viz/lib/bar-fill-ts/#L13)

</details>

<span id="api-BarThresholdFill-colors"></span>
<details>
<summary>colors</summary>


```ts
readonly colors: readonly string[]
```

Colors assigned to successive threshold intervals. See BarThresholdFill.

[View source — packages/core/src/features/viz/lib/bar-fill.ts:15](/source/packages/core/src/features/viz/lib/bar-fill-ts/#L15)

</details>

<span id="api-BarCategoryAccessor"></span>

### BarCategoryAccessor

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

```ts
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](/reference/components/bar-series/), [BandCategory](/reference/components/scale/).

#### 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](/reference/components/scale/) .

#### See also

[BandCategory](/reference/components/scale/)

[BarSeriesProps](/reference/components/bar-series/)

[View source — packages/core/src/features/viz/lib/bar-series.tsx:36](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L36)

<span id="api-BarSeriesStyle"></span>

### BarSeriesStyle

Supported geometry and presentation properties for BarSeries.

```ts
interface BarSeriesStyle
```

Related API: [BarSeriesStyle](/reference/components/bar-series/).

#### See also

[FillStyle](/reference/types/styles/#fillstyle)

[BarThresholdFill](/reference/components/bar-series/)

[StrokeStyle](/reference/types/styles/#strokestyle)

[BarStyleResolver](/reference/components/bar-series/)

[View source — packages/core/src/features/viz/lib/bar-series.tsx:57](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L57)

#### Properties and methods

<span id="api-BarSeriesStyle-bandwidth"></span>
<details>
<summary>bandwidth (optional)</summary>


```ts
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](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L59)

</details>

<span id="api-BarSeriesStyle-fill"></span>
<details>
<summary>fill (optional)</summary>


```ts
readonly fill?: BarThresholdFill | FillStyle | undefined
```

Related API: [BarThresholdFill](/reference/components/bar-series/), [FillStyle](/reference/types/styles/#fillstyle).

Paint used for the interior. See FillStyle, BarThresholdFill.

[View source — packages/core/src/features/viz/lib/bar-series.tsx:61](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L61)

</details>

<span id="api-BarSeriesStyle-stroke"></span>
<details>
<summary>stroke (optional)</summary>


```ts
readonly stroke?: StrokeStyle | undefined
```

Related API: [StrokeStyle](/reference/types/styles/#strokestyle).

Paint used for the outline. See StrokeStyle.

[View source — packages/core/src/features/viz/lib/bar-series.tsx:63](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L63)

</details>

<span id="api-BarSeriesStyle-strokeWidth"></span>
<details>
<summary>strokeWidth (optional)</summary>


```ts
readonly strokeWidth?: number | undefined
```

Width of the painted outline. See BarSeriesStyle.

[View source — packages/core/src/features/viz/lib/bar-series.tsx:65](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L65)

</details>

<span id="api-BarSeriesStyle-opacity"></span>
<details>
<summary>opacity (optional)</summary>


```ts
readonly opacity?: number | undefined
```

Related API: [opacity](/reference/types/filters/#opacity).

Opacity of the painted result. See BarSeriesStyle.

[View source — packages/core/src/features/viz/lib/bar-series.tsx:67](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L67)

</details>

<span id="api-BarSeriesStyle-cursor"></span>
<details>
<summary>cursor (optional)</summary>


```ts
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](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L69)

</details>

<span id="api-BarStyleResolver"></span>

### BarStyleResolver

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

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

Related API: [BarStyleResolver](/reference/components/bar-series/), [BarSeriesStyle](/reference/components/bar-series/).

#### 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](/reference/components/bar-series/).

#### See also

[BarSeriesStyle](/reference/components/bar-series/)

[View source — packages/core/src/features/viz/lib/bar-series.tsx:81](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L81)

<span id="api-BarSeriesProps"></span>

### BarSeriesProps

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

<details>
<summary>Full type declaration</summary>

```ts
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;
      }
  )
```

</details>

Related API: [BarSeriesProps](/reference/components/bar-series/), [LineAccessor](/reference/components/line-series/), [SignalValue](/reference/types/signal-inputs/#signalvalue), [BarCategoryAccessor](/reference/components/bar-series/), [ScaleId](/reference/components/scale/).

#### See also

[LineAccessor](/reference/components/line-series/)

[SignalValue](/reference/types/signal-inputs/#signalvalue)

[BarCategoryAccessor](/reference/components/bar-series/)

[ScaleId](/reference/components/scale/)

[BarSeries](/reference/components/bar-series/)

[View source — packages/core/src/features/viz/lib/bar-series.tsx:129](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L129)

#### Properties and methods

<span id="api-BarSeriesProps-data"></span>
<details>
<summary>data</summary>


```ts
readonly data: SignalValue<readonly D[]>
```

Related API: [SignalValue](/reference/types/signal-inputs/#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](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L97)

</details>

<span id="api-BarSeriesProps-orientation"></span>
<details>
<summary>orientation (optional)</summary>


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

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

[View source — packages/core/src/features/viz/lib/bar-series.tsx:99](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L99)

</details>

<span id="api-BarSeriesProps-category"></span>
<details>
<summary>category</summary>


```ts
readonly category: BarCategoryAccessor<D>
```

Related API: [BarCategoryAccessor](/reference/components/bar-series/).

Property or callback extracting a bar's discrete category. See BarCategoryAccessor.

[View source — packages/core/src/features/viz/lib/bar-series.tsx:101](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L101)

</details>

<span id="api-BarSeriesProps-categoryScale"></span>
<details>
<summary>categoryScale</summary>


```ts
readonly categoryScale: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

Band scale used to place categories. See ScaleId.

[View source — packages/core/src/features/viz/lib/bar-series.tsx:103](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L103)

</details>

<span id="api-BarSeriesProps-valueScale"></span>
<details>
<summary>valueScale</summary>


```ts
readonly valueScale: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

Numeric scale used to map bar values. See ScaleId.

[View source — packages/core/src/features/viz/lib/bar-series.tsx:105](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L105)

</details>

<span id="api-BarSeriesProps-defined"></span>
<details>
<summary>defined (optional)</summary>


```ts
readonly defined?: ((datum: D, index: number, data: readonly D[]) => boolean) | undefined
```

Selects the records that participate in the bar series. See BarSeriesProps.

##### 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](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L113)

</details>

<span id="api-BarSeriesProps-style"></span>
<details>
<summary>style (optional)</summary>


```ts
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
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue), [BarStyleResolver](/reference/components/bar-series/), [BarThresholdFill](/reference/components/bar-series/), [FillStyle](/reference/types/styles/#fillstyle), [StrokeStyle](/reference/types/styles/#strokestyle), [opacity](/reference/types/filters/#opacity).

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

[View source — packages/core/src/features/viz/lib/bar-series.tsx:118](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L118)

</details>

<span id="api-BarSeriesProps-pointerEvents"></span>
<details>
<summary>pointerEvents (optional)</summary>


```ts
readonly pointerEvents?: PibblPointerEvents | undefined
```

Related API: [PibblPointerEvents](/reference/types/events/#pibblpointerevents).

Whether this content participates in pointer targeting. See PibblPointerEvents.

[View source — packages/core/src/lib/events/types.ts:126](/source/packages/core/src/lib/events/types-ts/#L126)

</details>

<span id="api-BarSeriesProps-value"></span>
<details>
<summary>value (optional)</summary>


```ts
readonly value?: LineAccessor<D> | undefined
```

Related API: [LineAccessor](/reference/components/line-series/).

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](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L133)

</details>

<span id="api-BarSeriesProps-baseline"></span>
<details>
<summary>baseline (optional)</summary>


```ts
readonly baseline?: SignalValue<number> | undefined
```

Related API: [SignalValue](/reference/types/signal-inputs/#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](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L135)

</details>

<span id="api-BarSeriesProps-valueStart"></span>
<details>
<summary>valueStart (optional)</summary>


```ts
readonly valueStart?: LineAccessor<D> | undefined
```

Related API: [LineAccessor](/reference/components/line-series/).

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](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L140)

</details>

<span id="api-BarSeriesProps-valueEnd"></span>
<details>
<summary>valueEnd (optional)</summary>


```ts
readonly valueEnd?: LineAccessor<D> | undefined
```

Related API: [LineAccessor](/reference/components/line-series/).

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](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L145)

</details>

<span id="api-BarSeriesProps-group"></span>
<details>
<summary>group (optional)</summary>


```ts
readonly group?: BarCategoryAccessor<D> | undefined
```

Related API: [BarCategoryAccessor](/reference/components/bar-series/).

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](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L167)

</details>

<span id="api-BarSeriesProps-groupScale"></span>
<details>
<summary>groupScale (optional)</summary>


```ts
readonly groupScale?: ScaleId | undefined
```

Related API: [ScaleId](/reference/components/scale/).

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](/source/packages/core/src/features/viz/lib/bar-series-tsx/#L169)

</details>

## Implementation guidance for agents

Read the [Data visualization companion](/agents/topics/visualization/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Threshold-colored bars](/minimal-examples/viz/bars/): Render category bars with a typed style resolver and threshold fill. [Plain source](/minimal/viz/bars.tsx)
## Documentation version

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