mtrl 0.2.5 → 0.2.6

package/src/components/card/features.ts

@@ -20,8 +20,21 @@ interface SwipeableConfig {
 
 /**
  * Higher-order function to add loading state to a card
+ * 
  * @param {LoadingConfig} config - Loading state configuration
  * @returns {Function} Card component enhancer
+ * 
+ * @example
+ * ```typescript
+ * // Create a card with loading state
+ * const card = pipe(
+ *   createCard,
+ *   withLoading({ initialState: true })
+ * )();
+ * 
+ * // Toggle loading state
+ * setTimeout(() => card.loading.setLoading(false), 2000);
+ * ```
  */
 export const withLoading = (config: LoadingConfig = {}) => (component: BaseComponent): BaseComponent & { loading: LoadingFeature } => {
   const initialState = config.initialState || false;
@@ -36,7 +49,12 @@ export const withLoading = (config: LoadingConfig = {}) => (component: BaseCompo
       loadingElement = createElement({
         tag: 'div',
         className: `${PREFIX}-card-loading-overlay`,
-        container: component.element
+        container: component.element,
+        attrs: {
+          'role': 'progressbar',
+          'aria-busy': 'true',
+          'aria-label': 'Loading'
+        }
       });
 
       // Add spinner
@@ -47,11 +65,13 @@ export const withLoading = (config: LoadingConfig = {}) => (component: BaseCompo
       });
 
       component.element.classList.add(`${PREFIX}-card--state-loading`);
+      component.element.setAttribute('aria-busy', 'true');
     } else if (!loading && loadingElement) {
       // Remove loading overlay
       loadingElement.remove();
       loadingElement = null;
       component.element.classList.remove(`${PREFIX}-card--state-loading`);
+      component.element.setAttribute('aria-busy', 'false');
     }
   }
 
@@ -68,10 +88,61 @@ export const withLoading = (config: LoadingConfig = {}) => (component: BaseCompo
   };
 };
 
+/**
+ * Higher-order function to add elevation to a card based on its variant
+ * 
+ * Sets the initial elevation CSS variable according to Material Design 3 guidelines:
+ * - Elevated variant: 1dp elevation
+ * - Filled and outlined variants: 0dp elevation
+ * 
+ * @param {BaseComponent} component - Card component
+ * @returns {BaseComponent} Card component with elevation applied
+ * @example
+ * ```typescript
+ * // Apply elevation in the composition chain
+ * const card = pipe(
+ *   createBase,
+ *   withElement(config),
+ *   withElevation
+ * )(baseConfig);
+ * ```
+ */
+export const withElevation = (component: BaseComponent): BaseComponent => {
+  const config = component.config;
+  
+  // Set initial elevation based on variant
+  if (config.variant === 'elevated') {
+    component.element.style.setProperty('--card-elevation', '1');
+  } else {
+    component.element.style.setProperty('--card-elevation', '0');
+  }
+  
+  return component;
+};
+
 /**
  * Higher-order function to add expandable behavior to a card
+ * 
  * @param {ExpandableConfig} config - Expandable configuration
  * @returns {Function} Card component enhancer
+ * 
+ * @example
+ * ```typescript
+ * // Create a card with expandable content
+ * const expandableContent = document.createElement('div');
+ * expandableContent.textContent = 'Additional content that can be expanded';
+ * 
+ * const card = pipe(
+ *   createCard,
+ *   withExpandable({ 
+ *     initialExpanded: false,
+ *     expandableContent
+ *   })
+ * )();
+ * 
+ * // Later toggle the expanded state
+ * card.expandable.toggleExpanded();
+ * ```
  */
 export const withExpandable = (config: ExpandableConfig = {}) => (component: BaseComponent): BaseComponent & { expandable: ExpandableFeature } => {
   const initialExpanded = config.initialExpanded || false;
@@ -85,7 +156,8 @@ export const withExpandable = (config: ExpandableConfig = {}) => (component: Bas
     className: `${PREFIX}-card-expand-button`,
     attrs: {
       'aria-expanded': isExpanded ? 'true' : 'false',
-      'aria-label': isExpanded ? 'Collapse' : 'Expand'
+      'aria-label': isExpanded ? 'Collapse content' : 'Expand content',
+      'aria-controls': expandableContent?.id || `${component.element.id || 'card'}-expandable-content`
     }
   }) as HTMLButtonElement;
 
@@ -98,7 +170,10 @@ export const withExpandable = (config: ExpandableConfig = {}) => (component: Bas
     const newActionsContainer = createElement({
       tag: 'div',
       className: `${PREFIX}-card-actions`,
-      container: component.element
+      container: component.element,
+      attrs: {
+        'role': 'group'
+      }
     });
     newActionsContainer.appendChild(expandButton);
   }
