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

package/src/controls/types.d.ts

@@ -0,0 +1,395 @@
+import type { BasicToggleGroupListProps, CommonProps, Icon, Size } from "@trackunit/react-components";
+import type { ComponentProps, ReactNode } from "react";
+/** Extract IconName from Icon component props */
+export type IconName = ComponentProps<typeof Icon>["name"];
+/** Where the control appears in the UI hierarchy */
+export type Placement = "standalone" | "menu";
+/** Raw environment signal -- how much space the container has */
+export type AvailableSpace = "constrained" | "comfortable";
+/** Computed sizing decision -- set by the sizing middleware from placement + availableSpace */
+export type Compactness = "compact" | "spacious";
+/** The full rendering context that drives all layout decisions */
+export type RenderContext = Readonly<{
+    placement: Placement;
+    availableSpace: AvailableSpace;
+}>;
+/** Shared resolved fields set by cross-cutting middleware (before type-specific resolution) */
+export type ResolvedControlPropsBase = Readonly<{
+    /** Physical size of the control -- aligns with component library Size type */
+    size: Size;
+    /** Whether the control should be rendered at all */
+    visible: boolean;
+    /** Spacing between sub-elements (e.g. stepper buttons) */
+    gap: string;
+    /** Sizing decision: "compact" when in a menu or constrained container, "spacious" otherwise */
+    compactness: Compactness;
+    /** Resolved icon (state-dependent for toggles, static for buttons) */
+    icon?: IconName;
+}>;
+/** All control type discriminants (derived from config unions + separator) */
+type ControlType = ControlConfig["type"] | SeparatorItemConfig["type"];
+/**
+ * Discriminated union of resolved control props.
+ *
+ * Discriminant: `controlType` -- mirrors the config's `type` field.
+ * Flat mapped type: every control type resolves to `ResolvedControlPropsBase`
+ * plus a `controlType` discriminant.
+ */
+export type ResolvedControlProps = {
+    [K in ControlType]: ResolvedControlPropsBase & Readonly<{
+        controlType: K;
+    }>;
+}[ControlType];
+/**
+ * What happens to a control when responsive collapsing moves it into a menu.
+ *
+ * - `"menu"` (default) -- the control is placed inside the overflow menu
+ * - `"hide"` -- the control is fully removed instead of being menued
+ *
+ * Use `"hide"` for controls that only make sense as standalone map overlays
+ * and would be confusing or useless inside a menu (e.g. a visual indicator
+ * that has no interactive menu representation).
+ */
+export type OverflowBehavior = "menu" | "hide";
+/** Base fields shared by all controls */
+type BaseControlConfig<TType extends string> = Readonly<CommonProps & {
+    type: TType;
+    id: string;
+    /**
+     * What happens when responsive collapsing would move this control into a menu.
+     *
+     * - `"menu"` (default) -- placed inside the overflow menu alongside other controls
+     * - `"hide"` -- fully hidden instead of being menued
+     *
+     * @default "menu"
+     */
+    overflowBehavior?: OverflowBehavior;
+}>;
+/** Simple icon button - click action */
+export type ButtonControlConfig = BaseControlConfig<"button"> & Readonly<{
+    icon: IconName;
+    label: string;
+    onClick: () => void;
+    /** Section name for grouping in menus (consecutive items with same section get a header) */
+    section?: string;
+}>;
+/** Two connected buttons for increment/decrement (zoom) */
+export type StepperControlConfig = BaseControlConfig<"stepper"> & Readonly<{
+    /** Display label for the whole stepper control (e.g. "Zoom") */
+    label: string;
+    increment: () => void;
+    decrement: () => void;
+    /** Section name for grouping in menus (consecutive items with same section get a header) */
+    section?: string;
+}>;
+/** Shared fields for boolean (on/off) controls: toggle and checkbox */
+type BooleanControlFields = Readonly<{
+    label: string;
+    value: boolean;
+    onChange: (value: boolean) => void;
+    /**
+     * State-dependent icons shown when the control is on or off (standalone only).
+     * Both must be provided together — this prevents partial-icon bugs where
+     * only one state has a visible icon.
+     *
+     * - **Standalone**: the state-appropriate icon is shown on the button; omitted falls back to Check/XMark
+     * - **Menu**: icon is never shown (not exposed; would look cluttered)
+     */
+    icon?: Readonly<{
+        on: IconName;
+        off: IconName;
+    }>;
+    /** Section name for grouping in menus (consecutive items with same section get a header) */
+    section?: string;
+}>;
+/** Toggle switch - boolean value (renders ToggleSwitch in menus) */
+export type ToggleControlConfig = BaseControlConfig<"toggle"> & BooleanControlFields;
+/** Checkbox - boolean value (renders Checkbox in menus) */
+export type CheckboxControlConfig = BaseControlConfig<"checkbox"> & BooleanControlFields;
+/** Union of all boolean (on/off) control configs */
+export type BooleanControlConfig = ToggleControlConfig | CheckboxControlConfig;
+/** Select dropdown - string options */
+export type SelectControlConfig<TValue extends string = string> = BaseControlConfig<"select"> & Readonly<{
+    label: string;
+    value: TValue;
+    options: ReadonlyArray<Readonly<{
+        value: TValue;
+        label: string;
+    }>>;
+    onChange: (value: TValue) => void;
+    /** Section name for grouping in menus (consecutive items with same section get a header) */
+    section?: string;
+}>;
+/** Radio group - mutually exclusive string options (RadioGroup + RadioItem in the design system) */
+export type RadioGroupControlConfig<TValue extends string = string> = BaseControlConfig<"radioGroup"> & Readonly<{
+    label: string;
+    value: TValue;
+    options: ReadonlyArray<Readonly<{
+        value: TValue;
+        label: string;
+    }>>;
+    onChange: (value: TValue) => void;
+    /** Icon on the standalone trigger button (menu uses labeled RadioGroup only) */
+    icon: IconName;
+    /** Section name for grouping in menus (consecutive items with same section get a header) */
+    section?: string;
+}>;
+/**
+ * One segment in a toggle group — matches {@link BasicToggleGroupListProps} for the design-system `ToggleGroup` `list` prop.
+ */
+export type ToggleGroupOption<TValue extends string = string> = Readonly<BasicToggleGroupListProps<TValue>>;
+/**
+ * Segmented toggle group — mutually exclusive options (design-system `ToggleGroup`).
+ * Standalone uses icon-only styling per map controls patterns (every option must define `iconName`);
+ * menu supports text-only segments and icons.
+ */
+export type ToggleGroupControlConfig<TValue extends string = string> = BaseControlConfig<"toggleGroup"> & Readonly<{
+    /** Accessible name for the control (group label). */
+    label: string;
+    value: TValue;
+    options: ReadonlyArray<ToggleGroupOption<TValue>>;
+    onChange: (value: TValue) => void;
+    disabled?: boolean;
+    /** Section name for grouping in menus (consecutive items with same section get a header) */
+    section?: string;
+}>;
+/** Search control - string value with search/filter UI */
+export type SearchControlConfig = BaseControlConfig<"search"> & Readonly<{
+    label: string;
+    value: string;
+    placeholder?: string;
+    onChange: (value: string) => void;
+    onClear?: () => void;
+    /** Section name for grouping in menus (consecutive items with same section get a header) */
+    section?: string;
+}>;
+/** Separator between items in a menu */
+export type SeparatorItemConfig = Readonly<{
+    type: "separator";
+}>;
+/** Items that can appear inside a menu (excludes menu itself -- menus cannot nest) */
+export type MenuItemConfig = Readonly<ToggleControlConfig | CheckboxControlConfig | ButtonControlConfig | SelectControlConfig | RadioGroupControlConfig | ToggleGroupControlConfig | SearchControlConfig | StepperControlConfig | SeparatorItemConfig | CustomControlConfig>;
+/** Menu control - groups other controls in a popover */
+export type MenuControlConfig = BaseControlConfig<"menu"> & Readonly<{
+    /** Icon shown on the menu trigger button */
+    icon: IconName;
+    /** Tooltip/label for the menu trigger button */
+    label: string;
+    /** Items in the menu */
+    items: ReadonlyArray<MenuItemConfig>;
+}>;
+/**
+ * Context passed to custom control render functions.
+ *
+ * Contains all environment information needed to adapt rendering.
+ * Built-in control types handle these concerns automatically through
+ * the middleware pipeline. With custom controls, **you** are responsible
+ * for adapting to placement and compactness.
+ *
+ * @see {@link CustomControlConfig} for full usage guidance.
+ */
+export type CustomControlRenderContext = Readonly<{
+    /**
+     * Resolved rendering props from the middleware pipeline.
+     * Contains pre-computed decisions (size, gap, compactness, visible)
+     * that you should respect for visual consistency with built-in controls.
+     */
+    resolved: ResolvedControlProps;
+    /** Current placement -- "standalone" (floating on the map) or "menu" (inside a popover) */
+    placement: Placement;
+}>;
+/**
+ * Custom React component control -- **escape hatch** for cases not covered
+ * by the built-in control types (button, toggle, stepper, select, radioGroup, toggleGroup, search, menu).
+ *
+ * Custom controls can appear both **standalone** (floating on the map) and
+ * **inside menus** (as a menu item). At narrow screen widths the system may
+ * collapse any control into a menu, so your render function **must** handle
+ * both placements.
+ *
+ * ---
+ *
+ * **PREFER BUILT-IN TYPES.** Custom controls bypass the type-safe rendering
+ * pipeline and require you to manually handle:
+ *
+ * - **Compactness** -- use `resolved.compactness` to adapt sizing/spacing
+ * - **Placement** -- standalone (icon button + tooltip) vs menu (labeled item).
+ *   When `placement === "menu"`, render a menu-compatible layout: use `px-3 py-2`
+ *   padding, `role="menuitem"`, and ensure the control is keyboard-navigable.
+ * - **Tooltips** -- show tooltip when `placement === "standalone"`
+ * - **Sizing** -- use `resolved.size` for consistency with other controls
+ * - **Accessibility** -- keyboard navigation, ARIA attributes, focus management
+ * - **Pointer events** -- in standalone mode your content is inside a
+ *   `pointer-events-none` overlay (the container re-enables `pointer-events-auto`)
+ *
+ * If a built-in type can achieve what you need, use it instead. This escape
+ * hatch exists for genuinely novel UI that no config-driven type can express.
+ *
+ * @example
+ * ```ts
+ * const customControl: CustomControlConfig = {
+ *   type: "custom",
+ *   id: "battery-indicator",
+ *   label: "Battery Level",
+ *   render: ({ placement, resolved }) => {
+ *     // Menu placement -- render as a labeled row matching other menu items
+ *     if (placement === "menu") {
+ *       return (
+ *         <div className="px-3 py-2" role="menuitem">
+ *           <BatteryGauge level={72} size="small" showLabel />
+ *         </div>
+ *       );
+ *     }
+ *     // Standalone placement -- compact icon-style widget
+ *     return (
+ *       <BatteryGauge
+ *         size={resolved.size}
+ *         compact={resolved.compactness === "compact"}
+ *       />
+ *     );
+ *   },
+ * };
+ * ```
+ */
+export type CustomControlConfig = BaseControlConfig<"custom"> & Readonly<{
+    /**
+     * Required label for accessibility -- used as tooltip text in standalone
+     * placement (when {@link autoTooltip} is `"standalone"`). Even custom
+     * controls need an accessible name.
+     */
+    label: string;
+    /**
+     * Controls automatic tooltip wrapping in standalone placement.
+     * - `"standalone"` (default): wraps output in `Tooltip` using `label`.
+     * - `"none"`: suppresses auto-tooltip — use when the rendered content manages its own label.
+     */
+    autoTooltip?: "standalone" | "none";
+    /** Section name for grouping in menus (consecutive items with same section get a header) */
+    section?: string;
+    /**
+     * Render function that produces the custom control's UI.
+     *
+     * Receives the full rendering context so the control can adapt to the
+     * environment. You **must** handle compactness and placement changes --
+     * the pipeline provides the information but cannot enforce its use.
+     *
+     * The returned ReactNode is rendered inside the controls overlay.
+     * It will already have `pointer-events-auto` applied on its container.
+     */
+    render: (context: CustomControlRenderContext) => ReactNode;
+    /**
+     * Optional custom resolver that runs after the standard middleware pipeline
+     * but before your render function receives the resolved props.
+     *
+     * Use this to transform or extend the resolved props based on the environment.
+     * For example, override size decisions or add custom visibility logic.
+     *
+     * @example
+     * ```ts
+     * resolve: (resolved, renderContext) => ({
+     *   ...resolved,
+     *   // Hide in constrained containers -- too detailed for small spaces
+     *   visible: renderContext.availableSpace !== "constrained",
+     * })
+     * ```
+     */
+    resolve?: (resolved: ResolvedControlPropsBase, renderContext: RenderContext) => ResolvedControlPropsBase;
+}>;
+/**
+ * Discriminated union of all control types (top-level).
+ *
+ * Prefer the built-in types (button, stepper, toggle, checkbox, select, radioGroup, toggleGroup, search, menu)
+ * which participate fully in the rendering pipeline. Use "custom" only as an
+ * escape hatch for genuinely novel UI.
+ */
+export type ControlConfig = Readonly<ButtonControlConfig | StepperControlConfig | ToggleControlConfig | CheckboxControlConfig | SelectControlConfig | RadioGroupControlConfig | ToggleGroupControlConfig | SearchControlConfig | MenuControlConfig | CustomControlConfig>;
+/** Navigation area - array of controls */
+export type NavigationConfig = Readonly<{
+    controls: ReadonlyArray<ControlConfig>;
+}>;
+/** Settings area - array of controls */
+export type SettingsConfig = Readonly<{
+    controls: ReadonlyArray<ControlConfig>;
+}>;
+/** Statistics area - array of controls */
+export type StatisticsConfig = Readonly<{
+    controls: ReadonlyArray<ControlConfig>;
+}>;
+/** Complete controls configuration */
+export type ControlsConfig = Readonly<{
+    /** Navigation controls: zoom, fullscreen, compass (future), reset view (future) */
+    navigation: NavigationConfig;
+    /** Settings: layer toggles, layer settings (future), map style (future) */
+    settings: SettingsConfig;
+    /** Tools: drawing, measurement, selection (future) */
+    tools: null;
+    /** Statistics: data summaries, counts */
+    statistics: StatisticsConfig;
+}>;
+/**
+ * Built-in navigation controls returned by `useControlsConfig`.
+ *
+ * Consumers composing custom control stacks can use these named handles instead
+ * of re-identifying built-ins by their string ids after the controls are built.
+ */
+export interface BuiltInNavigationConfig extends NavigationConfig {
+    readonly zoom: StepperControlConfig | undefined;
+    readonly fullscreen: ToggleControlConfig | undefined;
+    readonly myLocation: ButtonControlConfig | undefined;
+}
+/** Built-in settings controls returned by `useControlsConfig`. */
+export interface BuiltInSettingsConfig extends SettingsConfig {
+    readonly mapStyle: MenuControlConfig | undefined;
+}
+/** Controls config with named handles for the controls built by `useControlsConfig`. */
+export interface BuiltInControlsConfig extends ControlsConfig {
+    readonly navigation: BuiltInNavigationConfig;
+    readonly settings: BuiltInSettingsConfig;
+}
+/**
+ * How a menu presents its content.
+ *
+ * - `"popover"` — floating `MoreMenu` popover anchored to the trigger button.
+ * - `"modal"` — bottom `Sheet` dialog (`variant="modal"`) with a backdrop.
+ *
+ * `Controls` derives this from `availableSpace`: `"constrained"` containers get
+ * `"modal"` (Sheet bottom-sheet, better on small screens); `"comfortable"` containers
+ * get `"popover"` (floating popover, better when there is room).
+ */
+export type MenuPresentation = "popover" | "modal";
+/**
+ * How aggressively controls are collapsed based on available space.
+ *
+ * - `"full"` -- all standalone controls shown as-is (wide containers)
+ * - `"categorized"` -- controls within each category grouped into a per-category
+ *   menu when >1 control exists in that category (medium containers)
+ * - `"collapsed"` -- all controls collapsed into a single menu button with
+ *   named sections per category (narrow containers)
+ */
+export type ResponsiveMode = "full" | "categorized" | "collapsed";
+/** The four semantic control areas used for categorization and section headers */
+export type CategoryKey = "navigation" | "settings" | "tools" | "statistics";
+/**
+ * Options for configuring controls when calling useMap
+ */
+export type ControlsOptions = Readonly<{
+    zoom?: Readonly<{
+        enabled?: boolean;
+    }>;
+    fullscreen?: Readonly<{
+        enabled?: boolean;
+    }>;
+    mapStyle?: Readonly<{
+        enabled?: boolean;
+    }>;
+    myLocation?: Readonly<{
+        enabled?: boolean;
+    }>;
+}>;
+/**
+ * Options passed to useMap for configuring map behavior
+ */
+export type UseMapOptions = Readonly<{
+    controls?: ControlsOptions;
+}>;
+export {};

