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

package/src/markers/model/markerDomTypes.d.ts

@@ -0,0 +1,68 @@
+/**
+ * DOM marker size tiers for Map Marker v2 (see map marker design plan §3).
+ */
+export type MarkerDomSize = "xs" | "sm" | "md" | "lg" | "xl";
+/**
+ * Pixel dimensions for a single marker size tier.
+ * - circle: outer circle diameter
+ * - icon: inner icon slot and GpsArrow size (0 = not rendered)
+ * - text: pill label font size (0 = no text tier)
+ * - dot: white inner circle diameter when no icon is set (0 = not rendered, e.g. xs)
+ * - pillPaddingY: vertical padding per side (px) for pill form; pl = pillPaddingY (concentric-cap invariant).
+ *   `xs` has no pill tier — value is 0.
+ */
+export type MarkerSizeDimensions = Readonly<{
+    circle: number;
+    icon: number;
+    text: number;
+    dot: number;
+    pillPaddingY: number;
+}>;
+/**
+ * Visual/interaction state for DOM markers (plan §4). Drives circle vs pill when combined with
+ * `labelVisible` via `resolveMarkerForm`.
+ */
+export type MarkerState = "default" | "hovered" | "expanded" | "selected";
+/**
+ * State for `ClusterStick` — all `MarkerState` values except `"default"`. A stick always shows
+ * its label, so the resting circle form has no useful meaning here.
+ */
+export type ClusterStickState = Exclude<MarkerState, "default">;
+/** Resolved marker silhouette for indicator mode (plan §14). */
+export type MarkerForm = "circle" | "pill";
+/**
+ * How a stick's user-facing distance is interpreted relative to the pill silhouette.
+ * Default (when omitted) is `"rounded-edge"`.
+ *
+ * - `"centerline"` — distance measured to the stick line's endpoint (center of pill cap)
+ * - `"rounded-edge"` — distance measured to the tangent point on the rounded cap surface
+ * - `"bbox-edge"` — distance measured to the nearest axis-aligned edge of the pill bounding box
+ */
+export type StickDistanceMode = "rounded-edge" | "bbox-edge" | "centerline";
+/**
+ * How a stick marker's pill is positioned relative to the map anchor.
+ *
+ * - `"polar"` — angle (math radians, +x = right, −π/2 = up on screen) + distance (px)
+ * - `"offset"` — Cartesian offset (dx, dy) from anchor; magnitude used as the user distance
+ * - `"absolute"` — target pixel coordinate in the map container's coordinate space, plus the
+ *   anchor's pixel coordinate (e.g. from `map.project(lngLat)`). The component derives
+ *   `dx = targetX − anchorX`, `dy = targetY − anchorY` and delegates to the offset path.
+ */
+export type StickPositioning = {
+    type: "polar";
+    angleRad: number;
+    distance: number;
+    distanceMode?: StickDistanceMode;
+} | {
+    type: "offset";
+    dx: number;
+    dy: number;
+    distanceMode?: StickDistanceMode;
+} | {
+    type: "absolute";
+    targetX: number;
+    targetY: number;
+    anchorX: number;
+    anchorY: number;
+    distanceMode?: StickDistanceMode;
+};

package/src/markers/model/markerResolvers.d.ts

@@ -0,0 +1,34 @@
+import type { MarkerDomSize, MarkerForm, MarkerState } from "./markerDomTypes";
+/**
+ * Raw inputs from the map/entity layer before priority resolution (plan §4, §14).
+ */
+export type MarkerRenderStateInput = {
+    selected: boolean;
+    hovered: boolean;
+    expandedRank: number | null;
+};
+type AdaptiveMarkerStateInput = Readonly<{
+    isMounting?: boolean | null;
+    selected: boolean;
+    hovered: boolean;
+}>;
+/**
+ * Priority: selected → expanded → hovered → default (plan §4).
+ */
+export declare const resolveMarkerState: (renderState: MarkerRenderStateInput) => MarkerState;
+export declare const resolveAdaptiveMarkerState: (input: AdaptiveMarkerStateInput, isPromoted?: boolean) => MarkerState;
+/**
+ * Pill when state would show a label and `labelVisible` is not false (plan §4, §14).
+ * `labelVisible` defaults to true when omitted.
+ */
+export declare const resolveMarkerForm: (state: MarkerState, labelVisible: boolean | undefined) => MarkerForm;
+/**
+ * Direction needs an icon slot; xs has none — bump to `sm` (plan §5).
+ */
+export declare const resolveEffectiveSize: (size: MarkerDomSize, direction: number | undefined) => MarkerDomSize;
+/**
+ * Final tier for DOM layout: direction bump (xs→sm), then xs→sm when pill needs label/icon
+ * tiers (`xs` has no pill text/icon — plan §3).
+ */
+export declare const resolveMarkerDomSize: (size: MarkerDomSize, direction: number | undefined, form: MarkerForm) => MarkerDomSize;
+export {};

