@giddaa-housing/ui 0.1.0

package/dist/funnel-chart.d.ts

@@ -0,0 +1,84 @@
+import * as React from 'react';
+import { ChartCard, ChartValueType } from './chart.js';
+import { ComponentSize } from './size-context.js';
+import 'class-variance-authority/types';
+import 'class-variance-authority';
+import 'recharts';
+
+/**
+ * A staged conversion chart for drop-off analytics. Two renderings share one
+ * component — `funnel` draws connected, edge-sharing trapezoids (recharts
+ * `FunnelChart`) that narrow top-down; `bars` draws flush, left-aligned tracks
+ * (recharts `BarChart`, vertical layout) over a faint 100 % reference, using
+ * recharts' built-in `Bar` `background`. Both read top-down as the audience
+ * drops off, and both reuse the same stage data, palette, value-label column,
+ * legend, frame, and tooltip — only the inner plot differs (the same split as
+ * `Sparkline`). Per the chart architecture the recharts primitives are rendered
+ * directly here, never wrapped.
+ *
+ * @example
+ * <FunnelChart
+ *   data={[
+ *     { label: "Applied", value: 1000 },
+ *     { label: "Pre-qualified", value: 720 },
+ *     { label: "Closed", value: 110 },
+ *   ]}
+ *   title="Application drop-off"
+ *   description="V3 analytics · last 30 days"
+ *   tooltip
+ * />
+ */
+/** Funnel sizes line up with the three shared `ComponentSize` values. */
+type FunnelChartSize = ComponentSize;
+/** Plot rendering — connected trapezoids or flush-stacked bars. */
+type FunnelChartType = "funnel" | "bars";
+/** Where the colour-key legend sits relative to the plot. */
+type FunnelLegendPlacement = "right" | "bottom";
+type FunnelStage = {
+    /** Stage name, e.g. "Applied". */
+    label: string;
+    /** Absolute count reaching this stage. */
+    value: number;
+    /** Segment colour; defaults to the palette in stage order. */
+    fill?: string;
+};
+/**
+ * Stage palette, ordered top-of-funnel → bottom: forest → brass → moss → clay →
+ * stone. Giddaa has no `chart-1`…`chart-N` tokens yet, so these map to the brand
+ * scales; assign by order, or override per stage with `fill`.
+ */
+declare const FUNNEL_CHART_PALETTE: readonly ["var(--color-forest-700)", "var(--color-brass-500)", "var(--color-moss-600)", "var(--color-clay-500)", "var(--color-stone-500)"];
+type FunnelChartLayout = {
+    /** Plot box height in px. */
+    height: number;
+    /** Plot box width in px — the funnel/bars column; labels + legend flow after. */
+    width: number;
+    /** Corner radius for the `bars` rendering. */
+    barRadius: number;
+    /** Bar thickness cap for the `bars` rendering. */
+    barMaxSize: number;
+};
+declare const FUNNEL_CHART_LAYOUT: Record<FunnelChartSize, FunnelChartLayout>;
+type FunnelChartProps = Omit<React.ComponentProps<typeof ChartCard>, "size" | "children"> & {
+    /** Stages in funnel order — the widest (top) stage first. */
+    data: FunnelStage[];
+    /** Plot rendering. Defaults to `funnel`. */
+    type?: FunnelChartType;
+    /** Explicit size; otherwise inherited from the nearest `SizeProvider`. */
+    size?: FunnelChartSize;
+    /** Chart heading. Omit to hide the title. */
+    title?: React.ReactNode;
+    /** Supporting metadata (period, source). Omit to hide the description. */
+    description?: React.ReactNode;
+    /** Enable the hover value tooltip. Default false. */
+    tooltip?: boolean;
+    /** Legend placement — a right column or a wrapped bottom row. Default right. */
+    legend?: FunnelLegendPlacement;
+    /** Format the absolute count in the value label and tooltip. */
+    valueFormatter?: (value: number) => string;
+    /** Value formatting for the tooltip. Defaults to `number`. */
+    valueType?: ChartValueType;
+};
+declare function FunnelChart({ data, type, size, title, description, tooltip, legend, valueFormatter, valueType, className, ...props }: FunnelChartProps): React.JSX.Element;
+
+export { FUNNEL_CHART_LAYOUT, FUNNEL_CHART_PALETTE, FunnelChart, type FunnelChartLayout, type FunnelChartProps, type FunnelChartSize, type FunnelChartType, type FunnelLegendPlacement, type FunnelStage };