package/src/controls/useAnimatedPresence.d.ts

@@ -0,0 +1,15 @@
+type AnimatedPresenceResult = Readonly<{
+    shouldRender: boolean;
+    isExiting: boolean;
+}>;
+/**
+ * Delays unmounting by `durationMs` after `isPresent` becomes false,
+ * giving consumers time to run an exit animation before the element
+ * is removed from the DOM.
+ *
+ * Returns `shouldRender: true` while the element should remain mounted
+ * (including during the exit window) and `isExiting: true` during the
+ * exit animation window.
+ */
+export declare const useAnimatedPresence: (isPresent: boolean, durationMs: number) => AnimatedPresenceResult;
+export {};

package/src/controls/useAnnotationPresence.d.ts

@@ -0,0 +1,16 @@
+import type { MapAnnotationDescriptor, MapAnnotationStore } from "../annotations/mapAnnotations";
+type AnnotationPresenceResult = Readonly<{
+    displayAnnotations: ReadonlyArray<MapAnnotationDescriptor>;
+    isExiting: boolean;
+    shouldRender: boolean;
+}>;
+/**
+ * Subscribes to a `MapAnnotationStore` and drives animated enter/exit
+ * for the AnnotationStack.
+ *
+ * During the exit window the hook keeps serving the last non-empty
+ * snapshot so the stack can animate out before the DOM elements are
+ * removed.
+ */
+export declare const useAnnotationPresence: (store: MapAnnotationStore) => AnnotationPresenceResult;
+export {};

