@misoto22/design 0.5.0 → 0.6.1

package/dist/charts/BarChart/BarChart.d.ts

@@ -0,0 +1,179 @@
+import { ChartTooltipSlotProps, ChartLegendSlotProps } from '../AreaChart/AreaChart.js';
+import * as react from 'react';
+import { ReactNode, ComponentProps } from 'react';
+import { BarChart as BarChart$1, Bar, XAxis, YAxis, CartesianGrid } from 'recharts';
+import { ChartConfig } from '../lib/chart.js';
+import { ChartEmptyProps } from '../lib/empty.js';
+import { ValuesProps } from '../lib/values.js';
+import { SonifyProps } from '../lib/sonify-control.js';
+import { ChartBackgroundVariant } from '../lib/background.js';
+import { BrushProps } from '../lib/brush.js';
+import { ToolbarProps } from '../lib/toolbar.js';
+import { ChartRevealType } from '../lib/paint.js';
+import { ReferenceLine, ReferenceBand, Annotation } from '../lib/annotations.js';
+import '../lib/dot.js';
+import '../lib/legend.js';
+import '../lib/tooltip.js';
+import 'recharts/types/component/DefaultTooltipContent';
+import '../lib/sonify.js';
+import '../lib/zoom.js';
+import '../lib/figure.js';
+
+/**
+ * The axis props, with `label` narrowed to a string.
+ *
+ * Recharts' own `label` accepts a render function and a config object, neither
+ * of which a call site should be reaching for to name an axis — and both of
+ * which would let a consumer opt out of the system's own axis type styling
+ * without noticing.
+ */
+type ChartXAxisProps = Omit<ComponentProps<typeof XAxis>, 'label'> & {
+    /** What this axis measures. Say the unit here or in the series label, once. */
+    label?: string;
+};
+type ChartYAxisProps = Omit<ComponentProps<typeof YAxis>, 'label'> & {
+    /** What this axis measures. Say the unit here or in the series label, once. */
+    label?: string;
+};
+
+/** How a bar meets the plot. The primary carrier of identity in monochrome. */
+type BarVariant = 'default' | 'hatched' | 'duotone' | 'duotone-reverse' | 'gradient' | 'stripped';
+/** How several bars combine: side by side, stacked, or normalised to 100%. */
+type BarStackType = 'default' | 'stacked' | 'percent';
+/**
+ * Which way the bars run.
+ *
+ * `vertical` stands them up from a category axis along the bottom — the default,
+ * and what a time series wants. `horizontal` lays them out from a category axis
+ * down the side, which is what long category NAMES want: a label that would be
+ * rotated 45° to fit under a column reads straight beside a row.
+ */
+type BarOrientation = 'vertical' | 'horizontal';
+type ValidateKeys<TData, TConfig> = {
+    [K in keyof TConfig]: K extends keyof TData ? ChartConfig[string] : never;
+};
+interface BarChartProps<TData extends Record<string, unknown>, TConfig extends Record<string, ChartConfig[string]>> {
+    config: TConfig & ValidateKeys<TData, TConfig>;
+    /** The rows the chart draws. One entry per point, bar or category. */
+    data: TData[];
+    /**
+     * What the chart shows, in a sentence a reader could act on. Required, and
+     * announced to a screen reader even when it is not printed.
+     */
+    title: string;
+    /** Prints the title above the plot instead of hiding it from sight. */
+    showTitle?: boolean;
+    /** A line under the title — the unit, the window, the caveat. */
+    description?: ReactNode;
+    /**
+     * The composed parts — axes, grid, tooltip, legend, and the marks
+     * themselves.
+     */
+    children: ReactNode;
+    /** Merged onto the figure, last, so a call site can size or space it. */
+    className?: string;
+    /** Escape hatch onto the raw Recharts chart element. */
+    chartProps?: ComponentProps<typeof BarChart$1>;
+    /** How several marks combine: side by side, stacked, or normalised to 100%. */
+    stackType?: BarStackType;
+    /**
+     * Which way the bars run. Reach for `horizontal` when the category names are
+     * long enough to need rotating under a column.
+     */
+    orientation?: BarOrientation;
+    /** The corner every `<BarChart.Bar>` inherits. */
+    barRadius?: number;
+    /** The grow-in order every `<BarChart.Bar>` inherits. */
+    animationType?: ChartRevealType;
+    /** Gap between bars inside one category. */
+    barGap?: number;
+    /** Gap between categories. */
+    barCategoryGap?: number;
+    /** The series lit on first render. Selection dims every other series. */
+    defaultSelectedDataKey?: string | null;
+    /** Fires when the selection changes, and with null when it is cleared. */
+    onSelectionChange?: (selectedDataKey: string | null) => void;
+    /**
+     * Swaps the marks for an animated skeleton, keeping the measured height so
+     * the page does not jump when the data lands.
+     */
+    isLoading?: boolean;
+    /** How many bars the skeleton draws. */
+    loadingBars?: number;
+    /**
+     * The row field on the category axis. Needed by the brush and by the table
+     * view.
+     */
+    xDataKey?: keyof TData & string;
+    /**
+     * Drops the hidden table view. Only correct when the page prints the data
+     * itself.
+     */
+    hideDataTable?: boolean;
+    /**
+     * What the chart shows when it has nothing to draw.
+     *
+     * Rendered instead of the plot whenever `data` is empty and the chart is not
+     * loading — the state a real dashboard reaches within a week, and the one an
+     * empty pair of axes is indistinguishable from a failed load. `false` keeps
+     * the axes, for a chart whose emptiness is itself the reading.
+     */
+    empty?: ChartEmptyProps | false;
+}
+/**
+ * Discrete categories compared by length — the shape for "how much, per thing".
+ *
+ * Reach for `<AreaChart>` or `<LineChart>` when the axis is continuous and the
+ * reader is following a trend rather than comparing buckets.
+ *
+ * @example
+ * <BarChart title="Visitors by month" config={config} data={data} xDataKey="month">
+ *   <BarChart.Grid />
+ *   <BarChart.XAxis dataKey="month" />
+ *   <BarChart.Tooltip />
+ *   <BarChart.Bar dataKey="desktop" variant="duotone" />
+ * </BarChart>
+ */
+declare function BarChart<TData extends Record<string, unknown>, TConfig extends Record<string, ChartConfig[string]>>({ config, data, title, showTitle, description, children, className, chartProps, stackType, orientation, barRadius, animationType, barGap, barCategoryGap, defaultSelectedDataKey, onSelectionChange, isLoading, loadingBars, xDataKey, hideDataTable, empty, }: BarChartProps<TData, TConfig>): react.JSX.Element;
+declare namespace BarChart {
+    var Bar: ({ dataKey, variant, radius, animationType, isClickable, enableHoverHighlight, glowing, buffer, children, barProps, }: BarProps) => react.JSX.Element | null;
+    var XAxis: ({ tickLine, axisLine, tickMargin, minTickGap, type, label, ...rest }: ChartXAxisProps) => react.JSX.Element | null;
+    var YAxis: ({ tickLine, axisLine, tickMargin, minTickGap, width, type, label, tickFormatter, ...rest }: ChartYAxisProps) => react.JSX.Element | null;
+    var Grid: ({ strokeDasharray, vertical, horizontal, ...rest }: ComponentProps<typeof CartesianGrid>) => react.JSX.Element;
+    var Tooltip: ({ variant, roundness, defaultIndex, cursor }: ChartTooltipSlotProps) => react.JSX.Element | null;
+    var Legend: ({ variant, align, verticalAlign, isClickable, }: ChartLegendSlotProps) => react.JSX.Element;
+    var Background: ({ variant }: {
+        variant: ChartBackgroundVariant;
+    }) => react.JSX.Element | null;
+    var ReferenceLine: typeof ReferenceLine;
+    var ReferenceBand: typeof ReferenceBand;
+    var Annotation: typeof Annotation;
+    var Values: react.FC<ValuesProps>;
+    var Brush: react.FC<BrushProps>;
+    var Toolbar: react.FC<ToolbarProps>;
+    var Sonify: react.FC<SonifyProps>;
+}
+interface BarProps {
+    dataKey: string;
+    variant?: BarVariant;
+    radius?: number;
+    animationType?: ChartRevealType;
+    /** Lets a click on this series select it, dimming the rest. */
+    isClickable?: boolean;
+    /** Dims this series while another bar in the same column is hovered. */
+    enableHoverHighlight?: boolean;
+    /** A halo behind the bars — for the one series that is the point of the figure. */
+    glowing?: boolean;
+    /**
+     * Draws the LAST category as an open hatch rather than a solid bar.
+     *
+     * The idiom for a period still in progress: the bar is the same height as any
+     * other but is visibly not the same kind of fact.
+     */
+    buffer?: boolean;
+    /** `<BarChart.Values>`. */
+    children?: ReactNode;
+    barProps?: ComponentProps<typeof Bar>;
+}
+
+export { BarChart, type BarChartProps, type BarOrientation, type BarProps, type BarStackType, type BarVariant, type ChartXAxisProps, type ChartYAxisProps, BarChart as default };