mtrl 0.3.1 → 0.3.3

package/src/components/chips/chip/chip.ts

@@ -0,0 +1,131 @@
+// src/components/chips/chip/chip.ts
+import { PREFIX } from '../../../core/config';
+import { pipe } from '../../../core/compose';
+import { createBase, withElement } from '../../../core/compose/component';
+import {
+  withEvents,
+  withText,
+  withIcon,
+  withVariant,
+  withRipple,
+  withDisabled,
+  withLifecycle
+} from '../../../core/compose/features';
+import { withAPI } from './api';
+import { ChipConfig, ChipComponent } from '../types';
+import { createBaseConfig, getElementConfig, getApiConfig } from './config';
+
+/**
+ * Creates a new Chip component
+ * @param {ChipConfig} config - Chip configuration
+ * @returns {ChipComponent} Chip component instance
+ */
+const createChip = (config: ChipConfig = {}): ChipComponent => {
+  const baseConfig = createBaseConfig(config);
+
+  try {
+    // Create base component with core features
+    const chip = pipe(
+      createBase,
+      withEvents(),
+      withElement(getElementConfig(baseConfig)),
+      withVariant(baseConfig),
+      withDisabled(baseConfig),
+      withRipple(baseConfig),
+      withLifecycle()
+    )(baseConfig);
+    
+    // Create a container for the chip content to ensure proper ordering
+    const contentContainer = document.createElement('div');
+    contentContainer.className = `${chip.getClass('chip')}-content`;
+    contentContainer.style.display = 'flex';
+    contentContainer.style.alignItems = 'center';
+    contentContainer.style.gap = '8px';
+    contentContainer.style.width = '100%';
+    chip.element.appendChild(contentContainer);
+    
+    // Add leading icon if provided
+    if (config.leadingIcon || config.icon) {
+      const leadingIconElement = document.createElement('span');
+      leadingIconElement.className = `${chip.getClass('chip')}-leading-icon`;
+      leadingIconElement.innerHTML = config.leadingIcon || config.icon || '';
+      contentContainer.appendChild(leadingIconElement);
+    }
+
+    // Add text element if provided
+    if (config.text) {
+      const textElement = document.createElement('span');
+      textElement.className = `${chip.getClass('chip')}-text`;
+      textElement.textContent = config.text;
+      contentContainer.appendChild(textElement);
+    }
+
+    // Add trailing icon if provided
+    if (config.trailingIcon) {
+      const trailingIconElement = document.createElement('span');
+      trailingIconElement.className = `${chip.getClass('chip')}-trailing-icon`;
+      trailingIconElement.innerHTML = config.trailingIcon;
+      
+      // Add click handler for trailing icon
+      if (config.onTrailingIconClick) {
+        trailingIconElement.addEventListener('click', (e) => {
+          e.stopPropagation(); // Prevent chip click event
+          config.onTrailingIconClick(chip as unknown as ChipComponent);
+        });
+      }
+      
+      contentContainer.appendChild(trailingIconElement);
+    }
+    
+    // Add selected class if needed
+    if (config.selected) {
+      chip.element.classList.add(`${chip.getClass('chip')}--selected`);
+      chip.element.setAttribute('aria-selected', 'true');
+    }
+    
+    // Set data-value attribute if provided
+    if (config.value) {
+      chip.element.setAttribute('data-value', config.value);
+    }
+
+    // Add API methods to the component
+    const enhancedChip = withAPI(getApiConfig(chip))(chip);
+    
+    // Initialize value if not already set
+    if (!chip.element.hasAttribute('data-value') && config.text) {
+      enhancedChip.getValue(); // This will trigger the automatic value generation in our fixed API
+    }
+
+    // Add click handler for selection toggle
+    if (config.variant === 'filter' || 
+        config.variant === 'assist' ||
+        config.variant === 'suggestion' ||
+        config.selectable) {
+      
+      chip.element.addEventListener('click', () => {
+        if (enhancedChip.isDisabled()) return;
+        
+        const wasSelected = enhancedChip.isSelected();
+        enhancedChip.toggleSelected();
+        const isNowSelected = enhancedChip.isSelected();
+        
+        // Call onChange with correct parameters
+        if (config.onChange && wasSelected !== isNowSelected) {
+          config.onChange(isNowSelected, enhancedChip);
+        }
+        
+        // Call onSelect with consistent parameters
+        if (config.onSelect) {
+          config.onSelect(enhancedChip);
+        }
+      });
+    }
+
+    return enhancedChip as unknown as ChipComponent;
+  } catch (error) {
+    console.error('Chip creation error:', error);
+    throw new Error(`Failed to create chip: ${(error as Error).message}`);
+  }
+};
+
+export default createChip;

