mtrl-addons 0.5.6 → 0.7.0

package/README.md

@@ -1,32 +1,592 @@
 # mtrl-addons
 
-Additional components and utilities for the mtrl library, featuring specialized elements, and extended functionality for modern applications.
+> Extended components and utilities for the [mtrl](https://github.com/nicholasgriffintn/mtrl) Material Design 3 component library
+
+mtrl-addons provides high-performance, specialized components and core systems that extend mtrl's capabilities for building modern web applications. Built with the same functional composition philosophy and zero external dependencies (except mtrl as a peer dependency).
+
+## Features
+
+- 🚀 **Virtual Scrolling** - Handle millions of items with smooth 60fps scrolling
+- 📝 **Form Builder** - Declarative form creation with validation and state management
+- 🎨 **Color Picker** - Full-featured HSV picker with swatches, pipette, and variants
+- 📐 **Layout System** - Flexible array-based layout schemas with JSX support
+- 👆 **Gesture Recognition** - Touch and mouse gesture detection (tap, swipe, pinch, etc.)
+- 🎯 **Viewport System** - Composable virtual scrolling foundation
+- 🌳 **Tree-Shaking Optimized** - Import only what you need
 
 ## Installation
 
 ```bash
-npm install mtrl-addons
+# npm
+npm install mtrl-addons mtrl
+
+# yarn
+yarn add mtrl-addons mtrl
+
+# bun
+bun add mtrl-addons mtrl
+```
+
+## Quick Start
+
+```javascript
+import { createVList, createForm, createColorPicker } from 'mtrl-addons';
+```
+
+## Tree-Shaking Optimized Imports
+
+mtrl-addons is optimized for tree-shaking. Constants are exported separately from component creators to minimize bundle size.
+
+### Import Patterns
+
+| Import Type | Path |
+|-------------|------|
+| Component creators | `import { createColorPicker } from 'mtrl-addons'` |
+| ColorPicker constants | `import { COLORPICKER_EVENTS } from 'mtrl-addons/components/colorpicker/constants'` |
+| Form constants | `import { FORM_EVENTS, DATA_STATE } from 'mtrl-addons/components/form/constants'` |
+| VList constants | `import { VLIST_CLASSES } from 'mtrl-addons/components/vlist/constants'` |
+| Color utilities | `import { hsvToRgb, rgbToHex } from 'mtrl-addons'` |
+| Layout system | `import { createLayout } from 'mtrl-addons/layout'` |
+| Viewport system | `import { createViewport } from 'mtrl-addons/viewport'` |
+| Gestures | `import { createGestureManager } from 'mtrl-addons/gestures'` |
+
+---
+
+## Components
+
+### VList (Virtual List)
+
+High-performance virtual scrolling list for large datasets. Renders only visible items while maintaining smooth scrolling with millions of rows.
+
+#### Features
+- 📊 Handles 100,000+ items efficiently
+- 🔍 Built-in search with debouncing
+- 🎛️ Filter panel integration
+- ⌨️ Keyboard navigation
+- 📍 Scroll position restoration
+- 🎯 Item selection (single/multi)
+- 📈 Stats tracking (render time, visible items)
+- ⚡ Velocity-based scroll optimization
+
+#### Basic Usage
+
+```javascript
+import { createVList } from 'mtrl-addons';
+
+const vlist = createVList({
+  container: '#my-list',
+  template: (item) => ({
+    class: 'list-item',
+    children: [
+      { tag: 'span', class: 'name', text: item.name },
+      { tag: 'span', class: 'email', text: item.email }
+    ]
+  }),
+  collection: {
+    adapter: {
+      read: async ({ page, limit }) => {
+        const response = await fetch(`/api/users?page=${page}&limit=${limit}`);
+        return response.json();
+      }
+    }
+  }
+});
+```
+
+#### With Layout, Search & Filters
+
+```javascript
+import { createVList } from 'mtrl-addons';
+import { createIconButton, createSearch, createSelect } from 'mtrl';
+
+const vlist = createVList({
+  container: '#users-list',
+  class: 'users',
+  
+  // Layout schema - declarative UI structure
+  layout: [
+    ['head', { class: 'list-head' },
+      [createIconButton, 'searchBtn', { icon: iconSearch, toggle: true }],
+      [createIconButton, 'filterBtn', { icon: iconFilter, toggle: true }]
+    ],
+    ['filter-panel', { class: 'filter-panel' },
+      [createSelect, 'country', { label: 'Country', options: countries }],
+      [createSelect, 'role', { label: 'Role', options: roles }]
+    ],
+    [createSearch, 'searchBar', { placeholder: 'Search users...' }],
+    ['viewport'], // Virtual scrolling area
+    ['foot', { class: 'list-foot' },
+      ['stats', { text: 'Loading...' }]
+    ]
+  ],
+  
+  // Search configuration
+  search: {
+    toggleButton: 'searchBtn',
+    searchBar: 'searchBar',
+    debounce: 300
+  },
+  
+  // Filter configuration
+  filter: {
+    toggleButton: 'filterBtn',
+    panel: 'filter-panel',
+    controls: {
+      country: 'country',
+      role: 'role'
+    }
+  },
+  
+  // Stats display
+  stats: {
+    element: 'stats',
+    format: ({ total, rendered }) => `${rendered} of ${total} users`
+  },
+  
+  template: userTemplate,
+  collection: {
+    adapter: {
+      read: async ({ page, limit, search, filters }) => {
+        // search and filters are automatically populated
+        return fetchUsers({ page, limit, search, ...filters });
+      }
+    }
+  }
+});
+
+// Events
+vlist.on('search:change', ({ query }) => console.log('Search:', query));
+vlist.on('filter:change', ({ filters }) => console.log('Filters:', filters));
+vlist.on('item:select', ({ item }) => console.log('Selected:', item));
+
+// API
+vlist.search('john');
+vlist.setFilter('country', 'US');
+vlist.scrollToIndex(50);
+vlist.refresh();
+```
+
+---
+
+### Form
+
+Functional form builder with declarative field configuration, validation, and state management.
+
+#### Features
+- 📋 Declarative field definitions
+- ✅ Built-in validation rules
+- 🔄 Dirty/pristine state tracking
+- 🛡️ Unsaved changes protection
+- 📤 Submit handling with loading states
+- 🎯 Field-level error handling
+
+#### Basic Usage
+
+```javascript
+import { createForm } from 'mtrl-addons';
+import { FORM_EVENTS, DATA_STATE } from 'mtrl-addons/components/form/constants';
+
+const form = createForm({
+  fields: [
+    { name: 'email', type: 'email', label: 'Email', required: true },
+    { name: 'password', type: 'password', label: 'Password', required: true },
+    { name: 'remember', type: 'checkbox', label: 'Remember me' }
+  ],
+  
+  // Protect unsaved changes
+  protectChanges: {
+    beforeUnload: true,      // Warn on page close
+    onDataOverwrite: true    // Emit event when setData() called with changes
+  },
+  
+  onSubmit: async (data) => {
+    await api.login(data);
+  }
+});
+
+// Mount to container
+document.getElementById('login-form').appendChild(form.element);
+
+// Events
+form.on(FORM_EVENTS.CHANGE, ({ field, value }) => {
+  console.log(`${field} changed to:`, value);
+});
+
+form.on(FORM_EVENTS.STATE_CHANGE, ({ state }) => {
+  if (state === DATA_STATE.DIRTY) {
+    console.log('Form has unsaved changes');
+  }
+});
+
+form.on(FORM_EVENTS.SUBMIT, (data) => {
+  console.log('Form submitted:', data);
+});
+
+form.on(FORM_EVENTS.DATA_CONFLICT, ({ currentData, newData, cancel, proceed }) => {
+  if (confirm('Discard unsaved changes?')) {
+    proceed();
+  } else {
+    cancel();
+  }
+});
+
+// API
+form.setData({ email: 'user@example.com' });
+const data = form.getData();
+const isValid = form.validate();
+form.reset();
+form.disable();
+form.enable();
 ```
 
-## Usage
+---
+
+### ColorPicker
+
+Full-featured color picker with HSV color area, hue slider, swatches, and multiple display variants.
+
+#### Features
+- 🎨 HSV color area with saturation/brightness
+- 📊 Hue slider
+- 🔲 Opacity/alpha slider (optional)
+- 💎 Color swatches with add/remove
+- 💉 Pipette/eyedropper (native API or canvas sampling)
+- 📝 Hex input field
+- 🖼️ Multiple variants: inline, dropdown, dialog
+- 📱 Compact density mode
+
+#### Basic Usage
 
 ```javascript
-import { version } from 'mtrl-addons';
+import { createColorPicker } from 'mtrl-addons';
+import { COLORPICKER_EVENTS, COLORPICKER_VARIANTS } from 'mtrl-addons/components/colorpicker/constants';
+
+// Inline picker (always visible)
+const picker = createColorPicker({
+  value: '#6200ee',
+  showSwatches: true,
+  swatches: ['#ff0000', '#00ff00', '#0000ff', '#ffff00', '#ff00ff', '#00ffff']
+});
+
+document.getElementById('color-picker').appendChild(picker.element);
+
+// Events
+picker.on(COLORPICKER_EVENTS.CHANGE, ({ value }) => {
+  console.log('Color selected:', value);
+});
+
+picker.on(COLORPICKER_EVENTS.INPUT, ({ value }) => {
+  // Live preview during drag
+  document.body.style.backgroundColor = value;
+});
+
+// API
+picker.setValue('#ff5722');
+const hex = picker.getValue();        // '#ff5722'
+const hsv = picker.getHSV();          // { h: 14, s: 86, v: 100 }
+const rgb = picker.getRGB();          // { r: 255, g: 87, b: 34 }
+
+picker.addSwatch('#9c27b0', 'Purple');
+picker.setOpacity(0.5);
 ```
 
+#### Dropdown Variant
+
+```javascript
+const trigger = document.getElementById('color-button');
+
+const picker = createColorPicker({
+  value: '#6200ee',
+  variant: COLORPICKER_VARIANTS.DROPDOWN,
+  trigger: trigger,
+  closeOnSelect: true
+});
+
+// Toggle programmatically
+picker.open();
+picker.close();
+picker.toggle();
+```
+
+#### With Pipette (Color Sampling)
+
+```javascript
+const picker = createColorPicker({
+  value: '#ffffff',
+  showPipette: true,
+  // Optional: provide image for canvas-based sampling
+  imageSource: document.getElementById('my-image'),
+  
+  onPipetteStart: () => console.log('Sampling started'),
+  onPipetteEnd: (color) => console.log('Picked:', color)
+});
+
+// Trigger programmatically
+const pickedColor = await picker.pickColor();
+```
+
+---
+
+## Core Systems
+
+### Layout System
+
+Flexible array-based layout schemas for declarative UI construction. Supports mtrl components, HTML elements, and nested structures.
+
+```javascript
+import { createLayout } from 'mtrl-addons/layout';
+import { createButton, createTextField } from 'mtrl';
+
+// Array-based schema
+const layout = createLayout([
+  'div', { class: 'form-container' },
+  [
+    ['header', { class: 'form-header' },
+      ['h2', { text: 'Contact Form' }]
+    ],
+    ['main', { class: 'form-body' },
+      [createTextField, 'name', { label: 'Name' }],
+      [createTextField, 'email', { label: 'Email', type: 'email' }],
+      [createTextField, 'message', { label: 'Message', multiline: true }]
+    ],
+    ['footer', { class: 'form-footer' },
+      [createButton, 'submit', { text: 'Send', variant: 'filled' }],
+      [createButton, 'cancel', { text: 'Cancel', variant: 'outlined' }]
+    ]
+  ]
+]);
+
+// Access named components
+layout.name.setValue('John Doe');
+layout.submit.on('click', handleSubmit);
+
+// Append to DOM
+document.body.appendChild(layout.element);
+```
+
+#### Convenience Functions
+
+```javascript
+import { layout, row, stack, grid } from 'mtrl-addons/layout';
+
+// Vertical stack
+const stackLayout = stack({ gap: '1rem' });
+
+// Horizontal row (mobile-stacks automatically)
+const rowLayout = row({ gap: '1rem', mobileStack: true });
+
+// Responsive grid
+const gridLayout = grid('auto-fit', { gap: '1rem' });
+```
+
+---
+
+### Viewport System
+
+Low-level composable virtual scrolling foundation. Used internally by VList but available for custom implementations.
+
+```javascript
+import { createViewport } from 'mtrl-addons/viewport';
+
+const viewport = createViewport({
+  container: document.getElementById('scroll-container'),
+  itemCount: 100000,
+  estimatedItemSize: 48,
+  overscan: 5, // Extra items to render outside viewport
+  
+  renderItem: (index) => {
+    const div = document.createElement('div');
+    div.textContent = `Item ${index}`;
+    return div;
+  },
+  
+  onRangeChange: ({ start, end }) => {
+    console.log(`Rendering items ${start} to ${end}`);
+  }
+});
+
+// API
+viewport.scrollToIndex(500);
+viewport.refresh();
+viewport.destroy();
+```
+
+#### Feature Composition
+
+```javascript
+import { 
+  withBase, 
+  withVirtual, 
+  withScrolling, 
+  withRendering 
+} from 'mtrl-addons/viewport';
+
+// Build custom viewport with specific features
+const customViewport = pipe(
+  withBase,
+  withVirtual,
+  withScrolling,
+  withRendering
+)(config);
+```
+
+---
+
+### Gesture System
+
+Touch and mouse gesture recognition with support for tap, swipe, long-press, pinch, rotate, and pan.
+
+```javascript
+import { createGestureManager } from 'mtrl-addons/gestures';
+
+const gestures = createGestureManager(element, {
+  // Tap detection
+  onTap: ({ x, y, target }) => {
+    console.log('Tapped at', x, y);
+  },
+  
+  // Swipe detection
+  onSwipe: ({ direction, velocity, distance }) => {
+    console.log(`Swiped ${direction} with velocity ${velocity}`);
+  },
+  
+  // Long press
+  onLongPress: ({ x, y, duration }) => {
+    console.log('Long pressed for', duration, 'ms');
+  },
+  
+  // Pinch (zoom)
+  onPinch: ({ scale, center }) => {
+    element.style.transform = `scale(${scale})`;
+  },
+  
+  // Rotation
+  onRotate: ({ angle, center }) => {
+    element.style.transform = `rotate(${angle}deg)`;
+  },
+  
+  // Pan (drag)
+  onPan: ({ deltaX, deltaY, state }) => {
+    if (state === 'move') {
+      element.style.transform = `translate(${deltaX}px, ${deltaY}px)`;
+    }
+  }
+});
+
+// Configuration
+const gestures = createGestureManager(element, {
+  tap: { maxDuration: 300 },
+  swipe: { minDistance: 50, minVelocity: 0.3 },
+  longPress: { duration: 500 },
+  pinch: { minScale: 0.5, maxScale: 3 }
+});
+
+// Cleanup
+gestures.destroy();
+```
+
+#### Individual Gesture Detectors
+
+```javascript
+import { detectTap, detectSwipe, detectPinch } from 'mtrl-addons/gestures';
+
+// Use specific detectors for lighter bundles
+const tapDetector = detectTap(element, { onTap: handleTap });
+const swipeDetector = detectSwipe(element, { onSwipe: handleSwipe });
+```
+
+---
+
+## Color Utilities
+
+Pure functions for color conversion (tree-shakeable, included in main bundle).
+
+```javascript
+import {
+  hsvToRgb,
+  rgbToHsv,
+  hsvToHex,
+  hexToHsv,
+  rgbToHex,
+  hexToRgb,
+  isValidHex,
+  normalizeHex,
+  getContrastColor
+} from 'mtrl-addons';
+
+// HSV ↔ RGB
+const rgb = hsvToRgb({ h: 200, s: 80, v: 90 }); // { r: 46, g: 184, b: 230 }
+const hsv = rgbToHsv({ r: 255, g: 128, b: 0 }); // { h: 30, s: 100, v: 100 }
+
+// Hex conversions
+const hex = rgbToHex({ r: 255, g: 0, b: 128 }); // '#ff0080'
+const rgb2 = hexToRgb('#ff0080'); // { r: 255, g: 0, b: 128 }
+
+// Validation & normalization
+isValidHex('#ff0080');      // true
+isValidHex('ff0080');       // true
+normalizeHex('f00');        // '#ff0000'
+normalizeHex('#F00');       // '#ff0000'
+
+// Contrast color (for text on colored backgrounds)
+getContrastColor('#ffffff'); // '#000000'
+getContrastColor('#000000'); // '#ffffff'
+```
+
+---
+
 ## Development
 
 ```bash
 # Install dependencies
 bun install
 
-# Build
+# Build package (for distribution)
 bun run build
 
-# Test
+# Build for mtrl-app integration
+bun run build:app
+
+# Run tests
 bun test
+
+# Watch mode
+bun run dev
+
+# Link mtrl for local development
+bun run link:mtrl
 ```
 
+## Browser Support
+
+mtrl-addons supports modern browsers:
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Peer Dependencies
+
+- `mtrl` ^0.6.2 - Core Material Design 3 component library
+
+## Related Packages
+
+- [mtrl](https://github.com/floor/mtrl) - Core Material Design 3 component library
+- [mtrl-app](https://github.com/floor/mtrl-app) - Documentation and showcase application
+
 ## License
 
-MIT
+MIT
+
+## Contributing
+
+Contributions are welcome! Please follow the existing code style and include tests for new features.
+
+```bash
+# Run tests before submitting
+bun test
+
+# Build to verify no errors
+bun run build
+```

package/dist/components/form/features/fields.d.ts

@@ -24,20 +24,27 @@ export declare const getFieldValue: (field: FormField) => FieldValue;
  */
 export declare const setFieldValue: (field: FormField, value: FieldValue, silent?: boolean) => void;
 /**
- * Updates the tracked value for a field
- * Called when setData is used with silent=true to keep deduplication in sync
+ * Binds change and input events to fields
+ * Calls the provided callback when any field changes
+ *
+ * Listens to both 'input' (for immediate feedback while typing)
+ * and 'change' (for components that only emit on blur/selection)
+ *
+ * Deduplicates events to prevent double-firing when both input and change
+ * emit for the same value (e.g., textfield input followed by blur)
  */
-export declare const updateTrackedFieldValue: (name: string, value: FieldValue) => void;
 /**
- * Updates all tracked field values from a fields registry
- * Called after silent setData to sync deduplication state
+ * Updates the tracked value for a field in the given tracker
  */
-export declare const syncTrackedFieldValues: (fields: FormFieldRegistry) => void;
+export declare const updateTrackedFieldValue: (name: string, value: FieldValue, tracker?: Map<string, FieldValue>) => void;
 /**
- * Resets the field value tracker for a new form
- * Should be called at the start of withFields before bindFieldEvents
+ * Updates all tracked field values from a fields registry
+ * Called after silent setData to sync deduplication state
+ *
+ * @param fields - The form's field registry
+ * @param tracker - The per-form tracker map (stored on the component as _fieldValueTracker)
  */
-export declare const resetFieldValueTracker: () => void;
+export declare const syncTrackedFieldValues: (fields: FormFieldRegistry, tracker?: Map<string, FieldValue>) => void;
 /**
  * withFields feature
  * Adds field extraction and registry management to the form

package/dist/components/form/features/index.d.ts

@@ -3,7 +3,7 @@
  * Each feature adds specific capabilities to the form component
  */
 export { withLayout } from "./layout";
-export { withFields, getFieldValue, setFieldValue, updateTrackedFieldValue, syncTrackedFieldValues, resetFieldValueTracker, } from "./fields";
+export { withFields, getFieldValue, setFieldValue, updateTrackedFieldValue, syncTrackedFieldValues, } from "./fields";
 export { withData, flatToNested, getNestedValue, setNestedValue } from "./data";
 export { withController } from "./controller";
 export { withSubmit, validateData, performRequest } from "./submit";

package/dist/components/index.d.ts

@@ -1,14 +1,18 @@
 /**
  * Components Module Exports
  *
- * Central export point for all components
+ * Central export point for all components.
+ *
+ * NOTE: Constants are NOT exported here to enable tree-shaking.
+ * Import constants directly from the component's constants file:
+ *   import { COLORPICKER_EVENTS } from 'mtrl-addons/components/colorpicker/constants'
+ *   import { FORM_EVENTS } from 'mtrl-addons/components/form/constants'
+ *   import { VLIST_CLASSES } from 'mtrl-addons/components/vlist/constants'
  */
 export { createVList } from "./vlist";
 export type { VListConfig, VListComponent } from "./vlist/types";
 export { createForm } from "./form";
 export type { FormConfig, FormComponent, FormField, FormData, DataState, FormState, FormValidationRule, FormValidationResult, FormSubmitOptions, FormEventHandlers, FieldValue, SubmitHandler, CancelHandler, } from "./form/types";
-export { DATA_STATE, FORM_EVENTS, FORM_CLASSES, FORM_DEFAULTS, } from "./form/constants";
 export { createColorPicker } from "./colorpicker";
 export type { ColorPickerConfig, ColorPickerComponent, HSVColor, RGBColor, ColorSwatch, } from "./colorpicker/types";
-export { COLORPICKER_EVENTS, COLORPICKER_SIZES, COLORPICKER_VARIANTS, COLORPICKER_CLASSES, COLORPICKER_DEFAULTS, SWATCH_SIZES, PALETTE_SWATCH_ORDER, } from "./colorpicker/constants";
 export { hsvToRgb, rgbToHsv, hsvToHex, hexToHsv, rgbToHex, hexToRgb, isValidHex, normalizeHex, getContrastColor, } from "./colorpicker/utils";