mtrl 0.2.5 → 0.2.7

package/src/components/card/_styles.scss

@@ -1,4 +1,4 @@
-// src/components/card/_card.scss
+// src/components/card/_styles.scss
 @use '../../styles/abstract/base' as base;
 @use '../../styles/abstract/variables' as v;
 @use '../../styles/abstract/functions' as f;
@@ -13,23 +13,33 @@ $component: '#{base.$prefix}-card';
   display: flex;
   flex-direction: column;
   box-sizing: border-box;
-  border-radius: v.shape('medium');
+  border-radius: f.get-shape('medium'); // Use function for MD3 standard shape
   background-color: t.color('surface');
   color: t.color('on-surface');
   overflow: hidden;
-  width: 320px; // Fixed width since v.card() isn't available
-  --card-elevation: 1;
+  width: v.card('width'); // Use card width variable
+  --card-elevation: 0;
   
-  // Typography
+  // Typography - use mixin
   @include m.typography('body-medium');
   
-  // Transition for elevation and hover states
+  // Transition for elevation and hover states - use motion-transition mixin
   @include m.motion-transition(
     box-shadow,
     background-color,
     border-color
   );
 
+  // Focus outline for accessibility - use focus-ring mixin
+  &:focus-visible {
+    @include m.focus-ring(t.color('secondary'));
+  }
+
+  // Focus state class
+  &--focused {
+    @include m.focus-ring(t.color('secondary'));
+  }
+
   // Ripple styles for clickable cards
   .ripple {
     position: absolute;
@@ -37,7 +47,7 @@ $component: '#{base.$prefix}-card';
     transform: scale(0);
     pointer-events: none;
     background-color: currentColor;
-    opacity: 0.08;
+    opacity: f.get-state-opacity('hover'); // Use function for standard opacity
   }
   
   // Ensure proper stacking for inner components
@@ -45,35 +55,50 @@ $component: '#{base.$prefix}-card';
     margin-bottom: 0;
   }
   
-  // === Variants ===
+  // === Variants - use proper theme colors ===
   
   // Elevated variant
   &--elevated {
-    @include m.elevation(1);
+    background-color: t.color('surface-container-low');
+    @include m.elevation(1); // Use elevation mixin
     
     &:hover.#{$component}--interactive {
-      @include m.elevation(2);
+      @include m.elevation(2); // Use elevation mixin for hover state
+    }
+
+    &:active.#{$component}--interactive {
+      @include m.state-layer(t.color('on-surface'), 'pressed'); // Use state-layer mixin
     }
   }
   
   // Filled variant
   &--filled {
     background-color: t.color('surface-container-highest');
+    @include m.elevation(0); // No elevation
     
     &:hover.#{$component}--interactive {
       @include m.state-layer(t.color('on-surface'), 'hover');
     }
+
+    &:active.#{$component}--interactive {
+      @include m.state-layer(t.color('on-surface'), 'pressed');
+    }
   }
   
   // Outlined variant
   &--outlined {
     border: 1px solid t.color('outline');
     background-color: t.color('surface');
+    @include m.elevation(0); // No elevation
     
     &:hover.#{$component}--interactive {
       @include m.state-layer(t.color('on-surface'), 'hover');
       border-color: t.color('outline-variant');
     }
+
+    &:active.#{$component}--interactive {
+      @include m.state-layer(t.color('on-surface'), 'pressed');
+    }
   }
   
   // === Modifiers ===