package/src/controls/useControlStack.d.ts

@@ -0,0 +1,21 @@
+import { collapseControls } from "./collapseControls";
+import { defineControlStack } from "./defineControlStack";
+export type ControlStackHelpers = Readonly<{
+    defineControlStack: typeof defineControlStack;
+    collapseControls: typeof collapseControls;
+}>;
+/**
+ * Build-your-own hook: stable references to control composition/layout helpers.
+ *
+ * Returns `defineControlStack` and `collapseControls` for consumers building
+ * custom control layouts without duplicating the stack-ordering and responsive-
+ * collapse logic already used by `Controls`.
+ *
+ * @example
+ * ```tsx
+ * const { defineControlStack, collapseControls } = useControlStack();
+ * const controls = defineControlStack([myControl, undefined, otherControl]);
+ * const collapsed = collapseControls(config, responsiveMode, metadata);
+ * ```
+ */
+export declare const useControlStack: () => ControlStackHelpers;

package/src/controls/useControlsConfig.d.ts

@@ -0,0 +1,27 @@
+import type { AdapterConfig } from "@trackunit/react-map-adapter-shared";
+import type { ContainerRefHolder, MapActions, MapStatus } from "../core/types";
+import type { BuiltInControlsConfig, UseMapOptions } from "./types";
+/**
+ * Partial MapApi type used by useControlsConfig.
+ * Includes only the fields this hook (and its sub-hooks) actually need,
+ * avoiding a direct dependency on the full MapApi type.
+ */
+type MapApiWithoutControls = Readonly<{
+    state: MapStatus;
+    actions: MapActions;
+    adapterConfig: AdapterConfig;
+    containerRef: ContainerRefHolder;
+}>;
+type UseControlsConfigParams = Readonly<{
+    options?: UseMapOptions;
+    api: MapApiWithoutControls;
+}>;
+/**
+ * Builds the controls configuration from useMap options and api.
+ *
+ * Creates control config objects with bound callbacks for each enabled control.
+ * The Controls component uses this configuration to render controls.
+ * Consumers can compose custom stacks from the named built-in handles.
+ */
+export declare const useControlsConfig: ({ options, api }: UseControlsConfigParams) => BuiltInControlsConfig;
+export {};

