diff --git a/README.md b/README.md index 1efb28dc..6a1e9656 100644 --- a/README.md +++ b/README.md @@ -2,41 +2,196 @@ The Utopia Map is a flexible collaborative app for decentralized coordination and real-life networking that can be adapted to the specific requirements of different networks. Its central element is the interactive geographical map, where users can add and manage **Items** in predefined **Layers**. -Utopia Map is made for networks and initiatives that aim to connect people in real life. By providing a custom instance of Utopia Map, each network can grow and coordinate its ecosystem effectively while encouraging real-world interactions and collaborations. +Utopia Map is made for networks and initiatives that aim to connect people in real life. By providing a custom instance of Utopia Map, each network can grow and coordinate its ecosystem effectively while encouraging real-world interactions and collaborations. -**Utopia Map** is based on **[Utopia UI](https://github.com/utopia-os/utopia-ui)**. +**Utopia Map** is based on our library **[Utopia UI](https://github.com/utopia-map/lib)**. -## Key Features +## ✨ Key Features - **Interactive Map**: The core feature is an intuitive geographical map where users can add, edit, and manage items like members, activities, and resources. Each map instance has its own identity, users, and unique configuration. - **Customizable Layers**: Items are organized into predefined Layers, each with specific icons, colors, texts, and Map Markers. This ensures clarity and relevance for different networks. -- **Dynamic Map Markers**: Geographic position of item are indicated on the map by adaptive and customizable Map Markers +- **Dynamic Map Markers**: Geographic positions of items are indicated on the map by adaptive and customizable Map Markers - **Popups**: Clicking a Map Marker reveals a Popup — a compact preview of the Item with its most relevant information. Define custom Popups for each of your Layers. - **Profiles**: Each Item has a dedicated Profile that showcases all its associated data, making it easier to explore and manage. Define custom profiles for each of your Layers. +- **Authentication System**: Built-in user authentication with login, signup, and password reset functionality +- **Permission Management**: Role-based access control for different user types +- **Gaming Elements**: Quest system for gamification and user engagement -## Deployment Options +## 🏗️ Architecture -- **SaaS**: A hosted solution with regular updates and support for easy onboarding and maintenance. -- **Self-Hosted**: Deploy on your own infrastructure to retain full control and customization. +Utopia Map consists of three main parts: -## Getting Started +### 1. Frontend Application (`/frontend`) +A React-based single-page application that provides the user interface for the map and all its features. -Clone the repository and get started with the following commands: +### 2. Component Library (`/lib` - published as `utopia-ui`) +A reusable React component library that contains all the UI components needed to build mapping applications. + +### 3. Backend (`/backend`) +A Directus-powered backend that handles data management, user authentication, and API services. + +## 🔑 Core Concepts + +- **Maps**: Each instance can have its own identity, users, and unique configuration +- **Items**: Geographic entities added to the map (members, activities, resources) +- **Layers**: Predefined categories for organizing items with specific icons, colors, and markers +- **Popups**: Compact previews shown when clicking map markers +- **Profiles**: Detailed views for each item with customizable templates +- **Tags**: Flexible categorization system for items +- **Permissions**: Fine-grained role-based access control +- **Attestations**: Verification system for items and users + +## 🛠️ Tech Stack + +### Frontend +- **React 18** with TypeScript +- **Vite** for fast development and building +- **Tailwind CSS** & **DaisyUI** for styling +- **React Router** for navigation +- **@directus/sdk** for backend communication +- **Leaflet** for map functionality + + +### Component Library (Utopia UI) +- **Rollup** for building +- **TypeScript** for type safety +- **Vitest** for unit testing +- **Cypress** for component testing +- **TypeDoc** for documentation + +### Backend +- **Directus CMS** +- **Docker** +- **GraphQL** & **REST API** + +## 🚀 Getting Started + +### Prerequisites +- Node.js (see `.tool-versions` for specific version) +- npm or yarn + +### Installation + +Clone the repository and install dependencies: ```bash +git clone https://github.com/utopia-os/utopia-map.git +cd utopia-map +``` + +#### Frontend Development +```bash +cd frontend npm install npm run dev ``` -## Get your Map! 🌱 🌍 +The frontend will be available at `http://localhost:5173`. + +#### Component Library Development +```bash +cd lib +npm install +npm run start # Watch mode +npm run build # Production build +``` + +#### Backend Setup +```bash +cd backend +docker-compose up +``` + +## 📁 Project Structure + +``` +utopia-map/ +├── frontend/ # React application +│ ├── src/ +│ │ ├── api/ # API integration layer +│ │ ├── pages/ # Page components +│ │ └── routes/ # Routing configuration +│ └── public/ # Static assets +├── lib/ # Utopia UI component library +│ ├── src/ +│ │ ├── Components/ # Reusable components +│ │ │ ├── AppShell/ # App layout components +│ │ │ ├── Auth/ # Authentication components +│ │ │ ├── Gaming/ # Quest system +│ │ │ ├── Input/ # Form components +│ │ │ ├── Item/ # Item management +│ │ │ ├── Map/ # Map components +│ │ │ ├── Profile/ # Profile components +│ │ │ └── Templates/# UI templates +│ │ ├── Utils/ # Utility functions +│ │ └── types/ # TypeScript definitions +│ └── examples/ # Example implementations +└── backend/ # Directus backend + ├── directus-config/ # Configuration files + └── extensions/ # Custom extensions +``` + +## 💻 Development + +### Available Scripts + +#### Frontend +```bash +npm run dev # Start development server +npm run build # Build for production +npm run preview # Preview production build +npm run test:lint:eslint # Run linting +``` + +#### Component Library +```bash +npm run start # Watch mode +npm run build # Build library +npm run test:unit # Run unit tests +npm run test:component # Run component tests +npm run lint # Run linting +npm run docs:generate # Generate documentation +``` + +### Code Quality +- **ESLint** & **Prettier** for code formatting +- **TypeScript** strict mode enabled +- Testing with **Vitest** and **Cypress** +- Documentation with **TypeDoc** + +## 🌐 Deployment Options + +### SaaS +A hosted solution with regular updates and support for easy onboarding and maintenance. + +### Self-Hosted +Deploy on your own infrastructure to retain full control and customization: + +## 📚 Examples + +The library includes three example implementations in `/lib/examples/`: + +1. **[Basic Map](https://github.com/utopia-os/utopia-map/tree/main/lib/examples/1-basic-map)** - Simple map implementation +2. **[Static Layers](https://github.com/utopia-os/utopia-map/tree/main/lib/examples/2-static-layers)** - Map with predefined layers +3. **[Tags](https://github.com/utopia-os/utopia-map/tree/main/lib/examples/3-tags)** - Implementation with tagging system + +## 🌱 Get your Map! Start mapping and growing your community ecosystem together with your custom map. [Join us on Telegram](https://t.me/UtopiaMap) -## Support Utopia Map 💚 +## 💚 Support Utopia Map -We are building Utopia Map as an free and opensource tool. To keep this project sustainable and accessible, we need financial support as well as Developrs, UX Designer, Community Managers and Content Creators. +We are building Utopia Map as a free and open-source tool. To keep this project sustainable and accessible, we need financial support as well as Developers, UX Designers, Community Managers and Content Creators. + +### How to Contribute + +- **Code**: Submit pull requests with improvements +- **Documentation**: Help improve our docs +- **Translation**: Help translate the interface +- **Testing**: Report bugs and test new features +- **Design**: Contribute UI/UX improvements [Join us on Telegram](https://t.me/UtopiaMap) and support us on [OpenCollective](https://opencollective.com/utopia-project) @@ -44,4 +199,12 @@ We are building Utopia Map as an free and opensource tool. To keep this project +## 📄 License + +This project is licensed under the terms specified in the LICENSE file. + +## 🙏 Acknowledgments + +Utopia Map is built with and depends on many amazing open-source projects. Special thanks to all contributors and supporters who make this project possible. + diff --git a/frontend/package-lock.json b/frontend/package-lock.json index 62763057..66a22349 100644 --- a/frontend/package-lock.json +++ b/frontend/package-lock.json @@ -18,7 +18,7 @@ "react-dom": "^18.2.0", "react-rnd": "^10.4.1", "react-router-dom": "^6.23.0", - "utopia-ui": "^3.0.105" + "utopia-ui": "^3.0.106" }, "devDependencies": { "@eslint-community/eslint-plugin-eslint-comments": "^4.4.1", @@ -11438,9 +11438,9 @@ } }, "node_modules/utopia-ui": { - "version": "3.0.105", - "resolved": "https://registry.npmjs.org/utopia-ui/-/utopia-ui-3.0.105.tgz", - "integrity": "sha512-QihvnHeR0R9GXIZ/Mx1EBlsYBthhykM/jPdfN/5bHyyBAXGX0jm+6msEySo0jFWASxPr2G4rhImJJzeRxPyUhw==", + "version": "3.0.106", + "resolved": "https://registry.npmjs.org/utopia-ui/-/utopia-ui-3.0.106.tgz", + "integrity": "sha512-O7G+iS0VBa9bOghzYCZnpRjyhrExCw0bloI97ch8MxDsiGoC0qPlvemp1GeO4HHfR1gJrTcVHWiUJMbEqaFqXQ==", "license": "GPL-3.0-only", "dependencies": { "@heroicons/react": "^2.0.17", diff --git a/frontend/package.json b/frontend/package.json index 280f172d..da8c7bd6 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -20,7 +20,7 @@ "react-dom": "^18.2.0", "react-rnd": "^10.4.1", "react-router-dom": "^6.23.0", - "utopia-ui": "^3.0.105" + "utopia-ui": "^3.0.106" }, "devDependencies": { "@eslint-community/eslint-plugin-eslint-comments": "^4.4.1", diff --git a/lib/Components.svg b/lib/Components.svg index f617789f..81c41f9c 100644 --- a/lib/Components.svg +++ b/lib/Components.svg @@ -1,3 +1,645 @@ - - -
AppShell
AppShell
Content
Content
MapContainer
MapContainer
Tags
Tags
Permissions
Permissions
Layer
Layer
Layer
Layer
Layer
Layer
Sidebar
Sidebar
Settings
Settings
Profile
Profile
another Page
another Page
NavBar
NavBar
ViewPopup
ViewPopup
FormPopup
FormPopupText is not SVG - cannot display \ No newline at end of file + + + + + + + + + + + + AppShell + + + + AppShell + + + + + + + + + Content + + + + Content + + + + + + + + + MapContainer + + + + MapContainer + + + + + + + + + Tags + + + + Tags + + + + + + + + + Permissions + + + + Permissions + + + + + + + + + Layer + + + + Layer + + + + + + + + + Layer + + + + Layer + + + + + + + + + Layer + + + + Layer + + + + + + + + + Sidebar + + + + Sidebar + + + + + + + + + Settings + + + + Settings + + + + + + + + + Profile + + + + Profile + + + + + + + + + another Page + + + + another Page + + + + + + + + + NavBar + + + + NavBar + + + + + + + + + ViewPopup + + + + ViewPopup + + + + + + + + + FormPopup + + + + FormPopup + + + + + + + Text is not SVG - cannot display + + + diff --git a/lib/README.md b/lib/README.md index 0d88014b..8d2cfc49 100644 --- a/lib/README.md +++ b/lib/README.md @@ -1,76 +1,327 @@ # Utopia UI [![npm version](https://img.shields.io/npm/v/utopia-ui.svg)](https://www.npmjs.com/package/utopia-ui) ![Build Status](https://img.shields.io/github/actions/workflow/status/utopia-os/utopia-ui/test.build.yml?branch=main) ![Test Coverage](https://utopia-os.org/utopia-map/test-coverage.svg) [![Docs Coverage](https://utopia-os.org/utopia-map/coverage.svg)](https://utopia-os.org/utopia-map/utopia-ui/coverage.svg) ![License](https://img.shields.io/github/license/utopia-os/utopia-ui) -**UI Framework for Real-Life-Networking-Apps** +**Reusable React Components for Building Mapping Apps for Real Life Communities** *Real change happens in real life when we meet in person and connect as local communities manifesting their ideas with the earth. When we help each other to step out of our bubbles at home and start building common infrastructure to meet human needs in harmony with Mother Earth.* -*That is why Utopia UI exists. It is a UI kit for minimalist, fast, intuitive and mobile-first map apps, as a tool for local connection and decentralised networking. We believe in maps as the perfect link between digital tools and real life action* +*That is why Utopia UI exists. It is a comprehensive React component library for minimalist, fast, intuitive and mobile-first map applications, as a tool for local connection and decentralized networking. We believe in maps as the perfect link between digital tools and real life action.* *It can work with any backend or p2p database and any kind of data structure.* -## Mission -Utopia UIs mission is to provide open source building blocks to create beautiful applications with a focus on real life impact, local communities and gamification. +## 🎯 Mission + +Utopia UI's mission is to provide open source building blocks to create beautiful applications with a focus on real life impact, local communities and gamification. The building blocks are designed to allow different networks and communities to assemble their map and app for their specific needs and purpose. -It is the base of [Utopia Map](https://github.com/utopia-os/utopia-map) and [Utopia Game](https://github.com/utopia-os/utopia-game). +It is the base of [Utopia Map](https://github.com/utopia-os/utopia-map). + +## ✨ Features + +### Core Features +- **Interactive Map**: Leaflet-based mapping with customizable layers (Projects, Events, People, etc.) +- **Flexible API Interface**: Works with any backend or p2p database +- **CRUD Operations**: Create, update, delete items with full form validation +- **Authentication System**: Complete user authentication API interface +- **Profile Management**: Customizable profiles with multiple templates +- **App Shell**: Responsive navigation with sidebar and top bar + +### Advanced Features +- **Permission System**: Role-based access control +- **Gaming Elements**: Quest system for user engagement +- **Rich Text Editing**: TipTap-based markdown editor +- **Image Management**: Upload, crop, and compress images +- **Tag System**: Flexible categorization and filtering +- **Responsive Design**: Mobile-first approach with PWA support + +## 📦 Installation + +Inside your **React** project run: -## Features +```bash +npm install utopia-ui +``` -* Interactive Component Map with customizable Layers (like Projects, Event, People) -* Flexible API-Interface to make it work with every backend or p2p database -* Create, Update, Delete Items -* User authentification API-Interface -* Customizable Profiles for users and other items -* App shell with navigation bar and sidebar -## Getting Started +## 🚀 Getting Started -1. If you want to use **Utopia UI** in your project, check out [`/examples`](/examples) to see how to use its components. +### Quick Start -2. If you need more information you can explore [the docs](https://utopia-os.org/utopia-ui/) +```typescript +import { UtopiaMap, AppShell, AuthProvider } from 'utopia-ui' -3. If you like to contribute to our library, see the [Contribution Guide](/CONTRIBUTING.md) to see how to setup a development environment on your local machine. +function App() { + return ( + + + + + + + + + ) +} -## Components +``` + +### Step-by-Step Guide + +1. **Explore Examples**: Check out [`/examples`](/examples) to see complete implementations +2. **Read Documentation**: Visit [the docs](https://utopia-os.org/utopia-ui/) for detailed API reference +3. **Join Community**: Connect with us on [Telegram](https://t.me/UtopiaMap) +4. **Contribute**: See the [Contribution Guide](/CONTRIBUTING.md) for development setup + +## 🧩 Components ![Utopia UI Components](Components.svg) -## Map Component -The map shows various Layers (like places, events, profiles ...) of Items at their respective position whith nice and informative Popup and Profiles. +### Core Components + +#### Map Components +- **`UtopiaMap`** - Main interactive map component +- **`Layer`** - Individual map layers with custom styling +- **`Tags`** - Tag management and filtering system +- **`Permissions`** - Access control wrapper + +#### App Structure +- **`AppShell`** - Main application layout +- **`SideBar`** - Navigation sidebar +- **`Content`** - Main content area +- **`NavBar`** - Top navigation bar + +#### Authentication +- **`AuthProvider`** - Authentication context +- **`LoginPage`** - User login form +- **`SignupPage`** - User registration form +- **`RequestPasswordPage`** - Password reset request +- **`SetNewPasswordPage`** - Password reset form + +#### Profile System +- **`ProfileView`** - Display item profiles +- **`ProfileForm`** - Edit item profiles +- **`UserSettings`** - User account settings + +#### Gaming +- **`Quests`** - Quest system component +- **`Modal`** - Gaming modal dialogs + +#### Form Components +- **`TextInput`** - Text input with validation +- **`TextAreaInput`** - Multi-line text input +- **`ComboBoxInput`** - Dropdown with search +- **`RichTextEditor`** - Markdown editor +- **`Autocomplete`** - Auto-completing input + +#### Templates +- **`DialogModal`** - Modal dialog wrapper +- **`CardPage`** - Card-based page layout +- **`ItemCard`** - Item display card +- **`Tabs`** - Tab navigation +- **`LoadingMapOverlay`** - Loading states + +## 📚 Examples + +The library includes three complete example implementations: + +### 1. Basic Map (`/examples/1-basic-map`) +A minimal implementation showing how to set up a basic interactive map. + +```bash +cd examples/1-basic-map +npm install +npm run dev +``` + +### 2. Static Layers (`/examples/2-static-layers`) +Demonstrates how to create predefined layers with custom icons and styling. + +```bash +cd examples/2-static-layers +npm install +npm run dev +``` + +### 3. Tags (`/examples/3-tags`) +Shows the implementation of a tagging system for categorizing and filtering items. -Tags, colors and clusters help to retain the overview. +```bash +cd examples/3-tags +npm install +npm run dev +``` +## 📖 API Reference -### Map Options +### UtopiaMap Component - Option | Type | Default | Required | Description - --- | --- | --- | --- | --- - `height` | `string` |`'400px'` | No | height of the map - `width` | `string` |`'100vw'` | No | width of the map - `center` | `LatLng` |`[50.6, 9.5]` | No | initial map position - `zoom` | `number` |`10` | No | initial zoom level +The main map component that displays items across different layers. -### Layer Options +#### Props - Option | Type | Default | Required | Description - --- | --- | --- | --- | --- -| ... | | | | +| Prop | Type | Default | Required | Description | +|------|------|---------|----------|-------------| +| `height` | `string` | - | No | Height of the map container | +| `width` | `string` | - | No | Width of the map container | +| `center` | `[number, number]` | - | No | Initial map center position | +| `zoom` | `number` | - | No | Initial zoom level | +| `tags` | `Tag[]` | - | No | Array of tags to display | +| `geo` | `GeoJsonObject` | - | No | GeoJSON object for map data | +| `showFilterControl` | `boolean` | `false` | No | Show filter control | +| `showLayerControl` | `boolean` | `false` | No | Show layer control | +| `showGratitudeControl` | `boolean` | `false` | No | Show gratitude control | +| `showThemeControl` | `boolean` | `false` | No | Show theme control | +| `showZoomControl` | `boolean` | `false` | No | Show zoom control | +| `infoText` | `string` | - | No | Additional information text | +| `donationWidget` | `boolean` | `false` | No | Show donation widget | +| `defaultTheme` | `string` | - | No | Default theme for the map | +| `expandLayerControl` | `boolean` | `false` | No | Expand layer control by default | -## Join the community +#### Layer Props + +| Property | Type | Default | Required | Description | +|----------|------|---------|----------|-------------| +| `name` | `string` | `'places'` | No | Layer name | +| `menuIcon` | `string` | `'MapPinIcon'` | No | Menu icon | +| `menuText` | `string` | `'add new place'` | No | Menu text | +| `menuColor` | `string` | `'#2E7D32'` | No | Menu color | +| `markerIcon` | `object` | - | No | Custom marker icon configuration | +| `markerShape` | `'circle'` \| `'square'` | `'circle'` | No | Shape of the marker | +| `markerDefaultColor` | `string` | `'#777'` | No | Default marker color | +| `markerDefaultColor2` | `string` | `'RGBA(35, 31, 32, 0.2)'` | No | Secondary marker color | +| `api` | `ItemsApi` | - | No | API for layer items | +| `itemType` | `string` | - | No | Type of items in the layer | +| `userProfileLayer` | `boolean` | `false` | No | Is this a user profile layer | +| `customEditLink` | `string` | - | No | Custom edit link | +| `customEditParameter` | `string` | - | No | Custom edit parameter | +| `public_edit_items` | `boolean` | - | No | Allow public item editing | +| `listed` | `boolean` | `true` | No | Show layer in layer list | + +### API Interfaces + +#### ItemsApi Interface +```typescript +interface ItemsApi { + getItems(filter?: Filter): Promise + getItem(id: string): Promise + createItem(item: Partial): Promise + updateItem(id: string, item: Partial): Promise + deleteItem(id: string): Promise +} +``` + +#### UserApi Interface +```typescript +interface UserApi { + login(email: string, password: string): Promise + logout(): Promise + getCurrentUser(): Promise + register(userData: RegisterData): Promise + requestPasswordReset(email: string): Promise + resetPassword(token: string, password: string): Promise +} +``` + +## 🤝 Contributing + +We welcome contributions! This library is in active development and we're looking for: + +- **Web Developers** - React/TypeScript expertise +- **UX Designers** - Mobile-first design patterns +- **Community Managers** - Documentation and community building +- **Visionaries** - Product direction and strategy +- **Artists** - Icons, illustrations, and visual design + +### How to Contribute + +1. **Fork the repository** +2. **Create a feature branch**: `git checkout -b feature/amazing-feature` +3. **Make your changes** and add tests +4. **Run the test suite**: `npm run test:unit && npm run test:component` +5. **Commit your changes**: `git commit -m 'Add amazing feature'` +6. **Push to the branch**: `git push origin feature/amazing-feature` +7. **Open a Pull Request** + +### Development Guidelines + +- Follow the existing code style (ESLint + Prettier) +- Write tests for new components +- Update documentation for API changes +- Use conventional commit messages +- Ensure accessibility compliance + +See our [Contribution Guide](/CONTRIBUTING.md) for detailed setup instructions. + +## 🌍 Community *This Library is in alpha stage. You are very welcome to participate in the development* -*We are looking for Web Developer, UX Designer, Community Manager, Visionaries, Artists, etc. who like to support this Vision.* +Join our community and help shape the future of real-life networking apps: + +- **Telegram**: [https://t.me/UtopiaMap](https://t.me/UtopiaMap) +- **GitHub Discussions**: Share ideas and ask questions +- **OpenCollective**: Support the project financially -[https://t.me/UtopiaMap](https://t.me/UtopiaMap) +## 💚 Support -## Support us +We are building Utopia UI as a free and open-source tool. To keep this project sustainable and accessible, we need your support: + +### Financial Support +### Other Ways to Support + +- ⭐ Star the repository +- 🐛 Report bugs and issues +- 📝 Improve documentation +- 🔗 Share the project with others +- 💡 Contribute ideas and feedback + +## 📄 License + +This project is licensed under GPL-3.0-only. See the [LICENSE](LICENSE) file for details. + +## 🙏 Acknowledgments + +- **BrowserStack** - Cross-browser testing platform +- **OpenCollective** - Transparent funding platform +- **All Contributors** - Everyone who has contributed to this project + --- +*Built with ❤️ for real-life communities around the world* + This project is tested with BrowserStack