@macrostrat/column-views 3.11.0 → 3.12.1

package/src/age-model/types.ts

@@ -0,0 +1,392 @@
+/** Surfaces: the view model for a column's age model.
+ *
+ * A `ColumnSurface` is one horizontal boundary in a column. It is what the
+ * surfaces view renders, and it is deliberately data-agnostic: a surface can
+ * come from an `/age_model` boundary (`boundaryToSurface`), be derived from
+ * unit tops and bottoms when a column has no age-model rows
+ * (`surfacesFromUnits`), or be built by an editor from its own state.
+ */
+import type {
+  AgeModelBoundary,
+  BoundaryStatus,
+  BoundaryType,
+  UnitLong,
+} from "@macrostrat/api-types";
+import { ColumnAxisType } from "@macrostrat/column-components";
+
+export type { AgeModelBoundary, BoundaryStatus, BoundaryType };
+
+/** A boundary status, plus `derived` for surfaces computed from units rather
+ * than stored in the age model. */
+export type SurfaceStatus = BoundaryStatus | "derived";
+
+/** The interval a surface is calibrated against */
+export interface SurfaceCalibration {
+  id: number;
+  name: string;
+  b_age: number;
+  t_age: number;
+}
+
+export interface ColumnSurface {
+  id: number | string;
+  /** Modeled age of the surface (Ma) */
+  age: number;
+  /** Measured position (height or depth) along the column, when known */
+  position?: number | null;
+  status: SurfaceStatus;
+  type: BoundaryType;
+  /** The calibration interval, and the surface's position within it
+   * (0 at the interval's base, 1 at its top) */
+  calibration?: SurfaceCalibration | null;
+  proportion?: number | null;
+  /** True when `status` was inferred rather than read from the data — see
+   * `inferTiePointStatuses`. */
+  statusInferred?: boolean;
+  unitsAbove: number[];
+  unitsBelow: number[];
+  section_id?: number | null;
+  ref_id?: number | null;
+  /** The API record, when the surface came from `/age_model` */
+  boundary?: AgeModelBoundary;
+}
+
+export const surfaceStatuses: SurfaceStatus[] = [
+  "absolute",
+  "relative",
+  "spike",
+  "imposed",
+  "modeled",
+  "",
+  "derived",
+];
+
+/** The statuses at which the age model was actually constrained — the tie
+ * points — as opposed to surfaces whose age falls out of the model
+ * (`modeled`), carries no status, or is merely derived from units. These are
+ * the surfaces worth labeling by default. */
+export const TIE_POINT_STATUSES: SurfaceStatus[] = [
+  "absolute",
+  "relative",
+  "spike",
+  "imposed",
+];
+
+export const surfaceStatusLabels: Record<SurfaceStatus, string> = {
+  absolute: "Absolute",
+  relative: "Relative",
+  spike: "Spike",
+  imposed: "Imposed",
+  modeled: "Modeled",
+  "": "Unspecified",
+  derived: "Derived",
+};
+
+export const surfaceStatusDescriptions: Record<SurfaceStatus, string> = {
+  absolute:
+    "Independently dated; the age is authoritative and the interval position is derived from it",
+  relative:
+    "Calibrated to a position within a geologic interval; the age follows the timescale",
+  spike: "Tied to a formally defined boundary point",
+  imposed:
+    "Interval-relative representation imposed on a boundary with no chronostratigraphic tie of its own (for instance, thickness interpolation)",
+  modeled: "Interpolated by the age model between calibrated surfaces",
+  "": "No status recorded",
+  derived:
+    "Computed from unit tops and bottoms; not stored in the column's age model",
+};
+
+/** A CSS-safe token for a status or type (`angular unconformity` →
+ * `angular-unconformity`, `""` → `unspecified`). */
+export function surfaceToken(value: string | null | undefined): string {
+  if (value == null || value === "") return "unspecified";
+  return value.replace(/[^a-z0-9]+/gi, "-").toLowerCase();
+}
+
+/** Legacy `unit_boundaries` rows use `0` as the "no unit" sentinel. */
+export function nullifyUnitID(id: number | null | undefined): number | null {
+  if (id == null || id === 0) return null;
+  return id;
+}
+
+/** How close to an interval's base or top a surface must sit to count as
+ * bounding it (as a fraction of the interval). */
+export const INTERVAL_BOUND_TOLERANCE = 0.001;
+
+/** Promote the `modeled` surfaces that cannot in fact have been interpolated
+ * to `relative`.
+ *
+ * This is a client-side affordance over a known gap in the data. An age model
+ * interpolates *between* tie points, so a surface with no constraint to
+ * interpolate from has to be one itself, whatever `boundary_status` says. Two
+ * cases are recognizable from the boundaries alone:
+ *
+ * - **It sits on the base or top of its calibration interval** (proportion 0
+ *   or 1). A height referred directly to an interval bounds the model rather
+ *   than falling out of it.
+ * - **It is the edge of a gap-bound package** — the youngest surface in its
+ *   section with no unit above, or the oldest with none below. There is
+ *   nothing beyond it to interpolate against.
+ *
+ * Both are common in columns whose age model was built by assigning positions
+ * within intervals, where the importer recorded everything as `modeled`;
+ * filtering to the tie-point statuses would otherwise hide real ones. Promoted
+ * surfaces are marked `statusInferred`, so views can say where the status came
+ * from; nothing about the underlying record changes.
+ *
+ * Two cases are deliberately left alone. A *mid-interval* position is
+ * ambiguous: an assigned position and an interpolated one are the same record
+ * there, and only the data can settle it. And an open side in the *interior*
+ * of a section is a lateral relationship, not a package edge — a unit that
+ * pinches out while others span past it — which the model can interpolate
+ * normally.
+ */
+export function inferTiePointStatuses(
+  surfaces: ColumnSurface[],
+  tolerance: number = INTERVAL_BOUND_TOLERANCE,
+): ColumnSurface[] {
+  const extents = sectionAgeExtents(surfaces);
+
+  return surfaces.map((surface) => {
+    if (surface.status !== "modeled") return surface;
+    if (surface.calibration == null) return surface;
+
+    const { proportion } = surface;
+    const onIntervalBound =
+      proportion != null &&
+      (Math.abs(proportion) <= tolerance ||
+        Math.abs(proportion - 1) <= tolerance);
+
+    if (!onIntervalBound && !boundsPackage(surface, extents)) {
+      return surface;
+    }
+    return { ...surface, status: "relative", statusInferred: true };
+  });
+}
+
+/** An open side only means a package edge at the ends of the section. In its
+ * interior it means a unit pinching out while others span past it, which the
+ * age model interpolates like any other surface. */
+function boundsPackage(
+  surface: ColumnSurface,
+  extents: Map<ColumnSurface["section_id"], [number, number]>,
+): boolean {
+  const extent = extents.get(surface.section_id ?? null);
+  if (extent == null) return false;
+  const [youngest, oldest] = extent;
+  if (surface.unitsAbove.length === 0 && surface.age === youngest) return true;
+  return surface.unitsBelow.length === 0 && surface.age === oldest;
+}
+
+/** The youngest and oldest surface age in each section. */
+function sectionAgeExtents(
+  surfaces: ColumnSurface[],
+): Map<ColumnSurface["section_id"], [number, number]> {
+  const extents = new Map<ColumnSurface["section_id"], [number, number]>();
+  for (const surface of surfaces) {
+    const key = surface.section_id ?? null;
+    const extent = extents.get(key);
+    if (extent == null) {
+      extents.set(key, [surface.age, surface.age]);
+      continue;
+    }
+    extent[0] = Math.min(extent[0], surface.age);
+    extent[1] = Math.max(extent[1], surface.age);
+  }
+  return extents;
+}
+
+export function boundaryToSurface(boundary: AgeModelBoundary): ColumnSurface {
+  const above = nullifyUnitID(boundary.unit_above);
+  const below = nullifyUnitID(boundary.unit_below);
+  let calibration: SurfaceCalibration | null = null;
+  if (boundary.interval_id != null) {
+    calibration = {
+      id: boundary.interval_id,
+      name: boundary.interval_name,
+      b_age: boundary.age_bottom,
+      t_age: boundary.age_top,
+    };
+  }
+  return {
+    id: boundary.boundary_id,
+    age: boundary.model_age,
+    position: boundary.boundary_position,
+    status: boundary.boundary_status ?? "",
+    type: boundary.boundary_type ?? "",
+    calibration,
+    proportion: boundary.rel_position,
+    unitsAbove: above == null ? [] : [above],
+    unitsBelow: below == null ? [] : [below],
+    section_id: boundary.section_id,
+    ref_id: boundary.ref_id,
+    boundary,
+  };
+}
+
+export interface SurfacesFromBoundariesOptions {
+  /** Promote `modeled` surfaces that must in fact constrain the age model to
+   * `relative` (default `true`) — see `inferTiePointStatuses`. */
+  inferTiePoints?: boolean;
+}
+
+/** Surfaces for a column's age-model boundaries, youngest first. */
+export function surfacesFromBoundaries(
+  boundaries: AgeModelBoundary[] | null | undefined,
+  options: SurfacesFromBoundariesOptions = {},
+): ColumnSurface[] {
+  const { inferTiePoints = true } = options;
+  if (boundaries == null) return [];
+  let surfaces = boundaries.map(boundaryToSurface);
+  if (inferTiePoints) {
+    surfaces = inferTiePointStatuses(surfaces);
+  }
+  return surfaces.sort((a, b) => a.age - b.age);
+}
+
+export interface SurfacesFromUnitsOptions {
+  /** Surfaces closer than this (in the axis's units) are merged */
+  tolerance?: number;
+  /** Which unit field the surfaces are keyed on: ages for age columns,
+   * measured positions for height and depth columns */
+  axisType?: ColumnAxisType;
+}
+
+/** Derive surfaces from unit tops and bottoms. Every distinct top or bottom
+ * becomes one surface with status `derived`; units sharing a boundary share
+ * the surface. This is the fallback when a column has no `unit_boundaries`. */
+export function surfacesFromUnits<T extends UnitLong>(
+  units: T[] | null | undefined,
+  options: SurfacesFromUnitsOptions = {},
+): ColumnSurface[] {
+  const { tolerance = 0.001, axisType = ColumnAxisType.AGE } = options;
+  if (units == null) return [];
+  const byPosition = isPositionAxis(axisType);
+
+  const surfaces: ColumnSurface[] = [];
+
+  function keyOf(surface: ColumnSurface): number | null {
+    if (byPosition) return surface.position ?? null;
+    return surface.age;
+  }
+
+  function addBound(unit: T, top: boolean) {
+    const age = top ? unit.t_age : unit.b_age;
+    const position = asNumber(top ? unit.t_pos : unit.b_pos);
+    const key = byPosition ? position : age;
+    if (key == null) return;
+
+    let surface = surfaces.find((d) => {
+      const k = keyOf(d);
+      return k != null && Math.abs(k - key) < tolerance;
+    });
+    if (surface == null) {
+      surface = {
+        id: "",
+        age,
+        position,
+        status: "derived",
+        type: "",
+        calibration: null,
+        proportion: null,
+        unitsAbove: [],
+        unitsBelow: [],
+        section_id: unit.section_id,
+      };
+      surfaces.push(surface);
+    }
+    // The unit whose top this is lies *below* the surface, and vice versa
+    if (top) {
+      surface.unitsBelow.push(unit.unit_id);
+    } else {
+      surface.unitsAbove.push(unit.unit_id);
+    }
+  }
+
+  for (const unit of units) {
+    addBound(unit, true);
+    addBound(unit, false);
+  }
+
+  surfaces.sort((a, b) => compareAlongAxis(a, b, axisType));
+  return surfaces.map((s, i) => ({ ...s, id: `derived-${i}` }));
+}
+
+/** The coordinate a surface is drawn at for a given axis type: its age for
+ * age columns, its measured position for height and depth columns. `null`
+ * when the surface has no coordinate on that axis. */
+export function surfacePosition(
+  surface: ColumnSurface,
+  axisType: ColumnAxisType | null | undefined,
+): number | null {
+  if (isPositionAxis(axisType)) {
+    return surface.position ?? null;
+  }
+  return surface.age ?? null;
+}
+
+export function isPositionAxis(
+  axisType: ColumnAxisType | null | undefined,
+): boolean {
+  return (
+    axisType === ColumnAxisType.HEIGHT || axisType === ColumnAxisType.DEPTH
+  );
+}
+
+/** Order surfaces from the top of the column downwards. */
+export function compareAlongAxis(
+  a: ColumnSurface,
+  b: ColumnSurface,
+  axisType: ColumnAxisType | null | undefined,
+): number {
+  const pa = surfacePosition(a, axisType);
+  const pb = surfacePosition(b, axisType);
+  if (pa == null || pb == null) return 0;
+  if (axisType === ColumnAxisType.HEIGHT) {
+    // Heights increase upwards
+    return pb - pa;
+  }
+  // Ages and depths increase downwards
+  return pa - pb;
+}
+
+/** Percent of the way up its calibration interval, e.g. `85%`. */
+export function formatProportion(
+  proportion: number | null | undefined,
+): string | null {
+  if (proportion == null) return null;
+  return `${Math.round(proportion * 100)}%`;
+}
+
+/** A short text label for a surface: its calibration ("Calymmian · 85%")
+ * or, failing that, its age. */
+export function surfaceLabel(surface: ColumnSurface): string {
+  const { calibration } = surface;
+  if (calibration != null) {
+    const prop = formatProportion(surface.proportion);
+    if (prop != null) {
+      return `${calibration.name} · ${prop}`;
+    }
+    return calibration.name;
+  }
+  return formatAge(surface.age);
+}
+
+export function formatAge(age: number | null | undefined): string {
+  if (age == null) return "";
+  let value = age;
+  let unit = "Ma";
+  if (Math.abs(age) < 1) {
+    value = age * 1000;
+    unit = "ka";
+  }
+  const _value = value.toLocaleString("en-US", { maximumFractionDigits: 2 });
+  return `${_value} ${unit}`;
+}
+
+function asNumber(value: unknown): number | null {
+  if (value == null || value === "") return null;
+  const n = Number(value);
+  if (Number.isNaN(n)) return null;
+  return n;
+}

