mtrl 0.3.1 → 0.3.3

package/.env

@@ -0,0 +1,15 @@
+# Application settings
+NODE_ENV=development
+PORT=4000
+# Compression settings
+COMPRESSION_ENABLED=false
+# Cache settings (shorter for development)
+CACHE_STATIC_FILES=0  # No caching in development
+CACHE_CSS_FILES=0
+CACHE_PUBLIC_FILES=0
+# Security settings
+ENABLE_CORS=true
+CORS_ORIGIN=*
+# Application specific settings
+APP_TITLE=MTRL Playground (DEV)
+DEBUG_LEVEL=debug

package/CONTRIBUTING.md

@@ -1,18 +1,18 @@
-# Contributing to MTRL
+# Contributing to mtrl
 
-Thank you for your interest in contributing to MTRL! This document provides guidelines and instructions for contributing to this lightweight, ES6-focused JavaScript UI component library.
+Thank you for your interest in contributing to mtrl! This document provides guidelines and instructions for contributing to this lightweight, TypeScript-focused UI component library.
 
 ## Why Contribute?
 
-MTRL aims to be a modern, flexible UI component library with:
+mtrl aims to be a modern, flexible UI component library with:
 
 - Zero dependencies (except Bun for development)
-- ES6+ focused codebase
+- TypeScript-first codebase
 - Lightweight, tree-shakable components
 - Simple and extensible API
 - Excellent documentation
 
-By contributing to MTRL, you'll help create a lean alternative to heavier frameworks while gaining experience with modern JavaScript patterns and component design.
+By contributing to mtrl, you'll help create a lean alternative to heavier frameworks while gaining experience with modern TypeScript patterns and component design.
 
 ## Getting Started
 
@@ -31,7 +31,7 @@ By contributing to MTRL, you'll help create a lean alternative to heavier framew
 
 ### Testing Your Components with mtrl.app
 
