# floret-kit

The shared **Material 3 Expressive design system + plumbing** for the Floret
family of Android apps ([Calendula](https://gitea.jeanlucmakiola.de/makiolaj/calendula),
[Agendula](https://gitea.jeanlucmakiola.de/makiolaj/agendula), and future siblings).

"Floret" is the family's design language: a Calendula flower head is a cluster of
many small *florets*, and each app is one of them. This repo is the bloom they
share — so a new app doesn't reinvent a settings screen, an edit form, or a theme;
it draws from here.

## How it's consumed

Each app embeds this repo as a **git submodule** and wires it in with a Gradle
**composite build**, so the kit is always built **from source** (no published
artifacts — keeps every app reproducible for F-Droid):

```kotlin
// app's settings.gradle.kts
includeBuild("floret-kit")
```
```kotlin
// app module's build.gradle.kts
implementation("de.jeanlucmakiola.floret:core-time")
```

Gradle's dependency substitution maps `de.jeanlucmakiola.floret:<module>` to the
local source module — edit the kit and the app picks it up immediately. Android
modules need an SDK location for the included build: set `ANDROID_HOME` (CI) or
add a gitignored `<app>/floret-kit/local.properties` with `sdk.dir` (locally).
See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the full consumption model.

## Modules

| Module | Type | What it holds |
|--------|------|---------------|
| `core-time` | JVM | Date/time helpers: `DayWindow` local-day windows, locale/zone-aware `Instant` formatting, `TimeBridge` (millis ↔ `Instant`). No Android, no deps. |
| `core-crash` | Android | Privacy-respecting on-device crash capture + report dialog + issue-tracker hand-off. Parameterized per app via `CrashConfig`. |
| `identity` | Android | The M3 Expressive theme factory `FloretExpressiveTheme(…)` + `rememberNavSlideSpec()`. Each app supplies its own seed/palette. |
| `components` | Android | Shared Compose vocabulary: `GroupedSurface`/`GroupedRow`, `InlineTextField`, `OptionCard`, `CollapsingScaffold`, `OptionPicker`, `pastelize()`. |

_The principle: the **mechanics** are shared, the **look** stays per-app. See
[`docs/ROADMAP.md`](docs/ROADMAP.md) for what's extracted, deferred, and
deliberately not shared._

## Docs

See [`docs/`](docs/) — start with [`docs/README.md`](docs/README.md)
([ARCHITECTURE](docs/ARCHITECTURE.md), [ROADMAP](docs/ROADMAP.md)) and
[`CONTRIBUTING.md`](CONTRIBUTING.md) to add or change a module.
[`CHANGELOG.md`](CHANGELOG.md) tracks what landed.

## Build

```sh
./gradlew :core-time:test          # JVM module tests
./gradlew :core-crash:testDebugUnitTest
./gradlew build                    # everything (Android modules need an SDK; see above)
```