@jcsoftdev/ui 0.0.0-stage → 0.1.1

package/src/charts/core/types.ts

@@ -0,0 +1,105 @@
+import type { ValueFormat } from "./format.js";
+import type { ChartTone } from "./palette.js";
+import type { ChartPattern } from "./patterns.js";
+
+/** A category or time stamp on the category axis. */
+export type XValue = string | number | Date;
+
+export interface ChartSeries {
+  /** Stable identity, used for keys and legend toggling. */
+  id: string;
+  /** Visible name in the legend, tooltip and data table. */
+  name: string;
+  /** One value per category; `null` leaves a gap. */
+  data: ReadonlyArray<number | null>;
+  /** CSS color, e.g. `var(--chart-cat-3)`. Defaults to the palette slot of the series. */
+  color?: string;
+  /** Dashed stroke (lines) or hatched look, e.g. for a forecast or last year. */
+  dashed?: boolean;
+  /** Overrides the chart `valueFormat` for this series. */
+  format?: ValueFormat;
+  /** Fills bars with an SVG pattern (stripes, dots, ...) in the series color, for color-blind friendly charts. */
+  pattern?: ChartPattern;
+}
+
+/** Visible strings. English defaults; pass Spanish (or any language) from the app. */
+export interface ChartLabels {
+  empty: string;
+  loading: string;
+  resetZoom: string;
+  total: string;
+  /** Accessible name of the keyboard-explorable plot. */
+  explore: string;
+  /** Accessible name of the brush (range selector). */
+  brush: string;
+  /** Header of the category column in the hidden data table. */
+  category: string;
+  /** Header of the value column in the hidden data table (single-series charts). */
+  value: string;
+  /** Header and tooltip label of a share of the total. */
+  share: string;
+}
+
+export const DEFAULT_LABELS: ChartLabels = {
+  empty: "No data to show",
+  loading: "Loading chart",
+  resetZoom: "Reset zoom",
+  total: "Total",
+  explore: "Data points. Use the arrow keys to move between them.",
+  brush: "Visible range",
+  category: "Category",
+  value: "Value",
+  share: "Share",
+};
+
+export function resolveLabels(labels?: Partial<ChartLabels>): ChartLabels {
+  return labels ? { ...DEFAULT_LABELS, ...labels } : DEFAULT_LABELS;
+}
+
+interface AnnotationBase {
+  label?: string;
+  /** Extra sentence shown in a tooltip when the pointer is near a `point` or `text` mark. */
+  tooltip?: string;
+  /** Color family, `neutral` by default. */
+  tone?: ChartTone;
+}
+
+/**
+ * Reference marks. `axis: "y"` is the value axis (a threshold such as a daily
+ * goal); `axis: "x"` is the category axis (a date or a category). In horizontal
+ * bar charts the value axis runs left to right, so "y" lines are drawn vertical.
+ */
+export type ChartAnnotation =
+  | (AnnotationBase & { type: "line"; axis: "y"; value: number; yAxis?: string })
+  | (AnnotationBase & {
+      type: "range";
+      axis: "y";
+      from: number;
+      to: number;
+      yAxis?: string;
+    })
+  | (AnnotationBase & { type: "line"; axis: "x"; value: XValue })
+  | (AnnotationBase & { type: "range"; axis: "x"; from: XValue; to: XValue })
+  /** Dot at a data coordinate (category `x`, value `y`) with an optional label pill. */
+  | (AnnotationBase & { type: "point"; x: XValue; y: number; yAxis?: string })
+  /** Free text anchored at a data coordinate. */
+  | (AnnotationBase & { type: "text"; x: XValue; y: number; yAxis?: string });
+
+export interface ValueAxisOptions {
+  /** Fixed lower bound; by default the data decides (bars and areas start at 0). */
+  min?: number;
+  /** Fixed upper bound. */
+  max?: number;
+  /** Approximate number of ticks; derived from the height by default. */
+  tickCount?: number;
+  /** Tick format; defaults to a short form of the chart `valueFormat`. */
+  format?: ValueFormat;
+  /** Short axis title drawn above the ticks, e.g. "S/" or "Citas". */
+  title?: string;
+  /** Logarithmic scale (line charts only, positive values). */
+  scale?: "linear" | "log";
+  /** Force zero into the domain (lines default to "auto": only when data sits near zero). */
+  zero?: boolean;
+  /** Flips the axis: values grow downwards (or to the left), bars hang from the top (or the right). */
+  reversed?: boolean;
+}

package/src/charts/core/unit-glyph.tsx

