@trackunit/react-map-adapter-shared 0.0.4-alpha-9d327375fc1.0

package/src/safeArea/safePolygon.d.ts

@@ -0,0 +1,36 @@
+import { type Point2D } from "./polygon";
+/**
+ * Filter `rects` to those on the "cursor side" of an opposing rect, preventing
+ * the safe-area polygon from extending into a corridor the cursor has clearly
+ * turned away from.
+ *
+ * For every pair of rects (R, S) in the input where the cursor is NOT inside R:
+ * if the cursor is on the opposite side of S from R (along the S→R axis,
+ * tested via the sign of `dot(cursor − centerS, centerR − centerS)`), R is
+ * dropped. Concretely: when cursor is at the entry-rect side of the marker and
+ * moving away from the floating live-rect (e.g. stick-marker pill), the live
+ * rect is dropped so the polygon does not include it. Rects the cursor is
+ * inside are always kept.
+ *
+ * Pure function. Returns the filtered list in the original order.
+ */
+export declare const filterRectsByCursorDirection: (rects: ReadonlyArray<DOMRect | null>, cursorX: number, cursorY: number) => ReadonlyArray<DOMRect | null>;
+/**
+ * Build a hover-safe convex-hull polygon spanning every input rect. Each
+ * non-null rect contributes its four corners (outward-buffered by `bufferPx`)
+ * and the result is the convex hull of all collected corners.
+ *
+ * Inspired by Floating UI's `safePolygon` middleware (used by `useHover` to
+ * keep menus open while the cursor travels toward them). The difference: that
+ * implementation builds a pointer-to-single-rect triangle for the standard
+ * trigger ↔ floating-element relationship; this one accepts an arbitrary list
+ * of rects so a single safe area can span N visible targets — e.g. a stick
+ * marker's pill at the tip, an entry-time snapshot of the same pill (used as
+ * an animation grace area), and the geographic anchor at the stick's base.
+ *
+ * The hull is angle-agnostic: it hugs the visible elements at any layout and
+ * naturally excludes the dead corners that an axis-aligned bounding box would
+ * include. Returns an empty polygon when no rects were provided; callers
+ * should treat that as "no safe area" (any cursor position is outside).
+ */
+export declare const safePolygon: (rects: ReadonlyArray<DOMRect | null>, bufferPx: number) => ReadonlyArray<Point2D>;

package/src/safeArea/watchSafeAreaLeave.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Generate a unique id for one active hover instance. Exposed so callers that
+ * orchestrate multiple watchers (e.g. {@link ./attachSafeAreaHoverListeners})
+ * can pre-allocate one id and pass it in, so the debug overlay shows a single
+ * polygon entry across the listener's lifecycle.
+ */
+export declare const allocSafeAreaDebugId: (label: string) => string;
+/**
+ * Listen for genuine pointer departure from a DOM marker's safe area. The
+ * watcher consults `getHitSurfaceRect` on every pointermove; when the inner
+ * query returns nothing transiently (mid-mount, mid-collapse), it falls back
+ * to the most recent non-empty rect seen.
+ *
+ * `entryRect` is the hit-surface rect captured at `mouseenter` time. It acts
+ * as a second stable reference so that when the element animates away from a
+ * stationary cursor (e.g. stick marker expanding from anchor to tip), the
+ * watcher does not fire `onLeave` while the cursor is still inside the
+ * original entry area.
+ *
+ * Returns a cancel function. Caller is responsible for invoking it on
+ * hover-end and on cleanup.
+ */
+export declare const watchSafeAreaLeave: (host: HTMLElement, onLeave: () => void, entryRect?: DOMRect | null, debugId?: string) => (() => void);

package/src/shapeStyleDefaults.d.ts

