@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/dist/charts/core/unit-icons.js

@@ -0,0 +1,157 @@
+function starPath(cx, cy, outer, inner, points = 5) {
+  const commands = [];
+  for (let i = 0; i < points * 2; i += 1) {
+    const radius = i % 2 === 0 ? outer : inner;
+    const angle = -Math.PI / 2 + i * Math.PI / points;
+    const x = Math.round((cx + radius * Math.cos(angle)) * 100) / 100;
+    const y = Math.round((cy + radius * Math.sin(angle)) * 100) / 100;
+    commands.push(`${i === 0 ? "M" : "L"}${x} ${y}`);
+  }
+  return `${commands.join("")}Z`;
+}
+const PERSON = "M12 2.5a4 4 0 1 1 0 8a4 4 0 1 1 0-8zM4.5 21.5v-2.8c0-3.6 3.3-6.2 7.5-6.2s7.5 2.6 7.5 6.2v2.8z";
+const UNIT_ICONS = {
+  person: { path: PERSON, labelY: 17.5 },
+  scissors: {
+    // Rings wind the other way round, so they stay hollow with the nonzero rule.
+    path: [
+      "M3 17.5a3.5 3.5 0 1 1 7 0a3.5 3.5 0 1 1-7 0zM4.9 17.5a1.6 1.6 0 1 0 3.2 0a1.6 1.6 0 1 0-3.2 0z",
+      "M14 17.5a3.5 3.5 0 1 1 7 0a3.5 3.5 0 1 1-7 0zM15.9 17.5a1.6 1.6 0 1 0 3.2 0a1.6 1.6 0 1 0-3.2 0z",
+      "M8.6 14.6L17.6 2.2L19 3.4L10.5 15.7z",
+      "M13.5 15.7L5 3.4L6.4 2.2L15.4 14.6z"
+    ].join("")
+  },
+  chair: {
+    path: [
+      "M7.5 2.5h9a1.5 1.5 0 0 1 1.5 1.5v6.5H6V4a1.5 1.5 0 0 1 1.5-1.5z",
+      "M3.5 11h17a1 1 0 0 1 1 1v1.5a1 1 0 0 1-1 1h-17a1 1 0 0 1-1-1V12a1 1 0 0 1 1-1z",
+      "M5.5 14.5h13v2.5h-13z",
+      "M11 17h2v3h-2z",
+      "M6.5 20h11a1 1 0 0 1 1 1v.5h-13V21a1 1 0 0 1 1-1z"
+    ].join("")
+  },
+  star: { path: starPath(12, 12.6, 10.5, 4.4) },
+  calendar: {
+    fillRule: "evenodd",
+    path: [
+      "M3.5 7a2 2 0 0 1 2-2h13a2 2 0 0 1 2 2v13a2 2 0 0 1-2 2h-13a2 2 0 0 1-2-2z",
+      "M7 2h2.2v3H7zM14.8 2H17v3h-2.2z",
+      "M6.5 10.5h3v3h-3zM10.5 10.5h3v3h-3zM14.5 10.5h3v3h-3zM6.5 15.5h3v3h-3zM10.5 15.5h3v3h-3z"
+    ].join("")
+  },
+  bottle: {
+    labelY: 14.5,
+    path: [
+      "M9.5 1.5h5v3.5h-5z",
+      "M10.2 5h3.6v2.2c2.6.9 4.2 2.9 4.2 5.6v7.7a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2v-7.7c0-2.7 1.6-4.7 4.2-5.6z"
+    ].join("")
+  },
+  battery: {
+    path: "M2.5 7.5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2h-14a2 2 0 0 1-2-2zM20.5 9.5h1a1 1 0 0 1 1 1v3a1 1 0 0 1-1 1h-1z",
+    fill: "right"
+  },
+  droplet: {
+    path: "M12 1.8c3.9 4.8 7.5 9 7.5 13a7.5 7.5 0 0 1-15 0c0-4 3.6-8.2 7.5-13z"
+  },
+  target: {
+    path: "M2 12a10 10 0 1 0 20 0a10 10 0 1 0-20 0z",
+    detail: "M5.5 12a6.5 6.5 0 1 0 13 0a6.5 6.5 0 1 0-13 0zM9 12a3 3 0 1 0 6 0a3 3 0 1 0-6 0z"
+  },
+  shield: {
+    path: "M12 1.8l8.5 3.2v6.4c0 5.4-3.6 9.5-8.5 11.1c-4.9-1.6-8.5-5.7-8.5-11.1V5z"
+  },
+  woman: {
+    path: "M12 0.9a3.4 3.4 0 1 1 0 6.8a3.4 3.4 0 1 1 0-6.8zM9 9h6l4.5 10h-15zM9.8 19h1.9v4h-1.9zM12.3 19h1.9v4h-1.9z",
+    labelY: 15
+  },
+  child: {
+    path: "M12 5.4a3.2 3.2 0 1 1 0 6.4a3.2 3.2 0 1 1 0-6.4zM6.8 21.5v-2.2c0-2.9 2.3-5 5.2-5s5.2 2.1 5.2 5v2.2z",
+    labelY: 18
+  },
+  heart: {
+    path: "M12 21.2C5.6 16.1 2.5 12.6 2.5 8.6A5 5 0 0 1 12 6.4a5 5 0 0 1 9.5 2.2c0 4-3.1 7.5-9.5 12.6z",
+    labelY: 11.5
+  },
+  tree: {
+    path: "M12 1.8L18 9.5H15.2L19.5 15.5H4.5L8.8 9.5H6zM10.8 15.5h2.4V22h-2.4z",
+    labelY: 11
+  },
+  house: {
+    path: "M12 2.2L21.5 10.6H18.9V21H13.7V15H10.3V21H5.1V10.6H2.5z",
+    labelY: 12
+  },
+  car: {
+    fillRule: "evenodd",
+    path: [
+      "M3.2 12.5l1.7-4.6A2.5 2.5 0 0 1 7.2 6.3h9.6a2.5 2.5 0 0 1 2.3 1.6l1.7 4.6c.9.3 1.5 1.1 1.5 2.1v3.2a1 1 0 0 1-1 1h-1.2a2.8 2.8 0 0 1-5.6 0H9.4a2.8 2.8 0 0 1-5.6 0H2.7a1 1 0 0 1-1-1v-3.2c0-1 .6-1.8 1.5-2.1z",
+      "M7 8h4.2v3.3H5.9zM12.8 8H17l1.1 3.3h-5.3z"
+    ].join("")
+  },
+  drop: {
+    path: "M12 1.8c3.9 4.8 7.5 9 7.5 13a7.5 7.5 0 0 1-15 0c0-4 3.6-8.2 7.5-13z"
+  },
+  clock: {
+    fillRule: "evenodd",
+    path: "M12 2a10 10 0 1 0 0 20a10 10 0 1 0 0-20zM11 6h2v6.3l4 2.3-1 1.7-5-3z"
+  },
+  pin: {
+    fillRule: "evenodd",
+    path: "M12 1.8a7.5 7.5 0 0 0-7.5 7.5c0 5.4 7.5 12.9 7.5 12.9s7.5-7.5 7.5-12.9A7.5 7.5 0 0 0 12 1.8zM12 6.7a2.6 2.6 0 1 1 0 5.2a2.6 2.6 0 1 1 0-5.2z",
+    labelY: 9.3
+  },
+  mustache: {
+    path: "M12 9.2C10.6 7.4 8.6 6.4 6.4 6.4C3.8 6.4 1.9 8 1.5 10.6C3.2 9.6 4.9 9.6 6.4 10.7C8.1 12 9.9 13.4 12 13.4C14.1 13.4 15.9 12 17.6 10.7C19.1 9.6 20.8 9.6 22.5 10.6C22.1 8 20.2 6.4 17.6 6.4C15.4 6.4 13.4 7.4 12 9.2Z",
+    labelY: 10
+  },
+  comb: {
+    path: "M3 4h18a1 1 0 0 1 1 1v4H2V5a1 1 0 0 1 1-1zM3 10h1.6v10H3zM6.2 10h1.6v10H6.2zM9.4 10h1.6v10H9.4zM12.6 10h1.6v10h-1.6zM15.8 10h1.6v10h-1.6zM19 10h1.6v10H19z",
+    labelY: 7
+  },
+  pole: {
+    fillRule: "evenodd",
+    path: "M8 1.5h8v2.5H8zM8.5 4h7v16h-7zM8 20h8v2.5H8zM8.5 7.5l7-2.5v3l-7 2.5zM8.5 13.5l7-2.5v3l-7 2.5z"
+  }
+};
+const PICTOGRAM_SILHOUETTES = [
+  "person",
+  "woman",
+  "child",
+  "heart",
+  "tree",
+  "house",
+  "car",
+  "star",
+  "drop",
+  "clock",
+  "pin"
+];
+const BARBER_SILHOUETTES = [
+  "scissors",
+  "comb",
+  "mustache",
+  "pole",
+  "chair",
+  "bottle"
+];
+function isUnitIconName(value) {
+  return typeof value === "string" && Object.hasOwn(UNIT_ICONS, value);
+}
+function resolveUnitShape(icon) {
+  const shape = isUnitIconName(icon) ? UNIT_ICONS[icon] : typeof icon === "string" ? { path: icon } : icon;
+  return {
+    path: shape.path,
+    width: shape.width ?? 24,
+    height: shape.height ?? 24,
+    fillRule: shape.fillRule ?? "nonzero",
+    detail: shape.detail,
+    fill: shape.fill ?? "up",
+    labelY: shape.labelY ?? (shape.height ?? 24) / 2
+  };
+}
+export {
+  BARBER_SILHOUETTES,
+  PICTOGRAM_SILHOUETTES,
+  UNIT_ICONS,
+  isUnitIconName,
+  resolveUnitShape
+};