package/src/controls/usePopoverPlacement.d.ts

@@ -0,0 +1,33 @@
+import type { PopoverPlacement } from "@trackunit/react-components";
+import { type RefObject } from "react";
+type UsePopoverPlacementOptions = Readonly<{
+    skip?: boolean;
+}>;
+/**
+ * Compute the ideal popover placement for a trigger element based on its
+ * physical position inside a container (e.g. the map controls overlay).
+ *
+ * The popover opens *toward the center* of the container so it stays inside
+ * the map square:
+ *
+ * | Trigger position | Popover direction | Placement        |
+ * |------------------|-------------------|------------------|
+ * | top-left         | down-right        | `"bottom-start"` |
+ * | top-center       | down              | `"bottom"`       |
+ * | top-right        | down-left         | `"bottom-end"`   |
+ * | bottom-left      | up-right          | `"top-start"`    |
+ * | bottom-center    | up                | `"top"`          |
+ * | bottom-right     | up-left           | `"top-end"`      |
+ *
+ * Recomputes when the container resizes (via ResizeObserver).
+ */
+export declare const computePlacement: (triggerEl: HTMLElement, containerEl: HTMLElement) => PopoverPlacement;
+/**
+ * Returns the ideal `PopoverPlacement` for a trigger element based on its
+ * physical position within a container element.
+ *
+ * Purely position-based — not tied to semantic area names. If the layout
+ * changes or controls move, the placement adapts automatically.
+ */
+export declare const usePopoverPlacement: (triggerRef: RefObject<HTMLElement | null>, containerRef: RefObject<HTMLElement | null>, options?: UsePopoverPlacementOptions) => PopoverPlacement;
+export {};

