@paul-portfolio/react 0.4.4 → 0.5.0

package/dist/Sparkline.d.ts

@@ -0,0 +1,30 @@
+import { type HTMLAttributes } from 'react';
+type SparklineProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+    /** The series to plot. Ignored when `series` is given. */
+    data?: number[];
+    /**
+     * Several series on one shared y-domain — for comparing trends at a glance.
+     * Takes precedence over `data`.
+     */
+    series?: number[][];
+    /** `line` (default) draws a stroke; `area` fills under it. Single series only. */
+    variant?: 'line' | 'area';
+    /** Accessible name for the chart. Required — the SVG itself is hidden. */
+    label: string;
+    /** viewBox width in coordinate units. Defaults to 160. */
+    width?: number;
+    /** viewBox height in coordinate units. Defaults to 40. */
+    height?: number;
+};
+/**
+ * A compact, axis-free trend line — the sparkline used across dashboards and
+ * KPI cards. Pure SVG from `chartGeometry`, so it renders identically to the
+ * Angular `PaulSparkline`. Exposes `role="img"` with a caller-supplied label
+ * since the drawing carries no text of its own.
+ *
+ * With `series`, every line is scaled against ONE domain spanning all of them —
+ * independently scaled sparklines look comparable and aren't. `area` applies to
+ * the single-series form only; stacked fills at this size are mud.
+ */
+export declare function Sparkline({ data, series, variant, label, width, height, className, ...props }: SparklineProps): import("react").JSX.Element;
+export {};

package/dist/Sparkline.js

@@ -0,0 +1,21 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from './cx';
+import { linePath, areaPath, multiLinePoints } from './chartGeometry';
+/**
+ * A compact, axis-free trend line — the sparkline used across dashboards and
+ * KPI cards. Pure SVG from `chartGeometry`, so it renders identically to the
+ * Angular `PaulSparkline`. Exposes `role="img"` with a caller-supplied label
+ * since the drawing carries no text of its own.
+ *
+ * With `series`, every line is scaled against ONE domain spanning all of them —
+ * independently scaled sparklines look comparable and aren't. `area` applies to
+ * the single-series form only; stacked fills at this size are mud.
+ */
+export function Sparkline({ data, series, variant = 'line', label, width = 160, height = 40, className, ...props }) {
+    const box = { width, height, padding: 2 };
+    const multi = series?.filter((s) => s.length > 0) ?? [];
+    const single = data ?? [];
+    const hasData = multi.length > 0 || single.length > 0;
+    const lines = multi.length > 0 ? multiLinePoints(multi, box) : [];
+    return (_jsx("div", { role: "img", "aria-label": label, className: cx('paul-chart', 'paul-chart--sparkline', className), ...props, children: hasData ? (_jsx("svg", { className: "paul-chart__svg", viewBox: `0 0 ${width} ${height}`, preserveAspectRatio: "none", "aria-hidden": "true", focusable: "false", children: multi.length > 0 ? (lines.map((points, i) => (_jsx("path", { className: "paul-chart__line", d: points.map((p, j) => `${j === 0 ? 'M' : 'L'}${p.x},${p.y}`).join(' '), fill: "none", stroke: `var(--paul-chart-${Math.min(i, 5) + 1})`, vectorEffect: "non-scaling-stroke" }, i)))) : (_jsxs(_Fragment, { children: [variant === 'area' && (_jsx("path", { className: "paul-chart__area", d: areaPath(single, box) })), _jsx("path", { className: "paul-chart__line", d: linePath(single, box), fill: "none", vectorEffect: "non-scaling-stroke" })] })) })) : (_jsx("span", { className: "paul-chart__empty", "aria-hidden": "true", children: "No data" })) }));
+}

package/dist/Spotlight.d.ts