package/dist/charts/core/units.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Pure geometry for unit charts (pictograms, waffles, hemicycles, isotypes,
+ * rating stars): how many units a value takes, how integer cells are shared
+ * between categories, and where every unit sits. No React, no DOM.
+ */
+export interface UnitCount {
+    /** Completely filled units. */
+    full: number;
+    /** Fill of the last unit, 0 (none) to under 1. */
+    partial: number;
+    /** Units drawn: `full`, plus one when `partial > 0`. */
+    units: number;
+}
+/** 23 people at 5 per icon -> 4 full icons and a 0.6 icon. */
+export declare function unitCount(value: number, perUnit?: number): UnitCount;
+/** Fill of every unit a value takes: `unitFractions(23, 5)` -> `[1, 1, 1, 1, 0.6]`. */
+export declare function unitFractions(value: number, perUnit?: number): number[];
+/** Rounds to the nearest multiple of `step` (e.g. 0.5 for half stars). No step, no rounding. */
+export declare function roundToStep(value: number, step?: number): number;
+/**
+ * Fill of each of `count` units sharing `max`: a 4.5 rating out of 5 stars is
+ * `[1, 1, 1, 1, 0.5]`. The value is clamped to `[0, max]` and rounded to `step`.
+ */
+export declare function progressFractions(value: number, max: number, count: number, step?: number): number[];
+/**
+ * Shares `total` whole units between weights so they add up exactly
+ * (largest remainder method). Negative or missing weights count as zero; all
+ * zero weights get nothing.
+ */
+export declare function largestRemainder(weights: readonly number[], total: number): number[];
+/**
+ * Cells per category in a waffle of `cells` cells. Without `total` the
+ * categories fill the whole grid; with a `total` larger than their sum, the
+ * remainder stays empty (e.g. 62 of 100 chairs taken).
+ */
+export declare function waffleCounts(values: readonly number[], cells: number, total?: number): number[];
+export type GridOrder = "row" | "column";
+/**
+ * Cell of the `index`-th unit. "row" fills left to right from the top row;
+ * "column" fills bottom to top from the left column (the classic waffle).
+ */
+export declare function gridCell(index: number, columns: number, rows: number, order?: GridOrder): {
+    row: number;
+    column: number;
+};
+export interface UnitGridFit {
+    columns: number;
+    rows: number;
+    /** Side of one unit in pixels. */
+    size: number;
+}
+export interface UnitGridOptions {
+    width: number;
+    height: number;
+    /** Gap between units as a fraction of the unit size. */
+    gap?: number;
+    /** Largest unit side, in pixels. */
+    maxSize?: number;
+    /** Most columns worth trying (usually the longest run of units). */
+    maxColumns: number;
+    /** Rows needed with a given number of columns. */
+    rowsFor: (columns: number) => number;
+    /** Force a column count instead of searching. */
+    columns?: number;
+}
+/**
+ * Picks the column count that gives the largest units inside `width` x
+ * `height`. When the size is capped, the widest layout wins (fewer rows).
+ */
+export declare function fitUnitGrid({ width, height, gap, maxSize, maxColumns, rowsFor, columns: fixed, }: UnitGridOptions): UnitGridFit;
+export interface Seat {
+    /** Center relative to the hemicycle center, in outer-radius units (y grows downwards). */
+    x: number;
+    y: number;
+    /** 0 is the innermost row. */
+    row: number;
+    /** Radians, pi on the left end, 0 on the right end. */
+    angle: number;
+}
+export interface ParliamentLayout {
+    rows: number;
+    /** Radius of each seat, in outer-radius units. */
+    seatRadius: number;
+    /** Every seat ordered left to right, so consecutive groups form wedges. */
+    seats: Seat[];
+    /** Radius of every row, innermost first. */
+    radii: number[];
+}
+/** Fewest arcs that hold `seats` without crowding. */
+export declare function parliamentRows(seats: number, innerRatio?: number): number;
+/**
+ * Seats of a hemicycle. Rows are auto-computed for the seat count (or fixed
+ * with `rows`), each row gets seats in proportion to its length, and the
+ * result is sorted left to right so assigning groups in order draws wedges.
+ */
+export declare function parliamentLayout(total: number, { rows: fixedRows, innerRatio }?: {
+    rows?: number;
+    innerRatio?: number;
+}): ParliamentLayout;
+/** Category of each position when `counts` are laid one after the other. */
+export declare function assignUnits(counts: readonly number[]): number[];

