@swisper.ai/web-map 0.0.2

package/src/map-view.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "../../int-eslint-config/schemas/component.schema.json",
+  "component": "map-view",
+  "purpose": "Interactive map root that frames a set of points and shares controlled selection and hover state with the MapMarkers drawn inside it.",
+  "useWhen": [
+    "Showing a set of places (search results, venues, offices) as selectable pins on a map",
+    "A map is paired with a list or cards and selecting in one must highlight the other",
+    "The map should frame all given points automatically on load and when the points change"
+  ],
+  "avoidWhen": [
+    "Drawing only custom layers, sources or plain markers with no selection — use web-map/base-map instead",
+    "Showing a single static address with no interaction — a written address or a link to an external map is lighter, since the map engine is loaded on first render",
+    "Listing places where location is not the deciding information — use ui/list instead"
+  ],
+  "uxPrinciples": [
+    "Selection is one shared state: the map, the pins and any list beside it read the same selectedId, so choosing a place anywhere highlights it everywhere",
+    "A place chosen outside the map is eased into view, so the user never selects something they cannot see",
+    "Frame the points the user cares about; don't open on an arbitrary world view when there is data"
+  ],
+  "accessibility": {
+    "required": [
+      "Pass an ariaLabel that says what the map shows (e.g. 'Restaurants near you'), not just 'Map'",
+      "Give every MapMarker a label, since it is the accessible name of the marker button",
+      "Offer the same places in a non-map form (a list or cards) alongside, because panning and zooming the map is not usable by every user"
+    ],
+    "keyboard": [
+      "Tab moves through the marker buttons; Enter or Space selects the focused marker",
+      "MapLibre's default keyboard handling applies when the map canvas has focus: arrow keys pan, + and - zoom"
+    ],
+    "aria": [
+      "The root is role=application with aria-label=ariaLabel",
+      "aria-invalid is set on the root while hasError is true",
+      "Each MapMarker renders a button with aria-pressed reflecting selection"
+    ],
+    "focus": [
+      "Marker buttons are the tab stops inside the map; the map does not move focus on selection",
+      "Hover state is driven by pointer enter/leave only, not by keyboard focus"
+    ]
+  },
+  "behaviour": {
+    "states": ["default", "loading", "error", "empty (no fitPoints)"],
+    "rules": [
+      "fitPoints is framed on load and every time a new array is passed; one point zooms to SINGLE_POINT_ZOOM, an empty array shows the whole world",
+      "fitPoints is compared by identity: memoise it, or every re-render (e.g. from a selection or hover change) re-frames the map and undoes the user's pan and zoom",
+      "selectedId and hoveredId are controlled: MapView only reports clicks and pointer enter/leave through onSelect and onHover; the parent stores the id and passes it back",
+      "Clicking a marker does not reach the map, and MapView never clears the selection on a map click; deselecting is up to the parent",
+      "flyToSelected=true eases the map to a marker when it becomes selected; a MapMarker's flyToOnSelect overrides it per marker",
+      "isLoading hides the map tiles behind the plain background without showing a spinner; hasError hides the map, disables pointer input and shows errorLabel over an error tint",
+      "MapView fills its parent (size-full): the parent or className must give it an explicit height",
+      "The ids passed to MapMarker are generic (string or number); onSelect and onHover only ever return ids the caller passed in"
+    ]
+  },
+  "composition": {
+    "allowedParents": [],
+    "allowedChildren": [
+      "web-map/map-marker",
+      "web-map/map-user-location",
+      "web-map/Source",
+      "web-map/Layer",
+      "web-map/Marker",
+      "custom children that read web-map/useMapView"
+    ],
+    "avoidCombinations": [
+      "web-map/map-marker outside a MapView — it throws, because it reads the MapView context",
+      "A MapView without a sized parent — it collapses to zero height"
+    ],
+    "contexts": [
+      "page section with an explicit height",
+      "split view beside a results list or cards",
+      "detail panel"
+    ]
+  },
+  "content": {
+    "labelRules": [
+      "ariaLabel describes the content of the map ('Restaurants near you', 'Office locations'), not the widget"
+    ],
+    "helperTextRules": [],
+    "errorRules": [
+      "errorLabel says the map could not load and what to do next, in one short sentence (default: 'Could not load map. Try again later.')",
+      "Pass errorLabel already translated; the package has no i18n dependency"
+    ]
+  },
+  "aiDecisionRules": [
+    {
+      "condition": "The places on the map are also listed beside it",
+      "decision": "Keep selectedId and hoveredId in the shared parent and pass them to both the MapView and the list",
+      "reason": "Both views stay in sync and a selection from the list eases the marker into view"
+    },
+    {
+      "condition": "fitPoints is derived from data (places.map(...))",
+      "decision": "Wrap it in useMemo keyed on the data",
+      "reason": "A new array on every render re-frames the map and snaps it back while the user pans"
+    },
+    {
+      "condition": "The map only needs custom sources, layers or markers without selection",
+      "decision": "Use web-map/base-map with initialViewState and bounds",
+      "reason": "MapView's selection context is unused weight, and MapMarker would not be needed"
+    },
+    {
+      "condition": "The map style must come from configuration",
+      "decision": "Pass mapStyleUrl explicitly from the app",
+      "reason": "The library does not read env vars such as VITE_MAP_STYLE_URL; without the prop it uses OpenFreeMap Liberty"
+    }
+  ],
+  "relatedComponents": [
+    "web-map/base-map",
+    "web-map/map-marker",
+    "web-map/map-pin",
+    "web-map/map-user-location",
+    "ui/list"
+  ]
+}

