@uzmaps/ui and @uzmaps/cartography

Two packages sit on top of @uzmaps/engine and @uzmaps/api:

Every symbol on this page was confirmed in the file named next to it. Anything that could not be confirmed is listed under Unverified at the end rather than guessed at.

@uzmaps/ui#

Install#

npm install @uzmaps/ui @uzmaps/engine @uzmaps/api react react-dom

From packages/ui/package.json: dependencies are @uzmaps/engine ^0.1.1, @uzmaps/api ^0.1.0 and lucide-react; peers are react >=18 and react-dom >=18, with @types/react >=18 as an optional peer. The package is ESM only ("type": "module", a single import entry in exports).

The stylesheet#

import '@uzmaps/ui/styles.css';

package.json maps "./styles.css" to ./dist/styles.css; scripts/postbuild.mjs copies every .css file under src/ into dist/ after tsc, because tsc emits nothing but JavaScript and declarations. Nothing injects the stylesheet at import time, so you control its order against your own CSS.

Facts about packages/ui/src/styles.css that affect how you lay out a page:

The tokens (--uz-bg, --uz-fg, --uz-accent, --uz-s-1…--uz-s-8, --uz-r-sm…--uz-r-full, --uz-dur-fast/--uz-dur/--uz-dur-slow, --uz-panel-w: 400px, --uz-control: 40px, --uz-topbar-h: 48px, --uz-safe-top, --uz-safe-bottom) are all declared on :root. Only the colour and shadow tokens are redeclared under [data-uz-theme='dark']; spacing, radii, motion and layout tokens are the same in both themes. --uz-panel-w is overridden to 100% at max-width: 720px. Layout classes used by the components but not owned by any one of them include .uz-panel (desktop left column, 400px wide), .uz-panel-card, .uz-panel-scroll, .uz-surface, .uz-topbar, .uz-toast and .uz-banner.

Controlled components#

The list, search, chips, route panel and bottom sheet hold no data of their own. They take state as props and raise callbacks; they never call the server. You keep the query, the results, the selected route and the sheet position in your own state and pass them down. This is why SearchBox has no api prop and ResultList has no onSearch: debouncing, cancellation and ranking belong to the application (the useSearch hook below does that work if you want it done for you).

Three components are not purely controlled, and the difference matters:

Everything exported#

From packages/ui/src/index.ts:

Exported from a module but not from the package index, so not reachable from @uzmaps/ui: useMap3D and DataSourceBadge, CopyKind, IconComponent.

MapView and useUzMap#

packages/ui/src/MapView.tsx.

interface MapViewProps extends Omit<UzMapOptions, 'container'> {
  className?: string;
  style?: React.CSSProperties;
  children?: ReactNode;
  onReady?: (map: UzMap) => void;
}
function useUzMap(): UzMap | null

MapView renders <div class="uz-map {className}">, creates new UzMap({ container, ...options }) in a mount effect, and calls map.destroy() on unmount. Children are rendered only once the instance exists (map ? <Ctx.Provider>… : null), so inside a MapView useUzMap() returns the instance; it returns null only when called outside one. The instance existing does not mean the style has loaded: onReady is wired to map.once('load', …) for that.

Options are read once at mount (they are captured in a ref). After mount only four props are watched, each applied through the engine's setter:

Changing center, zoom, serverUrl, apiKey or any other option after mount has no effect. For debugging, the instance is also assigned to window.__uzmap.

