mtrl 0.1.2 → 0.2.0

package/src/components/card/_styles.scss

@@ -0,0 +1,359 @@
+// src/components/card/_card.scss
+@use '../../styles/abstract/base' as base;
+@use '../../styles/abstract/variables' as v;
+@use '../../styles/abstract/functions' as f;
+@use '../../styles/abstract/mixins' as m;
+@use '../../styles/abstract/theme' as t;
+
+$component: '#{base.$prefix}-card';
+
+.#{$component} {
+  // Base styles
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  border-radius: v.shape('medium');
+  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;
+  
+  // Typography
+  @include m.typography('body-medium');
+  
+  // Transition for elevation and hover states
+  @include m.motion-transition(
+    box-shadow,
+    background-color,
+    border-color
+  );
+
+  // Ripple styles for clickable cards
+  .ripple {
+    position: absolute;
+    border-radius: 50%;
+    transform: scale(0);
+    pointer-events: none;
+    background-color: currentColor;
+    opacity: 0.08;
+  }
+  
+  // Ensure proper stacking for inner components
+  > :not(:last-child) {
+    margin-bottom: 0;
+  }
+  
+  // === Variants ===
+  
+  // Elevated variant
+  &--elevated {
+    @include m.elevation(1);
+    
+    &:hover.#{$component}--interactive {
+      @include m.elevation(2);
+    }
+  }
+  
+  // Filled variant
+  &--filled {
+    background-color: t.color('surface-container-highest');
+    
+    &:hover.#{$component}--interactive {
+      @include m.state-layer(t.color('on-surface'), 'hover');
+    }
+  }
+  
+  // Outlined variant
+  &--outlined {
+    border: 1px solid t.color('outline');
+    background-color: t.color('surface');
+    
+    &:hover.#{$component}--interactive {
+      @include m.state-layer(t.color('on-surface'), 'hover');
+      border-color: t.color('outline-variant');
+    }
+  }
+  
+  // === Modifiers ===
+  
+  // Interactive cards
+  &--interactive {
+    cursor: pointer;
+    user-select: none;
+  }
+  
+  // Full-width cards
+  &--full-width {
+    width: 100%;
+  }
+  
+  // === Sub-components ===
+  
+  // Card Header
+  &-header {
+    display: flex;
+    align-items: center;
+    padding: 16px;
+    
+    &-avatar {
+      margin-right: 16px;
+      flex-shrink: 0;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      
+      img {
+        width: 40px;
+        height: 40px;
+        border-radius: 50%;
+        object-fit: cover;
+      }
+    }
+    
+    &-text {
+      flex: 1;
+      overflow: hidden;
+    }
+    
+    &-title {
+      margin: 0;
+      @include m.typography('title-medium');
+      @include m.truncate;
+      color: t.color('on-surface');
+    }
+    
+    &-subtitle {
+      margin: 0;
+      @include m.typography('body-medium');
+      @include m.truncate;
+      color: t.color('on-surface-variant');
+    }
+    
+    &-action {
+      margin-left: 8px;
+      flex-shrink: 0;
+    }
+  }
+  
+  // Card Media
+  &-media {
+    position: relative;
+    overflow: hidden;
+    
+    &-img {
+      display: block;
+      width: 100%;
+      object-fit: cover;
+    }
+    
+    // Aspect ratios
+    &--16-9 {
+      aspect-ratio: 16 / 9;
+      
+      img {
+        height: 100%;
+      }
+    }
+    
+    &--4-3 {
+      aspect-ratio: 4 / 3;
+      
+      img {
+        height: 100%;
+      }
+    }
+    
+    &--1-1 {
+      aspect-ratio: 1 / 1;
+      
+      img {
+        height: 100%;
+      }
+    }
+    
+    &--contain {
+      img {
+        object-fit: contain;
+      }
+    }
+  }
+  
+  // Card Content
+  &-content {
+    padding: 16px;
+    flex: 1 1 auto;
+    
+    > *:first-child {
+      margin-top: 0;
+    }
+    
+    > *:last-child {
+      margin-bottom: 0;
+    }
+    
+    // When content follows media without padding
+    .#{$component}-media + &:not(.#{$component}-content--no-padding) {
+      padding-top: 16px;
+    }
+    
+    // No padding modifier
+    &--no-padding {
+      padding: 0;
+    }
+  }
+  
+  // Card Actions
+  &-actions {
+    display: flex;
+    flex-wrap: wrap;
+    padding: 8px;
+    align-items: center;
+    
+    > * {
+      margin: 0 4px;
+      
+      &:first-child {
+        margin-left: 8px;
+      }
+      
+      &:last-child {
+        margin-right: 8px;
+      }
+    }
+    
+    // Full-bleed actions
+    &--full-bleed {
+      padding: 0;
+      
+      > * {
+        margin: 0;
+        border-radius: 0;
+        flex: 1 1 auto;
+        
+        &:first-child {
+          margin-left: 0;
+        }
+        
+        &:last-child {
+          margin-right: 0;
+        }
+      }
+    }
+    
+    // Vertical actions
+    &--vertical {
+      flex-direction: column;
+      
+      > * {
+        width: 100%;
+        margin: 4px 0;
+        
+        &:first-child {
+          margin-top: 8px;
+        }
+        
+        &:last-child {
+          margin-bottom: 8px;
+        }
+      }
+    }
+    
+    // Alignment variations
+    &--center {
+      justify-content: center;
+    }
+    
+    &--end {
+      justify-content: flex-end;
+    }
+    
+    &--space-between {
+      justify-content: space-between;
+    }
+  }
+  
+  // State classes
+  &--state-disabled {
+    opacity: 0.38;
+    pointer-events: none;
+  }
+  
+  &--state-loading {
+    pointer-events: none;
+  }
+  
+  &--dragging {
+    @include m.elevation(4);
+    opacity: 0.9;
+  }
+  
+  // Loading overlay
+  &-loading-overlay {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background-color: rgba(t.color('surface'), 0.7);
+    z-index: 1;
+  }
+  
+  &-loading-spinner {
+    width: 40px;
+    height: 40px;
+    border-radius: 50%;
+    border: 3px solid rgba(t.color('primary'), 0.2);
+    border-top-color: t.color('primary');
+    animation: card-spinner 1s infinite linear;
+  }
+  
+  // Expandable content
+  &-expandable-content {
+    overflow: hidden;
+    transition: max-height 0.3s ease;
+  }
+  
+  &-expand-button {
+    background: none;
+    border: none;
+    padding: 8px;
+    cursor: pointer;
+    color: t.color('primary');
+    
+    &::before {
+      content: '';
+      display: inline-block;
+      width: 10px;
+      height: 10px;
+      border-right: 2px solid currentColor;
+      border-bottom: 2px solid currentColor;
+      transform: rotate(45deg);
+      transition: transform 0.3s ease;
+    }
+    
+    &[aria-expanded="true"]::before {
+      transform: rotate(-135deg);
+    }
+  }
+  
+  // Swipeable card
+  &--swipeable {
+    touch-action: pan-y;
+    transition: transform 0.3s ease;
+  }
+}
+
+// Spinner animation
+@keyframes card-spinner {
+  0% {
+    transform: rotate(0deg);
+  }
+  100% {
+    transform: rotate(360deg);
+  }
+}

