@umriss-ui/charts 0.43.0 → 0.45.0

package/dist/de.d.ts

@@ -38,6 +38,12 @@ declare interface ChartsWording {
     walkHelp: string;
     /** The key that reports the Active point - only where `onSelect` is given. */
     selectHelp: string;
+    /** Said when the keyboard sets the start of a range; the x value is written in the axis' format. */
+    rangeStarted: (from: string) => string;
+    /** Said when the keyboard sets the end of a range. */
+    rangeMade: (from: string, to: string) => string;
+    /** The key that marks a range - only where `onRange` is given and a tooltip stands. */
+    rangeHelp: string;
     /** The keys that zoom and pan it - only where the chart can be zoomed. */
     zoomHelp: string;
     /** The keys of the legend's entries - only where it has one to press. */

package/dist/index.d.ts

@@ -375,7 +375,7 @@ export declare type CalendarInput = WorkingCalendar | readonly WorkingInterval[]
 
 /** What `useChart` takes besides the rows: the view to start from and the
  handler that hears every change of it. */
-export declare interface ChartOptions<Z = unknown> {
+export declare interface ChartOptions<Z = unknown, V extends number | string = number> {
     /** The view to start from, read once when the hook first runs; a different
      value on a later render is ignored, as React ignores a changed
      `defaultValue`. To go to a view later, call `setView`. The chart
@@ -393,6 +393,14 @@ export declare interface ChartOptions<Z = unknown> {
      none: what is chosen is the application's state. Needs a `<Tooltip>`,
      which makes the hits; the hit does not travel over `syncId`. */
     onSelect?: (hit: TooltipHit<Z>) => void;
+    /** The reader marked a stretch of an x axis: Alt with a drag where the chart
+     zooms, a plain drag where it does not. Called once, on release - once per
+     x axis -, with `from` not after `to`, in the axis' own values: numbers, milliseconds on a time axis, wall-clock instants on a calendar axis, and on a category axis the first and last category covered, as strings - say so in the handler's parameter, `ChartRange<string>`. A band
+     covers the stretch while the pointer is down; the chart keeps no range and
+     draws none afterwards, and it does not travel over `syncId`. A press that
+     travels 4 px or less is a click and reaches `onSelect`; Escape and a
+     cancelled pointer report nothing. */
+    onRange?: (range: ChartRange<V>) => void;
 }
 
 /** What `useChart` hands back: the chart and its parts, typed at the row `Z`,
@@ -435,6 +443,15 @@ export declare interface ChartParts<Z> {
     showOnly: (name: string) => void;
     /** Shows every series again. */
     showAllSeries: () => void;
+    /** A PNG of the chart as it stands: the plot with its grid, series and
+     limits, the axes with ticks, labels and titles, and the legend, on the
+     chart's own ground in the colour scheme in use, at the chart's size on
+     screen and at least twice its CSS pixels. Not in it: the tooltip, the
+     crosshair and hover marks, the "Show all" button, the data key and
+     its table, the screen-reader texts, and any title. Where the picture goes
+     - a download, the clipboard, an upload - is the application's. Rejects
+     with an `Error` when the chart is not on screen or has no size. */
+    toPng: () => Promise<Blob>;
 }
 
 /** Measurements of the instrumentation for the benchmark page. */
@@ -463,10 +480,6 @@ export declare interface ChartProps extends Omit<HTMLAttributes<HTMLDivElement>,
     height?: number;
     /** Outer spacing of the plot area in CSS pixels. */
     padding?: number | Partial<Padding>;
-    /** 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;
     /** Goes to the root element, after the chart's own styles: a `height` or
@@ -491,6 +504,16 @@ export declare interface ChartProps extends Omit<HTMLAttributes<HTMLDivElement>,
      axis or series. German: `GERMAN_CHARTS_WORDING` from `@umriss-ui/charts/wording/de`.
      @default DEFAULT_CHARTS_WORDING */
     wording?: Partial<ChartsWording>;
+    /** An IANA time zone (`"Europe/Berlin"`) for every time axis of the chart, a
+     calendar axis included: ticks stand on its hours and midnights, and the
+     labels, tooltip, readout, data table and summary write its time, in the
+     wording's `locale`. Where the reader's zone is another, the axis title
+     ends in the zone's name (after mount). An hour a clock change doubles is
+     ticked twice and its labels carry the offset; the hour it removes has
+     no tick. A name Intl does not know throws its `RangeError`. An
+     application on `@umriss-ui/core` passes `useFormats().timeZone`.
+     @default the reader's zone */
+    timeZone?: string;
     /** How series are told apart. `"color"`: by their colour.
      `"marks"`: by a dash and a marker shape as well - a line, an area and a
      scatter -, and by a hatch - a bar, a state, a matrix cell, a limit band -,
@@ -513,6 +536,16 @@ export declare interface ChartProps extends Omit<HTMLAttributes<HTMLDivElement>,
     children?: ReactNode;
 }
 
+/** A stretch of an x axis the reader marked (`onRange`): `from` is not after
+ `to`, both in the axis' own values - numbers on a numeric or time axis
+ (milliseconds). A caller that reads numbers takes the default and needs no
+ cast; `V` is what a category axis widens it to. */
+export declare interface ChartRange<V extends number | string = number> {
+    axisId: string;
+    from: V;
+    to: V;
+}
+
 /** Everything the charts put out as text. */
 export declare interface ChartsWording {
     /** The BCP 47 tag every number and every date or time label of the chart is
@@ -553,6 +586,12 @@ export declare interface ChartsWording {
     walkHelp: string;
     /** The key that reports the Active point - only where `onSelect` is given. */
     selectHelp: string;
+    /** Said when the keyboard sets the start of a range; the x value is written in the axis' format. */
+    rangeStarted: (from: string) => string;
+    /** Said when the keyboard sets the end of a range. */
+    rangeMade: (from: string, to: string) => string;
+    /** The key that marks a range - only where `onRange` is given and a tooltip stands. */
+    rangeHelp: string;
     /** The keys that zoom and pan it - only where the chart can be zoomed. */
     zoomHelp: string;
     /** The keys of the legend's entries - only where it has one to press. */
@@ -760,6 +799,9 @@ export declare const DEFAULT_GRADIENT: readonly string[];
 /** One hour in milliseconds. */
 export declare const HOUR: number;
 
+/** Does the clock show this instant's time twice? */
+export declare function inDoubledHour(t: number, zone?: string): boolean;
+
 /** Explicit invalidation: devalue the cache, every living chart reads anew and
  redraws. */
 export declare function invalidateTheme(): void;
@@ -984,8 +1026,9 @@ export declare type ListValue<T> = ListField<T> | ListFunction<T>;
 
 /** The local offset at an instant, as the shift of a grid that is to lie on
  local time: `wallClock = offset + k · step`. Taken at one instant, it holds
- for a grid up to the next clock change. */
-export declare function localOffset(instant: number): number;
+ for a grid up to the next clock change. With a `timeZone` (an IANA name)
+ the zone's offset, else the reader's. */
+export declare function localOffset(instant: number, timeZone?: string): number;
 
 /** Materialised series: the draw loop works only on this.
  Gaps (null/undefined/NaN/±Infinity out of the accessor) are encoded as NaN. */
@@ -1516,7 +1559,7 @@ export declare function toWorkingTimeClamped(wallClock: number, input: CalendarI
  @returns `Chart`, `XAxis`, `YAxis` and every series kind - each keeps its
  identity over the renders -, the `view`, its `domains` and `hidden`, and
  the setters that change them. */
-export declare function useChart<Z>(rows: readonly Z[], options?: ChartOptions<Z>): ChartParts<Z>;
+export declare function useChart<Z, V extends number | string = number>(rows: readonly Z[], options?: ChartOptions<Z, V>): ChartParts<Z>;
 
 /** A value read from the row (ADR-0048): the name of a number field, compared
  by its name, or a function, compared by its source text (`ValueFunction`). */
@@ -1529,8 +1572,8 @@ 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
- changed closure variable under the same text is not run again; pass a new
- data reference then. A native or bound function is compared by identity. */
+ changed closure variable under the same text is not run again, and DEV warns;
+ carry the value in the rows, or give the series a `key` that changes with it. A native or bound function is compared by identity. */
 export declare type ValueFunction<T> = (d: T, index: number) => number | null | undefined;
 
 /** What a value is. Four outcomes, not three.
@@ -1610,9 +1653,14 @@ export declare interface WorkingTimeTick {
  the beginning of the next - the earlier one stays: two labels on the same
  pixel would be one too many.
 
+ With a `timeZone` the grid is the zone's, and `offset` is not read: a step
+ of whole days stands on the zone's midnights, a shorter one on its whole
+ multiples in real time - none in the hour a clock change removes, two in
+ the one it doubles.
+
  Both times come back, because the axis needs both: the working time to
  place the tick, the wall clock time to label it. */
-export declare function workingTimeTicks(input: CalendarInput, from: number, to: number, step: number, offset?: number): WorkingTimeTick[];
+export declare function workingTimeTicks(input: CalendarInput, from: number, to: number, step: number, offset?: number, timeZone?: string): WorkingTimeTick[];
 
 /** The props of `XAxis`. */
 export declare interface XAxisProps<T> extends CommonProps {

package/dist/wording/de.js

@@ -1,5 +1,5 @@
 "use client";
-const i = {
+const r = {
   locale: "de-DE",
   roleDescription: "Diagramm",
   empty: "Keine Daten",
@@ -12,6 +12,9 @@ const i = {
   percent: (e) => `${e} %`,
   walkHelp: "Pfeil links und rechts gehen durch die Werte, Pfeil hoch und runter wechseln die Serie, Pos1 und Ende springen zum ersten und letzten Wert, Escape hebt die Markierung auf.",
   selectHelp: "Enter wählt den Punkt.",
+  rangeStarted: (e) => `Bereich ab ${e} begonnen.`,
+  rangeMade: (e, n) => `Bereich von ${e} bis ${n}.`,
+  rangeHelp: "Leertaste setzt Anfang und Ende eines Bereichs, Escape bricht ab.",
   zoomHelp: "Plus und Minus zoomen, Umschalt mit Pfeil links oder rechts verschiebt, 0 kehrt zum eigenen Bereich der Achse zurück.",
   legendHelp: "In der Legende blendet Enter eine Serie aus oder ein, Umschalt+Enter zeigt nur sie.",
   allShown: "Sonst wäre nichts mehr zu sehen, darum werden alle Serien gezeigt.",
@@ -35,5 +38,5 @@ const i = {
   downsampled: (e) => `Ausgedünnt aus ${e.toLocaleString("de-DE")} Messwerten: erster, kleinster, größter und letzter Wert je Abschnitt.`
 };
 export {
-  i as GERMAN_CHARTS_WORDING
+  r as GERMAN_CHARTS_WORDING
 };