pulse-js-framework 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Pulse Framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# Pulse Framework
+
+A declarative DOM framework with CSS selector-based structure and reactive pulsations.
+
+## Features
+
+- **CSS Selector Syntax** - Create DOM elements using familiar CSS selectors
+- **Reactive Pulsations** - Automatic UI updates when state changes
+- **Custom DSL** - Optional `.pulse` file format for cleaner code
+- **No Build Required** - Works directly in the browser
+- **Lightweight** - Minimal footprint, maximum performance
+- **Router & Store** - Built-in SPA routing and state management
+
+## Installation
+
+```bash
+npm install pulse-js-framework
+```
+
+## Quick Start
+
+### Create a new project
+
+```bash
+npx pulse create my-app
+cd my-app
+npm install
+npm run dev
+```
+
+### Or use directly
+
+```javascript
+import { pulse, effect, el, mount } from 'pulse-js-framework';
+
+// Create reactive state
+const count = pulse(0);
+
+// Build UI with CSS selector syntax
+function Counter() {
+  const div = el('.counter');
+
+  const display = el('h1');
+  effect(() => {
+    display.textContent = `Count: ${count.get()}`;
+  });
+
+  const increment = el('button.btn', '+');
+  increment.onclick = () => count.update(n => n + 1);
+
+  const decrement = el('button.btn', '-');
+  decrement.onclick = () => count.update(n => n - 1);
+
+  div.append(display, increment, decrement);
+  return div;
+}
+
+mount('#app', Counter());
+```
+
+## CSS Selector Syntax
+
+Create DOM elements using familiar CSS syntax:
+
+```javascript
+el('div')                    // <div></div>
+el('.container')             // <div class="container"></div>
+el('#app')                   // <div id="app"></div>
+el('button.btn.primary')     // <button class="btn primary"></button>
+el('input[type=text]')       // <input type="text">
+el('h1', 'Hello World')      // <h1>Hello World</h1>
+```
+
+## Reactivity
+
+```javascript
+import { pulse, effect, computed } from 'pulse-js-framework';
+
+// Create reactive values
+const firstName = pulse('John');
+const lastName = pulse('Doe');
+
+// Computed values
+const fullName = computed(() =>
+  `${firstName.get()} ${lastName.get()}`
+);
+
+// Effects auto-run when dependencies change
+effect(() => {
+  console.log(`Hello, ${fullName.get()}!`);
+});
+
+firstName.set('Jane'); // Logs: "Hello, Jane Doe!"
+```
+
+## .pulse File Format
+
+```pulse
+@page Counter
+
+state {
+  count: 0
+}
+
+view {
+  .counter {
+    h1 "Count: {count}"
+    button @click(count++) "+"
+    button @click(count--) "-"
+  }
+}
+
+style {
+  .counter {
+    text-align: center
+    padding: 20px
+  }
+}
+```
+
+## API Reference
+
+### Reactivity
+
+- `pulse(value)` - Create a reactive value
+- `pulse.get()` - Read value (tracks dependency)
+- `pulse.set(value)` - Set new value
+- `pulse.update(fn)` - Update with function
+- `pulse.peek()` - Read without tracking
+- `effect(fn)` - Create reactive side effect
+- `computed(fn)` - Create derived value
+- `batch(fn)` - Batch multiple updates
+
+### DOM
+
+- `el(selector, ...children)` - Create element
+- `mount(target, element)` - Mount to DOM
+- `text(fn)` - Reactive text node
+- `list(items, template)` - Reactive list
+- `when(condition, then, else)` - Conditional render
+
+### Router
+
+```javascript
+import { createRouter } from 'pulse-js-framework/runtime/router.js';
+
+const router = createRouter({
+  routes: {
+    '/': HomePage,
+    '/about': AboutPage,
+    '/users/:id': UserPage
+  }
+});
+
+router.start();
+```
+
+### Store
+
+```javascript
+import { createStore } from 'pulse-js-framework/runtime/store.js';
+
+const store = createStore({
+  user: null,
+  theme: 'light'
+}, { persist: true });
+
+store.user.set({ name: 'John' });
+```
+
+## CLI Commands
+
+```bash
+pulse create <name>    # Create new project
+pulse dev [port]       # Start dev server
+pulse build            # Build for production
+pulse compile <file>   # Compile .pulse file
+```
+
+## License
+
+MIT

package/cli/build.js

@@ -0,0 +1,199 @@
+/**
+ * Pulse Build System
+ *
+ * Builds Pulse projects for production
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, copyFileSync } from 'fs';
+import { join, extname, relative, dirname } from 'path';
+import { compile } from '../compiler/index.js';
+
+/**
+ * Build project for production
+ */
+export async function buildProject(args) {
+  const root = process.cwd();
+  const outDir = join(root, 'dist');
+
+  // Check if vite is available
+  try {
+    const viteConfig = join(root, 'vite.config.js');
+    if (existsSync(viteConfig)) {
+      console.log('Vite config detected, using Vite build...');
+      const { build } = await import('vite');
+      await build({ root });
+      return;
+    }
+  } catch (e) {
+    // Vite not available, use built-in build
+  }
+
+  console.log('Building with Pulse compiler...');
+
+  // Create output directory
+  if (!existsSync(outDir)) {
+    mkdirSync(outDir, { recursive: true });
+  }
+
+  // Copy public files
+  const publicDir = join(root, 'public');
+  if (existsSync(publicDir)) {
+    copyDir(publicDir, outDir);
+  }
+
+  // Process source files
+  const srcDir = join(root, 'src');
+  if (existsSync(srcDir)) {
+    processDirectory(srcDir, join(outDir, 'assets'));
+  }
+
+  // Copy and process index.html
+  const indexHtml = join(root, 'index.html');
+  if (existsSync(indexHtml)) {
+    let html = readFileSync(indexHtml, 'utf-8');
+
+    // Update script paths for production
+    html = html.replace(
+      /src="\/src\/([^"]+)"/g,
+      'src="/assets/$1"'
+    );
+
+    // Rewrite .pulse imports to .js
+    html = html.replace(/\.pulse"/g, '.js"');
+
+    writeFileSync(join(outDir, 'index.html'), html);
+  }
+
+  // Bundle runtime
+  bundleRuntime(outDir);
+
+  console.log(`
+Build complete!
+
+Output directory: ${relative(root, outDir)}
+
+To preview the build:
+  npx serve dist
+  `);
+}
+
+/**
+ * Process a directory of source files
+ */
+function processDirectory(srcDir, outDir) {
+  if (!existsSync(outDir)) {
+    mkdirSync(outDir, { recursive: true });
+  }
+
+  const files = readdirSync(srcDir);
+
+  for (const file of files) {
+    const srcPath = join(srcDir, file);
+    const stat = statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      processDirectory(srcPath, join(outDir, file));
+    } else if (file.endsWith('.pulse')) {
+      // Compile .pulse files
+      const source = readFileSync(srcPath, 'utf-8');
+      const result = compile(source, {
+        runtime: './runtime.js',
+        minify: true
+      });
+
+      if (result.success) {
+        const outPath = join(outDir, file.replace('.pulse', '.js'));
+        writeFileSync(outPath, result.code);
+        console.log(`  Compiled: ${file}`);
+      } else {
+        console.error(`  Error compiling ${file}:`);
+        for (const error of result.errors) {
+          console.error(`    ${error.message}`);
+        }
+      }
+    } else if (file.endsWith('.js') || file.endsWith('.mjs')) {
+      // Process JS files - rewrite imports
+      let content = readFileSync(srcPath, 'utf-8');
+
+      // Rewrite .pulse imports to .js
+      content = content.replace(/from\s+['"]([^'"]+)\.pulse['"]/g, "from '$1.js'");
+
+      // Rewrite runtime imports
+      content = content.replace(
+        /from\s+['"]pulse-framework\/runtime['"]/g,
+        "from './runtime.js'"
+      );
+
+      const outPath = join(outDir, file);
+      writeFileSync(outPath, content);
+      console.log(`  Processed: ${file}`);
+    } else {
+      // Copy other files
+      const outPath = join(outDir, file);
+      copyFileSync(srcPath, outPath);
+    }
+  }
+}
+
+/**
+ * Bundle the runtime into a single file
+ */
+function bundleRuntime(outDir) {
+  // For simplicity, we'll create a minimal runtime bundle
+  // In production, you'd want to use a proper bundler
+
+  const runtimeCode = `
+// Pulse Runtime (bundled)
+${readRuntimeFile('pulse.js')}
+${readRuntimeFile('dom.js')}
+${readRuntimeFile('router.js')}
+${readRuntimeFile('store.js')}
+`;
+
+  writeFileSync(join(outDir, 'assets', 'runtime.js'), runtimeCode);
+  console.log('  Bundled: runtime.js');
+}
+
+/**
+ * Read a runtime file
+ */
+function readRuntimeFile(filename) {
+  const paths = [
+    join(process.cwd(), 'node_modules', 'pulse-framework', 'runtime', filename),
+    join(dirname(new URL(import.meta.url).pathname), '..', 'runtime', filename)
+  ];
+
+  for (const path of paths) {
+    if (existsSync(path)) {
+      return readFileSync(path, 'utf-8');
+    }
+  }
+
+  console.warn(`  Warning: Could not find runtime file: ${filename}`);
+  return '';
+}
+
+/**
+ * Copy a directory recursively
+ */
+function copyDir(src, dest) {
+  if (!existsSync(dest)) {
+    mkdirSync(dest, { recursive: true });
+  }
+
+  const files = readdirSync(src);
+
+  for (const file of files) {
+    const srcPath = join(src, file);
+    const destPath = join(dest, file);
+    const stat = statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+export default { buildProject };

package/cli/dev.js

@@ -0,0 +1,225 @@
+/**
+ * Pulse Development Server
+ *
+ * A simple development server with hot module replacement
+ */
+
+import { createServer } from 'http';
+import { readFileSync, existsSync, statSync, watch } from 'fs';
+import { join, extname, resolve } from 'path';
+import { compile } from '../compiler/index.js';
+
+const MIME_TYPES = {
+  '.html': 'text/html',
+  '.js': 'application/javascript',
+  '.mjs': 'application/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2'
+};
+
+// Connected clients for HMR
+const clients = new Set();
+
+/**
+ * Start the development server
+ */
+export async function startDevServer(args) {
+  const port = parseInt(args[0]) || 3000;
+  const root = process.cwd();
+
+  // Check if vite is available, use it if so
+  try {
+    const viteConfig = join(root, 'vite.config.js');
+    if (existsSync(viteConfig)) {
+      console.log('Vite config detected, using Vite...');
+      const { createServer: createViteServer } = await import('vite');
+      const server = await createViteServer({
+        root,
+        server: { port }
+      });
+      await server.listen();
+      server.printUrls();
+      return;
+    }
+  } catch (e) {
+    // Vite not available, use built-in server
+  }
+
+  // Built-in development server
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url, `http://localhost:${port}`);
+    let pathname = url.pathname;
+
+    // Handle HMR WebSocket upgrade
+    if (pathname === '/__pulse_hmr') {
+      // This would need WebSocket support
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    // Serve index.html for root
+    if (pathname === '/') {
+      pathname = '/index.html';
+    }
+
+    // Try to serve the file
+    let filePath = join(root, pathname);
+
+    // Check for .pulse files and compile them
+    if (pathname.endsWith('.pulse')) {
+      if (existsSync(filePath)) {
+        try {
+          const source = readFileSync(filePath, 'utf-8');
+          const result = compile(source, {
+            runtime: '/node_modules/pulse-framework/runtime/index.js'
+          });
+
+          if (result.success) {
+            res.writeHead(200, { 'Content-Type': 'application/javascript' });
+            res.end(result.code);
+          } else {
+            res.writeHead(500, { 'Content-Type': 'text/plain' });
+            res.end(`Compilation error: ${result.errors.map(e => e.message).join('\n')}`);
+          }
+        } catch (error) {
+          res.writeHead(500, { 'Content-Type': 'text/plain' });
+          res.end(`Error: ${error.message}`);
+        }
+        return;
+      }
+    }
+
+    // Serve JS files
+    if (pathname.endsWith('.js') || pathname.endsWith('.mjs')) {
+      if (existsSync(filePath)) {
+        const content = readFileSync(filePath, 'utf-8');
+        res.writeHead(200, { 'Content-Type': 'application/javascript' });
+        res.end(content);
+        return;
+      }
+    }
+
+    // Handle node_modules
+    if (pathname.startsWith('/node_modules/pulse-framework/')) {
+      const modulePath = join(root, '..', 'pulse', pathname.replace('/node_modules/pulse-framework/', ''));
+      if (existsSync(modulePath)) {
+        const content = readFileSync(modulePath, 'utf-8');
+        res.writeHead(200, { 'Content-Type': 'application/javascript' });
+        res.end(content);
+        return;
+      }
+    }
+
+    // Handle runtime path (for examples)
+    if (pathname.includes('/runtime/')) {
+      const runtimeFile = pathname.split('/runtime/')[1] || 'index.js';
+
+      // Try multiple possible locations
+      const possiblePaths = [
+        join(root, '..', 'runtime', runtimeFile),      // pulse/example/ -> pulse/runtime/
+        join(root, '..', '..', 'runtime', runtimeFile), // pulse/examples/*/ -> pulse/runtime/
+        join(root, 'runtime', runtimeFile),             // pulse/docs/ -> pulse/docs/runtime/ (fallback)
+      ];
+
+      for (const runtimePath of possiblePaths) {
+        if (existsSync(runtimePath)) {
+          const content = readFileSync(runtimePath, 'utf-8');
+          res.writeHead(200, { 'Content-Type': 'application/javascript' });
+          res.end(content);
+          return;
+        }
+      }
+    }
+
+    // Serve static files
+    if (existsSync(filePath) && statSync(filePath).isFile()) {
+      const ext = extname(filePath);
+      const mimeType = MIME_TYPES[ext] || 'application/octet-stream';
+
+      res.writeHead(200, { 'Content-Type': mimeType });
+      res.end(readFileSync(filePath));
+      return;
+    }
+
+    // 404
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('Not Found');
+  });
+
+  // Watch for file changes
+  watchFiles(root);
+
+  server.listen(port, () => {
+    console.log(`
+  Pulse Dev Server running at:
+
+    Local:   http://localhost:${port}/
+
+  Press Ctrl+C to stop.
+    `);
+  });
+}
+
+/**
+ * Watch files for changes
+ */
+function watchFiles(root) {
+  const srcDir = join(root, 'src');
+
+  if (existsSync(srcDir)) {
+    watch(srcDir, { recursive: true }, (eventType, filename) => {
+      if (filename && filename.endsWith('.pulse')) {
+        console.log(`File changed: ${filename}`);
+        // Notify HMR clients (simplified)
+        notifyClients({ type: 'update', path: `/src/${filename}` });
+      }
+    });
+  }
+}
+
+/**
+ * Notify connected HMR clients
+ */
+function notifyClients(message) {
+  for (const client of clients) {
+    try {
+      client.send(JSON.stringify(message));
+    } catch (e) {
+      clients.delete(client);
+    }
+  }
+}
+
+/**
+ * Get HMR client code
+ */
+function getHMRClient() {
+  return `
+(function() {
+  const ws = new WebSocket('ws://' + location.host + '/__pulse_hmr');
+
+  ws.onmessage = function(event) {
+    const data = JSON.parse(event.data);
+    if (data.type === 'update') {
+      console.log('[Pulse HMR] Update:', data.path);
+      location.reload();
+    }
+  };
+
+  ws.onclose = function() {
+    console.log('[Pulse HMR] Connection lost, reconnecting...');
+    setTimeout(() => location.reload(), 1000);
+  };
+})();
+`;
+}
+
+export default { startDevServer };