docs(docu): improved documentation (#169)

* rollup - fail when typescript has warnings or errors

Currently this is detected when building the docu. Since the developer
rarely does that the problem is detected on github.
This change allows the developer to discover the error early by failing
the build.

* cleand up types of UtopiaMap and UtopiaMapInner

* documented UtopiaMap, Tags, Tag and  Permissions

---------

Co-authored-by: Ulf Gebhardt <ulf.gebhardt@webcraft-media.de>

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()

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> }) {

src/Components/Map/UtopiaMap.tsx

@@ -5,9 +5,40 @@ import { ContextWrapper } from '#components/AppShell/ContextWrapper'
 
 import { UtopiaMapInner } from './UtopiaMapInner'
 
-import type { UtopiaMapProps } from '#types/UtopiaMapProps'
+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({
@@ -20,9 +51,29 @@ function UtopiaMap({
   showFilterControl = false,
   showGratitudeControl = false,
   showLayerControl = true,
-  infoText,
   donationWidget,
-}: UtopiaMapProps) {
+}: {
+  /** 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 (
     <ContextWrapper>
       <MapContainer
@@ -37,7 +88,6 @@ function UtopiaMap({
           showFilterControl={showFilterControl}
           showGratitudeControl={showGratitudeControl}
           showLayerControl={showLayerControl}
-          infoText={infoText}
           donationWidget={donationWidget}
         >
           {children}

src/Components/Map/UtopiaMapInner.tsx

@@ -34,8 +34,7 @@ import { TextView } from './Subcomponents/ItemPopupComponents/TextView'
 import { SelectPosition } from './Subcomponents/SelectPosition'
 
 import type { ItemFormPopupProps } from '#types/ItemFormPopupProps'
-import type { UtopiaMapProps } from '#types/UtopiaMapProps'
+import type { Feature, Geometry as GeoJSONGeometry, GeoJsonObject } from 'geojson'
-import type { Feature, Geometry as GeoJSONGeometry } from 'geojson'
 
 export function UtopiaMapInner({
   children,
@@ -44,7 +43,14 @@ export function UtopiaMapInner({
   showGratitudeControl = false,
   showLayerControl = true,
   donationWidget,
-}: UtopiaMapProps) {
+}: {
+  children?: React.ReactNode
+  geo?: GeoJsonObject
+  showFilterControl?: boolean
+  showLayerControl?: boolean
+  showGratitudeControl?: boolean
+  donationWidget?: boolean
+}) {
   const selectNewItemPosition = useSelectPosition()
   const setSelectNewItemPosition = useSetSelectPosition()
   const setClusterRef = useSetClusterRef()

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 {

src/types/UtopiaMapProps.d.ts

@@ -1,17 +0,0 @@
-import type { Tag } from './Tag'
-import type { GeoJsonObject } from 'geojson'
-
-export interface UtopiaMapProps {
-  height?: string
-  width?: string
-  center?: [number, number]
-  zoom?: number
-  tags?: Tag[]
-  children?: React.ReactNode
-  geo?: GeoJsonObject
-  showFilterControl?: boolean
-  showLayerControl?: boolean
-  showGratitudeControl?: boolean
-  infoText?: string
-  donationWidget?: boolean
-}