@swisper.ai/web-map 0.0.2

package/src/map-marker.tsx

@@ -0,0 +1,97 @@
+import { Marker } from '@vis.gl/react-maplibre';
+import { createContext, useContext, useEffect, useMemo, type ReactNode } from 'react';
+
+import { cn } from '@swisper.ai/ui';
+
+import { useMapView, type MapItemId } from './map-context';
+
+export interface MapMarkerState {
+  isSelected: boolean;
+  isHovered: boolean;
+}
+
+const MapMarkerContext = createContext<MapMarkerState | null>(null);
+
+/** Selection state of the enclosing `MapMarker`, or null outside of one. */
+export function useMapMarker() {
+  return useContext(MapMarkerContext);
+}
+
+export interface MapMarkerProps {
+  id: MapItemId;
+  longitude: number;
+  latitude: number;
+  /** Accessible name of the marker button. */
+  label: string;
+  anchor?: 'center' | 'top' | 'bottom' | 'left' | 'right';
+  /** Ease to this marker when selected; defaults to the `MapView`'s `flyToSelected`. */
+  flyToOnSelect?: boolean;
+  className?: string;
+  children: ReactNode | ((state: MapMarkerState) => ReactNode);
+}
+
+function getMarkerZIndex({ isHovered, isSelected }: MapMarkerState) {
+  if (isHovered) return 3;
+  if (isSelected) return 2;
+  return 1;
+}
+
+/**
+ * A selectable, hoverable point on a `MapView`. Renders any pin as its child —
+ * `MapPin` by default, or a render function receiving the marker state.
+ */
+export function MapMarker({
+  id,
+  longitude,
+  latitude,
+  label,
+  anchor = 'bottom',
+  flyToOnSelect,
+  className,
+  children,
+}: MapMarkerProps) {
+  const { mapRef, selectedId, hoveredId, flyToSelected, onSelect, onHover } = useMapView();
+
+  const isSelected = id === selectedId;
+  const isHovered = id === hoveredId;
+  const state = useMemo(() => ({ isSelected, isHovered }), [isSelected, isHovered]);
+
+  // Fly to the selected pin so it's always in view when chosen from outside the map.
+  const shouldFlyTo = flyToOnSelect ?? flyToSelected;
+
+  useEffect(() => {
+    if (!isSelected || !shouldFlyTo) return;
+    const map = mapRef.current?.getMap();
+    if (!map) return;
+    map.easeTo({ center: [longitude, latitude], duration: 400 });
+  }, [isSelected, shouldFlyTo, longitude, latitude, mapRef]);
+
+  return (
+    <Marker
+      longitude={longitude}
+      latitude={latitude}
+      anchor={anchor}
+      style={{ zIndex: getMarkerZIndex(state) }}
+      onClick={(e) => {
+        // Prevent the map's click handler from firing and deselecting.
+        e.originalEvent.stopPropagation();
+        onSelect?.(id);
+      }}
+    >
+      <button
+        type="button"
+        aria-label={label}
+        aria-pressed={isSelected}
+        data-selected={isSelected || undefined}
+        data-hovered={isHovered || undefined}
+        onMouseEnter={() => onHover?.(id)}
+        onMouseLeave={() => onHover?.(null)}
+        className={cn('cursor-pointer transition-[filter] duration-150 ease-out', className)}
+      >
+        <MapMarkerContext.Provider value={state}>
+          {typeof children === 'function' ? children(state) : children}
+        </MapMarkerContext.Provider>
+      </button>
+    </Marker>
+  );
+}