package/src/core/LoadingIndicatorPill.d.ts

@@ -0,0 +1,9 @@
+import type { ReactElement } from "react";
+/**
+ * Small pill that displays a loading spinner on the map.
+ * Styled to visually match the control buttons (secondary variant)
+ * while remaining non-interactive.
+ *
+ * @internal
+ */
+export declare const LoadingIndicatorPill: () => ReactElement;

package/src/core/MapLoadingState.d.ts

@@ -0,0 +1,17 @@
+import type { CSSProperties, ReactElement } from "react";
+type MapLoadingStateProps = {
+    /** Whether the map is currently loading */
+    isLoading: boolean;
+    /** Whether there was an error loading the map */
+    error?: boolean;
+    /** CSS class name */
+    className?: string;
+    /** Inline styles */
+    style?: CSSProperties;
+};
+/**
+ * Accessible loading state component for the map
+ * Shows a spinner while loading, error message on failure
+ */
+export declare const MapLoadingState: ({ isLoading, error, className, style }: MapLoadingStateProps) => ReactElement;
+export {};

package/src/core/SafeAreaLayoutContext.d.ts

@@ -0,0 +1,5 @@
+import type { AvailableSpace, ResponsiveMode } from "../controls/types";
+export declare const SafeAreaLayoutContext: import("react").Context<Readonly<{
+    availableSpace: AvailableSpace;
+    responsiveMode: ResponsiveMode;
+}> | null>;

