@swisper.ai/web-map 0.0.2

package/src/base-map.stories.tsx

@@ -0,0 +1,123 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { PLACE_POINTS, PLACES } from './__storybook__/fixtures';
+import { BaseMap } from './base-map';
+import { DEFAULT_FIT_BOUNDS_PADDING, DEFAULT_MAP_STYLE_URL } from './constants';
+import { getBoundsCentroid, getBoundsFromPoints } from './utils/get-bounds-from-points';
+
+const PLACE_BOUNDS = getBoundsFromPoints(PLACE_POINTS);
+
+const meta: Meta<typeof BaseMap> = {
+  title: 'Map/BaseMap',
+  component: BaseMap,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div className="h-[500px] w-[700px]">
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    testId: 'base-map-story',
+    ariaLabel: 'Map',
+    initialViewState: {
+      center: PLACE_BOUNDS ? getBoundsCentroid(PLACE_BOUNDS) : null,
+      zoom: 12,
+    },
+    isLoading: false,
+    hasError: false,
+    bounds: null,
+    fitBoundsPadding: DEFAULT_FIT_BOUNDS_PADDING,
+    errorLabel: 'Could not load map. Try again later.',
+  },
+  // Callbacks are logged through their `action` argTypes (`storybook/test` is not a dependency here).
+  argTypes: {
+    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, e.g. `Restaurants near you`.',
+    },
+    initialViewState: {
+      control: 'object',
+      description:
+        'Centre (`[lng, lat]`) and zoom the map opens at, before any `bounds` fit. Read once on mount.',
+    },
+    bounds: {
+      control: 'object',
+      description:
+        'South-west and north-east corners to frame on load and whenever they change. A single point zooms to `SINGLE_POINT_ZOOM`.',
+      table: { defaultValue: { summary: 'null' } },
+    },
+    fitBoundsPadding: {
+      control: 'number',
+      description: 'Padding in px kept around `bounds` when fitting them.',
+      table: { defaultValue: { summary: String(DEFAULT_FIT_BOUNDS_PADDING) } },
+    },
+    isLoading: {
+      control: 'boolean',
+      description: 'Hides the map tiles behind the background while data for it is loading.',
+      table: { defaultValue: { summary: 'false' } },
+    },
+    hasError: {
+      control: 'boolean',
+      description: 'Hides the map, disables interaction and shows `errorLabel` over an error tint.',
+      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.' } },
+    },
+    mapStyleUrl: {
+      control: 'text',
+      description: 'Style JSON URL; defaults to OpenFreeMap Liberty.',
+      table: { defaultValue: { summary: DEFAULT_MAP_STYLE_URL } },
+    },
+    mapRef: {
+      control: false,
+      description: 'Ref to the underlying MapLibre map, for imperative calls like `easeTo`.',
+    },
+    children: {
+      control: false,
+      description: 'Map layers and markers rendered inside the map.',
+    },
+    className: {
+      control: 'text',
+      description: 'Extra classes merged onto the root.',
+    },
+    onLoad: {
+      action: 'loaded',
+      description: 'Called once the map style has loaded (after any initial `bounds` fit).',
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof BaseMap>;
+
+/** Centred on `initialViewState`, with no bounds to fit. */
+export const Default: Story = {};
+
+/** Frames every point in `bounds` on load. */
+export const FitBounds: Story = {
+  args: { bounds: PLACE_BOUNDS },
+};
+
+/** A single point has no area to fit, so the map zooms in to `SINGLE_POINT_ZOOM`. */
+export const SinglePoint: Story = {
+  args: { bounds: [PLACES[0].lngLat, PLACES[0].lngLat] },
+};
+
+export const Loading: Story = {
+  args: { isLoading: true },
+};
+
+export const WithError: Story = {
+  args: { hasError: true, errorLabel: 'Could not load map. Try again later.' },
+};

package/src/base-map.tsx

@@ -0,0 +1,137 @@
+import { Map as MapGL } from '@vis.gl/react-maplibre';
+import type { MapRef } from '@vis.gl/react-maplibre';
+import type { Map as MapLibreMap } from 'maplibre-gl';
+import { useEffect, useRef, type ReactNode, type RefObject } from 'react';
+
+import { ErrorIcon } from '@swisper.ai/icons';
+import { Typography } from '@swisper.ai/ui';
+import { cn } from '@swisper.ai/web-core';
+
+import { DEFAULT_FIT_BOUNDS_PADDING, resolveMapStyleUrl, SINGLE_POINT_ZOOM } from './constants';
+import { loadMapLib } from './load-map-lib';
+import { isDegenerateBounds, type MapBounds, type MapLngLat } from './utils/get-bounds-from-points';
+
+import 'maplibre-gl/dist/maplibre-gl.css';
+
+interface BaseMapProps {
+  children?: ReactNode;
+  className?: string;
+  testId: string;
+  ariaLabel: string;
+  hasError?: boolean;
+  isLoading?: boolean;
+  initialViewState: { center: MapLngLat | null; zoom: number };
+  bounds?: MapBounds | null;
+  fitBoundsPadding?: number;
+  mapStyleUrl?: string;
+  mapRef?: RefObject<MapRef>;
+  onLoad?: () => void;
+  /**
+   * Shown when `hasError` is set. A prop rather than a translation lookup, so the
+   * package does not tie consumers to one i18n library or namespace.
+   */
+  errorLabel?: string;
+}
+
+function fitMapToBounds(map: MapLibreMap, bounds: MapBounds, padding: number) {
+  if (isDegenerateBounds(bounds)) {
+    const [[lng, lat]] = bounds;
+    map.setCenter([lng, lat]);
+    map.setZoom(SINGLE_POINT_ZOOM);
+    return;
+  }
+
+  map.fitBounds(bounds, { padding, duration: 0 });
+}
+
+export function BaseMap({
+  children,
+  className,
+  testId,
+  ariaLabel,
+  hasError,
+  isLoading,
+  initialViewState,
+  bounds = null,
+  fitBoundsPadding = DEFAULT_FIT_BOUNDS_PADDING,
+  mapStyleUrl,
+  mapRef: externalMapRef,
+  onLoad,
+  errorLabel = 'Could not load map. Try again later.',
+}: BaseMapProps) {
+  const internalMapRef = useRef<MapRef>(null);
+  const mapRef = externalMapRef ?? internalMapRef;
+  const resolvedMapStyleUrl = resolveMapStyleUrl(mapStyleUrl);
+
+  useEffect(() => {
+    if (!bounds) {
+      return;
+    }
+
+    const map = mapRef.current?.getMap();
+    if (!map) {
+      return;
+    }
+
+    fitMapToBounds(map, bounds, fitBoundsPadding);
+  }, [bounds, fitBoundsPadding, mapRef]);
+
+  return (
+    <div
+      data-testid={testId}
+      data-rounded={true}
+      data-loading={isLoading}
+      aria-invalid={hasError}
+      data-error={hasError}
+      className={cn(
+        'relative size-full',
+        'bg-[#f8f4f1]',
+        'data-[error=true]:bg-[#EB0000]/10',
+        'data-[rounded=true]:rounded-lg overflow-hidden',
+        className,
+      )}
+      role="application"
+      aria-label={ariaLabel}
+    >
+      {hasError && <BaseMapErrorLayer label={errorLabel} />}
+
+      <MapGL
+        ref={mapRef}
+        mapLib={loadMapLib()}
+        initialViewState={initialViewState}
+        mapStyle={resolvedMapStyleUrl}
+        style={{
+          width: '100%',
+          height: '100%',
+          opacity: isLoading || hasError ? 0 : 1,
+          pointerEvents: hasError ? 'none' : 'auto',
+        }}
+        attributionControl={false}
+        onLoad={() => {
+          if (bounds) {
+            const map = mapRef.current?.getMap();
+            if (map) {
+              fitMapToBounds(map, bounds, fitBoundsPadding);
+            }
+          }
+          onLoad?.();
+        }}
+      >
+        {children}
+      </MapGL>
+    </div>
+  );
+}
+
+function BaseMapErrorLayer({ label }: { label: string }) {
+  return (
+    <div className="absolute inset-0 flex items-center justify-center">
+      <div className="flex flex-col items-center gap-8">
+        <ErrorIcon fontSize="large" />
+        <Typography variant="body-sm" className="text-text-error">
+          {label}
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/constants.ts

@@ -0,0 +1,11 @@
+export const DEFAULT_MAP_STYLE_URL = 'https://tiles.openfreemap.org/styles/liberty';
+export const DEFAULT_FIT_BOUNDS_PADDING = 48;
+export const SINGLE_POINT_ZOOM = 15;
+
+/**
+ * No `import.meta.env` fallback: Vite replaces it when this library is built, so a
+ * consumer's `VITE_MAP_STYLE_URL` would never be read. Pass `mapStyleUrl` instead.
+ */
+export function resolveMapStyleUrl(mapStyleUrl?: string): string {
+  return mapStyleUrl ?? DEFAULT_MAP_STYLE_URL;
+}

package/src/index.css

@@ -0,0 +1 @@
+@import '@swisper.ai/tailwind-config/tailwind.css';

package/src/index.ts

@@ -0,0 +1,32 @@
+export { MapView } from './map-view';
+export { MapMarker, useMapMarker } from './map-marker';
+export { MapPin } from './map-pin';
+export { MapUserLocation } from './map-user-location';
+export { UserLocationPin } from './user-location-pin';
+export { useMapView } from './map-context';
+export { BaseMap } from './base-map';
+export { loadMapLib } from './load-map-lib';
+// The primitives for drawing inside a `BaseMap`, re-exported so consumers compose
+// against this package's copy of react-maplibre — and so read the same map context.
+export { Layer, Marker, Source, useMap } from '@vis.gl/react-maplibre';
+export {
+  DEFAULT_FIT_BOUNDS_PADDING,
+  DEFAULT_MAP_STYLE_URL,
+  SINGLE_POINT_ZOOM,
+  resolveMapStyleUrl,
+} from './constants';
+export {
+  getBoundsCentroid,
+  getBoundsFromPoints,
+  isDegenerateBounds,
+} from './utils/get-bounds-from-points';
+
+export type { MapViewProps } from './map-view';
+export type { MapMarkerProps, MapMarkerState } from './map-marker';
+export type { MapPinProps, MapPinClassNames } from './map-pin';
+export type { MapUserLocationProps } from './map-user-location';
+export type { UserLocationPinProps } from './user-location-pin';
+export type { MapItemId, MapViewContextValue } from './map-context';
+export type { MapBounds, MapLngLat } from './utils/get-bounds-from-points';
+export type { LayerProps, MapRef, MarkerProps, SourceProps } from '@vis.gl/react-maplibre';
+export type { ExpressionSpecification } from 'maplibre-gl';

package/src/load-map-lib.ts

@@ -0,0 +1,25 @@
+import type * as maplibre from 'maplibre-gl';
+
+type MapLib = typeof maplibre;
+
+let mapLib: Promise<MapLib> | undefined;
+
+/**
+ * maplibre-gl, with its worker pointed at a blob URL built from the source this
+ * package ships (see `vite-plugin-maplibre-worker.ts`). Pass it to `<Map mapLib>`.
+ *
+ * Both halves are dynamic imports, so the ~500 kB worker source is fetched with
+ * the first map rather than with every import of the package. Memoised: every
+ * map shares one worker URL.
+ */
+export function loadMapLib(): Promise<MapLib> {
+  mapLib ??= Promise.all([import('maplibre-gl'), import('./worker/maplibre-worker-source')]).then(
+    ([lib, { default: workerSource }]) => {
+      const blob = new Blob([workerSource], { type: 'text/javascript' });
+      lib.setWorkerUrl(URL.createObjectURL(blob));
+      return lib;
+    },
+  );
+
+  return mapLib;
+}

package/src/map-context.tsx

@@ -0,0 +1,25 @@
+import type { MapRef } from '@vis.gl/react-maplibre';
+import { createContext, useContext, type RefObject } from 'react';
+
+export type MapItemId = string | number;
+
+export interface MapViewContextValue {
+  mapRef: RefObject<MapRef>;
+  selectedId: MapItemId | null;
+  hoveredId: MapItemId | null;
+  flyToSelected: boolean;
+  onSelect?: (id: MapItemId) => void;
+  onHover?: (id: MapItemId | null) => void;
+}
+
+export const MapViewContext = createContext<MapViewContextValue | null>(null);
+
+export function useMapView() {
+  const context = useContext(MapViewContext);
+
+  if (!context) {
+    throw new Error('useMapView must be used within a MapView component');
+  }
+
+  return context;
+}

package/src/map-marker.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "../../int-eslint-config/schemas/component.schema.json",
+  "component": "map-marker",
+  "purpose": "A selectable, hoverable point on a MapView that wraps its pin in a button and passes the marker's selection and hover state down to it.",
+  "useWhen": [
+    "Placing a place, result or entity on a web-map/map-view that the user can select",
+    "A pin must change look when its place is selected or hovered, in the map or in a list beside it"
+  ],
+  "avoidWhen": [
+    "Showing the user's own position — use web-map/map-user-location instead",
+    "Drawing a non-interactive marker or a marker on a web-map/base-map — use web-map/Marker instead",
+    "Drawing many hundreds of points — use a web-map/Source with a web-map/Layer instead of one DOM marker each"
+  ],
+  "uxPrinciples": [
+    "A marker reflects shared state: it is selected because the parent says so, whether the click came from the map or from a list",
+    "Hovered and selected markers rise above the others so the active one is never hidden under a neighbour"
+  ],
+  "accessibility": {
+    "required": [
+      "label is required and becomes the button's accessible name; use the place's name",
+      "Do not put interactive elements inside the marker; it is already a button"
+    ],
+    "keyboard": ["Tab focuses the marker button; Enter or Space selects it, the same as a click"],
+    "aria": [
+      "Renders a button with aria-label=label and aria-pressed reflecting selection",
+      "data-selected and data-hovered are set on the button for styling"
+    ],
+    "focus": [
+      "Each marker is one tab stop, in DOM order",
+      "Focus does not set hover state; hover follows the pointer only"
+    ]
+  },
+  "behaviour": {
+    "states": ["default", "hovered", "selected"],
+    "rules": [
+      "Clicking the marker calls the MapView's onSelect with its id and stops the click from reaching the map",
+      "Pointer enter calls onHover with its id and pointer leave calls it with null; the marker is hovered or selected only when the MapView's hoveredId or selectedId equals its id",
+      "When the marker becomes selected it eases the map to its coordinate if flyToOnSelect is true, or, when flyToOnSelect is unset, if the MapView's flyToSelected is true",
+      "anchor sets which side of the marker sits on the coordinate: bottom for callout pins like MapPin, center for dots",
+      "children is either an element, which reads the state through useMapMarker (MapPin does this), or a render function that receives { isSelected, isHovered }",
+      "Stacking: a hovered marker is above a selected one, which is above the rest",
+      "Must be rendered inside a web-map/map-view; outside one it throws"
+    ]
+  },
+  "composition": {
+    "allowedParents": ["web-map/map-view"],
+    "allowedChildren": [
+      "web-map/map-pin",
+      "render function receiving { isSelected, isHovered }",
+      "custom non-interactive pin element"
+    ],
+    "avoidCombinations": [
+      "Buttons or links inside the marker — nested interactive elements inside its button",
+      "MapMarker inside a web-map/base-map without a web-map/map-view — it throws"
+    ],
+    "contexts": ["map overlay"]
+  },
+  "content": {
+    "labelRules": [
+      "label is the place's name as the user knows it ('Roma Pizza'), the same text as the pin and any list entry",
+      "Pass label already translated"
+    ],
+    "helperTextRules": [],
+    "errorRules": []
+  },
+  "aiDecisionRules": [
+    {
+      "condition": "The default callout pin fits the design",
+      "decision": "Render web-map/map-pin as the child with the same label and an optional value",
+      "reason": "MapPin picks up the marker's state through context and needs no extra props"
+    },
+    {
+      "condition": "A custom pin (dot, icon, avatar) is needed",
+      "decision": "Pass a render function as children and draw the pin from { isSelected, isHovered }; set anchor to center for round pins",
+      "reason": "The marker owns the button and state; the child only draws"
+    },
+    {
+      "condition": "One marker should not move the map when selected (e.g. it is already in view or is a reference point)",
+      "decision": "Set flyToOnSelect={false} on that marker",
+      "reason": "It overrides the MapView's flyToSelected for that marker only"
+    }
+  ],
+  "relatedComponents": ["web-map/map-view", "web-map/map-pin", "web-map/map-user-location"]
+}

package/src/map-marker.stories.tsx

@@ -0,0 +1,228 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState, type ReactNode } from 'react';
+
+import { TooltipProvider, cn } from '@swisper.ai/ui';
+
+import { PLACE_POINTS, PLACES } from './__storybook__/fixtures';
+import { MapMarker, type MapMarkerProps, type MapMarkerState } from './map-marker';
+import { MapPin } from './map-pin';
+import { MapView } from './map-view';
+
+type Anchor = NonNullable<MapMarkerProps['anchor']>;
+
+interface HarnessState {
+  selectedId: string | null;
+  setSelectedId: (id: string | null) => void;
+}
+
+interface MarkerHarnessProps {
+  children: ReactNode;
+  /** Rendered beside the map with the selection, e.g. a list that selects from outside. */
+  sidebar?: (state: HarnessState) => ReactNode;
+}
+
+/** `MapMarker` needs a `MapView` around it; this one owns selection and hover. */
+function MarkerHarness({ children, sidebar }: MarkerHarnessProps) {
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [hoveredId, setHoveredId] = useState<string | null>(null);
+
+  return (
+    <div className="flex size-full gap-16">
+      {sidebar?.({ selectedId, setSelectedId })}
+      <div className="h-full flex-1">
+        <MapView<string>
+          testId="map-marker-story"
+          ariaLabel="Restaurants near you"
+          fitPoints={PLACE_POINTS}
+          selectedId={selectedId}
+          hoveredId={hoveredId}
+          onSelect={setSelectedId}
+          onHover={setHoveredId}
+        >
+          {children}
+        </MapView>
+      </div>
+    </div>
+  );
+}
+
+/** `MapMarker`'s props, so it can be the meta's `component`, plus the harness's own args. */
+interface MapMarkerStoryArgs extends MapMarkerProps {
+  anchor: Anchor;
+  /** Only used by `SelectedFromOutside`: whether the first marker eases into view. */
+  flyToFirst: boolean;
+}
+
+const meta: Meta<MapMarkerStoryArgs> = {
+  title: 'Map/MapMarker',
+  component: MapMarker,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <TooltipProvider>
+        <div className="h-[600px] w-[900px]">
+          <Story />
+        </div>
+      </TooltipProvider>
+    ),
+  ],
+  args: {
+    anchor: 'bottom',
+    flyToFirst: true,
+  },
+  argTypes: {
+    anchor: {
+      control: 'inline-radio',
+      options: ['center', 'top', 'bottom', 'left', 'right'] satisfies Anchor[],
+      description:
+        'Which side of the marker sits on its coordinate: `bottom` for callout pins like `MapPin`, `center` for dots.',
+      table: { defaultValue: { summary: 'bottom' } },
+    },
+    flyToFirst: {
+      table: { disable: true },
+      description:
+        "Passed as the first marker's `flyToOnSelect`: whether selecting it eases the map to it, overriding the `MapView`'s `flyToSelected`.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<MapMarkerStoryArgs>;
+
+/** `MapPin` children pick up the marker state. Hover or click a pin to see it. */
+export const Default: Story = {
+  render: ({ anchor }) => (
+    <MarkerHarness>
+      {PLACES.map((place) => (
+        <MapMarker
+          key={place.id}
+          id={place.id}
+          longitude={place.lngLat[0]}
+          latitude={place.lngLat[1]}
+          label={place.label}
+          anchor={anchor}
+        >
+          <MapPin label={place.label} value={place.value} />
+        </MapMarker>
+      ))}
+    </MarkerHarness>
+  ),
+};
+
+function DotPin({ isSelected, isHovered }: MapMarkerState) {
+  return (
+    <span
+      className={cn(
+        'block size-16 rounded-full bg-[#252931] ring-2 ring-white transition-transform duration-150',
+        isHovered && 'scale-125',
+        isSelected && 'scale-150 bg-primary-main',
+      )}
+    />
+  );
+}
+
+/** Children as a render function get `{ isSelected, isHovered }` to draw any pin. */
+export const RenderFunction: Story = {
+  args: { anchor: 'center' },
+  render: ({ anchor }) => (
+    <MarkerHarness>
+      {PLACES.map((place) => (
+        <MapMarker
+          key={place.id}
+          id={place.id}
+          longitude={place.lngLat[0]}
+          latitude={place.lngLat[1]}
+          label={place.label}
+          anchor={anchor}
+        >
+          {(state) => <DotPin {...state} />}
+        </MapMarker>
+      ))}
+    </MarkerHarness>
+  ),
+};
+
+/**
+ * Selecting from a list outside the map eases to the marker. Pan away first to
+ * see it. Turn off `flyToFirst` to see the per-marker `flyToOnSelect` override.
+ */
+export const SelectedFromOutside: Story = {
+  argTypes: { flyToFirst: { table: { disable: false }, control: 'boolean' } },
+  render: ({ anchor, flyToFirst }) => (
+    <MarkerHarness
+      sidebar={({ selectedId, setSelectedId }) => (
+        <ul className="flex w-[200px] flex-col gap-4">
+          {PLACES.map((place) => (
+            <li key={place.id}>
+              <button
+                type="button"
+                aria-pressed={place.id === selectedId}
+                onClick={() => setSelectedId(place.id === selectedId ? null : place.id)}
+                className={cn(
+                  'w-full cursor-pointer rounded-md px-12 py-8 text-left',
+                  place.id === selectedId ? 'bg-primary-main/20' : 'hover:bg-white/5',
+                )}
+              >
+                {place.label}
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+    >
+      {PLACES.map((place, index) => (
+        <MapMarker
+          key={place.id}
+          id={place.id}
+          longitude={place.lngLat[0]}
+          latitude={place.lngLat[1]}
+          label={place.label}
+          anchor={anchor}
+          flyToOnSelect={index === 0 ? flyToFirst : undefined}
+        >
+          <MapPin label={place.label} value={place.value} />
+        </MapMarker>
+      ))}
+    </MarkerHarness>
+  ),
+};
+
+const ANCHORS: Anchor[] = ['center', 'top', 'bottom', 'left', 'right'];
+
+/** One marker per `anchor` at the same point, so each shows which side sits on it. */
+export const Anchors: Story = {
+  argTypes: { anchor: { table: { disable: true } } },
+  render: () => {
+    const [longitude, latitude] = PLACES[0].lngLat;
+    return (
+      <MarkerHarness>
+        <>
+          {ANCHORS.map((anchor) => (
+            <MapMarker
+              key={anchor}
+              id={anchor}
+              longitude={longitude}
+              latitude={latitude}
+              label={`Anchor ${anchor}`}
+              anchor={anchor}
+              flyToOnSelect={false}
+            >
+              <MapPin label={anchor} />
+            </MapMarker>
+          ))}
+          <MapMarker
+            id="point"
+            longitude={longitude}
+            latitude={latitude}
+            label="Anchor point"
+            anchor="center"
+            flyToOnSelect={false}
+          >
+            <span className="block size-8 rounded-full bg-[#EB0000]" />
+          </MapMarker>
+        </>
+      </MarkerHarness>
+    );
+  },
+};