@@ -0,0 +1,17 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+type SpotlightProps = HTMLAttributes<HTMLDivElement> & {
+    /** Diameter of the glow, in pixels. */
+    size?: number;
+    /** Glow colour. Any CSS colour; defaults to a soft brand-blue wash. */
+    color?: string;
+    children: ReactNode;
+};
+/**
+ * An interactive background: a soft radial glow that follows the cursor across
+ * the surface. The glow is decorative and clipped to the container, and the
+ * content sits in its own layer on top, so the component stays content-agnostic.
+ * Under prefers-reduced-motion the glow is pinned to the centre and stops
+ * tracking the pointer — visible, but with no cursor-driven movement.
+ */
+export declare function Spotlight({ size, color, className, style, children, ...rest }: SpotlightProps): import("react").JSX.Element;
+export {};

package/dist/Spotlight.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, } from 'react';
+import { cx } from './cx';
+import { usePrefersReducedMotion } from './usePrefersReducedMotion';
+/**
+ * An interactive background: a soft radial glow that follows the cursor across
+ * the surface. The glow is decorative and clipped to the container, and the
+ * content sits in its own layer on top, so the component stays content-agnostic.
+ * Under prefers-reduced-motion the glow is pinned to the centre and stops
+ * tracking the pointer — visible, but with no cursor-driven movement.
+ */
+export function Spotlight({ size = 350, color, className, style, children, ...rest }) {
+    const reduced = usePrefersReducedMotion();
+    const rootRef = useRef(null);
+    const baseStyle = {
+        ['--paul-spotlight-size']: `${size}px`,
+        ...(color ? { ['--paul-spotlight-color']: color } : {}),
+        ...style,
+    };
+    // Static, centred glow — visible, but never chases the pointer.
+    if (reduced) {
+        return (_jsxs("div", { className: cx('spotlight', className), "data-active": "true", style: baseStyle, ...rest, children: [_jsx("div", { "aria-hidden": "true", className: "spotlight__glow" }), _jsx("div", { className: "spotlight__content", children: children })] }));
+    }
+    const handleMove = (e) => {
+        const el = rootRef.current;
+        if (!el)
+            return;
+        const rect = el.getBoundingClientRect();
+        el.style.setProperty('--paul-spotlight-x', `${e.clientX - rect.left}px`);
+        el.style.setProperty('--paul-spotlight-y', `${e.clientY - rect.top}px`);
+        el.dataset.active = 'true';
+    };
+    const handleLeave = () => {
+        const el = rootRef.current;
+        if (el)
+            delete el.dataset.active;
+    };
+    return (_jsxs("div", { ref: rootRef, className: cx('spotlight', className), style: baseStyle, onPointerMove: handleMove, onPointerLeave: handleLeave, ...rest, children: [_jsx("div", { "aria-hidden": "true", className: "spotlight__glow" }), _jsx("div", { className: "spotlight__content", children: children })] }));
+}

package/dist/StackedLineChart.d.ts

@@ -0,0 +1,35 @@
+import { type HTMLAttributes } from 'react';
+export type LineSeries = {
+    label: string;
+    values: number[];
+};
+type StackedLineChartProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+    series: LineSeries[];
+    /** Accessible name for the chart. Required. */
+    label: string;
+    /** `lines` (default) overlays one line per series; `stacked` fills part-to-whole bands. */
+    variant?: 'lines' | 'stacked';
+    /** viewBox width in coordinate units. Defaults to 200. */
+    width?: number;
+    /** viewBox height in coordinate units. Defaults to 120. */
+    height?: number;
+    /**
+     * Render the swatch legend. Defaults to true, and a legend is the only thing
+     * naming a series here — set this to false with two or more series and
+     * identity becomes colour-only, which fails the same readers the palette was
+     * ordered for. One series never gets a legend regardless: the accessible
+     * name already says what the line is.
+     */
+    showLegend?: boolean;
+};
+/**
+ * Several series over one shared x — either overlaid as lines, or stacked as
+ * part-to-whole bands. Pure SVG from `chartGeometry`, matching the Angular
+ * `PaulStackedLineChart`.
+ *
+ * Both variants take their y-domain from `chartGeometry`, which computes it
+ * once across every series. That is the whole point of the primitive: series
+ * rescaled to their own extents look comparable and aren't.
+ */
+export declare function StackedLineChart({ series, label, variant, width, height, showLegend, className, ...props }: StackedLineChartProps): import("react").JSX.Element;
+export {};

