From c68b1baf8c9daf8a71bba07079bb677f63bff628 Mon Sep 17 00:00:00 2001 From: Alexis <35.alexis.pele@gmail.com> Date: Fri, 4 Apr 2025 21:46:56 +0200 Subject: [PATCH] Added docs for interfaces --- src/components/maps/Map.astro | 4 -- src/types/Leaflet.ts | 64 ++++++++++++++++++++++++++++++ src/types/Map.ts | 73 ++++++++++++++++++++++++++++++++++- 3 files changed, 136 insertions(+), 5 deletions(-) diff --git a/src/components/maps/Map.astro b/src/components/maps/Map.astro index 4115249a..71ec6bc4 100644 --- a/src/components/maps/Map.astro +++ b/src/components/maps/Map.astro @@ -2,15 +2,11 @@ import type { MapMarker, PlayerMarker } from '@/types/Leaflet'; import type { MapProps } from '@/types/Map'; import MarkerCreator from './overlay/MarkerCreator.vue'; -import { t } from '@/i18n/store'; -import { getLangFromUrl } from '@/i18n/utils'; -import { normalizeString } from '@/utils/Strings'; import MarkerContent from './MarkerContent.astro'; interface Props extends MapProps {} const { - title, mapKey, zoomifyKey, mapHeight, // diff --git a/src/types/Leaflet.ts b/src/types/Leaflet.ts index 2d94b539..90027445 100644 --- a/src/types/Leaflet.ts +++ b/src/types/Leaflet.ts @@ -7,26 +7,90 @@ export type MapCoords = { } export type MapMarker = { + /** + * The title of the marker (must be unique). + */ title: string, + /** + * The coordinates of the marker. + * @example { x: 123, y: 456 } + */ markerCoords: MapCoords, + /** + * The description of the marker. + */ description?: string, + /** + * The link that can appear on the marker title. + * @example https://example.com + */ link?: string, + /** + * The ID of the map the marker is supposed to point to. + * + * This should be a valid path of the `maps/data` folder. + * @example "fr/aldys/borelis" + */ mapId?: string, + /** + * The group that the marker belongs to. + * @example "capitals" + */ group?: MapMarkerGroup, + /** + * The icon that the marker should use. + * @example "castle" + */ icon?: MapMarkerIcon, + /** + * Cover image for the marker. + * This should be a valid image in the public folder. + * + * @example "Ambrose.webp" + */ cover?: string, + /** + * The link to the cover image's source. + */ coverLink?: string, + /** + * The author of the cover image. + */ coverAuthor?: string, + /** + * Whether the cover image should be displayed in portrait mode. + */ coverPortrait?: boolean } +/** + * A marker that is used to display players' location on the map. + */ export type PlayerMarker = { + /** + * The title of the marker (must be unique). + */ title: string, + /** + * The coordinates of the marker. + * @example { x: 123, y: 456 } + */ markerCoords: MapCoords, + /** + * The description of the marker. + */ description?: string, + /** + * The link that can appear on the marker title. + * @example https://example.com + */ link?: string, } +/** + * A marker that is used to display a custom location on the map. + * These are only used on the client side and are not saved anywhere else. + */ export type CustomMarker = { lat: number, lon: number, diff --git a/src/types/Map.ts b/src/types/Map.ts index 4102f0d5..b05b1a46 100644 --- a/src/types/Map.ts +++ b/src/types/Map.ts @@ -1,34 +1,105 @@ import type { MapMarker, PlayerMarker } from "./Leaflet" +/** + * A breadcrumb item. + */ export interface BreadcrumbItem { + /** + * The label of the breadcrumb. + */ name: string + /** + * The URL the breadcrumb points to. + */ url: string } +/** + * Search configuration options for the map overlay. + * This is used to filter the markers on the map. + */ export interface SearchConfig { + /** Whether to disable the quests in the search bar. */ disableQuests?: boolean + /** Whether to disable the capitals in the search bar. */ disableCapitals?: boolean + /** Whether to disable the landmarks in the search bar. */ disableLandmarks?: boolean } export interface MapProps { - title: string + /** + * The ID of the map. + * This is used to identify the map and store custom markers in the local storage. + * @example "fr/aldys/borelis" + */ mapKey: string + /** + * The ID of the map in the zoomify folder. + */ zoomifyKey: string + /** + * Height of the map in pixels. + * This information is generated by the zoomify tool. + * @example 30000 + */ mapHeight: number + /** + * Width of the map in pixels. + * This information is generated by the zoomify tool. + * @example 30000 + */ mapWidth: number + /** + * List of markers to display on the map. + */ markers?: MapMarker[] + /** + * Current player position on the map. + */ players?: PlayerMarker + /** + * Main unit of the map. + */ rulerMainUnit?: string + /** + * Ratio used to convert the map units to their relevant unit. + */ rulerDistanceRatio?: number + /** + * Whether to show the walking distance in the ruler. + */ rulerHideWalkDistance?: boolean + /** + * Default background color of the map. + * @exemple "#FFF" + */ backgroundColor?: string } export interface MapOverlayProps { + /** + * The ID of the map. + * This is used to identify the map and store custom markers in the local storage. + * @example "fr/aldys/borelis" + */ mapKey: string + /** + * List of markers to display on the map. + */ markers?: MapMarker[] + /** + * Current player position on the map. + */ players?: PlayerMarker + /** + * Configuration for the search bar. + * This is used to filter the markers on the map. + * @example { disableQuests: true, disableCapitals: false, disableLandmarks: false } + */ searchConfig?: SearchConfig + /** + * List of breadcrumbs to display. + */ breadcrumbs?: BreadcrumbItem[] }