@krizaka/charts 0.0.0-stage → 0.1.0

package/dist/native.d.ts

@@ -0,0 +1,300 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { ViewStyle } from 'react-native';
+
+interface ChartLabels {
+    /** The button that shows the data table. */
+    showData: string;
+    /** The button that hides it. */
+    hideData: string;
+    /** The caption of the data table: `{title}`. */
+    tableCaption: string;
+    /** The export buttons. */
+    exportPng: string;
+    exportSvg: string;
+    exportCsv: string;
+    /** Announced while the data loads. */
+    loading: string;
+    /** Shown when there is nothing to draw. */
+    empty: string;
+    /** Shown when the data could not be loaded. */
+    error: string;
+    /** The keyboard hint, read once when the plot takes the focus. */
+    keyboardHint: string;
+    /** The role description of the plot (`chart`). */
+    roleDescription: string;
+    /** Summary pieces. `{kind}` is the chart's name (`Line chart`), `{count}` a number of points or series. */
+    summaryIntro: string;
+    summarySeries: string;
+    summaryRange: string;
+    summaryTrendUp: string;
+    summaryTrendDown: string;
+    summaryTrendFlat: string;
+    summaryTotal: string;
+    summaryThreshold: string;
+    summaryShare: string;
+    /** Scatter: the correlation of x and y (Pearson's r). */
+    summaryCorrelation: string;
+    /** Funnel: from one stage to the next, and from the first to the last. */
+    summaryConversion: string;
+    summaryOverall: string;
+    /** Heatmap, calendar: the largest cell and the number of cells with a value. */
+    summaryPeak: string;
+    summaryActive: string;
+    /** Candlestick: the period's range. */
+    summaryOhlc: string;
+    /** The names of the charts, read first in the summary. */
+    kinds: Record<ChartKind, string>;
+    /** The column of the values, when the chart has no value label. */
+    value: string;
+    /** The column of the categories in the data table, when the chart has no x label. */
+    category: string;
+    /** The total row of a stacked chart, a pie, a funnel. */
+    total: string;
+    /** What a missing value reads as. */
+    noValue: string;
+}
+type ChartKind = "line" | "area" | "bar" | "pie" | "donut" | "gauge" | "sparkline" | "radar" | "heatmap" | "calendar" | "sankey" | "funnel" | "candlestick" | "treemap" | "scatter" | "map" | "globe" | "chart";
+declare const DEFAULT_LABELS: ChartLabels;
+/** The words an app or a chart passes: any of them, and any of the chart names. */
+type ChartLabelsInput = Partial<Omit<ChartLabels, "kinds">> & {
+    kinds?: Partial<Record<ChartKind, string>>;
+};
+
+/** A row of data: any object; the chart reads the fields its `x`, `y` and `series` name. */
+type Datum = object;
+/** A field of a row (`"month"`) or a function that reads it. */
+type Accessor<T, V> = (keyof T & string) | ((datum: T, index: number) => V);
+/** A Krizaka brand: its palette leads with the brand's own hue (Krizaka blue, Orazaka orange, Orochia violet). */
+type BrandId = "krizaka" | "orazaka" | "orochia";
+/** A BCP 47 locale (`"en-US"`, `"fr-FR"`), always explicit: server and client write the same figures. */
+type Locale = string | readonly string[];
+/**
+ * How a value is written, through `@krizaka/intl`:
+ * - `"number"` (default) `12,345.6`, `"integer"` `12,346`, `"compact"` `12.3K`, `"percent"` (a ratio: `0.42` → `42%`);
+ * - `{ style: "money", currency }`: the values are **integer minor units** (cents), as the ledger stores them;
+ * - `{ style: "unit", unit }`: an `Intl` unit (`"second"`, `"megabyte"`);
+ * - a function, for anything else.
+ */
+type ValueFormat = "number" | "integer" | "compact" | "percent" | {
+    readonly style: "money";
+    readonly currency: string;
+    readonly compact?: boolean;
+} | {
+    readonly style: "unit";
+    readonly unit: string;
+    readonly compact?: boolean;
+} | {
+    readonly style: "number";
+    readonly options: Intl.NumberFormatOptions;
+} | ((value: number, locale: Locale) => string);
+/**
+ * How a category of the x axis is written. A category that is a `Date`, an epoch or an ISO date (`"2026-04"`,
+ * `"2026-04-12"`) is a date: `"month"` (`Apr 2026`), `"day"` (`Apr 12`), `"date"` (`Apr 12, 2026`), `"time"`
+ * (`14:30`), `"datetime"`, `"year"`. `"text"` writes it as is (the default for anything that is not a date).
+ */
+type CategoryFormat = "text" | "year" | "month" | "day" | "date" | "time" | "datetime" | ((category: unknown, locale: Locale) => string);
+/** A series to draw: the field holding its values and the words that name it. */
+interface SeriesSpec<T extends Datum = Datum> {
+    /** The field (or a function) holding the series' value in each row. */
+    readonly key: Accessor<T, number | null | undefined>;
+    /** Its name: in the legend, the tooltip, the data table and the summary. */
+    readonly label: string;
+    /** A colour role instead of the next palette slot: `"accent"`, a status (`"success"`…) or a `var(--…)`. */
+    readonly color?: SeriesColor;
+    /** Draw it dashed (a forecast, a previous period). Lines and areas only. */
+    readonly dashed?: boolean;
+}
+/** A status or brand role a series, a threshold or a marker may wear instead of a palette slot. */
+type Tone = "neutral" | "accent" | "success" | "warning" | "danger" | "info";
+/** A palette slot (1–8), a tone, or any CSS colour (`var(--kz-…)` preferred). */
+type SeriesColor = Tone | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | (string & {});
+/** A horizontal line at a value: a goal, a payout threshold, a quota. */
+interface Threshold {
+    readonly value: number;
+    /** What it means, written beside the line and in the summary: “Payout threshold”. */
+    readonly label: string;
+    /** Default `"neutral"`; a goal reads well in `"success"`, a limit in `"danger"`. */
+    readonly tone?: Tone;
+}
+/** A vertical marker at a category: an event worth pointing at (“Campaign launch”). */
+interface Marker {
+    /** The category it marks, as in the data (`"2026-04"`). */
+    readonly x: unknown;
+    readonly label: string;
+    readonly tone?: Tone;
+}
+/** What a series says about itself, for the written summary. */
+interface SeriesSummary {
+    readonly label: string;
+    readonly count: number;
+    readonly min: {
+        readonly value: number;
+        readonly category: string;
+    } | null;
+    readonly max: {
+        readonly value: number;
+        readonly category: string;
+    } | null;
+    readonly first: number | null;
+    readonly last: number | null;
+    readonly total: number;
+    /** `last / first − 1`, or null when it cannot be said (no first value, a first value of 0). */
+    readonly change: number | null;
+    readonly trend: "up" | "down" | "flat" | "none";
+}
+
+type Curve = "linear" | "monotone" | "step";
+
+type Mode = "dark" | "light";
+
+/** The colour roles a chart reads (a subset of @krizaka/tokens/native's `Theme`; `useTheme().theme` of @krizaka/ui/native fits). */
+type ChartTheme = {
+    readonly surface1: string;
+    readonly surface2: string;
+    readonly surface3: string;
+    readonly borderSubtle: string;
+    readonly borderDefault: string;
+    readonly textPrimary: string;
+    readonly textSecondary: string;
+    readonly textMuted: string;
+    readonly accent: string;
+    readonly success: string;
+    readonly warning: string;
+    readonly danger: string;
+    readonly info: string;
+};
+interface NativeChartsSettings {
+    /** The locale of every figure and date. Default `"en-US"`. */
+    locale?: Locale;
+    /** The brand whose palette leads. Default Krizaka. */
+    brand?: BrandId;
+    /** The words: the readout, the summary. */
+    labels?: ChartLabelsInput;
+    /** Dark or light. Default: the device's (pass `useTheme().scheme` of @krizaka/ui/native to follow the app). */
+    scheme?: Mode;
+    /** The app's colour roles (`useTheme().theme` of @krizaka/ui/native): a product's brand overrides apply. */
+    theme?: Partial<ChartTheme>;
+}
+/** Sets the locale, brand, words, scheme and theme of every chart below it. */
+declare function ChartsProvider({ children, ...settings }: NativeChartsSettings & {
+    children: ReactNode;
+}): react.JSX.Element;
+interface NativeFrameProps extends NativeChartsSettings {
+    /** What the chart shows: its heading and accessible name. */
+    title: string;
+    /** Hide the heading (it stays the accessible name). */
+    hideTitle?: boolean;
+    /** The plot's height. */
+    height?: number;
+    /** The data is on its way. */
+    loading?: boolean;
+    /** Shown instead of the plot when there is nothing to draw. Default: the `empty` label. */
+    empty?: ReactNode;
+    /** The style of the chart's container (layout only: colours come from the theme). */
+    style?: ViewStyle;
+}
+
+interface NativeCartesianProps<T extends Datum> extends NativeFrameProps {
+    /** The rows, in the order of the x axis. */
+    data: readonly T[];
+    /** The field (or function) of the category. */
+    x?: Accessor<T, unknown>;
+    /** A single series: its field. */
+    y?: Accessor<T, number | null | undefined>;
+    /** The name of the single `y` series. */
+    yLabel?: string;
+    /** The series, each with its field and name. */
+    series?: readonly SeriesSpec<T>[];
+    /** How the values are written. */
+    format?: ValueFormat;
+    /** How the categories are written. */
+    xFormat?: CategoryFormat;
+    /** Horizontal lines at a value. */
+    thresholds?: readonly Threshold[];
+}
+interface NativeLineChartProps<T extends Datum> extends NativeCartesianProps<T> {
+    /** `monotone` (default), `linear` or `step`. */
+    curve?: Curve;
+}
+/** Change over time (React Native): one line per series. */
+declare function LineChart<T extends Datum>({ curve, ...props }: NativeLineChartProps<T>): react.JSX.Element;
+interface NativeAreaChartProps<T extends Datum> extends NativeLineChartProps<T> {
+    /** Stack the series: the parts of a total over time. */
+    stacked?: boolean;
+}
+interface NativeBarChartProps<T extends Datum> extends NativeCartesianProps<T> {
+    /** Stack the series in one bar per category; default: grouped side by side. */
+    stacked?: boolean;
+}
+/** A volume over time (React Native): a line over a wash; `stacked` for the parts of a total. */
+declare function AreaChart<T extends Datum>({ curve, stacked, ...props }: NativeAreaChartProps<T>): react.JSX.Element;
+/** Amounts across categories (React Native): grouped or `stacked` bars. */
+declare function BarChart<T extends Datum>({ stacked, ...props }: NativeBarChartProps<T>): react.JSX.Element;
+
+interface NativePieChartProps<T extends Datum> extends NativeFrameProps {
+    /** One row per part. */
+    data: readonly T[];
+    /** The field naming the part. */
+    label: Accessor<T, string>;
+    /** The field of its amount. */
+    value: Accessor<T, number>;
+    /** How the amounts are written. */
+    format?: ValueFormat;
+    /** A ring with the total in its hole. */
+    donut?: boolean;
+    /** The words under the total of a donut. */
+    centerLabel?: string;
+    /** At most this many slices; the rest fold into `otherLabel`. Default 6. */
+    maxSlices?: number;
+    /** The name of the folded slice. Default “Other”. */
+    otherLabel?: string;
+}
+/** Part of a whole (React Native). */
+declare function PieChart<T extends Datum>(props: NativePieChartProps<T>): react.JSX.Element;
+/** A pie with a hole (React Native). */
+declare function DonutChart<T extends Datum>(props: Omit<NativePieChartProps<T>, "donut">): react.JSX.Element;
+interface NativeGaugeProps extends NativeFrameProps {
+    /** The value. */
+    value: number;
+    /** The start of the range. Default 0. */
+    min?: number;
+    /** The end of the range. Default 100. */
+    max?: number;
+    /** How the value is written. */
+    format?: ValueFormat;
+    /** The words under the value. */
+    caption?: string;
+    /** A tick on the arc: the objective. */
+    target?: Threshold;
+    /** Zones: the value takes the tone of the zone it is in. */
+    zones?: readonly {
+        readonly to: number;
+        readonly tone: Tone;
+        readonly label?: string;
+    }[];
+    /** The tone of the value without zones. Default `"accent"`. */
+    tone?: Tone;
+}
+/** One figure against its range (React Native). */
+declare function Gauge(props: NativeGaugeProps): react.JSX.Element;
+interface NativeSparklineProps extends Omit<NativeFrameProps, "hideTitle"> {
+    /** The values, oldest first (`null` for a gap). */
+    data: readonly (number | null)[];
+    /** The labels of the values (dates), for the summary. */
+    categories?: readonly unknown[];
+    /** `line` (default), `area` or `bar`. */
+    variant?: "line" | "area" | "bar";
+    /** A palette slot, a tone or a colour. */
+    color?: SeriesColor;
+    /** Colour by the trend (success up, danger down; `"inverse"` for costs). */
+    trendTone?: boolean | "inverse";
+    /** How the values are written in the summary. */
+    format?: ValueFormat;
+    /** A fixed width. Default: the container's. */
+    width?: number;
+}
+/** A word-sized trend (React Native). */
+declare function Sparkline(props: NativeSparklineProps): react.JSX.Element;
+
+export { type Accessor, AreaChart, BarChart, type BrandId, type CategoryFormat, type ChartLabels, type ChartLabelsInput, type ChartTheme, ChartsProvider, DEFAULT_LABELS, type Datum, DonutChart, Gauge, LineChart, type Locale, type Marker, type NativeAreaChartProps, type NativeBarChartProps, type NativeCartesianProps, type NativeChartsSettings, type NativeFrameProps, type NativeGaugeProps, type NativeLineChartProps, type NativePieChartProps, type NativeSparklineProps, PieChart, type SeriesColor, type SeriesSpec, type SeriesSummary, Sparkline, type Threshold, type Tone, type ValueFormat };