From ef22c0b4936ff61a218def5fa57be75d1f286588 Mon Sep 17 00:00:00 2001
From: Anton Tranelis <mail@antontranelis.de>
Date: Fri, 28 Feb 2025 07:13:08 +0000
Subject: [PATCH] documented UtopiaMap, Tags, Tag and  Permissions

---
 src/Components/Map/Permissions.tsx | 43 +++++++++++++++++++++++-------
 src/Components/Map/Tags.tsx        | 22 +++++++++++++++
 src/Components/Map/UtopiaMap.tsx   | 41 ++++++++++++++++++++++++++++
 src/types/Tag.d.ts                 | 31 +++++++++++++++++++++
 4 files changed, 128 insertions(+), 9 deletions(-)

diff --git a/src/Components/Map/Permissions.tsx b/src/Components/Map/Permissions.tsx
index 4091319b..0cd33c8a 100644
--- a/src/Components/Map/Permissions.tsx
+++ b/src/Components/Map/Permissions.tsx
@@ -7,21 +7,46 @@ import { useSetPermissionData, useSetPermissionApi, useSetAdminRole } from './ho
 import type { ItemsApi } from '#types/ItemsApi'
 import type { Permission } from '#types/Permission'
 
-/**
- * @category Types
- */
-export interface PermissionsProps {
-  data?: Permission[]
-  api?: ItemsApi<Permission>
-  adminRole?: string
-}
 export type { Permission } from '#types/Permission'
 export type { ItemsApi } from '#types/ItemsApi'
 
 /**
+ * This Components injects Permissions comming from an {@link ItemsApi | `API`}
+ * ```tsx
+ * <Permissions api={itemsApiInstance} adminRole="8141dee8-8e10-48d0-baf1-680aea271298" />
+ * ```
+ * or from on {@link Permission| `Array`}
+ * ```tsx
+ * <Permissions data={permissions} adminRole="8141dee8-8e10-48d0-baf1-680aea271298" />
+ * ```
+ * Can be child of {@link AppShell | `AppShell`}
+ * ```tsx
+ * <AppShell>
+ *     ...
+ *     <Permissions api={itemsApiInstance} adminRole="8141dee8-8e10-48d0-baf1-680aea271298" />
+ * </AppShell>
+ *  ```
+ * Or child of {@link UtopiaMap | `UtopiaMap`}
+ * ```tsx
+ * <UtopiaMap>
+ *     ...
+ *     <Permissions api={itemsApiInstance} adminRole="8141dee8-8e10-48d0-baf1-680aea271298" />
+ * </UtopiaMap>
+ * ```
  * @category Map
  */
-export function Permissions({ data, api, adminRole }: PermissionsProps) {
+export function Permissions({
+  data,
+  api,
+  adminRole,
+}: {
+  /** Array with all the permissions inside */
+  data?: Permission[]
+  /** API to fetch all the permissions from a server */
+  api?: ItemsApi<Permission>
+  /** UUID of the admin role which has always all the permissions */
+  adminRole?: string
+}) {
   const setPermissionData = useSetPermissionData()
   const setPermissionApi = useSetPermissionApi()
   const setAdminRole = useSetAdminRole()
diff --git a/src/Components/Map/Tags.tsx b/src/Components/Map/Tags.tsx
index 7415560e..fb435f1a 100644
--- a/src/Components/Map/Tags.tsx
+++ b/src/Components/Map/Tags.tsx
@@ -8,6 +8,28 @@ import type { ItemsApi } from '#types/ItemsApi'
 import type { Tag } from '#types/Tag'
 
 /**
+ * This Components injects Tags comming from an {@link ItemsApi | `API`}
+ * ```tsx
+ * <Tags api={tagsApi} />
+ * ```
+ * or from on {@link Tag| `Array`}
+ * ```tsx
+ * <Tags data={tags} />
+ * ```
+ * Can be child of {@link AppShell | `AppShell`}
+ * ```tsx
+ * <AppShell>
+ *     ...
+ *     <Tags api={tagsApi} />
+ * </AppShell>
+ *  ```
+ * Or child of {@link UtopiaMap | `UtopiaMap`}
+ * ```tsx
+ * <UtopiaMap>
+ *     ...
+ *     <Tags api={tagsApi} />
+ * </UtopiaMap>
+ * ```
  * @category Map
  */
 export function Tags({ data, api }: { data?: Tag[]; api?: ItemsApi<Tag> }) {
diff --git a/src/Components/Map/UtopiaMap.tsx b/src/Components/Map/UtopiaMap.tsx
index 5bab58fb..be014472 100644
--- a/src/Components/Map/UtopiaMap.tsx
+++ b/src/Components/Map/UtopiaMap.tsx
@@ -9,6 +9,37 @@ import 'react-toastify/dist/ReactToastify.css'
 import type { GeoJsonObject } from 'geojson'
 
 /**
+ * This component creates the map.
+ * ```tsx
+ *   <UtopiaMap center={[50.6, 9.5]} zoom={5} height="100dvh" width="100dvw" />
+ *  ```
+ * You can define its {@link Layer | `Layers`}  as supcomponents.
+ * ```tsx
+ *     <UtopiaMap center={[50.6, 15.5]} zoom={5} height="100dvh" width="100dvw">
+ *       <Layer
+ *         name="events"
+ *         markerIcon="calendar"
+ *         markerShape="square"
+ *         markerDefaultColor="#700"
+ *         data={events}
+ *       />
+ *       <Layer
+ *         name="places"
+ *         markerIcon="point"
+ *         markerShape="circle"
+ *         markerDefaultColor="#007"
+ *         data={places}
+ *       />
+ *     </UtopiaMap>
+ *  ```
+ * You can also pass {@link Tags | `Tags`}  or {@link Permissions | `Permissions`}  as subcomponents.
+ * ```tsx
+ *     <UtopiaMap center={[50.6, 15.5]} zoom={5} height="100dvh" width="100dvw">
+ *       ...
+ *       <Tags data={tags} />
+ *       <Permissions data={permissions} />
+ *     </UtopiaMap>
+ * ```
  * @category Map
  */
 function UtopiaMap({
@@ -23,15 +54,25 @@ function UtopiaMap({
   showLayerControl = true,
   donationWidget,
 }: {
+  /** height of the map (default '500px') */
   height?: string
+  /** width of the map (default '100%') */
   width?: string
+  /** initial centered position of the map (default [50.6, 9.5]) */
   center?: [number, number]
+  /** initial zoom level of the map (default 10) */
   zoom?: number
+  /** React child-components */
   children?: React.ReactNode
+  /** GeoJSON to display on the map */
   geo?: GeoJsonObject
+  /** show the filter control widget (default false) */
   showFilterControl?: boolean
+  /** show the gratitude control widget (default false) */
   showLayerControl?: boolean
+  /** show the layer control widget (default true) */
   showGratitudeControl?: boolean
+  /** ask to donate to the Utopia Project OpenCollective campaign (default false) */
   donationWidget?: boolean
 }) {
   return (
diff --git a/src/types/Tag.d.ts b/src/types/Tag.d.ts
index 0999d7cd..c1dc7de8 100644
--- a/src/types/Tag.d.ts
+++ b/src/types/Tag.d.ts
@@ -1,4 +1,35 @@
 /**
+ * Tags are used to tag items within the app and the map and to filter by keywords. Every tag has a color.
+ * @example
+ * ```ts
+ * export const tags: Tag[] = [
+ *  { 
+ *   "id": "e19f46a7-77a4-4a50-99a2-a942dce843a3",
+ *   "name": "nature",
+ *   "color": "#9bc53d"
+ * },
+ * {
+ *   "id": "2c2099a6-23ac-4308-b91c-86eefeff3a1d",
+ *   "name": "utopia",
+ *   "color": "#c3423f"
+ * },
+ * {
+ *   "id": "48b2de97-2b9e-432b-b230-7bdc9a5fb6c0",
+ *   "name": "map",
+ *   "color": "#5bc0eb"
+ * },
+ * {
+ *   "id": "c88f52e6-357b-45fb-a171-9c2b1dceeb8e",
+ *   "name": "food",
+ *   "color": "#6761a8"
+ * },
+ * {
+ *   "id": "8928cb92-a3c1-4d83-9495-c2eb4fac0bbe",
+ *   "name": "permaculture",
+ *   "color": "#44344f"
+ * },
+ *];
+```
  * @category Types
  */
 export interface Tag {