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

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@trackunit/react-map",
+  "version": "0.0.4-alpha-9d327375fc1.0",
+  "repository": "https://github.com/Trackunit/manager",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "engines": {
+    "node": ">=24.x"
+  },
+  "dependencies": {
+    "@trackunit/react-components": "2.1.15-alpha-9d327375fc1.0",
+    "@trackunit/css-class-variance-utilities": "1.13.24-alpha-9d327375fc1.0",
+    "@trackunit/react-form-components": "2.1.16-alpha-9d327375fc1.0",
+    "@trackunit/react-core-hooks": "1.17.29-alpha-9d327375fc1.0",
+    "@trackunit/geo-json-utils": "1.14.25-alpha-9d327375fc1.0",
+    "@trackunit/i18n-library-translation": "2.0.17-alpha-9d327375fc1.0",
+    "@trackunit/react-modal": "2.1.17-alpha-9d327375fc1.0",
+    "react-minimal-pie-chart": "^8.4.0",
+    "@trackunit/react-map-adapter-shared": "0.0.4-alpha-9d327375fc1.0",
+    "@trackunit/ui-design-tokens": "1.13.24-alpha-9d327375fc1.0",
+    "@floating-ui/react": "^0.26.25",
+    "es-toolkit": "^1.39.10",
+    "tailwind-merge": "^2.0.0",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@tanstack/react-router": "1.114.29",
+    "react-hook-form": "7.62.0"
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/src/annotations/getDescriptorContentKey.d.ts

@@ -0,0 +1,14 @@
+import type { MapAnnotationDescriptor } from "./mapAnnotations";
+/**
+ * Returns a stable content key for the descriptor so that inline objects with
+ * the same logical content do not trigger effect re-runs.
+ *
+ * For simple descriptors, `onClick` and `icon` are tracked by reference
+ * identity so a new click handler or a new icon element causes re-registration,
+ * preventing stale-closure bugs.
+ *
+ * For custom descriptors, the descriptor's own object identity is used so the
+ * key changes whenever the render function reference changes (e.g. when
+ * isHovered / isSelected state changes).
+ */
+export declare const getDescriptorContentKey: (descriptor: MapAnnotationDescriptor | null) => string;

package/src/annotations/mapAnnotations.d.ts

@@ -0,0 +1,76 @@
+import type { ReactNode } from "react";
+/**
+ * Describes an annotation to be rendered in the map's Controls overlay.
+ *
+ * Discriminated union on `type`:
+ * - `"simple"`: icon + label + optional color -- rendered as a compact pill/badge
+ * - `"custom"`: arbitrary ReactNode via render function -- full control
+ */
+export type MapAnnotationDescriptor = Readonly<{
+    type: "simple";
+    id: string;
+    /** Lower number = higher priority in layout order */
+    priority?: number;
+    icon?: ReactNode;
+    label: string;
+    color?: string;
+    /**
+     * When set, the pill is rendered as a button and the handler runs on click.
+     * Implementations should call `stopPropagation` so multi-annotation stack
+     * expand/pin toggles on the outer container are not triggered accidentally.
+     */
+    onClick?: () => void;
+}> | Readonly<{
+    type: "custom";
+    id: string;
+    /** Lower number = higher priority in layout order */
+    priority?: number;
+    /**
+     * Render function that returns the annotation's content.
+     *
+     * **Peek-card convention (`data-peek-root`):**
+     * When multiple annotations are stacked, only the top card is fully
+     * visible. Older annotations appear as narrow peek strips behind it.
+     * To make peek strips show the correct background color, border-radius,
+     * and shadow, place a `data-peek-root` attribute on the outermost
+     * visual container element (the element that carries the background
+     * and shape styles). Its direct children will be automatically hidden
+     * via `visibility: hidden` when the annotation is rendered as a peek
+     * strip, while the container's own appearance is preserved.
+     *
+     * If `data-peek-root` is omitted the peek strip still renders but
+     * will show raw, unstyled content at 3 px height.
+     */
+    render: () => ReactNode;
+}>;
+/**
+ * Subscription-based store for map annotations.
+ * Compatible with `useSyncExternalStore(subscribe, getSnapshot)`.
+ *
+ * Exposed on `MapApi.annotations` so consumers and Controls can
+ * interact with annotations without React context indirection.
+ *
+ * The `claimRenderer` / `subscribeHasRenderer` / `getHasRendererSnapshot`
+ * trio lets the Map component detect whether an external renderer (Controls)
+ * has claimed annotation rendering. When unclaimed, the Map renders a
+ * built-in fallback AnnotationStack.
+ */
+export type MapAnnotationStore = Readonly<{
+    register: (descriptor: MapAnnotationDescriptor) => void;
+    unregister: (id: string) => void;
+    subscribe: (callback: () => void) => () => void;
+    getSnapshot: () => ReadonlyArray<MapAnnotationDescriptor>;
+    claimRenderer: () => () => void;
+    subscribeHasRenderer: (callback: () => void) => () => void;
+    getHasRendererSnapshot: () => boolean;
+}>;
+/**
+ * Creates a `MapAnnotationStore` instance.
+ *
+ * Uses a `Set<() => void>` for subscribers and a `Map<string, MapAnnotationDescriptor>`
+ * for registered annotations. `getSnapshot` returns a stable `ReadonlyArray` reference
+ * that only changes when annotations are mutated.
+ *
+ * @internal
+ */
+export declare const createMapAnnotationStore: () => MapAnnotationStore;

package/src/annotations/useMapAnnotation.d.ts

@@ -0,0 +1,16 @@
+import type { MapApi } from "../core/types";
+import type { MapAnnotationDescriptor } from "./mapAnnotations";
+/**
+ * Registers a map annotation to be rendered in the Controls overlay.
+ *
+ * Pass a descriptor to register, or `null` to unregister.
+ * Automatically cleans up on unmount.
+ *
+ * Same-id rerenders are stable: passing an inline descriptor with identical
+ * content (id, label, priority, etc.) will not cause unregister/register churn,
+ * avoiding reordering and enter/exit animation retriggers.
+ *
+ * @param api - The map API object from `useMap`
+ * @param descriptor - Annotation descriptor to register, or `null` to unregister
+ */
+export declare const useMapAnnotation: (api: MapApi, descriptor: MapAnnotationDescriptor | null) => void;

package/src/annotations/useMapAnnotations.d.ts

@@ -0,0 +1,17 @@
+import type { MapApi } from "../core/types";
+import type { MapAnnotationDescriptor } from "./mapAnnotations";
+/**
+ * Registers a list of map annotations to be rendered in the Controls overlay.
+ *
+ * Syncs the reactive `descriptors` list to the annotation store: newly added
+ * descriptors are registered, removed ones are unregistered on each render.
+ * Automatically cleans up all registrations on unmount.
+ *
+ * Stable on re-render with identical content: passing a new array reference
+ * with descriptors whose id/label/priority/color fields are unchanged does not
+ * cause unregister/register churn.
+ *
+ * @param api - The map API object from `useMap`
+ * @param descriptors - Array of annotation descriptors to sync
+ */
+export declare const useMapAnnotations: (api: MapApi, descriptors: ReadonlyArray<MapAnnotationDescriptor>) => void;

package/src/appearance/AppearancePreview.d.ts

@@ -0,0 +1,27 @@
+import type { AdapterConfig } from "@trackunit/react-map-adapter-shared";
+import type { MapType } from "../core/types";
+type AppearancePreviewProps = Readonly<{
+    /** Derived adapter config for this preview (with the correct theme baked in) */
+    adapterConfig: AdapterConfig;
+    /** Map type to display in this preview */
+    mapType: MapType;
+    /** Display label shown under the preview */
+    label: string;
+    /** Whether this preview is the currently selected appearance */
+    selected: boolean;
+    /** Called when this preview is clicked */
+    onSelect: () => void;
+    /** Test ID */
+    "data-testid"?: string;
+}>;
+/**
+ * A single map appearance preview cell.
+ *
+ * Renders a tiny non-interactive map using `usePreviewMap` with a derived adapter config.
+ * The map renders taller than the visible area to crop out the Google attribution at the bottom.
+ * Uses `cvaInteractableItem` with a hidden radio input for selection styling.
+ *
+ * @internal
+ */
+export declare const AppearancePreview: ({ adapterConfig, mapType, label, selected, onSelect, "data-testid": dataTestId, }: AppearancePreviewProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/src/appearance/AppearancePreviewGrid.d.ts

@@ -0,0 +1,29 @@
+import type { AdapterConfig } from "@trackunit/react-map-adapter-shared";
+import type { MapTheme, MapType } from "../core/types";
+import type { AppearanceOption } from "./appearanceTypes";
+type AppearancePreviewGridProps = Readonly<{
+    /** The adapter config from the main map (used to derive preview configs) */
+    adapterConfig: AdapterConfig;
+    /** Appearance options to display */
+    options: ReadonlyArray<AppearanceOption>;
+    /** Currently active theme */
+    currentTheme: MapTheme;
+    /** Currently active map type */
+    currentMapType: MapType;
+    /** Called when user selects an appearance option */
+    onChange: (theme: MapTheme, mapType: MapType) => void;
+}>;
+/**
+ * Grid of tiny live map previews for selecting map appearance.
+ *
+ * Each preview renders a real map instance using `usePreviewMap` with
+ * a derived adapter config. The grid is rendered as a `radiogroup`
+ * for accessibility.
+ *
+ * This component is always rendered inside a menu (as a custom menu item),
+ * so it uses menu-appropriate spacing (`px-3 py-2`).
+ *
+ * @internal
+ */
+export declare const AppearancePreviewGrid: ({ adapterConfig, options, currentTheme, currentMapType, onChange, }: AppearancePreviewGridProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/src/appearance/appearanceTypes.d.ts

@@ -0,0 +1,84 @@
+import type { AdapterConfig } from "@trackunit/react-map-adapter-shared";
+import { z } from "zod";
+import { type MapActions, type MapStatus, type MapTheme, type MapType } from "../core/types";
+/**
+ * Increment this number to invalidate stored appearance settings in localStorage
+ * and reset all users to defaults.
+ */
+export declare const APPEARANCE_SETTINGS_VERSION = 1;
+export declare const persistedAppearanceSchema: z.ZodObject<{
+    theme: z.ZodEnum<["light", "dark"]>;
+    mapType: z.ZodEnum<["roadmap", "satellite", "hybrid"]>;
+    showRoads: z.ZodBoolean;
+} & {
+    version: z.ZodLiteral<1>;
+}, "strip", z.ZodTypeAny, {
+    mapType: "roadmap" | "satellite" | "hybrid";
+    theme: "light" | "dark";
+    version: 1;
+    showRoads: boolean;
+}, {
+    mapType: "roadmap" | "satellite" | "hybrid";
+    theme: "light" | "dark";
+    version: 1;
+    showRoads: boolean;
+}>;
+/** Appearance state persisted to localStorage (MapAppearance + migration version) */
+export type PersistedAppearance = Readonly<z.infer<typeof persistedAppearanceSchema>>;
+/** Default persisted appearance when nothing is stored */
+export declare const DEFAULT_PERSISTED_APPEARANCE: PersistedAppearance;
+type SetThemeAction = Readonly<{
+    type: "setTheme";
+    payload: MapTheme;
+}>;
+type SetMapTypeAction = Readonly<{
+    type: "setMapType";
+    payload: MapType;
+}>;
+type SetShowRoadsAction = Readonly<{
+    type: "setShowRoads";
+    payload: boolean;
+}>;
+export type AppearanceAction = Readonly<SetThemeAction | SetMapTypeAction | SetShowRoadsAction>;
+/** Reducer for persisted appearance state */
+export declare const appearanceReducer: (state: PersistedAppearance, action: AppearanceAction) => PersistedAppearance;
+/** Configuration for which appearance options to show in the settings panel */
+export type AppearanceOptions = Readonly<{
+    /** Which themes to offer. Default: ["light", "dark"] */
+    themes?: ReadonlyArray<MapTheme>;
+    /** Which map types to offer. Default: ["roadmap", "satellite"] */
+    mapTypes?: ReadonlyArray<MapType>;
+    /** Whether to show the roads toggle when satellite/hybrid is selected. Default: true */
+    roads?: boolean;
+}>;
+/**
+ * Narrowed API surface that useMapAppearanceControls actually needs.
+ * Accepts the full MapApi (structural subtyping) but avoids
+ * coupling the hook to fields it never touches.
+ */
+export type MapAppearanceApi = Readonly<{
+    state: MapStatus;
+    actions: MapActions;
+    adapterConfig: AdapterConfig;
+}>;
+/** Parameters for the useMapAppearanceControls hook */
+export type UseMapAppearanceControlsParams = Readonly<{
+    /** The map API object from useMap (only state, actions, and adapterConfig are used) */
+    api: MapAppearanceApi;
+    /** Optional: configure which appearance options to show */
+    options?: AppearanceOptions;
+    /** Optional: localStorage persistence key. Default: "map-appearance-settings" */
+    persistenceKey?: string;
+}>;
+/** A single appearance option shown in the preview grid */
+export type AppearanceOption = Readonly<{
+    /** Unique key for this option */
+    key: string;
+    /** Display label (translated) */
+    label: string;
+    /** Theme for this option */
+    theme: MapTheme;
+    /** Map type for this option */
+    mapType: MapType;
+}>;
+export {};

package/src/appearance/useMapAppearanceControls.d.ts

@@ -0,0 +1,29 @@
+import type { MenuControlConfig } from "../controls/types";
+import { type UseMapAppearanceControlsParams } from "./appearanceTypes";
+/**
+ * Hook that returns `ControlConfig[]` for the map appearance settings area.
+ *
+ * Manages appearance state (theme, map type, roads toggle) using `useLocalStorageReducer`
+ * with Zod schema validation. Bidirectionally syncs with the adapter's
+ * `api.state.appearance` so external changes (e.g. from Storybook controls)
+ * are reflected in the UI and localStorage.
+ *
+ * Returns an array with a single `MenuControlConfig` that contains:
+ * - A custom item with a grid of live tiny map previews
+ * - A toggle item for roads overlay (when satellite/hybrid is selected)
+ *
+ * @example
+ * ```tsx
+ * const appearanceControls = useMapAppearanceControls({ api });
+ *
+ * const controlsConfig: ControlsConfig = {
+ *   navigation: { controls: navigationControls },
+ *   settings: { controls: appearanceControls },
+ *   tools: null,
+ *   statistics: { controls: [] },
+ * };
+ *
+ * <Controls api={api} controlsConfig={controlsConfig} />
+ * ```
+ */
+export declare const useMapAppearanceControls: ({ api, options: appearanceOptions, persistenceKey, }: UseMapAppearanceControlsParams) => ReadonlyArray<MenuControlConfig>;

package/src/clusters/ClusterMarker.d.ts

@@ -0,0 +1,41 @@
+import { type CommonProps, type Refable, type Styleable } from "@trackunit/react-components";
+import { type HTMLAttributes } from "react";
+import type { MapTheme } from "../core/types";
+import type { MarkerState } from "../markers/model/markerDomTypes";
+import { type MarkerColorConfig } from "../markers/shared/markerColors";
+import { type ClusterStickProps } from "./ClusterStick";
+/** Pre-computed doughnut segment input. `weight` maps directly to `value` in `BaseDataEntry`. */
+export type ClusterSegment = {
+    readonly color: string;
+    readonly weight: number;
+};
+/** Distributive `Omit` so the `label`/`aria-label` discriminated union of `ClusterStickProps` is preserved. */
+type DistributiveOmit<TUnion, TKey extends string> = TUnion extends unknown ? Omit<TUnion, TKey> : never;
+/**
+ * Per-member stick input. `onStickClick` is owned by `ClusterMarker` and forwarded with the stick's `id`.
+ * `positioning` is computed by `ClusterMarker` from the fan angle — callers do not provide it.
+ * `open` is managed internally — callers do not provide it.
+ */
+export type ClusterMarkerStickInput = DistributiveOmit<ClusterStickProps, "onStickClick" | "positioning" | "open">;
+type ClusterMarkerDivHandlers = Pick<HTMLAttributes<HTMLDivElement>, "onClick" | "onKeyDown" | "onMouseEnter" | "onMouseLeave" | "onFocus" | "onBlur">;
+type ClusterMarkerBaseProps = CommonProps & Styleable & Refable<HTMLDivElement> & ClusterMarkerDivHandlers & {
+    /** Total member count. Rendered via {@link formatClusterCount}. */
+    count: number;
+    /** Doughnut ring segments. Empty array suppresses the ring. */
+    segments: ReadonlyArray<ClusterSegment>;
+    /**
+     * Optional cluster member sticks fanned out around the bubble at evenly spread angles.
+     * Intended for clusters with 6 or fewer members; above that, stick labels become crowded.
+     */
+    sticks?: ReadonlyArray<ClusterMarkerStickInput>;
+    /** Fired by each fanned-out stick with its `id`. */
+    onStickClick?: (id: string) => void;
+    state?: MarkerState;
+    theme: MapTheme;
+    colorConfig?: MarkerColorConfig;
+};
+export type ClusterMarkerProps = ClusterMarkerBaseProps & {
+    "aria-label"?: string;
+};
+export declare const ClusterMarker: import("react").ForwardRefExoticComponent<Omit<ClusterMarkerProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export {};

package/src/clusters/ClusterStick.d.ts

@@ -0,0 +1,97 @@
+import { type CommonProps, type Refable, type Styleable } from "@trackunit/react-components";
+import { type HTMLAttributes, type ReactElement } from "react";
+import type { MapTheme } from "../core/types";
+import type { ClusterStickState, MarkerDomSize, StickPositioning } from "../markers/model/markerDomTypes";
+import { type MarkerColorConfig } from "../markers/shared/markerColors";
+type ClusterStickDivHandlers = Pick<HTMLAttributes<HTMLDivElement>, "onKeyDown" | "onMouseEnter" | "onMouseLeave" | "onFocus" | "onBlur">;
+type ClusterStickBaseProps = CommonProps & Styleable & Refable<HTMLDivElement> & ClusterStickDivHandlers & {
+    /** Stable identifier for the stick; forwarded to `onStickClick`. */
+    id: string;
+    /** Indicator fill (CSS color). Shares the disc/pill color system with `MapMarker`. */
+    color: string;
+    state?: ClusterStickState;
+    size: MarkerDomSize;
+    theme: MapTheme;
+    colorConfig?: MarkerColorConfig;
+    icon?: ReactElement | null;
+    /**
+     * How the pill is positioned relative to the cluster anchor.
+     * Defaults to `MARKER_TUNING.stick.defaultPositioning` (straight up, 40 px).
+     * In practice `ClusterMarker` always computes a polar fan angle and passes it here.
+     */
+    positioning?: StickPositioning;
+    /**
+     * Whether the stick is fanned out (`true`, default) or animating back to the
+     * cluster center (`false`). `ClusterMarker` sets this to `false` for sticks
+     * that have left the `sticks` array so they can animate in before unmounting.
+     * Callers rendering `ClusterStick` standalone should leave this at the default.
+     */
+    open?: boolean;
+    /** Fires with the `id` prop on click or keyboard activation. */
+    onStickClick?: (id: string) => void;
+};
+export type ClusterStickProps = (ClusterStickBaseProps & {
+    label: string;
+    "aria-label"?: string;
+}) | (ClusterStickBaseProps & {
+    label?: never;
+    "aria-label": string;
+});
+export declare const ClusterStick: import("react").ForwardRefExoticComponent<(Omit<CommonProps & Styleable & Refable<HTMLDivElement> & ClusterStickDivHandlers & {
+    /** Stable identifier for the stick; forwarded to `onStickClick`. */
+    id: string;
+    /** Indicator fill (CSS color). Shares the disc/pill color system with `MapMarker`. */
+    color: string;
+    state?: ClusterStickState;
+    size: MarkerDomSize;
+    theme: MapTheme;
+    colorConfig?: MarkerColorConfig;
+    icon?: ReactElement | null;
+    /**
+     * How the pill is positioned relative to the cluster anchor.
+     * Defaults to `MARKER_TUNING.stick.defaultPositioning` (straight up, 40 px).
+     * In practice `ClusterMarker` always computes a polar fan angle and passes it here.
+     */
+    positioning?: StickPositioning;
+    /**
+     * Whether the stick is fanned out (`true`, default) or animating back to the
+     * cluster center (`false`). `ClusterMarker` sets this to `false` for sticks
+     * that have left the `sticks` array so they can animate in before unmounting.
+     * Callers rendering `ClusterStick` standalone should leave this at the default.
+     */
+    open?: boolean;
+    /** Fires with the `id` prop on click or keyboard activation. */
+    onStickClick?: (id: string) => void;
+} & {
+    label: string;
+    "aria-label"?: string;
+}, "ref"> | Omit<CommonProps & Styleable & Refable<HTMLDivElement> & ClusterStickDivHandlers & {
+    /** Stable identifier for the stick; forwarded to `onStickClick`. */
+    id: string;
+    /** Indicator fill (CSS color). Shares the disc/pill color system with `MapMarker`. */
+    color: string;
+    state?: ClusterStickState;
+    size: MarkerDomSize;
+    theme: MapTheme;
+    colorConfig?: MarkerColorConfig;
+    icon?: ReactElement | null;
+    /**
+     * How the pill is positioned relative to the cluster anchor.
+     * Defaults to `MARKER_TUNING.stick.defaultPositioning` (straight up, 40 px).
+     * In practice `ClusterMarker` always computes a polar fan angle and passes it here.
+     */
+    positioning?: StickPositioning;
+    /**
+     * Whether the stick is fanned out (`true`, default) or animating back to the
+     * cluster center (`false`). `ClusterMarker` sets this to `false` for sticks
+     * that have left the `sticks` array so they can animate in before unmounting.
+     * Callers rendering `ClusterStick` standalone should leave this at the default.
+     */
+    open?: boolean;
+    /** Fires with the `id` prop on click or keyboard activation. */
+    onStickClick?: (id: string) => void;
+} & {
+    label?: never;
+    "aria-label": string;
+}, "ref">) & import("react").RefAttributes<HTMLDivElement>>;
+export {};

package/src/clusters/formatClusterCount.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Formats a cluster member count for display inside `MapCluster`.
+ *
+ * Rules:
+ * - `n < 1 000` → raw integer string
+ * - `1 000 ≤ n < 1 000 000` → `Xk` (truncated to whole thousands)
+ * - `n ≥ 1 000 000` → `X.Xm` (truncated to one decimal of millions)
+ *
+ * Truncation (not rounding) is used so the displayed value never overstates the count.
+ */
+export declare const formatClusterCount: (n: number) => string;

package/src/clusters/stories/ClusterMarkerCompactFormatsDemo.d.ts

@@ -0,0 +1,7 @@
+import type { ReactElement } from "react";
+import type { MapTheme } from "../../core/types";
+type ClusterMarkerCompactFormatsDemoProps = {
+    readonly theme: MapTheme;
+};
+export declare const ClusterMarkerCompactFormatsDemo: ({ theme }: ClusterMarkerCompactFormatsDemoProps) => ReactElement;
+export {};

package/src/clusters/stories/ClusterMarkerCountOnlyDemo.d.ts

@@ -0,0 +1,7 @@
+import type { ReactElement } from "react";
+import type { MapTheme } from "../../core/types";
+type ClusterMarkerCountOnlyDemoProps = {
+    readonly theme: MapTheme;
+};
+export declare const ClusterMarkerCountOnlyDemo: ({ theme }: ClusterMarkerCountOnlyDemoProps) => ReactElement;
+export {};

package/src/clusters/stories/ClusterMarkerDefaultDemo.d.ts

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+import type { MapTheme } from "../../core/types";
+import type { MarkerState } from "../../markers/model/markerDomTypes";
+type ClusterMarkerDefaultDemoProps = {
+    readonly count: number;
+    readonly state: MarkerState;
+    readonly theme: MapTheme;
+    readonly showSegments: boolean;
+    readonly showSticks: boolean;
+};
+export declare const ClusterMarkerDefaultDemo: ({ count, state, theme, showSegments, showSticks, }: ClusterMarkerDefaultDemoProps) => ReactElement;
+export {};

package/src/clusters/stories/ClusterMarkerPlaygroundDemo.d.ts

@@ -0,0 +1,10 @@
+import { type ReactElement } from "react";
+import type { MapTheme } from "../../core/types";
+type ClusterMarkerPlaygroundDemoProps = {
+    readonly theme: MapTheme;
+    readonly stickCount: number;
+    readonly showSegments: boolean;
+    readonly showIndicators: boolean;
+};
+export declare const ClusterMarkerPlaygroundDemo: ({ theme, stickCount, showSegments, showIndicators, }: ClusterMarkerPlaygroundDemoProps) => ReactElement;
+export {};

package/src/clusters/stories/ClusterMarkerStateDemo.d.ts

@@ -0,0 +1,9 @@
+import type { ReactElement } from "react";
+import type { MapTheme } from "../../core/types";
+import type { MarkerState } from "../../markers/model/markerDomTypes";
+type ClusterMarkerStateDemoProps = {
+    readonly theme: MapTheme;
+    readonly state: MarkerState;
+};
+export declare const ClusterMarkerStateDemo: ({ theme, state }: ClusterMarkerStateDemoProps) => ReactElement;
+export {};

package/src/clusters/stories/ClusterMarkerWithSegmentsDemo.d.ts

@@ -0,0 +1,7 @@
+import type { ReactElement } from "react";
+import type { MapTheme } from "../../core/types";
+type ClusterMarkerWithSegmentsDemoProps = {
+    readonly theme: MapTheme;
+};
+export declare const ClusterMarkerWithSegmentsDemo: ({ theme }: ClusterMarkerWithSegmentsDemoProps) => ReactElement;
+export {};

package/src/clusters/stories/ClusterMarkerWithSticksDemo.d.ts

@@ -0,0 +1,10 @@
+import type { ReactElement } from "react";
+import type { MapTheme } from "../../core/types";
+type ClusterMarkerWithSticksDemoProps = {
+    readonly theme: MapTheme;
+    readonly showSegments: boolean;
+    readonly showIndicators: boolean;
+    readonly stickCount: number;
+};
+export declare const ClusterMarkerWithSticksDemo: ({ theme, showSegments, showIndicators, stickCount, }: ClusterMarkerWithSticksDemoProps) => ReactElement;
+export {};

package/src/clusters/useClusterCountFormat.d.ts

@@ -0,0 +1,19 @@
+import { formatClusterCount } from "./formatClusterCount";
+export type ClusterCountFormatHelpers = Readonly<{
+    formatClusterCount: typeof formatClusterCount;
+}>;
+/**
+ * Build-your-own hook: stable reference to the cluster count formatter.
+ *
+ * Returns `formatClusterCount` for consumers building custom cluster markers
+ * that need consistent `"1.2k / 3.4m"` formatting without reimplementing
+ * the truncation rules.
+ *
+ * @example
+ * ```tsx
+ * const { formatClusterCount } = useClusterCountFormat();
+ * // Inside your cluster render:
+ * return <div>{formatClusterCount(clusterCount)}</div>;
+ * ```
+ */
+export declare const useClusterCountFormat: () => ClusterCountFormatHelpers;

package/src/controls/AnnotationRenderer.d.ts

@@ -0,0 +1,17 @@
+import type { MapAnnotationDescriptor } from "../annotations/mapAnnotations";
+type AnnotationRendererProps = Readonly<{
+    annotation: MapAnnotationDescriptor;
+}>;
+/**
+ * Renders a single map annotation based on its content type.
+ *
+ * - `"simple"`: compact pill with optional icon, label, and color; optional `onClick`
+ *   renders as a `<button type="button">` instead of a non-interactive div
+ * - `"custom"`: delegates entirely to the descriptor's render function.
+ *   The render function's root element is rendered directly (no wrapper),
+ *   so it should handle its own overflow (e.g. truncation).
+ *
+ * @internal
+ */
+export declare const AnnotationRenderer: ({ annotation }: AnnotationRendererProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/src/controls/AnnotationStack.d.ts

@@ -0,0 +1,21 @@
+import type { MapAnnotationDescriptor } from "../annotations/mapAnnotations";
+import "./AnnotationStack.css";
+type AnnotationStackProps = Readonly<{
+    annotations: ReadonlyArray<MapAnnotationDescriptor>;
+    isExiting: boolean;
+}>;
+/**
+ * Renders annotations as a collapsible card-deck stack.
+ *
+ * Only the newest (last) annotation is fully visible. Older annotations
+ * peek behind it as offset strips. The stack expands on hover (temporary)
+ * or click (pinned).
+ *
+ * The expanded panel uses Floating UI with safePolygon so it doesn't
+ * close when moving the pointer between the reference and floating
+ * elements, and doesn't affect the surrounding Controls grid layout.
+ *
+ * @internal
+ */
+export declare const AnnotationStack: ({ annotations, isExiting }: AnnotationStackProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

package/src/controls/ControlRenderer.d.ts

@@ -0,0 +1,20 @@
+import type { ComponentRef, RefObject } from "react";
+import { type AvailableSpace } from "./renderingRules";
+import type { ControlConfig, MenuPresentation } from "./types";
+type ControlRendererProps = Readonly<{
+    availableSpace: AvailableSpace;
+    /** Ref to the controls overlay container, used to compute popover placement */
+    containerRef: RefObject<ComponentRef<"div"> | null>;
+    control: ControlConfig;
+    customPortalId?: string;
+    menuPresentation: MenuPresentation;
+}>;
+/**
+ * Renders a control based on its type using exhaustive switch.
+ * Calls resolveControl to compute rendering decisions, then passes
+ * both the config and resolved props to the presentational renderer.
+ *
+ * @internal
+ */
+export declare const ControlRenderer: ({ availableSpace, containerRef, control, customPortalId, menuPresentation, }: ControlRendererProps) => import("react/jsx-runtime").JSX.Element;
+export {};