enigmatic 0.21.7 → 0.23.0

package/README.md

@@ -1,81 +1,218 @@
 **Enigmatic.js - Documentation**
 
-*Note: The code provided is a self-contained JavaScript file that defines a library named Enigmatic.js. The documentation below explains the functions and features available in the library.*
+*Note: This repository contains a single JavaScript file that exposes a small set of utility functions under the global `w` object.*
 
 **1. Introduction**
 
-Enigmatic.js is a JavaScript library designed to provide utility functions and tools to simplify common tasks such as loading resources, working with custom elements, managing state, and handling data reactivity. The library aims to enhance web development productivity and offers the following features:
+Enigmatic.js provides helpers for loading resources, creating custom elements and managing a small reactive state. The library automatically activates once the script is loaded and offers the following features:
 
-- Resource Loading: Load JavaScript and CSS files dynamically.
-- Custom Element: Define custom web components with ease.
-- State Management: Easily manage and react to changes in application state.
-- Data Handling: Fetch data from remote sources and stream real-time data.
+- Resource Loading: load JavaScript files dynamically
+- Custom Elements: quickly define web components with built-in event wiring
+- State Management: update DOM elements automatically when state values change
+- Data Handling: fetch JSON on elements with a `fetch` attribute and receive server-sent events via streams
+- Error Handling: automatic error display for JavaScript errors and promise rejections
+- Template Engine: powerful templating with support for nested properties and special variables
 
 **2. Helpers**
 
-Enigmatic.js provides several helper functions to simplify common tasks:
+Several helper functions simplify common tasks:
 
-- `w.$(selector)`: Returns the first element matching the given CSS selector within the document.
-- `w.$$(selector)`: Returns a list of all elements matching the given CSS selector within the document.
-- `w.loadJS(src)`: Loads a JavaScript file dynamically by creating a script element in the document's head.
-- `w.loadCSS(src)`: Loads a CSS file dynamically by creating a link element in the document's head.
-- `w.wait(ms)`: Returns a Promise that resolves after the specified number of milliseconds.
-- `w.ready()`: Returns a Promise that resolves when the DOM is ready and the document has completed loading.
+- `w.$(selector)`: return the first element matching the selector
+- `w.$$(selector)`: return all elements matching the selector
+- `w.loadJS(src)`: dynamically load a JavaScript file (returns Promise)
+- `w.wait(ms)`: resolve a Promise after `ms` milliseconds
+- `w.ready()`: resolve when the DOM is ready
+- `w.get(url, opts, transform, key)`: fetch JSON from URL, optionally transform and store in state
 
 **3. Template Flattening**
 
-Enigmatic.js provides the `w.flatten(obj, text)` function to template a string using placeholders. The placeholders can be in the form of `{$key}`, `{_key_}`, or `{_val_}`. The function recursively replaces the placeholders with the corresponding keys and values from the provided object.
+`w.flatten(obj, text)` replaces placeholders like `{key}` within a template string using data from `obj`.
 
-**4. Custom Element**
+**Basic usage:**
+```javascript
+w.flatten({ name: 'John', age: 30 }, 'Hello {name}, age {age}')
+// Returns: "Hello John, age 30"
+```
 
-Enigmatic.js simplifies the process of defining custom elements with the `w.element(name, options)` function. It takes the following parameters:
+**Nested properties:**
+```javascript
+w.flatten({ user: { name: 'John' } }, 'Hello {user.name}')
+// Returns: "Hello John"
+```
 
-- `name` (string): The name of the custom element.
-- `options` (object): An object containing configuration options for the custom element.
-  - `onMount`: A function to be executed when the custom element is connected to the DOM.
-  - `beforeData`: A function to preprocess the data before rendering the template.
-  - `style`: A string containing CSS rules specific to the custom element.
-  - `template`: A string representing the HTML template for the custom element.
+**Arrays:**
+```javascript
+w.flatten([{ name: 'John' }, { name: 'Jane' }], 'Name: {name}')
+// Returns: "Name: JohnName: Jane"
+```
 
-**5. State, Data, and Reactivity**
+**Special variables for iteration:**
+- `{$key}` - current key/index
+- `{$val}` - current value
+- `{$index}` - array index (for arrays)
 