package/dist/charts/core/units.js

@@ -0,0 +1,161 @@
+const EPSILON = 1e-9;
+function clean(value) {
+  return Math.round(value * 1e9) / 1e9;
+}
+function unitCount(value, perUnit = 1) {
+  if (!Number.isFinite(value) || value <= 0 || !(perUnit > 0)) {
+    return { full: 0, partial: 0, units: 0 };
+  }
+  const exact = clean(value / perUnit);
+  const full = Math.floor(exact);
+  const partial = clean(exact - full);
+  return { full, partial, units: full + (partial > 0 ? 1 : 0) };
+}
+function unitFractions(value, perUnit = 1) {
+  const { full, partial } = unitCount(value, perUnit);
+  const fractions = Array.from({ length: full }, () => 1);
+  if (partial > 0) fractions.push(partial);
+  return fractions;
+}
+function roundToStep(value, step) {
+  if (!step || !(step > 0)) return value;
+  return clean(Math.round(value / step) * step);
+}
+function progressFractions(value, max, count, step) {
+  const units = Math.max(0, Math.floor(count));
+  if (!units || !(max > 0) || !Number.isFinite(value))
+    return Array.from({ length: units }, () => 0);
+  const clamped = Math.min(max, Math.max(0, roundToStep(value, step)));
+  const filled = clean(clamped / max * units);
+  return Array.from(
+    { length: units },
+    (_, index) => Math.min(1, Math.max(0, clean(filled - index)))
+  );
+}
+function largestRemainder(weights, total) {
+  const safe = weights.map((weight) => Number.isFinite(weight) && weight > 0 ? weight : 0);
+  const sum = safe.reduce((acc, weight) => acc + weight, 0);
+  const slots = Math.max(0, Math.round(total));
+  if (sum <= 0 || slots === 0) return safe.map(() => 0);
+  const exact = safe.map((weight) => weight / sum * slots);
+  const counts = exact.map((share) => Math.floor(clean(share)));
+  let left = slots - counts.reduce((acc, count) => acc + count, 0);
+  const order = exact.map((share, index) => ({ index, rest: share - counts[index] })).filter((entry) => safe[entry.index] > 0).sort((a, b) => b.rest - a.rest || a.index - b.index);
+  for (let i = 0; left > 0 && order.length > 0; i += 1, left -= 1) {
+    const entry = order[i % order.length];
+    counts[entry.index] = counts[entry.index] + 1;
+  }
+  return counts;
+}
+function waffleCounts(values, cells, total) {
+  const sum = values.reduce(
+    (acc, value) => acc + (Number.isFinite(value) && value > 0 ? value : 0),
+    0
+  );
+  if (total != null && total > sum) {
+    return largestRemainder([...values, total - sum], cells).slice(0, values.length);
+  }
+  return largestRemainder(values, cells);
+}
+function gridCell(index, columns, rows, order = "row") {
+  if (order === "column") {
+    return { column: Math.floor(index / rows), row: rows - 1 - index % rows };
+  }
+  return { row: Math.floor(index / columns), column: index % columns };
+}
+function sideFor(width, height, columns, rows, gap) {
+  const across = columns + Math.max(0, columns - 1) * gap;
+  const down = rows + Math.max(0, rows - 1) * gap;
+  return Math.min(width / across, height / Math.max(1, down));
+}
+function fitUnitGrid({
+  width,
+  height,
+  gap = 0.2,
+  maxSize = Number.POSITIVE_INFINITY,
+  maxColumns,
+  rowsFor,
+  columns: fixed
+}) {
+  const limit = Math.max(1, Math.floor(maxColumns));
+  if (fixed && fixed > 0) {
+    const rows = rowsFor(fixed);
+    return {
+      columns: fixed,
+      rows,
+      size: Math.min(maxSize, sideFor(width, height, fixed, rows, gap))
+    };
+  }
+  let best = { columns: 1, rows: rowsFor(1), size: 0 };
+  for (let columns = 1; columns <= limit; columns += 1) {
+    const rows = rowsFor(columns);
+    const size = Math.min(maxSize, sideFor(width, height, columns, rows, gap));
+    if (size >= best.size - EPSILON) best = { columns, rows, size };
+  }
+  return best;
+}
+function rowRadii(rows, inner) {
+  if (rows <= 1) return [1];
+  return Array.from({ length: rows }, (_, row) => inner + (1 - inner) * row / (rows - 1));
+}
+function arcCapacity(rows, inner) {
+  if (rows <= 1) return 5;
+  const spacing = (1 - inner) / (rows - 1);
+  return rowRadii(rows, inner).reduce(
+    (acc, radius) => acc + Math.floor(Math.PI * radius / spacing) + 1,
+    0
+  );
+}
+function parliamentRows(seats, innerRatio = 0.4) {
+  if (seats <= 0) return 0;
+  const inner = Math.min(0.9, Math.max(0, innerRatio));
+  let rows = 1;
+  while (rows < 60 && arcCapacity(rows, inner) < seats) rows += 1;
+  return rows;
+}
+function parliamentLayout(total, { rows: fixedRows, innerRatio = 0.4 } = {}) {
+  const seatsWanted = Math.max(0, Math.floor(total));
+  if (seatsWanted === 0) return { rows: 0, seatRadius: 0, seats: [], radii: [] };
+  const inner = Math.min(0.9, Math.max(0, innerRatio));
+  const rows = Math.max(1, Math.min(seatsWanted, fixedRows ?? parliamentRows(seatsWanted, inner)));
+  const radii = rowRadii(rows, inner);
+  const perRow = largestRemainder(radii, seatsWanted);
+  const seats = [];
+  let spacing = rows > 1 ? (1 - inner) / (rows - 1) : Number.POSITIVE_INFINITY;
+  perRow.forEach((count, row) => {
+    const radius = radii[row];
+    if (count > 1) spacing = Math.min(spacing, Math.PI * radius / (count - 1));
+    for (let index = 0; index < count; index += 1) {
+      const angle = count === 1 ? Math.PI / 2 : Math.PI - index * Math.PI / (count - 1);
+      seats.push({
+        x: clean(radius * Math.cos(angle)),
+        y: clean(-radius * Math.sin(angle)),
+        row,
+        angle
+      });
+    }
+  });
+  seats.sort((a, b) => b.angle - a.angle || a.row - b.row);
+  const seatRadius = Number.isFinite(spacing) ? spacing * 0.42 : 0.3;
+  return { rows, seatRadius, seats, radii };
+}
+function assignUnits(counts) {
+  const owners = [];
+  counts.forEach((count, category) => {
+    for (let i = 0; i < count; i += 1) owners.push(category);
+  });
+  return owners;
+}
+export {
+  assignUnits,
+  fitUnitGrid,
+  gridCell,
+  largestRemainder,
+  parliamentLayout,
+  parliamentRows,
+  progressFractions,
+  roundToStep,
+  unitCount,
+  unitFractions,
+  waffleCounts
+};

