juxscript 1.0.0

package/README.md

@@ -0,0 +1,292 @@
+# *JUX* Authoring UI's in pure javascript.
+
+> Build beautiful, reactive UI's using only javascript. **No markup required.**
+> A clean authorship layer capable of being taught to non-developers, strong enough to be used by real developers.
+
+>> **jux** challenges the idea that markup based systems are the most efficient way to author web applications.
+## AI friendly - **use less tokens!**
+
+
+```diff
+- Markup is expensive! 
+Have you ever considered the energy requirements to ship chunks of HTML markup like Vue or React components?
+```
+
+- [ ] Build a code calculator (token calculator)
+> As a user, I want to be efficient with the LLM's. I want my code to be clean. I want to avoid repeating myself. I ultimately, want to write less code. Less code is better code.
+
+## Ecosystem friendly (NPM)
+
+> Because it is just javascript, .jux files work with any npm package you want to throw at it with standard ESM syntax.
+
+## GETTING STARTED
+
+
+> install
+`npm i juxscript`
+
+>> Your IDE must be setup to read .jux files as .js files. In VS Code, this is do in the `.vscode/settings.json`. Here is an example.
+
+```json
+//.vscode/settings.json
+{
+  "files.associations": {
+    "*.jux": "javascript",
+    "*.juxt": "javascript"
+  },
+  "javascript.validate.enable": false,
+  "[javascript]": {
+    "editor.defaultFormatter": "vscode.typescript-language-features"
+  }
+}
+```
+
+> building and serving the `examples` project directory.
+`npm run dev` 
+
+> building only (the `examples` project directory)
+`npm run build:examples`
+
+# GOAL: Eliminating the Markup System of building UI's.
+> HTML markup is the equivalent of still writing in `C` ro `C++` despite the availability of more functional levels of abstraction like `python`.
+> To remove the requirement for markup, **jux** must address the utility of markup.
+
+## Layouts
+
+### Grid System
+- [ ] Laying out JUX files in a rational way.
+> Develop a higher-level layout javascript grammar for building layouts and palettes of style using *ZERO markup*.
+
+- [ ] A Partial View Strategy
+>>> As a dev I may need to load partial pages/components into other pages. This should avoid noisy wrappers and ideally be just javascript imports of jux objects.
+
+### Components
+
+We have constructed the most helpful components for building 99% of core business/saas web applications, that present beautifully on the page and are created purely with javascript.
+> https://www.shadcn-vue.com/docs/components
+> Run time slots.. Example, `table.slot(columnName -> object);`
+
+# Backend
+
+### Routing & Views
+- [X] Subviews architecture
+  - [X] Nested routing support
+  - [X] View composition
+  - [X] Layout system
+- [X] User views
+  - [X] `profile.jux` - User 
+
+### Server Docs/Documentation. 
+
+- [ ] Should *jux* ship with a server at all? Or merely for demos.
+
+> What is the server even doing? Is it merely a matter of understanding that JUX builder/compilation gives you a mirror of how you setup your project. It can be as flat or deep as you would like.
+
+> *At this point*, we are speaking almost 100% towards UI interfaces. 
+> Servers should be 'loosely coupled.'. This allows for a standard. 
+>>> In the future, we could introduce an *auto api* feature, similar to *next.js* api heuristic for folders and files. 
+---
+
+
+[ **@jesseallenrxtrail -> Discuss.** ]
+
+### Chore: Commit to building more in package directory. 
+
+> We can experiment with our example project, using a simple `express` server, running. What third-party integration do we need? 
+- [ ] Chore: Cleanup our `machinery/server.js` to separate concerns and build our actual endpoints we need to build software here. 
+
+#### Alternative Chore: package this for `npmjs.org`, combine with our existing project, re-author frontend in *jux*.
+
+- [ ] Alternative Chore: package this for `npmjs.org` and ship it. 
+- [ ] Start a brand new project. 
+- [ ] Build the server aspect in `flask` (already done). 
+- [ ] Author the frontend in **jux** instead of **vue**.
+
+> This may require us to move our 'complilation error module', `lib/components/error-handler.ts` to the front-end for display without a 'server call' at all?
+- [ ] Chore for this? This takes more analysis, discussion.
+
+> How and what will we wire for backend and what **jux** components will we support for working with backends.
+- [ X ] SQL Database (query component) 
+  - [ ] Chore: This is currently supported. Needs revisiting and testing
+> API's 
+- [ ] Base payload creater and consumer as a **jux** component. *jux.api*??
+
+---
+
+# Jux Configs
+
+> Jux configs.. `jux.config.js` what should this entail?
+Currently it looks like this: 
+- [ ] Chore: **WHAT IS ACTUALLY BEING USED AND WHERE?**
+
+```javascript
+export default {
+  projectRoot: __dirname,
+  distDir: path.join(__dirname, 'dist'),
+  build: {
+    minify: false
+  },
+  
+  database: {
+    // Default connection
+    default: 'sqlite',
+    
+    // Named connections
+    connections: {
+      sqlite: {
+        driver: 'sqlite',
+        database: path.join(__dirname, 'db', 'jux.db')
+      },
+      ... // props to feed drivers for mysql/postgres
+    }
+  },
+  
+  server: {
+    port: process.env.PORT || 3000,
+    host: process.env.HOST || 'localhost'
+  },
+  
+};
+```  
+**As a user, I will want to control where JUX sends queries.**
+**As a user, I may want to specify a default proxy for backend. I may also want to specify, explicitly, URL's to hit other service endpoints**
+- [ ] Escape hatch (backend API proxy vs default)
+    - [ ] As a user, I may want to run my own server for backend requests/proxies.
+    - [ ] As a user, I may want to hit multiple endpoints in the same JUX file.
+
+--- 
+
+# CORE 
+
+### STATIC SERVING (your local file system, s3 bucket static sites, any host that allows serving etc...)
+**Should JUX function, as a 100% client side app (STATIC WEBSITES)**
+- [ ] Chore: Discovery... I think the answer is yes. I think what might be missing is bundling.
+![alt text](local.png)
+
+---
+## REACTIVITY LAYER.
+### Goal for Reactivity
+> We are shooting for better than nasty amounts of javascript, not as sophisticated as vue/react.
+
+> As a user, I want changes in state of my objects to be consumable by other objects on the page so they can paint changes and interface with each other seamlessly.
+- [ ] Build a basic `v-model` strategy in pure javascript. Different than jquery, javascript etc.
+- [ ] Build standard eventing systems, listeners and emitters on components where they make sense.
+`
+# ROADMAP
+
+### KEY UI PAGES
+- [ ] JWT Authentication (`authJWT`) (demo `examples` only)
+  - [ ] Token generation  (demo `examples` only)
+  - [ ] Token validation middleware  (demo `examples` only)
+  - [ ] Refresh token logic  (demo `examples` only)
+- [ ] *Login system PAGES! Ships with `vendor` assets like lib files/layouts etc.*
+  - [ ] Login
+  - [ ] Logout
+  - [ ] Profile
+
+
+### Additional Features
+- [ ] API documentation
+- [ ] Testing setup
+
+
+
+
+
+### LAYOUT NOTES...
+# Jux Standard Layout Regions
+
+- [ ] CHORE : REVISIT! I think maybe we ship with our figma, notion, default etc. But then document how to build and reuse a .jux page as a layout using the `jux.layout` class.
+
+## The Opinionated Structure
+
+**jux** layout pages provide a **strongly opinionated** layout structure that covers 99% of web applications. Every page includes these regions by default, even if not all are used. This eliminates layout decisions and provides consistent target containers across your entire application.
+
+These are free to use, but you can roll your own just as easily. 
+You can find the documentation for each of these layouts here:
+
+- Notion
+- Jux
+- Figma
+- Other?
+
+
+### Sample Documenation
+```markdown
+#app
+├── #appheader // Top navigation bar - your app's primary navigation
+│ ├── #appheader-logo // Brand identity - logo, app name
+│ ├── #appheader-nav // Primary navigation menu
+│ └── #appheader-actions // User actions - profile, notifications, settings
+│
+├── #appsubheader // Contextual navigation - changes based on current page
+│ ├── #appsubheader-breadcrumbs // Where am I? - navigation path
+│ ├── #appsubheader-tabs // Page-level tabs - views within the same context
+│ └── #appsubheader-actions // Context-specific actions - filters, search, "New Item"
+│
+├── #appsidebar // Left sidebar - persistent navigation or filters
+│ ├── #appsidebar-header // Sidebar title or search
+│ ├── #appsidebar-content // Main sidebar content - nav tree, filters
+│ └── #appsidebar-footer // Sidebar actions or status
+│
+├── #appmain // Your content lives here - the star of the show
+│
+├── #appaside // Right sidebar - contextual help, metadata
+│ ├── #appaside-header // Aside title
+│ ├── #appaside-content // Properties panel, help docs, related items
+│ └── #appaside-footer // Aside actions
+│
+├── #appfooter // Bottom of the page
+│ ├── #appfooter-content // Footer navigation, social links
+│ └── #appfooter-legal // Copyright, terms, privacy
+│
+└── #appmodal // Overlays and dialogs
+├── #appmodal-backdrop // Click-to-close background
+└── #appmodal-container
+├── #appmodal-header // Dialog title and close button
+├── #appmodal-content // Dialog body
+└── #appmodal-footer // Dialog actions - Cancel, Save, etc.
+
+```
+
+## Why consider a Jux layout?
+
+**Predictability**: Every page has the same structure. Developers know exactly where to render components.
+
+**Flexibility**: Don't need a sidebar? Leave it empty. CSS handles visibility automatically.
+
+**Composability**: Components can render to any region with `.render('#target-id')`.
+
+**Convention over Configuration**: No layout decisions needed. Just start building.
+
+## Common Patterns
+
+```javascript
+// Dashboard with sidebar navigation
+const sideNav = jux.nav('side-nav', { /* config */ });
+await sideNav.render('#appsidebar-content');
+
+const dashboard = jux.dashboard('main-dashboard', { /* config */ });
+await dashboard.render('#appmain');
+
+// Settings page with tabs
+const tabs = jux.tabs('settings-tabs', { /* config */ });
+await tabs.render('#appsubheader-tabs');
+
+const content = jux.container('settings-content', { /* config */ });
+await content.render('#appmain');
+
+// Detail view with metadata sidebar
+const detail = jux.detail('item-detail', { /* config */ });
+await detail.render('#appmain');
+
+const metadata = jux.metadata('item-meta', { /* config */ });
+await metadata.render('#appaside-content');
+
+// Modal dialog
+const dialog = jux.dialog('confirm-dialog', { /* config */ });
+await dialog.render('#appmodal-content');
+
+// Auto-render to default container (component chooses based on type)
+const hero = jux.hero('page-hero', { /* config */ });
+await hero.render(); // Automatically renders to #appmain

