Mithril Materialized UI Development Skill

Description: Expert skill for developing and maintaining the mithril-materialized library—a TypeScript-based Mithril.js component library implementing Material Design without external JavaScript dependencies.

When to use: When working with Mithril Materialized components, creating new ones, fixing bugs, implementing features, or helping users integrate the library.

Project Overview

Mithril Materialized is a zero-external-JS-dependency component library wrapping Material Design in Mithril.js. This monorepo uses pnpm workspaces:

• packages/lib/: Core library (published as mithril-materialized on npm).
• packages/example/: Documentation and live demo site.

Key Architectural Principles

1. Zero External JS Dependencies: Relies solely on CSS for styling; no Materialize.js or jQuery.
2. CSS-Only Styling: No JS initialization needed.
3. Factory Component Pattern: Uses Mithril's FactoryComponent for performance.
4. Controlled/Uncontrolled Support: Components handle both modes.
5. TypeScript First: Full types and JSDoc.
6. Modular CSS: Tree-shakable for optimal bundles.

Component Architecture Patterns

1. Factory Component Pattern

All components follow this for lifecycle management:

import m, { FactoryComponent, Attributes } from 'mithril';

export interface MyComponentAttrs extends Attributes {
  // Attributes here
}

export const MyComponent: FactoryComponent<MyComponentAttrs> = () => {
  const state = { /* Persistent state */ };
  return {
    oninit: ({ attrs }) => { /* Init */ },
    onremove: () => { /* Cleanup */ },
    view: ({ attrs }) => m('.my-component', { /* VNode */ }),
  };
};

2. Controlled vs Uncontrolled

Support both; detect via isControlled(attrs) (checks for value and handler).

• Controlled: Parent manages state via value and oninput/onchange.
• Uncontrolled: Use defaultValue and internal state.

Warn on misuse (e.g., value without handler).

3. Validation

Use ValidatorFunction<T> returning true | false | '' | string.

Validate on blur, track hasInteracted. Integrate with HTML5 validity.

Example:

m(TextInput, {
  validate: (v) => v.length >= 3 || 'Too short',
});

4. Icons

• Icon: For material-icons font.
• MaterialIcon: For SVG icons.

5. Labels and Helpers

Use Label and HelperText for form elements.

Component Categories

LikertScale (v3.13)

Purpose-built for surveys:

• Layouts: Horizontal/vertical/responsive.
• Anchors: Start/middle/end labels.
• Features: Tooltips, numbers, density/size variants.
• Alignment: Grid for multi-question surveys.

When to use:

TypeScript Types

Core types in types.ts: ComponentSize, ValidationResult, etc.

Utilities: RequiredKeys<T>, DeepReadonly<T>.

CSS Architecture

Modular files: core.css, forms.css, etc.

Theme via CSS vars (50+); supports light/dark/auto.

Programmatic: ThemeManager.setTheme('dark') or toggle().

Custom overrides via CSS vars: Override variables like --mm-primary-color or --mm-surface-color in your global CSS.

Development Workflow

Structure:

• lib/src: Components, types, SCSS.
• example/src: Demos.

Commands (root):

• pnpm start: Dev servers.
• npm run build: Build lib.

Releases: npm run patch-release (bumps, builds, publishes).

Best Practices

• Structure: Imports → Types → Factory → State → Helpers → Lifecycle.
• Props: Standard names (label, value, oninput, etc.).
• Events: oninput (real-time), onchange (commit), onblur (validate).
• A11y: Semantics, ARIA, keyboard.
• Perf: Factory pattern, minimal redraws.

Common Tasks

• New Component: Add TS/SCSS, export in index.ts, test in example.
• Modify: Check modes, types, backward compat.
• Debug: Validate on blur; check themes/responsiveness.

Integration Examples

Basic form, data table, theme toggle (condensed; refer to full docs for details).

Testing

Checklist: Modes, validation, themes, a11y, perf.

Pitfalls: Support uncontrolled; validate on blur; use uniqueId().

Quick Reference

• Files: types.ts, utils.ts, index.ts.
• Functions: uniqueId(), ThemeManager.
• New in v3.13: LikertScale, rich Collection content, Rating tooltips.

This skill is a streamlined reference; consult source for implementation details.