package/dist/StackedLineChart.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from './cx';
+import { multiLinePoints, stackedSeries } from './chartGeometry';
+/**
+ * Series colour comes from the CATEGORICAL palette: series are identities, not
+ * magnitudes. Clamped at slot 6 rather than cycled — a seventh line reusing
+ * slot 1 would read as the first series, and two identical hues on one plot is
+ * worse than none. Past six, facet or roll the tail into "Other".
+ */
+const seriesColor = (i) => `var(--paul-chart-${Math.min(i, 5) + 1})`;
+const toPath = (points) => points.map((p, i) => `${i === 0 ? 'M' : 'L'}${p.x},${p.y}`).join(' ');
+/**
+ * Several series over one shared x — either overlaid as lines, or stacked as
+ * part-to-whole bands. Pure SVG from `chartGeometry`, matching the Angular
+ * `PaulStackedLineChart`.
+ *
+ * Both variants take their y-domain from `chartGeometry`, which computes it
+ * once across every series. That is the whole point of the primitive: series
+ * rescaled to their own extents look comparable and aren't.
+ */
+export function StackedLineChart({ series, label, variant = 'lines', width = 200, height = 120, showLegend = true, className, ...props }) {
+    const box = { width, height, padding: 2 };
+    const values = series.map((s) => s.values);
+    const hasData = values.some((v) => v.length > 0);
+    const lines = variant === 'lines' ? multiLinePoints(values, box) : [];
+    const bands = variant === 'stacked' ? stackedSeries(values, box) : [];
+    // The last value is what a trend line is read for, so it is what the
+    // accessible name carries — the drawing itself is hidden.
+    const summary = series
+        .map((s) => `${s.label} ${s.values.length > 0 ? s.values[s.values.length - 1] : 0}`)
+        .join(', ');
+    const name = hasData ? `${label}: ${summary}` : label;
+    // Two or more series ALWAYS get a legend; one never does.
+    const legend = showLegend && hasData && series.length >= 2;
+    return (_jsxs("div", { className: cx('paul-chart', 'paul-chart--lines', className), ...props, children: [_jsx("div", { role: "img", "aria-label": name, className: "paul-chart__figure", children: hasData ? (_jsx("svg", { className: "paul-chart__svg", viewBox: `0 0 ${width} ${height}`, preserveAspectRatio: "none", "aria-hidden": "true", focusable: "false", children: variant === 'stacked'
+                        ? bands.map((band) => (_jsx("path", { className: "paul-chart__band", d: band.path, fill: seriesColor(band.index) }, band.index)))
+                        : lines.map((points, i) => (_jsx("path", { className: "paul-chart__series-line", d: toPath(points), fill: "none", stroke: seriesColor(i), vectorEffect: "non-scaling-stroke" }, series[i]?.label ?? i))) })) : (_jsx("span", { className: "paul-chart__empty", "aria-hidden": "true", children: "No data" })) }), legend && (_jsx("ul", { className: "paul-chart__legend", children: series.map((s, i) => (_jsxs("li", { className: "paul-chart__legend-item", children: [_jsx("span", { className: "paul-chart__swatch", "aria-hidden": "true", style: { backgroundColor: seriesColor(i) } }), _jsx("span", { className: "paul-chart__legend-label", children: s.label })] }, s.label))) }))] }));
+}

package/dist/Ticker.js

@@ -1,26 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
 import { cx } from './cx';
