@misoto22/folio 0.0.0 → 0.16.0

package/dist/charts/FunnelChart/FunnelChart.js

@@ -0,0 +1,137 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import {
+  createContext,
+  useContext,
+  useId,
+  useMemo
+} from "react";
+import {
+  Funnel as RechartsFunnel,
+  FunnelChart as RechartsFunnelChart,
+  LabelList
+} from "recharts";
+import { ChartContainer, colorStops, cssName } from "../lib/chart.js";
+import { ChartFigure } from "../lib/figure.js";
+import {} from "../lib/empty.js";
+import { ChartTooltip, ChartTooltipContent } from "../lib/tooltip.js";
+import { ColorStops } from "../lib/paint.js";
+const FunnelChartContext = createContext(null);
+function useFunnelChart() {
+  const context = useContext(FunnelChartContext);
+  if (!context) throw new Error("A funnel chart part must be rendered inside <FunnelChart>");
+  return context;
+}
+function FunnelChart({
+  config,
+  data,
+  dataKey,
+  nameKey,
+  title,
+  showTitle,
+  description,
+  children,
+  className,
+  chartProps,
+  hideDataTable = false,
+  empty
+}) {
+  const chartId = useId().replace(/:/g, "");
+  const context = useMemo(
+    () => ({ config, nameKey, dataKey, data }),
+    [config, data, dataKey, nameKey]
+  );
+  return /* @__PURE__ */ jsx(FunnelChartContext.Provider, { value: context, children: /* @__PURE__ */ jsx(
+    ChartFigure,
+    {
+      title,
+      showTitle,
+      description,
+      className,
+      table: hideDataTable ? false : { rows: data, rowKey: nameKey, columns: [{ key: dataKey, label: "Value" }] },
+      isEmpty: data.length === 0,
+      empty,
+      children: /* @__PURE__ */ jsx(ChartContainer, { config, children: /* @__PURE__ */ jsx(RechartsFunnelChart, { id: chartId, accessibilityLayer: true, ...chartProps, children }) })
+    }
+  ) });
+}
+function Funnel({
+  variant = "stepped",
+  orientation = "vertical",
+  gap = 2,
+  children,
+  funnelProps
+}) {
+  const { config, data, dataKey, nameKey } = useFunnelChart();
+  const chartId = useId().replace(/:/g, "");
+  const painted = data.map((row, index) => {
+    const name = String(row[nameKey]);
+    const slot = variant === "ramp" ? `var(--series-${index % 8 + 1})` : void 0;
+    return {
+      ...row,
+      fill: slot ?? (name in config ? `url(#${chartId}-stage-${cssName(name)})` : "var(--series-1)")
+    };
+  });
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
+      RechartsFunnel,
+      {
+        dataKey,
+        nameKey,
+        data: painted,
+        isAnimationActive: false,
+        stroke: "var(--chart-surface)",
+        strokeWidth: gap,
+        orientation,
+        ...funnelProps,
+        children
+      }
+    ),
+    /* @__PURE__ */ jsx("defs", { children: Object.entries(config).map(([key, series]) => /* @__PURE__ */ jsx(
+      "linearGradient",
+      {
+        id: `${chartId}-stage-${cssName(key)}`,
+        x1: "0",
+        y1: "0",
+        x2: "1",
+        y2: "0",
+        children: /* @__PURE__ */ jsx(ColorStops, { dataKey: cssName(key), stops: colorStops(series) })
+      },
+      key
+    )) })
+  ] });
+}
+function Label({ dataKey, position = "right", labelListProps }) {
+  const { nameKey } = useFunnelChart();
+  return /* @__PURE__ */ jsx(
+    LabelList,
+    {
+      dataKey: dataKey ?? nameKey,
+      position,
+      stroke: "none",
+      fontSize: 12,
+      className: "fill-(--ink)",
+      ...labelListProps
+    }
+  );
+}
+function Tooltip({ variant, roundness, defaultIndex }) {
+  const { nameKey } = useFunnelChart();
+  return /* @__PURE__ */ jsx(
+    ChartTooltip,
+    {
+      defaultIndex,
+      cursor: false,
+      content: /* @__PURE__ */ jsx(ChartTooltipContent, { nameKey, hideLabel: true, roundness, variant })
+    }
+  );
+}
+FunnelChart.Funnel = Funnel;
+FunnelChart.Label = Label;
+FunnelChart.Tooltip = Tooltip;
+var FunnelChart_default = FunnelChart;
+export {
+  FunnelChart,
+  FunnelChart_default as default
+};
+//# sourceMappingURL=FunnelChart.js.map

