@krizaka/ui 3.2.0 → 3.4.0

package/dist/map.d.ts

@@ -0,0 +1,463 @@
+import * as tailwind_variants from 'tailwind-variants';
+import * as React from 'react';
+import * as maplibre_gl from 'maplibre-gl';
+import { brands } from '@krizaka/tokens/native';
+import { Flavor } from '@protomaps/basemaps';
+
+/** The basemap extracts: OpenStreetMap data built by Protomaps (ODbL). `world` up to zoom 6, `quebec` (Montréal–Québec) up to 14. */
+declare const MAP_TILES: {
+    readonly world: "https://krizaka-assets.b-cdn.net/maps/v1/tiles/world-20261012.pmtiles";
+    readonly quebec: "https://krizaka-assets.b-cdn.net/maps/v1/tiles/quebec-20261012.pmtiles";
+};
+/** The glyphs of the labels (Noto Sans, SIL OFL): `{fontstack}` and `{range}` filled by MapLibre. */
+declare const MAP_GLYPHS = "https://krizaka-assets.b-cdn.net/maps/v1/fonts/{fontstack}/{range}.pbf";
+/** The words every map shows, as the licences ask: OpenStreetMap's contributors (ODbL) and Protomaps. */
+declare const MAP_ATTRIBUTION: {
+    readonly osm: "© OpenStreetMap contributors";
+    readonly osmUrl: "https://www.openstreetmap.org/copyright";
+    readonly protomaps: "Protomaps";
+    readonly protomapsUrl: "https://protomaps.com";
+};
+/**
+ * Where the maps read the tiles and the glyphs, when not from the CDN itself: a same-origin path that proxies it
+ * (`https://www.krizaka.com/maps/v1`, a rewrite of the site) — no cross-origin request at all. Absolute URL, no trailing slash.
+ */
+declare function setMapAssetsBase(url: string | null): void;
+/** The tiles and glyphs the maps read now: the CDN's, or under the base set by `setMapAssetsBase`. */
+declare function mapAssets(): {
+    tiles: {
+        world: string;
+        quebec: string;
+    };
+    glyphs: string;
+};
+
+/** A position: longitude, latitude (GeoJSON's order, MapLibre's `LngLat`). */
+type LngLat = readonly [lng: number, lat: number];
+/** The great-circle distance between two positions, in metres (haversine). */
+declare function distanceMeters(a: LngLat, b: LngLat): number;
+/** A circle of `radius` metres around `center` as a GeoJSON polygon (`steps` points): a delivery zone, a search radius. */
+declare function circlePolygon(center: LngLat, radius: number, steps?: number): GeoJSON.Feature<GeoJSON.Polygon>;
+/** The Web Mercator pixel of a position at a zoom (256-px tiles): what a static map draws without an engine. */
+declare function project([lng, lat]: LngLat, zoom: number): [number, number];
+/** A distance written the locale's way: metres under 1 km, kilometres (one decimal under 10) above. */
+declare function formatDistance(meters: number, locale: string): string;
+
+/** A product of the family: its accent paints the map. */
+type MapBrand = keyof typeof brands;
+/** A colour mixed into another (`#rrggbb` only): `t` = 0 gives `a`, 1 gives `b`. */
+declare function mix(a: string, b: string, t: number): string;
+/** The colours of the map in a scheme (and a brand): what the style, the markers and the static map share. */
+declare function mapPalette(scheme: "dark" | "light", brand?: MapBrand): {
+    land: string;
+    background: string;
+    water: string;
+    park: string;
+    road: string;
+    roadMajor: string;
+    casing: string;
+    building: string;
+    boundary: string;
+    label: string;
+    labelStrong: string;
+    halo: string;
+    accent: string;
+    onAccent: string;
+};
+/** The basemap flavour of a palette: every role of Protomaps' layers filled from the tokens. */
+declare function mapFlavor(scheme: "dark" | "light", brand?: MapBrand): Flavor;
+/** A region of the basemap: its PMTiles file and the zoom up to which it has tiles. */
+type MapRegion = {
+    url: string;
+    maxzoom: number;
+};
+type MapStyleOptions = {
+    /** `dark` or `light`: the scheme of the page or the app. */
+    scheme: "dark" | "light";
+    /** The product whose accent the map carries (its markers, its water's tint). Default `krizaka`. */
+    brand?: MapBrand;
+    /** The language of the labels (`fr`, `en`): the place names in it where OpenStreetMap has them. Default `en`. */
+    lang?: string;
+    /** The low zooms of the whole world. Default: our world extract (zoom 0–6). */
+    world?: MapRegion | null;
+    /** The detailed region drawn from zoom 7. Default: Montréal–Québec (up to 14, overzoomed beyond). */
+    region?: MapRegion | null;
+    /** The glyphs' URL template. Default: our Noto Sans on the CDN. */
+    glyphs?: string;
+};
+/** The zoom where the detailed region takes over from the world. */
+declare const REGION_FROM_ZOOM = 6.5;
+/**
+ * The MapLibre style of a Krizaka map (a `StyleSpecification`): the world's low zooms, then the detailed region,
+ * painted from the tokens. The `pmtiles://` sources need the PMTiles protocol (the web `Map` registers it; MapLibre
+ * Native reads it as it is).
+ */
+declare function mapStyle({ scheme, brand, lang, world, region, glyphs }: MapStyleOptions): {
+    version: 8;
+    glyphs: string;
+    sources: Record<string, unknown>;
+    layers: {
+        [k: string]: unknown;
+        id: string;
+        minzoom?: number;
+        maxzoom?: number;
+    }[];
+};
+
+type MapLibre = typeof maplibre_gl;
+type MapInstance = maplibre_gl.Map;
+declare const map: tailwind_variants.TVReturnType<{
+    [key: string]: {
+        [key: string]: tailwind_variants.ClassValue | {
+            root?: tailwind_variants.ClassValue;
+            canvas?: tailwind_variants.ClassValue;
+            fallback?: tailwind_variants.ClassValue;
+            controls?: tailwind_variants.ClassValue;
+            attribution?: tailwind_variants.ClassValue;
+            places?: tailwind_variants.ClassValue;
+            markerLabel?: tailwind_variants.ClassValue;
+            control?: tailwind_variants.ClassValue;
+            marker?: tailwind_variants.ClassValue;
+        };
+    };
+} | {
+    [x: string]: {
+        [x: string]: tailwind_variants.ClassValue | {
+            root?: tailwind_variants.ClassValue;
+            canvas?: tailwind_variants.ClassValue;
+            fallback?: tailwind_variants.ClassValue;
+            controls?: tailwind_variants.ClassValue;
+            attribution?: tailwind_variants.ClassValue;
+            places?: tailwind_variants.ClassValue;
+            markerLabel?: tailwind_variants.ClassValue;
+            control?: tailwind_variants.ClassValue;
+            marker?: tailwind_variants.ClassValue;
+        };
+    };
+} | {}, {
+    root: string;
+    canvas: string;
+    fallback: string;
+    controls: string;
+    control: string;
+    attribution: string;
+    places: string;
+    marker: string;
+    markerLabel: string;
+}, undefined, {
+    [key: string]: {
+        [key: string]: tailwind_variants.ClassValue | {
+            root?: tailwind_variants.ClassValue;
+            canvas?: tailwind_variants.ClassValue;
+            fallback?: tailwind_variants.ClassValue;
+            controls?: tailwind_variants.ClassValue;
+            attribution?: tailwind_variants.ClassValue;
+            places?: tailwind_variants.ClassValue;
+            markerLabel?: tailwind_variants.ClassValue;
+            control?: tailwind_variants.ClassValue;
+            marker?: tailwind_variants.ClassValue;
+        };
+    };
+} | {}, {
+    root: string;
+    canvas: string;
+    fallback: string;
+    controls: string;
+    control: string;
+    attribution: string;
+    places: string;
+    marker: string;
+    markerLabel: string;
+}, tailwind_variants.TVReturnTypeLike<unknown, {
+    root: string;
+    canvas: string;
+    fallback: string;
+    controls: string;
+    control: string;
+    attribution: string;
+    places: string;
+    marker: string;
+    markerLabel: string;
+}>>;
+type Registry = {
+    add: (id: string, text: string) => void;
+    remove: (id: string) => void;
+};
+type Ctx = {
+    map: MapInstance | null;
+    lib: MapLibre | null;
+    ready: boolean;
+    reduce: boolean;
+    places: Registry;
+};
+/** The map a child is drawn on (`Marker`, `RadiusCircle`, `Cluster`…): the MapLibre instance once it is ready. */
+declare function useMap(): Ctx;
+/**
+ * Where MapLibre's worker comes from. A bundler (Next.js, Vite) renames MapLibre's module and leaves its worker behind:
+ * by default the worker of the very version the app installed is imported from jsDelivr (free, open source, no key)
+ * through a module worker of the page's own origin. An app with a strict CSP serves it itself —
+ * `configureMaps({ workerUrl: "/maplibre-gl-worker.mjs" })` (with `maplibre-gl-shared.mjs` beside it), once, before a map.
+ * `assetsBase` reads the tiles and glyphs through a same-origin proxy of the CDN (`setMapAssetsBase`).
+ */
+declare function configureMaps(options: {
+    workerUrl?: string;
+    assetsBase?: string;
+}): void;
+type MapLabels = {
+    /** The zoom-in button ("Zoom in"). */
+    zoomIn: string;
+    /** The zoom-out button ("Zoom out"). */
+    zoomOut: string;
+    /** Before the list of places read in place of the map ("Places on the map"). */
+    places: string;
+};
+declare const mapLabels: MapLabels;
+type MapProps = {
+    /** The map's accessible name ("Pick-up points near you"), passed translated. */
+    label: string;
+    /** Where the map looks at first: longitude, latitude. */
+    center: LngLat;
+    /** The zoom at first (0 the world, 12 a city, 16 a street). Default 12. */
+    zoom?: number;
+    /** The camera follows `center` and `zoom` when they change (flies, or jumps under reduced motion). */
+    controlled?: boolean;
+    /** The scheme. Default: the page's (`html.light`), followed. */
+    scheme?: "dark" | "light";
+    /** The product whose accent the map carries. Default `krizaka`. */
+    brand?: MapBrand;
+    /** The language of the labels (`fr`, `en`). Default `en`. */
+    lang?: string;
+    /** The detailed region (PMTiles) drawn from zoom 6.5. Default: our Montréal–Québec extract (to zoom 14). */
+    region?: MapRegion | null;
+    /** The world's low zooms (PMTiles). Default: our world extract (to zoom 6). */
+    world?: MapRegion | null;
+    /** The zoom buttons (default) — the keyboard also zooms with + and − on the focused map. */
+    controls?: boolean;
+    /** Moves with the hand (default); `false` makes a still picture of a place. */
+    interactive?: boolean;
+    /** Shown in place of the map while its engine loads, and for good without WebGL: a `StaticMap`, a picture. */
+    fallback?: React.ReactNode;
+    /** Called when the camera rests: its centre and zoom. */
+    onMoveEnd?: (view: {
+        center: LngLat;
+        zoom: number;
+    }) => void;
+    /** Called with the position pressed on the map (not on a marker). */
+    onPress?: (position: LngLat) => void;
+    /** Markers, circles, clusters, the user's position — and anything drawn over the map. */
+    children?: React.ReactNode;
+    /** The words, passed translated; English by default. */
+    labels?: Partial<MapLabels>;
+    /** Classes merged on the root (its height: `h-80`, `aspect-video`). */
+    className?: string;
+};
+/** A map: MapLibre over our Protomaps tiles, styled from the tokens, with its places as a list for screen readers. */
+declare function Map({ label, center, zoom, controlled, scheme: schemeProp, brand, lang, region, world, controls, interactive, fallback, onMoveEnd, onPress, children, labels: given, className, }: MapProps): React.JSX.Element;
+type MarkerProps = {
+    /** Where it stands. */
+    position: LngLat;
+    /** Its words: the place's name, read in the list of places and as the button's name ("Café Olimpico, 350 m"). */
+    label: string;
+    /** Pressing it (details in a panel, a sheet): the marker becomes a button. */
+    onPress?: () => void;
+    /** The chosen one: larger, its label shown above it. */
+    selected?: boolean;
+    /** Its size in pixels. Default 18. */
+    size?: number;
+    /** What it draws instead of the accent dot (an avatar, an icon). */
+    children?: React.ReactNode;
+};
+/** A place on the map: an accent dot (or your content) that is a button when it does something. */
+declare function Marker({ position, label, onPress, selected, size, children }: MarkerProps): React.ReactPortal | null;
+type UserPositionProps = {
+    /** Where the person is. */
+    position: LngLat;
+    /** Its words ("You are here"), read in the list of places. */
+    label: string;
+    /** The accuracy in metres: a soft disc around the dot. */
+    accuracy?: number;
+};
+/** The person's position: a dot that pulses (still under reduced motion), its accuracy as a soft disc. */
+declare function UserPosition({ position, label, accuracy }: UserPositionProps): React.JSX.Element | null;
+type RadiusCircleProps = {
+    /** Its centre. */
+    center: LngLat;
+    /** Its radius in metres. */
+    radius: number;
+    /** `accent` (a zone that matters: a delivery area, a search radius) or `soft` (an accuracy). */
+    tone?: "accent" | "soft";
+};
+/** A circle on the ground: a delivery zone, a search radius — filled with the accent, its edge drawn. */
+declare function RadiusCircle({ center, radius, tone }: RadiusCircleProps): null;
+type ClusterPoint = {
+    id: string;
+    position: LngLat;
+    label: string;
+};
+type ClusterProps = {
+    /** The points: many of them (creators, pick-up points, events). */
+    points: readonly ClusterPoint[];
+    /** Pressing a single point. A group zooms in to open itself. */
+    onPointPress?: (point: ClusterPoint) => void;
+    /** The radius, in pixels, within which points group. Default 48. */
+    radius?: number;
+};
+/** Many points grouped while they are close: a disc with the count, opened by zooming in; each point is listed for screen readers. */
+declare function Cluster({ points, onPointPress, radius }: ClusterProps): null;
+
+declare const locationPicker: tailwind_variants.TVReturnType<{
+    [key: string]: {
+        [key: string]: tailwind_variants.ClassValue | {
+            root?: tailwind_variants.ClassValue;
+            status?: tailwind_variants.ClassValue;
+            frame?: tailwind_variants.ClassValue;
+            pin?: tailwind_variants.ClassValue;
+            bar?: tailwind_variants.ClassValue;
+            chip?: tailwind_variants.ClassValue;
+            near?: tailwind_variants.ClassValue;
+        };
+    };
+} | {
+    [x: string]: {
+        [x: string]: tailwind_variants.ClassValue | {
+            root?: tailwind_variants.ClassValue;
+            status?: tailwind_variants.ClassValue;
+            frame?: tailwind_variants.ClassValue;
+            pin?: tailwind_variants.ClassValue;
+            bar?: tailwind_variants.ClassValue;
+            chip?: tailwind_variants.ClassValue;
+            near?: tailwind_variants.ClassValue;
+        };
+    };
+} | {}, {
+    root: string;
+    frame: string;
+    pin: string;
+    bar: string;
+    chip: string;
+    near: string;
+    status: string;
+}, undefined, {
+    [key: string]: {
+        [key: string]: tailwind_variants.ClassValue | {
+            root?: tailwind_variants.ClassValue;
+            status?: tailwind_variants.ClassValue;
+            frame?: tailwind_variants.ClassValue;
+            pin?: tailwind_variants.ClassValue;
+            bar?: tailwind_variants.ClassValue;
+            chip?: tailwind_variants.ClassValue;
+            near?: tailwind_variants.ClassValue;
+        };
+    };
+} | {}, {
+    root: string;
+    frame: string;
+    pin: string;
+    bar: string;
+    chip: string;
+    near: string;
+    status: string;
+}, tailwind_variants.TVReturnTypeLike<unknown, {
+    root: string;
+    frame: string;
+    pin: string;
+    bar: string;
+    chip: string;
+    near: string;
+    status: string;
+}>>;
+type LocationPickerLabels = {
+    /** The button that centres the map on the person ("Near me"). */
+    nearMe: string;
+    /** While the position is asked ("Finding you…"). */
+    locating: string;
+    /** The person refused ("Location is off for this site. Move the map instead."). */
+    denied: string;
+    /** No position (no GPS, a timeout) ("We could not find you. Move the map instead."). */
+    unavailable: string;
+    /** The person's place in the list of places ("You are here"). */
+    you: string;
+    /** The distance chip, from a written distance ("1.2 km from you"). */
+    distance: (distance: string) => string;
+};
+declare const locationPickerLabels: LocationPickerLabels;
+type LocationPickerProps = Pick<MapProps, "scheme" | "brand" | "lang" | "region" | "world" | "fallback" | "className"> & {
+    /** The picker's accessible name ("Meeting point"), passed translated. */
+    label: string;
+    /** The chosen position (controlled): the centre of the map. */
+    value: LngLat;
+    /** Called when the map rests on a new position. */
+    onValueChange: (value: LngLat) => void;
+    /** The BCP 47 locale of the distance. */
+    locale: string;
+    /** The zoom at first. Default 14. */
+    zoom?: number;
+    /** A radius in metres drawn around the chosen position (a delivery zone, a search radius). */
+    radius?: number;
+    /** Where the person is, when the app already knows it (the distance chip shows at once). */
+    origin?: LngLat | null;
+    /** The words, passed translated; English by default. */
+    labels?: Partial<LocationPickerLabels>;
+};
+/** A position picked by moving the map under a pin; its distance from the person; "near me" on request. */
+declare function LocationPicker({ label, value, onValueChange, locale, zoom, radius, origin: originProp, labels: given, className, ...map }: LocationPickerProps): React.JSX.Element;
+
+declare const staticMap: tailwind_variants.TVReturnType<{
+    [key: string]: {
+        [key: string]: tailwind_variants.ClassValue | {
+            root?: tailwind_variants.ClassValue;
+            attribution?: tailwind_variants.ClassValue;
+            svg?: tailwind_variants.ClassValue;
+        };
+    };
+} | {
+    [x: string]: {
+        [x: string]: tailwind_variants.ClassValue | {
+            root?: tailwind_variants.ClassValue;
+            attribution?: tailwind_variants.ClassValue;
+            svg?: tailwind_variants.ClassValue;
+        };
+    };
+} | {}, {
+    root: string;
+    svg: string;
+    attribution: string;
+}, undefined, {
+    [key: string]: {
+        [key: string]: tailwind_variants.ClassValue | {
+            root?: tailwind_variants.ClassValue;
+            attribution?: tailwind_variants.ClassValue;
+            svg?: tailwind_variants.ClassValue;
+        };
+    };
+} | {}, {
+    root: string;
+    svg: string;
+    attribution: string;
+}, tailwind_variants.TVReturnTypeLike<unknown, {
+    root: string;
+    svg: string;
+    attribution: string;
+}>>;
+type StaticMapPlace = {
+    position: LngLat;
+    label: string;
+};
+type StaticMapProps = {
+    /** What the picture shows, in words ("Three pick-up points in the Plateau"), passed translated: its accessible name. */
+    label: string;
+    /** The centre of the picture. */
+    center: LngLat;
+    /** The zoom of the picture. Default 12. */
+    zoom?: number;
+    /** The places drawn on it (an accent dot each), listed in its name. */
+    places?: readonly StaticMapPlace[];
+    /** A snapshot of the real map of the area (same centre and zoom), drawn under the places; the attribution then shows. */
+    image?: string;
+    /** Classes merged on the root (its size). */
+    className?: string;
+};
+/** A still map: the places on the map's paper (or on a snapshot), named in words. */
+declare function StaticMap({ label, center, zoom, places, image, className }: StaticMapProps): React.JSX.Element;
+
+export { Cluster, type ClusterPoint, type ClusterProps, type LngLat, LocationPicker, type LocationPickerLabels, type LocationPickerProps, MAP_ATTRIBUTION, MAP_GLYPHS, MAP_TILES, Map, type MapBrand, type MapLabels, type MapProps, type MapRegion, type MapStyleOptions, Marker, type MarkerProps, REGION_FROM_ZOOM, RadiusCircle, type RadiusCircleProps, StaticMap, type StaticMapPlace, type StaticMapProps, UserPosition, type UserPositionProps, circlePolygon, configureMaps, distanceMeters, formatDistance, locationPicker, locationPickerLabels, map, mapAssets, mapFlavor, mapLabels, mapPalette, mapStyle, mix, project, setMapAssetsBase, staticMap, useMap };