zum-framework 1.0.1 → 1.0.3

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