-/**
- * Tracks prefers-reduced-motion. Defaults to false so the server and the first
- * client render agree (SSR-stable), then updates once mounted.
- */
-function usePrefersReducedMotion() {
-    const [reduced, setReduced] = useState(false);
-    useEffect(() => {
-        if (typeof window === 'undefined' ||
-            typeof window.matchMedia !== 'function') {
-            return;
-        }
-        const query = window.matchMedia('(prefers-reduced-motion: reduce)');
-        // Microtask defer keeps the effect from setting state synchronously.
-        queueMicrotask(() => setReduced(query.matches));
-        const onChange = (e) => setReduced(e.matches);
-        query.addEventListener('change', onChange);
-        return () => query.removeEventListener('change', onChange);
-    }, []);
-    return reduced;
-}
+import { usePrefersReducedMotion } from './usePrefersReducedMotion';
 /** How long a touch keeps the strip frozen before the ambient scroll resumes. */
 const TOUCH_RESUME_MS = 4000;
 /**
@@ -51,10 +32,18 @@ function ScrollTicker({ label, edge = 'top', direction = 'left', speed = 40, cla
     useEffect(() => {
         pausedRef.current = paused;
     }, [paused]);
-    // The clone fills the trailing half of the loop and stays clickable for
-    // pointer users, so drop its focusables out of the tab order by hand. Paired
-    // with aria-hidden, screen readers and axe never see the duplicate.
+    // Fallback for browsers without `inert`.
+    //
+    // The clone carries `inert` in the markup, which drops its descendants from
+    // the tab order and the accessibility tree together, before first paint. This
+    // effect used to be the only mechanism, and it left a gap: an effect runs
+    // after the DOM exists, so between render and this call the duplicate held
+    // tabbable controls inside an aria-hidden container. Hiding something from
+    // assistive tech while leaving it reachable by keyboard is worse than not
+    // hiding it — the user lands on a control a screen reader insists is absent.
     useEffect(() => {
+        if ('inert' in HTMLElement.prototype)
+            return;
         const focusables = cloneRef.current?.querySelectorAll('a[href], button, input, select, textarea, [tabindex]');
         focusables?.forEach((el) => {
             el.tabIndex = -1;
@@ -103,5 +92,5 @@ function ScrollTicker({ label, edge = 'top', direction = 'left', speed = 40, cla
     if (reduced) {
         return (_jsx("section", { "aria-label": label, className: classes, children: _jsx("div", { className: "ticker__group", children: children }) }));
     }
-    return (_jsx("section", { ref: scrollerRef, "aria-label": label, "data-direction": direction, className: classes, onMouseEnter: () => setPaused(true), onMouseLeave: () => setPaused(false), onTouchStart: freezeForTouch, children: _jsxs("div", { className: "ticker__track", "data-paused": paused || undefined, children: [_jsx("div", { className: "ticker__group", children: children }), _jsx("div", { ref: cloneRef, "aria-hidden": "true", className: "ticker__group", children: children })] }) }));
+    return (_jsx("section", { ref: scrollerRef, "aria-label": label, "data-direction": direction, className: classes, onMouseEnter: () => setPaused(true), onMouseLeave: () => setPaused(false), onTouchStart: freezeForTouch, children: _jsxs("div", { className: "ticker__track", "data-paused": paused || undefined, children: [_jsx("div", { className: "ticker__group", children: children }), _jsx("div", { ref: cloneRef, "aria-hidden": "true", inert: true, className: "ticker__group", children: children })] }) }));
 }

package/dist/TiltCard.d.ts

@@ -0,0 +1,17 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+type TiltCardProps = HTMLAttributes<HTMLDivElement> & {
+    /** Maximum rotation, in degrees, at the edges of the card. */
+    maxTilt?: number;
+    /** Show the cursor-tracking glare highlight. Defaults to true. */
+    glare?: boolean;
+    children: ReactNode;
+};
+/**
+ * A surface that tilts in 3D toward the pointer, with an optional glare that
+ * tracks the cursor. The effect is purely decorative — the content layer stays
+ * readable — and it is pointer-driven only, so keyboard users are never left
+ * without access. Under prefers-reduced-motion it renders as a flat card with
+ * no tilt or glare. Content-agnostic: pass any children (a Card, an image…).
+ */
+export declare function TiltCard({ maxTilt, glare, className, children, ...rest }: TiltCardProps): import("react").JSX.Element;
+export {};

