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.
Files changed (2) hide show
  1. package/README.md +79 -25
  2. 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
- After the package is published:
56
+ Install Zum Framework from the npm registry:
32
57
 
33
58
  npm install zum-framework
34
59
 
35
- ES Module
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
- <script src="./dist/zum.iife.js"></script>
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 responsive layouts.
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 initial state:
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 theme definition:
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
- Examples include:
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 element:
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 element out:
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 message:
620
+ Send a Message
583
621
 
584
622
  liveComponent.sendWebSocket({
585
623
  message: 'Hello server'
586
624
  });
587
625
 
588
- Close the connection:
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
- Examples:
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
- For direct browser usage:
680
+ Direct Browser Usage
681
+
682
+ <script src="./node_modules/zum-framework/dist/zum.iife.min.js"></script>
635
683
 
636
- <script src="./dist/zum.iife.js"></script>
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
- This approach does not require Vite, npm, or a separate application bundling process.
686
+ npm Projects
639
687
 
640
- For npm projects, Zum provides ESM and CommonJS distribution files.
688
+ For npm projects, Zum provides:
641
689
 
642
- The framework's distribution build uses "esbuild-wasm".
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.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
-