package/dist/charts/core/use-canvas.d.ts

@@ -0,0 +1,24 @@
+import { type RefObject } from "react";
+/**
+ * Bumps whenever the theme or accent changes (`data-theme` / `data-accent` on
+ * `<html>`), so canvas layers that bake token colors into pixels repaint.
+ */
+export declare function useThemeVersion(): number;
+/**
+ * Resolves CSS colors (`var(--token)`, `color-mix(...)`) to a string a canvas
+ * understands, using the cascade of `host`. Unresolvable values are returned
+ * unchanged.
+ */
+export declare function resolveCssColors(host: Element, colors: readonly string[]): string[];
+export interface CanvasPaint {
+    ctx: CanvasRenderingContext2D;
+    width: number;
+    height: number;
+    /** Resolve a CSS color once per paint (cached by the caller if needed). */
+    resolve: (colors: readonly string[]) => string[];
+}
+/**
+ * Sizes a canvas for the device pixel ratio and repaints it whenever `deps`
+ * or the theme change. `paint` draws in CSS pixels.
+ */
+export declare function useCanvasPaint(ref: RefObject<HTMLCanvasElement | null>, width: number, height: number, paint: (frame: CanvasPaint) => void, deps: readonly unknown[]): void;

package/dist/charts/core/use-canvas.js

