@orianatech/pire 0.9.0 → 0.11.0

package/dist/components/data/BarChart.d.cts

@@ -0,0 +1,32 @@
+import type * as React from 'react';
+import type { ChartBaseProps } from './ChartFrame.cjs';
+export interface BarChartProps extends ChartBaseProps {
+    /**
+     * `horizontal` puts categories down the side, which is what long ERP labels need — product
+     * names and account descriptions do not fit under a vertical bar without turning sideways.
+     * Use `vertical` when the categories are periods and reading left-to-right means time.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Stack the series into one bar per category, for parts of a total.
+     *
+     * Only the first segment and the total are easy to compare across categories, because the
+     * middle segments start at different offsets. If the comparison matters more than the total,
+     * leave this off and let the bars sit side by side.
+     */
+    stacked?: boolean;
+    /**
+     * Print each value beside its bar. Defaults on for a single series — where the chart is a
+     * ranking and the number is half the answer — and off beyond that, where a label per bar
+     * turns into noise. The tooltip and the data table always carry every value.
+     */
+    showValues?: boolean;
+}
+/**
+ * Magnitude and ranking — how big, and in what order.
+ *
+ * Laid out in HTML rather than SVG so category labels are real text: they wrap, truncate and
+ * inherit type tokens, none of which survives a scaled `viewBox`. The bar axis always starts at
+ * zero, since a bar encodes length, and a truncated axis overstates the difference.
+ */
+export declare function BarChart({ categories, series: rawSeries, title, description, formatValue, height, emptyState, showDataTable, orientation, stacked, showValues, className, style, ...rest }: BarChartProps): React.JSX.Element;

package/dist/components/data/BarChart.d.ts

@@ -0,0 +1,33 @@
+import type * as React from 'react';
+import type { ChartBaseProps } from './ChartFrame.js';
+export interface BarChartProps extends ChartBaseProps {
+    /**
+     * `horizontal` puts categories down the side, which is what long ERP labels need — product
+     * names and account descriptions do not fit under a vertical bar without turning sideways.
+     * Use `vertical` when the categories are periods and reading left-to-right means time.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Stack the series into one bar per category, for parts of a total.
+     *
+     * Only the first segment and the total are easy to compare across categories, because the
+     * middle segments start at different offsets. If the comparison matters more than the total,
+     * leave this off and let the bars sit side by side.
+     */
+    stacked?: boolean;
+    /**
+     * Print each value beside its bar. Defaults on for a single series — where the chart is a
+     * ranking and the number is half the answer — and off beyond that, where a label per bar
+     * turns into noise. The tooltip and the data table always carry every value.
+     */
+    showValues?: boolean;
+}
+/**
+ * Magnitude and ranking — how big, and in what order.
+ *
+ * Laid out in HTML rather than SVG so category labels are real text: they wrap, truncate and
+ * inherit type tokens, none of which survives a scaled `viewBox`. The bar axis always starts at
+ * zero, since a bar encodes length, and a truncated axis overstates the difference.
+ */
+export declare function BarChart({ categories, series: rawSeries, title, description, formatValue, height, emptyState, showDataTable, orientation, stacked, showValues, className, style, ...rest }: BarChartProps): React.JSX.Element;
+//# sourceMappingURL=BarChart.d.ts.map

package/dist/components/data/BarChart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BarChart.d.ts","sourceRoot":"","sources":["../../../src/components/data/BarChart.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD;;;;OAIG;IACH,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACxC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,EACvB,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,WAAgC,EACnF,MAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAA0B,EAAE,OAAe,EACpF,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,EACtC,EAAE,aAAa,qBAoFf"}

package/dist/components/data/ChartFrame.d.cts

