@umriss-ui/charts 0.42.0 → 0.43.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { CSSProperties } from 'react';
+import { HTMLAttributes } from 'react';
 import { ReactNode } from 'react';
+import { Ref } from 'react';
 
 /** The props of `Area`. */
 export declare interface AreaProps<T> {
@@ -20,9 +22,9 @@ export declare interface AreaProps<T> {
      unnamed series is a colour nobody can look up.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** The value as the tooltip writes it.
+    /** The value as the tooltip writes it, as a function or `NumberOptions`.
      @default the y axis' `tickFormat`, else the built-in number format */
-    format?: (value: number) => string;
+    format?: ValueFormat;
     /** Any CSS colour value.
      @default the palette's `--uc-series-N` */
     color?: string;
@@ -111,7 +113,7 @@ export declare interface AxisConfig<T = unknown> {
     accessor?: (d: T, index: number) => AxisValue;
     label?: string;
     tickCount?: number;
-    tickFormat?: (v: number) => string;
+    tickFormat?: ValueFormat;
     /** "visible" is a y axis' only: the extent of what its series show inside
      their x axis' domain. */
     domain: "nice" | "data" | "visible" | readonly [number, number];
@@ -184,9 +186,9 @@ export declare interface BarProps<T> {
      unnamed series is a colour nobody can look up.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** The value as the tooltip writes it.
+    /** The value as the tooltip writes it, as a function or `NumberOptions`.
      @default the y axis' `tickFormat`, else the built-in number format */
-    format?: (value: number) => string;
+    format?: ValueFormat;
     /** Any CSS colour value.
      @default the palette's `--uc-series-N` */
     color?: string;
@@ -323,9 +325,9 @@ export declare interface BoxPlotProps<T> {
     /** The name in legend and tooltip. Without one a warning stands in DEV.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** Every number of the box as the tooltip and the table write it.
+    /** Every number of the box as the tooltip and the table write it, as a function or `NumberOptions`.
      @default the y axis' `tickFormat`, else the built-in number format */
-    format?: (value: number) => string;
+    format?: ValueFormat;
     /** Any CSS colour value.
      @default the palette's `--uc-series-N` */
     color?: string;
@@ -444,7 +446,10 @@ export declare interface ChartPerf {
 
 /** The props of `Chart`. Its rows are not among them: `useChart(rows)` binds
  them (ADR-0048). */
-export declare interface ChartProps {
+export declare interface ChartProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** The root element, the `<div>` that `className`, `style`, `id` and the
+     `data-*` attributes reach. */
+    ref?: Ref<HTMLDivElement>;
     /** Width in CSS pixels, or `"100%"` for the host's: the chart measures its
      host and follows it through a ResizeObserver.
      @default "100%" */
@@ -458,7 +463,9 @@ export declare interface ChartProps {
     height?: number;
     /** Outer spacing of the plot area in CSS pixels. */
     padding?: number | Partial<Padding>;
-    /** Required in DEV through a warning. */
+    /** Accessible name of the plot. Without a name, `aria-label` or
+     `aria-labelledby`, the chart warns in development.
+     @deprecated since 0.43 - use `aria-label`. */
     ariaLabel?: string;
     /** Goes to the root element, as it does everywhere in this workspace. */
     className?: string;
@@ -607,8 +614,9 @@ declare interface CommonProps {
     /** Label of a tick. Compared by its source text: one that reads a changed
      closure variable under the same text does not relabel the axis - give it
      a new text or remount. A bound `Intl.NumberFormat#format` is compared by
-     identity. */
-    tickFormat?: (v: number) => string;
+     identity. Or `NumberOptions`: Intl's options in the wording's locale,
+     compared by value; the step's places stay unless the options set digits. */
+    tickFormat?: ValueFormat;
     /** Grid lines.
      @default only on the first axis of its orientation */
     grid?: boolean;
@@ -655,9 +663,9 @@ export declare interface ControlChartProps<T> {
      unnamed series is a colour nobody can look up.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** The value as the tooltip writes it - on the line and on the violations.
+    /** The value as the tooltip writes it - on the line and on the violations., as a function or `NumberOptions`.
      @default the y axis' `tickFormat`, else the built-in number format */
-    format?: (value: number) => string;
+    format?: ValueFormat;
     /** Any CSS colour value.
      @default the palette's `--uc-series-N` */
     color?: string;
@@ -928,9 +936,9 @@ export declare interface LineProps<T> {
      unnamed series is a colour nobody can look up.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** The value as the tooltip writes it.
+    /** The value as the tooltip writes it, as a function or `NumberOptions`.
      @default the y axis' `tickFormat`, else the built-in number format */
-    format?: (value: number) => string;
+    format?: ValueFormat;
     /** Any CSS colour value.
      @default the palette's `--uc-series-N` */
     color?: string;
@@ -1041,10 +1049,10 @@ export declare interface MatrixProps<T> {
      unnamed series is a colour nobody can look up.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** The level as the tooltip writes it. The y axis' `tickFormat` writes the
+    /** The level as the tooltip writes it, as a function or `NumberOptions`. The y axis' `tickFormat` writes the
      row, not the level.
      @default the built-in number format */
-    format?: (value: number) => string;
+    format?: ValueFormat;
 }
 
 /** A `Matrix` as the chart holds it once registered: its base accessor is the
@@ -1067,6 +1075,14 @@ export declare type NumberField<T> = NoInfer<{
     [K in keyof T & string]-?: T[K] extends number | null | undefined ? K : never;
 }[keyof T & string]>;
 
+/** The options of `Intl.NumberFormat`, plus `decimals` for a fixed number of
+ places (minimum and maximum alike; an Intl digit option given beside it
+ wins). The same shape as core's, declared here because the charts import
+ nothing. */
+export declare interface NumberOptions extends Intl.NumberFormatOptions {
+    decimals?: number;
+}
+
 /** A lane is named or given by its edges: the compiler refuses both at once.
  Beside the props and not in them, so that `StateBandProps` stays an
  interface another can extend. */
@@ -1267,9 +1283,9 @@ export declare interface ScatterProps<T> {
      unnamed series is a colour nobody can look up.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** The value as the tooltip writes it.
+    /** The value as the tooltip writes it, as a function or `NumberOptions`.
      @default the y axis' `tickFormat`, else the built-in number format */
-    format?: (value: number) => string;
+    format?: ValueFormat;
     /** Any CSS colour value.
      @default the palette's `--uc-series-N` */
     color?: string;
@@ -1300,8 +1316,9 @@ export declare interface SeriesBase<T = unknown> {
     yAxisId: string;
     name?: string;
     /** The value in the tooltip; before the y axis' `tickFormat`. Compared by its
-     source text, as an accessor is. */
-    format?: (value: number) => string;
+     source text, as an accessor is. Or `NumberOptions`: Intl's options in the
+     wording's locale, compared by value. */
+    format?: ValueFormat;
     color?: string;
     /** A role instead of a colour value: the theme resolves it, in both themes.
      For series that mean something rather than just being the next one - the
@@ -1505,6 +1522,10 @@ export declare function useChart<Z>(rows: readonly Z[], options?: ChartOptions<Z
  by its name, or a function, compared by its source text (`ValueFunction`). */
 export declare type Value<T> = NumberField<T> | ValueFunction<T>;
 
+/** A value format: a function, or Intl's options written in the chart's
+ wording's locale. */
+export declare type ValueFormat = ((value: number) => string) | NumberOptions;
+
 /** A **value** computed from the row - the function form of `Value`.
  Compared by its source text, not its identity - an inline function is new
  on every render. Known limit: one that reads a