mtrl 0.1.3 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # MTRL Library
 
-> **Project Status:** MTRL is in active early development. The core architecture and initial components are being established, with more features on the roadmap. While we're making rapid progress, the API may evolve as we refine the library. We welcome early adopters and contributors who want to help shape MTRL's future!
+> **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 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.
+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
 
@@ -12,16 +12,17 @@ MTRL (pronounced "material") takes its inspiration from Material Design while pr
 
 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.
+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:
 
-```javascript
+```typescript
 import { createButton, createTextField } from 'mtrl'
 
 // Create a material button with ripple effect
@@ -64,7 +65,7 @@ bun add mtrl
 
 Let's look at how MTRL components are constructed:
 
-```javascript
+```typescript
 // Example of a button component creation
 const button = createButton({
   prefix: 'mtrl',           // The library's prefix
@@ -77,11 +78,11 @@ const button = createButton({
 
 ### The Composition System
 
-MTRL uses a pipe-based composition system for building components:
+MTRL uses a pipe-based composition system with full type safety for building components:
 
-```javascript
+```typescript
 // Internal component creation
-const createButton = (config) => {
+const createButton = (config: ButtonConfig): ButtonComponent => {
   return pipe(
     createBase,                // Base component structure
     withEvents(),             // Event handling capability
@@ -98,6 +99,34 @@ const createButton = (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:
@@ -115,7 +144,7 @@ MTRL provides several approaches to state management:
 
 ### Local Component State
 
-```javascript
+```typescript
 const textField = createTextField({
   label: 'Username'
 })
@@ -131,8 +160,8 @@ textField.setValue('New value')
 
 For managing lists and datasets:
 
-```javascript
-const collection = new Collection({
+```typescript
+const collection = new Collection<User>({
   transform: (item) => ({
     ...item,
     displayName: `${item.firstName} ${item.lastName}`
@@ -148,7 +177,7 @@ collection.subscribe(({ event, data }) => {
 
 MTRL provides adapters for different data sources:
 
-```javascript
+```typescript
 // MongoDB adapter
 const mongoAdapter = createMongoAdapter({
   uri: 'mongodb://localhost:27017',
@@ -170,10 +199,19 @@ const routeAdapter = createRouteAdapter({
 
 ### Creating Custom Components
 
-Extend MTRL by creating custom components:
+Extend MTRL by creating custom components with full type safety:
 
-```javascript
-const createCustomCard = (config) => {
+```typescript
+interface CustomCardConfig {
+  title?: string;
+  class?: string;
+}
+
+interface CustomCardComponent extends ElementComponent {
+  setContent: (content: string) => CustomCardComponent;
+}
+
+const createCustomCard = (config: CustomCardConfig): CustomCardComponent => {
   return pipe(
     createBase,
     withEvents(),
@@ -185,12 +223,12 @@ const createCustomCard = (config) => {
     // Add custom features
     (component) => ({
       ...component,
-      setContent(content) {
-        component.element.innerHTML = content
-        return this
+      setContent(content: string) {
+        component.element.innerHTML = content;
+        return this;
       }
     })
-  )(config)
+  )(config);
 }
 ```
 
@@ -218,6 +256,16 @@ MTRL is designed with performance in mind:
 - 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:
@@ -238,7 +286,7 @@ MTRL supports modern browsers:
 
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details and our [Migration Guide](MIGRATION-GUIDE.md) for TypeScript information.
 
 ## License
 
@@ -250,4 +298,4 @@ For detailed API documentation, examples, and guides, visit our [documentation s
 
 ---
 
-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.
+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/index.ts

@@ -0,0 +1,33 @@
+// index.js
+import {
+  createLayout,
+  createElement,
+  createButton,
+  createCard,
+  createCheckbox,
+  createChip,
+  createList,
+  createMenu,
+  createNavigation,
+  createProgress,
+  createTextfield,
+  createSnackbar,
+  createSwitch
+
+} from './src/index.js'
+
+export {
+  createLayout,
+  createElement,
+  createButton,
+  createCard,
+  createCheckbox,
+  createChip,
+  createList,
+  createMenu,
+  createNavigation,
+  createProgress,
+  createTextfield,
+  createSnackbar,
+  createSwitch
+}

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "mtrl",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "A functional JavaScript component library with composable architecture based on Material Design 3",
-  "keywords": ["component", "library", "ui", "user interface", "functional", "composable"],
+  "keywords": [
+    "component",
+    "library",
+    "ui",
+    "user interface",
+    "functional",
+    "composable"
+  ],
   "main": "index.js",
   "scripts": {
     "test": "bun test",
@@ -14,7 +21,9 @@
     "type": "git",
     "url": "https://github.com/floor/mtrl.git"
   },
-  
   "author": "floor",
-  "license": "MIT License"
-}
+  "license": "MIT License",
+  "dependencies": {
+    "typedoc": "^0.27.9"
+  }
+}

package/src/components/button/{styles.scss → _styles.scss}

@@ -1,4 +1,4 @@
-// src/components/button/_button.scss
+// src/components/button/_styles.scss
 @use '../../styles/abstract/base' as base;
 @use '../../styles/abstract/variables' as v;
 @use '../../styles/abstract/functions' as f;
@@ -52,7 +52,7 @@ $component: '#{base.$prefix}-button';
   // Interactive states
   &:disabled {
     pointer-events: none;
-    opacity: 0.85;
+    opacity: 0.38;
   }
   
   // Ensure proper layout with icons

package/src/components/button/api.ts

@@ -0,0 +1,89 @@
+// src/components/button/api.ts
+import { ButtonComponent } from './types';
+
+interface ApiOptions {
+  disabled: {
+    enable: () => void;
+    disable: () => void;
+  };
+  lifecycle: {
+    destroy: () => void;
+  };
+}
+
+interface ComponentWithElements {
+  element: HTMLElement;
+  text: {
+    setText: (content: string) => any;
+    getText: () => string;
+    getElement: () => HTMLElement | null;
+  };
+  icon: {
+    setIcon: (html: string) => any;
+    getIcon: () => string;
+    getElement: () => HTMLElement | null;
+  };
+  getClass: (name: string) => string;
+}
+
+/**
+ * Enhances a button component with API methods
+ * @param {ApiOptions} options - API configuration options
+ * @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 }: ApiOptions) => 
+  (component: ComponentWithElements): ButtonComponent => ({
+    ...component as any,
+    element: component.element as HTMLButtonElement,
+    
+    getValue: () => component.element.value,
+    
+    setValue(value: string) {
+      component.element.value = value;
+      return this;
+    },
+    
+    enable() {
+      disabled.enable();
+      return this;
+    },
+    
+    disable() {
+      disabled.disable();
+      return this;
+    },
+    
+    setText(content: string) {
+      component.text.setText(content);
+      this.updateCircularStyle();
+      return this;
+    },
+    
+    getText() {
+      return component.text.getText();
+    },
+    
+    setIcon(icon: string) {
+      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.ts

@@ -0,0 +1,50 @@
+// src/components/button/button.ts
+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 { ButtonConfig } from './types';
+import { BUTTON_VARIANTS } from './constants';
+import { createBaseConfig, getElementConfig, getApiConfig } from './config';
+
+/**
+ * Creates a new Button component
+ * @param {ButtonConfig} config - Button configuration object
+ * @returns {ButtonComponent} Button component instance
+ */
+const createButton = (config: ButtonConfig = {}) => {
+  const baseConfig = createBaseConfig(config);
+
+  try {
+    const button = pipe(
+      createBase,
+      withEvents(),
+      withElement(getElementConfig(baseConfig)),
+      withVariant(baseConfig),
+      withSize(baseConfig),
+      withText(baseConfig),
+      withIcon(baseConfig),
+      withDisabled(baseConfig),
+      withRipple(baseConfig),
+      withLifecycle(),
+      comp => withAPI(getApiConfig(comp))(comp)
+    )(baseConfig);
+
+    return button;
+  } catch (error) {
+    console.error('Button creation error:', error);
+    throw new Error(`Failed to create button: ${(error as Error).message}`);
+  }
+};
+
+export default createButton;

package/src/components/button/config.ts

@@ -0,0 +1,75 @@
+// src/components/button/config.ts
+import { 
+  createComponentConfig, 
+  createElementConfig,
+  BaseComponentConfig 
+} from '../../core/config/component-config';
+import { ButtonConfig } from './types';
+import { BUTTON_VARIANTS } from './constants';
+
+/**
+ * Default configuration for the Button component
+ */
+export const defaultConfig: ButtonConfig = {
+  variant: BUTTON_VARIANTS.FILLED,
+  type: 'button'
+  // Don't set disabled: false as default - it should be undefined by default
+};
+
+/**
+ * Creates the base configuration for Button component
+ * @param {ButtonConfig} config - User provided configuration
+ * @returns {ButtonConfig} Complete configuration with defaults applied
+ */
+export const createBaseConfig = (config: ButtonConfig = {}): ButtonConfig => 
+  createComponentConfig(defaultConfig, config, 'button') as ButtonConfig;
+
+/**
+ * Generates element configuration for the Button component
+ * @param {ButtonConfig} config - Button configuration
+ * @returns {Object} Element configuration object for withElement
+ */
+export const getElementConfig = (config: ButtonConfig) => {
+  // Create the attributes object
+  const attrs: Record<string, any> = {
+    type: config.type || 'button'
+  };
+  
+  // Only add disabled attribute if it's explicitly true
+  if (config.disabled === true) {
+    attrs.disabled = true;
+  }
+  
+  // Add value attribute only if it exists
+  if (config.value !== undefined) {
+    attrs.value = config.value;
+  }
+  
+  return createElementConfig(config, {
+    tag: 'button',
+    attrs,
+    className: config.class,
+    forwardEvents: {
+      click: (component) => !component.element.disabled,
+      focus: true,
+      blur: true
+    }
+  });
+};
+
+/**
+ * Creates API configuration for the Button component
+ * @param {Object} comp - Component with disabled and lifecycle features
+ * @returns {Object} API configuration object
+ */
+export const getApiConfig = (comp) => ({
+  disabled: {
+    enable: () => comp.disabled.enable(),
+    disable: () => comp.disabled.disable()
+  },
+  lifecycle: {
+    destroy: () => comp.lifecycle.destroy()
+  }
+});
+
+export default defaultConfig;

package/src/components/button/constants.ts

@@ -0,0 +1,17 @@
+// src/components/button/constants.ts
+
+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'
+}

package/src/components/button/index.ts

@@ -0,0 +1,4 @@
+// src/components/button/index.ts
+export { default } from './button'
+export { BUTTON_VARIANTS, BUTTON_SIZES } from './constants'
+export { ButtonConfig, ButtonComponent } from './types'

package/src/components/button/types.ts

@@ -0,0 +1,118 @@
+/**
+ * Configuration interface for the Button component
+ */
+export interface ButtonConfig {
+  /** Button variant (filled, tonal, outlined, elevated, text) */
+  variant?: keyof typeof BUTTON_VARIANTS | BUTTON_VARIANTS;
+  
+  /** Button size (small, medium, large) */
+  size?: keyof typeof BUTTON_SIZES | BUTTON_SIZES;
+  
+  /** Whether the button is initially disabled */
+  disabled?: boolean;
+  
+  /** Initial button text content */
+  text?: string;
+  
+  /** Initial button icon HTML content */
+  icon?: string;
+  
+  /** Icon size */
+  iconSize?: string;
+  
+  /** Additional CSS classes */
+  class?: string;
+  
+  /** Button value attribute */
+  value?: string;
+  
+  /** Button type attribute (default: 'button') */
+  type?: 'button' | 'submit' | 'reset';
+  
+  /** Whether to enable ripple effect */
+  ripple?: boolean;
+  
+  /** Ripple effect configuration */
+  rippleConfig?: {
+    duration?: number;
+    timing?: string;
+    opacity?: [string, string];
+  };
+}
+
+/**
+ * Icon API interface
+ */
+export interface IconAPI {
+  setIcon: (html: string) => IconAPI;
+  getIcon: () => string;
+  getElement: () => HTMLElement | null;
+}
+
+/**
+ * Text API interface
+ */
+export interface TextAPI {
+  setText: (content: string) => TextAPI;
+  getText: () => string;
+  getElement: () => HTMLElement | null;
+}
+
+/**
+ * Button component interface
+ */
+export interface ButtonComponent {
+  element: HTMLButtonElement;
+  text: TextAPI;
+  icon: IconAPI;
+  disabled: {
+    enable: () => void;
+    disable: () => void;
+    isDisabled: () => boolean;
+  };
+  lifecycle: {
+    destroy: () => void;
+  };
+  
+  /** Gets the class with the specified name */
+  getClass: (name: string) => string;
+  
+  /** Gets the button's value */
+  getValue: () => string;
+  
+  /** Sets the button's value */
+  setValue: (value: string) => ButtonComponent;
+  
+  /** Enables the button */
+  enable: () => ButtonComponent;
+  
+  /** Disables the button */
+  disable: () => ButtonComponent;
+  
+  /** Sets the button's text content */
+  setText: (content: string) => ButtonComponent;
+  
+  /** Gets the button's text content */
+  getText: () => string;
+  
+  /** Sets the button's icon */
+  setIcon: (icon: string) => ButtonComponent;
+  
+  /** Gets the button's icon */
+  getIcon: () => string;
+  
+  /** Destroys the button component and cleans up resources */
+  destroy: () => void;
+  
+  /** Updates the button's circular style based on content */
+  updateCircularStyle: () => void;
+  
+  /** Adds event listener */
+  on: (event: string, handler: Function) => ButtonComponent;
+  
+  /** Removes event listener */
+  off: (event: string, handler: Function) => ButtonComponent;
+  
+  /** Add CSS classes */
+  addClass: (...classes: string[]) => ButtonComponent;
+}