@@ -0,0 +1,50 @@
+"use client";
+import { useEffect, useState } from "react";
+function useThemeVersion() {
+  const [version, setVersion] = useState(0);
+  useEffect(() => {
+    if (typeof document === "undefined" || typeof MutationObserver === "undefined") return;
+    const observer = new MutationObserver(() => setVersion((value) => value + 1));
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["data-theme", "data-accent", "class"]
+    });
+    return () => observer.disconnect();
+  }, []);
+  return version;
+}
+function resolveCssColors(host, colors) {
+  if (typeof document === "undefined") return [...colors];
+  const probe = document.createElement("span");
+  probe.style.cssText = "position:absolute;visibility:hidden;pointer-events:none";
+  host.appendChild(probe);
+  try {
+    return colors.map((color) => {
+      probe.style.color = "";
+      probe.style.color = color;
+      return probe.style.color ? getComputedStyle(probe).color : color;
+    });
+  } finally {
+    host.removeChild(probe);
+  }
+}
+function useCanvasPaint(ref, width, height, paint, deps) {
+  const theme = useThemeVersion();
+  useEffect(() => {
+    const canvas = ref.current;
+    if (!canvas || width <= 0 || height <= 0) return;
+    const ratio = typeof window === "undefined" ? 1 : Math.min(3, window.devicePixelRatio || 1);
+    canvas.width = Math.max(1, Math.round(width * ratio));
+    canvas.height = Math.max(1, Math.round(height * ratio));
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+    ctx.setTransform(ratio, 0, 0, ratio, 0, 0);
+    ctx.clearRect(0, 0, width, height);
+    paint({ ctx, width, height, resolve: (colors) => resolveCssColors(canvas, colors) });
+  }, [ref, width, height, theme, ...deps]);
+}
+export {
+  resolveCssColors,
+  useCanvasPaint,
+  useThemeVersion
+};