package/dist/TiltCard.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef } from 'react';
+import { cx } from './cx';
+import { usePrefersReducedMotion } from './usePrefersReducedMotion';
+/**
+ * A surface that tilts in 3D toward the pointer, with an optional glare that
+ * tracks the cursor. The effect is purely decorative — the content layer stays
+ * readable — and it is pointer-driven only, so keyboard users are never left
+ * without access. Under prefers-reduced-motion it renders as a flat card with
+ * no tilt or glare. Content-agnostic: pass any children (a Card, an image…).
+ */
+export function TiltCard({ maxTilt = 12, glare = true, className, children, ...rest }) {
+    const reduced = usePrefersReducedMotion();
+    const innerRef = useRef(null);
+    // No tilt, no glare, no pointer handlers — just a flat, static card.
+    if (reduced) {
+        return (_jsx("div", { className: cx('tilt-card', className), ...rest, children: _jsx("div", { className: "tilt-card__inner", children: children }) }));
+    }
+    const handleMove = (e) => {
+        const rect = e.currentTarget.getBoundingClientRect();
+        if (rect.width === 0 || rect.height === 0)
+            return;
+        const px = (e.clientX - rect.left) / rect.width; // 0 (left) … 1 (right)
+        const py = (e.clientY - rect.top) / rect.height; // 0 (top) … 1 (bottom)
+        const rotateY = (px - 0.5) * 2 * maxTilt;
+        const rotateX = -(py - 0.5) * 2 * maxTilt;
+        const inner = innerRef.current;
+        if (!inner)
+            return;
+        inner.style.setProperty('--paul-tilt-x', `${rotateX.toFixed(2)}deg`);
+        inner.style.setProperty('--paul-tilt-y', `${rotateY.toFixed(2)}deg`);
+        inner.style.setProperty('--paul-glare-x', `${(px * 100).toFixed(1)}%`);
+        inner.style.setProperty('--paul-glare-y', `${(py * 100).toFixed(1)}%`);
+        inner.dataset.active = 'true';
+    };
+    const handleLeave = () => {
+        const inner = innerRef.current;
+        if (!inner)
+            return;
+        inner.style.setProperty('--paul-tilt-x', '0deg');
+        inner.style.setProperty('--paul-tilt-y', '0deg');
+        delete inner.dataset.active;
+    };
+    return (_jsx("div", { className: cx('tilt-card', className), onPointerMove: handleMove, onPointerLeave: handleLeave, ...rest, children: _jsxs("div", { ref: innerRef, className: "tilt-card__inner", children: [glare && _jsx("div", { "aria-hidden": "true", className: "tilt-card__glare" }), children] }) }));
+}

package/dist/WordCloud.d.ts

@@ -0,0 +1,38 @@
+import { type HTMLAttributes } from 'react';
+export type WordCloudDatum = {
+    text: string;
+    weight: number;
+};
+type WordCloudProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+    terms: WordCloudDatum[];
+    /** Accessible name for the chart. Required. */
+    label: string;
+    /** Terms considered, heaviest first. Beyond this the tail is dropped. Defaults to 50. */
+    limit?: number;
+    /** Font size of the lightest term, in coordinate units. Defaults to 12. */
+    minFontSize?: number;
+    /** Font size of the heaviest term, in coordinate units. Defaults to 40. */
+    maxFontSize?: number;
+    /** viewBox width in coordinate units. Defaults to 400. */
+    width?: number;
+    /** viewBox height in coordinate units. Defaults to 240. */
+    height?: number;
+};
+/**
+ * A word cloud. Read this before you use it:
+ *
+ * Glyph AREA is not a comparable encoding. A long word reads as bigger than a
+ * short one at the same weight, so "internationalization" at weight 10 looks
+ * heavier than "go" at weight 30, and nobody can recover the numbers from the
+ * picture. `BarChart` shows the same data honestly. This component exists
+ * because a gallery wants one — when the numbers matter, reach for the bars.
+ *
+ * The aria-label carries the ranked term/weight list, which is the honest
+ * version of the same data, so a screen reader gets the better chart.
+ *
+ * Pure SVG from `chartGeometry`, matching the Angular `PaulWordCloud`. The
+ * layout has no randomness in it: the same input renders the same picture every
+ * time, so server and client agree and visual regression settles.
+ */
+export declare function WordCloud({ terms, label, limit, minFontSize, maxFontSize, width, height, className, ...props }: WordCloudProps): import("react").JSX.Element;
+export {};

