mtrl 0.8.0-next.8 → 0.8.0

package/README.md

@@ -1,364 +1,193 @@
-# mtrl Library
+# mtrl
 
-> **Project Status:** mtrl is in active development with TypeScript support! The core architecture and components are established, with more features on the roadmap. We welcome early adopters and contributors who want to help shape mtrl's future!
+Material Design 3 components for the web, written in TypeScript with zero dependencies.
 
-mtrl is a lightweight, composable TypeScript/JavaScript component library inspired by Material Design principles. Built with zero dependencies, mtrl provides a robust foundation for creating modern web interfaces with an emphasis on performance, type safety, and accessibility.
+mtrl implements the M3 expressive update: component sizes, shapes, colours and spring motion follow the Material 3 tokens. Each component is a plain function that returns a DOM element and a small API, so mtrl works with any framework or none. The documentation site, [mtrl.app](https://mtrl.app), shows every component with live examples.
 
-## Understanding mtrl
+## Quick start
 
-mtrl (pronounced "material") takes its inspiration from Material Design while providing a flexible, framework-agnostic implementation.
-
-### Design Philosophy
-
-mtrl is built on several core principles:
-
-1. **Composition Over Inheritance**: Components are constructed through functional composition with full type safety.
-2. **Zero Dependencies**: The entire library is built with vanilla TypeScript, ensuring minimal bundle size and maximum compatibility.
-3. **Material Design Inspiration**: While inspired by Material Design, mtrl provides flexibility in styling and behavior.
-4. **Accessibility First**: Built-in accessibility features ensure your applications are usable by everyone.
-5. **TypeScript First**: Comprehensive type definitions for better developer experience and code reliability.
-
-## Core Components
-
-mtrl provides a comprehensive set of components, each following Material Design principles:
-
-```typescript
-import { createButton, createTextField } from "mtrl";
-
-// Create a material button with ripple effect
-const button = createButton({
-  text: "Submit",
-  variant: "filled",
-  ripple: true,
-  class: "custom-button",
-});
-
-// className will be: mtrl-button mtrl-button--filled custom-button
+```bash
+npm install mtrl
 ```
 
-### Component List
-
-Each component follows the `mtrl-` prefix convention:
+```typescript
+import 'mtrl/styles';
+import { createButton, createTextfield } from 'mtrl';
 
-- `mtrl-button` - Material buttons with ripple effects
-- `mtrl-textfield` - Text input components
-- `mtrl-switch` - Toggle switches
-- `mtrl-navigation` - Navigation components
-- `mtrl-list` - List components with selection
-- `mtrl-snackbar` - Toast notifications
-- `mtrl-container` - Layout containers
+const name = createTextfield({ label: 'Name' });
+const save = createButton({ text: 'Save', variant: 'filled' });
+save.disabled.disable();
 
-## Installation
+name.on('input', ({ value }: { value: string }) => {
+  if (value.trim()) save.disabled.enable();
+  else save.disabled.disable();
+});
 
-```bash
-# Using npm
-npm install mtrl
+save.on('click', () => {
+  console.log('Saved', name.getValue());
+});
 
-# Using yarn
-yarn add mtrl
+document.body.append(name.element, save.element);
 
-# Using bun
-bun add mtrl
+// When the view goes away, release listeners and DOM
+name.destroy();
+save.destroy();
 ```
 
-## Tree-Shaking Optimized Imports
-
-mtrl is optimized for tree-shaking. Constants are exported separately from component creators to minimize bundle size.
+`mtrl/styles` loads every component and theme. For a smaller bundle, import only what you use (see [Styles](#styles)).
 
-### Import Patterns
+## Components
 
-| Import Type | Path |
-|-------------|------|
-| Component creators | `import { createButton } from 'mtrl'` |
-| Button constants | `import { BUTTON_VARIANTS } from 'mtrl/components/button/constants'` |
-| Slider constants | `import { SLIDER_SIZES } from 'mtrl/components/slider/constants'` |
-| Card constants | `import { CARD_VARIANTS } from 'mtrl/components/card/constants'` |
-| Direct component import | `import createButton from 'mtrl/components/button'` |
-| Core utilities | `import { addClass, removeClass } from 'mtrl/core/dom'` |
+Every component is created by a `create*` function exported from `mtrl`, and renders with `mtrl-` prefixed classes.
 
-### Example
+- **Actions:** `createButton`, `createButtonGroup`, `createSplitButton`, `createIconButton`, `createFab`, `createExtendedFab`
+- **Selection and input:** `createCheckbox`, `createChips` and `createChip`, `createRadios`, `createSwitch`, `createSlider`, `createSelect`, `createTextfield`, `createSearch`, `createDatePicker`, `createTimePicker`
+- **Navigation:** `createNavigationRail`, `createDrawer`, `createTabs` and `createTab`, `createTopAppBar`, `createBottomAppBar`, `createMenu`, `createNavigation`, `createNavigationSystem`
+- **Containment:** `createCard` with `createCardHeader`, `createCardContent`, `createCardMedia` and `createCardActions`, `createCarousel`, `createList`, `createDivider`, `createDialog`, `createBottomSheet`, `createSideSheet`
+- **Communication:** `createSnackbar`, `createTooltip`, `createBadge`, `createProgress`, `createLoadingIndicator`
+- **Deprecated:** `createSegmentedButton` and `createSegment`, replaced by `createButtonGroup` with `kind: 'connected'`
 
-```typescript
-// ✅ Optimal - only imports what you need
-import { createButton } from 'mtrl';
-import { BUTTON_VARIANTS, BUTTON_SIZES } from 'mtrl/components/button/constants';
+Virtual scrolling and data-driven lists live in [mtrl-addons](https://github.com/floor/mtrl-addons).
 
-const button = createButton({
-  text: 'Submit',
-  variant: BUTTON_VARIANTS.FILLED,
-  size: BUTTON_SIZES.LARGE
-});
+## Styles
 
-// ✅ Also optimal - direct component import
-import createSlider from 'mtrl/components/slider';
-import { SLIDER_COLORS } from 'mtrl/components/slider/constants';
+Import the full stylesheet once:
 
-const slider = createSlider({
-  color: SLIDER_COLORS.PRIMARY
-});
+```typescript
+import 'mtrl/styles';
 ```
 
-**Note:** Constants are NOT exported from main entry points. Always import them from the component's constants file.
-
-## Component Architecture
-
-Let's look at how mtrl components are constructed:
+Or import the base once, followed by the components you use:
 
 ```typescript
-// Example of a button component creation
-const button = createButton({
-  prefix: "mtrl", // The library's prefix
-  componentName: "button", // Component identifier
-  variant: "filled", // Visual variant
-  text: "Click me", // Button text
-  ripple: true, // Enable ripple effect
-});
+import 'mtrl/styles/base';
+import 'mtrl/styles/button';
+import 'mtrl/styles/textfield';
+
+// Optional: an alternate theme and the utility classes
+import 'mtrl/themes/ocean';
+import 'mtrl/styles/utilities';
 ```
 
-### The Composition System
+The base includes the baseline theme in light and dark, the tokens, a reset, typography and the ripple. Each selective entry imports what it depends on (the select brings the text field and the menu), so use a CSS-capable bundler to resolve and deduplicate them. Choose either the full stylesheet or selective imports, not both. The date picker has no selective entry yet; it is in the full stylesheet.
 
-mtrl uses a pipe-based composition system with full type safety for building components:
+Library styles sit in ordered `mtrl` cascade layers, so unlayered application CSS overrides them without specificity battles.
 
-```typescript
-// Internal component creation
-const createButton = (config: ButtonConfig): ButtonComponent => {
-  return pipe(
-    createBase, // Base component structure
-    withEvents(), // Event handling capability
-    withElement({
-      // DOM element creation
-      tag: "button",
-      componentName: "button",
-      prefix: "mtrl",
-    }),
-    withVariant(config), // Visual variant support
-    withText(config), // Text content management
-    withIcon(config), // Icon support
-    withRipple(config) // Ripple animation
-  )(config);
-};
-```
+### Themes
 
-### TypeScript Integration
+The baseline theme applies by default and follows the system light or dark preference. Choose a theme and mode on the root element:
 
-mtrl provides comprehensive TypeScript definitions:
+```html
+<html data-theme="ocean" data-theme-mode="dark">
+```
 
 ```typescript
-// Component interfaces for better developer experience
-export interface ButtonComponent
-  extends BaseComponent,
-    ElementComponent,
-    TextComponent,
-    IconComponent,
-    DisabledComponent,
-    LifecycleComponent {
-  // Button-specific properties and methods
-  getValue: () => string;
-  setValue: (value: string) => ButtonComponent;
-  enable: () => ButtonComponent;
-  disable: () => ButtonComponent;
-  setText: (content: string) => ButtonComponent;
-  getText: () => string;
-  setIcon: (icon: string) => ButtonComponent;
-  getIcon: () => string;
-  destroy: () => void;
-  updateCircularStyle: () => void;
-}
+document.documentElement.dataset.theme = 'ocean';
+document.documentElement.dataset.themeMode = 'dark';
 ```
 
-### CSS Classes
+Available themes: `baseline`, `ocean`, `desert`, `forest`, `sunset`, `spring`, `summer`, `autumn`, `winter`, `brownbeige`, `browngreen`, `sageivory`, `tealcaramel`, `material`, `legacy` and `highcontrast`. With selective styles, import the theme's entry, for example `mtrl/themes/ocean`.
+
+### Custom properties
 
-mtrl follows a consistent class naming convention:
+Components read the theme's colour roles, so overriding a role restyles every component that uses it:
 
 ```css
-.mtrl-component                /* Base component class */
-/* Base component class */
-.mtrl-component--variant      /* Variant modifier */
-.mtrl-component--state        /* State modifier (disabled, focused) */
-.mtrl-component-element; /* Child element */
+:root {
+  --mtrl-sys-color-primary: #6750a4;
+  --mtrl-sys-color-on-primary: #ffffff;
+}
 ```
 
-## State Management
-
-mtrl provides several approaches to state management:
+The type scale and shape scale are custom properties too (`--mtrl-sys-typescale-*`, `--mtrl-sys-shape-*`). Component hooks follow one convention, `--mtrl-<component>-<name>`:
 
-### Local Component State
-
-```typescript
-const textField = createTextField({
-  label: "Username",
-});
-
-textField.on("input", ({ value }) => {
-  console.log("Current value:", value);
-});
-
-textField.setValue("New value");
+```css
+.brand-slider {
+  --mtrl-slider-color: #006a6a;
+  --mtrl-slider-on-color: #ffffff;
+}
 ```
 
-### Collection Management
-
-For managing lists and datasets:
+## Imports and tree-shaking
 
-```typescript
-const collection = new Collection<User>({
-  transform: (item) => ({
-    ...item,
-    displayName: `${item.firstName} ${item.lastName}`,
-  }),
-});
-
-collection.subscribe(({ event, data }) => {
-  console.log(`Collection ${event}:`, data);
-});
-```
+mtrl publishes ESM with type declarations, so bundlers drop unused exports and split dynamic imports. CommonJS remains available through `require('mtrl')`.
 
-## Data Integration
+| Import | Path |
+|--------|------|
+| Component creators | `import { createButton } from 'mtrl'` |
+| One component directly | `import createSlider from 'mtrl/components/slider'` |
+| Component constants | `import { BUTTON_VARIANTS } from 'mtrl/components/button/constants'` |
+| Core utilities | `import { addClass, removeClass } from 'mtrl/core/dom'` |
 
-mtrl provides adapters for different data sources:
+Constants are not exported from the root; import them from the component's `constants` entry:
 
 ```typescript
-// MongoDB adapter
-const mongoAdapter = createMongoAdapter({
-  uri: "mongodb://localhost:27017",
-  dbName: "mtrl-app",
-  collection: "users",
-});
+import { createButton } from 'mtrl';
+import { BUTTON_VARIANTS, BUTTON_SIZES } from 'mtrl/components/button/constants';
 
-// Route adapter for REST APIs
-const routeAdapter = createRouteAdapter({
-  base: "/api",
-  endpoints: {
-    list: "/users",
-    create: "/users",
-  },
+const button = createButton({
+  text: 'Submit',
+  variant: BUTTON_VARIANTS.FILLED,
+  size: BUTTON_SIZES.L,
 });
 ```
 
-## Customization
+Button progress and card actions load on demand; enable code splitting in your build to keep them out of the initial chunk.
 
-### Creating Custom Components
+## Building your own components
 
-Extend mtrl by creating custom components with full type safety:
+Components are composed from small features with `pipe`. The same building blocks are public:
 
 ```typescript
-interface CustomCardConfig {
-  title?: string;
-  class?: string;
+import { pipe, createBase, withEvents, withElement } from 'mtrl/core/compose';
+import type { ElementComponent } from 'mtrl/core/compose';
+
+interface NoteConfig {
+  text?: string;
 }
 
-interface CustomCardComponent extends ElementComponent {
-  setContent: (content: string) => CustomCardComponent;
+interface NoteComponent extends ElementComponent {
+  setText: (text: string) => NoteComponent;
 }
 
-const createCustomCard = (config: CustomCardConfig): CustomCardComponent => {
-  return pipe(
+const createNote = (config: NoteConfig): NoteComponent =>
+  pipe(
     createBase,
     withEvents(),
-    withElement({
-      tag: "div",
-      componentName: "card",
-      prefix: "mtrl",
-    }),
-    // Add custom features
+    withElement({ tag: 'div', componentName: 'note' }),
     (component) => ({
       ...component,
-      setContent(content: string) {
-        component.element.innerHTML = content;
+      setText(text: string) {
+        component.element.textContent = text;
         return this;
       },
     })
   )(config);
-};
 ```
 
-### Styling
+The element gets the `mtrl-note` class, `withEvents` adds `on`, `off` and `emit`, and `destroy()` removes the element. Add `withLifecycle()` from `mtrl/core/compose/features` when features need to register cleanup.
 
-mtrl components can be styled through CSS custom properties:
+## Upgrading from 0.7
 
-```css
-:root {
-  --mtrl-primary: #6200ee;
-  --mtrl-surface: #ffffff;
-  --mtrl-on-surface: #000000;
-  --mtrl-elevation-1: 0 2px 4px rgba(0, 0, 0, 0.2);
-}
-```
+0.8.0 aligns the components with Material 3 expressive, and some of that changes the API or the styles:
 
-## Best Practices
+- `createSheet` is removed; use `createBottomSheet` or `createSideSheet`.
+- FAB and extended FAB: `variant: 'primary'`, `'secondary'` and `'tertiary'` are now the tone styles; the former look is `'primary-container'` (the default), `'secondary-container'` and `'tertiary-container'`.
+- `createSegmentedButton` is deprecated in favour of `createButtonGroup({ kind: 'connected' })`; its heights are now 40, 36 and 32px by density.
+- Component custom properties are renamed to `--mtrl-<component>-<name>`, for example `--drawer-width` to `--mtrl-drawer-width` and `--item-offset` to `--mtrl-list-item-offset`.
+- `title-large` uses weight 400, as M3 specifies.
+- The slider draws with DOM and CSS; styles for `.mtrl-slider-canvas` no longer apply.
 
-### Performance
+The full list, with every renamed property, is in [changelog.txt](changelog.txt).
 
-mtrl is designed with performance in mind:
+## Browser support
 
-- Minimal DOM operations
-- Efficient event handling
-- Automatic cleanup of resources
-- Lazy initialization of features
-
-### Type Safety
-
-mtrl leverages TypeScript for better developer experience:
-
-- Clear component interfaces
-- Type-safe method chaining
-- Intelligent code completion
-- Compile-time error checking
-- Self-documenting code
-
-### Accessibility
-
-Built-in accessibility features include:
-
-- ARIA attributes management
-- Keyboard navigation
-- Focus management
-- Screen reader support
-
-## Browser Support
-
-mtrl supports modern browsers:
-
-- Chrome (latest)
-- Firefox (latest)
-- Safari (latest)
-- Edge (latest)
+Current Chrome, Edge, Firefox and Safari. The spring motion uses CSS `linear()` easing (Safari 17.2 or later); older browsers render every component but skip those transitions.
 
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details and our [Migration Guide](MIGRATION-GUIDE.md) for TypeScript information.
+Contributions are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) covers the development setup, conventions and the distribution checks; [TESTING.md](TESTING.md) covers the test suite.
 
 ## License
 
-mtrl is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Testing
-
-mtrl comes with a comprehensive test suite using Bun's test runner. The tests are written in TypeScript and use JSDOM for DOM testing.
-
-```bash
-# Run all tests
-bun test
-
-# Run tests in watch mode
-bun test --watch
-
-# Run tests with coverage report
-bun test --coverage
-
-# Run tests with UI
-bun test --watch --ui
-
-# Run a specific test file
-bun test test/components/button.test.ts
-```
-
-For more details on writing and running tests, see our [Testing Guide](TESTING.md).
-
-## Documentation
-
-For detailed API documentation, examples, and guides, visit our [documentation site](https://mtrl.app).
-
----
-
-This library is designed to provide a solid foundation for building modern web interfaces with TypeScript while maintaining flexibility for custom implementations. For questions, issues, or contributions, please visit our GitHub repository.
+MIT, see [LICENSE](LICENSE).