mtrl 0.3.8 → 0.4.0

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 floor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/README.md

@@ -0,0 +1,324 @@
+# mtrl Library
+
+> **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!
+
+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.
+
+## Understanding mtrl
+
+mtrl (pronounced "material") takes its inspiration from Material Design while providing a flexible, framework-agnostic implementation. The library's name is reflected in its component prefix `mtrl-`, which you'll see used consistently throughout the codebase.
+
+### 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
+```
+
+### Component List
+
+Each component follows the `mtrl-` prefix convention:
+
+- `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
+
+## Installation
+
+```bash
+# Using npm
+npm install mtrl
+
+# Using yarn
+yarn add mtrl
+
+# Using bun
+bun add mtrl
+```
+
+## Component Architecture
+
+Let's look at how mtrl components are constructed:
+
+```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
+})
+```
+
+### The Composition System
+
+mtrl uses a pipe-based composition system with full type safety for building components:
+
+```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)
+}
+```
+
+### TypeScript Integration
+
+mtrl provides comprehensive TypeScript definitions:
+
+```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;
+}
+```
+
+### CSS Classes
+
+mtrl follows a consistent class naming convention:
+
+```css
+.mtrl-component                /* Base component class */
+.mtrl-component--variant      /* Variant modifier */
+.mtrl-component--state        /* State modifier (disabled, focused) */
+.mtrl-component-element       /* Child element */
+```
+
+## State Management
+
+mtrl provides several approaches to state management:
+
+### Local Component State
+
+```typescript
+const textField = createTextField({
+  label: 'Username'
+})
+
+textField.on('input', ({ value }) => {
+  console.log('Current value:', value)
+})
+
+textField.setValue('New value')
+```
+
+### Collection Management
+
+For managing lists and datasets:
+
+```typescript
+const collection = new Collection<User>({
+  transform: (item) => ({
+    ...item,
+    displayName: `${item.firstName} ${item.lastName}`
+  })
+})
+
+collection.subscribe(({ event, data }) => {
+  console.log(`Collection ${event}:`, data)
+})
+```
+
+## Data Integration
+
+mtrl provides adapters for different data sources:
+
+```typescript
+// MongoDB adapter
+const mongoAdapter = createMongoAdapter({
+  uri: 'mongodb://localhost:27017',
+  dbName: 'mtrl-app',
+  collection: 'users'
+})
+
+// Route adapter for REST APIs
+const routeAdapter = createRouteAdapter({
+  base: '/api',
+  endpoints: {
+    list: '/users',
+    create: '/users'
+  }
+})
+```
+
+## Customization
+
+### Creating Custom Components
+
+Extend mtrl by creating custom components with full type safety:
+
+```typescript
+interface CustomCardConfig {
+  title?: string;
+  class?: string;
+}
+
+interface CustomCardComponent extends ElementComponent {
+  setContent: (content: string) => CustomCardComponent;
+}
+
+const createCustomCard = (config: CustomCardConfig): CustomCardComponent => {
+  return pipe(
+    createBase,
+    withEvents(),
+    withElement({
+      tag: 'div',
+      componentName: 'card',
+      prefix: 'mtrl'
+    }),
+    // Add custom features
+    (component) => ({
+      ...component,
+      setContent(content: string) {
+        component.element.innerHTML = content;
+        return this;
+      }
+    })
+  )(config);
+}
+```
+
+### Styling
+
+mtrl components can be styled through CSS custom properties:
+
+```css
+:root {
+  --mtrl-primary: #6200ee;
+  --mtrl-surface: #ffffff;
+  --mtrl-on-surface: #000000;
+  --mtrl-elevation-1: 0 2px 4px rgba(0,0,0,0.2);
+}
+```
+
+## Best Practices
+
+### Performance
+
+mtrl is designed with performance in mind:
+
+- 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)
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details and our [Migration Guide](MIGRATION-GUIDE.md) for TypeScript information.
+
+## 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.

package/dist/components/badge/api.d.ts