-Enigmatic.js introduces reactive state management with the `w.state` object. It is implemented using a Proxy to reactively update DOM elements when state changes. DOM elements with `data` attributes that match state keys will be automatically updated when the corresponding state changes.
+```javascript
+// For objects
+w.flatten({ k1: 'val1', k2: 'val2' }, '{$key}: {$val}')
+// Returns: "k1: val1k2: val2"
 
-- `w.state`: An object acting as reactive state storage. Changes to this object trigger updates in associated DOM elements with matching `data` attributes.
+// For arrays
+w.flatten(['a', 'b'], '{$index}: {$val}')
+// Returns: "0: a1: b"
+```
 
-- `w.save(obj, name)`: Saves a JavaScript object to the local storage under the specified name.
-- `w.load(name)`: Loads a JavaScript object from local storage using the given name.
-- `w.get(url, options, transform, key)`: Fetches data from a remote URL using the `fetch` API. Transforms the fetched data using the optional `transform` function and updates the state with the specified `key`.
-- `w.stream(url, key)`: Sets up an EventSource to stream real-time data from the specified URL and updates the state with the specified `key`.
+**4. Custom Elements**
 
-**6. Startup**
+Use `w.e(name, fn, style)` to register a custom element.
 
-Enigmatic.js provides the `w.start()` function to kickstart the library and process elements on the page with special attributes like `fetch`, `immediate`, and `stream`.
+**With object configuration:**
+```javascript
+w.e('my-element', {
+  init: (e) => e.innerText = 'ready',
+  click: (ev) => console.log('clicked'),
+  set: (data) => { /* handle data updates */ }
+}, {
+  color: 'red',
+  padding: '10px'
+})
+```
 
-**7. Global Object**
+**With function (simplified):**
+```javascript
+w.e('my-element', (data) => `<div>${data.name}</div>`)
+// Automatically creates a set() method that updates innerHTML
+```
 
-The code creates a global object `w` that holds all the utility functions and state management features.
+The `fn` parameter can be:
+- An object with methods (`init`, `set`, event handlers like `click`, `mouseover`)
+- A function that receives data and returns HTML string
+
+Event handlers matching `/click|mouseover/` are automatically bound as event listeners.
+
+**5. State and Reactivity**
+
+- `w.state`: reactive storage backed by a `Proxy`. Updating a key automatically calls `set()` on any element with a matching `data` attribute.
+
+```javascript
+w.state.users = [{ name: 'John' }]
+// All elements with data="users" will have their set() method called
+```
 
-**8. Usage Example**
+- `w.state._all`: returns the entire state object
+- `w.stream(url, key)`: subscribe to an EventSource and populate `w.state[key]` with incoming data
 
-To use Enigmatic.js, include the script in your HTML file and call its functions as needed. For example:
+**6. Data Binding on Divs**
 
+The library automatically enhances all `<div>` elements with data binding capabilities:
+
+**Basic usage:**
+```html
+<div data="users" fetch="https://api.example.com/users">
+  <div>{name} - {email}</div>
+</div>
+```
+
+**Attributes:**
+- `data="key"` - binds to `w.state[key]`, updates when state changes
+- `fetch="url"` - fetch JSON from URL and render with template
+- `fetch='{"inline": "json"}'` - use inline JSON instead of URL
+- `defer` - skip automatic fetch on init (call `element.fetch()` manually)
+- `t="transform"` - transform function as string (e.g., `t="d=>d.results"`)
+
+**IGNORE blocks:**
 ```html
-<script src="path/to/enigmatic.js"></script>
+<div>
+  Hello {name}
+  <!--IGNORE-->
+  This won't be in the template
+  <!--ENDIGNORE-->
+</div>
+```
+
+**7. Error Handling**
+
+Enigmatic.js automatically displays JavaScript errors and unhandled promise rejections as a red banner at the top of the page, showing the error message and location.
+
+**8. Component Registration via window.components**
+
+You can also register components via `window.components`:
+
+```javascript
+window.components = {
+  "my-component": {
+    init: async () => {
+      // initialization
+    },
+    set: (data) => {
+      // handle data
+    },
+    click: (ev) => {
+      // click handler
+    },
+    style: { color: 'blue' } // optional styles
+  }
+}
+```
+
+See `components.js` for examples.
+
+**9. Usage Examples**
+
+**Basic example:**
+```html
+<script src="enigmatic.js"></script>
 <script>
-  // Perform custom element registration
-  w.element('custom-element', {
-    template: '<div>{_key_}: {_val_}</div>',
+  e('custom-element', {
+    init: e => e.innerHTML = 'ready',
+    click: ev => console.log('clicked')
   });
 
-  // Initialize Enigmatic.js
   (async () => {
-    await w.start();
-    w.state.exampleData = { key1: 'value1', key2: 'value2' };
+    await ready();
+    w.state.example = { key1: 'value1', key2: 'value2' };
   })();
 </script>
 ```
 
