@hotosm/hanko-auth 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +210 -0
  2. package/dist/hanko-auth.esm.js +4990 -0
  3. package/package.json +56 -0
  4. package/src/hanko-auth.ts +1690 -0
package/README.md ADDED
@@ -0,0 +1,210 @@
1
+ # @hotosm/hanko-auth
2
+
3
+ Header authentication widget for HOTOSM applications. Displays login/logout state and user profile dropdown.
4
+
5
+ **Note:** This package provides only the header widget. The actual login form and profile pages are hosted at the [HOTOSM Login service](https://login.hotosm.org). Users will be redirected there for authentication.
6
+
7
+ ## Installation
8
+
9
+ Install the package and its peer dependency:
10
+
11
+ ```bash
12
+ # npm
13
+ npm install @hotosm/hanko-auth @awesome.me/webawesome
14
+
15
+ # yarn
16
+ yarn add @hotosm/hanko-auth @awesome.me/webawesome
17
+
18
+ # pnpm
19
+ pnpm add @hotosm/hanko-auth @awesome.me/webawesome
20
+ ```
21
+
22
+ ## Usage
23
+
24
+ ### Basic Setup
25
+
26
+ ```javascript
27
+ import '@awesome.me/webawesome';
28
+ import '@hotosm/hanko-auth';
29
+ ```
30
+
31
+ ### React/Preact
32
+
33
+ ```jsx
34
+ import '@awesome.me/webawesome';
35
+ import '@hotosm/hanko-auth';
36
+
37
+ function Header() {
38
+ return (
39
+ <nav>
40
+ <hotosm-auth hanko-url="https://login.hotosm.org" />
41
+ </nav>
42
+ );
43
+ }
44
+ ```
45
+
46
+ ### HTML
47
+
48
+ ```html
49
+ <!DOCTYPE html>
50
+ <html>
51
+ <head>
52
+ <meta name="hanko-url" content="https://login.hotosm.org">
53
+ </head>
54
+ <body>
55
+ <script type="module">
56
+ import '@awesome.me/webawesome';
57
+ import '@hotosm/hanko-auth';
58
+ </script>
59
+
60
+ <!-- Header auth widget -->
61
+ <nav>
62
+ <hotosm-auth></hotosm-auth>
63
+ </nav>
64
+ </body>
65
+ </html>
66
+ ```
67
+
68
+ ## Component API
69
+
70
+ ### Attributes/Properties
71
+
72
+ | Attribute | Type | Default | Description |
73
+ |-----------|------|---------|-------------|
74
+ | `hanko-url` | `string` | `window.location.origin` | Hanko API URL (e.g., `https://login.hotosm.org`) |
75
+ | `redirect-after-login` | `string` | Current page | Redirect URL after successful login |
76
+ | `redirect-after-logout` | `string` | `""` | Redirect URL after logout |
77
+ | `display-name` | `string` | `""` | Override user display name |
78
+ | `osm-required` | `boolean` | `false` | Show OSM connection requirement indicator |
79
+ | `base-path` | `string` | `""` | Base path for API calls |
80
+ | `auth-path` | `string` | `"/api/auth/osm"` | OSM connection check endpoint |
81
+
82
+ ### Events
83
+
84
+ The component dispatches custom events:
85
+
86
+ ```javascript
87
+ document.addEventListener('hanko-login', (event) => {
88
+ console.log('User logged in:', event.detail.user);
89
+ });
90
+
91
+ document.addEventListener('hanko-logout', () => {
92
+ console.log('User logged out');
93
+ });
94
+
95
+ document.addEventListener('osm-connected', (event) => {
96
+ console.log('OSM connected:', event.detail.osmData);
97
+ });
98
+ ```
99
+
100
+ ## Examples
101
+
102
+ ### Basic Header Widget
103
+
104
+ ```html
105
+ <hotosm-auth
106
+ hanko-url="https://login.hotosm.org"
107
+ ></hotosm-auth>
108
+ ```
109
+
110
+ ### With Return URL
111
+
112
+ Redirect users back to a specific page after login:
113
+
114
+ ```html
115
+ <hotosm-auth
116
+ hanko-url="https://login.hotosm.org"
117
+ redirect-after-login="/dashboard"
118
+ ></hotosm-auth>
119
+ ```
120
+
121
+ ### Check OSM Connection Status
122
+
123
+ Show indicator if OSM connection is required:
124
+
125
+ ```html
126
+ <hotosm-auth
127
+ hanko-url="https://login.hotosm.org"
128
+ osm-required
129
+ auth-path="/api/auth/osm"
130
+ ></hotosm-auth>
131
+ ```
132
+
133
+ ### Custom Display Name
134
+
135
+ Override the displayed user name:
136
+
137
+ ```html
138
+ <hotosm-auth
139
+ hanko-url="https://login.hotosm.org"
140
+ display-name="Custom Name"
141
+ ></hotosm-auth>
142
+ ```
143
+
144
+ ## Styling
145
+
146
+ The component uses the HOT design system with CSS custom properties injected from CDN:
147
+
148
+ - `hotosm-ui-design/dist/hot.css` - Color, typography, spacing variables
149
+ - `hotosm-ui-design/dist/hot-font-face.css` - Font definitions
150
+ - `hotosm-ui-design/dist/hot-wa.css` - WebAwesome theme overrides
151
+
152
+ You can override styles by setting CSS custom properties:
153
+
154
+ ```css
155
+ hotosm-auth {
156
+ --hot-color-gray-800: #1a1a1a;
157
+ --hot-font-sans: 'Your Font', sans-serif;
158
+ }
159
+ ```
160
+
161
+ ## Features
162
+
163
+ - πŸ” **Authentication State** - Shows login/logout status and user info
164
+ - πŸ‘€ **Profile Dropdown** - Quick access to profile and logout
165
+ - πŸ—ΊοΈ **OSM Status Indicator** - Shows OpenStreetMap connection status
166
+ - 🎨 **HOT Design System** - Consistent styling with HOT branding
167
+ - πŸ“± **Responsive** - Works on desktop and mobile
168
+ - ⚑ **Lightweight** - Built with Lit web components
169
+ - πŸ”„ **Cross-App Sessions** - Shared authentication across HOT tools
170
+ - 🎯 **Framework Agnostic** - Works with React, Vue, vanilla JS, etc.
171
+
172
+ ## How It Works
173
+
174
+ 1. **Logged Out**: Displays a "Log in" button
175
+ 2. **Click Login**: Redirects to `https://login.hotosm.org` for authentication
176
+ 3. **After Login**: User returns to your app (or `redirect-after-login` URL)
177
+ 4. **Logged In**: Shows user avatar with dropdown menu:
178
+ - My Profile (redirects to login service)
179
+ - OSM connection status
180
+ - Sign Out
181
+
182
+ ## Browser Support
183
+
184
+ - Chrome/Edge (latest)
185
+ - Firefox (latest)
186
+ - Safari (latest)
187
+
188
+ ## Development
189
+
190
+ ```bash
191
+ # Install dependencies
192
+ pnpm install
193
+
194
+ # Build
195
+ pnpm build
196
+
197
+ # Development with hot reload
198
+ pnpm dev
199
+ ```
200
+
201
+ ## License
202
+
203
+ AGPL-3.0
204
+
205
+ ## Links
206
+
207
+ - [Documentation](https://hotosm.github.io/auth-docs)
208
+ - [GitHub Repository](https://github.com/hotosm/login)
209
+ - [Issues](https://github.com/hotosm/login/issues)
210
+ - [HOTOSM Website](https://www.hotosm.org)