@cueplusplus/ui 0.1.0

package/dist/charts/_token.js

@@ -0,0 +1,39 @@
+//#region src/charts/_token.ts
+/**
+* Two ways to read a colour token, and the rule for when each one is right.
+*
+* A chart wants both. Anything the browser paints — a stroke, a fill, a CSS
+* custom property — should carry the **reference** (`var(--cue-accent)`), because
+* a reference re-resolves for free when the theme, the mode or a nested density
+* island changes, with no React involved. Anything JavaScript has to *compute
+* with* — deriving a ramp in oklch, handing a colour to a canvas — needs the
+* **resolved** value, because `var()` is not a colour to anything but CSS.
+*
+* The resolution is deliberately a function call rather than a cached constant:
+* called during render it sees the theme that is stamped right now, which is what
+* makes every palette in this group theme-reactive.
+*
+* @internal Not part of the public API.
+*/
+/** The CSS-level reference to a semantic token: `accent` → `var(--cue-accent)`. */
+function tokenRef(name) {
+	return `var(--cue-${name})`;
+}
+/**
+* The token's computed value in the theme that applies at `element`.
+*
+* @param name - Token name without the `--cue-` prefix.
+* @param element - Where to resolve. Defaults to the document element, which is
+*   where `ThemeProvider` stamps by default; pass a node inside a portal or a
+*   nested theme to read that scope instead.
+* @returns The trimmed value, or `null` when there is no DOM (server render) or
+*   nothing has defined the token.
+*/
+function resolveToken(name, element) {
+	if (typeof window === "undefined" || typeof document === "undefined") return null;
+	const target = element ?? document.documentElement;
+	const value = window.getComputedStyle(target).getPropertyValue(`--cue-${name}`).trim();
+	return value === "" ? null : value;
+}
+//#endregion
+export { resolveToken, tokenRef };

package/dist/charts/container.d.ts

@@ -0,0 +1,58 @@
+import * as React from "react";
+//#region src/charts/container.d.ts
+interface ChartContainerProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /** The chart. Exactly one element — recharts' container takes a single child. */
+  children: React.ReactElement;
+  /** Plot height in px at the 16px root. Defaults to `200`. Ignored when `aspect` is set. */
+  height?: number;
+  /** Width-to-height ratio, letting the plot size itself from its column instead. */
+  aspect?: number;
+  /**
+   * What the chart shows. Given, the box becomes a named `figure`; a shape is
+   * not self-describing, so name the series.
+   */
+  label?: string;
+  /**
+   * The series palette, published as `--chart-1`…`--chart-N`. Defaults to
+   * {@link CHART_TONES}.
+   */
+  tones?: readonly string[];
+  /** Throttle for the resize observer, in ms. Defaults to none. */
+  debounce?: number;
+}
+/**
+ * The box every chart in this system sits in.
+ *
+ * It does three things, and deliberately not a fourth:
+ *
+ * 1. **It publishes the palette as custom properties.** `--chart-1`…`--chart-N`
+ *    carry `var(--cue-accent)`, `var(--cue-info)` and the rest *by reference*,
+ *    so a series written `<Line stroke={chartToneVar(0)} />` re-hues on a theme
+ *    switch with no re-render, no context and no effect. Resolving the palette in
+ *    JavaScript would have made the chart a subscriber to the theme; this way it
+ *    is simply painted in it.
+ * 2. **It re-inks recharts' chrome.** {@link chartChromeClasses} restyles the
+ *    grid, axes and ticks from tokens through the SVG's own class names, so
+ *    every axis is themed whether or not somebody remembered to configure it.
+ * 3. **It measures.** `ResponsiveContainer` is the only reliable way to give a
+ *    recharts chart a pixel size, and it needs a box with a real height — which
+ *    is what `height` (or `aspect`) sets, in `rem` so the plot scales with the
+ *    root font size like everything else.
+ *
+ * What it does not do is wrap or re-export recharts' chart components. A chart is
+ * a composition, and hiding `LineChart`/`XAxis`/`Tooltip` behind a props object
+ * would mean re-implementing a charting library's API surface one prop at a time.
+ *
+ * @example
+ * <ChartContainer label="Requests per minute" height={220}>
+ *   <LineChart data={series}>
+ *     <CartesianGrid vertical={false} />
+ *     <XAxis dataKey="t" />
+ *     <Tooltip cursor={chartTooltipCursor} content={<ChartTooltipContent />} />
+ *     <Line dataKey="requests" stroke={chartToneVar(0)} dot={false} />
+ *   </LineChart>
+ * </ChartContainer>
+ */
+declare const ChartContainer: React.ForwardRefExoticComponent<ChartContainerProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { ChartContainer, ChartContainerProps };

package/dist/charts/container.js

@@ -0,0 +1,77 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { toRem } from "../instruments/_rem.js";
+import { chartChromeClasses } from "./theme.js";
+import { CHART_TONES, chartToneProperty } from "./tones.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+import { ResponsiveContainer } from "recharts";
+//#region src/charts/container.tsx
+/** Default plot height in px at the 16px root. */
+const DEFAULT_HEIGHT_PX = 200;
+/**
+* The box every chart in this system sits in.
+*
+* It does three things, and deliberately not a fourth:
+*
+* 1. **It publishes the palette as custom properties.** `--chart-1`…`--chart-N`
+*    carry `var(--cue-accent)`, `var(--cue-info)` and the rest *by reference*,
+*    so a series written `<Line stroke={chartToneVar(0)} />` re-hues on a theme
+*    switch with no re-render, no context and no effect. Resolving the palette in
+*    JavaScript would have made the chart a subscriber to the theme; this way it
+*    is simply painted in it.
+* 2. **It re-inks recharts' chrome.** {@link chartChromeClasses} restyles the
+*    grid, axes and ticks from tokens through the SVG's own class names, so
+*    every axis is themed whether or not somebody remembered to configure it.
+* 3. **It measures.** `ResponsiveContainer` is the only reliable way to give a
+*    recharts chart a pixel size, and it needs a box with a real height — which
+*    is what `height` (or `aspect`) sets, in `rem` so the plot scales with the
+*    root font size like everything else.
+*
+* What it does not do is wrap or re-export recharts' chart components. A chart is
+* a composition, and hiding `LineChart`/`XAxis`/`Tooltip` behind a props object
+* would mean re-implementing a charting library's API surface one prop at a time.
+*
+* @example
+* <ChartContainer label="Requests per minute" height={220}>
+*   <LineChart data={series}>
+*     <CartesianGrid vertical={false} />
+*     <XAxis dataKey="t" />
+*     <Tooltip cursor={chartTooltipCursor} content={<ChartTooltipContent />} />
+*     <Line dataKey="requests" stroke={chartToneVar(0)} dot={false} />
+*   </LineChart>
+* </ChartContainer>
+*/
+const ChartContainer = React.forwardRef(function ChartContainer({ className, style, children, height = DEFAULT_HEIGHT_PX, aspect, label, tones = CHART_TONES, debounce, ...elementProps }, ref) {
+	const boxStyle = React.useMemo(() => {
+		const properties = {};
+		for (const [index, tone] of tones.entries()) properties[chartToneProperty(index)] = tone;
+		return {
+			...aspect === void 0 ? { height: toRem(height) } : null,
+			...properties,
+			...style
+		};
+	}, [
+		tones,
+		aspect,
+		height,
+		style
+	]);
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		role: label === void 0 ? void 0 : "figure",
+		"aria-label": label,
+		"data-slot": "chart",
+		className: cn("w-full min-w-0", chartChromeClasses, className),
+		style: boxStyle,
+		...elementProps,
+		children: /* @__PURE__ */ jsx(ResponsiveContainer, {
+			width: "100%",
+			...aspect === void 0 ? { height: "100%" } : { aspect },
+			debounce,
+			children
+		})
+	});
+});
+//#endregion
+export { ChartContainer };

package/dist/charts/index.d.ts