@@ -0,0 +1,62 @@
+import type * as React from 'react';
+import type { ChartSeries } from './chartGeometry.cjs';
+/** Props every chart shares. Each chart adds its own encoding options on top. */
+export interface ChartBaseProps {
+    /**
+     * What the chart shows, in a sentence. Required: a chart with no accessible name is
+     * an unlabelled image, and the visible title cannot be relied on — charts are often
+     * placed under a heading that already says something different.
+     */
+    'aria-label': string;
+    /** Category axis labels. `series[].values` line up with these by index. */
+    categories: string[];
+    series: ChartSeries[];
+    /** Shown above the plot. With a single series this is what names it, in place of a legend. */
+    title?: React.ReactNode;
+    /** Sits under the title in secondary ink — units, period, source. */
+    description?: React.ReactNode;
+    /**
+     * Formats every number that reaches a human: axis ticks, tooltips, the data table.
+     * Pire does not format — only the app knows the currency, the locale and the precision.
+     */
+    formatValue?: (value: number) => string;
+    /** Plot height in pixels. Width always fills the container. */
+    height?: number;
+    /** Replaces the plot when there is nothing to draw. */
+    emptyState?: React.ReactNode;
+    /** Renders the underlying table visibly beneath the plot, instead of only for screen readers. */
+    showDataTable?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/** One swatch in the legend. What it identifies differs by chart — see `ChartFrameProps.legend`. */
+export interface ChartLegendItem {
+    key: string;
+    label: string;
+    color: string;
+}
+export interface ChartFrameProps extends Pick<ChartBaseProps, 'title' | 'description' | 'categories' | 'series' | 'showDataTable' | 'className' | 'style'> {
+    label: string;
+    formatValue: (value: number) => string;
+    /**
+     * Rendered only when there are at least two entries — one thing needs no key to tell it from
+     * the others, and the title already names it.
+     *
+     * The chart decides what an entry stands for: bars and lines colour by series, a donut colours
+     * by segment. Passing the list ready-made keeps that decision with the chart that made it.
+     */
+    legend?: ChartLegendItem[];
+    children: React.ReactNode;
+}
+/** Legend entries for a chart that colours by series — bars and lines. */
+export declare function seriesLegend(series: ChartSeries[]): ChartLegendItem[];
+/** Falls back to the browser's grouping so large figures stay readable without configuration. */
+export declare const defaultFormatValue: (value: number) => string;
+/**
+ * The shell around every Pire chart: heading, legend, plot, and the data table.
+ *
+ * The table is always in the DOM. A chart summarised in prose tells a screen-reader user what
+ * someone else concluded; the table gives them the same numbers everyone else is looking at.
+ * `showDataTable` only decides whether it is also visible.
+ */
+export declare function ChartFrame({ label, title, description, categories, series, formatValue, legend, showDataTable, className, style, children, }: ChartFrameProps): React.JSX.Element;

package/dist/components/data/ChartFrame.d.ts

@@ -0,0 +1,63 @@
+import type * as React from 'react';
+import type { ChartSeries } from './chartGeometry.js';
+/** Props every chart shares. Each chart adds its own encoding options on top. */
+export interface ChartBaseProps {
+    /**
+     * What the chart shows, in a sentence. Required: a chart with no accessible name is
+     * an unlabelled image, and the visible title cannot be relied on — charts are often
+     * placed under a heading that already says something different.
+     */
+    'aria-label': string;
+    /** Category axis labels. `series[].values` line up with these by index. */
+    categories: string[];
+    series: ChartSeries[];
+    /** Shown above the plot. With a single series this is what names it, in place of a legend. */
+    title?: React.ReactNode;
+    /** Sits under the title in secondary ink — units, period, source. */
+    description?: React.ReactNode;
+    /**
+     * Formats every number that reaches a human: axis ticks, tooltips, the data table.
+     * Pire does not format — only the app knows the currency, the locale and the precision.
+     */
+    formatValue?: (value: number) => string;
+    /** Plot height in pixels. Width always fills the container. */
+    height?: number;
+    /** Replaces the plot when there is nothing to draw. */
+    emptyState?: React.ReactNode;
+    /** Renders the underlying table visibly beneath the plot, instead of only for screen readers. */
+    showDataTable?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/** One swatch in the legend. What it identifies differs by chart — see `ChartFrameProps.legend`. */
+export interface ChartLegendItem {
+    key: string;
+    label: string;
+    color: string;
+}
+export interface ChartFrameProps extends Pick<ChartBaseProps, 'title' | 'description' | 'categories' | 'series' | 'showDataTable' | 'className' | 'style'> {
+    label: string;
+    formatValue: (value: number) => string;
+    /**
+     * Rendered only when there are at least two entries — one thing needs no key to tell it from
+     * the others, and the title already names it.
+     *
+     * The chart decides what an entry stands for: bars and lines colour by series, a donut colours
+     * by segment. Passing the list ready-made keeps that decision with the chart that made it.
+     */
+    legend?: ChartLegendItem[];
+    children: React.ReactNode;
+}
+/** Legend entries for a chart that colours by series — bars and lines. */
+export declare function seriesLegend(series: ChartSeries[]): ChartLegendItem[];
+/** Falls back to the browser's grouping so large figures stay readable without configuration. */
+export declare const defaultFormatValue: (value: number) => string;
+/**
+ * The shell around every Pire chart: heading, legend, plot, and the data table.
+ *
+ * The table is always in the DOM. A chart summarised in prose tells a screen-reader user what
+ * someone else concluded; the table gives them the same numbers everyone else is looking at.
+ * `showDataTable` only decides whether it is also visible.
+ */
+export declare function ChartFrame({ label, title, description, categories, series, formatValue, legend, showDataTable, className, style, children, }: ChartFrameProps): React.JSX.Element;
+//# sourceMappingURL=ChartFrame.d.ts.map

package/dist/components/data/ChartFrame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChartFrame.d.ts","sourceRoot":"","sources":["../../../src/components/data/ChartFrame.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,8FAA8F;IAC9F,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,qEAAqE;IACrE,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACxC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC7B,iGAAiG;IACjG,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;CAC7B;AAED,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAgB,SAC/B,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,aAAa,GAAG,YAAY,GAAG,QAAQ,GAAG,eAAe,GACpF,WAAW,GAAG,OAAO,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACvC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,eAAe,EAAE,CAIrE;AAED,iGAAiG;AACjG,eAAO,MAAM,kBAAkB,UAAW,MAAM,KAAG,MAAgC,CAAC;AAEpF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EACjF,SAAS,EAAE,KAAK,EAAE,QAAQ,GAC3B,EAAE,eAAe,qBAuDjB"}

package/dist/components/data/DonutChart.d.cts

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import type { ChartBaseProps } from './ChartFrame.cjs';
+export interface DonutChartProps extends ChartBaseProps {
+    /**
+     * What sits in the hole. Defaults to the total of every segment, which is the number a
+     * part-to-whole chart is implicitly about. Hovering a segment replaces it with that segment.
+     */
+    centerLabel?: React.ReactNode;
+    /** Caption under the centre figure — "Total", "Invoiced", whatever the total means. */
+    centerCaption?: React.ReactNode;
+    /** Ring thickness in pixels. Thinner reads as a gauge, thicker as a pie. */
+    thickness?: number;
+}
+/**
+ * Part-to-whole, at a glance.
+ *
+ * **Use this only when the reader needs the rough shape of a split, not the ranking.** People
+ * compare angles far worse than they compare lengths, so any question of the form "which is
+ * bigger" or "by how much" is a `BarChart`. Six segments is the ceiling, and it is a ceiling
+ * rather than a target: past three or four the small slices stop being readable at all.
+ *
+ * Unlike the other charts, colour here follows the *segment*, not the series — a donut draws one
+ * series, and its categories are what need telling apart. Pass exactly one series; anything after
+ * the first is ignored, with a dev warning.
+ */
+export declare function DonutChart({ categories, series, title, description, formatValue, height, emptyState, showDataTable, centerLabel, centerCaption, thickness, className, style, ...rest }: DonutChartProps): React.JSX.Element;

package/dist/components/data/DonutChart.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import type { ChartBaseProps } from './ChartFrame.js';
+export interface DonutChartProps extends ChartBaseProps {
+    /**
+     * What sits in the hole. Defaults to the total of every segment, which is the number a
+     * part-to-whole chart is implicitly about. Hovering a segment replaces it with that segment.
+     */
+    centerLabel?: React.ReactNode;
+    /** Caption under the centre figure — "Total", "Invoiced", whatever the total means. */
+    centerCaption?: React.ReactNode;
+    /** Ring thickness in pixels. Thinner reads as a gauge, thicker as a pie. */
+    thickness?: number;
+}
+/**
+ * Part-to-whole, at a glance.
+ *
+ * **Use this only when the reader needs the rough shape of a split, not the ranking.** People
+ * compare angles far worse than they compare lengths, so any question of the form "which is
+ * bigger" or "by how much" is a `BarChart`. Six segments is the ceiling, and it is a ceiling
+ * rather than a target: past three or four the small slices stop being readable at all.
+ *
+ * Unlike the other charts, colour here follows the *segment*, not the series — a donut draws one
+ * series, and its categories are what need telling apart. Pass exactly one series; anything after
+ * the first is ignored, with a dev warning.
+ */
+export declare function DonutChart({ categories, series, title, description, formatValue, height, emptyState, showDataTable, centerLabel, centerCaption, thickness, className, style, ...rest }: DonutChartProps): React.JSX.Element;
+//# sourceMappingURL=DonutChart.d.ts.map

package/dist/components/data/DonutChart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DonutChart.d.ts","sourceRoot":"","sources":["../../../src/components/data/DonutChart.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,cAAc,CAAC;AAKpE,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD;;;OAGG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,uFAAuF;IACvF,aAAa,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAChC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,EACzB,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,WAAgC,EAAE,MAAY,EACtF,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,SAAc,EACrE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,EAC1B,EAAE,eAAe,qBAwFjB"}

package/dist/components/data/LineChart.d.cts

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import type { ChartBaseProps } from './ChartFrame.cjs';
+export interface LineChartProps extends ChartBaseProps {
+    /**
+     * Tint the area under each line. Reads well for one series; with several the fills overlap
+     * and the lower ones are read as smaller than they are, so it is ignored past the first.
+     */
+    showArea?: boolean;
+    /**
+     * Draw a dot at every point. On by default under about twenty points, where the dots show
+     * where the real readings are rather than implying data between them.
+     */
+    showMarkers?: boolean;
+    /**
+     * Let the axis start above zero, so a small movement in a large number stays visible.
+     *
+     * Legitimate for a line, which encodes change rather than length — but it does exaggerate,
+     * so leave it off whenever the size of the number is part of the point.
+     */
+    zoomToData?: boolean;
+}
+/**
+ * Change over time.
+ *
+ * Drawn in SVG at measured pixel coordinates rather than a scaled `viewBox`: scaling a viewBox
+ * to fit stretches the type and turns markers into ellipses. Gaps in a series break the line
+ * instead of interpolating across them — a missing month is not a straight line through it.
+ */
+export declare function LineChart({ categories, series: rawSeries, title, description, formatValue, height, emptyState, showDataTable, showArea, showMarkers, zoomToData, className, style, ...rest }: LineChartProps): React.JSX.Element;

package/dist/components/data/LineChart.d.ts

@@ -0,0 +1,30 @@
+import * as React from 'react';
+import type { ChartBaseProps } from './ChartFrame.js';
+export interface LineChartProps extends ChartBaseProps {
+    /**
+     * Tint the area under each line. Reads well for one series; with several the fills overlap
+     * and the lower ones are read as smaller than they are, so it is ignored past the first.
+     */
+    showArea?: boolean;
+    /**
+     * Draw a dot at every point. On by default under about twenty points, where the dots show
+     * where the real readings are rather than implying data between them.
+     */
+    showMarkers?: boolean;
+    /**
+     * Let the axis start above zero, so a small movement in a large number stays visible.
+     *
+     * Legitimate for a line, which encodes change rather than length — but it does exaggerate,
+     * so leave it off whenever the size of the number is part of the point.
+     */
+    zoomToData?: boolean;
+}
+/**
+ * Change over time.
+ *
+ * Drawn in SVG at measured pixel coordinates rather than a scaled `viewBox`: scaling a viewBox
+ * to fit stretches the type and turns markers into ellipses. Gaps in a series break the line
+ * instead of interpolating across them — a missing month is not a straight line through it.
+ */
+export declare function LineChart({ categories, series: rawSeries, title, description, formatValue, height, emptyState, showDataTable, showArea, showMarkers, zoomToData, className, style, ...rest }: LineChartProps): React.JSX.Element;
+//# sourceMappingURL=LineChart.d.ts.map

package/dist/components/data/LineChart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LineChart.d.ts","sourceRoot":"","sources":["../../../src/components/data/LineChart.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAOnD,MAAM,WAAW,cAAe,SAAQ,cAAc;IACpD;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAoCD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,EACxB,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,WAAgC,EACnF,MAAY,EAAE,UAAU,EAAE,aAAa,EAAE,QAAgB,EAAE,WAAW,EAAE,UAAkB,EAC1F,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,EAC1B,EAAE,cAAc,qBAwIhB"}

package/dist/components/data/chartGeometry.d.cts

@@ -0,0 +1,67 @@
+/**
+ * Scale maths and slot assignment shared by the chart components.
+ *
+ * Kept free of React and of the DOM so the arithmetic — which is where charts go quietly
+ * wrong — can be tested directly rather than through a rendered SVG.
+ */
+/** One measured thing, drawn across every category. */
+export interface ChartSeries {
+    /** Stable across re-renders and across filter changes. Colour follows this, not position. */
+    id: string;
+    /** Shown in the legend, the tooltip and the data table. */
+    label: string;
+    /** One entry per category, in the same order. `null` is a gap in the data, never a zero. */
+    values: (number | null)[];
+    /**
+     * Pin this series to a specific `--viz` slot, 1–6. Without it slots are handed out in
+     * order. Use it when the same entity appears on several charts and must keep one colour.
+     */
+    colorIndex?: number;
+}
+/** How many distinct series colours the palette defines. Validated as a set; do not extend. */
+export declare const VIZ_SLOT_COUNT = 6;
+export interface ChartScale {
+    min: number;
+    max: number;
+    /** Ascending, always including `min` and `max`. */
+    ticks: number[];
+}
+/**
+ * A rounded axis covering `values`.
+ *
+ * `startAtZero` defaults to true because a bar's length is only readable when the axis starts
+ * at zero — a truncated bar axis exaggerates differences, which is the commonest way a chart
+ * misleads. Lines may pass false, since a line encodes change rather than magnitude.
+ */
+export declare function linearScale(values: (number | null | undefined)[], tickCount?: number, startAtZero?: boolean): ChartScale;
+/** Where `value` sits on `scale`, as 0–1 from the axis minimum. */
+export declare function scalePosition(value: number, scale: ChartScale): number;
+/**
+ * The CSS colour for a series.
+ *
+ * Slots are handed out in declaration order and never cycled: past the sixth, identity by
+ * colour alone stops being reliable, so the overflow folds into one "other" neutral instead
+ * of inventing a seventh hue. Aggregate upstream when you have more than six.
+ */
+export declare function seriesColor(series: ChartSeries, index: number): string;
+/** Dev-only nudge: more series than the palette can tell apart is a data-shape problem. */
+export declare function warnOnSlotOverflow(series: ChartSeries[], chartLabel: string): void;
+/**
+ * Dev-only checks specific to a donut, where the failure modes are about shape rather than count.
+ *
+ * Negative values are the important one: an arc length cannot be negative, so a refund or a
+ * reversal silently draws as its own absolute value and the chart reads as confidently wrong.
+ */
+export declare function warnOnDonutShape(series: ChartSeries[], categoryCount: number, chartLabel: string): void;
+/** Sum of a category's values across series, skipping gaps. Used for stacked totals. */
+export declare function stackTotal(series: ChartSeries[], categoryIndex: number): number;
+/** Every plotted number in one flat list — what the scale is derived from. */
+export declare function flatValues(series: ChartSeries[]): (number | null)[];
+/**
+ * Trims each series to the category count.
+ *
+ * A series longer than the axis would otherwise plot points past the last category, stacked on
+ * top of each other at an undefined position. Shorter series need no padding — reading past the
+ * end already yields `undefined`, which every call site treats as a gap.
+ */
+export declare function alignToCategories(series: ChartSeries[], categoryCount: number): ChartSeries[];

package/dist/components/data/chartGeometry.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Scale maths and slot assignment shared by the chart components.
+ *
+ * Kept free of React and of the DOM so the arithmetic — which is where charts go quietly
+ * wrong — can be tested directly rather than through a rendered SVG.
+ */
+/** One measured thing, drawn across every category. */
+export interface ChartSeries {
+    /** Stable across re-renders and across filter changes. Colour follows this, not position. */
+    id: string;
+    /** Shown in the legend, the tooltip and the data table. */
+    label: string;
+    /** One entry per category, in the same order. `null` is a gap in the data, never a zero. */
+    values: (number | null)[];
+    /**
+     * Pin this series to a specific `--viz` slot, 1–6. Without it slots are handed out in
+     * order. Use it when the same entity appears on several charts and must keep one colour.
+     */
+    colorIndex?: number;
+}
+/** How many distinct series colours the palette defines. Validated as a set; do not extend. */
+export declare const VIZ_SLOT_COUNT = 6;
+export interface ChartScale {
+    min: number;
+    max: number;
+    /** Ascending, always including `min` and `max`. */
+    ticks: number[];
+}
+/**
+ * A rounded axis covering `values`.
+ *
+ * `startAtZero` defaults to true because a bar's length is only readable when the axis starts
+ * at zero — a truncated bar axis exaggerates differences, which is the commonest way a chart
+ * misleads. Lines may pass false, since a line encodes change rather than magnitude.
+ */
+export declare function linearScale(values: (number | null | undefined)[], tickCount?: number, startAtZero?: boolean): ChartScale;
+/** Where `value` sits on `scale`, as 0–1 from the axis minimum. */
+export declare function scalePosition(value: number, scale: ChartScale): number;
+/**
+ * The CSS colour for a series.
+ *
+ * Slots are handed out in declaration order and never cycled: past the sixth, identity by
+ * colour alone stops being reliable, so the overflow folds into one "other" neutral instead
+ * of inventing a seventh hue. Aggregate upstream when you have more than six.
+ */
+export declare function seriesColor(series: ChartSeries, index: number): string;
+/** Dev-only nudge: more series than the palette can tell apart is a data-shape problem. */
+export declare function warnOnSlotOverflow(series: ChartSeries[], chartLabel: string): void;
+/**
+ * Dev-only checks specific to a donut, where the failure modes are about shape rather than count.
+ *
+ * Negative values are the important one: an arc length cannot be negative, so a refund or a
+ * reversal silently draws as its own absolute value and the chart reads as confidently wrong.
+ */
+export declare function warnOnDonutShape(series: ChartSeries[], categoryCount: number, chartLabel: string): void;
+/** Sum of a category's values across series, skipping gaps. Used for stacked totals. */
+export declare function stackTotal(series: ChartSeries[], categoryIndex: number): number;
+/** Every plotted number in one flat list — what the scale is derived from. */
+export declare function flatValues(series: ChartSeries[]): (number | null)[];
+/**
+ * Trims each series to the category count.
+ *
+ * A series longer than the axis would otherwise plot points past the last category, stacked on
+ * top of each other at an undefined position. Shorter series need no padding — reading past the
+ * end already yields `undefined`, which every call site treats as a gap.
+ */
+export declare function alignToCategories(series: ChartSeries[], categoryCount: number): ChartSeries[];
+//# sourceMappingURL=chartGeometry.d.ts.map

package/dist/components/data/chartGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chartGeometry.d.ts","sourceRoot":"","sources":["../../../src/components/data/chartGeometry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,6FAA6F;IAC7F,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,MAAM,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+FAA+F;AAC/F,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAYD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EAAE,SAAS,SAAI,EAAE,WAAW,UAAO,GACvE,UAAU,CA4BZ;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAGtE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGtE;AAWD,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CASlF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAC/D,IAAI,CAmBN;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAEnE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,WAAW,EAAE,CAI7F"}

package/dist/components/forms/DateRangePicker.d.cts

@@ -0,0 +1,55 @@
+import type * as React from 'react';
+import type { DateValue } from 'react-aria-components';
+export interface DateRange {
+    start: DateValue;
+    end: DateValue;
+}
+export interface DateRangePreset {
+    id: string;
+    label: string;
+    /** The app computes the range: Pire cannot know when a customer's fiscal year starts. */
+    range: () => DateRange;
+}
+export interface DateRangePickerProps {
+    label?: React.ReactNode;
+    value?: DateRange | null;
+    defaultValue?: DateRange | null;
+    onChange?: (value: DateRange | null) => void;
+    minValue?: DateValue;
+    maxValue?: DateValue;
+    /** Return true for dates that cannot be picked — blocked periods, closed books. */
+    isDateUnavailable?: (date: DateValue) => boolean;
+    /**
+     * Longest range the caller accepts, in days. Exceeding it marks the field invalid so
+     * `errorMessage` shows — the wording is the app's, since only it knows the limit's reason.
+     *
+     * Days rather than a duration: "12 months" is not a fixed number of days, so pick the bound
+     * that matches your rule rather than expecting a calendar-aware one.
+     */
+    maxRangeDays?: number;
+    /** Shortcuts beside the calendar: "This month", "Last 30 days". */
+    presets?: DateRangePreset[];
+    description?: React.ReactNode;
+    errorMessage?: React.ReactNode;
+    isInvalid?: boolean;
+    isDisabled?: boolean;
+    isReadOnly?: boolean;
+    isRequired?: boolean;
+    size?: 'sm' | 'md' | 'lg';
+    fullWidth?: boolean;
+    /** HTML submit names for the two ends. */
+    startName?: string;
+    endName?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/** Whole days between the two ends, inclusive of both. */
+export declare function rangeLengthInDays(range: DateRange): number;
+/**
+ * Two dates that belong together — the default filter on 24 ERP screens.
+ *
+ * Built on React Aria's `DateRangePicker`, which supplies the segmented ends, the ordering rules
+ * between them, and locale-driven segment order. Wrap the app in `I18nProvider` to pin a locale:
+ * `es-PY` reads dd/mm/yyyy and `en-US` mm/dd/yyyy off the same value.
+ */
+export declare function DateRangePicker({ label, description, errorMessage, maxRangeDays, presets, size, fullWidth, startName, endName, className, style, ...rest }: DateRangePickerProps): React.JSX.Element;

package/dist/components/forms/DateRangePicker.d.ts

@@ -0,0 +1,56 @@
+import type * as React from 'react';
+import type { DateValue } from 'react-aria-components';
+export interface DateRange {
+    start: DateValue;
+    end: DateValue;
+}
+export interface DateRangePreset {
+    id: string;
+    label: string;
+    /** The app computes the range: Pire cannot know when a customer's fiscal year starts. */
+    range: () => DateRange;
+}
+export interface DateRangePickerProps {
+    label?: React.ReactNode;
+    value?: DateRange | null;
+    defaultValue?: DateRange | null;
+    onChange?: (value: DateRange | null) => void;
+    minValue?: DateValue;
+    maxValue?: DateValue;
+    /** Return true for dates that cannot be picked — blocked periods, closed books. */
+    isDateUnavailable?: (date: DateValue) => boolean;
+    /**
+     * Longest range the caller accepts, in days. Exceeding it marks the field invalid so
+     * `errorMessage` shows — the wording is the app's, since only it knows the limit's reason.
+     *
+     * Days rather than a duration: "12 months" is not a fixed number of days, so pick the bound
+     * that matches your rule rather than expecting a calendar-aware one.
+     */
+    maxRangeDays?: number;
+    /** Shortcuts beside the calendar: "This month", "Last 30 days". */
+    presets?: DateRangePreset[];
+    description?: React.ReactNode;
+    errorMessage?: React.ReactNode;
+    isInvalid?: boolean;
+    isDisabled?: boolean;
+    isReadOnly?: boolean;
+    isRequired?: boolean;
+    size?: 'sm' | 'md' | 'lg';
+    fullWidth?: boolean;
+    /** HTML submit names for the two ends. */
+    startName?: string;
+    endName?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/** Whole days between the two ends, inclusive of both. */
+export declare function rangeLengthInDays(range: DateRange): number;
+/**
+ * Two dates that belong together — the default filter on 24 ERP screens.
+ *
+ * Built on React Aria's `DateRangePicker`, which supplies the segmented ends, the ordering rules
+ * between them, and locale-driven segment order. Wrap the app in `I18nProvider` to pin a locale:
+ * `es-PY` reads dd/mm/yyyy and `en-US` mm/dd/yyyy off the same value.
+ */
+export declare function DateRangePicker({ label, description, errorMessage, maxRangeDays, presets, size, fullWidth, startName, endName, className, style, ...rest }: DateRangePickerProps): React.JSX.Element;
+//# sourceMappingURL=DateRangePicker.d.ts.map

package/dist/components/forms/DateRangePicker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DateRangePicker.d.ts","sourceRoot":"","sources":["../../../src/components/forms/DateRangePicker.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAMpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAKvD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,SAAS,CAAC;IACjB,GAAG,EAAE,SAAS,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,KAAK,EAAE,MAAM,SAAS,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB,YAAY,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,KAAK,IAAI,CAAC;IAC7C,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC;IACjD;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;CAC7B;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAG1D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,IAAW,EAAE,SAAgB,EACtF,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,EAC9C,EAAE,oBAAoB,qBAiFtB"}

package/dist/components/forms/Input.d.cts

@@ -6,6 +6,11 @@ export interface InputProps {
     /** Receives the raw string value. */
     onChange?: (value: string) => void;
     placeholder?: string;
+    /**
+     * `date` is accepted for compatibility but reaches for the browser's native picker, which
+     * ignores the token palette and behaves differently per browser. Use `DatePicker`, or
+     * `DateRangePicker` for two ends.
+     */
     type?: 'text' | 'search' | 'email' | 'number' | 'date' | 'password' | 'tel' | 'url';
     /** Leading icon slug — "search", "calendar", "hash". */
     icon?: string;

package/dist/components/forms/Input.d.ts

@@ -6,6 +6,11 @@ export interface InputProps {
     /** Receives the raw string value. */
     onChange?: (value: string) => void;
     placeholder?: string;
+    /**
+     * `date` is accepted for compatibility but reaches for the browser's native picker, which
+     * ignores the token palette and behaves differently per browser. Use `DatePicker`, or
+     * `DateRangePicker` for two ends.
+     */
     type?: 'text' | 'search' | 'email' | 'number' | 'date' | 'password' | 'tel' | 'url';
     /** Leading icon slug — "search", "calendar", "hash". */
     icon?: string;

package/dist/components/forms/Input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Input.d.ts","sourceRoot":"","sources":["../../../src/components/forms/Input.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAKpC,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,GAAG,KAAK,CAAC;IACpF,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,MAAM,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACzB,wEAAwE;IACxE,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,QAAQ,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;CACxC;AAED;oDACoD;AACpD,wBAAgB,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,IAAW,EAAE,OAAO,EAC1F,SAAgB,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,UAAU,qBAmB9E"}
+{"version":3,"file":"Input.d.ts","sourceRoot":"","sources":["../../../src/components/forms/Input.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAKpC,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,GAAG,KAAK,CAAC;IACpF,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,MAAM,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACzB,wEAAwE;IACxE,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,QAAQ,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;CACxC;AAED;oDACoD;AACpD,wBAAgB,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,IAAW,EAAE,OAAO,EAC1F,SAAgB,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,UAAU,qBAmB9E"}