@@ -0,0 +1,102 @@
+import { memo } from "react";
+import { EASE_OUT } from "./motion.js";
+import type { ResolvedUnitShape } from "./unit-icons.js";
+
+export interface UnitGlyphProps {
+  shape: ResolvedUnitShape;
+  /** Top-left corner of the square cell, in pixels. */
+  x: number;
+  y: number;
+  /** Side of the square cell. */
+  size: number;
+  /** 0 to 1: how much of the unit is filled (the rest shows the track). */
+  fill: number;
+  color: string;
+  /** Draw the unfilled part in the track color. */
+  track?: boolean;
+  /** Unique id for the clip of a partial unit. */
+  clipId: string;
+  /** Partial units fill left to right ("right") or bottom to top ("up"). */
+  direction?: "right" | "up";
+}
+
+/**
+ * One icon of a unit chart, centered in a square cell. A partial unit draws
+ * the track silhouette and clips the colored copy, so 0.6 of a person is
+ * exactly 60% of its width. The outer group carries `data-unit` and a
+ * fill-box origin, so entry animations can scale it in place.
+ */
+export const UnitGlyph = memo(function UnitGlyph({
+  shape,
+  x,
+  y,
+  size,
+  fill,
+  color,
+  track = true,
+  clipId,
+  direction = "right",
+}: UnitGlyphProps) {
+  const scale = size / Math.max(shape.width, shape.height);
+  const dx = x + (size - shape.width * scale) / 2;
+  const dy = y + (size - shape.height * scale) / 2;
+  const amount = Math.min(1, Math.max(0, fill));
+  const partial = amount > 0 && amount < 1;
+  return (
+    <g data-unit="" style={{ transformBox: "fill-box", transformOrigin: "center" }}>
+      <g transform={`translate(${dx} ${dy}) scale(${scale})`}>
+        {partial ? (
+          <clipPath id={clipId}>
+            {direction === "up" ? (
+              <rect
+                x={0}
+                y={shape.height * (1 - amount)}
+                width={shape.width}
+                height={shape.height * amount}
+              />
+            ) : (
+              <rect x={0} y={0} width={shape.width * amount} height={shape.height} />
+            )}
+          </clipPath>
+        ) : null}
+        {track && amount < 1 ? (
+          <path d={shape.path} style={{ fill: "var(--track)", fillRule: shape.fillRule }} />
+        ) : null}
+        {amount > 0 ? (
+          <path
+            d={shape.path}
+            clipPath={partial ? `url(#${clipId})` : undefined}
+            style={{ fill: color, fillRule: shape.fillRule }}
+          />
+        ) : null}
+      </g>
+    </g>
+  );
+});
+
+/**
+ * Unit charts make their frame a named container, so the HTML around the
+ * drawing follows the chart width instead of the viewport.
+ */
+export const UNIT_FRAME_CLASS = "@container/units";
+
+/** Legend under the drawing in narrow containers, at its requested place from `@sm` up. */
+export const UNIT_LEGEND_CLASS = "order-last @sm/units:order-none";
+
+/**
+ * Pops every `[data-unit]` in document order: a short scale-and-fade with a
+ * stagger that keeps the whole sequence under about a second.
+ */
+export function popUnits(root: Element, { duration = 420, budget = 900 } = {}): void {
+  const units = root.querySelectorAll("[data-unit]");
+  const step = units.length > 1 ? Math.min(28, budget / units.length) : 0;
+  units.forEach((unit, index) => {
+    unit.animate(
+      [
+        { transform: "scale(0.3)", opacity: 0 },
+        { transform: "scale(1)", opacity: 1 },
+      ],
+      { duration, delay: index * step, easing: EASE_OUT, fill: "backwards" },
+    );
+  });
+}

package/src/charts/core/unit-icons.ts

@@ -0,0 +1,210 @@
+/**
+ * Built-in silhouettes for unit charts, drawn on a 24 x 24 grid as solid
+ * shapes (so a partial unit can be clipped). Any SVG path can be used instead:
+ * pass the `d` string (24 x 24 box assumed) or a `UnitShape` with its own box.
+ */
+
+export interface UnitShape {
+  /** SVG path data. */
+  path: string;
+  /** Size of the drawing box; 24 x 24 by default. */
+  width?: number;
+  height?: number;
+  fillRule?: "nonzero" | "evenodd";
+  /** Optional stroked detail drawn over the shape (e.g. the rings of a target). */
+  detail?: string;
+  /** Direction a fill-gauge liquid rises: "up" (default) or "right" (a battery). */
+  fill?: "up" | "right";
+  /** Vertical position of a fill-gauge label in shape units; the middle by default. */
+  labelY?: number;
+}
+
+export interface ResolvedUnitShape {
+  path: string;
+  width: number;
+  height: number;
+  fillRule: "nonzero" | "evenodd";
+  detail?: string;
+  fill: "up" | "right";
+  labelY: number;
+}
+
+function starPath(cx: number, cy: number, outer: number, inner: number, points = 5): string {
+  const commands: string[] = [];
+  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";
+
+export 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",
+  },
+} as const satisfies Record<string, UnitShape>;
+
+export type UnitIconName = keyof typeof UNIT_ICONS;
+
+/** Human figures and everyday silhouettes for pictograms, in gallery order. */
+export const PICTOGRAM_SILHOUETTES = [
+  "person",
+  "woman",
+  "child",
+  "heart",
+  "tree",
+  "house",
+  "car",
+  "star",
+  "drop",
+  "clock",
+  "pin",
+] as const satisfies readonly UnitIconName[];
+
+/** Barbershop silhouettes drawn for this library. */
+export const BARBER_SILHOUETTES = [
+  "scissors",
+  "comb",
+  "mustache",
+  "pole",
+  "chair",
+  "bottle",
+] as const satisfies readonly UnitIconName[];
+
+/** A built-in name, a raw path (24 x 24 box) or a full shape definition. */
+export type UnitIcon = UnitIconName | UnitShape | (string & {});
+
+export function isUnitIconName(value: unknown): value is UnitIconName {
+  return typeof value === "string" && Object.hasOwn(UNIT_ICONS, value);
+}
+
+export function resolveUnitShape(icon: UnitIcon): ResolvedUnitShape {
+  const shape: UnitShape = 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,
+  };
+}
+
+/** A category of a unit chart: one color, optionally its own icon. */
+export interface UnitCategory {
+  id: string;
+  name: string;
+  value: number;
+  /** CSS color; the palette slot of the category by default. */
+  color?: string;
+  /** Icon of this category; the chart `icon` by default. */
+  icon?: UnitIcon;
+}

