@gridui/chart 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @gridui/chart
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Composable line and bar charts in the Data family. Import components from
+`@gridui/chart` and load `@gridui/chart/styles.css` after Theme.
+
+LineChart and BarChart own data and selection. ChartPlot, ChartGrid, ChartXAxis,
+ChartYAxis, LineSeries, BarSeries, ChartValueLabels, ChartCursor and ChartTooltip
+compose the actual chart. There are no whole-chart visual variants.
+
+```tsx
+<LineChart label="Requests per day" data={observations}>
+    <ChartPlot>
+        <ChartGrid />
+        <ChartXAxis />
+        <ChartYAxis />
+        <LineSeries points={{ shape: "square", size: 5 }} />
+        <ChartValueLabels visibility="all" />
+    </ChartPlot>
+</LineChart>
+```
+
+Bar gaps are preferred pixel spacing: they shrink when necessary to keep positive
+values visible within their category bands.
+
+Each observation has a stable nonempty `id`, `x` (string, number or Date), and `y`
+(finite number or null). Category coordinates preserve order. LineChart's
+`xScale="time"` and `"linear"` sort observations and preserve proportional gaps.
+Null breaks a line; zero remains data. Value domains include zero and all values.
+Explicit domains must be finite and increasing, and cannot clip data or zero.
+
+Charts fill their container. `height` defaults to 300px and must be at least
+160px. Plot padding reserves space for axes and labels; callers provide more
+padding for long formatted labels or relocated axes. If padding leaves no plotting
+space, the chart retains its accessible data description and resumes drawing
+when space becomes available. Use modest SVG datasets.
+Applications own aggregation, localized formatters and loading/empty content.
+
+Axes accept `tickCount` (an integer of at least two) or `tickValues` (exact values,
+with precedence over the count). Continuous counts divide the domain evenly;
+category counts sample existing observations and preserve endpoints. Explicit
+values outside the domain or missing categories are ignored; repeated continuous
+values are deduplicated. `tickValues={[]}` hides ticks. Time tick formatters receive
+Date values. Share the same options with `ChartGrid.xTicks` / `yTicks` to align
+reference lines with axes; these always use screen directions.
+
+Tick lines remain visible when their labels collide. Axis and value labels use
+actual SVG text bounds; tooltips wrap using measured text widths. Layout updates
+on resize and font changes. Visual labels need browser measurement; SSR retains
+the complete accessible data description. Plot padding remains caller-controlled.
+
+`defaultSelectedId` enables local selection. `selectedId` and
+`onSelectionChange` support controlled selection. Hover/focus is transient and
+independent from selection. Pointer inspection temporarily overrides keyboard
+inspection; leaving a mark restores the focused observation. Enter/Space toggles
+once per press, Escape clears. Missing or
+removed selected IDs show no selection without emitting a callback.
+`formatDatum` controls accessible names and default tooltip text.
+
+Local CSS variables map to Theme: `--gridui-chart-background`, `-grid`, `-axis`,
+`-label`, `-value`, `-series`, `-selected`, and `-point-background` (all share the
+`--gridui-chart` prefix). Part props override their respective default tokens.
+Keep cards, summaries and tables outside Chart; Grid owns surrounding seams.
+
+See [component ownership](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/docs/component-ownership.md),
+[component reference](docs/reference/README.md), and
+[release history](https://github.com/sudo-ui/GridUI-React-Monorepo/tree/main/packages-data/chart/.changeset/history).

package/dist/bar-chart/bar-chart.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @author WMXPY
+ * @package GridUI
+ * @namespace BarChart
+ * @description Bar Chart
+ */
+import type { ChartOptions } from "../shared/types";
+import type { FC } from "react";
+export type BarChartProps = ChartOptions & {
+    readonly orientation?: "vertical" | "horizontal";
+};
+export declare const BarChart: FC<BarChartProps>;

package/dist/bar-series/bar-series.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @author WMXPY
+ * @package GridUI
+ * @namespace BarSeries
+ * @description Bar Series
+ */
+import type { CSSProperties, FC } from "react";
+export type BarSeriesProps = {
+    readonly color?: CSSProperties["color"];
+    readonly selectedColor?: CSSProperties["color"];
+    readonly width?: number;
+    readonly widthRatio?: number;
+    readonly gap?: number;
+    readonly opacity?: number;
+    readonly inactiveOpacity?: number;
+};
+export declare const BarSeries: FC<BarSeriesProps>;

package/dist/chart-cursor/chart-cursor.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @author WMXPY
+ * @package GridUI
+ * @namespace ChartCursor
+ * @description Chart Cursor
+ */
+import type { CSSProperties, FC } from "react";
+export type ChartCursorProps = {
+    readonly color?: CSSProperties["color"];
+    readonly strokeWidth?: number;
+    readonly dashArray?: string;
+};
+export declare const ChartCursor: FC<ChartCursorProps>;

package/dist/chart-grid/chart-grid.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @author WMXPY
+ * @package GridUI
+ * @namespace ChartGrid
+ * @description Chart Grid
+ */
+import type { ChartTickOptions } from "../shared/types";
+import type { CSSProperties, FC } from "react";
+export type ChartGridProps = {
+    readonly xTicks?: ChartTickOptions;
+    readonly yTicks?: ChartTickOptions;
+    readonly horizontal?: boolean;
+    readonly vertical?: boolean;
+    readonly color?: CSSProperties["color"];
+    readonly strokeWidth?: number;
+    readonly dashArray?: string;
+};
+export declare const ChartGrid: FC<ChartGridProps>;

package/dist/chart-plot/chart-plot.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @author WMXPY
+ * @package GridUI
+ * @namespace ChartPlot
+ * @description Chart Plot
+ */
+import type { CSSProperties, FC, ReactNode } from "react";
+export type ChartPlotProps = {
+    readonly children: ReactNode;
+    readonly background?: CSSProperties["fill"];
+    readonly padding?: Partial<Record<"top" | "right" | "bottom" | "left", number>>;
+};
+export declare const ChartPlot: FC<ChartPlotProps>;

package/dist/chart-tooltip/chart-tooltip.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @author WMXPY
+ * @package GridUI
+ * @namespace ChartTooltip
+ * @description Chart Tooltip
+ */
+import type { ChartDatum } from "../shared/types";
+import type { CSSProperties, FC } from "react";
+export type ChartTooltipProps = {
+    readonly format?: (datum: ChartDatum) => string;
+    readonly background?: CSSProperties["color"];
+    readonly color?: CSSProperties["color"];
+};
+export declare const ChartTooltip: FC<ChartTooltipProps>;

package/dist/chart-tooltip/layout.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @author WMXPY
+ * @package GridUI
+ * @namespace ChartTooltip
+ * @description Layout
+ */
+import type { PlotState } from "../shared/context";
+import type { ChartDatum } from "../shared/types";
+import type { MeasureText } from "../shared/use-measured-layout";
+type TooltipLayout = {
+    readonly lines: readonly {
+        readonly text: string;
+        readonly x: number;
+        readonly y: number;
+    }[];
+    readonly width: number;
+    readonly height: number;
+};
+export declare const calculateTooltipLayout: (text: string | null, plotWidth: number, measure: MeasureText) => TooltipLayout | null;
+type TooltipPositionOptions = {
+    readonly datum: ChartDatum | undefined;
+    readonly horizontal: boolean;
+    readonly plot: Pick<PlotState, "width" | "height" | "category" | "value">;
+    readonly width: number;
+    readonly height: number;
+};
+export declare const calculateTooltipPosition: (options: TooltipPositionOptions) => {
+    readonly x: number;
+    readonly y: number;
+};
+export {};

package/dist/chart-value-labels/chart-value-labels.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @author WMXPY
+ * @package GridUI
+ * @namespace ChartValueLabels
+ * @description Chart Value Labels
+ */
+import type { ChartDatum } from "../shared/types";
+import type { CSSProperties, FC } from "react";
+export type ChartValueLabelsProps = {
+    readonly visibility?: "all" | "selected" | "none";
+    readonly position?: "end" | "center";
+    readonly format?: (value: number, datum: ChartDatum) => string;
+    readonly color?: CSSProperties["color"];
+    readonly fontSize?: number;
+    readonly offset?: number;
+};
+export declare const ChartValueLabels: FC<ChartValueLabelsProps>;

package/dist/chart-value-labels/layout.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @author WMXPY
+ * @package GridUI
+ * @namespace ChartValueLabels
+ * @description Layout
+ */
+import type { PlotState } from "../shared/context";
+import type { ChartDatum } from "../shared/types";
+import type { MeasureText } from "../shared/use-measured-layout";
+type ValueLabelLayoutOptions = {
+    readonly data: readonly ChartDatum[];
+    readonly selectedId: string | null;
+    readonly horizontal: boolean;
+    readonly plot: Pick<PlotState, "width" | "height" | "category" | "value">;
+    readonly visibility: "all" | "selected" | "none";
+    readonly position: "end" | "center";
+    readonly format: (value: number, datum: ChartDatum) => string;
+    readonly offset: number;
+    readonly measure: MeasureText;
+};
+type ValueLabel = {
+    readonly id: string;
+    readonly text: string;
+    readonly x: number;
+    readonly y: number;
+};
+export declare const calculateValueLabelLayout: (options: ValueLabelLayoutOptions) => ValueLabel[];
+export {};

package/dist/chart-x-axis/chart-x-axis.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @author WMXPY
+ * @package GridUI
+ * @namespace ChartXAxis
+ * @description Chart X Axis
+ */
+import type { ChartAxisOptions } from "../shared/types";
+import type { FC } from "react";
+export type ChartXAxisProps = ChartAxisOptions & {
+    readonly position?: "top" | "bottom";
+};
+export declare const ChartXAxis: FC<ChartXAxisProps>;

package/dist/chart-y-axis/chart-y-axis.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @author WMXPY
+ * @package GridUI
+ * @namespace ChartYAxis
+ * @description Chart Y Axis
+ */
+import type { ChartAxisOptions } from "../shared/types";
+import type { FC } from "react";
+export type ChartYAxisProps = ChartAxisOptions & {
+    readonly position?: "left" | "right";
+};
+export declare const ChartYAxis: FC<ChartYAxisProps>;

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @author WMXPY
+ * @package GridUI
+ * @namespace Root
+ * @description Index
+ */
+export type { BarChartProps } from "./bar-chart/bar-chart";
+export { BarChart } from "./bar-chart/bar-chart";
+export type { BarSeriesProps } from "./bar-series/bar-series";
+export { BarSeries } from "./bar-series/bar-series";
+export type { ChartCursorProps } from "./chart-cursor/chart-cursor";
+export { ChartCursor } from "./chart-cursor/chart-cursor";
+export type { ChartGridProps } from "./chart-grid/chart-grid";
+export { ChartGrid } from "./chart-grid/chart-grid";
+export type { ChartPlotProps } from "./chart-plot/chart-plot";
+export { ChartPlot } from "./chart-plot/chart-plot";
+export type { ChartTooltipProps } from "./chart-tooltip/chart-tooltip";
+export { ChartTooltip } from "./chart-tooltip/chart-tooltip";
+export type { ChartValueLabelsProps } from "./chart-value-labels/chart-value-labels";
+export { ChartValueLabels } from "./chart-value-labels/chart-value-labels";
+export type { ChartXAxisProps } from "./chart-x-axis/chart-x-axis";
+export { ChartXAxis } from "./chart-x-axis/chart-x-axis";
+export type { ChartYAxisProps } from "./chart-y-axis/chart-y-axis";
+export { ChartYAxis } from "./chart-y-axis/chart-y-axis";
+export type { LineChartProps } from "./line-chart/line-chart";
+export { LineChart } from "./line-chart/line-chart";
+export type { LineSeriesProps } from "./line-series/line-series";
+export { LineSeries } from "./line-series/line-series";
+export type { ChartDatum, ChartPointOptions, ChartScale, ChartTickOptions } from "./shared/types";