package/dist/WordCloud.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from './cx';
+import { wordCloudLayout } from './chartGeometry';
+/**
+ * A word cloud. Read this before you use it:
+ *
+ * Glyph AREA is not a comparable encoding. A long word reads as bigger than a
+ * short one at the same weight, so "internationalization" at weight 10 looks
+ * heavier than "go" at weight 30, and nobody can recover the numbers from the
+ * picture. `BarChart` shows the same data honestly. This component exists
+ * because a gallery wants one — when the numbers matter, reach for the bars.
+ *
+ * The aria-label carries the ranked term/weight list, which is the honest
+ * version of the same data, so a screen reader gets the better chart.
+ *
+ * Pure SVG from `chartGeometry`, matching the Angular `PaulWordCloud`. The
+ * layout has no randomness in it: the same input renders the same picture every
+ * time, so server and client agree and visual regression settles.
+ */
+export function WordCloud({ terms, label, limit = 50, minFontSize = 12, maxFontSize = 40, width = 400, height = 240, className, ...props }) {
+    const words = wordCloudLayout(terms, { width, height, padding: 4 }, { limit, minFontSize, maxFontSize });
+    // Ranked from the input rather than from the layout: a term the spiral had no
+    // room for still belongs in the accessible list. Same filter, sort and cap the
+    // geometry applies, so the two stay in step.
+    const ranked = [...terms]
+        .filter((t) => t.weight > 0)
+        .sort((a, b) => b.weight - a.weight)
+        .slice(0, limit);
+    const summary = ranked.map((t) => `${t.text} ${t.weight}`).join(', ');
+    const name = ranked.length > 0 ? `${label}: ${summary}` : label;
+    // Weight is already carried by font size. Ramping colour by weight too would
+    // encode the same number twice; the categorical slots just keep the words
+    // apart, cycling by rank.
+    const colorFor = (i) => `var(--paul-chart-${(i % 6) + 1})`;
+    return (_jsx("div", { className: cx('paul-chart', 'paul-chart--word-cloud', className), ...props, children: _jsx("div", { role: "img", "aria-label": name, className: "paul-chart__figure", children: words.length > 0 ? (_jsx("svg", { className: "paul-chart__svg", viewBox: `0 0 ${width} ${height}`, "aria-hidden": "true", focusable: "false", children: words.map((word) => (_jsx("text", { className: "paul-chart__word", x: word.x, y: word.y, fontSize: word.fontSize, fill: colorFor(word.index), textAnchor: "middle", dominantBaseline: "middle", children: word.text }, word.text))) })) : (_jsx("span", { className: "paul-chart__empty", "aria-hidden": "true", children: "No data" })) }) }));
+}