package/src/markers/model/markerSizeMap.d.ts

@@ -0,0 +1,82 @@
+import type { MarkerDomSize } from "./markerDomTypes";
+/**
+ * Pill (hovered / expanded / selected) layout uses this tier for the indicator
+ * disc, icon slot, label text size, direction arrow, and pill padding — independent
+ * of the `size` prop so the pill stays visually consistent while the default circle
+ * still follows the five-tier ladder.
+ */
+export declare const MARKER_PILL_CONTENT_LAYOUT_SIZE: "md";
+/**
+ * Canonical pixel dimensions for DOM markers. Single source of truth for
+ * circle diameter, icon slot, pill text size, direction arrow size, and pill
+ * vertical padding.
+ *
+ * Concentricity invariant: `pl === pillPaddingY` per size tier (both in
+ * `cvaMapMarker` pill compound variants), ensuring the indicator disc is always
+ * concentric with the pill's rounded left cap.
+ *
+ * `xs` has no pill tier — `pillPaddingY` is 0 (circle-only footprint).
+ */
+export declare const MARKER_SIZE_MAP: {
+    readonly xs: {
+        readonly circle: 8;
+        readonly icon: 0;
+        readonly text: 0;
+        readonly dot: 0;
+        readonly pillPaddingY: 0;
+    };
+    readonly sm: {
+        readonly circle: 12;
+        readonly icon: 8;
+        readonly text: 10;
+        readonly dot: 4;
+        readonly pillPaddingY: 4;
+    };
+    readonly md: {
+        readonly circle: 16;
+        readonly icon: 12;
+        readonly text: 12;
+        readonly dot: 6;
+        readonly pillPaddingY: 6;
+    };
+    readonly lg: {
+        readonly circle: 20;
+        readonly icon: 14;
+        readonly text: 14;
+        readonly dot: 8;
+        readonly pillPaddingY: 6;
+    };
+    readonly xl: {
+        readonly circle: 28;
+        readonly icon: 16;
+        readonly text: 14;
+        readonly dot: 12;
+        readonly pillPaddingY: 4;
+    };
+};
+/**
+ * Derived pill outer height: `circle + 2 × pillPaddingY`.
+ * Use this anywhere a concrete pixel height is needed for collision geometry
+ * or bounding-box calculations. For `xs` this equals the circle diameter.
+ */
+export declare const markerPillOuterHeightPx: (size: MarkerDomSize) => number;
+/**
+ * Derives the maximum full pill envelope width for geometry and viewport budgeting in stick mode.
+ *
+ * This is wider than `maxLabelWidthPx` when optional visual slots (icon disc, direction indicator)
+ * are present. Do NOT use this value to set a fixed rendered pill width — the pill remains
+ * intrinsically sized.
+ *
+ * Layout accounted for (left-to-right):
+ *   left padding + disc slot (if icon) + gap + label budget + gap + direction slot (if direction) + right padding
+ */
+export declare const computeFullPillEnvelopeWidth: (size: MarkerDomSize, maxLabelWidthPx: number, hasIcon: boolean, hasDirection: boolean) => number;
+/**
+ * Density ladder step for adaptive rendering: `xs` maps to `"symbol"` (skip 8px DOM dot; plan §3 / §8).
+ */
+export declare const downgradeMarkerDomSize: (size: MarkerDomSize) => MarkerDomSize | "symbol";
+/**
+ * One step up the five-tier ladder (inverse of {@link downgradeMarkerDomSize} for DOM tiers only).
+ * `xl` stays `xl`. Stick-mode **anchor pin** uses a fixed `xs` base and `upgradeMarkerDomSize` when `selected` (`sm`).
+ */
+export declare const upgradeMarkerDomSize: (size: MarkerDomSize) => MarkerDomSize;

package/src/markers/model/markerTuningParams.d.ts