@@ -0,0 +1,48 @@
+import { BadgeComponent } from './types';
+/**
+ * API configuration options for badge component
+ * @category Components
+ * @internal
+ */
+interface ApiOptions {
+    visibility: {
+        show: () => void;
+        hide: () => void;
+        toggle: (visible?: boolean) => void;
+        isVisible: () => boolean;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+}
+/**
+ * Component with required elements and methods for API enhancement
+ * @category Components
+ * @internal
+ */
+interface ComponentWithElements {
+    element: HTMLElement;
+    wrapper?: HTMLElement;
+    config: {
+        max?: number;
+        label?: string | number;
+        variant?: string;
+    };
+    getClass: (name: string) => string;
+    addClass: (...classes: string[]) => any;
+    removeClass: (...classes: string[]) => any;
+    on: (event: string, handler: Function) => any;
+    off: (event: string, handler: Function) => any;
+}
+/**
+ * Enhances a badge component with API methods.
+ * This follows the higher-order function pattern to add public API methods
+ * to the component, making them available to the end user.
+ *
+ * @param {ApiOptions} options - API configuration options
+ * @returns {Function} Higher-order function that adds API methods to component
+ * @category Components
+ * @internal This is an internal utility for the Badge component
+ */
+export declare const withAPI: ({ visibility, lifecycle }: ApiOptions) => (component: ComponentWithElements) => BadgeComponent;
+export {};

package/{src/components/badge/badge.ts → dist/components/badge/badge.d.ts}

@@ -1,45 +1,27 @@
-// src/components/badge/badge.ts
-import { pipe } from '../../core/compose';
-import { createBase, withElement } from '../../core/compose/component';
-import {
-  withEvents,
-  withLifecycle
-} from '../../core/compose/features';
-import { 
-  withVisibility,
-  withVariant,
-  withColor, 
-  withPosition,
-  withMax,
-  withAttachment
-} from './features';
-import { withAPI } from './api';
 import { BadgeConfig, BadgeComponent } from './types';
-import { createBaseConfig, getElementConfig, getApiConfig } from './config';
-
 /**
  * Creates a new Badge component following Material Design 3 guidelines.
- * 
- * The Badge component displays a small circle or numerical indicator to 
- * draw attention to items requiring user attention, like notifications 
+ *
+ * The Badge component displays a small circle or numerical indicator to
+ * draw attention to items requiring user attention, like notifications
  * or counts. Badges can be attached to any element.
- * 
+ *
  * @param {BadgeConfig} config - Badge configuration object
  * @returns {BadgeComponent} Badge component instance with methods for
  *  managing the badge appearance, content, and visibility
- * 
+ *
  * @throws {Error} Throws an error if badge creation fails
- * 
+ *
  * @category Components
- * 
+ *
  * @example
  * // Create a small dot badge (notification indicator)
- * const notificationBadge = createBadge({ 
+ * const notificationBadge = createBadge({
  *   variant: 'small',
  *   color: 'error',
  *   target: document.querySelector('.icon-button')
  * });
- * 
+ *
  * @example
  * // Create a large badge with a count (numbered indicator)
  * const countBadge = createBadge({
@@ -48,7 +30,7 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
  *   color: 'primary',
  *   target: document.querySelector('.notification-icon')
  * });
- * 
+ *
  * @example
  * // Create a badge with a maximum value
  * const messagesBadge = createBadge({
@@ -58,7 +40,7 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
  *   color: 'info',
  *   position: 'bottom-right'
  * });
- * 
+ *
  * @example
  * // Control badge visibility programmatically
  * const toggleBadge = createBadge({
@@ -66,7 +48,7 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
  *   color: 'success',
  *   target: document.querySelector('.toggle-button')
  * });
- * 
+ *
  * // Toggle badge visibility
  * function toggleNotification() {
  *   if (toggleBadge.isVisible()) {
@@ -76,30 +58,5 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
  *   }
  * }
  */
-const createBadge = (config: BadgeConfig = {}): BadgeComponent => {
-  const baseConfig = createBaseConfig(config);
-
-  try {
-    // Compose the badge component from multiple feature enhancers
-    const badge = pipe(
-      createBase,
-      withEvents(),
-      withElement(getElementConfig(baseConfig)),
-      withVariant(baseConfig),
-      withColor(baseConfig),
-      withPosition(baseConfig),
-      withMax(baseConfig),
-      withVisibility(),
-      withAttachment(baseConfig),
-      withLifecycle(),
-      comp => withAPI(getApiConfig(comp))(comp)
-    )(baseConfig);
-
-    return badge;
-  } catch (error) {
-    console.error('Badge creation error:', error);
-    throw new Error(`Failed to create badge: ${(error as Error).message}`);
-  }
-};
-
-export default createBadge;
+declare const createBadge: (config?: BadgeConfig) => BadgeComponent;
+export default createBadge;

package/dist/components/badge/config.d.ts

@@ -0,0 +1,79 @@
+import { BadgeConfig } from './types';
+/**
+ * Default configuration for the Badge component
+ * These values will be used when not explicitly specified by the user.
+ *
+ * @category Components
+ */
+export declare const defaultConfig: BadgeConfig;
+/**
+ * Creates the base configuration for Badge component by merging user-provided
+ * config with default values.
+ *
+ * @param {BadgeConfig} config - User provided configuration
+ * @returns {BadgeConfig} Complete configuration with defaults applied
+ * @category Components
+ * @internal
+ */
+export declare const createBaseConfig: (config?: BadgeConfig) => BadgeConfig;
+/**
+ * Generates element configuration for the Badge component.
+ * This function creates the necessary attributes and configuration
+ * for the DOM element creation process.
+ *
+ * @param {BadgeConfig} config - Badge configuration
+ * @returns {Object} Element configuration object for withElement
+ * @category Components
+ * @internal
+ */
+export declare const getElementConfig: (config: BadgeConfig) => {
+    tag: string;
+    componentName: string;
+    attributes: Record<string, any>;
+    className: string[];
+    rawClass: string | string[];
+    html: string;
+    text: string;
+    forwardEvents: Record<string, boolean | ((component: any, event: Event) => boolean)>;
+    interactive: boolean;
+};
+/**
+ * Creates API configuration for the Badge component.
+ * This connects the core component features (like visibility)
+ * to the public API methods exposed to users.
+ *
+ * @param {Object} comp - Component with visibility and lifecycle features
+ * @returns {Object} API configuration object
+ * @category Components
+ * @internal
+ */
+export declare const getApiConfig: (comp: any) => {
+    visibility: {
+        show: () => any;
+        hide: () => any;
+        toggle: (visible?: boolean) => any;
+        isVisible: () => any;
+    };
+    lifecycle: {
+        destroy: () => any;
+    };
+};
+/**
+ * Format a badge label following Material Design 3 guidelines:
+ * - Max 4 characters including "+" for overflow
+ * - Add "+" for numeric values exceeding max
+ *
+ * @param {string|number} label - Original label
+ * @param {number} max - Maximum value before using "+"
+ * @returns {string} Formatted label that fits within badge constraints
+ * @category Components
+ * @internal
+ *
+ * @example
+ * formatBadgeLabel(5) // "5"
+ * formatBadgeLabel(1250, 999) // "999+"
+ * formatBadgeLabel("New") // "New"
+ * formatBadgeLabel("VeryLong") // "Very" (truncated)
+ */
+export declare const formatBadgeLabel: (label: string | number, max?: number) => string;
+export default defaultConfig;

package/dist/components/badge/constants.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Badge variants
+ * - SMALL: Simple dot badge (6dp diameter)
+ * - LARGE: Numbered badge (16dp height)
+ */
+export declare const BADGE_VARIANTS: {
+    readonly SMALL: "small";
+    readonly LARGE: "large";
+};
+/**
+ * Badge colors
+ * ERROR is the default
+ */
+export declare const BADGE_COLORS: {
+    readonly ERROR: "error";
+    readonly PRIMARY: "primary";
+    readonly SECONDARY: "secondary";
+    readonly TERTIARY: "tertiary";
+    readonly SUCCESS: "success";
+    readonly WARNING: "warning";
+    readonly INFO: "info";
+};
+/**
+ * Badge positions relative to its container
+ */
+export declare const BADGE_POSITIONS: {
+    readonly TOP_RIGHT: "top-right";
+    readonly TOP_LEFT: "top-left";
+    readonly BOTTOM_RIGHT: "bottom-right";
+    readonly BOTTOM_LEFT: "bottom-left";
+};
+/**
+ * Maximum character count for badge labels
+ */
+export declare const BADGE_MAX_CHARACTERS = 4;

package/dist/components/badge/features.d.ts

@@ -0,0 +1,36 @@
+import { BadgeConfig } from './types';
+/**
+ * Higher-order function that adds visibility control features to a component
+ * @returns {Function} Component enhancer with visibility features
+ */
+export declare const withVisibility: () => (component: any) => any;
+/**
+ * Higher-order function that adds variant features to a badge component
+ * @param {BadgeConfig} config - Badge configuration
+ * @returns {Function} Component enhancer with variant features
+ */
+export declare const withVariant: (config: BadgeConfig) => (component: any) => any;
+/**
+ * Higher-order function that adds color features to a badge component
+ * @param {BadgeConfig} config - Badge configuration
+ * @returns {Function} Component enhancer with color features
+ */
+export declare const withColor: (config: BadgeConfig) => (component: any) => any;
+/**
+ * Higher-order function that adds positioning features to a badge component
+ * @param {BadgeConfig} config - Badge configuration
+ * @returns {Function} Component enhancer with positioning features
+ */
+export declare const withPosition: (config: BadgeConfig) => (component: any) => any;
+/**
+ * Higher-order function that adds max value features to a badge component
+ * @param {BadgeConfig} config - Badge configuration
+ * @returns {Function} Component enhancer with max value features
+ */
+export declare const withMax: (config: BadgeConfig) => (component: any) => any;
+/**
+ * Higher-order function that attaches badge to a target element
+ * @param {BadgeConfig} config - Badge configuration
+ * @returns {Function} Component enhancer with attachment features
+ */
+export declare const withAttachment: (config: BadgeConfig) => (component: any) => any;

package/dist/components/badge/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Badge component module
+ * @module components/badge
+ * @description A small element that communicates status, shows a count,
+ * or highlights an element requiring attention.
+ */
+export { default } from './badge';
+export type { BadgeConfig, BadgeComponent, BadgeVariant, BadgeColor, BadgePosition } from './types';