mtrl-addons 0.1.0 → 0.1.2

package/.cursorrules

@@ -0,0 +1,117 @@
+# mtrl-addons Package Development Rules
+
+## Package Overview
+
+mtrl-addons is an extension library for the mtrl Material Design 3 component system, providing specialized elements and extended functionality for modern applications. It maintains the same "less is more" philosophy with zero external dependencies (mtrl as peer dependency only).
+
+## Environment & Architecture
+
+- Part of workspace alongside mtrl and mtrl-app packages
+- mtrl-app serves as the information hub with documentation and showcases
+- Follows mtrl core architecture patterns and conventions
+- Primary dependency: mtrl
+
+## Development Philosophy
+
+- Follow "less is more" philosophy - minimalist but complete
+- Optimize for size, memory usage, and speed
+- Keep modules small and reusable for bundling
+- Find root causes and fix problems elegantly with minimal code
+- Avoid over-engineering and workarounds
+
+## Pre-Development Checklist
+
+1. Check if functionality already exists in mtrl (mtrl/src/core)
+2. Check mtrl styles system (mtrl/src/styles) before creating new styles
+3. Create tests first (mtrl-addons/test/) - test-driven development
+4. Use mtrl-app/docs for all documentation (no .md files in this package)
+
+## Code Standards
+
+### TypeScript & Structure
+
+- Use TypeScript for all components
+- Follow mtrl component and core structure conventions
+- Use pipe pattern for core and component composition
+- Add comprehensive TypeDoc comments for all public APIs
+- Maintain zero external dependencies policy
+
+### CSS & Styling
+
+- No inline CSS - use external SCSS files in src/styles/
+- Follow BEM naming: mtrl-component\_\_element--modifier
+- Use mtrl styles system as foundation
+
+### File Management
+
+- Prefer editing existing files over creating new ones
+- Avoid hyphens in filenames if possible
+- Prefer short filenames if clear enough
+- If you need to create html or js debugging files, just ./debugging folder (will be .git ignored)
+- No summary .md files for coding sessions
+- Component and Core usual ts files: index, main(module name), types, constant, api(special feature), features
+- If features become to large, create a folder and split the file by concern ans move api in it if appropriate
+
+### Component Development
+
+- Follow established mtrl component patterns (config, types, constants, features)
+- Always use functional composition over class inheritance
+- Implement proper lifecycle management
+- Ensure accessibility compliance - this is important!
+- Focus on the specific issue when fixing bugs - avoid enhancements during fixes
+
+## Testing Rules
+
+- Use Bun test runner for all tests
+- Mock components to avoid circular dependencies
+- Always use JSDOM for DOM testing
+- Comprehensive but lightweight tests
+- Follow test-first development approach
+
+## Showcase & Documentation
+
+- Create showcases in mtrl-app/client/content only and follow the hierarchy
+- Always use mtrl components via layout system (mtrl-app/docs/layout/usages.md)
+- Prefer array-based layout schema
+- Format schema following the formatting convention (mtrl-app/docs/core/layout/array-schema.md)
+- Avoid manual DOM element creation in showcases
+- Never inline CSS in showcases
+- Focus on demonstrating component capabilities
+- Keep the showcases small, maintainable and readable
+
+## Build & Deployment
+
+- Build using `bun run build:app` not `bun run build`
+- Fix TypeScript declaration errors immediately
+- Do not start development servers (bun/node)
+- Follow conventional commit format
+- Use `bun run build` for package builds
+- Ensure compatibility with both ES modules and CommonJS
+
+## Performance & Optimization
+
+- When enhancing/optimizing/refactoring: focus on size, memory usage, and speed
+- Minimize bundle size impact
+- Avoid unnecessary re-renders or DOM manipulations
+- Use efficient algorithms and data structures
+- Design for tree-shaking compatibility
+
+## Extension Development
+
+- Build upon mtrl core without duplicating functionality
+- Create specialized components not found in base mtrl package
+- Ensure seamless integration with mtrl component ecosystem
+- Maintain API consistency with mtrl patterns
+- Design for modularity - components should be importable individually
+
+## Prohibited Actions
+
+- Do not use React (pure TypeScript/JavaScript library)
+- Do not create markdown documentation for enhancements
+- Do not run server commands
+- Do not create workarounds or hacks
+- Do not duplicate mtrl core functionality
+- Do not enhance during bug fixes - stay focused on the issue
+- Do not harcode prefix
+- Do not use global Window object to store things
+- Do not build using bun run build (this is used for package build, use bun run build:app)

