Refactor code structure for improved readability and maintainability.…

[iantrich]

Boilerplate Card - Modernization Summary

Overview

Modernize from 2023 tooling (honestly might be older than that) to current 2026 standards. The project now uses the latest stable versions of all major dependencies.

Major Version Updates

Core Dependencies

Package	Old	New	Notes
Lit	2.0.0	3.3.2	Major version with improved performance and StandardElement API
TypeScript	4.4.3	5.6.0	Improved type inference, better error messages
Rollup	2.58.0	4.20.0	Modern bundler with improved tree-shaking
ESLint	7.32.0	9.39.1	Latest stable
Material Web Components	0.25.3	0.27.0	Latest maintained version
custom-card-helpers	1.7.2	2.0.0	Updated Home Assistant integration library
home-assistant-js-websocket	5.11.1	9.6.0	Major version with improved stability

Dev Dependencies - Removed

• @babel/core (^7.15.0) - No longer needed; TypeScript handles transpilation
• @babel/plugin-proposal-class-properties - Decorators now standardized
• @babel/plugin-proposal-decorators - Decorators now standardized
• rollup-plugin-babel - Redundant with TypeScript plugins
• rollup-plugin-commonjs - Replaced with @rollup/plugin-commonjs
• rollup-plugin-node-resolve - Replaced with @rollup/plugin-node-resolve
• rollup-plugin-terser - Replaced with @rollup/plugin-terser
• rollup-plugin-typescript2 - Replaced with @rollup/plugin-typescript

Dev Dependencies - Added

