From 67a5e6e22d2adf6138738251ef867f25fdeae1e5 Mon Sep 17 00:00:00 2001 From: Anton Tranelis <31516529+antontranelis@users.noreply.github.com> Date: Tue, 22 Apr 2025 00:21:11 +0100 Subject: [PATCH] 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 --- src/Components/Map/Permissions.tsx | 43 +++++++++++++++----- src/Components/Map/Tags.tsx | 22 ++++++++++ src/Components/Map/UtopiaMap.tsx | 58 +++++++++++++++++++++++++-- src/Components/Map/UtopiaMapInner.tsx | 12 ++++-- src/types/Tag.d.ts | 31 ++++++++++++++ src/types/UtopiaMapProps.d.ts | 17 -------- 6 files changed, 150 insertions(+), 33 deletions(-) delete mode 100644 src/types/UtopiaMapProps.d.ts 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 - 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 + * + * ``` + * or from on {@link Permission| `Array`} + * ```tsx + * + * ``` + * Can be child of {@link AppShell | `AppShell`} + * ```tsx + * + * ... + * + * + * ``` + * Or child of {@link UtopiaMap | `UtopiaMap`} + * ```tsx + * + * ... + * + * + * ``` * @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 + /** 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 + * + * ``` + * or from on {@link Tag| `Array`} + * ```tsx + * + * ``` + * Can be child of {@link AppShell | `AppShell`} + * ```tsx + * + * ... + * + * + * ``` + * Or child of {@link UtopiaMap | `UtopiaMap`} + * ```tsx + * + * ... + * + * + * ``` * @category Map */ export function Tags({ data, api }: { data?: Tag[]; api?: ItemsApi }) { diff --git a/src/Components/Map/UtopiaMap.tsx b/src/Components/Map/UtopiaMap.tsx index 6d89cebb..0832631d 100644 --- a/src/Components/Map/UtopiaMap.tsx +++ b/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 + * + * ``` + * You can define its {@link Layer | `Layers`} as supcomponents. + * ```tsx + * + * + * + * + * ``` + * You can also pass {@link Tags | `Tags`} or {@link Permissions | `Permissions`} as subcomponents. + * ```tsx + * + * ... + * + * + * + * ``` * @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 ( {children} diff --git a/src/Components/Map/UtopiaMapInner.tsx b/src/Components/Map/UtopiaMapInner.tsx index 4a7f15ac..9cea4335 100644 --- a/src/Components/Map/UtopiaMapInner.tsx +++ b/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 } from 'geojson' +import type { Feature, Geometry as GeoJSONGeometry, GeoJsonObject } 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() 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 { diff --git a/src/types/UtopiaMapProps.d.ts b/src/types/UtopiaMapProps.d.ts deleted file mode 100644 index cbcf02ce..00000000 --- a/src/types/UtopiaMapProps.d.ts +++ /dev/null @@ -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 -}