mtrl 0.1.2 → 0.1.3

package/index.js

@@ -2,10 +2,10 @@
 import {
   createLayout,
   createElement,
-  createButton, createCheckbox, createTextfield, createSwitch, createContainer, createList, createSnackbar, createNavigation, createMenu
+  createButton, createCard, createCheckbox, createTextfield, createSwitch, createContainer, createList, createSnackbar, createNavigation, createMenu
 } from './src/index.js'
 
 export {
   createLayout,
-  createElement, createButton, createCheckbox, createTextfield, createSwitch, createContainer, createList, createSnackbar, createNavigation, createMenu
+  createElement, createCard, createButton, createCheckbox, createTextfield, createSwitch, createContainer, createList, createSnackbar, createNavigation, createMenu
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrl",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A functional JavaScript component library with composable architecture based on Material Design 3",
   "keywords": ["component", "library", "ui", "user interface", "functional", "composable"],
   "main": "index.js",

package/src/components/card/actions.js

@@ -0,0 +1,51 @@
+// src/components/card/actions.js
+import { PREFIX } from '../../core/config'
+import { pipe } from '../../core/compose'
+import { createBase, withElement } from '../../core/compose/component'
+
+/**
+ * Creates a card actions component
+ * @param {Object} config - Actions configuration
+ * @param {Array<HTMLElement>} [config.actions] - Action elements to include
+ * @param {boolean} [config.fullBleed=false] - Whether actions extend full width
+ * @param {boolean} [config.vertical=false] - Whether to stack actions vertically
+ * @param {string} [config.align='start'] - Horizontal alignment ('start', 'center', 'end', 'space-between')
+ * @returns {HTMLElement} Card actions element
+ */
+export const createCardActions = (config = {}) => {
+  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)
+    throw new Error(`Failed to create card actions: ${error.message}`)
+  }
+}

package/src/components/card/api.js

@@ -0,0 +1,102 @@
+// src/components/card/api.js
+
+/**
+ * Enhances a card component with API methods
+ * @param {Object} options - API configuration options
+ * @param {Object} options.lifecycle - Object containing lifecycle methods
+ * @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 }) => (component) => ({
+  ...component,
+  element: component.element,
+
+  /**
+   * Adds content to the card
+   * @param {HTMLElement} contentElement - The content element to add
+   * @returns {Object} The card instance for chaining
+   */
+  addContent (contentElement) {
+    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 {Object} The card instance for chaining
+   */
+  setHeader (headerElement) {
+    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 {Object} The card instance for chaining
+   */
+  addMedia (mediaElement, position = 'top') {
+    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 {Object} The card instance for chaining
+   */
+  setActions (actionsElement) {
+    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 {Object} The card instance for chaining
+   */
+  makeDraggable (dragStartCallback) {
+    component.element.setAttribute('draggable', 'true')
+
+    if (typeof dragStartCallback === 'function') {
+      component.element.addEventListener('dragstart', dragStartCallback)
+    }
+
+    return this
+  },
+
+  /**
+   * Destroys the card component and removes event listeners
+   */
+  destroy () {
+    lifecycle.destroy()
+  }
+})

package/src/components/card/card.js

@@ -0,0 +1,102 @@
+// src/components/card/card.js
+import { PREFIX } from '../../core/config'
+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 { CARD_VARIANTS, CARD_ELEVATIONS } from './constants'
+import defaultConfig from './config'
+
+/**
+ * Creates a new Card component following Material Design 3 principles
+ * @param {Object} config - Card configuration object
+ * @param {string} [config.variant='elevated'] - Card variant (elevated, filled, outlined)
+ * @param {boolean} [config.interactive=false] - Whether the card has hover/focus states
+ * @param {boolean} [config.fullWidth=false] - Whether the card spans full width of container
+ * @param {boolean} [config.clickable=false] - Whether the card is clickable with ripple effect
+ * @param {boolean} [config.draggable=false] - Whether the card is draggable
+ * @param {string} [config.class] - Additional CSS classes
+ * @returns {Object} Card component instance
+ */
+const createCard = (config = {}) => {
+  const baseConfig = {
+    ...defaultConfig,
+    ...config,
+    componentName: 'card',
+    prefix: PREFIX
+  }
+
+  try {
+    const card = pipe(
+      createBase,
+      withEvents(),
+      withElement({
+        tag: 'div',
+        componentName: 'card',
+        className: [
+          config.class,
+          config.fullWidth ? `${PREFIX}-card--full-width` : null,
+          config.interactive ? `${PREFIX}-card--interactive` : null
+        ],
+        forwardEvents: {
+          click: (component) => config.clickable,
+          mouseenter: (component) => config.interactive,
+          mouseleave: (component) => config.interactive
+        },
+        interactive: config.interactive || config.clickable
+      }),
+      withVariant(baseConfig),
+      config.clickable ? withRipple(baseConfig) : (c) => c,
+      withLifecycle(),
+      comp => {
+        // 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', CARD_ELEVATIONS.HOVERED)
+            }
+          })
+
+          comp.element.addEventListener('mouseleave', () => {
+            if (comp.config.variant === CARD_VARIANTS.ELEVATED) {
+              comp.element.style.setProperty('--card-elevation', 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', CARD_ELEVATIONS.DRAGGED)
+            comp.emit('dragstart', { event: e })
+          })
+
+          comp.element.addEventListener('dragend', (e) => {
+            comp.element.style.setProperty('--card-elevation', CARD_ELEVATIONS.RESTING)
+            comp.emit('dragend', { event: e })
+          })
+        }
+
+        return comp
+      },
+      comp => withAPI({
+        lifecycle: {
+          destroy: () => comp.lifecycle.destroy()
+        }
+      })(comp)
+    )(baseConfig)
+
+    return card
+  } catch (error) {
+    console.error('Card creation error:', error)
+    throw new Error(`Failed to create card: ${error.message}`)
+  }
+}
+
+export default createCard

