@macrostrat/column-views 3.11.0 → 3.12.0

package/src/section.ts

@@ -3,14 +3,23 @@ import {
   LabelTrackerProvider,
   SectionLabelsColumn,
 } from "./units";
-import { ReactNode, FunctionComponent, useMemo } from "react";
+import {
+  type CSSProperties,
+  ReactNode,
+  FunctionComponent,
+  useMemo,
+} from "react";
 import {
   Timescale,
   TimescaleOrientation,
-  TimescaleClickHandler,
-  useMacrostratIntervals,
+  useMacrostratTimescales,
+  type Interval,
   type IntervalStyleBuilder,
+  type TimescaleClickData,
 } from "@macrostrat/timescale";
+
+/** Macrostrat's international timescale, the default for a column */
+const INTERNATIONAL_TIMESCALE_ID = 11;
 import { ColumnAxisType, SVG } from "@macrostrat/column-components";
 import hyper from "@macrostrat/hyper";
 import styles from "./column.module.sass";
@@ -19,10 +28,6 @@ import {
   useMacrostratUnits,
   MacrostratColumnProvider,
 } from "./data-provider";
-import {
-  useMacrostratBaseURL,
-  useMacrostratData,
-} from "@macrostrat/data-provider";
 import { Duration } from "./unit-details";
 import { Value } from "@macrostrat/data-components";
 import type { ExtUnit, PackageScaleLayoutData } from "./prepare-units/types";
@@ -37,6 +42,8 @@ export interface SectionSharedProps {
   columnWidth?: number;
   children?: ReactNode;
   showLabelColumn?: boolean;
+  /** Suppress the label for a unit drawn thinner than this many pixels */
+  labelSuppressHeight?: number;
   axisType?: ColumnAxisType;
   className?: string;
   clipUnits?: boolean;
@@ -63,6 +70,7 @@ export function SectionsColumn(props: SectionSharedProps) {
     showLabelColumn = true,
     clipUnits = true,
     maxInternalColumns,
+    labelSuppressHeight,
   } = props;
 
   const units = useMacrostratUnits();
@@ -82,6 +90,7 @@ export function SectionsColumn(props: SectionSharedProps) {
     }),
     h.if(showLabelColumn)(SectionLabelsColumn, {
       width: width - columnWidth,
+      labelSuppressHeight,
     }),
   ]);
 }
@@ -98,7 +107,8 @@ function SectionUnitsColumn(props: SectionSharedProps) {
     unconformityLabels = true,
   } = props;
 
-  const { sections, totalHeight } = useMacrostratColumnData();
+  const { sections, totalHeight, axisType: columnAxisType } =
+    useMacrostratColumnData();
 
   const scaleData: PackageScaleLayoutData[] = sections.map((section) => {
     return section.scaleInfo;
@@ -138,6 +148,9 @@ function SectionUnitsColumn(props: SectionSharedProps) {
     h.if(unconformityLabels)(UnconformityLabels, {
       width,
       sections: scaleData,
+      // A gap between sections is measured in whatever the axis is: metres
+      // down a core, Myr across a time column
+      axisType: axisType ?? columnAxisType,
       verbose: false,
     }),
   ]);
@@ -201,12 +214,77 @@ function SectionUnits(props: SectionProps) {
   );
 }
 