The inherited options, from UzMapOptions in packages/engine/src/types.ts (defaults are those stated in that file's doc comments):

SearchBox#

packages/ui/src/SearchBox.tsx.

The root is <div class="uz-search-box" role="search">, with is-focused while the input has focus. The input has autoComplete, autoCorrect, autoCapitalize and spellCheck off and enterKeyHint="search".

ResultList, ResultIcon, EmptyState, CategoryChips, highlight#

All in packages/ui/src/SearchBox.tsx.

ResultList

Rows are role="option" with tabIndex={0}; ArrowUp/ArrowDown move focus between rows.

ResultIcon — { r: Pick<SearchResult, 'icon' | 'group' | 'kind'>; size?: number }. Renders PoiIcon in a coloured square. Kinds street, address and place get the neutral grey style; otherwise the background is groupById[r.group].color, falling back to #4B5563.

EmptyState — { title: string; hint?: ReactNode; icon?: ReactNode; detail?: string; action?: ReactNode; tone?: 'error' }. tone: 'error' adds is-error and role="alert"; detail is rendered in monospace and clipped.

CategoryChips — { language: Language; active?: string | null; onSelect: (groupId: string | null) => void; groups?: string[] }. Renders one chip per group id, coloured and labelled from groupById in @uzmaps/cartography. Clicking the active chip calls onSelect(null). Default groups: food, shopping, health, transport, culture, lodging, finance, auto, leisure, education. Labels for uz-Cyrl fall back to the Russian label, since the group table carries uz, ru and en only.

highlight(text, query) — splits query on whitespace and commas, drops tokens of one character, and wraps the matching prefix of each word of text in <mark>. Returns a ReactNode.

PlaceCard and OpenStatus#

packages/ui/src/PlaceCard.tsx.

The hero photo is loaded when tags.wikidata is present; the image src is api.photoUrl(photo) and a failed load drops the hero. Rows are shown when the data exists: address (copies), opening hours (an expandable weekly table when details.hours parsed, plain text when hours.unparsed), phone (copies), website, Instagram, Telegram, cuisine, wheelchair, population, elevation (ele), description, and always coordinates (copies, kind: 'coords', five decimals). The footer links to details.osm.url.

OpenStatus — { d: PlaceDetails['details']; language: Language }. Renders nothing unless d.open_status?.known. Otherwise one of: open 24 hours; open (or "closing soon") with the closing time; closed with the next opening time, prefixed with "tomorrow" or a weekday name when next_day is set.

RoutePanel#

packages/ui/src/RoutePanel.tsx.

interface RouteEndpoint {
  label: string;
  lngLat: [number, number];
  kind: 'me' | 'pin' | 'place';
  place?: SearchResult;
}

The toll/highway/shortest chips are hidden when mode is foot or bike, and whenever editor is set. Steps are the concatenation of route.legs[].steps; the list supports ArrowUp/Down/Left/Right, Home and End. Step durations under 45 s are not shown next to the distance, since they would all read as "1 min".

MapControls and ScaleBar#

packages/ui/src/MapControls.tsx. Both must be rendered inside MapView; they call useUzMap().

What the component calls on the map directly: zoomIn(), zoomOut(), rotateBy(-30) / rotateBy(30), toggle3D(), setTraffic(next), and on the compass resetView() (plus set3D(false) if buildings are on) when pitched, otherwise resetNorth(). It subscribes to move, tilt, styleready and sources. The rotate arrows appear only while the map is in 3D mode or the view is tilted or rotated. The 3D button is labelled with the mode it switches to ("2D" while in 3D).

ScaleBar — { language: Language }. Recomputes on every move by unprojecting 100px at mid-height through map.ml, snapping to a 1-2-5 series between 1 m and 500 km. Hidden at max-width: 720px by the stylesheet.

BottomSheet#

packages/ui/src/BottomSheet.tsx.

type SheetSnap = 'peek' | 'half' | 'full';

Heights are computed from the parent element's clientHeight (falling back to window.innerHeight), so the sheet must be inside a sized, positioned container. The body scrolls only at full; at other snaps it gets is-locked. A drag on the body at full is decided on the first move: pulling down from scrollTop === 0 drags the sheet, pushing up scrolls. Release projects the flick velocity 180 ms ahead and snaps to the nearest stop; a decisive flick always moves at least one stop. A non-passive touchmove listener cancels the browser's own scroll while the sheet is being dragged. The root is role="dialog" aria-modal={false}.

Icons#

packages/ui/src/icons.tsx.

• poiIcons: Record<string, IconComponent> maps every UzMap icon name to a Lucide React component. Its keys are the same 88 names as glyphs in @uzmaps/cartography (listed under Category and icon tables below). Six are hand-drawn inline rather than Lucide: dentist, metro, monument, mosque, synagogue, toilets. Two differ from the sprite glyph: tram renders Lucide TrainTrack and college renders BookOpen.
• PoiIcon({ icon, ...svgProps }) renders poiIcons[icon], falling back to MapPin for unknown names.
• ui is an object of Lucide components used across the components: Search, X, ArrowLeft, Navigation, Locate, Layers, Sun, Moon, Compass, Plus, Minus, Phone, Globe, Clock, Copy, Share2, ArrowUpDown, MapPin, Route, CornerUpLeft, CornerUpRight, ArrowUp, ArrowDown, RotateCcw, RotateCw, Merge, Split, MoveUpLeft, MoveUpRight, CircleDot, Footprints, Bike, Car, CarTaxiFront, Ship, ChevronRight, ChevronDown, Info, ExternalLink, Users, Star, Check, TriangleAlert, Crosshair, History, Box, MountainSnow, Languages, AtSign, Send, Circle, Ellipsis, Sparkles, MapIcon, Accessibility, Flag, Mountain, TrafficCone.
• maneuverIcon(type, modifier) picks a component for a RouteStep:

Translations#

packages/ui/src/i18n.ts.

• t(lang: Language, key: string): string — looks the key up in the dictionary for lang, then in English, then returns the key itself. There are three dictionaries: uz, ru, en; uz-Cyrl is mapped to the Russian dictionary.
• makeT(lang) returns (key) => t(lang, key).
• languageNames: Record<Language, string> is { uz: 'O‘zbekcha', 'uz-Cyrl': 'Ўзбекча', ru: 'Русский', en: 'English' }.

Hooks#

packages/ui/src/hooks.ts.

Example#

Names below are all from the files above and from packages/engine/src/map.ts (selectPlace(place, { fly }), where place may be a SearchResult).

import { useState } from 'react';
import { UzMapClient, type Language, type SearchResult } from '@uzmaps/api';
import type { Theme } from '@uzmaps/engine';
import { MapView, SearchBox, ResultList, MapControls, ScaleBar, useUzMap, useSearch } from '@uzmaps/ui';
import '@uzmaps/ui/styles.css';

const api = new UzMapClient({ baseUrl: 'https://uzmaps.ndc.uz', language: 'uz' });

function Search({ language }: { language: Language }) {
  const map = useUzMap();
  const { query, setQuery, results, loading, submit } = useSearch(api, { language });
  return (
    <div className="uz-panel">
      <SearchBox value={query} onChange={setQuery} onSubmit={submit} loading={loading} language={language} listId="results" />
      <div className="uz-surface uz-panel-card">
        <div className="uz-panel-scroll">
          <ResultList
            id="results"
            results={results}
            query={query}
            language={language}
            onSelect={(r: SearchResult) => map?.selectPlace(r, { fly: true })}
          />
        </div>
      </div>
    </div>
  );
}

export default function App() {
  const [theme, setTheme] = useState<Theme>('auto');
  const [language, setLanguage] = useState<Language>('uz');
  return (
    <div className="uz-app" data-uz-theme={theme === 'dark' ? 'dark' : undefined}>
      <MapView serverUrl="https://uzmaps.ndc.uz" theme={theme} language={language} center={[69.2401, 41.2995]} zoom={12}>
        <Search language={language} />
        <MapControls theme={theme} onTheme={setTheme} language={language} onLanguage={setLanguage} onLocate={() => {}} />
        <ScaleBar language={language} />
      </MapView>
    </div>
  );
}

data-uz-theme is set by the application here because the stylesheet only reacts to that attribute. With theme === 'auto' the map picks its own basemap theme, but the panels stay light unless you resolve prefers-color-scheme yourself and set the attribute.

@uzmaps/cartography#

Install#

npm install @uzmaps/cartography

packages/cartography/package.json declares one peer, @maplibre/maplibre-gl-style-spec >=23. style.ts imports only types from it (import type { LayerSpecification, StyleSpecification }), so nothing is loaded from that package at runtime.

Everything exported#

From packages/cartography/src/index.ts:

Exported from a module but not from the package index: furnitureSourceId, customGlyphs and the BadgeIcon / RawIcon / SpriteIcon types, and the expression helpers in expr.ts (zoomLin, zoomExp, zoomMatch, match, …).

buildStyle(options)#

packages/cartography/src/style.ts. Returns a plain StyleSpecification (version: 8) that you can edit before handing to MapLibre.

Other properties of the returned style:

• name is `UzMap ${theme} (${language})` and metadata is { 'uzmap:theme', 'uzmap:language', 'uzmap:version': 1 }.
• light is viewport-anchored with position: [1.15, 210, 52] and intensity 0.32 (light) or 0.22 (dark). The polar angle is high and the intensity low on purpose: MapLibre's intensity is contrast, and a near-horizon light crushes walls facing away from it to near-black.
• transition is { duration: 300, delay: 0 }.
• When a terrain source is present, terrain is { source: 'uzmap-terrain', exaggeration: 1.15 } and a sky block is set from the theme's sky and land tokens.

Sources#

basemapSourceIds is ['uzmap', 'uzmap-terrain', 'uzmap-hillshade', 'uzmap-buildings-ml', 'uzmap-places'] — every source the generator owns, so the engine knows not to carry them over as runtime overlays.

Layer anchors#

export const anchors = {
  overlayFill: 'uz-anchor-overlay-fill',
  overlayLine: 'uz-anchor-overlay-line',
  overlaySymbol: 'uz-anchor-overlay-symbol',
} as const;

Each anchor is a background layer with visibility: 'none' — it paints nothing and exists only as a stable id. All layer ids in the style are namespaced uz-* so overlays can be inserted at known positions. MapLibre's map.addLayer(layer, beforeId) inserts before the named layer, so a layer added against an anchor lands immediately below it in the draw order:

The full order, from buildStyle: ground → hillshade → water → overlay-fill → aeroway → boundaries → flat buildings (uz-building-ml-wall, uz-building-ml, uz-building-wall, uz-building, uz-building-hover, uz-building-hover-line) → roads (uz-road-lowzoom, tunnels, uz-track, uz-path, pedestrian, uz-road-casing, uz-road-fill, uz-road-marking, uz-road-area, rail, bridges, uz-oneway) → furniture → uz-traffic-casing, uz-traffic → extruded buildings (uz-building-ml-base, uz-building-base, uz-building-ml-3d, uz-building-3d, uz-building-hover-3d) → overlay-line → labels → overlay-symbol.

Flat footprints are drawn under the roads because ML footprints traced from imagery often overlap the roadway by a few metres; painted on top they cover the street. Extrusions are drawn above the roads because in a pitched view a building stands in front of the road behind it.

Other layer constants#

• buildingLayers.flat = ['uz-building-wall', 'uz-building-ml-wall', 'uz-building', 'uz-building-ml', 'uz-building-hover', 'uz-building-hover-line']; buildingLayers.threeD = ['uz-building-base', 'uz-building-ml-base', 'uz-building-3d', 'uz-building-ml-3d', 'uz-building-hover-3d']. The engine toggles visibility between the two sets. In 2D the "wall" layer is a darker copy of each footprint translated a fraction of a pixel down-right, which is how a flat overhead map gets its sense of height.
• trafficLayers = ['uz-traffic-casing', 'uz-traffic']. Both start with visibility: 'none'; the engine turns them on with setTraffic().

Example#

import maplibregl from 'maplibre-gl';
import { buildStyle, anchors, themes } from '@uzmaps/cartography';

const map = new maplibregl.Map({
  container: 'map',
  style: buildStyle({ serverUrl: 'https://uzmaps.ndc.uz', theme: 'dark', language: 'ru' }),
  center: [69.2401, 41.2995],
  zoom: 12,
});

map.on('load', () => {
  map.addSource('zones', { type: 'geojson', data: { type: 'FeatureCollection', features: [] } });
  // Inserted before the anchor, so it renders under the roads and above the water.
  map.addLayer(
    { id: 'zones', type: 'fill', source: 'zones', paint: { 'fill-color': themes.dark.route.alt, 'fill-opacity': 0.35 } },
    anchors.overlayFill,
  );
});

nameExpr(language)#

packages/cartography/src/expr.ts. Returns a coalesce expression over name properties, in this order:

The Overture places layer (uz-poi-places) uses a simpler rule: name:ru then name for ru and uz-Cyrl, otherwise name.

Theme tokens#

packages/cartography/src/tokens.ts. ThemeName is 'light' | 'dark'; themes is { light, dark }, each a ThemeTokens. fonts is { regular: ['Noto Sans Regular'], medium: ['Noto Sans Medium'], italic: ['Noto Sans Italic'] }.

Ground, areas and water:

Buildings:

road.*:

The classed road colours are used up to z16.5 and crossfade to asphalt / asphaltCasing by z18. Across a city the class colour is what makes the network legible; standing over one junction it is noise, and the width already carries the classification. marking is the painted centre line, drawn from z17 on motorway through tertiary.

boundary.*:

text.*:

Terrain, overlays and accents:

The traffic ramp is deliberately not the UI's success/warning/danger palette: it sits directly on the roadway and has to stay legible over both themes.

Category and icon tables#

packages/cartography/src/categories.ts and icons.ts. The taxonomy is shared with the server (services/server/internal/taxonomy) and has to be kept in sync with it.

interface CategoryGroup { id: string; icon: string; color: string; label: Record<string, string> }

groups (18 entries; groupById is the same list keyed by id):

Labels are provided for uz, ru and en.

Icon names → group (iconGroup). These 88 names are the keys of glyphs here and of poiIcons in @uzmaps/ui, and are what SearchResult.icon carries:

Sprite manifest:

• glyphs: Record<string, string> maps each icon name to a Lucide glyph file name (e.g. restaurant → utensils, dentist → tooth, metro → metro, tram → tram-front, college → book-marked). Eight glyphs are hand-drawn because Lucide has no equivalent: tooth, metro, obelisk, mosque, synagogue, wc, tram-front, book-marked.
• badgeIcons() returns one { kind: 'badge', name, glyph, color, size: 22 } per glyph, with color from the icon's group (default #4B5563). The style references these as sprite id poi-<name> (for example poi-cafe); an icon name the style cannot map falls back to poi-poi so that a missing sprite does not also drop the label.
• rawIcons lists the hand-drawn SVGs under packages/cartography/icons/raw/: shield-light and shield-dark (stretchable, used for road refs), oneway, dot, dot-ring, star, peak, marker, airport-plane and entrance (SDF, tintable), and marker-shadow, route-start, route-end, route-via, user-location, metro-m (plain).

OpenMapTiles poi layer → icon. poiSubclassIcon is tried first, then poiClassIcon; a POI matching neither is not rendered on the basemap (it remains searchable through the API).

Every place_of_worship maps to mosque because the OpenMapTiles schema does not carry the religion tag, and mosques dominate in Uzbekistan.

iconPriority — higher means shown at a lower zoom. The uz-poi layer shows an icon when its priority is at least the zoom threshold (z13: 88, z14: 70, z15: 50, z16: 34, z17: 20, z18: 0) and its rank is within the zoom's limit (z13: 1, z14: 3, z15: 8, z16: 20, z17: 60, z18: 200). Icons not in the table get priority 10.

Metro stations, railway stations and bus stops are drawn by the separate uz-poi-transit layer (sprites metro-m, poi-train, poi-bus-stop), airports by uz-aerodrome (airport-plane), and named peaks by uz-peak (peak).

Unverified#

• UzMapOptions defaults (autoTiltFlatZoom 12.6, autoTiltZoom 15.6, tiltMax 50, tiles 'server', sources true, maxBounds Uzbekistan, terrainUrl) are quoted from the doc comments in packages/engine/src/types.ts and were confirmed against the constructor, detectSources() and the style URL code in packages/engine/src/map.ts; the rest of map.ts was only checked for method signatures, not read in full.
• The dist/ output of either package was not compared with src/; this page describes the source at the versions in package.json (@uzmaps/ui 0.1.1, @uzmaps/cartography 0.1.0).
• map.userLocation is a UserLocation with start(opts?: PositionOptions) and stop(), so the map.userLocation.start() call in packages/ui/README.md is valid; the example above still uses a no-op onLocate and the geolocation behaviour of UserLocation was not read.
• The lucide-react dependency range in packages/ui/package.json is ^1.39.0; the locked and installed version is 1.39.0 and every icon icons.tsx imports resolves in it.
• Server-side behaviour of the endpoints PlaceCard uses (/api/place/:id, /api/photo) was not read; only the client signatures in packages/api/src/index.ts were.
• The README's claim that its samples are compiled in CI from examples/ is backed by .github/workflows/ci-cd.yml (npx tsc -p examples --noEmit) and examples/ui.tsx; the workflow was not otherwise read.