mtrl 0.0.0

package/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/README.md

@@ -0,0 +1,251 @@
+# MTRL Library
+
+MTRL is a lightweight, composable JavaScript component library inspired by Material Design principles. Built with vanilla JavaScript and zero dependencies, MTRL provides a robust foundation for creating modern web interfaces with an emphasis on performance 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, making them flexible and maintainable.
+2. **Zero Dependencies**: The entire library is built with vanilla JavaScript, 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.
+
+## Core Components
+
+MTRL provides a comprehensive set of components, each following Material Design principles:
+
+```javascript
+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:
+
+```javascript
+// 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 for building components:
+
+```javascript
+// Internal component creation
+const createButton = (config) => {
+  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)
+}
+```
+
+### 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
+
+```javascript
+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:
+
+```javascript
+const collection = new Collection({
+  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:
+
+```javascript
+// 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:
+
+```javascript
+const createCustomCard = (config) => {
+  return pipe(
+    createBase,
+    withEvents(),
+    withElement({
+      tag: 'div',
+      componentName: 'card',
+      prefix: 'mtrl'
+    }),
+    // Add custom features
+    (component) => ({
+      ...component,
+      setContent(content) {
+        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
+
+### 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.
+
+## License
+
+MTRL is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 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 while maintaining flexibility for custom implementations. For questions, issues, or contributions, please visit our GitHub repository.

package/index.js

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

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "mtrl",
+  "version": "0.0.0",
+  "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",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/floor/mtrl.git"
+  },
+  
+  "author": "floor",
+  "license": "GPL-3.0"
+}

package/src/components/button/api.js

@@ -0,0 +1,54 @@
+// src/components/button/api.js
+
+/**
+ * Enhances a button component with API methods
+ * @param {Object} options - API configuration options
+ * @param {Object} options.disabled - Object containing enable/disable methods
+ * @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 Button component
+ */
+export const withAPI = ({ disabled, lifecycle }) => (component) => ({
+  ...component,
+  element: component.element,
+  getValue: () => component.element.value,
+  setValue (value) {
+    component.element.value = value
+    return this
+  },
+  enable () {
+    disabled.enable()
+    return this
+  },
+  disable () {
+    disabled.disable()
+    return this
+  },
+  setText (content) {
+    component.text.setText(content)
+    this.updateCircularStyle()
+    return this
+  },
+  getText () {
+    return component.text.getText()
+  },
+  setIcon (icon) {
+    component.icon.setIcon(icon)
+    this.updateCircularStyle()
+    return this
+  },
+  getIcon () {
+    return component.icon.getIcon()
+  },
+  destroy () {
+    lifecycle.destroy()
+  },
+  updateCircularStyle () {
+    const hasText = component.text.getElement()
+    if (!hasText && component.icon.getElement()) {
+      component.element.classList.add(`${component.getClass('button')}--circular`)
+    } else {
+      component.element.classList.remove(`${component.getClass('button')}--circular`)
+    }
+  }
+})

package/src/components/button/button.js

@@ -0,0 +1,81 @@
+// src/components/button/button.js
+import { PREFIX } from '../../core/config'
+import { pipe } from '../../core/compose'
+import { createBase, withElement } from '../../core/compose/component'
+import {
+  withEvents,
+  withText,
+  withIcon,
+  withVariant,
+  withSize,
+  withRipple,
+  withDisabled,
+  withLifecycle
+} from '../../core/compose/features'
+import { withAPI } from './api'
+import { BUTTON_VARIANTS } from './constants'
+
+/**
+ * Creates a new Button component
+ * @param {Object} config - Button configuration object
+ * @param {string} [config.variant='filled'] - Button variant (filled, tonal, outlined, elevated, text)
+ * @param {string} [config.size] - Button size (small, medium, large)
+ * @param {boolean} [config.disabled] - Whether the button is initially disabled
+ * @param {string} [config.text] - Initial button text content
+ * @param {string} [config.icon] - Initial button icon HTML content
+ * @param {string} [config.class] - Additional CSS classes
+ * @param {string} [config.value] - Button value attribute
+ */
+const createButton = (config = {}) => {
+  const baseConfig = {
+    ...config,
+    variant: config.variant || BUTTON_VARIANTS.FILLED,
+    componentName: 'button',
+    prefix: PREFIX
+  }
+
+  try {
+    const button = pipe(
+      createBase,
+      withEvents(),
+      withElement({
+        tag: 'button',
+        componentName: 'button',
+        attrs: {
+          type: config.type || 'button',
+          disabled: config.disabled,
+          value: config.value
+        },
+        className: config.class,
+        forwardEvents: {
+          click: (component) => !component.element.disabled,
+          focus: true,
+          blur: true
+        }
+      }),
+      withVariant(baseConfig),
+      withSize(baseConfig),
+      withText(baseConfig),
+      withIcon(baseConfig),
+      withDisabled(baseConfig),
+      withRipple(baseConfig),
+      withLifecycle(),
+      comp => withAPI({
+        disabled: {
+          enable: () => comp.disabled.enable(),
+          disable: () => comp.disabled.disable()
+        },
+        lifecycle: {
+          destroy: () => comp.lifecycle.destroy()
+        }
+      })(comp)
+    )(baseConfig)
+
+    return button
+  } catch (error) {
+    console.error('Button creation error:', error)
+    throw new Error(`Failed to create button: ${error.message}`)
+  }
+}
+
+export default createButton

package/src/components/button/config.js

@@ -0,0 +1,8 @@
+import PREFIX from '../../core/config'
+
+const defaultConfig = {
+  componentName: 'button',
+  prefix: PREFIX
+}
+
+export default defaultConfig

package/src/components/button/constants.js

@@ -0,0 +1,63 @@
+// src/components/button/constants.js
+
+import { RIPPLE_SCHEMA } from '../../core/build/constants'
+
+export const BUTTON_VARIANTS = {
+  FILLED: 'filled',
+  TONAL: 'tonal',
+  OUTLINED: 'outlined',
+  ELEVATED: 'elevated',
+  TEXT: 'text'
+}
+
+export const BUTTON_SIZES = {
+  SMALL: 'small',
+  MEDIUM: 'medium',
+  LARGE: 'large'
+}
+
+/**
+ * Validation schema for button configuration
+ */
+export const BUTTON_SCHEMA = {
+  variant: {
+    type: 'string',
+    enum: Object.values(BUTTON_VARIANTS),
+    required: false
+  },
+  size: {
+    type: 'string',
+    enum: Object.values(BUTTON_SIZES),
+    required: false
+  },
+  disabled: {
+    type: 'boolean',
+    required: false
+  },
+  text: {
+    type: 'string',
+    required: false
+  },
+  icon: {
+    type: 'string',
+    required: false
+  },
+  class: {
+    type: 'string',
+    required: false
+  },
+  value: {
+    type: 'string',
+    required: false
+  },
+  ripple: {
+    type: 'boolean',
+    required: false,
+    default: true
+  },
+  rippleConfig: {
+    type: 'object',
+    required: false,
+    properties: RIPPLE_SCHEMA
+  }
+}

package/src/components/button/index.js

@@ -0,0 +1,2 @@
+// src/components/button/index.js
+export { default } from './button.js'