mtrl 0.2.5 → 0.2.6

package/src/components/card/config.ts

@@ -1,14 +1,14 @@
 // src/components/card/config.ts
 import { 
   createComponentConfig, 
-  createElementConfig,
-  BaseComponentConfig 
+  createElementConfig
 } from '../../core/config/component-config';
 import { BaseComponent, CardSchema } from './types';
 import { CARD_VARIANTS, CARD_ELEVATIONS } from './constants';
 
 /**
  * Default configuration for the Card component
+ * @const {CardSchema}
  */
 export const defaultConfig: CardSchema = {
   variant: CARD_VARIANTS.ELEVATED,
@@ -18,8 +18,63 @@ export const defaultConfig: CardSchema = {
   draggable: false
 };
 
+/**
+ * Initializes a card component with its configured elements in the correct order
+ * 
+ * Creates and adds all configured elements to the card in the following order:
+ * 1. Top media elements (position='top')
+ * 2. Header element
+ * 3. Content elements
+ * 4. Bottom media elements (position='bottom')
+ * 5. Actions elements
+ * 
+ * This ordering ensures that media appears before header when both are configured,
+ * maintaining proper visual hierarchy according to Material Design guidelines.
+ * 
+ * @param {CardComponent} card - Card component to initialize
+ * @param {CardSchema} config - Card configuration
+ * @returns {CardComponent} Initialized card component
+ * @internal This is an internal utility for the Card component
+ */
+export const initializeCardElements = (card: CardComponent, config: CardSchema): CardComponent => {
+  // 1. Add top media first 
+  if (config.mediaConfig && (!config.mediaConfig.position || config.mediaConfig.position === 'top')) {
+    const { position, ...mediaConfigWithoutPosition } = config.mediaConfig;
+    const mediaElement = createCardMedia(mediaConfigWithoutPosition);
+    card.addMedia(mediaElement, 'top');
+  }
+  
+  // 2. Add header AFTER top media
+  if (config.headerConfig) {
+    const headerElement = createCardHeader(config.headerConfig);
+    card.setHeader(headerElement);
+  }
+  
+  // 3. Add content AFTER header
+  if (config.contentConfig) {
+    const contentElement = createCardContent(config.contentConfig);
+    card.addContent(contentElement);
+  }
+  
+  // 4. Add bottom media AFTER content
+  if (config.mediaConfig && config.mediaConfig.position === 'bottom') {
+    const { position, ...mediaConfigWithoutPosition } = config.mediaConfig;
+    const mediaElement = createCardMedia(mediaConfigWithoutPosition);
+    card.addMedia(mediaElement, 'bottom');
+  }
+  
+  // 5. Add actions LAST
+  if (config.actionsConfig) {
+    const actionsElement = createCardActions(config.actionsConfig);
+    card.setActions(actionsElement);
+  }
+  
+  return card;
+};
+
 /**
  * Creates the base configuration for Card component
+ * 
  * @param {CardSchema} config - User provided configuration
  * @returns {CardSchema} Complete configuration with defaults applied
  */
@@ -28,31 +83,64 @@ export const createBaseConfig = (config: CardSchema = {}): CardSchema =>
 
 /**
  * Generates element configuration for the Card component
+ * 
  * @param {CardSchema} config - Card configuration
  * @returns {Object} Element configuration object for withElement
  */
-export const getElementConfig = (config: CardSchema) =>
-  createElementConfig(config, {
+export const getElementConfig = (config: CardSchema) => {
+  const isInteractive = config.interactive || config.clickable;
+  const defaultRole = isInteractive ? 'button' : 'region';
+  
+  // Prepare ARIA attributes
+  const ariaAttrs: Record<string, string> = {};
+  if (config.aria) {
+    // Add all ARIA attributes from config
+    Object.entries(config.aria).forEach(([key, value]) => {
+      if (value !== undefined) {
+        // Convert attribute name to aria-* format if not already
+        const attrName = key.startsWith('aria-') ? key : `aria-${key}`;
+        ariaAttrs[attrName] = value;
+      }
+    });
+  }
+  
+  // Set default ARIA role if not specified
+  if (!ariaAttrs['role'] && !config.aria?.role) {
+    ariaAttrs['role'] = defaultRole;
+  }
+  
+  // Add tabindex for interactive cards if not specified
+  if (isInteractive && !ariaAttrs['tabindex']) {
+    ariaAttrs['tabindex'] = '0';
+  }
+  
+  return createElementConfig(config, {
     tag: 'div',
     className: [
       config.class,
       config.fullWidth ? `${config.prefix}-card--full-width` : null,
-      config.interactive ? `${config.prefix}-card--interactive` : null
+      isInteractive ? `${config.prefix}-card--interactive` : null
     ],
+    attrs: ariaAttrs,
     forwardEvents: {
       click: (component: BaseComponent) => !!config.clickable,
-      mouseenter: (component: BaseComponent) => !!config.interactive,
-      mouseleave: (component: BaseComponent) => !!config.interactive
+      mouseenter: (component: BaseComponent) => !!isInteractive,
+      mouseleave: (component: BaseComponent) => !!isInteractive,
+      keydown: (component: BaseComponent) => !!isInteractive,
+      focus: (component: BaseComponent) => !!isInteractive,
+      blur: (component: BaseComponent) => !!isInteractive
     },
-    interactive: config.interactive || config.clickable
+    interactive: isInteractive
   });
+};
 
 /**
  * Creates API configuration for the Card component
+ * 
  * @param {Object} comp - Component with lifecycle feature
  * @returns {Object} API configuration object
  */
-export const getApiConfig = (comp) => ({
+export const getApiConfig = (comp: any) => ({
   lifecycle: {
     destroy: () => comp.lifecycle?.destroy?.()
   }
@@ -60,35 +148,69 @@ export const getApiConfig = (comp) => ({
 
 /**
  * Adds interactive behavior to card component
+ * Uses the MTRL elevation system for proper elevation levels
+ * 
  * @param {BaseComponent} comp - Card component
  * @returns {BaseComponent} Enhanced card component
  */
 export const withInteractiveBehavior = (comp: BaseComponent): BaseComponent => {
-  // Implement hover state elevation changes for interactive cards
-  if (comp.config.interactive) {
+  const config = comp.config;
+  const isInteractive = config.interactive || config.clickable;
+  
+  // Implement MD3 elevation changes for interactive cards
+  if (isInteractive) {
+    // Mouse interactions
     comp.element.addEventListener('mouseenter', () => {
-      if (comp.config.variant === CARD_VARIANTS.ELEVATED) {
-        comp.element.style.setProperty('--card-elevation', String(CARD_ELEVATIONS.HOVERED));
+      if (config.variant === CARD_VARIANTS.ELEVATED) {
+        comp.element.style.setProperty('--card-elevation', String(CARD_ELEVATIONS.LEVEL2));
       }
     });
 
     comp.element.addEventListener('mouseleave', () => {
-      if (comp.config.variant === CARD_VARIANTS.ELEVATED) {
-        comp.element.style.setProperty('--card-elevation', String(CARD_ELEVATIONS.RESTING));
+      if (config.variant === CARD_VARIANTS.ELEVATED) {
+        comp.element.style.setProperty('--card-elevation', String(CARD_ELEVATIONS.LEVEL1));
       }
     });
+    
+    // Keyboard interactions for accessibility
+    comp.element.addEventListener('keydown', (e: KeyboardEvent) => {
+      // Activate on Enter or Space
+      if ((e.key === 'Enter' || e.key === ' ') && config.clickable) {
+        e.preventDefault();
+        comp.element.click();
+      }
+    });
+    
+    // Focus state handling
+    comp.element.addEventListener('focus', () => {
+      comp.element.classList.add(`${comp.getClass('card')}--focused`);
+    });
+    
+    comp.element.addEventListener('blur', () => {
+      comp.element.classList.remove(`${comp.getClass('card')}--focused`);
+    });
   }
 
-  // Set up draggable
-  if (comp.config.draggable) {
+  // Set up draggable behavior
+  if (config.draggable) {
     comp.element.setAttribute('draggable', 'true');
-    comp.element.addEventListener('dragstart', (e) => {
-      comp.element.style.setProperty('--card-elevation', String(CARD_ELEVATIONS.DRAGGED));
+    
+    comp.element.addEventListener('dragstart', (e: DragEvent) => {
+      comp.element.style.setProperty('--card-elevation', String(CARD_ELEVATIONS.LEVEL4));
+      comp.element.classList.add(`${comp.getClass('card')}--dragging`);
       comp.emit?.('dragstart', { event: e });
+      
+      // Ensure keyboard users can see what's being dragged
+      if (e.dataTransfer) {
+        // Set drag image and data
+        const cardTitle = comp.element.querySelector(`.${comp.getClass('card')}-header-title`)?.textContent || 'Card';
+        e.dataTransfer.setData('text/plain', cardTitle);
+      }
     });
 
-    comp.element.addEventListener('dragend', (e) => {
-      comp.element.style.setProperty('--card-elevation', String(CARD_ELEVATIONS.RESTING));
+    comp.element.addEventListener('dragend', (e: DragEvent) => {
+      comp.element.style.setProperty('--card-elevation', String(CARD_ELEVATIONS.LEVEL1));
+      comp.element.classList.remove(`${comp.getClass('card')}--dragging`);
       comp.emit?.('dragend', { event: e });
     });
   }

package/src/components/card/constants.ts

@@ -1,4 +1,5 @@
 // src/components/card/constants.ts
+
 import { CardVariant, CardElevation } from './types';
 
 /**
@@ -6,37 +7,33 @@ import { CardVariant, CardElevation } from './types';
  * @enum {string}
  */
 export const CARD_VARIANTS = {
+  /** Elevated card with shadow */
   ELEVATED: CardVariant.ELEVATED,
+  /** Filled card with higher surface container color */
   FILLED: CardVariant.FILLED,
+  /** Outlined card with border */
   OUTLINED: CardVariant.OUTLINED
 };
 
 /**
- * Card elevation levels
+ * Card elevation levels based on MD3 guidelines
+ * Uses the MTRL elevation system values
  * @enum {number}
  */
 export const CARD_ELEVATIONS = {
-  RESTING: CardElevation.RESTING,
-  HOVERED: CardElevation.HOVERED,
-  DRAGGED: CardElevation.DRAGGED
+  /** No elevation (for filled and outlined variants) */
+  LEVEL0: CardElevation.LEVEL0,
+  /** Default elevation for elevated cards */
+  LEVEL1: CardElevation.LEVEL1,
+  /** Elevation for hovered state */
+  LEVEL2: CardElevation.LEVEL2,
+  /** Elevation for dragged state */
+  LEVEL4: CardElevation.LEVEL4
 };
 
-// Default width values following MD3 principles
-export const CARD_WIDTHS = {
-  // Mobile-optimized default (MD3 recommends 344dp for small screens)
-  DEFAULT: '344px',
-  // Percentage-based responsive options
-  FULL: '100%',
-  HALF: '50%',
-  // Fixed widths for different breakpoints
-  SMALL: '344px',
-  MEDIUM: '480px',
-  LARGE: '624px'
-}
-
-
 /**
- * Validation schema for card configuration
+ * Card validation schema
+ * @const {Object}
  */
 export const CARD_SCHEMA = {
   variant: {
@@ -79,5 +76,9 @@ export const CARD_SCHEMA = {
   mediaConfig: {
     type: 'object',
     required: false
+  },
+  aria: {
+    type: 'object',
+    required: false
   }
 };

package/src/components/card/content.ts

@@ -3,11 +3,25 @@ import { PREFIX } from '../../core/config';
 import { pipe } from '../../core/compose';
 import { createBase, withElement } from '../../core/compose/component';
 import { CardContentConfig } from './types';
+import { CARD_CONTENT_PADDING } from './constants';
 
 /**
  * Creates a card content component
+ * 
  * @param {CardContentConfig} config - Content configuration
  * @returns {HTMLElement} Card content element
+ * 
+ * @example
+ * ```typescript
+ * // Create text content
+ * const textContent = createCardContent({ text: 'Simple text content' });
+ * 
+ * // Create HTML content with no padding
+ * const htmlContent = createCardContent({
+ *   html: '<p>Formatted <strong>HTML</strong> content</p>',
+ *   padding: false
+ * });
+ * ```
  */
 export const createCardContent = (config: CardContentConfig = {}): HTMLElement => {
   const baseConfig = {
@@ -17,6 +31,8 @@ export const createCardContent = (config: CardContentConfig = {}): HTMLElement =
   };
 
   try {
+    // Create element with innerHTML instead of html/text properties
+    // for more reliable content rendering
     const content = pipe(
       createBase,
       withElement({
@@ -26,11 +42,22 @@ export const createCardContent = (config: CardContentConfig = {}): HTMLElement =
           config.class,
           config.padding === false ? `${PREFIX}-card-content--no-padding` : null
         ],
-        html: config.html,
-        text: config.text
+        attrs: {
+          'role': 'region',
+          // Add explicit style attributes to ensure visibility
+          'style': 'display: block; color: inherit;'
+        }
       })
     )(baseConfig);
 
+    // Explicitly set the innerHTML for more reliable rendering
+    if (config.html) {
+      content.element.innerHTML = config.html;
+    } else if (config.text) {
+      // Wrap text in paragraph for proper formatting
+      content.element.innerHTML = `<p>${config.text}</p>`;
+    }
+
     // Add children if provided
     if (Array.isArray(config.children)) {
       config.children.forEach(child => {
@@ -40,9 +67,279 @@ export const createCardContent = (config: CardContentConfig = {}): HTMLElement =
       });
     }
 
+    // Add debug class to make troubleshooting easier
+    // Remove this in production
+    content.element.classList.add('debug-content');
+
     return content.element;
   } catch (error) {
     console.error('Card content creation error:', error instanceof Error ? error.message : String(error));
     throw new Error(`Failed to create card content: ${error instanceof Error ? error.message : String(error)}`);
   }
+};
+
+// src/components/card/header.ts
+import { createElement } from '../../core/dom/create';
+
+/**
+ * Creates a card header component
+ * 
+ * @param {CardHeaderConfig} config - Header configuration
+ * @returns {HTMLElement} Card header element
+ * 
+ * @example
+ * ```typescript
+ * // Create a header with title and subtitle
+ * const header = createCardHeader({
+ *   title: 'Card Title',
+ *   subtitle: 'Supporting text'
+ * });
+ * 
+ * // Create a header with an avatar and action
+ * const avatarHeader = createCardHeader({
+ *   title: 'User Profile',
+ *   avatar: '<img src="user.jpg" alt="User avatar">',
+ *   action: createIconButton({ icon: 'more_vert' })
+ * });
+ * ```
+ */
+export const createCardHeader = (config: any = {}): HTMLElement => {
+  const baseConfig = {
+    ...config,
+    componentName: 'card-header',
+    prefix: PREFIX
+  };
+
+  try {
+    const header = pipe(
+      createBase,
+      withElement({
+        tag: 'div',
+        componentName: 'card-header',
+        className: config.class,
+        attrs: {
+          'role': 'heading',
+          'aria-level': '3' // Default heading level
+        }
+      })
+    )(baseConfig);
+
+    // Create text container for title and subtitle
+    const textContainer = createElement({
+      tag: 'div',
+      className: `${PREFIX}-card-header-text`,
+      container: header.element
+    });
+
+    // Add title if provided
+    if (config.title) {
+      createElement({
+        tag: 'h3',
+        className: `${PREFIX}-card-header-title`,
+        text: config.title,
+        container: textContainer,
+        attrs: {
+          id: `${header.element.id || 'card-header'}-title`
+        }
+      });
+
+      // Link the title ID to the card for accessibility if parent card exists
+      const parentCard = header.element.closest(`.${PREFIX}-card`);
+      if (parentCard && !parentCard.hasAttribute('aria-labelledby')) {
+        parentCard.setAttribute('aria-labelledby', `${header.element.id || 'card-header'}-title`);
+      }
+    }
+
+    // Add subtitle if provided
+    if (config.subtitle) {
+      createElement({
+        tag: 'h4',
+        className: `${PREFIX}-card-header-subtitle`,
+        text: config.subtitle,
+        container: textContainer
+      });
+    }
+
+    // Add avatar if provided
+    if (config.avatar) {
+      const avatarElement = typeof config.avatar === 'string'
+        ? createElement({
+          tag: 'div',
+          className: `${PREFIX}-card-header-avatar`,
+          html: config.avatar
+        })
+        : config.avatar;
+
+      // Ensure avatar has correct ARIA attributes if it's an image
+      const avatarImg = avatarElement.querySelector('img');
+      if (avatarImg && !avatarImg.hasAttribute('alt')) {
+        avatarImg.setAttribute('alt', ''); // Decorative image
+        avatarImg.setAttribute('aria-hidden', 'true');
+      }
+
+      header.element.insertBefore(avatarElement, header.element.firstChild);
+    }
+
+    // Add action if provided
+    if (config.action) {
+      const actionElement = typeof config.action === 'string'
+        ? createElement({
+          tag: 'div',
+          className: `${PREFIX}-card-header-action`,
+          html: config.action
+        })
+        : config.action;
+
+      header.element.appendChild(actionElement);
+    }
+
+    return header.element;
+  } catch (error) {
+    console.error('Card header creation error:', error instanceof Error ? error.message : String(error));
+    throw new Error(`Failed to create card header: ${error instanceof Error ? error.message : String(error)}`);
+  }
+};
+
+// src/components/card/actions.ts
+/**
+ * Creates a card actions component
+ * 
+ * @param {CardActionsConfig} config - Actions configuration
+ * @returns {HTMLElement} Card actions element
+ * 
+ * @example
+ * ```typescript
+ * // Create simple actions container with buttons
+ * const actions = createCardActions({
+ *   actions: [
+ *     createButton({ text: 'Cancel' }),
+ *     createButton({ text: 'OK', variant: 'filled' })
+ *   ],
+ *   align: 'end'
+ * });
+ * 
+ * // Create full-bleed actions
+ * const fullBleedActions = createCardActions({
+ *   actions: [createButton({ text: 'View Details', fullWidth: true })],
+ *   fullBleed: true
+ * });
+ * ```
+ */
+export const createCardActions = (config: any = {}): HTMLElement => {
+  const baseConfig = {
+    ...config,
+    componentName: 'card-actions',
+    prefix: PREFIX
+  };
+
+  try {
+    const actions = pipe(
+      createBase,
+      withElement({
+        tag: 'div',
+        componentName: 'card-actions',
+        className: [
+          config.class,
+          config.fullBleed ? `${PREFIX}-card-actions--full-bleed` : null,
+          config.vertical ? `${PREFIX}-card-actions--vertical` : null,
+          config.align ? `${PREFIX}-card-actions--${config.align}` : null
+        ],
+        attrs: {
+          'role': 'group' // Semantically group actions together
+        }
+      })
+    )(baseConfig);
+
+    // Add action elements if provided
+    if (Array.isArray(config.actions)) {
+      config.actions.forEach((action, index) => {
+        if (action instanceof HTMLElement) {
+          // Ensure each action has accessible attributes
+          if (!action.hasAttribute('aria-label') && 
+              !action.hasAttribute('aria-labelledby') &&
+              action.textContent?.trim() === '') {
+            action.setAttribute('aria-label', `Action ${index + 1}`);
+          }
+          
+          actions.element.appendChild(action);
+        }
+      });
+    }
+
+    return actions.element;
+  } catch (error) {
+    console.error('Card actions creation error:', error instanceof Error ? error.message : String(error));
+    throw new Error(`Failed to create card actions: ${error instanceof Error ? error.message : String(error)}`);
+  }
+};
+
+// src/components/card/media.ts
+/**
+ * Creates a card media component
+ * 
+ * @param {CardMediaConfig} config - Media configuration
+ * @returns {HTMLElement} Card media element
+ * 
+ * @example
+ * ```typescript
+ * // Create a media component with an image
+ * const media = createCardMedia({
+ *   src: 'image.jpg',
+ *   alt: 'Descriptive alt text',
+ *   aspectRatio: '16:9'
+ * });
+ * 
+ * // Create a media component with a custom element
+ * const customMedia = createCardMedia({
+ *   element: videoElement,
+ *   aspectRatio: '4:3'
+ * });
+ * ```
+ */
+export const createCardMedia = (config: any = {}): HTMLElement => {
+  const baseConfig = {
+    ...config,
+    componentName: 'card-media',
+    prefix: PREFIX
+  };
+
+  try {
+    const media = pipe(
+      createBase,
+      withElement({
+        tag: 'div',
+        componentName: 'card-media',
+        className: [
+          config.class,
+          config.aspectRatio ? `${PREFIX}-card-media--${config.aspectRatio.replace(':', '-')}` : null,
+          config.contain ? `${PREFIX}-card-media--contain` : null
+        ]
+      })
+    )(baseConfig);
+
+    // If custom element is provided, use it
+    if (config.element instanceof HTMLElement) {
+      media.element.appendChild(config.element);
+    }
+    // Otherwise create an image if src is provided
+    else if (config.src) {
+      const img = document.createElement('img');
+      img.src = config.src;
+      img.className = `${PREFIX}-card-media-img`;
+      
+      // Ensure alt text is always provided for accessibility
+      img.alt = config.alt || '';
+      if (!config.alt) {
+        // If no alt text is provided, mark as decorative
+        img.setAttribute('aria-hidden', 'true');
+      }
+      
+      media.element.appendChild(img);
+    }
+
+    return media.element;
+  } catch (error) {
+    console.error('Card media creation error:', error instanceof Error ? error.message : String(error));
+    throw new Error(`Failed to create card media: ${error instanceof Error ? error.message : String(error)}`);
+  }
 };