BaseRecyclerViewAdapterHelper (Agent Skills)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project

BRVAH (BaseRecyclerViewAdapterHelper) — a RecyclerView Adapter helper library for Android (current major version: **v4.x**, published as `io.github.cymchad:BaseRecyclerViewAdapterHelper4`). v4 was rewritten to be fully compatible with `ConcatAdapter`, to split functionality into modules, and to support flexible multi-type layouts plus strengthened up/down load-more.

The repository contains **two Gradle modules**:
- `:library` — the published library (namespace `com.chad.library.adapter4`). This is the artifact.
- `:app` — the demo application that exercises every library feature (`com.chad.baserecyclerviewadapterhelper`). `demo/` holds a prebuilt APK only.

## Build & Toolchain

Gradle with Kotlin DSL (`settings.gradle`, `build.gradle.kts`, `gradle/libs.versions.toml`). Toolchain and SDK versions are pinned per module:

- **JDK 17** toolchain for both modules (CI uses temurin 17).
- `:library` — `compileSdk = 35`, `minSdk = 19`, depends only on `androidx.annotation`, `androidx.recyclerview`, and `compileOnly` `databinding-runtime`. No AndroidX app deps — it is a pure library.
- `:app` — `compileSdk/targetSdk = 36`, `minSdk = 23`, uses viewBinding + dataBinding, Moshi (KSP codegen). All third-party demo deps live here, never in `:library`.

Common commands (run from repo root):

```bash
./gradlew :library:compileDebugKotlin        # what CI runs — fastest library sanity check
./gradlew :library:assembleRelease           # build the AAR
./gradlew :app:assembleDebug                 # build the demo APK
./gradlew clean
```

There is **no test source set** — there are no unit or instrumented tests in either module. Verify changes by compiling and/or running the demo app.

### Publishing / versioning
- Library version lives in `library/build.gradle.kts` as `val versionName` (currently `4.4.1`). The `:app` `versionName` (`4.3.2`) is independent — update them separately.
- Publishing is configured with `maven-publish` + `signing`. Credentials/signing keys are read from `local.properties` (`signing.keyId`, `signing.password`, `signing.secretKeyRingFile`, `ossrhUsername`, `ossrhPassword`). The active publish repository is the local `$rootDir/Repo` folder (Maven Central upload block is commented out).
- ProGuard consumer rules ship via `consumerProguardFiles("proguard-rules.pro")` in `:library`, so consumers auto-import them; the file itself is mostly a placeholder.

## Library architecture

Everything is under `com.chad.library.adapter4`. The design centers on one abstract base plus adapter composition via `ConcatAdapter`.

### `BaseQuickAdapter<T, VH>` (the base class)
`BaseQuickAdapter.kt` is the foundation for all adapters. Two things define it:

1. **Two data modes**, decided at construction by whether a `DiffUtil.ItemCallback<T>`/`AsyncDifferConfig<T>` is supplied:
   - *Diff mode* — backs `items` with `AsyncListDiffer` (async diffing, no jank). Mutating ops (`submitList`, `add`, `set`, `removeAt`, `swap`, `move`, …) rebuild a mutable list and re-submit.
   - *Plain mode* (`mDiffer == null`) — backs `items` with a plain `List<T>` and calls the corresponding `notifyItem*` directly.
   Every mutating method branches on `mDiffer == null`; when touching one, update **both** branches.

2. **Sealed RecyclerView.Adapter overrides.** `getItemCount()`, `getItemViewType()`, `onCreateViewHolder()`, and `onBindViewHolder()` are `final`. Subclasses implement the **protected** variants instead (`onCreateViewHolder(context, parent, viewType)`, `onBindViewHolder(holder, position, item[, payloads])`, `getItemCount(items)`, `getItemViewType(position, list)`). Do not try to override the final ones.

Other base-class responsibilities: optional **state/empty view** (`isStateViewEnable` + `stateView`, shown when `items` is empty via `StateLayoutVH`), item **animations** (`animationEnable` + `itemAnimation`/`setItemAnimation(AnimationType)`), and click listeners (item / item-child by view id, stored in a `SparseArray`). `items` setter is `@Deprecated` at **ERROR level** — use `submitList()` to replace data.

### Adapter variants (all extend `BaseQuickAdapter`)
- **`BaseMultiItemAdapter<T>`** — multi view-type layouts. Register each type with `addItemType(viewType, OnMultiItemAdapterListener)` and decide types via `onItemViewType { position, list -> }`. The listener (or `OnMultiItem` subclass, which grants `adapter`/`context`) provides `onCreate`/`onBind` per type.
- **`BaseNodeAdapter`** — tree/expandable lists. Subclasses implement `getChildNodeList()` and `isInitialOpen()`; `open()`/`close()`/`openOrClose()`/`closeAll()` drive expansion. Open/closed state is tracked by a custom `NodeSet` matched through `isSameNode()` (override for value-based nodes; default is `===`). See the bilingual KDoc on `isSameNode` — it must uniquely identify a node or expand/collapse state leaks across nodes.
- **`BaseSingleItemAdapter<T, VH>`** — exactly one item (headers/footers). All list mutation methods throw; use `item`/`setItem()` only.
- **`BaseDifferAdapter`** — deprecated; `BaseQuickAdapter` now subsumes it.