package/src/components/card/actions.ts

@@ -0,0 +1,48 @@
+// src/components/card/actions.ts
+import { PREFIX } from '../../core/config';
+import { pipe } from '../../core/compose';
+import { createBase, withElement } from '../../core/compose/component';
+import { CardActionsConfig } from './types';
+
+/**
+ * Creates a card actions component
+ * @param {CardActionsConfig} config - Actions configuration
+ * @returns {HTMLElement} Card actions element
+ */
+export const createCardActions = (config: CardActionsConfig = {}): 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
+        ]
+      })
+    )(baseConfig);
+
+    // Add action elements if provided
+    if (Array.isArray(config.actions)) {
+      config.actions.forEach(action => {
+        if (action instanceof HTMLElement) {
+          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)}`);
+  }
+};

package/src/components/card/api.ts

@@ -0,0 +1,102 @@
+// src/components/card/api.ts
+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
+ */
+export const withAPI = ({ lifecycle }: ApiOptions) => (component: BaseComponent): CardComponent => ({
+  ...component,
+  element: component.element,
+
+  /**
+   * Adds content to the card
+   * @param {HTMLElement} contentElement - The content element to add
+   * @returns {CardComponent} The card instance for chaining
+   */
+  addContent(contentElement: HTMLElement): CardComponent {
+    if (contentElement && contentElement.classList.contains(`${component.getClass('card')}-content`)) {
+      component.element.appendChild(contentElement);
+    }
+    return this;
+  },
+
+  /**
+   * Sets the card header
+   * @param {HTMLElement} headerElement - The header element to add
+   * @returns {CardComponent} The card instance for chaining
+   */
+  setHeader(headerElement: HTMLElement): CardComponent {
+    if (headerElement && headerElement.classList.contains(`${component.getClass('card')}-header`)) {
+      // Remove existing header if present
+      const existingHeader = component.element.querySelector(`.${component.getClass('card')}-header`);
+      if (existingHeader) {
+        existingHeader.remove();
+      }
+
+      // Insert at the beginning of the card
+      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
+   */
+  addMedia(mediaElement: HTMLElement, position: 'top' | 'bottom' = 'top'): CardComponent {
+    if (mediaElement && mediaElement.classList.contains(`${component.getClass('card')}-media`)) {
+      if (position === 'top') {
+        component.element.insertBefore(mediaElement, component.element.firstChild);
+      } else {
+        component.element.appendChild(mediaElement);
+      }
+    }
+    return this;
+  },
+
+  /**
+   * Sets the card actions section
+   * @param {HTMLElement} actionsElement - The actions element to add
+   * @returns {CardComponent} The card instance for chaining
+   */
+  setActions(actionsElement: HTMLElement): CardComponent {
+    if (actionsElement && actionsElement.classList.contains(`${component.getClass('card')}-actions`)) {
+      // Remove existing actions if present
+      const existingActions = component.element.querySelector(`.${component.getClass('card')}-actions`);
+      if (existingActions) {
+        existingActions.remove();
+      }
+
+      // Add actions at the end
+      component.element.appendChild(actionsElement);
+    }
+    return this;
+  },
+
+  /**
+   * 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');
+
+    if (typeof dragStartCallback === 'function') {
+      component.element.addEventListener('dragstart', dragStartCallback as EventListener);
+    }
+
+    return this;
+  },
+
+  /**
+   * Destroys the card component and removes event listeners
+   */
+  destroy(): void {
+    lifecycle.destroy();
+  }
+});

package/src/components/card/card.ts

@@ -0,0 +1,41 @@
+// src/components/card/card.ts
+import { pipe } from '../../core/compose';
+import { createBase, withElement } from '../../core/compose/component';
+import {
+  withEvents,
+  withVariant,
+  withRipple,
+  withLifecycle
+} from '../../core/compose/features';
+import { withAPI } from './api';
+import { CardComponent, BaseComponent, CardSchema } from './types';
+import { createBaseConfig, getElementConfig, getApiConfig, withInteractiveBehavior } from './config';
+
+/**
+ * Creates a new Card component following Material Design 3 principles
+ * @param {CardSchema} config - Card configuration object
+ * @returns {CardComponent} Card component instance
+ */
+const createCard = (config: CardSchema = {}): CardComponent => {
+  const baseConfig = createBaseConfig(config);
+
+  try {
+    const card = pipe(
+      createBase,
+      withEvents(),
+      withElement(getElementConfig(baseConfig)),
+      withVariant(baseConfig),
+      config.clickable ? withRipple(baseConfig) : (c: BaseComponent) => c,
+      withLifecycle(),
+      withInteractiveBehavior,
+      comp => withAPI(getApiConfig(comp))(comp)
+    )(baseConfig);
+
+    return card as CardComponent;
+  } 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)}`);
+  }
+};
+
+export default createCard;

package/src/components/card/config.ts

@@ -0,0 +1,99 @@
+// src/components/card/config.ts
+import { 
+  createComponentConfig, 
+  createElementConfig,
+  BaseComponentConfig 
+} from '../../core/config/component-config';
+import { BaseComponent, CardSchema } from './types';
+import { CARD_VARIANTS, CARD_ELEVATIONS } from './constants';
+
+/**
+ * Default configuration for the Card component
+ */
+export const defaultConfig: CardSchema = {
+  variant: CARD_VARIANTS.ELEVATED,
+  interactive: false,
+  fullWidth: false,
+  clickable: false,
+  draggable: false
+};
+
+/**
+ * Creates the base configuration for Card component
+ * @param {CardSchema} config - User provided configuration
+ * @returns {CardSchema} Complete configuration with defaults applied
+ */
+export const createBaseConfig = (config: CardSchema = {}): CardSchema => 
+  createComponentConfig(defaultConfig, config, 'card') as 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, {
+    tag: 'div',
+    className: [
+      config.class,
+      config.fullWidth ? `${config.prefix}-card--full-width` : null,
+      config.interactive ? `${config.prefix}-card--interactive` : null
+    ],
+    forwardEvents: {
+      click: (component: BaseComponent) => !!config.clickable,
+      mouseenter: (component: BaseComponent) => !!config.interactive,
+      mouseleave: (component: BaseComponent) => !!config.interactive
+    },
+    interactive: config.interactive || config.clickable
+  });
+
+/**
+ * Creates API configuration for the Card component
+ * @param {Object} comp - Component with lifecycle feature
+ * @returns {Object} API configuration object
+ */
+export const getApiConfig = (comp) => ({
+  lifecycle: {
+    destroy: () => comp.lifecycle?.destroy?.()
+  }
+});
+
+/**
+ * Adds interactive behavior to card component
+ * @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) {
+    comp.element.addEventListener('mouseenter', () => {
+      if (comp.config.variant === CARD_VARIANTS.ELEVATED) {
+        comp.element.style.setProperty('--card-elevation', String(CARD_ELEVATIONS.HOVERED));
+      }
+    });
+
+    comp.element.addEventListener('mouseleave', () => {
+      if (comp.config.variant === CARD_VARIANTS.ELEVATED) {
+        comp.element.style.setProperty('--card-elevation', String(CARD_ELEVATIONS.RESTING));
+      }
+    });
+  }
+
+  // Set up draggable
+  if (comp.config.draggable) {
+    comp.element.setAttribute('draggable', 'true');
+    comp.element.addEventListener('dragstart', (e) => {
+      comp.element.style.setProperty('--card-elevation', String(CARD_ELEVATIONS.DRAGGED));
+      comp.emit?.('dragstart', { event: e });
+    });
+
+    comp.element.addEventListener('dragend', (e) => {
+      comp.element.style.setProperty('--card-elevation', String(CARD_ELEVATIONS.RESTING));
+      comp.emit?.('dragend', { event: e });
+    });
+  }
+
+  return comp;
+};
+
+export default defaultConfig;

package/src/components/card/constants.ts

@@ -0,0 +1,69 @@
+// src/components/card/constants.ts
+import { CardVariant, CardElevation } from './types';
+
+/**
+ * Card variant types following Material Design 3
+ * @enum {string}
+ */
+export const CARD_VARIANTS = {
+  ELEVATED: CardVariant.ELEVATED,
+  FILLED: CardVariant.FILLED,
+  OUTLINED: CardVariant.OUTLINED
+};
+
+/**
+ * Card elevation levels
+ * @enum {number}
+ */
+export const CARD_ELEVATIONS = {
+  RESTING: CardElevation.RESTING,
+  HOVERED: CardElevation.HOVERED,
+  DRAGGED: CardElevation.DRAGGED
+};
+
+/**
+ * Validation schema for card configuration
+ */
+export const CARD_SCHEMA = {
+  variant: {
+    type: 'string',
+    enum: Object.values(CARD_VARIANTS),
+    default: CARD_VARIANTS.ELEVATED
+  },
+  interactive: {
+    type: 'boolean',
+    default: false
+  },
+  fullWidth: {
+    type: 'boolean',
+    default: false
+  },
+  clickable: {
+    type: 'boolean',
+    default: false
+  },
+  draggable: {
+    type: 'boolean',
+    default: false
+  },
+  class: {
+    type: 'string',
+    required: false
+  },
+  headerConfig: {
+    type: 'object',
+    required: false
+  },
+  contentConfig: {
+    type: 'object',
+    required: false
+  },
+  actionsConfig: {
+    type: 'object',
+    required: false
+  },
+  mediaConfig: {
+    type: 'object',
+    required: false
+  }
+};