package/dist/charts/FunnelChart/FunnelChart.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/charts/FunnelChart/FunnelChart.tsx"],"sourcesContent":["'use client'\n\nimport {\n  createContext,\n  useContext,\n  useId,\n  useMemo,\n  type ComponentProps,\n  type ReactNode,\n} from 'react'\nimport {\n  Funnel as RechartsFunnel,\n  FunnelChart as RechartsFunnelChart,\n  LabelList,\n} from 'recharts'\nimport { ChartContainer, colorStops, cssName, type ChartConfig } from '../lib/chart'\nimport { ChartFigure } from '../lib/figure'\nimport { type ChartEmptyProps } from '../lib/empty'\nimport { ChartTooltip, ChartTooltipContent } from '../lib/tooltip'\nimport { ColorStops } from '../lib/paint'\nimport type { ChartTooltipSlotProps } from '../AreaChart/AreaChart'\n\n/**\n * How each stage is painted.\n *\n * `stepped` is the honest default: every stage keeps the same fill and the\n * TAPER carries the drop. A ramp that also darkens each stage encodes the same\n * fact twice and invites the reader to compare two things that are one.\n */\nexport type FunnelVariant = 'stepped' | 'ramp'\n\ninterface FunnelChartContextValue {\n  config: ChartConfig\n  nameKey: string\n  dataKey: string\n  data: Record<string, unknown>[]\n}\n\nconst FunnelChartContext = createContext<FunnelChartContextValue | null>(null)\n\nfunction useFunnelChart(): FunnelChartContextValue {\n  const context = useContext(FunnelChartContext)\n  if (!context) throw new Error('A funnel chart part must be rendered inside <FunnelChart>')\n  return context\n}\n\nexport interface FunnelChartProps<TData extends Record<string, unknown>> {\n  /** Stage names → their label and paint. Keys must match the `nameKey` values. */\n  config: ChartConfig\n  /** The stages, widest first. Order is the funnel; it is not sorted for you. */\n  data: TData[]\n  /** The row field holding each stage's number. */\n  dataKey: keyof TData & string\n  /** The row field naming each stage. */\n  nameKey: keyof TData & string\n  /**\n   * What the chart shows, in a sentence a reader could act on. Required, and\n   * announced to a screen reader even when it is not printed.\n   */\n  title: string\n  /** Prints the title above the plot instead of hiding it from sight. */\n  showTitle?: boolean\n  /** A line under the title — the unit, the window, the caveat. */\n  description?: ReactNode\n  /** The composed parts — `<Funnel>`, `<Tooltip>`. */\n  children: ReactNode\n  /** Merged onto the figure, last, so a call site can size or space it. */\n  className?: string\n  /** Escape hatch onto the raw Recharts chart element. */\n  chartProps?: ComponentProps<typeof RechartsFunnelChart>\n  /** Drops the hidden table view. Only correct when the page prints the data itself. */\n  hideDataTable?: boolean\n  /**\n   * What the chart shows when it has nothing to draw. `false` keeps the empty\n   * plot, for a chart whose emptiness is itself the reading.\n   */\n  empty?: ChartEmptyProps | false\n}\n\n/**\n * Stages that only ever narrow — a signup flow, a hiring pipeline, a checkout.\n *\n * The caveat is the same one every funnel has: the taper encodes a RATIO\n * between neighbouring stages, and the eye reads the enclosed area, so a funnel\n * exaggerates a shallow drop and flattens a steep one. Where the exact fall-off\n * is the point, put the percentages on the stages — `<Funnel.Label>` does — or\n * use a `<BarChart>`, which encodes each stage on one honest scale.\n *\n * Reach for `<SankeyChart>` instead when the flow can SPLIT rather than only\n * shrink: a funnel has one path through it by construction.\n *\n * @example\n * <FunnelChart title=\"Signup funnel\" config={config} data={stages} dataKey=\"people\" nameKey=\"stage\">\n *   <FunnelChart.Funnel>\n *     <FunnelChart.Label />\n *   </FunnelChart.Funnel>\n *   <FunnelChart.Tooltip />\n * </FunnelChart>\n */\nexport function FunnelChart<TData extends Record<string, unknown>>({\n  config,\n  data,\n  dataKey,\n  nameKey,\n  title,\n  showTitle,\n  description,\n  children,\n  className,\n  chartProps,\n  hideDataTable = false,\n  empty,\n}: FunnelChartProps<TData>) {\n  const chartId = useId().replace(/:/g, '')\n\n  const context = useMemo<FunnelChartContextValue>(\n    () => ({ config, nameKey, dataKey, data }),\n    [config, data, dataKey, nameKey],\n  )\n\n  return (\n    <FunnelChartContext.Provider value={context}>\n      <ChartFigure\n        title={title}\n        showTitle={showTitle}\n        description={description}\n        className={className}\n        table={\n          hideDataTable\n            ? false\n            : { rows: data, rowKey: nameKey, columns: [{ key: dataKey, label: 'Value' }] }\n        }\n        isEmpty={data.length === 0}\n        empty={empty}\n      >\n        <ChartContainer config={config}>\n          {/* No `<defs>` here. `<Funnel>` scopes the stage gradients under its\n              OWN generated id and paints from those, so a second set under the\n              root's id was markup nothing referenced — one gradient definition\n              per stage, per chart, drawn and never used. */}\n          <RechartsFunnelChart id={chartId} accessibilityLayer {...chartProps}>\n            {children}\n          </RechartsFunnelChart>\n        </ChartContainer>\n      </ChartFigure>\n    </FunnelChartContext.Provider>\n  )\n}\n\nexport interface FunnelProps {\n  variant?: FunnelVariant\n  /** Whether the funnel narrows downward or along the inline axis. */\n  orientation?: 'vertical' | 'horizontal'\n  /** Gap between stages, in pixels. */\n  gap?: number\n  /** `<FunnelChart.Label>`. */\n  children?: ReactNode\n  funnelProps?: Omit<ComponentProps<typeof RechartsFunnel>, 'data' | 'dataKey'>\n}\n\n/** The stages themselves. */\nfunction Funnel({\n  variant = 'stepped',\n  orientation = 'vertical',\n  gap = 2,\n  children,\n  funnelProps,\n}: FunnelProps) {\n  const { config, data, dataKey, nameKey } = useFunnelChart()\n  const chartId = useId().replace(/:/g, '')\n\n  // `ramp` walks the series ramp stage by stage; `stepped` holds slot one for\n  // all of them and lets the shape do the talking.\n  const painted = data.map((row, index) => {\n    const name = String(row[nameKey])\n    const slot = variant === 'ramp' ? `var(--series-${(index % 8) + 1})` : undefined\n    return {\n      ...row,\n      fill: slot ?? (name in config ? `url(#${chartId}-stage-${cssName(name)})` : 'var(--series-1)'),\n    }\n  })\n\n  return (\n    <>\n      <RechartsFunnel\n        dataKey={dataKey}\n        nameKey={nameKey}\n        data={painted}\n        isAnimationActive={false}\n        // A surface-coloured stroke rather than a transparent gap: the stages\n        // touch by construction, and a hairline of the page between them is\n        // what makes two similar stages countable.\n        stroke=\"var(--chart-surface)\"\n        strokeWidth={gap}\n        orientation={orientation}\n        {...funnelProps}\n      >\n        {children}\n      </RechartsFunnel>\n      <defs>\n        {Object.entries(config).map(([key, series]) => (\n          <linearGradient\n            key={key}\n            id={`${chartId}-stage-${cssName(key)}`}\n            x1=\"0\"\n            y1=\"0\"\n            x2=\"1\"\n            y2=\"0\"\n          >\n            <ColorStops dataKey={cssName(key)} stops={colorStops(series)} />\n          </linearGradient>\n        ))}\n      </defs>\n    </>\n  )\n}\n\nexport interface FunnelLabelProps {\n  /** The field printed on each stage. Defaults to the stage's name. */\n  dataKey?: string\n  /** Where the label sits relative to its stage. */\n  position?: ComponentProps<typeof LabelList>['position']\n  labelListProps?: Omit<ComponentProps<typeof LabelList>, 'dataKey'>\n}\n\n/**\n * Names printed on the stages.\n *\n * Worth reaching for: a funnel's taper is a ratio the eye reads badly, and a\n * printed number is the relief for that.\n */\nfunction Label({ dataKey, position = 'right', labelListProps }: FunnelLabelProps) {\n  const { nameKey } = useFunnelChart()\n\n  return (\n    <LabelList\n      dataKey={dataKey ?? nameKey}\n      position={position}\n      stroke=\"none\"\n      fontSize={12}\n      className=\"fill-(--ink)\"\n      {...labelListProps}\n    />\n  )\n}\n\n/** The hover panel. No heading: the stage's own name is the row label. */\nfunction Tooltip({ variant, roundness, defaultIndex }: ChartTooltipSlotProps) {\n  const { nameKey } = useFunnelChart()\n\n  return (\n    <ChartTooltip\n      defaultIndex={defaultIndex}\n      cursor={false}\n      content={\n        <ChartTooltipContent nameKey={nameKey} hideLabel roundness={roundness} variant={variant} />\n      }\n    />\n  )\n}\n\nFunnelChart.Funnel = Funnel\nFunnelChart.Label = Label\nFunnelChart.Tooltip = Tooltip\n\nexport default FunnelChart\n"],"mappings":"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","names":[]}

package/dist/charts/Heatmap/Heatmap.d.ts

@@ -0,0 +1,101 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { ChartEmptyProps } from '../lib/empty.js';
+
+/**
+ * How a cell's value is turned into ink.
+ *
+ * `sequential` is one ramp light to dark, and is the right answer for a
+ * magnitude that only goes up: counts, durations, volume. `diverging` puts the
+ * page's own surface at the midpoint and darkens outward in both directions,
+ * for a value with a meaningful zero — a change, a delta, a residual.
+ *
+ * There is no third option, and that is the point. A rainbow scale reads as
+ * ordered to nobody, and is the single most common defect in a heatmap.
+ */
+type HeatmapScale = 'sequential' | 'diverging';
+interface HeatmapCell {
+    /**
+     * The column this cell sits in. Must match one of `columns`, exactly: the
+     * grid is drawn by looking each pair up, so a cell naming a column that is
+     * not there is a cell the grid has nowhere to put. It is not drawn, and it
+     * takes no part in the derived domain either — a misspelt header used to
+     * stretch the scale with a number nothing on screen was painted from.
+     */
+    column: string;
+    /** The row this cell sits in. Must match one of `rows`, on the same terms. */
+    row: string;
+    /** The number. `null` is drawn as an explicit gap, not as a zero. */
+    value: number | null;
+}
+interface HeatmapProps {
+    /** What the grid shows. Required, and it names the table. */
+    title: string;
+    /** Prints the title above the grid instead of hiding it from sight. */
+    showTitle?: boolean;
+    /** A line under the title — the unit, the window, the caveat. */
+    description?: ReactNode;
+    /** Column headers, in the order they should appear. */
+    columns: string[];
+    /** Row headers, in the order they should appear. */
+    rows: string[];
+    cells: HeatmapCell[];
+    scale?: HeatmapScale;
+    /**
+     * The domain, as `[min, max]`. Derived from the data when omitted.
+     *
+     * Pin it whenever two grids are meant to be compared: two heatmaps on
+     * independent domains look alike and mean different things, which is the one
+     * failure a shared legend cannot fix.
+     */
+    domain?: [number, number];
+    /**
+     * Formats a value for the cell's announcement and its printed label.
+     *
+     * The cell is handed over as well, so a grid whose columns are not
+     * self-describing can name the reading rather than only the number. A
+     * calendar is the case that needs it: two days with the same count are two
+     * different readings, and the row and column headers a cell is announced
+     * with — "Mon" and a month name over a block of five weeks — do not say
+     * which day it was.
+     */
+    formatValue?: (value: number, cell: HeatmapCell) => string;
+    /** Prints the number inside each cell. Only legible on a coarse grid. */
+    showValues?: boolean;
+    className?: string;
+    /**
+     * What the grid shows when it has no rows or no columns to draw.
+     *
+     * A heatmap with no headers renders as a caption over nothing, which reads
+     * as a grid that failed to load rather than as one with nothing in it.
+     */
+    empty?: ChartEmptyProps;
+}
+/**
+ * A grid of values read by weight — a calendar of activity, a confusion matrix,
+ * an hour-by-weekday load.
+ *
+ * The one form in the set that a monochrome system renders BETTER than a
+ * chromatic one. A heatmap needs a scale whose order the eye can read without
+ * consulting a legend, and lightness is the only channel that is unambiguously
+ * ordered — which is why "one hue, light to dark" is the standing advice
+ * everywhere else, and why the rainbow heatmap is a perennial mistake. Here
+ * there is no hue left to get wrong.
+ *
+ * It is built as a real `<table>` rather than as an SVG, so the structure a
+ * screen reader walks is the structure the eye reads: a header row, a header
+ * column, and a cell that announces its own value. Nothing else in the package
+ * can say that, and nothing else needs to — which is also why this one takes no
+ * rendering engine at all.
+ *
+ * @example
+ * <Heatmap
+ *   title="Commits by weekday and hour"
+ *   columns={hours}
+ *   rows={weekdays}
+ *   cells={cells}
+ * />
+ */
+declare function Heatmap({ title, showTitle, description, columns, rows, cells, scale, domain, formatValue, showValues, className, empty, }: HeatmapProps): react.JSX.Element;
+
+export { Heatmap, type HeatmapCell, type HeatmapProps, type HeatmapScale, Heatmap as default };

package/dist/charts/Heatmap/Heatmap.js

@@ -0,0 +1,125 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "../../lib/cn.js";
+import { ChartEmpty } from "../lib/empty.js";
+import { clampedFraction } from "../lib/scale.js";
+const LABELLED_CEILING = 0.35;
+function cellKey(row, column) {
+  return `${row}\0${column}`;
+}
+function placed(cells, rows, columns) {
+  const rowSet = new Set(rows);
+  const columnSet = new Set(columns);
+  return new Map(
+    cells.filter((cell) => rowSet.has(cell.row) && columnSet.has(cell.column)).map((cell) => [cellKey(cell.row, cell.column), cell.value])
+  );
+}
+function Heatmap({
+  title,
+  showTitle = false,
+  description,
+  columns,
+  rows,
+  cells,
+  scale = "sequential",
+  domain,
+  formatValue = (value) => value.toLocaleString(),
+  showValues = false,
+  className,
+  empty
+}) {
+  const byKey = placed(cells, rows, columns);
+  const values = [...byKey.values()].filter((value) => value !== null);
+  const [min, max] = domain ?? [Math.min(0, ...values), Math.max(0, ...values)];
+  return /* @__PURE__ */ jsxs("figure", { className: cn("flex w-full flex-col", className), children: [
+    /* @__PURE__ */ jsxs("figcaption", { className: cn(!showTitle && "sr-only", showTitle && "mb-3 flex flex-col gap-1"), children: [
+      /* @__PURE__ */ jsx("span", { className: cn(showTitle && "font-heading text-[length:var(--fs-item)] text-(--ink)"), children: title }),
+      description && /* @__PURE__ */ jsx("span", { className: cn(showTitle && "mono-meta text-(--ink-3-aa)"), children: description })
+    ] }),
+    rows.length === 0 || columns.length === 0 ? /* @__PURE__ */ jsx(ChartEmpty, { ...empty || {} }) : /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsxs("table", { className: "w-full table-fixed border-separate border-spacing-[2px] text-xs", children: [
+      /* @__PURE__ */ jsx("caption", { className: "sr-only", children: title }),
+      /* @__PURE__ */ jsxs("colgroup", { children: [
+        /* @__PURE__ */ jsx("col", { className: "w-20" }),
+        /* @__PURE__ */ jsx("col", { span: columns.length })
+      ] }),
+      /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [
+        /* @__PURE__ */ jsx("th", { scope: "col", className: "sr-only", children: "Row" }),
+        columns.map((column) => /* @__PURE__ */ jsx("th", { scope: "col", className: "pb-1 mono-meta font-normal text-(--chart-axis)", children: column }, column))
+      ] }) }),
+      /* @__PURE__ */ jsx("tbody", { children: rows.map((row) => /* @__PURE__ */ jsxs("tr", { children: [
+        /* @__PURE__ */ jsx(
+          "th",
+          {
+            scope: "row",
+            className: "pe-2 text-end mono-meta font-normal whitespace-nowrap text-(--chart-axis)",
+            children: row
+          }
+        ),
+        columns.map((column) => /* @__PURE__ */ jsx(
+          HeatmapTile,
+          {
+            value: byKey.get(cellKey(row, column)) ?? null,
+            min,
+            max,
+            scale,
+            row,
+            column,
+            label: `${row}, ${column}`,
+            formatValue,
+            showValue: showValues
+          },
+          column
+        ))
+      ] }, row)) })
+    ] }) })
+  ] });
+}
+function HeatmapTile({
+  value,
+  min,
+  max,
+  scale,
+  row,
+  column,
+  label,
+  formatValue,
+  showValue
+}) {
+  if (value === null) {
+    return (
+      // A missing reading is not a zero, and drawing it as the palest cell
+      // would say that it was. The hairline says "no data" instead.
+      /* @__PURE__ */ jsx("td", { className: "h-7 rounded-[2px] border border-dashed border-(--rule) bg-transparent", children: /* @__PURE__ */ jsxs("span", { className: "sr-only", children: [
+        label,
+        ": no data"
+      ] }) })
+    );
+  }
+  const t = clampedFraction(value, min, max);
+  const ramp = scale === "diverging" ? Math.abs(t - 0.5) * 2 : t;
+  const weight = showValue ? ramp * LABELLED_CEILING : ramp;
+  return /* @__PURE__ */ jsxs(
+    "td",
+    {
+      className: "h-7 rounded-[2px] text-center align-middle tabular-nums",
+      style: {
+        // `color-mix` rather than eight discrete steps: a heatmap's whole job is
+        // a continuous read, and banding it into a ramp invents boundaries the
+        // data does not have.
+        backgroundColor: `color-mix(in srgb, var(--series-1) ${(weight * 100).toFixed(1)}%, var(--chart-surface))`,
+        // One text colour at every weight, which is only safe because the ramp
+        // above is capped when a number is printed on it.
+        color: "var(--ink)"
+      },
+      children: [
+        /* @__PURE__ */ jsx("span", { className: cn(!showValue && "sr-only forced-colors:not-sr-only"), children: formatValue(value, { row, column, value }) }),
+        !showValue && /* @__PURE__ */ jsx("span", { className: "sr-only", children: label })
+      ]
+    }
+  );
+}
+var Heatmap_default = Heatmap;
+export {
+  Heatmap,
+  Heatmap_default as default
+};
+//# sourceMappingURL=Heatmap.js.map