package/src/map-view.stories.tsx

@@ -0,0 +1,174 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+
+import { TooltipProvider } from '@swisper.ai/ui';
+
+import { PLACE_POINTS, PLACES, USER_LOCATION } from './__storybook__/fixtures';
+import { DEFAULT_FIT_BOUNDS_PADDING, DEFAULT_MAP_STYLE_URL } from './constants';
+import { MapMarker } from './map-marker';
+import { MapPin } from './map-pin';
+import { MapUserLocation } from './map-user-location';
+import { MapView, type MapViewProps } from './map-view';
+
+function MapViewDemo(args: Partial<MapViewProps<string>>) {
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [hoveredId, setHoveredId] = useState<string | null>(null);
+
+  return (
+    <MapView<string>
+      testId="map-view-story"
+      ariaLabel="Restaurants near you"
+      fitPoints={PLACE_POINTS}
+      selectedId={selectedId}
+      hoveredId={hoveredId}
+      onSelect={setSelectedId}
+      onHover={setHoveredId}
+      {...args}
+    >
+      {PLACES.map((place) => (
+        <MapMarker
+          key={place.id}
+          id={place.id}
+          longitude={place.lngLat[0]}
+          latitude={place.lngLat[1]}
+          label={place.label}
+        >
+          <MapPin label={place.label} value={place.value} />
+        </MapMarker>
+      ))}
+      <MapUserLocation coordinates={USER_LOCATION} />
+    </MapView>
+  );
+}
+
+const meta: Meta<typeof MapViewDemo> = {
+  title: 'Map/MapView',
+  component: MapViewDemo,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <TooltipProvider>
+        <div className="h-[600px] w-[800px]">
+          <Story />
+        </div>
+      </TooltipProvider>
+    ),
+  ],
+  // `selectedId`, `hoveredId`, `onSelect` and `onHover` stay out of meta args: the demo owns them
+  // in state, and an arg would override it and break selecting a pin. Callbacks are logged through
+  // their `action` argTypes (`storybook/test` is not a dependency here).
+  args: {
+    testId: 'map-view-story',
+    ariaLabel: 'Restaurants near you',
+    fitPoints: PLACE_POINTS,
+    flyToSelected: true,
+    fitBoundsPadding: DEFAULT_FIT_BOUNDS_PADDING,
+    isLoading: false,
+    hasError: false,
+    errorLabel: 'Could not load map. Try again later.',
+  },
+  argTypes: {
+    fitPoints: {
+      control: 'object',
+      description:
+        '`[lng, lat]` points the map frames on load and whenever they change; empty shows the whole world.',
+    },
+    selectedId: {
+      control: false,
+      description:
+        "Id of the selected `MapMarker`, controlled by the parent. Owned by the demo's state here.",
+      table: { defaultValue: { summary: 'null' } },
+    },
+    hoveredId: {
+      control: false,
+      description:
+        "Id of the hovered `MapMarker`, controlled by the parent. Owned by the demo's state here.",
+      table: { defaultValue: { summary: 'null' } },
+    },
+    onSelect: {
+      control: false,
+      description:
+        "Called with a marker's id when it is clicked; store it and pass it back as `selectedId`.",
+    },
+    onHover: {
+      control: false,
+      description:
+        "Called with a marker's id on pointer enter and `null` on leave; pass it back as `hoveredId`.",
+    },
+    flyToSelected: {
+      control: 'boolean',
+      description:
+        'Eases to a marker when it becomes selected, so one chosen from outside the map is never off screen.',
+      table: { defaultValue: { summary: 'true' } },
+    },
+    testId: {
+      control: 'text',
+      description: 'Sets `data-testid` on the map root.',
+    },
+    ariaLabel: {
+      control: 'text',
+      description: 'Accessible name of the map region; describe what it shows.',
+    },
+    isLoading: {
+      control: 'boolean',
+      description: 'Hides the map tiles behind the background while its data is loading.',
+      table: { defaultValue: { summary: 'false' } },
+    },
+    hasError: {
+      control: 'boolean',
+      description: 'Hides the map, disables interaction and shows `errorLabel`.',
+      table: { defaultValue: { summary: 'false' } },
+    },
+    errorLabel: {
+      control: 'text',
+      description: 'Message shown when `hasError` is set; pass a translated string.',
+      table: { defaultValue: { summary: 'Could not load map. Try again later.' } },
+    },
+    fitBoundsPadding: {
+      control: 'number',
+      description: 'Padding in px kept around `fitPoints` when framing them.',
+      table: { defaultValue: { summary: String(DEFAULT_FIT_BOUNDS_PADDING) } },
+    },
+    mapStyleUrl: {
+      control: 'text',
+      description: 'Style JSON URL; defaults to OpenFreeMap Liberty.',
+      table: { defaultValue: { summary: DEFAULT_MAP_STYLE_URL } },
+    },
+    children: {
+      control: false,
+      description: 'The `MapMarker`s and `MapUserLocation` drawn on the map.',
+    },
+    className: {
+      control: 'text',
+      description: 'Extra classes merged onto the root.',
+    },
+    onLoad: {
+      action: 'loaded',
+      description: 'Called once the map style has loaded and `fitPoints` are framed.',
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof MapViewDemo>;
+
+export const Default: Story = {};
+
+export const Loading: Story = {
+  args: { isLoading: true },
+};
+
+export const WithError: Story = {
+  args: { hasError: true },
+};
+
+/** A translated error message passed through `errorLabel`. */
+export const CustomErrorLabel: Story = {
+  args: { hasError: true, errorLabel: 'Karte konnte nicht geladen werden.' },
+};
+
+/** With no `fitPoints` there is nothing to frame, so the map shows the whole world. */
+export const EmptyPoints: Story = {
+  args: { fitPoints: [] },
+};

package/src/map-view.tsx

@@ -0,0 +1,86 @@
+import type { MapRef } from '@vis.gl/react-maplibre';
+import { useMemo, useRef, type ReactNode } from 'react';
+
+import { BaseMap } from './base-map';
+import { MapViewContext, type MapItemId, type MapViewContextValue } from './map-context';
+import {
+  getBoundsCentroid,
+  getBoundsFromPoints,
+  type MapLngLat,
+} from './utils/get-bounds-from-points';
+
+export interface MapViewProps<TId extends MapItemId = MapItemId> {
+  /** Points the map frames on load and whenever they change. */
+  fitPoints: MapLngLat[];
+  selectedId?: TId | null;
+  hoveredId?: TId | null;
+  onSelect?: (id: TId) => void;
+  onHover?: (id: TId | null) => void;
+  /** Ease to a marker when it becomes selected, so it is never off screen. */
+  flyToSelected?: boolean;
+  children?: ReactNode;
+  testId: string;
+  ariaLabel: string;
+  className?: string;
+  hasError?: boolean;
+  isLoading?: boolean;
+  fitBoundsPadding?: number;
+  mapStyleUrl?: string;
+  onLoad?: () => void;
+  /** Shown when `hasError` is set; pass a translated string. */
+  errorLabel?: string;
+}
+
+/**
+ * Interactive map root: frames `fitPoints` and shares selection / hover state
+ * with the `MapMarker`s composed inside it.
+ */
+export function MapView<TId extends MapItemId = MapItemId>({
+  fitPoints,
+  selectedId = null,
+  hoveredId = null,
+  onSelect,
+  onHover,
+  flyToSelected = true,
+  children,
+  ...baseMapProps
+}: MapViewProps<TId>) {
+  const mapRef = useRef<MapRef>(null);
+
+  const bounds = useMemo(() => getBoundsFromPoints(fitPoints), [fitPoints]);
+
+  const initialViewState = useMemo(() => {
+    if (bounds) {
+      // With a bounds fit called on load/change we still need an initial
+      // center or MapGL defaults to null-island. Use the geographic centroid.
+      return { center: getBoundsCentroid(bounds), zoom: 12 };
+    }
+    return { center: [0, 0] as MapLngLat, zoom: 2 };
+  }, [bounds]);
+
+  const value = useMemo<MapViewContextValue>(
+    () => ({
+      mapRef,
+      selectedId,
+      hoveredId,
+      flyToSelected,
+      // Markers deal in the widened id type; the caller only ever gets back ids it passed in.
+      onSelect: onSelect as MapViewContextValue['onSelect'],
+      onHover: onHover as MapViewContextValue['onHover'],
+    }),
+    [selectedId, hoveredId, flyToSelected, onSelect, onHover],
+  );
+
+  return (
+    <MapViewContext.Provider value={value}>
+      <BaseMap
+        {...baseMapProps}
+        initialViewState={initialViewState}
+        bounds={bounds}
+        mapRef={mapRef}
+      >
+        {children}
+      </BaseMap>
+    </MapViewContext.Provider>
+  );
+}

package/src/user-location-pin.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "../../int-eslint-config/schemas/component.schema.json",
+  "component": "user-location-pin",
+  "purpose": "The marker for the user's own position: a blue dot with a white ring, with a tooltip and accessible name.",
+  "useWhen": [
+    "Rendering the default user-position marker, which web-map/map-user-location does for you",
+    "Showing the user-position dot outside a map, such as in a map legend"
+  ],
+  "avoidWhen": [
+    "Placing it on a map directly — wrap it in web-map/map-user-location, which positions it and hides it while the position is unknown",
+    "Marking places — use web-map/map-pin inside web-map/map-marker instead"
+  ],
+  "uxPrinciples": ["One distinct look for 'you are here' that is never confused with a place pin"],
+  "accessibility": {
+    "required": [
+      "Pass a translated label; it is both the accessible name and the tooltip text",
+      "Render it under a ui/TooltipProvider; the tooltip requires one"
+    ],
+    "keyboard": ["None; the dot is not focusable, so its tooltip opens on pointer hover only"],
+    "aria": ["role=img with aria-label=label"],
+    "focus": ["No tab stop"]
+  },
+  "behaviour": {
+    "states": ["default", "tooltip open on hover"],
+    "rules": [
+      "Hovering the dot shows label in a ui/tooltip",
+      "className is merged onto the dot, so it can change its size or colour"
+    ]
+  },
+  "composition": {
+    "allowedParents": ["web-map/map-user-location"],
+    "allowedChildren": [],
+    "avoidCombinations": [
+      "Inside a web-map/map-marker — the user's position is not a selectable place"
+    ],
+    "contexts": ["map overlay", "map legend"]
+  },
+  "content": {
+    "labelRules": [
+      "label names the dot from the user's point of view, e.g. 'My location' (the default); pass it translated"
+    ],
+    "helperTextRules": [],
+    "errorRules": []
+  },
+  "aiDecisionRules": [
+    {
+      "condition": "The user's position should appear on a map",
+      "decision": "Render web-map/map-user-location with the coordinates rather than this pin directly",
+      "reason": "MapUserLocation positions the dot and renders nothing until the position is known"
+    },
+    {
+      "condition": "The app has no ui/TooltipProvider above the map",
+      "decision": "Add one",
+      "reason": "The pin's tooltip needs a provider"
+    }
+  ],
+  "relatedComponents": ["web-map/map-user-location", "web-map/map-pin", "ui/tooltip"]
+}

package/src/user-location-pin.stories.tsx

@@ -0,0 +1,43 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { UserLocationPin } from './user-location-pin';
+
+const meta: Meta<typeof UserLocationPin> = {
+  title: 'Map/UserLocationPin',
+  component: UserLocationPin,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div className="max-w-[420px] mx-auto flex items-center justify-center bg-[#252931] p-32 rounded-lg">
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    className: '',
+    label: 'My location',
+  },
+  argTypes: {
+    label: {
+      control: 'text',
+      description: 'Tooltip and accessible name of the dot; pass a translated string.',
+      table: { defaultValue: { summary: 'My location' } },
+    },
+    className: {
+      control: 'text',
+      description: 'Extra classes merged onto the dot — use to override its size or colour.',
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof UserLocationPin>;
+
+export const Default: Story = {};
+
+export const Playground: Story = {
+  args: {
+    className: 'size-16',
+  },
+};

package/src/user-location-pin.tsx

@@ -0,0 +1,27 @@
+import { Tooltip, cn } from '@swisper.ai/ui';
+
+export interface UserLocationPinProps {
+  className?: string;
+  /** Tooltip and accessible name; pass a translated string. */
+  label?: string;
+}
+
+/** Map marker for the user's own position: a blue dot with a white ring. */
+export function UserLocationPin({ className, label = 'My location' }: UserLocationPinProps) {
+  return (
+    <Tooltip tooltip={label}>
+      <div
+        data-testid="user-location-pin"
+        // The dot is a bare `div`, so without a label it is invisible to
+        // screen readers — the tooltip only covers pointer users.
+        role="img"
+        aria-label={label}
+        className={cn(
+          'size-3.5 rounded-full bg-blue-500 ring-2 ring-white',
+          'shadow-[0px_1px_3px_rgba(0,0,0,0.35)]',
+          className,
+        )}
+      />
+    </Tooltip>
+  );
+}

package/src/utils/get-bounds-from-points.ts

@@ -0,0 +1,39 @@
+export type MapLngLat = [number, number];
+export type MapBounds = [MapLngLat, MapLngLat];
+
+/**
+ * Computes a southwest/northeast bounding box from lng/lat points.
+ * Returns null when there are no points.
+ */
+export function getBoundsFromPoints(points: MapLngLat[]): MapBounds | null {
+  if (points.length === 0) {
+    return null;
+  }
+
+  let minLng = points[0][0];
+  let minLat = points[0][1];
+  let maxLng = points[0][0];
+  let maxLat = points[0][1];
+
+  for (const [lng, lat] of points) {
+    minLng = Math.min(minLng, lng);
+    minLat = Math.min(minLat, lat);
+    maxLng = Math.max(maxLng, lng);
+    maxLat = Math.max(maxLat, lat);
+  }
+
+  return [
+    [minLng, minLat],
+    [maxLng, maxLat],
+  ];
+}
+
+export function getBoundsCentroid(bounds: MapBounds): MapLngLat {
+  const [[minLng, minLat], [maxLng, maxLat]] = bounds;
+  return [(minLng + maxLng) / 2, (minLat + maxLat) / 2];
+}
+
+export function isDegenerateBounds(bounds: MapBounds): boolean {
+  const [[minLng, minLat], [maxLng, maxLat]] = bounds;
+  return minLng === maxLng && minLat === maxLat;
+}

package/src/worker/maplibre-worker-source.ts

@@ -0,0 +1,2 @@
+// The string is produced at build time by `vite-plugin-maplibre-worker.ts`.
+export { default } from 'virtual:maplibre-worker-source';

package/src/worker/virtual-maplibre-worker-source.d.ts

@@ -0,0 +1,5 @@
+declare module 'virtual:maplibre-worker-source' {
+  /** maplibre's worker as one self-contained script. */
+  const source: string;
+  export default source;
+}

package/tailwind.css

@@ -0,0 +1,9 @@
+/*
+ * Tailwind v4 sources for apps that use @swisper.ai/web-map:
+ *
+ *   @import "@swisper.ai/web-map/tailwind.css";
+ *
+ * Tailwind skips node_modules by default, so without this the package's class names
+ * are never generated and its components render without layout or colors.
+ */
+@source "./dist";