@giddaa-housing/ui 1.0.0 → 1.2.0

package/dist/line-chart.d.ts

@@ -1,155 +1,226 @@
-import { ComponentSize } from './size-context.js';
-import 'react';
-
+import { t as ComponentSize } from "./size-context-D4mYvcg8.js";
+import { ChartConfig } from "./chart.js";
+import * as React from "react";
+import { Area, AreaChart as AreaChart$1, CartesianGrid, Line, LineChart as LineChart$1, XAxis, YAxis } from "recharts";
+//#region src/line-chart.d.ts
 /**
- * Line charts are composed from recharts plot primitives directly — recharts
- * identifies `Line`, `Area`, `XAxis`, `YAxis`, and `CartesianGrid` by component
- * identity and cannot be wrapped. This module supplies giddaa-specific defaults
- * that would otherwise be copy-pasted into every line chart: per-size layout
- * numbers. Pair them with the shared frame and overlays from `./chart`.
+ * Line and area charts are composable wrappers over the recharts cartesian
+ * primitives. recharts 3 registers graphical items through context when they
+ * render, so the primitives CAN be wrapped in our own components. Each wrapper
+ * bakes in the giddaa defaults (tokens, size-scaled type, mark specs) and
+ * forwards every recharts prop, so anything can be overridden in place or
+ * replaced with the raw recharts element.
  *
- * Five sizes (sm → huge) extend the three `ComponentSize` values used elsewhere.
- * xl and huge must be passed explicitly — they cannot be inherited from
- * `SizeProvider` since `ComponentSize` only carries sm/md/lg.
- *
- * Tokens:
- * - Primary series stroke + dots + area fill: `var(--color-surface-brand)`
- * - Comparison series: `var(--color-surface-accent)`
- * - Gridlines: `var(--color-line-subtle)`
- * - Area wash: primary series colour at 15 % opacity (`fillOpacity={0.15}`)
- * - Active-dot ring: `var(--color-surface-raised)` stroke (matches card bg)
+ * Anatomy: `LineChart`/`AreaChart` are the plot roots (frame + responsive box +
+ * recharts chart); compose the grid, axes, series, and the shared overlays from
+ * `./chart` as children. Both roots share the same axis and grid wrappers.
  *
  * @example
- * const chart = useLineChartLayout();
  * <ChartCard size="md">
  *   <ChartHeader>
  *     <ChartTitle>Revenue Overview</ChartTitle>
  *     <ChartDescription>Monthly revenue · Jan–Jul</ChartDescription>
  *   </ChartHeader>
- *   <ChartContainer config={config} {...chart.container}>
- *     <AreaChart data={data} {...chart.chart}>
- *       <CartesianGrid vertical={false} stroke="var(--color-line-subtle)" />
- *       <XAxis dataKey="month" {...chart.xAxis} />
- *       <YAxis {...chart.yAxis} />
- *       <ChartLegend verticalAlign="top" content={<ChartLegendContent marker="line" />} />
- *       <ChartTooltip content={<ChartTooltipContent />} />
- *       <Area dataKey="revenue" {...chart.area("var(--color-revenue)")} />
- *     </AreaChart>
- *   </ChartContainer>
+ *   <AreaChart config={config} data={data}>
+ *     <LineChartGrid />
+ *     <LineChartXAxis dataKey="month" />
+ *     <LineChartYAxis />
+ *     <ChartTooltip content={<ChartTooltipContent />} />
+ *     <AreaChartSeries dataKey="revenue" name="Revenue" />
+ *   </AreaChart>
  * </ChartCard>
  */
-/** Five sizes for line charts — extends ComponentSize with xl and huge. */
+/**
+ * Categorical series palette — the theme-aware `chart-1`…`chart-3` tokens.
+ * Assign colours in this fixed order, never cycled: a fourth series folds into
+ * "Other" or becomes a second chart.
+ */
+declare const LINE_CHART_PALETTE: readonly ["var(--color-chart-1)", "var(--color-chart-2)", "var(--color-chart-3)"];
+/**
+ * Five sizes for line/area charts — extends the three shared `ComponentSize`
+ * values with `xl` and `huge` for hero trend panels. `xl`/`huge` scale the plot
+ * height and margins on the *root only*; the child series and axes resolve to
+ * `lg` marks (identical from `lg` up), so they never need the extended union.
+ */
 type LineChartSize = "sm" | "md" | "lg" | "xl" | "huge";
 type LineChartLayout = {
-    /** Plot height in px. Width stays fluid via ResponsiveContainer. */
-    height: number;
-    /** Outer margin. Top leaves room above the highest data point. */
-    margin: {
-        top: number;
-        right: number;
-        bottom: number;
-        left: number;
-    };
-    /** Line stroke width in px. */
-    strokeWidth: number;
-    /** Radius of the resting data-point dot. */
-    dotRadius: number;
-    /** Radius of the active (hover) dot. */
-    activeDotRadius: number;
-    /** Axis tick label font size. */
-    tickFontSize: number;
-    /** Reserved width for the value (Y) axis. */
-    yAxisWidth: number;
-    /** Space between an axis and its tick labels. */
-    tickMargin: number;
+  /** Plot height in px. Width stays fluid via ResponsiveContainer. */
+  height: number;
+  /** Outer margin. Top leaves room above the highest data point. */
+  margin: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+  };
+  /** Line stroke width in px. */
+  strokeWidth: number;
+  /** Radius of the resting data-point dot. */
+  dotRadius: number;
+  /** Radius of the active (hover) dot. */
+  activeDotRadius: number;
+  /** Axis tick label font size. */
+  tickFontSize: number;
+  /** Reserved width for the value (Y) axis. */
+  yAxisWidth: number;
+  /** Space between an axis and its tick labels. */
+  tickMargin: number;
 };
 declare const LINE_CHART_LAYOUT: Record<LineChartSize, LineChartLayout>;
-/** Map the 5 line-chart sizes to the 3 ComponentSize values for ChartCard. */
+/** Clamp the 5 line-chart sizes to the 3 `ComponentSize` values for children. */
 declare function toComponentSize(size: LineChartSize): ComponentSize;
+/** Shared root knobs — series theming, plot scale, and the plot-box className. */
+type LineChartRootExtras = {
+  /** Series labels/icons for the shared tooltip and legend (see `ChartConfig`). */
+  config?: ChartConfig;
+  /** Plot scale; inherited from the nearest `SizeProvider` when omitted. */
+  size?: LineChartSize;
+  /** Applied to the responsive plot box, e.g. to override its height. */
+  className?: string;
+};
+type LineChartProps = Omit<React.ComponentProps<typeof LineChart$1>, "width" | "height"> & LineChartRootExtras;
+type AreaChartProps = Omit<React.ComponentProps<typeof AreaChart$1>, "width" | "height"> & LineChartRootExtras;
 /**
- * Resolve the line-chart layout for an explicit or inherited component size. The
- * returned object groups the giddaa defaults by the recharts component they
- * belong to. `line(color)`/`area(color)` return the full series props for a
- * given colour — spread each onto its element, then pass the data-specific props
- * (`config`, `data`, `dataKey`, …) directly afterwards to add or override:
- *
- *   const chart = useLineChartLayout(size);
- *   <ChartContainer config={config} {...chart.container}>
- *     <AreaChart data={data} {...chart.chart}>
- *       <XAxis dataKey="month" {...chart.xAxis} />
- *       <YAxis {...chart.yAxis} />
- *       <Area dataKey="revenue" {...chart.area("var(--color-revenue)")} />
+ * Plot root — wraps the shared `ChartContainer` (tooltip/legend theming,
+ * responsive box) around the recharts `LineChart` with a size-scaled height and
+ * margin. `size` flows to the child primitives through `SizeProvider` (clamped
+ * to `lg` for `xl`/`huge`). Extra props reach the recharts chart (`data`,
+ * `syncId`, …).
+ */
+declare function LineChart({ config, size, className, children, ...props }: LineChartProps): React.JSX.Element;
+/**
+ * Plot root for filled trends — identical to `LineChart` but wraps the recharts
+ * `AreaChart`, so it hosts `AreaChartSeries` (and the same grid/axes/overlays).
+ */
+declare function AreaChart({ config, size, className, children, ...props }: AreaChartProps): React.JSX.Element;
+type LineChartGridProps = React.ComponentProps<typeof CartesianGrid>;
+/**
+ * Value reference lines — recharts `CartesianGrid` with vertical lines hidden
+ * and the visible grid painted with the `line` token (`line-subtle` matches the
+ * chart card surface in both themes, so it would vanish).
+ */
+declare function LineChartGrid(props: LineChartGridProps): React.JSX.Element;
+type LineChartXAxisProps = React.ComponentProps<typeof XAxis> & {
+  /** Explicit axis scale; otherwise inherited from the chart's `size`. */
+  size?: LineChartSize;
+};
+type LineChartYAxisProps = React.ComponentProps<typeof YAxis> & {
+  /** Explicit axis scale; otherwise inherited from the chart's `size`. */
+  size?: LineChartSize;
+};
+/**
+ * Category (time) axis — recharts `XAxis` with no axis/tick lines, a size-scaled
+ * tick margin, and caption-placeholder tick ink. Passing your own `tick`
+ * replaces the default styling entirely.
+ */
+declare function LineChartXAxis({ size, tick, ...props }: LineChartXAxisProps): React.JSX.Element;
+/**
+ * Value axis — recharts `YAxis` with no axis/tick lines, size-scaled tick type,
+ * and reserved width for value labels. Override `width` for long labels.
+ */
+declare function LineChartYAxis({ size, tick, ...props }: LineChartYAxisProps): React.JSX.Element;
+type LineChartSeriesProps = React.ComponentProps<typeof Line> & {
+  /** Series colour for the stroke and dots. Defaults to the first chart token. */
+  color?: string;
+  /** Explicit mark scale; otherwise inherited from the chart's `size`. */
+  size?: LineChartSize;
+};
+/**
+ * One line series — recharts `Line` with the giddaa mark spec: a 2px rounded
+ * stroke in `color`, solid resting dots, and a hover dot ringed in
+ * `surface-raised` so overlapping series stay separable. `color` drives all of
+ * them at once; `stroke`/`dot`/`activeDot` still win when passed directly.
+ */
+declare function LineChartSeries({ color, size, dot, activeDot, ...props }: LineChartSeriesProps): React.JSX.Element;
+type AreaChartSeriesProps = React.ComponentProps<typeof Area> & {
+  /** Series colour for the stroke, wash, and dots. Defaults to the first chart token. */
+  color?: string;
+  /** Explicit mark scale; otherwise inherited from the chart's `size`. */
+  size?: LineChartSize;
+};
+/**
+ * One area series — recharts `Area` with the giddaa mark spec: the same rounded
+ * 2px stroke and dots as `LineChartSeries`, plus the series colour washed to 15%
+ * beneath the stroke. `color` drives stroke + fill + dots at once;
+ * `stroke`/`fill`/`dot` still win when passed directly.
+ */
+declare function AreaChartSeries({ color, size, dot, activeDot, ...props }: AreaChartSeriesProps): React.JSX.Element;
+/**
+ * @deprecated Compose the `<LineChart>`/`<AreaChart>` primitives instead — see
+ * the module example. This layout hook predates recharts 3 wrapping support and
+ * will be removed in the next major. It returns prop bags to spread onto raw
+ * recharts elements.
  */
 declare function useLineChartLayout(size?: LineChartSize): {
-    container: {
-        className: string;
-        style: {
-            height: number;
-        };
+  container: {
+    className: string;
+    style: {
+      height: number;
+    };
+  };
+  chart: {
+    accessibilityLayer: boolean;
+    margin: {
+      top: number;
+      right: number;
+      bottom: number;
+      left: number;
+    };
+  };
+  xAxis: {
+    readonly tickLine: false;
+    readonly axisLine: false;
+    readonly tickMargin: number;
+    readonly tick: {
+      fontSize: number;
     };
-    chart: {
-        accessibilityLayer: boolean;
-        margin: {
-            top: number;
-            right: number;
-            bottom: number;
-            left: number;
-        };
+  };
+  yAxis: {
+    readonly tickLine: false;
+    readonly axisLine: false;
+    readonly width: number;
+    readonly tick: {
+      fontSize: number;
     };
-    xAxis: {
-        readonly tickLine: false;
-        readonly axisLine: false;
-        readonly tickMargin: number;
-        readonly tick: {
-            fontSize: number;
-        };
+  };
+  line: (color: string) => {
+    type: "linear";
+    stroke: string;
+    strokeWidth: number;
+    strokeLinejoin: "round";
+    strokeLinecap: "round";
+    dot: {
+      r: number;
+      fill: string;
+      strokeWidth: number;
     };
-    yAxis: {
-        readonly tickLine: false;
-        readonly axisLine: false;
-        readonly width: number;
-        readonly tick: {
-            fontSize: number;
-        };
+    activeDot: {
+      r: number;
+      fill: string;
+      stroke: string;
+      strokeWidth: number;
     };
-    line: (color: string) => {
-        type: "linear";
-        stroke: string;
-        strokeWidth: number;
-        strokeLinejoin: "round";
-        strokeLinecap: "round";
-        dot: {
-            r: number;
-            fill: string;
-            strokeWidth: number;
-        };
-        activeDot: {
-            r: number;
-            fill: string;
-            stroke: string;
-            strokeWidth: number;
-        };
+  };
+  area: (color: string) => {
+    type: "linear";
+    stroke: string;
+    strokeWidth: number;
+    strokeLinejoin: "round";
+    strokeLinecap: "round";
+    dot: {
+      r: number;
+      fill: string;
+      strokeWidth: number;
     };
-    area: (color: string) => {
-        fill: string;
-        fillOpacity: number;
-        type: "linear";
-        stroke: string;
-        strokeWidth: number;
-        strokeLinejoin: "round";
-        strokeLinecap: "round";
-        dot: {
-            r: number;
-            fill: string;
-            strokeWidth: number;
-        };
-        activeDot: {
-            r: number;
-            fill: string;
-            stroke: string;
-            strokeWidth: number;
-        };
+    activeDot: {
+      r: number;
+      fill: string;
+      stroke: string;
+      strokeWidth: number;
     };
+    fill: string;
+    fillOpacity: number;
+  };
 };
-
-export { LINE_CHART_LAYOUT, type LineChartLayout, type LineChartSize, toComponentSize, useLineChartLayout };
+//#endregion
+export { AreaChart, type AreaChartProps, AreaChartSeries, type AreaChartSeriesProps, LINE_CHART_LAYOUT, LINE_CHART_PALETTE, LineChart, LineChartGrid, type LineChartGridProps, type LineChartLayout, type LineChartProps, LineChartSeries, type LineChartSeriesProps, type LineChartSize, LineChartXAxis, type LineChartXAxisProps, LineChartYAxis, type LineChartYAxisProps, toComponentSize, useLineChartLayout };