@legendapp/list 2.0.0-next.0 → 2.0.0-next.2

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bun run:*)"
+    ],
+    "deny": []
+  }
+}

package/.cursor/rules/changelog.mdc

@@ -0,0 +1,60 @@
+---
+description:
+globs: CHANGELOG.md
+alwaysApply: false
+---
+# Changelog Update Rules
+
+## Process for Adding Git Changes to Changelog
+
+When updating the changelog with recent git commits, follow these guidelines:
+
+### 1. Identify Relevant Commits
+- Get all commits since the last version using: `git log --oneline --since="$(git log --grep="X.X.X" --format="%cd" --date=iso | head -1)" --reverse`
+- Exclude non-user-facing commits like:
+  - "Update changelog"
+  - "chore:" commits
+  - Internal refactoring that doesn't affect API
+  - "Refactor*" commits
+
+### 2. Categorize Changes
+Organize changes by type with these prefixes, in this order:
+- **Feat:** New features and capabilities
+- **Fix:** Bug fixes and corrections
+- **Perf:** Performance improvements
+- **Improvement:** Enhancements to existing functionality
+
+Skip **Refactor:**, they don't need to be in the changelog
+
+### 3. Format Guidelines
+- Write user-friendly descriptions, not raw commit messages
+- Focus on the impact/benefit to users
+- Be concise but descriptive
+- Use present tense ("Fix X" not "Fixed X")
+- Group similar changes together when possible
+
+### 4. Version Organization
+- Add changes to the current version in package.json
+- If significant changes warrant a new version, bump version first
+- List most important changes (breaking changes, major features) first
+- Group fixes and minor improvements at the end
+
+### 5. Example Format
+```markdown
+## X.X.X
+- Fix: [Issue description and impact]
+- Fix: [Another bug fix]
+- Feat: [New feature description]
+- Refactor: [API change description]
+- Perf: [Performance improvement description]
+- Improvement: [Enhancement description]
+```
+
+### 6. Quality Check
+- Ensure all user-facing changes are documented
+- Verify technical accuracy of descriptions
+- Check that breaking changes are clearly marked
+- Review for consistency in tone and format
+
+### 7. Update package version
+If a specific version number is requested and it is newer than the version in package.json, update package.json

package/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: [jmeistrich]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

package/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+example/android
+example/ios
+legendapp-list.tgz

package/.prettierrc.json

@@ -0,0 +1,5 @@
+{
+    "tabWidth": 4,
+    "printWidth": 120,
+    "singleQuote": true
+}

package/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+    "editor.codeActionsOnSave": {
+        "source.organizeImports.biome": "explicit",
+        "quickfix.biome": "explicit"
+    },
+    "editor.defaultFormatter": "biomejs.biome",
+    "[typescriptreact]": {
+        "editor.defaultFormatter": "biomejs.biome"
+    },
+    "[typescript]": {
+        "editor.defaultFormatter": "biomejs.biome"
+    },
+    "editor.formatOnSave": true
+}

package/CLAUDE.md

