Skip to content

maxrave-dev/kotlin-footguns / skills/compose-screens-footguns

compose-screens-footguns

Verified

Compose screen and interaction traps: navigation, adaptive layout, window insets, pagers, toolbars, sheets, list drag and selection, sliders, text fields, settings UI, one-shot effects. Use when layout, gestures or navigation misbehave.

FileKindSize
SKILL.mdskill md21.6 KB
references/collapsing-parallax-toolbar.mdmarkdown8.4 KB
references/commit-a-text-field-on-an-explicit-action.mdmarkdown8.1 KB
references/control-range-must-cover-stored-values.mdmarkdown6.2 KB
references/custom-modal-sheet-family.mdmarkdown7.1 KB
references/custom-thin-media-slider.mdmarkdown8.3 KB
references/desktop-mini-player-window.mdmarkdown7.8 KB
references/edit-a-shape-as-a-shape.mdmarkdown7.1 KB
references/empty-state-must-keep-its-navigation.mdmarkdown7.0 KB
references/event-not-state-edge-for-one-shot-effects.mdmarkdown7.5 KB
references/expandable-and-linkified-text.mdmarkdown6.9 KB
references/floating-overlay-reserves-its-own-strip.mdmarkdown9.1 KB
references/fullscreen-video-gesture-overlay.mdmarkdown7.6 KB
references/hidden-setting-does-not-clear-the-stored-value.mdmarkdown6.3 KB
references/layered-video-backdrop-pager.mdmarkdown8.6 KB
references/lazy-item-grouping-beats-arrangement-gap.mdmarkdown8.2 KB
references/lazy-list-drag-reorder.mdmarkdown8.0 KB
references/lazy-scroll-helper-kit.mdmarkdown6.9 KB
references/nav-tab-registration-drift.mdmarkdown8.6 KB
references/nowplaying-pager-no-feedback-loop.mdmarkdown7.5 KB
references/progress-indicator-as-scrubber.mdmarkdown6.0 KB
references/responsive-gate-size-not-platform.mdmarkdown9.0 KB
references/scoped-composable-shadows-the-top-level-one.mdmarkdown5.3 KB
references/screen-shell-content-split.mdmarkdown7.2 KB
references/selection-mode-state-holder.mdmarkdown8.0 KB
references/self-hiding-child-cannot-hide-its-slot.mdmarkdown5.2 KB
references/settings-value-round-tripped-through-its-label.mdmarkdown6.2 KB
references/stacked-bars-double-consume-window-insets.mdmarkdown8.7 KB
references/story-reel-auto-pager.mdmarkdown8.5 KB
references/swipe-action-list-row.mdmarkdown7.7 KB
references/type-safe-nav-graph-organization.mdmarkdown7.6 KB
references/variant-layout-math-stays-in-the-variant.mdmarkdown5.8 KB
references/weight-fill-false-to-center-a-cluster.mdmarkdown8.6 KB

references/selection-mode-state-holder.md

View on GitHub
---
name: selection-mode-state-holder
description: A small @Stable holder for multi-select in a Compose list — keyed by stable id rather than list position, with every mutation funnelled through one private method so a hard cap on the selection size cannot be bypassed, plus the toggle/clear/select-all semantics that make the two gestures read differently. Use when building bulk actions over a list, when selections drift onto the wrong rows after a reorder or a page load, or when a cap holds for tapping rows but not for select-all.
---

# A multi-select state holder

One `@Stable` class, held by the screen, read by the row. Two pieces of observable state — whether
the mode is on, and which ids are picked — and exactly one way to add to the second:

```kotlin
// adapted
@Stable
class SelectionState(private val limitMessage: String) {
    var isActive by mutableStateOf(false); private set

    private val _selected = mutableStateListOf<String>()
    val selected: List<String> get() = _selected
    val count: Int get() = _selected.size
    val isFull: Boolean get() = _selected.size >= MAX_SELECTION

    fun isSelected(id: String): Boolean = _selected.contains(id)

    /** The only way into [_selected] — which is what makes the cap hold. */
    private fun add(id: String): Boolean {
        if (id.isBlank() || _selected.contains(id)) return true
        if (isFull) { notifyLimitReached(limitMessage); return false }
        _selected.add(id)
        return true
    }
}
```

`start(id)` (long press) turns the mode on and adds one. `toggle(id)` (tap while active) removes or
adds. `toggleSelectAll(ids)` fills up to the cap, or clears. `exit()` turns the mode off and empties.
Every **addition** among them goes through `add` — that is the choke-point, and it is only about
growth. Removals stay direct (`toggle` calls `remove`, select-all and `exit` call `clear`), because
nothing has to be checked on the way out.

## Traps

**Track ids, not list positions.** An index identifies a row only until the list changes shape, and
the lists that get multi-select are exactly the ones that do: paged lists that grow underneath you,
reorderable lists where a drag renumbers everything between the source and the destination. After
either, an index-keyed selection is silently pointing at different rows than the ones the user
ticked — and a bulk action then runs on those. If the same screen also supports drag-to-reorder (see
`lazy-list-drag-reorder`), this is not a hypothetical.

