@mailwoman/spatial 4.9.0 → 4.11.0

package/out/geometries/point.d.ts

@@ -0,0 +1,208 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import type google from "@googlemaps/google-maps-services-js";
+import type { LatLng, LatLngLiteral } from "@googlemaps/google-maps-services-js";
+import { type BBox2DLiteral, type BBox3DLiteral, GeoBoundingBox } from "../bbox.js";
+import { type H3Cell } from "../h3/index.js";
+import { type GeoObjectLiteral } from "../objects.js";
+import { type InternalPointCoordinates, type Coordinates2D as Point2DCoordinates, type Coordinates3D as Point3DCoordinates } from "../position.js";
+/**
+ * A JSON-serializeable single point geometry, such as a specific location, address, or longitude,
+ * latitude pair.
+ *
+ * ```js
+ * {
+ * 	"type": "Point",
+ * 	"coordinates": [100, 0]
+ * }
+ * ```
+ *
+ * @title Point Geometry
+ * @public
+ */
+export interface PointLiteral extends GeoObjectLiteral {
+    /**
+     * Declares the type of GeoJSON object as a `Point` geometry.
+     */
+    type: "Point";
+    /**
+     * A pair of coordinates in the form of [longitude, latitude].
+     *
+     * @see {@linkcode Point2DCoordinates} for more information.
+     */
+    coordinates: Point2DCoordinates | Point3DCoordinates;
+}
+/**
+ * Type-predicate to determine if the given input is a GeoJSON Point geometry.
+ */
+export declare function isPointLiteral(input: PointLiteral | null | undefined | unknown): input is PointLiteral;
+/**
+ * Common interface for Browser Geolocation API coordinates.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates MDN Web Docs}
+ */
+export interface GeolocationCoordinatesLike {
+    latitude: number;
+    longitude: number;
+    altitude: number;
+}
+/**
+ * Type-predicate to determine if the given input appears to be a {@linkcode GeolocationCoordinates}
+ * object.
+ */
+export declare function isGeolocationCoordinatesLike(input: unknown): input is GeolocationCoordinatesLike;
+export type GeoPointInput = PointLiteral | Point2DCoordinates | Point3DCoordinates | GeolocationCoordinatesLike | InternalPointCoordinates | LatLngLiteral | LatLng;
+/**
+ * A single point geometry, such as a specific location, address, or longitude, latitude pair.
+ */
+export declare class GeoPoint implements PointLiteral {
+    #private;
+    /**
+     * Declares the type of GeoJSON object as a `Point` geometry.
+     */
+    readonly type: "Point";
+    /**
+     * The bounding box literal of the GeoPoint.
+     *
+     * @see {@linkcode GeoPoint.bbox} for the actual bounding box object.
+     * @see {@linkcode GeoBoundingBox} for creating a bounding box.
+     */
+    boundingBox: GeoBoundingBox | null;
+    /**
+     * The bounding box literal of the GeoPoint.
+     *
+     * @see {@linkcode BBox2DLiteral} for 2D bounding boxes.
+     * @see {@linkcode BBox3DLiteral} for 3D bounding boxes.
+     * @see {@linkcode GeoBoundingBox} for creating a bounding box.
+     */
+    get bbox(): BBox2DLiteral | BBox3DLiteral | undefined;
+    set bbox(bbox: BBox2DLiteral | BBox3DLiteral | undefined);
+    get coordinates(): Point2DCoordinates | Point3DCoordinates;
+    set coordinates(coords: Point2DCoordinates | Point3DCoordinates);
+    /**
+     * The longitude of the point in degrees, i.e. the x-coordinate.
+     *
+     * Values outside the range will be wrapped around to the opposite side of the globe.
+     *
+     * @minimum -180
+     * @maximum 180
+     */
+    get longitude(): number;
+    set longitude(value: number);
+    /**
+     * The latitude of the point in degrees, i.e. the y-coordinate.
+     *
+     * Values outside the range will be clamped to the poles.
+     *
+     * @minimum -90
+     * @maximum 90
+     */
+    get latitude(): number;
+    set latitude(value: number);
+    /**
+     * The altitude of the point, i.e. the z-coordinate.
+     *
+     * This is optional and is typically measured in meters.
+     */
+    get altitude(): number;
+    set altitude(value: number);
+    /**
+     * Create a new GeoPoint object with default coordinates.
+     */
+    constructor();
+    /**
+     * Create a new GeoPoint instance from another {@linkcode GeoJSONPosition} coordinates.
+     */
+    constructor(geoJSONPosition: Point2DCoordinates | Point3DCoordinates, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox);
+    /**
+     * Create a new GeoPoint instance from the browser's Geolocation API coordinates.
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates MDN Web Docs}
+     */
+    constructor(geoLocationCoordinates: GeolocationCoordinatesLike, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox);
+    /**
+     * Creates a new GeoPoint instance from a Google Maps API
+     * {@linkcode google.LatLngLiteral | LatLngLiteral} object.
+     */
+    constructor(latLngLiteral: google.LatLngLiteral, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox);
+    /**
+     * Creates a new GeoPoint instance from internal coordinates.
+     */
+    constructor(interpolatedCoords: InternalPointCoordinates, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox);
+    /**
+     * Creates a new GeoPoint instance from a Google Maps API {@linkcode google.LatLng | LatLng}
+     * object.
+     */
+    constructor(latLng: LatLngLiteral, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox);
+    /**
+     * Create a new GeoPoint instance from another {@linkcode PointLiteral}.
+     */
+    constructor(geoPointJSON: PointLiteral, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox);
+    /**
+     * Create a new GeoPoint instance.
+     */
+    constructor(input: GeoPointInput, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox);
+    /**
+     * Attempts to create a new GeoPoint instance from the given input.
+     */
+    static from(input: unknown): GeoPoint | null;
+    /**
+     * Whether the GeoPoint is 2-dimensional.
+     */
+    is2D(): boolean;
+    /**
+     * Whether the GeoPoint is 3-dimensional.
+     */
+    is3D(): boolean;
+    /**
+     * Whether the GeoPoint is the null island at 0, 0.
+     */
+    isNullIsland(): boolean;
+    toJSON(): PointLiteral;
+    to2DCoordinates(): Point2DCoordinates;
+    to3DCoordinates(): Point3DCoordinates;
+    /**
+     * Converts the GeoPoint to a Google Maps API {@linkcode google.LatLngLiteral | LatLngLiteral}
+     * object.
+     */
+    toGoogleLatLngLiteral(): google.LatLngLiteral;
+    /**
+     * Converts the GeoPoint to DMS (Degrees, Minutes, Seconds) format.
+     */
+    toDMS(): string;
+    /**
+     * Converts the GeoPoint to a H3 short cell address.
+     */
+    toH3Cell(resolution?: number): H3Cell;
+    /**
+     * Converts the GeoPoint to a H3 short cell address.
+     */
+    toH3ShortCell(resolution?: number): import("../h3/index.js").H3CellShort;
+    toString(): string;
+    [Symbol.iterator](): Iterator<number>;
+}
+/**
+ * An array of positions for each point in the geometry.
+ *
+ * @see {@linkcode GeoJSONPosition} for more information.
+ */
+export type MultiPointPath = [...points: Array<Point2DCoordinates | Point3DCoordinates>];
+/**
+ * A collection of points, such as a constellation or a set of locations.
+ */
+export interface MultiPointLiteral extends GeoObjectLiteral {
+    /**
+     * Declares the type of GeoJSON object as a `MultiPoint` geometry.
+     */
+    type: "MultiPoint";
+    /**
+     * An array of positions for each point in the geometry.
+     *
+     * @see {@linkcode GeoJSONPosition} for more information.
+     */
+    coordinates: MultiPointPath;
+}
+//# sourceMappingURL=point.d.ts.map

