feat: Update Gradle wrapper to version 8.13
feat: Add JitPack repository to dependency resolution management feat: Create ViewStyle enum for bookmark display styles feat: Implement EditLinkScreen with ViewModel for editing links feat: Add EditLinkViewModel to manage link editing state and logic feat: Create LinkItemViews for displaying links in various formats chore: Add build output and compile output logs
This commit is contained in:
@@ -1,114 +1,365 @@
|
||||
# ShaarIt
|
||||
|
||||
**ShaarIt** is a native Android client for [Shaarli](https://github.com/shaarli/Shaarli), the self-hosted bookmark manager. Built with modern Android technologies, it provides a seamless mobile experience for managing your links.
|
||||
**ShaarIt** est un client Android natif pour [Shaarli](https://github.com/shaarli/Shaarli), le gestionnaire de favoris auto-hébergé. Développé avec les technologies Android modernes, il offre une expérience mobile fluide pour gérer vos liens.
|
||||
|
||||
## Features
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
* **Authentication**: Secure login to your self-hosted Shaarli instance (API v1).
|
||||
* **Feed**: Infinite scroll browsing of your bookmarks with infinite loading.
|
||||
* **Search & Filter**: Server-side search by terms and tag filtering.
|
||||
* **Management**: Add new private/public links and delete existing ones.
|
||||
* **Share Intent**: Quick-save links from other apps (browser, YouTube, etc.) via the Android Share menu.
|
||||
---
|
||||
|
||||
## Tech Stack
|
||||
## 📱 Fonctionnalités
|
||||
|
||||
* **Language**: Kotlin
|
||||
* **UI**: Jetpack Compose (Material Design 3)
|
||||
* **Architecture**: Clean Architecture + MVVM
|
||||
* **Dependency Injection**: Dagger Hilt
|
||||
* **Network**: Retrofit + Moshi + OkHttp
|
||||
* **Concurrency**: Coroutines & Flow
|
||||
* **Pagination**: Paging 3
|
||||
### 🔐 Authentification
|
||||
- Connexion sécurisée à votre instance Shaarli auto-hébergée (API v1)
|
||||
- Stockage chiffré des tokens JWT et secrets API via `EncryptedSharedPreferences`
|
||||
- Génération automatique de tokens JWT avec algorithme HS512
|
||||
|
||||
## Prerequisites
|
||||
### 📚 Gestion des Favoris
|
||||
- **Flux infini** : Défilement continu avec chargement progressif (Paging 3)
|
||||
- **Recherche côté serveur** : Recherche par termes et filtrage par tags
|
||||
- **Ajout rapide** : Création de liens privés/publics avec description et tags
|
||||
- **Édition** : Modification complète des liens existants
|
||||
- **Suppression** : Gestion facile des favoris
|
||||
- **Détection des doublons** : Alerte lors de l'ajout d'un lien existant avec option de mise à jour
|
||||
|
||||
Before building via the command line, ensure you have:
|
||||
### 🏷️ Gestion des Tags
|
||||
- Vue dédiée pour parcourir tous les tags
|
||||
- Compteur d'utilisation par tag
|
||||
- Filtrage rapide du flux par tag
|
||||
|
||||
1. **JDK 17** (or newer) installed.
|
||||
2. **Android SDK** installed.
|
||||
3. **Gradle** (v8.0+) installed (only required if `gradlew` is missing).
|
||||
* *Note for Windows users with Scoop:* `scoop install gradle`
|
||||
### 🔗 Intégration système
|
||||
- **Share Intent Android** : Sauvegarde rapide depuis n'importe quelle app (navigateur, YouTube, etc.) via le menu Partager
|
||||
- Ouverture des liens dans le navigateur par défaut
|
||||
- Support des URLs partagées avec titre pré-rempli
|
||||
|
||||
## First Time Setup (If gradlew is missing)
|
||||
### 🎨 Interface Utilisateur
|
||||
- **Design premium** : Thème sombre moderne avec dégradés cyan/bleu
|
||||
- **Material Design 3** : Composants UI natifs Android
|
||||
- **Animations fluides** : Transitions et effets visuels
|
||||
- **Deux modes d'affichage** : Liste détaillée ou grille compacte
|
||||
- **Pull-to-refresh** : Actualisation du flux par glissement
|
||||
|
||||
If the `./gradlew` file is missing (e.g. fresh project generation), you need to generate it using a local Gradle installation:
|
||||
---
|
||||
|
||||
## 🛠️ Stack Technique
|
||||
|
||||
| Catégorie | Technologie |
|
||||
|-----------|-------------|
|
||||
| **Langage** | Kotlin 1.9.20 |
|
||||
| **UI** | Jetpack Compose + Material Design 3 |
|
||||
| **Architecture** | Clean Architecture + MVVM |
|
||||
| **Injection de dépendances** | Dagger Hilt 2.48.1 |
|
||||
| **Réseau** | Retrofit 2.9.0 + Moshi 1.15.0 + OkHttp 4.12.0 |
|
||||
| **Pagination** | Paging 3 |
|
||||
| **Concurrence** | Coroutines & Flow |
|
||||
| **Stockage sécurisé** | AndroidX Security Crypto |
|
||||
| **Navigation** | Navigation Compose |
|
||||
| **Compilation** | Gradle 8.0+ avec KSP |
|
||||
|
||||
### Compatibilité
|
||||
- **minSdk**: 24 (Android 7.0)
|
||||
- **targetSdk**: 34 (Android 14)
|
||||
- **compileSdk**: 34
|
||||
- **JDK requis**: 17+
|
||||
|
||||
---
|
||||
|
||||
## 📥 Installation
|
||||
|
||||
### Prérequis utilisateur
|
||||
- Un serveur Shaarli auto-hébergé (v0.12+) avec l'API v1 activée
|
||||
- Un appareil Android 7.0+ ou un émulateur
|
||||
|
||||
### Obtenir l'APK
|
||||
|
||||
#### Méthode 1 : Téléchargement direct
|
||||
Récupérez le dernier APK depuis la section [Releases](../../releases).
|
||||
|
||||
#### Méthode 2 : Compilation depuis les sources
|
||||
|
||||
##### Prérequis de développement
|
||||
1. **JDK 17** (ou plus récent) installé
|
||||
2. **Android SDK** installé (Platform API 34)
|
||||
3. **Gradle** 8.0+ (si `gradlew` est manquant)
|
||||
|
||||
##### Étapes de compilation
|
||||
|
||||
1. **Cloner le repository**
|
||||
```bash
|
||||
git clone https://github.com/votre-username/ShaarIt.git
|
||||
cd ShaarIt
|
||||
```
|
||||
|
||||
2. **Configurer l'emplacement du SDK Android**
|
||||
|
||||
Si la variable `ANDROID_HOME` n'est pas définie, créez un fichier `local.properties` :
|
||||
```bash
|
||||
# Windows
|
||||
echo sdk.dir=C:\Users\<Username>\AppData\Local\Android\Sdk > local.properties
|
||||
|
||||
# Linux/macOS
|
||||
echo sdk.dir=/home/<username>/Android/Sdk > local.properties
|
||||
```
|
||||
|
||||
3. **Compiler l'APK Debug**
|
||||
```bash
|
||||
# Windows
|
||||
./gradlew assembleDebug
|
||||
|
||||
# Linux/macOS
|
||||
chmod +x gradlew
|
||||
./gradlew assembleDebug
|
||||
```
|
||||
|
||||
4. **L'APK se trouve dans** : `app/build/outputs/apk/debug/app-debug.apk`
|
||||
|
||||
5. **Installer sur l'appareil**
|
||||
```bash
|
||||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||||
```
|
||||
|
||||
### Configuration initiale de l'app
|
||||
|
||||
1. Ouvrez l'application **ShaarIt**
|
||||
2. Entrez l'**URL de votre instance Shaarli** (ex: `https://monserveur.com/shaarli`)
|
||||
3. Entrez votre **Secret API** (trouvé dans les paramètres admin de Shaarli)
|
||||
4. Cliquez sur **Connecter**
|
||||
|
||||
---
|
||||
|
||||
## 🧑💻 Section Développement
|
||||
|
||||
### Architecture du projet
|
||||
|
||||
```bash
|
||||
gradle wrapper
|
||||
```
|
||||
|
||||
This will create `gradlew`, `gradlew.bat` and the `gradle/wrapper` folder.
|
||||
|
||||
## Environment Setup (SDK)
|
||||
|
||||
Ensure you have the required Android SDK components installed (Platform API 34).
|
||||
If you see a silent failure or "missing target" error, run:
|
||||
|
||||
```powershell
|
||||
# Adjust path to your sdkmanager if needed
|
||||
$SDK_MANAGER = "$env:ANDROID_HOME\cmdline-tools\latest\bin\sdkmanager"
|
||||
& $SDK_MANAGER "platforms;android-34" "build-tools;34.0.0"
|
||||
app/src/main/java/com/shaarit/
|
||||
├── core/ # Infrastructure et utilitaires
|
||||
│ ├── di/ # Modules Dagger Hilt (injection de dépendances)
|
||||
│ │ ├── AppModule.kt # Fournisseurs d'applications
|
||||
│ │ ├── NetworkModule.kt # Configuration Retrofit/OkHttp
|
||||
│ │ └── RepositoryModule.kt # Liaisons repository
|
||||
│ ├── network/ # Intercepteurs réseau
|
||||
│ │ ├── AuthInterceptor.kt # Injection automatique du token JWT
|
||||
│ │ └── HostSelectionInterceptor.kt # Changement dynamique d'hôte
|
||||
│ ├── storage/ # Stockage local sécurisé
|
||||
│ │ └── TokenManager.kt # Gestion chiffrée des tokens
|
||||
│ └── util/ # Utilitaires
|
||||
│ └── JwtGenerator.kt # Générateur JWT HS512
|
||||
├── data/ # Couche de données (Clean Architecture)
|
||||
│ ├── api/ # Interface Retrofit
|
||||
│ │ └── ShaarliApi.kt # Endpoints API v1
|
||||
│ ├── dto/ # Data Transfer Objects (Moshi)
|
||||
│ │ ├── Dtos.kt # Login, Link, Info DTOs
|
||||
│ │ └── TagDto.kt # Tag DTO
|
||||
│ ├── mapper/ # Convertisseurs DTO ↔ Domain
|
||||
│ │ └── LinkMapper.kt
|
||||
│ ├── paging/ # Sources de pagination
|
||||
│ │ └── LinkPagingSource.kt # Paging 3 pour le flux
|
||||
│ └── repository/ # Implémentations des repositories
|
||||
│ ├── AuthRepositoryImpl.kt
|
||||
│ └── LinkRepositoryImpl.kt
|
||||
├── domain/ # Couche métier (indépendante des frameworks)
|
||||
│ ├── model/ # Modèles de domaine
|
||||
│ │ ├── Models.kt # Credentials, ShaarliLink
|
||||
│ │ ├── ShaarliTag.kt
|
||||
│ │ └── ViewStyle.kt # Enum modes d'affichage
|
||||
│ ├── repository/ # Interfaces de repository
|
||||
│ │ ├── AuthRepository.kt
|
||||
│ │ └── LinkRepository.kt
|
||||
│ └── usecase/ # Cas d'utilisation
|
||||
│ └── LoginUseCase.kt
|
||||
├── presentation/ # Couche présentation (UI)
|
||||
│ ├── auth/ # Écran de connexion
|
||||
│ │ ├── LoginScreen.kt
|
||||
│ │ └── LoginViewModel.kt
|
||||
│ ├── feed/ # Flux principal
|
||||
│ │ ├── FeedScreen.kt
|
||||
│ │ ├── FeedViewModel.kt
|
||||
│ │ └── LinkItemViews.kt # Composants de carte de lien
|
||||
│ ├── add/ # Ajout de lien
|
||||
│ │ ├── AddLinkScreen.kt
|
||||
│ │ └── AddLinkViewModel.kt
|
||||
│ ├── edit/ # Édition de lien
|
||||
│ │ ├── EditLinkScreen.kt
|
||||
│ │ └── EditLinkViewModel.kt
|
||||
│ ├── tags/ # Gestion des tags
|
||||
│ │ ├── TagsScreen.kt
|
||||
│ │ └── TagsViewModel.kt
|
||||
│ └── nav/ # Navigation Compose
|
||||
│ └── NavGraph.kt # Routes et navigation
|
||||
├── ui/ # Composants UI réutilisables
|
||||
│ ├── components/ # Composants custom premium
|
||||
│ │ └── PremiumComponents.kt # GlassCard, GradientButton, etc.
|
||||
│ └── theme/ # Thème Material Design 3
|
||||
│ ├── Theme.kt # Couleurs et thème sombre
|
||||
│ └── Type.kt # Typographie
|
||||
├── MainActivity.kt # Point d'entrée avec gestion Share Intent
|
||||
└── ShaarItApp.kt # Application Hilt
|
||||
```
|
||||
|
||||
## Compilation Instructions (Command Line)
|
||||
### Flux d'authentification JWT
|
||||
|
||||
You can build the project without opening Android Studio by using the Gradle Wrapper included in the project.
|
||||
|
||||
### 1. Configure SDK Location
|
||||
If your `ANDROID_HOME` environment variable is not set, create a `local.properties` file in the project root:
|
||||
|
||||
```bash
|
||||
# Windows
|
||||
echo sdk.dir=C:\\Users\\<Username>\\AppData\\Local\\Android\\Sdk > local.properties
|
||||
|
||||
# Linux/macOS
|
||||
echo sdk.dir=/home/<username>/Android/Sdk > local.properties
|
||||
```
|
||||
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
|
||||
│ Utilisateur │────▶│ LoginScreen │────▶│ LoginViewModel │
|
||||
└─────────────┘ └──────────────┘ └─────────────────┘
|
||||
│
|
||||
┌───────────────────────────────┘
|
||||
▼
|
||||
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
|
||||
│ TokenManager│◀────│AuthRepository│◀────│ LoginUseCase │
|
||||
└─────────────┘ └──────────────┘ └─────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ EncryptedSharedPreferences│ (AES256_GCM)
|
||||
└─────────────────────────┘
|
||||
```
|
||||
|
||||
### 2. Build the APK
|
||||
Le token JWT est généré localement avec l'algorithme **HS512** :
|
||||
- **Header** : `{"typ":"JWT","alg":"HS512"}`
|
||||
- **Payload** : `{"iat": <unix_timestamp>}`
|
||||
- **Signature** : HMAC-SHA512(base64url(header) + "." + base64url(payload), apiSecret)
|
||||
|
||||
Open your terminal in the project root folder.
|
||||
### Pagination avec Paging 3
|
||||
|
||||
**Windows (PowerShell/CMD):**
|
||||
```powershell
|
||||
./gradlew assembleDebug
|
||||
```
|
||||
|
||||
**Linux/macOS:**
|
||||
```bash
|
||||
chmod +x gradlew
|
||||
./gradlew assembleDebug
|
||||
┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ FeedScreen │────▶│ FeedViewModel │────▶│ LinkRepository │
|
||||
└─────────────┘ └─────────────────┘ └─────────────────┘
|
||||
│
|
||||
┌──────────────────────────────────┘
|
||||
▼
|
||||
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
|
||||
│ lazyPagingItems│◀──│ Pager │◀────│ LinkPagingSource│
|
||||
└─────────────┘ └──────────────┘ └─────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ ShaarliApi │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
*The build process may take a few minutes as it downloads dependencies.*
|
||||
|
||||
### 3. Locate the APK
|
||||
Once the build is successful, the APK file will be located at:
|
||||
`app/build/outputs/apk/debug/app-debug.apk`
|
||||
|
||||
## Installation
|
||||
|
||||
To install the app on a connected device or emulator via command line:
|
||||
|
||||
```bash
|
||||
# Ensure your device is connected and visible
|
||||
adb devices
|
||||
|
||||
# Install the Debug APK
|
||||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||||
### Configuration réseau dynamique
|
||||
|
||||
L'application utilise un pattern d'intercepteur pour gérer le changement d'URL serveur sans recréer le client Retrofit :
|
||||
|
||||
```kotlin
|
||||
// HostSelectionInterceptor permet de changer l'hôte à la volée
|
||||
class HostSelectionInterceptor : Interceptor {
|
||||
@Volatile private var host: HttpUrl? = null
|
||||
|
||||
fun setHost(url: String) {
|
||||
host = url.toHttpUrlOrNull()
|
||||
}
|
||||
|
||||
override fun intercept(chain: Interceptor.Chain): Response {
|
||||
val request = chain.request()
|
||||
val newUrl = host?.let {
|
||||
request.url.newBuilder()
|
||||
.scheme(it.scheme)
|
||||
.host(it.host)
|
||||
.port(it.port)
|
||||
.build()
|
||||
} ?: request.url
|
||||
|
||||
return chain.proceed(request.newBuilder().url(newUrl).build())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
|
||||
To run unit tests:
|
||||
### Exécution des tests
|
||||
|
||||
```bash
|
||||
# Tests unitaires
|
||||
./gradlew test
|
||||
|
||||
# Tests instrumentés
|
||||
./gradlew connectedAndroidTest
|
||||
```
|
||||
|
||||
## Usage
|
||||
### Build de release
|
||||
|
||||
1. Open the **ShaarIt** app.
|
||||
2. Enter your **Shaarli Instance URL** (e.g., `https://myserver.com/shaarli`).
|
||||
3. Enter your **API Secret** (found in your Shaarli admin settings).
|
||||
4. Click **Connect**.
|
||||
1. **Créer un keystore** (si premier build)
|
||||
```bash
|
||||
keytool -genkey -v -keystore shaarit.keystore -alias shaarit \
|
||||
-keyalg RSA -keysize 2048 -validity 10000
|
||||
```
|
||||
|
||||
2. **Créer `keystore.properties`** dans le répertoire racine :
|
||||
```properties
|
||||
storeFile=shaarit.keystore
|
||||
storePassword=votre_password
|
||||
keyAlias=shaarit
|
||||
keyPassword=votre_password
|
||||
```
|
||||
|
||||
3. **Compiler**
|
||||
```bash
|
||||
./gradlew assembleRelease
|
||||
```
|
||||
|
||||
4. **L'APK signé se trouve dans** : `app/build/outputs/apk/release/app-release.apk`
|
||||
|
||||
### Dépendances principales
|
||||
|
||||
```toml
|
||||
[versions]
|
||||
agp = "8.13.2"
|
||||
kotlin = "1.9.20"
|
||||
hilt = "2.48.1"
|
||||
retrofit = "2.9.0"
|
||||
moshi = "1.15.0"
|
||||
okhttp = "4.12.0"
|
||||
paging = "3.2.1"
|
||||
composeBom = "2023.08.00"
|
||||
|
||||
[libraries]
|
||||
# Injection de dépendances
|
||||
hilt-android = { module = "com.google.dagger:hilt-android", version.ref = "hilt" }
|
||||
hilt-compiler = { module = "com.google.dagger:hilt-android-compiler", version.ref = "hilt" }
|
||||
|
||||
# Réseau
|
||||
retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
|
||||
retrofit-moshi = { module = "com.squareup.retrofit2:converter-moshi", version.ref = "retrofit" }
|
||||
moshi = { module = "com.squareup.moshi:moshi", version.ref = "moshi" }
|
||||
moshi-codegen = { module = "com.squareup.moshi:moshi-kotlin-codegen", version.ref = "moshi" }
|
||||
okhttp-logging = { module = "com.squareup.okhttp3:logging-interceptor", version.ref = "okhttp" }
|
||||
|
||||
# Pagination
|
||||
androidx-paging-runtime = { module = "androidx.paging:paging-runtime", version.ref = "paging" }
|
||||
androidx-paging-compose = { module = "androidx.paging:paging-compose", version.ref = "paging" }
|
||||
|
||||
# Sécurité
|
||||
androidx-security-crypto = { module = "androidx.security:security-crypto", version = "1.1.0-alpha06" }
|
||||
```
|
||||
|
||||
### Contribution
|
||||
|
||||
1. Forker le projet
|
||||
2. Créer une branche feature (`git checkout -b feature/amazing-feature`)
|
||||
3. Committer vos changements (`git commit -m 'Add amazing feature'`)
|
||||
4. Pusher sur la branche (`git push origin feature/amazing-feature`)
|
||||
5. Ouvrir une Pull Request
|
||||
|
||||
---
|
||||
|
||||
## 📄 Licence
|
||||
|
||||
Ce projet est sous licence MIT. Voir le fichier [LICENSE](LICENSE) pour plus de détails.
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Remerciements
|
||||
|
||||
- [Shaarli](https://github.com/shaarli/Shaarli) - Le gestionnaire de favoris auto-hébergé
|
||||
- [Jetpack Compose](https://developer.android.com/jetpack/compose) - UI toolkit moderne Android
|
||||
- [Material Design 3](https://m3.material.io/) - Système de design Google
|
||||
|
||||
---
|
||||
|
||||
## 📧 Contact
|
||||
|
||||
Pour toute question ou suggestion, n'hésitez pas à ouvrir une [issue](../../issues).
|
||||
|
||||
Reference in New Issue
Block a user