@@ -106,9 +181,19 @@ export const withExpandable = (config: ExpandableConfig = {}) => (component: Bas
   // Set initial state
   if (expandableContent) {
     expandableContent.classList.add(`${PREFIX}-card-expandable-content`);
+    
+    // Ensure the expandable content has an ID for ARIA controls
+    if (!expandableContent.id) {
+      expandableContent.id = `${component.element.id || 'card'}-expandable-content`;
+    }
+    
     if (!initialExpanded) {
       expandableContent.style.display = 'none';
+      expandableContent.setAttribute('aria-hidden', 'true');
+    } else {
+      expandableContent.setAttribute('aria-hidden', 'false');
     }
+    
     component.element.appendChild(expandableContent);
   }
 
@@ -118,10 +203,11 @@ export const withExpandable = (config: ExpandableConfig = {}) => (component: Bas
 
     if (expandableContent) {
       expandableContent.style.display = expanded ? 'block' : 'none';
+      expandableContent.setAttribute('aria-hidden', expanded ? 'false' : 'true');
     }
 
     expandButton.setAttribute('aria-expanded', expanded ? 'true' : 'false');
-    expandButton.setAttribute('aria-label', expanded ? 'Collapse' : 'Expand');
+    expandButton.setAttribute('aria-label', expanded ? 'Collapse content' : 'Expand content');
 
     if (expanded) {
       component.element.classList.add(`${PREFIX}-card--expanded`);
@@ -143,6 +229,14 @@ export const withExpandable = (config: ExpandableConfig = {}) => (component: Bas
     toggleExpanded();
   });
 
+  // Add keyboard handler for accessibility
+  expandButton.addEventListener('keydown', (e: KeyboardEvent) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      toggleExpanded();
+    }
+  });
+
   return {
     ...component,
     expandable: {
@@ -155,13 +249,70 @@ export const withExpandable = (config: ExpandableConfig = {}) => (component: Bas
 
 /**
  * Higher-order function to add swipeable behavior to a card
+ * 
  * @param {SwipeableConfig} config - Swipeable configuration
  * @returns {Function} Card component enhancer
+ * 
+ * @example
+ * ```typescript
+ * // Create a swipeable card
+ * const card = pipe(
+ *   createCard,
+ *   withSwipeable({
+ *     threshold: 100,
+ *     onSwipeLeft: (card) => console.log('Swiped left'),
+ *     onSwipeRight: (card) => console.log('Swiped right')
+ *   })
+ * )({ variant: CardVariant.ELEVATED });
+ * ```
  */
 export const withSwipeable = (config: SwipeableConfig = {}) => (component: BaseComponent): BaseComponent & { swipeable: SwipeableFeature } => {
   const threshold = config.threshold || 100;
   let startX = 0;
   let currentX = 0;
+  
+  // Add accessibility information for swipeable cards
+  component.element.setAttribute('aria-description', 'Swipeable card. Swipe left or right to perform actions.');
+
+  // Create hidden buttons for keyboard accessibility
+  const leftActionButton = createElement({
+    tag: 'button',
+    className: `${PREFIX}-card-swipe-left-action`,
+    text: 'Swipe Left Action',
+    container: component.element,
+    attrs: {
+      'aria-label': 'Perform swipe left action',
+      'style': 'position: absolute; left: -9999px; top: -9999px; visibility: hidden;' // Visually hidden but accessible
+    }
+  }) as HTMLButtonElement;
+  
+  const rightActionButton = createElement({
+    tag: 'button',
+    className: `${PREFIX}-card-swipe-right-action`,
+    text: 'Swipe Right Action',
+    container: component.element,
+    attrs: {
+      'aria-label': 'Perform swipe right action',
+      'style': 'position: absolute; left: -9999px; top: -9999px; visibility: hidden;' // Visually hidden but accessible
+    }
+  }) as HTMLButtonElement;
+  
+  // Add keyboard handlers to the hidden buttons
+  leftActionButton.addEventListener('click', () => {
+    if (config.onSwipeLeft) {
+      component.element.style.transform = 'translateX(-100%)';
+      component.element.style.transition = 'transform 0.3s ease';
+      config.onSwipeLeft(component as CardComponent);
+    }
+  });
+  
+  rightActionButton.addEventListener('click', () => {
+    if (config.onSwipeRight) {
+      component.element.style.transform = 'translateX(100%)';
+      component.element.style.transition = 'transform 0.3s ease';
+      config.onSwipeRight(component as CardComponent);
+    }
+  });
 
   function handleTouchStart(e: TouchEvent): void {
     startX = e.touches[0].clientX;

package/src/components/card/index.ts

@@ -1,9 +1,32 @@
 // src/components/card/index.ts
-export { default } from './card'
-export { createCardContent } from './content'
-export { createCardHeader } from './header'
-export { createCardActions } from './actions'
-export { createCardMedia } from './media'
+import defaultCreateCard from './card';
+
+/**
+ * Card Component Module
+ * 
+ * This module exports the Card components and related utilities following
+ * Material Design 3 specifications.
+ */
+
+// Add default export 
+export default defaultCreateCard;
+
+// Export components from content file where they are now merged
+export { 
+  createCardContent,
+  createCardHeader, 
+  createCardActions,
+  createCardMedia
+} from './content';
+
+// Other exports
+export { 
+  withLoading, 
+  withExpandable, 
+  withSwipeable, 
+  withElevation 
+} from './features';
+
 export {
   CardVariant,
   CardElevation,
@@ -12,8 +35,7 @@ export {
   CardContentConfig,
   CardActionsConfig,
   CardMediaConfig,
+  CardAriaAttributes,
   CardComponent
-} from './types'
-
-// Export constants for backward compatibility
-export { CARD_VARIANTS, CARD_ELEVATIONS, CARD_SCHEMA } from './constants'
+} from './types';
+export { CARD_VARIANTS, CARD_ELEVATIONS, CARD_WIDTHS, CARD_CORNER_RADIUS } from './constants';

package/src/components/card/types.ts

@@ -1,174 +1,297 @@
 // src/components/card/types.ts
-
 /**
- * Card variant types following Material Design 3
+ * Card variant types following Material Design 3 specifications
+ * @enum {string}
  */
 export enum CardVariant {
+  /** Elevated card with shadow */
   ELEVATED = 'elevated',
+  /** Filled card with higher surface container color */
   FILLED = 'filled',
+  /** Outlined card with border */
   OUTLINED = 'outlined'
 }
 
 /**
- * Card elevation levels
+ * Card elevation levels based on MD3 guidelines
+ * @enum {number}
  */
 export enum CardElevation {
-  RESTING = 1,
-  HOVERED = 2,
-  DRAGGED = 4
+  /** No elevation (for filled and outlined variants) */
+  LEVEL0 = 0,
+  /** Default elevation for elevated cards */
+  LEVEL1 = 1,
+  /** Elevation for hovered state */
+  LEVEL2 = 2,
+  /** Elevation for dragged state */
+  LEVEL4 = 4
 }
 
 /**
- * Interface for card configuration
+ * Card configuration interface
+ * @interface CardSchema
  */
 export interface CardSchema {
+  /** Card variant type (elevated, filled, outlined) */
   variant?: CardVariant;
+  /** Whether the card is interactive */
   interactive?: boolean;
+  /** Whether the card should take full width */
   fullWidth?: boolean;
+  /** Whether the card is clickable (with ripple effect) */
   clickable?: boolean;
+  /** Whether the card is draggable */
   draggable?: boolean;
+  /** Additional CSS class(es) */
   class?: string;
+  /** Header configuration */
   headerConfig?: CardHeaderConfig;
+  /** Content configuration */
   contentConfig?: CardContentConfig;
+  /** Actions configuration */
   actionsConfig?: CardActionsConfig;
+  /** Media configuration */
   mediaConfig?: CardMediaConfig;
+  /** ARIA attributes for accessibility */
+  aria?: CardAriaAttributes;
+  /** Internal component name */
+  componentName?: string;
+  /** CSS class prefix */
+  prefix?: string;
+  /** Callback executed after component creation */
+  afterCreation?: (component: BaseComponent) => void;
+}
+
+/**
+ * ARIA attributes for card accessibility
+ * @interface CardAriaAttributes
+ */
+export interface CardAriaAttributes {
+  /** ARIA label */
+  label?: string;
+  /** ARIA labelledby */
+  labelledby?: string;
+  /** ARIA describedby */
+  describedby?: string;
+  /** ARIA role (default is 'region' for non-interactive, 'button' for interactive) */
+  role?: string;
+  /** Additional ARIA attributes as key-value pairs */
+  [key: string]: string | undefined;
 }
 
 /**
- * Interface for card header configuration
+ * Card header configuration
+ * @interface CardHeaderConfig
  */
 export interface CardHeaderConfig {
+  /** Header title text */
   title?: string;
+  /** Header subtitle text */
   subtitle?: string;
+  /** Avatar element or HTML string */
   avatar?: HTMLElement | string;
+  /** Action element or HTML string */
   action?: HTMLElement | string;
+  /** Additional CSS class(es) */
   class?: string;
 }
 
 /**
- * Interface for card content configuration
+ * Card content configuration
+ * @interface CardContentConfig
  */
 export interface CardContentConfig {
+  /** Text content */
   text?: string;
+  /** HTML content */
   html?: string;
+  /** Child elements */
   children?: HTMLElement[];
+  /** Whether to add padding (true by default) */
   padding?: boolean;
+  /** Additional CSS class(es) */
   class?: string;
 }
 
 /**
- * Interface for card actions configuration
+ * Card actions configuration
+ * @interface CardActionsConfig
  */
 export interface CardActionsConfig {
+  /** Action elements */
   actions?: HTMLElement[];
+  /** Whether actions should be full-bleed */
   fullBleed?: boolean;
+  /** Whether actions should be stacked vertically */
   vertical?: boolean;
+  /** Horizontal alignment */
   align?: 'start' | 'center' | 'end' | 'space-between';
+  /** Additional CSS class(es) */
   class?: string;
 }
 
 /**
- * Interface for card media configuration
+ * Card media configuration
+ * @interface CardMediaConfig
  */
 export interface CardMediaConfig {
+  /** Image source URL */
   src?: string;
+  /** Image alt text (required for accessibility) */
   alt?: string;
+  /** Custom element instead of image */
   element?: HTMLElement;
+  /** Aspect ratio */
   aspectRatio?: '16:9' | '4:3' | '1:1' | string;
+  /** Whether media should use object-fit: contain */
   contain?: boolean;
+  /** Additional CSS class(es) */
   class?: string;
+  /** 
+   * Position of the media in the card
+   * - 'top': Media appears at the top of the card (default)
+   * - 'bottom': Media appears after the content
+   */
+  position?: 'top' | 'bottom';
 }
 
 /**
  * Base component interface
+ * @interface BaseComponent
  */
 export interface BaseComponent {
+  /** The DOM element */
   element: HTMLElement;
+  /** Get class name with prefix */
   getClass: (name?: string) => string;
+  /** Get modifier class */
   getModifierClass: (base: string, modifier: string) => string;
+  /** Get element class */
   getElementClass: (base: string, element: string) => string;
+  /** Add CSS class(es) */
   addClass: (...classes: string[]) => BaseComponent;
+  /** Emit an event */
   emit?: (event: string, data?: any) => void;
+  /** Component configuration */
   config: CardComponentConfig;
+  /** Touch state for touch interactions */
   touchState?: TouchState;
+  /** Update touch state */
   updateTouchState?: (event: TouchEvent | MouseEvent, status: 'start' | 'end') => void;
+  /** Component lifecycle methods */
   lifecycle?: ComponentLifecycle;
 }
 
 /**
- * Touch state interface
+ * Touch state interface for touch interactions
+ * @interface TouchState
  */
 export interface TouchState {
+  /** Timestamp when touch started */
   startTime: number;
+  /** Starting position */
   startPosition: { x: number; y: number };
+  /** Whether touch is active */
   isTouching: boolean;
+  /** Current touch target */
   activeTarget: EventTarget | null;
 }
 
 /**
  * Component lifecycle interface
+ * @interface ComponentLifecycle
  */
 export interface ComponentLifecycle {
+  /** Called when component is mounted to DOM */
   mount?: () => void;
+  /** Called when component is updated */
   update?: () => void;
+  /** Called when component is destroyed */
   destroy: () => void;
 }
 
 /**
  * Card component configuration
+ * @interface CardComponentConfig
+ * @extends CardSchema
  */
 export interface CardComponentConfig extends CardSchema {
+  /** Component name */
   componentName: string;
+  /** CSS class prefix */
   prefix: string;
 }
 
 /**
- * Card component interface
+ * Card component interface with methods
+ * @interface CardComponent
+ * @extends BaseComponent
  */
 export interface CardComponent extends BaseComponent {
-  // Card-specific methods
+  /** Add content to the card */
   addContent: (contentElement: HTMLElement) => CardComponent;
+  /** Set the card header */
   setHeader: (headerElement: HTMLElement) => CardComponent;
+  /** Add media to the card */
   addMedia: (mediaElement: HTMLElement, position?: 'top' | 'bottom') => CardComponent;
+  /** Set the card actions */
   setActions: (actionsElement: HTMLElement) => CardComponent;
+  /** Make the card draggable */
   makeDraggable: (dragStartCallback?: (event: DragEvent) => void) => CardComponent;
+  /** Set focus to the card */
+  focus: () => CardComponent;
+  /** Destroy the card and clean up resources */
   destroy: () => void;
   
-  // Optional feature interfaces
+  /** Optional loading feature */
   loading?: LoadingFeature;
+  /** Optional expandable feature */
   expandable?: ExpandableFeature;
+  /** Optional swipeable feature */
   swipeable?: SwipeableFeature;
 }
 
 /**
  * Loading feature interface
+ * @interface LoadingFeature
  */
 export interface LoadingFeature {
+  /** Check if loading state is active */
   isLoading: () => boolean;
+  /** Set loading state */
   setLoading: (loading: boolean) => void;
 }
 
 /**
  * Expandable feature interface
+ * @interface ExpandableFeature
  */
 export interface ExpandableFeature {
+  /** Check if expanded state is active */
   isExpanded: () => boolean;
+  /** Set expanded state */
   setExpanded: (expanded: boolean) => void;
+  /** Toggle expanded state */
   toggleExpanded: () => void;
 }
 
 /**
  * Swipeable feature interface
+ * @interface SwipeableFeature
  */
 export interface SwipeableFeature {
+  /** Reset swipe position */
   reset: () => void;
 }
 
 /**
  * API options interface
+ * @interface ApiOptions
  */
 export interface ApiOptions {
+  /** Lifecycle methods */
   lifecycle: {
+    /** Destroy callback */
     destroy: () => void;
   };
 }

package/src/components/chip/chip.ts

@@ -7,19 +7,17 @@ import {
   withText,
   withIcon,
   withVariant,
-  withSize,
   withRipple,
   withDisabled,
   withLifecycle
 } from '../../core/compose/features'
 import { withAPI } from './api'
-import { CHIP_VARIANTS, CHIP_SIZES } from './constants'
+import { CHIP_VARIANTS } from './constants'
 
 /**
  * Creates a new Chip component
  * @param {Object} config - Chip configuration
  * @param {string} [config.variant='filled'] - Chip variant
- * @param {string} [config.size='medium'] - Chip size
  * @param {boolean} [config.selected=false] - Whether the chip is initially selected
  * @param {boolean} [config.disabled=false] - Whether the chip is initially disabled
  * @param {string} [config.text] - Chip text content
@@ -37,7 +35,6 @@ const createChip = (config = {}) => {
   const baseConfig = {
     ...config,
     variant: config.variant || CHIP_VARIANTS.FILLED,
-    size: config.size || CHIP_SIZES.MEDIUM,
     componentName: 'chip',
     prefix: PREFIX,
     ripple: config.ripple !== false
@@ -76,11 +73,6 @@ const createChip = (config = {}) => {
       chip.element.classList.add(`${chip.getClass('chip')}--${config.variant}`)
     }
     
-    // Manually add the size class
-    if (config.size) {
-      chip.element.classList.add(`${chip.getClass('chip')}--${config.size}`)
-    }
-    
     // Add ripple if enabled
     if (config.ripple) {
       withRipple(baseConfig)(chip)

package/src/components/chip/constants.ts

@@ -25,14 +25,4 @@ export const CHIP_VARIANTS = {
 
   /** Suggestion chip for presenting options */
   SUGGESTION: 'suggestion'
-};
-
-/**
- * Available sizes for the Chip component
- * @enum {string}
- */
-export const CHIP_SIZES = {
-  SMALL: 'small',
-  MEDIUM: 'medium',
-  LARGE: 'large'
 };

package/src/components/chip/index.ts

@@ -1,4 +1,4 @@
 // src/components/chip/index.js
 export { default } from './chip'
 export { default as createChipSet } from './chip-set'
-export { CHIP_VARIANTS, CHIP_SIZES } from './constants'
+export { CHIP_VARIANTS } from './constants'

package/src/components/chip/types.ts

@@ -1,5 +1,5 @@
 // src/components/chip/types.ts
-import { CHIP_VARIANTS, CHIP_SIZES } from './constants';
+import { CHIP_VARIANTS } from './constants';
 
 /**
  * Configuration interface for the Chip component
@@ -8,9 +8,6 @@ export interface ChipConfig {
   /** Chip variant (filled, outlined, elevated, assist, filter, input, suggestion) */
   variant?: keyof typeof CHIP_VARIANTS | string;
   
-  /** Chip size (small, medium, large) */
-  size?: keyof typeof CHIP_SIZES | string;
-  
   /** Whether the chip is initially disabled */
   disabled?: boolean;