@jasonshimmy/custom-elements-runtime 0.0.5-beta.0 → 0.0.6-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +79 -82
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,20 +1,22 @@
1
1
  # 🧩 Custom Elements Runtime
2
2
 
3
- > **Ultra-lightweight, type-safe runtime for fast, reactive, and maintainable web components.**
3
+ > **Ultra-light, type-safe runtime for fast, reactive web components.**
4
4
 
5
- Build modern web components with strict TypeScript, zero dependencies, and a functional API. Designed for performance, standards compliance, and developer productivity.
5
+ Build modern components with strict TypeScript, zero dependencies, and a clean functional API. Designed for speed, standards compliance, and productivity.
6
6
 
7
- ## 🚀 Getting Started
7
+ ---
8
+
9
+ ## 🚀 Quick Start
8
10
 
9
11
  ### Install
10
12
 
11
- ```bash
13
+ ```
12
14
  npm install @jasonshimmy/custom-elements-runtime
13
15
  ```
14
16
 
15
- ### Import and use in your project
17
+ ### Example Usage
16
18
 
17
- ```typescript
19
+ ```ts
18
20
  import { component, html } from '@jasonshimmy/custom-elements-runtime';
19
21
 
20
22
  component('my-counter', {
@@ -26,107 +28,102 @@ component('my-counter', {
26
28
  });
27
29
  ```
28
30
 
29
- ### TypeScript support
30
-
31
- All types and interfaces are available for auto-completion and strict typing in code editors. No extra configuration is needed.
31
+ No config needed — TypeScript support is built-in.
32
32
 
33
- ### Advanced usage
33
+ 👉 Explore [Advanced Usage](docs/api-reference.md)
34
34
 
35
- See the [API Reference](docs/api-reference.md) for advanced configuration, SSR, plugin system, global store, event bus, and more.
35
+ ---
36
36
 
37
+ ## ✨ Why Use It?
37
38
 
38
- ## ✨ Features
39
+ - **Stateful or Stateless:** Flexible components with or without internal state
40
+ - **Reactive & Declarative:** Auto updates, attribute sync, and data binding
41
+ - **Functional Templates:** Tagged helpers (`html`, `compile`), Promises, and styles
42
+ - **Refs & Computed:** Access elements or create derived state easily
43
+ - **Built-in Store & Events:** Global state and event bus included
44
+ - **SSR & Hydration:** Universal rendering with opt-in hydration
45
+ - **Error Handling & Focus Retention:** Smooth updates without breaking UX
46
+ - **Plugin System:** Hooks like `onInit`, `onRender`, `onError`
47
+ - **Lightweight Router:** SSR-ready with `<router-view>` and programmatic navigation
48
+ - **Tiny & Fast:** Tree-shakable, modular, no dependencies
39
49
 
40
- - **Stateless & Stateful Components:** Define components with or without state for maximum flexibility and performance.
41
- - **Reactive State & Attribute Sync:** Automatic re-renders and attribute reflection for primitive keys. Direct assignment triggers batched updates.
42
- - **Functional Templates & Styling:** Use functions, tagged helpers (`html`, `compile`), or async Promises. Supports static and dynamic styles.
43
- - **Refs & Computed Properties:** Direct DOM access via `data-ref` and derived state with `computed`.
44
- - **Declarative Event & Input Binding:** Use `data-on-*`, `data-model`, and `data-bind` for type-safe event and input sync, including deep and nested state.
45
- - **Global Store & Event Bus:** Built-in reactive store and event bus for cross-component state and communication.
46
- - **SSR & Hydration:** Universal rendering, opt-in hydration, and template matching. SSR excludes refs, event listeners, and lifecycle hooks.
47
- - **Error Boundaries & Focus Preservation:** Robust error handling and input focus retention during updates.
48
- - **Plugin System:** Extend runtime with hooks (`onInit`, `onRender`, `onError`) for global/component logic.
49
- - **Router:** Lightweight, functional router with SSR/static site support, `<router-view>`, route params, and programmatic navigation.
50
- - **Performance & Modularity:** Smart DOM batching, tree-shakable exports, strict TypeScript, and modular functional API.
50
+ ---
51
51
 
52
- ### Limitations & Edge Cases
52
+ ## ⚠️ Things to Know
53
53
 
54
- - Templates require a single root node. Fragments are supported, but strict reconciliation and keys are recommended for robust updates.
55
- - Only one event handler per event type per element; handlers must be defined on the config object.
56
- - Controlled input sync always prioritizes user typing over state updates.
57
- - SSR hydration is opt-in via `data-hydrate`; refs, event listeners, and lifecycle hooks are excluded during SSR.
58
- - User-generated content is escaped in templates using `html` and `compile` helpers.
59
- - Only documented features are supported; undocumented features may not work as expected.
60
- - Plugin system hooks must be pure and side-effect free for best results.
61
- - Router requires template matching for SSR hydration; navigation is programmatic and declarative.
54
+ - Templates need a single root node (fragments allowed with keys)
55
+ - One handler per event type per element
56
+ - User input takes priority over programmatic changes
57
+ - SSR hydration is opt-in (`data-hydrate`)
58
+ - Only documented features are officially supported
59
+ - Plugins must be pure and side-effect free
60
+ - Router requires matching templates for SSR hydration
62
61
 
62
+ ---
63
63
 
64
- ## � Use Cases
64
+ ## 🔧 Use Cases
65
65
 
66
- - **Micro-frontends**: Lightweight, isolated components
67
- - **Progressive Enhancement**: Add reactivity to existing sites
68
- - **Design Systems**: Reusable component libraries
69
- - **SSR Applications**: Universal rendering with hydration
70
- - **Performance-Critical Apps**: When bundle size matters
71
- - **Web Standards**: Future-proof, standards-based development
72
- - **Static Site Generation**: Pre-render routes for instant loads and SEO
73
- - **Plugin-driven Architectures**: Extend runtime with custom hooks
66
+ - Micro-frontends
67
+ - Progressive enhancement
68
+ - Design systems
69
+ - SSR apps
70
+ - Performance-critical projects
71
+ - Standards-based development
72
+ - Static site generation
73
+ - Plugin-extendable architectures
74
74
 
75
+ ---
75
76
 
76
77
  ## 🖥️ SSR Highlights
77
78
 
78
- - **Universal Rendering & SEO:** Fast, standards-compliant HTML/CSS for instant loads and search optimization.
79
- - **Opt-in Hydration:** Hydrate only needed regions for efficient interactivity; templates must match for seamless transitions.
80
- - **Fragment & Keyed Templates:** Robust reconciliation for fragments and keyed nodes.
81
- - **Error Boundaries & Compliance:** Graceful fallback UI; lifecycle hooks and refs excluded for predictable SSR.
82
- - **SSR Router Support:** Match routes server-side for static site generation and universal rendering.
79
+ - SEO-friendly HTML/CSS out of the box
80
+ - Hydrate only what you need
81
+ - Robust support for fragments, keyed nodes, and error handling
82
+ - Compatible with routing and static site generation
83
83
 
84
+ ---
84
85
 
85
- ## 🛡️ Production-Readiness
86
+ ## 🛡️ Production Ready
86
87
 
87
- - Strict TypeScript, modular structure
88
- - Early returns, guard clauses, custom error types
89
- - No external dependencies
90
- - Manual input validation and error handling
91
- - Deep sanitization of user-generated content
92
- - Regression-tested features and API
88
+ - Strict TypeScript and modular design
89
+ - No dependencies
90
+ - Clean error handling and validation
91
+ - Secure: sanitizes user input
92
+ - Fully tested
93
93
 
94
+ ---
94
95
 
95
- ## ⚡ Performance Features
96
+ ## ⚡ Performance Perks
96
97
 