package/src/core/__testHelpers.d.ts

@@ -0,0 +1,23 @@
+import type { AdapterConfig, AdapterInstance, AdapterRendererProps, CameraState, MapStatus, SafeAreaInsets } from "@trackunit/react-map-adapter-shared";
+import type { ReactElement } from "react";
+import type { MapApi, MapState } from "./types";
+export type MockConfig = {
+    readonly apiKey: string;
+};
+export declare const INITIAL_MOCK_MAP_STATE: MapState;
+export declare const READY_MOCK_MAP_STATE: MapState;
+export type MockAdapterInstance = AdapterInstance<MockConfig> & {
+    readonly _setState: (state: Partial<MapState>) => void;
+    readonly _connect: () => void;
+};
+export type MockAdapterConfig = AdapterConfig<MockConfig> & {
+    readonly instance: MockAdapterInstance;
+};
+export type MutableMockMapApi = Readonly<{
+    api: MapApi;
+    setCameraState: (cameraState: Partial<CameraState>) => void;
+}>;
+export declare const TestHelpers: ({ children }: AdapterRendererProps) => ReactElement;
+export declare const createMockAdapter: (config: MockConfig, initialState?: MapState) => MockAdapterInstance;
+export declare const createMockAdapterConfig: (config: MockConfig, initialState?: MapState, safeAreaInsets?: SafeAreaInsets | null) => MockAdapterConfig;
+export declare const createMutableMockMapApi: (initialCameraState?: Partial<CameraState>, initialStatus?: MapStatus) => MutableMockMapApi;

