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

package/src/layers/useMarkers/adaptiveHelpers.d.ts

@@ -0,0 +1,156 @@
+import { type AdaptiveResolutionContext, type CircleSymbolDescriptor, type RenderMedium } from "@trackunit/react-map-adapter-shared";
+import type { MapTheme } from "../../core/types";
+import type { MarkerDomSize } from "../../markers/model/markerDomTypes";
+/**
+ * Tunables for {@link pickRenderMedium}. All optional — sensible defaults are
+ * documented inline.
+ */
+export type PickRenderMediumOptions = Readonly<{
+    /**
+     * If `markersInViewport` exceeds this, the helper returns `"symbol"` even
+     * when selected/hovered promotion does not apply. Keeps DOM marker counts
+     * bounded so layout cost stays low.
+     *
+     * @default 200
+     */
+    maxMarkersForDom?: number;
+    /**
+     * When `true`, the helper short-circuits to `"dom"` whenever a marker is
+     * hovered or selected, so the rich DOM form is always available for
+     * interaction even outside the density envelope.
+     *
+     * @default true
+     */
+    domMediumOnInteraction?: boolean;
+}>;
+/**
+ * Default heuristic for `AdaptiveRenderConfig.resolveMode` (ADR-0009).
+ *
+ * Returns `"dom"` when the marker is interacted with (hover/select) or when
+ * the viewport is not over-dense; otherwise `"symbol"`. Pure — no React, no
+ * allocation per call.
+ *
+ * Consumers use this directly:
+ *
+ * ```ts
+ * resolveMode: (_item, ctx) => pickRenderMedium(ctx)
+ * ```
+ *
+ * Or tune thresholds:
+ *
+ * ```ts
+ * resolveMode: (_item, ctx) =>
+ *   pickRenderMedium(ctx, { maxMarkersForDom: 80 })
+ * ```
+ *
+ * The library does not impose this heuristic — `resolveMode` always wins. The
+ * helper is a documented starting point for the common case (Q6 of the
+ * design grilling).
+ */
+export declare const pickRenderMedium: (ctx: AdaptiveResolutionContext, options?: PickRenderMediumOptions) => RenderMedium;
+/**
+ * Single zoom→size step. The helper picks the breakpoint with the highest
+ * `minZoom` that is still `<= ctx.zoom`.
+ */
+export type MarkerSizeBreakpoint = Readonly<{
+    /** Zoom at or above which this size applies. */
+    minZoom: number;
+    /** Size to use once `ctx.zoom >= minZoom`. */
+    size: MarkerDomSize;
+}>;
+/**
+ * Tunables for {@link pickMarkerSize}.
+ */
+export type PickMarkerSizeOptions = Readonly<{
+    /**
+     * Zoom→size ladder, sorted ascending by `minZoom`. The last breakpoint with
+     * `minZoom <= ctx.zoom` wins. If `ctx.zoom` is below every breakpoint, the
+     * first breakpoint's `size` is returned (the smallest tier acts as the
+     * floor).
+     *
+     * @default DEFAULT_MARKER_SIZE_BREAKPOINTS
+     */
+    breakpoints?: ReadonlyArray<MarkerSizeBreakpoint>;
+}>;
+/**
+ * Five-tier zoom ladder matching the `MapMarker` `size` prop. The chosen
+ * thresholds align with how the existing demos read at typical fleet zooms
+ * (city → asset → street).
+ */
+export declare const DEFAULT_MARKER_SIZE_BREAKPOINTS: ReadonlyArray<MarkerSizeBreakpoint>;
+/**
+ * Default zoom→`MarkerDomSize` mapping for the DOM branch of an adaptive
+ * `render`.
+ *
+ * Pure. Iterates the breakpoint ladder once and picks the largest `minZoom`
+ * still satisfied by `ctx.zoom`. The breakpoint list must be sorted ascending
+ * by `minZoom`; the helper does not sort defensively because it runs per
+ * marker per frame.
+ *
+ * ```ts
+ * <MapMarker size={pickMarkerSize(ctx)} ... />
+ * ```
+ *
+ * Consumers can tune the ladder for denser or sparser maps:
+ *
+ * ```ts
+ * pickMarkerSize(ctx, {
+ *   breakpoints: [
+ *     { minZoom: 0, size: "xs" },
+ *     { minZoom: 10, size: "md" },
+ *     { minZoom: 14, size: "xl" },
+ *   ],
+ * })
+ * ```
+ */
+export declare const pickMarkerSize: (ctx: AdaptiveResolutionContext, options?: PickMarkerSizeOptions) => MarkerDomSize;
+/**
+ * Tunables for {@link pickSymbolDiameter}. The same ladder shape as
+ * {@link pickMarkerSize} so `mode: "adaptive"` consumers can share one
+ * options object across both branches.
+ */
+export type PickSymbolDiameterOptions = PickMarkerSizeOptions;
+/**
+ * Symbol counterpart of {@link pickMarkerSize}: returns a `diameterPx` that
+ * matches the `MapMarker` `circle` dimension at the same zoom-derived tier
+ * (`MARKER_SIZE_MAP`). Use it inside the symbol arm of an adaptive `render`
+ * so the WebGL/canvas dot is the same physical size as the DOM circle the
+ * marker is about to morph into.
+ *
+ * ```ts
+ * if (state.medium === "symbol") {
+ *   return { color, diameterPx: pickSymbolDiameter(ctx) };
+ * }
+ * ```
+ *
+ * Pure; defers entirely to {@link pickMarkerSize} for the tier decision.
+ */
+export declare const pickSymbolDiameter: (ctx: AdaptiveResolutionContext, options?: PickSymbolDiameterOptions) => number;
+/**
+ * Width of the disc border drawn on DOM markers (Tailwind `border` = 1 px).
+ * Shared by {@link pickSymbolDescriptor} so DOM and symbol layers stay in sync.
+ */
+export declare const MARKER_DISC_BORDER_WIDTH_PX = 1;
+/**
+ * Full symbol descriptor for adaptive symbol markers.
+ *
+ * Symbol markers intentionally stay at the `xs` footprint to keep dense-map
+ * rendering stable while zooming. We still compute `diameterPx` via
+ * {@link pickSymbolDiameter} so the actual pixel value is sourced from the same
+ * `MARKER_SIZE_MAP` as DOM markers.
+ *
+ * Also derives `borderColor`
+ * from the same `color-mix()` formula used by `cvaMarkerIndicator` in CSS:
+ * - **light**: darken the fill by 30% (mix with black)
+ * - **dark**: lighten the fill by 50% (mix with white)
+ *
+ * Use this instead of the manual `{ color, diameterPx: pickSymbolDiameter(ctx) }`
+ * when you want the symbol circle and the DOM disc to look identical:
+ *
+ * ```ts
+ * if (state.medium === "symbol") {
+ *   return pickSymbolDescriptor(color, theme, sizingCtx);
+ * }
+ * ```
+ */
+export declare const pickSymbolDescriptor: (color: string, theme: MapTheme, ctx: AdaptiveResolutionContext) => CircleSymbolDescriptor;

package/src/layers/useMarkers/resolveServerClusters.d.ts

@@ -0,0 +1,26 @@
+import type { ClusterConfig, ResolutionContext } from "../types";
+type ServerClusterConfig<TCluster> = Extract<ClusterConfig<TCluster>, {
+    mode: "server";
+}>;
+/** Subset of {@link ResolutionContext} that callers supply from map state. */
+export type ViewportResolutionContext = Readonly<Pick<ResolutionContext, "zoom" | "markersInViewport" | "viewportBounds">>;
+/**
+ * Applies `resolveGroups` entity-shape decisions to a server cluster list.
+ *
+ * Per ADR-0016: expand-only resolution. Each cluster gets a `memberItems`
+ * cross-reference from `data` via `getId`/`getMarkerIds`. `"expand"` with
+ * non-null `memberItems` drops the cluster from the kept set; `"expand"` with
+ * null `memberItems` (any member missing from the data index) silently falls
+ * back to `"keep"`.
+ *
+ * `viewportCtx` carries live map state (zoom, density, bounds). When omitted
+ * all three default to zero/null — pass it from the consumer's map state so
+ * `resolveGroups` callbacks receive real values.
+ *
+ * Pure function — no hooks, safe to call inside `useMemo`.
+ */
+export declare const resolveServerClusters: <TItem, TCluster>(cluster: ServerClusterConfig<TCluster>, data: ReadonlyArray<TItem>, getId: (item: TItem) => string, resolveGroups: (cluster: TCluster, memberItems: ReadonlyArray<TItem> | null, ctx: ResolutionContext) => "keep" | "expand", viewportCtx?: ViewportResolutionContext) => Readonly<{
+    data: ReadonlyArray<TCluster>;
+    memberItems: ReadonlyMap<string, ReadonlyArray<TItem> | null>;
+}>;
+export {};

package/src/layers/useMarkers/useAdaptiveMarkerHelpers.d.ts

@@ -0,0 +1,38 @@
+import { resolveMapMarkerDomPortalStacking } from "../../markers/model/mapMarkerDomPortalStacking";
+import { resolveAdaptiveMarkerState } from "../../markers/model/markerResolvers";
+import { downgradeMarkerDomSize, upgradeMarkerDomSize } from "../../markers/model/markerSizeMap";
+import { DEFAULT_MARKER_SIZE_BREAKPOINTS, MARKER_DISC_BORDER_WIDTH_PX, pickMarkerSize, pickRenderMedium, pickSymbolDescriptor, pickSymbolDiameter } from "./adaptiveHelpers";
+export type AdaptiveMarkerHelpers = Readonly<{
+    pickMarkerSize: typeof pickMarkerSize;
+    pickRenderMedium: typeof pickRenderMedium;
+    pickSymbolDescriptor: typeof pickSymbolDescriptor;
+    pickSymbolDiameter: typeof pickSymbolDiameter;
+    resolveAdaptiveMarkerState: typeof resolveAdaptiveMarkerState;
+    downgradeMarkerDomSize: typeof downgradeMarkerDomSize;
+    upgradeMarkerDomSize: typeof upgradeMarkerDomSize;
+    resolveMapMarkerDomPortalStacking: typeof resolveMapMarkerDomPortalStacking;
+    DEFAULT_MARKER_SIZE_BREAKPOINTS: typeof DEFAULT_MARKER_SIZE_BREAKPOINTS;
+    MARKER_DISC_BORDER_WIDTH_PX: typeof MARKER_DISC_BORDER_WIDTH_PX;
+}>;
+/**
+ * Build-your-own hook: stable references to the full adaptive marker kit.
+ *
+ * Returns the complete set of primitives needed to hand-roll an adaptive marker
+ * layer (DOM ↔ symbol mode switching, zoom-based sizing, portal stacking) while
+ * staying consistent with `useMarkers`'s built-in rendering pipeline.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   pickRenderMedium, pickMarkerSize, pickSymbolDescriptor,
+ *   resolveAdaptiveMarkerState, resolveMapMarkerDomPortalStacking,
+ * } = useAdaptiveMarkerHelpers();
+ *
+ * // Inside your adaptive render callback:
+ * const medium = pickRenderMedium(ctx);
+ * if (medium === "symbol") return pickSymbolDescriptor(color, theme, ctx);
+ * const size  = pickMarkerSize(ctx);
+ * const state = resolveAdaptiveMarkerState({ selected, hovered });
+ * ```
+ */
+export declare const useAdaptiveMarkerHelpers: () => AdaptiveMarkerHelpers;

package/src/layers/useMarkers/useMarkers.d.ts