package/AI.md

@@ -0,0 +1,241 @@
+# MTRL-ADDONS - AI Assistant Guide
+
+This document provides specific guidance for AI assistants working with the mtrl-addons package - the advanced features extension library for the mtrl ecosystem.
+
+## 🎯 Package Purpose
+
+mtrl-addons extends the main mtrl library with advanced features and performance-optimized components:
+
+- **List Manager**: Virtual scrolling with intelligent data loading
+- **Collection System**: Advanced data management with caching and state
+- **Layout Schema**: Declarative UI composition system
+- **Performance Utilities**: Optimized calculations and range management
+
+## 🏗️ Architecture
+
+### Core Systems
+
+```
+src/
+├── components/           # Extended components
+│   └── list/            # Advanced list component
+├── core/                # Advanced core features
+│   ├── collection/      # Collection management system
+│   ├── list-manager/    # Virtual scrolling engine
+│   └── layout/          # Layout schema system
+└── styles/             # Extended component styles
+```
+
+### Key Features
+
+1. **List Manager** (`src/core/list-manager/`)
+   - Virtual scrolling with viewport management
+   - Item size calculation and caching
+   - Custom scrollbar implementation
+   - Collection integration for data loading
+
+2. **Collection System** (`src/core/collection/`)
+   - Data loading and caching strategies
+   - State management for large datasets
+   - Event-driven architecture
+
+3. **Layout Schema** (`src/core/layout/`)
+   - Declarative UI composition
+   - JSX-like syntax for component creation
+   - Array-based schema system
+
+## 🛠️ Development Guidelines
+
+### Dependencies
+- **Depends on mtrl main** - Import from `mtrl` package
+- **Zero additional dependencies** - Maintain the zero-dependency philosophy
+- **TypeScript first** - All features in TypeScript
+
+### Component Enhancement Pattern
+```typescript
+// Use functional composition to enhance components
+import { pipe } from 'mtrl/core/compose';
+import { createList } from 'mtrl/components/list';
+
+const enhancedList = pipe(
+  createList(config),
+  withCollection(collectionConfig),
+  withListManager(listManagerConfig),
+  withViewport(viewportConfig)
+);
+```
+
+### Performance Focus
+- **Virtual scrolling** - Handle massive datasets efficiently
+- **Memory optimization** - Minimize DOM elements and memory usage
+- **Intelligent loading** - Load data on-demand based on viewport
+- **Caching strategies** - Cache measured sizes and loaded data
+
+## 📋 List Manager System
+
+### Core Components
+- **Viewport**: Virtual scrolling and item positioning
+- **Collection**: Data loading and state management
+- **Item Size Manager**: Dynamic size calculation and caching
+- **Scrolling Manager**: Custom scrollbar and scroll handling
+
+### Usage Pattern
+```typescript
+import { createListManager } from 'mtrl-addons/core/list-manager';
+
+const listManager = createListManager({
+  collection: {
+    loadData: async (range) => fetchItems(range),
+    totalItems: 100000,
+    cacheSize: 1000
+  },
+  viewport: {
+    orientation: 'vertical',
+    estimatedItemSize: 60,
+    overscan: 5
+  }
+});
+```
+
+### Event System
+- **Data Loading**: `range:loaded`, `items:set`, `total:changed`
+- **Viewport Changes**: `viewport:changed`, `range:rendered`
+- **Performance**: `estimated-size:changed`, `dimensions:changed`
+
+## 🎨 Styling System
+
+### SCSS Architecture
+- **Extends mtrl styles** - Build on core style system
+- **BEM naming** - `mtrl-addon-component__element--modifier`
+- **Performance CSS** - Optimize for virtual scrolling
+
+### Virtual Scrolling Styles
+```scss
+.mtrl-list-manager {
+  &__viewport {
+    overflow: hidden;
+    position: relative;
+  }
+  
+  &__items {
+    position: absolute;
+    top: 0;
+    left: 0;
+  }
+  
+  &__scrollbar {
+    // Custom scrollbar styles
+  }
+}
+```
+
+## 🧪 Testing Strategy
+
+### Test Focus Areas
+- **Performance testing** - Measure virtual scrolling performance
+- **Data loading** - Test collection loading strategies
+- **Memory usage** - Monitor DOM element creation/destruction
+- **Viewport calculations** - Test range calculations and positioning
+
+### Test Structure
+```typescript
+// test/core/list-manager/list-manager.test.ts
+describe('ListManager', () => {
+  it('should handle large datasets efficiently', () => {
+    // Performance test
+  });
+  
+  it('should load data on demand', () => {
+    // Data loading test
+  });
+});
+```
+
+### Mock Strategies
+- **Mock data sources** - Simulate large datasets
+- **Mock viewport** - Test different container sizes
+- **Mock collection** - Test data loading patterns
+
+## 🚀 Common Development Tasks
+
+### Adding New List Manager Features
+1. **Create feature module** in `src/core/list-manager/features/`
+2. **Follow enhancement pattern** - Use functional composition
+3. **Add event handling** - Integrate with event system
+4. **Test performance** - Ensure no performance regression
+
+### Extending Collection System
+1. **Add to collection features** in `src/core/collection/features/`
+2. **Maintain cache efficiency** - Don't break caching strategies
+3. **Handle edge cases** - Empty datasets, loading failures
+4. **Test data integrity** - Ensure data consistency
+
+### Performance Optimization
+1. **Profile virtual scrolling** - Use browser dev tools
+2. **Minimize DOM operations** - Batch updates when possible
+3. **Optimize calculations** - Cache expensive computations
+4. **Monitor memory usage** - Prevent memory leaks
+
+## 📊 Performance Benchmarks
+
+### Target Metrics
+- **Initial render**: < 100ms for 1000+ items
+- **Scroll performance**: 60 FPS during scrolling
+- **Memory usage**: < 50MB for 100k items
+- **Data loading**: < 200ms for range requests
+
+### Monitoring Tools
+- **Performance tests** in `test/benchmarks/`
+- **Memory profiling** with browser dev tools
+- **Scroll performance** measurement utilities
+
+## 🔧 Integration with mtrl-app
+
+### Showcases
+- **Create showcases** in `mtrl-app/client/content/components/`
+- **Use layout schema** - Demonstrate declarative UI
+- **Performance demos** - Show large dataset handling
+- **Real-world examples** - Practical use cases
+
+### Documentation
+- **API documentation** in `mtrl-app/docs/`
+- **Performance guides** - Optimization strategies
+- **Integration examples** - How to use with mtrl core
+
+## 🐛 Common Issues & Solutions
+
+### Performance Issues
+- **Too many DOM elements** - Increase virtual scrolling efficiency
+- **Memory leaks** - Check event listener cleanup
+- **Slow scrolling** - Optimize item positioning calculations
+
+### Data Loading Issues
+- **Loading loops** - Check range calculation logic
+- **Missing data** - Verify collection loading strategies
+- **Inconsistent state** - Review event handling order
+
+### Integration Issues
+- **Component composition** - Ensure proper enhancement order
+- **Event conflicts** - Check event listener priorities
+- **Style conflicts** - Verify CSS specificity
+
+## 📚 Key Files Reference
+
+### Core Systems
+- `src/core/list-manager/list-manager.ts` - Main list manager
+- `src/core/collection/collection.ts` - Collection management
+- `src/core/layout/schema.ts` - Layout schema system
+
+### Features
+- `src/core/list-manager/features/viewport/` - Virtual scrolling
+- `src/core/collection/features/` - Collection features
+- `src/core/compose/features/` - Composition utilities
+
+### Tests
+- `test/core/list-manager/` - List manager tests
+- `test/benchmarks/` - Performance benchmarks
+- `test/components/` - Component integration tests
+
+---
+
+This guide focuses specifically on mtrl-addons development. For core mtrl development, see `mtrl/CLAUDE.md`. For showcase and documentation, see `mtrl-app/CLAUDE.md`.

