zum-framework 1.0.0 → 1.0.2

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 +15 -677
  2. package/package.json +1 -3
package/README.md CHANGED
@@ -1,683 +1,21 @@
1
- Zum Framework
1
+ ## Documentation & Learning Resources
2
2
 
3
- A lightweight, component-oriented JavaScript framework for building interactive web applications.
3
+ Explore the complete Zum Framework documentation and learning resources at:
4
4
 
5
- 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.
5
+ **https://zumscript.com**
6
6
 
7
- Use Zum directly in the browser through a script tag or import it into JavaScript projects through npm.
7
+ The official website provides:
8
8
 
9
- ---
9
+ - Complete documentation and API reference
10
+ - Step-by-step tutorials and learning guides
11
+ - Practical code samples and implementation guides
12
+ - Working examples and demonstrations
13
+ - Component development and state management guides
14
+ - Data fetching and synchronization tutorials
15
+ - Navigation, themes, animations, and WebSocket guides
16
+ - User privacy information
17
+ - License terms and usage conditions
10
18
 
11
- Features
19
+ Whether you are getting started with Zum or building advanced web applications, visit the official website for the resources you need.
12
20
 
13
- - Component System: Create reusable DOM components using JavaScript configuration objects.
14
- - Reactive State: Manage component state and observe property changes.
15
- - Data Fetching: Fetch remote data with caching, local modifications, and change detection.
16
- - Pagination: Manage paginated API responses.
17
- - Local Data Synchronization: Track local modifications and synchronize them with a server.
18
- - Navigation: Handle hash-based navigation and route parameters.
19
- - Theme Engine: Manage built-in themes, custom themes, and theme preferences.
20
- - Animations: Apply built-in animations to DOM elements.
21
- - Lifecycle Management: Handle component mounting, updates, and destruction.
22
- - WebSocket Support: Establish WebSocket connections through component configuration.
23
- - DOM Utilities: Create, query, update, mount, and remove DOM elements.
24
-
25
- ---
26
-
27
- Installation
28
-
29
- npm
30
-
31
- After the package is published:
32
-
33
- npm install zum-framework
34
-
35
- ES Module
36
-
37
- import Zum from 'zum-framework';
38
-
39
- Or import named exports:
40
-
41
- import { Zum, ZumActivity } from 'zum-framework';
42
-
43
- Browser Script
44
-
45
- Zum can be used without a bundler or frontend build tool.
46
-
47
- <script src="./dist/zum.iife.js"></script>
48
-
49
- The browser distribution exposes:
50
-
51
- window.Zum
52
- window.ZumActivity
53
-
54
- ---
55
-
56
- Getting Started
57
-
58
- Create an HTML file:
59
-
60
- <!DOCTYPE html>
61
- <html lang="en">
62
- <head>
63
- <meta charset="UTF-8">
64
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
65
- <title>Zum Application</title>
66
- </head>
67
- <body>
68
-
69
- <div id="app"></div>
70
-
71
- <script src="./dist/zum.iife.js"></script>
72
-
73
- <script>
74
- async function startApp() {
75
- await Zum.ready;
76
-
77
- const component = Zum.create('div', {
78
- className: 'welcome-card',
79
- html: `
80
- <h1>{{title}}</h1>
81
- <p>{{message}}</p>
82
- `,
83
- props: {
84
- title: 'Welcome to Zum',
85
- message: 'Your application is running.'
86
- },
87
- style: {
88
- padding: '24px',
89
- borderRadius: '12px'
90
- }
91
- });
92
-
93
- Zum.mount(component, '#app');
94
- }
95
-
96
- startApp();
97
- </script>
98
-
99
- </body>
100
- </html>
101
-
102
- "Zum.create()" returns a wrapper element containing the generated component.
103
-
104
- ---
105
-
106
- Creating Components
107
-
108
- Use "Zum.create()" to create components.
109
-
110
- const card = Zum.create('div', {
111
- className: 'user-card',
112
-
113
- html: `
114
- <h2>{{name}}</h2>
115
- <p>{{role}}</p>
116
- `,
117
-
118
- props: {
119
- name: 'James',
120
- role: 'Software Developer'
121
- },
122
-
123
- style: {
124
- padding: '20px',
125
- borderRadius: '10px'
126
- }
127
- });
128
-
129
- Zum.mount(card, '#app');
130
-
131
- Creating Multiple Components
132
-
133
- Zum provides "Zum.createMany()" for creating responsive layouts.
134
-
135
- const layout = Zum.createMany(
136
- defaultComponent,
137
- additionalComponents,
138
- '33/33/33'
139
- );
140
-
141
- The distribution argument controls the percentage distribution of the layout. The method supports up to three additional components.
142
-
143
- ---
144
-
145
- Component Configuration
146
-
147
- Zum components accept configuration options.
148
-
149
- Option| Description
150
- "html"| HTML template
151
- "style"| Inline styles
152
- "className"| CSS class name
153
- "events"| Event handlers
154
- "children"| Child elements or component configurations
155
- "attributes"| HTML attributes
156
- "css"| Component-specific CSS
157
- "script"| Component script
158
- "props"| Component properties
159
- "state"| Initial component state
160
- "websocket"| WebSocket configuration
161
- "onMount"| Mount callback
162
- "onUpdate"| Update callback
163
- "onDestroy"| Destruction callback
164
- "anim"| Entrance animation
165
- "autoSave"| Automatic state saving and form binding
166
- "autoSaveDelay"| Automatic-save delay
167
- "exclude"| Exclusion configuration
168
- "render"| Rendering callback
169
- "autoContrast"| Automatic contrast handling
170
- "safe"| Escapes string and numeric HTML placeholder values
171
-
172
- Example:
173
-
174
- const button = Zum.create('button', {
175
- html: 'Click Me',
176
-
177
- attributes: {
178
- type: 'button'
179
- },
180
-
181
- events: {
182
- click: () => {
183
- console.log('Button clicked');
184
- }
185
- }
186
- });
187
-
188
- Zum.mount(button, '#app');
189
-
190
- ---
191
-
192
- Reactive State
193
-
194
- Zum provides component state-management methods.
195
-
196
- Define initial state:
197
-
198
- const counter = Zum.create('div', {
199
- html: '<h2>Counter</h2>',
200
-
201
- state: {
202
- count: 0
203
- }
204
- });
205
-
206
- Zum.mount(counter, '#app');
207
-
208
- Get State
209
-
210
- const state = Zum.getState(counter);
211
-
212
- Update State
213
-
214
- Zum.setState(counter, {
215
- count: 10
216
- });
217
-
218
- Deep State Updates
219
-
220
- Zum.setState(counter, {
221
- user: {
222
- name: 'James'
223
- }
224
- }, {
225
- deep: true
226
- });
227
-
228
- Watch State Properties
229
-
230
- Zum.watchState(counter, 'count', (value) => {
231
- console.log('Count changed:', value);
232
- });
233
-
234
- ---
235
-
236
- Data Fetching
237
-
238
- Zum provides "Zum.fetch()" for managing remote data.
239
-
240
- It supports:
241
-
242
- - HTTP requests.
243
- - Data caching.
244
- - Local modifications.
245
- - Change detection.
246
- - Automatic refresh.
247
- - Success and error callbacks.
248
- - Pagination.
249
- - Custom fetch functions.
250
- - Nested response extraction.
251
-
252
- Basic Usage
253
-
254
- const users = await Zum.fetch('users', {
255
- url: 'https://example.com/api/users',
256
-
257
- method: 'GET',
258
-
259
- onSuccess(data) {
260
- console.log('Users loaded:', data);
261
- },
262
-
263
- onError(error) {
264
- console.error('Request failed:', error);
265
- }
266
- });
267
-
268
- console.log(users.data);
269
- console.log(users.loading);
270
- console.log(users.error);
271
-
272
- Refresh Data
273
-
274
- await users.refresh();
275
-
276
- Subscribe to Changes
277
-
278
- const unsubscribe = users.subscribe((state) => {
279
- console.log('Data:', state.data);
280
- console.log('Loading:', state.loading);
281
- });
282
-
283
- Remove the subscription:
284
-
285
- unsubscribe();
286
-
287
- Extract Nested Response Data
288
-
289
- const result = await Zum.fetch('users', {
290
- url: 'https://example.com/api/response',
291
- dataPath: 'response.users'
292
- });
293
-
294
- By default, Zum recognizes common response properties such as "data", "items", "posts", and "results".
295
-
296
- ---
297
-
298
- Local Data Changes
299
-
300
- Zum supports local modifications to fetched records.
301
-
302
- Update an Item
303
-
304
- users.updateItem(1, {
305
- name: 'Updated Name'
306
- });
307
-
308
- Revert an Item
309
-
310
- users.revertItem(1);
311
-
312
- Synchronize Changes
313
-
314
- await users.syncToServer();
315
-
316
- You can provide a custom synchronization endpoint:
317
-
318
- await users.syncToServer(
319
- 'https://example.com/api/synchronize'
320
- );
321
-
322
- Synchronization sends local changes using an HTTP PATCH request. The server must implement the corresponding endpoint.
323
-
324
- ---
325
-
326
- Pagination
327
-
328
- Enable pagination:
329
-
330
- const posts = await Zum.fetch('posts', {
331
- url: 'https://example.com/api/posts',
332
- pagination: true,
333
- pageSize: 10,
334
- initialPage: 1
335
- });
336
-
337
- Navigate Between Pages
338
-
339
- await posts.nextPage();
340
-
341
- await posts.prevPage();
342
-
343
- await posts.goToPage(3);
344
-
345
- Pagination Information
346
-
347
- console.log(posts.pagination.currentPage);
348
- console.log(posts.pagination.totalPages);
349
- console.log(posts.pagination.totalItems);
350
- console.log(posts.pagination.hasNext);
351
- console.log(posts.pagination.hasPrev);
352
-
353
- ---
354
-
355
- Navigation and Routing
356
-
357
- Zum includes a hash-based navigation system called Activity.
358
-
359
- Access it through:
360
-
361
- Zum.Activity
362
-
363
- Or import the named export:
364
-
365
- import { ZumActivity } from 'zum-framework';
366
-
367
- Register a Page
368
-
369
- Zum.Activity.addPage('/', () => {
370
- const page = document.createElement('div');
371
-
372
- page.textContent = 'Home Page';
373
-
374
- return page;
375
- });
376
-
377
- Route Parameters
378
-
379
- Zum.Activity.addPage('/users/:id', (params) => {
380
- const page = document.createElement('div');
381
-
382
- page.textContent = `User ID: ${params.id}`;
383
-
384
- return page;
385
- });
386
-
387
- Lazy Pages
388
-
389
- Zum.Activity.addLazyPage('/dashboard', async () => {
390
- const page = document.createElement('div');
391
-
392
- page.textContent = 'Dashboard';
393
-
394
- return page;
395
- });
396
-
397
- Navigate
398
-
399
- Zum.Activity.navigateTo('/dashboard');
400
-
401
- Go Back
402
-
403
- Zum.Activity.goBack();
404
-
405
- Get Current Path
406
-
407
- const path = Zum.Activity.getCurrentPath();
408
-
409
- Start Activity
410
-
411
- Zum.Activity.start();
412
-
413
- Activity also provides overlay interfaces, including sidebars, dialogs, option menus, and tool-pick menus.
414
-
415
- ---
416
-
417
- Theme Engine
418
-
419
- Zum includes a theme-management system.
420
-
421
- Theme functionality includes:
422
-
423
- - Built-in themes.
424
- - Custom theme definitions.
425
- - Theme switching.
426
- - System theme preference detection.
427
- - Theme persistence.
428
- - Theme observers.
429
- - Theme color access.
430
- - Accessibility checks.
431
- - Theme selectors and toggles.
432
- - Theme import and export.
433
-
434
- Examples:
435
-
436
- Zum.initTheme('light');
437
-
438
- Zum.toggleTheme();
439
-
440
- Zum.getCurrentTheme();
441
-
442
- Zum.getAvailableThemes();
443
-
444
- Zum.getThemeColors();
445
-
446
- Zum.isDarkTheme();
447
-
448
- Zum.isLightTheme();
449
-
450
- Custom theme definition:
451
-
452
- Zum.defineTheme('my-theme', {
453
- // Supply the theme configuration.
454
- });
455
-
456
- Refer to the framework implementation for the supported theme configuration structure.
457
-
458
- ---
459
-
460
- Animations
461
-
462
- Zum includes built-in animation presets.
463
-
464
- Examples include:
465
-
466
- - "fade"
467
- - "slideUp"
468
- - "slideDown"
469
- - "slideLeft"
470
- - "slideRight"
471
- - "scale"
472
- - "bounce"
473
- - "blurIn"
474
- - "rotateIn"
475
- - "flipIn"
476
- - "shake"
477
- - "pulse"
478
- - "reveal"
479
-
480
- Animate an element:
481
-
482
- const element = document.querySelector('.my-element');
483
-
484
- Zum.animate(element, 'fade');
485
-
486
- Animate an element out:
487
-
488
- Zum.animateOut(element, 'fade');
489
-
490
- Animation presets are also available through:
491
-
492
- Zum.animations
493
-
494
- ---
495
-
496
- Lifecycle Management
497
-
498
- Zum supports component lifecycle callbacks.
499
-
500
- onMount
501
-
502
- const component = Zum.create('div', {
503
- html: '<p>Component mounted</p>',
504
-
505
- onMount() {
506
- console.log('Component mounted');
507
- }
508
- });
509
-
510
- Zum.mount(component, '#app');
511
-
512
- onUpdate
513
-
514
- const component = Zum.create('div', {
515
- html: '<p>Component</p>',
516
-
517
- onUpdate() {
518
- console.log('Component updated');
519
- }
520
- });
521
-
522
- onDestroy
523
-
524
- const component = Zum.create('div', {
525
- html: '<p>Component</p>',
526
-
527
- onDestroy() {
528
- console.log('Component destroyed');
529
- }
530
- });
531
-
532
- Check Mount Status
533
-
534
- Zum.isMounted(component);
535
-
536
- Destroy a Component
537
-
538
- Zum.destroy(component);
539
-
540
- Unmount a Component
541
-
542
- Zum.unmount(component);
543
-
544
- Unmounting removes an element without performing the full component-destruction process.
545
-
546
- ---
547
-
548
- WebSocket Support
549
-
550
- Components can be configured with WebSocket connections.
551
-
552
- const liveComponent = Zum.create('div', {
553
- html: '<p>Live connection</p>',
554
-
555
- websocket: {
556
- url: 'wss://example.com/socket',
557
-
558
- onopen(event) {
559
- console.log('Connected');
560
- },
561
-
562
- onmessage(event) {
563
- console.log('Message:', event.data);
564
- },
565
-
566
- onclose(event) {
567
- console.log('Connection closed');
568
- },
569
-
570
- onerror(error) {
571
- console.error('WebSocket error:', error);
572
- },
573
-
574
- autoReconnect: true,
575
- reconnectInterval: 3000,
576
- maxReconnects: 5
577
- }
578
- });
579
-
580
- Zum.mount(liveComponent, '#app');
581
-
582
- Send a message:
583
-
584
- liveComponent.sendWebSocket({
585
- message: 'Hello server'
586
- });
587
-
588
- Close the connection:
589
-
590
- liveComponent.closeWebSocket();
591
-
592
- ---
593
-
594
- DOM Utilities
595
-
596
- Zum provides utilities for common DOM operations.
597
-
598
- Examples:
599
-
600
- Zum.find('.container');
601
-
602
- Zum.findAll('.item');
603
-
604
- Zum.querySelector('#app');
605
-
606
- Zum.querySelectorAll('.card');
607
-
608
- Zum.elementExists('#app');
609
-
610
- Zum.show(element);
611
-
612
- Zum.hide(element);
613
-
614
- Zum.updateText(element, 'Updated text');
615
-
616
- Zum.updateContent(element, '<p>Updated content</p>');
617
-
618
- Zum.updateStyles(element, {
619
- color: 'blue'
620
- });
621
-
622
- Zum.toggleClass(element, 'active');
623
-
624
- Zum.destroy(element);
625
-
626
- Refer to the source implementation for individual method signatures and argument requirements.
627
-
628
- ---
629
-
630
- Browser Compatibility and Usage
631
-
632
- Zum is designed for browser-based JavaScript applications and uses browser APIs, including the DOM.
633
-
634
- For direct browser usage:
635
-
636
- <script src="./dist/zum.iife.js"></script>
637
-
638
- This approach does not require Vite, npm, or a separate application bundling process.
639
-
640
- For npm projects, Zum provides ESM and CommonJS distribution files.
641
-
642
- The framework's distribution build uses "esbuild-wasm".
643
-
644
- ---
645
-
646
- Security Considerations
647
-
648
- When "safe" is enabled, string and numeric values interpolated through "{{property}}" placeholders in the "html" template are escaped.
649
-
650
- This does not sanitize arbitrary HTML or JavaScript.
651
-
652
- - Do not insert untrusted HTML into component templates.
653
- - Do not execute scripts received from untrusted sources.
654
- - Validate and sanitize user-generated content.
655
- - Use HTTPS for remote API requests.
656
- - Validate server-side data independently.
657
- - Only use trusted code in the "script" configuration.
658
-
659
- ---
660
-
661
- License
662
-
663
- Zum Framework is distributed under the Zum Proprietary License (ZPL) Version 1.0.
664
-
665
- Copyright (c) 2026 James Akandu. All Rights Reserved.
666
-
667
- The license permits developers to build, use, host, monetize, and sell applications developed with Zum.
668
-
669
- It does not grant permission to independently redistribute, sublicense, modify for redistribution, or sell Zum Framework as a standalone framework or development tool without prior written permission.
670
-
671
- See the "LICENSE" (./LICENSE) file for the complete terms.
672
-
673
- ---
674
-
675
- Author
676
-
677
- James Akandu
678
-
679
- Creator and developer of Zum Framework.
680
-
681
- ---
682
-
683
- Zum Framework — Build with control.
21
+ **Official Website:** https://zumscript.com
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.2",
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
-