package/src/components/card/config.js

@@ -0,0 +1,16 @@
+// src/components/card/config.js
+
+import { PREFIX } from '../../core/config'
+import { CARD_VARIANTS } from './constants'
+
+const defaultConfig = {
+  componentName: 'card',
+  prefix: PREFIX,
+  variant: CARD_VARIANTS.ELEVATED,
+  interactive: false,
+  fullWidth: false,
+  clickable: false,
+  draggable: false
+}
+
+export default defaultConfig

package/src/components/card/constants.js

@@ -0,0 +1,68 @@
+// src/components/card/constants.js
+
+/**
+ * Card variant types following Material Design 3
+ * @enum {string}
+ */
+export const CARD_VARIANTS = {
+  ELEVATED: 'elevated',
+  FILLED: 'filled',
+  OUTLINED: 'outlined'
+}
+
+/**
+ * Card elevation levels
+ * @enum {number}
+ */
+export const CARD_ELEVATIONS = {
+  RESTING: 1,
+  HOVERED: 2,
+  DRAGGED: 4
+}
+
+/**
+ * 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
+  }
+}

package/src/components/card/content.js

@@ -0,0 +1,51 @@
+// src/components/card/content.js
+import { PREFIX } from '../../core/config'
+import { pipe } from '../../core/compose'
+import { createBase, withElement } from '../../core/compose/component'
+
+/**
+ * Creates a card content component
+ * @param {Object} config - Content configuration
+ * @param {string} [config.text] - Text content
+ * @param {string} [config.html] - HTML content
+ * @param {Array<HTMLElement>} [config.children] - Child elements to append
+ * @param {boolean} [config.padding=true] - Whether to apply default padding
+ * @returns {HTMLElement} Card content element
+ */
+export const createCardContent = (config = {}) => {
+  const baseConfig = {
+    ...config,
+    componentName: 'card-content',
+    prefix: PREFIX
+  }
+
+  try {
+    const content = pipe(
+      createBase,
+      withElement({
+        tag: 'div',
+        componentName: 'card-content',
+        className: [
+          config.class,
+          config.padding === false ? `${PREFIX}-card-content--no-padding` : null
+        ],
+        html: config.html,
+        text: config.text
+      })
+    )(baseConfig)
+
+    // Add children if provided
+    if (Array.isArray(config.children)) {
+      config.children.forEach(child => {
+        if (child instanceof HTMLElement) {
+          content.element.appendChild(child)
+        }
+      })
+    }
+
+    return content.element
+  } catch (error) {
+    console.error('Card content creation error:', error)
+    throw new Error(`Failed to create card content: ${error.message}`)
+  }
+}

package/src/components/card/features.js

