@swiftbrowser/web 0.1.0

package/src/layout/chart.ts

@@ -0,0 +1,477 @@
+/**
+ * Phase 7 chart geometry (docs/ops-protocol.md, "Phase 7: charts").
+ *
+ * Pure functions, DOM-free: the engine feeds measured label sizes in and gets
+ * the plot rectangle, axis bands, legend rows and label rects back (all
+ * relative to the chart's origin); the DOM side maps unit coordinates onto
+ * the plot and builds SVG path data for lines, areas and symbols.
+ */
+
+import type { Rect, Size } from './types';
+
+// Constants from the spec.
+export const CHART_DEFAULT_WIDTH = 300;
+export const CHART_DEFAULT_HEIGHT = 200;
+/** Gap between an axis label and the plot edge (the ticks sit inside it). */
+export const CHART_AXIS_PAD = 6;
+export const CHART_TICK_LENGTH = 4;
+/** Legend glyph: a `symbolSize`-px symbol, or an 18 × 3 line when the item has no symbol. */
+export const CHART_LEGEND_GLYPH = 10;
+export const CHART_LEGEND_LINE: Size = { width: 18, height: 3 };
+/** Glyph → label gap inside a legend item. */
+export const CHART_LEGEND_GAP = 4;
+/** Horizontal distance between legend items (and vertical between wrapped rows). */
+export const CHART_LEGEND_ITEM_SPACING = 12;
+export const CHART_LEGEND_ROW_SPACING = 4;
+/** Gap between the legend and the axes / plot. */
+export const CHART_LEGEND_MARGIN = 8;
+
+export type ChartAxisPosition = 'bottom' | 'top' | 'leading' | 'trailing';
+export type ChartLegendPosition = 'top' | 'bottom' | 'leading' | 'trailing';
+export type ChartItemPosition = 'top' | 'bottom' | 'leading' | 'trailing' | 'overlay';
+
+export interface ChartAxisInput {
+  position: ChartAxisPosition;
+  /** Text labels: unit position and measured width (height is `labelHeight`). */
+  labels: { at: number; width: number }[];
+  /** Line height of the axis font. */
+  labelHeight: number;
+  /** View labels (`xLabel` / `yLabel` children) at their ideal size. */
+  views: { at: number; size: Size }[];
+}
+
+export interface ChartLegendInput {
+  position: ChartLegendPosition;
+  /** Measured width of each item (glyph + gap + label). */
+  itemWidths: number[];
+  itemHeight: number;
+}
+
+export interface ChartLayoutInput {
+  width: number;
+  height: number;
+  xAxis: ChartAxisInput | null;
+  yAxis: ChartAxisInput | null;
+  legend: ChartLegendInput | null;
+}
+
+/** Everything relative to the chart's origin. */
+export interface ChartGeometry {
+  plot: Rect;
+  legend: Rect | null;
+  xBand: Rect | null;
+  yBand: Rect | null;
+  xLabels: Rect[];
+  yLabels: Rect[];
+  xViews: Rect[];
+  yViews: Rect[];
+  legendItems: Rect[];
+}
+
+/**
+ * The chart's size for a proposal: the proposal on both axes, 300 × 200 for
+ * nil axes. An infinite axis stays infinite (the chart is as flexible as a
+ * shape); callers that need pixels pass `null` for it.
+ */
+export function chartSize(width: number | null, height: number | null): Size {
+  return {
+    width: width !== null && !Number.isNaN(width) ? Math.max(0, width) : CHART_DEFAULT_WIDTH,
+    height: height !== null && !Number.isNaN(height) ? Math.max(0, height) : CHART_DEFAULT_HEIGHT,
+  };
+}
+
+/** Thickness of an axis band: the largest label on its cross axis plus the pad, 0 without labels. */
+export function axisBandThickness(axis: ChartAxisInput | null, cross: 'width' | 'height'): number {
+  if (!axis) return 0;
+  let largest = 0;
+  let any = false;
+  for (const label of axis.labels) {
+    any = true;
+    largest = Math.max(largest, cross === 'width' ? label.width : axis.labelHeight);
+  }
+  for (const view of axis.views) {
+    any = true;
+    largest = Math.max(largest, view.size[cross]);
+  }
+  return any ? largest + CHART_AXIS_PAD : 0;
+}
+
+export interface LegendRows {
+  size: Size;
+  /** One rect per item, relative to the legend's origin. */
+  items: Rect[];
+}
+
+/**
+ * Flow legend items horizontally with 12 px between them, wrapping at
+ * `maxWidth` (one item per row when `column`), rows 4 px apart.
+ */
+export function legendRows(itemWidths: readonly number[], itemHeight: number, maxWidth: number, column = false): LegendRows {
+  const items: Rect[] = [];
+  let x = 0;
+  let y = 0;
+  let rowWidth = 0;
+  let widest = 0;
+  for (let i = 0; i < itemWidths.length; i++) {
+    const width = itemWidths[i] as number;
+    const wraps = column ? i > 0 : x > 0 && x + width > maxWidth;
+    if (wraps) {
+      widest = Math.max(widest, rowWidth);
+      x = 0;
+      y += itemHeight + CHART_LEGEND_ROW_SPACING;
+    }
+    items.push({ x, y, width, height: itemHeight });
+    x += width;
+    rowWidth = x;
+    x += CHART_LEGEND_ITEM_SPACING;
+  }
+  widest = Math.max(widest, rowWidth);
+  const height = itemWidths.length ? y + itemHeight : 0;
+  return { size: { width: widest, height }, items };
+}
+
+/**
+ * Split the chart's box into the legend (a row at the top / bottom or a
+ * column at the leading / trailing edge), the axis bands and the plot, and
+ * position every text and view label.
+ */
+export function layoutChart(input: ChartLayoutInput): ChartGeometry {
+  const { width, height, xAxis, yAxis } = input;
+  // 1. Legend.
+  let area: Rect = { x: 0, y: 0, width, height };
+  let legend: Rect | null = null;
+  let legendItems: Rect[] = [];
+  if (input.legend && input.legend.itemWidths.length) {
+    const { position, itemWidths, itemHeight } = input.legend;
+    const column = position === 'leading' || position === 'trailing';
+    const rows = legendRows(itemWidths, itemHeight, column ? Infinity : width, column);
+    if (column) {
+      const w = Math.min(rows.size.width, width);
+      const x = position === 'leading' ? 0 : width - w;
+      legend = { x, y: 0, width: w, height: Math.min(rows.size.height, height) };
+      const taken = w + CHART_LEGEND_MARGIN;
+      area = { x: position === 'leading' ? taken : 0, y: 0, width: Math.max(0, width - taken), height };
+    } else {
+      const h = Math.min(rows.size.height, height);
+      const y = position === 'top' ? 0 : height - h;
+      legend = { x: 0, y, width, height: h };
+      const taken = h + CHART_LEGEND_MARGIN;
+      area = { x: 0, y: position === 'top' ? taken : 0, width, height: Math.max(0, height - taken) };
+    }
+    legendItems = rows.items.map((r) => ({ x: legend!.x + r.x, y: legend!.y + r.y, width: r.width, height: r.height }));
+  }
+
+  // 2. Axis bands and the plot.
+  const xBandH = Math.min(axisBandThickness(xAxis, 'height'), area.height);
+  const yBandW = Math.min(axisBandThickness(yAxis, 'width'), area.width);
+  const xTop = xAxis?.position === 'top';
+  const yLeading = yAxis?.position === 'leading';
+  const plot: Rect = {
+    x: area.x + (yLeading ? yBandW : 0),
+    y: area.y + (xTop ? xBandH : 0),
+    width: Math.max(0, area.width - yBandW),
+    height: Math.max(0, area.height - xBandH),
+  };
+  const xBand: Rect | null = xAxis
+    ? { x: plot.x, y: xTop ? area.y : plot.y + plot.height, width: plot.width, height: xBandH }
+    : null;
+  const yBand: Rect | null = yAxis
+    ? { x: yLeading ? area.x : plot.x + plot.width, y: plot.y, width: yBandW, height: plot.height }
+    : null;
+
+  // 3. Labels.
+  const xLabels: Rect[] = [];
+  const xViews: Rect[] = [];
+  if (xAxis) {
+    const top = (h: number) => (xTop ? plot.y - CHART_AXIS_PAD - h : plot.y + plot.height + CHART_AXIS_PAD);
+    for (const label of xAxis.labels) {
+      const h = xAxis.labelHeight;
+      const x = clampTo(mapX(plot, label.at) - label.width / 2, label.width, 0, width);
+      xLabels.push({ x, y: top(h), width: label.width, height: h });
+    }
+    for (const view of xAxis.views) {
+      const { width: w, height: h } = view.size;
+      xViews.push({ x: mapX(plot, view.at) - w / 2, y: top(h), width: w, height: h });
+    }
+  }
+  const yLabels: Rect[] = [];
+  const yViews: Rect[] = [];
+  if (yAxis) {
+    const left = (w: number) => (yLeading ? plot.x - CHART_AXIS_PAD - w : plot.x + plot.width + CHART_AXIS_PAD);
+    for (const label of yAxis.labels) {
+      const h = yAxis.labelHeight;
+      const y = clampTo(mapY(plot, label.at) - h / 2, h, 0, height);
+      yLabels.push({ x: left(label.width), y, width: label.width, height: h });
+    }
+    for (const view of yAxis.views) {
+      const { width: w, height: h } = view.size;
+      yViews.push({ x: left(w), y: mapY(plot, view.at) - h / 2, width: w, height: h });
+    }
+  }
+
+  return { plot, legend, xBand, yBand, xLabels, yLabels, xViews, yViews, legendItems };
+}
+
+/** Keep `[start, start + length]` inside `[min, max]` when it fits (else pin it to `min`). */
+function clampTo(start: number, length: number, min: number, max: number): number {
+  if (length >= max - min) return min;
+  return Math.min(max - length, Math.max(min, start));
+}
+
+// ---------------------------------------------------------------------------
+// Unit → pixel mapping
+// ---------------------------------------------------------------------------
+
+export function mapX(plot: Rect, u: number): number {
+  return plot.x + fin(u) * plot.width;
+}
+
+/** `y` runs top → bottom like every box in the protocol. */
+export function mapY(plot: Rect, u: number): number {
+  return plot.y + fin(u) * plot.height;
+}
+
+/** The pixel rect of a unit rect (normalized so width/height are non-negative). */
+export function unitRect(plot: Rect, x0: number, x1: number, y0: number, y1: number): Rect {
+  const left = mapX(plot, Math.min(fin(x0), fin(x1)));
+  const right = mapX(plot, Math.max(fin(x0), fin(x1)));
+  const top = mapY(plot, Math.min(fin(y0), fin(y1)));
+  const bottom = mapY(plot, Math.max(fin(y0), fin(y1)));
+  return { x: left, y: top, width: right - left, height: bottom - top };
+}
+
+/** A `rect` mark's pixel rect: the unit rect, or `fixedWidth` px centered on the band. */
+export function rectMarkRect(
+  plot: Rect,
+  mark: { x0: number; x1: number; y0: number; y1: number; fixedWidth?: number | null },
+): Rect {
+  const r = unitRect(plot, mark.x0, mark.x1, mark.y0, mark.y1);
+  const fixed = mark.fixedWidth;
+  if (fixed != null && Number.isFinite(fixed) && fixed >= 0) {
+    return { x: r.x + (r.width - fixed) / 2, y: r.y, width: fixed, height: r.height };
+  }
+  return r;
+}
+
+// ---------------------------------------------------------------------------
+// Annotations
+// ---------------------------------------------------------------------------
+
+/** Unit anchors (0 leading/top, 0.5 center, 1 trailing/bottom) of an `Alignment`. */
+export function alignmentAnchors(alignment: string | null | undefined): [number, number] {
+  switch (alignment) {
+    case 'leading':
+      return [0, 0.5];
+    case 'trailing':
+      return [1, 0.5];
+    case 'top':
+      return [0.5, 0];
+    case 'bottom':
+      return [0.5, 1];
+    case 'topLeading':
+      return [0, 0];
+    case 'topTrailing':
+      return [1, 0];
+    case 'bottomLeading':
+      return [0, 1];
+    case 'bottomTrailing':
+      return [1, 1];
+    default:
+      return [0.5, 0.5];
+  }
+}
+
+/**
+ * Where an annotation of `size` goes against its mark's pixel rect `R`:
+ * `top` / `bottom` above / below it (`spacing` apart), `leading` / `trailing`
+ * beside it, `overlay` on it; `alignment` positions it along the free axis
+ * like a `ZStack` alignment would inside `R`.
+ */
+export function annotationFrame(
+  R: Rect,
+  size: Size,
+  position: ChartItemPosition,
+  alignment: string | null | undefined,
+  spacing: number,
+): Rect {
+  const [ax, ay] = alignmentAnchors(alignment);
+  const gap = fin(spacing);
+  const alongX = R.x + (R.width - size.width) * ax;
+  const alongY = R.y + (R.height - size.height) * ay;
+  switch (position) {
+    case 'top':
+      return { x: alongX, y: R.y - gap - size.height, ...size };
+    case 'bottom':
+      return { x: alongX, y: R.y + R.height + gap, ...size };
+    case 'leading':
+      return { x: R.x - gap - size.width, y: alongY, ...size };
+    case 'trailing':
+      return { x: R.x + R.width + gap, y: alongY, ...size };
+    default:
+      return { x: alongX, y: alongY, ...size };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export type Interpolation = 'linear' | 'cardinal' | 'catmullRom' | 'monotone' | 'stepStart' | 'stepCenter' | 'stepEnd';
+
+const n = (v: number): string => String(Math.round(fin(v) * 100) / 100);
+
+/**
+ * SVG path data through `points` with `interpolation`, starting with `M`
+ * (empty for no points). `cardinal`, `catmullRom` and `monotone` are all drawn
+ * as a uniform Catmull-Rom spline (one `C` per interval); the steps are
+ * right-angle paths.
+ */
+export function linePath(points: readonly Point[], interpolation: Interpolation | string | undefined): string {
+  if (points.length === 0) return '';
+  const [first, ...rest] = points as [Point, ...Point[]];
+  if (points.length === 1) return `M${n(first.x)} ${n(first.y)}`;
+  switch (interpolation) {
+    case 'cardinal':
+    case 'catmullRom':
+    case 'monotone':
+      return catmullRomPath(points);
+    case 'stepStart':
+    case 'stepCenter':
+    case 'stepEnd': {
+      let d = `M${n(first.x)} ${n(first.y)}`;
+      let prev = first;
+      for (const p of rest) {
+        if (interpolation === 'stepStart') d += `V${n(p.y)}H${n(p.x)}`;
+        else if (interpolation === 'stepEnd') d += `H${n(p.x)}V${n(p.y)}`;
+        else {
+          const mid = (prev.x + p.x) / 2;
+          d += `H${n(mid)}V${n(p.y)}H${n(p.x)}`;
+        }
+        prev = p;
+      }
+      return d;
+    }
+    default:
+      return `M${n(first.x)} ${n(first.y)}` + rest.map((p) => `L${n(p.x)} ${n(p.y)}`).join('');
+  }
+}
+
+/**
+ * Uniform Catmull-Rom spline through `points` as cubic Béziers: for the
+ * interval P1→P2 with neighbours P0 and P3 (clamped at the ends) the control
+ * points are P1 + (P2 − P0) / 6 and P2 − (P3 − P1) / 6.
+ */
+export function catmullRomPath(points: readonly Point[]): string {
+  if (points.length === 0) return '';
+  const first = points[0] as Point;
+  let d = `M${n(first.x)} ${n(first.y)}`;
+  for (let i = 0; i < points.length - 1; i++) {
+    const p0 = points[Math.max(0, i - 1)] as Point;
+    const p1 = points[i] as Point;
+    const p2 = points[i + 1] as Point;
+    const p3 = points[Math.min(points.length - 1, i + 2)] as Point;
+    const c1x = p1.x + (p2.x - p0.x) / 6;
+    const c1y = p1.y + (p2.y - p0.y) / 6;
+    const c2x = p2.x - (p3.x - p1.x) / 6;
+    const c2y = p2.y - (p3.y - p1.y) / 6;
+    d += `C${n(c1x)} ${n(c1y)} ${n(c2x)} ${n(c2y)} ${n(p2.x)} ${n(p2.y)}`;
+  }
+  return d;
+}
+
+/**
+ * A closed path between the upper curve (`y0`) and the lower curve (`y1`),
+ * both drawn with `interpolation`: the upper curve forward, then the lower
+ * one backward.
+ */
+export function areaPath(points: readonly { x: number; y0: number; y1: number }[], interpolation: Interpolation | string | undefined): string {
+  if (points.length === 0) return '';
+  const upper = points.map((p) => ({ x: p.x, y: p.y0 }));
+  const lower = points.map((p) => ({ x: p.x, y: p.y1 })).reverse();
+  const top = linePath(upper, interpolation);
+  // The lower curve continues from the upper one's end: drop its `M`. Walked
+  // backwards, a step that rises at the start rises at the end.
+  const reversed = interpolation === 'stepStart' ? 'stepEnd' : interpolation === 'stepEnd' ? 'stepStart' : interpolation;
+  const bottom = linePath(lower, reversed);
+  const start = lower[0] as Point;
+  return `${top}L${n(start.x)} ${n(start.y)}${bottom.replace(/^M[^A-Za-z]*/, '')}Z`;
+}
+
+// ---------------------------------------------------------------------------
+// Symbols
+// ---------------------------------------------------------------------------
+
+export type SymbolName = 'circle' | 'square' | 'triangle' | 'diamond' | 'cross' | 'plus' | 'asterisk';
+
+export interface SymbolPath {
+  d: string;
+  /** True for the line glyphs (`cross`, `plus`, `asterisk`): stroked with `strokeWidth`, not filled. */
+  stroked: boolean;
+  strokeWidth: number;
+}
+
+/** Path data for a `size`-px symbol glyph centered on (`cx`, `cy`). Unknown names draw a circle. */
+export function symbolPath(symbol: string | null | undefined, cx: number, cy: number, size: number): SymbolPath {
+  const r = Math.max(0, fin(size)) / 2;
+  const strokeWidth = Math.max(1, r / 3);
+  switch (symbol) {
+    case 'square':
+      return { d: `M${n(cx - r)} ${n(cy - r)}h${n(2 * r)}v${n(2 * r)}h${n(-2 * r)}Z`, stroked: false, strokeWidth };
+    case 'triangle': {
+      // Equilateral-ish: apex up, base at the bottom of the box.
+      const h = 2 * r;
+      return { d: `M${n(cx)} ${n(cy - r)}L${n(cx + r)} ${n(cy - r + h)}L${n(cx - r)} ${n(cy - r + h)}Z`, stroked: false, strokeWidth };
+    }
+    case 'diamond':
+      return {
+        d: `M${n(cx)} ${n(cy - r)}L${n(cx + r)} ${n(cy)}L${n(cx)} ${n(cy + r)}L${n(cx - r)} ${n(cy)}Z`,
+        stroked: false,
+        strokeWidth,
+      };
+    case 'cross': {
+      const k = r * Math.SQRT1_2;
+      return {
+        d: `M${n(cx - k)} ${n(cy - k)}L${n(cx + k)} ${n(cy + k)}M${n(cx + k)} ${n(cy - k)}L${n(cx - k)} ${n(cy + k)}`,
+        stroked: true,
+        strokeWidth,
+      };
+    }
+    case 'plus':
+      return {
+        d: `M${n(cx)} ${n(cy - r)}V${n(cy + r)}M${n(cx - r)} ${n(cy)}H${n(cx + r)}`,
+        stroked: true,
+        strokeWidth,
+      };
+    case 'asterisk': {
+      const k = r * Math.SQRT1_2;
+      return {
+        d:
+          `M${n(cx)} ${n(cy - r)}V${n(cy + r)}M${n(cx - r)} ${n(cy)}H${n(cx + r)}` +
+          `M${n(cx - k)} ${n(cy - k)}L${n(cx + k)} ${n(cy + k)}M${n(cx + k)} ${n(cy - k)}L${n(cx - k)} ${n(cy + k)}`,
+        stroked: true,
+        strokeWidth,
+      };
+    }
+    default:
+      // Two arcs make a full circle.
+      return {
+        d: `M${n(cx - r)} ${n(cy)}a${n(r)} ${n(r)} 0 1 0 ${n(2 * r)} 0a${n(r)} ${n(r)} 0 1 0 ${n(-2 * r)} 0Z`,
+        stroked: false,
+        strokeWidth,
+      };
+  }
+}
+
+/** The glyph box of a legend item: a `symbol` square or the 18 × 3 line. */
+export function legendGlyphSize(symbol: string | null | undefined): Size {
+  return symbol ? { width: CHART_LEGEND_GLYPH, height: CHART_LEGEND_GLYPH } : CHART_LEGEND_LINE;
+}
+
+export function fin(v: unknown): number {
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}

package/src/layout/controls.ts

@@ -0,0 +1,116 @@
+/**
+ * Phase 8 control helpers shared by the layout engine and the renderer
+ * (docs/ops-protocol.md, "Phase 8: interaction", Controls). Pure and DOM-free:
+ * slider value snapping and the US-English UTC formatting of a `datepicker`.
+ */
+
+// Slider
+// ---------------------------------------------------------------------------
+
+/** Decimal places of `step` (0.25 → 2), capped so float noise never leaks into the JSON. */
+function decimalsOf(step: number): number {
+  const text = String(step);
+  const exp = /e-(\d+)$/.exec(text);
+  if (exp) return Math.min(10, Number(exp[1]));
+  const dot = text.indexOf('.');
+  return dot < 0 ? 0 : Math.min(10, text.length - dot - 1);
+}
+
+/**
+ * The slider value for a thumb fraction (0 at `min`, 1 at `max`): snapped to
+ * the nearest multiple of `step` from `min` (when `step` is positive) and
+ * clamped to `min…max`. A degenerate range (`max <= min`) yields `min`.
+ */
+export function snapSliderValue(fraction: number, min: number, max: number, step: number | null): number {
+  if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) return Number.isFinite(min) ? min : 0;
+  const f = Number.isFinite(fraction) ? Math.min(1, Math.max(0, fraction)) : 0;
+  let value = min + f * (max - min);
+  if (step !== null && Number.isFinite(step) && step > 0) {
+    value = min + Math.round((value - min) / step) * step;
+    value = Number(value.toFixed(decimalsOf(step)));
+  } else {
+    value = Math.round(value * 1e6) / 1e6;
+  }
+  return Math.min(max, Math.max(min, value));
+}
+
+/** The thumb's position for `value`: 0 at `min`, 1 at `max`, clamped. */
+export function sliderFraction(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value) || !Number.isFinite(min) || !Number.isFinite(max) || max <= min) return 0;
+  return Math.min(1, Math.max(0, (value - min) / (max - min)));
+}
+
+// Date picker
+// ---------------------------------------------------------------------------
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+function dateOf(seconds: number): Date {
+  return new Date((Number.isFinite(seconds) ? seconds : 0) * 1000);
+}
+
+function pad2(n: number): string {
+  return n < 10 ? `0${n}` : String(n);
+}
+
+/** "Oct 3, 2026": the UTC date of `seconds` in the US English abbreviated form. */
+export function formatPickerDate(seconds: number): string {
+  const d = dateOf(seconds);
+  return `${MONTHS[d.getUTCMonth()]} ${d.getUTCDate()}, ${d.getUTCFullYear()}`;
+}
+
+/** "7:00 AM": the UTC time of `seconds` in the US English 12-hour form. */
+export function formatPickerTime(seconds: number): string {
+  const d = dateOf(seconds);
+  const hours = d.getUTCHours();
+  const period = hours < 12 ? 'AM' : 'PM';
+  const hour12 = hours % 12 === 0 ? 12 : hours % 12;
+  return `${hour12}:${pad2(d.getUTCMinutes())} ${period}`;
+}
+
+/** `yyyy-mm-dd` for a native `<input type="date">`, in UTC. */
+export function dateInputValue(seconds: number): string {
+  const d = dateOf(seconds);
+  return `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`;
+}
+
+/** `HH:MM` for a native `<input type="time">`, in UTC. */
+export function timeInputValue(seconds: number): string {
+  const d = dateOf(seconds);
+  return `${pad2(d.getUTCHours())}:${pad2(d.getUTCMinutes())}`;
+}
+
+/**
+ * Seconds (UTC) after a native input changed: the `date` (`yyyy-mm-dd`)
+ * replaces the day and keeps the time of day of `seconds`; the `time`
+ * (`HH:MM`) replaces the time of day and keeps the day. Seconds within the
+ * minute are dropped, like the pickers' minute granularity. An unparsable
+ * value leaves `seconds` as it was.
+ */
+export function combineDateSeconds(seconds: number, change: { date?: string; time?: string }): number {
+  const d = dateOf(seconds);
+  let year = d.getUTCFullYear();
+  let month = d.getUTCMonth();
+  let day = d.getUTCDate();
+  let hours = d.getUTCHours();
+  let minutes = d.getUTCMinutes();
+  if (change.date !== undefined) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(change.date);
+    if (!m) return seconds;
+    year = Number(m[1]);
+    month = Number(m[2]) - 1;
+    day = Number(m[3]);
+  }
+  if (change.time !== undefined) {
+    const m = /^(\d{2}):(\d{2})/.exec(change.time);
+    if (!m) return seconds;
+    hours = Number(m[1]);
+    minutes = Number(m[2]);
+  }
+  return Math.floor(Date.UTC(year, month, day, hours, minutes, 0) / 1000);
+}
+
+/** True when two instants fall on the same UTC day (a time input's `min`/`max` only apply then). */
+export function sameUTCDay(a: number, b: number): boolean {
+  return dateInputValue(a) === dateInputValue(b);
+}