@@ -0,0 +1,60 @@
+/**
+ * System-level tuning for stick geometry, pill layout, animation, and
+ * adaptive hover (see map marker design plan §3).
+ *
+ * `animation.spring` is the single source of truth for marker motion easing.
+ * The stick endpoint animation drives a JS spring directly; the morph (label
+ * track and direction icon collapse) uses CSS transitions whose duration is
+ * derived from the spring's settle time and whose timing function is
+ * `animation.morphEasing` so both motions feel like one.
+ */
+export declare const MARKER_TUNING: {
+    readonly stick: {
+        readonly defaultPositioning: {
+            readonly type: "polar";
+            readonly angleRad: number;
+            readonly distance: 40;
+        };
+        readonly dotSizePx: 8;
+        readonly lineWidthPx: 1.5;
+    };
+    readonly pill: {
+        /** Maximum width of the label text area. Not the full rendered pill width. */
+        readonly maxLabelWidthPx: 180;
+        readonly paddingRightPx: 12;
+        /** Matches `gap-1` (4 px) used between pill flex items in stick and indicator modes. */
+        readonly gapPx: 4;
+        /** Matches `pr-1.5` (6 px) applied to the pill outer div in stick mode. */
+        readonly stickPaddingRightPx: 6;
+    };
+    readonly animation: {
+        /**
+         * Source-of-truth easing for marker motion. Used directly by the stick
+         * endpoint loop, and as the timing reference for CSS-based morph parts.
+         */
+        readonly spring: Readonly<{
+            stiffness: number;
+            damping: number;
+            mass: number;
+            restVelocity: number;
+            restDelta: number;
+        }>;
+        /**
+         * CSS transition duration used by the morph (label grid track, direction
+         * icon collapse). Derived from the spring's settle time so the morph reads
+         * as a single coordinated motion with the stick endpoint.
+         */
+        readonly morphDurationMs: number;
+        /**
+         * CSS `transition-timing-function` used by every morph property. Matches
+         * the spring's decelerating attack so JS-driven and CSS-driven parts of
+         * the marker read as one motion. See `MARKER_MORPH_EASING` above.
+         */
+        readonly morphEasing: "cubic-bezier(0.22, 1, 0.36, 1)";
+    };
+    readonly hoverDebouncMs: 150;
+    /** Marker panel layout: bottom sheet when map container width is below this (plan §7). */
+    readonly panelLayout: {
+        readonly bottomCardBreakpointWidthPx: 400;
+    };
+};

package/src/markers/model/useMarkerStateResolvers.d.ts

@@ -0,0 +1,25 @@
+import { resolveAdaptiveMarkerState, resolveEffectiveSize, resolveMarkerDomSize, resolveMarkerForm, resolveMarkerState } from "./markerResolvers";
+import { MARKER_SIZE_MAP } from "./markerSizeMap";
+export type MarkerStateResolvers = Readonly<{
+    resolveMarkerState: typeof resolveMarkerState;
+    resolveMarkerForm: typeof resolveMarkerForm;
+    resolveEffectiveSize: typeof resolveEffectiveSize;
+    resolveMarkerDomSize: typeof resolveMarkerDomSize;
+    resolveAdaptiveMarkerState: typeof resolveAdaptiveMarkerState;
+    MARKER_SIZE_MAP: typeof MARKER_SIZE_MAP;
+}>;
+/**
+ * Build-your-own hook: stable references to marker state resolution primitives.
+ *
+ * Returns a memoized object of the pure resolver functions for consumers that
+ * want to hand-roll their own MapMarker replacement while staying consistent
+ * with the library's state priority rules (selected → expanded → hovered → default).
+ *
+ * @example
+ * ```tsx
+ * const { resolveMarkerState, resolveMarkerForm } = useMarkerStateResolvers();
+ * const state = resolveMarkerState({ selected, hovered, expandedRank });
+ * const form  = resolveMarkerForm(state, labelVisible);
+ * ```
+ */
+export declare const useMarkerStateResolvers: () => MarkerStateResolvers;

package/src/markers/shared/MarkerAnimatedSurface.d.ts

