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

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**: Uses custom SVG icons instead of Material Icons font
+- **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
@@ -32,10 +68,8 @@ 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)
+- [Others](https://erikvullings.github.io/mithril-materialized/#!/modals)
   - ModalPanel
-- [Miscellaneous](https://erikvullings.github.io/mithril-materialized/#!/misc)
-  - Tabs
   - MaterialBox
   - Carousel
   - Pagination
@@ -43,385 +77,112 @@ Supported components:
 - 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
-
-- When using a placeholder in an `input` field, the label should be active.
-
-v0.14.2
-
-- `LinksCollection` sometimes created unwanted `href` attribute in links.
-
-v0.14.1 Using Mithril v2
-
-- 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).
-
-v0.14.0 Using Mithril v2
-
-- Upgrading all dependencies
-- `Pickers` now trigger `onchange` when closing.
-- Replace all links `oncreate: m.route.link` with `m.route.Link`.
-
-v0.13.15 Patch
-
-- `Select` removed `console.warn` in library.
-- Updated `npm` scripts.
-
-v0.13.14 Enhancements
-
-- `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.
-
-v0.13.13 Bug fix related to mithril RC7
-
-- FIX `Kanban` key usage and drag-n-drop behaviour
-
-v0.13.12 Bug fix
-
-- `Options` `checkboxClass` was not applied, so you could not align items properly.
-
-v0.13.11 Enhancements
-
-- `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).
-
-v0.13.10 Enhancement
-
-- Added IIFE and ESM output builds
-- Refactoring the code slightly
-- `Chips` now has a default `className: col s12`
+  - Icon, a simple wrapper for creating icons using material-icons font
+  - MaterialIcon, for creating the close/clear and caret as SVG
 
-v0.13.9 Enhancement
+## 📖 Usage Instructions
 
-- `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.
+### Quick Start
 
-v0.13.8 Bug fix
+1. **Install the package**:
 
-- `Select`, checkedId is evaluated in the view instead of `oninit`.
+   ```bash
+   npm install mithril mithril-materialized
+   ```
 
-v0.13.6 Minor updates
+2. **Import the CSS** (optional, for Material Design styling):
 
-- `Dropdown`, `Kanban`, `TimePicker`, `DatePicker` can be disabled.
+   ```typescript
+   import 'mithril-materialized/index.css';
+   ```
 
-v0.13.5 Minor updates
+3. **Use components in your app**:
 
-- `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.
+   ```typescript
+   import m from 'mithril';
+   import { TextInput, Button, DatePicker } from 'mithril-materialized';
 
-v0.13.0 Breaking changes
+   const MyComponent = () => ({
+     view: () => m('.container', [
+       m(TextInput, {
+         label: 'Your name',
+         onchange: (value) => console.log(value)
+       }),
+       m(Button, { 
+         label: 'Submit',
+         onclick: () => alert('Hello!')
+       }),
+       m(DatePicker, {
+         label: 'Select date',
+         onchange: (date) => console.log(date)
+       })
+     ])
+   });
+   ```
 
-- `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.
+### Integration with Build Tools
 
-NEW
+**Webpack/Vite/Parcel**: The library works out-of-the-box with modern bundlers.
 
-- [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.
+**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.13.0 No breaking changes
+**TypeScript**: Full TypeScript support with comprehensive type definitions included.
 
-- `FileInput`: added `initialValue` to set the initial value more clearly, and added a clear button to remove the input.
+See the [live documentation](https://erikvullings.github.io/mithril-materialized/index.html) for examples and component APIs.
 
-v0.12.2 No breaking changes
-
-- `Tabs`: added `contentClass` to add a class to the content.
-
-v0.12.1 No breaking changes
-
-- Simplified bundling after issues in `webpack`.
-
-v0.12.0 No breaking changes
-
-- `Tabs` component added, to show [tabs](https://erikvullings.github.io/mithril-materialized/#!/misc).
-
-v0.11.11 No breaking changes
-
-- Bug fix: `TextArea` did not invoke `onchange` when the input was cleared.
-- Using Rollup as bundler, generating two bundles (ESM, regular JS).
-
-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.
-
-v0.6.4 Breaking changes, bug fix.
-
-- `Select` did not always return the proper id on selection changes with multiple elements.
-
-v0.6.3 No breaking changes, bug fix.
-
-- `Select` did not update dynamically when checkedId changed.
-
-v0.6.2 No breaking changes
-
-- `Select` can use `M.FormSelectOptions`.
-
-v0.6.1 No breaking changes
-
-- `Select` can have `disabled` options, and `id` is optional (in which case the label is used).
-- `Select` can use a prefix icon.
-
-v0.6.0 No breaking changes
-
-- `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).
-
-v0.5.0 No breaking changes
-
-- 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
-
-v0.4.4 No breaking changes
-
-- Do not pass attributes through, e.g. if you had a `m(FlatButton, { onupdate })`, the `onupdate` was passed through to the `HelperText` too.
-
-v0.4.3 No breaking changes
-
-- The validate method for inputs now also accepts the HTMLInputElement
-- Removed a few left-over `console.log` statements.
-
-v0.4.2 No breaking changes
-
-- Added `required` and `aria-required="true"` attributes when the `required` or `isMandatory` property are set.
+## Build instructions
 
-v0.4.1 No breaking changes
+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.
 
-- 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.
+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.4.0 No breaking changes
+## 🎨 Styling & CSS
 
-- New components: MaterialBox, Collapsible or accordion, and Carousel
+### CSS Usage
 
-v0.3.0 Breaking changes
+The library includes carefully crafted CSS that provides Material Design styling without external dependencies. You can import the ready-to-use CSS:
 
-- 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.
+```typescript
+import 'mithril-materialized/index.css';
+```
 
-v0.2.2
+**Important**: The CSS styling is **completely independent** of the original materialize-css. This means:
 
-- 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.
+- ✅ No conflicting styles from materialize-css
+- ✅ Smaller CSS bundle size
+- ✅ Custom optimizations for better performance
+- ✅ No external font dependencies
 
-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
+```scss
+// 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.
+```scss
+// 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 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mithril-materialized",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.0-beta.2",
   "description": "A materialize library for mithril.",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",