package/bin/cli.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+import { compileJuxFile, copyLibToOutput, copyProjectAssets } from '../machinery/compiler.js';
+import { generateDocs } from '../machinery/doc-generator.js';
+import { start } from '../machinery/server.js';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const command = process.argv[2];
+const projectRoot = process.cwd();
+const distDir = path.join(projectRoot, 'dist');
+
+function findJuxFiles(dir, fileList = []) {
+  const files = fs.readdirSync(dir);
+  
+  files.forEach(file => {
+    const filePath = path.join(dir, file);
+    const stat = fs.statSync(filePath);
+    
+    if (stat.isDirectory()) {
+      if (file !== 'node_modules' && file !== 'dist' && file !== '.git') {
+        findJuxFiles(filePath, fileList);
+      }
+    } else if (file.endsWith('.jux')) {
+      fileList.push(filePath);
+    }
+  });
+  
+  return fileList;
+}
+
+async function loadConfig() {
+  const configPath = path.join(projectRoot, 'jux.config.js');
+  
+  if (fs.existsSync(configPath)) {
+    try {
+      const configModule = await import(configPath);
+      return configModule.default || {};
+    } catch (err) {
+      console.warn('⚠️  Could not load jux.config.js:', err.message);
+      return {};
+    }
+  }
+  
+  return {};
+}
+
+async function buildProject(isServe = false) {
+  console.log('🔨 Building JUX project...\n');
+  
+  try {
+    if (fs.existsSync(distDir)) {
+      fs.rmSync(distDir, { recursive: true, force: true });
+    }
+    fs.mkdirSync(distDir, { recursive: true });
+
+    // Step 1: Generate documentation FIRST
+    console.log('📚 Generating documentation...');
+    try {
+      await generateDocs(projectRoot);
+      console.log('✅ Documentation generated\n');
+    } catch (error) {
+      console.warn('⚠️  Failed to generate docs:', error.message);
+    }
+
+    // Step 2: Copy lib/ to dist/lib/ (includes docs-data.json)
+    await copyLibToOutput(projectRoot, distDir);
+    
+    // Step 3: Copy project assets (CSS, JS) from project root
+    await copyProjectAssets(projectRoot, distDir);
+
+    // Step 4: Find and compile project .jux files
+    const projectJuxFiles = findJuxFiles(projectRoot);
+    console.log(`Found ${projectJuxFiles.length} project .jux file(s)\n`);
+
+    for (const file of projectJuxFiles) {
+      try {
+        await compileJuxFile(file, { distDir, projectRoot, isServe });
+      } catch (err) {
+        console.error(`Error compiling ${file}:`, err.message);
+      }
+    }
+
+    // Step 5: Find and compile vendor layout .jux files
+    const libRoot = path.resolve(projectRoot, '../lib');
+    const layoutsDir = path.join(libRoot, 'layouts');
+    
+    if (fs.existsSync(layoutsDir)) {
+      console.log('\n📐 Compiling vendor layouts...');
+      const vendorJuxFiles = findJuxFiles(layoutsDir);
+      console.log(`Found ${vendorJuxFiles.length} vendor layout(s)\n`);
+      
+      for (const file of vendorJuxFiles) {
+        try {
+          const relPath = path.relative(libRoot, file);
+          
+          await compileJuxFile(file, { 
+            distDir: path.join(distDir, 'lib'),
+            projectRoot: libRoot, 
+            isServe 
+          });
+          
+          console.log(`  ✓ Compiled: ${relPath}`);
+        } catch (err) {
+          console.error(`Error compiling vendor layout ${file}:`, err.message);
+        }
+      }
+    }
+
+    console.log(`\n✅ Built ${projectJuxFiles.length} project file(s) + layouts\n`);
+  } catch (err) {
+    console.error('❌ Build error:', err.message);
+    process.exit(1);
+  }
+}
+
+(async () => {
+  if (command === 'build') {
+    await buildProject(false);
+    console.log(`✅ Build complete: ${distDir}`);
+    
+  } else if (command === 'serve') {
+    // Build first
+    await buildProject(true); // isServe = true
+    
+    // Start server with watcher
+    const config = await loadConfig();
+    await start(3000, config);
+    
+  } else {
+    console.log(`
+JUX CLI - A JavaScript UX authorship platform
+
+Usage:
+  npx jux build              Compile all .jux files to HTML/CSS/JS
+  npx jux serve [port]       Start dev server with hot reload (default: 3000)
+                             Builds automatically if dist/ doesn't exist
+
+Examples:
+  npx jux build              Build for production
+  npx jux serve              Start dev server (builds if needed)
+  npx jux serve 8080         Start on port 8080
+    `);
+  }
+})();