@@ -95,10 +120,11 @@ $component: '#{base.$prefix}-card';
   &-header {
     display: flex;
     align-items: center;
-    padding: 16px;
-    
+    padding: v.card('padding');
+    padding-bottom: 0;
+
     &-avatar {
-      margin-right: 16px;
+      margin-right: v.card('padding');
       flex-shrink: 0;
       display: flex;
       align-items: center;
@@ -119,7 +145,7 @@ $component: '#{base.$prefix}-card';
     
     &-title {
       margin: 0;
-      @include m.typography('title-medium');
+      @include m.typography('title-large');
       @include m.truncate;
       color: t.color('on-surface');
     }
@@ -141,7 +167,7 @@ $component: '#{base.$prefix}-card';
   &-media {
     position: relative;
     overflow: hidden;
-    
+    border-radius: f.get-shape('medium');
     &-img {
       display: block;
       width: 100%;
@@ -182,7 +208,7 @@ $component: '#{base.$prefix}-card';
   
   // Card Content
   &-content {
-    padding: 16px;
+    padding: v.card('padding');
     flex: 1 1 auto;
     
     > *:first-child {
@@ -195,7 +221,7 @@ $component: '#{base.$prefix}-card';
     
     // When content follows media without padding
     .#{$component}-media + &:not(.#{$component}-content--no-padding) {
-      padding-top: 16px;
+      padding-top: v.card('padding');
     }
     
     // No padding modifier
@@ -276,7 +302,7 @@ $component: '#{base.$prefix}-card';
   
   // State classes
   &--state-disabled {
-    opacity: 0.38;
+    opacity: 0.38; // Use MTRL standard opacity
     pointer-events: none;
   }
   
@@ -285,7 +311,7 @@ $component: '#{base.$prefix}-card';
   }
   
   &--dragging {
-    @include m.elevation(4);
+    @include m.elevation(4); // Use elevation mixin
     opacity: 0.9;
   }
   
@@ -299,15 +325,15 @@ $component: '#{base.$prefix}-card';
     display: flex;
     align-items: center;
     justify-content: center;
-    background-color: rgba(t.color('surface'), 0.7);
-    z-index: 1;
+    background-color: t.alpha('surface', 0.7);
+    z-index: f.get-z-index('default');
   }
   
   &-loading-spinner {
     width: 40px;
     height: 40px;
     border-radius: 50%;
-    border: 3px solid rgba(t.color('primary'), 0.2);
+    border: 3px solid t.alpha('primary', 0.2);
     border-top-color: t.color('primary');
     animation: card-spinner 1s infinite linear;
   }
@@ -315,7 +341,7 @@ $component: '#{base.$prefix}-card';
   // Expandable content
   &-expandable-content {
     overflow: hidden;
-    transition: max-height 0.3s ease;
+    transition: max-height f.get-motion-duration('medium1') f.get-motion-easing('standard');
   }
   
   &-expand-button {
@@ -324,6 +350,9 @@ $component: '#{base.$prefix}-card';
     padding: 8px;
     cursor: pointer;
     color: t.color('primary');
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
     
     &::before {
       content: '';
@@ -333,7 +362,7 @@ $component: '#{base.$prefix}-card';
       border-right: 2px solid currentColor;
       border-bottom: 2px solid currentColor;
       transform: rotate(45deg);
-      transition: transform 0.3s ease;
+      transition: transform f.get-motion-duration('short2') f.get-motion-easing('standard');
     }
     
     &[aria-expanded="true"]::before {
@@ -344,7 +373,13 @@ $component: '#{base.$prefix}-card';
   // Swipeable card
   &--swipeable {
     touch-action: pan-y;
-    transition: transform 0.3s ease;
+    transition: transform f.get-motion-duration('medium1') f.get-motion-easing('standard');
+  }
+  
+  // Hidden buttons for accessibility
+  &-swipe-left-action,
+  &-swipe-right-action {
+    @include m.visually-hidden; // Use visually-hidden mixin
   }
 }
 
@@ -356,4 +391,11 @@ $component: '#{base.$prefix}-card';
   100% {
     transform: rotate(360deg);
   }
+}
+
+// Media query for responsive adjustments
+@include m.breakpoint-down('sm') {
+  .#{$component} {
+    width: 100%; // Full width on small screens
+  }
 }

package/src/components/card/api.ts

@@ -3,6 +3,7 @@ import { BaseComponent, CardComponent, ApiOptions } from './types';
 
 /**
  * Enhances a card component with API methods
+ * 
  * @param {ApiOptions} options - API configuration options
  * @returns {Function} Higher-order function that adds API methods to component
  * @internal This is an internal utility for the Card component
@@ -13,6 +14,7 @@ export const withAPI = ({ lifecycle }: ApiOptions) => (component: BaseComponent)
 
   /**
    * Adds content to the card
+   * 
    * @param {HTMLElement} contentElement - The content element to add
    * @returns {CardComponent} The card instance for chaining
    */
@@ -25,8 +27,18 @@ export const withAPI = ({ lifecycle }: ApiOptions) => (component: BaseComponent)
 
   /**
    * Sets the card header
+   * 
+   * Places the header element in the card. When media elements exist,
+   * the header is placed after the last media element to ensure proper 
+   * visual hierarchy following Material Design guidelines.
+   * 
    * @param {HTMLElement} headerElement - The header element to add
    * @returns {CardComponent} The card instance for chaining
+   * @example
+   * ```typescript
+   * // Add a header after media
+   * card.setHeader(headerElement);
+   * ```
    */
   setHeader(headerElement: HTMLElement): CardComponent {
     if (headerElement && headerElement.classList.contains(`${component.getClass('card')}-header`)) {
@@ -36,14 +48,32 @@ export const withAPI = ({ lifecycle }: ApiOptions) => (component: BaseComponent)
         existingHeader.remove();
       }
 
-      // Insert at the beginning of the card
-      component.element.insertBefore(headerElement, component.element.firstChild);
+      // Look for media element
+      const mediaElement = component.element.querySelector(`.${component.getClass('card')}-media`);
+      
+      if (mediaElement) {
+        // If media exists, insert after the LAST media element
+        // Find all media elements
+        const mediaElements = component.element.querySelectorAll(`.${component.getClass('card')}-media`);
+        const lastMedia = mediaElements[mediaElements.length - 1];
+        
+        // Insert after the last media element
+        if (lastMedia.nextSibling) {
+          component.element.insertBefore(headerElement, lastMedia.nextSibling);
+        } else {
+          component.element.appendChild(headerElement);
+        }
+      } else {
+        // No media, insert at the beginning
+        component.element.insertBefore(headerElement, component.element.firstChild);
+      }
     }
     return this;
   },
 
   /**
    * Adds media to the card
+   * 
    * @param {HTMLElement} mediaElement - The media element to add
    * @param {string} [position='top'] - Position to place media ('top', 'bottom')
    * @returns {CardComponent} The card instance for chaining
@@ -61,6 +91,7 @@ export const withAPI = ({ lifecycle }: ApiOptions) => (component: BaseComponent)
 
   /**
    * Sets the card actions section
+   * 
    * @param {HTMLElement} actionsElement - The actions element to add
    * @returns {CardComponent} The card instance for chaining
    */
@@ -80,19 +111,39 @@ export const withAPI = ({ lifecycle }: ApiOptions) => (component: BaseComponent)
 
   /**
    * Makes the card draggable
+   * 
    * @param {Function} [dragStartCallback] - Callback for drag start event
    * @returns {CardComponent} The card instance for chaining
    */
   makeDraggable(dragStartCallback?: (event: DragEvent) => void): CardComponent {
     component.element.setAttribute('draggable', 'true');
+    component.element.setAttribute('aria-grabbed', 'false');
 
     if (typeof dragStartCallback === 'function') {
-      component.element.addEventListener('dragstart', dragStartCallback as EventListener);
+      component.element.addEventListener('dragstart', (e: DragEvent) => {
+        component.element.setAttribute('aria-grabbed', 'true');
+        dragStartCallback(e);
+      });
+      
+      component.element.addEventListener('dragend', () => {
+        component.element.setAttribute('aria-grabbed', 'false');
+      });
     }
 
     return this;
   },
 
+  /**
+   * Sets focus to the card
+   * Useful for programmatic focus management
+   * 
+   * @returns {CardComponent} The card instance for chaining
+   */
+  focus(): CardComponent {
+    component.element.focus();
+    return this;
+  },
+
   /**
    * Destroys the card component and removes event listeners
    */

package/src/components/card/card.ts

@@ -9,29 +9,48 @@ import {
 } from '../../core/compose/features';
 import { withAPI } from './api';
 import { CardComponent, BaseComponent, CardSchema } from './types';
-import { createBaseConfig, getElementConfig, getApiConfig, withInteractiveBehavior } from './config';
+import { 
+  createBaseConfig, 
+  getElementConfig, 
+  getApiConfig, 
+  withInteractiveBehavior,
+  processInlineConfig,
+  applyInlineConfiguration
+} from './config';
+import { withElevation } from './features';
 
 /**
  * Creates a new Card component following Material Design 3 principles
+ * 
+ * Material Design 3 Cards are surfaces that display content and actions about a single topic.
+ * Cards can contain text, media, and UI controls.
+ * 
  * @param {CardSchema} config - Card configuration object
  * @returns {CardComponent} Card component instance
  */
 const createCard = (config: CardSchema = {}): CardComponent => {
-  const baseConfig = createBaseConfig(config);
+  // Process inline configuration (map shorthand properties)
+  const processedConfig = processInlineConfig(config);
+  const baseConfig = createBaseConfig(processedConfig);
 
   try {
+    // Create the core card component
     const card = pipe(
       createBase,
       withEvents(),
       withElement(getElementConfig(baseConfig)),
       withVariant(baseConfig),
-      config.clickable ? withRipple(baseConfig) : (c: BaseComponent) => c,
+      baseConfig.clickable ? withRipple(baseConfig) : (c: BaseComponent) => c,
       withLifecycle(),
       withInteractiveBehavior,
+      withElevation,
       comp => withAPI(getApiConfig(comp))(comp)
-    )(baseConfig);
-
-    return card as CardComponent;
+    )(baseConfig) as CardComponent;
+    
+    // Apply any inline configuration
+    applyInlineConfiguration(card, processedConfig);
+    
+    return card;
   } catch (error) {
     console.error('Card creation error:', error instanceof Error ? error.message : String(error));
     throw new Error(`Failed to create card: ${error instanceof Error ? error.message : String(error)}`);