97
- - Smart DOM batching and minimal re-renders
98
- - Tree-shakable exports for optimal bundle size
99
- - Modular functional API for code splitting
100
- - Zero dependencies for maximum speed
101
- - SSR and static site generation for instant loads
102
- - Input focus and selection preservation
103
- - Efficient attribute-state sync and event handling
98
+ - DOM batching and minimal re-renders
99
+ - Tree-shakable exports
100
+ - Focus preservation and efficient DOM updates
101
+ - Async rendering with Promises
102
+ - Smart memory cleanup
104
103
 
105
104
  ---
106
105
 
107
- - **Batched Updates & Caching:** State changes are batched (RAF); templates and computed properties are cached for speed.
108
- - **Memory Management:** Automatic cleanup prevents leaks.
109
- - **Focus & DOM Efficiency:** Input focus is preserved; only changed DOM nodes are updated for optimal UX.
110
- - **Async & Selective Rendering:** Promises supported in templates; hydrate only marked regions for efficient SSR.
111
-
112
-
113
- ## 📚 Documentation
106
+ ## 📚 Learn More
114
107
 
115
- - [Advanced Use Cases](docs/advanced-use-cases.md): Patterns for event bus, store, plugin system, async templates, error boundaries, SSR, VDOM.
116
- - [API Reference](docs/api-reference.md): All runtime exports, configuration options, and advanced patterns.
117
- - [Core Concepts](docs/core-concepts.md): State, attribute sync, event binding, input binding, global store, event bus, lifecycle, error boundaries, SSR, plugin system.
118
- - [Data Model vs Data Bind](docs/data-model-vs-data-bind.md): Comparison, use cases, modifiers, deep binding, edge cases.
119
- - [Examples](docs/examples.md): Concise, accurate code for all features and patterns.
120
- - [Form Input Bindings](docs/form-input-bindings.md): All supported input types, modifiers, deep binding, edge cases, VDOM patching.
121
- - [Framework Comparison](docs/framework-comparison.md): Unique features, tradeoffs, strengths, and when to choose each approach.
122
- - [Framework Integration](docs/framework-integration.md): Using with React, Vue, Angular, Svelte, and Lit.
123
- - [Routing](docs/routing.md): Lightweight, functional router with SSR/static site support.
124
- - [SSR](docs/ssr.md): SSR, hydration, limitations, API.
108
+ - [⚙️ Advanced Use Cases](docs/advanced-use-cases.md)
109
+ - [🛠 API Reference](docs/api-reference.md)
110
+ - [🌱 Core Concepts](docs/core-concepts.md)
111
+ - [🥊 Data Model vs Data Bind](docs/data-model-vs-data-bind.md)
112
+ - [📦 Examples](docs/examples.md)
113
+ - [🎛️ Form Input Bindings](docs/form-input-bindings.md)
114
+ - [🎯 Framework Comparison](docs/framework-comparison.md)
115
+ - [🔗 Framework Integration](docs/framework-integration.md)
116
+ - [🚦 Routing](docs/routing.md)
117
+ - [🌐 SSR Guide](docs/ssr.md)
125
118
 
119
+ ---
126
120
 
127
- See the [API Reference](docs/api-reference.md) for detailed usage, configuration options, and advanced patterns. For advanced topics, see the linked docs above.
121
+ ## 🛠 Local Dev
128
122
 
129
- ## Local development
123
+ ```
124
+ # Clone the repo
125
+ git clone <repo-url>
130
126
 
131
- 1. **Clone this repository**
132
- 2. **Run the examples**: `npm run dev`
127
+ # Run examples
128
+ npm run dev
129
+ ```
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@jasonshimmy/custom-elements-runtime",
3
3
  "description": "A powerful, modern, and lightweight runtime for creating reactive web components with TypeScript",
4
- "version": "0.0.5-beta.0",
4
+ "version": "0.0.6-beta.0",
5
5
  "type": "module",
6
6
  "keywords": [
7
7
  "web-components",