package/lib/adapters/base-adapter.js

@@ -0,0 +1,35 @@
+/**
+ * Base adapter interface that all database adapters must implement
+ */
+class BaseAdapter {
+  constructor(config) {
+    this.config = config;
+    this.connection = null;
+  }
+
+  async connect() {
+    throw new Error('connect() must be implemented');
+  }
+
+  async disconnect() {
+    throw new Error('disconnect() must be implemented');
+  }
+
+  async query(sql, params = []) {
+    throw new Error('query() must be implemented');
+  }
+
+  async execute(sql, params = []) {
+    throw new Error('execute() must be implemented');
+  }
+
+  async transaction(callback) {
+    throw new Error('transaction() must be implemented');
+  }
+
+  escape(value) {
+    throw new Error('escape() must be implemented');
+  }
+}
+
+module.exports = { BaseAdapter };

package/lib/adapters/index.js

@@ -0,0 +1,33 @@
+const { SQLiteAdapter } = require('./sqlite-adapter');
+const { MySQLAdapter } = require('./mysql-adapter');
+const { PostgresAdapter } = require('./postgres-adapter');
+
+/**
+ * Adapter factory - creates the appropriate adapter based on config
+ */
+function createAdapter(type, config) {
+  switch (type.toLowerCase()) {
+    case 'sqlite':
+    case 'sqlite3':
+      return new SQLiteAdapter(config);
+    
+    case 'mysql':
+    case 'mariadb':
+      return new MySQLAdapter(config);
+    
+    case 'postgres':
+    case 'postgresql':
+    case 'pg':
+      return new PostgresAdapter(config);
+    
+    default:
+      throw new Error(`Unsupported database type: ${type}`);
+  }
+}
+
+module.exports = {
+  createAdapter,
+  SQLiteAdapter,
+  MySQLAdapter,
+  PostgresAdapter
+};

