callstack / callstack/react-native-paper

feat: modernize List related components to the latest MD3 specs

Open
#4,976 1 comment 0 reactions 0 assignees View on GitHub
v6
Dominant language
TypeScript
Stars
14.5k
Forks
2.2k
Avg merge
5d 23h
Merged PRs (30d)
12

Description

The list specific components are spread out in the places mentioned below.
We need a refactoring to reuse the theme tokens, update to the latest specs(https://m3.material.io/components/lists) and simplify the implementation by reusing/composing subcomponents.
The specs mention draggable, swipeable and toggleable list items.
Given the complexity, this task can be split into multiple PRs.

# Current State

## List Accordion

**MD3 spec:** Lists (expand interaction)
**Specs link:** https://m3.material.io/components/lists/specs

### Color tokens

- Description / supporting text: `onSurfaceVariant` ✅
- [ ] Title color when expanded: hardcoded to `primary`; spec label text uses `onSurface` regardless of expand state
- [ ] Left icon color when expanded: hardcoded to `primary`; spec uses `onSurfaceVariant` for leading icons
- [ ] Container background: `theme.colors.background`; should be `surface`
- No selected state colors (`primaryContainer` bg / `onPrimaryContainer` text/icon) ❌

### Spacing / sizing

- `paddingVertical: 8` (container) + `marginVertical: 6` (row) = 14dp each side; spec 1-line item is 56dp total height, requiring 16dp top/bottom padding ❌
- `paddingRight: 24` trailing ✅
- Content `paddingLeft: 16` ✅
- [ ] Title and description use hardcoded `fontSize: 16` / `fontSize: 14`; should use `theme.fonts.bodyLarge` / `theme.fonts.bodyMedium`

### Behavior

- Expand/collapse toggling via press ✅
- Controlled and uncontrolled modes ✅
- [ ] No expand/collapse animation; children appear and disappear instantly
- [ ] Chevron direction reversal is the only visual feedback for expanded state; no container highlight or shape change
- [ ] No multi-select or single-select mode

### Notes

- Should be renamed to align with MD3 terminology (e.g., expandable list item) after the audit
- Animations and selected state are the most impactful missing features

---

## List Accordion Group

**MD3 spec:** Lists (expand interaction – single-expand group)
**Specs link:** https://m3.material.io/components/lists/specs

### Color tokens

No color logic of its own – delegates to `List.Accordion`. ✅

### Spacing / sizing

No sizing logic of its own. ✅

### Behavior

- At most one accordion expanded at a time (single-expand) ✅
- Controlled and uncontrolled modes ✅
- No direct MD3 equivalent; the constraint is implied by MD3 single-select list behavior ✅

### Notes

- Pure context provider; no rendering of its own
- No issues beyond what is inherited from `List.Accordion`

---

## List Item

**MD3 spec:** Lists
**Specs link:** https://m3.material.io/components/lists/specs

### Color tokens

- Title: `onSurface` ✅
- Description / supporting text: `onSurfaceVariant` ✅
- Leading and trailing icon color passed as `onSurfaceVariant` ✅
- No container background set (inherits from parent) – acceptable since list items sit on `surface` ✅
- [ ] No selected state: spec defines `primaryContainer` bg / `onPrimaryContainer` label+icon for selected items

### Spacing / sizing

- `paddingVertical: 8` (container) + `marginVertical: 6` (row) = 14dp each side; spec 1-line is 56dp requiring 16dp padding each side ❌
- `paddingRight: 24` trailing ✅
- Content `paddingLeft: 16` ✅
- [ ] Title uses hardcoded `fontSize: 16`; should use `theme.fonts.bodyLarge`
- [ ] Description uses hardcoded `fontSize: 14`; should use `theme.fonts.bodyMedium`

### Behavior

- State layers via `TouchableRipple` ✅
- Left and right render-prop slots ✅
- [ ] No overline text slot (spec anatomy includes overline above label)
- [ ] No trailing text slot
- [ ] No selected state prop
- [ ] No multi-action support (multiple independent trailing actions)

### Notes

- The `left` / `right` render-prop API is flexible but predates the MD3 slot model (leading / content / trailing); a typed slot API would be more aligned and enable correct padding calculations

---

## List Section

**MD3 spec:** Lists (section grouping / subheader)
**Specs link:** https://m3.material.io/components/lists/specs

### Color tokens

No color logic; delegates to `ListSubheader`. See `ListSubheader` for token review.

### Spacing / sizing

- `marginVertical: 8` on the section container – MD3 does not prescribe margin between sections; acceptable as a layout aid

### Behavior

- Groups list items under an optional subheader ✅
- No MD3-specific behavior beyond grouping

### Notes

- No functional issues; purely a layout container
- `ListSubheader` is not audited separately; its token usage should be verified against the MD3 subheader spec

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.