package/src/map-pin.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "../../int-eslint-config/schemas/component.schema.json",
+  "component": "map-pin",
+  "purpose": "The default callout pin for a map marker: a pill showing a short value that expands to value and place name on hover or selection.",
+  "useWhen": [
+    "Marking a place on a web-map/map-view with a short value the user compares at a glance, such as a rating or a price",
+    "Marking named places where the name should appear only on hover or selection to keep the map uncluttered",
+    "Showing a pin outside a map (a legend or a key) in a fixed state"
+  ],
+  "avoidWhen": [
+    "Marking the user's own position — use web-map/user-location-pin instead",
+    "Points that need no text, such as dense clusters — draw a custom pin through web-map/map-marker's render function instead",
+    "Showing long text or actions about a place — show it in a list, card or panel beside the map instead"
+  ],
+  "uxPrinciples": [
+    "The resting pin shows only what users compare across places (the value); the name appears when the user shows interest",
+    "Selected is the strongest state: dark pill and primary-coloured text, so the chosen place stands out from hovered ones"
+  ],
+  "accessibility": {
+    "required": [
+      "Inside a web-map/map-marker the marker button carries the accessible name; keep the marker's label and the pin's label the same",
+      "Used outside a marker, the pin has no role or name of its own; give it an accessible context (e.g. a legend caption)"
+    ],
+    "keyboard": [
+      "None on the pin; it is not focusable. Keyboard interaction belongs to the enclosing marker button"
+    ],
+    "aria": [
+      "No role; the divider and the caret are aria-hidden",
+      "data-selected and data-hovered are set on the root for styling"
+    ],
+    "focus": ["The pin is never a tab stop"]
+  },
+  "behaviour": {
+    "states": ["default", "hovered", "selected"],
+    "rules": [
+      "isSelected and isHovered default to the enclosing web-map/map-marker's state; passing either explicitly overrides the marker",
+      "With a value, the resting pin shows the value only and expands to value | label on hover or selection; without a value (undefined, null or an empty string) the label is always shown",
+      "The label is truncated past 84px",
+      "The label's expand animation is turned off under prefers-reduced-motion",
+      "The palette is a set of --map-pin-* CSS custom properties on the root; override them through className to restyle the pin (e.g. [--map-pin-bg:#fff])",
+      "classNames targets single parts: root, pill, value, divider, label and caret"
+    ]
+  },
+  "composition": {
+    "allowedParents": ["web-map/map-marker"],
+    "allowedChildren": ["label (place name)", "value (short text such as a rating or price)"],
+    "avoidCombinations": [
+      "Interactive content in value — the pin sits inside the marker's button",
+      "A web-map/map-marker anchored at center around a MapPin — the caret points at the coordinate only with the default bottom anchor"
+    ],
+    "contexts": ["map overlay", "map legend"]
+  },
+  "content": {
+    "labelRules": [
+      "label is the place name, kept short; anything past 84px is truncated",
+      "value is a short lead the user compares across pins, e.g. a rating (4.5) or a price (CHF 180), never a sentence"
+    ],
+    "helperTextRules": [],
+    "errorRules": []
+  },
+  "aiDecisionRules": [
+    {
+      "condition": "The pin is inside a web-map/map-marker",
+      "decision": "Do not pass isSelected or isHovered",
+      "reason": "The pin reads the marker's state; explicit props would freeze it"
+    },
+    {
+      "condition": "The pin must match a different surface or brand",
+      "decision": "Override the --map-pin-* custom properties through className",
+      "reason": "The pin's colours are defined as those variables, so every state follows the override"
+    },
+    {
+      "condition": "Places have no comparable value",
+      "decision": "Omit value",
+      "reason": "The pin then shows the label at rest, so it is never an empty pill"
+    }
+  ],
+  "relatedComponents": ["web-map/map-marker", "web-map/map-view", "web-map/user-location-pin"],
+  "tokenReferences": {
+    "source": "packages/design-system/src/tailwind.css",
+    "categories": [
+      "--color-primary-main (selected text and divider)",
+      "--map-pin-* component custom properties"
+    ],
+    "rule": "Restyle through the --map-pin-* properties; the defaults are fixed Figma values, and only the selected state reads a design token."
+  }
+}

package/src/map-pin.stories.tsx