-MTRL uses a separate repository called mtrl.app (https://mtrl.app) for showcasing and testing components. There are two ways to test your components:
+mtrl uses a separate repository called mtrl.app (https://mtrl.app) for showcasing and testing components. There are two ways to test your components:
 
 1. **Build and link locally**:
    ```bash
@@ -74,18 +74,31 @@ MTRL uses a separate repository called mtrl.app (https://mtrl.app) for showcasin
 
 ### Component Structure
 
-MTRL components follow a consistent pattern:
+mtrl components follow a consistent pattern:
 
-```javascript
-// src/components/mycomponent/index.js
+```typescript
+// src/components/mycomponent/index.ts
 export { createMyComponent } from './mycomponent';
+export type { MyComponentOptions } from './types';
 
-// src/components/mycomponent/mycomponent.js
+// src/components/mycomponent/types.ts
+export interface MyComponentOptions {
+  text?: string;
+  onClick?: (event: MouseEvent) => void;
+  // other options...
+}
+
+// src/components/mycomponent/mycomponent.ts
 import { createElement } from '../../core/dom/create';
 import { createLifecycle } from '../../core/state/lifecycle';
-// etc...
-
-export const createMyComponent = (options = {}) => {
+import type { MyComponentOptions } from './types';
+
+/**
+ * Creates a new MyComponent instance
+ * @param options - Configuration options for MyComponent
+ * @returns The MyComponent instance
+ */
+export const createMyComponent = (options: MyComponentOptions = {}) => {
   // Create DOM elements
   const element = createElement({...});
   
@@ -108,21 +121,30 @@ export const createMyComponent = (options = {}) => {
 The mtrl.app showcase application is the best way to develop and test your components:
 
 1. Clone the mtrl.app repository alongside your mtrl clone.
-2. Create a new view file in `src/client/views/components/` for your component.
-3. Add the route in `src/client/core/navigation.js` of the mtrl.app repository.
+2. Create a new view file in `src/client/content/components/` for your component.
+3. Add the route in `src/client/core/navigation.ts` of the mtrl.app repository.
 4. Implement different variants and states for testing.
 5. Run the showcase server with `bun run dev` in the mtrl.app directory.
 
 This separation of the library code (mtrl) and the showcase app (mtrl.app) keeps the core library clean while providing a rich development environment.
 
+### TypeScript Standards
+
+- Use TypeScript's type system to create clear interfaces and types
+- Export types and interfaces separately from implementations
+- Use strict typing and avoid `any` when possible
+- Prefer interfaces for public APIs and type aliases for complex types
+- Add proper return types to all functions
+
 ### Coding Standards
 
-- Use ES6+ features but maintain browser compatibility
-- Follow functional programming principles when possible
+- Add file path as a comment on the first line of each file
+- Use functional programming principles when possible
 - Use consistent naming conventions:
   - Factory functions should be named `createXyz`
   - Utilities should use clear, descriptive names
-- Write JSDoc comments for all public functions
+  - Interfaces should be named in PascalCase (e.g., `ButtonOptions`)
+- Write TypeDoc comments for all public functions and types
 
 ### CSS/SCSS Guidelines
 
@@ -143,7 +165,7 @@ This separation of the library code (mtrl) and the showcase app (mtrl.app) keeps
 
 Please add appropriate tests for your changes:
 
-```javascript
+```typescript
 // Example test structure
 describe('myComponent', () => {
   it('should render correctly', () => {
@@ -158,12 +180,29 @@ describe('myComponent', () => {
 
 ## Documentation
 
-For any new feature or component:
+Documentation is crucial for this project:
 
-- Add JSDoc comments for API methods
+- Add TypeDoc comments for all public API methods and types
+- Comment the file path at the top of each file
 - Update the component's README.md (if applicable)
 - Consider adding example code in the playground
 
+Example of proper TypeDoc:
+
+```typescript
+/**
+ * Creates a button element with specified options
+ * 
+ * @param options - The button configuration options
+ * @returns A button component instance
+ * @example
+ * ```ts
+ * const button = createButton({ text: 'Click me', variant: 'primary' });
+ * document.body.appendChild(button.element);
+ * ```
+ */
+```
+
 ## Community and Communication
 
 - Submit issues for bugs or feature requests
@@ -172,8 +211,8 @@ For any new feature or component:
 
 ## License
 
-By contributing to MTRL, you agree that your contributions will be licensed under the project's MIT License.
+By contributing to mtrl, you agree that your contributions will be licensed under the project's MIT License.
 
 ---
 
-Thank you for contributing to MTRL! Your efforts help make this library better for everyone.
+Thank you for contributing to mtrl! Your efforts help make this library better for everyone.

package/DOCS.md

@@ -1,6 +1,6 @@
-# TypeDoc Installation and Usage Guide for MTRL
+# TypeDoc Installation and Usage Guide for mtrl
 
-This guide will help you set up and use TypeDoc with your MTRL library.
+This guide will help you set up and use TypeDoc with your mtrl library.
 
 ## Installation
 
@@ -86,7 +86,7 @@ function myFunction(paramName: string): number {
 
 ### Categories
 
-Use the `@category` tag to organize your MTRL components and utilities:
+Use the `@category` tag to organize your mtrl components and utilities:
 
 ```typescript
 /**

package/README.md

@@ -1,26 +1,26 @@
-# MTRL Library
+# 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!
+> **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.
+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
+## 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.
+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:
+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.
+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:
+mtrl provides a comprehensive set of components, each following Material Design principles:
 
 ```typescript
 import { createButton, createTextField } from 'mtrl'
@@ -63,7 +63,7 @@ bun add mtrl
 
 ## Component Architecture
 
-Let's look at how MTRL components are constructed:
+Let's look at how mtrl components are constructed:
 
 ```typescript
 // Example of a button component creation
@@ -78,7 +78,7 @@ const button = createButton({
 
 ### The Composition System
 
-MTRL uses a pipe-based composition system with full type safety for building components:
+mtrl uses a pipe-based composition system with full type safety for building components:
 
 ```typescript
 // Internal component creation
@@ -101,7 +101,7 @@ const createButton = (config: ButtonConfig): ButtonComponent => {
 
 ### TypeScript Integration
 
-MTRL provides comprehensive TypeScript definitions:
+mtrl provides comprehensive TypeScript definitions:
 
 ```typescript
 // Component interfaces for better developer experience
@@ -129,7 +129,7 @@ export interface ButtonComponent extends
 
 ### CSS Classes
 
-MTRL follows a consistent class naming convention:
+mtrl follows a consistent class naming convention:
 
 ```css
 .mtrl-component                /* Base component class */
@@ -140,7 +140,7 @@ MTRL follows a consistent class naming convention:
 
 ## State Management
 
-MTRL provides several approaches to state management:
+mtrl provides several approaches to state management:
 
 ### Local Component State
 
@@ -175,7 +175,7 @@ collection.subscribe(({ event, data }) => {
 
 ## Data Integration
 
-MTRL provides adapters for different data sources:
+mtrl provides adapters for different data sources:
 
 ```typescript
 // MongoDB adapter
@@ -199,7 +199,7 @@ const routeAdapter = createRouteAdapter({
 
 ### Creating Custom Components
 
-Extend MTRL by creating custom components with full type safety:
+Extend mtrl by creating custom components with full type safety:
 
 ```typescript
 interface CustomCardConfig {
@@ -234,7 +234,7 @@ const createCustomCard = (config: CustomCardConfig): CustomCardComponent => {
 
 ### Styling
 
-MTRL components can be styled through CSS custom properties:
+mtrl components can be styled through CSS custom properties:
 
 ```css
 :root {
@@ -249,7 +249,7 @@ MTRL components can be styled through CSS custom properties:
 
 ### Performance
 
-MTRL is designed with performance in mind:
+mtrl is designed with performance in mind:
 
 - Minimal DOM operations
 - Efficient event handling
@@ -258,7 +258,7 @@ MTRL is designed with performance in mind:
 
 ### Type Safety
 
-MTRL leverages TypeScript for better developer experience:
+mtrl leverages TypeScript for better developer experience:
 
 - Clear component interfaces
 - Type-safe method chaining
@@ -277,7 +277,7 @@ Built-in accessibility features include:
 
 ## Browser Support
 
-MTRL supports modern browsers:
+mtrl supports modern browsers:
 
 - Chrome (latest)
 - Firefox (latest)
@@ -290,7 +290,30 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 
 ## License
 
-MTRL is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+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
 

package/TESTING.md

@@ -1,6 +1,6 @@
-# Testing MTRL Components
+# Testing mtrl Components
 
-This document provides guidelines for writing and running tests for the MTRL library. We use Bun's built-in test runner for fast, efficient testing.
+This document provides guidelines for writing and running tests for the mtrl library. We use Bun's built-in test runner for fast, efficient testing.
 
 ## Running Tests
 
@@ -18,7 +18,7 @@ bun test --coverage
 bun test --watch --ui
 
 # Run specific test file or pattern
-bun test test/components/button.test.js
+bun test test/components/button.test.ts
 ```
 
 ## Test Structure
@@ -27,29 +27,31 @@ Tests are organized to mirror the source code structure:
 
 ```
 test/
-├── setup.js                # Global test setup and DOM mocking
+├── setup.ts                # Global test setup and DOM mocking
 ├── components/             # Component tests
-│   ├── button.test.js
-│   ├── textfield.test.js
+│   ├── button.test.ts
+│   ├── textfield.test.ts
 │   └── ...
 └── core/                   # Core functionality tests
-    ├── build/
-    │   └── ripple.test.js
-    ├── dom/
-    │   └── ...
-    └── state/
-        └── emitter.test.js
+    ├── dom.classes.test.ts
+    ├── dom.attributes.test.ts
+    ├── dom.events.test.ts
+    ├── utils.normalize.test.ts
+    ├── utils.object.test.ts
+    ├── emitter.test.ts
+    ├── ripple.test.ts
+    └── state.store.test.ts
 ```
 
 ## Writing Tests
 
-When writing tests for MTRL components, follow these guidelines:
+When writing tests for mtrl components, follow these guidelines:
 
 ### 1. Test Component Creation
 
 Always verify that components are created correctly with default options:
 
-```javascript
+```typescript
 test('should create a component element', () => {
   const component = createComponent();
   expect(component.element).toBeDefined();
@@ -62,7 +64,7 @@ test('should create a component element', () => {
 
 Test that configuration options properly affect the component:
 
-```javascript
+```typescript
 test('should apply variant class', () => {
   const variant = 'filled';
   const component = createComponent({
@@ -77,7 +79,7 @@ test('should apply variant class', () => {
 
 Verify that events are properly emitted and handled:
 
-```javascript
+```typescript
 test('should handle click events', () => {
   const component = createComponent();
   const handleClick = mock(() => {});
@@ -96,9 +98,117 @@ test('should handle click events', () => {
 
 Test component state changes through its API:
 
-```javascript
+```typescript
 test('should support disabled state', () => {
   const component = createComponent();
   
   // Initially not disabled
-  expect(component.element.has
+  expect(component.disabled.isDisabled()).toBe(false);
+  
+  // Disable
+  component.disable();
+  expect(component.disabled.isDisabled()).toBe(true);
+  expect(component.element.classList.contains('mtrl-component--disabled')).toBe(true);
+  
+  // Enable
+  component.enable();
+  expect(component.disabled.isDisabled()).toBe(false);
+  expect(component.element.classList.contains('mtrl-component--disabled')).toBe(false);
+});
+```
+
+## JSDOM Setup
+
+We use JSDOM to create a DOM environment for component tests. Each test file that requires DOM manipulation should include the proper JSDOM setup:
+
+```typescript
+// Setup jsdom environment
+let dom: JSDOM;
+let window: Window;
+let document: Document;
+let originalGlobalDocument: any;
+let originalGlobalWindow: any;
+
+beforeAll(() => {
+  // Create a new JSDOM instance
+  dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', {
+    url: 'http://localhost/',
+    pretendToBeVisual: true
+  });
+  
+  // Get window and document from jsdom
+  window = dom.window;
+  document = window.document;
+  
+  // Store original globals
+  originalGlobalDocument = global.document;
+  originalGlobalWindow = global.window;
+  
+  // Set globals to use jsdom
+  global.document = document;
+  global.window = window;
+  global.Element = window.Element;
+  global.HTMLElement = window.HTMLElement;
+  global.Event = window.Event;
+});
+
+afterAll(() => {
+  // Restore original globals
+  global.document = originalGlobalDocument;
+  global.window = originalGlobalWindow;
+  
+  // Clean up jsdom
+  window.close();
+});
+```
+
+## Component Testing Approach
+
+For most component tests, we use a mock implementation approach that creates components with the same interface as the real components, but with simplified internals. This approach:
+
+1. Avoids circular dependency issues in tests
+2. Makes tests faster and more isolated
+3. Allows testing component interfaces without implementation details
+4. Provides better control over the test environment
+
+A typical mock component setup might look like:
+
+```typescript
+const createMockComponent = (config: ComponentConfig = {}): ComponentInterface => {
+  // Create base elements
+  const element = document.createElement('div');
+  element.className = 'mtrl-component';
+  
+  // Apply configuration
+  if (config.variant) {
+    element.classList.add(`mtrl-component--${config.variant}`);
+  }
+  
+  // Event tracking
+  const eventHandlers: Record<string, Function[]> = {};
+  
+  // Return component interface
+  return {
+    element,
+    
+    // Component methods matching the real component API
+    setValue(value: string) {
+      element.setAttribute('value', value);
+      return this;
+    },
+    
+    getValue() {
+      return element.getAttribute('value') || '';
+    },
+    
+    on(event: string, handler: Function) {
+      if (!eventHandlers[event]) eventHandlers[event] = [];
+      eventHandlers[event].push(handler);
+      element.addEventListener(event, handler as EventListener);
+      return this;
+    },
+    
+    // Additional methods as needed...
+  };
+};
+```