@@ -0,0 +1,5 @@
+import { ChartContainer, ChartContainerProps } from "./container.js";
+import { ACCENT_RAMP_MAX_LIGHTNESS, ACCENT_RAMP_MIN_LIGHTNESS, ACCENT_RAMP_STEPS, AccentRampOptions, BANDS_10, BANDS_16, BANDS_31, BANDS_7, ChartRamp, ChartRampProps, ChartSwatch, ChartSwatchProps, FrequencyBand, RAMPS, RAMP_NAMES, RampName, accentRamp } from "./ramps.js";
+import { ChartTooltipContent, ChartTooltipContentProps, ChartTooltipEntry, chartChromeClasses, chartTooltipCursor } from "./theme.js";
+import { CHART_EXTENDED_CHROMA, CHART_EXTENDED_HUES, CHART_EXTENDED_LIGHTNESS, CHART_EXTENDED_TONES, CHART_TONES, CHART_TONE_PROPERTY_PREFIX, CHART_TONE_TOKENS, ChartToneToken, ChartTonesOptions, chartToneProperty, chartToneVar, chartTones } from "./tones.js";
+export { ACCENT_RAMP_MAX_LIGHTNESS, ACCENT_RAMP_MIN_LIGHTNESS, ACCENT_RAMP_STEPS, type AccentRampOptions, BANDS_10, BANDS_16, BANDS_31, BANDS_7, CHART_EXTENDED_CHROMA, CHART_EXTENDED_HUES, CHART_EXTENDED_LIGHTNESS, CHART_EXTENDED_TONES, CHART_TONES, CHART_TONE_PROPERTY_PREFIX, CHART_TONE_TOKENS, ChartContainer, type ChartContainerProps, ChartRamp, type ChartRampProps, ChartSwatch, type ChartSwatchProps, type ChartToneToken, type ChartTonesOptions, ChartTooltipContent, type ChartTooltipContentProps, type ChartTooltipEntry, type FrequencyBand, RAMPS, RAMP_NAMES, type RampName, accentRamp, chartChromeClasses, chartToneProperty, chartToneVar, chartTones, chartTooltipCursor };

package/dist/charts/index.js

@@ -0,0 +1,5 @@
+import { 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 } from "./ramps.js";
+import { ChartTooltipContent, chartChromeClasses, chartTooltipCursor } from "./theme.js";
+import { CHART_EXTENDED_CHROMA, CHART_EXTENDED_HUES, CHART_EXTENDED_LIGHTNESS, CHART_EXTENDED_TONES, CHART_TONES, CHART_TONE_PROPERTY_PREFIX, CHART_TONE_TOKENS, chartToneProperty, chartToneVar, chartTones } from "./tones.js";
+import { ChartContainer } from "./container.js";
+export { ACCENT_RAMP_MAX_LIGHTNESS, ACCENT_RAMP_MIN_LIGHTNESS, ACCENT_RAMP_STEPS, BANDS_10, BANDS_16, BANDS_31, BANDS_7, CHART_EXTENDED_CHROMA, CHART_EXTENDED_HUES, CHART_EXTENDED_LIGHTNESS, CHART_EXTENDED_TONES, CHART_TONES, CHART_TONE_PROPERTY_PREFIX, CHART_TONE_TOKENS, ChartContainer, ChartRamp, ChartSwatch, ChartTooltipContent, RAMPS, RAMP_NAMES, accentRamp, chartChromeClasses, chartToneProperty, chartToneVar, chartTones, chartTooltipCursor };

package/dist/charts/ramps.d.ts

