From 7cbeb9ac72c425870131c5b3f5b2e48f27544b5b Mon Sep 17 00:00:00 2001 From: Anton Tranelis Date: Tue, 24 Jun 2025 09:29:45 +0200 Subject: [PATCH] library readme --- lib/Components.svg | 648 ++++++++++++++++++++++++++++++++++++++++++++- lib/README.md | 334 ++++++++++++++++++++--- 2 files changed, 944 insertions(+), 38 deletions(-) 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..94fbc553 100644 --- a/lib/README.md +++ b/lib/README.md @@ -1,76 +1,340 @@ # 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. +## 📋 Table of Contents + +- [Mission](#mission) +- [Features](#features) +- [Installation](#installation) +- [Getting Started](#getting-started) +- [Components](#components) +- [Examples](#examples) +- [API Reference](#api-reference) +- [Development](#development) +- [Contributing](#contributing) +- [Support](#support) + +## 🎯 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 +## ✨ Features -* 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 +### 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 -## Getting Started +### 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 -1. If you want to use **Utopia UI** in your project, check out [`/examples`](/examples) to see how to use its components. +## 📦 Installation -2. If you need more information you can explore [the docs](https://utopia-os.org/utopia-ui/) +Inside your **React** project run: -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. +```bash +npm install utopia-ui +``` -## Components + +## 🚀 Getting Started + +### Quick Start + +```typescript +import { UtopiaMap, AppShell, AuthProvider } from 'utopia-ui' + +function App() { + return ( + + + + + + + + + ) +} + +``` + +### 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 -Tags, colors and clusters help to retain the overview. +#### 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 -### Map Options +#### Authentication +- **`AuthProvider`** - Authentication context +- **`LoginPage`** - User login form +- **`SignupPage`** - User registration form +- **`RequestPasswordPage`** - Password reset request +- **`SetNewPasswordPage`** - Password reset form - 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 +#### Profile System +- **`ProfileView`** - Display item profiles +- **`ProfileForm`** - Edit item profiles +- **`UserSettings`** - User account settings -### Layer Options +#### Gaming +- **`Quests`** - Quest system component +- **`Modal`** - Gaming modal dialogs - Option | Type | Default | Required | Description - --- | --- | --- | --- | --- -| ... | | | | +#### Form Components +- **`TextInput`** - Text input with validation +- **`TextAreaInput`** - Multi-line text input +- **`ComboBoxInput`** - Dropdown with search +- **`RichTextEditor`** - Markdown editor +- **`Autocomplete`** - Auto-completing input -## Join the community +#### 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. + +```bash +cd examples/3-tags +npm install +npm run dev +``` + +## 📖 API Reference + +### UtopiaMap Component + +The main map component that displays items across different layers. + +#### Props + +| 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 | + +#### 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: -[https://t.me/UtopiaMap](https://t.me/UtopiaMap) +- **Telegram**: [https://t.me/UtopiaMap](https://t.me/UtopiaMap) +- **GitHub Discussions**: Share ideas and ask questions +- **OpenCollective**: Support the project financially -## Support us +## 💚 Support + +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