@@ -0,0 +1,45 @@
+import type { MapTheme } from "./primitiveMapTypes";
+import type { ShapeType } from "./interactionTypes";
+import type { ShapeStyle, ShapeStyleOverrides } from "./layerApiTypes";
+export declare const SHAPE_STYLE_DEFAULTS: {
+    readonly polygon: {
+        readonly fillOpacity: 0.05;
+        readonly strokeWidth: 1;
+        readonly strokeOpacity: 1;
+    };
+    readonly line: {
+        readonly strokeWidth: 1;
+        readonly strokeOpacity: 1;
+    };
+    readonly point: {
+        readonly fillOpacity: 0.2;
+        readonly strokeWidth: 1;
+        readonly strokeOpacity: 1;
+        readonly pointRadius: 5;
+    };
+};
+/**
+ * Resolve the visual style for a hovered shape.
+ *
+ * User-provided `base.hovered` overrides take priority; missing properties
+ * fall back to auto-computed defaults (darkened/lightened stroke based on theme).
+ */
+export declare const resolveHoveredStyle: (base: ShapeStyle, _shapeType: ShapeType, theme: MapTheme) => ShapeStyleOverrides;
+/**
+ * Resolve the visual style for a selected shape.
+ *
+ * User-provided `base.selected` overrides take priority; missing properties
+ * fall back to auto-computed defaults (darkened/lightened stroke based on theme,
+ * stronger shift than hover).
+ */
+export declare const resolveSelectedStyle: (base: ShapeStyle, _shapeType: ShapeType, theme: MapTheme) => ShapeStyleOverrides;
+/**
+ * Returns the base, hovered, and selected stroke colors for a shape in one call.
+ * Backed by the module-level color cache in colorUtils, so repeated calls with
+ * the same inputs are cheap Map lookups.
+ */
+export declare const resolveStrokeColors: (style: ShapeStyle, shapeType: ShapeType, theme: MapTheme) => Readonly<{
+    base: string;
+    hovered: string;
+    selected: string;
+}>;

package/src/types.d.ts

@@ -0,0 +1,68 @@
+import type { GeoJsonBbox } from "@trackunit/geo-json-utils";
+import type { AdapterRendererProps } from "./adapterContract";
+import type { InitialViewport, MapTheme } from "./primitiveMapTypes";
+type CSSProperties = import("react").CSSProperties;
+type ReactNode = import("react").ReactNode;
+/**
+ * Unified coordinate format used by both adapters
+ * Since these are objects (not tuples), property order doesn't matter in TypeScript
+ */
+export type MapCoordinates = Readonly<{
+    lat: number;
+    lng: number;
+}>;
+/**
+ * Base adapter configuration shared by all adapters
+ * Each adapter extends this with their specific authentication/config
+ */
+export type BaseAdapterConfig = Readonly<{
+    /** Language for map labels */
+    language?: string;
+    /**
+     * Region code (ISO 3166-1 alpha-2) that controls how disputed borders and territories
+     * are rendered. For example, setting `"MA"` displays Western Sahara as part of Morocco.
+     *
+     * - Google Maps: passed as the `region` parameter to the Maps JavaScript API.
+     * - Mapbox: passed as the `worldview` option to the Mapbox GL JS map constructor.
+     *
+     * When omitted, each provider uses its default (typically an international/neutral view).
+     *
+     * @see https://developers.google.com/maps/documentation/javascript/localization
+     */
+    region?: string;
+    /** Map theme - light or dark */
+    theme?: MapTheme;
+    /** Initial viewport: either center+zoom or bounds */
+    initialViewport?: InitialViewport;
+    /**
+     * Bounds to restrict panning/zoom. GeoJSON format: [minLng, minLat, maxLng, maxLat].
+     * - `undefined` (default): no restriction (infinite horizontal scroll)
+     * - `null`: no restriction (infinite horizontal scroll)
+     * - `GeoJsonBbox`: restrict to custom region (e.g. Europe only)
+     * Invalid bboxes are validated with geoJsonBboxSchema; on failure, console.warn is emitted
+     * and null (no restriction) is used as fallback.
+     */
+    restrictBounds?: GeoJsonBbox | null;
+}>;
+/**
+ * Base renderer internal props shared by all adapter renderers
+ * Each adapter extends this with their specific props (like accessToken, apiKey, etc.)
+ */
+export type BaseRendererInternalProps = Readonly<{
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    "data-testid"?: string;
+    "aria-label"?: string;
+    "aria-describedby"?: string;
+    theme: MapTheme;
+    initialViewport?: InitialViewport;
+}>;
+/**
+ * Helper type to create adapter-specific renderer props
+ * Combines AdapterRendererProps with BaseRendererInternalProps
+ */
+export type AdapterSpecificRendererProps<TAdapterInstance> = Readonly<AdapterRendererProps & BaseRendererInternalProps & {
+    adapterInstance: TAdapterInstance;
+}>;
+export {};