Skip to content
GeronfirPublic

About

LexiClock — Typographic Android home-screen widget that spells the time in words. Jetpack Glance, pure-Kotlin engine, Material 3, 71 unit tests.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

LexiClock — Word Clock Widget for Android

Build Release License: MIT Platform

An Android home-screen widget that tells the time in words instead of digits — "IT IS QUARTER PAST THREE", lit up in a letter-grid, exactly like a physical word clock.

Built for reliability, battery efficiency and extensibility: the time-to-words logic is a plain, fully unit-tested Kotlin library with no Android dependency, and the widget is a thin rendering shell on top of it.

v1.0 — Word Grid and Flowing Text styles, per-widget configuration, offline-first, no background service. 71 JVM unit tests, all green in CI.


Features

  • Word Grid — the classic lit/unlit word matrix (5×5 English grid).
  • Flowing Text — the same time rendered as a readable phrase.
  • Per-widget configuration — each widget instance keeps its own settings (12/24-hour, day period, style, colours).
  • Battery-friendly updates — an inexact AlarmManager alarm ticks once a minute; there is no permanently running service.
  • Offline-first — no network permission is requested and none is needed.
  • Lifecycle-safe — survives reboot, timezone/locale changes, resizes, widget restore, and configuration deletion.
  • Accessible — the lit phrase is exposed as a content description, and active words are bold as well as brighter, so state is never colour-only.

Architecture

System Clock
    ↓
Time Source (java.time, device timezone)
    ↓
Time Representation Engine   ← pure Kotlin, no Android
    ↓
Localization / Language Rules
    ↓
Semantic Time Model (SemanticTime: structured, not a string)
    ↓
┌─────────────────────┐
│                     │
▼                     ▼
Word Grid Renderer   Flowing Text Renderer
│                     │
└──────────┬──────────┘
           ▼
      Android Widget (Jetpack Glance)

Source layout

app/src/main/java/com/geronfir/wordclock/
├── engine/      Time logic + localization. No Android imports.
│   ├── WordKey.kt                  Language-neutral word keys
│   ├── SemanticTime.kt             Structured engine output
│   ├── TimeExpressionEngine.kt     Time → SemanticTime
│   ├── WordVocabulary.kt           English vocabulary
│   ├── WordGrid.kt                 5×5 English grid + active-cell mapping
│   ├── PhraseFormatter.kt          SemanticTime → readable phrase
│   ├── LocalizationRegistry.kt     Language lookup (extensible)
│   └── RepresentationStyle.kt      WORD_GRID | FLOWING_TEXT
├── settings/    Per-instance persistence (DataStore, namespaced by widget id)
├── widget/      Glance widget, receiver, per-minute scheduler, size resolver
└── config/      One-screen configuration activity

The engine has no Android imports, which is why every test runs as a plain JVM test in CI — no emulator, no instrumentation.

Building

Building happens in GitHub Actions (see .github/workflows/build.yml); the debug APK and test results are uploaded as workflow artifacts.

Locally, the same Gradle wrapper works if you have an Android SDK:

./gradlew testDebugUnitTest   # all unit tests
./gradlew assembleDebug       # app/build/outputs/apk/debug/*.apk
./gradlew lintDebug           # Android Lint

CI also runs scripts/verify-apk.sh against the assembled APK to prove it has a launcher activity and Compose-transformed code (guards the "Can't show content" widget regression).

Toolchain

Component Version
Android Gradle Plugin 8.13.2
Gradle 8.13
Kotlin 2.1.21
Jetpack Glance 1.1.1
compileSdk / targetSdk 35
minSdk 26
JDK 17 (CI) / 21 (local dev)

Testing

71 unit tests, all JVM-only:

Suite Covers
TimeExpressionEngineTest o'clock / past / to, boundary minutes, hour carry, 12/24-hour, timezones, invalid input
EnglishWordGridTest grid shape, unique tokens, active-cell mapping, shared FIVE/TEN cells
EdgeCaseTest all 1440 minutes of the day, midnight/noon, DST transitions, leap day, rounding off
LocalizationExtensibilityTest a second language with different word order and a different grid
IndonesianLocalizationTest hour-first phrasing, lebih/kurang, the setengah half-hour rule, day periods
GridMetricsTest continuous size → typography mapping; the grid fits at 30 dp and 5000 dp
GridMetricsScaleTest the user's font-size preference and its guards

Design decisions

See docs/DECISIONS.md for the reasoning behind the bigger choices (Glance, AlarmManager, value-class workarounds, grid token sharing).

License

MIT — see LICENSE.


Written, built and released from an Android phone (Termux + GitHub Actions).

About

LexiClock — Typographic Android home-screen widget that spells the time in words. Jetpack Glance, pure-Kotlin engine, Material 3, 71 unit tests.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages