mtrl 0.2.2 → 0.2.4

package/.typedocignore

@@ -0,0 +1,11 @@
+# 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/DOCS.md

@@ -0,0 +1,153 @@
+# 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/index.ts

@@ -2,32 +2,47 @@
 import {
   createLayout,
   createElement,
+  createBadge,
   createButton,
   createCard,
+  createCarousel,
   createCheckbox,
   createChip,
+  createDialog,
   createList,
   createMenu,
   createNavigation,
   createProgress,
-  createTextfield,
+  createRadios,
+  createSheet,
+  createSlider,
   createSnackbar,
+  createTabs,
+  createTextfield,
+  createTooltip,
   createSwitch
-
 } from './src/index.js'
 
 export {
   createLayout,
   createElement,
+  createBadge,
   createButton,
   createCard,
+  createCarousel,
   createCheckbox,
   createChip,
+  createDialog,
   createList,
   createMenu,
   createNavigation,
   createProgress,
-  createTextfield,
+  createRadios,
+  createSheet,
+  createSlider,
   createSnackbar,
+  createTabs,
+  createTextfield,
+  createTooltip,
   createSwitch
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrl",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "A functional JavaScript component library with composable architecture based on Material Design 3",
   "keywords": [
     "component",
@@ -15,7 +15,12 @@
     "test": "bun test",
     "test:watch": "bun test --watch",
     "test:coverage": "bun test --coverage",
-    "test:ui": "bun test --watch --ui"
+    "test:ui": "bun test --watch --ui",
+    "docs": "typedoc --skipErrorChecking",
+    "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"
   },
   "repository": {
     "type": "git",

package/src/components/badge/_styles.scss

@@ -0,0 +1,174 @@
+// src/components/badge/_styles.scss
+@use '../../styles/abstract/base' as base;
+@use '../../styles/abstract/variables' as v;
+@use '../../styles/abstract/functions' as f;
+@use '../../styles/abstract/mixins' as m;
+@use '../../styles/abstract/theme' as t;
+
+$component: '#{base.$prefix}-badge';
+
+.#{$component} {
+  // Base styles
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  min-width: 20px;
+  height: 20px;
+  padding: 0 6px;
+  border-radius: 10px;
+  background-color: t.color('error');
+  color: t.color('on-error');
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 1;
+  letter-spacing: 0.5px;
+  white-space: nowrap;
+  text-align: center;
+  
+  // Badge parent wrapper
+  &-wrapper {
+    position: relative;
+    display: inline-flex;
+  }
+  
+  // Default positioning (top-right)
+  &--positioned {
+    position: absolute;
+    top: -8px;
+    right: -8px;
+    transform: translate(50%, -50%);
+  }
+  
+  // Dot variant 
+  &--dot {
+    min-width: 8px;
+    height: 8px;
+    padding: 0;
+    border-radius: 50%;
+  }
+  
+  // Small size
+  &--small {
+    min-width: 16px;
+    height: 16px;
+    font-size: 10px;
+    padding: 0 4px;
+  }
+  
+  // Large size
+  &--large {
+    min-width: 24px;
+    height: 24px;
+    font-size: 12px;
+    padding: 0 8px;
+  }
+  
+  // Position variants
+  &--top-left {
+    top: 0;
+    left: 0;
+    transform: translate(-50%, -50%);
+  }
+  
+  &--top-right {
+    top: 0;
+    right: 0;
+    transform: translate(50%, -50%);
+  }
+  
+  &--bottom-left {
+    bottom: 0;
+    left: 0;
+    transform: translate(-50%, 50%);
+  }
+  
+  &--bottom-right {
+    bottom: 0;
+    right: 0;
+    transform: translate(50%, 50%);
+  }
+  
+  // Color variants
+  &--primary {
+    background-color: t.color('primary');
+    color: t.color('on-primary');
+  }
+  
+  &--secondary {
+    background-color: t.color('secondary');
+    color: t.color('on-secondary');
+  }
+  
+  &--tertiary {
+    background-color: t.color('tertiary');
+    color: t.color('on-tertiary');
+  }
+  
+  &--error {
+    background-color: t.color('error');
+    color: t.color('on-error');
+  }
+  
+  &--success {
+    background-color: t.color('success', t.color('primary'));
+    color: t.color('on-success', t.color('on-primary'));
+  }
+  
+  &--warning {
+    background-color: t.color('warning', t.color('tertiary'));
+    color: t.color('on-warning', t.color('on-tertiary'));
+  }
+  
+  &--info {
+    background-color: t.color('info', t.color('secondary'));
+    color: t.color('on-info', t.color('on-secondary'));
+  }
+  
+  // Outline variant
+  &--outlined {
+    background-color: transparent;
+    border: 1px solid currentColor;
+    
+    &.#{$component}--primary {
+      color: t.color('primary');
+    }
+    
+    &.#{$component}--secondary {
+      color: t.color('secondary');
+    }
+    
+    &.#{$component}--tertiary {
+      color: t.color('tertiary');
+    }
+    
+    &.#{$component}--error {
+      color: t.color('error');
+    }
+    
+    &.#{$component}--success {
+      color: t.color('success', t.color('primary'));
+    }
+    
+    &.#{$component}--warning {
+      color: t.color('warning', t.color('tertiary'));
+    }
+    
+    &.#{$component}--info {
+      color: t.color('info', t.color('secondary'));
+    }
+  }
+  
+  // Max value handling
+  &--max {
+    &::after {
+      content: '+';
+    }
+  }
+  
+  // Invisible
+  &--invisible {
+    display: none;
+  }
+}