@@ -0,0 +1,97 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { MapPin } from './map-pin';
+
+const meta: Meta<typeof MapPin> = {
+  title: 'Map/MapPin',
+  component: MapPin,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div className="max-w-[420px] mx-auto flex items-center justify-center bg-[#f8f4f1] p-32 rounded-lg">
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    label: 'Roma Pizza',
+    value: 4.5,
+    isSelected: false,
+    isHovered: false,
+    'data-testid': 'map-pin',
+  },
+  argTypes: {
+    label: {
+      control: 'text',
+      description: 'Place name, shown on hover or selection, or always when there is no `value`.',
+    },
+    value: {
+      control: 'text',
+      description:
+        'Short lead text always shown in the pill, e.g. a rating (`4.5`) or a price (`CHF 180`).',
+    },
+    isSelected: {
+      control: 'boolean',
+      description:
+        "Selected style: dark pill, primary text, label shown. Defaults to the enclosing `MapMarker`'s state.",
+      table: { defaultValue: { summary: 'false' } },
+    },
+    isHovered: {
+      control: 'boolean',
+      description:
+        "Hover style with the label expanded. Defaults to the enclosing `MapMarker`'s state.",
+      table: { defaultValue: { summary: 'false' } },
+    },
+    classNames: {
+      control: 'object',
+      description:
+        'Extra classes per part: `root`, `pill`, `value`, `divider`, `label` and `caret`.',
+    },
+    'data-testid': {
+      control: 'text',
+      description: 'Sets `data-testid` on the root.',
+      table: { defaultValue: { summary: 'map-pin' } },
+    },
+    className: {
+      control: 'text',
+      description:
+        'Merged onto the root. Override the palette with CSS vars, e.g. `[--map-pin-bg:#fff]`.',
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof MapPin>;
+
+export const Default: Story = {};
+
+export const Hovered: Story = {
+  args: { isHovered: true },
+};
+
+export const Selected: Story = {
+  args: { isSelected: true },
+};
+
+/** No value — the label is always shown. */
+export const LabelOnly: Story = {
+  args: { value: undefined },
+};
+
+/** Palette overridden through the pin's CSS custom properties. */
+export const Restyled: Story = {
+  args: {
+    isSelected: true,
+    value: 'CHF 180',
+    className: [
+      '[--map-pin-bg:#ffffff]',
+      '[--map-pin-bg-selected:#ffffff]',
+      '[--map-pin-overlay-selected:transparent]',
+      '[--map-pin-fg:#252931]',
+      '[--map-pin-fg-expanded:#252931]',
+      '[--map-pin-fg-selected:#0D212B]',
+      '[--map-pin-divider-selected:#BBC3CC]',
+    ].join(' '),
+  },
+};

package/src/map-pin.tsx

@@ -0,0 +1,174 @@
+import type { ReactNode } from 'react';
+
+import { Typography, cn } from '@swisper.ai/ui';
+
+import { useMapMarker } from './map-marker';
+
+/**
+ * Pin palette as CSS custom properties so a caller can restyle it with a class,
+ * e.g. `className="[--map-pin-bg:#fff] [--map-pin-fg:#000]"`.
+ * Defaults are the Figma PlacePointer values (brand/secondary/700, selected
+ * Pill #0D212B + 12% secondary overlay, hover 6% overlay).
+ */
+const PIN_PALETTE = cn(
+  '[--map-pin-bg:#252931]',
+  '[--map-pin-bg-selected:#0D212B]',
+  '[--map-pin-overlay-hover:rgba(187,195,204,0.06)]',
+  '[--map-pin-overlay-selected:rgba(187,195,204,0.12)]',
+  '[--map-pin-fg:#BBC3CC]',
+  '[--map-pin-fg-expanded:#E4E8EB]',
+  '[--map-pin-fg-selected:var(--color-primary-main)]',
+  '[--map-pin-divider:rgba(187,195,204,0.6)]',
+  '[--map-pin-divider-selected:color-mix(in_srgb,var(--color-primary-main)_40%,transparent)]',
+);
+
+function overlay(color: string, base: string) {
+  return `linear-gradient(${color}, ${color}), ${base}`;
+}
+
+export interface MapPinClassNames {
+  root?: string;
+  pill?: string;
+  value?: string;
+  divider?: string;
+  label?: string;
+  caret?: string;
+}
+
+export interface MapPinProps {
+  /** Shown on hover / selection, or always when there is no `value`. */
+  label: string;
+  /** Short lead text always shown in the pill, e.g. a rating or a price. */
+  value?: ReactNode;
+  /** Defaults to the enclosing `MapMarker`'s state. */
+  isSelected?: boolean;
+  /** Defaults to the enclosing `MapMarker`'s state. */
+  isHovered?: boolean;
+  className?: string;
+  classNames?: MapPinClassNames;
+  'data-testid'?: string;
+}
+
+/**
+ * Map callout pin: `value`-only by default; expands to `value | label` on
+ * hover/selection (Figma PlacePointer Default / Hover / selected Pill).
+ */
+export function MapPin({
+  label,
+  value,
+  isSelected: isSelectedProp,
+  isHovered: isHoveredProp,
+  className,
+  classNames,
+  'data-testid': dataTestId = 'map-pin',
+}: MapPinProps) {
+  const marker = useMapMarker();
+  const isSelected = isSelectedProp ?? marker?.isSelected ?? false;
+  const isHovered = isHoveredProp ?? marker?.isHovered ?? false;
+
+  const isExpanded = isSelected || isHovered;
+  const hasValue = value != null && value !== '';
+  const showLabel = isExpanded || !hasValue;
+
+  const pillBg = isSelected
+    ? overlay('var(--map-pin-overlay-selected)', 'var(--map-pin-bg-selected)')
+    : isHovered
+      ? overlay('var(--map-pin-overlay-hover)', 'var(--map-pin-bg)')
+      : 'var(--map-pin-bg)';
+
+  const textClassName = isSelected
+    ? 'text-[color:var(--map-pin-fg-selected)]'
+    : isExpanded
+      ? 'text-[color:var(--map-pin-fg-expanded)]'
+      : 'text-[color:var(--map-pin-fg)]';
+
+  return (
+    <div
+      data-testid={dataTestId}
+      data-selected={isSelected || undefined}
+      data-hovered={isHovered || undefined}
+      className={cn(
+        PIN_PALETTE,
+        'flex flex-col items-center isolate drop-shadow-[0px_1px_2px_rgba(228,232,235,0.3)]',
+        className,
+        classNames?.root,
+      )}
+    >
+      <div
+        className={cn(
+          'relative z-2 flex h-[20px] w-full items-center overflow-hidden rounded-[8px] px-4 -mb-1.25',
+          classNames?.pill,
+        )}
+        style={{ background: pillBg }}
+      >
+        <div className="flex items-center px-4">
+          {hasValue && (
+            <Typography
+              variant="caption"
+              className={cn(
+                'shrink-0 whitespace-nowrap leading-[1.3]',
+                textClassName,
+                classNames?.value,
+              )}
+            >
+              {value}
+            </Typography>
+          )}
+
+          {/* 0fr → 1fr animates to the label's intrinsic width; the inner
+              `w-max` keeps it from reflowing while the column collapses. */}
+          <div
+            className={cn(
+              'grid self-stretch transition-[grid-template-columns] duration-200 ease-out motion-reduce:transition-none',
+              showLabel ? 'grid-cols-[1fr]' : 'grid-cols-[0fr]',
+            )}
+          >
+            <div className="flex min-w-0 items-center overflow-hidden">
+              <div className={cn('flex w-max items-center gap-4', hasValue && 'pl-4')}>
+                {hasValue && (
+                  <span
+                    aria-hidden="true"
+                    className={cn(
+                      'w-px self-stretch shrink-0',
+                      isSelected
+                        ? 'bg-[color:var(--map-pin-divider-selected)]'
+                        : 'bg-[color:var(--map-pin-divider)]',
+                      classNames?.divider,
+                    )}
+                  />
+                )}
+
+                <Typography
+                  variant="caption"
+                  className={cn(
+                    'max-w-[84px] truncate whitespace-nowrap leading-[1.3] transition-opacity duration-200 ease-out motion-reduce:transition-none',
+                    showLabel ? 'opacity-100' : 'opacity-0',
+                    textClassName,
+                    classNames?.label,
+                  )}
+                >
+                  {label}
+                </Typography>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div className="relative z-1 flex w-full items-center justify-center" aria-hidden="true">
+        <svg
+          width={8}
+          height={8}
+          viewBox="0 0 8 8"
+          fill="none"
+          className={cn('size-8 shrink-0', classNames?.caret)}
+        >
+          <path
+            d="M4 8L0 0H8L4 8Z"
+            fill={isSelected ? 'var(--map-pin-bg-selected)' : 'var(--map-pin-bg)'}
+          />
+        </svg>
+      </div>
+    </div>
+  );
+}

package/src/map-user-location.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "../../int-eslint-config/schemas/component.schema.json",
+  "component": "map-user-location",
+  "purpose": "Draws the user's own position on a map once it is known, with UserLocationPin as the default marker.",
+  "useWhen": [
+    "Showing where the user is relative to the places on a web-map/map-view",
+    "The position comes from navigator.geolocation or another source that may resolve late or not at all"
+  ],
+  "avoidWhen": [
+    "Marking a place the user can select — use web-map/map-marker instead",
+    "Drawing the dot outside a map — use web-map/user-location-pin instead"
+  ],
+  "uxPrinciples": [
+    "Show nothing rather than a wrong position: no dot is drawn until coordinates are known",
+    "The user's position is a reference, not a choice: it is not selectable and does not move the map"
+  ],
+  "accessibility": {
+    "required": [
+      "Pass a translated label for the default pin; it is the dot's accessible name and tooltip",
+      "A custom marker passed as children needs its own accessible name",
+      "The default pin needs a ui/TooltipProvider above the map"
+    ],
+    "keyboard": ["None; the marker is not focusable"],
+    "aria": ["The default pin is role=img with aria-label=label"],
+    "focus": ["No tab stop"]
+  },
+  "behaviour": {
+    "states": ["unknown (renders nothing)", "known"],
+    "rules": [
+      "coordinates null or undefined renders nothing; any longitude/latitude pair draws the marker centred on it",
+      "children replaces the default web-map/user-location-pin; label is then ignored",
+      "It stacks at the same level as hovered and selected markers",
+      "It reads no MapView context, so it also works inside a web-map/base-map",
+      "It does not add the position to the MapView's fitPoints; include it there if the map should frame it"
+    ]
+  },
+  "composition": {
+    "allowedParents": ["web-map/map-view", "web-map/base-map"],
+    "allowedChildren": ["web-map/user-location-pin", "custom marker element"],
+    "avoidCombinations": [
+      "An interactive custom marker — the user's position is not a selectable place; use web-map/map-marker for those"
+    ],
+    "contexts": ["map overlay"]
+  },
+  "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": "Geolocation is pending or denied",
+      "decision": "Pass null and keep rendering the component",
+      "reason": "It renders nothing until coordinates arrive, so no conditional is needed and no dot lands at 0,0"
+    },
+    {
+      "condition": "The map should frame the user together with the places",
+      "decision": "Add the user's [longitude, latitude] to the MapView's fitPoints",
+      "reason": "MapUserLocation draws the dot but does not affect framing"
+    }
+  ],
+  "relatedComponents": [
+    "web-map/user-location-pin",
+    "web-map/map-view",
+    "web-map/map-marker",
+    "ui/tooltip"
+  ]
+}

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

@@ -0,0 +1,69 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { TooltipProvider } from '@swisper.ai/ui';
+
+import { USER_LOCATION } from './__storybook__/fixtures';
+import { MapUserLocation } from './map-user-location';
+import { MapView } from './map-view';
+
+const meta: Meta<typeof MapUserLocation> = {
+  title: 'Map/MapUserLocation',
+  component: MapUserLocation,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <TooltipProvider>
+        <div className="h-[500px] w-[700px]">
+          <MapView
+            testId="map-user-location-story"
+            ariaLabel="Your location"
+            fitPoints={[[USER_LOCATION.longitude, USER_LOCATION.latitude]]}
+          >
+            <Story />
+          </MapView>
+        </div>
+      </TooltipProvider>
+    ),
+  ],
+  args: {
+    coordinates: USER_LOCATION,
+    label: 'My location',
+  },
+  argTypes: {
+    coordinates: {
+      control: 'object',
+      description:
+        "The user's `longitude` and `latitude`, e.g. from `navigator.geolocation`. Nothing is drawn while it is `null` or `undefined`.",
+    },
+    label: {
+      control: 'text',
+      description:
+        'Tooltip and accessible name of the default `UserLocationPin`; ignored when `children` is set. Pass a translated string.',
+      table: { defaultValue: { summary: 'My location' } },
+    },
+    children: {
+      control: false,
+      description: 'Custom marker drawn at the position instead of the default `UserLocationPin`.',
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof MapUserLocation>;
+
+export const Default: Story = {};
+
+/** Until the position is known (`null` / `undefined`) nothing is drawn. */
+export const Unknown: Story = {
+  args: { coordinates: null },
+};
+
+/** Any element passed as `children` replaces the default `UserLocationPin`. */
+export const CustomMarker: Story = {
+  args: {
+    children: (
+      <span className="block size-24 rounded-full border-2 border-white bg-[#EB0000]/70 shadow" />
+    ),
+  },
+};

package/src/map-user-location.tsx

@@ -0,0 +1,29 @@
+import { Marker } from '@vis.gl/react-maplibre';
+import type { ReactNode } from 'react';
+
+import { UserLocationPin } from './user-location-pin';
+
+export interface MapUserLocationProps {
+  coordinates: Pick<GeolocationCoordinates, 'longitude' | 'latitude'> | null | undefined;
+  /** Custom marker; defaults to `UserLocationPin`. */
+  children?: ReactNode;
+  /** Label of the default `UserLocationPin`; ignored when `children` is set. */
+  label?: string;
+}
+
+/** The user's own position on a `MapView`; renders nothing until it is known. */
+export function MapUserLocation({ coordinates, children, label }: MapUserLocationProps) {
+  if (!coordinates) return null;
+
+  return (
+    <Marker
+      longitude={coordinates.longitude}
+      latitude={coordinates.latitude}
+      anchor="center"
+      // At the same level as the hovered and selected pins.
+      style={{ zIndex: 3 }}
+    >
+      {children ?? <UserLocationPin label={label} />}
+    </Marker>
+  );
+}