📝 Commitable

Mobile habit tracker with a GitHub-style contribution grid, daily reminders, external connector support, and a native Android home screen widget.

---

✨ Features

• Contribution grid — visualize your habits year-round exactly like GitHub's activity graph
• Custom colors — 8 color options per habit, reflected in the grid and widget
• Daily reminders — local push notifications with configurable hour and minute per habit
• External connectors — sync commits from any HTTP endpoint that returns the JSON contract
• Android widget — native home screen widget showing a 52-week grid for the selected habit
• Local persistence — all data stored on-device via AsyncStorage
• Streak & stats — current streak, best streak, 30-day completion rate, and total commits

🚀 Tech Stack

Technology	Role
React Native + Expo	Main framework
TypeScript	Static typing
AsyncStorage	Local data persistence
expo-notifications	Local push notifications
react-native-shared-preferences	React Native ↔ Android widget bridge
Kotlin	Native Android widget (AppWidgetProvider)
react-native-svg	SVG-based contribution grid rendering

📦 Getting Started

# Clone
git clone https://github.com/valb-mig/app.commitable.git
cd app.commitable

# Install dependencies
npm install

# Start Expo dev server
npx expo start

# Run on Android (with device/emulator connected)
npx expo run:android

Note: The Android widget requires a native build (expo run:android). It will not appear in Expo Go.

🔌 Connector API Contract

Habits can pull commits from an external HTTP endpoint. The URL must return the following JSON:

{
  "days": {
    "2025-06-01": { "committed": true, "message": "optional note" },
    "2025-06-02": { "committed": false },
    "2025-06-03": { "committed": true }
  }
}

Field	Type	Description
days	object	Keys are ISO dates (YYYY-MM-DD), values are day objects
days[date].committed	boolean	Whether that day counts as committed
days[date].message	string?	Optional commit note

Commits from the connector are merged with existing local commits — existing messages are preserved unless the connector provides a new one.

To trigger a sync, open the habit's detail view and tap sync connector.

🤖 Android Widget

The widget displays a 52-week contribution grid for the habit that was last viewed or committed.

Setup:

1. Build and install the app: npx expo run:android
2. Long-press your home screen → Widgets → Commitable
3. Tap the refresh button (↻) on the widget to force an update

The widget reads from SharedPreferences. It updates automatically every time the app writes a commit.

🔔 Notifications

During habit creation (step 4 — "lembrete diário"), you can enable a daily reminder:

• Toggle on/off
• Pick an hour (0–23) and minute (00, 15, 30, 45)
• Permissions are requested on first enable

Notifications are cancelled automatically when a habit is deleted.

🗂 Project Structure

src/
├── components/
│   ├── CommitGrid.tsx     # SVG contribution grid
│   ├── CommitList.tsx     # Recent commits log
│   ├── CommitModal.tsx    # Day edit bottom sheet
│   └── HabitCard.tsx      # Habit card with mini grid
├── hooks/
│   └── useHabits.ts       # Central state + AsyncStorage + widget sync
├── screens/
│   ├── HomeScreen.tsx     # Main view (all habits / filtered view)
│   └── CreateHabitScreen.tsx  # 4-step habit creation/edit
├── services/
│   ├── notifications.ts   # expo-notifications helpers
│   └── widget.ts          # Android widget bridge
├── utils/
│   ├── date.ts            # Date helpers and week generation
│   ├── stats.ts           # Streak and completion rate calculations
│   └── theme.ts           # Colors and font constants
└── types.ts               # Shared TypeScript types

🛣 Roadmap

See PLAN.md for the full roadmap including upcoming features and known issues tracked as GitHub Issues.

📄 License

MIT