package/src/charts/core/units.ts

@@ -0,0 +1,267 @@
+/**
+ * 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.
+ */
+
+const EPSILON = 1e-9;
+
+/** Drops floating point noise (0.6000000000000001 -> 0.6). */
+function clean(value: number): number {
+  return Math.round(value * 1e9) / 1e9;
+}
+
+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 function unitCount(value: number, perUnit = 1): UnitCount {
+  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) };
+}
+
+/** Fill of every unit a value takes: `unitFractions(23, 5)` -> `[1, 1, 1, 1, 0.6]`. */
+export function unitFractions(value: number, perUnit = 1): number[] {
+  const { full, partial } = unitCount(value, perUnit);
+  const fractions: number[] = Array.from({ length: full }, () => 1);
+  if (partial > 0) fractions.push(partial);
+  return fractions;
+}
+
+/** Rounds to the nearest multiple of `step` (e.g. 0.5 for half stars). No step, no rounding. */
+export function roundToStep(value: number, step?: number): number {
+  if (!step || !(step > 0)) return value;
+  return clean(Math.round(value / step) * step);
+}
+
+/**
+ * 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 function progressFractions(value: number, max: number, count: number, step?: number) {
+  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))),
+  );
+}
+
+/**
+ * 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 function largestRemainder(weights: readonly number[], total: number): number[] {
+  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] as number) }))
+    .filter((entry) => (safe[entry.index] as number) > 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] as { index: number };
+    counts[entry.index] = (counts[entry.index] as number) + 1;
+  }
+  return counts;
+}
+
+/**
+ * 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 function waffleCounts(values: readonly number[], cells: number, total?: number): number[] {
+  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);
+}
+
+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 function gridCell(
+  index: number,
+  columns: number,
+  rows: number,
+  order: GridOrder = "row",
+): { row: number; column: number } {
+  if (order === "column") {
+    return { column: Math.floor(index / rows), row: rows - 1 - (index % rows) };
+  }
+  return { row: Math.floor(index / columns), column: index % columns };
+}
+
+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;
+}
+
+/** Side of a unit when `columns` x `rows` units (with gaps) must fit in the box. */
+function sideFor(width: number, height: number, columns: number, rows: number, gap: number) {
+  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));
+}
+
+/**
+ * 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 function fitUnitGrid({
+  width,
+  height,
+  gap = 0.2,
+  maxSize = Number.POSITIVE_INFINITY,
+  maxColumns,
+  rowsFor,
+  columns: fixed,
+}: UnitGridOptions): UnitGridFit {
+  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: UnitGridFit = { 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;
+}
+
+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[];
+}
+
+function rowRadii(rows: number, inner: number): number[] {
+  if (rows <= 1) return [1];
+  return Array.from({ length: rows }, (_, row) => inner + ((1 - inner) * row) / (rows - 1));
+}
+
+/** Seats that fit in `rows` arcs when neighbours keep the radial row spacing. */
+function arcCapacity(rows: number, inner: number): number {
+  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,
+  );
+}
+
+/** Fewest arcs that hold `seats` without crowding. */
+export function parliamentRows(seats: number, innerRatio = 0.4): number {
+  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;
+}
+
+/**
+ * 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 function parliamentLayout(
+  total: number,
+  { rows: fixedRows, innerRatio = 0.4 }: { rows?: number; innerRatio?: number } = {},
+): ParliamentLayout {
+  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: Seat[] = [];
+  let spacing = rows > 1 ? (1 - inner) / (rows - 1) : Number.POSITIVE_INFINITY;
+  perRow.forEach((count, row) => {
+    const radius = radii[row] as number;
+    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 };
+}
+
+/** Category of each position when `counts` are laid one after the other. */
+export function assignUnits(counts: readonly number[]): number[] {
+  const owners: number[] = [];
+  counts.forEach((count, category) => {
+    for (let i = 0; i < count; i += 1) owners.push(category);
+  });
+  return owners;
+}