@macrostrat/column-views 3.11.0 → 3.12.1

package/src/age-model/data.ts

@@ -0,0 +1,98 @@
+/** Data hooks for a column's age model. */
+import { useMemo } from "react";
+import { useAPIResult } from "@macrostrat/ui-components";
+import { useMacrostratBaseURL } from "@macrostrat/data-provider";
+import type { UnitLong } from "@macrostrat/api-types";
+import { useMacrostratColumnData, useMacrostratUnits } from "../data-provider";
+import {
+  type AgeModelBoundary,
+  type ColumnSurface,
+  surfacesFromBoundaries,
+  surfacesFromUnits,
+} from "./types";
+
+export const AGE_MODEL_ROUTE = "/age_model";
+
+/** The age-model boundaries of a column, from `/age_model?col_id=` on the
+ * API the enclosing `MacrostratDataProvider` points at (production when there
+ * is none). `null` while loading or when `col_id` is not set. */
+export function useColumnAgeModel(
+  col_id: number | null | undefined,
+): AgeModelBoundary[] | null {
+  const baseURL = useMacrostratBaseURL();
+  const params = useMemo(() => ({ col_id }), [col_id]);
+  let route: string | null = null;
+  if (col_id != null) {
+    route = baseURL + AGE_MODEL_ROUTE;
+  }
+  return useAPIResult(route, params, unwrapAgeModel) ?? null;
+}
+
+function unwrapAgeModel(res: any): AgeModelBoundary[] {
+  return res?.success?.data ?? [];
+}
+
+/** Where a column's surfaces came from */
+export type SurfacesSource = "provided" | "age-model" | "derived" | "loading";
+
+export interface UseColumnSurfacesOptions {
+  /** Surfaces to show. When given, nothing is fetched. */
+  surfaces?: ColumnSurface[] | null;
+  /** The column whose age model to fetch. Defaults to the column being
+   * rendered (read from its units). */
+  col_id?: number | null;
+  /** When the age model has no boundaries, derive surfaces from the units
+   * instead (default `true`). */
+  fallbackToUnits?: boolean;
+  /** Promote `modeled` surfaces that must in fact constrain the age model to
+   * `relative` (default `true`) — see `inferTiePointStatuses`. */
+  inferTiePoints?: boolean;
+}
+
+export interface ColumnSurfacesData {
+  surfaces: ColumnSurface[];
+  source: SurfacesSource;
+}
+
+/** Resolve the surfaces to show for the enclosing `Column`: the ones passed
+ * in, else the column's age model, else (optionally) surfaces derived from
+ * its units. Must be used inside a `Column`. */
+export function useColumnSurfaces(
+  options: UseColumnSurfacesOptions = {},
+): ColumnSurfacesData {
+  const {
+    surfaces: provided,
+    col_id,
+    fallbackToUnits = true,
+    inferTiePoints = true,
+  } = options;
+  const units = useMacrostratUnits() as UnitLong[] | undefined;
+  const { axisType } = useMacrostratColumnData();
+
+  let fetchID: number | null = null;
+  if (provided == null) {
+    fetchID = col_id ?? units?.[0]?.col_id ?? null;
+  }
+  const boundaries = useColumnAgeModel(fetchID);
+
+  const fromAgeModel = useMemo(
+    () => surfacesFromBoundaries(boundaries, { inferTiePoints }),
+    [boundaries, inferTiePoints],
+  );
+
+  const derived = useMemo(() => {
+    if (!fallbackToUnits) return [];
+    return surfacesFromUnits(units, { axisType });
+  }, [units, axisType, fallbackToUnits]);
+
+  if (provided != null) {
+    return { surfaces: provided, source: "provided" };
+  }
+  if (fetchID != null && boundaries == null) {
+    return { surfaces: [], source: "loading" };
+  }
+  if (fromAgeModel.length > 0) {
+    return { surfaces: fromAgeModel, source: "age-model" };
+  }
+  return { surfaces: derived, source: "derived" };
+}

package/src/age-model/details.module.sass

