mtrl 0.3.2 → 0.3.3

package/CONTRIBUTING.md

@@ -1,18 +1,18 @@
 # 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:
 
 - 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
 
@@ -76,16 +76,29 @@ mtrl uses a separate repository called mtrl.app (https://mtrl.app) for showcasin
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrl",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "A functional TypeScript/JavaScript component library with composable architecture based on Material Design 3",
   "author": "floor",
   "license": "MIT License",

package/src/components/navigation/nav-item.ts

@@ -107,11 +107,22 @@ export const createNavItem = (
     itemElement.appendChild(icon);
   }
 
-  // Add label if provided
+  // Add label if provided - CONVERTED TO ANCHOR FOR SEO
   if (config.label) {
-    const label = document.createElement('span');
+    // Create anchor instead of span for the label
+    const label = document.createElement('a');
     label.className = `${prefix}-${NavClass.LABEL}`;
     label.textContent = config.label;
+    label.href = `/${config.id}`; // Create path based on ID
+    
+    // Ensure the anchor looks the same as a span would
+    label.style.textDecoration = 'none';
+    label.style.color = 'inherit';
+    label.style.pointerEvents = 'none'; // Let the button handle click events
+    
+    // Add SEO attributes
+    label.setAttribute('title', config.label);
+    
     itemElement.appendChild(label);
     itemElement.setAttribute('aria-label', config.label);
   }

package/src/core/dom/create.ts

@@ -6,6 +6,17 @@
 
 import { setAttributes } from './attributes';
 import { normalizeClasses } from '../utils';
+import { PREFIX } from '../config';
+
+/**
+ * Event handler function type
+ */
+export type EventHandler = (event: Event) => void;
+
+/**
+ * Event condition type - either a boolean or a function that returns a boolean
+ */
+export type EventCondition = boolean | ((context: any, event: Event) => boolean);
 
 /**
  * Options for element creation
@@ -59,7 +70,7 @@ export interface CreateElementOptions {
   /**
    * Events to forward when component has emit method
    */
-  forwardEvents?: Record<string, boolean | ((context: any, event: Event) => boolean)>;
+  forwardEvents?: Record<string, EventCondition>;
   
   /**
    * Callback after element creation
@@ -81,9 +92,12 @@ export interface CreateElementOptions {
  * Event handler storage to facilitate cleanup
  */
 export interface EventHandlerStorage {
-  [eventName: string]: EventListener;
+  [eventName: string]: EventHandler;
 }
 
+// Constant for prefix with dash
+const PREFIX_WITH_DASH = `${PREFIX}-`;
+
 /**
  * Creates a DOM element with the specified options
  *
@@ -108,89 +122,78 @@ export const createElement = (options: CreateElementOptions = {}): HTMLElement =
 
   const element = document.createElement(tag);
 
-  // Handle content
+  // Apply basic properties
   if (html) element.innerHTML = html;
   if (text) element.textContent = text;
   if (id) element.id = id;
 
   // Handle classes
   if (className) {
-    const normalizedClasses = normalizeClasses(className);
-    if (normalizedClasses.length) {
-      element.classList.add(...normalizedClasses);
+    const classes = normalizeClasses(className);
+    if (classes.length) {
+      // Apply prefix to classes in a single operation
+      element.classList.add(...classes.map(cls => 
+        cls && !cls.startsWith(PREFIX_WITH_DASH) ? PREFIX_WITH_DASH + cls : cls
+      ).filter(Boolean));
     }
   }
 
-  // Handle data attributes
-  Object.entries(data).forEach(([key, value]) => {
-    element.dataset[key] = value;
-  });
+  // Handle data attributes directly
+  for (const key in data) {
+    element.dataset[key] = data[key];
+  }
 
-  // Handle all other attributes
+  // Handle regular attributes
   const allAttrs = { ...attrs, ...rest };
-  Object.entries(allAttrs).forEach(([key, value]) => {
+  for (const key in allAttrs) {
+    const value = allAttrs[key];
     if (value != null) element.setAttribute(key, String(value));
-  });
-
-  // Initialize event handler storage if not present
-  if (!element.__eventHandlers) {
-    element.__eventHandlers = {};
   }
 
-  // Handle event forwarding if context has emit method or is a component with on method
+  // Handle event forwarding
   if (forwardEvents && (context?.emit || context?.on)) {
-    Object.entries(forwardEvents).forEach(([nativeEvent, eventConfig]) => {
-      // Create a wrapper handler function to evaluate condition and forward event
+    element.__eventHandlers = {};
+    
+    for (const nativeEvent in forwardEvents) {
+      const eventConfig = forwardEvents[nativeEvent];
+      
       const handler = (event: Event) => {
-        // Determine if the event should be forwarded
         let shouldForward = true;
         
         if (typeof eventConfig === 'function') {
           try {
-            // If it's a function, call with component context and event
-            shouldForward = eventConfig({ ...context, element }, event);
+            // Create a lightweight context clone
+            const ctxWithElement = { ...context, element };
+            shouldForward = eventConfig(ctxWithElement, event);
           } catch (error) {
             console.warn(`Error in event condition for ${nativeEvent}:`, error);
             shouldForward = false;
           }
         } else {
-          // If it's a boolean, use directly
           shouldForward = Boolean(eventConfig);
         }
         
-        // Forward the event if condition passes
         if (shouldForward) {
           if (context.emit) {
             context.emit(nativeEvent, { event, element, originalEvent: event });
           } else if (context.on) {
-            // This is a component with on method but no emit method
-            // Dispatch a custom event that can be listened to
-            const customEvent = new CustomEvent(nativeEvent, {
+            element.dispatchEvent(new CustomEvent(nativeEvent, {
               detail: { event, element, originalEvent: event },
               bubbles: true,
               cancelable: true
-            });
-            element.dispatchEvent(customEvent);
+            }));
           }
         }
       };
       
-      // Store the handler for future removal
       element.__eventHandlers[nativeEvent] = handler;
-      
-      // Add the actual event listener
       element.addEventListener(nativeEvent, handler);
-    });
+    }
   }
 
   // Append to container if provided
-  if (container) {
-    container.appendChild(element);
-  }
-
-  if (typeof onCreate === 'function') {
-    onCreate(element, context);
-  }
+  if (container) container.appendChild(element);
+  if (onCreate) onCreate(element, context);
 
   return element;
 };
@@ -200,10 +203,11 @@ export const createElement = (options: CreateElementOptions = {}): HTMLElement =
  * @param element - Element to cleanup
  */
 export const removeEventHandlers = (element: HTMLElement): void => {
-  if (element.__eventHandlers) {
-    Object.entries(element.__eventHandlers).forEach(([eventName, handler]) => {
-      element.removeEventListener(eventName, handler);
-    });
+  const handlers = element.__eventHandlers;
+  if (handlers) {
+    for (const event in handlers) {
+      element.removeEventListener(event, handlers[event]);
+    }
     delete element.__eventHandlers;
   }
 };
@@ -228,7 +232,9 @@ export const withClasses = (...classes: (string | string[])[]) =>
   (element: HTMLElement): HTMLElement => {
     const normalizedClasses = normalizeClasses(...classes);
     if (normalizedClasses.length) {
-      element.classList.add(...normalizedClasses);
+      element.classList.add(...normalizedClasses.map(cls => 
+        cls && !cls.startsWith(PREFIX_WITH_DASH) ? PREFIX_WITH_DASH + cls : cls
+      ).filter(Boolean));
     }
     return element;
   };
@@ -240,17 +246,17 @@ export const withClasses = (...classes: (string | string[])[]) =>
  */
 export const withContent = (content: Node | string) => 
   (element: HTMLElement): HTMLElement => {
-    if (content instanceof Node) {
-      element.appendChild(content);
-    } else {
-      element.textContent = content;
-    }
+    if (content instanceof Node) element.appendChild(content);
+    else element.textContent = content;
     return element;
   };
 
 // Extend HTMLElement interface to add eventHandlers property
 declare global {
   interface HTMLElement {
+    /**
+     * Storage for event handlers to enable cleanup
+     */
     __eventHandlers?: EventHandlerStorage;
   }
 }

package/src/styles/themes/_autumn.scss

@@ -58,6 +58,9 @@
   --#{$prefix}-sys-color-on-info: #003060;
   --#{$prefix}-sys-color-on-info-rgb: 0, 48, 96;
 
+    // Include status colors for light theme
+  @include status-colors-light();
+
   &[data-theme-mode="dark"] {
     // Key colors
     --#{$prefix}-sys-color-primary: #DDB995; // Softer brown