### Composition: `QuickAdapterHelper`
`QuickAdapterHelper` wraps a content adapter in a `ConcatAdapter` and exposes `helper.adapter` to set on the `RecyclerView`. Layout order: `LeadingLoadStateAdapter` → before-adapters → **content adapter** → after-adapters → `TrailingLoadStateAdapter`. Built via `QuickAdapterHelper.Builder(contentAdapter)` with optional leading/trailing load-more, then `.build()` or `.attachTo(recyclerView)`. This is the canonical way to get header/footer and up/down load-more in v4 — header/footer are separate small adapters prepended/appended, not built-in fields of the base adapter.

### Load more (`loadState/`)
- `LoadState` — sealed type: `None`, `NotLoading(endOfPaginationReached)`, `Loading`, `Error`.
- `LoadStateAdapter<VH>` — base for a load-more adapter; toggles its single item on/off via `displayLoadStateAsItem()`.
- `TrailingLoadStateAdapter` (tail) / `LeadingLoadStateAdapter` (head), each with a `Default…` implementation. Trailing supports `isAutoLoadMore`, `preloadSize`, and `checkDisableLoadMoreIfNotFullPage()`.

### Supporting utilities
- `viewholder/QuickViewHolder` — convenience `ViewHolder` with cached `findViewById` and chained setters (`setText`, `setVisible`, …).
- `layoutmanager/QuickGridLayoutManager` — `GridLayoutManager` that grants full span to adapters implementing `FullSpanAdapterType`, and to `BaseQuickAdapter` view types for which `isFullSpanItem(type)` is true (the empty/state view is full-span by default). Use it (or your own `SpanSizeLookup`) when an item must span all columns.
- `dragswipe/QuickDragAndSwipe` + `DragSwipeExt.kt` — drag-and-swipe on top of `ItemTouchHelper`.
- `animation/*` — `ItemAnimator` implementations (`AlphaIn`, `ScaleIn`, `SlideIn{Left,Right,Bottom}`).
- `util/AdapterUtils.kt` — `ViewGroup.getItemView(layoutResId)` and `ViewHolder.asStaggeredGridFullSpan()`.

### Internal resource IDs
The library declares IDs in `library/src/main/res/values/ids.xml` (e.g. `BaseQuickAdapter_empty_view`, `BaseQuickAdapter_key_multi`) used for internal view tagging and the empty-view `viewType`. The `EMPTY_VIEW` companion constant points at `R.id.BaseQuickAdapter_empty_view`.

## Conventions

- **Bilingual KDoc.** Public API documentation is written in **both Chinese and English** (Chinese typically first, then English). Match this style when adding or editing public APIs.
- **Builder/`apply` chaining.** Setters in `BaseQuickAdapter` and `QuickAdapterHelper.Builder` return `apply`/the builder for fluent config.
- Keep `:library` dependency-free of UI libs — it should only depend on AndroidX `annotation`/`recyclerview` (plus `compileOnly` databinding). Put demo-only dependencies in `:app`.

# Repository Guidelines

## Project Structure & Module Organization
This is an Android Gradle project with Kotlin DSL build files. `settings.gradle` includes two modules:

- `library/`: the reusable RecyclerView adapter library published as `io.github.cymchad:BaseRecyclerViewAdapterHelper4`.
- `app/`: the sample Android application demonstrating library usage.

Main source lives under `app/src/main/java` and `library/src/main/java`. Android resources are under each module's `src/main/res`. Keep public library APIs in the `com.chad.library.adapter4` namespace and sample-only code in `com.chad.baserecyclerviewadapterhelper`.

## Build, Test, and Development Commands
Use the Gradle wrapper from the repository root:

- `./gradlew assembleDebug`: builds debug artifacts for all modules.
- `./gradlew :app:assembleDebug`: builds the sample app.
- `./gradlew :library:assembleRelease`: builds the release AAR for the library.
- `./gradlew clean`: removes generated build output.
- `./gradlew test`: runs JVM unit tests when test sources exist.
- `./gradlew connectedAndroidTest`: runs instrumentation tests on a connected device or emulator when present.

The project targets Java 17 via Gradle toolchains. Dependencies and plugin versions are centralized in `gradle/libs.versions.toml`.

## Coding Style & Naming Conventions
Use Kotlin for new code unless working in an existing Java file. Follow Android/Kotlin conventions: 4-space indentation, `UpperCamelCase` classes, `lowerCamelCase` functions and properties, and package names matching module namespaces. Prefer clear adapter, view holder, and load-state names that match existing patterns such as `BaseQuickAdapter`, `QuickViewHolder`, and `DefaultTrailingLoadStateAdapter`.

Keep resources lowercase with underscores, for example `brvah_trailing_load_more.xml`. Avoid unrelated formatting churn in mixed Java/Kotlin files.

## Testing Guidelines
No test directories are currently checked in. Add unit tests under `module/src/test` and Android tests under `module/src/androidTest` when changing behavior. Name tests after the unit under test and expected behavior, for example `BaseDifferAdapterTest`. Run `./gradlew test` before submitting logic changes, and use `connectedAndroidTest` for RecyclerView or UI behavior that needs Android runtime coverage.

## Commit & Pull Request Guidelines
Recent history uses Conventional Commit-style messages, often scoped, such as `fix(adapter): ...`, `refactor(loadState): ...`, and `docs(README): ...`. Keep commits focused and use scopes that match affected areas.

Pull requests should include a concise description, linked issues when applicable, test results, and screenshots or recordings for sample app UI changes. For library API changes, document migration notes and update README or wiki references when needed.

## Security & Configuration Tips
Do not commit `local.properties`, signing keys, Sonatype credentials, or generated publishing output. Publishing credentials are loaded from local properties or environment-specific configuration.