@lblod/ember-rdfa-editor-lblod-plugins 32.3.0 → 32.4.0

package/addon/plugins/location-plugin/_private/utils/address-helpers.ts

@@ -0,0 +1,407 @@
+import { unwrap } from '@lblod/ember-rdfa-editor-lblod-plugins/utils/option';
+import { NodeContentsUtils } from '../../node-contents';
+import {
+  convertLambertCoordsToWGS84,
+  parseLambert72GMLString,
+  Point,
+} from './geo-helpers';
+
+type Identificator = {
+  id: string;
+  naamruimte: string;
+  objectId: string;
+  versieId: string;
+};
+type GeographicalName = {
+  spelling: string;
+  taal: string;
+};
+type DetailLink = {
+  objectId: string;
+  detail: string;
+};
+type GeoCoordinate = {
+  Lat_WGS84: number;
+  Lon_WGS84: number;
+  X_Lambert72: number;
+  Y_Lambert72: number;
+};
+/**
+ * Specified [in the API docs]{@link https://geo.api.vlaanderen.be/geolocation/}.
+ * It is not specified which fields can be null, so these might be incorrect.
+ */
+type LocationRegisterSearchResult = {
+  LocationResult: [
+    {
+      ID: number;
+      Municipality: string;
+      Zipcode: string | null;
+      Thoroughfarename: string | null;
+      Housenumber: string | null;
+      FormattedAddress: string | null;
+      Location: GeoCoordinate;
+      LocationType: string | null;
+      BoundingBox: {
+        LowerLeft: GeoCoordinate;
+        UpperRight: GeoCoordinate;
+      };
+    },
+  ];
+};
+
+type StreetSearchResult = {
+  adresMatches: [
+    {
+      gemeente: {
+        gemeentenaam: { geografischeNaam: GeographicalName };
+      };
+      straatnaam?: {
+        straatnaam: {
+          geografischeNaam: GeographicalName;
+        };
+      };
+    },
+  ];
+};
+
+type AddressSearchResult = {
+  adressen: {
+    identificator: Identificator;
+    detail: string;
+    huisnummer?: string;
+    volledigAdres: GeographicalName;
+    adresStatus: string;
+  }[];
+};
+
+/**
+ * {@link https://docs.basisregisters.vlaanderen.be/docs/api-documentation.html#operation/GetAddressV2}
+ */
+type AddressDetailResult = {
+  identificator: Identificator;
+  gemeente: DetailLink & {
+    gemeentenaam: {
+      geografischeNaam: GeographicalName;
+    };
+  };
+  postinfo: DetailLink;
+  straatnaam: DetailLink & {
+    straatnaam: {
+      geografischeNaam: GeographicalName;
+    };
+  };
+  huisnummer: string;
+  busnummer?: string;
+  volledigAdres: GeographicalName;
+  officieelToegekend: boolean;
+  adresPositie: {
+    geometrie: {
+      type: 'Point' | string;
+      /** GML encoded coordinates using Lambert72 CRS */
+      gml: string;
+    };
+    positieGeometrieMethode: string;
+    positieSpecificatie: string;
+  };
+};
+
+export class Address {
+  declare uri: string;
+  declare belgianAddressUri?: string;
+  declare street: string;
+  declare zipcode: string;
+  declare municipality: string;
+  declare housenumber?: string;
+  declare busnumber?: string;
+  declare location: Point;
+  declare truncated: boolean;
+
+  constructor(
+    args: Pick<
+      Address,
+      | 'street'
+      | 'housenumber'
+      | 'zipcode'
+      | 'municipality'
+      | 'uri'
+      | 'busnumber'
+      | 'location'
+      | 'belgianAddressUri'
+      | 'truncated'
+    >,
+  ) {
+    Object.assign(this, args);
+  }
+
+  get formatted() {
+    if (this.truncated) {
+      if (this.housenumber && this.busnumber) {
+        return `${this.street} ${this.housenumber} bus ${this.busnumber}`;
+      } else if (this.housenumber) {
+        return `${this.street} ${this.housenumber}`;
+      } else {
+        return `${this.street}`;
+      }
+    } else {
+      if (this.housenumber && this.busnumber) {
+        return `${this.street} ${this.housenumber} bus ${this.busnumber}, ${this.zipcode} ${this.municipality}`;
+      } else if (this.housenumber) {
+        return `${this.street} ${this.housenumber}, ${this.zipcode} ${this.municipality}`;
+      } else {
+        return `${this.street}, ${this.zipcode} ${this.municipality}`;
+      }
+    }
+  }
+
+  sameAs(
+    other?: Pick<
+      Address,
+      'street' | 'housenumber' | 'busnumber' | 'municipality' | 'truncated'
+    > | null,
+  ) {
+    return (
+      this.street === other?.street &&
+      this.housenumber === other?.housenumber &&
+      this.busnumber === other?.busnumber &&
+      this.municipality === other?.municipality &&
+      this.truncated === other?.truncated
+    );
+  }
+
+  get hasHouseNumber() {
+    return !!this.housenumber;
+  }
+}
+
+export class AddressError extends Error {
+  translation: string;
+  status?: number;
+  coords?: string;
+  alternativeAddress?: Address;
+  constructor({
+    message,
+    translation,
+    status,
+    coords,
+    alternativeAddress,
+  }: Pick<
+    AddressError,
+    'message' | 'translation' | 'status' | 'alternativeAddress' | 'coords'
+  >) {
+    super(message);
+    this.translation = translation;
+    this.status = status;
+    this.coords = coords;
+    this.alternativeAddress = alternativeAddress;
+  }
+}
+
+const LOC_GEOPUNT_ENDPOINT = `https://geo.api.vlaanderen.be/geolocation/v4/Location`;
+const BASISREGISTER = 'https://api.basisregisters.vlaanderen.be/v2';
+const BASISREGISTER_ADRESMATCH = `${BASISREGISTER}/adresmatch`;
+const BASISREGISTER_ADRES = `${BASISREGISTER}/adressen`;
+
+export const replaceAccents = (string: string) =>
+  string.normalize('NFD').replace(/([\u0300-\u036f])/g, '');
+
+export async function fetchMunicipalities(term: string): Promise<string[]> {
+  const url = new URL(LOC_GEOPUNT_ENDPOINT);
+  url.searchParams.append('q', replaceAccents(term.replace(/^"(.*)"$/, '$1')));
+  url.searchParams.append('c', '10');
+  url.searchParams.append('type', 'Municipality');
+  const result = await fetch(url, {
+    method: 'GET',
+  });
+  if (result.ok) {
+    const jsonResult = (await result.json()) as LocationRegisterSearchResult;
+    const municipalities = jsonResult.LocationResult.map(
+      (entry) => entry.Municipality,
+    );
+    return municipalities;
+  } else {
+    throw new AddressError({
+      translation: 'editor-plugins.address.edit.errors.http-error',
+      message: `An error occured when querying the location register, status code: ${result.status}`,
+      status: result.status,
+    });
+  }
+}
+
+export async function fetchStreets(term: string, municipality: string) {
+  const url = new URL(BASISREGISTER_ADRESMATCH);
+  url.searchParams.append(
+    'straatnaam',
+    replaceAccents(term.replace(/^"(.*)"$/, '$1')),
+  );
+  url.searchParams.append('gemeentenaam', municipality);
+  const result = await fetch(url, {
+    method: 'GET',
+  });
+  if (result.ok) {
+    const jsonResult = (await result.json()) as StreetSearchResult;
+
+    const streetnames = jsonResult.adresMatches
+      .map((entry) => entry.straatnaam?.straatnaam.geografischeNaam.spelling)
+      .filter(Boolean);
+
+    return streetnames;
+  } else {
+    throw new AddressError({
+      translation: 'editor-plugins.address.edit.errors.http-error',
+      message: `An error occured when querying the address register, status code: ${result.status}`,
+      status: result.status,
+    });
+  }
+}
+
+type StreetInfo = {
+  municipality: string;
+  street: string;
+  truncated: boolean;
+};
+
+export async function resolveStreet(
+  info: StreetInfo,
+  nodeContentsUtils: NodeContentsUtils,
+) {
+  const searchTerm = `${info.street}, ${info.municipality}`;
+  const url = new URL(LOC_GEOPUNT_ENDPOINT);
+  url.searchParams.append(
+    'q',
+    replaceAccents(searchTerm.replace(/^"(.*)"$/, '$1')),
+  );
+  url.searchParams.append('c', '1');
+  url.searchParams.append('type', 'ThoroughFarename');
+  const result = await fetch(url, {
+    method: 'GET',
+  });
+  if (result.ok) {
+    const jsonResult = (await result.json()) as LocationRegisterSearchResult;
+    const streetinfo = jsonResult.LocationResult[0];
+    if (streetinfo) {
+      return new Address({
+        uri: nodeContentsUtils.fallbackAddressUri(),
+        belgianAddressUri: `https://data.vlaanderen.be/id/straatnaam/${streetinfo.ID}`,
+        street: unwrap(streetinfo.Thoroughfarename),
+        municipality: streetinfo.Municipality,
+        zipcode: unwrap(streetinfo.Zipcode),
+        truncated: info.truncated,
+        location: new Point({
+          uri: nodeContentsUtils.fallbackGeometryUri(),
+          location: {
+            global: {
+              lng: streetinfo.Location.Lon_WGS84,
+              lat: streetinfo.Location.Lat_WGS84,
+            },
+            lambert: {
+              x: streetinfo.Location.X_Lambert72,
+              y: streetinfo.Location.Y_Lambert72,
+            },
+          },
+        }),
+      });
+    } else {
+      throw new AddressError({
+        translation: 'editor-plugins.address.edit.errors.address-not-found',
+        message: `Could not find address in address register`,
+      });
+    }
+  } else {
+    throw new AddressError({
+      translation: 'editor-plugins.address.edit.errors.http-error',
+      message: `An error occured when querying the location register, status code: ${result.status}`,
+      status: result.status,
+    });
+  }
+}
+type AddressInfo = {
+  municipality: string;
+  street: string;
+  housenumber: string;
+  busnumber?: string;
+  truncated: boolean;
+};
+
+export async function resolveAddress(
+  info: AddressInfo,
+  nodeContentsUtils: NodeContentsUtils,
+) {
+  const addressSearchResult = await searchAddress(info, 1);
+  if (addressSearchResult.adressen.length) {
+    const addressDetailURL = addressSearchResult.adressen[0].detail;
+    const response = await fetch(addressDetailURL);
+    if (response.ok) {
+      const result = (await response.json()) as AddressDetailResult;
+      const { lambert } = parseLambert72GMLString(
+        result.adresPositie.geometrie.gml,
+      );
+      return new Address({
+        street: result.straatnaam.straatnaam.geografischeNaam.spelling,
+        housenumber: result.huisnummer,
+        busnumber: result.busnummer,
+        zipcode: result.postinfo.objectId,
+        municipality: result.gemeente.gemeentenaam.geografischeNaam.spelling,
+        uri: nodeContentsUtils.fallbackAddressUri(),
+        belgianAddressUri: result.identificator.id,
+        truncated: info.truncated,
+        location: new Point({
+          uri: `${result.identificator.id}/1`,
+          location: {
+            lambert,
+            global: convertLambertCoordsToWGS84(lambert),
+          },
+        }),
+      });
+    } else {
+      throw new AddressError({
+        translation: 'editor-plugins.address.edit.errors.http-error',
+        message: `An error occured when querying the address register, status code: ${response.status}`,
+        status: response.status,
+      });
+    }
+  } else {
+    const alternativeAddress = await resolveStreet(
+      {
+        street: info.street,
+        municipality: info.municipality,
+        truncated: info.truncated,
+      },
+      nodeContentsUtils,
+    );
+
+    throw new AddressError({
+      translation: 'editor-plugins.address.edit.errors.address-not-found',
+      message: `Could not find address in address register`,
+      alternativeAddress,
+    });
+  }
+}
+
+export async function searchAddress(
+  { municipality, street, housenumber, busnumber }: AddressInfo,
+  limit = 10,
+) {
+  const url = new URL(BASISREGISTER_ADRES);
+
+  url.searchParams.append('GemeenteNaam', replaceAccents(municipality));
+  url.searchParams.append('Straatnaam', replaceAccents(street));
+  url.searchParams.append('limit', limit.toString());
+  url.searchParams.append('Huisnummer', replaceAccents(housenumber));
+  if (busnumber) {
+    url.searchParams.append('Busnummer', replaceAccents(busnumber));
+  }
+
+  const response = await fetch(url.toString(), {
+    method: 'GET',
+  });
+
+  if (response.ok) {
+    return (await response.json()) as AddressSearchResult;
+  } else {
+    throw new AddressError({
+      translation: 'editor-plugins.address.edit.errors.http-error',
+      message: `An error occured when querying the address register, status code: ${response.status}`,
+      status: response.status,
+    });
+  }
+}