package/src/components/badge/api.ts

@@ -0,0 +1,292 @@
+// src/components/badge/api.ts
+import { BadgeComponent } from './types';
+import { BADGE_VARIANTS, BADGE_SIZES, BADGE_COLORS, BADGE_POSITIONS } from './constants';
+
+interface ApiOptions {
+  visibility: {
+    show: () => void;
+    hide: () => void;
+    toggle: (visible?: boolean) => void;
+    isVisible: () => boolean;
+  };
+  lifecycle: {
+    destroy: () => void;
+  };
+}
+
+interface ComponentWithElements {
+  element: HTMLElement;
+  wrapper?: HTMLElement;
+  config: {
+    max?: number;
+    content?: string | number;
+  };
+  getClass: (name: string) => string;
+  addClass: (...classes: string[]) => any;
+  removeClass: (...classes: string[]) => any;
+  on: (event: string, handler: Function) => any;
+  off: (event: string, handler: Function) => any;
+}
+
+/**
+ * Enhances a badge 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 Badge component
+ */
+export const withAPI = ({ visibility, lifecycle }: ApiOptions) => 
+  (component: ComponentWithElements): BadgeComponent => ({
+    ...component as any,
+    
+    /**
+     * Sets the badge content
+     * @param {string|number} content - Content to display in the badge
+     * @returns {BadgeComponent} Badge component instance for chaining
+     */
+    setContent(content: string | number) {
+      const stringContent = String(content);
+      component.config.content = content;
+      
+      // If max is defined and content is a number greater than max, show max+
+      if (component.config.max !== undefined && 
+          typeof content === 'number' && 
+          content > component.config.max) {
+        component.element.textContent = String(component.config.max);
+        component.element.classList.add(`${component.getClass('badge')}--max`);
+      } else {
+        component.element.textContent = stringContent;
+        component.element.classList.remove(`${component.getClass('badge')}--max`);
+      }
+      
+      // Toggle the dot variant based on whether content is empty
+      if (stringContent === '' || stringContent === '0') {
+        this.hide();
+      } else {
+        this.show();
+      }
+      
+      return this;
+    },
+    
+    /**
+     * Gets the badge content
+     * @returns {string} Current badge content
+     */
+    getContent() {
+      return component.element.textContent || '';
+    },
+    
+    /**
+     * Shows the badge
+     * @returns {BadgeComponent} Badge component instance for chaining
+     */
+    show() {
+      visibility.show();
+      return this;
+    },
+    
+    /**
+     * Hides the badge
+     * @returns {BadgeComponent} Badge component instance for chaining
+     */
+    hide() {
+      visibility.hide();
+      return this;
+    },
+    
+    /**
+     * Toggles badge visibility
+     * @param {boolean} [visible] - Optional flag to force visibility state
+     * @returns {BadgeComponent} Badge component instance for chaining
+     */
+    toggle(visible?: boolean) {
+      visibility.toggle(visible);
+      return this;
+    },
+    
+    /**
+     * Checks if the badge is visible
+     * @returns {boolean} True if badge is visible
+     */
+    isVisible() {
+      return visibility.isVisible();
+    },
+    
+    /**
+     * Sets maximum value (after which badge shows max+)
+     * @param {number} max - Maximum value to display
+     * @returns {BadgeComponent} Badge component instance for chaining
+     */
+    setMax(max: number) {
+      component.config.max = max;
+      
+      // Apply max formatting if current content exceeds max
+      if (typeof component.config.content === 'number' && 
+          component.config.content > max) {
+        component.element.textContent = String(max);
+        component.element.classList.add(`${component.getClass('badge')}--max`);
+      } else {
+        component.element.classList.remove(`${component.getClass('badge')}--max`);
+      }
+      
+      return this;
+    },
+    
+    /**
+     * Sets badge color
+     * @param {string} color - Color variant to apply
+     * @returns {BadgeComponent} Badge component instance for chaining
+     */
+    setColor(color: keyof typeof BADGE_COLORS | BADGE_COLORS) {
+      // Remove existing color classes
+      Object.values(BADGE_COLORS).forEach(colorName => {
+        component.element.classList.remove(`${component.getClass('badge')}--${colorName}`);
+      });
+      
+      // Add new color class
+      component.element.classList.add(`${component.getClass('badge')}--${color}`);
+      return this;
+    },
+    
+    /**
+     * Sets badge variant
+     * @param {string} variant - Variant to apply
+     * @returns {BadgeComponent} Badge component instance for chaining
+     */
+    setVariant(variant: keyof typeof BADGE_VARIANTS | BADGE_VARIANTS) {
+      // Remove existing variant classes
+      Object.values(BADGE_VARIANTS).forEach(variantName => {
+        component.element.classList.remove(`${component.getClass('badge')}--${variantName}`);
+      });
+      
+      // Add new variant class if not standard
+      if (variant !== BADGE_VARIANTS.STANDARD) {
+        component.element.classList.add(`${component.getClass('badge')}--${variant}`);
+      }
+      
+      // Clear content if dot variant
+      if (variant === BADGE_VARIANTS.DOT) {
+        component.element.textContent = '';
+      } else if (component.config.content !== undefined) {
+        this.setContent(component.config.content);
+      }
+      
+      return this;
+    },
+    
+    /**
+     * Sets badge size
+     * @param {string} size - Size variant to apply
+     * @returns {BadgeComponent} Badge component instance for chaining
+     */
+    setSize(size: keyof typeof BADGE_SIZES | BADGE_SIZES) {
+      // Remove existing size classes
+      Object.values(BADGE_SIZES).forEach(sizeName => {
+        component.element.classList.remove(`${component.getClass('badge')}--${sizeName}`);
+      });
+      
+      // Add new size class if not medium (default)
+      if (size !== BADGE_SIZES.MEDIUM) {
+        component.element.classList.add(`${component.getClass('badge')}--${size}`);
+      }
+      
+      return this;
+    },
+    
+    /**
+     * Sets badge position
+     * @param {string} position - Position variant to apply
+     * @returns {BadgeComponent} Badge component instance for chaining
+     */
+    setPosition(position: keyof typeof BADGE_POSITIONS | BADGE_POSITIONS) {
+      // Remove existing position classes
+      Object.values(BADGE_POSITIONS).forEach(posName => {
+        component.element.classList.remove(`${component.getClass('badge')}--${posName}`);
+      });
+      
+      // Add new position class
+      component.element.classList.add(`${component.getClass('badge')}--${position}`);
+      
+      return this;
+    },
+    
+    /**
+     * Attaches badge to a target element
+     * @param {HTMLElement} target - Element to attach badge to
+     * @returns {BadgeComponent} Badge component instance for chaining
+     */
+    attachTo(target: HTMLElement) {
+      // If we already have a wrapper, remove the badge from it
+      if (component.wrapper && component.wrapper.contains(component.element)) {
+        component.wrapper.removeChild(component.element);
+      }
+      
+      // Create a new wrapper to hold the target and badge
+      const wrapper = document.createElement('div');
+      wrapper.classList.add(component.getClass('badge-wrapper'));
+      
+      // Replace the target with the wrapper
+      const parent = target.parentNode;
+      if (parent) {
+        parent.replaceChild(wrapper, target);
+        wrapper.appendChild(target);
+        wrapper.appendChild(component.element);
+        
+        // Make sure the badge is positioned
+        component.element.classList.add(`${component.getClass('badge')}--positioned`);
+        
+        // Save the wrapper reference
+        component.wrapper = wrapper;
+      }
+      
+      return this;
+    },
+    
+    /**
+     * Makes badge standalone (removes from wrapper)
+     * @returns {BadgeComponent} Badge component instance for chaining
+     */
+    detach() {
+      if (component.wrapper && component.wrapper.contains(component.element)) {
+        // Remove the badge from the wrapper
+        component.wrapper.removeChild(component.element);
+        
+        // Remove the positioned class
+        component.element.classList.remove(`${component.getClass('badge')}--positioned`);
+        
+        // Add the badge to the document body or another container
+        document.body.appendChild(component.element);
+        
+        // Clear the wrapper reference
+        component.wrapper = undefined;
+      }
+      
+      return this;
+    },
+    
+    /**
+     * Destroys the badge component and cleans up resources
+     */
+    destroy() {
+      lifecycle.destroy();
+      
+      // If badge is in a wrapper, restore the original DOM structure
+      if (component.wrapper) {
+        const target = component.wrapper.firstChild as HTMLElement;
+        const parent = component.wrapper.parentNode;
+        
+        if (parent && target) {
+          parent.replaceChild(target, component.wrapper);
+        }
+      }
+    },
+    
+    // Forward basic component methods for API consistency
+    getClass: component.getClass,
+    addClass: component.addClass,
+    removeClass: component.removeClass,
+    on: component.on,
+    off: component.off,
+    element: component.element,
+    wrapper: component.wrapper
+  });