package/src/column.module.sass

@@ -1,4 +1,10 @@
+// One slot per timescale level, as `--timescale-level-count` counts them
+$timescale-column-width: calc(calc(1.5em + 1.5px) * var(--timescale-level-count, 4))
+
 .column-container, body:global(.light-mode) .column-container
+  // One selection color for everything a column can select — units, surfaces —
+  // so the highlight means the same thing wherever it appears
+  --column-selection-color: var(--column-cursor-color, var(--pz-accent-color, #7961db))
   --column-background-color: var(--background-color, #fff)
   --column-stroke-color: var(--text-emphasized-color, #000)
   --column-text-color: var(--text-emphasized-color, #000)
@@ -53,13 +59,18 @@ body:global(.dark-mode) .column-container
     stroke: var(--column-stroke-color)
     stroke-width: 1px
 
+  // A box around the selected unit: a light wash so its own color still
+  // reads, and an outline in the selection color
   .selection-overlay
-    fill: var(--selection-overlay-color, red)
-    fill-opacity: var(--selection-overlay-opacity, 0.5)
+    fill: var(--selection-overlay-color, var(--column-selection-color))
+    fill-opacity: var(--selection-overlay-opacity, 0.15)
+    stroke: var(--selection-overlay-color, var(--column-selection-color))
+    stroke-width: var(--selection-overlay-stroke-width, 2px)
+    vector-effect: non-scaling-stroke
 
   // Units sharing a stratigraphic name with the selection: a subtler highlight
   .linked-overlay
-    fill: var(--linked-overlay-color, var(--selection-overlay-color, red))
+    fill: var(--linked-overlay-color, var(--selection-overlay-color, var(--column-selection-color)))
     fill-opacity: var(--linked-overlay-opacity, 0.18)
     pointer-events: none
 
@@ -80,10 +91,6 @@ body:global(.dark-mode) .column-container
 .column-container :global g.height-range
   display: none
 
-.column-container :global .note-inner
-  border: none
-  padding: 1px
-
 .column-container :global .frame rect
   fill: transparent
 
@@ -99,12 +106,56 @@ body:global(.dark-mode) .column-container
   cursor: pointer
 
 .column-container :global(.timescale)
-  width: calc(calc(1.5em + 1.5px) * var(--timescale-level-count, 4))
+  width: $timescale-column-width
   --timescale-level-size: 1.5em
 
 .timescale-column
   position: relative
 
+// A section's timescales, drawn side by side against that section's scale.
+// The name is deliberately not `timescale-container`: that is also the class
+// on each `Timescale`'s own root, and the two were easy to confuse for one
+// another (this one went unstyled for a while, stacking the timescales).
+// Timescale names, set above the columns they belong to. Positioned out of
+// flow so the timescales still start level with the units beside them: a
+// column that shows these needs top padding to fit them.
+.timescale-labels
+  position: absolute
+  bottom: 100%
+  left: 0
+  display: flex
+  flex-direction: row
+  align-items: flex-end
+  padding-bottom: 3px
+
+  // Matches the gap between the leveled timescale and the rest
+  > :first-child
+    margin-right: 5px
+
+.timescale-label
+  // No font-size here: the width is in `em`, and must resolve the same way it
+  // does on the timescale below
+  width: $timescale-column-width
+  display: flex
+  justify-content: center
+  overflow: hidden
+
+.timescale-label-text
+  writing-mode: vertical-rl
+  transform: rotate(180deg)
+  white-space: nowrap
+  font-size: 11px
+  color: var(--secondary-color, var(--text-color))
+
+.section-timescales
+  display: flex
+  flex-direction: row
+  align-items: flex-start
+
+  // Set the timescale a column is leveled against apart from the others
+  > :first-child
+    margin-right: 5px
+
 .section-main
   position: relative
   margin-bottom: -4px

package/src/column.ts

@@ -30,11 +30,15 @@ import {
 import {
   MacrostratColumnDataProvider,
   useCompositeScale,
+  useLabelColumnClaimed,
   useMacrostratColumnData,
 } from "./data-provider";
 import {
   SectionSharedProps,
   CompositeTimescale,
+  type ColumnIntervalStyleBuilder,
+  type ColumnTimescaleClickHandler,
+  type ColumnTimescaleLike,
   SectionsColumn,
 } from "./section";
 import { ApproximateHeightAxis, CompositeAgeAxis } from "./age-axis";
@@ -45,10 +49,6 @@ import {
   ColumnHeightScaleOptions,
 } from "./prepare-units";
 import { UnitLong } from "@macrostrat/api-types";
-import type {
-  TimescaleClickHandler,
-  IntervalStyleBuilder,
-} from "@macrostrat/timescale";
 import { NonIdealState } from "@blueprintjs/core";
 import { DataField } from "@macrostrat/data-components";
 import { ScaleContinuousNumeric } from "d3-scale";
@@ -59,16 +59,32 @@ interface BaseColumnProps extends Omit<
 > {
   className?: string;
   showLabelColumn?: boolean;
+  /** Suppress the label for a unit drawn thinner than this many pixels
+   * (default 2) */
+  labelSuppressHeight?: number;
   keyboardNavigation?: boolean;
   showLabels?: boolean;
   maxInternalColumns?: number;
   // Timescale properties
   showTimescale?: boolean;
   timescaleLevels?: number | [number, number];
-  /** Called when a timescale interval is clicked (e.g. to zoom the age range). */
-  onClickTimescaleInterval?: TimescaleClickHandler;
-  /** Per-interval style for the timescale (e.g. to bold the selected interval). */
-  timescaleIntervalStyle?: IntervalStyleBuilder;
+  /** Regional or project timescales drawn as extra columns beside the
+   * international one (see `CompositeTimescale`). Narrow `timescaleLevels` by
+   * as many to swap the finest level for them rather than widen the column. */
+  additionalTimescales?: number[];
+  /** Every timescale to draw beside the column, in order: a Macrostrat
+   * timescale ID, or a timescale with its own intervals (see
+   * `CompositeTimescale`). Supersedes `timescaleLevels` and
+   * `additionalTimescales`. */
+  timescales?: ColumnTimescaleLike[];
+  /** Draw each timescale's name above it */
+  showTimescaleLabels?: boolean;
+  /** Called when a timescale interval is clicked (e.g. to zoom the age range).
+   * The data says which timescale it was clicked in. */
+  onClickTimescaleInterval?: ColumnTimescaleClickHandler;
+  /** Per-interval style for the timescale (e.g. to bold the selected
+   * interval), by interval and the timescale it was drawn from. */
+  timescaleIntervalStyle?: ColumnIntervalStyleBuilder;
   unconformityLabels?: boolean | UnconformityLabelPlacement;
   onMouseOver?: (
     unit: UnitLong | null,
@@ -119,7 +135,10 @@ export function Column(props: ColumnProps) {
     b_pos,
     unconformityHeight = 30,
     targetUnitHeight = 20,
+    sectionOptions,
     pixelScale,
+    pixelsPerMyr,
+    pixelsPerMeter,
     minPixelScale = 0.2,
     minSectionHeight = 50,
     windowPadding = 0,
@@ -134,16 +153,9 @@ export function Column(props: ColumnProps) {
     ...rest
   } = props;
 
-  /* Make pixelScale and targetUnitHeight mutually exclusive. PixelScale implies
-   * standardization of scales in all sections */
-  let _targetUnitHeight: number | null = targetUnitHeight;
-  let _minSectionHeight = minSectionHeight;
-  let _minPixelScale = minPixelScale;
-  if (pixelScale != null) {
-    _targetUnitHeight = null;
-    _minSectionHeight = 0;
-    _minPixelScale = pixelScale;
-  }
+  /* `pixelScale` and `targetUnitHeight` are alternatives: a density stated
+   * outright takes over from the one a section's units imply, floors and all.
+   * That is settled in `prepare-units/density`, so nothing is adjusted here. */
 
   // Handle special cases for hybrid scales (WIP, we need to regularize this)
   let _axisType = axisType ?? ColumnAxisType.AGE;
@@ -164,11 +176,14 @@ export function Column(props: ColumnProps) {
     t_pos,
     b_pos,
     mergeSections,
-    targetUnitHeight: _targetUnitHeight,
+    targetUnitHeight,
+    sectionOptions,
     unconformityHeight,
     pixelScale,
-    minPixelScale: _minPixelScale,
-    minSectionHeight: _minSectionHeight,
+    pixelsPerMyr,
+    pixelsPerMeter,
+    minPixelScale,
+    minSectionHeight,
     windowPadding,
     collapseSmallUnconformities,
     // TODO: consider unifying scale and hybridScale options
@@ -231,11 +246,15 @@ function ColumnInner(props: ColumnInnerProps) {
     width: _width = 300,
     columnWidth: _columnWidth = 150,
     showLabelColumn: _showLabelColumn = true,
+    labelSuppressHeight,
     className,
     clipUnits = false,
     children,
     showTimescale,
     timescaleLevels,
+    additionalTimescales,
+    timescales,
+    showTimescaleLabels,
     maxInternalColumns,
     onMouseOver,
     onClickTimescaleInterval,
@@ -244,6 +263,9 @@ function ColumnInner(props: ColumnInnerProps) {
   } = props;
 
   const { axisType } = useMacrostratColumnData();
+  // A child layer drawing its own labels (the surfaces view) takes the label
+  // column over from the unit labels
+  const labelColumnClaimed = useLabelColumnClaimed();
 
   const columnRef = useColumnRef();
 
@@ -262,12 +284,12 @@ function ColumnInner(props: ColumnInnerProps) {
     columnWidth = width;
   }
   let showLabelColumn = _showLabelColumn;
-  if (columnWidth > width - 10) {
+  if (columnWidth > width - 10 || labelColumnClaimed) {
     showLabelColumn = false;
   }
 
   let _showTimescale = showTimescale ?? true;
-  if (timescaleLevels != null) {
+  if (timescaleLevels != null || timescales != null) {
     _showTimescale = true;
   }
   _showTimescale = axisType == ColumnAxisType.AGE && _showTimescale;
@@ -283,6 +305,9 @@ function ColumnInner(props: ColumnInnerProps) {
       h(ageAxisComponent),
       h.if(_showTimescale)(CompositeTimescale, {
         levels: timescaleLevels,
+        additionalTimescales,
+        timescales,
+        showLabels: showTimescaleLabels,
         unconformityLabels: _timescaleUnconformityLabels,
         onClickInterval: onClickTimescaleInterval,
         intervalStyle: timescaleIntervalStyle,
@@ -293,6 +318,7 @@ function ColumnInner(props: ColumnInnerProps) {
         width,
         columnWidth,
         showLabelColumn,
+        labelSuppressHeight,
         clipUnits,
         unconformityLabels: _sectionUnconformityLabels,
         maxInternalColumns,