package/dist/charts/core/use-chart-size.d.ts

@@ -0,0 +1,19 @@
+import { type RefObject, useEffect } from "react";
+/** Layout effect in the browser, plain effect on the server (no SSR warning). */
+export declare const useIsomorphicLayoutEffect: typeof useEffect;
+/** Width used for the server render and the first client paint before measuring. */
+export declare const FALLBACK_WIDTH = 640;
+/** Height used before the first measurement when a chart fills its parent. */
+export declare const FALLBACK_HEIGHT = 300;
+export interface ChartSize {
+    width: number;
+    height: number;
+}
+/**
+ * Tracks the content box of an element with a ResizeObserver. Renders with
+ * the fallback size on the server and until the first measurement.
+ */
+export declare function useChartSize<T extends HTMLElement>(fallback?: ChartSize): [RefObject<T | null>, ChartSize];
+/** Width only (kept for charts that do not need the height). */
+export declare function useChartWidth<T extends HTMLElement>(fallbackWidth?: number): [RefObject<T | null>, number];
+export { type ResolveHeightInput, resolveDrawingHeight } from "./drawing-height.js";

package/dist/charts/core/use-chart-size.js

@@ -0,0 +1,43 @@
+"use client";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+const FALLBACK_WIDTH = 640;
+const FALLBACK_HEIGHT = 300;
+function useChartSize(fallback = { width: FALLBACK_WIDTH, height: FALLBACK_HEIGHT }) {
+  const ref = useRef(null);
+  const [size, setSize] = useState(fallback);
+  useIsomorphicLayoutEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+    const apply = (width, height) => {
+      setSize((current) => {
+        const nextWidth = width > 0 ? width : current.width;
+        const nextHeight = height > 0 ? height : current.height;
+        return Math.abs(current.width - nextWidth) < 0.5 && Math.abs(current.height - nextHeight) < 0.5 ? current : { width: nextWidth, height: nextHeight };
+      });
+    };
+    const rect = element.getBoundingClientRect();
+    apply(rect.width, rect.height);
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (entry) apply(entry.contentRect.width, entry.contentRect.height);
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+  return [ref, { width: Math.floor(size.width), height: Math.floor(size.height) }];
+}
+function useChartWidth(fallbackWidth = FALLBACK_WIDTH) {
+  const [ref, size] = useChartSize({ width: fallbackWidth, height: FALLBACK_HEIGHT });
+  return [ref, size.width];
+}
+import { resolveDrawingHeight } from "./drawing-height.js";
+export {
+  FALLBACK_HEIGHT,
+  FALLBACK_WIDTH,
+  resolveDrawingHeight,
+  useChartSize,
+  useChartWidth,
+  useIsomorphicLayoutEffect
+};