@@ -0,0 +1,108 @@
+.surface-details-panel
+  display: flex
+  flex-direction: column
+  min-width: 0
+
+.surface-details-header
+  display: flex
+  flex-direction: row
+  align-items: center
+  flex-wrap: wrap
+  gap: 0.5em
+  padding: 0.5em 0
+  border-bottom: 1px solid var(--pz-panel-rule-color, var(--panel-rule-color, #ddd))
+  .spacer
+    flex: 1
+
+.surface-details-title
+  margin: 0
+  font-size: 1.1em
+  .surface-id
+    font-size: 0.85em
+    color: var(--text-subtle-color, var(--pz-text-subtle-color))
+
+.surface-details-tags
+  display: flex
+  gap: 0.3em
+
+.surface-details-content
+  padding: 0.5em 0
+
+.no-surface .placeholder
+  color: var(--text-subtle-color, var(--pz-text-subtle-color))
+  margin: 0
+
+.surface-tag
+  // A colored dot leading the status label
+  &:before
+    content: ''
+    display: inline-block
+    width: 0.6em
+    height: 0.6em
+    border-radius: 50%
+    margin-right: 0.4em
+    background-color: var(--surface-color, currentColor)
+  &.surface-type-tag:before
+    display: none
+  // An inferred status is marked, so the tag doesn't pass for a recorded one
+  &.inferred
+    font-style: italic
+
+.inferred-marker
+  margin-left: 0.15em
+  opacity: 0.7
+
+.calibration-interval
+  display: flex
+  align-items: baseline
+  gap: 0.5em
+  flex-wrap: wrap
+
+.calibration-range
+  color: var(--text-subtle-color, var(--pz-text-subtle-color))
+  font-size: 0.9em
+
+.calibration-proportion
+  margin-top: 0.2em
+
+.surface-units-list
+  list-style: none
+  margin: 0
+  padding: 0
+  li
+    display: inline
+    &:after
+      content: ', '
+    &:last-child:after
+      content: ''
+
+.no-units, .no-calibration
+  color: var(--text-subtle-color, var(--pz-text-subtle-color))
+
+.surface-status-legend
+  list-style: none
+  margin: 0
+  padding: 0
+  display: flex
+  flex-direction: column
+  gap: 0.3em
+  font-size: 0.85em
+  &.with-descriptions
+    gap: 0.6em
+
+.legend-item
+  display: flex
+  flex-direction: row
+  align-items: baseline
+  gap: 0.6em
+  .surface-label-marker
+    flex: none
+    width: 24px
+    align-self: center
+
+.legend-label
+  font-weight: 500
+
+.legend-description
+  color: var(--text-subtle-color, var(--pz-text-subtle-color))
+  font-size: 0.9em

package/src/age-model/details.ts

@@ -0,0 +1,333 @@
+/** The inspector for a selected surface, and the small tags and legend that
+ * explain surface statuses and types. */
+import hyper from "@macrostrat/hyper";
+import classNames from "classnames";
+import { type ReactNode, useMemo } from "react";
+import { Button, Tag } from "@blueprintjs/core";
+import {
+  DataField,
+  Identifier,
+  type IntervalShort,
+  IntervalTag,
+  UnitIdentifier,
+  Value,
+} from "@macrostrat/data-components";
+import { useMacrostratDefs } from "@macrostrat/data-provider";
+import type { UnitLong } from "@macrostrat/api-types";
+import { useColumnUnitsMap } from "../data-provider";
+import { AgeLabel } from "../unit-details/age-range";
+import { formatRange } from "../unit-details/utils";
+import { ReferencesField } from "../unit-details/panel";
+import { surfaceClasses } from "./surfaces";
+import surfaceStyles from "./surfaces.module.sass";
+import styles from "./details.module.sass";
+import {
+  type BoundaryType,
+  type ColumnSurface,
+  type SurfaceStatus,
+  formatProportion,
+  surfaceStatuses,
+  surfaceStatusDescriptions,
+  surfaceStatusLabels,
+} from "./types";
+
+const h = hyper.styled({ ...surfaceStyles, ...styles });
+
+export interface SurfaceDetailsPanelProps {
+  /** The surface to inspect; `null` renders the panel's empty state */
+  surface: ColumnSurface | null;
+  onClose?: () => void;
+  /** Called when a unit above or below the surface is clicked */
+  onSelectUnit?: (unitID: number) => void;
+  /** Extra controls for the header */
+  actions?: ReactNode;
+  /** Label for the measured-position field ("Height" or "Depth") */
+  positionLabel?: string;
+  className?: string;
+}
+
+/** Details of one surface: its age, calibration, the units it separates, and
+ * provenance. A companion to `UnitDetailsPanel`. */
+export function SurfaceDetailsPanel(props: SurfaceDetailsPanelProps) {
+  const {
+    surface,
+    onClose,
+    onSelectUnit,
+    actions,
+    positionLabel = "Position",
+    className,
+  } = props;
+
+  // A selection that hasn't been made yet is an ordinary state for a panel
+  // bound to one, not a caller error
+  if (surface == null) {
+    return h(
+      "div.surface-details-panel.no-surface",
+      { className },
+      h("p.placeholder", "No surface selected."),
+    );
+  }
+
+  let closeButton: ReactNode = null;
+  if (onClose != null) {
+    closeButton = h(Button, {
+      icon: "cross",
+      variant: "minimal",
+      size: "small",
+      onClick: onClose,
+      "aria-label": "Close",
+    });
+  }
+
+  let positionField: ReactNode = null;
+  if (surface.position != null) {
+    positionField = h(DataField, {
+      label: positionLabel,
+      value: surface.position.toLocaleString("en-US", {
+        maximumFractionDigits: 2,
+      }),
+      unit: "m",
+    });
+  }
+
+  let sectionField: ReactNode = null;
+  if (surface.section_id != null) {
+    sectionField = h(
+      DataField,
+      { label: "Section" },
+      h(Identifier, { id: surface.section_id }),
+    );
+  }
+
+  let refsField: ReactNode = null;
+  if (surface.ref_id != null) {
+    refsField = h(ReferencesField, { refs: [surface.ref_id] });
+  }
+
+  return h(
+    "div.surface-details-panel",
+    { className: classNames(className, surfaceClasses(surface)) },
+    [
+      h("div.surface-details-header", [
+        h("h3.surface-details-title", [
+          "Surface ",
+          h(SurfaceIdentifier, { id: surface.id }),
+        ]),
+        h("div.surface-details-tags", [
+          h(SurfaceStatusTag, {
+            status: surface.status,
+            inferred: surface.statusInferred,
+          }),
+          h(SurfaceTypeTag, { type: surface.type }),
+        ]),
+        h("div.spacer"),
+        actions,
+        closeButton,
+      ]),
+      h("div.surface-details-content", [
+        h(DataField, { label: "Model age" }, h(AgeLabel, { age: surface.age })),
+        h(SurfaceCalibrationField, { surface }),
+        positionField,
+        h(SurfaceUnitsField, {
+          label: "Unit above",
+          unitIDs: surface.unitsAbove,
+          onSelectUnit,
+        }),
+        h(SurfaceUnitsField, {
+          label: "Unit below",
+          unitIDs: surface.unitsBelow,
+          onSelectUnit,
+        }),
+        sectionField,
+        refsField,
+      ]),
+    ],
+  );
+}
+
+function SurfaceIdentifier({ id }: { id: ColumnSurface["id"] }) {
+  if (typeof id === "number") {
+    return h(Identifier, { id });
+  }
+  return h("code.surface-id", String(id));
+}
+
+/** The calibration interval as a colored tag, with the surface's position in
+ * it: "Calymmian (1600–1400 Ma), 85% above base". */
+function SurfaceCalibrationField({ surface }: { surface: ColumnSurface }) {
+  const { calibration, proportion } = surface;
+  const ids = useMemo(() => {
+    if (calibration == null) return [];
+    return [calibration.id];
+  }, [calibration?.id]);
+  // Interval colors come from the definitions table; the age model itself
+  // doesn't carry them
+  const intervalMap = useMacrostratDefs("intervals", ids, null);
+
+  if (calibration == null) {
+    return h(DataField, {
+      label: "Calibration",
+      value: "None",
+      className: "no-calibration",
+    });
+  }
+
+  const def = intervalMap?.get(calibration.id);
+  const interval: IntervalShort = {
+    id: calibration.id,
+    name: calibration.name,
+    b_age: calibration.b_age,
+    t_age: calibration.t_age,
+    color: def?.color,
+    rank: def?.rank,
+  };
+
+  return h(DataField, { label: "Calibration" }, [
+    h(
+      "div.calibration-interval",
+      h(IntervalTag, {
+        interval,
+        proportion,
+      }),
+    ),
+  ]);
+}
+
+function SurfaceUnitsField({
+  label,
+  unitIDs,
+  onSelectUnit,
+}: {
+  label: string;
+  unitIDs: number[];
+  onSelectUnit?: (unitID: number) => void;
+}) {
+  const unitsMap = useColumnUnitsMap();
+  if (unitIDs.length === 0) {
+    return h(DataField, { label, value: "None", className: "no-units" });
+  }
+  return h(
+    DataField,
+    { label, className: "surface-units-field" },
+    h(
+      "ul.surface-units-list",
+      unitIDs.map((unitID) => {
+        const unit = unitsMap?.get(unitID) as UnitLong | undefined;
+        let onClick: (() => void) | undefined = undefined;
+        if (onSelectUnit != null) {
+          onClick = () => onSelectUnit(unitID);
+        }
+        return h(
+          "li",
+          { key: unitID },
+          h(UnitIdentifier, {
+            unitID,
+            colID: unit?.col_id,
+            name: unit?.unit_name,
+            onClick,
+          }),
+        );
+      }),
+    ),
+  );
+}
+
+export function SurfaceStatusTag({
+  status,
+  inferred = false,
+  className,
+}: {
+  status: SurfaceStatus;
+  /** The status was inferred rather than recorded (see
+   * `inferTiePointStatuses`); the tag says so. */
+  inferred?: boolean;
+  className?: string;
+}) {
+  let label: ReactNode = surfaceStatusLabels[status] ?? status;
+  let title = surfaceStatusDescriptions[status];
+  if (inferred) {
+    label = [label, h("span.inferred-marker", "*")];
+    title = INFERRED_STATUS_DESCRIPTION;
+  }
+
+  return h(
+    Tag,
+    {
+      variant: "minimal",
+      className: classNames(
+        "surface-tag",
+        className,
+        surfaceClasses({ status }),
+        { inferred },
+      ),
+      title,
+    },
+    label,
+  );
+}
+
+const INFERRED_STATUS_DESCRIPTION =
+  "Recorded as modeled, but this surface cannot have been interpolated — it " +
+  "sits on the base or top of its interval, or is the edge of a gap-bound " +
+  "package — so it constrains the age model rather than falling out of it";
+
+export function SurfaceTypeTag({
+  type,
+  className,
+}: {
+  type: BoundaryType | null | undefined;
+  className?: string;
+}) {
+  if (type == null || type === "") return null;
+  return h(
+    Tag,
+    {
+      variant: "minimal",
+      className: classNames("surface-tag", "surface-type-tag", className),
+    },
+    type,
+  );
+}
+
+export interface SurfaceStatusLegendProps {
+  statuses?: SurfaceStatus[];
+  showDescriptions?: boolean;
+  className?: string;
+}
+
+/** A legend of surface line styles, one entry per boundary status. */
+export function SurfaceStatusLegend(props: SurfaceStatusLegendProps) {
+  const {
+    statuses = surfaceStatuses,
+    showDescriptions = false,
+    className,
+  } = props;
+  return h(
+    "ul.surface-status-legend",
+    {
+      className: classNames(className, {
+        "with-descriptions": showDescriptions,
+      }),
+    },
+    statuses.map((status) => {
+      let description: ReactNode = null;
+      if (showDescriptions) {
+        description = h(
+          "div.legend-description",
+          surfaceStatusDescriptions[status],
+        );
+      }
+      return h(
+        "li.legend-item",
+        { key: status, className: surfaceClasses({ status }) },
+        [
+          h("div.surface-label-marker"),
+          h("div.legend-text", [
+            h("div.legend-label", surfaceStatusLabels[status]),
+            description,
+          ]),
+        ],
+      );
+    }),
+  );
+}

package/src/age-model/index.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./data";
+export * from "./surfaces";
+export * from "./details";
+export * from "./legacy";

package/src/age-model/legacy.ts

@@ -0,0 +1,30 @@
+/** Earlier, in-development overlays, kept so existing consumers keep working.
+ * Both are now thin wrappers over `ColumnSurfaces`. */
+import h from "@macrostrat/hyper";
+import { useMemo } from "react";
+import type { UnitLong } from "@macrostrat/api-types";
+import { useMacrostratColumnData, useMacrostratUnits } from "../data-provider";
+import { ColumnSurfaces } from "./surfaces";
+import { surfacesFromUnits } from "./types";
+
+/** @deprecated Use `ColumnSurfaces`, which also labels the surfaces and
+ * styles them by boundary status. */
+export function BoundaryAgeModelOverlay() {
+  return h(ColumnSurfaces, {
+    showLabels: false,
+    extent: "column",
+    fallbackToUnits: false,
+  });
+}
+
+/** @deprecated Use `ColumnSurfaces` with `surfaces: surfacesFromUnits(units)`,
+ * or rely on its default fallback to unit-derived surfaces. */
+export function ComputedSurfacesOverlay() {
+  const units = useMacrostratUnits() as UnitLong[];
+  const { axisType } = useMacrostratColumnData();
+  const surfaces = useMemo(
+    () => surfacesFromUnits(units, { axisType }),
+    [units, axisType],
+  );
+  return h(ColumnSurfaces, { surfaces, showLabels: false, extent: "column" });
+}