package/addon/plugins/location-plugin/_private/utils/geo-helpers.ts

@@ -0,0 +1,210 @@
+import proj from 'proj4';
+import { AddressError } from './address-helpers';
+
+/** A point represents a location as a geometry in the OSLO model. */
+export class Point {
+  declare uri: string;
+  declare location: GeoPos;
+  constructor(args: Omit<Point, 'constructor' | 'formatted'>) {
+    Object.assign(this, args);
+  }
+
+  get formatted() {
+    return `[${this.location.lambert.x}, ${this.location.lambert.y}]`;
+  }
+}
+/** A polygon represents a bounded area, a kind of geometry in the OSLO model. */
+export class Polygon {
+  declare uri: string;
+  declare locations: GeoPos[];
+  constructor(args: Omit<Polygon, 'constructor' | 'formatted'>) {
+    this.uri = args.uri;
+    // The start and end points of a polygon should match
+    if (isSamePos(args.locations[0], args.locations.at(-1))) {
+      this.locations = args.locations;
+    } else {
+      this.locations = [...args.locations, args.locations[0]];
+    }
+  }
+
+  get formatted() {
+    return `[${this.locations
+      .map(({ lambert }) => `[${lambert.x}, ${lambert.y}]`)
+      .join(', ')}]`;
+  }
+}
+/**
+ * A place represents the combination of a location and a name in the OSLO model. Only the name is
+ * displayed in the human readable text.
+ */
+export class Place {
+  declare uri: string;
+  declare name: string;
+  declare location: Point;
+  constructor(args: Omit<Place, 'constructor' | 'formatted'>) {
+    Object.assign(this, args);
+  }
+
+  get formatted() {
+    return this.name;
+  }
+}
+/**
+ * An area represents multiple points which bound a part of the map, along with the human readable
+ * name of that it represents. This is used as a place for the oslo model.
+ */
+export class Area {
+  declare uri: string;
+  declare name: string;
+  declare shape: Polygon;
+  constructor(args: Omit<Area, 'constructor' | 'formatted'>) {
+    Object.assign(this, args);
+  }
+
+  get formatted() {
+    return this.name;
+  }
+}
+
+/**
+ * This CRS definition is corrected from that on epsg.io/31370, as there is a known bug that their
+ * definitions invert some of the TOWGS84 parameters.
+ * See [this issue]{@link https://github.com/OSGeo/PROJ/issues/4170} for more details.
+ */
+const LAMBERT_CRS =
+  'PROJCS["BD72 / Belgian Lambert 72",GEOGCS["BD72",DATUM["Reseau_National_Belge_1972",SPHEROID["International 1924",6378388,297],TOWGS84[-106.8686,52.2978,-103.7239,0.3366,-0.457,1.8422,-1.2747]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4313"]],PROJECTION["Lambert_Conformal_Conic_2SP"],PARAMETER["latitude_of_origin",90],PARAMETER["central_meridian",4.36748666666667],PARAMETER["standard_parallel_1",51.1666672333333],PARAMETER["standard_parallel_2",49.8333339],PARAMETER["false_easting",150000.013],PARAMETER["false_northing",5400088.438],UNIT["metre",1,AUTHORITY["EPSG","9001"]],AXIS["Easting",EAST],AXIS["Northing",NORTH],AUTHORITY["EPSG","31370"]]';
+const lambertToWgs84 = proj(LAMBERT_CRS, 'EPSG:4326');
+/**
+ * Convert between CRSs using the proj4js library.
+ */
+export function convertLambertCoordsToWGS84(
+  lambert: Lambert72Coordinates,
+): GlobalCoordinates {
+  const { x, y } = lambertToWgs84.forward(lambert);
+  return { lat: y, lng: x };
+}
+/**
+ * Convert between CRSs using the proj4js library.
+ */
+export function convertWGS84CoordsToLambert(
+  wgs84: GlobalCoordinates,
+): Lambert72Coordinates {
+  return lambertToWgs84.inverse({ x: wgs84.lng, y: wgs84.lat });
+}
+
+/** Representation of a location in the `WGS84` (globally applicable) Coordinate Reference System */
+export type GlobalCoordinates = {
+  lat: number;
+  lng: number;
+};
+/** Representation of a location in the `BD72 / Belgian Lambert 72` Coordinate Reference System */
+export type Lambert72Coordinates = {
+  x: number;
+  y: number;
+};
+
+/**
+ * Geographical position in both reference systems used in this plugin.
+ * Most mapping software assumes coordinates use the WGS84 CRS. The OSLO RDFa model as well as some
+ * of the APIs we use, use the Belgium-specific Lambert 72 CRS. To avoid the difficulties in
+ * supporting map positions and tiles following this CRS, we convert instead to WGS84, or use it
+ * directly when returned from an API.
+ */
+export type GeoPos = {
+  global?: GlobalCoordinates;
+  lambert: Lambert72Coordinates;
+};
+
+export function isSamePos(
+  a: GeoPos | undefined,
+  b: GeoPos | undefined,
+): boolean {
+  return (
+    !!a && !!b && a.lambert.x === b.lambert.x && a.lambert.y === b.lambert.y
+  );
+}
+
+export function constructLambert72GMLString({ x, y }: Lambert72Coordinates) {
+  return `<gml:Point srsName="http://www.opengis.net/def/crs/EPSG/0/31370" xmlns:gml="http://www.opengis.net/gml/3.2"><gml:pos>${x} ${y}</gml:pos></gml:Point>`;
+}
+/**
+ * Use a regex to parse a simple point as a GML string and return the coordinates.
+ * Throws an error if the format or CRS are not recognised
+ */
+export function parseLambert72GMLString(gml: string): GeoPos {
+  // Parsers for GML exist in other libraries, but mostly within much larger projects (e.g.
+  // openlayers) in a way that is hard to extract due to the potential complexity of the geometries
+  // which can be represented. Since we handle only simple points, it's much less complex to just
+  // use a simple regex.
+  const [_, crs, x, y] =
+    /<gml.Point .*srsName="https?:\/\/www.opengis.net\/def\/crs\/([^"]+)".+<gml.pos>(\S+) ([^<]+)<\/gml:pos>/.exec(
+      gml,
+    ) || [];
+  if (!crs || crs !== 'EPSG/0/31370') {
+    throw new AddressError({
+      translation: 'editor-plugins.address.edit.errors.http-error',
+      message: 'An error occured when querying the address register',
+    });
+  }
+  const lambert = { x: Number(x), y: Number(y) };
+
+  return { lambert };
+}
+/**
+ * Construct a string to represent a geolocation, using the Lambert 72 reference system according to
+ * [the GeoSPARQL spec]{@link https://docs.ogc.org/is/22-047r1/22-047r1.html#10-8-1-%C2%A0-well-known-text}
+ */
+export function constructLambert72WKTString(
+  coords: Lambert72Coordinates | Lambert72Coordinates[],
+) {
+  if (!Array.isArray(coords)) {
+    const { x, y } = coords;
+    return `<http://www.opengis.net/def/crs/EPSG/0/31370> POINT(${x} ${y})`;
+  } else {
+    const points = coords.map(({ x, y }) => `${x} ${y}`).join(', ');
+    // Double brackets are not a mistake...
+    return `<http://www.opengis.net/def/crs/EPSG/0/31370> POLYGON((${points}))`;
+  }
+}
+
+function parseWKTCoord(coordString: string): GeoPos | false {
+  const [x, y] = coordString.split(' ');
+  const lambert = { x: Number(x), y: Number(y) };
+  if (!Number.isNaN(lambert.x) && !Number.isNaN(lambert.y)) {
+    return { lambert };
+  }
+  return false;
+}
+/**
+ * Use a regex to parse a simple point as a WKT string and return the coordinates.
+ * Throws an error if the format or CRS are not recognised
+ */
+export function parseLambert72WKTString(gml: string): GeoPos | GeoPos[] {
+  // Parsers for WKT exist in other libraries, but either within much larger projects (e.g.
+  // openlayers) in a way that is hard to extract due to the potential complexity of the geometries
+  // which can be represented or within untyped libraries (e.g. wicket). Since we handle only simple
+  // cases, it's much less complex to just use a simple regex.
+
+  const [_, crs, shape, dimensions] =
+    /<https?:\/\/www.opengis.net\/def\/crs\/([^"]+)> (POLYGON|POINT)\(\(?([\d,. ]+)\)\)?/.exec(
+      gml,
+    ) || [];
+  if (crs && crs === 'EPSG/0/31370') {
+    if (shape === 'POINT') {
+      const point = parseWKTCoord(dimensions);
+      if (point) {
+        return point;
+      }
+    } else if (shape === 'POLYGON') {
+      const coords = dimensions.split(/, ?/).map(parseWKTCoord);
+      if (coords && coords.every(Boolean)) {
+        return coords as GeoPos[];
+      }
+    }
+  }
+
+  throw new AddressError({
+    translation: 'editor-plugins.address.edit.errors.http-error',
+    message: 'An error occured when querying the address register',
+  });
+}

package/addon/plugins/location-plugin/_private/utils/node-utils.ts

@@ -0,0 +1,82 @@
+import { SayController, NodeSelection, PNode } from '@lblod/ember-rdfa-editor';
+import { sayDataFactory } from '@lblod/ember-rdfa-editor/core/say-data-factory';
+import {
+  PROV,
+  RDF,
+} from '@lblod/ember-rdfa-editor-lblod-plugins/utils/constants';
+import { v4 as uuidv4 } from 'uuid';
+import { findAncestors } from '@lblod/ember-rdfa-editor/utils/position-utils';
+import {
+  Resource,
+  hasOutgoingNamedNodeTriple,
+} from '@lblod/ember-rdfa-editor-lblod-plugins/utils/namespace';
+import { Area, Place } from './geo-helpers';
+import { Address } from './address-helpers';
+
+/**
+ * Creates an 'OSLO location' node in place of the selection, along with the RDFa to create a triple
+ * with the nearest parent of one of the passed types as the subject and the predicate
+ * prov:atLocation. This doesn't work well with the RDFa tools, but since refactoring is required to
+ * clean up the RDFa structure inherited from variables and to make it work well with 'undo', this
+ * work was put off until then.
+ * @param controller - SayController
+ * @param toInsert - The object representing the location to insert
+ * @param subjectTypes - A list of Resources, each will be looked at in turn to compare the
+ * `rdf:type` of the resource, if no parent is found matching the first, then the second will be
+ * used, etc.
+ */
+export function replaceSelectionWithLocation(
+  controller: SayController,
+  subject: string,
+  toInsert?: Place | Address | Area,
+  subjectTypes?: Resource[],
+) {
+  let resourceToLink: { pos: number; node: PNode } | undefined;
+  subjectTypes?.forEach((subjectType) => {
+    if (!resourceToLink) {
+      resourceToLink = findAncestors(
+        controller.mainEditorState.selection.$from,
+        (node) => {
+          if ('typeof' in node.attrs) {
+            return subjectType.matches(node.attrs.typeof);
+          }
+          return hasOutgoingNamedNodeTriple(
+            node.attrs,
+            RDF('type'),
+            subjectType,
+          );
+        },
+      )[0];
+    }
+  });
+  const backlinks = !resourceToLink
+    ? []
+    : [
+        {
+          predicate: PROV('atLocation').full,
+          subject: sayDataFactory.resourceNode(
+            resourceToLink.node.attrs.subject,
+          ),
+        },
+      ];
+
+  controller.withTransaction((tr) => {
+    tr.replaceSelectionWith(
+      controller.schema.node('oslo_location', {
+        subject: subject,
+        rdfaNodeType: 'resource',
+        __rdfaId: uuidv4(),
+        value: toInsert,
+        properties: [],
+        backlinks,
+      }),
+    );
+    if (tr.selection.$anchor.nodeBefore) {
+      const resolvedPos = tr.doc.resolve(
+        tr.selection.anchor - tr.selection.$anchor.nodeBefore?.nodeSize,
+      );
+      tr.setSelection(new NodeSelection(resolvedPos));
+    }
+    return tr;
+  });
+}