@@ -0,0 +1,126 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Build and Development
+- `bun run build` - Build the package using tsup and run post-build script
+- `bun run publish:manual` - Build and publish to npm manually
+- `bun run lint` - Check code formatting with Biome for src and example
+- `bun run lint:fix` - Auto-fix formatting issues with Biome for src and example
+
+### Example App Development
+The repository includes a React Native example app in the `example/` directory:
+- `cd example && bun i && bun run ios` - Run the example app on iOS
+- Example app uses Expo and demonstrates various Legend List features
+
+### Build Process
+- Uses tsup for TypeScript compilation with multiple entry points:
+  - `src/index.ts` (main export)
+  - `src/animated.tsx` (animated variant)
+  - `src/reanimated.tsx` (reanimated variant)
+  - `src/keyboard-controller.tsx` (keyboard integration)
+- Post-build script (`posttsup.ts`) copies LICENSE, CHANGELOG.md, README.md to dist and modifies package.json for publishing
+- Builds to both CommonJS and ESM formats with TypeScript declarations
+
+## Architecture Overview
+
+Legend List is a high-performance React Native list component designed as a drop-in replacement for FlatList with better performance, especially for dynamically sized items.
+
+### Core Components
+
+**LegendList** (`src/LegendList.tsx`): Main component that wraps functionality in a StateProvider
+- Handles virtualization logic, scroll management, and item positioning
+- Manages anchor elements for `maintainVisibleContentPosition`
+- Implements advanced scroll adjustment and jump prevention
+- Uses container recycling for optimal performance
+
+**State Management** (`src/state.tsx`): Global state management using observable patterns
+- Manages container positions, item data, and scroll state
+- Provides reactive updates to child components
+
+**Container System** (`src/Container.tsx`, `src/Containers.tsx`): Manages item rendering containers
+- Implements container recycling when `recycleItems` is enabled
+- Handles absolute positioning of list items
+- Manages container allocation and deallocation
+
+**Scroll Adjustment** (`src/ScrollAdjustHandler.ts`): Handles complex scroll position adjustments
+- Prevents scroll jumps when items are added/removed
+- Manages scroll position during layout changes
+
+### Key Features Architecture
+
+**Dynamic Item Sizing**: Items can have varying heights without performance penalties
+- Uses `getEstimatedItemSize` or `estimatedItemSize` for initial estimates
+- Measures actual sizes on layout and adjusts total size calculations
+- Maintains position accuracy through size change events
+
+**Bidirectional Infinite Lists**: Supports infinite scrolling in both directions
+- `onStartReached` and `onEndReached` callbacks with configurable thresholds
+- Maintains scroll position when items are added to the beginning
+
+**Chat UI Support**: 
+- `alignItemsAtEnd` aligns content to bottom for chat interfaces
+- `maintainScrollAtEnd` automatically scrolls to end when new items are added
+- Avoids need for inverted lists which cause animation issues
+
+**Column Support**: Multi-column layouts via `numColumns` prop
+- Manages row heights when items have different sizes within the same row
+- Handles column-aware positioning and gap calculations via `columnWrapperStyle`
+
+### Performance Optimizations
+
+**Virtualization**: Only renders items in the visible area plus buffer zones
+- `drawDistance` controls how far ahead/behind to render items
+- Dynamic buffer adjustment based on scroll velocity
+- Container recycling to minimize React element creation/destruction
+
+**Scroll Jump Prevention**: Sophisticated system to prevent visual jumps
+- Anchor element tracking for `maintainVisibleContentPosition`
+- Scroll history tracking for velocity calculations
+- Position adjustment when item sizes change
+
+**Batched Updates**: Groups layout calculations to reduce renders
+- Uses `requestAnimationFrame` for batching size change calculations
+- Optimizes container position updates
+
+## Integration Patterns
+
+### Basic Usage
+Legend List is designed as a drop-in FlatList replacement:
+```typescript
+<LegendList
+  data={data}
+  renderItem={renderItem}
+  keyExtractor={(item) => item.id}
+  recycleItems={true}
+/>
+```
+
+### Optional Integrations
+- **Animated**: `@legendapp/list/animated` - Works with React Native Animated
+- **Reanimated**: `@legendapp/list/reanimated` - Works with React Native Reanimated
+- **Keyboard Controller**: `@legendapp/list/keyboard-controller` - Integrates with react-native-keyboard-controller
+
+### Viewability Tracking
+Supports advanced viewability detection:
+- Compatible with FlatList's `viewabilityConfig` and `onViewableItemsChanged`
+- Custom hooks available: `useViewability`, `useViewabilityAmount`
+
+## Important Development Notes
+
+- When working with container recycling (`recycleItems={true}`), be cautious about local state in item components
+- The `keyExtractor` is crucial for performance and correct behavior when data changes
+- Use `getEstimatedItemSize` for better performance with varying item sizes
+- The component uses advanced scroll position management that should not be interfered with directly
+
+## Configuration Files
+
+- **Biome** (`biome.json`): Used for linting and formatting with specific rules for the project
+- **TypeScript** (`tsconfig.json`): Configured for React Native with path mappings for internal imports
+- **Cursor Rules**: `.cursor/rules/changelog.mdc` contains guidelines for maintaining the changelog
+
+## Testing the Library
+
+To test changes, use the comprehensive example app which demonstrates various scenarios including dynamic sizing, infinite loading, chat interfaces, and performance comparisons with FlatList.

package/biome.json

@@ -0,0 +1,46 @@
+{
+    "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+    "vcs": {
+        "enabled": false,
+        "clientKind": "git",
+        "useIgnoreFile": false
+    },
+    "files": {
+        "ignoreUnknown": false,
+        "ignore": []
+    },
+    "formatter": {
+        "enabled": true,
+        "formatWithErrors": false,
+        "indentStyle": "space",
+        "indentWidth": 4,
+        "lineEnding": "lf",
+        "lineWidth": 120
+    },
+    "organizeImports": {
+        "enabled": true
+    },
+    "linter": {
+        "enabled": true,
+        "rules": {
+            "recommended": true,
+            "style": {
+                "noNonNullAssertion": "off"
+            },
+            "suspicious": {
+                "noArrayIndexKey": "off",
+                "noExplicitAny": "off",
+                "noConfusingVoidType": "off"
+            },
+            "correctness": {
+                "noUnusedImports": "warn",
+                "useExhaustiveDependencies": "off"
+            }
+        }
+    },
+    "javascript": {
+        "formatter": {
+            "quoteStyle": "double"
+        }
+    }
+}