panelui-native 0.86.1 → 0.87.0

package/lib/typescript/src/components/bubble-chart/index.d.ts

@@ -0,0 +1,338 @@
+/**
+ * BubbleChart — one labelled circle per row, on two measured axes, with a third
+ * quantity on each circle's area.
+ *
+ * ```tsx
+ * <BubbleChart data={teams} xDataKey="efficiency" yDataKey="performance"
+ *   sizeKey="headcount" labelKey="team">
+ *   <BubbleChart.Grid />
+ *   <BubbleChart.Bubbles />
+ *   <BubbleChart.Labels />
+ *   <BubbleChart.XAxis />
+ *   <BubbleChart.YAxis />
+ *   <BubbleChart.Tooltip />
+ * </BubbleChart>
+ * ```
+ *
+ * ## When this and not a scatter plot
+ *
+ * `ScatterChart` also maps a third quantity onto point area, through `sizeKey`,
+ * and it is the right component for a *series* of observations: many points of
+ * one colour, where the shape of the cloud is the finding and no single dot
+ * needs a name.
+ *
+ * This one is for a handful of named things. Each row is its own circle with
+ * its own colour and its own label written inside it, so the chart can be read
+ * entity by entity rather than as a distribution. Eight teams, twelve products,
+ * six regions — where the reader wants to find one of them and see where it
+ * sits.
+ *
+ * ## Area, not radius
+ *
+ * `sizeKey` maps to a circle's area. Doubling a radius quadruples the ink, so a
+ * chart that scaled the radius would show a doubled value as four times the
+ * size, and the reader would believe the picture. The scale runs over the whole
+ * data set, so one bubble's size means the same thing as another's.
+ *
+ * ## Labels are text, not SVG
+ *
+ * The names inside the bubbles are React Native `Text` in a layer over the
+ * plot, so they follow the theme's font and the platform's text scaling — SVG
+ * text does neither. A bubble too small to hold its own label is left without
+ * one rather than given an unreadable one; the readout still names it.
+ */
+import { type ReactNode } from 'react';
+import { type ViewProps } from 'react-native';
+import { type ChartAccessibilityProps } from '../../primitives/chart-accessibility.js';
+type Layer = 'svg' | 'overlay' | 'header' | 'footer';
+export type BubbleChartStatus = 'loading' | 'ready';
+export type BubbleChartDatum = Record<string, string | number | null | undefined>;
+/** One bubble, resolved back to the row it came from. */
+export interface BubbleChartPoint {
+    /** Index into `data`. */
+    index: number;
+    x: number;
+    y: number;
+    /** The value behind the area, when `sizeKey` is set. */
+    size: number | null;
+    /** The name written inside the circle, when `labelKey` is set. */
+    label: string;
+    /** The colour it was drawn in. */
+    color: string;
+    datum: BubbleChartDatum;
+}
+/** A bubble with its geometry resolved. Shared by every part. */
+interface ResolvedBubble extends BubbleChartPoint {
+    /** Radius in points, off the area scale. */
+    r: number;
+}
+/**
+ * The bubble under the finger, for something rendered *inside* the chart. A
+ * readout in the card's header is outside this provider — use
+ * `onActivePointChange` for that.
+ */
+export declare function useBubbleChart(): {
+    activeIndex: number;
+    activePoint: ResolvedBubble | null;
+};
+export interface BubbleChartProps extends ViewProps, ChartAccessibilityProps<BubbleChartDatum> {
+    className?: string;
+    /** The rows. One bubble each. */
+    data: BubbleChartDatum[];
+    /** Key holding the horizontal value. */
+    xDataKey?: string;
+    /** Key holding the vertical value. */
+    yDataKey?: string;
+    /**
+     * Key holding the third quantity, mapped to each bubble's *area*. Without it
+     * every bubble is drawn at the middle of `sizeRange` and the chart is a
+     * scatter plot with names on it.
+     */
+    sizeKey?: string;
+    /** Key holding the name written inside the circle. */
+    labelKey?: string;
+    /**
+     * Key holding a colour for the row — either a CSS colour or a number from 1
+     * to 5 naming a `--color-chart-*` token. Without it the ramp cycles by row.
+     */
+    colorKey?: string;
+    /**
+     * Smallest and largest radius `sizeKey` maps onto, in points. The largest is
+     * also what the plot holds back at every edge, so raising it costs room.
+     */
+    sizeRange?: [number, number];
+    /**
+     * `loading` shows a still field of muted circles and dissolves it as the real
+     * bubbles grow in. One component throughout, rather than a spinner swapped
+     * for a chart — swapping loses the transition. Add a `BubbleChart.Skeleton`
+     * for something to stand in the plot meanwhile.
+     */
+    status?: BubbleChartStatus;
+    /** Width ÷ height. `1` is the square shape a bubble field reads best in. */
+    aspectRatio?: number;
+    /** Milliseconds for the bubbles to grow in on mount. */
+    animationDuration?: number;
+    /** Milliseconds for the axes to settle after the data changes. */
+    domainDuration?: number;
+    /** Fix the horizontal axis instead of deriving it. */
+    xDomain?: [number, number];
+    /** Fix the vertical axis instead of deriving it. */
+    yDomain?: [number, number];
+    /** The bubble under the finger, and `null` when it lifts. */
+    onActivePointChange?: (point: BubbleChartPoint | null) => void;
+    children?: ReactNode;
+}
+/** Imperative handle: re-run the grow-in, for a "replay" control. */
+export interface BubbleChartHandle {
+    replay: () => void;
+}
+export interface BubbleChartGridProps {
+    /** Horizontal rules across the plot. */
+    rows?: number;
+    /** Vertical rules up it. Both axes are measured, so both earn lines. */
+    columns?: number;
+    color?: string;
+    opacity?: number;
+}
+/** Reference lines both ways, so a bubble can be placed against two numbers. */
+declare function BubbleChartGrid({ rows, columns, color, opacity, }: BubbleChartGridProps): import("react").JSX.Element;
+declare namespace BubbleChartGrid {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface BubbleChartBubblesProps {
+    /**
+     * Fill opacity. Below 1 by default so that overlapping bubbles read as
+     * denser rather than hiding each other — in a crowded corner that overlap
+     * *is* the finding, and opaque circles erase it.
+     */
+    opacity?: number;
+    /** One colour for every bubble, overriding the per-row ramp. */
+    color?: string;
+}
+/** The circles. */
+declare function BubbleChartBubbles({ opacity, color }: BubbleChartBubblesProps): import("react").JSX.Element | null;
+declare namespace BubbleChartBubbles {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface BubbleChartSkeletonProps {
+    /** How many placeholder circles to scatter. */
+    count?: number;
+    color?: string;
+}
+/**
+ * The loading state: a still field of muted circles where the data will be.
+ *
+ * Deliberately still. A shimmer over a field of circles reads as them *moving*,
+ * which is the one thing this chart must never appear to do — position is the
+ * entire message, and a loading state that implies it is changing is a loading
+ * state that lies.
+ *
+ * The layout is deterministic rather than random, so it does not reshuffle on
+ * every render of a component that may re-render several times while waiting.
+ * It dissolves as the real bubbles grow in, and outlives the status change by
+ * exactly that long: cut at the frame the data lands, the placeholder would
+ * disappear before anything had replaced it.
+ */
+declare function BubbleChartSkeleton({ count, color }: BubbleChartSkeletonProps): import("react").JSX.Element | null;
+declare namespace BubbleChartSkeleton {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface BubbleChartLabelsProps {
+    /**
+     * Smallest radius a bubble may have and still be given its label. Below it
+     * the name is wider than the circle it names.
+     */
+    minRadius?: number;
+    /** Turn a bubble into its label. Defaults to the value at `labelKey`. */
+    format?: (point: BubbleChartPoint) => string;
+    className?: string;
+}
+/**
+ * The names, written inside the circles.
+ *
+ * Real text over the plot rather than SVG text, so they follow the theme's font
+ * and the platform's text scaling. Each one rides the same domain tweens the
+ * circle under it does, so a label never lags the bubble it belongs to.
+ *
+ * A bubble too small to hold its name is left without one. Shrinking the text
+ * to fit would make it unreadable on exactly the bubbles the reader is
+ * squinting at already; the readout names those instead.
+ */
+declare function BubbleChartLabels({ minRadius, format, className, }: BubbleChartLabelsProps): import("react").JSX.Element | null;
+declare namespace BubbleChartLabels {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface BubbleChartXAxisProps {
+    /** How many intervals to divide the axis into. Yields `ticks + 1` labels. */
+    ticks?: number;
+    /** Turn a value into its label. Defaults to a compact number. */
+    format?: (value: number) => string;
+    className?: string;
+}
+/**
+ * The x labels, evenly along the axis.
+ *
+ * Evenly spaced, because this axis is a continuous scale rather than a list of
+ * rows. There is no bubble for a label to sit under.
+ */
+declare function BubbleChartXAxis({ ticks, format, className }: BubbleChartXAxisProps): import("react").JSX.Element;
+declare namespace BubbleChartXAxis {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface BubbleChartYAxisProps {
+    /** How many intervals to divide the axis into. Yields `ticks + 1` labels. */
+    ticks?: number;
+    /** Turn a value into its label. Defaults to a compact number. */
+    format?: (value: number) => string;
+    className?: string;
+}
+/** Value labels down the side, one per grid line. Reserves its own gutter. */
+declare function BubbleChartYAxis({ ticks, format, className }: BubbleChartYAxisProps): import("react").JSX.Element;
+declare namespace BubbleChartYAxis {
+    var displayName: string;
+    var layer: Layer;
+    var axis: "y";
+}
+export interface BubbleChartTooltipProps {
+    /** Float a small readout beside the selected bubble. On by default. */
+    showLabel?: boolean;
+    /** Format the x value for the readout. Defaults to a compact number. */
+    formatX?: (value: number) => string;
+    /** Format the y value for the readout. Defaults to a compact number. */
+    formatY?: (value: number) => string;
+    /** Format the size value for the readout. Defaults to a compact number. */
+    formatSize?: (value: number) => string;
+    /** Floor on the touch target, for a chart whose smallest bubbles are tiny. */
+    hitRadius?: number;
+    className?: string;
+}
+/**
+ * The touch target, the selection it drives, and the readout that follows it.
+ *
+ * A touch picks the nearest bubble whose own circle — or the `hitRadius` floor,
+ * whichever is larger — reaches the finger. Nearest rather than topmost,
+ * because where bubbles overlap the one drawn last is not the one being aimed
+ * at.
+ *
+ * The search runs on the UI thread over flat arrays of already-projected
+ * coordinates, and only the *index* of the winner crosses back into JS, and
+ * only when it changes. A drag across the plot therefore costs a handful of
+ * re-renders rather than one per frame.
+ *
+ * Distances are compared squared. The nearest bubble by distance is the nearest
+ * by distance-squared, and a square root per bubble per frame buys nothing.
+ */
+declare function BubbleChartTooltip({ showLabel, formatX, formatY, formatSize, hitRadius, className, }: BubbleChartTooltipProps): import("react").JSX.Element | null;
+declare namespace BubbleChartTooltip {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface BubbleChartLegendProps extends ViewProps {
+    className?: string;
+    /** Cap on how many bubbles are named. The rest are left to the readout. */
+    limit?: number;
+}
+/**
+ * A swatch and a name per bubble, for a chart whose circles are too small to
+ * carry their own labels.
+ *
+ * Drawn **under** the plot rather than floating in a corner of it. A key that
+ * overlays the drawing area competes with the bubbles for the space they are
+ * plotted in, and on a square chart there is no corner that is reliably empty —
+ * the position of a bubble is the data, so nowhere can be reserved for it.
+ *
+ * It lists rows rather than series, because in this chart a row *is* a
+ * category. Use it instead of `BubbleChart.Labels`, not beside it — the same
+ * names twice is the legend telling the reader what the plot already says.
+ */
+declare function BubbleChartLegend({ className, limit, ...props }: BubbleChartLegendProps): import("react").JSX.Element | null;
+declare namespace BubbleChartLegend {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface BubbleChartHeaderProps extends ViewProps {
+    className?: string;
+    /** Small line above the value — what the chart is of. */
+    title?: string;
+    /** The readout. The largest thing on the card, and the first thing read. */
+    value?: string;
+    /** One muted line under the value — what the area means, usually. */
+    caption?: string;
+    /** Trailing slot — a control, a badge, a range picker. */
+    children?: ReactNode;
+}
+/**
+ * The strip above the plot: what the chart is of, what it currently reads, and
+ * what the size of a circle means.
+ *
+ * The caption earns its place here more than on most charts. Two axes and an
+ * area is three quantities, and a reader who is not told what the area is has
+ * no way to work it out from the picture.
+ *
+ * The value is not derived here. A readout that follows the finger belongs to
+ * whoever owns the data — take it from `onActivePointChange` and pass the
+ * formatted string down.
+ */
+declare function BubbleChartHeader({ className, title, value, caption, children, ...props }: BubbleChartHeaderProps): import("react").JSX.Element;
+declare namespace BubbleChartHeader {
+    var displayName: string;
+    var layer: Layer;
+}
+export declare const BubbleChart: import("react").ForwardRefExoticComponent<BubbleChartProps & import("react").RefAttributes<BubbleChartHandle>> & {
+    Header: typeof BubbleChartHeader;
+    Grid: typeof BubbleChartGrid;
+    Bubbles: typeof BubbleChartBubbles;
+    Labels: typeof BubbleChartLabels;
+    Skeleton: typeof BubbleChartSkeleton;
+    XAxis: typeof BubbleChartXAxis;
+    YAxis: typeof BubbleChartYAxis;
+    Tooltip: typeof BubbleChartTooltip;
+    Legend: typeof BubbleChartLegend;
+};
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/components/bubble-chart/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/bubble-chart/index.tsx"],"names":[],"mappings":"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"}

package/lib/typescript/src/components/pyramid-chart/index.d.ts

@@ -0,0 +1,328 @@
+/**
+ * PyramidChart — two series mirrored about a centre line, drawn and animated on
+ * the UI thread.
+ *
+ * ```tsx
+ * <PyramidChart data={penguins} xDataKey="species">
+ *   <PyramidChart.Grid />
+ *   <PyramidChart.Bar dataKey="male" side="start" />
+ *   <PyramidChart.Bar dataKey="female" side="end" />
+ *   <PyramidChart.XAxis />
+ *   <PyramidChart.YAxis />
+ *   <PyramidChart.Tooltip />
+ * </PyramidChart>
+ * ```
+ *
+ * ## The two wings share one scale
+ *
+ * This is the whole contract, and everything else here follows from it. The
+ * domain is derived from the larger of the two series' extents and used by
+ * both, so a bar twice as long as the one facing it means twice as much.
+ * Scaling each side to its own maximum produces a chart whose halves cannot be
+ * compared — which is the only thing a pyramid is for.
+ *
+ * For the same reason the centre is zero and stays there. There is no `yDomain`
+ * that starts anywhere else, because a wing cropped at its base is a length
+ * that lies.
+ *
+ * ## Lengths, not signed values
+ *
+ * Which side a series is on comes from `side`, not from the sign of its
+ * numbers, so a value is a distance outward from the centre. A negative one has
+ * no direction left to grow in and is drawn as nothing; it still appears in the
+ * readout, so a data error shows up as a gap rather than as a bar pointing the
+ * wrong way.
+ *
+ * ## Where the category names go
+ *
+ * `labelPlacement="above"`, the default, gives each row a line of its own over
+ * its pair of bars. That leaves the two wings meeting in the middle with
+ * nothing standing between them, and puts the name where it is read before the
+ * lengths it belongs to rather than beside them.
+ *
+ * `"center"` puts the names in a gutter between the wings instead — taken off
+ * the bars rather than off the edges, so both wings stay equal — and `"start"`
+ * puts them down the left, for a chart with room to spare on that side.
+ *
+ * ## Every series is one path
+ *
+ * A `Bar` draws all its rectangles as subpaths of a single animated path, split
+ * in two so the row under the finger keeps full ink while the rest fade. Thirty
+ * rows is two animated props a frame rather than thirty.
+ */
+import { type ReactNode } from 'react';
+import { type ViewProps } from 'react-native';
+import { type ChartAccessibilityProps } from '../../primitives/chart-accessibility.js';
+import { type SeriesColorIndex } from '../../utils/chart.js';
+type Layer = 'svg' | 'overlay' | 'header';
+export type PyramidChartStatus = 'loading' | 'ready';
+/** Which wing a series grows into. */
+export type PyramidChartSide = 'start' | 'end';
+/** Where the category names sit. */
+export type PyramidChartLabelPlacement = 'above' | 'center' | 'start';
+export type PyramidChartDatum = Record<string, string | number | null | undefined>;
+/**
+ * The row under the finger, for something rendered *inside* the chart. A
+ * readout in the card's header is outside this provider — use
+ * `onActiveIndexChange` for that.
+ */
+export declare function usePyramidChart(): {
+    activeIndex: number;
+    activePoint: PyramidChartDatum | null;
+    xDataKey: string;
+};
+export interface PyramidChartProps extends ViewProps, ChartAccessibilityProps<PyramidChartDatum> {
+    className?: string;
+    /** The rows. Each one is a band across the chart, with a wing either side. */
+    data: PyramidChartDatum[];
+    /** Key holding the category label. Used by the axis and the readout. */
+    xDataKey?: string;
+    /**
+     * `loading` holds the bars at the centre and grows them out into the real
+     * ones when it turns `ready`. One component throughout, rather than a spinner
+     * swapped for a chart — swapping loses the transition. Add a
+     * `PyramidChart.Skeleton` for something to stand in the plot meanwhile.
+     */
+    status?: PyramidChartStatus;
+    /** Width ÷ height. `1.2` suits three or four rows in a card. */
+    aspectRatio?: number;
+    /** Milliseconds for the bars to grow out on mount. */
+    animationDuration?: number;
+    /** Milliseconds for the scale to settle after the data changes. */
+    domainDuration?: number;
+    /**
+     * Fix the far end of the shared scale instead of deriving it. The near end is
+     * zero either way — a pyramid measures outward from its centre.
+     */
+    maxValue?: number;
+    /**
+     * Where the category names sit. `above`, the default, gives each row a line
+     * of its own over its pair of bars, so the two wings meet in the middle with
+     * nothing standing between them. `center` puts the names in a gutter between
+     * the wings instead, and `start` down the left edge.
+     */
+    labelPlacement?: PyramidChartLabelPlacement;
+    /**
+     * Fraction of each band left empty, `0` to `1`. A fraction rather than a
+     * pixel gap so the proportions hold at any height.
+     */
+    barGap?: number;
+    /** Fixed bar thickness in points. Derived from the band when omitted. */
+    barWidth?: number;
+    /** Corner radius on the outward end of a bar. */
+    cornerRadius?: number;
+    /**
+     * Smallest length a non-zero bar is drawn at, in points. A value that rounds
+     * to nothing still happened, and a bar of zero length says it did not.
+     */
+    minBarLength?: number;
+    /** Opacity of the rows that are not under the finger. */
+    fadedOpacity?: number;
+    /**
+     * The row under the finger as it moves, and `-1`/`null` when it lifts.
+     * Fires when the index changes, not per frame.
+     */
+    onActiveIndexChange?: (index: number, datum: PyramidChartDatum | null) => void;
+    children?: ReactNode;
+}
+/** Imperative handle: re-run the grow-out, for a "replay" control. */
+export interface PyramidChartHandle {
+    replay: () => void;
+}
+export interface PyramidChartGridProps {
+    /** How many lines to draw per wing, not counting the centre. */
+    columns?: number;
+    color?: string;
+    dashArray?: string;
+    opacity?: number;
+    /** Draw the solid line down the middle the wings are measured from. */
+    centreLine?: boolean;
+}
+/**
+ * Lines up the value axis, mirrored, so a bar can be read against a number
+ * rather than only against the bar facing it.
+ *
+ * The centre line is drawn solid and undashed where the others are dashed: it
+ * is not a tick, it is the zero both wings are measured from.
+ */
+declare function PyramidChartGrid({ columns, color, dashArray, opacity, centreLine, }: PyramidChartGridProps): import("react").JSX.Element;
+declare namespace PyramidChartGrid {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface PyramidChartBarProps {
+    /** Column in the data holding this series' values. */
+    dataKey: string;
+    /** Which wing it grows into. */
+    side?: PyramidChartSide;
+    /** Explicit colour. Defaults to the `--color-chart-*` token for `colorIndex`. */
+    color?: string;
+    /**
+     * Which of the five chart tokens to take. Defaults to a different one per
+     * side, so two bars declared with nothing but a `dataKey` and a `side` are
+     * already told apart.
+     */
+    colorIndex?: SeriesColorIndex;
+    /** Corner radius, overriding the chart's. */
+    cornerRadius?: number;
+}
+/**
+ * One wing.
+ *
+ * Drawn as two paths rather than one rectangle per row: the row under the
+ * finger, and everything else. That is the fewest animated props that can still
+ * dim the rest — one path could not, since a path has one opacity, and a view
+ * per bar would be one animated prop per bar for the same picture.
+ */
+declare function PyramidChartBar({ dataKey, side, color, colorIndex, cornerRadius, }: PyramidChartBarProps): import("react").JSX.Element;
+declare namespace PyramidChartBar {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface PyramidChartSkeletonProps {
+    /**
+     * How many placeholder rows to draw. Defaults to one per row of data, and to
+     * five when the data has not arrived — the count is the one thing a loading
+     * chart can be honest about only if it already has the rows.
+     */
+    rows?: number;
+    /** Milliseconds for one pass of the sweep. */
+    duration?: number;
+    color?: string;
+}
+/**
+ * The loading state: equal stubs either side of the centre, with a highlight
+ * travelling across them.
+ *
+ * Equal on purpose. Placeholder wings of differing lengths are a distribution
+ * the reader has no way to tell from the real one until it changes under them,
+ * so these say only how many rows there will be and where the centre is.
+ */
+declare function PyramidChartSkeleton({ rows, duration, color }: PyramidChartSkeletonProps): import("react").JSX.Element | null;
+declare namespace PyramidChartSkeleton {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface PyramidChartXAxisProps {
+    /** How many labels per wing, not counting the zero in the middle. */
+    ticks?: number;
+    /** Format a value for its label. Defaults to a compact number. */
+    format?: (value: number) => string;
+    className?: string;
+}
+/**
+ * The value labels along the bottom, mirrored either side of a zero in the
+ * middle — the same magnitudes twice, because both wings are read outward from
+ * the centre rather than along one continuous axis.
+ *
+ * Real text rather than SVG text, so the labels follow the theme's font and the
+ * platform's text scaling. SVG text does neither.
+ */
+declare function PyramidChartXAxis({ ticks, format, className }: PyramidChartXAxisProps): import("react").JSX.Element | null;
+declare namespace PyramidChartXAxis {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface PyramidChartYAxisProps {
+    /** Turn a row into its label. Defaults to the value at `xDataKey`. */
+    format?: (datum: PyramidChartDatum, index: number) => string;
+    className?: string;
+}
+/**
+ * The category names, one per row.
+ *
+ * `above` puts each name on its own line over the pair of bars it belongs to,
+ * which leaves the two wings meeting in the middle — the name is read first and
+ * the bars are then read outward from a centre nothing is standing in.
+ *
+ * One box per band rather than a spaced column, in every placement: a row owns
+ * a *band*, so names spread evenly would be half a band out at the top and
+ * bottom.
+ */
+declare function PyramidChartYAxis({ format, className }: PyramidChartYAxisProps): import("react").JSX.Element | null;
+declare namespace PyramidChartYAxis {
+    var displayName: string;
+    var layer: Layer;
+    var axis: "y";
+}
+export interface PyramidChartTooltipProps {
+    /** Format one series' value. Defaults to a compact number. */
+    formatValue?: (value: number, key: string) => string;
+    /** Format the readout's heading from the row. Defaults to the value at xDataKey. */
+    formatX?: (datum: PyramidChartDatum) => string;
+    className?: string;
+}
+/**
+ * The readout, and the gesture that drives it.
+ *
+ * There is no crosshair. A bar is already the thing being pointed at, so
+ * highlighting its row and dimming the rest says the same thing without drawing
+ * a line through the chart.
+ *
+ * The hit area is the whole plot. A readout you have to land on the bar to
+ * summon is a readout nobody finds.
+ */
+declare function PyramidChartTooltip({ formatValue, formatX, className, }: PyramidChartTooltipProps): import("react").JSX.Element | null;
+declare namespace PyramidChartTooltip {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface PyramidChartLegendProps extends ViewProps {
+    className?: string;
+    /** Prettier names for the series keys. */
+    labels?: Record<string, string>;
+}
+/** A swatch and a name per series, in the order the series were declared. */
+declare function PyramidChartLegend({ className, labels, ...props }: PyramidChartLegendProps): import("react").JSX.Element | null;
+declare namespace PyramidChartLegend {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface PyramidChartHeaderProps extends ViewProps {
+    className?: string;
+    /** Small line above the value — what the chart is of. */
+    title?: string;
+    /** The readout. The largest thing on the card, and the first thing read. */
+    value?: string;
+    /** One muted line under the value — a period, a comparison, a total. */
+    caption?: string;
+    /** Prettier names for the series keys, as the legend takes. */
+    labels?: Record<string, string>;
+    /**
+     * Draw a swatch and a name per series along the trailing edge. Prefer this to
+     * `PyramidChart.Legend` on a chart that has a header: the legend floats over
+     * the plot, where it competes with the bars for the same corner.
+     */
+    legend?: boolean;
+    /** Trailing slot — a control, a badge, a range picker. Wins over `legend`. */
+    children?: ReactNode;
+}
+/**
+ * The strip above the plot: what the chart is of, what it currently reads, and
+ * what the two colours mean.
+ *
+ * It belongs to the chart rather than to the card around it because it is about
+ * the *plot* — the number changes as a finger moves down the rows, and the
+ * legend is the series list the chart itself is holding.
+ *
+ * The value is not derived here. A readout that follows the finger belongs to
+ * whoever owns the data — take it from `onActiveIndexChange` and pass the
+ * formatted string down.
+ */
+declare function PyramidChartHeader({ className, title, value, caption, labels, legend, children, ...props }: PyramidChartHeaderProps): import("react").JSX.Element;
+declare namespace PyramidChartHeader {
+    var displayName: string;
+    var layer: Layer;
+}
+export declare const PyramidChart: import("react").ForwardRefExoticComponent<PyramidChartProps & import("react").RefAttributes<PyramidChartHandle>> & {
+    Header: typeof PyramidChartHeader;
+    Grid: typeof PyramidChartGrid;
+    Bar: typeof PyramidChartBar;
+    Skeleton: typeof PyramidChartSkeleton;
+    XAxis: typeof PyramidChartXAxis;
+    YAxis: typeof PyramidChartYAxis;
+    Tooltip: typeof PyramidChartTooltip;
+    Legend: typeof PyramidChartLegend;
+};
+export {};
+//# sourceMappingURL=index.d.ts.map