@@ -0,0 +1,127 @@
+import { type GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { ControlConfig } from "../../controls/types";
+import type { ClusterConfig, ClusterInfo, ClusterRenderConfig, FitParticipation, MarkerLayerHandle, RenderConfig, ResolutionContext } from "../types";
+import { type ViewportResolutionContext } from "./resolveServerClusters";
+/**
+ * Options for the `useMarkers` hook.
+ *
+ * Two generics, both inferred from usage:
+ * - `TItem` from `data`
+ * - `TCluster` from `cluster.data` (server-side) or defaults to `ClusterInfo` (client-side / no clustering)
+ */
+export type UseMarkersOptions<TItem, TCluster = ClusterInfo> = Readonly<{
+    /** Unique ID for this layer */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Source data array */
+    data: ReadonlyArray<TItem>;
+    /** Extract position from item. Return null for items without position. */
+    getPosition: (item: TItem) => GeoJsonPosition | null;
+    /** Extract unique ID from item */
+    getId: (item: TItem) => string;
+    /**
+     * Clustering strategy. Omit to disable clustering.
+     * - mode: "client" -- adapter clusters for you (Mapbox native, Supercluster, etc.)
+     * - mode: "server" -- clusters are pre-computed, TCluster inferred from cluster.data
+     */
+    cluster?: ClusterConfig<TCluster>;
+    /** How markers are rendered (symbol, dom, or adaptive) */
+    markerRender: RenderConfig<TItem>;
+    /**
+     * How clusters are rendered. Only relevant when `cluster` is provided.
+     * For server-side clusters, the render function receives the full TCluster.
+     * For client-side clusters, it receives ClusterInfo (adapter-produced).
+     *
+     * Per ADR-0016, the render callback's second argument is
+     * `ClusterRenderState<TItem>` carrying `memberItems` cross-referenced from
+     * `data` (DOM mode only — symbol mode receives `memberItems: null`).
+     */
+    clusterRender?: ClusterRenderConfig<TCluster, TItem>;
+    /** Optional controls to contribute to the map UI */
+    controls?: ReadonlyArray<ControlConfig>;
+    /** Whether the layer is currently loading its initial data. Omit for static (non-loading) layers. */
+    loading?: boolean;
+    /** Controls whether this layer's bounds are included in fit-to-content operations. Default: `"all"` */
+    fitParticipation?: FitParticipation;
+    /**
+     * Per-cluster entity-shape decision (ADR-0016).
+     *
+     * Called per server cluster with `memberItems` cross-referenced from `data`
+     * via `getMarkerIds`. `memberItems` is `null` when any member ID is missing
+     * from the `data` index — in that case `"expand"` silently falls back to
+     * `"keep"`. Omit to leave existing behaviour unchanged.
+     *
+     * Expansion is expand-only (`TCluster` is preserved); the cluster feature
+     * is removed when `"expand"` is returned with non-null `memberItems`. Member
+     * features are not synthesized by the hook — they appear in the marker
+     * feature collection because the consumer keeps the corresponding items in
+     * `data` (the optimistic-fetch pattern described in ADR-0016).
+     */
+    resolveGroups?: (cluster: TCluster, memberItems: ReadonlyArray<TItem> | null, ctx: ResolutionContext) => "keep" | "expand";
+    /**
+     * Live map state forwarded to every `resolveGroups` call.
+     *
+     * When omitted, `zoom`, `markersInViewport`, and `viewportBounds` default
+     * to `0`, `0`, and `null`. Provide this whenever `resolveGroups` is used so
+     * the callback receives real viewport signals instead of zeros.
+     */
+    resolutionContext?: ViewportResolutionContext;
+}>;
+/**
+ * Return type of `useMarkers`.
+ * Extends `MarkerLayerHandle` with convenience count properties.
+ */
+export interface UseMarkersReturn extends MarkerLayerHandle {
+    /** All positioned items (excludes items where getPosition returned null) */
+    readonly positionedCount: number;
+    /** Total items including unpositioned */
+    readonly totalCount: number;
+    /** Number of clusters (0 when clustering is disabled or data is empty) */
+    readonly clusterCount: number;
+}
+/**
+ * `useMarkers` -- creates a marker layer handle from arbitrary data.
+ *
+ * Generic over:
+ * - `TItem`: the data item type (inferred from `data`)
+ * - `TCluster`: the cluster data type (inferred from `cluster.data` for server-side,
+ *   defaults to `ClusterInfo` for client-side or no clustering)
+ *
+ * @example
+ * ```tsx
+ * // Server-side clusters with adaptive rendering: high-importance assets
+ * // are promoted to DOM while the rest stay as fast WebGL symbols.
+ * const fleet = useMarkers({
+ *   id: "fleet",
+ *   name: "Fleet Assets",
+ *   data: assets,
+ *   getPosition: (a) => a.location,
+ *   getId: (a) => a.id,
+ *   cluster: {
+ *     mode: "server",
+ *     data: serverClusters,
+ *     getPosition: (c) => c.center,
+ *     getId: (c) => c.clusterId,
+ *     getMarkerIds: (c) => c.assetIds,
+ *     getCount: (c) => c.count,
+ *     getBbox: (c) => c.bbox,
+ *   },
+ *   markerRender: {
+ *     mode: "adaptive",
+ *     anchor: "center",
+ *     resolveMode: (a) => (a.importance >= 8 ? "dom" : "symbol"),
+ *     render: (a, state) => {
+ *       if (state.medium === "symbol") return { color: statusColor(a.status) };
+ *       return <AssetMarker asset={a} selected={state.selected} />;
+ *     },
+ *   },
+ *   clusterRender: {
+ *     mode: "dom",
+ *     anchor: "center",
+ *     render: (cluster, state) => <ClusterBubble cluster={cluster} />,
+ *   },
+ * });
+ * ```
+ */
+export declare const useMarkers: <TItem, TCluster = ClusterInfo>(options: UseMarkersOptions<TItem, TCluster>) => UseMarkersReturn;

package/src/layers/useShapes/InteractiveDecoration.d.ts

@@ -0,0 +1,23 @@
+import { ReactNode } from "react";
+import type { Entity, ShapeEntity } from "@trackunit/react-map-adapter-shared";
+type InteractiveDecorationProps = Readonly<{
+    entity: ShapeEntity;
+    select: (entity: Entity | null) => void;
+    hover: (entity: Entity | null) => void;
+    onClick?: (entity: ShapeEntity) => void;
+    onDblClick?: (entity: ShapeEntity) => void;
+    onHover?: (entity: ShapeEntity | null) => void;
+    children: ReactNode;
+}>;
+/**
+ * Uniform interactive wrapper for shape decorations.
+ *
+ * Renders a visually-transparent `<button>` that provides cursor, keyboard
+ * activation, focus-visible ring, and ARIA semantics. Click dispatches entity
+ * selection, mouseenter/mouseleave dispatches entity hover — both followed
+ * by optional supplementary callbacks.
+ *
+ * @internal
+ */
+export declare const InteractiveDecoration: ({ entity, select, hover, onClick, onDblClick, onHover, children, }: InteractiveDecorationProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/src/layers/useShapes/MultiGeometryPlusBadge.d.ts

@@ -0,0 +1,17 @@
+type MultiGeometryPlusBadgeProps = Readonly<{
+    size: number;
+    color: string;
+    /** Stroke color for the cross. Defaults to `"white"`. */
+    plusColor?: string;
+    className?: string;
+    "data-testid"?: string;
+    title?: string;
+    "aria-label"?: string;
+}>;
+/**
+ * Compact circular "+" badge for multi-part GeoJSON geometries.
+ *
+ * @internal
+ */
+export declare const MultiGeometryPlusBadge: ({ size, color, plusColor, className, "data-testid": dataTestId, title, "aria-label": ariaLabel, }: MultiGeometryPlusBadgeProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/src/layers/useShapes/MultiPartBadge.d.ts

@@ -0,0 +1,11 @@
+type MultiPartBadgeProps = Readonly<{
+    color: string;
+}>;
+/**
+ * Badge rendered on each part of a multi-geometry feature on the map.
+ * Compact circular "+" matching `ShapeIcon`'s preview badge at 14px parent size.
+ *
+ * @internal
+ */
+export declare const MultiPartBadge: ({ color }: MultiPartBadgeProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/src/layers/useShapes/ShapeAnnotationLabel.d.ts

@@ -0,0 +1,30 @@
+import type { GeoJsonGeometry } from "@trackunit/geo-json-utils";
+import type { MapTheme } from "../../core/types";
+type ShapeAnnotationLabelProps = Readonly<{
+    geometry: GeoJsonGeometry | null;
+    color: string;
+    label: string;
+    theme: MapTheme;
+    /** True when the underlying shape is hovered on the map — darkens the pill to match edge-label hover style. */
+    isHovered?: boolean;
+    /** True when the underlying shape is selected on the map — darkens the pill more to match edge-label selected style. */
+    isSelected?: boolean;
+    onClick?: () => void;
+    onMouseEnter?: () => void;
+    onMouseLeave?: () => void;
+}>;
+/**
+ * Annotation-mode shape label shown in the `AnnotationStack` when
+ * the viewport is fully inside a shape and no edge is visible.
+ *
+ * Composes `ShapeLabelPill` with a `ShapeIcon` preview on the left
+ * to preserve the site's visual identity (color + geometry type icon)
+ * in the annotation chrome bar. When `onClick` is provided, a wrapping
+ * `<button>` handles interaction; pass `fitFeatureBounds` here to
+ * zoom-to-fit on click.
+ *
+ * Intended for use inside a `MapAnnotationDescriptor` with
+ * `type: "custom"` — see `useFleetSiteAnnotation` for the canonical usage.
+ */
+export declare const ShapeAnnotationLabel: ({ geometry, color, label, theme, isHovered, isSelected, onClick, onMouseEnter, onMouseLeave, }: ShapeAnnotationLabelProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/src/layers/useShapes/ShapeIcon.d.ts

@@ -0,0 +1,21 @@
+import type { GeoJsonGeometry } from "@trackunit/geo-json-utils";
+type ShapeIconProps = Readonly<{
+    geometry: GeoJsonGeometry | null;
+    color: string;
+    size: number;
+    /** Stroke width in pixels. When omitted, scales automatically with `size`. */
+    strokeWidth?: number;
+    /** Foreground color for the multi-badge plus. Defaults to `"white"`. */
+    badgeColor?: string;
+}>;
+/**
+ * Renders a miniature SVG preview of a GeoJSON geometry.
+ *
+ * For multi-geometries (MultiPolygon, MultiLineString, etc.), shows
+ * a "multi" badge in the top-right corner. The badge is absolutely
+ * positioned so it does not inflate the icon's layout dimensions.
+ *
+ * @internal
+ */
+export declare const ShapeIcon: ({ geometry, color, size, strokeWidth, badgeColor }: ShapeIconProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

package/src/layers/useShapes/ShapeLabelPill.d.ts

@@ -0,0 +1,25 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { MapTheme } from "../../core/types";
+type ShapeLabelPillProps = Readonly<{
+    color: string;
+    theme: MapTheme;
+    borderRadius: string;
+    className?: string;
+    style?: CSSProperties;
+    "data-testid"?: string;
+    children: ReactNode;
+}>;
+export declare const cvaShapeLabel: (props?: ({
+    theme?: "light" | "dark" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * Shared styled container for shape labels (edge labels and annotation labels).
+ *
+ * Always renders a `<div>` — interaction is handled externally by
+ * `InteractiveDecoration` (portal path) or a wrapping `<button>` in
+ * `ShapeAnnotationLabel` (annotation path).
+ *
+ * @internal
+ */
+export declare const ShapeLabelPill: ({ color, theme, borderRadius, className, style, "data-testid": dataTestId, children, }: ShapeLabelPillProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/src/layers/useShapes/buildShapeLabelResolutionContext.d.ts

@@ -0,0 +1,23 @@
+import { type GeoJsonBbox, type GeoJsonFeature } from "@trackunit/geo-json-utils";
+import type { MapInteractionState } from "@trackunit/react-map-adapter-shared";
+import type { ShapeLabelResolutionContext } from "./shapeLabelResolution";
+/**
+ * Build the per-feature, per-frame context passed to an `edge-auto` anchor's
+ * `resolveLabel` callback. Pure: no React, no `api` reads — caller supplies the
+ * already-projected viewport bits, the precomputed `shapesInViewport` count for
+ * the layer, and the current interaction state.
+ *
+ * Lives next to `shapeLabelResolution.ts` and is consumed by
+ * `useShapeDecorations` once per feature that has at least one `edge-auto`
+ * decoration, before any placement work runs.
+ */
+export declare const buildShapeLabelResolutionContext: (feature: GeoJsonFeature, args: Readonly<{
+    handleId: string;
+    featureKey: string;
+    viewportBounds: Readonly<GeoJsonBbox>;
+    zoom: number;
+    tileSize: number;
+    shapesInViewport: number;
+    overlappingShapesCount: number;
+    interaction: MapInteractionState;
+}>) => ShapeLabelResolutionContext | null;

package/src/layers/useShapes/decorationFactories.d.ts

@@ -0,0 +1,47 @@
+import type { Placement } from "@floating-ui/react";
+import type { ShapeEntity } from "@trackunit/react-map-adapter-shared";
+import type { RefCallback } from "react";
+import type { EdgeLabelAnchor, EdgeLabelPlacementResolver } from "./edge/findBestEdgePosition";
+import type { ShapeDecoration } from "./shapeDecorations";
+import type { ResolveShapeLabel } from "./shapeLabelResolution";
+/**
+ * Create an edge-auto decoration that places a flush label on the best visible
+ * edge of a polygon or line. Returns `undefined` when `label` is nullish, so
+ * it can be used directly in a `getDecorations` array and filtered automatically.
+ *
+ * @example
+ * ```tsx
+ * const zones = useShapes({
+ *   id: "zones",
+ *   features: zoneFeatureCollection,
+ *   resolveStyle: () => ({ stroke: "blue" }),
+ *   getDecorations: (f) => [
+ *     edgeLabel(f.properties?.name as string | undefined),
+ *   ],
+ * });
+ * ```
+ */
+export declare const edgeLabel: (label: string | undefined | null, options?: Readonly<{
+    interactive?: boolean;
+    onClick?: (entity: ShapeEntity) => void;
+    onHover?: (entity: ShapeEntity | null) => void;
+    resolveLabel?: ResolveShapeLabel;
+    labelAnchor?: EdgeLabelAnchor;
+    /**
+     * Custom placement resolver. When omitted, the default resolver is used.
+     * The resolver receives `context.isForced = true` on the forced retry pass
+     * (when no edge fit the label), allowing anchor or side changes without a
+     * separate option.
+     */
+    labelPlacementResolver?: EdgeLabelPlacementResolver;
+    /**
+     * Forwarded to `ShapeDecoration.panelAnchorRef`. The edge-label portal
+     * container element is passed to this callback so a panel can anchor to it.
+     */
+    panelAnchorRef?: RefCallback<HTMLElement>;
+    /**
+     * Forwarded to `ShapeDecoration.onEdgePlacement`. Called with the outward
+     * Floating UI `Placement` when the label is placed on an edge.
+     */
+    onEdgePlacement?: (placement: Placement) => void;
+}>) => ShapeDecoration | undefined;

package/src/layers/useShapes/edge/ShapeEdgeLabel.d.ts

@@ -0,0 +1,13 @@
+import type { MapTheme } from "../../../core/types";
+import type { EdgeFitMode, EdgeLabelLayout } from "./findBestEdgePosition";
+type ShapeEdgeLabelProps = Readonly<{
+    text: string;
+    color: string;
+    theme: MapTheme;
+    layout: EdgeLabelLayout;
+    fitMode: EdgeFitMode;
+    /** When true the label is invisible, waiting for its parent shape to finish rendering. */
+    hidden?: boolean;
+}>;
+export declare const ShapeEdgeLabel: ({ text, color, theme, layout, fitMode, hidden }: ShapeEdgeLabelProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/src/layers/useShapes/edge/computeEdgeAutoPlacement.d.ts

@@ -0,0 +1,69 @@
+import type { GeoJsonBbox, GeoJsonFeature, GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { MarkerAnchor } from "@trackunit/react-map-adapter-shared";
+import { type EdgeIdentity, type EdgeInsets, type EdgeLabelAnchor, type EdgeLabelPlacementResolver, type EdgePlacement } from "./findBestEdgePosition";
+/**
+ * Placement mode chosen by the caller (typically derived from a `resolveLabel`
+ * callback on the `edge-auto` anchor).
+ *
+ * - `"auto"` — only place when an edge fits the measured label width.
+ * - `"force"` — if no edge fits, retry with no width requirement so the best
+ *   available edge holds the label (may overflow visually).
+ *
+ * In both modes the label is hidden when the feature is entirely off-screen.
+ */
+export type EdgeAutoPlacementMode = "auto" | "force";
+export type EdgeAutoPlacementOptions = Readonly<{
+    /** Pixel width measurement callback for the label text. */
+    labelPixelWidth: (label: string) => number;
+    /** Max angle from horizontal for readable rotated text (degrees). */
+    maxReadableAngleDeg: number | undefined;
+    /** Previous edge identity for hysteresis — avoids label jumping during panning. */
+    previousEdgeIdentity: EdgeIdentity | undefined;
+    /** Previous point position for hysteresis — avoids MultiPoint label jumping during panning. */
+    previousPointPosition: GeoJsonPosition | undefined;
+    /**
+     * Geographic position of the previous anchor, for "don't slide back left" hysteresis.
+     * When provided, a left-anchored label will not retreat left once the viewport has
+     * pushed it rightward along the edge to stay in view.
+     */
+    previousAnchorGeo?: GeoJsonPosition;
+    /**
+     * The layout side ("above" | "below") from the previous frame.
+     * When provided, the label will not flip sides unless the current side
+     * no longer fits within the viewport.
+     */
+    previousLayoutSide?: "above" | "below";
+    /** Per-edge insets from shape decorations (e.g. corner badges) to avoid overlap. */
+    edgeInsets: ReadonlyArray<EdgeInsets> | undefined;
+    /** Where the label attaches along the selected edge. Defaults to `"left"`. */
+    labelAnchor?: EdgeLabelAnchor;
+    /** Custom placement resolver. When omitted, `defaultEdgeLabelPlacementResolver` is used. */
+    labelPlacementResolver?: EdgeLabelPlacementResolver;
+    /** Placement mode. Defaults to `"auto"`. */
+    mode?: EdgeAutoPlacementMode;
+}>;
+export type EdgeAutoPlacementOutcome = Readonly<{
+    type: "placed";
+    placement: EdgePlacement;
+    anchor: MarkerAnchor;
+}> | Readonly<{
+    type: "hidden";
+}>;
+/**
+ * Compute the best placement for a shape label.
+ *
+ * Centralizes layout decisions: geometry branching (Point vs polygon/line),
+ * pixel width estimation, edge-finding for non-point geometries, and
+ * placement-to-anchor mapping.
+ *
+ * Returns a discriminated outcome:
+ * - `"placed"` — label positioned on an edge with placement + anchor
+ * - `"hidden"` — shape is off-screen, no qualifying edge, or (mode `"auto"`) no
+ *   edge fits the label width
+ *
+ * Whether the viewport is fully inside the shape is no longer decided here —
+ * callers compute that as part of the `ShapeLabelResolutionContext` so the
+ * `resolveLabel` callback can react to it (e.g. hide, or fall back to a
+ * caller-managed annotation).
+ */
+export declare const computeEdgeAutoPlacement: (feature: GeoJsonFeature, label: string, viewportBounds: Readonly<GeoJsonBbox>, zoom: number, tileSize: number, options: EdgeAutoPlacementOptions) => EdgeAutoPlacementOutcome;

package/src/layers/useShapes/edge/computeEdgeProperties.d.ts

@@ -0,0 +1,21 @@
+import { type GeoJsonGeometry, type GeoJsonPosition } from "@trackunit/geo-json-utils";
+/**
+ * Computed properties injected into `sourceProperties` for all edge-* anchors.
+ * Render functions read these from the `item` argument via portal descriptors.
+ */
+export type EdgeComputedProperties = Readonly<{
+    /** Screen-space angle of the edge in degrees, normalized to [-90, 90]. */
+    angleDeg: number;
+    /** Which side of the edge faces away from the shape interior. "above" for LineStrings. */
+    outwardSide: "above" | "below";
+    /** Length of the edge in screen pixels at the current zoom level. */
+    edgePixelLength: number;
+}>;
+/**
+ * Compute edge-specific properties from resolved edge endpoints.
+ *
+ * For Polygons, `outwardSide` uses the cross product with the geometry centroid
+ * to determine which side faces away from the interior. For LineStrings (no
+ * interior), `outwardSide` defaults to `"above"`.
+ */
+export declare const computeEdgeProperties: (start: GeoJsonPosition, end: GeoJsonPosition, geometry: GeoJsonGeometry, zoom: number, tileSize: number) => EdgeComputedProperties;