@@ -0,0 +1,140 @@
+import * as React from "react";
+//#region src/charts/ramps.d.ts
+/**
+ * The ordered colour ramps: four frequency ramps, and one derived from the
+ * accent.
+ *
+ * A ramp is not a palette. A palette says *which category*; a ramp says *where
+ * on a scale* — which is why every ramp here is monotone in the thing it
+ * encodes, and why none of them re-hues per theme:
+ *
+ * - **The frequency ramps** are ported from ableton-sync verbatim, edges and
+ *   colours intact. They are violet at 20 Hz through red, orange, yellow, green
+ *   and cyan to blue at 20 kHz — the spectrum analogy every audio tool in the
+ *   world uses. A listener who has learnt "bass is red" in one app must not have
+ *   to relearn it here, and a theme switch must not move the bass.
+ * - **The accent ramp** is the sequential one, and it *does* follow the theme,
+ *   because a heatmap's job is to say "more of the thing this console is about".
+ *   It is derived in oklch from the live accent, so lightness climbs evenly by
+ *   eye rather than by sRGB arithmetic.
+ *
+ * Kept free of recharts so the `/midi` spectrum visualiser can import the bands
+ * without pulling a charting library it never renders.
+ */
+/** One band of a frequency ramp. */
+interface FrequencyBand {
+  /** Stable identity. Unique within its ramp. */
+  id: string;
+  /** What to print in a legend: `"1 kHz"`, `"Sub Bass"`. */
+  label: string;
+  /** Lower edge, in Hz. Equal to the previous band's `maxFreq`. */
+  minFreq: number;
+  /** Upper edge, in Hz. */
+  maxFreq: number;
+  /** The band's ink: a literal, deliberately independent of the theme. */
+  color: string;
+}
+/** Seven musical ranges — the default, and the one a mix engineer thinks in. */
+declare const BANDS_7: readonly FrequencyBand[];
+/** Ten bands — the octave spacing of a standard graphic EQ. */
+declare const BANDS_10: readonly FrequencyBand[];
+/** Sixteen bands — half-octave detail. */
+declare const BANDS_16: readonly FrequencyBand[];
+/** Thirty-one bands — ISO third-octave, the professional analyser resolution. */
+declare const BANDS_31: readonly FrequencyBand[];
+/** Every frequency ramp, coarsest first. */
+declare const RAMP_NAMES: readonly ["bands-7", "bands-10", "bands-16", "bands-31"];
+/** One of the four frequency ramps. */
+type RampName = (typeof RAMP_NAMES)[number];
+/**
+ * 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)} />
+ */
+declare const RAMPS: Record<RampName, readonly FrequencyBand[]>;
+/** Steps in a sequential ramp when the caller does not say. */
+declare const ACCENT_RAMP_STEPS = 9;
+/** Lightness of the darkest step: dark enough to read as "none", still not black. */
+declare const ACCENT_RAMP_MIN_LIGHTNESS = 0.3;
+/** Lightness of the lightest step: bright enough to read as "most", still not white. */
+declare const ACCENT_RAMP_MAX_LIGHTNESS = 0.92;
+interface AccentRampOptions {
+  /** How many steps. Defaults to {@link ACCENT_RAMP_STEPS}. */
+  steps?: number;
+  /**
+   * Where `--cue-accent` resolves. Defaults to the document element; pass a node
+   * inside a portal or a nested theme to read that scope instead.
+   */
+  element?: Element | null;
+  /** Anchor colour, instead of the live accent. Any CSS colour CSS itself parses. */
+  from?: string;
+}
+/**
+ * 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]} />
+ */
+declare function accentRamp(options?: AccentRampOptions): string[];
+interface ChartSwatchProps extends Omit<React.ComponentPropsWithoutRef<"span">, "children" | "color"> {
+  /** The colour to show. Any CSS colour, including a `var()` reference. */
+  color: string;
+  /** What the colour stands for. Omit for a bare chip. */
+  label?: React.ReactNode;
+}
+/**
+ * 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} />)}
+ */
+declare const ChartSwatch: React.ForwardRefExoticComponent<ChartSwatchProps & React.RefAttributes<HTMLSpanElement>>;
+interface ChartRampProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /** The ramp, in order. Any CSS colours. */
+  colors: readonly string[];
+  /** What the ramp encodes. Required: it is the strip's accessible name. */
+  label: string;
+  /** Strip height in px at the 16px root, emitted as `rem`. Defaults to `8`. */
+  height?: number;
+}
+/**
+ * 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()} />
+ */
+declare const ChartRamp: React.ForwardRefExoticComponent<ChartRampProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { ACCENT_RAMP_MAX_LIGHTNESS, ACCENT_RAMP_MIN_LIGHTNESS, ACCENT_RAMP_STEPS, AccentRampOptions, BANDS_10, BANDS_16, BANDS_31, BANDS_7, ChartRamp, ChartRampProps, ChartSwatch, ChartSwatchProps, FrequencyBand, RAMPS, RAMP_NAMES, RampName, accentRamp };