package/dist/charts/core/use-drill.d.ts

@@ -0,0 +1,26 @@
+import { type HierarchyDatum, type HierarchyNode, type PartitionView } from "./hierarchy.js";
+export interface DrillState {
+    root: HierarchyNode;
+    /** Node filling the view. */
+    focus: HierarchyNode;
+    /** Root first, focus last. */
+    path: HierarchyNode[];
+    /** Zooms into a node with children; any ancestor id zooms back out. */
+    drill: (id: string) => void;
+    /** One level up; returns false at the root. */
+    up: () => boolean;
+}
+/**
+ * Builds the hierarchy once per data set and keeps the focused (zoomed) node.
+ * Drilling into a leaf does nothing; a stale focus falls back to the root.
+ */
+export declare function useDrill(data: HierarchyDatum, sort?: boolean, onFocusChange?: (node: HierarchyNode) => void): DrillState;
+/**
+ * Animates a partition view (the zoom window of a sunburst or icicle) towards
+ * `target` with `requestAnimationFrame`. Jumps straight there when disabled,
+ * under `prefers-reduced-motion`, or on the server.
+ */
+export declare function useAnimatedView(target: PartitionView, { disabled, duration }?: {
+    disabled?: boolean;
+    duration?: number;
+}): PartitionView;