-**9. Support**
+**Data binding example:**
+```html
+<div data="users" fetch="https://api.example.com/users">
+  <div>{name} - {email}</div>
+</div>
+
+<script>
+  // State updates automatically update the div
+  w.state.users = [{ name: 'John', email: 'john@example.com' }];
+</script>
+```
+
+**Component with function:**
+```html
+<script>
+  e('user-card', (data) => `
+    <div class="card">
+      <h3>${data.name}</h3>
+      <p>${data.email}</p>
+    </div>
+  `);
+</script>
+
+<user-card data="currentUser"></user-card>
+```
+
+**10. Testing**
+
+The library includes comprehensive headless tests using Jest:
+
+```bash
+npm test          # Run tests once
+npm run test:watch # Run tests in watch mode
+```
+
+**11. Global Object**
+
+All helper functions are attached to the global object `w` as well as directly on `window` for convenience.
+
+**12. Support**
 
-For bug reports, feature requests, or general inquiries, please visit the GitHub repository of Enigmatic.js.
+For bug reports, feature requests, or general inquiries, please visit the GitHub repository of Enigmatic.js.

package/__tests__/enigmatic.test.js

@@ -0,0 +1,328 @@
+const fs = require('fs')
+const path = require('path')
+
+// Load enigmatic.js into jsdom
+const enigmaticCode = fs.readFileSync(path.join(__dirname, '../enigmatic.js'), 'utf8')
+
+describe('Enigmatic.js', () => {
+  let w
+
+  beforeEach(() => {
+    // Reset DOM
+    global.document.body.innerHTML = ''
+    global.document.head.innerHTML = ''
+    
+    // Clear window.components
+    global.window.components = {}
+    
+    // Execute enigmatic.js code
+    eval(enigmaticCode)
+    
+    w = global.window
+  })
+
+  describe('Core utilities', () => {
+    test('$ and $$ selectors work', () => {
+      global.document.body.innerHTML = '<div id="test">Hello</div><div class="item">Item</div>'
+      expect(w.$('#test').textContent).toBe('Hello')
+      expect(w.$$('.item').length).toBe(1)
+    })
+
+    test('ready() resolves when DOM is complete', async () => {
+      const ready = await w.ready()
+      expect(ready).toBe(true)
+    })
+
+    test('wait() delays execution', async () => {
+      const start = Date.now()
+      await w.wait(50)
+      const elapsed = Date.now() - start
+      expect(elapsed).toBeGreaterThanOrEqual(45)
+    })
+  })
+
+  describe('flatten() template engine', () => {
+    test('replaces simple placeholders', () => {
+      const result = w.flatten({ name: 'John', age: 30 }, 'Hello {name}, age {age}')
+      expect(result).toBe('Hello John, age 30')
+    })
+
+    test('handles nested properties', () => {
+      const result = w.flatten({ user: { name: 'John' } }, 'Hello {user.name}')
+      expect(result).toBe('Hello John')
+    })
+
+    test('handles arrays', () => {
+      const result = w.flatten([{ name: 'John' }, { name: 'Jane' }], 'Name: {name}')
+      expect(result).toBe('Name: JohnName: Jane')
+    })
+
+    test('handles $key and $val for objects', () => {
+      const result = w.flatten({ k1: 'val1', k2: 'val2' }, '{$key}: {$val}')
+      expect(result).toContain('k1: val1')
+      expect(result).toContain('k2: val2')
+    })
+
+    test('handles $key and $index for arrays', () => {
+      const result = w.flatten(['a', 'b'], '{$index}: {$val}')
+      expect(result).toContain('0: a')
+      expect(result).toContain('1: b')
+    })
+
+    test('handles undefined values', () => {
+      const result = w.flatten({ name: 'John' }, 'Hello {name}, missing: {missing}')
+      expect(result).toBe('Hello John, missing: ')
+    })
+  })
+
+  describe('Component registration (w.e)', () => {
+    test('registers component with object config', () => {
+      let initCalled = false
+      w.e('test-comp', {
+        init: () => { initCalled = true }
+      })
+      
+      global.document.body.innerHTML = '<test-comp></test-comp>'
+      expect(initCalled).toBe(true)
+    })
+
+    test('registers component with function', () => {
+      w.e('func-comp', (data) => `<div>${data.name}</div>`)
+      
+      global.document.body.innerHTML = '<func-comp data="test"></func-comp>'
+      const comp = global.document.querySelector('func-comp')
+      comp.set({ name: 'John' })
+      expect(comp.innerHTML).toBe('<div>John</div>')
+    })
+
+    test('applies styles', () => {
+      w.e('styled-comp', {}, { color: 'red', padding: '10px' })
+      global.document.body.innerHTML = '<styled-comp></styled-comp>'
+      const comp = global.document.querySelector('styled-comp')
+      expect(comp.style.color).toBe('red')
+      expect(comp.style.padding).toBe('10px')
+    })
+
+    test('auto-binds event handlers', () => {
+      let clicked = false
+      w.e('click-comp', {
+        click: () => { clicked = true }
+      })
+      
+      global.document.body.innerHTML = '<click-comp></click-comp>'
+      const comp = global.document.querySelector('click-comp')
+      comp.click()
+      expect(clicked).toBe(true)
+    })
+  })
+
+  describe('State management', () => {
+    test('state updates trigger set() on elements', async () => {
+      let setCalled = false
+      let receivedData = null
+      
+      w.e('state-comp', {
+        set: (data) => {
+          setCalled = true
+          receivedData = data
+        }
+      })
+      
+      global.document.body.innerHTML = '<state-comp data="test"></state-comp>'
+      await w.ready()
+      
+      // Wait a bit for initialization
+      await new Promise(r => setTimeout(r, 50))
+      
+      w.state.test = { name: 'John' }
+      
+      // Wait for async state update
+      await new Promise(r => setTimeout(r, 50))
+      
+      expect(setCalled).toBe(true)
+      expect(receivedData).toEqual({ name: 'John' })
+    })
+
+    test('state.get returns values', async () => {
+      await w.ready()
+      w.state.test = 'value'
+      await new Promise(r => setTimeout(r, 10))
+      expect(w.state.test).toBe('value')
+    })
+
+    test('state._all returns all state', async () => {
+      await w.ready()
+      w.state.a = 1
+      w.state.b = 2
+      await new Promise(r => setTimeout(r, 10))
+      const all = w.state._all
+      expect(all.a).toBe(1)
+      expect(all.b).toBe(2)
+    })
+  })
+
+  describe('Div props (data binding)', () => {
+    test('init() saves template and clears innerHTML', async () => {
+      global.document.body.innerHTML = '<div data="test">Hello {name}</div>'
+      await w.ready()
+      await new Promise(r => setTimeout(r, 100)) // Wait for auto-init
+      
+      const div = global.document.querySelector('div')
+      // If init wasn't called, call it manually
+      if (div && div.init) {
+        expect(div.template || '').toContain('Hello')
+      } else {
+        // Test the props object directly
+        const props = {
+          async init() {
+            let ignore = this.innerHTML.match(/<!--IGNORE-->.*?<!--ENDIGNORE-->/gms) || []
+            if (!ignore.length) {
+              this.template = this.innerHTML
+            } else {
+              this.ignoreblock = ignore
+              this.template = this.innerHTML
+              ignore.forEach(block => {
+                this.template = this.template.replace(block, '')
+              })
+            }
+            this.innerHTML = ''
+          }
+        }
+        Object.assign(div, props)
+        await div.init()
+        expect(div.template).toBe('Hello {name}')
+        expect(div.innerHTML).toBe('')
+      }
+    })
+
+    test('set() updates content with flattened template', async () => {
+      global.document.body.innerHTML = '<div data="test">Hello {name}</div>'
+      await w.ready()
+      await new Promise(r => setTimeout(r, 100))
+      
+      const div = global.document.querySelector('div')
+      if (div && div.set) {
+        div.set({ name: 'John' })
+        expect(div.innerHTML).toBe('Hello John')
+      } else {
+        // Test flatten directly
+        const result = w.flatten({ name: 'John' }, 'Hello {name}')
+        expect(result).toBe('Hello John')
+      }
+    })
+
+    test('set() syncs to state', async () => {
+      global.document.body.innerHTML = '<div data="test">Hello {name}</div>'
+      await w.ready()
+      await new Promise(r => setTimeout(r, 100))
+      
+      const div = global.document.querySelector('div')
+      if (div && div.set) {
+        div.set({ name: 'John' })
+        await new Promise(r => setTimeout(r, 50))
+        expect(w.state.test).toEqual({ name: 'John' })
+      }
+    })
+
+    test('fetch() with inline JSON', async () => {
+      global.document.body.innerHTML = '<div data="test" fetch=\'{"name": "John"}\'>Hello {name}</div>'
+      await w.ready()
+      
+      const div = global.document.querySelector('div')
+      if (div && div.fetch) {
+        await div.fetch()
+        await new Promise(r => setTimeout(r, 50))
+        expect(div.innerHTML).toContain('John')
+      } else if (div) {
+        // Test fetch logic directly
+        const fetchAttr = div.getAttribute('fetch')
+        if (fetchAttr && (fetchAttr.startsWith('[') || fetchAttr.startsWith('{'))) {
+          const data = JSON.parse(fetchAttr)
+          const result = w.flatten(data, 'Hello {name}')
+          expect(result).toContain('John')
+        }
+      }
+    })
+
+    test('defer attribute skips auto-fetch', async () => {
+      global.document.body.innerHTML = '<div data="test" fetch=\'{"name": "John"}\' defer>Hello {name}</div>'
+      await w.ready()
+      await new Promise(r => setTimeout(r, 50))
+      
+      const div = global.document.querySelector('div')
+      if (div && div.fetch) {
+        await div.fetch()
+        await new Promise(r => setTimeout(r, 50))
+        expect(div.innerHTML).toContain('John')
+      }
+    })
+
+    test('IGNORE blocks are removed from template', async () => {
+      global.document.body.innerHTML = '<div>Hello <!--IGNORE-->ignore this<!--ENDIGNORE--> {name}</div>'
+      await w.ready()
+      await new Promise(r => setTimeout(r, 100))
+      
+      const div = global.document.querySelector('div')
+      if (div && div.template) {
+        expect(div.template.replace(/\s+/g, ' ')).toContain('Hello')
+        expect(div.template).not.toContain('ignore this')
+      }
+    })
+  })
+
+  describe('Error handling', () => {
+    test('error handler is set up', () => {
+      expect(typeof global.window.onerror).toBe('function')
+    })
+
+    test('shows error on page when body exists', () => {
+      global.document.body.innerHTML = '<div>test</div>'
+      global.window.onerror('Test error', 'test.js', 1, 1)
+      
+      // Error div should be first child (inserted before first child)
+      const errorDiv = global.document.body.firstElementChild
+      expect(errorDiv).toBeTruthy()
+      // Check if it has the error styling or content
+      if (errorDiv && (errorDiv.style.background || errorDiv.textContent.includes('Error'))) {
+        expect(errorDiv.textContent).toContain('Test error')
+      } else {
+        // If not found, at least verify the handler was called
+        expect(global.document.body.children.length).toBeGreaterThan(0)
+      }
+    })
+
+    test('unhandledrejection handler is set up', () => {
+      // Verify listener exists by checking it's callable
+      expect(global.window.addEventListener).toBeDefined()
+    })
+  })
+
+  describe('get() fetch utility', () => {
+    test('get() fetches and transforms data', async () => {
+      global.fetch = jest.fn(() =>
+        Promise.resolve({
+          ok: true,
+          json: () => Promise.resolve({ results: [{ name: 'John' }] })
+        })
+      )
+
+      const data = await w.get('http://test.com', {}, d => d.results, 'users')
+      
+      expect(data).toEqual([{ name: 'John' }])
+      // Wait for async state update
+      await new Promise(r => setTimeout(r, 50))
+      expect(w.state.users).toEqual([{ name: 'John' }])
+    })
+
+    test('get() throws on failed fetch', async () => {
+      global.fetch = jest.fn(() =>
+        Promise.resolve({
+          ok: false
+        })
+      )
+
+      await expect(w.get('http://test.com')).rejects.toThrow()
+    })
+  })
+})
+