{"id":49487182,"url":"https://github.com/floor/mtrl","last_synced_at":"2026-05-01T02:11:25.851Z","repository":{"id":278884403,"uuid":"937078487","full_name":"floor/mtrl","owner":"floor","description":"A functional JavaScript component library with composable architecture based on Material Design 3","archived":false,"fork":false,"pushed_at":"2026-03-30T11:04:38.000Z","size":3088,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-30T13:09:55.940Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/floor.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.txt","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-22T09:28:33.000Z","updated_at":"2026-03-30T11:04:39.000Z","dependencies_parsed_at":"2025-02-22T10:23:35.382Z","dependency_job_id":"e65510ee-9fee-40ee-be07-a428c560d2b2","html_url":"https://github.com/floor/mtrl","commit_stats":null,"previous_names":["floor/mtrl"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/floor/mtrl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floor%2Fmtrl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floor%2Fmtrl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floor%2Fmtrl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floor%2Fmtrl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/floor","download_url":"https://codeload.github.com/floor/mtrl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floor%2Fmtrl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32482620,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-01T02:11:24.857Z","updated_at":"2026-05-01T02:11:25.841Z","avatar_url":"https://github.com/floor.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mtrl Library\n\n\u003e **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!\n\nmtrl 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.\n\n## Understanding mtrl\n\nmtrl (pronounced \"material\") takes its inspiration from Material Design while providing a flexible, framework-agnostic implementation.\n\n### Design Philosophy\n\nmtrl is built on several core principles:\n\n1. **Composition Over Inheritance**: Components are constructed through functional composition with full type safety.\n2. **Zero Dependencies**: The entire library is built with vanilla TypeScript, ensuring minimal bundle size and maximum compatibility.\n3. **Material Design Inspiration**: While inspired by Material Design, mtrl provides flexibility in styling and behavior.\n4. **Accessibility First**: Built-in accessibility features ensure your applications are usable by everyone.\n5. **TypeScript First**: Comprehensive type definitions for better developer experience and code reliability.\n\n## Core Components\n\nmtrl provides a comprehensive set of components, each following Material Design principles:\n\n```typescript\nimport { createButton, createTextField } from \"mtrl\";\n\n// Create a material button with ripple effect\nconst button = createButton({\n  text: \"Submit\",\n  variant: \"filled\",\n  ripple: true,\n  class: \"custom-button\",\n});\n\n// className will be: mtrl-button mtrl-button--filled custom-button\n```\n\n### Component List\n\nEach component follows the `mtrl-` prefix convention:\n\n- `mtrl-button` - Material buttons with ripple effects\n- `mtrl-textfield` - Text input components\n- `mtrl-switch` - Toggle switches\n- `mtrl-navigation` - Navigation components\n- `mtrl-list` - List components with selection\n- `mtrl-snackbar` - Toast notifications\n- `mtrl-container` - Layout containers\n\n## Installation\n\n```bash\n# Using npm\nnpm install mtrl\n\n# Using yarn\nyarn add mtrl\n\n# Using bun\nbun add mtrl\n```\n\n## Tree-Shaking Optimized Imports\n\nmtrl is optimized for tree-shaking. Constants are exported separately from component creators to minimize bundle size.\n\n### Import Patterns\n\n| Import Type | Path |\n|-------------|------|\n| Component creators | `import { createButton } from 'mtrl'` |\n| Button constants | `import { BUTTON_VARIANTS } from 'mtrl/components/button/constants'` |\n| Slider constants | `import { SLIDER_SIZES } from 'mtrl/components/slider/constants'` |\n| Card constants | `import { CARD_VARIANTS } from 'mtrl/components/card/constants'` |\n| Direct component import | `import createButton from 'mtrl/components/button'` |\n| Core utilities | `import { addClass, removeClass } from 'mtrl/core/dom'` |\n\n### Example\n\n```typescript\n// ✅ Optimal - only imports what you need\nimport { createButton } from 'mtrl';\nimport { BUTTON_VARIANTS, BUTTON_SIZES } from 'mtrl/components/button/constants';\n\nconst button = createButton({\n  text: 'Submit',\n  variant: BUTTON_VARIANTS.FILLED,\n  size: BUTTON_SIZES.LARGE\n});\n\n// ✅ Also optimal - direct component import\nimport createSlider from 'mtrl/components/slider';\nimport { SLIDER_COLORS } from 'mtrl/components/slider/constants';\n\nconst slider = createSlider({\n  color: SLIDER_COLORS.PRIMARY\n});\n```\n\n**Note:** Constants are NOT exported from main entry points. Always import them from the component's constants file.\n\n## Component Architecture\n\nLet's look at how mtrl components are constructed:\n\n```typescript\n// Example of a button component creation\nconst button = createButton({\n  prefix: \"mtrl\", // The library's prefix\n  componentName: \"button\", // Component identifier\n  variant: \"filled\", // Visual variant\n  text: \"Click me\", // Button text\n  ripple: true, // Enable ripple effect\n});\n```\n\n### The Composition System\n\nmtrl uses a pipe-based composition system with full type safety for building components:\n\n```typescript\n// Internal component creation\nconst createButton = (config: ButtonConfig): ButtonComponent =\u003e {\n  return pipe(\n    createBase, // Base component structure\n    withEvents(), // Event handling capability\n    withElement({\n      // DOM element creation\n      tag: \"button\",\n      componentName: \"button\",\n      prefix: \"mtrl\",\n    }),\n    withVariant(config), // Visual variant support\n    withText(config), // Text content management\n    withIcon(config), // Icon support\n    withRipple(config) // Ripple animation\n  )(config);\n};\n```\n\n### TypeScript Integration\n\nmtrl provides comprehensive TypeScript definitions:\n\n```typescript\n// Component interfaces for better developer experience\nexport interface ButtonComponent\n  extends BaseComponent,\n    ElementComponent,\n    TextComponent,\n    IconComponent,\n    DisabledComponent,\n    LifecycleComponent {\n  // Button-specific properties and methods\n  getValue: () =\u003e string;\n  setValue: (value: string) =\u003e ButtonComponent;\n  enable: () =\u003e ButtonComponent;\n  disable: () =\u003e ButtonComponent;\n  setText: (content: string) =\u003e ButtonComponent;\n  getText: () =\u003e string;\n  setIcon: (icon: string) =\u003e ButtonComponent;\n  getIcon: () =\u003e string;\n  destroy: () =\u003e void;\n  updateCircularStyle: () =\u003e void;\n}\n```\n\n### CSS Classes\n\nmtrl follows a consistent class naming convention:\n\n```css\n.mtrl-component                /* Base component class */\n/* Base component class */\n.mtrl-component--variant      /* Variant modifier */\n.mtrl-component--state        /* State modifier (disabled, focused) */\n.mtrl-component-element; /* Child element */\n```\n\n## State Management\n\nmtrl provides several approaches to state management:\n\n### Local Component State\n\n```typescript\nconst textField = createTextField({\n  label: \"Username\",\n});\n\ntextField.on(\"input\", ({ value }) =\u003e {\n  console.log(\"Current value:\", value);\n});\n\ntextField.setValue(\"New value\");\n```\n\n### Collection Management\n\nFor managing lists and datasets:\n\n```typescript\nconst collection = new Collection\u003cUser\u003e({\n  transform: (item) =\u003e ({\n    ...item,\n    displayName: `${item.firstName} ${item.lastName}`,\n  }),\n});\n\ncollection.subscribe(({ event, data }) =\u003e {\n  console.log(`Collection ${event}:`, data);\n});\n```\n\n## Data Integration\n\nmtrl provides adapters for different data sources:\n\n```typescript\n// MongoDB adapter\nconst mongoAdapter = createMongoAdapter({\n  uri: \"mongodb://localhost:27017\",\n  dbName: \"mtrl-app\",\n  collection: \"users\",\n});\n\n// Route adapter for REST APIs\nconst routeAdapter = createRouteAdapter({\n  base: \"/api\",\n  endpoints: {\n    list: \"/users\",\n    create: \"/users\",\n  },\n});\n```\n\n## Customization\n\n### Creating Custom Components\n\nExtend mtrl by creating custom components with full type safety:\n\n```typescript\ninterface CustomCardConfig {\n  title?: string;\n  class?: string;\n}\n\ninterface CustomCardComponent extends ElementComponent {\n  setContent: (content: string) =\u003e CustomCardComponent;\n}\n\nconst createCustomCard = (config: CustomCardConfig): CustomCardComponent =\u003e {\n  return pipe(\n    createBase,\n    withEvents(),\n    withElement({\n      tag: \"div\",\n      componentName: \"card\",\n      prefix: \"mtrl\",\n    }),\n    // Add custom features\n    (component) =\u003e ({\n      ...component,\n      setContent(content: string) {\n        component.element.innerHTML = content;\n        return this;\n      },\n    })\n  )(config);\n};\n```\n\n### Styling\n\nmtrl components can be styled through CSS custom properties:\n\n```css\n:root {\n  --mtrl-primary: #6200ee;\n  --mtrl-surface: #ffffff;\n  --mtrl-on-surface: #000000;\n  --mtrl-elevation-1: 0 2px 4px rgba(0, 0, 0, 0.2);\n}\n```\n\n## Best Practices\n\n### Performance\n\nmtrl is designed with performance in mind:\n\n- Minimal DOM operations\n- Efficient event handling\n- Automatic cleanup of resources\n- Lazy initialization of features\n\n### Type Safety\n\nmtrl leverages TypeScript for better developer experience:\n\n- Clear component interfaces\n- Type-safe method chaining\n- Intelligent code completion\n- Compile-time error checking\n- Self-documenting code\n\n### Accessibility\n\nBuilt-in accessibility features include:\n\n- ARIA attributes management\n- Keyboard navigation\n- Focus management\n- Screen reader support\n\n## Browser Support\n\nmtrl supports modern browsers:\n\n- Chrome (latest)\n- Firefox (latest)\n- Safari (latest)\n- Edge (latest)\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details and our [Migration Guide](MIGRATION-GUIDE.md) for TypeScript information.\n\n## License\n\nmtrl is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Testing\n\nmtrl comes with a comprehensive test suite using Bun's test runner. The tests are written in TypeScript and use JSDOM for DOM testing.\n\n```bash\n# Run all tests\nbun test\n\n# Run tests in watch mode\nbun test --watch\n\n# Run tests with coverage report\nbun test --coverage\n\n# Run tests with UI\nbun test --watch --ui\n\n# Run a specific test file\nbun test test/components/button.test.ts\n```\n\nFor more details on writing and running tests, see our [Testing Guide](TESTING.md).\n\n## Documentation\n\nFor detailed API documentation, examples, and guides, visit our [documentation site](https://mtrl.app).\n\n---\n\nThis 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloor%2Fmtrl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffloor%2Fmtrl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloor%2Fmtrl/lists"}