mithril-materialized 2.0.0-beta.1 → 2.0.0-beta.11

package/README.md

@@ -1,15 +1,51 @@
 # mithril-materialized
 
-A [materialize-css](https://materializecss.com) library for the Mithril framework (tested with v2.0 and higher, but presumably, it should work with v1.1.6 too), making it easier to use a Materialize theme in your application. The main focus of this library is on creating Mithril components for the more complicated Materialize components.
+A Mithril.js component library inspired by [materialize-css](https://materializecss.com) design principles, [available on npm](https://www.npmjs.com/package/mithril-materialized). This library provides you with ready-to-use Mithril components that follow Material Design guidelines, with **no external JavaScript dependencies**.
 
-Supported components:
+## 🚀 v2.0.0 Beta - Major Release
+
+This is a **major breaking release** that removes all external JavaScript dependencies, making the library completely self-contained and significantly reducing bundle sizes.
+
+### ✨ What's New
+
+- **🔥 Zero External JS Dependencies**: No longer requires `materialize-css` JavaScript or `material-icons` fonts
+- **📦 Smaller Bundle Size**: Reduced package size by eliminating external dependencies
+- **🎨 Custom SVG Icons**: Built-in MaterialIcon component with custom SVG icons (caret, close)
+- **⚡ Better Performance**: Direct implementations without jQuery or other heavy dependencies
+- **🛠️ Enhanced Components**: Improved DatePicker and TimePicker with custom implementations
+- **📱 Modern Architecture**: Factory components with proper TypeScript support
+- **🎯 CSS-Only Styling**: Uses only CSS for styling - no JavaScript initialization needed
+
+### 💥 Breaking Changes from v1.x
+
+- **Removed dependencies**: No longer requires `materialize-css` or `material-icons` packages
+- **Component updates**: DatePicker and TimePicker now have custom implementations
+- **Icon changes**: Library uses custom SVG icons. Material Icons font is supported too, but not required.
+- **Installation**: Simpler installation process with fewer dependencies
+
+### 📈 Migration from v1.x
+
+**Old installation (v1.x):**
+
+```bash
+npm install materialize-css material-icons mithril mithril-materialized
+```
+
+**New installation (v2.x):**
+
+```bash
+npm install mithril mithril-materialized
+```
+
+Your CSS imports can remain the same, but you no longer need the materialize-css JavaScript.
+
+## Supported Components
 
 - [Buttons](https://erikvullings.github.io/mithril-materialized/#!/buttons)
   - Button
   - FlatButton
   - RoundButton
   - SubmitButton
-  - FloatingActionButton
 - [Inputs](https://erikvullings.github.io/mithril-materialized/#!/inputs)
   - TextInput
   - TextArea
@@ -21,7 +57,7 @@ Supported components:
   - RangeInput
   - Chips
 - [Pickers](https://erikvullings.github.io/mithril-materialized/#!/pickers)
-  - DatePicker
+  - DatePicker (with optional week numbers)
   - TimePicker
 - [Selections](https://erikvullings.github.io/mithril-materialized/#!/selections)
   - Select
@@ -32,396 +68,339 @@ Supported components:
 - [Collections](https://erikvullings.github.io/mithril-materialized/#!/collections)
   - Basic, Link and Avatar Collections
   - Collapsible or accordion
-- [Modals](https://erikvullings.github.io/mithril-materialized/#!/modals)
+- [Theme & Upload](https://erikvullings.github.io/mithril-materialized/#!/theme)
+  - ThemeSwitcher (light/dark/auto theme switching)
+  - ThemeToggle (simple light/dark toggle)
+  - FileUpload (drag-and-drop with validation and preview)
+- [Navigation](https://erikvullings.github.io/mithril-materialized/#!/navigation)
+  - Sidenav (responsive navigation drawer)
+  - Breadcrumb (navigation path indicator)
+  - Wizard/Stepper (multi-step process guidance)
+- [Others](https://erikvullings.github.io/mithril-materialized/#!/modals)
   - ModalPanel
-- [Miscellaneous](https://erikvullings.github.io/mithril-materialized/#!/misc)
-  - Tabs
   - MaterialBox
   - Carousel
   - Pagination
+  - PaginationControls
   - Parallax
+- Data & Tables
+  - DataTable (sorting, filtering, pagination, selection)
 - Additional
   - Label
   - HelperText
-- Not from Materialize-CSS
   - CodeBlock
   - SearchSelect, a searchable select dropdown
-  - [Timeline](https://erikvullings.github.io/mithril-materialized/#!/timeline)
-  - [MapEditor](https://erikvullings.github.io/mithril-materialized/#!/map_editor)
-
-## Version history
-
-v1.2.0: Added Search select, a searchable select dropdown
-
-v1.1.7: Added option to add style to InputCheckbox and Options
-
-v0.17.1: bug fix
-
-- `Select` component also reacts when the `checkedId` property becomes undefined (previously, it would ignore it).
-
-v0.17.0
-
-- Breaking change: `Options` and `RadioButtons` used the `inline` property to put items horizontally. This is actually not needed, and it has been removed. Instead, use the `checkboxClass` to set the grid size of each cell.
-
-v0.16.3
-
-- `NumberInput` adds support for the `step` attribute, so you can use the number up/down to represent floats too.
-
-v0.16.2
-
-- Updated dependencies, fixed library vulnerabilities
-
-v0.16.1
-
-- `Select`, `Options`, and `RadioButtons`: The `checkedId` property can be used to change the selection in `onupdate` dynamically. Otherwise, it is treated the same as `initialValue` (which is only processed in `oninit`). This allows you to dynamically update the selections without recreating the component.
-
-v0.16.0
-
-- `Select` `disabled` status is computed dynamically in the view, not only in `oninit`.
-- `Select`, `Option`, `Radio`, `Kanban`: `onchange` is computed dynamically in the view, not only in `oninit`. As the `onchange` created a closure, new attributes were not always updated as expected.
-
-v0.15.4
-
-- `Pagination` component simplified implementation.
-
-v0.15.3
-
-- FIX: `Pickers` destroy them `onremove`.
-
-v0.15.2
-
-- FIX: `Pagination` did not properly compute the go forward disabled/enabled state.
-
-v0.15.1
-
-- FIX: `Pagination` did not highlight current item when item index exceeded size limit. Also updated example with actual routes.
-
-v0.15.0
-
-- NEW: `FloatingActionButton` created.
-
-v0.14.14
-
-- FIX: `Kanban` triggering too many `onchange` messages.
-
-v0.14.12
-
-- FIX: `Select` when using `multiple` keeps the dropdown open, but re-initialize select when the options change.
-
-v0.14.11
-
-- FIX: `Kanban` did not trigger `onChange` when disabled, but with editable properties.
-
-v0.14.10
-
-- FIX: `Chips` did not initialize properly when `onChange` was not specified (e.g. when disabled).
-
-v0.14.9
-
-- NEW: `PasswordInput` component to enter passwords.
-
-v0.14.8
-
-- FIX: `Tabs` component selection did not work in Edge due to the way the `select` function was implemented in materialize-css.
-
-v0.14.7
-
-- FIX: `Select` when using `multiple` keeps the dropdown open, `dropdownOptions` and `classes` are passed on creation.
-- `Select`, `Options`, `Radios` use `initialValue` instead of `checkedId` (which is deprecated but still working). The rationale is that the checked values are only read initially, when the component is created.
-
-v0.14.5
-
-- FIX: `Options` and `Radios` no longer use `h6` element for labels, so they behave more like other labels.
-
-v0.14.4
-
-- FIX: `Options` and `RadioButtons` did not listen to the `disabled` property.
-
-v0.14.3
+  - Icon, a simple wrapper for creating icons using material-icons font
+  - MaterialIcon, for creating the close/clear and caret as SVG
+
+## 📖 Usage Instructions
+
+### Quick Start
+
+1. **Install the package**:
+
+   ```bash
+   npm install mithril mithril-materialized
+   ```
+
+2. **Import the CSS** (optional, for Material Design styling):
+
+   ```typescript
+   import 'mithril-materialized/index.css';
+   ```
+
+3. **Use components in your app**:
+
+   ```typescript
+   import m from 'mithril';
+   import { 
+     TextInput, 
+     Button, 
+     DatePicker,
+     DataTable,
+     ThemeToggle,
+     FileUpload,
+     Sidenav,
+     Breadcrumb,
+     Wizard
+   } from 'mithril-materialized';
+
+   const MyComponent = () => ({
+     view: () => m('.container', [
+       // Theme toggle in header
+       m('nav', [
+         m('.nav-wrapper', [
+           m('.right', m(ThemeToggle))
+         ])
+       ]),
+       
+       // Breadcrumb navigation
+       m(Breadcrumb, {
+         items: [
+           { text: 'Home', href: '/' },
+           { text: 'Products', href: '/products' },
+           { text: 'Details', active: true }
+         ]
+       }),
+       
+       // Form inputs
+       m(TextInput, {
+         label: 'Your name',
+         onchange: (value) => console.log(value)
+       }),
+       m(Button, { 
+         label: 'Submit',
+         onclick: () => alert('Hello!')
+       }),
+       
+       // File upload
+       m(FileUpload, {
+         accept: 'image/*',
+         multiple: true,
+         onFilesSelected: (files) => console.log(files)
+       })
+     ])
+   });
+   ```
 
-- When using a placeholder in an `input` field, the label should be active.
+### Integration with Build Tools
 
-v0.14.2
+**Webpack/Vite/Parcel**: The library works out-of-the-box with modern bundlers.
 
-- `LinksCollection` sometimes created unwanted `href` attribute in links.
+**CSS Framework Integration**: You can use the components with any CSS framework. The included CSS provides Material Design styling, but you can override it with your own styles.
 
-v0.14.1 Using Mithril v2
+**TypeScript**: Full TypeScript support with comprehensive type definitions included.
 
-- Migrated backwards from Mithril v2.0.3 to v2.0.1 due to bugs in the released version.
-- When `Collection` items have an `id` property, the `id` property is used as key (e.g. for sorting the collection). You should not include a `key` property directly in your item's data, as explained [here](https://mithril.js.org/keys.html#avoid-passing-model-data-directly-to-components-if-the-model-uses-key-as-a-data-property).
+See the [live documentation](https://erikvullings.github.io/mithril-materialized/index.html) for examples and component APIs.
 
-v0.14.0 Using Mithril v2
+## 🗺️ Roadmap & Planned Improvements
 
-- Upgrading all dependencies
-- `Pickers` now trigger `onchange` when closing.
-- Replace all links `oncreate: m.route.link` with `m.route.Link`.
+### 🚀 Phase 1: Core Optimizations & New Components (In Progress)
 
-v0.13.15 Patch
+**✅ Completed:**
 
-- `Select` removed `console.warn` in library.
-- Updated `npm` scripts.
+- ✅ Modular CSS architecture with tree-shaking support
+- ✅ Dark theme system with CSS custom properties  
+- ✅ File upload component with drag-and-drop
+- ✅ Theme switching components (ThemeSwitcher, ThemeToggle)
+- ✅ Sidenav component with responsive behavior
+- ✅ Breadcrumb navigation component
+- ✅ Wizard/Stepper component for multi-step forms
 
-v0.13.14 Enhancements
+**✅ Recently Completed:**
 
-- `Dropdown`: displayed text is truncated, so it doesn't overflow the button.
-- `Select` can receive options, e.g. `dropdownOptions: { container: document.body }` to display it properly in a `Modal`.
-- `Modal` examples added with `Select` and `Dropdown` components.
+- ✅ DataTable component with sorting, filtering, and pagination
+- ✅ Enhanced TypeScript definitions with better JSDoc comments
+- ✅ Performance optimizations and bundle size improvements
 
-v0.13.13 Bug fix related to mithril RC7
+### 🎯 Phase 2: Advanced Components & Features
 
-- FIX `Kanban` key usage and drag-n-drop behaviour
+**Data Display:**
 
-v0.13.12 Bug fix
+- TreeView component for hierarchical data
+- Card layouts with enhanced Material Design 3.0 styling
 
-- `Options` `checkboxClass` was not applied, so you could not align items properly.
+**Input & Forms:**
 
-v0.13.11 Enhancements
+- Advanced date range picker
+- Autocomplete with async data loading
 
-- `Chips` component can now have an optional `label` (title) and `helperText` (under the input). Also the alignment has been fixed (the input used to be slightly wider than a regular input).
+**Navigation & Layout:**
 
-v0.13.10 Enhancement
+- AppBar/Toolbar component with responsive behavior
+- Bottom navigation component for mobile apps
+- Drawer/Sidebar component with overlay and push modes
+- Grid system enhancements with CSS Grid support
 
-- Added IIFE and ESM output builds
-- Refactoring the code slightly
-- `Chips` now has a default `className: col s12`
+### 🔮 Phase 3: Modern Features & Integration
 
-v0.13.9 Enhancement
+**Developer Experience:**
 
-- `ModalPanel` buttons' `onclick` handler now also receives the event, so you can prevent mithril from redrawing.
-- `ModalPanel` has a new handler, `onCreate` which can be used to receive the modal instance, so you can control it programmatically.
+- Storybook integration for component documentation
+- Figma design system integration
+- CLI tools for component generation
+- Better accessibility (ARIA) support throughout
 
-v0.13.8 Bug fix
+**Performance & Optimization:**
 
-- `Select`, checkedId is evaluated in the view instead of `oninit`.
+- Virtual scrolling for large lists
+- Lazy loading component utilities
+- Bundle analyzer and optimization tools
+- CSS-in-JS runtime support option
 
-v0.13.6 Minor updates
+**Ecosystem Integration:**
 
-- `Dropdown`, `Kanban`, `TimePicker`, `DatePicker` can be disabled.
+- React compatibility layer
+- Vue.js compatibility layer
+- Web Components export option
+- PWA-friendly components
 
-v0.13.5 Minor updates
+### 📊 Bundle Size Targets
 
-- `Dropdown` id, if not supplied, caused confusion when multiple `Dropdowns` were used on one page.
-- `Kanban` uses type information. New property, `editableIds`, which makes some properties also editable in the list view.
+**Current Status (v2.0.0-beta.5):**
 
-v0.13.0 Breaking changes
+- Total: 70KB gzipped (44KB JS + 26KB CSS)
+- Modular CSS can reduce bundle by 30-50%
 
-- `Select` component now maintains the checkedIds internally, i.e. they are only processed during `oninit`. This is to create consistent behaviour with the `Options` and `RadioButtons` components.
-- `Select`, `Options`, `Dropdown` and `RadioButtons` are no longer of the generic type, since IDs can only be strings or numbers.
-- `ISelectOption` is removed, and is replaced by `IInputOption`, making it easier to switch between a radios, select and options.
-- `Options` has a property `checkedId`, similar to `RadioButtons` and `Select`, to specify the checked/selected IDs. This replaces the `IInputOption.isChecked` property, which has been removed.
+**Phase 1 Targets:**
 
-NEW
+- Core bundle: <40KB gzipped
+- Modular approach: <25KB for typical apps
+- Tree-shaking effectiveness: 60%+
 
-- [Kanban](https://erikvullings.github.io/mithril-materialized/#!/kanban): new component to render an editable list of items. Supports drag-and-drop between lists too, essentially allowing you to create a Kanban list. Hence the name.
-- `InputCheckbox`: label is optional
-- `Options` and `RadioButtons` are more consistent with respect to look and feel.
-- `Options` and `RadioButtons` support an `inline` property to align them horizontally.
-- `Select`, `Options`, and `RadioButtons` all use `IInputOption` to specify their options. An item can be disabled now.
+**Long-term Goals:**
 
-v0.13.0 No breaking changes
+- Individual components: <2KB each
+- Micro-bundle support for single components
+- Zero-runtime CSS option for static sites
 
-- `FileInput`: added `initialValue` to set the initial value more clearly, and added a clear button to remove the input.
+### 🤝 Contributing
 
-v0.12.2 No breaking changes
+We welcome contributions! Priority areas for community involvement:
 
-- `Tabs`: added `contentClass` to add a class to the content.
+1. **High Impact**: New components (DataTable, Sidenav, Breadcrumb)
+2. **Medium Impact**: Accessibility improvements, performance optimizations
+3. **Documentation**: Examples, guides, API documentation
+4. **Testing**: Unit tests, visual regression tests, browser compatibility
 
-v0.12.1 No breaking changes
+See our [contributing guide](CONTRIBUTING.md) for detailed information.
 
-- Simplified bundling after issues in `webpack`.
+### 📈 Performance Benchmarks
 
-v0.12.0 No breaking changes
+**Bundle Size Comparison:**
 
-- `Tabs` component added, to show [tabs](https://erikvullings.github.io/mithril-materialized/#!/misc).
+- mithril-materialized v2.0: 64KB gzipped
+- Material-UI: ~350KB gzipped
+- Materialize CSS + jQuery: ~180KB gzipped
+- Vuetify: ~250KB gzipped
 
-v0.11.11 No breaking changes
+**Runtime Performance:**
 
-- Bug fix: `TextArea` did not invoke `onchange` when the input was cleared.
-- Using Rollup as bundler, generating two bundles (ESM, regular JS).
+- Component initialization: <5ms average
+- Theme switching: <10ms for full page
+- File upload processing: Real-time without blocking
 
-v0.11.8 No breaking changes
-
-- `Collection onclick` event was not registered properly.
-
-v0.11.7 No breaking changes
-
-- `Timeline` title can now be a Vnode too.
-
-v0.11.6 No breaking changes
-
-- `Select` control can now be disabled by adding the property `disabled: true` to the control's properties.
-
-v0.11.5 No breaking changes
-
-- `MapEditor` has an `onchange` callback to notify changes to the properties collection.
-- `MapEditor` allows you to set the column width (`keyClass`) for the key and value column (`keyValue`).
-
-v0.11.4 No breaking changes
-
-- FIX `CodeBlock` missed importing of `css`.
-
-v0.11.3 No breaking changes
-
-- FIX `Timeline`: Default date formatter did not add 1 to the months. See [here](https://www.w3schools.com/js/js_dates.asp).
-- FIX `MapEditor` when dealing with number inputs and the number was 0, it did not work properly.
-- FIX `NumberInput` when the number was 0, the label was not active (and overlaying the number).
-
-v0.11.2 No breaking changes
-
-- FIX Issue with `SecondaryContent` in `Collection` component: when no `href` was provided, it still created a `href=#!undefined` link.
-
-v0.11.1 No breaking changes
-
-- Improved generics of `Select` and `Dropdown` component
-- FIX Issue with `placeholder` in `Select` component: when no item was selected, it would not show the placeholder text.
-
-v0.11.0 New component, `Timeline`
-
-- Added a `Timeline` component to render vertical timelines.
-- `Collection` now accepts other parameters, e.g. styles.
-- All `css` styles are extracted into separate `css` files, and imported in the component. This implies that you don't need to add the required CSS in your own application anymore (except for `materialisecss`, of course).
-- Added documentation using `Typedoc`. It can be found [here](https://erikvullings.github.io/mithril-materialized/typedoc/index.html).
-
-v0.10.0 New component, `MapEditor`
-
-- Added a new component, `MapEditor`, to edit a map of key-value pairs.
-- `InputCheckbox` can now be disabled.
-- Attributes are better dealt with and no longer end up as unused attributes of elements.
-- Fixed a bug for `TextInput`, where sometimes the `active` class was not added even if the `input` element had a value.
-
-v0.9.10 Breaking changes
-
-- Deprecated the use of all `contentClass` properties in favour of the mithril convention `className`.
-
-v0.9.9 Breaking changes
-
-- `ModalPanel`: it's description (i.e. the main content area of the modal) can be a `Vnode`.
-- `Select` does not use `contentClass` anymore, but instead uses the regular mithril `className` (but not `class`, since this is a reserved keyword in TypeScript).
-
-v0.9.6 No breaking changes
-
-- For a `Collection` with secondary content, do not create a SPA route (with a #!) but leave the URL as is.
-
-v0.9.5 No breaking changes
-
-- FIX `Select` bug when numeric option IDs were used and ID === 0, option was never selected.
-
-v0.9.4 No breaking changes
-
-- FIX `Collection` without headers did no longer render.
-
-v0.9.3 No breaking changes
-
-- `Collection` with links can now also contain a header.
-- `Collection` with no items and only a header will now just render the header
-
-v0.9.0 Breaking changes
-
-- `Collapsible` is now correctly spelled (used to be `Collabsible`, oops).
-- Added `Collection`, to create a collection of items: supports basic, link and avatar collections.
-
-v0.8.3 No breaking changes
-
-- `FileInput` component can be disabled, and accepts file types.
-
-v0.8.1 No breaking changes
-
-- Closes issue #1: Select issue with id === 0
-- MaterialBox can set height, passes attributes to wrapped image element
-
-v0.8.0 No breaking changes
-
-- `FileInput` component can specify `class` property on the `div` wrapper (default `col s12`) and `contentClass` property on the file input element.
-
-v0.7.0 Breaking changes for Dropdown component.
-
-- New `FileInput` component to upload one or more files.
-- `Dropdown` uses similar items as `Select`, and uses `checkedId` to select the item.
-- `Dropdown` items can now use an icon and dividers.
-- `Dropdown` can now have a helper text option and an icon prefix.
+## Build instructions
 
-v0.6.4 Breaking changes, bug fix.
+This repository consists of two packages, combined using `lerna`: the `lib` package that is published to `npm`, as well as an `example` project which uses this library to display the Mithril components that it contains.
 
-- `Select` did not always return the proper id on selection changes with multiple elements.
+To install the dependencies, you can use `npm i`, or, alternatively, use `pnpm m i` (assuming you have installed `pnpm` as alternative package manager using `npm i -g pnpm`) to perform a multi-repository install. Next, build everything using `npm start` and visit the documentation page on [http://localhost:1234](http://localhost:1234) in case port 1234 is not occupied already.
 
-v0.6.3 No breaking changes, bug fix.
+## 🎨 Styling & CSS
 
-- `Select` did not update dynamically when checkedId changed.
+### CSS Usage
 
-v0.6.2 No breaking changes
+The library includes carefully crafted CSS that provides Material Design styling without external dependencies. You can import the ready-to-use CSS:
 
-- `Select` can use `M.FormSelectOptions`.
+```typescript
+import 'mithril-materialized/index.css';
+```
 
-v0.6.1 No breaking changes
+**Important**: The CSS styling is **completely independent** of the original materialize-css. This means:
 
-- `Select` can have `disabled` options, and `id` is optional (in which case the label is used).
-- `Select` can use a prefix icon.
+- ✅ No conflicting styles from materialize-css
+- ✅ Smaller CSS bundle size
+- ✅ Custom optimizations for better performance
+- ✅ No external font dependencies
 
-v0.6.0 No breaking changes
+### 🔥 NEW: Modular CSS Architecture
 
-- `Inputs` can now use `onkeyup`, `onkeydown`, and `onkeypress` events. They also return the value.
-- Additionally, they can use `readOnly`, `pattern` and `autocomplete` (does not always seem to work).
+**Tree-shakable CSS modules** for optimal bundle sizes! Import only the CSS you need:
 
-v0.5.0 No breaking changes
+```typescript
+// Option 1: Import everything (64KB total)
+import 'mithril-materialized/index.css';
 
-- NEW: Pagination control
-- BUG FIX: `Input.onchange` would not fire if the input was cleared.
-- All options now derives from mithril's `Attributes`.
-- Using `FactoryComponent` type
+// Option 2: Import only what you need (modular approach)
+import 'mithril-materialized/core.css';      // Essential styles (18KB)
+import 'mithril-materialized/forms.css';     // Form components only
+import 'mithril-materialized/components.css'; // Interactive components
 
-v0.4.4 No breaking changes
+// Option 3: Advanced components only when needed
+import 'mithril-materialized/pickers.css';   // Date/Time pickers
+import 'mithril-materialized/advanced.css';  // Carousel, sidenav, etc.
+import 'mithril-materialized/utilities.css'; // Badges, icons, cards
+```
 
-- Do not pass attributes through, e.g. if you had a `m(FlatButton, { onupdate })`, the `onupdate` was passed through to the `HelperText` too.
+**CSS Modules Available:**
 
-v0.4.3 No breaking changes
+- `core.css` (18KB) - Essential foundation (normalize, grid, typography, variables)
+- `components.css` - Interactive components (buttons, dropdowns, modals, tabs)
+- `forms.css` - All form components (inputs, selects, switches, file upload)
+- `pickers.css` - Date and time picker components
+- `advanced.css` - Specialized components (carousel, sidenav, navbar, preloader)
+- `utilities.css` - Visual utilities (badges, cards, icons, toast, chips)
 
-- The validate method for inputs now also accepts the HTMLInputElement
-- Removed a few left-over `console.log` statements.
+**Bundle Size Optimization:**
 
-v0.4.2 No breaking changes
+- Full bundle: 64KB gzipped (44KB JS + 20KB CSS)
+- Modular approach can reduce CSS by 30-50%
+- Use only `core.css` + specific modules for your use case
 
-- Added `required` and `aria-required="true"` attributes when the `required` or `isMandatory` property are set.
+### 🌓 Dark Theme Support
 
-v0.4.1 No breaking changes
+Built-in dark theme support with CSS custom properties:
 
-- Updated all components to use the mithril `dom` attribute instead of performing a document query. This has two advantages: first of all, performance, since we do not need to query for an element we already have. Second, when implementing custom elements that have an `oncreate` function. Using document.query... will lead to no results.
+```typescript
+import { ThemeManager, ThemeSwitcher } from 'mithril-materialized';
 
-v0.4.0 No breaking changes
+// Programmatic theme control
+ThemeManager.setTheme('dark');    // 'light' | 'dark' | 'auto'
+ThemeManager.toggle();            // Toggle between light/dark
+ThemeManager.getTheme();          // Get current theme
 
-- New components: MaterialBox, Collapsible or accordion, and Carousel
+// UI Components
+m(ThemeSwitcher, {
+  onThemeChange: (theme) => console.log('Theme:', theme)
+});
 
-v0.3.0 Breaking changes
+m(ThemeToggle); // Simple toggle button
+```
 
-- Buttons no longer use the `ui` class to specify additional properties like `onclick`. Instead, you can leverage the mithril attributes directly. See the example, `button-page`.
-- `contentClass` has been removed in favour of the default mithril `class` or `className` attribute.
-- The Icon function has been replaced by the `Icon` component. The `SmallIcon` and `PrefixedIcon` have been removed, as they can easily be created using the `Icon` component.
-- The `autofocus` attribute for inputs now also works on updates (by calling the element.focus() method).
-- The code has been split over multiple files, so it is easier to only import the components that you need.
+**CSS Custom Properties**: All colors use CSS variables for runtime theme switching:
 
-v0.2.2
+```css
+:root {
+  --mm-primary-color: #26a69a;
+  --mm-background-color: #ffffff;
+  --mm-text-primary: rgba(0, 0, 0, 0.87);
+}
 
-- Validate function can return a custom validation message. Also, it is called in `onupdate`, so the validation occurs also when you just attach the validate function conditionally.
+[data-theme="dark"] {
+  --mm-primary-color: #80cbc4;
+  --mm-background-color: #121212;
+  --mm-text-primary: rgba(255, 255, 255, 0.87);
+}
+```
 
-v0.2.1
+### SASS Usage
 
-- Label field is optional for inputs.
-- Added autofocus function|property to input fields.
-- Added custom validation using the validate function|property to add valid/invalid label to an input.
-- Removed dependency on materialize-css (it is expected that it is imported via the main app).
+For advanced customization, you can use the SASS source files directly:
 
-## Usage instructions
+```css
+// Import all SASS components
+@import 'mithril-materialized/sass/materialize.scss';
 
-See the [documentation](https://erikvullings.github.io/mithril-materialized/index.html) for examples on how to use this library in your own application. Please note that the library does not include mithril, nor the materialize-css JavaScript or CSS, so you have to include them yourself, as documented.
+// Or import individual components
+@import 'mithril-materialized/sass/components/buttons';
+@import 'mithril-materialized/sass/components/forms';
+@import 'mithril-materialized/sass/components/grid';
+```
 
-## Build instructions
+**SASS Variables**: You can customize colors, spacing, and other design tokens by overriding SASS variables before importing:
 
-This repository consists of two packages, combined using `lerna`: the `lib` package that is published to `npm`, as well as an `example` project which uses this library to display the Mithril components that it contains.
+```css
+// Customize Material Design variables
+$primary-color: #2196F3;
+$secondary-color: #FF9800;
 
-To install the dependencies, you can use `npm i`, or, alternatively, use `pnpm m i` (assuming you have installed `pnpm` as alternative package manager using `npm i -g pnpm`) to perform a multi-repository install. Next, build everything using `npm start` and visit the documentation page on [http://localhost:1234](http://localhost:1234) in case port 1234 is not occupied already.
+// Then import the library
+@import 'mithril-materialized/sass/materialize.scss';
+```
 
-## CSS
+### Custom Styles
 
-Although I've tried to limit the CSS adaptations to a minimum, I needed to tweak certain parts to make it look better. Here are the styles I've added.
+The library includes these additional styles for enhanced functionality:
 
 ```css
 /* For the switch */
@@ -429,7 +408,7 @@ Although I've tried to limit the CSS adaptations to a minimum, I needed to tweak
 .clear-10,
 .clear-15 {
   clear: both;
-  /* overflow: hidden; Précaution pour IE 7 */
+  /* overflow: hidden; Precaution pour IE 7 */
 }
 .clear-10 {
   margin-bottom: 10px;