M3E (Material 3 Expressive)

@m3e/web is a modern implementation of Material Design 3 built entirely with Web Components. It provides a spec-aligned component suite that is framework-agnostic, meaning you can use it in any web environment without being tied to a specific framework like React or Vue.

Key characteristics include:

• Web Component Based: Uses standard Web Components for interoperability.
• Material 3 Aligned: Implements design tokens, dynamic color, shape, and motion systems.
• Framework Agnostic: No framework dependencies.
• Security Focused: Supports Trusted Types and strong Content Security Policies (CSP) with XSS-safe templating.
• Accessibility: Built-in support for accessibility standards.

The @m3e/web/list package provides a suite of accessible, Material 3-inspired components for organizing and displaying items. Key components include:

• m3e-list: A general container for organizing multiple list items.
• m3e-list-item: A single item supporting rich content and flexible layouts.
• m3e-list-action: An interactive item designed to perform user-initiated actions.
• m3e-list-option: A selectable option within a list.
• m3e-action-list: A specialized container for action-based interactions with built-in keyboard navigation.
• m3e-selection-list: A container for selectable options, supporting multi-select functionality.
• m3e-expandable-list-item: A hierarchical item that can be expanded to reveal nested content.

The @m3e/web/core module provides several key capabilities for Material 3 development:

• Design Tokens: Centralized design values for color, typography, shape, and elevation.
• Primitives: Reusable elements for depicting elevation, state layers, ripples, etc.
• Controllers: Behavioral logic for focus, hover, long press, mutation, pressed, and resize.
• Mixins: Tools to create new components using behavioral mixins.
• Accessibility: ARIA roles, keyboard navigation, and state management.
• Utilities: Platform detection, keycode mapping, and layout helpers.

The m3e-button is a semantic UI primitive designed according to Material Design 3 guidelines. It supports five visual variants via the variant attribute: filled, tonal, elevated, outlined, and text (default). The component handles interaction states (hover, focus, press, disabled) with smooth motion transitions and is accessible by default with ARIA roles and strong focus indicators.

<m3e-button variant="tonal">Tonal Button</m3e-button>

The module provides several specialized chip components and containers:

Individual Chips

• m3e-chip: A non-interactive chip for conveying small pieces of information.
• m3e-assist-chip: An interactive chip for performing smart or automated actions.
• m3e-input-chip: Represents a discrete piece of information entered by a user.
• m3e-filter-chip: An interactive chip used to select or deselect options.
• m3e-suggestion-chip: Used to present dynamically generated suggestions (e.g., search filters or suggested replies).

Chip Sets (Containers)

• m3e-chip-set: A container to organize chips into a cohesive unit.
• m3e-input-chip-set: A container that transforms user input into interactive chips, supporting entry, editing, and removal.
• m3e-filter-chip-set: A container for organizing filter chips to refine content or trigger behavior.

The @m3e/web/timepicker package provides several specialized elements for time selection:

• m3e-timepicker: The main container that presents a time picker on a temporary surface (adapts between docked and modal layouts).
• m3e-timepicker-input: A keyboard-based interface for selecting hours and minutes.
• m3e-timepicker-dial: A clock-face interface for selecting hours and minutes using a movable hand.
• m3e-timepicker-toggle: A component designed to be nested within a clickable element to trigger the timepicker.

The @m3e/web/option package provides a complete suite for selectable menus and lists following Material Design 3 principles:

• m3e-option: The individual selectable item. It manages its own selection state and provides visual feedback.
• m3e-option-panel: The container/surface that holds the options. It is designed to be anchored to a trigger element and supports scrolling.
• m3e-optgroup: A structural component used to group related m3e-option elements under a specific label.

Usage Example

<m3e-option-panel>
  <m3e-option value="apple">Apple</m3e-option>
  <m3e-option value="banana">Banana</m3e-option>
  <m3e-optgroup>
    <span slot="label">Citrus</span>
    <m3e-option value="lemon">Lemon</m3e-option>
    <m3e-option value="orange">Orange</m3e-option>
  </m3e-optgroup>
</m3e-option-panel>

The tree component is built using two primary elements:

• m3e-tree: The root container that manages the hierarchical structure and selection state.
• m3e-tree-item: Individual nodes within the tree that can be expanded, collapsed, or selected.

To create a tree, nest m3e-tree-item elements inside m3e-tree. Use the label slot on m3e-tree-item to define the text displayed for each node.

<m3e-tree>
  <m3e-tree-item open>
    <span slot="label">Parent Item</span>
    <m3e-tree-item>
      <span slot="label">Child Item</span>
    </m3e-tree-item>
  </m3e-tree-item>
</m3e-tree>

The @m3e/web/expansion-panel module provides two main components for managing collapsible content:

1. m3e-expansion-panel: A single collapsible section. It uses a details-summary pattern and supports custom headers, content, actions, and toggle icons via slots. It can be configured for toggle position, direction, and open/closed states.
2. m3e-accordion: A container that coordinates multiple m3e-expansion-panel elements. By default, it allows only one panel to be open at a time, but this can be changed using the multi attribute.

Basic Usage Example

<m3e-accordion>
  <m3e-expansion-panel>
    <span slot="header">Panel 1</span>
    I am content for the first expansion panel
  </m3e-expansion-panel>
  <m3e-expansion-panel>
    <span slot="header">Panel 2</span>
    I am content for the second expansion panel
  </m3e-expansion-panel>
</m3e-accordion>