@@ -0,0 +1,218 @@
+// src/components/card/features.js
+import { PREFIX } from '../../core/config'
+import { createElement } from '../../core/dom/create'
+
+/**
+ * Higher-order function to add loading state to a card
+ * @param {Object} config - Loading state configuration
+ * @param {boolean} [config.initialState=false] - Initial loading state
+ * @returns {Function} Card component enhancer
+ */
+export const withLoading = (config = {}) => (component) => {
+  const initialState = config.initialState || false
+  let loadingElement = null
+  let isLoading = initialState
+
+  if (initialState) {
+    setLoading(true)
+  }
+
+  function setLoading (loading) {
+    isLoading = loading
+
+    if (loading && !loadingElement) {
+      // Create and add loading overlay
+      loadingElement = createElement({
+        tag: 'div',
+        className: `${PREFIX}-card-loading-overlay`,
+        container: component.element
+      })
+
+      // Add spinner
+      createElement({
+        tag: 'div',
+        className: `${PREFIX}-card-loading-spinner`,
+        container: loadingElement
+      })
+
+      component.element.classList.add(`${PREFIX}-card--state-loading`)
+    } else if (!loading && loadingElement) {
+      // Remove loading overlay
+      loadingElement.remove()
+      loadingElement = null
+      component.element.classList.remove(`${PREFIX}-card--state-loading`)
+    }
+  }
+
+  return {
+    ...component,
+    loading: {
+      isLoading: () => isLoading,
+      setLoading
+    }
+  }
+}
+
+/**
+ * Higher-order function to add expandable behavior to a card
+ * @param {Object} config - Expandable configuration
+ * @param {boolean} [config.initialExpanded=false] - Whether card is initially expanded
+ * @param {HTMLElement} [config.expandableContent] - Content to show when expanded
+ * @returns {Function} Card component enhancer
+ */
+export const withExpandable = (config = {}) => (component) => {
+  const initialExpanded = config.initialExpanded || false
+  let isExpanded = initialExpanded
+  const expandableContent = config.expandableContent
+  let expandButton = null
+
+  // Create expand/collapse button
+  expandButton = createElement({
+    tag: 'button',
+    className: `${PREFIX}-card-expand-button`,
+    attrs: {
+      'aria-expanded': isExpanded ? 'true' : 'false',
+      'aria-label': isExpanded ? 'Collapse' : 'Expand'
+    }
+  })
+
+  // Add to card as action if not already present
+  const actionsContainer = component.element.querySelector(`.${PREFIX}-card-actions`)
+  if (actionsContainer) {
+    actionsContainer.appendChild(expandButton)
+  } else {
+    // Create actions container if not present
+    const newActionsContainer = createElement({
+      tag: 'div',
+      className: `${PREFIX}-card-actions`,
+      container: component.element
+    })
+    newActionsContainer.appendChild(expandButton)
+  }
+
+  // Set initial state
+  if (expandableContent) {
+    expandableContent.classList.add(`${PREFIX}-card-expandable-content`)
+    if (!initialExpanded) {
+      expandableContent.style.display = 'none'
+    }
+    component.element.appendChild(expandableContent)
+  }
+
+  // Toggle expanded state
+  function toggleExpanded () {
+    setExpanded(!isExpanded)
+  }
+
+  // Set expanded state
+  function setExpanded (expanded) {
+    isExpanded = expanded
+
+    if (expandableContent) {
+      expandableContent.style.display = expanded ? 'block' : 'none'
+    }
+
+    expandButton.setAttribute('aria-expanded', expanded ? 'true' : 'false')
+    expandButton.setAttribute('aria-label', expanded ? 'Collapse' : 'Expand')
+
+    if (expanded) {
+      component.element.classList.add(`${PREFIX}-card--expanded`)
+    } else {
+      component.element.classList.remove(`${PREFIX}-card--expanded`)
+    }
+
+    component.emit('expandedChanged', { expanded })
+  }
+
+  // Add click handler to toggle button
+  expandButton.addEventListener('click', (e) => {
+    e.stopPropagation()
+    toggleExpanded()
+  })
+
+  return {
+    ...component,
+    expandable: {
+      isExpanded: () => isExpanded,
+      setExpanded,
+      toggleExpanded
+    }
+  }
+}
+
+/**
+ * Higher-order function to add swipeable behavior to a card
+ * @param {Object} config - Swipeable configuration
+ * @param {Function} [config.onSwipeLeft] - Callback when card is swiped left
+ * @param {Function} [config.onSwipeRight] - Callback when card is swiped right
+ * @param {number} [config.threshold=100] - Swipe distance threshold to trigger action
+ * @returns {Function} Card component enhancer
+ */
+export const withSwipeable = (config = {}) => (component) => {
+  const threshold = config.threshold || 100
+  let startX = 0
+  let currentX = 0
+
+  function handleTouchStart (e) {
+    startX = e.touches[0].clientX
+    component.element.style.transition = 'none'
+  }
+
+  function handleTouchMove (e) {
+    if (!startX) return
+
+    currentX = e.touches[0].clientX
+    const diffX = currentX - startX
+
+    // Apply transform to move card
+    component.element.style.transform = `translateX(${diffX}px)`
+  }
+
+  function handleTouchEnd () {
+    if (!startX) return
+
+    component.element.style.transition = 'transform 0.3s ease'
+    const diffX = currentX - startX
+
+    if (Math.abs(diffX) >= threshold) {
+      // Swipe threshold reached
+      if (diffX > 0 && config.onSwipeRight) {
+        // Swipe right
+        component.element.style.transform = 'translateX(100%)'
+        config.onSwipeRight(component)
+      } else if (diffX < 0 && config.onSwipeLeft) {
+        // Swipe left
+        component.element.style.transform = 'translateX(-100%)'
+        config.onSwipeLeft(component)
+      } else {
+        // Reset if no handler
+        component.element.style.transform = 'translateX(0)'
+      }
+    } else {
+      // Reset if below threshold
+      component.element.style.transform = 'translateX(0)'
+    }
+
+    startX = 0
+    currentX = 0
+  }
+
+  // Add event listeners
+  component.element.addEventListener('touchstart', handleTouchStart)
+  component.element.addEventListener('touchmove', handleTouchMove)
+  component.element.addEventListener('touchend', handleTouchEnd)
+
+  // Add swipeable class
+  component.element.classList.add(`${PREFIX}-card--swipeable`)
+
+  // Return enhanced component
+  return {
+    ...component,
+    swipeable: {
+      reset: () => {
+        component.element.style.transition = 'transform 0.3s ease'
+        component.element.style.transform = 'translateX(0)'
+      }
+    }
+  }
+}

package/src/components/card/header.js

@@ -0,0 +1,92 @@
+// src/components/card/header.js
+import { PREFIX } from '../../core/config'
+import { pipe } from '../../core/compose'
+import { createBase, withElement } from '../../core/compose/component'
+import { withText } from '../../core/compose/features'
+import { createElement } from '../../core/dom/create'
+
+/**
+ * Creates a card header component
+ * @param {Object} config - Header configuration
+ * @param {string} [config.title] - Title text
+ * @param {string} [config.subtitle] - Subtitle text
+ * @param {HTMLElement|string} [config.avatar] - Avatar element or HTML string
+ * @param {HTMLElement|string} [config.action] - Action element or HTML string
+ * @returns {HTMLElement} Card header element
+ */
+export const createCardHeader = (config = {}) => {
+  const baseConfig = {
+    ...config,
+    componentName: 'card-header',
+    prefix: PREFIX
+  }
+
+  try {
+    const header = pipe(
+      createBase,
+      withElement({
+        tag: 'div',
+        componentName: 'card-header',
+        className: config.class
+      })
+    )(baseConfig)
+
+    // Create text container
+    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
+      })
+    }
+
+    // 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
+
+      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)
+    throw new Error(`Failed to create card header: ${error.message}`)
+  }
+}

package/src/components/card/index.js

@@ -0,0 +1,7 @@
+// src/components/card/index.js
+export { default } from './card.js'
+export { createCardContent } from './content.js'
+export { createCardHeader } from './header.js'
+export { createCardActions } from './actions.js'
+export { createCardMedia } from './media.js'
+export { CARD_VARIANTS, CARD_ELEVATIONS } from './constants.js'

package/src/components/card/media.js

@@ -0,0 +1,56 @@
+// src/components/card/media.js
+import { PREFIX } from '../../core/config'
+import { pipe } from '../../core/compose'
+import { createBase, withElement } from '../../core/compose/component'
+
+/**
+ * Creates a card media component
+ * @param {Object} config - Media configuration
+ * @param {string} [config.src] - Image source URL
+ * @param {string} [config.alt] - Image alt text
+ * @param {HTMLElement} [config.element] - Custom media element
+ * @param {string} [config.aspectRatio='16:9'] - Media aspect ratio
+ * @param {boolean} [config.contain=false] - Whether to use object-fit: contain
+ * @returns {HTMLElement} Card media element
+ */
+export const createCardMedia = (config = {}) => {
+  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
+      if (config.alt) img.alt = config.alt
+      img.className = `${PREFIX}-card-media-img`
+      media.element.appendChild(img)
+    }
+
+    return media.element
+  } catch (error) {
+    console.error('Card media creation error:', error)
+    throw new Error(`Failed to create card media: ${error.message}`)
+  }
+}

package/src/components/card/styles.scss

@@ -0,0 +1,287 @@
+// src/components/card/styles.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: v.card('width');
+  width: 340px;
+  --card-elevation: m.elevation(2);
+  
+  // 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(m.elevation(2));
+    
+    &:hover {
+      --card-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;
+  }
+}

package/src/index.js

@@ -2,6 +2,7 @@
 export { createElement } from './core/dom/create'
 export { default as createLayout } from './core/layout'
 export { default as createButton } from './components/button'
+export { default as createCard } from './components/card'
 export { default as createCheckbox } from './components/checkbox'
 export { default as createContainer } from './components/container'
 export { default as createMenu } from './components/menu'