mtrl 0.3.8 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrl",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "description": "A functional TypeScript/JavaScript component library with composable architecture based on Material Design 3",
   "author": "floor",
   "license": "MIT License",
@@ -20,7 +20,20 @@
     "type-safe"
   ],
   "type": "module",
-  "main": "index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./styles": "./dist/styles.css"
+  },
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "start": "bun run server.js",
     "dev": "bun --watch server.js",
@@ -30,7 +43,8 @@
     "build:js": "bun build demo/main.js --outfile=demo/dist/bundle.js --format=esm",
     "build:css": "sass src/styles/main.scss:demo/dist/styles.css --style=compressed",
     "build": "bun run build:js && bun run build:css",
-    "build:watch": "bun build --watch demo/main.js --outfile=demo/dist/bundle.js & sass --watch src/styles/main.scss:demo/dist/styles.css",
+    "build:lib": "bun run build.ts",
+    "prepublishOnly": "bun run build:lib",
     "test": "bun test",
     "test:watch": "bun test --watch",
     "test:coverage": "bun test --coverage",
@@ -39,7 +53,12 @@
     "docs:js": "typedoc --options typedoc.simple.json",
     "docs:alt": "bun generate-docs.js",
     "docs:serve": "bun run --bun serve docs",
-    "docs:fix-errors": "tsc --noEmit --allowJs --skipLibCheck"
+    "docs:fix-errors": "tsc --noEmit --allowJs --skipLibCheck",
+    "ts:check": "tsc --noEmit --skipLibCheck",
+    "ts:next-error": "bun scripts/next-ts-error.ts",
+    "ts:fix": "bun scripts/fix-typescript.ts",
+    "ts:fix-file": "bun scripts/fix-typescript.ts",
+    "ts:fix-next": "bun scripts/fix-next-error.ts"
   },
   "repository": {
     "type": "git",

package/.env

@@ -1,15 +0,0 @@
-# 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/.typedocignore

@@ -1,11 +0,0 @@
-# Ignore files with TypeScript errors
-src/components/snackbar/api.ts
-src/components/snackbar/config.ts
-src/components/snackbar/features.ts
-src/components/snackbar/index.ts
-src/components/snackbar/position.ts
-src/components/snackbar/queue.ts
-src/components/snackbar/snackbar.ts
-src/components/chip/chip-set.ts
-src/components/chip/chip.ts
-src/components/menu/features/items-manager.ts

package/CONTRIBUTING.md

@@ -1,218 +0,0 @@
-# Contributing to mtrl
-
-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:
-
-- Zero dependencies (except Bun for development)
-- 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 TypeScript patterns and component design.
-
-## Getting Started
-
-### Development Environment
-
-1. **Fork and clone the repository**:
-   ```bash
-   git clone https://github.com/YOUR-USERNAME/mtrl.git
-   cd mtrl
-   ```
-
-2. **Install dependencies**:
-   ```bash
-   bun install
-   ```
-
-### 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:
-
-1. **Build and link locally**:
-   ```bash
-   # In the mtrl repository
-   bun run build
-   
-   # Clone the mtrl.app repository 
-   git clone https://github.com/YOUR-USERNAME/mtrl.app.git
-   cd mtrl.app
-   
-   # Install dependencies and link to your local mtrl build
-   bun install
-   bun link ../path/to/your/mtrl
-   
-   # Start the showcase server
-   bun run dev
-   ```
-
-2. **Use the official showcase site**:
-   Visit https://mtrl.app to see official examples and documentation.
-
-## Contribution Workflow
-
-1. **Pick an issue or feature** - Start with issues labeled `good-first-issue` or `help-wanted`.
-
-2. **Create a branch** - Name your branch based on what you're working on:
-   ```bash
-   git checkout -b feature/button-improvements
-   # or
-   git checkout -b fix/textfield-validation
-   ```
-
-3. **Make your changes** - Follow the coding standards and guidelines below.
-
-4. **Test your changes** - Use the playground app to test your components in real-time.
-
-5. **Submit a pull request** - Include a detailed description of your changes and reference any related issues.
-
-## Development Guidelines
-
-### Component Structure
-
-mtrl components follow a consistent pattern:
-
-```typescript
-// src/components/mycomponent/index.ts
-export { createMyComponent } from './mycomponent';
-export type { MyComponentOptions } from './types';
-
-// 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';
-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({...});
-  
-  // Setup state and features
-  const lifecycle = createLifecycle(element);
-  
-  // Return component API
-  return {
-    element,
-    // Other public methods...
-    destroy() {
-      lifecycle.destroy();
-    }
-  };
-};
-```
-
-### Using mtrl.app for Development
-
-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/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
-
-- 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
-  - Interfaces should be named in PascalCase (e.g., `ButtonOptions`)
-- Write TypeDoc comments for all public functions and types
-
-### CSS/SCSS Guidelines
-
-- Use BEM-style naming: `mtrl-component__element--modifier`
-- Keep specificity low
-- Use CSS variables for theming
-- Organize styles in the `src/components/*/styles.scss` file
-
-## Pull Request Process
-
-1. Ensure your code follows the style guidelines
-2. Update documentation as needed
-3. Include a clear description of the changes
-4. Reference any issues that are being addressed
-5. Wait for review and address any feedback
-
-## Testing
-
-Please add appropriate tests for your changes:
-
-```typescript
-// Example test structure
-describe('myComponent', () => {
-  it('should render correctly', () => {
-    // Test code
-  });
-  
-  it('should handle user interaction', () => {
-    // Test code
-  });
-});
-```
-
-## Documentation
-
-Documentation is crucial for this project:
-
-- 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
-- Join the discussion on existing issues
-- Be respectful and constructive in communications
-
-## 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.

package/DOCS.md

@@ -1,153 +0,0 @@
-# TypeDoc Installation and Usage Guide for mtrl
-
-This guide will help you set up and use TypeDoc with your mtrl library.
-
-## Installation
-
-To install TypeDoc and its dependencies:
-
-```bash
-# Using Bun
-bun add -D typedoc
-
-# Using npm
-npm install --save-dev typedoc
-
-# Using yarn
-yarn add --dev typedoc
-```
-
-## Configuration
-
-TypeDoc is configured via the `typedoc.json` file at the root of your project. This configuration specifies input files, output directory, theming options, and more.
-
-## Generating Documentation
-
-To generate documentation:
-
-```bash
-# Using the npm script
-bun run docs
-
-# Or directly
-bun typedoc
-```
-
-## Serving Documentation Locally
-
-To view the generated documentation in your browser:
-
-```bash
-# Using the npm script
-bun run docs:serve
-
-# Or directly
-bun run --bun serve docs
-```
-
-Then open your browser to http://localhost:8080
-
-## Documentation Structure
-
-TypeDoc generates a structured representation of your codebase:
-
-- **Modules**: File-based organization of your code
-- **Classes/Interfaces**: Object definitions and their members
-- **Functions**: Standalone functions
-- **Type aliases**: Custom type definitions
-- **Variables**: Exported variables
-
-## JSDoc Tips for Better Documentation
-
-TypeDoc uses JSDoc comments to generate documentation. Here are some tips for writing effective comments:
-
-### Basic Comment Structure
-
-```typescript
-/**
- * Description of the function
- * @param paramName Description of the parameter
- * @returns Description of the return value
- */
-function myFunction(paramName: string): number {
-  // Implementation
-}
-```
-
-### Common JSDoc Tags
-
-- `@param {type} name - Description` - Describes a function parameter
-- `@returns {type} Description` - Describes the return value
-- `@example` - Provides an example of usage
-- `@see` - References related documentation
-- `@deprecated` - Marks an element as deprecated
-- `@since version` - Indicates when the element was added
-- `@category name` - Organizes documentation into categories
-
-### Categories
-
-Use the `@category` tag to organize your mtrl components and utilities:
-
-```typescript
-/**
- * @category Components
- */
-export interface ButtonConfig {
-  // ...
-}
-
-/**
- * @category Core
- */
-export const pipe = (...fns) => (initialValue) => {
-  // ...
-}
-```
-
-## Customizing the Theme
-
-If you want to customize the default theme, you can create a custom theme:
-
-1. Create a `typedoc-theme` directory
-2. Copy the default theme files from the TypeDoc package
-3. Modify the files as needed
-4. Update the `typedoc.json` file to use your custom theme:
-
-```json
-{
-  "theme": "./typedoc-theme"
-}
-```
-
-## Continuous Integration
-
-To automatically generate documentation on each commit or release:
-
-1. Add a script to your CI workflow (GitHub Actions, etc.)
-2. Generate the docs and deploy them to GitHub Pages or another hosting service
-
-Example GitHub Actions workflow:
-
-```yaml
-name: Generate Docs
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: oven-sh/setup-bun@v1
-      - name: Install dependencies
-        run: bun install
-      - name: Generate docs
-        run: bun run docs
-      - name: Deploy to GitHub Pages
-        uses: JamesIves/github-pages-deploy-action@4.1.4
-        with:
-          branch: gh-pages
-          folder: docs
-```

package/TESTING.md

@@ -1,214 +0,0 @@
-# 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.
-
-## Running Tests
-
-```bash
-# Run all tests
-bun test
-
-# Run tests in watch mode (re-runs tests when files change)
-bun test --watch
-
-# Run tests with coverage report
-bun test --coverage
-
-# Run tests with UI
-bun test --watch --ui
-
-# Run specific test file or pattern
-bun test test/components/button.test.ts
-```
-
-## Test Structure
-
-Tests are organized to mirror the source code structure:
-
-```
-test/
-├── setup.ts                # Global test setup and DOM mocking
-├── components/             # Component tests
-│   ├── button.test.ts
-│   ├── textfield.test.ts
-│   └── ...
-└── core/                   # Core functionality tests
-    ├── 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:
-
-### 1. Test Component Creation
-
-Always verify that components are created correctly with default options:
-
-```typescript
-test('should create a component element', () => {
-  const component = createComponent();
-  expect(component.element).toBeDefined();
-  expect(component.element.tagName).toBe('DIV');
-  expect(component.element.className).toContain('mtrl-component');
-});
-```
-
-### 2. Test Configuration Options
-
-Test that configuration options properly affect the component:
-
-```typescript
-test('should apply variant class', () => {
-  const variant = 'filled';
-  const component = createComponent({
-    variant
-  });
-  
-  expect(component.element.className).toContain(`mtrl-component--${variant}`);
-});
-```
-
-### 3. Test Events
-
-Verify that events are properly emitted and handled:
-
-```typescript
-test('should handle click events', () => {
-  const component = createComponent();
-  const handleClick = mock(() => {});
-  
-  component.on('click', handleClick);
-  
-  // Simulate event
-  const event = new Event('click');
-  component.element.dispatchEvent(event);
-  
-  expect(handleClick).toHaveBeenCalled();
-});
-```
-
-### 4. Test State Changes
-
-Test component state changes through its API:
-
-```typescript
-test('should support disabled state', () => {
-  const component = createComponent();
-  
-  // Initially not disabled
-  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...
-  };
-};
-```