**One private mutator is what makes the cap real.** There are three ways into the selection — long
press, tap, select-all — and a cap checked at each of them is a cap that survives until someone adds
a fourth. Route all three through one private `add`, check there, and the check cannot be bypassed
by the path nobody remembered. The same argument applies to normalisation: `add` rejects blanks and
duplicates, so no caller has to.

**The mutator returns a Boolean so bulk callers can stop.** Select-all loops; without a return value
it either keeps calling past the cap (firing the "limit reached" feedback once per remaining item —
dozens of toasts from one tap) or it needs its own copy of the cap check, which is the duplication
the choke-point exists to prevent:

```kotlin
// adapted
for (id in candidates) { if (!add(id)) return }
```

**Test "everything is already picked" against what select-all *would* pick, not against the whole
list.** Select-all doubles as deselect-all: pressing it again when its work is already done should
clear. But it only ever picks the first `MAX_SELECTION` candidates, so comparing against the full
input list can never report "all picked" on any list longer than the cap — and the button becomes
one-way. Compare against the truncated set:

```kotlin
// adapted
val candidates = ids.filter { it.isNotBlank() }.distinct()
val everythingReachableIsPicked =
    candidates.isNotEmpty() && candidates.take(MAX_SELECTION).all { _selected.contains(it) }
if (everythingReachableIsPicked) { _selected.clear(); return }
```

**Clearing by tap and clearing by select-all must end differently.** Tapping rows off one at a time
until none are left reads as *leaving* the mode, so `toggle` calls `exit()` when it empties the list
— otherwise the user is stranded in an action bar with nothing to act on and no obvious way out.
Pressing select-all a second time reads as *starting over*, so it clears the list and deliberately
stays active. Same end state, two intentions; collapsing them makes one of the two gestures feel
broken.

**Expose counts as derived getters over the snapshot list, not as separate state.** `count` and
`isFull` computed from `_selected.size` cannot go stale, and a header reading `state.count`
subscribes to the snapshot list and recomposes on change without holding the list itself. A cached
`var count` beside the list is a second source of truth for the same fact.

**`@Stable` is a promise the class has to keep.** It tells the compiler that every publicly readable
property changes only through the snapshot system, so composables reading this holder may be
skipped when it has not changed. `isActive` is `mutableStateOf` and `_selected` is
`mutableStateListOf`, so the promise holds. Add one plain `var` that the UI reads and the annotation
becomes a lie: the UI stops recomposing when that field changes, with no warning anywhere.

**A `remember`ed holder keyed on a localised string is rebuilt when the locale changes.** Building
the limit message with a string resource and keying `remember` on it is convenient, but it means the
selection is dropped on a language switch — and plain `remember` drops it on configuration change
and process death anyway. If a selection must survive those, hold it in the screen's view model
instead and pass the message in at the call.

**Reporting the limit from inside the holder is a deliberate trade, not an accident.** Putting the
notification next to the check keeps the cap in one place; the cost is that the state class now
depends on a UI notification API and cannot be exercised off the main thread. If that matters,
have `add` return a richer result and let the screen render it — but keep the *decision* in the
holder, or the cap fragments again.

## Verifying it

1. **Exactly one write path into the backing list.**
   `grep -n '_selected\.' <holderFile>`
   → observed: one `_selected.add(...)`, inside the private mutator; one `_selected.remove(...)` in
   `toggle`; two `_selected.clear()` (select-all and exit); everything else is a read
   (`.size`, `.contains`, `.isEmpty`). A second `.add` anywhere means the cap has a bypass.
2. **The cap constant is referenced by the check and by the truncation, and nowhere re-derived.**
   `grep -rn '<capConstant>' --include='*.kt' .`
   → observed: the declaration, the `isFull` comparison, the `take(...)` in select-all, the message
   formatting, and two references from documentation comments. A numeric literal for the same limit
   at any call site is a second cap.
3. **Every screen that turns the mode on also wires the toggle.** Compare the two per-file counts:
   ```bash
   grep -rc 'selectionMode =' --include='*.kt' . | grep -v ':0$' | sort
   grep -rc 'onSelectToggle =' --include='*.kt' . | grep -v ':0$' | sort
   ```
   → observed: the two listings match file for file and count for count, except one file whose
   `selectionMode` belongs to an unrelated file-picker API — worth knowing, because that is what a
   false positive looks like here. A genuine mismatch is a screen that renders checkboxes nothing
   can tick. Note the patterns carry no trailing space: a wrapped argument puts the value on the
   next line, and `'onSelectToggle = '` silently misses those.
4. By hand: select up to the cap, then press select-all. Nothing should be added and exactly one
   notification should appear — a burst of them means a caller is looping past a mutator whose
   return value it ignores.
5. By hand on a reorderable list: select two rows, drag a third between them, and confirm the same
   two rows are still ticked. If the ticks moved, the holder is keyed on positions.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall