zum-framework 1.0.0 → 1.0.1
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.
- package/README.md +79 -25
- package/package.json +1 -3
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
Zum Framework
|
|
2
2
|
|
|
3
|
+
Build with control.
|
|
4
|
+
|
|
3
5
|
A lightweight, component-oriented JavaScript framework for building interactive web applications.
|
|
4
6
|
|
|
5
7
|
Zum Framework provides tools for creating reusable DOM components, managing reactive state, fetching and synchronizing data, handling client-side navigation, managing themes, and building interactive browser applications.
|
|
@@ -8,6 +10,29 @@ Use Zum directly in the browser through a script tag or import it into JavaScrip
|
|
|
8
10
|
|
|
9
11
|
---
|
|
10
12
|
|
|
13
|
+
Table of Contents
|
|
14
|
+
|
|
15
|
+
- "Features" (#features)
|
|
16
|
+
- "Installation" (#installation)
|
|
17
|
+
- "Getting Started" (#getting-started)
|
|
18
|
+
- "Creating Components" (#creating-components)
|
|
19
|
+
- "Component Configuration" (#component-configuration)
|
|
20
|
+
- "Reactive State" (#reactive-state)
|
|
21
|
+
- "Data Fetching" (#data-fetching)
|
|
22
|
+
- "Pagination" (#pagination)
|
|
23
|
+
- "Navigation and Routing" (#navigation-and-routing)
|
|
24
|
+
- "Theme Engine" (#theme-engine)
|
|
25
|
+
- "Animations" (#animations)
|
|
26
|
+
- "Lifecycle Management" (#lifecycle-management)
|
|
27
|
+
- "WebSocket Support" (#websocket-support)
|
|
28
|
+
- "DOM Utilities" (#dom-utilities)
|
|
29
|
+
- "Browser Compatibility" (#browser-compatibility)
|
|
30
|
+
- "Security Considerations" (#security-considerations)
|
|
31
|
+
- "License" (#license)
|
|
32
|
+
- "Author" (#author)
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
11
36
|
Features
|
|
12
37
|
|
|
13
38
|
- Component System: Create reusable DOM components using JavaScript configuration objects.
|
|
@@ -28,11 +53,13 @@ Installation
|
|
|
28
53
|
|
|
29
54
|
npm
|
|
30
55
|
|
|
31
|
-
|
|
56
|
+
Install Zum Framework from the npm registry:
|
|
32
57
|
|
|
33
58
|
npm install zum-framework
|
|
34
59
|
|
|
35
|
-
ES
|
|
60
|
+
ES Modules
|
|
61
|
+
|
|
62
|
+
Import the default export:
|
|
36
63
|
|
|
37
64
|
import Zum from 'zum-framework';
|
|
38
65
|
|
|
@@ -40,23 +67,33 @@ Or import named exports:
|
|
|
40
67
|
|
|
41
68
|
import { Zum, ZumActivity } from 'zum-framework';
|
|
42
69
|
|
|
70
|
+
CommonJS
|
|
71
|
+
|
|
72
|
+
const Zum = require('zum-framework');
|
|
73
|
+
|
|
43
74
|
Browser Script
|
|
44
75
|
|
|
45
76
|
Zum can be used without a bundler or frontend build tool.
|
|
46
77
|
|
|
47
|
-
|
|
78
|
+
After installing the package, include its browser distribution:
|
|
79
|
+
|
|
80
|
+
<script src="./node_modules/zum-framework/dist/zum.iife.min.js"></script>
|
|
48
81
|
|
|
49
82
|
The browser distribution exposes:
|
|
50
83
|
|
|
51
84
|
window.Zum
|
|
52
85
|
window.ZumActivity
|
|
53
86
|
|
|
87
|
+
The browser distribution can also be copied into your project and referenced using its local path.
|
|
88
|
+
|
|
54
89
|
---
|
|
55
90
|
|
|
56
91
|
Getting Started
|
|
57
92
|
|
|
58
93
|
Create an HTML file:
|
|
59
94
|
|
|
95
|
+
index.html
|
|
96
|
+
|
|
60
97
|
<!DOCTYPE html>
|
|
61
98
|
<html lang="en">
|
|
62
99
|
<head>
|
|
@@ -68,7 +105,7 @@ Create an HTML file:
|
|
|
68
105
|
|
|
69
106
|
<div id="app"></div>
|
|
70
107
|
|
|
71
|
-
<script src="./dist/zum.iife.js"></script>
|
|
108
|
+
<script src="./node_modules/zum-framework/dist/zum.iife.min.js"></script>
|
|
72
109
|
|
|
73
110
|
<script>
|
|
74
111
|
async function startApp() {
|
|
@@ -76,14 +113,17 @@ Create an HTML file:
|
|
|
76
113
|
|
|
77
114
|
const component = Zum.create('div', {
|
|
78
115
|
className: 'welcome-card',
|
|
116
|
+
|
|
79
117
|
html: `
|
|
80
118
|
<h1>{{title}}</h1>
|
|
81
119
|
<p>{{message}}</p>
|
|
82
120
|
`,
|
|
121
|
+
|
|
83
122
|
props: {
|
|
84
123
|
title: 'Welcome to Zum',
|
|
85
124
|
message: 'Your application is running.'
|
|
86
125
|
},
|
|
126
|
+
|
|
87
127
|
style: {
|
|
88
128
|
padding: '24px',
|
|
89
129
|
borderRadius: '12px'
|
|
@@ -105,7 +145,7 @@ Create an HTML file:
|
|
|
105
145
|
|
|
106
146
|
Creating Components
|
|
107
147
|
|
|
108
|
-
Use "Zum.create()" to create components.
|
|
148
|
+
Use "Zum.create()" to create reusable components.
|
|
109
149
|
|
|
110
150
|
const card = Zum.create('div', {
|
|
111
151
|
className: 'user-card',
|
|
@@ -130,7 +170,7 @@ Zum.mount(card, '#app');
|
|
|
130
170
|
|
|
131
171
|
Creating Multiple Components
|
|
132
172
|
|
|
133
|
-
Zum provides "Zum.createMany()" for creating
|
|
173
|
+
Zum provides "Zum.createMany()" for creating layouts containing multiple components.
|
|
134
174
|
|
|
135
175
|
const layout = Zum.createMany(
|
|
136
176
|
defaultComponent,
|
|
@@ -144,7 +184,7 @@ The distribution argument controls the percentage distribution of the layout. Th
|
|
|
144
184
|
|
|
145
185
|
Component Configuration
|
|
146
186
|
|
|
147
|
-
Zum components accept configuration options.
|
|
187
|
+
Zum components accept configuration options that control their appearance, behavior, state, and lifecycle.
|
|
148
188
|
|
|
149
189
|
Option| Description
|
|
150
190
|
"html"| HTML template
|
|
@@ -169,7 +209,7 @@ Option| Description
|
|
|
169
209
|
"autoContrast"| Automatic contrast handling
|
|
170
210
|
"safe"| Escapes string and numeric HTML placeholder values
|
|
171
211
|
|
|
172
|
-
Example
|
|
212
|
+
Configuration Example
|
|
173
213
|
|
|
174
214
|
const button = Zum.create('button', {
|
|
175
215
|
html: 'Click Me',
|
|
@@ -193,7 +233,7 @@ Reactive State
|
|
|
193
233
|
|
|
194
234
|
Zum provides component state-management methods.
|
|
195
235
|
|
|
196
|
-
Define
|
|
236
|
+
Define Initial State
|
|
197
237
|
|
|
198
238
|
const counter = Zum.create('div', {
|
|
199
239
|
html: '<h2>Counter</h2>',
|
|
@@ -293,8 +333,6 @@ const result = await Zum.fetch('users', {
|
|
|
293
333
|
|
|
294
334
|
By default, Zum recognizes common response properties such as "data", "items", "posts", and "results".
|
|
295
335
|
|
|
296
|
-
---
|
|
297
|
-
|
|
298
336
|
Local Data Changes
|
|
299
337
|
|
|
300
338
|
Zum supports local modifications to fetched records.
|
|
@@ -325,7 +363,7 @@ Synchronization sends local changes using an HTTP PATCH request. The server must
|
|
|
325
363
|
|
|
326
364
|
Pagination
|
|
327
365
|
|
|
328
|
-
Enable pagination:
|
|
366
|
+
Enable pagination when fetching data:
|
|
329
367
|
|
|
330
368
|
const posts = await Zum.fetch('posts', {
|
|
331
369
|
url: 'https://example.com/api/posts',
|
|
@@ -431,7 +469,7 @@ Theme functionality includes:
|
|
|
431
469
|
- Theme selectors and toggles.
|
|
432
470
|
- Theme import and export.
|
|
433
471
|
|
|
434
|
-
Examples
|
|
472
|
+
Theme Examples
|
|
435
473
|
|
|
436
474
|
Zum.initTheme('light');
|
|
437
475
|
|
|
@@ -447,7 +485,7 @@ Zum.isDarkTheme();
|
|
|
447
485
|
|
|
448
486
|
Zum.isLightTheme();
|
|
449
487
|
|
|
450
|
-
Custom
|
|
488
|
+
Custom Theme Definition
|
|
451
489
|
|
|
452
490
|
Zum.defineTheme('my-theme', {
|
|
453
491
|
// Supply the theme configuration.
|
|
@@ -461,7 +499,7 @@ Animations
|
|
|
461
499
|
|
|
462
500
|
Zum includes built-in animation presets.
|
|
463
501
|
|
|
464
|
-
|
|
502
|
+
Available examples include:
|
|
465
503
|
|
|
466
504
|
- "fade"
|
|
467
505
|
- "slideUp"
|
|
@@ -477,13 +515,13 @@ Examples include:
|
|
|
477
515
|
- "pulse"
|
|
478
516
|
- "reveal"
|
|
479
517
|
|
|
480
|
-
Animate an
|
|
518
|
+
Animate an Element
|
|
481
519
|
|
|
482
520
|
const element = document.querySelector('.my-element');
|
|
483
521
|
|
|
484
522
|
Zum.animate(element, 'fade');
|
|
485
523
|
|
|
486
|
-
Animate an
|
|
524
|
+
Animate an Element Out
|
|
487
525
|
|
|
488
526
|
Zum.animateOut(element, 'fade');
|
|
489
527
|
|
|
@@ -579,13 +617,13 @@ const liveComponent = Zum.create('div', {
|
|
|
579
617
|
|
|
580
618
|
Zum.mount(liveComponent, '#app');
|
|
581
619
|
|
|
582
|
-
Send a
|
|
620
|
+
Send a Message
|
|
583
621
|
|
|
584
622
|
liveComponent.sendWebSocket({
|
|
585
623
|
message: 'Hello server'
|
|
586
624
|
});
|
|
587
625
|
|
|
588
|
-
Close the
|
|
626
|
+
Close the Connection
|
|
589
627
|
|
|
590
628
|
liveComponent.closeWebSocket();
|
|
591
629
|
|
|
@@ -595,7 +633,7 @@ DOM Utilities
|
|
|
595
633
|
|
|
596
634
|
Zum provides utilities for common DOM operations.
|
|
597
635
|
|
|
598
|
-
|
|
636
|
+
Query Elements
|
|
599
637
|
|
|
600
638
|
Zum.find('.container');
|
|
601
639
|
|
|
@@ -607,10 +645,14 @@ Zum.querySelectorAll('.card');
|
|
|
607
645
|
|
|
608
646
|
Zum.elementExists('#app');
|
|
609
647
|
|
|
648
|
+
Display Elements
|
|
649
|
+
|
|
610
650
|
Zum.show(element);
|
|
611
651
|
|
|
612
652
|
Zum.hide(element);
|
|
613
653
|
|
|
654
|
+
Update Elements
|
|
655
|
+
|
|
614
656
|
Zum.updateText(element, 'Updated text');
|
|
615
657
|
|
|
616
658
|
Zum.updateContent(element, '<p>Updated content</p>');
|
|
@@ -619,8 +661,12 @@ Zum.updateStyles(element, {
|
|
|
619
661
|
color: 'blue'
|
|
620
662
|
});
|
|
621
663
|
|
|
664
|
+
Manage Classes
|
|
665
|
+
|
|
622
666
|
Zum.toggleClass(element, 'active');
|
|
623
667
|
|
|
668
|
+
Destroy Elements
|
|
669
|
+
|
|
624
670
|
Zum.destroy(element);
|
|
625
671
|
|
|
626
672
|
Refer to the source implementation for individual method signatures and argument requirements.
|
|
@@ -631,15 +677,21 @@ Browser Compatibility and Usage
|
|
|
631
677
|
|
|
632
678
|
Zum is designed for browser-based JavaScript applications and uses browser APIs, including the DOM.
|
|
633
679
|
|
|
634
|
-
|
|
680
|
+
Direct Browser Usage
|
|
681
|
+
|
|
682
|
+
<script src="./node_modules/zum-framework/dist/zum.iife.min.js"></script>
|
|
635
683
|
|
|
636
|
-
|
|
684
|
+
This approach does not require Vite, npm-based application bundling, or a separate frontend build process once the browser distribution is available locally.
|
|
637
685
|
|
|
638
|
-
|
|
686
|
+
npm Projects
|
|
639
687
|
|
|
640
|
-
For npm projects, Zum provides
|
|
688
|
+
For npm projects, Zum provides:
|
|
641
689
|
|
|
642
|
-
|
|
690
|
+
- ES Module distribution: "dist/zum.mjs"
|
|
691
|
+
- CommonJS distribution: "dist/zum.cjs"
|
|
692
|
+
- Browser distribution: "dist/zum.iife.min.js"
|
|
693
|
+
|
|
694
|
+
The framework's distribution builds are generated using "esbuild-wasm".
|
|
643
695
|
|
|
644
696
|
---
|
|
645
697
|
|
|
@@ -649,6 +701,8 @@ When "safe" is enabled, string and numeric values interpolated through "{{proper
|
|
|
649
701
|
|
|
650
702
|
This does not sanitize arbitrary HTML or JavaScript.
|
|
651
703
|
|
|
704
|
+
Security recommendations:
|
|
705
|
+
|
|
652
706
|
- Do not insert untrusted HTML into component templates.
|
|
653
707
|
- Do not execute scripts received from untrusted sources.
|
|
654
708
|
- Validate and sanitize user-generated content.
|
package/package.json
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
|
-
|
|
2
1
|
{
|
|
3
2
|
"name": "zum-framework",
|
|
4
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
5
4
|
"description": "A lightweight JavaScript framework for building reactive web applications.",
|
|
6
5
|
"main": "dist/zum.cjs",
|
|
7
6
|
"module": "dist/zum.mjs",
|
|
@@ -35,4 +34,3 @@
|
|
|
35
34
|
"esbuild-wasm": "0.28.2"
|
|
36
35
|
}
|
|
37
36
|
}
|
|
38
|
-
|