@@ -0,0 +1,20 @@
+import type { ReactElement } from "react";
+import type { MapTheme } from "../../core/types";
+import type { DirectionIndicatorDisplay } from "../geometry/useDirectionIndicator";
+import type { MarkerDomSize } from "../model/markerDomTypes";
+import type { ResolvedMarkerColors } from "./markerColors";
+export type MarkerAnimatedSurfaceProps = {
+    readonly colors: ResolvedMarkerColors;
+    readonly directionDisplay: DirectionIndicatorDisplay;
+    readonly duration: number;
+    /** Pill chrome + indicator disc: padding, label `fontSize`, disc tier, icon slot budget. */
+    readonly effectiveSize: MarkerDomSize;
+    readonly icon: ReactElement | null;
+    readonly iconPx: number;
+    readonly isPill: boolean;
+    readonly labelText: string | undefined;
+    readonly showDisc: boolean;
+    readonly textPx: number;
+    readonly theme: MapTheme;
+};
+export declare const MarkerAnimatedSurface: ({ colors, directionDisplay, duration, effectiveSize, icon, iconPx, isPill, labelText, showDisc, textPx, theme, }: MarkerAnimatedSurfaceProps) => ReactElement;

package/src/markers/shared/MarkerDiscContent.d.ts

@@ -0,0 +1,11 @@
+import type { ReactElement } from "react";
+import type { DirectionIndicatorDisplay } from "../geometry/useDirectionIndicator";
+type MarkerDiscContentProps = {
+    readonly icon: ReactElement | null;
+    readonly iconPx: number;
+    readonly isPill: boolean;
+    readonly dotPx: number;
+    readonly directionDisplay: DirectionIndicatorDisplay;
+};
+export declare const MarkerDiscContent: ({ icon, iconPx, isPill, dotPx, directionDisplay, }: MarkerDiscContentProps) => ReactElement | null;
+export {};

package/src/markers/shared/mapMarkerVariants.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Outer MapMarker shell. Only the form-agnostic, state-agnostic base classes
+ * live here — every property that varies per `form`/`size`/`state` is applied
+ * inline in [MapMarker.tsx](../MapMarker.tsx) so the circle↔pill morph can
+ * interpolate it. CVA class toggles never interpolate, so anything that needs
+ * to animate (padding, gap, border-width, border-color, background, height
+ * via padding) is set as an inline number with concrete from/to values in
+ * both states. The inner indicator disc (`cvaMarkerIndicator` below) carries
+ * its own per-size `h-* w-*`; the outer surface sizes intrinsically around it.
+ *
+ * `transition-all` enables the morph; the duration and timing-function are
+ * applied inline from `MARKER_TUNING.animation` so the spring config remains
+ * the single source of truth (no stale `duration-200 ease-in-out` here).
+ */
+export declare const cvaMapMarker: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+/**
+ * Label span inside pill markers.
+ *
+ * Deliberately NO `text-box-trim`. With `leading-none` the line box is exactly
+ * one em, which already contains ascenders and descenders (g, y, p) and centres
+ * the glyphs symmetrically inside the pill. Adding `text-box-trim` shrinks the
+ * box to the cap/baseline band, so the wrapper's `overflow: hidden` (one level
+ * up in {@link MarkerAnimatedSurface}, required so the grid track collapses to
+ * `0fr` during the circle↔pill morph) clips the descenders, and `trim-start`
+ * alone biases the text upward (extra space below). `overflow-x: clip` gives the
+ * horizontal ellipsis without a vertical clip on the span itself.
+ */
+export declare const cvaPillLabel: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+/**
+ * Inner indicator disc: marker fill via `--marker-color`, border via CSS `color-mix` on that token (plan §5).
+ */
+export declare const cvaMarkerIndicator: (props?: ({
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | null | undefined;
+    theme?: "light" | "dark" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;

package/src/markers/shared/markerColors.d.ts

@@ -0,0 +1,55 @@
+import type { MapTheme } from "../../core/types";
+import type { MarkerState } from "../model/markerDomTypes";
+/**
+ * Optional layer-level overrides for pill chrome. Indicator fill always comes from the
+ * per-marker `color` prop (`fillColor` argument to `resolveMarkerColors`).
+ */
+export type MarkerColorConfig = {
+    selectedBackground?: string;
+    hoveredBackground?: string;
+    expandedBackground?: string;
+    pillBorderColor?: string;
+};
+/**
+ * CSS custom properties for spreading onto the marker root. Indicator stroke uses CSS
+ * `color-mix()` on `--marker-color` in stylesheets — not resolved here.
+ */
+export type MarkerColorCssVars = Readonly<{
+    "--marker-color": string;
+    "--marker-pill-bg": string;
+    "--marker-text-color": string;
+    "--marker-pill-border": string;
+}>;
+export type ResolvedMarkerColors = Readonly<{
+    /** Per-marker indicator fill (same as `fillColor`). */
+    indicatorFill: string;
+    /** Background for the pill when shown; `transparent` when `state` is `default`. */
+    pillBackground: string;
+    /** Pill label text color. */
+    textColor: string;
+    /** Pill outline color. */
+    pillBorderColor: string;
+    cssVars: MarkerColorCssVars;
+}>;
+/** Light basemap pill surfaces — neutral-100 / white / neutral-800. */
+export declare const MARKER_LIGHT_PILL: {
+    readonly hovered: string;
+    readonly expanded: "#ffffff";
+    readonly selected: string;
+};
+/** Dark basemap pill surfaces — neutral-700 / neutral-800 / white (inverted brightness from light). */
+export declare const MARKER_DARK_PILL: {
+    readonly hovered: string;
+    readonly expanded: string;
+    readonly selected: "#ffffff";
+};
+/**
+ * Default pill color config for a given theme. Pass as `colorConfig` on `MapMarker` to
+ * override individual values while keeping the rest as theme defaults.
+ */
+export declare const defaultMarkerColorConfig: (theme: MapTheme) => Required<MarkerColorConfig>;
+/**
+ * Single source of truth for JS-resolved marker colors. Pill colors default to the theme
+ * palette via `defaultMarkerColorConfig`; pass `config` to override any subset.
+ */
+export declare const resolveMarkerColors: (fillColor: string, state: MarkerState, theme: MapTheme, config?: MarkerColorConfig) => ResolvedMarkerColors;

package/src/markers/shared/useMarkerColors.d.ts

@@ -0,0 +1,23 @@
+import { MARKER_DARK_PILL, MARKER_LIGHT_PILL, defaultMarkerColorConfig, resolveMarkerColors } from "./markerColors";
+export type MarkerColorHelpers = Readonly<{
+    defaultMarkerColorConfig: typeof defaultMarkerColorConfig;
+    resolveMarkerColors: typeof resolveMarkerColors;
+    MARKER_DARK_PILL: typeof MARKER_DARK_PILL;
+    MARKER_LIGHT_PILL: typeof MARKER_LIGHT_PILL;
+}>;
+/**
+ * Build-your-own hook: stable references to theme-aware marker color primitives.
+ *
+ * Returns the `defaultMarkerColorConfig` factory and `resolveMarkerColors` resolver
+ * for consumers building custom marker components that need to stay visually
+ * consistent with `MapMarker`'s pill/indicator color system.
+ *
+ * @example
+ * ```tsx
+ * const { defaultMarkerColorConfig, resolveMarkerColors } = useMarkerColors();
+ * const config  = defaultMarkerColorConfig(theme);
+ * const colors  = resolveMarkerColors(fillColor, state, theme, config);
+ * // Spread colors.cssVars onto the marker root element.
+ * ```
+ */
+export declare const useMarkerColors: () => MarkerColorHelpers;

package/src/markers/stories/demoes/AnimationCircleVsPillDemo.d.ts

@@ -0,0 +1,7 @@
+import { type ReactElement } from "react";
+type AnimationCircleVsPillDemoProps = {
+    readonly markerColor: string;
+    readonly longLabel: string;
+};
+export declare const AnimationCircleVsPillDemo: ({ markerColor, longLabel }: AnimationCircleVsPillDemoProps) => ReactElement;
+export {};

package/src/markers/stories/demoes/CircleIconGuidanceDemo.d.ts

@@ -0,0 +1,2 @@
+import type { ReactElement } from "react";
+export declare const CircleIconGuidanceDemo: () => ReactElement;

package/src/markers/stories/demoes/DefaultDemo.d.ts

@@ -0,0 +1,14 @@
+import type { ReactElement } from "react";
+import type { MapTheme } from "../../../core/types";
+import type { MarkerDomSize, MarkerState } from "../../model/markerDomTypes";
+type DefaultDemoProps = {
+    readonly size: MarkerDomSize;
+    readonly state: MarkerState;
+    readonly theme: MapTheme;
+    readonly direction: number | undefined;
+    readonly stickMode: boolean;
+    readonly showIcon: boolean;
+    readonly label: string;
+};
+export declare const DefaultDemo: ({ size, state, theme, direction, stickMode, showIcon, label, }: DefaultDemoProps) => ReactElement;
+export {};

package/src/markers/stories/demoes/DirectionBehaviorDemo.d.ts

@@ -0,0 +1,2 @@
+import type { ReactElement } from "react";
+export declare const DirectionBehaviorDemo: () => ReactElement;

package/src/markers/stories/demoes/PillLabelLengthsDemo.d.ts

@@ -0,0 +1,2 @@
+import type { ReactElement } from "react";
+export declare const PillLabelLengthsDemo: () => ReactElement;

package/src/markers/stories/demoes/StatesDemo.d.ts

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

package/src/markers/stories/demoes/StickModeDemo.d.ts

@@ -0,0 +1,2 @@
+import type { ReactElement } from "react";
+export declare const StickModeDemo: () => ReactElement;

package/src/markers/stories/demoes/StickModePlaygroundDemo.d.ts

@@ -0,0 +1,10 @@
+import { type ReactElement } from "react";
+import type { MapTheme } from "../../../core/types";
+import type { MarkerDomSize, MarkerState } from "../../model/markerDomTypes";
+type StickModePlaygroundDemoProps = {
+    readonly size: MarkerDomSize;
+    readonly state: MarkerState;
+    readonly theme: MapTheme;
+};
+export declare const StickModePlaygroundDemo: ({ size, state, theme }: StickModePlaygroundDemoProps) => ReactElement;
+export {};

package/src/markers/stories/helpers/AbsoluteGridPicker.d.ts

@@ -0,0 +1,17 @@
+import { type ReactElement } from "react";
+type LineMode = "to-origin" | "to-anchor" | "polar";
+type AbsoluteGridPickerProps = {
+    readonly width: number;
+    readonly height: number;
+    readonly anchorX: number;
+    readonly anchorY: number;
+    readonly targetX: number;
+    readonly targetY: number;
+    readonly onChange: (x: number, y: number) => void;
+    readonly lineMode?: LineMode;
+    readonly title?: string;
+    readonly anchorLabel?: string;
+    readonly targetLabel?: string;
+};
+export declare const AbsoluteGridPicker: ({ width, height, anchorX, anchorY, targetX, targetY, onChange, lineMode, title, anchorLabel, targetLabel, }: AbsoluteGridPickerProps) => ReactElement;
+export {};

package/src/markers/stories/helpers/InlineLabel.d.ts

@@ -0,0 +1,4 @@
+import type { ReactElement, ReactNode } from "react";
+export declare const InlineLabel: ({ children }: {
+    children: ReactNode;
+}) => ReactElement;

package/src/markers/stories/helpers/InlineSlider.d.ts

@@ -0,0 +1,11 @@
+import type { ReactElement } from "react";
+type InlineSliderProps = {
+    readonly label: string;
+    readonly value: number;
+    readonly min: number;
+    readonly max: number;
+    readonly onChange: (value: number) => void;
+    readonly readout?: string;
+};
+export declare const InlineSlider: ({ label, value, min, max, onChange, readout }: InlineSliderProps) => ReactElement;
+export {};

package/src/markers/stories/helpers/LabeledMarker.d.ts

@@ -0,0 +1,7 @@
+import type { ReactElement, ReactNode } from "react";
+type LabeledMarkerProps = {
+    readonly caption: ReactNode;
+    readonly children: ReactElement;
+};
+export declare const LabeledMarker: ({ caption, children }: LabeledMarkerProps) => ReactElement;
+export {};

package/src/markers/stories/helpers/MarkerRow.d.ts

@@ -0,0 +1,4 @@
+import type { ReactElement, ReactNode } from "react";
+export declare const MarkerRow: ({ children }: {
+    children: ReactNode;
+}) => ReactElement;

package/src/markers/stories/helpers/SectionHeader.d.ts

@@ -0,0 +1,4 @@
+import type { ReactElement, ReactNode } from "react";
+export declare const SectionHeader: ({ children }: {
+    children: ReactNode;
+}) => ReactElement;

package/src/markers/stories/helpers/StatesMarkerCell.d.ts

@@ -0,0 +1,15 @@
+import { type ReactElement } from "react";
+import type { MapTheme } from "../../../core/types";
+import type { MarkerState } from "../../model/markerDomTypes";
+type StatesMarkerCellHandlers = {
+    readonly onClick: () => void;
+    readonly onMouseEnter: () => void;
+    readonly onMouseLeave: () => void;
+};
+type StatesMarkerCellProps = {
+    readonly label: string;
+    readonly theme: MapTheme;
+    readonly children: (state: MarkerState, handlers: StatesMarkerCellHandlers) => ReactElement;
+};
+export declare const StatesMarkerCell: ({ label, theme, children }: StatesMarkerCellProps) => ReactElement;
+export {};

package/src/markers/stories/helpers/ThemedPreview.d.ts

@@ -0,0 +1,10 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { MapTheme } from "../../../core/types";
+type ThemedPreviewProps = {
+    readonly theme: MapTheme;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    readonly children: ReactNode;
+};
+export declare const ThemedPreview: ({ theme, className, style, children }: ThemedPreviewProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/src/markers/stories/helpers/mapMarkerStoryConstants.d.ts

@@ -0,0 +1,4 @@
+export declare const MARKER_COLOR = "#2563eb";
+export declare const MAP_MARKER_SIZES: ("xs" | "sm" | "md" | "lg" | "xl")[];
+export declare const MAP_MARKER_STATES: ("default" | "expanded" | "selected" | "hovered")[];
+export declare const MAP_MARKER_LONG_LABEL = "Very long fleet asset identifier that should truncate with ellipsis when it exceeds the pill max width";

package/src/panel/Panel.d.ts

@@ -0,0 +1,60 @@
+import { type Placement } from "@floating-ui/react";
+import { ReactNode } from "react";
+import "./Panel.css";
+export type PanelContentScroll = "shell" | "internal";
+export type PanelProps = Readonly<{
+    /** Anchor element. The panel positions itself next to this element. */
+    anchor: HTMLElement | null;
+    /** Placement preference. Default: "bottom". */
+    placement?: Placement;
+    /** Called when the panel is dismissed (Escape key or pointer-down outside). */
+    onDismiss?: () => void;
+    /**
+     * Accessible label for the close button. Consumers should pass a translated
+     * string (e.g. `t("panel.close")`). Defaults to `"Close"`.
+     */
+    closeLabel?: string;
+    /**
+     * Called exactly once when the panel first becomes visible (isCommitted
+     * transitions from false to true). Does not re-fire on subsequent Floating
+     * UI recomputes. Fires again on the next open-cycle (anchor null → non-null).
+     *
+     * @param panelRect        Bounding rect of the floating panel element.
+     * @param anchorRect       Bounding rect of the anchor element.
+     * @param placement        Resolved Floating UI placement (after flip).
+     * @param panelScrollHeight Natural content height of the inner scroll div —
+     *   greater than `panelRect.height` when content is scroll-constrained.
+     */
+    onCommit?: (panelRect: DOMRect, anchorRect: DOMRect, placement: Placement, panelScrollHeight: number) => void;
+    /**
+     * Map container element. Used as the shift boundary so panels cannot bleed
+     * outside the map viewport. Falls back to clipping ancestors when null.
+     */
+    containerEl?: HTMLElement | null;
+    /** Accessible label for the panel dialog, announced by screen readers on open. */
+    "aria-label"?: string;
+    /**
+     * Where vertical overflow scrolls. Default `shell` keeps `overflow-auto` on the
+     * scroll slot; `internal` uses `overflow-hidden` so panel content owns scroll.
+     */
+    contentScroll?: PanelContentScroll;
+    children: ReactNode;
+}>;
+/**
+ * Renders a marker info panel positioned next to its anchor with Floating UI.
+ *
+ * Middleware chain: `offset(8) → flip() → shift(8) → hide`
+ *
+ * Animation state is driven by the `data-panel` attribute:
+ *   ""         — element is in DOM (for Floating UI to measure) but hidden via
+ *                CSS `visibility: hidden` so the pre-commit translate(0,0)
+ *                position is never visible.
+ *   "open"     — fades in via CSS opacity transition once placement is committed.
+ *   "closing"  — fades out during the EXIT_DURATION_MS window before unmount.
+ *
+ * @internal
+ */
+export declare const Panel: {
+    ({ anchor, placement, onDismiss, closeLabel, onCommit, containerEl, "aria-label": ariaLabel, contentScroll, children, }: PanelProps): import("react/jsx-runtime").JSX.Element | null;
+    displayName: string;
+};