Map

type map = map

type MapDrawing = {
  /** The drawing's width in its own units; with `height`, the frame's aspect ratio. */
  width: number;
  /** The drawing's height in its own units. */
  height: number;
  /**
   * Draws the map's SVG content in drawing units, using the kit's fills and
   * line classes and role-variable strokes. Put text in `labels`, not here,
   * so it keeps its size when zoomed.
   */
  render: (kit: MapDrawingKit) => React.ReactNode;
  /** The reset zoom step. Default 0, the whole drawing. */
  zoom?: number;
  /** The deepest zoom step; each step doubles the scale. Default 3. */
  maxZoom?: number;
  /** The reset center in drawing units. Default: the drawing's center. */
  center?: [number, number];
}

type MapDrawingKit = {
  /**
   * Area fills as `url(#…)` strings for a shape's `fill`: `water` (hatch
   * 45° in --primary12), `green` (dot screen 1.25 px at 6 px in the odd slot
   * ink), `planned` (hatch 135°, always with a label). Add `line.area` for
   * the shape's --border-size-1 --primary12 edge.
   */
  fill: { water: string; green: string; planned: string };
  /**
   * Classes for strokes and outlines: `boundary` (line-solid 1 px),
   * `subdivision` (line-dotted-fine), `road` / `street` / `path` (solid 2 /
   * 1.5 / 1 px), `building` (ground face, 1 px outline), `area` (the edge of
   * a patterned area), `route` (line-dashed in --role-accent), `altRoute`
   * (line-dashed in --primary12). Strokes never scale with zoom.
   */
  line: {
    boundary: string;
    subdivision: string;
    road: string;
    street: string;
    path: string;
    building: string;
    area: string;
    route: string;
    altRoute: string;
  };
}

type MapLabel = {
  /** Stable id. */
  id: string;
  /** The label text, e.g. "Lake". */
  text: string;
  /** Drawing maps: the label's center in drawing units. */
  x?: number;
  /** Drawing maps: the label's center in drawing units. */
  y?: number;
  /** Vector (PMTiles) maps: longitude in degrees. */
  lon?: number;
  /** Vector (PMTiles) maps: latitude in degrees. */
  lat?: number;
}

type MapMarker = {
  /** Stable id, used for selection. */
  id: string;
  /** The place's name: the index entry title and the marker's accessible name. */
  name: string;
  /** Drawing maps: the position in drawing units. */
  x?: number;
  /** Drawing maps: the position in drawing units. */
  y?: number;
  /** Vector (PMTiles) maps: longitude in degrees. */
  lon?: number;
  /** Vector (PMTiles) maps: latitude in degrees. */
  lat?: number;
  /** The index group head (a category), e.g. "Gardens". */
  group?: string;
  /** The marker's category shape. Default `circle`. */
  shape?: MapMarkerShape;
  /** Details shown when the entry is selected, in the index; printed expanded. */
  details?: React.ReactNode;
}

type MapMarkerShape = 'circle' | 'square' | 'diamond'

type MapMessages = {
  /** Default "Zoom in". */
  zoomIn: string;
  /** Default "Zoom out". */
  zoomOut: string;
  /** Default "Reset map view". */
  reset: string;
  /** The toolbar's accessible name. Default "Map controls". */
  toolbar: string;
  /** How to operate the map, read with the frame. */
  instructions: string;
  /** The announced zoom step. Default "Zoom 2 of 4". */
  zoomStatus: (level: number, levels: number) => string;
  /** The index's accessible name. Default "Index". */
  index: string;
}

type MapPmtiles = {
  /**
   * The archive's URL. It is read with HTTP range requests, so the host must
   * allow them and CORS. Host your own extract in production (`pmtiles
   * extract`); the public planet builds are for demos.
   */
  url: string;
  /** The reset center, `[longitude, latitude]`. */
  center: [number, number];
  /** The reset zoom level. */
  zoom: number;
  /** The shallowest zoom level. Default: `zoom` − 3. */
  minZoom?: number;
  /** The deepest zoom level. Default: `zoom` + 4, at most 19. */
  maxZoom?: number;
  /** The frame's aspect ratio (width ÷ height). Default 3 / 2. */
  ratio?: number;
  /** The label language, a Protomaps `lang` code. Default `"en"`. */
  lang?: string;
  /**
   * Glyphs URL template (`{fontstack}`, `{range}`) for the characters the
   * page's UI font files do not cover. Default: Protomaps' hosted Noto Sans
   * glyphs, OFL, which need no credit.
   */
  glyphs?: string;
  /**
   * URL of MapLibre's worker, `maplibre-gl-worker.mjs`, served in the same
   * directory as `maplibre-gl-shared.mjs`. Bundlers (Next.js, Vite, webpack)
   * need it: copy both files from `maplibre-gl/dist` to a public path, as
   * MapLibre's installation guide shows. Set once per page; the first map
   * wins. Default: MapLibre's own detection, which only works unbundled.
   */
  workerUrl?: string;
  /**
   * The data credit below the frame. Default: "© OpenStreetMap", linked to
   * openstreetmap.org/copyright, which print spells out. Protomaps asks for
   * no credit; add one only when your tiles carry other sources.
   */
  attribution?: React.ReactNode;
}

type MapProps = {
  /**
   * `technical` (default): --ds-radius-none, a --border-size-1 --role-rule
   * frame. `location`: --ds-radius-20, a --border-size-2 --primary12 frame,
   * always with a mixed-case `address`.
   */
  kind?: 'technical' | 'location' | null;
  /** The caps title above the map, with "(DETAIL)" for crops; also the frame's accessible name. */
  title: string;
  /** The caption below the map: what to notice. */
  caption?: React.ReactNode;
  /** The figure label, e.g. "Fig. 4". */
  figureLabel?: React.ReactNode;
  /** The text address, mixed case; required with `kind="location"`. */
  address?: React.ReactNode;
  /** A drawn base map. Pass `drawing` or `pmtiles`. */
  drawing?: MapDrawing;
  /**
   * A vector base map: a Protomaps PMTiles archive drawn by MapLibre GL JS
   * in the role variables. Pass `drawing` or `pmtiles`. Needs the optional
   * peers `maplibre-gl`, `pmtiles` and `@protomaps/basemaps`, and MapLibre's
   * worker URL under bundlers (`pmtiles.workerUrl`).
   */
  pmtiles?: MapPmtiles;
  /** Routes over a vector base map (a drawing draws its own with `kit.line.route`). */
  routes?: MapRoute[];
  /** The places, numbered in this order (01, 02 …) and listed in the index. */
  markers?: MapMarker[];
  /** Live text labels (areas, water) at screen size. */
  labels?: MapLabel[];
  /** The selected marker's id (controlled). */
  selected?: string | null;
  /** The initially selected marker's id. */
  defaultSelected?: string | null;
  /** Called when the selection changes, from a marker or the index. */
  onSelectedChange?: (id: string | null) => void;
  /** Heading level of the index entries. Default 3. */
  headingLevel?: HeadingLevel;
  /**
   * The static figure printed instead of the live base, e.g. a black-line
   * export at the reset extent. Without it, a drawing prints at its reset
   * extent, and a vector map prints a snapshot of its reset extent in the
   * print palette, rendered once the map settles.
   */
  printFallback?: React.ReactNode;
  /** The map's URL, printed in `type-url` beside the QR code [D168]. */
  url?: string;
  /** A QR code for `url` as inline SVG, printed at --ds-print-qr beside the URL, never instead of it. */
  qr?: React.ReactNode;
  /**
   * One ink: area patterns in --primary12 (a vector map also hatches its
   * water). Pass it on any ground but a light base or a `white` plate
   * (§8.10). Default `false`.
   */
  oneInk?: boolean;
  /** Primary Radix scale: lines, markers, labels. Never defaulted [D133]. */
  primary?:
    | 'ruby'
    | 'olive'
    | 'sage'
    | 'slate'
    | 'sand'
    | 'gray'
    | 'mauve'
    | 'brown'
    | 'bronze'
    | 'gold'
    | 'red'
    | 'crimson'
    | 'tomato'
    | 'pink'
    | 'plum'
    | 'indigo'
    | 'iris'
    | 'violet'
    | 'purple'
    | null;
  /** Secondary Radix scale: odd-slot area patterns. Never defaulted [D133]. */
  secondary?:
    | 'ruby'
    | 'olive'
    | 'sage'
    | 'slate'
    | 'sand'
    | 'gray'
    | 'mauve'
    | 'brown'
    | 'bronze'
    | 'gold'
    | 'red'
    | 'crimson'
    | 'tomato'
    | 'pink'
    | 'plum'
    | 'indigo'
    | 'iris'
    | 'violet'
    | 'purple'
    | 'amber'
    | 'blue'
    | 'cyan'
    | 'grass'
    | 'green'
    | 'jade'
    | 'lime'
    | 'mint'
    | 'orange'
    | 'sky'
    | 'teal'
    | 'yellow'
    | null;
  /** Interface strings. */
  messages?: Partial<MapMessages>;
}

type MapRoute = {
  /** Stable id. */
  id: string;
  /** The route's line, as `[longitude, latitude]` pairs in order. */
  points: [number, number][];
  /**
   * The accessible or alternate route: `line-dashed` in --primary12 instead
   * of --role-accent. Default `false`.
   */
  alternate?: boolean;
}