package/src/components/{chip → chips/chip}/config.ts

@@ -1,10 +1,10 @@
-// src/components/chip/config.ts
+// src/components/chips/chip/config.ts
 import { 
   createComponentConfig, 
   createElementConfig,
   BaseComponentConfig 
-} from '../../core/config/component-config';
-import { ChipConfig, BaseComponent } from './types';
+} from '../../../core/config/component-config';
+import { ChipConfig, BaseComponent } from '../types';
 
 /**
  * Default configuration for the Chip component

package/src/components/chips/chip/index.ts

@@ -0,0 +1,3 @@
+// src/components/chips/chip/index.ts
+export { default } from './chip';
+export * from './config';

package/src/components/chips/chips.md

@@ -0,0 +1,481 @@
+# MTRL Chips Component
+
+## Overview
+
+The Chips component is a lightweight, composable UI element used to represent discrete information, such as attributes, selections, filters, or user input. This TypeScript implementation provides a comprehensive API with zero dependencies, focusing on performance, accessibility, and extensibility.
+
+## Features
+
+- **Multiple Variants**: Filled, outlined, elevated, assist, filter, input, and suggestion chips
+- **Selection Support**: Single or multi-select modes with clear API for selection management
+- **Layout Options**: Horizontal or vertical arrangement with optional scrolling
+- **Icon Support**: Leading and trailing icons with customizable click handlers
+- **Keyboard Navigation**: Full accessibility support with keyboard controls
+- **Type Safety**: Comprehensive TypeScript interfaces for improved developer experience
+- **Zero Dependencies**: Built with vanilla TypeScript for minimal bundle size
+- **Composition-based Architecture**: Functional composition for extensibility
+- **Accessibility**: ARIA attributes and keyboard support built-in
+
+## Installation
+
+```bash
+# Using npm
+npm install mtrl
+
+# Using yarn
+yarn add mtrl
+
+# Using bun
+bun add mtrl
+```
+
+## Basic Usage
+
+### Single Chip
+
+```typescript
+import { createChip } from 'mtrl';
+
+// Create a basic chip
+const basicChip = createChip({
+  text: 'Basic Chip',
+  variant: 'filled'
+});
+
+// Add to DOM
+document.querySelector('.container').appendChild(basicChip.element);
+```
+
+### Chips Container
+
+```typescript
+import { createChips } from 'mtrl';
+
+// Create a chips container with multiple chips
+const filterChips = createChips({
+  multiSelect: true,
+  label: 'Categories',
+  chips: [
+    { text: 'JavaScript', variant: 'filter', value: 'js' },
+    { text: 'TypeScript', variant: 'filter', value: 'ts' },
+    { text: 'HTML', variant: 'filter', value: 'html' },
+    { text: 'CSS', variant: 'filter', value: 'css' }
+  ],
+  onChange: (selectedValues) => {
+    console.log('Selected categories:', selectedValues);
+  }
+});
+
+// Add to DOM
+document.querySelector('.filters').appendChild(filterChips.element);
+```
+
+## Component API
+
+### Chip Configuration
+
+```typescript
+interface ChipConfig {
+  variant?: 'filled' | 'outlined' | 'elevated' | 'assist' | 'filter' | 'input' | 'suggestion';
+  disabled?: boolean;
+  selected?: boolean;
+  text?: string;
+  icon?: string;
+  leadingIcon?: string;
+  trailingIcon?: string;
+  class?: string;
+  value?: string;
+  ripple?: boolean;
+  selectable?: boolean;
+  onTrailingIconClick?: (chip: ChipComponent) => void;
+  onSelect?: (chip: ChipComponent) => void;
+  onChange?: (selected: boolean, chip: ChipComponent) => void;
+}
+```
+
+### Chips Configuration
+
+```typescript
+interface ChipsConfig {
+  chips?: ChipConfig[];
+  scrollable?: boolean;
+  vertical?: boolean;
+  class?: string;
+  selector?: string | null;
+  multiSelect?: boolean;
+  onChange?: (selectedValues: (string | null)[], changedValue: string | null) => void;
+  label?: string;
+  labelPosition?: 'start' | 'end';
+}
+```
+
+### Chip Variants
+
+| Variant | Description |
+|---------|-------------|
+| `filled` | Standard chip with solid background color (default) |
+| `outlined` | Transparent background with outlined border |
+| `elevated` | Chip with subtle shadow effect |
+| `assist` | For suggesting actions to the user |
+| `filter` | For filtering content with selection behavior |
+| `input` | Represents user input in form fields |
+| `suggestion` | For presenting options and suggestions |
+
+## Chip API Methods
+
+### Content Management
+
+| Method | Description |
+|--------|-------------|
+| `setText(content)` | Sets the chip's text content |
+| `getText()` | Gets the chip's text content |
+| `setIcon(html)` | Sets the chip's leading icon |
+| `getIcon()` | Gets the chip's leading icon HTML |
+| `setLeadingIcon(html)` | Sets the chip's leading icon |
+| `setTrailingIcon(html, onClick?)` | Sets the chip's trailing icon with optional click handler |
+
+### State Management
+
+| Method | Description |
+|--------|-------------|
+| `setValue(value)` | Sets the chip's value attribute |
+| `getValue()` | Gets the chip's value attribute |
+| `isSelected()` | Checks if the chip is selected |
+| `setSelected(selected)` | Sets the chip's selected state |
+| `toggleSelected()` | Toggles the chip's selected state |
+| `isDisabled()` | Checks if the chip is disabled |
+| `enable()` | Enables the chip |
+| `disable()` | Disables the chip |
+
+### Event Handling
+
+| Method | Description |
+|--------|-------------|
+| `on(event, handler)` | Adds an event listener |
+| `off(event, handler)` | Removes an event listener |
+
+### Lifecycle
+
+| Method | Description |
+|--------|-------------|
+| `destroy()` | Cleans up the chip and removes it from the DOM |
+
+## Chips Container API Methods
+
+### Chip Management
+
+| Method | Description |
+|--------|-------------|
+| `addChip(chipConfig)` | Adds a new chip to the container |
+| `removeChip(chipOrIndex)` | Removes a chip by instance or index |
+| `getChips()` | Gets all chip instances |
+| `scrollToChip(chipOrIndex)` | Scrolls to make a specific chip visible |
+
+### Selection Management
+
+| Method | Description |
+|--------|-------------|
+| `getSelectedChips()` | Gets currently selected chip instances |
+| `getSelectedValues()` | Gets values of selected chips |
+| `selectByValue(values, triggerEvent?)` | Selects chips by their values |
+| `clearSelection()` | Clears all selections |
+
+### Layout Management
+
+| Method | Description |
+|--------|-------------|
+| `setScrollable(isScrollable)` | Sets the scrollable state |
+| `setVertical(isVertical)` | Sets the vertical layout state |
+
+### Label Management
+
+| Method | Description |
+|--------|-------------|
+| `setLabel(text)` | Sets the label text |
+| `getLabel()` | Gets the label text |
+| `setLabelPosition(position)` | Sets the label position ('start' or 'end') |
+| `getLabelPosition()` | Gets the label position |
+
+### Other Methods
+
+| Method | Description |
+|--------|-------------|
+| `enableKeyboardNavigation()` | Enables keyboard navigation between chips |
+| `on(event, handler)` | Adds an event listener |
+| `off(event, handler)` | Removes an event listener |
+| `destroy()` | Destroys the chips container and all contained chips |
+
+## Events
+
+### Chip Events
+
+| Event | Description |
+|-------|-------------|
+| `change` | Fired when chip selection state changes |
+| `select` | Fired when a chip is selected |
+| `deselect` | Fired when a chip is deselected |
+| `remove` | Fired when a chip is about to be removed |
+
+### Chips Container Events
+
+| Event | Description |
+|-------|-------------|
+| `change` | Fired when any chip selection changes |
+| `add` | Fired when a chip is added to the container |
+| `remove` | Fired when a chip is removed from the container |
+
+## Advanced Examples
+
+### Filter Chips with Icons
+
+```typescript
+import { createChips } from 'mtrl';
+
+const filterChips = createChips({
+  multiSelect: true,
+  scrollable: true,
+  label: 'Filter by:',
+  chips: [
+    { 
+      text: 'Completed', 
+      variant: 'filter',
+      value: 'completed',
+      leadingIcon: '<svg viewBox="0 0 24 24" width="18" height="18"><path fill="currentColor" d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"/></svg>'
+    },
+    { 
+      text: 'In Progress', 
+      variant: 'filter',
+      value: 'in-progress',
+      leadingIcon: '<svg viewBox="0 0 24 24" width="18" height="18"><path fill="currentColor" d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8z"/><path fill="currentColor" d="M12 5v7l5 5-1.41 1.41L10.59 13H7V11h3.59l3-3H12z"/></svg>'
+    },
+    { 
+      text: 'Pending', 
+      variant: 'filter',
+      value: 'pending',
+      leadingIcon: '<svg viewBox="0 0 24 24" width="18" height="18"><path fill="currentColor" d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8z"/><path fill="currentColor" d="M7 12h10v2H7z"/></svg>'
+    }
+  ],
+  onChange: (selectedValues) => {
+    console.log('Selected filters:', selectedValues);
+    updateTaskList(selectedValues);
+  }
+});
+
+document.querySelector('.filters-container').appendChild(filterChips.element);
+
+// Pre-select certain values
+filterChips.selectByValue(['completed', 'in-progress']);
+```
+
+### Input Chips for Email Tags
+
+```typescript
+import { createChips } from 'mtrl';
+
+const emailChips = createChips({
+  chips: [],
+  label: 'Recipients:',
+  onChange: (values) => {
+    document.querySelector('#recipients-input').value = values.join(',');
+  }
+});
+
+// Add to form
+const emailForm = document.querySelector('.email-form');
+emailForm.insertBefore(emailChips.element, emailForm.firstChild);
+
+// Handle input for adding emails
+const input = document.querySelector('#email-input');
+input.addEventListener('keydown', (e) => {
+  if (e.key === 'Enter' || e.key === ',') {
+    e.preventDefault();
+    
+    const email = input.value.trim().replace(',', '');
+    if (validateEmail(email)) {
+      emailChips.addChip({
+        text: email,
+        variant: 'input',
+        value: email,
+        trailingIcon: '<svg viewBox="0 0 24 24" width="18" height="18"><path fill="currentColor" d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>',
+        onTrailingIconClick: (chip) => {
+          emailChips.removeChip(chip);
+        }
+      });
+      input.value = '';
+    }
+  }
+});
+
+function validateEmail(email) {
+  return /\S+@\S+\.\S+/.test(email);
+}
+```
+
+### Theme Selector with Single Selection
+
+```typescript
+import { createChips } from 'mtrl';
+
+const themeChips = createChips({
+  multiSelect: false, // Single selection mode
+  label: 'Select theme:',
+  chips: [
+    { 
+      text: 'Light Theme', 
+      variant: 'filter', 
+      value: 'light',
+      selected: true // Pre-select Light theme
+    },
+    { 
+      text: 'Dark Theme', 
+      variant: 'filter', 
+      value: 'dark' 
+    },
+    { 
+      text: 'System Theme', 
+      variant: 'filter', 
+      value: 'system' 
+    }
+  ],
+  onChange: (selectedValues) => {
+    if (selectedValues.length > 0) {
+      applyTheme(selectedValues[0]);
+    }
+  }
+});
+
+document.querySelector('.theme-settings').appendChild(themeChips.element);
+
+function applyTheme(theme) {
+  document.documentElement.setAttribute('data-theme', theme);
+  localStorage.setItem('theme', theme);
+}
+```
+
+### Vertical Layout with Category Groups
+
+```typescript
+import { createChips } from 'mtrl';
+
+const categoryChips = createChips({
+  vertical: true,
+  multiSelect: true,
+  label: 'Categories:',
+  labelPosition: 'start',
+  chips: [
+    { text: 'Technology', variant: 'filter', value: 'tech' },
+    { text: 'Science', variant: 'filter', value: 'science' },
+    { text: 'Health', variant: 'filter', value: 'health' },
+    { text: 'Business', variant: 'filter', value: 'business' },
+    { text: 'Entertainment', variant: 'filter', value: 'entertainment' },
+    { text: 'Sports', variant: 'filter', value: 'sports' },
+    { text: 'Politics', variant: 'filter', value: 'politics' },
+    { text: 'Travel', variant: 'filter', value: 'travel' }
+  ],
+  onChange: (selectedValues) => {
+    updateArticlesList(selectedValues);
+  }
+});
+
+document.querySelector('.sidebar-filters').appendChild(categoryChips.element);
+```
+
+### Dynamic Chip Creation and Removal
+
+```typescript
+import { createChips } from 'mtrl';
+
+// Create empty chips container
+const dynamicChips = createChips({
+  scrollable: true,
+  label: 'Tags:',
+  onChange: (selectedValues) => {
+    console.log('Selected tags:', selectedValues);
+  }
+});
+
+document.querySelector('.tags-container').appendChild(dynamicChips.element);
+
+// Add new tag button
+document.querySelector('#add-tag').addEventListener('click', () => {
+  const tagInput = document.querySelector('#tag-input');
+  const tagText = tagInput.value.trim();
+  
+  if (tagText) {
+    dynamicChips.addChip({
+      text: tagText,
+      variant: 'input',
+      value: tagText.toLowerCase().replace(/\s+/g, '-'),
+      trailingIcon: '<svg viewBox="0 0 24 24" width="16" height="16"><path fill="currentColor" d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>',
+      onTrailingIconClick: (chip) => {
+        if (confirm(`Remove tag "${chip.getText()}"?`)) {
+          dynamicChips.removeChip(chip);
+        }
+      }
+    });
+    
+    tagInput.value = '';
+  }
+});
+```
+
+## Accessibility
+
+The MTRL Chips component is built with accessibility in mind:
+
+- **ARIA Attributes**: Proper `aria-selected`, `aria-disabled`, and `aria-multiselectable` attributes
+- **Keyboard Navigation**: Navigate between chips using arrow keys, select with Space/Enter
+- **Focus Management**: Visible focus indicators and proper focus handling
+- **Semantic Structure**: Appropriate roles and accessible names
+- **Screen Reader Support**: Meaningful announcements for selection changes
+
+## Technical Architecture
+
+The MTRL Chips component follows a functional composition pattern:
+
+1. **Base Component**: Core structure with element creation
+2. **Feature Enhancement**: Functional mixins that add specific capabilities
+3. **DOM Generation**: Creates the actual DOM elements from the structure
+4. **Controller**: Manages state, events, and behavior
+5. **Lifecycle Management**: Handles component lifecycle events
+6. **Public API**: Exposes a clean, consistent interface
+
+This architecture enables:
+- Efficient code reuse and maintainability
+- Clear separation of concerns
+- Extensibility through composition
+- Predictable behavior and clean API surface
+
+## CSS Customization
+
+MTRL Chips use BEM-style class naming for easy styling. Primary classes:
+
+```
+.mtrl-chip               /* Base chip class */
+.mtrl-chip--{variant}    /* Variant classes */
+.mtrl-chip--selected     /* Selected state */
+.mtrl-chip--disabled     /* Disabled state */
+.mtrl-chip-content       /* Content container */
+.mtrl-chip-text          /* Text element */
+.mtrl-chip-leading-icon  /* Leading icon */
+.mtrl-chip-trailing-icon /* Trailing icon */
+
+.mtrl-chips             /* Chips container */
+.mtrl-chips--scrollable /* Scrollable state */
+.mtrl-chips--vertical   /* Vertical layout */
+.mtrl-chips-container   /* Inner container */
+.mtrl-chips-label       /* Label element */
+```
+
+## Browser Support
+
+This component supports all modern browsers that implement ES6+ standards:
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## License
+
+MTRL is licensed under the MIT License.

package/src/components/chips/chips.ts

@@ -0,0 +1,75 @@
+// src/components/chips/chips.ts
+import { pipe } from '../../core/compose/pipe';
+import { createBase } from '../../core/compose/component';
+import { withEvents, withLifecycle } from '../../core/compose/features';
+import { withLayout, withIcon, withLabel, withDom  } from '../../core/composition/features';
+import { 
+  withContainer,
+  withChipItems,
+  withController,
+  withLabel
+} from './features';
+import { withAPI } from './api';
+import { ChipsConfig, ChipsComponent } from './types';
+import { createBaseConfig, getApiConfig } from './config';
+
+/**
+ * Creates a chips container for grouping related chips
+ * 
+ * Chips follows a clear architectural pattern:
+ * 1. Structure definition - Describes the DOM structure declaratively
+ * 2. Feature enhancement - Adds specific capabilities (container, items, etc.)
+ * 3. DOM creation - Turns the structure into actual DOM elements
+ * 4. Controller - Manages behavior, events, and UI rendering
+ * 5. Lifecycle - Handles component lifecycle events
+ * 6. Public API - Exposes a clean, consistent API
+ *
+ * @param {ChipsConfig} config - Chips configuration object
+ * @returns {ChipsComponent} Chips component instance
+ */
+const createChips = (config: ChipsConfig = {}): ChipsComponent => {
+  // Process configuration with defaults
+  const baseConfig = createBaseConfig(config);
+
+  try {
+    // Create the component by composing features in a specific order
+    const component = pipe(
+      // Base component with event system
+      createBase,
+      withEvents(),
+      withLayout(baseConfig),
+      withContainer(baseConfig),
+      withLabel(baseConfig),
+      withChipItems(baseConfig),
+      
+      // Now create the actual DOM elements from the complete structure
+      withDom(),
+      
+      // Add state management and behavior
+      withController(baseConfig),
+      withLifecycle()
+    )(baseConfig);
+    
+    // Generate the API configuration based on the enhanced component
+    const apiOptions = getApiConfig(component);
+    
+    // Apply the public API layer
+    const chips = withAPI(apiOptions)(component);
+
+    // Register event handlers from config for convenience
+    if (baseConfig.on && typeof chips.on === 'function') {
+      Object.entries(baseConfig.on).forEach(([event, handler]) => {
+        if (typeof handler === 'function') {
+          chips.on(event, handler);
+        }
+      });
+    }
+
+    return chips;
+  } catch (error) {
+    console.error('Chips creation error:', error);
+    throw new Error(`Failed to create chip: ${(error as Error).message}`);
+  }
+};
+
+export default createChips;