package/lib/adapters/mysql-adapter.js

@@ -0,0 +1,65 @@
+const { BaseAdapter } = require('./base-adapter');
+const mysql = require('mysql2/promise');
+
+class MySQLAdapter extends BaseAdapter {
+  async connect() {
+    this.connection = await mysql.createConnection({
+      host: this.config.host || 'localhost',
+      port: this.config.port || 3306,
+      user: this.config.user,
+      password: this.config.password,
+      database: this.config.database
+    });
+    return this.connection;
+  }
+
+  async disconnect() {
+    if (this.connection) {
+      await this.connection.end();
+      this.connection = null;
+    }
+  }
+
+  async query(sql, params = []) {
+    if (!this.connection) await this.connect();
+    
+    try {
+      const [rows] = await this.connection.execute(sql, params);
+      return { data: rows, rowCount: rows.length };
+    } catch (error) {
+      throw new Error(`MySQL query error: ${error.message}`);
+    }
+  }
+
+  async execute(sql, params = []) {
+    if (!this.connection) await this.connect();
+    
+    try {
+      const [result] = await this.connection.execute(sql, params);
+      return { 
+        rowCount: result.affectedRows,
+        lastInsertId: result.insertId 
+      };
+    } catch (error) {
+      throw new Error(`MySQL execute error: ${error.message}`);
+    }
+  }
+
+  async transaction(callback) {
+    await this.connection.beginTransaction();
+    try {
+      const result = await callback(this);
+      await this.connection.commit();
+      return result;
+    } catch (error) {
+      await this.connection.rollback();
+      throw error;
+    }
+  }
+
+  escape(value) {
+    return mysql.escape(value);
+  }
+}
+
+module.exports = { MySQLAdapter };

package/lib/adapters/postgres-adapter.js

@@ -0,0 +1,70 @@
+const { BaseAdapter } = require('./base-adapter');
+const { Pool } = require('pg');
+
+class PostgresAdapter extends BaseAdapter {
+  async connect() {
+    this.connection = new Pool({
+      host: this.config.host || 'localhost',
+      port: this.config.port || 5432,
+      user: this.config.user,
+      password: this.config.password,
+      database: this.config.database
+    });
+    return this.connection;
+  }
+
+  async disconnect() {
+    if (this.connection) {
+      await this.connection.end();
+      this.connection = null;
+    }
+  }
+
+  async query(sql, params = []) {
+    if (!this.connection) await this.connect();
+    
+    try {
+      const result = await this.connection.query(sql, params);
+      return { data: result.rows, rowCount: result.rowCount };
+    } catch (error) {
+      throw new Error(`Postgres query error: ${error.message}`);
+    }
+  }
+
+  async execute(sql, params = []) {
+    if (!this.connection) await this.connect();
+    
+    try {
+      const result = await this.connection.query(sql, params);
+      return { 
+        rowCount: result.rowCount,
+        lastInsertId: result.rows[0]?.id 
+      };
+    } catch (error) {
+      throw new Error(`Postgres execute error: ${error.message}`);
+    }
+  }
+
+  async transaction(callback) {
+    const client = await this.connection.connect();
+    try {
+      await client.query('BEGIN');
+      const result = await callback(this);
+      await client.query('COMMIT');
+      return result;
+    } catch (error) {
+      await client.query('ROLLBACK');
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+
+  escape(value) {
+    if (value === null) return 'NULL';
+    if (typeof value === 'number') return value.toString();
+    return `'${value.toString().replace(/'/g, "''")}'`;
+  }
+}
+
+module.exports = { PostgresAdapter };

package/lib/adapters/sqlite-adapter.js

@@ -0,0 +1,56 @@
+const { BaseAdapter } = require('./base-adapter');
+const Database = require('better-sqlite3');
+
+class SQLiteAdapter extends BaseAdapter {
+  async connect() {
+    this.connection = new Database(this.config.database || ':memory:');
+    return this.connection;
+  }
+
+  async disconnect() {
+    if (this.connection) {
+      this.connection.close();
+      this.connection = null;
+    }
+  }
+
+  async query(sql, params = []) {
+    if (!this.connection) await this.connect();
+    
+    try {
+      const stmt = this.connection.prepare(sql);
+      const rows = stmt.all(...params);
+      return { data: rows, rowCount: rows.length };
+    } catch (error) {
+      throw new Error(`SQLite query error: ${error.message}`);
+    }
+  }
+
+  async execute(sql, params = []) {
+    if (!this.connection) await this.connect();
+    
+    try {
+      const stmt = this.connection.prepare(sql);
+      const result = stmt.run(...params);
+      return { 
+        rowCount: result.changes,
+        lastInsertId: result.lastInsertRowid 
+      };
+    } catch (error) {
+      throw new Error(`SQLite execute error: ${error.message}`);
+    }
+  }
+
+  async transaction(callback) {
+    const transaction = this.connection.transaction(callback);
+    return transaction();
+  }
+
+  escape(value) {
+    if (value === null) return 'NULL';
+    if (typeof value === 'number') return value.toString();
+    return `'${value.toString().replace(/'/g, "''")}'`;
+  }
+}
+
+module.exports = { SQLiteAdapter };