package/out/geometries/point.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"point.d.ts","sourceRoot":"","sources":["../../geometries/point.ts"],"names":[],"mappings":"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"}

package/out/geometries/point.js

@@ -0,0 +1,258 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import { tryParsingJSON } from "@mailwoman/core/objects";
+import { convert as convertCoords } from "geo-coordinates-parser";
+import { latLngToCell } from "h3-js";
+import { GeoBoundingBox, isBBox } from "../bbox.js";
+import { shortenH3Cell } from "../h3/index.js";
+import { GeometryType } from "../objects.js";
+import { clampLatitude, inferGeoJSONCoordOrder, isCoordPairLiteral, isGoogleMapsLatLngLiteral, isInterpolatedCoordinates, wrapLongitude, } from "../position.js";
+/**
+ * Type-predicate to determine if the given input is a GeoJSON Point geometry.
+ */
+export function isPointLiteral(input) {
+    if (!input || typeof input !== "object")
+        return false;
+    if (!("type" in input))
+        return false;
+    if (!("coordinates" in input))
+        return false;
+    if (input.type !== GeometryType.Point)
+        return false;
+    return isCoordPairLiteral(input.coordinates);
+}
+/**
+ * Type-predicate to determine if the given input appears to be a {@linkcode GeolocationCoordinates}
+ * object.
+ */
+export function isGeolocationCoordinatesLike(input) {
+    if (!input || typeof input !== "object")
+        return false;
+    if (!("latitude" in input))
+        return false;
+    if (!("longitude" in input))
+        return false;
+    if (!("altitude" in input))
+        return false;
+    return true;
+}
+//#region GeoPoint
+/**
+ * A single point geometry, such as a specific location, address, or longitude, latitude pair.
+ */
+export class GeoPoint {
+    //#region Properties
+    /**
+     * Declares the type of GeoJSON object as a `Point` geometry.
+     */
+    type = GeometryType.Point;
+    /**
+     * The bounding box literal of the GeoPoint.
+     *
+     * @see {@linkcode GeoPoint.bbox} for the actual bounding box object.
+     * @see {@linkcode GeoBoundingBox} for creating a bounding box.
+     */
+    boundingBox = null;
+    /**
+     * The bounding box literal of the GeoPoint.
+     *
+     * @see {@linkcode BBox2DLiteral} for 2D bounding boxes.
+     * @see {@linkcode BBox3DLiteral} for 3D bounding boxes.
+     * @see {@linkcode GeoBoundingBox} for creating a bounding box.
+     */
+    get bbox() {
+        return this.boundingBox?.toJSON();
+    }
+    set bbox(bbox) {
+        this.boundingBox = bbox ? new GeoBoundingBox(bbox) : null;
+    }
+    get coordinates() {
+        if (this.is3D()) {
+            return [this.#longitude, this.#latitude, this.#altitude];
+        }
+        return [this.#longitude, this.#latitude];
+    }
+    set coordinates(coords) {
+        const [longitude, latitude, altitude] = coords;
+        this.#longitude = longitude;
+        this.#latitude = latitude;
+        this.#altitude = typeof altitude === "number" ? altitude : 0;
+    }
+    #latitude = 0;
+    #longitude = 0;
+    #altitude = 0;
+    /**
+     * The longitude of the point in degrees, i.e. the x-coordinate.
+     *
+     * Values outside the range will be wrapped around to the opposite side of the globe.
+     *
+     * @minimum -180
+     * @maximum 180
+     */
+    get longitude() {
+        return this.#longitude;
+    }
+    set longitude(value) {
+        this.#longitude = wrapLongitude(value);
+    }
+    /**
+     * The latitude of the point in degrees, i.e. the y-coordinate.
+     *
+     * Values outside the range will be clamped to the poles.
+     *
+     * @minimum -90
+     * @maximum 90
+     */
+    get latitude() {
+        return this.#latitude;
+    }
+    set latitude(value) {
+        this.#latitude = clampLatitude(value);
+    }
+    /**
+     * The altitude of the point, i.e. the z-coordinate.
+     *
+     * This is optional and is typically measured in meters.
+     */
+    get altitude() {
+        return this.#altitude;
+    }
+    set altitude(value) {
+        this.#altitude = value;
+    }
+    constructor(input, bbox) {
+        if (isCoordPairLiteral(input)) {
+            if (input.length === 2) {
+                this.coordinates = inferGeoJSONCoordOrder(input);
+            }
+            else {
+                this.coordinates = input;
+            }
+        }
+        else if (isPointLiteral(input)) {
+            this.coordinates = [...input.coordinates];
+            if (isBBox(input.bbox)) {
+                this.bbox = [...input.bbox];
+            }
+        }
+        else if (isGoogleMapsLatLngLiteral(input)) {
+            this.coordinates = [input.lng, input.lat];
+        }
+        else if (isGeolocationCoordinatesLike(input)) {
+            this.#longitude = input.longitude;
+            this.#latitude = input.latitude;
+            this.#altitude = input.altitude || 0;
+        }
+        else if (isInterpolatedCoordinates(input)) {
+            this.#longitude = input.x;
+            this.#latitude = input.y;
+            this.#altitude = 0;
+        }
+        else {
+            this.coordinates = [0, 0];
+        }
+        if (isBBox(bbox)) {
+            this.bbox = bbox;
+        }
+    }
+    /**
+     * Attempts to create a new GeoPoint instance from the given input.
+     */
+    static from(input) {
+        if (!input)
+            return null;
+        if (input instanceof GeoPoint)
+            return input;
+        if (typeof input === "string") {
+            const coordinates = tryParsingJSON(input) || tryParsingJSON(`[${input}]`);
+            if (coordinates) {
+                input = coordinates;
+            }
+        }
+        try {
+            const point = new GeoPoint(input);
+            if (point.isNullIsland())
+                return null;
+            return point;
+        }
+        catch (_error) {
+            return null;
+        }
+    }
+    //#endregion
+    //#region Predicates
+    /**
+     * Whether the GeoPoint is 2-dimensional.
+     */
+    is2D() {
+        return !this.is3D();
+    }
+    /**
+     * Whether the GeoPoint is 3-dimensional.
+     */
+    is3D() {
+        return this.#altitude !== 0;
+    }
+    /**
+     * Whether the GeoPoint is the null island at 0, 0.
+     */
+    isNullIsland() {
+        return this.#latitude === 0 && this.#longitude === 0;
+    }
+    //#endregion
+    //#region Conversion
+    toJSON() {
+        return {
+            type: this.type,
+            coordinates: this.coordinates,
+        };
+    }
+    to2DCoordinates() {
+        return [this.#longitude, this.#latitude];
+    }
+    to3DCoordinates() {
+        return [this.#longitude, this.#latitude, this.#altitude];
+    }
+    /**
+     * Converts the GeoPoint to a Google Maps API {@linkcode google.LatLngLiteral | LatLngLiteral}
+     * object.
+     */
+    toGoogleLatLngLiteral() {
+        return {
+            lat: this.#latitude,
+            lng: this.#longitude,
+        };
+    }
+    /**
+     * Converts the GeoPoint to DMS (Degrees, Minutes, Seconds) format.
+     */
+    toDMS() {
+        const converter = convertCoords(`${this.#latitude},${this.#longitude}`);
+        return converter.toCoordinateFormat("DMS");
+    }
+    /**
+     * Converts the GeoPoint to a H3 short cell address.
+     */
+    toH3Cell(resolution = 15) {
+        const cell = latLngToCell(this.#latitude, this.#longitude, resolution);
+        return cell;
+    }
+    /**
+     * Converts the GeoPoint to a H3 short cell address.
+     */
+    toH3ShortCell(resolution = 15) {
+        const cell = this.toH3Cell(resolution);
+        return shortenH3Cell(cell);
+    }
+    toString() {
+        return JSON.stringify(this.toJSON());
+    }
+    //#endregion
+    [Symbol.iterator]() {
+        return this.coordinates[Symbol.iterator]();
+    }
+}
+//# sourceMappingURL=point.js.map

package/out/geometries/point.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"point.js","sourceRoot":"","sources":["../../geometries/point.ts"],"names":[],"mappings":"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"}

package/out/geometries/polygon.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import type { GeoObjectLiteral } from "../objects.js";
+import type { LineStringPath } from "./line-string.js";
+/**
+ * An array of positions forming a closed shape, such as a country or a lake.
+ *
+ * @example
+ *
+ * A polygon without holes:
+ *
+ * ```json
+ * {
+ * 	"type": "Polygon",
+ * 	"coordinates": [
+ * 		[
+ * 			[100, 0],
+ * 			[101, 0],
+ * 			[101, 1],
+ * 			[100, 1],
+ * 			[100, 0]
+ * 		]
+ * 	]
+ * }
+ * ```
+ */
+export type SolidPolygonPath = [
+    /**
+     * - A linear ring is a closed LineString with four or more positions.
+     * - The first and last positions are equivalent (they represent equivalent points).
+     */
+    exteriorRing: LineStringPath
+];
+/**
+ * An array of positions forming a closed shape with holes, such as a country with islands or a lake
+ * with islands.
+ *
+ * @example
+ *
+ * A polygon with holes:
+ *
+ * ```json
+ * {
+ * 	"type": "Polygon",
+ * 	"coordinates": [
+ * 		[
+ * 			[100.0, 0.0],
+ * 			[101.0, 0.0],
+ * 			[101.0, 1.0],
+ * 			[100.0, 1.0],
+ * 			[100.0, 0.0]
+ * 		],
+ * 		[
+ * 			[100.8, 0.8],
+ * 			[100.8, 0.2],
+ * 			[100.2, 0.2],
+ * 			[100.2, 0.8],
+ * 			[100.8, 0.8]
+ * 		]
+ * 	]
+ * }
+ * ```
+ */
+export type NestedPolygonPath = [
+    /**
+     * - A linear ring is a closed LineString with four or more positions.
+     * - The first and last positions are equivalent (they represent equivalent points).
+     */
+    exteriorRing: LineStringPath,
+    /**
+     * - The interior rings are arrays of positions forming holes in the polygon.
+     */
+    ...interiorRings: LineStringPath[]
+];
+/**
+ * A polygon geometry.
+ *
+ * @see {@linkcode PolygonLiteral} for applicable JSON schema.
+ * @see {@linkcode SolidPolygonPath} for more information.
+ * @see {@linkcode NestedPolygonPath} for more information.
+ */
+export type PolygonPath = SolidPolygonPath | NestedPolygonPath;
+/**
+ * An array of positions forming a closed shape, such as a country or a lake.
+ */
+export interface PolygonLiteral<P extends PolygonPath = SolidPolygonPath> extends GeoObjectLiteral {
+    /**
+     * Declares the type of GeoJSON object as a `Polygon` geometry.
+     */
+    type: "Polygon";
+    /**
+     * An array of positions for each point in the geometry.
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6 | RFC 7946 Section 3.1.6}
+     * @see {@linkcode SolidPolygonPath}
+     * @see {@linkcode NestedPolygonPath}
+     */
+    coordinates: P;
+}
+/**
+ * Predicate for checking if a GeoJSON object is a `Polygon` geometry.
+ */
+export declare function isPolygonLiteral<P extends PolygonPath = PolygonPath>(input: unknown): input is PolygonLiteral<P>;
+/**
+ * Predicate for checking if a polygon geometry is a solid, i.e. it has no holes.
+ */
+export declare function isSolidPolygonPath(input: PolygonLiteral): boolean;
+/**
+ * A collection of polygons, such as a country with islands or a lake with islands.
+ */
+export interface MultiPolygonLiteral<P extends PolygonPath = SolidPolygonPath> extends GeoObjectLiteral {
+    type: "MultiPolygon";
+    /**
+     * An array of polygons.
+     */
+    coordinates: P[][];
+}
+/**
+ * Predicate for checking if a GeoJSON object is a `MultiPolygon` geometry.
+ */
+/**
+ * Given a polygon geometry, return an OSM filter string.
+ *
+ * This is useful when working with the Overpass API.
+ */
+export declare function polygonToOSMFilter(input: PolygonLiteral): string;
+/**
+ * Tags returned by the Overpass API for a node.
+ *
+ * @category OSM
+ */
+export declare enum OSMNodeTag {
+    HouseNumber = "addr:housenumber",
+    PostCode = "addr:postcode",
+    Street = "addr:street",
+    State = "addr:state",
+    City = "addr:city",
+    Website = "website",
+    Email = "email",
+    Phone = "phone",
+    Shop = "shop",
+    Brand = "brand",
+    Cuisine = "cuisine",
+    Name = "name",
+    Healthcare = "healthcare",
+    Office = "office",
+    Amenity = "amenity"
+}
+export declare const ForbiddenResidentialOSMNodeTags: ReadonlySet<OSMNodeTag>;
+export type OSMNodeTagRecord = Record<OSMNodeTag, string | undefined>;
+export interface OSMOverpassElement {
+    type: "node";
+    id: number;
+    lat: number;
+    lon: number;
+    tags: OSMNodeTagRecord;
+}
+export interface OSMOverpassResponseBody {
+    version: string;
+    generator: string;
+    osm3s: {
+        timestamp_osm_base: string;
+        copyright: string;
+    };
+    elements: OSMOverpassElement[];
+}
+/**
+ * Given an OSM element, attempts to infer if the result is a residential address.
+ */
+export declare function isResidentialElement(element: OSMOverpassElement): boolean;
+export declare function fetchOSMElementViaOverpassAPI(input: PolygonLiteral): Promise<OSMOverpassElement[]>;
+//# sourceMappingURL=polygon.d.ts.map

package/out/geometries/polygon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polygon.d.ts","sourceRoot":"","sources":["../../geometries/polygon.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B;;;OAGG;IACH,YAAY,EAAE,cAAc;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC/B;;;OAGG;IACH,YAAY,EAAE,cAAc;IAC5B;;OAEG;IACH,GAAG,aAAa,EAAE,cAAc,EAAE;CAClC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,iBAAiB,CAAA;AAE9D;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,WAAW,GAAG,gBAAgB,CAAE,SAAQ,gBAAgB;IACjG;;OAEG;IACH,IAAI,EAAE,SAAS,CAAA;IACf;;;;;;OAMG;IACH,WAAW,EAAE,CAAC,CAAA;CACd;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAAC,CAAC,CAAC,CAIhH;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAEjE;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,WAAW,GAAG,gBAAgB,CAAE,SAAQ,gBAAgB;IACtG,IAAI,EAAE,cAAc,CAAA;IAEpB;;OAEG;IACH,WAAW,EAAE,CAAC,EAAE,EAAE,CAAA;CAClB;AACD;;GAEG;AAEH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAQhE;AAED;;;;GAIG;AACH,oBAAY,UAAU;IACrB,WAAW,qBAAqB;IAChC,QAAQ,kBAAkB;IAC1B,MAAM,gBAAgB;IACtB,KAAK,eAAe;IACpB,IAAI,cAAc;IAClB,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,KAAK,UAAU;IACf,IAAI,SAAS;IACb,KAAK,UAAU;IACf,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,UAAU,eAAe;IACzB,MAAM,WAAW;IACjB,OAAO,YAAY;CACnB;AAED,eAAO,MAAM,+BAA+B,EAAE,WAAW,CAAC,UAAU,CAMlE,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AAErE,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,gBAAgB,CAAA;CACtB;AAED,MAAM,WAAW,uBAAuB;IACvC,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE;QACN,kBAAkB,EAAE,MAAM,CAAA;QAC1B,SAAS,EAAE,MAAM,CAAA;KACjB,CAAA;IACD,QAAQ,EAAE,kBAAkB,EAAE,CAAA;CAC9B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAQzE;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAiBlG"}