• @rollup/plugin-commonjs (^26.0.0) - Official Rollup CommonJS support
• @rollup/plugin-node-resolve (^15.2.0) - Official Rollup Node resolver
• @rollup/plugin-terser (^0.4.4) - Official Rollup minifier
• @rollup/plugin-typescript (^11.1.0) - Official Rollup TypeScript support
• tslib (^2.6.0) - TypeScript runtime library helper
• @typescript-eslint/* (^8.0.0) - Latest TypeScript ESLint parser

Build Configuration Changes

tsconfig.json

- "target": "es2017",                 # Was outdated
+ "target": "es2022",                 # Modern browser target
- "moduleResolution": "node",         # Deprecated
+ "moduleResolution": "bundler",      # Modern bundler resolution
+ "strict": true,                     # Better type safety
- "noImplicitAny": false,             # Disabled strict typing
+ (removed)                           # Now enforced

rollup.config.js

• Migrated from rollup-plugin-typescript2 to @rollup/plugin-typescript
• Added ES module support with createRequire for require.resolve()
• Removed Babel plugin (TypeScript now handles transpilation)
• Updated plugin imports to use official @rollup packages
• Proper plugin filtering to exclude disabled plugins

package.json

• Added "type": "module" to support ES module imports
• Removed Babel configuration entirely
• Added tslib as dependency for TypeScript helpers

.eslintrc.json (New)

Created modern ESLint configuration with:

• TypeScript parser support
• ESLint v8 compatible rules
• Proper import resolution
• Prettier integration
• Common sense defaults

Code Quality Improvements

Type Safety

• Replaced any types with proper typing:
  • any → Record<string, unknown> for dynamic objects
  • any → WindowWithCustomCards interface for window object
• Added proper interfaces:
  • IActionHandler - renamed from interface-class collision
  • Ripple - proper typing for mwc-ripple element
  • WindowWithCustomCards - window augmentation

Module Improvements

• Updated all local imports to include .js extensions for ES module compatibility
• Fixed import paths: './rollup-plugins/ignore' → './rollup-plugins/ignore.js'
• Proper CommonJS require polyfill in ES module context

ESLint Compliance

All linting passes successfully:

• ✅ No @typescript-eslint/no-explicit-any violations
• ✅ No unsafe declaration merging
• ✅ Proper unused variable detection
• ✅ All files lint without errors

Breaking Changes & Migration Notes

Lit 3.x Changes

• Decorators are now stabilized (no Babel plugins needed)
• Improved PropertyValues API
• Better performance with StandardElement

ESLint Configuration

• Old .eslintrc files ignored; new .eslintrc.json uses flat config
• Consider upgrading to ESLint 9 when Node 20.19+ is available
• Airbnb style guide still in use

TypeScript 5.x Changes

• Enhanced type inference may catch previously ignored errors
• const type parameters now available
• Better support for modern JavaScript features

Build & Runtime

Build Output

Command	Description
yarn build	Lint + production bundle (minified, ES2022 output)
yarn rollup	Production bundle only (skips lint)
yarn start	Development watcher with hot reload (rollup --watch)
yarn lint	ESLint across all src/ files

Build Artifacts

• Source maps available for debugging
• Minified output with Terser
• Tree-shaking enabled by default
• ES2022 target for modern browsers

Performance Improvements

1. TypeScript 5.6 - Faster compilation and better type checking
2. Rollup 4 - Improved bundling performance
3. ESLint 8 - Faster linting
4. Lit 3 - Runtime performance improvements for templating

Compatibility

• Node.js: v24+ (tested on v24.14.0)
• yarn: v4.12.0
• Browsers: Modern browsers (ES2022 target)
• Home Assistant: Compatible with current versions

Files Modified

Configuration Files

• ✅ package.json - Updated all dependencies, added type module
• ✅ tsconfig.json - Modern compiler options
• ✅ rollup.config.js - Modernized Rollup configuration
• ✅ rollup.config.dev.js - Development build config
• ✅ .eslintrc.json - New ESLint configuration (created)

Source Code

• ✅ src/boilerplate-card.ts - Proper typing for custom cards
• ✅ src/editor.ts - Fixed element imports
• ✅ src/action-handler-directive.ts - Type-safe directive implementation
• ✅ src/localize/localize.ts - Improved type safety

Updated devcontainer

Migrated to custom-cards/custom-card-devcontainer

Action Handler Directive (Complete Rewrite)

The src/action-handler-directive.ts was fully rewritten to implement a comprehensive,
cross-platform interaction system based on the button-card pattern.

Interaction Support Added

Interaction	Support
Mouse click (desktop)	✅ tap action
Touch tap (mobile)	✅ tap action
Hold (500ms timeout)	✅ hold action
Repeating hold	✅ configurable interval + limit
Double tap	✅ double_tap action
Keyboard (Enter / Space)	✅ fires click
Scroll/move cancellation	✅ cancels hold timer
Context menu prevention	✅ suppressed
Momentary press/release	✅ isMomentary option

Editor Controls Expansion

New Config Fields (src/types.ts)

Field	Type	Default	Description
card_style	'default' | 'compact' | 'detailed' | 'minimal'	'default'	Visual layout variant
accent_color	[number, number, number]	—	RGB accent color applied via CSS variable
attribute_limit	number	3	Max entity attributes displayed (0 = hidden)
show_timestamps	boolean	true	Toggle last-changed / last-updated display

New Editor Sections (src/editor.ts)

Appearance section (after Actions):

• ha-selector select — Card Style dropdown with four labeled options
• ha-selector color_rgb — Accent Color using HA's native color picker

Display section:

• ha-selector number — Attribute Limit (box mode, 0–10)
• ha-switch — Show Timestamps toggle

Added _selectorChanged handler for generic ha-selector fields, separate from the
existing _actionChanged handler for action selectors.

Card Rendering (src/boilerplate-card.ts)

• ha-card receives class="clickable-card style-${card_style}" for CSS variant targeting
• --card-accent-color CSS custom property injected inline when accent_color is set
• _renderAttributes() now accepts a limit parameter, wired to attribute_limit
• Action buttons suppressed when card_style === 'minimal'
• Timestamps wrapped in show_timestamps !== false conditional

CSS Variants Added

Class	Effect
.style-compact	Reduced padding, smaller text (8px content padding)
.style-detailed	Larger text (20px name), bigger icons (36px), 24px padding
.style-minimal	Entity row only — attributes and timestamps hidden via CSS

CSS Variants Added

Class	Effect
.style-compact	Reduced padding, smaller text (8px content padding)
.style-detailed	Larger text (20px name), bigger icons (36px), 24px padding
.style-minimal	Entity row only — attributes and timestamps hidden via CSS

Editor Accordion Sections

The editor was restructured from a long flat list of controls into collapsible accordion
sections to improve usability as the number of config fields grew.

Accordion Sections (src/editor.ts)

Four sections, only one open at a time:

Section	Fields	Default State
Entity	entity, area, name, icon, show_warning, show_error	Open
Actions	tap_action, hold_action, double_tap_action	Collapsed
Appearance	card_style, accent_color, layout, display_mode	Collapsed
Display	attribute_limit, show_timestamps	Collapsed

Implementation Details

• @state() private _openSection = 'entity' — tracks which section is expanded
• _renderSection(id, title, content) — reusable helper that wraps any content block in
  an accordion shell
• _toggleSection(ev, id) — dedicated handler that calls ev.stopPropagation(),
  ev.stopImmediatePropagation(), and this.requestUpdate() explicitly; required because
  HA's editor container re-invokes setConfig on bubbling click events, racing against
  Lit's microtask update and freezing the view
• All accordion <button> elements use type="button" to prevent accidental form
  submission behaviour in HA's editor host

CSS Animate Technique

Expand/collapse uses the grid-template-rows: 0fr → 1fr CSS grid trick (no JavaScript
height measurement required):

.accordion__body {
  display: grid;
  grid-template-rows: 0fr;
  transition: grid-template-rows 0.25s ease;
}
.accordion--open .accordion__body {
  grid-template-rows: 1fr;
}
.accordion__content {
  overflow: hidden;
}

[Copilot]

Pull request overview

This pull request modernizes the Boilerplate Card from 2023 tooling to 2026 standards, upgrading all major dependencies and introducing significant new features. The project transitions from Lit 2 to Lit 3, TypeScript 4 to 5, Rollup 2 to 4, and migrates build tooling to official Rollup plugins while removing Babel dependencies.

Changes:

• Major dependency upgrades: Lit 3.3.2, TypeScript 5.9.3, Rollup 4.20.0, ESLint 9.39.1, custom-card-helpers 2.0.0
• Complete action-handler-directive rewrite with improved gesture support (tap, hold, double-tap, keyboard, repeat)
• Visual editor refactored with accordion sections and new config fields (card_style, accent_color, layout, display_mode, attribute_limit, show_timestamps)
• Extensive boilerplate-card enhancements: skeleton loading, badge mode, horizontal layout, responsive design, comprehensive styling
• Build system modernization: ES module support, removed Babel, official Rollup plugins, updated devcontainer

Reviewed changes

Copilot reviewed 32 out of 45 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
package.json	Dependency version updates, ES module type declaration - has critical version errors
tsconfig.json	ES2022 target, bundler module resolution, strict mode enabled
src/types.ts	Added new config fields for appearance, layout, display options
src/editor.ts	Complete rewrite with accordion UI, new selectors for visual config
src/boilerplate-card.ts	Extensive expansion: skeleton, badge mode, layouts, action buttons, styling
src/action-handler-directive.ts	Complete rewrite with improved gesture handling and event management
src/localize/localize.ts	Type-safe localization with proper fallback handling
rollup.config.js	Modernized to official @rollup plugins, removed Babel
eslint.config.js	New flat config for ESLint 9
.devcontainer/*	Migrated to thomasloven/hass-custom-devcontainer image
README.md	Comprehensive rewrite with modern documentation
.github/workflows/*	Updated to actions/checkout@v4, setup-node@v4, npm ci

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 38 changed files in this pull request and generated 10 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[iantrich]

Blocked by thomasloven/hass-custom-devcontainer#231 which add LOVELACE_REMOTE_FILES functionality to Thomas' devcontainer so you can remotely use a hosted card in the devcontainer, allowing for easier debugging and builds of the card being developed

[iantrich]

Utilizes new custom-card-helpers release https://github.com/custom-cards/custom-card-helpers/releases/tag/2.0.0

[Copilot]

Pull request overview

Copilot reviewed 34 out of 39 changed files in this pull request and generated 8 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[iantrich]

I saw here piitaya/lovelace-mushroom#1860 that mwc components may longer be available. Need to investigate this further.