enigmatic 0.27.0 → 0.29.0

package/CLIENT_JS_DOCS.md

@@ -0,0 +1,322 @@
+# client.js Documentation
+
+## Overview
+
+`client.js` is a client-side JavaScript library that provides utilities for DOM manipulation, reactive state management, and API interactions with a backend server. It automatically initializes custom HTML elements and provides a simple API for key-value storage, file operations, and authentication.
+
+## Core Utilities
+
+### DOM Selectors
+
+```javascript
+window.$   // Alias for document.querySelector
+window.$$  // Alias for document.querySelectorAll
+window.$c  // Alias for element.closest (requires $0 context)
+```
+
+**Usage:**
+```javascript
+const element = window.$('#my-id');
+const elements = window.$$('.my-class');
+```
+
+### API Base URL
+
+```javascript
+window.api_url = "https://localhost:3000"
+```
+
+Configures the base URL for all API requests. Modify this to point to your server.
+
+## Reactive State Management
+
+`window.state` is a Proxy object that automatically updates DOM elements when properties change.
+
+**How it works:**
+- Set a property: `window.state.myKey = 'value'`
+- Elements with `data="myKey"` attribute are automatically updated
+- The system looks for custom element handlers in `window.custom[tagName]`
+- Supports both function and object-based custom elements
+
+**Example:**
+```html
+<div data="message">Initial</div>
+<script>
+  window.state.message = "Updated!"; // Automatically updates the div
+</script>
+```
+
+**Custom Element Integration:**
+- If `window.custom[tagName]` is a function: calls `f(value)` and sets `innerHTML`
+- If `window.custom[tagName]` is an object: calls `f.render(value)` and sets `innerHTML`
+
+## API Functions
+
+All API functions are async and return Promises. They use `window.api_url` as the base URL.
+
+### KV Storage Operations
+
+#### `window.get(key)`
+Retrieves a value from the server's key-value store.
+
+```javascript
+const value = await window.get('my-key');
+```
+
+**HTTP Method:** GET  
+**Endpoint:** `{api_url}/{key}`  
+**Returns:** Parsed JSON response
+
+#### `window.set(key, value)`
+Stores a value in the server's key-value store.
+
+```javascript
+await window.set('my-key', 'my-value');
+await window.set('my-key', { json: 'object' });
+```
+
+**HTTP Method:** POST  
+**Endpoint:** `{api_url}/{key}`  
+**Body:** String values sent as-is, objects are JSON stringified  
+**Returns:** Parsed JSON response
+
+#### `window.delete(key)`
+Deletes a key from the server's key-value store.
+
+```javascript
+await window.delete('my-key');
+```
+
+**HTTP Method:** DELETE  
+**Endpoint:** `{api_url}/{key}`  
+**Returns:** Parsed JSON response
+
+### R2 Storage Operations (File Storage)
+
+#### `window.put(key, body)`
+Uploads a file or data to R2 storage.
+
+```javascript
+await window.put('filename.txt', 'file content');
+await window.put('image.png', blob);
+await window.put('data.json', { json: 'data' });
+```
+
+**HTTP Method:** PUT  
+**Endpoint:** `{api_url}/{key}`  
+**Body:** Accepts Blob, string, or JSON-serializable objects  
+**Returns:** Parsed JSON response
+
+#### `window.purge(key)`
+Deletes a file from R2 storage.
+
+```javascript
+await window.purge('filename.txt');
+```
+
+**HTTP Method:** PURGE  
+**Endpoint:** `{api_url}/{key}`  
+**Returns:** Parsed JSON response
+
+#### `window.list()`
+Lists all files in the current user's R2 storage.
+
+```javascript
+const files = await window.list();
+// Returns: [{ name: 'file1.txt', lastModified: '...', size: 123 }, ...]
+```
+
+**HTTP Method:** PROPFIND  
+**Endpoint:** `{api_url}/` (base URL, no key)  
+**Returns:** Array of file objects with `name`, `lastModified`, and `size` properties
+
+#### `window.download(key)`
+Downloads a file from R2 storage and triggers browser download.
+
+```javascript
+await window.download('filename.txt');
+```
+
+**HTTP Method:** PATCH  
+**Endpoint:** `{api_url}/{key}`  
+**Behavior:** 
+- Fetches file as blob
+- Creates temporary download URL
+- Triggers browser download
+- Cleans up temporary URL
+
+**Note:** Uses PATCH method due to browser limitations with custom HTTP methods.
+
+### Authentication
+
+#### `window.login()`
+Redirects to the server's login endpoint.
+
+```javascript
+window.login();
+```
+
+**Behavior:** Sets `window.location.href` to `{api_url}/login`
+
+#### `window.logout()`
+Redirects to the server's logout endpoint.
+
+```javascript
+window.logout();
+```
+
+**Behavior:** Sets `window.location.href` to `{api_url}/logout`
+
+## Custom Elements System
+
+Custom elements are defined in `window.custom` object and automatically initialized when the DOM loads.
+
+### Initialization
+
+The library automatically:
+1. Waits for DOM to be ready (`DOMContentLoaded` or immediate if already loaded)
+2. Iterates through all keys in `window.custom`
+3. Finds all matching HTML elements by tag name
+4. Calls the custom element handler and sets `innerHTML`
+
+### Defining Custom Elements
+
+#### Function-based Custom Element
+
+```javascript
+window.custom = {
+  "my-element": async (data) => {
+    return `<div>Content: ${data}</div>`;
+  }
+};
+```
+
+**HTML Usage:**
+```html
+<my-element></my-element>
+```
+
+When `window.state.myKey = 'value'` is set and an element has `data="myKey"`:
+```html
+<my-element data="myKey"></my-element>
+```
+
+The function receives the state value as the first parameter.
+
+#### Object-based Custom Element
+
+```javascript
+window.custom = {
+  "my-element": {
+    prop: (data) => `Processed: ${data}`,
+    render: function(data) {
+      return `<div>${this.prop(data)}</div>`;
+    }
+  }
+};
+```
+
+**HTML Usage:**
+```html
+<my-element></my-element>
+```
+
+When used with reactive state, the `render` method is called with the state value.
+
+### Example: File Widget
+
+```javascript
+window.custom = {
+  "file-widget": async () => {
+    const list = await window.list();
+    // Returns HTML string with file list and upload button
+    return `<div>...</div>`;
+  }
+};
+```
+
+**HTML Usage:**
+```html
+<file-widget></file-widget>
+```
+
+This custom element:
+- Fetches file list using `window.list()`
+- Renders file items with download and delete buttons
+- Includes an upload button
+- Uses inline event handlers that call `window.download()`, `window.purge()`, and `window.put()`
+
+## Error Handling
+
+All API functions throw errors if the request fails. Use try-catch or `.catch()`:
+
+```javascript
+try {
+  await window.get('nonexistent');
+} catch (err) {
+  console.error('Error:', err);
+}
+
+// Or with promises
+window.get('key').catch(err => console.error(err));
+```
+
+## Complete Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script src="custom.js"></script>
+  <script src="client.js"></script>
+</head>
+<body>
+  <!-- Custom element -->
+  <file-widget></file-widget>
+  
+  <!-- Reactive state element -->
+  <div data="message">Initial</div>
+  
+  <script>
+    // Set reactive state
+    window.state.message = "Hello World";
+    
+    // Use API functions
+    (async () => {
+      await window.set('test', 'value');
+      const value = await window.get('test');
+      console.log(value);
+      
+      // Upload file
+      const fileInput = document.querySelector('input[type="file"]');
+      fileInput.onchange = async (e) => {
+        const file = e.target.files[0];
+        await window.put(file.name, file);
+      };
+      
+      // List files
+      const files = await window.list();
+      console.log(files);
+    })();
+  </script>
+</body>
+</html>
+```
+
+## Dependencies
+
+- Requires `custom.js` to be loaded before `client.js` if using custom elements
+- Requires a backend server that implements the API endpoints
+- Requires browser support for:
+  - `fetch` API
+  - `Proxy` API
+  - `Blob` API
+  - `URL.createObjectURL`
+
+## Notes
+
+- All API functions automatically encode keys using `encodeURIComponent`
+- The `window.download()` function uses PATCH method internally (browsers don't support custom HTTP methods)
+- Custom elements are initialized once on page load; use `location.reload()` to refresh
+- The reactive state system only updates elements with matching `data` attributes
+- Custom element handlers can be async functions

package/__tests__/e2.test.js

@@ -1,10 +1,11 @@
 const fs = require('fs')
 const path = require('path')
 
-// Load e2.js into jsdom
-const e2Code = fs.readFileSync(path.join(__dirname, '../e2.js'), 'utf8')
+// Load client.js and custom.js into jsdom
+const clientCode = fs.readFileSync(path.join(__dirname, '../public/client.js'), 'utf8')
+const customCode = fs.readFileSync(path.join(__dirname, '../public/custom.js'), 'utf8')
 
-describe('e2.js', () => {
+describe('client.js', () => {
   beforeEach(() => {
     // Reset DOM
     global.document.body.innerHTML = ''
@@ -13,80 +14,297 @@ describe('e2.js', () => {
     // Clear window.custom
     global.window.custom = {}
     
-    // Execute e2.js code
-    eval(e2Code)
+    // Execute custom.js first (defines window.custom)
+    eval(customCode)
+    // Execute client.js code
+    eval(clientCode)
   })
 
-  describe('fetchJson', () => {
-    test('fetches JSON with GET method', async () => {
-      const result = await window.fetchJson('GET', 'https://httpbin.org/json')
+  describe('$ and $$ selectors', () => {
+    test('$ selects single element', () => {
+      global.document.body.innerHTML = '<div id="test">Hello</div>'
+      expect(window.$('#test').textContent).toBe('Hello')
+    })
 
-      expect(result.status).toBe(200)
-      expect(result.statusText).toBe('OK')
-      expect(result.data).toBeDefined()
-      expect(typeof result.data).toBe('object')
-      expect(result.headers).toBeDefined()
+    test('$$ selects multiple elements', () => {
+      global.document.body.innerHTML = '<div class="item">1</div><div class="item">2</div>'
+      const items = window.$$('.item')
+      expect(items.length).toBe(2)
+      expect(items[0].textContent).toBe('1')
+      expect(items[1].textContent).toBe('2')
     })
 
-    test('fetches JSON with POST method and body', async () => {
-      const requestBody = { name: 'Test', value: 123 }
-      
-      const result = await window.fetchJson('POST', 'https://httpbin.org/post', {
-        body: JSON.stringify(requestBody)
+    test('$ returns null for non-existent element', () => {
+      global.document.body.innerHTML = '<div>Test</div>'
+      expect(window.$('#nonexistent')).toBeNull()
+    })
+
+    test('$$ returns empty NodeList for non-existent elements', () => {
+      global.document.body.innerHTML = '<div>Test</div>'
+      expect(window.$$('.nonexistent').length).toBe(0)
+    })
+  })
+
+  describe('window API functions', () => {
+    let originalFetch
+    let originalLocation
+
+    beforeEach(() => {
+      originalFetch = global.fetch
+      global.fetch = jest.fn()
+      originalLocation = global.window.location
+      delete global.window.location
+      global.window.location = { href: '' }
+    })
+
+    afterEach(() => {
+      global.fetch = originalFetch
+      global.window.location = originalLocation
+    })
+
+    test('window.get makes GET request with encoded key', async () => {
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ value: 'test' })
       })
 
-      expect(result.status).toBe(200)
-      expect(result.data).toBeDefined()
-      expect(result.data.json).toEqual(requestBody)
+      const result = await window.get('test key')
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        `${window.api_url}/test%20key`
+      )
+      expect(result).toEqual({ value: 'test' })
     })
 
-    test('fetches JSON with PUT method', async () => {
-      const requestBody = { name: 'Updated' }
-      
-      const result = await window.fetchJson('PUT', 'https://httpbin.org/put', {
-        body: JSON.stringify(requestBody)
+    test('window.set makes POST request with string value', async () => {
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ status: 'saved' })
+      })
+
+      const result = await window.set('test', 'value')
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        `${window.api_url}/test`,
+        expect.objectContaining({
+          method: 'POST',
+          body: 'value'
+        })
+      )
+      expect(result).toEqual({ status: 'saved' })
+    })
+
+    test('window.set stringifies object values', async () => {
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ status: 'saved' })
       })
 
-      expect(result.status).toBe(200)
-      expect(result.data).toBeDefined()
-      expect(result.data.json).toEqual(requestBody)
+      await window.set('test', { key: 'value' })
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        `${window.api_url}/test`,
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({ key: 'value' })
+        })
+      )
     })
 
-    test('fetches JSON with DELETE method', async () => {
-      const result = await window.fetchJson('DELETE', 'https://httpbin.org/delete')
+    test('window.delete makes DELETE request', async () => {
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ status: 'deleted' })
+      })
+
+      const result = await window.delete('test')
 
-      expect(result.status).toBe(200)
-      expect(result.data).toBeDefined()
+      expect(global.fetch).toHaveBeenCalledWith(
+        `${window.api_url}/test`,
+        expect.objectContaining({
+          method: 'DELETE'
+        })
+      )
+      expect(result).toEqual({ status: 'deleted' })
     })
 
-    test('includes Content-Type header', async () => {
-      const result = await window.fetchJson('POST', 'https://httpbin.org/post', {
-        body: JSON.stringify({ test: 'data' })
+    test('window.put makes PUT request with string body', async () => {
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ status: 'saved' })
       })
 
-      expect(result.status).toBe(200)
-      expect(result.data.headers['Content-Type']).toBe('application/json')
+      const result = await window.put('test', 'content')
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        `${window.api_url}/test`,
+        expect.objectContaining({
+          method: 'PUT',
+          body: 'content'
+        })
+      )
+      expect(result).toEqual({ status: 'saved' })
     })
 
-    test('includes credentials in request', async () => {
-      const result = await window.fetchJson('GET', 'https://httpbin.org/get')
+    test('window.put stringifies object body', async () => {
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ status: 'saved' })
+      })
+
+      await window.put('test', { data: 'value' })
 
-      expect(result.status).toBe(200)
-      // httpbin doesn't expose credentials, but we verify the request succeeded
-      expect(result.data).toBeDefined()
+      expect(global.fetch).toHaveBeenCalledWith(
+        `${window.api_url}/test`,
+        expect.objectContaining({
+          method: 'PUT',
+          body: JSON.stringify({ data: 'value' })
+        })
+      )
     })
 
-    test('handles error responses', async () => {
-      // httpbin status endpoints return empty body, so fetchJson will throw on JSON parse
-      await expect(
-        window.fetchJson('GET', 'https://httpbin.org/status/404')
-      ).rejects.toThrow()
+    test('window.put handles Blob body', async () => {
+      const blob = new Blob(['test'], { type: 'text/plain' })
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ status: 'saved' })
+      })
+
+      await window.put('test', blob)
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        `${window.api_url}/test`,
+        expect.objectContaining({
+          method: 'PUT',
+          body: blob
+        })
+      )
+    })
+
+    test('window.purge makes PURGE request', async () => {
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ status: 'deleted' })
+      })
+
+      const result = await window.purge('test')
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        `${window.api_url}/test`,
+        expect.objectContaining({
+          method: 'PURGE'
+        })
+      )
+      expect(result).toEqual({ status: 'deleted' })
+    })
+
+    test('window.list makes PROPFIND request to base URL', async () => {
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve([{ name: 'file1' }])
+      })
+
+      const result = await window.list()
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        window.api_url,
+        expect.objectContaining({
+          method: 'PROPFIND'
+        })
+      )
+      expect(result).toEqual([{ name: 'file1' }])
     })
 
-    test('handles network errors', async () => {
-      await expect(
-        window.fetchJson('GET', 'https://invalid-domain-that-does-not-exist-12345.com/api')
-      ).rejects.toThrow()
+    test('window.login redirects to /login', () => {
+      window.login()
+      expect(global.window.location.href).toBe(`${window.api_url}/login`)
+    })
+
+    test('window.logout redirects to /logout', () => {
+      window.logout()
+      expect(global.window.location.href).toBe(`${window.api_url}/logout`)
+    })
+  })
+
+  describe('window.custom components', () => {
+    test('hello-world component is a function', () => {
+      expect(typeof window.custom['hello-world']).toBe('function')
+    })
+
+    test('hello-world component renders correctly', () => {
+      const result = window.custom['hello-world']('Test')
+      expect(result).toBe('Hello Test')
+    })
+
+    test('hello-world-2 component has prop and render methods', () => {
+      expect(window.custom['hello-world-2']).toBeDefined()
+      expect(typeof window.custom['hello-world-2'].prop).toBe('function')
+      expect(typeof window.custom['hello-world-2'].render).toBe('function')
+    })
+
+    test('hello-world-2 component prop works', () => {
+      const result = window.custom['hello-world-2'].prop('Test')
+      expect(result).toBe('Test World')
+    })
+
+    test('hello-world-2 component render works', () => {
+      const result = window.custom['hello-world-2'].render('Test')
+      expect(result).toBe('Test World')
+    })
+  })
+
+
+  describe('window.state proxy', () => {
+    test('state.set updates DOM elements with data attribute', () => {
+      global.document.body.innerHTML = '<hello-world data="name"></hello-world>'
+      
+      window.state.name = 'John'
+      
+      const el = global.document.querySelector('hello-world')
+      expect(el.innerHTML).toBe('Hello John')
+    })
+
+    test('state.set updates multiple elements with same data attribute', () => {
+      global.document.body.innerHTML = '<hello-world data="name"></hello-world><hello-world data="name"></hello-world>'
+      
+      window.state.name = 'Jane'
+      
+      const els = global.document.querySelectorAll('hello-world')
+      expect(els[0].innerHTML).toBe('Hello Jane')
+      expect(els[1].innerHTML).toBe('Hello Jane')
+    })
+
+    test('state.set works with object components', () => {
+      global.document.body.innerHTML = '<hello-world-2 data="test"></hello-world-2>'
+      
+      window.state.test = 'Hello'
+      
+      const el = global.document.querySelector('hello-world-2')
+      expect(el.innerHTML).toBe('Hello World')
+    })
+
+    test('state.set stores value in proxy object', () => {
+      window.state.test = 'value'
+      expect(window.state.test).toBe('value')
+    })
+
+    test('state.set handles multiple properties', () => {
+      global.document.body.innerHTML = '<hello-world data="a"></hello-world><hello-world data="b"></hello-world>'
+      
+      window.state.a = 'A'
+      window.state.b = 'B'
+      
+      expect(global.document.querySelector('[data="a"]').innerHTML).toBe('Hello A')
+      expect(global.document.querySelector('[data="b"]').innerHTML).toBe('Hello B')
+    })
+
+    test('state.set does not update elements without matching data attribute', () => {
+      global.document.body.innerHTML = '<hello-world data="name"></hello-world><div data="other">Original</div>'
+      
+      window.state.name = 'John'
+      
+      expect(global.document.querySelector('[data="name"]').innerHTML).toBe('Hello John')
+      expect(global.document.querySelector('[data="other"]').innerHTML).toBe('Original')
     })
   })
 })

package/__tests__/jest.config.js

@@ -0,0 +1,7 @@
+module.exports = {
+  testEnvironment: 'jsdom',
+  testMatch: ['**/__tests__/**/*.test.js'],
+  setupFilesAfterEnv: ['<rootDir>/__tests__/jest.setup.js'],
+  testTimeout: 10000,
+  rootDir: require('path').resolve(__dirname, '..')
+}

package/{jest.setup.js → __tests__/jest.setup.js}

@@ -7,4 +7,3 @@ if (typeof window !== 'undefined' && !window.components) {
 if (typeof global.fetch === 'undefined') {
   global.fetch = require('whatwg-fetch').fetch
 }
-