You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: expand README with comprehensive API usage, slots, and troubleshooting
Improve project entry point with structured API tables, configuration examples, and platform-specific troubleshooting guides to support developer onboarding.
GeoQibla is a Kotlin Multiplatform Compose library for showing Qibla direction in Android and iOS apps. It provides a ready-made shared screen, a headless controller for custom UI, and styling, string, and slot APIs for product-specific presentation.
7
+
<palign="center">
8
+
Kotlin Multiplatform Compose Qibla direction UI for Android and iOS apps.
GeoQibla gives Compose Multiplatform apps a ready-made Qibla compass screen, a headless controller for custom UI, and public styling, localization, and slot APIs for product-specific presentation.
6
20
7
21
Current version: `0.0.1`
8
22
9
-
## Install
23
+
## Features
10
24
11
-
Add the dependency in your KMP module's `commonMain` source set:
25
+
-**Compose-first**: Drop in `GeoQiblaScreen` for a complete adaptive Qibla flow.
26
+
-**Cross-platform**: Shared Kotlin API for Android and iOS.
27
+
-**Headless control**: Build custom screens from `QiblaController.state`.
28
+
-**Location and sensor state**: Permission, settings, calibration, tilt, heading accuracy, and error handling.
29
+
-**Configurable behavior**: Alignment thresholds, smoothing, update interval, magnetic limits, haptics, and `onAligned`.
30
+
-**Custom presentation**: `QiblaStyle`, `QiblaStrings`, and `QiblaSlots` for theming, RTL text, and region replacement.
31
+
-**Reusable components**: Public compass dial, status panel, and state message composables.
32
+
33
+
## Installation
34
+
35
+
Add the dependency to your KMP module's `commonMain` source set:
| iOS | App target supported by your KMP app |`CoreLocation`, heading updates, when-in-use location permission |
114
+
115
+
Compass behavior should be verified on physical devices. Emulators and simulators are useful for layout and permission-state checks, but not final heading accuracy.
41
116
42
-
-`GeoQiblaScreen`: ready-made adaptive screen with compass, status, messages, and action buttons.
43
-
-`rememberQiblaController`: creates a controller backed by Android or iOS platform services.
44
-
-`QiblaController.state`: `StateFlow<QiblaState>` for custom UIs.
45
-
-`QiblaConfig`: alignment thresholds, smoothing, location interval, tilt and magnetic limits, haptics, and `onAligned`.
46
-
-`QiblaStyle`, `QiblaStrings`, and `QiblaSlots`: styling, localization, RTL behavior, and region replacement.
47
-
-`QiblaCompassDial`, `QiblaStatusPanel`, and `QiblaStateMessage`: reusable public UI components.
117
+
## Configuration
118
+
119
+
Pass `QiblaConfig` to `rememberQiblaController()`:
120
+
121
+
```kotlin
122
+
val controller = rememberQiblaController(
123
+
config =QiblaConfig(
124
+
nearDegrees =10f,
125
+
alignedDegrees =3f,
126
+
stableAlignedDurationMillis =750L,
127
+
smoothingFactor =0.15f,
128
+
locationUpdateIntervalMillis =1_000L,
129
+
tiltLimitDegrees =55f,
130
+
magneticFieldMinMicrotesla =25f,
131
+
magneticFieldMaxMicrotesla =65f,
132
+
hapticsEnabled =true,
133
+
onAligned = {
134
+
// Called after stable alignment.
135
+
},
136
+
),
137
+
)
138
+
```
139
+
140
+
| Property | Default | Description |
141
+
| --- | --- | --- |
142
+
|`nearDegrees`|`10f`| Direction difference treated as near Qibla. |
143
+
|`alignedDegrees`|`3f`| Direction difference treated as aligned. |
144
+
|`stableAlignedDurationMillis`|`750L`| Delay before `onAligned` fires. |
145
+
|`smoothingFactor`|`0.15f`| Compass heading smoothing, from `0f` to `1f`. |
// Show a permission prompt and call controller.requestPermission().
175
+
}
176
+
else-> {
177
+
// Render compass from state.compass and state.location.
178
+
}
179
+
}
180
+
}
54
181
```
55
182
56
-
Use `state.uiState`, `state.compass`, and `state.location` to render your own flow while delegating platform location and heading behavior to GeoQibla.
183
+
The state model exposes:
57
184
58
-
## Platform Notes
185
+
-`state.uiState`: high-level UI state such as `LOCATING`, `READY`, `NEAR_QIBLA`, or `ALIGNED`.
186
+
-`state.compass`: Qibla bearing, current azimuth, direction delta, distance, tilt, magnetic field, and alignment flags.
187
+
-`state.location`: location access, current fix, location-service availability, and address label.
188
+
-`state.sensorAccuracy`: heading sensor quality.
189
+
-`state.orientationSource`: rotation vector, accelerometer/magnetometer, platform heading, or none.
190
+
-`state.errorMessage`: optional platform or controller error text.
59
191
60
-
Android apps should use minSdk 26 or newer. GeoQibla declares foreground location permissions in its Android library manifest, requests runtime location permission from the default UI, and uses Android framework location and sensor APIs.
192
+
## Styling and Slots
61
193
62
-
iOS apps should include location usage text in `Info.plist`:
194
+
Use `QiblaStyle`, `QiblaStrings`, and `QiblaSlots` to customize the default screen without replacing its behavior:
63
195
64
-
```xml
65
-
<key>NSLocationWhenInUseUsageDescription</key>
66
-
<string>GeoQibla uses your location to calculate the direction of the Qibla.</string>
196
+
```kotlin
197
+
importandroidx.compose.ui.graphics.Color
198
+
importcom.shahid.tech.qibla.GeoQiblaScreen
199
+
importcom.shahid.tech.qibla.QiblaColors
200
+
importcom.shahid.tech.qibla.QiblaSlots
201
+
importcom.shahid.tech.qibla.QiblaStrings
202
+
importcom.shahid.tech.qibla.QiblaStyle
203
+
204
+
GeoQiblaScreen(
205
+
controller = controller,
206
+
style =QiblaStyle.default().copy(
207
+
colors =QiblaColors(
208
+
primary =Color(0xFF096B58),
209
+
qibla =Color(0xFF0A7C66),
210
+
),
211
+
),
212
+
strings =QiblaStrings.arabic(),
213
+
slots =QiblaSlots(
214
+
topBar = { state ->
215
+
// Custom header.
216
+
},
217
+
actionButtons = { state ->
218
+
// Custom action row.
219
+
},
220
+
),
221
+
)
67
222
```
68
223
69
-
Compass behavior should be verified on physical devices. Emulators and simulators are useful for layout and permission-state checks, but not final heading accuracy.
224
+
## Public Components
70
225
71
-
## Documentation
226
+
The default screen is built from reusable public components:
227
+
228
+
| Component | Purpose |
229
+
| --- | --- |
230
+
|`GeoQiblaScreen`| Complete adaptive screen with lifecycle handling. |
231
+
|`QiblaCompassDial`| Compass dial and Qibla pointer. |
232
+
|`QiblaStatusPanel`| Bearing, distance, sensor, and location status rows. |
233
+
|`QiblaStateMessage`| State-specific message and supporting copy. |
234
+
235
+
## API Reference
236
+
237
+
### QiblaController
238
+
239
+
```kotlin
240
+
interfaceQiblaController {
241
+
val state:StateFlow<QiblaState>
242
+
243
+
funstart()
244
+
funstop()
245
+
funretryLocation()
246
+
funrequestPermission()
247
+
funopenLocationSettings()
248
+
funopenAppSettings()
249
+
fundismissCalibration()
250
+
}
251
+
```
252
+
253
+
### QiblaState
72
254
73
-
The full docs site is configured with MkDocs Material and published to GitHub Pages:
Test on a physical device, keep the device flat, and confirm location permission is granted. Emulators and simulators do not provide reliable final heading accuracy.
272
+
273
+
### Permission state is stuck
274
+
275
+
Call `controller.requestPermission()` from a user action. If the user permanently denies permission, call `controller.openAppSettings()`.
276
+
277
+
### Location is disabled
278
+
279
+
Use `controller.openLocationSettings()` from your UI. The default screen already shows the relevant action for this state.
280
+
281
+
### Calibration warning appears
282
+
283
+
Ask the user to move away from magnetic interference and follow the device calibration motion. You can provide a custom calibration region with `QiblaSlots.calibrationSheet`.
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local commands, documentation rules, and pull request expectations.
296
+
297
+
## Support
298
+
299
+
If GeoQibla helps your app, star the repository and open issues with platform details, device model, OS version, GeoQibla version, and reproduction steps.
300
+
80
301
## License
81
302
82
-
Apache 2.0.
303
+
```
304
+
Apache License 2.0
305
+
306
+
Copyright 2026 Shahid Iqbal
307
+
308
+
Licensed under the Apache License, Version 2.0 (the "License");
309
+
you may not use this file except in compliance with the License.
310
+
You may obtain a copy of the License at
311
+
312
+
https://www.apache.org/licenses/LICENSE-2.0
313
+
314
+
Unless required by applicable law or agreed to in writing, software
315
+
distributed under the License is distributed on an "AS IS" BASIS,
316
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
317
+
See the License for the specific language governing permissions and
0 commit comments