package/dist/charts/Heatmap/Heatmap.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/charts/Heatmap/Heatmap.tsx"],"sourcesContent":["import type { ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\nimport { ChartEmpty, type ChartEmptyProps } from '../lib/empty'\nimport { clampedFraction } from '../lib/scale'\n\n/**\n * How a cell's value is turned into ink.\n *\n * `sequential` is one ramp light to dark, and is the right answer for a\n * magnitude that only goes up: counts, durations, volume. `diverging` puts the\n * page's own surface at the midpoint and darkens outward in both directions,\n * for a value with a meaningful zero — a change, a delta, a residual.\n *\n * There is no third option, and that is the point. A rainbow scale reads as\n * ordered to nobody, and is the single most common defect in a heatmap.\n */\nexport type HeatmapScale = 'sequential' | 'diverging'\n\nexport interface HeatmapCell {\n  /**\n   * The column this cell sits in. Must match one of `columns`, exactly: the\n   * grid is drawn by looking each pair up, so a cell naming a column that is\n   * not there is a cell the grid has nowhere to put. It is not drawn, and it\n   * takes no part in the derived domain either — a misspelt header used to\n   * stretch the scale with a number nothing on screen was painted from.\n   */\n  column: string\n  /** The row this cell sits in. Must match one of `rows`, on the same terms. */\n  row: string\n  /** The number. `null` is drawn as an explicit gap, not as a zero. */\n  value: number | null\n}\n\nexport interface HeatmapProps {\n  /** What the grid shows. Required, and it names the table. */\n  title: string\n  /** Prints the title above the grid instead of hiding it from sight. */\n  showTitle?: boolean\n  /** A line under the title — the unit, the window, the caveat. */\n  description?: ReactNode\n  /** Column headers, in the order they should appear. */\n  columns: string[]\n  /** Row headers, in the order they should appear. */\n  rows: string[]\n  cells: HeatmapCell[]\n  scale?: HeatmapScale\n  /**\n   * The domain, as `[min, max]`. Derived from the data when omitted.\n   *\n   * Pin it whenever two grids are meant to be compared: two heatmaps on\n   * independent domains look alike and mean different things, which is the one\n   * failure a shared legend cannot fix.\n   */\n  domain?: [number, number]\n  /**\n   * Formats a value for the cell's announcement and its printed label.\n   *\n   * The cell is handed over as well, so a grid whose columns are not\n   * self-describing can name the reading rather than only the number. A\n   * calendar is the case that needs it: two days with the same count are two\n   * different readings, and the row and column headers a cell is announced\n   * with — \"Mon\" and a month name over a block of five weeks — do not say\n   * which day it was.\n   */\n  formatValue?: (value: number, cell: HeatmapCell) => string\n  /** Prints the number inside each cell. Only legible on a coarse grid. */\n  showValues?: boolean\n  className?: string\n  /**\n   * What the grid shows when it has no rows or no columns to draw.\n   *\n   * A heatmap with no headers renders as a caption over nothing, which reads\n   * as a grid that failed to load rather than as one with nothing in it.\n   */\n  empty?: ChartEmptyProps\n}\n\n/**\n * How far up the ramp a cell may go.\n *\n * A printed number has to clear 4.5:1 against whatever it is printed on, and a\n * mid-grey clears it against neither ink nor paper — which is the reason a\n * heatmap with values on it usually ends up with unreadable cells somewhere in\n * the middle of its own scale. Capping the wash is the trade: the ORDER of the\n * cells survives untouched, the contrast range narrows, and the numbers — which\n * are the precise read anyway — become the thing carrying the detail.\n *\n * With no number printed the span is the full ramp, because the only text in\n * the cell is then visually hidden and has nothing to contrast against.\n */\nconst LABELLED_CEILING = 0.35\n\n/**\n * The key a row and a column are looked up by.\n *\n * Joined on a character no header can contain, so `\"a b\" × \"c\"` and\n * `\"a\" × \"b c\"` stay two different cells. This used to be a literal NUL byte in\n * the source — the same key, written invisibly, in a file every text tool then\n * treated as binary.\n */\nfunction cellKey(row: string, column: string): string {\n  return `${row}\u0000${column}`\n}\n\n/** The cells the grid can actually place, keyed by the pair that places them. */\nfunction placed(\n  cells: HeatmapCell[],\n  rows: string[],\n  columns: string[],\n): Map<string, number | null> {\n  const rowSet = new Set(rows)\n  const columnSet = new Set(columns)\n  return new Map(\n    cells\n      .filter((cell) => rowSet.has(cell.row) && columnSet.has(cell.column))\n      .map((cell) => [cellKey(cell.row, cell.column), cell.value]),\n  )\n}\n\n/**\n * A grid of values read by weight — a calendar of activity, a confusion matrix,\n * an hour-by-weekday load.\n *\n * The one form in the set that a monochrome system renders BETTER than a\n * chromatic one. A heatmap needs a scale whose order the eye can read without\n * consulting a legend, and lightness is the only channel that is unambiguously\n * ordered — which is why \"one hue, light to dark\" is the standing advice\n * everywhere else, and why the rainbow heatmap is a perennial mistake. Here\n * there is no hue left to get wrong.\n *\n * It is built as a real `<table>` rather than as an SVG, so the structure a\n * screen reader walks is the structure the eye reads: a header row, a header\n * column, and a cell that announces its own value. Nothing else in the package\n * can say that, and nothing else needs to — which is also why this one takes no\n * rendering engine at all.\n *\n * @example\n * <Heatmap\n *   title=\"Commits by weekday and hour\"\n *   columns={hours}\n *   rows={weekdays}\n *   cells={cells}\n * />\n */\nexport function Heatmap({\n  title,\n  showTitle = false,\n  description,\n  columns,\n  rows,\n  cells,\n  scale = 'sequential',\n  domain,\n  formatValue = (value) => value.toLocaleString(),\n  showValues = false,\n  className,\n  empty,\n}: HeatmapProps) {\n  // Keyed first, so the domain comes from the cells the grid draws. A cell\n  // whose row or column is not in the headers is never looked up, and it used\n  // to stretch the scale anyway — one misspelt header pushing every drawn cell\n  // into the first fraction of the ramp, with nothing on screen to explain it.\n  const byKey = placed(cells, rows, columns)\n  const values = [...byKey.values()].filter((value): value is number => value !== null)\n  const [min, max] = domain ?? [Math.min(0, ...values), Math.max(0, ...values)]\n\n  return (\n    <figure className={cn('flex w-full flex-col', className)}>\n      <figcaption className={cn(!showTitle && 'sr-only', showTitle && 'mb-3 flex flex-col gap-1')}>\n        <span className={cn(showTitle && 'font-heading text-[length:var(--fs-item)] text-(--ink)')}>\n          {title}\n        </span>\n        {description && (\n          <span className={cn(showTitle && 'mono-meta text-(--ink-3-aa)')}>{description}</span>\n        )}\n      </figcaption>\n\n      {rows.length === 0 || columns.length === 0 ? (\n        <ChartEmpty {...(empty || {})} />\n      ) : (\n      <>\n      {/* `border-separate` with a spacing rather than a gap on a grid: the two\n          pixels of page between cells are what make two neighbouring weights\n          countable, and a table is the only layout that keeps a header tied to\n          its own line.\n\n          `table-fixed`, and not automatic layout: every cell's printed reading\n          is `sr-only`, so it has no intrinsic width to size a column by, while\n          the row-header column carries real, `whitespace-nowrap` text. Automatic\n          layout hands the row-header column all the slack it can find and\n          leaves every data column to divide what is left of nothing — a year\n          of calendar cells computing 0px wide.\n\n          The `colgroup` below is the other half, and has to be a `colgroup`\n          rather than a width on a cell: fixed layout only ever reads a\n          column's width from its first row, and that row's own corner cell is\n          `sr-only` — `position: absolute`, so a width there is never seen by\n          the column it sits in. A `col` is read regardless of which row, or\n          which cell in it, is hidden. */}\n      <table className=\"w-full table-fixed border-separate border-spacing-[2px] text-xs\">\n        <caption className=\"sr-only\">{title}</caption>\n        <colgroup>\n          <col className=\"w-20\" />\n          <col span={columns.length} />\n        </colgroup>\n        <thead>\n          <tr>\n            <th scope=\"col\" className=\"sr-only\">\n              Row\n            </th>\n            {columns.map((column) => (\n              <th key={column} scope=\"col\" className=\"pb-1 mono-meta font-normal text-(--chart-axis)\">\n                {column}\n              </th>\n            ))}\n          </tr>\n        </thead>\n        <tbody>\n          {rows.map((row) => (\n            <tr key={row}>\n              <th\n                scope=\"row\"\n                className=\"pe-2 text-end mono-meta font-normal whitespace-nowrap text-(--chart-axis)\"\n              >\n                {row}\n              </th>\n              {columns.map((column) => (\n                <HeatmapTile\n                  key={column}\n                  value={byKey.get(cellKey(row, column)) ?? null}\n                  min={min}\n                  max={max}\n                  scale={scale}\n                  row={row}\n                  column={column}\n                  label={`${row}, ${column}`}\n                  formatValue={formatValue}\n                  showValue={showValues}\n                />\n              ))}\n            </tr>\n          ))}\n        </tbody>\n      </table>\n      </>\n      )}\n    </figure>\n  )\n}\n\nfunction HeatmapTile({\n  value,\n  min,\n  max,\n  scale,\n  row,\n  column,\n  label,\n  formatValue,\n  showValue,\n}: {\n  value: number | null\n  min: number\n  max: number\n  scale: HeatmapScale\n  row: string\n  column: string\n  label: string\n  formatValue: (value: number, cell: HeatmapCell) => string\n  showValue: boolean\n}) {\n  if (value === null) {\n    return (\n      // A missing reading is not a zero, and drawing it as the palest cell\n      // would say that it was. The hairline says \"no data\" instead.\n      <td className=\"h-7 rounded-[2px] border border-dashed border-(--rule) bg-transparent\">\n        <span className=\"sr-only\">{label}: no data</span>\n      </td>\n    )\n  }\n\n  const t = clampedFraction(value, min, max)\n  // Diverging reads DISTANCE from the midpoint, so both directions darken and\n  // the middle of the scale is the page itself.\n  const ramp = scale === 'diverging' ? Math.abs(t - 0.5) * 2 : t\n  const weight = showValue ? ramp * LABELLED_CEILING : ramp\n\n  return (\n    <td\n      className=\"h-7 rounded-[2px] text-center align-middle tabular-nums\"\n      style={{\n        // `color-mix` rather than eight discrete steps: a heatmap's whole job is\n        // a continuous read, and banding it into a ramp invents boundaries the\n        // data does not have.\n        backgroundColor: `color-mix(in srgb, var(--series-1) ${(weight * 100).toFixed(1)}%, var(--chart-surface))`,\n        // One text colour at every weight, which is only safe because the ramp\n        // above is capped when a number is printed on it.\n        color: 'var(--ink)',\n      }}\n    >\n      {/* Revealed under forced colours, where the cell's own background is\n          remapped away and the wash that WAS the encoding no longer exists.\n          The grid degrades to the table it always was underneath, rather than\n          to a page of identical empty boxes. */}\n      <span className={cn(!showValue && 'sr-only forced-colors:not-sr-only')}>\n        {formatValue(value, { row, column, value })}\n      </span>\n      {!showValue && <span className=\"sr-only\">{label}</span>}\n    </td>\n  )\n}\n\nexport default Heatmap\n"],"mappings":"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","names":[]}

package/dist/charts/Histogram/Histogram.d.ts

@@ -0,0 +1,188 @@
+import { ChartTooltipSlotProps } from '../AreaChart/AreaChart.js';
+import { ChartXAxisProps, ChartYAxisProps } from '../BarChart/BarChart.js';
+import * as react from 'react';
+import { ReactNode, ComponentProps } from 'react';
+import { BarChart, Bar, CartesianGrid } from 'recharts';
+import { ChartConfig } from '../lib/chart.js';
+import { ChartEmptyProps } from '../lib/empty.js';
+import { ChartBackgroundVariant } from '../lib/background.js';
+import { ReferenceLine, ReferenceBand, Annotation } from '../lib/annotations.js';
+import '../lib/values.js';
+import '../lib/sonify-control.js';
+import '../lib/sonify.js';
+import '../lib/brush.js';
+import '../lib/toolbar.js';
+import '../lib/zoom.js';
+import '../lib/figure.js';
+import '../lib/paint.js';
+import '../lib/dot.js';
+import '../lib/legend.js';
+import '../lib/tooltip.js';
+import 'recharts/types/component/DefaultTooltipContent';
+
+/** What the bar heights mean. */
+type HistogramMode = 'frequency' | 'density';
+/** One bucket, as the chart draws it. */
+interface HistogramBin {
+    /** The bucket's lower edge, inclusive. */
+    from: number;
+    /** The bucket's upper edge, exclusive — except the last, which includes it. */
+    to: number;
+    /** How many observations fell in it. */
+    count: number;
+}
+/**
+ * Observations the bins do not reach, and the edge each fell outside.
+ *
+ * Only ever non-zero when the call site gave explicit `bins` edges: a derived
+ * width spans the data by construction. When it IS non-zero it is the reading
+ * that matters most — a tail cut off by a hand-picked range — and dropping it
+ * silently hid it from the picture, from the table and from the tooltip's
+ * share-of-total all at once.
+ */
+interface HistogramOutside {
+    /** How many observations fell below the first edge. */
+    below: number;
+    /** How many fell above the last. */
+    above: number;
+    /** The first edge, and the last. */
+    edges: [number, number];
+}
+interface HistogramProps {
+    /**
+     * The single series — its label and its paint. Only the FIRST entry is read;
+     * a histogram has one distribution and as many bars as it has buckets.
+     */
+    config?: ChartConfig;
+    /**
+     * The raw observations, in any order. Binned for you by `bins`.
+     *
+     * Give this OR `data`, not both — `data` wins if both arrive.
+     */
+    values?: number[];
+    /**
+     * Buckets that were counted somewhere else — by a database, by a sketch, by
+     * a metrics backend that only ever ships histograms.
+     *
+     * Uneven bucket widths are drawn at their real widths, which is the whole
+     * reason this takes edges rather than labels. Set `mode="density"` when they
+     * are uneven, or the wide buckets will read as tall ones.
+     */
+    data?: HistogramBin[];
+    /**
+     * How to cut `values` up: a number of equal-width bins, or the explicit
+     * edges. Defaults to Freedman–Diaconis (`2 × IQR × n^(-1/3)`), falling back
+     * to Sturges when the interquartile range is zero.
+     *
+     * Explicit edges are a RANGE as well as a set of buckets: an observation
+     * outside the first and last edge has no bucket to fall in. It is counted
+     * anyway — into the tooltip's share-of-total, and into a "Below" or "Above"
+     * row in the table — so a tail your edges cut off is still somewhere a reader
+     * can find it.
+     */
+    bins?: number | number[];
+    /**
+     * What the bar heights mean.
+     *
+     * `frequency` is the count in each bucket and is what a reader assumes.
+     * `density` is `count / (n × bin width)`, so the total area is 1 — which is
+     * what makes two histograms of different sample sizes comparable, and what
+     * makes uneven buckets honest.
+     */
+    mode?: HistogramMode;
+    /**
+     * 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, and `<Histogram.Bars>`. */
+    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>;
+    /** Formats the measured values — bin edges, ticks, the tooltip's heading. */
+    formatValue?: (value: number) => 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. `false` keeps the axes,
+     * for a chart whose emptiness is itself the reading.
+     */
+    empty?: ChartEmptyProps | false;
+}
+/**
+ * The shape of one distribution — where the mass sits, how it leans, whether
+ * there is more than one hump in it.
+ *
+ * The form that answers what a `<BoxPlot>` structurally cannot: two clusters,
+ * a hard floor, a pile-up at a timeout value. Reach for the box plot when
+ * several distributions have to be compared side by side, and for this one when
+ * a single distribution has to be understood.
+ *
+ * **A histogram's shape is a property of its bin width, not only of its data.**
+ * The same numbers cut into eight buckets and into eighty are two different
+ * pictures, and a gap between two humps can be created or erased by moving a
+ * bin edge. That is not a defect to be fixed, it is what binning IS, and the
+ * defence is to say which rule drew the picture — the default here is
+ * Freedman–Diaconis — and to look at more than one width before believing a
+ * feature. Uneven buckets add a second trap: under `frequency` a bucket twice
+ * as wide stands twice as tall at the same underlying rate, which is what
+ * `mode="density"` exists to correct.
+ *
+ * Recharts earns its place here for the axes, the grid and the tooltip, but not
+ * for the bars: a bar chart's bars are positioned by CATEGORY and a histogram's
+ * are positioned and SIZED by a continuous measurement. So the x axis is
+ * numeric and each bar is drawn from its own two edges — which is what lets an
+ * uneven bucket be as wide as it really is instead of being flattened into an
+ * equal slot beside its neighbours.
+ *
+ * @example
+ * <Histogram title="Response times" values={samples} bins={20}>
+ *   <Histogram.Grid />
+ *   <Histogram.XAxis label="ms" />
+ *   <Histogram.YAxis />
+ *   <Histogram.Tooltip />
+ *   <Histogram.Bars />
+ * </Histogram>
+ *
+ * @example
+ * // Buckets that arrived already counted, with uneven widths.
+ * <Histogram title="Payload size" data={buckets} mode="density">
+ *   <Histogram.XAxis />
+ *   <Histogram.YAxis />
+ *   <Histogram.Bars />
+ * </Histogram>
+ */
+declare function Histogram({ config, values, data, bins, mode, title, showTitle, description, children, className, chartProps, formatValue, hideDataTable, empty, }: HistogramProps): react.JSX.Element;
+declare namespace Histogram {
+    var Bars: ({ radius, hatched, barProps }: HistogramBarsProps) => react.JSX.Element;
+    var XAxis: ({ dataKey, type, tickLine, axisLine, tickMargin, minTickGap, label, domain, tickFormatter, ...rest }: ChartXAxisProps) => react.JSX.Element;
+    var YAxis: ({ tickLine, axisLine, tickMargin, width, label, tickFormatter, ...rest }: ChartYAxisProps) => react.JSX.Element;
+    var Grid: ({ strokeDasharray, vertical, ...rest }: ComponentProps<typeof CartesianGrid>) => react.JSX.Element;
+    var Tooltip: ({ variant, roundness, defaultIndex }: ChartTooltipSlotProps) => react.JSX.Element;
+    var Background: ({ variant }: {
+        variant: ChartBackgroundVariant;
+    }) => react.JSX.Element;
+    var ReferenceLine: typeof ReferenceLine;
+    var ReferenceBand: typeof ReferenceBand;
+    var Annotation: typeof Annotation;
+}
+interface HistogramBarsProps {
+    /**
+     * The bars' corner. Zero by default, unlike `<BarChart>`: a histogram's bars
+     * are one continuous surface cut into pieces, and a rounded corner draws a
+     * gap between two buckets that are touching.
+     */
+    radius?: number;
+    /** Adds a 45° texture, for a histogram printed in greyscale or overlaid. */
+    hatched?: boolean;
+    /** Escape hatch onto the underlying Recharts bar. */
+    barProps?: ComponentProps<typeof Bar>;
+}
+
+export { Histogram, type HistogramBarsProps, type HistogramBin, type HistogramMode, type HistogramOutside, type HistogramProps, Histogram as default };