package/dist/chartGeometry.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Pure, dependency-free chart geometry. Every function turns a plain array of
+ * numbers into SVG coordinates or path strings, so the React and Angular chart
+ * components can render identical output without pulling in a charting runtime.
+ *
+ * This module is deliberately framework-agnostic and side-effect-free. It is
+ * mirrored verbatim in @paul-portfolio/angular; the unit tests in each package
+ * guard the two copies against drifting.
+ */
+export interface ChartBox {
+    width: number;
+    height: number;
+    /** Uniform inset, in px, between the drawing and the edges of the box. */
+    padding?: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    value: number;
+}
+export interface BarOptions {
+    /** Fraction of each band left empty as a gap, 0..1. Defaults to 0.25. */
+    gap?: number;
+}
+export interface DonutOptions {
+    /** Outer diameter of the ring, in px. */
+    size: number;
+    /** Ring thickness (outer radius − inner radius), in px. */
+    thickness: number;
+    /** Angle, in degrees, where the first slice starts. 0 is straight up. */
+    startAngle?: number;
+}
+export interface DonutSegment {
+    path: string;
+    percent: number;
+    startAngle: number;
+    endAngle: number;
+    index: number;
+}
+/** Maps each value to a point, spread evenly across the inner width. */
+export declare function linePoints(values: number[], box: ChartBox): Point[];
+export declare function linePath(values: number[], box: ChartBox): string;
+export declare function areaPath(values: number[], box: ChartBox): string;
+/** Vertical bars: one rect per value, heights proportional to the value. */
+export declare function barRects(values: number[], box: ChartBox, opts?: BarOptions): Rect[];
+/** Horizontal bars: one rect per value, widths proportional to the value. */
+export declare function barRectsHorizontal(values: number[], box: ChartBox, opts?: BarOptions): Rect[];
+/** 0deg points straight up; angle increases clockwise. */
+export declare function polarToCartesian(cx: number, cy: number, r: number, angleDeg: number): Point;
+/** SVG path for a ring wedge between two radii and two angles. */
+export declare function arcPath(cx: number, cy: number, rOuter: number, rInner: number, startAngle: number, endAngle: number): string;
+export declare function donutSegments(values: number[], opts: DonutOptions): DonutSegment[];
+export interface FunnelStage {
+    /** Trapezoid path for the stage band. */
+    path: string;
+    /** Share of the FIRST stage, 0..100 — what "conversion" means in a funnel. */
+    percent: number;
+    /** Loss from the previous stage, 0..100. 0 for the first stage. */
+    dropOff: number;
+    value: number;
+    index: number;
+}
+/**
+ * Stacked trapezoids narrowing stage to stage. Widths are proportional to the
+ * value, centred, so the taper reads as the drop-off — which is the number a
+ * funnel is actually read for, hence `dropOff` on every stage.
+ */
+export declare function funnelStages(values: number[], box: ChartBox, gap?: number): FunnelStage[];
+export interface RadarAxis {
+    /** Outer end of the spoke. */
+    x: number;
+    y: number;
+    angle: number;
+    index: number;
+}
+export interface RadarGeometry {
+    cx: number;
+    cy: number;
+    radius: number;
+    axes: RadarAxis[];
+    /** Radii of the background rings, outermost last. */
+    rings: number[];
+}
+/**
+ * Spokes and rings for a radar chart. `radarPolygon` draws on the same centre
+ * and radius, so the series and the frame can't disagree.
+ */
+export declare function radarAxes(count: number, box: ChartBox, ringCount?: number): RadarGeometry;
+/**
+ * A closed point list for one series. `max` fixes the scale so several series —
+ * or several small multiples — are comparable; it defaults to the series max.
+ */
+export declare function radarPolygon(values: number[], box: ChartBox, max?: number): Point[];
+export interface ScatterDatum {
+    x: number;
+    y: number;
+}
+export interface ScatterPoint extends Point {
+    datum: ScatterDatum;
+    index: number;
+}
+export interface ScatterDomain {
+    xMin: number;
+    xMax: number;
+    yMin: number;
+    yMax: number;
+}
+/**
+ * Maps points into the box. Pass an explicit `domain` when several plots must
+ * share a scale — without it each plot silently rescales to its own extent and
+ * they stop being comparable.
+ */
+export declare function scatterPoints(data: ScatterDatum[], box: ChartBox, domain?: ScatterDomain): ScatterPoint[];
+export interface HeatmapCell extends Rect {
+    /** 0..1 against the matrix max — the input to the SEQUENTIAL ramp. */
+    intensity: number;
+    row: number;
+    col: number;
+}
+/**
+ * A grid of cells with a normalised intensity per cell. Intensity is deliberately
+ * 0..1 rather than a colour: the component maps it onto the sequential ramp, and
+ * a categorical palette here would double-encode the value as hue.
+ */
+export declare function heatmapCells(matrix: number[][], box: ChartBox, gap?: number): HeatmapCell[];
+export interface ParetoLayout {
+    /** Bars as PERCENT of total, so they share the cumulative line's scale. */
+    bars: Rect[];
+    /** Cumulative percentage points, in the same coordinate space as the bars. */
+    cumulative: Point[];
+    /** Percent value per index, sorted descending like the bars. */
+    percents: number[];
+    /** Index where the cumulative line first crosses 80% — the Pareto cut. */
+    cutIndex: number;
+}
+/**
+ * Bars plus a cumulative line on ONE axis.
+ *
+ * The textbook Pareto puts counts on the left and cumulative percent on the
+ * right. Two y-scales on one plot invent a relationship the data doesn't have —
+ * the alignment between them is arbitrary. Here the bars are percent-of-total
+ * and the line is cumulative percent, so both live on the same 0–100 scale and
+ * the crossing point means something.
+ *
+ * Values are sorted descending, as a Pareto requires. `cutIndex` is the first
+ * item at or past `opts.threshold`, so the reported cut and the rule a component
+ * draws can't disagree.
+ */
+export interface ParetoOptions {
+    /** Fraction of each band left empty as a gap, 0..1. Defaults to 0.25. */
+    gap?: number;
+    /**
+     * The cumulative percentage the cut is measured against. Defaults to 80 —
+     * the "80/20" in Pareto — but a caller drawing a different rule needs
+     * `cutIndex` to agree with the line they drew, so it lives here rather than
+     * being re-derived in each component.
+     */
+    threshold?: number;
+}
+export declare function paretoLayout(values: number[], box: ChartBox, opts?: ParetoOptions): ParetoLayout;
+export interface GaugeOptions {
+    size: number;
+    thickness: number;
+    min?: number;
+    max?: number;
+    /** Total sweep in degrees. Defaults to 270 — a dial, not a full ring. */
+    sweep?: number;
+}
+export interface GaugeGeometry {
+    track: string;
+    fill: string;
+    /** 0..100, clamped. */
+    percent: number;
+    /** Where the fill ends, in degrees. */
+    angle: number;
+}
+/**
+ * A single ratio against a limit. Values outside [min, max] clamp rather than
+ * overflowing the arc — a gauge reading 140% of its own dial is a bug, not data.
+ */
+export declare function gaugeArc(value: number, opts: GaugeOptions): GaugeGeometry;
+export interface WordCloudTerm {
+    text: string;
+    weight: number;
+}
+export interface PlacedWord extends WordCloudTerm {
+    x: number;
+    y: number;
+    fontSize: number;
+    index: number;
+}
+export interface WordCloudOptions {
+    minFontSize?: number;
+    maxFontSize?: number;
+    /** Terms considered, highest weight first. Beyond this the tail is dropped. */
+    limit?: number;
+}
+/**
+ * Deterministic spiral packing for a word cloud.
+ *
+ * Caveat, stated where it can't be missed: glyph AREA is not a comparable
+ * encoding, and a long word reads as bigger than a short one at the same
+ * weight. A ranked bar chart shows the same data honestly. This exists because
+ * a gallery wants one; reach for `BarChart` when the numbers matter.
+ *
+ * No randomness anywhere — the same input must produce the same picture, or the
+ * server and the client disagree and visual regression never settles.
+ */
+export declare function wordCloudLayout(terms: WordCloudTerm[], box: ChartBox, opts?: WordCloudOptions): PlacedWord[];
+export interface StackedBand {
+    path: string;
+    index: number;
+}
+/**
+ * One y-domain across every series, computed once. Series scaled independently
+ * look comparable and aren't.
+ */
+export declare function multiLinePoints(series: number[][], box: ChartBox): Point[][];
+/**
+ * Part-to-whole over time: each series is a band stacked on the ones before it,
+ * scaled so the tallest total fills the box.
+ */
+export declare function stackedSeries(series: number[][], box: ChartBox): StackedBand[];