package/dist/charts/core/use-drill.js

@@ -0,0 +1,67 @@
+"use client";
+import { useEffect, useMemo, useRef, useState } from "react";
+import {
+  ancestors,
+  buildHierarchy,
+  findNode,
+  interpolateView
+} from "./hierarchy.js";
+import { useReducedMotion } from "./motion.js";
+function useDrill(data, sort = true, onFocusChange) {
+  const root = useMemo(() => buildHierarchy(data, { sort }), [data, sort]);
+  const [focusId, setFocusId] = useState(root.id);
+  const focus = findNode(root, focusId) ?? root;
+  const path = useMemo(() => ancestors(focus), [focus]);
+  const change = (node) => {
+    setFocusId(node.id);
+    onFocusChange?.(node);
+  };
+  return {
+    root,
+    focus,
+    path,
+    drill: (id) => {
+      const node = findNode(root, id);
+      if (node && node.children.length > 0 && node.id !== focus.id) change(node);
+    },
+    up: () => {
+      if (!focus.parent) return false;
+      change(focus.parent);
+      return true;
+    }
+  };
+}
+function easeOutCubic(t) {
+  return 1 - (1 - t) ** 3;
+}
+function useAnimatedView(target, { disabled = false, duration = 650 } = {}) {
+  const reduced = useReducedMotion();
+  const [view, setView] = useState(target);
+  const current = useRef(target);
+  const { x0, x1, depth } = target;
+  useEffect(() => {
+    const to = { x0, x1, depth };
+    const from = current.current;
+    if (disabled || reduced || typeof requestAnimationFrame !== "function") {
+      current.current = to;
+      setView(to);
+      return;
+    }
+    let frame = 0;
+    const start = performance.now();
+    const step = (now) => {
+      const t = Math.min(1, (now - start) / duration);
+      const next = interpolateView(from, to, easeOutCubic(t));
+      current.current = next;
+      setView(next);
+      if (t < 1) frame = requestAnimationFrame(step);
+    };
+    frame = requestAnimationFrame(step);
+    return () => cancelAnimationFrame(frame);
+  }, [x0, x1, depth, disabled, reduced, duration]);
+  return view;
+}
+export {
+  useAnimatedView,
+  useDrill
+};

package/dist/charts/core/use-index-navigation.d.ts

@@ -0,0 +1,30 @@
+import { type KeyboardEvent } from "react";
+export interface IndexNavigationOptions {
+    /** Arrow keys wrap around the ends (circular charts). */
+    wrap?: boolean;
+}
+/**
+ * Active-item state for charts made of discrete items (slices, axes, stages).
+ * One source of truth for pointer hover and keyboard focus, so the tooltip,
+ * the highlight and `aria-valuetext` always agree. `ref` goes on the
+ * positioned container: `hover` stores the pointer relative to it.
+ */
+export declare function useIndexNavigation<T extends HTMLElement = HTMLDivElement>(count: number, { wrap }?: IndexNavigationOptions): {
+    ref: import("react").RefObject<T | null>;
+    active: number | null;
+    pointer: {
+        x: number;
+        y: number;
+    } | null;
+    setActive: import("react").Dispatch<import("react").SetStateAction<number | null>>;
+    hover: (index: number, event: {
+        clientX: number;
+        clientY: number;
+    }) => void;
+    leave: () => void;
+    sliderProps: {
+        onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+        onFocus: () => void;
+        onBlur: () => void;
+    };
+};