+/** A per-interval style that also knows which timescale the interval was
+ * drawn from. The same interval often appears in several of the timescales
+ * beside each other, and they aren't interchangeable — only one of them is
+ * the one a selection was made in. */
+export type ColumnIntervalStyleBuilder =
+  | CSSProperties
+  | ((interval: Interval, timescaleID: number) => CSSProperties)
+  | null;
+
+/** A timescale click, reporting which timescale was clicked in */
+export type ColumnTimescaleClickHandler = (
+  event: Event,
+  data: TimescaleClickData & { timescaleID: number },
+) => void;
+
+/** A timescale to draw beside a column.
+ *
+ * The international timescale is one of these, not a special case: it is the
+ * one that happens to be nested several levels deep. Anything with the same
+ * shape can take its place or sit beside it — a regional set from the API, a
+ * zonation assembled locally, or a hierarchy that isn't a timescale at all,
+ * so long as its "intervals" carry ages.
+ */
+export interface ColumnTimescale {
+  /** Integer identifier. Clicks and per-interval styles report it, so a
+   * consumer can tell one column's copy of an interval from another's. For a
+   * Macrostrat timescale it is the `timescale_id`. */
+  id: number;
+  /** Shown above the column, unless `label` says otherwise */
+  name?: string;
+  /** The intervals themselves, flat or already nested by `pid`. Left out,
+   * the timescale `id` is fetched from the Macrostrat API. */
+  intervals?: Interval[];
+  /** Levels to draw, and so how many slots wide the column is (default
+   * `[1, 1]`: one level, which is what a flat timescale has) */
+  levels?: [number, number];
+  /** `oid` of the interval the tree hangs from (default 0) */
+  rootInterval?: number;
+  /** Drawn above the column in place of the name — any node, so a consumer
+   * can put a control or a legend there instead of text */
+  label?: ReactNode;
+}
+
+export type ColumnTimescaleLike = number | ColumnTimescale;
+
 interface CompositeTimescaleProps {
+  /** Every timescale to draw, in order. A bare number is a Macrostrat
+   * timescale to fetch and draw as a single level.
+   *
+   * Given this, `levels`, `timescaleID` and `additionalTimescales` are
+   * ignored: it says what they say and more. */
+  timescales?: ColumnTimescaleLike[];
+  /** Levels of the ICS hierarchy to show. If a number, the finest level is
+   * `levels[0]`, the second-finest is `levels[1]`, etc. If an array, the
+   * first element is the starting level, the second is the ending level. */
   levels?: [number, number] | number;
   unconformityLabels?: boolean;
-  onClickInterval?: TimescaleClickHandler;
+  onClickInterval?: ColumnTimescaleClickHandler;
   /** Per-interval style (e.g. to highlight the currently selected interval). */
-  intervalStyle?: IntervalStyleBuilder;
+  intervalStyle?: ColumnIntervalStyleBuilder;
+  /** The timescale to draw. Defaults to the international one; any other
+   * Macrostrat timescale (a regional or project-specific set of intervals)
+   * can be drawn in its place. */
+  timescaleID?: number;
+  /** Further timescales drawn as extra level columns beside the main one,
+   * against the same scale. Shorthand for listing them in `timescales`. */
+  additionalTimescales?: number[];
+  /** Draw the names above the columns. They sit above the column proper, so
+   * leave top padding for them. */
+  showLabels?: boolean;
+  className?: string;
 }
 
 export function CompositeTimescale(props: CompositeTimescaleProps) {
@@ -223,53 +301,85 @@ export function CompositeTimescale(props: CompositeTimescaleProps) {
 
 type CompositeTimescaleCoreProps = CompositeTimescaleProps & {
   packages: PackageScaleLayoutData[];
-  onClickInterval?: TimescaleClickHandler;
 };
 
+/** What is drawn above a timescale: its name, reading up the page, or
+ * whatever node the consumer gave instead. */
+function TimescaleLabel({ timescale }: { timescale: ColumnTimescale }) {
+  const { label, name } = timescale;
+  const style = levelCountStyle(levelCount(timescale));
+
+  let content: ReactNode = label;
+  if (label == null && name != null) {
+    content = h("span.timescale-label-text", name);
+  }
+  if (content == null) return h("div.timescale-label", { style });
+
+  return h("div.timescale-label", { style }, content);
+}
+
+/** How wide a timescale draws: one slot per level it shows. */
+function levelCountStyle(levelCount: number): CSSProperties {
+  return { "--timescale-level-count": levelCount } as CSSProperties;
+}
+
 export function CompositeTimescaleCore(props: CompositeTimescaleCoreProps) {
   const {
-    levels = 3,
     packages,
     unconformityLabels = false,
     onClickInterval,
     intervalStyle,
+    showLabels = false,
+    className,
   } = props;
 
-  // Use intervals from Macrostrat API
-  const baseURL = useMacrostratBaseURL();
-  const intervals = useMacrostratIntervals({ baseURL });
-
-  let _levels: [number, number];
-  if (typeof levels === "number") {
-    // If levels is a number, use the most common starting level
-    _levels = [2, Math.max(2 + Math.min(levels, 5) - 1, 1)];
-  } else {
-    _levels = levels;
+  const timescales = useColumnTimescales(props);
+
+  /** Clicks and styles carry the timescale they came from, so a consumer can
+   * tell one column's copy of an interval from another's. */
+  function forTimescale(id: number) {
+    let onClick = null;
+    if (onClickInterval != null) {
+      onClick = (event: Event, data: TimescaleClickData) => {
+        onClickInterval(event, { ...data, timescaleID: id });
+      };
+    }
+    let style = intervalStyle as IntervalStyleBuilder;
+    if (typeof intervalStyle === "function") {
+      style = (interval: Interval) => intervalStyle(interval, id);
+    }
+    return { onClick, intervalStyle: style };
   }
 
-  const nCols = _levels[1] - _levels[0] + 1;
-
-  return h("div.timescale-column", [
+  return h("div.timescale-column", { className }, [
+    h.if(showLabels)(
+      "div.timescale-labels",
+      timescales.map((timescale) =>
+        h(TimescaleLabel, { key: timescale.id, timescale }),
+      ),
+    ),
     h(
       "div.timescales",
       packages.map((group) => {
         const { pixelHeight, paddingTop, key, scale } = group;
         return h(
-          "div.timescale-container",
-          { style: { paddingTop, "--timescale-level-count": nCols }, key },
-          [
+          "div.section-timescales",
+          { style: { paddingTop }, key },
+          timescales.map((timescale) =>
             h(Timescale, {
+              key: timescale.id,
               orientation: TimescaleOrientation.VERTICAL,
               length: pixelHeight,
-              levels: _levels,
+              levels: timescale.levels,
+              rootInterval: timescale.rootInterval,
               absoluteAgeScale: true,
               showAgeAxis: false,
               scale,
-              intervals,
-              onClick: onClickInterval,
-              intervalStyle,
+              intervals: timescale.intervals,
+              style: levelCountStyle(levelCount(timescale)),
+              ...forTimescale(timescale.id),
             }),
-          ],
+          ),
         );
       }),
     ),
@@ -282,6 +392,82 @@ export function CompositeTimescaleCore(props: CompositeTimescaleCoreProps) {
   ]);
 }
 
+/** The timescales to draw, with their intervals.
+ *
+ * Every timescale a column draws is fetched in one place: a column is split
+ * into sections, and fetching per section would ask for the same timescale
+ * once per section per timescale.
+ */
+function useColumnTimescales(props: CompositeTimescaleProps): ColumnTimescale[] {
+  const { timescales, levels = 3, timescaleID, additionalTimescales } = props;
+
+  const specs = useMemo(
+    () => timescaleSpecs({ timescales, levels, timescaleID, additionalTimescales }),
+    [
+      timescales,
+      levels,
+      timescaleID,
+      additionalTimescales?.join(","),
+    ],
+  );
+
+  // Only the ones that didn't come with their own intervals need fetching
+  const fetchIDs = useMemo(
+    () => specs.filter((d) => d.intervals == null).map((d) => d.id),
+    [specs],
+  );
+  const intervalSets = useMacrostratTimescales(fetchIDs);
+
+  return useMemo(
+    () =>
+      specs.map((spec) => ({
+        ...spec,
+        intervals: spec.intervals ?? intervalSets.get(spec.id) ?? [],
+      })),
+    [specs, intervalSets],
+  );
+}
+
+/** The `timescales` list, or one built from the older props that name the
+ * leveled timescale and the flat ones beside it. */
+function timescaleSpecs(props: CompositeTimescaleProps): ColumnTimescale[] {
+  const { timescales, levels = 3, timescaleID, additionalTimescales = [] } = props;
+
+  if (timescales != null) {
+    return timescales.map(normalizeTimescale);
+  }
+
+  return [
+    {
+      id: timescaleID ?? INTERNATIONAL_TIMESCALE_ID,
+      levels: levelRange(levels),
+    },
+    ...additionalTimescales.map(normalizeTimescale),
+  ];
+}
+
+function normalizeTimescale(timescale: ColumnTimescaleLike): ColumnTimescale {
+  if (typeof timescale === "number") {
+    return { id: timescale, levels: FLAT_TIMESCALE_LEVELS };
+  }
+  return { levels: FLAT_TIMESCALE_LEVELS, ...timescale };
+}
+
+/** Regional and project timescales come back flat: one level of intervals. */
+const FLAT_TIMESCALE_LEVELS: [number, number] = [1, 1];
+
+function levelRange(levels: [number, number] | number): [number, number] {
+  if (typeof levels !== "number") return levels;
+  // A count, rather than a range: start at the level most columns start at
+  return [2, Math.max(2 + Math.min(levels, 5) - 1, 1)];
+}
+
+/** How many slots wide a timescale draws: one per level it shows. */
+function levelCount(timescale: ColumnTimescale): number {
+  const [min, max] = timescale.levels ?? FLAT_TIMESCALE_LEVELS;
+  return Math.max(max - min + 1, 1);
+}
+
 export function UnconformityLabels(props: {
   width: string | number;
   sections: PackageScaleLayoutData[];

package/src/timescale-zoom.ts

@@ -0,0 +1,341 @@
+/** Click-to-zoom navigation over geologic time.
+ *
+ * `useTimescaleZoom` turns clicks on a column's timescale into an animated
+ * age window: clicking an interval zooms to it, clicking the interval you are
+ * already in zooms back out a level, and the timescale shows a sliding window
+ * of levels that follows the selection, so finer intervals come into reach as
+ * you drill. The result spreads straight onto a `Column`.
+ */
+import { type CSSProperties, useCallback, useMemo, useState } from "react";
+import type {
+  Interval,
+  IntervalStyleBuilder,
+  TimescaleClickData,
+  TimescaleClickHandler,
+} from "@macrostrat/timescale";
+import { type AgeWindow, useAnimatedAgeWindow } from "./animated-age-window";
+
+/** Coarsest level worth showing; level 0 is "all of geologic time" */
+const MIN_TIMESCALE_LEVEL = 1;
+/** Deepest level in the timescale (age/stage) */
+const MAX_TIMESCALE_LEVEL = 5;
+/** How many levels are shown at once */
+const LEVEL_WINDOW = 3;
+/** The level anchored on before an interval is picked. 3 (period) puts the
+ * starting window at era–epoch, the levels a `Column` shows by default. */
+const DEFAULT_LEVEL = 3;
+
+const SELECTED_INTERVAL_STYLE: CSSProperties = { fontWeight: "bold" };
+
+export interface UseTimescaleZoomOptions {
+  /** The full data extent — the window zooming returns to. `null` until the
+   * data (and hence the extent) is known. */
+  fullExtent: AgeWindow | null;
+  /** When false the hook reports no window and no column props, so a view can
+   * offer zooming as an option without changing hook order (default `true`). */
+  enabled?: boolean;
+  /** How many timescale levels to show at once (default 3) */
+  levelWindow?: number;
+  /** The level to anchor the window on before an interval is picked
+   * (default 3, period) */
+  defaultLevel?: number;
+  minLevel?: number;
+  maxLevel?: number;
+  /** Animation duration in ms */
+  duration?: number;
+  /** Style for the selected interval — the one whose click zooms out
+   * (default bold) */
+  selectedIntervalStyle?: CSSProperties;
+}
+
+/** Timescale and age-window props, ready to spread onto a `Column`. */
+export interface TimescaleZoomColumnProps {
+  showTimescale?: boolean;
+  timescaleLevels?: [number, number];
+  timescaleIntervalStyle?: IntervalStyleBuilder;
+  onClickTimescaleInterval?: TimescaleClickHandler;
+  t_age?: number;
+  b_age?: number;
+  isTransitioning?: boolean;
+}
+
+export interface TimescaleZoom {
+  enabled: boolean;
+  /** The rendered age window — `null` when disabled or before the extent is
+   * known */
+  window: AgeWindow | null;
+  /** The drill path: coarse to fine, the last entry being the selection */
+  intervals: Interval[];
+  selectedInterval: Interval | null;
+  /** The timescale the selection was made in, when the click said so */
+  selectedTimescaleID: number | null;
+  /** Every interval in the selection: the one drilled to, plus any added by
+   * shift-clicking. The window spans all of them. */
+  selectedIntervals: Interval[];
+  /** The levels the timescale should show, following the selection */
+  timescaleLevels: [number, number];
+  isFullExtent: boolean;
+  isAnimating: boolean;
+  /** Return to the full extent, clearing the drill path */
+  reset(): void;
+  zoomToInterval(interval: Interval): void;
+  onClickTimescaleInterval: TimescaleClickHandler;
+  timescaleIntervalStyle: (interval: Interval) => CSSProperties;
+  columnProps: TimescaleZoomColumnProps;
+}
+
+export function useTimescaleZoom(
+  options: UseTimescaleZoomOptions,
+): TimescaleZoom {
+  const {
+    fullExtent,
+    enabled = true,
+    levelWindow = LEVEL_WINDOW,
+    defaultLevel = DEFAULT_LEVEL,
+    minLevel = MIN_TIMESCALE_LEVEL,
+    maxLevel = MAX_TIMESCALE_LEVEL,
+    duration,
+    selectedIntervalStyle = SELECTED_INTERVAL_STYLE,
+  } = options;
+
+  const anim = useAnimatedAgeWindow({ fullExtent, duration });
+
+  // The intervals drilled through; the last one is the current selection
+  const [intervals, setIntervals] = useState<Interval[]>([]);
+  // Intervals shift-clicked into the selection alongside it
+  const [addedIntervals, setAddedIntervals] = useState<Interval[]>([]);
+  // Which timescale the selection was made in. The same interval is drawn in
+  // every timescale that contains it, and those copies are not the same
+  // selection: clicking one in another column moves the selection there.
+  const [selectedTimescaleID, setSelectedTimescaleID] = useState<number | null>(
+    null,
+  );
+  const selectedInterval = intervals[intervals.length - 1] ?? null;
+
+  const selectedIntervals = useMemo(() => {
+    if (selectedInterval == null) return addedIntervals;
+    return [selectedInterval, ...addedIntervals];
+  }, [selectedInterval, addedIntervals]);
+
+  const reset = useCallback(() => {
+    setIntervals([]);
+    setAddedIntervals([]);
+    setSelectedTimescaleID(null);
+    anim.reset();
+  }, [anim.reset]);
+
+  /** Take the interval clicked into (or out of) the selection, and span the
+   * result — how you widen a window to the interval next door. */
+  const extendToInterval = useCallback(
+    (interval: Interval) => {
+      let added = addedIntervals.filter((d) => d.oid !== interval.oid);
+      const wasSelected = added.length !== addedIntervals.length;
+      if (!wasSelected && interval.oid !== selectedInterval?.oid) {
+        added = [...addedIntervals, interval];
+      }
+      setAddedIntervals(added);
+
+      let selection = added;
+      if (selectedInterval != null) {
+        selection = [selectedInterval, ...added];
+      }
+      if (selection.length === 0) {
+        anim.reset();
+        return;
+      }
+      anim.zoomToWindow(intervalsWindow(selection));
+    },
+    [addedIntervals, selectedInterval, anim.zoomToWindow, anim.reset],
+  );
+
+  const zoomToInterval = useCallback(
+    (interval: Interval, timescaleID: number | null = null) => {
+      // Keep only the coarser intervals that actually contain this one, so
+      // stepping sideways into a different parent (the last stage of the
+      // Cambrian → the first of the Ordovician) doesn't strand the old one
+      const containing = intervals.filter(
+        (d) =>
+          d.lvl < interval.lvl &&
+          d.eag >= interval.eag &&
+          d.lag <= interval.lag,
+      );
+      setIntervals([...containing, interval]);
+      setAddedIntervals([]);
+      setSelectedTimescaleID(timescaleID);
+      anim.zoomToInterval(interval);
+    },
+    [intervals, anim.zoomToInterval],
+  );
+
+  const onClickTimescaleInterval = useCallback<TimescaleClickHandler>(
+    (event: Event, data: TimescaleClickData & { timescaleID?: number }) => {
+      const interval = data?.interval;
+      if (interval == null || interval.lvl == null) return;
+
+      const timescaleID = data.timescaleID ?? null;
+      // A click in a different timescale is a different selection, even on the
+      // same interval: it moves to that column rather than zooming back out
+      const sameTimescale =
+        timescaleID == null ||
+        selectedTimescaleID == null ||
+        timescaleID === selectedTimescaleID;
+
+      // Shift-click widens the window instead of moving it, so a selection can
+      // grow into the interval next door
+      if ((event as MouseEvent)?.shiftKey) {
+        extendToInterval(interval);
+        return;
+      }
+
+      // Clicking the interval you are in is the way back out: pop a level, or
+      // return to the full extent past the root
+      if (interval.oid === selectedInterval?.oid && addedIntervals.length === 0) {
+        const next = intervals.slice(0, -1);
+        setIntervals(next);
+        setSelectedTimescaleID(null);
+        const parent = next[next.length - 1] ?? null;
+        if (parent == null) {
+          anim.reset();
+        } else {
+          anim.zoomToInterval(parent);
+        }
+        return;
+      }
+
+      // Every other click navigates *to* the interval clicked, whatever its
+      // rank: a finer one drills in, a neighbor moves along the timescale, a
+      // coarser one zooms out to it
+      zoomToInterval(interval, timescaleID);
+    },
+    [
+      intervals,
+      selectedInterval,
+      selectedTimescaleID,
+      addedIntervals,
+      extendToInterval,
+      zoomToInterval,
+      anim.reset,
+    ],
+  );
+
+  const timescaleIntervalStyle = useCallback(
+    (interval: Interval): CSSProperties => {
+      if (selectedIntervals.some((d) => d.oid === interval.oid)) {
+        return selectedIntervalStyle;
+      }
+      return {};
+    },
+    [selectedIntervals, selectedIntervalStyle],
+  );
+
+  const levels = useMemo(() => {
+    let level = defaultLevel;
+    for (const interval of selectedIntervals) {
+      if (interval.lvl != null) level = Math.max(level, interval.lvl);
+    }
+    return levelsForSelected(level, { levelWindow, minLevel, maxLevel });
+  }, [selectedIntervals, defaultLevel, levelWindow, minLevel, maxLevel]);
+
+  if (!enabled) {
+    return {
+      ...disabledZoom,
+      selectedTimescaleID: null,
+      selectedIntervals: [],
+      timescaleLevels: levels,
+      reset,
+      zoomToInterval,
+      onClickTimescaleInterval,
+      timescaleIntervalStyle,
+    };
+  }
+
+  const window = anim.window ?? fullExtent;
+
+  return {
+    enabled: true,
+    window,
+    intervals,
+    selectedInterval,
+    selectedTimescaleID,
+    selectedIntervals,
+    timescaleLevels: levels,
+    isFullExtent: anim.isFullExtent,
+    isAnimating: anim.isAnimating,
+    reset,
+    zoomToInterval,
+    onClickTimescaleInterval,
+    timescaleIntervalStyle,
+    columnProps: {
+      showTimescale: true,
+      timescaleLevels: levels,
+      timescaleIntervalStyle,
+      onClickTimescaleInterval,
+      t_age: window?.t_age,
+      b_age: window?.b_age,
+      isTransitioning: anim.isAnimating,
+    },
+  };
+}
+
+/** What the hook reports when zooming is switched off: no window, and no
+ * props to change how the column renders. */
+const disabledZoom: Pick<
+  TimescaleZoom,
+  | "enabled"
+  | "window"
+  | "intervals"
+  | "selectedInterval"
+  | "isFullExtent"
+  | "isAnimating"
+  | "columnProps"
+> = {
+  enabled: false,
+  window: null,
+  intervals: [],
+  selectedInterval: null,
+  isFullExtent: true,
+  isAnimating: false,
+  columnProps: {},
+};
+
+interface LevelWindowOptions {
+  levelWindow: number;
+  minLevel: number;
+  maxLevel: number;
+}
+
+/** A fixed window of timescale levels that slides with the selected level —
+ * one coarser for context, the rest finer to drill into. Clamped so the
+ * useless level 0 is never shown. */
+export function levelsForSelected(
+  selectedLevel: number,
+  options: LevelWindowOptions,
+): [number, number] {
+  const { levelWindow, minLevel, maxLevel } = options;
+  const span = Math.max(levelWindow - 1, 0);
+  const lo = Math.min(
+    Math.max(selectedLevel - 1, minLevel),
+    Math.max(maxLevel - span, minLevel),
+  );
+  return [lo, lo + span];
+}
+
+/** The window spanning a set of intervals. */
+function intervalsWindow(intervals: Interval[]): AgeWindow {
+  return {
+    t_age: Math.min(...intervals.map((d) => d.lag)),
+    b_age: Math.max(...intervals.map((d) => d.eag)),
+  };
+}
+
+/** The age extent of a set of units, in the shape the age-window props take.
+ * `null` for an empty or absent set. */
+export function unitsAgeExtent(
+  units: { t_age: number; b_age: number }[] | null | undefined,
+): AgeWindow | null {
+  if (units == null || units.length === 0) return null;
+  return {
+    t_age: Math.min(...units.map((d) => d.t_age)),
+    b_age: Math.max(...units.map((d) => d.b_age)),
+  };
+}