@graphysdk/react-renderer 1.9.0-beta.1793293011268 → 1.9.0-beta.1793617099519

package/dist/index.d.ts

@@ -21,6 +21,7 @@ import { FontSpec } from '@graphysdk/viz-engine';
 import { FormattedAxis } from '@graphysdk/viz-engine';
 import { FormattedHeadline } from '@graphysdk/viz-engine';
 import { FormattedLegend } from '@graphysdk/viz-engine';
+import { FormattingLocale } from '@graphysdk/viz-engine';
 import { Geom } from '@graphysdk/viz-engine';
 import { GeomCornerRadius } from '@graphysdk/viz-engine';
 import { GeomEffects } from '@graphysdk/viz-engine';
@@ -225,6 +226,8 @@ declare const createTargetBoundaryStore: () => StoreApi<TargetBoundaryStoreState
 /** vanilla-extract class that binds the dark token values; set it on any ancestor to flip to dark. */
 export declare const darkTheme: string;
 
+declare type DeepValue<T, Path extends string> = Path extends `${infer First}.${infer Rest}` ? First extends keyof T ? DeepValue<T[First], Rest> : never : Path extends keyof T ? T[Path] : never;
+
 /** Default paint for the footer region — caption, source line, and optional Graphy badge. */
 export declare const DefaultFooter: ({ ref, footerRect, mode, caption, showCaption, source, showSource, captionStyle, sourceStyle, graphyBadge, }: FooterSlotProps) => JSX.Element | null;
 
@@ -312,6 +315,321 @@ export declare interface DevToolsPanelProps {
     className?: string;
 }
 
+declare const dictionaries: {
+    readonly 'en-GB': {
+        readonly graph: {
+            readonly loading: "Loading";
+            readonly error: "Something went wrong";
+            readonly axisLabels: {
+                readonly placeholder: "Add label";
+            };
+            readonly defaultPropertyLabels: {
+                readonly date: "Date";
+                readonly year: "Year";
+                readonly quarter: "Quarter";
+                readonly month: "Month";
+                readonly week: "Week";
+                readonly series: "Series";
+                readonly category: "Category";
+                readonly columnNumber: ({ number }: {
+                    number: number;
+                }) => string;
+                readonly rowNumber: ({ number }: {
+                    number: number;
+                }) => string;
+                readonly seriesNumber: ({ number }: {
+                    number: number;
+                }) => string;
+            };
+            readonly trendComparison: {
+                readonly fromPrevious: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousYear: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousMonth: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousWeek: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousDay: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousHour: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+            };
+            readonly headlineMetrics: {
+                readonly averageLong: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly averageShort: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly total: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly totalConversionRate: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly current: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly comparisonReference: ({ value }: {
+                    value: string;
+                }) => string;
+            };
+            readonly legend: {
+                readonly hiddenItems: "Hidden legend items";
+            };
+        };
+        readonly dir: "ltr";
+    };
+    readonly 'en-US': LooseShapeOf<LocaleShape>;
+    readonly ar: {
+        readonly graph: {
+            readonly loading: "جاري التحميل";
+            readonly error: "حدث خطأ ما";
+            readonly axisLabels: {
+                readonly placeholder: "إضافة تسمية";
+            };
+            readonly defaultPropertyLabels: {
+                readonly date: "التاريخ";
+                readonly year: "السنة";
+                readonly quarter: "الربع";
+                readonly month: "الشهر";
+                readonly week: "الأسبوع";
+                readonly series: "السلسلة";
+                readonly category: "الفئة";
+                readonly columnNumber: ({ number }: {
+                    number: number;
+                }) => string;
+                readonly rowNumber: ({ number }: {
+                    number: number;
+                }) => string;
+                readonly seriesNumber: ({ number }: {
+                    number: number;
+                }) => string;
+            };
+            readonly trendComparison: {
+                readonly fromPrevious: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousYear: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousMonth: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousWeek: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousDay: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousHour: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+            };
+            readonly headlineMetrics: {
+                readonly averageLong: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly averageShort: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly total: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly totalConversionRate: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly current: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly comparisonReference: ({ value }: {
+                    value: string;
+                }) => string;
+            };
+            readonly legend: {
+                readonly hiddenItems: "عناصر وسيلة الإيضاح المخفية";
+            };
+        };
+        readonly dir: "rtl";
+    };
+    readonly 'pt-PT': {
+        readonly graph: {
+            readonly loading: "A carregar";
+            readonly error: "Algo correu mal";
+            readonly axisLabels: {
+                readonly placeholder: "Adicionar etiqueta";
+            };
+            readonly defaultPropertyLabels: {
+                readonly date: "Data";
+                readonly year: "Ano";
+                readonly quarter: "Trimestre";
+                readonly month: "Mês";
+                readonly week: "Semana";
+                readonly series: "Série";
+                readonly category: "Categoria";
+                readonly columnNumber: ({ number }: {
+                    number: number;
+                }) => string;
+                readonly rowNumber: ({ number }: {
+                    number: number;
+                }) => string;
+                readonly seriesNumber: ({ number }: {
+                    number: number;
+                }) => string;
+            };
+            readonly trendComparison: {
+                readonly fromPrevious: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousYear: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousMonth: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousWeek: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousDay: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+                readonly fromPreviousHour: {
+                    readonly long: ({ value }: {
+                        value: string;
+                    }) => string;
+                    readonly short: ({ value }: {
+                        value: string;
+                    }) => string;
+                };
+            };
+            readonly headlineMetrics: {
+                readonly averageLong: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly averageShort: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly total: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly totalConversionRate: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly current: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly comparisonReference: ({ value }: {
+                    value: string;
+                }) => string;
+            };
+            readonly legend: {
+                readonly hiddenItems: "Itens de legenda ocultos";
+            };
+        };
+        readonly dir: "ltr";
+    };
+};
+
+declare type Dictionary<T> = {
+    [K in keyof T]: T[K] extends object ? Dictionary<T[K]> : string;
+};
+
+declare type DotNotation<T> = T extends object ? {
+    [K in keyof T & string]: T[K] extends (...args: never[]) => unknown ? K : T[K] extends object ? `${K}.${DotNotation<T[K]>}` : K;
+}[keyof T & string] : never;
+
 /** Addresses the axis a stamped node belongs to. */
 declare const EDIT_TARGET_AXIS_ATTRIBUTE = "data-edit-axis";
 
@@ -377,6 +695,108 @@ export declare interface EditOutlineStroke extends MorphingEditOutlineShape {
     width: number;
 }
 
+declare const EN_GB: {
+    readonly graph: {
+        readonly loading: "Loading";
+        readonly error: "Something went wrong";
+        readonly axisLabels: {
+            readonly placeholder: "Add label";
+        };
+        readonly defaultPropertyLabels: {
+            readonly date: "Date";
+            readonly year: "Year";
+            readonly quarter: "Quarter";
+            readonly month: "Month";
+            readonly week: "Week";
+            readonly series: "Series";
+            readonly category: "Category";
+            readonly columnNumber: ({ number }: {
+                number: number;
+            }) => string;
+            readonly rowNumber: ({ number }: {
+                number: number;
+            }) => string;
+            readonly seriesNumber: ({ number }: {
+                number: number;
+            }) => string;
+        };
+        readonly trendComparison: {
+            readonly fromPrevious: {
+                readonly long: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly short: ({ value }: {
+                    value: string;
+                }) => string;
+            };
+            readonly fromPreviousYear: {
+                readonly long: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly short: ({ value }: {
+                    value: string;
+                }) => string;
+            };
+            readonly fromPreviousMonth: {
+                readonly long: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly short: ({ value }: {
+                    value: string;
+                }) => string;
+            };
+            readonly fromPreviousWeek: {
+                readonly long: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly short: ({ value }: {
+                    value: string;
+                }) => string;
+            };
+            readonly fromPreviousDay: {
+                readonly long: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly short: ({ value }: {
+                    value: string;
+                }) => string;
+            };
+            readonly fromPreviousHour: {
+                readonly long: ({ value }: {
+                    value: string;
+                }) => string;
+                readonly short: ({ value }: {
+                    value: string;
+                }) => string;
+            };
+        };
+        readonly headlineMetrics: {
+            readonly averageLong: ({ value }: {
+                value: string;
+            }) => string;
+            readonly averageShort: ({ value }: {
+                value: string;
+            }) => string;
+            readonly total: ({ value }: {
+                value: string;
+            }) => string;
+            readonly totalConversionRate: ({ value }: {
+                value: string;
+            }) => string;
+            readonly current: ({ value }: {
+                value: string;
+            }) => string;
+            readonly comparisonReference: ({ value }: {
+                value: string;
+            }) => string;
+        };
+        readonly legend: {
+            readonly hiddenItems: "Hidden legend items";
+        };
+    };
+    readonly dir: "ltr";
+};
+
 export { FadeIntroPlan }
 
 /**
@@ -677,7 +1097,7 @@ declare interface GeomRenderInput<G extends GeomName | string = string, C extend
     layer: SceneLayerOf<G>;
     coordSystem: CoordSystemFor<C>;
     animateTransitions: boolean;
-    formattingLocale: Locale;
+    formattingLocale: FormattingLocale;
     intro?: LayerIntroPlan | null;
     /**
      * The panel's pixel rect — the data rectangle geoms paint into, already inset from axes and chrome.
@@ -840,6 +1260,8 @@ export declare interface GraphHandle {
     subscribe: (onGraphChange: () => void) => () => void;
     /** The graph's scene as of now, or `null` before its first successful compile. */
     getScene: () => Scene | null;
+    /** The tag the graph formats values in, safe to hand to `Intl`. Unset, it formats in the scene's `parsingLocale`. */
+    formattingLocale?: FormattingLocale;
     /**
      * Reverse the most recent command. Returns whether the chart took the step, so a caller driving
      * this from a keystroke can leave the key to the app when the chart has nothing to undo or the
@@ -881,13 +1303,16 @@ export declare interface GraphHistoryShortcutsOptions {
 /** The mode a chart runs in, which `GraphRenderer` takes as a prop and every row of `MODE_SURFACES` is keyed by. */
 export declare type GraphMode = (typeof GRAPH_MODES)[keyof typeof GRAPH_MODES];
 
+/** Every phrase a chart can say. The editing surface adds its own — see `editable/i18n/editor-i18n`. */
+declare type GraphPhrases = typeof EN_GB;
+
 /**
  * Owns the scene for a graph and exposes it via {@link useSceneSelector}, plus a
  * `dispatch` for applying {@link Command}s. Both failure modes — a non-throwing compile failure and a
  * render-throw from a renderer component — converge on a single {@link GraphErrorBoundary} that shows
  * the error in place, so a broken chart never blanks the page.
  */
-export declare const GraphProvider: ({ data, spec, plugins, theme, formattingLocale, handleRef, onSpecChange, onError, onWarnings, colorScheme: hostColorScheme, children, }: GraphProviderProps) => JSX.Element;
+export declare const GraphProvider: ({ data, spec, plugins, theme, formattingLocale: requestedFormattingLocale, handleRef, onSpecChange, onError, onWarnings, colorScheme: hostColorScheme, children, }: GraphProviderProps) => JSX.Element;
 
 /** Props for {@link GraphProvider}: the data and spec to compile, plus color scheme, locale and plugin wiring. */
 export declare interface GraphProviderProps {
@@ -906,7 +1331,11 @@ export declare interface GraphProviderProps {
      * The theme's `colorScheme`, when set, overrides the `colorScheme` prop.
      */
     theme?: Theme;
-    formattingLocale?: Locale;
+    /**
+     * Formats numbers and dates for display: any BCP-47 tag (`it-IT`). A tag `Intl` cannot read formats as `en-GB` and
+     * reports `INVALID_FORMATTING_LOCALE`. Graphy's own texts use the built-in dictionary for its language, else `en-GB`.
+     */
+    formattingLocale?: FormattingLocale;
     /**
      * Filled with this graph's {@link GraphHandle}, for callers mounted outside the provider where the
      * hooks can't reach. `useGraphHistoryShortcuts` binds the undo/redo chords to one.
@@ -915,7 +1344,7 @@ export declare interface GraphProviderProps {
     onSpecChange?: (next: Spec) => void;
     /** Fires with the compile failure(s) whenever a compile/recompile/dispatch produces errors. */
     onError?: (errors: VizDiagnostic[]) => void;
-    /** Fires with any warnings a successful compile produced. */
+    /** Fires with any warnings a successful compile produced, and with `INVALID_FORMATTING_LOCALE` on a tag `Intl` cannot read. */
     onWarnings?: (warnings: VizDiagnostic[]) => void;
     colorScheme?: ColorScheme;
     children: ReactNode;
@@ -926,6 +1355,8 @@ export declare interface GraphProviderProps {
  * layout + DOM — the provider owns the spec and derives the scene output from it. There's
  * no `config` prop: every consumer must wrap with `<GraphProvider>` so commands can operate
  * on the live spec.
+ *
+ * Its texts follow `formattingLocale`, or the `locale` an `IntlProvider` above it sets, and take that provider's overrides.
  */
 export declare const GraphRenderer: (props: GraphRendererProps) => JSX.Element;
 
@@ -1171,6 +1602,22 @@ declare interface HoverStoreActions {
 /** State of the hover store: the current {@link HoverState} plus its setter. */
 declare type HoverStoreState = HoverSlice & HoverStoreActions;
 
+declare type I18nLocale = keyof typeof dictionaries;
+
+declare type I18nRuntimeOverrides = RuntimeOverrides<GraphPhrases>;
+
+/** The provider a read-only host wraps a chart in: chart phrases only, so `.` reaches no editor dictionary. */
+export declare const IntlProvider: React.FC<Omit<IntlProviderProps, 'dictionaries'>>;
+
+declare interface IntlProviderProps {
+    /** Any BCP-47 tag, which reads the dictionary {@link normalizeLocale} picks for it. */
+    locale?: FormattingLocale;
+    children: ReactNode;
+    i18nOverrides?: I18nRuntimeOverrides;
+    /** The phrase sets this tree translates against, most specific first. Defaults to the chart's own. */
+    dictionaries?: readonly PhraseSource[];
+}
+
 declare interface IntroAnimationOptions {
     /** Whether the entrance plays at all */
     enabled: boolean;
@@ -1272,6 +1719,22 @@ export declare interface LiveGeomApi {
     readPanelPoint: (cursor: GeomHoverCursor) => PanelPoint | null;
 }
 
+declare type LocaleShape = {
+    dir?: TextDirection;
+} & Dictionary<typeof EN_GB>;
+
+declare type LooseSection<T> = {
+    [K in keyof T]?: T[K] extends object ? LooseSection<T[K]> : LooseValue<T[K]>;
+};
+
+declare type LooseShapeOf<T> = {
+    [K in keyof T]?: LooseSection<T[K]>;
+};
+
+declare type LooseString<T> = T extends string ? string : T;
+
+declare type LooseValue<T> = T extends (...args: infer A) => infer R ? (...args: A) => R : LooseString<T>;
+
 declare interface MorphingEditOutlineShape {
     /** SVG path data in panel pixels. */
     pathData: string;
@@ -1307,6 +1770,8 @@ declare interface OverlayAnchorInput<G extends GeomName | string = string, C ext
 /** Where a geom `overpaint` lands: over everything a hook draws, or where the geom wraps it itself. */
 export declare type OverpaintPlacement = 'layer' | 'manual';
 
+declare type OverridePhrase<Phrases, Key extends string> = DeepValue<Phrases, Key> extends PhraseFn<infer P> ? PhraseFn<P> | string : string;
+
 export declare interface PaintDefs {
     /** The `fill` attribute for a paint: the color itself, or a `url(#id)` into the defs this SVG renders. */
     fillFor: (paint: ResolvedPaint) => string;
@@ -1341,6 +1806,11 @@ export declare interface PathStroke {
     strokeLinecap: StyleLineCap | undefined;
 }
 
+declare type PhraseFn<P extends Record<string, unknown> = Record<string, unknown>> = (params: P) => string;
+
+/** One surface's phrases, per locale. */
+declare type PhraseSource = Partial<Record<I18nLocale, object>>;
+
 /**
  * How a point's `(x, y)` becomes SVG coordinates — the only thing that differs between a cartesian point
  * and a polar (radar) point. Each coord's geom-renderer and hover container supply their own projection;
@@ -1409,6 +1879,12 @@ export declare const resolveGraphyBadgeVariant: (visible: boolean, frameSize: {
 /** `lineCap` is the cap the stroke would otherwise paint; a dotted stroke paints round dots under any cap. */
 export declare const resolvePathStroke: (dashArray: DashArray | undefined, strokeWidth: number, lineCap?: StyleLineCap) => PathStroke;
 
+declare type RuntimeOverrides<Phrases> = {
+    dir?: TextDirection;
+} & {
+    [Key in DotNotation<Phrases>]?: OverridePhrase<Phrases, Key>;
+};
+
 /** A point a point projection placed as a fraction of the panel, in panel pixels from the top left. */
 export declare const scalePointToPanel: (point: XYPoint, panelSize: {
     width: number;
@@ -1611,6 +2087,8 @@ declare interface TargetBoundaryStoreActions {
 /** State of the target boundary store: the boundary the editor last measured plus the action replacing it. */
 export declare type TargetBoundaryStoreState = TargetBoundarySlice & TargetBoundaryStoreActions;
 
+declare type TextDirection = 'ltr' | 'rtl';
+
 /**
  * Creates a font-ready, cached text measurer and shares it with descendants via context.
  * Renders nothing until the measurer resolves, so consumers reading the context always
@@ -1757,6 +2235,9 @@ export declare function useElementScreenRect<T extends Element = SVGRectElement>
     screenRect: ScreenRect | null;
 };
 
+/** The tag a chart formats numbers and dates in, which may name a locale no dictionary has. */
+export declare const useFormattingLocale: () => FormattingLocale;
+
 /**
  * Registers a layout geom's render-side hit tester so a `'renderHitTest'` layer inherits central hover
  * and the built-in tooltip — the path `bar` takes — with no pointer overlay of its own. The pull path.
@@ -1871,8 +2352,8 @@ export declare const useGraphHistory: () => GraphHistory;
  */
 export declare const useGraphHistoryShortcuts: (handleRef: RefObject<GraphHandle | null>, options?: GraphHistoryShortcutsOptions) => void;
 
-/** The locale a chart reads. Resolved outside `IntlProvider`, so either renderer can mount its own. */
-export declare const useGraphLocale: () => "en-GB" | "en-US" | "ar" | "pt-PT";
+/** The dictionary a chart's texts read when no host `IntlProvider` sets a locale. Resolved outside `IntlProvider`, so either renderer can mount its own. */
+export declare const useGraphLocale: () => Locale;
 
 /**
  * Subscribes to what the graph holds selected, from inside a `<GraphProvider>`. The store is