@lolmath/ui 9.5.0 → 9.6.0

package/dist/charts.d.mts

@@ -0,0 +1,352 @@
+import { HTMLAttributes, JSX, ReactNode } from "react";
+import { ChartCurve, ChartDefinition, ChartPoint, ChartTheme, ChartTheme as ChartTheme$1, ChartValue, ChartValue as ChartValue$1, DomChartDefinition, areaY, barX, barY, crosshair, d3Curve, defineChart, dot, group, lineX, lineY, rect, ruleX, ruleY, stack, text, tickX, tickY } from "@tanstack/charts";
+import { scaleBand } from "@tanstack/charts/scales/band";
+import { scaleLinear } from "@tanstack/charts/scales/linear";
+import { scaleOrdinal } from "@tanstack/charts/scales/ordinal";
+import { scalePoint } from "@tanstack/charts/scales/point";
+import { tooltip, tooltip as tooltip$1 } from "@tanstack/charts/tooltip";
+import { ChartProps } from "@tanstack/charts/react";
+//#region src/charts/curves.d.ts
+/** How a line or an area gets from one point to the next. */
+type ChartCurveName = "linear" | "smooth" | "step";
+/** Straight segments, like d3's `curveLinear`. */
+declare const linearCurve: ChartCurve;
+/**
+ * Monotone cubic interpolation over x — d3's `curveMonotoneX`, by way of
+ * Steffen's method. Smooth, but it never overshoots a reading, so a rounded
+ * corner cannot invent a value the data never had.
+ */
+declare const smoothCurve: ChartCurve;
+/** Holds each value until the next one, like d3's `curveStepAfter`. */
+declare const stepCurve: ChartCurve;
+//#endregion
+//#region src/charts/components/chart-legend/chart-legend.d.ts
+interface ChartLegendItem {
+  /** Stable identity for the entry. */
+  key: string;
+  /** What the reader sees. Falls back to `key`. */
+  label?: string;
+  /** The colour of the mark this entry stands for. */
+  color: string;
+}
+interface ChartLegendProps extends HTMLAttributes<HTMLUListElement> {
+  items: readonly ChartLegendItem[];
+  /** Matches the swatch to the mark: a diamond, a square, or a line key. */
+  swatch?: "diamond" | "square" | "line";
+}
+/**
+ * The legend every multi-series chart carries.
+ *
+ * Colour alone is never allowed to be the only way to tell two series apart,
+ * so this is not optional decoration — a chart with two or more series renders
+ * one. A single-series chart does not: its title already says what is plotted,
+ * and a lone swatch would only restate it.
+ */
+declare function ChartLegend({ items, swatch, className, ...rest }: ChartLegendProps): JSX.Element;
+//#endregion
+//#region src/charts/components/chart-common.d.ts
+/**
+ * What a chart can plot along its independent axis. Dates are deliberately
+ * absent: the engine ships no time scale, so map a date to a number or to a
+ * pre-formatted label before it reaches a chart.
+ */
+type ChartXValue = string | number;
+/** One measure drawn across the data — a line, an area, a set of bars. */
+interface ChartSeries<TDatum> {
+  /** Stable identity. Used for React keys and for the mark's id. */
+  key: string;
+  /** What the legend and the tooltip call it. Falls back to `key`. */
+  label?: string;
+  /** Reads this series' value out of a row. Return null to break the line. */
+  value: (datum: TDatum) => number | null | undefined;
+  /**
+   * Overrides the palette slot. Reach for it when the series *means*
+   * something — a win rate, a gold lead — and should wear a status colour.
+   */
+  color?: string;
+}
+/** Props every cartesian chart in this package accepts. */
+interface CartesianChartProps<TDatum> {
+  /** One row per position along the x axis. */
+  data: readonly TDatum[];
+  /** The measures to draw. Two or more get a legend. */
+  series: readonly ChartSeries<TDatum>[];
+  /** Reads the x position out of a row. */
+  x: (datum: TDatum) => ChartXValue;
+  /** Plot height in pixels. The width fills the container. */
+  height?: number;
+  /** Names what is plotted, in the frame's header. */
+  title?: ReactNode;
+  /** A line of context under the title. */
+  subtitle?: ReactNode;
+  /** Controls belonging to this chart, in the frame's header. */
+  actions?: ReactNode;
+  /** Axis titles. */
+  xLabel?: string;
+  yLabel?: string;
+  /** Tick and tooltip formatting. */
+  formatX?: (value: ChartXValue) => string;
+  formatY?: (value: number) => string;
+  /** Horizontal grid lines. On by default. */
+  grid?: boolean;
+  /**
+   * Forces the legend on or off. By default it appears for two or more
+   * series and is left off for one, whose title already names it.
+   */
+  legend?: boolean;
+  /** Drops the metal frame, keeping the type and colours. */
+  frame?: boolean;
+  /** Lights the marks with the hextech bloom. */
+  glow?: boolean;
+  /**
+   * What a screen reader announces. Derived from a string `title` when it can
+   * be; pass it explicitly whenever the title is a node or absent.
+   */
+  ariaLabel?: string;
+  ariaDescription?: string;
+  className?: string;
+  /** Props for the frame element. */
+  frameProps?: Omit<HTMLAttributes<HTMLElement>, "title" | "className" | "children">;
+}
+//#endregion
+//#region src/charts/components/area-chart/area-chart.d.ts
+interface AreaChartProps<TDatum> extends CartesianChartProps<TDatum> {
+  /** How the boundary travels between points. */
+  curve?: ChartCurveName;
+  /**
+   * Stacks the series into a total instead of overlaying them. Stack when the
+   * parts genuinely sum to something — damage by source, gold by lane.
+   */
+  stacked?: boolean;
+  /**
+   * Turns a stack into shares of 100%. Only meaningful when `stacked`.
+   */
+  normalize?: boolean;
+  /** Draws the boundary of each area. On by default. */
+  stroke?: boolean;
+  /** Follows the pointer with a vertical guide. On by default. */
+  crosshair?: boolean;
+}
+/**
+ * Filled areas — a composition over time, or a single magnitude you want to
+ * read as volume rather than as a trace.
+ *
+ * Overlaid areas (the default) are only honest for two or three series; past
+ * that the ones behind disappear. Stack them, or split into small multiples.
+ */
+declare function AreaChart<TDatum>({ data, series, x, curve, stacked, normalize, stroke, crosshair: withCrosshair, height, title, subtitle, actions, xLabel, yLabel, formatX, formatY, grid, legend, frame, glow, ariaLabel, ariaDescription, className, frameProps }: AreaChartProps<TDatum>): JSX.Element;
+//#endregion
+//#region src/charts/components/bar-chart/bar-chart.d.ts
+interface BarChartProps<TDatum> extends CartesianChartProps<TDatum> {
+  /**
+   * Side by side or stacked. Group when the series are compared against each
+   * other; stack when they sum to a whole.
+   */
+  layout?: "grouped" | "stacked";
+  /** Turns a stack into shares of 100%. Only meaningful when stacked. */
+  normalize?: boolean;
+  /**
+   * Corner radius. Zero by default: Hextech is chamfered and square, and the
+   * square is the shape the language uses to sit things on a grid.
+   */
+  radius?: number;
+  /** Widest a bar is allowed to get, in pixels. */
+  maxThickness?: number;
+}
+/**
+ * Columns over categories — per-champion damage, per-role gold share, counts
+ * by patch.
+ *
+ * Bars are separated by a gap in the surface rather than by an outline: a
+ * stroke around a bar is ink that carries no data.
+ */
+declare function BarChart<TDatum>({ data, series, x, layout, normalize, radius, maxThickness, height, title, subtitle, actions, xLabel, yLabel, formatX, formatY, grid, legend, frame, glow, ariaLabel, ariaDescription, className, frameProps }: BarChartProps<TDatum>): JSX.Element;
+//#endregion
+//#region src/charts/components/chart-frame/chart-frame.d.ts
+interface ChartFrameProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+  /** Names what is plotted. Set in Beaufort, uppercased, like the client. */
+  title?: ReactNode;
+  /** One line of context under the title — a patch, a rank, a sample size. */
+  subtitle?: ReactNode;
+  /** Controls that belong to this chart: a range picker, a toggle group. */
+  actions?: ReactNode;
+  /** Rendered under the plot. The chart components put the legend here. */
+  footer?: ReactNode;
+  /** Drops the metal, keeping the type and colours. */
+  preset?: "framed" | "bare";
+  children?: ReactNode;
+}
+/**
+ * The panel a Hextech chart sits in: a gold hairline, diamond corners, a title
+ * in Beaufort and a rule under it.
+ *
+ * Every chart in this package renders one of these. Reach for it directly when
+ * you are building a chart of your own and want it to sit alongside them.
+ */
+declare function ChartFrame({ title, subtitle, actions, footer, preset, className, children, ...rest }: ChartFrameProps): JSX.Element;
+//#endregion
+//#region src/charts/components/hextech-chart/hextech-chart.d.ts
+interface HextechChartProps<TDatum = unknown, TXValue extends ChartValue$1 = ChartValue$1, TYValue extends ChartValue$1 = ChartValue$1> extends ChartProps<TDatum, TXValue, TYValue> {
+  /**
+   * Lights the marks with the faint hextech bloom. On by default — turn it
+   * off for dense charts, where a glow on every line turns into haze.
+   */
+  glow?: boolean;
+  /** Props for the element wrapping the plot. */
+  wrapperProps?: HTMLAttributes<HTMLDivElement>;
+}
+/**
+ * A TanStack chart wearing the Hextech theme, with no frame around it.
+ *
+ * Use it when you have written a `defineChart` definition of your own and want
+ * it to look like the rest of the library. The theme is merged into the
+ * definition, so anything the definition sets for itself still wins.
+ */
+declare function HextechChart<TDatum, TXValue extends ChartValue$1 = ChartValue$1, TYValue extends ChartValue$1 = ChartValue$1>({ definition, glow, className, wrapperProps, ...rest }: HextechChartProps<TDatum, TXValue, TYValue>): JSX.Element;
+//#endregion
+//#region src/charts/components/line-chart/line-chart.d.ts
+interface LineChartProps<TDatum> extends CartesianChartProps<TDatum> {
+  /** How the line travels between points. Straight by default. */
+  curve?: ChartCurveName;
+  /** Marks each reading with a dot. Worth it below ~30 points a series. */
+  points?: boolean;
+  /** Washes the area under each line in its own hue. */
+  area?: boolean;
+  /** Follows the pointer with a vertical guide. On by default. */
+  crosshair?: boolean;
+}
+/**
+ * Lines over time — gold curves, damage curves, anything that only makes sense
+ * read left to right.
+ *
+ * ```tsx
+ * <LineChart
+ *   title="Team gold"
+ *   data={timeline}
+ *   x={(row) => row.minute}
+ *   series={[
+ *     { key: "blue", label: "Blue side", value: (row) => row.blueGold },
+ *     { key: "red", label: "Red side", value: (row) => row.redGold },
+ *   ]}
+ *   xLabel="Minute"
+ *   yLabel="Gold"
+ * />
+ * ```
+ */
+declare function LineChart<TDatum>({ data, series, x, curve, points, area, crosshair: withCrosshair, height, title, subtitle, actions, xLabel, yLabel, formatX, formatY, grid, legend, frame, glow, ariaLabel, ariaDescription, className, frameProps }: LineChartProps<TDatum>): JSX.Element;
+//#endregion
+//#region src/charts/components/ranking-chart/ranking-chart.d.ts
+interface RankingChartProps<TDatum> {
+  /** The rows to rank. */
+  data: readonly TDatum[];
+  /** Names a row — a champion, an item, a player. */
+  label: (datum: TDatum) => string;
+  /** The measure the ranking is on. */
+  value: (datum: TDatum) => number;
+  /**
+   * Paints one bar. Every bar wears the same hue by default, because the
+   * ranking is already carried by the order and the length — spending the
+   * identity channel on rank would mean a bar changes colour when the filter
+   * changes. Reach for this when a row *means* something: a pick you are
+   * highlighting, a positive against a negative delta.
+   */
+  color?: string | ((datum: TDatum, rank: number) => string);
+  /** How to order the rows before drawing. */
+  order?: "descending" | "ascending" | "input";
+  /** Keeps only the first N rows after ordering. */
+  limit?: number;
+  /** Writes each value at the tip of its bar. On by default. */
+  showValues?: boolean;
+  /** Formats the value, for the tip label, the axis and the tooltip. */
+  formatValue?: (value: number) => string;
+  /** Axis title for the measure. */
+  valueLabel?: string;
+  /** Draws the measure axis and its grid. Off by default — the tip labels
+   * already carry every value, and the axis would only repeat them. */
+  axis?: boolean;
+  /** Plot height. Defaults to something proportional to the row count. */
+  height?: number;
+  title?: ReactNode;
+  subtitle?: ReactNode;
+  actions?: ReactNode;
+  frame?: boolean;
+  glow?: boolean;
+  ariaLabel?: string;
+  ariaDescription?: string;
+  className?: string;
+  frameProps?: Omit<HTMLAttributes<HTMLElement>, "title" | "className" | "children">;
+}
+/**
+ * A ranked horizontal bar chart — the leaderboard shape. Longest bar on top,
+ * every value written at the tip.
+ *
+ * ```tsx
+ * <RankingChart
+ *   title="Damage to champions"
+ *   data={scoreboard}
+ *   label={(row) => row.champion}
+ *   value={(row) => row.damage}
+ *   formatValue={(value) => `${Math.round(value / 1000)}k`}
+ * />
+ * ```
+ */
+declare function RankingChart<TDatum>({ data, label, value, color, order, limit, showValues, formatValue, valueLabel, axis, height, title, subtitle, actions, frame, glow, ariaLabel, ariaDescription, className, frameProps }: RankingChartProps<TDatum>): JSX.Element;
+//#endregion
+//#region src/charts/theme/theme.d.ts
+/**
+ * The Hextech palette, in slot order. Every entry is a CSS custom property, so
+ * a host page retunes the whole library by redefining `--lol-chart-series-N`
+ * rather than by threading colours through props.
+ *
+ * Assign these in sequence and never cycle them: a seventh series is not a
+ * seventh colour, it is a sign that the chart should fold its tail into
+ * "Other" or split into small multiples.
+ */
+declare const hextechPalette: readonly ["var(--lol-chart-series-1)", "var(--lol-chart-series-2)", "var(--lol-chart-series-3)", "var(--lol-chart-series-4)", "var(--lol-chart-series-5)", "var(--lol-chart-series-6)"];
+/** How many categorical series the palette can carry. */
+declare const hextechPaletteSize: 6;
+/**
+ * Dot, bubble and scatter forms are held to a harder test than bars and lines:
+ * any two marks can end up touching, not just neighbouring slots. The palette
+ * clears that test for its first three slots, so those forms cap at three
+ * series — past that, facet rather than reach for a fourth colour.
+ */
+declare const hextechScatterPaletteSize = 3;
+/**
+ * Reserved status colours. A series that *means* good or bad — a win rate, a
+ * gold lead, a delta — wears these; a series that is merely "the third one"
+ * wears the categorical palette. Never both in one chart.
+ */
+declare const hextechStatusColors: {
+  readonly positive: "var(--lol-chart-positive)";
+  readonly negative: "var(--lol-chart-negative)";
+};
+/**
+ * The chart theme: gold ink and a near-black plot, matching the League client.
+ *
+ * `background` stays transparent so the frame behind the chart — or whatever
+ * the host puts there — shows through.
+ */
+declare const hextechChartTheme: {
+  readonly foreground: "var(--lol-chart-foreground)";
+  readonly muted: "var(--lol-chart-muted)";
+  readonly grid: "var(--lol-chart-grid)";
+  readonly background: "transparent";
+  readonly palette: readonly ["var(--lol-chart-series-1)", "var(--lol-chart-series-2)", "var(--lol-chart-series-3)", "var(--lol-chart-series-4)", "var(--lol-chart-series-5)", "var(--lol-chart-series-6)"];
+};
+/** The colour for a categorical slot, counted from zero and never wrapped. */
+declare function hextechSeriesColor(index: number): string;
+/**
+ * Applies the Hextech theme to a chart definition you wrote by hand, keeping
+ * any theme fields the definition sets for itself.
+ *
+ * ```ts
+ * const chart = withHextechTheme(defineChart({ marks: [...], x, y }));
+ * ```
+ */
+declare function withHextechTheme<TDefinition extends {
+  theme?: Partial<ChartTheme$1>;
+}>(definition: TDefinition): TDefinition;
+//#endregion
+export { AreaChart, AreaChartProps, BarChart, BarChartProps, type CartesianChartProps, type ChartCurveName, type ChartDefinition, ChartFrame, ChartFrameProps, ChartLegend, ChartLegendItem, ChartLegendProps, type ChartPoint, type ChartSeries, type ChartTheme, type ChartValue, type ChartXValue, type DomChartDefinition, HextechChart, HextechChartProps, LineChart, LineChartProps, RankingChart, RankingChartProps, areaY, barX, barY, crosshair, d3Curve, defineChart, dot, group, hextechChartTheme, hextechPalette, hextechPaletteSize, hextechScatterPaletteSize, hextechSeriesColor, hextechStatusColors, lineX, lineY, linearCurve, rect, ruleX, ruleY, scaleBand, scaleLinear, scaleOrdinal, scalePoint, smoothCurve, stack, stepCurve, text, tickX, tickY, tooltip, withHextechTheme };
+//# sourceMappingURL=charts.d.mts.map