@cueplusplus/ui 0.13.0

package/dist/charts/ramps.js

@@ -0,0 +1,615 @@
+import { cn } from "../lib/cn.js";
+import { toRem } from "../instruments/_rem.js";
+import { resolveToken } from "./_token.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { clampChroma, converter, formatHex, inGamut, parse } from "culori";
+//#region src/charts/ramps.tsx
+/** Seven musical ranges — the default, and the one a mix engineer thinks in. */
+const BANDS_7 = [
+	{
+		id: "sub-bass",
+		label: "Sub Bass",
+		minFreq: 20,
+		maxFreq: 60,
+		color: "#8b00ff"
+	},
+	{
+		id: "bass",
+		label: "Bass",
+		minFreq: 60,
+		maxFreq: 250,
+		color: "#ff0000"
+	},
+	{
+		id: "low-mid",
+		label: "Low Mid",
+		minFreq: 250,
+		maxFreq: 500,
+		color: "#ff6600"
+	},
+	{
+		id: "mid",
+		label: "Mid",
+		minFreq: 500,
+		maxFreq: 2e3,
+		color: "#ffff00"
+	},
+	{
+		id: "high-mid",
+		label: "High Mid",
+		minFreq: 2e3,
+		maxFreq: 4e3,
+		color: "#00ff00"
+	},
+	{
+		id: "high",
+		label: "High",
+		minFreq: 4e3,
+		maxFreq: 8e3,
+		color: "#00ffff"
+	},
+	{
+		id: "presence",
+		label: "Presence",
+		minFreq: 8e3,
+		maxFreq: 2e4,
+		color: "#0000ff"
+	}
+];
+/** Ten bands — the octave spacing of a standard graphic EQ. */
+const BANDS_10 = [
+	{
+		id: "band-31",
+		label: "31 Hz",
+		minFreq: 22,
+		maxFreq: 44,
+		color: "#8b00ff"
+	},
+	{
+		id: "band-62",
+		label: "62 Hz",
+		minFreq: 44,
+		maxFreq: 88,
+		color: "#9b00ff"
+	},
+	{
+		id: "band-125",
+		label: "125 Hz",
+		minFreq: 88,
+		maxFreq: 177,
+		color: "#ff0000"
+	},
+	{
+		id: "band-250",
+		label: "250 Hz",
+		minFreq: 177,
+		maxFreq: 355,
+		color: "#ff3300"
+	},
+	{
+		id: "band-500",
+		label: "500 Hz",
+		minFreq: 355,
+		maxFreq: 710,
+		color: "#ff6600"
+	},
+	{
+		id: "band-1k",
+		label: "1 kHz",
+		minFreq: 710,
+		maxFreq: 1420,
+		color: "#ffff00"
+	},
+	{
+		id: "band-2k",
+		label: "2 kHz",
+		minFreq: 1420,
+		maxFreq: 2840,
+		color: "#66ff00"
+	},
+	{
+		id: "band-4k",
+		label: "4 kHz",
+		minFreq: 2840,
+		maxFreq: 5680,
+		color: "#00ff00"
+	},
+	{
+		id: "band-8k",
+		label: "8 kHz",
+		minFreq: 5680,
+		maxFreq: 11360,
+		color: "#00ffff"
+	},
+	{
+		id: "band-16k",
+		label: "16 kHz",
+		minFreq: 11360,
+		maxFreq: 2e4,
+		color: "#0000ff"
+	}
+];
+/** Sixteen bands — half-octave detail. */
+const BANDS_16 = [
+	{
+		id: "band-25",
+		label: "25 Hz",
+		minFreq: 20,
+		maxFreq: 32,
+		color: "#8b00ff"
+	},
+	{
+		id: "band-40",
+		label: "40 Hz",
+		minFreq: 32,
+		maxFreq: 50,
+		color: "#9400ff"
+	},
+	{
+		id: "band-63",
+		label: "63 Hz",
+		minFreq: 50,
+		maxFreq: 80,
+		color: "#9d00ff"
+	},
+	{
+		id: "band-100",
+		label: "100 Hz",
+		minFreq: 80,
+		maxFreq: 125,
+		color: "#ff0000"
+	},
+	{
+		id: "band-160",
+		label: "160 Hz",
+		minFreq: 125,
+		maxFreq: 200,
+		color: "#ff1100"
+	},
+	{
+		id: "band-250",
+		label: "250 Hz",
+		minFreq: 200,
+		maxFreq: 315,
+		color: "#ff2200"
+	},
+	{
+		id: "band-400",
+		label: "400 Hz",
+		minFreq: 315,
+		maxFreq: 500,
+		color: "#ff4400"
+	},
+	{
+		id: "band-630",
+		label: "630 Hz",
+		minFreq: 500,
+		maxFreq: 800,
+		color: "#ff6600"
+	},
+	{
+		id: "band-1k",
+		label: "1 kHz",
+		minFreq: 800,
+		maxFreq: 1250,
+		color: "#ffaa00"
+	},
+	{
+		id: "band-1k6",
+		label: "1.6 kHz",
+		minFreq: 1250,
+		maxFreq: 2e3,
+		color: "#ffff00"
+	},
+	{
+		id: "band-2k5",
+		label: "2.5 kHz",
+		minFreq: 2e3,
+		maxFreq: 3150,
+		color: "#aaff00"
+	},
+	{
+		id: "band-4k",
+		label: "4 kHz",
+		minFreq: 3150,
+		maxFreq: 5e3,
+		color: "#66ff00"
+	},
+	{
+		id: "band-6k3",
+		label: "6.3 kHz",
+		minFreq: 5e3,
+		maxFreq: 8e3,
+		color: "#00ff00"
+	},
+	{
+		id: "band-10k",
+		label: "10 kHz",
+		minFreq: 8e3,
+		maxFreq: 12500,
+		color: "#00ff66"
+	},
+	{
+		id: "band-16k",
+		label: "16 kHz",
+		minFreq: 12500,
+		maxFreq: 18e3,
+		color: "#00ffff"
+	},
+	{
+		id: "band-20k",
+		label: "20 kHz",
+		minFreq: 18e3,
+		maxFreq: 2e4,
+		color: "#0000ff"
+	}
+];
+/** Thirty-one bands — ISO third-octave, the professional analyser resolution. */
+const BANDS_31 = [
+	{
+		id: "band-20",
+		label: "20 Hz",
+		minFreq: 18,
+		maxFreq: 22,
+		color: "#8b00ff"
+	},
+	{
+		id: "band-25",
+		label: "25 Hz",
+		minFreq: 22,
+		maxFreq: 28,
+		color: "#8f00ff"
+	},
+	{
+		id: "band-31",
+		label: "31 Hz",
+		minFreq: 28,
+		maxFreq: 35,
+		color: "#9400ff"
+	},
+	{
+		id: "band-40",
+		label: "40 Hz",
+		minFreq: 35,
+		maxFreq: 45,
+		color: "#9800ff"
+	},
+	{
+		id: "band-50",
+		label: "50 Hz",
+		minFreq: 45,
+		maxFreq: 57,
+		color: "#9d00ff"
+	},
+	{
+		id: "band-63",
+		label: "63 Hz",
+		minFreq: 57,
+		maxFreq: 71,
+		color: "#ff0000"
+	},
+	{
+		id: "band-80",
+		label: "80 Hz",
+		minFreq: 71,
+		maxFreq: 90,
+		color: "#ff0800"
+	},
+	{
+		id: "band-100",
+		label: "100 Hz",
+		minFreq: 90,
+		maxFreq: 113,
+		color: "#ff1100"
+	},
+	{
+		id: "band-125",
+		label: "125 Hz",
+		minFreq: 113,
+		maxFreq: 142,
+		color: "#ff1900"
+	},
+	{
+		id: "band-160",
+		label: "160 Hz",
+		minFreq: 142,
+		maxFreq: 180,
+		color: "#ff2200"
+	},
+	{
+		id: "band-200",
+		label: "200 Hz",
+		minFreq: 180,
+		maxFreq: 226,
+		color: "#ff2b00"
+	},
+	{
+		id: "band-250",
+		label: "250 Hz",
+		minFreq: 226,
+		maxFreq: 284,
+		color: "#ff3300"
+	},
+	{
+		id: "band-315",
+		label: "315 Hz",
+		minFreq: 284,
+		maxFreq: 358,
+		color: "#ff3c00"
+	},
+	{
+		id: "band-400",
+		label: "400 Hz",
+		minFreq: 358,
+		maxFreq: 452,
+		color: "#ff4400"
+	},
+	{
+		id: "band-500",
+		label: "500 Hz",
+		minFreq: 452,
+		maxFreq: 566,
+		color: "#ff5500"
+	},
+	{
+		id: "band-630",
+		label: "630 Hz",
+		minFreq: 566,
+		maxFreq: 716,
+		color: "#ff6600"
+	},
+	{
+		id: "band-800",
+		label: "800 Hz",
+		minFreq: 716,
+		maxFreq: 906,
+		color: "#ff7700"
+	},
+	{
+		id: "band-1k",
+		label: "1 kHz",
+		minFreq: 906,
+		maxFreq: 1130,
+		color: "#ffaa00"
+	},
+	{
+		id: "band-1k25",
+		label: "1.25 kHz",
+		minFreq: 1130,
+		maxFreq: 1420,
+		color: "#ffcc00"
+	},
+	{
+		id: "band-1k6",
+		label: "1.6 kHz",
+		minFreq: 1420,
+		maxFreq: 1800,
+		color: "#ffff00"
+	},
+	{
+		id: "band-2k",
+		label: "2 kHz",
+		minFreq: 1800,
+		maxFreq: 2260,
+		color: "#ccff00"
+	},
+	{
+		id: "band-2k5",
+		label: "2.5 kHz",
+		minFreq: 2260,
+		maxFreq: 2840,
+		color: "#aaff00"
+	},
+	{
+		id: "band-3k15",
+		label: "3.15 kHz",
+		minFreq: 2840,
+		maxFreq: 3580,
+		color: "#88ff00"
+	},
+	{
+		id: "band-4k",
+		label: "4 kHz",
+		minFreq: 3580,
+		maxFreq: 4520,
+		color: "#66ff00"
+	},
+	{
+		id: "band-5k",
+		label: "5 kHz",
+		minFreq: 4520,
+		maxFreq: 5660,
+		color: "#44ff00"
+	},
+	{
+		id: "band-6k3",
+		label: "6.3 kHz",
+		minFreq: 5660,
+		maxFreq: 7160,
+		color: "#22ff00"
+	},
+	{
+		id: "band-8k",
+		label: "8 kHz",
+		minFreq: 7160,
+		maxFreq: 9060,
+		color: "#00ff00"
+	},
+	{
+		id: "band-10k",
+		label: "10 kHz",
+		minFreq: 9060,
+		maxFreq: 11300,
+		color: "#00ff44"
+	},
+	{
+		id: "band-12k5",
+		label: "12.5 kHz",
+		minFreq: 11300,
+		maxFreq: 14200,
+		color: "#00ff88"
+	},
+	{
+		id: "band-16k",
+		label: "16 kHz",
+		minFreq: 14200,
+		maxFreq: 18e3,
+		color: "#00ffff"
+	},
+	{
+		id: "band-20k",
+		label: "20 kHz",
+		minFreq: 18e3,
+		maxFreq: 2e4,
+		color: "#0000ff"
+	}
+];
+/** Every frequency ramp, coarsest first. */
+const RAMP_NAMES = [
+	"bands-7",
+	"bands-10",
+	"bands-16",
+	"bands-31"
+];
+/**
+* The frequency ramps, indexed by name, so a resolution picker can be a select
+* over {@link RAMP_NAMES} rather than a switch statement.
+*
+* The sequential ramp is not in here on purpose: it depends on the live theme,
+* so it is a call — {@link accentRamp} — not a constant.
+*
+* @example
+* <ChartRamp label="Third octave" colors={RAMPS["bands-31"].map((band) => band.color)} />
+*/
+const RAMPS = {
+	"bands-7": BANDS_7,
+	"bands-10": BANDS_10,
+	"bands-16": BANDS_16,
+	"bands-31": BANDS_31
+};
+/** Steps in a sequential ramp when the caller does not say. */
+const ACCENT_RAMP_STEPS = 9;
+/** Lightness of the darkest step: dark enough to read as "none", still not black. */
+const ACCENT_RAMP_MIN_LIGHTNESS = .3;
+/** Lightness of the lightest step: bright enough to read as "most", still not white. */
+const ACCENT_RAMP_MAX_LIGHTNESS = .92;
+const toOklch = converter("oklch");
+const srgb = inGamut("rgb");
+/** Where step `index` of `count` sits on the 0–1 run. */
+function position(index, count) {
+	return count <= 1 ? 0 : index / (count - 1);
+}
+/**
+* The step as a live CSS expression, for when the accent cannot be computed.
+*
+* Mixing in oklch is the same colour space the resolved path derives in, and
+* `var(--cue-accent)` keeps it theme-reactive — so a chart that paints before
+* the stylesheet has resolved still gets a monotone ramp in the right hue,
+* rather than a ramp in an invented one. It floors at 25% accent so neither end
+* collapses to flat black or flat white.
+*/
+function mixExpression(t) {
+	const toward = t <= .5 ? "#000000" : "#ffffff";
+	return `color-mix(in oklch, var(--cue-accent) ${Math.round(25 + (t <= .5 ? t : 1 - t) * 150)}%, ${toward})`;
+}
+/**
+* A sequential ramp anchored on the accent, darkest first.
+*
+* Lightness climbs linearly in oklch, which is the point of doing this in oklch
+* at all: an evenly spaced sRGB ramp bunches up at the dark end, so the reader
+* sees steps where the data has none. Hue is held at the accent's, and chroma is
+* held at the accent's and then **clamped** into sRGB rather than clipped —
+* clipping a too-saturated dark step turns it into a different colour, whereas
+* clamping only takes the saturation the display cannot show anyway. That is
+* also what tapers the ends naturally: no colour holds full chroma at L 0.3.
+*
+* @param options - Step count, anchor, and where to resolve the accent.
+* @returns `steps` CSS colours, darkest first: hex when the anchor resolved, live
+*   `color-mix()` expressions when it did not — which covers a server render, a
+*   theme that has not loaded yet, and an anchor no colour parser recognises.
+* @example
+* <Area fill={accentRamp({ steps: 5 })[3]} />
+*/
+function accentRamp(options = {}) {
+	const { steps = 9, element, from } = options;
+	const count = Math.max(1, Math.floor(steps));
+	const anchor = from ?? resolveToken("accent", element);
+	const parsed = anchor === null ? void 0 : toOklch(parse(anchor));
+	return Array.from({ length: count }, (_unused, index) => {
+		const t = position(index, count);
+		if (parsed === void 0) return mixExpression(t);
+		const step = {
+			mode: "oklch",
+			l: ACCENT_RAMP_MIN_LIGHTNESS + t * .6200000000000001,
+			c: parsed.c,
+			h: parsed.h ?? 0
+		};
+		return formatHex(srgb(step) ? step : clampChroma(step, "oklch", "rgb"));
+	});
+}
+/**
+* One colour and what it means: the atom a chart legend is built from.
+*
+* The chip is `aria-hidden` and the label is plain text, so the meaning survives
+* without colour vision (WCAG 1.4.1). A swatch with no label is decoration and
+* announces nothing at all, which is the honest reading of a colour with no
+* caption.
+*
+* Static markup — no `"use client"`.
+*
+* @example
+* {BANDS_7.map((band) => <ChartSwatch key={band.id} color={band.color} label={band.label} />)}
+*/
+const ChartSwatch = React.forwardRef(function ChartSwatch({ className, color, label, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsxs("span", {
+		ref,
+		"data-slot": "chart-swatch",
+		className: cn("inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-label) text-fg-muted", className),
+		...elementProps,
+		children: [/* @__PURE__ */ jsx("span", {
+			"aria-hidden": "true",
+			"data-slot": "chart-swatch-chip",
+			className: "size-[0.375rem] shrink-0 rounded-[1px]",
+			style: { backgroundColor: color }
+		}), label === void 0 ? null : /* @__PURE__ */ jsx("span", {
+			"data-slot": "chart-swatch-label",
+			children: label
+		})]
+	});
+});
+/** Default strip height in px at the 16px root — a rule, not a block. */
+const DEFAULT_RAMP_HEIGHT_PX = 8;
+/**
+* A ramp drawn as a strip: equal cells, no gaps, in order.
+*
+* Equal cells rather than a CSS gradient, because a ramp *is* discrete — a
+* gradient would show steps the data cannot address, and would quietly disagree
+* with the same ramp used to fill bars. No seams either, for the same reason the
+* cells are equal: a seam reads as a category boundary, and a sequential scale
+* has none.
+*
+* Static markup — no `"use client"`.
+*
+* @example
+* <ChartRamp label="Density" colors={accentRamp()} />
+*/
+const ChartRamp = React.forwardRef(function ChartRamp({ className, colors, label, height = DEFAULT_RAMP_HEIGHT_PX, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		role: "img",
+		"aria-label": label,
+		"data-slot": "chart-ramp",
+		className: cn("flex w-full overflow-hidden rounded-(--radius-control)", className),
+		style: { height: toRem(height) },
+		...elementProps,
+		children: colors.map((color, index) => /* @__PURE__ */ jsx("span", {
+			"aria-hidden": "true",
+			"data-slot": "chart-ramp-cell",
+			className: "min-w-px flex-1",
+			style: { backgroundColor: color }
+		}, index))
+	});
+});
+//#endregion
+export { ACCENT_RAMP_MAX_LIGHTNESS, ACCENT_RAMP_MIN_LIGHTNESS, ACCENT_RAMP_STEPS, BANDS_10, BANDS_16, BANDS_31, BANDS_7, ChartRamp, ChartSwatch, RAMPS, RAMP_NAMES, accentRamp };

package/dist/charts/theme.d.ts

@@ -0,0 +1,112 @@
+import * as React from "react";
+//#region src/charts/theme.d.ts
+/**
+ * The recharts chrome, restated in this system's vocabulary.
+ *
+ * Recharts paints its grid, axes and ticks with presentation attributes baked
+ * into the SVG (`stroke="#ccc"`, `fill="#666"`). Those attributes lose to any
+ * CSS declaration, which is the whole opening: one scoped stylesheet on the
+ * chart's wrapper re-inks the entire chrome without a single prop threaded
+ * through the chart, and — because the declarations are token references — it
+ * re-inks again on a theme, mode or density switch with no React involved.
+ *
+ * The alternative, spreading a `{ stroke, fill, fontSize }` bundle onto every
+ * `CartesianGrid`, `XAxis` and `YAxis`, is the version of this that rots: the one
+ * axis somebody forgets to spread onto is grey forever, and nothing catches it.
+ *
+ * Deliberately recharts-free at the module level: only the container imports the
+ * library, so this file and the palette stay importable from groups that never
+ * render a chart.
+ */
+/**
+ * Everything the chart wrapper needs to re-ink recharts' own SVG.
+ *
+ * Spread by `ChartContainer`; exported so an app that mounts a chart some other
+ * way (a recharts component outside the container, a printed export) gets the
+ * same chrome from the same source.
+ *
+ * @example
+ * <div className={cn(chartChromeClasses, "h-40")}><LineChart …/></div>
+ */
+declare const chartChromeClasses: string;
+/**
+ * The cursor recharts draws under the tooltip.
+ *
+ * One object for both shapes it can take: a `<line>` on a line or area chart,
+ * where only the stroke lands, and a `<rect>` on a bar chart, where the faint
+ * fill washes the hovered band and the dashed rim keeps its edges legible. The
+ * dash is the same `2 3` the rest of the system uses for "this is a guide, not
+ * data".
+ *
+ * @example
+ * <Tooltip cursor={chartTooltipCursor} content={<ChartTooltipContent />} />
+ */
+declare const chartTooltipCursor: {
+  readonly stroke: "var(--cue-fg)";
+  readonly strokeOpacity: 0.5;
+  readonly strokeWidth: 1;
+  readonly strokeDasharray: "2 3";
+  readonly fill: "var(--cue-fg)";
+  readonly fillOpacity: 0.06;
+};
+/**
+ * One series' entry in a tooltip payload.
+ *
+ * Declared structurally rather than imported from recharts so nothing in this
+ * package's published types depends on an optional peer — an app that installs
+ * `@cueplusplus/ui` without recharts still type-checks.
+ */
+interface ChartTooltipEntry {
+  /** Series name, as recharts resolved it. */
+  name?: React.ReactNode;
+  /** The value at the hovered index. */
+  value?: number | string | readonly (number | string)[];
+  /** The colour recharts assigned the series. Drives the row's indicator. */
+  color?: string;
+  /** The key the series reads. Used for row identity when `name` repeats. */
+  dataKey?: string | number;
+  /** Unit suffix, when the series declares one. */
+  unit?: React.ReactNode;
+}
+interface ChartTooltipContentProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children" | "content"> {
+  /** Whether the pointer is on the plot. Recharts supplies this. */
+  active?: boolean;
+  /** One entry per series at the hovered index. Recharts supplies this. */
+  payload?: readonly ChartTooltipEntry[];
+  /** The hovered category — the x value. Recharts supplies this. */
+  label?: React.ReactNode;
+  /** Drop the label line, for a chart whose x axis needs no restating. */
+  hideLabel?: boolean;
+  /** Drop the per-row colour chips, for a single-series chart. */
+  hideIndicator?: boolean;
+  /** Format the label line. */
+  labelFormatter?: (label: React.ReactNode, payload: readonly ChartTooltipEntry[]) => React.ReactNode;
+  /** Format one row's value. Return the unit too if you want to own it. */
+  formatter?: (value: ChartTooltipEntry["value"], name: React.ReactNode, entry: ChartTooltipEntry, index: number) => React.ReactNode;
+}
+/**
+ * The tooltip surface: an overlay, styled like every other overlay.
+ *
+ * A chart tooltip *is* a floating surface, so it gets exactly what a Popover
+ * gets — `surface-2` fill, the overlay rim, one soft shadow — from
+ * `_surface.ts` rather than from a second, chart-only recipe that would drift.
+ * What it adds is the reading discipline the rest of the system uses for
+ * numbers: mono, tabular figures, values right-aligned so a column of them lines
+ * up under the pointer.
+ *
+ * Returns `null` when the pointer is off the plot or the payload is empty,
+ * because recharts keeps the content mounted between hovers.
+ *
+ * `formatter` and `labelFormatter` may equally be set on the `<Tooltip>` itself:
+ * recharts forwards its own configuration into cloned content, so both spellings
+ * land here. Everything else in that configuration is dropped rather than
+ * rendered — see {@link domProps} — which also means a handler passed to this
+ * component does not reach the surface. Nothing would fire on it anyway: the
+ * tooltip is drawn under the pointer, not in its path.
+ *
+ * @example
+ * <Tooltip cursor={chartTooltipCursor} content={<ChartTooltipContent />} />
+ */
+declare const ChartTooltipContent: React.ForwardRefExoticComponent<ChartTooltipContentProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { ChartTooltipContent, ChartTooltipContentProps, ChartTooltipEntry, chartChromeClasses, chartTooltipCursor };