callstack / callstack/react-native-paper
feat: modernize List related components to the latest MD3 specs
- 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
Assessment
This issue has not been assessed yet.