package/src/core/createMapComponent.d.ts

@@ -0,0 +1,32 @@
+import type { AdapterInstance, AdapterRendererProps, SafeAreaInsets } from "@trackunit/react-map-adapter-shared";
+import { type ComponentType } from "react";
+import type { MapAnnotationStore } from "../annotations/mapAnnotations";
+import type { PanelStore } from "../panel/store/panels";
+import { MapLoadingIndicatorStore } from "./loadingIndicator";
+import type { ContainerRefHolder, MapComponentProps } from "./types";
+type CreateMapComponentConfig = Readonly<{
+    adapter: AdapterInstance;
+    Renderer: ComponentType<AdapterRendererProps>;
+    adapterName: string;
+    containerRefHolder?: ContainerRefHolder;
+    containerId?: string;
+    annotationStore?: MapAnnotationStore;
+    loadingIndicatorStore?: MapLoadingIndicatorStore;
+    panelStore?: PanelStore;
+    safeAreaInsets?: SafeAreaInsets | null;
+}>;
+/**
+ * Creates a named Map component for the given adapter.
+ *
+ * When a `containerRefHolder` is provided (from `useMap`), the component renders a
+ * wrapper div that owns the container ref and applies ZStack grid classes
+ * so children (e.g. Controls) can overlay the map.
+ * The adapter/Renderer never receives container-related props.
+ *
+ * When no `containerRefHolder` is provided (from `usePreviewMap`), the component
+ * still wraps the Renderer in a relative container and draws the readiness overlay on top (SAGA-374).
+ *
+ * @internal
+ */
+export declare const createMapComponent: ({ adapter, Renderer, adapterName, containerRefHolder, containerId, annotationStore, loadingIndicatorStore, panelStore, safeAreaInsets, }: CreateMapComponentConfig) => ComponentType<MapComponentProps>;
+export {};

package/src/core/loadingIndicator.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Subscription-based store for the map loading indicator.
+ * Compatible with `useSyncExternalStore(subscribe, getSnapshot)`.
+ *
+ * `useLayers` pushes its aggregated `loading` boolean into this store.
+ * `createMapComponent` subscribes and renders a spinner overlay when active.
+ */
+export type MapLoadingIndicatorStore = Readonly<{
+    setLoading: (loading: boolean) => void;
+    subscribe: (callback: () => void) => () => void;
+    getSnapshot: () => boolean;
+}>;
+/**
+ * Creates a `MapLoadingIndicatorStore` instance.
+ *
+ * Internally tracks a single boolean. `setLoading` only notifies subscribers
+ * when the value actually changes, preventing unnecessary re-renders.
+ *
+ * @internal
+ */
+export declare const createMapLoadingIndicatorStore: () => MapLoadingIndicatorStore;

package/src/core/padWithInsets.d.ts

@@ -0,0 +1,5 @@
+import type { CSSProperties } from "react";
+import type { SafeAreaInsets } from "@trackunit/react-map-adapter-shared";
+import type { AvailableSpace } from "../controls/types";
+/** Build padding style that combines spacing with safe area insets. */
+export declare const padWithInsets: (availableSpace: AvailableSpace, insets: SafeAreaInsets | null) => CSSProperties;