package/build.js

@@ -0,0 +1,148 @@
+// build.js
+import { mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const isWatch = process.argv.includes("--watch");
+const isProduction =
+  process.argv.includes("--production") ||
+  process.env.NODE_ENV === "production";
+
+// Define consistent output paths
+const DIST_DIR = join(__dirname, "dist");
+const JS_OUTPUT = join(DIST_DIR, "index.js");
+const MJS_OUTPUT = join(DIST_DIR, "index.mjs");
+
+// Log build mode
+console.log(`Building in ${isProduction ? "PRODUCTION" : "DEVELOPMENT"} mode`);
+
+const buildApp = async () => {
+  try {
+    console.log("┌─────────────────────────────────────────");
+    console.log("│ JavaScript Build");
+    console.log("│ Mode:", isProduction ? "PRODUCTION" : "DEVELOPMENT");
+    console.log("│ Minify:", isProduction ? "Yes" : "No");
+    console.log("│ Sourcemaps:", isProduction ? "No" : "Yes (inline)");
+    console.log("└─────────────────────────────────────────");
+
+    // Create dist directory if it doesn't exist
+    await mkdir(DIST_DIR, { recursive: true });
+
+    // Build CJS version
+    const cjsResult = await Bun.build({
+      entrypoints: [join(__dirname, "src/index.ts")],
+      outdir: DIST_DIR,
+      minify: isProduction,
+      sourcemap: isProduction ? "none" : "inline",
+      format: "cjs",
+      target: "node",
+      external: ["mtrl"],
+    });
+
+    // Build ESM version
+    const esmResult = await Bun.build({
+      entrypoints: [join(__dirname, "src/index.ts")],
+      outdir: DIST_DIR,
+      minify: isProduction,
+      sourcemap: isProduction ? "none" : "inline",
+      format: "esm",
+      target: "node",
+      naming: {
+        entry: "index.mjs",
+      },
+      external: ["mtrl"],
+    });
+
+    if (!cjsResult.success || !esmResult.success) {
+      console.error("❌ JavaScript build failed");
+      console.error(cjsResult.logs);
+      console.error(esmResult.logs);
+      return false;
+    }
+
+    console.log("✓ JavaScript build successful");
+    console.log(
+      `  CJS bundle: ${((await Bun.file(JS_OUTPUT).size) / 1024).toFixed(2)} KB`
+    );
+    console.log(
+      `  ESM bundle: ${((await Bun.file(MJS_OUTPUT).size) / 1024).toFixed(
+        2
+      )} KB`
+    );
+
+    // Generate type definitions
+    console.log("Generating TypeScript declarations...");
+    const tscProcess = Bun.spawn(["tsc", "--project", "tsconfig.build.json"], {
+      cwd: __dirname,
+    });
+
+    const tscExitCode = await tscProcess.exited;
+    if (tscExitCode !== 0) {
+      console.error("❌ TypeScript declaration generation failed");
+      // Check if declaration files were actually generated despite errors
+      const declarationFile = join(DIST_DIR, "index.d.ts");
+      if (existsSync(declarationFile)) {
+        console.log("⚠️ Declaration files were generated despite errors");
+        return true;
+      }
+      return false;
+    }
+
+    console.log("✓ TypeScript declarations generated");
+    return true;
+  } catch (error) {
+    console.error("❌ JavaScript build error:", error);
+    console.error(error.stack);
+    return false;
+  }
+};
+
+const build = async () => {
+  try {
+    const startTime = Date.now();
+
+    console.log("┌───────────────────────────────────────────────");
+    console.log("│ 🚀 MTRL-Addons Build Process");
+    console.log("│ Mode:", isProduction ? "🏭 PRODUCTION" : "🔧 DEVELOPMENT");
+    console.log("│ Watch:", isWatch ? "✓ Enabled" : "✗ Disabled");
+    console.log("└───────────────────────────────────────────────");
+    console.log("");
+
+    // Create output directory
+    await mkdir(DIST_DIR, { recursive: true });
+
+    // Build JavaScript
+    const jsSuccess = await buildApp();
+
+    const buildTime = ((Date.now() - startTime) / 1000).toFixed(2);
+
+    if (isWatch && !isProduction) {
+      console.log("");
+      console.log("┌───────────────────────────────────────────────");
+      console.log("│ 👀 Watching for changes...");
+      console.log("└───────────────────────────────────────────────");
+
+      // Watch implementation would go here
+    } else {
+      console.log("");
+      console.log("┌───────────────────────────────────────────────");
+      console.log(`│ ✅ Build completed in ${buildTime}s`);
+      if (!jsSuccess) {
+        console.log("│ ⚠️ Build completed with some errors");
+      }
+      console.log("└───────────────────────────────────────────────");
+
+      // Only exit with error code in non-watch mode if there were failures
+      if (!isWatch && !jsSuccess) {
+        process.exit(1);
+      }
+    }
+  } catch (error) {
+    console.error("❌ Build failed with error:", error);
+    process.exit(1);
+  }
+};
+
+build();