Initial release: modifier-node-cookbook

A curated collection of canonical Jetpack Compose modifiers, every one
written using the Modifier.Node API. No Modifier.composed anywhere.

Standalone (20):
  pressScale, shimmer, skeleton, hoverElevation, fadeScrollEdges,
  parallax, tilt, longPressProgress, dropShadow, gradientBorder,
  colorPulse, shake, glassmorphism, bounceOnAppear, revealOnScroll,
  marquee, swipeToDismiss, magnetic, pinchZoom, dragToReorder.

Composites (2):
  interactiveCard (pressScale + tilt + hoverElevation),
  loadingPlaceholder (skeleton + shimmer).

Cookbook library + sample app + MkDocs Material site + CI workflows
+ Maven Central publishing config.

Author: ChristophyBarth

.editorconfig

@@ -0,0 +1,26 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+max_line_length = 140
+
+[*.{kt,kts}]
+ij_kotlin_allow_trailing_comma = true
+ij_kotlin_allow_trailing_comma_on_call_site = true
+ij_kotlin_imports_layout = *
+ktlint_standard_no-wildcard-imports = disabled
+ktlint_standard_filename = disabled
+ktlint_standard_function-naming = disabled
+ktlint_standard_chain-method-continuation = disabled
+ktlint_standard_property-naming = disabled
+
+[*.{yml,yaml,md}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build & test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Validate Gradle wrapper
+        uses: gradle/actions/wrapper-validation@v4
+
+      - name: Build, lint, ktlint, detekt, unit tests
+        run: ./gradlew build --stacktrace

.github/workflows/docs.yml

@@ -0,0 +1,40 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Deploy MkDocs site
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install MkDocs Material
+        run: |
+          python -m pip install --upgrade pip
+          pip install \
+            mkdocs-material==9.5.40 \
+            mkdocs-minify-plugin==0.8.0 \
+            pymdown-extensions==10.11
+
+      - name: Build site
+        run: mkdocs build --strict --verbose
+
+      - name: Deploy
+        run: mkdocs gh-deploy --force --verbose

.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish (e.g. 0.1.0)'
+        required: true
+
+jobs:
+  publish:
+    name: Publish to Maven Central
+    runs-on: ubuntu-latest
+    environment: maven-central
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Resolve version from tag or workflow input
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "version=${{ github.event.inputs.version }}" >> "$GITHUB_OUTPUT"
+          else
+            # Strip leading 'v' from the tag
+            echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Override VERSION_NAME with release version (drops -SNAPSHOT)
+        run: |
+          sed -i "s|^VERSION_NAME=.*|VERSION_NAME=${{ steps.version.outputs.version }}|" gradle.properties
+          grep "^VERSION_NAME=" gradle.properties
+
+      - name: Publish to Central Portal
+        env:
+          ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
+          ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}
+          ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.SIGNING_IN_MEMORY_KEY }}
+          ORG_GRADLE_PROJECT_signingInMemoryKeyId: ${{ secrets.SIGNING_IN_MEMORY_KEY_ID }}
+          ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.SIGNING_IN_MEMORY_KEY_PASSWORD }}
+        run: ./gradlew :cookbook:publishAndReleaseToMavenCentral --stacktrace --no-configuration-cache
+
+      - name: Create GitHub release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          name: ${{ steps.version.outputs.version }}

.gitignore

@@ -0,0 +1,26 @@
+.gradle/
+build/
+out/
+.idea/
+*.iml
+local.properties
+captures/
+.cxx/
+.kotlin/
+*.hprof
+.DS_Store
+gradle/wrapper/gradle-wrapper.jar.lock
+.gradle-cache/
+
+# Paparazzi failure artifacts
+**/src/test/snapshots/failures/
+
+# Secrets
+*.gpg
+*.asc
+*.jks
+*.keystore
+
+# IDE
+.vscode/
+*.swp

CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-04-27
+
+Initial release. Twenty production-ready standalone modifiers and two composites, all built on `Modifier.Node`. No `Modifier.composed` anywhere.
+
+**Standalone**
+
+- `Modifier.pressScale(scale, animationSpec)`: scales the receiver down on press, springs back.
+- `Modifier.shimmer(colors, angleDegrees, durationMillis, repeatMode)`: animated gradient sweep.
+- `Modifier.skeleton(shape, color)`: opaque placeholder shape.
+- `Modifier.hoverElevation(restingDp, hoveredDp, shape, animationSpec)`: animated elevation on hover.
+- `Modifier.fadeScrollEdges(scrollState, fadeLength)`: leading/trailing fade based on scroll.
+- `Modifier.parallax(scrollState, factor)`: child translates relative to a parent scroll.
+- `Modifier.tilt(maxAngleDeg, animationSpec)`: pointer-following 3D tilt.
+- `Modifier.longPressProgress(durationMs, strokeWidth, color, onComplete)`: radial hold progress.
+- `Modifier.dropShadow(color, blur, offset, shape)`: custom drop shadow untied from Material elevation.
+- `Modifier.gradientBorder(brush, width, animationSpec)`: animated gradient stroke around the receiver.
+- `Modifier.colorPulse(colors, durationMs)`: periodic color cycling for attention/badges.
+- `Modifier.shake(trigger, intensity, durationMs)`: single-shot horizontal shake driven by a trigger key.
+- `Modifier.glassmorphism(blurRadius, tint)`: frosted glass. `RenderEffect` blur on API 31+, translucent tint fallback below.
+- `Modifier.bounceOnAppear(initialScale, spring)`: single-shot entry bounce when the node first attaches.
+- `Modifier.revealOnScroll(translationY, threshold, durationMs)`: fade + translate in as the element enters the viewport.
+- `Modifier.marquee(direction, gap, fadeEdges, fadeColor, velocity)`: auto-scroll on overflow with edge fades and configurable velocity.
+- `Modifier.swipeToDismiss(onDismiss, threshold, axis)`: drag past threshold dismisses, otherwise springs back.
+- `Modifier.magnetic(anchors, snapThreshold)`: drag snaps to the nearest anchor on release.
+- `Modifier.pinchZoom(minScale, maxScale)`: two-finger zoom with pan support, pivots around the gesture centroid.
+- `Modifier.dragToReorder(state, key)`: gesture-driven reorder for list items, paired with a `ReorderableState` helper.
+
+**Composite**
+
+- `Modifier.interactiveCard(...)`: `pressScale + tilt + hoverElevation` with sensible defaults.
+- `Modifier.loadingPlaceholder(shape)`: `skeleton + shimmer` in one call.
+
+Sample app with one screen per modifier. MkDocs Material doc site. CI on PRs, doc deploy on `main`, Maven Central publish on tag.
+
+[0.1.0]: https://github.com/ChristophyBarth/modifier-node-cookbook/releases/tag/v0.1.0

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing
+
+Thanks for considering a contribution. The cookbook has a deliberately narrow scope: a small, curated set of canonical Compose modifiers, all built on `Modifier.Node`. We'd rather ship 12 great modifiers than 50 mediocre ones.
+
+## Before you start
+
+- Open an issue first if you're proposing a new modifier. We'll talk through scope, name, and whether it belongs in `cookbook` (general-purpose) or somewhere else.
+- Bug fixes and doc improvements: jump straight to a PR.
+
+## The bar for a new modifier
+
+Every modifier in the cookbook ships:
+
+1. **A `Modifier.xxx(...)` extension** that validates inputs and returns `this then SomeElement(...)`.
+2. **A `ModifierNodeElement` subclass** as a `data class` (so `equals`/`hashCode` are correct), with a meaningful `update()` that mutates the existing node, never recreates.
+3. **A node class** mixing in the right `Modifier.Node` mixin(s). Pick the cheapest mixin that does the job.
+4. **KDoc** on the public function: paragraph description, parameter docs, a `@sample` reference to a sample function in `cookbook/.../samples/`.
+5. **A unit test** in `cookbook/src/test/...`. Use `createComposeRule` + Robolectric. Cover at minimum: parameter validation, parameter-change-without-recreation, and one behaviour assertion.
+6. **A sample-app screen** in `sample/.../screens/` and entry in `CookbookCatalog.catalogEntries()`.
+7. **A doc page** in `docs/modifiers/<name>.md` with usage, parameters, and design notes (which node subtype, why, any subtleties).
+
+## Quality gates
+
+The CI build must be green. Locally:
+
+```bash
+./gradlew build
+```
+
+That runs `ktlint`, `detekt`, lint, unit tests, and assembles both modules.
+
+Conventions:
+
+- **No `Modifier.composed`** anywhere in `cookbook/`. That's the entire point of the project.
+- **No `LaunchedEffect`** in modifier impls; use the node's `coroutineScope`.
+- **No reflection.** No `kotlin-reflect`, no `Class.forName`.
+- **Public API is `@Stable`** (or `@Immutable` for value classes).
+- **`explicitApi()` is on** in `cookbook`: every public symbol needs an explicit visibility modifier.
+- Animations driven by `Animatable` / `AnimationState`, cancelled implicitly by node detach.
+
+## Repo secrets (for maintainers)
+
+Publishing to Maven Central is wired through GitHub Actions and reads these repo secrets:
+
+| Secret | Purpose |
+|---|---|
+| `MAVEN_CENTRAL_USERNAME` | Central Portal user token name |
+| `MAVEN_CENTRAL_PASSWORD` | Central Portal user token password |
+| `SIGNING_IN_MEMORY_KEY` | ASCII-armored private GPG key (`gpg --armor --export-secret-keys <KEY_ID>`) |
+| `SIGNING_IN_MEMORY_KEY_ID` | The 8-character short key ID (e.g. `0A1B2C3D`) |
+| `SIGNING_IN_MEMORY_KEY_PASSWORD` | Passphrase for the GPG key |
+
+Pushing a `vX.Y.Z` tag triggers `.github/workflows/publish.yml`, which strips `-SNAPSHOT` from `gradle.properties`, signs, and uploads to the Central Portal staging bundle (auto-released).
+
+## Style
+
+- Kotlin official style. ktlint enforces.
+- `data class` for elements; small `internal class` for the node.
+- Names: file = `Xxx.kt` (PascalCase), package = `xxx` (all lowercase, no separators), public function = `Modifier.xxx` (camelCase).
+- Tests: `xxx_does_yyy()` (snake_case method names; backticks-with-spaces are nicer to read but ktlint and the Robolectric runner complain about characters like `[`/`]`).
+
+## License
+
+By contributing you agree your contribution is licensed under the Apache 2.0 License.